Building LinuxCNC

For the impatient, try this:

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:

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

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

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:

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.

Building for Run-In-Place follows the steps in the Quick Start section at the top of this document, possibly with different arguments to src/configure and make.

When building Debian packages, the LinuxCNC programs are compiled from source and then stored in a Debian package, complete with dependency information. This process by default also includes the building of the documentation, which takes its time because of all the I/O for many languages, but that can be skipped. LinuxCNC is then installed as part of those packages on the same machines or on whatever machine of the same architecture that the .deb files are copied to. LinuxCNC cannot be run until the Debian packages are installed on a target machine and then the executables are available in /usr/bin and /usr/lib just like other regular software of the system.

This build mode is primarily useful when packaging the software for 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.

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 that are detailed below: * general build infrastructure shall be installed, i.e. compilers, etc. * build-time dependencies are to be installed, i.e. header files for external code libraries used, as described in the section Satisfying Build Dependencies. * file in debian folder need to be complete that describe the package

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

Once those prerequisites are met, building the Debian packages consists of two steps.

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

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

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.

When using the Preempt-RT realtime platform LinuxCNC runs with enough privilege to raise its memory lock limit itself. When using the RTAI realtime platform it does not have enough privilege, and the user must raise the memory lock limit.

If LinuxCNC displays the following message on startup, the problem is your system’s configured limit on locked memory:

To fix this problem, add a file named /etc/security/limits.d/linuxcnc.conf (as root) with your favorite text editor (e.g., sudo gedit /etc/security/limits.d/linuxcnc.conf). 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:

The LinuxCNC project git repo is at https://github.com/LinuxCNC/linuxcnc. GitHub is a popular git hosting service and code sharing website. You can easily (and at no costs) create a fork (a second instance holding a copy that you control) of the LinuxCNC git repository at GitHub. You can then use that fork of yours to track and publish your changes, receive comments to your changes and accept patches from the community. .

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.