# Installation Guide

This chapter describes the installation procedures for the writing system distribution. This chapter explains how to set and compile this distribution.

## Software distribution

The complete distribution can be downloaded from the AFNIX home page. The result is a 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 distribution is also available at the FreeBSD port collection.

## Supported platforms

Platform | Processor | Operating system
--- | --- | ---
Linux | X86-32, X86-64 | Linux 3.x, 4.x, 5.x
FreeBSD | X86-32, X86-64 | FreeBSD 8.x, 9.x, 10.x.x, 11.x.x, 12.x.x
Gnu | X86-32, X86-64 | GNU KBSD, GNU Hurd

Specific processors like the Alpha, M68K, ARM, MIPS, RISCV and SUPERH are also supported on certain distributions. The PowerPC (PPC) processor has been discontinued. The Solaris SPARC platform has been discontinued. Do not hesitate to contact the development team for specific processor or platform support.

## Installation procedure

The core software is written in C++. It has been successfully built with the latest `GNU GCC 10`. The `clang` compiler has also been succesfully tested. You will also need the `GNU Make` package. With some distributions the command is called `gmake`. Note that the Makefile hierarchy is designed to operate safely with the `-j` `GNU Make` option.

## Unpacking the distribution

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.

zsh> gzip -d afnix-src-[version].tar.gz zsh> tar xf afnix-src-[version].tar

## Quick command reference

The list of commands to execute is given in the example below. A detailed description for each command is given hereafter. The `make world` command is the default command that builds the whole tree with the default compiler.

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

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

## Configuration

The `afnix-setup` 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.

zsh> ./cnf/bin/afnix-setup -o --prefix=/usr/local/afnix

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

## Setup options

Option | Description | Default
--- | --- | ---
-h | Print a help message | n/a
-v | Set the verbose mode | n/a
-g | Set the debug mode | yes
-o | Set the optimized mode | no
--help | Same as -h | n/a
--prefix | Set the target install directory | /usr/local
--shrdir | Set the shared install directory | /usr/local/share
--altdir | Set the alternate install directory | /usr/local
--sdknam | Set the target sdk by name | platform dependent
--sdkdir | Set the target sdk directory | platform dependent
--ccname | Set the default compiler | platform dependent
--shared | Compile and link dynamically | yes
--static | Compile and link statically | no
--openmp | Enable the optional openmp compilation | no

The `prefix` option set the root installation directory. The binary and library installation directories are derived from it. The `shrdir` set the shared installation directory which is normally used for the installation of the manual pages on most popular systems. the `altdir` sets the alternate installation directory. Normally this path should be empty as it affects the path for the etc directory. This flag should be used when using a prefix to unusual destination. The `ccname` option can be used to force a particular compiler with the help of a compiler configuration file. The `-s` or `--static` 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 `shared` 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. There exists also specific options which are mostly for package maintainers. At this time, the build process integrates the Debian, Ubuntu and Fedora specific packaging mechanism.

## Specific package maintainer options

Option | Description | Default
--- | --- | ---
--pkgnam | Set the distribution package | none
--pkgbin | Set the optional package bin directory | none
--pkglib | Set the optional package lib directory | none
--pkgprj | Set the optional package prj directory | none
--pkghdr | Set the optional package hdr directory | none
--pkgetc | Set the optional package etc directory | none
--pkgman | Set the optional package man directory | none
--pkgdoc | Set the optional package doc directory | none
--pkgwww | Set the optional package www directory | none
--pkgsrv | Set the optional package srv directory | none

## Compiling the distribution

The compilation process is straightforward. With some platforms, the `make` accepts the `-j` that enables concurrent operations.

zsh> make [-j]

This will build the complete distribution locally. If an error occurs, it is best to report it at the AFNIX bug report mail address.

## Testing the distribution

The distribution contains all test suites. The test suites are compiled and executed with the following command.

zsh> make test

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++ with the application test suites written in the core writing system.

## Installing the distribution

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

zsh> make install

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

## Installation rule variables

Variable | Description | Default
--- | --- | ---
PREFIX | The root install directory | /usr/local
SHRDIR | The shared install directory | /usr/local/share
ALTDIR | The shared alternate directory | /usr/local/etc
SDKDIR | The system kit directory | platform dependent
BINDIR | The binary install directory | prefix/bin
LIBDIR | The library install directory | prefix/lib
HDRDIR | The header files install directory | prefix/include/afnix
ETCDIR | The extra files install directory | altdir/etc/afnix

## Installing the documentation

The documentation is installed independently of the software. The `doc` rule builds the documentation and the `publish` rule installs the documentation. Several variables also control the documentation installation path.

## Documentation rule variables

Variable | Description | Default
--- | --- | ---
DOCDIR | The documentation install directory | shrdir/doc/afnix
MANDIR | The manual pages install directory | shrdir/man

## Cleaning the distribution

The distribution is cleaned with the `clean` rule.

zsh> make clean

This rule does not clean the configuration. For a complete cleaning the `reset` rule is more appropriate.

zsh> make reset

## Running AFNIX

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

## Running some examples

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

zsh> axi EXP0501 major version number : 3 minor version number : 8 patch version number : 0 interpreter version : 3.8.0 program name : axi operating system name : linux operating system type : unix machine size : 64 afnix official uri : http://www.afnix.org

## Special features

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.

## Special target extensions

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 src/ext directory. Simply going into the appropriate directory and running the `make` command will build the extension.

The asi 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 bld/bin directory.

zsh> make -C src/ext/asi

## Extra files

The distribution comes with some extra files. The most important is the Emacs mode afnix-mode. The original source file is written in Emacs Lisp and is available in the etc directory of the distribution. This file should be installed according to the current Emacs installation.