Skip to content

Update "Use the Microsoft C++ toolset from the command line" topic #5619

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 56 additions & 43 deletions docs/build/building-on-the-command-line.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,10 @@
---
title: "Use the Microsoft C++ toolset from the command line"
description: "Use the Microsoft C++ (MSVC) compiler toolset from the command line outside of the Visual Studio IDE."
ms.custom: "conceptual"
ms.date: 04/07/2022
helpviewer_keywords: ["command-line builds [C++]", "compiling source code [C++], command line", "builds [C++], command-line", "command line [C++], building from", "command line [C++], compilers"]
ms.assetid: 7ca9daed-a003-4162-842d-908f79058365
ms.custom: "conceptual"
ms.topic: how-to
helpviewer_keywords: ["command-line builds [C++]", "compiling source code [C++], command line", "builds [C++], command-line", "command line [C++], building from", "command line [C++], compilers"]
---
# Use the Microsoft C++ toolset from the command line

Expand Down Expand Up @@ -81,15 +80,15 @@ The Start menu folder and shortcut names vary depending on the installed version
For an even faster way to open a developer command prompt, enter *developer command prompt* in the desktop search box. Then choose the result you want.

> [!NOTE]
> By default, the current working directory in a developer command prompt is the root of your Visual Studio installation in the Program Files directory. This isn't an appropriate location for your code and projects. Change the current working directory to another location before you create a project. The IDE creates projects in your user directory, typically in *%USERPROFILE%\\source\\repos*.
> By default, the current working directory in a developer command prompt is the root of your Visual Studio installation in the Program Files directory. This isn't an appropriate location for your code and projects. Change the current working directory to another location before you create a project. The IDE creates projects in your user directory, typically in *`%USERPROFILE%\source\repos`*.

## <a name="developer_command_file_locations"></a> Developer command file locations

If you prefer to set the build environment in an existing command prompt window, you can use one of the command files created by the installer. We recommend you set the environment in a new command prompt window. We don't recommend you later switch environments in the same command window.

::: moniker range=">= msvc-170"

The command file location depends on the version of Visual Studio you installed, and on choices you made during installation. For Visual Studio 2019, the typical installation location on a 64-bit system is in *`\Program Files\Microsoft Visual Studio\2022\<edition>`*. The *`<edition>`* may be Community, Professional, Enterprise, BuildTools, or another nickname you supplied.
The command file location depends on the version of Visual Studio you installed, and on choices you made during installation. For Visual Studio 2022, the typical installation location on a 64-bit system is in *`\Program Files\Microsoft Visual Studio\2022\<edition>`*. The *`<edition>`* may be Community, Professional, Enterprise, BuildTools, or another nickname you supplied.

::: moniker-end
::: moniker range="= msvc-160"
Expand All @@ -112,12 +111,12 @@ The primary developer command prompt command file, *`VsDevCmd.bat`*, is located

::: moniker range=">= msvc-150"

More command files are available to set up specific build architectures. The command files available depend on the Visual Studio workloads and options you've installed. In Visual Studio 2017 and Visual Studio 2019, you'll find them in the VC\\Auxiliary\\Build subdirectory.
More command files are available to set up specific build architectures. The command files available depend on the Visual Studio workloads and options you've installed. In Visual Studio 2017 and Visual Studio 2019, you'll find them in the *`VC\Auxiliary\Build`* subdirectory.

::: moniker-end
::: moniker range="< msvc-150"

More command files are available to set up specific build architectures. The command files available depend on the Visual Studio workloads and options you've installed. In Visual Studio 2015, they're located in the VC, VC\\bin, or VC\\bin\\*architecture* subdirectories, where *architecture* is one of the native or cross-compiler options.
More command files are available to set up specific build architectures. The command files available depend on the Visual Studio workloads and options you've installed. In Visual Studio 2015, they're located in the *`VC`*, *`VC\bin`*, or *`VC\bin\<architecture>`* subdirectories, where *`<architecture>`* is one of the native or cross-compiler options.

::: moniker-end

Expand Down Expand Up @@ -150,8 +149,8 @@ When used with no arguments, *`vcvarsall.bat`* configures the environment variab

