README.INSTALL

=== Installing RTAI and LinuxCNC ===

Commands marked with # specify root, commands marked with $ are user commands.


1.) Download the RTAI source

$ git clone https://github.com/NTULINUX/RTAI.git


2.) Patch kernel with IPIPE, in this case we use 5.4.258

# cd /usr/src
# wget https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.4.258.tar.xz
# tar xf linux-5.4.258.tar.xz
# ln -sfv linux-5.4.258 linux
# cd linux
# for i in "/path/to/this/RTAI-git-tree/ksrc/patches/v5.4.258/"*.patch ; do patch -p1 < "${i}" ; done
# make olddefconfig
# make menuconfig

Configure to your needs

# make bzImage && make modules
# make install && make modules_install


3.) Update grub

Refer to your distribution documentation to do this. Generally for newer distros:

# grub-mkconfig -o /boot/grub/grub.cfg


4.) Configure, build and install RTAI (MUST BE BOOTED INTO YOUR NEW RTAI KERNEL)

$ cd ~/RTAI
$ ./autogen.sh
$ make menuconfig

Configure to your needs. You may also use ./configure instead.

For a full list of possible options:

$ ./configure --help

To build and install RTAI:

$ make

# make install


5.) LinuxCNC

Configure LinuxCNC:

$ cd linuxcnc/src
$ ./autogen.sh
$ ./configure

For a full list of possible options:

$ ./configure --help

Now build LinuxCNC:

$ make

Allow LinuxCNC to change permissions as needed (run-in-place):

# make setuid

To test LinuxCNC in a run-in-place environment:

$ cd ../ && . ./scripts/rip-environment

To run LinuxCNC latency test in said environment:

$ latency-test

Or to run LinuxCNC itself:

$ linuxcnc

For more information on building and installing LinuxCNC, please visit:

http://linuxcnc.org/docs/master/html/code/building-linuxcnc.html

Currently, LinuxCNC does not support building Debian packages against RTAI. This behavior should hopefully be restored soon.

=== Creating RTAI Debian packages ===

Remove any previously installed RTAI packages:

# apt-get purge linux-*-rtai* rtai-modules*

Notice: You must run the command above from inside a directory that
does not contain any .deb packages, otherwise you may see errors such as:

E: Unable to locate package linux-5.4.258-rtai_5.4.258-rtai-1_amd64.changes

If you plan on building RTAI and LinuxCNC Debian packages, your kernel must also packaged as well.

For information on building .deb packages for Linux kernels, please visit:

https://wiki.debian.org/BuildADebianKernelPackage

In short, but not too short:

Install required dependencies (or at least most of them) with the following command:

# apt build-dep xorg mesa linux
# apt install fakeroot git patch python3-opengl tcl-dev tk-dev libmodbus-dev bwidget blt mesa-utils libusb-1.0-0-dev libgtk-3-dev libgtk2.0-dev intltool libreadline-dev python3-tk libglu1-mesa-dev libxmu-dev python3-gi-cairo

If things are still missing, it should be easy to tell which.

Download the latest 5.10 kernel from Debian:

https://packages.debian.org/bullseye/amd64/linux-image-5.10.0-25-amd64/download

Decompress the Debian package:

$ ar -x /path/to/linux-image-5.10.0-25-amd64_5.10.191-1_amd64.deb

The above command will leave you with a tarball called data.tar.xz

Extract the tarball containing the kernel configuration file:

$ tar xf /path/to/data.tar.xz

You should now have a directory named "boot" where you decompressed the tarball. Inside that boot directory will be a file called "config-5.10.0-25-amd64"

Prepare the 5.4.258 kernel source:

$ cd ~/
$ wget https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.4.258.tar.xz
$ tar xf linux-5.4.258.tar.xz
$ cd linux-5.4.258
$ for i in "/path/to/this/RTAI-git-tree/ksrc/patches/v5.4.258"/*.patch ; do patch -p1 < "${i}" ; done

Load it accordingly:

$ cp -aLv /path/to/boot/config-5.10.0-25-amd64 .config
$ make olddefconfig

Now modify the two following config parameters using `make menuconfig`:

The first one is the prompt for:

Local version - append to kernel release

And the second is:

Build ID Salt

These options are located within "General setup" in the `make menuconfig` ncurses screen.

The values I have used, respectively and without quotes, are:

"-rtai-amd64"
"5.4.0-25-rtai-amd64"

After saving the configuration file to .config make sure the output to this command:

$ grep -e "^CONFIG_BUILD_SALT" -e "^CONFIG_LOCALVERSION" .config

Looks something like:

CONFIG_LOCALVERSION="-rtai-amd64"
CONFIG_BUILD_SALT="5.4.0-25-rtai-amd64"

The -rtai-amd64 bits are most important. This is so you can build the LinuxCNC RTAI package.

IMPORTANT: The RTAI kernel packages, RTAI modules and LinuxCNC itself must all be built against each other. If any modification is made to the kernel, then the rtai-modules and linuxcnc packages must be re-created as well. DO NOT MIX AND MATCH KERNELS, MODULES AND/OR LINUXCNC! KEEP TRACK OF ALL YOUR WORK!

Generate the Debian kernel package:

$ make -j`nproc` bindeb-pkg

Install the Debian kernel packages:

# dpkg -i /path/to/linux-headers-5.4.258-rtai-amd64_5.4.258-rtai-amd64-1_amd64.deb
# dpkg -i /path/to/linux-image-5.4.258-rtai-amd64_5.4.258-rtai-amd64-1_amd64.deb

If you've previously built kernel packages, you may need to modify your dpkg commands (i.e. replace -1 with -2 etc.)

Update GRUB if Debian did not handle this for you so you can select the RTAI kernel on boot. I handle GRUB from my Gentoo system so GRUB is not even installed for me within Debian.

At this point, you should be booted into your RTAI kernel:

$ uname -r

Should return:

5.4.258-rtai-amd64

Now generate the rtai-modules Debian package:

$ cd ~/RTAI

Make sure the tree is clean and ready to be built:

$ make distclean

Configure the RTAI tree:

$ ./autogen.sh

$ ./debian/configure 5.4.258 rtai amd64

Now you are ready to build the actual package:

$ dpkg-buildpackage -uc -us

Install the rtai-modules package:

# dpkg -i /path/to/rtai-modules-5.4.258_5.3.2-linuxcnc_amd64.deb

As previously stated above,

For information on building and installing LinuxCNC, please visit:

http://linuxcnc.org/docs/master/html/code/building-linuxcnc.html

Currently, LinuxCNC does not support building Debian packages against RTAI. This behavior should hopefully be restored soon.