AFNIX installation guide

Introduction

This chapter describes the installation procedures for the AFNIX programming language distribution. This chapter explains how to set and compile this distribution.

AFNIX distribution

AFNIX 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 language is also distributed by FreeBSD .

Platform Processor Operating system
Linux IA32, IA64, X86/64, SPARC, SPARC64 Linux 2.4 and 2.6
FreeBSD IA32, IA64, X86/64, SPARC, SPARC64 FreeBSD 4.x, 5.x, 6.x
Darwin PPC, PPC64, IA32 MacOS X 10.4 Tiger, 10.5 Leopard

Specific processors like the Alpha, M68K, ARM and MIPS are also supported on certain distribution like Debian. The PowerPC (PPC) processor is primarily supported with the Darwin platform (MACOS) and is also working with the Linux platform. The Solaris SPARC platform has been discontinued. Do not hesitate to contact the AFNIX team for specific processor or platform support.

Installation procedure

AFNIX is written in C++. AFNIX has been successfully built with the GNU GCC 3 and GCC 4. No other compiler have been 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 -jGNU 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.

 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.

 ./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 AFNIX 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.

 ./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.

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
--sdkdir Set the system kit directory platform dependent
--compiler Set the default compiler platform dependent
--proctype Set the processor type generic
--dynamic Compile and link dynamically yes
--static Compile and link statically 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 sdkdir option sets the path of the platform system development kit. This option is only used with the Darwin platform. The compiler option can be used to force a particular compiler with the help of a compiler configuration file. The proctype option can be used to force a particular processor architecture. 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 dynamic 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.

Compiling the distribution

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

 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.

 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++ while the application test suites are written in AFNIX.

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.

 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

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.

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.

 make clean

]]>

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

 make reset

]]>
Running AFNIX

The afnix command invokes the AFNIXinterpreter. In order to operate properly, the LD_LIBRARY_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 /usr/local/lib, there is nothing to do.

Running some example

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.

 axi 0501
major version number   : 1
minor version number   : 9
patch version number   : 0
interpreter version    : 1.9.0
operating system name  : linux
operating system type  : unix
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.

Target customization

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 --proctype option of the afnix-setup command. Currently the distribution supports the 586 and 686 architectures for the Intel platform. The ultra architecture is valid for the SPARC platform.

 cnf/bin/afnix-setup -o --prefix=/usr/local --proctype=586

]]>

This command will configure the distribution to be compiled specifically for the Pentium architecture.

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.

 make -C src/ext/asi

]]>

Extra files

AFNIX comes with some extra files. The most important is the afnix-mode for Emacs. 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.


Maintainer notes

This chapter contains additional notes for the package maintainer. They are also useful for anybody who is in charge of integrating the AFNIX distribution in a build process. The chapter describes the distribution tree with more details.

The AFNIX distribution tree

The distribution tree is composed of various directories. Each of them has a Makefile which can be called locally or from the top level.

The process of building a package solely depends on the distribution type. Most likely, the standard distribution should contain the binary executables as well as some configuration file and the manual pages. The documentation and the development header files can put in separate packages.

Configuration and setup

The configuration process involves the use of the afnix-setup command located in the cnf/bin directory. This command is used to configure the distribution. Package maintainers are encouraged to use it with specific options.

Platform detection

The afnix-guess command is used during the configuration process to detect a supported platform. This command can be run in stand-alone mode. Various options can be used to tune the type of information requested.

Option Description
-h Print a help message
-n Print the platform name
-v Print the platform version
-M Print the platform major number
-m Print the platform minor number
-p Print the platform patch number
-t Print the processor type

Without option, the utility prints a platform and processor description string.

 ./cnf/bin/afnix-guess
linux-2.6-ia32-generic

]]>

Platform defaults

The directory cnf/def contains a platform specific default file. The file determines what is the default compiler and linking mode. This file is used by the afnix-setup command. For example, the afnix-darwin.def file contains:

Such options instructs the configuration utility, that the default compiler is gcc and the linking mode should operates in dynamic mode by using the dylib rule. These default values can be overwritten with the equivalent option of the afnix-setup command. Note that the compiler version is automatically detected by the system. The afnix-vcomp command will return the appropriate compiler version running on the target system.

C++ source file conventions

AFNIX has two types of C++ files. The first type has the extension .cxx and the second type has the extension .cpp. The .cxx -- and the associated .hxx -- files are only used to indicate a system dependency. These files are found only in the src/lib/plt directory. The .cxx extension indicates that the file might use system specific include files. The .cpp -- and the associated .hpp -- files are the normal C++ source files. The .cpp extension is used to indicate that these files will not use a system specific file. By default this rule is enforced in the compiler configuration file by specifying some compiler flags which do not authorize such access.

Configuration files

The configurations files are located in the cnf/mak directory. Normally they should be left untouched. The most important one is the afnix-rule.mak file that defines most of the compilation and linking rules. Additionally, during the setup operation, the afnix-setup command creates several files in the bld/cnf directory. The bld is the build directory. The afnix-plat.mak file is the platform configuration file and the afnix-comp.mak is a link to the appropriate compiler configuration file.

Compilation

Normally, the compilation process is immediate. Just invoking the make command will do the job. However, some package maintainer have the desire to overwrite some flags. Some options are provided to facilitate this task.

For example, it is common to have some maintainer to compile with both the debug and optimize flags. This can be done with the following command (assuming an optimized configuration):

All include files, compiled libraries and executables are placed in the bld directory. This directory contains the bld/bin for binaries, bld/lib for libraries and bld/hdr for the header files.

Building the package

The package can be built by accessing the bld directory or by invoking the install rule. The second method is not recommended for package construction, since it might trigger some file installation without any control.

The etc directory contains some special files that might be used for the package construction. A sample list of them is given hereafter.

Specific makefile rules

The top level Makefile contains several rules that might be useful for the package maintainer.


Release notes

This chapter contains the release notes for the AFNIX standard release. Release notes are given in descending order for a particular version. The standard notation is major.minor.patch which represents respectively, the major, minor and patch number. A major version number changes indicates a substantial change in the distribution, including new tools, application interface and license. A minor version number change indicates noticeable change, with or without new tools but without application interface change nor license change. Finally, a patch number change indicates a simple change to fix problem. There is no additional features in a patch nor an application interface change.

Release 1.9

Release features

Release 1.8

Release features

Release 1.7

Release features

Release history

Release 1.6

Release features

Release history

Release 1.5

Release features

Release history

Release 1.4

Release features

Release history

Release 1.3

Release features

Release 1.2

Release features

Release 1.1

Release features

Release history

Release 1.0

The 1.0 release is the initial AFNIX release. This release replaces the old ALEPH programming language which has been discontinued.

Release history