From 270483405021e237f54ffe6d02eecf11744fd1aa Mon Sep 17 00:00:00 2001 From: Rob Landley Date: Sun, 18 Aug 2013 14:24:59 -0500 Subject: Document the toybox entry path from main() into a command. --- www/code.html | 52 +++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 49 insertions(+), 3 deletions(-) (limited to 'www/code.html') diff --git a/www/code.html b/www/code.html index 75483564..ca9d1649 100755 --- a/www/code.html +++ b/www/code.html @@ -1,6 +1,6 @@ -

Code style

+

Code style

The primary goal of toybox is _simple_ code. Keeping the code small is second, with speed and lots of features coming in somewhere after that. @@ -23,7 +23,7 @@ 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.

-

Building Toybox:

+

Building Toybox

Toybox is configured using the Kconfig language pioneered by the Linux kernel, and adopted by many other projects (uClibc, OpenEmbedded, etc). @@ -55,7 +55,53 @@ to the environment will take precedence.

(To clarify: "configure" describes the build and installation environment, ".config" lists the features selected by defconfig/menuconfig.)

-

Infrastructure:

+

Running a command

+ +

main

+ +

The toybox main() function is at the end of main.c at the top level. It has +two possible codepaths, only one of which is configured into any given build +of toybox.

+ +

If CONFIG_SINGLE is selected, toybox is configured to contain only a single +command, so most of the normal setup can be skipped. In this case the +multiplexer isn't used, instead main() calls toy_singleinit() (also in main.c) +to set up global state and parse command line arguments, calls the command's +main function out of toy_list (in the CONFIG_SINGLE case the array has a single entry, no need to search), and if the function returns instead of exiting +it flushes stdout (detecting error) and returns toys.exitval.

+ +

When CONFIG_SINGLE is not selected, main() uses basename() to find the +name it was run as, shifts its argument list one to the right so it lines up +with where the multiplexer function expects it, and calls toybox_main(). This +leverages the multiplexer command's infrastructure to find and run the +appropriate command. (A command name starting with "toybox" will +recursively call toybox_main(); you can go "./toybox toybox toybox toybox ls" +if you want to...)

+ +

toybox_main

+ +

The toybox_main() function is also in main,c. It handles a possible +--help option ("toybox --help ls"), prints the list of available commands if no +arguments were provided to the multiplexer (or with full path names if any +other option is provided before a command name, ala "toybox --list"). +Otherwise it calls toy_exec() on its argument list.

+ +

Note that the multiplexer is the first entry in toy_list (the rest of the +list is sorted alphabetically to allow binary search), so toybox_main can +cheat and just grab the first entry to quickly set up its context without +searching. Since all command names go through the multiplexer at least once +in the non-TOYBOX_SINGLE case, this avoids a redundant search of +the list.

+ +

The toy_exec() function is also in main.c. It performs toy_find() to +perform a binary search on the toy_list array to look up the command's +entry by name and saves it in the global variable which, calls toy_init() +to parse command line arguments and set up global state (using which->options), +and calls the appropriate command's main() function (which->toy_main). On +return it flushes all pending ansi FILE * I/O, detects if stdout had an +error, and then calls xexit() (which uses toys.exitval).

+ +

Infrastructure

The toybox source code is in following directories: