From 9598134e3030a883ff6eea8a822466ce5143ffeb Mon Sep 17 00:00:00 2001
From: Andrew Dunstan <andrew@dunslane.net>
Date: Sun, 6 Oct 2013 23:03:57 -0400
Subject: [PATCH] Document support for VPATH builds of extensions.
MIME-Version: 1.0
Content-Type: text/plain; charset=utf8
Content-Transfer-Encoding: 8bit
Cédric Villemain and me.
---
doc/src/sgml/extend.sgml | 29 ++++++++++++++++++++++++++++-
1 file changed, 28 insertions(+), 1 deletion(-)
diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml
index 60fa1a8922..5015002aac 100644
--- a/doc/src/sgml/extend.sgml
+++ b/doc/src/sgml/extend.sgml
@@ -935,7 +935,7 @@ include $(PGXS)
To use the <acronym>PGXS</acronym> infrastructure for your extension,
you must write a simple makefile.
In the makefile, you need to set some variables
- and finally include the global <acronym>PGXS</acronym> makefile.
+ and include the global <acronym>PGXS</acronym> makefile.
Here is an example that builds an extension module named
<literal>isbn_issn</literal>, consisting of a shared library containing
some C code, an extension control file, a SQL script, and a documentation
@@ -1171,6 +1171,33 @@ include $(PGXS)
</para>
</caution>
+ <para>
+ You can also run <literal>make</literal> in a directory outside the source
+ tree of your extension, if you want to keep the build directory separate.
+ This procedure is also called a
+ <indexterm><primary>VPATH</primary></indexterm><firstterm>VPATH</firstterm>
+ build. Here's how:
+ <screen>
+ <userinput>mkdir build_dir</userinput>
+ <userinput>cd build_dir</userinput>
+ <userinput>make -f /path/to/extension/source/tree/Makefile</userinput>
+ <userinput>make -f /path/to/extension/source/tree/Makefile install</userinput>
+ </screen>
+ </para>
+
+ <para>
+ Alternatively, you can set up a directory for a VPATH build in a similar
+ way to how it is done for the core code. One way to to this is using the
+ core script <filename>config/prep_buildtree</>. Once this has been done
+ you can build by setting the <literal>make</literal> variable
+ <varname>USE_VPATH</varname> like this:
+ <screen>
+ <userinput>make USE_VPATH=/path/to/extension/source/tree</userinput>
+ <userinput>make USE_VPATH=/path/to/extension/source/tree install</userinput>
+ </screen>
+ This procedure can work with a greater variety of directory layouts.
+ </para>
+
<para>
The scripts listed in the <varname>REGRESS</> variable are used for
regression testing of your module, which can be invoked by <literal>make
--
2.49.0