diff options
Diffstat (limited to 'carbslinux.texi')
| -rw-r--r-- | carbslinux.texi | 483 |
1 files changed, 374 insertions, 109 deletions
diff --git a/carbslinux.texi b/carbslinux.texi index 532bd38..d3be7f9 100644 --- a/carbslinux.texi +++ b/carbslinux.texi @@ -7,7 +7,7 @@ @c %**end of header @copying -Copyright @copyright{} 2020 Cem Keylan +Copyright @copyright{} 2020-2024 Cem Keylan @quotation Permission is granted to copy, distribute and/or modify this document @@ -52,15 +52,15 @@ read. @ifhtml This documentation is also available in the distribution by the @command{carbs-docs} package, which can be read by either running -@code{info carbslinux} or reading @file{/usr/share/doc/carbslinux.txt} with your -favorite pager. You can install either the @command{info} or @command{texinfo} -for doing the first. +@code{info carbslinux} or reading @file{/usr/share/doc/carbslinux/carbslinux.txt} +with your favorite pager. You can install either the @command{info} or +@command{texinfo} for doing the first. @end ifhtml @end ifnottex @menu * Installation:: Installing Carbs Linux -* Init System:: Configure the init system +* Software:: Details on configuring your system's software * Contribution Guidelines:: Contribute to Carbs Linux * GNU Free Documentation License:: Your rights @@ -81,7 +81,6 @@ Preparing Environment * Download:: Download the root filesystem tarball * Signature verification:: Verify the signature of the rootfs tarball * Extracting the tarball:: Extracting the root filesystem to the desired location -* Obtain the chroot helper:: Download the script to easily chroot into the new filesystem Chroot @@ -95,6 +94,7 @@ System Configuration * Configuring hostname:: Setting up system hostname (recommended) * Hosts file:: Setting up hosts file for networking (optional) +* Creating a user:: Adding a user to your new system Kernel @@ -110,32 +110,41 @@ Making your system bootable Post-installation +* IRC:: Joining the IRC channel * KISS repositories:: Acquire kiss repositories +Software + +* Init System:: Configure the init system +* Wayland:: Maintaining a Wayland display system + Init System * Configuring Init:: Ways to configure the init system * Changing Init Program:: Replace the default busybox init with something new -Configuring Init - -* Kernel Command Line:: Configure init through the boot parameters -* @samp{/etc/init/rc.conf} file: @samp{/etc/init/rcconf} file. Configure init through the configuration file -* Init Hooks:: Configure init through hooks - -Changing Init Program +Wayland -* Rebooting after changing init:: Ways to reboot after replacing the init system +* Enabling the Wayland repository:: Including the wayland repository in your repository path +* Switching from Xorg:: Rebuilding system packages for wayland +* Installing a Compositor:: Getting wayland ready for your system Contribution Guidelines * Conventions:: Conventions of the distribution +* Contributing to the Community repository:: Package maintainership and issue reports +* Sending Patches:: Code contribution Conventions * Shell Conventions:: Conventions for shell scripts * Repository Conventions:: Conventions for repository build scripts +Sending Patches + +* Git Patches:: +* Fossil Patches:: + @end detailmenu @end menu @@ -186,7 +195,6 @@ will continue on that point. * Download:: Download the root filesystem tarball * Signature verification:: Verify the signature of the rootfs tarball * Extracting the tarball:: Extracting the root filesystem to the desired location -* Obtain the chroot helper:: Download the script to easily chroot into the new filesystem @end menu @node Download @@ -218,8 +226,8 @@ wget $URL/carbs-rootfs.tar.xz.sig The signature file should say something similar to @example -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= @end example @@ -230,7 +238,7 @@ check the validity of the public key from multiple locations, or just copy paste that portion to a file and use that instead. @example -PUBKEY=carbslinux-2021.04.pub +PUBKEY=carbslinux-2023.02.pub wget https://dl.carbslinux.org/keys/$PUBKEY @end example @@ -258,24 +266,13 @@ mount /dev/sdx1 /mnt tar xf carbs-rootfs.tar.xz -C /mnt @end example -@node Obtain the chroot helper -@subsection Obtain the chroot helper - -You can obtain the @samp{cpt-chroot} script in order to do a simple chroot into your -new root filesystem. - -@example -wget https://dl.carbslinux.org/distfiles/cpt-chroot -chmod a+x cpt-chroot -@end example - @node Chroot @section Chroot -Chroot into Carbs Linux! +Chroot into Carbs Linux by running the chroot helper inside the rootfs! @example -./cpt-chroot /mnt +/mnt/bin/cpt-chroot /mnt @end example @menu @@ -306,7 +303,7 @@ mkdir -p $HOME/repos @enumerate @item -Obtaining from git +@anchor{Obtaining from git}Obtaining from git Carbs Linux git repositories can be found both from the main server and GitHub @@ -314,9 +311,9 @@ Carbs Linux git repositories can be found both from the main server and GitHub @itemize @item -git://git.carbslinux.org/repository +@uref{https://git.carbslinux.org/repository} @item -@uref{https://github.com/carbslinux/repository} +@uref{https://git.sr.ht/~carbslinux/repository} @end itemize @example @@ -324,18 +321,18 @@ git clone git://git.carbslinux.org/repository $HOME/repos/carbs @end example @item -Obtaining from rsync +@anchor{Obtaining from rsync}Obtaining from rsync Carbs Linux rsync repositories live in rsync://carbslinux.org/repo. In order to obtain it, run the following: @example -rsync -avc rsync://carbslinux.org/repo $HOME/repos/carbs +rsync -avc rsync://vaylin.carbslinux.org/repo $HOME/repos/carbs @end example @item -Making the package manager use the repositories +@anchor{Making the package manager use the repositories}Making the package manager use the repositories In your shell's configuration file, or in your @samp{~/.profile} file, add the @@ -344,7 +341,7 @@ following lines: @example 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 @end example @@ -377,7 +374,9 @@ cpt-install package @node Essential Software @subsection 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 @strong{Software} section in the full +documentation to learn more about other packaged software. @strong{BOOTLOADERS} @@ -415,36 +414,6 @@ wpa@math{_supplicant} nano @item vim -@item -neatvi -@item -emacs -@item -emacs-nox (terminal-only version of emacs) -@end itemize - -@strong{USER SHELLS} - -@itemize -@item -bash -@item -zsh -@item -oksh -@item -rc -@end itemize - -@strong{POSIX BASE UTILITIES} - -@itemize -@item -busybox -@item -sbase -@item -coreutils @end itemize @strong{DOCUMENTATION} @@ -462,7 +431,7 @@ man-pages-posix @subsection Obtaining the documentation 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 +viewed offline. You can obtain either @samp{texinfo} or the @samp{info} packages in order to view the documentation. @example @@ -486,6 +455,7 @@ system to your liking. @menu * Configuring hostname:: Setting up system hostname (recommended) * Hosts file:: Setting up hosts file for networking (optional) +* Creating a user:: Adding a user to your new system @end menu @node Configuring hostname @@ -510,6 +480,35 @@ replace the 'localhost' part of these entries to your hostname. ::1 localhost.localdomain localhost ip6-localhost @end example +@node Creating a user +@subsection 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 @samp{doas} for doing operations that require @samp{root} +privileges. The code block below describes how to create a user (named @samp{foo}), +add them to the wheel group, and to give doas permissions to the wheel group + +@example +# 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 +@end example + +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 + +@example +su foo +@end example + @node Kernel @section Kernel @@ -528,17 +527,21 @@ need to reconfigure for your specific setup if you want to make use of it. You can visit the @uref{https://kernel.org} website to choose a kernel that you want to install. Though only the latest stable and longterm (LTS) versions are -supported. +supported. Note that kernel releases are quite rapid, and the version below is +likely outdated, so don't run it verbatim. @example # 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 @end example +@strong{NOTE:} If you want to validate the kernel signature, install the @samp{gnupg2} +package, and follow the instructions provided at @uref{https://kernel.org/category/signatures.html}. + @node Kernel dependencies @subsection Kernel dependencies @@ -599,7 +602,7 @@ without UEFI support (or you really want to use BIOS for a reason). @enumerate @item -GRUB BIOS installation +@anchor{GRUB BIOS installation}GRUB BIOS installation @example @@ -609,7 +612,7 @@ grub-mkconfig -o /boot/grub/grub.cfg @end example @item -GRUB UEFI installation +@anchor{GRUB UEFI installation}GRUB UEFI installation @example @@ -654,18 +657,43 @@ 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. @menu +* IRC:: Joining the IRC channel * KISS repositories:: Acquire kiss repositories @end menu +@node IRC +@subsection IRC + +The IRC channel for Carbs Linux is located in @samp{#carbslinux} on @uref{https://libera.chat, libera.chat}. You +can install the @samp{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. + @node KISS repositories @subsection 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 @samp{kiss} package manager that breaks +compatibility with @samp{cpt}. These changes throw away the entire premise of their +"static" packaging system. @samp{cpt} will never implement those changes, so don't +expect any KISS package that was changed during or after July 2021 to work with +@samp{cpt}. + +@node Software +@chapter 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 (@samp{#carbslinux} on @uref{https://libera.chat, Libera}). + +This section goes over the details of some packaged software + +@menu +* Init System:: Configure the init system +* Wayland:: Maintaining a Wayland display system +@end menu @node Init System -@chapter Init System +@section Init System Carbs Linux init scripts are run by the init daemon (@samp{busybox} by default) on boot and shutdown processes. It also provides its own halting program named @@ -678,7 +706,7 @@ programs. @end menu @node Configuring Init -@section Configuring Init +@subsection Configuring Init There are three ways you can change the behaviour of the init system. Those are: @@ -691,14 +719,10 @@ Kernel Command Line Init Hooks @end itemize -@menu -* Kernel Command Line:: Configure init through the boot parameters -* @samp{/etc/init/rc.conf} file: @samp{/etc/init/rcconf} file. Configure init through the configuration file -* Init Hooks:: Configure init through hooks -@end menu +@enumerate +@item +@anchor{Kernel Command Line}Kernel Command Line -@node Kernel Command Line -@subsection 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 will be acted upon, @@ -722,16 +746,18 @@ quiet=1 Some of these variables, such as @samp{rw=/=ro}, @samp{loglevel}, and @samp{quiet}, will be used by the init system to change the behaviour of the startup. -@node @samp{/etc/init/rcconf} file -@subsection @samp{/etc/init/rc.conf} file +@item +@anchor{@samp{/etc/init/rcconf} file}@samp{/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 the kernel command line always gets the priority for these variables since they can be set just before boot. -@node Init Hooks -@subsection Init Hooks +@item +@anchor{Init Hooks}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, modify interfaces, @@ -751,9 +777,10 @@ Run just before filesystems are unmounted. @item post.shutdown Run just before the system is halted. @end table +@end enumerate @node Changing Init Program -@section Changing Init Program +@subsection Changing Init Program By default, Carbs Linux comes preinstalled with @samp{busybox-init}, but this can easily be replaced without any issues. Currently, available init systems are: @@ -762,7 +789,7 @@ easily be replaced without any issues. Currently, available init systems are: @item @samp{sinit} @item -@samp{busybox} +@samp{busybox} init @item @samp{runit} @item @@ -779,12 +806,10 @@ cpt a runit /usr/bin/poweroff cpt a runit /usr/bin/reboot @end example -@menu -* Rebooting after changing init:: Ways to reboot after replacing the init system -@end menu +@enumerate +@item +@anchor{Rebooting after changing init}Rebooting after changing init -@node Rebooting after changing init -@subsection 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 running init's @@ -801,6 +826,78 @@ currently running on your system and not the one you are switching to. @item shinit/sinit @tab @samp{kill -s INT 1} @end multitable +@end enumerate + +@node Wayland +@section 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 @ref{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. + +@menu +* Enabling the Wayland repository:: Including the wayland repository in your repository path +* Switching from Xorg:: Rebuilding system packages for wayland +* Installing a Compositor:: Getting wayland ready for your system +@end menu + +@node Enabling the Wayland repository +@subsection Enabling the Wayland repository + +The @samp{wayland} repository requires packages from @samp{xorg} and @samp{extra} repositories. +So you should set your @samp{$CPT_PATH} so that @samp{core} and @samp{extra} repositories +precede the @samp{wayland} repository, and the @samp{xorg} repository should come after +@samp{wayland}. Here is an example below, where @samp{$REPOSITORY} points to the root of +your repository. + +@example +CPT_PATH=$REPOSITORY/core +CPT_PATH=$CPT_PATH:$REPOSITORY/extra +CPT_PATH=$CPT_PATH:$REPOSITORY/wayland +export CPT_PATH +@end example + +After you have enabled your repositories, go ahead and install @samp{wayland} and +@samp{wayland-protocols} packages. + +@example +cpt-build wayland wayland-protocols +@end example + +@node Switching from Xorg +@subsection Switching from Xorg + +If you are already an Xorg user, you will need to rebuild some packages so that +they support @samp{wayland}. If you don't have an @samp{xorg} system, feel free to skip +this step. The packages that need a rebuild are: + +@itemize +@item +@samp{gtk+3} +@item +@samp{gtk4} +@item +@samp{mesa} +@item +@samp{webkit2gtk} +@end itemize + +For xorg support inside wayland sessions, you need to install the @samp{xwayland} +package. + +@node Installing a Compositor +@subsection Installing a Compositor + +The @samp{wayland} repository currently only contains @samp{sway} as a Wayland compositor, +but you can package something else for your own. + +@example +cpt bi sway +@end example @node Contribution Guidelines @chapter Contribution Guidelines @@ -811,6 +908,8 @@ and changes may occur with good reasoning. @menu * Conventions:: Conventions of the distribution +* Contributing to the Community repository:: Package maintainership and issue reports +* Sending Patches:: Code contribution @end menu @node Conventions @@ -913,7 +1012,7 @@ ahead. @item [@anchor{2020}2020] Prefer sources without a dependency to @samp{automake}. There are usually distribution tarballs that are @samp{autoconf}'ed. Don't submit tarballs -with an automake dependency unless you are @samp{sure} there is no alternative. +with an automake dependency unless you are @strong{sure} there is no alternative. @item [@anchor{2030}2030] Avoid these packages: @table @asis @@ -942,7 +1041,10 @@ taken literally, they are meant as examples. @enumerate @item -Make [@anchor{2210}2210] +@anchor{Make [2210]}Make [2210] + + +@anchor{2210} @example @@ -953,7 +1055,10 @@ make DESTDIR="$1" PREFIX=/usr install @end example @item -Configure/Make [@anchor{2211}2211] +@anchor{Configure/Make [2211]}Configure/Make [2211] + + +@anchor{2211} @example @@ -969,7 +1074,10 @@ make DESTDIR="$1" install @end example @item -Autoconf/Automake [@anchor{2212}2212] +@anchor{Autoconf/Automake [2212]}Autoconf/Automake [2212] + + +@anchor{2212} @xref{2020} @@ -989,16 +1097,22 @@ make DESTDIR="$1" install @end example @item -Meson [@anchor{2220}2220] +@anchor{Meson [2220]}Meson [2220] + + +@anchor{2220} +The distribution provides a @samp{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. + @example #!/bin/sh -e export DESTDIR=$1 -meson \ - --prefix=/usr \ +cl-meson \ -Doption=false \ -Doption2=true \ . output @@ -1008,7 +1122,10 @@ ninja -C output install @end example @item -Cmake [@anchor{2230}2230] +@anchor{Cmake [2230]}Cmake [2230] + + +@anchor{2230} @example @@ -1026,7 +1143,10 @@ cmake --install build @end example @item -Go [@anchor{2240}2240] +@anchor{Go [2240]}Go [2240] + + +@anchor{2240} @example @@ -1040,8 +1160,14 @@ go build install -Dm755 program "$1/usr/bin/program" @end example +@strong{NOTE}: Follow 2242 if you are packaging for non-Community repository. +@xref{2242} + @item -Python [@anchor{2241}2241] +@anchor{Python [2241]}Python [2241] + + +@anchor{2241} @example @@ -1050,8 +1176,147 @@ Python [@anchor{2241}2241] python setup.py build python setup.py install --prefix=/usr --root="$1" @end example + +@item +@anchor{Go (pre-vendored) [2242]}Go (pre-vendored) [2242] + + +@anchor{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: + +@example +#!/bin/sh -e + +go build -v -mod=vendor +clinst -Dm755 program "$1/usr/bin/program" +@end example +@end enumerate + +@node Contributing to the Community repository +@section 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. + +@table @asis +@item [@anchor{3000}3000] +Any submitted package should contain a @samp{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: + +@example +description: some IRC client with some interesting feature +license: MIT +maintainer: Your Name <address@@example.com> +@end example + +The order of these are not important. However, make sure to use the license +identifiers as defined by @uref{https://spdx.org/licenses/, SPDX} when listing the license. + +@item [@anchor{3010}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. + +@item [@anchor{3020}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. + +@item [@anchor{3030}3030] +Package submissions and updates should be submitted in the form of patches to +the @uref{https://lists.sr.ht/~carbslinux/carbslinux-devel, ~carbslinux/carbslinux-devel} mailing list. The repository on Github is a +read-only mirror, and Pull Requests will @strong{NOT} be accepted. + +@item [@anchor{3031}3031] +Issues regarding community packages should be submitted to the +@uref{https://lists.sr.ht/~carbslinux/carbslinux-discuss, ~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 @code{cpt-maintainer <pkg>}. +@end table + +@node Sending Patches +@section Sending Patches + +@menu +* Git Patches:: +* Fossil Patches:: +@end menu + +@node Git Patches +@subsection 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 @samp{git send-email}. + +@enumerate +@item +@anchor{@samp{git-send-email} with msmtp}@samp{git-send-email} with msmtp + + +By default, @samp{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 @samp{msmtp} package, +and change your git configuration to match your msmtp settings. + +To your @samp{~/.gitconfig}, add the following section: + +@example +[sendemail] + smtpserver = /usr/bin/msmtp + smtpserveroption = -a + smtpserveroption = your-account-name +@end example + +@item +@anchor{@samp{git-imap-send}}@samp{git-imap-send} + + +The @samp{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 +@samp{git-imap-send(1)} for more information on setting up. @end enumerate +@node Fossil Patches +@subsection 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: + +@example +fossil diff -i > your-changes.patch +@end example + +You can also create a binary patch: + +@example +fossil patch create your-changes.db +@end example + +If your patchset is complex, and needs to be splitted in multiple check-ins, you +can create a Fossil bundle: + +@example +fossil bundle create --from CHECKIN --to CHECKIN2 patchset.bundle +@end example + +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. + @node GNU Free Documentation License @appendix GNU Free Documentation License |