System and Network Administration

lecture in color

Up the long ladder

illusion: to compile software one invokes the compiler.
reality: one almost never invokes the compiler directly.
instead, one invokes meta-tools that invoke the compiler for you.

Compiling problems:

portability: programs have to run in more than one environment.
one environment: no problem.
two environments: must adapt program for each.

Why software portability is difficult:

Heterogeneity: systems upon which you wish to run the compiler differ in configuration.
Conditional compilation: dealing with heterogeneity by modifying the program that gets compiled for different circumstances.
Environmental probing: how one figures out whether the program needs modification.
Environmental probe design: creating software that always, on every platform, figures out what customizations are needed.

The big picture

Here's how we deal with adapting programs to run in multiple environments (autoconf/automake model):

 Makefile.am: description of all goals
    |                  
    | +----- configure.in: map of all constraints
    | |           | 
    | |automake   |autoconf
    | |           |
    v v           |
 Makefile.in      |
     |            |
     |configure<--+
     |
     v
  Makefile
     |
     |make
     | 
     v
 executable program!

In this diagram:
- nodes are files.
- arrows are processes.
- arrow labels are programs that accomplish the processes.
In English:
- automake reads Makefile.am and configure.in and creates Makefile.in
- autoconf reads configure.in and creates configure.
- configure reads Makefile.in and creates Makefile.
- make reads Makefile and creates desired compiled binaries.

Meta-tools: up the long ladder

gcc: compiler
- doesn't know what to compile or link
- must figure out how to compile things by hand.
make: dependency analyzer
- determines what needs to be done to build an executable.
- does dependency analysis on intermediate files.
- creates an execution order for making the files.
imake: site dependency envelope
- remembers things that don't change for your site/machine.
- generates a Makefile containing those things.
- unique to X11 and older packages
- not useful for modern programs or for working around bugs in operating systems.
configure: environment analyzer and portable code generator
- tells C programs what your environment is like.
- allows 'portable' c code to be written.
- de-facto standard for portability analysis.
autoconf and automake: how to create configure scripts!
- you describe what needs to be located or determined.
- it builds a configure script that locates it!

From the bottom up:

make
configure
autoconf and automake

Make:

analyzes dependencies between actions
orders actions into a linear sequence.
calls compilers as appropriate.
rules specified in a file Makefile (or makefile)

General form of a make rule:

line starting with word is a rule:
```
 target files : source files to use
```

lines thereafter, starting with the TAB character, are commands to execute:

 <TAB> command to use to make the target files from the source files. 
 <TAB> another command
 <TAB> another command

commands executed inside /bin/sh (not /bin/tcsh, so syntax differs slightly)
first line not starting with <TAB> ends command stream.

Sample makefile: from the old comp15

 a1: a1.cc
       g++ -g  a1.cc -o a1
 a2: a2.o /g/15/class/a2/t2.o
       g++ -g  a2.o /g/15/class/a2/t2.o -lcurses -ltermcap -o a2
 a2.o: a2.cc
       g++ -g -c a2.cc

If you say:
```
 make a1
```
then the line
```
 g++ -g a1.cc -o a1
```
gets executed.
If on the other hand you say:
```
 make a2
```
then a rather complex process happens:
1. Make figures out the sequence of things to do by converting the partial order of things to make
```
      a2.o precedes a2
      t2.o precedes a2
      a2.cc precedes a2.o
```
  into some total order of things to make:
```
      a2.cc -> a2.o -> t2.o -> a2
```
  This is called a topological sort.
2. then make proceeds to make everything it knows how to make that's older than its precedent, using that sequence and the commands given.

Make automagically:

manages dependencies between files.
reads a control file Makefile that designates dependencies between files and commands that can be used to make one file from others.
uses the timestamps on files to remake any files older than their sources.
converts the dependency partial order into a total order and executes appropriate commands in order.

Partial results

If rules specify how to make partial results, then the commands are performed in the correct order to get an up-to-date end-result. E.g.

 a1.o: a1.c a1.h
       g++ -g -c a1.c
 t1.o: t1.c a1.h
       g++ -g -c t1.c
 t1 : t1.o a1.o
       g++ -g -o t1 t1.o a1.o -lcurses -ltermcap

