Tutorial : Compiling DOSBox SVN with Screenshot, Video Capture and IPX/Modem Support in Windows

DOSBox is a wonderful program, but in case you haven't noticed, the last official release, 0.74, is rapidly approaching its fourth birthday (05/12/2010).  This is by far the longest time span between releases of the program.  But DOSBox has not been sitting idly by, the developers have continued to fix bugs and add new features.  While it is easy enough to find a pre-compiled version of the latest SVN, it may not be able to support screenshots without crashing (EmuCR), has more options in the config file than an average DOSBox user may need (DOSBox-X, Yhkwong's build) or simply won't have the features of that particular patch you are looking for.  Until the development team releases 0.75, this is the closest you can get.

This tutorial is intended to guide a beginner through the compiling process in order to obtain a fully featured build of DOSBox SVN with important optional features such as IPX and Modem support and Screenshot and Video Recording in Windows.  I have omitted adding the debugger features, if you need them, then this tutorial is probably too basic for you.  To include the debug features, you need the curses library, and the best library for implementing the debugger in Windows is the pdcurses 3.4 library.

1.  The Compiler

This tutorial assumes you are running DOSBox on some modern version of Windows and using an x86 CPU.  (No Windows RT.)  Since we will be using a Microsoft product to compile the source code, it will not work on any other system.  It is easy enough to compile a DOSBox with the basic features.  There is a good tutorial on how to do it in Visual Studio 2008 Express Edition.  You can find it here and you may wish to consult with it if anything in this tutorial is unclear : http://www.dosbox.com/wiki/Building_DOSBox_with_Visual_C_2008_Express

I am indebted to the author, for this is the way I learned how to compile DOSBox, being a Microsoft loyalist since I first used a PC compatible in the early 90s.  You can also use MinGW and MSYS, but that is a Unix/Linux approach utterly foreign to me (and I could never figure it out anyways).

VS2008 is getting a bit old in the tooth, and some of the more modern project files do not really support VS2008.  So in this tutorial, I will be using Visual Studio 2010 Express, also freely downloadable from Microsoft.  Virtual Studio includes Visual C++.  Find it here :

http://www.visualstudio.com/en-us/downloads#d-2010-express

The installer will download the program and the modules it needs and will install them.  It will also set file associations for the files we will be using.

2.  The Source Code

Now, you need the source code.  First start with the current DOSBox SVN, found here :

http://source.dosbox.com/dosboxsvn.tgz

You should use a program like 7zip to uncompress this file.  It is doubly compressed.  Please see my DOSBox patching guide if you want to add any patches, as you can at this stage :

http://nerdlypleasures.blogspot.com/2014/02/patching-dosbox-for-beginners.html

Next, you will need the Simple Directmedia Layer (SDL) to build libraries that DOSBox needs to function.  DOSBox is only compatible with the 1.2 versions and the last version of SDL is 1.2.15.  However, you should obtain the source code for 1.2.14, which is the last SDL 1.2 version that will compile easily in VS2010.  You can download it here :

http://www.libsdl.org/release/SDL-1.2.14.zip

3.  Optional Libraries

If you want to add the optional features to your compiled DOSBox, you will need some more source code to build libraries.

1.  For Modem/IPX support, you need SDL_net.  SDL_net's mirrors SDL's versions, and the most current  version that will compile easily in VS2010 is 1.2.7.  Get it here :

http://www.libsdl.org/projects/SDL_net/release/SDL_net-1.2.7.zip

Now what you have obtained above is the easy part.  For working screenshots and video recording, you will need to compile libpng and zlib libraries from source.  After that, then you compile DOSBox.

For libpng, the current stable source is 1.6.9.  You can obtain it here :

http://prdownloads.sourceforge.net/libpng/lpng169.zip?download

You use libpng to compile both libpng.lib and zlib.lib, but for the latter, you need the zlib source code, and specifically 1.2.5 (even though 1.2.8 is the most recent version, but libpng expects 1.2.5).  You can obtain 1.2.5 here :

http://www.winimage.com/zLibDll/zlib125.zip

4.  Directory Setup

Once you have installed VS2010 and downloaded your source code and libraries, you need to put the source somewhere.  Make a folder like \Project and unzip your source code and libraries so they look like this :

\Project\dosboxsvn
\Project\lpng169
\Project\SDL_net-1.2.7
\Project\SDL-devel-1.2.14
\Project\zlib-1.2.5

This will be important for the next step and make it easier to point the compiler to the various include and library files later on.

5.  Compiling libpng.lib and zlib.lib

Go to \Project\lpng69\projects\vstudio\libpng and double click on libpng.vcxproj  A vcxproj file is a  Project File that tells a compiler how to build code.  This will start the compiler.  You should see Solution Explorer on the left hand side of the program.  There are seven projects here, but we only need two of them.  Right click on Solution 'vstudio' (7 projects), click on Properties and check the button that says Multiple startup projects:  Set libpng and zlib to Start and the rest to None.  Press Apply and OK.

