doc/intro.sgml

   1 <!-- -*- DocBook -*- -->
   2
   3 <chapter>
   4   <title>Introduction</title>
   5
   6   <sect1>
   7     <title>Purpose</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>
  13   </sect1>
  14
  15   <sect1>
  16     <title>History</title>
  17     <para>
  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;
  20 are:
  21 <itemizedlist>
  22 <listitem>
  23 <para>port from the &cmucl; FFI to &uffi;.</para>
  24 </listitem>
  25 <listitem>
  26 <para>new &acl; ODBC interface back-end.</para>
  27 </listitem>
  28 <listitem>
  29 <para>compatibility layer for &cmucl; specific code.</para>
  30 </listitem>
  31 <listitem>
  32 <para>much improved robustness for the &mysql; back-end.</para>
  33 </listitem>
  34 <listitem>
  35 <para>improved system loading.</para>
  36 </listitem>
  37 <listitem>
  38 <para>improved packages and symbol export.</para>
  39 </listitem>
  40 <listitem>
  41 <para>transaction support.</para>
  42 </listitem>
  43 </itemizedlist>
  44     </para>
  45   </sect1>
  46
  47   <sect1>
  48     <title>Prerequisites</title>
  49
  50     <sect2>
  51       <title>&defsystem;</title>
  52       <para> &clsql; uses &asdf; to compile and load its
  53 components.  &asdf; is included in the <ulink
  54 url="http://cclan.sourceforge.net"><citetitle>&cclan;</citetitle></ulink> collection.
  55       </para>
  56     </sect2>
  57
  58     <sect2>
  59       <title>&uffi;</title>
  60       <para>&clsql; uses <ulink
  61 url="http://uffi.med-info.com/"><citetitle>&uffi;</citetitle></ulink>
  62 as a <emphasis>Foreign Function Interface</emphasis> (<glossterm
  63 linkend="gloss-ffi">FFI</glossterm>) to support multiple &cl;
  64 implementations.</para>
  65
  66 <para>You can download &uffi; from its FTP <ulink
  67 url="ftp://ftp.med-info.com/pub/uffi/"><citetitle>site</citetitle></ulink>. There
  68 are zip files for Microsoft Windows systems and gzipped tar files for
  69 other systems.</para>
  70     </sect2>
  71
  72     <sect2>
  73       <title>&md5;</title>
  74       <para>&clsql;'s postgresql-socket interface uses Pierre Mai's
  75        <ulink url="ftp://clsql.b9.com/">md5</ulink> module. If you plan to use
  76        this interface please download the md5 module from ftp://clsql.b9.com </para>
  77     <sect2>
  78       <title>Supported Common Lisp Implementation</title>
  79       <para>
  80 The implementations that support &clsql; is governed by the supported
  81 implementations of &uffi;. The following implementations are supported:
  82       </para>
  83       <itemizedlist mark="opencircle">
  84         <listitem><para>&acl; v6.2 on Debian Linux, FreeBSD 4.5, and Microsoft Windows XP.</para></listitem>
  85         <listitem><para>&lw; v4.2 on Debian Linux and Microsoft Windows XP.</para></listitem>
  86         <listitem><para>&cmucl; 18d on Debian Linux, FreeBSD 4.5, and Solaris 2.8.</para></listitem>
  87         <listitem><para>&sbcl; 0.7.14 on Debian Linux.</para></listitem>
  88         <listitem><para>&scl; 1.1 on Debian Linux.</para></listitem>
  89         <listitem><para>&openmcl; 0.13 on Debian Linux PowerPC.</para></listitem>
  90       </itemizedlist>
  91     </sect2>
  92
  93     <sect2>
  94       <title>Supported &sql; Implementation</title>
  95       <para>
  96         Currently, &clsql; supports the following databases:
  97       </para>
  98       <itemizedlist mark="opencircle">
  99         <listitem><para>&mysql; v3.23.51.</para></listitem>
 100         <listitem><para>&postgresql; v7.2 with both direct API and TCP socket connections.</para></listitem>
 101         <listitem><para>Allegro's ODBC interface (&aodbc;) using iODBC ODBC manager.</para></listitem>
 102       </itemizedlist>
 103     </sect2>
 104
 105   </sect1>
 106
 107   <sect1>
 108     <title>Installation</title>
 109
 110     <sect2>
 111       <title>Ensure &defsystem; is loaded</title>
 112       <para>
 113         Simply load the file <filename>defsystem.lisp</filename>.
 114         <programlisting>
 115 (load "defsystem.lisp")
 116         </programlisting>
 117       </para>
 118     </sect2>
 119
 120     <sect2>
 121       <title>Build &c; helper libraries</title>
 122       <para>&clsql; uses functions that require 64-bit integer
 123 parameters and return values. The &ffi; in most &clsql;
 124 implementations do not support 64-bit integers. Thus, C helper
 125 libraries are required to break these 64-bit integers into two compatible
 126 32-bit integers.</para>
 127
 128 <para>Makefiles for Microsoft Windows and GNU/Solaris systems
 129 are supplied to build the libraries. Since many Microsoft Windows
 130 users don't have access to a compiler, the <type>DLL</type> and <type>LIB</type>
 131 files for Microsoft Windows are supplied with the distribution.</para>
 132
 133 <para>To build the libraries on a GNU or Solaris, use the shell and
 134 change to the root directory of &clsql;. You may need to edit the file
 135 <filename>interfaces/mysql/Makefile</filename> to specify the location of your
 136 MySQL installation. The default Makefiles are setup for shared library
 137 linking on Linux. If you are using FreeBSD or Solaris, you will need
 138 to change the linker setting as instructed in the Makefile.
 139 Then, you can give the command
 140 <programlisting>
 141 make libs
 142 </programlisting>
 143 in the root directory of &clsql; to build the libraries
 144 <filename>interfaces/mysql/clsql-mysql.so</filename> and
 145 <filename>interfaces/clsql-uffi/clsql-uffi.so</filename>.
 146 </para>
 147       </sect2>
 148
 149     <sect2>
 150       <title>Load &uffi;</title>
 151       <para>
 152         Unzip or untar the &uffi; distribution which creates a directory
 153 for the &uffi; files. Add that directory to Defsystem's <varname>asdf:*central-registry*</varname>.
 154 You can do that by pushing the pathname of the directory onto this variable.
 155  The following example code assumes the &uffi; files reside in the
 156 <filename>/usr/share/lisp/uffi/</filename> directory.
 157         <programlisting>
 158 (push #P"/usr/share/lisp/uffi/" asdf:*central-registry*)
 159 (asdf:oos 'asdf:load-op :uffi)
 160         </programlisting>
 161       </para>
 162     </sect2>
 163    <sect2>
 164       <title>Load &md5; module</title>
 165       <para>
 166         If you plan to use the  clsql-postgresql-socket interface, you must load the md5 module.
 167         Unzip or untar the cl-md5 distribution, which creates a directory for the cl-md5 files.
 168         Add that directory to Defsystem's <varname>asdf:*central-registry*</varname>.
 169         You can do that by pushing the pathname of the directory onto this variable.
 170         The following example code assumes the cl-md5 files reside in the
 171         <filename>/usr/share/lisp/cl-md5/</filename> directory.
 172         <programlisting>
 173 (push #P"/usr/share/lisp/cl-md5/" asdf:*central-registry*)
 174 (asdf:oos 'asdf:load-op :md5)
 175         </programlisting>
 176       </para>
 177     </sect2>
 178
 179     <sect2>
 180       <title>Load &clsql; modules</title>
 181       <para>
 182         Unzip or untar the &clsql; distribution which creates a directory
 183 for the &clsql; files. Add that directory to Defsystem's <varname>asdf:*central-registry*</varname>.
 184 You can do that by pushing the pathname of the directory onto this variable.
 185  The following example code assumes the &clsql; files reside in the
 186 <filename>/usr/share/lisp/clsql/</filename> directory. You need to load, at a minimum,
 187 the main <symbol>:clsql</symbol> system and at least one interface system.
 188         <programlisting>
 189 (push #P"/usr/share/lisp/clsql/" asdf:*central-repository*)
 190 (asdf:oos 'asdf:load-op :clsql-base)        ; base clsql package
 191 (asdf:oos 'asdf:load-op :clsql-mysql)       ; MySQL interface
 192 (asdf:oos 'asdf:load-op :clsql-postgresql)  ; PostgreSQL interface
 193 (asdf:oos 'asdf:load-op :clsql-postgresql-socket) ; Socket PGSQL interface
 194 (asdf:oos 'asdf:load-op :clsql-aodbc)       ; Allegro ODBC interface
 195 (asdf:oos 'asdf:load-op :clsql)             ; main clsql package
 196         </programlisting>
 197       </para>
 198     </sect2>
 199
 200     <sect2>
 201       <title>Run test suite</title>
 202       <para>
 203         After loading &clsql;, you can execute the test program in
 204 the directory <filename>./test-suite</filename>. The test file,
 205 <filename>tester-clsql</filename>
 206 has instructions for creating a <filename>test.config</filename>.
 207 After creating that file, simple load the test file with Lisp
 208 and the tests should automatically execute.
 209       </para>
 210     </sect2>
 211
 212   </sect1>
 213
 214 </chapter>