summaryrefslogtreecommitdiffstats
path: root/build_tools/l7/larch0/docs/html/profiles.html
diff options
context:
space:
mode:
Diffstat (limited to 'build_tools/l7/larch0/docs/html/profiles.html')
-rw-r--r--build_tools/l7/larch0/docs/html/profiles.html326
1 files changed, 326 insertions, 0 deletions
diff --git a/build_tools/l7/larch0/docs/html/profiles.html b/build_tools/l7/larch0/docs/html/profiles.html
new file mode 100644
index 0000000..a4c4a22
--- /dev/null
+++ b/build_tools/l7/larch0/docs/html/profiles.html
@@ -0,0 +1,326 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+
+<html>
+<head>
+<meta http-equiv="Content-type" content="text/html; charset=utf-8" />
+<title>Profiles</title>
+<!-- (en) Add your meta data here -->
+
+<link href="css/larchdocs.css" rel="stylesheet" type="text/css"/>
+<!--[if lte IE 7]>
+<link href="css/yaml/core/iehacks.css" rel="stylesheet" type="text/css" />
+<![endif]-->
+</head>
+
+<body>
+<!-- skip link navigation -->
+<ul id="skiplinks">
+ <li><a class="skip" href="#col1">Skip to main content (Press Enter).</a></li>
+</ul>
+
+<div class="page_margins">
+ <div class="page">
+ <div id="top"><div id="tm"></div></div>
+ <!-- begin: #col1 -->
+ <div id="col1" role="main">
+ <div id="col1_content">
+ <div id="header" role="banner">
+ <h1><span><em>live Arch Linux</em> builder</span></h1>
+ </div>
+
+ <!-- begin: #col3 navigation column -->
+ <div id="col3" role="complementary">
+ <div id="col3_content">
+ <img class="indent2" alt="larch logo" src="css/screen/larch150x.png" width="150" height="150" />
+ <div class="vlist">
+ <ul>
+ <li><a href="index.html"><h6>Table Of Contents</h6></a></li>
+ <li><a href="larch_live_system.html"><h6>Next:</h6>
+ <div class="indent1">Structure of a larch live system</div></a></li>
+ <li><a href="medium.html"><h6>Previous:</h6>
+ <div class="indent1">Preparing the larch live medium</div></a></li>
+ </ul>
+ </div>
+ </div>
+ </div>
+ <!-- end: #col3 -->
+
+<div class="larchdocs">
+<h2 id="pagetitle" level="1">Profiles</h2>
+
+<p>This feature of the <em>larch</em> build system allows bundling
+all the configuration information for a particular <em>live</em> system
+'design' into a single directory, a <em>larch profile</em>, and the
+name of the profile is the directory's name. This directory includes
+the list of packages to be installed, locale information and the
+particular tweaks and additions needed
+to customize the system, in particular a subdirectory containing the
+'overlay' files - those files which have been changed from their initial
+fresh state after installation and those which have simply been added.
+</p>
+
+<p>Note that of all the profile files and directories mentioned here
+only 'addedpacks' is not optional.
+</p>
+
+<h3><a name="overlay"></a>The overlay directory</h3>
+
+<p>One of the simplest features of the profile is perhaps the
+'<em>rootoverlay</em>' subdirectory:
+everything in this directory is copied directly to the
+<em>live</em> system's overlay, so that the a file 'a/b/c' within this
+directory will appear at '/a/b/c' in the <em>live</em> system, regardless
+of whether this file previously existed. Note however that all ownerships
+are changed to 'root:root'. The bulk of the customizations for the
+<em>live</em> system would normally be placed in this directory.
+</p>
+
+<p>It would be possible to make the desired alterations directly to the
+base system, and there are situations in which one would pretty well
+have to do it this way (for example if a modified or added file was to
+have some ownership other than 'root:root'). But another advantage (apart
+from the encapsulation of the customizations in the profile directory) of
+keeping the modifications in a separate directory is that the base
+installation can be kept 'clean' and thus it is easily reusable.
+</p>
+
+<p>If you would like to have a look at a profile, look in the 'profiles'
+directory in the 'larch-profiles' package (if you have downloaded
+<em>larch</em> by means of the 'larch-setup' script that will be
+'larch0/profiles'). Each of its subdirectories is a profile.
+If you want to make your own profile, it is probably easiest to start with
+one of the examples. Copy one of these directories to your working directory
+and rename it (to avoid confusion).
+</p>
+
+<h3><a name="cd-root"></a>The <strong>cd-root</strong> directory</h3>
+
+<p>This directory contains files that will be (more or less) directly copied
+to the <em>larch</em> medium, partly dependent on the available bootloaders.
+</p>
+
+<p>Bootloader independent files are provided in the 'larch' package at
+'cd-root/boot0'. Individual files can be added or substituted by
+supplying them in the <em>profile</em> at <strong>cd-root/boot</strong>.
+It is also possible to completely replace the basic boot directory by
+having <strong>cd-root/boot0</strong> in
+the profile - then the default version will not be used. These files are
+copied to the 'boot' directory of the bootable medium.
+</p>
+
+<p>There are also directories for bootloader dependent files. These are only
+copied over if the <em>live</em> system has support for the corresponding
+bootloader (i.e. if the corresponding packages - 'grub' and 'syslinux' - are
+installed). These end up as subdirectories of the medium's 'boot' directory,
+'boot/grub', 'boot/syslinux' or 'boot/isolinux', and work in a similar way to
+the 'boot(0)' directories. <em>larch</em> provides default versions of these
+directories in 'cd-root/grub0' and 'cd-root/isolinux0'. To extend these, or
+replace individual files, place your changes in the directories
+<strong>cd-root/grub</strong> and <strong>cd-root/isolinux</strong> in the
+<em>profile</em> directory, if
+you want to completely replace these directories, supply your versions in
+<strong>cd-root/grub0</strong> and <strong>cd-root/isolinux0</strong> in the
+profile directory.
+</p>
+
+<p>The contents of the directory <strong>cd-root/larch/copy</strong> will
+appear in '/larch/copy' on the medium. During booting the <em>larch live</em>
+system will copy the contents of this directory to the <em>tmpfs</em> base
+directory ('/.livesys'). This feature is not
+used by the <em>larch</em> system itself, but it can be used in various
+ways by the <em>live</em> system - the example profiles use it to some
+extent, for controlling autologin and for data required for installation
+as a normal <em>Arch</em> system (information on features specific to a
+<em>live</em> system which should be stripped out if a normal installation
+is performed).
+</p>
+
+<p>The contents of the directory <strong>cd-root/larch/extra</strong> will
+appear in 'larch/extra' on the medium but are otherwise unconnected with any
+<em>larch</em> functionality. <em>Live</em> system designers can use this
+in any way they like.
+</p>
+
+<h3><a name="other-files"></a>Other important files within a profile</h3>
+
+<ul>
+ <li><strong>addedpacks</strong> - This is the only compulsory file in
+ the profile (it must even be present if you are not using the
+ installation stage, but it can be empty in that case). It contains
+ a list of packages and package groups to be installed to the 'base'
+ system. Here you can enter all the applications
+ you would like in your <em>live</em> CD/USB system (and subsequently
+ installed to a hard disk partition, if that was your intention).
+ Thanks to <em>pacman</em> you don't need to sort out dependencies,
+ these should all be included automatically. See
+ <a href="archin.html#package_selection">here</a> for details.
+ </li>
+ <li><strong>vetopacks</strong> - Allows 'vetoing' of packages included
+ indirectly in the installation list from 'addedpacks'. See
+ <a href="archin.html#package_selection">here</a> for details.
+ </li>
+ <li><strong>pacman.conf.repos</strong> - Set the repository part of
+ 'pacman.conf' for the <em>live</em> system, and possibly also for
+ installation of the base system (See
+ <a href="archin.html#pacman_conf">here</a> for further details).
+ The default version will be adequate for many situations, but you
+ will need to supply this file if you use the 'testing' repository,
+ for example.
+ </li>
+ <li><strong>pacman.conf.options</strong> - Set the options part of
+ 'pacman.conf' for the <em>live</em> system and for
+ installation of the base system (See
+ <a href="archin.html#pacman_conf">here</a> for further details).
+ This will generally not be needed as the default version will be
+ adequate for most purposes.
+ </li>
+ <li><strong>bootlines</strong> - This file contains bootloader independent
+ boot lines, so that the same file can be used for grub and isolinux/syslinux.
+ The gui provides a button to edit this file.
+ To get an idea of what should be in here look at the default version (in
+ the 'larch' package, 'data' directory), or just click on the edit button.
+ </li>
+
+ <li><strong>rootoverlay/etc/rc.conf</strong> - As a major point of
+ configuration in an <em>Arch</em> system this is important enough
+ to get a button in the <em>larch</em> gui to edit it.
+ </li>
+
+ <li><strong>rootoverlay/etc/locale.gen</strong> - For convenience, the
+ <em>larch</em> gui provides a button to edit this file, which determines
+ which glibc locales are supported in the <em>live</em> system. The
+ corresponding files are generated (to the overlay) by the 'larchify'
+ script, which has an option (for experts only) to reuse the locale
+ files from a previous run (in order to reduce generation time in
+ cases where the locales are unchanged).
+ </li>
+
+ <li><strong>rootoverlay/etc/mkinitcpio.conf.larch0</strong> - Again for
+ convenience, the <em>larch</em> gui provides a button to edit this file,
+ which allows you to tweak the initramfs. This is a special version of
+ '/etc/mkinitcpio.conf' which is used to generate the initramfs for the
+ <em>larch live</em> system. The default version is supplied as
+ '/etc/mkinitcpio.conf.larch0' in the 'larch-live' package. Whatever else
+ you change, don't change the larch hooks.
+ </li>
+
+ <li><strong>rootoverlay/etc/inittab.larch</strong> - If this file is
+ present it will cause the original /etc/inittab to be saved with a
+ '.larchsave' suffix, and this new version will be used for the
+ <em>live</em> 'inittab'. This allows a special version of this file to
+ be used just for the <em>live</em> system, an installer
+ can replace it by the original during the installation process.
+ </li>
+
+ <li><strong>users</strong> - It is possible to add user accounts to the
+ system during building. See below.
+ </li>
+
+ <li><strong>skel_*</strong> (directory) - Customized '/etc/skel' substitutes
+ for use at build time only. See below.
+ </li>
+
+ <li><strong>vetodirs</strong> - Do not use this unless you really know what
+ you are doing. Each directory listed in this file (one entry per line,
+ comment lines start with '#') will be excluded from the live system. The
+ directories are relative to the installation root.
+ </li>
+
+ <li><strong>build-tweak</strong> - Do not use this unless you really know
+ what you are doing. It is a program (script) - so it must be executable -
+ to customize the construction of the overlay (to a certain extent). It gets
+ two arguments on the command line: the path to the installation being
+ larchified, and the (full) path to the directory in which the overlay is
+ being constructed. It is called just before 'mods.sqf' is squashed, but
+ also before users are added.
+ </li>
+
+ <li><strong>nosave</strong> - The existence of this file will suppress the
+ generation of the file 'larch/save' on a writable medium (unless overridden
+ by an option to the medium generation script). It is also copied to
+ 'larch/nosave' on the medium (also on non-writable media), so that this
+ message is available later, e.g. when copying the medium.
+ </li>
+
+</ul>
+
+<h3><a name="users"></a>Adding user accounts</h3>
+
+<p>
+The construction details should be provided in the 'users' file in the
+profile directory. It is an 'ini'-style configuration file, the sections
+being the user names. Here is an example:
+<pre>[DEFAULT]
+pw =
+expert =
+skel =
+maingroup =
+uid =
+xgroups = video,audio,optical,storage,scanner,power,camera
+
+[u1]
+uid = 999
+skel =
+
+[u2]
+pw = p1
+expert =
+skel =
+maingroup =
+uid =
+xgroups = video,audio,optical,storage
+</pre>
+The 'DEFAULT' section is not necessary, but is generated automatically
+by the gui user-table editor. Only entries which differ from the default
+values need be present.
+</p>
+<p>The default primary group is defined by settings in '/etc/login.defs'
+and '/etc/default/useradd' ('USERGROUPS_ENAB yes' in 'etc/login.defs'
+causes this to be a group with the same name as the user). You can
+override this by adding an 'expert' option, or by placing modified versions
+of these files in the profile's 'rootoverlay' directory.
+</p>
+<p>The additional groups should be comma-separated and without spaces.
+</p>
+<p>If no 'skel'-file is specified, the default ('/etc/skel') is used, including
+anything in the overlay. To use a custom 'skel'-file, place the directory
+in the profile, giving it a name starting with 'skel_', and place the rest of
+the name (the part after '_') in the configuration line.
+</p>
+<p>A password can be set for the new user by entering this (plain text -
+I'm guessing this is alright in this situation ...). An empty password
+field will allow passwordless logins (at least on the console).
+</p>
+<p>By default the UID number will be chosen automatically, but a specific
+number may be entered here. In <em>Arch Linux</em> the UIDs normally start
+at 1000.
+</p>
+<p>Users are added by means of 'useradd', so anything placed in the 'expert'
+field should be a valid option to that command. If a user-name already exists
+in the system to be larchified, it will be ignored (it does not count as
+an error).
+</p>
+
+</div>
+
+
+ <div class="topref"><a href="#top">Top</a></div>
+ </div>
+ <!-- begin: #footer -->
+ <div id="footer">
+ <div id="footer-content" role="contentinfo">© 2010 Michael Towers<br />
+ Page layout assisted by <a href="http://www.yaml.de/">YAML</a> and
+ <a href="http://www.kuwata-lab.com/tenjin/">pyTenjin</a>
+ </div>
+ </div>
+ <!-- end: #footer -->
+ </div>
+ <!-- end: #col1 -->
+ <div id="bottom"><div id="bl"><div id="bm"></div></div></div>
+ </div>
+</div>
+<!-- full skiplink functionality in webkit browsers -->
+<script src="css/yaml/core/js/webkit-focusfix.js" type="text/javascript"></script>
+</body>
+</html>