\chapter{Linux Development Tools}
\label{ch:linuxdevel}

As an operating system created by computer geeks, Linux provides a particularly nice programming environment. Although it may be a bit intimidating and confusing at first, it provides a great deal of power after the initial learning curve. In this chapter we will examine the basic Linux programming tools from the perspective of a game developer.

If you are already experienced with Linux or UNIX programming, some parts of this chapter will be of less interest to you. We will cover specific details of these tools later as we encounter them, so you will not be at a loss for skipping over sections of this chapter.

\section{Programming Editors}
\index{editors|(}
\longpage
Before we can dive into the subject of Linux game coding, we'll need a way to write our source code. Although simple editors such as \index{pico (text editor)}pico and \index{joe (text editor)}joe are sufficient for some simple tasks, they are inadequate for programming. It would be preferable to use a text editor with support for syntax highlighting, brace matching, and other features.  Let's take a look at several of the more popular code editors. If you have never written code with a UNIX-like system, it would be a good idea to try out these editors to see which one best suits your programming style. This chapter is not meant to be a reference manual or tutorial for these editors; rather, it is starting point for those who have never written code on a UNIX-like platform.

\subsection{vi}
\index{vi (text editor)|(}
\index{editors!vi|(}
vi (pronounced ``\emph{vee-eye}'' or ``\emph{vie}'') is a rather old text editor with a strong following. It is difficult to master, but once you have learned its keystrokes and its quirks, it is hard to use anything else. vi works well on just about any Linux configuration; it requires almost no processor power and very little memory. It also has the nice advantage of being present on nearly every UNIX-like system you'll encounter, including most Linux systems. vi is a standard component of every major Linux distribution.

Although vi is an old editor from the days when everyone worked over slow text terminals, it has been improved substantially by its users, and some modern versions (such as vim) are capable of syntax highlighting and other niceties. Several versions of this editor are also available for the X Window System, featuring pull-down menus and convenient shortcuts. However, these versions defeat one of the greatest features of vi: that it can be used over nearly any type of terminal. vi can be used efficiently over low-speed telnet connections, within local terminals, and even from Palm Pilots and other unusual devices. Its minimalistic interface requires very little functionality from the terminal. Graphical versions of vi throw this feature away and so can hardly be considered substitutes for the original vi editor.

vi is actually a full-screen interface to the command-based ex editing engine. ex can also be used outside of the vi editor as a command-line tool, and it can be used to add editing capabilities to shell scripts. For instance, a shell script might invoke ex to edit a configuration file automatically. ex commands can be specified within the vi editor, although a tutorial on the nuts and bolts of ex is beyond the scope of this chapter.

vi is a \emph{mode-based} editor, and this is a major source of confusion. vi has two main modes: \firstterm{command mode} and \firstterm{insertion mode}. Command mode is strictly for issuing commands to vi. For instance, one might use this mode to move to a certain line in the document and delete a word. Command mode may \emph{not} be used for typing text into the document. Anything you type in command mode will be interpreted as a vi command (and indeed there are so many possible vi commands that nearly anything you type in command mode will do something). Insertion mode, on the other hand, is strictly for typing text into the document. Most commands are not recognized in this mode, and anything you type will be inserted into the document.

vi initially starts up into command mode. To enter insertion mode, press \keysym{i}. To switch back into command mode, press Escape. This mode switching may seem like quite a hassle, but it becomes second nature after a bit of practice.
\index{vi (text editor)|)}
\index{editors!vi|)}

\subsection{Emacs}
\index{Emacs (operating system)|(}
\index{editors!Emacs|(}
GNU Emacs is uncontested as the behemoth of text editors (indeed, some think of it as an operating system in itself). It is based on its own variant of the Lisp programming language; almost all of the editor's functionality is implemented in customizable Emacs Lisp. Emacs has a loyal following among programmers, partly because absolutely every aspect of this editor can be changed by the user. I started writing this book with NEdit, but I eventually switched over to Emacs because it works well on the Linux console and doesn't require a mouse. (I'm also a bit of a Lisp enthusiast, and in that regard Emacs is a perfect match.)

Emacs is not as difficult as vi to learn initially; there is simply a lot more to learn. Its basic commands and keystrokes are not hard to get used to, but becoming fluent with Emacs is a major undertaking. Emacs includes a mail and news client, editing modes for nearly every language you'd ever want to use, several types of documentation readers, and even optional IRC clients and web browsers. Many of these features define their own sets of command keys, leaving much for the would-be user to learn. In return for this hassle, Emacs provides an enormous amount of power; it's quite literally possible to set your login shell to Emacs and never leave its environment.

To get started with Emacs, run the editor (the command is usually \code{emacs}), press \keysym{Ctrl-h}, and then \keysym{t}. The Emacs tutorial will open, and you can use it to learn the basic keys and editing modes.

\longpage
In addition to the ``real'' GNU Emacs, there are several other editors that are very similar in capabilities and usage. \index{XEmacs (text editor)}\index{editors!XEmacs}\website{XEmacs}{http://www.xemacs.org} is a code fork from GNU Emacs with a number of added features and an improved interface. \index{JED (text editor)}\index{editors!JED}\website{JED}{http://space.mit.edu/\%7Edavis/jed.html} is a programmer's editor that closely resembles Emacs but has fewer features and a smaller memory footprint.

Emacs is an ideal editor for people who appreciate a large (perhaps overwhelming) amount of functionality and don't mind a bit of a learning curve. It is excellent for those who would like to use a scripting language to add custom abilities to their editor (entire applications have in fact been written in Emacs Lisp). Emacs is available as part of nearly every Linux distribution, and it can also be obtained directly from the \website{GNU project's FTP server}{ftp://ftp.gnu.org} or one of its mirrors.
\index{Emacs (operating system)|)}
\index{editors!Emacs|)}

\subsection{NEdit}
\index{NEdit (text editor)|(}
\index{editors!NEdit|(}
NEdit, the ``Nirvana Editor,'' is a very slick code editor from Fermilab.\footnote{\ulink{http://www.nedit.org}} It is neither as absurdly customizable as Emacs nor as ubiquitous as vi, but it is much easier to learn (since its keystrokes are similar to those of many popular word processors) and powerful enough for serious work. NEdit's main downside is that it requires the X Window System to run. It is a good idea to have at least a working knowledge of another editor if you choose to use NEdit for your daily work. This book was written partly with NEdit (though I later switched to Emacs).
\suppressfloats
Although previous versions of NEdit were encumbered by a license that was not palatable to most Linux distributors, the NEdit license was changed to the GNU General Public License with the 5.1 release. The editor is now truly free software, and it is currently under active development by a team of volunteers.

\extfiguren{figures/nedit-screenshot}{The Nirvana Editor}

\index{editors!NEdit|)}
\index{NEdit (text editor)|)}
\index{editors|)}

\section{Compiling Programs Under Linux}
\index{compiling|(}
\index{gcc|(}
\longpage
We're here to talk about game programming, not the basics of C programming, so we won't discuss the language itself; however, it's quite possible that you've never worked with a C compiler under UNIX. This section demonstrates how to compile and link programs in the Linux (or more accurately, GNU/Linux) programming environment. There really isn't much to it; the compiler provides hundreds of possible command-line options, but most of them aren't necessary for our purposes.

gcc is the most popular C compiler for Linux. It was developed by the Free Software Foundation for the GNU project, and it is available on many platforms. gcc is free software, and it is included as a standard component of nearly every Linux distribution. There are several other C/\cplusplus{} compilers for Linux (such as Kai \cplusplus{} and the as-yet-unreleased Metrowerks CodeWarrior), but gcc is used for the vast majority of Linux software development. Some eschew gcc (and its \cplusplus{} brother, g++) as quirky or incomplete, but in reality it's at least as good as the other mainstream C compilers.

gcc's basic job is to compile C source code into executable programs. To compile one or more files, simply pass them to gcc on the command line as follows:

\index{gcc!basic usage}
\begin{shell}
\begin{verbatim}
$ gcc file1.c file2.c file3.c
\end{verbatim}
\end{shell}

% $

If there are no serious errors, gcc will create an executable file named \filename{a.out} in the current directory. Otherwise, you will receive warning and error messages describing the problems the compiler encountered, and gcc will not produce any compiled output. If you list multiple files on the command line, gcc will compile them separately and attempt to link them into one executable, stopping if any individual file produces an error. \index{gcc!linker interface@as linker interface}If gcc is given files that end in \filename{.o} (object files) or \filename{.a} (static libraries), it will link them directly into the executable. This allows gcc to serve as a simple interface to the linker.

\begin{warning}
\index{tab completion}
You may be in the habit of using the shell's tab-completion feature to fill in filenames. Be careful when you do this with gcc; it's easy to accidentally overwrite your source files by accidentally tab-completing the wrong filenames. This may seem obvious, but I've lost work because of it.
\end{warning}

\index{object files!creating}\index{gcc!creating object files}It is often useful to compile a C source file into an object file instead of an executable. Object files are not directly executable, but they contain the machine code translation of the source, and multiple object files can be pieced together into complete programs. To create object files, supply gcc with the \cmdline{-c} option. This will instruct gcc to skip its final linking phase and to write one object file for each source file listed on the command line.

gcc is a complex and capable tool, and it supports a large number of command-line options. We list the most important ones here.

\index{gcc!command-line options|(}
\shortpage\shortpage
\begin{bodylist}
	\item[{\cmdline{-ansi}}] Disable non-ANSI extensions, such as the \code{asm} and \code{inline} keywords. This option might be a good idea if you are concerned with portability between ANSI C compilers. However, most programmers aren't this careful about standards, and strict ANSI mode tends to break a lot of existing software.
   	\item[{\cmdline{-c}}] Compiles to an object (\filename{.o}) file instead of an executable. This is important for creating libraries.
	\item[{\cmdline{-D \emph{symbol}}}] Define the given symbol in the preprocessor. This option is convenient for setting up conditional compilation based on the system's configuration. We'll use it in some of our examples to switch between different versions of code.
	\item[{\cmdline{-o \emph{filename}}}] Outputs to the given filename instead of the default \filename{a.out}. For instance, \cmdline{-o foo} will cause the program to be compiled into an executable named \filename{foo} (or \filename{foo.exe} under Windows).
	\item[{\cmdline{-l \emph{libname}}}] Attempts to link in the given library, following the standard library naming convention. For instance, \cmdline{-lSDL} would link in \filename{libSDL.so}. See the discussion of shared libraries later in this chapter for more information.
	\item[{\cmdline{-L \emph{path}}}] Specifies an additional directory for libraries. For instance, \filename{/usr/X11R6/lib} is not normally in the library path, so it is common for X programs to specify \code{-L/usr/X11R6/lib}.
	\item[{\cmdline{-O \emph{n}}}] Sets the optimization level (from 1 to 6). The default is to perform no optimization. It's reasonable to make a practice of compiling code with \cmdline{-O2}; it doesn't mess with the structure of the code too much, and you can still (usually) debug it with gdb. In some cases this option can really speed up the compiled code. Finished products should almost always be compiled with optimization enabled.
	\item[{\cmdline{-pedantic}}] Enables a strict interpretation of the ANSI C Standard. Compile with \cmdline{-pedantic -W -Wall} if you want gcc to nag you about sloppy programming.
\end{bodylist}
\index{gcc!command-line options|)}

That's it for gcc! It has a few quirks and obscure features, but we'll get to those as we need them.\footnote{Richard Stallman's book \othertitle{Using and Porting gcc} is the authoritative guide to hacking gcc.} Like most GNU tools, gcc comes with excellent online documentation. In particular, refer to the manpage or info node for a description of gcc's command-line options.
\index{gcc|)}
\index{compiling|)}

\section{Using the Make Utility}
\index{Make utility|(}
Most game development projects consist of multiple source files, for the simple reason that it is impractical to manage thousands of lines of code in a single file. Since a large project can involve many source files, it would be wasteful to recompile everything if only one file had been changed since the program was last compiled. This happens, however, if all of the files are given to gcc at once on the command line. For instance, the Linux version of \gametitle{Civilization: Call To Power} consists of more than 500,000 lines of \cplusplus{} code in well over 100 files, and a full recompile of the entire source tree takes nearly an hour (whereas a partial rebuild assisted by Make usually takes 15 to 20 minutes).

\index{Make utility!advantages}The Make utility speeds up software development by automatically determining which files actually need to be recompiled after changes have been made. Make also eliminates the need to type long command lines to rebuild programs, since it stores all of the required commands and invokes them as needed.

Although Make has a lot of functionality, its basic usage is quite simple. It is based on \index{Make utility!targets}\firstterm{targets}, which are sets of directions for maintaining the components (object files, libraries, and so on) of a program. Targets specify the name of the component to track, the source files and other targets that the component depends on, and the commands for rebuilding the target. The instructions for building a component are called \index{Make utility!rules}\firstterm{rules}, and the list of files that a component depends on are called \index{Make utility!dependencies}\firstterm{dependencies}. When make is invoked upon a certain target, it checks that target's dependency list first. If any of the dependencies have been changed since the target was last rebuilt, the target's rules are executed. Make also recursively rebuilds any out-of-date targets in the dependency list. This is extremely convenient for large, modular programming projects.

\subsection{Creating Makefiles}
Make looks for targets and rules in a file called \index{Make utility!makefile}\filename{Makefile} or \filename{makefile}. This file can contain any number of targets. If Make is started with no command-line options, it automatically attempts to rebuild the first target it encounters. Consider the following makefile:

\longpage
\index{Make utility!makefile!example}
\begin{codesegment}
\begin{verbatim}
program: file1.c file2.c graphics.a
        gcc -c file1.c file2.c
        gcc file1.o file2.o graphics.a -lSDL -o program

graphics.a: graphics.c draw.c
        gcc -c graphics.c draw.c
        ar rcs graphics.a graphics.o draw.o
        ranlib graphics.a
\end{verbatim}
\end{codesegment}

This file describes how to build an executable called \filename{program} and a static library called \filename{graphics.a}. (Don't worry about the commands for building the library---we'll discuss libraries later in this chapter.) \code{program} depends on \filename{file1.c}, \filename{file2.c}, and \filename{graphics.a}. If any of these have been modified since \filename{program} was last built, Make will rebuild \code{program}. \filename{graphics.a} is also a target, and it depends on \filename{graphics.c} and \filename{draw.c}. The indented lines under each target are rules. If program needs to be rebuilt, Make will execute the two rules that have been provided. \index{Make utility!makefile!indentation}These lines must be indented with tab characters; spaces will not work. Make is rather particular about syntax.

\subsubsection{Variable Substitution}
\index{Make utility!variables|(}
\index{Make utility!environment}The Make utility provides convenient access to environment variables. Makefiles can set, combine, and retrieve environment variables as text strings and can include these variables in targets and rules. It is common to use the variable \index{CC@\code{CC} (variable)}\code{CC} to represent the C compiler command (which in our case is \cmdline{gcc}), \index{CFLAGS@\code{CFLAGS} (variable)}\code{CFLAGS} to represent the standard set of command-line options to pass to the compiler, and \index{LDFLAGS@\code{LDFLAGS} (variable)}\code{LDFLAGS} to represent the options to pass to the linker (which is normally just the C compiler but is sometimes explicitly invoked with the \cmdline{ld} command). For example, the previous makefile can be rewritten as follows to take advantage of variable substitution:

\bigbreak
\shortpage
\begin{codesegment}
\begin{verbatim}
CC=gcc
CFLAGS=-O2 -W -Wall -pedantic
LIBS=-lSDL -lpthread

program: file1.c file2.c graphics.a
        $(CC) $(CFLAGS) -c file1.c file2.c
        $(CC) file1.o file2.o graphics.a $(LIBS) -o program

graphics.a: graphics.c draw.c
        $(CC) $(CFLAGS) -c graphics.c draw.c
        ar rcs graphics.a graphics.o draw.o
        ranlib graphics.a
\end{verbatim}
\end{codesegment}

As you can see, variables are substituted into the makefile with the \code{\$(VARNAME)} notation. This is a literal text substitution, and it takes place before the rule is otherwise processed. What if you want to add to the end of a variable without destroying its old contents? You might try something like this:

\begin{codesegment}
\begin{verbatim}
FOO=bar
FOO=$(FOO) baz
FOO=$(FOO) qux
\end{verbatim}
\end{codesegment}

At a glance, it would appear that the \code{FOO} variable would end up with the value \code{bar baz qux}. However, Make does not normally evaluate variables until they are used (in targets), so \code{FOO} actually ends up with the string \code{\$(FOO) qux}. There are two solutions to this problem. GNU Make (the default Make on Linux systems) provides a \code{:=} operator for assignments, which causes its right-hand side to be evaluated before the variable is assigned. It also provides a \code{+=} operator for directly appending to variables. A more portable solution would be to assign \code{bar}, \code{baz}, and \code{qux} to three different variables and to combine them all at once:

\begin{codesegment}
\begin{verbatim}
BAR=bar
BAZ=baz
QUX=qux
FOO=$(BAR) $(BAZ) $(QUX)
\end{verbatim}
\end{codesegment}

% $  -  ignore this line

This (hacked) solution allows the variable \code{FOO} to be constructed correctly when it is used in a rule. It is a rather ugly way to do so, however, so we suggest using the GNU Make extensions.

Although the use of variables might lengthen a makefile, they can provide a nice bit of abstraction. Variables make it easy to modify the options used throughout the build process without changing the whole makefile.
\index{Make utility!variables|)}

\subsubsection{Implied Rules}
\index{Make utility!rules!implied|(}
Since C files are almost always compiled with the \code{cc} command (which is a symbolic link to the \code{gcc} command on Linux machines), there is really no need to specify build rules for each source file in the project. Make allows for \emph{implied} build rules. That is, if a target is followed by no rules and does not specify any dependencies (or it simply does not exist), Make will attempt to use a \emph{default} build rule based on the target's file extension.

For example, let's say that \filename{foo.c} is a C source file containing the function \code{bar} and that \filename{main.c} is a C source file containing a \code{main} function that calls \code{bar}. The following makefile will build the program. Notice that there is no target for \filename{foo.o}---it is referenced by the \code{foo} target, and Make assumes that it should create the target by compiling the file \filename{foo.c}. (Actually, Make knows of several different source file types, C being perhaps the most common.) When Make automatically invokes the C compiler, it adds the \code{CFLAGS} variable to the command line.

\begin{codesegment}
\begin{verbatim}
CFLAGS=-O2 -W -Wall -pedantic
foo:	foo.o main.c
        gcc foo.o main.c -o foo
\end{verbatim}
\end{codesegment}
\index{Make utility!rules!implied|)}

\subsubsection{Phony Targets}
\index{PHONY@\code{.PHONY} (Make target)|see{Make utility, targets, phony}}
\index{Make utility!targets!phony|(}
Programmers often use Make for purposes other than building executables. It's really a general-purpose project management tool. For instance, I'm currently using a makefile so that I don't have to delete a bunch of files and then run \LaTeX, \textit{MakeIndex}, and dvips every time I want a preview of this book. Consider the following makefile:

\begin{codesegment}
\begin{verbatim}
foo: foo.c
        gcc foo.c -o foo

clean:
        rm *.o
        rm foo
\end{verbatim}
\end{codesegment}

The \code{clean} target has no dependencies and is therefore built only when it is specifically requested on the command line. The command \code{make clean} causes all object files as well as the executable \code{foo} to be deleted and therefore serves to force a complete rebuild of the project. Programmers commonly include a \code{clean} target in their makefiles for convenience.
			
In a more general sense, Make is often used as a simple interface to complex commands. Targets used for this purpose do not actually describe a build process but rather a set of commands to be executed when the target is requested. But what happens if such a ``phony'' target has the same name as a file in the current directory? For instance, what if there is a file called \filename{clean}? Make would detect that this file exists and would decide not to build the target.
		
Make provides a special pseudo-target called \code{.PHONY} for this purpose. \code{.PHONY} takes a dependency list, just as other targets do, but no build rules. \code{.PHONY}'s dependencies are marked as phony targets and will always be built when requested, regardless of any existing file by the same name. Here is the previous makefile, rewritten to use the \code{.PHONY} target.
			
\begin{codesegment}
\begin{verbatim}
foo: foo.c
        gcc foo.c -o foo

.PHONY: clean

clean:
        rm *.o
        rm foo
\end{verbatim}
\end{codesegment}
\index{Make utility!targets!phony|)}

\subsection{Error Handling}
\index{Make utility!error handling|(}
In the event of an error, Make immediately stops and prints an error message (in addition to whatever was printed by the command that failed). Make detects errors by the return codes of the rules it executes: a return code of zero indicates success, and anything else indicates an error. Most UNIX commands follow this convention. If there is a syntax error in the makefile itself, Make will complain about it and exit.
\index{Make utility!error handling|)}
\index{Make utility|)}

\section{Working with Libraries}
\index{libraries|(}
Libraries provide a way to package code into reusable binary modules. Linux software can use two types of libraries: \emph{static} and \emph{shared}. A static library is simply a collection of object files that have been archived into one file with a symbol table. Static libraries have a file extension of \filename{.a}, and they can be linked into programs as normal object files. A shared library is similar to a static library, except that it permanently resides in a separate file and is never directly linked into an application. Shared libraries are linked at runtime by the operating system's dynamic linker.

\subsection{Static Libraries}
\index{libraries!static|(}
Static libraries are extremely simple to create and use. Once you have created the object files you wish to package as a library, combine them with the ar utility:

\begin{shell}
\begin{verbatim}
$ ar rcs something.a file1.o file2.o file3.o
\end{verbatim}
\end{shell}
% $

\index{ar}ar is a simple archiving utility. The \cmdline{r} option specifies an operating mode: it tells ar to add the given files to the archive, replacing any existing files with the same names. The \cmdline{c} option specifies that the archive should be created if it does not already exist. Finally, \cmdline{s} informs ar that this is an archive of object files (that is, a static library) and that a symbol table should be added. Optionally, you can leave out the \cmdline{s} flag and use the \index{ranlib}ranlib utility to add the symbol table; the resulting file will be equivalent.
		
\index{gcc!adding static libraries}\index{libraries!static!using}To use a static library, pass it to gcc just as you would pass a normal object file. gcc will recognize the \filename{.a} file extension as an archive of object files.
\index{libraries!static|)}

\subsection{Shared Libraries}
\index{libraries!shared|(}
\index{libraries!shared!advantages}Shared libraries are a bit more complex to manage than static libraries, but they are often worth the extra effort. Shared libraries are not stored in executables that use them; they are independent files that are linked into executables at runtime. In many cases shared libraries can be updated without recompiling the programs that depend on them. It is possible for the operating system to load a shared library into memory once, for use by multiple applications.

\index{libraries!shared!naming}Shared libraries follow a very specific naming scheme designed to keep incompatible versions separate. Each shared library should be given a unique base name (or \emph{soname}) of the form \filename{libFooBar.so.\emph{n}}, where \emph{n} is a major release number. The \firstterm{major} release number should be incremented whenever backward compatibility is broken. \firstterm{Minor} version and release numbers (indicating slight revisions that shouldn't affect compatibility) are added to the end of the base name, so that the final name looks something like \filename{libFooBar.so.2.1.3}.

The \index{ldconfig}ldconfig utility imposes sanity upon the various versions of a library that might exist. It searches for libraries in a certain set of directories, usually specified in \filename{/etc/ld.so.conf} or the environment variable \code{LD\_LIBRARY\_PATH}. For each library it finds with a name in the form \filename{libSomething.so.\emph{m.n.r}}, it creates a symbolic link for \filename{libSomething.so.\emph{m}}. If two libraries have the same base name, ldconfig creates a symbolic link to the later version. Applications reference these symbolic links rather than the full names of the libraries. If a new release of a library is installed, ldconfig updates the symbolic link, and all applications that use the library will automatically reference the new version.

\subsubsection{Creating Shared Libraries}
\index{libraries!shared!creating|(}
Shared libraries are simple to create. First, compile your sources into object files with the \cmdline{-fPIC} flag. This causes gcc to output position-independent code, which is more palatable to the dynamic linker. Then link with gcc's \cmdline{-shared} flag. You will also need to inform the linker of the soname you wish to use. To see how this is done, take a look at the following example:

\begin{shell}
\begin{verbatim}
$ gcc -fPIC -c foo.c bar.c
$ gcc -shared -Wl,-soname,libFooBar.so.1 foo.o bar.o -o \
          libFooBar.so.1.1.1
$ su
Password:
# install -m 0755 libFooBar.so.1.1.1 /usr/lib
# ldconfig
# ln -s /usr/lib/libFooBar.so.1 /usr/lib/libFooBar.so
# exit
\end{verbatim}
\end{shell}
% $

\index{libraries!shared!installing}The first command produces the object files \filename{foo.o} and \filename{bar.o}, and the second creates the shared library. Note the use of the \cmdline{-Wl} flag to send options directly to the linker. The library is then installed to the standard location with a reasonable set of permissions (note: this step will require write permission to \filename{/usr/lib}), and ldconfig is executed to set up the proper symbolic link. Finally, another symbolic link is created to the base name of the library. This allows the library to be linked into a program with the \cmdline{-lFooBar} gcc option.
\index{libraries!shared!creating|)}

\subsubsection{Using Shared Libraries}
\index{libraries!shared!using|(}
Shared libraries are extremely versatile. Once they are linked into an application, they act as part of the program, except that the actual linking is done at runtime. Shared libraries can also be manually loaded and accessed via the \code{dlopen} C interface.
		
To link a properly installed shared library into an application, use gcc's \cmdline{-l} option. For instance, to link with \filename{/usr/lib/libFooBar.so} (which is a symbolic link to \filename{/usr/lib/libFooBar.so.1}), specify \cmdline{-lFooBar}. If the library resides in a nonstandard directory (such as the X libraries in \filename{/usr/X11R6/lib}), use the \cmdline{-L} option (\cmdline{-L/usr/X11R6/lib}). When the application is run, the runtime linker attempts to locate the library (by name) and match its symbols with the symbols the application thinks it should have. If any symbols are missing, the linker reports an error, and the application fails to load. Otherwise, the shared library becomes part of the application.

\index{dlopen@\code{dlopen}}\code{dlopen}/\code{dlsym} is another approach to using shared libraries. This interface allows you to manually open and access shared object files. For example, suppose that \filename{libfoo.so} is a shared object file containing a function \code{bar}. The following example will open the file and call the function:

\begin{codesegment}
\begin{verbatim}
#include <dlfcn.h>
/* dlfcn.h provides the dlopen() interface */

int main()
{
    void *handle;
    void (*bar)(void);

    /* Open the library and save the handle */
    handle = dlopen("libfoo.so",RTLD_NOW);
    if (handle == NULL) {
        /* dlerror() returns an error message */
        printf("dlopen failed: %s\n",dlerror());
        return 1;
    }

    /* Attempt to find the address of bar() */
    bar = dlsym(handle,"bar");
    if (bar == NULL) {
        printf("dlsym failed: %s\n",dlerror());
        return 1;
    }

    /* Good, we found bar(), so call it */
    bar();

    /* Close libfoo.so */
    dlclose(handle);

    return 0;
}
\end{verbatim}
\end{codesegment}

The \code{RTLD\_NOW} flag in \code{dlopen} indicates that \code{dlopen} should attempt to resolve all symbols that the shared library depends on immediately. (Shared libraries can depend on other libraries, so this is a serious concern.) The other option is \code{RTLD\_LAZY}, which instructs the dynamic linker to resolve symbols as it encounters them.

Sometimes a dynamically loaded library needs to access symbols in the parent application. To allow these symbols to be resolved, compile the application with the \cmdline{-rdynamic} option and the \cmdline{--export-dynamic} linker option. (The correct syntax is \cmdline{-wl,--export-dynamic}.) The \cmdline{-rdynamic} option allows unresolved symbols in a shared library to be matched with symbols in the parent application, and the \cmdline{--export-dynamic} option instructs the linker to generate extra symbol information suitable for this purpose.
\index{libraries!shared!using|)}
\index{libraries!shared|)}
\index{libraries|)}

\section{Linux Linker Quirks}
\index{ld|(}
\longpage
The Linux linker, GNU ld, is a complex but quirky tool. Although a complete discussion of ld is far beyond the scope of this book, here are some hints that might make your life easier.

ld (and therefore gcc) is sensitive about the order in which libraries and object files are specified on the command line. If \filename{libfoo.so} depends on \filename{libbar.so}, you must specify \filename{libfoo.so} first (as counterintuitive as this may be). The reason is that ld keeps track only of unresolved symbols as it links. If \filename{libfoo.so} and \filename{libbar.so} depend on each other, one of the libraries will have to be specified twice (for example, \cmdline{-lfoo -lbar -lfoo}). This is different from the behavior of Visual \cplusplus{}'s linker, and it causes headaches when porting games from Windows. If the linker can't find a symbol but you're sure that you've given it the right libraries, double-check the order in which they're specified on the command line.

\index{LD\_LIBRARY\_PATH@\code{LD\_LIBRARY\_PATH} (variable)}The Linux runtime linker does not respect the \code{LD\_LIBRARY\_PATH} environment variable with setuid root executables. This is a bit annoying, but it is important for security; consider the implications of allowing users to modify the library search path for executables that are run as the root user.

\index{ld!name collisions}Name collisions are annoying, especially because they can be extremely hard to trace. The \cmdline{-warn-common} flag causes a warning to be printed whenever symbols (global variables, for instance) are combined between object files.

\index{ld!search path}Finally, keep in mind that some Linux distributions (notably Red Hat, at least as of the time of this writing) do not recognize \filename{/usr/local/lib} as a library directory, and hence any libraries placed there will not be accessible. You can fix this by editing \filename{/etc/ld.so.conf}. Remeber to run the ldconfig program after editing the library path list.
\index{ld|)}

\section{Debugging Linux Applications}
\index{debugging|(}
Linux's programming environment provides support for interactive debugging. The gcc compiler can generate symbol information for debugging, and several debuggers are available. We will begin by demonstrating how to add debugging information to an executable and then take a brief tour of two popular debugging environments for Linux.

\subsection{Compiling for Debugging}
\index{debugging!compiling for}
In order for a debugger to analyze an executable's behavior in a way that is useful to humans, it needs to determine the exact locations of the program's variables and function entry points. This requires a bit of help from the compiler; applications must be specifically compiled for debugging, or symbolic debuggers will be useless. To compile a program with the necessary debugging support (and in particular, support for the gdb debugger), use the \cmdline{-ggdb} flag:

\begin{shell}
\begin{verbatim}
$ gcc -ggdb foo.c -o foo
\end{verbatim}
\end{shell}

% $

It is a good idea to disable optimization when debugging (that is, do not use the \cmdline{-O\emph{n}} compiler option). Although gcc and gdb allow you to debug optimized executables, the results might be a bit surprising (since optimization, by definition, changes the internals of a program).

Although programmers sometimes use the \cmdline{-fomit-frame-pointer} compiler option in the hope of improving performance, this option is incompatible with debugging in most cases. (It causes the compiler to omit the instructions that usually keep track of an important piece of position information.) Compiling an executable for debugging will increase its size and most likely decrease its performance; executables intended for public release should not be compiled for debugging.

\subsection{gdb}
\index{debugging!with gdb|(}
\index{gdb!capabilities}
\index{gdb|(}
The GNU debugger, known as gdb, is the primary debugger for Linux. It allows you to single-step programs, inspect variables while programs are running, and analyze \index{core pies}\filename{core} files (memory dump files, usually named \filename{core}, generated automatically when applications crash, affectionately dubbed ``core pies''). gdb is an extremely powerful tool, but its interface is likely to throw beginners for a loop.

gdb is a text-based interactive debugger. Once a program is loaded into the debugger, gdb accepts commands to direct the program's operation. There are lots of commands, but there is also a nice online help facility. Simply type \code{help} for an index.

\subsubsection{A Trivial Example}
\index{gdb!example|(}
The following program is supposed to print the numbers from 0 to 9. However, it has a bug. There is an extra semicolon after the \code{for} loop, which causes the \code{printf} statement to be separated from the loop. This is a fairly common error, simple to fix but often hard to locate. gdb is great for pinpointing this type of error, since it lets you see exactly what's happening in the program.

\begin{codesegment}
\begin{verbatim}
#include <stdio.h>

int main()
{
    int i;
    for (i = 0; i < 10; i++);
        printf("Counter is now %i\n",i);
    return 0;
}
\end{verbatim}
\end{codesegment}

First, we compile the program and test it:

\begin{shell}
\begin{verbatim}
$ gcc -ggdb buggy.c -o buggy
$ ./buggy
Counter is now 10
\end{verbatim}
\end{shell}
% $

Yikes! That shouldn't have happened---we'll use gdb to figure out what's going on. To load a program into gdb, pass the name of the program on the command line:

\begin{shell}
\begin{verbatim}
$ gdb buggy
GNU gdb 4.18
Copyright 1998 Free Software Foundation, Inc.
\end{verbatim}
\emph{license notice removed}
\begin{verbatim}
This GDB was configured as "i386-redhat-linux"...}
\end{verbatim}
\end{shell}

% $

gdb is now ready to accept commands. We will set a breakpoint (a position at which gdb suspends the process for inspection) and then start the program:

\begin{shell}
\begin{verbatim}
(gdb) b main
Breakpoint 1 at 0x80483d6: file buggy.c, line 6.
(gdb) r
Starting program: /home/overcode/book/test/buggy

Breakpoint 1, main () at buggy.c:6
6        for (i = 0; i < 10; i++);
\end{verbatim}
\end{shell}

\index{gdb!adding breakpoints}The \code{b} command (short for breakpoint) sets a breakpoint at the specified function name. We also could have specified a line number or an actual memory address. In this case, gdb reports that breakpoint \#1 has been successfully added for line 6 of the source file \filename{buggy.c}. The \code{r} command starts the program's execution. Since we have set a breakpoint on the function \code{main}, gdb immediately suspends the program and prints the current line (which happens to be the \code{for} loop with the error). We will now use the \code{n} (next) command to single-step the program:

\begin{shell}
\begin{verbatim}
(gdb) n
7                printf("Counter is now %i\n",i);
\end{verbatim}
\end{shell}

\index{gdb!single-stepping}The \code{n} command runs the program until it reaches a different line of code, so this is the expected result. After executing this line of code, the program should continue through the loop. Let's see what happens:

\begin{shell}
\begin{verbatim}
(gdb) n
Counter is now 10
8        return 0;
\end{verbatim}
\end{shell}

\index{gdb!listing source}That's not good---the program moved on to line 8, meaning that the loop is no longer running. It is now fairly obvious that line 7 is not part of the loop. We can take a quick look at the source code with the \code{l} (\code{list}) command:

\begin{shell}
\begin{verbatim}
(gdb) l
3       int main()
4       {
5               int i;
6               for (i = 0; i < 10; i++);
7                       printf("Counter is now %i\n",i);
8               return 0;
9       }
\end{verbatim}
\end{shell}
\index{gdb!example|)}

Hopefully, at this point the programmer would notice the extra semicolon and fix the problem. (One would hope that the programmer would have found it before the gdb session, but we all make dumb mistakes.) gdb doesn't eliminate the need to study the source code for errors---it just helps you focus on the right areas.

\subsubsection{Accessing Data}
\index{gdb!snooping on data}gdb can report the value of any variable that is accessible from the current scope in the program. It can also modify variables while the program is running. To view a variable, use the \code{p} (code{print}) command. \code{p foo} would report the current value of \code{foo} (if \code{foo} is visible from the current location in the program). There is also a \code{printf} command, which behaves much like its C namesake. To modify a variable, use the \code{set var varname=value} command.

Programmers frequently need to track variables as they change throughout the program. With gdb, you can define a list of variables to display each time the program is suspended. The \code{display} command adds variables to this list, and the \code{undisplay} command removes them.

\index{gdb!watchpoints}gdb's \firstterm{watchpoints} are useful for tracing variable corruption. A watchpoint is a hardware trap placed on a memory location. If that memory location is read from or written to, gdb will catch the access and pause the program for inspection. Since watchpoints are independent of the semantics of a particular programming language, they can be used to trace memory corruption from misplaced pointers. There are three types of watchpoints: \firstterm{write-only}, \firstterm{read-only}, and \firstterm{access}. Write-only watchpoints detect modifications but not reads, read-only watchpoints detect reads but not modifications, and access watchpoints detect any type of access to the given memory address. The \code{watch}, \code{rwatch}, and \code{awatch} commands correspond to these types of watchpoints. These three commands take a symbol name as an argument. Use the \code{enable} and \code{disable} commands to toggle watchpoints. \code{info breakpoints} prints a list of all breakpoints and watchpoints.

\subsubsection{Viewing the Stack}
\index{gdb!examining the stack}It is often useful to examine the call stack. Programs often crash because of invalid data passed to the C library (notably the \code{free} function), and a normal gdb crash report will list the name and memory address only of the function where the crash actually occurred. This is essentially useless in a typical program that makes hundreds of calls to these functions; the bewildered programmer would have no idea where the erroneous library call took place. For instance, the following is the late-night programmer's worst nightmare (other than a copy of \code{eggdrop} found running in an unknown account):

\begin{shell}
\begin{verbatim}
Program received signal SIGSEGV, Segmentation fault.
0x401371eb in free () from /lib/libc.so.6
\end{verbatim}
\end{shell}

This message indicates a crash in the C library itself, resulting from an invalid call to \code{free}. This information is almost useless to us, since most nontrivial C programs make hundreds of calls to \code{free}. Since the segmentation fault occurred in a function outside of our program (and, more importantly, in one that does not contain debugging information), gdb cannot simply tell us the line number of the crash location.

\index{gdb!backtracing}gdb solves this problem with its \code{backtrace} command. When a program crashes under gdb, \code{backtrace} will display the names of all functions that are currently active on the stack. In this particular program, \code{backtrace} provides us with the following information:

\begin{shell}
\begin{verbatim}
(gdb) backtrace
#0  0x401371eb in free () from /lib/libc.so.6
#1  0x804b85e in ParseSurf (f=0x8112568, buf=0xbfffd6f0 "SURF 0x10")
    at ac3dfile.c:252
#2  0x804c71f in ParseObject (scene=0x8112620, f=0x8112568, 
    buf=0xbfffe34c "OBJECT poly") at ac3dfile.c:545
#3  0x804c7c3 in ParseObject (scene=0x8112620, f=0x8112568, 
    buf=0xbffff380 "OBJECT world") at ac3dfile.c:559
#4  0x804cb74 in AC3D_LoadSceneFile (filename=0xbffff957 "crash.ac")
    at ac3dfile.c:829
#5  0x804d7a2 in main (argc=3, argv=0xbffff7e4) at ac3dembed.c:15
\end{verbatim}
\end{shell}

Aha! The invalid \code{free} call occurred while the program was executing line 252 of \filename{ac3dfile.c}, in the function \code{ParseSurf}. We now know exactly where the erroneous call to \code{free} was made, and we can use standard debugging techniques to figure out why this particular line caused a crash. (A hint, in case you find yourself in this situation: crashes in \code{free} are usually due to \index{heap corruption}heap corruption, which can result when a program overruns allocated memory buffers.)

\code{backtrace}'s output will be useless if the program has corrupted the stack in some way. If this happens, you're in for a challenge, but at least you'll know to look for memory accesses that might cause stack corruption. If you're feeling particularly adventurous, you can try setting a watchpoint on an address in the stack, but it could easily be triggered by legitimate accesses as well as bugs.

\subsubsection{Remote Debugging}
\index{gdb!remote debugging}Linux is a network-enabled multiuser operating system, and it makes remote debugging extremely easy. Remote debugging (that is, debugging from a different console than the one on which the program is running) is useful when you're dealing with applications that take over the screen or keyboard (as is frequently the case with games). Anyone who has had to debug a full-screen OpenGL game can attest to the importance of remote debugging.

gdb supports two types of remote debugging. It provides support for debugging over a serial connection, which is useful for kernel debugging but probably overkill for game development. Serial debugging is important when one cannot count on the stability of the operating system itself (and therefore the stability of the debugger). gdb also has the ability to attach to programs that are already running. You start the buggy application (compiled for debugging) normally and launch gdb via a remote login from a second computer. You then attach gdb to the buggy application. Now you can use the debugger without fear of losing control of the console. Note that gdb is running on the same computer as the application; it is just controlled from a remote terminal.

\index{gdb!attaching to processes}To attach gdb to a running program, first use the \code{file} command with the name of the executable you want to debug:

\begin{shell}
\begin{verbatim}
(gdb) file foo
Reading symbols from foo...done.
\end{verbatim}
\end{shell}

gdb is now ready to attach to a running copy of \code{foo}. Use the \code{attach} command with the process ID of the running application:

\begin{shell}
\begin{verbatim}
(gdb) attach 3691
Attaching to program: /home/overcode/test/foo, Pid 3691
Reading symbols from /usr/X11R6/lib/libX11.so.6...done.
Reading symbols from /lib/libc.so.6...done.
Reading symbols from /lib/ld-linux.so.2...done.
0x4016754e in __select () from /lib/libc.so.6
\end{verbatim}
\end{shell}

The debugger has suspended \code{foo}, and you can now use the normal gdb debugging commands, just as if you had started \code{foo} under gdb directly.

\subsubsection{Debugging Multithreaded Applications}
\index{gdb!threads}Games frequently use multiple threads of execution to smoothly coordinate the various parts of the game engine. Unfortunately, multithreading has always been a thorn in the side of source-level debuggers. gdb can debug multithreaded applications locally, \emph{but it cannot attach to more than one thread of an application that is already running}. This is because threads under Linux are implemented as separate processes that share an address space, and each thread has a separate process ID. gdb needs to catch threads as they are created in order to debug them.

When gdb suspends a multithreaded application, it suspends all of its threads at once. This allows you to switch between threads and examine the program without the fear that something will change in the background. Keep in mind, however, that single-stepping a multithreaded application may result in more than one line of code being executed in some threads; gdb only directly controls the execution of one of the threads.

Working with threads in gdb is not particularly difficult. The \code{info threads} command prints a list of threads owned by the application, and the \code{thread }\emph{id} command switches between threads. gdb assigns its own thread IDs to a program's threads; these are listed in the leftmost column of the \code{info threads} display. To apply a gdb command to one or more threads, use \code{thread apply }\emph{ids}, where \emph{ids} is a list of thread IDs or ``all.''

\longpage
Unfortunately, multithreading causes problems with watchpoints. gdb can reliably detect memory changes only within the current thread; it might fail to detect a change caused by another thread. Watchpoints can still be useful in multithreaded applications, but you will have to determine which thread is causing the change on your own.
\index{gdb|)}
\index{debugging!with gdb|)}

\subsection{ddd}
\index{debugging!with ddd|(}

\extfigureheightn{figures/ddd-screenshot}{Screen shot of ddd}{3in}

Many people find the gdb interface hard to live with, and so several front ends have been created. Perhaps the best-known front end is the Data Display Debugger, or ddd. This program adds a nice interface to gdb, perhaps limiting its usefulness to hardcore gdb fans but certainly making life considerably easier for beginners.

ddd requires only a minimal introduction, because it closely mirrors the functionality provided by gdb (and with good reason; it \emph{is} gdb, inside a GUI wrapper). To begin a debugging session with ddd, choose \menucommand{Open Program} from the File menu. You may then set breakpoints and control execution with ddd's toolbar and menus. ddd allows you to attach to running programs after the corresponding executables have been opened. If you need a piece of functionality provided by gdb but not ddd, you can send commands directly to gdb with the console at the bottom of the screen.
\index{debugging!with ddd|)}
\index{debugging|)}

\subsection{Bug Tracking}
\index{debugging!bug tracking|(}\index{bug tracking|(}A very important but often overlooked aspect of debugging is keeping track of the information pertaining to identified bugs. A game development team might easily receive hundreds of bug reports during the course of a game's development and beta test, and it is essential to organize these reports so that the developers can easily verify and resolve the bugs. Bug-tracking software is every bit as important to a serious game development operation as the debugger itself.

The Mozilla project's Bugzilla has emerged as one of the best and most widely used bug-tracking systems. Bugzilla is a Web-based system written in Perl and designed for use with the popular Apache Web server and MySQL database server. With it, users can report bugs, check to see if a reported bug has been resolved, and browse through other bugs that have been reported. Bugzilla is covered under the Mozilla Public License, and it can be freely used and modified. It is relatively simple to install if MySQL and Apache are already configured. To see Bugzilla in action, visit \ulink{http://bugzilla.mozilla.org}.
\index{debugging!bug tracking|)}\index{bug tracking|)}

\section{Project Management with CVS}
\index{CVS|(}Collaboration is the only way to accomplish a large programming task in any reasonable amount of time, but coordination can become difficult even with only two or three developers working on a project. In particular, care must be taken to ensure that one programmer's work does not overwrite another's. It is also important to keep development and release versions of a piece of software separate.

\index{version control}These problems are addressed by \firstterm{version control} software. The capabilities of these tools vary, but we will discuss the most popular tool, the \index{CVS!overview}Concurrent Version System (CVS). CVS is a tool for managing \firstterm{repositories}, which are simply directory trees of source code with a bit of extra control information. Each project in a repository is called a \index{CVS!modules}\firstterm{module}. Modules are initially \firstterm{imported} into the repository, and additional files can subsequently be added. Individual developers can \firstterm{check out} modules, make changes, and \firstterm{commit} the updated files back into the master source repository when they are finished. CVS keeps a record of the changes made to each file and allows individual files or entire trees to be tagged with version designations. Developers can also create separate \firstterm{branches} of a source tree if they intend to make substantial and possibly dangerous modifications. Successful branches can later be \firstterm{merged} back into the main source tree.

\index{CVS!locking}What if two developers make (conflicting) modifications to the same file? Some version control systems physically prevent this with ``strong'' file locking, but CVS allows it. In the case of a conflict, CVS will prevent the most recent modification from being committed to the repository. Instead, it will provide the developer with a \firstterm{reject file} listing the source code lines in question. The developer must then merge the two sets of changes by hand and then recommit the file. This would obviously be a continuous hassle without a bit of coordination between developers; CVS does not replace communication and management. It is best to avoid conflicts in the first place, but they are sometimes inevitable.

CVS is a free tool, a fact that has played a role in its almost universal acceptance in the Linux development community. Free software would not be where it is today without CVS.

\subsection{A Brief Tutorial on CVS}
\index{CVS!example|(}We will now work through a complete example of using CVS to manage a small project. Suppose that we have four files: \filename{Makefile}, \filename{foo.c}, \filename{foo.h}, and \filename{main.c}. These constitute a small programming project, but their contents are not relevant for our purposes. We would like to create a CVS module out of these files so that other developers can join in. For now we'll assume that all developers have local access to the machine hosting the repository, though it is possible to use CVS remotely.

\subsubsection{Creating a CVS Module}
\index{CVS!project setup|(}The first step is to create a repository, if one does not already exist. A repository can host any number of modules, and it is common for software teams to use one central repository for all of their projects (this facilitates routine backups, among other things). To create a repository, set the \index{CVSROOT@\code{CVSROOT} (variable)}\code{CVSROOT} environment variable to a suitable location and issue the command \code{cvs init}. This will create the CVS repository directory and initialize several important control files. The location of \code{CVSROOT} is not especially important, but make sure that your account has write access to it. If a repository already exists, make sure the \code{CVSROOT} environment variable is set to the repository's location.

\begin{shell}
\begin{verbatim}
$ export CVSROOT=/home/overcode/cvs
$ cvs init
\end{verbatim}
\end{shell}

\begin{warning}
Do not create a CVS repository in the same directory as a project you wish to add to the repository. This would result in an infinite loop. CVS is remarkably brain-dead about some things, but it's a useful tool nonetheless.
\end{warning}

Now we need to import the initial set of source files to the repository. Assuming that we are in the project's directory and that \code{CVSROOT} is set correctly, we use the command \code{cvs import -m "Some descriptive comment" projname vendor label}, where \emph{projname} is the name of the project (``foobar'' for now), \emph{vendor} is the name of the organization responsible for the project (which doesn't matter too much to us), and \emph{label} is an indication of the software's progress, such as \code{initial} or \code{start}. This command will copy the project's files into the CVS repository under the given project name. The project is now controlled by CVS, and the original files can safely be deleted.

For the purposes of our tutorial, the correct \code{import} command is \code{cvs import -m "CVS Example" example xyz start}. This command must be executed from the directory containing the four source files, and \code{CVSROOT} must point to the initialized repository.

\bigbreak
\begin{shell}
\begin{verbatim}
$ cvs import -m "CVS Example" example xyz start
N example/foo.h
N example/foo.c
N example/main.c
N example/Makefile

No conflicts created by this import
\end{verbatim}
\end{shell}
\index{CVS!project setup|)}

% $

\subsubsection{Working with a CVS Project}
Once a project is in CVS, multiple developers can safely access the project's files without too much fear of colliding with one another. Each developer should make his or her own working copy of the project (with the \code{cvs checkout \emph{projname}} command). For our tutorial, switch to a new directory and type \cmdline{cvs checkout example}. CVS will copy the four example files to a new directory called \filename{example}. You can now make any modifications you like to the files, and other developers can join in by checking out their own copies of the project.

\begin{warning}
Try to avoid editing files in a CVS repository directly. Doing so defeats the whole purpose of CVS, and it is sure to cause massive headaches for the next person to commit a working copy to the repository. CVS-controlled files are marked read-only to help prevent this from happening. CVS is not designed to be a nuisance (quite the opposite, actually), but it requires a bit of cooperation from its users.
\end{warning} 

\index{CVS!committing}When you have finished making modifications to a project's files, you should commit them back into the repository for everyone else to use. For example, suppose that we have corrected an error in \filename{foo.c}, and we want to integrate this modification back into the master source tree. From the directory containing our working copy, we would type \code{cvs commit -m "Description of changes"}.

\begin{shell}
\begin{verbatim}
$ cvs commit -m "Fixed a typo."
cvs commit: Examining .
Checking in foo.c;
/home/overcode/testcvs/example/foo.c,v  <--  foo.c
new revision: 1.1; previous revision: 1.0
done
\end{verbatim}
\end{shell}
% $

\index{CVS!resolving conflicts}What if someone has made conflicting modifications to the master copy of \filename{foo.c}? It would be bad to simply overwrite those changes; that person may have spent a lot of time on them. CVS obviously doesn't know how to rewrite source code to integrate changes (beyond a certain, very limited capability), so we must intervene and merge the changes ourselves. The transaction might look something like this:

\begin{shell}
\begin{verbatim}
$ cvs commit
cvs commit: Examining .
cvs commit: Up-to-date check failed for `foo.c'
cvs [commit aborted]: correct above errors first!
\end{verbatim}
\end{shell}

% $

This response indicates that somebody else has modified \filename{foo.c}, and so this file requires special attention. To correct the problem we need to perform a CVS update, which will compare our modified version with the one on the server and produce a list of conflicts.

\begin{shell}
\begin{verbatim}
$ cvs update
cvs update: Updating .
RCS file: /home/overcode/testcvs/example/foo.c,v
retrieving revision 1.4
retrieving revision 1.5
Merging differences between 1.4 and 1.5 into foo.c
rcsmerge: warning: conflicts during merge
cvs update: conflicts found in foo.c
C foo.c
\end{verbatim}
\end{shell}

% $

The file \filename{foo.c} now contains \code{diff}-like information showing which lines need to be merged. We should edit the file, decide how to resolve the conflicting lines of code, remove CVS's information, and perform another \code{cvs commit}. Unless more modifications have been made to the master file, CVS will accept the second \code{commit}.

\begin{note}{CVS Revision Numbers}
\index{CVS!revision numbers}CVS automatically assigns revision numbers to the files in a source repository. These numbers are incremented after each successful commit. They are intended for reference within the CVS system, and they generally do not correspond to a product's actual version numbers.
\end{note}

\subsubsection{Adding and Removing Files}
\index{CVS!adding files}To add a file to a CVS module (that is, to ask CVS to start controlling a newly added file from your working directory), use the \code{cvs add} command. For instance, to add a file named \filename{qux.c} to the \code{foo} module, you would use the command \code{cvs add qux.c}. You can specify wildcards, but be careful when doing so. To add a directory to a CVS module, simply add one or more files within that directory.

\index{CVS!removing files}Removing files from CVS is a bit trickier. There is a \code{cvs remove} command, but it can be used only if the file in question no longer exists. For example, suppose that you erroneously added \filename{qux.c} to CVS. To remove it, you would first have to delete or rename your working copy of \filename{qux.c} and then run the \code{cvs remove} command. This is truly annoying, but it does at least make you think twice before ripping a file out of the source tree. CVS never actually deletes these files; instead, it stores them in a special directory called \filename{Attic}, from which they can usually be recovered.

\subsubsection{Branching Source Trees}
\index{CVS!branching}Developers often have great ideas, but they're sometimes risky or difficult to implement. CVS allows developers to create branches of source trees so that they can test these ideas without jeopardizing everyone else's work. If these experimental branches work out, CVS can merge them back into the main source tree. Branches are also good for creating release snapshots of a source tree so that individual releases can be maintained while the main development process continues. For instance, if the Linux kernel team were to use CVS (which it does not), the ``cutting edge'' kernel would probably be in the main tree, while each major release (2.2, 2.4, and so on) would have its own branch for continued maintenance (such as security patches and driver backports).

\index{CVS!tagging}To branch a source repository, use the \code{cvs rtag} (remote tag) command with the \cmdline{-b} (branch) option. This will create a new branch of the current source tree and tag it with a name. For example, suppose we want to add a \code{gltweak} branch (presumably for OpenGL tweaking) to the \code{example} tree:

\begin{shell}
\begin{verbatim}
$ cvs rtag -b gltweak example
cvs rtag: Tagging example/foo.h
cvs rtag: Tagging example/foo.c
cvs rtag: Tagging example/main.c
cvs rtag: Tagging example/Makefile
\end{verbatim}
\end{shell}
\index{CVS!example|)}

% $

Most CVS commands allow you to select a branch with the \cmdline{-r} option. To check out the new \code{gltweak} branch, use \code{cvs co -r gltweak example}. (Likewise, you would use \code{cvs update -r gltweak example} to update an already checked-out source tree to a new copy of the branch.) Once you've checked out a tagged branch, all further updates and commits from that directory will automatically refer to the branch rather than to the master source tree. It is possible to merge a branch back into the main tree with the \code{cvs update -j branchname} command (of course, this is likely to produce conflicts, just as any other merge might).

You may have noticed that the \code{cvs rtag} command operates on the CVS repository rather than on a checked-out copy of the code. You can tag an existing directory just as easily (in which case the branch will actually be created whenever it is committed). This might be useful if you decide that things are getting out of hand halfway into a major hacking session. The command for this is simply \code{cvs tag}.

Branching is certainly useful, but use it with care. It's easy to make a mess of a source repository unless you manage this sort of thing carefully.

\subsubsection{Accessing CVS Remotely}
\index{CVS!remote}CVS is well suited to the Internet's massively distributed environment. It supports remote access with its client/server mode. Setting up a CVS server is not too difficult, but it is beyond the scope of this section.\footnote{SourceForge (\ulink{http://www.sourceforge.net}) offers free remote CVS repositories to open source developers.} However, it is important to know how to access remote CVS servers, since they are frequently used for Linux-related projects on the Internet.

\code{CVSROOT} normally points to a directory on the local machine, but it may also specify a remote CVS site. The general syntax of a remote \code{CVSROOT} is
\begin{codesegment}
\begin{verbatim}
:pserver:username@hostname:path
\end{verbatim}
\end{codesegment}

The \emph{username} must exist on the remote CVS site, though many projects provide a username for the general public to use. The \emph{path} specifies the directory location of the CVS repository on the remote machine.

Remote CVS access is similar to local access, but you must first log in to the remote site with the \code{cvs login} command. For example, suppose you want to obtain the latest version of SDL from Loki Software's public CVS server:

\begin{shell}
\begin{verbatim}
$ export CVSROOT=:pserver:guest@cvs.lokigames.com:/cvs
$ cvs login
(Logging in to guest@cvs.lokigames.com)
CVS password: guest
$ cvs checkout SDL
cvs server: Updating SDL
...
\end{verbatim}
\end{shell}

% $
\index{CVS!compression}Since source modules can grow quite large, CVS provides a compression option for bandwidth-deprived users. The \cmdline{-z\emph{n}} option asks CVS to use compression for its downloads, where \emph{n} is a number from 0 to 9. CVS actually uses GNU's gzip program for its compression, and \emph{n} specifies the gzip compression level to use. Compression is a very good idea for performing CVS updates over slow connections.
\index{CVS|)}

\section{Other Useful Tools}
UNIX is full of useful programming tools; unfortunately we can't cover them all here. This section points out several standard shell utilities that often come in handy for programming projects. A full explanation of these utilities is left to the appropriate online manual pages.

\subsection{Rapid Text Searching with grep}
\index{grep utility|(}Programmers often need to search source code for specific strings. For instance, a programmer might need to check the way that a certain OpenGL function is implemented but might not know which source file contains the function's code. The grep utility can quickly search any number of files for a given piece of text.

\shortpage
grep is based on \index{regular expressions}\firstterm{regular expressions}. A regular expression (\firstterm{regex}) is a pattern for matching text.\footnote{Do not confuse regular expressions with \firstterm{globs}, which provide a much simpler (and less powerful) way to match strings. Most UNIX shells (such as bash) use globs for matching filenames, and this throws many UNIX users for a loop.} A regex \firstterm{matches} a string of text if all of the string's characters are described by the regular expression in some way. grep's basic job is to search text files and print out all lines that match a given regex. For an explanation of regular expressions, see the grep(1) manpage (type \code{man grep} at a shell prompt).
\index{grep utility|)}

\subsection{Updating Source with diff and patch}
\index{diff utility|(}\index{patch utility|(}
If you've worked with CVS, you've probably seen diff and patch (or a close equivalent) in action. Source code tends to change quickly, though specific changes are often small and isolated. If another developer is collaborating on a project, it doesn't make sense to trade entire source trees; it would be better to send just the parts of a source tree that have changed since the last update. diff is a utility for comparing two files or directories and generating a \firstterm{delta} (or \firstterm{patch}) that can be used to change one into the other. Deltas can be applied with the patch utility. CVS uses this patching technique internally to keep track of project revisions without maintaining multiple copies of the entire project. The Linux kernel development team uses patches to exchange code improvements.

The basic usage of diff is very simple. To create a delta file that describes how to convert the file \filename{foo} into the file \filename{bar}, simply feed the two files to diff and catch diff's output with redirection:

\begin{shell}
\begin{verbatim}
$ diff foo bar > foo.patch
\end{verbatim}
\end{shell}

% $

\filename{foo.patch} now contains a description of the differences between the files \filename{foo} and \filename{bar}, and this file is sufficient for the patch utility to convert \filename{foo} into \filename{bar}.

\newpage
\begin{warning}
When you specify files to diff on the command line, be sure to put the original file \emph{first} and the new file \emph{second}. Programmers often generate deltas in the wrong order. This is a bad thing!
\end{warning}

To patch a file with a delta, supply the patch utility with the name of the file on the command line and the delta information on standard input. The following example uses the delta we just generated to patch \filename{foo} into \filename{bar}:

\begin{shell}
\begin{verbatim}
$ cat foo.patch | patch foo
\end{verbatim}
\end{shell}

% $

Or, equivalently,

\begin{shell}
\begin{verbatim}
$ patch foo < foo.patch
\end{verbatim}
\end{shell}

% $

The patch utility generally prints status information to indicate its success or failure. Patching usually succeeds, but it can fail if the file to be patched has been otherwise modified since the delta was generated. The patch utility tries to recover from this situation, but sometimes it is necessary to perform the patch yourself. It's not too hard, but it's a situation you'll want to avoid if possible.

patch can also handle entire directories. Suppose you've made modifications to a source tree in the \filename{new/} directory, and there is a copy of the original source tree in the \filename{old/} directory. You can generate a complete diff of the two directories with the following command:

\begin{shell}
\begin{verbatim}
$ diff -ubr old/ new/ > foo.patch
\end{verbatim}
\end{shell}

% $

\shortpage\shortpage\shortpage
This command causes diff to recursively scan through each directory, comparing files with the same name and outputting a complete chunk of patch data for the entire set. The \cmdline{-b} option instructs diff to ignore changes in whitespace (such as indentation). You would obviously leave this option out if your code involves a language in which indentation is significant (such as Python). To apply the patch generated with this command, change to the directory containing the source tree you want to patch, and feed the file to the patch utility:

\begin{shell}
\begin{verbatim}
$ patch -p1 < foo.patch
\end{verbatim}
\end{shell}

% $

The \cmdline{-p1} option tells patch that it is already in the directory to be patched (which, in all likelihood, has a different name than the directory from which the patch file was generated) and that it should ignore the first part of each filename it encounters.
\index{diff utility|)}\index{patch utility|)}

\section*{Time to Move On}
There are a lot of useful utilities that we haven't mentioned (or just haven't done justice to) here, but we have covered the most valuable tools for game programming. gcc and gdb are the most important by far (after a programmer-friendly text editor, of course), and you would do yourself a favor to become proficient with them.

It's time to move on. The next chapter concerns the programming toolkits you're likely to use for programming Linux games, and after that we'll get into programming with the SDL library.
