General Procedure for Building Client Programs

This section describes the steps involved in compiling and linking a program that uses the MySQL client library. The commands to build clients vary somewhat from system to system, and you may need to modify the commands shown here a bit. However, the description is general and you should be able to apply it to most client programs you write.

Basic System Requirements

When you write a MySQL client program in C, you'll obviously need a C compiler. The examples shown here use gcc, which is probably the most common compiler used on UNIX. You'll also need the following in addition to the program's own source files:

• The MySQL header files

• The MySQL client library

The header files and client library constitute the basis of MySQL client programming support. If they are not installed on your system already, you'll need to obtain them. If MySQL was installed on your system from a source or binary distribution, client programming support should have been installed as part of that process. If RPM files were used, this support won't be present unless you installed the developer RPM. Should you need to obtain the MySQL header files and library, see Appendix A.

Compiling and Linking Client Programs

To compile and link a client program, you may need to specify where the MySQL header files and client library are located, because often they are not installed in locations that the compiler and linker search by default. For the following examples, suppose the header file and client library locations are /usr/local/include/mysql and /usr/local/lib/mysql.

To tell the compiler how to find the MySQL header files when you compile a source file into an object file, pass it an -I option that names the appropriate directory. For example, to compile myclient.c to produce myclient.o, you might use a command like this:

 % gcc -c -I/usr/local/include/mysql myclient.c  

To tell the linker where to find the client library and what its name is, pass -L/usr/local/lib/mysql and -lmysqlclient arguments when you link the object file to produce an executable binary, as follows:

 % gcc -o myclient myclient.o -L/usr/local/lib/mysql -lmysqlclient  

If your client consists of multiple files, name all the object files on the link command.

The link step may result in error messages having to do with functions that cannot be found. In such cases, you'll need to supply additional -l options to name the libraries containing the functions. If you see a message about compress() or uncompress(), try adding -lz or -lgz to tell the linker to search the zlib compression library:

 % gcc -o myclient myclient.o -L/usr/local/lib/mysql -lmysqlclient -lz  

If the message names the floor() function, add -lm to link in the math library. You might need to add other libraries as well. For example, you'll probably need -lsocket and -lnsl on Solaris.

As of MySQL 3.23.21, you can use the mysql_config utility to determine the proper flags for compiling and linking MySQL programs. For example, the utility might indicate that the following options are needed:

 % mysql_config --cflags  -I'/usr/local/mysql/include/mysql' % mysql_config --libs -L'/usr/local/mysql/lib/mysql' -lmysqlclient -lz -lcrypt -lnsl -lm 

To use mysql_config directly within your compile or link commands, invoke it within backticks:

 % gcc -c `mysql_config --cflags` myclient.c  % gcc -o myclient myclient.o `mysql_config --libs` 

The shell will execute mysql_config and substitute its output into the surrounding command, which automatically provides the appropriate flags for gcc.

If you don't use make to build programs, I suggest you learn how so that you won't have to type a lot of program-building commands manually. Suppose you have a client program, myclient, that comprises two source files, main.c and aux.c, and a header file, myclient.h. You might write a simple Makefile to build this program as follows. Note that indented lines are indented with tabs; if you use spaces, the Makefile will not work.

 CC = gcc  INCLUDES = -I/usr/local/include/mysql LIBS = -L/usr/local/lib/mysql -lmysqlclient all: myclient main.o: main.c myclient.h     $(CC) -c $(INCLUDES) main.c aux.o: aux.c myclient.h     $(CC) -c $(INCLUDES) aux.c myclient: main.o aux.o     $(CC) -o myclient main.o aux.o $(LIBS) clean:     rm -f myclient main.o aux.o 

Using the Makefile, you can rebuild your program whenever you modify any of the source files simply by running make, which displays and executes the necessary commands:

 % make  gcc -c -I/usr/local/mysql/include/mysql myclient.c gcc -o myclient myclient.o -L/usr/local/mysql/lib/mysql -lmysqlclient 

That's easier and less error prone than typing long gcc commands. A Makefile also makes it easier to modify the build process. For example, if your system is one for which you need to link in additional libraries, such as the math and compression libraries, edit the LIBS line in the Makefile to add -lm and -lz:

 LIBS = -L/usr/local/lib/mysql -lmysqlclient -lm -lz  

If you need other libraries, add them to the LIBS line as well. Thereafter, when you run make, it will use the updated value of LIBS automatically.

Another way to change make variables other than editing the Makefile is to specify them on the command line. For example, if your C compiler is named cc rather than gcc (as is the case for Mac OS X, for example), you can say so as follows:

 % make CC=cc  

If mysql_config is available, you can use it to avoid writing literal include file and library directory pathnames in the Makefile. Write the INCLUDES and LIBS lines as follows instead:

 INCLUDES = ${shell mysql_config --cflags}  LIBS = ${shell mysql_config --libs} 

When make runs, it will execute each mysql_config command and use its output to set the corresponding variable value. The ${shell} construct shown here is supported by GNU make; you may need to use a somewhat different syntax if your version of make isn't based on GNU make.

If you're using an integrated development environment (IDE), you may not see or use a Makefile at all. The details will depend on your particular IDE.