Provided by: afnix_2.8.1-2_amd64
vol-0 - afnix installation guide
This chapter describes the installation procedures for the AFNIX 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. Platform Processor Operating system Linux X86-32, X86-64, IA64, SPARC-32, SPARC-64 Linux 3.x, 4.x FreeBSD X86-32, X86-64, IA-64, SPARC-32, SPARC-64 FreeBSD 8.x, 9.x, 10.x.x Gnu X86-32, X86-64 GNU KBSD, GNU Hurd Specific processors like the Alpha, M68K, ARM, MIPS 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 GNU GCC 4, 5, 6. The clangcompiler has also been succesfully tested. You will also need the GNU Makepackage. With some distributions the command is called gmake. Note that the Makefilehierarchy is designed to operate safely with the -jGNU Makeoption. 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 worldcommand 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 makecommand should be replaced by the gmakecommand. The make statuscommand 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-setupcommand 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 -ooption configures the compilation in optimized mode. Use the -goption can be used to configure the build process in debug mode. The --prefixoption sets the installation directory. Note that the compilation process is done in the distribution tree and that the --prefixoption affects only the installation operations. The -voption 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 --openmp Enable the optional openmp compilation no The prefixoption set the root installation directory. The binary and library installation directories are derived from it. The shrdirset the shared installation directory which is normally used for the installation of the manual pages on most popular systems. the altdirsets the alternate installation directory. Normally this path should be empty as it affects the path for the etcdirectory. This flag should be used when using a prefix to unusual destination. the sdkdiroption sets the path of the platform system development kit. This option is only used with the Darwinplatform. The compileroption can be used to force a particular compiler with the help of a compiler configuration file. The proctypeoption can be used to force a particular processor architecture. The -sor --staticoption can be used to build a static executable. Normally, this option should not be used since it restrict the use of extension modules. The dynamiccontrols 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. Option Description Default --package Set the type of package to support none --pkgbin Set the optional package bin directory none --pkglib Set the optional package lib directory none --pkgprj Set the optional package project directory none --pkghdr Set the optional package header directory none --pkgetc Set the optional package etc directory none --pkgman Set the optional package manual directory none --pkgdoc Set the optional package documentation directory none --pkgwww Set the optional package www directory none Compiling the distribution The compilation process is straightforward. With some platforms, the makeaccepts the -jthat 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 (email@example.com) AFNIX bug reportmail 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/localdirectory. This can be overwritten with the --prefixoption during the configuration process. zsh> make install There are several variables that controls the behavior of the installrule. 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 docrule builds the documentation and the publishrule 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 cleanrule. zsh> make clean This rule does not clean the configuration. For a complete cleaning the resetrule is more appropriate. zsh> make reset Running AFNIX The axicommand invokes the interpreter. In order to operate properly, the LD_LIBRARY_PATHenvironment 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 example The directory expcontains various examples which can be run. Each example is labeled according to their use in the volume 1 of the documentation set. Example 0101.alsprints the message hello world. Example 0501.alsprints various information about the system configuration. zsh> axi 0501 major version number : 2 minor version number : 8 patch version number : 0 interpreter version : 2.8.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 --proctypeoption of the afnix-setupcommand. Currently the distribution supports the 586and 686architectures for the Intel platform. The ultraarchitecture 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/extdirectory. Simply going into the appropriate directory and running the makecommand will build the extension. The asiextension 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/bindirectory. 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 etcdirectory of the distribution. This file should be installed according to the current Emacs installation.
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 Makefilewhich 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 development 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-setupcommand located in the cnf/bindirectory. This command is used to configure the distribution. Package maintainers are encouraged to use it with specific options. Platform detection The afnix-guesscommand 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-4.7-x64-generic Platform defaults The directory cnf/defcontains a platform specific default file. The file determines what is the default compiler and linking mode. This file is used by the afnix-setupcommand. For example, the afnix-darwin.deffile contains: compiler: gcc lktype : dynamic lkmode : dylib Such options instructs the configuration utility, that the default compiler is gccand the linking mode should operates in dynamic mode by using the dylibrule. These default values can be overwritten with the equivalent option of the afnix-setupcommand. Note that the compiler version is automatically detected by the system. The afnix-vcompcommand 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 .cxxand 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/pltdirectory. The .cxxextension indicates that the file might use system specific include files. The .cpp-- and the associated .hpp-- files are the normal C++ source files. The .cppextension 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/makdirectory. Normally they should be left untouched. The most important one is the afnix-rule.makfile that defines most of the compilation and linking rules. Additionally, during the setup operation, the afnix- setupcommand creates several files in the bld/cnfdirectory. The bldis the build directory. The afnix-plat.makfile is the platform configuration file and the afnix-comp.makis a link to the appropriate compiler configuration file. Compilation Normally, the compilation process is immediate. Just invoking the makecommand 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 .cppfiles. EXTCXXFLAGS This flag can be used to add some compilation flags for all .cxxfiles. 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 .cxxfiles. 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 blddirectory. This directory contains the bld/binfor binaries, bld/libfor libraries and bld/hdrfor the header files. Building the package The package can be built by accessing the blddirectory or by invoking the installrule. The second method is not recommended for package construction, since it might trigger some file installation without any control. The etcdirectory contains some special files that might be used for the package construction. A sample list of them is given hereafter. 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 Makefilecontains 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. publish This rule installs the documentation. clean This rule cleans the distribution but keep the configuration. reset This rule resets the distribution including the configuration.