the command `make t1' will observe that in making t1, one has to make t1.o and a1.o, and make them first.
But if one or both of them are up to date, in the sense that they're newer than their sources, they're not remade.

Problem of the day #1

Consider the makefile

 foo: bar
       cp bar foo
 bar: baz.c 
       gcc -o bar baz.c
 clean: 
       rm bar

Assuming that your current directory only contains the Makefile and baz.c, what happens when you execute:
1. make foo
2. make bar
3. make clean in that order?

Default rules

Default rules and make variables can simplify complex makefiles.
The default transformation from a .c file to a .o file is
```
 $(CC) $(CFLAGS) -c file.c
```
where CC and CFLAGS are specified by the user. These are make variables, similar to shell variables.

This means that the Makefile:

 CC= g++
 CFLAGS= -g
 LIBS= -lcurses -ltermcap
 a1.o: a1.c a1.h
 t1.o: t1.c a1.h
 t1 : t1.o a1.o
       $(CC) $(CFLAGS) -o t1 t1.o a1.o $(LIBS)

calls two implicit rules.

Problem of the day #2

What are the implicit rules called by the above code?

Changing the default rule:

The code:
```
 .c.o: 
       $(CC) $(CFLAGS) $(MYFLAGS) -g -c $< -o $@
```
does the same thing as the one above, but has all site-specific information at the top.

Stupid `make` trick: uncompressing and unpacking files.

The following Makefile 'remembers' how to unpack files!

 hello-1.3.tar: hello-1.3.tar.gz
       gunzip $<
 hello-1.3: hello-1.3.tar
       tar xf $<

$<: special make variable contains name of dependencies

Make target conventions:

Certain conventions for target names help us remember what they do across all makefiles.
all: make everything
```
 make all      
```
makes all targets defined in the makefile, e.g.
```
 all: foo bar faw faux
```
install: make available to users
```
 make install  
```
installs all targets in a reasonable place where normal users can get to them to use them, e.g.,
```
 install: foo bar faw faux
       cp $< /usr/local/bin
```
clean: clean up after a make
```
 make clean    
```
removes all intermediate files that aren't needed in the final result, e.g.
```
 clean: 
       rm *.o
```
realclean: make clean enough to redistribute
```
 make realclean        
```
removes all created files regardless of function, e.g.:
```
 realclean: 
       rm *.o foo bar faw faux
```

Automatic dependency generation

Any .c file depends on ALL .h FILES IT INCLUDES.
If any header changes, the .c file has to be RECOMPILED.
Fortunately, gcc and g++ can automatically generate dependency parts of a makefile by tracing #include's. To do this,
```
 g++ -MM file.c file2.c file3.c ... >Make.deps
```
which generates a file of dependencies, and put the line
```
 include Make.deps
```
in your Makefile as the first line.
Method: G++ runs the C preprocessor, picks up all the #includes, collates a list of every file you include!

Things to watch out for:

gnu-make (gmake) is more powerful than make. If people require it, you'll have to install it first!
make doesn't handle cross-package dependencies. E.g., to compile g++, you have to first compile bison and flex and put them into your path. Only the README can help here.
make doesn't handle anything you don't tell it to. E.g., if you don't say things depend upon one another it'll never remake them!
you can't write a Makefile by terminal cut and paste.
- cut and paste don't preserve tab characters.
- make requires these to be preserved!

Next level: managing `make`

write software using conditional compilation rules.
never change program again.
edit Makefile to change conditions.

Simple example: calling ps in a portable way.

suppose your C program needs to call 'ps' to list processes
solaris: ps -efl
linux: ps aux

Let's write a program pssr.c that does that:

 #include <stdio.h>
 main()
 { 
 #ifdef LINUX
   system("ps aux"); 
 #else LINUX
   system("ps -efl"); 
 #endif LINUX
 }

If LINUX is defined, then it uses the first form.
If LINUX isn't defined, then it uses the second form.

Let's write a Makefile that handles both cases:

 # uncomment this for LINUX: 
 # DEFINES= -DLINUX
 pssr: pssr.c
       $(CC) $(DEFINES) pssr.c -o pssr

Let's analyze what happens:
1. if the DEFINES line is uncommented, then the compile command is
```
 gcc -DLINUX pssr.c -o pssr
```
2. if the DEFINES line is commented, then the compile command is
```
 gcc pssr.c -o pssr
```
net effect is to switch which line gets compiled into the program!

The next level: writing the `Makefile` differently

portability trick: uname command.
prints system description.

uname -a : all information known.

 SunOS conbrio 5.7 Generic_106541-11 sun4u sparc SUNW,Ultra-250

uname -n : name of operating system (Linux or SunOS).
```
 SunOS
