Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
andypugh merged 2 commits into from
Sep 5, 2025
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e6b72db
debian: Declaring deps required only for docs/testing
smoe Oct 8, 2023
5acd111
docs: [source,console] -> ""
smoe Sep 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions debian/changelog
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
37 changes: 31 additions & 6 deletions debian/configure
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
}

Expand All @@ -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
Expand Down Expand Up @@ -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."
34 changes: 18 additions & 16 deletions debian/control.top.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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),
Expand All @@ -37,7 +37,7 @@ Build-Depends:
libxmu-dev,
netcat-traditional | netcat-openbsd | netcat,
netpbm,
po4a,
po4a <!nodocs>,
procps,
psmisc,
python3,
Expand All @@ -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
Expand All @@ -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)
Expand Down
28 changes: 21 additions & 7 deletions debian/rules.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Comment on lines +60 to +66
Copy link
Collaborator

@petterreinholdtsen petterreinholdtsen Oct 17, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it really a good idea to have two ways to set the same flag? I suspect this will break the principle of least surprise. What should happen if someone enable documentation building and use the nodocs option? Which one should take effect? I suspect it is better to only have one flag, and allow both the option and the enable setting to set or unset this flag. At the moment this patch allow nodocs to override enable_documentation. Is that least surprising?

Copy link
Collaborator

@petterreinholdtsen petterreinholdtsen Oct 18, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest to ensure enable_build_documentation is "" if nodocs is set, and use only this test in the code, to ensure not two partly overlapping settings are used in the code.

Copy link
Collaborator Author

@smoe smoe Oct 20, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just had a look at it again. The "enable_build_documentation" is set by debian/configure.in - and I agree with you, this should just always be enabled and the decision to build or not be left to Debian's regular semantics, i.e. the DEB_BUILD_OPTIONS parameters. The point of this patch is to help transitioning towards that change of control. So, now you can decide not to package the documentation (by adding the nodocs) even though the configuration (by debian/configure) was expecting you to build it. The other way around does not work - you cannot enable the building of the documentation by omitting the nodocs if you have previously disabled it in debian/configure. I tend to think this is all very much how it should be - given the constraint to impose minimal changes to the current code base.

On a sidenote, at the beginning of debian/rules.in, there is

ifeq (,$(filter nodocs,$(DEB_BUILD_OPTIONS)))
enable_build_documentation = @ENABLE_BUILD_DOCUMENTATION@
endif

so enable_build_documentation will only be available if nodocs is not an option. I tend to think I am happy with how it is. I am uncertain if we should already use the nodocs/nocheck flags in our CI.


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).
Expand All @@ -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.
Expand All @@ -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`,
Expand All @@ -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
Expand Down
37 changes: 22 additions & 15 deletions docs/src/code/building-linuxcnc.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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

Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand Down
Loading