HOWTO: Gentoo for LinuxCNC

IMPORTANT: If using SystemRescue, any block device will easily be susceptible to destruction. It is your responsibility to ensure the correct device is selected upon execution! The author of this wiki and the installer is not responsible for any damages or loss of data. To ensure the integrity of your data, unplug any and all devices that you will not be using for the install in advance.

IMPORTANT: It is strongly advised to backup all data before proceeding!

Prerequisites

For using the installer, you must have the following:

• btrfs-progs
• dosfstools
• e2fsprogs
• f2fs-tools
• git (required for fetching the installer)
• parted
• xfsprogs
• b3sum
• OPTIONAL: syslinux (if burning SystemRescue) or syslinux-utils if using Debian

All of these are included in SystemRescue however these can all be installed on Debian 12/Bookworm. Versions of Debian older than 12/Bookworm will not work.

There is no support for RAID or LVM configurations.

A working internet connection is also required. This is not only to fetch the installer, but also because the installer downloads the required files for the Gentoo system (~2GB of data.)

OPTIONAL: Downloading SystemRescue

If you intend on using SystemRescue, download the latest version from here:

https://www.system-rescue.org/Download/

For a UEFI installation of Gentoo, you must have UEFI runtime services available. This means that you must be booted into a UEFI enabled environment, such as SystemRescue in UEFI mode, or a Linux system booted with UEFI. Note that if you are already booted with UEFI but are running a PREEMPT_RT kernel, you must specify `efi=runtime` on the kernel command line. This is because by default, UEFI runtime services are disabled with PREEMPT_RT.

To minimize confusion and possibly booting up with the wrong environment, it is recommended to disable CSM (Compatibility Support Module) completely if you intend on a UEFI installation. This way, the system cannot boot in legacy BIOS mode. On the other hand, if you wish to use legacy BIOS, make sure CSM is enabled and if applicable, disable UEFI boot support and specify, "Legacy OpROM."

If you wish to use the same USB device as SystemRescue for the Gentoo installation, you must use the "copytoram" function. This can be selected when first booting into SystemRescue at the GRUB menu.

SystemRescue for UEFI (Recommended)

isohybrid --uefi <path-to-System-Rescue.iso>

Example:

isohybrid --uefi /home/lcnc/systemrescue-11.03-amd64.iso

SystemRescue for Legacy BIOS

isohybrid -s 63 -h 255 <path-to-System-Rescue.iso>

Example:

isohybrid -s 63 -h 255 /home/lcnc/systemrescue-11.03-amd64.iso

OPTIONAL: Burning SystemRescue to USB

Before inserting the USB device that will be used as SystemRescue, as root, run:

fdisk -l

Or:

lsblk

To list available block devices.

After inserting the USB device, re-run the same command again. The device that did not appear before is most likely the intended target.

Do not specify a partition. If for example you have:

/dev/sda1
/dev/sda2
/dev/sda3

Then after plugging in the USB device, you have:

/dev/sda1
/dev/sda2
/dev/sda3
/dev/sdb1
/dev/sdb2

You would likely use /dev/sdb as the USB device.

IMPORTANT: All data on the device will be destroyed so proceed with caution!

IMPORTANT: If umount fails at all, you may have accidentally selected your root filesystem block device.

The asterisk is a wild card and not a typo. This is so any partitions are unmounted first by `umount` before executing the `dd`.

As root, run:

umount /dev/<USB block device>*
dd if=/path/to/system-rescue.iso of=/dev/<USB block device> bs=8M oflag=sync status=progress

Example:

umount /dev/sdb*
dd if=/path/to/system-rescue.iso of=/dev/sdb bs=8M oflag=sync status=progress

Fetching the installer

Once booted off the USB device with SystemRescue or from a currently working Debian 12/Bookworm installation:

In a terminal, run the following three commands:

git clone https://github.com/NTULINUX/gentoo_backup.git
cd gentoo_backup	
git checkout linuxcnc

If using SystemRescue, the network configuration may need to be modified as it defaults to DHCP. You may either run `startx` and modify the network configuration graphically, or use `nmtui` to use the ncurses interface.

Running the installer

Once you are in the gentoo_backup directory, simply run:

./installer.sh

sudo/root privileges are required.

Upon installation, you will be asked some questions in regards to UEFI or legacy BIOS for GRUB, filesystem type and filesystem sizes. If you specify any erroneous options, or a filesystem size that is too large for the block device, the script will fail.

IMPORTANT: All data on the device specified during installation will be destroyed so proceed with caution!

IMPORTANT: Theoretically, it should be possible to boot the Gentoo image off a USB device when specifying legacy BIOS during the install, however it fails to boot on the author's system. It is therefore suggested to specify UEFI during the installation for USB devices.

IMPORTANT: For NVMe devices, UEFI is required.

Finishing up

You should see a message if the program ran successfully. Reboot and select the Gentoo media.

The password for root and lcnc (the regular Linux user) is: gentoo-cnc123

Use NetworkManager to add or modify network settings. A working internet connection is required for the remaining steps. Due to licensing restrictions (something to do with GNU readline) LinuxCNC cannot be pre-packaged in binary form.

You will need to run the following to compile and install LinuxCNC:

sudo emerge --sync
sudo emerge linuxcnc

After installation, you must log out and log back in again for the new environment variables (TCLLIBPATH and PYTHONPATH) to be set.

LinuxCNC will show up under "Accessories" in the applications menu, as well as latency histogram, latency test and some others.

By default, a simple firewall (nftables) has been enabled. If you wish to fully and permanently disable the firewall, run:

sudo rc-service nftables clear
sudo rc-service nftables stop