From 6924b38801594d45396ec9676652fe379e39994d Mon Sep 17 00:00:00 2001 From: Rob Landley Date: Wed, 13 May 2020 05:06:45 -0500 Subject: FAQ polishing. --- www/faq.html | 44 ++++++++++++++++++++++++-------------------- 1 file changed, 24 insertions(+), 20 deletions(-) (limited to 'www') diff --git a/www/faq.html b/www/faq.html index ec62dd57..23f5d818 100755 --- a/www/faq.html +++ b/www/faq.html @@ -77,12 +77,6 @@ hardware and distributions released up to 7 years ago, and feel ok dropping support for stuff older than that. (This is a little longer than Ubuntu's Long Term Support, but not by much.)

-

If a kernel or libc feature is less than 7 years old, I try to have a -build-time configure test 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. (I'm not perfect about this, -but I accept bug reports.)

-

My original theory was "4 to 5 18-month cycles of moore's law should cover the vast majority of the installed base of PC hardware", loosely based on some research I did back in 2003 @@ -110,7 +104,7 @@ linear growth in hardware capabilities is feature is less than 7 years old, I try to have a build-time configure test 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.

+see what breaks. (I'm not perfect about this, but I accept bug reports.)

Q: Why time based releases?

A: Toybox targets quarterly releases (a similar schedule to the Linux @@ -183,27 +177,33 @@ 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".

+individual commands as standalone executables, ala "make sed cat ls". +(The "make change" target builds all of them, as in "change for a $20".)

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 function toybox_main() in the same file implements the "toybox" +multiplexer command that lists and selects the other commands.

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

+"examples" directory contains example code that aren't really useful commands. +Commands in those two directories +are _not_ selected by defconfig. (Most of the files in the pending directory +are 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.

+but more powerful, and is documented at the top of lib/args.c. A NULL option +string prevents this code from being called for that command.

Most of the actual build/install infrastructure is shell scripts under -"scripts". These populate the "generated" directory with headers +"scripts" (starting with scripts/make.sh and scripts/install.sh). +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 @@ -211,7 +211,7 @@ 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 +

Each command's .c 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 @@ -219,13 +219,17 @@ existing command file to a new filename 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 +code does. You might have to "make distclean" before your 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.

+

The toybox test suite lives in the "tests" directory, and is +driven by scripts/test.sh and scripts/runtest.sh. From the top +level you can "make tests" to test everything, or "make test_sed" to test a +single command's standalone version (which should behave identically, +but that's why we test). You can set TEST_HOST=1 to test the host versionn +instead of the toybox version (in theory they should work the same), +and VERBOSE=1 to see diffs of the expected and actual output when a +test fails (VERBOSE=fail to stop at the first such failure)

Q: How do you build a working Linux system with toybox?

-- cgit v1.2.3