Author: paul
Date: 2006-06-05 22:16:25 +0200 (Mon, 05 Jun 2006)
New Revision: 2281
Log:
r10281@polar: paul | 2006-06-05 14:29:36 -0500
Put mysql-test-run.pl in the ascendancy over mysql-test-run as of MySQL 5.1.
Modified:
trunk/
trunk/mysqltest/introduction.xml
trunk/mysqltest/programs.xml
trunk/mysqltest/tutorial.xml
Property changes on: trunk
___________________________________________________________________
Name: svk:merge
- 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:10280
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:10980
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:7663
+ 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:10281
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:10980
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:7663
Modified: trunk/mysqltest/introduction.xml
===================================================================
--- trunk/mysqltest/introduction.xml 2006-06-05 20:15:44 UTC (rev 2280)
+++ trunk/mysqltest/introduction.xml 2006-06-05 20:16:25 UTC (rev 2281)
@@ -27,19 +27,27 @@
<para>
The application that runs the test suite is named
- <command>mysql-test-run</command>. Its location is the
+ <command>mysql-test-run.pl</command>. Its location is the
<filename>mysql-test</filename> directory, which is present both in
- source and binary MySQL Server distributions. (Note: The
- <command>mysql-test-run</command> shell script is being replaced by
- the <command>mysql-test-run.pl</command> Perl script, which
- currently is under development.)
+ source and binary MySQL Server distributions.
</para>
<para>
- The <command>mysql-test-run</command> application starts MySQL
+ <emphasis role="bold">Note</emphasis>: There are actually two
+ scripts for running the test suite.
+ <command>mysql-test-run</command> is the original shell script and
+ <command>mysql-test-run.pl</command> is the corresponding Perl
+ script. From MySQL 5.1 on, <command>mysql-test-run.pl</command> is
+ the preferred script and is, in general, the script name used in
+ discussion and examples. If you are running MySQL 5.0 or earlier,
+ substitute <command>mysql-test-run</command> appropriately.
+ </para>
+
+ <para>
+ The <command>mysql-test-run.pl</command> application starts MySQL
servers, restarts them as necessary when a specific test case needs
different start arguments, and presents the test result. For each
- test case, <command>mysql-test-run</command> invokes the
+ test case, <command>mysql-test-run.pl</command> invokes the
<command>mysqltest</command> program to read the test case file,
intepret the test language constructs, and send SQL statements to
the server. <command>mysqltest</command> is also referred to as the
@@ -54,8 +62,9 @@
</para>
<para>
- For a MySQL source distribution, <command>mysql-test-run</command>
- is located in the <filename>mysql-test</filename> directory, and
+ For a MySQL source distribution,
+ <command>mysql-test-run.pl</command> is located in the
+ <filename>mysql-test</filename> directory, and
<command>mysqltest</command> is located in the
<filename>client</filename> directory. The
<filename>mysql-test</filename> and <filename>client</filename>
@@ -63,8 +72,9 @@
</para>
<para>
- For a MySQL binary distribution, <command>mysql-test-run</command>
- is located in the <filename>mysql-test</filename> directory, and
+ For a MySQL binary distribution,
+ <command>mysql-test-run.pl</command> is located in the
+ <filename>mysql-test</filename> directory, and
<command>mysqltest</command> is located in the same directory where
other client programs such as <command>mysql</command> or
<command>mysqladmin</command> are installed. The locations of the
Modified: trunk/mysqltest/programs.xml
===================================================================
--- trunk/mysqltest/programs.xml 2006-06-05 20:15:44 UTC (rev 2280)
+++ trunk/mysqltest/programs.xml 2006-06-05 20:16:25 UTC (rev 2281)
@@ -7,10 +7,10 @@
<!ENTITY current-series "MySQL 5.1">
<!ENTITY title-mysqltest-for-manpage "program to run test cases">
<!ENTITY title-mysqltest-for-manual "Program to Run Test Cases">
-<!ENTITY title-mysql-test-run-for-manpage "run MySQL test suite">
-<!ENTITY title-mysql-test-run-for-manual "Run MySQL Test Suite">
<!ENTITY title-mysql-test-run-pl-for-manpage "run MySQL test suite">
<!ENTITY title-mysql-test-run-pl-for-manual "Run MySQL Test Suite">
+<!ENTITY title-mysql-test-run-for-manpage "run MySQL test suite">
+<!ENTITY title-mysql-test-run-for-manual "Run MySQL Test Suite">
<!ENTITY title-mysql-stress-test-for-manpage "server stress test program">
<!ENTITY title-mysql-stress-test-for-manual "Server Stress Test Program">
]>
@@ -38,17 +38,18 @@
<listitem>
<para>
- The <command>mysql-test-run</command> shell script is the main
- application used to run the test suite. It invokes
- <command>mysqltest</command> to run individual test cases.
+ The <command>mysql-test-run.pl</command> Perl script is the main
+ application used to run the test suite for MySQL 5.1 and up. It
+ invokes <command>mysqltest</command> to run individual test
+ cases.
</para>
</listitem>
<listitem>
<para>
- The <command>mysql-test-run.pl</command> Perl script is
- currently in development to serve as a replacement for
- <command>mysql-test-run</command>.
+ The <command>mysql-test-run</command> shell script is the main
+ application used to run the test suite before MySQL 5.1.
+ (<command>mysql-test-run.pl</command> is preferred as of 5.1.)
</para>
</listitem>
@@ -112,7 +113,7 @@
a result file. This program reads input written in a special
test language. Typically, you invoke
<command>mysqltest</command> via
- <command>mysql-test-run</command> rather than invoking it
+ <command>mysql-test-run.pl</command> rather than invoking it
directly.
</para>
@@ -1073,6 +1074,139 @@
</section>
+ <section id="fake-id-for-mysql-test-run-pl-manpage-section-wrapper">
+
+ <title>fake title for mysql-test-run.pl manpage section wrapper</title>
+
+ <refentry id="mysql-test-run-pl">
+
+ <indexterm>
+ <primary><command>mysql-test-run.pl</command></primary>
+ </indexterm>
+
+ <refmeta>
+ <refentrytitle><command>mysql-test-run.pl</command></refentrytitle>
+
+ <manvolnum>1</manvolnum>
+ <refmiscinfo class="manual">MySQL Database System</refmiscinfo>
+ <refmiscinfo class="source">MySQL</refmiscinfo>
+ <refmiscinfo class="version">¤t-series;</refmiscinfo>
+ <refmiscinfo class="refman">&title-mysql-test-run-pl-for-manual;</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+ <refname>mysql-test-run.pl</refname>
+
+ <refpurpose>&title-mysql-test-run-pl-for-manpage;</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <cmdsynopsis>
+ <command>mysql-test-run.pl [<replaceable>options</replaceable>]</command>
+ </cmdsynopsis>
+ </refsynopsisdiv>
+
+ <refsection id="mysql-test-run-pl-description">
+
+ <title>Description</title>
+
+ <para>
+ The <command>mysql-test-run.pl</command> Perl script is the
+ main application used to run the test suite for MySQL 5.1 and
+ up. It invokes <command>mysqltest</command> to run individual
+ test cases. (Prior to MySQL 5.1,
+ <command>mysql-test-run</command> can be used instead.)
+ </para>
+
+ <para>
+ Invoke <command>mysql-test-run.pl</command> in the
+ <filename>mysql-test</filename> directory like this:
+ </para>
+
+<programlisting>
+shell> <userinput>mysql-test-run.pl [<replaceable>options</replaceable>] [<replaceable>test_name</replaceable>] ...</userinput>
+</programlisting>
+
+ </refsection>
+
+ <refsection id="mysql-test-run-pl-options">
+
+ <title><command>mysql-test-run.pl</command> Options</title>
+
+ <para>
+ [Because the options for the Perl script are so similar to
+ those for the shell script, just describe here by referring to
+ the option list for <command>mysql-test-run</command>, and
+ note which options have been dropped and which added in
+ <command>mysql-test-run.pl</command>.
+ </para>
+
+ <para>
+ <command>mysql-test-run.pl</command> supports the following
+ options:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>help option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>help option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--help</option>
+ </para>
+
+ <para>
+ Display a help message and exit.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <indexterm>
+ <primary>mysql-test-run.pl</primary>
+ <secondary>ssl option</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>ssl option</primary>
+ <secondary>mysql-test-run.pl</secondary>
+ </indexterm>
+
+ <option>--ssl</option>
+ </para>
+
+ <para>
+ If <command>mysql-test-run.pl</command> is started with
+ the <option>--ssl</option> option, it sets up a secure
+ conection for all test cases. In this case, if
+ <command>mysqld</command> does not support SSL,
+ <command>mysql-test-run.pl</command> exits with an error
+ message: <literal>Couldn't find support for SSL</literal>
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ [Fill in this section with all
+ <command>mysql-test-run.pl</command> options that
+ <command>mysql-test-run</command> does not have]
+ </para>
+
+ </refsection>
+
+ </refentry>
+
+ </section>
+
<section id="fake-id-for-mysql-test-run-manpage-section-wrapper">
<title>fake title for mysql-test-run manpage section wrapper</title>
@@ -1110,24 +1244,18 @@
<title>Description</title>
<para>
- <command>mysql-test-run</command> is the main application that
- is used to run the test suite. It invokes
- <command>mysqltest</command> to run individual test cases.
+ The <command>mysql-test-run</command> shell script is the main
+ application used to run the test suite before MySQL 5.1. It
+ invokes <command>mysqltest</command> to run individual test
+ cases. (<command>mysql-test-run.pl</command> is preferred as
+ of 5.1.)
</para>
<para>
<command>mysql-test-run</command> is a shell script, so it
- does not run on Windows. A replacement script
- (<command>mysql-test-run.pl</command>) is being developed that
- is written in Perl and therefore has better cross-platform
- portability. You can substitute
- <command>mysql-test-run.pl</command> for
- <command>mysql-test-run</command> whenever you see the latter
- in this document, but <command>mysql-test-run.pl</command>
- should still be considered experimental.
- <command>mysql-test-run.pl</command> will be the only script
- available as of MySQL 5.2. [Q: Perhaps this replacement will
- occur earlier]
+ does not run on Windows. The replacement script
+ (<command>mysql-test-run.pl</command>) is written in Perl and
+ therefore has better cross-platform portability.
</para>
<para>
@@ -2699,137 +2827,6 @@
</section>
- <section id="fake-id-for-mysql-test-run-pl-manpage-section-wrapper">
-
- <title>fake title for mysql-test-run.pl manpage section wrapper</title>
-
- <refentry id="mysql-test-run-pl">
-
- <indexterm>
- <primary><command>mysql-test-run.pl</command></primary>
- </indexterm>
-
- <refmeta>
- <refentrytitle><command>mysql-test-run.pl</command></refentrytitle>
-
- <manvolnum>1</manvolnum>
- <refmiscinfo class="manual">MySQL Database System</refmiscinfo>
- <refmiscinfo class="source">MySQL</refmiscinfo>
- <refmiscinfo class="version">¤t-series;</refmiscinfo>
- <refmiscinfo class="refman">&title-mysql-test-run-pl-for-manual;</refmiscinfo>
- </refmeta>
-
- <refnamediv>
- <refname>mysql-test-run.pl</refname>
-
- <refpurpose>&title-mysql-test-run-pl-for-manpage;</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <cmdsynopsis>
- <command>mysql-test-run.pl [<replaceable>options</replaceable>]</command>
- </cmdsynopsis>
- </refsynopsisdiv>
-
- <refsection id="mysql-test-run-pl-description">
-
- <title>Description</title>
-
- <para>
- The <command>mysql-test-run.pl</command> Perl script is
- currently in development to serve as a replacement for
- <command>mysql-test-run</command>.
- </para>
-
- <para>
- Invoke <command>mysql-test-run.pl</command> in the
- <filename>mysql-test</filename> directory like this:
- </para>
-
-<programlisting>
-shell> <userinput>mysql-test-run.pl [<replaceable>options</replaceable>] [<replaceable>test_name</replaceable>] ...</userinput>
-</programlisting>
-
- </refsection>
-
- <refsection id="mysql-test-run-pl-options">
-
- <title><command>mysql-test-run.pl</command> Options</title>
-
- <para>
- [Because the options for the Perl script are so similar to
- those for the shell script, just describe here by referring to
- the option list for <command>mysql-test-run</command>, and
- note which options have been dropped and which added in
- <command>mysql-test-run.pl</command>.
- </para>
-
- <para>
- <command>mysql-test-run.pl</command> supports the following
- options:
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- <indexterm>
- <primary>mysql-test-run.pl</primary>
- <secondary>help option</secondary>
- </indexterm>
-
- <indexterm>
- <primary>help option</primary>
- <secondary>mysql-test-run.pl</secondary>
- </indexterm>
-
- <option>--help</option>
- </para>
-
- <para>
- Display a help message and exit.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <indexterm>
- <primary>mysql-test-run.pl</primary>
- <secondary>ssl option</secondary>
- </indexterm>
-
- <indexterm>
- <primary>ssl option</primary>
- <secondary>mysql-test-run.pl</secondary>
- </indexterm>
-
- <option>--ssl</option>
- </para>
-
- <para>
- If <command>mysql-test-run.pl</command> is started with
- the <option>--ssl</option> option, it sets up a secure
- conection for all test cases. In this case, if
- <command>mysqld</command> does not support SSL,
- <command>mysql-test-run.pl</command> exits with an error
- message: <literal>Couldn't find support for SSL</literal>
- </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- [Fill in this section with all
- <command>mysql-test-run.pl</command> options that
- <command>mysql-test-run</command> does not have]
- </para>
-
- </refsection>
-
- </refentry>
-
- </section>
-
<section id="fake-id-for-mysql-stress-test-manpage-section-wrapper">
<title>fake title for mysql-stress-test.pl manpage section wrapper</title>
Modified: trunk/mysqltest/tutorial.xml
===================================================================
--- trunk/mysqltest/tutorial.xml 2006-06-05 20:15:44 UTC (rev 2280)
+++ trunk/mysqltest/tutorial.xml 2006-06-05 20:16:25 UTC (rev 2281)
@@ -39,39 +39,39 @@
root of the source tree. In a binary distribution, the location of
<filename>mysql-test</filename> depends on the distribution
layout. The program that runs the test suite,
- <command>mysql-test-run</command>, will figure out whether you are
- in a source tree or an installed directory tree.
+ <command>mysql-test-run.pl</command>, will figure out whether you
+ are in a source tree or an installed directory tree.
</para>
<para>
To run the test suite, change location into your
<filename>mysql-test</filename> directory and invoke the
- <command>mysql-test-run</command> script:
+ <command>mysql-test-run.pl</command> script:
</para>
<programlisting>
shell> <userinput>cd mysql-test</userinput>
-shell> <userinput>./mysql-test-run</userinput>
+shell> <userinput>./mysql-test-run.pl</userinput>
</programlisting>
<para>
- <command>mysql-test-run</command> accepts options on the command
- line. For example:
+ <command>mysql-test-run.pl</command> accepts options on the
+ command line. For example:
</para>
<programlisting>
-shell> <userinput>./mysql-test-run --force --local</userinput>
+shell> <userinput>./mysql-test-run.pl --force --local</userinput>
</programlisting>
<para>
- By default, <command>mysql-test-run</command> exits if a test case
- fails. <option>--force</option> causes execution to continue
+ By default, <command>mysql-test-run.pl</command> exits if a test
+ case fails. <option>--force</option> causes execution to continue
regardless of test case failure.
</para>
<para>
The <option>--local</option> option tells
- <command>mysql-test-run</command> not to use an already running
+ <command>mysql-test-run.pl</command> not to use an already running
server, but to start a server itself to use for the tests. This
option is the default as of MySQL 4.1, so it is necessary only
before 4.1.
@@ -79,7 +79,7 @@
<para>
For a full list of the supported options, see
- <xref linkend="mysql-test-run"/>.
+ <xref linkend="mysql-test-run-pl"/>.
</para>
<para>
@@ -88,14 +88,14 @@
where <replaceable>test_name</replaceable> is the name of the test
case. Each name should be the test case name, not the full test
case filename. To run one or more specific test cases, name them
- on the <command>mysql-test-run</command> command line. (You do not
- specify the full test case filename.) The following command runs
- the test case named <literal>rpl_abcd</literal>, which has a test
- file of <filename>t/rpl_abcd.test</filename>:
+ on the <command>mysql-test-run.pl</command> command line. (You do
+ not specify the full test case filename.) The following command
+ runs the test case named <literal>rpl_abcd</literal>, which has a
+ test file of <filename>t/rpl_abcd.test</filename>:
</para>
<programlisting>
-shell> <userinput>./mysql-test-run rpl_abcd</userinput>
+shell> <userinput>./mysql-test-run.pl rpl_abcd</userinput>
</programlisting>
<para>
@@ -104,7 +104,7 @@
</para>
<programlisting>
-shell> <userinput>./mysql-test-run --do-test=<replaceable>prefix</replaceable></userinput>
+shell> <userinput>./mysql-test-run.pl --do-test=<replaceable>prefix</replaceable></userinput>
</programlisting>
<para>
@@ -114,11 +114,11 @@
</para>
<programlisting>
-shell> <userinput>./mysql-test-run --do-tests=rpl</userinput>
+shell> <userinput>./mysql-test-run.pl --do-tests=rpl</userinput>
</programlisting>
<para>
- <command>mysql-test-run</command> starts the MySQL server if
+ <command>mysql-test-run.pl</command> starts the MySQL server if
necessary, sets up the environment for calling the
<command>mysqltest</command> program, and invokes
<command>mysqltest</command> to run the test case. For each test
@@ -140,11 +140,11 @@
<para>
You need not start a MySQL server first before running tests.
- Instead, the <command>mysql-test-run</command> program will start
- the server or servers needed on ports that do not conflict with
- ports used a production server, if you happen to have one on the
- same machine. (The test run uses ports in the range around 9300,
- so production servers should not use ports in that range.)
+ Instead, the <command>mysql-test-run.pl</command> program will
+ start the server or servers needed on ports that do not conflict
+ with ports used a production server, if you happen to have one on
+ the same machine. (The test run uses ports in the range around
+ 9300, so production servers should not use ports in that range.)
</para>
<section id="tutorial-simultaneous-test-runs">
@@ -154,19 +154,20 @@
<para>
If you have multiple users that run tests simultaneously on the
same machine, you must specify to the
- <command>mysql-test-run</command> program which ports to user so
- that no test run conflicts with others running concurrently. You
- add unique port arguments to <command>mysql-test-run</command>,
- such as <option>--no-manager --master_port=3911
+ <command>mysql-test-run.pl</command> program which ports to user
+ so that no test run conflicts with others running concurrently.
+ You add unique port arguments to
+ <command>mysql-test-run.pl</command>, such as
+ <option>--no-manager --master_port=3911
--slave_port=3927</option>.
</para>
<para>
- Only one person can run the <command>mysql-test-run</command>
+ Only one person can run the <command>mysql-test-run.pl</command>
program in the same <filename>mysql-test</filename> directory on
a shared drive, at the same time. The
<filename>mysql-test/var</filename> directory created and used
- by <command>mysql-test-run</command> cannot be shared between
+ by <command>mysql-test-run.pl</command> cannot be shared between
simultaneous test runs. A test run can use the
<option>--var=<replaceable>dir_path</replaceable></option>
option to specify an alternate directory not used by other runs.
@@ -250,7 +251,7 @@
</para>
<programlisting>
-shell> <userinput>./mysql-test-run <replaceable>test_name</replaceable></userinput>
+shell> <userinput>./mysql-test-run.pl <replaceable>test_name</replaceable></userinput>
</programlisting>
</listitem>
@@ -271,7 +272,7 @@
<para>
Another way to create the result file is by invoking
- <command>mysql-test-run</command> with the
+ <command>mysql-test-run.pl</command> with the
<option>--record</option> option to record the test output in
the result file:
</para>
@@ -287,7 +288,7 @@
</para>
<programlisting>
-shell> <userinput>./mysql-test-run <replaceable>test_name</replaceable></userinput>
+shell> <userinput>./mysql-test-run.pl <replaceable>test_name</replaceable></userinput>
</programlisting>
<para>
@@ -296,7 +297,7 @@
</para>
<programlisting>
-shell> <userinput>./mysql-test-run</userinput>
+shell> <userinput>./mysql-test-run.pl</userinput>
</programlisting>
</listitem>
@@ -641,7 +642,7 @@
<programlisting>
shell> <userinput>cd mysql-test</userinput>
-shell> <userinput>./mysql-test-run --record foo</userinput>
+shell> <userinput>./mysql-test-run.pl --record foo</userinput>
</programlisting>
<para>
@@ -837,7 +838,7 @@
<para>
After rerunning the test by invoking
- <command>mysql-test-run</command> with the
+ <command>mysql-test-run.pl</command> with the
<option>--record</option> option to record the new result, the
result file will contain more information:
</para>
@@ -964,13 +965,13 @@
</para>
<programlisting>
-shell> <userinput>./mysql-test-run --record foo</userinput>
-shell> <userinput>./mysql-test-run foo</userinput>
+shell> <userinput>./mysql-test-run.pl --record foo</userinput>
+shell> <userinput>./mysql-test-run.pl foo</userinput>
</programlisting>
<para>
Most likely, a failure will occur and
- <command>mysql-test-run</command> will display the difference
+ <command>mysql-test-run.pl</command> will display the difference
between the expected result and what we actually got, like this:
</para>
@@ -1085,12 +1086,12 @@
<para>
If a file exists named
<filename>t/<replaceable>test_name</replaceable>-master.opt</filename>,
- <command>mysql-test-run</command> examines it for extra options
- that the server needs to be run with when executing the
+ <command>mysql-test-run.pl</command> examines it for extra
+ options that the server needs to be run with when executing the
<replaceable>test_name</replaceable> test case. If no server has
yet been started or the current server is running with different
- options, <command>mysql-test-run</command> restarts the server
- with the new options.
+ options, <command>mysql-test-run.pl</command> restarts the
+ server with the new options.
</para>
<para>
@@ -1119,7 +1120,7 @@
in the form of extra command-line options. You can specify these
options in a file named
<filename>mysql-test/t/<replaceable>test_name</replaceable>-master.opt</filename>.
- <command>mysql-test-run</command> checks these
+ <command>mysql-test-run.pl</command> checks these
<filename>.opt</filename> files and restarts the server if a
test case requires different options than the previous test
case.
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r2281 - in trunk: . mysqltest | paul | 5 Jun |
