aboutsummaryrefslogtreecommitdiff
path: root/configure.ac.pamphlet
diff options
context:
space:
mode:
authordos-reis <gdr@axiomatics.org>2010-08-16 07:08:04 +0000
committerdos-reis <gdr@axiomatics.org>2010-08-16 07:08:04 +0000
commita8f6a2119931567767c404964568a4de405f94ed (patch)
treef85251e6259030917f50ec0109041e29daaab3d2 /configure.ac.pamphlet
parent2eb74847c641273b3e3479a32b9a75b5f070868c (diff)
downloadopen-axiom-a8f6a2119931567767c404964568a4de405f94ed.tar.gz
More configure work
Diffstat (limited to 'configure.ac.pamphlet')
-rw-r--r--configure.ac.pamphlet432
1 files changed, 0 insertions, 432 deletions
diff --git a/configure.ac.pamphlet b/configure.ac.pamphlet
deleted file mode 100644
index 6d332d58..00000000
--- a/configure.ac.pamphlet
+++ /dev/null
@@ -1,432 +0,0 @@
-%% 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}
-