Chapter 4 Installing MySQL from Source

The mysqld server is installed in the libexec directory rather than in the bin directory.

The data directory is var rather than data.

mysql_install_db is installed in the bin directory rather than in the scripts directory.

The header file and library directories are include/mysql and lib/mysql rather than include and lib.

A good make program. Although some platforms come with their own make implementations, it is highly recommended that you use GNU make 3.75 or newer. It may already be available on your system as gmake. GNU make is available from http://www.gnu.org/software/make/.

autoconf 2.58 (or newer), available from http://www.gnu.org/software/autoconf/.

automake 1.8.1, available from http://www.gnu.org/software/automake/.

libtool 1.5, available from http://www.gnu.org/software/libtool/. 1.5.24 or later is recommended.

m4, available from http://www.gnu.org/software/m4/.

bison 2.1 or newer, available from http://www.gnu.org/software/bison/. (Version 1 is no longer supported.) Use the latest version of bison where possible; if you experience problems, upgrade to a later version, rather than revert to an earlier one.

Section 4.9, “Notes on Installing MySQL on AIX from Source”

Section 4.10, “Notes on Installing MySQL on HP-UX from Source”

Section 4.8, “Notes on Installing MySQL on Solaris from Source”

To compile just the MySQL client libraries and client programs and not the server, use the --without-server option:

shell> ./configure --without-server

If you have no C++ compiler, some client programs such as mysql cannot be compiled because they require C++. In this case, you can remove the code in configure that tests for the C++ compiler and then run ./configure with the --without-server option. The compile step should still try to build all clients, but you can ignore any warnings about files such as mysql.cc. (If make stops, try make -k to tell it to continue with the rest of the build even if errors occur.)

To build the embedded MySQL library (libmysqld.a), use the --with-embedded-server option.

To place your log files and database directories elsewhere than under /usr/local/var, use a configure command something like one of these:

shell> ./configure --prefix=/usr/local/mysql
shell> ./configure --prefix=/usr/local \
           --localstatedir=/usr/local/mysql/data

The first command changes the installation prefix so that everything is installed under /usr/local/mysql rather than the default of /usr/local. The second command preserves the default installation prefix, but overrides the default location for database directories (normally /usr/local/var) and changes it to /usr/local/mysql/data.

You can also specify the installation directory and data directory locations at server startup time by using the --basedir and --datadir options. These can be given on the command line or in an MySQL option file, although it is more common to use an option file. See Using Option Files.

The --with-tcp-port option specifies the port number on which the server listens for TCP/IP connections. The default is port 3306. To listen on a different port, use a configure command like this:

shell> ./configure --with-tcp-port=3307

On Unix, if you want the MySQL socket file location to be somewhere other than the default location (normally in the directory /tmp or /var/run), use a configure command like this:

shell> ./configure \
           --with-unix-socket-path=/usr/local/mysql/tmp/mysql.sock

The socket file name must be an absolute path name. You can also change the location of mysql.sock at server startup by using a MySQL option file. See How to Protect or Change the MySQL Unix Socket File.

To compile statically linked programs (for example, to make a binary distribution, to get better performance, or to work around problems with some Red Hat Linux distributions), run configure like this:

shell> ./configure --with-client-ldflags=-all-static \
           --with-mysqld-ldflags=-all-static

If you are using gcc and do not have libg++ or libstdc++ installed, you can tell configure to use gcc as your C++ compiler:

shell> CC=gcc CXX=gcc ./configure

When you use gcc as your C++ compiler, it does not attempt to link in libg++ or libstdc++. This may be a good thing to do even if you have those libraries installed. Some versions of them have caused strange problems for MySQL users in the past.

In most cases, you can get a reasonably optimized MySQL binary by using the following options on the configure line:

--prefix=/usr/local/mysql --enable-assembler \
--with-mysqld-ldflags=-all-static

The full configure line would, in other words, be something like the following for all recent gcc versions:

CFLAGS="-O3 -mpentiumpro" CXX=gcc CXXFLAGS="-O3 -mpentiumpro \
-felide-constructors -fno-exceptions -fno-rtti" ./configure \
--prefix=/usr/local/mysql --enable-assembler \
--with-mysqld-ldflags=-all-static

The binaries we provide on the MySQL Web site at http://dev.mysql.com/downloads/ are all compiled with full optimization and should work well for most users. See Chapter 3, Installing MySQL on Unix/Linux Using Generic Binaries.

