doc: Document variables for path substitution in SQL tests

Test suites driven by pg_regress can use the following environment
variables for path substitutions since d1029bb5a26c:
- PG_ABS_SRCDIR
- PG_ABS_BUILDDIR
- PG_DLSUFFIX
- PG_LIBDIR

These variables have never been documented, and they can be useful for
out-of-core code based on the options used by the pg_regress command
invoked by installcheck (or equivalent) to build paths to libraries for
various commands, like LOAD or CREATE FUNCTION.

Reviewed-by: Zhang Hu <kongbaik228@gmail.com>
Reviewed-by: Chao Li <li.evan.chao@gmail.com>
Discussion: https://postgr.es/m/abDAWzHaesHLDFke@paquier.xyz

diff --git a/doc/src/sgml/regress.sgml b/doc/src/sgml/regress.sgml
index d80dd46c5fdb9477ce38f0f87105013abc58c99d..43f208df2724397cc6b561b22dddcced2130add6 100644 (file)
--- a/doc/src/sgml/regress.sgml
+++ b/doc/src/sgml/regress.sgml
@@ -444,6 +444,70 @@ make check LANG=C ENCODING=EUC_JP
    </para>
   </sect2>
 
+  <sect2 id="regress-run-path-substitution">
+   <title>Path Substitution</title>
+
+   <para>
+    The test suites driven by <command>pg_regress</command> can use the
+    following environment variables for path substitutions:
+
+    <variablelist>
+     <varlistentry>
+      <term><literal>PG_ABS_SRCDIR</literal></term>
+      <listitem>
+       <para>
+        Absolute path to the source directory.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+     <term><literal>PG_ABS_BUILDDIR</literal></term>
+     <listitem>
+      <para>
+       Absolute path to the build directory.
+      </para>
+     </listitem>
+     </varlistentry>
+
+     <varlistentry>
+     <term><literal>PG_DLSUFFIX</literal></term>
+     <listitem>
+      <para>
+       Name of extension for dynamically-loadable modules (e.g.
+       <literal>.so</literal> on Linux).
+      </para>
+     </listitem>
+     </varlistentry>
+
+     <varlistentry>
+     <term><literal>PG_LIBDIR</literal></term>
+     <listitem>
+      <para>
+       Absolute path to dynamic libraries.
+      </para>
+     </listitem>
+     </varlistentry>
+    </variablelist>
+   </para>
+
+   <para>
+    These variables should be set in the tests with the meta-command
+    <command>\getenv</command>, like:
+<programlisting>
+\getenv abs_builddir PG_ABS_BUILDDIR
+\getenv abs_srcdir PG_ABS_SRCDIR
+</programlisting>
+   </para>
+
+   <para>
+    These are useful when dealing with function and object loading
+    that require specific paths to work, like paths defined in a
+    <command>CREATE FUNCTION</command> or <command>LOAD</command>
+    command.
+   </para>
+  </sect2>
+
   <sect2 id="regress-run-custom-settings">
    <title>Custom Server Settings</title>