diff options
| -rw-r--r-- | contribution.texi | 53 | ||||
| -rw-r--r-- | cpt.texi | 91 | ||||
| -rw-r--r-- | init.texi | 26 | ||||
| -rw-r--r-- | install.texi | 104 | ||||
| -rw-r--r-- | top.texi | 28 |
5 files changed, 292 insertions, 10 deletions
diff --git a/contribution.texi b/contribution.texi index e7e776c..ad685af 100644 --- a/contribution.texi +++ b/contribution.texi @@ -1,3 +1,9 @@ +@c This document is part of Carbs Linux Documentation. +@c See the top.texi file for LICENSE information. + +@c ----------------------------------------------------------------------------- + +@c Macro Definitions @macro contid{id} [@anchor{\id\}\id\] @end macro @@ -6,6 +12,9 @@ @strong{@contid{\id\} \sect\} @end macro + +@c ----------------------------------------------------------------------------- + @node Contribution Guidelines @chapter Contribution Guidelines @@ -18,9 +27,21 @@ and changes may occur with good reasoning. * Sending Git mails:: @end menu + +@c ----------------------------------------------------------------------------- + @node Conventions @section Conventions +@menu +* General Conventions:: +* Shell Conventions:: +* Repository Conventions:: +@end menu + + +@c ----------------------------------------------------------------------------- + @node General Conventions @subsection General Conventions -- 00 @@ -45,6 +66,9 @@ your code goes here # Avoid this way of commenting. @end table @end table + +@c ----------------------------------------------------------------------------- + @node Shell Conventions @subsection Shell Conventions -- 10 @@ -82,6 +106,9 @@ test Instead of backticks, use @verb{|$(..)|}. @end table + +@c ----------------------------------------------------------------------------- + @node Repository Conventions @subsection Repository Conventions -- 20 @@ -136,6 +163,9 @@ 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. + +@c ----------------------------------------------------------------------------- + @sectid{2210, Make} @example @@ -145,6 +175,9 @@ make make DESTDIR="$1" PREFIX=/usr install @end example + +@c ----------------------------------------------------------------------------- + @sectid{2211, Configure/Make} @example @@ -160,6 +193,8 @@ make DESTDIR="$1" install @end example +@c ----------------------------------------------------------------------------- + @sectid{2212, Autoconf/Automake} @xref{2020} @@ -178,6 +213,9 @@ make make DESTDIR="$1" install @end example + +@c ----------------------------------------------------------------------------- + @sectid{2220, Meson} @example @@ -195,6 +233,9 @@ ninja -C output ninja -C output install @end example + +@c ----------------------------------------------------------------------------- + @sectid{2230, Cmake} @example @@ -211,6 +252,9 @@ cmake --build build cmake --install build @end example + +@c ----------------------------------------------------------------------------- + @sectid{2240, Go} @example @@ -224,6 +268,9 @@ go build install -Dm755 program "$1/usr/bin/program" @end example + +@c ----------------------------------------------------------------------------- + @sectid{2241, Python} @example @@ -233,6 +280,9 @@ python setup.py build python setup.py install --prefix=/usr --root="$1" @end example + +@c ----------------------------------------------------------------------------- + @node Sending Git mails @section Sending Git mails @@ -277,3 +327,6 @@ $ git format-patch --to=~carbslinux/dev+subscribe@@lists.sr.ht <region> Edit those files as necessary and send them. $ for file in *.patch; do msmtp -t -a my-mail < $patch; done @end example + + +@c ----------------------------------------------------------------------------- @@ -1,3 +1,7 @@ +@c This document is part of Carbs Linux Documentation. +@c See the top.texi file for LICENSE information. + +@c ----------------------------------------------------------------------------- @c Macros @macro optbehsingle{opt} @@ -8,15 +12,18 @@ This behaviour can also be achieved by adding @option{\opt\} or @option{\opt2\} as an argument @end macro + +@c ----------------------------------------------------------------------------- + @c TODO add extending the package manager @node Package Manager @chapter Package Manager Carbs Linux uses its own package managing toolchain named @code{cpt}. It is a -fork of the @url{https://github.com/kisslinux/kiss, kiss} package manager. Unlike -@command{kiss}, however, its main goal is being easily extendable. Instead of being -a single file package manager, it revolves around the shell library @command{cpt-lib}, -and many tools that wrap around it. +fork of the @url{https://github.com/kisslinux/kiss, kiss} package manager. +Unlike @command{kiss}, however, its main goal is being easily extendable. +Instead of being a single file package manager, it revolves around the shell +library @command{cpt-lib}, and many tools that wrap around it. @menu * Usage:: Using Carbs Packaging Tools @@ -26,6 +33,9 @@ and many tools that wrap around it. * Rsync Repositories:: Information on using or creating rsync repositories @end menu + +@c ----------------------------------------------------------------------------- + @node Usage @section Usage @command{cpt} is formed of many tools combined in a single environment, similar @@ -81,6 +91,9 @@ scripts on my system: * @command{cpt-build}:: @end menu + +@c ----------------------------------------------------------------------------- + @node @command{cpt-alternatives} @subsection @command{cpt-alternatives} @@ -89,6 +102,9 @@ You can list and swap to alternatives using @command{cpt-alternatives}, or alternatives. It can read from standard input if @option{-} is given as an argument. + +@c ----------------------------------------------------------------------------- + @subsubsection Examples List alternatives @@ -112,12 +128,18 @@ Swap in bulk (all of sbase). $ cpt a | grep ^sbase | cpt a - @end example + +@c ----------------------------------------------------------------------------- + @node @command{cpt-build} @subsection @command{cpt-build} cpt-build will build given packages and their dependencies. If multiple packages are specified, it will ask to install the packages as well. + +@c ----------------------------------------------------------------------------- + @subsubsection Options @command{cpt-build} will accept the following options: @@ -128,6 +150,9 @@ are specified, it will ask to install the packages as well. @option{} @end itemize + +@c ----------------------------------------------------------------------------- + @node Environment Variables @section Environment Variables @@ -140,16 +165,21 @@ alter the behaviour of @command{cpt}: @item CPT_PATH Set the locations of your repositories. This is set similar to the @env{PATH} variable. + @item XDG_CACHE_HOME Unless this is set, the @file{~/.cache} directory will be used instead. + @item CPT_CACHE The cache directory for @command{cpt}. Default: @file{$XDG_CACHE_HOME/cpt} + @item CPT_CHOICE If this is set to 0, a package installation will be aborted on conflicts. Default: 1 + @item CPT_COMPRESS Program used to compress package tarballs. The values should be the default suffixes for the program. Available values are: + @itemize @item @command{gz} @@ -161,12 +191,15 @@ suffixes for the program. Available values are: @command{xz} @end itemize Default: @command{gz} + @item CPT_DEBUG If this is set to 1, temporary build directories will not be removed after the given operation. Default: unset + @item CPT_FETCH If this is set to 0, @command{cpt-update} will not fetch the repositories. @optbeh{-n, --no-fetch}. Default: 0 + @item CPT_FORCE If this is set to 1, some of the @command{cpt} tools will continue regardless of errors or skip certain checks. Here are some examples: @@ -188,9 +221,11 @@ Default: 0 @item CPT_HOOK Location for the hook file @xref{Hooks}. Default: unset + @item CPT_KEEPLOG Normally, logs are deleted if the package is built successfully. If set to 1, logs will be kept even when the packages are built as intended. Default: 0 + @item CPT_PID If this variable is set, the temporary files will be created with this variable as the suffix, instead of the PID of the @command{cpt} process. The advantage @@ -198,27 +233,37 @@ is that you can know exactly where the build directory is located, while the disadvantage is that there will be issues with multiple operations at the same time. So the best way to use this variable is during one-time @command{cpt} calls. + @example CPT_PID=mesa cpt b mesa @end example + By running the above, you will know that the created build directories will end with the @verb{|*-mesa|} suffix. + @item CPT_PROMPT If set to 0, the package manager will not prompt you for anything and will continue with the default action. @optbeh{-y, --no-prompt} to some utilities. Default: 1 + @item CPT_ROOT If this variable is set, @command{cpt} will assume this as the system root, and will install/remove/update/list packages assuming this is the system root. @optbehsingle{--root} to some utilities. + @item CPT_TEST If set to 1, @command{cpt-build} will run tests where a package has the @file{test} build file. @optbeh{-t, --test} to @command{cpt-build}. Default: 0 + @item CPT_TMPDIR The directory to create the build files. This can be changed (for example to /tmp) for building on RAM, saving SSD space, etc. Default: @env{$CPT_CACHE} + @end table + +@c ----------------------------------------------------------------------------- + @node Hooks @section Hooks @@ -272,6 +317,9 @@ The destination of the operation. Can be null. * Editing the @file{build} file during pre-build:: @end menu + +@c ----------------------------------------------------------------------------- + @node Editing the @file{build} file during pre-build @subsection Editing the @file{build} file during pre-build @@ -306,6 +354,9 @@ ln -s bash "\$1/usr/bin/sh" EOF @end example + +@c ----------------------------------------------------------------------------- + @node Packaging System @section Packaging System @@ -334,6 +385,9 @@ package maintainer. Everything in the package directory will also be added to th package database that is located on '/var/db/cpt/installed'. These can be patches, configuration files, etc. + +@c ----------------------------------------------------------------------------- + @subsection @file{build} Typically @file{build} files are shell scripts that run commands to prepare the source @@ -359,6 +413,9 @@ Package version System architecture @end enumerate + +@c ----------------------------------------------------------------------------- + @subsection @file{sources} @file{sources} file is a list of files and sources that will be put to the build @@ -400,6 +457,8 @@ Other files are assumed to be residing in the package directory. They should be added with their paths relative to the package directory. +@c ----------------------------------------------------------------------------- + @subsection @file{checksums} checksums file is generated by the @file{cpt c pkg command}. It is generated @@ -407,6 +466,9 @@ according to the order of the sources file. That's why you shouldn't be editing it manually. The checksums file is created with the digests of the files using the sha256 algorithm. + +@c ----------------------------------------------------------------------------- + @subsection @file{version} The version file includes the version of the software and the release number of @@ -429,6 +491,9 @@ change in the build scripts that affect the output of the package When a version bump occurs, the release should be reset to 1. + +@c ----------------------------------------------------------------------------- + @subsection @file{depends} This is a list of dependencies that must be installed before a package build. You @@ -445,17 +510,26 @@ python test zlib @end example + +@c ----------------------------------------------------------------------------- + @subsection @file{post-install} @file{post-install} files have the same requirements as the build script. They will be run after the package is installed as root (or as the user if the user has write permissions on @env{CPT_ROOT}). + +@c ----------------------------------------------------------------------------- + @subsection @file{message} This plaintext file will be outputted with @command{cat} after every package is installed. + +@c ----------------------------------------------------------------------------- + @subsection @file{test} Test files are mainly for the repository maintainer to test the packages, and @@ -463,6 +537,9 @@ will only run if the user has the @env{CPT_TEST} variable set, or the build is run with the @option{-t} or @option{--test} options. This script is run on the build directory. It is run right after the build script is finished. + +@c ----------------------------------------------------------------------------- + @node Rsync Repositories @section Rsync Repositories @@ -512,6 +589,9 @@ is an individual repository, and the package manager will fetch accordingly. * Setting up an rsync repository for distribution:: @end menu + +@c ----------------------------------------------------------------------------- + @node Setting up an rsync repository for distribution @subsection Setting up an rsync repository for distribution @@ -564,3 +644,6 @@ Create a service file at @file{/etc/sv/rsync/run} (runit): #!/bin/sh exec rsync --daemon --no-detach @end example + + +@c ----------------------------------------------------------------------------- @@ -1,3 +1,8 @@ +@c This document is part of Carbs Linux Documentation. +@c See the top.texi file for LICENSE information. + +@c ----------------------------------------------------------------------------- + @node Init System @chapter Init System @@ -12,6 +17,9 @@ programs. * Changing Init Program:: Replacing the default busybox init with something new @end menu + +@c ----------------------------------------------------------------------------- + @node Configuring Init @section Configuring Init @@ -26,6 +34,9 @@ Kernel Command Line Init Hooks @end enumerate + +@c ----------------------------------------------------------------------------- + @subsection Kernel Command Line On GRUB, you can edit the kernel command line parameters, which will be parsed @@ -51,6 +62,9 @@ Some of these variables, such as @env{rw}/@env{ro}, @env{loglevel}, and @env{quiet}, will be used by the init system to change the behaviour of the startup. + +@c ----------------------------------------------------------------------------- + @subsection @file{/etc/init/rc.conf} file However, the kernel command line isn't the only place to set your boot @@ -58,6 +72,9 @@ 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. + +@c ----------------------------------------------------------------------------- + @node Init Hooks @section Init Hooks @@ -78,6 +95,9 @@ Run first when shutting down. Run just before the system is halted. @end table + +@c ----------------------------------------------------------------------------- + @node Changing Init Program @section Changing Init Program @@ -104,6 +124,9 @@ $ cpt a runit /usr/bin/poweroff $ cpt a runit /usr/bin/reboot @end example + +@c ----------------------------------------------------------------------------- + @subsection Rebooting after changing Init After switching init systems, your running init system may not accept the @@ -119,3 +142,6 @@ currently running on your system and not the one you are switching to. @item shinit/sinit @code{$ kill -s INT 1} @end table + + +@c ----------------------------------------------------------------------------- diff --git a/install.texi b/install.texi index 37e8bb3..d05fa59 100644 --- a/install.texi +++ b/install.texi @@ -1,3 +1,8 @@ +@c This document is part of Carbs Linux Documentation. +@c See the top.texi file for LICENSE information. + +@c ----------------------------------------------------------------------------- + @node Installation @chapter Installation @@ -17,6 +22,9 @@ The instructions can also be found plaintext on * Post-installation:: Acquiring more packages and repositories @end menu + +@c ----------------------------------------------------------------------------- + @node Preparing Environment @section Preparing Environment To install Carbs Linux, you will need a Live Linux ISO. For that purpose, you @@ -24,6 +32,7 @@ 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 @@ -38,12 +47,15 @@ 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. + +@c ----------------------------------------------------------------------------- + @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 @code{x86_64} -with @code{i686}. We are setting this in a URL variable so that we don't have to -write it every time. +to obtain the rootfs. If you are using an i686 machine, replace the +@code{x86_64} with @code{i686}. We are setting this in a URL variable so that we +don't have to write it every time. @example $ URL=https://dl.carbslinux.org/releases/x86_64 @@ -53,17 +65,23 @@ $ wget $URL/carbs-rootfs.tar.xz We can then check the integrity of the tarball and do a signature verification. Even thought these are optional, they are highly recommended. + +@c ----------------------------------------------------------------------------- + @subsection Check the integrity of the tarball (Recommended) -All of the releases are saved in a single file named @file{sha256sums.txt}, but the -latest release is saved on @file{carbs-rootfs.tar.xz.sha256}. You can acquire and -verify the tarball. +All of the releases are saved in a single file named @file{sha256sums.txt}, but +the latest release is saved on @file{carbs-rootfs.tar.xz.sha256}. You can +acquire and verify the tarball. @example $ wget $URL/carbs-rootfs.tar.xz.sha256 $ sha256sum -c carbs-rootfs.tar.xz.sha256 @end example + +@c ----------------------------------------------------------------------------- + @subsection Verify the signature It is highly recommended to verify the signature of the tarball. You will need @@ -75,6 +93,9 @@ $ gpg --recv-keys FF484BDFEFCEF8FF $ gpg --verify carbs-rootfs.tar.xz.sig @end example + +@c ----------------------------------------------------------------------------- + @subsection Extracting the tarball You will need to extract the tarball to your desired location. For partitioning, @@ -86,6 +107,9 @@ $ mount /dev/sdx1 /mnt $ tar xf carbs-rootfs.tar.xz -C /mnt @end example + +@c ----------------------------------------------------------------------------- + @subsection Obtain the chroot helper You can obtain the @command{cpt-chroot} script in order to do a simple chroot into @@ -96,6 +120,8 @@ $ wget https://dl.carbslinux.org/distfiles/cpt-chroot $ chmod a+x cpt-chroot @end example +@c ----------------------------------------------------------------------------- + @node Chroot @section Chroot @@ -105,6 +131,9 @@ Chroot into Carbs Linux! $ ./cpt-chroot /mnt @end example + +@c ----------------------------------------------------------------------------- + @subsection Setting up repositories Newest tarballs do not come with repositories, so you will need to manually @@ -123,6 +152,9 @@ you want. So go ahead and create that directory: $ mkdir -p $HOME/repos @end example + +@c ----------------------------------------------------------------------------- + @subsubsection Obtaining from rsync Carbs Linux rsync repositories live in @url{rsync://carbslinux.org/repo}. In @@ -132,6 +164,9 @@ order to obtain it, run the following: $ rsync -avc rsync://carbslinux.org/repo $HOME/repos/carbs @end example + +@c ----------------------------------------------------------------------------- + @subsubsection Obtaining from git Carbs Linux git repositories can be found both from the main server and GitHub @@ -148,6 +183,9 @@ Carbs Linux git repositories can be found both from the main server and GitHub $ git clone git://git.carbslinux.org/repository $HOME/repos/carbs @end example + +@c ----------------------------------------------------------------------------- + @subsubsection Making the package manager use the repositories In your shell's configuration file, or in your @file{~/.profile} file, add the @@ -162,6 +200,9 @@ CPT_PATH=$CPT_PATH:$HOME/repos/carbs/community export CPT_PATH @end example + +@c ----------------------------------------------------------------------------- + @subsection Updating packages It is good practice to make sure your system is up to date, especially before @@ -172,6 +213,9 @@ need to update twice. $ cpt update @end example + +@c ----------------------------------------------------------------------------- + @subsection Installing packages Since you are operating on a really small base, you might need to build and @@ -184,6 +228,9 @@ $ cpt build package $ cpt install package @end example + +@c ----------------------------------------------------------------------------- + @subsection Essential Software Here is a list of software that you might want to have on your system. @@ -258,6 +305,9 @@ man-pages man-pages-posix @end itemize + +@c ----------------------------------------------------------------------------- + @subsection Obtaining the documentation (optional) All the documentation for Carbs Linux can be found on a single info manual to be @@ -276,12 +326,18 @@ You can then run info and navigate through the documentation. $ info carbslinux @end example + +@c ----------------------------------------------------------------------------- + @node System Configuration @section System Configuration After you have finished installing some extra packages, you can configure your system to your liking. + +@c ----------------------------------------------------------------------------- + @subsection Configuring hostname (recommended) You might want to add a hostname, especially in a networked environment. Your @@ -291,6 +347,9 @@ hostname will default to 'carbslinux' unless you set this. $ echo your-hostname > /etc/hostname @end example + +@c ----------------------------------------------------------------------------- + @subsection Setting up hosts file (optional) You can edit your /etc/hosts file, which is the static lookup table for host @@ -302,6 +361,9 @@ replace the 'localhost' part of these entries to your hostname. ::1 localhost.localdomain localhost ip6-localhost @end example + +@c ----------------------------------------------------------------------------- + @node Kernel @section Kernel @@ -310,6 +372,9 @@ one for your personal use. Here is an @url{https://github.com/cemkeylan/kiss-rep which you will need to reconfigure for your specific setup if you want to make use of it. + +@c ----------------------------------------------------------------------------- + @subsection Obtaining the kernel sources You can visit the https://kernel.org website to choose a kernel that you want @@ -325,6 +390,9 @@ Change directory into the kernel sources $ cd linux-5.7.6 @end example + +@c ----------------------------------------------------------------------------- + @subsection Installing dependencies In order to compile the kernel you will need to install some dependencies. You @@ -347,6 +415,9 @@ $ wget https://dl.carbslinux.org/distfiles/kernel-no-perl.patch $ patch -p1 < kernel-no-perl.patch @end example + +@c ----------------------------------------------------------------------------- + @subsection Compiling the kernel Next step is configuring and building the kernel. You can check Gentoo's @url{https://wiki.gentoo.org/wiki/Kernel/Configuration, kernel configuration guide} @@ -360,6 +431,9 @@ $ make $ install -Dm755 $(make -s image_name) /boot/vmlinuz-linux @end example + +@c ----------------------------------------------------------------------------- + @node Making your system bootable @section Making your system bootable @@ -367,6 +441,9 @@ 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. + +@c ----------------------------------------------------------------------------- + @subsection Installing a bootloader In the main repository, there is efibootmgr and grub to serve as bootloaders. @@ -395,6 +472,9 @@ $ grub-install --target=x86_64-efi \ $ grub-mkconfig -o /boot/grub/grub.cfg @end example + +@c ----------------------------------------------------------------------------- + @subsection Installing init scripts Only thing left to do is installing the init-scripts, and now you are almost @@ -404,6 +484,9 @@ ready to boot your system! $ cpt b carbs-init && cpt i carbs-init @end example + +@c ----------------------------------------------------------------------------- + @subsection Generating fstab You can now manually edit your fstab entry, or you can use the genfstab tool. @@ -415,12 +498,18 @@ $ chmod +x genfstab $ ./genfstab -U /mnt >> /mnt/etc/fstab @end example + +@c ----------------------------------------------------------------------------- + @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. + +@c ----------------------------------------------------------------------------- + @subsection Acquiring kiss repositories While not 100% compatible with cpt, you can use kiss repositories in your @@ -435,3 +524,6 @@ $ export CPT_PATH=$CPT_PATH:$HOME/repos/kiss-community/community NOTE: There are lots of packages on the KISS community repository that are also on Carbs Linux main repository. I would advise giving lower priority to the KISS community repository as it may affect other packages that you might install. + + +@c ----------------------------------------------------------------------------- @@ -1,6 +1,18 @@ \input texinfo +@c ----------------------------------------------------------------------------- +@c +@c This is the Carbs Linux documentation, see the @copying section for LICENSE +@c details. +@c +@c In order to keep the file easily readable and editable, always seperate +@c with comment lines like the ones above and below. Those lines should reach +@c to 80 characters total. Try to keep characters per line below 80, and do NOT +@c exceed 100 unless you are adding a really long link or something. Also see +@c the Contribution guidelines, which are written contribution.texi for any more +@c information. @c Start of header +@c ----------------------------------------------------------------------------- @settitle Carbs Linux User Manual @setfilename carbslinux.info @@ -28,6 +40,9 @@ Documentation License.'' @insertcopying @end titlepage +@c End of Header +@c ----------------------------------------------------------------------------- + @ifnottex @node Top @top Carbs Linux User Manual @@ -52,6 +67,9 @@ for doing the first. @end ifnottex + +@c ----------------------------------------------------------------------------- + @menu * Installation:: Installing Carbs Linux * Package Manager:: Carbs Linux Packaging Tools @@ -61,6 +79,7 @@ for doing the first. * GNU Free Documentation License:: Copying Conditions @detailmenu + --- Detailed Menu Listing --- Overview of Installation @@ -88,15 +107,24 @@ Overview of Init System @end detailmenu @end menu + +@c ----------------------------------------------------------------------------- + @include install.texi @include cpt.texi @include contribution.texi @include init.texi @include software.texi + +@c ----------------------------------------------------------------------------- + @node GNU Free Documentation License @unnumbered GNU Free Documentation License @include fdl.texi + +@c ----------------------------------------------------------------------------- + @bye |