Welcome! (or "☡ Guile ∘ PostgreSQL ∞")
======================================

  Guile-PG is a collection of modules for Guile allowing access to
  the PostgreSQL RDBMS from Scheme programs.

  The low-level module ‘(database postgres)’ provides an almost
  one-to-one correspondence with the PostgreSQL "libpq" C library
  interface.  The other modules build on it to provide abstractions
  and convenience procedures:

    (database postgres-qcons)     -- Query Construction
    (database postgres-types)     -- Types Conversion
    (database postgres-col-defs)  -- Column Definitions
    (database postgres-resx)      -- Result Transforms
    (database postgres-table)     -- Single-Table Abstraction
    (database postgres-meta)      -- Introspection
    (database postgres-gxrepl)    -- Easy Interaction

  This is alpha code (pre 1.0 release), tested with various, but
  not all, versions of Guile and PostgreSQL.  It may have bugs,
  and the interfaces may change from version to version.

  To build Guile-PG you need to have installed both the PostgreSQL
  frontend library libpq, and a version of Guile that can either
  load binary module (a b c) from file a/b/c.so or a/b/c/libc.la
  under ‘%load-path’, or provide ‘dynamic-link’ and ‘dynamic-call’.

  In theory, this should work with Guile 1.4 and newer.  However,
  because of an API break in 2.2, it only works with 1.4.x, 1.8.x,
  and 2.0.x.


Building and Installing Guile-PG
================================

  Generic install instructions are provided in the file INSTALL.
  If you're in a hurry:

    ./configure [options]
    make
    make check
    make install
    make installcheck

  Each of the above steps is explained in detail below.


Configuration
-------------

  Normally, the configure script looks in $prefix/include and
  $prefix/lib for PostgreSQL headers and libraries, under the
  assumption that everything (Guile-PG, Guile and PostgreSQL)
  is to be installed there.

  It also attempts to use pkg-config, if available, to determine
  the ‘libpq’ package header (-I) and library (-L) dirs.  This is
  controlled by PKG_CONFIG* vars (see ‘configure --help’ output).

  If the ./configure script failed because it couldn't find
  libpq or the libpq headers then you can use the ‘PQ_CPPFLAGS’
  and ‘PQ_LDFLAGS’ vars to direct configure to the appropriate
  directory.  For example, if you installed PostgreSQL with the
  prefix $HOME/local, then you would invoke configure like so:

    ./configure                         \
      PQ_CPPFLAGS=-I$HOME/local/include \
      PQ_LDFLAGS=-L$HOME/local/lib

  If the configure script failed because it couldn't find
  guile-config, then make sure that script is on your path.

  If libguile is installed in a "non-standard" place, you may need
  to set the LDFLAGS environment variable to get configure to find
  it.  For example, if you use GCC with GNU ld and guile is
  installed under /opt/guile, then this can be achieved with the
  value: '-Wl,-rpath -Wl/opt/guile/lib' (quotes to protect spaces
  from the shell).

  If your platform needs "-R DIR" for the libpq link command, you
  can try the experimental configure option --enable-pq-rpath, or
  alternatively set the LDFLAGS env var as described above.

  For "make check" to work, you can specify to the configure script
  the initdb(1) program to use with option ‘INITDB=/path/to/initdb’.
  For example:

    ./configure INITDB=/usr/lib/postgresql/9.4/bin/initdb

  This saves the value of ‘INITDB’ so you don't need to specify it
  manually for each "make check" invocation (see "Testing", below).

  After configuration, type:

    make

  to build the libraries.


Testing
-------

  If configuration and "make" are successful, you can now run the
  tests.  To run the tests type:

    make check [options]

  Options are one or more of:
    VERBOSE=1
    DEBUG=1
    KEEPD=1
    INITDB=/path/to/initdb

  This creates a temporary installation dir test/fake-install/,
  creates a cluster test/fake-cluster/, creates one database in
  the cluster named ‘guile_pg_test’, kicks the daemon, runs the
  tests, and kills the daemon afterwards.

  Cluster creation uses initdb(1) to do the work.  If that program
  is not in ‘PATH’, and you did not specify it during configuration
  (see above), then you need to specify it.  (The remaining init
  uses pg_ctl(1) and psql(1) from the ‘PGPATH’ var output by
  ‘initdb --show’, so there is no need to specify those directly.)

  The basic tests should all pass.  The large-object tests might
  fail because of bugs in PostgreSQL.  The abstraction tests are
  not supposed to fail, but you never know.  If a test fails, the
  daemon might persist; to kill it "manually", use command:

    cd test/ && make kill-daemon [INITDB=/path/to/initdb]

  Alternatively, to ensure that the daemon never persists, you can:

    make check || ( cd test && make kill-daemon )

  Yet another alternative, much simpler:

    make -k check

  Normally, however, the last "test" arranges to kill the daemon;
  if you must resort to one of the above methods, that's a bug --
  please report it!

  Note that you may need to specify INITDB here, as well.
  In any case, the cluster persists, which reduces startup time
  for subsequent "make check" invocations (if you are in the mood).
  Use "make clean" to remove it and test/fake-install/ as well.

  Normally, "make check" shows only the status of the file-level
  tests.  To see more fine-grained status, specify ‘VERBOSE=1’.

  The DEBUG=1 is optional.  If "make check" fails, please re-run
  it with DEBUG=1 VERBOSE=1 and see "Reporting Bugs" below.

  Likewise, ‘KEEPD=1’ is optional.  If specified, the daemon is
  not killed, reducing startup time for subsequent runs.


What Goes Where
---------------

  If the basic tests passed then you may want to install Guile-PG.
  To do this type "make install", which puts files in these dirs:

    modules         -- ${GUILE_LIBSITE}/database
    guile-pg.info   -- ${infodir}

  The ${GUILE_LIBSITE} and ${infodir} values are determined by the
  configure script.  Typically, these would be, respectively,
  /usr/local/lib/guile/site and /usr/local/info.  Note that
  ${GUILE_LIBSITE} is based on the ${prefix} used for installing
  Guile, and may or may not coincide with the one specified by
  ‘configure --prefix’.

  Additionally, if the system supports it, "make install" updates
  each site dir's module catalog.

  Normally, "make install" deletes the superfluous .la file and any
  symlinks that "libtool install" created.  You can control this by
  specifying ‘SOFIXFLAGS’.  For example, to delete the .la file but
  leave the symlinks, you could do:

    make install SOFIXFLAGS=no-la

  See build-aux/guile-baux/sofix for more info.

  After installation, you may wish to "make installcheck", which
  is essentially "make check" modified to look for the modules in
  the install tree instead of the build tree.  Use ‘DEBUG=1’ and
  look for ";;; loading" lines to verify proper operation.


Reporting Bugs
==============

  See chapter Reporting Bugs in the manual.
  (info "(guile-pg) Reporting Bugs")
