debian: Extending build instructions for DEB_BUILD_OPTIONS

Author: smoe

docs/src/code/building-linuxcnc.adoc

@@ -18,8 +18,8 @@ http://buildbot.linuxcnc.org
 For the impatient, try this:
 
 ----
-$ git clone https://github.com/LinuxCNC/linuxcnc.git linuxcnc-dev
-$ cd linuxcnc-dev/src
+$ git clone https://github.com/LinuxCNC/linuxcnc.git linuxcnc-source-dir
+$ cd linuxcnc-source-dir/src
 $ ./autogen.sh
 $ ./configure --with-realtime=uspace
 $ make
@@ -125,7 +125,7 @@ It takes many optional arguments.
 List all arguments to `src/configure` by running this:
 
 -----
-$ cd linuxcnc-dev/src
+$ cd linuxcnc-source-dir/src
 $ ./configure --help
 -----
 
@@ -142,8 +142,7 @@ The most commonly used arguments are:
   these real-time kernels will also be enabled.
 
 `--with-realtime=/usr/realtime-$VERSION`::
-  Build for the RTAI realtime platform using the older "kernel realtime"
-  model.
+  Build for the RTAI realtime platform using the older "kernel realtime" model.
   This requires that you have an RTAI kernel and the RTAI modules
   installed in `/usr/realtime-$VERSION`. The resulting LinuxCNC
   executables will only run on the specified RTAI kernel. As of
@@ -180,7 +179,7 @@ Building just a specific target::
   executable by running:
 +
 -----
-$ cd linuxcnc-dev/src
+$ cd linuxcnc-source-dir/src
 $ make ../bin/froboz
 -----
 
@@ -214,7 +213,7 @@ The first step is generating the Debian package scripts and meta-data
 from the git repo by running this:
 
 ----
-$ cd linuxcnc-dev/debian
+$ cd linuxcnc-source-dir/debian
 $ ./configure uspace
 $ cd ..
 ----
@@ -235,21 +234,22 @@ $ dpkg-buildpackage -b -uc
 
 [NOTE]
 ====
-`dpkg-buildpackage` needs to run from the `linuxcnc-dev` directory, *not* from `linuxcnc-dev/debian`. +
+`dpkg-buildpackage` needs to run from the `linuxcnc-source-dir` directory, *not* from `linuxcnc-source-dir/debian`. +
 `dpkg-buildpackage` takes an optional argument `-jN` (where N is a number). This enables to run multiple jobs simultaneously.
 ====
 
 [[debian-configure-arguments]]
-==== `debian/configure` arguments
+==== LinuxCNC's `debian/configure` arguments
 
-The `debian/configure` script configures the Debian packaging.
-It must be run before `dpkg-checkbuilddeps` and `dpkg-buildpackage` can be run.
+The LinuxCNC source tree has a debian directory with all the info about how the Debian package shall be built,
+but some key files within are only distributed as templates. The `debian/configure` script readies those build instructions
+for the regular Debian packaging utilities and must thus be run prior to `dpkg-checkbuilddeps` or `dpkg-buildpackage`.
 
-It takes a single argument which specifies the realtime or non-realtime platform to build for.
-The normal values for this argument are:
+The `debian/configure` script takes a single argument which specifies the underlying realtime or non-realtime platform to build for.
+The regular values for this argument are:
 
 `no-docs`::
-   Skip building documentation.
+  Skip building documentation.
 
 `uspace`::
   Configure the Debian package for Preempt-RT realtime or for
@@ -286,36 +286,43 @@ If you want just the traditional RTAI "kernel module" realtime, use
   the test suite.
 
 [[Satisfying-Build-Dependencies]]
-== Satisfying Build Dependencies
+==== Satisfying Build Dependencies
 
-On Debian-based platforms we provide packaging meta-data that knows
-what external software packages need to be installed in order to build
-LinuxCNC.  This is called the Build Dependencies of LinuxCNC.  You can
-use this meta-data to easily list the required packages missing from
-your build system.
+On Debian-based platforms we provide packaging meta-data that knows what
+external software packages need to be installed in order to build LinuxCNC.
+This is called the Build Dependencies of LinuxCNC. These differ between
+platforms that LinuxCNC is configured for, so first run the following code
+sniplet in the root of your LinuxCNC git checkout to generate its Debian
+package meta-data:
 