> **`vcvarsall.bat`** [*`architecture`*] [*`platform_type`*] [*`winsdk_version`*] [**`-vcvars_ver=`***`vcversion`*] [*`spectre_mode`*]

*`architecture`*<br/>
This optional argument specifies the host and target architecture to use. If *architecture* isn't specified, the default build environment is used. These arguments are supported:
*`architecture`*\
This optional argument specifies the host and target architecture to use. If *`architecture`* isn't specified, the default build environment is used. These arguments are supported:

| *`architecture`* | Compiler | Host computer architecture | Build output (target) architecture |
|--|--|--|--|
Expand All @@ -164,13 +163,13 @@ This optional argument specifies the host and target architecture to use. If *ar
| `amd64_arm` or `x64_arm` | ARM on x64 cross | x64 | ARM |
| `amd64_arm64` or `x64_arm64` | ARM64 on x64 cross | x64 | ARM64 |

*`platform_type`*<br/>
*`platform_type`*\
This optional argument allows you to specify **`store`** or **`uwp`** as the platform type. By default, the environment is set to build desktop or console apps.

*`winsdk_version`*<br/>
*`winsdk_version`*\
Optionally specifies the version of the Windows SDK to use. By default, the latest installed Windows SDK is used. To specify the Windows SDK version, you can use a full Windows SDK number such as **`10.0.10240.0`**, or specify **`8.1`** to use the Windows 8.1 SDK.

*`vcversion`*<br/>
*`vcversion`*\
Optionally specifies the Visual Studio compiler toolset to use. By default, the environment is set to use the current Visual Studio compiler toolset.

::: moniker range=">= msvc-160"
Expand All @@ -195,65 +194,79 @@ Leave this parameter out to use libraries without Spectre mitigations. Use the v

#### <a name="vcvarsall"></a> To set up the build environment in an existing command prompt window

1. At the command prompt, use the CD command to change to the Visual Studio installation directory. Then, use CD again to change to the subdirectory that contains the configuration-specific command files. For Visual Studio 2019 and Visual Studio 2017, use the *VC\\Auxiliary\\Build* subdirectory. For Visual Studio 2015, use the *VC* subdirectory.
1. At the command prompt, use the `CD` command to change to the Visual Studio installation directory. Then, use `CD` again to change to the subdirectory that contains the configuration-specific command files. For Visual Studio 2019 and Visual Studio 2017, use the *`VC\Auxiliary\Build`* subdirectory. For Visual Studio 2015, use the *`VC`* subdirectory.

1. Enter the command for your preferred developer environment. For example, to build ARM code for UWP on a 64-bit platform, using the latest Windows SDK and Visual Studio compiler toolset, use this command line:

`vcvarsall.bat amd64_arm uwp`
```cmd
vcvarsall.bat amd64_arm uwp
```

## Create your own command prompt shortcut

::: moniker range=">= msvc-160"

Open the Properties dialog for a developer command prompt shortcut to see the command target used. For example, the target for the **x64 Native Tools Command Prompt for VS 2019** shortcut is something similar to:

`%comspec% /k "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat"`
```
%comspec% /k "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat"
```

::: moniker-end
::: moniker range="= msvc-150"

Open the Properties dialog for a developer command prompt shortcut to see the command target used. For example, the target for the **x64 Native Tools Command Prompt for VS 2017** shortcut is something similar to:

`%comspec% /k "C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvars64.bat"`
```
%comspec% /k "C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvars64.bat"
```

::: moniker-end
::: moniker range="< msvc-150"

Open the Properties dialog for a developer command prompt shortcut to see the command target used. For example, the target for the **VS2015 x64 Native Tools Command Prompt** shortcut is something similar to:

`%comspec% /k "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" amd64`
```
%comspec% /k "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" amd64
```

::: moniker-end

The architecture-specific batch files set the *`architecture`* parameter and call *`vcvarsall.bat`*. You can pass the same options to these batch files as you would pass to *`vcvarsall.bat`*, or you can just call *`vcvarsall.bat`* directly. To specify parameters for your own command shortcut, add them to the end of the command in double-quotes. For example, here's a shortcut to build ARM code for UWP on a 64-bit platform, using the latest Windows SDK. To use an earlier compiler toolset, specify the version number. Use something like this command target in your shortcut:

