Installation » History » Version 65

Marcus Pearce, 2014-06-10 10:36 AM

1 47 Marcus Pearce
h1. Installing IDyOM and its prerequisites
2 1 Marcus Pearce
3 46 Marcus Pearce
{{>toc}}
4 1 Marcus Pearce
5 46 Marcus Pearce
h2. Summary
6 1 Marcus Pearce
7 50 Marcus Pearce
# Download "Steel Bank Common Lisp [SBCL]":http://www.sbcl.org/platform-table.html and "install it":http://www.sbcl.org/getting.html
8 61 Marcus Pearce
# Install Emacs ("available here for MacOS":http://emacsformacosx.com/)
9 61 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/#installation)
10 50 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 50 Marcus Pearce
# Install and setup the IDyOM code itself
12 1 Marcus Pearce
13 60 Marcus Pearce
The following is a detailed 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). It has been successfully installed on Windows following the same basic steps but I don't have a Windows machine to test the detailed instructions.
14 46 Marcus Pearce
15 51 Marcus Pearce
h2. 1. Install SBCL
16 46 Marcus Pearce
17 48 Marcus Pearce
# download SBCL for MacOS X (the AMD64 version) here: http://www.sbcl.org/platform-table.html
18 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)
19 49 Marcus Pearce
# install SBCL by following the instructions here: http://www.sbcl.org/getting.html (Basically: unpack the downloaded tar.bz2 file, open a terminal window, change directory (<code>cd</code>) into the unpacked directory and type <code>sudo sh install.sh</code>).
20 1 Marcus Pearce
21 51 Marcus Pearce
h2. 2. Download and install Emacs
22 47 Marcus Pearce
23 47 Marcus Pearce
MacOS: Universal binaries available here: http://emacsformacosx.com/
24 47 Marcus Pearce
Linux: <code>sudo apt-get install emacs</code>
25 47 Marcus Pearce
26 51 Marcus Pearce
h2. 3. Install Quicklisp
27 47 Marcus Pearce
28 65 Marcus Pearce
*NB:* the full, original instructions are here http://www.quicklisp.org/beta/#installation. The following is my summary.
29 65 Marcus Pearce
30 47 Marcus Pearce
# make a new folder in your home directory called 'quicklisp'
31 47 Marcus Pearce
# download the file http://beta.quicklisp.org/quicklisp.lisp and put it into the new folder
32 47 Marcus Pearce
# open a terminal window and type 'sbcl' to start sbcl
33 47 Marcus Pearce
# type each of the following lines followed by enter, changing the path to match the location of your quicklisp folder:
34 1 Marcus Pearce
<pre>
35 1 Marcus Pearce
(load "/Users/marcusp/quicklisp/quicklisp.lisp")
36 47 Marcus Pearce
(quicklisp-quickstart:install :path "/Users/marcusp/quicklisp/")
37 47 Marcus Pearce
(ql:add-to-init-file)
38 47 Marcus Pearce
(ql:quickload "quicklisp-slime-helper")
39 49 Marcus Pearce
</pre>
40 64 Marcus Pearce
# Remember to follow the instructions given by each of these commands. *In particular*, the final command prints some lines of code to copy and paste into the emacs configuration file called <code>.emacs</code> in your home directory (you must create this file in Emacs or another text editor): 
41 64 Marcus Pearce
<pre>
42 64 Marcus Pearce
To use, add this to your ~/.emacs:
43 64 Marcus Pearce
44 64 Marcus Pearce
  (load (expand-file-name "~/quicklisp/slime-helper.el"))
45 64 Marcus Pearce
  ;; Replace "sbcl" with the path to your implementation
46 64 Marcus Pearce
  (setq inferior-lisp-program "sbcl")