-Debian systems provide a program called `dpkg-checkbuilddeps` that
+-----
+$ cd linuxcnc-source-dir/debian
+$ ./configure uspace
+$ cd ..
+-----
+
+This generates the file `debian/control` in a user-readable yaml-format
+which lists the build-dependencies close to the top.
+You can use this meta-data to easily list the required packages missing from
+your build system. You may decide to manually inspecting those files if you
+have a good understanding what is already installed.
+
+Alternatively, Debian systems provide a program called `dpkg-checkbuilddeps` that
 parses the package meta-data and compares the packages listed as build
 dependencies against the list of installed packages, and tells you
-what's missing.
+what's missing. Also, `dpkg-buildpackage` would inform you about what is missing,
+and it should be fine, but it reports missing build-deps only after patches in debian/patches
+are applied (if any), and if you are new to Linux and git version management,
+for a clean start it may be preferable to check first.
 
-First, install the `dpkg-checkbuilddeps` program by running:
+Hereto, install the `dpkg-checkbuilddeps` program by running:
 
 -----
 $ sudo apt-get install dpkg-dev
 -----
 
-Then ask your LinuxCNC git checkout to generate its Debian package
-meta-data:
-
------
-$ cd linuxcnc-dev/debian
-$ ./configure uspace
-$ cd ..
------
-
 Finally ask `dpkg-checkbuilddeps` to do its job (note that it needs to
-run from the `linuxcnc-dev` directory, *not* from `linuxcnc-dev/debian`):
+run from the `linuxcnc-source-dir` directory, *not* from `linuxcnc-source-dir/debian`):
 
 -----
 $ dpkg-checkbuilddeps
@@ -326,7 +333,53 @@ on your system, but that are not installed yet.  Install them all with
 `sudo apt-get install`, followed by the package names.
 
 You can rerun `dpkg-checkbuilddeps` any time you want, to list any
-missing packages.
+missing packages, which has no effect on the source tree.
+
+==== Options for `dpkg-buildpackage`
+
+For a typical Debian package to build, you would run dpkg-buildpackage without any arguments.
+As introduced above, the command has two extra options passed to it.
+Like for all good Linux tools, the man page has all the details with `man dpkg-buildpackage`.
+
+`-uc`:: Do not sign the resulting binaries. You would want to sign your packages with a GPG key of yours only if you would wanted to distribute them to others. Having that option not set and then failing to sign the package would not affect the .deb file.
+
+`-b`:: Only compiled the architecture-dependent packages (like the `linuxcnc` binaries and GUIs). This is very helpful to avoid compiling what is hardware-independent, which for LinuxCNC is the documentation. That documentation is available online anyway.
+
+If you happen to run into difficulties while compiling, check the LinuxCNC forum online.
+Currently emerging is the support for the DEB_BUILD_OPTIONS environment variable.
+Set it to
+
+`nodocs`:: to skip the building of the documentation. This is yet mostly untested, the `-b` flag to dpkg-buildpackage has the same effect, albeit formally a different semantics.
+
+`nocheck`:: to skip the self-tests of the LinuxCNC build process. This has no notable speed advantage but reduces the demand for a few software packages that may not be available for your system, i.e. the xvfb in particular. Do not set this unless running into difficulties with the dependencies.
+
+An environment variable can be set together with the execution of the command, e.g.
+----
+DEB_BUILD_OPTIONS=nodocs,nocheck dpkg-buildpackage -uc -b
+----
+would combine all the options introduced in this section.
+
+==== Installing self-built Debian packages
+
+A Debian package can be recognised by its .deb extension. The tool installing it,
+`dpkg` is part of every Debian installation. The .deb files created by `dpkg-buildpacakge`
+are found in the directoy above the linuxcnc-source-dir, i.e. in `..`.
+To see what files are provided in a package, run
+
+----
+dpkg -c ../linuxcnc-uspace*.deb
+----
+
+The version of LinuxCNC will be part of the file name, which is meant to be matched by the asterisk.
+There may be too many files listed to fit on your screen.
+If you cannot scroll up in your terminal then add `| more` to that command to have its output passed through a so-called "pager".
+Quit with "q".
+
+To install the packages, run
+
+----
+sudo dpkg -i ../linuxcnc*.deb
+----
 
 [[Setting-up-the-environment]]
 == Setting up the environment