docs/using.txt

   1 // -*- mode:doc; -*-
   2 // vim: set syntax=asciidoc:
   3
   4 Using OpenADK
   5 -------------
   6
   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:
  13
  14 --------------------
  15  $ make menuconfig
  16 --------------------
  17
  18 For each menu entry in the configuration tool, you can find associated
  19 help that describes the purpose of the entry.
  20
  21 image::openadk-menu.png[]
  22
  23 First of all you need to choose if you want to build a Linux firmware
  24 or a bare-metal toolchain. Linux is choosen as default.
  25
  26 image::openadk-arch.png[]
  27
  28 After that you should select your target architecture.
  29
  30 image::openadk-system.png[]
  31
  32 Now you can select your target system, endianess, cpu and other stuff.
  33
  34 image::openadk-task.png[]
  35
  36 If you want to compile some predefined appliance tasks, you can select it in +Tasks+.
  37 You can later simply add your own tasks, which is a collection of options, packages,
  38 kernel modules or features, runtime configuration and more. They can either be placed
  39 inside the +tasks+ directory or in your own custom directory that you pass via
  40 +ADK_CUSTOM_TASKS_DIR+ to make.
  41
  42 When you are ready exit and save. You can always redefine the
  43 configuration using +make menuconfig+.
  44
  45 Once everything is configured, the configuration tool generates a
  46 +.config+ file that contains the description of your configuration. It
  47 will be used by the Makefiles to do what's needed.
  48
  49 Let's go:
  50
  51 --------------------
  52  $ make
  53 --------------------
  54
  55 You *should never* use +make -jN+ with OpenADK: it does not support 'top-level
  56 parallel make'. Instead, use the +ADK_MAKE_JOBS+ option in +Global settings+ to
  57 tell OpenADK to run each package compilation with +make -jN+.
  58
  59 The `make` command will generally perform the following steps:
  60
  61 * download source files
  62 * configure, build and install required host tools
  63 * configure, build and install the cross-compiling toolchain
  64 * build a kernel image, if selected
  65 * build/install selected target packages
  66 * build a bootloader, if selected
  67 * create a root filesystem in selected format
  68
  69 OpenADK output is stored in several subdirectories:
  70
  71 * +firmware/+ where all the images and packages are stored.
  72
  73 * +build_<system>_<libc>_<arch>_<abi>/+ where all the components except for the
  74   cross-compilation toolchain are built. The directory contains one
  75   subdirectory for each of these components.
  76
  77 * +target_<system>_<libc>_<arch>_<abi>/+ which contains a hierarchy similar to a root filesystem
  78   hierarchy. This directory contains the installation of the
  79   cross-compilation toolchain and all the userspace packages selected
  80   for the target. However, this directory is 'not' intended to be
  81   the root filesystem for the target: it contains a lot of development
  82   files, unstripped binaries and libraries that make it far too big
  83   for an embedded system. These development files are used to compile
  84   libraries and applications for the target that depend on other
  85   libraries.
  86
  87 * +root_<system>_<libc>_<arch>_<abi>/+ which contains the complete root filesystem for
  88   the target. One exception, it doesn't have the correct
  89   permissions (e.g. setuid for the busybox binary) for some files.
  90   Therefore, this directory *should not be used on your target*.
  91   Instead, you should use one of the images or archives built in the
  92   +firmware/+ directory. If you need an
  93   extracted image of the root filesystem for booting over NFS, then
  94   use the tarball image generated in +firmware/+ and extract it as
  95   root. Compared to +build_*/+, +target_*/+ contains only the files and
  96   libraries needed to run the selected target applications: the
  97   development files are (exception: if any dev packages are selected)
  98   not present, the binaries are stripped.
  99
 100 * +host_<gnu_host_name>/+ contains the installation of tools compiled for the host
 101   that are needed for the proper execution of OpenADK
 102
 103 * +host_build_<gnu_host_name>/+ contains the build directories of tools compiled for the host
 104   that are needed for the proper execution of OpenADK
 105
 106 * +toolchain_<system>_<libc>_<arch>_<abi>>/+ contains just the cross-compilation toolchain.
 107   Can be used together with +target_<system>_<libc>_<arch>_<abi>/+ for other projects. Toolchain
 108   is relocatable.
 109
 110 * +toolchain_build_<system>_<libc>_<arch>_<abi>/+ contains the build directories for the various
 111   components of the cross-compilation toolchain.
 112
 113 * +pkg_<system>_<libc>_<arch>_<abi>/+ contains stamp files and file lists for the various components.
 114
 115 The command, +make menuconfig+ and +make+, are the
 116 basic ones that allow to easily and quickly generate images fitting
 117 your needs, with all the applications you enabled.
 118
 119 More details about the "make" command usage are given in
 120 xref:make-tips[].