nALFS, version 1.2.0
========================


nALFS is used for parsing the ALFS profiles (simple XML files) and, 
following those profiles, do various things (like executing commands), 
one by one, to (usually) compile some packages.


1. LFS, ALFS

2. Quick start

3. Requirements

4. Compiling and installing

5. Running and usage

   5.1 Run-status marks

   5.2 Starting the execution

   5.3 Types of messages (in status window)

   5.4 Options indicators

   5.5 Searching the profile

   5.6 Non-interactive mode


1. LFS, ALFS
============

LFS stands for Linux From Scratch and its a project, led by Gerard
Beekmans <gerard@linuxfromscratch.org>, which helps you build your own
Linux system.

What this means is that you will be using nothing but the source code
of various packages needed for a fully functional Linux system. You
will compile them, one by one, on your own machine, and therefore they
will be maximally configured for it. Also you will be able to tweak
every single corner of your system, by editing the configuration
files, creating your own boot scripts and more.

All this might sound a bit complicated, requiring too much work. But
even if it is, it's well worth it.

However, it doesn't have to be that complicated. With only a few
keystrokes and the right software, you can just sit back and relax,
while your system is being built. This is where ALFS comes into play.

ALFS stands for Automated Linux From Scratch, and its aim is to
provide a much simpler method for building a Linux system.

ALFS uses the profiles, simple XML files, which describe the actions
to be taken and what commands to execute. Feeding the program (like
nALFS) the profiles, will make the program act upon them.

For example, if you want to create a directory, all you have to do is
to put:

    <mkdir>
        <name>/some/directory</name>
    </mkdir>

in the profile and leave the rest to the program. Of course, you are
not limited to just compiling packages for LFS. You can do just about
anything.

This might seem very similar to ordinary shell scripting, but it has
also a lot of advantages. With this approach, nALFS, which reads the
given profile, can be instructed to pause execution, start execution
from selected element (by browsing a profile in a tree-like mode) and
much much more.

Some links that might interest you:

Linux From Scratch:
    http://www.linuxfromscratch.org/

Automated Linux From Scratch:
    http://www.linuxfromscratch.org/alfs/

Mailing lists for ALFS:
    http://linuxfromscratch.org/mailman/listinfo/alfs-discuss
    http://linuxfromscratch.org/mailman/listinfo/alfs-log


2. Quick start
==============

To configure, compile, install and run nALFS, just type:

    ./configure
    make
    make install
    nALFS profile/LFS-*/LFS-*.xml

This will start nALFS using the latest stable LFS profile, which is
included in the nALFS distribution. When you enter the program, type
'?' for a list of all available commands.


3. Requirements
===============

For actual parsing of XML profiles, nALFS uses the libxml2 (aka
gnome-xml) library. You can find it on the web at http://xmlsoft.org/.

If you use <download> and/or <unpack> elements in your profiles, and wish
to have the source file contents verified by computing digests, you can
use MD5 digests without requiring any additional libraries while building
nALFS. If you wish to use digests other than MD5 (i.e. SHA-1), nALFS can
be built using the OpenSSL library from http://www.openssl.org/.

If you use <download> and/or <unpack> elements in your profiles and
wish to get better download performance (and more reliability) than
using "wget" for the download processes, nALFS can be built using the
curl libraries that are included in the curl distribution from
http://curl.haxx.se/.

A copy of the DTD used to validate ALFS profiles is included in the
nALFS distribution, at doc/ALFS.dtd. This file can be used with the
xmllint tool from the libxml2 distribution to check whether your
profile(s) conform to the ALFS profile specification. Using this tool
is a fast and easy way to check for typing/spelling errors and other
simple syntactical problems that nALFS would find when it loads your
profiles.

Note: At this time, the ALFS DTD includes <if>, <then> and <else>
elements that nALFS does not currently implement. In addition, nALFS
does not implement the <description> element used in
<packageinfo>. These problems will be rectified in a future release.


4. Compiling and installing ===========================

First, you have to configure the package by typing:

    ./configure

To see the list of all available options, use "./configure --help".

nALFS supports (at least) three different ALFS profile versions: 2.0,
3.0 and 3.1. If not otherwise specified, the build process will build
handlers for all the included versions. If you would like to exclude
building handlers for profile versions that you do not use, you can
include the --enable-syntax argument to the configure command, like
so:

    ./configure --enable-syntax=3.0,3.1

The --enable-syntax argument accepts a list of versions (separated by
commas or colons) to build; all other versions present in the source
tree will be excluded.

nALFS can be built as a static executable, meaning that all its handlers
and other requirements will be linked into a single file, requiring no
actual "installation". This will happen automatically if you build nALFS
on a system that does not support shared libraries, or you can force
a static build by typing:

    ./configure --disable-shared --enable-static

When compilation is complete, ./src/nALFS will be a single executable
containing everything needed to run nALFS on your system.

Warning: As of the current version, nALFS uses a function from the C
library that glibc-2.2 (and later) implement by using the "libnss" shared
libraries that are part of glibc itself. This means that even if you
build a static binary of nALFS, the libnss libraries from your build
system will still be required on the system that you wish to run nALFS
on. This will be addressed in a future release of nALFS.

