Introduced apt build-dep

smoe · smoe · commit 38983fec379a · 2023-09-22T15:01:42.000+02:00
diff --git a/docs/src/code/building-linuxcnc.adoc b/docs/src/code/building-linuxcnc.adoc
@@ -5,12 +5,22 @@
 
 == Introduction
 
-This document describes how to build the LinuxCNC software and
-documentation from source.  This is primarily useful if you are a
-developer who is modifying LinuxCNC.  It can also be useful if you're
-a user who is testing developer branches, though then you also have
-the option of just installing Debian packages from the buildbot:
-http://buildbot.linuxcnc.org
+This document describes how to build the LinuxCNC software from source.
+This is primarily useful if you are a developer who is modifying LinuxCNC.
+It can also be useful if you're a user who is testing developer branches,
+though then you also have the option of just installing Debian packages from the buildbot
+(http://buildbot.linuxcnc.org) or as a regular package from your Linux
+distribution (https://tracker.debian.org/pkg/linuxcnc).
+Admittedly, this section also exists since LinuxCNC is a community effort.
+Buildbots and distributions only distribute what is considered safe.
+So, new developments, or you porting LinuxCNC to some new Linux disribution
+or a developers' reaction to you reporting a problem will see no buildbot
+to help, or that help is delayed, pending someone else's review.
+
+The LinuxCNC documentation is distributed together with all the other files of the source tree.
+You can also build that, but skipping that to just use the regularly rebuilt online verions saves some time.
+But please seriously consider to contribute ot the documentation.
+Everyone always finds something to improve - and if you only leave a "FIXME".
 
 [[Quick-Start]]
 === Quick Start
@@ -25,10 +35,9 @@ $ ./configure --with-realtime=uspace
 $ make
 ----
 
-That will probably fail!  That doesn't make you a bad person, it just
-means you should read this whole document to find out how to fix your
-problems.  Especially the section on <<Satisfying-Build-Dependencies,
-Satisfying Build Dependencies>>.
+That will probably fail!  That doesn't make you a bad person,
+it just means you should read this whole document to find out how to fix your problems.
+Especially the section on <<Satisfying-Build-Dependencies, Satisfying Build Dependencies>>.
 
 If you are running on a realtime-capable system (such as an install from
 the LinuxCNC Live/Install Image, see the <<sub:realtime,Realtime>> section
@@ -50,11 +59,8 @@ on <<Setting-up-the-environment,Setting up the test environment>>.
 
 == Supported Platforms
 
-The LinuxCNC project targets modern Debian-based distributions, including
-Debian, Ubuntu, and Mint.
-
-We continuously test on the platforms listed at
-http://buildbot.linuxcnc.org.
+The LinuxCNC project targets modern Debian-based distributions, including Debian, Ubuntu, and Mint.
+We continuously test on the platforms listed at http://buildbot.linuxcnc.org.
 
 LinuxCNC builds on most other Linux distributions, though dependency
 management will be more manual and less automatic. Patches to improve
@@ -63,36 +69,34 @@ portability to new platforms are always welcome.
 [[sub:realtime]]
 === Realtime
 
-LinuxCNC is a machine tool controller, and it requires a realtime platform
-to do this job. This version of LinuxCNC supports three realtime platforms
+LinuxCNC is a machine tool controller, and it requires a realtime platform to do this job.
+FIXME: Give a reference to a section to read this up.
+This version of LinuxCNC supports three realtime platforms
 
 RTAI::
-  From https://www.rtai.org. A Linux kernel with the RTAI patch is
-  available from the Debian archive at https://linuxcnc.org. See
-  <<cha:getting-linuxcnc,Getting LinuxCNC>> for installation instructions.
+  From https://www.rtai.org.
+  A Linux kernel with the RTAI patch is available from the Debian archive at https://linuxcnc.org.
+  See <<cha:getting-linuxcnc,Getting LinuxCNC>> for installation instructions.
 
 Xenomai::
-  From https://xenomai.org. You will have to compile or obtain a Xenomai
-  kernel yourself.
+  From https://xenomai.org. You will have to compile or obtain a Xenomai kernel yourself.
 
 Preempt-RT::
-  From https://rt.wiki.kernel.org. A Linux kernel with the
-  Preempt-RT patch is occasionally available from the Debian
-  archive at https://www.debian.org, and from the wayback machine at
-  https://snapshot.debian.org.
+  From https://rt.wiki.kernel.org.
+  A Linux kernel with the Preempt-RT patch is occasionally available from the Debian archive at https://www.debian.org, and from the wayback machine at https://snapshot.debian.org.
 
-To make use of the realtime capabilities of LinuxCNC, certain parts of
-LinuxCNC need to run with root privileges.  To enable root for these
-parts, run this extra command after the `make` that builds LinuxCNC:
+To make use of the realtime capabilities of LinuxCNC, certain parts of LinuxCNC need to run with root privileges.
+To enable root for these parts, run this extra command after the `make` that builds LinuxCNC:
 
 -----
 $ sudo make setuid
 -----
 
+FIXME: This does not belong here. Focus should be on building.
 === Non-realtime
 
-LinuxCNC can also be built and run on non-realtime platforms, such as
-a regular install of Debian or Ubuntu without any special realtime kernel.
+LinuxCNC can also be built and run on non-realtime platforms,
+such as a regular install of Debian or Ubuntu without any special realtime kernel.
 
 In this mode LinuxCNC is not useful for controlling machine tools,
 but it is useful for simulating the execution of G-code and for testing the non-realtime parts of the system
@@ -165,18 +169,15 @@ The most commonly used arguments are:
 The `make` command takes two useful optional arguments.
 
 Parallel compilation::
-  `make` takes an optional argument `-jN` (where N is a number).
-  This enables parallel compilation with N simultaneous processes, which
-  can significantly speed up your build.
+  `make` takes an optional argument `-j` _N_ (where _N_ is a number).
+  This enables parallel compilation with N simultaneous processes, which can significantly speed up your build.
 +
-A useful value for N is the number of CPUs in your build system.  You can
-discover the number of CPUs by running `nproc`.
+A useful value for _N_ is the number of CPUs in your build system.
+You can discover the number of CPUs by running `nproc`.
 
 Building just a specific target::
-  If you want to build just a specific part of LinuxCNC, you can name
-  the thing you want to build on the `make` command line.  For example,
-  if you are working on a component named `froboz`, you can build its
-  executable by running:
+  If you want to build just a specific part of LinuxCNC, you can name the thing you want to build on the `make` command line.
+  For example, if you are working on a component named `froboz`, you can build its executable by running:
 +
 -----
 $ cd linuxcnc-source-dir/src
@@ -185,32 +186,31 @@ $ make ../bin/froboz
 
 === Building Debian Packages
 
-When building Debian packages, the LinuxCNC programs are compiled from
-source and then stored in a Debian package, complete with dependency
-information.  This takes more time, and the programs can't be used until
-the Debian package is installed on a target machine.
+When building Debian packages, the LinuxCNC programs are compiled from source and then stored in several Debian packages.
+This packages separate different parts, like the documentation from the executables, and come with a description
+of themselves that describes what the package is providing and what other packages are also required to be installed
+to make use of what the package provides, i.e. the run-time dependencies.
+The programs can't be used until the Debian package is installed on a target machine.
 
-This build mode is primarily useful when packaging the software for
-delivery to end users, and when building the software for a machine
-that doesn't have the build environment installed, or that doesn't have
-internet access.
+To build packages is primarily useful when packaging the software for delivery to end users.
+Developers among themselves exchange only the source code.
+Also, when building the software for a machine that doesn't have the build environment installed,
+or that doesn't have internet access, one happily accepts a prebuilt package.
 
-Building Debian packages requires the `dpkg-buildpackage` tool, from the
-`dpkg-dev` package:
+Building Debian packages requires the `dpkg-buildpackage` tool, from the `dpkg-dev` package.
+But when building a Debian package, is generally expected to have all scripts in place that would commonly be expected.
+This has been formally manifested as a virtual "build-essential" package:
 
 ----
-$ sudo apt-get install dpkg-dev
+$ sudo apt-get install build-essential
 ----
 
-Building Debian packages also requires that all build dependencies are
-installed, as described in the section <<Satisfying-Build-Dependencies,
-Satisfying Build Dependencies>>.
+Building Debian packages also requires that all package-specific build dependencies are installed,
+as described in the section <<Satisfying-Build-Dependencies,Satisfying Build Dependencies>>.
 
-Once those prerequisites are met, building the Debian packages consists
-of two steps.
+Once those prerequisites are met, building the Debian packages consists of two steps.
 
-The first step is generating the Debian package scripts and meta-data
-from the git repo by running this:
+The first step is generating the Debian package scripts and meta-data from the git repo by running this:
 
 ----
 $ cd linuxcnc-source-dir/debian
@@ -235,7 +235,7 @@ $ dpkg-buildpackage -b -uc
 [NOTE]
 ====
 `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.
+`dpkg-buildpackage` takes an optional argument ``-j``_N_ (where _N_ is a number). This enables to run multiple jobs simultaneously.
 ====
 
 [[debian-configure-arguments]]
@@ -252,38 +252,32 @@ The regular values for this argument are:
   Skip building documentation.
 
 `uspace`::
-  Configure the Debian package for Preempt-RT realtime or for
-  non-realtime (these two are compatible).
+  Configure the Debian package for Preempt-RT realtime or for non-realtime (these two are compatible).
 
 `noauto`::
 `rtai`::
 `xenomai`::
-  Normally, the lists of RTOSes for uspace realtime to support is detected
-  automatically.  However, if you wish, you may specify one or more of these
-  after `uspace` to enable support for these RTOSes.  Or, to disable
-  autodetection, specify `noauto`.
+  Normally, the lists of RTOSes for uspace realtime to support is detected automatically.
+  However, if you wish, you may specify one or more of these after `uspace` to enable support for these RTOSes.
+  Or, to disable autodetection, specify `noauto`.
 +
-If you want just the traditional RTAI "kernel module" realtime, use
-`-r` or `$KERNEL_VERSION` instead.
+If you want just the traditional RTAI "kernel module" realtime, use `-r` or `$KERNEL_VERSION` instead.
 
 `rtai=<package name>`::
-  If the development package for rtai lxrt does not start with
-  "rtai-modules", or if the first such package listed by apt-cache search
-  is not the desired one, then explicitly specify the package name.
+  If the development package for rtai lxrt does not start with "rtai-modules",
+  or if the first such package listed by apt-cache search is not the desired one,
+  then explicitly specify the package name.
 
 `-r`::
   Configure the Debian package for the currently running RTAI kernel.
-  You must be running an RTAI kernel on your build machine for this
-  to work!
+  You must be running an RTAI kernel on your build machine for this to work!
 
 `$KERNEL_VERSION`::
-  Configure the debian package for the specified RTAI kernel version
-  (for example "3.4.9-rtai-686-pae").  The matching kernel headers
-  debian package must be installed on your build machine (for example
-  "linux-headers-3.4.9-rtai-686-pae").  Note that you can _build_
-  LinuxCNC in this configuration, but if you are not running the
-  matching RTAI kernel you will not be able to _run_ LinuxCNC, including
-  the test suite.
+  Configure the debian package for the specified RTAI kernel version (for example "3.4.9-rtai-686-pae").
+  The matching kernel headers debian package must be installed on your build machine (for example "linux-headers-3.4.9-rtai-686-pae").
+  Note that you can _build_ LinuxCNC in this configuration,
+  but if you are not running the matching RTAI kernel you will not be able to _run_ LinuxCNC,
+  including the test suite.
 
 [[Satisfying-Build-Dependencies]]
 ==== Satisfying Build Dependencies
@@ -315,25 +309,23 @@ and it should be fine, but it reports missing build-deps only after patches in d
 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.
 
-Hereto, install the `dpkg-checkbuilddeps` program by running:
+The `dpkg-checkbuilddeps` (also from the dpkg-dev package that is installed as part of the build-essential dependencies)
+program can be ask `dpkg-checkbuilddeps` to do its job
+(note that it needs to run from the `linuxcnc-source-dir` directory, *not* from `linuxcnc-source-dir/debian`):
 
 -----
-$ sudo apt-get install dpkg-dev
+$ dpkg-checkbuilddeps
 -----
 
-Finally ask `dpkg-checkbuilddeps` to do its job (note that it needs to
-run from the `linuxcnc-source-dir` directory, *not* from `linuxcnc-source-dir/debian`):
+It will emit a list of packages that are required to build LinuxCNC on your system, but that are not installed yet.
+You can now install missing build-dependencies
 
------
-$ dpkg-checkbuilddeps
------
+manually:: Install them all with `sudo apt-get install`, followed by the package names.i
+  You can rerun `dpkg-checkbuilddeps` any time you want, to list any missing packages, which has no effect on the source tree.
 
-It will emit a list of packages that are required to build LinuxCNC
-on your system, but that are not installed yet.  Install them all with
-`sudo apt-get install`, followed by the package names.
+automated:: Run `sudo apt build-dep .` .
 
-You can rerun `dpkg-checkbuilddeps` any time you want, to list any
-missing packages, which has no effect on the source tree.
+If in doubt about what a particular package of a build-dep may be providing, check out the package's description with ``apt-cache show`` _packagename_.
 
 ==== Options for `dpkg-buildpackage`
 
@@ -384,25 +376,20 @@ sudo dpkg -i ../linuxcnc*.deb
 [[Setting-up-the-environment]]
 == Setting up the environment
 
-This section describes the special steps needed to set up a machine to
-run the LinuxCNC programs, including the tests.
+This section describes the special steps needed to set up a machine to run the LinuxCNC programs, including the tests.
 
 === Increase the locked memory limit
 
-LinuxCNC tries to improve its realtime latency by locking the memory it
-uses into RAM.  It does this in order to prevent the operating system from
-swapping LinuxCNC out to disk, which would have bad effects on latency.
+LinuxCNC tries to improve its realtime latency by locking the memory it uses into RAM.
+It does this in order to prevent the operating system from swapping LinuxCNC out to disk, which would have bad effects on latency.
 
 Normally locking memory into RAM is frowned upon, and the operating system
 places a strict limit on how much memory a user is allowed to have locked.
 
-When using the Preempt-RT realtime platform LinuxCNC runs with enough
-privilege to raise its memory lock limit itself.  When using the RTAI
-realtime platform it does not have enough privilege, and the user must
-raise the memory lock limit.
+When using the Preempt-RT realtime platform LinuxCNC runs with enough privilege to raise its memory lock limit itself.
+When using the RTAI realtime platform it does not have enough privilege, and the user must raise the memory lock limit.
 
-If LinuxCNC displays the following message on startup, the problem is
-your system's configured limit on locked memory:
+If LinuxCNC displays the following message on startup, the problem is your system's configured limit on locked memory:
 
 -----
 RTAPI: ERROR: failed to map shmem
@@ -418,8 +405,8 @@ The file should contain the following line:
 * - memlock 20480
 -----
 
-Log out and log back in to make the changes take effect.  Verify that
-the memory lock limit is raised using the following command:
+Log out and log back in to make the changes take effect.
+Verify that the memory lock limit is raised using the following command:
 
 -----
 $ ulimit -l
@@ -434,17 +421,14 @@ way to get started.  However, there are other options to consider.
 
 === Fork us on Github
 
-The LinuxCNC project git repo is at https://github.com/LinuxCNC/linuxcnc.
-github is a popular git hosting service and code sharing website.
-You can easily (and for no cost) create a fork of our git repo at github,
-and use that to track and publish your changes.
+FIXME: This needs more content.
 
-After creating your own github fork of LinuxCNC, clone it to your
-development machine and proceed with your hacking as usual.
+The LinuxCNC project git repo is at https://github.com/LinuxCNC/linuxcnc.
+GitHub is a popular git hosting service and code sharing website.
+You can easily (and for no cost) create a fork of our git repo at GitHub, and use that to track and publish your changes.
+After creating your own GitHub fork of LinuxCNC, clone it to your development machine and proceed with your hacking as usual.
 
-We of the LinuxCNC project hope that you will share your changes with
-us, so that the community can benefit from your work.  Github makes this
-sharing very easy: after you polish your changes and push them to your
-github fork, send us a Pull Request.
+We of the LinuxCNC project hope that you will share your changes with us, so that the community can benefit from your work.
+Github makes this sharing very easy: after you polish your changes and push them to your github fork, send us a Pull Request.
 
 // vim: set syntax=asciidoc:
