From 2e5fd2849c85e71a50690dfb7517b5a79da5f66b Mon Sep 17 00:00:00 2001 From: Colin Robertson <3836425+corob-msft@users.noreply.github.com> Date: Fri, 11 Nov 2022 18:01:41 -0800 Subject: [PATCH 1/4] Doc new Zc conformance options --- .../compiler-options-listed-alphabetically.md | 3 + .../compiler-options-listed-by-category.md | 3 + docs/build/reference/zc-conformance.md | 3 + docs/build/reference/zc-gotoscope.md | 93 +++++++++++++++++++ docs/build/reference/zc-nrvo.md | 49 ++++++++++ docs/build/reference/zc-templatescope.md | 50 ++++++++++ docs/build/toc.yml | 6 ++ 7 files changed, 207 insertions(+) create mode 100644 docs/build/reference/zc-gotoscope.md create mode 100644 docs/build/reference/zc-nrvo.md create mode 100644 docs/build/reference/zc-templatescope.md diff --git a/docs/build/reference/compiler-options-listed-alphabetically.md b/docs/build/reference/compiler-options-listed-alphabetically.md index b27c7815489..dc18f459e65 100644 --- a/docs/build/reference/compiler-options-listed-alphabetically.md +++ b/docs/build/reference/compiler-options-listed-alphabetically.md @@ -220,16 +220,19 @@ This table contains an alphabetical list of compiler options. For a list of comp | [`/Zc:externC[-]`](zc-externc.md) | Enforce Standard C++ rules for `extern "C"` functions (implied by **`/permissive-`**). | | [`/Zc:externConstexpr[-]`](zc-externconstexpr.md) | Enable external linkage for **`constexpr`** variables (off by default). | | [`/Zc:forScope[-]`](zc-forscope-force-conformance-in-for-loop-scope.md) | Enforce Standard C++ **`for`** scoping rules (on by default). | +| [`/Zc:gotoScope`](zc-gotoscope.md) | Enforce Standard C++ **`goto`** rules around local variable initialization (implied by **`/permissive-`**). | | [`/Zc:hiddenFriend[-]`](zc-hiddenfriend.md) | Enforce Standard C++ hidden friend rules (implied by **`/permissive-`**) | | [`/Zc:implicitNoexcept[-]`](zc-implicitnoexcept-implicit-exception-specifiers.md) | Enable implicit **`noexcept`** on required functions (on by default). | | [`/Zc:inline[-]`](zc-inline-remove-unreferenced-comdat.md) | Remove unreferenced functions or data if they're COMDAT or have internal linkage only (off by default). | | [`/Zc:lambda[-]`](zc-lambda.md) | Enable new lambda processor for conformance-mode syntactic checks in generic lambdas. | | [`/Zc:noexceptTypes[-]`](zc-noexcepttypes.md) | Enforce C++17 **`noexcept`** rules (on by default in C++17 or later). | +| [`/Zc:nrvo[-]`](zc-nrvo.md) | Enable optional copy and move elisions (on by default under **`/O2`**, **`/permissive-`**, or **`/std:c++20`** or later). | | [`/Zc:preprocessor[-]`](zc-preprocessor.md) | Use the new conforming preprocessor (off by default, except in C11/C17). | | [`/Zc:referenceBinding[-]`](zc-referencebinding-enforce-reference-binding-rules.md) | A UDT temporary won't bind to a non-const lvalue reference (off by default). | | [`/Zc:rvalueCast[-]`](zc-rvaluecast-enforce-type-conversion-rules.md) | Enforce Standard C++ explicit type conversion rules (off by default). | | [`/Zc:sizedDealloc[-]`](zc-sizeddealloc-enable-global-sized-dealloc-functions.md) | Enable C++14 global sized deallocation functions (on by default). | | [`/Zc:strictStrings[-]`](zc-strictstrings-disable-string-literal-type-conversion.md) | Disable string-literal to `char*` or `wchar_t*` conversion (off by default). | +| [`/Zc:templateScope[-]`](zc-templatescope.md) | Enforce Standard C++ template parameter shadowing rules (off by default). | | [`/Zc:ternary[-]`](zc-ternary.md) | Enforce conditional operator rules on operand types (off by default). | | [`/Zc:threadSafeInit[-]`](zc-threadsafeinit-thread-safe-local-static-initialization.md) | Enable thread-safe local static initialization (on by default). | | [`/Zc:throwingNew[-]`](zc-throwingnew-assume-operator-new-throws.md) | Assume **`operator new`** throws on failure (off by default). | diff --git a/docs/build/reference/compiler-options-listed-by-category.md b/docs/build/reference/compiler-options-listed-by-category.md index f2087515e7d..8564888316b 100644 --- a/docs/build/reference/compiler-options-listed-by-category.md +++ b/docs/build/reference/compiler-options-listed-by-category.md @@ -182,16 +182,19 @@ This article contains a categorical list of compiler options. For an alphabetica | [`/Zc:externC[-]`](zc-externc.md) | Enforce Standard C++ rules for `extern "C"` functions (implied by **`/permissive-`**). | | [`/Zc:externConstexpr[-]`](zc-externconstexpr.md) | Enable external linkage for **`constexpr`** variables (off by default). | | [`/Zc:forScope[-]`](zc-forscope-force-conformance-in-for-loop-scope.md) | Enforce Standard C++ **`for`** scoping rules (on by default). | +| [`/Zc:gotoScope`](zc-gotoscope.md) | Enforce Standard C++ **`goto`** rules around local variable initialization (implied by **`/permissive-`**). | | [`/Zc:hiddenFriend[-]`](zc-hiddenfriend.md) | Enforce Standard C++ hidden friend rules (implied by **`/permissive-`**) | | [`/Zc:implicitNoexcept[-]`](zc-implicitnoexcept-implicit-exception-specifiers.md) | Enable implicit **`noexcept`** on required functions (on by default). | | [`/Zc:inline[-]`](zc-inline-remove-unreferenced-comdat.md) | Remove unreferenced functions or data if they're COMDAT or have internal linkage only (off by default). | | [`/Zc:lambda[-]`](zc-lambda.md) | Enable new lambda processor for conformance-mode syntactic checks in generic lambdas. | | [`/Zc:noexceptTypes[-]`](zc-noexcepttypes.md) | Enforce C++17 **`noexcept`** rules (on by default in C++17 or later). | +| [`/Zc:nrvo[-]`](zc-nrvo.md) | Enable optional copy and move elisions (on by default under **`/O2`**, **`/permissive-`**, or **`/std:c++20`** or later). | | [`/Zc:preprocessor[-]`](zc-preprocessor.md) | Use the new conforming preprocessor (off by default, except in C11/C17). | | [`/Zc:referenceBinding[-]`](zc-referencebinding-enforce-reference-binding-rules.md) | A UDT temporary won't bind to a non-const lvalue reference (off by default). | | [`/Zc:rvalueCast[-]`](zc-rvaluecast-enforce-type-conversion-rules.md) | Enforce Standard C++ explicit type conversion rules (off by default). | | [`/Zc:sizedDealloc[-]`](zc-sizeddealloc-enable-global-sized-dealloc-functions.md) | Enable C++14 global sized deallocation functions (on by default). | | [`/Zc:strictStrings[-]`](zc-strictstrings-disable-string-literal-type-conversion.md) | Disable string-literal to `char*` or `wchar_t*` conversion (off by default). | +| [`/Zc:templateScope[-]`](zc-templatescope.md) | Enforce Standard C++ template parameter shadowing rules (off by default). | | [`/Zc:ternary[-]`](zc-ternary.md) | Enforce conditional operator rules on operand types (off by default). | | [`/Zc:threadSafeInit[-]`](zc-threadsafeinit-thread-safe-local-static-initialization.md) | Enable thread-safe local static initialization (on by default). | | [`/Zc:throwingNew[-]`](zc-throwingnew-assume-operator-new-throws.md) | Assume **`operator new`** throws on failure (off by default). | diff --git a/docs/build/reference/zc-conformance.md b/docs/build/reference/zc-conformance.md index 7427b8962e1..6774cae102b 100644 --- a/docs/build/reference/zc-conformance.md +++ b/docs/build/reference/zc-conformance.md @@ -31,17 +31,20 @@ Here are the **`/Zc`** compiler options: | [`/Zc:externC`](zc-externc.md) | Enforce Standard C++ rules for `extern "C"` functions (implied by **`/permissive-`**). | | [`/Zc:externConstexpr`](zc-externconstexpr.md) | Enable external linkage for **`constexpr`** variables (off by default). | | [`/Zc:forScope`](zc-forscope-force-conformance-in-for-loop-scope.md) | Enforce Standard C++ **`for`** scoping rules (on by default). | +| [`/Zc:gotoScope`](zc-gotoscope.md) | Enforce Standard C++ **`goto`** rules around local variable initialization (implied by **`/permissive-`**). | | [`/Zc:hiddenFriend`](zc-hiddenfriend.md) | Enforce Standard C++ hidden friend rules (implied by **`/permissive-`**) | | [`/Zc:implicitNoexcept`](zc-implicitnoexcept-implicit-exception-specifiers.md) | Enable implicit **`noexcept`** on required functions (on by default). | | [`/Zc:inline`](zc-inline-remove-unreferenced-comdat.md) | Remove unreferenced functions or data if they're COMDAT or have internal linkage only (off by default). | | [`/Zc:lambda`](zc-lambda.md) | Enable new lambda processor for conformance-mode syntactic checks in generic lambdas. | | [`/Zc:noexceptTypes`](zc-noexcepttypes.md) | Enforce C++17 **`noexcept`** rules (on by default in C++17 or later). | +| [`/Zc:nrvo[-]`](zc-nrvo.md) | Enable optional copy and move elisions (on by default under **`/O2`**, **`/permissive-`**, or **`/std:c++20`** or later). | | [`/Zc:preprocessor`](zc-preprocessor.md) | Use the new conforming preprocessor (off by default, except in C11/C17). | | [`/Zc:referenceBinding`](zc-referencebinding-enforce-reference-binding-rules.md) | A UDT temporary won't bind to a non-const lvalue reference (off by default). | | [`/Zc:rvalueCast`](zc-rvaluecast-enforce-type-conversion-rules.md) | Enforce Standard C++ explicit type conversion rules (off by default). | | [`/Zc:sizedDealloc`](zc-sizeddealloc-enable-global-sized-dealloc-functions.md) | Enable C++14 global sized deallocation functions (on by default). | | [`/Zc:strictStrings`](zc-strictstrings-disable-string-literal-type-conversion.md) | Disable string-literal to `char*` or `wchar_t*` conversion (off by default). | | [`/Zc:static_assert`](zc-static-assert.md) | strict handling of `static_assert` (implied by **`/permissive-`**). | +| [`/Zc:templateScope[-]`](zc-templatescope.md) | Enforce Standard C++ template parameter shadowing rules (off by default). | | [`/Zc:ternary`](zc-ternary.md) | Enforce conditional operator rules on operand types (off by default). | | [`/Zc:threadSafeInit`](zc-threadsafeinit-thread-safe-local-static-initialization.md) | Enable thread-safe local static initialization (on by default). | | [`/Zc:throwingNew`](zc-throwingnew-assume-operator-new-throws.md) | Assume **`operator new`** throws on failure (off by default). | diff --git a/docs/build/reference/zc-gotoscope.md b/docs/build/reference/zc-gotoscope.md new file mode 100644 index 00000000000..5851e4ba968 --- /dev/null +++ b/docs/build/reference/zc-gotoscope.md @@ -0,0 +1,93 @@ +--- +description: "Learn more about the /Zc:gotoScope (Enforce conformance in goto scope) compiler option." +title: "/Zc:gotoScope (Enforce conformance in goto scope)" +ms.date: 11/11/2022 +f1_keywords: ["/Zc:gotoScope"] +helpviewer_keywords: ["-Zc:gotoScope compiler option (C++)", "/Zc:gotoScope compiler option (C++)"] +--- +# `/Zc:gotoScope` (Enforce conformance in goto scope) + +The **`/Zc:gotoScope`** compiler option enables checks for Standard C++ behavior around **`goto`** statements that jump over the initialization of local variables. + +## Syntax + +> **`/Zc:gotoScope`**\[**`-`**] + +## Remarks + +The **`/Zc:gotoScope`** compiler option enforces C++ Standard behavior around **`goto`** statements that jump over the initialization of one or more local variables. The compiler emits error [C2362](../../error-messages/compiler-errors-1/compiler-error-c2362.md) in all such cases when **`/Zc:gotoScope`** is specified. The **`/Zc:gotoScope-`** relaxes this check, but the compiler still emits an error if a **`goto`** skips initialization of a local variable that has a non-trivial destructor. + +The intent of the **`/Zc:gotoScope-`** option is to help ease the migration of older code bases to more conformant code. You may use it to suppress certain errors until you've updated the non-conforming code. + +The **`/Zc:gotoScope`** compiler option is new in Visual Studio 2022 version 17.4. The option is off by default. It's enabled automatically by the **`/permissive-`** option (or an option that implies **`/permissive-`**, such as **`/std:c++20`** or **`/std:c++latest`**). To enable the error check explicitly, add **`/Zc:gotoScope`** to the compiler command line. To explicitly disable the check, use the **`/Zc:gotoScope-`** option. The **`/Zc:gotoScope-`** must appear after the **`/permissive-`** option or any option that implies **`/permissive-`**. + +### Example + +This sample generates an error message when compiled using **`/Zc:gotoScope`**: + +```cpp +int g(int*); +bool failed(int); + +int f() { + int v1; + auto result = g(&v1); + if (failed(result)) + goto OnError; + int v2 = v1 + 2; + return v2; +OnError: + return -1; +} + +/* Output: +t.cpp(9): error C2362: initialization of 'v2' is skipped by 'goto OnError' +*/ +``` + +If the code is compiled with **`/Zc:gotoScope-`**, the compiler doesn't emit the error. + +Even when **`/Zc:gotoScope-`** is specified, the compiler still emits an error if the local variable has a non-trivial destructor. For example: + +```cpp +int g(int*); +bool failed(int); + +class S { +public: + S(int); + ~S(); + int mf() const; +}; + +int f() +{ + int v1; + auto result = g(&v1); + if (failed(result)) + goto OnError; + S s(v1); + return s.mf(); + +OnError: + return -1; +} + +/* Output: +t.cpp(17): error C2362: initialization of 's' is skipped by 'goto OnError' +*/ +``` + +### To set this compiler option in Visual Studio + +1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. + +1. In **Additional options**, add *`/Zc:gotoScope`* or *`/Zc:gotoScope-`*. Choose **OK** or **Apply** to save your changes. + +## See also + +[`/Zc` (Conformance)](zc-conformance.md)\ +[`/permissive-](./permissive-standards-conformance.md)\ +[`/std` (Specify language standard version)](std-specify-language-standard-version.md) diff --git a/docs/build/reference/zc-nrvo.md b/docs/build/reference/zc-nrvo.md new file mode 100644 index 00000000000..becd73c75e9 --- /dev/null +++ b/docs/build/reference/zc-nrvo.md @@ -0,0 +1,49 @@ +--- +description: "Learn more about the /Zc:nrvo (Control optional NRVO) compiler option." +title: "/Zc:nrvo (Control optional NRVO)" +ms.date: 11/10/2022 +f1_keywords: ["/Zc:nrvo"] +helpviewer_keywords: ["-Zc:nrvo compiler option (C++)", "/Zc:nrvo compiler option (C++)"] +--- +# `/Zc:nrvo` (Control optional NRVO) + +The **`/Zc:nrvo`** compiler option controls Standard C++ optional named return value optimization (NRVO) copy or move elision behavior. + +## Syntax + +> **`/Zc:nrvo`**\[**`-`**] + +## Remarks + +In Visual Studio 2022 version 17.4 and later, you can explicitly enable optional copy or move elision behavior by using the **`/Zc:nrvo`** compiler option. This option is off by default, but is set automatically when you compile using the **`/O2`** option, the **`/permissive-`** option, or **`/std:c++20`** or later. Under **`/Zc:nrvo`**, copy and move elision is performed wherever possible. Optional copy or move elision can also be explicitly disabled by using the **`/Zc:nrvo-`** option. These compiler options only control optional copy or move elision. Mandatory copy or move elision (specified by the C++ Standard) can't be disabled. + +### Mandatory copy and move elision + +The C++ standard requires copy or move elision when the returned value is initialized as part of the return statement. For example, it's required when a function returns an `ExampleType` returned by using `return ExampleType();`. The MSVC compiler always performs copy and move elision for **`return`** statements when it's required, even under **`/Zc:nrvo-`**. + +### Optional copy and move elision + +When a **`return`** statement contains an expression of non-primitive type, its execution copies the expression result into the return slot of the calling function. The compiler invokes the copy or move constructor of the returned type. Then, as the function is exited, destructors for function-local variables are called, which includes any variables named in the expression. + +The C++ standard allows (but doesn't require) the compiler to optionally construct the returned object directly in the return slot of the calling function. This construction skips (or *elides*) the copy or move constructor executed as part of the **`return`** statement. Unlike most other optimizations, this transformation is allowed to have an observable effect on the program's output. Namely, the copy or move constructor and associated destructor are called one less time. The standard still requires that the named returned variable has a defined copy or move constructor, even if the compiler elides the constructor in all cases. + +In versions before Visual Studio 2022 version 17.4, when optimizations are disabled (such as under **`/Od`** or in functions marked `#pragma optimize("", off)`) the compiler only performs mandatory copy and move elision. Under **`/O2`**, the older compilers perform optional copy or move elision on return of a named variable in an optimized function when all of these conditions are met: it has no loops or exception handling, it doesn't return multiple symbols with overlapping lifetimes, the type's copy or move constructor doesn't have default arguments. + +Visual Studio 2022 version 17.4 increases the number of places where the compiler does optional copy or move elisions under **`/Zc:nrvo`**, whether enabled explicitly, or automatically by using the **`/O2`**, **`/permissive-`**, or **`/std:c++20`** or later options. Under **`/Zc:nrvo`**, the compiler performs optional copy or move elision on return of a named variable for any function when: it has no loops or exception handling (as before); it returns the variable from a loop; it has exception handling; the returned type's copy or move constructor has default arguments. Optional copy or move elisions are never done when **`/Zc:nrvo-`** is applied, or when the function returns multiple symbols with overlapping lifetimes, or for a throw of a named variable. + +For more information and examples of mandatory and optional copy elision under **`/Zc:nrvo`**, see [Improving Copy and Move Elision](https://devblogs.microsoft.com/cppblog/improving-copy-and-move-elision) in the C++ Team Blog. + +### To set this compiler option in Visual Studio + +1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. + +1. In **Additional options**, add *`/Zc:nrvo`* or *`/Zc:nrvo-`*. Choose **OK** or **Apply** to save your changes. + +## See also + +[`/Zc` (Conformance)](zc-conformance.md)\ +[`/O2`](./o1-o2-minimize-size-maximize-speed.md)\ +[`/permissive-](./permissive-standards-conformance.md)\ +[`/std` (Specify language standard version)](std-specify-language-standard-version.md) diff --git a/docs/build/reference/zc-templatescope.md b/docs/build/reference/zc-templatescope.md new file mode 100644 index 00000000000..a149051cdd0 --- /dev/null +++ b/docs/build/reference/zc-templatescope.md @@ -0,0 +1,50 @@ +--- +description: "Learn more about the /Zc:templateScope (Check template parameter shadowing) compiler option." +title: "/Zc:templateScope (Check template parameter shadowing)" +ms.date: 11/11/2022 +f1_keywords: ["/Zc:templateScope"] +helpviewer_keywords: ["-Zc:templateScope compiler option (C++)", "/Zc:templateScope compiler option (C++)"] +--- +# `/Zc:templateScope` (Check template parameter shadowing) + +The **`/Zc:templateScope`** compiler option enables checks for Standard C++ behavior around shadowing of template parameters. + +## Syntax + +> **`/Zc:templateScope`**\[**`-`**] + +## Remarks + +The C++ Standard doesn't allow the reuse of a template parameter's name (or *shadowing*) for another declaration within the scope of the template. The **`/Zc:templateScope`** compiler option enables an error check for such shadowing. + +The **`/Zc:templateScope`** option is new in Visual Studio 2022 version 17.5 preview 1. The option is off by default even when the code is compiled using the **`/permissive-`** option (or an option that implies **`/permissive-`**, such as **`/std:c++20`** or **`/std:c++latest`**). To enable the error check, you must explicitly add **`/Zc:templateScope`** to the compiler command line. To explicitly disable the check, use the **`/Zc:templateScope-`** option. + +### Example + +Under **`/Zc:templateScope`**, this sample code produces an error: + +```cpp +template +void f(T&& t) { + int T = 13; +} + +/* Output: +t.cpp(3): error C7527: 'T': a template parameter name cannot be reused within its scope +Compiling with '/Zc:templateScope' will inform the compiler to generate this diagnostic. +*/ +``` + +### To set this compiler option in Visual Studio + +1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. + +1. In **Additional options**, add *`/Zc:templateScope`* or *`/Zc:templateScope-`*. Choose **OK** or **Apply** to save your changes. + +## See also + +[`/Zc` (Conformance)](zc-conformance.md)\ +[`/permissive-](./permissive-standards-conformance.md)\ +[`/std` (Specify language standard version)](std-specify-language-standard-version.md) diff --git a/docs/build/toc.yml b/docs/build/toc.yml index 01d14f0cb1b..b058612896c 100644 --- a/docs/build/toc.yml +++ b/docs/build/toc.yml @@ -787,6 +787,8 @@ items: href: ../build/reference/zc-externconstexpr.md - name: "/Zc:forScope (Force conformance in for loop scope)" href: ../build/reference/zc-forscope-force-conformance-in-for-loop-scope.md + - name: "/Zc:gotoScope (Enforce conformance in goto scope)" + href: ../build/reference/zc-gotoscope.md - name: "/Zc:hiddenFriend (Enforce Standard C++ hidden friend rules)" href: ../build/reference/zc-hiddenfriend.md - name: "/Zc:implicitNoexcept (Implicit exception specifiers)" @@ -797,6 +799,8 @@ items: href: ../build/reference/zc-lambda.md - name: "/Zc:noexceptTypes (C++17 noexcept rules)" href: ../build/reference/zc-noexcepttypes.md + - name: "/Zc:nrvo (Control optional NRVO)" + href: ../build/reference/zc-nrvo.md - name: "/Zc:preprocessor (Enable preprocessor conformance mode)" href: ../build/reference/zc-preprocessor.md - name: "/Zc:referenceBinding (Enforce reference binding rules)" @@ -809,6 +813,8 @@ items: href: ../build/reference/zc-static-assert.md - name: "/Zc:strictStrings (Disable string literal type conversion)" href: ../build/reference/zc-strictstrings-disable-string-literal-type-conversion.md + - name: "/Zc:templateScope (Check template parameter shadowing)" + href: ../build/reference/zc-templatescope.md - name: "/Zc:ternary (Enforce conditional operator rules)" href: ../build/reference/zc-ternary.md - name: "/Zc:threadSafeInit (Thread-safe local static initialization)" From b8e14e39712e2bc2ef3e3a0f07949df4855984d8 Mon Sep 17 00:00:00 2001 From: Colin Robertson <3836425+corob-msft@users.noreply.github.com> Date: Fri, 11 Nov 2022 18:14:18 -0800 Subject: [PATCH 2/4] fix link issue --- docs/build/reference/zc-gotoscope.md | 2 +- docs/build/reference/zc-nrvo.md | 2 +- docs/build/reference/zc-templatescope.md | 3 +-- 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/build/reference/zc-gotoscope.md b/docs/build/reference/zc-gotoscope.md index 5851e4ba968..e71d6071423 100644 --- a/docs/build/reference/zc-gotoscope.md +++ b/docs/build/reference/zc-gotoscope.md @@ -89,5 +89,5 @@ t.cpp(17): error C2362: initialization of 's' is skipped by 'goto OnError' ## See also [`/Zc` (Conformance)](zc-conformance.md)\ -[`/permissive-](./permissive-standards-conformance.md)\ +[`/permissive-`](./permissive-standards-conformance.md)\ [`/std` (Specify language standard version)](std-specify-language-standard-version.md) diff --git a/docs/build/reference/zc-nrvo.md b/docs/build/reference/zc-nrvo.md index becd73c75e9..1248f10e14d 100644 --- a/docs/build/reference/zc-nrvo.md +++ b/docs/build/reference/zc-nrvo.md @@ -45,5 +45,5 @@ For more information and examples of mandatory and optional copy elision under * [`/Zc` (Conformance)](zc-conformance.md)\ [`/O2`](./o1-o2-minimize-size-maximize-speed.md)\ -[`/permissive-](./permissive-standards-conformance.md)\ +[`/permissive-`](./permissive-standards-conformance.md)\ [`/std` (Specify language standard version)](std-specify-language-standard-version.md) diff --git a/docs/build/reference/zc-templatescope.md b/docs/build/reference/zc-templatescope.md index a149051cdd0..a6ca453833f 100644 --- a/docs/build/reference/zc-templatescope.md +++ b/docs/build/reference/zc-templatescope.md @@ -31,7 +31,6 @@ void f(T&& t) { /* Output: t.cpp(3): error C7527: 'T': a template parameter name cannot be reused within its scope -Compiling with '/Zc:templateScope' will inform the compiler to generate this diagnostic. */ ``` @@ -46,5 +45,5 @@ Compiling with '/Zc:templateScope' will inform the compiler to generate this dia ## See also [`/Zc` (Conformance)](zc-conformance.md)\ -[`/permissive-](./permissive-standards-conformance.md)\ +[`/permissive-`](./permissive-standards-conformance.md)\ [`/std` (Specify language standard version)](std-specify-language-standard-version.md) From 648aeca227a819cf45234b09bd5de509e5041335 Mon Sep 17 00:00:00 2001 From: Colin Robertson <3836425+corob-msft@users.noreply.github.com> Date: Mon, 14 Nov 2022 20:02:21 -0800 Subject: [PATCH 3/4] Address cpp-docs 4213 vcxproj at scale --- docs/build/reference/vcxproj-file-structure.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/build/reference/vcxproj-file-structure.md b/docs/build/reference/vcxproj-file-structure.md index 0f0cd77c754..5284133a666 100644 --- a/docs/build/reference/vcxproj-file-structure.md +++ b/docs/build/reference/vcxproj-file-structure.md @@ -1,7 +1,7 @@ --- title: ".vcxproj and .props file structure" description: "How the C++ native MSBuild project system .vcxproj and .props files store project information." -ms.date: 09/30/2020 +ms.date: 11/14/2022 helpviewer_keywords: [".vcxproj file structure"] ms.assetid: 14d0c552-29db-480e-80c1-7ea89d6d8e9c --- @@ -9,15 +9,15 @@ ms.assetid: 14d0c552-29db-480e-80c1-7ea89d6d8e9c [MSBuild](../msbuild-visual-cpp.md) is the default project system in Visual Studio; when you choose **File** > **New Project** in Visual C++ you're creating an MSBuild project whose settings are stored in an XML project file that has the extension *`.vcxproj`*. The project file may also import *`.props`* files and *`.targets`* files where settings can be stored. -We recommend you only create and modify *`.vcxproj`* projects in the IDE, and avoid manual editing as much as possible. In most cases, you never need to manually edit the project file. Whenever possible you should use the Visual Studio property pages to modify project settings. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +If you intend to maintain your project properties in the IDE, we recommend you only create and modify your *`.vcxproj`* projects in the IDE, and avoid manual editing as much as possible. In most cases, you never need to manually edit the project file. Manual edits may break the project connections required to modify project settings in the Visual Studio property pages, and can cause build errors that are difficult to debug and repair. For more information about using the property pages, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). -If you need customizations that aren't possible in the IDE, we recommend you add custom props or targets. Handy places to insert customizations are the *`Directory.Build.props`* and *`Directory.Build.targets`* files, which are automatically imported in all MSBuild-based projects. +At scale, managing many individual projects in the IDE becomes tedious and error-prone. It's hard to maintain consistency or enforce standardization across tens or hundreds of projects. In these cases, it's worthwhile to edit your project files to use customized *`.props`* or *`.targets`* files for common properties across many projects. You may also use these files when you require customizations that aren't possible in the IDE. Handy places to insert customizations are the *`Directory.Build.props`* and *`Directory.Build.targets`* files, which are automatically imported in all MSBuild-based projects. -In some cases, you may still need to modify a *`.vcxproj`* project file or property sheet manually. We don't recommend you edit it manually unless you have a good understanding of MSBuild, and follow the guidelines in this article. In order for the IDE to load and update *`.vcxproj`* files automatically, these files have several restrictions that don't apply to other MSBuild project files. They weren't designed for manual editing. Mistakes can cause the IDE to crash or behave in unexpected ways. +In some cases, customized *`.props`* or *`.targets`* files alone may not be sufficient for your project management needs. You may still need to modify *`.vcxproj`* project files or property sheets manually. Manual editing requires a good understanding of MSBuild, and must follow the guidelines in this article. In order for the IDE to load and update *`.vcxproj`* files automatically, these files have several restrictions that don't apply to other MSBuild project files. Mistakes can cause the IDE to crash or behave in unexpected ways. For manual editing scenarios, this article contains basic information about the structure of *`.vcxproj`* and related files. -**Important:** +## Important considerations If you choose to manually edit a *`.vcxproj`* file, be aware of these facts: @@ -42,7 +42,7 @@ If you choose to manually edit a *`.vcxproj`* file, be aware of these facts: ``` - "Not supported" means that macros aren't guaranteed to work for all operations in the IDE. Macros that don't change their value in different configurations should work, but might not be preserved if an item is moved to a different filter or project. Macros that change their value for different configurations will cause problems. That's because the IDE doesn't expect project item paths to be different for different project configurations. + "Not supported" means that macros aren't guaranteed to work for all operations in the IDE. Macros that don't change their value in different configurations should work, but might not be preserved if an item is moved to a different filter or project. Macros that change their value for different configurations will cause problems. The IDE doesn't expect project item paths to be different for different project configurations. - To add, remove, or modify project properties correctly when you edit them in the **Project Properties** dialog, the file must contain separate groups for each project configuration. The conditions must be in this form: @@ -272,7 +272,7 @@ Defines (directly or through imports) C++ targets such as build, clean, and so o This group contains imports for the Build Customization target files. -## Impact of incorrect ordering +## Consequences of incorrect ordering The Visual Studio IDE depends on the project file having the ordering described previously. For example, when you define a property value in the property pages, the IDE will generally place the property definition in the property group with the empty label. This ordering ensures that default values brought in the system property sheets are overridden by user-defined values. Similarly, the target files are imported at the end since they consume the properties defined before, and since they generally don't define properties themselves. Likewise, user property sheets are imported after the system property sheets (included by *`Microsoft.Cpp.props`*). This order ensures that the user can override any defaults brought in by the system property sheets. From 93e8066867dfaf2312d1326159698a74dfab17b6 Mon Sep 17 00:00:00 2001 From: Colin Robertson <3836425+corob-msft@users.noreply.github.com> Date: Mon, 14 Nov 2022 20:03:39 -0800 Subject: [PATCH 4/4] Tone recommendation for manual edits --- docs/build/reference/vcxproj-file-structure.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/build/reference/vcxproj-file-structure.md b/docs/build/reference/vcxproj-file-structure.md index 5284133a666..0ce1e28fb50 100644 --- a/docs/build/reference/vcxproj-file-structure.md +++ b/docs/build/reference/vcxproj-file-structure.md @@ -9,7 +9,7 @@ ms.assetid: 14d0c552-29db-480e-80c1-7ea89d6d8e9c [MSBuild](../msbuild-visual-cpp.md) is the default project system in Visual Studio; when you choose **File** > **New Project** in Visual C++ you're creating an MSBuild project whose settings are stored in an XML project file that has the extension *`.vcxproj`*. The project file may also import *`.props`* files and *`.targets`* files where settings can be stored. -If you intend to maintain your project properties in the IDE, we recommend you only create and modify your *`.vcxproj`* projects in the IDE, and avoid manual editing as much as possible. In most cases, you never need to manually edit the project file. Manual edits may break the project connections required to modify project settings in the Visual Studio property pages, and can cause build errors that are difficult to debug and repair. For more information about using the property pages, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +If you intend to maintain your project properties in the IDE, we recommend you only create and modify your *`.vcxproj`* projects in the IDE, and avoid manual edits to the files. In most cases, you never need to manually edit the project file. Manual edits may break the project connections required to modify project settings in the Visual Studio property pages, and can cause build errors that are difficult to debug and repair. For more information about using the property pages, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). At scale, managing many individual projects in the IDE becomes tedious and error-prone. It's hard to maintain consistency or enforce standardization across tens or hundreds of projects. In these cases, it's worthwhile to edit your project files to use customized *`.props`* or *`.targets`* files for common properties across many projects. You may also use these files when you require customizations that aren't possible in the IDE. Handy places to insert customizations are the *`Directory.Build.props`* and *`Directory.Build.targets`* files, which are automatically imported in all MSBuild-based projects.