From 0064020680c1293ec6ce9fe2588e33d6aebdb015 Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter@eisentraut.org>
Date: Thu, 1 May 2025 22:10:36 +0200
Subject: [PATCH] doc: Flesh out extension 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.

Author: David E. Wheeler <david@justatheory.com>
Reviewed-by: Matheus Alcantara <matheusssilv97@gmail.com>
Reviewed-by: Christoph Berg <myon@debian.org>
Discussion: https://www.postgresql.org/message-id/6B5BF07B-8A21-48E3-858C-1DC22F3A28B4@justatheory.com
---
 doc/src/sgml/extend.sgml | 34 ++++++++++++++++++++++++++++++----
 1 file changed, 30 insertions(+), 4 deletions(-)

diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml
index 64f8e133cae..4915c1985e0 100644
--- a/doc/src/sgml/extend.sgml
+++ b/doc/src/sgml/extend.sgml
@@ -1809,10 +1809,36 @@ 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 select a separate directory prefix in which to install your
+    extension's files, by setting the <command>make</command> variable
+    <varname>prefix</varname> when executing <literal>make install</literal>
+    like so:
+<programlisting>
+make install prefix=/usr/local/postgresql
+</programlisting>
+    This will install the extension control and SQL files into
+    <filename>/usr/local/postgresql/share</filename> and the shared modules into
+    <filename>/usr/local/postgresql/lib</filename>.  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 <literal>postgresql</literal> will be appended to the directory
+    names, installing the control and SQL files into
+    <filename>/usr/local/extras/share/postgresql/extension</filename> and the
+    shared modules into <filename>/usr/local/extras/lib/postgresql</filename>.
+    Either way, you'll need to set <xref
+    linkend="guc-extension-control-path"/> and <xref
+    linkend="guc-dynamic-library-path"/> to enable the
+    <productname>PostgreSQL</productname> server to find the files:
+<programlisting>
+extension_control_path = '/usr/local/extras/share/postgresql/extension:$system'
+dynamic_library_path = '/usr/local/extras/lib/postgresql:$libdir'
+</programlisting>
    </para>
 
    <para>
-- 
2.39.5