Libpng relies on zlib, so we want to make sure zlib is compiled first.  Right click on libpng in the Solution Explorer and go to Project Dependencies.  In the drop down box, select libpng and make sure there is a checkmark next to zlib in the box below and none on any other box.  Then click on the Build Order tab and you should see that zlib comes first and libpng comes second.

Next right click on Solution 'vstudio' (7 projects) and click on Configuration Manager.  Under Active solution configuration: click Release Library.  In the box below, next to libpng and zlib, change the Configuration to Release Library.  For the other options, uncheck the boxes next to the Build so they will not be compiled.  Do not worry if they compile anyway, these extra projects are mainly for testing.

Next, in the Solution Explorer right click on libpng and go to properties.  On the left hand side, you should see a line called Configuration Properties.  On the right side of the window, you will see a line that says Configuration Type.  Click on the dropdown box next to it and set it to Static library (.lib) if it is not already.

Then click on VC++ Directories.  The window here is a bit small for what you need to do, but be very careful here.  Clicking on the wrong thing will wipe out the default directory entries, and if you do that the compiler will not know where to find the code it needs to compile.

Next to the line that says Include Directories, click once on the box after the partition.  This will show a down arrow button.  Click on that once and then click on  On the next window, click on the icon of a file with an asterisk in the corner, then click on the box with the ...  On the Select Directory Window, navigate to the directory with the zlib Include files.  The directory is typically : \Project\zlib-1.2.5.  When done, click OK.

To compile the libraries, hit F7.  In the output window, you will see the compiler crunch code and turn it into libpng.lib and zlib.lib.  If you succeed, the compiler will indicate where the .lib files are located.  If you fail, then the compiler will report an error and your files will not be built.  In this example, you can find the .lib files in \Project\lpng169\projects\vstudio\Release Library\ as zlib.lib and libpng16.lib.

6.  Compiling SDL and SDL_net

In this guide, I have completely avoided using developer libraries.  While there are appropriate Visual C ++ developer libraries that work with VS2010 available for SDL and SDL_net, I think its best to compile your own libraries.  Since you have to do this for libpng and zlib, you already should begin to get a feel for how to incorporate include and library directories.  Compiling your own libraries can improve DOSBox performance and compatibility with your particular system.

To compile SDL, you will need the DirectX SDK.  The DirectX 10 SDK from June 2010 seems compatible, and you can get it here :

http://www.microsoft.com/en-us/download/details.aspx?id=6812

You only need to install the libraries.  The installer may give an error if the rest of the components aren't installed, but the libraries will be installed.  You will be able to find them typically in C:\Program Files (x86)\Microsoft DirectX SDK (June 2010)

Now, in the SDL-1.2.14 directory, there will be a zip file named VisualC.zip.  Unzip it so that you can see files in the next level subdirectory.  Go into that subdirectory and open the file SDL.sln.  This is a solution file used by older versions of Visual C++ to build a project. VS2010 will run a conversion tool that will convert it into something it can manage properly.   Click on Next and then Finish.  You may see some warnings but you shouldn't see any errors.

In the resulting Solution Explorer, you will see two projects, SDL and SDLmain, and you will need to compile both of them.  First, right click on Solution 'SDL' (2 projects) and go to properties.  Then click on the button that says Configuration Manager.  From the Active solution configuration: dropdown menu, click on release, and for the Configuration menu drop downs next to SDL and SDLmain, set them both to release.  Close the Configuration Manager.  At this point, the Configuration dropmenu should show Active(Release).  Click on Apply and then OK.

Next, in the Solution Explorer right click on SDL and go to properties.  On the left hand side, you should see a line called Configuration Properties.  On the right side of the window, you will see a line that says Configuration Type.  Click on the dropdown box next to it and set it to Static library (.lib) if it is not already.  DOSBox needs the libraries to compile, and SDL should still create an SDL.dll when you compile it.

Then click on VC++ Directories.  This is where you add the DirectX SDK libraries you installed at the beginning of this step  Next to the line that says Include Directories, click once on the box after the partition.  This will show a down arrow button.  Click on that once and then click on  On the next window, click on the icon of a file with an asterisk in the corner, then click on the box with the ...  On the Select Directory Window, navigate to the directory with the DirectX SDK Include files.  The directory is typically : \Program Files (x86)\Microsoft DirectX SDK (June 2010)\Include  When done, click OK.