::: moniker range=">= msvc-160"

`%comspec% /k "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" amd64_arm uwp -vcvars_ver=14.29`
```
%comspec% /k "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" amd64_arm uwp -vcvars_ver=14.29
```

::: moniker-end
::: moniker range="= msvc-150"

`%comspec% /k "C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvarsall.bat" amd64_arm uwp -vcvars_ver=14.19`
```
%comspec% /k "C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvarsall.bat" amd64_arm uwp -vcvars_ver=14.19
```

::: moniker-end
::: moniker range="< msvc-150"

`%comspec% /k "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" amd64 -vcvars_ver=14.0`
```
%comspec% /k "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" amd64 -vcvars_ver=14.0
```

::: moniker-end

Adjust the path to reflect your Visual Studio installation directory. The vcvarsall.bat file has additional information about specific version numbers.
Adjust the path to reflect your Visual Studio installation directory. The *`vcvarsall.bat`* file has additional information about specific version numbers.

## Command-line tools

To build a C/C++ project at a command prompt, Visual Studio provides these command-line tools:

[`CL`](reference/compiling-a-c-cpp-program.md)<br/>
Use the compiler (cl.exe) to compile and link source code files into apps, libraries, and DLLs.
[`CL`](reference/compiling-a-c-cpp-program.md)\
Use the compiler (`cl.exe`) to compile and link source code files into apps, libraries, and DLLs.

[`Link`](reference/linking.md)<br/>
Use the linker (link.exe) to link compiled object files and libraries into apps and DLLs.
[`Link`](reference/linking.md)\
Use the linker (`link.exe`) to link compiled object files and libraries into apps and DLLs.

When you build on the command line, the F1 command isn't available for instant help. Instead, you can use a search engine to get information about warnings, errors, and messages. You can also download and use the offline help files. To use the search in Microsoft Learn, enter your query in the search box at the top of any article.

Expand All @@ -262,16 +275,16 @@ When you build on the command line, the F1 command isn't available for instant h
By default, the Visual Studio IDE uses native project build systems based on MSBuild. You can invoke MSBuild directly to build projects without using the IDE. You can also use the `devenv` command to use Visual Studio to build projects and solutions. Visual Studio also supports build systems based on CMake or NMake.

