Install packages required for building Debian packages with Docker

These instructions assume that you have sudo rights and that you can execute bash scripts on your machine. You can build the Machinekit-HAL debian package this way which can be then installed on target machine by the apt utility.

As a fist step make sure you can execute Docker CLI commands by installing Docker. The current steps needed for your platform are published in the official Docker documentation. For vast majority of cases following the Debian Buster (current Debian stable version) here will be the right one. Make sure you can run Docker commands without the need for sudo command!

Test the installation by running few basic commands:

machinekit@machinekit:~$ docker --version
Docker version 0.0.0-20190727010531-15bdbd76a5, build 15bdbd76a5
machinekit@machinekit:~$ docker run hello-world
Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
1b930d010525: Pull complete
Digest: sha256:fc6a51919cfeb2e6763f62b6d9e8815acbf7cd2e476ea353743570610737b752
Status: Downloaded newer image for hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
 3. The Docker daemon created a new container from that image which runs the
    executable that produces the output you are currently reading.
 4. The Docker daemon streamed that output to the Docker client, which sent it
    to your terminal.

To try something more ambitious, you can run an Ubuntu container with:
 $ docker run -it ubuntu bash

Share images, automate workflows, and more with a free Docker ID:

For more examples and ideas, visit:


Then you will need to have installed (and from terminal accessible) git CLI. The current steps needed for your platform are published in the official Git documentation. For Debian system and standard official repository this means running:

sudo apt install git

After test that you can successfuly use git by running:

machinekit@machinekit:~$ git --version
git version 2.20.1

This is all you actually need for building Machinekit-HAL Debian packages in Docker containers.

Get and build the Debian packages

Download (clone) the latest Machinekit-HAL repository locally and navigate to its folder.

git clone
cd machinekit-hal

From here run the build_docker script as follows:

scripts/build_docker -t amd64_10 -c deb -n

Where amd64_10 stands for architecture _ debian-version for which you want to have the package build. For example, for example for armhf packages for Debian Stretch you would use armhf_9. More information can be glanced from the official Dovetail Automata GitHUB repository for mk-cross-builder.

This script uses the official pre-build Docker images from Dovetail Automata’s Docker HUB. In case you want to use your own compiled packages (or some other pre-compiled packages from Docker HUB or other container repository), use environment variable when running aforementioned script:

IMAGE=eryaf/mk-cross-builder scripts/build_docker -t amd64_10 -c deb -n

The build objects (with wanted .deb packages) will be created in directory where machinekit-hal resides.

Install packages required for building from source

These instructions assume you have a pristine Debian installation, and you have made sure you have sudo rights. Do not build Machinekit-HAL or Machinekit-CNC as root.

If you have previously installed the machinekit* runtime packages, make sure you have completely removed all of the runtime packages before you continue. To do so, execute sudo apt-get remove --purge machinekit* .

Note that a previous LinuxCNC package install will conflict with building from source, so make sure LinuxCNC packages are removed by sudo apt-get remove --purge linuxcnc .

First, install supporting packages - note you must have configured the apt repository already or the wrong package versions will be installed - see the instructions here to do so.

sudo apt-get install libczmq-dev python-zmq libjansson-dev pkg-config \
  libwebsockets-dev python-pyftpdlib cython bwidget lsb-release git dpkg-dev

sudo apt-get install --no-install-recommends devscripts equivs

Get and build the source

For Machinekit-HAL run the following commands:

# only if you want to follow the step with adding to ~/.bashrc
cd ~
git clone
cd machinekit-hal
sudo mk-build-deps -ir
cd src
# for the Beaglebone, add --with-platform-beaglebone to ./configure
# for the Raspberry2, add --with-platform-raspberry to ./configure
sudo make setuid

# this script checks for missing configuration files
# and will give hints how to remedy:

If you wish to run this installation by default, add the next lines to your ~/.bashrc file, so that every new terminal is set up correctly for running Machinekit-HAL.