On the line that says Library Directories, you are going to do almost the same thing.  This time, you want to add the directory for the DirectX SDK Library files.  The directory is typically : \Program Files (x86)\Microsoft DirectX SDK (June 2010)\Lib\x86.  Make sure you select the x86 (for 32-bit) and not the x64 (64-bit, DOSBox doesn't like 64-bit code).  Once you are done, you can press OK to get back to the Solution Explorer. Now press F7 and you should be have created sdl.lib and sdlmain.lib in their respective Release directories, \Project\SDL-1.2.14\VisualC\SDL\Release and \Project\SDL-1.2.14\VisualC\SDLmain\Release

SDL_net requires the SDL libraries, which is why we compiled the SDL libraries first.  Like with SDL, you will need to unzip the VisualC.zip file and convert the solution file SDL_net.sln.  Set SDL_net to Release in the Configuration Properties.

Open the SDL_net properties page, set the Configuration Type to Static library (.lib) and then click on VC++ Directories.  For the Include Directories, you need to add the directory containing the SDL Include files.  They can be typically found here : \Project\SDL-1.2.14  Next you need to add the directories containing the SDL Library files.  These are \Project\SDL-1.2.14\VisualC\SDL\Release and \Project\SDL-1.2.14\VisualC\SDLmain\Release.  You need to add both.  After you have done all this, you can exit the properties window and press F7 to compile.  You should end up with sdl_net.lib.

7.  Setting Up the DOSBox Compiling Environment

Now that you have all your libraries, you can compile as full a DOSBox as you like.  Navigate to \Project\dosboxsvn\dosbox\visualc_net and click on dosbox.vcxproj

In the Solution Explorer Window, right click on dosbox.  Set the active configuration to Release using the Configuration drop box and the Configuration Manager button first.

In the VC++ Directories, you will need to add the following directories to the Include Directories :

\Project\lpng169
\Project\SDL_net-1.2.7
\Project\SDL-1.2.14\include
\Project\zlib-1.2.5
\Program Files (x86)\Microsoft DirectX SDK (June 2010)\Include

If you are compiling code specific to Windows, you may also need to include a directory like :

\Program Files (x86)\Microsoft Visual Studio 10.0\VC\include\sys

You will need to add the following directories to the Library Directories :

\Project\lpng169\projects\vstudio\Release Library\
\Project\SDL_net-1.2.7\VisualC\Release
\Project\SDL-1.2.14\VisualC\SDL\Release
\Project\SDL-1.2.14\VisualC\SDLmain\Release
\Program Files (x86)\Microsoft DirectX SDK (June 2010)\Lib\x86

On the left side of the Property Page, click on C/C++ and then on General.  On the line that says Treat Warnings As Errors, click on the box next to it and set it to No (/WX-)  The compiling process will give many warnings, and if this is not set these warnings will cause the build to fail.

Next click on Linker and next to the Force File Output, click on the box next to it and select Multiply Defined Symbol Only (/FORCE:MULTIPLE).  Next to the Treat Linker Warning As Errors, click on the box next to it and select No (/WX:NO).  These "errors" and warnings are not going to affect a compiled DOSBox, but they certainly will stop DOSBox from compiling correctly.

Finally, underneath Linker, click Input.  The following line needs to be present :

dinput8.lib;dxguid.lib;libpng16.lib;sdl_net.lib;opengl32.lib;winmm.lib;sdlmain.lib;sdl.lib;ws2_32.lib;zlib.lib;%(AdditionalDependencies)

Many of these items are already present.  You will need to add dinput8.lib and dxguid.lib and rename libpng.lib to libpng16.lib.  Since the space is very small, you should check the spelling and formatting very carefully.  Each library, including the last, needs a semicolon ; after it.

8.  Adjusting the DOSBox Code and compiling

In the Solution Explorer, clock on Source Files and then click on visualc and then double click on config.h. The code listing will appear to the right.  If you are not compiling with IPX and Modem support, then change the values from 1 to 0 in the lines :

#define C_MODEM 1

#define C_IPX 1

If you are not compiling with screenshot and video recording support, change the value from 1 to 0 in the
line :

#define C_SSHOT 1

Next, for a speed boost, change the value from 0 to 1 in the line :

#define C_CORE_INLINE 0

Finally, you should see in the Solution Explorer a file called winres.rc.  Right click on that and select View Code  Change the line that says #include "afxres.h" to #include "Windows.h"

In the Solution Explorer, right click on dosbox, go to properties an then the Configuration Manager.  Makes sure the Active solution configuration and the dosbox project configuration are both set to Release, NOT Debug.  Release builds are faster than debug builds.  Debug DOSBox builds exhibit an annoying issue with the Adlib music where it will stutter unless the cycle count is set very low in DOSBox.  After you close the Configuration Manager window, you should see in the Configuration drop down menu Active(Release).  Exit the dosbox Property pages.

Now you are ready to compile.  Hit F7 and be prepared to wait.  If you are successful, you will have a dosbox.exe in \Project\dosboxsvn\dosbox\visualc_net\Release.  You probably will not need any .dll files since the libraries should be statically linked within the DOSBox executable, but if you do, you can obtain them from the official 0.74 DOSBox.

DOSBox will generate a .conf file on its first run if one is not present.  Look in the status window to find it and move it to the directory in which you will use DOSBox.  It is typically buried in AppData on Windows Vista/7/8.   It will save screenshots and other captures to a folder named capture, but by default will save them to the same place as it wrote the .conf file.

If you are using Windows 8.1, you will find that the mouse movement will be extremely jerky when using this build.  This is due to some changes Microsoft made in handling mouse input.  To fix the problem, apply the appropriate patch for your OS (32-bit or 64-bit) from here : http://support.microsoft.com/kb/2908279