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