Installation » History » Version 46

Marcus Pearce, 2014-06-03 07:13 PM

1 46 Marcus Pearce
h1. Installing and Loading IDyOM
2 1 Marcus Pearce
3 46 Marcus Pearce
{{>toc}}
4 1 Marcus Pearce
5 46 Marcus Pearce
h2. Summary
6 1 Marcus Pearce
7 46 Marcus Pearce
* Download "Steel Bank Common Lisp [SBCL]":http://www.sbcl.org/platform-table.html and "install":http://www.sbcl.org/getting.html
8 46 Marcus Pearce
* Install Emacs ("see here for MacOS":http://emacsformacosx.com/)
9 46 Marcus Pearce
* Install "Quicklisp":http://www.quicklisp.org/beta/, a library manager for Common Lisp: download "<code>quicklisp.lisp</code>":http://beta.quicklisp.org/quicklisp.lisp and follow the instructions "here":http://www.quicklisp.org/beta/
10 46 Marcus Pearce
* (Optional) Install an SQL database - I recommend  "SQLite":http://www.sqlite.org/ which is already installed on most recent flavours of MacOS and Linux. 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.
11 46 Marcus Pearce
* Install and setup the IDyOM code itself
12 1 Marcus Pearce
13 46 Marcus Pearce
The following is a description of each of these steps tested on MacOS 10.7.5 and Ubuntu 14.04 (GNU/Linux 3.13.0-24-generic x86_64).
14 46 Marcus Pearce
15 46 Marcus Pearce
h2. Install SBCL
16 46 Marcus Pearce
17 46 Marcus Pearce
# download SBCL for MacOS X (the AMD64 version) here:
18 46 Marcus Pearce
19 46 Marcus Pearce
http://www.sbcl.org/platform-table.html
20 46 Marcus Pearce
21 46 Marcus Pearce
# on MacOS make sure you have the Xcode developer tools installed from the DVD that came with your Mac (required for GNU make)
22 46 Marcus Pearce
23 46 Marcus Pearce
# install SBCL by following the instructions here:
24 46 Marcus Pearce
25 46 Marcus Pearce
http://www.sbcl.org/getting.html
26 46 Marcus Pearce
27 46 Marcus Pearce
(Basically: unpack the downloaded tar.bz2 file, open a terminal window, 
28 46 Marcus Pearce
change directory ('cd') into the unpacked directory and type 'sudo sh 
29 46 Marcus Pearce
install.sh').
30 27 Marcus Pearce
31 7 Jeremy Gow
h2. Install Quicklisp
32 1 Marcus Pearce
33 43 Marcus Pearce
First download  "<code>quicklisp.lisp</code>":http://beta.quicklisp.org/quicklisp.lisp to a directory <code>DIR_A</code>. Then start SBCL by typing <code>sbcl</code> in a terminal window and install Quicklisp to another directory of your choice <code>DIR_B</code>:
34 1 Marcus Pearce
35 1 Marcus Pearce
<pre>
36 22 Jeremy Gow
(load "/DIR_A/quicklisp.lisp")
37 22 Jeremy Gow
(quicklisp-quickstart:install :path "/DIR_B/quicklisp/")
38 1 Marcus Pearce
(ql:add-to-init-file)
39 40 Marcus Pearce
(ql:quickload "quicklisp-slime-helper")
40 1 Marcus Pearce
</pre>
41 22 Jeremy Gow
42 43 Marcus Pearce
Use the full pathnames for both directories (when run in the terminal, SBCL doesn't interpret shell substitutions like ~ for the home directory).
43 40 Marcus Pearce
44 40 Marcus Pearce
Remember to follow the instructions given by each of these commands (in particular the final command includes some lines of code to put in the emacs configuration file - usually called <code>.emacs</code> in your home directory). 
45 1 Marcus Pearce
46 32 Marcus Pearce
See the "Quicklisp website":http://beta.quicklisp.org/ for documentation about other features of Quicklisp.
47 32 Marcus Pearce
48 7 Jeremy Gow
h2. Download IDyOM
49 1 Marcus Pearce
50 42 Marcus Pearce
Download the IDyOM software, and unzip it into <code>DIR_B/quicklisp/local-projects/</code>
51 1 Marcus Pearce
52 36 Marcus Pearce
* "idyom":https://code.soundsoftware.ac.uk/hg/idyom/archive/tip.zip
53 9 Jeremy Gow
54 42 Marcus Pearce
*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.
55 34 Marcus Pearce
56 12 Jeremy Gow
h2. Set <code>*idyom-root*</code>
57 1 Marcus Pearce
58 28 Marcus Pearce
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):
59 21 Jeremy Gow
60 1 Marcus Pearce
<pre>
61 29 Marcus Pearce
(defvar *idyom-root* "/FULL/PATH/TO/WORKING/DIR/")
62 1 Marcus Pearce
</pre>
63 28 Marcus Pearce
64 10 Jeremy Gow
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>.
65 16 Jeremy Gow
66 1 Marcus Pearce
h2. Install IDyOM
67 7 Jeremy Gow
68 9 Jeremy Gow
You can now use Quicklisp to install IDyOM:
69 31 Marcus Pearce
70 5 Marcus Pearce
<pre>
71 7 Jeremy Gow
(ql:quickload "idyom")
72 1 Marcus Pearce
</pre>
73 31 Marcus Pearce
74 31 Marcus Pearce
This will also install the third-party Lisp libraries IDyOM depends on.  
75 31 Marcus Pearce
76 31 Marcus Pearce
(If you get an error which brings up the debugger, press 2 [ACCEPT] and the installation should complete.)
77 1 Marcus Pearce
78 7 Jeremy Gow
h2. Create a database
79 1 Marcus Pearce
80 30 Marcus Pearce
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>:
81 5 Marcus Pearce
82 1 Marcus Pearce
<pre>
83 1 Marcus Pearce
(clsql:connect '("DIR/example.db") :if-exists :old :database-type :sqlite3)
84 8 Jeremy Gow
</pre>
85 8 Jeremy Gow
Alternatively, to connect to an existing local MySQL database:
86 8 Jeremy Gow
<pre>
87 8 Jeremy Gow
(clsql:connect '("localhost" "example-database" "username" "password") :if-exists :old :database-type :mysql)
88 8 Jeremy Gow
</pre>
89 8 Jeremy Gow
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.
90 8 Jeremy Gow
91 8 Jeremy Gow
Finally, for a new database: 
92 8 Jeremy Gow
<pre>
93 7 Jeremy Gow
(mtp-admin:initialise-database)
94 7 Jeremy Gow
</pre>
95 1 Marcus Pearce
96 8 Jeremy Gow
97 8 Jeremy Gow
h3. Problems loading foreign libraries
98 8 Jeremy Gow
99 8 Jeremy Gow
Depending on how your system is configured, <code>clsql:connect</code> may give a "Couldn't load foreign libraries" error.  In this case, you
100 8 Jeremy Gow
need to "tell CLSQL where it can find these libraries":http://clsql.b9.com/manual/appendix.html#foreignlibs, e.g.
101 8 Jeremy Gow
<pre>
102 8 Jeremy Gow
(clsql:push-library-path "/usr/local/mysql/lib/")
103 8 Jeremy Gow
</pre>
104 9 Jeremy Gow
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.
105 44 Marcus Pearce
106 44 Marcus Pearce
h1. Starting IDyOM
107 44 Marcus Pearce
108 44 Marcus Pearce
Having [[Installation|installed IDyOM]], you can load the system by running Common Lisp and using <code>quickload</code>:
109 44 Marcus Pearce
<pre>
110 44 Marcus Pearce
(ql:quickload "idyom")
111 44 Marcus Pearce
</pre>
112 44 Marcus Pearce
You then need to reconnect to your database.  For example, if you have an SQLite database located at DIR/example.db then:
113 44 Marcus Pearce
<pre>
114 44 Marcus Pearce
(clsql:connect '("DIR/example.db") :if-exists :old :database-type :sqlite3)
115 44 Marcus Pearce
</pre>
116 44 Marcus Pearce
117 44 Marcus Pearce
h2. Create a startup script [optional]
118 44 Marcus Pearce
119 44 Marcus Pearce
Every time you start IDyOM, you will need to connect to the database.  You may find it easier to combine all the startup commands and put them in the SBCL configuration file <code>.sbclrc</code> in your home directory. Here is my complete <code>.sbclrc</code> file:
120 44 Marcus Pearce
121 44 Marcus Pearce
<pre>
122 44 Marcus Pearce
;;; The following lines added by ql:add-to-init-file:
123 44 Marcus Pearce
#-quicklisp
124 44 Marcus Pearce
(let ((quicklisp-init (merge-pathnames "quicklisp/setup.lisp"
125 44 Marcus Pearce
                                       (user-homedir-pathname))))
126 44 Marcus Pearce
  (when (probe-file quicklisp-init)
127 44 Marcus Pearce
    (load quicklisp-init)))
128 44 Marcus Pearce
129 44 Marcus Pearce
;;; Load CLSQL by default
130 44 Marcus Pearce
(ql:quickload "clsql")
131 44 Marcus Pearce
132 44 Marcus Pearce
;;; IDyOM
133 44 Marcus Pearce
(defun start-idyom () 
134 44 Marcus Pearce
  (defvar *idyom-root* "/Users/marcusp/idyom/")
135 44 Marcus Pearce
  (ql:quickload "idyom")
136 44 Marcus Pearce
  (clsql:connect '("/Users/marcusp/idyom/db/database-cents.sqlite") :if-exists :old :database-type :sqlite3))
137 44 Marcus Pearce
</pre>
138 44 Marcus Pearce
139 44 Marcus Pearce
You will need to change the path and filenames. Then after starting Emacs and SBCL, you can just run <code>(start-idyom)</code> to load IDyOM and connect to the database.