If the build fails and produces errors about your compiler or linker not being able to create the shared library libmysqlclient.so.N (where N is a version number), you can work around this problem by giving the --disable-shared option to configure. In this case, configure does not build a shared libmysqlclient.so.N library.

By default, MySQL uses the latin1 (cp1252 West European) character set. To change the default set, use the --with-charset option:

shell> ./configure --with-charset=CHARSET

CHARSET may be one of binary, armscii8, ascii, big5, cp1250, cp1251, cp1256, cp1257, cp850, cp852, cp866, cp932, dec8, eucjpms, euckr, gb2312, gbk, geostd8, greek, hebrew, hp8, keybcs2, koi8r, koi8u, latin1, latin2, latin5, latin7, macce, macroman, sjis, swe7, tis620, ucs2, ujis, utf8. (Additional character sets might be available. Check the output from ./configure --help for the current list.)

The default collation may also be specified. MySQL uses the latin1_swedish_ci collation by default. To change this, use the --with-collation option:

shell> ./configure --with-collation=COLLATION

To change both the character set and the collation, use both the --with-charset and --with-collation options. The collation must be a legal collation for the character set. (Use the SHOW COLLATION statement to determine which collations are available for each character set.)

With the configure option --with-extra-charsets=LIST, you can define which additional character sets should be compiled into the server. LIST is one of the following:

Clients that want to convert characters between the server and the client should use the SET NAMES statement. See Connection Character Sets and Collations.

To configure MySQL with debugging code, use the --with-debug option:

shell> ./configure --with-debug

This causes a safe memory allocator to be included that can find some errors and that provides output about what is happening. See Debugging and Porting MySQL.

As of MySQL 5.1.12, using --with-debug to configure MySQL with debugging support enables you to use the --debug="d,parser_debug" option when you start the server. This causes the Bison parser that is used to process SQL statements to dump a parser trace to the server's standard error output. Typically, this output is written to the error log.

To cause the Debug Sync facility to be compiled into the server, use the --enable-debug-sync option. This facility is used for testing and debugging. When compiled in, Debug Sync is disabled by default at runtime. To enable it, start mysqld with the --debug-sync-timeout=N option, where N is a timeout value greater than 0. (The default value is 0, which disables Debug Sync.) N becomes the default timeout for individual synchronization points.

Debug Sync is also compiled in if you configure with the --with-debug option (which implies --enable-debug-sync), unless you also use the --disable-debug-sync option.

For a description of the Debug Sync facility and how to use synchronization points, see MySQL Internals: Test Synchronization.

The --enable-debug-sync and --disable-debug-sync options were added in MySQL 5.1.41.

If your client programs are using threads, you must compile a thread-safe version of the MySQL client library with the --enable-thread-safe-client configure option. This creates a libmysqlclient_r library with which you should link your threaded applications. See Writing C API Threaded Client Programs.

Some features require that the server be built with compression library support, such as the COMPRESS() and UNCOMPRESS() functions, and compression of the client/server protocol. The --with-zlib-dir=no|bundled|DIR option provides control over compression library support. The value no explicitly disables compression support. bundled causes the zlib library bundled in the MySQL sources to be used. A DIR path name specifies the directory in which to find the compression library sources.

It is possible to build MySQL with large table support using the --with-big-tables option.

This option causes the variables that store table row counts to be declared as unsigned long long rather than unsigned long. This enables tables to hold up to approximately 1.844E+19 ((2³²)²) rows rather than 2³² (~4.295E+09) rows. Previously it was necessary to pass -DBIG_TABLES to the compiler manually in order to enable this feature.

Run configure with the --disable-grant-options option to cause the --bootstrap, --skip-grant-tables, and --init-file options for mysqld to be disabled. For Windows, the configure.js script recognizes the DISABLE_GRANT_OPTIONS flag, which has the same effect. The capability is available as of MySQL 5.1.15.

This option allows MySQL Community Server features to be enabled. Additional options may be required for individual features, such as --enable-profiling to enable statement profiling. This option was added in MySQL 5.1.24. It is enabled by default as of MySQL 5.1.28; to disable it, use --disable-community-features.

When given with --enable-community-features, the --enable-profiling option enables the statement profiling capability exposed by the SHOW PROFILE and SHOW PROFILES statements. (See SHOW PROFILES Syntax.) This option was added in MySQL 5.1.24. It is enabled by default as of MySQL 5.1.28; to disable it, use --disable-profiling.

See Chapter 2, General Installation Guidance, for options that pertain to particular operating systems.

