Building on MSVC

From Open Surge Engine Wiki
Jump to: navigation, search
Stub
This article is outdated. Its instructions might need some adaptation. Please help us improving this page by adding up-to-date information to it.

This document describes the approximate steps necessary to build the Open Surge source in Microsoft Visual Studio. If you have no programming experience, then you may be looking for the Open Surge binaries from this page instead.

Open Surge is developed in C for a broad compatibility, theoretically supporting any system which can also compile the Allegro Game Programming Library. It would be helpful if you had some experience in either C or C++ or an syntax-equivalent language like (gasp) PHP.

Software you need

Before continuing on this tutorial, you will need to install a few things (unless you already know you have them). The following list attempts to describe what you need and where to get them. If the links do not work, then attempt to search for these products online.

Note that this tutorial is not going to cover how to use any of this software. For that, consult the individual documentation where necessary.

Microsoft Visual C++

The newest express edition of Microsoft's Visual C++ compiler is suggested, though this tutorial should work as far back as Visual Studio .NET 2003. There are some hacks and workarounds if you choose to use an older compiler that will be discussed later.

Microsoft Windows SDK

This one is a little tougher to choose. The above link should show a page with a table with your cryptic Development Requirement. You are probably safe choosing the one on the far left, though if you have a special compiler situation the previous versions are available for you as well. This is a sizable package that will take awhile to install.

DirectX SDK

The download for this is a bit more straightforward. The DirectX SDK release is named for the month and year it was last released (currently February 2010). This is another sizable package that will take awhile to install.

Cross Platform Make

You will need this utility to create the Open Surge solution and project files for Visual Studio. There is a fairly straightforward install process, but note that it is a command line tool. Fortunately it is a very small package.

Subversion

This product is optional. If you wish to maintain a synchronized version of the Open Surge source code on your computer, or if you would like to submit patches to the developer, go ahead and grab this software as well.

Setting up your Environment

The Visual Studio Command Prompt is a shortcut to a normal command prompt (cmd.exe) which sets environment variables useful for working with solutions from the command line. While graphical tools exist for nearly every problem, savvy developers will have experience with a command line.

Check your programs folder (under your Start Menu) for the Visual Studio group. This group should contain the special Visual Studio Command Prompt shortcut, possibly under a header containing the word Tools. If the shortcut is missing, this page may provide a good starting point for restoring it. You'll need this special command prompt to continue.

Once you get the command prompt running, type the following commands to make sure they all work on your system:

nmake /?
svn help
cmake --help

If there are any issues, examine them before continuing. Since you have your command prompt open, now would also be a good time to brush up on Subversion and the process of checking out files, reverting, and updating revisions.

Development folder

You will need to set up a folder for development files you will be downloading. This is as easy as using the Visual Studio project folder somewhere in your Documents folder, but sometimes a separate path is useful. For example, you could make a folder called "dev" in your c:\ root. That way, all your programming materials are accessible with just a c:\dev\ prefix; easy to remember. Wherever you set it up at you'll want to remember and know how to get there quickly.

Make batch files! Since you are using the command prompt anyways, type the following:

echo @echo off > devdir.bat
echo c:\ >> devdir.bat
echo cd \ >> devdir.bat
echo cd long_path_to_files\subdir\another_dir\projects\src >> devdir.bat

After these commands, you'll be able to type one command to move to the long path in the example:

devdir

Make a mistake? Check it out with the command:

start notepad devdir.bat

Microsoft has plenty of articles on batch files, so don't be afraid to use them!

Building Dependencies

There are several dependencies that need to be either built or acquired before Open Surge to work. Some of these libraries have nice pre-built binaries for convenience but if your build environment is abnormal (or outdated) in any way you'll probably need to build from source.

Allegro

To build the Allegro Game Programming Library under MSVC, first download the latest stable version from the above link. Unzip it to your development folder (under "Allegro" or something) and open that folder up in explorer.

At present, the Allegro package contains a file "build\pre-build-msvc.bat" which needs to be executed before the Allegro project files are accessed. Locate this file and double-click it. In most default Windows versions, the command prompt window should open and close pretty quickly and you'll be unsure what happened. Assume and move on.

Also at present, there are three folders under the build folder called msvc6, msvc7, and msvc8. Open the newest folder for the version of Visual Studio you have (msvc8 = 2005, msvc9 = 2008, etc). Double-click on the Allegro.sln file to open up the project in your environment. If you had to use an older msvc# version, prepare for Visual Studio to ask you to convert the projects. Allow it to do so.

Batch Building the Allegro solution

Depending on your version of Visual Studio, the Solution Explorer box is on either the left side or the right side of the window. This has the Allegro solution and the Allegro project, as well as the source/header files and others. Right click on the Allegro solution and click on "Batch Build...". This will open up a box which looks like the picture to the right.

Put a tick in the checkboxes next to Debug and Release. You can optionally tick the Static Debug, Static Release, and Static Release Runtime if you want to just get it over with, but they are not needed for Open Surge. Once your selections are made, click on "Rebuild" and watch the results.

Note: building the Allegro source is technically beyond the scope of this tutorial. If you have issues, the output window should give you a hint. For example, "dinput.lib" errors probably are related to the version of DirectX SDK you have installed. The Allegro people have files for that at the bottom of their download page. It is impossible to cover every scenario here; the Allegro community is large and support will be easy to find.

