First, we need to download the rootfs tarball. You can do the following in order to obtain the rootfs. If you are using an i686 machine, replace the x86_64 with i686. We are setting this in a URL variable so that we don't have to write it every time.

  URL=https://dl.carbslinux.org/releases/x86_64
  wget $URL/carbs-rootfs.tar.xz.sha256
  sha256sum -c carbs-rootfs.tar.xz.sha256

It is highly recommended to verify the signature of the tarball. You will need the OpenBSD tool signify(1) for this. Many distributions provide a package for it, if you are using a Carbs Linux host, you can also install the package otools which provides signify. Download the signature first.

  wget $URL/carbs-rootfs.tar.xz.sig

The signature file should say something similar to

untrusted comment: verify with carbslinux-2023.02.pub
RWTe38zmx+iyuKEL5T84MJ5Y24jqenkTtQLJxbaMzOBS/NkGVl5J+Vn2B6vTV/gJK7LYBPS+IOXV5sEf+YLGCMcBYAGHCcP4xQ8=

Grab the key (which probably should be the latest one) that is written on the file from https://dl.carbslinux.org/keys/ so you can verify the signature. The latest Signify public key is also available on the package repository, so you can check the validity of the public key from multiple locations, or just copy paste that portion to a file and use that instead.

  PUBKEY=carbslinux-2023.02.pub
  wget https://dl.carbslinux.org/keys/$PUBKEY

You can now verify the distribution tarball with signify.

  signify -V -m carbs-rootfs.tar.xz -p $PUBKEY

If everything went alright, this should output:

  Signature Verified

You will need to extract the tarball to your desired location. For partitioning, you can follow this guide. This will assume that you will be mounting your root partition to /mnt.

  mount /dev/sdx1 /mnt
  tar xf carbs-rootfs.tar.xz -C /mnt

Newest tarballs do not come with repositories, so you will need to manually obtain them, and set your CPT_PATH environment variable. Carbs Linux repositories can either be obtained by git or rsync. While rsync repositories are overall faster and smaller, git offers the whole history of the repository and a means to manipulate your repository as you like it. If you want to obtain the git repository, you will need to install git itself.

The following guide will assume that you put the repositories into ~/repos/ directory, but you can put the repositories into any directory you want. So go ahead and create that directory:

  mkdir -p $HOME/repos

  git clone git://git.carbslinux.org/repository $HOME/repos/carbs

  rsync -avc rsync://vaylin.carbslinux.org/repo $HOME/repos/carbs

  CPT_PATH=$HOME/repos/carbs/core
  CPT_PATH=$CPT_PATH:$HOME/repos/carbs/extra
  CPT_PATH=$CPT_PATH:$HOME/repos/carbs/wayland
  CPT_PATH=$CPT_PATH:$HOME/repos/carbs/community
  export CPT_PATH

It is good practice to make sure your system is up to date, especially before building new packages. If there is an update for the package manager you will need to update twice.

  cpt-update && cpt-update

Since you are operating on a really small base, you might need to build and install new programs to extend the functionality of your system. In order to build and install packages new packages in Carbs, you need to execute the following. "Package" is not actually a package and is given as an example.

  cpt-build   package
  cpt-install package

Here is a small list of software that you might want to have on your system as you are setting up. You might want to check the Software section in the full documentation to learn more about other packaged software.

BOOTLOADERS

• efibootmgr
• grub

FILESYSTEMS

• e2fsprogs
• dosfstools
• ntfs-3g

NETWORKING

• dhcpcd
• wpa_supplicant

TEXT EDITORS

• nano
• vim

DOCUMENTATION

• carbs-docs
• man-pages
• man-pages-posix

All the documentation for Carbs Linux can be found on a single info manual to be viewed offline. You can obtain either texinfo or the info packages in order to view the documentation.

  # Install the documentation.
  cpt b carbs-docs && cpt i carbs-docs

  # Install either texinfo or the info package. We will be installing standalone info
  # as it doesn't need perl.
  cpt b info && cpt i info

  # You can then run info and navigate through the documentation.
  info carbslinux

