Centaur Books
Copyright (C) 2008-2011 Centaur Technology and others (see **)

Contact Information
   Centaur Technology Formal Verification Group
   7600-C N. Capital of Texas Highway, Suite 300, Austin, TX 78731, USA.
   http://www.centtech.com/

Copyright Notice
   This program is free software; you can redistribute it and/or modify it
   under the terms of the GNU General Public License as published by the Free
   Software Foundation; either version 2 of the License, or (at your option)
   any later version.  This program is distributed in the hope that it will be
   useful but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
   Public License for more details.  You should have received a copy of the GNU
   General Public License along with this program; if not, write to the Free
   Software Foundation, Inc., 51 Franklin Street, Suite 500, Boston, MA
   02110-1335, USA.

** All of the books here are licensed under the GPL "2 or later."  Most are
   copyrights of Centaur Technology, but some are copyrights of others, e.g.,
   the books in ubdds/ are copyright of Bob Boyer and Warren Hunt; see the
   individual headers on each file for more information.  Also, note that many
   books here depend on other ACL2 libraries, each with their own copyrights
   and licenses.  We believe all libraries we include are also licensed under
   the GPL "2 or later".


-------------------------------------------------------------------------------

                   Quick Overview of the Available Books

  ubdds/
    * unlabeled bdd library
    * needs Hons and lots of memory
    * mainly used by GL

  bitops/
    * arithmetic lemmas about logand, logxor, etc.
    * bitset libraries for compactly representing sets of natural numbers

  misc/
    * lemmas about set reasoning and fast alists
    * tools for quantification (universal equivalences, witnessing stuff)
    * memory management books (critical for bdd operations)
    * miscellaneous tools and lemmas

   vl/
     * verilog toolkit (parser, transformations, static checks, ...)

   gl/
     * "bit blasting" decision procedure for ACL2 theorems involving
        finitely-constrained variables

   aig/
     * basic AIG library for use in GL, etc.

   ... and others forthcoming ...


-------------------------------------------------------------------------------

                             Getting Started

  WARNING: We expect these books to be much less stable than ordinary ACL2
  books because we are actively using them and often need to extend them.


  Prerequisites.

  We generally expect there to be ample memory available.  While many books are
  quite ordinary ACL2 stuff like arithmetic lemmas and don't need any special
  resources, you certainly won't be able to do any kind of serious BDD
  computations without, say, at least 8 GB of memory.  Even things like our
  Verilog parser are written in a memory-hungry way because that's just the
  kind of environment we work in.

  We generally use 64-bit CCL on Linux or Darwin as the host lisp, and build
  ACL2 with the Hons extension enabled.  It wouldn't be surprising if some
  books don't certify or don't function well in other setups.  A good way to
  build ACL2 might be:

     make LISP=ccl ACL2_HONS=h ACL2_SIZE=3000000

  We use cert.pl instead of Makefiles, so you'll need a working Perl
  installation.  We recommend that you:

     - Be able to invoke cert.pl by typing "cert.pl" (i.e., add a symlink
       to it to your PATH; it is located in the acl2/books directory.)

     - Be able to invoke your ACL2 image by typing "acl2" (i.e., add a
       symlink to your PATH)

  Alternately, you can invoke cert.pl directly and use the --acl2 option to
  tell it which ACL2 image to use and/or the --acl2-books option to tell it
  where the acl2 system books directory is,, but this can be cumbersome.


  Building Books and Documentation.

  To build all of the books and all of the available documentation, you should
  be able to run, in the books/centaur directory:

      cert.pl doc.lisp -j 4       # -j 4 for a quad-core processor

  Alternatively, you can do a full regression (for all of books/, not just
  books/centaur/) by standing in the acl2-sources directory and executing one
  of the following commands, where the first of these starts by cleaning all
  books.  As above, we assume four cores; also, we write "<acl2h>" for the path
  to your saved_acl2h image.

      make -j 4 regression-hons-fresh ACL2_HONS_OPT='-j4' ACL2=<acl2h>
      make -j 4 regression-hons       ACL2_HONS_OPT='-j4' ACL2=<acl2h>

  To see the resulting manual, just point your web browser to:

      books/centaur/manual/preview.html

  This manual actually also has all of the regular ACL2 documentation, as well
  as the documentation for several other ordinary ACL2 libraries that we rely
  on (e.g., str, serialize, and ihs).

  To clean the cert files, you should be able to run either of the following.

      cert.pl -c doc.lisp  # in acl2-sources/books/centaur
      make clean-books     # in acl2-sources

  Of course, the second of these will delete all certificates under the books/
  directory.  HOWEVER, note that the above cert.pl command also will delete
  some certificates not under books/centaur, namely: all certificates of books
  included by the books/centaur books.


  Getting Help.

  We can't offer any serious technical support.

  If you have questions, comments, or bug reports about these books or about
  cert.pl, please email Jared Davis and Sol Swords,
  {jared,sswords}@centtech.com; we may be able to answer some questions on an
  informal, "low bandwidth" basis.


