List:Commits« Previous MessageNext Message »
From:mhillyer Date:January 17 2006 5:23pm
Subject:svn commit - mysqldoc@docsrva: r873 - trunk/refman-5.1
View as plain text  
Author: mhillyer
Date: 2006-01-17 18:23:16 +0100 (Tue, 17 Jan 2006)
New Revision: 873

Log:
Removed pluggable information from 5.1 manual as per stefan/robin request.

Added:
   trunk/refman-5.1/custom-engine-build.xml
Modified:
   trunk/refman-5.1/custom-engine.xml
   trunk/refman-5.1/manual.xml
   trunk/refman-5.1/storage-engines.xml

Added: trunk/refman-5.1/custom-engine-build.xml
===================================================================
--- trunk/refman-5.1/custom-engine-build.xml	2006-01-17 17:13:14 UTC (rev 872)
+++ trunk/refman-5.1/custom-engine-build.xml	2006-01-17 17:23:16 UTC (rev 873)
@@ -0,0 +1,338 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section id="custom-engine-build">
+
+      <title>Building and Testing Pluggable Storage Engines</title>
+
+      <para>
+        With MySQL 5.1 it is possible to build storage engines as shared
+        objects that can be loaded dynamically into a running MySQL
+        server. This new approach makes it easier to deploy custom
+        storage engines because it is no longer necessary to re-compile
+        the MySQL server to install or upgrade a storage engine.
+      </para>
+
+      <para>
+        Building and testing a pluggable storage engine requires some
+        modifications to be made to your storage engine source files,
+        along with the creation of a specialized Makefile.
+      </para>
+
+      <section id="custom-engine-build-source">
+
+        <title>Source Modifications Required to Build a Pluggable Storage Engine</title>
+
+        <para>
+          When building a pluggable storage engine, avoid using symbol
+          names that already exist in the <literal>mysqld</literal>
+          source code. This can be as simple as prepending all symbol
+          names with the name of your storage engine.
+        </para>
+
+        <para>
+          The following line must be added to the start of your
+          <filename><replaceable>storage-engine</replaceable>.cc</filename>
+          file:
+        </para>
+
+<programlisting>
+#include &lt;plugins.h&gt;
+</programlisting>
+
+        <para>
+          The <filename>plugins.h</filename> file contains declarations
+          related to the MySQL plugin framework.
+        </para>
+
+        <para>
+          Additionally, the following macro must be appended to your
+          <filename><replaceable>storage-engine</replaceable>.cc</filename>
+          file:
+        </para>
+
+<programlisting>
+mysql_declare_plugin
+{
+  MYSQL_STORAGE_ENGINE_PLUGIN,
+  &amp;tina_hton,
+  tina_hton.name,
+  "MySQL AB",
+  "CSV Storage Engine",
+  tina_init_func, /* Plugin Init */
+  tina_done_func  /* Plugin Deinit */
+}
+mysql_declare_plugin_end;
+</programlisting>
+
+        <para>
+          The preceding example is from the <literal>CSV</literal>
+          storage engine.
+        </para>
+
+        <para>
+          The first element in the macro declares that this plugin is a
+          storage engine. The second element is a pointer to the storage
+          engine's
+          <link
+        linkend="custom-engine-handlerton">handlerton</link>.
+          The third element is the name of the plugin. The fourth
+          element is the author of the plugin. The fifth element is a
+          description of the plugin.
+        </para>
+
+        <para>
+          The <function>init</function> function performs any static
+          initialization required for the plugin, such as creating
+          mutexes and other internal structures.
+        </para>
+
+        <para>
+          The <function>done</function> function is used to free all
+          resources used by the plugin.
+        </para>
+
+        <para>
+          The storage engine should have a <function>panic</function>
+          function declared in its
+          <link linkend="custom-engine-handlerton">handlerton</link>.
+          Upon shutdown of <literal>mysqld</literal>, the panic function
+          is usually passed an argument of value
+          <literal>HA_PANIC_CLOSE</literal>, where the storage engine
+          should close all open tables. However, if the storage engine
+          is a pluggable, and the user attempts to un-install a storage
+          engine at runtime, the value of the panic argument will be
+          <literal>HA_PANIC_TRY_CLOSE</literal>. If the storage engine
+          has any open handler instances, it should return a nonzero
+          fail value, otherwise it should close all files and perform
+          any necessary cleanup.
+        </para>
+
+        <para>
+          In the case of a pluggable storage engine, returning a nonzero
+          value from the handlerton <function>init</function> function
+          does not prevent the storage engine shared library from being
+          loaded -- only the failure of the plugin
+          <function>init</function> function can prevent loading.
+          However, if the handlerton <function>init</function> function
+          returns failure, then the storage engine will be installed in
+          the <literal>DISABLED</literal> state.
+        </para>
+
+      </section>
+
+      <section id="custom-engine-build-makefile">
+
+        <title>Creating a Makefile to Build a Custom Storage Engine</title>
+
+        <para>
+          A <filename>Makefile.am</filename> file can be created for
+          your custom storage engine using <command>Libtool</command>.
+          The following sample Makefile is for the pluggable version of
+          the <literal>CSV</literal> engine:
+        </para>
+
+<programlisting>
+MYSQLDATAdir =          $(localstatedir)
+MYSQLSHAREdir =         $(pkgdatadir)
+MYSQLBASEdir=           $(prefix)
+MYSQLLIBdir=            $(pkglibdir)
+INCLUDES =              -I$(top_srcdir)/include \
+                        -I$(top_srcdir)/regex \
+                        -I$(top_srcdir)/sql \
+                        -I$(srcdir)
+WRAPLIBS=
+
+lib_LTLIBRARIES =       libhacsv.la
+
+libhacsv_la_SOURCES =   ha_tina.cc
+
+LDADD =
+
+DEFS =                  -DMYSQL_SERVER @DEFS@
+
+# Don't update the files from bitkeeper %::SCCS/s.%
+</programlisting>
+
+      </section>
+
+      <section id="custom-engine-build-buildobject">
+
+        <title>Building a Shared Object</title>
+
+        <para>
+          Once the Makefile is created, use the following steps to build
+          a pluggable shared object:
+        </para>
+
+        <orderedlist>
+
+          <listitem>
+            <para>
+              Navigate to the directory containing
+              <filename>Makefile.am</filename>.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Type <command>make</command> to compile the shared object.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Type <command>make install</command> to install the shared
+              object into the MySQL server's library directory.
+            </para>
+          </listitem>
+
+        </orderedlist>
+
+      </section>
+
+      <section id="custom-engine-install">
+
+        <title>Installing a Custom Storage Engine</title>
+
+        <para>
+          Once your storage engine is built, ensure the
+          <filename>.so</filename> file is in the MySQL server library
+          directory (typically <filename>installdir/lib</filename>).
+        </para>
+
+        <para>
+          To install the plugin, issue the <literal>INSTALL
+          PLUGIN</literal> command:
+        </para>
+
+<programlisting>
+INSTALL PLUGIN <replaceable>ha_foo</replaceable> SONAME
+  '<replaceable>ha_foo.so</replaceable>';
+</programlisting>
+
+      </section>
+
+      <section id="custom-engine-uninstall">
+
+        <title>Uninstalling a Custom Storage Engine</title>
+
+        <para>
+          To uninstall a storage engine, use the <literal>UNINSTALL
+          PLUGIN</literal> statement:
+        </para>
+
+<programlisting>
+UNINSTALL PLUGIN <replaceable>ha_foo</replaceable>;
+</programlisting>
+
+        <para>
+          If you uninstall a storage engine that is being used by
+          existing tables, those tables will not be accessible, but will
+          still be present on disk (where applicable). Ensure that there
+          are no tables using a given storage engine before uninstalling
+          it otherwise the table will be inaccessible unless you
+          re-install the storage engine.
+        </para>
+
+      </section>
+
+      <section id="custom-engine-testing">
+
+        <title>Testing a Custom Storage Engine</title>
+
+        <para>
+          The MySQL AB development team follows a test-driven approach
+          for storage engine development: as functionality is developed
+          and bugs are fixed, new tests are added to an extensive
+          regression testing suite to ensure that new functionality
+          works properly and old bugs are not re-introduced.
+        </para>
+
+        <para>
+          Developers of custom storage engines can use the same
+          regression test suite to ensure the reliable operation of
+          their storage engine.
+        </para>
+
+        <para>
+          For more information on the MySQL Test Suite, see
+          <xref linkend="mysql-test-suite"/>.
+        </para>
+
+        <section id="custom-engine-testing-testrun">
+
+          <title>Running the Regression Test Suite</title>
+
+          <para>
+            To run the test suite follow these steps:
+          </para>
+
+          <orderedlist>
+
+            <listitem>
+              <para>
+                From the MySQL main directory tree change directory to
+                the <filename>mysql-test</filename> directory.
+              </para>
+            </listitem>
+
+            <listitem>
+              <para>
+                Run <command>perl ./mysql-test-run.pl</command>.
+              </para>
+            </listitem>
+
+          </orderedlist>
+
+          <para>
+            Running the script without options executes the complete
+            test suite on a server running on the local machine.
+          </para>
+
+          <para>
+            In order to run a subset of tests or a specific test case,
+            execute <command>perl ./mysql-test-run.pl
+            --do-test=abc</command>.This will execute all tests that
+            start with <literal>abc</literal>
+            (<literal>abc*.test</literal>).
+          </para>
+
+          <para>
+            For a complete list of options run <command>perl
+            ./mysql-test-run.pl --help</command>.
+          </para>
+
+        </section>
+
+        <section id="custom-engine-testing-custom">
+
+          <title>Customizing Test Script for Custom Engine Use</title>
+
+          <para>
+            The existing tests in the MySQL Test Suite are typically
+            created against specific storage engines. As such, running
+            the full test suite will not result in custom storage
+            engines being tested.
+          </para>
+
+          <para>
+            To add support for your storage engine to the test suite,
+            you must first write tests against your storage engine. The
+            simplest way to do this is to take an existing test script
+            and modify the <literal>CREATE TABLE</literal> statements
+            within to use your custom engine.
+          </para>
+
+          <para>
+            Tests are located in the <filename>mysql-test/t/</filename>.
+          </para>
+
+          <para>
+            For more information on creating and modifying tests, see
+            <xref linkend="extending-mysqltest"/>.
+          </para>
+
+        </section>
+
+      </section>
+
+    </section>
\ No newline at end of file

