From 7d0f94729f20300e55375c8a05b52aeeaf00f1f0 Mon Sep 17 00:00:00 2001
From: Nazir Bilal Yavuz <byavuz81@gmail.com>
Date: Thu, 6 Mar 2025 17:46:57 +0300
Subject: [PATCH v6 4/7] meson: [WIP] Add docs for postgresql-extension.pc

Author: Andres Freund <andres@anarazel.de>
Author: Nazir Bilal Yavuz <byavuz81@gmail.com>
Discussion: https://postgr.es/m/206b001d-1884-4081-bd02-bed5c92f02ba%40eisentraut.org
---
 doc/src/sgml/acronyms.sgml |   2 +-
 doc/src/sgml/extend.sgml   | 101 +++++++++++++++++++++++--------------
 doc/src/sgml/jit.sgml      |   2 +-
 3 files changed, 66 insertions(+), 39 deletions(-)

diff --git a/doc/src/sgml/acronyms.sgml b/doc/src/sgml/acronyms.sgml
index 2f906e9f018..57f49c06a19 100644
--- a/doc/src/sgml/acronyms.sgml
+++ b/doc/src/sgml/acronyms.sgml
@@ -579,7 +579,7 @@
     <term><acronym>PGXS</acronym></term>
     <listitem>
      <para>
-      <link linkend="extend-pgxs"><productname>PostgreSQL</productname> Extension System</link>
+      <link linkend="extend-postgres-pgxs"><productname>PostgreSQL</productname> Extension System</link>
      </para>
     </listitem>
    </varlistentry>
diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml
index 63c5ec6d1eb..6d9fe5e96ad 100644
--- a/doc/src/sgml/extend.sgml
+++ b/doc/src/sgml/extend.sgml
@@ -1426,7 +1426,7 @@ include $(PGXS)
 </programlisting>
 
      This makefile relies on <acronym>PGXS</acronym>, which is described
-     in <xref linkend="extend-pgxs"/>.  The command <literal>make install</literal>
+     in <xref linkend="extend-postgres-pgxs"/>.  The command <literal>make install</literal>
      will install the control and script files into the correct
      directory as reported by <application>pg_config</application>.
     </para>
@@ -1439,21 +1439,26 @@ include $(PGXS)
    </sect2>
   </sect1>
 
-  <sect1 id="extend-pgxs">
+  <sect1 id="extend-postgres">
    <title>Extension Building Infrastructure</title>
 
-   <indexterm zone="extend-pgxs">
-    <primary>pgxs</primary>
-   </indexterm>
-
    <para>
     If you are thinking about distributing your
     <productname>PostgreSQL</productname> extension modules, setting up a
     portable build system for them can be fairly difficult.  Therefore
     the <productname>PostgreSQL</productname> installation provides a build
-    infrastructure for extensions, called <acronym>PGXS</acronym>, so
-    that simple extension modules can be built simply against an
-    already installed server.  <acronym>PGXS</acronym> is mainly intended
+    infrastructure for extensions, called <literal>PGXS</literal>
+    (<xref linkend="extend-postgres-pgxs"/>) and
+    its meson counterpart <literal>postgresql-extension.pc</literal>
+    (<xref linkend="extend-postgres-meson"/>).
+   </para>
+
+  </sect1>
+
+  <sect1 id="extend-postgres-pgxs">
+   <title>PGXS</title>
+
+   <para>  <acronym>PGXS</acronym> is mainly intended
     for extensions that include C code, although it can be used for
     pure-SQL extensions too.  Note that <acronym>PGXS</acronym> is not
     intended to be a universal build system framework that can be used
@@ -1493,7 +1498,7 @@ include $(PGXS)
     Set one of these three variables to specify what is built:
 
     <variablelist>
-     <varlistentry id="extend-pgxs-modules">
+     <varlistentry id="extend-postgres-pgxs-modules">
       <term><varname>MODULES</varname></term>
       <listitem>
        <para>
@@ -1503,7 +1508,7 @@ include $(PGXS)
       </listitem>
      </varlistentry>
 
-     <varlistentry id="extend-pgxs-module-big">
+     <varlistentry id="extend-postgres-pgxs-module-big">
       <term><varname>MODULE_big</varname></term>
       <listitem>
        <para>
@@ -1513,7 +1518,7 @@ include $(PGXS)
       </listitem>
      </varlistentry>
 
-     <varlistentry id="extend-pgxs-program">
+     <varlistentry id="extend-postgres-pgxs-program">
       <term><varname>PROGRAM</varname></term>
       <listitem>
        <para>
@@ -1527,7 +1532,7 @@ include $(PGXS)
     The following variables can also be set:
 
     <variablelist>
-     <varlistentry id="extend-pgxs-extension">
+     <varlistentry id="extend-postgres-pgxs-extension">
       <term><varname>EXTENSION</varname></term>
       <listitem>
        <para>
