This is the full documentation of Carbs Linux, from the details of the distribution, installation, to the package manager. It is not yet complete.

• Copying
• Installation
  • Preparing Environment
    • Download
    • Signature verification
    • Extracting the tarball
  • Chroot
    • Setting up repositories
    • Updating packages
    • Installing packages
    • Essential Software
    • Obtaining the documentation
  • System Configuration
    • Configuring hostname
    • Hosts file
    • Creating a user
  • Kernel
    • Obtaining the kernel sources
    • Kernel dependencies
    • Building the kernel
  • Making your system bootable
    • Bootloader
    • Init scripts
    • Fstab
  • Post-installation
    • IRC
    • KISS repositories
• Software
  • Init System
    • Configuring Init
    • Changing Init Program
  • Wayland
    • Enabling the Wayland repository
    • Switching from Xorg
    • Installing a Compositor
• Contribution Guidelines
  • Conventions
    • Shell Conventions
    • Repository Conventions
  • Contributing to the Community repository
  • Sending Patches
    • Git Patches
    • Fossil Patches
• GNU Free Documentation License

Copyright © 2020-{{{time(%Y)}}} Cem Keylan

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts and no Back-Cover Texts. A copy of the license is included in the section entitled “GNU Free Documentation License.”

These are the step-by-step instructions for installing Carbs Linux. It can be acquired as plain-text to be viewed offline with a pager from https://carbslinux.org/install.txt.

curl -sL https://carbslinux.org/install.txt | less

To install Carbs Linux, you will need a Live Linux ISO. For that purpose, you can obtain a Gentoo or Void Linux live image. You can follow their instructions to boot and setup your network.

You will need the following programs in order to install Carbs Linux:

• tar
• wget
• xz
• some form of base utilities (coreutils, sbase, busybox, etc.)

Rest of these instructions will assume that you have set all of these up, and will continue on that point.

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>>
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

Chroot into Carbs Linux by running the chroot helper inside the rootfs!

/mnt/bin/cpt-chroot /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

Carbs Linux git repositories can be found both from the main server and GitHub (mirror). Here are both their repository links. You can clone any of them.

• https://git.carbslinux.org/repository
• https://git.sr.ht/~carbslinux/repository

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

Carbs Linux rsync repositories live in rsync://carbslinux.org/repo. In order to obtain it, run the following:

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

In your shell’s configuration file, or in your ~/.profile file, add the following lines:

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

After you have finished installing some extra packages, you can configure your system to your liking.

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

Kernel isn’t managed under the main repositories, even though you could package one for your personal use. Here is an example kernel package, which you will need to reconfigure for your specific setup if you want to make use of it.

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 order to be able to boot your fresh system, wou will need an init-daemon, init-scripts and a bootloader. The init daemon is already provided by busybox, but you can optionally change it.

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 base installation is now complete, you can now fine tune your system according to your needs. Rest of these instructions are completely optional. You can check the rest of the documentation to learn more about the system.

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.

