From 7eaf4f535da215cd7061d60fb691df2ba09fff8a Mon Sep 17 00:00:00 2001 From: Rob Landley Date: Wed, 9 Apr 2014 08:30:09 -0500 Subject: Document some of the new temporary files in generated/, add anchor tags. --- www/code.html | 183 ++++++++++++++++++++++++++++++++++------------------------ 1 file changed, 107 insertions(+), 76 deletions(-) (limited to 'www/code.html') diff --git a/www/code.html b/www/code.html index 64ee98f5..a5ffa155 100755 --- a/www/code.html +++ b/www/code.html @@ -129,7 +129,7 @@ files generated from other parts of the source code. -

Adding a new command

+

Adding a new command

To add a new command to toybox, add a C file implementing that command under the toys directory. No other files need to be modified; the build extracts all the information it needs (such as command line arguments) from specially @@ -225,7 +225,7 @@ as appropriate by the time this function is called. (See get_optflags() for details.

-

Headers.

+

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 @@ -252,7 +252,7 @@ that haven't changed since the 1990's, it's ok to #define them yourself or just use the constant inline with a comment explaining what it is. (A #define that's only used once isn't really helping.)

-

Top level directory.

+

Top level directory.

This directory contains global infrastructure.

@@ -460,13 +460,14 @@ install path prepended.

to build into toybox (thus generating a .config file), and by scripts/config2help.py to create generated/help.h.

-

Temporary files:

+ +

Temporary files:

There is one temporary file in the top level source directory:

- -

The "generated/" directory contains files generated from other source code -in toybox. All of these files can be recreated by the build system, although -some (such as generated/help.h) are shipped in release versions to reduce -environmental dependencies (I.E. so you don't need python on your build -system).

+

Directory generated/

+ +

The remaining temporary files live in the "generated/" directory, +which is for files generated at build time from other source files.

 - -

Directory toys/

- -

toys/Config.in

- -

Included from the top level Config.in, contains one or more -configuration entries for each command.

- -

Each command has a configuration entry matching the command name (although -configuration symbols are uppercase and command names are lower case). -Options to commands start with the command name followed by an underscore and -the option name. Global options are attached to the "toybox" command, -and thus use the prefix "TOYBOX_". This organization is used by -scripts/cfg2files to select which toys/*.c files to compile for a given -.config.

-

A command with multiple names (or multiple similar commands implemented in -the same .c file) should have config symbols prefixed with the name of their -C file. I.E. config symbol prefixes are NEWTOY() names. If OLDTOY() names -have config symbols they're options (symbols with an underscore and suffix) -to the NEWTOY() name. (See toys/toylist.h)

- -

toys/toylist.h

-

The first half of this file prototypes all the structures to hold -global variables for each command, and puts them in toy_union. These -prototypes are only included if the macro NEWTOY isn't defined (in which -case NEWTOY is defined to a default value that produces function -prototypes).

- -

The second half of this file lists all the commands in alphabetical -order, along with their command line arguments and install location. -Each command has an appropriate configuration guard so only the commands that -are enabled wind up in the list.

- -

The first time this header is #included, it defines structures and -produces function prototypes for the commands in the toys directory.

+

  • generated/flags.h - FLAG_? macros indicating which command +line options were seen. The option parsing in lib/args.c sets bits in +toys.optflags, which can be tested by anding with the appropriate FLAG_ +macro. (Bare longopts, which have no corresponding short option, will +have the longopt name after FLAG_. All others use the single letter short +option.)

    + +

    To get the appropriate macros for your command, #define FOR_commandname +before #including toys.h. To switch macro sets (because you have an OLDTOY() +with different options in the same .c file), #define CLEANUP_oldcommand +and also #define FOR_newcommand, then #include "generated/flags.h" to switch. +

    +
    • +

  • generated/globals.h - +Declares structures to hold the contents of each command's GLOBALS(), +and combines them into "global_union this". (Yes, the name was +chosen to piss off C++ developers who think that C +is merely a subset of C++, not a language in its own right.)

    -

    The first time it's included, it defines structures and produces function -prototypes. - This -is used to initialize toy_list in main.c, and later in that file to initialize -NEED_OPTIONS (to figure out whether the command like parsing logic is needed), -and to put the help entries in the right order in toys/help.c.

    +

    The union reuses the same memory for each command's global struct: +since only one command's globals are in use at any given time, collapsing +them together saves space. The headers #define TT to the appropriate +"this.commandname", so you can refer to the current command's global +variables out of "this" as TT.variablename.

    -

    toys/help.h

    +

    The globals start zeroed, and the first few are filled out by the +lib/args.c argument parsing code called from main.c.

    +
    • -

    #defines two help text strings for each command: a single line +

  • toys/help.h - +#defines two help text strings for each command: a single line command_help and an additinal command_help_long. This is used by help_main() in toys/help.c to display help for commands.

    -

    Although this file is generated from Config.in help entries by -scripts/config2help.py, it's shipped in release tarballs so you don't need -python on the build system. (If you check code out of source control, or -modify Config.in, then you'll need python installed to rebuild it.)

    +

    This file is created by scripts/make.sh, which compiles scripts/config2help.c +into the binary generated/config2help, and then runs it against the top +level .config and Config.in files to extract the help text from each config +entry and collate together dependent options.

    + +

    This file contains help text for all commands, regardless of current +configuration, but only the ones currently enabled in the .config file +wind up in the help_data[] array, and only the enabled dependent options +have their help text added to the command they depend on.

    +
    • -

    This file contains help for all commands, regardless of current -configuration, but only the currently enabled ones are entered into help_data[] -in toys/help.c.

    +

  • generated/newtoys.h - +All the NEWTOY() and OLDTOY() macros in alphabetical order, +each of which should be inside the appropriate USE_ macro. (Ok, not _quite_ +alphabetical orer: the "toybox" multiplexer is always the first entry.)

    + +

    By #definining NEWTOY() to various things before #including this file, +it may be used to create function prototypes (in toys.h), initialize the +toy_list array (in main.c, the alphabetical order lets toy_find() do a +binary search), initialize the help_data array (in lib/help.c), and so on. +(It's even used to initialize the NEED_OPTIONS macro, which is has a 1 or 0 +for each command using command line option parsing, ORed together. +This allows compile-time dead code elimination to remove the whole of +lib/args.c if nothing currently enabled is using it.)

    + +

    Each NEWTOY and OLDTOY macro contains the command name, command line +option string (telling lib/args.c how to parse command line options for +this command), recommended install location, and miscelaneous data such +as whether this command should retain root permissions if installed suid.

    +
    • + +

  • toys/oldtoys.h - Macros with the command line option parsing +string for each NEWTOY. This allows an OLDTOY that's just an alias for an +existing command to refer to the existing option string instead of +having to repeat it.

    +
    • +

    Directory lib/

    @@ -648,14 +677,16 @@ struct double_list *new) - append existing struct double_list to list, does not allocate anything.

    -Trivia questions: +List code trivia questions: