- 1 A Guided Tour Of The MySQL Source Code
- 1.1 Getting the Source Tree
- 1.2 The Major Directories
- 1.3 The Flow
- 1.4 The Open-Source Directories
- 1.5 The Internal and External Storage Engine Directories
- 1.6 The OS-Specific Directories
- 1.7 Odds and Ends
- 1.8 A Chunk of Code in /sql/sql_update.cc
- 1.9 The Skeleton of the Server Code
- 1.10 Recap
BUILDclientDocsmyisammysyssqlvio
The orderly approach is to look first at the most important directories, then we'll look at the whole list in our second pass. So, first, let's look at what you'll find in just seven of the directories: BUILD, client, Docs, myisam, mysys, sql, and vio.
The first major directory we'll look at is BUILD. It actually has very little in it, but it's useful, because one of the first things you might want to do with the source code is: compile and link it.
The example command line that we could use is
shell> ./BUILD/compile-pentium-debug --prefix=$HOME/mysql-bin
It invokes a batch file in the BUILD directory. When it's done, you'll have an executable MySQL server and client.
Or, um, well, maybe you won't. Sometimes people have trouble with this step because there's something missing in their operating system version, or whatever. Don't worry, it really does work, and there are people around who might help you if you have trouble with this step. Search for "build" in the archives of lists.mysql.com.
We, when we're done building, tend to install it with the following sequence:
shell>makeshell>make installshell>$HOME/mysql-bin/bin/mysql_install_db\ --basedir=$HOME/mysql-bin\ --datadir=$HOME/mysql-bin/var
This puts the new MySQL installation files on
shell>$HOME/mysql-bin/libexec -- for the servershell>$HOME/mysql-bin/bin -- for the mysql clientshell>$HOME/mysql-bin/var -- for the databases
Once you've got something that runs, you can put a debugger on it. We recommend use of the GNU debugger
http://www.gnu.org/software/gdb/documentation/
And many developers use the graphical debugger tool DDD - Data Display Debugger
http://www.gnu.org/software/ddd/manual/
These are free and common, they're probably on your Linux system already.
There are debuggers for Windows and other operating systems, of course don't feel left out just because we're mentioning a Linux tool name! But it happens that we do a lot of things with Linux ourselves, so we happen to know what to say. To debug the mysqld server, say:
shell> ddd --gdb --args \
$HOME/mysql-bin/libexec/mysqld \
--basedir=$HOME/mysql-bin \
--datadir=$HOME/mysql-bin/var\
--skip-networking
From this point on, it may be tempting to follow along through the rest of the "guided tour" by setting breakpoints, displaying the contents of variables, and watching what happens after starting a client from another shell. That would be more fun. But it would require a detour, to discuss how to use the debugger. So we'll plow forward, the dull way, noting what's in the directories and using a text editor to note what's in the individual files.
To run a test named some.test with the
debugger in embedded mode you could do this:
Run
libmysqld/examples/test_run --gdb some.test. This creates alibmysqld/examples/test-gdbinitfile which contains the required parameters for mysqltest.Make a copy of the
test-gdbinitfile (call it, for example,some-gdbinit). Thetest-gdbinitfile will be removed aftertest-run --gdbhas finished.Load
libmysqld/examples/mysqltest_embeddedinto your favorite debugger, for example:gdb mysqltest_embedded.In the debugger, for example in
gdb, do:--sou some-gdbinit
Now some.test is running, and you can see
if it's passing or not.
If you just want to debug some queries with the embedded
server (not the test), it's easier to just run
libmysqld/examples/mysql. It's the embedded
server-based clone of the usual
mysql tool, and works fine
under gdb or whatever your
favorite debugger is.
The next major directory is mysql-5.0/client.
size name comment ---- ---- ------- 100034 mysql.cc "The MySQL command tool" 36913 mysqladmin.c maintenance of MYSQL databases 22829 mysqlshow.c show databases, tables, or columns + 12 more .c and .cc programs
It has the source code of many of your familiar favorites, like mysql, which everybody has used to connect to the MySQL server at one time or another. There are other utilities too in fact, you'll find the source of most client-side programs here. There are also programs for checking the password, and for testing that basic functions such as threading or access via SSL are possible.
You'll notice, by the way, that we're concentrating on the files that have extension of ".c" or ".cc". By now it's obvious that C is our principal language although there are some utilities written in Perl as well.
The next major directory is labelled myisam. We will begin by mentioning that myisam is one of what we call the MySQL storage engine directories.
The MySQL storage engine directories: heap -- also known as 'memory' innodb -- maintained by Innobase Oy myisam -- see next section! ndb -- ndb cluster
For example the heap directory contains the source files for the heap storage engine and the ndb directory contains the source files for the ndb storage engine.
But the files in those directories are mostly analogues of what's in the myisam directory, and the myisam directory is sort of a 'template'.
On the myisam directory, you'll find the programs that do file I/O. Notice that the file names begin with the letters mi, by the way. That stands for MyISAM, and most of the important files in this directory start with mi.
File handling programs on mysql-5.0/myisam:
size name comment ---- ---- ------- 40301 mi_open.c for opening 3593 mi_close.c for closing 1951 mi_rename.c for renaming + more mi_*.c programs
Row handling programs on mysql-5.0/myisam:
size name comment ---- ---- ------- 29064 mi_delete.c for deleting 2562 mi_delete_all.c for deleting all 6797 mi_update.c for updating 32613 mi_write.c for inserting + more mi_*.c programs
Drilling down a bit, you'll also find programs in the myisam directory that handle deleting, updating, and inserting of rows. The only one that's a little hard to find is the program for inserting rows, which we've called mi_write.c instead of mi_insert.c.
Key handling programs on mysql-5.0/myisam:
size name comment ---- ---- ------- 4668 mi_rkey.c for random key searches 3646 mi_rnext.c for next-key searches 15440 mi_key.c for managing keys + more mi_*.c programs
The final notable group of files in the myisam directory is the group that handles keys in indexes.
To sum up: (1) The myisam directory is where you'll find programs for handling files, rows, and keys. You won't find programs for handling columns we'll get to them a bit later. (2) The myisam directory is just one of the handler directories. The programs in the other storage engine directories fulfill about the same functions.
The next major directory is labelled mysys, which stands for MySQL System Library. This is the toolbox directory, for example it has low level routines for file access. The .c files in mysys have procedures and functions that are handy for calling by main programs, for example by the programs in the myisam directory. There are 115 .c files in mysys, so we only can note a sampling.
Sampling of programs on mysql-5.0/mysys
size name comment ---- ---- ------- 17684 charset.c character sets 6165 mf_qsort.c quicksort 5609 mf__tempfile.c temporary files + 112 more *.c programs
Example one: with charset.c routines, you can change the character set.
Example two: mf_qsort.c contains our quicksort package.
Example three: mf_tempfile.c has what's needed for maintaining MySQL's temporary files.
You can see from these examples that mysys is a hodgepodge. That's why we went to the trouble of producing extra documentation in this document to help you analyze mysys's contents.
The next major directory is mysql-5.0/sql. If you remember your manual, you know that you must pronounce this: ess queue ell.
The "parser" programs on mysql-5.0/sql:
size name comment ---- ---- ------- 51326 sql_lex.cc lexer 230026 sql_yacc.yy parser + many more *.cc programs
This is where we keep the parser. In other words, programs like sql_lex.cc and sql_yacc.yy are responsible for figuring out what's in an SQL command, and deciding what to do about it.
The "handler" programs on mysql-5.0/sql:
size name comment ---- ---- ------- 79798 ha_berkeley.cc bdb 56687 ha_federated.cc federated (sql/med) 61033 ha_heap.cc heap (memory) 214046 ha_innodb.cc innodb 47361 ha_myisam.cc myisam 14727 ha_myisammrg.cc merge 215091 ha_ndbcluster.cc ndb
This is also where we keep the handler programs. Now, you'll recall that the storage engine itself, for example myisam, is a separate directory. But here in the sql directory, we have programs which are responsible for determining which handler to call, formatting appropriate arguments, and checking results. In other words, the programs that begin with the letters ha are the handler interface programs, and there's one for each storage engine.
The "statement" routines in mysql-5.0/sql:
size name comment ---- ---- ------- 24212 sql_delete.cc 'delete ...' statement 1217 sql_do.cc 'do ...' 22362 sql_help.cc 'help ...' 75331 sql_insert.cc 'insert ...' 430486 sql_select.cc 'select ...' 130861 sql_show.cc 'show ...' 42346 sql_update.cc 'update ...' + many more sql_*.cc programs
Also in the sql directory, you'll find individual programs for handling each of the syntactical components of an SQL statement. These programs tend to have names beginning with sql_. So for the SELECT statement, check out sql_select.cc.
Thus, there are "statement" routines like sql_delete.c, sql_load.c, and sql_help.c, which take care of the DELETE, LOAD DATA, and HELP statements. The file names are hints about the SQL statements involved.
The "statement function" routines in mysql-5.0/sql:
size name comment ---- ---- ------- 19906 sql_string.cc strings 6152 sql_olap.cc olap (rollup) 14241 sql_udf.cc user-defined functions 17669 sql_union.cc unions
Then there are the routines for components of statements, such as strings, or online analytical processing which at this moment just means ROLLUP, or user-defined functions, or the UNION operator.
The final major directory that we'll highlight is labelled vio, for "virtual I/O".
The vio routines are wrappers for the various network I/O calls that happen with different protocols. The idea is that in the main modules one won't have to write separate bits of code for each protocol. Thus vio's purpose is somewhat like the purpose of Microsoft's winsock library.
That wraps up our quick look at the seven major directories. Just one summary chart remains to do.
