Building and Installing MySQL 5.1 and the BLOB Streaming Engine
===============================================================

This document describes how to build the pluggable Streaming Engine for MySQL 5.1 on MacOS X and Linux.

If you already have a compiled MySQL 5.1 source tree then skip to step 4.

1. Download MySQL 5.1
---------------------

To build the Streaming Engine you need to download and build MySQL 5.1. I recommend the source download from:

http://dev.mysql.com/downloads/mysql/5.1.html

Unpack the .tar.gz in your development directory.

Alternatively you can use the latest sources directly from the BitKeeper repository as described here:

http://dev.mysql.com/doc/refman/5.1/en/installing-source-tree.html

For this document I will assume your development directory is '/home/build', and that the MySQL source tree is in a directory named  'mysql-51'. In other words, the MySQL source tree is located in the directory: '/home/build/mysql-51'

2. Configure and build MySQL 5.1
--------------------------------

Currently, I recommend you configure MySQL 5.1 as follows:

$ ./configure --with-zlib-dir=bundled --with-extra-charsets=complex --with-plugins=max-no-ndb --with-embedded-server --enable-thread-safe-client --with-big-tables

Please note, you will probably want to add some of the options described below.

After configuration, make and install MySQL:

$ make
$ make install

3. Additional MySQL Options
---------------------------

In addition to the options above, you will probably want to use the following options:

--prefix=<mysql-home>

Use this option to specify an alternative "home" for mysql. By default MySQL will be installed in the location '/usr/local/mysql'. This is inconvenient for 2 reasons:
* you need root privileges to install in this location,
* you may already have a production version of MySQL installed here.

So for testing I recommend using you add the following to configure command above: --prefix=/home/build/test

--with-mysqld-user=<user>

Specify an alternative user for the mysqld executable (default is mysql). I recommend using the user under which you are building mysql. In this way you will not have to start the MySQL server as root.

In this document we are using a user with the name 'build', so you should add the following option to the configure command: --with-mysqld-user=build

--with-debug=yes/no/full

For development or debug purpose use the option --with-debug=yes or --with-debug=full. If you wish to perform performance tests, then make sure you use --with-debug=no, or omit this option.

Whichever option you use, remember to build the Streaming Engine with the same options or it will not load, or otherwise crash (see below).

4. Download the Streaming Engine
--------------------------------

You can download the Streaming Engine from http://www.blobstreaming.org.

Unpack the .tar.gz archive in your development directory (assumed to be /home/build/ in this document).

5. Configure and build the Streaming Engine
-------------------------------------------

Assuming the MySQL source tree has been built in the directory, '/home/build/mysql-51', as follows:

$ ./configure --with-zlib-dir=bundled --with-extra-charsets=complex --with-plugins=max-no-ndb --with-embedded-server --enable-thread-safe-client --with-big-tables --prefix=/home/build/test --with-mysqld-user=build --with-debug=full

Configure the Streaming Engine as follows:

$ ./configure --with-mysql=/home/build/mysql-51 --libdir=/home/build/test/lib/mysql --with-debug=full

--with-mysql indicates the path to the MySQL source tree.

--libdir indicates the plug-in installation directory.

--with-debug specifies the debug level and must be set to the same level as the MySQL build. Possible options are no, yes or full. If the option is omitted from the MySQL build, then it must also be omitted from the the Streaming Engine configure.

After configuration, build and install the plug-in:

$ make
$ make install

This copies the plug-in shared library to the directory where it can be found by the MySQL server. 

6. Loading and using the plug-in
--------------------------------

In order to load the plug-in, start the MySQL server, and connect with the MySQL shell, for example:

$ cd /home/build/test
$ bin/mysqld_safe &
$ bin/mysql -u root

Now enter the following command:

mysql> INSTALL PLUGIN MyBS SONAME 'libmybs.so';

The server will load and register the the Streaming Engine plug-in in the mysql.plugin table. The plug-in is now available whenever the server is started.

Note: the streaming engine can only be used in combination with a streaming enabled storage engine (such as PBXT 0.9.87 Beta or later).