1. Einführung

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. and you are encouraged to contribute to the development of LinuxCNC. Generally, you want to compile LinuxCNC yourself for immediate functional access * to a new development of LinuxCNC or * a new development you perhaps want to contribute to LinuxCNC or help other completing it.

You may for instance be porting LinuxCNC to some new Linux distribution or, and this common, a developer reacts to you reporting a problem whose fix you want to test. Any such change will see no buildbot to help, or that help is delayed, pending someone else’s review that you do not want to wait for or you are the only other individual with a particular hardware to test the code.

Besides the programs that control your machine that are built from the source tree, you can also build the same PDFs and/or HTML files that you are likely to have encountered online on https://linuxcnc.org/documents/.

If you want to contribute to LinuxCNC but are uncertain about where to start, please seriously consider to contribute to the documentation. Everyone always finds something to improve - and if you only leave a "FIXME: with a comment" in the text as a reference for yourself and others to revisit a section later. Also, translations to languages other than English are very likely to benefit from your scrutiny at https://hosted.weblate.org/projects/linuxcnc/ .

2. Downloading source tree

The LinuxCNC project git repository is at https://github.com/LinuxCNC/linuxcnc. GitHub is a popular git hosting service and code sharing website.

To retrieve the source tree you have two options:

Download tarball

On the LinuxCNC project page in GitHub find a reference to the "releases" or "tags", click that hyperlink to the archive page and download the latest .tar file. You will find that file compressed as a .tar.xz or .tar.gz file. This file, commonly referred to as a "tarball" is an archive very analogous to a .zip. Your Linux desktop will know how to treat that file when double-clicking on it.

Prepare a local copy of the LinuxCNC repository

You would first install the tool "git" on your machine if it is not available already (sudo apt install git). Then prepare a local instance of the source tree as follows: . 

$ git clone https://github.com/LinuxCNC/linuxcnc.git linuxcnc-source-dir

. The first argument to the git command gives it away: 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 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.

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.

2.1. Schnellstart

Wer ungeduldig ist, kann dies versuchen:

$ git clone https://github.com/LinuxCNC/linuxcnc.git linuxcnc-source-dir
$ cd linuxcnc-source-dir/src
$ ./autogen.sh
$ ./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.

If you are running on a realtime-capable system (such as an install from the LinuxCNC Live/Install Image, see the Realtime section below), one extra build step is needed at this time:

>$ sudo make setuid

Nachdem Sie erfolgreich LinuxCNC gebaut haben, ist es nun Zeit, die Tests durchzuführen:

>$ source ../scripts/rip-environment
>$ runtests

This might fail, too! Read this whole document, especially the section on Setting up the test environment.

3. Unterstützte Plattformen

Das LinuxCNC-Projekt orientiert sich an moderne Debian-basierte Distributionen, einschließlich Debian, Ubuntu und Mint. Wir testen ständig auf den unter http://buildbot.linuxcnc.org aufgeführten Plattformen.

LinuxCNC builds on most other Linux distributions, though dependency management will be more manual and less automatic. Patches to improve portability to new platforms are always welcome.

3.1. Echtzeit

LinuxCNC is a machine tool controller, and it requires a realtime platform to do this job. This version of LinuxCNC supports the following platforms. The first three listed are realtime operating systems:

RTAI

From https://www.rtai.org. A Linux kernel with the RTAI patch is available from the Debian archive at https://linuxcnc.org. See Getting LinuxCNC for installation instructions.

Xenomai

Von https://xenomai.org. Sie müssen einen Xenomai-Kernel selbst kompilieren oder beziehen.

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.

Nicht in Echtzeit

LinuxCNC kann auch auf Nicht-Echtzeit-Plattformen, wie z.B. einer normalen Installation von Debian oder Ubuntu ohne speziellen Echtzeit-Kernel, gebaut und ausgeführt werden. . In diesem Modus ist LinuxCNC nicht nützlich für die Steuerung von Werkzeugmaschinen, aber es ist nützlich für die Simulation der Ausführung von G-Code und für die Prüfung der Nicht-Echtzeit-Teile des Systems (wie die Benutzeroberflächen, und einige Arten von Komponenten und Gerätetreiber). . Um die Echtzeit-Fähigkeiten von LinuxCNC zu nutzen, müssen bestimmte Teile von LinuxCNC mit root-Rechten laufen. Um root für diese Teile zu aktivieren, führen Sie diesen zusätzlichen Befehl nach dem make aus, der LinuxCNC baut: 