See Building MySQL with Support for Secure Connections, for options that pertain to configuring MySQL to support secure (encrypted) connections.

Several configure options apply to plugin selection and building:

--with-plugins=PLUGIN[,PLUGIN]...
--with-plugins=GROUP
--with-plugin-PLUGIN
--without-plugin-PLUGIN

PLUGIN is an individual plugin name such as csv or archive.

As shorthand, GROUP is a configuration group name such as none (select no plugins) or all (select all plugins).

You can build a plugin as static (compiled into the server) or dynamic (built as a dynamic library that must be installed using the INSTALL PLUGIN statement or the --plugin-load option before it can be used). Some plugins might not support static or dynamic build.

configure --help shows the following information pertaining to plugins:

--with-plugins 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.

--with-plugin-PLUGIN configures the given plugin to be built as a static plugin.

--without-plugin-PLUGIN disables the given plugin from being built.

If a plugin is named both with a --with and --without option, the result is undefined.

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. (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.)

If configure is run after it has previously been run, it may use information that was gathered during its previous invocation. This information is stored in config.cache. When configure starts up, it looks for that file and reads its contents if it exists, on the assumption that the information is still correct. That assumption is invalid when you reconfigure.

Each time you run configure, you must run make again to recompile. However, you may want to remove old object files from previous builds first because they were compiled using different configuration options.

If you get errors such as the ones shown here when compiling sql_yacc.cc, you probably have run out of memory or swap space:

Internal compiler error: program cc1plus got fatal signal 11
Out of virtual memory
Virtual memory exhausted

The problem is that gcc requires a huge amount of memory to compile sql_yacc.cc with inline functions. Try running configure with the --with-low-memory option:

shell> ./configure --with-low-memory

This option causes -fno-inline to be added to the compile line if you are using gcc and -O0 if you are using something else. You should try the --with-low-memory option even if you have so much memory and swap space that you think you can't possibly have run out. This problem has been observed to occur even on systems with generous hardware configurations, and the --with-low-memory option usually fixes it.

By default, configure picks c++ as the compiler name and GNU c++ links with -lg++. If you are using gcc, that behavior can cause problems during configuration such as this:

configure: error: installation or configuration problem:
C++ compiler cannot create executables.

You might also observe problems during compilation related to g++, libg++, or libstdc++.

One cause of these problems is that you may not have g++, or you may have g++ but not libg++, or libstdc++. Take a look at the config.log file. It should contain the exact reason why your C++ compiler did not work. To work around these problems, you can use gcc as your C++ compiler. Try setting the environment variable CXX to "gcc -O3". For example:

shell> CXX="gcc -O3" ./configure

This works because gcc compiles C++ source files as well as g++ does, but does not link in libg++ or libstdc++ by default.

Another way to fix these problems is to install g++, libg++, and libstdc++. However, do not use libg++ or libstdc++ with MySQL because this only increases the binary size of mysqld without providing any benefits. Some versions of these libraries have also caused strange problems for MySQL users in the past.

To define flags to be used by your C or C++ compilers, specify them using the CFLAGS and CXXFLAGS environment variables. You can also specify the compiler names this way using CC and CXX. For example:

shell> CC=gcc
shell> CFLAGS=-O3
shell> CXX=gcc
shell> CXXFLAGS=-O3
shell> export CC CFLAGS CXX CXXFLAGS

To see what flags you might need to specify, invoke mysql_config with the --cflags option.

If you get errors such as those shown here when compiling mysqld, configure did not correctly detect the type of the last argument to accept(), getsockname(), or getpeername():

cxx: Error: mysqld.cc, line 645: In this statement, the referenced
     type of the pointer value ''length'' is ''unsigned long'',
     which is not compatible with ''int''.
new_sock = accept(sock, (struct sockaddr *)&cAddr, &length);

To fix this, edit the config.h file (which is generated by configure). Look for these lines:

/* Define as the base type of the last arg to accept */
#define SOCKET_SIZE_TYPE XXX

Change XXX to size_t or int, depending on your operating system. (You must do this each time you run configure because configure regenerates config.h.)

If your compile fails with errors such as any of the following, you must upgrade your version of make to GNU make:

make: Fatal error in reader: Makefile, line 18:
Badly formed macro assignment

Or:

