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.

Include directory rearrangement
f5944af8 · Peter Eisentraut · 3fcea502 · f5944af8 · f5944af8 · f5944af8
Commit f5944af8 authored 23 years ago by Peter Eisentraut
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
-<!-- $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>

--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
 <!--
-$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 &lt;libpq-fe&gt;
+</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>


--- a/doc/src/sgml/ref/pg_config-ref.sgml
+++ b/doc/src/sgml/ref/pg_config-ref.sgml
-<!-- $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>
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
 <!--
-$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>


--- a/src/Makefile.global.in
+++ b/src/Makefile.global.in
 # -*-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@


--- a/src/bin/pg_config/Makefile
+++ b/src/bin/pg_config/Makefile
-# $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' \

--- 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";;


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

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