From f5944af8ba020b26741845c59682e6bd835beb07 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Tue, 28 Aug 2001 14:20:28 +0000 Subject: 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 +++--- 4 files changed, 217 insertions(+), 27 deletions(-) (limited to 'doc/src') 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 @@ - + <![%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 + + + To build (i.e., compile and link) your libpq programs you need to + do the following things: + + + + + Include the libpq-fe.h header file: + +#include <libpq-fe> + + If you failed to do that then you will normally get error + messages from your compiler, such as + +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) + + + + + + + Point your compiler to the directory where the PostgreSQL header + files were installed, by supplying the + -Idirectory 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: + +cc -c -I/usr/local/pgsql/include testprog.c + + If you are using makefiles then add the option to the + CPPFLAGS variable: + +CPPFLAGS += -I/usr/local/pgsql/include + + + + + 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 + pg_config to find out where the header files + are on the local system: + +$ pg_config --includedir +/usr/local/include + + + + + Failure to specify the correct option to the compiler will + result in an error message such as + +testlibpq.c:8:22: libpq-fe.h: No such file or directory + + + + + + + When linking the final program, specify the option + -lpq so that the libpq library gets pulled + in, as well as the option + -Ldirectory to + point it to the directory where libpq resides. (Again, the + compiler will search some directories by default.) For maximum + portability, put the option before the + option. For example: + +cc -o testprog testprog1.o testprog2.o -L/usr/local/pgsql/lib -lpq + + + + + You can find out the library directory using + pg_config as well: + +$ pg_config --libdir +/usr/local/pgsql/lib + + + + + Error messages that point to problems in this area could look + like the following. + +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' + + This means you forgot . + +/usr/bin/ld: cannot find -lpq + + This means you forgot the or did not specify + the right path. + + + + + + + If your codes references the header file + libpq-int.h and you refuse to fix your code to + not use it, starting in PostgreSQL 7.2, this file will be found in + includedir/postgresql/internal/libpq-int.h, + so you need to add the appropriate option to + your compiler command line. + + + + + Example Programs 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 @@ - + @@ -22,6 +22,7 @@ --bindir --includedir + --includedir-server --libdir --configure --version @@ -32,12 +33,17 @@ 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 To use pg_config, supply one or more of the following options: @@ -57,7 +63,17 @@ --includedir - Print the location of C and C++ header files. + Print the location of C and C++ header files of the client interfaces. + + + + + + --includedir-server + + + Print the location of C and C++ header files for server + programming. @@ -99,4 +115,42 @@ information is printed in that order, one item per line. + + + + Notes + + + The 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 . To make your + package handle both cases, try the newer option first and test the + exit status to see whether it succeeded. + + + + In releases prior to PostgreSQL 7.1, before the + pg_config came to be, a method for finding the + equivalent configuration information did not exist. + + + + + + History + + + The pg_config utility first appeared in PostgreSQL 7.1. + + + + + + See Also + + + PostgreSQL Programmer's Guide + + 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 @@ @@ -1203,13 +1203,16 @@ LANGUAGE 'c'; - The relevant header (include) files are installed under - /usr/local/pgsql/include or equivalent. - You can use pg_config --includedir 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 PostgreSQL - source tree available. + Use pg_config --includedir-server 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 . + (pg_config 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. -- cgit v1.2.3