diff options
Diffstat (limited to 'carbslinux.texi')
| -rw-r--r-- | carbslinux.texi | 331 |
1 files changed, 270 insertions, 61 deletions
diff --git a/carbslinux.texi b/carbslinux.texi index fd0973d..d3be7f9 100644 --- a/carbslinux.texi +++ b/carbslinux.texi @@ -7,7 +7,7 @@ @c %**end of header @copying -Copyright @copyright{} 2020-2021 Cem Keylan +Copyright @copyright{} 2020-2024 Cem Keylan @quotation Permission is granted to copy, distribute and/or modify this document @@ -94,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 @@ -115,26 +116,35 @@ Post-installation Software * Init System:: Configure the init system -* Display Systems:: +* 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 -Display Systems +Wayland -* Wayland:: +* 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 @@ -216,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.08.pub -RWTK4GFDD7JiohUHBeJXuKw+/P3K4ZRR8jQud0iOxNDbn7WCFxQsxt9FUNSEiXfLjkm1Ez8c3esRG8oydrsFUFpBGtekFt5obgo= +untrusted comment: verify with carbslinux-2023.02.pub +RWTe38zmx+iyuKEL5T84MJ5Y24jqenkTtQLJxbaMzOBS/NkGVl5J+Vn2B6vTV/gJK7LYBPS+IOXV5sEf+YLGCMcBYAGHCcP4xQ8= @end example @@ -228,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.08.pub +PUBKEY=carbslinux-2023.02.pub wget https://dl.carbslinux.org/keys/$PUBKEY @end example @@ -293,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 @@ -311,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 @@ -331,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 @@ -445,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 @@ -469,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 @@ -487,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 @@ -558,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 @@ -568,7 +612,7 @@ grub-mkconfig -o /boot/grub/grub.cfg @end example @item -GRUB UEFI installation +@anchor{GRUB UEFI installation}GRUB UEFI installation @example @@ -645,7 +689,7 @@ This section goes over the details of some packaged software @menu * Init System:: Configure the init system -* Display Systems:: +* Wayland:: Maintaining a Wayland display system @end menu @node Init System @@ -677,7 +721,7 @@ Init Hooks @enumerate @item -Kernel Command Line +@anchor{Kernel Command Line}Kernel Command Line On GRUB, you can edit the kernel command line parameters, which will be parsed @@ -703,7 +747,7 @@ Some of these variables, such as @samp{rw=/=ro}, @samp{loglevel}, and @samp{quie used by the init system to change the behaviour of the startup. @item -@samp{/etc/init/rc.conf} file +@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 @@ -712,7 +756,7 @@ kernel command line always gets the priority for these variables since they can be set just before boot. @item -Init Hooks +@anchor{Init Hooks}Init Hooks Init hooks are for custom personal commands that the user may want to add to @@ -764,7 +808,7 @@ cpt a runit /usr/bin/reboot @enumerate @item -Rebooting after changing init +@anchor{Rebooting after changing init}Rebooting after changing init After switching init systems, your running init system may not accept the @@ -784,29 +828,25 @@ currently running on your system and not the one you are switching to. @end multitable @end enumerate -@node Display Systems -@section @strong{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. - -@menu -* Wayland:: -@end menu - @node Wayland -@subsection 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. -@enumerate -@item -Enabling the Wayland repository +@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 @@ -818,7 +858,6 @@ your repository. 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 @end example @@ -829,9 +868,8 @@ After you have enabled your repositories, go ahead and install @samp{wayland} an cpt-build wayland wayland-protocols @end example -@item -Switching from Xorg - +@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 @@ -839,24 +877,27 @@ this step. The packages that need a rebuild are: @itemize @item -gtk+3 -@item -gtk4 +@samp{gtk+3} @item -mesa +@samp{gtk4} @item -xorg-server (for Xwayland support) +@samp{mesa} @item -webkit2gtk +@samp{webkit2gtk} @end itemize -@item -@strong{TODO} Installing a Compositor +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. -@end enumerate + +@example +cpt bi sway +@end example @node Contribution Guidelines @chapter Contribution Guidelines @@ -867,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 @@ -969,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 @@ -998,7 +1041,10 @@ taken literally, they are meant as examples. @enumerate @item -Make [@anchor{2210}2210] +@anchor{Make [2210]}Make [2210] + + +@anchor{2210} @example @@ -1009,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 @@ -1025,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} @@ -1045,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 @@ -1064,7 +1122,10 @@ ninja -C output install @end example @item -Cmake [@anchor{2230}2230] +@anchor{Cmake [2230]}Cmake [2230] + + +@anchor{2230} @example @@ -1082,7 +1143,10 @@ cmake --install build @end example @item -Go [@anchor{2240}2240] +@anchor{Go [2240]}Go [2240] + + +@anchor{2240} @example @@ -1096,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 @@ -1106,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 |