>$ sudo make setuid

4. Build-Modi

There are two ways to build LinuxCNC: The developer-friendly "run in place" mode and the user-friendly Debian packaging mode.

4.1. Kompilieren (bauen) für eine Ausführung ohne Installation ("run-in-place")

In a Run-In-Place build, the LinuxCNC programs are compiled from source and then run directly from within the build directory. Nothing is installed outside the build directory. This is quick and easy, and suitable for rapid iteration of changes. The LinuxCNC test suite runs only in a Run-In-Place build. Most LinuxCNC developers primarily build using this mode.

Das Bauen für Run-In-Place folgt den Schritten im Schneller Einstieg Abschnitt am Anfang dieses Dokuments, möglicherweise mit anderen Argumenten für src/configure und make.

4.1.1. src/configure Argumente

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

Die am häufigsten verwendeten Argumente sind:

--with-realtime=uspace

Build for any realtime platform, or for non-realtime. The resulting LinuxCNC executables will run on both a Linux kernel with Preempt-RT patches (providing realtime machine control) and on a vanilla (un-patched) Linux kernel (providing G-code simulation but no realtime machine control). 

If development files are installed for Xenomai (typically from package libxenomai-dev) or RTAI (typically from a package with a name starting "rtai-modules"), support for these real-time kernels will also be enabled.
--with-realtime=/usr/realtime-$VERSION

Bauen Sie für die RTAI-Echtzeitplattform unter Verwendung des älteren "Echtzeit-Kernel" Pakets. Dies erfordert, dass Sie einen RTAI-Kernel und die RTAI-Module in /usr/realtime-$VERSION installiert haben. Die resultierenden ausführbare Dateien von LinuxCNC werden nur auf dem angegebenen RTAI-Kernel laufen. Ab LinuxCNC 2.7, produziert dies die beste Echtzeit-Leistung.

--enable-build-documentation

Erzeuge (engl. build) die Dokumentation zusätzlich zu den ausführbaren Dateien. Diese Option erhöht den Zeitaufwand für die Kompilierung erheblich, da die Erstellung der Dokumentation recht zeitaufwendig ist. Wenn Sie nicht aktiv an der Dokumentation arbeiten, sollten Sie diese Option nicht anwählen.

--disable-build-documentation-translation

Deaktivieren Sie die Erstellung der übersetzten Dokumentation für alle verfügbaren Sprachen. Die Erstellung der übersetzten Dokumentation nimmt sehr viel Zeit in Anspruch, daher ist es empfehlenswert, dies zu überspringen, wenn es nicht wirklich benötigt wird.

4.1.2. make Argumente

Der Befehl make akzeptiert zwei nützliche optionale Argumente.

Parallele Kompilierung

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.

Bauen nur eines bestimmten Ziels

Wenn Sie nur einen bestimmten Teil von LinuxCNC bauen wollen, können Sie das, was Sie bauen wollen, in der Kommandozeile make nennen. Wenn Sie zum Beispiel an einer Komponente namens "froboz" arbeiten, können Sie seine ausführbare Datei zu bauen, indem Sie: 

$ cd linuxcnc-source-dir/src
$ make ../bin/froboz

4.2. Debian-Pakete erstellen

Beim Erstellen von Debian-Paketen werden die LinuxCNC-Programme anhand des Quellcodes kompiliert und dann in einem Debian-Paket gespeichert, komplett mit Abhängigkeitsinformationen. Dieser Prozess beinhaltet standardmäßig auch das Erstellen der Dokumentation, was aufgrund der ganzen I/O-Vorgänge für die vielen Sprachen seine Zeit dauert, aber das kann übersprungen werden. LinuxCNC wird dann als Teil dieser Pakete auf denselben Rechner oder auf jedem Rechner derselben Architektur installiert, auf welchen die .deb-Dateien kopiert wurden. LinuxCNC kann nicht ausgeführt werden, bis die Debian-Pakete auf dem gewünschen Rechner installiert sind und dann die ausführbaren Dateien in /usr/bin und /usr/lib verfügbar sind, genau wie andere reguläre Software des Systems.

Diese Art des Bauens ist vor allem dann nützlich, wenn die Software für die Auslieferung an Endbenutzer verpackt werden soll und wenn die Software für einen Rechner erstellt werden soll, auf dem die Build-Umgebung nicht installiert ist oder der keinen Internetzugang hat.

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.