You might want to add a hostname, especially in a networked environment. Your hostname will default to 'carbslinux' unless you set this.

  echo your-hostname > /etc/hostname

You can edit your /etc/hosts file, which is the static lookup table for host names. By default, there are two entries for localhost which are OKAY. You can replace the 'localhost' part of these entries to your hostname.

  127.0.0.1  localhost.localdomain localhost
  ::1        localhost.localdomain localhost ip6-localhost

Creating a new user is not strictly necessary, but it is highly recommended. Especially for building packages, it is the safest option to create an unprivileged user and using doas for doing operations that require root privileges. The code block below describes how to create a user (named foo), add them to the wheel group, and to give doas permissions to the wheel group

  # Create the new user
  adduser foo

  # Add the user to the wheel group
  addgroup foo wheel

  # Give root permission to the wheel group using doas
  echo permit persist :wheel >> /etc/doas.conf

You are also advised to take a look at the doas configuration file and the manual page of doas.

After you are finished you can switch to the new user by running

  su foo

You can visit the https://kernel.org website to choose a kernel that you want to install. Though only the latest stable and longterm (LTS) versions are supported. Note that kernel releases are quite rapid, and the version below is likely outdated, so don't run it verbatim.

  # Download the kernel and extract it
  wget https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.19.4.tar.xz
  tar xJf linux-5.19.4.tar.xz

  # Change directory into the kernel sources
  cd linux-5.19.4

NOTE: If you want to validate the kernel signature, install the gnupg2 package, and follow the instructions provided at https://kernel.org/category/signatures.html.

In order to compile the kernel you will need to install some dependencies. You will need libelf, and bison to compile the kernel. If you want to configure using the menu interface you will also need ncurses.

  # The package manager asks to install if you are building more than one package,
  # so no need to run 'cpt i ...'
  cpt b libelf ncurses

In the vanilla kernel sources, you need perl to compile the kernel, but it can be easily patched out. You will need to apply the following patch. Patch was written by E5ten. You will need to obtain and apply the patch in the kernel source directory.

  wget https://dl.carbslinux.org/distfiles/kernel-no-perl.patch
  patch -p1 < kernel-no-perl.patch

Next step is configuring and building the kernel. You can check Gentoo's kernel configuration guide to learn more about the matter. Overall, Gentoo Wiki is a good place to learn about configuration according to your hardware. The following will assume a monolithic kernel.

  make menuconfig
  make
  install -Dm755 $(make -s image_name) /boot/vmlinuz-linux

In the main repository, there is efibootmgr and grub to serve as bootloaders. efibootmgr can be used as a standalone bootloader, or can be used to install grub in a UEFI environment. efibootmgr is needed unless you are using a device without UEFI support (or you really want to use BIOS for a reason).

  cpt b grub && cpt i grub
  grub-install --target=i386-pc /dev/sdX
  grub-mkconfig -o /boot/grub/grub.cfg

  cpt b efibootmgr && cpt i efibootmgr
  cpt b grub && cpt i grub

  grub-install --target=x86_64-efi \
               --efi-directory=esp \
               --bootloader-id=CarbsLinux

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

Only thing left to do is installing the init-scripts, and now you are almost ready to boot your system!

  cpt b carbs-init && cpt i carbs-init

You can now manually edit your fstab entry, or you can use the genfstab tool. If you want to use the tool, exit the chroot and run the following:

  wget https://github.com/cemkeylan/genfstab/raw/master/genfstab
  chmod +x genfstab
  ./genfstab -U /mnt >> /mnt/etc/fstab

The IRC channel for Carbs Linux is located in #carbslinux on libera.chat. You can install the catgirl package from the repository, or use a client of your preference to join. Feel free to ask for help, or have a general chat.

There have been recent changes to the kiss package manager that breaks compatibility with cpt. These changes throw away the entire premise of their "static" packaging system. cpt will never implement those changes, so don't expect any KISS package that was changed during or after July 2021 to work with cpt.