Microsoft Visual C++ Guide

From WxWiki
Jump to navigation Jump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.
This article applies to the following versions
Platform wxWidgets Visual C++
Windows XP 2.6.6
2.8.6
2.8.8
2.8.10 		2008 Express Edition
Windows 7 2.9.3 only 2010 Professional Edition
Status: Current
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
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.

A NuGet package has been made for building and linking to the wxWidgets library for you. This way of linking to wxWidgets is much more conducive to SCM and projects involving more than one developer as each developer may define where wxWidgets is on their machine and how they link to it. To include this package in your project, see the guide here: Microsoft_Visual_C++_NuGet.

Version information

All "Express Edition", or "Community Edition" versions of Visual C++ are available for free, including for commercial use with limitations. Please note that specific versions of Visual C++ are not supported by all versions of wxWidgets. The instructions below apply to all versions unless stated otherwise. Be sure to check the troubleshooting section for known version specific issues if you run into any.

Name Version wxWidgets Support Comments
Visual C++ 6.0 6.0 2.8, 3.0 Released in 1998. Be sure to install the last service pack 6 as well.
Visual C++ .NET 2002 7.0 2.8, 3.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 7.1 2.8, 3.0 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 8.0 2.8, 3.0 This version contains a few improvements to Intellisense and additional STL debugging features.
Visual C++ 2008 9.0 2.8, 3.0 The Express Edition of this version includes the Windows Platform SDK making it easier to build wxWidgets applications.
Visual C++ 2010 10.0 3.0 See What's New in Visual C++ 2010. Free download: Visual C++ 2010 Express
Visual C++ 2012 11.0 3.0 Early C++11 features, and performance tools. See What's New in Visual Studio 2012.
Visual C++ 2013 12.0 3.0 Full C++11 support. See What's New in Visual Studio 2013. Free download: Visual Studio Express 2013 for Windows Desktop

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).

Changing setup settings

Depending on what you want wxWidgets for, you might need to change some specific setup settings before building wxWidgets. The settings that could be of interest are stored as defines in the file setup.h, located in "include\wx\msw\".

  • For OpenGL support, you need to set wxUSE_GLCANVAS to 1 (located at line 1006 of setup.h for version 2.8.11 of wxWidgets) before building wxWidgets. You also need to have OpenGL headers and libraries on your computer to be able to build with this option. If you are running Windows 98/Me/NT/2000/XP/2003/Vista, the OpenGL library has already been installed on your system.

Opening the workspaces

Wxmsw-workspaces.png
Msvc-workspace-version-warn.png

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

  1. Select "Batch Build..." from the Build menu.
  2. Click the "Select All" button to select all projects and configurations (a total of 320 in wxWidgets 2.8).
  3. Read the 2 paragraphs below.
  4. 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.
  • 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.
    • 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 (note that this definition may be inherited from a project default - see note below)
        • _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
      Note that some preprocessor definitions may be included if the "Inherit from parent or project defaults" checkbox is ticked (which is the default). You may need to uncheck this tick box.
    • 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.
    • 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
  • Linker:
    • Category: General
      • Additional Library Directories
        • $(WXWIN)\lib\vc_lib (static) or $(WXWIN)\lib\vc_dll (dll) - The location of the wxWidgets lib directory.
    • 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).
    • Category: System
      • SubSystem
        • Set Windows (/SUBSYSTEM:WINDOWS)

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.

Create a project based on a sample using Visual Studio 2013 Express

  • Create a new empty solution
    • File->Create New Project
    • Installed->Templates->Visual C++->Visual Studio Solutions->Blank Solution
  • Locate the sample you want to use (this is the folder with the vcproj file in).
  • Manually (outside of Visual Studio) copy this project folder into your new solution.
  • Copy the sample.rc and sample.ico from the samples folder to your solution folder
  • In Visual Studio, in Solution Explorer, Right click on the Solution and choose Add->Existing Project from the popup menu.
  • Navigate to your solution directory and open the sample folder you copied.
  • Open the VC++ Project file for your version of Visual Studio
  • In Solution Explorer, Right click on the Project and choose Properties
  • In Configuration Properties->C/C++->General->Additional Include Directories change the paths to use WXWIN:
e.g. .\..\..\include becomes $(WXWIN)\include
  • Do the same for Configuration Properties->Linker->General->Additional Library Directories
  • Do the same for Configuration Properties->Resources->General->Additional Include Directories

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 Express and wxWidgets 2.9.3 Compilation, with Compilation and execution of a Sample Program

The Key to Compilation using Visual C++ 2010 Express and wxWidgets 2.9.3 is to keep Pressing F7 Again-and-Again-and-again.... till you you get '0 Failed' Message below. Because many Projects have dependencies which are not satisfied immediately, so it is necessary to keep compiling with 'F7' till all are satisfied.

Download wxWidgets. I downloaded the .7-Zip File (only 12 MB ! ), and installed it at C:\wxWidgets . You can download the .ZIP File if you wish instead of .7-zip. Now, the Structure of your extracted wxWidgets Source should be like so that you see the following Folders like C:\wxWidgets\lib and C:\wxWidgets\build etc etc...

Basically the process should be to go to C:\wxWidgets\build\msw , and open wx_vc9 Solution File for VC-2008, and convert it to VC-2010 when asked. Then Choose 'DLL-Release Win32' on Top, and Press F7. Wait for Compilation to take place and see the Message. Then keep Pressing F7 again and again till you get '0 Failed' Message below. Once you are done compiling DLL-Release Version, then you would want to Compile 'DLL-Debug' Release in the same manner as described above.

The compiled DLL Files can then be found at C:\wxWidgets\lib\vc_dll. Now, To Add vc_dll Folder to your PATH, Right-Click on My-Computer -> Properties -> Advanced System Settings -> Environment-Variables -> User-Variables. Search for 'Path' -> 'Edit', and then Just Append ;C:\wxWidgets\lib\vc_dll to the End.

This makes running your compiled Application easier, as your .EXE can now easily find DLLs. When you are packaging, then you obviously need to bundle specific Release-DLL'S along.

Then you can compile the Samples located at C:\wxWidgets\samples. I just go to individual Project Folder, like for e.g. C:\wxWidgets\samples\drawing, and Open drawing_vc9 Project, then Convert it as Prompted, and then hit F7 to create Release Version. Now if you go inside C:\wxWidgets\samples\drawing\vc_mswudll\ Folder, you have your 'drawing.exe' ready-to-be-run !

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:

  1. Download and execute the 2.9.1 .exe installer.
  2. Download wx291_msw_vc10.zip from this page.
    1. Unzip it in the "build" directory.
  3. 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).

VC10 wxWidgets.png


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:

  1. ...\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:

  1. Open wx_vc9.sln
  2. Go through with the conversion process
  3. Close the Visual Studio
  4. Open all the newly created *.vcxproj files in a texteditor
  5. replace the string $(INTDIR) $(OUTDIR);% with $(INTDIR);$(OUTDIR);% (note the added semicolon)
  6. Open wx_vc9.sln again
  7. Build as expected. The error should not appear

Note: If both Visual Studio 2010 and 2012 are installed, an error can occur in linking with 2010: "fatal error LNK1123: failure during conversion to COFF: file invalid or corrupt". This may be rectified by installing Visual Studio 2010 SP1. [1]

WxWigets VS 2010.png

Troubleshooting

See Troubleshooting building wxWidgets using Microsoft VC.

See also

WxMSW Issues

External links

Retrieved from "https://wiki.wxwidgets.org/index.php?title=Microsoft_Visual_C%2B%2B_Guide&oldid=10897"