diff options
Diffstat (limited to 'docs/docs/carbslinux.html')
| -rw-r--r-- | docs/docs/carbslinux.html | 1786 |
1 files changed, 1786 insertions, 0 deletions
diff --git a/docs/docs/carbslinux.html b/docs/docs/carbslinux.html new file mode 100644 index 0000000..e50d6f4 --- /dev/null +++ b/docs/docs/carbslinux.html @@ -0,0 +1,1786 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 2020 Cem Keylan + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with no Front-Cover Texts and no Back-Cover Texts. +A copy of the license is included in the section entitled "GNU Free +Documentation License." + --> +<!-- Created by GNU Texinfo 6.7, http://www.gnu.org/software/texinfo/ --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<title>Carbs Linux User Manual</title> + +<meta name="description" content="Carbs Linux User Manual"> +<meta name="keywords" content="Carbs Linux User Manual"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<link href="#Top" rel="start" title="Top"> +<link href="#SEC_Contents" rel="contents" title="Table of Contents"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.indentedblock {margin-right: 0em} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +kbd {font-style: oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +span.nolinebreak {white-space: nowrap} +span.roman {font-family: initial; font-weight: normal} +span.sansserif {font-family: sans-serif; font-weight: normal} +ul.no-bullet {list-style: none} +--> +</style> +<link rel="stylesheet" type="text/css" href="https://www.gnu.org/software/gnulib/manual.css"> + + +</head> + +<body lang="en"> +<h1 class="settitle" align="center">Carbs Linux User Manual</h1> + + + + +<span id="SEC_Contents"></span> +<h2 class="contents-heading">Table of Contents</h2> + +<div class="contents"> + +<ul class="no-bullet"> + <li><a id="toc-Installation-1" href="#Installation">1 Installation</a> + <ul class="no-bullet"> + <li><a id="toc-Preparing-Environment-1" href="#Preparing-Environment">1.1 Preparing Environment</a> + <ul class="no-bullet"> + <li><a id="toc-Download-1" href="#Download">1.1.1 Download</a></li> + <li><a id="toc-Signature-verification-1" href="#Signature-verification">1.1.2 Signature verification</a></li> + <li><a id="toc-Extracting-the-tarball-1" href="#Extracting-the-tarball">1.1.3 Extracting the tarball</a></li> + <li><a id="toc-Obtain-the-chroot-helper-1" href="#Obtain-the-chroot-helper">1.1.4 Obtain the chroot helper</a></li> + </ul></li> + <li><a id="toc-Chroot-1" href="#Chroot">1.2 Chroot</a> + <ul class="no-bullet"> + <li><a id="toc-Setting-up-repositories-1" href="#Setting-up-repositories">1.2.1 Setting up repositories</a></li> + <li><a id="toc-Updating-packages-1" href="#Updating-packages">1.2.2 Updating packages</a></li> + <li><a id="toc-Installing-packages-1" href="#Installing-packages">1.2.3 Installing packages</a></li> + <li><a id="toc-Essential-Software-1" href="#Essential-Software">1.2.4 Essential Software</a></li> + <li><a id="toc-Obtaining-the-documentation-1" href="#Obtaining-the-documentation">1.2.5 Obtaining the documentation</a></li> + </ul></li> + <li><a id="toc-System-Configuration-1" href="#System-Configuration">1.3 System Configuration</a> + <ul class="no-bullet"> + <li><a id="toc-Configuring-hostname-1" href="#Configuring-hostname">1.3.1 Configuring hostname</a></li> + <li><a id="toc-Hosts-file-1" href="#Hosts-file">1.3.2 Hosts file</a></li> + </ul></li> + <li><a id="toc-Kernel-1" href="#Kernel">1.4 Kernel</a> + <ul class="no-bullet"> + <li><a id="toc-Obtaining-the-kernel-sources-1" href="#Obtaining-the-kernel-sources">1.4.1 Obtaining the kernel sources</a></li> + <li><a id="toc-Kernel-dependencies-1" href="#Kernel-dependencies">1.4.2 Kernel dependencies</a></li> + <li><a id="toc-Building-the-kernel-1" href="#Building-the-kernel">1.4.3 Building the kernel</a></li> + </ul></li> + <li><a id="toc-Making-your-system-bootable-1" href="#Making-your-system-bootable">1.5 Making your system bootable</a> + <ul class="no-bullet"> + <li><a id="toc-Bootloader-1" href="#Bootloader">1.5.1 Bootloader</a></li> + <li><a id="toc-Init-scripts-1" href="#Init-scripts">1.5.2 Init scripts</a></li> + <li><a id="toc-Fstab-1" href="#Fstab">1.5.3 Fstab</a></li> + </ul></li> + <li><a id="toc-Post_002dinstallation-1" href="#Post_002dinstallation">1.6 Post-installation</a> + <ul class="no-bullet"> + <li><a id="toc-KISS-repositories-1" href="#KISS-repositories">1.6.1 KISS repositories</a></li> + </ul></li> + </ul></li> + <li><a id="toc-Init-System-1" href="#Init-System">2 Init System</a> + <ul class="no-bullet"> + <li><a id="toc-Configuring-Init-1" href="#Configuring-Init">2.1 Configuring Init</a> + <ul class="no-bullet"> + <li><a id="toc-Kernel-Command-Line-1" href="#Kernel-Command-Line">2.1.1 Kernel Command Line</a></li> + <li><a id="toc-_002fetc_002finit_002frc_002econf-file" href="#g_t_002fetc_002finit_002frcconf-file">2.1.2 ‘<samp>/etc/init/rc.conf</samp>’ file</a></li> + <li><a id="toc-Init-Hooks-1" href="#Init-Hooks">2.1.3 Init Hooks</a></li> + </ul></li> + <li><a id="toc-Changing-Init-Program-1" href="#Changing-Init-Program">2.2 Changing Init Program</a> + <ul class="no-bullet"> + <li><a id="toc-Rebooting-after-changing-init-1" href="#Rebooting-after-changing-init">2.2.1 Rebooting after changing init</a></li> + </ul></li> + </ul></li> + <li><a id="toc-Contribution-Guidelines-1" href="#Contribution-Guidelines">3 Contribution Guidelines</a> + <ul class="no-bullet"> + <li><a id="toc-Conventions-1" href="#Conventions">3.1 Conventions</a> + <ul class="no-bullet"> + <li><a id="toc-Shell-Conventions-1" href="#Shell-Conventions">3.1.1 Shell Conventions</a></li> + <li><a id="toc-Repository-Conventions-1" href="#Repository-Conventions">3.1.2 Repository Conventions</a></li> + </ul></li> + </ul></li> + <li><a id="toc-GNU-Free-Documentation-License-1" href="#GNU-Free-Documentation-License">Appendix A GNU Free Documentation License</a> + <ul class="no-bullet"> + <li><a id="toc-ADDENDUM_003a-How-to-use-this-License-for-your-documents" href="#ADDENDUM_003a-How-to-use-this-License-for-your-documents">A.1 ADDENDUM: How to use this License for your documents</a></li> + </ul></li> +</ul> +</div> + + +<span id="Top"></span><div class="header"> +<p> +Next: <a href="#Installation" accesskey="n" rel="next">Installation</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Carbs-Linux-User-Manual"></span><h1 class="top">Carbs Linux User Manual</h1> + +<p>This is the full documentation of <a href="https://carbslinux.org">Carbs Linux</a>, from the details of the +distribution, installation, to the package manager. It is not yet complete. +</p> + +<p>This documentation is also available in the distribution by the +<code>carbs-docs</code> package, which can be read by either running +<code>info carbslinux</code> or reading <samp>/usr/share/doc/carbslinux.txt</samp> with your +favorite pager. You can install either the <code>info</code> or <code>texinfo</code> +for doing the first. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Installation" accesskey="1">Installation</a></td><td> </td><td align="left" valign="top">Installing Carbs Linux +</td></tr> +<tr><td align="left" valign="top">• <a href="#Init-System" accesskey="2">Init System</a></td><td> </td><td align="left" valign="top">Configure the init system +</td></tr> +<tr><td align="left" valign="top">• <a href="#Contribution-Guidelines" accesskey="3">Contribution Guidelines</a></td><td> </td><td align="left" valign="top">Contribute to Carbs Linux +</td></tr> +<tr><td align="left" valign="top">• <a href="#GNU-Free-Documentation-License" accesskey="4">GNU Free Documentation License</a></td><td> </td><td align="left" valign="top">Your rights +</td></tr> +<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> + +</pre></th></tr><tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">— The Detailed Node Listing — + +Installation + +</pre></th></tr><tr><td align="left" valign="top">• <a href="#Preparing-Environment" accesskey="5">Preparing Environment</a></td><td> </td><td align="left" valign="top">Getting ready to chroot +</td></tr> +<tr><td align="left" valign="top">• <a href="#Chroot" accesskey="6">Chroot</a></td><td> </td><td align="left" valign="top">Going inside your new system +</td></tr> +<tr><td align="left" valign="top">• <a href="#System-Configuration" accesskey="7">System Configuration</a></td><td> </td><td align="left" valign="top">Customizing your system for personal use +</td></tr> +<tr><td align="left" valign="top">• <a href="#Kernel" accesskey="8">Kernel</a></td><td> </td><td align="left" valign="top">Compiling your own kernel +</td></tr> +<tr><td align="left" valign="top">• <a href="#Making-your-system-bootable" accesskey="9">Making your system bootable</a></td><td> </td><td align="left" valign="top">Installing bootloader and boot scripts +</td></tr> +<tr><td align="left" valign="top">• <a href="#Post_002dinstallation">Post-installation</a></td><td> </td><td align="left" valign="top">Post-installation tasks +</td></tr> +<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> + +Preparing Environment + +</pre></th></tr><tr><td align="left" valign="top">• <a href="#Download">Download</a></td><td> </td><td align="left" valign="top">Download the root filesystem tarball +</td></tr> +<tr><td align="left" valign="top">• <a href="#Signature-verification">Signature verification</a></td><td> </td><td align="left" valign="top">Verify the signature of the rootfs tarball +</td></tr> +<tr><td align="left" valign="top">• <a href="#Extracting-the-tarball">Extracting the tarball</a></td><td> </td><td align="left" valign="top">Extracting the root filesystem to the desired location +</td></tr> +<tr><td align="left" valign="top">• <a href="#Obtain-the-chroot-helper">Obtain the chroot helper</a></td><td> </td><td align="left" valign="top">Download the script to easily chroot into the new filesystem +</td></tr> +<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> + +Chroot + +</pre></th></tr><tr><td align="left" valign="top">• <a href="#Setting-up-repositories">Setting up repositories</a></td><td> </td><td align="left" valign="top">Basic setup for obtaining repositories +</td></tr> +<tr><td align="left" valign="top">• <a href="#Updating-packages">Updating packages</a></td><td> </td><td align="left" valign="top">Update your system +</td></tr> +<tr><td align="left" valign="top">• <a href="#Installing-packages">Installing packages</a></td><td> </td><td align="left" valign="top">Install new software on your system +</td></tr> +<tr><td align="left" valign="top">• <a href="#Essential-Software">Essential Software</a></td><td> </td><td align="left" valign="top">Software you might want to include on your system +</td></tr> +<tr><td align="left" valign="top">• <a href="#Obtaining-the-documentation">Obtaining the documentation</a></td><td> </td><td align="left" valign="top">Install documentation for offline use (optional) +</td></tr> +<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> + +System Configuration + +</pre></th></tr><tr><td align="left" valign="top">• <a href="#Configuring-hostname">Configuring hostname</a></td><td> </td><td align="left" valign="top">Setting up system hostname (recommended) +</td></tr> +<tr><td align="left" valign="top">• <a href="#Hosts-file">Hosts file</a></td><td> </td><td align="left" valign="top">Setting up hosts file for networking (optional) +</td></tr> +<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> + +Kernel + +</pre></th></tr><tr><td align="left" valign="top">• <a href="#Obtaining-the-kernel-sources">Obtaining the kernel sources</a></td><td> </td><td align="left" valign="top">Downloading the Linux source code +</td></tr> +<tr><td align="left" valign="top">• <a href="#Kernel-dependencies">Kernel dependencies</a></td><td> </td><td align="left" valign="top">Requirements for building the kernel +</td></tr> +<tr><td align="left" valign="top">• <a href="#Building-the-kernel">Building the kernel</a></td><td> </td><td align="left" valign="top">Configure and compile the kernel +</td></tr> +<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> + +Making your system bootable + +</pre></th></tr><tr><td align="left" valign="top">• <a href="#Bootloader">Bootloader</a></td><td> </td><td align="left" valign="top">Install a bootloader for your system +</td></tr> +<tr><td align="left" valign="top">• <a href="#Init-scripts">Init scripts</a></td><td> </td><td align="left" valign="top">Install init scripts for your system +</td></tr> +<tr><td align="left" valign="top">• <a href="#Fstab">Fstab</a></td><td> </td><td align="left" valign="top">Generating fstab +</td></tr> +<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> + +Post-installation + +</pre></th></tr><tr><td align="left" valign="top">• <a href="#KISS-repositories">KISS repositories</a></td><td> </td><td align="left" valign="top">Acquire kiss repositories +</td></tr> +<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> + +Init System + +</pre></th></tr><tr><td align="left" valign="top">• <a href="#Configuring-Init">Configuring Init</a></td><td> </td><td align="left" valign="top">Ways to configure the init system +</td></tr> +<tr><td align="left" valign="top">• <a href="#Changing-Init-Program">Changing Init Program</a></td><td> </td><td align="left" valign="top">Replace the default busybox init with something new +</td></tr> +<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> + +Configuring Init + +</pre></th></tr><tr><td align="left" valign="top">• <a href="#Kernel-Command-Line">Kernel Command Line</a></td><td> </td><td align="left" valign="top">Configure init through the boot parameters +</td></tr> +<tr><td align="left" valign="top">• <a href="#g_t_002fetc_002finit_002frcconf-file">‘<samp>/etc/init/rc.conf</samp>’ file</a></td><td> </td><td align="left" valign="top">Configure init through the configuration file +</td></tr> +<tr><td align="left" valign="top">• <a href="#Init-Hooks">Init Hooks</a></td><td> </td><td align="left" valign="top">Configure init through hooks +</td></tr> +<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> + +Changing Init Program + +</pre></th></tr><tr><td align="left" valign="top">• <a href="#Rebooting-after-changing-init">Rebooting after changing init</a></td><td> </td><td align="left" valign="top">Ways to reboot after replacing the init system +</td></tr> +<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> + +Contribution Guidelines + +</pre></th></tr><tr><td align="left" valign="top">• <a href="#Conventions">Conventions</a></td><td> </td><td align="left" valign="top">Conventions of the distribution +</td></tr> +<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> + +Conventions + +</pre></th></tr><tr><td align="left" valign="top">• <a href="#Shell-Conventions">Shell Conventions</a></td><td> </td><td align="left" valign="top">Conventions for shell scripts +</td></tr> +<tr><td align="left" valign="top">• <a href="#Repository-Conventions">Repository Conventions</a></td><td> </td><td align="left" valign="top">Conventions for repository build scripts +</td></tr> +<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> + +</pre></th></tr></table> + +<hr> +<span id="Installation"></span><div class="header"> +<p> +Next: <a href="#Init-System" accesskey="n" rel="next">Init System</a>, Previous: <a href="#Top" accesskey="p" rel="prev">Top</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Installation-1"></span><h2 class="chapter">1 Installation</h2> + +<p>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 +<a href="https://carbslinux.org/install.txt">https://carbslinux.org/install.txt</a>. +</p> +<div class="example"> +<pre class="example">curl -sL https://carbslinux.org/install.txt | less +</pre></div> + +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Preparing-Environment" accesskey="1">Preparing Environment</a></td><td> </td><td align="left" valign="top">Getting ready to chroot +</td></tr> +<tr><td align="left" valign="top">• <a href="#Chroot" accesskey="2">Chroot</a></td><td> </td><td align="left" valign="top">Going inside your new system +</td></tr> +<tr><td align="left" valign="top">• <a href="#System-Configuration" accesskey="3">System Configuration</a></td><td> </td><td align="left" valign="top">Customizing your system for personal use +</td></tr> +<tr><td align="left" valign="top">• <a href="#Kernel" accesskey="4">Kernel</a></td><td> </td><td align="left" valign="top">Compiling your own kernel +</td></tr> +<tr><td align="left" valign="top">• <a href="#Making-your-system-bootable" accesskey="5">Making your system bootable</a></td><td> </td><td align="left" valign="top">Installing bootloader and boot scripts +</td></tr> +<tr><td align="left" valign="top">• <a href="#Post_002dinstallation" accesskey="6">Post-installation</a></td><td> </td><td align="left" valign="top">Post-installation tasks +</td></tr> +</table> + +<hr> +<span id="Preparing-Environment"></span><div class="header"> +<p> +Next: <a href="#Chroot" accesskey="n" rel="next">Chroot</a>, Up: <a href="#Installation" accesskey="u" rel="up">Installation</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Preparing-Environment-1"></span><h3 class="section">1.1 Preparing Environment</h3> + +<p>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. +</p> +<p>You will need the following programs in order to install Carbs Linux: +</p> +<ul> +<li> tar +</li><li> wget +</li><li> xz +</li><li> some form of base utilities (coreutils, sbase, busybox, etc.) +</li></ul> + +<p>Rest of these instructions will assume that you have set all of these up, and +will continue on that point. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Download" accesskey="1">Download</a></td><td> </td><td align="left" valign="top">Download the root filesystem tarball +</td></tr> +<tr><td align="left" valign="top">• <a href="#Signature-verification" accesskey="2">Signature verification</a></td><td> </td><td align="left" valign="top">Verify the signature of the rootfs tarball +</td></tr> +<tr><td align="left" valign="top">• <a href="#Extracting-the-tarball" accesskey="3">Extracting the tarball</a></td><td> </td><td align="left" valign="top">Extracting the root filesystem to the desired location +</td></tr> +<tr><td align="left" valign="top">• <a href="#Obtain-the-chroot-helper" accesskey="4">Obtain the chroot helper</a></td><td> </td><td align="left" valign="top">Download the script to easily chroot into the new filesystem +</td></tr> +</table> + +<hr> +<span id="Download"></span><div class="header"> +<p> +Next: <a href="#Signature-verification" accesskey="n" rel="next">Signature verification</a>, Up: <a href="#Preparing-Environment" accesskey="u" rel="up">Preparing Environment</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Download-1"></span><h4 class="subsection">1.1.1 Download</h4> + +<p>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 ‘<samp>x86_64</samp>’ +with ‘<samp>i686</samp>’. We are setting this in a URL variable so that we don’t have to +write it every time. +</p> +<div class="example"> +<pre class="example">wget $URL/carbs-rootfs.tar.xz.sha256 +sha256sum -c carbs-rootfs.tar.xz.sha256 +</pre></div> + +<hr> +<span id="Signature-verification"></span><div class="header"> +<p> +Next: <a href="#Extracting-the-tarball" accesskey="n" rel="next">Extracting the tarball</a>, Previous: <a href="#Download" accesskey="p" rel="prev">Download</a>, Up: <a href="#Preparing-Environment" accesskey="u" rel="up">Preparing Environment</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Signature-verification-1"></span><h4 class="subsection">1.1.2 Signature verification</h4> + +<p>It is highly recommended to verify the signature of the tarball. You will need +GPG for this. +</p> +<div class="example"> +<pre class="example">wget $URL/carbs-rootfs.tar.xz.sig +gpg --recv-keys FF484BDFEFCEF8FF +gpg --verify carbs-rootfs.tar.xz.sig +</pre></div> + +<hr> +<span id="Extracting-the-tarball"></span><div class="header"> +<p> +Next: <a href="#Obtain-the-chroot-helper" accesskey="n" rel="next">Obtain the chroot helper</a>, Previous: <a href="#Signature-verification" accesskey="p" rel="prev">Signature verification</a>, Up: <a href="#Preparing-Environment" accesskey="u" rel="up">Preparing Environment</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Extracting-the-tarball-1"></span><h4 class="subsection">1.1.3 Extracting the tarball</h4> + +<p>You will need to extract the tarball to your desired location. For partitioning, +you can follow <a href="https://wiki.archlinux.org/index.php/Partitioning">this guide</a>. This will assume that you will be mounting your root +partition to ‘<samp>/mnt</samp>’. +</p> +<div class="example"> +<pre class="example">mount /dev/sdx1 /mnt +tar xf carbs-rootfs.tar.xz -C /mnt +</pre></div> + +<hr> +<span id="Obtain-the-chroot-helper"></span><div class="header"> +<p> +Previous: <a href="#Extracting-the-tarball" accesskey="p" rel="prev">Extracting the tarball</a>, Up: <a href="#Preparing-Environment" accesskey="u" rel="up">Preparing Environment</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Obtain-the-chroot-helper-1"></span><h4 class="subsection">1.1.4 Obtain the chroot helper</h4> + +<p>You can obtain the ‘<samp>cpt-chroot</samp>’ script in order to do a simple chroot into your +new root filesystem. +</p> +<div class="example"> +<pre class="example">wget https://dl.carbslinux.org/distfiles/cpt-chroot +chmod a+x cpt-chroot +</pre></div> + +<hr> +<span id="Chroot"></span><div class="header"> +<p> +Next: <a href="#System-Configuration" accesskey="n" rel="next">System Configuration</a>, Previous: <a href="#Preparing-Environment" accesskey="p" rel="prev">Preparing Environment</a>, Up: <a href="#Installation" accesskey="u" rel="up">Installation</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Chroot-1"></span><h3 class="section">1.2 Chroot</h3> + +<p>Chroot into Carbs Linux! +</p> +<div class="example"> +<pre class="example">./cpt-chroot /mnt +</pre></div> + +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Setting-up-repositories" accesskey="1">Setting up repositories</a></td><td> </td><td align="left" valign="top">Basic setup for obtaining repositories +</td></tr> +<tr><td align="left" valign="top">• <a href="#Updating-packages" accesskey="2">Updating packages</a></td><td> </td><td align="left" valign="top">Update your system +</td></tr> +<tr><td align="left" valign="top">• <a href="#Installing-packages" accesskey="3">Installing packages</a></td><td> </td><td align="left" valign="top">Install new software on your system +</td></tr> +<tr><td align="left" valign="top">• <a href="#Essential-Software" accesskey="4">Essential Software</a></td><td> </td><td align="left" valign="top">Software you might want to include on your system +</td></tr> +<tr><td align="left" valign="top">• <a href="#Obtaining-the-documentation" accesskey="5">Obtaining the documentation</a></td><td> </td><td align="left" valign="top">Install documentation for offline use (optional) +</td></tr> +</table> + +<hr> +<span id="Setting-up-repositories"></span><div class="header"> +<p> +Next: <a href="#Updating-packages" accesskey="n" rel="next">Updating packages</a>, Up: <a href="#Chroot" accesskey="u" rel="up">Chroot</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Setting-up-repositories-1"></span><h4 class="subsection">1.2.1 Setting up repositories</h4> + +<p>Newest tarballs do not come with repositories, so you will need to manually +obtain them, and set your ‘<samp>CPT_PATH</samp>’ environment variable. Carbs Linux +repositories can either be obtained by ‘<samp>git</samp>’ or ‘<samp>rsync</samp>’. 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 ‘<samp>git</samp>’ itself. +</p> +<p>The following guide will assume that you put the repositories into ‘<samp>~/repos/</samp>’ +directory, but you can put the repositories into any directory you want. So go +ahead and create that directory: +</p> +<div class="example"> +<pre class="example">mkdir -p $HOME/repos +</pre></div> + +<ol> +<li> Obtaining from git + + +<p>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. +</p> +<ul> +<li> git://git.carbslinux.org/repository +</li><li> <a href="https://github.com/carbslinux/repository">https://github.com/carbslinux/repository</a> +</li></ul> + +<div class="example"> +<pre class="example">git clone git://git.carbslinux.org/repository $HOME/repos/carbs +</pre></div> + +</li><li> Obtaining from rsync + + +<p>Carbs Linux rsync repositories live in rsync://carbslinux.org/repo. In +order to obtain it, run the following: +</p> +<div class="example"> +<pre class="example">rsync -avc rsync://carbslinux.org/repo $HOME/repos/carbs +</pre></div> + +</li><li> Making the package manager use the repositories + + +<p>In your shell’s configuration file, or in your ‘<samp>~/.profile</samp>’ file, add the +following lines: +</p> +<div class="example"> +<pre class="example">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 +</pre></div> +</li></ol> + +<hr> +<span id="Updating-packages"></span><div class="header"> +<p> +Next: <a href="#Installing-packages" accesskey="n" rel="next">Installing packages</a>, Previous: <a href="#Setting-up-repositories" accesskey="p" rel="prev">Setting up repositories</a>, Up: <a href="#Chroot" accesskey="u" rel="up">Chroot</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Updating-packages-1"></span><h4 class="subsection">1.2.2 Updating packages</h4> + +<p>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. +</p> +<div class="example"> +<pre class="example">cpt-update && cpt-update +</pre></div> + +<hr> +<span id="Installing-packages"></span><div class="header"> +<p> +Next: <a href="#Essential-Software" accesskey="n" rel="next">Essential Software</a>, Previous: <a href="#Updating-packages" accesskey="p" rel="prev">Updating packages</a>, Up: <a href="#Chroot" accesskey="u" rel="up">Chroot</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Installing-packages-1"></span><h4 class="subsection">1.2.3 Installing packages</h4> + +<p>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. +</p> +<div class="example"> +<pre class="example">cpt-build package +cpt-install package +</pre></div> + +<hr> +<span id="Essential-Software"></span><div class="header"> +<p> +Next: <a href="#Obtaining-the-documentation" accesskey="n" rel="next">Obtaining the documentation</a>, Previous: <a href="#Installing-packages" accesskey="p" rel="prev">Installing packages</a>, Up: <a href="#Chroot" accesskey="u" rel="up">Chroot</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Essential-Software-1"></span><h4 class="subsection">1.2.4 Essential Software</h4> + +<p>Here is a list of software that you might want to have on your system. +</p> +<p><strong>BOOTLOADERS</strong> +</p> +<ul> +<li> efibootmgr +</li><li> grub +</li></ul> + +<p><strong>FILESYSTEMS</strong> +</p> +<ul> +<li> e2fsprogs +</li><li> dosfstools +</li><li> ntfs-3g +</li></ul> + +<p><strong>NETWORKING</strong> +</p> +<ul> +<li> dhcpcd +</li><li> wpa<em>_supplicant</em> +</li></ul> + +<p><strong>TEXT EDITORS</strong> +</p> +<ul> +<li> nano +</li><li> vim +</li><li> neatvi +</li><li> emacs +</li><li> emacs-nox (terminal-only version of emacs) +</li></ul> + +<p><strong>USER SHELLS</strong> +</p> +<ul> +<li> bash +</li><li> zsh +</li><li> oksh +</li><li> rc +</li></ul> + +<p><strong>POSIX BASE UTILITIES</strong> +</p> +<ul> +<li> busybox +</li><li> sbase +</li><li> coreutils +</li></ul> + +<p><strong>DOCUMENTATION</strong> +</p> +<ul> +<li> carbs-docs +</li><li> man-pages +</li><li> man-pages-posix +</li></ul> + +<hr> +<span id="Obtaining-the-documentation"></span><div class="header"> +<p> +Previous: <a href="#Essential-Software" accesskey="p" rel="prev">Essential Software</a>, Up: <a href="#Chroot" accesskey="u" rel="up">Chroot</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Obtaining-the-documentation-1"></span><h4 class="subsection">1.2.5 Obtaining the documentation</h4> + +<p>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. +</p> +<div class="example"> +<pre class="example"># Install the documentation. +cpt b carbs-docs && cpt i carbs-docs + +# Install either texinfo or the info package. We will be installing standalone info +# as it doesn't need perl. +cpt b info && cpt i info + +# You can then run info and navigate through the documentation. +info carbslinux +</pre></div> + +<hr> +<span id="System-Configuration"></span><div class="header"> +<p> +Next: <a href="#Kernel" accesskey="n" rel="next">Kernel</a>, Previous: <a href="#Chroot" accesskey="p" rel="prev">Chroot</a>, Up: <a href="#Installation" accesskey="u" rel="up">Installation</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="System-Configuration-1"></span><h3 class="section">1.3 System Configuration</h3> + +<p>After you have finished installing some extra packages, you can configure your +system to your liking. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Configuring-hostname" accesskey="1">Configuring hostname</a></td><td> </td><td align="left" valign="top">Setting up system hostname (recommended) +</td></tr> +<tr><td align="left" valign="top">• <a href="#Hosts-file" accesskey="2">Hosts file</a></td><td> </td><td align="left" valign="top">Setting up hosts file for networking (optional) +</td></tr> +</table> + +<hr> +<span id="Configuring-hostname"></span><div class="header"> +<p> +Next: <a href="#Hosts-file" accesskey="n" rel="next">Hosts file</a>, Up: <a href="#System-Configuration" accesskey="u" rel="up">System Configuration</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Configuring-hostname-1"></span><h4 class="subsection">1.3.1 Configuring hostname</h4> + +<p>You might want to add a hostname, especially in a networked environment. Your +hostname will default to ’carbslinux’ unless you set this. +</p> +<div class="example"> +<pre class="example">echo your-hostname > /etc/hostname +</pre></div> + +<hr> +<span id="Hosts-file"></span><div class="header"> +<p> +Previous: <a href="#Configuring-hostname" accesskey="p" rel="prev">Configuring hostname</a>, Up: <a href="#System-Configuration" accesskey="u" rel="up">System Configuration</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Hosts-file-1"></span><h4 class="subsection">1.3.2 Hosts file</h4> + +<p>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. +</p> +<div class="example"> +<pre class="example">127.0.0.1 localhost.localdomain localhost +::1 localhost.localdomain localhost ip6-localhost +</pre></div> + +<hr> +<span id="Kernel"></span><div class="header"> +<p> +Next: <a href="#Making-your-system-bootable" accesskey="n" rel="next">Making your system bootable</a>, Previous: <a href="#System-Configuration" accesskey="p" rel="prev">System Configuration</a>, Up: <a href="#Installation" accesskey="u" rel="up">Installation</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Kernel-1"></span><h3 class="section">1.4 Kernel</h3> + +<p>Kernel isn’t managed under the main repositories, even though you could package +one for your personal use. Here is an <a href="https://github.com/cemkeylan/kiss-repository/tree/master/personal/linux">example kernel package</a>, which you will +need to reconfigure for your specific setup if you want to make use of it. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Obtaining-the-kernel-sources" accesskey="1">Obtaining the kernel sources</a></td><td> </td><td align="left" valign="top">Downloading the Linux source code +</td></tr> +<tr><td align="left" valign="top">• <a href="#Kernel-dependencies" accesskey="2">Kernel dependencies</a></td><td> </td><td align="left" valign="top">Requirements for building the kernel +</td></tr> +<tr><td align="left" valign="top">• <a href="#Building-the-kernel" accesskey="3">Building the kernel</a></td><td> </td><td align="left" valign="top">Configure and compile the kernel +</td></tr> +</table> + +<hr> +<span id="Obtaining-the-kernel-sources"></span><div class="header"> +<p> +Next: <a href="#Kernel-dependencies" accesskey="n" rel="next">Kernel dependencies</a>, Up: <a href="#Kernel" accesskey="u" rel="up">Kernel</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Obtaining-the-kernel-sources-1"></span><h4 class="subsection">1.4.1 Obtaining the kernel sources</h4> + +<p>You can visit the <a href="https://kernel.org">https://kernel.org</a> website to choose a kernel that you want +to install. Though only the latest stable and longterm (LTS) versions are +supported. +</p> +<div class="example"> +<pre class="example"># 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 +</pre></div> + +<hr> +<span id="Kernel-dependencies"></span><div class="header"> +<p> +Next: <a href="#Building-the-kernel" accesskey="n" rel="next">Building the kernel</a>, Previous: <a href="#Obtaining-the-kernel-sources" accesskey="p" rel="prev">Obtaining the kernel sources</a>, Up: <a href="#Kernel" accesskey="u" rel="up">Kernel</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Kernel-dependencies-1"></span><h4 class="subsection">1.4.2 Kernel dependencies</h4> + +<p>In order to compile the kernel you will need to install some dependencies. You +will need ‘<samp>libelf</samp>’, and ‘<samp>bison</samp>’ to compile the kernel. If you want to configure +using the menu interface you will also need ‘<samp>ncurses</samp>’. +</p> +<div class="example"> +<pre class="example"># The package manager asks to install if you are building more than one package, +# so no need to run 'cpt i ...' +cpt b libelf ncurses +</pre></div> + +<p>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 <a href="https://github.com/E5ten">E5ten</a>. You will need to obtain and apply the patch in the kernel +source directory. +</p> +<div class="example"> +<pre class="example">wget https://dl.carbslinux.org/distfiles/kernel-no-perl.patch +patch -p1 < kernel-no-perl.patch +</pre></div> + +<hr> +<span id="Building-the-kernel"></span><div class="header"> +<p> +Previous: <a href="#Kernel-dependencies" accesskey="p" rel="prev">Kernel dependencies</a>, Up: <a href="#Kernel" accesskey="u" rel="up">Kernel</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Building-the-kernel-1"></span><h4 class="subsection">1.4.3 Building the kernel</h4> + +<p>Next step is configuring and building the kernel. You can check Gentoo’s +<a href="https://wiki.gentoo.org/wiki/Kernel/Configuration">kernel configuration guide</a> 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. +</p> +<div class="example"> +<pre class="example">make menuconfig +make +install -Dm755 $(make -s image_name) /boot/vmlinuz-linux +</pre></div> + +<hr> +<span id="Making-your-system-bootable"></span><div class="header"> +<p> +Next: <a href="#Post_002dinstallation" accesskey="n" rel="next">Post-installation</a>, Previous: <a href="#Kernel" accesskey="p" rel="prev">Kernel</a>, Up: <a href="#Installation" accesskey="u" rel="up">Installation</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Making-your-system-bootable-1"></span><h3 class="section">1.5 Making your system bootable</h3> + +<p>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. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Bootloader" accesskey="1">Bootloader</a></td><td> </td><td align="left" valign="top">Install a bootloader for your system +</td></tr> +<tr><td align="left" valign="top">• <a href="#Init-scripts" accesskey="2">Init scripts</a></td><td> </td><td align="left" valign="top">Install init scripts for your system +</td></tr> +<tr><td align="left" valign="top">• <a href="#Fstab" accesskey="3">Fstab</a></td><td> </td><td align="left" valign="top">Generating fstab +</td></tr> +</table> + +<hr> +<span id="Bootloader"></span><div class="header"> +<p> +Next: <a href="#Init-scripts" accesskey="n" rel="next">Init scripts</a>, Up: <a href="#Making-your-system-bootable" accesskey="u" rel="up">Making your system bootable</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Bootloader-1"></span><h4 class="subsection">1.5.1 Bootloader</h4> + +<p>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). +</p> +<ol> +<li> GRUB BIOS installation + + +<div class="example"> +<pre class="example">cpt b grub && cpt i grub +grub-install --target=i386-pc /dev/sdX +grub-mkconfig -o /boot/grub/grub.cfg +</pre></div> + +</li><li> GRUB UEFI installation + + +<div class="example"> +<pre class="example">cpt b efibootmgr && cpt i efibootmgr +cpt b grub && cpt i grub + +grub-install --target=x86_64-efi \ + --efi-directory=esp \ + --bootloader-id=CarbsLinux + +grub-mkconfig -o /boot/grub/grub.cfg +</pre></div> +</li></ol> + +<hr> +<span id="Init-scripts"></span><div class="header"> +<p> +Next: <a href="#Fstab" accesskey="n" rel="next">Fstab</a>, Previous: <a href="#Bootloader" accesskey="p" rel="prev">Bootloader</a>, Up: <a href="#Making-your-system-bootable" accesskey="u" rel="up">Making your system bootable</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Init-scripts-1"></span><h4 class="subsection">1.5.2 Init scripts</h4> + +<p>Only thing left to do is installing the init-scripts, and now you are almost +ready to boot your system! +</p> +<div class="example"> +<pre class="example">cpt b carbs-init && cpt i carbs-init +</pre></div> + +<hr> +<span id="Fstab"></span><div class="header"> +<p> +Previous: <a href="#Init-scripts" accesskey="p" rel="prev">Init scripts</a>, Up: <a href="#Making-your-system-bootable" accesskey="u" rel="up">Making your system bootable</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Fstab-1"></span><h4 class="subsection">1.5.3 Fstab</h4> + +<p>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: +</p> +<div class="example"> +<pre class="example">wget https://github.com/cemkeylan/genfstab/raw/master/genfstab +chmod +x genfstab +./genfstab -U /mnt >> /mnt/etc/fstab +</pre></div> + +<hr> +<span id="Post_002dinstallation"></span><div class="header"> +<p> +Previous: <a href="#Making-your-system-bootable" accesskey="p" rel="prev">Making your system bootable</a>, Up: <a href="#Installation" accesskey="u" rel="up">Installation</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Post_002dinstallation-1"></span><h3 class="section">1.6 Post-installation</h3> + +<p>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. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#KISS-repositories" accesskey="1">KISS repositories</a></td><td> </td><td align="left" valign="top">Acquire kiss repositories +</td></tr> +</table> + +<hr> +<span id="KISS-repositories"></span><div class="header"> +<p> +Up: <a href="#Post_002dinstallation" accesskey="u" rel="up">Post-installation</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="KISS-repositories-1"></span><h4 class="subsection">1.6.1 KISS repositories</h4> + +<p>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. +</p> +<hr> +<span id="Init-System"></span><div class="header"> +<p> +Next: <a href="#Contribution-Guidelines" accesskey="n" rel="next">Contribution Guidelines</a>, Previous: <a href="#Installation" accesskey="p" rel="prev">Installation</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Init-System-1"></span><h2 class="chapter">2 Init System</h2> + +<p>Carbs Linux init scripts are run by the init daemon (‘<samp>busybox</samp>’ 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. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Configuring-Init" accesskey="1">Configuring Init</a></td><td> </td><td align="left" valign="top">Ways to configure the init system +</td></tr> +<tr><td align="left" valign="top">• <a href="#Changing-Init-Program" accesskey="2">Changing Init Program</a></td><td> </td><td align="left" valign="top">Replace the default busybox init with something new +</td></tr> +</table> + +<hr> +<span id="Configuring-Init"></span><div class="header"> +<p> +Next: <a href="#Changing-Init-Program" accesskey="n" rel="next">Changing Init Program</a>, Up: <a href="#Init-System" accesskey="u" rel="up">Init System</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Configuring-Init-1"></span><h3 class="section">2.1 Configuring Init</h3> + +<p>There are three ways you can change the behaviour of the init system. Those are: +</p> +<ul> +<li> Kernel Command Line +</li><li> ‘<samp>/etc/init/rc.conf</samp>’ file +</li><li> Init Hooks +</li></ul> + +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Kernel-Command-Line" accesskey="1">Kernel Command Line</a></td><td> </td><td align="left" valign="top">Configure init through the boot parameters +</td></tr> +<tr><td align="left" valign="top">• <a href="#g_t_002fetc_002finit_002frcconf-file" accesskey="2">‘<samp>/etc/init/rc.conf</samp>’ file</a></td><td> </td><td align="left" valign="top">Configure init through the configuration file +</td></tr> +<tr><td align="left" valign="top">• <a href="#Init-Hooks" accesskey="3">Init Hooks</a></td><td> </td><td align="left" valign="top">Configure init through hooks +</td></tr> +</table> + +<hr> +<span id="Kernel-Command-Line"></span><div class="header"> +<p> +Next: <a href="#g_t_002fetc_002finit_002frcconf-file" accesskey="n" rel="next">‘<samp>/etc/init/rcconf</samp>’ file</a>, Up: <a href="#Configuring-Init" accesskey="u" rel="up">Configuring Init</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Kernel-Command-Line-1"></span><h4 class="subsection">2.1.1 Kernel Command Line</h4> + +<p>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. +</p> +<div class="example"> +<pre class="example">BOOT_IMAGE=/boot/vmlinuz root=/dev/sda2 rw loglevel=3 quiet +</pre></div> + +<p>This command line will be parsed to set the following variables: +</p> +<div class="example"> +<pre class="example">BOOT_IMAGE=/boot/vmlinuz +root=/dev/sda2 +rw=1 +loglevel=3 +quiet=1 +</pre></div> + +<p>Some of these variables, such as ‘<samp>rw=/=ro</samp>’, ‘<samp>loglevel</samp>’, and ‘<samp>quiet</samp>’, will be +used by the init system to change the behaviour of the startup. +</p> +<hr> +<span id="g_t_002fetc_002finit_002frcconf-file"></span><div class="header"> +<p> +Next: <a href="#Init-Hooks" accesskey="n" rel="next">Init Hooks</a>, Previous: <a href="#Kernel-Command-Line" accesskey="p" rel="prev">Kernel Command Line</a>, Up: <a href="#Configuring-Init" accesskey="u" rel="up">Configuring Init</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="g_t_002fetc_002finit_002frc_002econf-file"></span><h4 class="subsection">2.1.2 ‘<samp>/etc/init/rc.conf</samp>’ file</h4> + +<p>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. +</p> +<hr> +<span id="Init-Hooks"></span><div class="header"> +<p> +Previous: <a href="#g_t_002fetc_002finit_002frcconf-file" accesskey="p" rel="prev">‘<samp>/etc/init/rcconf</samp>’ file</a>, Up: <a href="#Configuring-Init" accesskey="u" rel="up">Configuring Init</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Init-Hooks-1"></span><h4 class="subsection">2.1.3 Init Hooks</h4> + +<p>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 ‘<samp>/etc/init</samp>’ directory with the +hook name as the suffix. For example, a boot script will be placed as +‘<samp>/etc/init/my-hook.boot</samp>’. Currently, there are 4 hooks that the user can use. +</p> +<dl compact="compact"> +<dt>early-boot</dt> +<dd><p>Run after pseudo-filesystems are mounted. +</p></dd> +<dt>boot</dt> +<dd><p>Run before the boot stage is completed. +</p></dd> +<dt>pre.shutdown</dt> +<dd><p>Run first when shutting down. +</p></dd> +<dt>umount</dt> +<dd><p>Run just before filesystems are unmounted. +</p></dd> +<dt>post.shutdown</dt> +<dd><p>Run just before the system is halted. +</p></dd> +</dl> + +<hr> +<span id="Changing-Init-Program"></span><div class="header"> +<p> +Previous: <a href="#Configuring-Init" accesskey="p" rel="prev">Configuring Init</a>, Up: <a href="#Init-System" accesskey="u" rel="up">Init System</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Changing-Init-Program-1"></span><h3 class="section">2.2 Changing Init Program</h3> + +<p>By default, Carbs Linux comes preinstalled with ‘<samp>busybox-init</samp>’, but this can +easily be replaced without any issues. Currently, available init systems are: +</p> +<ul> +<li> ‘<samp>sinit</samp>’ +</li><li> ‘<samp>busybox</samp>’ +</li><li> ‘<samp>runit</samp>’ +</li><li> ‘<samp>shinit</samp>’ +</li></ul> + +<p>This example is for runit, but it will work with all init systems packaged in the +distribution repositories. See the ‘<samp>cpt-alternatives(1)</samp>’ manual page for more +details. +</p> +<div class="example"> +<pre class="example">cpt a runit /usr/bin/init +cpt a runit /usr/bin/poweroff +cpt a runit /usr/bin/reboot +</pre></div> + +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Rebooting-after-changing-init" accesskey="1">Rebooting after changing init</a></td><td> </td><td align="left" valign="top">Ways to reboot after replacing the init system +</td></tr> +</table> + +<hr> +<span id="Rebooting-after-changing-init"></span><div class="header"> +<p> +Up: <a href="#Changing-Init-Program" accesskey="u" rel="up">Changing Init Program</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Rebooting-after-changing-init-1"></span><h4 class="subsection">2.2.1 Rebooting after changing init</h4> + +<p>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. +</p> +<table> +<thead><tr><th>Program</th><th>Command</th></tr></thead> +<tr><td>busybox</td><td>‘<samp>busybox reboot</samp>’</td></tr> +<tr><td>runit</td><td>‘<samp>runit-init 6</samp>’</td></tr> +<tr><td>shinit/sinit</td><td>‘<samp>kill -s INT 1</samp>’</td></tr> +</table> + +<hr> +<span id="Contribution-Guidelines"></span><div class="header"> +<p> +Next: <a href="#GNU-Free-Documentation-License" accesskey="n" rel="next">GNU Free Documentation License</a>, Previous: <a href="#Init-System" accesskey="p" rel="prev">Init System</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Contribution-Guidelines-1"></span><h2 class="chapter">3 Contribution Guidelines</h2> + +<p>Thanks for taking your time to contribute! To maintain stylistic behaviour +throughout the repositories, one must adhere to these conventions. Exceptions +and changes may occur with good reasoning. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Conventions" accesskey="1">Conventions</a></td><td> </td><td align="left" valign="top">Conventions of the distribution +</td></tr> +</table> + +<hr> +<span id="Conventions"></span><div class="header"> +<p> +Up: <a href="#Contribution-Guidelines" accesskey="u" rel="up">Contribution Guidelines</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Conventions-1"></span><h3 class="section">3.1 Conventions</h3> + + + +<dl compact="compact"> +<dt>[<span id="g_t0010"></span>0010]</dt> +<dd><p>Try to keep the file readable. +</p><dl compact="compact"> +<dt>[<span id="g_t0011"></span>0011]</dt> +<dd><p>Characters on a line shouldn’t exceed 100 characters. +</p></dd> +<dt>[<span id="g_t0012"></span>0012]</dt> +<dd><p>Make sure you don’t have code commented out during +commit. Uncomment them or remove them completely. +</p></dd> +<dt>[<span id="g_t0013"></span>0013]</dt> +<dd><p>Do not add comments following the code, add them to the +top of the code. It makes it harder to read, and lines longer. Here is an example: +</p></dd> +</dl> + +<div class="example"> +<pre class="example"># Good way of commenting. +your code goes here + +your code goes here # Avoid this way of commenting. +</pre></div> +</dd> +</dl> + +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Shell-Conventions" accesskey="1">Shell Conventions</a></td><td> </td><td align="left" valign="top">Conventions for shell scripts +</td></tr> +<tr><td align="left" valign="top">• <a href="#Repository-Conventions" accesskey="2">Repository Conventions</a></td><td> </td><td align="left" valign="top">Conventions for repository build scripts +</td></tr> +</table> + +<hr> +<span id="Shell-Conventions"></span><div class="header"> +<p> +Next: <a href="#Repository-Conventions" accesskey="n" rel="next">Repository Conventions</a>, Up: <a href="#Conventions" accesskey="u" rel="up">Conventions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Shell-Conventions-1"></span><h4 class="subsection">3.1.1 Shell Conventions</h4> + +<p>Shell is central to Carbs Linux projects. Most of the tools and packages are +written in POSIX sh. +</p> +<dl compact="compact"> +<dt>[<span id="g_t1010"></span>1010]</dt> +<dd><p>Use 4 spaces for indentation, don’t use tabs. +</p></dd> +<dt>[<span id="g_t1020"></span>1020]</dt> +<dd><p>Make sure you don’t use bash-specific code. +</p></dd> +<dt>[<span id="g_t1030"></span>1030]</dt> +<dd><p>Make sure you lint your code with ‘<samp>shellcheck</samp>’ and if +you are new to POSIX sh, use ‘<samp>checkbashisms</samp>’. +</p></dd> +<dt>[<span id="g_t1040"></span>1040]</dt> +<dd><p>Don’t spawn new processes if you don’t absolutely need +to, especially during string manipulation. +</p><dl compact="compact"> +<dt>[<span id="g_t1041"></span>1041]</dt> +<dd><p>Never use a program for text manupilation that isn’t +defined in the POSIX standard. This includes ‘<samp>gawk</samp>’ and ‘<samp>perl</samp>’. +</p></dd> +<dt>[<span id="g_t1042"></span>1042]</dt> +<dd><p>Instead of <code>$(basename $file)</code>, use <code>${file##*}</code>. +</p></dd> +<dt>[<span id="g_t1043"></span>1043]</dt> +<dd><p>Instead of <code>$(dirname $file)</code>, use <code>${file%/*}</code>. +</p></dd> +</dl> + +<div class="example"> +<pre class="example"># This is the same thing as basename /path/to/test.asc .asc + +$ file=/path/to/test.asc file=${file##*/} file=${file%.asc} +$ echo $file +test +</pre></div> +</dd> +<dt>[<span id="g_t1050"></span>1050]</dt> +<dd><p>Instead of backticks, use <code>$(..)</code>. +</p></dd> +</dl> + +<hr> +<span id="Repository-Conventions"></span><div class="header"> +<p> +Previous: <a href="#Shell-Conventions" accesskey="p" rel="prev">Shell Conventions</a>, Up: <a href="#Conventions" accesskey="u" rel="up">Conventions</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="Repository-Conventions-1"></span><h4 class="subsection">3.1.2 Repository Conventions</h4> + +<p>Repository conventions are important in order to ensure every package resemble +themselves. Here are the things to keep in mind: +</p> +<dl compact="compact"> +<dt>[<span id="g_t2010"></span>2010]</dt> +<dd><p>Prefer tarballs over git packages unless there is a +sensible reason. Here are some: +</p><ul> +<li> Every patch is a new release. (See <a href="https://github.com/vim/vim">vim</a>) +</li><li> There are no releases. (See <a href="https://git.suckless.org/sbase">sbase</a>) +</li><li> Following a development branch. +</li><li> There has been a long time since the latest release, but upstream is far +ahead. +</li></ul> +</dd> +<dt>[<span id="g_t2020"></span>2020]</dt> +<dd><p>Prefer sources without a dependency to ‘<samp>automake</samp>’. There +are usually distribution tarballs that are ‘<samp>autoconf</samp>’’ed. Don’t submit tarballs +with an automake dependency unless you are ‘<samp>sure</samp>’ there is no alternative. +</p></dd> +<dt>[<span id="g_t2030"></span>2030]</dt> +<dd><p>Avoid these packages: +</p><dl compact="compact"> +<dt>dbus</dt> +<dd><p>Usually can be disabled by <code>--disable-dbus</code>. +</p></dd> +<dt>gettext</dt> +<dd><p>Usually can be disabled by <code>--disable-nls</code>. +</p></dd> +</dl> +</dd> +<dt>[<span id="g_t2040"></span>2040]</dt> +<dd><ul> +<li> Always install a package to the ‘<samp>/usr</samp>’ prefix. +</li><li> All binaries should go to ‘<samp>/usr/bin</samp>’, not ‘<samp>/usr/sbin</samp>’ or any other directory. +</li><li> All libraries should go to ‘<samp>/usr/lib</samp>’. +</li></ul> +</dd> +<dt>[<span id="g_t2050"></span>2050]</dt> +<dd><p>All build files on the repository should be a POSIX +shell script, and must start with <code>#!/bin/sh -e</code>. +</p></dd> +</dl> + +<p>The next section is about package templates that should be used in order to +ensure stylistic consistency. Note that the option configurations shouldn’t be +taken literally, they are meant as examples. +</p> +<ol> +<li> Make [<span id="g_t2210"></span>2210] + + +<div class="example"> +<pre class="example">#!/bin/sh -e + +make +make DESTDIR="$1" PREFIX=/usr install +</pre></div> + +</li><li> Configure/Make [<span id="g_t2211"></span>2211] + + +<div class="example"> +<pre class="example">#!/bin/sh -e + +./configure \ + --prefix=/usr \ + --disable-option \ + --enable-option + +make +make DESTDIR="$1" install +</pre></div> + +</li><li> Autoconf/Automake [<span id="g_t2212"></span>2212] + + +<p>See <a href="#g_t2020">2020</a> +</p> +<div class="example"> +<pre class="example">#!/bin/sh -e + +autoreconf -fi + +./configure \ + --prefix=/usr \ + --disable-option \ + --enable-option + +make +make DESTDIR="$1" install +</pre></div> + +</li><li> Meson [<span id="g_t2220"></span>2220] + + +<div class="example"> +<pre class="example">#!/bin/sh -e + +export DESTDIR=$1 + +meson \ + --prefix=/usr \ + -Doption=false \ + -Doption2=true \ + . output + +ninja -C output +ninja -C output install +</pre></div> + +</li><li> Cmake [<span id="g_t2230"></span>2230] + + +<div class="example"> +<pre class="example">#!/bin/sh -e + +export DESTDIR=$1 + +cmake -B build \ + -DCMAKE_INSTALL_PREFIX=/usr \ + -DCMAKE_BUILD_TYPE=Release \ + -DOPTION=ON + +cmake --build build +cmake --install build +</pre></div> + +</li><li> Go [<span id="g_t2240"></span>2240] + + +<div class="example"> +<pre class="example">#!/bin/sh -e + +export GOPATH=$PWD/gopath +trap "go clean -modcache" EXIT INT +go mod vendor + +go build +install -Dm755 program "$1/usr/bin/program" +</pre></div> + +</li><li> Python [<span id="g_t2241"></span>2241] + + +<div class="example"> +<pre class="example">#!/bin/sh -e + +python setup.py build +python setup.py install --prefix=/usr --root="$1" +</pre></div> +</li></ol> + +<hr> +<span id="GNU-Free-Documentation-License"></span><div class="header"> +<p> +Previous: <a href="#Contribution-Guidelines" accesskey="p" rel="prev">Contribution Guidelines</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<span id="GNU-Free-Documentation-License-1"></span><h2 class="appendix">Appendix A GNU Free Documentation License</h2> + +<div align="center">Version 1.3, 3 November 2008 +</div> +<div class="display"> +<pre class="display">Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. +<a href="http://fsf.org/">http://fsf.org/</a> + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +</pre></div> + +<ol start="0"> +<li> PREAMBLE + +<p>The purpose of this License is to make a manual, textbook, or other +functional and useful document <em>free</em> +in the sense of freedom: to assure everyone the effective freedom +to copy and redistribute it, with or without modifying it, either +commercially or noncommercially. Secondarily, this License +preserves for the author and publisher a way to get credit for +their work, while not being considered responsible for +modifications made by others. +</p> +<p>This License is a kind of "copyleft", which means that derivative +works of the document must themselves be free in the same sense. +It complements the GNU General Public License, which is a copyleft +license designed for free software. +</p> +<p>We have designed this License in order to use it for manuals for +free software, because free software needs free documentation: +a free program should come with manuals providing the same freedoms +that the software does. But this License is not limited to +software manuals; it can be used for any textual work, regardless +of subject matter or whether it is published as a printed book. We +recommend this License principally for works whose purpose is +instruction or reference. +</p> +</li><li> APPLICABILITY AND DEFINITIONS + +<p>This License applies to any manual or other work, in any medium, +that contains a notice placed by the copyright holder saying it can +be distributed under the terms of this License. Such a notice +grants a world-wide, royalty-free license, unlimited in duration, +to use that work under the conditions stated herein. The +"Document", below, refers to any such manual or work. Any member +of the public is a licensee, and is addressed as "you". You accept +the license if you copy, modify or distribute the work in a way +requiring permission under copyright law. +</p> +<p>A "Modified Version" of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. +</p> +<p>A "Secondary Section" is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document’s overall +subject (or to related matters) and contains nothing that could +fall directly within that overall subject. (Thus, if the Document +is in part a textbook of mathematics, a Secondary Section may not +explain any mathematics.) The relationship could be a matter of +historical connection with the subject or with related matters, or +of legal, commercial, philosophical, ethical or political position +regarding them. +</p> +<p>The "Invariant Sections" are certain Secondary Sections whose +titles are designated, as being those of Invariant Sections, in the +notice that says that the Document is released under this License. +If a section does not fit the above definition of Secondary then it +is not allowed to be designated as Invariant. The Document may +contain zero Invariant Sections. If the Document does not identify +any Invariant Sections then there are none. +</p> +<p>The "Cover Texts" are certain short passages of text that are +listed, as Front-Cover Texts or Back-Cover Texts, in the notice +that says that the Document is released under this License. +A Front-Cover Text may be at most 5 words, and a Back-Cover Text +may be at most 25 words. +</p> +<p>A "Transparent" copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed +of pixels) generic paint programs or (for drawings) some widely +available drawing editor, and that is suitable for input to text +formatters or for automatic translation to a variety of formats +suitable for input to text formatters. A copy made in an otherwise +Transparent file format whose markup, or absence of markup, has +been arranged to thwart or discourage subsequent modification by +readers is not Transparent. An image format is not Transparent if +used for any substantial amount of text. A copy that is not +"Transparent" is called "Opaque". +</p> +<p>Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, +SGML or XML using a publicly available DTD, and standard-conforming +simple HTML, PostScript or PDF designed for human modification. +Examples of transparent image formats include PNG, XCF and JPG. +Opaque formats include proprietary formats that can be read and +edited only by proprietary word processors, SGML or XML for which +the DTD and/or processing tools are not generally available, and +the machine-generated HTML, PostScript or PDF produced by some word +processors for output purposes only. +</p> +<p>The "Title Page" means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the +material this License requires to appear in the title page. For +works in formats which do not have any title page as such, "Title +Page" means the text near the most prominent appearance of the +work’s title, preceding the beginning of the body of the text. +</p> +<p>The "publisher" means any person or entity that distributes copies +of the Document to the public. +</p> +<p>A section "Entitled XYZ" means a named subunit of the Document +whose title either is precisely XYZ or contains XYZ in parentheses +following text that translates XYZ in another language. (Here XYZ +stands for a specific section name mentioned below, such as +"Acknowledgements", "Dedications", "Endorsements", or "History".) +To "Preserve the Title" of such a section when you modify the +Document means that it remains a section "Entitled XYZ" according +to this definition. +</p> +<p>The Document may include Warranty Disclaimers next to the notice +which states that this License applies to the Document. These +Warranty Disclaimers are considered to be included by reference in +this License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and +has no effect on the meaning of this License. +</p> +</li><li> VERBATIM COPYING + +<p>You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License +applies to the Document are reproduced in all copies, and that you +add no other conditions whatsoever to those of this License. You +may not use technical measures to obstruct or control the reading +or further copying of the copies you make or distribute. However, +you may accept compensation in exchange for copies. If you +distribute a large enough number of copies you must also follow the +conditions in section 3. +</p> +<p>You may also lend copies, under the same conditions stated above, +and you may publicly display copies. +</p> +</li><li> COPYING IN QUANTITY + +<p>If you publish printed copies (or copies in media that commonly +have printed covers) of the Document, numbering more than 100, and +the Document’s license notice requires Cover Texts, you must +enclose the copies in covers that carry, clearly and legibly, all +these Cover Texts: Front-Cover Texts on the front cover, and +Back-Cover Texts on the back cover. Both covers must also clearly +and legibly identify you as the publisher of these copies. The +front cover must present the full title with all words of the title +equally prominent and visible. You may add other material on the +covers in addition. Copying with changes limited to the covers, as +long as they preserve the title of the Document and satisfy these +conditions, can be treated as verbatim copying in other respects. +</p> +<p>If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto +adjacent pages. +</p> +<p>If you publish or distribute Opaque copies of the Document +numbering more than 100, you must either include a machine-readable +Transparent copy along with each Opaque copy, or state in or with +each Opaque copy a computer-network location from which the general +network-using public has access to download using public-standard +network protocols a complete Transparent copy of the Document, free +of added material. If you use the latter option, you must take +reasonably prudent steps, when you begin distribution of Opaque +copies in quantity, to ensure that this Transparent copy will +remain thus accessible at the stated location until at least one +year after the last time you distribute an Opaque copy (directly or +through your agents or retailers) of that edition to the public. +</p> +<p>It is requested, but not required, that you contact the authors of +the Document well before redistributing any large number of copies, +to give them a chance to provide you with an updated version of the +Document. +</p> +</li><li> MODIFICATIONS + +<p>You may copy and distribute a Modified Version of the Document +under the conditions of sections 2 and 3 above, provided that you +release the Modified Version under precisely this License, with the +Modified Version filling the role of the Document, thus licensing +distribution and modification of the Modified Version to whoever +possesses a copy of it. In addition, you must do these things in +the Modified Version: +</p> +<ol type="A" start="1"> +<li> Use in the Title Page (and on the covers, if any) a title +distinct from that of the Document, and from those of previous +versions (which should, if there were any, be listed in the +History section of the Document). You may use the same title as +a previous version if the original publisher of that version +gives permission. + +</li><li> List on the Title Page, as authors, one or more persons or +entities responsible for authorship of the modifications in the +Modified Version, together with at least five of the principal +authors of the Document (all of its principal authors, if it has +fewer than five), unless they release you from this requirement. + +</li><li> State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +</li><li> Preserve all the copyright notices of the Document. + +</li><li> Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +</li><li> Include, immediately after the copyright notices, a license +notice giving the public permission to use the Modified Version +under the terms of this License, in the form shown in the +Addendum below. + +</li><li> Preserve in that license notice the full lists of Invariant +Sections and required Cover Texts given in the Document’s +license notice. + +</li><li> Include an unaltered copy of this License. + +</li><li> Preserve the section Entitled "History", Preserve its Title, and +add to it an item stating at least the title, year, new authors, +and publisher of the Modified Version as given on the Title +Page. If there is no section Entitled "History" in the Document, +create one stating the title, year, authors, and publisher of +the Document as given on its Title Page, then add an item +describing the Modified Version as stated in the previous +sentence. + +</li><li> Preserve the network location, if any, given in the Document +for public access to a Transparent copy of the Document, and +likewise the network locations given in the Document for +previous versions it was based on. These may be placed in the +"History" section. You may omit a network location for a work +that was published at least four years before the Document +itself, or if the original publisher of the version it refers +to gives permission. + +</li><li> For any section Entitled "Acknowledgements" or "Dedications", +Preserve the Title of the section, and preserve in the section +all the substance and tone of each of the contributor +acknowledgements and/or dedications given therein. + +</li><li> Preserve all the Invariant Sections of the Document, unaltered +in their text and in their titles. Section numbers or the +equivalent are not considered part of the section titles. + +</li><li> Delete any section Entitled "Endorsements". Such a section may +not be included in the Modified Version. + +</li><li> Do not retitle any existing section to be Entitled +"Endorsements" or to conflict in title with any Invariant +Section. + +</li><li> Preserve any Warranty Disclaimers. +</li></ol> + +<p>If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version’s license notice. +These titles must be distinct from any other section titles. +</p> +<p>You may add a section Entitled "Endorsements", provided it contains +nothing but endorsements of your Modified Version by various +parties—for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. +</p> +<p>You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. +</p> +<p>The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. +</p> +</li><li> COMBINING DOCUMENTS + +<p>You may combine the Document with other documents released under +this License, under the terms defined in section 4 above for +modified versions, provided that you include in the combination all +of the Invariant Sections of all of the original documents, +unmodified, and list them all as Invariant Sections of your +combined work in its license notice, and that you preserve all +their Warranty Disclaimers. +</p> +<p>The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name +but different contents, make the title of each such section unique +by adding at the end of it, in parentheses, the name of the +original author or publisher of that section if known, or else +a unique number. Make the same adjustment to the section titles in +the list of Invariant Sections in the license notice of the +combined work. +</p> +<p>In the combination, you must combine any sections Entitled +"History" in the various original documents, forming one section +Entitled "History"; likewise combine any sections Entitled +"Acknowledgements", and any sections Entitled "Dedications". You +must delete all sections Entitled "Endorsements." +</p> +</li><li> COLLECTIONS OF DOCUMENTS + +<p>You may make a collection consisting of the Document and other +documents released under this License, and replace the individual +copies of this License in the various documents with a single copy +that is included in the collection, provided that you follow the +rules of this License for verbatim copying of each of the documents +in all other respects. +</p> +<p>You may extract a single document from such a collection, and +distribute it individually under this License, provided you insert +a copy of this License into the extracted document, and follow this +License in all other respects regarding verbatim copying of that +document. +</p> +</li><li> AGGREGATION WITH INDEPENDENT WORKS + +<p>A compilation of the Document or its derivatives with other +separate and independent documents or works, in or on a volume of +a storage or distribution medium, is called an "aggregate" if the +copyright resulting from the compilation is not used to limit the +legal rights of the compilation’s users beyond what the individual +works permit. When the Document is included in an aggregate, this +License does not apply to the other works in the aggregate which +are not themselves derivative works of the Document. +</p> +<p>If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half +of the entire aggregate, the Document’s Cover Texts may be placed +on covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic +form. Otherwise they must appear on printed covers that bracket +the whole aggregate. +</p> +</li><li> TRANSLATION + +<p>Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of +section 4. Replacing Invariant Sections with translations requires +special permission from their copyright holders, but you may +include translations of some or all Invariant Sections in addition +to the original versions of these Invariant Sections. You may +include a translation of this License, and all the license notices +in the Document, and any Warranty Disclaimers, provided that you +also include the original English version of this License and the +original versions of those notices and disclaimers. In case of +a disagreement between the translation and the original version of +this License or a notice or disclaimer, the original version will +prevail. +</p> +<p>If a section in the Document is Entitled "Acknowledgements", +"Dedications", or "History", the requirement (section 4) to +Preserve its Title (section 1) will typically require changing the +actual title. +</p> +</li><li> TERMINATION + +<p>You may not copy, modify, sublicense, or distribute the Document +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense, or distribute it is void, +and will automatically terminate your rights under this License. +</p> +<p>However, if you cease all violation of this License, then your +license from a particular copyright holder is reinstated (a) +provisionally, unless and until the copyright holder explicitly and +finally terminates your license, and (b) permanently, if the +copyright holder fails to notify you of the violation by some +reasonable means prior to 60 days after the cessation. +</p> +<p>Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from +that copyright holder, and you cure the violation prior to 30 days +after your receipt of the notice. +</p> +<p>Termination of your rights under this section does not terminate +the licenses of parties who have received copies or rights from you +under this License. If your rights have been terminated and not +permanently reinstated, receipt of a copy of some or all of the +same material does not give you any rights to use it. +</p> +</li><li> FUTURE REVISIONS OF THIS LICENSE + +<p>The Free Software Foundation may publish new, revised versions of +the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +<a href="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</a>. +</p> +<p>Each version of the License is given a distinguishing version +number. If the Document specifies that a particular numbered +version of this License "or any later version" applies to it, you +have the option of following the terms and conditions either of +that specified version or of any later version that has been +published (not as a draft) by the Free Software Foundation. If +the Document does not specify a version number of this License, +you may choose any version ever published (not as a draft) by the +Free Software Foundation. If the Document specifies that a proxy +can decide which future versions of this License can be used, that +proxy’s public statement of acceptance of a version permanently +authorizes you to choose that version for the Document. +</p> +</li><li> RELICENSING + +<p>"Massive Multiauthor Collaboration Site" (or "MMC Site") means any +World Wide Web server that publishes copyrightable works and also +provides prominent facilities for anybody to edit those works. +A public wiki that anybody can edit is an example of such +a server. A "Massive Multiauthor Collaboration" (or "MMC") +contained in the site means any set of copyrightable works thus +published on the MMC site. +</p> +<p>"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 +license published by Creative Commons Corporation, +a not-for-profit corporation with a principal place of business in +San Francisco, California, as well as future copyleft versions of +that license published by that same organization. +</p> +<p>"Incorporate" means to publish or republish a Document, in whole +or in part, as part of another Document. +</p> +<p>An MMC is "eligible for relicensing" if it is licensed under this +License, and if all works that were first published under this +License somewhere other than this MMC, and subsequently +incorporated in whole or in part into the MMC, (1) had no cover +texts or invariant sections, and (2) were thus incorporated prior +to November 1, 2008. +</p> +<p>The operator of an MMC Site may republish an MMC contained in the +site under CC-BY-SA on the same site at any time before August 1, +2009, provided the MMC is eligible for relicensing. +</p></li></ol> + + +<span id="ADDENDUM-How-to-use-this-License-for-your-documents"></span><span id="ADDENDUM_003a-How-to-use-this-License-for-your-documents"></span><h3 class="appendixsec">A.1 ADDENDUM: How to use this License for your documents</h3> + +<p>To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: +</p> +<div class="example"> +<pre class="example">Copyright (C) YEAR YOUR NAME. +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 +or any later version published by the Free Software Foundation; +with no Invariant Sections, no Front-Cover Texts, and no Back-Cover +Texts. A copy of the license is included in the section entitled ``GNU +Free Documentation License''. +</pre></div> + +<p>If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the "with…Texts." line with this: +</p> +<div class="example"> +<pre class="example">with the Invariant Sections being LIST THEIR TITLES, with +the Front-Cover Texts being LIST, and with the Back-Cover Texts +being LIST. +</pre></div> + +<p>If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. +</p> +<p>If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, to +permit their use in free software. +</p> +<hr> + + + +</body> +</html> |