2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4 <!ENTITY % myents SYSTEM "entities.xml">
8 <chapter id="introduction">
9 <title>Introduction</title>
12 <title>Purpose</title>
13 <para>&clsql; is a Common Lisp interface to <glossterm
14 linkend="gloss-sql">SQL</glossterm> databases. A number of Common
15 Lisp implementations and SQL databases are supported. The general
16 structure of &clsql; is based on the
17 <application>CommonSQL</application>
23 <title>History</title>
25 &clsql; is written by Kevin M. Rosenberg and based substantially
26 on Pierre R. Mai's excellent &maisql; package. The main changes from &maisql;
30 <para>Optimized loading of integer and floating-point fields.</para>
33 <para>port from the &cmucl; FFI to &uffi;.</para>
36 <para>new &acl; ODBC interface back-end.</para>
39 <para>compatibility layer for &cmucl; specific code.</para>
42 <para>much improved robustness for the &mysql; back-end.</para>
45 <para>improved system loading.</para>
48 <para>improved packages and symbol export.</para>
51 <para>transaction support.</para>
57 <sect1 id="prerequisites">
58 <title>Prerequisites</title>
62 <para> &clsql; uses &asdf; to compile and load its
63 components. &asdf; is included in the <ulink
64 url="http://cclan.sourceforge.net"><citetitle>&cclan;</citetitle></ulink> collection.
70 <para>&clsql; uses <ulink
71 url="http://uffi.med-info.com/"><citetitle>&uffi;</citetitle></ulink>
72 as a <emphasis>Foreign Function Interface</emphasis> (<glossterm
73 linkend="gloss-ffi">FFI</glossterm>) to support multiple &cl;
77 <para>You can download &uffi; from its FTP <ulink
78 url="ftp://ftp.med-info.com/pub/uffi/"><citetitle>site</citetitle></ulink>. There
79 are zip files for Microsoft Windows systems and gzipped tar files for
86 <para>&clsql;'s postgresql-socket interface uses Pierre Mai's
87 <ulink url="ftp://clsql.b9.com/">md5</ulink>
88 module. If you plan to use
89 this interface please download the md5 module from ftp://clsql.b9.com.
93 <title>Supported Common Lisp Implementation</title>
95 The implementations that support &clsql; is governed by the supported
96 implementations of &uffi;. The following implementations are supported:
98 <itemizedlist mark="opencircle">
99 <listitem><para>&acl; v6.2 on Debian Linux, FreeBSD 4.5, and Microsoft Windows XP.</para></listitem>
100 <listitem><para>&lw; v4.3 on Debian Linux and Microsoft Windows XP.</para></listitem>
101 <listitem><para>&cmucl; 18e on Debian Linux, FreeBSD 4.5, and Solaris 2.8.</para></listitem>
102 <listitem><para>&sbcl; 0.8.5 on Debian Linux.</para></listitem>
103 <listitem><para>&scl; 1.2 on Debian Linux.</para></listitem>
104 <listitem><para>&openmcl; 0.14 on Debian Linux PowerPC.</para></listitem>
109 <title>Supported &sql; Implementation</title>
111 Currently, &clsql; supports the following databases:
113 <itemizedlist mark="opencircle">
114 <listitem><para>&mysql; v3.23.51.</para></listitem>
115 <listitem><para>&postgresql; v7.2 with both direct API and TCP socket connections.</para></listitem>
116 <listitem><para>Allegro's ODBC interface (&aodbc;) using iODBC ODBC manager.</para></listitem>
122 <sect1 id="installation">
123 <title>Installation</title>
126 <title>Ensure &asdf; is loaded</title>
128 Simply load the file <filename>asdf.lisp</filename>.
136 <title>Build &c; helper libraries</title>
137 <para>&clsql; uses functions that require 64-bit integer
138 parameters and return values. The &ffi; in most &clsql;
139 implementations do not support 64-bit integers. Thus, C helper
140 libraries are required to break these 64-bit integers into two compatible
144 <para>Makefiles for Microsoft Windows and GNU/Solaris systems
145 are supplied to build the libraries. Since many Microsoft Windows
146 users don't have access to a compiler, the <type>DLL</type> and <type>LIB</type>
147 files for Microsoft Windows are supplied with the distribution.
150 <para>To build the libraries on a GNU or Solaris, use the shell and
151 change to the root directory of &clsql;. You may need to edit the file
152 <filename>interfaces/mysql/Makefile</filename>
153 to specify the location of your
154 MySQL installation. The default Makefiles are setup for shared library
155 linking on Linux. If you are using FreeBSD or Solaris, you will need
156 to change the linker setting as instructed in the Makefile.
157 Then, you can give the command
161 in the root directory of &clsql; to build the libraries
162 <filename>interfaces/mysql/clsql-mysql.so</filename>
163 and <filename>interfaces/clsql-uffi/clsql-uffi.so</filename>.
168 <title>Load &uffi;</title>
170 Unzip or untar the &uffi; distribution which creates a directory
171 for the &uffi; files. Add that directory to &asdf;'s <varname>asdf:*central-registry*</varname>.
172 You can do that by pushing the pathname of the directory onto this variable.
173 The following example code assumes the &uffi; files reside in the
174 <filename>/usr/share/lisp/uffi/</filename>
177 (push #P"/usr/share/lisp/uffi/" asdf:*central-registry*)
178 (asdf:operate 'asdf:load-op :uffi)
183 <title>Load &md5; module</title>
185 If you plan to use the clsql-postgresql-socket interface, you must load the md5 module.
186 Unzip or untar the cl-md5 distribution, which creates a directory for the cl-md5 files.
187 Add that directory to &asdf;'s <varname>asdf:*central-registry*</varname>.
188 You can do that by pushing the pathname of the directory onto this variable.
189 The following example code assumes the cl-md5 files reside in the
190 <filename>/usr/share/lisp/cl-md5/</filename>
193 (push #P"/usr/share/lisp/cl-md5/" asdf:*central-registry*)
194 (asdf:operate 'asdf:load-op :md5)
200 <title>Load &clsql; modules</title>
202 Unzip or untar the &clsql; distribution which creates a directory
203 for the &clsql; files. Add that directory to &asdf;'s <varname>asdf:*central-registry*</varname>.
204 You can do that by pushing the pathname of the directory onto this variable.
205 The following example code assumes the &clsql; files reside in the
206 <filename>/usr/share/lisp/clsql/</filename>
207 directory. You need to load, at a minimum,
208 the main <symbol>:clsql</symbol> system and at least one interface system.
210 (push #P"/usr/share/lisp/clsql/" asdf:*central-repository*)
211 (asdf:operate 'asdf:load-op 'clsql-base) ; base clsql package
212 (asdf:operate 'asdf:load-op 'clsql-mysql) ; MySQL interface
213 (asdf:operate 'asdf:load-op 'clsql-postgresql) ; PostgreSQL interface
214 (asdf:operate 'asdf:load-op 'clsql-postgresql-socket) ; Socket PGSQL interface
215 (asdf:operate 'asdf:load-op 'clsql-aodbc) ; Allegro ODBC interface
216 (asdf:operate 'asdf:load-op 'clsql) ; main clsql package
222 <title>Run test suite</title>
224 After loading &clsql;, you can execute the test suite. A configuration
225 file named <filename>.clsql-test.config</filename> must be created
226 in your home directory. There are instructures on the format of that file
227 in the <filename>tests/tests.lisp</filename> file in the &clsql;
228 source directory. After creating that file, you can run the test suite
231 (asdf:operate 'asdf:test-op 'clsql)