@@ -1539,7 +1544,7 @@ include $(PGXS)
       </listitem>
      </varlistentry>
 
-     <varlistentry id="extend-pgxs-moduledir">
+     <varlistentry id="extend-postgres-pgxs-moduledir">
       <term><varname>MODULEDIR</varname></term>
       <listitem>
        <para>
@@ -1552,7 +1557,7 @@ include $(PGXS)
       </listitem>
      </varlistentry>
 
-     <varlistentry id="extend-pgxs-data">
+     <varlistentry id="extend-postgres-pgxs-data">
       <term><varname>DATA</varname></term>
       <listitem>
        <para>
@@ -1561,7 +1566,7 @@ include $(PGXS)
       </listitem>
      </varlistentry>
 
-     <varlistentry id="extend-pgxs-data-built">
+     <varlistentry id="extend-postgres-pgxs-data-built">
       <term><varname>DATA_built</varname></term>
       <listitem>
        <para>
@@ -1572,7 +1577,7 @@ include $(PGXS)
       </listitem>
      </varlistentry>
 
-     <varlistentry id="extend-pgxs-data-tsearch">
+     <varlistentry id="extend-postgres-pgxs-data-tsearch">
       <term><varname>DATA_TSEARCH</varname></term>
       <listitem>
        <para>
@@ -1582,7 +1587,7 @@ include $(PGXS)
       </listitem>
      </varlistentry>
 
-     <varlistentry id="extend-pgxs-docs">
+     <varlistentry id="extend-postgres-pgxs-docs">
       <term><varname>DOCS</varname></term>
       <listitem>
        <para>
@@ -1592,7 +1597,7 @@ include $(PGXS)
       </listitem>
      </varlistentry>
 
-     <varlistentry id="extend-pgxs-headers">
+     <varlistentry id="extend-postgres-pgxs-headers">
       <term><varname>HEADERS</varname></term>
       <term><varname>HEADERS_built</varname></term>
       <listitem>
@@ -1608,7 +1613,7 @@ include $(PGXS)
       </listitem>
      </varlistentry>
 
-     <varlistentry id="extend-pgxs-headers-module">
+     <varlistentry id="extend-postgres-pgxs-headers-module">
       <term><varname>HEADERS_$MODULE</varname></term>
       <term><varname>HEADERS_built_$MODULE</varname></term>
       <listitem>
@@ -1634,7 +1639,7 @@ include $(PGXS)
       </listitem>
      </varlistentry>
 
-     <varlistentry id="extend-pgxs-scripts">
+     <varlistentry id="extend-postgres-pgxs-scripts">
       <term><varname>SCRIPTS</varname></term>
       <listitem>
        <para>
@@ -1644,7 +1649,7 @@ include $(PGXS)
       </listitem>
      </varlistentry>
 
-     <varlistentry id="extend-pgxs-scripts-built">
+     <varlistentry id="extend-postgres-pgxs-scripts-built">
       <term><varname>SCRIPTS_built</varname></term>
       <listitem>
        <para>
@@ -1655,7 +1660,7 @@ include $(PGXS)
       </listitem>
      </varlistentry>
 
-     <varlistentry id="extend-pgxs-regress">
+     <varlistentry id="extend-postgres-pgxs-regress">
       <term><varname>REGRESS</varname></term>
       <listitem>
        <para>
@@ -1664,7 +1669,7 @@ include $(PGXS)
       </listitem>
      </varlistentry>
 
-     <varlistentry id="extend-pgxs-regress-opts">
+     <varlistentry id="extend-postgres-pgxs-regress-opts">
       <term><varname>REGRESS_OPTS</varname></term>
       <listitem>
        <para>
@@ -1673,7 +1678,7 @@ include $(PGXS)
       </listitem>
      </varlistentry>
 
-     <varlistentry id="extend-pgxs-isolation">
+     <varlistentry id="extend-postgres-pgxs-isolation">
       <term><varname>ISOLATION</varname></term>
       <listitem>
        <para>
@@ -1682,7 +1687,7 @@ include $(PGXS)
       </listitem>
      </varlistentry>
 
-     <varlistentry id="extend-pgxs-isolation-opts">
+     <varlistentry id="extend-postgres-pgxs-isolation-opts">
       <term><varname>ISOLATION_OPTS</varname></term>
       <listitem>
        <para>
@@ -1692,7 +1697,7 @@ include $(PGXS)
       </listitem>
      </varlistentry>
 
-     <varlistentry id="extend-pgxs-tap-tests">
+     <varlistentry id="extend-postgres-pgxs-tap-tests">
       <term><varname>TAP_TESTS</varname></term>
       <listitem>
        <para>
@@ -1701,7 +1706,7 @@ include $(PGXS)
       </listitem>
      </varlistentry>
 
-     <varlistentry id="extend-pgxs-no-install">
+     <varlistentry id="extend-postgres-pgxs-no-install">
       <term><varname>NO_INSTALL</varname></term>
       <listitem>
        <para>