[`MSBuild`](msbuild-visual-cpp.md)\
Use MSBuild (msbuild.exe) and a project file (.vcxproj) to configure a build and invoke the toolset without loading the Visual Studio IDE. It's equivalent to running the **Build** project or **Build Solution** command in the Visual Studio IDE. MSBuild has advantages over the IDE when you build at the command line. You don't have to install the full IDE on all your build servers and build pipelines. You avoid the extra overhead of the IDE. MSBuild runs in containerized build environments, and supports a [binary logger](https://msbuildlog.com/).
Use MSBuild (`msbuild.exe`) and a project file (`.vcxproj`) to configure a build and invoke the toolset without loading the Visual Studio IDE. It's equivalent to running the **Build** project or **Build Solution** command in the Visual Studio IDE. MSBuild has advantages over the IDE when you build at the command line. You don't have to install the full IDE on all your build servers and build pipelines. You avoid the extra overhead of the IDE. MSBuild runs in containerized build environments, and supports a [binary logger](https://msbuildlog.com/).

[`DEVENV`](/visualstudio/ide/reference/devenv-command-line-switches)\
Use DEVENV (devenv.exe) combined with a command-line switch such as **`/Build`** or **`/Clean`** to execute certain build commands without displaying the Visual Studio IDE.
Use DEVENV (`devenv.exe`) combined with a command-line switch such as **`/Build`** or **`/Clean`** to execute certain build commands without displaying the Visual Studio IDE.

[`CMake`](../build/cmake-projects-in-visual-studio.md)\
CMake (cmake.exe) is a cross-platform, open-source tool for defining build processes that run on multiple platforms. CMake can configure and control native build tools for its supported platforms, such as MSBuild and Make. For more information about CMake, see the [CMake documentation](https://cmake.org/cmake/help/latest/index.html#).
CMake (`cmake.exe`) is a cross-platform, open-source tool for defining build processes that run on multiple platforms. CMake can configure and control native build tools for its supported platforms, such as MSBuild and Make. For more information about CMake, see the [CMake documentation](https://cmake.org/cmake/help/latest/index.html#).

[`NMAKE`](reference/nmake-reference.md)\
Use NMAKE (nmake.exe) to build C++ projects by using a traditional makefile.
Use NMAKE (`nmake.exe`) to build C++ projects by using a traditional makefile.

> [!NOTE]
> Starting in Visual Studio 2019 version 16.5, MSBuild and DEVENV don't use the command-line environment to control the toolset and libraries used.
Expand All @@ -280,36 +293,36 @@ Use NMAKE (nmake.exe) to build C++ projects by using a traditional makefile.

These articles show how to build apps on the command line, and describe how to customize the command-line build environment. Some show how to use 64-bit toolsets, and target x86, x64, ARM, and ARM64 platforms. They also describe use of the command-line build tools MSBuild and NMAKE.

[Walkthrough: Compiling a native C++ program on the command line](walkthrough-compiling-a-native-cpp-program-on-the-command-line.md)<br/>
[Walkthrough: Compiling a native C++ program on the command line](walkthrough-compiling-a-native-cpp-program-on-the-command-line.md)\
Gives an example that shows how to create and compile a C++ program on the command line.

[Walkthrough: Compile a C program on the command line](walkthrough-compile-a-c-program-on-the-command-line.md)<br/>
[Walkthrough: Compile a C program on the command line](walkthrough-compile-a-c-program-on-the-command-line.md)\
Describes how to compile a program written in the C programming language.

[Walkthrough: Compiling a C++/CLI program on the command line](walkthrough-compiling-a-cpp-cli-program-on-the-command-line.md)<br/>
[Walkthrough: Compiling a C++/CLI program on the command line](walkthrough-compiling-a-cpp-cli-program-on-the-command-line.md)\
Describes how to create and compile a C++/CLI program that uses the .NET Framework.

[Walkthrough: Compiling a C++/CX program on the command line](walkthrough-compiling-a-cpp-cx-program-on-the-command-line.md)<br/>
[Walkthrough: Compiling a C++/CX program on the command line](walkthrough-compiling-a-cpp-cx-program-on-the-command-line.md)\
Describes how to create and compile a C++/CX program that uses the Windows Runtime.

[NMAKE reference](reference/nmake-reference.md)<br/>
Provides links to articles that describe the Microsoft Program Maintenance Utility (NMAKE.EXE).
[NMAKE reference](reference/nmake-reference.md)\
Provides links to articles that describe the Microsoft Program Maintenance Utility (`NMAKE.EXE`).

[MSBuild on the command line - C++](msbuild-visual-cpp.md)<br/>
Provides links to articles that discuss how to use msbuild.exe from the command line.
[MSBuild on the command line - C++](msbuild-visual-cpp.md)\
Provides links to articles that discuss how to use `msbuild.exe` from the command line.

## Related sections

[/MD, /MT, /LD (Use run-time library)](reference/md-mt-ld-use-run-time-library.md)<br/>
[`/MD`, `/MT`, `/LD` (Use run-time library)](reference/md-mt-ld-use-run-time-library.md)\
Describes how to use these compiler options to use a Debug or Release run-time library.

[C/C++ compiler options](reference/compiler-options.md)<br/>
Provides links to articles that discuss the C and C++ compiler options and CL.exe.
[C/C++ compiler options](reference/compiler-options.md)\
Provides links to articles that discuss the C and C++ compiler options and `CL.exe`.

[MSVC linker options](reference/linker-options.md)<br/>
Provides links to articles that discuss the linker options and LINK.exe.
[MSVC linker options](reference/linker-options.md)\
Provides links to articles that discuss the linker options and `LINK.exe`.

[Additional MSVC build tools](reference/c-cpp-build-tools.md)<br/>
[Additional MSVC build tools](reference/c-cpp-build-tools.md)\
Provides links to the C/C++ build tools that are included in Visual Studio.

## See also
Expand Down