Looks better on GitHub. Basically the same, but I removed the instructions that take you to the same text as the link in "Why Toybox?". (Because if there was a difference there, those instructions need to be rewritten for clarity anyway!)
Preview posted on the bug. Bug: https://github.com/landley/toybox/issues/128 --- README => README.md | 97 +++++++++++++++++++++++---------------------- 1 file changed, 50 insertions(+), 47 deletions(-) rename README => README.md (66%)
From 168556f0de213999a3f83cbb9d5dee4cb95b1778 Mon Sep 17 00:00:00 2001 From: Elliott Hughes <e...@google.com> Date: Thu, 23 May 2019 12:37:37 -0700 Subject: [PATCH] README: switch to markdown. Looks better on GitHub. Basically the same, but I removed the instructions that take you to the same text as the link in "Why Toybox?". (Because if there was a difference there, those instructions need to be rewritten for clarity anyway!) Preview posted on the bug. Bug: https://github.com/landley/toybox/issues/128 --- README => README.md | 97 +++++++++++++++++++++++---------------------- 1 file changed, 50 insertions(+), 47 deletions(-) rename README => README.md (66%) diff --git a/README b/README.md similarity index 66% rename from README rename to README.md index 4b3dee00..c9277941 100644 --- a/README +++ b/README.md @@ -1,83 +1,87 @@ -Toybox: all-in-one Linux command line. +# Toybox: all-in-one Linux command line. ---- Getting started +## Getting started -You can download static binaries for various targets from: +You can download static binaries for various targets from +http://landley.net/toybox/bin. - http://landley.net/toybox/bin - -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 +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/toybox/bin/toybox-x86_64 - chmod +x toybox-x86_64 - ./toybox-x86_64 echo hello world +``` +wget http://landley.net/toybox/bin/toybox-x86_64 +chmod +x toybox-x86_64 +./toybox-x86_64 echo hello world +``` ---- Building toybox +## Building toybox -Type "make help" for build instructions. +Type `make help` for build instructions. -Toybox uses the "make menuconfig; make; make install" idiom same as +Toybox uses the `make menuconfig; make; make install` idiom same as the Linux kernel. Usually you want something like: +``` make defconfig make make install +``` 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 +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 +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: - - http://landley.net/aboriginal/bin +prefixed cross compiler toolchain, several example toolchains are available at +http://landley.net/aboriginal/bin. -For the "CROSS_COMPILE=armv5l-" example above, download -cross-compiler-armv5l.tar.bz2, extract it, and add its "bin" subdirectory to -your $PATH. (And yes, the trailing - is significant, because the prefix +For the `CROSS_COMPILE=armv5l-` example above, download +`cross-compiler-armv5l.tar.bz2`, extract it, and add its `bin` subdirectory to +your `$PATH`. (And yes, the trailing `-` is significant, because the prefix includes a dash.) 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 +For a more thorough description of the toybox build process, see: + http://landley.net/toybox/code.html#building ---- Using toybox +## Using toybox The toybox build produces a multicall binary, a "swiss-army-knife" program that acts differently depending on the name it was called by (cp, mv, cat...). -Installing toybox adds symlinks for each command name to the $PATH. +Installing toybox adds symlinks for each command name to the `$PATH`. -The special "toybox" command treats its first argument as the command to run. +The special `toybox` command treats its first argument as the command to run. With no arguments, it lists available commands. This allows you to use toybox without installing it. This is the only command that can have an arbitrary suffix (hence "toybox-armv5l"). -The "help" command provides information about each command (ala "help cat"). +The `help` command provides information about each command (for example +`help cat`). ---- Configuring toybox +## Configuring toybox -It works like the Linux kernel: allnoconfig, defconfig, and menuconfig edit -a ".config" file that selects which features to include in the resulting -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 +It works like the Linux kernel: `allnoconfig`, `defconfig`, and `menuconfig` +edit a `.config` file that selects which features to include in the resulting +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 +The maximum sane configuration is `make defconfig`: `allyesconfig` isn't recommended for toybox because it enables unfinished commands and debug code. ---- Creating a Toybox-based Linux system +## Creating a Toybox-based Linux system 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 @@ -90,14 +94,13 @@ 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. (And miscellaneous binaries like nm and objdump.) -Static linking (with the --static option) copies the shared library contents +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). +the target system (`man ldd` and `man ld.so` for details). An example toybox-based system is Aboriginal Linux: - http://landley.net/aboriginal/about.html That's designed to run under qemu, emulating several different hardware @@ -110,14 +113,12 @@ the Android Open Source Project.) * Or something providing the same API such as FreeBSD's Linux emulation layer. ---- Presentations +## 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 @@ -130,14 +131,14 @@ the Android Open Source Project.) 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 + 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 +## Contributing The three important URLs for communicating with the toybox project are: @@ -150,13 +151,15 @@ The three important URLs for communicating with the toybox project are: 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 +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 @@ -164,6 +167,6 @@ me of it. 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. +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.bp` and the checked-in `generated/*` files) which go directly to AOSP. -- 2.22.0.rc1.257.g3120a18244-goog
_______________________________________________ Toybox mailing list Toybox@lists.landley.net http://lists.landley.net/listinfo.cgi/toybox-landley.net