Building Debian packages requires the dpkg-buildpackage tool the is provided by 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 package named build-essential:

$ sudo apt-get install build-essential

Building Debian packages also requires that all package-specific build dependencies are installed, as described in the section Satisfying Build Dependencies.

Sobald diese Voraussetzungen erfüllt sind, besteht die Erstellung der Debian-Pakete aus zwei Schritten.

Der erste Schritt ist die Generierung der Debian-Paket-Skripte und Metadaten aus dem Git-Repositorium, indem Sie dies ausführen:

$ cd linuxcnc-dev
$ ./debian/configure
Anmerkung

Das Skript debian/configure unterscheidet sich von dem Skript src/configure!

Das debian/configure Skript akzeptiert verschiedene Argumente, abhängig von der Plattform, auf der/für die Sie bauen, siehe den debian/configure Argumente Abschnitt. Ohne weitere Angaben ist er für die Variante von LinuxCNC im user space ("uspace") voreingestellt, einen preempt_rt Kernel erwartend um die Latenzen zu minimieren.

Sobald die Debian-Paket-Skripte und Meta-Daten konfiguriert sind, bauen Sie das Paket, indem Sie dpkg-buildpackage ausführen:

$ dpkg-buildpackage -b -uc
Anmerkung

dpkg-buildpackage needs to run from the linuxcnc-source-dir directory, not from linuxcnc-source-dir/debian.
dpkg-buildpackage takes an optional argument ``-j``N (where N is a number). This enables to run multiple jobs simultaneously.

4.2.1. LinuxCNC’s debian/configure arguments

The LinuxCNC source tree has a debian directory with all the info about how the Debian package shall be built, but some key files within are only distributed as templates. The debian/configure script readies those build instructions for the regular Debian packaging utilities and must thus be run prior to dpkg-checkbuilddeps or dpkg-buildpackage.

The debian/configure script takes a single argument which specifies the underlying realtime or non-realtime platform to build for. The regular values for this argument are:

no-docs

Erstellen der Dokumentation überspringen.

uspace

Konfigurieren Sie das Debian-Paket für Preempt-RT-Echtzeit oder für Nicht-Echtzeit (diese beiden sind kompatibel).

noauto
rtai
xenomai

Normalerweise wird die Liste der RTOS, die uspace Echtzeit unterstützen soll, automatisch erkannt. Wenn Sie möchten, können Sie jedoch eine oder mehrere dieser Optionen nach uspace angeben, um die Unterstützung für diese RTOS zu aktivieren. Um die automatische Erkennung zu deaktivieren, geben Sie noauto an.

Wenn Sie nur die traditionelle RTAI "Kernel-Modul" Echtzeit wollen, verwenden Sie stattdessen -r oder $KERNEL_VERSION.

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.

-r

Konfigurieren Sie das Debian-Paket für den aktuell laufenden RTAI-Kernel. Sie müssen einen RTAI-Kernel auf Ihrer Build-Maschine laufen haben, damit dies funktioniert!

$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, e.g. "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.

4.2.2. Erfüllen von Build-Abhängigkeiten

Auf Debian-basierenden Plattformen bieten wir Paketierungs-Metadaten, die wissen, welche externen Softwarepakete installiert werden müssen, um LinuxCNC zu bauen. Dies wird Build-Abhängigkeiten von LinuxCNC genannt, d.h. heißt solche Pakete, die installiert sein müssen, damit * das Bauen wird erfolgreich beendet und * der Vorgang kann bitidentisch reproduziert werden.

Sie können diese Meta-Daten verwenden, um die benötigten Pakete aufzulisten, die aus Ihrem Build-System fehlt. Gehen Sie zunächst zum Quellbaum von LinuxCNC und starten Sie seine Standard-Selbstkonfiguration, wenn nicht bereits ausgeführt:

$ cd linuxcnc-dev
$ ./debian/configure

Dies bereitet die Datei debian/control vor, die Listen von zu erstellenden Debian-Paketen enthält mit den Angaben von weiteren Paketen, die zur Laufzeit von LinuxCNC benötigt werden und für unseren Zweck auch eine Liste für die Pakete, die für die Kompilierung von LinuxCNC benötigt werden (engl. Build-Dependencies).

