22.1.3.5. Building Connector/ODBC from a Source Distribution on Unix

Note

Connector/5.2 uses cmake for build, rather than autoconf and its configure command.

You need the following tools to build MySQL from source on Unix:

A working ANSI C++ compiler. GCC 4.2.1 or later, Sun Studio 10 or later, Visual Studio 2008 or later, and many current vendor-supplied compilers are known to work.
cmake.
MySQL client libraries and include files from MySQL 4.0.0 or higher. (Preferably MySQL 4.0.16 or higher). This is required because Connector/ODBC uses calls and structures that exist only starting from this version of the library. To get the client libraries and include files, visit http://dev.mysql.com/downloads/.

If you have built your own MySQL server or client libraries from source using the GNU autotools, use the --enable-thread-safe-client option to configure when the libraries were built. No special option is needed if you configure with cmake.

Also, ensure that the libmysqlclient library was built and installed as a shared library.
A compatible ODBC manager must be installed. Connector/ODBC is known to work with the iODBC and unixODBC managers. See Section 22.1.2.1.2, "ODBC Driver Managers" for more information.
If you are using a character set that is not compiled into the MySQL client library, install the MySQL character definitions from the charsets directory into SHAREDIR (by default, /usr/local/mysql/share/mysql/charsets). These should be in place if you have installed the MySQL server on the same machine. See Section 10.1, "Character Set Support" for more information on character set support.

Once you have all the required files, unpack the source files to a separate directory, then run configure and build the library using make.

Typical cmake Options

iODBC is the default ODBC library used by Connector/ODBC. Alternatively, unixODBC may be used by passing in the appropriate option to cmake. For example:

shell> cmake -G "Unix Makefiles"
        -DWITH_UNIXODBC=1

When you run cmake, you might add options to the command line. Here are some examples:

-DODBC_INCLUDES=dir_name: Used when the ODBC include directory is not found within the system $PATH.
-DODBC_LIB_DIR=dir_name: Used when the ODBC library directory is not found within the system $PATH.
-DWITH_UNIXODBC=1: Enables unixODBC support.

Additional configure Options

There are a number of other options that you need, or want, to set when configuring the Connector/ODBC driver before it is built.

To link the driver with MySQL thread safe client libraries libmysqlclient_r.so or libmysqlclient_r.a, specify the following configure option:
```
--enable-thread-safe
```
and can be disabled (default) using
```
--disable-thread-safe
```
This option enables the building of the driver thread-safe library libmyodbc3_r.so from by linking with MySQL thread-safe client library libmysqlclient_r.so. (The extensions are OS-dependent.)

If the compilation with the thread-safe option fails, it may be because the correct thread-libraries on the system could not be located. Set the value of LIBS to point to the correct thread library for your system.
```
LIBS="-lpthread" ./configure ..
```
You can enable or disable the shared and static versions of Connector/ODBC using these options:
```
--enable-shared[=yes|no]--disable-shared--enable-static[=yes|no]--disable-static
```
By default, all the binary distributions are built as non-debug versions (configured with --without-debug).

To enable debugging information, build the driver from a source distribution with the proper configuration option to enable debugging support. See Section 2.9.4, "MySQL Source-Configuration Options".
This option is available only for source trees that have been obtained from the Subversion repository. This option does not apply to the packaged source distributions.

By default, the driver is built with the --without-docs option. If you would like the documentation to be built, then execute configure with:
```
--with-docs
```

Build Steps for Unix

To build the driver libraries, execute make:

shell> make

If any errors occur, correct them and continue the build process. If you are not able to build, then send a detailed email to <myodbc@lists.mysql.com> for further assistance.

Building Shared Libraries

On most platforms, MySQL does not build or support .so (shared) client libraries by default. This is based on our experience of problems when building shared libraries.

In cases like this, you have to download the MySQL distribution and configure it with these options:

--without-server --enable-shared

To build shared driver libraries, specify the --enable-shared option for configure. By default, configure does not enable this option.

If you have configured with the --disable-shared option, you can build the .so file from the static libraries using the following commands:

shell> cd
        mysql-connector-odbc-3.51.01shell> makeshell> cd drivershell> CC=/usr/bin/gcc
        \          $CC -bundle -flat_namespace -undefined error \          -o .libs/libmyodbc3-3.51.01.so \          catalog.o
        connect.o cursor.o dll.o error.o execute.o \          handle.o
        info.o misc.o myodbc3.o options.o prepare.o \          results.o
        transact.o utility.o \          -L/usr/local/mysql/lib/mysql/
        \          -L/usr/local/iodbc/lib/
        \          -lz -lc -lmysqlclient
        -liodbcinst

Make sure to change -liodbcinst to -lodbcinst if you are using unixODBC instead of iODBC, and configure the library paths accordingly.

This builds and places the libmyodbc3-3.51.01.so file in the .libs directory. Copy this file to the Connector/ODBC library installation directory (/usr/local/lib, or the lib directory under the installation directory that you supplied with the --prefix option).

shell> cd .libsshell> cp libmyodbc3-3.51.01.so /usr/local/libshell> cd /usr/local/libshell> ln -s
        libmyodbc3-3.51.01.so libmyodbc3.so

To build the thread-safe driver library:

shell> CC=/usr/bin/gcc
        \          $CC -bundle -flat_namespace -undefined
        error          -o .libs/libmyodbc3_r-3.51.01.so          catalog.o connect.o cursor.o dll.o error.o
        execute.o          handle.o info.o misc.o myodbc3.o options.o
        prepare.o          results.o transact.o
        utility.o          -L/usr/local/mysql/lib/mysql/          -L/usr/local/iodbc/lib/          -lz
        -lc -lmysqlclient_r -liodbcinst

Installing Driver Libraries

To install the driver libraries, execute the following command:

shell> make install

That command installs one of the following sets of libraries:

For Connector/ODBC 3.51:

libmyodbc3.so
libmyodbc3-3.51.01.so, where 3.51.01 is the version of the driver
libmyodbc3.a

For thread-safe Connector/ODBC 3.51:

libmyodbc3_r.so
libmyodbc3-3_r.51.01.so
libmyodbc3_r.a

For more information on build process, refer to the INSTALL file that comes with the source distribution. Note that if you are trying to use the make from Sun, you may end up with errors. On the other hand, GNU gmake should work fine on all platforms.

Testing Connector/ODBC on Unix

To run the basic samples provided in the distribution with the libraries that you built, use the following command:

shell> make test

Before running the tests, create the DSN 'myodbc3' in odbc.ini and set the environment variable ODBCINI to the correct odbc.ini file; and MySQL server is running. You can find a sample odbc.ini with the driver distribution.

You can even modify the samples/run-samples script to pass the desired DSN, UID, and PASSWORD values as the command-line arguments to each sample.