Skip to content

Repo sync for protected CLA branch #4241

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

Merged
merged 13 commits into from
Oct 25, 2022
Merged
Show file tree
Hide file tree
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
Binary file modified docs/build/media/cmake-general-prefer-cmake-presets.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
32 changes: 18 additions & 14 deletions docs/build/walkthrough-build-debug-wsl2.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
description: "Learn to use Windows Subsystem for Linux version 2 (WSL2) to build and debug C++ in Visual Studio 2022"
title: "Walkthrough: Build and Debug C++ with Microsoft Windows Subsystem for Linux 2 (WSL 2) and Visual Studio 2022"
ms.date: 10/29/2021
ms.date: 10/21/2022
author: "tylermsft"
ms.author: "twhitney"
helpviewer_keywords: ["wsl2", "cmake", "linux", "build"]
Expand Down Expand Up @@ -51,52 +51,52 @@ Visual Studio defines a CMake project as a folder with a `CMakeLists.txt` file a

3. From the Visual Studio **Get started** screen, select **Create a new project**.

![Screenshot of the Visual Studio 2022 get started dialog box that shows options to clone a repository, open a project or solution, open a local folder, create a new project, or continue without code](media/vs2022-get-started.png)
![Screenshot of the Visual Studio 2022 get started dialog box that shows options to clone a repository, open a project or solution, open a local folder, create a new project, or continue without code.](media/vs2022-get-started.png)

4. In the **Search for templates** textbox, type "cmake". Choose the **CMake Project** type and select **Next**. Give the project a name and location, and then select **Create**.

5. Enable Visual Studio's CMake Presets integration. Select **Tools** > **Options** > **CMake** > **General**. Select **Prefer using CMake Presets for configure, build, and test**, then select **OK**. Instead, you could have added a `CMakePresets.json` file to the root of the project. For more information, see [Enable CMake Presets integration](cmake-presets-vs.md#enable-cmakepresets-json-integration).

![Screenshot of CMake general options screen with Prefer using CMake Presets for configure, build, and test highlighted and selected](media/cmake-general-prefer-cmake-presets.png)
![Screenshot of CMake general options screen with Use CMake Presets if available, otherwise use CMakeSettings.json highlighted and selected.](media/cmake-general-prefer-cmake-presets.png)

6. To activate the integration: from the main menu, select **File** > **Close Folder**. The **Get started** page appears. Under **Open recent**, select the folder you just closed to reopen the folder.

7. There are three dropdowns across the Visual Studio main menu bar. Use the dropdown on the left to select your active target system. This is the system where CMake will be invoked to configure and build the project. Visual Studio queries for WSL installations with `wsl -l -v`. In the following image, **WSL2: Ubuntu-20.04** is shown selected as the **Target System**.

![Target system dropdown displaying WSL2: Ubuntu-20.04 as being selected](media/vs2022-target-system-dropdown.png)
![Target system dropdown shows WSL2: Ubuntu-20.04 as being selected.](media/vs2022-target-system-dropdown.png)

