Microsoft Visual C++ NuGet

From WxWiki
Jump to: navigation, search
This article applies to the following versions
wxWidgets Visual C++
Any 2010 Any Edition (but Express is difficult)
Any 2012 Any Edition
Any 2013 Any Edition
*Any Visual Studio Edition that NuGet supports will work

A workaround for MSVC 2010 Express is demonstrated at the end.

Video Tutorials
How to download and setup wxWidgets in 3 different ways,
how to use this package,
and how to use wxFormBuilder

The developer must obtain wxWidgets via one of the following:

  1. Source code (most secure, but will take some time to build, this package will build it for you)
  2. wxPack (includes prebuilt binaries and other goodies)
  3. Prebuilt binaries (see below section for help on how to download these)

NuGet is an open-source package manager for the Microsoft development platform[1]. It is most frequently used to handle .NET libraries for a .NET project; it supports native C++ libraries as well.

This guide describes a NuGet package that will set up the C++ project to use the wxWidgets library; there are many things [2] that this package configures for you. In addition, this package allows each developer working on the same project to link to wxWidgets how they want to (from source, from prebuilt, statically/dynamically, etc).

This guide (installing the NuGet package) can be completed in the 3 easy steps below.

Three easy steps

(1) Install the NuGet Package Manager

Starting with Visual Studio 2012, the NuGet Package Manager comes preinstalled by default[3].

It can be installed from within Visual Studio, by searching for "NuGet" within Visual Studio's Extension Manager (Tools->Extensions and Updates...). Detailed instructions can be found here[4].

(2) Install the wxWidgetsTemplate NuGet Package

NuGet Package Manager. Menu accessible from Tools->Library Package Manager->Manage NuGet Packages for Solution...

This step is is also done from within Visual Studio. Within the Manage NuGet Packages pane. In Tools->Library Package Manager->Manage NuGet Packages for Solution..., search for and install the wxWidgetsTemplate package.

(3) Customize how wxWidgets is linked to

Reload the project in order for everything to be properly parsed by Visual Studio.

If wxPack was installed, there is no need to configure anything further as the defaults will work. Otherwise, read on.

Project properties: wxWidgets package property page. The wxWidgets properties page may either appear in Common Properties or Configuration Properties depending on your VS version. Also pictured is the properties for the zlib NuGet package (for demonstration purposes).

The meaning of each setting in the properties page depends on if using the prebuilt binaries or source code.

Prebuilt binaries Source code
wxWidgets path This field will automatically be populated with $(WXWIN) if the WXWIN environmental variable is defined (wxPack defines this during the install). Should point to the root folder of the wxWidgets installation/working-copy that will be linked against (e.g. C:\lib\wxWidgets).
SHARED Leave the default setting; only dynamically link to wxWidgets as static builds are not distributed. Determines if the project dynamically links or statically links to wxWidgets.
wxTOOLKIT_PREFIX Leave the default setting; only msw is prebuilt. See documentation[5]. If not using msw, then change this so that the appropriate libraries will be linked to. Want to try the wxUniversal port? Set this to 'mswuniv'.
wxMSVC_VERSION Auto detection should work. If it doesn't, this must be set to what was downloaded and is being targeted (e.g. if downloaded wxMSW-3.0.2_vc120_x64_ReleaseDLL.7z set this to 120). Auto detection should work. If there are multiple builds of wxWidgets with multiple versions of the MSVC compiler, then the one to target should be specified here.
Print MSBuild Variables during compile? Think of this as a verbosity flag. If problems are encountered turn this on, and inspect the Output pane of visual studio to diagnose the problem(s). Not every version of visual studio will display the messages in the Output pane; but they will appear in the build .log file (in the intermediate project directory).
Build wxWidgets library? N/A Will check to see that wxWidgets is built and up to date before compiling the project. If the target wxWidgets configuration isn't built, it will build that wxWidgets configuration. Turn this off to speed up compilation time (as it would skip this check). The library will have to be built for each used build configuration (e.g. x86/x64, release/debug).
Additional build options N/A If building wxWidgets, these options will be passed to the nmake build. If interested, look at the wxWidgets msw build readme to understand what can be specified here. This property is how additional make options may be specified, which were not able to be specified with the other parameters (many options are automatically deduced from the configuration, such as BUILD=release/debug). 'clean' is useful to clean up the build.

