--- /dev/null
+// -*- 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.
+