Der einfachste Weg, um alle Build-Dependencies installiert ist folgendes auszuführen (aus demselben Verzeichnis):

sudo apt-get build-dep .

which will install all the dependencies required but available. The . is part of the command line, i.e. an instruction to retrieve the dependencies for the source tree at hand, not for dependencies of another package. This completes the installation of build-dependencies.

Der Rest dieses Abschnitts beschreibt einen halbmanuellen Ansatz. Die Liste der Abhängigkeiten in debian/control ist lang und es ist mühsam, den aktuellen Zustand der Installation mit den bereits installierten Paketen mit dieser Liste zu vergleichen. Debian-Systeme bieten ein Programm namens dpkg-checkbuilddeps, das die Paket-Metadaten analysiert und die als Build-Abhängigkeiten aufgelisteten Pakete mit der Liste der installierten Pakete vergleicht und Ihnen sagt, was fehlt.

Installieren Sie zuerst das Programm dpkg-checkbuilddeps, indem Sie es ausführen:

$ 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. You can use this meta-data to easily list the required packages missing from your build system. You may decide to manually inspecting those files if you have a good understanding what is already installed.

Alternatively, Debian systems provide a program called dpkg-checkbuilddeps that parses the package meta-data and compares the packages listed as build dependencies against the list of installed packages, and tells you what’s missing. Also, dpkg-buildpackage would inform you about what is missing, and it should be fine. However, it reports missing build-deps only after patches in debian/patches are applied (if any). If you are new to Linux and git version management, a clean start may be preferable to avoid complications.

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

manually

Install them all with sudo apt-get install, followed by the package names. You can rerun dpkg-checkbuilddeps any time you want, to list any missing packages, which has no effect on the source tree.

automated

Run sudo apt build-dep . .

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.

4.2.3. Options for dpkg-buildpackage

For a typical Debian package to build, you would run dpkg-buildpackage without any arguments. As introduced above, the command has two extra options passed to it. Like for all good Linux tools, the man page has all the details with man dpkg-buildpackage.

-uc

Do not sign the resulting binaries. You would want to sign your packages with a GPG key of yours only if you would wanted to distribute them to others. Having that option not set and then failing to sign the package would not affect the .deb file.

-b

Only compiles the architecture-dependent packages (like the linuxcnc binaries and GUIs). This is very helpful to avoid compiling what is hardware-independent, which for LinuxCNC is the documentation. That documentation is available online anyway.

If you happen to run into difficulties while compiling, check the LinuxCNC forum online. Currently emerging is the support for the DEB_BUILD_OPTIONS environment variable. Set it to

nodocs

to skip building the documentation, preferably instead use the -B flag to dpkg-buildpackage.

nocheck

to skip self-tests of the LinuxCNC build process. This saves some time and reduces the demand for a few software packages that may not be available for your system, i.e. the xvfb in particular. You should not set this option for some extra confidence in your build to perform as expected unless running into difficulties with the dependencies.

An environment variable can be set together with the execution of the command, e.g.

DEB_BUILD_OPTIONS=nocheck dpkg-buildpackage -uc -B

would combine all the options introduced in this section.

4.2.4. Installing self-built Debian packages

A Debian package can be recognised by its .deb extension. The tool installing it, dpkg is part of every Debian installation. The .deb files created by dpkg-buildpackage are found in the directoy above the linuxcnc-source-dir, i.e. in ... To see what files are provided in a package, run

dpkg -c ../linuxcnc-uspace*.deb

The version of LinuxCNC will be part of the file name, which is meant to be matched by the asterisk. There may be too many files listed to fit on your screen. If you cannot scroll up in your terminal then add | more to that command to have its output passed through a so-called "pager". Quit with "q".

To install the packages, run

sudo dpkg -i ../linuxcnc*.deb

5. Einrichten der Umgebung

Dieser Abschnitt beschreibt die speziellen Schritte, die benötigt werden, um eine Maschine einzurichten, um die LinuxCNC-Programme auszuführen, einschließlich der Tests.

5.1. Erhöhen Sie das Limit für den gesperrten Speicher

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.

Bei Verwendung der Preempt-RT-Echtzeitplattform läuft LinuxCNC mit genügend Privilegien, um seine Speichersperrgrenze selbst zu erhöhen. Bei Verwendung der RTAI-Echtzeit-Plattform hat es nicht genug Privilegien, und der Benutzer muss die Speichersperre Grenze zu erhöhen.