```

Rewriting the Makefile

Let's do this in a simple way:

 #! /bin/csh
 if (`uname -n` == "Linux") then 
   echo "DEFINES= -DLINUX" >Makefile
 else 
   echo "# DEFINES= -DLINUX" >Makefile
 endif
 cat >>Makefile <<EOF2
 pssr: pssr.c
       \$(CC) \$(DEFINES) pssr.c -o pssr
 EOF2

This changes the makefile depending upon whether uname -n is |Linux| or |SunOS|!
So when make is called, the program compiles correctly!
If we call this program configure we know what we're really doing.
This is of course much simpler than a real configure

But is this a realistic technique?

This is well and good for simple programs, but realistic programs can have hundreds of environmental dependencies.
Old approach: imake.
New approach: autoconf.

Imake

a simple kludge that makes it possible to easily write machine-independent Makefile's.
runs the C preprocessor cpp on a template file you specify, after including a template file describing your system's quirks and curiosities.
The output is a Makefile that'll run your system.
You in turn refer to environment-dependent variables in that Makefile when writing rules.
Advantage: easy to interpret what Imake will do.
Disadvantage: implementor is completely at the mercy of the contents of the Imake configuration.
- If a variable is there, one can customize with respect to it.
- If a variable isn't there, there's no hope.

Imake example:

For example, the Imakefile:

 CFLAGS= -g
 foo: foo.c
       $(CC) $(CFLAGS) -c foo.c

 realclean: 
       $(RM) *.o foo foo.o

And the command `imake' generates the real Makefile:

 # Makefile generated by imake - do not edit!
 # $XConsortium: imake.c,v 1.72 92/09/14 11:44:22 rws Exp $
 #
 # The cpp used on this machine replaces all newlines and multiple tabs and
 # spaces in a macro expansion with a single space.  Imake tries to compensate
 # for this, but is not always successful.
 #
 
 # -------------------------------------------------------------------------
 # Makefile generated from "Imake.tmpl" and <Imakefile>
 # $XConsortium: Imake.tmpl,v 1.158 92/09/03 19:54:25 rws Exp $
 #
 # Platform-specific parameters may be set in the appropriate <vendor>.cf
 # configuration files.  Site-specific parameters should be set in the file
 # site.def.  Full rebuilds are recommended if any parameters are changed.
 #
 # If your C preprocessor does not define any unique symbols, you will need
 # to set BOOTSTRAPCFLAGS when rebuilding imake (usually when doing
 # "make World" the first time).
 #
 
 # -------------------------------------------------------------------------
 # site-specific configuration parameters that need to come before
 # the platform-specific parameters - edit site.def to change
 
 # site:  $XConsortium: site.def,v 1.2 91/07/30 20:26:44 rws Exp $
 
 # -------------------------------------------------------------------------
 # platform-specific configuration parameters - edit sun.cf to change
 
 #
 # platform:  $XConsortium: sun.cf,v 1.77 92/05/29 18:37:21 rws Exp $
 
 # operating system:  SunOS 5.0
 
 .INIT: Makefile
 REVCTLARCHFILE = SCCS/s.Imakefile
 REVCTLCMD = sccs get
 
 # $XConsortium: sv4Lib.rules,v 1.8 91/07/19 15:38:53 rws Exp $
 
 # -------------------------------------------------------------------------
 # site-specific configuration parameters that go after
 # the platform-specific parameters - edit site.def to change
 
 # site:  $XConsortium: site.def,v 1.2 91/07/30 20:26:44 rws Exp $
 
             SHELL = /bin/sh
 
               TOP = .
       CURRENT_DIR = .
 
                AR = ar cq
   BOOTSTRAPCFLAGS =
                CC = cc
                AS = as
 
          COMPRESS = compress
               CPP = /usr/ccs/lib/cpp $(STD_CPP_DEFINES)
     PREPROCESSCMD = cc -E $(STD_CPP_DEFINES)
           INSTALL = $(BINDIR)/bsdinst
                LD = ld
               LEX = lex
              YACC = yacc
              LINT = lint
       LINTLIBFLAG = -o
          LINTOPTS = -ax
                LN = ln -s
              MAKE = make
                MV = mv
                CP = cp
 
                RM = rm -f
             TROFF = psroff -t
          MSMACROS = -ms
               TBL = tbl
               EQN = eqn
      STD_INCLUDES =
   STD_CPP_DEFINES = -DSVR4 -DSYSV
       STD_DEFINES = -DSVR4 -DSYSV
  EXTRA_LOAD_FLAGS =
   EXTRA_LDOPTIONS =
   EXTRA_LIBRARIES = -lsocket -lnsl
              TAGS = ctags
 
     SHAREDCODEDEF =
          SHLIBDEF =
 
     PROTO_DEFINES =
 
      INSTPGMFLAGS =
 
      INSTBINFLAGS = -m 0755
      INSTUIDFLAGS = -m 4755
      INSTLIBFLAGS = -m 0644
      INSTINCFLAGS = -m 0444
      INSTMANFLAGS = -m 0444
      INSTDATFLAGS = -m 0444
     INSTKMEMFLAGS = -m 4755
 
       PROJECTROOT = $(OPENWINHOME)
       DESTDIR =
 
      TOP_INCLUDES = -I$(INCROOT)
 
       CDEBUGFLAGS = -O -xF
         CCOPTIONS = -DSYSV -DSVR4 -xF -Wa,-cg92
 
       ALLINCLUDES = $(INCLUDES) $(EXTRA_INCLUDES) $(TOP_INCLUDES) $(STD_INCLUDES)
        ALLDEFINES = $(ALLINCLUDES) $(STD_DEFINES) $(EXTRA_DEFINES) $(PROTO_DEFINES) $(DEFINES)
            CFLAGS = $(CDEBUGFLAGS) $(CCOPTIONS) $(ALLDEFINES)
         CCFLAGS = $(CDEBUGFLAGS) $(CCCOPTIONS) $(ALLDEFINES)
         LINTFLAGS = $(LINTOPTS) -DLINT $(ALLDEFINES)
 
            LDLIBS = $(SYS_LIBRARIES) $(EXTRA_LIBRARIES)
 
         LDOPTIONS = $(CDEBUGFLAGS) $(CCOPTIONS) $(EXTRA_LDOPTIONS) $(LOCAL_LDFLAGS) -L$(USRLIBDIR)
 
    LDCOMBINEFLAGS = -r
       DEPENDFLAGS =
 
         MACROFILE = sun.cf
            RM_CMD = $(RM) mapfile *.CKP *.ln *.BAK *.bak *.o core errs ,* *~ *.a .emacs_* tags TAGS make.log MakeOut *.O
 
     IMAKE_DEFINES =
 
          IRULESRC = $(CONFIGDIR)
         IMAKE_CMD = $(IMAKE) -DUseInstalled -I$(IRULESRC) $(IMAKE_DEFINES)
 
      ICONFIGFILES = $(IRULESRC)/Imake.tmpl $(IRULESRC)/Imake.rules \
                       $(IRULESRC)/Project.tmpl $(IRULESRC)/site.def \
                       $(IRULESRC)/$(MACROFILE)  \
                       $(EXTRA_ICONFIGFILES)
 
 # -------------------------------------------------------------------------
 # X Window System Build Parameters
 # $XConsortium: Project.tmpl,v 1.152 92/08/10 17:47:45 eswu Exp $
 
 # -------------------------------------------------------------------------
 # X Window System make variables; this need to be coordinated with rules
 
           PATHSEP = /
         USRLIBDIR = $(OPENWINHOME)/lib
          SHLIBDIR = $(OPENWINHOME)/lib
            BINDIR = $(OPENWINHOME)/bin
           DEMODIR = $(OPENWINHOME)/demo
           INCROOT = $(OPENWINHOME)/include
      BUILDINCROOT = $(TOP)
       BUILDINCDIR = $(BUILDINCROOT)/X11
       BUILDINCTOP = ..
            INCDIR = $(INCROOT)/X11
            ADMDIR = /usr/adm
            LIBDIR = $(USRLIBDIR)/X11
         CONFIGDIR = $(LIBDIR)/config
        LINTLIBDIR = $(USRLIBDIR)/lint
 
           FONTDIR = $(LIBDIR)/fonts
          XINITDIR = $(LIBDIR)/xinit
            XDMDIR = $(LIBDIR)/xdm
            TWMDIR = $(LIBDIR)/twm
           MANPATH = $(OPENWINHOME)/man
     MANSOURCEPATH = $(MANPATH)/man
         MANSUFFIX = n
      LIBMANSUFFIX = 3
            MANDIR = $(MANSOURCEPATH)$(MANSUFFIX)
         LIBMANDIR = $(MANSOURCEPATH)$(LIBMANSUFFIX)
            NLSDIR = $(LIBDIR)/nls
         PEXAPIDIR = $(LIBDIR)/PEX
       XAPPLOADDIR = $(LIBDIR)/app-defaults
        FONTCFLAGS = -t
 
      INSTAPPFLAGS = $(INSTDATFLAGS)
 
             IMAKE = imake
            DEPEND = makedepend
               RGB = rgb
 
             FONTC = bdftopcf
 
         MKFONTDIR = mkfontdir
         MKDIRHIER = /bin/sh $(BINDIR)/mkdirhier
 
         CONFIGSRC = $(TOP)/config
        DOCUTILSRC = $(TOP)/doc/util
         CLIENTSRC = $(TOP)/clients
           DEMOSRC = $(TOP)/demos
            LIBSRC = $(TOP)/lib
           FONTSRC = $(TOP)/../../../lib/libfont
        INCLUDESRC = $(TOP)/X11
         SERVERSRC = $(TOP)/server
           DDXSRC  = $(SERVERSRC)/ddx
           UTILSRC = $(TOP)/util
         SCRIPTSRC = $(UTILSRC)/scripts
        EXAMPLESRC = $(TOP)/examples
        CONTRIBSRC = $(TOP)/../contrib
            DOCSRC = $(TOP)/doc
            RGBSRC = $(TOP)/rgb
         DEPENDSRC = $(UTILSRC)/makedepend
          IMAKESRC = $(CONFIGSRC)
          XAUTHSRC = $(LIBSRC)/Xau
           XLIBSRC = $(LIBSRC)/X
            XMUSRC = $(LIBSRC)/Xmu
        TOOLKITSRC = $(LIBSRC)/Xt
        AWIDGETSRC = $(LIBSRC)/Xaw
        OLDXLIBSRC = $(LIBSRC)/oldX
       XDMCPLIBSRC = $(LIBSRC)/Xdmcp
 
       BDFTOPCFSRC = $(FONTSRC)/clients/bdftopcf
 
      MKFONTDIRSRC = $(FONTSRC)/clients/mkfontdir
          FSLIBSRC = $(FONTSRC)/lib/fs
     FONTSERVERSRC = $(FONTSRC)/server
      EXTENSIONSRC = $(TOP)/extensions
          XILIBSRC = $(TOP)/../../../lib/libXinput
       XTESTLIBSRC = $(EXTENSIONSRC)/lib/xtest
         PEXLIBSRC = $(EXTENSIONSRC)/lib/PEXlib
       PHIGSLIBSRC = $(EXTENSIONSRC)/lib/PEX
         DGALIBSRC = $(EXTENSIONSRC)/lib/dga
 
 # $XConsortium: sv4Lib.tmpl,v 1.8 92/06/28 17:43:23 rws Exp $
 
        SERVERETC = $(OPENWINHOME)/server/etc
 
        SERVERLIB = $(OPENWINHOME)/server/lib
 
    SERVERMODULES = $(OPENWINHOME)/server/modules
 
 SHLIBLDFLAGS = -G -z text -M mapfile
 PICFLAGS = -K PIC
 MAPFILE = mapfile
 
   DEPEXTENSIONLIB =
      EXTENSIONLIB = -lXext
 
           DEPXLIB = $(DEPEXTENSIONLIB)
          XLIBONLY = -lX11
              XLIB = $(EXTENSIONLIB) $(XLIBONLY)
 
         DEPXMULIB =
        XMULIBONLY = -lXmu
            XMULIB = $(XMULIBONLY) -z nodefs
 
        DEPOLDXLIB =
           OLDXLIB = -loldX
 
       DEPXTOOLLIB =
          XTOOLLIB = -lXt
 
         DEPXAWLIB =
            XAWLIB = -lXaw
 
         DEPXILIB =
            XILIB = -lXi
 
         DEPXTESTLIB =
            XTESTLIB = -lXtst
 
         DEPPEXLIB =
          PEXLIB = -lPEX5
 
         DEPDGALIB =
            DGALIB = -ldga
 
         SOXLIBREV = 5.0
           SOXTREV = 5.0
          SOXAWREV = 5.0
         SOOLDXREV = 5.0
          SOXMUREV = 5.0
         SOXEXTREV = 5.0
       SOXINPUTREV = 5.0
        SOXTESTREV = 1.0
        SOXTRAPREV = 1.0
          SOPEXREV = 1.0
        SODPSREV = 5
        SODGAREV = 1
 
       DEPXAUTHLIB = $(USRLIBDIR)/libXau.a
          XAUTHLIB =  -lXau
       DEPXDMCPLIB = $(USRLIBDIR)/libXdmcp.a
          XDMCPLIB =  -lXdmcp
 
         DEPPHIGSLIB = $(USRLIBDIR)/libphigs.a
            PHIGSLIB =  -lphigs
 
        DEPXBSDLIB = $(USRLIBDIR)/libXbsd.a
           XBSDLIB =  -lXbsd
 
  LINTEXTENSIONLIB = $(LINTLIBDIR)/llib-lXext.ln
          LINTXLIB = $(LINTLIBDIR)/llib-lX11.ln
           LINTXMU = $(LINTLIBDIR)/llib-lXmu.ln
         LINTXTOOL = $(LINTLIBDIR)/llib-lXt.ln
           LINTXAW = $(LINTLIBDIR)/llib-lXaw.ln
            LINTXI = $(LINTLIBDIR)/llib-lXi.ln
           LINTPEX = $(LINTLIBDIR)/llib-lPEX5.ln
         LINTPHIGS = $(LINTLIBDIR)/llib-lphigs.ln
               LINTDGA = $(LINTLIBDIR)/llib-ldga.ln
 
           DEPLIBS = $(DEPXAWLIB) $(DEPXMULIB) $(DEPXTOOLLIB) $(DEPXLIB)
 
          DEPLIBS1 = $(DEPLIBS)
          DEPLIBS2 = $(DEPLIBS)
          DEPLIBS3 = $(DEPLIBS)
 
 # -------------------------------------------------------------------------
 # Imake rules for building libraries, programs, scripts, and data files
 # rules:  $XConsortium: Imake.rules,v 1.129 92/05/29 17:01:19 rws Exp $
 
 # -------------------------------------------------------------------------
 # start of Imakefile
 
 CFLAGS= -g
 foo: foo.c
       $(CC) $(CFLAGS) -c foo.c
 
 realclean:
       $(RM) *.o foo foo.o
 
 # -------------------------------------------------------------------------
 # common rules for all Makefiles - do not edit
 
 emptyrule::
 
 dependlocal::
 includes:: $(HEADERS) $(OTHERFILES)
 
 clean::
       $(RM_CMD) "#"*
 
 Makefile:: Imakefile
       -@if [ -f Makefile ]; then set -x; \
       $(RM) Makefile.bak; $(MV) Makefile Makefile.bak; \
       else exit 0; fi
       $(IMAKE_CMD) -DTOPDIR=$(TOP) -DCURDIR=$(CURRENT_DIR)
       $(MAKE) $(MFLAGS) dependlocal
 
 tags::
       $(TAGS) -w *.[ch]
       $(TAGS) -xw *.[ch] > TAGS
 
 # -------------------------------------------------------------------------
 # empty rules for directories that do not have SUBDIRS - do not edit
 
 install::
       @echo "install in $(CURRENT_DIR) done"
 
 install.man::
       @echo "install.man in $(CURRENT_DIR) done"
 
 Makefiles::
 
 includes::
 
 # -------------------------------------------------------------------------
 # dependencies generated by makedepend

