Carbs Linux Documentation
git clone git://
Log | Files | Refs | Submodules | README

commit 9212ead597f031a7707c07d8276af1b49668f515
parent 3f621264096c465378a7f1bc4d5dab90c946d7b5
Author: Cem Keylan <>
Date:   Fri, 25 Dec 2020 16:51:27 +0300

*.texi: remove from repository

Dcontribution.texi | 332-------------------------------------------------------------------------------
Dcpt.texi | 776-------------------------------------------------------------------------------
Dfdl.texi | 505-------------------------------------------------------------------------------
Dinit.texi | 147-------------------------------------------------------------------------------
Dinstall.texi | 529-------------------------------------------------------------------------------
Dtop.texi | 131-------------------------------------------------------------------------------
6 files changed, 0 insertions(+), 2420 deletions(-)

diff --git a/contribution.texi b/contribution.texi @@ -1,332 +0,0 @@ -@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 - -@macro sectid{id, sect} -@strong{@contid{\id\} \sect\} -@end macro - - -@c ----------------------------------------------------------------------------- - -@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:: Distribution conventions -* 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 - -@table @strong -@item @contid{0010} -Try to keep the file readable. -@table @strong -@item @contid{0011} -Characters on a line shouldn't exceed 100 characters. -@item @contid{0012} -Make sure you don't have code commented out during commit. Uncomment them -or remove them completely. -@item @contid{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: -@example -# Good way of commenting. -your code goes here - -your code goes here # Avoid this way of commenting. -@end example -@end table -@end table - - -@c ----------------------------------------------------------------------------- - -@node Shell Conventions -@subsection Shell Conventions -- 10 - -Shell is central to Carbs Linux projects. Most of the tools and packages are -written in POSIX sh. - -@table @strong -@item @contid{1010} -Use 4 spaces for indentation, don't use tabs. -@item @contid{1020} -Make sure you don't use bash-specific code. -@item @contid{1030} -Make sure you lint your code with @command{shellcheck} and if you are new to -POSIX sh, use @command{checkbashisms}. -@item @contid{1040} -Don't spawn new processes if you don't absolutely need to, especially during -string manipulation. -@table @strong -@item @contid{1041} -Never use a program for text manupilation that isn't defined in the POSIX -standard. This includes @command{gawk} and @command{perl}. -@item @contid{1042} -Instead of @code{$(basename $file)}, use @code{$@{file##*@}}. -@item @contid{1043} -Instead of @code{$(dirname $file)}, use @code{$@{file%/*@}}. -@end table -@example -# This is the same thing as @code{basename /path/to/test.asc .asc} - -$ file=/path/to/test.asc file=$@{file##*/@} file=$@{file%.asc@} -$ echo $file -test -@end example -@item @contid{1050} -Instead of backticks, use @verb{|$(..)|}. -@end table - - -@c ----------------------------------------------------------------------------- - -@node Repository Conventions -@subsection Repository Conventions -- 20 - -Repository conventions are important in order to ensure every package resemble -themselves. Here are the things to keep in mind: - -@table @strong -@item @contid{2010} -Prefer tarballs over git packages unless there is a sensible reason. -Here are some: - -@itemize -@item -Every patch is a new release. (See @url{, vim}) -@item -There are no releases. (See @url{}) -@item -Following a development branch. -@item -There has been a long time since the latest release, but upstream is far ahead. -@end itemize - -@item @contid{2020} -Prefer sources without a dependency to @command{automake}. There are usually -distribution tarballs that are @command{autoconf}'ed. Don't submit tarballs -with an automake dependency unless you are @strong{sure} there is no -alternative. -@item @contid{2030} -Avoid these packages: -@table @command -@item dbus -Usually can be disabled by @option{--disable-dbus} -@item gettext -Usually can be disabled by @option{--disable-nls} -@end table -@item @contid{2040} -@itemize -@item -Always install a package to the @file{/usr} prefix. -@item -All binaries should go to @file{/usr/bin}, not @file{/usr/sbin} or any other -directory. -@item -All libraries should go to @file{/usr/lib}. -@end itemize -@item @contid{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. - - -@c ----------------------------------------------------------------------------- - -@sectid{2210, Make} - -@example -#!/bin/sh -e - -make -make DESTDIR="$1" PREFIX=/usr install -@end example - - -@c ----------------------------------------------------------------------------- - -@sectid{2211, Configure/Make} - -@example -#!/bin/sh -e - -./configure \ - --prefix=/usr \ - --disable-option \ - --enable-option - -make -make DESTDIR="$1" install -@end example - - -@c ----------------------------------------------------------------------------- - -@sectid{2212, Autoconf/Automake} - -@xref{2020} - -@example -#!/bin/sh -e - -autoreconf -fi - -./configure \ - --prefix=/usr \ - --disable-option \ - --enable-option - -make -make DESTDIR="$1" install -@end example - - -@c ----------------------------------------------------------------------------- - -@sectid{2220, Meson} - -@example -#!/bin/sh -e - -export DESTDIR=$1 - -meson \ - --prefix=/usr \ - -Doption=false \ - -Doption2=true \ - . output - -ninja -C output -ninja -C output install -@end example - - -@c ----------------------------------------------------------------------------- - -@sectid{2230, Cmake} - -@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 - - -@c ----------------------------------------------------------------------------- - -@sectid{2240, Go} - -@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 - - -@c ----------------------------------------------------------------------------- - -@sectid{2241, Python} - -@example -#!/bin/sh -e - -python build -python install --prefix=/usr --root="$1" -@end example - - -@c ----------------------------------------------------------------------------- - -@node Sending Git mails -@section Sending Git mails - -As mentioned, the preferred way of contribution is via patches. The easiest way -for sending git mails without @command{git send-email} is using @command{msmtp}. -You can install it from the repository by doing: - -@example -$ cpt b msmtp && cpt i msmtp -@end example - -You can then edit @file{~/.config/msmtp/config} to add your email. Here is an -example configuration, you can use @command{pass}, @command{pash}, or any other -password manager that fits your needs: - -@example -defaults -auth on -tls on -tls_trust_file /etc/ssl/certs/ca-certificates.crt -logfile ~/.config/msmtp/msmtp.log -account my-mail -host -port 587 -from -user -passwordeval "pass my-mail" -@end example - -In order to simply send your patch, do the following: - -@example -$ git format-patch --to=~carbslinux/ -1 --stdout | - msmtp -t -a my-mail -@end example - -You can also send multiple patches by doing the following: - -@example -$ git format-patch --to=~carbslinux/ <region> - -Edit those files as necessary and send them. -$ for file in *.patch; do msmtp -t -a my-mail < $patch; done -@end example - - -@c ----------------------------------------------------------------------------- diff --git a/cpt.texi b/cpt.texi @@ -1,776 +0,0 @@ -@c This document is part of Carbs Linux Documentation. -@c See the top.texi file for LICENSE information. - -@c ----------------------------------------------------------------------------- - -@c Macros -@macro optbehsingle{opt} -This behaviour can also be achieved by adding @option{\opt\} as an argument -@end macro -@macro optbeh{opt, opt2} -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{, 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 -* Environment Variables:: Values that affect the operation of CPT -* Hooks:: Using hooks to customize the package manager operations -* Packaging System:: More detail on creating packages -* 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 -to @command{git}. When you run @command{cpt} without any arguments, it will show -all available tools and their explanations. Here is an example call with extra -scripts on my system: - -@example --> Carbs Packaging Tool --> add Commit the current directory as a new package --> alternatives List and swap to alternatives --> build Build a package --> bump Commit the current directory as a version bump --> cargo-urlgen Create static cargo sources for Rust packages --> cargolock-urlgen Convert the given Cargo.lock file to sources --> cat Concatanate package files in the installed package database --> changelog Print the git log of the specific package --> chbuild Create/destroy temporary chroots --> checkmissing Verify package manifests --> checksum Generate checksums --> chroot Enter a chroot --> commit Commit a package without the prefix of 'package:' --> depends Display a package's dependencies --> download Download sources for the given package --> exec Execute a command inside the alternatives system --> export Turn an installed package into a CPT tarball --> fetch Fetch repositories --> fork Fork a package to the current directory --> getchoice Prints the full path to a file in the alternatives system. --> install Install a package --> link Link a forked package's files to the other repository --> list List installed packages --> maintainer Find the maintainer of a package --> manifest Display all files owned by a package --> manifest-tree Display all files owned by a package with a tree view --> new Create a boilerplate CPT package --> orphans List orphaned packages --> owns Check which package owns a file --> rel Bump the release number of a package --> remove Remove a package --> repodepends Display a package's dependencies in the repository --> reporevdepends Display packages on the repository which depend on package --> reset Remove all packages except for the base --> revdepends Display packages which depend on package --> search Search for a package --> size Show the size on disk for a package --> source Extract sources of a given package to the current directory --> update Check for updates -@end example - -@menu -* @command{cpt-alternatives}:: -* @command{cpt-build}:: -* @command{cpt-checksum}:: -* @command{cpt-download}:: -* @command{cpt-fetch}:: -* @command{cpt-install}:: -* @command{cpt-list}:: -* @command{cpt-remove}:: -* @command{cpt-search}:: -* @command{cpt-update}:: -@end menu - - -@c ----------------------------------------------------------------------------- - -@node @command{cpt-alternatives} -@subsection @command{cpt-alternatives} - -You can list and swap to alternatives using @command{cpt-alternatives}, or -@command{cpt a} for short. When run without alternatives, it will list -alternatives. It can read from standard input if @option{-} is given as an -argument. - - -@c ----------------------------------------------------------------------------- - -@unnumberedsubsubsec Examples - -List alternatives - -@example -$ cpt-alternatives -ncurses /usr/bin/clear -ncurses /usr/bin/reset -@end example - -Swap to @command{clear} from @command{ncurses}. - -@example -$ cpt-alternatives ncurses /usr/bin/clear --> Swapping '/usr/bin/clear' from 'busybox' to 'ncurses' -@end example - -Swap in bulk (all of sbase). - -@example -$ cpt a | grep ^sbase | cpt a - -@end example - - -@c ----------------------------------------------------------------------------- - -@node @command{cpt-build} -@subsection @command{cpt-build} - -@command{cpt-build} will build given packages and their dependencies. If -multiple packages are specified, it will ask to install the packages as well. - - -@c ----------------------------------------------------------------------------- - -@unnumberedsubsubsec Options - -@table @option -@item -y --no-prompt -Do not prompt for confirmation -@item -t --test -Run tests (if it exists) -@end table - - -@c ----------------------------------------------------------------------------- - -@node @command{cpt-checksum} -@subsection @command{cpt-checksum} - -@command{cpt-checksum} will generate a @file{checksums} file from the package's -sources. - - -@c ----------------------------------------------------------------------------- - -@node @command{cpt-download} -@subsection @command{cpt-download} - -@command{cpt-download} will download the sources of a package. - - -@c ----------------------------------------------------------------------------- - -@node @command{cpt-fetch} -@subsection @command{cpt-fetch} - -@command{cpt-fetch} will fetch remote repositories. - - -@c ----------------------------------------------------------------------------- - -@node @command{cpt-install} -@subsection @command{cpt-install} - -@command{cpt-install} will install given packages. - - -@c ----------------------------------------------------------------------------- - -@unnumberedsubsubsec Options - -@table @option -@item -f --force -Force installation. @xref{cptforce,,@env{CPT_FORCE}}. -@item --root -Set an alternative root directory. @xref{cptroot,,@env{CPT_ROOT}}. -@end table - - -@c ----------------------------------------------------------------------------- - -@node @command{cpt-list} -@subsection @command{cpt-list} - -When called without arguments, @command{cpt-list} will print all installed -packages. You can add package names as arguments to check whether they are -installed or not. In success, @command{cpt-list} will exit with status 0 if all -given packages are installed, it will return 1 if any of the given packages -aren't installed. - - -@c ----------------------------------------------------------------------------- - -@node @command{cpt-remove} -@subsection @command{cpt-remove} - -@command{cpt-remove} will remove given packages. - - -@c ----------------------------------------------------------------------------- - -@unnumberedsubsubsec Options - -@table @option -@item -f --force -Force removal. @xref{cptforce,,@env{CPT_FORCE}}. -@item --root -Set an alternative root directory. @xref{cptroot,,@env{CPT_ROOT}}. -@end table - - -@c ----------------------------------------------------------------------------- - -@node @command{cpt-search} -@subsection @command{cpt-search} - -@command{cpt-search} will remove given packages. - - -@c ----------------------------------------------------------------------------- - -@unnumberedsubsubsec Options - -@table @option -@item -s --single -Only show the first instance of a package. -@end table - - -@c ----------------------------------------------------------------------------- - -@node @command{cpt-update} -@subsection @command{cpt-update} - -@command{cpt-update} will update the packages on your system. - - -@c ----------------------------------------------------------------------------- - -@unnumberedsubsubsec Options - -@table @option -@item -d --download -Only download updatable packages. -@item -n --no-fetch -Do not fetch remote repositories. -@item -y --no-prompt -Do not prompt for confirmation. -@item --root -Use an alternate root directory. @xref{cptroot,,@env{CPT_ROOT}}. -@end table - - -@c ----------------------------------------------------------------------------- - -@node Environment Variables -@section Environment Variables - -Since there is no configuration file for cpt, the package manager is configured -through environment variables. These can be set per operation, or be set to your -shell configuration or @file{~/.profile}. Here are the environment variables that -alter the behaviour of @command{cpt}: - -@table @env -@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} -@item -@command{zst} -@item -@command{bz2} -@item -@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 @anchor{cptforce}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: - -@itemize -@item -@command{cpt-install} will install a package without verifying its manifest. -@item -@command{cpt-install} will install a package even when there are missing -dependencies. -@item -@command{cpt-remove} will remove packages even when there are other packages -that depend on the current package. -@end itemize - -@optbeh{-f, --force} to those utilities. - -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 -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 @anchor{cptroot}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 - -Hooks can be used in order to change the runtime behaviour of the package manager. -There are a variety of package hooks, mostly self explanatory: - -@itemize -@item -pre-build -@item -post-build -@item -build-fail -@item -pre-test -@item -test-fail -@item -pre-install -@item -post-install -@item -pre-remove -@item -post-remove -@item -pre-fetch -@item -post-fetch -@item -post-package -@end itemize - -In order to use hooks, you will need to set the @env{CPT_HOOK} variable pointing -to your hook file. Your hook file @strong{MUST} be a POSIX shell script as its -contents are sourced by the package manager. - -The hook is given 3 variables when it is executed. Those are: -@table @env -@item $TYPE -The type of the hook, (pre-build, post-build, etc.) -@item $PKG -The package that @command{cpt} is currently working on. Can be null. -@item $DEST -The destination of the operation. Can be null. -@end table - -@c There are many ways to deal with hooks. - -@menu -* 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 - -You can edit the @file{build} file during pre-build. The file is copied from the -repository to the build directory named as @file{.build.cpt}. You can use -@command{sed} or any other tool to edit the build file. After the build is -complete, a @command{diff} file will be placed to the package database named as -@file{build.diff}. Here is an example @file{build} file manipulation during the -pre-build hook. - -@example -cat <<EOF> .build.cpt -#!/bin/sh -e - -for patch in bash50-0??; do - patch -p0 < "\$patch" -done - -export LDFLAGS=-static - -./configure \ - --prefix=/usr \ - --without-bash-malloc \ - --disable-nls - -export MAKEFLAGS="TERMCAP_LIB=/usr/lib/libncursesw.a $MAKEFLAGS" - -make -make DESTDIR="\$1" install - -ln -s bash "\$1/usr/bin/sh" -EOF -@end example - - -@c ----------------------------------------------------------------------------- - -@node Packaging System -@section Packaging System - -A package is formed of several files, these are: -@itemize -@item -@file{build} -@item -@file{sources} -@item -@file{checksums} -@item -@file{version} -@item -@file{depends} -@item -@file{post-install} -@item -@file{message} -@item -@file{test} -@end itemize - -Any other file can be added to the package directory at the discretion of the -package maintainer. Everything in the package directory will also be added to the -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 -code to be installed on the target system. Even though we will be assuming that -the @file{build} file is a POSIX shell script (for portability's sake), @file{build} -files can be any executable program from binary programs to @command{perl} scripts. - -The contents of a build script do not need to follow a certain rule for the -package manager, except for the fact that the user needs the permission to -execute the file. - -An important advice is to append an '-e' to the shebang (#!/bin/sh -e) so that -the build script exits on compilation error. - -Build is run with three arguments (@env{$#}) - -@enumerate -@item -Location of the package directory (DESTDIR) -@item -Package version -@item -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 -directory during the build process. Those can be remote sources (such as tarballs), -git repositories, and files that reside on the package directory. - -The syntax is pretty simple for the @file{soures} file; @verb{|src dest|}. The -@env{dest} parameter is optional. It is the directory that the source will be -placed in. Here is the @file{sources} file for the @command{gst-plugins} package: - -@example - good - bad - ugly - libav -@end example - -This file is read from the package manager as space seperated. Files that begin -with a '#' comment are ignored. The first value points to the location of the -source. - -If it starts with a protcol url, (such as ftp:// http:// https://) it will be -downloaded with @command{curl}. - -If the source is a git repository, it shall be prefixed with a @verb{|git+|} git(1) will -be used to do a shallow clone of the repository. If the commit is suffixed by a -history pointer, git will checkout the relevant revision. So, - -@table @indicateurl -@item git+git:// -will checkout the tag named 'v1.2.3' -@item git+git:// -will checkout the branch named 'development' -@item git+git:// -will checkout the commit named '1a314s87' -@end table - -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 -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 -of the package on a space seperated format. The contents of the file should look -like below. - -@example -1.3.2 1 -@end example - -The version should always match to the number of the upstream release. For -drastic changes that require a rebuild Those can be, - -@itemize -@item -update of libraries that forces the package to be relinked -@item -change in the build scripts that affect the output of the package -@end itemize - -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 -can append ``make'' after a dependency to mark a package is only required during -the build process of a package. Packages marked as a make dependency can be -removed after the build. There are also ``test'' dependencies. These dependencies -are only installed if either the @env{CPT_TEST} is set to 1, or the build is run -with the @option{-t} or @option{--test} options. So, a package package could have -the following @file{depends} file: - -@example -linux-headers make -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 -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 - -Rsync repositories are simple to serve and simple to use. In the repository -directory, there needs to be a '.rsync' file that points to the remote of the -repository. This is used in order to fetch changes from the upstream. '.rsync' -file looks like this for the core repository: - -@example -rsync:// -@end example - -Rsync repositories have some few distinctions when it comes to fetching them. -They can be either synced individually or as a ``root''. There are 2 important -files, those are @file{.rsync} and @file{.rsync_root}. Here is the Carbs Linux -rsync repository structure. - -@example - / - ----------------- - | | -.rsync core/ - ---------------- - | | - .rsync .rsync_root -@end example - -Unlike git repositories, they don't have a defined ``root'' directory. This is -both an advantage and a disadvantage. This way, we can sync individual -repositories, but that also means we need extra files to define root directories -and repository locations. Here is the content for each of these files: - -@example -/.rsync: rsync:// -/core/.rsync: rsync:// -/core/.rsync_root: .. -@end example - -The @file{.rsync_root} file on the core repository points to the upper directory. -If a @file{.rsync} file exists on the upper directory, this means that is the whole -repository and will sync the entire repository instead of each individual repository. - -If the upper directory doesn't have this @file{.rsync} file, this means that this -is an individual repository, and the package manager will fetch accordingly. - -@menu -* 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 - -Carbs Linux repositories automatically sync from the git repostitories and serve -it through the rsync daemon. Here is a sample shell script that I use in order to -sync repositories. Feel free to customize for your own use. - -@verbatim - #!/bin/sh - HOSTNAME="rsync://" - GITDIR="/pub/git/repo" - SHAREDIR="/pub/share/repo" - git -C "$GITDIR" pull - - rsync -avcC --delete --include=core --exclude=.rsync,.rsync_root "$GITDIR/." "$SHAREDIR" - - printf '%s\n' "$HOSTNAME" > "$GITDIR/.rsync" - for dir in "$GITDIR/"*; do - [ -d "$dir" ] || continue - [ -f "$dir/.rsync" ] || - printf '%s/%s\n' "$HOSTNAME" "${dir##*/}" > "$dir/.rsync" - printf '..\n' > "$dir/.rsync_root" - done -@end verbatim - -You can then create an @strong{rsync} user for serving the repositories. - -@example -$ adduser -SD rsync -@end example - -Create @file{/etc/rsyncd.conf} and a service configuration as well. - -@verbatim - - uid = rsync - gid = rsync - address = - max connections = 10 - use chroot = yes - - [repo] - path = /pub/share/repo - comment = My repository -@end verbatim - -Create a service file at @file{/etc/sv/rsync/run} (runit): - -@example -#!/bin/sh -exec rsync --daemon --no-detach -@end example - - -@c ----------------------------------------------------------------------------- diff --git a/fdl.texi b/fdl.texi @@ -1,505 +0,0 @@ -@c The GNU Free Documentation License. -@center Version 1.3, 3 November 2008 - -@c This file is intended to be included within another document, -@c hence no sectioning command or @node. - -@display -Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. -@uref{} - -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, La@TeX{} 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{}. - -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 -@heading 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: - -@smallexample -@group - Copyright (C) @var{year} @var{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 group -@end smallexample - -If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, -replace the ``with@dots{}Texts.''@: line with this: - -@smallexample -@group - with the Invariant Sections being @var{list their titles}, with - the Front-Cover Texts being @var{list}, and with the Back-Cover Texts - being @var{list}. -@end group -@end smallexample - -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. - -@c Local Variables: -@c ispell-local-pdict: "ispell-dict" -@c End: diff --git a/init.texi b/init.texi @@ -1,147 +0,0 @@ -@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 - -Carbs Linux init scripts are run by the init daemon (@command{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 -* Init Hooks:: Adding your personal commands to the init system -* Changing Init Program:: Replacing the default busybox init with something new -@end menu - - -@c ----------------------------------------------------------------------------- - -@node Configuring Init -@section Configuring Init - -There are three ways you can change the behaviour of the init system. Those are: - -@enumerate -@item -Kernel Command Line -@item -@file{/etc/init/rc.conf} file -@item -Init Hooks -@end enumerate - - -@c ----------------------------------------------------------------------------- - -@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 @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 -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 - -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 @file{/etc/init} directory with the -hook name as the suffix. For example, a boot script will be placed as -@file{/etc/init/my-hook.boot}. Currently, there are 4 hooks that the user can use. - -@table @file -@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 post.shutdown -Run just before the system is halted. -@end table - - -@c ----------------------------------------------------------------------------- - -@node Changing Init Program -@section Changing Init Program - -By default, Carbs Linux comes preinstalled with @command{busybox-init}, but this -can easily be replaced without any issues. Currently, available init systems are: - -@itemize -@item -sinit -@item -busybox -@item -runit -@item -shinit -@end itemize - -This example is for runit, but it will work with all init systems packaged in the -distribution repositories. @xref{@command{cpt-alternatives}} - -@example -$ cpt a runit /usr/bin/init -$ 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 -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. - -@table @command -@item busybox -@code{$ busybox reboot} -@item runit -@code{$ runit-init 6} -@item shinit/sinit -@code{$ kill -s INT 1} -@end table - - -@c ----------------------------------------------------------------------------- diff --git a/install.texi b/install.texi @@ -1,529 +0,0 @@ -@c This document is part of Carbs Linux Documentation. -@c See the top.texi file for LICENSE information. - -@c ----------------------------------------------------------------------------- - -@node Installation -@chapter Installation - -These are the step-by-step instructions for installing Carbs Linux. - -@ifhtml -The instructions can also be found plaintext on -@url{} -@end ifhtml - -@menu -* Preparing Environment:: Getting ready to chroot -* Chroot:: Going inside your new system -* System Configuration:: Customizing for your personal use -* Kernel:: Compiling your own kernel -* Making your system bootable:: Installing init and bootloader -* 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 -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. - - -@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. - -@example -$ URL= -$ wget $URL/carbs-rootfs.tar.xz -@end example - -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. - -@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 -GPG for this. - -@example -$ wget $URL/carbs-rootfs.tar.xz.sig -$ 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, -you can follow @url{, this guide}. -This will assume that you will be mounting your root partition to @file{/mnt}. - -@example -$ 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 -your new root filesystem. - -@example -$ wget -$ chmod a+x cpt-chroot -@end example - -@c ----------------------------------------------------------------------------- - -@node Chroot -@section Chroot - -Chroot into Carbs Linux! - -@example -$ ./cpt-chroot /mnt -@end example - - -@c ----------------------------------------------------------------------------- - -@subsection Setting up repositories - -Newest tarballs do not come with repositories, so you will need to manually -obtain them, and set your @env{CPT_PATH} environment variable. Carbs Linux -repositories can either be obtained by @command{git} or @command{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 -@command{git} itself. - -The following guide will assume that you put the repositories into -@file{~/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 - - -@c ----------------------------------------------------------------------------- - -@subsubsection Obtaining from rsync - -Carbs Linux rsync repositories live in @url{rsync://}. In -order to obtain it, run the following: - -@example -$ rsync -avc rsync:// $HOME/repos/carbs -@end example - - -@c ----------------------------------------------------------------------------- - -@subsubsection 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 -@url{git://} -@item -@url{} -@end itemize - -@example -$ git clone git:// $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 -following lines: - -@example -export CPT_PATH='' -CPT_PATH=$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 - - -@c ----------------------------------------------------------------------------- - -@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 -@end example - - -@c ----------------------------------------------------------------------------- - -@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 - - -@c ----------------------------------------------------------------------------- - -@subsection Essential Software - -Here is a list of software that you might want to have on your system. - -BOOTLOADERS -@itemize -@item -efibootmgr -@item -grub -@end itemize -FILESYSTEMS -@itemize -@item -e2fsprogs -@item -dosfstools -@item -ntfs-3g -@end itemize -NETWORKING -@itemize -@item -dhcpcd -@item -wpa_supplicant -@end itemize -TEXT EDITORS -@itemize -@item -nano -@item -vim -@item -neatvi -@item -nvi -@item -emacs -@item -emacs-nox (terminal-only version of emacs) -@end itemize -USER SHELLS -@itemize -@item -bash -@item -zsh -@item -dash -@item -oksh -@item -rc -@end itemize -POSIX BASE UTILITIES -@itemize -@item -busybox -@item -sbase -@item -coreutils -@end itemize -DOCUMENTATION -@itemize -@item -carbs-docs -@item -man-pages -@item -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 -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 - - -@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 -hostname will default to 'carbslinux' unless you set this. - -@example -$ 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 -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 - localhost.localdomain localhost -::1 localhost.localdomain localhost ip6-localhost -@end example - - -@c ----------------------------------------------------------------------------- - -@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 @url{, example kernel package}, -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 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 -$ tar xf linux-5.7.6.tar.xz - -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 -will need @command{libelf} to compile the kernel. If you want to configure using the menu -interface you will also need @command{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 @url{, E5ten}. You will need to obtain and -apply the patch in the kernel source directory. - -@example -$ wget -$ 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{, 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 - - -@c ----------------------------------------------------------------------------- - -@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. - - -@c ----------------------------------------------------------------------------- - -@subsection Installing a bootloader - -In the main repository, there is efibootmgr and grub to serve as bootloaders. -efibootmgr can be used as a standalone bootloader, or can be used to install -grub in a UEFI environment. efibootmgr is needed unless you are using a device -without UEFI support (or you really want to use BIOS for a reason). - -GRUB BIOS installation - -@example -$ cpt b grub && cpt i grub -$ grub-install --target=i386-pc /dev/sdX -$ grub-mkconfig -o /boot/grub/grub.cfg -@end example - -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 - - -@c ----------------------------------------------------------------------------- - -@subsection Installing 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 - - -@c ----------------------------------------------------------------------------- - -@subsection Generating 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 -$ 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 -system the same way you are using the distribution repositories. Here is an -example for the KISS Linux Community repository. - -@example -$ git clone $HOME/repos/kiss-community -$ export CPT_PATH=$CPT_PATH:$HOME/repos/kiss-community/community -@end example - -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 ----------------------------------------------------------------------------- diff --git a/top.texi b/top.texi @@ -1,131 +0,0 @@ -\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 - -@copying -Copyright @copyright{} 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.'' -@end copying - -@dircategory System administration -@direntry -* Carbs Linux: (carbslinux). Carbs Linux User Manual -@end direntry - -@titlepage -@title Carbs Linux User Manual - -@page -@vskip 0pt plus 1fill -@insertcopying -@end titlepage - -@c End of Header -@c ----------------------------------------------------------------------------- -@summarycontents -@contents - - -@ifnottex -@node Top -@top Carbs Linux User Manual - -This is the full documentation of @url{, 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 - - -@c ----------------------------------------------------------------------------- - -@menu -* Installation:: Installing Carbs Linux -* Package Manager:: Carbs Linux Packaging Tools -* Init System:: Configuring the init system -* Contribution Guidelines:: Contributing to Carbs Linux -* GNU Free Documentation License:: Copying Conditions - -@detailmenu - ---- Detailed Menu Listing --- - -Installation - -* Preparing Environment:: Getting ready to chroot -* Chroot:: Going inside your new system -* System Configuration:: Customizing for your personal use -* Kernel:: Compiling your own kernel -* Making your system bootable:: Installing init and bootloader -* Post-installation:: Acquiring more packages and repositories - -Package Manager - -* Usage:: Using Carbs Packaging Tools -* Environment Variables:: Values that affect the operation of CPT -* Hooks:: Using hooks to customize the package manager operations -* Packaging System:: More detail on creating packages -* Rsync Repositories:: Information on using or creating rsync repositories - -Init System - -* Configuring Init:: Ways to configure the init system -* Init Hooks:: Adding your personal commands to the init system -* Changing Init Program:: Replacing the default busybox init with something new -@end detailmenu -@end menu - - -@c ----------------------------------------------------------------------------- - -@include install.texi -@include cpt.texi -@include init.texi -@include contribution.texi - - -@c ----------------------------------------------------------------------------- - -@node GNU Free Documentation License -@unnumbered GNU Free Documentation License - -@include fdl.texi - - -@c ----------------------------------------------------------------------------- - -@bye