aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--Makefile21
-rw-r--r--README7
-rw-r--r--cpt.texi359
-rw-r--r--extMakefile13
-rw-r--r--init.texi114
-rw-r--r--install.texi426
-rw-r--r--install.txt475
-rw-r--r--top.texi73
8 files changed, 1006 insertions, 482 deletions
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..7392697
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,21 @@
+# This Makefile is meant to generate a dist tarball in order to avoid installing
+# texinfo on the target system.
+TARBALL=carbs-docs-`date +%Y-%m-%d`
+DESTDIR=./docs
+
+all:
+
+dist:
+ mkdir -p ${TARBALL}
+ makeinfo -o ${TARBALL}/carbslinux.info top.texi
+ makeinfo --plaintext top.texi > ${TARBALL}/carbslinux.txt
+ cp extMakefile ${TARBALL}/Makefile
+ tar -cf ${TARBALL}.tar ${TARBALL}
+ gzip -9 ${TARBALL}.tar
+ rm -rf ${TARBALL}.tar ${TARBALL}
+
+htmldocs:
+ rm -rf -- ${DESTDIR}
+ makeinfo --html -o ${DESTDIR} top.texi
+
+.PHONY: all dist htmldocs
diff --git a/README b/README
index 68ca07d..8cf5b66 100644
--- a/README
+++ b/README
@@ -10,10 +10,3 @@ This is the source of offline documentation for Carbs Linux. It is a part of the
+--------------------------------------------------------------------------+
This documentation isn't complete yet, you can help by expanding it.
-
-
-[1.0] Document structure
---------------------------------------------------------------------------------
-
-Documents are categorized in directory structures which provide information on
-a certain subject. \ No newline at end of file
diff --git a/cpt.texi b/cpt.texi
new file mode 100644
index 0000000..8823a54
--- /dev/null
+++ b/cpt.texi
@@ -0,0 +1,359 @@
+@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.
+
+
+@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
+
+@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.
+
+@subsubsection 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
+
+@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.
+
+@subsubsection Options
+@command{cpt-build} will accept the following options:
+
+@itemize
+@item
+@option{-y}, @option{--no-prompt} -- Do not prompt for confirmation
+@item
+@option{}
+@end itemize
+
+@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.
+
+@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
+
+@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
+https://gstreamer.freedesktop.org/src/gst-plugins-good/gst-plugins-good-1.16.2.tar.xz good
+https://gstreamer.freedesktop.org/src/gst-plugins-bad/gst-plugins-bad-1.16.2.tar.xz bad
+https://gstreamer.freedesktop.org/src/gst-plugins-ugly/gst-plugins-ugly-1.16.2.tar.xz ugly
+https://gstreamer.freedesktop.org/src/gst-libav/gst-libav-1.16.2.tar.xz 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,
+
+@example
+git+git://example.com/pub/repo#v1.2.3 will checkout the tag named 'v1.2.3'
+git+git://example.com/pub/repo#development will checkout the branch named 'development'
+git+git://example.com/pub/repo#1a314s87 will checkout the commit named '1a314s87'
+@end example
+
+Other files are assumed to be residing in the package directory. They should be
+added with their paths relative to the package directory.
+
+
+@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.
+
+@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.
+
+@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
+
+@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}).
+
+@subsection @file{message}
+
+This plaintext file will be outputted with @command{cat} after every package is
+installed.
+
+@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.
+
+@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://carbslinux.org/repo/core
+@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://carbslinux.org/repo
+/core/.rsync: rsync://carbslinux.org/repo/core
+/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.
+
+@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://carbslinux.org/repo"
+ 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 = example.com
+ 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
diff --git a/extMakefile b/extMakefile
new file mode 100644
index 0000000..3724c1f
--- /dev/null
+++ b/extMakefile
@@ -0,0 +1,13 @@
+PREFIX=/usr/local
+SHAREDIR=${PREFIX}/share
+INFODIR=${SHAREDIR}/info
+DOCDIR=${SHAREDIR}/doc
+
+all:
+ @echo run make install
+
+install:
+ install -Dm644 carbslinux.info ${DESTDIR}${INFODIR}/carbslinux.info
+ install -Dm644 carbslinux.txt ${DESTDIR}${SHAREDIR}/carbslinux.txt
+
+.PHONY: all install
diff --git a/init.texi b/init.texi
new file mode 100644
index 0000000..b8811af
--- /dev/null
+++ b/init.texi
@@ -0,0 +1,114 @@
+@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.
+
+@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
+
+@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.
+
+@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.
+
+@subsection Init Hooks
+
+Init hooks are for custom personal commands that the user may want to add to
+alter their boot. These can be used to load kernel modules, modify interfaces,
+and lot more. Those hooks are added to the @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
+
+@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
+
+@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
diff --git a/install.texi b/install.texi
new file mode 100644
index 0000000..ccc8695
--- /dev/null
+++ b/install.texi
@@ -0,0 +1,426 @@
+@node Installation
+@chapter Installation
+
+These are the step-by-step instructions for installing Carbs Linux.
+
+@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
+
+@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.
+
+@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}.
+
+@example
+$ wget https://dl.carbslinux.org/releases/x86_64/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.
+
+@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 https://dl.carbslinux.org/releases/x86_64/carbs-rootfs.tar.xz.sha256
+$ sha256sum -c carbs-rootfs.tar.xz.sha256
+@end example
+
+@subsection Verify the signature
+
+It is highly recommended to verify the signature of the tarball. You will need
+GPG for this.
+
+@example
+$ wget https://dl.carbslinux.org/releases/carbs-rootfs.tar.xz.sig
+$ gpg --recv-keys FF484BDFEFCEF8FF
+$ gpg --verify carbs-rootfs.tar.xz.sig
+@end example
+
+@subsection Extracting the tarball
+
+You will need to extract the tarball to your desired location. For partitioning,
+you can follow @url{https://wiki.archlinux.org/index.php/Partitioning, 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
+
+@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 https://dl.carbslinux.org/distfiles/cpt-chroot
+$ chmod a+x cpt-chroot
+@end example
+
+@node Chroot
+@section Chroot
+
+Chroot into Carbs Linux!
+
+@example
+$ ./cpt-chroot /mnt
+@end example
+
+@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. @command{mkdir -p $HOME/repos}.
+
+@subsubsection Obtaining from rsync
+
+Carbs Linux rsync repositories live in @url{rsync://carbslinux.org/repo}. In
+order to obtain it, run the following:
+
+@example
+$ rsync -avc rsync://carbslinux.org/repo $HOME/repos/carbs
+@end example
+
+@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://git.carbslinux.org/repository}
+@item
+@url{https://github.com/carbslinux/repository}
+@end itemize
+
+@example
+$ git clone git://git.carbslinux.org/repository $HOME/repos/carbs
+@end example
+
+@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
+
+@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
+
+@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.
+
+@example
+$ cpt build package
+$ cpt install package
+@end example
+
+@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
+
+@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
+
+@node System Configuration
+@section System Configuration
+
+After you have finished installing some extra packages, you can configure your
+system to your liking.
+
+@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
+
+@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
+127.0.0.1 localhost.localdomain localhost
+::1 localhost.localdomain localhost ip6-localhost
+@end example
+
+@node Kernel
+@section Kernel
+
+Kernel isn't managed under the main repositories, even though you could package
+one for your personal use. Here is an @url{https://github.com/cemkeylan/kiss-repository/tree/master/personal/linux, example kernel package},
+which you will need to reconfigure for your specific setup if you want to make
+use of it.
+
+@subsection Obtaining the kernel sources
+
+You can visit the https://kernel.org website to choose a kernel that you want
+to install. Though only the latest stable and longterm (LTS) versions are
+supported.
+
+@example
+Download the kernel and extract it
+$ wget https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.7.6.tar.xz
+$ tar xf linux-5.7.6.tar.xz
+
+Change directory into the kernel sources
+$ cd linux-5.7.6
+@end example
+
+@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{https://github.com/E5ten, E5ten}. You will need to obtain and
+apply the patch in the kernel source directory.
+
+@example
+$ wget https://dl.carbslinux.org/distfiles/kernel-no-perl.patch
+$ patch -p1 < kernel-no-perl.patch
+@end example
+
+@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}
+to learn more about the matter. Overall, Gentoo Wiki is a good place to learn
+about configuration according to your hardware. The following will assume a
+monolithic kernel.
+
+@example
+$ make menuconfig
+$ make
+$ install -Dm755 $(make -s image_name) /boot/vmlinuz-linux
+@end example
+
+@node Making your system bootable
+@section Making your system bootable
+
+In order to be able to boot your fresh system, wou will need an init-daemon,
+init-scripts and a bootloader. The init daemon is already provided by busybox,
+but you can optionally change it.
+
+@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
+
+@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
+
+@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 https://github.com/cemkeylan/genfstab/raw/master/genfstab
+$ chmod +x genfstab
+$ ./genfstab -U /mnt >> /mnt/etc/fstab
+@end example
+
+@node Post-installation
+@section Post-installation
+
+The base installation is now complete, you can now fine tune your system
+according to your needs. Rest of these instructions are completely optional.
+
+@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 https://github.com/kisslinux/community $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.
diff --git a/install.txt b/install.txt
deleted file mode 100644
index d068a67..0000000
--- a/install.txt
+++ /dev/null
@@ -1,475 +0,0 @@
-Installation Instructions
-================================================================================
-
-This post will guide you step-by-set in order to install Carbs Linux. You can
-obtain these instructions for offline use, the plaintext version can be found on
-https://carbslinux.org/docs/install.txt
-
-
-TABLE OF CONTENTS
---------------------------------------------------------------------------------
-
-- Downloading and getting ready to chroot [1.0]
- - Download [1.1]
- - Check the integrity of the tarball (Recommended) [1.2]
- - Verify the signature [1.3]
- - Extracting the tarball [1.4]
- - Obtain the chroot helper [1.5]
-- Chroot [2.0]
- - Updating packages (optional) [2.1]
- - Installing packages [2.2]
- - Essential software [2.3]
- - Obtaining the documentation (optional) [2.4]
-- System Configuration [3.0]
- - Configuring hostname (recommended) [3.1]
- - Setting up the hosts file (optional) [3.2]
- - Generating fstab [3.3]
-- Kernel [4.0]
- - Obtaining the kernel sources. [4.1]
- - Installing dependencies [4.2]
- - Compiling the kernel [4.3]
-- Making your system bootable [5.0]
- - Installing a bootloader [5.1]
- - Installing init scripts [5.2]
-- Post-installation [6.0]
- - Acquiring kiss repositories [6.1]
-
-
-
-[1.0] Downloading and getting ready to chroot
---------------------------------------------------------------------------------
-
-To install Carbs Linux, you will need a Live Linux ISO. For that purpose, you
-can obtain a Gentoo or Void Linux live image. You can follow their instructions
-to boot and setup your network.
-
-You will need the following programs in order to install Carbs Linux:
-- tar
-- wget (or curl)
-- xz
-- some form of base utilities (coreutils, sbase, busybox, etc.)
-
-Rest of the instructions assume that you have set all of these up, and will
-continue on that point.
-
-
-[1.1] Download
---------------------------------------------------------------------------------
-
-First, we need to download the rootfs tarball. You can do the following in order
-to obtain the rootfs. If you are using an i686 machine, replace the 'x86_64'
-with 'i686'.
-
- +--------------------------------------------------------------------------+
- | |
- | $ wget https://dl.carbslinux.org/releases/x86_64/carbs-rootfs.tar.xz |
- | |
- +--------------------------------------------------------------------------+
-
-We can then check the integrity of the tarball and do a signature verification.
-Even though these are optional, they are highly recommended.
-
-
-[1.2] Check the integrity of the tarball (Recommended)
---------------------------------------------------------------------------------
-
-All of the releases are saved in a single file named 'sha256sums.txt'. You can
-either verify manually, or you can run the following for a single step
-verification.
-
- +-----------------------------------------------------------------------------+
- | |
- | $ wget https://dl.carbslinux.org/releases/x86_64/carbs-rootfs.tar.xz.sha256 |
- | |
- | $ sha256sum -c carbs-rootfs.tar.xz.sha256 |
- | |
- | This should produce the following (or a similar) output: |
- | carbs-rootfs.tar.xz: OK |
- | |
- +-----------------------------------------------------------------------------+
-
-
-[1.3] Verify the signature
---------------------------------------------------------------------------------
-
-It is highly recommended to verify the signature of the tarball. You will need
-GPG for this.
-
- +--------------------------------------------------------------------------+
- | |
- | $ wget https://carbslinux.org/releases/carbs-rootfs.tar.xz.sig |
- | |
- | $ gpg --recv-keys FF484BDFEFCEF8FF |
- | |
- | $ gpg --verify carbs-rootfs.tar.xz.sig |
- | |
- +--------------------------------------------------------------------------+
-
-
-[1.4] Extracting the tarball
---------------------------------------------------------------------------------
-
-You will need to extract the tarball to your desired location. For partitioning,
-you can follow this guide[1]. This will assume that you will be mounting your
-root partition to '/mnt'.
-
- +--------------------------------------------------------------------------+
- | |
- | $ mount /dev/sdx1 /mnt |
- | |
- | $ tar xf carbs-rootfs.tar.xz -C /mnt |
- | |
- +--------------------------------------------------------------------------+
-
-
-[1.5] Obtain the chroot helper
---------------------------------------------------------------------------------
-
-You can obtain the cpt-chroot script in order to do a simple chroot into your
-new root filesystem.
-
- +--------------------------------------------------------------------------+
- | |
- | $ wget https://dl.carbslinux.org/distfiles/cpt-chroot |
- | $ chmod a+x cpt-chroot |
- | |
- +--------------------------------------------------------------------------+
-
-
-[2.0] Chroot
---------------------------------------------------------------------------------
-
-Chroot into Carbs Linux!
-
- +--------------------------------------------------------------------------+
- | |
- | $ ./cpt-chroot /mnt |
- | |
- +--------------------------------------------------------------------------+
-
-
-[2.1] Updating packages (optional)
---------------------------------------------------------------------------------
-
-It is good practice to make sure your system is up to date, especially before
-building new packages. If there is an update for the package manager you will
-need to update twice.
-
- +--------------------------------------------------------------------------+
- | |
- | $ cpt update |
- | |
- +--------------------------------------------------------------------------+
- | |
- | If the package manager is updated, run the same command again. |
- | $ cpt update |
- | |
- +--------------------------------------------------------------------------+
-
-
-[2.2] 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.
-
- +--------------------------------------------------------------------------+
- | |
- | $ cpt build package |
- | $ cpt install package |
- | |
- +--------------------------------------------------------------------------+
-
-
-[2.3] Essential software
---------------------------------------------------------------------------------
-
-Here is a list of software that you might want to have on your system.
-
- BOOTLOADERS
- - efibootmgr
- - grub
- FILESYSTEMS
- - e2fsprogs
- - dosfstools
- - ntfs-3g
- NETWORKING
- - dhcpcd[2]
- - wpa_supplicant
- TEXT EDITORS
- - nano
- - vim
- - neatvi
- - nvi
- - emacs
- - emacs-nox (terminal-only version of emacs)
- - mg (micro gnuemacs)
- USER SHELLS
- - bash
- - dash
- - zsh
- - 9base (rc shell)
- DEVICE MANAGEMENT
- - eudev
- COREUTILS
- - sbase
- DOCUMENTATION
- - carbs-docs [2.4]
- - man-pages
- - man-pages-posix
- OTHER
- - git
-
-
-[2.4] Obtaining the documentation (optional)
---------------------------------------------------------------------------------
-
-All the documentation for Carbs Linux (including this installation manual) can
-be obtained to be viewed offline.
-
- +--------------------------------------------------------------------------+
- | |
- | Install the documentation. |
- | $ cpt b carbs-docs && cpt i carbs-docs |
- | |
- | 'docs' tool can be used in order to crawl through the documentation. |
- | |
- | Following command can be used in order to view this installation guide |
- | through a pager. |
- | |
- | $ docs install |
- | |
- +--------------------------------------------------------------------------+
-
-
-[3.0] System Configuration
---------------------------------------------------------------------------------
-
-After you have finished installing some extra packages, you can configure your
-system to your liking.
-
-
-[3.1] 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.
-
- +--------------------------------------------------------------------------+
- | |
- | $ echo your-hostname > /etc/hostname |
- | |
- +--------------------------------------------------------------------------+
-
-
-[3.2] Setting up the 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.
-
- +--------------------------------------------------------------------------+
- | |
- | 127.0.0.1 localhost.localdomain localhost |
- | ::1 localhost.localdomain localhost ip6-localhost |
- | |
- +--------------------------------------------------------------------------+
-
-
-[3.3] Generating fstab
---------------------------------------------------------------------------------
-
-You can use this POSIX sh variant for genfstab
-
-
-[4.0] Kernel
---------------------------------------------------------------------------------
-
-Kernel isn't managed under the main repositories, even though you could package
-one for your personal use. Here is an example kernel package, which you will
-need to reconfigure for your specific setup if you want to make use of it[3].
-
-
-[4.1] Obtaining the kernel sources.
---------------------------------------------------------------------------------
-
-You can visit the https://kernel.org website to choose a kernel that you want
-to install. Though only the latest stable and longterm (LTS) versions are
-supported.
-
- +--------------------------------------------------------------------------+
- | |
- | Download the kernel and extract it |
- | $ wget https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.7.6.tar.xz |
- | $ tar xf linux-5.7.6.tar.xz |
- | |
- | Change directory into the kernel sources |
- | $ cd linux-5.7.6 |
- | |
- +--------------------------------------------------------------------------+
-
-[4.2] Installing dependencies
---------------------------------------------------------------------------------
-
-In order to compile the kernel you will need to install some dependencies.
-
- +--------------------------------------------------------------------------+
- | |
- | You will need libelf to compile the kernel |
- | |
- | $ cpt b libelf && cpt i libelf |
- | |
- +--------------------------------------------------------------------------+
- | |
- | In order to configure the kernel with a user interface, you will need |
- | ncurses to be installed on your system. |
- | |
- | $ cpt b ncurses && cpt i ncurses |
- | |
- +--------------------------------------------------------------------------+
-
-In the vanilla kernel sources, you need perl to compile the kernel, but it can
-be easily patched out. You will need to apply the following patch. Patch was
-written by E5ten[4].
-
- +--------------------------------------------------------------------------+
- | |
- | Obtain the patch by downloading it. |
- | |
- | $ wget https://dl.carbslinux.org/distfiles/kernel-no-perl.patch |
- | |
- | Apply the patch. |
- | |
- | $ patch -p1 < kernel-no-perl.patch |
- | |
- +--------------------------------------------------------------------------+
-
-
-[4.3] Compiling the kernel
---------------------------------------------------------------------------------
-
-Next step is configuring and building the kernel. You can check Gentoo's kernel
-configuration guide[5] to learn more about the matter. Overall, Gentoo Wiki is a
-good place to learn about configuration according to your hardware.
-
- +--------------------------------------------------------------------------+
- | Configure and build the kernel |
- +--------------------------------------------------------------------------+
- | |
- | $ make menuconfig |
- | $ make |
- | |
- +--------------------------------------------------------------------------+
- | Install the kernel |
- +--------------------------------------------------------------------------+
- | |
- | $ install -Dm755 $(make -s image_name) /boot/vmlinuz-linux |
- | |
- +--------------------------------------------------------------------------+
-
-
-[5.0] Making your system bootable
---------------------------------------------------------------------------------
-
-In order to be able to boot your fresh system, wou will need an init-daemon,
-init-scripts and a bootloader. The init daemon is already provided by busybox,
-but you can optionally change it.
-
-
-[5.1] 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 |
- +--------------------------------------------------------------------------+
- | |
- | $ cpt b grub && cpt i grub |
- | $ grub-install --target=i386-pc /dev/sdX |
- | $ grub-mkconfig -o /boot/grub/grub.cfg |
- | |
- +--------------------------------------------------------------------------+
- | GRUB UEFI installation |
- +--------------------------------------------------------------------------+
- | |
- | $ cpt b efibootmgr && cpt i efibootmgr |
- | $ cpt b grub && cpt i grub |
- | |
- | $ grub-install --target=x86_64-efi \ |
- | --efi-directory=esp \ |
- | --bootloader-id=CarbsLinux |
- | |
- | $ grub-mkconfig -o /boot/grub/grub.cfg |
- | |
- +--------------------------------------------------------------------------+
-
-
-[5.2] Installing init scripts
---------------------------------------------------------------------------------
-
-Only thing left to do is installing the init-scripts, and now you are ready to
-boot your system!
-
- +--------------------------------------------------------------------------+
- | |
- | $ cpt b carbs-init && cpt i carbs-init |
- | |
- +--------------------------------------------------------------------------+
-
-
-[6.0] 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.
-
-
-[6.1] Acquiring kiss repositories
---------------------------------------------------------------------------------
-
-Most kiss repositories can only be obtained through git, but it isn't installed
-by default. You'll need to install it:
-
- +--------------------------------------------------------------------------+
- | |
- | $ cpt b git && cpt i git |
- | |
- +--------------------------------------------------------------------------+
-
-
-After installing git, you can clone a repository, and add it to your path:
-
- +--------------------------------------------------------------------------+
- | KISS Community Repository |
- +--------------------------------------------------------------------------+
- | |
- | $ git clone https://github.com/kisslinux/community |
- | $ export CPT_PATH=$CPT_PATH:$PWD/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. |
- | |
- +--------------------------------------------------------------------------+
-
-
-You can also lookup other repositories on GitHub, by searching the 'cpt-repo'
-tag, or looking it up on the KISS Wiki page for repositories[6].
-
-
-Footnotes
---------------------------------------------------------------------------------
-[1]: https://wiki.archlinux.org/index.php/Partitioning
-[2]: busybox also provides udhcpc which can be used to configure dynamic IP
-[3]: https://github.com/cemkeylan/kiss-repository/tree/master/personal/linux
-[4]: https://github.com/E5ten
-[5]: https://wiki.gentoo.org/wiki/Kernel/Configuration
-[6]: https://k1ss.org/wiki/community/repositories
diff --git a/top.texi b/top.texi
new file mode 100644
index 0000000..7a6c930
--- /dev/null
+++ b/top.texi
@@ -0,0 +1,73 @@
+\input texinfo
+
+@c Start of header
+@settitle Carbs Linux User Manual
+@setfilename carbslinux.info
+
+@copying
+Copyright @copyright{} 2020 Cem Keylan
+
+Licensed under Gnu Free Documentation License.
+@end copying
+
+@titlepage
+@title Carbs Linux User Manual
+
+@page
+@vskip 0pt plus 1fill
+@insertcopying
+@end titlepage
+
+@ifnottex
+@node Top
+@top Carbs Linux User Manual
+
+This is the full documentation of 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 which can be read
+by either running @code{info carbslinux} or reading @file{/usr/share/doc/carbslinux.txt}
+with your favorite pager. You can install either the @command{info} or @command{texinfo}
+for doing the first.
+@end ifhtml
+
+@end ifnottex
+
+@menu
+* Installation:: Installing Carbs Linux
+* Package Manager:: Carbs Linux Packaging Tools
+* Init System:: Configuring the init system
+
+@detailmenu
+--- Detailed Menu Listing ---
+
+Overview of 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
+
+Overview of Package manager
+
+* Usage:: Using Carbs Packaging Tools
+* Packaging System:: More detail on creating packages
+* Rsync Repositories:: Information on using or creating rsync repositories
+@end detailmenu
+@end menu
+
+@include install.texi
+@include cpt.texi
+@include init.texi
+
+
+@bye