-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.50 2001/06/02 18:25:16 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.51 2001/08/28 14:20:24 petere Exp $ -->
<chapter id="installation">
<title><![%flattext-install-include[<productname>PostgreSQL</>]]>
<note>
<para>
- To reduce the pollution of shared installation locations (such
- as <filename>/usr/local/include</filename>), the string
- <quote><literal>/postgresql</literal></quote> is automatically
- appended to <varname>datadir</varname>,
- <varname>sysconfdir</varname>, <varname>includedir</varname>,
- and <varname>docdir</varname>, unless the fully expanded
- directory name already contains the string
- <quote>postgres</quote> or <quote>pgsql</quote>. For example,
- if you choose <filename>/usr/local</filename> as prefix, the C
- header files will be installed in
- <filename>/usr/local/include/postgresql</filename>, but if the
- prefix is <filename>/opt/postgres</filename>, then they will be
- in <filename>/opt/postgres/include</filename>.
+ Care has been taken to make it possible to install PostgreSQL
+ into shared installation locations (such as
+ <filename>/usr/local/include</filename>) without interfering
+ with the namespace of the rest of the system. First, the
+ string <quote><literal>/postgresql</literal></quote> is
+ automatically appended to <varname>datadir</varname>,
+ <varname>sysconfdir</varname>, and <varname>docdir</varname>,
+ unless the fully expanded directory name already contains the
+ string <quote>postgres</quote> or <quote>pgsql</quote>. For
+ example, if you choose <filename>/usr/local</filename> as
+ prefix, the documentation will be installed in
+ <filename>/usr/local/doc/postgresql</filename>, but if the
+ prefix is <filename>/opt/postgres</filename>, then it will be
+ in <filename>/opt/postgres/doc</filename>. Second, the
+ installation layout of the C and C++ header files has been
+ reorganized in the 7.2 release. The public header files of the
+ client interfaces are installed into
+ <varname>includedir</varname> and are namespace-clean. The
+ internal header files and the server header files are installed
+ into private directories under
+ <filename><replaceable>includedir</replaceable>/postgresql</filename>.
+ See the <citetitle>Programmer's Guide</citetitle> for
+ information how to get at the header files for each interface.
</para>
</note>
</para>
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.66 2001/08/10 22:50:09 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.67 2001/08/28 14:20:25 petere Exp $
-->
<chapter id="libpq">
</sect1>
+ <sect1 id="libpq-build">
+ <title>Building Libpq Programs</title>
+
+ <para>
+ To build (i.e., compile and link) your libpq programs you need to
+ do the following things:
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Include the <filename>libpq-fe.h</filename> header file:
+<programlisting>
+#include <libpq-fe>
+</programlisting>
+ If you failed to do that then you will normally get error
+ messages from your compiler, such as
+<screen>
+foo.c: In function `main':
+foo.c:34: `PGconn' undeclared (first use in this function)
+foo.c:35: `PGresult' undeclared (first use in this function)
+foo.c:54: `CONNECTION_BAD' undeclared (first use in this function)
+foo.c:68: `PGRES_COMMAND_OK' undeclared (first use in this function)
+foo.c:95: `PGRES_TUPLES_OK' undeclared (first use in this function)
+</screen>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Point your compiler to the directory where the PostgreSQL header
+ files were installed, by supplying the
+ <literal>-I<replaceable>directory</replaceable></literal> option
+ to your compiler. (In some cases the compiler will look into
+ the directory in question by default, so you can omit this
+ option.) For instance, your compile command line could look
+ like:
+<programlisting>
+cc -c -I/usr/local/pgsql/include testprog.c
+</programlisting>
+ If you are using makefiles then add the option to the
+ <varname>CPPFLAGS</varname> variable:
+<programlisting>
+CPPFLAGS += -I/usr/local/pgsql/include
+</programlisting>
+ </para>
+
+ <para>
+ If there is any chance that your program might be compiled by
+ other users then you should not hardcode the directory location
+ like that. Instead, you can run the utility
+ <command>pg_config</command> to find out where the header files
+ are on the local system:
+<screen>
+<prompt>$</prompt> pg_config --includedir
+<computeroutput>/usr/local/include</computeroutput>
+</screen>
+ </para>
+
+ <para>
+ Failure to specify the correct option to the compiler will
+ result in an error message such as
+<screen>
+testlibpq.c:8:22: libpq-fe.h: No such file or directory
+</screen>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ When linking the final program, specify the option
+ <literal>-lpq</literal> so that the libpq library gets pulled
+ in, as well as the option
+ <literal>-L<replaceable>directory</replaceable></literal> to
+ point it to the directory where libpq resides. (Again, the
+ compiler will search some directories by default.) For maximum
+ portability, put the <option>-L</option> option before the
+ <option>-lpq</option> option. For example:
+<programlisting>
+cc -o testprog testprog1.o testprog2.o -L/usr/local/pgsql/lib -lpq
+</programlisting>
+ </para>
+
+ <para>
+ You can find out the library directory using
+ <command>pg_config</command> as well:
+<screen>
+<prompt>$</prompt> pg_config --libdir
+<computeroutput>/usr/local/pgsql/lib</computeroutput>
+</screen>
+ </para>
+
+ <para>
+ Error messages that point to problems in this area could look
+ like the following.
+<screen>
+testlibpq.o: In function `main':
+testlibpq.o(.text+0x60): undefined reference to `PQsetdbLogin'
+testlibpq.o(.text+0x71): undefined reference to `PQstatus'
+testlibpq.o(.text+0xa4): undefined reference to `PQerrorMessage'
+</screen>
+ This means you forgot <option>-lpq</option>.
+<screen>
+/usr/bin/ld: cannot find -lpq
+</screen>
+ This means you forgot the <option>-L</option> or did not specify
+ the right path.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ If your codes references the header file
+ <filename>libpq-int.h</filename> and you refuse to fix your code to
+ not use it, starting in PostgreSQL 7.2, this file will be found in
+ <filename><replaceable>includedir</replaceable>/postgresql/internal/libpq-int.h</filename>,
+ so you need to add the appropriate <option>-I</option> option to
+ your compiler command line.
+ </para>
+
+ </sect1>
+
+
<sect1 id="libpq-example">
<title>Example Programs</title>
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_config-ref.sgml,v 1.5 2001/03/05 18:42:56 momjian Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/pg_config-ref.sgml,v 1.6 2001/08/28 14:20:26 petere Exp $ -->
<refentry id="app-pgconfig">
<docinfo>
<group choice="req" rep="repeat">
<arg>--bindir</arg>
<arg>--includedir</arg>
+ <arg>--includedir-server</arg>
<arg>--libdir</arg>
<arg>--configure</arg>
<arg>--version</arg>
<refsect1>
<title>Description</>
<para>
- The <application>pg_config</> utility provides configuration parameters
+ The <application>pg_config</> utility prints configuration parameters
of the currently installed version of <productname>PostgreSQL</>. It is
intended, for example, to be used by software packages that want to interface
- to <productname>PostgreSQL</> in order to find the respective header files
+ to <productname>PostgreSQL</> to facilitate finding the required header files
and libraries.
</para>
+ </refsect1>
+
+
+ <refsect1>
+ <title>Options</title>
<para>
To use <application>pg_config</>, supply one or more of the following options:
<term>--includedir</>
<listitem>
<para>
- Print the location of C and C++ header files.
+ Print the location of C and C++ header files of the client interfaces.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>--includedir-server</>
+ <listitem>
+ <para>
+ Print the location of C and C++ header files for server
+ programming.
</para>
</listitem>
</varlistentry>
information is printed in that order, one item per line.
</para>
</refsect1>
+
+
+ <refsect1>
+ <title>Notes</title>
+
+ <para>
+ The option <option>--includedir-server</option> is new in
+ PostgreSQL 7.2. In prior releases, the server include files were
+ installed in the same location as the client headers, which could
+ be queried with the <option>--includedir</option>. To make your
+ package handle both cases, try the newer option first and test the
+ exit status to see whether it succeeded.
+ </para>
+
+ <para>
+ In releases prior to PostgreSQL 7.1, before the
+ <command>pg_config</command> came to be, a method for finding the
+ equivalent configuration information did not exist.
+ </para>
+ </refsect1>
+
+
+ <refsect1>
+ <title>History</title>
+
+ <para>
+ The <command>pg_config</command> utility first appeared in PostgreSQL 7.1.
+ </para>
+ </refsect1>
+
+
+ <refsect1>
+ <title>See Also</title>
+
+ <para>
+ <citetitle>PostgreSQL Programmer's Guide</citetitle>
+ </para>
+ </refsect1>
</refentry>
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/xfunc.sgml,v 1.32 2001/05/19 09:01:10 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/xfunc.sgml,v 1.33 2001/08/28 14:20:26 petere Exp $
-->
<chapter id="xfunc">
<itemizedlist>
<listitem>
<para>
- The relevant header (include) files are installed under
- <filename>/usr/local/pgsql/include</filename> or equivalent.
- You can use <literal>pg_config --includedir</literal> to find
- out where it is on your system (or the system that your
- users will be running on). For very low-level work you might
- need to have a complete <productname>PostgreSQL</productname>
- source tree available.
+ Use <literal>pg_config --includedir-server</literal> to find
+ out where the PostgreSQL server header files are installed on
+ your system (or the system that your users will be running
+ on). This option is new with PostgreSQL 7.2. For PostgreSQL
+ 7.1 you should use the option <option>--includedir</option>.
+ (<command>pg_config</command> will exit with a non-zero status
+ if it encounters an unknown option.) For releases prior to
+ 7.1 you will have to guess, but since that was before the
+ current calling conventions were introduced, it is unlikely
+ that you want to support those releases.
</para>
</listitem>
# -*-makefile-*-
-# $Header: /cvsroot/pgsql/src/Makefile.global.in,v 1.134 2001/08/27 00:29:49 petere Exp $
+# $Header: /cvsroot/pgsql/src/Makefile.global.in,v 1.135 2001/08/28 14:20:26 petere Exp $
#------------------------------------------------------------------------------
# All PostgreSQL makefiles include this file and use the variables it sets,
pkglibdir = $(libdir)/postgresql
includedir := @includedir@
-ifeq "$(findstring pgsql, $(includedir))" ""
-ifeq "$(findstring postgres, $(includedir))" ""
-override includedir := $(includedir)/postgresql
-endif
-endif
+pkgincludedir = $(includedir)/postgresql
+includedir_server = $(pkgincludedir)/server
+includedir_internal = $(pkgincludedir)/internal
mandir := @mandir@
-# $Header: /cvsroot/pgsql/src/bin/pg_config/Makefile,v 1.1 2000/10/10 22:01:55 momjian Exp $
+# $Header: /cvsroot/pgsql/src/bin/pg_config/Makefile,v 1.2 2001/08/28 14:20:28 petere Exp $
subdir = src/bin/pg_config
top_builddir = ../../..
configure=`sed -n '7s,^# [^ ]*configure *,,p' $(top_builddir)/config.status` && \
sed -e 's,@bindir@,$(bindir),g' \
-e 's,@includedir@,$(includedir),g' \
+ -e 's,@includedir_server@,$(includedir_server),g' \
-e 's,@libdir@,$(libdir),g' \
-e "s,@configure@,$$configure,g" \
-e 's,@version@,$(VERSION),g' \
# Author: Peter Eisentraut <peter_e@gmx.net>
# Public domain
-# $Header: /cvsroot/pgsql/src/bin/pg_config/Attic/pg_config.sh,v 1.3 2001/05/13 00:12:05 petere Exp $
+# $Header: /cvsroot/pgsql/src/bin/pg_config/Attic/pg_config.sh,v 1.4 2001/08/28 14:20:28 petere Exp $
me=`basename $0`
# stored configuration values
val_bindir='@bindir@'
val_includedir='@includedir@'
+val_includedir_server='@includedir_server@'
val_libdir='@libdir@'
val_configure="@configure@"
val_version='@version@'
help="\
$me provides information about the installed version of PostgreSQL.
-Usage: $me --bindir | --includedir | --libdir | --configure | --version
+Usage: $me --bindir | --includedir | --includedir-server | --libdir | --configure | --version
Operation modes:
- --bindir show location of user executables
- --includedir show location of C header files
- --libdir show location of object code libraries
- --configure show options given to 'configure' script when
- PostgreSQL was built
- --version show PostgreSQL version and exit
+ --bindir show location of user executables
+ --includedir show location of C header files of the client
+ interfaces
+ --includedir-server show location of C header files for the server
+ --libdir show location of object code libraries
+ --configure show options given to 'configure' script when
+ PostgreSQL was built
+ --version show the PostgreSQL version and exit
Report bugs to <pgsql-bugs@postgresql.org>."
case $opt in
--bindir) show="$show \$val_bindir";;
--includedir) show="$show \$val_includedir";;
+ --includedir-server)
+ show="$show \$val_includedir_server";;
--libdir) show="$show \$val_libdir";;
--configure) show="$show \$val_configure";;
# programming. 'make install-all-headers' installs the whole contents
# of src/include.
#
-# $Header: /cvsroot/pgsql/src/include/Makefile,v 1.9 2001/08/24 14:07:49 petere Exp $
+# $Header: /cvsroot/pgsql/src/include/Makefile,v 1.10 2001/08/28 14:20:28 petere Exp $
#
#-------------------------------------------------------------------------
top_builddir = ../..
include $(top_builddir)/src/Makefile.global
-# Headers needed by clients
-srcdir_headers := c.h postgres_ext.h postgres_fe.h \
- libpq/pqcomm.h libpq/libpq-fs.h lib/dllist.h
-builddir_headers := pg_config_os.h pg_config.h
-
-HEADERS = $(srcdir_headers) $(builddir_headers)
-
-# Subdirectories containing headers that install-all-headers should install
-SUBDIRS = access bootstrap catalog commands executor lib libpq mb \
- nodes optimizer parser port regex rewrite storage tcop utils
-
-
-all: $(HEADERS)
+all: pg_config.h pg_config_os.h
# Install only selected headers
install: all installdirs remove-old-headers
- for file in $(srcdir_headers); do \
- $(INSTALL_DATA) $(srcdir)/$$file $(DESTDIR)$(includedir)/$$file || exit; \
- done
- for file in $(builddir_headers); do \
- $(INSTALL_DATA) $$file $(DESTDIR)$(includedir)/$$file || exit; \
- done
+# These headers are needed by the public headers of the interfaces.
+ $(INSTALL_DATA) $(srcdir)/postgres_ext.h $(DESTDIR)$(includedir)
+ $(INSTALL_DATA) $(srcdir)/libpq/libpq-fs.h $(DESTDIR)$(includedir)/libpq
+ $(INSTALL_DATA) pg_config.h $(DESTDIR)$(includedir)
+ $(INSTALL_DATA) pg_config_os.h $(DESTDIR)$(includedir)
+# These headers are needed by the not-so-public headers of the interfaces.
+ $(INSTALL_DATA) $(srcdir)/c.h $(DESTDIR)$(includedir_internal)
+ $(INSTALL_DATA) $(srcdir)/postgres_fe.h $(DESTDIR)$(includedir_internal)
+ $(INSTALL_DATA) $(srcdir)/libpq/pqcomm.h $(DESTDIR)$(includedir_internal)/libpq
+ $(INSTALL_DATA) $(srcdir)/lib/dllist.h $(DESTDIR)$(includedir_internal)/lib
-# Automatically pick out the needed subdirectories for the include tree.
installdirs:
- $(mkinstalldirs) $(addprefix $(DESTDIR)$(includedir)/, $(sort $(dir $(HEADERS))))
+ $(mkinstalldirs) $(DESTDIR)$(includedir)/libpq $(DESTDIR)$(includedir_internal)/libpq $(DESTDIR)$(includedir_internal)/lib
# Install all headers
+# Subdirectories containing headers that install-all-headers should install
+SUBDIRS = access bootstrap catalog commands executor lib libpq mb \
+ nodes optimizer parser port regex rewrite storage tcop utils
+
install-all-headers: all install-all-dirs
+ $(INSTALL_DATA) pg_config.h $(DESTDIR)$(includedir_server)
+ $(INSTALL_DATA) pg_config_os.h $(DESTDIR)$(includedir_server)
for file in $(srcdir)/*.h; do \
- $(INSTALL_DATA) $$file $(DESTDIR)$(includedir)/`basename $$file` || exit; \
+ $(INSTALL_DATA) $$file $(DESTDIR)$(includedir_server)/`basename $$file` || exit; \
done
for dir in $(SUBDIRS); do \
for file in $(srcdir)/$$dir/*.h; do \
- $(INSTALL_DATA) $$file $(DESTDIR)$(includedir)/$$dir/`basename $$file` || exit; \
+ $(INSTALL_DATA) $$file $(DESTDIR)$(includedir_server)/$$dir/`basename $$file` || exit; \
done \
done
- for file in $(builddir_headers); do \
- $(INSTALL_DATA) $$file $(DESTDIR)$(includedir)/$$file || exit; \
- done
install-all-dirs:
- $(mkinstalldirs) $(addprefix $(DESTDIR)$(includedir)/, $(SUBDIRS))
+ $(mkinstalldirs) $(addprefix $(DESTDIR)$(includedir_server)/, $(SUBDIRS))
# Pre-7.1 Postgres installed some headers that are no longer installed by
done
-# This isn't a complete uninstall, but rm'ing everything under
-# $(DESTDIR)$(includedir) is probably too drastic...
uninstall:
- rm -rf $(addprefix $(DESTDIR)$(includedir)/, $(HEADERS) $(SUBDIRS))
+ rm -f $(addprefix $(DESTDIR)$(includedir)/, pg_config.h pg_config_os.h postgres_ext.h libpq/libpq-fs.h)
+ rm -f $(addprefix $(DESTDIR)$(includedir_internal)/, c.h postgres_fe.h lib/dllist.h libpq/pqcomm.h)
+# heuristic...
+ rm -rf $(addprefix $(DESTDIR)$(includedir_server)/, $(SUBDIRS) *.h)
+
clean:
rm -f utils/fmgroids.h parser/parse.h
#
# Copyright (c) 1994, Regents of the University of California
#
-# $Header: /cvsroot/pgsql/src/interfaces/libpq/Makefile,v 1.55 2001/08/15 21:08:21 momjian Exp $
+# $Header: /cvsroot/pgsql/src/interfaces/libpq/Makefile,v 1.56 2001/08/28 14:20:28 petere Exp $
#
#-------------------------------------------------------------------------
SHLIB_LINK += $(filter -L%, $(LDFLAGS)) $(filter -lcrypt -ldes -lkrb -lcom_err -lcrypto -lk5crypto -lkrb5 -lssl -lsocket -lnsl -lresolv -lintl, $(LIBS))
-all: md5.c all-lib
+all: all-lib
# Shared library stuff
include $(top_srcdir)/src/Makefile.shlib
endif
-install: all installdirs install-headers install-lib
-
-.PHONY: install-headers
-install-headers: libpq-fe.h libpq-int.h pqexpbuffer.h
+install: all installdirs install-lib
$(INSTALL_DATA) $(srcdir)/libpq-fe.h $(DESTDIR)$(includedir)
- $(INSTALL_DATA) $(srcdir)/libpq-int.h $(DESTDIR)$(includedir)
- $(INSTALL_DATA) $(srcdir)/pqexpbuffer.h $(DESTDIR)$(includedir)
+ $(INSTALL_DATA) $(srcdir)/libpq-int.h $(DESTDIR)$(includedir_internal)
+ $(INSTALL_DATA) $(srcdir)/pqexpbuffer.h $(DESTDIR)$(includedir_internal)
installdirs:
- $(mkinstalldirs) $(DESTDIR)$(libdir) $(DESTDIR)$(includedir)
+ $(mkinstalldirs) $(DESTDIR)$(libdir) $(DESTDIR)$(includedir) $(DESTDIR)$(includedir_internal)
uninstall: uninstall-lib
- rm -f $(addprefix $(DESTDIR)$(includedir)/, libpq-fe.h libpq-int.h pqexpbuffer.h)
+ rm -f $(DESTDIR)$(includedir)/libpq-fe.h $(DESTDIR)$(includedir_internal)/libpq-int.h $(includedir_internal)/pqexpbuffer.h
clean distclean maintainer-clean: clean-lib
rm -f $(OBJS) dllist.c md5.c md5.h wchar.c
rm -f $(OBJS) inet_aton.c snprintf.c strerror.c
-
-depend dep:
- $(CC) -MM $(CFLAGS) *.c >depend
-
-ifeq (depend,$(wildcard depend))
-include depend
-endif