| 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, IA32 | MacOS X 10.4

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

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.

With some platforms, the `make` command should be replaced by the `gmake` command. The `make status` comand 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.

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 enable parallelization.

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.

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.

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 `instdoc` 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.

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

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.

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.

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.

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.

- cnf
  This directory contains the configuration distribution and various utilities. Normally you should not touch it, unless you are using a compiler different than gcc.
- src
  This directory contains the complete source tree. The source code is written in C++. Normally this directory is left untouched. If there are good reasons to modify it, please contact the team.
- tst
  This directory contains the complete test suites. The test suites are used by various programs including the main interpreter, the compiler and the debugger. It shall be noted that the library distribution also includes specific test suites.
- doc
  This directory contains the complete documentation written in in XML with a special DTD. It should be left untouched.
- etc
  This directory contains various files associated with the distribution. Some files are useful to be copied.
- exp
  This directory contains various examples. They are included for illustration purpose.

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.

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.

- EXTCPPFLAGS
  This flag can be used to add some compilation flags for all .cpp files.
- EXTCXXFLAGS
  This flag can be used to add some compilation flags for all .cxx files.
- EXTCCDEFINE
  This flag can be used to add some compilation definitions for all source files.
- EXTINCLUDES
  This flag can be used to add some compilation paths for the .cxx files.

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. Some files with the `rtf` extension are used within the pre-packed Darwin distribution.

- afnix-mode.el
  This file is the Emacs mode.
- afnix-gud.el
  This file is the debugger Emacs gud mode.

Specific makefile rules

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

- status
  This rule show the configuration status for each parameters with the version.
- debug
  This rule invokes the default configuration in debug mode.
- optimized
  This rule invokes the default configuration in optimized mode.
- build
  This rule invokes the default configuration in debug mode and compile the whole distribution. The default install directory is /usr/local.
- world
  This rule invokes the default configuration in optimized mode and compile the whole distribution. The default install directory is /usr/local.
- test
  This rule runs all test suites.
- doc
  This rule builds the documentation.
- distri
  This rule builds the distribution.
- install
  This rule installs the distribution.
- instdoc
  This rule installs the documentation.
- clean
  This rule cleans the distribution but keep the configuration.
- distclean
  This rule cleans the distribution including the configuration.

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

Release features

- Core engine: unicode 5.0 support
  The core engine continues to be updated in order to better support the Unicode 5.0 standard. With this release, the string normalization scheme is now in place and used by default internally. This implies among other things, a better support for multiple diacritics as well as the beginning of the standard collation algorithm.
- Core engine: log file support
  The Logger base class has been enhanced to support the generation of a log file. An output stream can now be bound to the object.
- Core engine: class defer support
  The concept of class defer object has been added to the Class object. The defer mode is the opposite of the infer mode and provides a mechanism for base class creation.
- Core engine: print table header
  The PrintTable object has been enhanced to support the concept of table header.
- Core engine: exception re-throwing
  The exception object what can be thrown with the reserved keyword throw. This provides a mechanism to re-throw an exception.
- Core engine: critical bug with return form
  A critical bug in the core engine affecting the behavior of the return reserved keyword in a try block has been fixed. A return form inside a try block was incorrectly generating an exception which was subsequently catched by the try block.
- Core modules: net module
  The base network module has been enhanced to better operate with IPV6. In particular, when both IPV4 and IPV6 stacks are present and a host name (typically localhost) have an address entry, the socket constructor make sure it can build an object. The IPV6 address display has been rewritten.
- Core modules: sio module
  A new object called Pathname has been added to support the manipulation of system path. In addition, two new functions mkdir and mhdir have been also added to support the directory creation, both normally and hierarchically.
- Core modules: nwg module
  The Uri has been dramatically enhanced to conform to the RFC 3986. In particular, the path representation for urn is now working properly. The cookie object has been massaged to support the cookie version 1, although it does not seem to be supported (yet!) by the browsers.
- Core modules: xml module
  The xml module has been enhanced with a new parsing system called the simple model. In the simple model, nodes are parsed in a linear fashion. The node content is available in the form of a string and its interpretation is at the user discretion.
- Core service: wax service
  The afnix-wam service has been renamed as afnix-wax. The service has also been updated with two new objects, namely the XmlMime and XhtmlMime which permits to build a mime representation of an xml tree. Several xhtml objects have also been added to complete the collection. This include the XhtmlScript for example.
