Skip to content
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

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

Open
wants to merge 6 commits into
base: master
Choose a base branch
from
Open

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
6 commits
Select commit Hold shift + click to select a range
e98ad1d
debian: Declaring deps required only for docs/testing
smoe Oct 8, 2023
dfb63c0
debian: petter reminded about asciidoc required for man pages
smoe Oct 9, 2023
92ac393
Rebased on master. Pointing to selective builds in d/configure
smoe Aug 17, 2024
8a86d50
docs: quick build instructions update
smoe Aug 17, 2024
ab53bd4
debian: Declaring deps required only for docs/testing
smoe Oct 8, 2023
82ebabb
docs: rodw-au on building Debian packages
smoe Aug 31, 2024
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
9 changes: 8 additions & 1 deletion debian/configure
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -195,4 +195,11 @@ 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"
echo " To avoid documentation: DEB_BUILD_OPTIONS=nodocs fakeroot debian/rules binary"
echo " The DEB_BUILD_OPTIONS environment variable also works with dpkg-buildpackage."
34 changes: 17 additions & 17 deletions debian/control.top.in
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,12 +10,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 @@ -34,7 +34,7 @@ Build-Depends:
libusb-1.0-0-dev,
libxmu-dev,
netcat-traditional | netcat-openbsd | netcat,
po4a,
po4a <!nodocs>,
procps,
psmisc,
python3,
Expand All @@ -44,12 +44,12 @@ Build-Depends:
tcl@TCLTK_VERSION@-dev,
tclx,
tk@TCLTK_VERSION@-dev,
xvfb,
xvfb <!nocheck>,
yapps2
Build-Depends-Indep:
@DOC_DEPENDS@,
Build-Conflicts: libjpeg8-dev, libtiff4-dev
Standards-Version: 4.6.1
Build-Conflicts-Arch: libjpeg8-dev, libtiff4-dev
Standards-Version: 4.7.0
Homepage: https://linuxcnc.org/
Vcs-Browser: https://github.com/LinuxCNC/linuxcnc
Vcs-Git: https://github.com/LinuxCNC/linuxcnc.git
Expand All @@ -69,23 +69,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
30 changes: 22 additions & 8 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

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

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
Contributor Author

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,27 +88,30 @@ 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,
# because that's where the `linuxcnc` launcher script looks for them,
# and that's inconvenient to change.
dh_installdocs --doc-main-package=@MAIN_PACKAGE_NAME@ --package=@MAIN_PACKAGE_NAME@
mkdir -p debian/@MAIN_PACKAGE_NAME@/usr/share/doc/linuxcnc
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
58 changes: 43 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 @@ -59,7 +59,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 All @@ -72,6 +73,7 @@ GitHub makes this sharing very easy: After you polish your changes and push them

For the impatient, try this:

[source,console]
----
$ git clone https://github.com/LinuxCNC/linuxcnc.git linuxcnc-source-dir
$ cd linuxcnc-source-dir/src
Expand All @@ -87,12 +89,14 @@ 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:

-----
[source,console]
----
$ sudo make setuid
-----
----

After you have successfully built LinuxCNC it is time to run the tests:

[source,console]
-----
$ source ../scripts/rip-environment
$ runtests
Expand Down Expand Up @@ -165,10 +169,11 @@ 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:

-----
[source,console]
----
$ cd linuxcnc-source-dir/src
$ ./configure --help
-----
----

The most commonly used arguments are:

Expand Down Expand Up @@ -212,10 +217,11 @@ 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:
+
-----
[source,console]
----
$ cd linuxcnc-source-dir/src
$ make ../bin/froboz
-----
----

=== Building Debian Packages

Expand All @@ -234,10 +240,17 @@ 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:

[source,console]
----
$ 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 All @@ -249,6 +262,7 @@ that are detailed below:

Build tools have been gathered as a virtual package named `build-essential`. To install it, run:

[source,console]
----
$ sudo apt-get install build-essential
----
Expand All @@ -257,6 +271,7 @@ Once those prerequisites are met, building the Debian packages consists of two s

The first step is generating the Debian package scripts and meta-data from the git repo by running this:

[source,console]
----
$ cd linuxcnc-dev
$ ./debian/configure
Expand All @@ -274,6 +289,7 @@ to minimize latencies.

Once the Debian package scripts and meta-data are configured, build the package by running `dpkg-buildpackage`:

[source,console]
----
$ dpkg-buildpackage -b -uc
----
Expand Down Expand Up @@ -338,6 +354,7 @@ You can use this meta-data to easily list the required packages missing from you
First, go to the source tree of LinuxCNC and initiate its default self-configuration,
if not already performed:

[source,console]
-----
$ cd linuxcnc-dev
$ ./debian/configure
Expand All @@ -350,6 +367,7 @@ the build-dependencies for those to-be-created packages.
The most straightforward way to get all build-dependencies installed is to just
execute (from the same directory):

[source,console]
----
sudo apt-get build-dep .
----
Expand All @@ -369,9 +387,10 @@ what's missing.

First, install the `dpkg-checkbuilddeps` program by running:

-----
[source,console]
----
$ 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 @@ -388,9 +407,10 @@ 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`):

-----
[source,console]
----
$ 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 Expand Up @@ -425,6 +445,7 @@ Set it to
You should not set this option to gain some extra confidence in your build to perform as expected unless you are running into mere technical difficulties with the test-specific software dependencies.

An environment variable can be set together with the execution of the command, e.g.
[source,console]
----
DEB_BUILD_OPTIONS=nocheck dpkg-buildpackage -uc -B
----
Expand All @@ -437,6 +458,7 @@ The tool installing it, `dpkg` is part of every Debian installation.
The .deb files created by `dpkg-buildpackage` are found in the directory above the linuxcnc-source-dir, i.e. in `..`.
To see what files are provided in a package, run

[source,console]
----
dpkg -c ../linuxcnc-uspace*.deb
----
Expand All @@ -448,6 +470,7 @@ Quit with "q".

To install the packages, run

[source,console]
----
sudo dpkg -i ../linuxcnc*.deb
----
Expand Down Expand Up @@ -485,6 +508,7 @@ The file should contain the following line:
Log out and log back in to make the changes take effect.
Verify that the memory lock limit is raised using the following command:

[source,console]
-----
$ ulimit -l
-----
Expand All @@ -495,6 +519,7 @@ Building on Gentoo is possible, but not supported. Be sure you are
running a desktop profile. This project uses the Tk Widget Set, asciidoc,
and has some other dependencies. They should be installed as root:

[source,console]
-----
~ # euse -E tk imagequant
~ # emerge -uDNa world
Expand All @@ -507,6 +532,7 @@ You can switch back to being a normal user for most of the rest of the
install. As that user, create a virtual environment for pip, then install
the pip packages:

[source,console]
-----
~/src $ python -m venv --system-site-packages ~/src/venv
~/src $ . ~/src/venv/bin/activate
Expand All @@ -516,6 +542,7 @@ the pip packages:

Then you can contrinue as normally:

[source,console]
-----
(venv) ~/src $ git clone https://github.com/LinuxCNC/linuxcnc.git
(venv) ~/src $ cd linuxcnc
Expand All @@ -529,6 +556,7 @@ There is no need to run "make suid", just make sure your user is in
the "dialout" group. To start linuxcnc, you must be in the Python
Virtual Environment, and set up the linuxcnc environment:

[source,console]
-----
~ $ . ~/src/venv/bin/activate
(venv) ~ $ . ~/src/linuxcnc/scripts/rip-environment
Expand Down
Loading