After building, there were some files in the the Allegro folder under lib/msvc. My choices left me with two DLL files, five LIB files, and a handful of other stuff like PDB and ILK files that I don't necessarily need. The DLL file needs to go somewhere accessible in the path. If you a re only building Allegro for Open Surge, then just put it in the Open Surge folder. If you are on a limited account, put it in your main user folder.

Leave the rest of the files where they are and add the current folder to Visual Studio paths. Do the same for the includes folder, located in the main Allegro folder. The instructions for doing this are located here.

The AllegroPNG package will only build successfully if this package built successfully. If there are any issues there, it would be worth retracing your steps for this package.

AllegroPNG

Download the AllegroPNG package and unzip it to your development area. AllegroPNG requires the Visual Studio command prompt to build, which provides a perfect test for the Allegro package we've already set up. The shortcut for this should be in your programs folder under Visual Studio Tools. Locate it and start it up.

Navigate to the folder where AllegroPNG has been checked out and run the following commands:

configure.bat msvc
nmake

If anything goes wrong here, make sure you are in the correct folder under the command prompt window. Also make sure you are using the special Visual Studio command prompt. Finally, make sure the paths to the Allegro package previously set up are correct. It would be worth rechecking the steps outlined for both packages to help see what went wrong.

One LIB file was created during this process. Copy this file to the Allegro folder under lib\msvc. Then locate the file src/alpng.h and copy it to the Allegro folder under include. Since the Visual Studio paths already point to these locations there should be nothing left to do for this package.

Dynamic Universal Music Bibliotheque

Download and unzip the DUMB project and open up the folder. There is a vc6 folder which contains the file "dumb.dsw". Open this workspace and allow Visual Studio to convert the projects to the current version.

Right-click on the dumb solution and use the "Batch Build" dialog to build the Debug and Release versions. This process should create four lib files in the following location:

aldumb\Debug\aldmd.lib
aldumb\Release\aldmb.lib
dumb\Debug\dumb.lib
dumb\Debug\dumbd.lib

Rather than make four entries in the Visual Studio directories dialog, copy these files to a new lib folder in the DUMB folder. Add this folder and the include folder to the appropriate place in the Visual Studio folders dialog.

OGG and Vorbis

Configuring the Solution

Before doing anything in the Open Surge code, you'll want a convenient Solution file for Visual Studio to open. This is created using the Cross Platform Make tool, otherwise known as cmake. Using a command prompt window, navigate to the opensurge folder and run the following command:

cmake --help

You'll use one of cmake's built-in generators to produce the solution file. The one you use depends on the version of Visual C++ you are using, but the command for Visual Studio .NET 2003 looks like this:

cmake -G "Visual Studio 7 .NET 2003"

If there are any missing dependencies now is where you will notice them. CMake will try to find important library files before creating a solution file and fail if one is missing. If you happen to have any trouble with this step, recheck the #Building Dependencies section above.

The first time you load the Open Surge solution in Visual Studio, there are a couple of steps you should take to save time later on. These steps are optional, but the tutorial is going to assume that if you did not take them you know how to work around the issues raised. For your own sanity, you should at least check over this list.

Startup Project

Startup project in bold

Depending on your version of Visual Studio, the project files will either be on the right side of the window or on the left in the Solution Explorer box. There should be two projects in the solution:

  • ALL BUILD
  • opensurge

By default, the ALL BUILD project is bold, indicating that it will be the first project to run when the debugger starts. Go ahead and right-click on the opensurge project and click "Set as StartUp Project". If done correctly, the opensurge project is now the one in bold.

Output Directory

When the Visual Studio debugger builds the executable, by default it attempts to do so in either the Debug or Release folder. You can tell that MSVC has done this if you receive an error similar to the following:

FATAL ERROR: can't read file '...\config\sprite.def'.
Please make sure the game is installed properly.
Linker output directory

There are two ways to solve this problem. The manual way is to copy the newly built opensurge.exe file to the main opensurge folder. It will be located in a subfolder of opensurge called either Debug or Release.

The automatic way is to change where the executable is built. Right-click on the opensurge project in the Solution Explorer again, except this time click on "Properties" at the bottom of the menu. This will bring up a whole load of options pertaining to the project.

On the left, click on the Linker folder. Roughly, a linker takes a bunch of compiled code files and combines them into an EXE. In the Open Surge project, that file is called "opensurge.exe" and you can see the output directory at the top of the Linker options.

The path should include the word Debug or Release sort of like the following:

C:\Users\celdecea\dev\opensurge\Debug\opensurge.exe

Remove the Debug or Release part so that the executable is built in the main opensurge folder:

C:\Users\celdecea\dev\opensurge\opensurge.exe

Debugging

On your keyboard, hit Ctrl+Shift+B to build the application. A successful build looks somewhat like the following:

---------------------- Done ----------------------
Build: 1 succeeded, 0 failed, 1 skipped

If you see these signs of success, then hit the F5 key to run Open Surge. Congratulations, you have built the game from source.

Problems

If you have any problems, check the Bleeding Edge forum thread. There may be a patch file which corrects build issues in the current revision. Details on applying patch files are available in the Subversion article. Sometimes the patch is a little behind, so you can either fix the bug yourself or ask for help at this thread.

Programmers new to C or C++ are often intimidated by the number of errors that seem to be produced. Note that the unwinding from a bug produces other bug reports so there could theoretically be just one depending on the nesting. Consider each bug one at a time and keep rebuilding, eventually they'll all go away.

Good luck and happy coding.