Merge pull request #2647 from smoe/debian_nocheck

debian: introducing nodocs and nocheck DEB_BUILD_OPTIONS (smoe:debian_nocheck)

Author: andypugh

debian/changelog

@@ -8,6 +8,9 @@ linuxcnc (1:2.10.0~pre0) UNRELEASED; urgency=medium
     depend on defaults passed by dpkg-buildflags on
     Ubuntu and Debian (LP: #2104012)
 
+  [ Steffen Moeller ]
+  * Introducing DEB_BUILD_OPTIONS to d/rules.
+
  -- Pushkar Kulkarni <[email protected]>  Mon, 24 Mar 2025 20:50:08 +0530
 
 linuxcnc (1:2.9.4-2) unstable; urgency=medium

debian/configure

@@ -14,15 +14,25 @@ set -e
 
 usage () {
     P=${0##*/}
-    cat <<EOF
+    cat 1>&2 <<EOF
 $P: Set up debian/ files to build for a particular kernel
 
 Usage:
   $P [no-docs]
 
   Extra options:
-    no-docs
-        Skip building documentation
+
+    no-docs|nodocs
+        Skip building documentation.
+        Debian packaging will not know about documentation to exist at all.
+        If configured regularly but with the intent not to build the docs,
+        run "DEB_BUILD_OPTIONS=nodocs dpkg-buildpackage".
+
+    sim|uspace|noauto
+        Accepted for compatibility, but now ignored.
+
+    -h|--help|help
+	Show this help.
 EOF
 }
 
@@ -47,8 +57,12 @@ ENABLE_BUILD_DOCUMENTATION=--enable-build-documentation=pdf
 while test $# -ne 0; do
     case "$1" in
     sim|uspace|noauto) echo "$1 is accepted for compatibility, but ignored";;
-    no-docs) unset ENABLE_BUILD_DOCUMENTATION ;;
-    *) echo 1>&2 "Unknown option: $1"; exit 99 ;;
+    help|-h|--help) usage; exit 0 ;;
+    no-docs|nodocs) unset ENABLE_BUILD_DOCUMENTATION ;;
+    *)  echo 1>&2 "Unknown option: $1"
+        echo 1>&2
+	usage
+        exit 99 ;;
     esac
     shift
 done
@@ -195,4 +209,15 @@ fi
 
 
 rm -f ../build-stamp
-echo "successfully configured for '$DISTRIB_NAME'.."
+echo "I: Successfully configured for '$DISTRIB_NAME'."
+
+echo "I: You can now start the build of LinuxCNC Debian packages."
+echo "   To build and test everything: fakeroot debian/rules binary"
+echo "   To build the executables and man pages only: fakeroot debian/rules binary-arch"
+echo "   To avoid tests: DEB_BUILD_OPTIONS=nocheck debian/rules binary"
+if [ -n "$ENABLE_BUILD_DOCUMENTATION" ]; then
+    echo "   To avoid documentation: DEB_BUILD_OPTIONS=nodocs fakeroot debian/rules binary"
+else
+    echo "   Building of documentation is disabled."
+fi
+echo "   The DEB_BUILD_OPTIONS environment variable also works with dpkg-buildpackage."

debian/control.top.in

@@ -12,12 +12,12 @@ Build-Depends:
     @KERNEL_HEADERS@,
     @MODUTILS_DEPENDS@,
     @EXTRA_BUILD@,
-    docbook-xsl,
+    docbook-xsl <!nodocs>,
     asciidoc,
-    ghostscript,
-    groff-base,
-    imagemagick,
-    asciidoc-dblatex,
+    ghostscript <!nodocs>,
+    groff-base <!nodocs>,
+    imagemagick <!nodocs>,
+    asciidoc-dblatex <!nodocs>,
     autoconf,
     automake,
     bwidget (>= 1.7),
@@ -37,7 +37,7 @@ Build-Depends:
     libxmu-dev,
     netcat-traditional | netcat-openbsd | netcat,
     netpbm,
-    po4a,
+    po4a <!nodocs>,
     procps,
     psmisc,
     python3,
@@ -51,8 +51,10 @@ Build-Depends:
     yapps2
 Build-Depends-Indep:
     @DOC_DEPENDS@,
-Build-Conflicts: libjpeg8-dev, libtiff4-dev
-Standards-Version: 4.7.0
+Build-Conflicts-Arch:
+    libjpeg8-dev,
+    libtiff4-dev
+Standards-Version: 4.7.2
 Homepage: https://linuxcnc.org/
 Vcs-Browser: https://github.com/LinuxCNC/linuxcnc
 Vcs-Git: https://github.com/LinuxCNC/linuxcnc.git
