MSVC Setup Guide

From WxWiki
Jump to: navigation, search
This article applies to the following versions
Platform wxWidgets Visual C++
Windows XP 2.4.0 6
Status: Out of Date

Note: This guide contains good general information about setting up wxWidgets on MSVC, however, some of the contents may be a bit out of date for the current builds. Please refer to Microsoft Visual C++ Guide for setting up the latest version of wxWidgets.

Working with wxWidgets on MS-Windows is an enjoyable computing experience, but it takes a little work to set it up. This guide was created to help you set up a basic configuration of wxWidgets quickly, so I'll try to be brief and to the point. I'll assume you know how to work the operating system (unpack the zip, set environment variables, etc.) I am basing this guide on my personal setup of Windows 2000, Visual C++ 6.0 and wxWidgets 2.4.0.

Feel free to correct inaccuracies in this document or you can send comments and corrections to the wx-users mailing list at comp.soft-sys.wxwindows on usenet or wx-users at lists.wxwidgets.org (For subscription info send a message with 'help' in the subject line to wx-users-help at lists.wxwidgets.org ;)


Installation

  1. Unpack/install the archive into a directory with no spaces (e.g. C:\wxWidgets_2.4.0). I'll refer to this as %WXWIN%.
  2. Create an environment variable called WXWIN and set it to the installation directory (including drive letter). This is for building the libraries with makefiles (not covered here - see %WXWIN%\docs\msw\install.txt and Compiling Using MSVC On The Commandline).
  3. You need to compile the libraries yourself. Open %WXWIN%\src\wxWidgets.dsw (or %WXWIN%\src\wxWindows.dsw) in the IDE. You'll see several projects. The 'wxWindows' project is the main project and is dependent on the other projects, so make this the active project.


Setup.h

In the workspace window, go to the FileView thing and go to wxWidgets files->Headers->Setup and open up Setup.h. This file exists in %WXWIN%\include\wx\msw. This is the global configuration file. It is not used directly by the compiler, but it is a make dependency with a build step that copies it to configuration-specific locations (see the table below) whenever it is changed and built. Perform all your wxWidgets configuration here, unless you need different settings for different wxWidgets configurations in which case you may need to worry about touching your files so they don't get overwritten or re-editing them after changing the original setup.h, but I'll leave you to ponder those ramifications. Some of the settings you may want to look at are:

  • WXWIN_COMPATIBILITY_2_2 & wxDIALOG_UNIT_COMPATIBILITY - If you are just starting wxWidgets development and don't need backward compatibility, define these to zero.
  • wxUSE_UNICODE - Under VC, this is enabled automatically if either _UNICODE or UNICODE are defined and vice versa. See also Unicode Support in wxWidgets in the manual.
  • wxUSE_GLCANVAS - If you want OpenGL. Don't forget to include opengl32.lib and glu32.lib libraries, for proper linking.
  • wxUSE_WX_RESOURCES & wxUSE_PROLOGIO - For using the old resource system. This is currently being superseded by a new XML based resource system called XRC that needs to be built separately in %WXWIN%\contrib\src\xrc. See the XML-Based Resource System Overview. Documentation for the file format exists in %WXWIN%\docs\tech\tn0014.txt.
  • wxUSE_ODBC - If you want ODBC. See the Database Classes Overview.
  • wxUSE_IOSTREAMH - Define this to zero if you want the library to use the standard <iostream> library header.
  • wxUSE_DYNAMIC_LOADER - In version 2.5.1, even though the comment says it should not be used, you should change it to 1 in order to prevent compiling errors.
  • wxUSE_MEMORY_TRACING & wxUSE_GLOBAL_MEMORY_OPERATORS - If you get link errors about unresolved external symbols for operator new[] and delete[] for all of the sample projects and don't know whats wrong, try turning these settings on. Even though they both default to off, and the comments in setup.h tell you that wxUSE_GLOBAL_MEMORY_OPERATORS commonly causes link errors, they should fix the problem.

See also Setup.H.


Configurations

There are 8 different project configurations (all paths are relative to %WXWIN%):

