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 </itemizedlist>
  41     </para>
  42   </sect1>
  43
  44   <sect1>
  45     <title>Prerequisites</title>
  46
  47     <sect2>
  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
  55 <ulink
  56 url="ftp://ftp.med-info.com/pub/defsystem/"><citetitle>site</citetitle></ulink>
  57 of &clsql;.
  58       </para>
  59     </sect2>
  60
  61     <sect2>
  62       <title>&uffi;</title>
  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>
  68
  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
  72 other systems.</para>
  73     </sect2>
  74
  75     <sect2>
  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;
  82 test suite.</para>
  83     </sect2>
  84
  85     <sect2>
  86       <title>Supported Common Lisp Implementation</title>
  87       <para>
  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:
  91       </para>
  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>
  96       </itemizedlist>
  97     </sect2>
  98
  99     <sect2>
 100       <title>Supported &sql; Implementation</title>
 101       <para>
 102         Currently, &clsql; supports the following databases:
 103       </para>
 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>
 108       </itemizedlist>
 109     </sect2>
 110
 111   </sect1>
 112
 113   <sect1>
 114     <title>Installation</title>
 115
 116     <sect2>
 117       <title>Ensure &defsystem; is loaded</title>
 118       <para>
 119         Simply load the file <filename>defsystem.lisp</filename>.
 120         <programlisting>
 121 (load "defsystem.lisp")
 122         </programlisting>
 123       </para>
 124     </sect2>
 125
 126     <sect2>
 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>
 133
 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>
 138
 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
 143 <programlisting>
 144 make libs
 145 </programlisting>
 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>.
 149 </para>
 150       </sect2>
 151
 152     <sect2>
 153       <title>Load &uffi;</title>
 154       <para>
 155         Unpack the appropriate &uffi; version for your system 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.
 161         <programlisting>
 162 (mk:add-registry-location #P"/usr/local/src/lisp/uffi")
 163 (mk:load-system :uffi)
 164         </programlisting>
 165       </para>
 166     </sect2>
 167
 168   </sect1>
 169
 170 </chapter>