The distribution aims to package essential and useful software needed in a practical system. If the repository lacks a package that you use, you may also easily package it yourself or request it to be added to the default repositories over on the IRC channel (#carbslinux on Libera).

This section goes over the details of some packaged software

Carbs Linux init scripts are run by the init daemon (busybox by default) on boot and shutdown processes. It also provides its own halting program named shalt. This provides a portable method that doesn’t rely on non-POSIX external programs.

There are three ways you can change the behaviour of the init system. Those are:

• Kernel Command Line
• /etc/init/rc.conf file
• Init Hooks

On GRUB, you can edit the kernel command line parameters, which will be parsed as variables on the init system. Not all of the parameters will be acted upon, but all of them will be set as variables on the init script. For example an example command line, and how it is interpreted.

BOOT_IMAGE=/boot/vmlinuz root=/dev/sda2 rw loglevel=3 quiet

This command line will be parsed to set the following variables:

BOOT_IMAGE=/boot/vmlinuz
root=/dev/sda2
rw=1
loglevel=3
quiet=1

Some of these variables, such as rw=/=ro, loglevel, and quiet, will be used by the init system to change the behaviour of the startup.

However, the kernel command line isn’t the only place to set your boot parameters. You can specify variables here as well, although note that the kernel command line always gets the priority for these variables since they can be set just before boot.

Init hooks are for custom personal commands that the user may want to add to alter their boot. These can be used to load kernel modules, modify interfaces, and lot more. Those hooks are added to the /etc/init directory with the hook name as the suffix. For example, a boot script will be placed as /etc/init/my-hook.boot. Currently, there are 4 hooks that the user can use.

early-boot

Run after pseudo-filesystems are mounted.

boot

Run before the boot stage is completed.

pre.shutdown

Run first when shutting down.

umount

Run just before filesystems are unmounted.

post.shutdown

Run just before the system is halted.

By default, Carbs Linux comes preinstalled with busybox-init, but this can easily be replaced without any issues. Currently, available init systems are:

• sinit
• busybox init
• runit
• shinit

This example is for runit, but it will work with all init systems packaged in the distribution repositories. See the cpt-alternatives(1) manual page for more details.

cpt a runit /usr/bin/init
cpt a runit /usr/bin/poweroff
cpt a runit /usr/bin/reboot

After switching init systems, your running init system may not accept the new poweroff commands. You will need to reboot/poweroff using the running init’s utilities for the new utilities to work. These commands are for the init system currently running on your system and not the one you are switching to.

Carbs Linux only supports Wayland displays as of January 2023. If your system makes use of the X.org display system, read the section Switching from Xorg.

Wayland is a modern display server protocol intended as a replacement for Xorg. Wayland has a much simpler architecture compared to X by its careful design and implementation. Users who want to use a Wayland compositor should follow this section.

The wayland repository requires packages from xorg and extra repositories. So you should set your $CPT_PATH so that core and extra repositories precede the wayland repository, and the xorg repository should come after wayland. Here is an example below, where $REPOSITORY points to the root of your repository.

CPT_PATH=$REPOSITORY/core
CPT_PATH=$CPT_PATH:$REPOSITORY/extra
CPT_PATH=$CPT_PATH:$REPOSITORY/wayland
export CPT_PATH

After you have enabled your repositories, go ahead and install wayland and wayland-protocols packages.

cpt-build wayland wayland-protocols

If you are already an Xorg user, you will need to rebuild some packages so that they support wayland. If you don’t have an xorg system, feel free to skip this step. The packages that need a rebuild are:

• gtk+3
• gtk4
• mesa
• webkit2gtk

For xorg support inside wayland sessions, you need to install the xwayland package.

The wayland repository currently only contains sway as a Wayland compositor, but you can package something else for your own.

cpt bi sway

Thanks for taking your time to contribute! To maintain stylistic behaviour throughout the repositories, one must adhere to these conventions. Exceptions and changes may occur with good reasoning.

{{{contid(0010)}}}

Try to keep the file readable.

{{{contid(0011)}}}

Characters on a line shouldn’t exceed 100 characters.

{{{contid(0012)}}}

Make sure you don’t have code commented out during commit. Uncomment them or remove them completely.

{{{contid(0013)}}}

Do not add comments following the code, add them to the top of the code. It makes it harder to read, and lines longer. Here is an example:

# Good way of commenting.
your code goes here

your code goes here  # Avoid this way of commenting.
    

Shell is central to Carbs Linux projects. Most of the tools and packages are written in POSIX sh.

{{{contid(1010)}}}

Use 4 spaces for indentation, don’t use tabs.

{{{contid(1020)}}}

Make sure you don’t use bash-specific code.

{{{contid(1030)}}}

Make sure you lint your code with shellcheck and if you are new to POSIX sh, use checkbashisms.

{{{contid(1040)}}}

Don’t spawn new processes if you don’t absolutely need to, especially during string manipulation.

{{{contid(1041)}}}

Never use a program for text manupilation that isn’t defined in the POSIX standard. This includes gawk and perl.

{{{contid(1042)}}}

Instead of $(basename $file), use ${file##*}.

{{{contid(1043)}}}

Instead of $(dirname $file), use ${file%/*}.

# This is the same thing as basename /path/to/test.asc .asc

$ file=/path/to/test.asc file=${file##*/} file=${file%.asc}
$ echo $file
test
    

{{{contid(1050)}}}

Instead of backticks, use $(..).

Repository conventions are important in order to ensure every package resemble themselves. Here are the things to keep in mind:

{{{contid(2010)}}}

Prefer tarballs over git packages unless there is a sensible reason. Here are some:

• Every patch is a new release. (See vim)
• There are no releases. (See sbase)
• Following a development branch.
• There has been a long time since the latest release, but upstream is far ahead.

{{{contid(2020)}}}

Prefer sources without a dependency to automake. There are usually distribution tarballs that are autoconf‘ed. Don’t submit tarballs with an automake dependency unless you are sure there is no alternative.

{{{contid(2030)}}}

Avoid these packages:

dbus

Usually can be disabled by --disable-dbus.

gettext

Usually can be disabled by --disable-nls.

{{{contid(2040)}}}

• Always install a package to the /usr prefix.
• All binaries should go to /usr/bin, not /usr/sbin or any other directory.
• All libraries should go to /usr/lib.

{{{contid(2050)}}}

All build files on the repository should be a POSIX shell script, and must start with #!/bin/sh -e.

The next section is about package templates that should be used in order to ensure stylistic consistency. Note that the option configurations shouldn’t be taken literally, they are meant as examples.

#!/bin/sh -e

make
make DESTDIR="$1" PREFIX=/usr install

#!/bin/sh -e

./configure \
    --prefix=/usr \
    --disable-option \
    --enable-option

make
make DESTDIR="$1" install

#!/bin/sh -e

autoreconf -fi

./configure \
    --prefix=/usr \
    --disable-option \
    --enable-option

make
make DESTDIR="$1" install

The distribution provides a cl-meson wrapper script which sets some common options like installation directories, disables downloading subprojects among other things. This is the preferred method for packages.

#!/bin/sh -e

export DESTDIR=$1

cl-meson \
    -Doption=false \
    -Doption2=true \
    . output

ninja -C output
ninja -C output install

#!/bin/sh -e

export DESTDIR=$1

cmake -B build \
    -DCMAKE_INSTALL_PREFIX=/usr \
    -DCMAKE_BUILD_TYPE=Release \
    -DOPTION=ON

cmake --build   build
cmake --install build

#!/bin/sh -e

export GOPATH=$PWD/gopath
trap "go clean -modcache" EXIT INT
go mod vendor

go build
install -Dm755 program "$1/usr/bin/program"

NOTE: Follow 2242 if you are packaging for non-Community repository.

#!/bin/sh -e

python setup.py build
python setup.py install --prefix=/usr --root="$1"

If you are a distribution maintainer create and upload vendor tarballs so that no internet connection is required during package compilation at all. You can use the following template for this case:

#!/bin/sh -e

go build -v -mod=vendor
clinst -Dm755 program "$1/usr/bin/program"

The community repository is available for any user to submit packages. However, there are certain guidelines that the users are expected to follow before they submit packages.

{{{contid(3000)}}}

Any submitted package should contain a meta file that includes a short description of the package, the maintainer’s name and email address, and the license of the package. Below is an example:

description: some IRC client with some interesting feature
license: MIT
maintainer: Your Name <[email protected]>
    

The order of these are not important. However, make sure to use the license identifiers as defined by SPDX when listing the license.

{{{contid(3010)}}}

The user submitting the package is expected to maintain their packages. This means that they are keeping the packages up-to-date, and responding to issues related to the package.

{{{contid(3020)}}}

If a maintainer doesn’t follow the above expectation for a duration of up to a month, their packages will be orphaned and can be adopted by a new maintainer. Maintainers can also request that their packages be orphaned. If the orphaned packages aren’t adopted by a new maintainer in a period of two weeks, these packages will be dropped from the repository.

{{{contid(3030)}}}

Package submissions and updates should be submitted in the form of patches to the ~carbslinux/carbslinux-devel mailing list. The repository on Github is a read-only mirror, and Pull Requests will NOT be accepted.

{{{contid(3031)}}}

Issues regarding community packages should be submitted to the ~carbslinux/carbslinux-discuss mailing list. When submitting issues, do not forget to add the maintainer as a recipient. You can easily find the maintainer information by running cpt-maintainer <pkg>.

There are multiple ways of sending patches with git. Unfortunately, the most popular / official way of doing it requires Perl and some extra Perl libraries that are not packaged in the repository. This section tries to list other options that are just as useful as git send-email.

By default, git-send-email uses a Perl SMTP client, but without using it this command doesn’t actually need extra Perl libraries, only Perl itself. So, if you are okay with using Perl, the easiest option is to install the msmtp package, and change your git configuration to match your msmtp settings.

To your ~/.gitconfig, add the following section:

[sendemail]
    smtpserver = /usr/bin/msmtp
    smtpserveroption = -a
    smtpserveroption = your-account-name

The git imap-send command reads patches in mbox format, and uploads it to your imap server as drafts. You can then use your preferred email-client to edit and send them. This is the option with no dependencies. Check out the manual page git-imap-send(1) for more information on setting up.

You can create multiple types of “patches” with Fossil. Unlike the common convention in Git, the first two examples here uses uncommitted changes to create a patch (although you could very well create patches of committed changes). The preferred method is by creating a plaintext patch by doing the following:

fossil diff -i > your-changes.patch

You can also create a binary patch:

fossil patch create your-changes.db

If your patchset is complex, and needs to be splitted in multiple check-ins, you can create a Fossil bundle:

fossil bundle create --from CHECKIN --to CHECKIN2 patchset.bundle

After creating the patches, you can simply send them to the mailing list, or upload the patches to the Fossil forum of the relevant repository.