The Yacas build system

	    Introduction

*A build system

This chapter describes the build system of Yacas. So here you will
find what happens when you give the {configure} or the {make} command,
and how to change this. It will concentrate on Unix systems; other
architectures are briefly covered in the final section.

As the Yacas build system is built on the GNU autotools suite, which
contains both {automake} and {autoconf}, we will start with a short
description of this package. Then we will turn to the various
components of Yacas: the program itself, the script files, the
documentation, the test suite, and so on. 

As explained in the {INSTALL} file, building Yacas requires the
following steps.
*	(This step is only necessary if building from CVS.) Start by
running the {makemake} script. This executes the {automake} and
{autoconf} programs. 
*	Then the {configure} script should be run.
*	Finally, Yacas can be built by giving the {make} command.

Both {configure} and {make} accept many options. Some of them are
explained below.


	    The GNU autotools suite

*A build system!autotools
*A {autotools}

The GNU {autotools} suite is a collection of applications to streamline
the build system of other programs, like Yacas. Its two main goals are
to present a consistent build procedure to users, and to assist
developers in tackling portability problems.

The autotools suite consists of a number of utilities. These are
developed separately, but are designed to be used together. They are
*	{automake}. Its main goal is to produce a {Makefile.in} file
from a high-level description in the {Makefile.am} file. The
{configure} script generated by {autoconf} will later transform it in
a {Makefile}. The generated Makefiles are portable and contain all the
targets specified in the GNU Coding Standards document, like {all},
{install} and {clean}.
*	{autoconf}. Its main goal is to produce the {configure} script.
When Yacas is built, this script gathers information from the user's
system, like the operating system and the location of certain programs
used by the Yacas build system. This information is used in turn by the
Makefiles.
*	{libtool}. This utility provides a portable interface for
building and using libraries. Static libraries, shared libraries and
dynamically loadable modules are all supported.

The users do not need to run {automake} and {autoconf} (here, "users"
refers to the people who do not want to make any changes to Yacas and
includes those who just want to compile Yacas from a tar.gz source
archive). They do need the {libtool} script. But the {libtool} package
is included in the Yacas distribution, so the users do not need to
install {libtool} themselves.

*A build system!makemake
*A {makemake}
Developers do need to install {autoconf} and {automake} on their
systems. But they usually do not need to run these tools directly, as
the Makefiles contain the necessary commands. When the Makefiles are
not present, which occurs for instance when installing afresh from the
CVS repository, the {makemake} script in the root of the Yacas source
tree can (and probably should) be used to invoke {automake} and
{autoconf} in the right order and with the correct flags.

In the following three sections, these utilities are briefly
explained. In all cases, the reader is referred to the documentation
included in the {autotools} suite for more information. Another useful
source of information is <i>GNU Autoconf, Automake, and Libtool</i> by
Gary V. Vaughan, Ben Elliston, Tom Tromey and Ian Lance, which is
published by New Riders. An online version is available from
<*http://sources.redhat.com/autobook*>.


	    The automake tool

*A build system!automake
*A {automake}

Automake is a tool to generate standard-compliant Makefiles. More
precisely, {automake} uses the information in {Makefile.am} to produce a
{Makefile.in} file, which will be turned into a {Makefile} by the
{configure} script generated by the {autoconf} utility.

The {Makefile.am} file contains the definition of certain macros that
are used by {automake}. The rest of the {Makefile.am} file is copied
verbatim to the generated {Makefile.in} file.

The most important macros which are used by {automake} are the
so-called <i>primaries</i>. These list the files that make up the Yacas
package. For instance, in the {src} directory, the file {Makefile.am}
contains the following line
	 bin_PROGRAMS = yacas
This is an example of the {PROGRAMS} primary, and says that the
directory contains a program called {yacas}. Hence it will be built if
the {make all} command is executed, it will be installed at 
{make install}, etc. Other useful primaries are {SCRIPTS} for
executable scripts, {HEADERS} for header files, and {DATA} for all
files which are just copied verbatim at installation time (this
includes Yacas scripts). 

The {bin} prefix in the example above says that {yacas} should be
installed in the binary directory, as determined by the {configure}
script. By default, this is the directory {/usr/local/bin}. There are
also prefixes for the other directories, as well as some prefixes with
different meanings: the {noinst} prefix says that the specified file
need not be installed, and the {check} prefix says that the file is
only needed when testing.

