upgrade legacy C++ code with compiler options

A complete collection of upgrading legacy projects.

upgrade legacy C++ code with compiler options.

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

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

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

3. Code that conforms to all versions of the standard but is no longer considered best practice in modern C++.
To identify code where changes are recommended, run Code analysis.
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.

4. Upgrade your code to the Universal CRT

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

With this refactoring, the names or locations of many CRT header files, library files, and redistributables, and the deployment methods required for your code have changed. In addition, many functions and macros in the UCRT were added or changed to improve standards conformance. To take advantage of these changes, your existing code and project build systems must be updated.

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 SP2, Windows Server 2003 SP1, 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.

In most cases, the What's New or Breaking Changes document for each release of Visual Studio doesn't mention changes to library internals. After all, you're not supposed to be affected by these implementation details. However, sometimes the temptation to use some code you can see inside the library is too great. This topic discusses dependencies on CRT or Standard Library internals you may have relied on, and how to update your code to remove those dependencies so you can make it more portable or migrate to new versions of the library.

7. New math functions and Universal CRT changes

Most CRT math functions have been available in Visual Studio for years, but starting in Visual Studio 2013, all of the functions required by ISO C99 are included. These functions are implemented to balance performance with correctness. Because producing the correctly rounded result in every case may be prohibitively expensive, these functions are designed to efficiently produce a close approximation to the correctly rounded result. In most cases, the result produced is within +/-1 unit of least precision, or ulp, of the correctly rounded result, though there may be cases where there is greater inaccuracy. If you were using a different math library to get these functions before, implementation differences may be responsible for the change in your results.

When the math functions were moved to the Universal CRT in Visual Studio 2015, some new algorithms were used, and several bugs in the implementation of the functions that were new in Visual Studio 2013 were fixed. These changes can lead to detectable differences in the results of floating-point calculations that use these functions. The functions that had bug issues were erf, exp2, remainder, remquo, scalbln, and scalbn, and their float and long double variants. Other changes in Visual Studio 2015 fixed issues in preserving floating point status word and exception state information in _clear87, _clearfp, fegetenv, fesetenv, and feholdexcept functions.

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

This is a paragraph.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

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.

The following sections summarize the changes from VCBuild to MSBuild. If your VCBuild project has custom build rules or macros that aren't recognized by MSBuild, see Visual Studio Projects - C++ to learn how to translate those instructions to the MSBuild system. The initial conversion from VCBuild to MSBuild is just an intermediate step. It isn't necessary to get the project file completely correct or to get the program to compile without errors. You are only using Visual Studio 2010 to convert the project to MSBuild format so that you get the project working in the latest version of Visual Studio.

11. Porting and Upgrading: Examples and Case Studies

You can get an idea of the kinds of issues you might encounter duration a migration from a previous version of Visual C++ to the current one by reviewing stories of successful migrations.