Microsoft Visual C++ Guide
This article applies to the following versions | ||
Platform | wxWidgets | Visual C++ |
---|---|---|
Windows XP | 2.6.6 2.8.6 2.8.8 |
2008 Express Edition |
Status: Partly Out of Date |
Related Articles |
---|
Visual C++ 2008: Visual Studio 2008 (9.0) |
Visual C++ 6.0: User's Guide For VCpp 6.0 MSVC Setup Guide Installing wx 2.4 with VisualStudio 6 |
Visual C++ Toolkit 2003: Installing WxWin For MS Free Tools |
Video Tutorials |
Setting up wxWidgets 2.8.10 Download, install, compile, and test wxWidgets 2.8.8 Download the wx.vsprops file |
This guide outlines the steps for building the wxWidgets library, building and running the included samples, and outlines two separate ways of setting up your own project (the first by hand, and the second by copying one of the wxWidgets sample projects). This is an informal, complementary guide to the official wxWidgets MSW installation docs included with wxWidgets at docs\msw\install.txt (which can also be found online), please read all of the "Microsoft Visual C++ compilation" section before following this guide for important installation notes not covered here. If you run into any problems, check the troubleshooting section first, then all of the wxWidgets FAQs, and failing those, you can try the mailing lists, forums, or IRC.
Version Information
It is recommended that you use Visual C++ 2008 Express Edition - available for free, including for commercial use (or one of the other 2008 editions such as Professional if you need features not included in the Express Edition). However, wxWidgets is compatible with every version of Visual C++ listed below if you need to use an older or newer version for some reason. The instructions below apply to all versions of Visual C++ from 6.0 to 10.0. Be sure to check the troubleshooting section for known version specific issues if you run into any.
Version | Aka | Comments |
---|---|---|
Visual C++ 6.0 | VC6 | Released in 1998. Be sure to install the last service pack 6 as well. |
Visual C++ .NET 2002 | Visual C++ 7.0 | First edition of Visual C++ to include managed extensions to the C++ language shared with Visual Basic and Visual C#. This version was known to contain some major bugs at release, and it's highly recommended developers either stick with 6.0 (since wxWidgets does not use the managed extensions anyway) or upgrade to at least 7.1. |
Visual C++ .NET 2003 | Visual C++ 7.1 | Released as a major upgrade to 7.0 fixing a number of issues. The compiler and linker were released for free in the Visual C++ Toolkit 2003 (which has now been taken down in favor of using Visual C++ 2005 (8.0) Express Edition). |
Visual C++ 2005 | Visual C++ 8.0 | This version contains a few improvements to Intellisense and additional STL debugging features. |
Visual C++ 2008 | Visual C++ 9.0 | (Recommended) (works best with wxWidgets 2.8 and 2.9+). As opposed to 2005, the Express Edition of this version includes the Windows Platform SDK making it much easier to setup applications built on wxWidgets than in 2005. The Express Edition is still available for free, including for commercial use, with limitations. The Professional Version can also be used. See this guide: How to compile a wxWidgets application in Visual Studio 2008? |
Visual C++ 2010 | Visual C++ 10.0 | (Warning: wxWidgets 2.8 Not Supported) The latest current release of Visual C++. The Express Edition is available for free, including for commercial use, with limitations. |
Getting Started
Downloading and Installing wxWidgets
Please see Downloading and installing wxWidgets (be sure to check the troubleshooting section if you are using wxALL, CVS or daily snapshot sources).
Opening the Workspaces
wxWidgets contains two separate Visual C++ workspaces used to build wxWidgets using MSVC: "build\msw\wx.dsw" and "build\msw\wx_dll.dsw". The first has subproject dependency information setup for use when building static libraries, and the second is setup for building dynamic libraries. Both contain configurations for static and dynamic libraries, but you may run into problems building those configurations using the wrong workspace.
The wxWidgets project files distributed for Visual C++ are currently saved in the Visual C++ 6.0 file format. If you are using a version of Visual C++ other than 6.0, you will be asked about converting the project files for the version you are using. This is expected behavior, and you can safely answer "Yes To All" when opening any of the project or workspace files. The files are saved in the 6.0 format simply for backwards compatibility, and will work in all version of Visual C++ from 6.0 to 10.0.
wxWidgets Build Configurations
You are now ready to open the wxWidgets workspace file of your choice, and compile the wxWidgets library. Once opened (and converted if necessary), the wxWidgets workspace contains multiple configurations for all subprojects (Debug or Release, ANSI or Unicode, Static or Dynamic, Universal). If you are not familiar with what these are or how they work, please read WxWidgets Build Configurations before continuing onward. (You might also want to have a look at Understanding wxWidgets Build Scheme.)
Building wxWidgets
At this point, you hopefully have a good idea of what configurations you will need to build. If you don't already have either the wx.dsw or wx_dll.dsw (both explained above) workspace open, do so now. The basic process of building wxWidgets involves either batch building all configurations, or changing your active configuration to the ones you need and building those.
If you batch build all configurations, be aware that you will almost certainly run into problems building specific projects in certain configurations. wxWidgets makes every effort to keep these in working order, but there are a lot of different configurations, projects, and distribution methods that can play a part in errors. When projects (or whole configurations) fail to compile you will need to either make sure they are not ones you need, or figure out what's wrong with them and fix them as you go. You should also note that batch building everything will take anywhere from one to two hours (assuming you don't run into problems), and will take up as much as 10GB of disk space.
Building single configurations one at a time will usually take 5 to 10 minutes per configuration, and will result in only needing 400 to 800 megabytes depending on which configurations you need. Using this process can help with pinpointing problems with the build, and you will know for sure when configurations you need failed to build. In theory, this method of building wxWidgets should take more steps, and is slightly more complex, but in practice it tends to be easier since most users run into fewer problems this way. Skip down to the Building Single Configurations section if you would rather use this method.
If the computer you are compiling wxWidgets on has a multi-core CPU (most newer processors these days), Visual C++ will attempt to build multiple projects simultaneously on each core. This has been known to cause Visual C++ to ignore wxWidgets project dependencies which can result in the failure of some projects to build correctly. If this happens, you can simply just tell Visual C++ to build the solution again until it successfully builds any remaining projects that failed to build. If the number of projects that fail stays the same between two builds, this means that you have a problem involving something else.
Batch Building All
- Select "Batch Build..." from the Build menu.
- Click the "Select All" button to select all projects and configurations (a total of 320 in wxWidgets 2.8).
- Read the 2 paragraphs below.
- Click "Build" to start building wxWidgets.
(I have found that if I manually set the Project Dependencies in MSVC before I do any builds, I do not have to repeat the process multiple times. Simply right click on the solution name in the Solution Explorer and select Project Dependencies... from the menu. Then start at the bottom of the list shown below and make each one dependent on the one above it. Once you have done this, simply build as described above and MSVC will build in the correct sequence each and every time. ~BruceKahn)
Use the time now to go watch a movie (I recommend The Fifth Element), or get a head start reading the wxWidgets Manual. If you come back to find failed builds and are not sure how to fix it, check the troubleshooting section, the FAQs, and lastly, the mailing lists, forums, and IRC. Repeat the steps above until all configurations build successfully. Alternatively, you can figure out which configurations you really need, and use the single configuration build method
Building Single Configurations
Build all libraries you need one by one, in the following order:
wxjpeg, wxpng, wxtiff, wxzlib, wxregex, wxexpat, base, net, odbc, core, gl, html, xml, media, qa, adv, dbgrid, xrc, aui, richtext
Check your file : "wxWidgets-X.Y.Z\INSTALL-MSW.txt"
Building Output
The libraries created by the build process are located under \lib\vc_lib and will have .lib extension. For a list of possible files see Library files under Windows.
Building the wxWidgets Samples
- Open the sample's .DSW file in .NET
- Hit yes to convert
- Select the same build you did above (in 'Steps to build wxWidgets')
- Build
However, this may result into rebuilding the wx libs/dlls again. If you had already built these, do following instead:
- Open the sample's .DSW file in .NET
- Hit yes to convert
- Remove those projects from the sample solution, which you already have build (in 'Steps to build all wxWidgets projects')
- Build
Creating a New Project by Hand
The main things to worry about with project settings are the C runtime library, 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.
Start with a Visual C++ Win32 Project and accept the default settings. (I suggest to check the "empty project" checkbox [or unselect "precompiled header" for static libs] so you can start really clean. Also, don't forget that until you have a .cpp file inside the project, the C/C++ won't appear under "configuration settings" in the project's properties -DL)
Project Properties
- General
- Character Set
- Select Not Set, Unicode, or Multi-Byte depending on what you need.
- Character Set
- C/C++
- Category: General
- Additional include directories:
- $(WXWIN)\include - The location of the wxWidgets include directory.
- $(WXWIN)\include\msvc - This automatically includes the build-specific setup.h files.
- Detect 64-bit Portability Issues: Select No to avoid warning messages on strings.
- Additional include directories:
- Category: Preprocessor:
- Preprocessor definitions:
- WIN32 - Required
- WINVER=0x0400 - Required
- __WXMSW__ - Required
- _WINDOWS - Required
- WXUSINGDLL - If you're compiling using DLLs instead of a static build
- wxUSE_GUI=1 - Add this for projects using GUI components (optional)
- _UNICODE - Add this if you are using Unicode
- _DEBUG - Enables debugging
- __WXDEBUG__ - Add this for debug builds that link to wxWidgets debug configurations. Activates wxASSERT(), etc. See the Debugging Overview for more information.
- _CRT_SECURE_NO_DEPRECATE - Add this if you want to suppress "This function or variable may be unsafe. Consider using <alternative> instead." warnings.
- _CRT_NONSTDC_NO_DEPRECATE - Suppresses other warnings.
- Complete string: WIN32;_WINDOWS;WINVER=0x0400;__WXMSW__;WXUSINGDLL;wxUSE_GUI=1;_DEBUG;__WXDEBUG__;_CRT_SECURE_NO_DEPRECATE;_CRT_NONSTDC_NO_DEPRECATE
- Preprocessor definitions:
- Category: Code Generation
- For the C runtime library, use the Multithreaded DLL (/MD) for release and Debug Multithreaded DLL (/MDd) for debug builds, as the multithreaded DLL libraries are the ones wxWidgets is linked with by default. If you get something like
MSVCRT.lib(MSVCRT.dll) : error LNK2005: _free already defined in LIBC.lib(free.obj)
then you're linking with the wrong runtime library.
- For the C runtime library, use the Multithreaded DLL (/MD) for release and Debug Multithreaded DLL (/MDd) for debug builds, as the multithreaded DLL libraries are the ones wxWidgets is linked with by default. If you get something like
- Category: Precompiled Headers
- Create/Use Precompiled Headers: Not using Precompiled Headers - See the Tips'n'Tricks section of the wiki for setting up precompiled headers
- Category: General
- Linker:
- Category: General
- Additional Library Directories
- $(WXWIN)\lib\vc_lib (static) or $(WXWIN)\lib\vc_dll (dll) - The location of the wxWidgets lib directory.
- Additional Library Directories
- Category: Input
- Additional Depenedencies:
- wxmsw28[ud]_core.lib wxbase28[ud].lib - The core Wx libraries. Note, you need to choose the correct ones according to the table below. For example, for debug ANSI static: wxmsw28d_core.lib wxbase28d.lib
- comctl32.lib rpcrt4.lib winmm.lib advapi32.lib wsock32.lib - wxWidgets needs these.
- wxpng[ud].lib wxzlib[ud].lib wxjpeg[ud].lib wxtiff[ud].lib (release) - Wx support libraries (optional, modify file names according to need).
- Additional Depenedencies:
- Category: System
- SubSystem
- Set Windows (/SUBSYSTEM:WINDOWS)
- SubSystem
- Category: General
Core wxWidgets libraries to include
Directory | Basic wxWidgets libraries | Description |
lib\vc_lib\msw | wxmsw28_core.lib wxbase28.lib | release ANSI static |
lib\vc_lib\mswd | wxmsw28d_core.lib wxbase28d.lib | debug ANSI static |
lib\vc_lib\mswu | wxmsw28u_core.lib wxbase28u.lib | release Unicode static |
lib\vc_lib\mswud | wxmsw28ud_core.lib wxbase28ud.lib | debug Unicode static |
Linking with correct runtime library
Runtime Library name | Switch | CRT library file | Macro(s) Defined | wxWidgets options | Description |
Multithreaded | /MT | LIBCMT.lib | _MT | RUNTIME_LIBS=static BUILD=release | release static |
Multithreaded Debug | /MTd | LIBCMTD.lib | _MT _DEBUG | RUNTIME_LIBS=static BUILD=debug | debug static |
Multithreaded DLL | /MD | MSVCRT.lib | _MT _DLL | RUNTIME_LIBS=dynamic BUILD=release | release dynamic |
Multithreaded Debug DLL | /MDd | MSVCRTD.lib | _MT _DEBUG _DLL | RUNTIME_LIBS=dynamic BUILD=debug | debug dynamic |
Creating a New Project From a Sample
If you have trouble with the above method, this is also an option. If you can get a sample to build, you should be able to use this method without issues.
This tutorial takes the simple (and usually best) route, of copying a sample's project file. This automatically sets up all the right build configurations, and is less error prone than manually creating a project file.
- First convert samples\internat\internat.dsp to Visual Studio .NET as above. This will create internat.vcproj and internat.sln.
- Copy internat.vcproj and internat.sln to your application directory, rename as myapp.vcproj and myapp.sln.
- Open myapp.vcproj in notepad.
- Search replace "internat" with "myapp".
- Search replace "..\.." with "c:\wxWidgets-2.6.2" or wherever you installed wxWidgets to.
- (Note: with wxWidgets 2.6.2 and VC8 Express or VC .NET 2003 (7.1), the above will yield odd results. Try searching and replacing ".\..\.." with "c:\wxWidgets-2.6.2" or wherever instead. Add more info to this wiki if you find this to be true of other combinations.)
- Search replace "../.." with "c:\wxWidgets-2.6.2" or wherever you installed wxWidgets to.
- Save and close.
- Open myapp.sln in notepad.
- Search replace "internat" with "myapp".
- Search replace "..\.." with "c:\wxWidgets-2.6.2" or wherever you installed wxWidgets to.
- Save and close.
- Open myapp.sln in Visual Studio .NET, add your source files to the project and build.
Note that you can add the wxWidgets include/lib paths to your Visual Studio's search paths (under Tools>Options>Projects>VC++ Directories). This is recommeded if you will be working with anyone else on the project. Otherwise, specifying your path to wxWidgets directly in the project, as described above, is all you need.
Visual C++ 2005 Express and Text Editor of Your Choice
If all else fails (although I wish I had tried this earlier), open the sample's converted .vcproj file in a text editor and take a close look at what the paths should be. The solution file is of no value, it will get created automatically. In fact the solution file will be counterproductive if you built all the samples at once, because it brings up all the samples!
In the text editor, pay close attention to the OutputDirectory, IntermediateDirectory, AdditionalIncludeDirectories, AdditionalDependencies, and OutputFile attributes and make sure they are what you expect. Use the $(WXWIN) variable and relative paths whenever possible. You are doing two things at once, preparing your app for building and making sure the project reflects your preferred code organization.
Search and replace the sample name with your app name, then edit it so that it only contains a single Configuration (such as "Release|Win32"). This must match the build under which you compiled wxWidgets. A single configuration may lose some functionality but makes it harder to screw up the file. The uniqueness of the ProjectGUID setting is necessary to calculate the build order correctly from the project dependencies. So you should search and replace the duplicate GUID by a unique one in the .vcproj and .sln files. (Otherwise it should only matter in .NET applications, according to Microsoft.)
Now reopen the .vcproj file in the IDE and remove the bogus files (left over from the sample) and add the real files. If the .cpp files you added do not appear under Source Files, close VC, fire up the text editor again and move the File elements so that they are inside the Filter elements and then close and reopen in VC8.
Visual Studio C++ 2008 Professional
The following steps work on Visual Studio C++ 2008 Professional and will probably work on Express as well.
How to compile a wxWidgets application in Visual Studio 2008?
Please provide feed back and we can migrate this documentation to this wiki.
Visual Studio C++ 2010
The wxWidgets Custom build rules in default uses "$(Input)" instead of the new "%(Identity)" for all the custom build rules. Open all project files (.vcxproj) in a text editor and use Find & Replace to replace all occurrences of $(Input) with %(Identity).
In case of problems while importing the original VC++ 6 workspace (*.dsw), try conversion via VS C++ 2008 (open *.dsw -> create *.sln / *.vcproj) -> open *.sln in VS C++ 2010 (create -> *.vcxproj, this step may be slow).
Note: at time of writing (25/09/2010), for building wxWidgets with VC++ 2010, it is recommended to carry out the 3 following simple steps:
- Download and execute the 2.9.1 .exe installer.
- Download wx291_msw_vc10.zip from this page.
- Unzip it in the "build" directory.
- In build/wx291_msw_vc10, open wx_vc10.sln, select a configuration (for example "DLL Release") and hit F7 until all 22 projects are built successfully (see below screenshot).
Note: at time of writing (09/11/2010) A Bug in the conversion process of Visual C++ Express 2010 may cause an error similar to:
- ...\Microsoft.CppCommon.targets(151,5): error MSB6001: Invalid command line switch for "cmd.exe". The path is not of a legal form.
A potential workaround is as follows:
- Open wx_vc9.sln
- Go through with the conversion process
- Close the Visual Studio
- Open all the newly created *.vcxproj files in a texteditor
- replace the string $(INTDIR) $(OUTDIR);% with $(INTDIR);$(OUTDIR);% (note the added semicolon)
- Open wx_vc9.sln again
- Build as expected. The error should not appear
Troubleshooting
See Troubleshooting building wxWidgets using Microsoft VC.
See also
External Links
- How to link with the correct C Run-Time (CRT) library
- Herb Thompson's build report - with the steps he followed (Visual C++ 2008 Express & wxWidgets 2.8.6)
- Compiling & Using wxWidgets - a German tutorial for wxWidgets 2.8.7 and VS 2008 (9.0)
- wxCRP - Many useful project templates and code snippets; wxCRP is abandoned and replaced with CodeVolution
- CodeVolution (CVL) - (not yet released to the public)
- Lit Window Productions: Additional help and tools for using wxWidgets with Visual Studio (Commercial).
- How to find the file and line number of memory leaks using C++ with wxWidgets in Visual Studio 2008? - Visual Studio will show you memory leaks when you close the program after debugging, but will not show you the line number. With this setup the line number shows, which makes it easier to find those pesky memory leaks.