IDyOM Project

h1. Installing IDyOM

h2. Prerequisites

* "Steel Bank Common Lisp [SBCL]":http://www.sbcl.org/platform-table.html

* "Quicklisp":http://www.quicklisp.org/beta/ is a library manager for Common Lisp.  Just download "<code>quicklisp.lisp</code>":http://beta.quicklisp.org/quicklisp.lisp and follow the instructions "here":http://www.quicklisp.org/beta/

* An SQL database.  I would recommend  "SQLite":http://www.sqlite.org/ which is already installed on most recent flavours of MacOS and Linux.

It is possible to use SBCL in a terminal window but I strongly suggest using "Emacs":http://www.gnu.org/software/emacs/ and installing Slime (a Lisp interface for Emacs) which is easily done using Quicklisp (see instructions "here":http://www.quicklisp.org/beta/).

See the "CLSQL Manual":http://clsql.b9.com/manual/ for information on other database systems you can use and how to access them from Common Lisp.

h2. Install Quicklisp

First download  "<code>quicklisp.lisp</code>":http://beta.quicklisp.org/quicklisp.lisp to a directory <code>DIR_A</code>.  You can then install Quicklisp to another directory of your choice <code>DIR_B</code>:

<pre>

(load "/DIR_A/quicklisp.lisp")

(quicklisp-quickstart:install :path "/DIR_B/quicklisp/")

(ql:add-to-init-file)

</pre>

Use the full pathnames for both directories (Lisp doesn't interpret shell substitutions like ~ for the home directory).

See the "Quicklisp website":http://beta.quicklisp.org/ for documentation about other features of Quicklisp.

h2. Download IDyOM

Download the following Lisp libraries, and unzip them into <code>DIR/quicklisp/local-projects/</code>

* "idyom":https://code.soundsoftware.ac.uk/hg/idyom/archive/tip.zip

*Removing previous installations*: If you have any previous installations of these libraries, you would do well to remove them, especially if they are in folders such as '~/.local' which are automatically scanned by asdf/quicklisp. You may also want to clear the corresponding entries from <code>asdf:*central-registry*</code> in your .sbclrc file, should any exist.

h2. Set <code>*idyom-root*</code>

IDyOM requires the global variable <code>*idyom-root*</code> be set to a suitable working directory, where it stores models, cross-validation settings, cached results etc. By default, this is a directory called 'idyom' in your home directory. Alternatively, you can customise the location by setting the variable <code>*idyom-root*</code> to point to the desired directory by including the following in your <code>.sbclrc</code> file, located in your home directory (you must restart SBCL for this to take effect):

<pre>

(defvar *idyom-root* "/FULL/PATH/TO/WORKING/DIR/")

</pre>

However you configure this, you must ensure that the directory exists (create it if it doesn't) and you will also need to create three directories below <code>*idyom-root*</code> for IDyOM to use: <code>*idyom-root*/data/cache/</code>, <code>data/models/</code> and <code>data/resampling/</code>.

h2. Install IDyOM

You can now use Quicklisp to install IDyOM:

<pre>

(ql:quickload "idyom")

</pre>

This will also install the third-party Lisp libraries IDyOM depends on.  

(If you get an error which brings up the debugger, press 2 [ACCEPT] and the installation should complete.)

h2. Create a database

IDyOM is now installed, but you will need a database in order to use it.  For example, to create an SQLite database called 'example.db' in directory <code>DIR</code>:

<pre>

(clsql:connect '("DIR/example.db") :if-exists :old :database-type :sqlite3)

</pre>

Alternatively, to connect to an existing local MySQL database:

<pre>

(clsql:connect '("localhost" "example-database" "username" "password") :if-exists :old :database-type :mysql)

</pre>

See the "CLSQL documentation":http://clsql.b9.com/manual/ for more on "connect":http://clsql.b9.com/manual/connect.html and "supported databases":http://clsql.b9.com/manual/prerequisites.html#idp8251808.

Finally, for a new database: 

<pre>

(mtp-admin:initialise-database)

</pre>

h3. Problems loading foreign libraries

Depending on how your system is configured, <code>clsql:connect</code> may give a "Couldn't load foreign libraries" error.  In this case, you

need to "tell CLSQL where it can find these libraries":http://clsql.b9.com/manual/appendix.html#foreignlibs, e.g.

<pre>

(clsql:push-library-path "/usr/local/mysql/lib/")

</pre>

The exact path will depend on your system.  Note that, for some database installations these libraries may not have been installed, and you should consult the database documentation.