Modified: trunk/refman-5.1/custom-engine.xml
===================================================================
--- trunk/refman-5.1/custom-engine.xml	2006-01-17 17:13:14 UTC (rev 872)
+++ trunk/refman-5.1/custom-engine.xml	2006-01-17 17:23:16 UTC (rev 873)
@@ -34,10 +34,10 @@
       storage engine for the new pluggable storage engine architecture.
     </para>
 
-    <para>
+    <!--<para>
       For more information on the MySQL pluggable storage engine
       architecture, see <xref linkend="pluggable-storage"/>.
-    </para>
+    </para>-->
 
     <bridgehead>Additional resources</bridgehead>
 
@@ -2888,343 +2888,6 @@
 
   </section>
 
-  <section id="custom-engine-build">
-
-    <title>Building and Testing Pluggable Storage Engines</title>
-
-    <para>
-      With MySQL 5.1 it is possible to build storage engines as shared
-      objects that can be loaded dynamically into a running MySQL
-      server. This new approach makes it easier to deploy custom storage
-      engines because it is no longer necessary to re-compile the MySQL
-      server to install or upgrade a storage engine.
-    </para>
-
-    <para>
-      Building and testing a pluggable storage engine requires some
-      modifications to be made to your storage engine source files,
-      along with the creation of a specialized Makefile.
-    </para>
-
-    <section id="custom-engine-build-source">
-
-      <title>Source Modifications Required to Build a Pluggable Storage Engine</title>
-
-      <para>
-        When building a pluggable storage engine, avoid using symbol
-        names that already exist in the <literal>mysqld</literal> source
-        code. This can be as simple as prepending all symbol names with
-        the name of your storage engine.
-      </para>
-
-      <para>
-        The following line must be added to the start of your
-        <filename><replaceable>storage-engine</replaceable>.cc</filename>
-        file:
-      </para>
-
-<programlisting>
-#include &lt;plugins.h&gt;
-</programlisting>
-
-      <para>
-        The <filename>plugins.h</filename> file contains declarations
-        related to the MySQL plugin framework.
-      </para>
-
-      <para>
-        Additionally, the following macro must be appended to your
-        <filename><replaceable>storage-engine</replaceable>.cc</filename>
-        file:
-      </para>
-
-<programlisting>
-mysql_declare_plugin
-{
-  MYSQL_STORAGE_ENGINE_PLUGIN,
-  &amp;tina_hton,
-  tina_hton.name,
-  "MySQL AB",
-  "CSV Storage Engine",
-  tina_init_func, /* Plugin Init */
-  tina_done_func  /* Plugin Deinit */
-}
-mysql_declare_plugin_end;
-</programlisting>
-
-      <para>
-        The preceding example is from the <literal>CSV</literal> storage
-        engine.
-      </para>
-
-      <para>
-        The first element in the macro declares that this plugin is a
-        storage engine. The second element is a pointer to the storage
-        engine's
-        <link
-        linkend="custom-engine-handlerton">handlerton</link>.
-        The third element is the name of the plugin. The fourth element
-        is the author of the plugin. The fifth element is a description
-        of the plugin.
-      </para>
-
-      <para>
-        The <function>init</function> function performs any static
-        initialization required for the plugin, such as creating mutexes
-        and other internal structures.
-      </para>
-
-      <para>
-        The <function>done</function> function is used to free all
-        resources used by the plugin.
-      </para>
-
-      <para>
-        The storage engine should have a <function>panic</function>
-        function declared in its
-        <link linkend="custom-engine-handlerton">handlerton</link>. Upon
-        shutdown of <literal>mysqld</literal>, the panic function is
-        usually passed an argument of value
-        <literal>HA_PANIC_CLOSE</literal>, where the storage engine
-        should close all open tables. However, if the storage engine is
-        a pluggable, and the user attempts to un-install a storage
-        engine at runtime, the value of the panic argument will be
-        <literal>HA_PANIC_TRY_CLOSE</literal>. If the storage engine has
-        any open handler instances, it should return a nonzero fail
-        value, otherwise it should close all files and perform any
-        necessary cleanup.
-      </para>
-
-      <para>
-        In the case of a pluggable storage engine, returning a nonzero
-        value from the handlerton <function>init</function> function
-        does not prevent the storage engine shared library from being
-        loaded -- only the failure of the plugin
-        <function>init</function> function can prevent loading. However,
-        if the handlerton <function>init</function> function returns
-        failure, then the storage engine will be installed in the
-        <literal>DISABLED</literal> state.
-      </para>
-
-    </section>
-
-    <section id="custom-engine-build-makefile">
-
-      <title>Creating a Makefile to Build a Custom Storage Engine</title>
-
-      <para>
-        A <filename>Makefile.am</filename> file can be created for your
-        custom storage engine using <command>Libtool</command>. The
-        following sample Makefile is for the pluggable version of the
-        <literal>CSV</literal> engine:
-      </para>
-
-<programlisting>
-MYSQLDATAdir =          $(localstatedir)
-MYSQLSHAREdir =         $(pkgdatadir)
-MYSQLBASEdir=           $(prefix)
-MYSQLLIBdir=            $(pkglibdir)
-INCLUDES =              -I$(top_srcdir)/include \
-                        -I$(top_srcdir)/regex \
-                        -I$(top_srcdir)/sql \
-                        -I$(srcdir)
-WRAPLIBS=
-
-lib_LTLIBRARIES =       libhacsv.la
-
-libhacsv_la_SOURCES =   ha_tina.cc
-
-LDADD =
-
-DEFS =                  -DMYSQL_SERVER @DEFS@
-
-# Don't update the files from bitkeeper %::SCCS/s.%
-</programlisting>
-
-    </section>
-
-    <section id="custom-engine-build-buildobject">
-
-      <title>Building a Shared Object</title>
-
-      <para>
-        Once the Makefile is created, use the following steps to build a
-        pluggable shared object:
-      </para>
-
-      <orderedlist>
-
-        <listitem>
-          <para>
-            Navigate to the directory containing
-            <filename>Makefile.am</filename>.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            Type <command>make</command> to compile the shared object.
-          </para>
-        </listitem>
-
-        <listitem>
-          <para>
-            Type <command>make install</command> to install the shared
-            object into the MySQL server's library directory.
-          </para>
-        </listitem>
-
-      </orderedlist>
-
-    </section>
-
-    <section id="custom-engine-install">
-
-      <title>Installing a Custom Storage Engine</title>
-
-      <para>
-        Once your storage engine is built, ensure the
-        <filename>.so</filename> file is in the MySQL server library
-        directory (typically <filename>installdir/lib</filename>).
-      </para>
-
-      <para>
-        To install the plugin, issue the <literal>INSTALL
-        PLUGIN</literal> command:
-      </para>
-
-<programlisting>
-INSTALL PLUGIN <replaceable>ha_foo</replaceable> SONAME
-  '<replaceable>ha_foo.so</replaceable>';
-</programlisting>
-
-    </section>
-
-    <section id="custom-engine-uninstall">
-
-      <title>Uninstalling a Custom Storage Engine</title>
-
-      <para>
-        To uninstall a storage engine, use the <literal>UNINSTALL
-        PLUGIN</literal> statement:
-      </para>
-
-<programlisting>
-UNINSTALL PLUGIN <replaceable>ha_foo</replaceable>;
-</programlisting>
-
-      <para>
-        If you uninstall a storage engine that is being used by existing
-        tables, those tables will not be accessible, but will still be
-        present on disk (where applicable). Ensure that there are no
-        tables using a given storage engine before uninstalling it
-        otherwise the table will be inaccessible unless you re-install
-        the storage engine.
-      </para>
-
-    </section>
-
-    <section id="custom-engine-testing">
-
-      <title>Testing a Custom Storage Engine</title>
-
-      <para>
-        The MySQL AB development team follows a test-driven approach for
-        storage engine development: as functionality is developed and
-        bugs are fixed, new tests are added to an extensive regression
-        testing suite to ensure that new functionality works properly
-        and old bugs are not re-introduced.
-      </para>
-
-      <para>
-        Developers of custom storage engines can use the same regression
-        test suite to ensure the reliable operation of their storage
-        engine.
-      </para>
-
-      <para>
-        For more information on the MySQL Test Suite, see
-        <xref linkend="mysql-test-suite"/>.
-      </para>
-
-      <section id="custom-engine-testing-testrun">
-
-        <title>Running the Regression Test Suite</title>
-
-        <para>
-          To run the test suite follow these steps:
-        </para>
-
-        <orderedlist>
-
-          <listitem>
-            <para>
-              From the MySQL main directory tree change directory to the
-              <filename>mysql-test</filename> directory.
-            </para>
-          </listitem>
-
-          <listitem>
-            <para>
-              Run <command>perl ./mysql-test-run.pl</command>.
-            </para>
-          </listitem>
-
-        </orderedlist>
-
-        <para>
-          Running the script without options executes the complete test
-          suite on a server running on the local machine.
-        </para>
-
-        <para>
-          In order to run a subset of tests or a specific test case,
-          execute <command>perl ./mysql-test-run.pl
-          --do-test=abc</command>.This will execute all tests that start
-          with <literal>abc</literal> (<literal>abc*.test</literal>).
-        </para>
-
-        <para>
-          For a complete list of options run <command>perl
-          ./mysql-test-run.pl --help</command>.
-        </para>
-
-      </section>
-
-      <section id="custom-engine-testing-custom">
-
-        <title>Customizing Test Script for Custom Engine Use</title>
-
-        <para>
-          The existing tests in the MySQL Test Suite are typically
-          created against specific storage engines. As such, running the
-          full test suite will not result in custom storage engines
-          being tested.
-        </para>
-
-        <para>
-          To add support for your storage engine to the test suite, you
-          must first write tests against your storage engine. The
-          simplest way to do this is to take an existing test script and
-          modify the <literal>CREATE TABLE</literal> statements within
-          to use your custom engine.
-        </para>
-
-        <para>
-          Tests are located in the <filename>mysql-test/t/</filename>.
-        </para>
-
-        <para>
-          For more information on creating and modifying tests, see
-          <xref linkend="extending-mysqltest"/>.
-        </para>
-
-      </section>
-
-    </section>
-
-  </section>
-
   <section id="custom-engine-api-reference">
 
     <title>API Reference</title>