make: file `Makefile' line 18: Must be a separator (:

Or:

pthread.h: No such file or directory

Solaris and FreeBSD are known to have troublesome make programs.

GNU make 3.75 is known to work.

The sql_yacc.cc file is generated from sql_yacc.yy. Normally, the build process does not need to create sql_yacc.cc because MySQL comes with a pregenerated copy. However, if you do need to re-create it, you might encounter this error:

"sql_yacc.yy", line xxx fatal: default action causes potential...

This is a sign that your version of yacc is deficient. You probably need to install bison (the GNU version of yacc) and use that instead.

Versions of bison older than 1.75 may report this error:

sql_yacc.yy:#####: fatal error: maximum table size (32767) exceeded

The maximum table size is not actually exceeded; the error is caused by bugs in older versions of bison.

On Debian Linux 3.0, you need to install gawk instead of the default mawk.

If you get a compilation error on Linux (for example, SuSE Linux 8.1 or Red Hat Linux 7.3) similar to the following one, you probably do not have g++ installed:

libmysql.c:1329: warning: passing arg 5 of `gethostbyname_r' from
incompatible pointer type
libmysql.c:1329: too few arguments to function `gethostbyname_r'
libmysql.c:1329: warning: assignment makes pointer from integer
without a cast
make[2]: *** [libmysql.lo] Error 1

By default, the configure script attempts to determine the correct number of arguments by using g++ (the GNU C++ compiler). This test yields incorrect results if g++ is not installed. There are two ways to work around this problem:

You must run configure again after making either of those changes.

If you link dynamically (without -static), the result is 13% slower on Linux. Note that you still can use a dynamically linked MySQL library for your client applications. It is the server that is most critical for performance.

For a connection from a client to a server running on the same host, if you connect using TCP/IP rather than a Unix socket file, performance is 7.5% slower. (On Unix, if you connect to the host name localhost, MySQL uses a socket file by default.)

For TCP/IP connections from a client to a server, connecting to a remote server on another host is 8% to 11% slower than connecting to a server on the same host, even for connections faster than 100Mb/s Ethernet.

When running our benchmark tests using secure connections (all data encrypted with internal SSL support) performance was 55% slower than with unencrypted connections.

On a Sun UltraSPARC-IIe, a server compiled with Forte 5.0 is 4% faster than one compiled with gcc 3.2.

On a Sun UltraSPARC-IIe, a server compiled with Forte 5.0 is 4% faster in 32-bit mode than in 64-bit mode.

Compiling on Linux-x86 using gcc without frame pointers (-fomit-frame-pointer or -fomit-frame-pointer -ffixed-ebp) makes mysqld 1% to 4% faster.

Windows 2000, Windows XP, or newer version.

Windows Vista is supported when using Visual Studio 2005 provided you have installed the following updates:

CMake, which can be downloaded from http://www.cmake.org. After installing, modify your PATH environment variable to include the directory where cmake is located.

Microsoft Visual C++ 2005 Express Edition, Visual Studio .Net 2003 (7.1), or Visual Studio 2005 (8.0) compiler system.

If you are using Visual C++ 2005 Express Edition, you must also install an appropriate Platform SDK. More information and links to downloads for various Windows platforms is available from http://www.microsoft.com/downloads/details.aspx?familyid=0baf2b35-c656-4969-ace8-e4c0c0716adb.

If you are compiling from a Bazaar tree or making changes to the parser, you need bison for Windows, which can be downloaded from http://gnuwin32.sourceforge.net/packages/bison.htm. Download the package labeled “Complete package, excluding sources”. After installing the package, modify your PATH environment variable to include the directory where bison is located.

Cygwin might be necessary if you want to run the test script or package the compiled binaries and support files into a Zip archive. (Cygwin is needed only to test or package the distribution, not to build it.) Cygwin is available from http://cygwin.com.

3GB to 5GB of disk space.

Obtain a source distribution packaged by Oracle Corporation. These are available from http://dev.mysql.com/downloads/.

Package a source distribution yourself from the latest Bazaar developer source tree. For instructions on pulling the latest source files, see Section 4.3, “Installing MySQL Using a Development Source Tree”.

When building you should ensure that your PATH variable includes the necessary tools, including ar for building libraries. Some tools are located in /usr/ccs/bin.

When running configure, you should specify the C and C++ compiler explicitly to ensure that the right C compiler combination is used:

CC=gcc CXX=g++ ./configure

If you have an UltraSPARC system, you can get 4% better performance by adding -mcpu=v8 -Wa,-xarch=v8plusa to the CFLAGS and CXXFLAGS environment variables.

If you have Sun's Forte 5.00 (or newer) or Sun Studio compiler, you can run configure like this:

CC=cc CFLAGS="-Xa -fast -native -xstrconst -mt" \
CXX=CC CXXFLAGS="-noex -mt" \
./configure --prefix=/usr/local/mysql --enable-assembler

To create a 64-bit SPARC binary with Sun's Forte or Sun Studio compiler, use the following configuration options:

CC=cc CFLAGS="-Xa -fast -native -xstrconst -mt -xarch=v9" \
CXX=CC CXXFLAGS="-noex -mt -xarch=v9" ASFLAGS="-xarch=v9" \
./configure --prefix=/usr/local/mysql --enable-assembler

To create a 64-bit Solaris binary using gcc, add -m64 to CFLAGS and CXXFLAGS and remove --enable-assembler from the configure line.

In the MySQL benchmarks, we obtained a 4% speed increase on UltraSPARC when using Forte 5.0 in 32-bit mode, as compared to using gcc 3.2 with the -mcpu flag.

If you create a 64-bit mysqld binary, it is 4% slower than the 32-bit binary, but can handle more threads and memory.

If you get a problem with fdatasync or sched_yield, you can fix this by adding LIBS=-lrt to the configure line

Solaris does not provide static versions of all system libraries (libpthreads and libdl), so you cannot compile MySQL with --static. If you try to do so, you get one of the following errors:

ld: fatal: library -ldl: not found
undefined reference to `dlopen'
cannot find -lrt

