diff options
Diffstat (limited to 'configure.ac.pamphlet')
| -rw-r--r-- | configure.ac.pamphlet | 432 |
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} - |