@@ -72,23 +74,23 @@ Section: devel
 Description: PC based motion controller for real-time Linux
  LinuxCNC is a fully-realised CNC machine controller that can interpret
  machine-control programs (such as G-code), plan trajectories and finally
- output low-level signals to machine control hardware
+ output low-level signals to machine control hardware.
  .
- LinuxCNC is modular and in principle the HAL (hardware abstraction layer),
- pluggable interpreters and variety of hardware drivers mean that it can
- control almost any software-defined physical system.
+ LinuxCNC is modular, thus in principle its HAL (hardware abstraction
+ layer) together with pluggable interpreters and variety of hardware
+ drivers can control almost any software-defined physical system.
  .
  LinuxCNC relies on a realtime kernel to support real-time motion control,
- typically updating the position waypoints every 1mS and reacting to
- input within tens of microseconds.
+ typically updating the position waypoints every millisecond and reacting
+ to input within tens of microseconds.
  .
  Modules exist to use the low-level parts of LinuxCNC as a motion-control
  client for OpenPnP. Interfaces exist for ROS (the Robot Operating System)
  with which LinuxCNC has considerable overlap.
  .
  LinuxCNC supports arbitrary kinematics (the mapping between coordinate
- space and actuator space) and can control both parallel (eg Stewart
- platform) and serial (eg robot arm) systems in addition to conventional
+ space and actuator space) and can control both parallel (e.g., Stewart
+ platform) and serial (e.g., robot arm) systems in addition to conventional
  cartesian machine tools.
  .
  LinuxCNC supports 9 cartesian axes and 16 "Joints" (individual actuators)

debian/rules.in

@@ -32,7 +32,9 @@ export TIME=$(shell LANG=C date --date='@$(TIMESTAMP)' '+%T')
 
 kernel_version = @KERNEL_VERSION@
 configure_realtime_arg = @CONFIGURE_REALTIME_ARG@
+ifeq (,$(filter nodocs,$(DEB_BUILD_OPTIONS)))
 enable_build_documentation = @ENABLE_BUILD_DOCUMENTATION@
+endif
 SRCDIR = $(CURDIR)/src
 DESTDIR=$(CURDIR)/debian/tmp
 DEV_PACKAGE_NAME=@MAIN_PACKAGE_NAME@-dev
@@ -55,18 +57,25 @@ override_dh_auto_build-arch:
 	dh_auto_build -- build-software
 
 override_dh_auto_build-indep:
+ifeq (,$(filter nodocs,$(DEB_BUILD_OPTIONS)))
 ifneq "$(enable_build_documentation)" ""
 	dh_auto_build -- manpages
 	dh_auto_build -- translateddocs
 	dh_auto_build -- docs
 endif
+endif
 
 override_dh_auto_clean:
 	if [ -r src/Makefile.inc -a -r src/config.status ]; then \
 	dh_auto_clean; \
 	py3clean .; \
 	fi
 
+override_dh_auto_test:
+ifeq (,$(filter nocheck,$(DEB_BUILD_OPTIONS)))
+	dh_auto_test
+endif
+
 override_dh_auto_install-arch:
 	# Install all architecture-dependent libraries and executables
 	# in DESTDIR (the staging dir for the main package).
