From b8cc8f94730610c0189aa82dfec4ae6ce9b13e34 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Tue, 27 May 2014 19:42:08 -0400
Subject: Support BSD and e2fsprogs UUID libraries alongside OSSP UUID library.

Allow the contrib/uuid-ossp extension to be built atop any one of these
three popular UUID libraries.  (The extension's name is now arguably a
misnomer, but we'll keep it the same so as not to cause unnecessary
compatibility issues for users.)

We would not normally consider a change like this post-beta1, but the issue
has been forced by our upgrade to autoconf 2.69, whose more rigorous header
checks are causing OSSP's header files to be rejected on some platforms.
It's been foreseen for some time that we'd have to move away from depending
on OSSP UUID due to lack of upstream maintenance, so this is a down payment
on that problem.

While at it, add some simple regression tests, in hopes of catching any
major incompatibilities between the three implementations.

Matteo Beccati, with some further hacking by me
---
 doc/src/sgml/installation.sgml | 43 +++++++++++++++++++++++++++++++-------
 doc/src/sgml/uuid-ossp.sgml    | 47 +++++++++++++++++++++++++++++-------------
 2 files changed, 69 insertions(+), 21 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index b6b582e24c2..7353c612b1f 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -869,17 +869,46 @@ su - postgres
        </listitem>
       </varlistentry>
 
+      <varlistentry>
+       <term><option>--with-uuid=<replaceable>LIBRARY</replaceable></option></term>
+       <listitem>
+        <para>
+         Build the <![%standalone-include[uuid-ossp]]>
+         <![%standalone-ignore[<xref linkend="uuid-ossp">]]> module
+         (which provides functions to generate UUIDs), using the specified
+         UUID library.<indexterm><primary>UUID</primary></indexterm>
+         <replaceable>LIBRARY</replaceable> must be one of:
+        </para>
+        <itemizedlist>
+         <listitem>
+          <para>
+           <option>bsd</> to use the UUID functions found in FreeBSD, NetBSD,
+           and some other BSD-derived systems
+          </para>
+         </listitem>
+         <listitem>
+          <para>
+           <option>e2fs</> to use the UUID library created by
+           the <literal>e2fsprogs</> project; this library is present in most
+           Linux systems and in Mac OS X, and can be obtained for other
+           platforms as well
+          </para>
+         </listitem>
+         <listitem>
+          <para>
+           <option>ossp</> to use the <ulink
+           url="http://www.ossp.org/pkg/lib/uuid/">OSSP UUID library</ulink>
+          </para>
+         </listitem>
+        </itemizedlist>
+       </listitem>
+      </varlistentry>
+
       <varlistentry>
        <term><option>--with-ossp-uuid</option></term>
        <listitem>
         <para>
-         Build components using the <ulink
-         url="http://www.ossp.org/pkg/lib/uuid/">OSSP UUID
-         library</ulink>.  Specifically, build the
-         <![%standalone-include[uuid-ossp]]>
-         <![%standalone-ignore[<xref linkend="uuid-ossp">]]> module,
-         which provides functions to generate
-         UUIDs.<indexterm><primary>UUID</primary></indexterm>
+         Obsolete equivalent of <literal>--with-uuid=ossp</literal>.
         </para>
        </listitem>
       </varlistentry>
diff --git a/doc/src/sgml/uuid-ossp.sgml b/doc/src/sgml/uuid-ossp.sgml
index c48106ba0f4..dbbea09313a 100644
--- a/doc/src/sgml/uuid-ossp.sgml
+++ b/doc/src/sgml/uuid-ossp.sgml
@@ -13,20 +13,6 @@
   are also functions to produce certain special UUID constants.
  </para>
 
- <para>
-  This module depends on the OSSP UUID library, which can be found at
-  <ulink url="http://www.ossp.org/pkg/lib/uuid/"></ulink>.
- </para>
-
- <note>
-  <para>
-   The OSSP UUID library is not well maintained, and is becoming increasingly
-   difficult to port to newer platforms.  If you only need randomly-generated
-   (version 4) UUIDs, consider using the <function>gen_random_uuid()</>
-   function from the <xref linkend="pgcrypto"> module instead.
-  </para>
- </note>
-
  <sect2>
   <title><literal>uuid-ossp</literal> Functions</title>
 
@@ -172,6 +158,39 @@ SELECT uuid_generate_v3(uuid_ns_url(), 'http://www.postgresql.org');
   </table>
  </sect2>
 
+ <sect2>
+  <title>Building <filename>uuid-ossp</></title>
+
+  <para>
+   Historically this module depended on the OSSP UUID library, which accounts
+   for the module's name.  While the OSSP UUID library can still be found
+   at <ulink url="http://www.ossp.org/pkg/lib/uuid/"></ulink>, it is not well
+   maintained, and is becoming increasingly difficult to port to newer
+   platforms.  <filename>uuid-ossp</> can now be built without the OSSP
+   library on some platforms.  On FreeBSD, NetBSD, and some other BSD-derived
+   platforms, suitable UUID creation functions are included in the
+   core <filename>libc</> library.  On Linux, Mac OS X, and some other
+   platforms, suitable functions are provided in the <filename>libuuid</>
+   library, which originally came from the <literal>e2fsprogs</> project
+   (though on modern Linux it is considered part
+   of <literal>util-linux-ng</>).  When invoking <filename>configure</>,
+   specify <option>--with-uuid=bsd</option> to use the BSD functions,
+   or <option>--with-uuid=e2fs</option> to
+   use <literal>e2fsprogs</>' <filename>libuuid</>, or
+   <option>--with-uuid=ossp</option> to use the OSSP UUID library.
+   More than one of these libraries might be available on a particular
+   machine, so <filename>configure</> does not automatically choose one.
+  </para>
+
+  <note>
+   <para>
+    If you only need randomly-generated (version 4) UUIDs,
+    consider using the <function>gen_random_uuid()</> function
+    from the <xref linkend="pgcrypto"> module instead.
+   </para>
+  </note>
+ </sect2>
+
  <sect2>
   <title>Author</title>
 
-- 
cgit v1.2.3