From 23ef31e6e9a2b625fd27a1dd54b23ae097d03efc Mon Sep 17 00:00:00 2001 From: Rob Landley Date: Wed, 6 May 2020 12:36:08 -0500 Subject: Minor doc tweaks. --- toys/example/hello.c | 1 + toys/example/skeleton.c | 1 + www/code.html | 26 +++++++++++++++----------- 3 files changed, 17 insertions(+), 11 deletions(-) diff --git a/toys/example/hello.c b/toys/example/hello.c index 4cd5d13a..3e68f215 100644 --- a/toys/example/hello.c +++ b/toys/example/hello.c @@ -5,6 +5,7 @@ * See http://pubs.opengroup.org/onlinepubs/9699919799/utilities/ * See http://refspecs.linuxfoundation.org/LSB_4.1.0/LSB-Core-generic/LSB-Core-generic/cmdbehav.html * See https://www.ietf.org/rfc/rfc3.txt + * See http://man7.org/linux/man-pages/dir_section_1.html USE_HELLO(NEWTOY(hello, 0, TOYFLAG_USR|TOYFLAG_BIN)) diff --git a/toys/example/skeleton.c b/toys/example/skeleton.c index 1796ba1b..a22bc90f 100644 --- a/toys/example/skeleton.c +++ b/toys/example/skeleton.c @@ -6,6 +6,7 @@ * See http://pubs.opengroup.org/onlinepubs/9699919799/utilities/ * See http://refspecs.linuxfoundation.org/LSB_4.1.0/LSB-Core-generic/LSB-Core-generic/cmdbehav.html * See https://www.ietf.org/rfc/rfc3.txt + * See http://man7.org/linux/man-pages/dir_section_1.html // Accept many different kinds of command line argument (see top of lib/args.c) // Demonstrate two commands in the same file (see www/documentation.html) diff --git a/www/code.html b/www/code.html index 953c53bb..25a18193 100644 --- a/www/code.html +++ b/www/code.html @@ -20,8 +20,9 @@ want the code to be consistent.

Building Toybox

-

Toybox is configured using the Kconfig language pioneered by the Linux -kernel, and adopted by many other projects (uClibc, OpenEmbedded, etc). +

Toybox is configured using the +Kconfig language pioneered by the Linux +kernel, and adopted by many other projects (buildroot, OpenEmbedded, etc). This generates a ".config" file containing the selected options, which controls which features are included when compiling toybox.

@@ -189,8 +190,8 @@ toys/posix/cat.c only gets included if you have "CAT=y" in ".config".

year.

  • Give a URL to the relevant standards document, where applicable. -(Sample links to SUSv4 and LSB are provided, feel free to link to other -documentation or standards as appropriate.)

    • +(Sample links to SUSv4, LSB, IETF RFC, and man7.org are provided, feel free to +link to other documentation or standards as appropriate.)

  • Update the USE_YOURCOMMAND(NEWTOY(yourcommand,"blah",0)) line. The NEWTOY macro fills out this command's toy_list @@ -263,11 +264,13 @@ back off.

    • Headers.

    -

    Commands generally don't have their own headers. If it's common code -it can live in lib/, if it isn't put it in the command's .c file. (The line -between implementing multiple commands in a C file via OLDTOY() to share -infrastructure and moving that shared infrastructure to lib/ is a judgement -call. Try to figure out which is simplest.)

    +

    Commands are implemented as self-contained .c files, and generally don't +have their own .h files. If it's common code put it in lib/, and if it's +something like a local structure definition just put it in the command's .c +file. If it would only ever be #included from one place, inline it. +(The line between implementing multiple commands in a C file via OLDTOY() +to share infrastructure and moving that shared infrastructure to lib/ is a +judgement call. Try to figure out which is simplest.)

    The top level toys.h should #include all the standard (posix) headers that any command uses. (Partly this is friendly to ccache and partly this @@ -281,7 +284,7 @@ or operating systems) should be confined to lib/portability.h and lib/portability.c. (There's even some minimal compile-time environment probing that writes data to generated/portability.h, see scripts/genconfig.sh.)

    -

    Only include linux/*.h headers from individual commands (not from other +

    Only include <linux/*.h> headers from individual commands (not from other headers), and only if you really need to. Data that varies per architecture is a good reason to include a header. If you just need a couple constants that haven't changed since the 1990's, it's ok to #define them yourself or @@ -1370,7 +1373,8 @@ Makefile.

    Directory kconfig/

    -

    Menuconfig infrastructure copied from the Linux kernel. See the +

    Menuconfig infrastructure copied from the Linux kernel a long time ago +(version 2.6.16). See the Linux kernel's Documentation/kbuild/kconfig-language.txt