Parent Directories

Directory guile-pg

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-resdisp)   -- Displaying Results
	  (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 Guile 1.4.x and
	PostgreSQL 7.4, 8.0, 8.1, 8.2, 8.3.  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 load
	binary module (a b c) from file a/b/c.so or a/b/c/libc.la under
	`%load-path'.


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 destroy-nonmodule-guile-pg-prior-install
	  make install

	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.

	If the ./configure script failed because it couldn't find
	libpq or the libpq headers then you can use the --with-libpq
	option to direct configure to the appropriate directory.  E.g.,
	if you installed PostgreSQL with the prefix ~/local/ix86, so that
	the libpq headers are in ~/local/ix86/include and the library in
	~/local/ix86/lib then you would configure Guile-PG using a line
	like:

           ./configure --with-libpq=~/local/ix86

	If your libpq include directory is somewhere other than where
	the lib dorectory is then you can use the more specific switches
	--with-libpq-includes and --with-libpq-lib.  See the output of
	"./configure --help" for details.

	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.

	After configuration, type:

	    make

	to build the libraries.


Testing
-------

	If configuration and "make" are successful, you can now run the
	tests.  These need to be run as a user with permissions to
	create databases.  They also need permissions to write to the
	Guile-PG build directory.  You could do this by unpacking and
	building Guile-PG as the Postgres superuser, or by making
	yourself a user with permissions to create databases.  To do the
	latter use the PostgreSQL `createuser' command.

	The tests assume that the postmaster is either running on the
	local host or on the host pointed to by the PGHOST environment
	variable.

	The tests will destroy any existing database named
	"guile_pg_test", create it anew, and upon completion of the
	tests, destroy it again.  This means that the uid running
	the tests has to be a PostgreSQL user that additionally must
	be able to create databases.  If you should find the database
	hanging around afterwards for some reason, you can use the
	command:

	    dropdb guile_pg_test

	to get rid of it decisively.  To run the tests type:

            make check [DEBUG=1]

	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.

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


Removing Misguided Prior Installations
--------------------------------------

	(If this is the first time you're installing Guile-PG, you can
	skip this section.)

	Prior to 0.17, "make install" put these files in these dirs:

	   uncompiled modules -- ${datadir}/guile/database
	   compiled modules   -- ${libdir}/guile-pg/${VERSION}

	(See "What Goes Where" below for current installation practice.)

	There are three ways to delete these old files and directories:
	- Manually.
	- Using "make uninstall" in the old Guile-PG build tree.
	- Using "make destroy-nonmodule-guile-pg-prior-install".

	The last method is recommended because everything is automatic
	as well as convenient.  In addition to doing the deletions, if
	a module catalog is found in ${datadir}/guile, the relevant
	entries are also removed.


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.


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

	Please report bugs to Thien-Thi Nguyen.  Include Guile-PG
	version, the output of the show-platform script, and the log
	file of the test that failed (all in subdir "test").

	There is one known bug we can't do anything about (we tried but
	failed): The sourceforge folks don't want to update their site
	to point to the new Guile-PG homepage:

	    http://www.gnuvola.org/software/guile-pg/

	But if there are enough links to the new page, perhaps the
	relevancy of sourceforge's obstinance will decline over time.