diff options
| -rw-r--r-- | Makefile | 21 | ||||
| -rw-r--r-- | README | 7 | ||||
| -rw-r--r-- | cpt.texi | 359 | ||||
| -rw-r--r-- | extMakefile | 13 | ||||
| -rw-r--r-- | init.texi | 114 | ||||
| -rw-r--r-- | install.texi | 426 | ||||
| -rw-r--r-- | install.txt | 475 | ||||
| -rw-r--r-- | top.texi | 73 |
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 @@ -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 |