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. The default Makefiles are setup for shared library
 143 linking on Linux. If you are using FreeBSD or Solaris, you will need
 144 to change the linker setting as instructed in the Makefile.
 145 Then, you can give the command
 146 <programlisting>
 147 make libs
 148 </programlisting>
 149 in the root directory of &clsql; to build the libraries
 150 <filename>interfaces/mysql/clsql-mysql.so</filename> and
 151 <filename>interfaces/clsql-uffi/clsql-uffi.so</filename>.
 152 </para>
 153       </sect2>
 154
 155     <sect2>
 156       <title>Load &uffi;</title>
 157       <para>
 158         Unzip or untar the &uffi; distribution which creates a directory
 159 for the &uffi; files. Add that directory to Defsystem's <varname>mk:*central-registry*</varname>.
 160 You can do that by either pushing the pathname of the directory onto this variable, or
 161 use the new <function>add-registry-location</function> present in the newest versions of
 162 &defsystem;. The following example code assumes the &uffi; files reside in the
 163 <filename>/usr/local/src/lisp/uffi</filename> directory.
 164         <programlisting>
 165 (mk:add-registry-location #P"/usr/local/src/lisp/uffi")
 166 (mk:load-system :uffi)
 167         </programlisting>
 168       </para>
 169     </sect2>
 170
 171     <sect2>
 172       <title>Load &clsql; modules</title>
 173       <para>
 174         Unzip or untar the &clsql; distribution which creates a directory
 175 for the &clsql; files. Add that directory to Defsystem's <varname>mk:*central-registry*</varname>.
 176 You can do that by either pushing the pathname of the directory onto this variable, or
 177 use the new <function>add-registry-location</function> present in the newest versions of
 178 &defsystem;. The following example code assumes the &clsql; files reside in the
 179 <filename>/usr/local/src/lisp/clsql</filename> directory. You need to load, at a minimum,
 180 the main <symbol>:clsql</symbol> system and at least one interface system.
 181         <programlisting>
 182 (mk:add-registry-location #P"/usr/local/src/lisp/clsql")
 183 (mk:load-system :clsql)              ; main clsql package
 184 (mk:load-system :clsql-mysql)       ; MySQL interface
 185 (mk:load-system :clsql-postgresql)  ; PostgreSQL interface
 186 (mk:load-system :clsql-postgresql-socket) ; Socket PGSQL interface
 187 (mk:load-system :clsql-aodbc)       ; Allegro ODBC interface
 188         </programlisting>
 189       </para>
 190     </sect2>
 191
 192   </sect1>
 193
 194 </chapter>