Porting C++ programs from Linux to Windows using vcpkg, CMake, and Visual Studio

Recently I had to reinstall Windows to debug a hardware issue. I decided to try to make the most of this by trying to build my game on Windows.

Installing vcpkg

First, you need to clone vcpkg. I installed the git bash program from the git website

git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.bat

Next, you need to decide whether to install 32-bit (x86) or 64-bit (x64) dependencies, or both, then run one or both of the following commands:

VCPKG_DEFAULT_TRIPLET=x86-windows ./vcpkg.exe install DEPS
VCPKG_DEFAULT_TRIPLET=x64-windows ./vcpkg.exe install DEPS

where DEPS is a space-deliminated list of package names.

You can search for packages like so:

./vcpkg.exe search query

If you’re unable to find a dependency, you may have to write your own “port” file to add it to vcpkg.

Finally, to let Visual Studio know about the dependencies, run this:

./vcpkg.exe integrate install

Building

Toolchain

Import your program into Visual Studio as a cmake project. When generating the CMake cache, you’ll probably receive “not found” errors.

Right click on CMakeLists.txt and select “Open CMake Settings”. A file called CMakeSettings.json should appear, with content like the following:

{
  "configurations": [
    {
      "name": "x64-Release",
      "generator": "Ninja",
      "configurationType": "RelWithDebInfo",
      "inheritEnvironments": [
        "msvc_x64_x64"
      ],
      "buildRoot": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}\\build\\${name}",
      "installRoot": "${env.USERPROFILE}\\CMakeBuilds\\${workspaceHash}\\install\\${name}",
      "cmakeCommandArgs": "",
      "buildCommandArgs": "-v",
      "ctestCommandArgs": ""
    }
  ]
}

Add the vcpkg toolchain file to cmakeCommandArgs

"cmakeCommandArgs": "-DCMAKE_TOOLCHAIN_FILE=\"C:\\Users\\ruben\\vcpkg\\scripts\\buildsystems\\vcpkg.cmake\""

Clear the CMake cache by doing CMake > Delete Cache Folders > CMakeLists.txt, then click the Generate button on the CMake changes detected banner.

This should be enough to get Visual Studio to find the dependencies, but I found that this wouldn’t work when you have custom CMake find files which probably don’t support the toolchain.

Explicit dependency paths

I’ve yet to find out how to modify the find modules to use vcpkg’s toolchain cleanly, but in the meantime I set the directories manually by adding CMake flags and environment variables.

You should prefer more general settings to individual include/lib settings. For example, findX.cmake files may allow you to specify a single environment variable to the install root instead of separate X_INCLUDE_DIR and X_LIBRARY CMake variables. This is shown below, with ENETDIR and SFML_ROOT. Don’t be too afraid to modify any embedded find scripts to support environment variables.

{
  "environments": [
    {
      "ENETDIR": "C:\\Users\\ruben\\vcpkg\\installed\\x64-windows",
      "SFML_ROOT": "C:\\Users\\ruben\\vcpkg\\installed\\x64-windows",
      "SFGUI_ROOT": "C:\\Users\\ruben\\vcpkg\\installed\\x64-windows",
      "THOR_ROOT": "C:\\Users\\ruben\\vcpkg\\installed\\x64-windows",
      "LUA_ROOT": "C:\\Users\\ruben\\vcpkg\\installed\\x64-windows"
    }
  ],
  "configurations": [
    {
      "cmakeCommandArgs": "-DCMAKE_TOOLCHAIN_FILE=\"C:\\Users\\ruben\\vcpkg\\scripts\\buildsystems\\vcpkg.cmake\""
    }
  ]
}

Note that you may need to clear the CMake cache and regenerate for changes to take affect.

Common mistakes

Console program vs Windows program

By default, MSVC will compile your program as a console program. This mode results in Windows allocating and showing a console for you when starting the program up. This console will require a redraw on every std::cerr or std::cout print, resulting in massive performance issues.

If you program shows a graphical window, then you should change it to a Windows program.

There are three methods to do this.

1. The first option is to set the executable type to WIN32 in CMake:

    if(WIN32)
        add_executable(${EXECUTABLE_NAME} WIN32 ${SRC})
    else()
        add_executable(${EXECUTABLE_NAME} ${SRC})
    endif()
   

2. Second, by setting linker flags using CMake:

    if(WIN32)
        set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} /SUBSYSTEM:WINDOWS /ENTRY:mainCRTStartup")
    endif()
   

3. The final option is to set the linker flags using a pragma directive:

    #ifdef _WIN32
        #pragma comment(linker, "/SUBSYSTEM:WINDOWS /ENTRY:mainCRTStartup")
    #endif
   

The ENTRY parameter allows you to use the standard main() entrypoint instead of the non-standard WinMain(). You may need to clear and regenerate the CMake cache.

Profit!

Hopefully that should be enough to get it work. Please contact me if you know of any ways to make this cleaner or more robust.