From 6882ee89dc5da4081d5721706ad77a3e0396b1bc Mon Sep 17 00:00:00 2001 From: Rob Landley Date: Tue, 12 Feb 2008 18:41:34 -0600 Subject: Partial update. Needs more work. --- www/code.html | 162 ++++++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 117 insertions(+), 45 deletions(-) (limited to 'www/code.html') diff --git a/www/code.html b/www/code.html index 06c777d9..531539de 100644 --- a/www/code.html +++ b/www/code.html @@ -15,6 +15,12 @@ at the end of the function. Goto labels are never indented: they override the block structure of the file. Putting them at the left edge makes them easy to spot as overrides to the normal flow of control, which they are.

+

The primary goal of toybox is _simple_ code. Small is second, +speed and lots of features come in somewhere after that. Note that +environmental dependencies are a type of complexity, so needing other packages +to build or run is a downside. For example, don't use curses when you can +output ansi escape sequences instead.

+

Infrastructure:

The toybox source code is in following directories:

@@ -37,17 +43,19 @@ files generated from other parts of the source code.

Adding a new command

To add a new command to toybox, add a C file implementing that command to the toys directory. No other files need to be modified; the build extracts -other information it needs (such as command line arguments) from specially +all the information it needs (such as command line arguments) from specially formatted comments and macros in the C file. (See the description of the generated directory for details.)

An easy way to start a new command is copy the file "hello.c" to the name of the new command, and modify this copy to implement the new command. -This file is a small, simple command meant to be used as a "skeleton" for +This file is an example command meant to be used as a "skeleton" for new commands (more or less by turning every instance of "hello" into the name of your command, updating the command line arguments, globals, and help data, and then filling out its "main" function with code that does -something interesting).

