SAS Makefiles

Using Makefiles

Quick guide

• to build all that is needed to run, do make (either at the toplevel directory of the SAS or your package). If it reports an error, see build.html.
• to run the tests do 'make test'.
• to run a thorough check, do make check (either at the toplevel directory of the SAS or your package). If it reports an error, see check.html.
• to build part of your package during development, do make depend, make bin or make doc in a subdirectory of your package.

Explanation

1. To build the entire sas, you untar the packages in a subdirectory packages and do
   
   packages/sas/install
   ./configure
   source sas-setup.csh
   make
   
   The 'make' will build the libraries, executables and documentation. When an error occurs it will continue building the rest. If one or more errors occurred it will report an error at the very end. The file build.html provides a table with all the errors that were encountered.
   
   If you want to run the tests, you do
   
   make test
   
   This will run all tests, and exit with an error message at the end if one ore more tests failed.
   
   If you have installed all the required and optional software no error should occur, since we only distribute packages that give no error on our systems.
   
   
2. To build only your package you can do
   
   make
   
   at the toplevel of your package. This will build libraries, executables and documentation. You see a + for each stage that worked and a - if an error occurred. The file build_log contains the full make output.
   
   Unfortunately, and this is the accidental problem, if you do 'make' in a ~subdirectory~ of your package, it will do nothing and report an error. In this case you should do 'make depend', 'make bin' or 'make doc', depending on what you want to make. 
   
   
3. You can perform a thorough check on your package or on the entire SAS with 
   
   make check
   
   If run at the toplevel of the SAS, it will traverse all packages; if run at the toplevel of a package, it will check and build the package. Note that this command will clean everything first, so it is not very suited for incremental builds during development. It will produce a +/- table, and after completion the file check.html provides a table of errors.
   
   When you want to submit a package you run 
   
   make check
   
   at the toplevel of your package, and no - should appear.
   
   
4. If you want to run the stages of a make by hand, and see the commands and error rolling over your screen, you can perform the build stages by hand:
   
   make depend
   make bin
   make doc
   
   You can also do
   make clean
   or
   make clobber
   as you like
   
   All these procedures work recursively on all subdirectories.
   
   
5. After building the entire SAS, you might want to know whether enough succeeded to be able to develop new tasks. You can run
   constructManifest
   at the SAS toplevel. This will construct a file manifest.ok that contains the packages that built OK. It exits with an error if that is not enough to build new tasks.

Writing Makefiles

Each Makefile should define a few variables and then include the toplevel Makefile:

# Makefile

<var> = <value>

<var> = <value>

include $(SAS_DIR)/Make.include

• SUBDIRS
a list of all subdirectories that should be traversed
• USEDLIBS
a list of libraries to be used by the programs in this directories. The include files of these libraries will be available (both .h and .mod) and the libraries will be linked in to the executables in this directory.
• TASKS
a list of task names that have to be compiled in this directory. For each task foo a corresponding foo_OBJS variable should be defined. Note that his variable should only contain proper tasks. A proper task 'foo' is a F90 module foo_mod in a file foo_mod.f90. foo_mod should contain the subroutine foo, that takes no arguments.
• TESTBINS
a list of executables that have to be compiled for the test harness
• LIBS
a list of libraries that should be constructed in this directory. The libraries will be available to the rest of the SAS.
• TESTS
a list of programs to run as a test. Failing tests should exit with an exit status other than zero. One can add the name of test scripts to this variable. Such a script might for example provide
• TEXDOCS
a list of LaTeX documents in this directory. Do not append the .tex extension.
• DOCS
a list of entry points into the online documentation. The entry point of a TeX document 'foo' is foo/foo.html. This file will be automatically generated from the LaTeX file, but you have to add it to this variable if you want this to be an entry point into the documentation of this package.
• foo_OBJS
a list of object files to link with foo. Do not specify the .o extension. A _OBJS variable should be defined for everything that appears in TASKS BINS LIBS and TESTBINS.
• CONFIGFILES
the files that should be accessible as configuration files. This should contain for example the parameter file.
• CLEANFILES
These files will be removed when you do make clean
• CLOBBERFILES
These files will be removed when you do make clean. Add files here that are built and required to run the SAS, but that are not removed by a normal make clobber
• MKDIRS
A list of directories that should be newly created when doing make, and will be removed when doing make clobber

Examples

• A Makefile at the toplevel of the package
• A Makefile in a src subdirectory
• A Makefile in a test subdirectory
• A Makefile in a config subdirectory
• A Makefile in a doc subdirectory
• A Makefile in a lib subdirectory

• A combined Makefile for a simple package

Make.include

The configure script is generated from configure.in by the developers by running autoconf.

Modifying the rules

• edit in packages/sas
• configure.in
• Make.include.in
• config.h.in
• Run autoconf, this updates the configure script
• Run ./configure.