INSTALL

Install Instructions for Motion Grammar Kit

The Motion-Grammar-Kit is implemented in Common Lisp and C.  The Lisp
portion loads using ASDF.  The C portion builds with the conventional
autotools `./configure && make && make install`.

* To quickly get started, you can download a binary Lisp core file
  from http://code.golems.org/pkg/mgk/core/.

* Deb packages for Debian and Ubuntu are also available from
  http://code.golems.org/debian.

* Installation from source is summarized under the "Short
  Instructions".  For a step-by-step guide, please see the "Detailed
  Instructions" below.

Binaries
========

Binaries for the lisp code are available at
http://code.golems.org/pkg/mgk/core/.  These are executable lisp core
files containing all dependencies, so installation is simply copying
the file to your bin directory (e.g. /usr/local/bin/).

Debian Packages
===============

1. Add the following to /etc/apt/sources:

    http://code.golems.org/debian squeeze golems.org

  (substitute the codename for your distribution in place of squeeze,
  e.g. wheezy, precise)

2. `sudo apt-get update && sudo apt-get install libmotgram-dev motgramlisp`

Short Instructions
==================

Dependencies
------------

A few dependencies on some typical lisp libraries, plus the author's
tree and finite set library.  Most dependencies are installable using
the Quicklisp library manager (http://www.quicklisp.org/)

* CL-PPCRE -- quicklisp or http://weitz.de/cl-ppcre/
* ALEXANDRIA -- quicklisp or http://common-lisp.net/project/alexandria/
* CFFI -- quicklisp or http://common-lisp.net/project/cffi/
* LISP-UNIT -- for tests only, quicklisp or
  http://www.cs.northwestern.edu/academics/courses/325/readings/lisp-unit.html
* SYCAMORE -- http://ndantam.github.com/sycamore/ or
              $ git clone https://github.com/ndantam/sycamore
* CL-FUZZ -- for tests only, http://ndantam.github.com/cl-fuzz/ or
              $ git clone https://github.com/ndantam/cl-fuzz

Motion-Grammar-Kit
------------------

* `git clone https://github.com/golems/motion-grammar-kit`
*  Set your ASDF symlink, and load it up!

Libmotgram
----------
* ./configure && make && make install
* If the Ach library is detected, support will automatically be
  enabled.

Detailed Instructions
=====================

These step-by-step instructions describe how to install a Common Lisp
development environment, install the various dependencies, and load
the Motion-Grammar-Kit.

Install a Common Lisp System
----------------------------

First, you will need to install a Common Lisp system, giving you the
lisp compiler and runtime environment.  The SBCL implementation
(http://www.sbcl.org/) is a popular Free lisp with a very good
compiler that run on most popular unix-like systems.  Microsoft
Windows support on SBCL is present but rather new, so CLISP
(http://www.clisp.org/) is another option.  Clozure CL is another
Free, fast lisp that also includes an IDE for MacOSX.

* Debian / Ubuntu
  * `sudo apt-get install sbcl`
* All Others
  * SBCL -- http://www.sbcl.org/platform-table.html (or your favorite
    package manager)
  * Clozure -- http://ccl.clozure.com/ (or package manager)
  * CLISP -- http://www.clisp.org/ (or package manager)

Install Quicklisp
-----------------

Quicklisp is a package manager for lisp, similar to CPAN, RubyGems,
Python's easy_install, and ELPA.  At the time of writing, it is the
easiest way to install Lisp packages.  You can install Quicklisp from
http://www.quicklisp.org/.

Alternatively, Debian Wheezy and Ubuntu Precise (or later) contain a
package for quicklisp:

    $ sudo apt-get install cl-quicklisp

Then, the following command will setup quicklisp for your user account:

    $ sbcl --load /usr/share/cl-quicklisp/quicklisp.lisp \
           --eval '(quicklisp-quickstart:install)'       \
           --eval '(ql:add-to-init-file)'                \
           --eval '(quit)'

Install Development Environment
-------------------------------

Lisp development is typically done interactively with a running Lisp
process, similar to systems such as Matlab or Mathematica.  It is very
convenient to have a text editor which supports communication with a
running lisp.  The Superior Lisp Interacton Mode for Emacs (SLIME,
http://common-lisp.net/project/slime/) provides a good lisp interface.

* Debian / Ubuntu:
  * `sudo apt-get install emacs slime`
* Install via quicklisp:
  * `sbcl --eval '(ql:quickload "quicklisp-slime-helper")'`
* All Others
  * Emacs -- http://www.gnu.org/software/emacs/#Obtaining (or package
    manager)
  * Slime -- http://common-lisp.net/project/slime/ (or package manager)

Then, start emacs and type `M-x slime`.  (If you are new to emacs as
well, "M-x slime" means push Alt-x, then type "slime").  This will
give you the "REPL" (read-eval-print-loop), where you can
interactively run lisp code.  More information is available in the
Slime manual: http://common-lisp.net/project/slime/doc/html/.

There are some alternatives to Slime as well.  Eclipse users may
prefer the Cusp environment (http://bitfauna.com/projects/cusp/).  On
MacOSX, you can use the ClozureCL IDE.  Lispworks
(http://www.lispworks.com/) and Allegro CL (http://www.franz.com/) are
two commercial, proprietary lisps that come with IDEs.

ASDF and Other Dependencies
---------------------------

ASDF is a build system for Common Lisp, similar to make or ant.  To
load ASDF systems into a lisp, you must define where the system
definition files (*.asd) are stored.  Generally, one picks a single
directory to place symlinks to the asd files for each separate system.
Then, that directory is specified in the startup file for the lisp.
To store the asd symlinks under ~/.asdf/systems/, add the following
code to your lisp startup file:

    (pushnew '(merge-pathnames ".asdf/systems/"
               (user-homedir-pathname))
             asdf:*central-registry*
             :test #'equal)

Startup files for various lisps are:

* SBCL -- ~/.sbclrc
* CLISP -- ~/.clisprc.lisp
* Clozure -- ~/.ccl-init.lisp

Note that your lisp may not automatically load the ASDF package, so it
may be necessary to insert the following line at the beginning of the
startup file:

    (require 'asdf)

Next, you need to install the SYCAMORE lisp library, available at
http://ndantam.github.com/sycamore/ or with:

    $ git clone https://github.com/ndantam/sycamore

Once you have obtained the source, put a symbolic link to sycamore.asd
under ~/.asdf/systems (or some other directory you have set).

    $ ln -s /path/to/sycamore/sycamore.asd ~/.asdf/systems/sycamore.asd

Similarly, you can install CL-FUZZ from
http://ndantam.github.com/cl-fuzz/ or with:

    $ git clone https://github.com/ndantam/cl-fuzz

Then, add the appropriate symbolic link:

    $ ln -s /path/to/cl-fuzz/cl-fuzz.asd ~/.asdf/systems/cl-fuzz.asd

You can then load CL-FUZZ and SYCAMORE from the lisp REPL with:

    (ql:quickload :cl-fuzz)
    (ql:quickload :sycamore)

Install Motion-Grammar-Kit Package
----------------------------------

Now, download the source for the Motion-Grammar-Kit from
http://golems.github.com/motion-grammar-kit/ (unless you already have
it):

    $ git clone https://github.com/golems/motion-grammar-kit

Then, put the symlink for src/motion-grammar-kit.asd under
~/.asdf/systems/ (or your preferred directory):

    $ ln -s /path/to/motion-grammar-kit/src/motion-grammar-kit.asd ~/.asdf/systems/motion-grammar-kit.asd

Finally, load it from the REPL with:

    (ql:quickload :motion-grammar-kit)

and the package is loaded.

Build libmotgram
----------------

0. If you have obtained the Motion-Grammar-Kit from the git repo, you
   need to initialize the autotools build scripts.  This requires the
   autotools and the autoconf macro archive. To install these on
   Debian or Ubuntu GNU/Linux, you can do

    $ sudo apt-get install autoconf automake libtool autoconf-archive

Then, initialize autotools with

    $ autoreconf -i

This whole step is not necessary when you have obtained a distribution
tarball which already contains the autoconf-generated configure script.

1. Configure for your system:

    $ ./configure

If the Ach library is detected, support will automatically be enabled.
To disable Ach support in this case, add the `--without-ach` file to
configure: `$ ./configure --without-ach`.

2. Build:

    $ make

3. Install:

    $ sudo make install