From f5944af8ba020b26741845c59682e6bd835beb07 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut <peter_e@gmx.net> Date: Tue, 28 Aug 2001 14:20:28 +0000 Subject: [PATCH] Include directory rearrangement Client headers are no longer in a subdirectory, since they have been made namespace-clean. Internal libpq headers are in a private subdirectory. Server headers are in a private subdirectory. pg_config has a new option to point there. --- doc/src/sgml/installation.sgml | 38 +++++---- doc/src/sgml/libpq.sgml | 125 +++++++++++++++++++++++++++- doc/src/sgml/ref/pg_config-ref.sgml | 62 +++++++++++++- doc/src/sgml/xfunc.sgml | 19 +++-- src/Makefile.global.in | 10 +-- src/bin/pg_config/Makefile | 3 +- src/bin/pg_config/pg_config.sh | 21 +++-- src/include/Makefile | 58 ++++++------- src/interfaces/libpq/Makefile | 24 ++---- 9 files changed, 270 insertions(+), 90 deletions(-) diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index 6588f5e552a..4a2d34fd238 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -1,4 +1,4 @@ -<!-- $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</>]]> @@ -448,19 +448,29 @@ su - postgres <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> diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index edda51533fe..f74f3c4944d 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1,5 +1,5 @@ <!-- -$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"> @@ -1994,6 +1994,129 @@ call <function>fe_setauthsvc</function> at all. </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> diff --git a/doc/src/sgml/ref/pg_config-ref.sgml b/doc/src/sgml/ref/pg_config-ref.sgml index 680418771c8..89fc04fbf7e 100644 --- a/doc/src/sgml/ref/pg_config-ref.sgml +++ b/doc/src/sgml/ref/pg_config-ref.sgml @@ -1,4 +1,4 @@ -<!-- $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> @@ -22,6 +22,7 @@ <group choice="req" rep="repeat"> <arg>--bindir</arg> <arg>--includedir</arg> + <arg>--includedir-server</arg> <arg>--libdir</arg> <arg>--configure</arg> <arg>--version</arg> @@ -32,12 +33,17 @@ <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: @@ -57,7 +63,17 @@ <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> @@ -99,4 +115,42 @@ 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> diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml index c06a3a5b33c..be5ab0dd38a 100644 --- a/doc/src/sgml/xfunc.sgml +++ b/doc/src/sgml/xfunc.sgml @@ -1,5 +1,5 @@ <!-- -$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"> @@ -1203,13 +1203,16 @@ LANGUAGE 'c'; <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> diff --git a/src/Makefile.global.in b/src/Makefile.global.in index 8055b4f0cf2..dc54dcd1e66 100644 --- a/src/Makefile.global.in +++ b/src/Makefile.global.in @@ -1,5 +1,5 @@ # -*-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, @@ -83,11 +83,9 @@ libdir := @libdir@ 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@ diff --git a/src/bin/pg_config/Makefile b/src/bin/pg_config/Makefile index d4dffd8b43e..0efaff5e352 100644 --- a/src/bin/pg_config/Makefile +++ b/src/bin/pg_config/Makefile @@ -1,4 +1,4 @@ -# $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 = ../../.. @@ -10,6 +10,7 @@ pg_config: pg_config.sh $(top_builddir)/config.status $(top_builddir)/src/Makefi 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' \ diff --git a/src/bin/pg_config/pg_config.sh b/src/bin/pg_config/pg_config.sh index 6576260f4f2..df05b92fee7 100644 --- a/src/bin/pg_config/pg_config.sh +++ b/src/bin/pg_config/pg_config.sh @@ -7,13 +7,14 @@ # 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@' @@ -21,15 +22,17 @@ 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>." @@ -49,6 +52,8 @@ do 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";; diff --git a/src/include/Makefile b/src/include/Makefile index a8aed3fdd70..e66c62f6eaf 100644 --- a/src/include/Makefile +++ b/src/include/Makefile @@ -6,7 +6,7 @@ # 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 $ # #------------------------------------------------------------------------- @@ -14,54 +14,48 @@ subdir = src/include 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 @@ -82,10 +76,12 @@ remove-old-headers: 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 diff --git a/src/interfaces/libpq/Makefile b/src/interfaces/libpq/Makefile index 2973799c37f..ce2bd7058f0 100644 --- a/src/interfaces/libpq/Makefile +++ b/src/interfaces/libpq/Makefile @@ -4,7 +4,7 @@ # # 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 $ # #------------------------------------------------------------------------- @@ -33,7 +33,7 @@ endif 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 @@ -70,27 +70,17 @@ wchar.c : % : $(backend_src)/utils/mb/% 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 -- GitLab