There are also so-called <i>associated variables</i>. The same
{Makefile.am} contains the following variables associated to the Yacas
executable:
	yacas_SOURCES = yacasmain.cpp commandline.cpp \
	      unixcommandline.cpp stdcommandline.cpp
	yacas_LDADD = libyacas.a libyacasplatform.a 
These lines tell that the executable is built from four source files
(yacasmain.cpp, commandline.cpp, unixcommandline.cpp and stdcommandline.cpp)
and two static libraries (libyacas.a and libyacasplatform.a). 

From the information contained in these lines, {automake} can construct
the necessary commands to go in the final {Makefile}.  This {Makefile}
does not only support building, testing, and installing the package, but
also rolling the tar-ball for release (use {make dist} for this, as
explained in the section <*"Targets for make"|yacasdoc://#make!targets*>
below). In the above example, {automake} can figure out that
{yacasmain.cpp} should be included in the distribution.

Unfortunately not everything is supported that well. For instance, Yacas
comes with its own documentation system, which is of course not
supported by {automake}. So we need to tell {automake} how to handle
these files. To specify which files should be included in the distribution, the
{EXTRA_DIST} variable can  be used. The developer should list all files
to be included in the distribution that {automake} does not know about
here. If we want to run some commands at build or installation time, we
can specify them by {Makefile} rules in the traditional ways. Just
write the rules in {Makefile.am} and they will be copied verbatim in the
generated {Makefile}. Please keep in mind that the rules should work on
a wide variety of platforms in order to retain portability. In
particular,
*	remember that the source files may be in a different directory,
if the user decides to use separate source and build trees (see
<*"The configure script"|yacasdoc://#build system!configure*>);
*	only use the automatic variable {$<} in suffix rules, as Solaris
{make} does not define {$<} correctly in other rules;
*	do not use pattern rules (like {%.o: %.c}) as they are not
supported on all platforms, use suffix rules (like {.c.o:})
instead. 

We currently assume {automake} version 1.4 or later. Note that version
1.5 breaks backward compatibility and should be avoided. Version 1.6
contains some useful additions, like the {nobase} prefix and the
possibility to define new prefixes, so at a certain point we may
require version 1.6.

For more information about {automake}, the reader is referred to the
documentation that comes with the package.


	    The autoconf tool

*A build system!autoconf
*A {autoconf}

Autoconf is a tool to generate portable shell scripts that users
can run to configure the package (in our case Yacas) for their
system. It reads the file {configure.in} and produces the {configure}
script. The latter script can be run by the user to prepare for
building Yacas.

The {configure.in} file consists of standard shell code, interspersed
with special macros defined by the {autoconf} package. These can be
recognized by the {AC_} prefix.

As the {configure.in} file only rarely needs to be changed, we will
only describe the {autoconf} tool by one example. 

This ends the brief description of {autoconf}. For more information,
the reader is referred to the documentation that comes with the
package.

We currently assume {autoconf} version 2.13 or later.



 
	    The configure script

*A build system!configure
*A configuration

The {configure} script is run by the user to prepare the Yacas package
for the build and installation process. It examines the user's system
and the options passed to the script by the user, and generates
suitable Makefiles. Furthermore, it generates {yacas.spec} which is
used to build a package in Red Hat's {.rpm} format, and the C header
file {config.h}.

A nice feature is the possibility to build in a different directory
than the source directory by simply running {configure} from that
directory. This not only prevents the source directory from being
cluttered up by object files and so on, but it also enables the user
to build for different architectures in different directories or to
have the source in a read-only directory. For example, suppose that
the Yacas source is installed under {/mnt/cdrom/src/yacas} and that
you want to build Yacas under {/tmp/build-yacas}. This is achieved by
the following commands
	mkdir /tmp/build-yacas
	cd /tmp/build-yacas
	/mnt/cdrom/src/yacas/configure
	make

A list of options accepted by the {configure} script can be retrieved
by invoking it with the {help} option
	./configure --help
The most important is the {prefix} option, which influences where
everything will be installed. The default is {/usr/local}, meaning
that for instance the yacas executable is installed as
{/usr/local/bin/yacas}. To change this in {/usr/bin/yacas}, invoke the
script as follows
	./configure --prefix=/usr
Other options to {configure} enable the user to fine-tune the location
where the various files should be installed.

We will not describe the common {configure} options which are shared
by all packages, but will restrict ourselves to the options
exclusively used by Yacas.
*	{with-numlib=LIB}. This option specifies the arbitrary-precision
library to use.  The supported values for {LIB} so far are {native} (the
default). 
*	{enable-debug}. Build a version of Yacas suitable for debugging. 
*	{enable-archive}. Build and install the library archive. The
library archive resides in the file {scripts.dat} and contains all the
Yacas scripts in compressed form.
*	{enable-server}. Build a version of the Yacas executable which
accepts the {--server} flag, which puts Yacas in server mode (see
<*"Command-line options"|yacasdoc://intro/3/1/*>) 

The following three options pertain to the extensive documentation
that comes with Yacas. By default, only HTML documentation is
generated.
*	{disable-html-doc}. Do not generate documentation in HTML
format.
*	{enable-ps-doc}. Generate documentation in PostScript
format. This requires the latex suite.
*	{enable-pdf-doc}. Generate documentation in PDF format. This
also requires the latex suite. 

Then there are three options describing where to install various parts
of the Yacas package.
*	{with-script-dir=DIR}. Install the Yacas script files, which
have extension {.ys}, in the specified directory. By default, the
script files are installed in {DATADIR/yacas}, where {DATADIR}
defaults to {PREFIX/share}. In turn, {PREFIX} refers to the value of
the {prefix} option described above; the default value is
{/usr/local}. The conclusion is that the script files by default end
up in {/usr/local/share/yacas}.
*	{with-html-dir=DIR}. This specifies where to install the HTML
documentation for the Yacas package. The default is a subdirectory
named {documentation} of the directory in which the Yacas script files
are installed.
*	{with-ps-dir=DIR}. Where to install the PostScript and PDF
documentation. This defaults to the same directory as for the
documentation in HTML format.

Furthermore, the opposites of the above options (eg. {disable-server})
are also recognized.


	    Targets for make

*A build system!targets for make
*A make!targets

One of the advantages of using the autotool suite to generate
Makefiles, is that the resulting Makefiles support a variety of
targets. Here is a partial list of them.
*	{all}. This is the default target, so instead of {make all}
one can just type {make}. It builds the executables, which includes
{yacas}, and the documentation. By default, only documentation in HTML
format will be built, but this can be changed by the {configure} script.
*	{install}. Compile the executables, and install them together
with the libraries, Yacas scripts, and documentation so that the Yacas
program can be run. 
*	{install-strip}. Same as {install}, but also strip the debug
information from the installed executables.
*	{uninstall}. Remove the installed files.
*	{clean}. Delete files that are created during the build
process, for instance {.o} files.
*	{distclean}. Delete files that are created during either the
configuration or the build process. This leaves only the files in that
were included in the distribution. 
*	{dist}. Create a tar-ball (a gzipped tar archive) ready for
distribution. 
*	{check} (or its synonym {test}). Test whether Yacas works correctly.
*	{installcheck}. Test whether Yacas is installed correctly. The
difference with the {check} target is that that one tests the
<i>built</i> version of Yacas, while the {installcheck} target tests
the <i>installed</i> version.
*	{distcheck}. Check whether Yacas is ready for
distribution. This creates a tar-ball, unpacks it in a different
directory, compiles Yacas with default options, installs it in a temporary directory, and
finally checks that the installed version works correctly. Extra flags
to be passed to the {configure} script (eg. {--enable-archive}) can be
put in the {DISTCHECK_CONFIGURE_FLAGS} environment variable.

	    The Yacas executable

*A build system!executable

The main executable is called {yacas} and resides in the {src}
directory. 

Conceptually, the build process consists of the following parts:
*	Generating the source files. Almost all source files were
written by the Yacas development team, but the following are generated
automatically: {version.h} (generated from {configure.in}),
{fastprimes.c} (generated by the {mkfastprimes} program), and
{core_yacasmain.h} (generated from {yacasmain.cpp}).
*	Building the executables. Besides the Yacas executables, we
also build {mkfastprimes} and {gencorefunctions} (which are needed to
generate some source files), and the {codereviewer} executable (which does a static analysis of code 
and can in some circumstances also fix the code where the coding
style is not adhered to).


	    The Yacas script files

*A build system!Yacas scripts
*A scripts!installation

The Yacas script files with extension {ys} can be found in the
{scripts/} directory and its "repository" subdirectories. 

All script files and {.def} files are listed in {Makefile.am}. This
definition is used to generate the {packages.ys} file, which contains
a list of all {.def} files. The {corefunctions.ys} file is also
automatically generated. This is done by running the
{gencorefunctions} program, which resides in the {src/} directory. 

At installation time, all the script files and {.def} files that are
listed in {Makefile.am} are copied. During this installation, the
directory structure should be preserved.

The {check} target checks that all the script files and {.def} files
listed in the {Makefile.am} are indeed present, and vice versa, that
all files present in the {scripts/} hierarchy are indeed listed. 


	    The documentation

*A build system!documentation
*A documentation!building

The documentation system for Yacas is explained in <*yacasdoc://essays/5/2/*>. 

The documentation is generated from plain text source files with the
{txt} extension in the {manmake} directory. The source files
are converted to Yacas code by the {txt2yacasdoc.pl} script.
The result is a set of Yacas source files containing the text of the documentation.
These Yacas source files are not well suited for human reading and must be further processed to obtain the books in HTML and PS/PDF formats.

To generate the books in HTML format, the Yacas source files are processed by the Yacas interpreter using the scripts {manualmaker} and {indexmaker}.
The script {indexmaker} creates the file {books.html} with the top-level index to all HTML documentation books.
The script {manualmaker} creates the HTML files with the book text (both the framed and the non-framed versions are written out).
It is also possible to generate more than one HTML book at once.
The two reference manuals are generated together to produce the full hyperlinked index to all commands.

To generate the books in PostScript and PDF format, the {book2TeX.sh}
script is used. This script converts the Yacas source files
to $TeX$ files. They can then be processed by the standard $TeX$
tools.

By default, only the HTML-formatted documents are generated. To change this, use the options
{disable-html-doc}, {enable-ps-doc} and {enable-pdf-doc}
in the {configure} script. The {with-html-dir} and
{with-ps-dir} options can be used to tell where the documentation
should be installed.

*A Wester's benchmark

At the moment, the {Makefile.am} for the documentation is rather
messy. For this reason, we do not describe it in detail. Instead, we
just point out some special features:
*	The Yacas interpreter and {perl} are needed to generate the documentation.
*	The section
<*"Full listing of core functions"|yacasdoc://refprog/5/1/*>
is generated from the Yacas source by the {gencorefunctions} program,
which resides in the {src} directory.
*	The Yacas code from the section 
<i>M. Wester's CAS benchmark and Yacas</i>, built from
{wester-1994.chapt.txt}, is extracted with the {book2ys.sh}
script. This code is used for testing (see below).
*	All the scripts described can be found in the {manmake} directory.


	    The test suite

*A build system!test suite
*A testing Yacas

The Yacas distribution contains a (hopefully comprehensive) test
suite, which can be used to check whether Yacas is (still) functioning
correctly. The command {make check} tests the latest compiled version
of Yacas. To test the executable that is installed on your system, use
the command {make installcheck}.

The {yts} files in the {tests} directory contain the tests for
different subsystems of Yacas. For instance, the file {arithmetic.yts}
contains tests for the basic arithmetic functions; the first test is
to check that {3+2} evaluates to {5}. All the test files are listed in
the {TESTFILES} variable. This variable can be overridden. For
example, the command
	make TESTFILES='comments.yts complex.yts' clean
only runs the test scripts {comments.yts} and {complex.yts}.

The shell script {test-yacas} does the actual testing. It runs the
scripts listed in the {TESTFILES} variable through the Yacas
executable. The tests that take a long time are at the end of the
list, so that these tests are performed last. The output of the tests
is collected in the file {testresult.txt}. The test is considered to
be failed, if the exit code is nonzero (which happens for instance if
Yacas crashes) or if either of the strings {******} (six stars) or
{Error} appear in the output.

*A Wester's benchmark

A special case is the last test, which goes through the problems put
forward by Michael Wester (see the section 
<*M. Wester's CAS benchmark and Yacas|yacasdoc://essays/2/*>). The commands for this
tests are not in a {yts} file in the {tests} directory, but are
extracted from the documentation
(see <*the immediately preceding section|yacasdoc://#documentation!building*>).


	    The library archive

The library archive is a file, commonly called {scripts.dat}, which
contains all the scripts in compressed form. If Yacas is started with
the {--archive} flag, it uses the contents of this file. This is
useful for binary releases, as one needs only two files: the Yacas
executable and the library archive.

Support for the library archive resides in the {src/}
directory. It contains the code for the {compressor} program. This
program generates the library archive.

The archive is only built if the {enable-archive} option is
passed to the {configure} script. In that case, the {compressor}
program is built and run. At installation time, the generated archive
is installed in the library directory ({/usr/local/lib} by
default). There is also a test to check that the generated archive in
fact works.