Author: mcbrown
Date: 2007-01-08 17:59:17 +0100 (Mon, 08 Jan 2007)
New Revision: 4398
Log:
Adding download/build information to Falcon docs.
Updating warning/overview
Removing warning from SE section
Modified:
trunk/falcon/falcon.xml
trunk/falcon/se-falcon.xml
Modified: trunk/falcon/falcon.xml
===================================================================
--- trunk/falcon/falcon.xml 2007-01-08 11:56:02 UTC (rev 4397)
+++ trunk/falcon/falcon.xml 2007-01-08 16:59:17 UTC (rev 4398)
Changed blocks: 2, Lines Added: 346, Lines Deleted: 5; 11732 bytes
@@ -14,7 +14,9 @@
<abstract>
<para>
- This document provides information for use with the special alpha release of the Falcon Storage Engine component for the MySQL database.
+ This document provides information for use with the special
+ alpha release of the Falcon Storage Engine component for the
+ MySQL database.
</para>
<para>
@@ -32,14 +34,353 @@
</bookinfo>
-<chapter id="getting-falcon">
-<title>Getting Falcon</title>
+ <preface>
-<para>You can get Falcon from....</para>
+ <title>About the Falcon Storage Engine Release</title>
-</chapter>
+ <para>
+ The Falcon storage engine is part of the MySQL DBMS, and thus
+ depends on the MySQL server. It's currently released within a
+ special alpha build of MySQL and will be updated regularly during
+ the alpha process. The production (GA) version of the Falcon
+ storage engine will be incorporated into the next major version of
+ MySQL along with other major new features.
+ </para>
+ <para>
+ Falcon is currently an Alpha release and should not be used in
+ production environments. Falcon is currently only supported within
+ a special fork of the MySQL release, termed MySQL -5.2-falcon.
+ This release is not considered ready for production. The
+ mysql-5.2-falcon tree is provided only for testing and evaluation
+ of the Falcon storage engine.
+ </para>
+ <para>
+ Note that mysql-5.2-falcon tree may not include all feature or bug
+ fixes that have been applied to previous releases of MySQL.
+ </para>
+
+ </preface>
+
+ <chapter id="building-falcon">
+
+ <title>Getting and Building Falcon</title>
+
+ <para>
+ Falcon has been made available as a special MySQL tree called
+ <literal>mysql-5.2-falcon</literal>. In order to try out Falcon
+ you must download the source code and build the special version of
+ the MySQL tree.
+ </para>
+
+ <para>
+ To build the Falcon release you will need:
+ </para>
+
+ <itemizedlist>
+
+ <listitem>
+ <para>
+ GNU <command>make</command>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ GNU <command>autoconf</command> 2.58 (or newer)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ GNU <command>automake</command> 1.8 (or newer)
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ GNU <command>libtool</command> 1.5
+ </para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>
+ You can obtain the sources for Falcon from
+ <ulink
+ url="http://mysql.bkbits.com">http://mysql.bkbits.com</ulink>.
+ In order to download the sources, you must use a BitKeeper client.
+ You may use either the free client or the commercial client to
+ download the sources.
+ </para>
+
+ <para>
+ To obtain a source tree, first download and install the BitKeeper
+ free client if you do not have it. The client can be obtained from
+ <ulink url="http://www.bitmover.com/bk-client2.0.shar"/>.
+ <emphasis role="deprecated">Note that old 1.1 versions of the
+ BitKeeper free client will not work!</emphasis>
+ </para>
+
+ <para>
+ To install the BitKeeper client on Unix, use these commands:
+ </para>
+
+<programlisting>
+shell> <userinput>/bin/sh bk-client2.0.shar</userinput>
+shell> <userinput>cd bk-client2.0</userinput>
+shell> <userinput>make</userinput>
+</programlisting>
+
+ <para>
+ If you get a <literal>cc: command not found</literal> error,
+ invoke this command before running <literal>make</literal>:
+ </para>
+
+<programlisting>
+shell> <userinput>make CC=gcc</userinput>
+</programlisting>
+
+ <para>
+ To install the BitKeeper client on Windows, use these
+ instructions:
+ </para>
+
+ <orderedlist>
+
+ <listitem>
+ <para>
+ Download and install Cygwin from
+ <ulink url="http://cygwin.com/">http://cygwin.com</ulink>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Make sure <command>gcc</command> and <command>make</command>
+ have been installed under Cygwin. You can test this by issuing
+ <command>which gcc</command> and <command>which make</command>
+ commands. If either one is not installed, run Cygwin's package
+ manager, select <command>gcc</command>,
+ <command>make</command>, or both, and install them.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ For the installation of the BitKeeper free client, use the
+ same installations as given for Unix-like systems above.
+ </para>
+ </listitem>
+
+ </orderedlist>
+
+ <para>
+ The BitKeeper free client is shipped with its source code. The
+ only documentation available for the free client is the source
+ code itself.
+ </para>
+
+ <para>
+ After you have installed the BitKeeper client, you can access the
+ MySQL development source tree:
+ </para>
+
+ <orderedlist>
+
+ <listitem>
+ <para>
+ Change location to the directory you want to work from, and
+ then use the following command to make a local copy of the
+ <literal>mysql-5.2-falcon</literal> tree:
+ </para>
+
+<programlisting>
+shell> <userinput>bkf clone bk://mysql.bkbits.net/mysql-5.2-falcon
+mysql-5.2-falcon</userinput>
+</programlisting>
+
+ <para>
+ In the preceding example, the source tree is set up in the
+ <filename>mysql-5.2-falcon/</filename> subdirectory of your
+ current directory.
+ </para>
+
+ <para>
+ The initial download of the source tree may take a while,
+ depending on the speed of your connection. Please be patient.
+ </para>
+ </listitem>
+
+ </orderedlist>
+
+ <para>
+ Once you have downloaded the Falcon tree:
+ </para>
+
+ <orderedlist>
+
+ <listitem>
+ <para>
+ Change into the directory containing the Falcon tree:
+ </para>
+
+<programlisting>shell> cd mysql-5.2-falcon</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ Run the appropropriate build script to start the build
+ process. For Pentium CPUs, use
+ <command>compile-pentium-debug-falcon</command>, for AMD 64
+ CPUs, use <command>compile-amd64-debug-falcon</command>. The
+ build scipts are located in the <filename>BUILD</filename>,
+ but they should be executed from the root directory of the
+ tree:
+
+<programlisting>shell>
+ ./BUILD/compile-pentium-debug-falcon</programlisting>
+
+ .
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The build script will create the necessary stubs for the
+ configure process, run <command>configure</command>, and then
+ execute the <command>make</command> to start the compilation
+ process.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ Rather than installing directly from this build, you may want
+ to create a binary package that can be distributed and
+ relocated to the right location. To create such a
+ distribution, use the
+ <command>make_binary_distribution</command> script:
+ </para>
+
+<programlisting>shell>
+ ./scripts/make_binary_distribution</programlisting>
+
+ <para>
+ The above command will create an archive with all the files
+ you need configured to behave as if they were in a directoy
+ named according to the version and tag for this release. For
+ example, on a Linux Pentium machine, the Falcon release will
+ create an archive with the name
+ <filename>mysql-5.2.0-falcon-alpha-linux-i686.tar</filename>,
+ which contains the directory
+ <filename>mysql-5.2.0-falcon-alpha-linux-i686</filename>.
+ </para>
+
+ <para>
+ To install the files to a new location, extract them
+ specifying the new base directory:
+ </para>
+
+<programlisting>shell> tar zxf mysql-5.2.0-falcon-alpha-linux-i686 -C /usr/local</programlisting>
+
+ <para>
+ You can either use directory or link to an alternative
+ location. For example, you may want to create a link to
+ <filename>/usr/local/mysql-falcon</filename>:
+ </para>
+
+<programlisting>shell>
+cd /usr/local
+shell> ln -s mysql-5.2.0-falcon-alpha-linux-i686 mysql-falcon</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ You must configure the new installation, including creating
+ the base databases. Running <command>configure</command> in
+ this directory will perform this function for you, and start
+ an instance of <literal>mysqld</literal>:
+ </para>
+
+<programlisting>shell> cd
+mysql-falcon
+shell> ./configure</programlisting>
+
+ <para>
+ If <literal>mysqld</literal> fails to start, ensure that the
+ files in your chosen directory are owned by the
+ <literal>mysql</literal> user:
+ </para>
+
+<programlisting>shell> chown -R mysql:mysql *</programlisting>
+ </listitem>
+
+ <listitem>
+ <para>
+ Confirm that <command>mysqld</command> is running by obtaining
+ the version from the server:
+ </para>
+
+<programlisting>shell>
+ ./bin/mysqladmin version
+./bin/mysqladmin Ver 8.42 Distrib 5.2.0-falcon-alpha, for pc-linux-gnu on i686
+Copyright (C) 2000 MySQL AB & MySQL Finland AB & TCX DataKonsult AB
+This software comes with ABSOLUTELY NO WARRANTY. This is free software,
+and you are welcome to modify and redistribute it under the GPL license
+
+Server version 5.2.0-falcon-alpha-debug
+Protocol version 10
+Connection Localhost via UNIX socket
+UNIX socket /tmp/mysql.sock
+Uptime: 3 min 24 sec
+
+Threads: 1 Questions: 1 Slow queries: 0 Opens: 14 Flush tables: 1 »
+ Open tables: 7 Queries per second avg: </programlisting>
+
+ <para>
+ You may need to update your <literal>LD_LIBRARY_PATH</literal>
+ with the MySQL libraries:
+ </para>
+
+<programlisting>shell> export
+ LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/mysql-falcon/lib</programlisting>
+ </listitem>
+
+ </orderedlist>
+
+ <para>
+ Once Falcon has been installed, you can try creating tables using
+ the Falcon engine. For example, to create a simple table with
+ Falcon:
+ </para>
+
+<programlisting>shell> ./bin/mysql
+Welcome to the MySQL monitor. Commands end with ; or \g.
+Your MySQL connection id is 2
+Server version: 5.2.0-falcon-alpha-debug Source distribution
+
+Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
+
+mysql> use test
+Database changed
+mysql> CREATE TABLE falcon_basic (id int, fname varchar(20)) ENGINE=Falcon;
+Query OK, 0 rows affected (1.07 sec)</programlisting>
+
+ <para>
+ For more information on Falcon features and functionality, see
+ <xref
+ linkend="se-falcon"/>. You may want to exchange
+ information on your experiences with other users on the
+ <ulink
+ url="http://forums.mysql.com/list.php?133">Falcon
+ Forum</ulink>. If you think you have found a bug, use
+ <ulink url="http://buys.mysql.com">MySQL Bugs</ulink>.
+ </para>
+
+ </chapter>
+
<xi:include href="se-falcon.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
</book>
Modified: trunk/falcon/se-falcon.xml
===================================================================
--- trunk/falcon/se-falcon.xml 2007-01-08 11:56:02 UTC (rev 4397)
+++ trunk/falcon/se-falcon.xml 2007-01-08 16:59:17 UTC (rev 4398)
Changed blocks: 6, Lines Added: 6, Lines Deleted: 7; 1765 bytes
@@ -47,7 +47,7 @@
<section id="se-falcon-features">
<title>Falcon Features</title>
-&falcon-warning;
+
<para>
Falcon has been specially developed for systems that are able to
support larger memory architectures and multi-threaded or
@@ -147,7 +147,7 @@
<section id="se-falcon-configuration">
<title>Configuration Parameters</title>
- &falcon-warning;
+
<para>
Parameters are configured through the standard
<filename>my.cnf</filename> or <filename>my.ini</filename> file.
@@ -324,8 +324,7 @@
<section id="se-falcon-createdb">
<title>Creating the Falcon Tablespace</title>
- &falcon-warning;
-
+
<para>
Within Falcon, all data within one database is stored within a
single tablespace, which in turn is stored within a single file
@@ -368,7 +367,7 @@
<section id="se-falcon-createtable">
<title>Creating Tables and Indexes within Falcon</title>
- &falcon-warning;
+
<para>
Falcon supports all of the standard column data types supported by
MySQL.
@@ -407,7 +406,7 @@
<section id="se-falcon-principles">
<title>Principles and Terminology</title>
- &falcon-warning;
+
<para>
To get the best out of the Falcon engine you should understand the
following basic principles and terminology.
@@ -901,7 +900,7 @@
<section id="se-falcon-limits">
<title>Limits</title>
- &falcon-warning;
+
<para>
There are a number of limits in the alpha release of Falcon; these
will be addressed in forthcoming releases:
| Thread |
|---|
| • svn commit - mysqldoc@docsrva: r4398 - trunk/falcon | mcbrown | 8 Jan |
