1 files changed, 95 insertions, 0 deletions
diff --git a/docs/common-usage.txt b/docs/common-usage.txt
new file mode 100644
index 000000000..25cc22454
--- /dev/null
+++ b/docs/common-usage.txt
@@ -0,0 +1,95 @@
+// -*- 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 rebuilds 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=<pkgname> 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-<pkgname>-<pkgversion>/+, just do:
+--------------------
+ $ make package=<pkgname> package
+--------------------
+
+If you are happy with your changes to the package sources, you can automatically
+generate a patch, which will be saved in +package/<pkgname>/patches+ and automatically
+applied on the next clean rebuild:
+--------------------
+ $ make package=<pkgname> update-patches
+--------------------
+
+The newly created patches will be opened in $EDITOR, so you can add 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+. The most useful and common ones are:
+
+* +ADK_APPLIANCE+, the appliance task you want to build
+* +ADK_CUSTOM_TASKS_DIR+, extra directory to fetch tasks from
+* +ADK_TARGET_OS+, the operating system of the target system
+* +ADK_TARGET_ARCH+, the architecture of the target system
+* +ADK_TARGET_CPU+, the specific CPU optimization for the target system (f.e. cortex-a53)
+* +ADK_TARGET_SYSTEM+, the embedded target system name
+* +ADK_TARGET_LIBC+, the C library for the target system
+* +ADK_TARGET_ABI+, the ABI for the target system (f.e. MIPS N64)
+* +ADK_TARGET_ENDIAN+, the endianess for the target system (little/big)
+* +ADK_TARGET_BINFMT+, the binary format for the target system (f.e. ELF/FLAT/FDPIC)
+* +ADK_TARGET_FLOAT+, the float support for the target system (f.e. soft/softfp/hard)
+* +ADK_TARGET_FS+, the firmware type or root filesystem for the target system
+* +ADK_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 ADK_APPLIANCE=new ADK_TARGET_ARCH=arm ADK_TARGET_SYSTEM=raspberry-pi ADK_TARGET_LIBC=musl allmodconfig
+--------------------
+
+This is often used in the development process of a target system, to verify that
+all packages are compilable.