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 <plugins.h>
+</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,
+ &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 <plugins.h>
-</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,
- &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.1 | mhillyer | 17 Jan |
