summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--TODO9
-rw-r--r--docs/Makefile24
-rw-r--r--docs/adding-packages-auto.txt71
-rw-r--r--docs/adding-packages-conclusion.txt13
-rw-r--r--docs/adding-packages-directory.txt57
-rw-r--r--docs/adding-packages-hooks.txt31
-rw-r--r--docs/adding-packages-host.txt92
-rw-r--r--docs/adding-packages-manual.txt83
-rw-r--r--docs/adding-packages.txt25
-rw-r--r--docs/advanced.txt15
-rw-r--r--docs/appendix.txt8
-rw-r--r--docs/ccache-support.txt21
-rw-r--r--docs/common-usage.txt87
-rw-r--r--docs/configure.txt68
-rw-r--r--docs/contribute.txt87
-rw-r--r--docs/customize-busybox-config.txt20
-rw-r--r--docs/customize-kernel-config.txt48
-rw-r--r--docs/customize-libc-config.txt33
-rw-r--r--docs/customize-outside-adk.txt154
-rw-r--r--docs/customize-rootfs.txt23
-rw-r--r--docs/customize-store.txt14
-rw-r--r--docs/customize-toolchain.txt23
-rw-r--r--docs/customize.txt19
-rw-r--r--docs/debugging-openadk.txt29
-rw-r--r--docs/developer-guide.txt13
-rw-r--r--docs/download-location.txt26
-rw-r--r--docs/faq-troubleshooting.txt58
-rw-r--r--docs/getting.txt22
-rw-r--r--docs/going-further.txt9
-rw-r--r--docs/how-openadk-works.txt80
-rw-r--r--docs/images/menuconfig-configured.pngbin0 -> 341555 bytes
-rw-r--r--docs/images/menuconfig.pngbin0 -> 271731 bytes
-rw-r--r--docs/introduction.txt26
-rw-r--r--docs/legal-notice.txt51
-rw-r--r--docs/make-tips.txt99
-rw-r--r--docs/manual.txt33
-rw-r--r--docs/network-configuration.txt182
-rw-r--r--docs/package-make-target.txt52
-rw-r--r--docs/package-reference.txt135
-rw-r--r--docs/patch-policy.txt82
-rw-r--r--docs/prerequisite.txt52
-rw-r--r--docs/qemu.txt1
-rw-r--r--docs/running-openadk.txt178
-rw-r--r--docs/runtime-debugging.txt22
-rw-r--r--docs/starting-up.txt12
-rw-r--r--docs/using-openadk-development.txt62
-rw-r--r--docs/using-openadk-toolchain.txt19
-rw-r--r--docs/using.txt99
-rw-r--r--docs/working-with.txt25
-rw-r--r--docs/writing-rules.txt91
50 files changed, 2483 insertions, 0 deletions
diff --git a/TODO b/TODO
index 362a8f944..e789024f5 100644
--- a/TODO
+++ b/TODO
@@ -1,3 +1,12 @@
+- tzdata split + update
+- getty + serial rework
+- add daemon() function to functions.sh
+- add printing of OK/FAIL (optional verbose bootup)
+- fixup rework libgcc --export-symbols
+- libgcc static?
+- remove 32 bit kernel for 64 bit targets
+- static toolchain support
+- toolchain in /usr , check gcj
- rework startup, maybe use init.c, start gettys after bootup ready
- more output for initscripts on bootup
- port uuterm
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 000000000..1670e0041
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,24 @@
+TOPDIR=$(pwd)
+
+all: pdf text html
+
+pdf:
+ mkdir .pdf pdf
+ cp *.txt .pdf
+ cp images/*.png pdf
+ a2x -v --dblatex-opts "-P latex.output.revhistory=0" -f pdf -d book -L -D pdf .pdf/manual.txt
+
+text:
+ mkdir .text text
+ cp *.txt .text
+ cp images/*.png text
+ a2x -v -f text -d book -L -D text .text/manual.txt
+
+html:
+ mkdir .html html
+ cp *.txt .html
+ cp images/*.png html
+ a2x -v --xsltproc-opts "--stringparam toc.section.depth 2" -f xhtml -d book -L -D html .html/manual.txt
+
+clean:
+ rm -rf pdf .pdf text .text html .html
diff --git a/docs/adding-packages-auto.txt b/docs/adding-packages-auto.txt
new file mode 100644
index 000000000..ac52c395f
--- /dev/null
+++ b/docs/adding-packages-auto.txt
@@ -0,0 +1,71 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+Infrastructure for autotools-based packages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+[[auto-package-tutorial]]
+
+First, let's see how to write a +Makefile+ file for an autotools-based
+package, with an example:
+
+------------------------
+01: # This file is part of the OpenADK project. OpenADK is copyrighted
+02: # material, please see the LICENCE file in the top-level directory.
+03:
+04: include ${TOPDIR}/rules.mk
+05:
+06: PKG_NAME:= libfoo
+07: PKG_VERSION:= 1.0
+08: PKG_RELEASE:= 1
+09: PKG_MD5SUM:= ba526cd8f4403a5d351a9efaa8608fbc
+10: PKG_DESCR:= foo library
+11: PKG_SECTION:= libs
+12: PKG_BUILDDEP:= openssl
+13: PKG_DEPENDS:= libopenssl
+14: PKG_URL:= http://www.libfoo.org/
+15: PKG_SITES:= http://downloads.libfoo.org/
+16:
+17: include ${TOPDIR}/mk/package.mk
+18:
+19: $(eval $(call PKG_template,LIBFOO,libfoo,${PKG_VERSION}-${PKG_RELEASE},${PKG_DEPENDS},${PKG_DESCR},${PKG_SECTION}))
+20:
+21: libfoo-install:
+22: ${INSTALL_DIR} ${IDIR_LIBFOO}/usr/lib
+23: ${CP} ${WRKINST}/usr/lib/libfoo.so* ${IDIR_LIBFOO}/usr/lib
+24:
+25: include ${TOPDIR}/mk/pkg-bottom.mk
+
+------------------------
+
+The Makefile begins with line 4 with the inclusion of the top level rules.mk
+file. After that the Makefile starts on line 6 to 15 with metadata
+information: the name of the package (+PKG_NAME+), the version of the package
+(+PKG_VERSION+), the release number of the package (+PKG_RELEASE+), which is
+used in OpenADK to mark any package updates, the md5 hash of the source archive
+(+PKG_MD5SUM+), the short one line description for the package (+PKG_DESCR+),
+the package section for the menu configuration system (+PKG_SECTION+), the
+package buildtime dependencies (+PKG_BUILDDEP+), the package runtime
+dependencies (+PKG_DEPENDS+), the package homepage (+PKG_URL+) and finally the
+internet locations at which the tarball can be downloaded from (+PKG_SITES+).
+Normally ${PKG_NAME}-${PKG_VERSION}.tar.gz will be downloaded. You can
+overwrite the default via the +DISTFILES+ variable. You can add more then one
+archive name in +DISTFILES+ via space separated. If you have no source archive
+at all, just use the boolean variable +NO_DISTFILES+ and set it to 1.
+
+On line 17 the +mk/package.mk+ file is included, which contains the PKG_template
+function, which is used in line 19.
+
+On line 21-23 we install the shared library into the package installation
+directory, which is used to create the resulting binary package or tar archive
+for the target.
+
+On line 25 we include +mk/pkg-bottom.mk+, which includes common functions used
+by the package fetching and building process.
+
+With the autotools infrastructure, all the steps required to build
+and install the packages are already defined, and they generally work
+well for most autotools-based packages. However, when required, it is
+still possible to customize what is done in any particular step.
+By adding a post-operation hook (after extract, patch, configure,
+build or install). See xref:hooks[] for details.
diff --git a/docs/adding-packages-conclusion.txt b/docs/adding-packages-conclusion.txt
new file mode 100644
index 000000000..6ec88e999
--- /dev/null
+++ b/docs/adding-packages-conclusion.txt
@@ -0,0 +1,13 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+Conclusion
+~~~~~~~~~~
+
+As you can see, adding a software package to OpenADK is simply a
+matter of writing a Makefile using an existing template and modifying it
+according to the compilation process required by the package.
+
+If you package software that might be useful for other people, don't
+forget to send a patch to the OpenADK developer (see xref:submitting-patches[])!
+
diff --git a/docs/adding-packages-directory.txt b/docs/adding-packages-directory.txt
new file mode 100644
index 000000000..347c39aa6
--- /dev/null
+++ b/docs/adding-packages-directory.txt
@@ -0,0 +1,57 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+New package
+~~~~~~~~~~~
+
+First of all, create a directory and Makefile under the +package+
+directory for your software, for example +libfoo+:
+
+------------
+ $ make newpackage PKG=libfoo VER=0.1
+------------
+
+This will create a sample Makefile for you, with a lot of comments and
+hints. It describes how the package should be downloaded, configured,
+built, installed, etc.
+
+Depending on the package type, the +Makefile+ must be written in a
+different way, using two different infrastructures:
+
+* manual package configuration
+
+* automatic package configuration using autotools
+
+
+[[dependencies-target-toolchain-options]]
+Dependencies on target and toolchain options
+
+Some packages depend on certain options of the toolchain: mainly the
+choice of C library and C++ support. Some packages can only be built on
+certain target architectures or for specific target systems.
+
+These dependencies have to be expressed in the Makefile. The given values
+are space separated and can be negated with ! as a prefix.
+
+* Target architecture
+** variable used PKG_ARCH_DEPENDS
+** allowed values are: arm, mips, .. see target/arch.lst
+
+* Target system
+** variable used PKG_SYSTEM_DEPENDS
+** for allowed values see the output of ./scripts/getsystems
+
+* Target C library
+** variable used PKG_LIBC_DEPENDS
+** allowed values are: uclibc glibc musl
+
+* Host system
+** variable used PKG_HOST_DEPENDS
+** allowed values are: linux darwin cygwin freebsd netbsd openbsd
+
+* C++ support
+** variable used PKG_NEED_CXX
+** Comment string: `C++`
+
+Further formatting details: see xref:writing-rules-mk[the writing
+rules].
diff --git a/docs/adding-packages-hooks.txt b/docs/adding-packages-hooks.txt
new file mode 100644
index 000000000..65786fbfc
--- /dev/null
+++ b/docs/adding-packages-hooks.txt
@@ -0,0 +1,31 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[hooks]]
+Hooks available in the various build steps
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The infrastructure allow packages to specify hooks. These define further
+actions to perform after existing steps. Most hooks aren't really useful for
+manual packages, since the +Makefile+ already has full control over the
+actions performed in each step of the package construction.
+
+The following hook targets are available:
+
+* +post-extract+
+* +post-patch+
+* +pre-configure+
+* +post-configure+
+* +pre-build+
+* +post-build+
+* +pre-install+
+* +post-install+
+
+For example, to make some scripts executable after extraction,
+add following to your +Makefile+:
+
+---------------------
+post-extract:
+ chmod a+x $(WRKBUILD)/build/make/*.sh
+ chmod a+x $(WRKBUILD)/build/make/*.pl
+---------------------
diff --git a/docs/adding-packages-host.txt b/docs/adding-packages-host.txt
new file mode 100644
index 000000000..a858d4563
--- /dev/null
+++ b/docs/adding-packages-host.txt
@@ -0,0 +1,92 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+Infrastructure for host packages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+[[host-package-tutorial]]
+
+First, let's see how to write a +Makefile+ for an host only package, required
+by another target package to build, with an example:
+
+------------------------
+01: # This file is part of the OpenADK project. OpenADK is copyrighted
+02: # material, please see the LICENCE file in the top-level directory.
+03:
+04: include $(TOPDIR)/rules.mk
+05:
+06: PKG_NAME:= hostfoo
+07: PKG_VERSION:= 1.0
+08: PKG_RELEASE:= 1
+09: PKG_MD5SUM:= 291ba57c0acd218da0b0916c280dcbae
+10: PKG_DESCR:= hostfoo utility
+11: PKG_SECTION:= misc
+12: PKG_URL:= http://www.foo.org/
+13: PKG_SITES:= http://download.foo.org/
+14:
+15: PKG_CFLINE_HOSTFOO:= depends on ADK_HOST_ONLY
+16:
+17: include $(TOPDIR)/mk/host.mk
+18: include $(TOPDIR)/mk/package.mk
+19:
+20: $(eval $(call HOST_template,HOSTFOO,hostfoo,$(PKG_VERSION)-${PKG_RELEASE}))
+21:
+22: HOST_STYLE:= auto
+23:
+24: include ${TOPDIR}/mk/host-bottom.mk
+25: include ${TOPDIR}/mk/pkg-bottom.mk
+------------------------
+
+The differences to a target package is the inclusion of +mk/host.mk+ in line 17 and
++mk/host-bottom.mk+ in line 24. Furthermore the HOST_template is called instead of
+the PKG_template. The last difference is the usage of +PKG_CFLINE_HOSTFOO+ to mark
+the package as host only package.
+
+Following mix between host and target package is possible, too:
+------------------------
+01: # This file is part of the OpenADK project. OpenADK is copyrighted
+02: # material, please see the LICENCE file in the top-level directory.
+03:
+04: include ${TOPDIR}/rules.mk
+05:
+06: PKG_NAME:= foo
+07: PKG_VERSION:= 1.0
+08: PKG_RELEASE:= 1
+09: PKG_MD5SUM:= 032a7b7b9f1a6e278ccde73f82cec5c2
+10: PKG_DESCR:= foo tool
+11: PKG_SECTION:= lang
+12: PKG_BUILDDEP:= foo-host
+13: PKG_URL:= http://www.foo.org/
+14: PKG_SITES:= http://download.foo.org/
+15:
+16: include ${TOPDIR}/mk/host.mk
+17: include ${TOPDIR}/mk/package.mk
+18:
+19: $(eval $(call HOST_template,FOO,foo,${PKG_VERSION}-${PKG_RELEASE}))
+20: $(eval $(call PKG_template,FOO,foo,${PKG_VERSION}-${PKG_RELEASE},${PKG_DEPENDS},${PKG_DESCR},${PKG_SECTION}))
+21:
+22: HOST_STYLE:= auto
+23:
+24: foo-install:
+25: ${INSTALL_DIR} ${IDIR_FOO}/usr/bin
+26: ${INSTALL_BIN} ${WRKINST}/usr/bin/foo ${IDIR_FOO}/usr/bin
+27:
+28: include ${TOPDIR}/mk/host-bottom.mk
+29: include ${TOPDIR}/mk/pkg-bottom.mk
+------------------------
+
+It is important to have foo-host as package build dependency, see line 12, so that the order is always build the host package
+and then the target package.
+If you need to rebuild a mixed package, you are advised to use:
+------------
+ $ make package=<package> clean hostpackage package
+------------
+
+At the moment there is one limitation regarding the recursive dependency resolving. It is just not implemented, yet.
+So you always need to set +PKG_BUILDDEP+ to all host tools dependencies in the right order. If package foo needs host
+tool bar, and host tool bar needs host library libbaz, you have to use following +PKG_BUILDDEP+ variable:
+------------
+ PKG_BUILDDEP:=libbaz-host bar-host
+------------
+
+
diff --git a/docs/adding-packages-manual.txt b/docs/adding-packages-manual.txt
new file mode 100644
index 000000000..b231c19fb
--- /dev/null
+++ b/docs/adding-packages-manual.txt
@@ -0,0 +1,83 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+Infrastructure for packages with specific build systems
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By 'packages with specific build systems' we mean all the packages whose build
+system is not the standard one, speak 'autotools'. This typically includes
+packages whose build system is based on hand-written Makefiles or shell
+scripts.
+
+[[manual-package-tutorial]]
+
+------------------------------
+01: # This file is part of the OpenADK project. OpenADK is copyrighted
+02: # material, please see the LICENCE file in the top-level directory.
+03:
+04: include $(TOPDIR)/rules.mk
+05:
+06: PKG_NAME:= libfoo
+07: PKG_VERSION:= 1.0
+08: PKG_RELEASE:= 1
+09: PKG_MD5SUM:= eade38998313c25fd7934719cdf8a2ea
+10: PKG_DESCR:= foo library
+11: PKG_SECTION:= libs
+12: PKG_BUILDDEP:= openssl
+13: PKG_DEPENDS:= libopenssl
+14: PKG_URL:= http://www.libfoo.org/
+15: PKG_SITES:= http://download.libfoo.org/
+16:
+17: include $(TOPDIR)/mk/package.mk
+18:
+19: $(eval $(call PKG_template,LIBFOO,libfoo,${PKG_VERSION}-${PKG_RELEASE},${PKG_DEPENDS},${PKG_DESCR},${PKG_SECTION}))
+20:
+21: CONFIG_STYLE:= manual
+22: BUILD_STYLE:= manual
+23: INSTALL_STYLE:= manual
+24:
+25: do-configure:
+26: ${CP} ./files/config ${WRKBUILD}/.config
+27:
+28: do-build:
+29: ${MAKE} -C ${WRKBUILD} all
+30:
+31: do-install:
+32: ${INSTALL_DIR} ${IDIR_LIBFOO}/usr/lib
+33: ${CP} ${WRKBUILD}/libfoo.so* ${IDIR_LIBFOO}/usr/lib
+34:
+35: include ${TOPDIR}/mk/pkg-bottom.mk
+--------------------------------
+
+The Makefile begins with line 4 with the inclusion of the top level rules.mk
+file. After that the Makefile starts on line 6 to 15 with metadata
+information: the name of the package (+PKG_NAME+), the version of the package
+(+PKG_VERSION+), the release number of the package (+PKG_RELEASE+), which is
+used in OpenADK to mark any package updates, the md5 hash of the source archive
+(+PKG_MD5SUM+), the short one line description for the package (+PKG_DESCR+),
+the package section for the menu configuration system (+PKG_SECTION+), the
+package buildtime dependencies (+PKG_BUILDDEP+), the package runtime
+dependencies (+PKG_DEPENDS+), the package homepage (+PKG_URL+) and finally the
+internet locations at which the tarball can be downloaded from (+PKG_SITES+).
+Normally ${PKG_NAME}-${PKG_VERSION}.tar.gz will be downloaded. You can
+overwrite the default via the +DISTFILES+ variable. You can add more then one
+archive name in +DISTFILES+ via space separated. If you have no source archive
+at all, just use the boolean variable +NO_DISTFILES+ and set it to 1.
+
+On line 17 the +mk/package.mk+ file is included, which contains the PKG_template
+function, which is used in line 19.
+
+On line 21 to 23 we define that the configuration step, the building and install
+steps are manually provided.
+
+On line 25-26 we implement a manual configuration step of the libfoo package
+by copying a manually created config file into the build directory.
+
+On line 28-29 we start the compilation process via make.
+
+On line 31-33 we install the shared library into the package installation
+directory, which is used to create the resulting binary package or tar archive
+for the target.
+
+On line 35 we include +mk/pkg-bottom.mk+, which includes common functions used
+by the package fetching and building process.
diff --git a/docs/adding-packages.txt b/docs/adding-packages.txt
new file mode 100644
index 000000000..122ae6c3c
--- /dev/null
+++ b/docs/adding-packages.txt
@@ -0,0 +1,25 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[adding-packages]]
+Adding new packages to OpenADK
+------------------------------
+
+This section covers how new packages (userspace libraries or
+applications) can be integrated into OpenADK. It also shows how existing
+packages are integrated, which is needed for fixing issues or tuning
+their configuration.
+
+include::adding-packages-directory.txt[]
+
+include::adding-packages-manual.txt[]
+
+include::adding-packages-auto.txt[]
+
+include::adding-packages-host.txt[]
+
+include::adding-packages-hooks.txt[]
+
+include::adding-packages-conclusion.txt[]
+
+include::package-reference.txt[]
diff --git a/docs/advanced.txt b/docs/advanced.txt
new file mode 100644
index 000000000..4ef75e884
--- /dev/null
+++ b/docs/advanced.txt
@@ -0,0 +1,15 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+Advanced usage
+--------------
+
+include::using-openadk-toolchain.txt[]
+
+include::ccache-support.txt[]
+
+include::download-location.txt[]
+
+include::package-make-target.txt[]
+
+include::using-openadk-development.txt[]
diff --git a/docs/appendix.txt b/docs/appendix.txt
new file mode 100644
index 000000000..cf004b461
--- /dev/null
+++ b/docs/appendix.txt
@@ -0,0 +1,8 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+Appendix
+========
+
+include::network-configuration.txt[]
+
diff --git a/docs/ccache-support.txt b/docs/ccache-support.txt
new file mode 100644
index 000000000..3dfdd1fa2
--- /dev/null
+++ b/docs/ccache-support.txt
@@ -0,0 +1,21 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[ccache]]
+Using +ccache+ in OpenADK
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+http://ccache.samba.org[ccache] is a compiler cache. It stores the
+object files resulting from each compilation process, and is able to
+skip future compilation of the same source file (with same compiler
+and same arguments) by using the pre-existing object files. When doing
+almost identical builds from scratch a number of times, it can nicely
+speed up the build process.
+
++ccache+ support is integrated in OpenADK. You just have to enable +Use ccache
+to speedup recompilation+ in +Globale settings+. This will automatically build
++ccache+ and use it for every target compilation.
+
+The cache is located in +$HOME/.ccache+. It is stored outside of OpenADK
+directory so that it can be shared by separate OpenADK builds. If you want to
+get rid of the cache, simply remove this directory.
diff --git a/docs/common-usage.txt b/docs/common-usage.txt
new file mode 100644
index 000000000..b08475c4d
--- /dev/null
+++ b/docs/common-usage.txt
@@ -0,0 +1,87 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+Daily use
+---------
+
+Understanding when a full rebuild is necessary
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+OpenADK tries to detect what part of the system should be rebuilt when the
+system configuration is changed through +make menuconfig+. In some cases it
+automatically rebuilt packages, but sometimes just a warning is printed to the
+terminal, that a rebuild is necessary to make the changes an effect. If strange
+things are happening, the autodetection might have not worked correctly, then
+you should consider to rebuild everything. If you are following development you
+should always do a full rebuild after fetching updates via +git pull+. It is
+not always required, but if anything fails, you are on your own.
+Use following to do a full rebuild without refetching distfiles:
+
+--------------------
+ $ make cleandir && make
+--------------------
+
+Understanding how to rebuild packages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In OpenADK you can rebuild a single package with:
+--------------------
+ $ make package=<pkgname> clean package
+--------------------
+
+It will automatically remove all files added to the staging target directory
++target_*+. If you just want to restart compilation process, after making
+some fixes in +build_*/w-<pkgname>-<pkgversion>/+, just do:
+--------------------
+ $ make package=<pkgname> package
+--------------------
+
+If you are happy with your changes to the package sources, you can automatically
+generate a patch, which will be saved in +package/<pkgname>/patches and automatically
+applied on the next clean rebuild:
+--------------------
+ $ make package=<pkgname> update-patches
+--------------------
+
+The newly created patches will be opened in $EDITOR, so you can some comments to
+the top of the file, before the diff.
+
+
+Offline builds
+~~~~~~~~~~~~~~
+
+If you intend to do an offline build and just want to download
+all sources that you previously selected in the configurator
+then issue:
+
+--------------------
+ $ make download
+--------------------
+
+You can now disconnect or copy the content of your +dl+
+directory to the build-host.
+
+[[env-vars]]
+
+Environment variables
+~~~~~~~~~~~~~~~~~~~~~
+
+OpenADK also honors some environment variables, when they are passed
+to +make+.
+
+* +ARCH+, the architecture of the target system
+* +SYSTEM+, the target system name
+* +LIBC+, the C library for the target system
+* +COLLECT+, the package collection, which will be used
+* +VERBOSE+, verbose build, when set to 1
+
+An example that creates a configuration file for Raspberry PI with all
+software packages enabled, but not included in the resulting firmware image:
+
+--------------------
+ $ make ARCH=arm SYSTEM=raspberry-pi LIBC=musl allmodconfig
+--------------------
+
+This is often used in the development process of a target system, to verify that
+all packages are compilable.
+
diff --git a/docs/configure.txt b/docs/configure.txt
new file mode 100644
index 000000000..3fadc1f48
--- /dev/null
+++ b/docs/configure.txt
@@ -0,0 +1,68 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[toolchain]]
+
+Cross-compilation toolchain
+---------------------------
+
+A compilation toolchain is the set of tools that allows you to compile
+code for your system. It consists of a compiler (in our case, +gcc+),
+binary utils like assembler and linker (in our case, +binutils+) and a
+C standard library (either
+http://www.gnu.org/software/libc/libc.html[GNU Libc],
+http://www.uclibc.org/[uClibc] or
+http://www.musl-libc.org/[musl]).
+
+The system installed on your development station certainly already has
+a compilation toolchain that you can use to compile an application
+that runs on your system. If you're using a PC, your compilation
+toolchain runs on an x86 processor and generates code for an x86
+processor. Under most Linux systems, the compilation toolchain uses
+the GNU libc (glibc) as the C standard library. This compilation
+toolchain is called the "host compilation toolchain". The machine on
+which it is running, and on which you're working, is called the "host
+system" footnote:[This terminology differs from what is used by GNU
+configure, where the host is the machine on which the application will
+run (which is usually the same as target)].
+
+The compilation toolchain is provided by your distribution, and
+OpenADK has nothing to do with it (other than using it to build a
+cross-compilation toolchain and other tools that are run on the
+development host).
+
+As said above, the compilation toolchain that comes with your system
+runs on and generates code for the processor in your host system. As
+your embedded system has a different processor, you need a
+cross-compilation toolchain - a compilation toolchain that runs on
+your _host system_ but generates code for your _target system_ (and
+target processor). For example, if your host system uses x86 and your
+target system uses ARM, the regular compilation toolchain on your host
+runs on x86 and generates code for x86, while the cross-compilation
+toolchain runs on x86 and generates code for ARM.
+
+OpenADK provides only one solution for the cross-compilation toolchain.
+The versions for binutils, gcc, gdb and libc are fixed. It is a combination
+of mostly the latest versions, which are known to work in this combination
+and are known to produce usable firmware images. You normally do not need to
+know the deep details, it is part of OpenADK policy to keep this part
+simple for the user.
+
+You can only choose between three C libraries:
+http://www.uclibc.org[uClibc], the
+http://www.gnu.org/software/libc/libc.html[glibc] and
+http://www.musl-libc.org[musl].
+
+There are some minimal configuration options provided in +Toolchain settings+.
+You can enable or disable the building of following components and toolchain
+options:
+
+* GDB (enabled by default)
+
+* GNU C++ compiler (enabled by default, when disabled
+ will prevent some packages to show up in the menu selection)
+
+* Stack Smashing Support (SSP) support for GNU C/C++ Compiler (experimental, some packages will fail to build)
+
+* Link Time Optimization (LTO) support for GNU C/C++ Compiler (experimental, some packages will fail to build)
+
diff --git a/docs/contribute.txt b/docs/contribute.txt
new file mode 100644
index 000000000..909263886
--- /dev/null
+++ b/docs/contribute.txt
@@ -0,0 +1,87 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+Contributing to OpenADK
+=======================
+
+If you want to contribute to OpenADK, you will need a git view of
+the project. Refer to xref:getting-openadk[] to get it.
+
+Currently a mail to wbx@openadk.org is the central place for contribution.
+
+[[submitting-patches]]
+Submitting patches
+------------------
+
+When your changes are done, and committed in your local git view,
+_rebase_ your development branch on top of the upstream tree before
+generating the patch set. To do so, run:
+
+---------------------
+$ git fetch --all --tags
+$ git rebase origin/master
+---------------------
+
+Here, you are ready to generate then submit your patch set.
+
+To generate it, run:
+
+---------------------
+$ git format-patch -M -n -s origin/master
+---------------------
+
+This will generate patch files automatically adding the +Signed-off-by+ line.
+
+Once patch files are generated, you can review/edit the commit message
+before submitting them using your favorite text editor.
+
+Lastly, send/submit your patch set to the OpenADK developer:
+
+---------------------
+$ git send-email --to wbx@openadk.org *.patch
+---------------------
+
+Note that +git+ should be configured to use your mail account.
+To configure +git+, see +man git-send-email+ or google it.
+
+Make sure posted *patches are not line-wrapped*, otherwise they cannot
+easily be applied. In such a case, fix your e-mail client, or better,
+use +git send-email+ to send your patches.
+
+Cover letter
+~~~~~~~~~~~~
+
+If you want to present the whole patch set in a separate mail, add
++--cover-letter+ to the +git format-patch+ command (see +man
+git-format-patch+ for further information). This will generate a
+template for an introduction e-mail to your patch series.
+
+A 'cover letter' may be useful to introduce the changes you propose
+in the following cases:
+
+* large number of commits in the series;
+
+* deep impact of the changes in the rest of the project;
+
+* RFC footnote:[RFC: (Request for comments) change proposal];
+
+* whenever you feel it will help presenting your work, your choices,
+ the review process, etc.
+
+[[reporting-bugs]]
+Reporting issues/bugs, get help
+-------------------------------
+
+Try to think as if you were trying to help someone else; in
+that case, what would you need?
+
+Here is a short list of details to provide in such case:
+
+* host machine (OS/release)
+* git version of OpenADK
+* target for which the build fails
+* package(s) which the build fails
+* the command that fails and its output
+* any information you think that may be relevant
+
+Additionally, you can add the +.config+ file.
diff --git a/docs/customize-busybox-config.txt b/docs/customize-busybox-config.txt
new file mode 100644
index 000000000..dc1c7abaa
--- /dev/null
+++ b/docs/customize-busybox-config.txt
@@ -0,0 +1,20 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[busybox-custom]]
+Customizing the Busybox configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+http://www.busybox.net/[Busybox] is very configurable, and you may
+want to customize it. You can just configure it via +Package selection+,
++Base System+, +Busybox Configuration+. The menu based busybox configuration
+is mostly integrated into OpenADK. There are some options, which are not
+available and not supported. If you need to, you can change the defaults
+in +package/busybox/config+ and regenerate your OpenADK configuration.
+
+A change in the busybox configuration will rebuild the busybox package. If you
+choose another implementation of f.e. tar, which is provided by default from
+busybox, tar in busybox will be deactivated and the package will be
+automatically rebuilded, so that your resulting firmware images or archives
+will only contain a single tar program. Obviosly just the one you have
+selected.
diff --git a/docs/customize-kernel-config.txt b/docs/customize-kernel-config.txt
new file mode 100644
index 000000000..9adeb7a9d
--- /dev/null
+++ b/docs/customize-kernel-config.txt
@@ -0,0 +1,48 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[kernel-custom]]
+Customizing the Linux kernel configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Linux kernel configuration can be customized using +make menuconfig+.
+OpenADK uses a combination of Linux miniconfig feature and user defined
+features to generate a valid Linux configuration for your target.
+Some features and drivers are not selectable via +make menuconfig+, either
+because your choosen target system does not have support for it or the
+option is not implemented, yet. OpenADK uses some kind of abstraction
+layer between the real full featured and complicated Linux kernel configuration
+and you. It is not perfect and does include a lot of manual work in
++target/linux/config+, but it works in a acceptable way.
+
+If you just want to view the Linux configuration, which is actually
+used for your target, you can execute following command:
+
+---------------
+ $ make kernelconfig
+---------------
+
+Any changes here will get lost and will not be used to generate a kernel for
+your target. If you want to change the existing kernel configuration you need
+to follow these steps.
+
+The basic kernel configuration used for your choosen target is concatenated from
+following two files:
++target/linux/kernel.config+ and +target/<arch>/kernel/<system>+.
+
+So if you would like to change any basic stuff, just edit the files and recreate your
+firmware via:
+
+---------------
+ $ make
+---------------
+
+OpenADK automatically recognizes any change and will rebuild the kernel.
+
+The base kernel configuration for your target generated by OpenADK is normally just enough to
+bootup the system with support for your board, serial console, network card and boot medium.
+(like a hard disk, sd card or flash partition)
+
+If you need to enable some new optional drivers or features, which are not available in
++make menuconfig+, you need to dig in +target/linux/config+. There is the abstraction layer
+for the real kernel configuration.
diff --git a/docs/customize-libc-config.txt b/docs/customize-libc-config.txt
new file mode 100644
index 000000000..075a272a0
--- /dev/null
+++ b/docs/customize-libc-config.txt
@@ -0,0 +1,33 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[libc-custom]]
+Customizing the libc configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Just like xref:busybox-custom[BusyBox], http://www.uclibc.org/[uClibc]
+offers a lot of configuration options. They allow you to select
+various functionalities depending on your needs and limitations.
+OpenADK chooses automatically the best configuration regarding
+resulting code size, standard conformance, portability and GNU
+libc compatibility.
+
+If you still have the requirements to change the default, regenerate
+a new uClibc config from the existing one:
+
+----------------
+ $ tar xvf dl/uClibc-x.y.z.tar.bz2
+ $ cd uClibc-x.y.z && patch -p1 <../toolchain/uClibc/patches/uclibc-git*.patch
+ $ cp ../target/<arch>/uclibc.config .config
+ $ make menuconfig
+----------------
+
+Make all required changes. Then copy the newly created uClibc configuration back
+and rebuild your targetsystem, including the toolchain components:
+
+----------------
+ $ cp .config ../target/<arch>/uclibc.config
+ $ cd .. && make cleantarget && make
+----------------
+
+There are no customization options for GNU libc or musl available.
diff --git a/docs/customize-outside-adk.txt b/docs/customize-outside-adk.txt
new file mode 100644
index 000000000..575defa82
--- /dev/null
+++ b/docs/customize-outside-adk.txt
@@ -0,0 +1,154 @@
+// -*- mode:doc -*- ;
+
+[[outside-adk-custom]]
+Keeping customizations outside OpenADK
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The OpenADK project recommends and encourages upstreaming to the
+official OpenADK version the packages and board support that are
+written by developers. However, it is sometimes not possible or
+desirable because some of these packages or board support are highly
+specific or proprietary.
+
+In this case, OpenADK users are offered following choice using
+here own git repository.
+
+* Initialize your project
+
+Personalize your Git environment via:
+
+---------------------
+ $ git config --global user.name "Waldemar Brodkorb"
+ $ git config --global user.email wbx@openadk.org
+---------------------
+
+Get the latest version of OpenADK via anonymous git:
+
+---------------------
+ $ git clone --bare git://openadk.org/git/openadk myadk.git
+---------------------
+
+Use git-daemon to make the repository public to your developers. After that clone your new shared project repository:
+
+---------------------
+ $ git clone git+ssh://myserver.com/git/myadk.git
+ $ cd myadk
+---------------------
+
+Configure OpenADK remote git repository:
+
+---------------------
+ $ git remote add openadk git://openadk.org/git/openadk
+---------------------
+
+* Create your firmware
+
+Now you can either start with the latest version or use some older version:
+
+---------------------
+ $ git checkout -b stable_1_0 $sha1
+---------------------
+You can find $sha1 via git log. $sha1 is the hash after the keyword “commit”.
+
+Now build a firmware image for your target and test it. Fix bugs in the build
+environment or add new stuff. You can use the “extra” directory to add local
+unpackaged binaries and/or configuration files to overwrite packaged stuff.
+
+Check your uncommitted changes:
+
+---------------------
+ $ git status
+ $ git diff --cached
+ $ git diff
+---------------------
+
+Commit your git-added changes:
+
+---------------------
+ $ git commit
+---------------------
+Or just commit all changes:
+
+---------------------
+ $ git commit -a
+---------------------
+It is a good style to make a lot of small atomic commits.
+
+Push your changes back to your git repository.
+For new local branches:
+
+---------------------
+ $ git push origin stable_1_0
+---------------------
+
+Or in regulary usage via:
+---------------------
+ $ git push
+---------------------
+
+* Working together with OpenADK
+
+You can generate patches from all your changes against the remote master:
+
+---------------------
+ $ git format-patch -s origin
+---------------------
+
+Send all relevant patches to OpenADK author via eMail.
+
+Update your master with changes from OpenADK:
+
+---------------------
+ $ git checkout master
+ $ git pull openadk master
+---------------------
+
+If you want you can merge all changes to your branch:
+
+---------------------
+ $ git checkout stable_1_0
+ $ git merge master
+---------------------
+
+Or just cherry-pick some of the commits:
+
+---------------------
+ $ git cherry-pick $sha1
+---------------------
+
+* Releasing
+
+Tag your tested stable branch:
+
+---------------------
+ $ git tag -a stable_1.0
+---------------------
+Push your tag to your repository:
+
+---------------------
+ $ git push origin stable_1.0
+---------------------
+
+Checkout your tag and build your firmware:
+
+---------------------
+ $ git clone git+ssh://myserver.com/git/myadk.git mytag
+ $ cd mytag
+ $ git checkout stable_1.0
+---------------------
+
+* Deleting unused branches
+
+Deleting branches remotely:
+
+---------------------
+ $ git branch -r
+ $ git push origin :branchname
+---------------------
+
+Deleting branches locally:
+
+---------------------
+ $ git branch
+ $ git branch -D branchname
+---------------------
diff --git a/docs/customize-rootfs.txt b/docs/customize-rootfs.txt
new file mode 100644
index 000000000..b21b82209
--- /dev/null
+++ b/docs/customize-rootfs.txt
@@ -0,0 +1,23 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[rootfs-custom]]
+Customizing the generated target filesystem
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Besides changing one or another configuration through +make menuconfig+,
+there are is a way to customize the resulting target filesystem.
+
+Create a new directory called +extra+ in the top OpenADK directory.
+Put there a tree of directories and files that will be copied directly
+over the target filesystem (+root_*+) after everything is build, but
+before the firmware images or archives are created.
+
+You can also point to another directory via:
+---------------
+ $ make extra=/foo/bar
+---------------
+
+You can start with the example configuration files from +root_*+.
+The +extra+ directory will never be deleted by any clean target to avoid
+loss of customized configuration data.
diff --git a/docs/customize-store.txt b/docs/customize-store.txt
new file mode 100644
index 000000000..d0c209273
--- /dev/null
+++ b/docs/customize-store.txt
@@ -0,0 +1,14 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[customize-store]]
+Storing the configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When you have a OpenADK configuration that you are satisfied with and
+you want to share it with others, put it under revision control or move
+on to a different OpenADK project.
+
+You just need to copy your .config and extra directory to regenerate your
+firmware images on another system. The used config is, if not explicitely disabled,
+saved on the target in +/etc/adkconfig.gz+.
diff --git a/docs/customize-toolchain.txt b/docs/customize-toolchain.txt
new file mode 100644
index 000000000..8a14d4bbb
--- /dev/null
+++ b/docs/customize-toolchain.txt
@@ -0,0 +1,23 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[toolchain-custom]]
+Customizing the toolchain
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There is no simple way to change anything for the toolchain.
+OpenADK chooses the best combination of the toolchain components to
+provide you with a working and recent system.
+
+If you like to change the version of a component, add patches or like
+to change the configure options, you need to dig into the +toolchain+ directory.
+
+For example to change the version of gcc, you need to change +toolchain/gcc/Makefile.inc+.
+Be aware of the fact, that this is used for the +package/gcc/Makefile+ and therefore for
+the gcc running on your target.
+
+OpenADK supports running a cross-compiled toolchain on your target. You can even use OpenADK
+buildsystem on your target. There is a package collection called +development+, which does
+configure OpenADK to include all required software to use OpenADK on your target.
+
+
diff --git a/docs/customize.txt b/docs/customize.txt
new file mode 100644
index 000000000..81fe18e02
--- /dev/null
+++ b/docs/customize.txt
@@ -0,0 +1,19 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+Customization
+-------------
+
+include::customize-rootfs.txt[]
+
+include::customize-busybox-config.txt[]
+
+include::customize-libc-config.txt[]
+
+include::customize-kernel-config.txt[]
+
+include::customize-toolchain.txt[]
+
+include::customize-store.txt[]
+
+include::customize-outside-adk.txt[]
diff --git a/docs/debugging-openadk.txt b/docs/debugging-openadk.txt
new file mode 100644
index 000000000..ba48b273e
--- /dev/null
+++ b/docs/debugging-openadk.txt
@@ -0,0 +1,29 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[debugging-openadk]]
+
+Debugging OpenADK
+-----------------
+
+To analyze any build problems, use verbose output:
+
+----
+ $ make v
+----
+
+To analyze any inter package dependency problems, use make debug output:
+
+----
+ $ make --debug=b
+----
+
+If you have a problem with a specific package, use following command
+to capture the output and send it to the OpenADK developer:
+
+----
+ $ make package=<pkgname> clean package > pkgname.log 2>&1
+----
+
+
+
diff --git a/docs/developer-guide.txt b/docs/developer-guide.txt
new file mode 100644
index 000000000..d4975027a
--- /dev/null
+++ b/docs/developer-guide.txt
@@ -0,0 +1,13 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+Developer Guidelines
+====================
+
+include::writing-rules.txt[]
+
+include::adding-packages.txt[]
+
+include::patch-policy.txt[]
+
+include::debugging-openadk.txt[]
diff --git a/docs/download-location.txt b/docs/download-location.txt
new file mode 100644
index 000000000..50088b57a
--- /dev/null
+++ b/docs/download-location.txt
@@ -0,0 +1,26 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+Location of downloaded packages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The various tarballs that are downloaded by OpenADK are all stored
+in +ADK_DL_DIR+, which by default is the +dl+ directory. If you want
+to keep a complete version of OpenaDK which is known to be working
+with the associated tarballs, you can make a copy of this directory.
+This will allow you to regenerate the toolchain and the target
+filesystem with exactly the same versions.
+
+If you maintain several OpenADK trees, it might be better to have a
+shared download location. This can be achieved by pointing the
++DL_DIR+ environment variable to a directory. If this is
+set, then the value of +ADK_DL_DIR+ in the OpenADK configuration is
+overridden. The following line should be added to +<~/.bashrc>+.
+
+-----------------
+ $ export DL_DIR=<shared download location>
+-----------------
+
+The download location can also be set in the +.config+ file, with the
++ADK_DL_DIR+ option. Unlike most options in the .config file, this value
+is overridden by the +DL_DIR+ environment variable.
diff --git a/docs/faq-troubleshooting.txt b/docs/faq-troubleshooting.txt
new file mode 100644
index 000000000..84059b2f9
--- /dev/null
+++ b/docs/faq-troubleshooting.txt
@@ -0,0 +1,58 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+Frequently Asked Questions & Troubleshooting
+============================================
+
+[[faq-no-doc-on-target]]
+Why is there no documentation on the target?
+--------------------------------------------
+
+Because OpenADK mostly targets _small_ or _very small_ target
+hardware with limited resource onboard (CPU, ram, mass-storage), it
+does not make sense to waste space with the documentation data.
+
+If you need documentation data on your target anyway, then OpenADK
+is not suitable for your purpose, and you should look for a _real
+distribution_.
+
+[[faq-no-locale-on-target]]
+Why is there no locale support on the target?
+---------------------------------------------
+
+OpenADK tries to create a simple and small Linux system, which
+has no fancy features enabled. Locale support on a headless system,
+like a router is not useful anyway. To avoid bloat, it is a design
+decision to not have any locale support. Developers and users
+still could add any kind of user interface with internationalization
+features.
+
+[[faq-why-not-visible-package]]
+Why are some packages not visible in the OpenADK config menu?
+-------------------------------------------------------------
+
+If a package exists in the OpenADK tree and does not appear in the
+config menu, this most likely means that some of the package's
+dependencies are not met.
+
+To know more about the dependencies of a package, search for the
+package symbol in the config menu (see xref:make-tips[]).
+
+Then, you may have to recursively enable several options (which
+correspond to the unmet dependencies) to finally be able to select
+the package.
+
+If the package is not visible due to some unmet dependency to another
+C library, either consider to switch to another C library or fix the
+package so that it works with your configured library. For this you
+need to add your C library to PKG_LIBC_DEPENDS in +package/<pkgname>/Makefile+.
+
+[[faq-no-web-interface]]
+Why is there no web based configuration interface available?
+------------------------------------------------------------
+
+OpenADK provides a basic root filesystem for your embedded device.
+If you need a web based configuration interface for your own appliance,
+just write one. There are plenty of possibilities. You could use
+Lighttpd with PHP or an C++ application server like Tntnet.
+
diff --git a/docs/getting.txt b/docs/getting.txt
new file mode 100644
index 000000000..534ba99c9
--- /dev/null
+++ b/docs/getting.txt
@@ -0,0 +1,22 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[getting-openadk]]
+Getting OpenADK
+---------------
+
+OpenADK does not have any releases. Only direct Git
+access is possible.
+
+To download OpenADK using Git just do:
+
+---------------------
+ $ git clone git://openadk.org/git/openadk
+---------------------
+
+Or if you prefer HTTP or using Git behind a proxy:
+
+---------------------
+ $ git clone http://git.openadk.org/openadk.git
+---------------------
+
diff --git a/docs/going-further.txt b/docs/going-further.txt
new file mode 100644
index 000000000..2cabb62ed
--- /dev/null
+++ b/docs/going-further.txt
@@ -0,0 +1,9 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+Going further in OpenADK's innards
+====================================
+
+include::how-openadk-works.txt[]
+
+include::advanced.txt[]
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
diff --git a/docs/images/menuconfig-configured.png b/docs/images/menuconfig-configured.png
new file mode 100644
index 000000000..cad536cc9
--- /dev/null
+++ b/docs/images/menuconfig-configured.png
Binary files differ
diff --git a/docs/images/menuconfig.png b/docs/images/menuconfig.png
new file mode 100644
index 000000000..5624a2982
--- /dev/null
+++ b/docs/images/menuconfig.png
Binary files differ
diff --git a/docs/introduction.txt b/docs/introduction.txt
new file mode 100644
index 000000000..991747672
--- /dev/null
+++ b/docs/introduction.txt
@@ -0,0 +1,26 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+About OpenADK
+=============
+
+OpenADK is a tool that simplifies and automates the process of
+building a complete Linux system for an embedded system, using
+cross-compilation. ADK stands for appliance development kit.
+
+In order to achieve this, OpenADK is able to generate a
+cross-compilation toolchain, a root filesystem, a Linux kernel image
+and a bootloader for your target.
+
+OpenADK is useful mainly for people working with embedded systems,
+but can be used by people playing with emulators (like Qemu, Virtualbox
+or Aranym) or small netbooks (like Lemote Yeelong) needing a fast
+and small Linux system.
+
+Embedded systems often use processors that are not the regular x86
+processors everyone is used to having in his PC. They can be PowerPC
+processors, MIPS processors, ARM processors, etc.
+
+OpenADK supports numerous processors and their variants; it also comes
+with default configurations for some embedded systems and netbooks.
+(Raspberry PI, Sharp Zaurus, Lemote Yeelong, IBM X40 and more)
diff --git a/docs/legal-notice.txt b/docs/legal-notice.txt
new file mode 100644
index 000000000..6b1546ef0
--- /dev/null
+++ b/docs/legal-notice.txt
@@ -0,0 +1,51 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[legal-info]]
+
+Legal notice and licensing
+==========================
+
+Complying with open source licenses
+-----------------------------------
+
+All of the end products of OpenADK (toolchain, root filesystem, kernel,
+bootloaders) contain open source software, released under various licenses.
+
+Using open source software gives you the freedom to build rich embedded
+systems, choosing from a wide range of packages, but also imposes some
+obligations that you must know and honour.
+Some licenses require you to publish the license text in the documentation of
+your product. Others require you to redistribute the source code of the
+software to those that receive your product.
+
+The exact requirements of each license are documented in each package, and
+it is your responsibility (or that of your legal office) to comply with those
+requirements.
+
+Complying with the OpenADK license
+----------------------------------
+
+OpenADK itself is an open source software, released under the
+http://www.gnu.org/licenses/old-licenses/gpl-2.0.html[GNU General Public
+License, version 2] or (at your option) any later version.
+However, being a build system, it is not normally part of the end product:
+if you develop the root filesystem, kernel, bootloader or toolchain for a
+device, the code of OpenADK is only present on the development machine, not
+in the device storage.
+
+Nevertheless, the general view of the OpenADK developer is that you should
+release the OpenADK source code along with the source code of other packages
+when releasing a product that contains GPL-licensed software.
+This is because the
+http://www.gnu.org/licenses/old-licenses/gpl-2.0.html[GNU GPL]
+defines the "'complete source code'" for an executable work as "'all the
+source code for all modules it contains, plus any associated interface
+definition files, plus the scripts used to control compilation and installation
+of the executable'".
+OpenADK is part of the 'scripts used to control compilation and
+installation of the executable', and as such it is considered part of the
+material that must be redistributed.
+
+Keep in mind that this is only the OpenADK developer opinion, and you
+should consult your legal department or lawyer in case of any doubt.
diff --git a/docs/make-tips.txt b/docs/make-tips.txt
new file mode 100644
index 000000000..787121cb4
--- /dev/null
+++ b/docs/make-tips.txt
@@ -0,0 +1,99 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[make-tips]]
+'make' tips
+-----------
+
+This is a collection of tips that help you make the most of OpenADK.
+
+.Configuration searches:
+
+The +make menuconfig+ command offer a search tool.
+The search tool is called by pressing +/+;
+The result of the search shows the help message of the matching items.
+
+.Display all commands executed by make:
+
+--------------------
+ $ make v
+--------------------
+
+or
+
+--------------------
+ $ make VERBOSE=1 <target>
+--------------------
+
+.Display all available targets:
+
+--------------------
+ $ make help
+--------------------
+
+.Cleaning:
+
+There are different cleaning targets available. If a full clean is
+necessary, you normally will get a message from OpenADK.
+To delete all build products (including build directories, target, host
+and pkg trees, the firmware and the toolchain for all targets):
+
+--------------------
+ $ make cleandir
+--------------------
+
+If you only want to clean your specific configured target, just use:
+
+--------------------
+ $ make cleantarget
+--------------------
+
+If you even want to clean any downloaded source:
+
+--------------------
+ $ make distclean
+--------------------
+
+If you only want to clean the kernel build, because you added or
+removed some patch, just do:
+
+--------------------
+ $ make cleankernel
+--------------------
+
+This is automatically triggered if you change the kernel version in
+your configuration.
+
+If you just want to clean all packages and wants to rebuild the firmware,
+(the tools/toolchain is not deleted) just use:
+
+--------------------
+ $ make clean
+--------------------
+
+.Resetting OpenADK for a new target:
+
+You can either delete the configuration and start from scratch:
+
+--------------------
+ $ rm .config*
+ $ make menuconfig
+--------------------
+
+Or you can save your existing configuration and switch to a new
+one with:
+
+--------------------
+ $ make switch
+--------------------
+
+Afterwards you can switch back to your old configuration, you just
+need to remember, which architecture and system you had configured:
+
+--------------------
+ $ make switch ARCH=<arch> SYSTEM=<system>
+--------------------
+
+OpenADK is designed to have multiple architectures and embedded system
+combinations configured and build without a need to rebuild everything
+from scratch. There is no limit, you just need to have enough disk space.
diff --git a/docs/manual.txt b/docs/manual.txt
new file mode 100644
index 000000000..38700e45c
--- /dev/null
+++ b/docs/manual.txt
@@ -0,0 +1,33 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+The OpenADK user manual
+=======================
+:toc:
+
+OpenADK usage and documentation by Waldemar Brodkorb.
+
+(based on the buildroot manual by Thomas Petazzoni. Contributions from Karsten Kruse, Ned Ludd, Martin Herren and others.
+See http://www.buildroot.net for the original text).
+
+:leveloffset: 1
+
+include::introduction.txt[]
+
+include::starting-up.txt[]
+
+include::working-with.txt[]
+
+include::faq-troubleshooting.txt[]
+
+include::running-openadk.txt[]
+
+include::going-further.txt[]
+
+include::developer-guide.txt[]
+
+include::legal-notice.txt[]
+
+include::contribute.txt[]
+
+include::appendix.txt[]
diff --git a/docs/network-configuration.txt b/docs/network-configuration.txt
new file mode 100644
index 000000000..ea869c0bc
--- /dev/null
+++ b/docs/network-configuration.txt
@@ -0,0 +1,182 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[network-configuration]]
+Network configuration
+~~~~~~~~~~~~~~~~~~~~~
+
+loopback devices
+^^^^^^^^^^^^^^^^
+
+Example for loopback device configuration:
+
+---------------------
+auto lo
+iface lo inet loopback
+---------------------
+
+static network configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Example for an ethernet network card:
+
+---------------------
+auto eth0
+iface eth0 inet static
+ address 192.168.1.1
+ netmask 255.255.255.0
+ broadcast +
+ gateway 192.168.1.254
+---------------------
+
+The DNS resolver must be manually configured in /etc/resolv.conf.
+The plus for the broadcast value, will calculate the correct broadcast address for the network.
+
+dynamic network configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Example for an ethernet network card:
+
+---------------------
+auto eth0
+iface eth0 inet dhcp
+---------------------
+
+bridge configuration
+^^^^^^^^^^^^^^^^^^^^
+
+Example for a network bridge with two ethernet network interfaces and an ip address:
+
+---------------------
+auto br0
+iface br0 inet static
+ address 192.168.99.1
+ netmask 255.255.255.0
+ broadcast +
+ bridge-ports eth0 eth1
+---------------------
+
+Just a bridge without an ip address:
+---------------------
+auto br0
+iface br0 inet manual
+ bridge-ports eth0 eth1
+---------------------
+
+You need to install either Busybox brctl applet or the bridge-utils package. The required kernel modules will be automatically selected.
+
+VLAN network interfaces
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Example configuration of a network interface with VLAN ID 8 without any ip configuration:
+
+---------------------
+auto eth0.8
+iface eth0.8 inet manual
+---------------------
+
+You need to install Busybox vconfig applet. The required kernel modules will be automatically selected.
+
+PPP over Ethernet
+^^^^^^^^^^^^^^^^^
+
+Typical DSL configuration:
+
+---------------------
+auto ppp0
+iface ppp0 inet ppp
+ use-template pppoe
+ provider isp
+ ppp-mtu 1412
+ ppp-username foo
+ ppp-password bar
+ ppp-device eth1
+---------------------
+
+The provider can be used as argument for "pon" and "poff" commands.
+You need to install the ppp and ppp-mod-pppoe package. The required kernel modules will be automatically selected.
+
+wireless client configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Example wireless client configuration, secured with WPA2:
+
+---------------------
+auto wlan0
+iface wlan0 inet dhcp
+ wireless-ssid myap
+ wireless-channel 11
+ wireless-mode sta
+ wireless-security wpa2
+ wireless-passphrase xxxxxx
+---------------------
+
+You need to install iw and wpa_supplicant packages. For older wireless drivers you
+need to install wireless-tools instead of iw and use the following variable to choose the right tools:
+
+---------------------
+wireless-extension 1
+---------------------
+
+wireless accesspoint configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To configure an access point use following example:
+
+---------------------
+auto wlan0
+iface wlan0 inet static
+ address 192.168.40.10
+ netmask 255.255.255.0
+ broadcast +
+ wireless-ssid myap
+ wireless-channel 8
+ wireless-mode ap
+ wireless-security wpa2
+ wireless-passphrase xxxxxx
+---------------------
+
+You need to install hostapd and iw/wireless-tools packages.
+
+hso umts modem
+^^^^^^^^^^^^^^
+
+If you have a HSO UMTS modem, you can use following to configure internet access:
+---------------------
+auto hso0
+iface hso0 inet manual
+ pin 1234
+ apn your.apn
+---------------------
+
+ATM configuration
+^^^^^^^^^^^^^^^^^
+
+For example a configuration on a Linksys AG241 router with integrated DSL modem,
+you can configure two ATM devices to distinguish between Internet and IPTV traffic:
+
+---------------------
+auto eth0.1
+iface eth0.1 inet manual
+
+auto eth0.8
+iface eth0.8 inet manual
+
+auto nas0
+iface nas0 inet manual
+
+auto nas1
+iface nas1 inet manual
+ atm-vpi 1
+ atm-vci 34
+
+auto br0
+iface br0 inet manual
+ bridge-ports eth0.1 nas0
+
+auto br1
+iface br1 inet manual
+ bridge-ports eth0.8 nas1
+---------------------
+
+More network setups can be implemented on request.
diff --git a/docs/package-make-target.txt b/docs/package-make-target.txt
new file mode 100644
index 000000000..13c498062
--- /dev/null
+++ b/docs/package-make-target.txt
@@ -0,0 +1,52 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[pkg-build-steps]]
+
+Package-specific _make_ targets
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Running +make package=<package> package+ builds and installs that particular package.
+Be aware of the fact, that no build dependencies are resolved using this method!
+
+For packages relying on the OpenADK infrastructure, there are
+numerous special make targets that can be called independently like
+this:
+
+------------
+ $ make package=<package> <target>
+------------
+
+The package build targets are (in the order they are executed):
+
+[width="90%",cols="^1,4",options="header"]
+|===================================================
+| command/target | Description
+
+| +fetch+ | Fetch the source
+
+| +extract+ | Put the source in the package build directory
+
+| +patch+ | Apply the patches, if any
+
+| +configure+ | Run the configure commands, if any
+
+| +build+ | Run the compilation commands
+
+| +fake+ | Run the installation of the package into a fake directory
+
+| +package+ | Create a package or tar archive of the package files
+
+|===================================================
+
+Additionally, there are some other useful make targets:
+
+[width="90%",cols="^1,4",options="header"]
+|===================================================
+| command/target | Description
+
+| +clean+ | Remove the whole package build directory
+
+| +host-package+ | Build and install the host binaries and libraries
+
+|===================================================
diff --git a/docs/package-reference.txt b/docs/package-reference.txt
new file mode 100644
index 000000000..650694bf2
--- /dev/null
+++ b/docs/package-reference.txt
@@ -0,0 +1,135 @@
+[[package-reference]]
+
++package+ Reference
+~~~~~~~~~~~~~~~~~~~
+
+The list of variables that can be set in a +Makefile+ to give metadata
+information is:
+
+* +PKG_NAME+, mandatory, must contain the name of the package.
+
+* +PKG_VERSION+, mandatory, must contain the version of the package.
+
+* +PKG_RELEASE+, mandatory, must contain the OpenADK specific release of the package.
+
+* +PKG_MD5SUM+, mandatory, must contain the MD5 hash of the package, will be used
+ to check if a download of a package is complete.
+
+* +PKG_SECTION+, mandatory, must contain the OpenADK specific section, see package/section.lst.
+
+* +PKG_RELEASE+, mandatory, must contain an one line summary of the package description.
+
+* +PKG_URL+, optional, may contain the url to the homepage of the package
+
+* +PKG_SITES+, mandatory, must contain the download url for the package, multiple entries
+ with space separated, are allowed. Only HTTP/HTTPS or FTP URLS are allowed.
+ A backup site (http://www.openadk.org/distfiles) is always used, if the package site is
+ not available. There is no direct support for cvs/svn/git/hg/bzr repositories, because
+ building OpenADK behind a HTTP proxy should be working without any configuration hassle.
+ There are also some predefined mirror sites in +mk/mirrors.mk+,
+ which can be used.
+ Example: PKG_SITES:= ${MASTER_SITE_GNU:=foo/}
+
+* +DISTFILES+ optional, may contain the name of the tarball of
+ the package. If +DISTFILES+ is not specified, it defaults to +PKG_NAME-PKG_VERSION.tar.gz+.
+ Example: DISTFILES= ${PKG_NAME}${PKG_VERSION}.tar.xz
+
+* +NO_DISTFILES+ optional, may be set to 1, to disable fetching of any archives.
+ Provide the source code for the package in +package/<pkgname>/src+, which will be
+ automatically copied to the WRKBUILD/WRKSRC directory.
+
+* +PKG_BUILDDEP+ optional, lists the build time dependencies (in terms of package
+ directory name, see +package/+) that are required for the current target package to
+ compile. These dependencies are guaranteed to be compiled and
+ installed before the configuration of the current package starts.
+
+* +PKG_DEPENDS+ optional, lists the runtime dependencies that are required to
+ run the software package on the target. It conatins a list of package names,
+ which might be different to the package directory name. See what is used
+ in PKG_template, to find out the package name used here.
+
+* +PKG_NOPARALLEL+ optional, may be set to 1, to disable parallel building of the
+ package via make -jn, n=4 is default, but can be changed in +Global Settings+ in the
+ menu based configuration.
+
+* +PKG_OPTS+ optional, may be set to following values:
+ +dev+ create a development package automatically, containing header files and +.pc+ files.
+ Only useful for library packages, when you want to compile on the target.
+ +devonly+ only creates a development package with header files, normally not needed on
+ the target.
+ +noscripts+ do not automatically install *-config and other build related scripts into
+ +STAGING_TARGET_DIR/scripts+, required for automake/autoconf package
+ +noremove+ do not automatically remove package files from +STAGING_TARGET_DIR+
+
+* +PKG_NEED_CXX+ optional, package need C++ compiler
+
+* +PKG_CXX+ optional, package can use either `uClibc++` or `libstdc++`
+
+The recommended way to define these variables is to use the following
+syntax:
+
+----------------------
+PKG_VERSION:= 2.11
+----------------------
+
+Or for lines longer than 80 characters use:
+----------------------
+PKG_DEPENDS:= foo bar baz
+PKG_DEPENDS+= muh maeh
+----------------------
+
+
+The variables that define what should be performed at the
+different steps of the configure, build and install process.
+
+* +CONFIG_STYLE+ either manual, auto or minimal
+
+* +CONFIGURE_ARGS+ add --enable-foo/--disable-foo to configure
+
+* +CONFIGURE_ENV+ add additional environment variables to configure step
+
+* +HOST_STYLE+ either manual or auto
+
+* +HOST_CONFIGURE_ARGS+ add --enable-foo/--disable-foo to host configure
+
+* +HOST_CONFIGURE_ENV+ add additional environment variables to the host configure step
+
+* +AUTOTOOL_STYLE+ either autoreconf, autoconf or bootstrap
+
+* +BUILD_STYLE+ either manual or auto
+
+* +MAKE_ENV+ add additional variables to build step
+
+* +MAKE_FLAGS+ add additinal make flags to build step
+
+* +FAKE_FLAGS+ add additional make flags to fake install step
+
+* +XAKE_FLAGS+ add additional make flags to build and fake install step
+
+* +INSTALL_STYLE+ either manual or auto
+
+* +CONFIGURE_PROG+ overwrite default configure programm
+
+* +MAKE_FILE+ overwrite default Makefile
+
+* +ALL_TARGET+ overwrite default build target
+
+* +INSTALL_TARGET+ overwrite default install target
+
+The variables to add or overwrite preprocessor, compiler and linker flags:
+
+* +TARGET_CPPFLAGS+ flags for the preprocessor
+
+* +TARGET_CFLAGS+ flags for the compiler
+
+* +TARGET_LDFLAGS+ flags for the linker
+
+* +TARGET_CXXFLAGS+ flags for the C++ compiler
+
+* +CPPFLAGS_FOR_BUILD+ flags used for host preprocessing
+
+* +CFLAGS_FOR_BUILD+ flags used for host compiling
+
+* +LDFLAGS_FOR_BUILD+ flags used for host linking
+
+
diff --git a/docs/patch-policy.txt b/docs/patch-policy.txt
new file mode 100644
index 000000000..b5a585b5e
--- /dev/null
+++ b/docs/patch-policy.txt
@@ -0,0 +1,82 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[patch-policy]]
+
+Patching a package
+------------------
+
+While integrating a new package or updating an existing one, it may be
+necessary to patch the source of the software to get it cross-built within
+OpenADK. OpenADK offers an infrastructure to automatically handle this during
+the builds. Patches are provided within OpenADK, in the package directory;
+these typically aim to fix cross-compilation, libc support, or other such
+issues.
+
+Normally the patches are autogenerated via:
+------------
+ $ make package=<package> update-patches
+------------
+
+Otherwise they are manually generated via:
+------------
+ $ diff -Nur <pkgname>-<pkgversion>.orig <pkgname>-<pkgversion> > package/<pkgname>/patches/xxx-description.patch
+------------
+
+The string +xxx+ should be substituted by a number starting with 001. The
+patches will be applied in numeric order. You should either use the automatic
+patch generation or the manual patch creation for a package. Mixed usage is not
+supported.
+
+Format and licensing of the package patches
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Patches are released under the same license as the software that is
+modified.
+
+A message explaining what the patch does, and why it is needed, should
+be added in the header commentary of the patch.
+At the end, the patch should look like:
+
+---------------
+add C++ support test
+
+--- configure.ac.orig
++++ configure.ac
+@@ -40,2 +40,12 @@
+
+AC_PROG_MAKE_SET
++
++AC_CACHE_CHECK([whether the C++ compiler works],
++ [rw_cv_prog_cxx_works],
++ [AC_LANG_PUSH([C++])
++ AC_LINK_IFELSE([AC_LANG_PROGRAM([], [])],
++ [rw_cv_prog_cxx_works=yes],
++ [rw_cv_prog_cxx_works=no])
++ AC_LANG_POP([C++])])
++
++AM_CONDITIONAL([CXX_WORKS], [test "x$rw_cv_prog_cxx_works" = "xyes"])
+---------------
+
+Integrating patches found on the Web
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When integrating a patch of which you are not the author, you have to
+add a few things in the header of the patch itself.
+
+Depending on whether the patch has been obtained from the project
+repository itself, or from somewhere on the web, add one of the
+following tags:
+
+---------------
+Backported from: <some commit id>
+---------------
+
+or
+
+---------------
+Fetch from: <some url>
+---------------
+
+It is also sensible to add a few words about any changes to the patch
+that may have been necessary.
diff --git a/docs/prerequisite.txt b/docs/prerequisite.txt
new file mode 100644
index 000000000..8a9670066
--- /dev/null
+++ b/docs/prerequisite.txt
@@ -0,0 +1,52 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[requirement]]
+System requirements
+-------------------
+
+OpenADK is designed to run on Linux systems. But there is basic
+support to run on MacOS X Maverick, Windows 7 with Cygwin, OpenBSD,
+NetBSD and FreeBSD. Main development happens on Debian/GNU Linux 7
+and MacOS X Maverick. The other host platforms are occasionally
+tested.
+
+OpenADK detects the host system and displays only the software
+packages, which are known to be cross-compilable on the used host.
+For example OpenJDK7 is only cross-compilable on a Linux host.
+
+OpenADK needs some software to be already installed on the host
+system; here is the list of the mandatory packages,
+package names may vary between host systems.
+
+* Build tools:
+
+** +bash+
+** +binutils+
+** +gcc+
+** `g++`
+** +GNU sed+
+** +GNU awk+
+** +GNU make+
+** +patch+
+** +gzip+
+** +perl+
+** +tar+
+** +wget+
+** +findutils (find, xargs)+
+** +ncurses5 development+
+** +zlib development+
+** +libc development+
+
+There is a check for the required versions of these tools in advance,
+though. To re-issue the checks, use +make prereq+.
+
+For some packages there are some optional packages required. OpenADK
+will check for the required tools in advance, when a specific package is
+choosen. For example XBMC needs java installed on the host system.
+OpenADK tries to avoid any optional required host tools and will try to
+build them when needed.
+
+For some host systems you can try to use ./scripts/adkprepare.sh to
+install all required software. You need to run the script as root, it
+will use the package management of your host to install the software.
diff --git a/docs/qemu.txt b/docs/qemu.txt
new file mode 100644
index 000000000..976490bf3
--- /dev/null
+++ b/docs/qemu.txt
@@ -0,0 +1 @@
+user,hostfwd=tcp::2222-:22
diff --git a/docs/running-openadk.txt b/docs/running-openadk.txt
new file mode 100644
index 000000000..c4ae0fa72
--- /dev/null
+++ b/docs/running-openadk.txt
@@ -0,0 +1,178 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+Running OpenADK created Linux firmware
+======================================
+
+Bootloader
+~~~~~~~~~~~
+
+The Bootloader is used to initialize the machine and load the Linux kernel.
+A list of popular Bootloaders can be found on http://elinux.org/Bootloader.
+OpenADK provides the Bootloader if necessary for a target system.
+You can find them in +make menuconfg+ under +Packages/Bootloader+.
+Some Bootloaders require the Linux kernel in a special format (SREC, ELF, ..),
+compressed or with a special header. This will be automatically done by
+OpenADK in +target/<arch>/Makefile+ while creating the firmware archives or
+images.
+
+Linux kernel
+~~~~~~~~~~~~
+
+The kernel is a program that constitutes the central core of a computer
+operating system. It has complete control over everything that occurs in the
+system. The Bootloader can provide some basic runtime configuration
+parameters via the kernel commandline feature.
+
+The Linux kernel in OpenADK is intended to be very small in size and will
+be by default compressed with xz compression algorithm, if available for
+the target system. You can configure the compression algorithm used for the
+compression of the Linux kernel and if choosen the initramfs filesystem in
++make menuconfig+. In +Kernel configuration+ you have the choice between
+dfferent kernel versions. The latest version will be automatically used.
+There you can choose any needed addon drivers or any supported runtime
+and debugging features.
+
+The kernel expands itself on boot, if compressed, and then initialize the
+hardware. The additional kernel modules are loaded later by a init script.
+The kernel will autoamtically mount the virtual filesystem /dev as devtmpfs
+and then will execute +/sbin/init+ in userspace.
+
+init system
+~~~~~~~~~~~
+
+The _init_ program is the first userspace program started by the kernel (it
+carries the PID number 1), and is responsible for starting the userspace
+services and programs (for example: web server, graphical applications, other
+network servers, etc.).
+
+OpenADK uses *Busybox* init. Amongst many programs, Busybox has an
+implementation of a basic +init+ program, which is sufficient for most embedded
+systems. The Busybox +init+ program will read the +/etc/inittab+ file at boot
+to know what to do. The syntax of this file can be found in
+http://git.busybox.net/busybox/tree/examples/inittab (note that Busybox
++inittab+ syntax is special: do not use a random +inittab+ documentation from
+the Internet to learn about Busybox +inittab+). The default +inittab+ in
+OpenADK is generated while producing the +base-files+ package. The main job
+the default inittab does is to start the +/etc/init.d/rcS+ shell script, and
+start one or more +getty+ programs (which provides a login prompt).
+
+/dev management
+~~~~~~~~~~~~~~~
+
+On a Linux system, the +/dev+ directory contains special files, called
+_device files_, that allow userspace applications to access the
+hardware devices managed by the Linux kernel. Without these _device
+files_, your userspace applications would not be able to use the
+hardware devices, even if they are properly recognized by the Linux
+kernel.
+
+OpenADK uses *dynamic device nodes using devtmpfs and mdev*. This method relies
+on the _devtmpfs_ virtual filesystem in the kernel, which is enabled by default
+for all OpenADK generated kernels, and adds the +mdev+ userspace utility on top
+of it. +mdev+ is a program part of Busybox that the kernel will call every time
+a device is added or removed. Thanks to the +/etc/mdev.conf+ configuration
+file, +mdev+ can be configured to for example, set specific permissions or
+ownership on a device file, call a script or application whenever a device
+appears or disappear, etc. Basically, it allows _userspace_ to react on device
+addition and removal events. +mdev+ is also important if you have devices that
+require a firmware, as it will be responsible for pushing the firmware contents
+to the kernel. +mdev+ is a lightweight implementation (with fewer features) of
++udev+. For more details about +mdev+ and the syntax of its configuration file,
+see http://git.busybox.net/busybox/tree/docs/mdev.txt.
+
+initscripts
+~~~~~~~~~~~
+
+The /etc/init.d/rcS script will execute all shell scripts in /etc/init.d in
+order with the parameter +autostart+. The order is identified by the +#INIT+
+comment in the script. All scripts are sourcing the +/etc/rc.conf+ file to
+determine if a service should be started on boot and which flags if any are
+used for the service. By default all services except syslog and ssh are
+disabled. Most scripts provided by OpenADK via
++package/<pkgname>/files/<pkgname>.init+ are like:
+
+---------------------
+#!/bin/sh
+#PKG foo
+#INIT 60
+
+. /etc/rc.conf
+
+case $1 in
+autostop) ;;
+autostart)
+ test x"${foo:-NO}" = x"NO" && exit 0
+ exec sh $0 start
+ ;;
+start)
+ /usr/sbin/foo $foo_flags
+ ;;
+stop)
+ kill $(pgrep -f /usr/sbin/foo )
+ ;;
+restart)
+ sh $0 stop
+ sh $0 start
+ ;;
+*)
+ echo "usage: $0 (start|stop|restart)"
+ exit 1
+esac
+exit $?
+---------------------
+
+cfgfs - configuration file system
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The cfgfs application for the OpenADK system uses a special small partition on
+the block device of your embedded system (f.e. flash, sd card, compact flash
+or hard disk). Only changes made to /etc on your embedded system are saved in a
+compressed form (using LZO1 compression algorithm) in this partition. There is
+no Linux filesystem on this partition. The embedded system initialization
+process will setup /etc correctly on boot up, when cfgfs application is found.
+After making any changes to /etc, which should survive a reboot of the embedded
+system must be written to the cfgfs partition via “cfgfs commit”. Trying to
+reboot, shutdown or halt an embedded system with unsaved changes will generate
+an error, which can be circumvented. Updates to /etc via the ipkg package
+manager will be reported.
+
+---------------------
+cfgfs
+Configuration Filesystem Utility (cfgfs), Version 1.09
+Syntax:
+ /sbin/cfgfs commit [-f]
+ /sbin/cfgfs erase
+ /sbin/cfgfs setup [-N]
+ /sbin/cfgfs status [-rq]
+ /sbin/cfgfs { dump | restore } [<filename>]
+---------------------
+
+network configuration
+~~~~~~~~~~~~~~~~~~~~~
+
+On bootup +/etc/network/interfaces+ is used to find out which network configuration
+should be used. The default is to use DHCP (via busybox +udhcpc+) on the first found
+ethernet device to configure the network. See network configuration for detailed syntax
+of +/etc/network/interfaces+. It is similar to Debian network configuration and uses
++ifupdown+ from +busybox+.
+
+See Appendix xref:network-configuration[]
+
+getting a shell on the system
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are two method available to get a shell on your embedded system created with
+OpenADK. You can either login locally via serial console or graphical console or you
+can login remotely via secure shell.
+
+In both cases the default user is +root+ and the default password is
++linux123+. *You should always change the default password!!* You can do this
+either via +passwd+ on the system or you can preconfigure a password via +make
+menuconfig+ under +Runtime configuration+.
+
+The default shell used in OpenADK is +mksh+ from http://www.mirbsd.org/mksh/.
+You can change the shell in +make menuconfig+ under +Runtime configuration+. Be
+aware of the fact that the bootup process might use some +mksh+ features to
+speedup the system start. When you change the shell for system +/bin/sh+ the
+slower startup is used as a fallback.
diff --git a/docs/runtime-debugging.txt b/docs/runtime-debugging.txt
new file mode 100644
index 000000000..5147883f9
--- /dev/null
+++ b/docs/runtime-debugging.txt
@@ -0,0 +1,22 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+[[runtime-debugging]]
+
+Details on debugging your newly created firmware
+------------------------------------------------
+
+strace
+~~~~~~
+
+gdbserver
+~~~~~~~~~
+
+gdb
+~~~
+
+kernel module debugging
+~~~~~~~~~~~~~~~~~~~~~~~
+
+kernel debugging
+~~~~~~~~~~~~~~~~
diff --git a/docs/starting-up.txt b/docs/starting-up.txt
new file mode 100644
index 000000000..7326f60c7
--- /dev/null
+++ b/docs/starting-up.txt
@@ -0,0 +1,12 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+Starting up
+===========
+
+include::prerequisite.txt[]
+
+include::getting.txt[]
+
+include::using.txt[]
+
diff --git a/docs/using-openadk-development.txt b/docs/using-openadk-development.txt
new file mode 100644
index 000000000..d7d31fbad
--- /dev/null
+++ b/docs/using-openadk-development.txt
@@ -0,0 +1,62 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+Using OpenADK during development
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The normal operation of OpenADK is to download a tarball, extract it,
+configure, compile and install the software component found inside this
+tarball. The source code is extracted in
++build_<system>_<arch>_<libc>/w-<package>-<version>+, which is a
+temporary directory: whenever +make clean+ or one of the other clean
+targets are used, this directory is entirely removed, and recreated at
+the next +make+ invocation.
+
+This behavior is well-suited when OpenADK is used mainly as an
+integration tool, to build and integrate all the components of an
+embedded Linux system. However, if one uses OpenADK during the
+development of certain components of the system, this behavior is not
+very convenient: one would instead like to make a small change to the
+source code of one package, and be able to quickly rebuild the system
+with OpenADK.
+
+Following workflow might help to integrate your own changes, while
+developing a new package or board support.
+
+Make changes directly in +build_<system>_<arch>_<libc>/w-<package>-<version>+
+and recompile the package with:
+
+------------
+ $ make package=<package> package
+------------
+
+When you are happy with the change, generate a patch:
+------------
+ $ make package=<package> update-patches
+------------
+
+For the linux kernel just change the code in
++build_<system>_<arch>_<libc>/linux, remove the .config
+and call make again:
+
+------------
+ $ rm build_<system>_<arch>_<libc>/linux/.config
+ $ make
+------------
+
+There is no update-patches target for the kernel, you need
+to extract the kernel source from your download dir, make
+a copy of the source tree, add your changes and create a
+patch manually:
+
+------------
+ $ tar xvf dl/linux-x.y.z.tar.xz
+ $ cp -a linux-x.y.z linux-x.y.z.orig
+ $ diff -Nur linux-x.y.z.orig linux-x.y.z > target/linux/patches/x.y.z/mykernel.patch
+ $ make cleankernel
+ $ make
+------------
+
+The same method can be used for toolchain components and _must_
+be used for busybox, because it contains patches, which are not
+generated via +make update-patches+.
diff --git a/docs/using-openadk-toolchain.txt b/docs/using-openadk-toolchain.txt
new file mode 100644
index 000000000..1b294d4da
--- /dev/null
+++ b/docs/using-openadk-toolchain.txt
@@ -0,0 +1,19 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+Using the generated toolchain outside OpenADK
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You may want to compile, for your target, your own programs or other software
+that are not packaged in OpenADK. In order to do this you can use the toolchain
+that was generated by OpenADK.
+
+The toolchain generated by OpenADK is located by default in
++host_<gnu_host_name>/+. The simplest way to use it is to add
++host_<gnu_host_name>/bin/+ to your PATH environment variable and then to use
++<arch>-<vendor>-linux-<libcsuffix>-gcc+,
++<arch>-<vendor>-linux-<libcsuffix>-objdump+, etc.
+
+It is possible to relocate the toolchain, you just need to put
++target_<arch>_<libc>_<abi>+ into the same directory as
++host_<gnu_host_name>/+.
diff --git a/docs/using.txt b/docs/using.txt
new file mode 100644
index 000000000..c51914c04
--- /dev/null
+++ b/docs/using.txt
@@ -0,0 +1,99 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+Using OpenADK
+-------------
+
+OpenADK has a nice configuration tool similar to the one you can
+find in the http://www.kernel.org/[Linux kernel] or in
+http://www.busybox.net/[Busybox]. Note that you can *and should build
+everything as a normal user*. There is no need to be root to configure
+and use OpenADK. The first step is to run the configuration
+assistant:
+
+--------------------
+ $ make menuconfig
+--------------------
+
+For each menu entry in the configuration tool, you can find associated
+help that describes the purpose of the entry.
+
+image::menuconfig.png[]
+
+First of all you need to choose your target architecture, your target
+system, your target C library, your target firmware type and your target
+package format. After that you can select individual packages and kernel
+settings or just use one of the predefined package collections. When you
+are ready exit and save. You can always redefine the configuration
+using +make menuconfig+.
+
+image::menuconfig-configured.png[]
+
+Once everything is configured, the configuration tool generates a
++.config+ file that contains the description of your configuration. It
+will be used by the Makefiles to do what's needed.
+
+Let's go:
+
+--------------------
+ $ make
+--------------------
+
+You *should never* use +make -jN+ with OpenADK: it does not support 'top-level
+parallel make'. Instead, use the +ADK_MAKE_JOBS+ option in +Global settings+ to
+tell OpenADK to run each package compilation with +make -jN+.
+
+The `make` command will generally perform the following steps:
+
+* download source files (as required);
+* configure, build and install required host tools;
+* configure, build and install the cross-compiling toolchain;
+* build a kernel image, if selected;
+* build/install selected target packages;
+* build a bootloader, if selected;
+* create a root filesystem in selected format.
+
+OpenADK output is stored in several subdirectories:
+
+* +firmware/+ where all the images and packages are stored.
+
+* +build_<system>_<arch>_<libc>/+ where all the components except for the cross-compilation toolchain are built. The directory contains one subdirectory for each of these components.
+
+* +target_<arch>_<libc>/+ which contains a hierarchy similar to a root filesystem
+ hierarchy. This directory contains the installation of the
+ cross-compilation toolchain and all the userspace packages selected
+ for the target. However, this directory is 'not' intended to be
+ the root filesystem for the target: it contains a lot of development
+ files, unstripped binaries and libraries that make it far too big
+ for an embedded system. These development files are used to compile
+ libraries and applications for the target that depend on other
+ libraries.
+
+* +root_<system>_<arch>_<libc>/+ which contains the complete root filesystem for
+ the target. One exception, it doesn't have the correct
+ permissions (e.g. setuid for the busybox binary) for some files.
+ Therefore, this directory *should not be used on your target*.
+ Instead, you should use one of the images or archives built in the
+ +firmware/+ directory. If you need an
+ extracted image of the root filesystem for booting over NFS, then
+ use the tarball image generated in +firmware/+ and extract it as
+ root. Compared to +build_*/+, +target_*/+ contains only the files and
+ libraries needed to run the selected target applications: the
+ development files are (exception: if any dev packages are selected)
+ not present, the binaries are stripped.
+
+* +host_<gnu_host_name>/+ contains the installation of tools compiled for the host
+ that are needed for the proper execution of OpenADK, including the
+ cross-compilation toolchain.
+
+* +toolchain_build_<arch>_<libc>/+ contains the build directories for the various
+ components of the cross-compilation toolchain.
+
+* +pkg_<system>_<arch>_<libc>/+ contains stamp files and file lists for the various components.
+
+The command, +make menuconfig+ and +make+, are the
+basic ones that allow to easily and quickly generate images fitting
+your needs, with all the supports and applications you enabled.
+
+More details about the "make" command usage are given in
+xref:make-tips[].
diff --git a/docs/working-with.txt b/docs/working-with.txt
new file mode 100644
index 000000000..9e101d28f
--- /dev/null
+++ b/docs/working-with.txt
@@ -0,0 +1,25 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+Working with OpenADK
+====================
+
+This section explains how you can customize OpenADK to fit your
+needs.
+
+include::configure.txt[]
+
+include::make-tips.txt[]
+
+include::customize.txt[]
+
+include::common-usage.txt[]
+
+Hacking OpenADK
+---------------
+
+If OpenADK does not yet fit all your requirements, you may be
+interested in hacking it to add:
+
+* new packages: refer to the xref:adding-packages[Developer guide]
+
diff --git a/docs/writing-rules.txt b/docs/writing-rules.txt
new file mode 100644
index 000000000..22f6547ad
--- /dev/null
+++ b/docs/writing-rules.txt
@@ -0,0 +1,91 @@
+// -*- mode:doc; -*-
+// vim: set syntax=asciidoc:
+
+Coding style
+------------
+
+Overall, these coding style rules are here to help you to add new files in
+OpenADK or refactor existing ones.
+
+[[writing-rules-config-in]]
+
++Config.in+
+~~~~~~~~~~~
+
++Config.in+ files contain entries for almost anything configurable in
+OpenADK. Mostly all Config.in files for packages are autogenerated and
+should not be manually edited. The following rules apply for the top level
+Config.in, for the files in target/config and target/linux/config.
+
+An entry has the following pattern:
+
+---------------------
+config ADK_TARGET_FOO
+ bool "foo"
+ depends on ADK_PACKAGE_LIBBAZ
+ select BR2_PACKAGE_LIBBAR
+ help
+ This is a comment that explains what foo is.
+
+ http://foo.org/foo/
+---------------------
+
+* The +bool+, +depends on+, +select+ and +help+ lines are indented
+ with one tab.
+
+* The help text itself should be indented with one tab and two
+ spaces.
+
+The +Config.in+ files are the input for the configuration tool
+used in OpenADK, which is the regular _Kconfig_. For further
+details about the _Kconfig_ language, refer to
+http://kernel.org/doc/Documentation/kbuild/kconfig-language.txt[].
+
+[[writing-rules-mk]]
+
++Makefile+
+~~~~~~~~~~
+
+* Header: The file starts with a license header.
++
+---------------------
+# This file is part of the OpenADK project. OpenADK is copyrighted
+# material, please see the LICENCE file in the top-level directory.
+---------------------
++
+* Assignment: use +=+ followed by two tabs:
++
+---------------------
+PKG_VERSION:= 1.0
+PKG_BUILDDEP+= libfoo
+---------------------
++
+
+* Indentation: use tab only:
++
+---------------------
+libfoo-install:
+ $(CP) $(WRKINST)/usr/lib/libfoo*.so* \
+ $(IDIR_LIBFOO)/usr/lib
+---------------------
++
+
+* Optional dependency:
+
+** Prefer multi-line syntax.
+---------------------
+ifeq ($(ADK_PACKAGE_LIBFOO_WITH_PYTHON),y)
+CONFIGURE_ARGS+= --with-python-support
+else
+CONFIGURE_ARGS+= --without-python-support
+endif
+---------------------
+
+Documentation
+~~~~~~~~~~~~~
+
+The documentation uses the
+http://www.methods.co.nz/asciidoc/[asciidoc] format.
+
+For further details about the http://www.methods.co.nz/asciidoc/[asciidoc]
+syntax, refer to http://www.methods.co.nz/asciidoc/userguide.html[].