# Installation

## Getting the library

The &LIBGDA; library is bundled with some Linux distributions, so for these distributions, installing can be done using the distribution specific tools.

Also &LIBGDA;'s sources are available for download from the GNOME ftp servers, and from the GNOME SVN repositories; see the Gnome-DB web site for more information.

## Installing from the sources

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:

    $ ./configure
    $ make
    $ make install

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:

- On Linux (or other Unix systems, including MacOSX)

- On linux using the MinGW compiler in a cross compilation environment to generate Windows binaries

- On Windows using the MinGW compiler

If you don't find a file named `configure`, usually because you use non packaged sources which come from a Git repository, then execute the `autogen.sh` script which will create and run the generated `configure` file (please not that for this script to work, you'll need to have the autotools components installed on your system).

You can specify several arguments to `configure` (or `autogen.sh`). You can check all the available arguments by running `configure --help`, but the most significant ones are:

- `--prefix=<directory>`: Prefix where package will be installed

- `--enable-gtk-doc`: Specify that the library's documentation must be built (using the gtk-doc program)

- `--enable-warnings`: Specify compilation warnings, to choose from: min, max, fatal or no.

- `--with-<provider name>=[yes/no/<directory>]`: 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 `--with-oracle=/local/BASES/OCI32`).

- `--enable-system-sqlite`: Specify that the SQLite installed with the system must be used instead of the embedded version.

- `--with-ui`: Require that the UI extension (using GTK+) be built. This also enables building the graphical tools such as the control center and GdaBrowser.

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.

If you find any problem during the configuration, compilation or installation process, do not hesitate in contacting the &GNOMEDB; mailing list (gnome-db-list@gnome.org, first send an email to gnome-db-list-request@gnome.org with the subject SUBSCRIBE, if you are not already subscribed).

## Compiling your code using the &LIBGDA; library

To compile you will need to set the C flags and to link the library, so we recommend to use the `pkg-config` command.

    $ gcc -c full_example.c `pkg-config --cflags libgda-5.0`
    $ gcc -o full_example `pkg-config --libs libgda-5.0` full_example.o

or more simply:

    $ gcc -o full_example `pkg-config --cflags --libs libgda-4.0` full_example.c

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 `libgda/libgda.h` (more headers may be needed depending on some features, and are included in the documentation).

## Configuring

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.

### Configuration for development

If you want to develop applications using &LIBGDA;, you should install the libgda-dev[el] package if you do a &RPM; or Debian-based installation. If you compiled the source code, development files are installed in your system.

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; `bin/` directory is in your `PATH` environment variable, as well as the `lib/` in your `LD_LIBRARY_PATH` (or `/etc/ld.so.conf` file).

Programs which need to use &LIBGDA;'s features need to include headers files, which are:

    #include <libgda/libgda.h>
    #include <sql-parser/gda-sql-parser.h>

and to use reports:

    #include <libgda/libgda.h>
    #include <libgda-report/libgda-report.h>

and to use virtual connections:

    #include <libgda/libgda.h>
    #include <virtual/libgda-virtual.h>

### Configuration for accessing a database

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 bugzilla), and that database provider must be compiled an installed: the `gda-list-config-5.0` or `gda-sql-5.0 -L` commands will show a list of the installed and configured database providers.

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 name 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.

A connection string is a semi-colon delimited list of named parameters (as <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).

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 `$HOME/.local/share/libgda/config` file (which is created the first time &LIBGDA; is used within an application. System wide DSN are defined in the `<prefix>/etc/libgda/config`. Rather than editing that file manually, it is possible to use the `gda-control-center-5.0` tool (part of &LIBGDA;). Note: if the `$HOME/.libgda/config` already exists from a previous use of &LIBGDA;, then that file is used instead of `$HOME/.local/share/libgda/config`.

### Provider's specific information

This section provides information specific to each of the available &LIBGDA; providers.

#### SQLite provider

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 `$HOME/.local/share/libgda/config` (or `$HOME/.libgda` if it exists and `$HOME/.local/share/libgda/config` does not) named "SalesTest".

#### Connection information for each database provider

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 Gda SQL console tool with the `-L <provider name>` option. For example for PostgreSQL (strings truncated for better readability):

    $ 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)