Re: [Axiom-developer] [build-improvements] Requests for discussion

[Gabriel Dos Reis]

Ralf Hemmecke <address@hidden> writes:

| Does that help you? I am running debian sarge.
| I don't see a ./config file in that directory.

Ralf --

   Based on the feedback I got, I implemented the Autoconf-based
configuration stuff as a pamphlet file (see below).  At the moment,
the only thing it does is to mimic the existing (old) configure file.
Future work aims at reducing the build process to

     ./configure
      make
      make install


   To test this, you don't need to run Autoconf.  Just check out a
fresh copy of the build-improvements branch and proceed as usual.

   Feedback appreciated.

Thanks!

-- Gaby

\documentclass[12pt]{article}
\usepackage{axiom}
\usepackage[latin1]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{fancyvrb}
\usepackage{pslatex}
\usepackage{noweb}
\usepackage{url}

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

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

\begin{document}
\maketitle

\begin{abstract}
 ...
\end{abstract}

\section{Introduction}
This is the top-level Autoconf file that sets up the minimum build
environment for Axiom.  At the moment, the mainline version
of Axiom is driven by \file{Makefile} pamphlet files.  This effort
strives to move the build machinery to more abstract description
and conventional ones.
The task is compounded by the fact that the Axiom system is very 
complex -- but much less complex, I suspect, than say GCC.  There does not
seem to be good reasons why Axiom should build its own ghetto.

