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>Supported Common Lisp Implementation</title>
78 The implementations that support &clsql; is governed by the supported
79 implementations of &uffi;. The following implementations are supported:
81 <itemizedlist mark="opencircle">
82 <listitem><para>&acl; v6.1 on Redhat Linux 7.2, FreeBSD 4.5, and Microsoft Windows XP.</para></listitem>
83 <listitem><para>&lw; v4.2 on Redhat Linux 7.2 and Microsoft Windows XP.</para></listitem>
84 <listitem><para>&cmucl; 18d-pre on Redhat Linux 7.2, FreeBSD 4.5, and Solaris 2.8.</para></listitem>
89 <title>Supported &sql; Implementation</title>
91 Currently, &clsql; supports the following databases:
93 <itemizedlist mark="opencircle">
94 <listitem><para>&mysql; v3.23.49.</para></listitem>
95 <listitem><para>&postgresql; v7.2 with both direct API and TCP socket connections.</para></listitem>
96 <listitem><para>Allegro's ODBC interface (&aodbc;) using iODBC ODBC manager.</para></listitem>
103 <title>Installation</title>
106 <title>Ensure &defsystem; is loaded</title>
108 Simply load the file <filename>defsystem.lisp</filename>.
110 (load "defsystem.lisp")
116 <title>Build &c; helper libraries</title>
117 <para>&clsql; uses functions that require 64-bit integer
118 parameters and return values. The &ffi; in most &clsql;
119 implementations do not support 64-bit integers. Thus, C helper
120 libraries are required to break these 64-bit integers into two compatible
121 32-bit integers.</para>
123 <para>Makefiles for Microsoft Windows and GNU/Solaris systems
124 are supplied to build the libraries. Since many Microsoft Windows
125 users don't have access to a compiler, the <type>DLL</type> and <type>LIB</type>
126 files for Microsoft Windows are supplied with the distribution.</para>
128 <para>To build the libraries on a GNU or Solaris, use the shell and
129 change to the root directory of &clsql;. You may need to edit the file
130 <filename>interfaces/mysql/Makefile</filename> to specify the location of your
131 MySQL installation. The default Makefiles are setup for shared library
132 linking on Linux. If you are using FreeBSD or Solaris, you will need
133 to change the linker setting as instructed in the Makefile.
134 Then, you can give the command
138 in the root directory of &clsql; to build the libraries
139 <filename>interfaces/mysql/clsql-mysql.so</filename> and
140 <filename>interfaces/clsql-uffi/clsql-uffi.so</filename>.
145 <title>Load &uffi;</title>
147 Unzip or untar the &uffi; distribution which creates a directory
148 for the &uffi; files. Add that directory to Defsystem's <varname>mk:*central-registry*</varname>.
149 You can do that by either pushing the pathname of the directory onto this variable, or
150 use the new <function>add-registry-location</function> present in the newest versions of
151 &defsystem;. The following example code assumes the &uffi; files reside in the
152 <filename>/usr/local/src/lisp/uffi</filename> directory.
154 (mk:add-registry-location #P"/usr/local/src/lisp/uffi")
155 (mk:load-system :uffi)
161 <title>Load &clsql; modules</title>
163 Unzip or untar the &clsql; distribution which creates a directory
164 for the &clsql; files. Add that directory to Defsystem's <varname>mk:*central-registry*</varname>.
165 You can do that by either pushing the pathname of the directory onto this variable, or
166 use the new <function>add-registry-location</function> present in the newest versions of
167 &defsystem;. The following example code assumes the &clsql; files reside in the
168 <filename>/usr/local/src/lisp/clsql</filename> directory. You need to load, at a minimum,
169 the main <symbol>:clsql</symbol> system and at least one interface system.
171 (mk:add-registry-location #P"/usr/local/src/lisp/clsql")
172 (mk:load-system :clsql) ; main clsql package
173 (mk:load-system :clsql-mysql) ; MySQL interface
174 (mk:load-system :clsql-postgresql) ; PostgreSQL interface
175 (mk:load-system :clsql-postgresql-socket) ; Socket PGSQL interface
176 (mk:load-system :clsql-aodbc) ; Allegro ODBC interface
182 <title>Run test suite</title>
184 After loading &clsql;, you can execute the test program in
185 the directory <filename>./test-suite</filename>. The test file,
186 <filename>tester-clsql</filename>
187 has instructions for creating a <filename>test.config</filename>.
188 After creating that file, simple load the test file with Lisp
189 and the tests should automatically execute.