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 &defsystem to compile and load its
50 components. &defsystem; is included in the <ulink
51 url="http://clocc.sourceforge.net"><citetitle>&clocc;</citetitle></ulink> collection. The
52 version in the pre-packaged distribution is rather old and
53 may not function well. The version in CVS tree tree works quite
54 well. For convenience, a copy of the latest &defsystem; at the FTP
56 url="ftp://ftp.med-info.com/pub/defsystem/"><citetitle>site</citetitle></ulink>
63 <para>&clsql; uses <ulink
64 url="http://uffi.med-info.com/"><citetitle>&uffi;</citetitle></ulink>
65 as a <emphasis>Foreign Function Interface</emphasis> (<glossterm
66 linkend="gloss-ffi">FFI</glossterm>) to support multiple &cl;
67 implementations.</para>
69 <para>You can download &uffi; from its FTP <ulink
70 url="ftp://ftp.med-info.com/pub/uffi/"><citetitle>site</citetitle></ulink>. There
71 are zip files for Microsoft Windows systems and gzipped tar files for
76 <title>XPTest (optional)</title>
77 <para>The test suite for &clsql; uses the onShore Development's
78 XPTest package. onShore has graciously put the package in the public
79 domain. You can download the package from onShore's web <ulink
80 url="http://alpha.onshored.com/lisp-software/"><citetitle>site</citetitle></ulink>.
81 This package is not required except if you wish to run the &clsql;
86 <title>Supported Common Lisp Implementation</title>
88 The implementations that support &clsql; is governed by the supported
89 implementations of &uffi;. At the time of the initial release of &clsql;,
90 the following implementations are supported:
92 <itemizedlist mark="opencircle">
93 <listitem><para>&acl; v6.1 on Redhat Linux 7.2 and Microsoft Windows.</para></listitem>
94 <listitem><para>&lw; v4.2 on Redhat Linux 7.2 and Microsoft Windows.</para></listitem>
95 <listitem><para>&cmucl; 18d on Redhat Linux 7.2.</para></listitem>
100 <title>Supported &sql; Implementation</title>
102 Currently, &clsql; supports the following databases:
104 <itemizedlist mark="opencircle">
105 <listitem><para>&mysql; v3.23.49 on Redhat Linux 7.2 and Microsoft Windows.</para></listitem>
106 <listitem><para>&postgresql; v7.1 on Redhat Linux 7.2. Support for both direct API connections and TCP socket connections.</para></listitem>
107 <listitem><para>Allegro's ODBC interface (&aodbc;) on Redhat Linux 7.2 and Microsoft Windows.</para></listitem>
114 <title>Installation</title>
117 <title>Ensure &defsystem; is loaded</title>
119 Simply load the file <filename>defsystem.lisp</filename>.
121 (load "defsystem.lisp")
127 <title>Build &c; helper libraries</title>
128 <para>&clsql; uses functions that require 64-bit integer
129 parameters and return values. The &ffi; in most &clsql;
130 implementations do not support 64-bit integers. Thus, C helper
131 libraries are required to break these 64-bit integers into two compatible
132 32-bit integers.</para>
134 <para>Makefiles for Microsoft Windows and GNU/Solaris systems
135 are supplied to build the libraries. Since many Microsoft Windows
136 users don't have access to a compiler, the <type>DLL</type> and <type>LIB</type>
137 files for Microsoft Windows are supplied with the distribution.</para>
139 <para>To build the libraries on a GNU or Solaris, use the shell and
140 change to the root directory of &clsql;. You may need to edit the file
141 <filename>interfaces/mysql/Makefile</filename> to specify the location of your
142 MySQL installation. Then, you can give the command
146 in the root directory of &clsql; to build the libraries
147 <filename>interfaces/mysql/clsql-mysql.so</filename> and
148 <filename>interfaces/clsql-uffi/clsql-uffi.so</filename>.
153 <title>Load &uffi;</title>
155 Unzip or untar the &uffi; distribution which creates a directory
156 for the &uffi; files. Add that directory to Defsystem's <varname>mk:*central-registry*</varname>.
157 You can do that by either pushing the pathname of the directory onto this variable, or
158 use the new <function>add-registry-location</function> present in the newest versions of
159 &defsystem;. The following example code assumes the &uffi; files reside in the
160 <filename>/usr/local/src/lisp/uffi</filename> directory.
162 (mk:add-registry-location #P"/usr/local/src/lisp/uffi")
163 (mk:load-system :uffi)
169 <title>Load &clsql; modules</title>
171 Unzip or untar the &clsql; distribution which creates a directory
172 for the &clsql; files. Add that directory to Defsystem's <varname>mk:*central-registry*</varname>.
173 You can do that by either pushing the pathname of the directory onto this variable, or
174 use the new <function>add-registry-location</function> present in the newest versions of
175 &defsystem;. The following example code assumes the &clsql; files reside in the
176 <filename>/usr/local/src/lisp/clsql</filename> directory. You need to load, at a minimum,
177 the main <symbol>:clsql</symbol> system and at least one interface system.
179 (mk:add-registry-location #P"/usr/local/src/lisp/clsql")
180 (mk:load-system :clsql) ; main clsql package
181 (mk:load-system :clsql-mysql) ; MySQL interface
182 (mk:load-system :clsql-postgresql) ; PostgreSQL interface
183 (mk:load-system :clsql-postgresql-socket) ; Socket PGSQL interface
184 (mk:load-system :clsql-aodbc) ; Allegro ODBC interface