From 40eb4e45d48337dfcd748540fe25c5eb684e911d Mon Sep 17 00:00:00 2001 From: Cem Keylan Date: Wed, 9 Sep 2020 17:51:04 +0300 Subject: Install docs --- build | 3 + docs/docs/Changing-Init-Program.html | 92 +++++++++ docs/docs/Chroot.html | 206 +++++++++++++++++++++ docs/docs/Configuring-Init.html | 122 ++++++++++++ docs/docs/Init-System.html | 66 +++++++ docs/docs/Installation.html | 71 +++++++ docs/docs/Kernel.html | 114 ++++++++++++ docs/docs/Making-your-system-bootable.html | 106 +++++++++++ docs/docs/Package-Manager.html | 70 +++++++ docs/docs/Packaging-System.html | 197 ++++++++++++++++++++ docs/docs/Post_002dinstallation.html | 71 +++++++ docs/docs/Preparing-Environment.html | 129 +++++++++++++ docs/docs/Rsync-Repositories.html | 101 ++++++++++ ...ng-up-an-rsync-repository-for-distribution.html | 99 ++++++++++ docs/docs/System-Configuration.html | 77 ++++++++ docs/docs/Usage.html | 113 +++++++++++ docs/docs/cpt_002dalternatives.html | 82 ++++++++ docs/docs/cpt_002dbuild.html | 65 +++++++ docs/docs/index.html | 108 +++++++++++ src/docs/Changing-Init-Program.html | 92 +++++++++ src/docs/Chroot.html | 206 +++++++++++++++++++++ src/docs/Configuring-Init.html | 122 ++++++++++++ src/docs/Init-System.html | 66 +++++++ src/docs/Installation.html | 71 +++++++ src/docs/Kernel.html | 114 ++++++++++++ src/docs/Making-your-system-bootable.html | 106 +++++++++++ src/docs/Package-Manager.html | 70 +++++++ src/docs/Packaging-System.html | 197 ++++++++++++++++++++ src/docs/Post_002dinstallation.html | 71 +++++++ src/docs/Preparing-Environment.html | 129 +++++++++++++ src/docs/Rsync-Repositories.html | 101 ++++++++++ ...ng-up-an-rsync-repository-for-distribution.html | 99 ++++++++++ src/docs/System-Configuration.html | 77 ++++++++ src/docs/Usage.html | 113 +++++++++++ src/docs/cpt_002dalternatives.html | 82 ++++++++ src/docs/cpt_002dbuild.html | 65 +++++++ src/docs/index.html | 108 +++++++++++ 37 files changed, 3781 insertions(+) create mode 100644 docs/docs/Changing-Init-Program.html create mode 100644 docs/docs/Chroot.html create mode 100644 docs/docs/Configuring-Init.html create mode 100644 docs/docs/Init-System.html create mode 100644 docs/docs/Installation.html create mode 100644 docs/docs/Kernel.html create mode 100644 docs/docs/Making-your-system-bootable.html create mode 100644 docs/docs/Package-Manager.html create mode 100644 docs/docs/Packaging-System.html create mode 100644 docs/docs/Post_002dinstallation.html create mode 100644 docs/docs/Preparing-Environment.html create mode 100644 docs/docs/Rsync-Repositories.html create mode 100644 docs/docs/Setting-up-an-rsync-repository-for-distribution.html create mode 100644 docs/docs/System-Configuration.html create mode 100644 docs/docs/Usage.html create mode 100644 docs/docs/cpt_002dalternatives.html create mode 100644 docs/docs/cpt_002dbuild.html create mode 100644 docs/docs/index.html create mode 100644 src/docs/Changing-Init-Program.html create mode 100644 src/docs/Chroot.html create mode 100644 src/docs/Configuring-Init.html create mode 100644 src/docs/Init-System.html create mode 100644 src/docs/Installation.html create mode 100644 src/docs/Kernel.html create mode 100644 src/docs/Making-your-system-bootable.html create mode 100644 src/docs/Package-Manager.html create mode 100644 src/docs/Packaging-System.html create mode 100644 src/docs/Post_002dinstallation.html create mode 100644 src/docs/Preparing-Environment.html create mode 100644 src/docs/Rsync-Repositories.html create mode 100644 src/docs/Setting-up-an-rsync-repository-for-distribution.html create mode 100644 src/docs/System-Configuration.html create mode 100644 src/docs/Usage.html create mode 100644 src/docs/cpt_002dalternatives.html create mode 100644 src/docs/cpt_002dbuild.html create mode 100644 src/docs/index.html diff --git a/build b/build index 74c7d9b..13160ea 100755 --- a/build +++ b/build @@ -125,6 +125,9 @@ main() { genrss index news index.html > src/news.xml genrss src/blog > src/rss.xml + # Generate htmldocs + make -s -C texidocs DESTDIR="$PWD/src/docs" htmldocs + # Generate pages genpages } diff --git a/docs/docs/Changing-Init-Program.html b/docs/docs/Changing-Init-Program.html new file mode 100644 index 0000000..60bf1b3 --- /dev/null +++ b/docs/docs/Changing-Init-Program.html @@ -0,0 +1,92 @@ + + + + + + +Changing Init Program (Carbs Linux User Manual) + + + + + + + + + + + + + + + +
+

+Previous: , Up: Init System  

+
+
+

3.2 Changing Init Program

+ +

By default, Carbs Linux comes preinstalled with busybox-init, but this +can easily be replaced without any issues. Currently, available init systems are: +

+ + +

This example is for runit, but it will work with all init systems packaged in the +distribution repositories. See cpt-alternatives +

+
+
$ cpt a runit /usr/bin/init
+$ cpt a runit /usr/bin/poweroff
+$ cpt a runit /usr/bin/reboot
+
+ +

3.2.1 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. +

+
+
busybox
+

$ busybox reboot +

+
runit
+

$ runit-init 6 +

+
shinit/sinit
+

$ kill -s INT 1 +

+
+ + + + + + + diff --git a/docs/docs/Chroot.html b/docs/docs/Chroot.html new file mode 100644 index 0000000..07c41b5 --- /dev/null +++ b/docs/docs/Chroot.html @@ -0,0 +1,206 @@ + + + + + + +Chroot (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Next: , Previous: , Up: Installation  

+
+
+

1.2 Chroot

+ +

Chroot into Carbs Linux! +

+
+
$ ./cpt-chroot /mnt
+
+ +

1.2.1 Setting up repositories

+ +

Newest tarballs do not come with repositories, so you will need to manually +obtain them, and set your CPT_PATH environment variable. Carbs Linux +repositories can either be obtained by git or 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 +git itself. +

+

The following guide will assume that you put the repositories into +~/repos/ directory, but you can put the repositories into any directory +you want. So go ahead and create that directory. mkdir -p $HOME/repos. +

+

1.2.1.1 Obtaining from rsync

+ +

Carbs Linux rsync repositories live in rsync://carbslinux.org/repo. In +order to obtain it, run the following: +

+
+
$ rsync -avc rsync://carbslinux.org/repo $HOME/repos/carbs
+
+ +

1.2.1.2 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. +

+ + +
+
$ git clone git://git.carbslinux.org/repository $HOME/repos/carbs
+
+ +

1.2.1.3 Making the package manager use the repositories

+ +

In your shell’s configuration file, or in your ~/.profile file, add the +following lines: +

+
+
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
+
+ +

1.2.2 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. +

+
+
$ cpt update
+
+ +

1.2.3 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
+
+ +

1.2.4 Essential Software

+ +

Here is a list of software that you might want to have on your system. +

+

BOOTLOADERS +

+

FILESYSTEMS +

+

NETWORKING +

+

TEXT EDITORS +

+

USER SHELLS +

+

POSIX BASE UTILITIES +

+

DOCUMENTATION +

+ +

1.2.5 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. +

+
+
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
+
+ +
+
+

+Next: , Previous: , Up: Installation  

+
+ + + + + diff --git a/docs/docs/Configuring-Init.html b/docs/docs/Configuring-Init.html new file mode 100644 index 0000000..e90cd74 --- /dev/null +++ b/docs/docs/Configuring-Init.html @@ -0,0 +1,122 @@ + + + + + + +Configuring Init (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Next: , Up: Init System  

+
+
+

3.1 Configuring Init

+ +

There are three ways you can change the behaviour of the init system. Those are: +

+
    +
  1. Kernel Command Line +
  2. /etc/init/rc.conf file +
  3. Init Hooks +
+ +

3.1.1 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. +

+
+
BOOT_IMAGE=/boot/vmlinuz root=/dev/sda2 rw loglevel=3 quiet
+
+ +

This command line will be parsed to set the following variables: +

+
+
BOOT_IMAGE=/boot/vmlinuz
+root=/dev/sda2
+rw=1
+loglevel=3
+quiet=1
+
+ +

Some of these variables, such as rw/ro, loglevel, and +quiet, will be used by the init system to change the behaviour of the +startup. +

+

3.1.2 /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. +

+

3.1.3 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 /etc/init directory with the +hook name as the suffix. For example, a boot script will be placed as +/etc/init/my-hook.boot. Currently, there are 4 hooks that the user can use. +

+
+
early-boot
+

Run after pseudo-filesystems are mounted. +

+
boot
+

Run before the boot stage is completed. +

+
pre.shutdown
+

Run first when shutting down. +

+
post.shutdown
+

Run just before the system is halted. +

+
+ +
+
+

+Next: , Up: Init System  

+
+ + + + + diff --git a/docs/docs/Init-System.html b/docs/docs/Init-System.html new file mode 100644 index 0000000..cf596dd --- /dev/null +++ b/docs/docs/Init-System.html @@ -0,0 +1,66 @@ + + + + + + +Init System (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Previous: , Up: Top  

+
+
+

3 Init System

+ +

Carbs Linux init scripts are run by the init daemon (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. +

+ + + +
• Configuring Init   +
• Changing Init Program   +
+ + + + + + diff --git a/docs/docs/Installation.html b/docs/docs/Installation.html new file mode 100644 index 0000000..48c83c3 --- /dev/null +++ b/docs/docs/Installation.html @@ -0,0 +1,71 @@ + + + + + + +Installation (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Next: , Previous: , Up: Top  

+
+
+

1 Installation

+ +

These are the step-by-step instructions for installing Carbs Linux. +

+ + + + + + + +
• 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 +
+ + + + + + diff --git a/docs/docs/Kernel.html b/docs/docs/Kernel.html new file mode 100644 index 0000000..eca1794 --- /dev/null +++ b/docs/docs/Kernel.html @@ -0,0 +1,114 @@ + + + + + + +Kernel (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Next: , Previous: , Up: Installation  

+
+
+

1.4 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. +

+

1.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
+
+ +

1.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. If you want to configure using the menu +interface you will also need ncurses. +

+
+
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
+
+ +

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. You will need to obtain and +apply the patch in the kernel source directory. +

+
+
$ wget https://dl.carbslinux.org/distfiles/kernel-no-perl.patch
+$ patch -p1 < kernel-no-perl.patch
+
+ +

1.4.3 Compiling the kernel

+ +

Next step is configuring and building the kernel. You can check Gentoo’s 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. +

+
+
$ make menuconfig
+$ make
+$ install -Dm755 $(make -s image_name) /boot/vmlinuz-linux
+
+ +
+
+

+Next: , Previous: , Up: Installation  

+
+ + + + + diff --git a/docs/docs/Making-your-system-bootable.html b/docs/docs/Making-your-system-bootable.html new file mode 100644 index 0000000..0387eb4 --- /dev/null +++ b/docs/docs/Making-your-system-bootable.html @@ -0,0 +1,106 @@ + + + + + + +Making your system bootable (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Next: , Previous: , Up: Installation  

+
+
+

1.5 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. +

+

1.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
+
+ +

1.5.2 Installing init scripts

+ +

Only thing left to do is installing the init-scripts, and now you are almost +ready to boot your system! +

+
+
$ cpt b carbs-init && cpt i carbs-init
+
+ +

1.5.3 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: +

+
+
$ wget https://github.com/cemkeylan/genfstab/raw/master/genfstab
+$ chmod +x genfstab
+$ ./genfstab -U /mnt >> /mnt/etc/fstab
+
+ + + + + + diff --git a/docs/docs/Package-Manager.html b/docs/docs/Package-Manager.html new file mode 100644 index 0000000..04173a6 --- /dev/null +++ b/docs/docs/Package-Manager.html @@ -0,0 +1,70 @@ + + + + + + +Package Manager (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Next: , Previous: , Up: Top  

+
+
+

2 Package Manager

+ +

Carbs Linux uses its own package managing toolchain named cpt. It is a +fork of the kiss package manager. Unlike +kiss, however, its main goal is being easily extendable. Instead of being +a single file package manager, it revolves around the shell library cpt-lib, +and many tools that wrap around it. +

+ + + + + +
• Usage   +
• Packaging System   +
• Rsync Repositories   +
+ + + + + + diff --git a/docs/docs/Packaging-System.html b/docs/docs/Packaging-System.html new file mode 100644 index 0000000..4fda504 --- /dev/null +++ b/docs/docs/Packaging-System.html @@ -0,0 +1,197 @@ + + + + + + +Packaging System (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Next: , Previous: , Up: Package Manager  

+
+
+

2.2 Packaging System

+ +

A package is formed of several files, these are: +

+ +

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. +

+

2.2.1 build

+ +

Typically 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 build file is a POSIX shell script (for portability’s sake), build +files can be any executable program from binary programs to 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 ($#) +

+
    +
  1. Location of the package directory (DESTDIR) +
  2. Package version +
  3. System architecture +
+ +

2.2.2 sources

+ +

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 soures file; src dest. The +dest parameter is optional. It is the directory that the source will be +placed in. Here is the sources file for the gst-plugins package: +

+
+
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
+
+ +

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 curl. +

+

If the source is a git repository, it shall be prefixed with a 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, +

+
+
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'
+
+ +

Other files are assumed to be residing in the package directory. They should be +added with their paths relative to the package directory. +

+ +

2.2.3 checksums

+ +

checksums file is generated by the 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. +

+

2.2.4 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. +

+
+
1.3.2 1
+
+ +

The version should always match to the number of the upstream release. For +drastic changes that require a rebuild Those can be, +

+ + +

When a version bump occurs, the release should be reset to 1. +

+

2.2.5 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 CPT_TEST is set to 1, or the build is run +with the -t or --test options. So, a package package could have +the following depends file: +

+
+
linux-headers make
+python        test
+zlib
+
+ +

2.2.6 post-install

+ +

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 CPT_ROOT). +

+

2.2.7 message

+ +

This plaintext file will be outputted with cat after every package is +installed. +

+

2.2.8 test

+ +

Test files are mainly for the repository maintainer to test the packages, and +will only run if the user has the CPT_TEST variable set, or the build is +run with the -t or --test options. This script is run on the +build directory. It is run right after the build script is finished. +

+
+
+

+Next: , Previous: , Up: Package Manager  

+
+ + + + + diff --git a/docs/docs/Post_002dinstallation.html b/docs/docs/Post_002dinstallation.html new file mode 100644 index 0000000..19f7b21 --- /dev/null +++ b/docs/docs/Post_002dinstallation.html @@ -0,0 +1,71 @@ + + + + + + +Post-installation (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Previous: , Up: Installation  

+
+
+

1.6 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. +

+

1.6.1 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. +

+
+
$ git clone https://github.com/kisslinux/community $HOME/repos/kiss-community
+$ export CPT_PATH=$CPT_PATH:$HOME/repos/kiss-community/community
+
+ +

NOTE: There are lots of packages on the KISS community repository that are also +on Carbs Linux main repository. I would advise giving lower priority to the KISS +community repository as it may affect other packages that you might install. +

+ + + + diff --git a/docs/docs/Preparing-Environment.html b/docs/docs/Preparing-Environment.html new file mode 100644 index 0000000..476299d --- /dev/null +++ b/docs/docs/Preparing-Environment.html @@ -0,0 +1,129 @@ + + + + + + +Preparing Environment (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Next: , Up: Installation  

+
+
+

1.1 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: +

+ +

Rest of these instructions will assume that you have set all of these up, and +will continue on that point. +

+

1.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 thought these are optional, they are highly recommended. +

+

1.1.2 Check the integrity of the tarball (Recommended)

+ +

All of the releases are saved in a single file named sha256sums.txt, but the +latest release is saved on carbs-rootfs.tar.xz.sha256. You can acquire and +verify the tarball. +

+
+
$ wget https://dl.carbslinux.org/releases/x86_64/carbs-rootfs.tar.xz.sha256
+$ sha256sum -c carbs-rootfs.tar.xz.sha256
+
+ +

1.1.3 Verify the signature

+ +

It is highly recommended to verify the signature of the tarball. You will need +GPG for this. +

+
+
$ wget https://dl.carbslinux.org/releases/carbs-rootfs.tar.xz.sig
+$ gpg --recv-keys FF484BDFEFCEF8FF
+$ gpg --verify carbs-rootfs.tar.xz.sig
+
+ +

1.1.4 Extracting the tarball

+ +

You will need to extract the tarball to your desired location. For partitioning, +you can follow this guide. +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.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
+
+ +
+
+

+Next: , Up: Installation  

+
+ + + + + diff --git a/docs/docs/Rsync-Repositories.html b/docs/docs/Rsync-Repositories.html new file mode 100644 index 0000000..847b22c --- /dev/null +++ b/docs/docs/Rsync-Repositories.html @@ -0,0 +1,101 @@ + + + + + + +Rsync Repositories (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Previous: , Up: Package Manager  

+
+
+

2.3 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: +

+
+
rsync://carbslinux.org/repo/core
+
+ +

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 .rsync and .rsync_root. Here is the Carbs Linux +rsync repository structure. +

+
+
           /
+   -----------------
+  |                |
+.rsync           core/
+          ----------------
+          |              |
+        .rsync      .rsync_root
+
+ +

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: +

+
+
/.rsync:           rsync://carbslinux.org/repo
+/core/.rsync:      rsync://carbslinux.org/repo/core
+/core/.rsync_root: ..
+
+ +

The .rsync_root file on the core repository points to the upper directory. +If a .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 .rsync file, this means that this +is an individual repository, and the package manager will fetch accordingly. +

+ + +
• Setting up an rsync repository for distribution   +
+ + + + + + diff --git a/docs/docs/Setting-up-an-rsync-repository-for-distribution.html b/docs/docs/Setting-up-an-rsync-repository-for-distribution.html new file mode 100644 index 0000000..2262723 --- /dev/null +++ b/docs/docs/Setting-up-an-rsync-repository-for-distribution.html @@ -0,0 +1,99 @@ + + + + + + +Setting up an rsync repository for distribution (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Up: Rsync Repositories  

+
+
+

2.3.1 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. +

+
    #!/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
+
+

You can then create an rsync user for serving the repositories. +

+
+
$ adduser -SD rsync
+
+ +

Create /etc/rsyncd.conf and a service configuration as well. +

+
+    uid = rsync
+    gid = rsync
+    address = example.com
+    max connections = 10
+    use chroot = yes
+
+    [repo]
+        path = /pub/share/repo
+        comment = My repository
+
+

Create a service file at /etc/sv/rsync/run (runit): +

+
+
#!/bin/sh
+exec rsync --daemon --no-detach
+
+ + + + + diff --git a/docs/docs/System-Configuration.html b/docs/docs/System-Configuration.html new file mode 100644 index 0000000..1b8d78b --- /dev/null +++ b/docs/docs/System-Configuration.html @@ -0,0 +1,77 @@ + + + + + + +System Configuration (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Next: , Previous: , Up: Installation  

+
+
+

1.3 System Configuration

+ +

After you have finished installing some extra packages, you can configure your +system to your liking. +

+

1.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
+
+ +

1.3.2 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. +

+
+
127.0.0.1  localhost.localdomain localhost
+::1        localhost.localdomain localhost ip6-localhost
+
+ + + + + + diff --git a/docs/docs/Usage.html b/docs/docs/Usage.html new file mode 100644 index 0000000..84c1283 --- /dev/null +++ b/docs/docs/Usage.html @@ -0,0 +1,113 @@ + + + + + + +Usage (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Next: , Up: Package Manager  

+
+
+

2.1 Usage

+

cpt is formed of many tools combined in a single environment, similar +to git. When you run cpt without any arguments, it will show +all available tools and their explanations. Here is an example call with extra +scripts on my system: +

+
+
-> 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
+
+ + + + +
• cpt-alternatives   +
• cpt-build   +
+ +
+
+

+Next: , Up: Package Manager  

+
+ + + + + diff --git a/docs/docs/cpt_002dalternatives.html b/docs/docs/cpt_002dalternatives.html new file mode 100644 index 0000000..1730bac --- /dev/null +++ b/docs/docs/cpt_002dalternatives.html @@ -0,0 +1,82 @@ + + + + + + +cpt-alternatives (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Next: , Up: Usage  

+
+
+

2.1.1 cpt-alternatives

+ +

You can list and swap to alternatives using cpt-alternatives, or +cpt a for short. When run without alternatives, it will list +alternatives. It can read from standard input if - is given as an +argument. +

+

2.1.1.1 Examples

+ +

List alternatives +

+
+
$ cpt-alternatives
+ncurses /usr/bin/clear
+ncurses /usr/bin/reset
+
+ +

Swap to clear from ncurses. +

+
+
$ cpt-alternatives ncurses /usr/bin/clear
+-> Swapping '/usr/bin/clear' from 'busybox' to 'ncurses'
+
+ +

Swap in bulk (all of sbase). +

+
+
$ cpt a | grep ^sbase | cpt a -
+
+ + + + + + diff --git a/docs/docs/cpt_002dbuild.html b/docs/docs/cpt_002dbuild.html new file mode 100644 index 0000000..e7d3712 --- /dev/null +++ b/docs/docs/cpt_002dbuild.html @@ -0,0 +1,65 @@ + + + + + + +cpt-build (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Previous: , Up: Usage  

+
+
+

2.1.2 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. +

+

2.1.2.1 Options

+

cpt-build will accept the following options: +

+ + + + + + + diff --git a/docs/docs/index.html b/docs/docs/index.html new file mode 100644 index 0000000..96175c0 --- /dev/null +++ b/docs/docs/index.html @@ -0,0 +1,108 @@ + + + + + + +Top (Carbs Linux User Manual) + + + + + + + + + + + + + + +

Carbs Linux User Manual

+ + + +
+

+Next:  

+
+
+

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. +

+ +

This documentation is also available in the distribution which can be read +by either running info carbslinux or reading /usr/share/doc/carbslinux.txt +with your favorite pager. You can install either the info or texinfo +for doing the first. +

+ + + + + + + + + + + + + + +
• Installation  Installing Carbs Linux +
• Package Manager  Carbs Linux Packaging Tools +
• Init System  Configuring the init system +
+
+
— 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 +
+ +
+
+

+Next:  

+
+ + + + + diff --git a/src/docs/Changing-Init-Program.html b/src/docs/Changing-Init-Program.html new file mode 100644 index 0000000..60bf1b3 --- /dev/null +++ b/src/docs/Changing-Init-Program.html @@ -0,0 +1,92 @@ + + + + + + +Changing Init Program (Carbs Linux User Manual) + + + + + + + + + + + + + + + +
+

+Previous: , Up: Init System  

+
+
+

3.2 Changing Init Program

+ +

By default, Carbs Linux comes preinstalled with busybox-init, but this +can easily be replaced without any issues. Currently, available init systems are: +

+ + +

This example is for runit, but it will work with all init systems packaged in the +distribution repositories. See cpt-alternatives +

+
+
$ cpt a runit /usr/bin/init
+$ cpt a runit /usr/bin/poweroff
+$ cpt a runit /usr/bin/reboot
+
+ +

3.2.1 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. +

+
+
busybox
+

$ busybox reboot +

+
runit
+

$ runit-init 6 +

+
shinit/sinit
+

$ kill -s INT 1 +

+
+ + + + + + + diff --git a/src/docs/Chroot.html b/src/docs/Chroot.html new file mode 100644 index 0000000..07c41b5 --- /dev/null +++ b/src/docs/Chroot.html @@ -0,0 +1,206 @@ + + + + + + +Chroot (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Next: , Previous: , Up: Installation  

+
+
+

1.2 Chroot

+ +

Chroot into Carbs Linux! +

+
+
$ ./cpt-chroot /mnt
+
+ +

1.2.1 Setting up repositories

+ +

Newest tarballs do not come with repositories, so you will need to manually +obtain them, and set your CPT_PATH environment variable. Carbs Linux +repositories can either be obtained by git or 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 +git itself. +

+

The following guide will assume that you put the repositories into +~/repos/ directory, but you can put the repositories into any directory +you want. So go ahead and create that directory. mkdir -p $HOME/repos. +

+

1.2.1.1 Obtaining from rsync

+ +

Carbs Linux rsync repositories live in rsync://carbslinux.org/repo. In +order to obtain it, run the following: +

+
+
$ rsync -avc rsync://carbslinux.org/repo $HOME/repos/carbs
+
+ +

1.2.1.2 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. +

+ + +
+
$ git clone git://git.carbslinux.org/repository $HOME/repos/carbs
+
+ +

1.2.1.3 Making the package manager use the repositories

+ +

In your shell’s configuration file, or in your ~/.profile file, add the +following lines: +

+
+
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
+
+ +

1.2.2 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. +

+
+
$ cpt update
+
+ +

1.2.3 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
+
+ +

1.2.4 Essential Software

+ +

Here is a list of software that you might want to have on your system. +

+

BOOTLOADERS +

+

FILESYSTEMS +

+

NETWORKING +

+

TEXT EDITORS +

+

USER SHELLS +

+

POSIX BASE UTILITIES +

+

DOCUMENTATION +

+ +

1.2.5 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. +

+
+
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
+
+ +
+
+

+Next: , Previous: , Up: Installation  

+
+ + + + + diff --git a/src/docs/Configuring-Init.html b/src/docs/Configuring-Init.html new file mode 100644 index 0000000..e90cd74 --- /dev/null +++ b/src/docs/Configuring-Init.html @@ -0,0 +1,122 @@ + + + + + + +Configuring Init (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Next: , Up: Init System  

+
+
+

3.1 Configuring Init

+ +

There are three ways you can change the behaviour of the init system. Those are: +

+
    +
  1. Kernel Command Line +
  2. /etc/init/rc.conf file +
  3. Init Hooks +
+ +

3.1.1 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. +

+
+
BOOT_IMAGE=/boot/vmlinuz root=/dev/sda2 rw loglevel=3 quiet
+
+ +

This command line will be parsed to set the following variables: +

+
+
BOOT_IMAGE=/boot/vmlinuz
+root=/dev/sda2
+rw=1
+loglevel=3
+quiet=1
+
+ +

Some of these variables, such as rw/ro, loglevel, and +quiet, will be used by the init system to change the behaviour of the +startup. +

+

3.1.2 /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. +

+

3.1.3 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 /etc/init directory with the +hook name as the suffix. For example, a boot script will be placed as +/etc/init/my-hook.boot. Currently, there are 4 hooks that the user can use. +

+
+
early-boot
+

Run after pseudo-filesystems are mounted. +

+
boot
+

Run before the boot stage is completed. +

+
pre.shutdown
+

Run first when shutting down. +

+
post.shutdown
+

Run just before the system is halted. +

+
+ +
+
+

+Next: , Up: Init System  

+
+ + + + + diff --git a/src/docs/Init-System.html b/src/docs/Init-System.html new file mode 100644 index 0000000..cf596dd --- /dev/null +++ b/src/docs/Init-System.html @@ -0,0 +1,66 @@ + + + + + + +Init System (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Previous: , Up: Top  

+
+
+

3 Init System

+ +

Carbs Linux init scripts are run by the init daemon (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. +

+ + + +
• Configuring Init   +
• Changing Init Program   +
+ + + + + + diff --git a/src/docs/Installation.html b/src/docs/Installation.html new file mode 100644 index 0000000..48c83c3 --- /dev/null +++ b/src/docs/Installation.html @@ -0,0 +1,71 @@ + + + + + + +Installation (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Next: , Previous: , Up: Top  

+
+
+

1 Installation

+ +

These are the step-by-step instructions for installing Carbs Linux. +

+ + + + + + + +
• 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 +
+ + + + + + diff --git a/src/docs/Kernel.html b/src/docs/Kernel.html new file mode 100644 index 0000000..eca1794 --- /dev/null +++ b/src/docs/Kernel.html @@ -0,0 +1,114 @@ + + + + + + +Kernel (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Next: , Previous: , Up: Installation  

+
+
+

1.4 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. +

+

1.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
+
+ +

1.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. If you want to configure using the menu +interface you will also need ncurses. +

+
+
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
+
+ +

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. You will need to obtain and +apply the patch in the kernel source directory. +

+
+
$ wget https://dl.carbslinux.org/distfiles/kernel-no-perl.patch
+$ patch -p1 < kernel-no-perl.patch
+
+ +

1.4.3 Compiling the kernel

+ +

Next step is configuring and building the kernel. You can check Gentoo’s 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. +

+
+
$ make menuconfig
+$ make
+$ install -Dm755 $(make -s image_name) /boot/vmlinuz-linux
+
+ +
+
+

+Next: , Previous: , Up: Installation  

+
+ + + + + diff --git a/src/docs/Making-your-system-bootable.html b/src/docs/Making-your-system-bootable.html new file mode 100644 index 0000000..0387eb4 --- /dev/null +++ b/src/docs/Making-your-system-bootable.html @@ -0,0 +1,106 @@ + + + + + + +Making your system bootable (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Next: , Previous: , Up: Installation  

+
+
+

1.5 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. +

+

1.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
+
+ +

1.5.2 Installing init scripts

+ +

Only thing left to do is installing the init-scripts, and now you are almost +ready to boot your system! +

+
+
$ cpt b carbs-init && cpt i carbs-init
+
+ +

1.5.3 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: +

+
+
$ wget https://github.com/cemkeylan/genfstab/raw/master/genfstab
+$ chmod +x genfstab
+$ ./genfstab -U /mnt >> /mnt/etc/fstab
+
+ + + + + + diff --git a/src/docs/Package-Manager.html b/src/docs/Package-Manager.html new file mode 100644 index 0000000..04173a6 --- /dev/null +++ b/src/docs/Package-Manager.html @@ -0,0 +1,70 @@ + + + + + + +Package Manager (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Next: , Previous: , Up: Top  

+
+
+

2 Package Manager

+ +

Carbs Linux uses its own package managing toolchain named cpt. It is a +fork of the kiss package manager. Unlike +kiss, however, its main goal is being easily extendable. Instead of being +a single file package manager, it revolves around the shell library cpt-lib, +and many tools that wrap around it. +

+ + + + + +
• Usage   +
• Packaging System   +
• Rsync Repositories   +
+ + + + + + diff --git a/src/docs/Packaging-System.html b/src/docs/Packaging-System.html new file mode 100644 index 0000000..4fda504 --- /dev/null +++ b/src/docs/Packaging-System.html @@ -0,0 +1,197 @@ + + + + + + +Packaging System (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Next: , Previous: , Up: Package Manager  

+
+
+

2.2 Packaging System

+ +

A package is formed of several files, these are: +

+ +

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. +

+

2.2.1 build

+ +

Typically 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 build file is a POSIX shell script (for portability’s sake), build +files can be any executable program from binary programs to 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 ($#) +

+
    +
  1. Location of the package directory (DESTDIR) +
  2. Package version +
  3. System architecture +
+ +

2.2.2 sources

+ +

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 soures file; src dest. The +dest parameter is optional. It is the directory that the source will be +placed in. Here is the sources file for the gst-plugins package: +

+
+
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
+
+ +

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 curl. +

+

If the source is a git repository, it shall be prefixed with a 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, +

+
+
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'
+
+ +

Other files are assumed to be residing in the package directory. They should be +added with their paths relative to the package directory. +

+ +

2.2.3 checksums

+ +

checksums file is generated by the 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. +

+

2.2.4 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. +

+
+
1.3.2 1
+
+ +

The version should always match to the number of the upstream release. For +drastic changes that require a rebuild Those can be, +

+ + +

When a version bump occurs, the release should be reset to 1. +

+

2.2.5 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 CPT_TEST is set to 1, or the build is run +with the -t or --test options. So, a package package could have +the following depends file: +

+
+
linux-headers make
+python        test
+zlib
+
+ +

2.2.6 post-install

+ +

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 CPT_ROOT). +

+

2.2.7 message

+ +

This plaintext file will be outputted with cat after every package is +installed. +

+

2.2.8 test

+ +

Test files are mainly for the repository maintainer to test the packages, and +will only run if the user has the CPT_TEST variable set, or the build is +run with the -t or --test options. This script is run on the +build directory. It is run right after the build script is finished. +

+
+
+

+Next: , Previous: , Up: Package Manager  

+
+ + + + + diff --git a/src/docs/Post_002dinstallation.html b/src/docs/Post_002dinstallation.html new file mode 100644 index 0000000..19f7b21 --- /dev/null +++ b/src/docs/Post_002dinstallation.html @@ -0,0 +1,71 @@ + + + + + + +Post-installation (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Previous: , Up: Installation  

+
+
+

1.6 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. +

+

1.6.1 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. +

+
+
$ git clone https://github.com/kisslinux/community $HOME/repos/kiss-community
+$ export CPT_PATH=$CPT_PATH:$HOME/repos/kiss-community/community
+
+ +

NOTE: There are lots of packages on the KISS community repository that are also +on Carbs Linux main repository. I would advise giving lower priority to the KISS +community repository as it may affect other packages that you might install. +

+ + + + diff --git a/src/docs/Preparing-Environment.html b/src/docs/Preparing-Environment.html new file mode 100644 index 0000000..476299d --- /dev/null +++ b/src/docs/Preparing-Environment.html @@ -0,0 +1,129 @@ + + + + + + +Preparing Environment (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Next: , Up: Installation  

+
+
+

1.1 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: +

+ +

Rest of these instructions will assume that you have set all of these up, and +will continue on that point. +

+

1.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 thought these are optional, they are highly recommended. +

+

1.1.2 Check the integrity of the tarball (Recommended)

+ +

All of the releases are saved in a single file named sha256sums.txt, but the +latest release is saved on carbs-rootfs.tar.xz.sha256. You can acquire and +verify the tarball. +

+
+
$ wget https://dl.carbslinux.org/releases/x86_64/carbs-rootfs.tar.xz.sha256
+$ sha256sum -c carbs-rootfs.tar.xz.sha256
+
+ +

1.1.3 Verify the signature

+ +

It is highly recommended to verify the signature of the tarball. You will need +GPG for this. +

+
+
$ wget https://dl.carbslinux.org/releases/carbs-rootfs.tar.xz.sig
+$ gpg --recv-keys FF484BDFEFCEF8FF
+$ gpg --verify carbs-rootfs.tar.xz.sig
+
+ +

1.1.4 Extracting the tarball

+ +

You will need to extract the tarball to your desired location. For partitioning, +you can follow this guide. +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.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
+
+ +
+
+

+Next: , Up: Installation  

+
+ + + + + diff --git a/src/docs/Rsync-Repositories.html b/src/docs/Rsync-Repositories.html new file mode 100644 index 0000000..847b22c --- /dev/null +++ b/src/docs/Rsync-Repositories.html @@ -0,0 +1,101 @@ + + + + + + +Rsync Repositories (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Previous: , Up: Package Manager  

+
+
+

2.3 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: +

+
+
rsync://carbslinux.org/repo/core
+
+ +

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 .rsync and .rsync_root. Here is the Carbs Linux +rsync repository structure. +

+
+
           /
+   -----------------
+  |                |
+.rsync           core/
+          ----------------
+          |              |
+        .rsync      .rsync_root
+
+ +

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: +

+
+
/.rsync:           rsync://carbslinux.org/repo
+/core/.rsync:      rsync://carbslinux.org/repo/core
+/core/.rsync_root: ..
+
+ +

The .rsync_root file on the core repository points to the upper directory. +If a .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 .rsync file, this means that this +is an individual repository, and the package manager will fetch accordingly. +

+ + +
• Setting up an rsync repository for distribution   +
+ + + + + + diff --git a/src/docs/Setting-up-an-rsync-repository-for-distribution.html b/src/docs/Setting-up-an-rsync-repository-for-distribution.html new file mode 100644 index 0000000..2262723 --- /dev/null +++ b/src/docs/Setting-up-an-rsync-repository-for-distribution.html @@ -0,0 +1,99 @@ + + + + + + +Setting up an rsync repository for distribution (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Up: Rsync Repositories  

+
+
+

2.3.1 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. +

+
    #!/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
+
+

You can then create an rsync user for serving the repositories. +

+
+
$ adduser -SD rsync
+
+ +

Create /etc/rsyncd.conf and a service configuration as well. +

+
+    uid = rsync
+    gid = rsync
+    address = example.com
+    max connections = 10
+    use chroot = yes
+
+    [repo]
+        path = /pub/share/repo
+        comment = My repository
+
+

Create a service file at /etc/sv/rsync/run (runit): +

+
+
#!/bin/sh
+exec rsync --daemon --no-detach
+
+ + + + + diff --git a/src/docs/System-Configuration.html b/src/docs/System-Configuration.html new file mode 100644 index 0000000..1b8d78b --- /dev/null +++ b/src/docs/System-Configuration.html @@ -0,0 +1,77 @@ + + + + + + +System Configuration (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Next: , Previous: , Up: Installation  

+
+
+

1.3 System Configuration

+ +

After you have finished installing some extra packages, you can configure your +system to your liking. +

+

1.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
+
+ +

1.3.2 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. +

+
+
127.0.0.1  localhost.localdomain localhost
+::1        localhost.localdomain localhost ip6-localhost
+
+ + + + + + diff --git a/src/docs/Usage.html b/src/docs/Usage.html new file mode 100644 index 0000000..84c1283 --- /dev/null +++ b/src/docs/Usage.html @@ -0,0 +1,113 @@ + + + + + + +Usage (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Next: , Up: Package Manager  

+
+
+

2.1 Usage

+

cpt is formed of many tools combined in a single environment, similar +to git. When you run cpt without any arguments, it will show +all available tools and their explanations. Here is an example call with extra +scripts on my system: +

+
+
-> 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
+
+ + + + +
• cpt-alternatives   +
• cpt-build   +
+ +
+
+

+Next: , Up: Package Manager  

+
+ + + + + diff --git a/src/docs/cpt_002dalternatives.html b/src/docs/cpt_002dalternatives.html new file mode 100644 index 0000000..1730bac --- /dev/null +++ b/src/docs/cpt_002dalternatives.html @@ -0,0 +1,82 @@ + + + + + + +cpt-alternatives (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Next: , Up: Usage  

+
+
+

2.1.1 cpt-alternatives

+ +

You can list and swap to alternatives using cpt-alternatives, or +cpt a for short. When run without alternatives, it will list +alternatives. It can read from standard input if - is given as an +argument. +

+

2.1.1.1 Examples

+ +

List alternatives +

+
+
$ cpt-alternatives
+ncurses /usr/bin/clear
+ncurses /usr/bin/reset
+
+ +

Swap to clear from ncurses. +

+
+
$ cpt-alternatives ncurses /usr/bin/clear
+-> Swapping '/usr/bin/clear' from 'busybox' to 'ncurses'
+
+ +

Swap in bulk (all of sbase). +

+
+
$ cpt a | grep ^sbase | cpt a -
+
+ + + + + + diff --git a/src/docs/cpt_002dbuild.html b/src/docs/cpt_002dbuild.html new file mode 100644 index 0000000..e7d3712 --- /dev/null +++ b/src/docs/cpt_002dbuild.html @@ -0,0 +1,65 @@ + + + + + + +cpt-build (Carbs Linux User Manual) + + + + + + + + + + + + + + + + +
+

+Previous: , Up: Usage  

+
+
+

2.1.2 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. +

+

2.1.2.1 Options

+

cpt-build will accept the following options: +

+ + + + + + + diff --git a/src/docs/index.html b/src/docs/index.html new file mode 100644 index 0000000..96175c0 --- /dev/null +++ b/src/docs/index.html @@ -0,0 +1,108 @@ + + + + + + +Top (Carbs Linux User Manual) + + + + + + + + + + + + + + +

Carbs Linux User Manual

+ + + +
+

+Next:  

+
+
+

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. +

+ +

This documentation is also available in the distribution which can be read +by either running info carbslinux or reading /usr/share/doc/carbslinux.txt +with your favorite pager. You can install either the info or texinfo +for doing the first. +

+ + + + + + + + + + + + + + +
• Installation  Installing Carbs Linux +
• Package Manager  Carbs Linux Packaging Tools +
• Init System  Configuring the init system +
+
+
— 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 +
+ +
+
+

+Next:  

+
+ + + + + -- cgit v1.2.3