doc/intro.xml

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