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. --- 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 +++++++++++++++++ 49 files changed, 2474 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 (limited to 'docs') 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: +--------------------- +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+ 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= +------------ + +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//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= update-patches +------------ + +Otherwise they are manually generated via: +------------ + $ diff -Nur -.orig - > package//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: +--------------- + +or + +--------------- +Fetch from: +--------------- + +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//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//files/.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 } [] +--------------------- + +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___/w--+, 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___/w--+ +and recompile the package with: + +------------ + $ make package= package +------------ + +When you are happy with the change, generate a patch: +------------ + $ make package= update-patches +------------ + +For the linux kernel just change the code in ++build___/linux, remove the .config +and call make again: + +------------ + $ rm build___/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_/+. The simplest way to use it is to add ++host_/bin/+ to your PATH environment variable and then to use ++--linux--gcc+, ++--linux--objdump+, etc. + +It is possible to relocate the toolchain, you just need to put ++target___+ into the same directory as ++host_/+. 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___/+ where all the components except for the cross-compilation toolchain are built. The directory contains one subdirectory for each of these components. + +* +target__/+ 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___/+ 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_/+ 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__/+ contains the build directories for the various + components of the cross-compilation toolchain. + +* +pkg___/+ 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[]. -- cgit v1.2.3 From 4893f466c54b0dc48e97f785fa6b1b5b1e01e4ca Mon Sep 17 00:00:00 2001 From: Waldemar Brodkorb Date: Sun, 16 Mar 2014 22:24:17 +0100 Subject: remove cleantarget at the moment we share all toolchains in host_ directory, so the existing cleantarget does not work as expected. remove it for now. --- docs/customize-libc-config.txt | 2 +- docs/make-tips.txt | 9 ++------- 2 files changed, 3 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/customize-libc-config.txt b/docs/customize-libc-config.txt index 075a272a0..438e630f8 100644 --- a/docs/customize-libc-config.txt +++ b/docs/customize-libc-config.txt @@ -27,7 +27,7 @@ and rebuild your targetsystem, including the toolchain components: ---------------- $ cp .config ../target//uclibc.config - $ cd .. && make cleantarget && make + $ cd .. && make cleandir && make ---------------- There are no customization options for GNU libc or musl available. diff --git a/docs/make-tips.txt b/docs/make-tips.txt index 787121cb4..f508633e9 100644 --- a/docs/make-tips.txt +++ b/docs/make-tips.txt @@ -42,13 +42,8 @@ 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: +If you even want to clean any downloaded source and your +confiuration +.config+: -------------------- $ make distclean -- cgit v1.2.3 From ed78ab954ca991cca578f59a32d147304025647d Mon Sep 17 00:00:00 2001 From: Waldemar Brodkorb Date: Wed, 19 Mar 2014 10:05:22 +0100 Subject: correct new toolchain path --- docs/how-openadk-works.txt | 4 ++-- docs/package-reference.txt | 4 ++-- docs/using-openadk-toolchain.txt | 8 ++++---- docs/using.txt | 7 +++++-- 4 files changed, 13 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/how-openadk-works.txt b/docs/how-openadk-works.txt index 9c6ae167d..a8634d8c3 100644 --- a/docs/how-openadk-works.txt +++ b/docs/how-openadk-works.txt @@ -59,8 +59,8 @@ is done: 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. +* 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 diff --git a/docs/package-reference.txt b/docs/package-reference.txt index 650694bf2..36d2e28b4 100644 --- a/docs/package-reference.txt +++ b/docs/package-reference.txt @@ -28,11 +28,11 @@ information is: 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/} + 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 + 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//src+, which will be diff --git a/docs/using-openadk-toolchain.txt b/docs/using-openadk-toolchain.txt index 1b294d4da..6994d9abc 100644 --- a/docs/using-openadk-toolchain.txt +++ b/docs/using-openadk-toolchain.txt @@ -9,11 +9,11 @@ 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_/+. The simplest way to use it is to add -+host_/bin/+ to your PATH environment variable and then to use ++toolchain_/+. The simplest way to use it is to add ++toolchain_/usr/bin/+ to your PATH environment variable and then to use +--linux--gcc+, +--linux--objdump+, etc. It is possible to relocate the toolchain, you just need to put -+target___+ into the same directory as -+host_/+. ++target___+ into the same directory as ++toolchain_/+. diff --git a/docs/using.txt b/docs/using.txt index c51914c04..45ea3f20c 100644 --- a/docs/using.txt +++ b/docs/using.txt @@ -83,8 +83,11 @@ OpenADK output is stored in several subdirectories: not present, the binaries are stripped. * +host_/+ contains the installation of tools compiled for the host - that are needed for the proper execution of OpenADK, including the - cross-compilation toolchain. + that are needed for the proper execution of OpenADK + +* +toolchain_/+ contains just the cross-compilation toolchain. + Can be used together with +target__/+ for other projects. Toolchain + is relocatable. * +toolchain_build__/+ contains the build directories for the various components of the cross-compilation toolchain. -- cgit v1.2.3 From 3ef9bac3df49421f6a58f5b3e5b0997d144ece38 Mon Sep 17 00:00:00 2001 From: Waldemar Brodkorb Date: Thu, 20 Mar 2014 21:04:34 +0100 Subject: update with new host tool dependency stuff --- docs/adding-packages-host.txt | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/adding-packages-host.txt b/docs/adding-packages-host.txt index a858d4563..c9eba6d02 100644 --- a/docs/adding-packages-host.txt +++ b/docs/adding-packages-host.txt @@ -75,18 +75,12 @@ Following mix between host and target package is possible, too: 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: +If you need to rebuild a mixed package, you can do: ------------ - $ make package= clean hostpackage package + $ make package= hostclean hostpackage clean 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: +If your host package have some dependencies, use following: ------------ - PKG_BUILDDEP:=libbaz-host bar-host + HOST_BUILDDEP:=libbaz-host bar-host ------------ - - -- cgit v1.2.3 From 3f794fad83e51a090191803aa54f4a7fe0d5a2ef Mon Sep 17 00:00:00 2001 From: Waldemar Brodkorb Date: Wed, 26 Mar 2014 12:32:06 +0100 Subject: remove git as dependency, we now have snapshot tarballs --- docs/contribute.txt | 1 + docs/getting.txt | 6 ++++-- docs/introduction.txt | 6 ++++++ docs/patch-policy.txt | 12 ++++++++++-- 4 files changed, 21 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/contribute.txt b/docs/contribute.txt index 909263886..5a8e1fdd8 100644 --- a/docs/contribute.txt +++ b/docs/contribute.txt @@ -82,6 +82,7 @@ Here is a short list of details to provide in such case: * target for which the build fails * package(s) which the build fails * the command that fails and its output +* the make.log file, generated when make v is used * any information you think that may be relevant Additionally, you can add the +.config+ file. diff --git a/docs/getting.txt b/docs/getting.txt index 534ba99c9..0902bb6e0 100644 --- a/docs/getting.txt +++ b/docs/getting.txt @@ -5,8 +5,9 @@ Getting OpenADK --------------- -OpenADK does not have any releases. Only direct Git -access is possible. +OpenADK does not have any releases. We are following the +http://en.wikipedia.org/wiki/Rolling_release[rolling release] +development model. To download OpenADK using Git just do: @@ -20,3 +21,4 @@ Or if you prefer HTTP or using Git behind a proxy: $ git clone http://git.openadk.org/openadk.git --------------------- +Or you can get a http://www.openadk.org/snapshots/[snapshot]. diff --git a/docs/introduction.txt b/docs/introduction.txt index 991747672..3489c9d5f 100644 --- a/docs/introduction.txt +++ b/docs/introduction.txt @@ -24,3 +24,9 @@ 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) + +OpenADK is not a Linux distribution and there are no releases or binary +packages available. If you need something like that, better switch to +something else. OpenADK builds everything from source. There are only a +few exceptions to this rule (f.e. some bootloaders and firmware files for +wireless network cards). diff --git a/docs/patch-policy.txt b/docs/patch-policy.txt index b5a585b5e..e948661cf 100644 --- a/docs/patch-policy.txt +++ b/docs/patch-policy.txt @@ -10,8 +10,8 @@ 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. +these typically aim to fix cross-compilation, libc support, portability issues +or other things. Normally the patches are autogenerated via: ------------ @@ -80,3 +80,11 @@ Fetch from: It is also sensible to add a few words about any changes to the patch that may have been necessary. + +Upstreaming patches +~~~~~~~~~~~~~~~~~~~ + +OpenADK tries to avoid any patches to the source code. If a patch could +not be avoided, it should be tried to make the patch of a good quality to +get it upstream. OpenADK tries to report any found issues and try to send +in any upstream compatible patches. -- cgit v1.2.3 From 8aed1fcd443b550c15a21ddbf1b1d3899803120a Mon Sep 17 00:00:00 2001 From: Waldemar Brodkorb Date: Sun, 30 Mar 2014 15:55:20 +0200 Subject: rework hosttools building, add tools into package stuff --- docs/how-openadk-works.txt | 25 +++++++++---------------- docs/make-tips.txt | 4 ++-- docs/prerequisite.txt | 11 +++++------ 3 files changed, 16 insertions(+), 24 deletions(-) (limited to 'docs') diff --git a/docs/how-openadk-works.txt b/docs/how-openadk-works.txt index a8634d8c3..e86251196 100644 --- a/docs/how-openadk-works.txt +++ b/docs/how-openadk-works.txt @@ -6,7 +6,7 @@ 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. +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. @@ -22,28 +22,20 @@ many different parts. 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. + associated files for all user-space tools and libraries that OpenADK can + compile and add to the target root filesystem or to the host directory. There + is one sub-directory per package. * The +mk/+ directory contains some globally used Makefiles with the suffix +.mk+, these are used in all other Makefile via include -* The +tools/+ directory contains the Makefiles and +* The +adk/+ 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: + host tools needed for +make menuconfig+ system * The +scripts/+ directory contains shell scripts for the creation of meta-data in OpenADK, install scripts and image creation scripts -* The +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: @@ -69,12 +61,13 @@ configuration is done (it is mainly a wrapper for +mk/build.mk+): available systems and package collections * Generate the host tools required for different tasks (encrypting passwords, - compressing data, extracting archives, ..) + compressing data, extracting archives, creating images, ..) * Generate the cross-compilation toolchain (binutils, gcc, libc, gdb) -* Compile the linux kernel +* 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/make-tips.txt b/docs/make-tips.txt index f508633e9..dcfbe22e0 100644 --- a/docs/make-tips.txt +++ b/docs/make-tips.txt @@ -43,7 +43,7 @@ and pkg trees, the firmware and the toolchain for all targets): -------------------- If you even want to clean any downloaded source and your -confiuration +.config+: +configuration +.config+: -------------------- $ make distclean @@ -60,7 +60,7 @@ 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: +(the toolchain is not deleted) just use: -------------------- $ make clean diff --git a/docs/prerequisite.txt b/docs/prerequisite.txt index 8a9670066..d7ffcc544 100644 --- a/docs/prerequisite.txt +++ b/docs/prerequisite.txt @@ -23,8 +23,8 @@ package names may vary between host systems. ** +bash+ ** +binutils+ -** +gcc+ -** `g++` +** +C compiler (gcc or clang)+ +** `C++ compiler (g++ or clang++)` ** +GNU sed+ ** +GNU awk+ ** +GNU make+ @@ -33,10 +33,9 @@ package names may vary between host systems. ** +perl+ ** +tar+ ** +wget+ -** +findutils (find, xargs)+ -** +ncurses5 development+ -** +zlib development+ -** +libc development+ +** +ncurses5 development files+ +** +zlib development files+ +** +libc development files+ There is a check for the required versions of these tools in advance, though. To re-issue the checks, use +make prereq+. -- cgit v1.2.3