- Core service: xpe service
  The afnix-xpe service has been added as a new service. The xml processing environment (xpe) provides a xml processor that permits manipulate the whole xml tree with the help of various xml processor features. In particular, the service provides the support for the xml include extension.
- Core projects: apx project
  This release incorporates for the first time, the concept of core project, which represents a librarian or an application written in . The first project is the AFNIX protocol extension or apx which is a message based protocol designed to transport request/reply messages within a client/server environment. The message is built with the xml library and the librarian provides the encapsulation layer.
- Core projects: amd project
  The AFNIX media dumper or amd project is a complete application designed to illustrate the design of an application inside . The application permits to dump an uri content into a file.

Release history

- 06/08/2007: release 1.5.2
  AFNIX 1.5.2 has been released. This is a minor release that fixes the build process with GCC 4.2.
- 04/21/2007: release 1.5.1
  AFNIX 1.5.1 has been released. This is a minor release that fixes the documentation targets during the build process.
- 04/18/2007: release 1.5.0
  AFNIX 1.5.0 has been released. This release provides a xml processor in the form of a new service module called 'xml processing environment'or xpe. The whole documentation generation is now fully automated, thanks to the new xml processor. This release also provides a better support for the 'web application extension' or wax service. The support for the GNU/FreeBSD platform has also been added in this release. As usual, this release comes with its wagon of bug fixes, notably this time in the network field especially with IPV6 on the FreeBSD platform.

Release 1.4

Release features

- Core engine: unicode 5.0 support
  The core engine has been substantially changed to support the new Unicode 5.0 standard. As of now, the engine is in place internally, but not fully activated. In particular, the string normalization is implemented but not activated. The next release should incorporate the full system with a change that should be transparent to the user.
- Core language: instance inference
  An instance inference mechanism -- which is equivalent to the concept of virtual constructor -- has been added to the core engine. Such system permits to derive top instance from a base instance construction.
- Core language: print table object
  The PrintTable object has been enhanced with a dump method similar to the format method.
- Core language: property list object
  The Property and the Plist objects have been added to the standard library. a property is name/value pair. The property list object is an iterable object that stores property objects.
- Core modules: xml module
  A new module called afnix-xml has been added. The module provides the foundation for a full xml 1.0/1.1 support. The module also includes a parser that permits to build xml tree. A xml tree writer is also part of the module functionality. A xml processor is not yet available and is expected in the next release.
- Core modules: nwg module
  A new module called afnix-nwg has been added. The module provides the support for the network working group objects such like Uri object. The module also provides the foundation for the mime support.
- Core modules: web module
  The afnix-web module has been removed and replaced by the afnix-wam service.
- Core service: wam service
  The afnix-wam service has been added as the first service into the core distribution. A service differs from a module in the sense that it is a combination of different modules. The web application management service depends on the xml and nwg modules. The service provides all the functionality to support a http session, including xhtml page generation and cgi request reply.

Release history

- 01/28/2007: release 1.4.3
  This release is a minor release that fixes the "install" rule in the etc directory.
- 01/01/2007: release 1.4.2
  This release is a minor release that fixes the tcp socket read method that incorrectly handles a connection reset by the peer. The Time class also incorporates a small fix for the to-rfc method.
- 11/09/2006: release 1.4.1
  This release is a minor release that fixes the lexer for not parsing correctly some floating point numbers. The standard i/o documentation is also fixed. A print media support is now available in the documentation.
- 11/06/2006: release 1.4.0
  This release incorporates the Unicode 5.0 standard as well as a brand new xml module. This release also introduces the concept of service module, which provides additional functionalities on top of regular modules. A new service module called web application management or wam is also introduced with this release. This service module is based on the newly created xml module and replaces the old web module which has been obsoleted immediately.

Release 1.3

Release features

- Core language: ISO-8859 transcoding support
  The core engine has been modified to integrate a character transcoder that permits the support all ISO-8859 codesets which are mostly used for the encoding of european and arabic characters. Depending on the locale settings, the transcoder automatically remaps the 8 bits characters into their respective unicode character. All clients have been updated to detect their associated locale and to set automatically the appropriate transcoder. A new option -e has been added to force a particular encoding.
- Core language: Logger base class
  A logging base class has been added. The logging facility provides the interface to store messages by time and level. This class is further extended in the modules.
- Core language: Heap class
  A heap class has been added. The heap can operate in ascending or descending mode. This class can be used to support priority queue.
