diff options
| -rw-r--r-- | carbslinux.texi | 1535 |
1 files changed, 1535 insertions, 0 deletions
diff --git a/carbslinux.texi b/carbslinux.texi new file mode 100644 index 0000000..d99c49d --- /dev/null +++ b/carbslinux.texi @@ -0,0 +1,1535 @@ +\input texinfo @c -*- texinfo -*- +@c %**start of header +@setfilename carbslinux.info +@settitle Carbs Linux User Manual +@documentencoding UTF-8 +@documentlanguage en +@c %**end of header + +@copying +Copyright @copyright{} 2020 Cem Keylan + +@quotation +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." + +@end quotation +@end copying + +@dircategory System Administration +@direntry +* Carbs Linux: (carbslinux). Carbs Linux User Manual. +@end direntry + +@finalout +@titlepage +@title Carbs Linux User Manual +@author Cem Keylan +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top Carbs Linux User Manual + +This is the full documentation of @uref{https://carbslinux.org, Carbs Linux}, from the details of the +distribution, installation, to the package manager. It is not yet complete. + +@ifplaintext +You can build and install the @command{info} package in order to view this +documentation with the info reader. It is divided into sections and easier to +read. +@end ifplaintext + +@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. +@end ifhtml +@end ifnottex + +@menu +* Installation:: Installing Carbs Linux +* Init System:: Configure the init system +* Contribution Guidelines:: Contribute to Carbs Linux +* GNU Free Documentation License:: Your rights + +@detailmenu +--- The Detailed Node Listing --- + +Installation + +* Preparing Environment:: Getting ready to chroot +* Chroot:: Going inside your new system +* System Configuration:: Customizing your system for personal use +* Kernel:: Compiling your own kernel +* Making your system bootable:: Installing bootloader and boot scripts +* Post-installation:: Post-installation tasks + +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 + +* Setting up repositories:: Basic setup for obtaining repositories +* Updating packages:: Update your system +* Installing packages:: Install new software on your system +* Essential Software:: Software you might want to include on your system +* Obtaining the documentation:: Install documentation for offline use (optional) + +System Configuration + +* Configuring hostname:: Setting up system hostname (recommended) +* Hosts file:: Setting up hosts file for networking (optional) + +Kernel + +* Obtaining the kernel sources:: Downloading the Linux source code +* Kernel dependencies:: Requirements for building the kernel +* Building the kernel:: Configure and compile the kernel + +Making your system bootable + +* Bootloader:: Install a bootloader for your system +* Init scripts:: Install init scripts for your system +* Fstab:: Generating fstab + +Post-installation + +* KISS repositories:: Acquire kiss repositories + +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 + +* Rebooting after changing init:: Ways to reboot after replacing the init system + +Contribution Guidelines + +* Conventions:: Conventions of the distribution + +Conventions + +* Shell Conventions:: Conventions for shell scripts +* Repository Conventions:: Conventions for repository build scripts + +@end detailmenu +@end menu + +@node Installation +@chapter 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 +@uref{https://carbslinux.org/docs/install.txt}. + +@menu +* Preparing Environment:: Getting ready to chroot +* Chroot:: Going inside your new system +* System Configuration:: Customizing your system for personal use +* Kernel:: Compiling your own kernel +* Making your system bootable:: Installing bootloader and boot scripts +* Post-installation:: Post-installation tasks +@end menu + +@node Preparing Environment +@section 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: + +@itemize +@item +tar +@item +wget +@item +xz +@item +some form of base utilities (coreutils, sbase, busybox, etc.) +@end itemize + +Rest of these instructions will assume that you have set all of these up, and +will continue on that point. + +@menu +* 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 +@subsection 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 @samp{x86_64} +with @samp{i686}. We are setting this in a URL variable so that we don't have to +write it every time. + +@example +wget $URL/carbs-rootfs.tar.xz.sha256 +sha256sum -c carbs-rootfs.tar.xz.sha256 +@end example + +@node Signature verification +@subsection Signature verification + +It is highly recommended to verify the signature of the tarball. You will need +GPG for this. + +@example +wget $URL/carbs-rootfs.tar.xz.sig +gpg --recv-keys FF484BDFEFCEF8FF +gpg --verify carbs-rootfs.tar.xz.sig +@end example + +@node Extracting the tarball +@subsection Extracting the tarball + +You will need to extract the tarball to your desired location. For partitioning, +you can follow @uref{https://wiki.archlinux.org/index.php/Partitioning, this guide}. This will assume that you will be mounting your root +partition to @samp{/mnt}. + +@example +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! + +@example +./cpt-chroot /mnt +@end example + +@menu +* Setting up repositories:: Basic setup for obtaining repositories +* Updating packages:: Update your system +* Installing packages:: Install new software on your system +* Essential Software:: Software you might want to include on your system +* Obtaining the documentation:: Install documentation for offline use (optional) +@end menu + +@node Setting up repositories +@subsection Setting up repositories + +Newest tarballs do not come with repositories, so you will need to manually +obtain them, and set your @samp{CPT_PATH} environment variable. Carbs Linux +repositories can either be obtained by @samp{git} or @samp{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 @samp{git} itself. + +The following guide will assume that you put the repositories into @samp{~/repos/} +directory, but you can put the repositories into any directory you want. So go +ahead and create that directory: + +@example +mkdir -p $HOME/repos +@end example + +@enumerate +@item +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. + +@itemize +@item +git://git.carbslinux.org/repository +@item +@uref{https://github.com/carbslinux/repository} +@end itemize + +@example +git clone git://git.carbslinux.org/repository $HOME/repos/carbs +@end example + +@item +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 +@end example + +@item +Making the package manager use the repositories + + +In your shell's configuration file, or in your @samp{~/.profile} file, add the +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/community +export CPT_PATH +@end example +@end enumerate + +@node Updating packages +@subsection 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. + +@example +cpt-update && cpt-update +@end example + +@node Installing packages +@subsection 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. + +@example +cpt-build package +cpt-install package +@end example + +@node Essential Software +@subsection Essential Software + +Here is a list of software that you might want to have on your system. + +@strong{BOOTLOADERS} + +@itemize +@item +efibootmgr +@item +grub +@end itemize + +@strong{FILESYSTEMS} + +@itemize +@item +e2fsprogs +@item +dosfstools +@item +ntfs-3g +@end itemize + +@strong{NETWORKING} + +@itemize +@item +dhcpcd +@item +wpa@math{_supplicant} +@end itemize + +@strong{TEXT EDITORS} + +@itemize +@item +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} + +@itemize +@item +carbs-docs +@item +man-pages +@item +man-pages-posix +@end itemize + +@node Obtaining the documentation +@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 +to view the documentation. + +@example +# 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 example + +@node System Configuration +@section System Configuration + +After you have finished installing some extra packages, you can configure your +system to your liking. + +@menu +* Configuring hostname:: Setting up system hostname (recommended) +* Hosts file:: Setting up hosts file for networking (optional) +@end menu + +@node Configuring hostname +@subsection Configuring hostname + +You might want to add a hostname, especially in a networked environment. Your +hostname will default to 'carbslinux' unless you set this. + +@example +echo your-hostname > /etc/hostname +@end example + +@node Hosts file +@subsection 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. + +@example +127.0.0.1 localhost.localdomain localhost +::1 localhost.localdomain localhost ip6-localhost +@end example + +@node Kernel +@section Kernel + +Kernel isn't managed under the main repositories, even though you could package +one for your personal use. Here is an @uref{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. + +@menu +* Obtaining the kernel sources:: Downloading the Linux source code +* Kernel dependencies:: Requirements for building the kernel +* Building the kernel:: Configure and compile the kernel +@end menu + +@node Obtaining the kernel sources +@subsection Obtaining the kernel sources + +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. + +@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 + +# Change directory into the kernel sources +cd linux-5.9.1 +@end example + +@node Kernel dependencies +@subsection Kernel dependencies + +In order to compile the kernel you will need to install some dependencies. You +will need @samp{libelf} to compile the kernel. If you want to configure using the +menu interface you will also need @samp{ncurses}. + +@example +# 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 example + +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 @uref{https://github.com/E5ten, E5ten}. You will need to obtain and apply the patch in the kernel +source directory. + +@example +wget https://dl.carbslinux.org/distfiles/kernel-no-perl.patch +patch -p1 < kernel-no-perl.patch +@end example + +@node Building the kernel +@subsection Building the kernel + +Next step is configuring and building the kernel. You can check Gentoo's +@uref{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. + +@example +make menuconfig +make +install -Dm755 $(make -s image_name) /boot/vmlinuz-linux +@end example + +@node Making your system bootable +@section 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. + +@menu +* Bootloader:: Install a bootloader for your system +* Init scripts:: Install init scripts for your system +* Fstab:: Generating fstab +@end menu + +@node Bootloader +@subsection 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). + +@enumerate +@item +GRUB BIOS installation + + +@example +cpt b grub && cpt i grub +grub-install --target=i386-pc /dev/sdX +grub-mkconfig -o /boot/grub/grub.cfg +@end example + +@item +GRUB UEFI installation + + +@example +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 example +@end enumerate + +@node Init scripts +@subsection Init scripts + +Only thing left to do is installing the init-scripts, and now you are almost +ready to boot your system! + +@example +cpt b carbs-init && cpt i carbs-init +@end example + +@node Fstab +@subsection 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: + +@example +wget https://github.com/cemkeylan/genfstab/raw/master/genfstab +chmod +x genfstab +./genfstab -U /mnt >> /mnt/etc/fstab +@end example + +@node Post-installation +@section 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. + +@menu +* KISS repositories:: Acquire kiss repositories +@end menu + +@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. + +@node Init System +@chapter 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 +shalt. This provides a portable method that doesn't rely on non-POSIX external +programs. + +@menu +* Configuring Init:: Ways to configure the init system +* Changing Init Program:: Replace the default busybox init with something new +@end menu + +@node Configuring Init +@section Configuring Init + +There are three ways you can change the behaviour of the init system. Those are: + +@itemize +@item +Kernel Command Line +@item +@samp{/etc/init/rc.conf} file +@item +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 + +@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, +but all of them will be set as variables on the init script. For example an +example command line, and how it is interpreted. + +@example +BOOT_IMAGE=/boot/vmlinuz root=/dev/sda2 rw loglevel=3 quiet +@end example + +This command line will be parsed to set the following variables: + +@example +BOOT_IMAGE=/boot/vmlinuz +root=/dev/sda2 +rw=1 +loglevel=3 +quiet=1 +@end example + +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 + +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 + +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 @samp{/etc/init} directory with the +hook name as the suffix. For example, a boot script will be placed as +@samp{/etc/init/my-hook.boot}. Currently, there are 4 hooks that the user can use. + +@table @asis +@item early-boot +Run after pseudo-filesystems are mounted. +@item boot +Run before the boot stage is completed. +@item pre.shutdown +Run first when shutting down. +@item umount +Run just before filesystems are unmounted. +@item post.shutdown +Run just before the system is halted. +@end table + +@node Changing Init Program +@section 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: + +@itemize +@item +@samp{sinit} +@item +@samp{busybox} +@item +@samp{runit} +@item +@samp{shinit} +@end itemize + +This example is for runit, but it will work with all init systems packaged in the +distribution repositories. See the @samp{cpt-alternatives(1)} manual page for more +details. + +@example +cpt a runit /usr/bin/init +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 + +@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 +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. + +@multitable {aaaaaaaaaaaa} {aaaaaaaaaaaaaaaa} +@headitem Program +@tab Command +@item busybox +@tab @samp{busybox reboot} +@item runit +@tab @samp{runit-init 6} +@item shinit/sinit +@tab @samp{kill -s INT 1} +@end multitable + +@node Contribution Guidelines +@chapter 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. + +@menu +* Conventions:: Conventions of the distribution +@end menu + +@node Conventions +@section Conventions + +@macro contid{id} +[@anchor{\id\}\id\] +@end macro + +@macro sectid{id, sect} +@strong{@contid{\id\} \sect\} +@end macro + +@table @asis +@item [@anchor{0010}0010] +Try to keep the file readable. +@table @asis +@item [@anchor{0011}0011] +Characters on a line shouldn't exceed 100 characters. +@item [@anchor{0012}0012] +Make sure you don't have code commented out during +commit. Uncomment them or remove them completely. +@item [@anchor{0013}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: +@end table + +@example +# Good way of commenting. +your code goes here + +your code goes here # Avoid this way of commenting. +@end example +@end table + +@menu +* Shell Conventions:: Conventions for shell scripts +* Repository Conventions:: Conventions for repository build scripts +@end menu + +@node Shell Conventions +@subsection Shell Conventions + +Shell is central to Carbs Linux projects. Most of the tools and packages are +written in POSIX sh. + +@table @asis +@item [@anchor{1010}1010] +Use 4 spaces for indentation, don't use tabs. +@item [@anchor{1020}1020] +Make sure you don't use bash-specific code. +@item [@anchor{1030}1030] +Make sure you lint your code with @samp{shellcheck} and if +you are new to POSIX sh, use @samp{checkbashisms}. +@item [@anchor{1040}1040] +Don't spawn new processes if you don't absolutely need +to, especially during string manipulation. +@table @asis +@item [@anchor{1041}1041] +Never use a program for text manupilation that isn't +defined in the POSIX standard. This includes @samp{gawk} and @samp{perl}. +@item [@anchor{1042}1042] +Instead of @code{$(basename $file)}, use @code{$@{file##*@}}. +@item [@anchor{1043}1043] +Instead of @code{$(dirname $file)}, use @code{$@{file%/*@}}. +@end table + +@example +# 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 +@end example +@item [@anchor{1050}1050] +Instead of backticks, use @code{$(..)}. +@end table + +@node Repository Conventions +@subsection Repository Conventions + +Repository conventions are important in order to ensure every package resemble +themselves. Here are the things to keep in mind: + +@table @asis +@item [@anchor{2010}2010] +Prefer tarballs over git packages unless there is a +sensible reason. Here are some: +@itemize +@item +Every patch is a new release. (See @uref{https://github.com/vim/vim, vim}) +@item +There are no releases. (See @uref{https://git.suckless.org/sbase, sbase}) +@item +Following a development branch. +@item +There has been a long time since the latest release, but upstream is far +ahead. +@end itemize +@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. +@item [@anchor{2030}2030] +Avoid these packages: +@table @asis +@item dbus +Usually can be disabled by @code{--disable-dbus}. +@item gettext +Usually can be disabled by @code{--disable-nls}. +@end table +@item [@anchor{2040}2040] +@itemize +@item +Always install a package to the @samp{/usr} prefix. +@item +All binaries should go to @samp{/usr/bin}, not @samp{/usr/sbin} or any other directory. +@item +All libraries should go to @samp{/usr/lib}. +@end itemize +@item [@anchor{2050}2050] +All build files on the repository should be a POSIX +shell script, and must start with @code{#!/bin/sh -e}. +@end table + +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. + +@enumerate +@item +Make [@anchor{2210}2210] + + +@example +#!/bin/sh -e + +make +make DESTDIR="$1" PREFIX=/usr install +@end example + +@item +Configure/Make [@anchor{2211}2211] + + +@example +#!/bin/sh -e + +./configure \ + --prefix=/usr \ + --disable-option \ + --enable-option + +make +make DESTDIR="$1" install +@end example + +@item +Autoconf/Automake [@anchor{2212}2212] + + +@xref{2020} + +@example +#!/bin/sh -e + +autoreconf -fi + +./configure \ + --prefix=/usr \ + --disable-option \ + --enable-option + +make +make DESTDIR="$1" install +@end example + +@item +Meson [@anchor{2220}2220] + + +@example +#!/bin/sh -e + +export DESTDIR=$1 + +meson \ + --prefix=/usr \ + -Doption=false \ + -Doption2=true \ + . output + +ninja -C output +ninja -C output install +@end example + +@item +Cmake [@anchor{2230}2230] + + +@example +#!/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 +@end example + +@item +Go [@anchor{2240}2240] + + +@example +#!/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" +@end example + +@item +Python [@anchor{2241}2241] + + +@example +#!/bin/sh -e + +python setup.py build +python setup.py install --prefix=/usr --root="$1" +@end example +@end enumerate + +@node GNU Free Documentation License +@appendix GNU Free Documentation License + +@center Version 1.3, 3 November 2008 + +@display +Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. +@uref{http://fsf.org/} + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@enumerate 0 +@item +PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +functional and useful document @dfn{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. + +@item +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. + +@item +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. + +@item +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. + +@item +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: + +@enumerate A +@item +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. + +@item +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. + +@item +State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +@item +Preserve all the copyright notices of the Document. + +@item +Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +@item +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. + +@item +Preserve in that license notice the full lists of Invariant +Sections and required Cover Texts given in the Document's +license notice. + +@item +Include an unaltered copy of this License. + +@item +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. + +@item +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. + +@item +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. + +@item +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. + +@item +Delete any section Entitled "Endorsements". Such a section may +not be included in the Modified Version. + +@item +Do not retitle any existing section to be Entitled +"Endorsements" or to conflict in title with any Invariant +Section. + +@item +Preserve any Warranty Disclaimers. +@end enumerate + +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. + +@item +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." + +@item +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. + +@item +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. + +@item +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. + +@item +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. + +@item +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 +@uref{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. + +@item +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. +@end enumerate + +@page + +@anchor{ADDENDUM How to use this License for your documents} +@appendixsec 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: + +@example +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''. +@end example + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the "with@dots{}Texts."@tie{}line with this: + +@example +with the Invariant Sections being LIST THEIR TITLES, with +the Front-Cover Texts being LIST, and with the Back-Cover Texts +being LIST. +@end example + +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. + +@bye
\ No newline at end of file |