diff options
Diffstat (limited to 'carbslinux.txt')
| -rw-r--r-- | carbslinux.txt | 304 |
1 files changed, 264 insertions, 40 deletions
diff --git a/carbslinux.txt b/carbslinux.txt index 4ea8415..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 @@ -24,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 @@ -39,12 +40,18 @@ _________________ .. 1. Init System ..... 1. Configuring Init ..... 2. Changing Init Program -.. 2. TODO Display Systems -..... 1. Wayland +.. 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 @@ -62,7 +69,7 @@ with the info reader. It is divided into sections and easier to read. 1 Copying ========= - Copyright (c) 2020-2021 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 @@ -97,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 @@ -159,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.08.pub - | RWTK4GFDD7JiohUHBeJXuKw+/P3K4ZRR8jQud0iOxNDbn7WCFxQsxt9FUNSEiXfLjkm1Ez8c3esRG8oydrsFUFpBGtekFt5obgo= + | untrusted comment: verify with carbslinux-2023.02.pub + | RWTe38zmx+iyuKEL5T84MJ5Y24jqenkTtQLJxbaMzOBS/NkGVl5J+Vn2B6vTV/gJK7LYBPS+IOXV5sEf+YLGCMcBYAGHCcP4xQ8= `---- @@ -172,7 +180,7 @@ with the info reader. It is divided into sections and easier to read. use that instead. ,---- - | PUBKEY=carbslinux-2021.08.pub + | PUBKEY=carbslinux-2023.02.pub | wget https://dl.carbslinux.org/keys/$PUBKEY `---- @@ -259,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 `---- @@ -271,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 `---- @@ -393,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 ~~~~~~~~~~ @@ -410,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 ------------------------- @@ -504,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 `---- @@ -695,17 +739,12 @@ with the info reader. It is divided into sections and easier to read. shinit/sinit `kill -s INT 1' -3.2 TODO Display Systems -~~~~~~~~~~~~~~~~~~~~~~~~ - - Carbs Linux supports both Xorg and Wayland in the distribution - repositories. This section serves as a guide to set up your preferred - display server. Follow the subsection for the display server you want - to setup. - +3.2 Wayland +~~~~~~~~~~~ -3.2.1 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 @@ -713,7 +752,10 @@ with the info reader. It is divided into sections and easier to read. compositor should follow this section. -* 3.2.1.1 Enabling the Wayland repository +[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 @@ -725,7 +767,6 @@ with the info reader. It is divided into sections and easier to read. | CPT_PATH=$REPOSITORY/core | CPT_PATH=$CPT_PATH:$REPOSITORY/extra | CPT_PATH=$CPT_PATH:$REPOSITORY/wayland - | CPT_PATH=$CPT_PATH:$REPOSITORY/xorg | export CPT_PATH `---- @@ -737,25 +778,33 @@ with the info reader. It is divided into sections and easier to read. `---- -* 3.2.1.2 Switching from Xorg +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 - - xorg-server (for Xwayland support) - - webkit2gtk + - `gtk+3' + - `gtk4' + - `mesa' + - `webkit2gtk' + For xorg support inside wayland sessions, you need to install the + `xwayland' package. -* 3.2.1.3 TODO Installing a Compositor + +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 ========================= @@ -842,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 @@ -870,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 | @@ -880,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 | @@ -895,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 | @@ -912,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 @@ -930,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 | @@ -947,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 | @@ -958,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 | @@ -969,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 ================================ |