diff options
| -rw-r--r-- | .gitmodules | 6 | ||||
| -rw-r--r-- | Makefile | 19 | ||||
| -rw-r--r-- | carbslinux.org | 288 | ||||
| -rw-r--r-- | carbslinux.texi | 348 | ||||
| -rw-r--r-- | carbslinux.txt | 324 | ||||
| -rw-r--r-- | config.mk | 2 | ||||
| m--------- | flatui | 0 | ||||
| m--------- | htmlize | 0 | ||||
| -rw-r--r-- | install.org | 66 | ||||
| -rw-r--r-- | install.txt | 84 |
10 files changed, 936 insertions, 201 deletions
diff --git a/.gitmodules b/.gitmodules deleted file mode 100644 index f9768bd..0000000 --- a/.gitmodules +++ /dev/null @@ -1,6 +0,0 @@ -[submodule "htmlize"] - path = htmlize - url = https://github.com/hniksic/emacs-htmlize.git -[submodule "flatui"] - path = flatui - url = https://github.com/john2x/flatui-theme.el.git @@ -22,10 +22,10 @@ carbslinux.texi: ${ORG} ${EMACS} carbslinux.org -f org-texinfo-export-to-texinfo clean: - rm -f carbslinux.info + rm -f carbslinux.info carbslinux-docs-${VERSION}.tar.xz allclean: clean - rm -f carbslinux.txt install.txt carbslinux.texi + rm -f install.org carbslinux.txt install.txt carbslinux.texi htmldocs: mkdir -p "${HTMLDIR}" @@ -38,18 +38,17 @@ htmldocs: cp install.txt ${HTMLDIR}/install.txt install: - install -Dm644 carbslinux.info "${DESTDIR}${INFODIR}/carbslinux.info" - install -Dm644 carbslinux.txt "${DESTDIR}${DOCDIR}/carbslinux/carbslinux.txt" + ${INSTALLSH} -Dm644 carbslinux.info "${DESTDIR}${INFODIR}/carbslinux.info" + ${INSTALLSH} -Dm644 carbslinux.txt "${DESTDIR}${DOCDIR}/carbslinux/carbslinux.txt" uninstall: rm -f "${DESTDIR}${INFODIR}/carbslinux.info" rm -f "${DESTDIR}${DOCDIR}/carbslinux/carbslinux.txt" dist: ${TARGET} - mkdir -p carbs-docs-${VERSION} - cp README.md Makefile config.mk ${ORG} ${TEXI} ${TARGET} carbs-docs-${VERSION} - tar cf carbs-docs-${VERSION}.tar carbs-docs-${VERSION} - xz -z carbs-docs-${VERSION}.tar - rm -r carbs-docs-${VERSION} + pax -ws ,^,carbs-docs-${VERSION}/, \ + LICENSE README.md Makefile config.mk ${ORG} ${TEXI} ${TARGET} \ + tools | \ + xz -cz > carbs-docs-${VERSION}.tar.xz -.PHONY: all dist htmldocs install clean uninstall +.PHONY: all dist htmldocs install allclean clean uninstall diff --git a/carbslinux.org b/carbslinux.org index c4c5083..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. @@ -31,9 +31,9 @@ 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_EXPORT @@ -53,6 +53,7 @@ for doing the first. - [[#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]] @@ -62,17 +63,24 @@ for doing the first. - [[#init-scripts][Init scripts]] - [[#fstab][Fstab]] - [[#post-installation][Post-installation]] + - [[#irc][IRC]] - [[#kiss-repositories][KISS repositories]] - [[#software][Software]] - [[#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 @@ -80,7 +88,7 @@ for doing the first. :COPYING: t :END: -Copyright \copy 2020 Cem Keylan +Copyright \copy 2020-{{{time(%Y)}}} Cem Keylan #+BEGIN_QUOTE Permission is granted to copy, distribute and/or modify this document @@ -100,7 +108,7 @@ Documentation License." #+NAME: pubkey #+begin_src sh :exports none -PUBKEY=carbslinux-2021.07.pub +PUBKEY=carbslinux-2023.02.pub #+end_src These are the step-by-step instructions for installing Carbs Linux. It can be @@ -168,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.07.pub -: RWQ79tImLgmmq5LjSRcelhb0lquuNXOVkLYuaqaH6kDTZAiU/mlc97recADvGJ6UuU38XANqes91KzWiJsncqC2q4SZQO09DWwA= +: 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 @@ -194,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 @@ -259,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 @@ -270,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 @@ -394,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 @@ -410,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 @@ -537,6 +578,15 @@ The base installation is now complete, you can now fine tune your system 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. +*** IRC +:PROPERTIES: +:DESCRIPTION: Joining the IRC channel +:END: + +The IRC channel for Carbs Linux is located in =#carbslinux= on [[https://libera.chat][libera.chat]]. You +can install the =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. + *** KISS repositories :PROPERTIES: :DESCRIPTION: Acquire kiss repositories @@ -549,6 +599,9 @@ expect any KISS package that was changed during or after July 2021 to work with =cpt=. * Software +:PROPERTIES: +:DESCRIPTION: Details on configuring your system's software +:END: 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 @@ -671,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 @@ -696,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 @@ -707,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 @@ -805,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~. @@ -863,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)}}} @@ -907,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 @@ -916,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 266489d..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 -* Software:: +* Software:: Details on configuring your system's software * Contribution Guidelines:: Contribute to Carbs Linux * GNU Free Documentation License:: Your rights @@ -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 @@ -109,31 +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 -* 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 @@ -215,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.07.pub -RWQ79tImLgmmq5LjSRcelhb0lquuNXOVkLYuaqaH6kDTZAiU/mlc97recADvGJ6UuU38XANqes91KzWiJsncqC2q4SZQO09DWwA= +untrusted comment: verify with carbslinux-2023.02.pub +RWTe38zmx+iyuKEL5T84MJ5Y24jqenkTtQLJxbaMzOBS/NkGVl5J+Vn2B6vTV/gJK7LYBPS+IOXV5sEf+YLGCMcBYAGHCcP4xQ8= @end example @@ -227,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.07.pub +PUBKEY=carbslinux-2023.02.pub wget https://dl.carbslinux.org/keys/$PUBKEY @end example @@ -292,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 @@ -310,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 @@ -330,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 @@ -444,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 @@ -468,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 @@ -486,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 @@ -557,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 @@ -567,7 +612,7 @@ grub-mkconfig -o /boot/grub/grub.cfg @end example @item -GRUB UEFI installation +@anchor{GRUB UEFI installation}GRUB UEFI installation @example @@ -612,9 +657,17 @@ 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 @@ -636,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 @@ -668,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 @@ -694,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 @@ -703,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 @@ -755,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 @@ -775,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 @@ -809,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 @@ -820,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 @@ -830,24 +877,27 @@ this step. The packages that need a rebuild are: @itemize @item -gtk+3 +@samp{gtk+3} @item -gtk4 +@samp{gtk4} @item -mesa +@samp{mesa} @item -xorg-server (for Xwayland support) -@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 @@ -858,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 @@ -960,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 @@ -989,7 +1041,10 @@ taken literally, they are meant as examples. @enumerate @item -Make [@anchor{2210}2210] +@anchor{Make [2210]}Make [2210] + + +@anchor{2210} @example @@ -1000,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 @@ -1016,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} @@ -1036,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 @@ -1055,7 +1122,10 @@ ninja -C output install @end example @item -Cmake [@anchor{2230}2230] +@anchor{Cmake [2230]}Cmake [2230] + + +@anchor{2230} @example @@ -1073,7 +1143,10 @@ cmake --install build @end example @item -Go [@anchor{2240}2240] +@anchor{Go [2240]}Go [2240] + + +@anchor{2240} @example @@ -1087,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 @@ -1097,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 6079275..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 @@ -33,17 +34,24 @@ _________________ ..... 2. Init scripts ..... 3. Fstab .. 6. Post-installation -..... 1. KISS repositories +..... 1. IRC +..... 2. KISS repositories 3. Software .. 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 @@ -61,7 +69,7 @@ with the info reader. It is divided into sections and easier to read. 1 Copying ========= - Copyright (c) 2020 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 @@ -96,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 @@ -105,7 +114,8 @@ with the info reader. It is divided into sections and easier to read. ..... 2. Init scripts ..... 3. Fstab .. 6. Post-installation - ..... 1. KISS repositories + ..... 1. IRC + ..... 2. KISS repositories 2.1 Preparing Environment @@ -157,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.07.pub - | RWQ79tImLgmmq5LjSRcelhb0lquuNXOVkLYuaqaH6kDTZAiU/mlc97recADvGJ6UuU38XANqes91KzWiJsncqC2q4SZQO09DWwA= + | untrusted comment: verify with carbslinux-2023.02.pub + | RWTe38zmx+iyuKEL5T84MJ5Y24jqenkTtQLJxbaMzOBS/NkGVl5J+Vn2B6vTV/gJK7LYBPS+IOXV5sEf+YLGCMcBYAGHCcP4xQ8= `---- @@ -170,7 +180,7 @@ with the info reader. It is divided into sections and easier to read. use that instead. ,---- - | PUBKEY=carbslinux-2021.07.pub + | PUBKEY=carbslinux-2023.02.pub | wget https://dl.carbslinux.org/keys/$PUBKEY `---- @@ -257,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 `---- @@ -269,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 `---- @@ -391,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 ~~~~~~~~~~ @@ -408,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 ------------------------- @@ -502,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 `---- @@ -543,7 +589,19 @@ with the info reader. It is divided into sections and easier to read. learn more about the system. -2.6.1 KISS repositories +2.6.1 IRC +--------- + + The IRC channel for Carbs Linux is located in `#carbslinux' on + [libera.chat]. You can install the `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. + + +[libera.chat] <https://libera.chat> + + +2.6.2 KISS repositories ----------------------- There have been recent changes to the `kiss' package manager that @@ -681,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 @@ -699,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 @@ -711,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 `---- @@ -723,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 ========================= @@ -828,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 @@ -856,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 | @@ -866,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 | @@ -881,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 | @@ -898,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 @@ -916,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 | @@ -933,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 | @@ -944,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 | @@ -955,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.07 +VERSION = 2024.03 # System and build directories PREFIX = /usr/local diff --git a/flatui b/flatui deleted file mode 160000 -Subproject 9c15db5526c15c8dba55023f5698372b19c2a78 diff --git a/htmlize b/htmlize deleted file mode 160000 -Subproject 49205105898ba8993b5253beec55d8bddd820a7 diff --git a/install.org b/install.org index fb7c7e3..59d3acc 100644 --- a/install.org +++ b/install.org @@ -1,6 +1,6 @@ -# Created 2021-07-23 Fri 19:20 -#+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.07.pub -: RWQ79tImLgmmq5LjSRcelhb0lquuNXOVkLYuaqaH6kDTZAiU/mlc97recADvGJ6UuU38XANqes91KzWiJsncqC2q4SZQO09DWwA= +: 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.07.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 @@ -344,6 +373,11 @@ The base installation is now complete, you can now fine tune your system 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. +** IRC +The IRC channel for Carbs Linux is located in =#carbslinux= on [[https://libera.chat][libera.chat]]. You +can install the =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. + ** KISS repositories There have been recent changes to the =kiss= package manager that breaks compatibility with =cpt=. These changes throw away the entire premise of their diff --git a/install.txt b/install.txt index e80dd75..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 @@ -41,7 +42,8 @@ can be acquired as plain-text to be viewed offline with a pager from .. 2. Init scripts .. 3. Fstab 6. Post-installation -.. 1. KISS repositories +.. 1. IRC +.. 2. KISS repositories 1 Preparing Environment @@ -93,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.07.pub - | RWQ79tImLgmmq5LjSRcelhb0lquuNXOVkLYuaqaH6kDTZAiU/mlc97recADvGJ6UuU38XANqes91KzWiJsncqC2q4SZQO09DWwA= + | untrusted comment: verify with carbslinux-2023.02.pub + | RWTe38zmx+iyuKEL5T84MJ5Y24jqenkTtQLJxbaMzOBS/NkGVl5J+Vn2B6vTV/gJK7LYBPS+IOXV5sEf+YLGCMcBYAGHCcP4xQ8= `---- @@ -106,7 +108,7 @@ can be acquired as plain-text to be viewed offline with a pager from use that instead. ,---- - | PUBKEY=carbslinux-2021.07.pub + | PUBKEY=carbslinux-2023.02.pub | wget https://dl.carbslinux.org/keys/$PUBKEY `---- @@ -195,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 `---- @@ -208,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 `---- @@ -330,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 ======== @@ -347,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 ~~~~~~~~~~~~~~~~~~~~~~~ @@ -443,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 `---- @@ -484,7 +522,19 @@ can be acquired as plain-text to be viewed offline with a pager from learn more about the system. -6.1 KISS repositories +6.1 IRC +~~~~~~~ + + The IRC channel for Carbs Linux is located in `#carbslinux' on + [libera.chat]. You can install the `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. + + +[libera.chat] <https://libera.chat> + + +6.2 KISS repositories ~~~~~~~~~~~~~~~~~~~~~ There have been recent changes to the `kiss' package manager that |