diff options
Diffstat (limited to 'carbslinux.txt')
| -rw-r--r-- | carbslinux.txt | 454 |
1 files changed, 369 insertions, 85 deletions
diff --git a/carbslinux.txt b/carbslinux.txt index 1451ef2..5fde782 100644 --- a/carbslinux.txt +++ b/carbslinux.txt @@ -1,9 +1,9 @@ - _________________________ + _________________________ - CARBS LINUX USER MANUAL + CARBS LINUX USER MANUAL - Cem Keylan - _________________________ + Cem Keylan + _________________________ Table of Contents @@ -15,7 +15,6 @@ _________________ ..... 1. Download ..... 2. Signature verification ..... 3. Extracting the tarball -..... 4. Obtain the chroot helper .. 2. Chroot ..... 1. Setting up repositories ..... 2. Updating packages @@ -25,6 +24,7 @@ _________________ .. 3. System Configuration ..... 1. Configuring hostname ..... 2. Hosts file +..... 3. Creating a user .. 4. Kernel ..... 1. Obtaining the kernel sources ..... 2. Kernel dependencies @@ -34,18 +34,24 @@ _________________ ..... 2. Init scripts ..... 3. Fstab .. 6. Post-installation -..... 1. KISS repositories -3. Init System -.. 1. Configuring Init -..... 1. Kernel Command Line -..... 2. `/etc/init/rc.conf' file -..... 3. Init Hooks -.. 2. Changing Init Program -..... 1. Rebooting after changing init +..... 1. IRC +..... 2. KISS repositories +3. Software +.. 1. Init System +..... 1. Configuring Init +..... 2. Changing Init Program +.. 2. Wayland +..... 1. Enabling the Wayland repository +..... 2. Switching from Xorg +..... 3. Installing a Compositor 4. Contribution Guidelines .. 1. Conventions ..... 1. Shell Conventions ..... 2. Repository Conventions +.. 2. Contributing to the Community repository +.. 3. Sending Patches +..... 1. Git Patches +..... 2. Fossil Patches 5. GNU Free Documentation License @@ -63,7 +69,7 @@ with the info reader. It is divided into sections and easier to read. 1 Copying ========= - Copyright (c) 2020 Cem Keylan + Copyright (c) 2020-2024 Cem Keylan Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free @@ -89,7 +95,6 @@ with the info reader. It is divided into sections and easier to read. ..... 1. Download ..... 2. Signature verification ..... 3. Extracting the tarball - ..... 4. Obtain the chroot helper .. 2. Chroot ..... 1. Setting up repositories ..... 2. Updating packages @@ -99,6 +104,7 @@ with the info reader. It is divided into sections and easier to read. .. 3. System Configuration ..... 1. Configuring hostname ..... 2. Hosts file + ..... 3. Creating a user .. 4. Kernel ..... 1. Obtaining the kernel sources ..... 2. Kernel dependencies @@ -108,7 +114,8 @@ with the info reader. It is divided into sections and easier to read. ..... 2. Init scripts ..... 3. Fstab .. 6. Post-installation - ..... 1. KISS repositories + ..... 1. IRC + ..... 2. KISS repositories 2.1 Preparing Environment @@ -160,8 +167,8 @@ with the info reader. It is divided into sections and easier to read. The signature file should say something similar to ,---- - | untrusted comment: verify with carbslinux-2021.04.pub - | RWTBBPDVQ+aHB3dme2Kerf8XY+vWkIISp7Za2ufKghtlnRXPyObAQQyvEJYrwMVTaCBlPEnSWcnHQz8Nka06YVOIeextNKZY3AQ= + | untrusted comment: verify with carbslinux-2023.02.pub + | RWTe38zmx+iyuKEL5T84MJ5Y24jqenkTtQLJxbaMzOBS/NkGVl5J+Vn2B6vTV/gJK7LYBPS+IOXV5sEf+YLGCMcBYAGHCcP4xQ8= `---- @@ -173,7 +180,7 @@ with the info reader. It is divided into sections and easier to read. use that instead. ,---- - | PUBKEY=carbslinux-2021.04.pub + | PUBKEY=carbslinux-2023.02.pub | wget https://dl.carbslinux.org/keys/$PUBKEY `---- @@ -209,25 +216,14 @@ with the info reader. It is divided into sections and easier to read. [this guide] <https://wiki.archlinux.org/index.php/Partitioning> -2.1.4 Obtain the chroot helper ------------------------------- - - You can obtain the `cpt-chroot' script in order to do a simple chroot - into your new root filesystem. - - ,---- - | wget https://dl.carbslinux.org/distfiles/cpt-chroot - | chmod a+x cpt-chroot - `---- - - 2.2 Chroot ~~~~~~~~~~ - Chroot into Carbs Linux! + Chroot into Carbs Linux by running the chroot helper inside the + rootfs! ,---- - | ./cpt-chroot /mnt + | /mnt/bin/cpt-chroot /mnt `---- @@ -257,8 +253,8 @@ with the info reader. It is divided into sections and easier to read. and GitHub (mirror). Here are both their repository links. You can clone any of them. - - git://git.carbslinux.org/repository - - <https://github.com/carbslinux/repository> + - <https://git.carbslinux.org/repository> + - <https://git.sr.ht/~carbslinux/repository> ,---- | git clone git://git.carbslinux.org/repository $HOME/repos/carbs @@ -271,7 +267,7 @@ with the info reader. It is divided into sections and easier to read. order to obtain it, run the following: ,---- - | rsync -avc rsync://carbslinux.org/repo $HOME/repos/carbs + | rsync -avc rsync://vaylin.carbslinux.org/repo $HOME/repos/carbs `---- @@ -283,7 +279,7 @@ with the info reader. It is divided into sections and easier to read. ,---- | CPT_PATH=$HOME/repos/carbs/core | CPT_PATH=$CPT_PATH:$HOME/repos/carbs/extra - | CPT_PATH=$CPT_PATH:$HOME/repos/carbs/xorg + | CPT_PATH=$CPT_PATH:$HOME/repos/carbs/wayland | CPT_PATH=$CPT_PATH:$HOME/repos/carbs/community | export CPT_PATH `---- @@ -319,7 +315,10 @@ with the info reader. It is divided into sections and easier to read. 2.2.4 Essential Software ------------------------ - Here is a list of software that you might want to have on your system. + 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* @@ -341,22 +340,6 @@ with the info reader. It is divided into sections and easier to read. - nano - vim - - neatvi - - emacs - - emacs-nox (terminal-only version of emacs) - - *USER SHELLS* - - - bash - - zsh - - oksh - - rc - - *POSIX BASE UTILITIES* - - - busybox - - sbase - - coreutils *DOCUMENTATION* @@ -369,8 +352,8 @@ with the info reader. It is divided into sections and easier to read. --------------------------------- All the documentation for Carbs Linux can be found on a single info - manual to be viewed offline. You can obtain texinfo or the info - (standalone) package in order to view the documentation. + manual to be viewed offline. You can obtain either `texinfo' or the + `info' packages in order to view the documentation. ,---- | # Install the documentation. @@ -418,6 +401,37 @@ with the info reader. It is divided into sections and easier to read. `---- +2.3.3 Creating a user +--------------------- + + 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 + `---- + + 2.4 Kernel ~~~~~~~~~~ @@ -435,17 +449,22 @@ with the info reader. It is divided into sections and easier to read. 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. + 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.9.1.tar.xz - | tar xf linux-5.9.1.tar.xz + | 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.9.1 + | 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>. + 2.4.2 Kernel dependencies ------------------------- @@ -529,8 +548,8 @@ with the info reader. It is divided into sections and easier to read. | cpt b grub && cpt i grub | | grub-install --target=x86_64-efi \ - | --efi-directory=esp \ - | --bootloader-id=CarbsLinux + | --efi-directory=esp \ + | --bootloader-id=CarbsLinux | | grub-mkconfig -o /boot/grub/grub.cfg `---- @@ -570,17 +589,44 @@ with the info reader. It is divided into sections and easier to read. learn more about the system. -2.6.1 KISS repositories +2.6.1 IRC +--------- + + 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. + + +[libera.chat] <https://libera.chat> + + +2.6.2 KISS repositories ----------------------- - While not 100% compatible with cpt, you can use kiss repositories in - your system the same way you are using the distribution - repositories. Here is an example for the KISS Linux Community - repository. + 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'. + + +3 Software +========== + + 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 -3 Init System -============= +[Libera] <https://libera.chat> + +3.1 Init System +~~~~~~~~~~~~~~~ Carbs Linux init scripts are run by the init daemon (`busybox' by default) on boot and shutdown processes. It also provides its own @@ -588,8 +634,8 @@ with the info reader. It is divided into sections and easier to read. doesn't rely on non-POSIX external programs. -3.1 Configuring Init -~~~~~~~~~~~~~~~~~~~~ +3.1.1 Configuring Init +---------------------- There are three ways you can change the behaviour of the init system. Those are: @@ -599,8 +645,7 @@ with the info reader. It is divided into sections and easier to read. - Init Hooks -3.1.1 Kernel Command Line -------------------------- +* 3.1.1.1 Kernel Command Line 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 @@ -627,8 +672,7 @@ with the info reader. It is divided into sections and easier to read. startup. -3.1.2 `/etc/init/rc.conf' file ------------------------------- +* 3.1.1.2 `/etc/init/rc.conf' file 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 @@ -636,8 +680,7 @@ with the info reader. It is divided into sections and easier to read. since they can be set just before boot. -3.1.3 Init Hooks ----------------- +* 3.1.1.3 Init Hooks 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, @@ -658,15 +701,15 @@ with the info reader. It is divided into sections and easier to read. Run just before the system is halted. -3.2 Changing Init Program -~~~~~~~~~~~~~~~~~~~~~~~~~ +3.1.2 Changing Init Program +--------------------------- 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' + - `busybox' init - `runit' - `shinit' @@ -681,8 +724,7 @@ with the info reader. It is divided into sections and easier to read. `---- -3.2.1 Rebooting after changing init ------------------------------------ +* 3.1.2.1 Rebooting after changing init After switching init systems, your running init system may not accept the new poweroff commands. You will need to reboot/poweroff using the @@ -697,6 +739,73 @@ with the info reader. It is divided into sections and easier to read. shinit/sinit `kill -s INT 1' +3.2 Wayland +~~~~~~~~~~~ + + 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. + + +[Switching from Xorg] See section 3.2.2 + +3.2.1 Enabling the Wayland repository +------------------------------------- + + 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 + `---- + + +3.2.2 Switching from Xorg +------------------------- + + 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. + + +3.2.3 Installing a Compositor +----------------------------- + + The `wayland' repository currently only contains `sway' as a Wayland + compositor, but you can package something else for your own. + + ,---- + | cpt bi sway + `---- + + 4 Contribution Guidelines ========================= @@ -782,7 +891,7 @@ with the info reader. It is divided into sections and easier to read. 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. + *sure* there is no alternative. [2030] Avoid these packages: dbus @@ -810,6 +919,9 @@ with the info reader. It is divided into sections and easier to read. * 4.1.2.1 Make [2210] + + + ,---- | #!/bin/sh -e | @@ -820,6 +932,9 @@ with the info reader. It is divided into sections and easier to read. * 4.1.2.2 Configure/Make [2211] + + + ,---- | #!/bin/sh -e | @@ -835,6 +950,9 @@ with the info reader. It is divided into sections and easier to read. * 4.1.2.3 Autoconf/Automake [2212] + + + ,---- | #!/bin/sh -e | @@ -852,13 +970,20 @@ with the info reader. It is divided into sections and easier to read. * 4.1.2.4 Meson [2220] + + + + 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 | - | meson \ - | --prefix=/usr \ + | cl-meson \ | -Doption=false \ | -Doption2=true \ | . output @@ -870,6 +995,9 @@ with the info reader. It is divided into sections and easier to read. * 4.1.2.5 Cmake [2230] + + + ,---- | #!/bin/sh -e | @@ -887,6 +1015,9 @@ with the info reader. It is divided into sections and easier to read. * 4.1.2.6 Go [2240] + + + ,---- | #!/bin/sh -e | @@ -898,9 +1029,14 @@ with the info reader. It is divided into sections and easier to read. | install -Dm755 program "$1/usr/bin/program" `---- + *NOTE*: Follow 2242 if you are packaging for non-Community repository. + * 4.1.2.7 Python [2241] + + + ,---- | #!/bin/sh -e | @@ -909,6 +1045,154 @@ with the info reader. It is divided into sections and easier to read. `---- +* 4.1.2.8 Go (pre-vendored) [2242] + + + + :ID: d2c828ae-bc56-4183-8830-becbf6a812d1 + + 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" + `---- + + +4.2 Contributing to the Community repository +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + 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. + + [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 <address@example.com> + `---- + + The order of these are not important. However, make sure to use + the license identifiers as defined by [SPDX] when listing the + license. + + [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. + + [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. + + [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. + + [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>'. + + +[SPDX] <https://spdx.org/licenses/> + +[~carbslinux/carbslinux-devel] +<https://lists.sr.ht/~carbslinux/carbslinux-devel> + +[~carbslinux/carbslinux-discuss] +<https://lists.sr.ht/~carbslinux/carbslinux-discuss> + + +4.3 Sending Patches +~~~~~~~~~~~~~~~~~~~ + +4.3.1 Git Patches +----------------- + + 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'. + + +* 4.3.1.1 `git-send-email' with msmtp + + 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 + `---- + + +* 4.3.1.2 `git-imap-send' + + 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. + + +4.3.2 Fossil Patches +-------------------- + + 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. + + 5 GNU Free Documentation License ================================ |