Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/MicrosoftDocs/cpp-docs/llms.txt

Use this file to discover all available pages before exploring further.

MSBuild is the native build system for Visual Studio and is the best choice for Windows-specific C++ applications. A Visual Studio C++ project is represented by a .vcxproj XML file that describes source files, compiler options, linker options, and custom build steps. MSBuild is tightly integrated with the Visual Studio IDE — property pages expose every build setting with documentation, and the build engine supports incremental compilation, parallel builds, and multi-project solutions. You can also invoke MSBuild directly from the command line, making it suitable for CI pipelines that do not need the full IDE.

​
Creating a Visual Studio C++ Project

1

New Project Dialog

Select File → New → Project. In the Create a new project dialog, set the Language filter to C++. Choose a project template such as Console App, Windows Desktop Application, Dynamic-Link Library (DLL), or Static Library, then click Next.
2

Configure Project

Enter the project name, location, and solution name on the Configure your new project page. Click Create. Visual Studio creates a .vcxproj file, a .sln solution file, and default source files.
3

Add Source Files

Right-click the project in Solution Explorer and choose Add → New Item or Add → Existing Item to add .cpp and .h files to the project.
4

Set Properties and Build

Right-click the project and choose Properties to open the Property Pages dialog. Configure compiler and linker options, then press F5 or Build → Build Solution (Ctrl+Shift+B).

​
Understanding the .vcxproj File

A .vcxproj file is an MSBuild XML project file. You rarely edit it by hand, but understanding its structure helps when troubleshooting or applying bulk changes. 
<?xml version="1.0" encoding="utf-8"?>
<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

  <!-- Import default props -->
  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.Default.props" />

  <!-- Configuration/Platform combinations -->
  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'" Label="Configuration">
    <ConfigurationType>Application</ConfigurationType>
    <UseDebugLibraries>true</UseDebugLibraries>
    <PlatformToolset>v143</PlatformToolset>
    <CharacterSet>Unicode</CharacterSet>
  </PropertyGroup>

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|x64'" Label="Configuration">
    <ConfigurationType>Application</ConfigurationType>
    <UseDebugLibraries>false</UseDebugLibraries>
    <PlatformToolset>v143</PlatformToolset>
    <WholeProgramOptimization>true</WholeProgramOptimization>
    <CharacterSet>Unicode</CharacterSet>
  </PropertyGroup>

  <!-- Compiler settings per configuration -->
  <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Release|x64'">
    <ClCompile>
      <Optimization>MaxSpeed</Optimization>
      <IntrinsicFunctions>true</IntrinsicFunctions>
      <PreprocessorDefinitions>NDEBUG;%(PreprocessorDefinitions)</PreprocessorDefinitions>
      <RuntimeLibrary>MultiThreadedDLL</RuntimeLibrary>
      <WarningLevel>Level4</WarningLevel>
      <AdditionalIncludeDirectories>$(SolutionDir)include;%(AdditionalIncludeDirectories)</AdditionalIncludeDirectories>
    </ClCompile>
    <Link>
      <SubSystem>Console</SubSystem>
      <EnableCOMDATFolding>true</EnableCOMDATFolding>
      <OptimizeReferences>true</OptimizeReferences>
      <GenerateDebugInformation>true</GenerateDebugInformation>
    </Link>
  </ItemDefinitionGroup>

  <!-- Source files -->
  <ItemGroup>
    <ClCompile Include="src\main.cpp" />
    <ClCompile Include="src\engine.cpp" />
  </ItemGroup>
  <ItemGroup>
    <ClInclude Include="include\engine.h" />
  </ItemGroup>

</Project>

​
Project Properties

Open the Property Pages dialog (Project → Properties or right-click the project in Solution Explorer). All settings are scoped to a Configuration (Debug, Release, or custom) and Platform (Win32, x64, ARM, ARM64).
Always verify which Configuration and Platform are selected at the top of the Property Pages dialog before modifying a setting. Changes apply only to the selected combination.

​
Key Property Categories

