NAME
vol-0 - 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 -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.
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 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.
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.
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.
zsh> make [-j]
This will build the complete distribution locally. If an error occurs,
it is best to report it at the (bugs@afnix.org) 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++ 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.
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
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.
zsh> make clean
This rule does not clean the configuration. For a complete cleaning the
distclean rule is more appropriate.
zsh> make distclean
Running AFNIX
The afnix command invokes the AFNIX interpreter. 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.
zsh> axi 0501
major version number : 1
minor version number : 5
patch version number : 2
interpreter version : 1.5.2
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.
zsh> 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.
zsh> 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.
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.
zsh> ./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:
compiler: gcc
lktype : dynamic
lkmode : dylib
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):
make EXTCPPFLAGS=-g EXTCXXFLAGS=-g
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.