From d49d3445ca5bdde436713dc8a2ae7707683851e3 Mon Sep 17 00:00:00 2001
From: "David E. Wheeler" <david@justatheory.com>
Date: Fri, 25 Apr 2025 15:22:23 -0400
Subject: [PATCH v3] Flesh out docs for the `prefix` make variable

The variable is a bit magical in how it requires "postgresql" or "pgsql"
to be part of the path, and files end up in its `share` and `lib`
subdirectories. So mention all that and show an example of setting
`extension_control_path` and `dynamic_library_path` to use those
locations.
---
 doc/src/sgml/extend.sgml | 33 +++++++++++++++++++++++++++++----
 1 file changed, 29 insertions(+), 4 deletions(-)

diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml
index 64f8e133cae..05063d4e7bc 100644
--- a/doc/src/sgml/extend.sgml
+++ b/doc/src/sgml/extend.sgml
@@ -1809,10 +1809,35 @@ include $(PGXS)
     setting <varname>PG_CONFIG</varname> to point to its
     <command>pg_config</command> program, either within the makefile
     or on the <literal>make</literal> command line.
-    You can also select a separate installation directory for your extension
-    by setting the <literal>make</literal> variable <varname>prefix</varname>
-    on the <literal>make</literal> command line.  (But this will then require
-    additional setup to get the server to find the extension there.)
+   </para>
+
+   <para>
+    You can also select a separate directory prefix in which to install your
+    extension's files by setting the <literal>make</literal> variable
+    <varname>prefix</varname> when executing <literal>make install</literal>
+    like so:
+<programlisting>
+make install prefix=/usr/local/postgresql
+</programlisting>
+    This will install the control SQL files into
+    <literal>/usr/local/postgresql/share</literal> and shared modules into
+    <literal>/usr/local/postgresql/lib</literal>. If the prefix does not
+    include the strings <literal>postgres</literal> or
+    <literal>pgsql</literal>, such as:
+<programlisting>
+make install prefix=/usr/local/extras
+</programlisting>
+    Then the <literal>postgresql</literal> directory will be appended io the
+    prefix, installing the control and SQL files into
+    <literal>/usr/local/extras/postgresql/share/extension</literal> and shared
+    modules into <literal>/usr/local/extras/postgresql/lib</literal>. Either
+    way, you'll need to set <xref linkend="guc-extension-control-path"/> and
+    <xref linkend="guc-dynamic-library-path"/> to allow
+    <productname>PostgreSQL</productname> to find the files:
+</programlisting>
+extension_control_path = '/usr/local/extras/postgresql/share/extension:$system'
+dynamic_library_path = '/usr/local/extras/postgresql/lib:$libdir'
+ </programlisting>
    </para>
 
    <para>
-- 
2.48.1