Microsoft C++ porting and upgrading guide

Microsoft C++ porting and upgrading guide

1. Microsoft C++ porting and upgrading guide

This article provides a guide for upgrading Microsoft C++ code to the latest version of Visual Studio. For projects created in Visual Studio 2010 through 2015, just open the project in Visual Studio 2019. You can upgrade a Visual Studio 2008 or earlier project in two steps. Use Visual Studio 2010 to convert the project to MSBuild format first. Then open the project in Visual Studio 2019. For complete instructions, see Upgrading C++ projects from earlier versions of Visual Studio.

The toolsets in Visual Studio 2015, Visual Studio 2017, and Visual Studio 2019 are binary-compatible. Now you can upgrade to a more recent version of the compiler without having to upgrade your library dependencies. For more information, see C++ binary compatibility 2015-2019.

2. Upgrade C++ projects from earlier versions of Visual Studio

To upgrade a project created in an earlier version of Visual Studio, just open the project in the latest version of Visual Studio. Visual Studio offers to upgrade the project to the current schema.

If you choose No, the project doesn't get upgraded. For projects created in Visual Studio 2010 and later, you can still use the project in the newer version of Visual Studio. Just set your project properties to continue to target the older toolset. If you leave the older version of Visual Studio on your computer, its toolset is available in later versions. For example, if your project must continue to run on Windows XP, you can upgrade to Visual Studio 2019. You then specify the toolset as v141_xp or earlier in your project properties. For more information, see Use native multi-targeting in Visual Studio to build old projects.

If you choose Yes, then the project gets upgraded in place. It can't be converted back to the earlier version. In upgrade scenarios, that's why it's good practice to make a backup copy of the existing project and solution files.

3. Overview of potential upgrade issues (Visual C++)

Over the years, the Microsoft C++ compiler has undergone many changes, along with changes in the C++ language itself, the C++ Standard Library, the C runtime (CRT), and other libraries such as MFC and ATL. As a result, when upgrading an application from an earlier version of Visual Studio you might encounter compiler and linker errors and warnings in code that previously compiled cleanly. The older the original code base, the greater the potential for such errors. This overview summarizes the most common classes of issues you are likely to encounter, and provides links to more detailed information.

Note In the past, we have recommended that upgrades that span several versions of Visual Studio should be performed incrementally one version at a time. We no longer recommend this approach. We have found that it's almost always simpler to upgrade to the most current version of Visual Studio no matter how old the code base.

4. Upgrade your code to the Universal CRT

n Visual Studio 2015, the Microsoft C Runtime Library (CRT) was refactored. The Standard C Library, POSIX extensions and Microsoft-specific functions, macros, and global variables were moved into a new library, the Universal C Runtime Library (Universal CRT or UCRT). The compiler-specific components of the CRT were moved into a new vcruntime library.

The UCRT is now a Windows component, and ships as part of Windows 10. The UCRT supports a stable ABI based on C calling conventions, and it conforms closely to the ISO C99 standard, with only a few exceptions. It is no longer tied to a specific version of the compiler. You can use the UCRT on any version of Windows supported by Visual Studio 2015 or Visual Studio 2017. The benefit is that you no longer need to update your builds to target a new version of the CRT with every upgrade of Visual Studio.

the path information is listed in this link.

5. Update WINVER and _WIN32_WINNT

When you use the Windows SDK, you can specify which versions of Windows your code can run on. The preprocessor macros WINVER and _WIN32_WINNT specify the minimum operating system version your code supports. Visual Studio and the Microsoft C++ compiler support targeting Windows 7 SP1 and later. Older toolsets include support for Windows XP SP4, Windows Server 2003 SP4, Vista, and Windows Server 2008. Windows 95, Windows 98, Windows ME, Windows NT, and Windows 2000 are unsupported.

When you upgrade an older project, you may need to update your WINVER or _WIN32_WINNT macros. If they're assigned values for an unsupported version of Windows, you may see compilation errors related to these macros.

6. Fix your dependencies on C++ library internals