- Core language: Option class
  An option class has been added in order to ease the option capture when designing an application. The class permits to define the valid options and offer a powerful retrieval mechanism.
- Core language: Date class
  The Time class has been completely changed and a new Date class has been added. The new mechanism provides a better separation between the time and the date, increase the date range and authorizes the support for multiple calendar.
- Client: cross spreadsheet client
  The axs client has been modified to support the axs:insert-marker, axs:insert-header and insert-footer control commands.
- Core modules: speadsheet module
  The Folio and Sheet classes have been substantially updated to support additional information. The Sheet also supports the concept of markers that marks the sheet columns by literals. The concept of column tagging has been added with the associated search methods. All classes also contain an information field. The importation mechanism now supports a cons cell that defines both the cell name and the cell value.
- Core modules: web module
  The Table class has been modified to support the concept of table data header. The associated methods have been added to the class and a new HtmlTh has been added. The concept of tag propagation has also been added. If a tag element already exists, this one is not added. This is particularly true for the class tag that is now part of the class constructor. The HtmlPage class has been put in strict conformance with xhtml 1.1 and the XHtmlpage class has been removed.
- Core modules: pim module
  A new module called the afnix-pim module has been added to the base distribution. The personal information management or pim module is designed to ease the management of personal information and agenda.
- Core modules: gfx module
  A new module called the afnix-gfx module has been added to the base distribution. The module contains the base class that supports the graph data structure which was previously part of the standard library.

Release 1.2

Release features

- Core language: Unicode support
  The core engine has been substantially modified to integrate the support for Unicode characters. Depending on the system settings the reader automatically adjust itself to operate in byte mode or in UTF-8 mode. The String and Character classes are now operating with a Unicode representation. The design of an Unicode based engine also impacts several classes like the Regex, Buffer and stream classes. A new class called Byte is also designed to handle byte character. A new stream model with a base Stream class has also been added. The full support with Unicode character is not yet completed. In particular, certain codesets are not supported at all. This is particularly true with case-conversion functions.
- Core language: orphan instance and reparenting
  The object model now supports the creation of orphan instance which is an instance without a class attached to it. The instance can be later bound to a class and such class can even be changed during the course of the program execution.
- Core modules: network module
  The Address class has been updated to reflect the access to address aliases.
- Core modules: text processing module
  The Literate class has been updated to reflect the support of Unicode characters. The class can operate both in byte mode or in Unicode character mode.

Release 1.1

Release features

- Core language: Large file support
  Support for the large file system has been added in the base distribution. All input/output operations as long as they are supported by the operating system are now done in 64 bits mode.
- Core libraries: Secure hash algorithm
  The cryptographic library incorporates the support for the SHA-1, SHA-256, SHA-384 and SHA-512 hash algorithms.
- Core libraries: Standard symmetric cipher
  The cryptographic library incorporates the support for the Advanced Encryption Standard (AES) as a symmetric cipher.
- Core libraries: ODC library renamed
  The ODC library has been renamed to SPS which stands for spreadsheet library. This new name is considered more appropriate for the function the library achieves.
- Core libraries: xhtml 1.1 support
  The XhtmlPara class is now configured to support XHTML 1.1 with utf-8 encoding.
- Documentation: XML based documentation
  The documentation has been rewritten completely in XML. An DTD as well as the necessary XSLT style sheets have also been designed to produce a professional documentation which can be used for printing or for online browsing.

Release history

- 10/04/2005: release 1.1.2
  This release incorporates a fix for a terminal capability error.
- 08/25/2005: release 1.1.1
  This release incorporates fixes for several build problems with the FreeBSD platform.
- 08/19/2005: release 1.1.0
  The 1.1 release is yet another milestone that incorporates a full redesign of the documentation tree as well as the inclusion of the cryptographic library that features some original implementations. The full documentation is now available in XML format and can be accessed online.

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

- 04/19/2005: release 1.0.3
  This release incorporates the necessary files that support GCC 4. It also provides some minor fixes that were preventing the compilation on some 64 bits platforms.
- 03/02/2005: release 1.0.2
  This release incorporates a minor fix that could cause the build process to fail.
- 02/16/2005: release 1.0.1
  This release incorporates a minor fix that could cause the build process to fail.
- 01/16/2005: release 1.0.0
  This is the primary release 1.0.0 which originated from the ALEPH programming language and which has been discontinued. A complete history of the language is provided in the description page.