If you link your own MySQL client programs, you may see the following error at runtime:

ld.so.1: fatal: libmysqlclient.so.#:
open failed: No such file or directory

To avoid this problem, use one of the following methods:

If you have problems with configure trying to link with -lz when you do not have zlib installed, you have two options:

If you are using gcc and have problems with loading user-defined functions (UDFs) into MySQL, try adding -lgcc to the link line for the UDF.

Automatic xlC detection is missing from Autoconf, so a number of variables need to be set before running configure. The following example uses the IBM compiler:

export CC="xlc_r -ma -O3 -qstrict -qoptimize=3 -qmaxmem=8192 "
export CXX="xlC_r -ma -O3 -qstrict -qoptimize=3 -qmaxmem=8192"
export CFLAGS="-I /usr/local/include"
export LDFLAGS="-L /usr/local/lib"
export CPPFLAGS=$CFLAGS
export CXXFLAGS=$CFLAGS
./configure --prefix=/usr/local \
                --localstatedir=/var/mysql \
                --sbindir='/usr/local/bin' \
                --libexecdir='/usr/local/bin' \
                --enable-thread-safe-client \
                --enable-large-files

The preceding options are used to compile the MySQL distribution that can be found at http://www-frec.bull.com/.

If you change the -O3 to -O2 in the preceding configure line, you must also remove the -qstrict option. This is a limitation in the IBM C compiler.

If you compile MySQL with gcc, you must use the -fno-exceptions flag because the exception handling in gcc is not thread-safe. There are also some known problems with IBM's assembler that may cause it to generate bad code when used with gcc.

If you have problems with signals (MySQL dies unexpectedly under high load), you may have found an OS bug with threads and signals. In this case, you can tell MySQL not to use signals by configuring as follows:

CFLAGS=-DDONT_USE_THR_ALARM CXX=gcc \
CXXFLAGS="-felide-constructors -fno-exceptions -fno-rtti \
-DDONT_USE_THR_ALARM" \
./configure --prefix=/usr/local/mysql --with-debug \
    --with-low-memory

This does not affect the performance of MySQL, but has the side effect that you cannot kill clients that are “sleeping” on a connection with mysqladmin kill or mysqladmin shutdown. Instead, the client dies when it issues its next command.

On some versions of AIX, linking with libbind.a makes getservbyname() dump core. This is an AIX bug and should be reported to IBM.

If you are using HP-UX compiler, you can use the following command (which has been tested with cc B.11.11.04):

CC=cc CXX=aCC CFLAGS=+DD64 CXXFLAGS=+DD64 ./configure \
    --with-extra-character-set=complex

You can ignore any errors of the following type:

aCC: warning 901: unknown option: `-3': use +help for online
documentation

If you get the following error from configure, verify that you do not have the path to the K&R compiler before the path to the HP-UX C and C++ compiler:

checking for cc option to accept ANSI C... no
configure: error: MySQL requires an ANSI C compiler (and a C++ compiler).
Try gcc. See the Installation chapter in the Reference Manual.

Another reason for compile failure is that you did not define the +DD64 flags as just described.