If dynamically linking to wxWidgets, the package will set up hard links to the *.dll's within the output folder; this allows the executable to be ran locally within that directory (by double clicking on it).

If any issues regarding this NuGet package are encountered, please open an issue on GitHub[6].

Notes on use with prebuilt binaries

Installing wxPack will set up the headers and the prebuilt binaries (DLLs).

If not using wxPack, three archives must be downloaded: the headers, the release DLLs, and the debug DLLs. They must all be extracted into the same folder (e.g. C:\dev\wxWidgets), such that .\include (headers) and .\lib (prebuilt binaries) exist in that folder.

As an example using wxWidgets 3.0.2, the MSVC2010 compiler, and targeting 32-bit, the following archives would be downloaded from here:

  1. ./wxWidgets-3.0.2_headers.7z
  2. ./binaries/wxMSW-3.0.2_vc100_Dev.7z (debug DLLs)
  3. ./binaries/wxMSW-3.0.2_vc100_ReleaseDLL.7z

Download the 7z archives, not any MSIs. The MSI files are useful as redistributables of the wxWidgets libary (they install the DLLs to %WINDOWS%/system32 by default).

Make sure that the DLL archives downloaded correspond to your MSVC compiler (e.g. for VS 2013 it is v120)[7].

wxWidgets lib folder. These 7z archives after extraction should appear as shown (with both the debug and non-debug DLLs as annotated by the d in the filename, and the vc100_dll may differ depending on what is being targeted).
General project configuration properties: Character Set. MSVC 2010 Express doesn't define _UNICODE by default (others do), but the wxWidgets prebuilt binary expects it to be defined as wxWidgets is built supporting Unicode by default. To define _UNICODE for the project, set the property as shown above.

Notes on the packaged PCH

The package will automatically create and use a precompiled header file (PCH) exclusively for wxWidgets (See the .cpp within the package for more information).

If the project was already using a PCH, it will continue to be used, the packaged PCH will be ignored, and there is no need to change anything.

This PCH roughly halves compilation time as wxWidgets is large. The packaged PCH wasn't designed to be modifiable as modifications would be removed if the NuGet package is updated. It is suggested that a new PCH be set up to optimize compilation time due to other rarely changing code in the project. When setting up a new PCH (e.g. stdafx.h & stdafx.cpp):

  1. In the project properties (for all configurations), define stdafx.h as the PCH instead of wx/wxprec.h.
  2. In the stdafx.cpp properties (for all configurations), set the PCH flag to Create.

If the above settings were properly made, next time the project is built, stdafx.cpp will be the first file compiled.

If you want this feature disabled (not use any PCH), file an issue on GitHub[8] (I can't imagine why this would be desired- disabling this would double compilation time).

Notes on source code management (SCM)

VS will prompt any other developer who opens the project to download any missing NuGet packages (libraries). See this MSDN page for many other available native libraries. Using NuGet packages to distribute .NET libraries is useful, though due to certain issues with package management I wouldn't recommend it for most C++ libraries until NuGet 3.0 is released.

If using version control, version the following:

  1. $(SolutionDir)/.nuget/*, (if it exists)
  2. $(ProjectDir)/packages.config[9]

Do not version the package themselves, which are by default in $(SolutionDir)/packages/

The options chosen in the properties page will be stored in a *.user file. This contains user-specific settings; don't version this file.

MSVC 2010 Express

The 2010 Express edition does not support NuGet; others editions (Ultimate, Pro) do. Of the 2010 Express products, NuGet only supports Microsoft Visual Web Developer 2010 Express[10]. To get NuGet to install the package to our MSVC 2010 Express project, we must trick that other express product into changing the MSVC project:

  1. Install Microsoft Visual Web Developer 2010 Express.
  2. Install the NuGet Package Manager into that Express product[11]
  3. Rename the project filename from .vcxproj to .csproj (this must be done as Web Express won't open VC++ projects, but will open C# projects).
  4. Open the project's solution file (.sln) with notepad, and rename the .vcxproj to .csproj.
  5. Open the solution with Microsoft Visual Web Developer 2010 Express.
  6. Add the NuGet project.
  7. Close everything, and revert what had been renamed (.csproj -> .vcxproj).

NuGet also mentions a command line client, but that won't do every necessary change. Using Web Developer 2010 Express works.