aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--.gitmodules6
-rw-r--r--Makefile54
-rw-r--r--carbslinux.org405
-rw-r--r--carbslinux.texi483
-rw-r--r--carbslinux.txt454
-rw-r--r--clean.do7
-rw-r--r--config.mk13
-rw-r--r--config.rc19
-rw-r--r--default.do73
-rw-r--r--docs.el24
m---------flatui0
m---------htmlize0
-rw-r--r--install.html.do23
-rw-r--r--install.org386
-rw-r--r--install.txt140
-rw-r--r--install.txt.do13
-rw-r--r--lib.rc84
-rwxr-xr-xtools/do446
18 files changed, 1624 insertions, 1006 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
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..f7ca11a
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,54 @@
+include config.mk
+ORG = carbslinux.org fdl.org
+TEXI = carbslinux.texi
+
+TARGET = carbslinux.info install.txt carbslinux.txt install.org
+
+all: ${TARGET}
+
+carbslinux.info: carbslinux.texi
+ ${MAKEINFO} -o $@ carbslinux.texi
+
+install.txt: ${ORG}
+ ${EMACS} carbslinux.org -f docs-install-txt
+
+install.org: ${ORG}
+ ${EMACS} carbslinux.org -f docs-install-org
+
+carbslinux.txt: ${ORG}
+ ${EMACS} carbslinux.org -f org-ascii-export-to-ascii
+
+carbslinux.texi: ${ORG}
+ ${EMACS} carbslinux.org -f org-texinfo-export-to-texinfo
+
+clean:
+ rm -f carbslinux.info carbslinux-docs-${VERSION}.tar.xz
+
+allclean: clean
+ rm -f install.org carbslinux.txt install.txt carbslinux.texi
+
+htmldocs:
+ mkdir -p "${HTMLDIR}"
+ rm -rf ${HTMLDIR}/carbslinux \
+ ${HTMLDIR}/carbslinux.html \
+ ${HTMLDIR}/install.html.in \
+ ${HTMLDIR}/install.txt
+ ${MAKEINFO} --html -o ${HTMLDIR}/carbslinux ${TEXI}
+ ${MAKEINFO} --html --no-split -o ${HTMLDIR}/carbslinux.html ${TEXI}
+ cp install.txt ${HTMLDIR}/install.txt
+
+install:
+ ${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}
+ 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 allclean clean uninstall
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
diff --git a/carbslinux.texi b/carbslinux.texi
index 532bd38..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
-* Init System:: Configure the init system
+* Software:: Details on configuring your system's software
* Contribution Guidelines:: Contribute to Carbs Linux
* GNU Free Documentation License:: Your rights
@@ -81,7 +81,6 @@ Preparing Environment
* Download:: Download the root filesystem tarball
* Signature verification:: Verify the signature of the rootfs tarball
* Extracting the tarball:: Extracting the root filesystem to the desired location
-* Obtain the chroot helper:: Download the script to easily chroot into the new filesystem
Chroot
@@ -95,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
@@ -110,32 +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
+* 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
-Configuring Init
-
-* Kernel Command Line:: Configure init through the boot parameters
-* @samp{/etc/init/rc.conf} file: @samp{/etc/init/rcconf} file. Configure init through the configuration file
-* Init Hooks:: Configure init through hooks
-
-Changing Init Program
+Wayland
-* Rebooting after changing init:: Ways to reboot after replacing the init system
+* 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
@@ -186,7 +195,6 @@ will continue on that point.
* Download:: Download the root filesystem tarball
* Signature verification:: Verify the signature of the rootfs tarball
* Extracting the tarball:: Extracting the root filesystem to the desired location
-* Obtain the chroot helper:: Download the script to easily chroot into the new filesystem
@end menu
@node Download
@@ -218,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.04.pub
-RWTBBPDVQ+aHB3dme2Kerf8XY+vWkIISp7Za2ufKghtlnRXPyObAQQyvEJYrwMVTaCBlPEnSWcnHQz8Nka06YVOIeextNKZY3AQ=
+untrusted comment: verify with carbslinux-2023.02.pub
+RWTe38zmx+iyuKEL5T84MJ5Y24jqenkTtQLJxbaMzOBS/NkGVl5J+Vn2B6vTV/gJK7LYBPS+IOXV5sEf+YLGCMcBYAGHCcP4xQ8=
@end example
@@ -230,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.04.pub
+PUBKEY=carbslinux-2023.02.pub
wget https://dl.carbslinux.org/keys/$PUBKEY
@end example
@@ -258,24 +266,13 @@ mount /dev/sdx1 /mnt
tar xf carbs-rootfs.tar.xz -C /mnt
@end example
-@node Obtain the chroot helper
-@subsection Obtain the chroot helper
-
-You can obtain the @samp{cpt-chroot} script in order to do a simple chroot into your
-new root filesystem.
-
-@example
-wget https://dl.carbslinux.org/distfiles/cpt-chroot
-chmod a+x cpt-chroot
-@end example
-
@node Chroot
@section Chroot
-Chroot into Carbs Linux!
+Chroot into Carbs Linux by running the chroot helper inside the rootfs!
@example
-./cpt-chroot /mnt
+/mnt/bin/cpt-chroot /mnt
@end example
@menu
@@ -306,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
@@ -314,9 +311,9 @@ Carbs Linux git repositories can be found both from the main server and GitHub
@itemize
@item
-git://git.carbslinux.org/repository
+@uref{https://git.carbslinux.org/repository}
@item
-@uref{https://github.com/carbslinux/repository}
+@uref{https://git.sr.ht/~carbslinux/repository}
@end itemize
@example
@@ -324,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
@@ -344,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
@@ -377,7 +374,9 @@ cpt-install package
@node Essential Software
@subsection Essential Software
-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 @strong{Software} section in the full
+documentation to learn more about other packaged software.
@strong{BOOTLOADERS}
@@ -415,36 +414,6 @@ wpa@math{_supplicant}
nano
@item
vim
-@item
-neatvi
-@item
-emacs
-@item
-emacs-nox (terminal-only version of emacs)
-@end itemize
-
-@strong{USER SHELLS}
-
-@itemize
-@item
-bash
-@item
-zsh
-@item
-oksh
-@item
-rc
-@end itemize
-
-@strong{POSIX BASE UTILITIES}
-
-@itemize
-@item
-busybox
-@item
-sbase
-@item
-coreutils
@end itemize
@strong{DOCUMENTATION}
@@ -462,7 +431,7 @@ man-pages-posix
@subsection Obtaining the documentation
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 @samp{texinfo} or the @samp{info} packages in order
to view the documentation.
@example
@@ -486,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
@@ -510,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
@@ -528,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
@@ -599,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
@@ -609,7 +612,7 @@ grub-mkconfig -o /boot/grub/grub.cfg
@end example
@item
-GRUB UEFI installation
+@anchor{GRUB UEFI installation}GRUB UEFI installation
@example
@@ -654,18 +657,43 @@ 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
-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 @samp{kiss} package manager that breaks
+compatibility with @samp{cpt}. These changes throw away the entire premise of their
+"static" packaging system. @samp{cpt} will never implement those changes, so don't
+expect any KISS package that was changed during or after July 2021 to work with
+@samp{cpt}.
+
+@node Software
+@chapter Software
+
+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 (@samp{#carbslinux} on @uref{https://libera.chat, Libera}).
+
+This section goes over the details of some packaged software
+
+@menu
+* Init System:: Configure the init system
+* Wayland:: Maintaining a Wayland display system
+@end menu
@node Init System
-@chapter Init System
+@section Init System
Carbs Linux init scripts are run by the init daemon (@samp{busybox} by default) on
boot and shutdown processes. It also provides its own halting program named
@@ -678,7 +706,7 @@ programs.
@end menu
@node Configuring Init
-@section Configuring Init
+@subsection Configuring Init
There are three ways you can change the behaviour of the init system. Those are:
@@ -691,14 +719,10 @@ Kernel Command Line
Init Hooks
@end itemize
-@menu
-* Kernel Command Line:: Configure init through the boot parameters
-* @samp{/etc/init/rc.conf} file: @samp{/etc/init/rcconf} file. Configure init through the configuration file
-* Init Hooks:: Configure init through hooks
-@end menu
+@enumerate
+@item
+@anchor{Kernel Command Line}Kernel Command Line
-@node Kernel Command Line
-@subsection Kernel Command Line
On GRUB, you can edit the kernel command line parameters, which will be parsed
as variables on the init system. Not all of the parameters will be acted upon,
@@ -722,16 +746,18 @@ quiet=1
Some of these variables, such as @samp{rw=/=ro}, @samp{loglevel}, and @samp{quiet}, will be
used by the init system to change the behaviour of the startup.
-@node @samp{/etc/init/rcconf} file
-@subsection @samp{/etc/init/rc.conf} file
+@item
+@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
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.
-@node Init Hooks
-@subsection Init Hooks
+@item
+@anchor{Init Hooks}Init Hooks
+
Init hooks are for custom personal commands that the user may want to add to
alter their boot. These can be used to load kernel modules, modify interfaces,
@@ -751,9 +777,10 @@ Run just before filesystems are unmounted.
@item post.shutdown
Run just before the system is halted.
@end table
+@end enumerate
@node Changing Init Program
-@section Changing Init Program
+@subsection Changing Init Program
By default, Carbs Linux comes preinstalled with @samp{busybox-init}, but this can
easily be replaced without any issues. Currently, available init systems are:
@@ -762,7 +789,7 @@ easily be replaced without any issues. Currently, available init systems are:
@item
@samp{sinit}
@item
-@samp{busybox}
+@samp{busybox} init
@item
@samp{runit}
@item
@@ -779,12 +806,10 @@ cpt a runit /usr/bin/poweroff
cpt a runit /usr/bin/reboot
@end example
-@menu
-* Rebooting after changing init:: Ways to reboot after replacing the init system
-@end menu
+@enumerate
+@item
+@anchor{Rebooting after changing init}Rebooting after changing init
-@node Rebooting after changing init
-@subsection Rebooting after changing init
After switching init systems, your running init system may not accept the
new poweroff commands. You will need to reboot/poweroff using the running init's
@@ -801,6 +826,78 @@ currently running on your system and not the one you are switching to.
@item shinit/sinit
@tab @samp{kill -s INT 1}
@end multitable
+@end enumerate
+
+@node 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.
+
+@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
+precede the @samp{wayland} repository, and the @samp{xorg} repository should come after
+@samp{wayland}. Here is an example below, where @samp{$REPOSITORY} points to the root of
+your repository.
+
+@example
+CPT_PATH=$REPOSITORY/core
+CPT_PATH=$CPT_PATH:$REPOSITORY/extra
+CPT_PATH=$CPT_PATH:$REPOSITORY/wayland
+export CPT_PATH
+@end example
+
+After you have enabled your repositories, go ahead and install @samp{wayland} and
+@samp{wayland-protocols} packages.
+
+@example
+cpt-build wayland wayland-protocols
+@end example
+
+@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
+this step. The packages that need a rebuild are:
+
+@itemize
+@item
+@samp{gtk+3}
+@item
+@samp{gtk4}
+@item
+@samp{mesa}
+@item
+@samp{webkit2gtk}
+@end itemize
+
+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.
+
+@example
+cpt bi sway
+@end example
@node Contribution Guidelines
@chapter Contribution Guidelines
@@ -811,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
@@ -913,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
@@ -942,7 +1041,10 @@ taken literally, they are meant as examples.
@enumerate
@item
-Make [@anchor{2210}2210]
+@anchor{Make [2210]}Make [2210]
+
+
+@anchor{2210}
@example
@@ -953,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
@@ -969,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}
@@ -989,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
@@ -1008,7 +1122,10 @@ ninja -C output install
@end example
@item
-Cmake [@anchor{2230}2230]
+@anchor{Cmake [2230]}Cmake [2230]
+
+
+@anchor{2230}
@example
@@ -1026,7 +1143,10 @@ cmake --install build
@end example
@item
-Go [@anchor{2240}2240]
+@anchor{Go [2240]}Go [2240]
+
+
+@anchor{2240}
@example
@@ -1040,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
@@ -1050,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 1451ef2..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
@@ -15,7 +15,6 @@ _________________
..... 1. Download
..... 2. Signature verification
..... 3. Extracting the tarball
-..... 4. Obtain the chroot helper
.. 2. Chroot
..... 1. Setting up repositories
..... 2. Updating packages
@@ -25,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
@@ -34,18 +34,24 @@ _________________
..... 2. Init scripts
..... 3. Fstab
.. 6. Post-installation
-..... 1. KISS repositories
-3. Init System
-.. 1. Configuring Init
-..... 1. Kernel Command Line
-..... 2. `/etc/init/rc.conf' file
-..... 3. Init Hooks
-.. 2. Changing Init Program
-..... 1. Rebooting after changing init
+..... 1. IRC
+..... 2. KISS repositories
+3. Software
+.. 1. Init System
+..... 1. Configuring Init
+..... 2. Changing Init Program
+.. 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
@@ -63,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
@@ -89,7 +95,6 @@ with the info reader. It is divided into sections and easier to read.
..... 1. Download
..... 2. Signature verification
..... 3. Extracting the tarball
- ..... 4. Obtain the chroot helper
.. 2. Chroot
..... 1. Setting up repositories
..... 2. Updating packages
@@ -99,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
@@ -108,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
@@ -160,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.04.pub
- | RWTBBPDVQ+aHB3dme2Kerf8XY+vWkIISp7Za2ufKghtlnRXPyObAQQyvEJYrwMVTaCBlPEnSWcnHQz8Nka06YVOIeextNKZY3AQ=
+ | untrusted comment: verify with carbslinux-2023.02.pub
+ | RWTe38zmx+iyuKEL5T84MJ5Y24jqenkTtQLJxbaMzOBS/NkGVl5J+Vn2B6vTV/gJK7LYBPS+IOXV5sEf+YLGCMcBYAGHCcP4xQ8=
`----
@@ -173,7 +180,7 @@ with the info reader. It is divided into sections and easier to read.
use that instead.
,----
- | PUBKEY=carbslinux-2021.04.pub
+ | PUBKEY=carbslinux-2023.02.pub
| wget https://dl.carbslinux.org/keys/$PUBKEY
`----
@@ -209,25 +216,14 @@ with the info reader. It is divided into sections and easier to read.
[this guide] <https://wiki.archlinux.org/index.php/Partitioning>
-2.1.4 Obtain the chroot helper
-------------------------------
-
- You can obtain the `cpt-chroot' script in order to do a simple chroot
- into your new root filesystem.
-
- ,----
- | wget https://dl.carbslinux.org/distfiles/cpt-chroot
- | chmod a+x cpt-chroot
- `----
-
-
2.2 Chroot
~~~~~~~~~~
- Chroot into Carbs Linux!
+ Chroot into Carbs Linux by running the chroot helper inside the
+ rootfs!
,----
- | ./cpt-chroot /mnt
+ | /mnt/bin/cpt-chroot /mnt
`----
@@ -257,8 +253,8 @@ with the info reader. It is divided into sections and easier to read.
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>
,----
| git clone git://git.carbslinux.org/repository $HOME/repos/carbs
@@ -271,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
`----
@@ -283,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
`----
@@ -319,7 +315,10 @@ with the info reader. It is divided into sections and easier to read.
2.2.4 Essential Software
------------------------
- 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*
@@ -341,22 +340,6 @@ with the info reader. It is divided into sections and easier to read.
- nano
- vim
- - neatvi
- - emacs
- - emacs-nox (terminal-only version of emacs)
-
- *USER SHELLS*
-
- - bash
- - zsh
- - oksh
- - rc
-
- *POSIX BASE UTILITIES*
-
- - busybox
- - sbase
- - coreutils
*DOCUMENTATION*
@@ -369,8 +352,8 @@ with the info reader. It is divided into sections and easier to read.
---------------------------------
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 to view the documentation.
+ manual to be viewed offline. You can obtain either `texinfo' or the
+ `info' packages in order to view the documentation.
,----
| # Install the documentation.
@@ -418,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
~~~~~~~~~~
@@ -435,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
-------------------------
@@ -529,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
`----
@@ -570,17 +589,44 @@ 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
-----------------------
- 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'.
+
+
+3 Software
+==========
+
+ 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
+ [Libera]).
+
+ This section goes over the details of some packaged software
-3 Init System
-=============
+[Libera] <https://libera.chat>
+
+3.1 Init System
+~~~~~~~~~~~~~~~
Carbs Linux init scripts are run by the init daemon (`busybox' by
default) on boot and shutdown processes. It also provides its own
@@ -588,8 +634,8 @@ with the info reader. It is divided into sections and easier to read.
doesn't rely on non-POSIX external programs.
-3.1 Configuring Init
-~~~~~~~~~~~~~~~~~~~~
+3.1.1 Configuring Init
+----------------------
There are three ways you can change the behaviour of the init
system. Those are:
@@ -599,8 +645,7 @@ with the info reader. It is divided into sections and easier to read.
- Init Hooks
-3.1.1 Kernel Command Line
--------------------------
+* 3.1.1.1 Kernel Command Line
On GRUB, you can edit the kernel command line parameters, which will
be parsed as variables on the init system. Not all of the parameters
@@ -627,8 +672,7 @@ with the info reader. It is divided into sections and easier to read.
startup.
-3.1.2 `/etc/init/rc.conf' file
-------------------------------
+* 3.1.1.2 `/etc/init/rc.conf' file
However, the kernel command line isn't the only place to set your boot
parameters. You can specify variables here as well, although note that
@@ -636,8 +680,7 @@ with the info reader. It is divided into sections and easier to read.
since they can be set just before boot.
-3.1.3 Init Hooks
-----------------
+* 3.1.1.3 Init Hooks
Init hooks are for custom personal commands that the user may want to
add to alter their boot. These can be used to load kernel modules,
@@ -658,15 +701,15 @@ with the info reader. It is divided into sections and easier to read.
Run just before the system is halted.
-3.2 Changing Init Program
-~~~~~~~~~~~~~~~~~~~~~~~~~
+3.1.2 Changing Init Program
+---------------------------
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'
@@ -681,8 +724,7 @@ with the info reader. It is divided into sections and easier to read.
`----
-3.2.1 Rebooting after changing init
------------------------------------
+* 3.1.2.1 Rebooting after changing init
After switching init systems, your running init system may not accept
the new poweroff commands. You will need to reboot/poweroff using the
@@ -697,6 +739,73 @@ with the info reader. It is divided into sections and easier to read.
shinit/sinit `kill -s INT 1'
+3.2 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
+ its careful design and implementation. Users who want to use a Wayland
+ compositor should follow this section.
+
+
+[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
+ `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.
+
+ ,----
+ | CPT_PATH=$REPOSITORY/core
+ | CPT_PATH=$CPT_PATH:$REPOSITORY/extra
+ | CPT_PATH=$CPT_PATH:$REPOSITORY/wayland
+ | export CPT_PATH
+ `----
+
+ After you have enabled your repositories, go ahead and install
+ `wayland' and `wayland-protocols' packages.
+
+ ,----
+ | cpt-build wayland wayland-protocols
+ `----
+
+
+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'
+ - `webkit2gtk'
+
+ For xorg support inside wayland sessions, you need to install the
+ `xwayland' package.
+
+
+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
=========================
@@ -782,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
@@ -810,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
|
@@ -820,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
|
@@ -835,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
|
@@ -852,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
@@ -870,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
|
@@ -887,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
|
@@ -898,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
|
@@ -909,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
================================
diff --git a/clean.do b/clean.do
deleted file mode 100644
index d71b034..0000000
--- a/clean.do
+++ /dev/null
@@ -1,7 +0,0 @@
-. ./config.rc
-
-rm -f carbslinux.info carbslinux.html
-rm -rf carbslinux
-rm -f -- ./*.tar.*
-redo_clean
-PHONY
diff --git a/config.mk b/config.mk
new file mode 100644
index 0000000..17bb72c
--- /dev/null
+++ b/config.mk
@@ -0,0 +1,13 @@
+VERSION = 2024.03
+
+# System and build directories
+PREFIX = /usr/local
+SHAREDIR = ${PREFIX}/share
+INFODIR = ${SHAREDIR}/info
+DOCDIR = ${SHAREDIR}/doc
+HTMLDIR = ./carbslinux
+
+EMACS = emacs --batch -l docs.el
+MAKEINFO = makeinfo
+
+INSTALLSH = ./tools/install.sh
diff --git a/config.rc b/config.rc
deleted file mode 100644
index 3cba001..0000000
--- a/config.rc
+++ /dev/null
@@ -1,19 +0,0 @@
-# -*- mode: redo; -*-
-# Source the helper library
-. ./lib.rc
-
-setv PREFIX = /usr/local
-setv SHAREDIR = ${PREFIX}/share
-setv INFODIR = ${SHAREDIR}/info
-setv DOCDIR = ${SHAREDIR}/doc
-setv TARBALL = "carbs-docs-$(date +%Y%m%d)"
-setv HTMLDIR = ./carbslinux
-setv ORG = carbslinux.org
-setv TEXI = carbslinux.texi
-
-setv EMACS = emacs --batch
-setv MAKEINFO = makeinfo
-
-setv INSTALLSH = ./tools/install.sh
-
-PHONY all dist htmldocs install clean
diff --git a/default.do b/default.do
deleted file mode 100644
index e72e62c..0000000
--- a/default.do
+++ /dev/null
@@ -1,73 +0,0 @@
-exec >&2
-. ./config.rc
-
-fn=${1%.*}
-
-date=$(date +%Y%m%d)
-export date
-
-case "$1" in
- *.txt|*.texi)
- [ -f "$fn.org" ] || {
- printf '%s\n' "Don't know how to build $1"
- exit 1
- }
- redo-ifchange "$fn.org" fdl.org
- trap 'rm -f $3.org' EXIT INT
- cp "$fn.org" "$3.org"
-esac
-
-case "$1" in
- all) redo-ifchange carbslinux.info install.txt carbslinux.txt ;;
- allclean)
- rm -f carbslinux.texi install.txt carbslinux.txt
- redo clean
- PHONY
- ;;
- htmldocs)
- redo-ifchange carbslinux.org carbslinux.texi install.txt install.html
- mkdir -p "${HTMLDIR:?}"
- rm -rf "$HTMLDIR/carbslinux" \
- "$HTMLDIR/carbslinux.html" \
- "$HTMLDIR/install.html.in" \
- "$HTMLDIR/install.txt"
- makeinfo --html -o "$HTMLDIR/carbslinux" "$TEXI"
- makeinfo --html --no-split -o "$HTMLDIR/carbslinux.html" "$TEXI"
- cp install.txt "$HTMLDIR/install.txt"
- cp install.html "$HTMLDIR/install.html.in"
- PHONY
- ;;
- *.txt)
- ${EMACS} "$3.org" -f org-ascii-export-to-ascii
- mv "$3.txt" "$3"
- ;;
- *.texi)
- ${EMACS} "$3.org" -f org-texinfo-export-to-texinfo
- mv "$3.texi" "$3"
- ;;
- *.info)
- redo-ifchange "$fn.texi"
- ${MAKEINFO} "$fn.texi" -o "$3"
- ;;
- "carbs-docs-$date.tar.xz")
- target=$1 dest=$3
- set -- README.md ./*.do ./*.org config.rc lib.rc carbslinux.info \
- install.txt carbslinux.txt
- redo-ifchange "$@"
- trap 'rm -rf carbs-docs-$date carbs-docs-$date.tar' EXIT INT
- mkdir -p "carbs-docs-$date"
- cp README.md ./*.do ./*.org config.rc lib.rc \
- carbslinux.info install.txt carbslinux.txt "carbs-docs-$date"
- tar cf "carbs-docs-$date.tar" "carbs-docs-$date"
- xz -cz "carbs-docs-$date.tar" > "$dest"
- ;;
- install)
- redo-ifchange carbslinux.info carbslinux.txt
- "$INSTALLSH" -Dm644 carbslinux.info "${DESTDIR}${INFODIR}/carbslinux.info"
- "$INSTALLSH" -Dm644 carbslinux.txt "${DESTDIR}${DOCDIR}/carbslinux.txt"
- ;;
- dist)
- redo-ifchange "carbs-docs-$date.tar.xz"
- ;;
- *) printf '%s\n' "Unknown operation $1"; exit 1
-esac
diff --git a/docs.el b/docs.el
new file mode 100644
index 0000000..d3838e8
--- /dev/null
+++ b/docs.el
@@ -0,0 +1,24 @@
+;;; docs.el --- configuration for docs exports
+;;; Commentary:
+;;; Code:
+(require 'org)
+(require 'ox)
+(require 'ox-ascii)
+
+;; We do NOT want backup files.
+(setq make-backup-files nil)
+
+(defun docs-install-txt ()
+ "Extract and export installation manual from the User Manual."
+ (let ((org-export-with-toc nil))
+ (re-search-forward "^* Installation")
+ (org-ascii-export-to-ascii nil t)))
+
+(defun docs-install-org ()
+ "Extract and export installation manual as an org file from the User Manual."
+ (let ((org-export-with-toc nil))
+ (re-search-forward "^* Installation")
+ (org-org-export-to-org nil t)))
+
+(provide 'docs)
+;;; docs.el ends here
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.html.do b/install.html.do
deleted file mode 100644
index 838e3d6..0000000
--- a/install.html.do
+++ /dev/null
@@ -1,23 +0,0 @@
-exec >&2
-. ./config.rc
-redo-ifchange "$ORG" htmlize/htmlize.el flatui/flatui-theme.el
-
-cp "$ORG" "$3.org"
-trap 'rm -f $3.html $3.org' EXIT INT
-
-# Org HTML export is a bit of a mess from the command line. I have added flatui
-# and htmlize repositories as a submodule so that we don't rely on packages.
-${EMACS} "$3.org" --eval \
-'(progn
-(load-file "flatui/flatui-theme.el")
-(add-to-list '"'"'custom-theme-load-path (concat default-directory "flatui/"))
-(load-theme '"'"'flatui t)
-(load-file "htmlize/htmlize.el") (org-mode)
-(replace-regexp "^* Installation" "* Carbs Linux Installation Guide")
-(setq org-export-with-toc nil)
-(org-html-export-to-html nil t nil t)
-(revert-buffer nil t)
-)'
-
-printf '%s\n' "<h1>Carbs Linux Installation Guide</h1>" > "$3"
-cat "$3.html" >> "$3"
diff --git a/install.org b/install.org
new file mode 100644
index 0000000..59d3acc
--- /dev/null
+++ b/install.org
@@ -0,0 +1,386 @@
+# 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]].
+
+#+begin_src sh
+ curl -sL https://carbslinux.org/install.txt | less
+#+end_src
+
+#+toc: headlines 3 local
+* Preparing Environment
+To install Carbs Linux, you will need a Live Linux ISO. For that purpose, you
+can obtain a Gentoo or Void Linux live image. You can follow their instructions
+to boot and setup your network.
+
+You will need the following programs in order to install Carbs Linux:
+
+- tar
+- wget
+- xz
+- some form of base utilities (coreutils, sbase, busybox, etc.)
+
+Rest of these instructions will assume that you have set all of these up, and
+will continue on that point.
+
+** Download
+First, we need to download the rootfs tarball. You can do the following in order
+to obtain the rootfs. If you are using an i686 machine, replace the =x86_64=
+with =i686=. We are setting this in a URL variable so that we don't have to
+write it every time.
+
+#+begin_src sh
+ URL=https://dl.carbslinux.org/releases/x86_64
+ wget $URL/carbs-rootfs.tar.xz.sha256
+ sha256sum -c carbs-rootfs.tar.xz.sha256
+#+end_src
+
+** Signature verification
+It is highly recommended to verify the signature of the tarball. You will need
+the OpenBSD tool =signify(1)= for this. Many distributions provide a package for
+it, if you are using a Carbs Linux host, you can also install the package
+=otools= which provides =signify=. Download the signature first.
+
+#+begin_src sh
+ wget $URL/carbs-rootfs.tar.xz.sig
+#+end_src
+
+The signature file should say something similar to
+
+#+results:
+: 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
+latest Signify public key is also available on the [[https://git.carbslinux.org/repository][package repository]], so you can
+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-2023.02.pub
+ wget https://dl.carbslinux.org/keys/$PUBKEY
+#+end_src
+
+You can now verify the distribution tarball with signify.
+
+#+begin_src sh
+ signify -V -m carbs-rootfs.tar.xz -p $PUBKEY
+#+end_src
+
+If everything went alright, this should output:
+
+#+begin_example
+ 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
+partition to =/mnt=.
+
+#+begin_src sh
+ mount /dev/sdx1 /mnt
+ tar xf carbs-rootfs.tar.xz -C /mnt
+#+end_src
+
+* Chroot
+Chroot into Carbs Linux by running the chroot helper inside the rootfs!
+
+#+begin_src sh
+ /mnt/bin/cpt-chroot /mnt
+#+end_src
+
+** Setting up repositories
+Newest tarballs do not come with repositories, so you will need to manually
+obtain them, and set your =CPT_PATH= environment variable. Carbs Linux
+repositories can either be obtained by =git= or =rsync=. While rsync
+repositories are overall faster and smaller, git offers the whole history of the
+repository and a means to manipulate your repository as you like it. If you want
+to obtain the git repository, you will need to install =git= itself.
+
+The following guide will assume that you put the repositories into =~/repos/=
+directory, but you can put the repositories into any directory you want. So go
+ahead and create that directory:
+
+#+begin_src sh
+ mkdir -p $HOME/repos
+#+end_src
+
+*** Obtaining from git
+
+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.
+
+- https://git.carbslinux.org/repository
+- https://git.sr.ht/~carbslinux/repository
+
+#+begin_src sh
+ git clone git://git.carbslinux.org/repository $HOME/repos/carbs
+#+end_src
+
+*** Obtaining from rsync
+
+Carbs Linux rsync repositories live in rsync://carbslinux.org/repo. In
+order to obtain it, run the following:
+
+#+begin_src sh
+ rsync -avc rsync://vaylin.carbslinux.org/repo $HOME/repos/carbs
+#+end_src
+
+*** Making the package manager use the repositories
+
+In your shell's configuration file, or in your =~/.profile= file, add the
+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/wayland
+ CPT_PATH=$CPT_PATH:$HOME/repos/carbs/community
+ export CPT_PATH
+#+end_src
+
+** Updating packages
+It is good practice to make sure your system is up to date, especially before
+building new packages. If there is an update for the package manager you will
+need to update twice.
+
+#+begin_src sh
+ cpt-update && cpt-update
+#+end_src
+
+** Installing packages
+Since you are operating on a really small base, you might need to build and
+install new programs to extend the functionality of your system. In order to
+build and install packages new packages in Carbs, you need to execute the
+following. "Package" is not actually a package and is given as an example.
+
+#+begin_src sh
+ cpt-build package
+ cpt-install package
+#+end_src
+
+** Essential Software
+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*
+
+- efibootmgr
+- grub
+
+*FILESYSTEMS*
+
+- e2fsprogs
+- dosfstools
+- ntfs-3g
+
+*NETWORKING*
+
+- dhcpcd
+- wpa_supplicant
+
+*TEXT EDITORS*
+
+- nano
+- vim
+
+*DOCUMENTATION*
+
+- carbs-docs
+- man-pages
+- man-pages-posix
+
+** Obtaining the documentation
+All the documentation for Carbs Linux can be found on a single info manual to be
+viewed offline. You can obtain either =texinfo= or the =info= packages in order
+to view the documentation.
+
+#+begin_src sh
+ # Install the documentation.
+ cpt b carbs-docs && cpt i carbs-docs
+
+ # Install either texinfo or the info package. We will be installing standalone info
+ # as it doesn't need perl.
+ cpt b info && cpt i info
+
+ # You can then run info and navigate through the documentation.
+ info carbslinux
+#+end_src
+
+* System Configuration
+After you have finished installing some extra packages, you can configure your
+system to your liking.
+
+** Configuring hostname
+You might want to add a hostname, especially in a networked environment. Your
+hostname will default to 'carbslinux' unless you set this.
+
+#+begin_src sh
+ echo your-hostname > /etc/hostname
+#+end_src
+
+** Hosts file
+You can edit your /etc/hosts file, which is the static lookup table for host
+names. By default, there are two entries for localhost which are OKAY. You can
+replace the 'localhost' part of these entries to your hostname.
+
+#+begin_example
+ 127.0.0.1 localhost.localdomain localhost
+ ::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
+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. 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.19.4.tar.xz
+ tar xJf linux-5.19.4.tar.xz
+
+ # Change directory into the kernel sources
+ 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
+using the menu interface you will also need =ncurses=.
+
+#+begin_src sh
+ # The package manager asks to install if you are building more than one package,
+ # so no need to run 'cpt i ...'
+ cpt b libelf ncurses
+#+end_src
+
+In the vanilla kernel sources, you need perl to compile the kernel, but it can
+be easily patched out. You will need to apply the following patch. Patch was
+written by [[https://github.com/E5ten][E5ten]]. You will need to obtain and apply the patch in the kernel
+source directory.
+
+#+begin_src sh
+ wget https://dl.carbslinux.org/distfiles/kernel-no-perl.patch
+ patch -p1 < kernel-no-perl.patch
+#+end_src
+
+** Building the kernel
+Next step is configuring and building the kernel. You can check Gentoo's
+[[https://wiki.gentoo.org/wiki/Kernel/Configuration][kernel configuration guide]] to learn more about the matter. Overall, Gentoo Wiki
+is a good place to learn about configuration according to your hardware. The
+following will assume a monolithic kernel.
+
+#+begin_src sh
+ make menuconfig
+ make
+ install -Dm755 $(make -s image_name) /boot/vmlinuz-linux
+#+end_src
+
+* Making your system bootable
+In order to be able to boot your fresh system, wou will need an init-daemon,
+init-scripts and a bootloader. The init daemon is already provided by busybox,
+but you can optionally change it.
+
+** Bootloader
+In the main repository, there is efibootmgr and grub to serve as bootloaders.
+efibootmgr can be used as a standalone bootloader, or can be used to install
+grub in a UEFI environment. efibootmgr is needed unless you are using a device
+without UEFI support (or you really want to use BIOS for a reason).
+
+*** GRUB BIOS installation
+
+#+begin_src sh
+ cpt b grub && cpt i grub
+ grub-install --target=i386-pc /dev/sdX
+ grub-mkconfig -o /boot/grub/grub.cfg
+#+end_src
+
+*** GRUB UEFI installation
+
+#+begin_src sh
+ cpt b efibootmgr && cpt i efibootmgr
+ cpt b grub && cpt i grub
+
+ grub-install --target=x86_64-efi \
+ --efi-directory=esp \
+ --bootloader-id=CarbsLinux
+
+ grub-mkconfig -o /boot/grub/grub.cfg
+#+end_src
+
+** Init scripts
+Only thing left to do is installing the init-scripts, and now you are almost
+ready to boot your system!
+
+#+begin_src sh
+ cpt b carbs-init && cpt i carbs-init
+#+end_src
+
+** Fstab
+You can now manually edit your fstab entry, or you can use the genfstab tool.
+If you want to use the tool, exit the chroot and run the following:
+
+#+begin_src sh
+ wget https://github.com/cemkeylan/genfstab/raw/master/genfstab
+ chmod +x genfstab
+ ./genfstab -U /mnt >> /mnt/etc/fstab
+#+end_src
+
+* Post-installation
+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
+"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=.
diff --git a/install.txt b/install.txt
index 59e892e..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
@@ -18,7 +18,6 @@ can be acquired as plain-text to be viewed offline with a pager from
.. 1. Download
.. 2. Signature verification
.. 3. Extracting the tarball
-.. 4. Obtain the chroot helper
2. Chroot
.. 1. Setting up repositories
..... 1. Obtaining from git
@@ -31,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
@@ -42,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
@@ -94,8 +95,8 @@ can be acquired as plain-text to be viewed offline with a pager from
The signature file should say something similar to
,----
- | untrusted comment: verify with carbslinux-2021.04.pub
- | RWTBBPDVQ+aHB3dme2Kerf8XY+vWkIISp7Za2ufKghtlnRXPyObAQQyvEJYrwMVTaCBlPEnSWcnHQz8Nka06YVOIeextNKZY3AQ=
+ | untrusted comment: verify with carbslinux-2023.02.pub
+ | RWTe38zmx+iyuKEL5T84MJ5Y24jqenkTtQLJxbaMzOBS/NkGVl5J+Vn2B6vTV/gJK7LYBPS+IOXV5sEf+YLGCMcBYAGHCcP4xQ8=
`----
@@ -107,7 +108,7 @@ can be acquired as plain-text to be viewed offline with a pager from
use that instead.
,----
- | PUBKEY=carbslinux-2021.04.pub
+ | PUBKEY=carbslinux-2023.02.pub
| wget https://dl.carbslinux.org/keys/$PUBKEY
`----
@@ -143,25 +144,14 @@ can be acquired as plain-text to be viewed offline with a pager from
[this guide] <https://wiki.archlinux.org/index.php/Partitioning>
-1.4 Obtain the chroot helper
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
- You can obtain the `cpt-chroot' script in order to do a simple chroot
- into your new root filesystem.
-
- ,----
- | wget https://dl.carbslinux.org/distfiles/cpt-chroot
- | chmod a+x cpt-chroot
- `----
-
-
2 Chroot
========
- Chroot into Carbs Linux!
+ Chroot into Carbs Linux by running the chroot helper inside the
+ rootfs!
,----
- | ./cpt-chroot /mnt
+ | /mnt/bin/cpt-chroot /mnt
`----
@@ -192,8 +182,8 @@ can be acquired as plain-text to be viewed offline with a pager from
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>
,----
| git clone git://git.carbslinux.org/repository $HOME/repos/carbs
@@ -207,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
`----
@@ -220,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
`----
@@ -256,7 +246,10 @@ can be acquired as plain-text to be viewed offline with a pager from
2.4 Essential Software
~~~~~~~~~~~~~~~~~~~~~~
- 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*
@@ -278,22 +271,6 @@ can be acquired as plain-text to be viewed offline with a pager from
- nano
- vim
- - neatvi
- - emacs
- - emacs-nox (terminal-only version of emacs)
-
- *USER SHELLS*
-
- - bash
- - zsh
- - oksh
- - rc
-
- *POSIX BASE UTILITIES*
-
- - busybox
- - sbase
- - coreutils
*DOCUMENTATION*
@@ -306,8 +283,8 @@ can be acquired as plain-text to be viewed offline with a pager from
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 to view the documentation.
+ manual to be viewed offline. You can obtain either `texinfo' or the
+ `info' packages in order to view the documentation.
,----
| # Install the documentation.
@@ -355,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
========
@@ -372,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
~~~~~~~~~~~~~~~~~~~~~~~
@@ -468,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
`----
@@ -509,10 +522,23 @@ 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
~~~~~~~~~~~~~~~~~~~~~
- 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'.
diff --git a/install.txt.do b/install.txt.do
deleted file mode 100644
index bb6f727..0000000
--- a/install.txt.do
+++ /dev/null
@@ -1,13 +0,0 @@
-exec >&2
-. ./config.rc
-redo-ifchange "$ORG"
-
-cp "$ORG" "$3.org"
-trap 'rm -f $3.org' EXIT INT
-
-${EMACS} "$3.org" --eval \
- '(progn (replace-regexp "^* Installation" "* Carbs Linux Installation Guide")
- (setq org-export-with-toc nil)
- (org-ascii-export-to-ascii nil t))'
-
-mv "$3.txt" "$3"
diff --git a/lib.rc b/lib.rc
deleted file mode 100644
index 3c713e2..0000000
--- a/lib.rc
+++ /dev/null
@@ -1,84 +0,0 @@
-# Various helper functions for redo
-# URL: https://github.com/cemkeylan/redo-lib
-# LICENSE: CC0 (Public Domain)
-
-# 'basename' is not used by the functions here, but it doesn't mean that it
-# cannot be used at all.
-# shellcheck disable=2034
-target=$1 basename=$2 dest=$3
-
-# Add dependency to these files as well.
-redo-ifchange lib.rc config.rc
-
-setv() {
- # Usage: setv [variable = [key...]]
- #
- # Variable setting function that somewhat imitates the Makefile syntax.
- # - Using == sets the variable.
- # - Using = sets the variable if it is unset.
- # - Using += increments to a variable.
- [ "$3" ] || {
- printf '%s\n' "Faulty variable syntax" >&2
- exit 1
- }
- var=$1 sym=$2; shift 2
- case "$sym" in
- ==) export "$var=$*" ;;
- =) eval "[ \"\$$var\" ]" || export "$var=$*" ;;
- +=) eval export "$var=\$$var $*"
- esac
-}
-
-targcheck() {
- # Usage: targcheck [target...]
- #
- # Check if current target is one of the given arguments of this function.
- # Returns 0 if target is one of the arguments, returns 1 if not.
- for arg; do
- [ "$arg" = "$target" ] && return 0
- done; return 1
-}
-
-PHONY() {
- # Usage: PHONY [target...]
- #
- # Function that resembles the .PHONY: target on the classic 'make' system.
- # You can either use it without an argument on a single target, or specify
- # multiple targets.
- if [ -z "$1" ] || targcheck "$@"; then
- # There is no guarantee that the value of dest will not be modified
- # during the operation, we want to evaluate the value of $dest as soon
- # as possible
- # shellcheck disable=2064
- trap "rm -f $dest" EXIT INT
- fi
-}
-
-expsuf() {
- # Usage: expsuf [suffix [item...]]
- #
- # Expand suffix for the given list.
- suffix=$1 buf=; shift
- for i; do buf="$buf $i$suffix "; done; printf %s "$buf"
-}
-
-repsuf() {
- # Usage: repsuf [old-suffix new-suffix [item...]]
- #
- # Replace old-suffix with new-suffix on list.
- oldsuffix=$1 newsuffix=$2 buf=; shift 2
- for i; do buf="$buf ${i%$oldsuffix}$newsuffix "; done; printf %s "$buf"
-}
-
-redo_clean() {
- # Clean function for various redo implementations
- [ -r .do_built ] && {
- while read -r file; do
- [ -d "$file" ] || rm -f "$file"
- done < .do_built
- }
- find . -type f \( -name '*.tmp' -o -name '*.did' -o -name '.dep*' -o -name '.target*' \) \
- -exec rm -f -- {} +
- [ "$DO_BUILT" ] || find . -name '.do_built*' -exec rm -rf -- {} +
- [ "$REDO_BASE" ] || rm -rf -- .redo
-}
diff --git a/tools/do b/tools/do
deleted file mode 100755
index f38a2a7..0000000
--- a/tools/do
+++ /dev/null
@@ -1,446 +0,0 @@
-#!/bin/sh
-#
-# A minimal alternative to djb redo that doesn't support incremental builds.
-# For the full version, visit http://github.com/apenwarr/redo
-#
-# The author disclaims copyright to this source file and hereby places it in
-# the public domain. (2010 12 14; updated 2019 02 24)
-#
-USAGE="
-usage: do [-d] [-x] [-v] [-c] <targets...>
- -d print extra debug messages (mostly about dependency checks)
- -v run .do files with 'set -v'
- -x run .do files with 'set -x'
- -c clean up all old targets before starting
-
- Note: do is an implementation of redo that does *not* check dependencies.
- It will never rebuild a target it has already built, unless you use -c.
-"
-
-# CDPATH apparently causes unexpected 'cd' output on some platforms.
-unset CDPATH
-
-# By default, no output coloring.
-green=""
-bold=""
-plain=""
-
-if [ -n "$TERM" -a "$TERM" != "dumb" ] && tty <&2 >/dev/null 2>&1; then
- green="$(printf '\033[32m')"
- bold="$(printf '\033[1m')"
- plain="$(printf '\033[m')"
-fi
-
-# The 'seq' command is not available on all platforms.
-_seq() {
- local x=0 max="$1"
- while [ "$x" -lt "$max" ]; do
- x=$((x + 1))
- echo "$x"
- done
-}
-
-# Split $1 into a dir part ($_dirsplit_dir) and base filename ($_dirsplit_base)
-_dirsplit() {
- _dirsplit_base=${1##*/}
- _dirsplit_dir=${1%$_dirsplit_base}
-}
-
-# Like /usr/bin/dirname, but avoids a fork and uses _dirsplit semantics.
-qdirname() (
- _dirsplit "$1"
- dir=${_dirsplit_dir%/}
- echo "${dir:-.}"
-)
-
-_dirsplit "$0"
-REDO=$(cd "$(pwd -P)" &&
- cd "${_dirsplit_dir:-.}" &&
- echo "$PWD/$_dirsplit_base")
-export REDO
-_cmd=$_dirsplit_base
-
-DO_TOP=
-if [ -z "$DO_BUILT" ]; then
- export _do_opt_debug=
- export _do_opt_exec=
- export _do_opt_verbose=
- export _do_opt_clean=
-fi
-while getopts 'dxvcj:h?' _opt; do
- case $_opt in
- d) _do_opt_debug=1 ;;
- x) _do_opt_exec=x ;;
- v) _do_opt_verbose=v ;;
- c) _do_opt_clean=1 ;;
- j) ;; # silently ignore, for compat with real redo
- \?|h|*) printf "%s" "$USAGE" >&2
- exit 99
- ;;
- esac
-done
-shift "$((OPTIND - 1))"
-_debug() {
- [ -z "$_do_opt_debug" ] || echo "$@" >&2
-}
-
-if [ -z "$DO_BUILT" -a "$_cmd" != "redo-whichdo" ]; then
- DO_TOP=1
- if [ "$#" -eq 0 ] && [ "$_cmd" = "do" -o "$_cmd" = "redo" ]; then
- set all # only toplevel redo has a default target
- fi
- export DO_STARTDIR="$(pwd -P)"
- # If starting /bin/pwd != $PWD, this will fix it.
- # That can happen when $PWD contains symlinks that the shell is
- # trying helpfully (but unsuccessfully) to hide from the user.
- cd "$DO_STARTDIR" || exit 99
- export DO_BUILT="$PWD/.do_built"
- if [ -z "$_do_opt_clean" -a -e "$DO_BUILT" ]; then
- echo "do: Incremental mode. Use -c for clean rebuild." >&2
- fi
- : >>"$DO_BUILT"
- sort -u "$DO_BUILT" >"$DO_BUILT.new"
- while read f; do
- [ -n "$_do_opt_clean" ] && printf "%s\0%s.did\0" "$f" "$f"
- printf "%s.did.tmp\0" "$f"
- done <"$DO_BUILT.new" |
- xargs -0 rm -f 2>/dev/null
- mv "$DO_BUILT.new" "$DO_BUILT"
- export DO_PATH="$DO_BUILT.dir"
- export PATH="$DO_PATH:$PATH"
- rm -rf "$DO_PATH"
- mkdir "$DO_PATH"
- for d in redo redo-ifchange redo-whichdo; do
- ln -s "$REDO" "$DO_PATH/$d"
- done
- for d in redo-ifcreate redo-stamp redo-always redo-ood \
- redo-targets redo-sources; do
- echo "#!/bin/sh" >"$DO_PATH/$d"
- chmod a+rx "$DO_PATH/$d"
- done
-fi
-
-
-# Chop the "file" part off a /path/to/file pathname.
-# Note that if the filename already ends in a /, we just remove the slash.
-_updir()
-{
- local v="${1%/*}"
- [ "$v" != "$1" ] && echo "$v"
- # else "empty" which means we went past the root
-}
-
-
-# Returns true if $1 starts with $2.
-_startswith()
-{
- [ "${1#"$2"}" != "$1" ]
-}
-
-
-# Returns true if $1 ends with $2.
-_endswith()
-{
- [ "${1%"$2"}" != "$1" ]
-}
-
-
-# Prints $1 if it's absolute, or $2/$1 if $1 is not absolute.
-_abspath()
-{
- local here="$2" there="$1"
- if _startswith "$1" "/"; then
- echo "$1"
- else
- echo "$2/$1"
- fi
-}
-
-
-# Prints $1 as a path relative to $PWD (not starting with /).
-# If it already doesn't start with a /, doesn't change the string.
-_relpath()
-{
- local here="$2" there="$1" out= hadslash=
- #echo "RP start '$there' hs='$hadslash'" >&2
- _startswith "$there" "/" || { echo "$there" && return; }
- [ "$there" != "/" ] && _endswith "$there" "/" && hadslash=/
- here=${here%/}/
- while [ -n "$here" ]; do
- #echo "RP out='$out' here='$here' there='$there'" >&2
- [ "${here%/}" = "${there%/}" ] && there= && break;
- [ "${there#$here}" != "$there" ] && break
- out=../$out
- _dirsplit "${here%/}"
- here=$_dirsplit_dir
- done
- there=${there#$here}
- if [ -n "$there" ]; then
- echo "$out${there%/}$hadslash"
- else
- echo "${out%/}$hadslash"
- fi
-}
-
-
-# Prints a "normalized relative" path, with ".." resolved where possible.
-# For example, a/b/../c will be reduced to just a/c.
-_normpath()
-(
- local path="$1" relto="$2" out= isabs=
- #echo "NP start '$path'" >&2
- if _startswith "$path" "/"; then
- isabs=1
- else
- path="${relto%/}/$path"
- fi
- set -f
- IFS=/
- for d in ${path%/}; do
- #echo "NP out='$out' d='$d'" >&2
- if [ "$d" = ".." ]; then
- out=$(_updir "${out%/}")/
- else
- out=$out$d/
- fi
- done
- #echo "NP out='$out' (done)" >&2
- out=${out%/}
- if [ -n "$isabs" ]; then
- echo "${out:-/}"
- else
- _relpath "${out:-/}" "$relto"
- fi
-)
-
-
-# Prints a "real" path, with all symlinks resolved where possible.
-_realpath()
-{
- local path="$1" relto="$2" isabs= rest=
- if _startswith "$path" "/"; then
- isabs=1
- else
- path="${relto%/}/$path"
- fi
- (
- for d in $(_seq 100); do
- #echo "Trying: $PWD--$path" >&2
- if cd -P "$path" 2>/dev/null; then
- # success
- pwd=$(pwd -P)
- #echo " chdir ok: $pwd--$rest" >&2
- np=$(_normpath "${pwd%/}/$rest" "$relto")
- if [ -n "$isabs" ]; then
- echo "$np"
- else
- _relpath "$np" "$relto"
- fi
- break
- fi
- _dirsplit "${path%/}"
- path=$_dirsplit_dir
- rest="$_dirsplit_base/$rest"
- done
- )
-}
-
-
-# List the possible names for default*.do files in dir $1 matching the target
-# pattern in $2. We stop searching when we find the first one that exists.
-_find_dofiles_pwd()
-{
- local dodir="$1" dofile="$2"
- _startswith "$dofile" "default." || dofile=${dofile#*.}
- while :; do
- dofile=default.${dofile#default.*.}
- echo "$dodir$dofile"
- [ -e "$dodir$dofile" ] && return 0
- [ "$dofile" = default.do ] && break
- done
- return 1
-}
-
-
-# List the possible names for default*.do files in $PWD matching the target
-# pattern in $1. We stop searching when we find the first name that works.
-# If there are no matches in $PWD, we'll search in .., and so on, to the root.
-_find_dofiles()
-{
- local target="$1" dodir= dofile= newdir=
- _debug "find_dofile: '$PWD' '$target'"
- dofile="$target.do"
- echo "$dofile"
- [ -e "$dofile" ] && return 0
-
- # Try default.*.do files, walking up the tree
- _dirsplit "$dofile"
- dodir=$_dirsplit_dir
- dofile=$_dirsplit_base
- [ -n "$dodir" ] && dodir=${dodir%/}/
- [ -e "$dodir$dofile" ] && return 0
- for i in $(_seq 100); do
- [ -n "$dodir" ] && dodir=${dodir%/}/
- #echo "_find_dofiles: '$dodir' '$dofile'" >&2
- _find_dofiles_pwd "$dodir" "$dofile" && return 0
- newdir=$(_realpath "${dodir}.." "$PWD")
- [ "$newdir" = "$dodir" ] && break
- dodir=$newdir
- done
- return 1
-}
-
-
-# Print the last .do file returned by _find_dofiles.
-# If that file exists, returns 0, else 1.
-_find_dofile()
-{
- local files="$(_find_dofiles "$1")"
- rv=$?
- #echo "files='$files'" >&2
- [ "$rv" -ne 0 ] && return $rv
- echo "$files" | {
- while read -r linex; do line=$linex; done
- printf "%s\n" "$line"
- }
-}
-
-
-# Actually run the given $dofile with the arguments in $@.
-# Note: you should always run this in a subshell.
-_run_dofile()
-{
- export DO_DEPTH="$DO_DEPTH "
- export REDO_TARGET="$PWD/$target"
- local line1
- set -e
- read line1 <"$PWD/$dofile" || true
- cmd=${line1#"#!/"}
- if [ "$cmd" != "$line1" ]; then
- set -$_do_opt_verbose$_do_opt_exec
- exec /$cmd "$PWD/$dofile" "$@"
- else
- set -$_do_opt_verbose$_do_opt_exec
- # If $dofile is empty, "." might not change $? at
- # all, so we clear it first with ":".
- :; . "$PWD/$dofile"
- fi
-}
-
-
-# Find and run the right .do file, starting in dir $1, for target $2,
-# providing a temporary output file as $3. Renames the temp file to $2 when
-# done.
-_do()
-{
- local dir="$1" target="$1$2" tmp="$1$2.redo.tmp" tdir=
- local dopath= dodir= dofile= ext=
- if [ "$_cmd" = "redo" ] ||
- ( [ ! -e "$target" -o -d "$target" ] &&
- [ ! -e "$target.did" ] ); then
- printf '%sdo %s%s%s%s\n' \
- "$green" "$DO_DEPTH" "$bold" "$target" "$plain" >&2
- dopath=$(_find_dofile "$target")
- if [ ! -e "$dopath" ]; then
- echo "do: $target: no .do file ($PWD)" >&2
- return 1
- fi
- _dirsplit "$dopath"
- dodir=$_dirsplit_dir dofile=$_dirsplit_base
- if _startswith "$dofile" "default."; then
- ext=${dofile#default}
- ext=${ext%.do}
- else
- ext=
- fi
- target=$PWD/$target
- tmp=$PWD/$tmp
- cd "$dodir" || return 99
- target=$(_relpath "$target" "$PWD") || return 98
- tmp=$(_relpath "$tmp" "$PWD") || return 97
- base=${target%$ext}
- tdir=$(qdirname "$target")
- [ ! -e "$DO_BUILT" ] || [ ! -w "$tdir/." ] ||
- : >>"$target.did.tmp"
- # $qtmp is a temporary file used to capture stdout.
- # Since it might be accidentally deleted as a .do file
- # does its work, we create it, then open two fds to it,
- # then immediately delete the name. We use one fd to
- # redirect to stdout, and the other to read from after,
- # because there's no way to fseek(fd, 0) in sh.
- qtmp=$DO_PATH/do.$$.tmp
- (
- rm -f "$qtmp"
- ( _run_dofile "$target" "$base" "$tmp" >&3 3>&- 4<&- )
- rv=$?
- if [ $rv != 0 ]; then
- printf "do: %s%s\n" "$DO_DEPTH" \
- "$target: got exit code $rv" >&2
- rm -f "$tmp.tmp" "$tmp.tmp2" "$target.did"
- return $rv
- fi
- echo "$PWD/$target" >>"$DO_BUILT"
- if [ ! -e "$tmp" ]; then
- # if $3 wasn't created, copy from stdout file
- cat <&4 >$tmp
- # if that's zero length too, forget it
- [ -s "$tmp" ] || rm -f "$tmp"
- fi
- ) 3>$qtmp 4<$qtmp # can't use "|| return" here...
- # ...because "|| return" would mess up "set -e" inside the ()
- # on some shells. Running commands in "||" context, even
- # deep inside, will stop "set -e" from functioning.
- rv=$?
- [ "$rv" = 0 ] || return "$rv"
- mv "$tmp" "$target" 2>/dev/null
- [ -e "$target.did.tmp" ] &&
- mv "$target.did.tmp" "$target.did" ||
- : >>"$target.did"
- else
- _debug "do $DO_DEPTH$target exists." >&2
- fi
-}
-
-
-# Implementation of the "redo" command.
-_redo()
-{
- local i startdir="$PWD" dir base
- set +e
- for i in "$@"; do
- i=$(_abspath "$i" "$startdir")
- (
- cd "$DO_STARTDIR" || return 99
- i=$(_realpath "$(_relpath "$i" "$PWD")" "$PWD")
- _dirsplit "$i"
- dir=$_dirsplit_dir base=$_dirsplit_base
- _do "$dir" "$base"
- )
- [ "$?" = 0 ] || return 1
- done
-}
-
-
-# Implementation of the "redo-whichdo" command.
-_whichdo()
-{
- _find_dofiles "$1"
-}
-
-
-case $_cmd in
- do|redo|redo-ifchange) _redo "$@" ;;
- redo-whichdo) _whichdo "$1" ;;
- do.test) ;;
- *) printf "do: '%s': unexpected redo command" "$_cmd" >&2; exit 99 ;;
-esac
-[ "$?" = 0 ] || exit 1
-
-if [ -n "$DO_TOP" ]; then
- if [ -n "$_do_opt_clean" ]; then
- echo "do: Removing stamp files..." >&2
- [ ! -e "$DO_BUILT" ] ||
- while read f; do printf "%s.did\0" "$f"; done <"$DO_BUILT" |
- xargs -0 rm -f 2>/dev/null
- fi
-fi
generated by cgit v1.2.3 (git 2.39.1) at 2024-04-26 07:14:57 +0000