+something interesting). It provides examples of all the build infrastructure +(including optional elements like command line argument parsing and global +variables that a "hello world" program doesn't strictly need).

Here's a checklist of steps to turn hello.c into another command:

@@ -69,10 +77,11 @@ command line utility standards on the Open Group's website, where there's often a relevant commandname.html file. Feel free to link to other documentation or standards as appropriate.

-

  • Update the USE_YOURCOMMAND(NEWTOY(yourcommand,NULL,0)) line. This -specifies the name used to run your command, the command line arguments (NULL -if none), and where your command should be installed on a running system. See -[TODO] for details.

    • +

  • Update the USE_YOURCOMMAND(NEWTOY(yourcommand,"blah",0)) line. The +arguments to newtoy are: 1) the name used to run your command, 2) +the command line arguments (NULL if none), and additional information such +as where your command should be installed on a running system. See [TODO] for +details.

  • Change the kconfig data (from "config YOURCOMMAND" to the end of the comment block) to supply your command's configuration and help @@ -91,13 +100,14 @@ variables will be initialized by the automatic argument parsing logic, and the type and order of these variables must correspond to the arguments specified in NEWTOY(). See [TODO] for details.

    • -

  • Change the "#define TT this.hello" line to use your command name in -place of the "hello". This is a shortcut to access your global variables -as if they were members of the global struct "TT". (Access these members with -a period ".", not a right arrow "->".)

    • +

  • If you didn't delete the DEFINE_GLOBALS macro, change the "#define TT +this.hello" line to use your command name in place of the "hello". This is a +shortcut to access your global variables as if they were members of the global +struct "TT". (Access these members with a period ".", not a right arrow +"->".)

  • Rename hello_main() to yourcommand_main(). This is the main() function -where execution off your command starts. See [TODO] to figure out what +where execution of your command starts. See [TODO] to figure out what happened to your command line arguments and how to access them.

    • @@ -108,16 +118,17 @@ happened to your command line arguments and how to access them.

    main.c

    Contains the main() function where execution starts, plus common infrastructure to initialize global variables and select which command -to run. The "toybox" multiplexer command is also defined here. (This is the +to run. The "toybox" multiplexer command also lives here. (This is the only command defined outside of the toys directory.)

    -

    Execution starts in main() which removes the path from the first command -name and calls toybox_main(), which calls toy_exec(), which calls toy_find(), -toy_init() and the appropriate command's function from toy_list. If -the command is "toybox", execution returns to toybox_main(), otherwise -the call goes to the appropriate command_main() from the toys directory.

    +

    Execution starts in main() which trims any path off of the first command +name and calls toybox_main(), which calls toy_exec(), which calls toy_find() +and toy_init() before calling the appropriate command's function from toy_list. +If the command is "toybox", execution recurses into toybox_main(), otherwise +the call goes to the appropriate commandname_main() from a C file in the toys +directory.

    -

    The following global variables are defined here:

    +

    The following global variables are defined in main.c:

  • struct toy_context toys - global structure containing information @@ -164,21 +185,52 @@ and the fields in the toy union initialized by get_optflags().

  • unsigned optflags - Command line option flags, set by get_optflags(). Indicates which of the command line options listed in -toys->which.options were seen this time. See get_optflags() for -details.

    • +toys->which.options occurred this time.

    + +

    The rightmost command line argument listed in toys->which.options sets bit +1, the next one sets bit 2, and so on. This means the bits are set in the same +order the binary digits would be listed if typed out as a string. For example, +the option string "abcd" would parse the command line "-c" to set optflags to 2, +"-a" would set optflags to 8, and "-bd" would set optflags to 6 (4|2).

    + +

    Only letters are relevant to optflags. In the string "a*b:c#d", d=1, c=2, +b=4, a=8. The punctuation after a letter initializes global variables +(see [TODO] DECLARE_GLOBALS() for details).

    + +

    For more information on option parsing, see [TODO] get_optflags().

    + +

  • char **optargs - Null terminated array of arguments left over after get_optflags() removed all the ones it understood. Note: optarg[0] is the first argument, not the command name. Use toys.which->name for the command name.

    • +

  • int optc - Optarg count, equivalent to argc but for +optargs[].

  • int exithelp - Whether error_exit() should print a usage message via help_main() before exiting. (True during option parsing, defaults to false afterwards.)


    • -

  • union toy_union toy - Union of structures containing each +

  • union toy_union this - Union of structures containing each command's global variables.

    -

    A command that needs global variables should declare a structure to +

    Global variables are useful: they reduce the overhead of passing extra +command line arguments between functions, they conveniently start prezeroed to +save initialization costs, and the command line argument parsing infrastructure +can also initialize global variables with its results.

    + +

    But since each toybox process can only run one command at a time, allocating +space for global variables belonging to other commands you aren't currently +running would be wasteful.

    + +

    Toybox handles this by encapsulating each command's global variables in +a structure, and declaring a union of those structures. The DECLARE_GLOBALS() +macro contains the global variables that should go in a command's global +structure. Each variable can then be accessed as "this.commandname.varname". +Generally, the macro TT is #defined to this.commandname so the variable +can then be accessed as "TT.variable".

    + +A command that needs global variables should declare a structure to contain them all, and add that structure to this union. A command should never declare global variables outside of this, because such global variables would allocate memory when running other commands that don't use those global @@ -195,48 +247,68 @@ and it should never be directly referenced by functions in lib/ (although commands are free to pass toybuf in to a library function as an argument).
    • -

    The following functions are defined here:

    +

    The following functions are defined in main.c:

    Config.in

    Top level configuration file in a stylized variant of -kconfig format. Includes toys/Config.in.

    +kconfig format. Includes generated/Config.in.

    These files are directly used by "make menuconfig" to select which commands to build into toybox (thus generating a .config file), and by -scripts/config2help.py to generate toys/help.h.

    +scripts/config2help.py to create generated/help.h.

    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).

    -

  • gen_config.h - list of CFG_SYMBOL and USE_SYMBOL() macros, +