<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
          "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"[
<!ENTITY LIBGDA          "<application>Libgda</application>">
<!ENTITY GNOMEDB         "<acronym>Gnome-Db</acronym>">
<!ENTITY RPM             "<acronym>RPM</acronym>">
]>
<chapter id="installation">
  <title>Installation</title>
  <sect1 id="installation-introduction">
    <title>Getting the library</title>
    <para>
      The &LIBGDA; library is bundled with some Linux distributions, so for these distributions, installing
      can be done using the distribution specific tools.
    </para>
    <para>
      Also &LIBGDA;'s sources are available for download from the 
      <ulink url="http://ftp.gnome.org/pub/GNOME/sources/libgda/">GNOME ftp servers</ulink>, and from
      the GNOME SVN repositories; see the <ulink url="http://www.gnome-db.org">Gnome-DB web site</ulink> for
      more information.
    </para>
  </sect1>
  <sect1 id="installation-installing">
    <title>Installing from the sources</title>
    <para>
      If you downloaded the source code (in a tarball), you must
      compile the software. To do so, once you have unpacked
      the source tree, you must:
      <programlisting>
<prompt>$ </prompt>./configure
<prompt>$ </prompt>make
<prompt>$ </prompt>make install
      </programlisting>
    </para>
    <para>
      This will generate the makefiles for your specific platform,
      compile all the source tree, and install the binaries and
      documentation in your system. This method works in the following environments:
      <itemizedlist mark="bullet">
	<listitem><para>On Linux (or other Unix systems, including MacOSX)</para></listitem>
	<listitem><para>On linux using the MinGW compiler in a cross compilation environment to generate Windows binaries</para></listitem>
	<listitem><para>On Windows using the MinGW compiler</para></listitem>
      </itemizedlist>
    </para>
    <para>
      If you don't find a file named <filename>configure</filename>, usually because you use
      non packaged sources which come from a Git repository, then
      execute the <filename>autogen.sh</filename> script which will create and run the
      generated <filename>configure</filename> file (please not that for this script to work,
      you'll need to have the autotools components installed on your system).
    </para>
    <para>
      You can specify several arguments to <filename>configure</filename> (or
      <filename>autogen.sh</filename>). You can
      check all the available arguments by running
      <command>configure --help</command>, but the most significant ones are:
    </para>
    <itemizedlist mark="bullet">
      <listitem>
        <para>
          <userinput>--prefix=&lt;directory&gt;</userinput>: Prefix where
          package will be installed
        </para>
      </listitem>
      <listitem>
        <para>
          <userinput>--enable-gtk-doc</userinput>: Specify that the library's documentation
	  must be built (using the gtk-doc program)
        </para>
      </listitem>
      <listitem>
        <para>
          <userinput>--enable-warnings</userinput>: Specify compilation warnings, to choose from:
	  min, max, fatal or no.
        </para>
      </listitem>
      <listitem>
        <para>
          <userinput>--with-&lt;provider name&gt;=[yes/no/&lt;directory&gt;]</userinput>: Specify, for
	  each supported database type (bdb, mysql, postgres, oracle, java, mdb) if the corresponding
	  provider is resquired ("yes"), should not be built ("no"), or can be built if its development
	  files can be detected by the configure script (you can specify a directory to look into if these
	  files are installed in a non standard location, for example
	  <userinput>--with-oracle=/local/BASES/OCI32</userinput>).
        </para>
      </listitem>
      <listitem>
        <para>
          <userinput>--enable-system-sqlite</userinput>: Specify that the SQLite installed with the
	  system must be used instead of the embedded version.
        </para>
      </listitem>
      <listitem>
        <para>
          <userinput>--with-ui</userinput>: Require that the UI extension (using GTK+) be built. This
	  also enables building the graphical tools such as the control center and GdaBrowser.
        </para>
      </listitem>
    </itemizedlist>
    <para>
      Libraries needed by providers are searched by default, so, if found, providers are
      compiled by default. Those libraries are searched in hard-coded directories, so
      if the installation of these libraries is in an uncommon place, the above arguments
      should be used to specify the directories where the libraries and header files
      are installed. Note that the SQLite provider is now always built using the sources
      of the SQLite library that are bundled within &LIBGDA;'s sources.
    </para>
    <para>
      If you find any problem during the configuration, compilation or
      installation process, do not hesitate in contacting the
      &GNOMEDB; mailing list (<email>gnome-db-list@gnome.org</email>, first
      send an email to <email>gnome-db-list-request@gnome.org</email> with 
      the subject SUBSCRIBE, if you are not already subscribed).
    </para>
  </sect1>
  <sect1 id="compiling">
    <title>Compiling your code using the &LIBGDA; library</title>
    <para>
      To compile you will need to set the C flags and to link the library, so we recommend
      to use the <command>pkg-config</command> command.
    </para>
    <programlisting>
<systemitem class="prompt">$ </systemitem>gcc -c full_example.c `pkg-config --cflags libgda-5.0`
<systemitem class="prompt">$ </systemitem>gcc -o full_example `pkg-config --libs libgda-5.0` full_example.o
    </programlisting>
    <para>
      or more simply:
      <programlisting>
<systemitem class="prompt">$ </systemitem>gcc -o full_example `pkg-config --cflags --libs libgda-4.0` full_example.c
    </programlisting>
    </para>
    <para>
      Doing this will add to the C compiler command line all needed header files
      and library directories as well as all needed libraries for linking your GDA
      application. To include header files, you can use <filename>libgda/libgda.h</filename>
      (more headers may be needed depending on some features, and are included in the documentation).
    </para>
  </sect1>
  <sect1 id="installation-configuring">
    <title>Configuring</title>
    <para>
      Depending on the use you're going to get out of &LIBGDA;, you may have
      to dig deep into its internals, but don't be afraid, things have been
      implemented to be easy to use.
    </para>
    <sect2 id="installation-development">
      <title>Configuration for development</title>
      <para>
        If you want to develop applications using &LIBGDA;, you should 
        install the libgda-dev[el] package if you do a &RPM; or <link linkend="installation-debian">Debian-based</link>
        installation. If you compiled the source code, development files are
        installed in your system.
      </para>
      <para>
        The only step you need to do to make sure everything is well 
        installed, is to check that &LIBGDA; libraries and binaries are seen
        by your system. That is, make sure that the &LIBGDA; 
        <filename class="directory">bin/</filename> directory is in your
        <envar>PATH</envar> environment variable, as well as the
        <filename class="directory">lib/</filename> in your 
        <envar>LD_LIBRARY_PATH</envar> (or 
        <filename>/etc/ld.so.conf</filename> file).
      </para>
      <para>
        Programs which need to use &LIBGDA;'s features need to include headers files, which are:
      </para>
      <programlisting>
#include &lt;libgda/libgda.h&gt;
#include &lt;sql-parser/gda-sql-parser.h&gt;
      </programlisting>
      and to use reports:
      <programlisting>
#include &lt;libgda/libgda.h&gt;
#include &lt;libgda-report/libgda-report.h&gt;
      </programlisting>
      and to use virtual connections:
      <programlisting>
#include &lt;libgda/libgda.h&gt;
#include &lt;virtual/libgda-virtual.h&gt;
      </programlisting>
    </sect2>


    <sect2 id="installation-client">
      <title>Configuration for accessing a database</title>
      <para>
	To access a database, it must have a database provider (if &LIBGDA; does not
	support the type of database to access, make a bug report in 
	<ulink url="http://bugzilla.gnome.org/">bugzilla</ulink>), and that database provider
	must be compiled an installed: the <command>gda-list-config-5.0</command> or 
	<command>gda-sql-5.0 -L</command> commands will
	show a list of the installed and configured database providers.
      </para>
      <para>
	Any connection to a database can be done either using a pre-defined data source, or using a
	connection string: using a data source (DSN) allows one to <emphasis>name</emphasis> connections
	and define them once, whereas using connection strings allows programs to be more
	independent of any &LIBGDA; configuration. Anyway, defining a DSN involves defining the same
	parameters as for a connection string.
      </para>
      <para>
	A connection string is a semi-colon delimited list of named parameters 
	(as <![CDATA[<param1_name>=<param1_value>;<param2_name>=<param2_value>...]]>), the parameters
	being specific to each database provider (the two commands mentioned above also list all the
	parameters for each provider).
      </para>
      <para>
	DSNs can be configured on a per-user basis or on a system-wide basis. Each user's
	own DSN definitions are stored in the <filename>$HOME/.local/share/libgda/config</filename> file
	(which
	is created the first time &LIBGDA; is used within an application. System wide DSN are defined in the
	<filename>&lt;prefix&gt;/etc/libgda/config</filename>. Rather than editing that
	file manually, it is possible to use the <command>gda-control-center-5.0</command> tool
	(part of &LIBGDA;).
	Note: if the <filename>$HOME/.libgda/config</filename> already exists from a previous use
	of &LIBGDA;, then that file is used instead of
	<filename>$HOME/.local/share/libgda/config</filename>.
      </para>
    </sect2>

    <sect2 id="installation-provider">
      <title>Provider's specific information</title>
      <para>
        This section provides information specific to each of the available
        &LIBGDA; providers.
      </para>
      <sect3 id="installation-provider-default">
	<title>SQLite provider</title>
	<para>
	  The SQLite provider is always installed (it is required by &LIBGDA;'s internally)
          with &LIBGDA;, which means that a default database system is always available. 
	  Specifically the first time you use
	  &LIBGDA;, a test database is copied into <filename>$HOME/.local/share/libgda/config</filename>
	  (or <filename>$HOME/.libgda</filename> if it exists and <filename>$HOME/.local/share/libgda/config</filename>
	  does not)
	  named "SalesTest". 
	</para>
      </sect3>
      <sect3 id="installation-provider-all">
	<title>Connection information for each database provider</title>
	<para>
	  Each provider exports a list of the arguments it requires in 
	  its connection string which is used internally by &LIBGDA; to
	  establish each connection. To obtain the required information to open a connection
	  using a provider, use the <link linkend="gda-sql">Gda SQL console tool</link> with the
	  <userinput>-L &lt;provider name&gt;</userinput> option. For example for PostgreSQL (strings truncated
	  for better readability):
	  <programlisting>
<systemitem class="prompt">$ </systemitem>gda-sql -L PostgreSQL
                   Provider 'PostgreSQL' description
Attribute      | Value                                                   
---------------+-------------------------------------------------------------
Provider       | PostgreSQL                                              
Description    | Provider for PostgreSQL databases                       
DSN parameters | DB_NAME: The name of a database to connect to (string),     
                 SEARCHPATH: Search path among database's schemas ('search_path' variable) (string),
                 HOST: Host on which the database server is running (for servers running on unix domain sockets, enter the socket's path (usually /tmp), or leave this field empty).
                 PORT: Database server port (for servers running on unix domain sockets, enter the socket's file name extension (usually 5432), or leave this field empty).
                 OPTIONS: Extra connection options (string),                 
                 USE_SSL: Whether or not to use SSL to establish the connection (boolean),
Authentication | USERNAME (string),                                                         
                 PASSWORD (string)
File           | /local/lib/libgda-4.0/providers/libgda-postgres.so
(5 rows)
	  </programlisting>
	</para>
      </sect3>
    </sect2>
  </sect1>
</chapter>