docs/common-usage.txt

   1 // -*- mode:doc; -*-
   2 // vim: set syntax=asciidoc:
   3
   4 Daily use
   5 ---------
   6
   7 Understanding when a full rebuild is necessary
   8 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   9
  10 OpenADK tries to detect what part of the system should be rebuilt when the
  11 system configuration is changed through +make menuconfig+.  In some cases it
  12 automatically rebuilds packages, but sometimes just a warning is printed to the
  13 terminal, that a rebuild is necessary to make the changes an effect. If strange
  14 things are happening, the autodetection might have not worked correctly, then
  15 you should consider to rebuild everything. If you are following development you
  16 should always do a full rebuild after fetching updates via +git pull+. It is
  17 not always required, but if anything fails, you are on your own.
  18 Use following to do a full rebuild without refetching distfiles:
  19
  20 --------------------
  21  $ make cleandir && make
  22 --------------------
  23
  24 Understanding how to rebuild packages
  25 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  26
  27 In OpenADK you can rebuild a single package with:
  28 --------------------
  29  $ make package=<pkgname> clean package
  30 --------------------
  31
  32 It will automatically remove all files added to the staging target directory
  33 +target_*+. If you just want to restart compilation process, after making
  34 some fixes in +build_*/w-<pkgname>-<pkgversion>/+, just do:
  35 --------------------
  36  $ make package=<pkgname> package
  37 --------------------
  38
  39 If you are happy with your changes to the package sources, you can automatically
  40 generate a patch, which will be saved in +package/<pkgname>/patches+ and automatically
  41 applied on the next clean rebuild:
  42 --------------------
  43  $ make package=<pkgname> update-patches
  44 --------------------
  45
  46 The newly created patches will be opened in $EDITOR, so you can add some comments to
  47 the top of the file, before the diff.
  48
  49
  50 Offline builds
  51 ~~~~~~~~~~~~~~
  52
  53 If you intend to do an offline build and just want to download
  54 all sources that you previously selected in the configurator
  55 then issue:
  56
  57 --------------------
  58  $ make download
  59 --------------------
  60
  61 You can now disconnect or copy the content of your +dl+
  62 directory to the build-host.
  63
  64 [[env-vars]]
  65
  66 Environment variables
  67 ~~~~~~~~~~~~~~~~~~~~~
  68
  69 OpenADK also honors some environment variables, when they are passed
  70 to +make+. The most useful and common ones are:
  71
  72 * +ADK_APPLIANCE+, the appliance task you want to build
  73 * +ADK_CUSTOM_TASKS_DIR+, extra directory to fetch tasks from
  74 * +ADK_TARGET_OS+, the operating system of the target system
  75 * +ADK_TARGET_ARCH+, the architecture of the target system
  76 * +ADK_TARGET_CPU+, the specific CPU optimization for the target system (f.e. cortex-a53)
  77 * +ADK_TARGET_SYSTEM+, the embedded target system name
  78 * +ADK_TARGET_LIBC+, the C library for the target system
  79 * +ADK_TARGET_ABI+, the ABI for the target system (f.e. MIPS N64)
  80 * +ADK_TARGET_ENDIAN+, the endianess for the target system (little/big)
  81 * +ADK_TARGET_BINFMT+, the binary format for the target system (f.e. ELF/FLAT/FDPIC)
  82 * +ADK_TARGET_FLOAT+, the float support for the target system (f.e. soft/softfp/hard)
  83 * +ADK_TARGET_FS+, the firmware type or root filesystem for the target system
  84 * +ADK_VERBOSE+, verbose build, when set to 1
  85
  86
  87 An example that creates a configuration file for Raspberry PI with all
  88 software packages enabled, but not included in the resulting firmware image:
  89
  90 --------------------
  91  $ make ADK_APPLIANCE=new ADK_TARGET_ARCH=arm ADK_TARGET_SYSTEM=raspberry-pi ADK_TARGET_LIBC=musl allmodconfig
  92 --------------------
  93
  94 This is often used in the development process of a target system, to verify that
  95 all packages are compilable.