Modified: trunk/refman-5.1/manual.xml
===================================================================
--- trunk/refman-5.1/manual.xml	2006-01-17 17:13:14 UTC (rev 872)
+++ trunk/refman-5.1/manual.xml	2006-01-17 17:23:16 UTC (rev 873)
@@ -62,7 +62,8 @@
 
   <xi:include href="sql-syntax.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
 
-  <xi:include href="pluggable-storage.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+<!-- <xi:include href="pluggable-storage.xml"
+   xmlns:xi="http://www.w3.org/2001/XInclude"/> -->
 
   <xi:include href="storage-engines.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
 

Modified: trunk/refman-5.1/storage-engines.xml
===================================================================
--- trunk/refman-5.1/storage-engines.xml	2006-01-17 17:13:14 UTC (rev 872)
+++ trunk/refman-5.1/storage-engines.xml	2006-01-17 17:23:16 UTC (rev 873)
@@ -250,10 +250,10 @@
 
   </itemizedlist>
 
-  <para>
+  <!--<para>
     For assistance in choosing a storage engine, see
     <xref linkend="pluggable-storage-choosing"/>.
-  </para>
+  </para>-->
 
   <para>
     This chapter describes each of the MySQL storage engines except for

Thread
svn commit - mysqldoc@docsrva: r873 - trunk/refman-5.1mhillyer17 Jan