Warning: If you build a static nALFS binary and choose to include curl
(libcurl) support for downloading files in your profiles, you may
experience problems due to libcurl's use of the resolver library provided
by glibc.

By default, the nALFS executable will be installed into
/usr/local/bin, while handlers will be installed into the
/usr/local/lib/nALFS directory.

You can change these defaults by specifying the --prefix or --libdir
options to configure.

Then, after configuring, type:

    make

to compile the program. To install it, use:

    make install


5. Running and usage
====================

Just type:

    nALFS profile/LFS-*/LFS-*.xml

where "profiles/LFS-*/LFS-*.xml" is the current stable LFS profile
distributed with the nALFS package. Multiple profiles separated by
spaces can also be specified.

nALFS reads the /etc/nALFSrc file, then the ~/.nALFSrc file, in which
different options can be set.  An example of these files is located in
the doc directory.

When you enter the program, you can press '?' to display a list of all
available commands. They might be described here in detail one day -
for now, just a few random hints...


5.1 Run-status marks
--------------------

    >  - Currently running element
         (all parents of the running element are also marked like this).
    @  - Some, but not all, child elements are successfully done. 
    #  - Element, and all its child elements (if any) are successfully done.
    !  - Element, or at least one of its child elements (if any) failed.

You can change these manually by pressing 'm' and picking the right one.


5.2 Starting the execution
--------------------------

After pressing 's', you will have to choose what elements you want to
run. You have four options:

    m  - Run only marked elements. You can mark elements by pressing
         'Insert' or '*'. It doesn't matter whether they are already
         successfully executed or not - all marked elements will run
         again.

    c  - Run only the current element and its children. Elements marked
         with '#' will be skipped.

    n  - Run current element, its children, and all the elements below
         the current (on the same level/depth). Elements marked with
         '#' will be skipped.

    f  - Force running of current element and its children. Elements
         marked with '#' will also be executed.

Since the elements that have already successfully run won't run again
(unless they are marked or forced), you can safely press 's' on the
first element (your profile) without worrying that some elements will
get executed twice.

Elements that previously failed (marked with '!') will always run again.


5.3 Types of messages (in status window)
----------------------------------------

    I  - Informative message.
    H  - Help message.
    -  - System command output.
    W  - Warning.
    E  - Error message.

Marks that are not in color (if you see any color at all) are the ones
from the backend - a separate process that does all the work.


5.4 Options indicators
----------------------

All options are changeable with 'o' (quickly) and 'O' (to enter the
options menu).

--| r a c v s o w h f B |--

    | | | | | | | | | |
    | | | | | | | | | |Log backend (times/handler actions/changed files).
    | | | | | | | | |
    | | | | | | | | |Log changed files (can be 'f' for logging using time
    | | | | | | | | |stamps, or empty).
    | | | | | | | | 
    | | | | | | | |Log handler actions.
    | | | | | | |
    | | | | | | |Log status window content.
    | | | | | |
    | | | | | |Follow running elements.
    | | | | |
    | | | | |Print system command output (see "Types of messages").
    | | | |
    | | | |Be verbose.
    | | |
    | | |Display comments.
    | |
    | |Display <alfs> element.
    |
    |Element to which you will jump after using 'J', 'K' or ';' commands.
    |It can be 'r' (for currently running), 'f' (for the one that failed),
    |'d' (for successfully done) or 'p' (for package).


5.5 Searching the profile
-------------------------

After pressing '/', you will be prompted to enter a search string.
Depending on your input (listed below), the search can be performed on
various parts of the profile:

   <string>     - everything
   ~e <string>  - names of the elements
   ~a <string>  - attributes (both name and value parts)
   ~c <string>  - contents
   ~p <string>  - names of the packages
   ~P <string>  - names of the packages (the exact match)

The last two can be especially useful if you're trying to locate a
specific package in some large profile.

Searches are not case sensitive.


5.6 Non-interactive mode
------------------------

Using a command-line option -i (or --interactive) will toggle the mode
in which nALFS will run. By default ALFS runs in the interactive mode.

However, it can also run in a non-interactive mode. By doing so, the
program will start executing the profiles immediately, without any
previous user interaction. All output will be printed on stdout. If
the execution fails for some reason, nALFS will simply exit with the
return value not equal to 0.

This mode can be useful, for example, if you're writing your own
scripts for automated installation and want to support ALFS profiles.
You could split the profile into smaller chunks and feed them, one by
one, to nALFS. By checking the program's return value, you could act
accordingly.

If you have any problems, either when compiling, running, or using the
program, do email us. Any suggestions, ideas, bug reports, patches
etc. are also highly welcome and can be sent to the address below.

For the latest version of the program:

    http://www.linuxfromscratch.org/alfs/

For comments, questions or other information about the program, the
alfs-discuss mailing list in section 1 of this document is the best
method to contact the developers and others users of the program.

Neven Has <haski@sezampro.yu>

Kevin P. Fleming <kpfleming@linuxfromscratch.org>
