1 <?xml version='1.0' ?> <!-- -*- DocBook -*- -->
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> package by Xanalys.</para>
21 <title>History</title>
23 &clsql; is written by Kevin M. Rosenberg and based substantially
24 on Pierre R. Mai's excellent &maisql; package. The main changes from &maisql;
28 <para>port from the &cmucl; FFI to &uffi;.</para>
31 <para>new &acl; ODBC interface back-end.</para>
34 <para>compatibility layer for &cmucl; specific code.</para>
37 <para>much improved robustness for the &mysql; back-end.</para>
40 <para>improved system loading.</para>
43 <para>improved packages and symbol export.</para>
46 <para>transaction support.</para>
53 <title>Prerequisites</title>
56 <title>&defsystem;</title>
57 <para> &clsql; uses &asdf; to compile and load its
58 components. &asdf; is included in the <ulink
59 url="http://cclan.sourceforge.net"><citetitle>&cclan;</citetitle></ulink> collection.
65 <para>&clsql; uses <ulink
66 url="http://uffi.med-info.com/"><citetitle>&uffi;</citetitle></ulink>
67 as a <emphasis>Foreign Function Interface</emphasis> (<glossterm
68 linkend="gloss-ffi">FFI</glossterm>) to support multiple &cl;
69 implementations.</para>
71 <para>You can download &uffi; from its FTP <ulink
72 url="ftp://ftp.med-info.com/pub/uffi/"><citetitle>site</citetitle></ulink>. There
73 are zip files for Microsoft Windows systems and gzipped tar files for
79 <para>&clsql;'s postgresql-socket interface uses Pierre Mai's
80 <ulink url="ftp://clsql.b9.com/">md5</ulink> module. If you plan to use
81 this interface please download the md5 module from ftp://clsql.b9.com </para>
83 <title>Supported Common Lisp Implementation</title>
85 The implementations that support &clsql; is governed by the supported
86 implementations of &uffi;. The following implementations are supported:
88 <itemizedlist mark="opencircle">
89 <listitem><para>&acl; v6.2 on Debian Linux, FreeBSD 4.5, and Microsoft Windows XP.</para></listitem>
90 <listitem><para>&lw; v4.2 on Debian Linux and Microsoft Windows XP.</para></listitem>
91 <listitem><para>&cmucl; 18d on Debian Linux, FreeBSD 4.5, and Solaris 2.8.</para></listitem>
92 <listitem><para>&sbcl; 0.7.14 on Debian Linux.</para></listitem>
93 <listitem><para>&scl; 1.1 on Debian Linux.</para></listitem>
94 <listitem><para>&openmcl; 0.13 on Debian Linux PowerPC.</para></listitem>
99 <title>Supported &sql; Implementation</title>
101 Currently, &clsql; supports the following databases:
103 <itemizedlist mark="opencircle">
104 <listitem><para>&mysql; v3.23.51.</para></listitem>
105 <listitem><para>&postgresql; v7.2 with both direct API and TCP socket connections.</para></listitem>
106 <listitem><para>Allegro's ODBC interface (&aodbc;) using iODBC ODBC manager.</para></listitem>
113 <title>Installation</title>
116 <title>Ensure &defsystem; is loaded</title>
118 Simply load the file <filename>defsystem.lisp</filename>.
120 (load "defsystem.lisp")
126 <title>Build &c; helper libraries</title>
127 <para>&clsql; uses functions that require 64-bit integer
128 parameters and return values. The &ffi; in most &clsql;
129 implementations do not support 64-bit integers. Thus, C helper
130 libraries are required to break these 64-bit integers into two compatible
131 32-bit integers.</para>
133 <para>Makefiles for Microsoft Windows and GNU/Solaris systems
134 are supplied to build the libraries. Since many Microsoft Windows
135 users don't have access to a compiler, the <type>DLL</type> and <type>LIB</type>
136 files for Microsoft Windows are supplied with the distribution.</para>
138 <para>To build the libraries on a GNU or Solaris, use the shell and
139 change to the root directory of &clsql;. You may need to edit the file
140 <filename>interfaces/mysql/Makefile</filename> to specify the location of your
141 MySQL installation. The default Makefiles are setup for shared library
142 linking on Linux. If you are using FreeBSD or Solaris, you will need
143 to change the linker setting as instructed in the Makefile.
144 Then, you can give the command
148 in the root directory of &clsql; to build the libraries
149 <filename>interfaces/mysql/clsql-mysql.so</filename> and
150 <filename>interfaces/clsql-uffi/clsql-uffi.so</filename>.
155 <title>Load &uffi;</title>
157 Unzip or untar the &uffi; distribution which creates a directory
158 for the &uffi; files. Add that directory to Defsystem's <varname>asdf:*central-registry*</varname>.
159 You can do that by pushing the pathname of the directory onto this variable.
160 The following example code assumes the &uffi; files reside in the
161 <filename>/usr/share/lisp/uffi/</filename> directory.
163 (push #P"/usr/share/lisp/uffi/" asdf:*central-registry*)
164 (asdf:oos 'asdf:load-op :uffi)
169 <title>Load &md5; module</title>
171 If you plan to use the clsql-postgresql-socket interface, you must load the md5 module.
172 Unzip or untar the cl-md5 distribution, which creates a directory for the cl-md5 files.
173 Add that directory to Defsystem's <varname>asdf:*central-registry*</varname>.
174 You can do that by pushing the pathname of the directory onto this variable.
175 The following example code assumes the cl-md5 files reside in the
176 <filename>/usr/share/lisp/cl-md5/</filename> directory.
178 (push #P"/usr/share/lisp/cl-md5/" asdf:*central-registry*)
179 (asdf:oos 'asdf:load-op :md5)
185 <title>Load &clsql; modules</title>
187 Unzip or untar the &clsql; distribution which creates a directory
188 for the &clsql; files. Add that directory to Defsystem's <varname>asdf:*central-registry*</varname>.
189 You can do that by pushing the pathname of the directory onto this variable.
190 The following example code assumes the &clsql; files reside in the
191 <filename>/usr/share/lisp/clsql/</filename> directory. You need to load, at a minimum,
192 the main <symbol>:clsql</symbol> system and at least one interface system.
194 (push #P"/usr/share/lisp/clsql/" asdf:*central-repository*)
195 (asdf:oos 'asdf:load-op :clsql-base) ; base clsql package
196 (asdf:oos 'asdf:load-op :clsql-mysql) ; MySQL interface
197 (asdf:oos 'asdf:load-op :clsql-postgresql) ; PostgreSQL interface
198 (asdf:oos 'asdf:load-op :clsql-postgresql-socket) ; Socket PGSQL interface
199 (asdf:oos 'asdf:load-op :clsql-aodbc) ; Allegro ODBC interface
200 (asdf:oos 'asdf:load-op :clsql) ; main clsql package
206 <title>Run test suite</title>
208 After loading &clsql;, you can execute the test program in
209 the directory <filename>./test-suite</filename>. The test file,
210 <filename>tester-clsql</filename>
211 has instructions for creating a <filename>test.config</filename>.
212 After creating that file, simple load the test file with Lisp
213 and the tests should automatically execute.