diff options
Diffstat (limited to 'carbslinux.org')
| -rw-r--r-- | carbslinux.org | 269 |
1 files changed, 229 insertions, 40 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 |