1 files changed, 73 insertions, 0 deletions
diff --git a/docs/how-openadk-works.txt b/docs/how-openadk-works.txt
new file mode 100644
index 000000000..e86251196
--- /dev/null
+++ b/docs/how-openadk-works.txt
@@ -0,0 +1,73 @@
+// -*- 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 or to the host directory. 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 +adk/+ directory contains the Makefiles and
+  associated files for software related to the generation of the
+  host tools needed for +make menuconfig+ system
+
+* The +scripts/+ directory contains shell scripts for the creation of
+  meta-data in OpenADK, install scripts and image creation scripts
+
+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, creating images, ..)
+
+* 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
+