Merge from bittboy/buildroot@db180c0

docs/manual/how-buildroot-works.txt

@@ -0,0 +1,69 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+== How Buildroot works
+
+As mentioned above, Buildroot is basically a set of Makefiles that
+download, configure, and compile software with the correct options. It
+also includes patches for various software packages - mainly the ones
+involved in the cross-compilation toolchain (+gcc+, +binutils+ and
++uClibc+).
+
+There is basically one Makefile per software package, and they are
+named with the +.mk+ extension. Makefiles are split into many different
+parts.
+
+* The +toolchain/+ directory contains the Makefiles
+  and associated files for all software related to the
+  cross-compilation toolchain: +binutils+, +gcc+, +gdb+,
+  +kernel-headers+ and +uClibc+.
+
+* The +arch/+ directory contains the definitions for all the processor
+  architectures that are supported by Buildroot.
+
+* The +package/+ directory contains the Makefiles and
+  associated files for all user-space tools and libraries that Buildroot
+  can compile and add to the target root filesystem. There is one
+  sub-directory per package.
+
+* The +linux/+ directory contains the Makefiles and associated files for
+  the Linux kernel.
+
+* The +boot/+ directory contains the Makefiles and associated files for
+  the bootloaders supported by Buildroot.
+
+* The +system/+ directory contains support for system integration, e.g.
+  the target filesystem skeleton and the selection of an init system.
+
+* The +fs/+ directory contains the Makefiles and
+  associated files for software related to the generation of the
+  target root filesystem image.
+
+Each directory contains at least 2 files:
+
+* +something.mk+ is the Makefile that downloads, configures,
+  compiles and installs the package +something+.
+
+* +Config.in+ is a part of the configuration tool
+  description file. It describes the options related to the
+  package.
+
+The main Makefile performs the following steps (once the
+configuration is done):
+
+* Create all the output directories: +staging+, +target+, +build+,
+  etc. in the output directory (+output/+ by default,
+  another value can be specified using +O=+)
+
+* Generate the toolchain target. When an internal toolchain is used, this
+  means generating the cross-compilation toolchain. When an external
+  toolchain is used, this means checking the features of the external
+  toolchain and importing it into the Buildroot environment.
+
+* Generate all the targets listed in the +TARGETS+ variable. This
+  variable is filled by all the individual components'
+  Makefiles. Generating these targets will trigger the compilation of
+  the userspace packages (libraries, programs), the kernel, the
+  bootloader and the generation of the root filesystem images,
+  depending on the configuration.
+