PropertyDescription
Output DirectoryDirectory for the final .exe, .dll, or .lib. Default: $(SolutionDir)$(Platform)\$(Configuration)\
Intermediate DirectoryDirectory for .obj and .pch files. Default: $(Platform)\$(Configuration)\
Configuration TypeApplication (.exe), Dynamic Library (.dll), Static library (.lib)
Platform ToolsetMSVC toolset version (v143 = VS 2022, v142 = VS 2019)
C++ Language StandardMaps to /std:c++14, /std:c++17, /std:c++20, /std:c++latest
PropertyCompiler FlagDescription
Additional Include Directories/ISemicolon-separated list of paths to search for #include files
Debug Information Format/Z7, /Zi, /ZIWhere debug symbols are stored
Warning Level/W0–/W4, /WallCompiler warning verbosity
Treat Warnings As Errors/WXFail the build on any warning
SDL Checks/sdlEnable additional Security Development Lifecycle checks
PropertyCompiler FlagDescription
Preprocessor Definitions/DSemicolon-separated list, e.g. WIN32;NDEBUG;_CONSOLE
Undefine Preprocessor Definitions/URemove a previously-defined macro
Always append %(PreprocessorDefinitions) to inherit the parent scope’s definitions:
<PreprocessorDefinitions>MY_DEFINE;NDEBUG;%(PreprocessorDefinitions)</PreprocessorDefinitions>
PropertyCompiler FlagDescription
Optimization/Od, /O1, /O2, /OxDisabled, minimize size, maximize speed, or full
Inline Function Expansion/Ob0, /Ob1, /Ob2Controls inlining aggressiveness
Intrinsic Functions/OiReplace function calls with compiler intrinsics
Favor Size or Speed/Os, /OtTrade size for speed or vice-versa
Whole Program Optimization/GLEnable cross-module optimization (use with /LTCG)
PropertyCompiler FlagDescription
Runtime Library/MD, /MT, /MDd, /MTdLink to DLL or static CRT
Enable C++ Exceptions/EHscEnable standard C++ exception handling
Enable Run-Time Type Information/GREnable dynamic_cast and typeid
Security Check/GSBuffer overrun detection
Struct Member Alignment/ZpOverride default struct packing
PropertyLinker FlagDescription
Output File/OUTName of the output file
Additional Library Directories/LIBPATHExtra paths to search for .lib files
Enable Incremental Linking/INCREMENTALSpeed up repeated links at the cost of some size
PropertyLinker FlagDescription
Additional Dependencies(listed libs)Explicit .lib files to link against, e.g. kernel32.lib;user32.lib
Ignore All Default Libraries/NODEFAULTLIBDo not link CRT or Windows SDK default libs
Ignore Specific Default Libraries/NODEFAULTLIB:nameExclude a named library

​
Using Property Sheets (.props)

Property sheets allow you to define shared settings once and apply them across multiple projects. This is the recommended way to share include paths, preprocessor definitions, and library paths across a solution. Creating a property sheet:
  1. Open View → Property Manager.
  2. Right-click a project and choose Add New Project Property Sheet.
  3. Name the file (e.g., SharedSettings.props) and save it at the solution root.
  4. Edit the sheet to add common settings.
Example SharedSettings.props: 
<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <PropertyGroup Label="UserMacros">
    <VendorRoot>$(SolutionDir)third_party</VendorRoot>
  </PropertyGroup>
  <ItemDefinitionGroup>
    <ClCompile>
      <AdditionalIncludeDirectories>
        $(VendorRoot)\include;%(AdditionalIncludeDirectories)
      </AdditionalIncludeDirectories>
      <PreprocessorDefinitions>
        MY_LIBRARY_VERSION="2.0";%(PreprocessorDefinitions)
      </PreprocessorDefinitions>
    </ClCompile>
    <Link>
      <AdditionalLibraryDirectories>
        $(VendorRoot)\lib\$(Platform)\$(Configuration);%(AdditionalLibraryDirectories)
      </AdditionalLibraryDirectories>
    </Link>
  </ItemDefinitionGroup>
</Project>
Import the sheet in each .vcxproj that needs it: 
<ImportGroup Label="PropertySheets">
  <Import Project="$(SolutionDir)SharedSettings.props" />
</ImportGroup>
Use MSBuild macros ($(SolutionDir), $(Platform), $(Configuration), $(VC_SourcePath)) instead of absolute paths in property sheets. This makes settings portable across machines and CI environments.

​
Multi-Project Solutions

A Visual Studio solution (.sln) coordinates multiple projects. The solution file tracks project dependencies and the build order. Adding a project to an existing solution: Right-click the solution node in Solution Explorer → Add → New Project or Add → Existing Project. Setting project dependencies: Right-click the solution in Solution Explorer → Project Dependencies. Check which projects must build before others. Referencing another project: Right-click the consuming project in Solution Explorer → Add → Reference, and select the project to reference. This automatically adds the correct .lib output to the linker’s input list and establishes a build dependency. Example: a solution with a library and an application: 
MyApp.sln
├── MathLib\
│   ├── MathLib.vcxproj    (Static Library)
│   └── src\math.cpp
└── MyApp\
    ├── MyApp.vcxproj       (Console Application, References MathLib)
    └── src\main.cpp

​
Building with MSBuild from the Command Line

After setting up the MSVC environment (see Command-Line Builds), you can invoke MSBuild directly: 
# Build the Release|x64 configuration
msbuild MyApp.vcxproj /p:Configuration=Release /p:Platform=x64

# Build the entire solution
msbuild MyApp.sln /p:Configuration=Release /p:Platform=x64

# Parallel build using 8 processes
msbuild MyApp.sln /p:Configuration=Release /p:Platform=x64 /m:8

# Clean and rebuild
msbuild MyApp.sln /t:Clean;Build /p:Configuration=Release /p:Platform=x64
Starting in Visual Studio 2019 version 16.5, MSBuild does not use the command-line environment to determine the toolset. Always set the platform using /p:Platform= rather than relying on environment variables.

​
Target Platforms

Visual Studio C++ projects support multiple target architectures via the Platform configuration:
Platform NameTarget Architecture
Win3232-bit x86 Windows
x6464-bit x64 Windows
ARM32-bit ARM Windows
ARM6464-bit ARM64 Windows
Add a new platform via Build → Configuration Manager → Active Solution Platform → <New>.

Build docs developers (and LLMs) love

Get started for freeTalk to us