+++ /dev/null
-<?xml version='1.0' ?> <!-- -*- DocBook -*- -->
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
-<!ENTITY % myents SYSTEM "entities.xml">
-%myents;
-]>
-
-<chapter id="introduction">
- <title>Introduction</title>
-
- <sect1>
- <title>Purpose</title>
- <para>&clsql; is a Common Lisp interface to <glossterm
-linkend="gloss-sql">SQL</glossterm> databases. A number of Common
-Lisp implementations and SQL databases are supported.The general
-structure of &clsql; is based on the
-<application>CommonSQL</application> package by Xanalys.</para>
- </sect1>
-
- <sect1>
- <title>History</title>
- <para>
- &clsql; is written by Kevin M. Rosenberg and based substantially
-on Pierre R. Mai's excellent &maisql; package. The main changes from &maisql;
-are:
-<itemizedlist>
-<listitem>
-<para>port from the &cmucl; FFI to &uffi;.</para>
-</listitem>
-<listitem>
-<para>new &acl; ODBC interface back-end.</para>
-</listitem>
-<listitem>
-<para>compatibility layer for &cmucl; specific code.</para>
-</listitem>
-<listitem>
-<para>much improved robustness for the &mysql; back-end.</para>
-</listitem>
-<listitem>
-<para>improved system loading.</para>
-</listitem>
-<listitem>
-<para>improved packages and symbol export.</para>
-</listitem>
-<listitem>
-<para>transaction support.</para>
-</listitem>
-</itemizedlist>
- </para>
- </sect1>
-
- <sect1>
- <title>Prerequisites</title>
-
- <sect2>
- <title>&defsystem;</title>
- <para> &clsql; uses &asdf; to compile and load its
-components. &asdf; is included in the <ulink
-url="http://cclan.sourceforge.net"><citetitle>&cclan;</citetitle></ulink> collection.
- </para>
- </sect2>
-
- <sect2>
- <title>&uffi;</title>
- <para>&clsql; uses <ulink
-url="http://uffi.med-info.com/"><citetitle>&uffi;</citetitle></ulink>
-as a <emphasis>Foreign Function Interface</emphasis> (<glossterm
-linkend="gloss-ffi">FFI</glossterm>) to support multiple &cl;
-implementations.</para>
-
-<para>You can download &uffi; from its FTP <ulink
-url="ftp://ftp.med-info.com/pub/uffi/"><citetitle>site</citetitle></ulink>. There
-are zip files for Microsoft Windows systems and gzipped tar files for
-other systems.</para>
- </sect2>
-
- <sect2>
- <title>&md5;</title>
- <para>&clsql;'s postgresql-socket interface uses Pierre Mai's
- <ulink url="ftp://clsql.b9.com/">md5</ulink> module. If you plan to use
- this interface please download the md5 module from ftp://clsql.b9.com </para>
- <sect2>
- <title>Supported Common Lisp Implementation</title>
- <para>
-The implementations that support &clsql; is governed by the supported
-implementations of &uffi;. The following implementations are supported:
- </para>
- <itemizedlist mark="opencircle">
- <listitem><para>&acl; v6.2 on Debian Linux, FreeBSD 4.5, and Microsoft Windows XP.</para></listitem>
- <listitem><para>&lw; v4.2 on Debian Linux and Microsoft Windows XP.</para></listitem>
- <listitem><para>&cmucl; 18d on Debian Linux, FreeBSD 4.5, and Solaris 2.8.</para></listitem>
- <listitem><para>&sbcl; 0.7.14 on Debian Linux.</para></listitem>
- <listitem><para>&scl; 1.1 on Debian Linux.</para></listitem>
- <listitem><para>&openmcl; 0.13 on Debian Linux PowerPC.</para></listitem>
- </itemizedlist>
- </sect2>
-
- <sect2>
- <title>Supported &sql; Implementation</title>
- <para>
- Currently, &clsql; supports the following databases:
- </para>
- <itemizedlist mark="opencircle">
- <listitem><para>&mysql; v3.23.51.</para></listitem>
- <listitem><para>&postgresql; v7.2 with both direct API and TCP socket connections.</para></listitem>
- <listitem><para>Allegro's ODBC interface (&aodbc;) using iODBC ODBC manager.</para></listitem>
- </itemizedlist>
- </sect2>
-
- </sect1>
-
- <sect1>
- <title>Installation</title>
-
- <sect2>
- <title>Ensure &defsystem; is loaded</title>
- <para>
- Simply load the file <filename>defsystem.lisp</filename>.
- <programlisting>
-(load "defsystem.lisp")
- </programlisting>
- </para>
- </sect2>
-
- <sect2>
- <title>Build &c; helper libraries</title>
- <para>&clsql; uses functions that require 64-bit integer
-parameters and return values. The &ffi; in most &clsql;
-implementations do not support 64-bit integers. Thus, C helper
-libraries are required to break these 64-bit integers into two compatible
-32-bit integers.</para>
-
-<para>Makefiles for Microsoft Windows and GNU/Solaris systems
-are supplied to build the libraries. Since many Microsoft Windows
-users don't have access to a compiler, the <type>DLL</type> and <type>LIB</type>
-files for Microsoft Windows are supplied with the distribution.</para>
-
-<para>To build the libraries on a GNU or Solaris, use the shell and
-change to the root directory of &clsql;. You may need to edit the file
-<filename>interfaces/mysql/Makefile</filename> to specify the location of your
-MySQL installation. The default Makefiles are setup for shared library
-linking on Linux. If you are using FreeBSD or Solaris, you will need
-to change the linker setting as instructed in the Makefile.
-Then, you can give the command
-<programlisting>
-make libs
-</programlisting>
-in the root directory of &clsql; to build the libraries
-<filename>interfaces/mysql/clsql-mysql.so</filename> and
-<filename>interfaces/clsql-uffi/clsql-uffi.so</filename>.
-</para>
- </sect2>
-
- <sect2>
- <title>Load &uffi;</title>
- <para>
- Unzip or untar the &uffi; distribution which creates a directory
-for the &uffi; files. Add that directory to Defsystem's <varname>asdf:*central-registry*</varname>.
-You can do that by pushing the pathname of the directory onto this variable.
- The following example code assumes the &uffi; files reside in the
-<filename>/usr/share/lisp/uffi/</filename> directory.
- <programlisting>
-(push #P"/usr/share/lisp/uffi/" asdf:*central-registry*)
-(asdf:oos 'asdf:load-op :uffi)
- </programlisting>
- </para>
- </sect2>
- <sect2>
- <title>Load &md5; module</title>
- <para>
- If you plan to use the clsql-postgresql-socket interface, you must load the md5 module.
- Unzip or untar the cl-md5 distribution, which creates a directory for the cl-md5 files.
- Add that directory to Defsystem's <varname>asdf:*central-registry*</varname>.
- You can do that by pushing the pathname of the directory onto this variable.
- The following example code assumes the cl-md5 files reside in the
- <filename>/usr/share/lisp/cl-md5/</filename> directory.
- <programlisting>
-(push #P"/usr/share/lisp/cl-md5/" asdf:*central-registry*)
-(asdf:oos 'asdf:load-op :md5)
- </programlisting>
- </para>
- </sect2>
-
- <sect2>
- <title>Load &clsql; modules</title>
- <para>
- Unzip or untar the &clsql; distribution which creates a directory
-for the &clsql; files. Add that directory to Defsystem's <varname>asdf:*central-registry*</varname>.
-You can do that by pushing the pathname of the directory onto this variable.
- The following example code assumes the &clsql; files reside in the
-<filename>/usr/share/lisp/clsql/</filename> directory. You need to load, at a minimum,
-the main <symbol>:clsql</symbol> system and at least one interface system.
- <programlisting>
-(push #P"/usr/share/lisp/clsql/" asdf:*central-repository*)
-(asdf:oos 'asdf:load-op :clsql-base) ; base clsql package
-(asdf:oos 'asdf:load-op :clsql-mysql) ; MySQL interface
-(asdf:oos 'asdf:load-op :clsql-postgresql) ; PostgreSQL interface
-(asdf:oos 'asdf:load-op :clsql-postgresql-socket) ; Socket PGSQL interface
-(asdf:oos 'asdf:load-op :clsql-aodbc) ; Allegro ODBC interface
-(asdf:oos 'asdf:load-op :clsql) ; main clsql package
- </programlisting>
- </para>
- </sect2>
-
- <sect2>
- <title>Run test suite</title>
- <para>
- After loading &clsql;, you can execute the test program in
-the directory <filename>./test-suite</filename>. The test file,
-<filename>tester-clsql</filename>
-has instructions for creating a <filename>test.config</filename>.
-After creating that file, simple load the test file with Lisp
-and the tests should automatically execute.
- </para>
- </sect2>
-
- </sect1>
-
-</chapter>
projects / clsql.git / blobdiff