Name Setup.h Location Output Files
Win32 Release lib\msw\wx lib\msw.lib
Win32 Debug lib\mswd\wx lib\mswd.lib
Win32 Release DLL lib\mswdll\wx lib\wxmsw240.lib, lib\wxmsw240.exp, lib\wxmsw240.dll
Win32 Debug DLL lib\mswdlld\wx lib\wxmsw240d.lib, lib\wxmsw240d.exp, lib\wxmsw240d.dll
Win32 Release Unicode lib\mswu\wx lib\mswu.lib
Win32 Debug Unicode lib\mswud\wx lib\mswud.lib
Win32 Release Unicode DLL lib\mswdllu\wx lib\wxmsw240u.lib, lib\wxmsw240u.exp, lib\wxmsw240u.dll
Win32 Debug Unicode DLL lib\mswdllud\wx lib\wxmsw240ud.lib, lib\wxmsw240ud.exp, lib\wxmsw240ud.dll

At the risk of stating the painfully obvious: Debug builds wxWidgets with debugging information, DLL builds it as a DLL, Unicode builds it with wxChar (which is the character type of all strings in wxWidgets, even though the docs say char a lot, it's essentially a TCHAR) defined as wchar_t instead of char, and probably has other effects. I really don't know offhand.


Project Settings

The main things to worry about with project settings are the C runtime library, precompiled headers, preprocessor definitions, additional include directories, libraries that your program needs, libraries that wxWidgets needs, and the disabling of certain default libraries to resolve symbol conflicts that might occur.

  • C/C++
    • Category: General
      • Additional Include Directories:
        • Specify the location of the setup.h file. It is referenced by the wxWidgets headers. If you used the same setup.h for all wxWidgets configurations, you can just set this to %WXWIN%\lib\msw for all of your project configurations (you'll have to expand the variable yourself or use makefile syntax i.e. $(WXWIN)). Otherwise, you need to match it up with the wxWidgets library you are linking with.
    • Category: Preprocessor
      • Preprocessor definitions:
        • Remove _MBCS unless you know that you need it.
        • Add __WXMSW__ to include MS-Windows code from wxWidgets headers.
        • Add WINVER=0x0400
        • Add UNICODE,_UNICODE for unicode builds.
        • UNICODE is for Windows headers, _UNICODE is for C runtime headers.
        • Add __WXDEBUG__ for debug builds that link to wxWidgets debug configurations. Activates wxASSERT(), etc. See the Debugging Overview for more information.
        • Add WXUSINGDLL for builds that link to a DLL version of wxWidgets.
    • Category: Code Generation
      • For the C runtime library, use the Multithreaded DLL for release and Debug Multithreaded DLL for debug builds, as the multithreaded DLL libraries are the ones wxWidgets is linked with by default. Some common errors you might run into:
        1. MSVCRT.lib(MSVCRT.dll) : error LNK2005: _free already defined in LIBC.lib(free.obj): You're linking with the wrong runtime library. See the docs for the /MD, /ML, /MT, /LD compiler switches in MSDN for more information.
        2. MSVCRT.lib(crtexe.obj) : error LNK2001: unresolved external symbol _main: You have created a console project. Start with a Win32 App and the linker won't miss the _main.
    • Category: Precompiled Headers
      • Precompiled headers are not necessary, but using them gives you such a big improvement in compilation speed that it doesn't make sense not to use them, especially with large libraries that have a lot of interdependent headers like wxWidgets. The way your #include statements are arranged in your source affects the usefulness precompiled headers. Most important is the fact that they have to be in the same order. The way this is normally done is to create an empty module, putting all of the system and library headers that you need for the project in the header, including this header in all of your implementation files, and setting the "through header" field to this header. When a precompiled header needs to be created it is done so during the compilation of one of your files (don't try to set "Create precompiled header..." for the project itself or it will give you the most fatal error imaginable short of crashing your computer). You can do this manually by changing the precompiled header setting to "Create..." for one of your files and compiling it, and afterwards change all of your files to "Use...", but this is kind of a pain because if your project settings change or you modify the included headers the .pch has to be recreated. It is only useful under certain circumstances outside the scope of this document. Just create your precompiled module file as explained above and set all your files to "Automatic use of precompiled headers through header:" and enter the name of the header you created.


Other Tips

wxCRP (dead link) has multiple templates for wxWidgets projects such as library projects, empty projects, console projects, both VS 6.0 and VS .NET.


In Visual C++ 6 (7 should be similar), to create an application that is both a console application (cout's to the console are visible) and has a wxWidgets GUI, you need to use the linker option "/subsystem:console" and the following code:

int main(int argc, char* argv[])
{
	return WinMain(::GetModuleHandle(NULL), NULL, ::GetCommandLine(), SW_SHOWNORMAL);
}

Recommended Links