Wenn LinuxCNC beim Start folgende Meldung zeigt, ist das Problem die für Ihre System konfigurierte Grenze des gesperrten Speichers:

RTAPI: ERROR: failed to map shmem
RTAPI: Locked memory limit is 32KiB, recommended at least 20480KiB.

Um dieses Problem zu beheben, fügen Sie eine Datei namens /etc/security/limits.d/linuxcnc.conf (als root) mit Ihrem bevorzugten Texteditor hinzu (z.B. sudo gedit /etc/security/limits.d/linuxcnc.conf). Die Datei sollte die folgende Zeile enthalten:

* - memlock 20480

Melden Sie sich ab und wieder an, damit die Änderungen wirksam werden. Überprüfen Sie mit dem folgenden Befehl, ob die Speichersperrgrenze angehoben wurde:

$ ulimit -l

6. Kompilieren (bauen) für Gentoo

Bauen auf Gentoo ist möglich, aber nicht unterstützt. Achten Sie darauf, dass Sie ein Desktop-Profil ausführen. Dieses Projekt verwendet das Tk Widget Set, Asciidoc und hat einige andere Abhängigkeiten. Sie sollten als root installiert werden:

~ # euse -E tk imagequant
~ # emerge -uDNa world
~ # emerge -a dev-libs/libmodbus dev-lang/tk dev-tcltk/bwidget dev-tcltk/tclx
~ # emerge -a dev-python/pygobject dev-python/pyopengl dev-python/numpy
~ # emerge -a app-text/asciidoc app-shells/bash-completion

Sie können wieder zu einem normalen Benutzer für den überwiegenden restlichen Teil der Installation wechseln. Als dieser Benutzer erstellen Sie eine virtuelle Umgebung für pip, dann installieren Sie die pip Pakete:

~/src $ python -m venv   --system-site-packages ~/src/venv
~/src $ . ~/src/venv/bin/activate
(venv) ~/src $ pip install yapps2
(venv) ~/src $

Dann können Sie regulär weitermachen:

(venv) ~/src $ git clone https://github.com/LinuxCNC/linuxcnc.git
(venv) ~/src $ cd linuxcnc
(venv) ~/src $ cd src
(venv) ~/src $ ./autogen.sh
(venv) ~/src $ ./configure --enable-non-distributable=yes
(venv) ~/src $ make

Es gibt keine Notwendigkeit zur Ausführung von "make suid", nur stellen Sie sicher, dass Ihr Benutzer in der "dialout" Gruppe ist. Um linuxcnc zu starten, müssen Sie in der Python Virtual Environment sein und die linuxcnc Umgebung einrichten:

~ $ . ~/src/venv/bin/activate
(venv) ~ $ . ~/src/linuxcnc/scripts/rip-environment
(venv) ~ $ ~/src/linuxcnc $ scripts/linuxcnc

7. Optionen zum Auschecken des Git-Repos

Die Schnellstart Anleitung am Anfang dieses Dokuments klont unser Git-Repository auf https://github.com/LinuxCNC/linuxcnc.git. Dies ist der schnellste und einfachste Weg um loszulegen. Es gibt jedoch auch noch andere Optionen, die Sie in Betracht ziehen sollten.

7.1. Forken Sie uns auf Github

Das LinuxCNC Projekt git repo ist auf https://github.com/LinuxCNC/linuxcnc. github ist ein beliebter git Hosting-Service und Code-Sharing-Website. Sie können ganz einfach (und kostenlos) einen Fork unseres Git-Repos bei Github erstellen und diesen verwenden, um Ihre Änderungen zu verfolgen und zu veröffentlichen.

Nachdem Sie Ihren eigenen Github-Fork von LinuxCNC erstellt haben, klonen Sie ihn auf Ihren Entwicklungsrechner und fahren Sie wie gewohnt mit den von Ihnen gwünschten Änderungen (gerne auch "hacking" genannt) fort.

Wir vom LinuxCNC-Projekt hoffen, dass Sie Ihre Änderungen mit uns teilen werden, damit die Gemeinschaft von Ihrer Arbeit profitieren kann. Github macht dieses Teilen sehr einfach: Nachdem Sie Ihre Änderungen aufpoliert und in Ihren Github-Fork gepusht haben, schicken Sie uns einen Pull Request.