47 64 Marcus Pearce
</pre>
48 47 Marcus Pearce
# open (or restart) Emacs, press Alt-x and type slime - you should now be running SBCL from within Emacs
49 1 Marcus Pearce
50 52 Marcus Pearce
h2. 4. Install an SQL database
51 1 Marcus Pearce
52 52 Marcus Pearce
MacOS: No action required, Sqlite is already installed (unless you prefer a different database system, see below).
53 57 Marcus Pearce
Linux: <code>sudo apt-get install sqlite</code>
54 52 Marcus Pearce
55 52 Marcus Pearce
h2. 5. Install IDyOM
56 52 Marcus Pearce
57 62 Marcus Pearce
# download the latest release of the IDyOM code:
58 62 Marcus Pearce
** "latest release: v1.0":https://code.soundsoftware.ac.uk/attachments/download/1104/idyom-1.0.zip
59 62 Marcus Pearce
** "older releases":https://code.soundsoftware.ac.uk/projects/idyom-project/files 
60 47 Marcus Pearce
# unzip the zip file into the folder 'local-projects' within the 'quicklisp' folder (e.g., '/Users/marcusp/quicklisp/local-projects/')
61 47 Marcus Pearce
# make a folder in your home directory called 'idyom'. Within that folder make two further folders, one called 'db', the other called 'data'. Within the 'data' folder make three further folders called 'cache', 'models' and 'resampling'.
62 1 Marcus Pearce
# using Emacs or another text editor open the file called '.sbclrc' in your home directory and add the following lines to the end of the file (the file should already have some lisp code in it), changing the paths to match the location of the 'idyom' folder you created in step 3:
63 47 Marcus Pearce
<pre>
64 47 Marcus Pearce
;;; Load CLSQL by default
65 47 Marcus Pearce
(ql:quickload "clsql")
66 1 Marcus Pearce
67 47 Marcus Pearce
;;; IDyOM
68 47 Marcus Pearce
(defun start-idyom ()
69 47 Marcus Pearce
   (defvar *idyom-root* "/Users/marcusp/idyom/")
70 47 Marcus Pearce
   (ql:quickload "idyom")
71 63 Marcus Pearce
   (clsql:connect '("/Users/marcusp/idyom/db/database.sqlite") :if-exists :old :database-type :sqlite3))
72 47 Marcus Pearce
</pre>
73 47 Marcus Pearce
# Restart Emacs, run Slime again (<code>Alt-x slime</code>) and type <code>(start-idyom)</code> at the prompt, <code>CL-USER></code>, to load IDyOM. The first time you run this, it will also download all the required third-party lisp libraries.
74 47 Marcus Pearce
# The first time you run IDyOM, you must initialise the database by issuing the following command at the prompt (<code>CL-USER></code>):
75 8 Jeremy Gow
<pre>
76 1 Marcus Pearce
(mtp-admin:initialise-database)
77 8 Jeremy Gow
</pre>
78 47 Marcus Pearce
NB: if you run this command later it will delete all the contents of your database, so only run it once.
79 8 Jeremy Gow
80 47 Marcus Pearce
h1. Starting IDyOM
81 1 Marcus Pearce
82 47 Marcus Pearce
Having installed IDyOM as described above, you can start it by:
83 47 Marcus Pearce
84 50 Marcus Pearce
# launching Emacs
85 44 Marcus Pearce
# typing <code>Alt-x slime</code>
86 47 Marcus Pearce
# entering <code>(start-idyom)</code> at the Lisp prompt, <code>CL-USER></code>
87 44 Marcus Pearce
88 44 Marcus Pearce
h1. Troubleshooting
89 1 Marcus Pearce
90 52 Marcus Pearce
h2. The lisp debugger
91 52 Marcus Pearce
92 52 Marcus Pearce
If you find yourself with something like this:
93 52 Marcus Pearce
94 52 Marcus Pearce
<pre>
95 52 Marcus Pearce
* (/ 1 0)
96 52 Marcus Pearce
97 52 Marcus Pearce
debugger invoked on a DIVISION-BY-ZERO:
98 52 Marcus Pearce
  arithmetic error DIVISION-BY-ZERO signalled
99 52 Marcus Pearce
Operation was SB-KERNEL::DIVISION, operands (1 0).
100 52 Marcus Pearce
101 52 Marcus Pearce
Type HELP for debugger help, or (SB-EXT:EXIT) to exit from SBCL.
102 52 Marcus Pearce
103 52 Marcus Pearce
restarts (invokable by number or by possibly-abbreviated name):
104 52 Marcus Pearce
  0: [ABORT] Exit debugger, returning to top level.
105 52 Marcus Pearce
106 52 Marcus Pearce
(SB-KERNEL::INTEGER-/-INTEGER 1 0)
107 52 Marcus Pearce
0] 
108 52 Marcus Pearce
</pre>
109 52 Marcus Pearce
110 52 Marcus Pearce
Then you have typed something that lisp doesn't like. Be sure to read the information and the restart options and enter the appropriate restart number - usually this is the one labelled <code>[ABORT]</code> but, depending on the situation, <code>[CONTINUE]</code> may also be useful.
111 52 Marcus Pearce
112 53 Marcus Pearce
h2. Reinstalling IDyOM
113 47 Marcus Pearce
114 1 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.
115 47 Marcus Pearce
116 52 Marcus Pearce
h2. Using different SQL database systems
117 47 Marcus Pearce
118 47 Marcus Pearce
You may use different kinds of databases. For example, to create an SQLite database called 'example.db' in directory <code>DIR</code>:
119 47 Marcus Pearce
120 44 Marcus Pearce
<pre>
121 44 Marcus Pearce
(clsql:connect '("DIR/example.db") :if-exists :old :database-type :sqlite3)
122 44 Marcus Pearce
</pre>
123 47 Marcus Pearce
124 44 Marcus Pearce
Alternatively, to connect to an existing local MySQL database:
125 47 Marcus Pearce
126 44 Marcus Pearce
<pre>
127 44 Marcus Pearce
(clsql:connect '("localhost" "example-database" "username" "password") :if-exists :old :database-type :mysql)
128 44 Marcus Pearce
</pre>
129 47 Marcus Pearce
130 44 Marcus Pearce
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.
131 44 Marcus Pearce
132 47 Marcus Pearce
h2. Problems loading foreign database libraries:
133 44 Marcus Pearce
134 44 Marcus Pearce
Depending on how your system is configured, <code>clsql:connect</code> may give a "Couldn't load foreign libraries" error.  In this case, you
135 44 Marcus Pearce
need to "tell CLSQL where it can find these libraries":http://clsql.b9.com/manual/appendix.html#foreignlibs, e.g.
136 47 Marcus Pearce
137 44 Marcus Pearce
<pre>
138 1 Marcus Pearce
(clsql:push-library-path "/usr/local/mysql/lib/")
139 1 Marcus Pearce
</pre>
140 1 Marcus Pearce
141 47 Marcus Pearce
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.