Author: paul
Date: 2006-06-02 21:33:41 +0200 (Fri, 02 Jun 2006)
New Revision: 2260
Log:
r7747@kite-hub: paul | 2006-06-02 14:32:30 -0500
Document configure support for plugins (WL#3201)
- configure command-line options
- autotools macros that control plugin support
Modified:
trunk/
trunk/internals/internals.xml
Property changes on: trunk
___________________________________________________________________
Name: svk:merge
- 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:10205
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:10895
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:7746
+ 4767c598-dc10-0410-bea0-d01b485662eb:/mysqldoc-local/mysqldoc/trunk:10205
b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:10895
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:7747
Modified: trunk/internals/internals.xml
===================================================================
--- trunk/internals/internals.xml 2006-06-02 19:33:10 UTC (rev 2259)
+++ trunk/internals/internals.xml 2006-06-02 19:33:41 UTC (rev 2260)
@@ -82,7 +82,7 @@
<para>
We want to download the latest, the very latest, version of the
MySQL server. So we won't click <quote>Downloads</quote> on the
- MySQL Developer Zone page --- that's usually a few weeks old.
+ MySQL Developer Zone page — that's usually a few weeks old.
Instead we'll get BitKeeper (tm), which is a revision control
package, vaguely like CVS or Perforce. This is what MySQL's
developers use every day, so what we download with BitKeeper is
@@ -359,7 +359,7 @@
<para>
There are debuggers for Windows and other operating systems, of
- course --- don't feel left out just because we're mentioning a
+ course — don't feel left out just because we're mentioning a
Linux tool name! But it happens that we do a lot of things with
Linux ourselves, so we happen to know what to say. To debug the
mysqld server, say:
@@ -465,11 +465,11 @@
<para>
It has the source code of many of your familiar favorites, like
mysql, which everybody has used to connect to the MySQL server at
- one time or another. There are other utilities too --- in fact,
- you'll find the source of most client-side programs here. There
- are also programs for checking the password, and for testing that
- basic functions --- such as threading or access via SSL --- are
- possible.
+ one time or another. There are other utilities too — in
+ fact, you'll find the source of most client-side programs here.
+ There are also programs for checking the password, and for testing
+ that basic functions — such as threading or access via SSL
+ — are possible.
</para>
<para>
@@ -652,10 +652,10 @@
<para>
To sum up: (1) The myisam directory is where you'll find programs
for handling files, rows, and keys. You won't find programs for
- handling columns --- we'll get to them a bit later. (2) The myisam
- directory is just one of the handler directories. The programs in
- the other storage engine directories fulfill about the same
- functions.
+ handling columns — we'll get to them a bit later. (2) The
+ myisam directory is just one of the handler directories. The
+ programs in the other storage engine directories fulfill about the
+ same functions.
</para>
<para>
@@ -867,10 +867,10 @@
</programlisting>
<para>
- The diagram is very simplified --- it's a caricature that distorts
- important things, but remember that we've only discussed seven
- major directories so far: Docs, BUILD, and the five that you see
- here.
+ The diagram is very simplified — it's a caricature that
+ distorts important things, but remember that we've only discussed
+ seven major directories so far: Docs, BUILD, and the five that you
+ see here.
</para>
<para>
@@ -897,7 +897,7 @@
<para>
Finally, one of the ha (handler) programs in the sql directory
will dispatch to an appropriate handler for storage. In this case
- we've assumed, as before, that the handler is myisam --- so a
+ we've assumed, as before, that the handler is myisam — so a
myisam-directory program is involved. Specifically, that program
is mi_write.c, as we mentioned earlier.
</para>
@@ -924,10 +924,10 @@
</programlisting>
<para>
- Now it's time to reveal a startling fact, which is --- we didn't
- write all of the source code in all of the source code directories
- all by ourselves. This list is, in a sense, a tribute to the idea
- of open source.
+ Now it's time to reveal a startling fact, which is — we
+ didn't write all of the source code in all of the source code
+ directories all by ourselves. This list is, in a sense, a tribute
+ to the idea of open source.
</para>
<para>
@@ -983,8 +983,9 @@
Let's go through the idea of storage engines once more, this time
with a list of all the storage engines, both the ones that we
produce, and the ones that others produce. We've already mentioned
- the internal ones --- so now we'll remark on the directories of
- the two common external storage engines --- BDB and innobase.
+ the internal ones — so now we'll remark on the directories
+ of the two common external storage engines — BDB and
+ innobase.
</para>
<para>
@@ -1050,8 +1051,8 @@
<para>
Finally, for the sake of completeness, we'll put up a list of the
- rest of the directories --- those that we haven't had occasion to
- mention till now.
+ rest of the directories — those that we haven't had occasion
+ to mention till now.
</para>
<programlisting>
@@ -1112,7 +1113,7 @@
<para>
Now, having finished with our bird's eye view of the source code
from the air, let's take the perspective of the worms on the
- ground. (Which is another name for MySQL's developer staff ---
+ ground. (Which is another name for MySQL's developer staff —
turn on laugh track here.)
</para>
@@ -1145,8 +1146,8 @@
<para>
Here's a snippet of code from a .c file in the sql directory,
- specifically from sql_update.cc, which --- as we mentioned earlier
- -- is invoked when there's an UPDATE statement to process.
+ specifically from sql_update.cc, which — as we mentioned
+ earlier -- is invoked when there's an UPDATE statement to process.
</para>
<para>
@@ -1175,9 +1176,9 @@
is opening and locking, allocating memory in a cache, initializing
a process for reading records, reading records in a loop until the
thread is killed or there are no more to read, storing a modified
- record for the table, and --- after the loop is through ---
- possibly writing to the log. Incidentally, a transactional table
- is usually a BDB or an InnoDB table.
+ record for the table, and — after the loop is through
+ — possibly writing to the log. Incidentally, a transactional
+ table is usually a BDB or an InnoDB table.
</para>
<para>
@@ -1328,8 +1329,8 @@
request, it assigns resources which will be exclusive to that
client. In particular, the main thread will spawn a new thread
just to handle the connection. Then the main server will loop and
- listen for new connections --- but we will leave it and follow the
- new thread.
+ listen for new connections — but we will leave it and follow
+ the new thread.
</para>
<para>
@@ -1491,12 +1492,12 @@
</para>
<para>
- There will be --- we're going into list mode now and just reciting
- the rest of the items in the switch statement --- code for
- prepare, close statement, query, quit, create database, drop
- database, dump binary log, refresh, statistics, get process info,
- kill process, sleep, connect, and several minor commands. This is
- the big junction.
+ There will be — we're going into list mode now and just
+ reciting the rest of the items in the switch statement —
+ code for prepare, close statement, query, quit, create database,
+ drop database, dump binary log, refresh, statistics, get process
+ info, kill process, sleep, connect, and several minor commands.
+ This is the big junction.
</para>
<para>
@@ -1809,7 +1810,7 @@
at one of the include files. In handler.h on the sql directory, we
find that write_row is associated with a handler for a table. This
definition is telling us that the address in write_row will vary
- --- it gets filled in at run time. In fact, there are several
+ — it gets filled in at run time. In fact, there are several
possible addresses.
</para>
@@ -1991,8 +1992,9 @@
<para>
The thing to notice here is that the records are stored compactly.
- There is one byte at the start of each record --- F1 for the first
- record and F5 for the second record --- which contains a bit list.
+ There is one byte at the start of each record — F1 for the
+ first record and F5 for the second record — which contains a
+ bit list.
</para>
<para>
@@ -2030,19 +2032,19 @@
<para>
If, on the other hand, you look at an InnoDB file, you'll find
that it's got more complexities in the storage. The details are in
- the later chapters of internals.xml, remember --- and you can ask
- for more details when you go to Heikki Tuuri's presentation at the
- MySQL User conference. But here's an introductory look.
+ the later chapters of internals.xml, remember — and you can
+ ask for more details when you go to Heikki Tuuri's presentation at
+ the MySQL User conference. But here's an introductory look.
</para>
<para>
- The header here begins with offsets --- unlike MyISAM, which has
- no offsets. So you'd have to go through column 1 before getting to
- column 2.
+ The header here begins with offsets — unlike MyISAM, which
+ has no offsets. So you'd have to go through column 1 before
+ getting to column 2.
</para>
<para>
- Then there is a fixed header --- the extra bytes.
+ Then there is a fixed header — the extra bytes.
</para>
<para>
@@ -2054,8 +2056,8 @@
</para>
<para>
- And finally there are the column contents --- the string of Ps at
- the end of the snippet here. You can see that InnoDB does more
+ And finally there are the column contents — the string of Ps
+ at the end of the snippet here. You can see that InnoDB does more
administrating.
</para>
@@ -2082,7 +2084,7 @@
<para>
By packet, we mean: what's the format of a message that the client
- sends over the tcp/ip line to the server --- and what does the
+ sends over the tcp/ip line to the server — and what does the
server send back?
</para>
@@ -2147,81 +2149,107 @@
This chapter shows the guidelines that MySQL's developers follow
when writing new code. Consistent style is important for us,
because everyone must know what to expect. For example, after we
- become accustomed to seeing that everything inside an "if" is
- indented two spaces, we can glance at a listing and understand
- what's nested within what. Writing non-conforming code can be bad.
- For example, if we want to find where assignments are made to
- variable "mutex_count", we might search for "mutex_count=" with an
- editor -- and miss assignments that look like "mutex_count ="
- (with a space before the equal sign) (which is non-conforming).
- Knowing our rules, you'll find it easier to read our code, and
- when you you decide to contribute (which we hope you'll consider!)
- we'll find it easier to read your code.
+ become accustomed to seeing that everything inside an
+ <quote>if</quote> is indented two spaces, we can glance at a
+ listing and understand what's nested within what. Writing
+ non-conforming code can be bad. For example, if we want to find
+ where assignments are made to variable <quote>mutex_count</quote>,
+ we might search for <quote>mutex_count=</quote> with an editor and
+ miss assignments that look like <quote>mutex_count =</quote> with
+ a space before the equal sign (which is non-conforming). Knowing
+ our rules, you'll find it easier to read our code, and when you
+ you decide to contribute (which we hope you'll consider!) we'll
+ find it easier to read your code.
</para>
<para>
- These guidelines are for C/C++ code for the MySQL server. They do
- not necessarily apply for other projects such as MySQL Connector/J
- or MaxDB.
+ The chapter covers the following topics:
</para>
- <para>
- <emphasis role="bold">Indentation and Spacing</emphasis>
- </para>
-
<itemizedlist>
<listitem>
<para>
- Use spaces for space. Do not use tabs (\t). See the editor
- configuration tips at the end of this chapter for instructions
- on configuring a vim or emacs editor to use spaces instead of
- tabs.
+ C/C++ coding guidelines for MySQL Server
</para>
</listitem>
<listitem>
<para>
- Use line feed (\n) for line breaks. Do not use carriage return
- + line feed (\r\n); that can cause problems for other users
- and for builds. This rule is particularly important if you use
- a Windows editor.
+ <command>configure</command> support for plugins
</para>
</listitem>
- <listitem>
- <para>
- To begin indenting, add two spaces. To end indenting, subtract
- two spaces. For example:
- </para>
+ </itemizedlist>
+ <section id="coding-guidelines-c">
+
+ <title>C/C++ Coding Guidelines</title>
+
+ <para>
+ This section covers guidelines for C/C++ code for the MySQL
+ server. The guidelines do not necessarily apply for other
+ projects such as MySQL Connector/J or MaxDB.
+ </para>
+
+ <para>
+ <emphasis role="bold">Indentation and Spacing</emphasis>
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ Use spaces for space. Do not use tabs (\t). See the editor
+ configuration tips at the end of this section for
+ instructions on configuring a vim or emacs editor to use
+ spaces instead of tabs.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Use line feed (\n) for line breaks. Do not use carriage
+ return + line feed (\r\n); that can cause problems for other
+ users and for builds. This rule is particularly important if
+ you use a Windows editor.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ To begin indenting, add two spaces. To end indenting,
+ subtract two spaces. For example:
+ </para>
+
<programlisting>
- {
- code, code, code
- {
- code, code, code
- }
- }
+{
+ code, code, code
+ {
+ code, code, code
+ }
+}
</programlisting>
- </listitem>
+ </listitem>
- <listitem>
- <para>
- The maximum line width is 80 characters. If you are writing a
- longer line, try to break it at a logical point and continue
- on the next line with the same indenting. Use of backslash is
- okay; however, multi-line literals might cause less confusion
- if they are defined before the function start.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ The maximum line width is 80 characters. If you are writing
+ a longer line, try to break it at a logical point and
+ continue on the next line with the same indenting. Use of
+ backslash is okay; however, multi-line literals might cause
+ less confusion if they are defined before the function
+ start.
+ </para>
+ </listitem>
- <listitem>
- <para>
- To separate two functions, use two line breaks. To separate a
- list of variable declarations from executable statements, use
- two line breaks. To separate a function from a block of code,
- use two line breaks. For example:
- </para>
+ <listitem>
+ <para>
+ To separate two functions, use two line breaks. To separate
+ a list of variable declarations from executable statements,
+ use two line breaks. To separate a function from a block of
+ code, use two line breaks. For example:
+ </para>
<programlisting>
int function_1()
@@ -2238,66 +2266,66 @@
}
</programlisting>
- </listitem>
+ </listitem>
- <listitem>
- <para>
- Matching '<literal>{}</literal>' (left and right braces)
- should be in the same column, that is, the closing '}' should
- be directly below the opening '{'. Do not put any non-space
- characters on the same line as a brace, not even a comment.
- Indent within braces. Exception 1: after
- <literal>switch</literal> there is a different rule, see
- below. Exception 2: if there is nothing between two braces,
- i.e. '{}', they should appear together. For example:
- </para>
+ <listitem>
+ <para>
+ Matching '<literal>{}</literal>' (left and right braces)
+ should be in the same column, that is, the closing '}'
+ should be directly below the opening '{'. Do not put any
+ non-space characters on the same line as a brace, not even a
+ comment. Indent within braces. Exception 1: after
+ <literal>switch</literal> there is a different rule, see
+ below. Exception 2: if there is nothing between two braces,
+ i.e. '{}', they should appear together. For example:
+ </para>
<programlisting>
- if (code, code, code)
- {
- code, code, code;
- }
- for (code, code, code)
- {}
+if (code, code, code)
+{
+ code, code, code;
+}
+for (code, code, code)
+{}
</programlisting>
- </listitem>
+ </listitem>
- <listitem>
- <para>
- After <literal>switch</literal> use a brace on the same line,
- and do not indent the next line. For example:
- </para>
+ <listitem>
+ <para>
+ After <literal>switch</literal> use a brace on the same
+ line, and do not indent the next line. For example:
+ </para>
<programlisting>
- switch (condition) {
- code
- code
- code
- }
+switch (condition) {
+code
+code
+code
+}
</programlisting>
- </listitem>
+ </listitem>
- <listitem>
- <para>
- You may align variable declarations like this:
- </para>
+ <listitem>
+ <para>
+ You may align variable declarations like this:
+ </para>
<programlisting>
Type value;
int var2;
ulonglong var3;
</programlisting>
- </listitem>
+ </listitem>
- <listitem>
- <para>
- When assigning to a variable, put zero spaces after the target
- variable name, then the assignment operator ('=' '+=' etc.),
- then space(s). For single assignments, there should be only
- one space after the equal sign. For multiple assignments, add
- additional spaces so that the source values line up. For
- example:
- </para>
+ <listitem>
+ <para>
+ When assigning to a variable, put zero spaces after the
+ target variable name, then the assignment operator ('=' '+='
+ etc.), then space(s). For single assignments, there should
+ be only one space after the equal sign. For multiple
+ assignments, add additional spaces so that the source values
+ line up. For example:
+ </para>
<programlisting>
a/= b;
@@ -2307,23 +2335,23 @@
int new_var= 18;
</programlisting>
- <para>
- Align assignments from one structure to another, like this:
- </para>
+ <para>
+ Align assignments from one structure to another, like this:
+ </para>
<programlisting>
foo->member= bar->member;
foo->name= bar->name;
foo->name_length= bar->name_length;
</programlisting>
- </listitem>
+ </listitem>
- <listitem>
- <para>
- Put separate statements on separate lines. This applies for
- both variable declarations and executable statements. For
- example, this is wrong:
- </para>
+ <listitem>
+ <para>
+ Put separate statements on separate lines. This applies for
+ both variable declarations and executable statements. For
+ example, this is wrong:
+ </para>
<programlisting>
int x= 11; int y= 12;
@@ -2331,9 +2359,9 @@
z= x; y+= x;
</programlisting>
- <para>
- This is right:
- </para>
+ <para>
+ This is right:
+ </para>
<programlisting>
int x= 11;
@@ -2342,18 +2370,18 @@
z= x;
y+= x;
</programlisting>
- </listitem>
+ </listitem>
- <listitem>
- <para>
- Put spaces both before and after comparison operators ('>'
- '==' '>=' etc.), arithmetic operators ('+' etc.), and
- Boolean operators ('||' etc.). Do not put spaces around '++'
- or '->'. Do not put space after '*' when '*' introduces a
- pointer. Do not put spaces after '('. Put one space after ')'
- if it ends a condition, but not if it ends a list of function
- arguments. For example:
- </para>
+ <listitem>
+ <para>
+ Put spaces both before and after comparison operators
+ ('>' '==' '>=' etc.), arithmetic operators ('+' etc.),
+ and Boolean operators ('||' etc.). Do not put spaces around
+ '++' or '->'. Do not put space after '*' when '*'
+ introduces a pointer. Do not put spaces after '('. Put one
+ space after ')' if it ends a condition, but not if it ends a
+ list of function arguments. For example:
+ </para>
<programlisting>
int *var;
@@ -2361,53 +2389,53 @@
if (x == y + 2)
function_call();
</programlisting>
- </listitem>
+ </listitem>
- <listitem>
- <para>
- When a function has multiple arguments separated by commas
- ('<literal>,</literal>'), put one space after each comma. For
- example:
- </para>
+ <listitem>
+ <para>
+ When a function has multiple arguments separated by commas
+ ('<literal>,</literal>'), put one space after each comma.
+ For example:
+ </para>
<programlisting>
- ln= mysql_bin_log.generate_name(opt_bin_logname, "-bin", 1, buf);
+ln= mysql_bin_log.generate_name(opt_bin_logname, "-bin", 1, buf);
</programlisting>
- </listitem>
+ </listitem>
- <listitem>
- <para>
- Put one space after a keyword which introduces a condition,
- such as <literal>if</literal> or <literal>for</literal> or
- <literal>while</literal>.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ Put one space after a keyword which introduces a condition,
+ such as <literal>if</literal> or <literal>for</literal> or
+ <literal>while</literal>.
+ </para>
+ </listitem>
- <listitem>
- <para>
- After <literal>if</literal> or <literal>else</literal> or
- <literal>while</literal>, when there is only one instruction
- after the condition, braces are not necessary and the
- instruction goes on the next line, indented.
- </para>
+ <listitem>
+ <para>
+ After <literal>if</literal> or <literal>else</literal> or
+ <literal>while</literal>, when there is only one instruction
+ after the condition, braces are not necessary and the
+ instruction goes on the next line, indented.
+ </para>
<programlisting>
- if (sig != MYSQL_KILL_SIGNAL && sig != 0)
- unireg_abort(1);
- else
- unireg_end();
- while (*val && my_isspace(mysqld_charset, *val))
- *val++;
+if (sig != MYSQL_KILL_SIGNAL && sig != 0)
+ unireg_abort(1);
+else
+ unireg_end();
+while (*val && my_isspace(mysqld_charset, *val))
+ *val++;
</programlisting>
- </listitem>
+ </listitem>
- <listitem>
- <para>
- In function declarations and invocations: there is no space
- between function name and '('; there is no space or line break
- between '(' and the first argument; if the arguments do not
- fit on one line then align them. Examples:
- </para>
+ <listitem>
+ <para>
+ In function declarations and invocations: there is no space
+ between function name and '('; there is no space or line
+ break between '(' and the first argument; if the arguments
+ do not fit on one line then align them. Examples:
+ </para>
<programlisting>
Return_value_type *Class_name::method_name(const char *arg1,
@@ -2437,20 +2465,21 @@
Long_long_type *arg3)
</programlisting>
- <para>
- (You may but don't have to split
- <literal>Class_name::method_name</literal> into two lines.)
- </para>
+ <para>
+ (You may but don't have to split
+ <literal>Class_name::method_name</literal> into two lines.)
+ </para>
- <para>
- When arguments do not fit on one line, consider renaming them.
- </para>
- </listitem>
+ <para>
+ When arguments do not fit on one line, consider renaming
+ them.
+ </para>
+ </listitem>
- <listitem>
- <para>
- Format constructors in the following way:
- </para>
+ <listitem>
+ <para>
+ Format constructors in the following way:
+ </para>
<programlisting>
Item::Item(int a_arg, int b_arg, int c_arg)
@@ -2458,9 +2487,9 @@
{}
</programlisting>
- <para>
- But keep lines short to make them more readable:
- </para>
+ <para>
+ But keep lines short to make them more readable:
+ </para>
<programlisting>
Item::Item(int longer_arg, int more_longer_arg)
@@ -2469,105 +2498,106 @@
{}
</programlisting>
- <para>
- If a constructor can fit into one line:
- </para>
+ <para>
+ If a constructor can fit into one line:
+ </para>
<programlisting>
Item::Item(int a_arg) :a(a_arg) {}
</programlisting>
- </listitem>
+ </listitem>
- </itemizedlist>
+ </itemizedlist>
- <para>
- <emphasis role="bold">Naming Conventions</emphasis>
- </para>
+ <para>
+ <emphasis role="bold">Naming Conventions</emphasis>
+ </para>
- <itemizedlist>
+ <itemizedlist>
- <listitem>
- <para>
- For identifiers formed from multiple words, separate each
- component with underscore rather than capitalization. Thus,
- use <literal>my_var</literal> instead of
- <literal>myVar</literal> or <literal>MyVar</literal>.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ For identifiers formed from multiple words, separate each
+ component with underscore rather than capitalization. Thus,
+ use <literal>my_var</literal> instead of
+ <literal>myVar</literal> or <literal>MyVar</literal>.
+ </para>
+ </listitem>
- <listitem>
- <para>
- Avoid capitalization except for class names; class names
- should begin with a capital letter.
- </para>
+ <listitem>
+ <para>
+ Avoid capitalization except for class names; class names
+ should begin with a capital letter.
+ </para>
<programlisting>
class Item;
class Query_arena;
class Log_event;
</programlisting>
- </listitem>
+ </listitem>
- <listitem>
- <para>
- Avoid function names, structure elements, or variables that
- begin or end with '<literal>_</literal>'.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ Avoid function names, structure elements, or variables that
+ begin or end with '<literal>_</literal>'.
+ </para>
+ </listitem>
- <listitem>
- <para>
- Use long function and variable names in English. This will
- make your code easier to read for all developers.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ Use long function and variable names in English. This will
+ make your code easier to read for all developers.
+ </para>
+ </listitem>
- <listitem>
- <para>
- Structure types are <literal>typedef</literal>'ed to an
- all-upper-case identifier.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ Structure types are <literal>typedef</literal>'ed to an
+ all-upper-case identifier.
+ </para>
+ </listitem>
- <listitem>
- <para>
- All <literal>#define</literal> declarations should be in upper
- case.
- </para>
+ <listitem>
+ <para>
+ All <literal>#define</literal> declarations should be in
+ upper case.
+ </para>
<programlisting>
#define MY_CONSTANT 15
</programlisting>
- </listitem>
+ </listitem>
- <listitem>
- <para>
- Enumeration names should begin with <literal>enum_</literal>.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ Enumeration names should begin with
+ <literal>enum_</literal>.
+ </para>
+ </listitem>
- </itemizedlist>
+ </itemizedlist>
- <para>
- <emphasis role="bold">Commenting Code</emphasis>
- </para>
+ <para>
+ <emphasis role="bold">Commenting Code</emphasis>
+ </para>
- <itemizedlist>
+ <itemizedlist>
- <listitem>
- <para>
- Comment your code when you do something that someone else may
- think is not <quote>trivial</quote>.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ Comment your code when you do something that someone else
+ may think is not <quote>trivial</quote>.
+ </para>
+ </listitem>
- <listitem>
- <para>
- When writing multi-line comments: put the '/*' and '*/' on
- their own lines, put the '*/' below the '/*', put a line break
- and a two-space indent after the '/*', do not use additional
- asterisks on the left of the comment.
- </para>
+ <listitem>
+ <para>
+ When writing multi-line comments: put the '/*' and '*/' on
+ their own lines, put the '*/' below the '/*', put a line
+ break and a two-space indent after the '/*', do not use
+ additional asterisks on the left of the comment.
+ </para>
<programlisting>
/*
@@ -2578,52 +2608,52 @@
</programlisting>
<programlisting>
-/* ********* This comment is bad. It's indented wrong, it has additional
-* asterisks. Don't write this way.
+/* ********* This comment is bad. It's indented incorrectly, it has
+* additional asterisks. Don't write this way.
* *********/
</programlisting>
- </listitem>
+ </listitem>
- <listitem>
- <para>
- When writing single-line comments, the '/*' and '*/" are on
- the same line. For example:
- </para>
+ <listitem>
+ <para>
+ When writing single-line comments, the '/*' and '*/" are on
+ the same line. For example:
+ </para>
<programlisting>
- /* We must check if stack_size = 0 as Solaris 2.9 can return 0 here */
+/* We must check if stack_size = 0 as Solaris 2.9 can return 0 here */
</programlisting>
- </listitem>
+ </listitem>
- <listitem>
- <para>
- For a short comment at the end of a line, you may use either
- /* ... */ or a <literal>//</literal> double slash. In C files
- or in header files used by C files, avoid
- <literal>//</literal> comments.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ For a short comment at the end of a line, you may use either
+ /* ... */ or a <literal>//</literal> double slash. In C
+ files or in header files used by C files, avoid
+ <literal>//</literal> comments.
+ </para>
+ </listitem>
- <listitem>
- <para>
- Align short side <literal>//</literal> or /* ... */ comments
- by 48 column (start the comment in column 49).
- </para>
+ <listitem>
+ <para>
+ Align short side <literal>//</literal> or /* ... */ comments
+ by 48 column (start the comment in column 49).
+ </para>
<programlisting>
- {
- qc*= 2; /* double the estimation */
- }
+{
+ qc*= 2; /* double the estimation */
+}
</programlisting>
- </listitem>
+ </listitem>
- <listitem>
- <para>
- When commenting members of a structure or a class , align
- comments by 48th column. If a comment doesn't fit into one
- line, move it to a separate line. Do not create multiline
- comments aligned by 48th column.
- </para>
+ <listitem>
+ <para>
+ When commenting members of a structure or a class , align
+ comments by 48th column. If a comment doesn't fit into one
+ line, move it to a separate line. Do not create multiline
+ comments aligned by 48th column.
+ </para>
<programlisting>
struct st_mysql_stmt
@@ -2641,22 +2671,23 @@
...
};
</programlisting>
- </listitem>
+ </listitem>
- <listitem>
- <para>
- Function comments are important! When commenting a function,
- note the IN parameters (the word IN is implicit).
- </para>
+ <listitem>
+ <para>
+ Function comments are important! When commenting a function,
+ note the IN parameters (the word IN is implicit).
+ </para>
- <para>
- Every function should have a description unless the function
- is very short and its purpose is obvious.
- </para>
+ <para>
+ Every function should have a description unless the function
+ is very short and its purpose is obvious.
+ </para>
- <para>
- Use the following example as a template for function comments:
- </para>
+ <para>
+ Use the following example as a template for function
+ comments:
+ </para>
<programlisting>
/*
@@ -2678,26 +2709,25 @@
int sha1_reset(SHA1_CONTEXT *context)
{
...
-
</programlisting>
- <para>
- Additional sections can be used: WARNING, NOTES, TODO, SEE
- ALSO, ERRORS, REFERENCED BY.
- </para>
- </listitem>
+ <para>
+ Additional sections can be used: WARNING, NOTES, TODO, SEE
+ ALSO, ERRORS, REFERENCED BY.
+ </para>
+ </listitem>
- <listitem>
- <para>
- All comments should be in English.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ All comments should be in English.
+ </para>
+ </listitem>
- <listitem>
- <para>
- Put a line break between a function comment and its
- description.
- </para>
+ <listitem>
+ <para>
+ Put a line break between a function comment and its
+ description.
+ </para>
<programlisting>
/*
@@ -2707,220 +2737,223 @@
int my_function()
</programlisting>
- </listitem>
+ </listitem>
- </itemizedlist>
+ </itemizedlist>
- <para>
- <emphasis role="bold">General Development Guidelines</emphasis>
- </para>
+ <para>
+ <emphasis role="bold">General Development Guidelines</emphasis>
+ </para>
- <itemizedlist>
+ <itemizedlist>
- <listitem>
- <para>
- We use
- <ulink url="http://www.bitkeeper.com/">BitKeeper</ulink> for
- source management. Bitkeeper can be downloaded from
- <ulink
+ <listitem>
+ <para>
+ We use
+ <ulink url="http://www.bitkeeper.com/">BitKeeper</ulink> for
+ source management. Bitkeeper can be downloaded from
+ <ulink
url="http://www.bitmover.com/cgi-bin/download.cgi"/>
- </para>
- </listitem>
+ </para>
+ </listitem>
- <listitem>
- <para>
- You should use the MySQL 5.0 source for all new developments.
- The public 5.0 development branch can be downloaded with
- <literal>shell> bk clone bk://mysql.bkbits.net/mysql-5.0
- mysql-5.0</literal>
- </para>
- </listitem>
+ <listitem>
+ <para>
+ You should use the MySQL 5.0 source for all new
+ developments. The public 5.0 development branch can be
+ downloaded with <literal>shell> bk clone
+ bk://mysql.bkbits.net/mysql-5.0 mysql-5.0</literal>
+ </para>
+ </listitem>
- <listitem>
- <para>
- If you have any questions about the MySQL source, you can post
- them to <email>internals@stripped</email> and we will
- answer them.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ If you have any questions about the MySQL source, you can
+ post them to <email>internals@stripped</email> and we
+ will answer them.
+ </para>
+ </listitem>
- <listitem>
- <para>
- Before making big design decisions, please begin by posting a
- summary of what you want to do, why you want to do it, and how
- you plan to do it. This way we can easily provide you with
- feedback and also discuss it thoroughly. Perhaps another
- developer can assist you.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ Before making big design decisions, please begin by posting
+ a summary of what you want to do, why you want to do it, and
+ how you plan to do it. This way we can easily provide you
+ with feedback and also discuss it thoroughly. Perhaps
+ another developer can assist you.
+ </para>
+ </listitem>
- <listitem>
- <para>
- Try to write code in a lot of black boxes that can be reused
- or at least use a clean, easy to change interface.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ Try to write code in a lot of black boxes that can be reused
+ or at least use a clean, easy to change interface.
+ </para>
+ </listitem>
- <listitem>
- <para>
- Reuse code; There are already many algorithms in MySQL that
- can be reused for list handling, queues, dynamic and hashed
- arrays, sorting, etc.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ Reuse code; There are already many algorithms in MySQL that
+ can be reused for list handling, queues, dynamic and hashed
+ arrays, sorting, etc.
+ </para>
+ </listitem>
- <listitem>
- <para>
- Use the <literal>my_*</literal> functions like
- <literal>my_read()</literal>/<literal>my_write()</literal>/
- <literal>my_malloc()</literal> that you can find in the
- <literal>mysys</literal> library, instead of the direct system
- calls; This will make your code easier to debug and more
- portable.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ Use the <literal>my_*</literal> functions like
+ <literal>my_read()</literal>/<literal>my_write()</literal>/
+ <literal>my_malloc()</literal> that you can find in the
+ <literal>mysys</literal> library, instead of the direct
+ system calls; This will make your code easier to debug and
+ more portable.
+ </para>
+ </listitem>
- <listitem>
- <para>
- Use <literal>libstring</literal> functions (in the
- <filename>strings</filename> directory) instead of standard
- <literal>libc</literal> string functions whenever possible.
- For example, use <literal>bfill()</literal> and
- <literal>bzero()</literal> instead of
- <literal>memset()</literal>.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ Use <literal>libstring</literal> functions (in the
+ <filename>strings</filename> directory) instead of standard
+ <literal>libc</literal> string functions whenever possible.
+ For example, use <literal>bfill()</literal> and
+ <literal>bzero()</literal> instead of
+ <literal>memset()</literal>.
+ </para>
+ </listitem>
- <listitem>
- <para>
- Try to always write optimized code, so that you don't have to
- go back and rewrite it a couple of months later. It's better
- to spend 3 times as much time designing and writing an optimal
- function than having to do it all over again later on.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ Try to always write optimized code, so that you don't have
+ to go back and rewrite it a couple of months later. It's
+ better to spend 3 times as much time designing and writing
+ an optimal function than having to do it all over again
+ later on.
+ </para>
+ </listitem>
- <listitem>
- <para>
- Avoid CPU wasteful code, even when its use is trivial, to
- avoid developing sloppy coding habits.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ Avoid CPU wasteful code, even when its use is trivial, to
+ avoid developing sloppy coding habits.
+ </para>
+ </listitem>
- <listitem>
- <para>
- If you can do something in fewer lines, please do so (as long
- as the code will not be slower or much harder to read).
- </para>
- </listitem>
+ <listitem>
+ <para>
+ If you can do something in fewer lines, please do so (as
+ long as the code will not be slower or much harder to read).
+ </para>
+ </listitem>
- <listitem>
- <para>
- Do not check the same pointer for <literal>NULL</literal> more
- than once.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ Do not check the same pointer for <literal>NULL</literal>
+ more than once.
+ </para>
+ </listitem>
- <listitem>
- <para>
- Never use a macro when an (inline) function would work as
- well.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ Never use a macro when an (inline) function would work as
+ well.
+ </para>
+ </listitem>
- <listitem>
- <para>
- Do not make a function inline if you don't have a very good
- reason for it. In many cases, the extra code that is generated
- is more likely to slow down the resulting code than give a
- speed increase because the bigger code will cause more data
- fetches and instruction misses in the processor cache.
- </para>
+ <listitem>
+ <para>
+ Do not make a function inline if you don't have a very good
+ reason for it. In many cases, the extra code that is
+ generated is more likely to slow down the resulting code
+ than give a speed increase because the bigger code will
+ cause more data fetches and instruction misses in the
+ processor cache.
+ </para>
- <para>
- It is okay to use inline functions are which satisfy most of
- the following requirements:
- </para>
+ <para>
+ It is okay to use inline functions are which satisfy most of
+ the following requirements:
+ </para>
- <itemizedlist>
+ <itemizedlist>
- <listitem>
- <para>
- The function is very short (just a few lines).
- </para>
- </listitem>
+ <listitem>
+ <para>
+ The function is very short (just a few lines).
+ </para>
+ </listitem>
- <listitem>
- <para>
- The function is used in a speed critical place and is
- executed over and over again.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ The function is used in a speed critical place and is
+ executed over and over again.
+ </para>
+ </listitem>
- <listitem>
- <para>
- The function is handling the normal case, not some extra
- functionallity that most users will not use.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ The function is handling the normal case, not some extra
+ functionallity that most users will not use.
+ </para>
+ </listitem>
- <listitem>
- <para>
- The function is rarely called. (This restriction must be
- followed unless the function translates to fewer than 16
- assembler instructions.)
- </para>
- </listitem>
+ <listitem>
+ <para>
+ The function is rarely called. (This restriction must be
+ followed unless the function translates to fewer than 16
+ assembler instructions.)
+ </para>
+ </listitem>
- <listitem>
- <para>
- The compiler can do additional optimizations with inlining
- and the resulting function will be only a fraction of size
- of the original one.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ The compiler can do additional optimizations with
+ inlining and the resulting function will be only a
+ fraction of size of the original one.
+ </para>
+ </listitem>
- </itemizedlist>
- </listitem>
+ </itemizedlist>
+ </listitem>
- <listitem>
- <para>
- Think assembly - make it easier for the compiler to optimize
- your code.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ Think assembly - make it easier for the compiler to optimize
+ your code.
+ </para>
+ </listitem>
- <listitem>
- <para>
- Avoid using <literal>malloc()</literal>, which is very slow.
- For memory allocations that only need to live for the lifetime
- of one thread, use <literal>sql_alloc()</literal> instead.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ Avoid using <literal>malloc()</literal>, which is very slow.
+ For memory allocations that only need to live for the
+ lifetime of one thread, use <literal>sql_alloc()</literal>
+ instead.
+ </para>
+ </listitem>
- <listitem>
- <para>
- Functions return zero on success, and non-zero on error, so
- you can do:
- </para>
+ <listitem>
+ <para>
+ Functions return zero on success, and non-zero on error, so
+ you can do:
+ </para>
<programlisting>
if (a() || b() || c())
error("something went wrong");
</programlisting>
- </listitem>
+ </listitem>
- <listitem>
- <para>
- Using <literal>goto</literal> is okay if not abused.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ Using <literal>goto</literal> is okay if not abused.
+ </para>
+ </listitem>
- <listitem>
- <para>
- If you have an 'if' statement that ends with a 'goto' or
- 'return' you should NOT have an else statement:
- </para>
+ <listitem>
+ <para>
+ If you have an 'if' statement that ends with a 'goto' or
+ 'return' you should NOT have an else statement:
+ </para>
<programlisting>
if (a == b)
@@ -2933,34 +2966,34 @@
return 5;
return 6;
</programlisting>
- </listitem>
+ </listitem>
- <listitem>
- <para>
- Avoid default variable initializations. Use
- <literal>LINT_INIT()</literal> if the compiler complains after
- making sure that there is really no way the variable can be
- used uninitialized.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ Avoid default variable initializations. Use
+ <literal>LINT_INIT()</literal> if the compiler complains
+ after making sure that there is really no way the variable
+ can be used uninitialized.
+ </para>
+ </listitem>
- <listitem>
- <para>
- Use <literal>TRUE</literal> and <literal>FALSE</literal>
- instead of <literal>true</literal> and
- <literal>false</literal> in C++ code. This makes the code more
- readable and makes it easier to use it later in a C library,
- if needed.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ Use <literal>TRUE</literal> and <literal>FALSE</literal>
+ instead of <literal>true</literal> and
+ <literal>false</literal> in C++ code. This makes the code
+ more readable and makes it easier to use it later in a C
+ library, if needed.
+ </para>
+ </listitem>
- <listitem>
- <para>
- <literal>bool</literal> exists only in C++. In C, you have to
- use <literal>my_bool</literal> (which is
- <literal>char</literal>); it has different cast rules than
- <literal>bool</literal>:
- </para>
+ <listitem>
+ <para>
+ <literal>bool</literal> exists only in C++. In C, you have
+ to use <literal>my_bool</literal> (which is
+ <literal>char</literal>); it has different cast rules than
+ <literal>bool</literal>:
+ </para>
<programlisting>
int c= 256*2;
@@ -2969,61 +3002,64 @@
my_bool b= test(c); /* b gets 'true': GOOD */
</programlisting>
- <para>
- In C++, use <literal>bool</literal>, unless the variable is
- used in C code (for example the variable is passed to a C
- function).
- </para>
- </listitem>
+ <para>
+ In C++, use <literal>bool</literal>, unless the variable is
+ used in C code (for example the variable is passed to a C
+ function).
+ </para>
+ </listitem>
- <listitem>
- <para>
- Do not instantiate a class if you do not have to.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ Do not instantiate a class if you do not have to.
+ </para>
+ </listitem>
- <listitem>
- <para>
- Use pointers rather than array indexing when operating on
- strings.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ Use pointers rather than array indexing when operating on
+ strings.
+ </para>
+ </listitem>
- <listitem>
- <para>
- Never pass parameters with the
- <literal>&variable_name</literal> construct in C++. Always
- use a pointer instead!
- </para>
+ <listitem>
+ <para>
+ Never pass parameters with the
+ <literal>&variable_name</literal> construct in C++.
+ Always use a pointer instead!
+ </para>
- <para>
- The reason is that the above makes it much harder for the one
- reading the caller function code to know what is happening and
- what kind of code the compiler is generating for the call.
- </para>
- </listitem>
+ <para>
+ The reason is that the above makes it much harder for the
+ one reading the caller function code to know what is
+ happening and what kind of code the compiler is generating
+ for the call.
+ </para>
+ </listitem>
- <listitem>
- <para>
- Do not use the <literal>%p</literal> marker of
- <literal>printf()</literal> (<literal>fprintf()</literal>,
- <literal>vprintf()</literal>, etc) because it leads to
- different outputs (for example on some Linux and Mac OS X the
- output starts with <literal>0x</literal> while it does not on
- some Solaris). Use <literal>0x%lx</literal> instead, even if
- it causes a truncation on some 64-bit platforms. Being sure
- that there is always <literal>0x</literal> enables us to
- quickly identify pointer values in the DBUG trace.
- </para>
- </listitem>
+ <listitem>
+ <para>
+ Do not use the <literal>%p</literal> marker of
+ <literal>printf()</literal> (<literal>fprintf()</literal>,
+ <literal>vprintf()</literal>, etc) because it leads to
+ different outputs (for example on some Linux and Mac OS X
+ the output starts with <literal>0x</literal> while it does
+ not on some Solaris). Use <literal>0x%lx</literal> instead,
+ even if it causes a truncation on some 64-bit platforms.
+ Being sure that there is always <literal>0x</literal>
+ enables us to quickly identify pointer values in the DBUG
+ trace.
+ </para>
+ </listitem>
- <listitem>
- <para>
- Relying on loop coutner variables being local to the loop body
- if declared in the <literal>for</literal> statement is not
- portable. Some compilers still don't implment this ANSI C++
- specification. The symptom such use is an error like this:
- </para>
+ <listitem>
+ <para>
+ Relying on loop counter variables being local to the loop
+ body if declared in the <literal>for</literal> statement is
+ not portable. Some compilers still don't implement this ANSI
+ C++ specification. The symptom of such use is an error like
+ this:
+ </para>
<programlisting>
c-1101 CC: ERROR File = listener.cc, Line = 187
@@ -3031,13 +3067,13 @@
for (int i= 0; i < num_sockets; i++)
</programlisting>
- </listitem>
+ </listitem>
- </itemizedlist>
+ </itemizedlist>
- <para>
- Suggested mode in <literal>emacs</literal>:
- </para>
+ <para>
+ Suggested mode in <literal>emacs</literal>:
+ </para>
<programlisting>
(require 'font-lock)
@@ -3069,9 +3105,9 @@
(setq c-default-style "MY")
</programlisting>
- <para>
- Basic <literal>vim</literal> setup:
- </para>
+ <para>
+ Basic <literal>vim</literal> setup:
+ </para>
<programlisting>
set tabstop=8
@@ -3084,9 +3120,9 @@
"set expandtab "uncomment if you don't want to use tabstops
</programlisting>
- <para>
- Another <literal>vim</literal> setup:
- </para>
+ <para>
+ Another <literal>vim</literal> setup:
+ </para>
<programlisting>
set tabstop=8
@@ -3114,121 +3150,624 @@
let c_space_errors=1
</programlisting>
- <para>
- <emphasis role="bold">DBUG Tags</emphasis>
- </para>
+ <para>
+ <emphasis role="bold">DBUG Tags</emphasis>
+ </para>
- <para>
- Here are some of the DBUG tags we now use:
- </para>
+ <para>
+ Here are some of the DBUG tags we now use:
+ </para>
- <itemizedlist>
+ <itemizedlist>
- <listitem>
+ <listitem>
+ <para>
+ <literal>enter</literal>
+ </para>
+
+ <para>
+ Arguments to the function.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>exit</literal>
+ </para>
+
+ <para>
+ Results from the function.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>info</literal>
+ </para>
+
+ <para>
+ Something that may be interesting.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>warning</literal>
+ </para>
+
+ <para>
+ When something doesn't go the usual route or may be wrong.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>error</literal>
+ </para>
+
+ <para>
+ When something went wrong.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>loop</literal>
+ </para>
+
+ <para>
+ Write in a loop, that is probably only useful when debugging
+ the loop. These should normally be deleted when you are
+ satisfied with the code and it has been in real use for a
+ while.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ Some tags specific to <literal>mysqld</literal>, because we want
+ to watch these carefully:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ <literal>trans</literal>
+ </para>
+
+ <para>
+ Starting/stopping transactions.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>quit</literal>
+ </para>
+
+ <para>
+ <literal>info</literal> when <literal>mysqld</literal> is
+ preparing to die.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>query</literal>
+ </para>
+
+ <para>
+ Print query.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ </section>
+
+ <section id="coding-guidelines-plugins">
+
+ <title><command>configure</command> Support for Plugins</title>
+
+ <para>
+ Beginning with MySQL 5.1, the server supports a plugin
+ architecture for loading plugins. For example, several storage
+ engines have been converted to plugins, and they can be selected
+ of disabled at configuration time by means of command-options to
+ <command>configure</command>.
+ </para>
+
+ <para>
+ This section describes the command-line options that are used to
+ control which plugins get built, and the Autoconf macros that
+ enable a plugin configuration support to be described.
+ </para>
+
+ <section id="coding-guidelines-plugin-options">
+
+ <title><command>configure</command> Plugin Command-Line Options</title>
+
<para>
- <literal>enter</literal>
+ Several <command>configure</command> options apply to plugin
+ selection and building. You can build a plugin as static
+ (compiled into the server) or dynamic (built as a dynamic
+ library that must be installed using the <literal>INSTALL
+ PLUGIN</literal> statement before it can be used). Some
+ plugins might not support static or dynamic build.
</para>
<para>
- Arguments to the function.
+ <command>configure --help</command> shows the following
+ information pertaining to plugins:
</para>
- </listitem>
- <listitem>
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ The plugin-related options
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The names of all available plugins
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ For each plugin, a description of its purpose, which build
+ types it supports (static or dynamic), and which plugin
+ groups it is a part of.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
<para>
- <literal>exit</literal>
+ The following <command>configure</command> options are used to
+ select or disable plugins:
</para>
+<programlisting>
+--with-plugins=<replaceable>PLUGIN</replaceable>[,<replaceable>PLUGIN</replaceable>]...
+--with-plugins=<replaceable>GROUP</replaceable>
+--with-plugin-<replaceable>PLUGIN</replaceable>
+--without-plugin-<replaceable>PLUGIN</replaceable>
+</programlisting>
+
<para>
- Results from the function.
+ <replaceable>PLUGIN</replaceable> is an individual plugin name
+ such as <literal>csv</literal> or <literal>archive</literal>.
</para>
- </listitem>
- <listitem>
<para>
- <literal>info</literal>
+ As shorthand, <replaceable>GROUP</replaceable> is a
+ configuration group name such as <literal>none</literal>
+ (select no plugins), <literal>all</literal> (select all
+ plugins), or <literal>max</literal> (select all plugins used
+ in a <command>mysqld-max</command> server).
</para>
<para>
- Something that may be interesting.
+ <option>--with-plugins</option> can take a list of one or more
+ plugin names separated by commas, or a plugin group name. The
+ named plugins are configured to be built as static plugins.
</para>
- </listitem>
- <listitem>
<para>
- <literal>warning</literal>
+ <option>--with-plugin-<replaceable>PLUGIN</replaceable></option>
+ configures the given plugin to be built as a static plugin.
</para>
<para>
- When something doesn't go the usual route or may be wrong.
+ <option>--without-plugin-<replaceable>PLUGIN</replaceable></option>
+ disables the given plugin from being built.
</para>
- </listitem>
- <listitem>
<para>
- <literal>error</literal>
+ If a plugin is named both with a <option>--with</option> and
+ <option>--without</option> option, the result is undefined.
</para>
<para>
- When something went wrong.
+ For any plugin that is not explicitly selected or disabled, it
+ is selected to be built dynamically if it supports dynamic
+ build, and not built if it does not support dynamic build.
</para>
- </listitem>
- <listitem>
<para>
- <literal>loop</literal>
+ Thus, in the case that no plugin options are given, all
+ plugins that support dynamic build are selected to be built as
+ dynamic plugins. Plugins that do not support dynamic build are
+ not built.
</para>
+ </section>
+
+ <section id="coding-guidelines-plugin-macros">
+
+ <title>Autotools Plugin Macros</title>
+
<para>
- Write in a loop, that is probably only useful when debugging
- the loop. These should normally be deleted when you are
- satisfied with the code and it has been in real use for a
- while.
+ The following macros enable plugin support in the autotools
+ configuration files.
</para>
- </listitem>
- </itemizedlist>
+ <para>
+ Declaring a plugin:
+ </para>
- <para>
- Some tags specific to <literal>mysqld</literal>, because we want
- to watch these carefully:
- </para>
+<programlisting>
+MYSQL_PLUGIN(name, long-name, description [,configlist])
+</programlisting>
- <itemizedlist>
+ <para>
+ Each plugin is required to have
+ <literal>MYSQL_PLUGIN()</literal> declared first. The
+ <literal>configlist</literal> is an optional argument that is
+ a comma-separated list of configurations of which the module
+ is a member.
+ </para>
- <listitem>
<para>
- <literal>trans</literal>
+ Example:
</para>
+<programlisting>
+MYSQL_PLUGIN(ftexample, [Simple Parser], [Simple full-text parser plugin])
+</programlisting>
+
<para>
- Starting/stopping transactions.
+ Declaring a storage engine plugin:
</para>
- </listitem>
- <listitem>
+<programlisting>
+MYSQL_STORAGE_ENGINE(name, legacy-opt, long-name, description [,configlist])
+</programlisting>
+
<para>
- <literal>quit</literal>
+ This is a simple utility macro that calls
+ <literal>MYSQL_PLUGIN</literal>. It performs the bare basics
+ required to declare a storage engine plugin and provides
+ support for handling the legacy <command>configure</command>
+ command-line options. If the <literal>legacy-opt</literal> is
+ not specified, it will default to
+ <option>--with-<replaceable>NAME</replaceable>-storage-engine</option>.
+ Set the <literal>legacy-opt</literal> value to
+ <literal>no</literal> if you do not want to handle any legacy
+ option.
</para>
<para>
- <literal>info</literal> when <literal>mysqld</literal> is
- preparing to die.
+ This macro is roughly equivalent to:
</para>
- </listitem>
- <listitem>
+<programlisting>
+MYSQL_PLUGIN(name, long-name, description)
+MYSQL_PLUGIN_DEFINE(name, WITH_name_STORAGE_ENGINE)
+</programlisting>
+
<para>
- <literal>query</literal>
+ Example:
</para>
+<programlisting>
+MYSQL_STORAGE_ENGINE(berkeley, berkeley-db, [BerkeleyDB Storage Engine],
+ [Transactional Tables using BerkeleyDB], [max,max-no-ndb])
+</programlisting>
+
<para>
- Print query.
+ Declaring a C preprocessor variable:
</para>
- </listitem>
- </itemizedlist>
+<programlisting>
+MYSQL_PLUGIN_DEFINE(name, define-name)
+</programlisting>
+ <para>
+ When a plugin will be included in a static build, this will
+ set a preprocessor variable to 1. These preprocessor variables
+ are defined in <filename>config.h</filename>.
+ </para>
+
+ <para>
+ Example:
+ </para>
+
+<programlisting>
+MYSQL_PLUGIN_DEFINE(innobase, WITH_INNOBASE_STORAGE_ENGINE)
+</programlisting>
+
+ <para>
+ Declaring a source directory for a plugin:
+ </para>
+
+<programlisting>
+MYSQL_PLUGIN_DIRECTORY(name, dir-name)
+</programlisting>
+
+ <para>
+ Includes the specified directory into the build. If a file
+ named <filename>configure</filename> is detected in the
+ directory, it will be executed as part of the
+ <command>configure</command> build otherwise it is assumed
+ that there is a <filename>Makefile</filename> to be built in
+ that directory. Currently, there is only support for plugin
+ directories to be specified in the
+ <filename>storage/</filename> and <filename>plugin/</filename>
+ subdirectories.
+ </para>
+
+ <para>
+ Example:
+ </para>
+
+<programlisting>
+MYSQL_PLUGIN_DIRECTORY(archive, [storage/archive])
+</programlisting>
+
+ <para>
+ Declaring a static library name for a plugin:
+ </para>
+
+<programlisting>
+MYSQL_PLUGIN_STATIC(name, lib-name)
+</programlisting>
+
+ <para>
+ Sets the <command>configure</command> substitution
+ @plugin_NAME_static_target@ to the supplied library name if
+ the plugin is a static build. It also adds the library to the
+ list of libraries to be linked into <command>mysqld</command>.
+ It may either be just the name of the library where if there
+ is a directory specified then the directory will be prepended
+ for the link or if the supplied argument is another
+ <command>make</command> variable or substitution, it will be
+ passed through as is.
+ </para>
+
+ <para>
+ Example:
+ </para>
+
+<programlisting>
+MYSQL_PLUGIN_STATIC(archive, [libarchive.a])
+MYSQL_PLUGIN_STATIC(berkeley, [[\$(bdb_libs_with_path)]])
+</programlisting>
+
+ <para>
+ Declaring a dynamic library name for a plugin:
+ </para>
+
+<programlisting>
+MYSQL_PLUGIN_DYNAMIC(name, dso-name)
+</programlisting>
+
+ <para>
+ Sets the <command>configure</command> substitution
+ <literal>@plugin_NAME_shared_target@</literal> to the supplied
+ library name if the module is a dynamic build.
+ </para>
+
+ <para>
+ Example:
+ </para>
+
+<programlisting>
+MYSQL_PLUGIN_DYNAMIC(archive, [ha_archive.la])
+</programlisting>
+
+ <para>
+ Declaring a plugin as a mandatory module:
+ </para>
+
+<programlisting>
+MYSQL_PLUGIN_MANDATORY(name)
+</programlisting>
+
+ <para>
+ Mandatory plugins cannot be disabled.
+ </para>
+
+ <para>
+ Example:
+ </para>
+
+<programlisting>
+MYSQL_PLUGIN_MANDATORY(myisam)
+</programlisting>
+
+ <para>
+ Declaring a plugin as disabled:
+ </para>
+
+<programlisting>
+MYSQL_PLUGIN_DISABLED(name)
+</programlisting>
+
+ <para>
+ A disabled plugin will not be included in any build. If the
+ plugin has been marked as <literal>MANDATORY</literal>, it
+ will result in an <command>autoconf</command> error.
+ </para>
+
+ <para>
+ Declaring additional plugin <command>configure</command>
+ actions:
+ </para>
+
+<programlisting>
+MYSQL_PLUGIN_ACTIONS(name, configure-actions)
+</programlisting>
+
+ <para>
+ Useful if there are additional <command>configure</command>
+ actions required for a plugin. The
+ <literal>configure-actions</literal> argument may either be
+ the name of an <command>autoconf</command> macro or it may be
+ more <command>autoconf</command> script.
+ </para>
+
+ <para>
+ Example:
+ </para>
+
+<programlisting>
+MYSQL_PLUGIN_ACTIONS(ndbcluster,[MYSQL_SETUP_NDBCLUSTER])
+</programlisting>
+
+ <para>
+ Declaring plugin dependencies:
+ </para>
+
+<programlisting>
+MYSQL_PLUGIN_DEPENDS(name, dependencies)
+</programlisting>
+
+ <para>
+ Declares all plugins, in a comma-seperated list, that are
+ required for the named plugin to be built. If the named plugin
+ is selected, it will in turn enable all its depenencies. All
+ plugins listed as a dependency must already have been declared
+ with <literal>MYSQL_PLUGIN()</literal>.
+ </para>
+
+ <para>
+ Example:
+ </para>
+
+<programlisting>
+MYSQL_PLUGIN_DEPENDS(ndbcluster, [partition])
+</programlisting>
+
+ <para>
+ Performing the magic:
+ </para>
+
+<programlisting>
+MYSQL_CONFIGURE_PLUGINS(default-names)
+</programlisting>
+
+ <para>
+ Actually performs the task of generating the shell scripts for
+ <command>configure</command> based upon the declarations made
+ previously. It emits the shell code neccessary to check the
+ options and sets the variables accordingly.
+ </para>
+
+ <para>
+ Example:
+ </para>
+
+<programlisting>
+MYSQL_CONFIGURE_PLUGINS([none])
+</programlisting>
+
+ <para>
+ <command>configure</command> errors:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ When any plugin macro is called before
+ <literal>MYSQL_PLUGIN()</literal> is declared for that
+ plugin, <command>configure</command> aborts with an error.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ When any of the plugins specified in the dependency list
+ doesn't exist, <command>configure</command> aborts with an
+ error.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ When a mandatory plugin is specified in
+ <option>--without-plugin-<replaceable>NAME</replaceable></option>,
+ <command>configure</command> aborts with an error.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ When a disabled plugin is specified in
+ <option>--with-modules=... </option> or
+ <option>--with-plugin=<replaceable>NAME</replaceable></option>,
+ <command>configure</command> reports an error.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ When an optional plugin that may only be built dynamically
+ is specified in <option>--with-plugins=...</option> or
+ <option>--with-plugin-<replaceable>NAME</replaceable></option>,
+ <command>configure</command> emits a warning and continues
+ to configure the plugin for dynamic build.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ When an optional plugin that may only be built statically
+ is not specified in <option>--with-plugins=...</option>
+ nor
+ <option>--without-plugin-<replaceable>NAME</replaceable></option>,
+ <command>configure</command> emits a warning but should
+ proceed anyway.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ Avoiding <filename>configure.in</filename> changes:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ If a plugin source (which is located in a subdirectory of
+ the <filename>storage/</filename> or
+ <filename>plugin/</filename> directory) contains a
+ <filename>plug.in</filename> file (for example,
+ <filename>storage/example/plug.in</filename>), this file
+ will be included as a part of
+ <filename>configure.in</filename>. This way,
+ <filename>configure.in</filename> does not need to be
+ modified to add a new plugin to the build.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ A <filename>plug.in</filename> file may contain
+ everything, particularly all
+ <literal>MYSQL_PLUGIN_<replaceable>xxx</replaceable></literal>
+ macros as just described. The <filename>plug.in</filename>
+ file does not need to specify
+ <literal>MYSQL_PLUGIN_DIRECTORY</literal>; it is set
+ automatically to the directory of the
+ <filename>plug.in</filename> file.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ </section>
+
+ </section>
+
</chapter>
<chapter id="optimizer">
@@ -3471,7 +4010,7 @@
</programlisting>
<para>
- is an always-true situation --- so such columns are also
+ is an always-true situation — so such columns are also
eliminated from the conditional expression. This can be tricky.
For example, in an <literal>OUTER JOIN</literal>, a column which
is defined as <literal>NOT NULL</literal> might still contain a
@@ -3481,7 +4020,8 @@
<para>
The optimizer will not detect all possible <literal>impossible
- WHERE</literal> situations --- there are too many. For example:
+ WHERE</literal> situations — there are too many. For
+ example:
</para>
<programlisting>
@@ -3518,9 +4058,9 @@
<para>
Before you say <quote>but I never would write 1 + 2 in the first
- place</quote> --- remember what was said earlier about constant
- propagation. It is quite easy for the optimizer to put such
- expressions together. This process simplifies the result.
+ place</quote> — remember what was said earlier about
+ constant propagation. It is quite easy for the optimizer to put
+ such expressions together. This process simplifies the result.
</para>
<para>
@@ -3610,10 +4150,10 @@
<para>
When evaluating this query, MySQL first finds that table
- <literal>Table1</literal> --- after restriction with
- <literal>Table1.unique_not_null_column</literal> --- is a constant
- table according to the second definition above. So it retrieves
- that value.
+ <literal>Table1</literal> — after restriction with
+ <literal>Table1.unique_not_null_column</literal> — is a
+ constant table according to the second definition above. So it
+ retrieves that value.
</para>
<para>
@@ -3769,8 +4309,8 @@
</programlisting>
<para>
- and MySQL treats them the same --- there is no need to change IN
- to OR for a query, or vice versa.
+ and MySQL treats them the same — there is no need to change
+ IN to OR for a query, or vice versa.
</para>
<para>
@@ -3989,8 +4529,8 @@
When choosing a strategy to solve this query, the optimizer picks
<literal>s2 = 5</literal> as the driver because the index for
<literal>s2</literal> was created first. Regard this as an
- accidental effect rather than a rule --- it could change at any
- moment.
+ accidental effect rather than a rule — it could change at
+ any moment.
</para>
<para>
@@ -4162,8 +4702,8 @@
finding the values. (It's cheaper to do a sequential scan of the
index than a sequential scan of the table, that's why
<literal>index</literal> is a better join type than
- <literal>ALL</literal> --- see "The 'index' Join Type" section,
- earlier.) There will still be a full sort of the results.
+ <literal>ALL</literal> — see "The 'index' Join Type"
+ section, earlier.) There will still be a full sort of the results.
</para>
<para>
@@ -5803,7 +6343,7 @@
<literal>A or B</literal>. The problem is that <literal>+A
B</literal> can <emphasis role="bold">not</emphasis> be
rewritten in and/or terms (that's the reason why
- this---extended---set of operators was chosen). Still,
+ this—extended—set of operators was chosen). Still,
aproximations can be used. <literal>+A B C</literal> can be
approximated as <literal>A or (A and (B or C))</literal> or as
<literal>A or (A and B) or (A and C) or (A and B and
@@ -11892,7 +12432,7 @@
<para>
Let's look at the <filename>.MYD</filename> Data file
(<literal>MyISAM</literal> SQL Data file) more closely. There
- are three possible formats --- fixed, dynamic, and packed.
+ are three possible formats — fixed, dynamic, and packed.
First, let's discuss the fixed format.
</para>
@@ -11973,9 +12513,9 @@
<para>
A <literal>CHAR(1)</literal> column takes precisely one byte
- (plus one bit of overhead that is assigned to every column ---
- I'll describe the details of column storage later). So the file
- <filename>Table1.MYD</filename> looks like this:
+ (plus one bit of overhead that is assigned to every column
+ — I'll describe the details of column storage later). So
+ the file <filename>Table1.MYD</filename> looks like this:
</para>
<para>
@@ -12026,11 +12566,11 @@
</para>
<para>
- There are complications --- the record header is more complex if
- there are variable-length fields --- but the simple display
- shown in the example is exactly what you'd see if you looked at
- the MySQL Data file with a debugger or a hexadecimal file
- dumper.
+ There are complications — the record header is more
+ complex if there are variable-length fields — but the
+ simple display shown in the example is exactly what you'd see if
+ you looked at the MySQL Data file with a debugger or a
+ hexadecimal file dumper.
</para>
<para>
@@ -12070,7 +12610,7 @@
<para>
In the example, the actual length and the unused length are
short (one byte each) because the table definition says that the
- columns are short --- if the columns were potentially large,
+ columns are short — if the columns were potentially large,
then the actual length and the unused length could be two bytes
each, three bytes each, and so on. In this case, actual length
plus unused length is 10 hexadecimal (sixteen decimal), which is
@@ -12078,8 +12618,8 @@
</para>
<para>
- As for the third format --- packed --- we will only say briefly
- that:
+ As for the third format — packed — we will only say
+ briefly that:
</para>
<itemizedlist>
@@ -12788,7 +13328,7 @@
bytes long (the size of a <literal>MEDIUMINT</literal>),
it's easy to think there's some sort of correspondence
between the the <literal>BLOB</literal> and
- <literal>INT</literal> types. There isn't --- a
+ <literal>INT</literal> types. There isn't — a
<literal>BLOB</literal>'s preceding length is not four bytes
long (the size of an <literal>INT</literal>).
</para>
@@ -14216,7 +14756,7 @@
<para>
If you're just trying to read the record, the key bit in the
- Extra Bytes is 1byte_offs_flag --- you need to know if
+ Extra Bytes is 1byte_offs_flag — you need to know if
1byte_offs_flag is 1 (i.e.: "short 1-byteoffsets") or 0 (i.e.:
"2-byte offsets").
</para>
@@ -14292,9 +14832,9 @@
<para>
To understand what follows, you must know that table
- <literal>T</literal> has six columns --- not three ---
- because <literal>InnoDB</literal> automatically added
- three "system columns" at the start for its own
+ <literal>T</literal> has six columns — not three
+ — because <literal>InnoDB</literal> automatically
+ added three "system columns" at the start for its own
housekeeping. It happens that these system columns are the
row ID, the transaction ID, and the rollback pointer, but
their values don't matter now. Regard them as three black
@@ -14964,14 +15504,14 @@
<para>
An unordered list is often called a "heap". If you make a pile
of stones by saying "whichever one I happen to pick up next
- will go on top" --- rather than organizing them according to
- size and colour --- then you end up with a heap. Similarly,
- <literal>InnoDB</literal> does not want to insert new rows
- according to the B-tree's key order (that would involve
- expensive shifting of large amounts of data), so it inserts
- new rows right after the end of the existing rows (at the top
- of the Free Space part) or wherever there's space left by a
- deleted row.
+ will go on top" — rather than organizing them according
+ to size and colour — then you end up with a heap.
+ Similarly, <literal>InnoDB</literal> does not want to insert
+ new rows according to the B-tree's key order (that would
+ involve expensive shifting of large amounts of data), so it
+ inserts new rows right after the end of the existing rows (at
+ the top of the Free Space part) or wherever there's space left
+ by a deleted row.
</para>
<para>
@@ -15887,219 +16427,222 @@
<title>Directory Listing</title>
<para>
- <emphasis role="bold">Directory --- Short Comment</emphasis>
+ <emphasis role="bold">Directory — Short Comment</emphasis>
</para>
<itemizedlist>
<listitem>
<para>
- bdb --- The Berkeley Database table handler
+ bdb — The Berkeley Database table handler
</para>
</listitem>
<listitem>
<para>
- BitKeeper --- BitKeeper administration (not part of the
+ BitKeeper — BitKeeper administration (not part of the
source distribution)
</para>
</listitem>
<listitem>
<para>
- BUILD --- Frequently used build scripts
+ BUILD — Frequently used build scripts
</para>
</listitem>
<listitem>
<para>
- client --- Client library
+ client — Client library
</para>
</listitem>
<listitem>
<para>
- cmd-line-utils --- Command-line utilities (libedit and
+ cmd-line-utils — Command-line utilities (libedit and
readline)
</para>
</listitem>
<listitem>
<para>
- config --- Some files used during build
+ config — Some files used during build
</para>
</listitem>
<listitem>
<para>
- dbug --- Fred Fish's dbug library
+ dbug — Fred Fish's dbug library
</para>
</listitem>
<listitem>
<para>
- Docs --- Preliminary documents about internals and new
+ Docs — Preliminary documents about internals and new
modules; will eventually be moved to the mysqldoc repository
</para>
</listitem>
<listitem>
<para>
- extra --- Some minor standalone utility programs
+ extra — Some minor standalone utility programs
</para>
</listitem>
<listitem>
<para>
- heap --- The HEAP table handler
+ heap — The HEAP table handler
</para>
</listitem>
<listitem>
<para>
- include --- Header (*.h) files for most libraries; includes
- all header files distributed with the MySQL binary
+ include — Header (*.h) files for most libraries;
+ includes all header files distributed with the MySQL binary
distribution
</para>
</listitem>
<listitem>
<para>
- innobase --- The Innobase (InnoDB) table handler
+ innobase — The Innobase (InnoDB) table handler
</para>
</listitem>
<listitem>
<para>
- libmysql --- For producing MySQL as a library (e.g. a
+ libmysql — For producing MySQL as a library (e.g. a
Windows .DLL)
</para>
</listitem>
<listitem>
<para>
- libmysql_r --- For building a thread-safe libmysql library
+ libmysql_r — For building a thread-safe libmysql
+ library
</para>
</listitem>
<listitem>
<para>
- libmysqld --- The MySQL Server as an embeddable library
+ libmysqld — The MySQL Server as an embeddable library
</para>
</listitem>
<listitem>
<para>
- man --- Some user-contributed manual pages
+ man — Some user-contributed manual pages
</para>
</listitem>
<listitem>
<para>
- myisam --- The <literal>MyISAM</literal> table handler
+ myisam — The <literal>MyISAM</literal> table handler
</para>
</listitem>
<listitem>
<para>
- myisammrg --- The <literal>MyISAM</literal> Merge table
+ myisammrg — The <literal>MyISAM</literal> Merge table
handler
</para>
</listitem>
<listitem>
<para>
- mysql-test --- A test suite for mysqld
+ mysql-test — A test suite for mysqld
</para>
</listitem>
<listitem>
<para>
- mysys --- MySQL system library (Low level routines for file
- access etc.)
+ mysys — MySQL system library (Low level routines for
+ file access etc.)
</para>
</listitem>
<listitem>
<para>
- ndb --- MySQL Cluster
+ ndb — MySQL Cluster
</para>
</listitem>
<listitem>
<para>
- netware --- Files related to the Novell NetWare version of
- MySQL
+ netware — Files related to the Novell NetWare version
+ of MySQL
</para>
</listitem>
<listitem>
<para>
- NEW-RPMS --- Directory to place RPMs while making a
+ NEW-RPMS — Directory to place RPMs while making a
distribution
</para>
</listitem>
<listitem>
<para>
- os2 --- Routines for working with the OS/2 operating system
+ os2 — Routines for working with the OS/2 operating
+ system
</para>
</listitem>
<listitem>
<para>
- pstack --- Process stack display (not currently used)
+ pstack — Process stack display (not currently used)
</para>
</listitem>
<listitem>
<para>
- regex --- Henry Spencer's Regular Expression library for
+ regex — Henry Spencer's Regular Expression library for
support of REGEXP function
</para>
</listitem>
<listitem>
<para>
- SCCS --- Source Code Control System (not part of source
+ SCCS — Source Code Control System (not part of source
distribution)
</para>
</listitem>
<listitem>
<para>
- scripts --- SQL batches, e.g. mysqlbug and mysql_install_db
+ scripts — SQL batches, e.g. mysqlbug and
+ mysql_install_db
</para>
</listitem>
<listitem>
<para>
- server-tools --- instance manager
+ server-tools — instance manager
</para>
</listitem>
<listitem>
<para>
- sql --- Programs for handling SQL commands; the "core" of
- MySQL
+ sql — Programs for handling SQL commands; the "core"
+ of MySQL
</para>
</listitem>
<listitem>
<para>
- sql-bench --- The MySQL benchmarks
+ sql-bench — The MySQL benchmarks
</para>
</listitem>
<listitem>
<para>
- sql-common --- Some .c files related to sql directory
+ sql-common — Some .c files related to sql directory
</para>
</listitem>
<listitem>
<para>
- SSL --- Secure Sockets Layer; includes an example
+ SSL — Secure Sockets Layer; includes an example
certification one can use to test an SSL (secure) database
connection
</para>
@@ -16107,46 +16650,47 @@
<listitem>
<para>
- strings --- Library for C string routines, e.g. atof, strchr
+ strings — Library for C string routines, e.g. atof,
+ strchr
</para>
</listitem>
<listitem>
<para>
- support-files --- Files used to build MySQL on different
+ support-files — Files used to build MySQL on different
systems
</para>
</listitem>
<listitem>
<para>
- tests --- Tests in Perl and in C
+ tests — Tests in Perl and in C
</para>
</listitem>
<listitem>
<para>
- tools --- mysqlmanager.c (tool under development, not yet
- useful)
+ tools — mysqlmanager.c (tool under development, not
+ yet useful)
</para>
</listitem>
<listitem>
<para>
- VC++Files --- Includes this entire directory, repeated for
- VC++ (Windows) use
+ VC++Files — Includes this entire directory, repeated
+ for VC++ (Windows) use
</para>
</listitem>
<listitem>
<para>
- vio --- Virtual I/O Library
+ vio — Virtual I/O Library
</para>
</listitem>
<listitem>
<para>
- zlib --- Data compression library, used on Windows
+ zlib — Data compression library, used on Windows
</para>
</listitem>
@@ -16189,7 +16733,7 @@
distribution. This directory may be present if you downloaded
the MySQL source using BitKeeper rather than via the mysql.com
site. The files in the BitKeeper directory are for maintenance
- purposes only --- they are not part of the MySQL package.
+ purposes only — they are not part of the MySQL package.
</para>
<para>
@@ -21620,15 +22164,16 @@
<listitem>
<para>
First: <literal>InnoDB</literal> uses rollback segments like
- Oracle8i does --- but Oracle9i uses a different name.
+ Oracle8i does — but Oracle9i uses a different name.
</para>
</listitem>
<listitem>
<para>
Second: <literal>InnoDB</literal> uses multi-versioning like
- Oracle does --- but I see nothing that looks like an Oracle
- ITL being stored in the <literal>InnoDB</literal> data pages.
+ Oracle does — but I see nothing that looks like an
+ Oracle ITL being stored in the <literal>InnoDB</literal> data
+ pages.
</para>
</listitem>
@@ -21637,19 +22182,19 @@
Third: <literal>InnoDB</literal> and Oracle both have short
(back-to-statement-start) versioning for the <literal>READ
COMMITTED</literal> isolation level and long
- (back-to-transaction-start) versioning for higher levels ---
- but <literal>InnoDB</literal> and Oracle have different
- "default" isolation levels.
+ (back-to-transaction-start) versioning for higher levels
+ — but <literal>InnoDB</literal> and Oracle have
+ different "default" isolation levels.
</para>
</listitem>
<listitem>
<para>
Finally: <literal>InnoDB</literal>'s documentation says it has
- to lock "the gaps before index keys" to prevent phantoms ---
- but any Oracle user will tell you that phantoms are impossible
- anyway at the <literal>SERIALIZABLE</literal> isolation level,
- so key-locks are unnecessary.
+ to lock "the gaps before index keys" to prevent phantoms
+ — but any Oracle user will tell you that phantoms are
+ impossible anyway at the <literal>SERIALIZABLE</literal>
+ isolation level, so key-locks are unnecessary.
</para>
</listitem>
@@ -21699,7 +22244,7 @@
finding a prime slightly greater than the given argument, which is
useful for hash functions, but unrelated to randomness. The
functions in ut0mem.c are wrappers for "malloc" and "free" calls
- --- for the real "memory" module see section \mem (MEMORY).
+ — for the real "memory" module see section \mem (MEMORY).
Finally, the functions in ut0ut.c are a miscellany that didn't fit
better elsewhere: get_high_bytes, clock, time, difftime,
get_year_month_day, and "sprintf" for various diagnostic purposes.
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r2260 - in trunk: . internals | paul | 2 Jun |
