Implement a preliminary 'template' facility for procedural languages,

as per my recent proposal.  For now the template data is hard-wired in
proclang.c --- this should be replaced later by a new shared system
catalog, but we don't want to force initdb during 8.1 beta.  This change
lets us cleanly load existing dump files even if they contain outright
wrong information about a PL's support functions, such as a wrong path
to the shared library or a missing validator function.  Also, we can
revert the recent kluges to make pg_dump dump PL support functions that
are stored in pg_catalog.
While at it, I removed the code in pg_regress that replaced $libdir
with a hardcoded path for temporary installations.  This is no longer
needed given our support for relocatable installations.

3 files changed, 101 insertions, 73 deletions

diff --git a/doc/src/sgml/ref/create_language.sgml b/doc/src/sgml/ref/create_language.sgml
index 9e895f2817b..29bcade195d 100644
--- a/doc/src/sgml/ref/create_language.sgml
+++ b/doc/src/sgml/ref/create_language.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_language.sgml,v 1.39 2005/01/04 00:39:53 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_language.sgml,v 1.40 2005/09/05 23:50:48 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -20,6 +20,7 @@ PostgreSQL documentation
 
  <refsynopsisdiv>
 <synopsis>
+CREATE [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</replaceable>
 CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</replaceable>
     HANDLER <replaceable class="parameter">call_handler</replaceable> [ VALIDATOR <replaceable>valfunction</replaceable> ]
 </synopsis>
@@ -46,9 +47,25 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</
   </para>
 
   <para>
-   Note that procedural languages are local to individual databases.
-   To make a language available in all databases by default, it should
-   be installed into the <literal>template1</literal> database.
+   There are two forms of the <command>CREATE LANGUAGE</command> command.
+   In the first form, the user merely supplies the name of the desired
+   language, and the <productname>PostgreSQL</productname> server consults
+   an internal table to determine the correct parameters.  In
+   the second form, the user supplies the language parameters along with
+   the language name.  The second form must be used to create a language
+   that is not present in the internal table, but this form is considered
+   obsolescent.  (It is expected that future releases of
+   <productname>PostgreSQL</productname> will replace the internal table
+   with a system catalog that can be extended to support additional
+   languages.)
+  </para>
+
+  <para>
+   When the server finds an entry in its internal table for the given
+   language name, it will use the table data even if the given command
+   includes language parameters.  This behavior simplifies loading of
+   old dump files, which are likely to contain out-of-date information
+   about language support functions.
   </para>
  </refsect1>
 
@@ -145,52 +162,68 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</
      </listitem>
     </varlistentry>
    </variablelist>
+
+  <para>
+   The <literal>TRUSTED</> option and the support function name(s) are
+   ignored if the server has information about the specified language
+   name in its internal table.
+  </para>
  </refsect1>
 
  <refsect1 id="sql-createlanguage-notes">
   <title>Notes</title>
 
   <para>
-   This command normally should not be executed directly by users.
-   For the procedural languages supplied in the
-   <productname>PostgreSQL</productname> distribution, the <xref
-   linkend="app-createlang"> program should be used, which will also
-   install the correct call handler.  (<command>createlang</command>
-   will call <command>CREATE LANGUAGE</command> internally.)
+   The <xref linkend="app-createlang"> program is a simple wrapper around
+   the <command>CREATE LANGUAGE</> command.  It eases
+   installation of procedural languages from the shell command line.
   </para>
 
   <para>
-   In <productname>PostgreSQL</productname> versions before 7.3, it was
-   necessary to declare handler functions as returning the placeholder
-   type <type>opaque</>, rather than <type>language_handler</>.
-   To support loading 
-   of old dump files, <command>CREATE LANGUAGE</> will accept a function
-   declared as returning <type>opaque</>, but it will issue a notice and
-   change the function's declared return type to <type>language_handler</>.
+   Use <xref linkend="sql-droplanguage" endterm="sql-droplanguage-title">, or better yet the <xref
+   linkend="app-droplang"> program, to drop procedural languages.
   </para>
 
   <para>
-   Use the <xref linkend="sql-createfunction" endterm="sql-createfunction-title"> command to create a new
-   function.
+   The system catalog <classname>pg_language</classname> (see <xref
+   linkend="catalog-pg-language">) records information about the
+   currently installed languages.  Also, <command>createlang</command>
+   has an option to list the installed languages.
   </para>
 
   <para>
-   Use <xref linkend="sql-droplanguage" endterm="sql-droplanguage-title">, or better yet the <xref
-   linkend="app-droplang"> program, to drop procedural languages.
+   To create functions in a procedural language, a user must have the
+   <literal>USAGE</literal> privilege for the language.  By default,
+   <literal>USAGE</> is granted to <literal>PUBLIC</> (i.e., everyone)
+   for trusted languages.  This may be revoked if desired.
   </para>
 
   <para>
-   The system catalog <classname>pg_language</classname> (see <xref
-   linkend="catalog-pg-language">) records information about the
-   currently installed languages.  Also <command>createlang</command>
-   has an option to list the installed languages.
+   Procedural languages are local to individual databases.
+   However, a language can be installed into the <literal>template1</literal>
+   database, which will cause it to be available automatically in
+   all subsequently-created databases.
   </para>
 
   <para>
-   To be able to use a procedural language, a user must be granted the
-   <literal>USAGE</literal> privilege.  The
-   <command>createlang</command> program automatically grants
-   permissions to everyone if the language is known to be trusted.
+   The call handler function and the validator function (if any)
+   must already exist if the server does not have information about
+   the language in its internal table.  But when there is an entry
+   in the internal table, the functions need not already exist;
+   they will be automatically defined if not present in the database.
+   (This can result in <command>CREATE LANGUAGE</> failing, if the
+   shared library that implements the language is not available in
+   the installation.)
+  </para>
+
+  <para>
+   In <productname>PostgreSQL</productname> versions before 7.3, it was
+   necessary to declare handler functions as returning the placeholder
+   type <type>opaque</>, rather than <type>language_handler</>.
+   To support loading 
+   of old dump files, <command>CREATE LANGUAGE</> will accept a function
+   declared as returning <type>opaque</>, but it will issue a notice and
+   change the function's declared return type to <type>language_handler</>.
   </para>
  </refsect1>
 
@@ -198,8 +231,16 @@ CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE <replaceable class="parameter">name</
   <title>Examples</title>
 
   <para>
-   The following two commands executed in sequence will register a new
-   procedural language and the associated call handler.
+   The preferred way of creating any of the standard procedural languages
+   is just:
+<programlisting>
+CREATE LANGUAGE plpgsql;
+</programlisting>
+  </para>
+
+  <para>
+   For a language not known in the server's internal table, a sequence
+   such as this is needed:
 <programlisting>
 CREATE FUNCTION plsample_call_handler() RETURNS language_handler
     AS '$libdir/plsample'
diff --git a/doc/src/sgml/ref/createlang.sgml b/doc/src/sgml/ref/createlang.sgml
index 9829d845b0e..f9f8dc1ea78 100644
--- a/doc/src/sgml/ref/createlang.sgml
+++ b/doc/src/sgml/ref/createlang.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/createlang.sgml,v 1.35 2005/06/21 04:02:31 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/createlang.sgml,v 1.36 2005/09/05 23:50:48 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -42,13 +42,7 @@ PostgreSQL documentation
    programming language to a <productname>PostgreSQL</productname> database.
    <application>createlang</application> can handle all the languages
    supplied in the default <productname>PostgreSQL</> distribution, but
-   not languages provided by other parties.
-  </para>
-  <para>
-   Although backend programming languages can be added directly using
-   several <acronym>SQL</acronym> commands, it is recommended to use
-   <application>createlang</application> because it performs a number
-   of checks and is much easier to use. See
+   not languages provided by other parties.  See
    <xref linkend="sql-createlanguage" endterm="sql-createlanguage-title">
    for additional information.
   </para>
@@ -66,8 +60,8 @@ PostgreSQL documentation
       <term><replaceable class="parameter">langname</replaceable></term>
       <listitem>
        <para>
-	Specifies the name of the procedural programming language to be
-	defined.
+        Specifies the name of the procedural programming language to be
+        defined.
        </para>
       </listitem>
      </varlistentry>
@@ -77,7 +71,7 @@ PostgreSQL documentation
       <term><option><optional>--dbname</> <replaceable class="parameter">dbname</replaceable></></term>
       <listitem>
        <para>
-	Specifies to which database the language should be added.
+        Specifies to which database the language should be added.
         The default is to use the database with the same name as the
         current system user.
        </para>
@@ -104,17 +98,6 @@ PostgreSQL documentation
       </listitem>
      </varlistentry>
 
-     <varlistentry>
-      <term><option>-L <replaceable class="parameter">directory</replaceable></></term>
-      <listitem>
-       <para>
-	Specifies the directory in which the language interpreter is
-        to be found.  The directory is normally found automatically; this
-        option is primarily for debugging purposes.
-       </para>
-      </listitem>
-     </varlistentry>
-
     </variablelist>
    </para>
 
@@ -128,10 +111,10 @@ PostgreSQL documentation
       <term><option>--host <replaceable class="parameter">host</replaceable></></term>
       <listitem>
        <para>
-	Specifies the host name of the machine on which the 
-	server
-	is running.  If the value begins with a slash, it is used 
-	as the directory for the Unix domain socket.
+        Specifies the host name of the machine on which the 
+        server
+        is running.  If the value begins with a slash, it is used 
+        as the directory for the Unix domain socket.
        </para>
       </listitem>
      </varlistentry>
@@ -141,9 +124,9 @@ PostgreSQL documentation
       <term><option>--port <replaceable class="parameter">port</replaceable></></term>
       <listitem>
        <para>
-	Specifies the TCP port or local Unix domain socket file 
-	extension on which the server
-	is listening for connections.
+        Specifies the TCP port or local Unix domain socket file 
+        extension on which the server
+        is listening for connections.
        </para>
       </listitem>
      </varlistentry>
diff --git a/doc/src/sgml/xplang.sgml b/doc/src/sgml/xplang.sgml
index 76842017a6a..7943138e623 100644
--- a/doc/src/sgml/xplang.sgml
+++ b/doc/src/sgml/xplang.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/xplang.sgml,v 1.28 2004/12/30 21:45:37 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/xplang.sgml,v 1.29 2005/09/05 23:50:48 tgl Exp $
 -->
 
  <chapter id="xplang">
@@ -59,17 +59,19 @@ $PostgreSQL: pgsql/doc/src/sgml/xplang.sgml,v 1.28 2004/12/30 21:45:37 tgl Exp $
    </para>
 
    <para>
-    For the languages supplied with the standard distribution, the
-    program <xref linkend="app-createlang"> may be used to install the
-    language instead of carrying out the details by hand.  For
-    example, to install the language
+    For the languages supplied with the standard distribution, it is
+    only necessary to execute <command>CREATE LANGUAGE</>
+    <replaceable>language_name</> to install the language into the
+    current database.  Alternatively, the program <xref
+    linkend="app-createlang"> may be used to do this from the shell
+    command line.  For example, to install the language
     <application>PL/pgSQL</application> into the database
     <literal>template1</>, use
 <programlisting>
 createlang plpgsql template1
 </programlisting>
     The manual procedure described below is only recommended for
-    installing custom languages that <command>createlang</command>
+    installing custom languages that <command>CREATE LANGUAGE</command>
     does not know about.
    </para>
 
@@ -80,9 +82,10 @@ createlang plpgsql template1
 
     <para>
      A procedural language is installed in a database in four steps,
-     which must be carried out by a database superuser.  The
-     <command>createlang</command> program automates all but <xref
-     linkend="xplang-install-cr1">.
+     which must be carried out by a database superuser.  (For languages
+     known to <command>CREATE LANGUAGE</>, the second and third steps
+     can be omitted, because they will be carried out automatically
+     if needed.)
     </para>
 
     <step performance="required" id="xplang-install-cr1">
@@ -202,10 +205,11 @@ CREATE TRUSTED PROCEDURAL LANGUAGE plpgsql
     In a default <productname>PostgreSQL</productname> installation,
     the handler for the <application>PL/pgSQL</application> language
     is built and installed into the <quote>library</quote>
-    directory. If <application>Tcl</> support is configured in, the handlers for
-    <application>PL/Tcl</> and <application>PL/TclU</> are also built and installed in the same
-    location.  Likewise, the <application>PL/Perl</> and <application>PL/PerlU</> handlers are built
-    and installed if Perl support is configured, and <application>PL/PythonU</> is
+    directory. If <application>Tcl</> support is configured in, the handlers
+    for <application>PL/Tcl</> and <application>PL/TclU</> are also built and
+    installed in the same location.  Likewise, the <application>PL/Perl</> and
+    <application>PL/PerlU</> handlers are built and installed if Perl support
+    is configured, and the <application>PL/PythonU</> handler is
     installed if Python support is configured.
    </para>