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.

4 files changed, 217 insertions, 27 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 &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>
 
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>