Compiling LinuxCNC from Source Code
There have been people to ask the question of how to run LinuxCNC on a Linux distribution of their choice. This is possible and actually a fairly simple thing to do. If you want to run LinuxCNC as a simulator for gcode, then you can start right away, but if you wish to use LinuxCNC as a controller, it only becomes a little more complicated because you have to have a realtime kernel for it to work properly. I addressed how to compile a realtime kernel using the PREEMPT_RT patch in a separate tutorial. You can find the written tutorial on my webpage at the following address: http://myheap.com/cnc-stuff/linuxcnc-emc2.html. You can read the tutorial there by following the link or download a PDF version of the tutorial by clicking on the PDF icon next to the title. Additionally, I made a video tutorial of the process as part of the LinuxCNC for the Home Hobbyist series. You can find a link to watch the video on the same page as above, or you can watch it on YouTube by using this link: https://www.youtube.com/watch?v=RjTfKF7gcIo. If your intention is to use LinuxCNC as a controller of a machine, I encourage you to take a look at the above tutorial and video.
This tutorial is based on Lubuntu 18.04 32-bit version. This distribution was selected do to its lightweight desktop. While this is not the newest release of Lubuntu, it is the newest available LTS (Long Term Support) available at the time of this writing.
The computer I prepared for use with this tutorial has Lubuntu 18.04 i386 installed on it using the normal installation option with the download updates while installing box checked. After installation all updates were completed and the system rebooted. To finish setting up the computer, a realtime kernel was compiled using the PREEMPT_RT patch and installed on the machine.
Getting the computer ready
We will need the source code repository from Ubuntu to perform some of the work which we will need to do. To add the source code repository in Lubuntu, click the menu button → System Tools → Synaptic Package Manager. You will need to enter your password and click OK to open the software. We need to make two changes here. The first one will add the source code repository to our list of repositories. Click Settings from the top menu and select repositories from the sub-menu. A dialog will open up with several tabs across the top of it. The first tab reads Ubuntu Software, on this tab, locate the line that reads Source code and check the box to indicate that we want software from that repository. The second change we want to make is to inform Lubuntu that we do not want to do any upgrades to a newer version of Ubuntu. If we did, we would lose our realtime kernel and the LinuxCNC controller would not work for us anymore. Locate the third tab on the top that reads Updates and click on it. On this page where it reads “Notify me of a new Ubuntu Version” click the drop down box and select Never from the list. With our changes out of the way click the close button on the dialog. Lubuntu will then inform you that its list of repositories has changed. Click the reload button to reload the repositories into Lubuntu. We are finished with Synaptic Package Manager so go ahead and close it.
With that out of the way, we will now update the system to make sure everything is ready to go. Open a terminal either using the shortcut icon or by pressing [CTRL][ALT][T] on the keyboard. Now in your terminal enter the following command:
sudo apt update
This command checks for any changes in the software repositories and compares its software list to the software we have installed on the computer. Remember, we are potentially making changes to the system and will have to provide our password. When it is complete, apt will notify you if there are newer software versions available. Let’s go ahead and update anything out there before we start on compiling LinuxCNC by issuing the following command:
sudo apt dist-upgrade
The dist-upgrade directive passed to apt tells apt that we want to upgrade our software but unlike using just upgrade, dist-upgrade will also handle any changing dependencies from old software to the new software.
Finally, this tutorial assumes that you have compiled your own realtime kernel. If you have you are all set. If you have not compiled a realtime kernel because you are only interested in running LinuxCNC as a gcode simulator then we will need to install the software compiler to permit the computer to compile the LinuxCNC source code. You can install the compiler with the following command:
sudo apt install build-essential
With the preliminary work completed with the computer, we can carry on.
Getting the LinuxCNC Source Code
We will start this adventure by getting the LinuxCNC source code. The LinuxCNC source is hosted on a site called github. Github specializes in storing and tracking the changes to source code for different projects, and you can get the code in one of two ways. First you could open your browser and navigate to https://github.com/LinuxCNC/linuxcnc, select the branch you are interested in and click the Clone or download button, or you can use the git application and get it all. In this tutorial I will use git to download the LinuxCNC source code as it allows easy switching from the current development source tree to the stable 2.7 source tree as you please. Like most things in the Linux world, we will need to install some software to make this happen.
Open a terminal by pressing [CTRL][ALT][T] or clicking the launcher for the terminal if you don’t already have it open. For the duration of this tutorial we will be working within the terminal environment. Also as a side note, there will be a video of this tutorial that you can watch to help clarify issues that may arise. Now that we have a terminal open, we need to install the git software that will download and manage the source code for us. Enter the following command in the terminal.
sudo apt install git
Because we are installing software that potentially makes changes to the system, we have to run the sudo command. When you press enter the computer will ask for your password and then offer to install the related packages. Enter Y and press the enter key and let it do its thing.
Now that we have the git software installed we can use it to download the LinuxCNC source code from the github website. Git is software for managing revision histories of file and is mostly used with source code. While we are only going to use it to retrieve and select a particular branch of the LinuxCNC software, it is good to keep in mind that it can do much, much more. I will leave those things for you to discover on your own. To download the LinuxCNC source code in the terminal, type the following command.
git clone git://github.com/linuxcnc/linuxcnc.git linuxcnc-dev
The above command runs the git program. The parameter clone means we wish to get a full copy of the source code, or a clone of it as you will. The next part, git://github.com/linuxcnc/linuxcnc.git tells the software where the repository is located and finally, the linuxcnc-dev tells git that we want it copied into a folder called linuxcnc-dev. Git will give you some status messages while it does its job and when it is finished will return you to the prompt.
Now if you type the ls command in the terminal you will see a new folder called linuxcnc-dev that contains the code we downloaded. Now let’s change to the linuxcnc-dev folder by using the following command.
cd linuxcnc-dev
What version of LinuxCNC to compile
We have reached a point where we need to decide what version of LinuxCNC that we wish to compile. Recall I told you that Git manages changes in files and is typically used for computer source code. Git also allows you to branch your source code to work on things without affecting your previous work. When you are satisfied with your new work, git can be used to merge the new stuff with the old stuff. Now the developers at LinuxCNC use this feature to keep what they are working on currently separated from the stuff that they have already written and is considered stable. At the time of this writing the main development software called 2.8 pre1 is located in the main branch on git. This main branch is referred to as the master branch or just master. The last stable release of LinuxCNC is version 2.7.x. This is managed as a separate branch in git called simply 2.7. By default when we download the source code git will be pointing to the master branch or version 2.8 pre1. If you want to compile the stable 2.7 version of LinuxCNC, we will need to tell git to switch to that branch of code. Doing this is as simple as telling git that you want to use that branch. To select the 2.7 branch use the following command:
git checkout 2.7
If you change your mind and decide you would rather compile the 2.8 pre1 version of LinuxCNC, then simply check that branch back out. Remember the newest version of the LinuxCNC software is called master. You can do that with the following command:
git checkout master
The checkout command given to git tells git that you want to use a specific branch of code. In the example above the 2.7 branch for LinuxCNC 2.7 or the master branch for LinuxCNC 2.8 pre1.
One last thing before continuing that I want to mention is that LinuxCNC sometimes is very actively developed and things can be added or changed relatively quickly. Because of this, I would recommend that you use git to retrieve any changes to the source code since you initially cloned the repository. We just cloned the source so there isn’t likely to be any changes, but if it has been a few days since you cloned the repository, it would be good check anyway.
To update our source code with any changes that may have happened on the LinuxCNC GitHub repository we only need to run the following command.
git pull
The pull command will get any changes and merge them with the code we have for the branch we have checked out. To clarify this, say we have checked out branch 2.7 with the command git checkout 2.7, then when we use the command git pull, any changes that have been made to the 2.7 branch source code will be merged with ours. It would be a good idea to run gut pull any time you change branches of source code.
Now that I have covered all that, decide which version you want to compile, check out the appropriate branch and do a pull to make sure you have the most updated code.
Installing the required dependencies
Just like when we compiled the Linux Kernel, LinuxCNC will require some additional software to be installed before we can compile it. This software, in programming parlance, is called build dependencies. Determining which software you need can be easy or a little tricky depending on which distribution of Linux you have selected. If you have a Debian based Linux distribution, then the developers have provided meta-data that will examine your system and list the various packages that you will need to install to allow the computer to build the software. To be able to utilize this feature we will need to again install a bit of extra software. Install the devscripts, dpkg-dev and python software by using the following command in your terminal.
sudo apt install devscripts dpkg-dev python
Because we are making changes to the system, we again use the sudo command. Enter your password if prompted. If the package is already installed apt will inform you that you already have it. Otherwise apt will install the software. Now to determine what dependencies that need to be installed we need to move to the debian directory and run the configuration script. Change to the debian directory by issuing the following command:
cd ~/linuxcnc-dev/debian
The configure script located in this directory configures the debian packaging. It must be run if you want to either get the system to give you a list of dependencies or if you want to create a debian package files that can be installed on the system. The script takes several options but the only one we will concern ourselves with is the uspace option. Uspace tells the script that we will be building for either a PREEMPT_RT realtime system or a non-realtime system. These are compatible for our needs. Now issue the command:
./configure uspace
If all went well, you should see a message that reads “successfully configured for ‘uspace-Ubuntu-18.04’” To get a list of dependencies that we need to install, we will run the dpkg-checkbuilddeps tool. This program will need to be run from the linuxcnc-dev folder. Move to this folder by entering the following command:
cd ..
This command changes the directory and the two dots mean move up to the parent folder. Now lets run the dependency check by running the following command.
dpkg-checkbuilddeps
The output of this command will list all the software packages that need to be installed to successfully compile the LinuxCNC software. You can install them with the following command:
sudo apt install <package name>
You can install multiple packages at the same time by specifying the packages separated by spaces, like so:
sudo apt install <package name> <package name> <...> …
Depending on whether you want to compile the LinuxCNC 2.8 pre1 version or the 2.7 version the dependencies may differ slightly. Below is a list of dependencies that can be installed that will take care of every scenario in this tutorial. You can copy and paste the section of code in your terminal to install all of them at the same time.
sudo apt install debhelper dh-python libudev-dev libxenomai-dev \ tcl8.6-dev tk8.6-dev libreadline-gplv2-dev asciidoc \ dvipng graphviz groff imagemagick inkscape python-lxml \ source-highlight texlive-font-utils texlive-lang-cyrillic \ texlive-lang-french texlive-lang-german texlive-lang-polish \ texlive-lang-spanish w3c-linkchecker python-dev python-tk \ libxmu-dev libgtk2.0-dev intltool libboost-python-dev \ libusb-1.0-0-dev yapps2 libglu1-mesa-dev libgl1-mesa-dev \ dblatex docbook-xsl texlive-extra-utils texlive-fonts-recommended \ texlive-latex-recommended xsltproc gettext autoconf libmodbus-dev \ asciidoc-dblatex libxaw7-dev bwidget libtk-img tclx python-gtk2
After entering your password, if asked, press Y to install the packages. There is a lot of software to install, so stretch your legs and get a beverage of your choice. When it has finished come back here.
Another Decision to make … Compile Uspace or deb packages
Now that the required dependency packages are installed, it is time for you to make another decision. Do you want to compile the software for a RIP Environment, which means run in place, or do you want installable debian packages? Let me briefly talk about the difference between the two.
The Run In Place (RIP) environment does not install any software on the computer, but instead leaves the compiled software in the source tree. Running the software will require you to source a script called rip-environment each time you log into the system. The script sets up the computers environment to allow the software to run, by adding relevant paths and other information. This is considered the developers environment because you can compile multiple versions of the LinuxCNC software and at any time run whichever you please.
Compiling debian install packages on the other hand is considered the user friendly route. It will create the binary and documentation deb packages that you can install on the computer that give you the well known cnc menu entry with shortcuts to start the software. This is what you would see if you are familiar with the current live install CD available from the linuxcnc.org website.
The choice to compile either the RIP environment or debian package option of LinuxCNC is your choice. I will cover both in this tutorial. Simply go to the heading that matches your decision.
Compiling LinuxCNC for the RIP Environment
This section of the tutorial explains how to compile LinuxCNC for a Run In Place (RIP) Environment. If you want to see how to compile LinuxCNC for installable Debian packages, see the heading below titled, “Compiling LinuxCNC for Debian Packages”.
Now that all the dependencies are installed we can now begin compiling LinuxCNC. At this point you should be in the linuxcnc-dev folder. To compile the software we need to change into the src directory. Do this by entering the following command:
cd src
Now that we are in the src directory we can start. First we will run the autogen.sh script. Its job is to create the configure script that will be used to configure LinuxCNC software for compilation. Enter the command:
./autogen.sh
It will appear that nothing happened, but in the background, the configure script will have been created. The configure script configures how the source code will be compiled and there are many options you can use. I will briefly examine and talk about only two of them. These options are --with-realtime and --enable-build-documentation.
The first option --with-realtime tells the configure script what realtime system you are using. For example, preempt_rt, xenomai or rtai. In our case, we will either want to compile LinuxCNC as a simulator using the installed vanilla kernel, or we will want to compile LinuxCNC as a machine controller using the PREEMPT_RT realtime kernel that we installed. Fortunately for us, the value to use with --with-realtime is the same. That option will be called uspace. If you are interested in using a different --with-realtime option, for an RTAI kernel, for example, please see the configure documentation. Issuing a ./configure -h will show all the options.
The Second option, --enable-build-documentation requires no arguments. If you want to build the LinuxCNC documentation along with the executables then add this option to the configure switch. Building the documentation does take a little longer to complete, so if you’re not interested in having a local copy built, feel free to leave it off.
Now that we know what the options are we can compile the software. I will include the latest documentation with the build, so in the terminal issue the following command:
./configure --with-realtime=uspace --enable-build-documentation
The configure script will check the system looking for all the dependencies required to build the software. If any are missing, it will error and tell you what needs to be installed. If all went well, you will get a notification in a big box telling you that the configure script completed successfully. Now that we are done configuring LinuxCNC, we can compile it. Now, before we compile, I should remind you that the make program can utilize multiple processor cores. Using multiple cores will speed up the process somewhat. To tell make to use multiple cores we pass it the -j flag along with the number of cores we would like it to use. If you are unsure how many cores your computer has type the following command:
nproc
The result will be a number indicating how may processor cores are available. Say for example, your computer returned the value of 2. We can tell make to use both cores by passing -j2 on the command line, for example:
make -j2
Will run make and compile using 2 cores. Choose whatever selection you want here and let the software compile. For example:
make
Compiling the LinuxCNC software and documentation will take a bit of time. Nothing like compiling the realtime kernel, but you will still have enough time get a drink and relax. Come back when the compile is finished.
Giving permissions to LinuxCNC
Now that the software is compiled, we only need to run another command to have a complete LinuxCNC system. LinuxCNC will need permission to access the hardware on the computer if you are running in realtime. To do this we will run make with the setuid option. Because this changes the file to run as root and sets the sticky bit, it will have to be run with elevated privileges. To do this, enter the following command:
sudo make setuid
Everything is now in place to start using your newly compiled LinuxCNC system. Now, what we finished compiling here is what is called Run In Place or RIP. And to use it, we must source the environment before running any of the LinuxCNC software. To do this, we can issue the command:
source ~/linuxcnc-dev/scripts/rip-environment
This command will source variable that are needed by LinuxCNC to run properly. Keep in mind that you have to do this every time you log into the machine.
Most of the software will be located in either the bin or scripts directories. Paths to these are created for you when you source the rip-environment script. Enjoy your newly compiled LinuxCNC software.
Compiling LinuxCNC for Debian Packages
This section describes how to compile LinuxCNC to create installable Debian packages. If you are interested in compiling LinuxCNC for use in a Run In Place please see the section above titled, “Compiling LinuxCNC for the RIP Environment”.
Compiling LinuxCNC to make Debian packages is almost too easy to believe. At this point all the dependencies have been installed. We only have a couple more things to do to get the job done. You should be in the linuxcnc-dev folder to complete these steps. If not enter the following command in the terminal.
cd ~/linuxcnc-dev
We will use a program called dpkg-checkbuilddeps to get the system ready to build the Debian install packages. This program checks the installed packages in the system against the build dependencies and build conflicts listed in the control file. If there are any issues it will report them and exit. For example, if you are missing any of the required programs required to build the software. Since we installed all the build dependencies in the last step, it should return nothing to us. Enter the following command in the terminal.
dpkg-checkbuilddeps
When dpkg-checkbuilddeps has finished running we only need to issue one more command to kick off the job. Enter the following command in the terminal.
debuild -uc -us
The debuild program will configure LinuxCNC and compile it and its documentation. The process does take a little while to complete. When it has finished you will find several .deb files in your home directory.
Installing the Deb packages
Now that the software has been compiled and made into installable Debian packages you are free to install them. When debuild creates the packages, you will end up with several located in your home directory. When compiling LinuxCNC version 2.7 I got the following packages. I have listed them below with a short description of what each is.
linuxcnc-doc-en_2.7.14_all.deb – LinuxCNC documentation in English
linuxcnc-doc-es_2.7.14_all.deb – LinuxCNC documentation in Spanish
linuxcnc-doc-fr_2.7.14_all.deb – LinuxCNC documentation in French
linuxcnc-uspace_2.7.14_i386.deb – LinuxCNC software for i386 (32bit system)
linuxcnc-uspace-dev_2.7.14_i386.deb – LinuxCNC development files for i386 (32bit system)
You can install the deb files in a couple of ways. You can install them from command line by using a command like the following:
sudo apt install ~/linuxcnc-uspace_2.7.14_i386.deb
The above command tells the apt program to install the package located in the home folder named linuxcnc-uspace_2.7.14_i386.deb. Another method of installing the deb files is to open the file browser and double click the deb file and have the graphical package installer install the package for you.
Installing from the deb file will place an entry in the menu with relevant links to LinuxCNC and its documentation.
I hope this tutorial has removed some of the mystery of compiling LinuxCNC from source code. Thank you for participating.
END OF TUTORIAL
Last Update 29 MAY 2019