use unzip for zip
[openadk.git] / docs / using.txt
blobb91e58826de5121a40b5ac1c653e07ce84c7da1a
1 // -*- mode:doc; -*-
2 // vim: set syntax=asciidoc:
4 Using OpenADK
5 -------------
7 OpenADK has a nice configuration tool similar to the one you can
8 find in the http://www.kernel.org/[Linux kernel] or in
9 http://www.busybox.net/[Busybox]. Note that you can *and should build
10 everything as a normal user*. There is no need to be root to configure
11 and use OpenADK. The first step is to run the configuration
12 assistant:
14 --------------------
15  $ make menuconfig
16 --------------------
18 For each menu entry in the configuration tool, you can find associated
19 help that describes the purpose of the entry.
21 image::openadk-appliance.png[]
23 First of all you need to choose a new or predefined appliance. 
24 This is a collection of different packages and configuration options
25 for a specific appliance.
27 image::openadk-target.png[]
29 After that you can choose your target architecture, your target system and
30 other general stuff. Then you can select individual packages and kernel
31 settings. When you are ready exit and save. You can always redefine the
32 configuration using +make menuconfig+.
34 Once everything is configured, the configuration tool generates a
35 +.config+ file that contains the description of your configuration. It
36 will be used by the Makefiles to do what's needed.
38 Let's go:
40 --------------------
41  $ make
42 --------------------
44 You *should never* use +make -jN+ with OpenADK: it does not support 'top-level
45 parallel make'. Instead, use the +ADK_MAKE_JOBS+ option in +Global settings+ to
46 tell OpenADK to run each package compilation with +make -jN+.
48 The `make` command will generally perform the following steps:
50 * download source files
51 * configure, build and install required host tools
52 * configure, build and install the cross-compiling toolchain
53 * build a kernel image, if selected
54 * build/install selected target packages
55 * build a bootloader, if selected
56 * create a root filesystem in selected format
58 OpenADK output is stored in several subdirectories: 
60 * +firmware/+ where all the images and packages are stored.
62 * +build_<system>_<libc>_<arch>_<abi>/+ where all the components except for the
63   cross-compilation toolchain are built. The directory contains one
64   subdirectory for each of these components.
66 * +target_<system>_<libc>_<arch>_<abi>/+ which contains a hierarchy similar to a root filesystem
67   hierarchy. This directory contains the installation of the
68   cross-compilation toolchain and all the userspace packages selected
69   for the target. However, this directory is 'not' intended to be
70   the root filesystem for the target: it contains a lot of development
71   files, unstripped binaries and libraries that make it far too big
72   for an embedded system. These development files are used to compile
73   libraries and applications for the target that depend on other
74   libraries.
76 * +root_<system>_<libc>_<arch>_<abi>/+ which contains the complete root filesystem for
77   the target. One exception, it doesn't have the correct
78   permissions (e.g. setuid for the busybox binary) for some files. 
79   Therefore, this directory *should not be used on your target*.  
80   Instead, you should use one of the images or archives built in the 
81   +firmware/+ directory. If you need an
82   extracted image of the root filesystem for booting over NFS, then
83   use the tarball image generated in +firmware/+ and extract it as
84   root. Compared to +build_*/+, +target_*/+ contains only the files and
85   libraries needed to run the selected target applications: the
86   development files are (exception: if any dev packages are selected)
87   not present, the binaries are stripped.
89 * +host_<gnu_host_name>/+ contains the installation of tools compiled for the host
90   that are needed for the proper execution of OpenADK
92 * +host_build_<gnu_host_name>/+ contains the build directories of tools compiled for the host
93   that are needed for the proper execution of OpenADK
95 * +toolchain_<system>_<libc>_<arch>_<abi>>/+ contains just the cross-compilation toolchain.
96   Can be used together with +target_<system>_<libc>_<arch>_<abi>/+ for other projects. Toolchain
97   is relocatable.
99 * +toolchain_build_<system>_<libc>_<arch>_<abi>/+ contains the build directories for the various
100   components of the cross-compilation toolchain.
102 * +pkg_<system>_<libc>_<arch>_<abi>/+ contains stamp files and file lists for the various components.
104 The command, +make menuconfig+ and +make+, are the
105 basic ones that allow to easily and quickly generate images fitting
106 your needs, with all the applications you enabled.
108 More details about the "make" command usage are given in
109 xref:make-tips[].