debian: Declaring deps required only for docs/testing

smoe · smoe · commit e1c148b2d1b1 · 2025-09-03T19:08:58.000+01:00
debian: petter reminded about asciidoc required for man pages

Rebased on master. Pointing to selective builds in d/configure

docs: quick build instructions update

debian: Declaring deps required only for docs/testing

docs: rodw-au on building Debian packages

debian: Adjusting d/{configure,control,rules.in} to rebase and review
diff --git a/debian/changelog b/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 <pushkar.kulkarni@canonical.com>  Mon, 24 Mar 2025 20:50:08 +0530
 
 linuxcnc (1:2.9.4-2) unstable; urgency=medium
diff --git a/debian/configure b/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."
diff --git a/debian/control.top.in b/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)
diff --git a/debian/rules.in b/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
diff --git a/docs/src/code/building-linuxcnc.adoc b/docs/src/code/building-linuxcnc.adoc