@@ -1711,7 +1716,7 @@ include $(PGXS)
       </listitem>
      </varlistentry>
 
-     <varlistentry id="extend-pgxs-no-installcheck">
+     <varlistentry id="extend-postgres-pgxs-no-installcheck">
       <term><varname>NO_INSTALLCHECK</varname></term>
       <listitem>
        <para>
@@ -1720,7 +1725,7 @@ include $(PGXS)
       </listitem>
      </varlistentry>
 
-     <varlistentry id="extend-pgxs-extra-clean">
+     <varlistentry id="extend-postgres-pgxs-extra-clean">
       <term><varname>EXTRA_CLEAN</varname></term>
       <listitem>
        <para>
@@ -1729,7 +1734,7 @@ include $(PGXS)
       </listitem>
      </varlistentry>
 
-     <varlistentry id="extend-pgxs-pg-cppflags">
+     <varlistentry id="extend-postgres-pgxs-pg-cppflags">
       <term><varname>PG_CPPFLAGS</varname></term>
       <listitem>
        <para>
@@ -1738,7 +1743,7 @@ include $(PGXS)
       </listitem>
      </varlistentry>
 
-     <varlistentry id="extend-pgxs-pg-cflags">
+     <varlistentry id="extend-postgres-pgxs-pg-cflags">
       <term><varname>PG_CFLAGS</varname></term>
       <listitem>
        <para>
@@ -1747,7 +1752,7 @@ include $(PGXS)
       </listitem>
      </varlistentry>
 
-     <varlistentry id="extend-pgxs-pg-cxxflags">
+     <varlistentry id="extend-postgres-pgxs-pg-cxxflags">
       <term><varname>PG_CXXFLAGS</varname></term>
       <listitem>
        <para>
@@ -1756,7 +1761,7 @@ include $(PGXS)
       </listitem>
      </varlistentry>
 
-     <varlistentry id="extend-pgxs-pg-ldflags">
+     <varlistentry id="extend-postgres-pgxs-pg-ldflags">
       <term><varname>PG_LDFLAGS</varname></term>
       <listitem>
        <para>
@@ -1765,7 +1770,7 @@ include $(PGXS)
       </listitem>
      </varlistentry>
 
-     <varlistentry id="extend-pgxs-pg-libs">
+     <varlistentry id="extend-postgres-pgxs-pg-libs">
       <term><varname>PG_LIBS</varname></term>
       <listitem>
        <para>
@@ -1774,7 +1779,7 @@ include $(PGXS)
       </listitem>
      </varlistentry>
 
-     <varlistentry id="extend-pgxs-shlib-link">
+     <varlistentry id="extend-postgres-pgxs-shlib-link">
       <term><varname>SHLIB_LINK</varname></term>
       <listitem>
        <para>
@@ -1783,7 +1788,7 @@ include $(PGXS)
       </listitem>
      </varlistentry>
 
-     <varlistentry id="extend-pgxs-pg-config">
+     <varlistentry id="extend-postgres-pgxs-pg-config">
       <term><varname>PG_CONFIG</varname></term>
       <listitem>
        <para>
@@ -1929,4 +1934,26 @@ make VPATH=/path/to/extension/source/tree install
    </tip>
   </sect1>
 
+  <sect1 id="extend-postgres-meson">
+   <title>postgresql-extension.pc</title>
+
+   <para>
+    When Postgres is built by using meson, it generates
+    <literal>postgresql-extension.pc</literal> pkg-config file. Extension
+    libraries can use this file like <literal>PGXS</literal>
+    (<xref linkend="extend-postgres-pgxs"/>).
+
+    To use the <literal>postgresql-extension.pc</literal> infrastructure for
+    your extension, you must write a simple meson.build file. In the
+    meson.build file, you need to include the
+    <literal>postgresql-extension.pc</literal> pkg-config file. Here is an
+    example that builds an extension module named isbn_issn, consisting of a
+    shared library containing some C code, an extension control file, an SQL
+    script, an include file (only needed if other modules might need to access
+    the extension functions without going via SQL), and a documentation text
+    file:
+   </para>
+
+  </sect1>
+
  </chapter>
diff --git a/doc/src/sgml/jit.sgml b/doc/src/sgml/jit.sgml
index 44e18bf1a6f..81a4644a97d 100644
--- a/doc/src/sgml/jit.sgml
+++ b/doc/src/sgml/jit.sgml
@@ -223,7 +223,7 @@ SET
     of types <literal>C</literal> and <literal>internal</literal>, as well as
     operators based on such functions.  To do so for functions in extensions,
     the definitions of those functions need to be made available.
-    When using <link linkend="extend-pgxs">PGXS</link> to build an extension
+    When using <link linkend="extend-postgres-pgxs">PGXS</link> to build an extension
     against a server that has been compiled with LLVM JIT support, the
     relevant files will be built and installed automatically.
    </para>
-- 
2.49.0