You get much more than you need.

Up another rung: autoconf and automake

imake is a passive strategy for determining configuration.
need to instead be able to make an active probe of configuration information.
main problem is to make the resulting mess manageable.
- An early example: Larry Wall's Configure.
- Current practice: autoconf, automake.

Configure

General map of Configure operation

 
Configure (discovery script) 
    |     \
    |      \  execute!
    v       \
config.sh   config.h  (to be included in program) 
    |          
    |
    v
Makefile
    |
    | make
    v
your program!

config.sh: describes `configuration' (reusable)
config.h: describes `configuration' to C programs.

Configure details

SH Script!
Figures out system dependencies.
Writes header files describing system.
Writes Makefile
So you don't have to figure out dependencies.
So you don't have to port code.

Highlights of SSH Configure

In the following, italics are comments that are not part of the code.

Figure out if our compiler works!

contents of meta/config1.txt...
put a test of confdefs.h into conftest.c and compile
cat > conftest.$ac_ext <<EOF
#line 1014 "configure"
#include "confdefs.h"
main(){return(0);}
EOF
use a mysterious incantation to compile the test program
if { (eval echo configure:1018: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest; then
  it compiled! try to run it!
  ac_cv_prog_cc_works=yes
  # If we can't run a trivial program, we are probably using a cross compiler.
  if (./conftest; exit) 2>/dev/null; then
    ac_cv_prog_cc_cross=no
  else
    ac_cv_prog_cc_cross=yes
  fi
else
  oops! it didn't compile. Give up! 
  echo "configure: failed program was:" >&5
  cat conftest.$ac_ext >&5
  ac_cv_prog_cc_works=no
fi
rm -fr conftest*

if something is really wrong, inform user
echo "$ac_t""$ac_cv_prog_cc_works" 1>&6
if test $ac_cv_prog_cc_works = no; then
  { echo "configure: error: installation or configuration problem: C compiler cannot create executables." 1>&2; exit 1; }
fi
echo $ac_n "checking whether the C compiler ($CC $CFLAGS $LDFLAGS) is a cross-compiler""... $ac_c" 1>&6
echo "configure:1038: checking whether the C compiler ($CC $CFLAGS $LDFLAGS) is a cross-compiler" >&5
echo "$ac_t""$ac_cv_prog_cc_cross" 1>&6
cross_compiling=$ac_cv_prog_cc_cross

preprocess a simple program that contains 'yes' if this is gcc
echo $ac_n "checking whether we are using GNU C""... $ac_c" 1>&6
echo "configure:1043: checking whether we are using GNU C" >&5
if eval "test \"`echo '$''{'ac_cv_prog_gcc'+set}'`\" = set"; then
  if we've already done this, then don't repeat it 
  echo $ac_n "(cached) $ac_c" 1>&6
else
  if not, make up a program that does this
  (not a real C program)
  cat > conftest.c <<EOF
#ifdef __GNUC__
  yes;
#endif
EOF
preprocess this program and if the output contains a yes, we're golden
if { ac_try='${CC-cc} -E conftest.c'; { (eval echo configure:1052: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }; } | egrep yes >/dev/null 2>&1; then
  ac_cv_prog_gcc=yes
else
  ac_cv_prog_gcc=no
fi
fi
...end of meta/config1.txt

Figure out which install program to use!

contents of meta/config2.txt...
# Find a good install program.  We prefer a C program (faster),
# so one script is as good as another.  But avoid the broken or
# incompatible versions:
# SysV /etc/install, /usr/sbin/install
# SunOS /usr/etc/install
# IRIX /sbin/install
# AIX /bin/install
# AFS /usr/afsws/bin/install, which mishandles nonexistent args
# SVR4 /usr/ucb/install, which tries to use the nonexistent group "staff"
# ./install, which can be erroneously created by make from ./install.sh.
echo $ac_n "checking for a BSD compatible install""... $ac_c" 1>&6
echo "configure:1325: checking for a BSD compatible install" >&5
if test -z "$INSTALL"; then
first check whether we've already done this before
(if so the answer is 'cached' in config.cache)
if eval "test \"`echo '$''{'ac_cv_path_install'+set}'`\" = set"; then
  echo $ac_n "(cached) $ac_c" 1>&6
else
    IFS="${IFS= 	}"; ac_save_IFS="$IFS"; IFS="${IFS}:"
  for ac_dir in $PATH; do
    # Account for people who put trailing slashes in PATH elements.
    case "$ac_dir/" in
    /|./|.//|/etc/*|/usr/sbin/*|/usr/etc/*|/sbin/*|/usr/afsws/bin/*|/usr/ucb/*) ;;
    *)
      # OSF1 and SCO ODT 3.0 have their own names for install.
      for ac_prog in ginstall installbsd scoinst install; do
        check for the first one that exists and record its name
        if test -f $ac_dir/$ac_prog; then
	  if test $ac_prog = install &&
            grep dspmsg $ac_dir/$ac_prog >/dev/null 2>&1; then
	    # AIX install.  It has an incompatible calling convention.
	    # OSF/1 installbsd also uses dspmsg, but is usable.
	    :
	  else
	    ac_cv_path_install="$ac_dir/$ac_prog -c"
	    break 2
	  fi
	fi
      done
      ;;
    esac
  done
  IFS="$ac_save_IFS"

fi
  if you didn't find one, use the default
  if test "${ac_cv_path_install+set}" = set; then
    INSTALL="$ac_cv_path_install"
  else
    # As a last resort, use the slow shell script.  We don't cache a
    # path for INSTALL within a source directory, because that will
    # break other packages using the cache if that directory is
    # removed, or if the path is relative.
    INSTALL="$ac_install_sh"
  fi
fi
echo "$ac_t""$INSTALL" 1>&6

...end of meta/config2.txt

Put this into Makefile!

INSTALL = ./install-sh -c
INSTALL_PROGRAM = ${INSTALL}
INSTALL_DATA = ${INSTALL} -m 644
INSTALL_SCRIPT = ${INSTALL_PROGRAM}

Figure out whether we can include standard #includes

contents of meta/config3.txt...
checks for headers by compiling trivial programs that include them
for ac_hdr in utime.h ulimit.h sys/resource.h
do
ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'`
echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6
echo "configure:2965: checking for $ac_hdr" >&5
check whether we already found this out and stored it in cache=
if eval "test \"`echo '$''{'ac_cv_header_$ac_safe'+set}'`\" = set"; then
  echo $ac_n "(cached) $ac_c" 1>&6
else
  this is the C program that tests whether headers exist
  cat > conftest.$ac_ext <<EOF
#line 2970 "configure"
#include "confdefs.h"
#include <$ac_hdr>
EOF
compile this pprogram
ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
{ (eval echo configure:2975: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
ac_err=`grep -v '^ *+' conftest.out`
if test -z "$ac_err"; then
  if there are no errors it worked and we have the header
  rm -rf conftest*
  eval "ac_cv_header_$ac_safe=yes"
else
  oops, there was an error, no header available
  echo "$ac_err" >&5
  echo "configure: failed program was:" >&5
  cat conftest.$ac_ext >&5
  rm -rf conftest*
  eval "ac_cv_header_$ac_safe=no"
fi
rm -f conftest*
fi
if eval "test \"`echo '$ac_cv_header_'$ac_safe`\" = yes"; then
  echo "$ac_t""yes" 1>&6
    ac_tr_hdr=HAVE_`echo $ac_hdr | sed 'y%abcdefghijklmnopqrstuvwxyz./-%ABCDEFGHIJKLMNOPQRSTUVWXYZ___%'`
record existence of header as #define
  cat >> confdefs.h <<EOF
#define $ac_tr_hdr 1
EOF
 
else
  echo "$ac_t""no" 1>&6
fi
done
...end of meta/config3.txt

Put a line into sshconf.h (to be included by all programs):
```
 
#define HAVE_ULIMIT_H 1
```

Use this in source code!

 
#ifdef HAVE_ULIMIT_H
#include <ulimit.h>
#endif /* ULIMIT_H */
...
#ifdef HAVE_ULIMIT_H
  /* Set up the file size ulimit if ULIMIT is set. */
  def = ssh_child_get_env(defenv, "ULIMIT");
  if (def != NULL && atoi(def) > 0)
    ulimit(UL_SETFSIZE, atoi(def));
#endif /* HAVE_ULIMIT_H */

The next level: autoconf

Helps programmers create configure scripts!
Has a battery of standardized tests you can apply.
Allows you to include customized tests!
Recall the big picture:

"Simple" Autoconf Example

configure.in:

contents of meta/hello-1.3/configure.in.txt...
dnl Process this file with autoconf to produce a configure script.
AC_INIT(hello.c)   these are the source files
AC_PROG_CC         find a c compiler, please
AC_PROG_CPP        find a c preprocessor, please
AC_PROG_INSTALL    find an install program 
AC_STDC_HEADERS    check for whether stdlib.h exists
AC_HAVE_HEADERS(string.h fcntl.h sys/file.h)  and whether these exist
AC_ALLOCA          is ther an alloca() function in the c library?
AC_OUTPUT(Makefile)write a Makefile as a result
...end of meta/hello-1.3/configure.in.txt

produces configure.

Makefile.am: (approximately)

contents of meta/Makefile.am.txt...
bin_PROGRAMS = hello what to compile
hello_SOURCES = hello.c version.c getopt.c getopt1.c getopt.h system.h
what to link to get hello
hello_LDADD = @INTLLIBS@ @hello@
where to find locale information
localedir = $(datadir)/locale
INCLUDES = -I../intl -DLOCALEDIR=\"$(localedir)\"
...end of meta/Makefile.am.txt

produces Makefile.in. which configure uses to produce Makefile!

What's happening?

autoconf and automake are written in m4.
m4: the macro processor.
- More powerful than C preprocessor.
- Very different syntax.
autoconf and automake scripts are simply macro calls that get expanded into sh script and make control file, respectively.

The point

It takes a term to fully understand how to assure program portability. And two books:
- One on the real powers of make.
- One on autoconf, automake, and m4.
Over 2000 separate tests of system state.
If that's not enough you can write your own.
As a system administrator, if all goes well, you need not do anything but simply run configure and make.
Get real! It is very difficult to create a perfect configure.