diff options
| -rw-r--r-- | Makefile | 5 | ||||
| -rw-r--r-- | carbslinux.org | 120 | ||||
| -rw-r--r-- | carbslinux.texi | 188 | ||||
| -rw-r--r-- | carbslinux.txt | 149 | ||||
| -rw-r--r-- | docs.el | 6 | ||||
| -rw-r--r-- | install.org | 361 | ||||
| -rw-r--r-- | install.txt | 34 |
7 files changed, 683 insertions, 180 deletions
@@ -2,7 +2,7 @@ include config.mk ORG = carbslinux.org fdl.org TEXI = carbslinux.texi -TARGET = carbslinux.info install.txt carbslinux.txt +TARGET = carbslinux.info install.txt carbslinux.txt install.org all: ${TARGET} @@ -12,6 +12,9 @@ carbslinux.info: carbslinux.texi install.txt: ${ORG} ${EMACS} carbslinux.org -f docs-install-txt +install.org: ${ORG} + ${EMACS} carbslinux.org -f docs-install-org + carbslinux.txt: ${ORG} ${EMACS} carbslinux.org -f org-ascii-export-to-ascii diff --git a/carbslinux.org b/carbslinux.org index 52ef531..750f4a4 100644 --- a/carbslinux.org +++ b/carbslinux.org @@ -64,13 +64,12 @@ for doing the first. - [[#fstab][Fstab]] - [[#post-installation][Post-installation]] - [[#kiss-repositories][KISS repositories]] -- [[#init-system][Init System]] - - [[#configuring-init][Configuring Init]] - - [[#kernel-command-line][Kernel Command Line]] - - [[#etcinitrcconf-file][=/etc/init/rc.conf= file]] - - [[#init-hooks][Init Hooks]] - - [[#changing-init-program][Changing Init Program]] - - [[#rebooting-after-changing-init][Rebooting after changing init]] +- [[#software][Software]] + - [[#init-system][Init System]] + - [[#configuring-init][Configuring Init]] + - [[#changing-init-program][Changing Init Program]] + - [[#display-systems][Display Systems]] + - [[#wayland][Wayland]] - [[#contribution-guidelines][Contribution Guidelines]] - [[#conventions][Conventions]] - [[#shell-conventions][Shell Conventions]] @@ -323,7 +322,9 @@ cpt-install package :DESCRIPTION: Software you might want to include on your system :END: -Here is a list of software that you might want to have on your system. +Here is a small list of software that you might want to have on your system as +you are setting up. You might want to check the *Software* section in the full +documentation to learn more about other packaged software. *BOOTLOADERS* @@ -345,22 +346,6 @@ Here is a list of software that you might want to have on your system. - nano - vim -- neatvi -- emacs -- emacs-nox (terminal-only version of emacs) - -*USER SHELLS* - -- bash -- zsh -- oksh -- rc - -*POSIX BASE UTILITIES* - -- busybox -- sbase -- coreutils *DOCUMENTATION* @@ -374,7 +359,7 @@ Here is a list of software that you might want to have on your system. :END: 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 +viewed offline. You can obtain either =texinfo= or the =info= packages in order to view the documentation. #+BEGIN_SRC sh @@ -571,11 +556,22 @@ You can check the rest of the documentation to learn more about the system. :DESCRIPTION: Acquire kiss repositories :END: -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. +There have been recent changes to the =kiss= package manager that breaks +compatibility with =cpt=. These changes throw away the entire premise of their +"static" packaging system. =cpt= will never implement those changes, so don't +expect any KISS package that was changed during or after July 2021 to work with +=cpt=. + +* Software + +The distribution aims to package essential and useful software needed in a +practical system. If the repository lacks a package that you use, you may also +easily package it yourself or request it to be added to the default repositories +over on the IRC channel (=#carbslinux= on [[https://libera.chat][Libera]]). -* Init System +This section goes over the details of some packaged software + +** Init System :PROPERTIES: :DESCRIPTION: Configure the init system :END: @@ -585,7 +581,7 @@ 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 +*** Configuring Init :PROPERTIES: :DESCRIPTION: Ways to configure the init system :END: @@ -596,7 +592,7 @@ There are three ways you can change the behaviour of the init system. Those are: - =/etc/init/rc.conf= file - Init Hooks -*** Kernel Command Line +**** Kernel Command Line :PROPERTIES: :DESCRIPTION: Configure init through the boot parameters :END: @@ -623,7 +619,7 @@ 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. -*** =/etc/init/rc.conf= file +**** =/etc/init/rc.conf= file :PROPERTIES: :DESCRIPTION: Configure init through the configuration file :END: @@ -633,7 +629,7 @@ 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. -*** Init Hooks +**** Init Hooks :PROPERTIES: :DESCRIPTION: Configure init through hooks :END: @@ -650,7 +646,7 @@ hook name as the suffix. For example, a boot script will be placed as - umount :: Run just before filesystems are unmounted. - post.shutdown :: Run just before the system is halted. -** Changing Init Program +*** Changing Init Program :PROPERTIES: :DESCRIPTION: Replace the default busybox init with something new :END: @@ -659,7 +655,7 @@ By default, Carbs Linux comes preinstalled with =busybox-init=, but this can easily be replaced without any issues. Currently, available init systems are: - =sinit= -- =busybox= +- =busybox= init - =runit= - =shinit= @@ -673,7 +669,7 @@ cpt a runit /usr/bin/poweroff cpt a runit /usr/bin/reboot #+END_SRC -*** Rebooting after changing init +**** Rebooting after changing init :PROPERTIES: :DESCRIPTION: Ways to reboot after replacing the init system :END: @@ -689,28 +685,58 @@ currently running on your system and not the one you are switching to. | runit | =runit-init 6= | | shinit/sinit | =kill -s INT 1= | -* TODO Wayland :noexport: -:PROPERTIES: -:DESCRIPTION: Installing Wayland on Carbs Linux -:END: +** TODO Display Systems + +Carbs Linux supports both Xorg and Wayland in the distribution repositories. +This section serves as a guide to set up your preferred display server. Follow +the subsection for the display server you want to setup. + +*** Wayland Wayland is a modern display server protocol intended as a replacement for Xorg. Wayland has a much simpler architecture compared to X by its careful design and implementation. Users who want to use a Wayland compositor should follow this section. -** TODO Enabling the Wayland repository +**** Enabling the Wayland repository The =wayland= repository requires packages from =xorg= and =extra= repositories. +So you should set your =$CPT_PATH= so that =core= and =extra= repositories +precede the =wayland= repository, and the =xorg= repository should come after +=wayland=. Here is an example below, where =$REPOSITORY= points to the root of +your repository. + +#+begin_src sh +CPT_PATH=$REPOSITORY/core +CPT_PATH=$CPT_PATH:$REPOSITORY/extra +CPT_PATH=$CPT_PATH:$REPOSITORY/wayland +CPT_PATH=$CPT_PATH:$REPOSITORY/xorg +export CPT_PATH +#+end_src + +After you have enabled your repositories, go ahead and install =wayland= and +=wayland-protocols= packages. + +#+begin_src sh +cpt-build wayland wayland-protocols +#+end_src + +**** Switching from Xorg + +If you are already an Xorg user, you will need to rebuild some packages so that +they support =wayland=. If you don't have an =xorg= system, feel free to skip +this step. The packages that need a rebuild are: -** TODO Switching from Xorg +- gtk+3 +- gtk4 +- mesa +- xorg-server (for Xwayland support) +- webkit2gtk -If you are switching from Xorg, you will need to recompile some programs to -reflect on the changes. Those are: +**** TODO Installing a Compositor -- =xorg-server= -- =gtk+3= -- =mesa= +The =wayland= repository currently only contains =sway= as a Wayland compositor, +but you can package something else for your own. * Contribution Guidelines :PROPERTIES: diff --git a/carbslinux.texi b/carbslinux.texi index 532bd38..9345006 100644 --- a/carbslinux.texi +++ b/carbslinux.texi @@ -60,7 +60,7 @@ for doing the first. @menu * Installation:: Installing Carbs Linux -* Init System:: Configure the init system +* Software:: * Contribution Guidelines:: Contribute to Carbs Linux * GNU Free Documentation License:: Your rights @@ -112,20 +112,19 @@ Post-installation * KISS repositories:: Acquire kiss repositories +Software + +* Init System:: Configure the init system +* Display Systems:: + Init System * Configuring Init:: Ways to configure the init system * Changing Init Program:: Replace the default busybox init with something new -Configuring Init - -* Kernel Command Line:: Configure init through the boot parameters -* @samp{/etc/init/rc.conf} file: @samp{/etc/init/rcconf} file. Configure init through the configuration file -* Init Hooks:: Configure init through hooks - -Changing Init Program +Display Systems -* Rebooting after changing init:: Ways to reboot after replacing the init system +* Wayland:: Contribution Guidelines @@ -377,7 +376,9 @@ cpt-install package @node Essential Software @subsection Essential Software -Here is a list of software that you might want to have on your system. +Here is a small list of software that you might want to have on your system as +you are setting up. You might want to check the @strong{Software} section in the full +documentation to learn more about other packaged software. @strong{BOOTLOADERS} @@ -415,36 +416,6 @@ wpa@math{_supplicant} nano @item vim -@item -neatvi -@item -emacs -@item -emacs-nox (terminal-only version of emacs) -@end itemize - -@strong{USER SHELLS} - -@itemize -@item -bash -@item -zsh -@item -oksh -@item -rc -@end itemize - -@strong{POSIX BASE UTILITIES} - -@itemize -@item -busybox -@item -sbase -@item -coreutils @end itemize @strong{DOCUMENTATION} @@ -462,7 +433,7 @@ man-pages-posix @subsection Obtaining the documentation 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 +viewed offline. You can obtain either @samp{texinfo} or the @samp{info} packages in order to view the documentation. @example @@ -660,12 +631,29 @@ You can check the rest of the documentation to learn more about the system. @node KISS repositories @subsection 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. +There have been recent changes to the @samp{kiss} package manager that breaks +compatibility with @samp{cpt}. These changes throw away the entire premise of their +"static" packaging system. @samp{cpt} will never implement those changes, so don't +expect any KISS package that was changed during or after July 2021 to work with +@samp{cpt}. + +@node Software +@chapter Software + +The distribution aims to package essential and useful software needed in a +practical system. If the repository lacks a package that you use, you may also +easily package it yourself or request it to be added to the default repositories +over on the IRC channel (@samp{#carbslinux} on @uref{https://libera.chat, Libera}). + +This section goes over the details of some packaged software + +@menu +* Init System:: Configure the init system +* Display Systems:: +@end menu @node Init System -@chapter Init System +@section Init System Carbs Linux init scripts are run by the init daemon (@samp{busybox} by default) on boot and shutdown processes. It also provides its own halting program named @@ -678,7 +666,7 @@ programs. @end menu @node Configuring Init -@section Configuring Init +@subsection Configuring Init There are three ways you can change the behaviour of the init system. Those are: @@ -691,14 +679,10 @@ Kernel Command Line Init Hooks @end itemize -@menu -* Kernel Command Line:: Configure init through the boot parameters -* @samp{/etc/init/rc.conf} file: @samp{/etc/init/rcconf} file. Configure init through the configuration file -* Init Hooks:: Configure init through hooks -@end menu +@enumerate +@item +Kernel Command Line -@node Kernel Command Line -@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, @@ -722,16 +706,18 @@ quiet=1 Some of these variables, such as @samp{rw=/=ro}, @samp{loglevel}, and @samp{quiet}, will be used by the init system to change the behaviour of the startup. -@node @samp{/etc/init/rcconf} file -@subsection @samp{/etc/init/rc.conf} file +@item +@samp{/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. -@node Init Hooks -@subsection Init Hooks +@item +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, @@ -751,9 +737,10 @@ Run just before filesystems are unmounted. @item post.shutdown Run just before the system is halted. @end table +@end enumerate @node Changing Init Program -@section Changing Init Program +@subsection Changing Init Program By default, Carbs Linux comes preinstalled with @samp{busybox-init}, but this can easily be replaced without any issues. Currently, available init systems are: @@ -762,7 +749,7 @@ easily be replaced without any issues. Currently, available init systems are: @item @samp{sinit} @item -@samp{busybox} +@samp{busybox} init @item @samp{runit} @item @@ -779,12 +766,10 @@ cpt a runit /usr/bin/poweroff cpt a runit /usr/bin/reboot @end example -@menu -* Rebooting after changing init:: Ways to reboot after replacing the init system -@end menu +@enumerate +@item +Rebooting after changing init -@node Rebooting after changing init -@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 @@ -801,6 +786,81 @@ currently running on your system and not the one you are switching to. @item shinit/sinit @tab @samp{kill -s INT 1} @end multitable +@end enumerate + +@node Display Systems +@section @strong{TODO} Display Systems + +Carbs Linux supports both Xorg and Wayland in the distribution repositories. +This section serves as a guide to set up your preferred display server. Follow +the subsection for the display server you want to setup. + +@menu +* Wayland:: +@end menu + +@node Wayland +@subsection Wayland + +Wayland is a modern display server protocol intended as a replacement for Xorg. +Wayland has a much simpler architecture compared to X by its careful design and +implementation. Users who want to use a Wayland compositor should follow this +section. + +@enumerate +@item +Enabling the Wayland repository + + +The @samp{wayland} repository requires packages from @samp{xorg} and @samp{extra} repositories. +So you should set your @samp{$CPT_PATH} so that @samp{core} and @samp{extra} repositories +precede the @samp{wayland} repository, and the @samp{xorg} repository should come after +@samp{wayland}. Here is an example below, where @samp{$REPOSITORY} points to the root of +your repository. + +@example +CPT_PATH=$REPOSITORY/core +CPT_PATH=$CPT_PATH:$REPOSITORY/extra +CPT_PATH=$CPT_PATH:$REPOSITORY/wayland +CPT_PATH=$CPT_PATH:$REPOSITORY/xorg +export CPT_PATH +@end example + +After you have enabled your repositories, go ahead and install @samp{wayland} and +@samp{wayland-protocols} packages. + +@example +cpt-build wayland wayland-protocols +@end example + +@item +Switching from Xorg + + +If you are already an Xorg user, you will need to rebuild some packages so that +they support @samp{wayland}. If you don't have an @samp{xorg} system, feel free to skip +this step. The packages that need a rebuild are: + +@itemize +@item +gtk+3 +@item +gtk4 +@item +mesa +@item +xorg-server (for Xwayland support) +@item +webkit2gtk +@end itemize + +@item +@strong{TODO} Installing a Compositor + + +The @samp{wayland} repository currently only contains @samp{sway} as a Wayland compositor, +but you can package something else for your own. +@end enumerate @node Contribution Guidelines @chapter Contribution Guidelines diff --git a/carbslinux.txt b/carbslinux.txt index 1451ef2..43dc949 100644 --- a/carbslinux.txt +++ b/carbslinux.txt @@ -35,13 +35,12 @@ _________________ ..... 3. Fstab .. 6. Post-installation ..... 1. KISS repositories -3. Init System -.. 1. Configuring Init -..... 1. Kernel Command Line -..... 2. `/etc/init/rc.conf' file -..... 3. Init Hooks -.. 2. Changing Init Program -..... 1. Rebooting after changing init +3. Software +.. 1. Init System +..... 1. Configuring Init +..... 2. Changing Init Program +.. 2. TODO Display Systems +..... 1. Wayland 4. Contribution Guidelines .. 1. Conventions ..... 1. Shell Conventions @@ -319,7 +318,10 @@ with the info reader. It is divided into sections and easier to read. 2.2.4 Essential Software ------------------------ - Here is a list of software that you might want to have on your system. + Here is a small list of software that you might want to have on your + system as you are setting up. You might want to check the *Software* + section in the full documentation to learn more about other packaged + software. *BOOTLOADERS* @@ -341,22 +343,6 @@ with the info reader. It is divided into sections and easier to read. - nano - vim - - neatvi - - emacs - - emacs-nox (terminal-only version of emacs) - - *USER SHELLS* - - - bash - - zsh - - oksh - - rc - - *POSIX BASE UTILITIES* - - - busybox - - sbase - - coreutils *DOCUMENTATION* @@ -369,8 +355,8 @@ with the info reader. It is divided into sections and easier to read. --------------------------------- 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. + manual to be viewed offline. You can obtain either `texinfo' or the + `info' packages in order to view the documentation. ,---- | # Install the documentation. @@ -573,14 +559,29 @@ with the info reader. It is divided into sections and easier to read. 2.6.1 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. + There have been recent changes to the `kiss' package manager that + breaks compatibility with `cpt'. These changes throw away the entire + premise of their "static" packaging system. `cpt' will never implement + those changes, so don't expect any KISS package that was changed + during or after July 2021 to work with `cpt'. + +3 Software +========== -3 Init System -============= + The distribution aims to package essential and useful software needed + in a practical system. If the repository lacks a package that you use, + you may also easily package it yourself or request it to be added to + the default repositories over on the IRC channel (`#carbslinux' on + [Libera]). + + This section goes over the details of some packaged software + + +[Libera] <https://libera.chat> + +3.1 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 @@ -588,8 +589,8 @@ with the info reader. It is divided into sections and easier to read. doesn't rely on non-POSIX external programs. -3.1 Configuring Init -~~~~~~~~~~~~~~~~~~~~ +3.1.1 Configuring Init +---------------------- There are three ways you can change the behaviour of the init system. Those are: @@ -599,8 +600,7 @@ with the info reader. It is divided into sections and easier to read. - Init Hooks -3.1.1 Kernel Command Line -------------------------- +* 3.1.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 @@ -627,8 +627,7 @@ with the info reader. It is divided into sections and easier to read. startup. -3.1.2 `/etc/init/rc.conf' file ------------------------------- +* 3.1.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 @@ -636,8 +635,7 @@ with the info reader. It is divided into sections and easier to read. since they can be set just before boot. -3.1.3 Init Hooks ----------------- +* 3.1.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, @@ -658,15 +656,15 @@ with the info reader. It is divided into sections and easier to read. Run just before the system is halted. -3.2 Changing Init Program -~~~~~~~~~~~~~~~~~~~~~~~~~ +3.1.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: - `sinit' - - `busybox' + - `busybox' init - `runit' - `shinit' @@ -681,8 +679,7 @@ with the info reader. It is divided into sections and easier to read. `---- -3.2.1 Rebooting after changing init ------------------------------------ +* 3.1.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 @@ -697,6 +694,68 @@ with the info reader. It is divided into sections and easier to read. shinit/sinit `kill -s INT 1' +3.2 TODO Display Systems +~~~~~~~~~~~~~~~~~~~~~~~~ + + Carbs Linux supports both Xorg and Wayland in the distribution + repositories. This section serves as a guide to set up your preferred + display server. Follow the subsection for the display server you want + to setup. + + +3.2.1 Wayland +------------- + + Wayland is a modern display server protocol intended as a replacement + for Xorg. Wayland has a much simpler architecture compared to X by + its careful design and implementation. Users who want to use a Wayland + compositor should follow this section. + + +* 3.2.1.1 Enabling the Wayland repository + + The `wayland' repository requires packages from `xorg' and `extra' + repositories. So you should set your `$CPT_PATH' so that `core' and + `extra' repositories precede the `wayland' repository, and the `xorg' + repository should come after `wayland'. Here is an example below, + where `$REPOSITORY' points to the root of your repository. + + ,---- + | CPT_PATH=$REPOSITORY/core + | CPT_PATH=$CPT_PATH:$REPOSITORY/extra + | CPT_PATH=$CPT_PATH:$REPOSITORY/wayland + | CPT_PATH=$CPT_PATH:$REPOSITORY/xorg + | export CPT_PATH + `---- + + After you have enabled your repositories, go ahead and install + `wayland' and `wayland-protocols' packages. + + ,---- + | cpt-build wayland wayland-protocols + `---- + + +* 3.2.1.2 Switching from Xorg + + If you are already an Xorg user, you will need to rebuild some + packages so that they support `wayland'. If you don't have an `xorg' + system, feel free to skip this step. The packages that need a rebuild + are: + + - gtk+3 + - gtk4 + - mesa + - xorg-server (for Xwayland support) + - webkit2gtk + + +* 3.2.1.3 TODO Installing a Compositor + + The `wayland' repository currently only contains `sway' as a Wayland + compositor, but you can package something else for your own. + + 4 Contribution Guidelines ========================= @@ -14,5 +14,11 @@ (re-search-forward "^* Installation") (org-ascii-export-to-ascii nil t))) +(defun docs-install-org () + "Extract and export installation manual as an org file from the User Manual." + (let ((org-export-with-toc nil)) + (re-search-forward "^* Installation") + (org-org-export-to-org nil t))) + (provide 'docs) ;;; docs.el ends here diff --git a/install.org b/install.org new file mode 100644 index 0000000..b5a1234 --- /dev/null +++ b/install.org @@ -0,0 +1,361 @@ +# Created 2021-07-22 Thu 15:50 +#+TITLE: Carbs Linux Installation Guide +#+AUTHOR: Cem Keylan +These are the step-by-step instructions for installing Carbs Linux. It can be +acquired as plain-text to be viewed offline with a pager from +[[https://carbslinux.org/install.txt]]. + +#+begin_src sh + curl -sL https://carbslinux.org/install.txt | less +#+end_src + +#+toc: headlines 3 local +* 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: + +- tar +- wget +- xz +- some form of base utilities (coreutils, sbase, busybox, etc.) + +Rest of these instructions will assume that you have set all of these up, and +will continue on that point. + +** 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=. We are setting this in a URL variable so that we don't have to +write it every time. + +#+begin_src sh + URL=https://dl.carbslinux.org/releases/x86_64 + wget $URL/carbs-rootfs.tar.xz.sha256 + sha256sum -c carbs-rootfs.tar.xz.sha256 +#+end_src + +** Signature verification +It is highly recommended to verify the signature of the tarball. You will need +the OpenBSD tool =signify(1)= for this. Many distributions provide a package for +it, if you are using a Carbs Linux host, you can also install the package +=otools= which provides =signify=. Download the signature first. + +#+begin_src sh + wget $URL/carbs-rootfs.tar.xz.sig +#+end_src + +The signature file should say something similar to + +#+results: +: untrusted comment: verify with carbslinux-2021.04.pub +: RWTBBPDVQ+aHB3dme2Kerf8XY+vWkIISp7Za2ufKghtlnRXPyObAQQyvEJYrwMVTaCBlPEnSWcnHQz8Nka06YVOIeextNKZY3AQ= + + +Grab the key (which probably should be the latest one) that is written on the +file from [[https://dl.carbslinux.org/keys/]] so you can verify the signature. The +latest Signify public key is also available on the [[https://git.carbslinux.org/repository][package repository]], so you can +check the validity of the public key from multiple locations, or just copy paste +that portion to a file and use that instead. + +#+begin_src sh + PUBKEY=carbslinux-2021.04.pub + wget https://dl.carbslinux.org/keys/$PUBKEY +#+end_src + +You can now verify the distribution tarball with signify. + +#+begin_src sh + signify -V -m carbs-rootfs.tar.xz -p $PUBKEY +#+end_src + +If everything went alright, this should output: + +#+begin_example + Signature Verified +#+end_example + + + +** Extracting the tarball +You will need to extract the tarball to your desired location. For partitioning, +you can follow [[https://wiki.archlinux.org/index.php/Partitioning][this guide]]. This will assume that you will be mounting your root +partition to =/mnt=. + +#+begin_src sh + mount /dev/sdx1 /mnt + tar xf carbs-rootfs.tar.xz -C /mnt +#+end_src + +** Obtain the chroot helper +You can obtain the =cpt-chroot= script in order to do a simple chroot into your +new root filesystem. + +#+begin_src sh + wget https://dl.carbslinux.org/distfiles/cpt-chroot + chmod a+x cpt-chroot +#+end_src + +* Chroot +Chroot into Carbs Linux! + +#+begin_src sh + ./cpt-chroot /mnt +#+end_src + +** 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: + +#+begin_src sh + mkdir -p $HOME/repos +#+end_src + +*** 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://git.carbslinux.org/repository +- https://github.com/carbslinux/repository + +#+begin_src sh + git clone git://git.carbslinux.org/repository $HOME/repos/carbs +#+end_src + +*** Obtaining from rsync + +Carbs Linux rsync repositories live in rsync://carbslinux.org/repo. In +order to obtain it, run the following: + +#+begin_src sh + rsync -avc rsync://carbslinux.org/repo $HOME/repos/carbs +#+end_src + +*** Making the package manager use the repositories + +In your shell's configuration file, or in your =~/.profile= file, add the +following lines: + +#+begin_src sh + 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_src + +** 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. + +#+begin_src sh + cpt-update && cpt-update +#+end_src + +** Installing packages +Since you are operating on a really small base, you might need to build and +install new programs to extend the functionality of your system. In order to +build and install packages new packages in Carbs, you need to execute the +following. "Package" is not actually a package and is given as an example. + +#+begin_src sh + cpt-build package + cpt-install package +#+end_src + +** Essential Software +Here is a small list of software that you might want to have on your system as +you are setting up. You might want to check the *Software* section in the full +documentation to learn more about other packaged software. + +*BOOTLOADERS* + +- efibootmgr +- grub + +*FILESYSTEMS* + +- e2fsprogs +- dosfstools +- ntfs-3g + +*NETWORKING* + +- dhcpcd +- wpa_supplicant + +*TEXT EDITORS* + +- nano +- vim + +*DOCUMENTATION* + +- carbs-docs +- man-pages +- man-pages-posix + +** Obtaining the documentation +All the documentation for Carbs Linux can be found on a single info manual to be +viewed offline. You can obtain either =texinfo= or the =info= packages in order +to view the documentation. + +#+begin_src sh + # 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_src + +* System Configuration +After you have finished installing some extra packages, you can configure your +system to your liking. + +** Configuring hostname +You might want to add a hostname, especially in a networked environment. Your +hostname will default to 'carbslinux' unless you set this. + +#+begin_src sh + echo your-hostname > /etc/hostname +#+end_src + +** Hosts file +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. + +#+begin_example + 127.0.0.1 localhost.localdomain localhost + ::1 localhost.localdomain localhost ip6-localhost +#+end_example + +* Kernel +Kernel isn't managed under the main repositories, even though you could package +one for your personal use. Here is an [[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. + +** 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. + +#+begin_src sh + # Download the kernel and extract it + wget https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.9.1.tar.xz + tar xf linux-5.9.1.tar.xz + + # Change directory into the kernel sources + cd linux-5.9.1 +#+end_src + +** Kernel dependencies +In order to compile the kernel you will need to install some dependencies. You +will need =libelf=, and =bison= to compile the kernel. If you want to configure +using the menu interface you will also need =ncurses=. + +#+begin_src sh + # 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_src + +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 [[https://github.com/E5ten][E5ten]]. You will need to obtain and apply the patch in the kernel +source directory. + +#+begin_src sh + wget https://dl.carbslinux.org/distfiles/kernel-no-perl.patch + patch -p1 < kernel-no-perl.patch +#+end_src + +** Building the kernel +Next step is configuring and building the kernel. You can check Gentoo's +[[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. + +#+begin_src sh + make menuconfig + make + install -Dm755 $(make -s image_name) /boot/vmlinuz-linux +#+end_src + +* 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. + +** 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 + +#+begin_src sh + cpt b grub && cpt i grub + grub-install --target=i386-pc /dev/sdX + grub-mkconfig -o /boot/grub/grub.cfg +#+end_src + +*** GRUB UEFI installation + +#+begin_src sh + 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_src + +** Init scripts +Only thing left to do is installing the init-scripts, and now you are almost +ready to boot your system! + +#+begin_src sh + cpt b carbs-init && cpt i carbs-init +#+end_src + +** 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: + +#+begin_src sh + wget https://github.com/cemkeylan/genfstab/raw/master/genfstab + chmod +x genfstab + ./genfstab -U /mnt >> /mnt/etc/fstab +#+end_src + +* 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. +You can check the rest of the documentation to learn more about the system. + +** KISS repositories +There have been recent changes to the =kiss= package manager that breaks +compatibility with =cpt=. These changes throw away the entire premise of their +"static" packaging system. =cpt= will never implement those changes, so don't +expect any KISS package that was changed during or after July 2021 to work with +=cpt=. diff --git a/install.txt b/install.txt index 59e892e..68e8dac 100644 --- a/install.txt +++ b/install.txt @@ -256,7 +256,10 @@ can be acquired as plain-text to be viewed offline with a pager from 2.4 Essential Software ~~~~~~~~~~~~~~~~~~~~~~ - Here is a list of software that you might want to have on your system. + Here is a small list of software that you might want to have on your + system as you are setting up. You might want to check the *Software* + section in the full documentation to learn more about other packaged + software. *BOOTLOADERS* @@ -278,22 +281,6 @@ can be acquired as plain-text to be viewed offline with a pager from - nano - vim - - neatvi - - emacs - - emacs-nox (terminal-only version of emacs) - - *USER SHELLS* - - - bash - - zsh - - oksh - - rc - - *POSIX BASE UTILITIES* - - - busybox - - sbase - - coreutils *DOCUMENTATION* @@ -306,8 +293,8 @@ can be acquired as plain-text to be viewed offline with a pager from ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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. + manual to be viewed offline. You can obtain either `texinfo' or the + `info' packages in order to view the documentation. ,---- | # Install the documentation. @@ -512,7 +499,8 @@ can be acquired as plain-text to be viewed offline with a pager from 6.1 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. + There have been recent changes to the `kiss' package manager that + breaks compatibility with `cpt'. These changes throw away the entire + premise of their "static" packaging system. `cpt' will never implement + those changes, so don't expect any KISS package that was changed + during or after July 2021 to work with `cpt'. |