Autoconf supports two kinds of comments:
\begin{enumerate}
\item [[dnl]] style, and
\item [[#]] style.
\end{enumerate}
Comments introduced with [[dnl]] do not appear in the \file{configure}
output file.  Comments starting with [[#]] appear verbatim in the
\file{configure} generated file.  Because this source file is
literate, there almost never is a need to use the [[dnl]]-style
comment.  Consequently, Autoconf comments in this file should be
of [[#]]-style.  Such comments can be of value to the occasional
poor masochist who will be debugging the generated \file{configure}
file.

\section{Old Story}

The contents of top-level \file{configure} file from mainline is 
reproduced below.  It will serve as the initial basis for the new,
improved, build machinery.

\begin{verbatim}
# The sysname function uses uname -s to try to decode what kind of
# system to build. Currently the return value of uname is mapped as
#       Linux          --> linux
#       MINGW32_NT-5.1 --> windows
#       SunOS          --> Solaris9
#       Fedora Core 3  --> fedora3
#       freebsd        --> freebsd
#
# The solaris platform needs patch->gpatch, awk->gawk, tar->gtar
 
sysname () {
if [ -f /etc/redhat-release ] ;
 then 
  SYSNAME=`cat /etc/redhat-release` 
  if [ "$SYSNAME" = "Fedora Core release 3 (Heidelberg)" ] ; 
   then SYSNAME=fedora3
  fi
  echo SYSNAME=$SYSNAME
fi
if [ ! "$SYSNAME" = "fedora3" ] ; 
 then
   SYSNAME=`uname -s`
   echo $SYSNAME 
   if [ "$SYSNAME" = "Linux" ] ; then SYSNAME=linux
   elif  [ "$SYSNAME" = "MINGW32_NT-5.1" ] ; then SYSNAME=windows
   elif  [ "$SYSNAME" = "SunOS" ] ; then SYSNAME=solaris9
   elif  [ "$SYSNAME" = "freebsd" ] ; then SYSNAME=freebsd
   else
     echo Your system name is $SYSNAME
     echo We do not know how to build for this kind of system
     echo Send a note to address@hidden about it
     echo
     exit 0
   fi
fi

}

# This function checks for the gawk command. 
# If it exists then AWKNAME is the complete pathname

checkgawk() {
AWKNAME=`which gawk 2>>trace`
if [ -n "$AWKNAME" ] ; then
 if [ -x $AWKNAME ] ; then 
  echo 
 fi
fi
}

# This function checks for the nawk command. 
# If it exists then AWKNAME is the complete pathname

checknawk() {
AWKNAME=`which nawk 2>>trace`
if [ -n "$AWKNAME" ] ; then
 if [ -x $AWKNAME ] ; then 
  echo 
 fi
fi
}

# This function checks for the awk command. 
# If it exists then AWKNAME is the complete pathname

checkawk() {
AWKNAME=`which awk 2>>trace`
if [ -n "$AWKNAME" ] ; then
 if [ -x $AWKNAME ] ; then 
  echo 
 fi
fi
}

# This function uses the check*awk functions to decide 
# whether the system can build noweb. If one of gawk, nawk or awk
# are not found we fail.
needAwk ()
{
checkgawk
if [ -z "$AWKNAME" ] ; then
  checknawk
  if [ -z "$AWKNAME" ] ; then
    checkawk
    if [ -z "$AWKNAME" ] ; then
      echo We need the commands gawk, nawk, or awk
      exit 0
    fi
  fi
fi
}

# The mustSet function tells the user what needs to be typed on the 
# command line. If any extra variables need to be set we add them here.
# Currently the only thing we check if for the presence of gawk, which
# is the default in the Makefile. If gawk does not exist we can use 
# either nawk or awk but the user has to specify that on the command line.

# We check the system we are using with the uname command and try to
# generate the appropriate value. We fail otherwise.

# We generate the appropriate command line that the user should use.

mustSet() {
echo
echo ===================================================
echo You must set your AXIOM and PATH variables. Type:
echo
echo To build the rest of the system type:
echo
echo export AXIOM=`pwd`/mnt/$SYSNAME
echo 'export PATH=$AXIOM/bin:$PATH'
if [ "$SYSNAME" = "freebsd" ] ; then
  echo Note that freebsd usually has noweb available
  echo If you wish to use the standard version you must type
  echo touch noweb 
  echo If you wish to use a pre-installed GCL you must type
  echo make GCLVERSION=gcl-system
fi
if [ "$SYSNAME" = "solaris9" ] ; 
 then echo make AWK=gawk TAR=gtar PATCH=gpatch
elif [ "`basename $AWKNAME`" = "gawk"  ] ; 
 then echo make
 else echo make AWK=$AWKNAME
fi
echo
echo configure finished.
}

#########################################################################
# This is the main line of configure logic.
# (1) We test to see if we understand this system name. So far
#     the recognized strings from uname -s are translated as:
#       Linux          --> linux
#       MINGW32_NT-5.1 --> windows
#       SunOS          --> Solaris9
#       Fedora Core 3  --> fedora3
#       freebsd        --> freebsd
# (1) We test for the AWK variable. We need one of gawk, nawk, or awk
#     in order to build the noweb software.
# (2) Then we output the final message for the user.
#
# The solaris platform needs patch->gpatch, awk->gawk, tar->gtar
#########################################################################

sysname
needAwk

if [ "x$AXIOM" = "x" ] ;
 then mustSet
 else 
  if [ ! "`dirname $AXIOM`" = "`pwd`/mnt" ]
    then mustSet
    else 
     echo Configure complete. Now type
     echo
     echo make
     echo
  fi
fi
\end{verbatim}


\section{Basic Setup}
\subsection{Autoconf Initialization}

The Autoconf machinery needs to be initialized with several pieces of
information:
\begin{itemize}
\item the \emph{name} of the system --- ``Axiom silver branch''
\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 Axiom flavour du jour is being
  built;
\item and where to send feedback, \emph{e.g.} bug reports.  I have chosen
  the \email{axiom-developer} 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>>=
AC_INIT([Axiom silver branch], [2006-07-15], address@hidden)
@

Autoconf needs some auxilary files that are present in the sub-directory
\file{config}.  Autoconf needs to be told about that.
<<auxiliary config files>>=
AC_CONFIG_AUX_DIR(config)
@

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

We require Autoconf 2.59 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.59 or higher to process this
file in order to regenerate \file{configure}.
<<Autoconf prerequirement>>=
AC_PREREQ([2.59])
@


\subsection{Source tree sanity check}

The 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, I have chosen \file{Makefile.pamphlet} from the \file{src}
subdirectory.
<<sanity check>>=
AC_CONFIG_SRCDIR(src/Makefile.pamphlet)
@


\subsection{Build Environment}

Standard build environments consist of
\begin{enumerate}
\item the \emph{host} platform,
\item the \emph{build} platform, and
\item the \emph{target} platform.
\end{enumerate}
FIXME: Example on these notions.

We need to get the canonical names for the above three platforms.
After call to this macro, those values are available in the variables
[[host]], [[build]], and [[target]], respectively.
<<host build target platfoms>>=
AC_CANONICAL_SYSTEM
@

For the moment, Axiom supports neither cross-compilation, nor Canadian cross.
Consequently, we must bail out if the build is not native.
<<check cross-compilation>>=
if test $host != $build -o $host != $target; then
   AC_MSG_ERROR([Sorry, only native builds are currently supported])
fi
@

Most of the tools we're testing for are with respect to the build
environment, neither the host nor the target.  

First of all, check for a C compiler --- \textsl{GCC/gcc} preferably.  As
written, this test is OK because currently we support only native
builds.  However, it needs to be more carefully written when we move
to cross-compilation.
<<check for C compiler>>=
AC_PROG_CC
@

Then, check for a usable 'install' program.
<<check for install>>=
AC_PROG_INSTALL
@

The old build machinery needs 'awk'.  Currently, it checks for
'gawk', 'nawk', and 'awk'.  Autoconf has a predefined test for that
task.  It checks for 'gawk', 'mawk', 'nawk', and 'awk' in that order.
That should be OK and match Axiom's need.

The old build system claims that on solaris9, gawk, gtar 
and gpatch are required (with no much explanation of why).  Notice
that these programs are needed only to build Axiom; so we do
check based on the value of [[build]].
<<check for awk tar patch>>=
case ${build} in
     *-solaris9)
        AC_CHECK_PROG([AWK], [gawk], 
                      [gawk], [AC_MSG_ERROR([Axiom needs gawk])])

        AC_CHECK_PROG([TAR], [gtar], 
                      [gtar], [AC_MSG_ERROR([Axiom needs gtar])])

        AC_CHECK_PROG([PATCH], [gpatch],
                      [gptach], [AC_MSG_ERROR([Axiom needs gpatch])]) 
        ;;

      *)
        AC_PROG_AWK

        AC_CHECK_PROGS([TAR], [gtar tar], 
                       [AC_MSG_ERROR([Axiom needs a tar program])])

        AC_CHECK_PROGS([PATCH], [gpatch patch], 
                       [AC_MSG_ERROR([Axiom needs a patch program])])
        ;;
esac
@


Once we have found those values, we must substitute them in the
Makefiles.  For the moment, these actions are effectless as the
current makefile are hand-written and Autoconf-unaware.
<<substitute AWK TAR PATCH>>=
AC_SUBST(AWK)
AC_SUBST(TAR)
AC_SUBST(PATCH)
@

Obviously we need the 'make' program.  No build will proceed without
it.
<<check for make>>=
AC_CHECK_PROG([MAKE], [make],
              [make], [AC_MSG_ERROR([`make' program missing.])])
@

Here, we replicate the behaviour of the old configure, waiting for
a better alternative, e.g. where it is not needed.  THIS WILL BE
REMOVED IN THE NEAR FUTURE.

First, the old machinery has a very coarse target name "discovery"
<<replicate old behaviour>>=
if test -f /etc/redhat-release; then 
   SYSNAME=`cat /etc/redhat-release` 
   if test "$SYSNAME" = "Fedora Core release 3 (Heidelberg)"; then
       SYSNAME=fedora3
   fi
   AC_MSG_NOTICE([SYSNAME=$SYSNAME])
fi
if test "$SYSNAME" != "fedora3"; then
   SYSNAME=`uname -s`
   AC_MSG_NOTICE([$SYSNAME])
   case "$SYSNAME" in
      Linux)
         SYSNAME=linux ;;
      MINGW32_NT-5.1)
         SYSNAME=windows ;;
      SunOS)
         SYSNAME=solaris9 ;;
      freebsd)
         ;;
      *)
         AC_MSG_NOTICE([Your system name is $SYSNAME])
         AC_MSG_NOTICE([We do not know how to build for this kind of system])
         AC_MSG_ERROR([Send a note to address@hidden about it])
   esac
fi

must_set_AXIOM() {
   AC_MSG_NOTICE([])
   AC_MSG_NOTICE([===================================================])
   AC_MSG_NOTICE([])
   AC_MSG_NOTICE([You must set your AXIOM and PATH variables. Type:])
   AC_MSG_NOTICE([])
   AC_MSG_NOTICE([export AXIOM=`pwd`/mnt/$SYSNAME])
   AC_MSG_NOTICE([export PATH=\$AXIOM/bin:\$PATH])
   case "$SYSNAME" in
      freebsd)
         AC_MSG_NOTICE([Note that freebsd usually has noweb available])
         AC_MSG_NOTICE([echo If you wish to use the standard version you must 
type])
         AC_MSG_NOTICE([touch noweb])
         AC_MSG_NOTICE([If you wish to use a pre-installed GCL you must type])
         AC_MSG_NOTICE([make GCLVERSION=gcl-system])
         ;;
      solaris9)
         AC_MSG_NOTICE([make AWK=gawk TAR=gtar PATCH=gpatch])
         ;;
      *)
         AC_MSG_NOTICE([make AWK=$AWK])
   esac
}

if test "x$AXIOM" = "x"; then
   must_set_AXIOM
elif test "`dirname $AXIOM`" != "`pwd`/mnt"; then
   must_set_AXIOM
else
   AC_MSG_NOTICE([configure complete.  Now type ])
   AC_MSG_NOTICE([                              ])
   AC_MSG_NOTICE([make])
   AC_MSG_NOTICE([                              ])
   AC_MSG_NOTICE([export AXIOM=`pwd`/mnt/$SYSNAME])
   AC_MSG_NOTICE([export PATH=\$AXIOM/bin:\$PATH])
fi
@

<<*>>=
<<Autoconf init>>

<<auxiliary config files>>

<<Automake init>>

<<Autoconf prerequirement>>

<<sanity check>>

<<host build target platfoms>>

<<check cross-compilation>>

<<check for C compiler>>

<<check for install>>

<<check for awk tar patch>>

<<substitute AWK TAR PATCH>>

<<check for make>>

<<replicate old behaviour>>
@

\end{document}