aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorCem Keylan <cem@ckyln.com>2020-12-26 02:39:36 +0300
committerCem Keylan <cem@ckyln.com>2020-12-26 03:12:25 +0300
commitd1590234d19724f14e8ba94582986963fce47267 (patch)
tree1bb6273414ef57443b3cdda21f0329b0dc8ae742
parent06aca27d4b504ea5f42f4611fa3b44d9429bea75 (diff)
downloaddocs-20201226.tar.gz
docs: switch to redo build system.20201226
-rw-r--r--.gitignore9
-rw-r--r--Makefile40
-rw-r--r--README.md25
-rw-r--r--carbslinux.txt1327
-rw-r--r--clean.do7
-rw-r--r--config.rc17
-rw-r--r--default.do69
-rw-r--r--install.html.do21
-rw-r--r--install.txt481
-rw-r--r--install.txt.do12
-rw-r--r--lib.rc84
11 files changed, 2045 insertions, 47 deletions
diff --git a/.gitignore b/.gitignore
index f65cec4..a93a059 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,5 +2,14 @@ carbslinux
carbslinux.info
*.tar.*
+### Redo files
+/.redo
+/.do_built
+/.do_built.dir
+*.tmp
+*.did
+.dep*
+.target*
+
### Org HTML output
*.html
diff --git a/Makefile b/Makefile
deleted file mode 100644
index cc64acf..0000000
--- a/Makefile
+++ /dev/null
@@ -1,40 +0,0 @@
-# This Makefile is meant to generate a dist tarball in order to avoid installing
-# texinfo on the target system.
-PREFIX = /usr/local
-SHAREDIR = ${PREFIX}/share
-INFODIR = ${SHAREDIR}/info
-DOCDIR = ${SHAREDIR}/doc
-TARBALL = carbs-docs-`date +%Y%m%d`
-HTMLDIR = ./carbslinux
-TEXI = contribution.texi cpt.texi init.texi install.texi top.texi
-OBJ = carbslinux.info carbslinux.txt
-
-all: ${OBJ}
- @echo run \'make install\' if you want to install the docs.
-
-clean:
- rm -f ${OBJ} ${TARBALL}.tar.gz
-
-carbslinux.txt: ${TEXI}
- makeinfo --plaintext top.texi -o carbslinux.txt
-
-carbslinux.info: ${TEXI}
- makeinfo top.texi -o carbslinux.info
-
-dist: ${OBJ}
- mkdir -p ${TARBALL}
- cp ${OBJ} ${TEXI} Makefile README.md ${TARBALL}
- tar -cf ${TARBALL}.tar ${TARBALL}
- gzip -9 ${TARBALL}.tar
- rm -rf ${TARBALL}.tar ${TARBALL}
-
-htmldocs: ${OBJ}
- rm -f -- ${HTMLDIR}/*
- makeinfo --html -o ${HTMLDIR} top.texi
- makeinfo --plaintext -o ${HTMLDIR}/install.txt install.texi
-
-install: carbslinux.info carbslinux.txt
- install -Dm644 carbslinux.info ${DESTDIR}${INFODIR}/carbslinux.info
- install -Dm644 carbslinux.txt ${DESTDIR}${DOCDIR}/carbslinux.txt
-
-.PHONY: all dist htmldocs install clean
diff --git a/README.md b/README.md
index 78a51fa..9dc1134 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,18 @@
Carbs Linux User Manual
--------------------------------------------------------------------------------
-This is the Carbs Linux documentation written with Texinfo. It can be viewed
-offline by installing the `carbs-docs` package. Distribution tarballs comes with
-prebuilt info and plaintext pages, so they don't depend on the `texinfo`
-package.
+This is the Carbs Linux documentation written with Emacs Org-mode. It can be
+viewed offline by installing the `carbs-docs` package. Distribution tarballs
+come with a prebuilt info page and plaintext pages, so neither `emacs` nor
+`texinfo` is necessary.
+
+You can view offline documentation by doing one of the following:
+
+ less /usr/share/doc/carbslinux.txt
+
+Or:
+
+ info carbslinux
There are two packages in the repository for viewing info files, `texinfo` and
`info`. The `info` package only comes with the statically linked documentation
@@ -12,10 +20,13 @@ reader, so you don't need `perl` to install it.
cpt-build info carbs-docs
-To generate pages from the git repository you will need to install `texinfo`.
+
+To generate info pages from the git repository, you will need to install
+`texinfo`. For your convenience, the plaintext and texinfo files are committed
+directly on the repository, but those files are generated directly from Emacs.
git clone git://git.carbslinux.org/docs
cpt-build texinfo && cpt-install texinfo
- make
- make PREFIX=/usr install
+ redo
+ PREFIX=/usr redo install
install-info /usr/share/info/carbslinux.info /usr/share/info/dir
diff --git a/carbslinux.txt b/carbslinux.txt
new file mode 100644
index 0000000..ddf94f6
--- /dev/null
+++ b/carbslinux.txt
@@ -0,0 +1,1327 @@
+ _________________________
+
+ CARBS LINUX USER MANUAL
+
+ Cem Keylan
+ _________________________
+
+
+Table of Contents
+_________________
+
+1. Copying
+2. Installation
+.. 1. Preparing Environment
+..... 1. Download
+..... 2. Signature verification
+..... 3. Extracting the tarball
+..... 4. Obtain the chroot helper
+.. 2. Chroot
+..... 1. Setting up repositories
+..... 2. Updating packages
+..... 3. Installing packages
+..... 4. Essential Software
+..... 5. Obtaining the documentation
+.. 3. System Configuration
+..... 1. Configuring hostname
+..... 2. Hosts file
+.. 4. Kernel
+..... 1. Obtaining the kernel sources
+..... 2. Kernel dependencies
+..... 3. Building the kernel
+.. 5. Making your system bootable
+..... 1. Bootloader
+..... 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
+4. Contribution Guidelines
+.. 1. Conventions
+..... 1. Shell Conventions
+..... 2. Repository Conventions
+5. GNU Free Documentation License
+
+
+This is the full documentation of [Carbs Linux], from the details of the
+distribution, installation, to the package manager. It is not yet
+complete.
+
+You can build and install the 'info' package in order to view this documentation
+with the info reader. It is divided into sections and easier to read.
+
+
+[Carbs Linux] <https://carbslinux.org>
+
+
+1 Copying
+=========
+
+ Copyright (c) 2020 Cem Keylan
+
+ Permission is granted to copy, distribute and/or modify
+ this document under the terms of the GNU Free
+ Documentation License, Version 1.3 or any later version
+ published by the Free Software Foundation; with no
+ Invariant Sections, with no Front-Cover Texts and no
+ Back-Cover Texts. A copy of the license is included in
+ the section entitled "GNU Free Documentation License."
+
+
+2 Installation
+==============
+
+ 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/docs/install.txt>.
+
+
+2.1 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.
+
+
+2.1.1 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.
+
+ ,----
+ | wget $URL/carbs-rootfs.tar.xz.sha256
+ | sha256sum -c carbs-rootfs.tar.xz.sha256
+ `----
+
+
+2.1.2 Signature verification
+----------------------------
+
+ It is highly recommended to verify the signature of the tarball. You
+ will need GPG for this.
+
+ ,----
+ | wget $URL/carbs-rootfs.tar.xz.sig
+ | gpg --recv-keys FF484BDFEFCEF8FF
+ | gpg --verify carbs-rootfs.tar.xz.sig
+ `----
+
+
+2.1.3 Extracting the tarball
+----------------------------
+
+ You will need to extract the tarball to your desired location. For
+ partitioning, you can follow [this guide]. This will assume that you
+ will be mounting your root partition to `/mnt'.
+
+ ,----
+ | mount /dev/sdx1 /mnt
+ | tar xf carbs-rootfs.tar.xz -C /mnt
+ `----
+
+
+[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!
+
+ ,----
+ | ./cpt-chroot /mnt
+ `----
+
+
+2.2.1 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:
+
+ ,----
+ | mkdir -p $HOME/repos
+ `----
+
+
+* 2.2.1.1 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.
+
+ - git://git.carbslinux.org/repository
+ - <https://github.com/carbslinux/repository>
+
+ ,----
+ | git clone git://git.carbslinux.org/repository $HOME/repos/carbs
+ `----
+
+
+* 2.2.1.2 Obtaining from rsync
+
+ Carbs Linux rsync repositories live in rsync://carbslinux.org/repo. In
+ order to obtain it, run the following:
+
+ ,----
+ | rsync -avc rsync://carbslinux.org/repo $HOME/repos/carbs
+ `----
+
+
+* 2.2.1.3 Making the package manager use the repositories
+
+ In your shell's configuration file, or in your `~/.profile' file, add
+ the following lines:
+
+ ,----
+ | 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/community
+ | export CPT_PATH
+ `----
+
+
+2.2.2 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.
+
+ ,----
+ | cpt-update && cpt-update
+ `----
+
+
+2.2.3 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.
+
+ ,----
+ | cpt-build package
+ | cpt-install package
+ `----
+
+
+2.2.4 Essential Software
+------------------------
+
+ Here is a list of software that you might want to have on your system.
+
+ *BOOTLOADERS*
+
+ - efibootmgr
+ - grub
+
+ *FILESYSTEMS*
+
+ - e2fsprogs
+ - dosfstools
+ - ntfs-3g
+
+ *NETWORKING*
+
+ - dhcpcd
+ - wpa_supplicant
+
+ *TEXT EDITORS*
+
+ - nano
+ - vim
+ - neatvi
+ - emacs
+ - emacs-nox (terminal-only version of emacs)
+
+ *USER SHELLS*
+
+ - bash
+ - zsh
+ - oksh
+ - rc
+
+ *POSIX BASE UTILITIES*
+
+ - busybox
+ - sbase
+ - coreutils
+
+ *DOCUMENTATION*
+
+ - carbs-docs
+ - man-pages
+ - man-pages-posix
+
+
+2.2.5 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 to view the documentation.
+
+ ,----
+ | # 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
+ `----
+
+
+2.3 System Configuration
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+ After you have finished installing some extra packages, you can
+ configure your system to your liking.
+
+
+2.3.1 Configuring hostname
+--------------------------
+
+ You might want to add a hostname, especially in a networked
+ environment. Your hostname will default to 'carbslinux' unless you set
+ this.
+
+ ,----
+ | echo your-hostname > /etc/hostname
+ `----
+
+
+2.3.2 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.
+
+ ,----
+ | 127.0.0.1 localhost.localdomain localhost
+ | ::1 localhost.localdomain localhost ip6-localhost
+ `----
+
+
+2.4 Kernel
+~~~~~~~~~~
+
+ Kernel isn't managed under the main repositories, even though you
+ could package one for your personal use. Here is an [example kernel
+ package], which you will need to reconfigure for your specific setup
+ if you want to make use of it.
+
+
+[example kernel package]
+<https://github.com/cemkeylan/kiss-repository/tree/master/personal/linux>
+
+2.4.1 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.
+
+ ,----
+ | # 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
+ |
+ | # Change directory into the kernel sources
+ | cd linux-5.9.1
+ `----
+
+
+2.4.2 Kernel dependencies
+-------------------------
+
+ In order to compile the kernel you will need to install some
+ dependencies. You will need `libelf' to compile the kernel. If you
+ want to configure using the menu interface you will also need
+ `ncurses'.
+
+ ,----
+ | # 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
+ `----
+
+ 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 [E5ten]. You will need to obtain and apply
+ the patch in the kernel source directory.
+
+ ,----
+ | wget https://dl.carbslinux.org/distfiles/kernel-no-perl.patch
+ | patch -p1 < kernel-no-perl.patch
+ `----
+
+
+[E5ten] <https://github.com/E5ten>
+
+
+2.4.3 Building the kernel
+-------------------------
+
+ Next step is configuring and building the kernel. You can check
+ Gentoo's [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.
+
+ ,----
+ | make menuconfig
+ | make
+ | install -Dm755 $(make -s image_name) /boot/vmlinuz-linux
+ `----
+
+
+[kernel configuration guide]
+<https://wiki.gentoo.org/wiki/Kernel/Configuration>
+
+
+2.5 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.
+
+
+2.5.1 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).
+
+
+* 2.5.1.1 GRUB BIOS installation
+
+ ,----
+ | cpt b grub && cpt i grub
+ | grub-install --target=i386-pc /dev/sdX
+ | grub-mkconfig -o /boot/grub/grub.cfg
+ `----
+
+
+* 2.5.1.2 GRUB UEFI installation
+
+ ,----
+ | 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
+ `----
+
+
+2.5.2 Init scripts
+------------------
+
+ Only thing left to do is installing the init-scripts, and now you are
+ almost ready to boot your system!
+
+ ,----
+ | cpt b carbs-init && cpt i carbs-init
+ `----
+
+
+2.5.3 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:
+
+ ,----
+ | wget https://github.com/cemkeylan/genfstab/raw/master/genfstab
+ | chmod +x genfstab
+ | ./genfstab -U /mnt >> /mnt/etc/fstab
+ `----
+
+
+2.6 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.
+
+
+2.6.1 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.
+
+
+3 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
+ halting program named shalt. This provides a portable method that
+ doesn't rely on non-POSIX external programs.
+
+
+3.1 Configuring Init
+~~~~~~~~~~~~~~~~~~~~
+
+ There are three ways you can change the behaviour of the init
+ system. Those are:
+
+ - Kernel Command Line
+ - `/etc/init/rc.conf' file
+ - Init Hooks
+
+
+3.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
+ will be acted upon, but all of them will be set as variables on the
+ init script. For example an example command line, and how it is
+ interpreted.
+
+ ,----
+ | BOOT_IMAGE=/boot/vmlinuz root=/dev/sda2 rw loglevel=3 quiet
+ `----
+
+ This command line will be parsed to set the following variables:
+
+ ,----
+ | BOOT_IMAGE=/boot/vmlinuz
+ | root=/dev/sda2
+ | rw=1
+ | loglevel=3
+ | 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.
+
+
+3.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
+ the kernel command line always gets the priority for these variables
+ since they can be set just before boot.
+
+
+3.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,
+ modify interfaces, and lot more. Those hooks are added to the
+ `/etc/init' directory with the hook name as the suffix. For example, a
+ boot script will be placed as `/etc/init/my-hook.boot'. Currently,
+ there are 4 hooks that the user can use.
+
+ early-boot
+ Run after pseudo-filesystems are mounted.
+ boot
+ Run before the boot stage is completed.
+ pre.shutdown
+ Run first when shutting down.
+ umount
+ Run just before filesystems are unmounted.
+ post.shutdown
+ Run just before the system is halted.
+
+
+3.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'
+ - `runit'
+ - `shinit'
+
+ This example is for runit, but it will work with all init systems
+ packaged in the distribution repositories. See the
+ `cpt-alternatives(1)' manual page for more details.
+
+ ,----
+ | cpt a runit /usr/bin/init
+ | cpt a runit /usr/bin/poweroff
+ | cpt a runit /usr/bin/reboot
+ `----
+
+
+3.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
+ running init's utilities for the new utilities to work. These commands
+ are for the init system currently running on your system and not the
+ one you are switching to.
+
+ Program Command
+ --------------------------------
+ busybox `busybox reboot'
+ runit `runit-init 6'
+ shinit/sinit `kill -s INT 1'
+
+
+4 Contribution Guidelines
+=========================
+
+ Thanks for taking your time to contribute! To maintain stylistic
+ behaviour throughout the repositories, one must adhere to these
+ conventions. Exceptions and changes may occur with good reasoning.
+
+
+4.1 Conventions
+~~~~~~~~~~~~~~~
+
+ [0010]
+ Try to keep the file readable.
+ [0011]
+ Characters on a line shouldn't exceed 100 characters.
+ [0012]
+ Make sure you don't have code commented out during
+ commit. Uncomment them or remove them completely.
+ [0013]
+ Do not add comments following the code, add them to the
+ top of the code. It makes it harder to read, and lines
+ longer. Here is an example:
+
+ ,----
+ | # Good way of commenting.
+ | your code goes here
+ |
+ | your code goes here # Avoid this way of commenting.
+ `----
+
+
+4.1.1 Shell Conventions
+-----------------------
+
+ Shell is central to Carbs Linux projects. Most of the tools and
+ packages are written in POSIX sh.
+
+ [1010]
+ Use 4 spaces for indentation, don't use tabs.
+ [1020]
+ Make sure you don't use bash-specific code.
+ [1030]
+ Make sure you lint your code with `shellcheck' and if you are
+ new to POSIX sh, use `checkbashisms'.
+ [1040]
+ Don't spawn new processes if you don't absolutely need to,
+ especially during string manipulation.
+ [1041]
+ Never use a program for text manupilation that isn't
+ defined in the POSIX standard. This includes `gawk' and
+ `perl'.
+ [1042]
+ Instead of `$(basename $file)', use `${file##*}'.
+ [1043]
+ Instead of `$(dirname $file)', use `${file%/*}'.
+
+ ,----
+ | # This is the same thing as basename /path/to/test.asc .asc
+ |
+ | $ file=/path/to/test.asc file=${file##*/} file=${file%.asc}
+ | $ echo $file
+ | test
+ `----
+ [1050]
+ Instead of backticks, use `$(..)'.
+
+
+4.1.2 Repository Conventions
+----------------------------
+
+ Repository conventions are important in order to ensure every package
+ resemble themselves. Here are the things to keep in mind:
+
+ [2010]
+ Prefer tarballs over git packages unless there is a sensible
+ reason. Here are some:
+ - Every patch is a new release. (See [vim])
+ - There are no releases. (See [sbase])
+ - Following a development branch.
+ - There has been a long time since the latest release, but
+ upstream is far ahead.
+ [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.
+ [2030]
+ Avoid these packages:
+ dbus
+ Usually can be disabled by `--disable-dbus'.
+ gettext
+ Usually can be disabled by `--disable-nls'.
+ [2040]
+ - Always install a package to the `/usr' prefix.
+ - All binaries should go to `/usr/bin', not `/usr/sbin' or any
+ other directory.
+ - All libraries should go to `/usr/lib'.
+ [2050]
+ All build files on the repository should be a POSIX shell
+ script, and must start with `#!/bin/sh -e'.
+
+ The next section is about package templates that should be used in
+ order to ensure stylistic consistency. Note that the option
+ configurations shouldn't be taken literally, they are meant as
+ examples.
+
+
+[vim] <https://github.com/vim/vim>
+
+[sbase] <https://git.suckless.org/sbase>
+
+* 4.1.2.1 Make [2210]
+
+ ,----
+ | #!/bin/sh -e
+ |
+ | make
+ | make DESTDIR="$1" PREFIX=/usr install
+ `----
+
+
+* 4.1.2.2 Configure/Make [2211]
+
+ ,----
+ | #!/bin/sh -e
+ |
+ | ./configure \
+ | --prefix=/usr \
+ | --disable-option \
+ | --enable-option
+ |
+ | make
+ | make DESTDIR="$1" install
+ `----
+
+
+* 4.1.2.3 Autoconf/Automake [2212]
+
+ ,----
+ | #!/bin/sh -e
+ |
+ | autoreconf -fi
+ |
+ | ./configure \
+ | --prefix=/usr \
+ | --disable-option \
+ | --enable-option
+ |
+ | make
+ | make DESTDIR="$1" install
+ `----
+
+
+* 4.1.2.4 Meson [2220]
+
+ ,----
+ | #!/bin/sh -e
+ |
+ | export DESTDIR=$1
+ |
+ | meson \
+ | --prefix=/usr \
+ | -Doption=false \
+ | -Doption2=true \
+ | . output
+ |
+ | ninja -C output
+ | ninja -C output install
+ `----
+
+
+* 4.1.2.5 Cmake [2230]
+
+ ,----
+ | #!/bin/sh -e
+ |
+ | export DESTDIR=$1
+ |
+ | cmake -B build \
+ | -DCMAKE_INSTALL_PREFIX=/usr \
+ | -DCMAKE_BUILD_TYPE=Release \
+ | -DOPTION=ON
+ |
+ | cmake --build build
+ | cmake --install build
+ `----
+
+
+* 4.1.2.6 Go [2240]
+
+ ,----
+ | #!/bin/sh -e
+ |
+ | export GOPATH=$PWD/gopath
+ | trap "go clean -modcache" EXIT INT
+ | go mod vendor
+ |
+ | go build
+ | install -Dm755 program "$1/usr/bin/program"
+ `----
+
+
+* 4.1.2.7 Python [2241]
+
+ ,----
+ | #!/bin/sh -e
+ |
+ | python setup.py build
+ | python setup.py install --prefix=/usr --root="$1"
+ `----
+
+
+5 GNU Free Documentation License
+================================
+
+ Version 1.3, 3 November 2008
+
+ Copyright (c) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
+ <http://fsf.org/>
+
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+ 0. PREAMBLE
+
+ The purpose of this License is to make a manual, textbook, or other
+ functional and useful document free in the sense of freedom: to
+ assure everyone the effective freedom to copy and redistribute it,
+ with or without modifying it, either commercially or
+ noncommercially. Secondarily, this License preserves for the author
+ and publisher a way to get credit for their work, while not being
+ considered responsible for modifications made by others.
+
+ This License is a kind of "copyleft", which means that derivative
+ works of the document must themselves be free in the same sense.
+ It complements the GNU General Public License, which is a copyleft
+ license designed for free software.
+
+ We have designed this License in order to use it for manuals for
+ free software, because free software needs free documentation: a
+ free program should come with manuals providing the same freedoms
+ that the software does. But this License is not limited to
+ software manuals; it can be used for any textual work, regardless
+ of subject matter or whether it is published as a printed book. We
+ recommend this License principally for works whose purpose is
+ instruction or reference.
+
+ 1. APPLICABILITY AND DEFINITIONS
+
+ This License applies to any manual or other work, in any medium,
+ that contains a notice placed by the copyright holder saying it can
+ be distributed under the terms of this License. Such a notice
+ grants a world-wide, royalty-free license, unlimited in duration,
+ to use that work under the conditions stated herein. The
+ "Document", below, refers to any such manual or work. Any member
+ of the public is a licensee, and is addressed as "you". You accept
+ the license if you copy, modify or distribute the work in a way
+ requiring permission under copyright law.
+
+ A "Modified Version" of the Document means any work containing the
+ Document or a portion of it, either copied verbatim, or with
+ modifications and/or translated into another language.
+
+ A "Secondary Section" is a named appendix or a front-matter section
+ of the Document that deals exclusively with the relationship of the
+ publishers or authors of the Document to the Document's overall
+ subject (or to related matters) and contains nothing that could
+ fall directly within that overall subject. (Thus, if the Document
+ is in part a textbook of mathematics, a Secondary Section may not
+ explain any mathematics.) The relationship could be a matter of
+ historical connection with the subject or with related matters, or
+ of legal, commercial, philosophical, ethical or political position
+ regarding them.
+
+ The "Invariant Sections" are certain Secondary Sections whose
+ titles are designated, as being those of Invariant Sections, in the
+ notice that says that the Document is released under this License.
+ If a section does not fit the above definition of Secondary then it
+ is not allowed to be designated as Invariant. The Document may
+ contain zero Invariant Sections. If the Document does not identify
+ any Invariant Sections then there are none.
+
+ The "Cover Texts" are certain short passages of text that are
+ listed, as Front-Cover Texts or Back-Cover Texts, in the notice
+ that says that the Document is released under this License. A
+ Front-Cover Text may be at most 5 words, and a Back-Cover Text may
+ be at most 25 words.
+
+ A "Transparent" copy of the Document means a machine-readable copy,
+ represented in a format whose specification is available to the
+ general public, that is suitable for revising the document
+ straightforwardly with generic text editors or (for images composed
+ of pixels) generic paint programs or (for drawings) some widely
+ available drawing editor, and that is suitable for input to text
+ formatters or for automatic translation to a variety of formats
+ suitable for input to text formatters. A copy made in an otherwise
+ Transparent file format whose markup, or absence of markup, has
+ been arranged to thwart or discourage subsequent modification by
+ readers is not Transparent. An image format is not Transparent if
+ used for any substantial amount of text. A copy that is not
+ "Transparent" is called "Opaque".
+
+ Examples of suitable formats for Transparent copies include plain
+ ASCII without markup, Texinfo input format, LaTeX input format,
+ SGML or XML using a publicly available DTD, and standard-conforming
+ simple HTML, PostScript or PDF designed for human modification.
+ Examples of transparent image formats include PNG, XCF and JPG.
+ Opaque formats include proprietary formats that can be read and
+ edited only by proprietary word processors, SGML or XML for which
+ the DTD and/or processing tools are not generally available, and
+ the machine-generated HTML, PostScript or PDF produced by some word
+ processors for output purposes only.
+
+ The "Title Page" means, for a printed book, the title page itself,
+ plus such following pages as are needed to hold, legibly, the
+ material this License requires to appear in the title page. For
+ works in formats which do not have any title page as such, "Title
+ Page" means the text near the most prominent appearance of the
+ work's title, preceding the beginning of the body of the text.
+
+ The "publisher" means any person or entity that distributes copies
+ of the Document to the public.
+
+ A section "Entitled XYZ" means a named subunit of the Document
+ whose title either is precisely XYZ or contains XYZ in parentheses
+ following text that translates XYZ in another language. (Here XYZ
+ stands for a specific section name mentioned below, such as
+ "Acknowledgements", "Dedications", "Endorsements", or "History".)
+ To "Preserve the Title" of such a section when you modify the
+ Document means that it remains a section "Entitled XYZ" according
+ to this definition.
+
+ The Document may include Warranty Disclaimers next to the notice
+ which states that this License applies to the Document. These
+ Warranty Disclaimers are considered to be included by reference in
+ this License, but only as regards disclaiming warranties: any other
+ implication that these Warranty Disclaimers may have is void and
+ has no effect on the meaning of this License.
+
+ 2. VERBATIM COPYING
+
+ You may copy and distribute the Document in any medium, either
+ commercially or noncommercially, provided that this License, the
+ copyright notices, and the license notice saying this License
+ applies to the Document are reproduced in all copies, and that you
+ add no other conditions whatsoever to those of this License. You
+ may not use technical measures to obstruct or control the reading
+ or further copying of the copies you make or distribute. However,
+ you may accept compensation in exchange for copies. If you
+ distribute a large enough number of copies you must also follow the
+ conditions in section 3.
+
+ You may also lend copies, under the same conditions stated above,
+ and you may publicly display copies.
+
+ 3. COPYING IN QUANTITY
+
+ If you publish printed copies (or copies in media that commonly
+ have printed covers) of the Document, numbering more than 100, and
+ the Document's license notice requires Cover Texts, you must
+ enclose the copies in covers that carry, clearly and legibly, all
+ these Cover Texts: Front-Cover Texts on the front cover, and
+ Back-Cover Texts on the back cover. Both covers must also clearly
+ and legibly identify you as the publisher of these copies. The
+ front cover must present the full title with all words of the title
+ equally prominent and visible. You may add other material on the
+ covers in addition. Copying with changes limited to the covers, as
+ long as they preserve the title of the Document and satisfy these
+ conditions, can be treated as verbatim copying in other respects.
+
+ If the required texts for either cover are too voluminous to fit
+ legibly, you should put the first ones listed (as many as fit
+ reasonably) on the actual cover, and continue the rest onto
+ adjacent pages.
+
+ If you publish or distribute Opaque copies of the Document
+ numbering more than 100, you must either include a machine-readable
+ Transparent copy along with each Opaque copy, or state in or with
+ each Opaque copy a computer-network location from which the general
+ network-using public has access to download using public-standard
+ network protocols a complete Transparent copy of the Document, free
+ of added material. If you use the latter option, you must take
+ reasonably prudent steps, when you begin distribution of Opaque
+ copies in quantity, to ensure that this Transparent copy will
+ remain thus accessible at the stated location until at least one
+ year after the last time you distribute an Opaque copy (directly or
+ through your agents or retailers) of that edition to the public.
+
+ It is requested, but not required, that you contact the authors of
+ the Document well before redistributing any large number of copies,
+ to give them a chance to provide you with an updated version of the
+ Document.
+
+ 4. MODIFICATIONS
+
+ You may copy and distribute a Modified Version of the Document
+ under the conditions of sections 2 and 3 above, provided that you
+ release the Modified Version under precisely this License, with the
+ Modified Version filling the role of the Document, thus licensing
+ distribution and modification of the Modified Version to whoever
+ possesses a copy of it. In addition, you must do these things in
+ the Modified Version:
+
+ 1. Use in the Title Page (and on the covers, if any) a title
+ distinct from that of the Document, and from those of previous
+ versions (which should, if there were any, be listed in the
+ History section of the Document). You may use the same title as
+ a previous version if the original publisher of that version
+ gives permission.
+
+ 2. List on the Title Page, as authors, one or more persons or
+ entities responsible for authorship of the modifications in the
+ Modified Version, together with at least five of the principal
+ authors of the Document (all of its principal authors, if it has
+ fewer than five), unless they release you from this requirement.
+
+ 3. State on the Title page the name of the publisher of the
+ Modified Version, as the publisher.
+
+ 4. Preserve all the copyright notices of the Document.
+
+ 5. Add an appropriate copyright notice for your modifications
+ adjacent to the other copyright notices.
+
+ 6. Include, immediately after the copyright notices, a license
+ notice giving the public permission to use the Modified Version
+ under the terms of this License, in the form shown in the
+ Addendum below.
+
+ 7. Preserve in that license notice the full lists of Invariant
+ Sections and required Cover Texts given in the Document's
+ license notice.
+
+ 8. Include an unaltered copy of this License.
+
+ 9. Preserve the section Entitled "History", Preserve its Title, and
+ add to it an item stating at least the title, year, new authors,
+ and publisher of the Modified Version as given on the Title
+ Page. If there is no section Entitled "History" in the Document,
+ create one stating the title, year, authors, and publisher of
+ the Document as given on its Title Page, then add an item
+ describing the Modified Version as stated in the previous
+ sentence.
+
+ 10. Preserve the network location, if any, given in the Document
+ for public access to a Transparent copy of the Document, and
+ likewise the network locations given in the Document for
+ previous versions it was based on. These may be placed in the
+ "History" section. You may omit a network location for a work
+ that was published at least four years before the Document
+ itself, or if the original publisher of the version it refers
+ to gives permission.
+
+ 11. For any section Entitled "Acknowledgements" or "Dedications",
+ Preserve the Title of the section, and preserve in the section
+ all the substance and tone of each of the contributor
+ acknowledgements and/or dedications given therein.
+
+ 12. Preserve all the Invariant Sections of the Document, unaltered
+ in their text and in their titles. Section numbers or the
+ equivalent are not considered part of the section titles.
+
+ 13. Delete any section Entitled "Endorsements". Such a section may
+ not be included in the Modified Version.
+
+ 14. Do not retitle any existing section to be Entitled
+ "Endorsements" or to conflict in title with any Invariant
+ Section.
+
+ 15. Preserve any Warranty Disclaimers.
+
+ If the Modified Version includes new front-matter sections or
+ appendices that qualify as Secondary Sections and contain no
+ material copied from the Document, you may at your option designate
+ some or all of these sections as invariant. To do this, add their
+ titles to the list of Invariant Sections in the Modified Version's
+ license notice. These titles must be distinct from any other
+ section titles.
+
+ You may add a section Entitled "Endorsements", provided it contains
+ nothing but endorsements of your Modified Version by various
+ parties---for example, statements of peer review or that the text
+ has been approved by an organization as the authoritative
+ definition of a standard.
+
+ You may add a passage of up to five words as a Front-Cover Text,
+ and a passage of up to 25 words as a Back-Cover Text, to the end of
+ the list of Cover Texts in the Modified Version. Only one passage
+ of Front-Cover Text and one of Back-Cover Text may be added by (or
+ through arrangements made by) any one entity. If the Document
+ already includes a cover text for the same cover, previously added
+ by you or by arrangement made by the same entity you are acting on
+ behalf of, you may not add another; but you may replace the old
+ one, on explicit permission from the previous publisher that added
+ the old one.
+
+ The author(s) and publisher(s) of the Document do not by this
+ License give permission to use their names for publicity for or to
+ assert or imply endorsement of any Modified Version.
+
+ 5. COMBINING DOCUMENTS
+
+ You may combine the Document with other documents released under
+ this License, under the terms defined in section 4 above for
+ modified versions, provided that you include in the combination all
+ of the Invariant Sections of all of the original documents,
+ unmodified, and list them all as Invariant Sections of your
+ combined work in its license notice, and that you preserve all
+ their Warranty Disclaimers.
+
+ The combined work need only contain one copy of this License, and
+ multiple identical Invariant Sections may be replaced with a single
+ copy. If there are multiple Invariant Sections with the same name
+ but different contents, make the title of each such section unique
+ by adding at the end of it, in parentheses, the name of the
+ original author or publisher of that section if known, or else a
+ unique number. Make the same adjustment to the section titles in
+ the list of Invariant Sections in the license notice of the
+ combined work.
+
+ In the combination, you must combine any sections Entitled
+ "History" in the various original documents, forming one section
+ Entitled "History"; likewise combine any sections Entitled
+ "Acknowledgements", and any sections Entitled "Dedications". You
+ must delete all sections Entitled "Endorsements."
+
+ 6. COLLECTIONS OF DOCUMENTS
+
+ You may make a collection consisting of the Document and other
+ documents released under this License, and replace the individual
+ copies of this License in the various documents with a single copy
+ that is included in the collection, provided that you follow the
+ rules of this License for verbatim copying of each of the documents
+ in all other respects.
+
+ You may extract a single document from such a collection, and
+ distribute it individually under this License, provided you insert
+ a copy of this License into the extracted document, and follow this
+ License in all other respects regarding verbatim copying of that
+ document.
+
+ 7. AGGREGATION WITH INDEPENDENT WORKS
+
+ A compilation of the Document or its derivatives with other
+ separate and independent documents or works, in or on a volume of a
+ storage or distribution medium, is called an "aggregate" if the
+ copyright resulting from the compilation is not used to limit the
+ legal rights of the compilation's users beyond what the individual
+ works permit. When the Document is included in an aggregate, this
+ License does not apply to the other works in the aggregate which
+ are not themselves derivative works of the Document.
+
+ If the Cover Text requirement of section 3 is applicable to these
+ copies of the Document, then if the Document is less than one half
+ of the entire aggregate, the Document's Cover Texts may be placed
+ on covers that bracket the Document within the aggregate, or the
+ electronic equivalent of covers if the Document is in electronic
+ form. Otherwise they must appear on printed covers that bracket
+ the whole aggregate.
+
+ 8. TRANSLATION
+
+ Translation is considered a kind of modification, so you may
+ distribute translations of the Document under the terms of section
+ 4. Replacing Invariant Sections with translations requires special
+ permission from their copyright holders, but you may include
+ translations of some or all Invariant Sections in addition to the
+ original versions of these Invariant Sections. You may include a
+ translation of this License, and all the license notices in the
+ Document, and any Warranty Disclaimers, provided that you also
+ include the original English version of this License and the
+ original versions of those notices and disclaimers. In case of a
+ disagreement between the translation and the original version of
+ this License or a notice or disclaimer, the original version will
+ prevail.
+
+ If a section in the Document is Entitled "Acknowledgements",
+ "Dedications", or "History", the requirement (section 4) to
+ Preserve its Title (section 1) will typically require changing the
+ actual title.
+
+ 9. TERMINATION
+
+ You may not copy, modify, sublicense, or distribute the Document
+ except as expressly provided under this License. Any attempt
+ otherwise to copy, modify, sublicense, or distribute it is void,
+ and will automatically terminate your rights under this License.
+
+ However, if you cease all violation of this License, then your
+ license from a particular copyright holder is reinstated (a)
+ provisionally, unless and until the copyright holder explicitly and
+ finally terminates your license, and (b) permanently, if the
+ copyright holder fails to notify you of the violation by some
+ reasonable means prior to 60 days after the cessation.
+
+ Moreover, your license from a particular copyright holder is
+ reinstated permanently if the copyright holder notifies you of the
+ violation by some reasonable means, this is the first time you have
+ received notice of violation of this License (for any work) from
+ that copyright holder, and you cure the violation prior to 30 days
+ after your receipt of the notice.
+
+ Termination of your rights under this section does not terminate
+ the licenses of parties who have received copies or rights from you
+ under this License. If your rights have been terminated and not
+ permanently reinstated, receipt of a copy of some or all of the
+ same material does not give you any rights to use it.
+
+ 10. FUTURE REVISIONS OF THIS LICENSE
+
+ The Free Software Foundation may publish new, revised versions of
+ the GNU Free Documentation License from time to time. Such new
+ versions will be similar in spirit to the present version, but may
+ differ in detail to address new problems or concerns. See
+ <http://www.gnu.org/copyleft/>.
+
+ Each version of the License is given a distinguishing version
+ number. If the Document specifies that a particular numbered
+ version of this License "or any later version" applies to it, you
+ have the option of following the terms and conditions either of
+ that specified version or of any later version that has been
+ published (not as a draft) by the Free Software Foundation. If
+ the Document does not specify a version number of this License,
+ you may choose any version ever published (not as a draft) by the
+ Free Software Foundation. If the Document specifies that a proxy
+ can decide which future versions of this License can be used, that
+ proxy's public statement of acceptance of a version permanently
+ authorizes you to choose that version for the Document.
+
+ 11. RELICENSING
+
+ "Massive Multiauthor Collaboration Site" (or "MMC Site") means any
+ World Wide Web server that publishes copyrightable works and also
+ provides prominent facilities for anybody to edit those works. A
+ public wiki that anybody can edit is an example of such a server.
+ A "Massive Multiauthor Collaboration" (or "MMC") contained in the
+ site means any set of copyrightable works thus published on the
+ MMC site.
+
+ "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
+ license published by Creative Commons Corporation, a
+ not-for-profit corporation with a principal place of business in
+ San Francisco, California, as well as future copyleft versions of
+ that license published by that same organization.
+
+ "Incorporate" means to publish or republish a Document, in whole
+ or in part, as part of another Document.
+
+ An MMC is "eligible for relicensing" if it is licensed under this
+ License, and if all works that were first published under this
+ License somewhere other than this MMC, and subsequently
+ incorporated in whole or in part into the MMC, (1) had no cover
+ texts or invariant sections, and (2) were thus incorporated prior
+ to November 1, 2008.
+
+ The operator of an MMC Site may republish an MMC contained in the
+ site under CC-BY-SA on the same site at any time before August 1,
+ 2009, provided the MMC is eligible for relicensing.
+
+
+ADDENDUM: How to use this License for your documents
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ To use this License in a document you have written, include a copy of
+ the License in the document and put the following copyright and
+ license notices just after the title page:
+
+ ,----
+ | Copyright (C) YEAR YOUR NAME.
+ | Permission is granted to copy, distribute and/or modify this document
+ | under the terms of the GNU Free Documentation License, Version 1.3
+ | or any later version published by the Free Software Foundation;
+ | with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+ | Texts. A copy of the license is included in the section entitled ``GNU
+ | Free Documentation License''.
+ `----
+
+ If you have Invariant Sections, Front-Cover Texts and Back-Cover
+ Texts, replace the "with...Texts." line with this:
+
+ ,----
+ | with the Invariant Sections being LIST THEIR TITLES, with
+ | the Front-Cover Texts being LIST, and with the Back-Cover Texts
+ | being LIST.
+ `----
+
+ If you have Invariant Sections without Cover Texts, or some other
+ combination of the three, merge those two alternatives to suit the
+ situation.
+
+ If your document contains nontrivial examples of program code, we
+ recommend releasing these examples in parallel under your choice of
+ free software license, such as the GNU General Public License, to
+ permit their use in free software.
diff --git a/clean.do b/clean.do
new file mode 100644
index 0000000..d71b034
--- /dev/null
+++ b/clean.do
@@ -0,0 +1,7 @@
+. ./config.rc
+
+rm -f carbslinux.info carbslinux.html
+rm -rf carbslinux
+rm -f -- ./*.tar.*
+redo_clean
+PHONY
diff --git a/config.rc b/config.rc
new file mode 100644
index 0000000..769faef
--- /dev/null
+++ b/config.rc
@@ -0,0 +1,17 @@
+# -*- 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
+
+PHONY all dist htmldocs install clean
diff --git a/default.do b/default.do
new file mode 100644
index 0000000..231765f
--- /dev/null
+++ b/default.do
@@ -0,0 +1,69 @@
+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
+ rm -f "${HTMLDIR:?}/"*
+ makeinfo --html -o "${HTMLDIR}" "${TEXI}"
+ cp install.txt "${HTMLDIR}/install.txt"
+ cp install.html "${HTMLDIR}/install.html"
+ 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
+ mkdir -p "${DESTDIR}${INFODIR}" "${DESTDIR}${DOCDIR}"
+ cp carbslinux.info "${DESTDIR}${INFODIR}/carbslinux.info"
+ cp 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/install.html.do b/install.html.do
new file mode 100644
index 0000000..90e6c1c
--- /dev/null
+++ b/install.html.do
@@ -0,0 +1,21 @@
+exec >&2
+. ./config.rc
+redo-ifchange "$ORG" htmlize/htmlize.el flatui/flatui-theme.el
+
+cp "$ORG" "$3.org"
+trap 'rm -f $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")
+(org-html-export-to-html nil t)
+(revert-buffer nil t)
+)'
+
+mv "$3.html" "$3"
diff --git a/install.txt b/install.txt
new file mode 100644
index 0000000..f7a6881
--- /dev/null
+++ b/install.txt
@@ -0,0 +1,481 @@
+ ________________________________
+
+ CARBS LINUX INSTALLATION GUIDE
+
+ Cem Keylan
+ ________________________________
+
+
+Table of Contents
+_________________
+
+1. Preparing Environment
+.. 1. Download
+.. 2. Signature verification
+.. 3. Extracting the tarball
+.. 4. Obtain the chroot helper
+2. Chroot
+.. 1. Setting up repositories
+..... 1. Obtaining from git
+..... 2. Obtaining from rsync
+..... 3. Making the package manager use the repositories
+.. 2. Updating packages
+.. 3. Installing packages
+.. 4. Essential Software
+.. 5. Obtaining the documentation
+3. System Configuration
+.. 1. Configuring hostname
+.. 2. Hosts file
+4. Kernel
+.. 1. Obtaining the kernel sources
+.. 2. Kernel dependencies
+.. 3. Building the kernel
+5. Making your system bootable
+.. 1. Bootloader
+..... 1. GRUB BIOS installation
+..... 2. GRUB UEFI installation
+.. 2. Init scripts
+.. 3. Fstab
+6. Post-installation
+.. 1. KISS repositories
+
+
+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/docs/install.txt>.
+
+
+1 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.
+
+
+1.1 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.
+
+ ,----
+ | wget $URL/carbs-rootfs.tar.xz.sha256
+ | sha256sum -c carbs-rootfs.tar.xz.sha256
+ `----
+
+
+1.2 Signature verification
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ It is highly recommended to verify the signature of the tarball. You
+ will need GPG for this.
+
+ ,----
+ | wget $URL/carbs-rootfs.tar.xz.sig
+ | gpg --recv-keys FF484BDFEFCEF8FF
+ | gpg --verify carbs-rootfs.tar.xz.sig
+ `----
+
+
+1.3 Extracting the tarball
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ You will need to extract the tarball to your desired location. For
+ partitioning, you can follow [this guide]. This will assume that you
+ will be mounting your root partition to `/mnt'.
+
+ ,----
+ | mount /dev/sdx1 /mnt
+ | tar xf carbs-rootfs.tar.xz -C /mnt
+ `----
+
+
+[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!
+
+ ,----
+ | ./cpt-chroot /mnt
+ `----
+
+
+2.1 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:
+
+ ,----
+ | mkdir -p $HOME/repos
+ `----
+
+
+2.1.1 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.
+
+ - git://git.carbslinux.org/repository
+ - <https://github.com/carbslinux/repository>
+
+ ,----
+ | git clone git://git.carbslinux.org/repository $HOME/repos/carbs
+ `----
+
+
+2.1.2 Obtaining from rsync
+--------------------------
+
+ Carbs Linux rsync repositories live in rsync://carbslinux.org/repo. In
+ order to obtain it, run the following:
+
+ ,----
+ | rsync -avc rsync://carbslinux.org/repo $HOME/repos/carbs
+ `----
+
+
+2.1.3 Making the package manager use the repositories
+-----------------------------------------------------
+
+ In your shell's configuration file, or in your `~/.profile' file, add
+ the following lines:
+
+ ,----
+ | 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/community
+ | export CPT_PATH
+ `----
+
+
+2.2 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.
+
+ ,----
+ | cpt-update && cpt-update
+ `----
+
+
+2.3 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.
+
+ ,----
+ | cpt-build package
+ | cpt-install package
+ `----
+
+
+2.4 Essential Software
+~~~~~~~~~~~~~~~~~~~~~~
+
+ Here is a list of software that you might want to have on your system.
+
+ *BOOTLOADERS*
+
+ - efibootmgr
+ - grub
+
+ *FILESYSTEMS*
+
+ - e2fsprogs
+ - dosfstools
+ - ntfs-3g
+
+ *NETWORKING*
+
+ - dhcpcd
+ - wpa_supplicant
+
+ *TEXT EDITORS*
+
+ - nano
+ - vim
+ - neatvi
+ - emacs
+ - emacs-nox (terminal-only version of emacs)
+
+ *USER SHELLS*
+
+ - bash
+ - zsh
+ - oksh
+ - rc
+
+ *POSIX BASE UTILITIES*
+
+ - busybox
+ - sbase
+ - coreutils
+
+ *DOCUMENTATION*
+
+ - carbs-docs
+ - man-pages
+ - man-pages-posix
+
+
+2.5 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 to view the documentation.
+
+ ,----
+ | # 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
+ `----
+
+
+3 System Configuration
+======================
+
+ After you have finished installing some extra packages, you can
+ configure your system to your liking.
+
+
+3.1 Configuring hostname
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+ You might want to add a hostname, especially in a networked
+ environment. Your hostname will default to 'carbslinux' unless you set
+ this.
+
+ ,----
+ | echo your-hostname > /etc/hostname
+ `----
+
+
+3.2 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.
+
+ ,----
+ | 127.0.0.1 localhost.localdomain localhost
+ | ::1 localhost.localdomain localhost ip6-localhost
+ `----
+
+
+4 Kernel
+========
+
+ Kernel isn't managed under the main repositories, even though you
+ could package one for your personal use. Here is an [example kernel
+ package], which you will need to reconfigure for your specific setup
+ if you want to make use of it.
+
+
+[example kernel package]
+<https://github.com/cemkeylan/kiss-repository/tree/master/personal/linux>
+
+4.1 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.
+
+ ,----
+ | # 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
+ |
+ | # Change directory into the kernel sources
+ | cd linux-5.9.1
+ `----
+
+
+4.2 Kernel dependencies
+~~~~~~~~~~~~~~~~~~~~~~~
+
+ In order to compile the kernel you will need to install some
+ dependencies. You will need `libelf' to compile the kernel. If you
+ want to configure using the menu interface you will also need
+ `ncurses'.
+
+ ,----
+ | # 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
+ `----
+
+ 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 [E5ten]. You will need to obtain and apply
+ the patch in the kernel source directory.
+
+ ,----
+ | wget https://dl.carbslinux.org/distfiles/kernel-no-perl.patch
+ | patch -p1 < kernel-no-perl.patch
+ `----
+
+
+[E5ten] <https://github.com/E5ten>
+
+
+4.3 Building the kernel
+~~~~~~~~~~~~~~~~~~~~~~~
+
+ Next step is configuring and building the kernel. You can check
+ Gentoo's [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.
+
+ ,----
+ | make menuconfig
+ | make
+ | install -Dm755 $(make -s image_name) /boot/vmlinuz-linux
+ `----
+
+
+[kernel configuration guide]
+<https://wiki.gentoo.org/wiki/Kernel/Configuration>
+
+
+5 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.
+
+
+5.1 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).
+
+
+5.1.1 GRUB BIOS installation
+----------------------------
+
+ ,----
+ | cpt b grub && cpt i grub
+ | grub-install --target=i386-pc /dev/sdX
+ | grub-mkconfig -o /boot/grub/grub.cfg
+ `----
+
+
+5.1.2 GRUB UEFI installation
+----------------------------
+
+ ,----
+ | 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
+ `----
+
+
+5.2 Init scripts
+~~~~~~~~~~~~~~~~
+
+ Only thing left to do is installing the init-scripts, and now you are
+ almost ready to boot your system!
+
+ ,----
+ | cpt b carbs-init && cpt i carbs-init
+ `----
+
+
+5.3 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:
+
+ ,----
+ | wget https://github.com/cemkeylan/genfstab/raw/master/genfstab
+ | chmod +x genfstab
+ | ./genfstab -U /mnt >> /mnt/etc/fstab
+ `----
+
+
+6 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.
+
+
+6.1 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.
diff --git a/install.txt.do b/install.txt.do
new file mode 100644
index 0000000..1ce0be9
--- /dev/null
+++ b/install.txt.do
@@ -0,0 +1,12 @@
+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")
+ (org-ascii-export-to-ascii nil t))'
+
+mv "$3.txt" "$3"
diff --git a/lib.rc b/lib.rc
new file mode 100644
index 0000000..4b03274
--- /dev/null
+++ b/lib.rc
@@ -0,0 +1,84 @@
+# 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
+}