1 <!-- -*- DocBook -*- -->
4 <title>Introduction</title>
8 <para>&clsql; is a Common Lisp interface to <glossterm
9 linkend="gloss-sql">SQL</glossterm> databases. A number of Common
10 Lisp implementations and SQL databases are supported.The general
11 structure of &clsql; is based on the
12 <application>CommonSQL</application> package by Xanalys.</para>
16 <title>History</title>
18 &clsql; is written by Kevin M. Rosenberg and based substantially
19 on Pierre R. Mai's excellent &maisql; package. The main changes from &maisql;
23 <para>port from the &cmucl; FFI to &uffi;.</para>
26 <para>new &acl; ODBC interface back-end.</para>
29 <para>compatibility layer for &cmucl; specific code.</para>
32 <para>much improved robustness for the &mysql; back-end.</para>
35 <para>improved system loading.</para>
38 <para>improved packages and symbol export.</para>
45 <title>Prerequisites</title>
48 <title>&defsystem;</title>
49 <para> &clsql; uses &asdf; to compile and load its
50 components. &asdf; is included in the <ulink
51 url="http://cclan.sourceforge.net"><citetitle>&cclan;</citetitle></ulink> collection.
57 <para>&clsql; uses <ulink
58 url="http://uffi.med-info.com/"><citetitle>&uffi;</citetitle></ulink>
59 as a <emphasis>Foreign Function Interface</emphasis> (<glossterm
60 linkend="gloss-ffi">FFI</glossterm>) to support multiple &cl;
61 implementations.</para>
63 <para>You can download &uffi; from its FTP <ulink
64 url="ftp://ftp.med-info.com/pub/uffi/"><citetitle>site</citetitle></ulink>. There
65 are zip files for Microsoft Windows systems and gzipped tar files for
70 <title>Supported Common Lisp Implementation</title>
72 The implementations that support &clsql; is governed by the supported
73 implementations of &uffi;. The following implementations are supported:
75 <itemizedlist mark="opencircle">
76 <listitem><para>&acl; v6.2 on Debian Linux, FreeBSD 4.5, and Microsoft Windows XP.</para></listitem>
77 <listitem><para>&lw; v4.2 on Debian Linux and Microsoft Windows XP.</para></listitem>
78 <listitem><para>&cmucl; 18d on Debian Linux, FreeBSD 4.5, and Solaris 2.8.</para></listitem>
79 <listitem><para>&sbcl; 0.7.8 on Debian Linux, FreeBSD 4.5, and Solaris 2.8.</para></listitem>
80 <listitem><para>&openmcl; 0.13 on Debian Linux.</para></listitem>
85 <title>Supported &sql; Implementation</title>
87 Currently, &clsql; supports the following databases:
89 <itemizedlist mark="opencircle">
90 <listitem><para>&mysql; v3.23.51.</para></listitem>
91 <listitem><para>&postgresql; v7.2 with both direct API and TCP socket connections.</para></listitem>
92 <listitem><para>Allegro's ODBC interface (&aodbc;) using iODBC ODBC manager.</para></listitem>
99 <title>Installation</title>
102 <title>Ensure &defsystem; is loaded</title>
104 Simply load the file <filename>defsystem.lisp</filename>.
106 (load "defsystem.lisp")
112 <title>Build &c; helper libraries</title>
113 <para>&clsql; uses functions that require 64-bit integer
114 parameters and return values. The &ffi; in most &clsql;
115 implementations do not support 64-bit integers. Thus, C helper
116 libraries are required to break these 64-bit integers into two compatible
117 32-bit integers.</para>
119 <para>Makefiles for Microsoft Windows and GNU/Solaris systems
120 are supplied to build the libraries. Since many Microsoft Windows
121 users don't have access to a compiler, the <type>DLL</type> and <type>LIB</type>
122 files for Microsoft Windows are supplied with the distribution.</para>
124 <para>To build the libraries on a GNU or Solaris, use the shell and
125 change to the root directory of &clsql;. You may need to edit the file
126 <filename>interfaces/mysql/Makefile</filename> to specify the location of your
127 MySQL installation. The default Makefiles are setup for shared library
128 linking on Linux. If you are using FreeBSD or Solaris, you will need
129 to change the linker setting as instructed in the Makefile.
130 Then, you can give the command
134 in the root directory of &clsql; to build the libraries
135 <filename>interfaces/mysql/clsql-mysql.so</filename> and
136 <filename>interfaces/clsql-uffi/clsql-uffi.so</filename>.
141 <title>Load &uffi;</title>
143 Unzip or untar the &uffi; distribution which creates a directory
144 for the &uffi; files. Add that directory to Defsystem's <varname>asdf:*central-registry*</varname>.
145 You can do that by pushing the pathname of the directory onto this variable.
146 The following example code assumes the &uffi; files reside in the
147 <filename>/usr/share/lisp/uffi/</filename> directory.
149 (push #P"/usr/share/lisp/uffi/" asdf:*central-repository*)
150 (asdf:oos 'asdf:load-op :uffi)
156 <title>Load &clsql; modules</title>
158 Unzip or untar the &clsql; distribution which creates a directory
159 for the &clsql; files. Add that directory to Defsystem's <varname>asdf:*central-registry*</varname>.
160 You can do that by pushing the pathname of the directory onto this variable.
161 The following example code assumes the &clsql; files reside in the
162 <filename>/usr/share/lisp/clsql/</filename> directory. You need to load, at a minimum,
163 the main <symbol>:clsql</symbol> system and at least one interface system.
165 (push #P"/usr/share/lisp/clsql/" asdf:*central-repository*)
166 (asdf:oos 'asdf:load-op :clsql-base) ; base clsql package
167 (asdf:oos 'asdf:load-op :clsql-mysql) ; MySQL interface
168 (asdf:oos 'asdf:load-op :clsql-postgresql) ; PostgreSQL interface
169 (asdf:oos 'asdf:load-op :clsql-postgresql-socket) ; Socket PGSQL interface
170 (asdf:oos 'asdf:load-op :clsql-aodbc) ; Allegro ODBC interface
171 (asdf:oos 'asdf:load-op :clsql) ; main clsql package
177 <title>Run test suite</title>
179 After loading &clsql;, you can execute the test program in
180 the directory <filename>./test-suite</filename>. The test file,
181 <filename>tester-clsql</filename>
182 has instructions for creating a <filename>test.config</filename>.
183 After creating that file, simple load the test file with Lisp
184 and the tests should automatically execute.