@@ -79,6 +88,7 @@ override_dh_auto_install-arch:
 	rm -f $(DESTDIR)/usr/share/doc/@MAIN_PACKAGE_NAME@/examples/sample-configs/*/*position*.txt
 
 override_dh_installdocs-arch:
+ifeq (,$(filter nodocs,$(DEB_BUILD_OPTIONS)))
 	# Sample configs go in `usr/share/doc/linuxcnc` (not `.../doc/@MAIN_PACKAGE_NAME@`)
 	# because that's where the `linuxcnc` launcher script looks for them,
 	# and that's inconvenient to change.
@@ -87,19 +97,21 @@ override_dh_installdocs-arch:
 	mv debian/@MAIN_PACKAGE_NAME@/usr/share/doc/@MAIN_PACKAGE_NAME@/examples debian/@MAIN_PACKAGE_NAME@/usr/share/doc/linuxcnc
 
 	dh_installdocs --doc-main-package=@MAIN_PACKAGE_NAME@ --package=@MAIN_PACKAGE_NAME@-dev
-
+endif
 
 override_dh_auto_install-indep:
+ifeq (,$(filter nodocs,$(DEB_BUILD_OPTIONS)))
 	DESTDIR=$(DESTDIR) $(MAKE) -C src install-docs install-doc
 	# Remove the docs we just built that we don't have debs for yet...
 	rm -f $(DESTDIR)/usr/share/doc/linuxcnc/*_nb.pdf
+endif
 
 override_dh_installdocs-indep:
+ifeq (,$(filter nodocs,$(DEB_BUILD_OPTIONS)))
 	# The G-code quick reference html docs are built as `docs/html/${LANG}/gcode.html`.
-	# We install them into `/usr/share/doc/@MAIN_PACKAGE_NAME@/` in each
-	# linuxcnc-doc-${LANG} package, then rename them there (except
-	# for the English one) to include the language in the filename,
-	# so they don't collide when we install all the doc debs.
+	# We install them into `/usr/share/doc/@MAIN_PACKAGE_NAME@/` in each # linuxcnc-doc-${LANG} package,
+	# then rename them there (except for the English one) to include the language in the filename,
+	# so they do not collide when we install all the doc debs.
 	#
 	# Rename the "main" doc directories from
 	# `usr/share/doc/@MAIN_PACKAGE_NAME@` to `usr/share/doc/linuxcnc`,
@@ -116,8 +128,10 @@ override_dh_installdocs-indep:
 		$(RM) debian/tmp/usr/share/doc/linuxcnc/LinuxCNC_*_$$l.pdf; \
 	done
 	$(RM) debian/tmp/usr/share/doc/linuxcnc/*_es.adoc
-
-
+else
+	# Avoiding error message because of examples
+	$(RM) -fr debian/tmp/usr/share/doc/
+endif
 
 override_dh_compress:
 	dh_compress -X.pdf -X.txt -X.hal -X.ini -X.clp -X.var -X.nml -X.tbl -X.xml -Xsample-configs

docs/src/code/building-linuxcnc.adoc

@@ -60,7 +60,8 @@ $ git clone https://github.com/LinuxCNC/linuxcnc.git linuxcnc-source-dir
   This is called a "clone" of the LinuxCNC repository.
   The advantage is that this local clone supports the communication about changes you may decide to perform on the source tree.
 
-GitHub is an infrastructure on its own and explained in depth elsewhere. Just to get you motivated if you do not know it already.offers to perform a clone for you and have that instance made publicly available.
+GitHub is an infrastructure on its own and explained in depth elsewhere.
+Just to get you motivated if you do not know it already.offers to perform a clone for you and have that instance made publicly available.
 GitHub refers to such an additional instance of another repository as a "fork".
 You can easily (and at no cost) create a fork of the LinuxCNC git repository 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.
@@ -88,9 +89,9 @@ Especially the section on <<Satisfying-Build-Dependencies,Satisfying Build Depen
 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 below), one extra build step is needed at this time:
 
------
+----
 $ sudo make setuid
------
+----
 
 After you have successfully built LinuxCNC it is time to run the tests:
 
@@ -163,10 +164,10 @@ The `src/configure` script configures how the source code will be compiled.
 It takes many optional arguments.
 List all arguments to `src/configure` by running this:
 
------
+----
 $ cd linuxcnc-source-dir/src
 $ ./configure --help
------
+----
 
 The most commonly used arguments are:
 
@@ -210,10 +211,10 @@ 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:
 +
------
+----
 $ cd linuxcnc-source-dir/src
 $ make ../bin/froboz
------
+----
 
 === Building Debian Packages
 
@@ -232,10 +233,16 @@ delivery to end users, and when building the software for a machine
 that does not have the build environment installed, or that does not 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, likely supported by the LinuxCNC GitHub repository referenced below.
-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.
+For the impatient, try this:
+
+----
+$ sudo apt-get install build-essential
+$ git clone https://github.com/LinuxCNC/linuxcnc.git linuxcnc-source-dir
+$ cd linuxcnc-source-dir/src
+$ ./debian/configure
+$ sudo apt-get build-dep .
+$ DEB_BUILD_OPTIONS=nocheck dpkg-buildpackage -uc -B
+----
 
 Building Debian packages is performed with the `dpkg-buildpackage` tool that is
 provided by the `dpkg-dev` package. Its execution comes with a series of prerequisites
@@ -368,9 +375,9 @@ what's missing.
 
 First, install the `dpkg-checkbuilddeps` program by running:
 
------
+----
 $ sudo apt-get install dpkg-dev
------
+----
 
 This generates the file `debian/control` in a user-readable yaml-format
 which lists the build-dependencies close to the top.
@@ -387,9 +394,9 @@ If you are new to Linux and git version management, a clean start may be prefera
 The `dpkg-checkbuilddeps` (also from the dpkg-dev package that is installed as part of the build-essential dependencies) program
 can be asked to do its job (note that it needs to run from the `linuxcnc-source-dir` directory, *not* from `linuxcnc-source-dir/debian`):
 
------
+----
 $ dpkg-checkbuilddeps
------
+----
 
 It will emit a list of packages that are required to build LinuxCNC on your system but are not installed, yet.
 You can now install missing build-dependencies