<?xml version="1.0" encoding="UTF-8"?>

<!-- ====================================================================== -->
<!-- = chapter-1.xml                                                      = -->
<!-- = afnix installation guide chapter 1                                 = -->
<!-- ====================================================================== -->
<!-- = This  program  is  free  software; you  can redistribute it and/or = -->
<!-- = modify it provided that this copyright notice is kept intact.      = -->
<!-- = This program is distributed in the hope that it will be useful but = -->
<!-- = without  any  warranty;  without  even  the  implied  warranty  of = -->
<!-- = merchantability or fitness for  a  particular purpose. In no event = -->
<!-- = shall  the  copyright  holder be liable for any  direct, indirect, = -->
<!-- = incidental  or special  damages arising  in any way out of the use = -->
<!-- = of this software.                                                  = -->
<!-- ====================================================================== -->
<!-- = copyright (c) 2005-2007 - amaury darsch                            = -->
<!-- ====================================================================== -->

<chapter id="vol-0-01">
 <title>Introduction</title>

 <p>
 This chapter describes the installation procedures for the 
 <afnix/> programming language distribution. This chapter explains how
 to set and compile this distribution.
 </p>

 <!-- afnix distribution-->
 <section>
   <title>AFNIX distribution</title>

   <p>
   <afnix/> can be downloaded from the
   <link url="http://www.afnix.org">AFNIX home page</link>. The result
   is complete source tree that is ready for compilation. The
   distribution contains also the documentation as well as
   examples. The distribution is supported on a
   variety of platforms as indicated below that can be either 32 bits
   or 64 bits machines. The language is also 
   distributed by <link url="http://www.freebsd.org">FreeBSD</link>.
   </p>

   <table>
     <title>AFNIX supported platforms</title>
     <thead>
       <tr>
         <td>Platform</td><td>Processor</td><td>Operating system</td>
       </tr>
     </thead>
     <tbody>
       <tr>
         <td>Linux</td> 
         <td>IA32, IA64, X86/64, Alpha, M68K, SPARC, PPC, ARM and MIPS</td>
         <td>Linux 2.4 and 2.6</td>
       </tr>
       <tr>
         <td>FreeBSD</td>
         <td>IA32, IA64, X86/64, SPARC, SPARC64</td>
         <td>FreeBSD 4.x, 5.x, 6.x</td>
       </tr>
       <tr>
         <td>Darwin</td>
         <td>PPC, IA32</td>
         <td>MacOS X 10.4</td>
       </tr>
       <tr>
         <td>Solaris</td>
         <td>SPARC V7, ULTRASPARC V9</td>
         <td>Solaris 2.7 and 2.8</td>
       </tr>
     </tbody>
   </table>
 </section>

 <!-- installation procedure -->
 <section>
   <title>Installation procedure</title>
   <p>
   <afnix/> is written in C++. <afnix/> has been successfully
   built with the <package>GNU GCC 3</package> and <package>GCC
   4</package>. No other compiler have been tested. You will also need
   the <package>GNU Make</package> package. With some distributions
   the command is called <command>gmake</command>. Note that the
   <file>Makefile</file> hierarchy is designed to operate safely with
   the <option>-j</option> <package>GNU Make</package> option.
   </p>

   <!-- unpacking the distribution -->
   <subsect>
     <title>Unpacking the distribution</title>

     <p>
     The distribution is available as a compressed tar file. Note that the
     documentation is distributed in a separate file. The following
     command unpacks the distribution.
     </p>

     <example>
     zsh&gt; gzip -d afnix-src-[version].tar.gz
     zsh&gt; tar  xf afnix-src-[version].tar
     </example>
   </subsect>

   <!-- quick command reference -->
   <subsect>
     <title>Quick command reference</title>
     
     <p>
     The list of commands to execute is given in the example below. A
     detailed description for each command is given hereafter. The
     <command>make world</command> is the default command that builds
     the whole tree with the default compiler. 
     </p>

     <example>
     zsh&gt; ./cnf/bin/afnix-setup -o --prefix=/usr/local/afnix
     zsh&gt; make status
     zsh&gt; make [-j]
     zsh&gt; make test
     zsh&gt; make install
     zsh&gt; make clean
     </example>

     <p>
     With some platforms, the <command>make</command> should be
     replaced by the <command>gmake</command>. The <command>make
     status</command> is optional and can be used to report the
     internal value contents. In particular, the <afnix/> version and
     the installation parameters are reported.
     </p>
   </subsect>

   <!-- configuration -->
   <subsect>
     <title>Configuration</title>
     
     <p>
     The <command>afnix-setup</command> command can be invoked to
     setup a particular configuration. You should have your compiler
     on your search path. Normally, the command given below is enough.
     </p>

     <example>
     zsh&gt; ./cnf/bin/afnix-setup -o --prefix=/usr/local/afnix
     </example>

     <p>
     This command checks that the target platform can be detected and
     configured. The <option>-o</option> option configures the compilation
     in optimized mode. Use the <option>-g</option> option can be used
     to configure the build process in debug mode. The
     <option>--prefix</option> option sets the installation 
     directory. Note that the compilation process is done in the
     distribution tree and that the <option>--prefix</option> option
     affects only the installation operations. The <option>-v</option>
     option is the verbose option. Other options are available for
     fine tuning.
     </p>

     <table>
       <title>AFNIX setup options</title>
       <thead>
         <tr>
           <td>Option</td><td>Description</td><td>Default</td>
         </tr>
       </thead>
       <tbody>
         <tr>
           <td>-h</td><td>Print a help message</td><td>n/a</td>
         </tr>
         <tr>
           <td>-v</td><td>Set the verbose mode</td><td>n/a</td>
         </tr>
         <tr>
           <td>-g</td><td>Set the debug mode</td><td>yes</td>
         </tr>
         <tr>
           <td>-o</td><td>Set the optimized mode</td><td>no</td>
         </tr>
         <tr>
           <td>--help</td><td>Same as -h</td><td>n/a</td>
         </tr>
         <tr>
           <td>--prefix</td>
	   <td>Set the target installation directory</td> 
	   <td>/usr/local</td>
         </tr>
         <tr>
           <td>--shrdir</td>
	   <td>Set the shared installation directory</td>
	   <td>/usr/local/share</td>
         </tr>
         <tr>
           <td>--altdir</td>
	   <td>Set the alternate installation directory</td>
	   <td>/usr/local</td>
         </tr>
         <tr>
           <td>--sdkdir</td>
	   <td>Set the system development kit directory</td>
	   <td>platform dependent</td>
         </tr>
         <tr>
           <td>--compiler</td>
	   <td>Set the default compiler</td>
	   <td>platform dependent</td>
         </tr>
         <tr>
           <td>--proctype</td>
	   <td>Set the processor type for fine tuning</td> 
	   <td>generic</td>
         </tr>
         <tr>
           <td>--dynamic</td>
	   <td>Compile and link dynamically</td> 
	   <td>yes</td>
         </tr>
         <tr>
           <td>--static</td>
	   <td>Compile and link statically</td> 
	   <td>no</td>
         </tr>
       </tbody>
     </table>

     <p>
     the <option>prefix</option> option set the root installation
     directory. The binary and library installation directories are
     derived from it. The <option>shrdir</option> set the shared
     installation directory which is normally used for the
     installation of the manual pages on most popular systems. the
     <option>altdir</option> sets the alternate installation
     directory. Normally this path should be empty as it affects the
     path for the <path>etc</path> directory. This flag should be used
     when using a prefix to unusual destination. the
     <option>sdkdir</option> option sets the path of the platform
     system development kit. This option is only used with the
     <em>Darwin</em> platform.
     
     The <option>compiler</option> option can be used to force a particular
     compiler with the help of a compiler configuration file. The
     <option>proctype</option> option can be used to force a particular
     processor architecture. The <option>-s</option> or
     <option>--static</option> option can be used to build a 
     static executable. Normally, this option should not be used since
     it restrict the use of extension modules. The <option>dynamic</option>
     controls whether or not the dynamic libraries should be built. This     
     option is detected automatically for a particular platform and
     should be used only by package maintainer.
     </p>
   </subsect>

   <!-- compiling the distribution -->
   <subsect>
     <title>Compiling the distribution</title>

     <p>
     The compilation process is straightforward. With some platforms,
     the <command>make</command> accepts the <option>-j</option> that
     enable parallelization.
     </p>

     <example>
     zsh&gt; make [-j]
     </example>

     <p>
     This will build the complete distribution locally. If an error occurs,
     it is best to report it at the <mail address="bugs@afnix.org">AFNIX bug
     report</mail> mail address.
     </p>
   </subsect>

   <!-- testing the distribution -->
   <subsect>
     <title>Testing the distribution</title>

     <p>
     The distribution contains all test suites. The test suites are
     compiled and executed with the following command.
     </p>

     <example>
     zsh&gt; make test
     </example>

     <p>
     This command run the test suites for each library as well as the
     test suites for each application client. Most of the base library
     test suites are written in C++ while the application test suites
     are written in <afnix/>.
     </p>
   </subsect>

   <!-- installing the distribution -->
   <subsect>
     <title>Installing the distribution</title>

     <p>
     Once the system has been built and tested, it can be installed. By
     default, the distribution tree is installed into the
     <path>/usr/local</path> directory. This can be overwritten with the
     <option>--prefix</option> option during the configuration process.
     </p>

     <example>
     zsh&gt; make install
     </example>

     <p>
     There are several variables that controls the behavior of the
     <command>install</command> rule. Each variable has its default
     value sets during the setup configuration. However, this variable
     can also be altered during the installation process
     </p>

     <table>
       <title>AFNIX install rule variables</title>
       <thead>
         <tr>
           <td>Variable</td><td>Description</td><td>Default</td>
         </tr>
       </thead>
       <tbody>
         <tr>
	   <td>PREFIX</td>
	   <td>The root installation directory</td>
	   <td>/usr/local</td>
         </tr>
         <tr>
	   <td>SHRDIR</td>
	   <td>The shared installation directory</td>
	   <td>/usr/local/share</td>
         </tr>
         <tr>
	   <td>ALTDIR</td>
	   <td>The shared alternate directory</td>
	   <td>/usr/local/etc</td>
         </tr>
         <tr>
	   <td>SDKDIR</td>
	   <td>The system development kit directory</td>
	   <td>platform dependent</td>
         </tr>
         <tr>
	   <td>BINDIR</td>
	   <td>The binary executable installation directory</td>
	   <td>prefix/bin</td>
         </tr>
         <tr>
	   <td>LIBDIR</td>
	   <td>The library installation directory</td>
	   <td>prefix/lib</td>
         </tr>
         <tr>
	   <td>HDRDIR</td>
	   <td>The development header files installation directory</td>
	   <td>prefix/include/afnix</td>
         </tr>
         <tr>
	   <td>DOCDIR</td>
	   <td>The documentation installation directory</td>
	   <td>shrdir/doc/afnix</td>
         </tr>
         <tr>
	   <td>MANDIR</td>
	   <td>The manual pages installation directory</td>
	   <td>shrdir/man</td>
         </tr>
         <tr>
	   <td>ETCDIR</td>
	   <td>The extra files installation directory</td>
	   <td>altdir/etc/afnix</td>
         </tr>
       </tbody>
     </table>
   </subsect>

   <!-- cleaning the distribution -->
   <subsect>
     <title>Cleaning the distribution</title>

     <p>
     The distribution is cleaned with the <command>clean</command> rule.
     </p>

     <example>
     zsh&gt; make clean
     </example>

     <p>
     This rule does not clean the configuration. For a complete cleaning
     the <command>distclean</command> rule is more appropriate.
     </p>

     <example>
     zsh&gt; make distclean
     </example>
   </subsect>
 </section>

 <!-- running afnix -->
 <section>
   <title>Running AFNIX</title>

   <p>
   The <command>afnix</command> command invokes the
   <afnix/>interpreter. In order to operate properly, the
   <path>LD_LIBRARY_PATH</path> environment variable must be
   configured with the directory containing the <afnix/> shared
   libraries. If the libraries have been installed in a standard
   location like <path>/usr/local/lib</path>, there is nothing to do.
   </p>

   <!-- running some example -->
   <subsect>
     <title>Running some example</title>

     <p>
     The directory <path>exp</path> contains various examples which can
     be run. Each example is labeled according to their use in the volume
     1 of the documentation set. Example <file>0101.als</file> prints
     the message <tt>hello world</tt>. Example <file>0501.als</file>
     prints various information about the system configuration.
     </p>

     <example>
     zsh&gt; axi 0501
     major version number   : <major/>
     minor version number   : <minor/>
     patch version number   : <patch/>
     interpreter version    : <major/>.<minor/>.<patch/>
     operating system name  : linux
     operating system type  : unix
     afnix official url     : http://www.afnix.org
     </example>
   </subsect>
 </section>

 <!-- special targets -->
 <section>
   <title>Special features</title>
   
   <p>
   The build process provides several features that permits to
   customize the compilation process as well as the nature of the
   final executable. Most of the time, these options are reserved for
   the package maintainer and are given below for illustration
   purpose.
   </p>

   <!-- target customization -->
   <subsect>
     <title>Target customization</title>
   
     <p>
     The distribution can be configured to operate on a specific machine
     target. For example, a typical Linux box will be compiled with the
     default compiler target, which is the 386 processor. You can force the
     compilation to be optimized for a particular processor. This is done
     with the <option>--proctype</option> option of the
     <command>afnix-setup</command> command. Currently the distribution
     supports the <option>586</option> and <option>686</option>
     architectures for the Intel platform. The <option>ultra</option>
     architecture is valid for the SPARC platform. 
     </p>

     <example>
     zsh&gt; cnf/bin/afnix-setup -o --prefix=/usr/local --proctype=586
     </example>

     <p>
     This command will configure the distribution to be compiled
     specifically for the Pentium architecture.
     </p>
   </subsect>

   <!-- special target extensions-->
   <subsect>
     <title>Special target extensions</title>
     
     <p>
     Extensions are specific libraries or executables which are not build
     automatically during the build process. The user is responsible to
     decide which extension is needed for the system All extensions are
     located under the <path>src/ext</path> directory. Simply going
     into the appropriate directory and running the
     <command>make</command> command will build the extension.
     </p>

     <p>
     The <path>asi</path> extension creates a static interpreter with
     all libraries automatically included in the final executable. The
     extension is simply build with the following command. Note that this
     extension overwrite the previous executable in the
     <path>bld/bin</path> directory.
     </p>

     <example>
     zsh&gt; make -C src/ext/asi
     </example>
   </subsect>

   <!-- extra files -->
   <subsect>
     <title>Extra files</title>

     <p>
     <afnix/> comes with some extra files. The most important is the
     <file>afnix-mode</file> for Emacs. The original source file is
     written in Emacs Lisp and is available in the <path>etc</path>
     directory of the distribution. This file should be installed
     according to the current Emacs installation.
     </p>
   </subsect>
 </section>
</chapter>
