%% Oh Emacs, this is a -*- sh -*- script, despite appearance.
\documentclass[12pt]{article}
\usepackage{axiom}
\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{fancyvrb}
\usepackage{pslatex}
\usepackage{url}

\newcommand{\email}[1]{\url{#1}}
\CustomVerbatimEnvironment{chunk}{Verbatim}{frame=none,fontsize=\small}

\def\nwendcode{\endtrivlist \endgroup}
\let\nwdocspar=\par
\let\nowebsize=\small


\title{The Toplevel \File{configure.ac} Pamphlet}
\author{Gabriel Dos~Reis}

\begin{document}
\maketitle

\begin{abstract}
  This pamphlet details the configuration process of setting up 
  \Tool{OpenAxiom} for build from source codes. 
  It also explains general dependencies on external tools.  
  The configuration process scrutinizes the build, host,  and target
  environments, and finally instantiates \File{Makefile}s for building
  \Tool{OpenAxiom} interpreter, compiler, libraries, and auxiliary tools
  where appropriate.
\end{abstract}

\section{Introduction}
\label{sec:intro}

This is the top-level \Tool{Autoconf} description that sets up the
minimum environment for building \Tool{OpenAxiom}.  This effort
strives for describing the build machinery at a sufficiently abstract
level that
enables interoperability with existing conventional frameworks, \eg{}
the GNU build framework.
The task is compounded by the fact that the existing \Tool{OpenAxiom} system 
is complex and very poorly documented, with blatantly conflicting or
questionable codes. 

The \Tool{OpenAxiom} system is written for the most part in Lisp, or 
thereof.  That in itself is a great source of portability 
problems\footnote{even after half a century of existence}, 
let alone issues related to insulation from mainstream
development tools, dependence on particular Lisp implementation details, etc.
A tiny part of it, mainly the interface with host operating system, is
written in the C programming language.  That does not improve on the 
portability problems.  Fortunately, there are well-supported, 
widely used, widely available, well tested tools supporting
C-derived development environments across platforms.  The GNU 
\Tool{Autotools} being one of them.  For the moment, we only make use of
the \Tool{Autoconf} component.  This build machinery does not 
use \Tool{Automake} and \Tool{Libtool}.  People intending to modify
this part of the build machinery are expected to be familiar with 
\Tool{Autotconf}.

The \File{Makefile} pamphlets that compose the build machinery are
written in a way that abstracts platform idiosyncracies into
parameters.  The purpose of the \File{configure.ac} script is to
find values for those parameters, on a given platform, necessary to
instantiate the \File{Makefile}s, and therefore to set up a concrete
build machinery.  And that task must be accomplished portably.

\section{Generalities on build instantiations}

\subsection{Two actors}

The instantiation of the abstract build machinery description requires
that we gather information from two platforms:
\begin{enumerate}
\item the \emph{build platform}, and 
\item the \emph{host platform}.
\end{enumerate}

The build platform is where we build the system, \eg{} where
the \File{configure} script is executed.  The host platform
is where \Tool{OpenAxiom} will run.  Note that in full generality, there is 
a third platform: the \emph{target platform}.  It is the plaform for which
we are building the system.

For typical build instantiations, those  three  platforms are the same: we 
call that a \emph{native build instantiation} or just \emph{native build}.
The OpenAxiom system only support native build at the moment, due to its
dependence on \Tool{GCL} which supports only native build.

To facilitate the porting of programs across platforms, the GNU build
system has standardized on designation of platforms, called
\emph{configuration names}.  A configuration name used to be
made of three parts\footnote{hence the term \emph{canonical triplet} in 
    earlier versions of \Tool{Autoconf}}:
\textsl{cpu--vendor--os}.  Examples are
[[i686-pc-linux-gnu]], or [[sparc-sun-solaris2.8]].

The \textsl{cpu}
part usually designates the type of processor used on the platform.
Examples are [[i686]], or [[sparc]], or [[x86_64]].

The \textsl{vendor} part formally designates the manufacturer of
the platform.  In many cases it is simply [[unknown]].  However,
in specific cases, you can see the name of a workstation vendor such
as [[sun]], or [[pc]] for an IBM PC compatible system.

The \textsl{os} part can be either \textsl{system} (such as [[solaris2.8]])
or \textsl{kernel--system} (such as [[linux-gnu]]).

Here is how we get the canonical names for the above three platforms:
<<host build target platfoms>>=
AC_CANONICAL_SYSTEM

open_axiom_installdir=$libdir/open-axiom/$target/$PACKAGE_VERSION
AC_SUBST(open_axiom_installdir)

@
After that call, the configuration names of the three platforms
are available in the shell variables [[build]], [[host]], and [[target]].

\subsubsection{Cross build}

As we said earlier, a native build instantiation is one where all 
[[build]], [[host]], and [[target]] have the same value.  However,
when porting programs to other platforms, it is not always possible
to do a native build --- either because all the tools are not
available on that machine, or because it is much more convenient to
build the software on a faster machine. Both situations are quite
common.

Those considerations bring us to the notion of cross build 
instantiation (also called cross compilation).  
We say that the build instantiation is a \emph{cross build} when
the build platform is different from the target platform; \eg{}, when
[[build]] $\neq$ [[target]].  

For the moment, the \Tool{OpenAxiom} base source code is written
in a way that does not support cross build.  However, we do
want to make cross build possible; consequently we issue
a warning when we detect attempt at cross build:
<<host build target platfoms>>=
if test $build != $target; then
   AC_MSG_WARN([Cross build is not supported.])
   AC_MSG_WARN([Please notify open-axiom-devel@open-axiom.org if you succeed.])
fi
@
Note that we do not stop the configuration process because we do seek
contributions for cross build support.

Note that the shell variable [[cross_compiling]],
set by the \Tool{Autoconf} macro [[AC_PROG_CC]], indicates whether
the C compiler used is a cross compiler.

\subsubsection{Canadian cross}

As we said previously, most software don't care about the target 
platform.  But compilers do.  And \Tool{OpenAxiom} does because, among
other things, it uses Lisp and C compilers, and it provides a Spad compiler.
Another type of build instantiation arises when the host platform
is different from the target platform.  The resulting compiler
is called a \emph{cross compiler}.  Please note the distinction here:
a compiler that is cross compiled with [[host]] $=$ [[target]] is 
not a cross compiler; it is a \emph{native compiler}. 
A cross compiler is one with [[host]] $\neq$ [[target]].  

The type of the compiler should not be confused with the type of the 
build instantiation.  It perfectly makes sense to have a build
instantiation that cross builds a cross-compiler, \ie{} all three
platforms are different: This is called \emph{Canadian cross}.
The \Tool{OpenAxiom} system does not that support that level of
sophistication yet.  Although we could test for Canadian cross build
at this point, we delay that check for when we look for a C compiler.

\subsection{Directories for the build instantiation}

Although \Tool{OpenAxiom} does not support cross build yet, let
alone Canadian cross, we want to make sure that we do not write
the build machinery in a way that actively unsupports 
cross build.  Consequently, in the build tree, we sequester
tools that we build and use on the build platform,
in  sub-directories different from others.
<<host build target platfoms>>=
## Where tools for the build platform are sequestered
axiom_build_sharedir=$axiom_builddir/share

@

\section{Configuration options}
\label{sec:config-options}

We strive for making \Tool{OpenAxiom}'s build system integrate as seamlessly as 
possibly into the standard GNU build framework.

\subsection{Standard options}
\label{sec:config-options:std}

At the moment, we honor the following options:
\begin{description}
\item \verb!--prefix!:
  By default, \Tool{OpenAxiom}'s build system will install files 
  in ``\File{/usr/local}''.  However, you 
  can select a different location prefix using this option.

\item \verb!--with-x!:

\item \verb!--x-includes=DIR!

\item \verb!--x-libraries=DIR!

\item \verb!--help!

\item \verb!--version!
\end{description}


\subsection{\Tool{OpenAxiom}-specific options}
\label{sec:config-options:axiom-specific}

\begin{description}
\item \verb!--enable-gcl!:
  \Tool{OpenAxiom} needs an implementation of Lisp to support its
  runtime system.  At the moment, GNU Common Lisp (\Tool{GCL} for short)
  is used.  This options instructs \Tool{OpenAxiom} to build its own copy
  of \Tool{GCL}.  Use \verb!--disable-gcl! to prevent OpenAxiom
  from building \Tool{GCL}.

\item \verb!--with-lisp=L!:  
  instructs \Tool{OpenAxiom} to use the Lisp image [[L]] for its 
  runtime platform.

\item \verb!--enable-checking!:
  instructs \Tool{OpenAxiom}'s Lisp image to perform runtime checking
  for generated Lisp codes.
\end{description}

\section{Basic Setup}
\label{sec:basic-setup}

\subsection{\Tool{Autoconf} Initialization}
\label{sec:basic-setup:init}

The \Tool{Autoconf} machinery needs to be initialized with several pieces of
information:
\begin{itemize}
\item the \emph{name} of the system --- ``OpenAxiom 1.2.0''
\item its \emph{version}.  I choose to use the date of last checkin.
  It should probably include the revision number so as to 
  unambiguously identify which \Tool{OpenAxiom} flavour du jour is being
  built;
\item and where to send feedback, \emph{e.g.} bug reports.  At the moment, 
  we use
  the \email{open-axiom-devel} list.  That could change in the future if
  we reach a high volume traffic.  For the moment, we don't seem to
  suffer from traffic...
\end{itemize}
<<Autoconf init>>=
sinclude(config/open-axiom.m4)
sinclude(config/aclocal.m4)
AC_INIT([OpenAxiom], [1.4.0-2010-08-07], 
        [open-axiom-bugs@lists.sf.net])

@

\Tool{Autoconf} needs some auxilary files that are present in the 
sub-directory \File{config}:
<<Autoconf init>>=
AC_CONFIG_AUX_DIR(config)
AC_CONFIG_MACRO_DIR(config)
@

Not all platforms present the same operating system API to applications.
For the part of \Tool{OpenAxiom} written in the C programming language, we 
can collect, in a single file, variabilities in operating system 
API in form of C preprocessor macros.  That file is for the most part
automatically generated by \Tool{Autoheader}.
<<Autoconf init>>=
AC_CONFIG_HEADERS([config/openaxiom-c-macros.h])
@

Note that at configuration time, \Tool{configure} will instantiate a
file \File{config/openaxiom-c-macros.h} in the directory [[$(top_builddir)]],
appropriate for all C sub-parts of \Tool{OpenAxiom} to include.


Notice that since we don't use Automake (yet), we don't initialize
the Automake subsystem.  
<<Autoconf init>>=
# AM_INIT_AUTOMAKE([foreign])
@

We require Autoconf $2.62$ or higher from the developer part. Please,
note that this is no requirement on the user build environment.  All,
it means is that if someone makes changes to the current \File{configure.ac}
file, that someone needs to have Autoconf $2.62$ or higher to process this
file in order to regenerate \File{configure}.
<<Autoconf init>>=
AC_PREREQ([2.62])
@


\subsection{Source tree sanity check}
\label{sec:basic-setup:sanity-check}

The \Tool{Autoconf} system implements a very basic, simple-minded, 
sanity check
whereby it will refuse to run \File{configure} if the source tree does
not contain a specified file, that serves a witness for a bona fide source
tree.  Here, we use \File{Makefile.pamphlet} from the \File{src}
subdirectory.
<<sanity check>>=
AC_CONFIG_SRCDIR(src/Makefile.pamphlet)
@


\subsubsection{Instantiating configuration files}

<<instantiate config files>>=
OPENAXIOM_MAKEFILE([Makefile])
OPENAXIOM_MAKEFILE([src/Makefile])
OPENAXIOM_MAKEFILE([src/lib/Makefile])
OPENAXIOM_MAKEFILE([src/hyper/Makefile])
OPENAXIOM_MAKEFILE([src/driver/Makefile])
OPENAXIOM_MAKEFILE([src/lisp/Makefile])
OPENAXIOM_MAKEFILE([src/boot/Makefile])
OPENAXIOM_MAKEFILE([src/interp/Makefile])
OPENAXIOM_MAKEFILE([src/share/Makefile])
OPENAXIOM_MAKEFILE([src/algebra/Makefile])
OPENAXIOM_MAKEFILE([src/input/Makefile])
OPENAXIOM_MAKEFILE([src/etc/Makefile])
OPENAXIOM_MAKEFILE([src/doc/Makefile])

AC_CONFIG_FILES([src/hyper/presea], [chmod +x src/hyper/presea])


## We now generate the "document" script and support files at configure time.
## We put them in the build directory because they are intended to be 
## build support utils only.
AC_CONFIG_FILES(build/scripts/document:$srcdir/src/scripts/document.in, \
                [chmod +x build/scripts/document])

AC_OUTPUT

## Generate rules to extrad SPAD type definitions from pamphlets.
echo -n "extracting list of SPAD type definitions..."
egrep '@<<(category|domain|package) .*>>=' \
    $srcdir/src/algebra/*.spad.pamphlet \
    | sort | uniq | \
    while IFS=':' read spad_file chunk_desc; do 
	chunk_desc=`echo $chunk_desc | sed -e 's,@<<,,' -e 's,>>=,,'`
	set $chunk_desc; spad_abbrev=$2
	cat >> src/algebra/tmp-extract-spad.mk <<EOF
$spad_abbrev.spad: \$(srcdir)/`basename $spad_file` ; \
    @\$(axiom_build_document) --output=\$@.tmp --tangle="$chunk_desc" \$< && \
    \$(top_confdir)/move-if-change \$@.tmp \$@
EOF
    done 
echo done
$srcdir/config/move-if-change \
    src/algebra/tmp-extract-spad.mk src/algebra/extract-spad.mk

@

\section{configure.ac}

<<*>>=
<<Autoconf init>>
<<sanity check>>
<<host build target platfoms>>

## Accumulate list of utils needed for the build platform
## It is vital that noweb is present in the build environement.
oa_all_prerequisites=
AC_SUBST(oa_all_prerequisites)

OPENAXIOM_HOST_COMPILERS
OPENAXIOM_GCL_HACKS
OPENAXIOM_HOST_DATA_PROPERTIES

OPENAXIOM_DYNAMIC_MODULE_SUPPORT
OPENAXIOM_BUILD_TOOLS
OPENAXIOM_LISP_FLAGS
OPENAXIOM_FILE_EXTENSIONS

OPENAXIOM_BUILD_OPTIONS
OPENAXIOM_HOST_PROGS

axiom_src_subdirs="lib hyper lisp boot interp share algebra input etc doc"
AC_SUBST(axiom_src_subdirs)

OPENAXIOM_CHECK_CORE_SUPPORT
OPENAXIOM_CHECK_IO
OPENAXIOM_CHECK_GRAPHICS

OPENAXIOM_FFI_TYPE_TABLE
OPENAXIOM_GCL_BUILD_OPTIONS
OPENAXIOM_CHECK_MISC

<<instantiate config files>>

echo "Type '${MAKE}' (without quotes) to build OpenAxiom"
@


\section{A note about comments}
\label{sec:comment}

This is a pamphlet file.  That means the source code embedded here 
are first extracted into a form (\File{configure.ac}) digestible by
\Tool{Autoconf}, which in turn produces the end-user \File{configure}
script run for setting up the build.

\Tool{Autoconf} supports two kinds of comments:
\begin{enumerate}
\item [[dnl]] style, and
\item [[#]] style.
\end{enumerate}
Comments introduced with [[dnl]] are copied verbatim to the generated
\File{configure.ac}; however, do not appear in the \File{configure}
output file.  They are for \Tool{Autoconf} consumption only --- and that
of the humans reading \File{configure.ac} (ideally, there should be none).
Comments starting with [[#]] appear verbatim in both \File{configure.ac}
and \File{configure} files.  Because this is a pamphlet file, there almost 
never is a need to use the [[dnl]]-style comment.  
Consequently, \Tool{Autoconf} comments in this file should be
of [[#]]-style form.  Such comments can be of value to the occasional
poor masochist who will be debugging the generated \File{configure}.


\end{document}