From 9d097a780c0ffe2c9dbe146046d5b68123c47708 Mon Sep 17 00:00:00 2001 From: Waldemar Brodkorb Date: Sun, 16 Mar 2014 19:51:41 +0100 Subject: add OpenADK manual. --- TODO | 9 ++ docs/Makefile | 24 +++++ docs/adding-packages-auto.txt | 71 +++++++++++++ docs/adding-packages-conclusion.txt | 13 +++ docs/adding-packages-directory.txt | 57 +++++++++++ docs/adding-packages-hooks.txt | 31 ++++++ docs/adding-packages-host.txt | 92 +++++++++++++++++ docs/adding-packages-manual.txt | 83 ++++++++++++++++ docs/adding-packages.txt | 25 +++++ docs/advanced.txt | 15 +++ docs/appendix.txt | 8 ++ docs/ccache-support.txt | 21 ++++ docs/common-usage.txt | 87 ++++++++++++++++ docs/configure.txt | 68 +++++++++++++ docs/contribute.txt | 87 ++++++++++++++++ docs/customize-busybox-config.txt | 20 ++++ docs/customize-kernel-config.txt | 48 +++++++++ docs/customize-libc-config.txt | 33 ++++++ docs/customize-outside-adk.txt | 154 ++++++++++++++++++++++++++++ docs/customize-rootfs.txt | 23 +++++ docs/customize-store.txt | 14 +++ docs/customize-toolchain.txt | 23 +++++ docs/customize.txt | 19 ++++ docs/debugging-openadk.txt | 29 ++++++ docs/developer-guide.txt | 13 +++ docs/download-location.txt | 26 +++++ docs/faq-troubleshooting.txt | 58 +++++++++++ docs/getting.txt | 22 ++++ docs/going-further.txt | 9 ++ docs/how-openadk-works.txt | 80 +++++++++++++++ docs/images/menuconfig-configured.png | Bin 0 -> 341555 bytes docs/images/menuconfig.png | Bin 0 -> 271731 bytes docs/introduction.txt | 26 +++++ docs/legal-notice.txt | 51 ++++++++++ docs/make-tips.txt | 99 ++++++++++++++++++ docs/manual.txt | 33 ++++++ docs/network-configuration.txt | 182 ++++++++++++++++++++++++++++++++++ docs/package-make-target.txt | 52 ++++++++++ docs/package-reference.txt | 135 +++++++++++++++++++++++++ docs/patch-policy.txt | 82 +++++++++++++++ docs/prerequisite.txt | 52 ++++++++++ docs/qemu.txt | 1 + docs/running-openadk.txt | 178 +++++++++++++++++++++++++++++++++ docs/runtime-debugging.txt | 22 ++++ docs/starting-up.txt | 12 +++ docs/using-openadk-development.txt | 62 ++++++++++++ docs/using-openadk-toolchain.txt | 19 ++++ docs/using.txt | 99 ++++++++++++++++++ docs/working-with.txt | 25 +++++ docs/writing-rules.txt | 91 +++++++++++++++++ 50 files changed, 2483 insertions(+) create mode 100644 docs/Makefile create mode 100644 docs/adding-packages-auto.txt create mode 100644 docs/adding-packages-conclusion.txt create mode 100644 docs/adding-packages-directory.txt create mode 100644 docs/adding-packages-hooks.txt create mode 100644 docs/adding-packages-host.txt create mode 100644 docs/adding-packages-manual.txt create mode 100644 docs/adding-packages.txt create mode 100644 docs/advanced.txt create mode 100644 docs/appendix.txt create mode 100644 docs/ccache-support.txt create mode 100644 docs/common-usage.txt create mode 100644 docs/configure.txt create mode 100644 docs/contribute.txt create mode 100644 docs/customize-busybox-config.txt create mode 100644 docs/customize-kernel-config.txt create mode 100644 docs/customize-libc-config.txt create mode 100644 docs/customize-outside-adk.txt create mode 100644 docs/customize-rootfs.txt create mode 100644 docs/customize-store.txt create mode 100644 docs/customize-toolchain.txt create mode 100644 docs/customize.txt create mode 100644 docs/debugging-openadk.txt create mode 100644 docs/developer-guide.txt create mode 100644 docs/download-location.txt create mode 100644 docs/faq-troubleshooting.txt create mode 100644 docs/getting.txt create mode 100644 docs/going-further.txt create mode 100644 docs/how-openadk-works.txt create mode 100644 docs/images/menuconfig-configured.png create mode 100644 docs/images/menuconfig.png create mode 100644 docs/introduction.txt create mode 100644 docs/legal-notice.txt create mode 100644 docs/make-tips.txt create mode 100644 docs/manual.txt create mode 100644 docs/network-configuration.txt create mode 100644 docs/package-make-target.txt create mode 100644 docs/package-reference.txt create mode 100644 docs/patch-policy.txt create mode 100644 docs/prerequisite.txt create mode 100644 docs/qemu.txt create mode 100644 docs/running-openadk.txt create mode 100644 docs/runtime-debugging.txt create mode 100644 docs/starting-up.txt create mode 100644 docs/using-openadk-development.txt create mode 100644 docs/using-openadk-toolchain.txt create mode 100644 docs/using.txt create mode 100644 docs/working-with.txt create mode 100644 docs/writing-rules.txt 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= 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= 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--/+, just do: +-------------------- + $ make package= package +-------------------- + +If you are happy with your changes to the package sources, you can automatically +generate a patch, which will be saved in +package//patches and automatically +applied on the next clean rebuild: +-------------------- + $ make package= 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//kernel/+. + +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//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//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= 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= +----------------- + +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//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_+, +target__+, +build__+, + +pkg__+, 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 Binary files /dev/null and b/docs/images/menuconfig-configured.png differ diff --git a/docs/images/menuconfig.png b/docs/images/menuconfig.png new file mode 100644 index 000000000..5624a2982 Binary files /dev/null and b/docs/images/menuconfig.png 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 +-------------------- + +.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= 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: +-