List:Commits« Previous MessageNext Message »
From:mhillyer Date:December 18 2005 5:19am
Subject:svn commit - mysqldoc@docsrva: r587 - branches/MikePluggable/trunk/refman-5.1 trunk/refman-5.1
View as plain text  
Author: mhillyer
Date: 2005-12-18 06:19:53 +0100 (Sun, 18 Dec 2005)
New Revision: 587

Log:
Add docs on building storage engine, testing storage engine. Also change a couple of notes in the pluggable chapter.

Modified:
   branches/MikePluggable/trunk/refman-5.1/custom-engine.xml
   trunk/refman-5.1/pluggable-storage.xml

Modified: branches/MikePluggable/trunk/refman-5.1/custom-engine.xml
===================================================================
--- branches/MikePluggable/trunk/refman-5.1/custom-engine.xml	2005-12-18 00:35:15 UTC (rev 586)
+++ branches/MikePluggable/trunk/refman-5.1/custom-engine.xml	2005-12-18 05:19:53 UTC (rev 587)
@@ -2888,6 +2888,343 @@
 
   </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/pluggable-storage.xml
===================================================================
--- trunk/refman-5.1/pluggable-storage.xml	2005-12-18 00:35:15 UTC (rev 586)
+++ trunk/refman-5.1/pluggable-storage.xml	2005-12-18 05:19:53 UTC (rev 587)
@@ -1,13 +1,13 @@
 <?xml version='1.0' encoding='utf-8'?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-                      "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
-[
-    <!ENTITY % fixedchars.entities     SYSTEM "../refman-common/fixedchars.ent">
-    %fixedchars.entities;
-    <!ENTITY % title.entities          SYSTEM "../refman-common/titles.en.ent">
-    %title.entities;
-    <!ENTITY % versions.entities       SYSTEM "versions.ent">
-    %versions.entities;
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+                      "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+    <!ENTITY % fixedchars.entities     SYSTEM "../refman-common/fixedchars.ent">
+    %fixedchars.entities;
+    <!ENTITY % title.entities          SYSTEM "../refman-common/titles.en.ent">
+    %title.entities;
+    <!ENTITY % versions.entities       SYSTEM "versions.ent">
+    %versions.entities;
     ]>
 <chapter id="pluggable-storage">
 
@@ -357,10 +357,10 @@
       <literal>ENGINE</literal> parameter:
     </para>
 
-<programlisting>
-CREATE TABLE engineTest(
-id INT
-) ENGINE = MyISAM;
+<programlisting>
+CREATE TABLE engineTest(
+id INT
+) ENGINE = MyISAM;
 </programlisting>
 
     <para>
@@ -368,8 +368,8 @@
       <literal>ALTER TABLE</literal> statement:
     </para>
 
-<programlisting>
-ALTER TABLE <replaceable>engineTest</replaceable> ENGINE = <replaceable>ARCHIVE</replaceable>;
+<programlisting>
+ALTER TABLE <replaceable>engineTest</replaceable> ENGINE = <replaceable>ARCHIVE</replaceable>;
 </programlisting>
 
   </section>
@@ -421,8 +421,8 @@
       engine you would first load the ha_example.so module:
     </para>
 
-<programlisting>
-INSTALL PLUGIN <replaceable>ha_example</replaceable> SONAME '<replaceable>ha_example.so</replaceable>';
+<programlisting>
+INSTALL PLUGIN <replaceable>ha_example</replaceable> SONAME '<replaceable>ha_example.so</replaceable>';
 </programlisting>
 
     <para>
@@ -442,13 +442,14 @@
       PLUGIN</literal> statement:
     </para>
 
-<programlisting>
-UNINSTALL PLUGIN <replaceable>ha_example</replaceable>;
+<programlisting>
+UNINSTALL PLUGIN <replaceable>ha_example</replaceable>;
 </programlisting>
 
     <para>
       If you unplug a storage engine that is being used by existing
-      tables, those tables will not be accessible. Ensure that there are
+      tables, those tables will not be accessible, but will still be
+      present on disk (where applicable). Ensure that there are
       no tables using a storage engine before you unplug the storage
       engine.
     </para>

Thread
svn commit - mysqldoc@docsrva: r587 - branches/MikePluggable/trunk/refman-5.1 trunk/refman-5.1mhillyer18 Dec