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
* An SQL database. I would recommend "SQLite":http://www.sqlite.org/

Many people find "Emacs":http://www.gnu.org/software/emacs/ with "Slime":http://common-lisp.net/project/slime/ useful for Common Lisp development. Package management systems can simplify the installation of these prerequisites, e.g. "Fink":http://www.finkproject.org/ or "Macports":http://www.macports.org/ for OS X.

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. If you prefer not to use Quicklisp, you will need to install the following Lisp libraries: "UFFI":http://uffi.bi.com, "CLSQL":http://clsql.b9.com, "CL-PPCRE":http://www.weitz.de/cl-ppcre/, "PS-Graph":http://www.cliki.net/psgraph, "Midi":http://www.cliki.net/midi

If you are a new user of Quicklisp and you have existing installations of any of these libraries, then you would do well to remove them and clear the corresponding ASDF entries from your .sbclrc file first.

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).

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/stable.zip
* "AMuSE":https://code.soundsoftware.ac.uk/hg/amuse/archive/tip.zip
* "amuse-viewpoints":https://code.soundsoftware.ac.uk/hg/amuse-viewpoints/archive/tip.zip
* "MIPS":https://code.soundsoftware.ac.uk/hg/mips/archive/tip.zip
* "mtp-admin":https://code.soundsoftware.ac.uk/hg/mtp-admin/archive/tip.zip
* "ppm-star":https://code.soundsoftware.ac.uk/hg/ppm-star/archive/tip.zip

The <code>local-projects</code> directory should now contain six subdirectories, one for each library.

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 can cache results etc. By default, this is a directory called 'idyom' in your home directory. Alternatively, Additionally, you can customise the location by setting the variable need to create three directories below <code>*idyom-root*</code> for IDyOM to point use: &lt;code&gt;*idyom-root*/data/cache/&lt;/code&gt;, &lt;code&gt;data/models/&lt;/code&gt; and &lt;code&gt;data/resampling/&lt;/code&gt;.

One way to ensure &lt;code&gt;*idyom-root*&lt;/code&gt; always points to the desired correct directory by including is to include the following in your <code>.sbclrc</code> file, located in your home directory (you must directory, and then restart SBCL for this to take effect): SBCL:

<pre>
(defvar *idyom-root* "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. The first time it loads, you may 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. To create an SQLite database 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>

You may now proceed to the [[tutorial]].

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.

h2. Create a startup script [optional]

Every time you start IDyOM, you will need to connect to the database. You may find it easier to combine all the startup commands in a single script, e.g.

<pre>
(ql:quickload "idyom")
(clsql:push-library-path "/usr/local/mysql/lib/")
(defun connect-example ()
(clsql:connect '("DIR/example.db") :if-exists :old :database-type :sqlite3))
(connect-example)
</pre>