[Axiom-developer] [axiom] Makefile conventions

[root]

Arthur,

I've set up a mailing list for developers at:
address@hidden

You can subscribe to it online at:
http://mail.freesoftware.fsf.org/mailman/listinfo/axiom-developer

You can see the archives at:
http://mail.freesoftware.fsf.org/pipermail/axiom-developer

More conventions related to Makefiles:

The top level Makefile defines
SPAD= the full path to the root of the world. This is where the
      highest level Makefile lives.
SYS=  the name of the shipped system type (e.g. linux)
LISP= the name of the lisp we are building on
SRC=  ${SPAD}/src
INT=  ${SPAD}/int
OBJ=  ${SPAD}/obj
MNT=  ${SPAD}/mnt/${SYS}
LSP=  ${SPAD}/lsp/${LISP}

so if we are building a system in /home/axiom for linux using ccl these
would look like:

SPAD= /home/axiom
SYS=  linux
LISP= ccl
SRC=  /home/axiom/src
INT=  /home/axiom/int
OBJ=  /home/axiom/obj
MNT=  /home/axiom/mnt/linux
LSP=  /home/axiom/lsp/ccl


We need to keep track of where we are and where we are putting files.
In order to solve this problem we want to name 3 "places" we want to be.
The first is where we have the input (IN), 
the second is where we have space to work (MID) and 
the third is where we want the result (OUT).

Each Makefile (one per src directory) defines 3 local variables (if needed):

IN=  the full path to the src directory where the Makefile lives
MID= the full path to the "working directory" 
       this could be in the int subtree if the file that gets
       created is system independent but machine generated or
       this could be in the obj subtree if the file that gets
       created is system dependent but machine generated.
OUT= the full path to the target directory
       this might be the mnt/${SYS}/bin directory, for example,
       if the result of the make is a shipped executable file.

for example, 
IN=${SRC}/boot
MID=${INT}/boot
OUT=${OBJ}/boot

so, in general, a "standard stanza set" will look like:

${OUT}/boothdr.o: ${MID}/boothdr.lisp
        @ echo making ${OUT}/boothdr.o from ${MID}/boothdr.lisp
        @ ( cd ${MID} ; \
           echo '(progn  (compile-file "${MID}/boothdr.lisp" :output-file 
"${OUT}/boothdr.${O}") (${BYE}))' | ${LISPSYS}  )
 
${MID}/boothdr.lisp:    ${IN}/boothdr.lisp
        @ echo making ${MID}/boothdr.lisp from ${IN}/boothdr.lisp
        @ cp ${IN}/boothdr.lisp ${MID}/boothdr.lisp

Note that the there are two stanzas related to the boothdr.lisp file. 
The idea is that the second stanza will go from our input file to
our work directory (IN->MID) and the first stanza will go from our
work directory to where we want the result (MID->OUT). This two step
process, while tedious to write, allows us to cache work in the MID
subdirectory. In general, after the first system build, the second
stanzas will never be executed again unless the source files change.
This can result in a considerable savings (for example, depsys images
are cached after being built). For more detail:

The second stanza takes 
  ${IN}/boothdr.lisp -> (by copy) -> ${MID}/boothdr.lisp

  (a) since this is a "system independent" file it creates a copy in the
      int subdirectory (MID=/spad/int/boot).
  (b) since there is no other processing required it just copies.
  (c) the MID file is now in the cache (since this only required a
      copy in this case it hardly matters but overall it saves a lot)

The first stanza takes
  ${MID}/boothdr.lisp -> (compile-file piped into lisp) -> ${OUT}/boothdr.o

  (a) since this is a "system dependent" file it creates the compiled
      output in the obj subdirectory.
  (b) since this file is not shipped with the system there is nothing
      created in the mnt subdirectory.
  (c) note the ( cd ${MID} ; do-the-compile-command ) style.
      this makes sure that we are not trying to work in the src directory.
      (in this case the compiler does not generate tmp files so it doesn't
       matter where we work but the style is followed anyway)


By convention there are two stanzas per file. We don't depend
on default rules for make stanzas so each subdirectory's Makefile
is very explicit about the steps necessary to make a file properly.

By convention the first line in a stanza echos what the stanza does.
All other operations in the stanza are quiet (have a preceeding '@')
This is useful for quickly finding where a build failed.
   
Tim