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 have
  20 been to port the &ffi; to &uffi;, add to Allegro's ODBC interface as a
  21 supported database, add a compatibility layer for &cmucl; specific
  22 code, and make the code more robust in terms of &mysql; support.
  23     </para>
  24   </sect1>
  25
  26   <sect1>
  27     <title>Prerequisites</title>
  28
  29     <sect2>
  30       <title>&defsystem;</title>
  31       <para> &clsql; uses &defsystem to compile and load its
  32 components.  &defsystem; is included in the <ulink
  33 url="http://clocc.sourceforge.net"><citetitle>&clocc;</citetitle></ulink>. The
  34 defsystem version in the pre-packaged distribution is rather old and
  35 may not function well. The version in CVS tree tree works quite
  36 well. For convenience, a copy of the latest defsystem at the FTP
  37 <ulink
  38 url="ftp://ftp.med-info.com/pub/defsystem/"><citetitle>site</citetitle></ulink>
  39 of &clsql;.
  40       </para>
  41     </sect2>
  42
  43     <sect2>
  44       <title>&uffi;</title>
  45       <para> &clsql; uses <ulink
  46 url="http://uffi.med-info.com/"><citetitle>&uffi;</citetitle></ulink>
  47 as a <emphasis>Foreign Function Interface</emphasis> (<glossterm
  48 linkend="gloss-ffi">FFI</glossterm>) to support multiple &cl;
  49 implementations.</para>
  50
  51 <para>You can download &uffi; from its FTP <ulink
  52 url="ftp://ftp.med-info.com/pub/uffi/"><citetitle>site</citetitle></ulink>. There
  53 are zip files for Microsoft Windows systems and gzipped tar files for
  54 other systems.</para>
  55     </sect2>
  56
  57     <sect2>
  58       <title>Supported Common Lisp Implementation</title>
  59       <para>
  60 The implementations that support &clsql; is governed by the supported
  61 implementations of &uffi;. At the time of the initial release of &clsql;,
  62 the following implementations are supported:
  63       </para>
  64       <itemizedlist mark="opencircle">
  65         <listitem><para>&acl; v6.1 on Redhat Linux 7.2 and Microsoft Windows.</para></listitem>
  66         <listitem><para>&lw; v4.2 on Redhat Linux 7.2 and Microsoft Windows.</para></listitem>
  67         <listitem><para>&cmucl; 18d on Redhat Linux 7.2.</para></listitem>
  68       </itemizedlist>
  69     </sect2>
  70
  71     <sect2>
  72       <title>Supported &sql; Implementation</title>
  73       <para>
  74         Currently, &clsql; supports the following databases:
  75       </para>
  76       <itemizedlist mark="opencircle">
  77         <listitem><para>&mysql; v3.23.49 on Redhat Linux 7.2 and Microsoft Windows.</para></listitem>
  78         <listitem><para>&postgresql; v7.1 on Redhat Linux 7.2. Support for both direct API connections and TCP socket connections.</para></listitem>
  79         <listitem><para>Allegro's ODBC interface (&aodbc;) on Redhat Linux 7.2 and Microsoft Windows.</para></listitem>
  80       </itemizedlist>
  81     </sect2>
  82
  83   </sect1>
  84
  85   <sect1>
  86     <title>Installation</title>
  87
  88     <sect2>
  89       <title>Ensure &defsystem; is loaded</title>
  90       <para>
  91         Simply load the file <filename>defsystem.lisp</filename>.
  92 <computeroutput>
  93 (load "defsystem.lisp")
  94 </computeroutput>
  95       </para>
  96     </sect2>
  97
  98     <sect2>
  99       <title>Build <filename>clsql-mysql</filename> helper library</title>
 100       <para>&mysql; uses functions that require 64-bit integer
 101 parameters and return values. The &ffi; in most &clsql;
 102 implementations do not support 64-bit integers. Thus, a C helper
 103 library is required to break these 64-bit integers into two compatible
 104 32-bit integers.</para>
 105
 106 <para><filename>Makefile</filename>'s for Microsoft Windows and GNU/Solaris systems
 107 are supplied to build this library. In addition, the <type>DLL</type> and <type>LIB</type>
 108 files for Microsoft Windows are supplied with the distribution.</para>
 109
 110 <para>To build the library, first move to the directory
 111 <filename>interfaces/mysql</filename> directory. You may need to
 112 edit <filename>Makefile</filename> or <filename>Makefile.msvc</filename> to
 113 correctly specify the location of your &mysql; installation. On UNIX systems, use
 114 the command:
 115 <programlisting>make</programlisting>. On a Microsoft Windows system,
 116 use the command: <programlisting>nmake /f
 117 Makefile.msvc</programlisting>.</para>
 118     </sect2>
 119
 120     <sect2>
 121       <title>Load &uffi;</title>
 122       <para>
 123         Unpack the appropriate &uffi; version for your system which creates a directory
 124 for the &uffi; files. Add that directory to &defsystem; <varname>*central-registry*</varname>.
 125 You can do that by either pushing the pathname of the directory onto this variable, or
 126 use the new <function>add-registry-location</function> present in the newest versions of
 127 &defsystem;. The below example code assumes the &uffi; files reside in the
 128 <filename>/usr/local/src/lisp/uffi</filename> directory.
 129         <computeroutput>
 130         (mk:add-registry-location #P"/usr/local/src/lisp/uffi")
 131         (mk:load-system :uffi)
 132         </computeroutput>
 133       </para>
 134     </sect2>
 135
 136   </sect1>
 137
 138 </chapter>