Building DOSBox with Visual Studio

From DOSBoxWiki
Jump to navigationJump to search

While the official Windows build environment for DOSBox is MinGW, it may also be built in Visual Studio for users more comfortable with this.

Get Visual Studio

Free versions of Visual Studio are available at:

The free version of Visual Studio 2017 is called the "Community" edition. Prior to this (VS2005-2015) free versions were called the "Express" edition.

Some older versions are available at:

When installing Visual Studio, there may be tools for multiple languages available (C++, C#, Visual Basic .NET, Java, etc.) but only the C++ tools are necessary for DOSBox.

Get Libraries

  • Optional for compressed audio disc images:
  • Optional for DOS debugging tools:

Prepare Libraries


If using VS2013 or earlier, you can use the pre-built library in For VS2015 or later you will need to rebuild it from source (

  • Open SDL-1.2.15\VisualC\SDL.sln and allow Visual Studio to automatically convert the solution and project to the latest version.
  • Select the Release configuration and use the Build menu to build the solution.
  • The following 3 files should be built:
    • SDL-1.2.15\VisualC\Release\SDL.dll
    • SDL-1.2.15\VisualC\Release\SDL.lib
    • SDL-1.2.15\VisualC\SDLmain\Release\SDLmain.lib
  • The following folder also contains relevant include files for the library:
    • SDL-1.2.15\include
  • If you need more info on building SDL with VS, see: SDL-1.2.15\VisualC.html

zlib / libpng (optional)

Enables screenshot and video capture.

Because zlib is a dependency of libpng, a VS solution to build both at once is provided by the libpng package.

  • Unpack to create the folder: lpng1634
  • Unpack zlib-1.2.8.tar.gz to create an adjacent folder: zlib-1.2.8
  • Open lpng1634\projects\vstudio\zlib.props with a text editor.
    • Near the bottom of the file you will find <DisableSpecificWarnings>. Add ;5045 to the end of this list. (This disables a new spurious warning in VS2017.)
  • Open lpng1634\projects\vstudio\vstudio.sln and allow Visual Studio to automatically convert the solution and projects to the latest version.
  • Select the Release Library configuration.
  • Right click on the zlib project in the solution explorer and open its Properties.
    • From Configuration Properties > C/C++ > Preprocessor > Preprocessor Definitions remove Z_SOLO. (Currently causes video capture to fail and crash.)
    • Change Configuration Properties > C/C++ > Code Generation > Runtime Library to Multi-threaded DLL (/MD).
  • Right click on the zlib project and build it.
  • Now open the libpng project's properties.
    • Change Configuration Properties > C/C++ > Code Generation > Runtime Library to Multi-threaded DLL (/MD).
  • Build the libpng project.
  • The following libraries should now be built:
    • lpng1634\projects\vstudio\Release Library\zlib.lib
    • lpng1634\projects\vstudio\Release Library\libpng16.lib
  • Include folders:
    • lpng1634
    • zlib-1.2.8
  • For more libpng build information see: lpng1634\INSTALL

SDL_net (optional)

Enables networking.

You can use the pre-built libraries in

  • Library files:
    • SDL_net-1.2.8\lib\x86\SDL_net.dll
    • SDL_net-1.2.8\lib\x86\SDL_net.lib
  • Include folder:
    • SDL_net-1.2.8\include

SDL_sound (optional)

Enables the use of CD images with compressed audio.

  • Guide not yet written.

PDCurses (optional)

Enables a DOS debugger.

  • Guide not yet written.

Get the DOSBox sources

The next step is to get DOSBox itself. At the time of writing, the latest official release of DOSBox is 0.74, available at the Releases page. However, it was released over 6 years ago, so if you want more recent source code you can go to the SVN Builds page to download the source of some SVN version of DOSBox. Since the DOSBox sources come as a .tar.gz file, you may need a separate program to extract this. Unpack the source to the location of your choosing. For this discussion, I have chosen C:\Development\dosbox.

Set up the environment

Setting the include directories for SDL

From your start menu, start VCE. After a few moments, the IDE (Integrated Development Environment) will start. The first thing we need to do is tell VCE where to find SDL. From the "Tools" menu select "Options". When the Options menu appears, expand the category "Projects and Solutions" and choose "VC++ Directories". From the directories pulldown, choose to show the directories for include files, click the folder icon and add the folder for the SDL includes. If you have been following this guide literally, that would C:\Development\SDL-1.2.13\include. Next, elect to show the directories for library files. This time, add the folder for the SDL libraries. When you have followed this guide, that would be C:\Development\SDL-1.2.13\lib.

After you have done this, click OK to accept and close the options.

Set up the solution

Conversion wizard

Conversion wizard

Open the solution provided by DOSBox. It can be found as C:\Development\dosbox\visualc_net\dosbox.sln. If you have file extensions hidden (as they are by default), you may select "Solution files (*.sln)" from the object type dropdown to ensure you get the correct one. The first time you open the solution, VCE will present you with the Visual Studio Conversion Wizard, because the solution included in the DOSBox distribution is for an older version of Visual C++. You can simply click Finish and be done with it. If you want, you can take a look at the conversion log, but the information in there is not particularly interesting.


Editing the additional dependencies

Now that the solution has been opened, it is necessary to disable some of the optional features of DOSBox. From the "Project" menu select "dosbox Properties". Expand the "Configuration Properties" and then the "Linker" category. Then choose "Input". From the properties on the right, you will need to remove some of the "Additional Dependencies". With the setup I have described here, I need to remove sdl_net.lib, zlib.lib, libpng.lib and curses.lib (you will also not need the odbc32.lib and odbccp32.lib references, but there is no harm in leaving them). Apply the changes and use the dropdown at the top left to switch to the Release configuration. Repeat the previous step, removing those same references and again apply the changes.

Configuration setup

Adjusting the config.h file

In the Solution Explorer, browse down the solution into "Source files" and then "visualc". Open the file config.h listed there and do some editing. Find the line that reads

#define C_SSHOT 1

and change the 1 to a 0. Do the same for the lines mentioning C_MODEM and C_IPX. The reason we are disabling these options is that they require some extra libraries that we haven’t set up for this tutorial. Also, set C_CORE_INLINE to 1 to enable faster CPU emulation.

In the Solution Explorer, in the "Source files", you will find the file winres.rc. Right-click on that and choose "View code". Remove the line at the top that reads

#include "afxres.h"

When you have done this, save the solution ("Save all" from the file menu). This ensures you won’t have to repeat any of the previous steps.

The actual build

Build successfully completed

Before building, right click on "Solution 'dosbox'" in the Solution Explorer and go to Properties -> Configuration Properties. Set the Configuration dropdown box to "Release" instead of "Debug". This will cause VC++ to build an optimized binary without extra debug features.

Now that all this is done, press F7 to start the build process. There will be a few warnings, but they are unimportant. The build may take a few minutes depending on the speed of your computer, but if you have followed this tutorial it will complete successfully.

Note that to actually run the executable you have built, you will need the SDL library (SDL.DLL) from your regular DOSBox install and place it in the C:\Development\dosbox\visualc_net directory.