Microsoft has published the source code for the Standard Library, most of the C Runtime Library, and other Microsoft libraries in many versions of Visual Studio. The intent is to help you understand library behavior and to debug your code. One side-effect of publishing the library source code is that some internal values, data structures, and functions are exposed, even though they are not part of the library interface. They usually have names that begin with two underscores, or an underscore followed by a capital letter, names that the C++ Standard reserves to implementations. These values, structures, and functions are implementation details that may change as the libraries evolve over time, and so we strongly recommend against taking any dependencies on them. If you do, you risk non-portable code and issues when you try to migrate your code to new versions of the libraries.

7. Floating-point migration issues

Sometimes when you upgrade your projects to a newer version of Visual Studio, you may find that the results of certain floating-point operations have changed. This generally happens for one of two reasons: Code generation changes that take better advantage of the available processor, and bug fixes or changes to the algorithms used in math functions in the C runtime library (CRT). In general, the new results are correct to within the limits specified by the language standard. Read on to find out what's changed, and if it's important, how to get the same results your functions got before

8. Use native multi-targeting in Visual Studio to build old projects

Normally, we recommend that you update your projects when you install the latest version of Visual Studio. The cost of updating your projects and code is usually more than offset by the benefits of the new IDE, compiler, libraries, and tools. However, we know that you may not be able to update some projects. You may have binaries that are tied to older libraries or platforms that for maintenance reasons you can’t upgrade. Your code may use non-standard language constructs that would break if you moved to a more recent compiler. Your code might rely on 3rd party libraries compiled for a specific version of Visual C++. Or you may produce libraries for others that must target a specific older version of Visual C++.

Fortunately, you can use Visual Studio 2017 and Visual Studio 2015 to build projects that target older compiler toolsets and libraries. You don't have to upgrade a Visual Studio 2010, Visual Studio 2012, Visual Studio 2013, or Visual Studio 2015 project to take advantage of new features in the IDE:

9. C++ features deprecated in Visual Studio 2019

Support for Windows XP development Visual Studio 2019 and later does not include support for creating code for Windows XP by using the v142 toolset. Support for Windows XP development by using the v141 toolset that shipped in Visual Studio 2017 is available as an optional component in the Visual Studio Installer. For information on how to install the v141 Windows XP platform toolset, see Configuring programs for Windows XP.

10. VCBuild vs. MSBuild: Build system changes in Visual Studio 2010

The MSBuild system for C++ projects was introduced in Visual Studio 2010. In Visual Studio 2008 and earlier releases, the VCBuild system was used. Certain file types and concepts that depended on VCBuild either do not exist or are represented differently in MSBuild. This document discusses the differences in the current build system. To convert a Visual Studio 2008 project to MSBuild, you must use Visual Studio 2010. After the project is converted, you should use the latest version of Visual Studio to upgrade to the current IDE and compiler toolset. For more information, including how to obtain Visual Studio 2010, see Instructions for Visual Studio 2008.

11. Visual Studio IDE tools for upgrading C++ code

Visual Studio helps you upgrade legacy C++ code with compiler options, code analysis warnings, and editor features such as Quick Fixes, Quick Info, and the enhanced scroll bar. The term "legacy code" refers to any of these categories. this section contains a demo.

Code that was formerly allowed by the Microsoft C++ compiler (MSVC) but never conformed to the C++ standard.

To upgrade older non-conformant MSVC code, turn on the /permissive- compiler option. All instances of non-conformant usages are underlined with red squiggles in the code editor. The error messages in the Error List window include a recommendation for how to fix the error. Click on the error code to go to its help page in the documentation. If fixing all the errors at once is impractical, you can upgrade non-conformant code in stages by turning on the permissive- option, fixing some errors, then turning the option off again. The code will compile with the new improvements, and you can go back and fix the remaining issues at a later time. See the /permissive- page for examples of non-conformant MSVC code.

Code that was permitted in an earlier version of the C++ standard but has been deprecated or removed in a later version.

To upgrade to a newer language standard, set the C++ Language Standard option to the desired standard and fix any compile errors that are raised. In general, we recommend setting the language standard to /std:c++17. The errors raised when upgrading to a newer standard are not related to the errors raised when using the permissive- option.

Code that conforms to all versions of the standard but is no longer considered best practice in modern C++.