30.2 Adding libraries to your project file

If you're not using the Pop Framework, the first time you add the ::PlaySound call to your code and try and compile the code, you'll get a compiler error that says something like PlaySound' : undeclared identifier'. To get rid of this, you need to add the line #include <mmsystem.h> to the top of your file.

And now after you get past the compile, you'll get a linker error, saying something like "PlaySound definition not found". Actually it will have a bunch of gibberish attached to the PlaySound name; this is because C++ does 'name-mangling' which means attaching symbols to a function name so as to specify what types the function expects as its arguments.

When you get a linker error of this kind, this means that you have used the name of some function without telling the compiler where to find the code that defines this function. The compiler is recognizing that PlaySound is a function, but the linker isn't able to find the code for it.

The response is to add more *.cpp or *.lib modules to your project file. If the function is one that you yourself have the code for, then the linker error means that you forgot to include the *.cpp file where your code lives. If the function is a Windows function, then the error means that this is some unusual function whose code is found in some Windows library other than the standard libraries.

How do you figure out which header and library to use for a function? Use F1 or the Help | Index to find the documentation on PlaySound. This will include a Quick Info section that tells you what header file and import library the function uses. It turns out that the import library where PlaySound lives is winmm.lib, and the header file where its prototype lives is mmsystem.h.

So we want to tell the project file to include winmm.lib. The wrong way to do this is to use Project | Add to Project | Files to add the winmm.lib to your project files. This is not a good method because you need to tell the Add Files To Project dialog where winmm.lib lives, which means browsing around until you find it in, say, C:\Program Files\Developer Studio\VC\Libraries. Doing this takes a long time. Even worse, doing this has the effect of making your project file non-portable, because the path name you use becomes part of the name of the library file as stored by the project. This then means that if someone whose Developer Studio lives on his or her D: drive tries to use a project files that looks for winmm.lib in the C: drive, the project file won't be able to find winmm.lib.

The correct way to add a *.lib file to a project is to use the Project | Settings dialog. Open the dialog and change the Settings For dropdown to All Configurations in the upper left-hand corner of the dialog. Now click on the Link sheet of the dialog. Make sure the General selection is active at the top of the Link sheet. Now click on the Object/Library Modules edit box. The box may be empty, but if there are file names in it, use the Arrow key to move to the end of the list of *.lib files in this edit box. Type in winmm.lib, making sure there is a space between it and the previous file name. Don't put a path name in front of winmm.lib; the linker will look for the library in the Visual Studio's list of Library directories.

Let's reiterate that you should do this for All Configurations, so that you are making the change to both the Debug and the Release versions of your project. After making this change you need to do Build | Rebuild All.

From now on, the linker will look for winmm.lib in the list of Library directories maintained by the active installation of Visual Studio.

This list, by the way, is found under the Tools | Options dialog on the Directories sheet. To see the Library directories select Libraries in the box at the upper right of the sheet. Normally the correct library directory will be among the options listed, but if it isn't you can type it in. Note that the Tools | Options Directories settings are attached to the Visual Studio compiler when it is installed on some specific machine. These settings are not part of your project or workspace file.

    Part I: Software Engineering and Computer Games
    Part II: Software Engineering and Computer Games Reference