aboutsummaryrefslogtreecommitdiff
path: root/carbslinux.org
diff options
context:
space:
mode:
Diffstat (limited to 'carbslinux.org')
-rw-r--r--carbslinux.org405
1 files changed, 321 insertions, 84 deletions
diff --git a/carbslinux.org b/carbslinux.org
index 05ad080..21b8117 100644
--- a/carbslinux.org
+++ b/carbslinux.org
@@ -11,12 +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]
-
-#+NAME: pubkey
-#+begin_src sh :exports none
-PUBKEY=carbslinux-2021.04.pub
-#+end_src
+#+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.
@@ -36,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
@@ -49,7 +44,6 @@ for doing the first.
- [[#download][Download]]
- [[#signature-verification][Signature verification]]
- [[#extracting-the-tarball][Extracting the tarball]]
- - [[#obtain-the-chroot-helper][Obtain the chroot helper]]
- [[#chroot][Chroot]]
- [[#setting-up-repositories][Setting up repositories]]
- [[#updating-packages][Updating packages]]
@@ -59,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]]
@@ -68,18 +63,24 @@ for doing the first.
- [[#init-scripts][Init scripts]]
- [[#fstab][Fstab]]
- [[#post-installation][Post-installation]]
+ - [[#irc][IRC]]
- [[#kiss-repositories][KISS repositories]]
-- [[#init-system][Init System]]
- - [[#configuring-init][Configuring Init]]
- - [[#kernel-command-line][Kernel Command Line]]
- - [[#etcinitrcconf-file][=/etc/init/rc.conf= file]]
- - [[#init-hooks][Init Hooks]]
- - [[#changing-init-program][Changing Init Program]]
- - [[#rebooting-after-changing-init][Rebooting after changing init]]
+- [[#software][Software]]
+ - [[#init-system][Init System]]
+ - [[#configuring-init][Configuring Init]]
+ - [[#changing-init-program][Changing Init Program]]
+ - [[#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
@@ -87,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
@@ -105,6 +106,11 @@ Documentation License."
:EXPORT_TITLE: Carbs Linux Installation Guide
:END:
+#+NAME: pubkey
+#+begin_src sh :exports none
+PUBKEY=carbslinux-2023.02.pub
+#+end_src
+
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]].
@@ -170,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.04.pub
-: RWTBBPDVQ+aHB3dme2Kerf8XY+vWkIISp7Za2ufKghtlnRXPyObAQQyvEJYrwMVTaCBlPEnSWcnHQz8Nka06YVOIeextNKZY3AQ=
+: 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
@@ -196,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
@@ -212,28 +216,15 @@ mount /dev/sdx1 /mnt
tar xf carbs-rootfs.tar.xz -C /mnt
#+END_SRC
-*** Obtain the chroot helper
-:PROPERTIES:
-:DESCRIPTION: Download the script to easily chroot into the new filesystem
-:END:
-
-You can obtain the =cpt-chroot= script in order to do a simple chroot into your
-new root filesystem.
-
-#+BEGIN_SRC sh
-wget https://dl.carbslinux.org/distfiles/cpt-chroot
-chmod a+x cpt-chroot
-#+END_SRC
-
** Chroot
:PROPERTIES:
:DESCRIPTION: Going inside your new system
:END:
-Chroot into Carbs Linux!
+Chroot into Carbs Linux by running the chroot helper inside the rootfs!
#+BEGIN_SRC sh
-./cpt-chroot /mnt
+/mnt/bin/cpt-chroot /mnt
#+END_SRC
*** Setting up repositories
@@ -261,8 +252,8 @@ mkdir -p $HOME/repos
Carbs Linux git repositories can be found both from the main server and GitHub
(mirror). Here are both their repository links. You can clone any of them.
-- git://git.carbslinux.org/repository
-- https://github.com/carbslinux/repository
+- https://git.carbslinux.org/repository
+- https://git.sr.ht/~carbslinux/repository
#+BEGIN_SRC sh
git clone git://git.carbslinux.org/repository $HOME/repos/carbs
@@ -274,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
@@ -285,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
@@ -323,7 +314,9 @@ cpt-install package
:DESCRIPTION: Software you might want to include on your system
:END:
-Here is a list of software that you might want to have on your system.
+Here is a small list of software that you might want to have on your system as
+you are setting up. You might want to check the *Software* section in the full
+documentation to learn more about other packaged software.
*BOOTLOADERS*
@@ -345,22 +338,6 @@ Here is a list of software that you might want to have on your system.
- nano
- vim
-- neatvi
-- emacs
-- emacs-nox (terminal-only version of emacs)
-
-*USER SHELLS*
-
-- bash
-- zsh
-- oksh
-- rc
-
-*POSIX BASE UTILITIES*
-
-- busybox
-- sbase
-- coreutils
*DOCUMENTATION*
@@ -374,7 +351,7 @@ Here is a list of software that you might want to have on your system.
:END:
All the documentation for Carbs Linux can be found on a single info manual to be
-viewed offline. You can obtain texinfo or the info (standalone) package in order
+viewed offline. You can obtain either =texinfo= or the =info= packages in order
to view the documentation.
#+BEGIN_SRC sh
@@ -423,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
@@ -439,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
@@ -566,16 +578,39 @@ 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
:END:
-While not 100% compatible with cpt, you can use kiss repositories in your
-system the same way you are using the distribution repositories. Here is an
-example for the KISS Linux Community repository.
+There have been recent changes to the =kiss= package manager that breaks
+compatibility with =cpt=. These changes throw away the entire premise of their
+"static" packaging system. =cpt= will never implement those changes, so don't
+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
+easily package it yourself or request it to be added to the default repositories
+over on the IRC channel (=#carbslinux= on [[https://libera.chat][Libera]]).
+
+This section goes over the details of some packaged software
-* Init System
+** Init System
:PROPERTIES:
:DESCRIPTION: Configure the init system
:END:
@@ -585,7 +620,7 @@ boot and shutdown processes. It also provides its own halting program named
shalt. This provides a portable method that doesn't rely on non-POSIX external
programs.
-** Configuring Init
+*** Configuring Init
:PROPERTIES:
:DESCRIPTION: Ways to configure the init system
:END:
@@ -596,7 +631,7 @@ There are three ways you can change the behaviour of the init system. Those are:
- =/etc/init/rc.conf= file
- Init Hooks
-*** Kernel Command Line
+**** Kernel Command Line
:PROPERTIES:
:DESCRIPTION: Configure init through the boot parameters
:END:
@@ -623,7 +658,7 @@ quiet=1
Some of these variables, such as =rw=/=ro=, =loglevel=, and =quiet=, will be
used by the init system to change the behaviour of the startup.
-*** =/etc/init/rc.conf= file
+**** =/etc/init/rc.conf= file
:PROPERTIES:
:DESCRIPTION: Configure init through the configuration file
:END:
@@ -633,7 +668,7 @@ parameters. You can specify variables here as well, although note that the
kernel command line always gets the priority for these variables since they can
be set just before boot.
-*** Init Hooks
+**** Init Hooks
:PROPERTIES:
:DESCRIPTION: Configure init through hooks
:END:
@@ -650,7 +685,7 @@ hook name as the suffix. For example, a boot script will be placed as
- umount :: Run just before filesystems are unmounted.
- post.shutdown :: Run just before the system is halted.
-** Changing Init Program
+*** Changing Init Program
:PROPERTIES:
:DESCRIPTION: Replace the default busybox init with something new
:END:
@@ -659,7 +694,7 @@ By default, Carbs Linux comes preinstalled with =busybox-init=, but this can
easily be replaced without any issues. Currently, available init systems are:
- =sinit=
-- =busybox=
+- =busybox= init
- =runit=
- =shinit=
@@ -673,7 +708,7 @@ cpt a runit /usr/bin/poweroff
cpt a runit /usr/bin/reboot
#+END_SRC
-*** Rebooting after changing init
+**** Rebooting after changing init
:PROPERTIES:
:DESCRIPTION: Ways to reboot after replacing the init system
:END:
@@ -689,6 +724,73 @@ currently running on your system and not the one you are switching to.
| runit | =runit-init 6= |
| shinit/sinit | =kill -s INT 1= |
+** Wayland
+:PROPERTIES:
+:DESCRIPTION: Maintaining a Wayland display system
+:END:
+
+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
+: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
+precede the =wayland= repository, and the =xorg= repository should come after
+=wayland=. Here is an example below, where =$REPOSITORY= points to the root of
+your repository.
+
+#+begin_src sh
+CPT_PATH=$REPOSITORY/core
+CPT_PATH=$CPT_PATH:$REPOSITORY/extra
+CPT_PATH=$CPT_PATH:$REPOSITORY/wayland
+export CPT_PATH
+#+end_src
+
+After you have enabled your repositories, go ahead and install =wayland= and
+=wayland-protocols= packages.
+
+#+begin_src sh
+cpt-build wayland wayland-protocols
+#+end_src
+
+*** 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=
+- =webkit2gtk=
+
+For xorg support inside wayland sessions, you need to install the =xwayland=
+package.
+
+*** 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
@@ -770,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~.
@@ -828,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)}}}
@@ -872,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
@@ -881,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