# 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 GitLab repository. For additional information see the Gnome-DB web site.

## Installing from the sources

Starting from version 6.0, &LIBGDA; uses Meson build system. The following commands should work for most platforms:

    $ git clone https://gitlab.gnome.org/GNOME/libgda.git
    $ cd libgda
    $ meson build
    $ ninja -C build
    $ ninja -C build install

This will compile all the source tree, and install the binaries and documentation in your system. This method should work on all platforms where meson and ninja as well as all dependencies are available.

You can specify several arguments to `meson`. Some arguments are related to the meson system itself, while others are project specific. To get a full list of all meson specific options a one can type:

    $ meson help setup

All project specific options can be found in `meson_options.txt` file. In meson all parameters should be provided in the forms: -Dparameter=value

Option | Type | Default value | Description
--- | --- | --- | ---
with-help | boolean | true | Enable building help (GdaBrowser))
with-goocanvas | boolean | false | Enable GooCanvas
with-graphviz | boolean | false | Enable using Graphviz
with-json | boolean | true | Enable support for JSON
enable-gda-gi | boolean | false | Enable GObject Introspection for libgda
disable-sqlcipher | boolean | false | Disable SQLCipher database provider
with-libsoup | boolean | true | Enable libsoup support
with-libsecret | boolean | false | Enable libsecret support
with-gnome-keyring | boolean | false | Enable gnome-keyring support
enable-debug | boolean | false | Enable debug mode
with-examples | boolean | false | Compile examples
enable-tools | boolean | false | Enable build experimental GUI Tools
glade-catalog-dir | string | '' | Use the given directory to install glade catalog files. If glade is not available this option is ignored. If it is not given the valaue from pkg-config will be used
glade-pixmap-dir | string | '' | Use the given directory to install glade pixmap files. If glade is not available this option is ignored. If it is not given the valaue from pkg-config will be used
gtk_doc | boolean | false | Enable documentation generation
experimental | boolean | false | Enable experimental features
enable-ldap | boolean | false | Enable experimental LDAP provider
enable-web | boolean | false | Enable experimental WEB provider
enable-test-flatpak | boolean | false | Enable Terminal Test Application

The custom prefix for the installation can be provided during the configuration step:

    $ meson --prefix=/opt/GNOME/progs -Dgtk_doc=true

Please review all available options by running:

    $meson help setup

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-6.0`
    $ gcc -o full_example `pkg-config --libs libgda-6.0` full_example.o

or more simply:

    $ gcc -o full_example `pkg-config --cflags --libs libgda-6.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 GDA's issues tracker), and that database provider must be compiled an installed: the `gda-list-config-6.0` or `gda-sql-6.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-6.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".

#### JDBC based providers

Refer to the JDBC notes section for more information.

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