> [!NOTE]
> If Visual Studio starts to configure your project automatically, read step 11 to manage CMake binary deployment, and then continue to the step below. To customize this behavior, see [Modify automatic configuration and cache notifications](cmake-presets-vs.md#modify-automatic-configuration-and-cache-notifications).

8. Use the dropdown in the middle to select your active Configure Preset. Configure Presets tell Visual Studio how to invoke CMake and generate the underlying build system. In step 7, the active Configure Preset is the **linux-default** Preset created by Visual Studio. To create a custom Configure Preset, select **Manage Configurations…** For more information about Configure Presets, see [Select a Configure Preset](cmake-presets-vs.md#select-a-configure-preset) and [Edit Presets](cmake-presets-vs.md#edit-presets).

![Active configure preset dropdown, showing Manage Configurations... selected](media/vs2022-ActivePresetDropdown.png)
![Active configure preset dropdown, showing Manage Configurations... selected.](media/vs2022-ActivePresetDropdown.png)

9. Use the dropdown on the right to select your active Build Preset. Build Presets tell Visual Studio how to invoke build. In the illustration for step 7, the active Build Preset is the **Default** Build Preset created by Visual Studio. For more information about Build Presets, see [Select a Build Preset](cmake-presets-vs.md#select-a-build-preset).

10. Configure the project on WSL 2. If project generation doesn't start automatically, then manually invoke configure with **Project** > **Configure** *project-name*

![Project configure drop-down showing Configure CMakeProject selected](media/vs2022-project-configure.png)
![Project configure drop-down showing Configure CMakeProject selected.](media/vs2022-project-configure.png)

11. If you don't have a supported version of CMake installed on your WSL 2 distro, then Visual Studio will prompt you beneath the main menu ribbon to deploy a recent version of CMake. Select **Yes** to deploy CMake binaries to your WSL 2 distro.

![Visual Studio prompt beneath the toolbar that says: supported cmake version is not present. Install latest CMake binaries from Cmake.org? Yes no](media/vs2022-supported-cmake-not-present-prompt.png)
![Visual Studio prompt beneath the toolbar that says: supported cmake version is not present. Install latest CMake binaries from Cmake.org? Yes no.](media/vs2022-supported-cmake-not-present-prompt.png)

12. Confirm that the configure step has completed and that you can see the **CMake generation finished** message in the **Output** window under the **CMake** pane. Build files are written to a directory in the WSL 2 distro's file system.

![Output window showing message that CMake generation is done](media/vs-output-window-cmake-generation.png)
![Output window showing message that CMake generation is done.](media/vs-output-window-cmake-generation.png)

13. Select the active debug target. The debug dropdown menu lists all the CMake targets available to the project.

![Debug dropdown menu showing CMakeProject selected](media/vs-debug-dropdown-menu-cmake.png)
![Debug dropdown menu showing CMakeProject selected.](media/vs-debug-dropdown-menu-cmake.png)

14. Expand the project subfolder in the **Solution Explorer**. In the `CMakeProject.cpp` file, set a breakpoint in `main()`. You can also navigate to CMake targets view by selecting the View Picker button in the **Solution Explorer**, highlighted in following screenshot:

![Solution explorer showing the button to switch views. The button is just to the right of the home (house) button](media/solution-explorer-switch-view.png)
![Solution explorer showing the button to switch views. The button is just to the right of the home (house) button.](media/solution-explorer-switch-view.png)

15. Select **Debug** > **Start**, or press **F5**. Your project will build, the executable will launch on your WSL 2 distro, and Visual Studio will stop execution at the breakpoint. You can see the output of your program (in this case, `"Hello CMake."`) in the Linux Console Window:

![Linux console window, displaying the text "Hello Cmake." Also shows the sample program with a breakpoint on the line following cout << "Hello CMake."](media/walkthrough-build-debug-wsl2-breakpoint.png)
![Linux console window, displaying the text "Hello Cmake." Also shows the sample program with a breakpoint on the line following cout << "Hello CMake".](media/walkthrough-build-debug-wsl2-breakpoint.png)

You've now built and debugged a C++ app with WSL 2 and Visual Studio 2022.

Expand All @@ -118,11 +118,15 @@ You can change the IntelliSense mode, or specify other IntelliSense options, in

## WSL 2 and MSBuild-based Linux projects

CMake is recommended for all C++ cross-platform development with Visual Studio because it allows you to build and debug the same project on Windows, WSL, and remote systems. If you're already using a MSBuild-based Linux project, then you can upgrade to the WSL 2 toolset in Visual Studio via **Property pages** > **General** > **Platform Toolset**:
CMake is recommended for all C++ cross-platform development with Visual Studio because it allows you to build and debug the same project on Windows, WSL, and remote systems.

![A screenshot of a dropdown with Platform Toolset selected, and to the right, another dropdown with WSL2 Toolset selected](media/wsl-platform-toolset-selection.png)
But you may have a MSBuild-based Linux project.

If you're targeting a WSL 2 distribution and you don't want to use the WSL 2 toolset, then in **Property Pages** > **General** > **Platform Toolset**, select the **GCC for Windows Subsystem for Linux** or **Clang for Windows Subsystem for Linux** toolset. If either of these toolsets are selected, Visual Studio won't maintain a copy of your source files in the WSL file system and will instead access source files over the mounted Windows drive (`/mnt/`…). System headers are still automatically copied to the Windows file system to provide a native IntelliSense experience. Customize the headers that are included or excluded from this copy in **Property Pages** > **General**.
If you have a MSBuild-based Linux project, then you can upgrade to the WSL 2 toolset in Visual Studio. Right-click the project in the solution explorer, then choose **Properties** > **General** > **Platform Toolset**:

![A screenshot of a dropdown with Platform Toolset selected, and to the right, another dropdown with WSL2 Toolset selected.](media/wsl-platform-toolset-selection.png)

If you're targeting a WSL 2 distribution and you don't want to use the WSL 2 toolset, then in the **Platform Toolset** dropdown, select the **GCC for Windows Subsystem for Linux** or **Clang for Windows Subsystem for Linux** toolset. If either of these toolsets are selected, Visual Studio won't maintain a copy of your source files in the WSL file system and will instead access source files over the mounted Windows drive (`/mnt/`…). System headers are still automatically copied to the Windows file system to provide a native IntelliSense experience. Customize the headers that are included or excluded from this copy in **Property Pages** > **General**.

In most cases, it's best to use the WSL 2 toolset with WSL 2 distributions because WSL 2 is slower when project files are stored in the Windows file system. To to learn more, see [Comparing WSL 1 and WSL 2](/windows/wsl/compare-versions).

Expand Down
2 changes: 1 addition & 1 deletion docs/c-runtime-library/crtlcmapstringw.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ Zero indicates failure. To get extended error information, call the `GetLastErro

## Remarks

If `cchSrc` is greater than zero and `lpSrcStr` is a null-terminated string, `__crtLCMapStringW` sets `cchSrc` to the length of the string. Then `__crtLCMapStringW` calls the wide string (Unicode) version of the `LCMapString` function with the specified parameters. For more information about the parameters and return value of this function, see the [LCMapString](/windows/win32/api/winnls/nf-winnls-lcmapstringw).
If `cchSrc` is greater than zero and `lpSrcStr` is a null-terminated string, `__crtLCMapStringW` sets `cchSrc` to the length of the string. Then `__crtLCMapStringW` calls the wide string (Unicode) version of the `LCMapString` function with the specified parameters. For more information about the parameters and return value of this function, see the [`LCMapString`](/windows/win32/api/winnls/nf-winnls-lcmapstringw).

## Requirements

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ A basic conversion specification contains only the percent sign and a *type* cha

The *type* conversion specifier character specifies whether to interpret the corresponding argument as a character, a string, a pointer, an integer, or a floating-point number. The *type* character is the only required conversion specification field, and it appears after any optional fields.

The arguments that follow the format string are interpreted according to the corresponding *type* character and the optional [size](#size) prefix. Conversions for character types `char` and `wchar_t` are specified by using **`c`** or **`C`**, and single-byte and multi-byte or wide character strings are specified by using **`s`** or **`S`**, depending on which formatting function is being used. Character and string arguments that are specified by using **`c`** and **`s`** are interpreted as `char` and `char*` by `printf` family functions, or as `wchar_t` and `wchar_t*` by `wprintf` family functions. Character and string arguments that are specified by using **`C`** and **`S`** are interpreted as `wchar_t` and `wchar_t*` by `printf` family functions, or as `char` and `char*` by `wprintf` family functions. This behavior is Microsoft-specific.
The arguments that follow the format string are interpreted according to the corresponding *type* character and the optional [*size*](#size) prefix. Conversions for character types `char` and `wchar_t` are specified by using **`c`** or **`C`**, and single-byte and multi-byte or wide character strings are specified by using **`s`** or **`S`**, depending on which formatting function is being used. Character and string arguments that are specified by using **`c`** and **`s`** are interpreted as `char` and `char*` by `printf` family functions, or as `wchar_t` and `wchar_t*` by `wprintf` family functions. Character and string arguments that are specified by using **`C`** and **`S`** are interpreted as `wchar_t` and `wchar_t*` by `printf` family functions, or as `char` and `char*` by `wprintf` family functions. This behavior is Microsoft-specific.

Integer types such as `short`, `int`, `long`, `long long`, and their `unsigned` variants, are specified by using **`d`**, **`i`**, **`o`**, **`u`**, **`x`**, and **`X`**. Floating-point types such as `float`, `double`, and `long double`, are specified by using **`a`**, **`A`**, **`e`**, **`E`**, **`f`**, **`F`**, **`g`**, and **`G`**. By default, unless they're modified by a *size* prefix, integer arguments are coerced to `int` type, and floating-point arguments are coerced to `double`. On 64-bit systems, an `int` is a 32-bit value; so, 64-bit integers will be truncated when they're formatted for output unless a *size* prefix of **`ll`** or **`I64`** is used. Pointer types that are specified by **`p`** use the default pointer size for the platform.

Expand All @@ -56,7 +56,7 @@ Integer types such as `short`, `int`, `long`, `long long`, and their `unsigned`
|**`e`**|Floating-point|Signed value that has the form [`-`]*d.dddd*`e`\[`+`\|`-`]*dd*\[*d*], where *d* is one decimal digit, *dddd* is one or more decimal digits depending on the specified precision, or six by default, and *dd*\[*d*] is two or three decimal digits depending on the [output format](./set-output-format.md) and size of the exponent.|
|**`E`**|Floating-point|Identical to the **`e`** format except that **`E`** rather than **`e`** introduces the exponent.|
|**`f`**|Floating-point|Signed value that has the form [`-`]*dddd*`.`*dddd*, where *dddd* is one or more decimal digits. The number of digits before the decimal point depends on the magnitude of the number, and the number of digits after the decimal point depends on the requested precision, or six by default.|
|**`F`**|Floating-point|Identical to the **`f`** format except that infinity and nan output is capitalized.|
|**`F`**|Floating-point|Identical to the **`f`** format except that infinity and NaN output is capitalized.|
|**`g`**|Floating-point|Signed values are displayed in **`f`** or **`e`** format, whichever is more compact for the given value and precision. The **`e`** format is used only when the exponent of the value is less than -4 or greater than or equal to the *precision* argument. Trailing zeros are truncated, and the decimal point appears only if one or more digits follow it.|
|**`G`**|Floating-point|Identical to the **`g`** format, except that **`E`**, rather than **`e`**, introduces the exponent (where appropriate).|
|**`a`**|Floating-point|Signed hexadecimal double-precision floating-point value that has the form [`-`]`0x`*h.hhhh*`p`\[`+`\|`-`]*dd*, where *h.hhhh* are the hex digits (using lower case letters) of the mantissa, and *dd* are one or more digits for the exponent. The precision specifies the number of digits after the point.|
Expand Down
2 changes: 1 addition & 1 deletion docs/c-runtime-library/reference/acos-acosf-acosl.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ By default, if *`x`* is less than -1 or greater than 1, **`acos`** returns an in

Because C++ allows overloading, you can call overloads of **`acos`** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the `<tgmath.h>` macro to call this function, **`acos`** always takes and returns a **`double`**.

If you use the `<tgmath.h>` `acos()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details.
If you use the `acos` macro from `<tgmath.h>`, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details.

By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md).

Expand Down
2 changes: 1 addition & 1 deletion docs/c-runtime-library/reference/asin-asinf-asinl.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ By default, if *`x`* is less than -1 or greater than 1, **`asin`** returns an in

Because C++ allows overloading, you can call overloads of **`asin`** with **`float`** and **`long double`** values. In a C program, unless you're using the `<tgmath.h>` macro to call this function, **`asin`** always takes and returns a **`double`**.

If you use the `<tgmath.h>` `asin()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details.
If you use the `asin` macro from `<tgmath.h>`, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details.

By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md).

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ Any numbers.

The **`atan`** function calculates the arctangent (the inverse tangent function) of *`x`*. **`atan2`** calculates the arctangent of *`y`*/*`x`* (if *`x`* equals 0, **`atan2`** returns π/2 if *`y`* is positive, -π/2 if *`y`* is negative, or 0 if *`y`* is 0.)

If you use the `<tgmath.h>` `atan()` or `atan2()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details.
If you use the `atan` or `atan2` macro from `<tgmath.h>`, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details.

**`atan`** has an implementation that uses Streaming SIMD Extensions 2 (SSE2). For information and restrictions about using the SSE2 implementation, see [`_set_SSE2_enable`](set-sse2-enable.md).

Expand Down
2 changes: 1 addition & 1 deletion docs/c-runtime-library/reference/chdrive.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ Zero (0) if the current working drive was changed successfully; otherwise, -1.

If *`drive`* isn't in the range from 1 through 26, the invalid-parameter handler is invoked as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the **`_chdrive`** function returns -1, `errno` is set to `EACCES`, and `_doserrno` is set to `ERROR_INVALID_DRIVE`.

The **`_chdrive`** function isn't thread-safe because it depends on the `SetCurrentDirectory` function, which is itself not thread-safe. To use **`_chdrive`** safely in a multi-threaded application, you must provide your own thread synchronization. For more information, see [SetCurrentDirectory](/windows/win32/api/winbase/nf-winbase-setcurrentdirectory).
The **`_chdrive`** function isn't thread-safe because it depends on the `SetCurrentDirectory` function, which is itself not thread-safe. To use **`_chdrive`** safely in a multi-threaded application, you must provide your own thread synchronization. For more information, see [`SetCurrentDirectory`](/windows/win32/api/winbase/nf-winbase-setcurrentdirectory).

The **`_chdrive`** function changes only the current working drive; `_chdir` changes the current working directory.

Expand Down
Loading