X-Git-Url: http://git.osdn.net/view?a=blobdiff_plain;f=README;h=eebe7b7d1f3cb0f8658b3c953794f1e414b8ef04;hb=a379d5ee15365709e2f68d3a82da4f33d08e9578;hp=4fc2472c336b58eddd4c33d7e91aa7d811db7b9a;hpb=0b87b2e71324a20bdb7839ac95742d6208d5c321;p=android-x86%2Fexternal-toybox.git diff --git a/README b/README index 4fc2472c..eebe7b7d 100644 --- a/README +++ b/README @@ -10,7 +10,7 @@ The special name "." indicates the current directory (just like ".." means the parent directory), and you can run a program that isn't in the $PATH by specifying a path to it, so this should work: - wget http://landley.net/bin/toybox-x86_64 + wget http://landley.net/toybox/bin/toybox-x86_64 chmod +x toybox-x86_64 ./toybox-x86_64 echo hello world @@ -18,13 +18,23 @@ specifying a path to it, so this should work: Type "make help" for build instructions. -Usually you want something like: +Toybox uses the "make menuconfig; make; make install" idiom same as +the Linux kernel. Usually you want something like: make defconfig - CFLAGS="--static" CROSS_COMPILE=armv5l- make toybox - PREFIX=/path/to/root/filesystem make install + make + make install -The CROSS_COMPILE argument is optional, and without it builds a version of +Or maybe: + + LDFLAGS="--static" CROSS_COMPILE=armv5l- make defconfig toybox + PREFIX=/path/to/root/filesystem/bin make install_flat + +The file "configure" defines default values for many environment +variables that control the toybox build; if you set a value for any of +these, your value is used instead of the default in that file. + +The CROSS_COMPILE argument above is optional, the default builds a version of toybox to run on the current machine. Cross compiling requires an appropriately prefixed cross compiler toolchain, several example toolchains are available at: @@ -40,6 +50,9 @@ For more about cross compiling, see: http://landley.net/writing/docs/cross-compiling.html http://landley.net/aboriginal/architectures.html +For a more thorough description of the toybox build process, see +http://landley.net/toybox/code.html#building + --- Using toybox The toybox build produces a multicall binary, a "swiss-army-knife" program @@ -57,7 +70,9 @@ The "help" command provides information about each command (ala "help cat"). It works like the Linux kernel: allnoconfig, defconfig, and menuconfig edit a ".config" file that selects which features to include in the resulting -binary. +binary. You can save and re-use your .config file, although may want to +run "make oldconfig" to re-run the dependency resolver when migrating to +new versions. The maximum sane configuration is "make defconfig": allyesconfig isn't recommended for toybox because it enables unfinished commands and debug code. @@ -66,26 +81,89 @@ recommended for toybox because it enables unfinished commands and debug code. Toybox is not a complete operating system, it's a program that runs under an operating system. Booting a simple system to a shell prompt requires -three packages: an operating system kernel (Linux) to drive the hardware, -a program for the system to run (toybox), and a C library to tie them -together (toybox has been tested with musl, uClibc, and glibc, on Android -systems musl is recommended).

+three packages: an operating system kernel (Linux*) to drive the hardware, +one or more programs for the system to run (toybox), and a C library ("libc") +to tie them together (toybox has been tested with musl, uClibc, glibc, +and bionic). -

The C library is part of a "toolchain", which is an integrated suite +The C library is part of a "toolchain", which is an integrated suite of compiler, assembler, and linker, plus the standard headers and libraries -necessary to build C programs.

+necessary to build C programs. (And miscellaneous binaries like nm and objdump.) +Static linking (with the --static option) copies the shared library contents +into the program, resulting in larger but more portable programs, which +can run even if they're the only file in the filesystem. Otherwise, +the "dynamically" linked programs require the library files to be present on +the target system ("man ldd" and "man ld.so" for details). - Static linking (with the --static option) -copies the shared library contents into the program, resulting in -larger but more portable programs. Dynamically linked programs (the default) -Otherwise, the -"dynamically" linked programs require the -library to be present on the target system ("man ldd" and "man ld.so" for -details) statically linked programs do not.

+An example toybox-based system is Aboriginal Linux: -Toybox is not a kernel, it needs Linux to drive the hardware. + http://landley.net/aboriginal/about.html -An example toybox-based system is Aboriginal Linux: +That's designed to run under qemu, emulating several different hardware +architectures (x86, x86-64, arm, mips, sparc, powerpc, sh4). Each toybox +release is regression tested by building Linux From Scratch under this +toybox-based system on each supported architecture, using QEMU to emulate +big and little endian systems with different word size and alignment +requirements. (The eventual goal is to replace Linux From Scratch with +the Android Open Source Project.) + +* Or something providing the same API such as FreeBSD's Linux emulation layer. + +--- Presentations + +1) "Why Toybox?" talk at the Embedded Linux Conference in 2013 + + video: http://youtu.be/SGmtP5Lg_t0 + outline: http://landley.net/talks/celf-2013.txt + linked from http://landley.net/toybox/ in nav bar on left as "Why is it?" + - march 21, 2013 entry has section links. + +2) "Why Public Domain?" The rise and fall of copyleft, Ohio LinuxFest 2013 + + audio: https://archive.org/download/OhioLinuxfest2013/24-Rob_Landley-The_Rise_and_Fall_of_Copyleft.mp3 + outline: http://landley.net/talks/ohio-2013.txt + +3) Why did I do Aboriginal Linux (which led me here) + + 260 slide presentation: + https://speakerdeck.com/landley/developing-for-non-x86-targets-using-qemu + + How and why to make android self-hosting: + http://landley.net/aboriginal/about.html#selfhost + +4) What's new with toybox (ELC 2015 status update): + + video: http://elinux.org/ELC_2015_Presentations + outline: http://landley.net/talks/celf-2015.txt + +--- Contributing + +The three important URLs for communicating with the toybox project are: + + web page: http://landley.net/toybox + + mailing list: http://lists.landley.net/listinfo.cgi/toybox-landley.net + + git repo: http://github.com/landley/toybox + +The maintainer prefers patches be sent to the mailing list. If you use git, +the easy thing to do is: + + git format-patch -1 $HASH + +Then send a file attachment. The list holds messages from non-subscribers +for moderation, but I usually get to them in a day or two. + +Although I do accept pull requests on github, I download the patches and +apply them with "git am" (which avoids gratuitous merge commits). Closing +the pull request is then the submitter's responsibility. + +If I haven't responded to your patch after one week, feel free to remind +me of it. - http://landley.net/aboriginal +Android's policy for toybox patches is that non-build patches should go +upstream first (into vanilla toybox, with discussion on the toybox mailing +list) and then be pulled into android's toybox repo from there. (They +generally resync on fridays). The exception is patches to their build scripts +(Android.mk and the checked-in generated/* files) which go directly to AOSP.