echo 'if [ -f ~/machinekit-hal/scripts/rip-environment ]; then
    source ~/machinekit/scripts/rip-environment
    echo "Environment set up for running Machinekit-HAL"
fi' >> ~/.bashrc

However, if you are installing a RIP build onto a system that already has a version of Machinekit* installed as a binary install from packages say, or has other RIP builds, you should invoke from the root dir of the RIP,

. ./scripts/rip-environment

only in terminal sessions where you specifically want to run this RIP.

Users who wish to invoke machinekit-hal (built with Xenomai 2 threads enabled) on a Xenomai 2 realtime kernel must ensure they are members of the xenomai group. If that wasn’t already done when installing the kernel, then add each such user now

sudo adduser <username> xenomai

Logout and login again therafter. (Machinekit-HAL supports only the 2.x version of Xenomai. For most uses use the Preempt_RT patched kernel only.)

To build both Machinekit-HAL and Machinekit-CNC in one step, use special script build_with_cnc in the scripts directory. Please, be advised that this script presumes existence of all needed packages on build machine and does not have provision for errors. To faciliate a issue-less build, try building the Machinekit-HAL package first.

Also, the build_with_cnc script is better run in newly cloned repository of Machinekit-HAL, as it internally clones the Machinekit-CNC repository into the Machinekit-HAL repository.


git clone machinekit-hal-cnc-build
cd machinekit-hal-cnc-build
. ./scripts/rip-environment

You will need to hack the build_with_cnc script for other uses. (Patches welcome!)

A Note on machinekit.ini and the MKUUID

Since inception, /etc/linuxcnc/machinekit.ini has contained a hard coded UUID under the 'MKUUID=' field

This despite the text above it stating that all machines should have a unique MKUUID to enable the zeroconf browsing for particular instances to work.

This has now actually caused problems, with some users exploring the networked communications aspect of machinekit, as perhaps it was originally envisaged.

So, from 16th Jan 2019 onwards, there are a couple of wrinkles to be aware of, if you actually intend using the MKUUID for anything.

RIP builds

A fresh clone will generate a new UUID when built. If you want to use a particular UUID, keep it in a separate system file called /etc/linuxcnc/mkuuid [1] and manually edit RIP/etc/linuxcnc/machinekit.ini to use it. When you rebuild the machinekit.ini UUID will be preserved, however be aware doing a complete ' git clean -xdf && ./ && ./configure' will wipe it.

([1] For RIPs, this file is just a suggested failsafe storage option for now, it will actually be used by package installs)

Package installs

A package install onto a blank system will generate a new UUID.

If you are updating and do not purge your configs:

  • If the package finds an /etc/linuxcnc/mkuuid file [1], it will use the MKUUID within if valid, over any other option.

  • If machinekit.ini exists with a valid UUID, it will use that. Otherwise it will update with the generated UUID.

  • If machinekit.ini is missing even though the previous package was not purged, it will generate one with a valid UUID.

For the vast majority of users, this change will have no impact, their configs just use whatever UUID is in machinekit.ini, if at all, without consequence.

Additional runtime packages you may need


Documentation has been almost completely split from the machinekit build.

Drivers and components built with comp or instcomp, can still be configured to provide documentation for those items only using

./configure --enable-build-documentation

when building machinekit.

The complete documentation is available as below, so this option is only really of interest to developers writing components who wish to check the generated manual page for it.

This package will provide local copies of the manual pages and a man page stub to remind of how to use them.

sudo apt-get install machinekit-manual-pages

It is an optional install for users who wish to use a stand alone system or who have limited internet connectivity.

The same pages can be accessed here: For information on utilities and GUIs For information on the hal and rtapi APIs For information on components and drivers

Additional runtime packages

The above steps outline only the build requirements. There might be some runtime support packages missing if machinekit was never installed before.

The easiest way to fetch all the machinekit runtime packages is to install a current package, and then delete it - the process pulls in all current runtime prerequisites:

sudo apt-get install machinekit-hal machinekit-cnc
sudo apt-get remove --purge machinekit*