%% 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: <>= 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: <>= 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. <>= ## 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} <>= 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}: <>= 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}. <>= 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. <>= # 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}. <>= 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. <>= AC_CONFIG_SRCDIR(src/Makefile.pamphlet) @ \subsubsection{Instantiating configuration 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 <>= <> <> <> ## 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 <> 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}