# Maintainer notes

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

## The 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.

This directory contains the configuration distribution and various utilities. Normally you should not touch it, unless you are using a compiler different than `gcc`.
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 development team.
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.
This directory contains the complete documentation written in in XML with a special DTD. It should be left untouched.
This directory contains various files associated with the distribution. Some files are useful to be copied.
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.

### Platform detection options

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

THe source tree 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.

This flag can be used to add some compilation flags for all .cpp files.
This flag can be used to add some compilation flags for all .cxx files.
This flag can be used to add some compilation definitions for all source files.
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.

This file is the Emacs mode.
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.

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