From abae617e900539f349d5b6aadf8c4f74fa17d153 Mon Sep 17 00:00:00 2001
From: "David E. Wheeler" <david@justatheory.com>
Date: Wed, 19 Mar 2025 13:18:33 -0400
Subject: [PATCH] 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 64f8e133caeb..4e75a01fae4e 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=/etc/postgresql
+</programlisting>
+    This will install the control SQL files into
+    <literal>/etc/postgresql/share</literal> and shared modules into
+    <literal>/etc/postgresql/lib</literal>. If the prefix does not
+    include the strings <literal>postgresql</literal> or
+    <literal>pgsql</literal>, such as:
+<programlisting>
+make install prefix=/etc/extras
+</programlisting>
+    Then the <literal>postgresql</literal> directory will be appended io the
+    prefix, installing the control SQL files into
+    <literal>/etc/extras/postgresql/share</literal> and shared modules into
+    <literal>/etc/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 = '/etc/extras/postgresql/share/extension:$system'
+dynamic_library_path = '/etc/extras/postgresql/lib:$libdir'
+ </programlisting>
    </para>
 
    <para>