From 5ffa45661c50be1e6d384156be9b83fbed1356b3 Mon Sep 17 00:00:00 2001 From: Rob Landley Date: Mon, 24 Apr 2017 19:01:33 -0500 Subject: Another FAQ, and some related tweaks as long as I was there. --- www/faq.html | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 80 insertions(+), 6 deletions(-) (limited to 'www/faq.html') diff --git a/www/faq.html b/www/faq.html index 6cc7cdb8..c5709eff 100755 --- a/www/faq.html +++ b/www/faq.html @@ -5,6 +5,7 @@

  • Do you capitalize toybox?

  • Why toybox? (What was wrong with busybox?)

  • Why a 7 year support horizon?

    • +

  • Where do I start understanding the toybox source code?

    • @@ -80,18 +81,19 @@ law below the high end systems, and that another 2-3 iterations should cover the useful lifetime of most systems no longer being sold but still in use and potentially being upgraded to new software releases.

    -

    It turns out I missed industry changes in the 1990's that stretched the gap -from low end to high end from 2 cycles to 4 cycles (here's my writeup on that; and _that_ analysis +

    It turns out I missed +industry changes in the 1990's that stretched the gap +from low end to high end from 2 cycles to 4 cycles, and _that_ analysis ignored the switch from PC to smartphone cutting off the R&D air supply of the laptop market. Meanwhile the Moore's Law s-curve started bending -down in 2000 and these days is pretty flat: the drive for faster clock speeds -stumbled -then died, +down in 2000 and these days is pretty flat because the drive for faster clock +speeds stumbled +then died, and the subsequent drive to go wide maxed out around 4x SMP with ~2 megabyte caches for most applications. These days the switch from exponential to linear growth in hardware capabilities is common -knowledge.)

    +knowledge.

    But the 7 year rule of thumb stuck around anyway: if a kernel or libc feature is less than 7 years old, I try to have a build-time configure test @@ -99,4 +101,76 @@ for it and let the functionality cleanly drop out. I also keep old Ubuntu images around in VMs and perform the occasional defconfig build there to see what breaks.

    +

    Where do I start understanding the source code?

    + +

    Toybox is written in C. There are longer writeups of the +design ideas and a code walkthrough, +and the about page summarizes what we're trying to +accomplish, but here's a quick start:

    + +

    Toybox uses the standard three stage configure/make/install +build, in this case "make defconfig; +make; make install". Type "make help" to +see available make targets.

    + +

    The configure stage is copied from the Linux kernel (in the "kconfig" +directory), and saves your selections in the file ".config" at the top +level. The "defconfig" target selects the +maximum sane configuration (enabling all the commands and features that +aren't unfinished, only intended as examples, debug code, etc) and is +probably what you want. You can use "make menuconfig" to manually select +specific commands to include, through an interactive menu (cursor up and +down, enter to descend into a sub-menu, space to select an entry, ? to see +an entry's help text, esc to exit). The menuconfig help text is the +same as the command's --help output.

    + +

    The "make" stage creates a toybox binary (which is stripped, look in +generated/unstripped for the debug versions), and "install" adds a bunch of +symlinks to toybox under the various command names. Toybox determines which +command to run based on the filename, or you can use the "toybox" name in which case the first +argument is the command to run (ala "toybox ls -l"). You can also build +individual commands as standalone executables, ala "make sed cat ls".

    + +

    The main() function is in main.c at the top level, +along with setup plumbing and selecting which command to run this time. +The function toybox_main() implements the "toybox" multiplexer command.

    + +

    The individual command implementations are under "toys", and are grouped +into categories (mostly based on which standard they come from, posix, lsb, +android...) The "pending" directory contains unfinished commands, and the +"examples" directory contains examples. Commands in those two directories +are _not_ selected by defconfig. (These days pending directory is mostly +third party submissions that have not yet undergone proper code review.)

    + +

    Common infrastructure shared between commands is under "lib". Most +commands call lib/args.c to parse their command line arguments before calling +the command's own main() function, which uses the option string in +the command's NEWTOY() macro. This is similar to the libc function getopt(), +but more powerful, and is documented at the top of lib/args.c.

    + +

    Most of the actual build/install infrastructure is shell scripts under +"scripts". These populate the "generated" directory with headers +created from other files, which are described +in the code walkthrough. All the +build's temporary files live under generated, including the .o files built +from the .c files (in generated/obj). The "make clean" target deletes that +directory. ("make distclean" also deletes your .config and deletes the +kconfig binaries that process .config.)

    + +

    Each command's file contains all the information for that command, so +adding a command to toybox means adding a single file under "toys". +Usually you start a new command by copying an +existing command file to a new filename +(toys/examples/hello.c, toys/examples/skeleton.c, toys/posix/cat.c, +and toys/posix/true.c have all been used for this purpose) and then replacing +all instances of its old name with the new name (which should match the +new filename), and modifying the help text, argument string, and what the +code does. You might have to "make distclean" before you new command +shows up in defconfig or menuconfig.

    + +

    The toybox test suite lives in the "tests" directory. From the top +level you can "make tests" to test everything, or "make test_sed" test a +single command's standalone version (which should behave identically) +but that's why we test.

    + -- cgit v1.2.3