
				     RAMS

OVERVIEW

   RAMS is a mess of shell scripts and makefiles that collectively make
   managing the build process for ACL2 projects fairly painless.  RAMS is
   intended to be largely transparent to the user, who should interact with it
   just through "make".  To use RAMS, an ACL2 project need only create a simple
   four-line Makefile that looks like this:

   MAKEDIR = ../../../make            # (where the "make" directory lives)
   LIBS = :lib1 :lib2 :lib3           # (what libraries are needed)
   BOOKS = book1 book2 book3          # (what books to certify)
   include $(MAKEDIR)/Makefile.top    # (invoke RAMS)

   RAMS should then handle the rest, automatically calculating your books'
   dependencies and managing links to other libraries.  Of course, life can get
   more complicated when projects start using packages and depending on other
   libraries.


HOW EXTERNAL LIBRARIES ARE HANDLED

   There is a DIRS file in the make directory which lists the locations of
   :dir :foo libraries.  The LIBS line in your Makefile specifies which of
   these libraries you will use.  When RAMS starts up, it creates two new
   files in your project's directory:

    Makefile.acl2 - contains (add-include-book-dir ...) commands that set up
    ":dir :foo" links for include-book.  This file is typically ld'd in
    cert.acl2 so that these symbolic directories are available throughout your
    project.

    Makefile.dirs - used by Make, sets up ACL2_FOO_BOOKS variables for use with
    external library dependencies

   Because the DIRS file exists in only one place, this is a convenient way to
   "register" new libraries with the make system.  Essentially, you
   can add one line here, and your library will be accessible using :dir :foo
   in every project that has :foo mentioned in its LIBS.

   Note: If you want to "mix and match" different library versions, you can
   override the entries in make/DIRS by adding a new DIRS file to your own
   project directory.  The entries in this file override the global make/DIRS
   file, allowing you to easily switch libraries when desired.


HOW DEPENDENCIES ARE HANDLED

   After RAMS has established the links to external libraries, it automatically
   computes the dependencies for all of your lisp files by scanning for ld and
   include-book commands.  These dependencies are stored into a new file in
   your project's directory:

    Makfile.deps - lists the dependencies for all of the books in your project.

   The dependency calculation is relatively fast, so RAMS will perform it every
   time you invoke make.  Ideally, you should never need to worry about
   dependencies.

   Of course, there are some situations that the simple autodependency
   algorithm will not handle.  In particular, if you are generating LISP files
   to be certified later, then you will want to attach dependencies to .lisp
   files rather than .cert files, and so forth.  If you ever need dependencies
   that are not automatically computed, you can just edit the file MOREDEPS,
   and add in your new targets.  (It just gets cat'd onto Makefile.deps).


SELECTING ACL2 EXECUTABLES

   The file make/Makefile.config specifies which ACL2 executable should be used
   to build your source files.  If you want to use another ACL2 image, you
   can add ACL2=/path/to/saved_acl2 to your Makefile command line, and the
   new image will be used instead.  Of course, you need to be consistent
   across builds in which ACL2 version you use, or you can get version
   incompatibility messages.


WHATS IT DOING? (PRECIOUS)

   If you are having any trouble with your build, you can add DEBUG=1 to
   your "make" line to see debugging information.  This is disabled by
   default because when things work fine, you don't want to be flooded with
   mundane details about what is happening.


USING THE MAKEFILE

   There are several Makefile targets that you might be interested in.

     make (or, equivalently, "make all")
     Builds all of the BOOKS specified in the Makefile.

     make clean
     Removes the generated files, e.g., .cert and .o files.

     make status
     Checks with CVS to summarize the current status of each file.

     make deps
     Instructs RAMS to only generate the paths and dependency information,
     which is probably not useful unless you are debugging RAMS.

     make help
     Displays this help message.

     make foo.cert bar.cert
     Builds only the listed books (and their dependencies).



