add OpenADK manual.

1 files changed, 80 insertions, 0 deletions

diff --git a/docs/how-openadk-works.txt b/docs/how-openadk-works.txt
new file mode 100644
index 000000000..9c6ae167d
--- /dev/null
+++ b/docs/how-openadk-works.txt
@@ -0,0 +1,80 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+How OpenADK works
+-----------------
+
+As mentioned above, OpenADK is basically a set of Makefiles that
+download, configure, and compile software with the correct options. It
+also includes patches for various software packages and the linux kernel. 
+
+There is basically one Makefile per software package. 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 +libc+.
+
+* The +target/+ directory contains the definitions for all the processor
+  architectures that are supported by OpenADK. +target/linux+ contains
+  the meta-data for the Linux kernel configuration abstraction layer and
+  the kernel patches
+
+* The +package/+ directory contains the Makefiles and
+  associated files for all user-space tools and libraries that OpenADK
+  can compile and add to the target root filesystem. There is one
+  sub-directory per package.
+
+* The +mk/+ directory contains some globally used Makefiles with
+  the suffix +.mk+, these are used in all other Makefile via include
+
+* The +tools/+ directory contains the Makefiles and
+  associated files for software related to the generation of the
+  host tools needed for different tasks (compression tools, ..).
+
+There are three other directories in the top level directory of OpenADK:
+
+* The +scripts/+ directory contains shell scripts for the creation of
+  meta-data in OpenADK, install scripts and image creation scripts
+
+* The +config/+ directory contains the application used for the
+  +make menuconfig+ system
+
+* The +tests/+ directory contains some data for the +make check+ target,
+  to run the gcc testsuite
+
+The main Makefile performs the following steps before the configuration
+is done:
+
+* Call the +prereq+ target to check if the host system have all required
+  software installed. It creates the +prereq.mk+ Makefile. 
+
+* Compile and run the OpenADK tools to generate the meta-data for the menu
+  based configuration and creates the +package/Depends.mk+ Makefile to handle the 
+  dependencies
+
+* Starts the menu based configuration system via +make menuconfig+
+
+The main Makefile performs the following steps, once the
+configuration is done (it is mainly a wrapper for +mk/build.mk+):
+
+* Create all the output directories: +host_<gnu_host_name>+, +target_<arch>_<libc>+, +build_<arch>_<libc>+,
+  +pkg_<arch>_<libc>+, etc. 
+
+* Call the +scan-pkgs.sh+ script to find any needed optional host software, needed to compile
+  software the user has configured 
+
+* Call the +update-sys+ and +update-pkg+ scripts to generate some meta-data for 
+  available systems and package collections
+
+* Generate the host tools required for different tasks (encrypting passwords,
+  compressing data, extracting archives, ..)
+
+* Generate the cross-compilation toolchain (binutils, gcc, libc, gdb)
+
+* Compile the linux kernel
+
+* Compile all the userspace packages, the boot loader and external kernel modules
+
+* Generate the firmware images or archives