diff options
| -rw-r--r-- | carbslinux.org | 269 | ||||
| -rw-r--r-- | carbslinux.texi | 331 | ||||
| -rw-r--r-- | carbslinux.txt | 304 | ||||
| -rw-r--r-- | config.mk | 2 | ||||
| -rw-r--r-- | install.org | 61 | ||||
| -rw-r--r-- | install.txt | 67 |
6 files changed, 861 insertions, 173 deletions
diff --git a/carbslinux.org b/carbslinux.org index dce939b..21b8117 100644 --- a/carbslinux.org +++ b/carbslinux.org @@ -11,7 +11,7 @@ This is the documentation source for Carbs Linux in Org-mode. The macros below are used for assigning IDs to contribution guidelines. #+END_COMMENT #+MACRO: contid [@@texinfo:@anchor{$1}@@$1] -#+MACRO: sectid $2 [@@texinfo:@anchor{$1}@@$1] +#+MACRO: sectid (eval (format "%s [%s]\n@@texinfo:@anchor{%s}@@\n" $2 $1 $1)) This is the full documentation of [[https://carbslinux.org][Carbs Linux]], from the details of the distribution, installation, to the package manager. It is not yet complete. @@ -53,6 +53,7 @@ with your favorite pager. You can install either the @command{info} or - [[#system-configuration][System Configuration]] - [[#configuring-hostname][Configuring hostname]] - [[#hosts-file][Hosts file]] + - [[#creating-a-user][Creating a user]] - [[#kernel][Kernel]] - [[#obtaining-the-kernel-sources][Obtaining the kernel sources]] - [[#kernel-dependencies][Kernel dependencies]] @@ -68,12 +69,18 @@ with your favorite pager. You can install either the @command{info} or - [[#init-system][Init System]] - [[#configuring-init][Configuring Init]] - [[#changing-init-program][Changing Init Program]] - - [[#display-systems][Display Systems]] - - [[#wayland][Wayland]] + - [[#wayland][Wayland]] + - [[#enabling-the-wayland-repository][Enabling the Wayland repository]] + - [[#switching-from-xorg][Switching from Xorg]] + - [[#installing-a-compositor][Installing a Compositor]] - [[#contribution-guidelines][Contribution Guidelines]] - [[#conventions][Conventions]] - [[#shell-conventions][Shell Conventions]] - [[#repository-conventions][Repository Conventions]] + - [[#contributing-to-the-community-repository][Contributing to the Community repository]] + - [[#sending-patches][Sending Patches]] + - [[#git-patches][Git Patches]] + - [[#fossil-patches][Fossil Patches]] - [[#gnu-free-documentation-license][GNU Free Documentation License]] * Copying @@ -81,7 +88,7 @@ with your favorite pager. You can install either the @command{info} or :COPYING: t :END: -Copyright \copy 2020-2021 Cem Keylan +Copyright \copy 2020-{{{time(%Y)}}} Cem Keylan #+BEGIN_QUOTE Permission is granted to copy, distribute and/or modify this document @@ -101,7 +108,7 @@ Documentation License." #+NAME: pubkey #+begin_src sh :exports none -PUBKEY=carbslinux-2021.08.pub +PUBKEY=carbslinux-2023.02.pub #+end_src These are the step-by-step instructions for installing Carbs Linux. It can be @@ -169,8 +176,8 @@ curl -L https://dl.carbslinux.org/releases/x86_64/carbs-rootfs.tar.xz.sig #+end_src #+RESULTS: -: 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= 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 @@ -195,8 +202,6 @@ If everything went alright, this should output: Signature Verified #+end_example - - *** Extracting the tarball :PROPERTIES: :DESCRIPTION: Extracting the root filesystem to the desired location @@ -260,7 +265,7 @@ Carbs Linux rsync repositories live in rsync://carbslinux.org/repo. In order to obtain it, run the following: #+BEGIN_SRC sh -rsync -avc rsync://carbslinux.org/repo $HOME/repos/carbs +rsync -avc rsync://vaylin.carbslinux.org/repo $HOME/repos/carbs #+END_SRC **** Making the package manager use the repositories @@ -271,7 +276,7 @@ following lines: #+BEGIN_SRC sh 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_SRC @@ -395,6 +400,37 @@ replace the 'localhost' part of these entries to your hostname. ::1 localhost.localdomain localhost ip6-localhost #+END_EXAMPLE +*** Creating a user +:PROPERTIES: +:DESCRIPTION: Adding a user to your new system +:END: + +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 + +#+BEGIN_SRC sh +# 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_SRC + +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 + +#+begin_src sh +su foo +#+end_src + ** Kernel :PROPERTIES: :DESCRIPTION: Compiling your own kernel @@ -411,17 +447,21 @@ 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. +supported. Note that kernel releases are quite rapid, and the version below is +likely outdated, so don't run it verbatim. #+BEGIN_SRC sh # 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_SRC +*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]]. + *** Kernel dependencies :PROPERTIES: :DESCRIPTION: Requirements for building the kernel @@ -684,20 +724,23 @@ currently running on your system and not the one you are switching to. | runit | =runit-init 6= | | shinit/sinit | =kill -s INT 1= | -** 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. +** Wayland +:PROPERTIES: +:DESCRIPTION: Maintaining a Wayland display system +:END: -*** 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][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. -**** Enabling the Wayland repository +*** Enabling the Wayland repository +:PROPERTIES: +:DESCRIPTION: Including the wayland repository in your repository path +:END: The =wayland= repository requires packages from =xorg= and =extra= repositories. So you should set your =$CPT_PATH= so that =core= and =extra= repositories @@ -709,7 +752,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_src @@ -720,23 +762,35 @@ After you have enabled your repositories, go ahead and install =wayland= and cpt-build wayland wayland-protocols #+end_src -**** Switching from Xorg +*** Switching from Xorg +:PROPERTIES: +:DESCRIPTION: Rebuilding system packages for wayland +:END: 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. -**** TODO Installing a Compositor +*** Installing a Compositor +:PROPERTIES: +:DESCRIPTION: Getting wayland ready for your system +:END: The =wayland= repository currently only contains =sway= as a Wayland compositor, but you can package something else for your own. +#+begin_src sh +cpt bi sway +#+end_src + * Contribution Guidelines :PROPERTIES: :DESCRIPTION: Contribute to Carbs Linux @@ -818,7 +872,7 @@ themselves. Here are the things to keep in mind: 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. + 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~. @@ -876,19 +930,22 @@ taken literally, they are meant as examples. **** {{{sectid(2220, Meson)}}} +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. + #+BEGIN_SRC sh - #!/bin/sh -e +#!/bin/sh -e - export DESTDIR=$1 +export DESTDIR=$1 - meson \ - --prefix=/usr \ - -Doption=false \ - -Doption2=true \ - . output +cl-meson \ + -Doption=false \ + -Doption2=true \ + . output - ninja -C output - ninja -C output install +ninja -C output +ninja -C output install #+END_SRC **** {{{sectid(2230, Cmake)}}} @@ -920,6 +977,9 @@ taken literally, they are meant as examples. install -Dm755 program "$1/usr/bin/program" #+END_SRC +*NOTE*: Follow 2242 if you are packaging for non-Community repository. +#+TEXINFO: @xref{2242} + **** {{{sectid(2241, Python)}}} #+BEGIN_SRC sh @@ -929,6 +989,135 @@ taken literally, they are meant as examples. python setup.py install --prefix=/usr --root="$1" #+END_SRC +**** {{{sectid(2242, Go (pre-vendored))}}} +:PROPERTIES: +:ID: d2c828ae-bc56-4183-8830-becbf6a812d1 +:END: + +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: + +#+BEGIN_SRC sh +#!/bin/sh -e + +go build -v -mod=vendor +clinst -Dm755 program "$1/usr/bin/program" +#+END_SRC + +** Contributing to the Community repository +:PROPERTIES: +:DESCRIPTION: Package maintainership and issue reports +:END: + +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: + + #+begin_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 [[https://spdx.org/licenses/][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 [[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 *NOT* be accepted. + +- {{{contid(3031)}}} :: + + Issues regarding community packages should be submitted to the + [[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 ~cpt-maintainer <pkg>~. + +** Sending Patches +:PROPERTIES: +:DESCRIPTION: Code contribution +:END: +*** 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=. + +**** =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: + +#+begin_example +[sendemail] + smtpserver = /usr/bin/msmtp + smtpserveroption = -a + smtpserveroption = your-account-name +#+end_example + +**** =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. + +*** 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: + +#+begin_src sh +fossil diff -i > your-changes.patch +#+end_src + +You can also create a binary patch: + +#+begin_src sh +fossil patch create your-changes.db +#+end_src + +If your patchset is complex, and needs to be splitted in multiple check-ins, you +can create a Fossil bundle: + +#+begin_src sh +fossil bundle create --from CHECKIN --to CHECKIN2 patchset.bundle +#+end_src + +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. + * GNU Free Documentation License :PROPERTIES: :APPENDIX: t 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 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 ================================ @@ -1,4 +1,4 @@ -VERSION = 2021.09 +VERSION = 2024.03 # System and build directories PREFIX = /usr/local diff --git a/install.org b/install.org index 21ba261..59d3acc 100644 --- a/install.org +++ b/install.org @@ -1,6 +1,6 @@ -# Created 2021-10-20 Wed 17:22 -#+TITLE: Carbs Linux Installation Guide -#+AUTHOR: Cem Keylan +# Created 2024-03-06 Wed 16:19 +#+title: Carbs Linux Installation Guide +#+author: Cem Keylan 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]]. @@ -50,8 +50,8 @@ it, if you are using a Carbs Linux host, you can also install the package The signature file should say something similar to #+results: -: 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= Grab the key (which probably should be the latest one) that is written on the @@ -61,7 +61,7 @@ check the validity of the public key from multiple locations, or just copy paste that portion to a file and use that instead. #+begin_src sh - PUBKEY=carbslinux-2021.08.pub + PUBKEY=carbslinux-2023.02.pub wget https://dl.carbslinux.org/keys/$PUBKEY #+end_src @@ -77,8 +77,6 @@ If everything went alright, this should output: Signature Verified #+end_example - - ** Extracting the tarball You will need to extract the tarball to your desired location. For partitioning, you can follow [[https://wiki.archlinux.org/index.php/Partitioning][this guide]]. This will assume that you will be mounting your root @@ -130,7 +128,7 @@ Carbs Linux rsync repositories live in rsync://carbslinux.org/repo. In order to obtain it, run the following: #+begin_src sh - rsync -avc rsync://carbslinux.org/repo $HOME/repos/carbs + rsync -avc rsync://vaylin.carbslinux.org/repo $HOME/repos/carbs #+end_src *** Making the package manager use the repositories @@ -141,7 +139,7 @@ following lines: #+begin_src sh 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_src @@ -237,6 +235,33 @@ replace the 'localhost' part of these entries to your hostname. ::1 localhost.localdomain localhost ip6-localhost #+end_example +** 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 + +#+begin_src sh + # 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_src + +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 + +#+begin_src sh + su foo +#+end_src + * Kernel Kernel isn't managed under the main repositories, even though you could package one for your personal use. Here is an [[https://github.com/cemkeylan/kiss-repository/tree/master/personal/linux][example kernel package]], which you will @@ -245,17 +270,21 @@ need to reconfigure for your specific setup if you want to make use of it. ** Obtaining the kernel sources 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. +supported. Note that kernel releases are quite rapid, and the version below is +likely outdated, so don't run it verbatim. #+begin_src sh # 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_src +*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]]. + ** Kernel dependencies 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 @@ -315,8 +344,8 @@ without UEFI support (or you really want to use BIOS for a reason). 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 #+end_src diff --git a/install.txt b/install.txt index 0704b7b..00c7109 100644 --- a/install.txt +++ b/install.txt @@ -1,9 +1,9 @@ - ________________________________ + ________________________________ - CARBS LINUX INSTALLATION GUIDE + CARBS LINUX INSTALLATION GUIDE - Cem Keylan - ________________________________ + Cem Keylan + ________________________________ These are the step-by-step instructions for installing Carbs Linux. It @@ -30,6 +30,7 @@ can be acquired as plain-text to be viewed offline with a pager from 3. System Configuration .. 1. Configuring hostname .. 2. Hosts file +.. 3. Creating a user 4. Kernel .. 1. Obtaining the kernel sources .. 2. Kernel dependencies @@ -94,8 +95,8 @@ can be acquired as plain-text to be viewed offline with a pager from 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= `---- @@ -107,7 +108,7 @@ can be acquired as plain-text to be viewed offline with a pager from use that instead. ,---- - | PUBKEY=carbslinux-2021.08.pub + | PUBKEY=carbslinux-2023.02.pub | wget https://dl.carbslinux.org/keys/$PUBKEY `---- @@ -196,7 +197,7 @@ can be acquired as plain-text to be viewed offline with a pager from 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 `---- @@ -209,7 +210,7 @@ can be acquired as plain-text to be viewed offline with a pager from ,---- | 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 `---- @@ -331,6 +332,37 @@ can be acquired as plain-text to be viewed offline with a pager from `---- +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 + `---- + + 4 Kernel ======== @@ -348,17 +380,22 @@ can be acquired as plain-text to be viewed offline with a pager from 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>. + 4.2 Kernel dependencies ~~~~~~~~~~~~~~~~~~~~~~~ @@ -444,8 +481,8 @@ can be acquired as plain-text to be viewed offline with a pager from | 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 `---- |