diff --git a/.acrolinx-config.edn b/.acrolinx-config.edn index 06bbb9c9c2..78cdd0e4df 100644 --- a/.acrolinx-config.edn +++ b/.acrolinx-config.edn @@ -1,4 +1,4 @@ -{:allowed-branchname-matches ["^master$" "^release..*"] +{:allowed-branchname-matches ["main" "release-.*"] :allowed-filename-matches ["docs" "styleguide"] :template-header @@ -21,7 +21,7 @@ " **More info about Acrolinx** -- [Install Acrolinx locally for VSCode](https://review.docs.microsoft.com/en-us/help/contribute/contribute-acrolinx-vscode) +- [Install Acrolinx locally for VS Code](https://review.docs.microsoft.com/en-us/help/contribute/contribute-acrolinx-vscode) - [Report false positives or issues](https://aka.ms/acrolinxbug) "} diff --git a/.github/ISSUE_TEMPLATE/new-c---2017-stl-library-documentation-topic-.md b/.github/ISSUE_TEMPLATE/new-c---2017-stl-library-documentation-topic-.md deleted file mode 100644 index 701e5a16cc..0000000000 --- a/.github/ISSUE_TEMPLATE/new-c---2017-stl-library-documentation-topic-.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -name: 'New C++ 2017 STL library documentation topic ' -about: Create a C++ 2017 doc tracking work item -title: '' -labels: C++17, STL doc work -assignees: '' - ---- - -ISO paper for this feature: [PaperID]() -First implemented in: VS 20YY major.minor diff --git a/.github/ISSUE_TEMPLATE/new-c---2020-stl-library-documentation-topic-.md b/.github/ISSUE_TEMPLATE/new-c---2020-stl-library-documentation-topic-.md deleted file mode 100644 index 7a10d6f1c7..0000000000 --- a/.github/ISSUE_TEMPLATE/new-c---2020-stl-library-documentation-topic-.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -name: 'New C++ 2020 STL library documentation topic ' -about: Create a C++ 2020 doc tracking work item -title: '' -labels: STL doc work, C++20 -assignees: '' -milestone: backlog -project: C++20 ---- - -ISO paper for this feature: [PaperID]() -First implemented in: VS 20YY major.minor diff --git a/.github/ISSUE_TEMPLATE/new-c---stl-library-doc-topic-.md b/.github/ISSUE_TEMPLATE/new-c---stl-library-doc-topic-.md deleted file mode 100644 index 77b51776c3..0000000000 --- a/.github/ISSUE_TEMPLATE/new-c---stl-library-doc-topic-.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -name: 'New C++ STL library documentation topic ' -about: Create a C++ doc tracking work item -title: '' -labels: STL doc work -assignees: '' - ---- - -ISO paper for this feature: [PaperID]() -First implemented in: VS YYYY major.minor diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000000..75dc5da1e0 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,118 @@ +When writing documentation, follow these guidelines: + +## General style tips + +* Get to the point fast. Be concise and clear. +* Talk like a person. +* Simpler is better. +* Be brief. Give customers just enough information to make decisions confidently. Prune excess words. +* Break up long sentences. +* Follow the style of the [Microsoft Writing Style Guide](https://learn.microsoft.com/style-guide/welcome/). If there's a conflict between the following guidelines and the Microsoft Writing Style Guide, ask how to resolve it. + +## Grammar + +* Use present tense verbs (is, open) instead of past tense (was, opened). For example, "The method returns a value" instead of "The method will return a value." +* Write factual statements and direct commands. Avoid hypotheticals. +* Use active voice where the subject performs the action. +* Write in second person (you) to speak directly to readers. +* Use gender-neutral language. +* Avoid multiple -ing words that could create ambiguity. +* Keep prepositional phrases simple and clear. +* Place modifiers close to what they modify. +* Use a conversational tone with contractions. +* Don't use "we" or "our" to refer to the authors of the documentation. +* Use the imperative mood for instructions. For example, "Call the method" instead of "You should call the method." +* Use "might" instead of "may" to indicate possibility. For example, "This method might throw an exception" instead of "This method may throw an exception." +* Use the Oxford comma in lists of three or more items. + +## Capitalization + +* Use sentence-style capitalization for everything except proper nouns. +* Always capitalize proper nouns. +* Don’t capitalize the spelled-out form of an acronym unless it's a proper noun. +* Use title-style capitalization for product and service names. +* Don't use all uppercase for emphasis. + +## Numbers + +* Spell out numbers for zero through nine, unless space is limited. Use numerals for 10 and above. +* Spell out numbers at the beginning of a sentence. +* Spell out ordinal numbers such as first, second, and third. Don't add -ly to form adverbs from ordinal numbers. +* Number ordered list items all as "1." instead of "1.", "2.", etc. Use bullets for unordered lists. + +## Punctuation + +* Use short, simple sentences. +* End all sentences with a period. +* Use one space after punctuation marks. +* After a colon, capitalize only proper nouns. +* Avoid semicolons - use separate sentences instead. +* Use question marks sparingly. +* Don't use slashes (/) - use "or" instead. + +## Text formatting + +* UI elements, like menu items, dialog names, and names of text boxes, should be in **bold** text. +* Use `code style` for: + * Code elements, like method names, property names, and language keywords. + * SQL commands. + * NuGet package names. + * Command-line commands. + * Database table and column names. + * Resource names (like virtual machine names) that shouldn't be localized. + * URLs that you don't want to be selectable. + * File names and folders, custom types, and other text that should never be localized. +* For code placeholders, if you want users to replace part of an input string with their own values, use angle brackets (less than < and greater than > characters) on that placeholder text. + +## Headings + +* Headings should be in sentence case, not title case. Don't use gerunds in titles. +* Don't apply an inline style like italic, or bold to headings. But do use inline code style for headings that are code elements, like method names or property names. + +## Alerts + +* Alerts are a Markdown extension to create block quotes that render with colors and icons that indicate the significance of the content. The following alert types are supported: + + * `[!NOTE]` Information the user should notice even if skimming. + * `[!TIP]` Optional information to help a user be more successful. + * `[!IMPORTANT]` Essential information required for user success. + * `[!CAUTION]` Negative potential consequences of an action. + * `[!WARNING]` Dangerous certain consequences of an action. + +## Adding links + +* Add links to related topics and resources where appropriate. +* Links to other documentation articles should be relative, not absolute. Start relative links with `/docs/` and include the `.md` suffix. If you add a link to another page on learn.microsoft.com that's not in this repo, remove https://learn.microsoft.com/en-us from the link. +* Links to bookmarks within the same article should be relative and start with `#`. +* Link descriptions should be descriptive and make sense on their own. Don't use "click here" or "this link" or "here". +* When you are going to refer to another file or an article on the web, use this format: "For more information, see [descriptive name of link](link path)." The exception to this is the See Also links at the end of an article. Those should be markdown links and contain the title of the article you link to as the descriptive portion of the link. + +## Adding new files + +* If you add a new Markdown file, it should be named in all lowercase with hyphens separating words. Also, omit any filler words such as "the" or "a" from the file name. +* If you're adding a new Markdown file, the following indicates where it should go the folder structure. If you aren't sure, ask. + If the new file is about Linux, put it in the docs/linux folder. + If the new file is about the C++ Standard Template Library (STL), put it in the docs/standard-library folder. + If the new file is about the C runtime, put it in the docs/c-runtime-library folder. + If the new file is about the C++ language, put it in the docs/cpp folder. + If the new file is about a C++ feature specific to the Visual Studio IDE, put it in the docs/ide folder. + If the new file is about the build process or modules, put it in the docs/build\reference folder. + If the new file is about Build Insights, put it in the docs/build-insights folder. + +## Images + +* Use images only when they add value. +* Images have a descriptive and meaningful alt text that starts with "Screenshot showing" and ends with ".". +* Videos have a descriptive and meaningful alt text or title that starts with "Video showing" and ends with ".". + +## Numbered steps + +* Write complete sentences with capitalization and periods +* Use imperative verbs +* Clearly indicate where actions take place (UI location) +* For single steps, use a bullet instead of a number +* When allowed, use angle brackets for menu sequences (File > Open) + +## Terminology + +* Use "Select" instead of "Click" for UI elements like buttons, menu items, links, dropdowns, and checkboxes. \ No newline at end of file diff --git a/.gitignore b/.gitignore index 50628e8f13..10b0192bf5 100644 --- a/.gitignore +++ b/.gitignore @@ -7,7 +7,7 @@ _themes.MSDN.Modern/ _themes.VS.Modern/ # Ignore local configuration changes -.github/ +#.github/ .openpublishing.buildcore.ps1 .vscode/ diff --git a/.markdownlint.json b/.markdownlint.json index ce59de63f1..721f62cf28 100644 --- a/.markdownlint.json +++ b/.markdownlint.json @@ -2,6 +2,7 @@ "default": true, "DOCSMD006": false, "MD001": false, + "MD004": false, "MD013": false, "MD024": { "siblings_only": true diff --git a/.openpublishing.build.ps1 b/.openpublishing.build.ps1 deleted file mode 100644 index aadef76202..0000000000 --- a/.openpublishing.build.ps1 +++ /dev/null @@ -1,17 +0,0 @@ -param( - [string]$buildCorePowershellUrl = "https://opbuildstorageprod.blob.core.windows.net/opps1container/.openpublishing.buildcore.ps1", - [string]$parameters -) -# Main -$errorActionPreference = 'Stop' - -# Step-1: Download buildcore script to local -echo "download build core script to local with source url: $buildCorePowershellUrl" -$repositoryRoot = Split-Path -Parent $MyInvocation.MyCommand.Definition -$buildCorePowershellDestination = "$repositoryRoot\.openpublishing.buildcore.ps1" -Invoke-WebRequest $buildCorePowershellUrl -OutFile "$buildCorePowershellDestination" - -# Step-2: Run build core -echo "run build core script with parameters: $parameters" -& "$buildCorePowershellDestination" "$parameters" -exit $LASTEXITCODE diff --git a/.openpublishing.publish.config.json b/.openpublishing.publish.config.json index 565bd55125..296bfe4f38 100644 --- a/.openpublishing.publish.config.json +++ b/.openpublishing.publish.config.json @@ -10,7 +10,10 @@ "moniker_ranges": [ ">= msvc-140" ], - "xref_query_tags": ["/dotnet", "/uwp/api"], + "xref_query_tags": [ + "/dotnet", + "/uwp/api" + ], "open_to_public_contributors": true, "type_mapping": { "Conceptual": "Content", @@ -22,23 +25,22 @@ } ], "notification_subscribers": [], + "sync_notification_subscribers": [], "branches_to_filter": [], - "git_repository_url_open_to_public_contributors": "https://github.com/Microsoft/cpp-docs", - "git_repository_branch_open_to_public_contributors": "master", - "skip_source_output_uploading": false, + "git_repository_url_open_to_public_contributors": "https://github.com/MicrosoftDocs/cpp-docs", + "git_repository_branch_open_to_public_contributors": "main", "need_preview_pull_request": true, - "enable_incremental_build": true, "dependent_repositories": [ { "path_to_root": "_themes", "url": "https://github.com/Microsoft/templates.docs.msft", - "branch": "master", + "branch": "main", "branch_mapping": {} }, { "path_to_root": "_themes.pdf", "url": "https://github.com/Microsoft/templates.docs.msft.pdf", - "branch": "master", + "branch": "main", "branch_mapping": {} } ], @@ -47,20 +49,21 @@ "Publish", "Pdf" ], - "master": [ + "main": [ "Publish", "Pdf" ] }, - "need_generate_pdf_url_template": true, "targets": { "Pdf": { "template_folder": "_themes.pdf" } }, + "docs_build_engine": {}, + "skip_source_output_uploading": false, + "enable_incremental_build": true, + "contribution_branch_mappings": null, + "need_generate_pdf_url_template": true, "need_generate_pdf": false, - "need_generate_intellisense": false, - "docs_build_engine": { - "name": "docfx_v3" - } -} + "need_generate_intellisense": false +} \ No newline at end of file diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index 95be4e1800..e6910b5922 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -1,5 +1,10 @@ { "redirections": [ + { + "source_path": "docs/windows/desktop-applications-visual-cpp.md", + "redirect_url": "/cpp/windows/overview-of-windows-programming-in-cpp", + "redirect_document_id": true + }, { "source_path": "docs/cpp-conformance-improvements-2017.md", "redirect_url": "/cpp/overview/cpp-conformance-improvements", @@ -317,17 +322,32 @@ }, { "source_path": "docs/build/batch-mode-rules.md", - "redirect_url": "/cpp/build/reference/batch-mode-rules", + "redirect_url": "/cpp/build/reference/inference-rules#batch-mode-rules", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/batch-mode-rules.md", + "redirect_url": "/cpp/build/reference/inference-rules#batch-mode-rules", "redirect_document_id": false }, { "source_path": "docs/build/command-macros-and-options-macros.md", - "redirect_url": "/cpp/build/reference/command-macros-and-options-macros", + "redirect_url": "/cpp/build/reference/special-nmake-macros#command-macros-and-options-macros", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/command-macros-and-options-macros.md", + "redirect_url": "/cpp/build/reference/special-nmake-macros#command-macros-and-options-macros", "redirect_document_id": false }, { "source_path": "docs/build/command-modifiers.md", - "redirect_url": "/cpp/build/reference/command-modifiers", + "redirect_url": "/cpp/build/reference/commands-in-a-makefile#command-modifiers", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/command-modifiers.md", + "redirect_url": "/cpp/build/reference/commands-in-a-makefile#command-modifiers", "redirect_document_id": false }, { @@ -337,7 +357,12 @@ }, { "source_path": "docs/build/comments-in-a-makefile.md", - "redirect_url": "/cpp/build/reference/comments-in-a-makefile", + "redirect_url": "/cpp/build/reference/contents-of-a-makefile#comments-in-a-makefile", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/comments-in-a-makefile.md", + "redirect_url": "/cpp/build/reference/contents-of-a-makefile#comments-in-a-makefile", "redirect_document_id": false }, { @@ -347,7 +372,12 @@ }, { "source_path": "docs/build/creating-inline-file-text.md", - "redirect_url": "/cpp/build/reference/creating-inline-file-text", + "redirect_url": "/cpp/build/reference/inline-files-in-a-makefile#creating-inline-file-text", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/creating-inline-file-text.md", + "redirect_url": "/cpp/build/reference/inline-files-in-a-makefile#creating-inline-file-text", "redirect_document_id": false }, { @@ -362,7 +392,12 @@ }, { "source_path": "docs/build/defining-a-rule.md", - "redirect_url": "/cpp/build/reference/defining-a-rule", + "redirect_url": "/cpp/build/reference/inference-rules#defining-a-rule", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/defining-a-rule.md", + "redirect_url": "/cpp/build/reference/inference-rules#defining-a-rule", "redirect_document_id": false }, { @@ -397,12 +432,12 @@ }, { "source_path": "docs/build/environment-variable-macros.md", - "redirect_url": "/cpp/build/reference/environment-variable-macros", + "redirect_url": "/cpp/build/reference/special-nmake-macros#environment-variable-macros", "redirect_document_id": false }, { - "source_path": "docs/build/executing-a-program-in-preprocessing.md", - "redirect_url": "/cpp/build/reference/executing-a-program-in-preprocessing", + "source_path": "docs/build/reference/environment-variable-macros.md", + "redirect_url": "/cpp/build/reference/special-nmake-macros#environment-variable-macros", "redirect_document_id": false }, { @@ -416,18 +451,23 @@ "redirect_document_id": false }, { - "source_path": "docs/build/expressions-in-makefile-preprocessing.md", - "redirect_url": "/cpp/build/reference/expressions-in-makefile-preprocessing", + "source_path": "docs/build/filename-macros.md", + "redirect_url": "/cpp/build/reference/special-nmake-macros#filename-macros", "redirect_document_id": false }, { - "source_path": "docs/build/filename-macros.md", - "redirect_url": "/cpp/build/reference/filename-macros", + "source_path": "docs/build/reference/filename-macros.md", + "redirect_url": "/cpp/build/reference/special-nmake-macros#filename-macros", "redirect_document_id": false }, { "source_path": "docs/build/filename-parts-syntax.md", - "redirect_url": "/cpp/build/reference/filename-parts-syntax", + "redirect_url": "/cpp/build/reference/commands-in-a-makefile#filename-parts-syntax", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/filename-parts-syntax.md", + "redirect_url": "/cpp/build/reference/commands-in-a-makefile#filename-parts-syntax", "redirect_document_id": false }, { @@ -437,7 +477,12 @@ }, { "source_path": "docs/build/inferred-dependents-and-rules.md", - "redirect_url": "/cpp/build/reference/inferred-dependents-and-rules", + "redirect_url": "/cpp/build/reference/inference-rules#inferred-dependents-and-rules", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/inferred-dependents-and-rules.md", + "redirect_url": "/cpp/build/reference/inference-rules#inferred-dependents-and-rules", "redirect_document_id": false }, { @@ -457,7 +502,17 @@ }, { "source_path": "docs/build/long-filenames-in-a-makefile.md", - "redirect_url": "/cpp/build/reference/long-filenames-in-a-makefile", + "redirect_url": "/cpp/build/reference/contents-of-a-makefile#long-filenames-in-a-makefile", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/long-filenames-in-a-makefile.md", + "redirect_url": "/cpp/build/reference/contents-of-a-makefile#long-filenames-in-a-makefile", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/wildcards-and-nmake.md", + "redirect_url": "/cpp/build/reference/contents-of-a-makefile#wildcards-and-nmake", "redirect_document_id": false }, { @@ -537,7 +592,12 @@ }, { "source_path": "docs/build/macro-substitution.md", - "redirect_url": "/cpp/build/reference/macro-substitution", + "redirect_url": "/cpp/build/reference/using-an-nmake-macro#macro-substitution", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/macro-substitution.md", + "redirect_url": "/cpp/build/reference/using-an-nmake-macro#macro-substitution", "redirect_document_id": false }, { @@ -547,17 +607,47 @@ }, { "source_path": "docs/build/makefile-preprocessing-directives.md", - "redirect_url": "/cpp/build/reference/makefile-preprocessing-directives", + "redirect_url": "/cpp/build/reference/makefile-preprocessing#makefile-preprocessing-directives", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/makefile-preprocessing-directives.md", + "redirect_url": "/cpp/build/reference/makefile-preprocessing#makefile-preprocessing-directives", "redirect_document_id": false }, { "source_path": "docs/build/makefile-preprocessing-operators.md", - "redirect_url": "/cpp/build/reference/makefile-preprocessing-operators", + "redirect_url": "/cpp/build/reference/makefile-preprocessing#makefile-preprocessing-operators", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/makefile-preprocessing-operators.md", + "redirect_url": "/cpp/build/reference/makefile-preprocessing#makefile-preprocessing-operators", + "redirect_document_id": false + }, + { + "source_path": "docs/build/expressions-in-makefile-preprocessing.md", + "redirect_url": "/cpp/build/reference/makefile-preprocessing#expressions-in-makefile-preprocessing", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/expressions-in-makefile-preprocessing.md", + "redirect_url": "/cpp/build/reference/makefile-preprocessing#expressions-in-makefile-preprocessing", + "redirect_document_id": false + }, + { + "source_path": "docs/build/executing-a-program-in-preprocessing.md", + "redirect_url": "/cpp/build/reference/makefile-preprocessing#executing-a-program-in-preprocessing", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/executing-a-program-in-preprocessing.md", + "redirect_url": "/cpp/build/reference/makefile-preprocessing#executing-a-program-in-preprocessing", "redirect_document_id": false }, { "source_path": "docs/build/makefile-preprocessing.md", - "redirect_url": "/cpp/build/reference/expressions-in-makefile-preprocessing", + "redirect_url": "/cpp/build/reference/makefile-preprocessing", "redirect_document_id": false }, { @@ -567,7 +657,12 @@ }, { "source_path": "docs/build/multiple-inline-files.md", - "redirect_url": "/cpp/build/reference/multiple-inline-files", + "redirect_url": "/cpp/build/reference/inline-files-in-a-makefile#multiple-inline-files", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/multiple-inline-files.md", + "redirect_url": "/cpp/build/reference/inline-files-in-a-makefile#multiple-inline-files", "redirect_document_id": false }, { @@ -597,22 +692,42 @@ }, { "source_path": "docs/build/null-and-undefined-macros.md", - "redirect_url": "/cpp/build/reference/null-and-undefined-macros", + "redirect_url": "/cpp/build/reference/defining-an-nmake-macro#null-and-undefined-macros", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/null-and-undefined-macros.md", + "redirect_url": "/cpp/build/reference/defining-an-nmake-macro#null-and-undefined-macros", "redirect_document_id": false }, { "source_path": "docs/build/precedence-in-inference-rules.md", - "redirect_url": "/cpp/build/reference/precedence-in-inference-rules", + "redirect_url": "/cpp/build/reference/inference-rules#precedence-in-inference-rules", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/precedence-in-inference-rules.md", + "redirect_url": "/cpp/build/reference/inference-rules#precedence-in-inference-rules", "redirect_document_id": false }, { "source_path": "docs/build/precedence-in-macro-definitions.md", - "redirect_url": "/cpp/build/reference/precedence-in-macro-definitions", + "redirect_url": "/cpp/build/reference/defining-an-nmake-macro#precedence-in-macro-definitions", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/precedence-in-macro-definitions.md", + "redirect_url": "/cpp/build/reference/defining-an-nmake-macro#precedence-in-macro-definitions", "redirect_document_id": false }, { "source_path": "docs/build/predefined-rules.md", - "redirect_url": "/cpp/build/reference/predefined-rules", + "redirect_url": "/cpp/build/reference/inference-rules#predefined-rules", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/predefined-rules.md", + "redirect_url": "/cpp/build/reference/inference-rules#predefined-rules", "redirect_document_id": false }, { @@ -632,12 +747,22 @@ }, { "source_path": "docs/build/recursion-macros.md", - "redirect_url": "/cpp/build/reference/recursion-macros", + "redirect_url": "/cpp/build/reference/special-nmake-macros#recursion-macros", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/recursion-macros.md", + "redirect_url": "/cpp/build/reference/special-nmake-macros#recursion-macros", "redirect_document_id": false }, { "source_path": "docs/build/reusing-inline-files.md", - "redirect_url": "/cpp/build/reference/reusing-inline-files", + "redirect_url": "/cpp/build/reference/inline-files-in-a-makefile#reusing-inline-files", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/reusing-inline-files.md", + "redirect_url": "/cpp/build/reference/inline-files-in-a-makefile#reusing-inline-files", "redirect_document_id": false }, { @@ -662,17 +787,37 @@ }, { "source_path": "docs/build/search-paths-in-rules.md", - "redirect_url": "/cpp/build/reference/search-paths-in-rules", + "redirect_url": "/cpp/build/reference/inference-rules#search-paths-in-rules", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/search-paths-in-rules.md", + "redirect_url": "/cpp/build/reference/inference-rules#search-paths-in-rules", + "redirect_document_id": false + }, + { + "source_path": "docs/build/setting-the-path-and-environment-variables-for-command-line-builds.md", + "redirect_url": "/cpp/build/building-on-the-command-line", "redirect_document_id": false }, { "source_path": "docs/build/special-characters-in-a-makefile.md", - "redirect_url": "/cpp/build/reference/special-characters-in-a-makefile", + "redirect_url": "/cpp/build/reference/contents-of-a-makefile#special-characters-in-a-makefile", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/special-characters-in-a-makefile.md", + "redirect_url": "/cpp/build/reference/contents-of-a-makefile#special-characters-in-a-makefile", "redirect_document_id": false }, { "source_path": "docs/build/special-characters-in-macros.md", - "redirect_url": "/cpp/build/reference/special-characters-in-macros", + "redirect_url": "/cpp/build/reference/defining-an-nmake-macro#special-characters-in-macros", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/special-characters-in-macros.md", + "redirect_url": "/cpp/build/reference/defining-an-nmake-macro#special-characters-in-macros", "redirect_document_id": false }, { @@ -682,7 +827,12 @@ }, { "source_path": "docs/build/specifying-an-inline-file.md", - "redirect_url": "/cpp/build/reference/specifying-an-inline-file", + "redirect_url": "/cpp/build/reference/inline-files-in-a-makefile#specifying-an-inline-file", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/specifying-an-inline-file.md", + "redirect_url": "/cpp/build/reference/inline-files-in-a-makefile#specifying-an-inline-file", "redirect_document_id": false }, { @@ -715,6 +865,21 @@ "redirect_url": "/cpp/build/reference/running-nmake", "redirect_document_id": false }, + { + "source_path": "docs/build/manifest-generation-in-visual-studio.md", + "redirect_url": "/cpp/build/understanding-manifest-generation-for-c-cpp-programs#manifest-generation-in-visual-studio", + "redirect_document_id": false + }, + { + "source_path": "docs/build/manifest-generation-at-the-command-line.md", + "redirect_url": "/cpp/build/understanding-manifest-generation-for-c-cpp-programs#manifest-generation-at-the-command-line", + "redirect_document_id": false + }, + { + "source_path": "docs/build/how-to-embed-a-manifest-inside-a-c-cpp-application.md", + "redirect_url": "/cpp/build/understanding-manifest-generation-for-c-cpp-programs#how-to-embed-a-manifest-inside-a-c-cpp-application", + "redirect_document_id": false + }, { "source_path": "docs/build/unwind-data-for-exception-handling-debugger-support.md", "redirect_url": "/cpp/build/exception-handling-x64", @@ -752,7 +917,12 @@ }, { "source_path": "docs/build/where-to-define-macros.md", - "redirect_url": "/cpp/build/reference/where-to-define-macros", + "redirect_url": "/cpp/build/reference/defining-an-nmake-macro#where-to-define-macros", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/where-to-define-macros.md", + "redirect_url": "/cpp/build/reference/defining-an-nmake-macro#where-to-define-macros", "redirect_document_id": false }, { @@ -800,6 +970,11 @@ "redirect_url": "/cpp/build-insights/reference/wpa-views", "redirect_document_id": false }, + { + "source_path": "docs/c-language/generic_selection.md", + "redirect_url": "/cpp/c-language/generic-selection", + "redirect_document_id": false + }, { "source_path": "docs/c-language/operators-c.md", "redirect_url": "/cpp/c-language/lexical-grammar", @@ -1205,11 +1380,6 @@ "redirect_url": "/cpp/get-started/tutorial-console-cpp", "redirect_document_id": false }, - { - "source_path": "docs/get-started/index.yml", - "redirect_url": "/cpp/get-started/tutorial-console-cpp", - "redirect_document_id": false - }, { "source_path": "docs/ide/adding-references-in-visual-cpp-projects.md", "redirect_url": "/cpp/build/adding-references-in-visual-cpp-projects", @@ -7580,6 +7750,21 @@ "redirect_url": "/cpp/error-messages/compiler-errors-2/compiler-errors-c2500-through-c2599", "redirect_document_id": false }, + { + "source_path": "docs/error-messages/compiler-errors-1/fatal-error-c999.md", + "redirect_url": "/cpp/error-messages/compiler-errors-1/c-cpp-build-errors", + "redirect_document_id": false + }, + { + "source_path": "docs/error-messages/compiler-errors-1/fatal-error-c1000-c1999.md", + "redirect_url": "/cpp/error-messages/compiler-errors-1/c-cpp-build-errors", + "redirect_document_id": false + }, + { + "source_path": "docs/error-messages/compiler-warnings/compiler-warning-level-1-c4999.md", + "redirect_url": "/cpp/error-messages/compiler-errors-1/c-cpp-build-errors", + "redirect_document_id": false + }, { "source_path": "docs/error-messages/compiler-warnings/index.md", "redirect_url": "/cpp/error-messages/compiler-warnings/compiler-warnings-c4000-through-c4199", @@ -13574,6 +13759,11 @@ "source_path": "docs/c-runtime-library/operator-new-crt.md", "redirect_url": "docs/c-runtime-library/new-operator-crt", "redirect_document_id": false + }, + { + "source_path": "docs/overview/whats-new-cpp-docs.md", + "redirect_url": "../../cpp/overview/what-s-new-for-visual-cpp-in-visual-studio", + "redirect_document_id": false } ] -} +} \ No newline at end of file diff --git a/.whatsnew.json b/.whatsnew.json index e1f1f386cc..a5807f933e 100644 --- a/.whatsnew.json +++ b/.whatsnew.json @@ -1,5 +1,5 @@ { - "$schema": "https://whatsnewapi.azurewebsites.net/schema", + "$schema": "https://github.com/dotnet/docs-tools/blob/main/WhatsNew.Infrastructure/Configuration/reposettings.schema.json", "docSetProductName": "C++, C, and Assembler", "rootDirectory": "docs/", "docLinkSettings": { @@ -7,13 +7,21 @@ "relativeLinkPrefix": "../" }, "inclusionCriteria": { - "minAdditionsToFile": 10, + "minAdditionsToFile": 2, "pullRequestTitlesToIgnore": [ "^Confirm merge from FromPublicMasterBranch", - "^Repo sync for protected CLA branch" + "^Repo sync for protected CLA branch", + "^Repo sync for protected branch" ], "omitPullRequestTitles": false }, + "navigationOptions": { + "maximumNumberOfArticles": 2, + "tocParentNode": " ", + "repoTocFolder": " ", + "indexParentNode": " ", + "repoIndexFolder": " " + }, "areas": [ {"names": ["assembler", "intrinsics"], "heading": "C/C++ compiler intrinsics and assembly language"}, {"names": ["atl", "atl-mfc-shared", "mfc"], "heading": "Active Template Library (ATL), Microsoft Foundation Classes (MFC)"}, diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a52d3bc599..bbfa443111 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,13 +2,13 @@ Thank you for your interest in contributing to the Visual C++ documentation! -In this topic, you'll see the basic process for adding or updating content in the [Visual C++ documentation site](https://docs.microsoft.com/cpp). +In this topic, you'll see the basic process for adding or updating content in the [Visual C++ documentation site](https://learn.microsoft.com/cpp/). In this topic, we'll cover: - [Process for contributing](#process-for-contributing) - [DOs and DON'Ts](#dos-and-donts) -- [Building the docs](#building-the-docs) +- [Building the documentation](#building-the-documentation) - [Contributing to samples](#contributing-to-samples) - [Contributor license agreement](#contributor-license-agreement) @@ -44,7 +44,7 @@ docs wstring-conversion.png ``` -**Step 5:** Submit a Pull Request (PR) from your branch to `MicrosoftDocs/cpp-docs/master`. +**Step 5:** Submit a Pull Request (PR) from your branch to `MicrosoftDocs/cpp-docs/main`. If your PR is addressing an existing issue, add the `Fixes #Issue_Number` keyword to the commit message or PR description, so the issue can be automatically closed when the PR is merged. For more information, see [Closing issues via commit messages](https://help.github.com/articles/closing-issues-via-commit-messages/). @@ -52,9 +52,9 @@ The Visual Studio team will review your PR and let you know if the change looks **Step 6:** Make any necessary updates to your branch as discussed with the team. -The maintainers will merge your PR into the master branch once feedback has been applied and your change looks good. +The maintainers will merge your PR into the main branch once feedback has been applied and your change looks good. -On a certain cadence, we push all commits from master branch into the live branch and then you'll be able to see your contribution live on [docs.microsoft.com](https://docs.microsoft.com/cpp/). +On a certain cadence, we push all commits from main branch into the live branch and then you'll be able to see your contribution on [Microsoft Learn](https://learn.microsoft.com/cpp/). ## DOs and DON'Ts @@ -70,11 +70,11 @@ Below is a short list of guiding rules that you should keep in mind when you are > [!NOTE] > You might notice that some of the topics are not currently following all the guidelines specified here and on the [style guide](./styleguide/template.md) as well. We're working towards achieving consistency throughout the site. Check the list of [open issues](https://github.com/MicrosoftDocs/cpp-docs/issues?q=is%3Aissue+is%3Aopen+label%3Aguidelines-adherence) we're currently tracking for that specific goal. -## Building the docs +## Building the documentation -The documentation is written in [GitHub Flavored Markdown](https://help.github.com/categories/writing-on-github/) and built using [DocFX](https://dotnet.github.io/docfx/) and other internal publishing/building tools. It is hosted at [docs.microsoft.com](https://docs.microsoft.com/). +The documentation is written in [GitHub-Flavored Markdown](https://help.github.com/categories/writing-on-github/) and built using [DocFX](https://dotnet.github.io/docfx/) and other internal publishing and build tools. It's published to [Microsoft Learn](https://learn.microsoft.com/). -If you want to build the docs locally, you need to install [DocFX](https://dotnet.github.io/docfx/); latest versions are the best. +If you want to build the documentation locally, you need to install the latest version of [DocFX](https://dotnet.github.io/docfx/). There are several ways to use DocFX, and most of them are covered in the [DocFX getting started guide](https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html). The following instructions use the [command-line based](https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html#2-use-docfx-as-a-command-line-tool) version of the tool. If you are comfortable with other ways listed on the link above, feel free to use those. @@ -94,6 +94,6 @@ For now, include required sample code as inline code blocks in your article. The ## Contributor license agreement -You must sign the [Contribution License Agreement (CLA)](LICENSE) before your PR is merged. This is a one-time requirement for projects in docs.microsoft.com. You can read more about [Contribution License Agreements (CLA)](https://en.wikipedia.org/wiki/Contributor_License_Agreement) on Wikipedia. +You must sign the [Contribution License Agreement (CLA)](LICENSE) before your PR is merged. This is a one-time requirement for projects on Microsoft Learn. You can read more about [Contribution License Agreements (CLA)](https://en.wikipedia.org/wiki/Contributor_License_Agreement) on Wikipedia. You don't have to sign the agreement up-front. You can clone, fork, and submit your PR as usual. When your PR is created, it is classified by a CLA bot. If the change is trivial (for example, you fixed a typo), then the PR is labeled with CLA-not-required. Otherwise, it's classified as CLA-required. Once you signed the CLA, the current and all future pull requests are labeled as CLA-signed. diff --git a/README.md b/README.md index a02389709b..816a2293bf 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,14 @@ -# Visual Studio documentation for Microsoft C++ +# Microsoft C++, C, and Assembler documentation -Welcome! This repository contains source files for the work-in-progress Microsoft C++ (MSVC or Visual C++) technical documentation. The articles are published on the [C++ in Visual Studio documentation site](https://docs.microsoft.com/cpp). +Welcome! This repository contains source files for the technical documentation published on [https://learn.microsoft.com/cpp](https://learn.microsoft.com/cpp). -The documentation for Visual Basic and Visual C# are located in a separate repository at [https://github.com/dotnet/core-docs](https://github.com/dotnet/core-docs), and the Visual Studio documentation is located in the repository located at [https://github.com/Microsoft/visualstudio-docs](https://github.com/Microsoft/visualstudio-docs). +The documentation for [.NET](https://github.com/dotnet/docs) and [Visual Studio](https://github.com/MicrosoftDocs/visualstudio-docs) are located in separate repositories. ## Contributing to the documentation -We welcome your contributions to help us improve the MSVC docs. For a comprehensive guide to contributing to docs.microsoft.com, see the [Microsoft Docs contributor guide overview](https://docs.microsoft.com/contribute). For details on how to make a contribution to the MSVC documentation, see the [Contributing guide](CONTRIBUTING.md). +We welcome your contributions to help us improve the MSVC docs. For a comprehensive guide to contributing, see the [Microsoft Docs contributor guide](https://learn.microsoft.com/contribute). For details on how to make a contribution to the MSVC documentation, see our [Contributing guidance](CONTRIBUTING.md). -Several feature areas of MSVC have their own folders in this repository, such as `standard-library` for articles on the C++ Standard Library, `ide` for C++-specific articles on the Visual Studio interactive development environment (IDE), and so forth. The `/media` subfolder in each folder contains art files for the articles. The [Contributing guide](CONTRIBUTING.md) has more information. +Several feature areas of MSVC have their own folders in this repository, such as `standard-library` for articles on the C++ Standard Library, `ide` for C++-specific articles on the Visual Studio integrated development environment (IDE), and so forth. The `/media` subfolder in each folder contains art files for the articles. The [Contributing guide](CONTRIBUTING.md) has more information. ## Microsoft Open Source Code of Conduct diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000000..675ad2a215 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,41 @@ + + +## Security + +Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, such as [Microsoft](https://github.com/microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), and [our GitHub organizations](https://opensource.microsoft.com/). + +If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://aka.ms/opensource/security/definition), please report it to us as described below. + +## Reporting Security Issues + +**Please do not report security vulnerabilities through public GitHub issues.** + +Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://aka.ms/opensource/security/create-report). + +If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com). If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://aka.ms/opensource/security/pgpkey). + +You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://aka.ms/opensource/security/msrc). + +Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue: + + * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.) + * Full paths of source file(s) related to the manifestation of the issue + * The location of the affected source code (tag/branch/commit or direct URL) + * Any special configuration required to reproduce the issue + * Step-by-step instructions to reproduce the issue + * Proof-of-concept or exploit code (if possible) + * Impact of the issue, including how an attacker might exploit the issue + +This information will help us triage your report more quickly. + +If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our [Microsoft Bug Bounty Program](https://aka.ms/opensource/security/bounty) page for more details about our active programs. + +## Preferred Languages + +We prefer all communications to be in English. + +## Policy + +Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://aka.ms/opensource/security/cvd). + + diff --git a/ThirdPartyNotices b/ThirdPartyNotices index a0bd09d68f..faceb5a528 100644 --- a/ThirdPartyNotices +++ b/ThirdPartyNotices @@ -7,7 +7,7 @@ see the [LICENSE](LICENSE) file, and grant you a license to any code in the repo Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. -Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653. +Microsoft's general trademark guidelines can be found at https://go.microsoft.com/fwlink/?LinkID=254653. Privacy information can be found at https://privacy.microsoft.com/en-us/ diff --git a/docs/_breadcrumb/toc.yml b/docs/_breadcrumb/toc.yml index 08c2231e26..363d1dad6b 100644 --- a/docs/_breadcrumb/toc.yml +++ b/docs/_breadcrumb/toc.yml @@ -1,128 +1,3 @@ -- name: Docs - tocHref: / - topicHref: / - items: - - name: Microsoft C++, C, and Assembler - tocHref: /cpp/ - topicHref: /cpp/index - items: - - name: Compiler intrinsics and assembly language - tocHref: /cpp/intrinsics/ - topicHref: /cpp/intrinsics/index - items: - - name: Compiler intrinsics - tocHref: /cpp/intrinsics/ - topicHref: /cpp/intrinsics/compiler-intrinsics - - name: ARM and ARM64 assembler - tocHref: /cpp/assembler/arm/ - topicHref: /cpp/assembler/arm/arm-assembler-reference - - name: C/C++ x86 inline assembler - tocHref: /cpp/assembler/inline/ - topicHref: /cpp/assembler/inline/inline-assembler - - name: x86 and x64 assembler - tocHref: /cpp/assembler/masm/ - topicHref: /cpp/assembler/masm/microsoft-macro-assembler-reference - - name: ATL - tocHref: /cpp/atl/ - topicHref: /cpp/atl/atl-com-desktop-components - - name: ATL/MFC shared classes - tocHref: /cpp/atl-mfc-shared/ - topicHref: /cpp/atl-mfc-shared/atl-mfc-shared-classes - items: - - name: ATL/MFC reference - tocHref: /cpp/atl-mfc-shared/reference/ - topicHref: /cpp/atl-mfc-shared/reference/classes-shared-by-mfc-and-atl - - name: Build C/C++ projects - tocHref: /cpp/build/ - topicHref: /cpp/build/building-c-cpp-programs - items: - - name: Build reference - tocHref: /cpp/build/reference/ - topicHref: /cpp/build/reference/c-cpp-building-reference - - name: Build insights - tocHref: /cpp/build-insights/ - topicHref: /cpp/build-insights/index - - name: C language - tocHref: /cpp/c-language/ - topicHref: /cpp/c-language/index - - name: C runtime library - tocHref: /cpp/c-runtime-library/ - topicHref: /cpp/c-runtime-library/c-run-time-library-reference - items: - - name: UCRT reference - tocHref: /cpp/c-runtime-library/reference/ - topicHref: /cpp/c-runtime-library/reference/crt-alphabetical-function-reference - - name: Cloud and web - tocHref: /cpp/cloud/ - topicHref: /cpp/cloud/cloud-and-web-programming-in-visual-cpp - - name: Code analysis - tocHref: /cpp/code-quality/ - topicHref: /cpp/code-quality/index - - name: Code sanitizers - tocHref: /cpp/sanitizers/ - topicHref: /cpp/sanitizers/index - - name: C++ language - tocHref: /cpp/cpp/ - topicHref: /cpp/cpp/index - - name: C++/CX - tocHref: /cpp/cppcx/ - topicHref: /cpp/cppcx/visual-c-language-reference-c-cx - - name: Cross-platform mobile development - tocHref: /cpp/cross-platform/ - topicHref: /cpp/cross-platform/index - - name: Data access - tocHref: /cpp/data/ - topicHref: /cpp/data/data-access-in-cpp - items: - - name: OLEDB - tocHref: /cpp/data/oledb/ - topicHref: /cpp/data/oledb/ole-db-programming - - name: ODBC - tocHref: /cpp/data/odbc/ - topicHref: /cpp/data/odbc/open-database-connectivity-odbc - - name: C++/CLI for .NET - tocHref: /cpp/dotnet/ - topicHref: /cpp/dotnet/dotnet-programming-with-cpp-cli-visual-cpp - - name: Errors and warnings - tocHref: /cpp/error-messages/ - topicHref: /cpp/error-messages/compiler-errors-1/c-cpp-build-errors - - name: Edit, navigate, and refactor code - tocHref: /cpp/ide/ - topicHref: /cpp/ide/read-and-understand-code-cpp - - name: Linux - tocHref: /cpp/linux/ - topicHref: /cpp/linux/index - - name: Linux - tocHref: /cpp/build/configure-cmake-debugging-sessions - topicHref: /cpp/linux/index - - name: MFC - tocHref: /cpp/mfc/ - topicHref: /cpp/mfc/mfc-desktop-applications - items: - - name: MFC reference - tocHref: /cpp/mfc/reference/ - topicHref: /cpp/mfc/reference/mfc-classes - - name: Microsoft C/C++ - tocHref: /cpp/overview/ - topicHref: /cpp/overview/visual-cpp-in-visual-studio - - name: Parallel programming - tocHref: /cpp/parallel/ - topicHref: /cpp/parallel/parallel-programming-in-visual-cpp - - name: Porting and upgrading - tocHref: /cpp/porting/ - topicHref: /cpp/porting/visual-cpp-porting-and-upgrading-guide - - name: C/C++ preprocessor - tocHref: /cpp/preprocessor/ - topicHref: /cpp/preprocessor/c-cpp-preprocessor-reference - - name: Security - tocHref: /cpp/security/ - topicHref: /cpp/security/security-best-practices-for-cpp - - name: C++ standard library - tocHref: /cpp/standard-library/ - topicHref: /cpp/standard-library/cpp-standard-library-reference - - name: Text and strings - tocHref: /cpp/text/ - topicHref: /cpp/text/text-and-strings-in-visual-cpp - - name: Windows - tocHref: /cpp/windows/ - topicHref: /cpp/windows/overview-of-windows-programming-in-cpp +- name: C++, C, and Assembler + tocHref: /cpp/ + topicHref: /cpp/index diff --git a/docs/assembler/arm/arm-assembler-command-line-reference.md b/docs/assembler/arm/arm-assembler-command-line-reference.md index 527a475f65..6c79ceaf15 100644 --- a/docs/assembler/arm/arm-assembler-command-line-reference.md +++ b/docs/assembler/arm/arm-assembler-command-line-reference.md @@ -1,78 +1,119 @@ --- title: "ARM Assembler command-line reference" description: "Reference guide to the Microsoft ARM assembler command-line options." -ms.date: "02/09/2020" -ms.assetid: f7b89478-1ab5-4995-8cde-a805f0462c45 +ms.date: 05/09/2022 --- # ARM Assembler command-line reference -This article provides command-line information about the Microsoft ARM assembler, **armasm**. **armasm** assembles ARMv7 Thumb assembly language into the Microsoft implementation of the Common Object File Format (COFF). The linker can link COFF code objects produced by both the ARM assembler and the C compiler. It can link either together with object libraries created by the librarian. +The Microsoft ARM assemblers, **armasm** and **armasm64**, support several command-line options. By default, **armasm** assembles ARMv7 Thumb assembly language into the Microsoft implementation of the Common Object File Format (COFF). The **armasm64** assembler creates COFF object code for ARM64 and ARM64EC targets. The linker can link COFF code objects produced by both the ARM assembler and the C/C++ compiler. It can link either together with object libraries created by the librarian. ## Syntax > **`armasm`** [*options*] *source_file* *object_file*\ -> **`armasm`** [*options*] **`-o`** *object_file* *source_file* +> **`armasm`** [*options*] *source_file* + +> **`armasm64`** [*options*] *source_file* *object_file*\ +> **`armasm64`** [*options*] *source_file* ### Parameters *options*\ A combination of zero or more of the following options: +- **`-16`**\ + Available only in **armasm**. Assemble source as 16-bit Thumb instructions. This option is the default. + +- **`-32`**\ + Available only in **armasm**. Assemble source as 32-bit ARM instructions. + +- **`-coff_thumb2_only`**\ + Available only in **armasm**. Allow only Thumb-2 code. + +- **`-errorReport:`** *option*\ + This option is deprecated. In Windows Vista and later, error reporting is controlled by [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings. + - **`-errors`** *filename*\ - Redirect error and warning messages to *filename*. + **`-e`** *filename*\ + Redirect error and warning messages to *filename*. By default, these messages are sent to `stdout`. -- **`-i`** *dir*[**`;`**dir]\ - Add the specified directories to the include search path. +- **`-funcOverride:`** *function_name*\ + Available only in **armasm64**. Emit function overriding support for *function_name*. -- **`-predefine`** *directive*\ - Specify a SETA, SETL, or SETS directive to predefine a symbol.\ - Example: `armasm.exe -predefine "COUNT SETA 150" source.asm`\ - For more information, see the [ARM Compiler armasm Reference Guide](http://infocenter.arm.com/help/topic/com.arm.doc.dui0802b/index.html). +- **`-g`**\ + Generate debugging information. -- **`-nowarn`**\ - Disable all warning messages. +- **`-gh:SHA1`**\ + Use the SHA-1 cryptographic hash algorithm to generate a checksum of each source file in debug info. Overrides **`-gh:SHA256`**. -- **`-ignore`** *warning*\ - Disable the specified warning. For possible values, see the section about warnings. +- **`-gh:SHA256`**\ + Use the SHA-256 cryptographic hash algorithm to generate a checksum of each source file in debug info. This option is on by default in Visual Studio 2022 version 17.0 and later. + +- **`-guard:ehcont`**[**`-`**]\ + Generate a sorted list of the relative virtual addresses (RVA) of all the valid exception handling continuation targets for a binary. It's used at runtime for `NtContinue` and `SetThreadContext` instruction pointer validation. By default, **`-guard:ehcont`** is off and must be explicitly enabled. To explicitly disable this option, use **`-guard:ehcont-`**. This option is available in Visual Studio 2019 version 16.7 and later. The feature is supported for 64-bit processes on a 64-bit OS. - **`-help`**\ - Print the command-line help message. + **`-h`**\ + Print the command-line help message. + +- **`-i`** *dir*[**`;`** *dir*]\ + Add one or more specified directories to the include search path. Separate directories by using a semi-colon (`;`). + +- **`-ignore`** *warning_number*\ + Disable the specified warning number. For possible values, see [ARM Assembler diagnostic messages](arm-assembler-diagnostic-messages.md). + +- **`-list`** *list_file*\ + Create a detailed listing of the generated assembly language to *list_file*. The *list_file* parameter is optional. If it's omitted, the assembler appends *`.lst`* to the base name of *source_file* to create the listing file. - **`-machine`** *machine*\ - Specify the machine type to set in the PE header. Possible values for *machine* are:\ - **ARM**—Sets the machine type to IMAGE_FILE_MACHINE_ARMNT. This option is the default.\ - **THUMB**—Sets the machine type to IMAGE_FILE_MACHINE_THUMB. + Specify the machine type to set in the PE header. In **armasm**, possible values for *machine* are: + - **ARM**—Sets the machine type to `IMAGE_FILE_MACHINE_ARMNT`. This option is the default. + - **THUMB**—Sets the machine type to `IMAGE_FILE_MACHINE_THUMB`. -- **`-oldit`**\ - Generate ARMv7-style IT blocks. By default, ARMv8-compatible IT blocks are generated. + In **armasm64**, possible values are: + - **ARM64**—Sets the machine type to `IMAGE_FILE_MACHINE_ARM64`. This option is the default. + - **ARM64EC**—Sets the machine type to `IMAGE_FILE_MACHINE_ARM64EC`. -- **`-via`** *filename*\ - Read additional command-line arguments from *filename*. +- **`-noesc`**\ + **`-noe`**\ + Ignore C-style escaped special characters, such as `\n` or `\t`. -- **`-16`**\ - Assemble source as 16-bit Thumb instructions. This option is the default. +- **`-nologo`**\ + Suppress the copyright banner. -- **`-32`**\ - Assemble source as 32-bit ARM instructions. +- **`-nowarn`**\ + **`-now`**\ + Disable all warning messages. -- **`-g`**\ - Generate debugging information. +- **`-o`** *object_file*\ + Specify the name of the object (output) file. The **`-o`** option is optional; you can instead specify an object file name as the last element of the command line. -- **`-errorReport:`** *option*\ - This option is deprecated. Starting in Windows Vista, error reporting is controlled by [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings. +- **`-oldit`**\ + Available only in **armasm**. Generate ARMv7-style IT blocks. By default, ARMv8-compatible IT blocks are generated. + +- **`-predefine`** *directive*\ + **`-pd`** *directive*\ + Specify a SETA, SETL, or SETS directive to predefine a symbol.\ + Example: `armasm.exe -predefine "COUNT SETA 150" source.asm`\ + For more information, see the [ARM Compiler armasm Reference Guide](https://developer.arm.com/documentation/dui0802/latest/). + +- **`-sourcelink:`** *sourcelink_filename*\ + *sourcelink_filename* specifies a JSON-formatted configuration file that contains a simple mapping of local file paths to URLs for source files to display in the debugger. For more information on the format of this file, see [Source Link JSON Schema](https://github.com/dotnet/designs/blob/main/accepted/2020/diagnostics/source-link.md#source-link-json-schema). Source Link is a language- and source-control agnostic system for providing source debugging for binaries. Source Link is supported for native binaries starting in Visual Studio 2017 version 15.8. For an overview of Source Link, see [Source Link](https://github.com/dotnet/designs/blob/main/accepted/2020/diagnostics/source-link.md). For information on how to use Source Link in your projects, and how to generate the SourceLink file as part of your project, see [Using Source Link](https://github.com/dotnet/sourcelink#using-source-link-in-c-projects). + +- **`-via`** *filename*\ + Read extra command-line arguments from *filename*. *source_file*\ The name of the source file. *object_file*\ -The name of the object (output) file. +The last element of the command line can specify the name of the object (output) file. If it's omitted, and no **`-o`** option is specified, the assembler appends *`.obj`* to the base name of *source_file* to create the object file. ## Remarks The following example demonstrates how to use armasm in a typical scenario. First, use armasm to build an assembly language source (.asm) file to an object (.obj) file. Then, use the CL command-line C compiler to compile a source (.c) file, and also specify the linker option to link the ARM object file. ```cmd -armasm myasmcode.asm -o myasmcode.obj +armasm -o myasmcode.obj myasmcode.asm cl myccode.c /link myasmcode.obj ``` diff --git a/docs/assembler/arm/arm-assembler-diagnostic-messages.md b/docs/assembler/arm/arm-assembler-diagnostic-messages.md index 1215580189..ebe3253ac4 100644 --- a/docs/assembler/arm/arm-assembler-diagnostic-messages.md +++ b/docs/assembler/arm/arm-assembler-diagnostic-messages.md @@ -1,24 +1,24 @@ --- description: "Learn more about: ARM Assembler diagnostic messages" title: "ARM Assembler diagnostic messages" -ms.date: "08/30/2018" +ms.date: 05/09/2022 f1_keywords: ["A2193", "A2196", "A2202", "A2513", "A2557", "A4228", "A4508", "A4509"] helpviewer_keywords: ["A2193", "A2196", "A2202", "A2513", "A2557", "A4228", "A4508", "A4509"] ms.assetid: 52b38267-6023-4bdc-a0ef-863362f48eec --- # ARM Assembler diagnostic messages -The Microsoft ARM assembler (*armasm*) emits diagnostic warnings and errors when it encounters them. This article describes the most commonly-encountered messages. +The Microsoft ARM assemblers, **armasm** and **armasm64**, emit diagnostic warnings and errors when they encounter them. This article describes the most commonly encountered messages. ## Syntax -> filename**(**line-number**) :** \[**error**|**warning**] **A**number**:** *message* +> *filename* **(** *line-number* **) :** \[**error**|**warning**] **A** *number* **:** *message* ## Diagnostic messages - Errors > A2193: this instruction generates unpredictable behavior -The ARM architecture cannot guarantee what happens when this instruction is executed. For details about the well-defined forms of this instruction, consult the [ARM Architecture Reference Manual](https://go.microsoft.com/fwlink/p/?linkid=246464). +The ARM architecture can't guarantee what happens when this instruction is executed. For details about the well-defined forms of this instruction, consult the [ARM Architecture Reference Manual](https://go.microsoft.com/fwlink/p/?linkid=246464). ```asm ADD r0, r8, pc ; A2193: this instruction generates unpredictable behavior @@ -26,22 +26,22 @@ The ARM architecture cannot guarantee what happens when this instruction is exec > A2196: instruction cannot be encoded in 16 bits -The specified instruction cannot be encoded as a 16-bit Thumb instruction. Specify a 32-bit instruction, or rearrange code to bring the target label into the range of a 16-bit instruction. +The specified instruction can't be encoded as a 16-bit Thumb instruction. Specify a 32-bit instruction, or rearrange code to bring the target label into the range of a 16-bit instruction. The assembler may attempt to encode a branch in 16 bits and fail with this error, even though a 32-bit branch is encodable. You can solve this problem by using the `.W` specifier to explicitly mark the branch as 32-bit. ```asm - ADD.N r0, r1, r2 ; A2196: instruction cannot be encoded in 16 bits + ADD.N r0, r1, r2 ; A2196: instruction can't be encoded in 16 bits B.W label ; OK - B.N label ; A2196: instruction cannot be encoded in 16 bits + B.N label ; A2196: instruction can't be encoded in 16 bits SPACE 10000 label ``` > A2202: Pre-UAL instruction syntax not allowed in THUMB region -Thumb code must use the Unified Assembler Language (UAL) syntax. The old syntax is no longer accepted +Thumb code must use the Unified Assembler Language (UAL) syntax. The old syntax is no longer accepted ```asm ADDEQS r0, r1 ; A2202: Pre-UAL instruction syntax not allowed in THUMB region @@ -50,7 +50,7 @@ Thumb code must use the Unified Assembler Language (UAL) syntax. The old syntax > A2513: Rotation must be even -In ARM mode, there is an alternate syntax for specifying constants. Instead of writing `#`, you can write `#,#`, which represents the constant value that is obtained by rotating the value `` right by ``. When you use this syntax, you must make the value of `` even. +In ARM mode, there's an alternate syntax for specifying constants. Instead of writing `#`, you can write `#,#`, which represents the constant value that's obtained by rotating the value `` right by ``. When you use this syntax, you must make the value of `` even. ```asm MOV r0, #4, #2 ; OK @@ -59,7 +59,7 @@ In ARM mode, there is an alternate syntax for specifying constants. Instead of > A2557: Incorrect number of bytes to write back -On the NEON structure load and store instructions (`VLDn`, `VSTn`), there is an alternate syntax for specifying writeback to the base register. Instead of putting an exclamation point (!) after the address, you can specify an immediate value that indicates the offset to be added to the base register. If you use this syntax, you must specify the exact number of bytes that were loaded or stored by the instruction. +On the NEON structure load and store instructions (`VLDn`, `VSTn`), there's an alternate syntax for specifying writeback to the base register. Instead of putting an exclamation point (!) after the address, you can specify an immediate value that indicates the offset to be added to the base register. If you use this syntax, you must specify the exact number of bytes that were loaded or stored by the instruction. ```asm VLD1.8 {d0-d3}, [r0]! ; OK @@ -71,9 +71,9 @@ On the NEON structure load and store instructions (`VLDn`, `VSTn`), there is an > A4228: Alignment value exceeds AREA alignment; alignment not guaranteed -The alignment that is specified in an `ALIGN` directive is greater than the alignment of the enclosing `AREA`. As a result, the assembler cannot guarantee that the `ALIGN` directive will be honored. +The alignment that's specified in an `ALIGN` directive is greater than the alignment of the enclosing `AREA`. As a result, the assembler can't guarantee that the `ALIGN` directive will be honored. -To fix this, you can specify on the `AREA` directive an `ALIGN` attribute that is equal to or greater than the desired alignment. +To fix this warning, you can specify on the `AREA` directive an `ALIGN` attribute that's equal to or greater than the desired alignment. ```asm AREA |.myarea1| @@ -85,7 +85,7 @@ ALIGN 8 ; OK > A4508: Use of this rotated constant is deprecated -In ARM mode, there is an alternate syntax for specifying constants. Instead of writing `#`, you can write `#,#`, which represents the constant value that is obtained by rotating the value `` right by ``. In some contexts, ARM has deprecated the use of these rotated constants. In these cases, use the basic `#` syntax instead. +In ARM mode, there's an alternate syntax for specifying constants. Instead of writing `#`, you can write `#,#`, which represents the constant value that's obtained by rotating the value `` right by ``. In some contexts, ARM has deprecated the use of these rotated constants. In these cases, use the basic `#` syntax instead. ```asm ANDS r0, r0, #1 ; OK @@ -96,7 +96,7 @@ In ARM mode, there is an alternate syntax for specifying constants. Instead of This form of conditional instruction has been deprecated by ARM in the ARMv8 architecture. We recommend that you change the code to use conditional branches. To see which conditional instructions are still supported, consult the [ARM Architecture Reference Manual](https://go.microsoft.com/fwlink/p/?linkid=246464). -This warning is not emitted when the **-oldit** command-line switch is used. +This warning isn't emitted when the **`-oldit`** command-line switch is used. ```asm ADDEQ r0, r1, r8 ; A4509: This form of conditional instruction is deprecated diff --git a/docs/assembler/arm/arm-assembler-directives.md b/docs/assembler/arm/arm-assembler-directives.md index 8b2466a6eb..0dd3001b16 100644 --- a/docs/assembler/arm/arm-assembler-directives.md +++ b/docs/assembler/arm/arm-assembler-directives.md @@ -6,117 +6,117 @@ ms.assetid: 9cfa8896-ec10-4e77-855a-3135c40d7d2a --- # ARM Assembler Directives -For the most part, the Microsoft ARM assembler uses the ARM assembly language, which is documented in the [ARM Compiler armasm Reference Guide](http://infocenter.arm.com/help/topic/com.arm.doc.dui0802b/index.html). However, the Microsoft implementations of some assembly directives differ from the ARM assembly directives. This article explains the differences. +Generally, the Microsoft ARM assembler uses the ARM assembly language, which is documented in the [ARM Compiler armasm Reference Guide](https://developer.arm.com/documentation/dui0802/latest/). However, the Microsoft implementations of some assembly directives differ from the ARM assembly directives. This article explains the differences. ## Microsoft Implementations of ARM Assembly Directives -- AREA +- `AREA` The Microsoft ARM assembler supports these `AREA` attributes: `ALIGN`, `CODE`, `CODEALIGN`, `DATA`, `NOINIT`, `READONLY`, `READWRITE`, `THUMB`, `ARM`. - All except `THUMB` and `ARM` work as documented in the [ARM Compiler armasm Reference Guide](http://infocenter.arm.com/help/topic/com.arm.doc.dui0802b/index.html). + All except `THUMB` and `ARM` work as documented in the [ARM Compiler armasm Reference Guide](https://developer.arm.com/documentation/dui0802/latest/). In the Microsoft ARM assembler, `THUMB` indicates that a `CODE` section contains Thumb code, and is the default for `CODE` sections. `ARM` indicates that the section contains ARM code. -- ATTR +- `ATTR` Not supported. -- CODE16 +- `CODE16` - Not supported because it implies pre-UAL Thumb syntax, which the Microsoft ARM assembler does not allow. Use the `THUMB` directive instead, along with UAL syntax. + Not supported because it implies pre-UAL Thumb syntax, which the Microsoft ARM assembler doesn't allow. Use the `THUMB` directive instead, along with UAL syntax. -- COMMON +- `COMMON` - Specification of an alignment for the common region is not supported. + Specification of an alignment for the common region isn't supported. -- DCDO +- `DCDO` Not supported. - `DN`, `QN`, `SN` - Specification of a type or a lane on the register alias is not supported. + Specification of a type or a lane on the register alias isn't supported. -- ENTRY +- `ENTRY` Not supported. -- EQU +- `EQU` - Specification of a type for the defined symbol is not supported. + Specification of a type for the defined symbol isn't supported. - `EXPORT` and `GLOBAL` Specifies exports using this syntax: - > **EXPORT**|**GLOBAL** sym{**[**type**]**} + > **`EXPORT`**|**`GLOBAL`** *`symbol`*{*`[type]`*} - *sym* is the symbol to be exported. [*type*], if specified, can be either `[DATA]` to indicate that the symbol points to data or `[FUNC]` to indicate that the symbol points to code. `GLOBAL` is a synonym for `EXPORT`. + *`symbol`* is the symbol to be exported. *`[type]`*, if specified, can be either `[DATA]` to indicate that the symbol points to data or `[FUNC]` to indicate that the symbol points to code. `GLOBAL` is a synonym for `EXPORT`. -- EXPORTAS +- `EXPORTAS` Not supported. -- FRAME +- `FRAME` Not supported. - `FUNCTION` and `PROC` - Although the assembly syntax supports the specification of a custom calling convention on procedures by listing the registers that are caller-save and those that are callee-save, the Microsoft ARM assembler accepts the syntax but ignores the register lists. The debug information that is produced by the assembler supports only the default calling convention. + The assembly syntax lets you specify a custom calling convention on procedures: you list the registers that are caller-save, and the ones that are callee-save. However, while the Microsoft ARM assembler accepts the syntax, it ignores the register lists. The debug information that's produced by the assembler supports only the default calling convention. - `IMPORT` and `EXTERN` Specifies imports using this syntax: - > **IMPORT**|**EXTERN** *sym*{**, WEAK** *alias*{**, TYPE** *t*}} + > **`IMPORT`**|**`EXTERN`** *`symbol`*{**`, WEAK`** *`alias`*{**`, TYPE`** *`t`*}} - *sym* is the name of the symbol to be imported. + *`symbol`* is the name of the symbol to be imported. - If `WEAK` *alias* is specified, it indicates that *sym* is a weak external. If no definition for it is found at link time, then all references to it bind instead to *alias*. + If `WEAK` *`alias`* is specified, it indicates that *`symbol`* is a weak external. If a definition for it isn't found at link time, then all references to it bind instead to *`alias`*. - If `TYPE` *t* is specified, then *t* indicates how the linker should attempt to resolve *sym*. These values for *t* are possible: + If `TYPE` *`t`* is specified, then *`t`* indicates how the linker should attempt to resolve *`symbol`*. These values for *`t`* are possible: - |Value|Description| - |-|-| - |1|Do not perform a library search for *sym*| - |2|Perform a library search for *sym*| - |3|*sym* is an alias for *alias* (default)| + | Value | Description | + |--|--| + | 1 | Don't search libraries for *`symbol`*. | + | 2 | Search libraries for *`symbol`*. | + | 3 | *`symbol`* is an alias for *`alias`* (default). | - `EXTERN` is a synonym for `IMPORT`, except that *sym* is imported only if there are references to it in the current assembly. + `EXTERN` is a synonym for `IMPORT`, except that *`symbol`* is imported only if there are references to it in the current assembly. -- MACRO +- `MACRO` - The use of a variable to hold the condition code of a macro is not supported. Default values for macro parameters are not supported. + The use of a variable to hold the condition code of a macro isn't supported. Default values for macro parameters aren't supported. -- NOFP +- `NOFP` Not supported. - `OPT`, `TTL`, `SUBT` - Not supported because the Microsoft ARM assembler does not produce listings. + Not supported, because the Microsoft ARM assembler doesn't produce listings. -- PRESERVE8 +- `PRESERVE8` Not supported. -- RELOC +- `RELOC` - `RELOC n` can only follow an instruction or a data definition directive. There is no "anonymous symbol" that can be relocated. + `RELOC n` can only follow an instruction or a data definition directive. There's no "anonymous symbol" that can be relocated. -- REQUIRE +- `REQUIRE` Not supported. -- REQUIRE8 +- `REQUIRE8` Not supported. -- THUMBX +- `THUMBX` - Not supported because the Microsoft ARM assembler does not support the Thumb-2EE instruction set. + Not supported, because the Microsoft ARM assembler doesn't support the Thumb-2EE instruction set. ## See also diff --git a/docs/assembler/arm/arm-assembler-reference.md b/docs/assembler/arm/arm-assembler-reference.md index 3611d4cc0d..905ab3a72a 100644 --- a/docs/assembler/arm/arm-assembler-reference.md +++ b/docs/assembler/arm/arm-assembler-reference.md @@ -1,22 +1,25 @@ --- -description: "Learn more about: ARM Assembler Reference" -title: "ARM Assembler Reference" -ms.date: "08/28/2017" +description: "Learn more about: ARM Assembler reference" +title: "ARM Assembler reference" +ms.date: 05/09/2022 ms.assetid: f8a076cc-9627-4328-a34a-9c44f7a3aab1 --- -# ARM Assembler Reference +# ARM Assembler reference -The articles in this section of the documentation provide reference material for the Microsoft ARM assembler (armasm) and related tools. +The articles in this section of the documentation provide reference material for the Microsoft ARM assembler (**armasm** or **armasm64**) and related tools. -## Related Articles +## Related articles |Title|Description| |-----------|-----------------| -|[ARM Assembler Command-Line Reference](../../assembler/arm/arm-assembler-command-line-reference.md)|Describes the armasm command-line options.| -|[ARM Assembler Diagnostic Messages](../../assembler/arm/arm-assembler-diagnostic-messages.md)|Describes commonly encountered armasm warning and error messages.| -|[ARM Assembler Directives](../../assembler/arm/arm-assembler-directives.md)|Describes the ARM directives that are different in armasm.| +|[ARM Assembler command-line reference](../../assembler/arm/arm-assembler-command-line-reference.md)|Describes the Microsoft armasm and armasm64 command-line options.| +|[ARM Assembler diagnostic messages](../../assembler/arm/arm-assembler-diagnostic-messages.md)|Describes commonly seen armasm and armasm64 warning and error messages.| +|[ARM Assembler directives](../../assembler/arm/arm-assembler-directives.md)|Describes the ARM directives that are different in Microsoft armasm and armasm64.| |[ARM Architecture Reference Manual](https://developer.arm.com/search#q=ARM%20Architecture%20Reference%20Manual) on the ARM Developer website.|Choose the relevant manual for your ARM architecture. Each contains reference sections about ARM, Thumb, NEON, and VFP, and additional information about the ARM assembly language.| -|[ARM Compiler armasm User Guide](https://developer.arm.com/search#q=ARM%20Compiler%20armasm%20User%20Guide) on the ARM Developer website.|Choose a recent version to find up-to-date information about the ARM assembly language. **Note:** The "armasm" assembler that is referred to on the ARM Developer website is not the Microsoft armasm assembler that is included in Visual Studio and is documented in this section.| +|[ARM Compiler armasm User Guide](https://developer.arm.com/search#q=ARM%20Compiler%20armasm%20User%20Guide) on the ARM Developer website.|Choose a recent version to find up-to-date information about the ARM assembly language.| + +> [!IMPORTANT] +> The armasm assembler that the ARM Developer website describes isn't the same as the Microsoft armasm assembler that's included in Visual Studio and is documented in this section. ## See also diff --git a/docs/assembler/inline/asm.md b/docs/assembler/inline/asm.md index edc958759c..0aa4253ef7 100644 --- a/docs/assembler/inline/asm.md +++ b/docs/assembler/inline/asm.md @@ -10,20 +10,20 @@ ms.assetid: 77ff3bc9-a492-4b5e-85e1-fa4e414e79cd **Microsoft Specific** -The **`__asm`** keyword invokes the inline assembler and can appear wherever a C or C++ statement is legal. It cannot appear by itself. It must be followed by an assembly instruction, a group of instructions enclosed in braces, or, at the very least, an empty pair of braces. The term "**`__asm`** block" here refers to any instruction or group of instructions, whether or not in braces. +The **`__asm`** keyword invokes the inline assembler and can appear wherever a C or C++ statement is legal. It can't appear by itself. It must be followed by an assembly instruction, a group of instructions enclosed in braces, or, at minimum, an empty pair of braces. The term "**`__asm`** block" here refers to any instruction or group of instructions, whether or not in braces. > [!NOTE] > Visual C++ support for the Standard C++ **`asm`** keyword is limited to the fact that the compiler will not generate an error on the keyword. However, an **`asm`** block will not generate any meaningful code. Use **`__asm`** instead of **`asm`**. ## Grammar -*asm-block*:
-    **`__asm`** *assembly-instruction* **`;`**opt
-    **`__asm {`** *assembly-instruction-list* **`}`** **`;`**opt +*asm-block*:\ + **`__asm`** *assembly-instruction* **`;`**opt\ + **`__asm {`** *assembly-instruction-list* **`}`** **`;`**opt -*assembly-instruction-list*:
-    *assembly-instruction* **`;`**opt
-    *assembly-instruction* **`;`** *assembly-instruction-list* **`;`**opt +*assembly-instruction-list*:\ + *assembly-instruction* **`;`**opt\ + *assembly-instruction* **`;`** *assembly-instruction-list* **`;`**opt ## Remarks @@ -37,7 +37,7 @@ Before Visual Studio 2005, the instruction __asm int 3 ``` -did not cause native code to be generated when compiled with **/clr**; the compiler translated the instruction to a CLR break instruction. +didn't cause native code to be generated when compiled with **/clr**; the compiler translated the instruction to a CLR break instruction. `__asm int 3` now results in native code generation for the function. If you want a function to cause a break point in your code and if you want that function compiled to MSIL, use [__debugbreak](../../intrinsics/debugbreak.md). @@ -69,9 +69,9 @@ Because the **`__asm`** keyword is a statement separator, you can also put assem __asm mov al, 2 __asm mov dx, 0xD007 __asm out dx, al ``` -All three examples generate the same code, but the first style (enclosing the **`__asm`** block in braces) has some advantages. The braces clearly separate assembly code from C or C++ code and avoid needless repetition of the **`__asm`** keyword. Braces can also prevent ambiguities. If you want to put a C or C++ statement on the same line as an **`__asm`** block, you must enclose the block in braces. Without the braces, the compiler cannot tell where assembly code stops and C or C++ statements begin. Finally, because the text in braces has the same format as ordinary MASM text, you can easily cut and paste text from existing MASM source files. +All three examples generate the same code, but the first style (enclosing the **`__asm`** block in braces) has some advantages. The braces clearly separate assembly code from C or C++ code and avoid needless repetition of the **`__asm`** keyword. Braces can also prevent ambiguities. If you want to put a C or C++ statement on the same line as an **`__asm`** block, you must enclose the block in braces. Without the braces, the compiler can't tell where assembly code stops and C or C++ statements begin. Finally, because the text in braces has the same format as ordinary MASM text, you can easily cut and paste text from existing MASM source files. -Unlike braces in C and C++, the braces enclosing an **`__asm`** block don't affect variable scope. You can also nest **`__asm`** blocks; nesting does not affect variable scope. +Unlike braces in C and C++, the braces enclosing an **`__asm`** block don't affect variable scope. You can also nest **`__asm`** blocks; nesting doesn't affect variable scope. **END Microsoft Specific** diff --git a/docs/assembler/inline/data-directives-and-operators-in-inline-assembly.md b/docs/assembler/inline/data-directives-and-operators-in-inline-assembly.md index 94f04a2e7e..364313604c 100644 --- a/docs/assembler/inline/data-directives-and-operators-in-inline-assembly.md +++ b/docs/assembler/inline/data-directives-and-operators-in-inline-assembly.md @@ -1,18 +1,22 @@ --- description: "Learn more about: Data Directives and Operators in Inline Assembly" title: "Data Directives and Operators in Inline Assembly" -ms.date: "08/30/2018" +ms.date: 06/03/2022 helpviewer_keywords: ["data directives [C++]", "__asm keyword [C++], referencing limitations", "MASM (Microsoft Macro Assembler), directives", "directives [C++], MASM", "MASM (Microsoft Macro Assembler), structures", "operators [MASM]", "inline assembly, operators", "inline assembly, data directives", "MASM (Microsoft Macro Assembler), operators", "structures [C++], MASM"] ms.assetid: fb7410c7-156a-4131-bcfc-211aa70533e3 --- -# Data Directives and Operators in Inline Assembly +# Data directives and operators in inline assembly **Microsoft Specific** -Although an **`__asm`** block can reference C or C++ data types and objects, it cannot define data objects with MASM directives or operators. Specifically, you cannot use the definition directives **DB**, `DW`, **DD**, `DQ`, `DT`, and `DF`, or the operators `DUP` or **THIS**. MASM structures and records are also unavailable. The inline assembler doesn't accept the directives `STRUC`, `RECORD`, **WIDTH**, or **MASK**. +The inline assembler doesn't support all the data directives and operators available in MASM. + +## Remarks + +Although an **`__asm`** block can reference C or C++ data types and objects, it can't define data objects with MASM directives or operators. Specifically, you can't use the definition directives **`DB`**, **`DW`**, **`DD`**, **`DQ`**, **`DT`**, and **`DF`**, or the operators **`DUP`** or **`THIS`**. MASM structures and records are also unavailable. The inline assembler doesn't accept the directives **`STRUC`**, **`RECORD`**, **`WIDTH`**, or **`MASK`**. **END Microsoft Specific** ## See also -[Using Assembly Language in __asm Blocks](../../assembler/inline/using-assembly-language-in-asm-blocks.md)
+[Using Assembly Language in `__asm` blocks](../../assembler/inline/using-assembly-language-in-asm-blocks.md) diff --git a/docs/assembler/inline/defining-asm-blocks-as-c-macros.md b/docs/assembler/inline/defining-asm-blocks-as-c-macros.md index 0a5d4df127..2e5305a93c 100644 --- a/docs/assembler/inline/defining-asm-blocks-as-c-macros.md +++ b/docs/assembler/inline/defining-asm-blocks-as-c-macros.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Defining __asm Blocks as C Macros" title: "Defining __asm Blocks as C Macros" -ms.date: "08/30/2018" +description: "Learn more about: Defining __asm Blocks as C Macros" +ms.date: 08/30/2018 helpviewer_keywords: ["macros, __asm blocks", "Visual C, macros", "__asm keyword [C++], as C macros"] -ms.assetid: 677ba11c-21c8-4609-bba7-cd47312243b0 --- # Defining __asm Blocks as C Macros @@ -15,7 +14,7 @@ C macros offer a convenient way to insert assembly code into your source code, b - Put the **`__asm`** keyword in front of each assembly instruction. -- Use old-style C comments ( `/* comment */`) instead of assembly-style comments ( `; comment`) or single-line C comments ( `// comment`). +- Use old-style C comments (`/* comment */`) instead of assembly-style comments (`; comment`) or single-line C comments (`// comment`). To illustrate, the following example defines a simple macro: @@ -39,7 +38,7 @@ The third and fourth **`__asm`** keywords are needed as statement separators. Th The braces are essential as well. If you omit them, the compiler can be confused by C or C++ statements on the same line to the right of the macro invocation. Without the closing brace, the compiler cannot tell where assembly code stops, and it sees C or C++ statements after the **`__asm`** block as assembly instructions. -Assembly-style comments that start with a semicolon (**;**) continue to the end of the line. This causes problems in macros because the compiler ignores everything after the comment, all the way to the end of the logical line. The same is true of single-line C or C++ comments ( `// comment`). To prevent errors, use old-style C comments ( `/* comment */`) in **`__asm`** blocks defined as macros. +Assembly-style comments that start with a semicolon (**;**) continue to the end of the line. This causes problems in macros because the compiler ignores everything after the comment, all the way to the end of the logical line. The same is true of single-line C or C++ comments (`// comment`). To prevent errors, use old-style C comments (`/* comment */`) in **`__asm`** blocks defined as macros. An **`__asm`** block written as a C macro can take arguments. Unlike an ordinary C macro, however, an **`__asm`** macro cannot return a value. So you cannot use such macros in C or C++ expressions. diff --git a/docs/assembler/inline/intel-s-mmx-instruction-set.md b/docs/assembler/inline/intel-s-mmx-instruction-set.md index 6fee1181a2..eb492df28d 100644 --- a/docs/assembler/inline/intel-s-mmx-instruction-set.md +++ b/docs/assembler/inline/intel-s-mmx-instruction-set.md @@ -1,12 +1,12 @@ --- -description: "Learn more about: Intel's MMX Instruction Set" -title: "Intel's MMX Instruction Set" +description: "Learn more about: Intel's MMX Instruction Set" +title: "Intel's MMX Instruction Set" ms.date: "08/30/2018" ms.topic: "reference" helpviewer_keywords: ["MMX instruction set"] ms.assetid: 705deb2d-c3fd-4696-9e22-8bcf25866daf --- -# Intel's MMX Instruction Set +# Intel's MMX Instruction Set **Microsoft Specific** diff --git a/docs/assembler/inline/masm-macro-directives-in-inline-assembly.md b/docs/assembler/inline/masm-macro-directives-in-inline-assembly.md index b2d74c12ef..323a67036e 100644 --- a/docs/assembler/inline/masm-macro-directives-in-inline-assembly.md +++ b/docs/assembler/inline/masm-macro-directives-in-inline-assembly.md @@ -9,10 +9,10 @@ ms.assetid: 83643a09-1699-40a8-8ef2-13502bc4ac2c **Microsoft Specific** -The inline assembler is not a macro assembler. You cannot use MASM macro directives (**MACRO**, `REPT`, **IRC**, `IRP`, and `ENDM`) or macro operators (**<>**, **!**, **&**, `%`, and `.TYPE`). An **`__asm`** block can use C preprocessor directives, however. See [Using C or C++ in __asm Blocks](../../assembler/inline/using-c-or-cpp-in-asm-blocks.md) for more information. +The inline assembler isn't a macro assembler. You can't use MASM macro directives (`MACRO`, `REPT`, `IRC`, `IRP`, and `ENDM`) or macro operators (**`<>`**, **`!`**, **`&`**, **`%`**, and `.TYPE`). An **`__asm`** block can use C preprocessor directives, however. For more information, see [Using C or C++ in `__asm` blocks](../../assembler/inline/using-c-or-cpp-in-asm-blocks.md). **END Microsoft Specific** ## See also -[Using Assembly Language in __asm Blocks](../../assembler/inline/using-assembly-language-in-asm-blocks.md)
+[Using assembly language in `__asm` blocks](../../assembler/inline/using-assembly-language-in-asm-blocks.md) diff --git a/docs/assembler/inline/writing-functions-with-inline-assembly.md b/docs/assembler/inline/writing-functions-with-inline-assembly.md index adef94e4ad..65e852819f 100644 --- a/docs/assembler/inline/writing-functions-with-inline-assembly.md +++ b/docs/assembler/inline/writing-functions-with-inline-assembly.md @@ -1,39 +1,46 @@ --- -description: "Learn more about: Writing Functions with Inline Assembly" -title: "Writing Functions with Inline Assembly" -ms.date: "08/30/2018" +description: "Learn more about: Writing functions with inline assembly" +title: "Writing functions with inline assembly" +ms.date: 02/11/2022 helpviewer_keywords: ["functions [C++], inline assembly", "inline assembly [C++], writing functions", "assembler [C++], writing functions", "__asm keyword [C++], in functions"] ms.assetid: b5df8a04-fdc7-4622-8c9e-e4b618927497 --- -# Writing Functions with Inline Assembly +# Writing functions with inline assembly **Microsoft Specific** -If you write a function with inline assembly code, it's easy to pass arguments to the function and return a value from it. The following examples compare a function first written for a separate assembler and then rewritten for the inline assembler. The function, called `power2`, receives two parameters, multiplying the first parameter by 2 to the power of the second parameter. Written for a separate assembler, the function might look like this: +> [!NOTE] +> Inline assembly is only available for x86 targets. For similar functionality in x64 or ARM64 code, use [compiler intrinsics](../../intrinsics/compiler-intrinsics.md). + +If you write a function with inline assembly code, it's easy to pass arguments to the function and return a value from it. The following examples compare a function first written for a separate assembler and then rewritten for the inline assembler. The function, called `power2`, receives two parameters, multiplying the first parameter by 2 to the power of the second parameter. As a separate assembler file, the function might look like this: ```asm -; POWER.ASM -; Compute the power of an integer -; - PUBLIC _power2 -_TEXT SEGMENT WORD PUBLIC 'CODE' +; power2.asm +; x86 code for C interop +; Command line: ml /c /Cx /W3 /WX power2.asm + .686P + .XMM + .MODEL flat + +PUBLIC _power2 +; int power2(int num, int power); +; computes num x 2^power +_TEXT SEGMENT _power2 PROC - - push ebp ; Save EBP - mov ebp, esp ; Move ESP into EBP so we can refer - ; to arguments on the stack - mov eax, [ebp+4] ; Get first argument - mov ecx, [ebp+6] ; Get second argument - shl eax, cl ; EAX = EAX * ( 2 ^ CL ) - pop ebp ; Restore EBP - ret ; Return with sum in EAX - + push ebp ; save EBP + mov ebp, esp ; Move ESP into EBP so we can refer + ; to arguments on the stack + mov eax, [ebp+8] ; load first argument + mov ecx, [ebp+12] ; load second argument + shl eax, cl ; compute result in EAX + pop ebp ; restore EBP + ret _power2 ENDP _TEXT ENDS - END +END ``` -Since it's written for a separate assembler, the function requires a separate source file and assembly and link steps. C and C++ function arguments are usually passed on the stack, so this version of the `power2` function accesses its arguments by their positions on the stack. (Note that the **MODEL** directive, available in MASM and some other assemblers, also allows you to access stack arguments and local stack variables by name.) +Since it's written as a separate assembler file, the function requires separate assembly and link steps. C and C++ function arguments are usually passed on the stack, so this version of the `power2` function accesses its arguments by their positions on the stack. (The **`MODEL`** directive, available in MASM and some other assemblers, also allows you to access stack arguments and local stack variables by name.) ## Example @@ -67,10 +74,10 @@ int power2( int num, int power ) The inline version of the `power2` function refers to its arguments by name and appears in the same source file as the rest of the program. This version also requires fewer assembly instructions. -Because the inline version of `power2` doesn't execute a C **`return`** statement, it causes a harmless warning if you compile at warning level 2 or higher. The function does return a value, but the compiler cannot tell that in the absence of a **`return`** statement. You can use [#pragma warning](../../preprocessor/warning.md) to disable the generation of this warning. +Because the inline version of `power2` doesn't execute a C **`return`** statement, it causes a harmless warning if you compile at warning level 2 or higher. The function does return a value, but the compiler can't tell it does in the absence of a **`return`** statement. You can use [`#pragma warning`](../../preprocessor/warning.md) to disable the generation of this warning. **END Microsoft Specific** ## See also -[Using C or C++ in __asm Blocks](../../assembler/inline/using-c-or-cpp-in-asm-blocks.md)
+[Using C or C++ in `__asm` Blocks](../../assembler/inline/using-c-or-cpp-in-asm-blocks.md) diff --git a/docs/assembler/masm/dot-code.md b/docs/assembler/masm/dot-code.md index c8167f89f3..9bf447e91b 100644 --- a/docs/assembler/masm/dot-code.md +++ b/docs/assembler/masm/dot-code.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: .CODE" title: ".CODE" +description: "Learn more about: .CODE" ms.date: "12/17/2019" f1_keywords: [".CODE"] helpviewer_keywords: [".CODE directive"] -ms.assetid: 2b8c882c-c0d2-4fa3-8335-e6b12717a4f4 --- # .CODE -(32-bit MASM only.) When used with [.MODEL](dot-model.md), indicates the start of a code segment. +Indicates the start of a code segment. + +When using 32-bit MASM, this should be used along with [.MODEL](dot-model.md). ## Syntax > **.CODE** ⟦*name*⟧\ > ⟦ *segmentItem* ⟧...\ -> ⟦ *codesegmentnameId* **ENDS**;;⟧\ +> ⟦ *codesegmentnameId* **ENDS**;;⟧ ### Parameters diff --git a/docs/assembler/masm/dot-data.md b/docs/assembler/masm/dot-data.md index cf080270da..c36eb3fee1 100644 --- a/docs/assembler/masm/dot-data.md +++ b/docs/assembler/masm/dot-data.md @@ -8,7 +8,9 @@ ms.assetid: 32797935-9c79-46e0-bf6f-07d0c2bf1dc1 --- # .DATA - (32-bit MASM only.) When used with [.MODEL](dot-model.md), starts a near data segment for initialized data (segment name _DATA). +Indicates the start of a data segment. + +When using 32-bit MASM, this starts a near data segment for initialized data (segment name _DATA) and should be used along with [.MODEL](dot-model.md). ## Syntax diff --git a/docs/assembler/masm/dot-erridn.md b/docs/assembler/masm/dot-erridn.md index be62a1cf8e..35421fa294 100644 --- a/docs/assembler/masm/dot-erridn.md +++ b/docs/assembler/masm/dot-erridn.md @@ -1,23 +1,23 @@ --- -description: "Learn more about: .ERRIDN, .ERRIDNI" -title: ".ERRIDN, .ERRIDNI" +description: "Learn more about: `.ERRIDN`, `.ERRIDNI`" +title: "'.ERRIDN', '.ERRIDNI'" ms.date: "05/23/2019" f1_keywords: [".ERRIDN", ".ERRIDNI"] helpviewer_keywords: [".ERRIDN directive", ".ERRIDNI directive"] ms.assetid: 89507db3-7d40-4a5e-a378-24d30feda9d1 --- -# .ERRIDN, .ERRIDNI +# `.ERRIDN`, `.ERRIDNI` Generates an error if the text items are identical. ## Syntax -> **.ERRIDN** *textitem1*__,__ *textitem2* ⟦__,__ *message*⟧\ -> **.ERRIDNI** *textitem1*__,__ *textitem2* ⟦__,__ *message*⟧ +> **`.ERRIDN`** *textitem1*__,__ *textitem2* ⟦__,__ *message*⟧\ +> **`.ERRIDNI`** *textitem1*__,__ *textitem2* ⟦__,__ *message*⟧ ## Remarks -If **.ERRIDNI** is given, the comparison is case insensitive. +If **`.ERRIDNI`** is given, the comparison is case insensitive. ## See also diff --git a/docs/assembler/masm/dot-nolistif.md b/docs/assembler/masm/dot-nolistif.md index bb4996f2ad..37703a53fb 100644 --- a/docs/assembler/masm/dot-nolistif.md +++ b/docs/assembler/masm/dot-nolistif.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: .NOLISTIF" title: ".NOLISTIF" +description: "Learn more about: .NOLISTIF" ms.date: "12/16/2019" f1_keywords: [".NOLISTIF"] helpviewer_keywords: [".NOLISTIF directive"] -ms.assetid: 9243af7a-7221-4531-bbc3-281b6b292bfd --- # .NOLISTIF @@ -20,5 +19,5 @@ This is the default. Same as [.SFCOND](dot-sfcond.md). ## See also -[Directives reference](directives-reference.md) +[Directives reference](directives-reference.md)\ [MASM BNF Grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/dot-xmm.md b/docs/assembler/masm/dot-xmm.md index 72b1af9e0a..9c0eae78b0 100644 --- a/docs/assembler/masm/dot-xmm.md +++ b/docs/assembler/masm/dot-xmm.md @@ -8,7 +8,7 @@ ms.assetid: db3062b6-8b2f-469b-aa02-df6571eab3ba --- # .XMM (32-bit MASM) -Enables assembly of Internet Streaming SIMD Extension instructions. (32-bit MASM only.) +Enables assembly of Streaming SIMD Extension instructions. (32-bit MASM only.) ## Syntax diff --git a/docs/assembler/masm/extern-masm.md b/docs/assembler/masm/extern-masm.md index dc0325534e..d261390d68 100644 --- a/docs/assembler/masm/extern-masm.md +++ b/docs/assembler/masm/extern-masm.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: EXTERN" +description: "Learn more about the MASM directive: EXTERN" title: "EXTERN (MASM)" -ms.date: "12/06/2019" +ms.date: 1/10/2025 helpviewer_keywords: ["EXTERN directive"] -ms.assetid: 667d703d-3aaf-4139-a586-29bc5dab1aff --- # EXTERN @@ -17,7 +16,9 @@ Defines one or more external variables, labels, or symbols called *name* whose t The *language-type* argument is valid in 32-bit MASM only. -The *type* can be [ABS](operator-abs.md), which imports *name* as a constant. Same as [EXTRN](extrn.md). +The *type* can be [`ABS`](operator-abs.md), which imports *name* as a constant. Same as [`EXTRN`](extrn.md). + +The *type* can also be [`PROC`](proc.md), in which case *name* is treated as an external procedure. ## See also diff --git a/docs/assembler/masm/instruction-format.md b/docs/assembler/masm/instruction-format.md new file mode 100644 index 0000000000..ac653870b1 --- /dev/null +++ b/docs/assembler/masm/instruction-format.md @@ -0,0 +1,79 @@ +--- +description: Learn how instructions are formatted for translation by MASM. +title: "MASM instruction format" +ms.date: 09/21/2021 +helpviewer_keywords: ["MASM (Microsoft Macro Assembler), instruction reference", "instruction format", "instructions [MASM]"] +no-loc: ["VEX", "REP"] +--- +# MASM instruction format + +## Syntax + +Instructions are written in source code according to this syntax: + +> [*prefix*](#prefix) [*mnemonic*](#mnemonic) [*operand-list*](#operand-list) + +For information on instruction definitions, options, and encoding, see the [Processor Manufacturer Programming Manuals](../../assembler/masm/processor-manufacturer-programming-manuals.md). Some instructions and instruction options may not be supported by the Microsoft Macro Assembler. + +## Prefix + +You can prefix some instructions with keywords that set options for how the instruction is encoded. The **`REP`**, **`REPE`**, **`REPZ`**, **`REPNE`**, and **`REPNZ`** keywords are used with string instructions to do `memcpy` or `strlen` kinds of operations in a single instruction. The **`LOCK`** keyword makes certain operations on memory operands atomic. You can combine it with the **`XACQUIRE`** and **`XRELEASE`** keywords to do Hardware Lock Elision (HLE) on supported processors, which allows greater transactional parallelism in certain cases. + +The remaining prefixes control how AVX instructions are encoded. AVX instructions are encoded using a **`VEX`** prefix, which appears before the opcode. It takes the place of certain byte instruction prefixes and opcode lead-in bytes. Many AVX instructions are also AVX-512 instructions, which are encoded using an **`EVEX`** prefix that supports [more options](#avx-512-options). MASM tries to encode instructions as compactly as possible, but these keywords allow more control over which encoding to use with a particular instruction. They're also used to force generation of AVX instruction forms that were introduced after the corresponding AVX-512 instruction. For example, `vex vpdpbusd` specifies the AVX-VNNI form of the `VPDPBUSD` instructions rather than the AVX512-VNNI form. When an AVX instruction appears without an explicit prefix keyword, the encoding chosen depends on the current AVX encoding setting. The [`OPTION AVXENCODING`](option-avxencoding-masm.md) directive lets you change this setting. + +The **`VEX2`**, **`VEX3`**, **`VEX`**, and **`EVEX`** options are available in Visual Studio 2019 version 16.7 and later. + +| Keyword | Usage | +|--|--| +| **`REP`** | Repeat the string operation by the count in (E)CX. | +| **`REPE`**
**`REPZ`** | Repeat the string operation while the comparison is equal, limited by the count in (E)CX. | +| **`REPNE`**
**`REPNZ`** | Repeat the string operation while the comparison is not-equal, limited by the count in (E)CX. | +| **`LOCK`** | Perform the operation atomically on a memory operand. | +| **`XACQUIRE`** | Begin an HLE transaction, most often used with **`LOCK`** prefix. | +| **`XRELEASE`** | Complete an HLE transaction, most often used with **`LOCK`** prefix. | +| **`VEX`** | Encode an AVX instruction using a **`VEX`** prefix. | +| **`VEX2`** | Encode an AVX instruction using a 2-byte **`VEX`** prefix. | +| **`VEX3`** | Encode an AVX instruction using a 3-byte **`VEX`** prefix. | +| **`EVEX`** | Encode an AVX instruction using an **`EVEX`** prefix. | + +## Mnemonic + +The mnemonic identifies a particular instruction, which determines the prefixes and operand patterns that are allowed. + +## Operand list + +Most instructions use an operand list to specify the explicit source and destination operands to the instruction. The operand list may contain memory references, registers, and constant values. Each instruction allows only certain types of operands to appear at each position in the operand list. Except for the `MOVS` and `CMPS` instructions, only one of the operands may be a memory reference; all other operands must be register references or constants. + +## AVX-512 options + +Some AVX-512 instructions allow more options to be specified. These options are: masking, zero-masking, embedded broadcast, embedded rounding, and exception suppression. + +*Masking* allows an operation to be applied only to selected elements of a vector. This option is controlled by placing a mask register from `{k1}` to `{k7}` after the destination operand. If the mask register is followed by `{z}`, all non-selected elements of the destination are set to zero. This alternative is known as *zero-masking*. + +*Embedded Broadcast* allows a scalar value in memory to be applied to all elements of a vector. This option is enabled by adding the element size and the keyword `BCST` to the memory operand, which is similar to the use of `PTR` for normal memory references. + +*Embedded Rounding* controls the rounding mode for an individual floating-point instruction, without having to set and reset the global rounding mode. It's enabled by following the instruction with the rounding mode enclosed in braces. When enabled, it also suppresses all exceptions for only that instruction. Floating-point instructions that don't round can also suppress all exceptions using a similar option. + +```asm + ; Examples of AVX-512 options + vaddps xmm1 {k1}, xmm2, xmm3 ; merge-masking + vsubps ymm0 {k4}{z}, ymm1, ymm2 ; zero-masking + vmulps zmm0, zmm1, dword bcst scalar ; embedded broadcast + vdivps zmm0, zmm1, zmm2 {rz-sae} ; embedded rounding + vmaxss xmm1, xmm2, xmm3 {sae} ; suppress all exceptions +``` + +### Rounding modes + +| Mode | Effect | +|--|--| +| **`rn-sae`** | Round to nearest, ties to even, suppress all exceptions. | +| **`rz-sae`** | Round toward zero, suppress all exceptions. | +| **`rd-sae`** | Round down (toward negative infinity), suppress all exceptions. | +| **`ru-sae`** | Round up (toward positive infinity), suppress all exceptions. | +| **`sae`** | Suppress all exceptions (no rounding needed). | + +## See also + +[Microsoft Macro Assembler Reference](microsoft-macro-assembler-reference.md)
+[Processor Manufacturer Programming Manuals](../../assembler/masm/processor-manufacturer-programming-manuals.md)
diff --git a/docs/assembler/masm/masm-bnf-grammar.md b/docs/assembler/masm/masm-bnf-grammar.md index d725146caf..65eea98ce0 100644 --- a/docs/assembler/masm/masm-bnf-grammar.md +++ b/docs/assembler/masm/masm-bnf-grammar.md @@ -22,7 +22,7 @@ The BNF grammar allows recursive definitions. For example, the grammar uses *`qu   *`endOfLine`* | *`comment`* *`=Dir`*\ -  *`id`* = *`immExpr`* *`;;`* +  *`id`* **`=`** *`immExpr`* *`;;`* *`addOp`*\   **`+`** | **`-`** @@ -492,7 +492,7 @@ The BNF grammar allows recursive definitions. For example, the grammar uses *`qu   *`immExpr`*\   | *`string`*\   | **`?`**\ -  | *`constExpr`* **`DUP`** ( *`scalarInstList`* )\ +  | *`constExpr`* **`DUP`** **`(`** *`scalarInstList`* **`)`**\   | *`floatNumber`*\   | *`bcdConst`* @@ -591,7 +591,7 @@ The BNF grammar allows recursive definitions. For example, the grammar uses *`qu *`macroCall`*\   *`id`* *`macroArgList`* *`;;`*\ -  | *`id`* ( *`macroArgList`* ) +  | *`id`* **`(`** *`macroArgList`* **`)`** *`macroDir`*\   *`id`* **`MACRO`** ⟦ *`macroParmList`* ⟧ *`;;`*\ @@ -716,7 +716,7 @@ The BNF grammar allows recursive definitions. For example, the grammar uses *`qu   | **`OLDMACROS`** | **`NOOLDMACROS`**\   | **`OLDSTRUCTS`** | **`NOOLDSTRUCTS`**\   | **`PROC`** **`:`** *`oVisibility`*\ -  | **`PROLOGUE`** : *`macroId`*\ +  | **`PROLOGUE`** **`:`** *`macroId`*\   | **`READONLY`** | **`NOREADONLY`**\   | **`SCOPED`** | **`NOSCOPED`**\   | **`SEGMENT`** **`:`** *`segSize`*\ diff --git a/docs/assembler/masm/masm-for-x64-ml64-exe.md b/docs/assembler/masm/masm-for-x64-ml64-exe.md index 65d46bde80..840b002083 100644 --- a/docs/assembler/masm/masm-for-x64-ml64-exe.md +++ b/docs/assembler/masm/masm-for-x64-ml64-exe.md @@ -1,23 +1,22 @@ --- -description: "Learn more about: MASM for x64 (ml64.exe)" +description: "Learn more about: Microsoft Macro Assembler (MASM) for x64 (ml64.exe)" title: "MASM for x64 (ml64.exe)" -ms.date: "12/17/2019" +ms.date: 09/21/2021 helpviewer_keywords: ["ml64", "ml64.exe", "masm for x64"] -ms.assetid: 89059103-f372-4968-80ea-0c7f90bb9c91 --- # MASM for x64 (ml64.exe) -Visual Studio includes both 32-bit and 64-bit hosted versions of Microsoft Assembler (MASM) to target x64 code. Named ml64.exe, this is the assembler that accepts x64 assembler language. The MASM command-line tools are installed when you choose a C++ workload during Visual Studio installation. The MASM tools are not available as a separate download. For instructions on how to download and install a copy of Visual Studio, see [Install Visual Studio](/visualstudio/install/install-visual-studio). If you do not want to install the complete Visual Studio IDE, but only want the command-line tools, download the [Build Tools for Visual Studio](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019). +Visual Studio includes both 32-bit and 64-bit hosted versions of MASM (the Microsoft Macro Assembler) to target x64 code. Named ml64.exe, it's the assembler that accepts x64 assembly language. The MASM command-line tools are installed when you choose a C++ workload during Visual Studio installation. The MASM tools aren't available as a separate download. For instructions on how to download and install a copy of Visual Studio, see [Install Visual Studio](/visualstudio/install/install-visual-studio). If you only want the command-line tools, not the full IDE, download the [Build Tools for Visual Studio](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022). -To use MASM to build code for x64 targets on the command line, you must use a developer command prompt for x64 targets, which sets the required path and other environment variables. For information on how to start a developer command prompt, see [Build C/C++ code on the command line](../../build/building-on-the-command-line.md). +To use ml64.exe on the command line, start a developer command prompt for x64 targets. A developer command prompt sets the required path and other environment variables. For information on how to start a developer command prompt, see [Build C/C++ code on the command line](../../build/building-on-the-command-line.md). -For information on ml64.exe command line options, see [ML and ML64 Command-Line Reference](ml-and-ml64-command-line-reference.md). +For information on ml64.exe command-line options, see [ML and ML64 Command-Line Reference](ml-and-ml64-command-line-reference.md). -Inline assembler or use of the ASM keyword is not supported for x64 or ARM targets. To port your x86 code that uses inline assembler to x64 or ARM, you can convert your code to C++, use compiler intrinsics, or create assembler-language source files. The Microsoft C++ compiler supports intrinsics to allow you to use special-function instructions, for example, privileged, bit scan/test, interlocked, and so on, in as close to a cross-platform manner as possible. For information on available intrinsics, see [Compiler Intrinsics](../../intrinsics/compiler-intrinsics.md). +Inline assembler or use of the **`ASM`** keyword isn't supported for x64 or ARM64 targets. To port your x86 code that uses inline assembler to x64 or ARM64, you can convert your code to C++, use compiler intrinsics, or create assembler-language source files. The Microsoft C++ compiler supports intrinsics to allow you to use special-function instructions, for example, privileged, bit scan or test, interlocked, and so on, in as close to a cross-platform manner as possible. For information on available intrinsics, see [Compiler Intrinsics](../../intrinsics/compiler-intrinsics.md). ## Add an assembler-language file to a Visual Studio C++ project -The Visual Studio project system supports assembler-language files built by using MASM in your C++ projects. You can create x64 assembler-language source files and build them into object files by using MASM, which supports x64 fully. You can then link these object files to your C++ code built for x64 targets. This is one way to overcome the lack of an x64 inline assembler. +The Visual Studio project system supports assembler-language files built by using MASM in your C++ projects. MASM fully supports x64 assembler-language source files, and builds them into object files. You can then link these object files to your C++ code built for x64 targets. It's one way to overcome the lack of an x64 inline assembler. ### To add an assembler-language file to an existing Visual Studio C++ project @@ -27,29 +26,29 @@ The Visual Studio project system supports assembler-language files built by usin 1. On the menu bar, choose **Project**, **Add New Item**. -1. In the **Add New Item** dialog box, select **C++ file (.cpp)** in the center pane. In the **Name** edit control, enter a new file name that has a **.asm** extension instead of .cpp. Choose **Add** to add the file to your project and close the dialog box. +1. In the **Add New Item** dialog box, select **C++ file (.cpp)** in the center pane. In the **Name** edit control, enter a new file name that has a *`.asm`* extension instead of *`.cpp`*. Choose **Add** to add the file to your project and close the dialog box. -Create your assembler-language code in the .asm file you added. When you build your solution, the MASM assembler is invoked to assemble the .asm file into an object file that is then linked into your project. To make symbol access easier, declare your assembler functions as `extern "C"` in your C++ source code, rather than using the C++ name decoration conventions in your assembler-language source files. +Create your assembler-language code in the *`.asm`* file you added. When you build your solution, the MASM assembler is invoked to assemble the *`.asm`* file into an object file that is then linked into your project. To make symbol access easier, declare your assembler functions as `extern "C"` in your C++ source code, rather than using the C++ name decoration conventions in your assembler-language source files. ## ml64-Specific Directives You can use the following ml64-specific directives in your assembler-language source code that targets x64: -- [.ALLOCSTACK](dot-allocstack.md) +- [`.ALLOCSTACK`](dot-allocstack.md) -- [.ENDPROLOG](dot-endprolog.md) +- [`.ENDPROLOG`](dot-endprolog.md) -- [.PUSHFRAME](dot-pushframe.md) +- [`.PUSHFRAME`](dot-pushframe.md) -- [.PUSHREG](dot-pushreg.md) +- [`.PUSHREG`](dot-pushreg.md) -- [.SAVEREG](dot-savereg.md) +- [`.SAVEREG`](dot-savereg.md) -- [.SAVEXMM128](dot-savexmm128.md) +- [`.SAVEXMM128`](dot-savexmm128.md) -- [.SETFRAME](dot-setframe.md) +- [`.SETFRAME`](dot-setframe.md) -In addition, the [PROC](proc.md) directive has been updated for use with ml64.exe. +The [`PROC`](proc.md) directive has also been updated for use with ml64.exe. ## 32-Bit Address Mode (Address Size Override) @@ -63,7 +62,7 @@ prefetch [eax] movnti rax, QWORD PTR [r8d] ``` -MASM assumes that if a 32-bit displacement appears alone as a memory operand, 64-bit addressing is intended. There is currently no support for 32-bit addressing with such operands. +MASM assumes 64-bit addressing if a 32-bit displacement appears alone as a memory operand. There's currently no support for 32-bit addressing with such operands. Finally, mixing register sizes within a memory operand, as demonstrated in the following code, generates an error. diff --git a/docs/assembler/masm/microsoft-macro-assembler-reference.md b/docs/assembler/masm/microsoft-macro-assembler-reference.md index a0ffe150e9..1cf7f09461 100644 --- a/docs/assembler/masm/microsoft-macro-assembler-reference.md +++ b/docs/assembler/masm/microsoft-macro-assembler-reference.md @@ -1,21 +1,23 @@ --- description: "Learn more about: Microsoft Macro Assembler reference" title: "Microsoft Macro Assembler reference" -ms.date: "12/17/2019" +ms.date: 09/21/2021 helpviewer_keywords: ["MASM (Microsoft Macro Assembler), reference", "MASM (Microsoft Macro Assembler), overview", "MASM (Microsoft Macro Assembler)", "MASM (Microsoft Macro Assembler), documentation overview"] -ms.assetid: 1446d55f-e2e7-4fd1-a9b8-b15cf7d4e47c --- # Microsoft Macro Assembler reference -The Microsoft Macro Assembler (MASM) provides several advantages over inline assembly. MASM contains a macro language that has features such as looping, arithmetic, and text string processing. MASM also gives you greater control over the hardware because it supports the instruction sets of the 386, 486, and Pentium processors. By using MASM, you also can reduce time and memory overhead. +The Microsoft Macro Assembler (MASM) provides several advantages over inline assembly. MASM contains a macro language that has features such as looping, arithmetic, and string processing. MASM gives you greater control over the hardware. By using MASM, you also can reduce time and memory overhead in your code. ## In This Section -[ML and ML64 command-line option](ml-and-ml64-command-line-reference.md)\ -Describes the ML.exe and ML64.exe command-line options. +[ML and ML64 command-line options](ml-and-ml64-command-line-reference.md)\ +Describes the ML and ML64 command-line options. -[ML error messages](ml-error-messages.md)\ -Describes ML.exe fatal and nonfatal error messages and warnings. +[MASM for x64 (ml64.exe)](masm-for-x64-ml64-exe.md)\ +Information about how to create output files for x64. + +[Instruction Format](instruction-format.md)\ +Describes basic instruction format and instruction prefixes for MASM. [Directives reference](directives-reference.md)\ Provides links to articles that discuss the use of directives in MASM. @@ -26,14 +28,13 @@ Provides links to articles that discuss the use of symbols in MASM. [Operators Reference](operators-reference.md)\ Provides links to articles that discuss the use of operators in MASM. -[Processor Manufacturer Programming Manuals](processor-manufacturer-programming-manuals.md)\ -Provides links to websites that may contain programming information about processors that are not manufactured, sold, or supported by Microsoft. - -[MASM for x64 (ml64.exe)](masm-for-x64-ml64-exe.md)\ -Information about how to create output files for x64. +[ML error messages](ml-error-messages.md)\ +Describes fatal and nonfatal error messages and warnings. -[MASM BNF Grammar](masm-bnf-grammar.md) +[Processor Manufacturer Programming Manuals](processor-manufacturer-programming-manuals.md)\ +Provides links to programming information about processors not manufactured, sold, or supported by Microsoft. +[MASM BNF Grammar](masm-bnf-grammar.md)\ Formal BNF description of MASM for x64. ## Related Sections @@ -44,5 +45,5 @@ Provides links to different areas of the Visual Studio and Visual C++ documentat ## See also [Compiler Intrinsics](../../intrinsics/compiler-intrinsics.md)\ -[x86Intrinsics](../../intrinsics/x86-intrinsics-list.md)\ +[x86 Intrinsics](../../intrinsics/x86-intrinsics-list.md)\ [x64 (amd64) Intrinsics](../../intrinsics/x64-amd64-intrinsics-list.md) diff --git a/docs/assembler/masm/ml-and-ml64-command-line-reference.md b/docs/assembler/masm/ml-and-ml64-command-line-reference.md index a14b954932..e4ea469e36 100644 --- a/docs/assembler/masm/ml-and-ml64-command-line-reference.md +++ b/docs/assembler/masm/ml-and-ml64-command-line-reference.md @@ -1,10 +1,9 @@ --- title: "ML and ML64 command-line reference" description: "Reference guide to the Microsoft MASM ML and ML64 assembler command-line options." -ms.date: "02/09/2020" +ms.date: 7/3/2023 f1_keywords: ["ML"] -helpviewer_keywords: ["/W* MASM compiler option", "/c MASM compiler option", "/EP MASM compiler option", "/Fe MASM compiler option", "/Zp MASM compiler option", "/AT MASM compiler option", "/Zm MASM compiler option", "/Sf MASM compiler option", "/Sp MASM compiler option", "/w MASM compiler option", "/Fl MASM compiler option", "/coff MASM compiler option", "/St MASM compiler option", "/Cx MASM compiler option", "/Sl MASM compiler option", "/Cu MASM compiler option", "MASM (Microsoft Macro Assembler), ML command-line reference", "/FPi MASM compiler option", "/Zf MASM compiler option", "ML environment variable", "/Fr MASM compiler option", "/help MASM compiler option", "/Sa MASM compiler option", "/Zd MASM compiler option", "/I MASM compiler option", "/? MASM compiler option", "/Bl MASM compiler option", "/Fm MASM compiler option", "/Fo MASM compiler option", "command-line reference [ML]", "/Sn MASM compiler option", "/Gd MASM compiler option", "/D* MASM compiler option", "environment variables, ML", "/Gc MASM compiler option", "/F* MASM compiler option", "/Sc MASM compiler option", "/H MASM compiler option", "/Zs MASM compiler option", "/omf MASM compiler option", "/Sg MASM compiler option", "/Cp MASM compiler option", "/Zi MASM compiler option", "/nologo MASM compiler option", "/Sx MASM compiler option", "/WX MASM compiler option", "/Ss MASM compiler option", "command line, reference [ML]", "/Ta MASM compiler option"] -ms.assetid: 712623c6-f77e-47ea-a945-089e57c50b40 +helpviewer_keywords: ["/W* MASM compiler option", "/c MASM compiler option", "/EP MASM compiler option", "/Fe MASM compiler option", "/Zp MASM compiler option", "/AT MASM compiler option", "/Zm MASM compiler option", "/Sf MASM compiler option", "/Sp MASM compiler option", "/w MASM compiler option", "/Fl MASM compiler option", "/coff MASM compiler option", "/St MASM compiler option", "/Cx MASM compiler option", "/Sl MASM compiler option", "/Cu MASM compiler option", "MASM (Microsoft Macro Assembler), ML command-line reference", "/FPi MASM compiler option", "/Zf MASM compiler option", "ML environment variable", "/Fr MASM compiler option", "/help MASM compiler option", "/Sa MASM compiler option", "/Zd MASM compiler option", "/I MASM compiler option", "/? MASM compiler option", "/Bl MASM compiler option", "/Fm MASM compiler option", "/Fo MASM compiler option", "command-line reference [ML]", "/Sn MASM compiler option", "/Gd MASM compiler option", "/D* MASM compiler option", "environment variables, ML", "/Gc MASM compiler option", "/F* MASM compiler option", "/Sc MASM compiler option", "/H MASM compiler option", "/Zs MASM compiler option", "/omf MASM compiler option", "/quiet MASM compiler option", "/Sg MASM compiler option", "/Cp MASM compiler option", "/Zi MASM compiler option", "/nologo MASM compiler option", "/Sx MASM compiler option", "/WX MASM compiler option", "/Ss MASM compiler option", "command line, reference [ML]", "/Ta MASM compiler option"] --- # ML and ML64 command-line reference @@ -14,74 +13,77 @@ For more information on ml64.exe, see [MASM for x64 (ml64.exe)](masm-for-x64-ml6 ## Syntax -> ML \[*options*] *filename* \[ \[*options*] *filename*] +> **`ML`** \[*`options`*] *`filename`* \[ \[*`options`*] *`filename`*] > -> ML64 \[*options*] *filename* \[ \[*options*] *filename*] ... \[/link *link_options*] +> **`ML64`** \[*`options`*] *`filename`* \[ \[*`options`*] *`filename`*] ... \[**`/link`** *`link_options`*] ### Parameters -*options*\ -The options listed in the following table. - -|Option|Action| -|------------|------------| -|**/AT**|Enables tiny-memory-model support. Enables error messages for code constructs that violate the requirements for .com format files. This option isn't equivalent to the [.MODEL](dot-model.md) **TINY** directive.

Not available in ml64.exe.| -|**/Bl** *filename*|Selects an alternate linker.| -|**/c**|Assembles only. Does no linking.| -|**/coff**|Generates common object file format (COFF) type of object module. Required for Win32 assembly language development.

Not available in ml64.exe.| -|**/Cp**|Preserves case of all user identifiers.| -|**/Cu**|Maps all identifiers to upper case (default).

Not available in ml64.exe.| -|**/Cx**|Preserves case in public and extern symbols.| -|**/D** *symbol*⟦=*value*⟧|Defines a text macro with the given name. If *value* is missing, it's blank. Multiple tokens separated by spaces must be enclosed in quotation marks.| -|**/EP**|Generates a preprocessed source listing (sent to STDOUT). See **/Sf**.| -|**/ERRORREPORT** [ **NONE** | **PROMPT** | **QUEUE** | **SEND** ]| Deprecated. Error reporting is controlled by [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings. | -|**/F** *hexnum*|Sets stack size to *hexnum* bytes (the same as **/link /STACK**:*number*). The value must be expressed in hexadecimal notation. There must be a space between **/F** and *hexnum*.| -|**/Fe** *filename*|Names the executable file.| -|**/Fl**⟦*filename*⟧|Generates an assembled code listing. See **/Sf**.| -|**/Fm**⟦*filename*⟧|Creates a linker map file.| -|**/Fo** *filename*|Names an object file. For more information, see [Remarks](#remarks).| -|**/FPi**|Generates emulator fix-ups for floating-point arithmetic (mixed language only).

Not available in ml64.exe.| -|**/Fr**⟦*filename*⟧|Generates a source browser .sbr file.| -|**/FR**⟦*filename*⟧|Generates an extended form of a source browser .sbr file.| -|**/Gc**|Specifies use of FORTRAN- or Pascal-style function calling and naming conventions. Same as **OPTION LANGUAGE:PASCAL**.

Not available in ml64.exe.| -|**/Gd**|Specifies use of C-style function calling and naming conventions. Same as **OPTION LANGUAGE:C**.

Not available in ml64.exe.| -|**/GZ**|Specifies use of __stdcall function calling and naming conventions. Same as **OPTION LANGUAGE:STCALL**.

Not available in ml64.exe.| -|**/H** *number*|Restricts external names to number significant characters. The default is 31 characters.

Not available in ml64.exe.| -|**/help**|Calls QuickHelp for help on ML.| -|**/I** *pathname*|Sets path for include file. A maximum of 10 **/I** options is allowed.| -|**/nologo**|Suppresses messages for successful assembly.| -|**/omf**|Generates object module file format (OMF) type of object module. **/omf** implies **/c**; ML.exe doesn't support linking OMF objects.

Not available in ml64.exe.| -|**/Sa**|Turns on listing of all available information.| -|**/safeseh**|Marks the object as either containing no exception handlers or containing exception handlers that are all declared with [.SAFESEH](dot-safeseh.md).

Not available in ml64.exe.| -|**/Sf**|Adds first-pass listing to listing file.| -|**/Sl** *width*|Sets the line width of source listing in characters per line. Range is 60 to 255 or 0. Default is 0. Same as [PAGE](page.md) width.| -|**/Sn**|Turns off symbol table when producing a listing.| -|**/Sp** *length*|Sets the page length of source listing in lines per page. Range is 10 to 255 or 0. Default is 0. Same as [PAGE](page.md) length.| -|**/Ss** *text*|Specifies text for source listing. Same as [SUBTITLE](subtitle.md) text.| -|**/St** *text*|Specifies title for source listing. Same as [TITLE](title.md) text.| -|**/Sx**|Turns on false conditionals in listing.| -|**/Ta** *filename*|Assembles source file whose name doesn't end with the .asm extension.| -|**/w**|Same as **/W0/WX**.| -|**/W** *level*|Sets the warning level, where *level* = 0, 1, 2, or 3.| -|**/WX**|Returns an error code if warnings are generated.| -|**/X**|Ignore INCLUDE environment path.| -|**/Zd**|Generates line-number information in object file.| -|**/Zf**|Makes all symbols public.| -|**/Zi**|Generates CodeView information in object file.| -|**/Zm**|Enables**M510** option for maximum compatibility with MASM 5.1.

Not available in ml64.exe.| -|**/Zp**⟦*alignment*⟧|Packs structures on the specified byte boundary. The *alignment* can be 1, 2, or 4.| -|**/Zs**|Performs a syntax check only.| -|**/?**|Displays a summary of ML command-line syntax.| - -*filename*\ +*`options`*\ +The options listed in the following table: + +| Option | Action | +|--|--| +| **`/AT`** | Enables tiny-memory-model support. Enables error messages for code constructs that violate the requirements for *`.com`* format files. This option isn't equivalent to the [`.MODEL`](dot-model.md) **`TINY`** directive.
Not available in ml64.exe. | +| **`/Bl`** *`filename`* | Selects an alternate linker in *`filename`*. | +| **`/c`** | Assembles only. Does no linking. | +| **`/coff`** | Generates common object file format (COFF) type of object module. Required for Win32 assembly language development.
Not available in ml64.exe. | +| **`/Cp`** | Preserves case of all user identifiers. | +| **`/Cu`** | Maps all identifiers to upper case (default).
Not available in ml64.exe. | +| **`/Cx`** | Preserves case in public and extern symbols. | +| **`/D`** *`symbol`*⟦=*`value`*⟧ | Defines a text macro with the given name *`symbol`*. If *`value`* is missing, it's blank. Multiple tokens separated by spaces must be enclosed in quotation marks. | +| **`/EP`** | Generates a preprocessed source listing (sent to `STDOUT`). See **`/Sf`**. | +| **`/ERRORREPORT`** [ **`NONE`** \| **`PROMPT`** \| **`QUEUE`** \| **`SEND`** ] | Deprecated. Error reporting is controlled by [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings. | +| **`/F`** *`hexnum`* | Sets stack size to *`hexnum`* bytes (the same as **`/link /STACK:`**). The value must be expressed in hexadecimal notation. There must be a space between **`/F`** and *`hexnum`*. | +| **`/Fe`** *`filename`* | Names the executable file. | +| **`/Fl`**⟦*`filename`*⟧ | Generates an assembled code listing. See **/Sf**. | +| **`/Fm`**⟦*`filename`*⟧ | Creates a linker map file. | +| **`/Fo`** *`filename`* | Names an object file. For more information, see [Remarks](#remarks). | +| **`/FPi`** | Generates emulator fix-ups for floating-point arithmetic (mixed language only).
Not available in ml64.exe. | +| **`/Fr`**⟦*`filename`*⟧ | Generates a source browser *`.sbr`* file. | +| **`/FR`**⟦*`filename`*⟧ | Generates an extended form of a source browser *`.sbr`* file. | +| **`/Gc`** | Specifies use of FORTRAN- or Pascal-style conventions for function calls and names. Same as **`OPTION LANGUAGE:PASCAL`**.
Not available in ml64.exe. | +| **`/Gd`** | Specifies use of C-style conventions for function calls and names. Same as **`OPTION LANGUAGE:C`**.
Not available in ml64.exe. | +| **`/Gz`** | Specifies use of `__stdcall` conventions for function calls and names. Same as **`OPTION LANGUAGE:STDCALL`**.
Not available in ml64.exe. | +| **`/H`** *`number`* | Restricts external names to *`number`* significant characters. The default is 31 characters.
Not available in ml64.exe. | +| **`/help`** | Displays a summary of ML command-line syntax and options. | +| **`/I`** *`pathname`* | Sets path for include file. A maximum of 10 **`/I`** options is allowed. | +| **`/nologo`** | Suppresses messages for successful assembly. | +| **`/omf`** | Generates object module file format (OMF) type of object module. **`/omf`** implies **`/c`**. ML.exe doesn't support linking OMF objects.
Not available in ml64.exe. | +| **`/quiet`** | Suppresses 'Assembling' message. Available in Visual Studio 17.6 and later. | +| **`/Sa`** | Turns on listing of all available information. | +| **`/safeseh`** | Marks the object file: either it contains no exception handlers, or it contains exception handlers that are all declared with [`.SAFESEH`](dot-safeseh.md).
Not available in ml64.exe. | +| **`/Sf`** | Adds the first-pass listing to the listing file. | +| **`/Sl`** *`width`* | Sets the line width of source listing in characters per line to *`width`*. Range is 60-255 or 0. Default is 0. Same as [`PAGE`](page.md) *`width`*. | +| **`/Sn`** | Turns off symbol table when a listing is produced. | +| **`/Sp`** *`length`* | Sets the page length of source listing in lines per page to *`length`*. Range is 10-255 or 0. Default is 0. Same as [`PAGE`](page.md) *`length`*. | +| **`/Ss`** *`text`* | Specifies text for source listing. Same as [`SUBTITLE`](subtitle.md) text. | +| **`/St`** *`text`* | Specifies title for source listing. Same as [`TITLE`](title.md) text. | +| **`/Sx`** | Turns on false conditionals in listing. | +| **`/Ta`** *`filename`* | Assembles source file whose name doesn't end with the *`.asm`* extension. | +| **`/w`** | Same as **`/W0 /WX`**. | +| **`/W`** *`level`* | Sets the warning level, where *`level`* = 0, 1, 2, or 3. | +| **`/WX`** | If warnings are generated, returns an error code. | +| **`/X`** | Ignore `INCLUDE` environment path. | +| **`/Zd`** | Generates line-number information in object file. | +| **`/Zf`** | Makes all symbols public. | +| **`/ZH:MD5`** | Use MD5 for checksum in debug info. | +| **`/ZH:SHA_256`** | Use SHA256 for checksum in debug info (default in Visual Studio 2022 version 17.0 and later). | +| **`/Zi`** | Generates CodeView information in object file. | +| **`/Zm`** | Enables **`M510`** option for maximum compatibility with MASM 5.1.
Not available in ml64.exe. | +| **`/Zp`**⟦*`alignment`*⟧ | Packs structures on the specified byte boundary. The *`alignment`* can be 1, 2, 4, 8, or 16. | +| **`/Zs`** | Performs a syntax check only. | +| **`/?`** | Displays a summary of ML command-line syntax and options. | + +*`filename`*\ The name of the file. -*link_options*\ +*`link_options`*\ The link options. For more information, see [Linker options](../../build/reference/linker-options.md). ## Remarks -Some command-line options to ML and ML64 are placement-sensitive. For example, because ML and ML64 can accept several **/c** options, any corresponding **/Fo** options must be specified before **/c**. The following command-line example illustrates an object file specification for each assembly file specification: +Some command-line options to ML and ML64 are placement-sensitive. For example, because ML and ML64 can accept several **`/c`** options, any corresponding **`/Fo`** options must be specified before **`/c`**. The following command-line example illustrates an object file specification for each assembly file specification: ```cmd ml.exe /Fo a1.obj /c a.asm /Fo b1.obj /c b.asm @@ -89,13 +91,13 @@ ml.exe /Fo a1.obj /c a.asm /Fo b1.obj /c b.asm ## Environment Variables -|Variable|Description| -|--------------|-----------------| -|INCLUDE|Specifies search path for include files.| -|ML|Specifies default command-line options.| -|TMP|Specifies path for temporary files.| +| Variable | Description | +|--|--| +| `INCLUDE` | Specifies search path for include files. | +| `ML` | Specifies default command-line options. | +| `TMP` | Specifies path for temporary files. | ## See also -[ML Error Messages](ml-error-messages.md)\ -[Microsoft Macro Assembler Reference](microsoft-macro-assembler-reference.md) +[ML error messages](ml-error-messages.md)\ +[Microsoft Macro Assembler reference](microsoft-macro-assembler-reference.md) diff --git a/docs/assembler/masm/ml-error-messages.md b/docs/assembler/masm/ml-error-messages.md index fa05763b6c..60ef663335 100644 --- a/docs/assembler/masm/ml-error-messages.md +++ b/docs/assembler/masm/ml-error-messages.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Error Messages" title: "ML Error Messages" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["vc.errors.ml"] helpviewer_keywords: ["MASM (Microsoft Macro Assembler), ML error messages"] ms.assetid: e7e164b3-6d65-4b5b-8925-bfbebc043523 diff --git a/docs/assembler/masm/ml-fatal-error-a1000.md b/docs/assembler/masm/ml-fatal-error-a1000.md index 58b8730b20..64c18b9e37 100644 --- a/docs/assembler/masm/ml-fatal-error-a1000.md +++ b/docs/assembler/masm/ml-fatal-error-a1000.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Fatal Error A1000" title: "ML Fatal Error A1000" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A1000"] helpviewer_keywords: ["A1000"] ms.assetid: 4fc77a83-8796-4dcf-9c37-6395d635b817 diff --git a/docs/assembler/masm/ml-fatal-error-a1005.md b/docs/assembler/masm/ml-fatal-error-a1005.md index 8dbccfde31..26a5522b82 100644 --- a/docs/assembler/masm/ml-fatal-error-a1005.md +++ b/docs/assembler/masm/ml-fatal-error-a1005.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Fatal Error A1005" title: "ML Fatal Error A1005" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A1005"] helpviewer_keywords: ["A1005"] ms.assetid: 42c7a6c5-277d-417c-acc1-d84c370e8d24 diff --git a/docs/assembler/masm/ml-fatal-error-a1007.md b/docs/assembler/masm/ml-fatal-error-a1007.md index dddac87749..8f6c7940ef 100644 --- a/docs/assembler/masm/ml-fatal-error-a1007.md +++ b/docs/assembler/masm/ml-fatal-error-a1007.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Fatal Error A1007" title: "ML Fatal Error A1007" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A1007"] helpviewer_keywords: ["A1007"] ms.assetid: bcf9c826-beb3-4e93-91fe-1ffd34995fbf diff --git a/docs/assembler/masm/ml-fatal-error-a1008.md b/docs/assembler/masm/ml-fatal-error-a1008.md index 64c30f7b55..c18d2492c9 100644 --- a/docs/assembler/masm/ml-fatal-error-a1008.md +++ b/docs/assembler/masm/ml-fatal-error-a1008.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Fatal Error A1008" title: "ML Fatal Error A1008" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A1008"] helpviewer_keywords: ["A1008"] ms.assetid: fe592f9d-c37b-4cd8-a51d-e3c15ddcab83 diff --git a/docs/assembler/masm/ml-fatal-error-a1009.md b/docs/assembler/masm/ml-fatal-error-a1009.md index b3395c7b59..23fe9aee2c 100644 --- a/docs/assembler/masm/ml-fatal-error-a1009.md +++ b/docs/assembler/masm/ml-fatal-error-a1009.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Fatal Error A1009" title: "ML Fatal Error A1009" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A1009"] helpviewer_keywords: ["A1009"] ms.assetid: f7a962a6-4280-485e-95cb-2ab8922c66c2 diff --git a/docs/assembler/masm/ml-fatal-error-a1010.md b/docs/assembler/masm/ml-fatal-error-a1010.md index 7c0b1733fc..0229ad3136 100644 --- a/docs/assembler/masm/ml-fatal-error-a1010.md +++ b/docs/assembler/masm/ml-fatal-error-a1010.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Fatal Error A1010" title: "ML Fatal Error A1010" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A1010"] helpviewer_keywords: ["A1010"] ms.assetid: 9e0b5241-67f4-4740-8701-3b2d2d1ad9e4 diff --git a/docs/assembler/masm/ml-fatal-error-a1011.md b/docs/assembler/masm/ml-fatal-error-a1011.md index e64d7bef96..6a5e3ea920 100644 --- a/docs/assembler/masm/ml-fatal-error-a1011.md +++ b/docs/assembler/masm/ml-fatal-error-a1011.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Fatal Error A1011" title: "ML Fatal Error A1011" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A1011"] helpviewer_keywords: ["A1011"] ms.assetid: 7fbf092d-4189-4330-a884-dfa2268fc3dd diff --git a/docs/assembler/masm/ml-fatal-error-a1016.md b/docs/assembler/masm/ml-fatal-error-a1016.md index c0281f0d1c..193e1af425 100644 --- a/docs/assembler/masm/ml-fatal-error-a1016.md +++ b/docs/assembler/masm/ml-fatal-error-a1016.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Fatal Error A1016" title: "ML Fatal Error A1016" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A1016"] helpviewer_keywords: ["A1016"] ms.assetid: 440b3750-ba0b-44d8-b82d-d581f62c08b2 diff --git a/docs/assembler/masm/ml-fatal-error-a1017.md b/docs/assembler/masm/ml-fatal-error-a1017.md index 024e05953a..186314b280 100644 --- a/docs/assembler/masm/ml-fatal-error-a1017.md +++ b/docs/assembler/masm/ml-fatal-error-a1017.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Fatal Error A1017" title: "ML Fatal Error A1017" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A1017"] helpviewer_keywords: ["A1017"] ms.assetid: bef0b312-5431-4e5a-b637-c19919acf01b diff --git a/docs/assembler/masm/ml-nonfatal-error-a2004.md b/docs/assembler/masm/ml-nonfatal-error-a2004.md index c6b906e562..cb40f2e8d3 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2004.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2004.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2004" title: "ML Nonfatal Error A2004" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2004"] helpviewer_keywords: ["A2004"] ms.assetid: 74e219ba-4dec-467a-b121-18a76aa57230 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2006.md b/docs/assembler/masm/ml-nonfatal-error-a2006.md index 43c8f5a860..5eb17a38e6 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2006.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2006.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2006" title: "ML Nonfatal Error A2006" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2006"] helpviewer_keywords: ["A2006"] ms.assetid: b8a8f096-95df-42b5-85ed-d2530560a84c diff --git a/docs/assembler/masm/ml-nonfatal-error-a2008.md b/docs/assembler/masm/ml-nonfatal-error-a2008.md index fe1bb27488..b648e40ee5 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2008.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2008.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2008" title: "ML Nonfatal Error A2008" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2008"] helpviewer_keywords: ["A2008"] ms.assetid: ca24157f-c88a-4678-ae06-3bc3cd956001 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2010.md b/docs/assembler/masm/ml-nonfatal-error-a2010.md index 9b8e63a98d..0037f31377 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2010.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2010.md @@ -2,16 +2,18 @@ description: "Learn more about: ML Nonfatal Error A2010" title: "ML Nonfatal Error A2010" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2010"] helpviewer_keywords: ["A2010"] ms.assetid: 8bcd57f4-1e3f-421f-9ef8-e702daf57fcb --- # ML Nonfatal Error A2010 -**invalid type expression** +> **invalid type expression** -The operand to [THIS](operator-this.md) or [PTR](operator-ptr.md) was not a valid type expression. +## Remarks + +The operand to [`THIS`](operator-this.md) or [`PTR`](operator-ptr.md) wasn't a valid type expression. ## See also diff --git a/docs/assembler/masm/ml-nonfatal-error-a2019.md b/docs/assembler/masm/ml-nonfatal-error-a2019.md index ba6c9f21dd..90bd405bec 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2019.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2019.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2019" title: "ML Nonfatal Error A2019" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2019"] helpviewer_keywords: ["A2019"] ms.assetid: 7dff209b-6d91-4e39-88a3-5d6329bac537 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2022.md b/docs/assembler/masm/ml-nonfatal-error-a2022.md index df9fae2891..8751e3f61e 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2022.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2022.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2022" title: "ML Nonfatal Error A2022" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2022"] helpviewer_keywords: ["A2022"] ms.assetid: 3f4b1017-543e-4236-820f-61070ab58920 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2031.md b/docs/assembler/masm/ml-nonfatal-error-a2031.md index f82a717e43..ca2b604bdc 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2031.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2031.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2031" title: "ML Nonfatal Error A2031" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2031"] helpviewer_keywords: ["A2031"] ms.assetid: d5b11f58-4a00-42be-9062-8fa8728e6306 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2034.md b/docs/assembler/masm/ml-nonfatal-error-a2034.md index c1759d7f64..3f39de593f 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2034.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2034.md @@ -2,30 +2,32 @@ description: "Learn more about: ML Nonfatal Error A2034" title: "ML Nonfatal Error A2034" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2034"] helpviewer_keywords: ["A2034"] ms.assetid: 6438970c-0aee-4f14-a058-5fe47d0ee216 --- # ML Nonfatal Error A2034 -**must be in segment block** +> **must be in segment block** -One of the following was found outside of a segment block: +## Remarks + +The assembler found one of the following items outside of a segment block: - An instruction - A label definition -- A [THIS](operator-this.md) operator +- A [`THIS`](operator-this.md) operator -- A [$](dollar.md) operator +- A [`$`](dollar.md) operator - A procedure definition -- An [ALIGN](align-masm.md) directive +- An [`ALIGN`](align-masm.md) directive -- An [ORG](org.md) directive +- An [`ORG`](org.md) directive ## See also diff --git a/docs/assembler/masm/ml-nonfatal-error-a2037.md b/docs/assembler/masm/ml-nonfatal-error-a2037.md index 38416a396a..8f3aa5c882 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2037.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2037.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2037" title: "ML Nonfatal Error A2037" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2037"] helpviewer_keywords: ["A2037"] ms.assetid: e7fdb98b-3ce9-4e1f-99fc-1b1ea10b6961 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2038.md b/docs/assembler/masm/ml-nonfatal-error-a2038.md index e80aebd1bb..cc8d4dc964 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2038.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2038.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2038" title: "ML Nonfatal Error A2038" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2038"] helpviewer_keywords: ["A2038"] ms.assetid: 001bf60a-58ac-4654-97eb-b734f2999f8e diff --git a/docs/assembler/masm/ml-nonfatal-error-a2039.md b/docs/assembler/masm/ml-nonfatal-error-a2039.md index f281ad154f..055cb0540a 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2039.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2039.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2039" title: "ML Nonfatal Error A2039" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2039"] helpviewer_keywords: ["A2039"] ms.assetid: ad8cdaae-b20d-45f0-acb1-79880979c6b7 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2044.md b/docs/assembler/masm/ml-nonfatal-error-a2044.md index bd6b47e17f..0997887d02 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2044.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2044.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2044" title: "ML Nonfatal Error A2044" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2044"] helpviewer_keywords: ["A2044"] ms.assetid: 7cf144ac-408c-4e35-9a15-38656a4e87cd diff --git a/docs/assembler/masm/ml-nonfatal-error-a2047.md b/docs/assembler/masm/ml-nonfatal-error-a2047.md index 31611b75c2..6896fe8592 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2047.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2047.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2047" title: "ML Nonfatal Error A2047" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2047"] helpviewer_keywords: ["A2047"] ms.assetid: 7799f988-6c2e-4022-a447-c56b48473f0c diff --git a/docs/assembler/masm/ml-nonfatal-error-a2050.md b/docs/assembler/masm/ml-nonfatal-error-a2050.md index dba465efd8..924f38d3f9 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2050.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2050.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2050" title: "ML Nonfatal Error A2050" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2050"] helpviewer_keywords: ["A2050"] ms.assetid: 16f3a58f-4bde-48f1-b0e3-2ed9612780a5 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2054.md b/docs/assembler/masm/ml-nonfatal-error-a2054.md index d4b0d750d7..febf4f6c4e 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2054.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2054.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2054" title: "ML Nonfatal Error A2054" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2054"] helpviewer_keywords: ["A2054"] ms.assetid: 878a2ced-0b88-49e5-bea5-0a014efb08b6 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2055.md b/docs/assembler/masm/ml-nonfatal-error-a2055.md index 057ed4ca3b..54e57104a9 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2055.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2055.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2055" title: "ML Nonfatal Error A2055" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2055"] helpviewer_keywords: ["A2055"] ms.assetid: b4c3585f-6e55-4127-ba84-e68a41f1ada8 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2057.md b/docs/assembler/masm/ml-nonfatal-error-a2057.md index 39029959c4..98ba11536a 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2057.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2057.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2057" title: "ML Nonfatal Error A2057" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2057"] helpviewer_keywords: ["A2057"] ms.assetid: 13c47848-3f4d-4145-a00c-5418ff176ba3 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2059.md b/docs/assembler/masm/ml-nonfatal-error-a2059.md index aa648c9909..4f563d54ac 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2059.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2059.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2059" title: "ML Nonfatal Error A2059" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2059"] helpviewer_keywords: ["A2059"] ms.assetid: fadabbce-3054-4758-aeae-34d8540ce410 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2060.md b/docs/assembler/masm/ml-nonfatal-error-a2060.md index eb4c2bca21..3e74b86485 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2060.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2060.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2060" title: "ML Nonfatal Error A2060" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2060"] helpviewer_keywords: ["A2060"] ms.assetid: 435d5b32-9b4f-4f4e-8142-af0ce7676e89 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2063.md b/docs/assembler/masm/ml-nonfatal-error-a2063.md index ad369aba9e..2da91f339b 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2063.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2063.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2063" title: "ML Nonfatal Error A2063" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2063"] helpviewer_keywords: ["A2063"] ms.assetid: 12976b25-2159-4e0c-9df3-dcfac61091ee diff --git a/docs/assembler/masm/ml-nonfatal-error-a2064.md b/docs/assembler/masm/ml-nonfatal-error-a2064.md index 21bf975dca..ed06a37737 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2064.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2064.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2064" title: "ML Nonfatal Error A2064" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2064"] helpviewer_keywords: ["A2064"] ms.assetid: 553a5ec5-b404-4321-ab2c-b9ccec6471fc diff --git a/docs/assembler/masm/ml-nonfatal-error-a2065.md b/docs/assembler/masm/ml-nonfatal-error-a2065.md index 336fdc4b63..316f95333e 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2065.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2065.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2065" title: "ML Nonfatal Error A2065" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2065"] helpviewer_keywords: ["A2065"] ms.assetid: 836e46c7-461a-4abc-8d48-03952c5b25f4 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2066.md b/docs/assembler/masm/ml-nonfatal-error-a2066.md index 529b93d4f7..f1583f30b5 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2066.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2066.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2066" title: "ML Nonfatal Error A2066" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2066"] helpviewer_keywords: ["A2066"] ms.assetid: 58220fdf-fb8f-47fc-a36d-737867361185 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2069.md b/docs/assembler/masm/ml-nonfatal-error-a2069.md index 7403f746f1..5ebda337f1 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2069.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2069.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2069" title: "ML Nonfatal Error A2069" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2069"] helpviewer_keywords: ["A2069"] ms.assetid: 57dbf072-da61-4306-8d41-a4d9c97fec1a diff --git a/docs/assembler/masm/ml-nonfatal-error-a2070.md b/docs/assembler/masm/ml-nonfatal-error-a2070.md index 0ceafc257e..2267b0ccdd 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2070.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2070.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2070" title: "ML Nonfatal Error A2070" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2070"] helpviewer_keywords: ["A2070"] ms.assetid: f6025e2c-b142-426f-88c8-7160df4c1631 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2074.md b/docs/assembler/masm/ml-nonfatal-error-a2074.md index d3fd8fe842..50f575f954 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2074.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2074.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2074" title: "ML Nonfatal Error A2074" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2074"] helpviewer_keywords: ["A2074"] ms.assetid: d19600d8-785b-4afb-af77-9dbbeb6a1275 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2078.md b/docs/assembler/masm/ml-nonfatal-error-a2078.md index 636fed7832..0b287e79bd 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2078.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2078.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2078" title: "ML Nonfatal Error A2078" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2078"] helpviewer_keywords: ["A2078"] ms.assetid: 42ac48fd-ac7f-4e74-a11e-20181d443faf diff --git a/docs/assembler/masm/ml-nonfatal-error-a2079.md b/docs/assembler/masm/ml-nonfatal-error-a2079.md index cc2dd601f5..f04053fcc4 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2079.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2079.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2079" title: "ML Nonfatal Error A2079" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2079"] helpviewer_keywords: ["A2079"] ms.assetid: 87003fa1-ce71-4572-9efc-06a4404860ab diff --git a/docs/assembler/masm/ml-nonfatal-error-a2083.md b/docs/assembler/masm/ml-nonfatal-error-a2083.md index 6d5a9e0898..0e852033cd 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2083.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2083.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2083" title: "ML Nonfatal Error A2083" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2083"] helpviewer_keywords: ["A2083"] ms.assetid: d2715877-1702-44e5-ab8f-6ef1fb6069f1 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2085.md b/docs/assembler/masm/ml-nonfatal-error-a2085.md index 78664076a6..70def6928d 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2085.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2085.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2085" title: "ML Nonfatal Error A2085" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2085"] helpviewer_keywords: ["A2085"] ms.assetid: c2fef415-a32b-4249-896c-6d981fc6e327 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2096.md b/docs/assembler/masm/ml-nonfatal-error-a2096.md index 100cf67596..f670b73aca 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2096.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2096.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2096" title: "ML Nonfatal Error A2096" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2096"] helpviewer_keywords: ["A2096"] ms.assetid: bab0b5ee-b39f-4e44-a41a-3f949fab4297 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2097.md b/docs/assembler/masm/ml-nonfatal-error-a2097.md index 9f35dcdc76..abeea9f8f9 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2097.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2097.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2097" title: "ML Nonfatal Error A2097" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2097"] helpviewer_keywords: ["A2097"] ms.assetid: 52f6f1f8-4eb4-4264-8619-7b9ccb20c0c7 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2107.md b/docs/assembler/masm/ml-nonfatal-error-a2107.md index 5f26d5f2e6..0c7b3ad230 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2107.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2107.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2107" title: "ML Nonfatal Error A2107" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2107"] helpviewer_keywords: ["A2107"] ms.assetid: 0385b9f2-36df-4e30-a905-ab49bdc504d1 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2119.md b/docs/assembler/masm/ml-nonfatal-error-a2119.md index e487e73215..e19e92eb19 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2119.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2119.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2119" title: "ML Nonfatal Error A2119" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2119"] helpviewer_keywords: ["A2119"] ms.assetid: 4d4ee6da-3a58-495c-a1da-c3a405c4c18d diff --git a/docs/assembler/masm/ml-nonfatal-error-a2133.md b/docs/assembler/masm/ml-nonfatal-error-a2133.md index 69b444fba7..fa9872a213 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2133.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2133.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2133" title: "ML Nonfatal Error A2133" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2133"] helpviewer_keywords: ["A2133"] ms.assetid: 5ba50911-22c8-43b7-90e2-946fc612e05f diff --git a/docs/assembler/masm/ml-nonfatal-error-a2137.md b/docs/assembler/masm/ml-nonfatal-error-a2137.md index a06ef7e218..d9c908f94f 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2137.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2137.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2137" title: "ML Nonfatal Error A2137" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2137"] helpviewer_keywords: ["A2137"] ms.assetid: 913172e3-866e-49c3-9502-e49d1f0df4b0 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2189.md b/docs/assembler/masm/ml-nonfatal-error-a2189.md index 4b5ed1af16..2fca4c0dc4 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2189.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2189.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2189" title: "ML Nonfatal Error A2189" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2189"] helpviewer_keywords: ["A2189"] ms.assetid: 39649f39-57bc-4ceb-ab16-53f9b2a8d2d5 diff --git a/docs/assembler/masm/ml-nonfatal-error-a2206.md b/docs/assembler/masm/ml-nonfatal-error-a2206.md index 688342d02b..8a1264fe6c 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2206.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2206.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2206" title: "ML Nonfatal Error A2206" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2206"] helpviewer_keywords: ["A2206"] ms.assetid: 711846d0-5a09-4353-8857-60588c25526a diff --git a/docs/assembler/masm/ml-nonfatal-error-a2219.md b/docs/assembler/masm/ml-nonfatal-error-a2219.md index cd1936d6e5..7d6dc6b457 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2219.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2219.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Nonfatal Error A2219" title: "ML Nonfatal Error A2219" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A2219"] helpviewer_keywords: ["A2219"] ms.assetid: 5ebc2f40-e47e-4f8e-b7b9-960b9cfc9f6d @@ -13,7 +13,7 @@ ms.assetid: 5ebc2f40-e47e-4f8e-b7b9-960b9cfc9f6d ## Remarks -The operand for [.ALLOCSTACK](dot-allocstack.md) and [.SAVEREG](dot-savereg.md) must be a multiple of 8. The operand for [.SAVEXMM128](dot-savexmm128.md) and [.SETFRAME](dot-setframe.md) must be a multiple of 16. +The operand for [`.ALLOCSTACK`](dot-allocstack.md) and [`.SAVEREG`](dot-savereg.md) must be a multiple of 8. The operand for [`.SAVEXMM128`](dot-savexmm128.md) and [`.SETFRAME`](dot-setframe.md) must be a multiple of 16. ## See also diff --git a/docs/assembler/masm/ml-warning-a4004.md b/docs/assembler/masm/ml-warning-a4004.md index d1631f84d9..ee4e7df825 100644 --- a/docs/assembler/masm/ml-warning-a4004.md +++ b/docs/assembler/masm/ml-warning-a4004.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Warning A4004" title: "ML Warning A4004" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A4004"] helpviewer_keywords: ["A4004"] ms.assetid: f11b13c9-fa8d-49f2-b816-a6b7871c7261 diff --git a/docs/assembler/masm/ml-warning-a4012.md b/docs/assembler/masm/ml-warning-a4012.md index bb5ff35a53..52fe3645e8 100644 --- a/docs/assembler/masm/ml-warning-a4012.md +++ b/docs/assembler/masm/ml-warning-a4012.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Warning A4012" title: "ML Warning A4012" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A4012"] helpviewer_keywords: ["A4012"] ms.assetid: 842b1259-9679-4eeb-a02d-672a583a94e5 diff --git a/docs/assembler/masm/ml-warning-a4014.md b/docs/assembler/masm/ml-warning-a4014.md index 9550b5f042..dbecdeb23c 100644 --- a/docs/assembler/masm/ml-warning-a4014.md +++ b/docs/assembler/masm/ml-warning-a4014.md @@ -2,7 +2,7 @@ description: "Learn more about: ML Warning A4014" title: "ML Warning A4014" ms.date: "12/17/2019" -ms.custom: "error-reference" +ms.topic: error-reference f1_keywords: ["A4014"] helpviewer_keywords: ["A4014"] ms.assetid: 11bc8920-3255-4ac8-999a-b9ea9c15bc81 diff --git a/docs/assembler/masm/operator-bitwise-and.md b/docs/assembler/masm/operator-bitwise-and.md index 96562fa6a2..1f90291924 100644 --- a/docs/assembler/masm/operator-bitwise-and.md +++ b/docs/assembler/masm/operator-bitwise-and.md @@ -1,20 +1,20 @@ --- -description: "Learn more about: operator &" -title: "operator &" +description: "Learn more about: Microsoft Assembler (MASM) operator &" +title: "operator &" ms.date: "12/17/2019" f1_keywords: ["&", "operator &"] helpviewer_keywords: ["& operator, syntax", "AND operator", "& operator"] ms.assetid: f3c51a54-48ba-4b99-afed-5c45177bf694 --- -# operator & +# operator `&` (MASM) -Bitwise **AND**. Used only within [.IF](dot-if.md), [.WHILE](dot-while.md), or [.REPEAT](dot-repeat.md) blocks and evaluated at run time, not at assembly time. +Bitwise **AND**. Used only within [`.IF`](dot-if.md), [`.WHILE`](dot-while.md), or [`.REPEAT`](dot-repeat.md) blocks and evaluated at run time, not at assembly time. ## Syntax -> *expression1* **&** *expression2* +> *expression1* **`&`** *expression2* ## See also -[Operators Reference](operators-reference.md)\ -[MASM BNF Grammar](masm-bnf-grammar.md) +[Operators reference](operators-reference.md)\ +[MASM BNF grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/operator-double-quote.md b/docs/assembler/masm/operator-double-quote.md index 02d4c54bf0..48a8d3702a 100644 --- a/docs/assembler/masm/operator-double-quote.md +++ b/docs/assembler/masm/operator-double-quote.md @@ -1,12 +1,12 @@ --- -description: "Learn more about: operator " "" -title: "operator " "" +description: 'Learn more about: operator " "' +title: 'operator " "' ms.date: "12/17/2019" -f1_keywords: ["" "", "operator " ""] -helpviewer_keywords: ["" " operator", "operator " ""] +f1_keywords: ['operator " "'] +helpviewer_keywords: ['" " operator', 'operator " "'] ms.assetid: e96fd419-06d4-4989-b65b-7d3754f00f81 --- -# operator " " +# operator " " Treats "*text*" as a string. diff --git a/docs/assembler/masm/operator-greater-or-equal-masm-run-time.md b/docs/assembler/masm/operator-greater-or-equal-masm-run-time.md index 1c6a7f8f64..15190e74d6 100644 --- a/docs/assembler/masm/operator-greater-or-equal-masm-run-time.md +++ b/docs/assembler/masm/operator-greater-or-equal-masm-run-time.md @@ -1,20 +1,20 @@ --- -description: "Learn more about: operator >= (MASM Run Time)" -title: "operator >= (MASM Run Time)" +description: "Learn more about: Microsoft Assembler operator >= (MASM runtime)" +title: "MASM perator >= (runtime)" ms.date: "12/17/2019" f1_keywords: ["operator >="] helpviewer_keywords: [">= operator, comparing specific objects", "operator >="] ms.assetid: c7366d99-f7b8-4eb8-b5df-6dc74491b114 --- -# operator >= (MASM Run Time) +# operator `>=` (MASM runtime) -Is greater than or equal to. Used only within [.IF](dot-if.md), [.WHILE](dot-while.md), or [.REPEAT](dot-repeat.md) blocks and evaluated at run time, not at assembly time. +Greater than or equal to operator. Used only within [`.IF`](dot-if.md), [`.WHILE`](dot-while.md), or [`.REPEAT`](dot-repeat.md) blocks and evaluated at runtime, not at assembly time. ## Syntax -> *expression1* **>=** *expression2* +> *expression1* **`>=`** *expression2* ## See also [Operators reference](operators-reference.md)\ -[MASM BNF Grammar](masm-bnf-grammar.md) +[MASM BNF grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/operator-greater-than-masm-run-time.md b/docs/assembler/masm/operator-greater-than-masm-run-time.md index b1eab87a53..01d8c629e5 100644 --- a/docs/assembler/masm/operator-greater-than-masm-run-time.md +++ b/docs/assembler/masm/operator-greater-than-masm-run-time.md @@ -1,20 +1,20 @@ --- -description: "Learn more about: operator > (MASM Run Time)" -title: "operator > (MASM Run Time)" +description: "Learn more about: Microsoft Assembler (MASM) operator > (MASM runtime)" +title: "MASM operator > (runtime)" ms.date: "12/17/2019" f1_keywords: ["operator >"] helpviewer_keywords: ["> operator, comparing specific objects", "operator >"] ms.assetid: f2244900-8ddf-4e8c-9ab0-68b9118a6f75 --- -# operator > (MASM Run Time) +# operator `>` (MASM runtime) -Is greater than. Used only within [.IF](dot-if.md), [.WHILE](dot-while.md), or [.REPEAT](dot-repeat.md) blocks and evaluated at run time, not at assembly time. +Greater than operator. Used only within [`.IF`](dot-if.md), [`.WHILE`](dot-while.md), or [`.REPEAT`](dot-repeat.md) blocks and evaluated at run time, not at assembly time. ## Syntax -> *expression1* **>** *expression2* +> *expression1* **`>`** *expression2* ## See also [Operators reference](operators-reference.md)\ -[MASM BNF Grammar](masm-bnf-grammar.md) +[MASM BNF grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/operator-less-or-equal-masm-run-time.md b/docs/assembler/masm/operator-less-or-equal-masm-run-time.md index 58c2264cc6..e98485dacf 100644 --- a/docs/assembler/masm/operator-less-or-equal-masm-run-time.md +++ b/docs/assembler/masm/operator-less-or-equal-masm-run-time.md @@ -1,12 +1,12 @@ --- -description: "Learn more about: operator <= (MASM Run Time)" -title: "operator <= (MASM Run Time)" +description: "Learn more about: operator <= (MASM Run Time)" +title: "operator <= (MASM Run Time)" ms.date: "12/17/2019" f1_keywords: ["operator <="] helpviewer_keywords: ["operator <=", "<= operator, comparing specific objects"] ms.assetid: a5676804-07ef-40ab-8251-cde5b11ebdf9 --- -# operator <= (MASM Run Time) +# operator `<=` (MASM Run Time) Is less than or equal to. Used only within [.IF](dot-if.md), [.WHILE](dot-while.md), or [.REPEAT](dot-repeat.md) blocks and evaluated at run time, not at assembly time. diff --git a/docs/assembler/masm/operator-less-than-masm-run-time.md b/docs/assembler/masm/operator-less-than-masm-run-time.md index e6237046af..6db6b40771 100644 --- a/docs/assembler/masm/operator-less-than-masm-run-time.md +++ b/docs/assembler/masm/operator-less-than-masm-run-time.md @@ -1,12 +1,12 @@ --- -description: "Learn more about: operator < (MASM Run Time)" -title: "operator < (MASM Run Time)" +description: "Learn more about: operator < (MASM Run Time)" +title: "operator < (MASM Run Time)" ms.date: "12/17/2019" f1_keywords: ["operator <"] helpviewer_keywords: ["operator <", "< operator, comparing specific objects"] ms.assetid: 1d5fc8f1-a62f-4a3d-824d-619c6f421a04 --- -# operator < (MASM Run Time) +# operator `<` (MASM Run Time) Is less than. Used only within [.IF](dot-if.md), [.WHILE](dot-while.md), or [.REPEAT](dot-repeat.md) blocks and evaluated at run time, not at assembly time. diff --git a/docs/assembler/masm/operator-literal.md b/docs/assembler/masm/operator-literal.md index 80c0b5b63a..2eec929673 100644 --- a/docs/assembler/masm/operator-literal.md +++ b/docs/assembler/masm/operator-literal.md @@ -1,20 +1,20 @@ --- -description: "Learn more about: operator <>" -title: "operator <>" +description: "Learn more about: Microsoft Assembler (MASM) operator <>" +title: "MASM operator <>" ms.date: "12/17/2019" f1_keywords: ["<>", "operator <>"] helpviewer_keywords: ["operator <>", "<> operator"] ms.assetid: bc5acf43-df3e-499b-a3ed-1672cfa0d1ed --- -# operator <> +# MASM operator `<>` Treats *text* as a single literal element. ## Syntax -> __\<__*text*__>__ +> __`<`__*text*__`>`__ ## See also [Operators reference](operators-reference.md)\ -[MASM BNF Grammar](masm-bnf-grammar.md) +[MASM BNF grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/operator-logical-and-masm-run-time.md b/docs/assembler/masm/operator-logical-and-masm-run-time.md index 03dbeb11b7..856cde6ca7 100644 --- a/docs/assembler/masm/operator-logical-and-masm-run-time.md +++ b/docs/assembler/masm/operator-logical-and-masm-run-time.md @@ -1,20 +1,20 @@ --- -description: "Learn more about: operator && (MASM Run Time)" -title: "operator && (MASM Run Time)" +description: "Learn more about: Microsoft Assembler (MASM) operator && (MASM runtime)" +title: "operator && (MASM Run Time)" ms.date: "12/17/2019" f1_keywords: ["operator &&"] helpviewer_keywords: ["operator &&", "&& operator"] ms.assetid: 0a633a40-114c-48f5-88ff-09bc8d9b281a --- -# operator && (MASM Run Time) +# operator `&&` (MASM runtime) -Logical **AND**. Used only within [.IF](dot-if.md), [.WHILE](dot-while.md), or [.REPEAT](dot-repeat.md) blocks and evaluated at run time, not at assembly time. +Logical **AND**. Used only within [`.IF`](dot-if.md), [`.WHILE`](dot-while.md), or [`.REPEAT`](dot-repeat.md) blocks and evaluated at runtime, not at assembly time. ## Syntax -> *expression1* **&&** *expression2* +> *expression1* **`&&`** *expression2* ## See also [Operators reference](operators-reference.md)\ -[MASM BNF Grammar](masm-bnf-grammar.md) +[MASM BNF grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/operator-single-quote.md b/docs/assembler/masm/operator-single-quote.md index a862f760d8..a97eb12976 100644 --- a/docs/assembler/masm/operator-single-quote.md +++ b/docs/assembler/masm/operator-single-quote.md @@ -1,12 +1,12 @@ --- -description: "Learn more about: operator ' '" -title: "operator ' '" +description: "Learn more about: operator ' '" +title: "operator ' '" ms.date: "12/17/2019" f1_keywords: ["operator ' '", "' '"] helpviewer_keywords: ["operator ' '", "' ' operator"] ms.assetid: 62a5d993-3d9b-470d-ba8a-53d76afd29b1 --- -# operator ' ' +# operator ' ' Treats '*text*' as a string. diff --git a/docs/assembler/masm/operator-this.md b/docs/assembler/masm/operator-this.md index 7f6640e917..bf1695d145 100644 --- a/docs/assembler/masm/operator-this.md +++ b/docs/assembler/masm/operator-this.md @@ -6,13 +6,13 @@ f1_keywords: ["this", "operator THIS"] helpviewer_keywords: ["operator THIS", "THIS operator"] ms.assetid: d795aa0e-6c01-49b7-8c64-8ab111fd82d3 --- -# operator THIS +# operator `THIS` Returns an operand of specified *type* whose offset and segment values are equal to the current location counter value. ## Syntax -> **THIS** *type* +> **`THIS`** *type* ## See also diff --git a/docs/assembler/masm/option-avxencoding-masm.md b/docs/assembler/masm/option-avxencoding-masm.md new file mode 100644 index 0000000000..806b205a3b --- /dev/null +++ b/docs/assembler/masm/option-avxencoding-masm.md @@ -0,0 +1,84 @@ +--- +title: "OPTION AVXENCODING" +description: Describes how to select the preferred encoding of AVX instructions when more than one possibility will work +ms.date: "10/06/2020" +f1_keywords: ["avxencoding"] +helpviewer_keywords: ["OPTION AVXENCODING directive"] +--- +# OPTION AVXENCODING + +Selects the preferred encoding of AVX instructions. + +## Syntax + +> **`OPTION AVXENCODING:`** *preference* + +## Background + +Intel AVX and AVX-512 instructions are encoded differently from other Intel Architecture instructions. Rather than relying on instruction prefix bytes and opcode lead-in bytes to select an instruction, they use a single multi-byte prefix. This prefix can encode an additional register operand. In 64-bit mode, it also has bits to select registers 8 through 15 for the other operands, and a REX prefix isn't needed. + +Three different multi-byte prefixes are used. AVX instructions can be encoded with a 3-byte VEX prefix, where the second and third bytes help to select the specific operation executed. If some of the fields in the 3-byte VEX prefix have specific values, a 2-byte form of the VEX prefix can be used instead. Finally, some AVX instructions also have an AVX-512 form, which is encoded with a 4-byte EVEX prefix. The EVEX prefix has an additional fields to select 512-bit vector length and other options specific to AVX-512 instructions. + +Because some AVX instructions might be encoded in up to three different ways, there are rules to select which form to use. The **`OPTION AVXENCODING`** directive is used to select which set of rules to use. + +## Preferences + +| Preference | Encoding preference priority | +|--|--| +| **`PREFER_FIRST`** | Use first defined form if possible. | +| **`PREFER_VEX`** | Use `VEX` encoding in preference to `EVEX` encoding. | +| **`PREFER_VEX3`** | Use 3-byte `VEX` encoding in preference to `EVEX` encoding. | +| **`PREFER_EVEX`** | Use `EVEX` encoding in preference to `VEX` encoding. | +| **`NO_EVEX`** | Don't encode using `EVEX`. | + +The AVXENCODING order applies only if the instruction prefix form isn't specified for the instruction. If the instruction prefix is explicitly coded, it takes precedence over the **`AVXENCODING`** option. For example, `evex vpmaddwd` will use **`EVEX`**-prefixed `VPMADDWD` even if `OPTION AVXENCODING:no_EVEX` is specified. + +If an assembly source doesn't use `OPTION AVXENCODING` to select encoding preferences, the **`PREFER_FIRST`** rules are used by default. By these rules, the earliest instruction encodings added to Microsoft Macro Assembler (MASM) have precedence, and among those possibilities the encoding with the shortest prefix form is preferred. These rules ensure that code assembled by MASM still generates the same object code if new instruction forms are added later. + +The **`PREFER_VEX`** rules always tries to encode with a **`VEX`** prefix before trying to encode with **`EVEX`**. If possible, the 2-byte form of **`VEX`** is used instead of the 3-byte form. + +The **`PREFER_VEX3`** preference always tries to encode with a 3-byte **`VEX`** prefix before trying to encode with **`EVEX`**. The 2-byte form of **`VEX`** won't be used. + +The **`PREFER_EVEX`** option always tries to encode with an **`EVEX`** prefix, and only tries to use **`VEX`** if the instruction has no AVX-512 form. + +The **`NO_EVEX`** preference only tries to encode by using a **`VEX`** prefix. No AVX-512 instruction forms are allowed. This option lets you assemble code for use on platforms that have no AVX-512 support at all. + +The **`OPTION AVXENCODING`** directive is available in Visual Studio 2019 version 16.7 and later. + +### Example + +This example uses `VPDPBUSD` and `VPMADDWD` instructions to illustrate how the **`AVXENCODING`** option works. `VPDPBUSD` was first defined to be encoded only with `EVEX`, and was later extended with a VEX-encoded form for platforms without AVX-512 support, while `VPMADDWD` was AVX and extended to AVX-512. The listing output from assembling the example shows how changing the **`AVXENCODING`** mode affects the object code generated for each instruction. The prefix for each instruction ends at the "/". + +```asm + 00000000 62 F2 6D 08/ 50 vpdpbusd xmm1, xmm2, xmm3 + CB + 00000006 C5 E9/ F5 CB vpmaddwd xmm1, xmm2, xmm3 + + option avxencoding:no_EVEX + 0000000A C4 E2 69/ 50 CB vpdpbusd xmm1, xmm2, xmm3 + 0000000F C5 E9/ F5 CB vpmaddwd xmm1, xmm2, xmm3 + + option avxencoding:prefer_VEX + 00000013 C4 E2 69/ 50 CB vpdpbusd xmm1, xmm2, xmm3 + 00000018 C5 E9/ F5 CB vpmaddwd xmm1, xmm2, xmm3 + + option avxencoding:prefer_VEX3 + 0000001C C4 E2 69/ 50 CB vpdpbusd xmm1, xmm2, xmm3 + 00000021 C4 E1 69/ F5 CB vpmaddwd xmm1, xmm2, xmm3 + + option avxencoding:prefer_EVEX + 00000026 62 F2 6D 08/ 50 vpdpbusd xmm1, xmm2, xmm3 + CB + 0000002C 62 F1 6D 08/ F5 vpmaddwd xmm1, xmm2, xmm3 + CB + + option avxencoding:prefer_first + 00000032 62 F2 6D 08/ 50 vpdpbusd xmm1, xmm2, xmm3 + CB + 00000038 C5 E9/ F5 CB vpmaddwd xmm1, xmm2, xmm3 +``` + +## See also + +[Option (MASM)](option-masm.md)\ +[Directives Reference](directives-reference.md) diff --git a/docs/assembler/masm/option-language-masm.md b/docs/assembler/masm/option-language-masm.md new file mode 100644 index 0000000000..bc258e08f1 --- /dev/null +++ b/docs/assembler/masm/option-language-masm.md @@ -0,0 +1,40 @@ +--- +description: Learn more about the alternatives for the OPTION LANGUAGE directive +title: "OPTION LANGUAGE" +ms.date: 09/21/2021 +f1_keywords: ["language"] +helpviewer_keywords: ["OPTION LANGUAGE directive"] +--- +# `OPTION LANGUAGE` + +Sets default language features such as calling convention. + +## Syntax + +> **`OPTION LANGUAGE:`** *language* + +## Remarks + +Available languages include: + +:::row::: + :::column span=""::: + **`C`**\ + **`SYSCALL`**\ + :::column-end::: + :::column span=""::: + **`STDCALL`**\ + **`PASCAL`**\ + :::column-end::: + :::column span=""::: + **`FORTRAN`**\ + **`BASIC`** + :::column-end::: +:::row-end::: + +**`SYSCALL`**, **`PASCAL`**, **`FORTRAN`**, and **`BASIC`** aren't supported when used with [`.MODEL FLAT`](../../assembler/masm/dot-model.md). + +## See also + +[`OPTION` directive](../../assembler/masm/option-masm.md)\ +[Directives reference](../../assembler/masm/directives-reference.md) diff --git a/docs/assembler/masm/option-masm.md b/docs/assembler/masm/option-masm.md index 82ac5d3001..fd6b674619 100644 --- a/docs/assembler/masm/option-masm.md +++ b/docs/assembler/masm/option-masm.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: OPTION" +description: "Learn more about: the OPTION directive" title: "OPTION (MASM)" -ms.date: 07/15/2020 +ms.date: 09/21/2021 f1_keywords: ["option"] helpviewer_keywords: ["OPTION directive"] -ms.assetid: 8e10dabd-e36f-4586-ab01-ada96736b0bd --- -# OPTION +# `OPTION` Enables and disables features of the assembler. @@ -20,6 +19,7 @@ Available options include: :::row::: :::column span=""::: + [`AVXENCODING`](option-avxencoding-masm.md)\ **`CASEMAP`**\ **`DOTNAME`**\ **`NODOTNAME`**\ @@ -30,7 +30,7 @@ Available options include: :::column-end::: :::column span=""::: **`EXPR32`**\ - **`LANGUAGE`**\ + [`LANGUAGE`](option-language-masm.md)\ **`LJMP`**\ **`NOLJMP`**\ **`M510`**\ @@ -57,7 +57,7 @@ Available options include: :::column-end::: :::row-end::: -The syntax for LANGUAGE is **`OPTION LANGUAGE:`** _`x`_, where *`x`* is one of **`C`**, **`SYSCALL`**, **`STDCALL`**, **`PASCAL`**, **`FORTRAN`**, or **`BASIC`**. **`SYSCALL`**, **`PASCAL`**, **`FORTRAN`**, and **`BASIC`** are not supported with [`.MODEL`](dot-model.md) **`FLAT`**. +The **`OPTION AVXENCODING`** directive is available in Visual Studio 2019 version 16.7 and later. ## See also diff --git a/docs/assembler/masm/processor-manufacturer-programming-manuals.md b/docs/assembler/masm/processor-manufacturer-programming-manuals.md index 65d09ceed1..4774fdeeb7 100644 --- a/docs/assembler/masm/processor-manufacturer-programming-manuals.md +++ b/docs/assembler/masm/processor-manufacturer-programming-manuals.md @@ -1,22 +1,18 @@ --- description: "Learn more about: Processor manufacturer programming manuals" title: "Processor manufacturer programming manuals" -ms.date: "05/28/2020" -ms.assetid: 61844163-de2f-419a-808e-04de39dfdddf +ms.date: "12/6/2024" --- # Processor manufacturer programming manuals -This article provides links to websites that may contain programming info about processors that aren't made, sold, or supported by Microsoft. Microsoft doesn't control the websites or their content. +This article provides links to websites that may contain programming info about processors that Microsoft doesn't make, sell, or support. Microsoft doesn't control the websites or their content. ## Processor manufacturer websites -- [AMD Developer Guides, Manuals & ISA Documents](https://developer.amd.com/resources/developer-guides-manuals/) - -- [ARM Architecture Reference Manual](https://developer.arm.com/docs/ddi0487/fb) - -- [Intel 64 and IA-32 Architectures Software Developer Manuals](https://software.intel.com/articles/intel-sdm) - -- [Introduction to Intel Advanced Vector Extensions](https://software.intel.com/articles/introduction-to-intel-advanced-vector-extensions) +- [AMD Documentation Hub](https://www.amd.com/en/search/documentation/hub.html) +- [ARM Architecture Reference Manual](https://developer.arm.com/documentation/ddi0487/latest/) +- [Intel 64 and IA-32 Architectures Software Developer Manuals](https://www.intel.com/content/www/us/en/developer/articles/technical/intel-sdm.html) +- [Introducing Intel® Advanced Performance Extensions (Intel APX)](https://www.intel.com/content/www/us/en/developer/articles/technical/advanced-performance-extensions-apx.html) ## Remarks diff --git a/docs/assembler/masm/purge.md b/docs/assembler/masm/purge.md index 2e19584edd..9051b7fae9 100644 --- a/docs/assembler/masm/purge.md +++ b/docs/assembler/masm/purge.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: PURGE" title: "PURGE" +description: "Learn more about: PURGE" ms.date: "12/16/2019" f1_keywords: ["PURGE"] helpviewer_keywords: ["PURGE directive"] -ms.assetid: 1e7ec2bf-f123-4ff9-97de-28b512ade2f9 --- # PURGE @@ -16,5 +15,5 @@ Deletes the specified macros from memory. ## See also -[Directives reference](directives-reference.md) +[Directives reference](directives-reference.md)\ [MASM BNF Grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/subttl.md b/docs/assembler/masm/subttl.md index b59e41f224..a119b8eb14 100644 --- a/docs/assembler/masm/subttl.md +++ b/docs/assembler/masm/subttl.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: SUBTTL" title: "SUBTTL" +description: "Learn more about: SUBTTL" ms.date: "12/16/2019" f1_keywords: ["SUBTTL"] helpviewer_keywords: ["SUBTTL directive"] -ms.assetid: 927efadd-ec99-4de9-b64d-229bb2df3bf4 --- # SUBTTL @@ -16,5 +15,5 @@ See [SUBTITLE](subtitle.md). ## See also -[Directives reference](directives-reference.md) +[Directives reference](directives-reference.md)\ [MASM BNF Grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/toc.yml b/docs/assembler/toc.yml index 8e36b420cb..8f8b923a9c 100644 --- a/docs/assembler/toc.yml +++ b/docs/assembler/toc.yml @@ -1,3 +1,4 @@ +items: - name: Compiler intrinsics and assembly language href: ../intrinsics/index.yml - name: Compiler intrinsics @@ -78,6 +79,8 @@ href: ../assembler/masm/microsoft-macro-assembler-reference.md - name: MASM for x64 (ml64.exe) href: ../assembler/masm/masm-for-x64-ml64-exe.md + - name: MASM instruction format + href: ../assembler/masm/instruction-format.md - name: ML and ML64 command-line reference href: ../assembler/masm/ml-and-ml64-command-line-reference.md - name: Directives reference (MASM) @@ -300,6 +303,10 @@ href: ../assembler/masm/dot-nolistmacro.md - name: OPTION href: ../assembler/masm/option-masm.md + - name: OPTION AVXENCODING + href: ../assembler/masm/option-avxencoding-masm.md + - name: OPTION LANGUAGE + href: ../assembler/masm/option-language-masm.md - name: ORG href: ../assembler/masm/org.md - name: "%OUT" @@ -476,8 +483,6 @@ href: ../assembler/masm/at-version.md - name: "@WordSize" href: ../assembler/masm/at-wordsize.md - - name: Processor manufacturer programming manuals - href: ../assembler/masm/processor-manufacturer-programming-manuals.md - name: Operators reference items: - name: Operators reference @@ -746,5 +751,7 @@ href: ../assembler/masm/ml-warning-a4012.md - name: ML warning A4014 href: ../assembler/masm/ml-warning-a4014.md + - name: Processor manufacturer programming manuals + href: ../assembler/masm/processor-manufacturer-programming-manuals.md - name: MASM BNF grammar href: ../assembler/masm/masm-bnf-grammar.md diff --git a/docs/atl-mfc-shared/allocating-and-releasing-memory-for-a-bstr.md b/docs/atl-mfc-shared/allocating-and-releasing-memory-for-a-bstr.md index 8089fa46bc..b257f105f9 100644 --- a/docs/atl-mfc-shared/allocating-and-releasing-memory-for-a-bstr.md +++ b/docs/atl-mfc-shared/allocating-and-releasing-memory-for-a-bstr.md @@ -15,16 +15,16 @@ In general, the rules for allocating and releasing memory allocated for `BSTR`s - When you call into a function that expects a `BSTR` argument, you must allocate the memory for the `BSTR` before the call and release it afterwards. For example: [!code-cpp[NVC_ATLMFC_Utilities#192](../atl-mfc-shared/codesnippet/cpp/allocating-and-releasing-memory-for-a-bstr_1.cpp)] - +   [!code-cpp[NVC_ATLMFC_Utilities#193](../atl-mfc-shared/codesnippet/cpp/allocating-and-releasing-memory-for-a-bstr_2.cpp)] - When you call into a function that returns a `BSTR`, you must free the string yourself. For example: [!code-cpp[NVC_ATLMFC_Utilities#194](../atl-mfc-shared/codesnippet/cpp/allocating-and-releasing-memory-for-a-bstr_3.cpp)] - +   [!code-cpp[NVC_ATLMFC_Utilities#195](../atl-mfc-shared/codesnippet/cpp/allocating-and-releasing-memory-for-a-bstr_4.cpp)] -- When you implement a function that returns a `BSTR`, allocate the string but do not free it. The receiving the function releases the memory. For example: +- When you implement a function that returns a `BSTR`, allocate the string but do not free it. The receiving function releases the memory. For example: [!code-cpp[NVC_ATLMFC_Utilities#196](../atl-mfc-shared/codesnippet/cpp/allocating-and-releasing-memory-for-a-bstr_5.cpp)] diff --git a/docs/atl-mfc-shared/basic-cstring-operations.md b/docs/atl-mfc-shared/basic-cstring-operations.md index 41926fe05b..047bd978b2 100644 --- a/docs/atl-mfc-shared/basic-cstring-operations.md +++ b/docs/atl-mfc-shared/basic-cstring-operations.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Basic CString Operations" title: "Basic CString Operations" -ms.date: "11/04/2016" +description: "Learn more about: Basic CString Operations" +ms.date: 11/04/2016 helpviewer_keywords: ["CString objects, basic operations", "string literals, CString operations", "literal strings, CString operations", "CString objects", "string comparison, CString operations", "characters, accessing in CStrings"] -ms.assetid: 41db66b2-9427-4bb3-845a-9b6869159a6c --- # Basic CString Operations @@ -19,7 +18,7 @@ This topic explains the following basic [CString](../atl-mfc-shared/reference/cs - [Converting CString objects](#_core_converting_cstring_objects) -`Class CString` is based on class template [CStringT Class](../atl-mfc-shared/reference/cstringt-class.md). `CString` is a **`typedef`** of `CStringT`. More exactly, `CString` is a **`typedef`** of an *explicit specialization* of `CStringT`, which is a common way to use a class template to define a class. Similarly defined classes are `CStringA` and `CStringW`. +`Class CString` is based on class template [`CStringT`](../atl-mfc-shared/reference/cstringt-class.md). `CString` is a **`typedef`** of `CStringT`. More exactly, `CString` is a **`typedef`** of an *explicit specialization* of `CStringT`, which is a common way to use a class template to define a class. Similarly defined classes are `CStringA` and `CStringW`. `CString`, `CStringA`, and `CStringW` are defined in atlstr.h. `CStringT` is defined in cstringt.h. diff --git a/docs/atl-mfc-shared/codesnippet/CPP/cstringt-class_2.cpp b/docs/atl-mfc-shared/codesnippet/CPP/cstringt-class_2.cpp index 78a3ad3444..2b6ff825fd 100644 --- a/docs/atl-mfc-shared/codesnippet/CPP/cstringt-class_2.cpp +++ b/docs/atl-mfc-shared/codesnippet/CPP/cstringt-class_2.cpp @@ -1,5 +1,5 @@ // OEM character 252 on most IBM-compatible computers in - // Western countries/regions is superscript n, as in 2^n. + // many countries/regions is superscript n, as in 2^n. // Converting it to the ANSI English charset results in a // normal character 'n', which is the closest possible // representation. @@ -14,4 +14,4 @@ // the character's value truly was. str.AnsiToOem(); ASSERT(str[0] != 252); - ASSERT(str[0] == 'n'); \ No newline at end of file + ASSERT(str[0] == 'n'); diff --git a/docs/atl-mfc-shared/codesnippet/CPP/cstringt-class_37.cpp b/docs/atl-mfc-shared/codesnippet/CPP/cstringt-class_37.cpp index e9d808179a..2dd71b8650 100644 --- a/docs/atl-mfc-shared/codesnippet/CPP/cstringt-class_37.cpp +++ b/docs/atl-mfc-shared/codesnippet/CPP/cstringt-class_37.cpp @@ -3,6 +3,6 @@ // or an apostrophe('). // typedef CStringT>> CAtlString; - CAtlString src(_T("World Cup '98")); + CAtlString src(_T("abcdef")); _tprintf_s(_T("%s"),src.SpanExcluding(_T(";,.-'"))); \ No newline at end of file diff --git a/docs/atl-mfc-shared/cstring-argument-passing.md b/docs/atl-mfc-shared/cstring-argument-passing.md index 763e4adea7..68ff5addc6 100644 --- a/docs/atl-mfc-shared/cstring-argument-passing.md +++ b/docs/atl-mfc-shared/cstring-argument-passing.md @@ -3,21 +3,20 @@ description: "Learn more about: CString Argument Passing" title: "CString Argument Passing" ms.date: "11/04/2016" helpviewer_keywords: ["strings [C++], as function input/output", "argument passing [C++]", "arguments [C++], passing", "functions [C++], strings as input/output", "argument passing [C++], C strings", "passing arguments, C strings", "CString objects, passing arguments", "string arguments"] -ms.assetid: a67bebff-edf1-4cf4-bbff-d1cc6a901099 --- -# CString Argument Passing +# `CString` Argument Passing -This article explains how to pass [CString](../atl-mfc-shared/reference/cstringt-class.md) objects to functions and how to return `CString` objects from functions. +This article explains how to pass [`CString`](../atl-mfc-shared/reference/cstringt-class.md) objects to functions and how to return `CString` objects from functions. -## CString Argument-Passing Conventions +## `CString` Argument-Passing Conventions -When you define a class interface, you must determine the argument-passing convention for your member functions. There are some standard rules for passing and returning `CString` objects. If you follow the rules described in [Strings as Function Inputs](#_core_strings_as_function_inputs) and [Strings as Function Outputs](#_core_strings_as_function_outputs), you will have efficient, correct code. +When you define a class interface, you must determine the argument-passing convention for your member functions. There are some standard rules for passing and returning `CString` objects. If you follow the rules described in [Strings as Function Inputs](#_core_strings_as_function_inputs) and [Strings as Function Outputs](#_core_strings_as_function_outputs), you'll have efficient, correct code. ## Strings as Function Inputs -The most efficient and secure way to use a `CString` object in called functions is to pass a `CString` object to the function. Despite the name, a `CString` object does not store a string internally as a C-style string that has a null terminator. Instead, a `CString` object keeps careful track of the number of characters it has. Having `CString` provide a LPCTSTR pointer to a null-terminated string is a small amount of work that can become significant if your code has to do it constantly. The result is temporary because any change to the `CString` contents invalidates old copies of the LPCTSTR pointer. +The most efficient and secure way to use a `CString` object in called functions is to pass a `CString` object to the function. Despite the name, a `CString` object doesn't store a string internally as a C-style string that has a `NULL` terminator. Instead, a `CString` object keeps careful track of the number of characters it has. Having `CString` provide an `LPCTSTR` pointer to a `NULL`-terminated string is a small amount of work that can become significant if your code has to do it constantly. The result is temporary because any change to the `CString` contents invalidates old copies of the `LPCTSTR` pointer. -It does make sense in some cases to provide a C-style string. For example, there can be a situation where a called function is written in C and does not support objects. In this case, coerce the `CString` parameter to LPCTSTR, and the function will get a C-style null-terminated string. You can also go the other direction and create a `CString` object by using the `CString` constructor that accepts a C-style string parameter. +It does make sense in some cases to provide a C-style string. For example, there can be a situation where a called function is written in C and doesn't support objects. In this case, coerce the `CString` parameter to `LPCTSTR`, and the function will get a C-style `NULL`-terminated string. You can also go the other direction and create a `CString` object by using the `CString` constructor that accepts a C-style string parameter. If the string contents are to be changed by a function, declare the parameter as a nonconstant `CString` reference (`CString&`). @@ -26,7 +25,7 @@ If the string contents are to be changed by a function, declare the parameter as Typically you can return `CString` objects from functions because `CString` objects follow value semantics like primitive types. To return a read-only string, use a constant `CString` reference (`const CString&`). The following example illustrates the use of `CString` parameters and return types: [!code-cpp[NVC_ATLMFC_Utilities#197](../atl-mfc-shared/codesnippet/cpp/cstring-argument-passing_1.cpp)] - +  [!code-cpp[NVC_ATLMFC_Utilities#198](../atl-mfc-shared/codesnippet/cpp/cstring-argument-passing_2.cpp)] ## See also diff --git a/docs/atl-mfc-shared/cstring-operations-relating-to-c-style-strings.md b/docs/atl-mfc-shared/cstring-operations-relating-to-c-style-strings.md index 743ade9bc7..c90c04bf1b 100644 --- a/docs/atl-mfc-shared/cstring-operations-relating-to-c-style-strings.md +++ b/docs/atl-mfc-shared/cstring-operations-relating-to-c-style-strings.md @@ -5,9 +5,9 @@ ms.date: "11/04/2016" helpviewer_keywords: ["CString objects, basic operations", "MFC [C++], string handling class", "string conversion [C++], C-style strings", "strings [C++], string operations", "standard run-time library string functions", "null values, Null-terminated string conversion", "string functions", "strings [C++], in C", "string arguments", "C-style strings", "strings [C++], class CString", "casting CString objects"] ms.assetid: 5048de8a-5298-4891-b8a0-c554b5a3ac1b --- -# CString Operations Relating to C-Style Strings +# `CString` Operations Relating to C-Style Strings -A [CString](../atl-mfc-shared/using-cstring.md) object contains character string data. `CString` inherits the set of the [methods and operators](../atl-mfc-shared/reference/cstringt-class.md) that are defined in the class template [CStringT](../atl-mfc-shared/reference/cstringt-class.md) to work with string data. (`CString` is a **`typedef`** that specializes `CStringT` to work with the kind of character data that `CString` supports.) +A [`CString`](../atl-mfc-shared/using-cstring.md) object contains character string data. `CString` inherits the set of the [methods and operators](../atl-mfc-shared/reference/cstringt-class.md) that are defined in the class template [`CStringT`](../atl-mfc-shared/reference/cstringt-class.md) to work with string data. (`CString` is a **`typedef`** that specializes `CStringT` to work with the kind of character data that `CString` supports.) `CString` does not store character data internally as a C-style null-terminated string. Instead, `CString` tracks the length of character data so that it can more securely watch the data and the space it requires. @@ -17,15 +17,15 @@ A [CString](../atl-mfc-shared/using-cstring.md) object contains character string - [Working with standard run-time library string functions](#_core_working_with_standard_run.2d.time_library_string_functions) -- [Modifying CString contents directly](#_core_modifying_cstring_contents_directly) +- [Modifying `CString` contents directly](#_core_modifying_cstring_contents_directly) -- [Using CString objects with variable argument functions](#_core_using_cstring_objects_with_variable_argument_functions) +- [Using `CString` objects with variable argument functions](#_core_using_cstring_objects_with_variable_argument_functions) -- [Specifying CString formal parameters](#_core_specifying_cstring_formal_parameters) +- [Specifying `CString` formal parameters](#_core_specifying_cstring_formal_parameters) -## Using CString as a C-Style Null-Terminated String +## Using `CString` as a C-Style Null-Terminated String -To use a `CString` object as a C-style string, cast the object to LPCTSTR. In the following example, the `CString` returns a pointer to a read-only C-style null-terminated string. The `strcpy` function puts a copy of the C-style string in the variable `myString`. +To use a `CString` object as a C-style string, cast the object to `LPCTSTR`. In the following example, the `CString` returns a pointer to a read-only C-style null-terminated string. The `strcpy` function puts a copy of the C-style string in the variable `myString`. ```cpp CString aCString = "A string"; @@ -33,7 +33,7 @@ char myString[256]; strcpy(myString, (LPCTSTR)aCString); ``` -You can use `CString` methods, for example, `SetAt`, to modify individual characters in the string object. However, the LPCTSTR pointer is temporary and becomes invalid when any change is made to `CString`. The `CString` can also go out of scope and be automatically deleted. We recommend that you get a fresh LPCTSTR pointer of a `CString` object every time that you use one. +You can use `CString` methods, for example, `SetAt`, to modify individual characters in the string object. However, the `LPCTSTR` pointer is temporary and becomes invalid when any change is made to `CString`. The `CString` can also go out of scope and be automatically deleted. We recommend that you get a fresh `LPCTSTR` pointer of a `CString` object every time that you use one. Sometimes you may require a copy of `CString` data to modify directly. Use the more secured function `strcpy_s` (or the Unicode/MBCS-portable `_tcscpy_s`) to copy the `CString` object into a separate buffer. This is where characters can be safely modified, as shown by the following example. @@ -46,9 +46,9 @@ Sometimes you may require a copy of `CString` data to modify directly. Use the m You should be able to find a `CString` method to perform any string operation for which you might consider using the standard C run-time library string functions such as `strcmp` (or the Unicode/MBCS-portable `_tcscmp`). -If you must use the C run-time string functions, you can use the techniques described in _core_using_cstring_as_a_c.2d.style_null.2d.terminated_string. You can copy the `CString` object to an equivalent C-style string buffer, perform your operations on the buffer, and then assign the resulting C-style string back to a `CString` object. +If you must use the C run-time string functions, you can use the techniques described in [Using `CString` as a C-style null-terminated string](#_core_using_cstring_as_a_c.2d.style_null.2d.terminated_string). You can copy the `CString` object to an equivalent C-style string buffer, perform your operations on the buffer, and then assign the resulting C-style string back to a `CString` object. -## Modifying CString Contents Directly +## Modifying `CString` Contents Directly In most situations, you should use `CString` member functions to modify the contents of a `CString` object or to convert the `CString` to a C-style character string. @@ -56,7 +56,7 @@ There are some situations where it makes sense to directly modify the `CString` The `GetBuffer` and `ReleaseBuffer` methods offer access to the internal character buffer of a `CString` object and let you modify it directly. The following steps show how to use these functions for this purpose. -### To use GetBuffer and ReleaseBuffer to access the internal character buffer of a CString object +### To use `GetBuffer` and `ReleaseBuffer` to access the internal character buffer of a `CString` object 1. Call `GetBuffer` for a `CString` object and specify the length of the buffer you require. @@ -64,17 +64,17 @@ The `GetBuffer` and `ReleaseBuffer` methods offer access to the internal charact 1. Call `ReleaseBuffer` for the `CString` object to update all the internal `CString` state information, for example, the length of the string. After you modify the contents of a `CString` object directly, you must call `ReleaseBuffer` before you call any other `CString` member functions. -## Using CString Objects with Variable Argument Functions +## Using `CString` Objects with Variable Argument Functions Some C functions take a variable number of arguments. A notable example is `printf_s`. Because of the way this kind of function is declared, the compiler cannot be sure of the type of the arguments and cannot determine which conversion operation to perform on each argument. Therefore, it is essential that you use an explicit type cast when passing a `CString` object to a function that takes a variable number of arguments. -To use a `CString` object in a variable argument function, explicitly cast the `CString` to an LPCTSTR string, as shown in the following example. +To use a `CString` object in a variable argument function, explicitly cast the `CString` to an `LPCTSTR` string, as shown in the following example. [!code-cpp[NVC_ATLMFC_Utilities#190](../atl-mfc-shared/codesnippet/cpp/cstring-operations-relating-to-c-style-strings_2.cpp)] -## Specifying CString Formal Parameters +## Specifying `CString` Formal Parameters -For most functions that need a string argument, it is best to specify the formal parameter in the function prototype as a **`const`** pointer to a character (`LPCTSTR`) instead of a `CString`. When a formal parameter is specified as a **`const`** pointer to a character, you can pass either a pointer to a TCHAR array, a literal string [`"hi there"`], or a `CString` object. The `CString` object will be automatically converted to an LPCTSTR. Any place you can use an LPCTSTR, you can also use a `CString` object. +For most functions that need a string argument, it is best to specify the formal parameter in the function prototype as a **`const`** pointer to a character (`LPCTSTR`) instead of a `CString`. When a formal parameter is specified as a **`const`** pointer to a character, you can pass either a pointer to a `TCHAR` array, a literal string [`"hi there"`], or a `CString` object. The `CString` object will be automatically converted to an `LPCTSTR`. Any place you can use an `LPCTSTR`, you can also use a `CString` object. You can also specify a formal parameter as a constant string reference (that is, `const CString&`) if the argument will not be modified. Drop the **`const`** modifier if the string will be modified by the function. If a default null value is desired, initialize it to the null string [`""`], as shown below: @@ -85,4 +85,4 @@ For most function results, you can simply return a `CString` object by value. ## See also [Strings (ATL/MFC)](../atl-mfc-shared/strings-atl-mfc.md)
-[CString Argument Passing](../atl-mfc-shared/cstring-argument-passing.md) +[`CString` Argument Passing](../atl-mfc-shared/cstring-argument-passing.md) diff --git a/docs/atl-mfc-shared/date-and-time.md b/docs/atl-mfc-shared/date-and-time.md index ccc38a2767..6285d86cb2 100644 --- a/docs/atl-mfc-shared/date-and-time.md +++ b/docs/atl-mfc-shared/date-and-time.md @@ -3,33 +3,32 @@ description: "Learn more about: Date and Time" title: "Date and Time" ms.date: "08/13/2019" helpviewer_keywords: ["time, MFC programming", "time", "MFC, date and time", "dates, MFC"] -ms.assetid: ecf56dc5-d418-4603-ad3e-af7e205a6403 --- # Date and Time MFC supports several different ways of working with dates and times: -- Support for the Automation [DATE data type](../atl-mfc-shared/date-type.md). DATE supports date, time, and date/time values. The [COleDateTime](../atl-mfc-shared/reference/coledatetime-class.md) and [COleDateTimeSpan](../atl-mfc-shared/reference/coledatetimespan-class.md) classes encapsulate this functionality. They work with the [COleVariant](../mfc/reference/colevariant-class.md) class using Automation support. +- Support for the Automation [`DATE` data type](../atl-mfc-shared/date-type.md). `DATE` supports date, time, and date/time values. The [`COleDateTime`](../atl-mfc-shared/reference/coledatetime-class.md) and [`COleDateTimeSpan`](../atl-mfc-shared/reference/coledatetimespan-class.md) classes encapsulate this functionality. They work with the [`COleVariant`](../mfc/reference/colevariant-class.md) class using Automation support. -- General-purpose time classes. The [CTime](../atl-mfc-shared/reference/ctime-class.md) and [CTimeSpan](../atl-mfc-shared/reference/ctimespan-class.md) classes encapsulate most of the functionality associated with the ANSI-standard time library, which is declared in TIME.H. +- General-purpose time classes. The [`CTime`](../atl-mfc-shared/reference/ctime-class.md) and [`CTimeSpan`](../atl-mfc-shared/reference/ctimespan-class.md) classes encapsulate most of the functionality associated with the ANSI-standard time library, which is declared in `time.h`. - Support for system clock. With MFC version 3.0, support was added to `CTime` for the Win32 `SYSTEMTIME` and `FILETIME` data types. ## Date and Time: Automation Support -The [COleDateTime](../atl-mfc-shared/reference/coledatetime-class.md) class provides a way to represent date and time information. It provides finer granularity and a greater range than the [CTime](../atl-mfc-shared/reference/ctime-class.md) class. The [COleDateTimeSpan](../atl-mfc-shared/reference/coledatetimespan-class.md) class represents elapsed time, such as the difference between two `COleDateTime` objects. +The [`COleDateTime`](../atl-mfc-shared/reference/coledatetime-class.md) class provides a way to represent date and time information. It provides finer granularity and a greater range than the [`CTime`](../atl-mfc-shared/reference/ctime-class.md) class. The [`COleDateTimeSpan`](../atl-mfc-shared/reference/coledatetimespan-class.md) class represents elapsed time, such as the difference between two `COleDateTime` objects. -The `COleDateTime` and `COleDateTimeSpan` classes are designed for use with the `COleVariant` class. `COleDateTime` and `COleDateTimeSpan` are also useful in MFC database programming, but they can be used whenever you want to manipulate date and time values. Although the `COleDateTime` class has a greater range of values and finer granularity than the `CTime` class, it requires more storage per object than `CTime`. There are also some special considerations when working with the underlying DATE type. For more information on the implementation of DATE, see [The DATE Type](../atl-mfc-shared/date-type.md). +The `COleDateTime` and `COleDateTimeSpan` classes are designed for use with the `COleVariant` class. `COleDateTime` and `COleDateTimeSpan` are also useful in MFC database programming, but they can be used whenever you want to manipulate date and time values. Although the `COleDateTime` class has a greater range of values and finer granularity than the `CTime` class, it requires more storage per object than `CTime`. There are also some special considerations when working with the underlying DATE type. For more information on the implementation of `DATE`, see [The `DATE` Type](../atl-mfc-shared/date-type.md). -`COleDateTime` objects can be used to represent dates between January 1, 100, and December 31, 9999. `COleDateTime` objects are floating point values, with an approximate resolution of 1 millisecond. `COleDateTime` is based on the DATE data type, defined in the MFC documentation under [COleDateTime::operator DATE](../atl-mfc-shared/reference/coledatetime-class.md#operator_date). The actual implementation of DATE extends beyond these bounds. The `COleDateTime` implementation imposes these bounds to make it easier to work with the class. +`COleDateTime` objects can be used to represent dates between January 1, 100, and December 31, 9999. `COleDateTime` objects are floating point values, with an approximate resolution of 1 millisecond. `COleDateTime` is based on the `DATE` data type, defined in the MFC documentation under [`COleDateTime::operator DATE`](../atl-mfc-shared/reference/coledatetime-class.md#operator_date). The actual implementation of `DATE` extends beyond these bounds. The `COleDateTime` implementation imposes these bounds to make it easier to work with the class. `COleDateTime` doesn't support Julian dates. The Gregorian calendar is assumed to extend back in time to January 1, 100. `COleDateTime` ignores Daylight Saving Time (DST). The following code example compares two methods of calculating a time span that crosses the DST switchover date: one using the CRT, and the other using `COleDateTime`. -The first method sets two `CTime` objects, *time1* and *time2*, to April 5 and April 6 respectively, using the standard C type structures `tm` and `time_t`. The code displays *time1* and *time2* and the time span between them. +The first method sets two `CTime` objects, *`time1`* and *`time2`*, to April 5 and April 6 respectively, using the standard C type structures `tm` and `time_t`. The code displays *`time1`* and *`time2`* and the time span between them. -The second method creates two `COleDateTime` objects, `oletime1` and `oletime2`, and sets them to the same dates as *time1* and *time2*. It displays `oletime1` and `oletime2` and the time span between them. +The second method creates two `COleDateTime` objects, `oletime1` and `oletime2`, and sets them to the same dates as *`time1`* and *`time2`*. It displays `oletime1` and `oletime2` and the time span between them. The CRT correctly calculates a difference of 23 hours. `COleDateTimeSpan` calculates a difference of 24 hours. @@ -69,21 +68,21 @@ This procedure shows how to calculate the difference between two `COleDateTime` #### To format a time -Use the `Format` member function of either [COleDateTime](../atl-mfc-shared/reference/coledatetime-class.md) or [COleDateTimeSpan](../atl-mfc-shared/reference/coledatetimespan-class.md) to create a character string representing the time or elapsed time. +Use the `Format` member function of either [`COleDateTime`](../atl-mfc-shared/reference/coledatetime-class.md) or [`COleDateTimeSpan`](../atl-mfc-shared/reference/coledatetimespan-class.md) to create a character string representing the time or elapsed time. [!code-cpp[NVC_ATLMFC_Utilities#179](../atl-mfc-shared/codesnippet/cpp/formatting-time-automation-classes_1.cpp)] -For more information, see class [COleVariant](../mfc/reference/colevariant-class.md). +For more information, see class [`COleVariant`](../mfc/reference/colevariant-class.md). ## Date and Time: Database Support -Starting in version 4.0, MFC database programming uses the [COleDateTime](../atl-mfc-shared/reference/coledatetime-class.md) and [COleDateTimeSpan](../atl-mfc-shared/reference/coledatetimespan-class.md) classes to represent date and time data. These classes, also used in Automation, are derived from class [COleVariant](../mfc/reference/colevariant-class.md). They supply better support for managing date and time data than do [CTime](../atl-mfc-shared/reference/ctime-class.md) and [CTimeSpan](../atl-mfc-shared/reference/ctimespan-class.md). +Starting in version 4.0, MFC database programming uses the [`COleDateTime`](../atl-mfc-shared/reference/coledatetime-class.md) and [`COleDateTimeSpan`](../atl-mfc-shared/reference/coledatetimespan-class.md) classes to represent date and time data. These classes, also used in Automation, are derived from class [`COleVariant`](../mfc/reference/colevariant-class.md). They supply better support for managing date and time data than do [`CTime`](../atl-mfc-shared/reference/ctime-class.md) and [`CTimeSpan`](../atl-mfc-shared/reference/ctimespan-class.md). -## Date and Time: SYSTEMTIME Support +## Date and Time: `SYSTEMTIME` Support -The [COleDateTime](../atl-mfc-shared/reference/coledatetime-class.md) class has constructors that accept system and file times from Win32. +The [`COleDateTime`](../atl-mfc-shared/reference/coledatetime-class.md) class has constructors that accept system and file times from Win32. -The Win32 `FILETIME` structure represents time as a 64-bit value. It's a more convenient format for internal storage than a `SYSTEMTIME` structure, and the format used by Win32 to represent the time of file creation. For information about the SYSTEMTIME structure, see [SYSTEMTIME](/windows/desktop/api/minwinbase/ns-minwinbase-systemtime). For information about the FILETIME structure, see [FILETIME](/windows/desktop/api/minwinbase/ns-minwinbase-filetime). +The Win32 `FILETIME` structure represents time as a 64-bit value. It's a more convenient format for internal storage than a `SYSTEMTIME` structure, and the format used by Win32 to represent the time of file creation. For information about the `SYSTEMTIME` structure, see [`SYSTEMTIME`](/windows/desktop/api/minwinbase/ns-minwinbase-systemtime). For information about the `FILETIME` structure, see [`FILETIME`](/windows/desktop/api/minwinbase/ns-minwinbase-filetime). ## See also diff --git a/docs/atl-mfc-shared/exporting-string-classes-using-cstringt.md b/docs/atl-mfc-shared/exporting-string-classes-using-cstringt.md index 43fae08362..3e5b794a88 100644 --- a/docs/atl-mfc-shared/exporting-string-classes-using-cstringt.md +++ b/docs/atl-mfc-shared/exporting-string-classes-using-cstringt.md @@ -27,7 +27,7 @@ To resolve this problem, do the following: Export `CStringA` and `CStringW` (and the necessary base classes) from MFC90.DLL. Projects that include MFC will always use the MFC DLL exported `CStringA` and `CStringW`, as in previous MFC implementations. -Then create a exportable derived class using the `CStringT` template, as `CStringT_Exported` is below, for example: +Then create an exportable derived class using the `CStringT` template, as `CStringT_Exported` is below, for example: [!code-cpp[NVC_MFC_DLL#7](../atl-mfc-shared/codesnippet/cpp/exporting-string-classes-using-cstringt_2.cpp)] diff --git a/docs/atl-mfc-shared/reference/cfiletime-class.md b/docs/atl-mfc-shared/reference/cfiletime-class.md index da4732a852..35d7d8dc48 100644 --- a/docs/atl-mfc-shared/reference/cfiletime-class.md +++ b/docs/atl-mfc-shared/reference/cfiletime-class.md @@ -1,100 +1,100 @@ --- -description: "Learn more about: CFileTime Class" -title: "CFileTime Class" +description: "Learn more about: CFileTime class" +title: "CFileTime class" ms.date: "10/18/2018" f1_keywords: ["CFileTime", "ATLTIME/ATL::CFileTime", "ATLTIME/ATL::CFileTime::CFileTime", "ATLTIME/ATL::CFileTime::GetCurrentTime", "ATLTIME/ATL::CFileTime::GetTime", "ATLTIME/ATL::CFileTime::LocalToUTC", "ATLTIME/ATL::CFileTime::SetTime", "ATLTIME/ATL::CFileTime::UTCToLocal", "ATLTIME/ATL::CFileTime::Day", "ATLTIME/ATL::CFileTime::Hour", "ATLTIME/ATL::CFileTime::Millisecond", "ATLTIME/ATL::CFileTime::Minute", "ATLTIME/ATL::CFileTime::Second", "ATLTIME/ATL::CFileTime::Week"] helpviewer_keywords: ["CFileTime class", "shared classes, CFileTime"] ms.assetid: 1a358a65-1383-4124-b0d4-59b026e6860f --- -# CFileTime Class +# `CFileTime` class This class provides methods for managing the date and time values associated with a file. ## Syntax -``` +```cpp class CFileTime : public FILETIME ``` ## Members -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[CFileTime::CFileTime](#cfiletime)|The constructor.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|[CFileTime::GetCurrentTime](#getcurrenttime)|Call this static function to retrieve a `CFileTime` object that represents the current system date and time.| -|[CFileTime::GetTime](#gettime)|Call this method to retrieve the time from the `CFileTime` object.| -|[CFileTime::LocalToUTC](#localtoutc)|Call this method to convert a local file time to a file time based on the Coordinated Universal Time (UTC).| -|[CFileTime::SetTime](#settime)|Call this method to set the date and time stored by the `CFileTime` object.| -|[CFileTime::UTCToLocal](#utctolocal)|Call this method to convert time based on the Coordinated Universal Time (UTC) to local file time.| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|[CFileTime::operator -](#operator_-)|This operator is used to perform subtraction on a `CFileTime` or `CFileTimeSpan` object.| -|[CFileTime::operator !=](#operator_neq)|This operator compares two `CFileTime` objects for inequality.| -|[CFileTime::operator +](#operator_add)|This operator is used to perform addition on a `CFileTimeSpan` object.| -|[CFileTime::operator +=](#operator_add_eq)|This operator is used to perform addition on a `CFileTimeSpan` object and assign the result to the current object.| -|[CFileTime::operator <](#operator_lt)|This operator compares two `CFileTime` objects to determine the lesser.| -|[CFileTime::operator <=](#operator_lt_eq)|This operator compares two `CFileTime` objects to determine equality or the lesser.| -|[CFileTime::operator =](#operator_eq)|The assignment operator.| -|[CFileTime::operator -=](#operator_-_eq)|This operator is used to perform subtraction on a `CFileTimeSpan` object and assign the result to the current object.| -|[CFileTime::operator ==](#operator_eq_eq)|This operator compares two `CFileTime` objects for equality.| -|[CFileTime::operator >](#operator_gt)|This operator compares two `CFileTime` objects to determine the larger.| -|[CFileTime::operator >=](#operator_gt_eq)|This operator compares two `CFileTime` objects to determine equality or the larger.| - -### Public Constants - -|Name|Description| -|----------|-----------------| -|[CFileTime::Day](#day)|A static data member storing the number of 100-nanosecond intervals that make up one day.| -|[CFileTime::Hour](#hour)|A static data member storing the number of 100-nanosecond intervals that make up one hour.| -|[CFileTime::Millisecond](#millisecond)|A static data member storing the number of 100-nanosecond intervals that make up one millisecond.| -|[CFileTime::Minute](#minute)|A static data member storing the number of 100-nanosecond intervals that make up one minute.| -|[CFileTime::Second](#second)|A static data member storing the number of 100-nanosecond intervals that make up one second.| -|[CFileTime::Week](#week)|A static data member storing the number of 100-nanosecond intervals that make up one week.| +### Public constructors + +| Name | Description | +|--|--| +| [`CFileTime::CFileTime`](#cfiletime) | The constructor. | + +### Public methods + +| Name | Description | +|--|--| +| [`CFileTime::GetCurrentTime`](#getcurrenttime) | Call this static function to retrieve a `CFileTime` object that represents the current system date and time. | +| [`CFileTime::GetTime`](#gettime) | Call this method to retrieve the time from the `CFileTime` object. | +| [`CFileTime::LocalToUTC`](#localtoutc) | Call this method to convert a local file time to a file time based on the Coordinated Universal Time (UTC). | +| [`CFileTime::SetTime`](#settime) | Call this method to set the date and time stored by the `CFileTime` object. | +| [`CFileTime::UTCToLocal`](#utctolocal) | Call this method to convert time based on the Coordinated Universal Time (UTC) to local file time. | + +### Public operators + +| Name | Description | +|--|--| +| [`CFileTime::operator -`](#operator_-) | This operator is used to perform subtraction on a `CFileTime` or `CFileTimeSpan` object. | +| [`CFileTime::operator !=`](#operator_neq) | This operator compares two `CFileTime` objects for inequality. | +| [`CFileTime::operator +`](#operator_add) | This operator is used to perform addition on a `CFileTimeSpan` object. | +| [`CFileTime::operator +=`](#operator_add_eq) | This operator is used to perform addition on a `CFileTimeSpan` object and assign the result to the current object. | +| [`CFileTime::operator <`](#operator_lt) | This operator compares two `CFileTime` objects to determine the lesser. | +| [`CFileTime::operator <=`](#operator_lt_eq) | This operator compares two `CFileTime` objects to determine equality or the lesser. | +| [`CFileTime::operator =`](#operator_eq) | The assignment operator. | +| [`CFileTime::operator -=`](#operator_-_eq) | This operator is used to perform subtraction on a `CFileTimeSpan` object and assign the result to the current object. | +| [`CFileTime::operator ==`](#operator_eq_eq) | This operator compares two `CFileTime` objects for equality. | +| [`CFileTime::operator >`](#operator_gt) | This operator compares two `CFileTime` objects to determine the larger. | +| [`CFileTime::operator >=`](#operator_gt_eq) | This operator compares two `CFileTime` objects to determine equality or the larger. | + +### Public constants + +| Name | Description | +|--|--| +| [`CFileTime::Day`](#day) | A static data member storing the number of 100-nanosecond intervals that make up one day. | +| [`CFileTime::Hour`](#hour) | A static data member storing the number of 100-nanosecond intervals that make up one hour. | +| [`CFileTime::Millisecond`](#millisecond) | A static data member storing the number of 100-nanosecond intervals that make up one millisecond. | +| [`CFileTime::Minute`](#minute) | A static data member storing the number of 100-nanosecond intervals that make up one minute. | +| [`CFileTime::Second`](#second) | A static data member storing the number of 100-nanosecond intervals that make up one second. | +| [`CFileTime::Week`](#week) | A static data member storing the number of 100-nanosecond intervals that make up one week. | ## Remarks -This class provides methods for managing the date and time values associated with the creation, access and modification of files. The methods and data of this class are frequently used in conjunction with `CFileTimeSpan` objects, which deal with relative time values. +This class provides methods for managing the date and time values associated with the creation, access, and modification of files. The methods and data of this class are frequently used together with `CFileTimeSpan` objects, which deal with relative time values. -The date and time value is stored as a 64-bit value representing the number of 100-nanosecond intervals since January 1, 1601. This is the Coordinated Universal Time (UTC) format. +The date and time value is stored as a 64-bit value representing the number of 100-nanosecond intervals since January 1, 1601. This format is the Coordinated Universal Time (UTC) format. The following static const member variables are provided to simplify calculations: -|Member variable|Number of 100-nanosecond intervals| -|---------------------|-----------------------------------------| -|Millisecond|10,000| -|Second|Millisecond \* 1,000| -|Minute|Second \* 60| -|Hour|Minute \* 60| -|Day|Hour \* 24| -|Week|Day \* 7| - -**Note** Not all file systems can record creation and last access time and not all file systems record them in the same manner. For example, on the Windows NT FAT file system, create time has a resolution of 10 milliseconds, write time has a resolution of 2 seconds, and access time has a resolution of 1 day (the access date). On NTFS, access time has a resolution of 1 hour. Furthermore, FAT records times on disk in local time, but NTFS records times on disk in UTC. For more information, see [File Times](/windows/win32/SysInfo/file-times). +| Member variable | Number of 100-nanosecond intervals | +|--|--| +| Millisecond | 10,000 | +| Second | Millisecond \* 1,000 | +| Minute | Second \* 60 | +| Hour | Minute \* 60 | +| Day | Hour \* 24 | +| Week | Day \* 7 | -## Inheritance Hierarchy +> [!Note] +> Not all file systems can record creation and last access time and not all file systems record them in the same manner. For example, on the Windows NT FAT file system, create time has a resolution of 10 milliseconds, write time has a resolution of 2 seconds, and access time has a resolution of 1 day (the access date). On NTFS, access time has a resolution of 1 hour. Furthermore, FAT records times on disk in local time, but NTFS records times on disk in UTC. For more information, see [File times](/windows/win32/SysInfo/file-times). -`FILETIME` +## Inheritance hierarchy -`CFileTime` +[`FILETIME`](/windows/win32/api/minwinbase/ns-minwinbase-filetime)\ + └ [`CFileTime`](cfiletime-class.md) ## Requirements **Header:** atltime.h -## CFileTime::CFileTime +## `CFileTime::CFileTime` The constructor. -``` +```cpp CFileTime() throw(); CFileTime(const FILETIME& ft) throw(); CFileTime(ULONGLONG nTime) throw(); @@ -102,37 +102,37 @@ CFileTime(ULONGLONG nTime) throw(); ### Parameters -*ft*
-A [FILETIME](/windows/win32/api/minwinbase/ns-minwinbase-filetime) structure. +*`ft`*\ +A [`FILETIME`](/windows/win32/api/minwinbase/ns-minwinbase-filetime) structure. -*nTime*
+*`nTime`*\ The date and time expressed as a 64-bit value. ### Remarks The `CFileTime` object can be created using an existing date and time from a `FILETIME` structure, or expressed as a 64-bit value (in local or Coordinated Universal Time (UTC) time formats). The default constructor sets the time to 0. -## CFileTime::Day +## `CFileTime::Day` A static data member storing the number of 100-nanosecond intervals that make up one day. -``` +```cpp static const ULONGLONG Day = Hour* 24; ``` ### Example -See the example for [CFileTime::Millisecond](#millisecond). +See the example for [`CFileTime::Millisecond`](#millisecond). -## CFileTime::GetCurrentTime +## `CFileTime::GetCurrentTime` Call this static function to retrieve a `CFileTime` object that represents the current system date and time. -``` +```cpp static CFileTime GetCurrentTime() throw(); ``` -### Return Value +### Return value Returns the current system date and time in Coordinated Universal Time (UTC) format. @@ -140,51 +140,51 @@ Returns the current system date and time in Coordinated Universal Time (UTC) for [!code-cpp[NVC_MFCFiles#41](../../atl-mfc-shared/reference/codesnippet/cpp/cfiletime-class_1.cpp)] -## CFileTime::GetTime +## `CFileTime::GetTime` Call this method to retrieve the time from the `CFileTime` object. -``` +```cpp ULONGLONG GetTime() const throw(); ``` -### Return Value +### Return value Returns the date and time as a 64-bit number, which may be in either local or Coordinated Universal Time (UTC) format. -## CFileTime::Hour +## `CFileTime::Hour` A static data member storing the number of 100-nanosecond intervals that make up one hour. -``` +```cpp static const ULONGLONG Hour = Minute* 60; ``` ### Example -See the example for [CFileTime::Millisecond](#millisecond). +See the example for [`CFileTime::Millisecond`](#millisecond). -## CFileTime::LocalToUTC +## `CFileTime::LocalToUTC` Call this method to convert a local file time to a file time based on the Coordinated Universal Time (UTC). -``` +```cpp CFileTime LocalToUTC() const throw(); ``` -### Return Value +### Return value Returns a `CFileTime` object containing the time in UTC format. ### Example -See the example for [CFileTime::UTCToLocal](#utctolocal). +See the example for [`CFileTime::UTCToLocal`](#utctolocal). -## CFileTime::Millisecond +## `CFileTime::Millisecond` A static data member storing the number of 100-nanosecond intervals that make up one millisecond. -``` +```cpp static const ULONGLONG Millisecond = 10000; ``` @@ -192,226 +192,226 @@ static const ULONGLONG Millisecond = 10000; [!code-cpp[NVC_MFCFiles#44](../../atl-mfc-shared/reference/codesnippet/cpp/cfiletime-class_2.cpp)] -## CFileTime::Minute +## `CFileTime::Minute` A static data member storing the number of 100-nanosecond intervals that make up one minute. -``` +```cpp static const ULONGLONG Minute = Second* 60; ``` ### Example -See the example for [CFileTime::Millisecond](#millisecond). +See the example for [`CFileTime::Millisecond`](#millisecond). -## CFileTime::operator - +## `CFileTime::operator -` This operator is used to perform subtraction on a `CFileTime` or `CFileTimeSpan` object. -``` +```cpp CFileTime operator-(CFileTimeSpan span) const throw(); CFileTimeSpan operator-(CFileTime ft) const throw(); ``` ### Parameters -*span*
+*`span`*\ A `CFileTimeSpan` object. -*ft*
+*`ft`*\ A `CFileTime` object. -### Return Value +### Return value Returns a `CFileTime` object or a `CFileTimeSpan` object representing the result of the time difference between the two objects. -## CFileTime::operator != +## `CFileTime::operator !=` This operator compares two `CFileTime` objects for inequality. -``` +```cpp bool operator!=(CFileTime ft) const throw(); ``` ### Parameters -*ft*
+*`ft`*\ The `CFileTime` object to be compared. -### Return Value +### Return value -Returns TRUE if the item being compared is not equal to the `CFileTime` object, otherwise FALSE. +Returns `TRUE` if the item being compared isn't equal to the `CFileTime` object, otherwise `FALSE`. -## CFileTime::operator + +## `CFileTime::operator +` This operator is used to perform addition on a `CFileTimeSpan` object. -``` +```cpp CFileTime operator+(CFileTimeSpan span) const throw(); ``` ### Parameters -*span*
+*`span`*\ A `CFileTimeSpan` object. -### Return Value +### Return value Returns a `CFileTime` object representing the result of the original time plus a relative time. -## CFileTime::operator += +## `CFileTime::operator +=` This operator is used to perform addition on a `CFileTimeSpan` object and assign the result to the current object. -``` +```cpp CFileTime& operator+=(CFileTimeSpan span) throw(); ``` ### Parameters -*span*
+*`span`*\ A `CFileTimeSpan` object. -### Return Value +### Return value Returns the updated `CFileTime` object, representing the result of the original time plus a relative time. -## CFileTime::operator < +## `CFileTime::operator <` This operator compares two `CFileTime` objects to determine the lesser. -``` +```cpp bool operator<(CFileTime ft) const throw(); ``` ### Parameters -*ft*
+*`ft`*\ The `CFileTime` object to be compared. -### Return Value +### Return value -Returns TRUE if the first object is less (earlier in time) than the second, FALSE otherwise. +Returns `TRUE` if the first object is less (earlier in time) than the second, `FALSE` otherwise. ### Example [!code-cpp[NVC_MFCFiles#43](../../atl-mfc-shared/reference/codesnippet/cpp/cfiletime-class_3.cpp)] -## CFileTime::operator <= +## `CFileTime::operator <>=` This operator compares two `CFileTime` objects to determine equality or the lesser. -``` +```cpp bool operator<=(CFileTime ft) const throw(); ``` ### Parameters -*ft*
+*`ft`*\ The `CFileTime` object to be compared. -### Return Value +### Return value -Returns TRUE if the first object is less than (earlier in time) or equal to the second, otherwise FALSE. +Returns `TRUE` if the first object is less than (earlier in time) or equal to the second, otherwise `FALSE`. -## CFileTime::operator = +## `CFileTime::operator =` The assignment operator. -``` +```cpp CFileTime& operator=(const FILETIME& ft) throw(); ``` ### Parameters -*ft*
+*`ft`*\ A `CFileTime` object containing the new time and date. -### Return Value +### Return value Returns the updated `CFileTime` object. -## CFileTime::operator -= +## `CFileTime::operator -=` This operator is used to perform subtraction on a `CFileTimeSpan` object and assign the result to the current object. -``` +```cpp CFileTime& operator-=(CFileTimeSpan span) throw(); ``` ### Parameters -*span*
+*`span`*\ A `CFileTimeSpan` object containing the relative time to subtract. -### Return Value +### Return value Returns the updated `CFileTime` object. -## CFileTime::operator == +## `CFileTime::operator ==` This operator compares two `CFileTime` objects for equality. -``` +```cpp bool operator==(CFileTime ft) const throw(); ``` ### Parameters -*ft*
+*`ft`*\ The `CFileTime` object to compare. -### Return Value +### Return value -Returns TRUE if the objects are equal, otherwise FALSE. +Returns `TRUE` if the objects are equal, otherwise `FALSE`. -## CFileTime::operator > +## `CFileTime::operator >` This operator compares two `CFileTime` objects to determine the larger. -``` +```cpp bool operator>(CFileTime ft) const throw(); ``` ### Parameters -*ft*
+*`ft`*\ The `CFileTime` object to be compared. -### Return Value +### Return value -Returns TRUE if the first object is greater than (later in time) than the second, otherwise FALSE. +Returns `TRUE` if the first object is greater than (later in time) than the second, otherwise `FALSE`. -## CFileTime::operator >= +## `CFileTime::operator >=` This operator compares two `CFileTime` objects to determine equality or the larger. -``` +```cpp bool operator>=(CFileTime ft) const throw(); ``` ### Parameters -*ft*
+*`ft`*\ The `CFileTime` object to be compared. -### Return Value +### Return value -Returns TRUE if the first object is greater than (later in time) or equal to the second, otherwise FALSE. +Returns `TRUE` if the first object is greater than (later in time) or equal to the second, otherwise `FALSE`. -## CFileTime::Second +## `CFileTime::Second` A static data member storing the number of 100-nanosecond intervals that make up one day. -``` +```cpp static const ULONGLONG Second = Millisecond* 1000; ``` ### Example -See the example for [CFileTime::Millisecond](#millisecond). +See the example for [`CFileTime::Millisecond`](#millisecond). -## CFileTime::SetTime +## `CFileTime::SetTime` Call this method to set the date and time stored by the `CFileTime` object. @@ -421,18 +421,18 @@ void SetTime(ULONGLONG nTime) throw(); ### Parameters -*nTime*
+*`nTime`*\ The 64-bit value representing the date and time, in either local or Coordinated Universal Time (UTC) format. -## CFileTime::UTCToLocal +## `CFileTime::UTCToLocal` Call this method to convert time based on the Coordinated Universal Time (UTC) to local file time. -``` +```cpp CFileTime UTCToLocal() const throw(); ``` -### Return Value +### Return value Returns a `CFileTime` object containing the time in local file time format. @@ -440,21 +440,21 @@ Returns a `CFileTime` object containing the time in local file time format. [!code-cpp[NVC_MFCFiles#42](../../atl-mfc-shared/reference/codesnippet/cpp/cfiletime-class_4.cpp)] -## CFileTime::Week +## `CFileTime::Week` A static data member storing the number of 100-nanosecond intervals that make up one week. -``` +```cpp static const ULONGLONG Week = Day* 7; ``` ### Example -See the example for [CFileTime::Millisecond](#millisecond). +See the example for [`CFileTime::Millisecond`](#millisecond). ## See also -[FILETIME](/windows/win32/api/minwinbase/ns-minwinbase-filetime)
-[CFileTimeSpan Class](../../atl-mfc-shared/reference/cfiletimespan-class.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[ATL/MFC Shared Classes](../../atl-mfc-shared/atl-mfc-shared-classes.md) +[`FILETIME`](/windows/win32/api/minwinbase/ns-minwinbase-filetime)\ +[`CFileTimeSpan` class](../../atl-mfc-shared/reference/cfiletimespan-class.md)\ +[Hierarchy chart](../../mfc/hierarchy-chart.md)\ +[ATL/MFC shared classes](../../atl-mfc-shared/atl-mfc-shared-classes.md) diff --git a/docs/atl-mfc-shared/reference/cfiletimespan-class.md b/docs/atl-mfc-shared/reference/cfiletimespan-class.md index 144bb6a723..62a26f382e 100644 --- a/docs/atl-mfc-shared/reference/cfiletimespan-class.md +++ b/docs/atl-mfc-shared/reference/cfiletimespan-class.md @@ -6,7 +6,7 @@ f1_keywords: ["CFileTimeSpan", "ATLTIME/ATL::CFileTimeSpan", "ATLTIME/ATL::CFile helpviewer_keywords: ["shared classes, CFileTimeSpan", "CFileTimeSpan class"] ms.assetid: 5856fb39-9c82-4027-8ccf-8760890491ec --- -# CFileTimeSpan class +# `CFileTimeSpan` class This class provides methods for managing relative date and time values associated with a file. @@ -22,44 +22,44 @@ class CFileTimeSpan |Name|Description| |----------|-----------------| -|[CFileTimeSpan::CFileTimeSpan](#cfiletimespan)|The constructor.| +|[`CFileTimeSpan::CFileTimeSpan`](#cfiletimespan)|The constructor.| ### Public methods |Name|Description| |----------|-----------------| -|[CFileTimeSpan::GetTimeSpan](#gettimespan)|Call this method to retrieve the time span from the `CFileTimeSpan` object.| -|[CFileTimeSpan::SetTimeSpan](#settimespan)|Call this method to set the time span of the `CFileTimeSpan` object.| +|[`CFileTimeSpan::GetTimeSpan`](#gettimespan)|Call this method to retrieve the time span from the `CFileTimeSpan` object.| +|[`CFileTimeSpan::SetTimeSpan`](#settimespan)|Call this method to set the time span of the `CFileTimeSpan` object.| ### Public operators |Name|Description| |----------|-----------------| -|[CFileTimeSpan::operator -](#operator_-)|Performs subtraction on a `CFileTimeSpan` object.| -|[CFileTimeSpan::operator !=](#operator_neq)|Compares two `CFileTimeSpan` objects for inequality.| -|[CFileTimeSpan::operator +](#operator_add)|Performs addition on a `CFileTimeSpan` object.| -|[CFileTimeSpan::operator +=](#operator_add_eq)|Performs addition on a `CFileTimeSpan` object and assign the result to the current object.| -|[CFileTimeSpan::operator <](#operator_lt)|Compares two `CFileTimeSpan` objects to determine the lesser.| -|[CFileTimeSpan::operator <=](#operator_lt_eq)|Compares two `CFileTimeSpan` objects to determine equality or the lesser.| -|[CFileTimeSpan::operator =](#operator_eq)|The assignment operator.| -|[CFileTimeSpan::operator -=](#operator_-_eq)|Performs subtraction on a `CFileTimeSpan` object and assign the result to the current object.| -|[CFileTimeSpan::operator ==](#operator_eq_eq)|Compares two `CFileTimeSpan` objects for equality.| -|[CFileTimeSpan::operator >](#operator_gt)|Compares two `CFileTimeSpan` objects to determine the larger.| -|[CFileTimeSpan::operator >=](#operator_gt_eq)|Compares two `CFileTimeSpan` objects to determine equality or the larger.| +|[`CFileTimeSpan::operator -`](#operator_-)|Performs subtraction on a `CFileTimeSpan` object.| +|[`CFileTimeSpan::operator !=`](#operator_neq)|Compares two `CFileTimeSpan` objects for inequality.| +|[`CFileTimeSpan::operator +`](#operator_add)|Performs addition on a `CFileTimeSpan` object.| +|[`CFileTimeSpan::operator +=`](#operator_add_eq)|Performs addition on a `CFileTimeSpan` object and assign the result to the current object.| +|[`CFileTimeSpan::operator <`](#operator_lt)|Compares two `CFileTimeSpan` objects to determine the lesser.| +|[`CFileTimeSpan::operator <=`](#operator_lt_eq)|Compares two `CFileTimeSpan` objects to determine equality or the lesser.| +|[`CFileTimeSpan::operator =`](#operator_eq)|The assignment operator.| +|[`CFileTimeSpan::operator -=`](#operator_-_eq)|Performs subtraction on a `CFileTimeSpan` object and assign the result to the current object.| +|[`CFileTimeSpan::operator ==`](#operator_eq_eq)|Compares two `CFileTimeSpan` objects for equality.| +|[`CFileTimeSpan::operator >`](#operator_gt)|Compares two `CFileTimeSpan` objects to determine the larger.| +|[`CFileTimeSpan::operator >=`](#operator_gt_eq)|Compares two `CFileTimeSpan` objects to determine equality or the larger.| ## Remarks -The `CFileTimeSpan` class provides methods to handle relative periods of time in the units the file system uses. These units are often used in file operations, such as when a file was created, last accessed, or last modified. The methods of this class are frequently used in conjunction with [CFileTime class](../../atl-mfc-shared/reference/cfiletime-class.md) objects. +The `CFileTimeSpan` class provides methods to handle relative periods of time in the units the file system uses. These units are often used in file operations, such as when a file was created, last accessed, or last modified. The methods of this class are frequently used together with [`CFileTime` class](../../atl-mfc-shared/reference/cfiletime-class.md) objects. ## Example -See the example for [CFileTime::Millisecond](../../atl-mfc-shared/reference/cfiletime-class.md#millisecond). +See the example for [`CFileTime::Millisecond`](../../atl-mfc-shared/reference/cfiletime-class.md#millisecond). ## Requirements **Header:** atltime.h -## CFileTimeSpan::CFileTimeSpan +## `CFileTimeSpan::CFileTimeSpan` The constructor. @@ -71,17 +71,17 @@ CFileTimeSpan(LONGLONG nSpan) throw(); ### Parameters -*span*\ +*`span`*\ An existing `CFileTimeSpan` object. -*nSpan*\ -A period of time in FILETIME units. +*`nSpan`*\ +A period of time in `FILETIME` units. ### Remarks -The `CFileTimeSpan` object can be created using an existing `CFileTimeSpan` object, or expressed as a 64-bit value in 100-nanosecond FILETIME units. For more information, see [CFileTime](cfiletime-class.md). The default constructor sets the time span to 0. +The `CFileTimeSpan` object can be created using an existing `CFileTimeSpan` object, or expressed as a 64-bit value in 100-nanosecond `FILETIME` units. For more information, see [`CFileTime`](cfiletime-class.md). The default constructor sets the time span to 0. -## CFileTimeSpan::GetTimeSpan +## `CFileTimeSpan::GetTimeSpan` Call this method to retrieve the time span from the `CFileTimeSpan` object. @@ -91,9 +91,9 @@ LONGLONG GetTimeSpan() const throw(); ### Return value -Returns the time span in 100-nanosecond FILETIME units. For more information, see [CFileTime](cfiletime-class.md). +Returns the time span in 100-nanosecond `FILETIME` units. For more information, see [`CFileTime`](cfiletime-class.md). -## CFileTimeSpan::operator - +## `CFileTimeSpan::operator -` Performs subtraction on a `CFileTimeSpan` object. @@ -103,14 +103,14 @@ CFileTimeSpan operator-(CFileTimeSpan span) const throw(); ### Parameters -*span*\ +*`span`*\ A `CFileTimeSpan` object. ### Return value Returns a `CFileTimeSpan` object representing the result of the difference between two time spans. -## CFileTimeSpan::operator != +## `CFileTimeSpan::operator !=` Compares two `CFileTimeSpan` objects for inequality. @@ -120,14 +120,14 @@ bool operator!=(CFileTimeSpan span) const throw(); ### Parameters -*span*\ +*`span`*\ The `CFileTimeSpan` object to be compared. ### Return value -Returns TRUE if the item being compared isn't equal to the `CFileTimeSpan` object; otherwise FALSE. +Returns `TRUE` if the item being compared isn't equal to the `CFileTimeSpan` object; otherwise `FALSE`. -## CFileTimeSpan::operator + +## `CFileTimeSpan::operator +` Performs addition on a `CFileTimeSpan` object. @@ -137,14 +137,14 @@ CFileTimeSpan operator+(CFileTimeSpan span) const throw(); ### Parameters -*span*\ +*`span`*\ A `CFileTimeSpan` object. ### Return value Returns a `CFileTimeSpan` object containing the sum of the two time spans. -## CFileTimeSpan::operator += +## `CFileTimeSpan::operator +=` Performs addition on a `CFileTimeSpan` object and assigns the result to the current object. @@ -154,14 +154,14 @@ CFileTimeSpan& operator+=(CFileTimeSpan span) throw(); ### Parameters -*span*\ +*`span`*\ A `CFileTimeSpan` object. ### Return value Returns the updated `CFileTimeSpan` object containing the sum of the two time spans. -## CFileTimeSpan::operator < +## `CFileTimeSpan::operator <` Compares two `CFileTimeSpan` objects to determine the lesser. @@ -171,14 +171,14 @@ bool operator<(CFileTimeSpan span) const throw(); ### Parameters -*span*\ +*`span`*\ The `CFileTimeSpan` object to be compared. ### Return value -Returns TRUE if the first object is less (that is, represents a shorter time period) than the second, otherwise FALSE. +Returns `TRUE` if the first object is less (that is, represents a shorter time period) than the second, otherwise `FALSE`. -## CFileTimeSpan::operator <= +## `CFileTimeSpan::operator <=` Compares two `CFileTimeSpan` objects to determine equality or the lesser. @@ -188,14 +188,14 @@ bool operator<=(CFileTimeSpan span) const throw(); ### Parameters -*span*\ +*`span`*\ The `CFileTimeSpan` object to be compared. ### Return value -Returns TRUE if the first object is less than (that is, represents a shorter time period) or equal to the second, otherwise FALSE. +Returns `TRUE` if the first object is less than (that is, represents a shorter time period) or equal to the second, otherwise `FALSE`. -## CFileTimeSpan::operator = +## `CFileTimeSpan::operator =` The assignment operator. @@ -205,14 +205,14 @@ CFileTimeSpan& operator=(const CFileTimeSpan& span) throw(); ### Parameters -*span*\ +*`span`*\ A `CFileTimeSpan` object. ### Return value Returns the updated `CFileTimeSpan` object. -## CFileTimeSpan::operator -= +## `CFileTimeSpan::operator -=` Performs subtraction on a `CFileTimeSpan` object and assigns the result to the current object. @@ -222,14 +222,14 @@ CFileTimeSpan& operator-=(CFileTimeSpan span) throw(); ### Parameters -*span*\ +*`span`*\ A `CFileTimeSpan` object. ### Return value Returns the updated `CFileTimeSpan` object. -## CFileTimeSpan::operator == +## `CFileTimeSpan::operator ==` Compares two `CFileTimeSpan` objects for equality. @@ -239,14 +239,14 @@ bool operator==(CFileTimeSpan span) const throw(); ### Parameters -*span*\ +*`span`*\ The `CFileTimeSpan` object to be compared. ### Return value -Returns TRUE if the objects are equal, otherwise FALSE. +Returns `TRUE` if the objects are equal, otherwise `FALSE`. -## CFileTimeSpan::operator > +## `CFileTimeSpan::operator >` Compares two `CFileTimeSpan` objects to determine the larger. @@ -256,14 +256,14 @@ bool operator>(CFileTimeSpan span) const throw(); ### Parameters -*span*\ +*`span`*\ The `CFileTimeSpan` object to be compared. ### Return value -Returns TRUE if the first object is greater than (that is, represents a longer time period) than the second, otherwise FALSE. +Returns `TRUE` if the first object is greater than (that is, represents a longer time period) than the second, otherwise `FALSE`. -## CFileTimeSpan::operator >= +## `CFileTimeSpan::operator >=` Compares two `CFileTimeSpan` objects to determine equality or the larger. @@ -273,14 +273,14 @@ bool operator>=(CFileTimeSpan span) const throw(); ### Parameters -*span*\ +*`span`*\ The `CFileTimeSpan` object to be compared. ### Return value -Returns TRUE if the first object is greater than (that is, represents a longer time period) or equal to the second, otherwise FALSE. +Returns `TRUE` if the first object is greater than (that is, represents a longer time period) or equal to the second, otherwise `FALSE`. -## CFileTimeSpan::SetTimeSpan +## `CFileTimeSpan::SetTimeSpan` Call this method to set the time span of the `CFileTimeSpan` object. @@ -290,12 +290,12 @@ void SetTimeSpan(LONGLONG nSpan) throw(); ### Parameters -*nSpan*\ -The new value for the time span in 100-nanosecond FILETIME units. For more information, see [CFileTime](cfiletime-class.md). +*`nSpan`*\ +The new value for the time span in 100-nanosecond `FILETIME` units. For more information, see [`CFileTime`](cfiletime-class.md). ## See also -[FILETIME](/windows/win32/api/minwinbase/ns-minwinbase-filetime)\ -[CFileTime class](cfiletime-class.md)\ +[`FILETIME`](/windows/win32/api/minwinbase/ns-minwinbase-filetime)\ +[`CFileTime` class](cfiletime-class.md)\ [Hierarchy chart](../../mfc/hierarchy-chart.md)\ [ATL/MFC shared classes](../../atl-mfc-shared/atl-mfc-shared-classes.md) diff --git a/docs/atl-mfc-shared/reference/cfixedstringt-class.md b/docs/atl-mfc-shared/reference/cfixedstringt-class.md index f550ca44b9..c236dcb8d4 100644 --- a/docs/atl-mfc-shared/reference/cfixedstringt-class.md +++ b/docs/atl-mfc-shared/reference/cfixedstringt-class.md @@ -12,7 +12,7 @@ This class represents a string object with a fixed character buffer. ## Syntax -``` +```cpp template class CFixedStringT : private CFixedStringMgr, public StringType ``` @@ -69,7 +69,7 @@ For more information on the customization of `CFixedStringT` and memory manageme Constructs a `CFixedStringT` object. -``` +```cpp CFixedStringT() throw(); explicit CFixedStringT(IAtlStringMgr* pStringMgr) throw(); CFixedStringT(const CFixedStringT& strSrc); @@ -98,7 +98,7 @@ Because the constructors copy the input data into new allocated storage, you sho Reinitializes an existing `CFixedStringT` object with new data. -``` +```cpp CFixedStringT& operator=( const CFixedStringT& strSrc); CFixedStringT& operator=(const char* pszSrc); diff --git a/docs/atl-mfc-shared/reference/cimage-class.md b/docs/atl-mfc-shared/reference/cimage-class.md index 47da691421..0dd7899250 100644 --- a/docs/atl-mfc-shared/reference/cimage-class.md +++ b/docs/atl-mfc-shared/reference/cimage-class.md @@ -6,7 +6,7 @@ f1_keywords: ["CImage", "ATLIMAGE/ATL::CImage", "ATLIMAGE/ATL::CImage::CImage", helpviewer_keywords: ["jpeg files", "bitmaps [C++], ATL and MFC support for", "images [C++], ATL and MFC support for", "gif files, ATL and MFC support", ".gif files, ATL and MFC support", "PNG files, ATL and MFC support", "CImage class", "transparent color"] ms.assetid: 52861e3d-bf7e-481f-a240-90e88f76c490 --- -# CImage Class +# `CImage` Class `CImage` provides enhanced bitmap support, including the ability to load and save images in JPEG, GIF, BMP, and Portable Network Graphics (PNG) formats. @@ -15,7 +15,7 @@ ms.assetid: 52861e3d-bf7e-481f-a240-90e88f76c490 ## Syntax -``` +```cpp class CImage ``` @@ -25,85 +25,85 @@ class CImage |Name|Description| |----------|-----------------| -|[CImage::CImage](#cimage)|The constructor.| +|[`CImage::CImage`](#cimage)|The constructor.| ### Public Methods |Name|Description| |----------|-----------------| -|[CImage::AlphaBlend](#alphablend)|Displays bitmaps that have transparent or semitransparent pixels.| -|[CImage::Attach](#attach)|Attaches an HBITMAP to a `CImage` object. Can be used with either non-DIB section bitmaps or DIB section bitmaps.| -|[CImage::BitBlt](#bitblt)|Copies a bitmap from the source device context to this current device context.| -|[CImage::Create](#create)|Creates a DIB section bitmap and attaches it to the previously constructed `CImage` object.| -|[CImage::CreateEx](#createex)|Creates a DIB section bitmap (with additional parameters) and attaches it to the previously constructed `CImage` object.| -|[CImage::Destroy](#destroy)|Detaches the bitmap from the `CImage` object and destroys the bitmap.| -|[CImage::Detach](#detach)|Detaches the bitmap from a `CImage` object.| -|[CImage::Draw](#draw)|Copies a bitmap from a source rectangle into a destination rectangle. `Draw` stretches or compresses the bitmap to fit the dimensions of the destination rectangle, if necessary, and handles alpha blending and transparent colors.| -|[CImage::GetBits](#getbits)|Retrieves a pointer to the actual pixel values of the bitmap.| -|[CImage::GetBPP](#getbpp)|Retrieves the bits per pixel.| -|[CImage::GetColorTable](#getcolortable)|Retrieves red, green, blue (RGB) color values from a range of entries in the color table.| -|[CImage::GetDC](#getdc)|Retrieves the device context into which the current bitmap is selected.| -|[CImage::GetExporterFilterString](#getexporterfilterstring)|Finds the available image formats and their descriptions.| -|[CImage::GetHeight](#getheight)|Retrieves the height of the current image in pixels.| -|[CImage::GetImporterFilterString](#getimporterfilterstring)|Finds the available image formats and their descriptions.| -|[CImage::GetMaxColorTableEntries](#getmaxcolortableentries)|Retrieves the maximum number of entries in the color table.| -|[CImage::GetPitch](#getpitch)|Retrieves the pitch of the current image, in bytes.| -|[CImage::GetPixel](#getpixel)|Retrieves the color of the pixel specified by *x* and *y*.| -|[CImage::GetPixelAddress](#getpixeladdress)|Retrieves the address of a given pixel.| -|[CImage::GetTransparentColor](#gettransparentcolor)|Retrieves the position of the transparent color in the color table.| -|[CImage::GetWidth](#getwidth)|Retrieves the width of the current image in pixels.| -|[CImage::IsDIBSection](#isdibsection)|Determines if the attached bitmap is a DIB section.| -|[CImage::IsIndexed](#isindexed)|Indicates that a bitmap's colors are mapped to an indexed palette.| -|[CImage::IsNull](#isnull)|Indicates if a source bitmap is currently loaded.| -|[CImage::IsTransparencySupported](#istransparencysupported)|Indicates whether the application supports transparent bitmaps.| -|[CImage::Load](#load)|Loads an image from the specified file.| -|[CImage::LoadFromResource](#loadfromresource)|Loads an image from the specified resource.| -|[CImage::MaskBlt](#maskblt)|Combines the color data for the source and destination bitmaps using the specified mask and raster operation.| -|[CImage::PlgBlt](#plgblt)|Performs a bit-block transfer from a rectangle in a source device context into a parallelogram in a destination device context.| -|[CImage::ReleaseDC](#releasedc)|Releases the device context that was retrieved with [CImage::GetDC](#getdc).| -|[CImage::ReleaseGDIPlus](#releasegdiplus)|Releases resources used by GDI+. Must be called to free resources created by a global `CImage` object.| -|[CImage::Save](#save)|Saves an image as the specified type. `Save` cannot specify image options.| -|[CImage::SetColorTable](#setcolortable)|Sets red, green, blue RGB) color values in a range of entries in the color table of the DIB section.| -|[CImage::SetPixel](#setpixel)|Sets the pixel at the specified coordinates to the specified color.| -|[CImage::SetPixelIndexed](#setpixelindexed)|Sets the pixel at the specified coordinates to the color at the specified index of the palette.| -|[CImage::SetPixelRGB](#setpixelrgb)|Sets the pixel at the specified coordinates to the specified red, green, blue (RGB) value.| -|[CImage::SetTransparentColor](#settransparentcolor)|Sets the index of the color to be treated as transparent. Only one color in a palette can be transparent.| -|[CImage::StretchBlt](#stretchblt)|Copies a bitmap from a source rectangle into a destination rectangle, stretching or compressing the bitmap to fit the dimensions of the destination rectangle, if necessary.| -|[CImage::TransparentBlt](#transparentblt)|Copies a bitmap with transparent color from the source device context to this current device context.| +|[`CImage::AlphaBlend`](#alphablend)|Displays bitmaps that have transparent or semitransparent pixels.| +|[`CImage::Attach`](#attach)|Attaches an `HBITMAP` to a `CImage` object. Can be used with either non-DIB section bitmaps or DIB section bitmaps.| +|[`CImage::BitBlt`](#bitblt)|Copies a bitmap from the source device context to this current device context.| +|[`CImage::Create`](#create)|Creates a DIB section bitmap and attaches it to the previously constructed `CImage` object.| +|[`CImage::CreateEx`](#createex)|Creates a DIB section bitmap (with additional parameters) and attaches it to the previously constructed `CImage` object.| +|[`CImage::Destroy`](#destroy)|Detaches the bitmap from the `CImage` object and destroys the bitmap.| +|[`CImage::Detach`](#detach)|Detaches the bitmap from a `CImage` object.| +|[`CImage::Draw`](#draw)|Copies a bitmap from a source rectangle into a destination rectangle. `Draw` stretches or compresses the bitmap to fit the dimensions of the destination rectangle, if necessary, and handles alpha blending and transparent colors.| +|[`CImage::GetBits`](#getbits)|Retrieves a pointer to the actual pixel values of the bitmap.| +|[`CImage::GetBPP`](#getbpp)|Retrieves the bits per pixel.| +|[`CImage::GetColorTable`](#getcolortable)|Retrieves red, green, blue (RGB) color values from a range of entries in the color table.| +|[`CImage::GetDC`](#getdc)|Retrieves the device context into which the current bitmap is selected.| +|[`CImage::GetExporterFilterString`](#getexporterfilterstring)|Finds the available image formats and their descriptions.| +|[`CImage::GetHeight`](#getheight)|Retrieves the height of the current image in pixels.| +|[`CImage::GetImporterFilterString`](#getimporterfilterstring)|Finds the available image formats and their descriptions.| +|[`CImage::GetMaxColorTableEntries`](#getmaxcolortableentries)|Retrieves the maximum number of entries in the color table.| +|[`CImage::GetPitch`](#getpitch)|Retrieves the pitch of the current image, in bytes.| +|[`CImage::GetPixel`](#getpixel)|Retrieves the color of the pixel specified by *`x`* and *`y`*.| +|[`CImage::GetPixelAddress`](#getpixeladdress)|Retrieves the address of a given pixel.| +|[`CImage::GetTransparentColor`](#gettransparentcolor)|Retrieves the position of the transparent color in the color table.| +|[`CImage::GetWidth`](#getwidth)|Retrieves the width of the current image in pixels.| +|[`CImage::IsDIBSection`](#isdibsection)|Determines if the attached bitmap is a DIB section.| +|[`CImage::IsIndexed`](#isindexed)|Indicates that a bitmap's colors are mapped to an indexed palette.| +|[`CImage::IsNull`](#isnull)|Indicates if a source bitmap is currently loaded.| +|[`CImage::IsTransparencySupported`](#istransparencysupported)|Indicates whether the application supports transparent bitmaps.| +|[`CImage::Load`](#load)|Loads an image from the specified file.| +|[`CImage::LoadFromResource`](#loadfromresource)|Loads an image from the specified resource.| +|[`CImage::MaskBlt`](#maskblt)|Combines the color data for the source and destination bitmaps using the specified mask and raster operation.| +|[`CImage::PlgBlt`](#plgblt)|Performs a bit-block transfer from a rectangle in a source device context into a parallelogram in a destination device context.| +|[`CImage::ReleaseDC`](#releasedc)|Releases the device context that was retrieved with [`CImage::GetDC`](#getdc).| +|[`CImage::ReleaseGDIPlus`](#releasegdiplus)|Releases resources used by GDI+. Must be called to free resources created by a global `CImage` object.| +|[`CImage::Save`](#save)|Saves an image as the specified type. `Save` cannot specify image options.| +|[`CImage::SetColorTable`](#setcolortable)|Sets red, green, blue RGB) color values in a range of entries in the color table of the DIB section.| +|[`CImage::SetPixel`](#setpixel)|Sets the pixel at the specified coordinates to the specified color.| +|[`CImage::SetPixelIndexed`](#setpixelindexed)|Sets the pixel at the specified coordinates to the color at the specified index of the palette.| +|[`CImage::SetPixelRGB`](#setpixelrgb)|Sets the pixel at the specified coordinates to the specified red, green, blue (RGB) value.| +|[`CImage::SetTransparentColor`](#settransparentcolor)|Sets the index of the color to be treated as transparent. Only one color in a palette can be transparent.| +|[`CImage::StretchBlt`](#stretchblt)|Copies a bitmap from a source rectangle into a destination rectangle, stretching or compressing the bitmap to fit the dimensions of the destination rectangle, if necessary.| +|[`CImage::TransparentBlt`](#transparentblt)|Copies a bitmap with transparent color from the source device context to this current device context.| ### Public Operators |Name|Description| |----------|-----------------| -|[CImage::operator HBITMAP](#operator_hbitmap)|Returns the Windows handle attached to the `CImage` object.| +|[`CImage::operator HBITMAP`](#operator_hbitmap)|Returns the Windows handle attached to the `CImage` object.| ## Remarks -`CImage` takes bitmaps that are either device-independent bitmap (DIB) sections or not; however, you can use [Create](#create) or [CImage::Load](#load) with only DIB sections. You can attach a non-DIB section bitmap to a `CImage` object using [Attach](#attach), but then you cannot use the following `CImage` methods, which support only DIB section bitmaps: +`CImage` takes bitmaps that are either device-independent bitmap (DIB) sections or not; however, you can use [`Create`](#create) or [`CImage::Load`](#load) with only DIB sections. You can attach a non-DIB section bitmap to a `CImage` object using [`Attach`](#attach), but then you cannot use the following `CImage` methods, which support only DIB section bitmaps: -- [GetBits](#getbits) +- [`GetBits`](#getbits) -- [GetColorTable](#getcolortable) +- [`GetColorTable`](#getcolortable) -- [GetMaxColorTableEntries](#getmaxcolortableentries) +- [`GetMaxColorTableEntries`](#getmaxcolortableentries) -- [GetPitch](#getpitch) +- [`GetPitch`](#getpitch) -- [GetPixelAddress](#getpixeladdress) +- [`GetPixelAddress`](#getpixeladdress) -- [IsIndexed](#isindexed) +- [`IsIndexed`](#isindexed) -- [SetColorTable](#setcolortable) +- [`SetColorTable`](#setcolortable) -To determine if an attached bitmap is a DIB section, call [IsDibSection](#isdibsection). +To determine if an attached bitmap is a DIB section, call [`IsDibSection`](#isdibsection). > [!NOTE] > In Visual Studio .NET 2003, this class keeps a count of the number of `CImage` objects created. Whenever the count goes to 0, the function `GdiplusShutdown` is automatically called to release resources used by GDI+. This ensures that any `CImage` objects created directly or indirectly by DLLs are always destroyed properly and that `GdiplusShutdown` is not called from `DllMain`. > [!NOTE] -> Using global `CImage` objects in a DLL is not recommended. If you need to use a global `CImage` object in a DLL, call [CImage::ReleaseGDIPlus](#releasegdiplus) to explicitly release resources used by GDI+. +> Using global `CImage` objects in a DLL is not recommended. If you need to use a global `CImage` object in a DLL, call [`CImage::ReleaseGDIPlus`](#releasegdiplus) to explicitly release resources used by GDI+. -`CImage` cannot be selected into a new [CDC](../../mfc/reference/cdc-class.md). `CImage` creates its own HDC for the image. Because an HBITMAP can only be selected into one HDC at a time, the HBITMAP associated with the `CImage` cannot be selected into another HDC. If you need a CDC, retrieve the HDC from the `CImage` and give it to [CDC::FromHandle](../../mfc/reference/cdc-class.md#fromhandle). +`CImage` cannot be selected into a new [`CDC`](../../mfc/reference/cdc-class.md). `CImage` creates its own `HDC` for the image. Because an `HBITMAP` can only be selected into one `HDC` at a time, the `HBITMAP` associated with the `CImage` cannot be selected into another `HDC`. If you need a `CDC`, retrieve the `HDC` from the `CImage` and give it to [`CDC::FromHandle`](../../mfc/reference/cdc-class.md#fromhandle). ## Examples @@ -116,7 +116,7 @@ pDC->Rectangle(0, 40, 100, 50); m_myImage.ReleaseDC(); ``` -When you use `CImage` in an MFC project, note which member functions in your project expect a pointer to a [CBitmap](../../mfc/reference/cbitmap-class.md) object. If you want to use `CImage` with such a function, like [CMenu::AppendMenu](../../mfc/reference/cmenu-class.md#appendmenu), use [CBitmap::FromHandle](../../mfc/reference/cbitmap-class.md#fromhandle), pass it your `CImage` HBITMAP, and use the returned `CBitmap*`. +When you use `CImage` in an MFC project, note which member functions in your project expect a pointer to a [`CBitmap`](../../mfc/reference/cbitmap-class.md) object. If you want to use `CImage` with such a function, like [`CMenu::AppendMenu`](../../mfc/reference/cmenu-class.md#appendmenu), use [`CBitmap::FromHandle`](../../mfc/reference/cbitmap-class.md#fromhandle), pass it your `CImage` `HBITMAP`, and use the returned `CBitmap*`. ```cpp void CMyDlg::OnRButtonDown(UINT nFlags, CPoint point) @@ -131,24 +131,24 @@ void CMyDlg::OnRButtonDown(UINT nFlags, CPoint point) } ``` -Through `CImage`, you have access to the actual bits of a DIB section. You can use a `CImage` object anywhere you previously used a Win32 HBITMAP or DIB section. +Through `CImage`, you have access to the actual bits of a DIB section. You can use a `CImage` object anywhere you previously used a Win32 `HBITMAP` or DIB section. You can use `CImage` from either MFC or ATL. > [!NOTE] -> When you create a project using `CImage`, you must define `CString` before you include *atlimage.h*. If your project uses ATL without MFC, include *atlstr.h* before you include *atlimage.h*. If your project uses MFC (or if it is an ATL project with MFC support), include *afxstr.h* before you include *atlimage.h*. +> When you create a project using `CImage`, you must define `CString` before you include *`atlimage.h`*. If your project uses ATL without MFC, include *`atlstr.h`* before you include *`atlimage.h`*. If your project uses MFC (or if it is an ATL project with MFC support), include *`afxstr.h`* before you include *`atlimage.h`*. > -> Likewise, you must include *atlimage.h* before you include *atlimpl.cpp*. To accomplish this easily, include *atlimage.h* in your *pch.h* (*stdafx.h* in Visual Studio 2017 and earlier). +> Likewise, you must include *`atlimage.h`* before you include *`atlimpl.cpp`*. To accomplish this easily, include *`atlimage.h`* in your *`pch.h`* (*`stdafx.h`* in Visual Studio 2017 and earlier). ## Requirements -**Header:** atlimage.h +**Header:** `atlimage.h` -## CImage::AlphaBlend +## `CImage::AlphaBlend` Displays bitmaps that have transparent or semitransparent pixels. -``` +```cpp BOOL AlphaBlend( HDC hDestDC, int xDest, @@ -185,46 +185,46 @@ BOOL AlphaBlend( ### Parameters -*hDestDC*
+*`hDestDC`*
Handle to the destination device context. -*xDest*
+*`xDest`*
The x-coordinate, in logical units, of the upper left corner of the destination rectangle. -*yDest*
+*`yDest`*
The y-coordinate, in logical units, of the upper left corner of the destination rectangle. -*bSrcAlpha*
+*`bSrcAlpha`*
An alpha transparency value to be used on the entire source bitmap. The default 0xff (255) assumes that your image is opaque, and that you want to use per-pixel alpha values only. -*bBlendOp*
-The alpha-blending function for source and destination bitmaps, a global alpha value to be applied to the entire source bitmap, and format information for the source bitmap. The source and destination blend functions are currently limited to AC_SRC_OVER. +*`bBlendOp`*
+The alpha-blending function for source and destination bitmaps, a global alpha value to be applied to the entire source bitmap, and format information for the source bitmap. The source and destination blend functions are currently limited to `AC_SRC_OVER`. -*pointDest*
-A reference to a [POINT](/windows/win32/api/windef/ns-windef-point) structure that identifies the upper left corner of the destination rectangle, in logical units. +*`pointDest`*
+A reference to a [`POINT`](/windows/win32/api/windef/ns-windef-point) structure that identifies the upper left corner of the destination rectangle, in logical units. -*nDestWidth*
+*`nDestWidth`*
The width, in logical units, of the destination rectangle. -*nDestHeight*
+*`nDestHeight`*
The height, in logical units, of the destination rectangle. -*xSrc*
+*`xSrc`*
The logical x-coordinate of the upper left corner of the source rectangle. -*ySrc*
+*`ySrc`*
The logical y-coordinate of the upper left corner of the source rectangle. -*nSrcWidth*
+*`nSrcWidth`*
The width, in logical units, of the source rectangle. -*nSrcHeight*
+*`nSrcHeight`*
The height, in logical units, of the source rectangle. -*rectDest*
-A reference to a [RECT](/windows/win32/api/windef/ns-windef-rect) structure, identifying the destination. +*`rectDest`*
+A reference to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure, identifying the destination. -*rectSrc*
+*`rectSrc`*
A reference to a `RECT` structure, identifying the source. ### Return Value @@ -235,11 +235,11 @@ Nonzero if successful; otherwise 0. Alpha-blend bitmaps support color blending on a per-pixel basis. -When *bBlendOp* is set to the default of AC_SRC_OVER, the source bitmap is placed over the destination bitmap based on the alpha values of the source pixels. +When *`bBlendOp`* is set to the default of `AC_SRC_OVER`, the source bitmap is placed over the destination bitmap based on the alpha values of the source pixels. -## CImage::Attach +## `CImage::Attach` -Attaches *hBitmap* to a `CImage` object. +Attaches *`hBitmap`* to a `CImage` object. ```cpp void Attach(HBITMAP hBitmap, DIBOrientation eOrientation = DIBOR_DEFAULT) throw(); @@ -247,27 +247,27 @@ void Attach(HBITMAP hBitmap, DIBOrientation eOrientation = DIBOR_DEFAULT) throw( ### Parameters -*hBitmap*
-A handle to an HBITMAP. +*`hBitmap`*
+A handle to an `HBITMAP`. -*eOrientation*
+*`eOrientation`*
Specifies the orientation of the bitmap. Can be one of the following: -- DIBOR_DEFAULT The orientation of the bitmap is determined by the operating system. +- `DIBOR_DEFAULT` The orientation of the bitmap is determined by the operating system. -- DIBOR_BOTTOMUP The lines of the bitmap are in reverse order. This causes [CImage::GetBits](#getbits) to return a pointer near the end of the bitmap buffer and [CImage::GetPitch](#getpitch) to return a negative number. +- `DIBOR_BOTTOMUP` The lines of the bitmap are in reverse order. This causes [`CImage::GetBits`](#getbits) to return a pointer near the end of the bitmap buffer and [`CImage::GetPitch`](#getpitch) to return a negative number. -- DIBOR_TOPDOWN The lines of the bitmap are in top to bottom order. This causes [CImage::GetBits](#getbits) to return a pointer to the first byte of the bitmap buffer and [CImage::GetPitch](#getpitch) to return a positive number. +- `DIBOR_TOPDOWN` The lines of the bitmap are in top to bottom order. This causes [`CImage::GetBits`](#getbits) to return a pointer to the first byte of the bitmap buffer and [`CImage::GetPitch`](#getpitch) to return a positive number. ### Remarks -The bitmap can be either a non-DIB section bitmap or a DIB section bitmap. See [IsDIBSection](#isdibsection) for a list of methods that you can use only with DIB section bitmaps. +The bitmap can be either a non-DIB section bitmap or a DIB section bitmap. See [`IsDIBSection`](#isdibsection) for a list of methods that you can use only with DIB section bitmaps. -## CImage::BitBlt +## `CImage::BitBlt` Copies a bitmap from the source device context to this current device context. -``` +```cpp BOOL BitBlt( HDC hDestDC, int xDest, @@ -298,37 +298,37 @@ BOOL BitBlt( ### Parameters -*hDestDC*
-The destination HDC. +*`hDestDC`*
+The destination `HDC`. -*xDest*
+*`xDest`*
The logical x-coordinate of the upper left corner of the destination rectangle. -*yDest*
+*`yDest`*
The logical y-coordinate of the upper left corner of the destination rectangle. -*dwROP*
-The raster operation to be performed. Raster-operation codes define exactly how to combine the bits of the source, the destination, and the pattern (as defined by the currently selected brush) to form the destination. See [BitBlt](/windows/win32/api/wingdi/nf-wingdi-bitblt) in the Windows SDK for a list of other raster-operation codes and their descriptions. +*`dwROP`*
+The raster operation to be performed. Raster-operation codes define exactly how to combine the bits of the source, the destination, and the pattern (as defined by the currently selected brush) to form the destination. See [`BitBlt`](/windows/win32/api/wingdi/nf-wingdi-bitblt) in the Windows SDK for a list of other raster-operation codes and their descriptions. -*pointDest*
-A [POINT](/windows/win32/api/windef/ns-windef-point) structure indicating the upper left corner of the destination rectangle. +*`pointDest`*
+A [`POINT`](/windows/win32/api/windef/ns-windef-point) structure indicating the upper left corner of the destination rectangle. -*nDestWidth*
+*`nDestWidth`*
The width, in logical units, of the destination rectangle. -*nDestHeight*
+*`nDestHeight`*
The height, in logical units, of the destination rectangle. -*xSrc*
+*`xSrc`*
The logical x-coordinate of the upper left corner of the source rectangle. -*ySrc*
+*`ySrc`*
The logical y-coordinate of the upper left corner of the source rectangle. -*rectDest*
-A [RECT](/windows/win32/api/windef/ns-windef-rect) structure indicating the destination rectangle. +*`rectDest`*
+A [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure indicating the destination rectangle. -*pointSrc*
+*`pointSrc`*
A `POINT` structure indicating the upper left corner of the source rectangle. ### Return Value @@ -337,29 +337,29 @@ Nonzero if successful; otherwise zero. ### Remarks -For more information, see [BitBlt](/windows/win32/api/wingdi/nf-wingdi-bitblt) in the Windows SDK. +For more information, see [`BitBlt`](/windows/win32/api/wingdi/nf-wingdi-bitblt) in the Windows SDK. -## CImage::CImage +## `CImage::CImage` Constructs a `CImage` object. -``` +```cpp CImage() throw(); ``` ### Remarks -Once you have constructed the object, call [Create](#create), [Load](#load), [LoadFromResource](#loadfromresource), or [Attach](#attach) to attach a bitmap to the object. +Once you have constructed the object, call [`Create`](#create), [`Load`](#load), [`LoadFromResource`](#loadfromresource), or [`Attach`](#attach) to attach a bitmap to the object. **Note** In Visual Studio, this class keeps a count of the number of `CImage` objects created. Whenever the count goes to 0, the function `GdiplusShutdown` is automatically called to release resources used by GDI+. This ensures that any `CImage` objects created directly or indirectly by DLLs are always destroyed properly and that `GdiplusShutdown` is not called from DllMain. -Using global `CImage` objects in a DLL is not recommended. If you need to use a global `CImage` object in a DLL, call [CImage::ReleaseGDIPlus](#releasegdiplus) to explicitly release resources used by GDI+. +Using global `CImage` objects in a DLL is not recommended. If you need to use a global `CImage` object in a DLL, call [`CImage::ReleaseGDIPlus`](#releasegdiplus) to explicitly release resources used by GDI+. -## CImage::Create +## `CImage::Create` Creates a `CImage` bitmap and attach it to the previously constructed `CImage` object. -``` +```cpp BOOL Create( int nWidth, int nHeight, @@ -369,32 +369,32 @@ BOOL Create( ### Parameters -*nWidth*
+*`nWidth`*
The width of the `CImage` bitmap, in pixels. -*nHeight*
-The height of the `CImage` bitmap, in pixels. If *nHeight* is positive, the bitmap is a bottom-up DIB and its origin is the lower left corner. If *nHeight* is negative, the bitmap is a top-down DIB and its origin is the upper left corner. +*`nHeight`*
+The height of the `CImage` bitmap, in pixels. If *`nHeight`* is positive, the bitmap is a bottom-up DIB and its origin is the lower left corner. If *`nHeight`* is negative, the bitmap is a top-down DIB and its origin is the upper left corner. -*nBPP*
+*`nBPP`*
The numbers of bits per pixel in the bitmap. Usually 4, 8, 16, 24, or 32. Can be 1 for monochrome bitmaps or masks. -*dwFlags*
+*`dwFlags`*
Specifies if the bitmap object has an alpha channel. Can be a combination of zero or more of the following values: -- *createAlphaChannel* Can only be used if *nBPP* is 32, and *eCompression* is BI_RGB. If specified, the created image has an alpha (transparency) value for each pixel, stored in the 4th byte of each pixel (unused in a non-alpha 32-bit image). This alpha channel is automatically used when calling [CImage::AlphaBlend](#alphablend). +- *`createAlphaChannel`* Can only be used if *`nBPP`* is 32, and *`eCompression`* is `BI_RGB`. If specified, the created image has an alpha (transparency) value for each pixel, stored in the 4th byte of each pixel (unused in a non-alpha 32-bit image). This alpha channel is automatically used when calling [`CImage::AlphaBlend`](#alphablend). > [!NOTE] -> In calls to [CImage::Draw](#draw), images with an alpha channel are automatically alpha blended to the destination. +> In calls to [`CImage::Draw`](#draw), images with an alpha channel are automatically alpha blended to the destination. ### Return Value Nonzero if successful; otherwise 0. -## CImage::CreateEx +## `CImage::CreateEx` Creates a `CImage` bitmap and attach it to the previously constructed `CImage` object. -``` +```cpp BOOL CreateEx( int nWidth, int nHeight, @@ -406,36 +406,36 @@ BOOL CreateEx( ### Parameters -*nWidth*
+*`nWidth`*
The width of the `CImage` bitmap, in pixels. -*nHeight*
-The height of the `CImage` bitmap, in pixels. If *nHeight* is positive, the bitmap is a bottom-up DIB and its origin is the lower left corner. If *nHeight* is negative, the bitmap is a top-down DIB and its origin is the upper left corner. +*`nHeight`*
+The height of the `CImage` bitmap, in pixels. If *`nHeight`* is positive, the bitmap is a bottom-up DIB and its origin is the lower left corner. If *`nHeight`* is negative, the bitmap is a top-down DIB and its origin is the upper left corner. -*nBPP*
+*`nBPP`*
The numbers of bits per pixel in the bitmap. Usually 4, 8, 16, 24, or 32. Can be 1 for monochrome bitmaps or masks. -*eCompression*
+*`eCompression`*
Specifies the type of compression for a compressed bottom-up bitmap (top-down DIBs cannot be compressed). Can be one of the following values: -- BI_RGB The format is uncompressed. Specifying this value when calling `CImage::CreateEx` is equivalent to calling `CImage::Create`. +- `BI_RGB` The format is uncompressed. Specifying this value when calling `CImage::CreateEx` is equivalent to calling `CImage::Create`. -- BI_BITFIELDS The format is uncompressed and the color table consists of three DWORD color masks that specify the red, green, and blue components, respectively, of each pixel. This is valid when used with 16- and 32-bpp bitmaps. +- `BI_BITFIELDS` The format is uncompressed and the color table consists of three `DWORD` color masks that specify the red, green, and blue components, respectively, of each pixel. This is valid when used with 16- and 32-bpp bitmaps. -*pdwBitfields*
-Only used if *eCompression* is set to BI_BITFIELDS, otherwise it must be NULL. A pointer to an array of three DWORD bitmasks, specifying which bits of each pixel are used for the red, green, and blue components of the color, respectively. For information on restrictions for the bitfields, see [BITMAPINFOHEADER](/windows/win32/api/wingdi/ns-wingdi-bitmapinfoheader) in the Windows SDK. +*`pdwBitfields`*
+Only used if *`eCompression`* is set to `BI_BITFIELDS`, otherwise it must be `NULL`. A pointer to an array of three `DWORD` bitmasks, specifying which bits of each pixel are used for the red, green, and blue components of the color, respectively. For information on restrictions for the bitfields, see [`BITMAPINFOHEADER`](/windows/win32/api/wingdi/ns-wingdi-bitmapinfoheader) in the Windows SDK. -*dwFlags*
+*`dwFlags`*
Specifies if the bitmap object has an alpha channel. Can be a combination of zero or more of the following values: -- *createAlphaChannel* Can only be used if *nBPP* is 32, and *eCompression* is BI_RGB. If specified, the created image has an alpha (transparency) value for each pixel, stored in the 4th byte of each pixel (unused in a non-alpha 32-bit image). This alpha channel is automatically used when calling [CImage::AlphaBlend](#alphablend). +- *`createAlphaChannel`* Can only be used if *`nBPP`* is 32, and *`eCompression`* is `BI_RGB`. If specified, the created image has an alpha (transparency) value for each pixel, stored in the 4th byte of each pixel (unused in a non-alpha 32-bit image). This alpha channel is automatically used when calling [`CImage::AlphaBlend`](#alphablend). > [!NOTE] - > In calls to [CImage::Draw](#draw), images with an alpha channel are automatically alpha blended to the destination. + > In calls to [`CImage::Draw`](#draw), images with an alpha channel are automatically alpha blended to the destination. ### Return Value -TRUE if successful. Otherwise FALSE. +`TRUE` if successful. Otherwise `FALSE`. ### Example @@ -446,7 +446,7 @@ DWORD adwBitmasks[3] = { 0x0000000f, 0x000000f0, 0x00000f00 }; m_myImage.CreateEx(100, 100, 16, BI_BITFIELDS, adwBitmasks, 0); ``` -## CImage::Destroy +## `CImage::Destroy` Detaches the bitmap from the `CImage` object and destroys the bitmap. @@ -454,23 +454,23 @@ Detaches the bitmap from the `CImage` object and destroys the bitmap. void Destroy() throw(); ``` -## CImage::Detach +## `CImage::Detach` Detaches a bitmap from a `CImage` object. -``` +```cpp HBITMAP Detach() throw(); ``` ### Return Value -A handle to the bitmap detached, or NULL if no bitmap is attached. +A handle to the bitmap detached, or `NULL` if no bitmap is attached. -## CImage::Draw +## `CImage::Draw` Copies a bitmap from the source device context to the current device context. -``` +```cpp BOOL Draw( HDC hDestDC, int xDest, @@ -510,41 +510,41 @@ BOOL Draw( ### Parameters -*hDestDC*
+*`hDestDC`*
A handle to the destination device context. -*xDest*
+*`xDest`*
The x-coordinate, in logical units, of the upper left corner of the destination rectangle. -*yDest*
+*`yDest`*
The y-coordinate, in logical units, of the upper left corner of the destination rectangle. -*nDestWidth*
+*`nDestWidth`*
The width, in logical units, of the destination rectangle. -*nDestHeight*
+*`nDestHeight`*
The height, in logical units, of the destination rectangle. -*xSrc*
+*`xSrc`*
The x-coordinate, in logical units, of the upper left corner of the source rectangle. -*ySrc*
+*`ySrc`*
The y-coordinate, in logical units, of the upper left corner of the source rectangle. -*nSrcWidth*
+*`nSrcWidth`*
The width, in logical units, of the source rectangle. -*nSrcHeight*
+*`nSrcHeight`*
The height, in logical units, of the source rectangle. -*rectDest*
-A reference to a [RECT](/windows/win32/api/windef/ns-windef-rect) structure, identifying the destination. +*`rectDest`*
+A reference to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure, identifying the destination. -*rectSrc*
+*`rectSrc`*
A reference to a `RECT` structure, identifying the source. -*pointDest*
-A reference to a [POINT](/windows/win32/api/windef/ns-windef-point) structure that identifies the upper left corner of the destination rectangle, in logical units. +*`pointDest`*
+A reference to a [`POINT`](/windows/win32/api/windef/ns-windef-point) structure that identifies the upper left corner of the destination rectangle, in logical units. ### Return Value @@ -552,11 +552,11 @@ Nonzero if successful; otherwise 0. ### Remarks -`Draw` performs the same operation as [StretchBlt](#stretchblt), unless the image contains a transparent color or alpha channel. In that case, `Draw` performs the same operation as either [TransparentBlt](#transparentblt) or [AlphaBlend](#alphablend) as required. +`Draw` performs the same operation as [`StretchBlt`](#stretchblt), unless the image contains a transparent color or alpha channel. In that case, `Draw` performs the same operation as either [`TransparentBlt`](#transparentblt) or [`AlphaBlend`](#alphablend) as required. For versions of `Draw` that do not specify a source rectangle, the entire source image is the default. For the version of `Draw` that does not specify a size for the destination rectangle, the size of the source image is the default and no stretching or shrinking occurs. -## CImage::GetBits +## `CImage::GetBits` Retrieves a pointer to the actual bit values of a given pixel in a bitmap. @@ -570,16 +570,16 @@ A pointer to the bitmap buffer. If the bitmap is a bottom-up DIB, the pointer po ### Remarks -Using this pointer, along with the value returned by [GetPitch](#getpitch), you can locate and change individual pixels in an image. +Using this pointer, along with the value returned by [`GetPitch`](#getpitch), you can locate and change individual pixels in an image. > [!NOTE] > This method supports only DIB section bitmaps; consequently, you access the pixels of a `CImage` object the same way you would the pixels of a DIB section. The returned pointer points to the pixel at the location (0, 0). -## CImage::GetBPP +## `CImage::GetBPP` Retrieves the bits-per-pixel value. -``` +```cpp int GetBPP() const throw(); ``` @@ -591,9 +591,9 @@ The number of bits per pixel. This value determines the number of bits that define each pixel and the maximum number of colors in the bitmap. -The bits per pixel is usually 1, 4, 8, 16, 24, or 32. See the `biBitCount` member of [BITMAPINFOHEADER](/windows/win32/api/wingdi/ns-wingdi-bitmapinfoheader) in the Windows SDK for more information about this value. +The bits per pixel is usually 1, 4, 8, 16, 24, or 32. See the `biBitCount` member of [`BITMAPINFOHEADER`](/windows/win32/api/wingdi/ns-wingdi-bitmapinfoheader) in the Windows SDK for more information about this value. -## CImage::GetColorTable +## `CImage::GetColorTable` Retrieves red, green, blue (RGB) color values from a range of entries in the palette of the DIB section. @@ -606,20 +606,20 @@ void GetColorTable( ### Parameters -*iFirstColor*
+*`iFirstColor`*
The color table index of the first entry to retrieve. -*nColors*
+*`nColors`*
The number of color table entries to retrieve. -*prgbColors*
-A pointer to the array of [RGBQUAD](/windows/win32/api/wingdi/ns-wingdi-rgbquad) structures to retrieve the color table entries. +*`prgbColors`*
+A pointer to the array of [`RGBQUAD`](/windows/win32/api/wingdi/ns-wingdi-rgbquad) structures to retrieve the color table entries. -## CImage::GetDC +## `CImage::GetDC` Retrieves the device context that currently has the image selected into it. -``` +```cpp HDC GetDC() const throw(); ``` @@ -629,13 +629,13 @@ A handle to a device context. ### Remarks -For each call to `GetDC`, you must have a subsequent call to [ReleaseDC](#releasedc). +For each call to `GetDC`, you must have a subsequent call to [`ReleaseDC`](#releasedc). -## CImage::GetExporterFilterString +## `CImage::GetExporterFilterString` Finds image formats available for saving images. -``` +```cpp static HRESULT GetExporterFilterString( CSimpleString& strExporters, CSimpleArray& aguidFileTypes, @@ -646,17 +646,17 @@ static HRESULT GetExporterFilterString( ### Parameters -*strExporters*
+*`strExporters`*
A reference to a `CSimpleString` object. See **Remarks** for more information. -*aguidFileTypes*
-An array of GUIDs, with each element corresponding to one of the file types in the string. In the example in *pszAllFilesDescription* below, *aguidFileTypes*[0] is GUID_NULL and the remaining array values are the image file formats supported by the current operating system. +*`aguidFileTypes`*
+An array of GUIDs, with each element corresponding to one of the file types in the string. In the example in *`pszAllFilesDescription`* below, *`aguidFileTypes[0]`* is `GUID_NULL` and the remaining array values are the image file formats supported by the current operating system. > [!NOTE] > For a complete list of constants, see **Image File Format Constants** in the Windows SDK. -*pszAllFilesDescription*
-If this parameter is not NULL, the filter string will have one additional filter at the beginning of the list. This filter will have the current value of *pszAllFilesDescription* for its description, and accepts files of any extension supported by any other exporter in the list. +*`pszAllFilesDescription`*
+If this parameter is not `NULL`, the filter string will have one additional filter at the beginning of the list. This filter will have the current value of *`pszAllFilesDescription`* for its description, and accepts files of any extension supported by any other exporter in the list. For example: @@ -668,7 +668,7 @@ CImage::GetExporterFilterString( _T("All Image Files")); ``` -*dwExclude*
+*`dwExclude`*
Set of bit flags specifying which file types to exclude from the list. Allowable flags are: - `excludeGIF` = 0x01 Excludes GIF files. @@ -691,34 +691,34 @@ Set of bit flags specifying which file types to exclude from the list. Allowable - `excludeDefaultLoad` = 0 For load, all file types are included by default -- `excludeDefaultSave` = `excludeIcon | excludeEMF | excludeWMF` For saving, these files are excluded by default because they usually have special requirements. +- `excludeDefaultSave` = `excludeIcon | excludeEMF | excludeWMF` For saving, these files are excluded by default because they usually have special requirements. -*chSeparator*
+*`chSeparator`*
The separator used between the image formats. See **Remarks** for more information. ### Return Value -A standard HRESULT. +A standard `HRESULT`. ### Remarks -You can pass the resulting format string to your MFC [CFileDialog](../../mfc/reference/cfiledialog-class.md) object to expose the file extensions of the available image formats in the File Save As dialog box. +You can pass the resulting format string to your MFC [`CFileDialog`](../../mfc/reference/cfiledialog-class.md) object to expose the file extensions of the available image formats in the File Save As dialog box. -The parameter *strExporter* has the format: +The parameter *`strExporter`* has the format: -file description0|\*.ext0|filedescription1|\*.ext1|...file description *n*|\*.ext *n*|| +`file description 0|*.ext0|file description 1|*.ext1|...file description N|*.extN||` -where '|' is the separator character specified by `chSeparator`. For example: +where `|` is the separator character specified by `chSeparator`. For example: `"Bitmap format|*.bmp|JPEG format|*.jpg|GIF format|*.gif|PNG format|*.png||"` -Use the default separator '|' if you pass this string to an MFC `CFileDialog` object. Use the null separator '\0' if you pass this string to a common File Save dialog box. +Use the default separator `|` if you pass this string to an MFC `CFileDialog` object. Use the null separator `'\0'` if you pass this string to a common File Save dialog box. -## CImage::GetHeight +## `CImage::GetHeight` Retrieves the height, in pixels, of an image. -``` +```cpp int GetHeight() const throw(); ``` @@ -726,11 +726,11 @@ int GetHeight() const throw(); The height, in pixels, of an image. -## CImage::GetImporterFilterString +## `CImage::GetImporterFilterString` Finds image formats available for loading images. -``` +```cpp static HRESULT GetImporterFilterString( CSimpleString& strImporters, CSimpleArray& aguidFileTypes, @@ -741,17 +741,17 @@ static HRESULT GetImporterFilterString( ### Parameters -*strImporters*
+*`strImporters`*
A reference to a `CSimpleString` object. See **Remarks** for more information. -*aguidFileTypes*
-An array of GUIDs, with each element corresponding to one of the file types in the string. In the example in *pszAllFilesDescription* below, *aguidFileTypes*[0] is GUID_NULL with the remaining array values are the image file formats supported by the current operating system. +*`aguidFileTypes`*
+An array of GUIDs, with each element corresponding to one of the file types in the string. In the example in *`pszAllFilesDescription`* below, *`aguidFileTypes[0]*` is `GUID_NULL` with the remaining array values are the image file formats supported by the current operating system. > [!NOTE] > For a complete list of constants, see **Image File Format Constants** in the Windows SDK. -*pszAllFilesDescription*
-If this parameter is not NULL, the filter string will have one additional filter at the beginning of the list. This filter will have the current value of *pszAllFilesDescription* for its description, and accepts files of any extension supported by any other exporter in the list. +*`pszAllFilesDescription`*
+If this parameter is not `NULL`, the filter string will have one additional filter at the beginning of the list. This filter will have the current value of *`pszAllFilesDescription`* for its description, and accepts files of any extension supported by any other exporter in the list. For example: @@ -763,7 +763,7 @@ CImage::GetImporterFilterString( _T("All Image Files")); ``` -*dwExclude*
+*`dwExclude`*
Set of bit flags specifying which file types to exclude from the list. Allowable flags are: - `excludeGIF` = 0x01 Excludes GIF files. @@ -786,30 +786,30 @@ Set of bit flags specifying which file types to exclude from the list. Allowable - `excludeDefaultLoad` = 0 For load, all file types are included by default -- `excludeDefaultSave` = `excludeIcon | excludeEMF | excludeWMF` For saving, these files are excluded by default because they usually have special requirements. +- `excludeDefaultSave` = `excludeIcon | excludeEMF | excludeWMF` For saving, these files are excluded by default because they usually have special requirements. -*chSeparator*
+*`chSeparator`*
The separator used between the image formats. See **Remarks** for more information. ### Remarks -You can pass the resulting format string to your MFC [CFileDialog](../../mfc/reference/cfiledialog-class.md) object to expose the file extensions of the available image formats in the **File Open** dialog box. +You can pass the resulting format string to your MFC [`CFileDialog`](../../mfc/reference/cfiledialog-class.md) object to expose the file extensions of the available image formats in the **File Open** dialog box. -The parameter *strImporter* has the format: +The parameter *`strImporter`* has the format: -file description0|\*.ext0|filedescription1|\*.ext1|...file description *n*|\*.ext *n*|| +`file description 0|*.ext0|file description 1|*.ext1|...file description N|*.extN|| -where '|' is the separator character specified by *chSeparator*. For example: +where `|` is the separator character specified by *`chSeparator`*. For example: `"Bitmap format|*.bmp|JPEG format|*.jpg|GIF format|*.gif|PNG format|*.png||"` -Use the default separator '|' if you pass this string to an MFC `CFileDialog` object. Use the null separator '\0' if you pass this string to a common **File Open** dialog box. +Use the default separator `|` if you pass this string to an MFC `CFileDialog` object. Use the null separator `'\0'` if you pass this string to a common **File Open** dialog box. -## CImage::GetMaxColorTableEntries +## `CImage::GetMaxColorTableEntries` Retrieves the maximum number of entries in the color table. -``` +```cpp int GetMaxColorTableEntries() const throw(); ``` @@ -821,11 +821,11 @@ The number of entries in the color table. This method supports only DIB section bitmaps. -## CImage::GetPitch +## `CImage::GetPitch` Retrieves the pitch of an image. -``` +```cpp int GetPitch() const throw(); ``` @@ -837,32 +837,32 @@ The pitch of the image. If the return value is negative, the bitmap is a bottom- The pitch is the distance, in bytes, between two memory addresses that represent the beginning of one bitmap line and the beginning of the next bitmap line. Because pitch is measured in bytes, the pitch of an image helps you to determine the pixel format. The pitch can also include additional memory, reserved for the bitmap. -Use `GetPitch` with [GetBits](#getbits) to find individual pixels of an image. +Use `GetPitch` with [`GetBits`](#getbits) to find individual pixels of an image. > [!NOTE] > This method supports only DIB section bitmaps. -## CImage::GetPixel +## `CImage::GetPixel` Retrieves the color of the pixel at the location specified by *x* and *y*. -``` +```cpp COLORREF GetPixel(int x, int y) const throw(); ``` ### Parameters -*x*
+*`x`*
The x-coordinate of the pixel. -*y*
+*`y`*
The y-coordinate of the pixel. ### Return Value -The red, green, blue (RGB) value of the pixel. If the pixel is outside of the current clipping region, the return value is CLR_INVALID. +The red, green, blue (RGB) value of the pixel. If the pixel is outside of the current clipping region, the return value is `CLR_INVALID`. -## CImage::GetPixelAddress +## `CImage::GetPixelAddress` Retrieves the exact address of a pixel. @@ -872,10 +872,10 @@ void* GetPixelAddress(int x, int y) throw(); ### Parameters -*x*
+*`x`*
The x-coordinate of the pixel. -*y*
+*`y`*
The y-coordinate of the pixel. ### Remarks @@ -887,11 +887,11 @@ For formats that have less than 8 bits per pixel, this method returns the addres > [!NOTE] > This method supports only DIB section bitmaps. -## CImage::GetTransparentColor +## `CImage::GetTransparentColor` Retrieves the indexed location of the transparent color in the color palette. -``` +```cpp LONG GetTransparentColor() const throw(); ``` @@ -899,11 +899,11 @@ LONG GetTransparentColor() const throw(); The index of the transparent color. -## CImage::GetWidth +## `CImage::GetWidth` Retrieves the width, in pixels, of an image. -``` +```cpp int GetWidth() const throw(); ``` @@ -911,72 +911,72 @@ int GetWidth() const throw(); The width of the bitmap, in pixels. -## CImage::IsDIBSection +## `CImage::IsDIBSection` Determines if the attached bitmap is a DIB section. -``` +```cpp bool IsDIBSection() const throw(); ``` ### Return Value -TRUE if the attached bitmap is a DIB section. Otherwise FALSE. +`TRUE` if the attached bitmap is a DIB section. Otherwise `FALSE`. ### Remarks If the bitmap is not a DIB section, you cannot use the following `CImage` methods, which support only DIB section bitmaps: -- [GetBits](#getbits) +- [`GetBits`](#getbits) -- [GetColorTable](#getcolortable) +- [`GetColorTable`](#getcolortable) -- [GetMaxColorTableEntries](#getmaxcolortableentries) +- [`GetMaxColorTableEntries`](#getmaxcolortableentries) -- [GetPitch](#getpitch) +- [`GetPitch`](#getpitch) -- [GetPixelAddress](#getpixeladdress) +- [`GetPixelAddress`](#getpixeladdress) -- [IsIndexed](#isindexed) +- [`IsIndexed`](#isindexed) -- [SetColorTable](#setcolortable) +- [`SetColorTable`](#setcolortable) -## CImage::IsIndexed +## `CImage::IsIndexed` Determines whether a bitmap's pixels are mapped to a color palette. -``` +```cpp bool IsIndexed() const throw(); ``` ### Return Value -TRUE if indexed; otherwise FALSE. +`TRUE` if indexed; otherwise `FALSE`. ### Remarks -This method returns TRUE only if the bitmap is 8-bit (256 colors) or less. +This method returns `TRUE` only if the bitmap is 8-bit (256 colors) or less. > [!NOTE] > This method supports only DIB section bitmaps. -## CImage::IsNull +## `CImage::IsNull` Determines if a bitmap is currently loaded. -``` +```cpp bool IsNull() const throw(); ``` ### Remarks -This method returns TRUE if a bitmap is not currently loaded; otherwise FALSE. +This method returns `TRUE` if a bitmap is not currently loaded; otherwise `FALSE`. -## CImage::IsTransparencySupported +## `CImage::IsTransparencySupported` Indicates whether the application supports transparent bitmaps. -``` +```cpp static BOOL IsTransparencySupported() throw(); ``` @@ -986,38 +986,38 @@ Nonzero if the current platform supports transparency. Otherwise 0. ### Remarks -If the return value is nonzero, and transparency is supported, a call to [AlphaBlend](#alphablend), [TransparentBlt](#transparentblt), or [Draw](#draw) will handle transparent colors. +If the return value is nonzero, and transparency is supported, a call to [`AlphaBlend`](#alphablend), [`TransparentBlt`](#transparentblt), or [`Draw`](#draw) will handle transparent colors. -## CImage::Load +## `CImage::Load` Loads an image. -``` +```cpp HRESULT Load(LPCTSTR pszFileName) throw(); HRESULT Load(IStream* pStream) throw(); ``` ### Parameters -*pszFileName*
+*`pszFileName`*
A pointer to a string containing the name of the image file to load. -*pStream*
+*`pStream`*
A pointer to a stream containing the name of the image file to load. ### Return Value -A standard HRESULT. +A standard `HRESULT`. ### Remarks -Loads the image specified by *pszFileName* or *pStream*. +Loads the image specified by *`pszFileName`* or *`pStream`*. Valid image types are BMP, GIF, JPEG, PNG, and TIFF. -## CImage::LoadFromResource +## `CImage::LoadFromResource` -Loads an image from a BITMAP resource. +Loads an image from a `BITMAP` resource. ```cpp void LoadFromResource( @@ -1031,24 +1031,24 @@ void LoadFromResource( ### Parameters -*hInstance*
+*`hInstance`*
Handle to an instance of the module that contains the image to be loaded. -*pszResourceName*
+*`pszResourceName`*
A pointer to the string containing the name of the resource containing the image to load. -*nIDResource*
+*`nIDResource`*
The ID of the resource to load. ### Remarks -The resource must be of type BITMAP. +The resource must be of type `BITMAP`. -## CImage::MaskBlt +## `CImage::MaskBlt` Combines the color data for the source and destination bitmaps using the specified mask and raster operation. -``` +```cpp BOOL MaskBlt( HDC hDestDC, int xDest, @@ -1086,49 +1086,49 @@ BOOL MaskBlt( ### Parameters -*hDestDC*
+*`hDestDC`*
The handle to the module whose executable contains the resource. -*xDest*
+*`xDest`*
The x-coordinate, in logical units, of the upper left corner of the destination rectangle. -*yDest*
+*`yDest`*
The y-coordinate, in logical units, of the upper left corner of the destination rectangle. -*nDestWidth*
+*`nDestWidth`*
The width, in logical units, of the destination rectangle and source bitmap. -*nDestHeight*
+*`nDestHeight`*
The height, in logical units, of the destination rectangle and source bitmap. -*xSrc*
+*`xSrc`*
The logical x-coordinate of the upper left corner of the source bitmap. -*ySrc*
+*`ySrc`*
The logical y-coordinate of the upper left corner of the source bitmap. -*hbmMask*
+*`hbmMask`*
Handle to the monochrome mask bitmap combined with the color bitmap in the source device context. -*xMask*
-The horizontal pixel offset for the mask bitmap specified by the *hbmMask* parameter. +*`xMask`*
+The horizontal pixel offset for the mask bitmap specified by the *`hbmMask`* parameter. -*yMask*
-The vertical pixel offset for the mask bitmap specified by the *hbmMask* parameter. +*`yMask`*
+The vertical pixel offset for the mask bitmap specified by the *`hbmMask`* parameter. -*dwROP*
+*`dwROP`*
Specifies both foreground and background ternary raster operation codes that the method uses to control the combination of source and destination data. The background raster operation code is stored in the high-order byte of the high-order word of this value; the foreground raster operation code is stored in the low-order byte of the high-order word of this value; the low-order word of this value is ignored, and should be zero. For a discussion of foreground and background in the context of this method, see `MaskBlt` in the Windows SDK. For a list of common raster operation codes, see `BitBlt` in the Windows SDK. -*rectDest*
+*`rectDest`*
A reference to a `RECT` structure, identifying the destination. -*pointSrc*
+*`pointSrc`*
A `POINT` structure indicating the upper left corner of the source rectangle. -*pointMask*
+*`pointMask`*
A `POINT` structure indicating the upper left corner of the mask bitmap. -*pointDest*
+*`pointDest`*
A reference to a `POINT` structure that identifies the upper left corner of the destination rectangle, in logical units. ### Return Value @@ -1139,15 +1139,15 @@ Nonzero if successful, otherwise 0. This method applies to Windows NT, versions 4.0 and later only. -## CImage::operator HBITMAP +## `CImage::operator HBITMAP` -Use this operator to get the attached Windows GDI handle of the `CImage` object. This operator is a casting operator, which supports direct use of an HBITMAP object. +Use this operator to get the attached Windows GDI handle of the `CImage` object. This operator is a casting operator, which supports direct use of an `HBITMAP` object. -## CImage::PlgBlt +## `CImage::PlgBlt` Performs a bit-block transfer from a rectangle in a source device context into a parallelogram in a destination device context. -``` +```cpp BOOL PlgBlt( HDC hDestDC, const POINT* pPoints, @@ -1174,38 +1174,38 @@ BOOL PlgBlt( ### Parameters -*hDestDC*
+*`hDestDC`*
A handle to the destination device context. -*pPoints*
+*`pPoints`*
A pointer to an array of three points in logical space that identify three corners of the destination parallelogram. The upper left corner of the source rectangle is mapped to the first point in this array, the upper-right corner to the second point in this array, and the lower left corner to the third point. The lower-right corner of the source rectangle is mapped to the implicit fourth point in the parallelogram. -*hbmMask*
+*`hbmMask`*
A handle to an optional monochrome bitmap that is used to mask the colors of the source rectangle. -*xSrc*
+*`xSrc`*
The x-coordinate, in logical units, of the upper left corner of the source rectangle. -*ySrc*
+*`ySrc`*
The y-coordinate, in logical units, of the upper left corner of the source rectangle. -*nSrcWidth*
+*`nSrcWidth`*
The width, in logical units, of the source rectangle. -*nSrcHeight*
+*`nSrcHeight`*
The height, in logical units, of the source rectangle. -*xMask*
+*`xMask`*
The x-coordinate of the upper left corner of the monochrome bitmap. -*yMask*
+*`yMask`*
The y-coordinate of the upper left corner of the monochrome bitmap. -*rectSrc*
-A reference to a [RECT](/windows/win32/api/windef/ns-windef-rect) structure specifying the coordinates of the source rectangle. +*`rectSrc`*
+A reference to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure specifying the coordinates of the source rectangle. -*pointMask*
-A [POINT](/windows/win32/api/windef/ns-windef-point) structure indicating the upper left corner of the mask bitmap. +*`pointMask`*
+A [`POINT`](/windows/win32/api/windef/ns-windef-point) structure indicating the upper left corner of the mask bitmap. ### Return Value @@ -1213,11 +1213,11 @@ Nonzero if successful, otherwise 0. ### Remarks -If *hbmMask* identifies a valid monochrome bitmap, `PlgBit` uses this bitmap to mask the bits of color data from the source rectangle. +If *`hbmMask`* identifies a valid monochrome bitmap, `PlgBit` uses this bitmap to mask the bits of color data from the source rectangle. -This method applies to Windows NT, versions 4.0 and later only. See [PlgBlt](/windows/win32/api/wingdi/nf-wingdi-plgblt) in the Windows SDK for more detailed information. +This method applies to Windows NT, versions 4.0 and later only. See [`PlgBlt`](/windows/win32/api/wingdi/nf-wingdi-plgblt) in the Windows SDK for more detailed information. -## CImage::ReleaseDC +## `CImage::ReleaseDC` Releases the device context. @@ -1227,9 +1227,9 @@ void ReleaseDC() const throw(); ### Remarks -Because only one bitmap can be selected into a device context at a time, you must call `ReleaseDC` for each call to [GetDC](#getdc). +Because only one bitmap can be selected into a device context at a time, you must call `ReleaseDC` for each call to [`GetDC`](#getdc). -## CImage::ReleaseGDIPlus +## `CImage::ReleaseGDIPlus` Releases resources used by GDI+. @@ -1239,13 +1239,13 @@ void ReleaseGDIPlus() throw(); ### Remarks -This method must be called to free resources allocated by a global `CImage` object. See [CImage::CImage](#cimage). +This method must be called to free resources allocated by a global `CImage` object. See [`CImage::CImage`](#cimage). -## CImage::Save +## `CImage::Save` Saves an image to the specified stream or file on disk. -``` +```cpp HRESULT Save( IStream* pStream, REFGUID guidFileType) const throw(); @@ -1257,13 +1257,13 @@ HRESULT Save( ### Parameters -*pStream*
+*`pStream`*
A pointer to a COM IStream object containing the file image data. -*pszFileName*
+*`pszFileName`*
A pointer to the file name for the image. -*guidFileType*
+*`guidFileType`*
The file type to save the image as. Can be one of the following: - `ImageFormatBMP` An uncompressed bitmap image. @@ -1279,13 +1279,13 @@ The file type to save the image as. Can be one of the following: ### Return Value -A standard HRESULT. +A standard `HRESULT`. ### Remarks -Call this function to save the image using a specified name and type. If the *guidFileType* parameter is not included, the file name's file extension will be used to determine the image format. If no extension is provided, the image will be saved in BMP format. +Call this function to save the image using a specified name and type. If the *`guidFileType`* parameter is not included, the file name's file extension will be used to determine the image format. If no extension is provided, the image will be saved in BMP format. -## CImage::SetColorTable +## `CImage::SetColorTable` Sets the red, green, blue (RGB) color values for a range of entries in the palette of the DIB section. @@ -1298,20 +1298,20 @@ void SetColorTable( ### Parameters -*iFirstColor*
+*`iFirstColor`*
The color table index of the first entry to set. -*nColors*
+*`nColors`*
The number of color table entries to set. -*prgbColors*
-A pointer to the array of [RGBQUAD](/windows/win32/api/wingdi/ns-wingdi-rgbquad) structures to set the color table entries. +*`prgbColors`*
+A pointer to the array of [`RGBQUAD`](/windows/win32/api/wingdi/ns-wingdi-rgbquad) structures to set the color table entries. ### Remarks This method supports only DIB section bitmaps. -## CImage::SetPixel +## `CImage::SetPixel` Sets the color of a pixel at a given location in the bitmap. @@ -1321,22 +1321,22 @@ void SetPixel(int x, int y, COLORREF color) throw(); ### Parameters -*x*
+*`x`*
The horizontal location of the pixel to set. -*y*
+*`y`*
The vertical location of the pixel to set. -*color*
+*`color`*
The color to which you set the pixel. ### Remarks This method fails if the pixel coordinates lie outside of the selected clipping region. -## CImage::SetPixelIndexed +## `CImage::SetPixelIndexed` -Sets the pixel color to the color located at *iIndex* in the color palette. +Sets the pixel color to the color located at *`iIndex`* in the color palette. ```cpp void SetPixelIndexed(int x, int y, int iIndex) throw(); @@ -1344,18 +1344,18 @@ void SetPixelIndexed(int x, int y, int iIndex) throw(); ### Parameters -*x*
+*`x`*
The horizontal location of the pixel to set. -*y*
+*`y`*
The vertical location of the pixel to set. -*iIndex*
+*`iIndex`*
The index of a color in the color palette. -## CImage::SetPixelRGB +## `CImage::SetPixelRGB` -Sets the pixel at the locations specified by *x* and *y* to the colors indicated by *r*, *g*, and *b*, in a red, green, blue (RGB) image. +Sets the pixel at the locations specified by *`x`* and *`y`* to the colors indicated by *`r`*, *`g`*, and *`b`*, in a red, green, blue (RGB) image. ```cpp void SetPixelRGB( @@ -1368,47 +1368,47 @@ void SetPixelRGB( ### Parameters -*x*
+*`x`*
The horizontal location of the pixel to set. -*y*
+*`y`*
The vertical location of the pixel to set. -*r*
+*`r`*
The intensity of the red color. -*g*
+*`g`*
The intensity of the green color. -*b*
+*`b`*
The intensity of the blue color. ### Remarks The red, green, and blue parameters are each represented by a number between 0 and 255. If you set all three parameters to zero, the combined resulting color is black. If you set all three parameters to 255, the combined resulting color is white. -## CImage::SetTransparentColor +## `CImage::SetTransparentColor` Sets a color at a given indexed location as transparent. -``` +```cpp LONG SetTransparentColor(LONG iTransparentColor) throw(); ``` ### Parameters -*iTransparentColor*
+*`iTransparentColor`*
The index, in a color palette, of the color to set to transparent. If -1, no color is set to transparent. ### Return Value The index of the color previously set as transparent. -## CImage::StretchBlt +## `CImage::StretchBlt` Copies a bitmap from the source device context to this current device context. -``` +```cpp BOOL StretchBlt( HDC hDestDC, int xDest, @@ -1443,40 +1443,40 @@ BOOL StretchBlt( ### Parameters -*hDestDC*
+*`hDestDC`*
A handle to the destination device context. -*xDest*
+*`xDest`*
The x-coordinate, in logical units, of the upper left corner of the destination rectangle. -*yDest*
+*`yDest`*
The y-coordinate, in logical units, of the upper left corner of the destination rectangle. -*nDestWidth*
+*`nDestWidth`*
The width, in logical units, of the destination rectangle. -*nDestHeight*
+*`nDestHeight`*
The height, in logical units, of the destination rectangle. -*dwROP*
-The raster operation to be performed. Raster-operation codes define exactly how to combine the bits of the source, the destination, and the pattern (as defined by the currently selected brush) to form the destination. See [BitBlt](/windows/win32/api/wingdi/nf-wingdi-bitblt) in the Windows SDK for a list of other raster-operation codes and their descriptions. +*`dwROP`*
+The raster operation to be performed. Raster-operation codes define exactly how to combine the bits of the source, the destination, and the pattern (as defined by the currently selected brush) to form the destination. See [`BitBlt`](/windows/win32/api/wingdi/nf-wingdi-bitblt) in the Windows SDK for a list of other raster-operation codes and their descriptions. -*rectDest*
-A reference to a [RECT](/windows/win32/api/windef/ns-windef-rect) structure, identifying the destination. +*`rectDest`*
+A reference to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure, identifying the destination. -*xSrc*
+*`xSrc`*
The x-coordinate, in logical units, of the upper left corner of the source rectangle. -*ySrc*
+*`ySrc`*
The y-coordinate, in logical units, of the upper left corner of the source rectangle. -*nSrcWidth*
+*`nSrcWidth`*
The width, in logical units, of the source rectangle. -*nSrcHeight*
+*`nSrcHeight`*
The height, in logical units, of the source rectangle. -*rectSrc*
+*`rectSrc`*
A reference to a `RECT` structure, identifying the source. ### Return Value @@ -1485,13 +1485,13 @@ Nonzero if successful, otherwise 0. ### Remarks -For more information, see [StretchBlt](/windows/win32/api/wingdi/nf-wingdi-stretchblt) in the Windows SDK. +For more information, see [`StretchBlt`](/windows/win32/api/wingdi/nf-wingdi-stretchblt) in the Windows SDK. -## CImage::TransparentBlt +## `CImage::TransparentBlt` Copies a bitmap from the source device context to this current device context. -``` +```cpp BOOL TransparentBlt( HDC hDestDC, int xDest, @@ -1526,49 +1526,49 @@ BOOL TransparentBlt( ### Parameters -*hDestDC*
+*`hDestDC`*
A handle to the destination device context. -*xDest*
+*`xDest`*
The x-coordinate, in logical units, of the upper left corner of the destination rectangle. -*yDest*
+*`yDest`*
The y-coordinate, in logical units, of the upper left corner of the destination rectangle. -*nDestWidth*
+*`nDestWidth`*
The width, in logical units, of the destination rectangle. -*nDestHeight*
+*`nDestHeight`*
The height, in logical units, of the destination rectangle. -*crTransparent*
-The color in the source bitmap to treat as transparent. By default, CLR_INVALID, indicating that the color currently set as the transparent color of the image should be used. +*`crTransparent`*
+The color in the source bitmap to treat as transparent. By default, `CLR_INVALID`, indicating that the color currently set as the transparent color of the image should be used. -*rectDest*
-A reference to a [RECT](/windows/win32/api/windef/ns-windef-rect) structure, identifying the destination. +*`rectDest`*
+A reference to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure, identifying the destination. -*xSrc*
+*`xSrc`*
The x-coordinate, in logical units, of the upper left corner of the source rectangle. -*ySrc*
+*`ySrc`*
The y-coordinate, in logical units, of the upper left corner of the source rectangle. -*nSrcWidth*
+*`nSrcWidth`*
The width, in logical units, of the source rectangle. -*nSrcHeight*
+*`nSrcHeight`*
The height, in logical units, of the source rectangle. -*rectSrc*
+*`rectSrc`*
A reference to a `RECT` structure, identifying the source. ### Return Value -TRUE if successful, otherwise FALSE. +`TRUE` if successful, otherwise `FALSE`. ### Remarks -`TransparentBlt` is supported for source bitmaps of 4 bits per pixel and 8 bits per pixel. Use [CImage::AlphaBlend](#alphablend) to specify 32 bits-per-pixel bitmaps with transparency. +`TransparentBlt` is supported for source bitmaps of 4 bits per pixel and 8 bits per pixel. Use [`CImage::AlphaBlend`](#alphablend) to specify 32 bits-per-pixel bitmaps with transparency. ### Example @@ -1601,10 +1601,9 @@ BOOL TransparentBlt(CImage* pSrcImage, CImage* pDstImage, ## See also -[MMXSwarm Sample](../../overview/visual-cpp-samples.md)
-[SimpleImage Sample](../../overview/visual-cpp-samples.md)
+[`MMXSwarm` Sample](../../overview/visual-cpp-samples.md)
+[`SimpleImage` Sample](../../overview/visual-cpp-samples.md)
[Device-Independent Bitmaps](/windows/win32/gdi/device-independent-bitmaps)
-[CreateDIBSection](/windows/win32/api/wingdi/nf-wingdi-createdibsection)
+[`CreateDIBSection`](/windows/win32/api/wingdi/nf-wingdi-createdibsection)
[ATL COM Desktop Components](../../atl/atl-com-desktop-components.md)
-[Device-Independent Bitmaps](/windows/win32/gdi/device-independent-bitmaps)
-[CreateDIBSection](/windows/win32/api/wingdi/nf-wingdi-createdibsection) +[Device-Independent Bitmaps](/windows/win32/gdi/device-independent-bitmaps) diff --git a/docs/atl-mfc-shared/reference/classes-shared-by-mfc-and-atl.md b/docs/atl-mfc-shared/reference/classes-shared-by-mfc-and-atl.md index dd93cb77f4..bbcb2af079 100644 --- a/docs/atl-mfc-shared/reference/classes-shared-by-mfc-and-atl.md +++ b/docs/atl-mfc-shared/reference/classes-shared-by-mfc-and-atl.md @@ -21,7 +21,7 @@ The following table lists the classes shared between MFC and ATL. |[CRect](../../atl-mfc-shared/reference/crect-class.md)|A class similar to a Windows [RECT](/windows/win32/api/windef/ns-windef-rect) structure that also includes member functions to manipulate `CRect` objects and Windows `RECT` structures.|atltypes.h| |[CSimpleStringT](../../atl-mfc-shared/reference/csimplestringt-class.md)|Represents a `CSimpleStringT` object.|atlsimpstr.h| |[CSize](../../atl-mfc-shared/reference/csize-class.md)|A class similar to the Windows [SIZE](/windows/win32/api/windef/ns-windef-size) structure, which implements a relative coordinate or position.|atltypes.h| -|[CStrBufT](../../atl-mfc-shared/reference/cstrbuft-class.md)|Provides automatic resource cleanup for `GetBuffer` and `ReleaseBuffer` calls on a existing `CStringT` object.|atlsimpstr.h| +|[CStrBufT](../../atl-mfc-shared/reference/cstrbuft-class.md)|Provides automatic resource cleanup for `GetBuffer` and `ReleaseBuffer` calls on an existing `CStringT` object.|atlsimpstr.h| |[CStringData](../../atl-mfc-shared/reference/cstringdata-class.md)|Represents the data of a string object.|atlsimpstr.h| |[CStringT](../../atl-mfc-shared/reference/cstringt-class.md)|Represents a `CStringT` object.|cstringt.h (MFC dependent) atlstr.h (MFC independent)| |[CTime](../../atl-mfc-shared/reference/ctime-class.md)|Represents an absolute time and date.|atltime.h| diff --git a/docs/atl-mfc-shared/reference/codesnippet/CPP/cfiledialog-class_3.cpp b/docs/atl-mfc-shared/reference/codesnippet/CPP/cfiledialog-class_3.cpp index 69b8fc155d..9c7f028ed7 100644 --- a/docs/atl-mfc-shared/reference/codesnippet/CPP/cfiledialog-class_3.cpp +++ b/docs/atl-mfc-shared/reference/codesnippet/CPP/cfiledialog-class_3.cpp @@ -1,7 +1,7 @@ void CMyClass::OnFileOpen() { // szFilters is a text string that includes two file name filters: - // "*.my" for "MyType Files" and "*.*' for "All Files." + // "*.my" for "MyType Files" and "*.*" for "All Files." TCHAR szFilters[]= _T("MyType Files (*.my)|*.my|All Files (*.*)|*.*||"); // Create an Open dialog; the default file name extension is ".my". diff --git a/docs/atl-mfc-shared/reference/coledatetime-class.md b/docs/atl-mfc-shared/reference/coledatetime-class.md index 691c33fc2e..5da193d9b9 100644 --- a/docs/atl-mfc-shared/reference/coledatetime-class.md +++ b/docs/atl-mfc-shared/reference/coledatetime-class.md @@ -1,10 +1,9 @@ --- title: "COleDateTime Class" description: "API reference for the MFC COleDateTime class which Encapsulates the `DATE` data type used in OLE automation." -ms.date: "08/27/2020" +ms.date: 08/27/2020 f1_keywords: ["COleDateTime", "ATLCOMTIME/ATL::COleDateTime", "ATLCOMTIME/ATL::COleDateTime::COleDateTime", "ATLCOMTIME/ATL::COleDateTime::Format", "ATLCOMTIME/ATL::COleDateTime::GetAsDBTIMESTAMP", "ATLCOMTIME/ATL::COleDateTime::GetAsSystemTime", "ATLCOMTIME/ATL::COleDateTime::GetAsUDATE", "ATLCOMTIME/ATL::COleDateTime::GetCurrentTime", "ATLCOMTIME/ATL::COleDateTime::GetDay", "ATLCOMTIME/ATL::COleDateTime::GetDayOfWeek", "ATLCOMTIME/ATL::COleDateTime::GetDayOfYear", "ATLCOMTIME/ATL::COleDateTime::GetHour", "ATLCOMTIME/ATL::COleDateTime::GetMinute", "ATLCOMTIME/ATL::COleDateTime::GetMonth", "ATLCOMTIME/ATL::COleDateTime::GetSecond", "ATLCOMTIME/ATL::COleDateTime::GetStatus", "ATLCOMTIME/ATL::COleDateTime::GetYear", "ATLCOMTIME/ATL::COleDateTime::ParseDateTime", "ATLCOMTIME/ATL::COleDateTime::SetDate", "ATLCOMTIME/ATL::COleDateTime::SetDateTime", "ATLCOMTIME/ATL::COleDateTime::SetStatus", "ATLCOMTIME/ATL::COleDateTime::SetTime", "ATLCOMTIME/ATL::COleDateTime::m_dt", "ATLCOMTIME/ATL::COleDateTime::m_status"] helpviewer_keywords: ["shared classes, COleDateTime", "time-only values", "Date data type, MFC encapsulation of", "COleDateTime class", "dates, handling in MFC", "time, handling in MFC"] -ms.assetid: e718f294-16ec-4649-88b6-a4dbae5178fb --- # COleDateTime Class @@ -12,7 +11,7 @@ Encapsulates the `DATE` data type that is used in OLE automation. ## Syntax -``` +```cpp class COleDateTime ``` @@ -109,7 +108,7 @@ For more information about the `COleDateTime` and `COleDateTimeSpan` classes, se Comparison operators. -``` +```cpp bool operator==(const COleDateTime& date) const throw(); bool operator!=(const COleDateTime& date) const throw(); bool operator<(const COleDateTime& date) const throw(); @@ -128,12 +127,10 @@ The `COleDateTime` object to be compared. > [!NOTE] > An ATLASSERT will occur if either of the two operands is invalid. -### Example +### Examples [!code-cpp[NVC_ATLMFC_Utilities#13](../../atl-mfc-shared/codesnippet/cpp/coledatetime-class_2.cpp)] -### Example - The operators **>=**, **\<=**, **>**, and **<**, will assert if the `COleDateTime` object is set to null. [!code-cpp[NVC_ATLMFC_Utilities#170](../../atl-mfc-shared/codesnippet/cpp/coledatetime-class_3.cpp)] @@ -142,7 +139,7 @@ The operators **>=**, **\<=**, **>**, and **<**, will assert if the `COleDateTim Constructs a `COleDateTime` object. -``` +```cpp COleDateTime() throw(); COleDateTime(const VARIANT& varSrc) throw(); COleDateTime(DATE dtSrc) throw(); @@ -213,7 +210,7 @@ Following is a brief description of each constructor: - `COleDateTime(` `dateSrc` **)** Constructs a `COleDateTime` object from an existing `COleDateTime` object. -- `COleDateTime(` *varSrc* **)** Constructs a `COleDateTime` object. Attempts to convert a `VARIANT` structure or [COleVariant](../../mfc/reference/colevariant-class.md) object to a date/time ( `VT_DATE`) value. If this conversion is successful, the converted value is copied into the new `COleDateTime` object. If it is not, the value of the `COleDateTime` object is set to 0 (midnight, 30 December 1899) and its status to invalid. +- `COleDateTime(` *varSrc* **)** Constructs a `COleDateTime` object. Attempts to convert a `VARIANT` structure or [COleVariant](../../mfc/reference/colevariant-class.md) object to a date/time (`VT_DATE`) value. If this conversion is successful, the converted value is copied into the new `COleDateTime` object. If it is not, the value of the `COleDateTime` object is set to 0 (midnight, 30 December 1899) and its status to invalid. - `COleDateTime(` `dtSrc` **)** Constructs a `COleDateTime` object from a `DATE` value. @@ -244,7 +241,7 @@ For more information about the bounds for `COleDateTime` values, see the article Creates a formatted representation of the date/time value. -``` +```cpp CString Format(DWORD dwFlags = 0, LCID lcid = LANG_USER_DEFAULT) const; CString Format(LPCTSTR lpszFormat) const; CString Format(UINT nFormatID) const; @@ -265,7 +262,7 @@ Indicates one of the following locale flags: Indicates locale ID to use for the conversion. For more information about language identifiers, see [Language Identifiers](/windows/win32/Intl/language-identifiers). *lpszFormat*
-A formatting string similar to the `printf` formatting string. Each formatting code, preceded by a percent ( `%`) sign, is replaced by the corresponding `COleDateTime` component. Other characters in the formatting string are copied unchanged to the returned string. For more information, see the run-time function [strftime](../../c-runtime-library/reference/strftime-wcsftime-strftime-l-wcsftime-l.md). The value and meaning of the formatting codes for `Format` are: +A formatting string similar to the `printf` formatting string. Each formatting code, preceded by a percent (`%`) sign, is replaced by the corresponding `COleDateTime` component. Other characters in the formatting string are copied unchanged to the returned string. For more information, see the run-time function [strftime](../../c-runtime-library/reference/strftime-wcsftime-strftime-l-wcsftime-l.md). The value and meaning of the formatting codes for `Format` are: - `%H` Hours in the current day @@ -305,7 +302,7 @@ This form formats the value by using the format string which contains special fo Call this method to obtain the time in the `COleDateTime` object as a `DBTIMESTAMP` data structure. -``` +```cpp bool GetAsDBTIMESTAMP(DBTIMESTAMP& timeStamp) const throw(); ``` @@ -330,7 +327,7 @@ Stores the resulting time in the referenced *timeStamp* structure. The `DBTIMEST Call this method to obtain the time in the `COleDateTime` object as a `SYSTEMTIME` data structure. -``` +```cpp bool GetAsSystemTime(SYSTEMTIME& sysTime) const throw(); ``` @@ -353,7 +350,7 @@ For more information on the status information held in a `COleDateTime` object, Call this method to obtain the time in the `COleDateTime` object as a `UDATE` data structure. -``` +```cpp bool GetAsUDATE(UDATE& uDate) const throw(); ``` @@ -374,7 +371,7 @@ A `UDATE` structure represents an "unpacked" date. Call this static member function to return the current date/time value. -``` +```cpp static COleDateTime WINAPI GetCurrentTime() throw(); ``` @@ -386,7 +383,7 @@ static COleDateTime WINAPI GetCurrentTime() throw(); Gets the day of the month represented by this date/time value. -``` +```cpp int GetDay() const throw(); ``` @@ -422,7 +419,7 @@ For information on other member functions that query the value of this `COleDate Gets the day of the week represented by this date/time value. -``` +```cpp int GetDayOfWeek() const throw(); ``` @@ -458,7 +455,7 @@ For information on other member functions that query the value of this `COleDate Gets the day of the year represented by this date/time value. -``` +```cpp int GetDayOfYear() const throw(); ``` @@ -494,7 +491,7 @@ For information on other member functions that query the value of this `COleDate Gets the hour represented by this date/time value. -``` +```cpp int GetHour() const throw(); ``` @@ -530,7 +527,7 @@ For information on other member functions that query the value of this `COleDate Gets the minute represented by this date/time value. -``` +```cpp int GetMinute() const throw(); ``` @@ -566,7 +563,7 @@ See the example for [GetHour](#gethour). Gets the month represented by this date/time value. -``` +```cpp int GetMonth() const throw(); ``` @@ -602,7 +599,7 @@ See the example for [GetDay](#getday). Gets the second represented by this date/time value. -``` +```cpp int GetSecond() const throw(); ``` @@ -643,7 +640,7 @@ See the example for [GetHour](#gethour). Gets the status (validity) of a given `COleDateTime` object. -``` +```cpp DateTimeStatus GetStatus() const throw(); ``` @@ -655,7 +652,7 @@ Returns the status of this `COleDateTime` value. If you call `GetStatus` on a `C The return value is defined by the `DateTimeStatus` enumerated type, which is defined within the `COleDateTime` class. -``` +```cpp enum DateTimeStatus { error = -1, @@ -709,7 +706,7 @@ For more information about the bounds for `COleDateTime` values, see the article Gets the year represented by this date/time value. -``` +```cpp int GetYear() const throw(); ``` @@ -747,7 +744,7 @@ See the example for [GetDay](#getday). The underlying `DATE` structure for this `COleDateTime` object. -``` +```cpp DATE m_dt; ``` @@ -762,7 +759,7 @@ For more information about the implementation of the `DATE` object, see the arti Contains the status of this `COleDateTime` object. -``` +```cpp DateTimeStatus m_status; ``` @@ -777,7 +774,7 @@ The type of this data member is the enumerated type `DateTimeStatus`, which is d Copies a `COleDateTime` value. -``` +```cpp COleDateTime& operator=(const VARIANT& varSrc) throw(); COleDateTime& operator=(DATE dtSrc) throw(); COleDateTime& operator=(const time_t& timeSrc) throw(); @@ -817,7 +814,7 @@ For more information about the bounds for `COleDateTime` values, see the article Add and subtract `ColeDateTime` values. -``` +```cpp COleDateTime operator+(COleDateTimeSpan dateSpan) const throw(); COleDateTime operator-(COleDateTimeSpan dateSpan) const throw(); COleDateTimeSpan operator-(const COleDateTime& date) const throw(); @@ -847,7 +844,7 @@ For more information about the bounds for `COleDateTime` values, see the article Add and subtract a `ColeDateTime` value from this `COleDateTime` object. -``` +```cpp COleDateTime& operator+=(COleDateTimeSpan dateSpan) throw(); COleDateTime& operator-=(COleDateTimeSpan dateSpan) throw(); ``` @@ -870,7 +867,7 @@ For more information about the bounds for `COleDateTime` values, see the article Converts a `ColeDateTime` value into a `DATE`. -``` +```cpp operator DATE() const throw(); ``` @@ -884,7 +881,7 @@ The `DATE` operator will assert if the `COleDateTime` object is set to null. See Parses a string to read a date/time value. -``` +```cpp bool ParseDateTime( LPCTSTR lpszDate, DWORD dwFlags = 0, @@ -945,7 +942,7 @@ For more information about the bounds and implementation for `COleDateTime` valu Sets the date of this `COleDateTime` object. -``` +```cpp int SetDate( int nYear, int nMonth, @@ -1022,7 +1019,7 @@ For more information about the bounds for `COleDateTime` values, see the article Sets the date and time of this `COleDateTime` object. -``` +```cpp int SetDateTime( int nYear, int nMonth, @@ -1130,7 +1127,7 @@ See the example for [GetStatus](#getstatus). Sets the time of this `COleDateTime` object. -``` +```cpp int SetTime( int nHour, int nMin, diff --git a/docs/atl-mfc-shared/reference/coledatetimespan-class.md b/docs/atl-mfc-shared/reference/coledatetimespan-class.md index 41f2f693c9..491074bbae 100644 --- a/docs/atl-mfc-shared/reference/coledatetimespan-class.md +++ b/docs/atl-mfc-shared/reference/coledatetimespan-class.md @@ -12,7 +12,7 @@ Represents a relative time, a time span. ## Syntax -``` +```cpp class COleDateTimeSpan ``` @@ -76,7 +76,7 @@ For more information on the `COleDateTime` and `COleDateTimeSpan` classes, see t Comparison operators. -``` +```cpp bool operator==(const COleDateTimeSpan& dateSpan) const throw(); bool operator!=(const COleDateTimeSpan& dateSpan) const throw(); bool operator<(const COleDateTimeSpan& dateSpan) const throw(); @@ -102,14 +102,14 @@ These operators compare two date/time-span values and return TRUE if the conditi ### Example [!code-cpp[NVC_ATLMFC_Utilities#25](../../atl-mfc-shared/codesnippet/cpp/coledatetimespan-class_1.cpp)] - +  [!code-cpp[NVC_ATLMFC_Utilities#26](../../atl-mfc-shared/codesnippet/cpp/coledatetimespan-class_2.cpp)] ## COleDateTimeSpan::COleDateTimeSpan Constructs a `COleDateTimeSpan` object. -``` +```cpp COleDateTimeSpan() throw(); COleDateTimeSpan(double dblSpanSrc) throw(); COleDateTimeSpan(LONG lDays, int nHours, int nMins, int nSecs) throw(); @@ -145,7 +145,7 @@ For more information about the bounds for `COleDateTimeSpan` values, see the art Generates a formatted string representation of a `COleDateTimeSpan` object. -``` +```cpp CString Format(LPCTSTR pFormat) const; CString Format(UINT nID) const; ``` @@ -194,7 +194,7 @@ This form formats the value using the format string that contains special format Retrieves the day portion of this date/time-span value. -``` +```cpp LONG GetDays() const throw(); ``` @@ -230,7 +230,7 @@ For other functions that query the value of a `COleDateTimeSpan` object, see the Retrieves the hour portion of this date/time-span value. -``` +```cpp LONG GetHours() const throw(); ``` @@ -266,7 +266,7 @@ For other functions that query the value of a `COleDateTimeSpan` object, see the Retrieves the minute portion of this date/time-span value. -``` +```cpp LONG GetMinutes() const throw(); ``` @@ -302,7 +302,7 @@ For other functions that query the value of a `COleDateTimeSpan` object, see the Retrieves the second portion of this date/time-span value. -``` +```cpp LONG GetSeconds() const throw(); ``` @@ -338,7 +338,7 @@ For other functions that query the value of a `COleDateTimeSpan` object, see the Gets the status (validity) of this `COleDateTimeSpan` object. -``` +```cpp DateTimeSpanStatus GetStatus() const throw(); ``` @@ -350,7 +350,7 @@ The status of this `COleDateTimeSpan` value. The return value is defined by the `DateTimeSpanStatus` enumerated type, which is defined within the `COleDateTimeSpan` class. -``` +```cpp enum DateTimeSpanStatus{ valid = 0, invalid = 1, @@ -382,7 +382,7 @@ For more information about the bounds for `COleDateTimeSpan` values, see the art Retrieves this date/time-span value expressed in days. -``` +```cpp double GetTotalDays() const throw(); ``` @@ -418,7 +418,7 @@ For other functions that query the value of a `COleDateTimeSpan` object, see the Retrieves this date/time-span value expressed in hours. -``` +```cpp double GetTotalHours() const throw(); ``` @@ -454,7 +454,7 @@ See the example for [GetTotalDays](#gettotaldays). Retrieves this date/time-span value expressed in minutes. -``` +```cpp double GetTotalMinutes() const throw(); ``` @@ -490,7 +490,7 @@ See the example for [GetTotalDays](#gettotaldays). Retrieves this date/time-span value expressed in seconds. -``` +```cpp double GetTotalSeconds() const throw(); ``` @@ -526,7 +526,7 @@ See the example for [GetTotalDays](#gettotaldays). The underlying **`double`** value for this `COleDateTime` object. -``` +```cpp double m_span; ``` @@ -541,13 +541,13 @@ This value expresses the date/time-span in days. The type for this data member is the enumerated type `DateTimeSpanStatus`, which is defined within the `COleDateTimeSpan` class. -``` +```cpp DateTimeSpanStatus m_status; ``` ### Remarks -``` +```cpp enum DateTimeSpanStatus{ valid = 0, invalid = 1, @@ -582,7 +582,7 @@ For more information about the bounds for `COleDateTimeSpan` values, see the art Copies a `COleDateTimeSpan` value. -``` +```cpp COleDateTimeSpan& operator=(double dblSpanSrc) throw(); ``` @@ -594,7 +594,7 @@ This overloaded assignment operator copies the source date/time-span value into Add, subtract, and change sign for `COleDateTimeSpan` values. -``` +```cpp COleDateTimeSpan operator+(const COleDateTimeSpan& dateSpan) const throw(); COleDateTimeSpan operator-(const COleDateTimeSpan& dateSpan) const throw(); COleDateTimeSpan operator-() const throw(); @@ -618,7 +618,7 @@ For more information on the valid, invalid, and null status values, see the [m_s Add and subtract a `COleDateTimeSpan` value from this `COleDateTimeSpan` value. -``` +```cpp COleDateTimeSpan& operator+=(const COleDateTimeSpan dateSpan) throw(); COleDateTimeSpan& operator-=(const COleDateTimeSpan dateSpan) throw(); ``` @@ -639,7 +639,7 @@ For more information on the valid, invalid, and null status values, see the [m_s Converts this `COleDateTimeSpan` value to a **`double`**. -``` +```cpp operator double() const throw(); ``` @@ -701,7 +701,7 @@ The new status value for this `COleDateTimeSpan` object. The *Status* parameter value is defined by the `DateTimeSpanStatus` enumerated type, which is defined within the `COleDateTimeSpan` class. -``` +```cpp enum DateTimeSpanStatus{ valid = 0, invalid = 1, diff --git a/docs/atl-mfc-shared/reference/cpoint-class.md b/docs/atl-mfc-shared/reference/cpoint-class.md index 94f05597be..1636a18f6d 100644 --- a/docs/atl-mfc-shared/reference/cpoint-class.md +++ b/docs/atl-mfc-shared/reference/cpoint-class.md @@ -4,15 +4,14 @@ title: "CPoint Class" ms.date: "11/04/2016" f1_keywords: ["CPoint", "ATLTYPES/ATL::CPoint", "ATLTYPES/ATL::CPoint::CPoint", "ATLTYPES/ATL::CPoint::Offset"] helpviewer_keywords: ["LPPOINT structure", "POINT structure", "CPoint class"] -ms.assetid: a6d4db93-35cc-444d-9221-c3e160f6edaa --- -# CPoint Class +# `CPoint` Class Similar to the Windows `POINT` structure. ## Syntax -``` +```cpp class CPoint : public tagPOINT ``` @@ -22,30 +21,30 @@ class CPoint : public tagPOINT |Name|Description| |----------|-----------------| -|[CPoint::CPoint](#cpoint)|Constructs a `CPoint`.| +|[`CPoint::CPoint`](#cpoint)|Constructs a `CPoint`.| ### Public Methods |Name|Description| |----------|-----------------| -|[CPoint::Offset](#offset)|Adds values to the `x` and `y` members of the `CPoint`.| +|[`CPoint::Offset`](#offset)|Adds values to the `x` and `y` members of the `CPoint`.| ### Public Operators |Name|Description| |----------|-----------------| -|[CPoint::operator -](#operator_-)|Returns the difference of a `CPoint` and a size, or the negation of a point, or the size difference between two points, or the offset by a negative size.| -|[CPoint::operator !=](#operator_neq)|Checks for inequality between two points.| -|[CPoint::operator +](#operator_add)|Returns the sum of a `CPoint` and a size or point, or a `CRect` offset by a size.| -|[CPoint::operator +=](#operator_add_eq)|Offsets `CPoint` by adding a size or point.| -|[CPoint::operator -=](#operator_-_eq)|Offsets `CPoint` by subtracting a size or point.| -|[CPoint::operator ==](#operator_eq_eq)|Checks for equality between two points.| +|[`CPoint::operator -`](#operator_-)|Returns the difference of a `CPoint` and a `SIZE`, or the negation of a `POINT`, or the `CSize` difference between two `POINT`s, or the offset by a negative `SIZE`.| +|[`CPoint::operator !=`](#operator_neq)|Checks for inequality between two `POINT`s.| +|[`CPoint::operator +`](#operator_add)|Returns the sum of a `CPoint` and a `SIZE` or `POINT`, or a `CRect` offset by a `SIZE`.| +|[`CPoint::operator +=`](#operator_add_eq)|Offsets `CPoint` by adding a `SIZE` or `POINT`.| +|[`CPoint::operator -=`](#operator_-_eq)|Offsets `CPoint` by subtracting a `SIZE` or `POINT`.| +|[`CPoint::operator ==`](#operator_eq_eq)|Checks for equality between two `POINT`s.| ## Remarks -It also includes member functions to manipulate `CPoint` and [POINT](/windows/win32/api/windef/ns-windef-point) structures. +It also includes member functions to manipulate `CPoint` and [`POINT`](/windows/win32/api/windef/ns-windef-point) structures. -A `CPoint` object can be used wherever a `POINT` structure is used. The operators of this class that interact with a "size" accept either [CSize](../../atl-mfc-shared/reference/csize-class.md) objects or [SIZE](/windows/win32/api/windef/ns-windef-size) structures, since the two are interchangeable. +A `CPoint` object can be used wherever a `POINT` structure is used. The operators of this class that interact with a `SIZE` accept either [`CSize`](../../atl-mfc-shared/reference/csize-class.md) objects or [`SIZE`](/windows/win32/api/windef/ns-windef-size) structures, since the two are interchangeable. > [!NOTE] > This class is derived from the `tagPOINT` structure. (The name `tagPOINT` is a less commonly used name for the `POINT` structure.) This means that the data members of the `POINT` structure, `x` and `y`, are accessible data members of `CPoint`. @@ -61,13 +60,13 @@ A `CPoint` object can be used wherever a `POINT` structure is used. The operator ## Requirements -**Header:** atltypes.h +**Header:** `atltypes.h` -## CPoint::CPoint +## `CPoint::CPoint` Constructs a `CPoint` object. -``` +```cpp CPoint() throw(); CPoint(int initX, int initY) throw(); CPoint(POINT initPt) throw(); @@ -77,20 +76,20 @@ CPoint(LPARAM dwPoint) throw(); ### Parameters -*initX*
+*`initX`*\ Specifies the value of the `x` member of `CPoint`. -*initY*
+*`initY`*\ Specifies the value of the `y` member of `CPoint`. -*initPt*
-[POINT](/windows/win32/api/windef/ns-windef-point) structure or `CPoint` that specifies the values used to initialize `CPoint`. +*`initPt`*\ +[`POINT`](/windows/win32/api/windef/ns-windef-point) structure or `CPoint` that specifies the values used to initialize `CPoint`. -*initSize*
-[SIZE](/windows/win32/api/windef/ns-windef-size) structure or [CSize](../../atl-mfc-shared/reference/csize-class.md) that specifies the values used to initialize `CPoint`. +*`initSize`*\ +[`SIZE`](/windows/win32/api/windef/ns-windef-size) structure or [`CSize`](../../atl-mfc-shared/reference/csize-class.md) that specifies the values used to initialize `CPoint`. -*dwPoint*
-Sets the `x` member to the low-order word of *dwPoint* and the `y` member to the high-order word of *dwPoint*. +*`dwPoint`*\ +Sets the `x` member to the low-order word of *`dwPoint`* and the `y` member to the high-order word of *`dwPoint`*. ### Remarks @@ -123,7 +122,7 @@ CPoint ptFromDouble(dwSize); ASSERT(ptFromDouble == ptMFCHere); ``` -## CPoint::Offset +## `CPoint::Offset` Adds values to the `x` and `y` members of the `CPoint`. @@ -135,46 +134,46 @@ void Offset(SIZE size) throw(); ### Parameters -*xOffset*
+*`xOffset`*\ Specifies the amount to offset the `x` member of the `CPoint`. -*yOffset*
+*`yOffset`*\ Specifies the amount to offset the `y` member of the `CPoint`. -*point*
-Specifies the amount ( [POINT](/windows/win32/api/windef/ns-windef-point) or `CPoint`) to offset the `CPoint`. +*`point`*\ +Specifies the amount ([`POINT`](/windows/win32/api/windef/ns-windef-point) or `CPoint`) to offset the `CPoint`. -*size*
-Specifies the amount ( [SIZE](/windows/win32/api/windef/ns-windef-size) or [CSize](../../atl-mfc-shared/reference/csize-class.md)) to offset the `CPoint`. +*`size`*\ +Specifies the amount ([`SIZE`](/windows/win32/api/windef/ns-windef-size) or [`CSize`](../../atl-mfc-shared/reference/csize-class.md)) to offset the `CPoint`. ### Example [!code-cpp[NVC_ATLMFC_Utilities#28](../../atl-mfc-shared/codesnippet/cpp/cpoint-class_1.cpp)] -## CPoint::operator == +## `CPoint::operator ==` -Checks for equality between two points. +Checks for equality between two `POINT`s. -``` +```cpp BOOL operator==(POINT point) const throw(); ``` ### Parameters -*point*
-Contains a [POINT](/windows/win32/api/windef/ns-windef-point) structure or `CPoint` object. +*`point`*\ +Contains a [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or `CPoint` object. ### Return Value -Nonzero if the points are equal; otherwise 0. +Nonzero if the `POINT`s are equal; otherwise 0. ### Example [!code-cpp[NVC_ATLMFC_Utilities#29](../../atl-mfc-shared/codesnippet/cpp/cpoint-class_2.cpp)] -## CPoint::operator != +## `CPoint::operator !=` -Checks for inequality between two points. +Checks for inequality between two `POINT`s. ``` BOOL operator!=(POINT point) const throw(); @@ -182,20 +181,20 @@ BOOL operator!=(POINT point) const throw(); ### Parameters -*point*
-Contains a [POINT](/windows/win32/api/windef/ns-windef-point) structure or `CPoint` object. +*`point`*\ +Contains a [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or `CPoint` object. ### Return Value -Nonzero if the points are not equal; otherwise 0. +Nonzero if the `POINT`s aren't equal; otherwise 0. ### Example [!code-cpp[NVC_ATLMFC_Utilities#30](../../atl-mfc-shared/codesnippet/cpp/cpoint-class_3.cpp)] -## CPoint::operator += +## `CPoint::operator +=` -The first overload adds a size to the `CPoint`. +The first overload adds a `SIZE` to the `CPoint`. ```cpp void operator+=(SIZE size) throw(); @@ -204,27 +203,27 @@ void operator+=(POINT point) throw(); ### Parameters -*size*
-Contains a [SIZE](/windows/win32/api/windef/ns-windef-size) structure or [CSize](../../atl-mfc-shared/reference/csize-class.md) object. +*`size`*\ +Contains a [`SIZE`](/windows/win32/api/windef/ns-windef-size) structure or [`CSize`](../../atl-mfc-shared/reference/csize-class.md) object. -*point*
-Contains a [POINT](/windows/win32/api/windef/ns-windef-point) structure or [CPoint](../../atl-mfc-shared/reference/cpoint-class.md) object. +*`point`*\ +Contains a [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) object. ### Remarks -The second overload adds a point to the `CPoint`. +The second overload adds a `POINT` to the `CPoint`. In both cases, addition is done by adding the `x` (or `cx`) member of the right-hand operand to the `x` member of the `CPoint` and adding the `y` (or `cy`) member of the right-hand operand to the `y` member of the `CPoint`. -For example, adding `CPoint(5, -7)` to a variable which contains `CPoint(30, 40)` changes the variable to `CPoint(35, 33)`. +For example, adding `CPoint(5, -7)` to a variable that contains `CPoint(30, 40)` changes the variable to `CPoint(35, 33)`. ### Example [!code-cpp[NVC_ATLMFC_Utilities#31](../../atl-mfc-shared/codesnippet/cpp/cpoint-class_4.cpp)] -## CPoint::operator -= +## `CPoint::operator -=` -The first overload subtracts a size from the `CPoint`. +The first overload subtracts a `SIZE` from the `CPoint`. ```cpp void operator-=(SIZE size) throw(); @@ -233,29 +232,29 @@ void operator-=(POINT point) throw(); ### Parameters -*size*
-Contains a [SIZE](/windows/win32/api/windef/ns-windef-size) structure or [CSize](../../atl-mfc-shared/reference/csize-class.md) object. +*`size`*\ +Contains a [`SIZE`](/windows/win32/api/windef/ns-windef-size) structure or [`CSize`](../../atl-mfc-shared/reference/csize-class.md) object. -*point*
-Contains a [POINT](/windows/win32/api/windef/ns-windef-point) structure or [CPoint](../../atl-mfc-shared/reference/cpoint-class.md) object. +*`point`*\ +Contains a [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) object. ### Remarks -The second overload subtracts a point from the `CPoint`. +The second overload subtracts a `POINT` from the `CPoint`. In both cases, subtraction is done by subtracting the `x` (or `cx`) member of the right-hand operand from the `x` member of the `CPoint` and subtracting the `y` (or `cy`) member of the right-hand operand from the `y` member of the `CPoint`. -For example, subtracting `CPoint(5, -7)` from a variable which contains `CPoint(30, 40)` changes the variable to `CPoint(25, 47)`. +For example, subtracting `CPoint(5, -7)` from a variable that contains `CPoint(30, 40)` changes the variable to `CPoint(25, 47)`. ### Example [!code-cpp[NVC_ATLMFC_Utilities#32](../../atl-mfc-shared/codesnippet/cpp/cpoint-class_5.cpp)] -## CPoint::operator + +## `CPoint::operator +` Use this operator to offset `CPoint` by a `CPoint` or `CSize` object, or to offset a `CRect` by a `CPoint`. -``` +```cpp CPoint operator+(SIZE size) const throw(); CPoint operator+(POINT point) const throw(); CRect operator+(const RECT* lpRect) const throw(); @@ -263,34 +262,34 @@ CRect operator+(const RECT* lpRect) const throw(); ### Parameters -*size*
-Contains a [SIZE](/windows/win32/api/windef/ns-windef-size) structure or [CSize](../../atl-mfc-shared/reference/csize-class.md) object. +*`size`*\ +Contains a [`SIZE`](/windows/win32/api/windef/ns-windef-size) structure or [`CSize`](../../atl-mfc-shared/reference/csize-class.md) object. -*point*
-Contains a [POINT](/windows/win32/api/windef/ns-windef-point) structure or [CPoint](../../atl-mfc-shared/reference/cpoint-class.md) object. +*`point`*\ +Contains a [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) object. -*lpRect*
-Contains a pointer to a [RECT](/windows/win32/api/windef/ns-windef-rect) structure or [CRect](../../atl-mfc-shared/reference/crect-class.md) object. +*`lpRect`*\ +Contains a pointer to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object. ### Return Value -A `CPoint` that is offset by a size, a `CPoint` that is offset by a point, or a `CRect` offset by a point. +A `CPoint` that is offset by a `SIZE`, a `CPoint` that is offset by a `POINT`, or a `CRect` offset by a `POINT`. ### Remarks For example, using one of the first two overloads to offset the point `CPoint(25, -19)` by a point `CPoint(15, 5)` or size `CSize(15, 5)` returns the value `CPoint(40, -14)`. -Adding a rectangle to a point returns the rectangle after being offset by the `x` and `y` values specified in the point. For example, using the last overload to offset a rectangle `CRect(125, 219, 325, 419)` by a point `CPoint(25, -19)` returns `CRect(150, 200, 350, 400)`. +Adding a `CRect` to a `POINT` returns the `CRect` after being offset by the `x` and `y` values specified in the `POINT`. For example, using the last overload to offset a rectangle `CRect(125, 219, 325, 419)` by a point `CPoint(25, -19)` returns `CRect(150, 200, 350, 400)`. ### Example [!code-cpp[NVC_ATLMFC_Utilities#33](../../atl-mfc-shared/codesnippet/cpp/cpoint-class_6.cpp)] -## CPoint::operator - +## `CPoint::operator -` Use one of the first two overloads to subtract a `CPoint` or `CSize` object from `CPoint`. -``` +```cpp CSize operator-(POINT point) const throw(); CPoint operator-(SIZE size) const throw(); CRect operator-(const RECT* lpRect) const throw(); @@ -299,18 +298,18 @@ CPoint operator-() const throw(); ### Parameters -*point*
-A [POINT](/windows/win32/api/windef/ns-windef-point) structure or [CPoint](../../atl-mfc-shared/reference/cpoint-class.md) object. +*`point`*\ +A [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or [`CPoint`](../../atl-mfc-shared/reference/cpoint-class.md) object. -*size*
-A [SIZE](/windows/win32/api/windef/ns-windef-size) structure or [CSize](../../atl-mfc-shared/reference/csize-class.md) object. +*`size`*\ +A [`SIZE`](/windows/win32/api/windef/ns-windef-size) structure or [`CSize`](../../atl-mfc-shared/reference/csize-class.md) object. -*lpRect*
-A pointer to a [RECT](/windows/win32/api/windef/ns-windef-rect) structure or a [CRect](../../atl-mfc-shared/reference/crect-class.md) object. +*`lpRect`*\ +A pointer to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or a [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object. ### Return Value -A `CSize` that is the difference between two points, a `CPoint` that is offset by the negation of a size, a `CRect` that is offset by the negation of a point, or a `CPoint` that is the negation of a point. +A `CSize` that is the difference between two `POINT`s, a `CPoint` that is offset by the negation of a `SIZE`, a `CRect` that is offset by the negation of a `POINT`, or a `CPoint` that is the negation of a `POINT`. ### Remarks @@ -320,9 +319,9 @@ For example, using the first overload to find the difference between two points Subtracting a `CSize` from `CPoint` does the same calculation as above but returns a `CPoint` object, not a `CSize` object. For example, using the second overload to find the difference between the point `CPoint(25, -19)` and the size `CSize(15, 5)` returns `CPoint(10, -24)`. -Subtracting a rectangle from a point returns the rectangle offset by the negatives of the `x` and `y` values specified in the point. For example, using the last overload to offset the rectangle `CRect(125, 200, 325, 400)` by the point `CPoint(25, -19)` returns `CRect(100, 219, 300, 419)`. +Subtracting a rectangle from a `POINT` returns the rectangle offset by the negatives of the `x` and `y` values specified in the `POINT`. For example, using the last overload to offset the rectangle `CRect(125, 200, 325, 400)` by the point `CPoint(25, -19)` returns `CRect(100, 219, 300, 419)`. -Use the unary operator to negate a point. For example, using the unary operator with the point `CPoint(25, -19)` returns `CPoint(-25, 19)`. +Use the unary operator to negate a `POINT`. For example, using the unary operator with the point `CPoint(25, -19)` returns `CPoint(-25, 19)`. ### Example @@ -330,8 +329,8 @@ Use the unary operator to negate a point. For example, using the unary operator ## See also -[MFC Sample MDI](../../overview/visual-cpp-samples.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
-[POINT Structure](/windows/win32/api/windef/ns-windef-point)
-[CRect Class](../../atl-mfc-shared/reference/crect-class.md)
-[CSize Class](../../atl-mfc-shared/reference/csize-class.md) +[MFC Sample MDI](../../overview/visual-cpp-samples.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ +[`POINT` Structure](/windows/win32/api/windef/ns-windef-point)\ +[`CRect` Class](../../atl-mfc-shared/reference/crect-class.md)\ +[`CSize` Class](../../atl-mfc-shared/reference/csize-class.md) diff --git a/docs/atl-mfc-shared/reference/crect-class.md b/docs/atl-mfc-shared/reference/crect-class.md index 9eae201d14..d05e09be56 100644 --- a/docs/atl-mfc-shared/reference/crect-class.md +++ b/docs/atl-mfc-shared/reference/crect-class.md @@ -6,13 +6,13 @@ f1_keywords: ["CRect", "ATLTYPES/ATL::CRect", "ATLTYPES/ATL::CRect::CRect", "ATL helpviewer_keywords: ["LPCRECT data type", "CRect class", "LPRECT operator", "RECT structure"] ms.assetid: dee4e752-15d6-4db4-b68f-1ad65b2ed6ca --- -# CRect Class +# `CRect` Class -Similar to a Windows [RECT](/windows/win32/api/windef/ns-windef-rect) structure. +Similar to a Windows [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure. ## Syntax -``` +```cpp class CRect : public tagRECT ``` @@ -22,53 +22,53 @@ class CRect : public tagRECT |Name|Description| |----------|-----------------| -|[CRect::CRect](#crect)|Constructs a `CRect` object.| +|[`CRect::CRect`](#crect)|Constructs a `CRect` object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CRect::BottomRight](#bottomright)|Returns the bottom-right point of `CRect`.| -|[CRect::CenterPoint](#centerpoint)|Returns the centerpoint of `CRect`.| -|[CRect::CopyRect](#copyrect)|Copies the dimensions of a source rectangle to `CRect`.| -|[CRect::DeflateRect](#deflaterect)|Decreases the width and height of `CRect`.| -|[CRect::EqualRect](#equalrect)|Determines whether `CRect` is equal to the given rectangle.| -|[CRect::Height](#height)|Calculates the height of `CRect`.| -|[CRect::InflateRect](#inflaterect)|Increases the width and height of `CRect`.| -|[CRect::IntersectRect](#intersectrect)|Sets `CRect` equal to the intersection of two rectangles.| -|[CRect::IsRectEmpty](#isrectempty)|Determines whether `CRect` is empty. `CRect` is empty if the width and/or height are 0.| -|[CRect::IsRectNull](#isrectnull)|Determines whether the `top`, `bottom`, `left`, and `right` member variables are all equal to 0.| -|[CRect::MoveToX](#movetox)|Moves `CRect` to the specified x-coordinate.| -|[CRect::MoveToXY](#movetoxy)|Moves `CRect` to the specified x- and y-coordinates.| -|[CRect::MoveToY](#movetoy)|Moves `CRect` to the specified y-coordinate.| -|[CRect::NormalizeRect](#normalizerect)|Standardizes the height and width of `CRect`.| -|[CRect::OffsetRect](#offsetrect)|Moves `CRect` by the specified offsets.| -|[CRect::PtInRect](#ptinrect)|Determines whether the specified point lies within `CRect`.| -|[CRect::SetRect](#setrect)|Sets the dimensions of `CRect`.| -|[CRect::SetRectEmpty](#setrectempty)|Sets `CRect` to an empty rectangle (all coordinates equal to 0).| -|[CRect::Size](#size)|Calculates the size of `CRect`.| -|[CRect::SubtractRect](#subtractrect)|Subtracts one rectangle from another.| -|[CRect::TopLeft](#topleft)|Returns the top-left point of `CRect`.| -|[CRect::UnionRect](#unionrect)|Sets `CRect` equal to the union of two rectangles.| -|[CRect::Width](#width)|Calculates the width of `CRect`.| +|[`CRect::BottomRight`](#bottomright)|Returns the bottom-right point of `CRect`.| +|[`CRect::CenterPoint`](#centerpoint)|Returns the centerpoint of `CRect`.| +|[`CRect::CopyRect`](#copyrect)|Copies the dimensions of a source rectangle to `CRect`.| +|[`CRect::DeflateRect`](#deflaterect)|Decreases the width and height of `CRect`.| +|[`CRect::EqualRect`](#equalrect)|Determines whether `CRect` is equal to the given rectangle.| +|[`CRect::Height`](#height)|Calculates the height of `CRect`.| +|[`CRect::InflateRect`](#inflaterect)|Increases the width and height of `CRect`.| +|[`CRect::IntersectRect`](#intersectrect)|Sets `CRect` equal to the intersection of two rectangles.| +|[`CRect::IsRectEmpty`](#isrectempty)|Determines whether `CRect` is empty. `CRect` is empty if the width and/or height are 0.| +|[`CRect::IsRectNull`](#isrectnull)|Determines whether the `top`, `bottom`, `left`, and `right` member variables are all equal to 0.| +|[`CRect::MoveToX`](#movetox)|Moves `CRect` to the specified x-coordinate.| +|[`CRect::MoveToXY`](#movetoxy)|Moves `CRect` to the specified x- and y-coordinates.| +|[`CRect::MoveToY`](#movetoy)|Moves `CRect` to the specified y-coordinate.| +|[`CRect::NormalizeRect`](#normalizerect)|Standardizes the height and width of `CRect`.| +|[`CRect::OffsetRect`](#offsetrect)|Moves `CRect` by the specified offsets.| +|[`CRect::PtInRect`](#ptinrect)|Determines whether the specified point lies within `CRect`.| +|[`CRect::SetRect`](#setrect)|Sets the dimensions of `CRect`.| +|[`CRect::SetRectEmpty`](#setrectempty)|Sets `CRect` to an empty rectangle (all coordinates equal to 0).| +|[`CRect::Size`](#size)|Calculates the size of `CRect`.| +|[`CRect::SubtractRect`](#subtractrect)|Subtracts one rectangle from another.| +|[`CRect::TopLeft`](#topleft)|Returns the top-left point of `CRect`.| +|[`CRect::UnionRect`](#unionrect)|Sets `CRect` equal to the union of two rectangles.| +|[`CRect::Width`](#width)|Calculates the width of `CRect`.| ### Public Operators |Name|Description| |----------|-----------------| -|[CRect::operator -](#operator_-)|Subtracts the given offsets from `CRect` or deflates `CRect` and returns the resulting `CRect`.| -|[CRect::operator LPCRECT](#operator_lpcrect)|Converts a `CRect` to an `LPCRECT`.| -|[CRect::operator LPRECT](#operator_lprect)|Converts a `CRect` to an `LPRECT`.| -|[CRect::operator !=](#operator_neq)|Determines whether `CRect` is not equal to a rectangle.| -|[CRect::operator &](#operator_amp)|Creates the intersection of `CRect` and a rectangle and returns the resulting `CRect`.| -|[CRect::operator &=](#operator_amp_eq)|Sets `CRect` equal to the intersection of `CRect` and a rectangle.| -|[CRect::operator |](#operator_or)|Creates the union of `CRect` and a rectangle and returns the resulting `CRect`.| -|[CRect::operator |=](#operator_or_eq)|Sets `CRect` equal to the union of `CRect` and a rectangle.| -|[CRect::operator +](#operator_add)|Adds the given offsets to `CRect` or inflates `CRect` and returns the resulting `CRect`.| -|[CRect::operator +=](#operator_add_eq)|Adds the specified offsets to `CRect` or inflates `CRect`.| -|[CRect::operator =](#operator_eq)|Copies the dimensions of a rectangle to `CRect`.| -|[CRect::operator -=](#operator_-_eq)|Subtracts the specified offsets from `CRect` or deflates `CRect`.| -|[CRect::operator ==](#operator_eq_eq)|Determines whether `CRect` is equal to a rectangle.| +|[`CRect::operator -`](#operator_-)|Subtracts the given offsets from `CRect` or deflates `CRect` and returns the resulting `CRect`.| +|[`CRect::operator LPCRECT`](#operator_lpcrect)|Converts a `CRect` to an `LPCRECT`.| +|[`CRect::operator LPRECT`](#operator_lprect)|Converts a `CRect` to an `LPRECT`.| +|[`CRect::operator !=`](#operator_neq)|Determines whether `CRect` is not equal to a rectangle.| +|[`CRect::operator &`](#operator_amp)|Creates the intersection of `CRect` and a rectangle and returns the resulting `CRect`.| +|[`CRect::operator &=`](#operator_amp_eq)|Sets `CRect` equal to the intersection of `CRect` and a rectangle.| +|[`CRect::operator |`](#operator_or)|Creates the union of `CRect` and a rectangle and returns the resulting `CRect`.| +|[`CRect::operator |=`](#operator_or_eq)|Sets `CRect` equal to the union of `CRect` and a rectangle.| +|[`CRect::operator +`](#operator_add)|Adds the given offsets to `CRect` or inflates `CRect` and returns the resulting `CRect`.| +|[`CRect::operator +=`](#operator_add_eq)|Adds the specified offsets to `CRect` or inflates `CRect`.| +|[`CRect::operator =`](#operator_eq)|Copies the dimensions of a rectangle to `CRect`.| +|[`CRect::operator -=`](#operator_-_eq)|Subtracts the specified offsets from `CRect` or deflates `CRect`.| +|[`CRect::operator ==`](#operator_eq_eq)|Determines whether `CRect` is equal to a rectangle.| ## Remarks @@ -81,11 +81,11 @@ A `CRect` object can be passed as a function parameter wherever a `RECT` structu A `CRect` contains member variables that define the top-left and bottom-right points of a rectangle. -When specifying a `CRect`, you must be careful to construct it so that it is normalized — in other words, such that the value of the left coordinate is less than the right and the top is less than the bottom. For example, a top left of (10,10) and bottom right of (20,20) defines a normalized rectangle but a top left of (20,20) and bottom right of (10,10) defines a non-normalized rectangle. If the rectangle is not normalized, many `CRect` member functions may return incorrect results. (See [CRect::NormalizeRect](#normalizerect) for a list of these functions.) Before you call a function that requires normalized rectangles, you can normalize non-normalized rectangles by calling the `NormalizeRect` function. +When specifying a `CRect`, you must be careful to construct it so that it is normalized — in other words, such that the value of the left coordinate is less than the right and the top is less than the bottom. For example, a top left of (10,10) and bottom right of (20,20) defines a normalized rectangle but a top left of (20,20) and bottom right of (10,10) defines a non-normalized rectangle. If the rectangle is not normalized, many `CRect` member functions may return incorrect results. (See [`CRect::NormalizeRect`](#normalizerect) for a list of these functions.) Before you call a function that requires normalized rectangles, you can normalize non-normalized rectangles by calling the `NormalizeRect` function. -Use caution when manipulating a `CRect` with the [CDC::DPtoLP](../../mfc/reference/cdc-class.md#dptolp) and [CDC::LPtoDP](../../mfc/reference/cdc-class.md#lptodp) member functions. If the mapping mode of a display context is such that the y-extent is negative, as in `MM_LOENGLISH`, then `CDC::DPtoLP` will transform the `CRect` so that its top is greater than the bottom. Functions such as `Height` and `Size` will then return negative values for the height of the transformed `CRect`, and the rectangle will be non-normalized. +Use caution when manipulating a `CRect` with the [`CDC::DPtoLP`](../../mfc/reference/cdc-class.md#dptolp) and [`CDC::LPtoDP`](../../mfc/reference/cdc-class.md#lptodp) member functions. If the mapping mode of a display context is such that the y-extent is negative, as in `MM_LOENGLISH`, then `CDC::DPtoLP` will transform the `CRect` so that its top is greater than the bottom. Functions such as `Height` and `Size` will then return negative values for the height of the transformed `CRect`, and the rectangle will be non-normalized. -When using overloaded `CRect` operators, the first operand must be a `CRect`; the second can be either a [RECT](/windows/win32/api/windef/ns-windef-rect) structure or a `CRect` object. +When using overloaded `CRect` operators, the first operand must be a `CRect`; the second can be either a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or a `CRect` object. ## Inheritance Hierarchy @@ -95,11 +95,11 @@ When using overloaded `CRect` operators, the first operand must be a `CRect`; th ## Requirements -**Header:** atltypes.h +**Header:** `atltypes.h` -## CRect::BottomRight +## `CRect::BottomRight` -The coordinates are returned as a reference to a [CPoint](cpoint-class.md) object that is contained in `CRect`. +The coordinates are returned as a reference to a [`CPoint`](cpoint-class.md) object that is contained in `CRect`. ``` CPoint& BottomRight() throw(); @@ -140,7 +140,7 @@ rect2.BottomRight() = ptLow; ASSERT(rect2 == CRect(10, 10, 180, 180)); ``` -## CRect::CenterPoint +## `CRect::CenterPoint` Calculates the centerpoint of `CRect` by adding the left and right values and dividing by two, and adding the top and bottom values and dividing by two. @@ -203,7 +203,7 @@ void CMyDlg::OnPaint() } ``` -## CRect::CopyRect +## `CRect::CopyRect` Copies the `lpSrcRect` rectangle into `CRect`. @@ -213,8 +213,8 @@ void CopyRect(LPCRECT lpSrcRect) throw(); ### Parameters -*lpSrcRect*
-Points to the [RECT](/windows/win32/api/windef/ns-windef-rect) structure or `CRect` object that is to be copied. +*`lpSrcRect`*
+Points to the [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or `CRect` object that is to be copied. ### Example @@ -238,7 +238,7 @@ rectDest.CopyRect(&rectSource2); // rectDest is now set to (0, 0, 640, 480) ``` -## CRect::CRect +## `CRect::CRect` Constructs a `CRect` object. @@ -253,41 +253,41 @@ CRect(POINT topLeft, POINT bottomRight) throw(); ### Parameters -*l*
+*`l`*
Specifies the left position of `CRect`. -*t*
+*`t`*
Specifies the top of `CRect`. -*r*
+*`r`*
Specifies the right position of `CRect`. -*b*
+*`b`*
Specifies the bottom of `CRect`. -*srcRect*
-Refers to the [RECT](/windows/win32/api/windef/ns-windef-rect) structure with the coordinates for `CRect`. +*`srcRect`*
+Refers to the [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure with the coordinates for `CRect`. -*lpSrcRect*
+*`lpSrcRect`*
Points to the `RECT` structure with the coordinates for `CRect`. -*point*
+*`point`*
Specifies the origin point for the rectangle to be constructed. Corresponds to the top-left corner. -*size*
+*`size`*
Specifies the displacement from the top-left corner to the bottom-right corner of the rectangle to be constructed. -*topLeft*
+*`topLeft`*
Specifies the top-left position of `CRect`. -*bottomRight*
+*`bottomRight`*
Specifies the bottom-right position of `CRect`. ### Remarks If no arguments are given, `left`, `top`, `right`, and `bottom` members are set to 0. -The `CRect`(`const RECT&`) and `CRect`(`LPCRECT`) constructors perform a [CopyRect](#copyrect). The other constructors initialize the member variables of the object directly. +The `CRect`(`const RECT&`) and `CRect`(`LPCRECT`) constructors perform a [`CopyRect`](#copyrect). The other constructors initialize the member variables of the object directly. ### Example @@ -327,7 +327,7 @@ CRect rect5(pt, ptBottomRight); ASSERT(rect5 == rect4); ``` -## CRect::DeflateRect +## `CRect::DeflateRect` `DeflateRect` deflates `CRect` by moving its sides toward its center. @@ -340,35 +340,35 @@ void DeflateRect(int l, int t, int r, int b) throw(); ### Parameters -*x*
+*`x`*
Specifies the number of units to deflate the left and right sides of `CRect`. -*y*
+*`y`*
Specifies the number of units to deflate the top and bottom of `CRect`. -*size*
-A [SIZE](/windows/win32/api/windef/ns-windef-size) or [CSize](csize-class.md) that specifies the number of units to deflate `CRect`. The `cx` value specifies the number of units to deflate the left and right sides and the `cy` value specifies the number of units to deflate the top and bottom. +*`size`*
+A [`SIZE`](/windows/win32/api/windef/ns-windef-size) or [`CSize`](csize-class.md) that specifies the number of units to deflate `CRect`. The `cx` value specifies the number of units to deflate the left and right sides and the `cy` value specifies the number of units to deflate the top and bottom. -*lpRect*
-Points to a [RECT](/windows/win32/api/windef/ns-windef-rect) structure or `CRect` that specifies the number of units to deflate each side. +*`lpRect`*
+Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or `CRect` that specifies the number of units to deflate each side. -*l*
+*`l`*
Specifies the number of units to deflate the left side of `CRect`. -*t*
+*`t`*
Specifies the number of units to deflate the top of `CRect`. -*r*
+*`r`*
Specifies the number of units to deflate the right side of `CRect`. -*b*
+*`b`*
Specifies the number of units to deflate the bottom of `CRect`. ### Remarks To do this, `DeflateRect` adds units to the left and top and subtracts units from the right and bottom. The parameters of `DeflateRect` are signed values; positive values deflate `CRect` and negative values inflate it. -The first two overloads deflate both pairs of opposite sides of `CRect` so that its total width is decreased by two times *x* (or `cx`) and its total height is decreased by two times *y* (or `cy`). The other two overloads deflate each side of `CRect` independently of the others. +The first two overloads deflate both pairs of opposite sides of `CRect` so that its total width is decreased by two times *`x`* (or `cx`) and its total height is decreased by two times *`y`* (or `cy`). The other two overloads deflate each side of `CRect` independently of the others. ### Example @@ -385,7 +385,7 @@ ASSERT(rect2.left == 11 && rect2.right == 47); ASSERT(rect2.top == 12 && rect2.bottom == 46); ``` -## CRect::EqualRect +## `CRect::EqualRect` Determines whether `CRect` is equal to the given rectangle. @@ -395,15 +395,15 @@ BOOL EqualRect(LPCRECT lpRect) const throw(); ### Parameters -*lpRect*
-Points to a [RECT](/windows/win32/api/windef/ns-windef-rect) structure or `CRect` object that contains the upper-left and lower-right corner coordinates of a rectangle. +*`lpRect`*
+Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or `CRect` object that contains the upper-left and lower-right corner coordinates of a rectangle. ### Return Value Nonzero if the two rectangles have the same top, left, bottom, and right values; otherwise 0. > [!NOTE] -> Both of the rectangles must be normalized or this function may fail. You can call [NormalizeRect](#normalizerect) to normalize the rectangles before calling this function. +> Both of the rectangles must be normalized or this function may fail. You can call [`NormalizeRect`](#normalizerect) to normalize the rectangles before calling this function. ### Example @@ -424,11 +424,11 @@ test.bottom = 25; ASSERT(rect1.EqualRect(&test)); ``` -## CRect::Height +## `CRect::Height` Calculates the height of `CRect` by subtracting the top value from the bottom value. -``` +```cpp int Height() const throw(); ``` @@ -441,7 +441,7 @@ The height of `CRect`. The resulting value can be negative. > [!NOTE] -> The rectangle must be normalized or this function may fail. You can call [NormalizeRect](#normalizerect) to normalize the rectangle before calling this function. +> The rectangle must be normalized or this function may fail. You can call [`NormalizeRect`](#normalizerect) to normalize the rectangle before calling this function. ### Example @@ -453,7 +453,7 @@ int nHt = rect.Height(); ASSERT(nHt == 40); ``` -## CRect::InflateRect +## `CRect::InflateRect` `InflateRect` inflates `CRect` by moving its sides away from its center. @@ -466,35 +466,35 @@ void InflateRect(int l, int t, int r, int b) throw(); ### Parameters -*x*
+*`x`*
Specifies the number of units to inflate the left and right sides of `CRect`. -*y*
+*`y`*
Specifies the number of units to inflate the top and bottom of `CRect`. -*size*
-A [SIZE](/windows/win32/api/windef/ns-windef-size) or [CSize](csize-class.md) that specifies the number of units to inflate `CRect`. The `cx` value specifies the number of units to inflate the left and right sides and the `cy` value specifies the number of units to inflate the top and bottom. +*`size`*
+A [`SIZE`](/windows/win32/api/windef/ns-windef-size) or [`CSize`](csize-class.md) that specifies the number of units to inflate `CRect`. The `cx` value specifies the number of units to inflate the left and right sides and the `cy` value specifies the number of units to inflate the top and bottom. -*lpRect*
-Points to a [RECT](/windows/win32/api/windef/ns-windef-rect) structure or `CRect` that specifies the number of units to inflate each side. +*`lpRect`*
+Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or `CRect` that specifies the number of units to inflate each side. -*l*
+*`l`*
Specifies the number of units to inflate the left side of `CRect`. -*t*
+*`t`*
Specifies the number of units to inflate the top of `CRect`. -*r*
+*`r`*
Specifies the number of units to inflate the right side of `CRect`. -*b*
+*`b`*
Specifies the number of units to inflate the bottom of `CRect`. ### Remarks To do this, `InflateRect` subtracts units from the left and top and adds units to the right and bottom. The parameters of `InflateRect` are signed values; positive values inflate `CRect` and negative values deflate it. -The first two overloads inflate both pairs of opposite sides of `CRect` so that its total width is increased by two times *x* (or `cx`) and its total height is increased by two times *y* (or `cy`). The other two overloads inflate each side of `CRect` independently of the others. +The first two overloads inflate both pairs of opposite sides of `CRect` so that its total width is increased by two times *`x`* (or `cx`) and its total height is increased by two times *`y`* (or `cy`). The other two overloads inflate each side of `CRect` independently of the others. ### Example @@ -506,20 +506,20 @@ rect.InflateRect(50, 200); ASSERT(rect == CRect(-50, -200, 350, 500)); ``` -## CRect::IntersectRect +## `CRect::IntersectRect` Makes a `CRect` equal to the intersection of two existing rectangles. -``` +```cpp BOOL IntersectRect(LPCRECT lpRect1, LPCRECT lpRect2) throw(); ``` ### Parameters -*lpRect1*
-Points to a [RECT](/windows/win32/api/windef/ns-windef-rect) structure or `CRect` object that contains a source rectangle. +*`lpRect1`*
+Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or `CRect` object that contains a source rectangle. -*lpRect2*
+*`lpRect2`*
Points to a `RECT` structure or `CRect` object that contains a source rectangle. ### Return Value @@ -531,7 +531,7 @@ Nonzero if the intersection is not empty; 0 if the intersection is empty. The intersection is the largest rectangle contained in both existing rectangles. > [!NOTE] -> Both of the rectangles must be normalized or this function may fail. You can call [NormalizeRect](#normalizerect) to normalize the rectangles before calling this function. +> Both of the rectangles must be normalized or this function may fail. You can call [`NormalizeRect`](#normalizerect) to normalize the rectangles before calling this function. ### Example @@ -549,11 +549,11 @@ rectInter2 &= rectTwo; ASSERT(rectInter2 == CRect(125, 75, 150, 95)); ``` -## CRect::IsRectEmpty +## `CRect::IsRectEmpty` Determines whether `CRect` is empty. -``` +```cpp BOOL IsRectEmpty() const throw(); ``` @@ -566,7 +566,7 @@ Nonzero if `CRect` is empty; 0 if `CRect` is not empty. A rectangle is empty if the width and/or height are 0 or negative. Differs from `IsRectNull`, which determines whether all coordinates of the rectangle are zero. > [!NOTE] -> The rectangle must be normalized or this function may fail. You can call [NormalizeRect](#normalizerect) to normalize the rectangle before calling this function. +> The rectangle must be normalized or this function may fail. You can call [`NormalizeRect`](#normalizerect) to normalize the rectangle before calling this function. ### Example @@ -579,11 +579,11 @@ CRect rectEmpty(35, 35, 35, 35); ASSERT(rectEmpty.IsRectEmpty()); ``` -## CRect::IsRectNull +## `CRect::IsRectNull` Determines whether the top, left, bottom, and right values of `CRect` are all equal to 0. -``` +```cpp BOOL IsRectNull() const throw(); ``` @@ -608,9 +608,9 @@ CRect rectNotNull(0, 0, 35, 50); ASSERT(!rectNotNull.IsRectNull()); ``` -## CRect::MoveToX +## `CRect::MoveToX` -Call this function to move the rectangle to the absolute x-coordinate specified by *x*. +Call this function to move the rectangle to the absolute x-coordinate specified by *`x`*. ```cpp void MoveToX(int x) throw(); @@ -618,7 +618,7 @@ void MoveToX(int x) throw(); ### Parameters -*x*
+*`x`*
The absolute x-coordinate for the upper-left corner of the rectangle. ### Example @@ -631,7 +631,7 @@ rect.MoveToX(10); ASSERT(rect == CRect(10, 0, 110, 100)); ``` -## CRect::MoveToXY +## `CRect::MoveToXY` Call this function to move the rectangle to the absolute x- and y-coordinates specified. @@ -642,13 +642,13 @@ void MoveToXY(POINT point) throw(); ### Parameters -*x*
+*`x`*
The absolute x-coordinate for the upper-left corner of the rectangle. -*y*
+*`y`*
The absolute y-coordinate for the upper-left corner of the rectangle. -*point*
+*`point`*
A `POINT` structure specifying the absolute upper-left corner of the rectangle. ### Example @@ -660,9 +660,9 @@ rect.MoveToXY(10, 10); ASSERT(rect == CRect(10, 10, 110, 110)); ``` -## CRect::MoveToY +## `CRect::MoveToY` -Call this function to move the rectangle to the absolute y-coordinate specified by *y*. +Call this function to move the rectangle to the absolute y-coordinate specified by *`y`*. ```cpp void MoveToY(int y) throw(); @@ -670,7 +670,7 @@ void MoveToY(int y) throw(); ### Parameters -*y*
+*`y`*
The absolute y-coordinate for the upper-left corner of the rectangle. ### Example @@ -682,7 +682,7 @@ rect.MoveToY(10); ASSERT(rect == CRect(0, 10, 100, 110)); ``` -## CRect::NormalizeRect +## `CRect::NormalizeRect` Normalizes `CRect` so that both the height and width are positive. @@ -695,7 +695,7 @@ void NormalizeRect() throw(); The rectangle is normalized for fourth-quadrant positioning, which Windows typically uses for coordinates. `NormalizeRect` compares the top and bottom values, and swaps them if the top is greater than the bottom. Similarly, it swaps the left and right values if the left is greater than the right. This function is useful when dealing with different mapping modes and inverted rectangles. > [!NOTE] -> The following `CRect` member functions require normalized rectangles in order to work properly: [Height](#height), [Width](#width), [Size](#size), [IsRectEmpty](#isrectempty), [PtInRect](#ptinrect), [EqualRect](#equalrect), [UnionRect](#unionrect), [IntersectRect](#intersectrect), [SubtractRect](#subtractrect), [operator ==](#operator_eq_eq), [operator !=](#operator_neq), [operator |](#operator_or), [operator |=](#operator_or_eq), [operator &](#operator_amp), and [operator &=](#operator_amp_eq). +> The following `CRect` member functions require normalized rectangles in order to work properly: [`Height`](#height), [`Width`](#width), [`Size`](#size), [`IsRectEmpty`](#isrectempty), [`PtInRect`](#ptinrect), [`EqualRect`](#equalrect), [`UnionRect`](#unionrect), [`IntersectRect`](#intersectrect), [`SubtractRect`](#subtractrect), [`operator ==`](#operator_eq_eq), [`operator !=`](#operator_neq), [`operator |`](#operator_or), [`operator |=`](#operator_or_eq), [`operator &`](#operator_amp), and [`operator &=`](#operator_amp_eq). ### Example @@ -707,7 +707,7 @@ rect2.NormalizeRect(); ASSERT(rect1 == rect2); ``` -## CRect::OffsetRect +## `CRect::OffsetRect` Moves `CRect` by the specified offsets. @@ -719,21 +719,21 @@ void OffsetRect(SIZE size) throw(); ### Parameters -*x*
+*`x`*
Specifies the amount to move left or right. It must be negative to move left. -*y*
+*`y`*
Specifies the amount to move up or down. It must be negative to move up. -*point*
-Contains a [POINT](/windows/win32/api/windef/ns-windef-point) structure or [CPoint](cpoint-class.md) object specifying both dimensions by which to move. +*`point`*
+Contains a [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or [`CPoint`](cpoint-class.md) object specifying both dimensions by which to move. -*size*
-Contains a [SIZE](/windows/win32/api/windef/ns-windef-size) structure or [CSize](csize-class.md) object specifying both dimensions by which to move. +*`size`*
+Contains a [`SIZE`](/windows/win32/api/windef/ns-windef-size) structure or [`CSize`](csize-class.md) object specifying both dimensions by which to move. ### Remarks -Moves `CRect`*x* units along the x-axis and *y* units along the y-axis. The *x* and *y* parameters are signed values, so `CRect` can be moved left or right and up or down. +Moves `CRect`*`x`* units along the x-axis and *`y`* units along the y-axis. The *`x`* and *`y`* parameters are signed values, so `CRect` can be moved left or right and up or down. ### Example @@ -745,35 +745,35 @@ rect.OffsetRect(230, 230); ASSERT(rect == CRect(230, 230, 265, 265)); ``` -## CRect::operator LPCRECT Converts a `CRect` to an [LPCRECT](../../mfc/reference/data-types-mfc.md). +## `CRect::operator LPCRECT` Converts a `CRect` to an [`LPCRECT`](../../mfc/reference/data-types-mfc.md). -``` +```cpp operator LPCRECT() const throw(); ``` ### Remarks -When you use this function, you don't need the address-of (**&**) operator. This operator will be automatically used when you pass a `CRect` object to a function that expects an `LPCRECT`. +When you use this function, you don't need the address-of (**`&`**) operator. This operator will be automatically used when you pass a `CRect` object to a function that expects an `LPCRECT`. -## CRect::operator LPRECT +## `CRect::operator LPRECT` -Converts a `CRect` to an [LPRECT](../../mfc/reference/data-types-mfc.md). +Converts a `CRect` to an [`LPRECT`](../../mfc/reference/data-types-mfc.md). -``` +```cpp operator LPRECT() throw(); ``` ### Remarks -When you use this function, you don't need the address-of (**&**) operator. This operator will be automatically used when you pass a `CRect` object to a function that expects an `LPRECT`. +When you use this function, you don't need the address-of (**`&`**) operator. This operator will be automatically used when you pass a `CRect` object to a function that expects an `LPRECT`. ### Example -See the example for [CRect::operator LPCRECT](#operator_lpcrect). +See the example for [`CRect::operator LPCRECT`](#operator_lpcrect). -## CRect::operator = +## `CRect::operator =` -Assigns *srcRect* to `CRect`. +Assigns *`srcRect`* to `CRect`. ```cpp void operator=(const RECT& srcRect) throw(); @@ -781,8 +781,8 @@ void operator=(const RECT& srcRect) throw(); ### Parameters -*srcRect*
-Refers to a source rectangle. Can be a [RECT](/windows/win32/api/windef/ns-windef-rect) or `CRect`. +*`srcRect`*
+Refers to a source rectangle. Can be a [`RECT`](/windows/win32/api/windef/ns-windef-rect) or `CRect`. ### Example @@ -794,18 +794,18 @@ rect2 = rect; ASSERT(rect2 == CRect(0, 0, 127, 168)); ``` -## CRect::operator == +## `CRect::operator ==` Determines whether `rect` is equal to `CRect` by comparing the coordinates of their upper-left and lower-right corners. -``` +```cpp BOOL operator==(const RECT& rect) const throw(); ``` ### Parameters -*rect*
-Refers to a source rectangle. Can be a [RECT](/windows/win32/api/windef/ns-windef-rect) or `CRect`. +*`rect`*
+Refers to a source rectangle. Can be a [`RECT`](/windows/win32/api/windef/ns-windef-rect) or `CRect`. ### Return Value @@ -814,7 +814,7 @@ Nonzero if equal; otherwise 0. ### Remarks > [!NOTE] -> Both of the rectangles must be normalized or this function may fail. You can call [NormalizeRect](#normalizerect) to normalize the rectangles before calling this function. +> Both of the rectangles must be normalized or this function may fail. You can call [`NormalizeRect`](#normalizerect) to normalize the rectangles before calling this function. ### Example @@ -834,18 +834,18 @@ test.bottom = 25; ASSERT(rect1 == test); ``` -## CRect::operator != +## `CRect::operator !=` -Determines whether *rect* is not equal to `CRect` by comparing the coordinates of their upper-left and lower-right corners. +Determines whether *`rect`* is not equal to `CRect` by comparing the coordinates of their upper-left and lower-right corners. -``` +```cpp BOOL operator!=(const RECT& rect) const throw(); ``` ### Parameters -*rect*
-Refers to a source rectangle. Can be a [RECT](/windows/win32/api/windef/ns-windef-rect) or `CRect`. +*`rect`*
+Refers to a source rectangle. Can be a [`RECT`](/windows/win32/api/windef/ns-windef-rect) or `CRect`. ### Return Value @@ -854,7 +854,7 @@ Nonzero if not equal; otherwise 0. ### Remarks > [!NOTE] -> Both of the rectangles must be normalized or this function may fail. You can call [NormalizeRect](#normalizerect) to normalize the rectangles before calling this function. +> Both of the rectangles must be normalized or this function may fail. You can call [`NormalizeRect`](#normalizerect) to normalize the rectangles before calling this function. ### Example @@ -874,7 +874,7 @@ test.bottom = 25; ASSERT(rect3 != test); ``` -## CRect::operator += +## `CRect::operator +=` The first two overloads move `CRect` by the specified offsets. @@ -886,18 +886,18 @@ void operator+=(LPCRECT lpRect) throw(); ### Parameters -*point*
-A [POINT](/windows/win32/api/windef/ns-windef-point) structure or [CPoint](cpoint-class.md) object that specifies the number of units to move the rectangle. +*`point`*
+A [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or [`CPoint`](cpoint-class.md) object that specifies the number of units to move the rectangle. -*size*
-A [SIZE](/windows/win32/api/windef/ns-windef-size) structure or [CSize](csize-class.md) object that specifies the number of units to move the rectangle. +*`size`*
+A [`SIZE`](/windows/win32/api/windef/ns-windef-size) structure or [`CSize`](csize-class.md) object that specifies the number of units to move the rectangle. -*lpRect*
-Points to a [RECT](/windows/win32/api/windef/ns-windef-rect) structure or `CRect` object that contains the number of units to inflate each side of `CRect`. +*`lpRect`*
+Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or `CRect` object that contains the number of units to inflate each side of `CRect`. ### Remarks -The parameter's *x* and *y* (or `cx` and `cy`) values are added to `CRect`. +The parameter's *`x`* and *`y`* (or `cx` and `cy`) values are added to `CRect`. The third overload inflates `CRect` by the number of units specified in each member of the parameter. @@ -912,7 +912,7 @@ rect1 += pt; ASSERT(rect1 == rect2); ``` -## CRect::operator -= +## `CRect::operator -=` The first two overloads move `CRect` by the specified offsets. @@ -924,20 +924,20 @@ void operator-=(LPCRECT lpRect) throw(); ### Parameters -*point*
-A [POINT](/windows/win32/api/windef/ns-windef-point) structure or [CPoint](cpoint-class.md) object that specifies the number of units to move the rectangle. +*`point`*
+A [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or [`CPoint`](cpoint-class.md) object that specifies the number of units to move the rectangle. -*size*
-A [SIZE](/windows/win32/api/windef/ns-windef-size) structure or [CSize](csize-class.md) object that specifies the number of units to move the rectangle. +*`size`*
+A [`SIZE`](/windows/win32/api/windef/ns-windef-size) structure or [`CSize`](csize-class.md) object that specifies the number of units to move the rectangle. -*lpRect*
-Points to a [RECT](/windows/win32/api/windef/ns-windef-rect) structure or `CRect` object that contains the number of units to deflate each side of `CRect`. +*`lpRect`*
+Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or `CRect` object that contains the number of units to deflate each side of `CRect`. ### Remarks -The parameter's *x* and *y* (or `cx` and `cy`) values are subtracted from `CRect`. +The parameter's *`x`* and *`y`* (or `cx` and `cy`) values are subtracted from `CRect`. -The third overload deflates `CRect` by the number of units specified in each member of the parameter. Note that this overload functions like [DeflateRect](#deflaterect). +The third overload deflates `CRect` by the number of units specified in each member of the parameter. Note that this overload functions like [`DeflateRect`](#deflaterect). ### Example @@ -950,7 +950,7 @@ CRect rectResult(65, 170, 165, 270); ASSERT(rect1 == rectResult); ``` -## CRect::operator &= +## `CRect::operator &=` Sets `CRect` equal to the intersection of `CRect` and `rect`. @@ -960,21 +960,21 @@ void operator&=(const RECT& rect) throw(); ### Parameters -*rect*
-Contains a [RECT](/windows/win32/api/windef/ns-windef-rect) or `CRect`. +*`rect`*
+Contains a [`RECT`](/windows/win32/api/windef/ns-windef-rect) or `CRect`. ### Remarks The intersection is the largest rectangle that is contained in both rectangles. > [!NOTE] -> Both of the rectangles must be normalized or this function may fail. You can call [NormalizeRect](#normalizerect) to normalize the rectangles before calling this function. +> Both of the rectangles must be normalized or this function may fail. You can call [`NormalizeRect`](#normalizerect) to normalize the rectangles before calling this function. ### Example -See the example for [CRect::IntersectRect](#intersectrect). +See the example for [`CRect::IntersectRect`](#intersectrect). -## CRect::operator |= +## `CRect::operator |=` Sets `CRect` equal to the union of `CRect` and `rect`. @@ -984,15 +984,15 @@ void operator|=(const RECT& rect) throw(); ### Parameters -*rect*
-Contains a `CRect` or [RECT](/windows/win32/api/windef/ns-windef-rect). +*`rect`*
+Contains a `CRect` or [`RECT`](/windows/win32/api/windef/ns-windef-rect). ### Remarks The union is the smallest rectangle that contains both source rectangles. > [!NOTE] -> Both of the rectangles must be normalized or this function may fail. You can call [NormalizeRect](#normalizerect) to normalize the rectangles before calling this function. +> Both of the rectangles must be normalized or this function may fail. You can call [`NormalizeRect`](#normalizerect) to normalize the rectangles before calling this function. ### Example @@ -1005,11 +1005,11 @@ CRect rectResult(0, 0, 300, 300); ASSERT(rectResult == rect1); ``` -## CRect::operator + +## `CRect::operator +` The first two overloads return a `CRect` object that is equal to `CRect` displaced by the specified offsets. -``` +```cpp CRect operator+(POINT point) const throw(); CRect operator+(LPCRECT lpRect) const throw(); CRect operator+(SIZE size) const throw(); @@ -1017,14 +1017,14 @@ CRect operator+(SIZE size) const throw(); ### Parameters -*point*
-A [POINT](/windows/win32/api/windef/ns-windef-point) structure or [CPoint](cpoint-class.md) object that specifies the number of units to move the return value. +*`point`*
+A [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or [`CPoint`](cpoint-class.md) object that specifies the number of units to move the return value. -*size*
-A [SIZE](/windows/win32/api/windef/ns-windef-size) structure or [CSize](csize-class.md) object that specifies the number of units to move the return value. +*`size`*
+A [`SIZE`](/windows/win32/api/windef/ns-windef-size) structure or [`CSize`](csize-class.md) object that specifies the number of units to move the return value. -*lpRect*
-Points to a [RECT](/windows/win32/api/windef/ns-windef-rect) structure or `CRect` object that contains the number of units to inflate each side of the return value. +*`lpRect`*
+Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or `CRect` object that contains the number of units to inflate each side of the return value. ### Return Value @@ -1032,7 +1032,7 @@ The `CRect` resulting from moving or inflating `CRect` by the number of units sp ### Remarks -The parameter's *x* and *y* (or `cx` and `cy`) parameters are added to `CRect`'s position. +The parameter's *`x`* and *`y`* (or `cx` and `cy`) parameters are added to `CRect`'s position. The third overload returns a new `CRect` that is equal to `CRect` inflated by the number of units specified in each member of the parameter. @@ -1048,11 +1048,11 @@ CRect rectResult(135, 300, 235, 400); ASSERT(rectResult == rect2); ``` -## CRect::operator - +## `CRect::operator -` The first two overloads return a `CRect` object that is equal to `CRect` displaced by the specified offsets. -``` +```cpp CRect operator-(POINT point) const throw(); CRect operator-(SIZE size) const throw(); CRect operator-(LPCRECT lpRect) const throw(); @@ -1060,14 +1060,14 @@ CRect operator-(LPCRECT lpRect) const throw(); ### Parameters -*point*
-A [POINT](/windows/win32/api/windef/ns-windef-point) structure or `CPoint` object that specifies the number of units to move the return value. +*`point`*
+A [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or `CPoint` object that specifies the number of units to move the return value. -*size*
-A [SIZE](/windows/win32/api/windef/ns-windef-size) structure or `CSize` object that specifies the number of units to move the return value. +*`size`*
+A [`SIZE`](/windows/win32/api/windef/ns-windef-size) structure or `CSize` object that specifies the number of units to move the return value. -*lpRect*
-Points to a [RECT](/windows/win32/api/windef/ns-windef-rect) structure or `CRect` object that contains the number of units to deflate each side of the return value. +*`lpRect`*
+Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or `CRect` object that contains the number of units to deflate each side of the return value. ### Return Value @@ -1075,9 +1075,9 @@ The `CRect` resulting from moving or deflating `CRect` by the number of units sp ### Remarks -The parameter's *x* and *y* (or `cx` and `cy`) parameters are subtracted from `CRect`'s position. +The parameter's *`x`* and *`y`* (or `cx` and `cy`) parameters are subtracted from `CRect`'s position. -The third overload returns a new `CRect` that is equal to `CRect` deflated by the number of units specified in each member of the parameter. Note that this overload functions like [DeflateRect](#deflaterect), not [SubtractRect](#subtractrect). +The third overload returns a new `CRect` that is equal to `CRect` deflated by the number of units specified in each member of the parameter. Note that this overload functions like [`DeflateRect`](#deflaterect), not [`SubtractRect`](#subtractrect). ### Example @@ -1091,29 +1091,29 @@ CRect rectResult(65, 170, 165, 270); ASSERT(rect2 == rectResult); ``` -## CRect::operator & +## `CRect::operator &` Returns a `CRect` that is the intersection of `CRect` and *rect2*. -``` +```cpp CRect operator&(const RECT& rect2) const throw(); ``` ### Parameters -*rect2*
-Contains a [RECT](/windows/win32/api/windef/ns-windef-rect) or `CRect`. +*`rect2`*
+Contains a [`RECT`](/windows/win32/api/windef/ns-windef-rect) or `CRect`. ### Return Value -A `CRect` that is the intersection of `CRect` and *rect2*. +A `CRect` that is the intersection of `CRect` and *`rect2`*. ### Remarks The intersection is the largest rectangle that is contained in both rectangles. > [!NOTE] -> Both of the rectangles must be normalized or this function may fail. You can call [NormalizeRect](#normalizerect) to normalize the rectangles before calling this function. +> Both of the rectangles must be normalized or this function may fail. You can call [`NormalizeRect`](#normalizerect) to normalize the rectangles before calling this function. ### Example @@ -1127,30 +1127,30 @@ CRect rectResult(100, 100, 200, 200); ASSERT(rectResult == rect3); ``` -## CRect::operator | +## `CRect::operator |` -Returns a `CRect` that is the union of `CRect` and *rect2*. +Returns a `CRect` that is the union of `CRect` and *`rect2`*. -``` +```cpp CRect operator|(const RECT& rect2) const throw(); ``` ### Parameters -*rect2*
-Contains a [RECT](/windows/win32/api/windef/ns-windef-rect) or `CRect`. +*`rect2`*
+Contains a [`RECT`](/windows/win32/api/windef/ns-windef-rect) or `CRect`. ### Return Value -A `CRect` that is the union of `CRect` and *rect2*. +A `CRect` that is the union of `CRect` and *`rect2`*. ### Remarks The union is the smallest rectangle that contains both rectangles. > [!NOTE] -> Both of the rectangles must be normalized or this function may fail. You can call [NormalizeRect](#normalizerect) to normalize the rectangles before calling this function. +> Both of the rectangles must be normalized or this function may fail. You can call [`NormalizeRect`](#normalizerect) to normalize the rectangles before calling this function. ### Example @@ -1164,18 +1164,18 @@ CRect rectResult(0, 0, 300, 300); ASSERT(rectResult == rect3); ``` -## CRect::PtInRect +## `CRect::PtInRect` Determines whether the specified point lies within `CRect`. -``` +```cpp BOOL PtInRect(POINT point) const throw(); ``` ### Parameters -*point*
-Contains a [POINT](/windows/win32/api/windef/ns-windef-point) structure or [CPoint](cpoint-class.md) object. +*`point`*
+Contains a [`POINT`](/windows/win32/api/windef/ns-windef-point) structure or [`CPoint`](cpoint-class.md) object. ### Return Value @@ -1186,7 +1186,7 @@ Nonzero if the point lies within `CRect`; otherwise 0. A point is within `CRect` if it lies on the left or top side or is within all four sides. A point on the right or bottom side is outside `CRect`. > [!NOTE] -> The rectangle must be normalized or this function may fail. You can call [NormalizeRect](#normalizerect) to normalize the rectangle before calling this function. +> The rectangle must be normalized or this function may fail. You can call [`NormalizeRect`](#normalizerect) to normalize the rectangle before calling this function. ### Example @@ -1216,7 +1216,7 @@ pt.y = 50; ASSERT(rect.PtInRect(pt)); ``` -## CRect::SetRect +## `CRect::SetRect` Sets the dimensions of `CRect` to the specified coordinates. @@ -1226,16 +1226,16 @@ void SetRect(int x1, int y1, int x2, int y2) throw(); ### Parameters -*x1*
+*`x1`*
Specifies the x-coordinate of the upper-left corner. -*y1*
+*`y1`*
Specifies the y-coordinate of the upper-left corner. -*x2*
+*`x2`*
Specifies the x-coordinate of the lower-right corner. -*y2*
+*`y2`*
Specifies the y-coordinate of the lower-right corner. ### Example @@ -1246,7 +1246,7 @@ rect.SetRect(256, 256, 512, 512); ASSERT(rect == CRect(256, 256, 512, 512)); ``` -## CRect::SetRectEmpty +## `CRect::SetRectEmpty` Makes `CRect` a null rectangle by setting all coordinates to zero. @@ -1264,7 +1264,7 @@ rect.SetRectEmpty(); ASSERT(rect.IsRectEmpty()); ``` -## CRect::SIZE +## `CRect::SIZE` The `cx` and `cy` members of the return value contain the height and width of `CRect`. @@ -1274,14 +1274,14 @@ CSize Size() const throw(); ### Return Value -A [CSize](csize-class.md) object that contains the size of `CRect`. +A [`CSize`](csize-class.md) object that contains the size of `CRect`. ### Remarks Either the height or width can be negative. > [!NOTE] -> The rectangle must be normalized or this function may fail. You can call [NormalizeRect](#normalizerect) to normalize the rectangle before calling this function. +> The rectangle must be normalized or this function may fail. You can call [`NormalizeRect`](#normalizerect) to normalize the rectangle before calling this function. ### Example @@ -1291,21 +1291,21 @@ CSize sz = rect.Size(); ASSERT(sz.cx == 40 && sz.cy == 40); ``` -## CRect::SubtractRect +## `CRect::SubtractRect` Makes the dimensions of the `CRect` equal to the subtraction of `lpRectSrc2` from `lpRectSrc1`. -``` +```cpp BOOL SubtractRect(LPCRECT lpRectSrc1, LPCRECT lpRectSrc2) throw(); ``` ### Parameters -*lpRectSrc1*
-Points to the [RECT](/windows/win32/api/windef/ns-windef-rect) structure or `CRect` object from which a rectangle is to be subtracted. +*`lpRectSrc1`*
+Points to the [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure or `CRect` object from which a rectangle is to be subtracted. -*lpRectSrc2*
-Points to the `RECT` structure or `CRect` object that is to be subtracted from the rectangle pointed to by the *lpRectSrc1* parameter. +*`lpRectSrc2`*
+Points to the `RECT` structure or `CRect` object that is to be subtracted from the rectangle pointed to by the *`lpRectSrc1`* parameter. ### Return Value @@ -1313,16 +1313,16 @@ Nonzero if the function is successful; otherwise 0. ### Remarks -The subtraction is the smallest rectangle that contains all of the points in *lpRectScr1* that are not in the intersection of *lpRectScr1* and *lpRectScr2*. +The subtraction is the smallest rectangle that contains all of the points in *`lpRectScr1`* that are not in the intersection of *`lpRectScr1`* and *`lpRectScr2`*. -The rectangle specified by *lpRectSrc1* will be unchanged if the rectangle specified by *lpRectSrc2* doesn't completely overlap the rectangle specified by *lpRectSrc1* in at least one of the x- or y-directions. +The rectangle specified by *`lpRectSrc1`* will be unchanged if the rectangle specified by *`lpRectSrc2`* doesn't completely overlap the rectangle specified by *`lpRectSrc1`* in at least one of the x- or y-directions. -For example, if *lpRectSrc1* were (10,10, 100,100) and *lpRectSrc2* were (50,50, 150,150), the rectangle pointed to by *lpRectSrc1* would be unchanged when the function returned. If *lpRectSrc1* were (10,10, 100,100) and *lpRectSrc2* were (50,10, 150,150), however, the rectangle pointed to by *lpRectSrc1* would contain the coordinates (10,10, 50,100) when the function returned. +For example, if *`lpRectSrc1`* were (10,10, 100,100) and *`lpRectSrc2`* were (50,50, 150,150), the rectangle pointed to by *`lpRectSrc1`* would be unchanged when the function returned. If *`lpRectSrc1`* were (10,10, 100,100) and *`lpRectSrc2`* were (50,10, 150,150), however, the rectangle pointed to by *`lpRectSrc1`* would contain the coordinates (10,10, 50,100) when the function returned. `SubtractRect` is not the same as [operator -](#operator_-) nor [operator -=](#operator_-_eq). Neither of these operators ever calls `SubtractRect`. > [!NOTE] -> Both of the rectangles must be normalized or this function may fail. You can call [NormalizeRect](#normalizerect) to normalize the rectangles before calling this function. +> Both of the rectangles must be normalized or this function may fail. You can call [`NormalizeRect`](#normalizerect) to normalize the rectangles before calling this function. ### Example @@ -1358,11 +1358,11 @@ rectOut.SubtractRect(rect1, rect2); ASSERT(rectResult == rectOut); ``` -## CRect::TopLeft +## `CRect::TopLeft` -The coordinates are returned as a reference to a [CPoint](cpoint-class.md) object that is contained in `CRect`. +The coordinates are returned as a reference to a [`CPoint`](cpoint-class.md) object that is contained in `CRect`. -``` +```cpp CPoint& TopLeft() throw(); const CPoint& TopLeft() const throw(); ``` @@ -1377,22 +1377,22 @@ You can use this function to either get or set the top-left corner of the rectan ### Example -See the example for [CRect::CenterPoint](#centerpoint). +See the example for [`CRect::CenterPoint`](#centerpoint). -## CRect::UnionRect +## `CRect::UnionRect` Makes the dimensions of `CRect` equal to the union of the two source rectangles. -``` +```cpp BOOL UnionRect(LPCRECT lpRect1, LPCRECT lpRect2) throw(); ``` ### Parameters -*lpRect1*
-Points to a [RECT](/windows/win32/api/windef/ns-windef-rect) or `CRect` that contains a source rectangle. +*`lpRect1`*
+Points to a [`RECT`](/windows/win32/api/windef/ns-windef-rect) or `CRect` that contains a source rectangle. -*lpRect2*
+*`lpRect2`*
Points to a `RECT` or `CRect` that contains a source rectangle. ### Return Value @@ -1406,7 +1406,7 @@ The union is the smallest rectangle that contains both source rectangles. Windows ignores the dimensions of an empty rectangle; that is, a rectangle that has no height or has no width. > [!NOTE] -> Both of the rectangles must be normalized or this function may fail. You can call [NormalizeRect](#normalizerect) to normalize the rectangles before calling this function. +> Both of the rectangles must be normalized or this function may fail. You can call [`NormalizeRect`](#normalizerect) to normalize the rectangles before calling this function. ### Example @@ -1420,11 +1420,11 @@ CRect rectResult(0, 0, 300, 300); ASSERT(rectResult == rect3); ``` -## CRect::Width +## `CRect::Width` Calculates the width of `CRect` by subtracting the left value from the right value. -``` +```cpp int Width() const throw(); ``` @@ -1437,7 +1437,7 @@ The width of `CRect`. The width can be negative. > [!NOTE] -> The rectangle must be normalized or this function may fail. You can call [NormalizeRect](#normalizerect) to normalize the rectangle before calling this function. +> The rectangle must be normalized or this function may fail. You can call [`NormalizeRect`](#normalizerect) to normalize the rectangle before calling this function. ### Example @@ -1450,6 +1450,6 @@ ASSERT(nWid == 60); ## See also -[CPoint Class](cpoint-class.md)
-[CSize Class](csize-class.md)
-[RECT](/windows/win32/api/windef/ns-windef-rect) +[`CPoint` Class](cpoint-class.md)
+[`CSize` Class](csize-class.md)
+[`RECT`](/windows/win32/api/windef/ns-windef-rect) diff --git a/docs/atl-mfc-shared/reference/csimplestringt-class.md b/docs/atl-mfc-shared/reference/csimplestringt-class.md index 5cd20a4600..b62a850efa 100644 --- a/docs/atl-mfc-shared/reference/csimplestringt-class.md +++ b/docs/atl-mfc-shared/reference/csimplestringt-class.md @@ -1,32 +1,31 @@ --- -description: "Learn more about: CSimpleStringT Class" title: "CSimpleStringT Class" -ms.date: "10/18/2018" +description: "Learn more about: CSimpleStringT class" +ms.date: 01/26/2024 f1_keywords: ["CSimpleStringT", "ATLSIMPSTR/ATL::CSimpleStringT", "ATLSIMPSTR/ATL::CSimpleStringT::PCXSTR", "ATLSIMPSTR/ATL::CSimpleStringT::PXSTR", "ATLSIMPSTR/ATL::CSimpleStringT::CSimpleStringT", "ATLSIMPSTR/ATL::CSimpleStringT::Append", "ATLSIMPSTR/ATL::CSimpleStringT::AppendChar", "ATLSIMPSTR/ATL::CSimpleStringT::CopyChars", "ATLSIMPSTR/ATL::CSimpleStringT::CopyCharsOverlapped", "ATLSIMPSTR/ATL::CSimpleStringT::Empty", "ATLSIMPSTR/ATL::CSimpleStringT::FreeExtra", "ATLSIMPSTR/ATL::CSimpleStringT::GetAllocLength", "ATLSIMPSTR/ATL::CSimpleStringT::GetAt", "ATLSIMPSTR/ATL::CSimpleStringT::GetBuffer", "ATLSIMPSTR/ATL::CSimpleStringT::GetBufferSetLength", "ATLSIMPSTR/ATL::CSimpleStringT::GetLength", "ATLSIMPSTR/ATL::CSimpleStringT::GetManager", "ATLSIMPSTR/ATL::CSimpleStringT::GetString", "ATLSIMPSTR/ATL::CSimpleStringT::IsEmpty", "ATLSIMPSTR/ATL::CSimpleStringT::LockBuffer", "ATLSIMPSTR/ATL::CSimpleStringT::Preallocate", "ATLSIMPSTR/ATL::CSimpleStringT::ReleaseBuffer", "ATLSIMPSTR/ATL::CSimpleStringT::ReleaseBufferSetLength", "ATLSIMPSTR/ATL::CSimpleStringT::SetAt", "ATLSIMPSTR/ATL::CSimpleStringT::SetManager", "ATLSIMPSTR/ATL::CSimpleStringT::SetString", "ATLSIMPSTR/ATL::CSimpleStringT::StringLength", "ATLSIMPSTR/ATL::CSimpleStringT::Truncate", "ATLSIMPSTR/ATL::CSimpleStringT::UnlockBuffer"] helpviewer_keywords: ["shared classes, CSimpleStringT", "strings [C++], ATL class", "CSimpleStringT class"] -ms.assetid: 15814fcb-5b8f-4425-a97e-3b61fc9b48d8 --- -# CSimpleStringT Class +# `CSimpleStringT` Class This class represents a `CSimpleStringT` object. ## Syntax -``` +```cpp template class CSimpleStringT ``` ### Parameters -*BaseType*
+*`BaseType`*\ The character type of the string class. Can be one of the following: - **`char`** (for ANSI character strings). - **`wchar_t`** (for Unicode character strings). -- TCHAR (for both ANSI and Unicode character strings). +- `TCHAR` (for both ANSI and Unicode character strings). ## Members @@ -34,63 +33,63 @@ The character type of the string class. Can be one of the following: |Name|Description| |----------|-----------------| -|[CSimpleStringT::PCXSTR](#pcxstr)|A pointer to a constant string.| -|[CSimpleStringT::PXSTR](#pxstr)|A pointer to a string.| +|[`CSimpleStringT::PCXSTR`](#pcxstr)|A pointer to a constant string.| +|[`CSimpleStringT::PXSTR`](#pxstr)|A pointer to a string.| ### Public Constructors |Name|Description| |----------|-----------------| -|[CSimpleStringT::CSimpleStringT](#ctor)|Constructs `CSimpleStringT` objects in various ways.| -|[CSimpleStringT::~CSimpleStringT](#dtor)|Destructor.| +|[`CSimpleStringT::CSimpleStringT`](#ctor)|Constructs `CSimpleStringT` objects in various ways.| +|[`CSimpleStringT::~CSimpleStringT`](#dtor)|Destructor.| ### Public Methods |Name|Description| |----------|-----------------| -|[CSimpleStringT::Append](#append)|Appends a `CSimpleStringT` object to an existing `CSimpleStringT` object.| -|[CSimpleStringT::AppendChar](#appendchar)|Appends a character to an existing `CSimpleStringT` object.| -|[CSimpleStringT::CopyChars](#copychars)|Copies a character or characters to another string.| -|[CSimpleStringT::CopyCharsOverlapped](#copycharsoverlapped)|Copies a character or characters to another string in which the buffers overlap.| -|[CSimpleStringT::Empty](#empty)|Forces a string to have a length of zero.| -|[CSimpleStringT::FreeExtra](#freeextra)|Frees any extra memory previously allocated by the string object.| -|[CSimpleStringT::GetAllocLength](#getalloclength)|Retrieves the allocated length of a `CSimpleStringT` object.| -|[CSimpleStringT::GetAt](#getat)|Returns the character at a given position.| -|[CSimpleStringT::GetBuffer](#getbuffer)|Returns a pointer to the characters in a `CSimpleStringT`.| -|[CSimpleStringT::GetBufferSetLength](#getbuffersetlength)|Returns a pointer to the characters in a `CSimpleStringT`, truncating to the specified length.| -|[CSimpleStringT::GetLength](#getlength)|Returns the number of characters in a `CSimpleStringT` object.| -|[CSimpleStringT::GetManager](#getmanager)|Retrieves the memory manager of the `CSimpleStringT` object.| -|[CSimpleStringT::GetString](#getstring)|Retrieves the character string| -|[CSimpleStringT::IsEmpty](#isempty)|Tests whether a `CSimpleStringT` object contains no characters.| -|[CSimpleStringT::LockBuffer](#lockbuffer)|Disables reference counting and protects the string in the buffer.| -|[CSimpleStringT::Preallocate](#preallocate)|Allocates a specific amount of memory for the character buffer.| -|[CSimpleStringT::ReleaseBuffer](#releasebuffer)|Releases control of the buffer returned by `GetBuffer`.| -|[CSimpleStringT::ReleaseBufferSetLength](#releasebuffersetlength)|Releases control of the buffer returned by `GetBuffer`.| -|[CSimpleStringT::SetAt](#setat)|Sets a character at a given position.| -|[CSimpleStringT::SetManager](#setmanager)|Sets the memory manager of a `CSimpleStringT` object.| -|[CSimpleStringT::SetString](#setstring)|Sets the string of a `CSimpleStringT` object.| -|[CSimpleStringT::StringLength](#stringlength)|Returns the number of characters in the specified string.| -|[CSimpleStringT::Truncate](#truncate)|Truncates the string to a specified length.| -|[CSimpleStringT::UnlockBuffer](#unlockbuffer)|Enables reference counting and releases the string in the buffer.| +|[`CSimpleStringT::Append`](#append)|Appends a `CSimpleStringT` object to an existing `CSimpleStringT` object.| +|[`CSimpleStringT::AppendChar`](#appendchar)|Appends a character to an existing `CSimpleStringT` object.| +|[`CSimpleStringT::CopyChars`](#copychars)|Copies a character or characters to another string.| +|[`CSimpleStringT::CopyCharsOverlapped`](#copycharsoverlapped)|Copies a character or characters to another string in which the buffers overlap.| +|[`CSimpleStringT::Empty`](#empty)|Forces a string to have a length of zero.| +|[`CSimpleStringT::FreeExtra`](#freeextra)|Frees any extra memory previously allocated by the string object.| +|[`CSimpleStringT::GetAllocLength`](#getalloclength)|Retrieves the allocated length of a `CSimpleStringT` object.| +|[`CSimpleStringT::GetAt`](#getat)|Returns the character at a given position.| +|[`CSimpleStringT::GetBuffer`](#getbuffer)|Returns a pointer to the characters in a `CSimpleStringT`.| +|[`CSimpleStringT::GetBufferSetLength`](#getbuffersetlength)|Returns a pointer to the characters in a `CSimpleStringT`, truncating to the specified length.| +|[`CSimpleStringT::GetLength`](#getlength)|Returns the number of characters in a `CSimpleStringT` object.| +|[`CSimpleStringT::GetManager`](#getmanager)|Retrieves the memory manager of the `CSimpleStringT` object.| +|[`CSimpleStringT::GetString`](#getstring)|Retrieves the character string| +|[`CSimpleStringT::IsEmpty`](#isempty)|Tests whether a `CSimpleStringT` object contains no characters.| +|[`CSimpleStringT::LockBuffer`](#lockbuffer)|Disables reference counting and protects the string in the buffer.| +|[`CSimpleStringT::Preallocate`](#preallocate)|Allocates a specific amount of memory for the character buffer.| +|[`CSimpleStringT::ReleaseBuffer`](#releasebuffer)|Releases control of the buffer returned by `GetBuffer`.| +|[`CSimpleStringT::ReleaseBufferSetLength`](#releasebuffersetlength)|Releases control of the buffer returned by `GetBuffer`.| +|[`CSimpleStringT::SetAt`](#setat)|Sets a character at a given position.| +|[`CSimpleStringT::SetManager`](#setmanager)|Sets the memory manager of a `CSimpleStringT` object.| +|[`CSimpleStringT::SetString`](#setstring)|Sets the string of a `CSimpleStringT` object.| +|[`CSimpleStringT::StringLength`](#stringlength)|Returns the number of characters in the specified string.| +|[`CSimpleStringT::Truncate`](#truncate)|Truncates the string to a specified length.| +|[`CSimpleStringT::UnlockBuffer`](#unlockbuffer)|Enables reference counting and releases the string in the buffer.| ### Public Operators |Name|Description| |----------|-----------------| -|[CSimpleStringT::operator PCXSTR](#operator_pcxstr)|Directly accesses characters stored in a `CSimpleStringT` object as a C-style string.| -|[CSimpleStringT::operator\[\]](#operator_at)|Returns the character at a given position — operator substitution for `GetAt`.| -|[CSimpleStringT::operator +=](#operator_add_eq)|Concatenates a new string to the end of an existing string.| -|[CSimpleStringT::operator =](#operator_eq)|Assigns a new value to a `CSimpleStringT` object.| +|[`CSimpleStringT::operator PCXSTR`](#operator_pcxstr)|Directly accesses characters stored in a `CSimpleStringT` object as a C-style string.| +|[`CSimpleStringT::operator[]`](#operator_at)|Returns the character at a given position — operator substitution for `GetAt`.| +|[`CSimpleStringT::operator +=`](#operator_add_eq)|Concatenates a new string to the end of an existing string.| +|[`CSimpleStringT::operator =`](#operator_eq)|Assigns a new value to a `CSimpleStringT` object.| ### Remarks -`CSimpleStringT` is the base class for the various string classes supported by Visual C++. It provides minimal support for memory management of the string object and basic buffer manipulation. For more advanced string objects, see [CStringT Class](../../atl-mfc-shared/reference/cstringt-class.md). +`CSimpleStringT` is the base class for the various string classes supported by Visual C++. It provides minimal support for memory management of the string object and basic buffer manipulation. For more advanced string objects, see [`CStringT Class`](../../atl-mfc-shared/reference/cstringt-class.md). ### Requirements -**Header:** atlsimpstr.h +**Header:** `atlsimpstr.h` -## CSimpleStringT::Append +## `CSimpleStringT::Append` Appends a `CSimpleStringT` object to an existing `CSimpleStringT` object. @@ -104,13 +103,13 @@ void Append(PCXSTR pszSrc); #### Parameters -*strSrc*
+*`strSrc`*
The `CSimpleStringT` object to be appended. -*pszSrc*
+*`pszSrc`*
A pointer to a string containing the characters to be appended. -*nLength*
+*`nLength`*
The number of characters to append. ### Remarks @@ -122,6 +121,8 @@ Call this method to append an existing `CSimpleStringT` object to another `CSimp The following example demonstrates the use of `CSimpleStringT::Append`. ```cpp +CAtlString basestr; +IAtlStringMgr* pMgr = basestr.GetManager(); CSimpleString str1(pMgr), str2(pMgr); str1.SetString(_T("Soccer is")); str2.SetString(_T(" an elegant game")); @@ -129,7 +130,7 @@ str1.Append(str2); ASSERT(_tcscmp(str1, _T("Soccer is an elegant game")) == 0); ``` -## CSimpleStringT::AppendChar +## `CSimpleStringT::AppendChar` Appends a character to an existing `CSimpleStringT` object. @@ -141,60 +142,77 @@ void AppendChar(XCHAR ch); #### Parameters -*ch*
+*`ch`*
The character to be appended ### Remarks Call this function to append the specified character to the end of an existing `CSimpleStringT` object. -## CSimpleStringT::CopyChars +## `CSimpleStringT::CopyChars` Copies a character or characters to a `CSimpleStringT` object. ### Syntax -``` +```cpp static void CopyChars( XCHAR* pchDest, const XCHAR* pchSrc, int nChars) throw(); +static void CopyChars( + XCHAR* pchDest, + size_t nDestLen, + const XCHAR* pchSrc, + int nChars) throw(); ``` #### Parameters -*pchDest*
+*`pchDest`*
A pointer to a character string. -*pchSrc*
+*`nDestLen`*
+Buffer size of *`pchDest`* + +*`pchSrc`*
A pointer to a string containing the characters to be copied. -*nChars*
-The number of *pchSrc* characters to be copied. +*`nChars`*
+The number of *`pchSrc`* characters to be copied. ### Remarks -Call this method to copy characters from *pchSrc* to the *pchDest* string. +Call this method to copy characters from *`pchSrc`* to the *`pchDest`* string. ### Example The following example demonstrates the use of `CSimpleStringT::CopyChars`. ```cpp +CAtlString basestr; +IAtlStringMgr* pMgr = basestr.GetManager(); CSimpleString str(_T("xxxxxxxxxxxxxxxxxxx"), 20, pMgr); -TCHAR* pszSrc = _T("Hello world!"); +const TCHAR* pszSrc = _T("Hello world!"); _tprintf_s(_T("%s\n"), str); -str.CopyChars(str.GetBuffer(), pszSrc, 12); +str.CopyChars(str.GetBuffer(), 20, pszSrc, 12); _tprintf_s(_T("%s\n"), str); ``` -## CSimpleStringT::CopyCharsOverlapped +The output from this example is as follows: + +```output +xxxxxxxxxxxxxxxxxxx +Hello world!xxxxxxx +``` + +## `CSimpleStringT::CopyCharsOverlapped` Copies a character or characters to a `CSimpleStringT` object. ### Syntax -``` +```cpp static void CopyCharsOverlapped( XCHAR* pchDest, const XCHAR* pchSrc, @@ -203,30 +221,30 @@ static void CopyCharsOverlapped( #### Parameters -*pchDest*
+*`pchDest`*
A pointer to a character string. -*pchSrc*
+*`pchSrc`*
A pointer to a string containing the characters to be copied. -*nChars*
-The number of *pchSrc* characters to be copied. +*`nChars`*
+The number of *`pchSrc`* characters to be copied. ### Remarks -Call this method to copy characters from *pchSrc* to the *pchDest* string. Unlike `CopyChars`, `CopyCharsOverlapped` provides a safe method for copying from character buffers that might be overlapped. +Call this method to copy characters from *`pchSrc`* to the *`pchDest`* string. Unlike `CopyChars`, `CopyCharsOverlapped` provides a safe method for copying from character buffers that might be overlapped. ### Example -See the example for [CSimpleStringT::CopyChars](#copychars), or the source code for `CSimpleStringT::SetString` (located in atlsimpstr.h). +See the example for [`CSimpleStringT::CopyChars`](#copychars), or the source code for `CSimpleStringT::SetString` (located in `atlsimpstr.h`). -## CSimpleStringT::CSimpleStringT +## `CSimpleStringT::CSimpleStringT` Constructs a `CSimpleStringT` object. ### Syntax -``` +```cpp CSimpleStringT(const XCHAR* pchSrc, int nLength, IAtlStringMgr* pStringMgr); CSimpleStringT(PCXSTR pszSrc, IAtlStringMgr* pStringMgr); CSimpleStringT(const CSimpleStringT& strSrc); @@ -235,20 +253,20 @@ explicit CSimpleStringT(IAtlStringMgr* pStringMgr) throw(); #### Parameters -*strSrc*
+*`strSrc`*
An existing `CSimpleStringT` object to be copied into this `CSimpleStringT` object. -*pchSrc*
-A pointer to an array of characters of length *nLength*, not null terminated. +*`pchSrc`*
+A pointer to an array of characters of length *`nLength`*, not null terminated. -*pszSrc*
+*`pszSrc`*
A null-terminated string to be copied into this `CSimpleStringT` object. -*nLength*
+*`nLength`*
A count of the number of characters in `pch`. -*pStringMgr*
-A pointer to the memory manager of the `CSimpleStringT` object. For more information about `IAtlStringMgr` and memory management for `CSimpleStringT`, see [Memory Management and CStringT](../memory-management-with-cstringt.md). +*`pStringMgr`*
+A pointer to the memory manager of the `CSimpleStringT` object. For more information about `IAtlStringMgr` and memory management for `CSimpleStringT`, see [Memory Management and `CStringT`](../memory-management-with-cstringt.md). ### Remarks @@ -259,6 +277,9 @@ Construct a new `CSimpleStringT` object. Because the constructors copy the input The following example demonstrates the use of `CSimpleStringT::CSimpleStringT` by using the ATL **`typedef`** `CSimpleString`. `CSimpleString` is a commonly used specialization of the class template `CSimpleStringT`. ```cpp +CAtlString basestr; +IAtlStringMgr* pMgr = basestr.GetManager(); + CSimpleString s1(pMgr); // Empty string CSimpleString s2(_T("cat"), pMgr); @@ -273,7 +294,7 @@ CSimpleString s5(_T("xxxxxx"), 6, pMgr); // s5 = "xxxxxx" ``` -## CSimpleStringT::Empty +## `CSimpleStringT::Empty` Makes this `CSimpleStringT` object an empty string and frees memory as appropriate. @@ -285,18 +306,21 @@ void Empty() throw(); ### Remarks -For more information, see [Strings: CString Exception Cleanup](../cstring-exception-cleanup.md). +For more information, see [Strings: `CString` Exception Cleanup](../cstring-exception-cleanup.md). ### Example The following example demonstrates the use of `CSimpleStringT::Empty`. ```cpp +CAtlString basestr; +IAtlStringMgr* pMgr = basestr.GetManager(); + CSimpleString s(pMgr); ASSERT(s.IsEmpty()); ``` -## CSimpleStringT::FreeExtra +## `CSimpleStringT::FreeExtra` Frees any extra memory previously allocated by the string but no longer needed. @@ -308,7 +332,7 @@ void FreeExtra(); ### Remarks -This should reduce the memory overhead consumed by the string object. The method reallocates the buffer to the exact length returned by [GetLength](#getlength). +This should reduce the memory overhead consumed by the string object. The method reallocates the buffer to the exact length returned by [`GetLength`](#getlength). ### Example @@ -337,8 +361,6 @@ _tprintf_s(_T("Alloc length is %d, String length is %d\n"), str.GetAllocLength(), str.GetLength()); ``` -### Remarks - The output from this example is as follows: ```Output @@ -347,13 +369,13 @@ Alloc length is 1031, String length is 15 Alloc length is 15, String length is 15 ``` -## CSimpleStringT::GetAllocLength +## `CSimpleStringT::GetAllocLength` Retrieves the allocated length of a `CSimpleStringT` object. ### Syntax -``` +```cpp int GetAllocLength() const throw(); ``` @@ -363,22 +385,22 @@ The number of characters allocated for this object. ### Remarks -Call this method to determine the number of characters allocated for this `CSimpleStringT` object. See [FreeExtra](#freeextra) for an example of calling this function. +Call this method to determine the number of characters allocated for this `CSimpleStringT` object. See [`FreeExtra`](#freeextra) for an example of calling this function. -## CSimpleStringT::GetAt +## `CSimpleStringT::GetAt` Returns one character from a `CSimpleStringT` object. ### Syntax -``` +```cpp XCHAR GetAt(int iChar) const; ``` #### Parameters -*iChar*
-Zero-based index of the character in the `CSimpleStringT` object. The *iChar* parameter must be greater than or equal to 0 and less than the value returned by [GetLength](#getlength). Otherwise, `GetAt` will generate an exception. +*`iChar`*
+Zero-based index of the character in the `CSimpleStringT` object. The *`iChar`* parameter must be greater than or equal to 0 and less than the value returned by [`GetLength`](#getlength). Otherwise, `GetAt` will generate an exception. ### Return Value @@ -386,7 +408,7 @@ An `XCHAR` that contains the character at the specified position in the string. ### Remarks -Call this method to return the one character specified by *iChar*. The overloaded subscript (**[]**) operator is a convenient alias for `GetAt`. The null terminator is addressable without generating an exception by using `GetAt`. However, it is not counted by `GetLength`, and the value returned is 0. +Call this method to return the one character specified by *`iChar`*. The overloaded subscript (**`[]`**) operator is a convenient alias for `GetAt`. The null terminator is addressable without generating an exception by using `GetAt`. However, it is not counted by `GetLength`, and the value returned is 0. ### Example @@ -397,23 +419,23 @@ CSimpleString s(_T("abcdef"), pMgr); ASSERT(s.GetAt(2) == _T('c')); ``` -## CSimpleStringT::GetBuffer +## `CSimpleStringT::GetBuffer` Returns a pointer to the internal character buffer for the `CSimpleStringT` object. ### Syntax -``` +```cpp PXSTR GetBuffer(int nMinBufferLength); PXSTR GetBuffer(); ``` #### Parameters -*nMinBufferLength*
+*`nMinBufferLength`*
The minimum number of characters that the character buffer can hold. This value does not include space for a null terminator. -If *nMinBufferLength* is larger than the length of the current buffer, `GetBuffer` destroys the current buffer, replaces it with a buffer of the requested size, and resets the object reference count to zero. If you have previously called [LockBuffer](#lockbuffer) on this buffer, you lose the buffer lock. +If *`nMinBufferLength`* is larger than the length of the current buffer, `GetBuffer` destroys the current buffer, replaces it with a buffer of the requested size, and resets the object reference count to zero. If you have previously called [`LockBuffer`](#lockbuffer) on this buffer, you lose the buffer lock. ### Return Value @@ -423,7 +445,7 @@ An `PXSTR` pointer to the object's (null-terminated) character buffer. Call this method to return the buffer contents of the `CSimpleStringT` object. The returned `PXSTR` is not a constant and therefore allows direct modification of `CSimpleStringT` contents. -If you use the pointer returned by `GetBuffer` to change the string contents, you must call [ReleaseBuffer](#releasebuffer) before you use any other `CSimpleStringT` member methods. +If you use the pointer returned by `GetBuffer` to change the string contents, you must call [`ReleaseBuffer`](#releasebuffer) to update the internal state of `CSimpleStringT` before you use any other `CSimpleStringT` methods. The address returned by `GetBuffer` may not be valid after the call to `ReleaseBuffer` because additional `CSimpleStringT` operations can cause the `CSimpleStringT` buffer to be reallocated. The buffer is not reallocated if you do not change the length of the `CSimpleStringT`. @@ -431,7 +453,7 @@ The buffer memory is automatically freed when the `CSimpleStringT` object is des If you keep track of the string length yourself, you should not append the terminating null character. However, you must specify the final string length when you release the buffer with `ReleaseBuffer`. If you do append a terminating null character, you should pass -1 (the default) for the length. `ReleaseBuffer` then determines the buffer length. -If there is insufficient memory to satisfy the `GetBuffer` request, this method throws a CMemoryException*. +If there is insufficient memory to satisfy the `GetBuffer` request, this method throws a `CMemoryException*`. ### Example @@ -446,19 +468,19 @@ ASSERT(_tcscmp(s, _T("Hello")) == 0); s.ReleaseBuffer(); ``` -## CSimpleStringT::GetBufferSetLength +## `CSimpleStringT::GetBufferSetLength` -Returns a pointer to the internal character buffer for the `CSimpleStringT` object, truncating or growing its length if necessary to exactly match the length specified in *nLength*. +Returns a pointer to the internal character buffer for the `CSimpleStringT` object, truncating or growing its length if necessary to exactly match the length specified in *`nLength`*. ### Syntax -``` +```cpp PXSTR GetBufferSetLength(int nLength); ``` #### Parameters -*nLength*
+*`nLength`*
The exact size of the `CSimpleStringT` character buffer in characters. ### Return Value @@ -469,7 +491,7 @@ A `PXSTR` pointer to the object's (null-terminated) character buffer. Call this method to retrieve a specified length of the internal buffer of the `CSimpleStringT` object. The returned `PXSTR` pointer is not **`const`** and thus allows direct modification of `CSimpleStringT` contents. -If you use the pointer returned by [GetBufferSetLength](#getbuffersetlength) to change the string contents, call `ReleaseBuffer` to update the internal state of `CsimpleStringT` before you use any other `CSimpleStringT` methods. +If you use the pointer returned by [`GetBufferSetLength`](#getbuffersetlength) to change the string contents, call `ReleaseBuffer` to update the internal state of `CSimpleStringT` before you use any other `CSimpleStringT` methods. The address returned by `GetBufferSetLength` may not be valid after the call to `ReleaseBuffer` because additional `CSimpleStringT` operations can cause the `CSimpleStringT` buffer to be reallocated. The buffer is not reassigned if you do not change the length of the `CSimpleStringT`. @@ -480,9 +502,7 @@ If you keep track of the string length yourself, do not append the terminating n For more information about reference counting, see the following articles: - [Managing Object Lifetimes through Reference Counting](/windows/win32/com/managing-object-lifetimes-through-reference-counting) in the Windows SDK. - - [Implementing Reference Counting](/windows/win32/com/implementing-reference-counting) in the Windows SDK. - - [Rules for Managing Reference Counts](/windows/win32/com/rules-for-managing-reference-counts) in the Windows SDK. ### Example @@ -495,21 +515,19 @@ LPTSTR pstr = str.GetBufferSetLength(3); pstr[0] = _T('C'); pstr[1] = _T('u'); pstr[2] = _T('p'); - -// No need for trailing zero or call to ReleaseBuffer() -// because GetBufferSetLength() set it for us. +str.ReleaseBuffer(); str += _T(" soccer is best!"); ASSERT(_tcscmp(str, _T("Cup soccer is best!")) == 0); ``` -## CSimpleStringT::GetLength +## `CSimpleStringT::GetLength` Returns the number of characters in the `CSimpleStringT` object. ### Syntax -``` +```cpp int GetLength() const throw(); ``` @@ -521,15 +539,15 @@ A count of the characters in the string. Call this method to return the number of characters in the object. The count does not include a null terminator. -For multibyte character sets (MBCS), `GetLength` counts each 8-bit character; that is, a lead and trail byte in one multibyte character are counted as two bytes. See [FreeExtra](#freeextra) for an example of calling this function. +For multibyte character sets (MBCS), `GetLength` counts each 8-bit character; that is, a lead and trail byte in one multibyte character are counted as two bytes. See [`FreeExtra`](#freeextra) for an example of calling this function. -## CSimpleStringT::GetManager +## `CSimpleStringT::GetManager` Retrieves the memory manager of the `CSimpleStringT` object. ### Syntax -``` +```cpp IAtlStringMgr* GetManager() const throw(); ``` @@ -539,15 +557,15 @@ A pointer to the memory manager for the `CSimpleStringT` object. ### Remarks -Call this method to retrieve the memory manager used by the `CSimpleStringT` object. For more information on memory managers and string objects, see [Memory Management and CStringT](../memory-management-with-cstringt.md). +Call this method to retrieve the memory manager used by the `CSimpleStringT` object. For more information on memory managers and string objects, see [Memory Management and `CStringT`](../memory-management-with-cstringt.md). -## CSimpleStringT::GetString +## `CSimpleStringT::GetString` Retrieves the character string. ### Syntax -``` +```cpp PCXSTR GetString() const throw(); ``` @@ -567,24 +585,32 @@ Call this method to retrieve the character string associated with the `CSimpleSt The following example demonstrates the use of `CSimpleStringT::GetString`. ```cpp +CAtlString basestr; +IAtlStringMgr* pMgr = basestr.GetManager(); CSimpleString str(pMgr); str += _T("Cup soccer is best!"); _tprintf_s(_T("%s"), str.GetString()); ``` -## CSimpleStringT::IsEmpty +The output from this example is as follows: + +```output +Cup soccer is best! +``` + +## `CSimpleStringT::IsEmpty` Tests a `CSimpleStringT` object for the empty condition. ### Syntax -``` +```cpp bool IsEmpty() const throw(); ``` ### Return Value -Returns TRUE if the `CSimpleStringT` object has 0 length; otherwise FALSE. +Returns `TRUE` if the `CSimpleStringT` object has 0 length; otherwise `FALSE`. ### Remarks @@ -599,13 +625,13 @@ CSimpleString s(pMgr); ASSERT(s.IsEmpty()); ``` -## CSimpleStringT::LockBuffer +## `CSimpleStringT::LockBuffer` Disables reference counting and protects the string in the buffer. ### Syntax -``` +```cpp PXSTR LockBuffer(); ``` @@ -623,10 +649,10 @@ Call this method to lock the buffer of the `CSimpleStringT` object. By calling ` By locking the string in the buffer, you ensure that the string's exclusive hold on the buffer will remain intact. -After you have finished with `LockBuffer`, call [UnlockBuffer](#unlockbuffer) to reset the reference count to 1. +After you have finished with `LockBuffer`, call [`UnlockBuffer`](#unlockbuffer) to reset the reference count to 1. > [!NOTE] -> If you call [GetBuffer](#getbuffer) on a locked buffer and you set the `GetBuffer` parameter `nMinBufferLength` to greater than the length of the current buffer, you will lose the buffer lock. Such a call to `GetBuffer` destroys the current buffer, replaces it with a buffer of the requested size, and resets the reference count to zero. +> If you call [`GetBuffer`](#getbuffer) on a locked buffer and you set the `GetBuffer` parameter `nMinBufferLength` to greater than the length of the current buffer, you will lose the buffer lock. Such a call to `GetBuffer` destroys the current buffer, replaces it with a buffer of the requested size, and resets the reference count to zero. For more information about reference counting, see the following articles: @@ -641,6 +667,9 @@ For more information about reference counting, see the following articles: The following example demonstrates the use of `CSimpleStringT::LockBuffer`. ```cpp +CAtlString basestr; +IAtlStringMgr* pMgr = basestr.GetManager(); + CSimpleString str(_T("Hello"), pMgr); TCHAR ch; @@ -650,27 +679,33 @@ _tprintf_s(_T("%c"), ch); str.UnlockBuffer(); ``` -## CSimpleStringT::operator\[\] +The output from this example is as follows: + +```output +l +``` + +## `CSimpleStringT::operator[]` Call this function to access a single character of the character array. ### Syntax -``` +```cpp XCHAR operator[](int iChar) const; ``` #### Parameters -*iChar*
+*`iChar`*
Zero-based index of a character in the string. ### Remarks -The overloaded subscript (**[]**) operator returns a single character specified by the zero-based index in *iChar*. This operator is a convenient substitute for the [GetAt](#getat) member function. +The overloaded subscript (**`[]`**) operator returns a single character specified by the zero-based index in *`iChar`*. This operator is a convenient substitute for the [`GetAt`](#getat) member function. > [!NOTE] -> You can use the subscript (**[]**) operator to get the value of a character in a `CSimpleStringT`, but you cannot use it to change the value of a character in a `CSimpleStringT`. +> You can use the subscript (**`[]`**) operator to get the value of a character in a `CSimpleStringT`, but you cannot use it to change the value of a character in a `CSimpleStringT`. ### Example @@ -681,35 +716,13 @@ CSimpleString s(_T("abc"), pMgr); ASSERT(s[1] == _T('b')); ``` -## CSimpleStringT::operator \[\] - -Call this function to access a single character of the character array. - -### Syntax - -``` -XCHAR operator[](int iChar) const; -``` - -### Parameters - -*iChar*
-Zero-based index of a character in the string. - -### Remarks - -The overloaded subscript (**[]**) operator returns a single character specified by the zero-based index in *iChar*. This operator is a convenient substitute for the [GetAt](#getat) member function. - -> [!NOTE] -> You can use the subscript (**[]**) operator to get the value of a character in a `CSimpleStringT`, but you cannot use it to change the value of a character in a `CSimpleStringT`. - -## CSimpleStringT::operator += +## `CSimpleStringT::operator +=` Joins a new string or character to the end of an existing string. ### Syntax -``` +```cpp CSimpleStringT& operator +=(PCXSTR pszSrc); CSimpleStringT& operator +=(const CSimpleStringT& strSrc); template @@ -721,13 +734,13 @@ CSimpleStringT& operator +=(wchar_t ch); #### Parameters -*pszSrc*
+*`pszSrc`*
A pointer to a null-terminated string. -*strSrc*
+*`strSrc`*
A pointer to an existing `CSimpleStringT` object. -*ch*
+*`ch`*
The character to be appended. ### Remarks @@ -743,23 +756,23 @@ CSimpleString str(_T("abc"), pMgr); ASSERT(_tcscmp((str += _T("def")), _T("abcdef")) == 0); ``` -## CSimpleStringT::operator = +## `CSimpleStringT::operator =` Assigns a new value to a `CSimpleStringT` object. ### Syntax -``` +```cpp CSimpleStringT& operator =(PCXSTR pszSrc); CSimpleStringT& operator =(const CSimpleStringT& strSrc); ``` #### Parameters -*pszSrc*
+*`pszSrc`*
A pointer to a null-terminated string. -*strSrc*
+*`strSrc`*
A pointer to an existing `CSimpleStringT` object. ### Remarks @@ -790,13 +803,13 @@ s1 = _T("x"); ASSERT(_tcscmp(s1, _T("x")) == 0); ``` -## CSimpleStringT::operator PCXSTR +## `CSimpleStringT::operator PCXSTR` Directly accesses characters stored in a `CSimpleStringT` object as a C-style string. ### Syntax -``` +```cpp operator PCXSTR() const throw(); ``` @@ -842,17 +855,17 @@ wcout << strSports; wcout << (PCWSTR)strSports; ``` -## CSimpleStringT::PCXSTR +## `CSimpleStringT::PCXSTR` A pointer to a constant string. ### Syntax -``` +```cpp typedef ChTraitsBase< BaseType >::PCXSTR PCXSTR; ``` -## CSimpleStringT::Preallocate +## `CSimpleStringT::Preallocate` Allocates a specific amount of bytes for the `CSimpleStringT` object. @@ -864,39 +877,49 @@ void Preallocate( int nLength); #### Parameters -*nLength*
+*`nLength`*
The exact size of the `CSimpleStringT` character buffer in characters. ### Remarks Call this method to allocate a specific buffer size for the `CSimpleStringT` object. -`CSimpleStringT` generates a STATUS_NO_MEMORY exception if it is unable to allocate space for the character buffer. By default, memory allocation is performed by WIN32 API functions `HeapAlloc` or `HeapReAlloc`. +`CSimpleStringT` generates a `STATUS_NO_MEMORY` exception if it is unable to allocate space for the character buffer. By default, memory allocation is performed by WIN32 API functions `HeapAlloc` or `HeapReAlloc`. ### Example The following example demonstrates the use of `CSimpleStringT::Preallocate`. ```cpp +CAtlString basestr; +IAtlStringMgr* pMgr = basestr.GetManager(); + CSimpleString str(pMgr); _tprintf_s(_T("Allocated length: %d\n"), str.GetAllocLength()); str.Preallocate(100); _tprintf_s(_T("Allocated length: %d\n"), str.GetAllocLength()); ``` -## CSimpleStringT::PXSTR +The output from this example is as follows: + +```output +Allocated length: 0 +Allocated length: 103 +``` + +## `CSimpleStringT::PXSTR` A pointer to a string. ### Syntax -``` +```cpp typedef ChTraitsBase< BaseType >::PXSTR PXSTR; ``` -## CSimpleStringT::ReleaseBuffer +## `CSimpleStringT::ReleaseBuffer` -Releases control of the buffer allocated by [GetBuffer](#getbuffer). +Releases control of the buffer allocated by [`GetBuffer`](#getbuffer). ### Syntax @@ -906,12 +929,12 @@ void ReleaseBuffer(int nNewLength = -1); #### Parameters -*nNewLength*
+*`nNewLength`*
The new length of the string in characters, not counting a null terminator. If the string is null terminated, the -1 default value sets the `CSimpleStringT` size to the current length of the string. ### Remarks -Call this method to reallocate or free up the buffer of the string object. If you know that the string in the buffer is null terminated, you can omit the *nNewLength* argument. If your string is not null terminated, use *nNewLength* to specify its length. The address returned by [GetBuffer](#getbuffer) is invalid after the call to `ReleaseBuffer` or any other `CSimpleStringT` operation. +Call this method to reallocate or free up the buffer of the string object. If you know that the string in the buffer is null terminated, you can omit the *`nNewLength`* argument. If your string is not null terminated, use *`nNewLength`* to specify its length. The address returned by [`GetBuffer`](#getbuffer) is invalid after the call to `ReleaseBuffer` or any other `CSimpleStringT` operation. ### Example @@ -935,9 +958,9 @@ ASSERT(s.GetLength() == 3); // Length still 3 ``` -## CSimpleStringT::ReleaseBufferSetLength +## `CSimpleStringT::ReleaseBufferSetLength` -Releases control of the buffer allocated by [GetBuffer](#getbuffer). +Releases control of the buffer allocated by [`GetBuffer`](#getbuffer). ### Syntax @@ -947,14 +970,14 @@ void ReleaseBufferSetLength(int nNewLength); #### Parameters -*nNewLength*
+*`nNewLength`*
The length of the string being released ### Remarks -This function is functionally similar to [ReleaseBuffer](#releasebuffer) except that a valid length for the string object must be passed. +This function is functionally similar to [`ReleaseBuffer`](#releasebuffer) except that a valid length for the string object must be passed. -## CSimpleStringT::SetAt +## `CSimpleStringT::SetAt` Sets a single character from a `CSimpleStringT` object. @@ -966,15 +989,15 @@ void SetAt(int iChar, XCHAR ch); #### Parameters -*iChar*
-Zero-based index of the character in the `CSimpleStringT` object. The *iChar* parameter must be greater than or equal to 0 and less than the value returned by [GetLength](#getlength). +*`iChar`*
+Zero-based index of the character in the `CSimpleStringT` object. The *`iChar`* parameter must be greater than or equal to 0 and less than the value returned by [`GetLength`](#getlength). -*ch*
+*`ch`*
The new character. ### Remarks -Call this method to overwrite the character located at *iChar*. This method will not enlarge the string if *iChar* exceeds the bounds of the existing string. +Call this method to overwrite the character located at *`iChar`*. This method will not enlarge the string if *`iChar`* exceeds the bounds of the existing string. ### Example @@ -986,7 +1009,7 @@ s.SetAt(1, _T('a')); ASSERT(_tcscmp(s, _T("aacdef")) == 0); ``` -## CSimpleStringT::SetManager +## `CSimpleStringT::SetManager` Specifies the memory manager of the `CSimpleStringT` object. @@ -998,12 +1021,12 @@ void SetManager(IAtlStringMgr* pStringMgr); #### Parameters -*pStringMgr*
+*`pStringMgr`*
A pointer to the new memory manager. ### Remarks -Call this method to specify a new memory manager used by the `CSimpleStringT` object. For more information on memory managers and string objects, see [Memory Management and CStringT](../memory-management-with-cstringt.md). +Call this method to specify a new memory manager used by the `CSimpleStringT` object. For more information on memory managers and string objects, see [Memory Management and `CStringT`](../memory-management-with-cstringt.md). ### Example @@ -1014,7 +1037,7 @@ CSimpleString s(pMgr); s.SetManager(pCustomMgr); ``` -## CSimpleStringT::SetString +## `CSimpleStringT::SetString` Sets the string of a `CSimpleStringT` object. @@ -1027,23 +1050,23 @@ void SetString(PCXSTR pszSrc); #### Parameters -*pszSrc*
+*`pszSrc`*
A pointer to a null-terminated string. -*nLength*
-A count of the number of characters in *pszSrc*. +*`nLength`*
+A count of the number of characters in *`pszSrc`*. ### Remarks Copy a string into the `CSimpleStringT` object. `SetString` overwrites the older string data in the buffer. -Both versions of `SetString` check whether *pszSrc* is a null pointer, and if it is, throw an E_INVALIDARG error. +Both versions of `SetString` check whether *`pszSrc`* is a null pointer, and if it is, throw an `E_INVALIDARG` error. -The one-parameter version of `SetString` expects *pszSrc* to point to a null-terminated string. +The one-parameter version of `SetString` expects *`pszSrc`* to point to a null-terminated string. -The two-parameter version of `SetString` also expects *pszSrc* to be a null-terminated string. It uses *nLength* as the string length unless it encounters a null terminator first. +The two-parameter version of `SetString` also expects *`pszSrc`* to be a null-terminated string. It uses *`nLength`* as the string length unless it encounters a null terminator first. -The two-parameter version of `SetString` also checks whether *pszSrc* points to a location in the current buffer in `CSimpleStringT`. In this special case, `SetString` uses a memory copy function that does not overwrite the string data as it copies the string data back to its buffer. +The two-parameter version of `SetString` also checks whether *`pszSrc`* points to a location in the current buffer in `CSimpleStringT`. In this special case, `SetString` uses a memory copy function that does not overwrite the string data as it copies the string data back to its buffer. ### Example @@ -1056,28 +1079,28 @@ s.SetString(_T("Soccer"), 6); ASSERT(_tcscmp(s, _T("Soccer")) == 0); ``` -## CSimpleStringT::StringLength +## `CSimpleStringT::StringLength` Returns the number of characters in the specified string. ### Syntax -``` +```cpp ATL_NOINLINE static int StringLength(PCXSTR psz) throw(); ``` #### Parameters -*psz*
+*`psz`*
A pointer to a null-terminated string. ### Return Value -The number of characters in *psz*; not counting a null terminator. +The number of characters in *`psz`*; not counting a null terminator. ### Remarks -Call this method to retrieve the number of characters in the string pointed to by *psz*. +Call this method to retrieve the number of characters in the string pointed to by *`psz`*. ### Example @@ -1087,7 +1110,7 @@ The following example demonstrates the use of `CSimpleStringT::StringLength`. ASSERT(CSimpleString::StringLength(_T("soccer")) == 6); ``` -## CSimpleStringT::Truncate +## `CSimpleStringT::Truncate` Truncates the string to the new length. @@ -1099,7 +1122,7 @@ void Truncate(int nNewLength); #### Parameters -*nNewLength*
+*`nNewLength`*
The new length of the string. ### Remarks @@ -1107,22 +1130,33 @@ The new length of the string. Call this method to truncate the contents of the string to the new length. > [!NOTE] -> This does not affect the allocated length of the buffer. To decrease or increase the current buffer, see [FreeExtra](#freeextra) and [Preallocate](#preallocate). +> This does not affect the allocated length of the buffer. To decrease or increase the current buffer, see [`FreeExtra`](#freeextra) and [`Preallocate`](#preallocate). ### Example The following example demonstrates the use of `CSimpleStringT::Truncate`. ```cpp +CAtlString basestr; +IAtlStringMgr* pMgr = basestr.GetManager(); CSimpleString str(_T("abcdefghi"), pMgr); -_tprintf_s(_T("Allocated length: %d\n"), str.GetLength()); -_tprintf_s(_T("Contents: %s\n"), str); +_tprintf_s(_T("String length: %d / Allocated length: %d\n"), str.GetLength(), str.GetAllocLength()); +_tprintf_s(_T("Contents: %s\n"), (LPCTSTR)str); str.Truncate(4); -_tprintf_s(_T("Allocated length: %d\n"), str.GetLength()); -_tprintf_s(_T("Contents: %s\n"), str); +_tprintf_s(_T("String length: %d / Allocated length: %d\n"), str.GetLength(), str.GetAllocLength()); +_tprintf_s(_T("Contents: %s\n"), (LPCTSTR)str); ``` -## CSimpleStringT::UnlockBuffer +The output from this example is: + +```Output +String length: 9 / Allocated length: 15 +Contents: abcdefghi +String length: 4 / Allocated length: 15 +Contents: abcd +``` + +## `CSimpleStringT::UnlockBuffer` Unlocks the buffer of the `CSimpleStringT` object. @@ -1136,15 +1170,15 @@ void UnlockBuffer() throw(); Call this method to reset the reference count of the string to 1. -The `CSimpleStringT` destructor automatically calls `UnlockBuffer` to ensure that the buffer is not locked when the destructor is called. For an example of this method, see [LockBuffer](#lockbuffer). +The `CSimpleStringT` destructor automatically calls `UnlockBuffer` to ensure that the buffer is not locked when the destructor is called. For an example of this method, see [`LockBuffer`](#lockbuffer). -## CSimpleStringT::~CSimpleStringT +## `CSimpleStringT::~CSimpleStringT` Destroys a `CSimpleStringT` object. ### Syntax -``` +```cpp ~CSimpleStringT() throw(); ``` @@ -1154,5 +1188,5 @@ Call this method to destroy the `CSimpleStringT` object. ## See also -[Hierarchy Chart](../../mfc/hierarchy-chart.md)
+[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ [ATL/MFC Shared Classes](../../atl-mfc-shared/atl-mfc-shared-classes.md) diff --git a/docs/atl-mfc-shared/reference/csize-class.md b/docs/atl-mfc-shared/reference/csize-class.md index e807aab432..f398b5055d 100644 --- a/docs/atl-mfc-shared/reference/csize-class.md +++ b/docs/atl-mfc-shared/reference/csize-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CSize Class" title: "CSize Class" -ms.date: "10/18/2018" +description: "Learn more about: CSize Class" +ms.date: 10/18/2018 f1_keywords: ["CSize", "ATLTYPES/ATL::CSize", "ATLTYPES/ATL::CSize::CSize"] helpviewer_keywords: ["SIZE", "dimensions, MFC", "dimensions", "CSize class"] -ms.assetid: fb2cf85a-0bc1-46f8-892b-309c108b52ae --- # CSize Class @@ -12,7 +11,7 @@ Similar to the Windows [SIZE](/windows/win32/api/windef/ns-windef-size) structur ## Syntax -``` +```cpp class CSize : public tagSIZE ``` @@ -58,7 +57,7 @@ The `cx` and `cy` members of `SIZE` (and `CSize`) are public. In addition, `CSiz Constructs a `CSize` object. -``` +```cpp CSize() throw(); CSize( int initCX, int initCY) throw(); CSize( SIZE initSize) throw(); @@ -95,13 +94,13 @@ If no arguments are given, `cx` and `cy` are initialized to zero. Checks for equality between two sizes. -``` +```cpp BOOL operator==(SIZE size) const throw(); ``` ### Remarks -Returns nonzero if the sizes are equal, otherwize 0. +Returns nonzero if the sizes are equal, otherwise 0. ### Example @@ -111,7 +110,7 @@ Returns nonzero if the sizes are equal, otherwize 0. Checks for inequality between two sizes. -``` +```cpp BOOL operator!=(SIZE size) const throw(); ``` @@ -151,7 +150,7 @@ void operator-=(SIZE size) throw(); These operators add this `CSize` value to the value of parameter. -``` +```cpp CSize operator+(SIZE size) const throw(); CPoint operator+(POINT point) const throw(); CRect operator+(const RECT* lpRect) const throw(); @@ -181,7 +180,7 @@ See the following descriptions of the individual operators: The first three of these operators subtract this `CSize` value to the value of parameter. -``` +```cpp CSize operator-(SIZE size) const throw(); CPoint operator-(POINT point) const throw(); CRect operator-(const RECT* lpRect) const throw(); diff --git a/docs/atl-mfc-shared/reference/cstrbuft-class.md b/docs/atl-mfc-shared/reference/cstrbuft-class.md index 4f6f092b91..4cc53bfee5 100644 --- a/docs/atl-mfc-shared/reference/cstrbuft-class.md +++ b/docs/atl-mfc-shared/reference/cstrbuft-class.md @@ -12,7 +12,7 @@ This class provides automatic resource cleanup for `GetBuffer` and `ReleaseBuffe ## Syntax -``` +```cpp template class CStrBufT ``` @@ -26,7 +26,7 @@ The character type of the `CStrBufT` class. Can be one of the following: - **`wchar_t`** (for Unicode character strings) -- TCHAR (for both ANSI and Unicode character strings) +- **`TCHAR`** (for both ANSI and Unicode character strings) ## Members @@ -34,8 +34,8 @@ The character type of the `CStrBufT` class. Can be one of the following: |Name|Description| |----------|-----------------| -|PCXSTR|A pointer to a constant string.| -|PXSTR|A pointer to a string.| +|`PCXSTR`|A pointer to a constant string.| +|`PXSTR`|A pointer to a string.| |`StringType`|The string type whose buffer is to be manipulated by specializations of this class template.| ### Public Constructors @@ -78,7 +78,7 @@ Primarily designed as a helper class, `CStrBufT` provides a convenient way for a Automatically determine the new length of the string at release. -``` +```cpp static const DWORD AUTO_LENGTH = 0x01; ``` @@ -90,7 +90,7 @@ Automatically determine the new length of the string at release. The string must Constructs a buffer object. -``` +```cpp CStrBufT(StringType& str, int nMinLength, DWORD dwFlags = AUTO_LENGTH) throw(...); explicit CStrBufT(StringType& str) throw(...); ``` @@ -120,7 +120,7 @@ Note that the copy constructor is **`private`**. Directly accesses characters stored in the associated string object as a C-style string. -``` +```cpp operator PCXSTR() const throw(); ``` @@ -136,7 +136,7 @@ Call this function to return a pointer to the character buffer of a string objec Directly accesses characters stored in the associated string object as a C-style string. -``` +```cpp operator PXSTR() throw(); ``` @@ -152,7 +152,7 @@ Call this function to return a pointer to the character buffer of a string objec A pointer to a constant string. -``` +```cpp typedef CSimpleStringT::PCXSTR PCXSTR; ``` @@ -160,7 +160,7 @@ typedef CSimpleStringT::PCXSTR PCXSTR; A pointer to a string. -``` +```cpp typedef CSimpleStringT::PXSTR PXSTR; ``` @@ -168,7 +168,7 @@ typedef CSimpleStringT::PXSTR PXSTR; Set the length of the string object at `GetBuffer` time. -``` +```cpp static const DWORD SET_LENGTH = 0x02; ``` @@ -202,7 +202,7 @@ Call this function to set the length of the string represented by the buffer obj The string type whose buffer is to be manipulated by specializations of this class template. -``` +```cpp typedef CSimpleStringT StringType; ``` diff --git a/docs/atl-mfc-shared/reference/cstringdata-class.md b/docs/atl-mfc-shared/reference/cstringdata-class.md index 03da39cca6..2755f5e8ab 100644 --- a/docs/atl-mfc-shared/reference/cstringdata-class.md +++ b/docs/atl-mfc-shared/reference/cstringdata-class.md @@ -12,7 +12,7 @@ This class represents the data of a string object. ## Syntax -``` +```cpp struct CStringData ``` @@ -105,7 +105,7 @@ Call this function to return the current character buffer of the associated stri Determines if the character buffer is locked. -``` +```cpp bool IsLocked() const throw(); ``` @@ -121,7 +121,7 @@ Call this function to determine if the character buffer of a string object is cu Determines if the character buffer is shared. -``` +```cpp bool IsShared() const throw(); ``` @@ -152,7 +152,7 @@ Call this function to lock the character buffer of the string data object. Locki Length of the allocated character buffer. -``` +```cpp int nAllocLength; ``` @@ -164,7 +164,7 @@ Stores the length of the allocated data buffer in `XCHAR`s (not including termin Current length of the string object. -``` +```cpp int nDataLength; ``` @@ -176,7 +176,7 @@ Stores the length of currently used data in `XCHAR`s (not including terminating Reference count of the string data object. -``` +```cpp long nRefs; ``` @@ -188,7 +188,7 @@ Stores the reference count of the string data object. This count indicates the n The memory manager of the associated string object. -``` +```cpp IAtlStringMgr* pStringMgr; ``` diff --git a/docs/atl-mfc-shared/reference/cstringt-class.md b/docs/atl-mfc-shared/reference/cstringt-class.md index be2952345b..a47c9ad9a6 100644 --- a/docs/atl-mfc-shared/reference/cstringt-class.md +++ b/docs/atl-mfc-shared/reference/cstringt-class.md @@ -112,7 +112,7 @@ Determines if the string class needs C Run-Time (CRT) Library support and where ## Remarks -**`CStringT`** inherits from [CSimpleStringT Class](../../atl-mfc-shared/reference/csimplestringt-class.md). Advanced features, such as character manipulation, ordering, and searching, are implemented by **`CStringT`**. +**`CStringT`** inherits from [`CSimpleStringT` Class](../../atl-mfc-shared/reference/csimplestringt-class.md). Advanced features, such as character manipulation, ordering, and searching, are implemented by **`CStringT`**. > [!NOTE] > **`CStringT`** objects are capable of throwing exceptions. This occurs when a **`CStringT`** object runs out of memory for any reason. @@ -159,15 +159,15 @@ The following string types are available in projects where `ATL_CSTRING_NO_CRT` - **`CStringT`** objects can grow because of concatenation operations. -- **`CStringT`** objects follow "value semantics." Think of a **`CStringT`** object as an actual string, not as a pointer to a string. +- **`CStringT`** objects follow "value semantics". Think of a **`CStringT`** object as an actual string, not as a pointer to a string. - You can freely substitute **`CStringT`** objects for `PCXSTR` function arguments. -- Custom memory management for string buffers. For more information, see [Memory Management and CStringT](../../atl-mfc-shared/memory-management-with-cstringt.md). +- Custom memory management for string buffers. For more information, see [Memory Management and `CStringT`](../../atl-mfc-shared/memory-management-with-cstringt.md). ## CStringT Predefined Types -Because **`CStringT`** uses a template argument to define the character type (either [wchar_t](../../c-runtime-library/standard-types.md) or [char](../../c-runtime-library/standard-types.md)) supported, method parameter types can be complicated at times. To simplify this issue, a set of predefined types is defined and used throughout the **`CStringT`** class. The following table lists the various types: +Because **`CStringT`** uses a template argument to define the character type (either [`wchar_t`](../../c-runtime-library/standard-types.md) or [`char`](../../c-runtime-library/standard-types.md)) supported, method parameter types can be complicated at times. To simplify this issue, a set of predefined types is defined and used throughout the **`CStringT`** class. The following table lists the various types: |Name|Description| |----------|-----------------| @@ -183,7 +183,7 @@ Because **`CStringT`** uses a template argument to define the character type (ei ## Inheritance Hierarchy -[CSimpleStringT](../../atl-mfc-shared/reference/csimplestringt-class.md) +[`CSimpleStringT`](../../atl-mfc-shared/reference/csimplestringt-class.md) **`CStringT`** @@ -191,8 +191,8 @@ Because **`CStringT`** uses a template argument to define the character type (ei |Header|Use for| |------------|-------------| -|cstringt.h|MFC-only string objects| -|atlstr.h|Non-MFC string objects| +|`cstringt.h`|MFC-only string objects| +|`atlstr.h`|Non-MFC string objects| ## `CStringT::AllocSysString` @@ -208,11 +208,11 @@ The newly allocated string. ### Remarks -In MFC programs, a [CMemoryException Class](../../mfc/reference/cmemoryexception-class.md) is thrown if insufficient memory exists. In ATL programs, a [CAtlException](../../atl/reference/catlexception-class.md) is thrown. This function is normally used to return strings for Automation. +In MFC programs, a [`CMemoryException` Class](../../mfc/reference/cmemoryexception-class.md) is thrown if insufficient memory exists. In ATL programs, a [`CAtlException`](../../atl/reference/catlexception-class.md) is thrown. This function is normally used to return strings for Automation. -Commonly, if this string is passed to a COM function as an `[in]` parameter, then this requires the caller to free the string. This can be done by using [SysFreeString](/windows/win32/api/oleauto/nf-oleauto-sysfreestring), as described in the Windows SDK. For more information, see [Allocating and Releasing Memory for a BSTR](../../atl-mfc-shared/allocating-and-releasing-memory-for-a-bstr.md). +Commonly, if this string is passed to a COM function as an `[in]` parameter, then this requires the caller to free the string. This can be done by using [`SysFreeString`](/windows/win32/api/oleauto/nf-oleauto-sysfreestring), as described in the Windows SDK. For more information, see [Allocating and Releasing Memory for a `BSTR`](../../atl-mfc-shared/allocating-and-releasing-memory-for-a-bstr.md). -For more information about OLE allocation functions in Windows, see [SysAllocString](/windows/win32/api/oleauto/nf-oleauto-sysallocstring) in the Windows SDK. +For more information about OLE allocation functions in Windows, see [`SysAllocString`](/windows/win32/api/oleauto/nf-oleauto-sysallocstring) in the Windows SDK. ### Example @@ -283,7 +283,7 @@ Zero if the strings are identical, < 0 if this **`CStringT`** object is less tha ### Remarks -The generic-text function `_tcscoll`, which is defined in TCHAR.H, maps to either `strcoll`, `wcscoll`, or `_mbscoll`, depending on the character set that is defined at compile time. Each function does a case-sensitive comparison of the strings according to the code page currently in use. For more information, see [strcoll, wcscoll, _mbscoll, _strcoll_l, _wcscoll_l, _mbscoll_l](../../c-runtime-library/reference/strcoll-wcscoll-mbscoll-strcoll-l-wcscoll-l-mbscoll-l.md). +The generic-text function `_tcscoll`, which is defined in `TCHAR.H`, maps to either `strcoll`, `wcscoll`, or `_mbscoll`, depending on the character set that is defined at compile time. Each function does a case-sensitive comparison of the strings according to the code page currently in use. For more information, see [`strcoll`, `wcscoll`, `_mbscoll`, `_strcoll_l`, `_wcscoll_l`, _mbscoll_l](../../c-runtime-library/reference/strcoll-wcscoll-mbscoll-strcoll-l-wcscoll-l-mbscoll-l.md). ## `CStringT::CollateNoCase` @@ -304,7 +304,7 @@ Zero if the strings are identical (ignoring case), < 0 if this **`CStringT`** ob ### Remarks -The generic-text function `_tcscoll`, which is defined in TCHAR.H, maps to either `stricoll`, `wcsicoll`, or `_mbsicoll`, depending on the character set that is defined at compile time. Each function does a case-insensitive comparison of the strings, according to the code page currently in use. For more information, see [strcoll, wcscoll, _mbscoll, _strcoll_l, _wcscoll_l, _mbscoll_l](../../c-runtime-library/reference/strcoll-wcscoll-mbscoll-strcoll-l-wcscoll-l-mbscoll-l.md). +The generic-text function `_tcscoll`, which is defined in `TCHAR.H`, maps to either `stricoll`, `wcsicoll`, or `_mbsicoll`, depending on the character set that is defined at compile time. Each function does a case-insensitive comparison of the strings, according to the code page currently in use. For more information, see [`strcoll`, `wcscoll`, `_mbscoll`, `_strcoll_l`, `_wcscoll_l`, `_mbscoll_l`](../../c-runtime-library/reference/strcoll-wcscoll-mbscoll-strcoll-l-wcscoll-l-mbscoll-l.md). ### Example @@ -329,7 +329,7 @@ Zero if the strings are identical, < 0 if this **`CStringT`** object is less tha ### Remarks -The generic-text function `_tcscmp`, which is defined in TCHAR.H, maps to either `strcmp`, `wcscmp`, or `_mbscmp`, depending on the character set that is defined at compile time. Each function does a case-sensitive comparison of the strings and isn't affected by locale. For more information, see [strcmp, wcscmp, _mbscmp](../../c-runtime-library/reference/strcmp-wcscmp-mbscmp.md). +The generic-text function `_tcscmp`, which is defined in `TCHAR.H`, maps to either `strcmp`, `wcscmp`, or `_mbscmp`, depending on the character set that is defined at compile time. Each function does a case-sensitive comparison of the strings and isn't affected by locale. For more information, see [`strcmp`, `wcscmp`, `_mbscmp`](../../c-runtime-library/reference/strcmp-wcscmp-mbscmp.md). If the string contains embedded nulls, for purposes of comparison the string is considered to be truncated at the first embedded null character. @@ -358,7 +358,7 @@ Zero if the strings are identical (ignoring case), <0 if this **`CStringT`** obj ### Remarks -The generic-text function `_tcsicmp`, which is defined in TCHAR.H, maps to either `_stricmp`, `_wcsicmp` or `_mbsicmp`, depending on the character set that is defined at compile time. Each function does a case-insensitive comparison of the strings. The comparison depends on the LC_CTYPE aspect of the locale but not LC_COLLATE. For more information, see [_stricmp, _wcsicmp, _mbsicmp, _stricmp_l, _wcsicmp_l, _mbsicmp_l](../../c-runtime-library/reference/stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md). +The generic-text function `_tcsicmp`, which is defined in `TCHAR.H`, maps to either `_stricmp`, `_wcsicmp` or `_mbsicmp`, depending on the character set that is defined at compile time. Each function does a case-insensitive comparison of the strings. The comparison depends on the `LC_CTYPE` aspect of the locale but not `LC_COLLATE`. For more information, see [`_stricmp`, `_wcsicmp`, `_mbsicmp`, `_stricmp_l`, `_wcsicmp_l`, `_mbsicmp_l`](../../c-runtime-library/reference/stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md). ### Example @@ -444,10 +444,10 @@ CStringT(const YCHAR* pch, int nLength, IAtlStringMgr* pStringMgr) : ### Parameters *`pch`*\ -A pointer to an array of characters of length *nLength*, not null-terminated. +A pointer to an array of characters of length *`nLength`*, not null-terminated. *`nLength`*\ -A count of the number of characters in *pch*. +A count of the number of characters in *`pch`*. *`ch`*\ A single character. @@ -486,16 +486,16 @@ A handle for a **`CStringT`** object. Because the constructors copy the input data into new allocated storage, memory exceptions may result. Some of these constructors act as conversion functions. This allows you to substitute, for example, an **`LPTSTR`** where a **`CStringT`** object is expected. -- **`CStringT`**( `LPCSTR` `lpsz` ): Constructs a Unicode **`CStringT`** from an ANSI string. You can also use this constructor to load a string resource as shown in the example below. +- **`CStringT`**(`LPCSTR` `lpsz`): Constructs a Unicode **`CStringT`** from an ANSI string. You can also use this constructor to load a string resource as shown in the example below. -- `CStringT(` `LPCWSTR` `lpsz` ): Constructs a **`CStringT`** from a Unicode string. +- **`CStringT`**(`LPCWSTR` `lpsz`): Constructs a **`CStringT`** from a Unicode string. -- **`CStringT`**( `const unsigned char*` `psz` ): Allows you to construct a **`CStringT`** from a pointer to **`unsigned char`**. +- **`CStringT`**(`const unsigned char*` `psz`): Allows you to construct a **`CStringT`** from a pointer to **`unsigned char`**. > [!NOTE] > Define the `_CSTRING_DISABLE_NARROW_WIDE_CONVERSION` macro to turn off implicit string conversion between ANSI and Unicode strings. The macro excludes from compilation constructors that support conversion. -The *`strSrc`* parameter can be either a **`CStringT`** or `CThisSimpleString` object. For **`CStringT`**, use one of its default instantiations (`CString`, `CStringA`, or `CStringW`); for `CThisSimpleString`, use a **`this`** pointer. `CThisSimpleString` declares an instance of the [CSimpleStringT Class](../../atl-mfc-shared/reference/csimplestringt-class.md), which is a smaller string class with less built-in functionality than the **`CStringT`** class. +The *`strSrc`* parameter can be either a **`CStringT`** or `CThisSimpleString` object. For **`CStringT`**, use one of its default instantiations (`CString`, `CStringA`, or `CStringW`); for `CThisSimpleString`, use a **`this`** pointer. `CThisSimpleString` declares an instance of the [`CSimpleStringT` Class](../../atl-mfc-shared/reference/csimplestringt-class.md), which is a smaller string class with less built-in functionality than the **`CStringT`** class. The overload operator `CSimpleStringT<>&()` constructs a **`CStringT`** object from a `CSimpleStringT` declaration. @@ -612,7 +612,7 @@ Finds the first occurrence of any of the characters in *`pszCharSet`*. ## `CStringT::Format` -Writes formatted data to a **`CStringT`** in the same way that [sprintf_s](../../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md) formats data into a C-style character array. +Writes formatted data to a **`CStringT`** in the same way that [`sprintf_s`](../../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md) formats data into a C-style character array. ```cpp void __cdecl Format(UINT nFormatID, [, argument]...); @@ -638,7 +638,7 @@ The call will fail if the string object itself is offered as a parameter to `For [!code-cpp[NVC_ATLMFC_Utilities#116](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_11.cpp)] -For more information, see [Format Specification Syntax: printf and wprintf Functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format Specification Syntax: `printf` and `wprintf` Functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). ### Example @@ -659,7 +659,7 @@ void __cdecl FormatMessage(PCXSTR pszFormat, [, argument]...); The string resource identifier that contains the unformatted message text. *`pszFormat`*\ -Points to the format-control string. It will be scanned for inserts and formatted accordingly. The format string is similar to run-time function *printf*-style format strings, except it allows for the parameters to be inserted in an arbitrary order. +Points to the format-control string. It will be scanned for inserts and formatted accordingly. The format string is similar to run-time function *`printf`*-style format strings, except it allows for the parameters to be inserted in an arbitrary order. *`argument`*\ Optional arguments. @@ -671,7 +671,7 @@ The function requires a message definition as input. The message definition is d > [!NOTE] > `FormatMessage` attempts to allocate system memory for the newly formatted string. If this attempt fails, a memory exception is automatically thrown. -Each insert must have a corresponding parameter following the *`pszFormat`* or *`nFormatID`* parameter. Within the message text, several escape sequences are supported for dynamically formatting the message. For more information, see the Windows [FormatMessage](/windows/win32/api/winbase/nf-winbase-formatmessage) function in the Windows SDK. +Each insert must have a corresponding parameter following the *`pszFormat`* or *`nFormatID`* parameter. Within the message text, several escape sequences are supported for dynamically formatting the message. For more information, see the Windows [`FormatMessage`](/windows/win32/api/winbase/nf-winbase-formatmessage) function in the Windows SDK. ### Example @@ -698,9 +698,9 @@ Pointer to a list of arguments. The function requires a message definition as input, determined by *`pszFormat`*. The function copies the formatted message text and a variable list of arguments to the **`CStringT`** object, processing any embedded insert sequences if requested. > [!NOTE] -> `FormatMessageV` calls [CStringT::FormatMessage](#formatmessage), which attempts to allocate system memory for the newly formatted string. If this attempt fails, a memory exception is automatically thrown. +> `FormatMessageV` calls [`CStringT::FormatMessage`](#formatmessage), which attempts to allocate system memory for the newly formatted string. If this attempt fails, a memory exception is automatically thrown. -For more information, see the Windows [FormatMessage](/windows/win32/api/winbase/nf-winbase-formatmessage) function in the Windows SDK. +For more information, see the Windows [`FormatMessage`](/windows/win32/api/winbase/nf-winbase-formatmessage) function in the Windows SDK. ## `CStringT::FormatV` @@ -725,7 +725,7 @@ Writes a formatted string and a variable list of arguments to a **`CStringT`** s ### Example [!code-cpp[NVC_ATLMFC_Utilities#119](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_14.cpp)] - +  [!code-cpp[NVC_ATLMFC_Utilities#120](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_15.cpp)] ## `CStringT::GetEnvironmentVariable` @@ -779,7 +779,7 @@ The length of the changed string. ### Remarks -The *`iIndex`* parameter identifies the first character that will be moved to make room for the character or substring. If *nIndex* is zero, the insertion will occur before the entire string. If *nIndex* is higher than the length of the string, the function will concatenate the present string and the new material provided by either *`ch`* or *`psz`*. +The *`iIndex`* parameter identifies the first character that will be moved to make room for the character or substring. If *`nIndex`* is zero, the insertion will occur before the entire string. If *nIndex* is higher than the length of the string, the function will concatenate the present string and the new material provided by either *`ch`* or *`psz`*. ### Example @@ -839,7 +839,7 @@ Nonzero if resource load was successful; otherwise 0. ### Remarks -Loads the string resource (*nID*) from the specified module (*hInstance*) using the specified language (*wLanguage*). +Loads the string resource (*`nID`*) from the specified module (*`hInstance`*) using the specified language (*`wLanguage`*). ### Example @@ -940,7 +940,7 @@ This function isn't available if `_UNICODE` is defined. ### Example -See the example for [CStringT::AnsiToOem](#ansitooem). +See the example for [`CStringT::AnsiToOem`](#ansitooem). ## `CStringT::operator =` @@ -986,7 +986,7 @@ A pointer to the original string being assigned. The assignment operator accepts another **`CStringT`** object, a character pointer, or a single character. Memory exceptions can occur whenever you use this operator because new storage can be allocated. -For information on `CThisSimpleString`, see the Remarks section of [CStringT::CStringT](#cstringt). +For information on `CThisSimpleString`, see the Remarks section of [`CStringT::CStringT`](#cstringt). > [!NOTE] > Although it is possible to create **`CStringT`** instances that contain embedded null characters, we recommend against it. Calling methods and operators on **`CStringT`** objects that contain embedded null characters can produce unintended results. @@ -998,11 +998,11 @@ Concatenates two strings or a character and a string. ```cpp friend CStringT operator+(const CStringT& str1, const CStringT& str2); friend CStringT operator+(const CStringT& str1, PCXSTR psz2); -friend CStringT operator+(PCXSTR psz1, const CStringT& str2,); -friend CStringT operator+(char ch1, const CStringT& str2,); +friend CStringT operator+(PCXSTR psz1, const CStringT& str2); +friend CStringT operator+(char ch1, const CStringT& str2); friend CStringT operator+(const CStringT& str1, char ch2); friend CStringT operator+(const CStringT& str1, wchar_t ch2); -friend CStringT operator+(wchar_t ch1, const CStringT& str2,); +friend CStringT operator+(wchar_t ch1, const CStringT& str2); ``` ### Parameters @@ -1083,7 +1083,7 @@ A **`CStringT`** to concatenate to this string. The operator accepts another **`CStringT`** object, a character pointer, or a single character. Memory exceptions can occur whenever you use this concatenation operator because new storage can be allocated for characters added to this **`CStringT`** object. -For information on `CThisSimpleString`, see the Remarks section of [CStringT::CStringT](#cstringt). +For information on `CThisSimpleString`, see the Remarks section of [`CStringT::CStringT`](#cstringt). > [!NOTE] > Although it is possible to create **`CStringT`** instances that contain embedded null characters, we recommend against it. Calling methods and operators on **`CStringT`** objects that contain embedded null characters can produce unintended results. @@ -1102,8 +1102,8 @@ friend bool operator==(const CStringT& str1, PCXSTR psz2) throw(); friend bool operator==(const CStringT& str1, PCYSTR psz2) throw(); friend bool operator==(const CStringT& str1, XCHAR ch2) throw(); friend bool operator==(PCXSTR psz1, const CStringT& str2) throw(); -friend bool operator==(PCYSTR psz1, const CStringT& str2,) throw(); -friend bool operator==(XCHAR ch1, const CStringT& str2,) throw(); +friend bool operator==(PCYSTR psz1, const CStringT& str2) throw(); +friend bool operator==(XCHAR ch1, const CStringT& str2) throw(); ``` ### Parameters @@ -1144,8 +1144,8 @@ friend bool operator!=(const CStringT& str1, PCXSTR psz2) throw(); friend bool operator!=(const CStringT& str1, PCYSTR psz2) throw(); friend bool operator!=(const CStringT& str1, XCHAR ch2) throw(); friend bool operator!=(PCXSTR psz1, const CStringT& str2) throw(); -friend bool operator!=(PCYSTR psz1, const CStringT& str2,) throw(); -friend bool operator!=(XCHAR ch1, const CStringT& str2,) throw(); +friend bool operator!=(PCYSTR psz1, const CStringT& str2) throw(); +friend bool operator!=(XCHAR ch1, const CStringT& str2) throw(); ``` ### Parameters @@ -1447,7 +1447,7 @@ A **`CStringT`** object that contains a copy of the specified range of character If *`nCount`* exceeds the string length, then the entire string is extracted. `Right` is similar to the Basic `Right` function (except that indexes in Basic are zero-based). -For multibyte character sets (MBCS), *`nCount`* refers to each 8-bit character; that is, a lead and trail byte in one multibyte character are counted as two characters. +For multibyte character sets (`MBCS`), *`nCount`* refers to each 8-bit character; that is, a lead and trail byte in one multibyte character are counted as two characters. ### Example @@ -1455,7 +1455,7 @@ For multibyte character sets (MBCS), *`nCount`* refers to each 8-bit character; ## `CStringT::SetSysString` -Reallocates the **`BSTR`** pointed to by *`pbstr`* and copies the contents of the **`CStringT`** object into it, including the NULL character. +Reallocates the **`BSTR`** pointed to by *`pbstr`* and copies the contents of the **`CStringT`** object into it, including the `NULL` character. ```cpp BSTR SetSysString(BSTR* pbstr) const; @@ -1552,9 +1552,9 @@ A **`CStringT`** object containing the current token value. ### Remarks -The `Tokenize` function finds the next token in the target string. The set of characters in *pszTokens* specifies possible delimiters of the token to be found. On each call to `Tokenize` the function starts at *`iStart`*, skips leading delimiters, and returns a **`CStringT`** object containing the current token, which is the string of characters up to the next delimiter character. The value of *`iStart`* is updated to be the position following the ending delimiter character, or -1 if the end of the string was reached. More tokens can be broken out of the rest of the target string by a series of calls to `Tokenize`, using *`iStart`* to keep track of where in the string the next token is to be read. When there are no more tokens, the function will return an empty string and *`iStart`* will be set to -1. +The `Tokenize` function finds the next token in the target string. The set of characters in *`pszTokens`* specifies possible delimiters of the token to be found. On each call to `Tokenize` the function starts at *`iStart`*, skips leading delimiters, and returns a **`CStringT`** object containing the current token, which is the string of characters up to the next delimiter character. The value of *`iStart`* is updated to be the position following the ending delimiter character, or -1 if the end of the string was reached. More tokens can be broken out of the rest of the target string by a series of calls to `Tokenize`, using *`iStart`* to keep track of where in the string the next token is to be read. When there are no more tokens, the function will return an empty string and *`iStart`* will be set to -1. -Unlike the CRT tokenize functions like [`strtok_s, _strtok_s_l, wcstok_s, _wcstok_s_l, _mbstok_s, _mbstok_s_l`](../../c-runtime-library/reference/strtok-s-strtok-s-l-wcstok-s-wcstok-s-l-mbstok-s-mbstok-s-l.md), `Tokenize` doesn't modify the target string. +Unlike the CRT tokenize functions like [`strtok_s`, `_strtok_s_l`, `wcstok_s`, `_wcstok_s_l`, `_mbstok_s`, `_mbstok_s_l`](../../c-runtime-library/reference/strtok-s-strtok-s-l-wcstok-s-wcstok-s-l-mbstok-s-mbstok-s-l.md), `Tokenize` doesn't modify the target string. ### Example @@ -1693,4 +1693,4 @@ The `CStringT& TrimRight()` version requires no parameters. It trims any trailin [Hierarchy Chart](../../mfc/hierarchy-chart.md)\ [ATL/MFC Shared Classes](../../atl-mfc-shared/atl-mfc-shared-classes.md)\ -[CSimpleStringT Class](../../atl-mfc-shared/reference/csimplestringt-class.md) +[`CSimpleStringT` Class](../../atl-mfc-shared/reference/csimplestringt-class.md) diff --git a/docs/atl-mfc-shared/reference/ctime-class.md b/docs/atl-mfc-shared/reference/ctime-class.md index 0fbc79bb4d..067db91b52 100644 --- a/docs/atl-mfc-shared/reference/ctime-class.md +++ b/docs/atl-mfc-shared/reference/ctime-class.md @@ -12,7 +12,7 @@ Represents an absolute time and date. ## Syntax -``` +```cpp class CTime ``` @@ -82,7 +82,7 @@ For more information about using `CTime`, see the articles [Date and Time](../.. Comparison operators. -``` +```cpp bool operator==(CTime time) const throw(); bool operator!=(CTime time) const throw(); bool operator<(CTime time) const throw(); @@ -108,7 +108,7 @@ These operators compare two absolute times and return TRUE if the condition is t Creates a new `CTime` object initialized with the specified time. -``` +```cpp CTime() throw(); CTime(__time64_t time) throw(); CTime(int nYear, int nMonth, int nDay, @@ -193,7 +193,7 @@ For more information, see the [SYSTEMTIME](/windows/win32/api/minwinbase/ns-minw Call this member function to create a formatted representation of the date-time value. -``` +```cpp CString Format(LPCTSTR pszFormat) const; CString Format(UINT nFormatID) const; ``` @@ -224,7 +224,7 @@ This method throws an exception if the date-time value to format does not range Generates a formatted string that corresponds to this `CTime` object. -``` +```cpp CString FormatGmt(LPCTSTR pszFormat) const; CString FormatGmt(UINT nFormatID) const; ``` @@ -255,7 +255,7 @@ See the example for [CTime::Format](#format). Call this member function to convert the time information stored in the `CTime` object to a Win32-compatible DBTIMESTAMP structure. -``` +```cpp bool GetAsDBTIMESTAMP(DBTIMESTAMP& dbts) const throw(); ``` @@ -280,7 +280,7 @@ Stores the resulting time in the referenced *dbts* structure. The `DBTIMESTAMP` Call this member function to convert the time information stored in the `CTime` object to a Win32-compatible [SYSTEMTIME](/windows/win32/api/minwinbase/ns-minwinbase-systemtime) structure. -``` +```cpp bool GetAsSystemTime(SYSTEMTIME& st) const throw(); ``` @@ -305,7 +305,7 @@ TRUE if successful; otherwise FALSE. Returns a `CTime` object that represents the current time. -``` +```cpp static CTime WINAPI GetCurrentTime() throw(); ``` @@ -321,7 +321,7 @@ Returns the current system date and time in Coordinated Universal Time (UTC). Returns the day represent by the `CTime` object. -``` +```cpp int GetDay() const throw(); ``` @@ -341,7 +341,7 @@ This function calls `GetLocalTm`, which uses an internal, statically allocated b Returns the day of the week represented by the `CTime` object. -``` +```cpp int GetDayOfWeek() const throw(); ``` @@ -361,7 +361,7 @@ This function calls `GetLocalTm`, which uses an internal statically allocated bu Gets a **struct tm** that contains a decomposition of the time contained in this `CTime` object. -``` +```cpp struct tm* GetGmtTm(struct tm* ptm) const; ``` @@ -388,7 +388,7 @@ A pointer to a filled-in **struct tm** as defined in the include file TIME.H. Se Returns the hour represented by the `CTime` object. -``` +```cpp int GetHour() const throw(); ``` @@ -408,7 +408,7 @@ This function calls `GetLocalTm`, which uses an internal statically allocated bu Gets a **struct tm** containing a decomposition of the time contained in this `CTime` object. -``` +```cpp struct tm* GetLocalTm(struct tm* ptm) const; ``` @@ -435,7 +435,7 @@ A pointer to a filled-in **struct tm** as defined in the include file TIME.H. Se Returns the minute represented by the `CTime` object. -``` +```cpp int GetMinute() const throw(); ``` @@ -455,7 +455,7 @@ See the example for [GetHour](#gethour). Returns the month represented by the `CTime` object. -``` +```cpp int GetMonth() const throw(); ``` @@ -475,7 +475,7 @@ See the example for [GetDay](#getday). Returns the second represented by the `CTime` object. -``` +```cpp int GetSecond() const throw(); ``` @@ -495,7 +495,7 @@ See the example for [GetHour](#gethour). Returns a **__time64_t** value for the given `CTime` object. -``` +```cpp __time64_t GetTime() const throw(); ``` @@ -511,7 +511,7 @@ __time64_t GetTime() const throw(); Returns the year represented by the `CTime` object. -``` +```cpp int GetYear(); ``` @@ -531,7 +531,7 @@ See the example for [GetDay](#getday). The assignment operator. -``` +```cpp CTime& operator=(__time64_t time) throw(); ``` @@ -552,7 +552,7 @@ This overloaded assignment operator copies the source time into this `CTime` obj These operators add and subtract `CTimeSpan` and `CTime` objects. -``` +```cpp CTime operator+(CTimeSpan timeSpan) const throw(); CTime operator-(CTimeSpan timeSpan) const throw(); CTimeSpan operator-(CTime time) const throw(); @@ -582,7 +582,7 @@ A `CTime` or `CTimeSpan` object representing the result of the operation. These operators add and subtract a `CTimeSpan` object to and from this `CTime` object. -``` +```cpp CTime& operator+=(CTimeSpan span) throw(); CTime& operator-=(CTimeSpan span) throw(); ``` @@ -611,7 +611,7 @@ These operators allow you to add and subtract a `CTimeSpan` object to and from t Serializes the data associated with the member variable to or from an archive. -``` +```cpp CArchive& Serialize64(CArchive& ar); ``` diff --git a/docs/atl-mfc-shared/reference/ctimespan-class.md b/docs/atl-mfc-shared/reference/ctimespan-class.md index d00f45805e..ae10bdba1c 100644 --- a/docs/atl-mfc-shared/reference/ctimespan-class.md +++ b/docs/atl-mfc-shared/reference/ctimespan-class.md @@ -4,15 +4,14 @@ title: "CTimeSpan Class" ms.date: "10/18/2018" f1_keywords: ["CTimeSpan", "ATLTIME/ATL::CTimeSpan", "ATLTIME/ATL::CTimeSpan::CTimeSpan", "ATLTIME/ATL::CTimeSpan::Format", "ATLTIME/ATL::CTimeSpan::GetDays", "ATLTIME/ATL::CTimeSpan::GetHours", "ATLTIME/ATL::CTimeSpan::GetMinutes", "ATLTIME/ATL::CTimeSpan::GetSeconds", "ATLTIME/ATL::CTimeSpan::GetTimeSpan", "ATLTIME/ATL::CTimeSpan::GetTotalHours", "ATLTIME/ATL::CTimeSpan::GetTotalMinutes", "ATLTIME/ATL::CTimeSpan::GetTotalSeconds", "ATLTIME/ATL::CTimeSpan::Serialize64"] helpviewer_keywords: ["elapsed time, CTimeSpan object", "timespan", "time span", "CTimeSpan class", "shared classes, CTimeSpan", "time, elapsed"] -ms.assetid: ee1e42f6-1839-477a-8435-fb26ad475140 --- -# CTimeSpan Class +# `CTimeSpan` Class An amount of time, which is internally stored as the number of seconds in the time span. ## Syntax -``` +```cpp class CTimeSpan ``` @@ -22,54 +21,54 @@ class CTimeSpan |Name|Description| |----------|-----------------| -|[CTimeSpan::CTimeSpan](#ctimespan)|Constructs `CTimeSpan` objects in various ways.| +|[`CTimeSpan::CTimeSpan`](#ctimespan)|Constructs `CTimeSpan` objects in various ways.| ### Public Methods |Name|Description| |----------|-----------------| -|[CTimeSpan::Format](#format)|Converts a `CTimeSpan` into a formatted string.| -|[CTimeSpan::GetDays](#getdays)|Returns a value that represents the number of complete days in this `CTimeSpan`.| -|[CTimeSpan::GetHours](#gethours)|Returns a value that represents the number of hours in the current day (-23 through 23).| -|[CTimeSpan::GetMinutes](#getminutes)|Returns a value that represents the number of minutes in the current hour (-59 through 59).| -|[CTimeSpan::GetSeconds](#getseconds)|Returns a value that represents the number of seconds in the current minute (-59 through 59).| -|[CTimeSpan::GetTimeSpan](#gettimespan)|Returns the value of the `CTimeSpan` object.| -|[CTimeSpan::GetTotalHours](#gettotalhours)|Returns a value that represents the total number of complete hours in this `CTimeSpan`.| -|[CTimeSpan::GetTotalMinutes](#gettotalminutes)|Returns a value that represents the total number of complete minutes in this `CTimeSpan`.| -|[CTimeSpan::GetTotalSeconds](#gettotalseconds)|Returns a value that represents the total number of complete seconds in this `CTimeSpan`.| -|[CTimeSpan::Serialize64](#serialize64)|Serializes data to or from an archive.| +|[`CTimeSpan::Format`](#format)|Converts a `CTimeSpan` into a formatted string.| +|[`CTimeSpan::GetDays`](#getdays)|Returns a value that represents the number of complete days in this `CTimeSpan`.| +|[`CTimeSpan::GetHours`](#gethours)|Returns a value that represents the number of hours in the current day (-23 through 23).| +|[`CTimeSpan::GetMinutes`](#getminutes)|Returns a value that represents the number of minutes in the current hour (-59 through 59).| +|[`CTimeSpan::GetSeconds`](#getseconds)|Returns a value that represents the number of seconds in the current minute (-59 through 59).| +|[`CTimeSpan::GetTimeSpan`](#gettimespan)|Returns the value of the `CTimeSpan` object.| +|[`CTimeSpan::GetTotalHours`](#gettotalhours)|Returns a value that represents the total number of complete hours in this `CTimeSpan`.| +|[`CTimeSpan::GetTotalMinutes`](#gettotalminutes)|Returns a value that represents the total number of complete minutes in this `CTimeSpan`.| +|[`CTimeSpan::GetTotalSeconds`](#gettotalseconds)|Returns a value that represents the total number of complete seconds in this `CTimeSpan`.| +|[`CTimeSpan::Serialize64`](#serialize64)|Serializes data to or from an archive.| ### Operators |Name|Description| |-|-| -|[operator + -](#operator_add_-)|Adds and subtracts `CTimeSpan` objects.| -|[operator += -=](#operator_add_eq_-_eq)|Adds and subtracts a `CTimeSpan` object to and from this `CTimeSpan`.| -|[operator == < etc.](#ctimespan_comparison_operators)|Compares two relative time values.| +|[`operator + -`](#operator_add_-)|Adds and subtracts `CTimeSpan` objects.| +|[`operator += -=`](#operator_add_eq_-_eq)|Adds and subtracts a `CTimeSpan` object to and from this `CTimeSpan`.| +|[`operator == < etc.`](#ctimespan_comparison_operators)|Compares two relative time values.| ## Remarks -`CTimeSpan` does not have a base class. +`CTimeSpan` doesn't have a base class. `CTimeSpan` functions convert seconds to various combinations of days, hours, minutes, and seconds. -The `CTimeSpan` object is stored in a **__time64_t** structure, which is 8 bytes. +The `CTimeSpan` object is stored in a **`__time64_t`** structure, which is 8 bytes. -A companion class, [CTime](../../atl-mfc-shared/reference/ctime-class.md), represents an absolute time. +A companion class, [`CTime`](../../atl-mfc-shared/reference/ctime-class.md), represents an absolute time. -The `CTime` and `CTimeSpan` classes are not designed for derivation. Because there are no virtual functions, the size of both `CTime` and `CTimeSpan` objects is exactly 8 bytes. Most member functions are inline. +The `CTime` and `CTimeSpan` classes aren't designed for derivation. Because there are no virtual functions, the size of both `CTime` and `CTimeSpan` objects is exactly 8 bytes. Most member functions are inline. For more information on using `CTimeSpan`, see the articles [Date and Time](../../atl-mfc-shared/date-and-time.md), and [Time Management](../../c-runtime-library/time-management.md) in the *Run-Time Library Reference*. ## Requirements -**Header:** atltime.h +**Header:** `atltime.h` -## CTimeSpan Comparison Operators +## `CTimeSpan` Comparison Operators Comparison operators. -``` +```cpp bool operator==(CTimeSpan span) const throw(); bool operator!=(CTimeSpan span) const throw(); bool operator<(CTimeSpan span) const throw(); @@ -80,22 +79,22 @@ bool operator>=(CTimeSpan span) const throw(); ### Parameters -*span*
+*`span`*\ The object to compare. ### Return Value -These operators compare two relative time values. They return TRUE if the condition is true; otherwise FALSE. +These operators compare two relative time values. They return `TRUE` if the condition is true; otherwise `FALSE`. ### Example [!code-cpp[NVC_ATLMFC_Utilities#169](../../atl-mfc-shared/codesnippet/cpp/ctimespan-class_1.cpp)] -## CTimeSpan::CTimeSpan +## `CTimeSpan::CTimeSpan` Constructs `CTimeSpan` objects in various ways. -``` +```cpp CTimeSpan() throw(); CTimeSpan(__time64_t time) throw(); @@ -108,13 +107,13 @@ CTimeSpan( ### Parameters -*timeSpanSrc*
+*`timeSpanSrc`*\ A `CTimeSpan` object that already exists. -*time*
-A **__time64_t** time value, which is the number of seconds in the time span. +*`time`*\ +A **`__time64_t`** time value, which is the number of seconds in the time span. -*lDays*, *nHours*, *nMins*, *nSecs*
+*`lDays`*, *`nHours`*, *`nMins`*, *`nSecs`*\ Days, hours, minutes, and seconds, respectively. ### Remarks @@ -125,7 +124,7 @@ All these constructors create a new `CTimeSpan` object initialized with the spec - `CTimeSpan( const CTimeSpan& );` Constructs a `CTimeSpan` object from another `CTimeSpan` value. -- `CTimeSpan( __time64_t );` Constructs a `CTimeSpan` object from a **__time64_t** type. +- `CTimeSpan( __time64_t );` Constructs a `CTimeSpan` object from a **`__time64_t`** type. - `CTimeSpan( LONG, int, int, int );` Constructs a `CTimeSpan` object from components with each component constrained to the following ranges: @@ -142,11 +141,11 @@ Note that the Debug version of the Microsoft Foundation Class Library asserts if [!code-cpp[NVC_ATLMFC_Utilities#162](../../atl-mfc-shared/codesnippet/cpp/ctimespan-class_2.cpp)] -## CTimeSpan::Format +## `CTimeSpan::Format` Generates a formatted string that corresponds to this `CTimeSpan`. -``` +```cpp CString Format(LPCSTR pFormat) const; CString Format(LPCTSTR pszFormat) const; CString Format(UINT nID) const; @@ -154,20 +153,20 @@ CString Format(UINT nID) const; ### Parameters -*pFormat*, *pszFormat*
+*`pFormat`*, *`pszFormat`*\ A formatting string similar to the `printf` formatting string. Formatting codes, preceded by a percent (`%`) sign, are replaced by the corresponding `CTimeSpan` component. Other characters in the formatting string are copied unchanged to the returned string. The value and meaning of the formatting codes for `Format` are listed below: -- **%D** Total days in this `CTimeSpan` +- **`%D`** Total days in this `CTimeSpan` -- **%H** Hours in the current day +- **`%H`** Hours in the current day -- **%M** Minutes in the current hour +- **`%M`** Minutes in the current hour -- **%S** Seconds in the current minute +- **`%S`** Seconds in the current minute -- **%%** Percent sign +- **`%%`** Percent sign -*nID*
+*`nID`*\ The ID of the string that identifies this format. ### Return Value @@ -176,17 +175,17 @@ A `CString` object that contains the formatted time. ### Remarks -The Debug version of the library checks the formatting codes and asserts if the code is not in the list above. +The Debug version of the library checks the formatting codes and asserts if the code isn't in the list above. ### Example [!code-cpp[NVC_ATLMFC_Utilities#163](../../atl-mfc-shared/codesnippet/cpp/ctimespan-class_3.cpp)] -## CTimeSpan::GetDays +## `CTimeSpan::GetDays` Returns a value that represents the number of complete days in this `CTimeSpan`. -``` +```cpp LONGLONG GetDays() const throw(); ``` @@ -196,17 +195,17 @@ Returns the number of complete 24-hour days in the time span. This value may be ### Remarks -Note that Daylight Savings Time can cause `GetDays` to return a potentially surprising result. For example, when DST is in effect, `GetDays` reports the number of days between April 1 and May 1 as 29, not 30, because one day in April is shortened by an hour and therefore does not count as a complete day. +Note that Daylight Savings Time (DST) can cause `GetDays` to return a potentially surprising result. For example, when DST is in effect, `GetDays` reports the number of days between April 1 and May 1 as 29, not 30, because one day in April is shortened by an hour and therefore doesn't count as a complete day. ### Example [!code-cpp[NVC_ATLMFC_Utilities#164](../../atl-mfc-shared/codesnippet/cpp/ctimespan-class_4.cpp)] -## CTimeSpan::GetHours +## `CTimeSpan::GetHours` Returns a value that represents the number of hours in the current day (-23 through 23). -``` +```cpp LONG GetHours() const throw(); ``` @@ -218,11 +217,11 @@ Returns the number of hours in the current day. The range is -23 through 23. [!code-cpp[NVC_ATLMFC_Utilities#165](../../atl-mfc-shared/codesnippet/cpp/ctimespan-class_5.cpp)] -## CTimeSpan::GetMinutes +## `CTimeSpan::GetMinutes` Returns a value that represents the number of minutes in the current hour (-59 through 59). -``` +```cpp LONG GetMinutes() const throw(); ``` @@ -232,13 +231,13 @@ Returns the number of minutes in the current hour. The range is -59 through 59. ### Example -See the example for [GetHours](#gethours). +See the example for [`GetHours`](#gethours). -## CTimeSpan::GetSeconds +## `CTimeSpan::GetSeconds` Returns a value that represents the number of seconds in the current minute (-59 through 59). -``` +```cpp LONG GetSeconds() const throw(); ``` @@ -248,13 +247,13 @@ Returns the number of seconds in the current minute. The range is -59 through 59 ### Example -See the example for [GetHours](#gethours). +See the example for [`GetHours`](#gethours). -## CTimeSpan::GetTimeSpan +## `CTimeSpan::GetTimeSpan` Returns the value of the `CTimeSpan` object. -``` +```cpp __ time64_t GetTimeSpan() const throw(); ``` @@ -262,11 +261,11 @@ __ time64_t GetTimeSpan() const throw(); Returns the current value of the `CTimeSpan` object. -## CTimeSpan::GetTotalHours +## `CTimeSpan::GetTotalHours` Returns a value that represents the total number of complete hours in this `CTimeSpan`. -``` +```cpp LONGLONG GetTotalHours() const throw(); ``` @@ -278,11 +277,11 @@ Returns the total number of complete hours in this `CTimeSpan`. [!code-cpp[NVC_ATLMFC_Utilities#166](../../atl-mfc-shared/codesnippet/cpp/ctimespan-class_6.cpp)] -## CTimeSpan::GetTotalMinutes +## `CTimeSpan::GetTotalMinutes` Returns a value that represents the total number of complete minutes in this `CTimeSpan`. -``` +```cpp LONGLONG GetTotalMinutes() const throw(); ``` @@ -292,13 +291,13 @@ Returns the total number of complete minutes in this `CTimeSpan`. ### Example -See the example for [GetTotalHours](#gettotalhours). +See the example for [`GetTotalHours`](#gettotalhours). -## CTimeSpan::GetTotalSeconds +## `CTimeSpan::GetTotalSeconds` Returns a value that represents the total number of complete seconds in this `CTimeSpan`. -``` +```cpp LONGLONG GetTotalSeconds() const throw(); ``` @@ -308,20 +307,20 @@ Returns the total number of complete seconds in this `CTimeSpan`. ### Example -See the example for [GetTotalHours](#gettotalhours). +See the example for [`GetTotalHours`](#gettotalhours). -## CTimeSpan::operator +, - +## `CTimeSpan::operator +`, `CTimeSpan::operator -` Adds and subtracts `CTimeSpan` objects. -``` +```cpp CTimeSpan operator+(CTimeSpan span) const throw(); CTimeSpan operator-(CTimeSpan span) const throw(); ``` ### Parameters -*span*
+*`span`*\ The value to add to the `CTimeSpan` object. ### Return Value @@ -336,18 +335,18 @@ These two operators allow you to add and subtract `CTimeSpan` objects to and fro [!code-cpp[NVC_ATLMFC_Utilities#167](../../atl-mfc-shared/codesnippet/cpp/ctimespan-class_7.cpp)] -## CTimeSpan::operator +=, -= +## `CTimeSpan::operator +=`, `CTimeSpan::operator -=` Adds and subtracts a `CTimeSpan` object to and from this `CTimeSpan`. -``` +```cpp CTimeSpan& operator+=(CTimeSpan span) throw(); CTimeSpan& operator-=(CTimeSpan span) throw(); ``` ### Parameters -*span*
+*`span`*\ The value to add to the `CTimeSpan` object. ### Return Value @@ -362,20 +361,20 @@ These operators allow you to add and subtract a `CTimeSpan` object to and from t [!code-cpp[NVC_ATLMFC_Utilities#168](../../atl-mfc-shared/codesnippet/cpp/ctimespan-class_8.cpp)] -## CTimeSpan::Serialize64 +## `CTimeSpan::Serialize64` > [!NOTE] > This method is only available in MFC projects. Serializes the data associated with the member variable to or from an archive. -``` +```cpp CArchive& Serialize64(CArchive& ar); ``` ### Parameters -*ar*
+*`ar`*\ The `CArchive` object that you want to update. ### Return Value @@ -384,11 +383,11 @@ The updated `CArchive` object. ## See also -[asctime, _wasctime](../../c-runtime-library/reference/asctime-wasctime.md)
-[_ftime, _ftime32, _ftime64](../../c-runtime-library/reference/ftime-ftime32-ftime64.md)
-[gmtime, _gmtime32, _gmtime64](../../c-runtime-library/reference/gmtime-gmtime32-gmtime64.md)
-[localtime, _localtime32, _localtime64](../../c-runtime-library/reference/localtime-localtime32-localtime64.md)
-[strftime, wcsftime, _strftime_l, _wcsftime_l](../../c-runtime-library/reference/strftime-wcsftime-strftime-l-wcsftime-l.md)
-[time, _time32, _time64](../../c-runtime-library/reference/time-time32-time64.md)
-[Hierarchy Chart](../../mfc/hierarchy-chart.md)
+[`asctime`, `_wasctime`](../../c-runtime-library/reference/asctime-wasctime.md)\ +[`_ftime`, `_ftime32`, `_ftime64`](../../c-runtime-library/reference/ftime-ftime32-ftime64.md)\ +[`gmtime`, `_gmtime32`, `_gmtime64`](../../c-runtime-library/reference/gmtime-gmtime32-gmtime64.md)\ +[`localtime`, `_localtime32`, `_localtime64`](../../c-runtime-library/reference/localtime-localtime32-localtime64.md)\ +[`strftime`, `wcsftime`, `_strftime_l`, `_wcsftime_l`](../../c-runtime-library/reference/strftime-wcsftime-strftime-l-wcsftime-l.md)\ +[`time`, `_time32`, `_time64`](../../c-runtime-library/reference/time-time32-time64.md)\ +[Hierarchy Chart](../../mfc/hierarchy-chart.md)\ [ATL/MFC Shared Classes](../../atl-mfc-shared/atl-mfc-shared-classes.md) diff --git a/docs/atl-mfc-shared/reference/iatlstringmgr-class.md b/docs/atl-mfc-shared/reference/iatlstringmgr-class.md index cbf301b82b..9eb991ca28 100644 --- a/docs/atl-mfc-shared/reference/iatlstringmgr-class.md +++ b/docs/atl-mfc-shared/reference/iatlstringmgr-class.md @@ -12,7 +12,7 @@ This class represents the interface to a `CStringT` memory manager. ## Syntax -``` +```cpp __interface IAtlStringMgr ``` @@ -42,7 +42,7 @@ You can also use this class to implement a custom memory manager for your custom Allocates a new string data structure. -``` +```cpp CStringData* Allocate(int nAllocLength,int nCharSize) throw(); ``` @@ -72,7 +72,7 @@ Call [IAtlStringMgr::Free](#free) or [IAtlStringMgr::ReAllocate](#reallocate) to Returns a pointer to a new string manager for use with another instance of `CSimpleStringT`. -``` +```cpp IAtlStringMgr* Clone() throw(); ``` @@ -113,7 +113,7 @@ Frees the specified memory block previously allocated by [Allocate](#allocate) o Returns a pointer to a string data structure for an empty string. -``` +```cpp CStringData* GetNilString() throw(); ``` @@ -135,7 +135,7 @@ Call this function to return a representation of an empty string. Reallocates a string data structure. -``` +```cpp CStringData* Reallocate( CStringData* pData, int nAllocLength, diff --git a/docs/atl-mfc-shared/string-data-management.md b/docs/atl-mfc-shared/string-data-management.md index 80640e06c2..b48c6a636d 100644 --- a/docs/atl-mfc-shared/string-data-management.md +++ b/docs/atl-mfc-shared/string-data-management.md @@ -3,19 +3,18 @@ description: "Learn more about: String Data Management" title: "String Data Management" ms.date: "11/04/2016" helpviewer_keywords: ["Unicode, string objects"] -ms.assetid: 0b53a542-eeb1-4108-9ada-6700645b6f8f --- # String Data Management Visual C++ provides several ways to manage string data: -- [String Manipulation](../c-runtime-library/string-manipulation-crt.md) for working with C-style null-terminated strings +- [String Manipulation](../c-runtime-library/string-manipulation-crt.md) for working with C-style `NULL`-terminated strings - Win32 API functions for managing strings -- MFC's class [CStringT Class](../atl-mfc-shared/reference/cstringt-class.md), which provides flexible, resizable string objects +- MFC's class [`CStringT` Class](../atl-mfc-shared/reference/cstringt-class.md), which provides flexible, resizable string objects -- Class [CStringT Class](../atl-mfc-shared/reference/cstringt-class.md), which provides an MFC-independent string object with the same functionality as `CString` +- Class [`CStringT` Class](../atl-mfc-shared/reference/cstringt-class.md), which provides an MFC-independent string object with the same functionality as `CString` Nearly all programs work with string data. MFC's `CString` class is often the best solution for flexible string handling. Starting with version 7.0, `CString` can be used in MFC or MFC-independent programs. Both the run-time library and `CString` support strings containing multibyte (wide) characters, as in Unicode or MBCS programming. @@ -23,11 +22,11 @@ This article describes the general-purpose services that the class library provi - [Unicode and MBCS Provide portability](#_core_unicode_and_mbcs_provide_portability) -- [CStrings and const char Pointers](#_core_cstrings_and_const_char_pointers) +- [`CStrings` and `const char` Pointers](#_core_cstrings_and_const_char_pointers) -- [CString Reference Counting](#_core_cstring_reference_counting) +- [`CString` Reference Counting](#_core_cstring_reference_counting) -The [CStringT Class](../atl-mfc-shared/reference/cstringt-class.md) class provides support for manipulating strings. It is intended to replace and extend the functionality normally provided by the C run-time library string package. The `CString` class supplies member functions and operators for simplified string handling, similar to those found in Basic. The class also provides constructors and operators for constructing, assigning, and comparing `CString`s and standard C++ string data types. Because `CString` is not derived from `CObject`, you can use `CString` objects independently of most of the Microsoft Foundation Class Library (MFC). +The [`CStringT` Class](../atl-mfc-shared/reference/cstringt-class.md) class provides support for manipulating strings. It's intended to replace and extend the functionality normally provided by the C run-time library string package. The `CString` class supplies member functions and operators for simplified string handling, similar to those found in Basic. The class also provides constructors and operators for constructing, assigning, and comparing `CString`s and standard C++ string data types. Because `CString` isn't derived from `CObject`, you can use `CString` objects independently of most of the Microsoft Foundation Class Library (MFC). `CString` objects follow "value semantics." A `CString` object represents a unique value. Think of a `CString` as an actual string, not as a pointer to a string. @@ -35,10 +34,10 @@ A `CString` object represents a sequence of a variable number of characters. `CS ## Unicode and MBCS Provide Portability -With MFC version 3.0 and later, MFC, including `CString`, is enabled for both Unicode and multibyte character sets (MBCS). This support makes it easier for you to write portable applications that you can build for either Unicode or ANSI characters. To enable this portability, each character in a `CString` object is of type TCHAR, which is defined as **`wchar_t`** if you define the symbol _UNICODE when you build your application, or as **`char`** if not. A **`wchar_t`** character is 16 bits wide. MBCS is enabled if you build with the symbol _MBCS defined. MFC itself is built with either the _MBCS symbol (for the NAFX libraries) or the _UNICODE symbol (for the UAFX libraries) defined. +With MFC version 3.0 and later, MFC, including `CString`, is enabled for both Unicode and multibyte character sets (MBCS). This support makes it easier for you to write portable applications that you can build for either Unicode or ANSI characters. To enable this portability, each character in a `CString` object is of type `TCHAR`, which is defined as **`wchar_t`** if you define the symbol `_UNICODE` when you build your application, or as **`char`** if not. A **`wchar_t`** character is 16 bits wide. MBCS is enabled if you build with the symbol `_MBCS` defined. MFC itself is built with either the `_MBCS` symbol (for the NAFX libraries) or the `_UNICODE` symbol (for the UAFX libraries) defined. > [!NOTE] -> The `CString` examples in this and the accompanying articles on strings show literal strings properly formatted for Unicode portability, using the _T macro, which translates the literal string to the form: +> The `CString` examples in this and the accompanying articles on strings show literal strings properly formatted for Unicode portability, using the `_T` macro, which translates the literal string to the form: `L"literal string"` @@ -48,34 +47,34 @@ With MFC version 3.0 and later, MFC, including `CString`, is enabled for both Un [!code-cpp[NVC_ATLMFC_Utilities#187](../atl-mfc-shared/codesnippet/cpp/string-data-management_1.cpp)] > [!NOTE] -> is translated as a Unicode string if _UNICODE is defined or as an ANSI string if not. For more information, see the article [Unicode and Multibyte Character Set (MBCS) Support](../atl-mfc-shared/unicode-and-multibyte-character-set-mbcs-support.md). +> is translated as a Unicode string if `_UNICODE` is defined or as an ANSI string if not. For more information, see the article [Unicode and Multibyte Character Set (MBCS) Support](../atl-mfc-shared/unicode-and-multibyte-character-set-mbcs-support.md). -A `CString` object can store up to INT_MAX (2,147,483,647) characters. The TCHAR data type is used to get or set individual characters inside a `CString` object. Unlike character arrays, the `CString` class has a built-in memory allocation capability. This allows `CString` objects to automatically grow as needed (that is, you do not have to worry about growing a `CString` object to fit longer strings). +A `CString` object can store up to `INT_MAX` (2,147,483,647) characters. The `TCHAR` data type is used to get or set individual characters inside a `CString` object. Unlike character arrays, the `CString` class has a built-in memory allocation capability. This allows `CString` objects to automatically grow as needed (that is, you don't have to worry about growing a `CString` object to fit longer strings). -## CStrings and const char Pointers +## `CStrings` and `const char` Pointers -A `CString` object also can act like a literal C-style string (an `PCXSTR`, which is the same as **const char**\* if not under Unicode). The [CSimpleStringT::operator PCXSTR](../atl-mfc-shared/reference/csimplestringt-class.md#operator_pcxstr) conversion operator allows `CString` objects to be freely substituted for character pointers in function calls. The **CString( LPCWSTR** `pszSrc` **)** constructor allows character pointers to be substituted for `CString` objects. +A `CString` object also can act like a literal C-style string (an `PCXSTR`, which is the same as `const char*` if not under Unicode). The [`CSimpleStringT::operator PCXSTR`](../atl-mfc-shared/reference/csimplestringt-class.md#operator_pcxstr) conversion operator allows `CString` objects to be freely substituted for character pointers in function calls. The `CString(LPCWSTR pszSrc)` constructor allows character pointers to be substituted for `CString` objects. -No attempt is made to fold `CString` objects. If you make two `CString` objects containing `Chicago`, for example, the characters in `Chicago` are stored in two places. (This may not be true of future versions of MFC, so you should not depend on it.) +No attempt is made to fold `CString` objects. If you make two `CString` objects containing `Chicago`, for example, the characters in `Chicago` are stored in two places. (This may not be true of future versions of MFC, so you shouldn't depend on it.) > [!NOTE] -> Use the [CSimpleStringT::GetBuffer](../atl-mfc-shared/reference/csimplestringt-class.md#getbuffer) and [CSimpleStringT::ReleaseBuffer](../atl-mfc-shared/reference/csimplestringt-class.md#releasebuffer) member functions when you need to directly access a `CString` as a nonconstant pointer to a character. +> Use the [`CSimpleStringT::GetBuffer`](../atl-mfc-shared/reference/csimplestringt-class.md#getbuffer) and [`CSimpleStringT::ReleaseBuffer`](../atl-mfc-shared/reference/csimplestringt-class.md#releasebuffer) member functions when you need to directly access a `CString` as a nonconstant pointer to a character. > [!NOTE] -> Use the [CStringT::AllocSysString](../atl-mfc-shared/reference/cstringt-class.md#allocsysstring) and [CStringT::SetSysString](../atl-mfc-shared/reference/cstringt-class.md#setsysstring) member functions to allocate and set BSTR objects used in Automation (formerly known as OLE Automation). +> Use the [`CStringT::AllocSysString`](../atl-mfc-shared/reference/cstringt-class.md#allocsysstring) and [`CStringT::SetSysString`](../atl-mfc-shared/reference/cstringt-class.md#setsysstring) member functions to allocate and set `BSTR` objects used in Automation (formerly known as OLE Automation). > [!NOTE] > Where possible, allocate `CString` objects on the frame rather than on the heap. This saves memory and simplifies parameter passing. -The `CString` class is not implemented as a Microsoft Foundation Class Library collection class, though `CString` objects can certainly be stored as elements in collections. +The `CString` class isn't implemented as a Microsoft Foundation Class Library collection class, though `CString` objects can certainly be stored as elements in collections. -## CString Reference Counting +## `CString` Reference Counting -As of MFC version 4.0, when [CStringT Class](../atl-mfc-shared/reference/cstringt-class.md) objects are copied, MFC increments a reference count rather than copying the data. This makes passing parameters by value and returning `CString` objects by value more efficient. These operations cause the copy constructor to be called, sometimes more than once. Incrementing a reference count reduces that overhead for these common operations and makes using `CString` a more attractive option. +As of MFC version 4.0, when [`CStringT` Class](../atl-mfc-shared/reference/cstringt-class.md) objects are copied, MFC increments a reference count rather than copying the data. This makes passing parameters by value and returning `CString` objects by value more efficient. These operations cause the copy constructor to be called, sometimes more than once. Incrementing a reference count reduces that overhead for these common operations and makes using `CString` a more attractive option. -As each copy is destroyed, the reference count in the original object is decremented. The original `CString` object is not destroyed until its reference count is reduced to zero. +As each copy is destroyed, the reference count in the original object is decremented. The original `CString` object isn't destroyed until its reference count is reduced to zero. -You can use the `CString` member functions [CSimpleStringT::LockBuffer](../atl-mfc-shared/reference/csimplestringt-class.md#lockbuffer) and [CSimpleStringT::UnlockBuffer](../atl-mfc-shared/reference/csimplestringt-class.md#unlockbuffer) to disable or enable reference counting. +You can use the `CString` member functions [`CSimpleStringT::LockBuffer`](../atl-mfc-shared/reference/csimplestringt-class.md#lockbuffer) and [`CSimpleStringT::UnlockBuffer`](../atl-mfc-shared/reference/csimplestringt-class.md#unlockbuffer) to disable or enable reference counting. ## See also diff --git a/docs/atl-mfc-shared/strings-atl-mfc.md b/docs/atl-mfc-shared/strings-atl-mfc.md index db5891cc87..1c0b4515fa 100644 --- a/docs/atl-mfc-shared/strings-atl-mfc.md +++ b/docs/atl-mfc-shared/strings-atl-mfc.md @@ -3,7 +3,6 @@ description: "Learn more about: Strings (ATL/MFC)" title: "Strings (ATL-MFC)" ms.date: "11/04/2016" helpviewer_keywords: ["const char pointers", "strings [C++], in ATL", "MFC [C++], string handling class", "MBCS [C++], CString support", "strings [C++], class CStringT", "char pointers", "reference counting [C++]", "strings [C++], string operations", "portability [C++], Unicode and ANSI string objects", "literal strings [C++], class CString", "copying string objects", "ATL, string handling class", "strings [C++], in MFC", "strings [C++]", "C-style strings", "language portability [C++]", "strings [C++], class CString", "literal strings [C++], class CStringT"] -ms.assetid: 3b33125b-1684-4542-a3a7-b00de7d0419e --- # Strings (ATL/MFC) @@ -11,18 +10,18 @@ Nearly all programs work with string data. Visual C++ provides several ways to m ## In This Section -[Using CStringT](../atl-mfc-shared/using-cstringt.md)
-Describes programming using the template class CStringT. +[Using `CStringT`](../atl-mfc-shared/using-cstringt.md)\ +Describes programming using the template class `CStringT`. -[Using CString](../atl-mfc-shared/using-cstring.md)
-Describes programming using CString, the default implementation of CStringT. +[Using `CString`](../atl-mfc-shared/using-cstring.md)\ +Describes programming using `CString`, the default implementation of `CStringT`. ## Related Sections -[CStringT Overview](../atl-mfc-shared/reference/cstringt-class.md)
+[`CStringT` Overview](../atl-mfc-shared/reference/cstringt-class.md)\ Provides reference information about the shared `CStringT` class. -[MFC Concepts](../mfc/mfc-concepts.md)
+[MFC Concepts](../mfc/mfc-concepts.md)\ Provides conceptual and task-based topics to help you program using the MFC Library. ## See also diff --git a/docs/atl-mfc-shared/toc.yml b/docs/atl-mfc-shared/toc.yml index dbc065eaca..39bdbdcbe9 100644 --- a/docs/atl-mfc-shared/toc.yml +++ b/docs/atl-mfc-shared/toc.yml @@ -1,3 +1,4 @@ +items: - name: ATL-MFC shared classes href: ../atl-mfc-shared/atl-mfc-shared-classes.md - name: ATL-MFC concepts diff --git a/docs/atl-mfc-shared/unicode-and-multibyte-character-set-mbcs-support.md b/docs/atl-mfc-shared/unicode-and-multibyte-character-set-mbcs-support.md index 094c1d037a..2ba1928aa6 100644 --- a/docs/atl-mfc-shared/unicode-and-multibyte-character-set-mbcs-support.md +++ b/docs/atl-mfc-shared/unicode-and-multibyte-character-set-mbcs-support.md @@ -8,11 +8,14 @@ helpviewer_keywords: ["MFC [C++], character set support", "MBCS [C++], strings a Some languages, for example, Japanese and Chinese, have large character sets. To support programming for these markets, the Microsoft Foundation Class Library (MFC) enables two different approaches to handling large character sets: -- [Unicode](#mfc-support-for-unicode-strings), **`wchar_t`** based wide-characters and strings encoded as UTF-16. +- [Unicode](#mfc-support-for-unicode-strings), **`wchar_t`** based wide-characters, and strings encoded as UTF-16. - [Multibyte Character Sets (MBCS)](#mfc-support-for-mbcs-strings), **`char`** based single or double-byte characters and strings encoded in a locale-specific character set. -Microsoft has recommended the MFC Unicode libraries for all new development, and the MBCS libraries were deprecated in Visual Studio 2013 and Visual Studio 2015. This is no longer the case. The MBCS deprecation warnings have been removed in Visual Studio 2017. +> [!NOTE] +> Microsoft recommends the MFC Unicode libraries for all new development.\ +> The MBCS libraries were deprecated in Visual Studio 2013 and Visual Studio 2015. This is no longer the case.\ +> Starting with Visual Studio 2017, the MBCS libraries are no longer deprecated and don't generate deprecation warnings. ## MFC Support for Unicode Strings @@ -51,13 +54,13 @@ These library, debugger, and DLL files are used to support Unicode in MFC: (*version* represents the version number of the file; for example, '140' means version 14.0.) -`CString` is based on the `TCHAR` data type. If the symbol `_UNICODE` is defined for a build of your program, `TCHAR` is defined as type **`wchar_t`**, a 16-bit character encoding type. Otherwise, `TCHAR` is defined as **`char`**, the normal 8-bit character encoding. Therefore, under Unicode, a `CString` is composed of 16-bit characters. Without Unicode, it is composed of characters of type **`char`**. +`CString` is based on the `TCHAR` data type. If the symbol `_UNICODE` is defined for a build of your program, `TCHAR` is defined as type **`wchar_t`**, a 16-bit character encoding type. Otherwise, `TCHAR` is defined as **`char`**, the normal 8-bit character encoding. Therefore, under Unicode, a `CString` is composed of 16-bit characters. Without Unicode, it's composed of characters of type **`char`**. To complete Unicode programming of your application, you must also: - Use the `_T` macro to conditionally code literal strings to be portable to Unicode. -- When you pass strings, pay attention to whether function arguments require a length in characters or a length in bytes. The difference is important if you are using Unicode strings. +- When you pass strings, pay attention to whether function arguments require a length in characters or a length in bytes. The difference is important if you're using Unicode strings. - Use portable versions of the C run-time string-handling functions. @@ -77,9 +80,9 @@ The [Run-Time Library Reference](../c-runtime-library/c-run-time-library-referen The class library is also enabled for multibyte character sets, but only for double-byte character sets (DBCS). -In a multibyte character set, a character can be one or two bytes wide. If it is two bytes wide, its first byte is a special "lead byte" that is chosen from a particular range, depending on which code page is in use. Taken together, the lead and "trail bytes" specify a unique character encoding. +In a multibyte character set, a character can be one or 2 bytes wide. If it's 2 bytes wide, its first byte is a special "lead byte" that is chosen from a particular range, depending on which code page is in use. Taken together, the lead and "trail bytes" specify a unique character encoding. -If the symbol `_MBCS` is defined for a build of your program, type `TCHAR`, on which `CString` is based, maps to **`char`**. It is up to you to determine which bytes in a `CString` are lead bytes and which are trail bytes. The C run-time library supplies functions to help you determine this. +If the symbol `_MBCS` is defined for a build of your program, type `TCHAR`, on which `CString` is based, maps to **`char`**. It's up to you to determine which bytes in a `CString` are lead bytes and which are trail bytes. The C run-time library supplies functions to help you determine this. Under DBCS, a given string can contain all single-byte ANSI characters, all double-byte characters, or a combination of the two. These possibilities require special care in parsing strings. This includes `CString` objects. diff --git a/docs/atl-mfc-shared/using-cstring.md b/docs/atl-mfc-shared/using-cstring.md index c1bc670b80..f6a99466fc 100644 --- a/docs/atl-mfc-shared/using-cstring.md +++ b/docs/atl-mfc-shared/using-cstring.md @@ -5,17 +5,17 @@ ms.date: "06/18/2018" helpviewer_keywords: ["CString objects, C++ string manipulation", "CString objects, reference counting", "CString class (Visual C++)"] ms.assetid: ed018aaf-8b10-46f9-828c-f9c092dc7609 --- -# Using CString +# Using `CString` -The topics in this section describe how to program with `CString`. For reference documentation about the `CString` class, see the documentation for [CStringT](../atl-mfc-shared/reference/cstringt-class.md). +The topics in this section describe how to program with `CString`. For reference documentation about the `CString` class, see the documentation for [`CStringT`](../atl-mfc-shared/reference/cstringt-class.md). To use `CString`, include the `atlstr.h` header. -The `CString`, `CStringA`, and `CStringW` classes are specializations of a class template called [CStringT](../atl-mfc-shared/reference/cstringt-class.md) based on the type of character data they support. +The `CString`, `CStringA`, and `CStringW` classes are specializations of a class template called [`CStringT`](../atl-mfc-shared/reference/cstringt-class.md) based on the type of character data they support. A `CStringW` object contains the **`wchar_t`** type and supports Unicode strings. A `CStringA` object contains the **`char`** type, and supports single-byte and multi-byte (MBCS) strings. A `CString` object supports either the **`char`** type or the **`wchar_t`** type, depending on whether the MBCS symbol or the UNICODE symbol is defined at compile time. -A `CString` object keeps character data in a `CStringData` object. `CString` accepts NULL-terminated C-style strings. `CString` tracks the string length for faster performance, but it also retains the NULL character in the stored character data to support conversion to LPCWSTR. `CString` includes the null terminator when it exports a C-style string. You can insert a NULL at other locations in a `CString`, but it may produce unexpected results. +A `CString` object keeps character data in a `CStringData` object. `CString` accepts NULL-terminated C-style strings. `CString` tracks the string length for faster performance, but it also retains the `NULL` character in the stored character data to support conversion to `LPCWSTR`. `CString` includes the null terminator when it exports a C-style string. You can insert a `NULL` at other locations in a `CString`, but it may produce unexpected results. The following set of string classes can be used without linking an MFC library, with or without CRT support: `CAtlString`, `CAtlStringA`, and `CAtlStringW`. @@ -36,7 +36,7 @@ int main() { ## In This Section -[Basic CString Operations](../atl-mfc-shared/basic-cstring-operations.md)
+[Basic `CString` Operations](../atl-mfc-shared/basic-cstring-operations.md)
Describes basic `CString` operations, including creating objects from C literal strings, accessing individual characters in a `CString`, concatenating two objects, and comparing `CString` objects. [String Data Management](../atl-mfc-shared/string-data-management.md)
@@ -48,24 +48,24 @@ Explains how `CString` objects are used. [CString Operations Relating to C-Style Strings](../atl-mfc-shared/cstring-operations-relating-to-c-style-strings.md)
Describes manipulating the contents of a `CString` object like a C-style null-terminated string. -[Allocating and Releasing Memory for a BSTR](../atl-mfc-shared/allocating-and-releasing-memory-for-a-bstr.md)
-Discusses using memory for a BSTR and COM objects. +[Allocating and Releasing Memory for a `BSTR`](../atl-mfc-shared/allocating-and-releasing-memory-for-a-bstr.md)
+Discusses using memory for a `BSTR` and COM objects. [CString Exception Cleanup](../atl-mfc-shared/cstring-exception-cleanup.md)
Explains that explicit cleanup in MFC 3.0 and later is no longer necessary. [CString Argument Passing](../atl-mfc-shared/cstring-argument-passing.md)
-Explains how to pass CString objects to functions and how to return `CString` objects from functions. +Explains how to pass `CString` objects to functions and how to return `CString` objects from functions. [Unicode and Multibyte Character Set (MBCS) Support](../atl-mfc-shared/unicode-and-multibyte-character-set-mbcs-support.md)
Discusses how MFC is enabled for Unicode and MBCS support. ## Reference -[CStringT](../atl-mfc-shared/reference/cstringt-class.md)
+[`CStringT`](../atl-mfc-shared/reference/cstringt-class.md)
Provides reference information about the `CStringT` class. -[CSimpleStringT Class](../atl-mfc-shared/reference/csimplestringt-class.md)
+[`CSimpleStringT` Class](../atl-mfc-shared/reference/csimplestringt-class.md)
Provides reference information about the `CSimpleStringT` class. ## Related Sections diff --git a/docs/atl/active-template-library-atl-concepts.md b/docs/atl/active-template-library-atl-concepts.md index 1502b2c5cc..bf9f677b9a 100644 --- a/docs/atl/active-template-library-atl-concepts.md +++ b/docs/atl/active-template-library-atl-concepts.md @@ -28,7 +28,7 @@ Describes the implementation and creation of collections and enumerators in ATL. [Composite Control Fundamentals](atl-composite-control-fundamentals.md)
Provides step-by-step instructions for creating a composite control. A composite control is a type of ActiveX control that can contain other ActiveX controls or Windows controls. -[ATL Control Containment FAQ](atl-control-containment-faq.md)
+[ATL Control Containment FAQ](atl-control-containment-faq.yml)
Covers the fundamental questions related to hosting controls with ATL. [ATL COM Property Pages](atl-com-property-pages.md)
diff --git a/docs/atl/adding-a-control-atl-tutorial-part-2.md b/docs/atl/adding-a-control-atl-tutorial-part-2.md index bc613dd306..64913399d1 100644 --- a/docs/atl/adding-a-control-atl-tutorial-part-2.md +++ b/docs/atl/adding-a-control-atl-tutorial-part-2.md @@ -109,7 +109,7 @@ Now you can build the control to see it in action. Next, you'll add a custom property to the control. -[Back to Step 1](../atl/creating-the-project-atl-tutorial-part-1.md) | [On to Step 3](../atl/adding-a-property-to-the-control-atl-tutorial-part-3.md) +[Back to Step 1](../atl/creating-the-project-atl-tutorial-part-1.md) \| [On to Step 3](../atl/adding-a-property-to-the-control-atl-tutorial-part-3.md) ## See also diff --git a/docs/atl/adding-a-property-page-atl-tutorial-part-6.md b/docs/atl/adding-a-property-page-atl-tutorial-part-6.md index 2422ad5958..77ab6f873a 100644 --- a/docs/atl/adding-a-property-page-atl-tutorial-part-6.md +++ b/docs/atl/adding-a-property-page-atl-tutorial-part-6.md @@ -142,7 +142,7 @@ The **Apply** button is initially disabled. Start typing a value in the **Sides* Next, you will put your control on a Web page. -[Back to Step 5](../atl/adding-an-event-atl-tutorial-part-5.md) | [On to Step 7](../atl/putting-the-control-on-a-web-page-atl-tutorial-part-7.md) +[Back to Step 5](../atl/adding-an-event-atl-tutorial-part-5.md) \| [On to Step 7](../atl/putting-the-control-on-a-web-page-atl-tutorial-part-7.md) ## See also diff --git a/docs/atl/adding-a-property-to-the-control-atl-tutorial-part-3.md b/docs/atl/adding-a-property-to-the-control-atl-tutorial-part-3.md index 5ddcc5edb6..eae5f195dd 100644 --- a/docs/atl/adding-a-property-to-the-control-atl-tutorial-part-3.md +++ b/docs/atl/adding-a-property-to-the-control-atl-tutorial-part-3.md @@ -57,7 +57,7 @@ The `get_Sides` method returns the current value of the `Sides` property through You now have a property called `Sides`. In the next step, you will change the drawing code to use it. -[Back to Step 2](../atl/adding-a-control-atl-tutorial-part-2.md) | [On to Step 4](../atl/changing-the-drawing-code-atl-tutorial-part-4.md) +[Back to Step 2](../atl/adding-a-control-atl-tutorial-part-2.md) \| [On to Step 4](../atl/changing-the-drawing-code-atl-tutorial-part-4.md) ## See also diff --git a/docs/atl/adding-an-event-atl-tutorial-part-5.md b/docs/atl/adding-an-event-atl-tutorial-part-5.md index 7e5f75567b..18306b8df0 100644 --- a/docs/atl/adding-an-event-atl-tutorial-part-5.md +++ b/docs/atl/adding-an-event-atl-tutorial-part-5.md @@ -149,7 +149,7 @@ Now try out your events. Build the control and start the ActiveX Control Test Co Next, you will add a property page. -[Back to Step 4](../atl/changing-the-drawing-code-atl-tutorial-part-4.md) | [On to Step 6](../atl/adding-a-property-page-atl-tutorial-part-6.md) +[Back to Step 4](../atl/changing-the-drawing-code-atl-tutorial-part-4.md) \| [On to Step 6](../atl/adding-a-property-page-atl-tutorial-part-6.md) ## See also diff --git a/docs/atl/atl-collection-classes.md b/docs/atl/atl-collection-classes.md index e8a60d3ece..7545e6d690 100644 --- a/docs/atl/atl-collection-classes.md +++ b/docs/atl/atl-collection-classes.md @@ -97,7 +97,7 @@ For a list of the CTraits classes, see [Collection Classes](../atl/collection-cl The following diagram shows the class hierarchy for the CTraits classes. -![Traits hierarchy for collection classes](../atl/media/vctraitscollectionclasseshierarchy.gif "Traits hierarchy for collection classes") +![Diagram that shows the traits hierarchy for collection classes.](../atl/media/vctraitscollectionclasseshierarchy.gif "Traits hierarchy for collection classes") ## Collection Classes Samples diff --git a/docs/atl/atl-connection-points.md b/docs/atl/atl-connection-points.md index 1567d22930..9bad34db0b 100644 --- a/docs/atl/atl-connection-points.md +++ b/docs/atl/atl-connection-points.md @@ -9,7 +9,7 @@ ms.assetid: 17d76165-5f83-4f95-b36d-483821c247a1 A connectable object is one that supports outgoing interfaces. An outgoing interface allows the object to communicate with a client. For each outgoing interface, the connectable object exposes a connection point. Each outgoing interface is implemented by a client on an object called a sink. -![Connection points](../atl/media/vc2zw31.gif "Connection points") +![Diagram that shows the connection points on a client object and a connectable object.](../atl/media/vc2zw31.gif "Connection points") Each connection point supports the [IConnectionPoint](/windows/win32/api/ocidl/nn-ocidl-iconnectionpoint) interface. The connectable object exposes its connection points to the client through the [IConnectionPointContainer](/windows/win32/api/ocidl/nn-ocidl-iconnectionpointcontainer) interface. diff --git a/docs/atl/atl-control-containment-faq.md b/docs/atl/atl-control-containment-faq.md deleted file mode 100644 index 34ce86293c..0000000000 --- a/docs/atl/atl-control-containment-faq.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -description: "Learn more about: ATL Control Containment FAQ" -title: "ATL Control Containment FAQ" -ms.date: "11/04/2016" -helpviewer_keywords: ["hosting controls using ATL", "ActiveX control containers [C++], ATL control hosting", "ATL, hosting ActiveX controls", "ActiveX controls [C++], hosting", "controls [ATL]"] -ms.assetid: d4bdfbe0-82ca-4f2f-bb95-cb89bdcc9b53 ---- -# ATL Control Containment FAQ - -## Which ATL Classes Facilitate ActiveX Control Containment? - -ATL's control-hosting code doesn't require you to use any ATL classes; you can simply create an **"AtlAxWin80"** window and use the control-hosting API if necessary (for more information, see **What Is the ATL Control-Hosting API**. However, the following classes make the containment features easier to use. - -|Class|Description| -|-----------|-----------------| -|[CAxWindow](../atl/reference/caxwindow-class.md)|Wraps an **"AtlAxWin80"** window, providing methods for creating the window, creating a control and/or attaching a control to the window, and retrieving interface pointers on the host object.| -|[CAxWindow2T](../atl/reference/caxwindow2t-class.md)|Wraps an **"AtlAxWinLic80"** window, providing methods for creating the window, creating a control and/or attaching a licensed control to the window, and retrieving interface pointers on the host object.| -|[CComCompositeControl](../atl/reference/ccomcompositecontrol-class.md)|Acts as a base class for ActiveX control classes based on a dialog resource. Such controls can contain other ActiveX controls.| -|[CAxDialogImpl](../atl/reference/caxdialogimpl-class.md)|Acts as a base class for dialog classes based on a dialog resource. Such dialogs can contain ActiveX controls.| -|[CWindow](../atl/reference/cwindow-class.md)|Provides a method, [GetDlgControl](../atl/reference/cwindow-class.md#getdlgcontrol), that will return an interface pointer on a control, given the ID of its host window. In addition, the Windows API wrappers exposed by `CWindow` generally make window management easier.| - -## What Is the ATL Control-Hosting API? - -ATL's control-hosting API is the set of functions that allows any window to act as an ActiveX control container. These functions can be statically or dynamically linked into your project since they are available as source code and exposed by ATL90.dll. The control-hosting functions are listed in the table below. - -|Function|Description| -|--------------|-----------------| -|[AtlAxAttachControl](reference/composite-control-global-functions.md#atlaxattachcontrol)|Creates a host object, connects it to the supplied window, then attaches an existing control.| -|[AtlAxCreateControl](reference/composite-control-global-functions.md#atlaxcreatecontrol)|Creates a host object, connects it to the supplied window, then loads a control.| -|[AtlAxCreateControlLic](reference/composite-control-global-functions.md#atlaxcreatecontrollic)|Creates a licensed ActiveX control, initializes it, and hosts it in the specified window, similar to [AtlAxCreateControl](reference/composite-control-global-functions.md#atlaxcreatecontrol).| -|[AtlAxCreateControlEx](reference/composite-control-global-functions.md#atlaxcreatecontrolex)|Creates a host object, connects it to the supplied window, then loads a control (also allows event sinks to be set up).| -|[AtlAxCreateControlLicEx](reference/composite-control-global-functions.md#atlaxcreatecontrollicex)|Creates a licensed ActiveX control, initializes it, and hosts it in the specified window, similar to [AtlAxCreateControlLic](reference/composite-control-global-functions.md#atlaxcreatecontrollic).| -|[AtlAxCreateDialog](reference/composite-control-global-functions.md#atlaxcreatedialog)|Creates a modeless dialog box from a dialog resource and returns the window handle.| -|[AtlAxDialogBox](reference/composite-control-global-functions.md#atlaxdialogbox)|Creates a modal dialog box from a dialog resource.| -|[AtlAxGetControl](reference/composite-control-global-functions.md#atlaxgetcontrol)|Returns the **IUnknown** interface pointer of the control hosted in a window.| -|[AtlAxGetHost](reference/composite-control-global-functions.md#atlaxgethost)|Returns the **IUnknown** interface pointer of the host object connected to a window.| -|[AtlAxWinInit](reference/composite-control-global-functions.md#atlaxwininit)|Initializes the control-hosting code.| -|[AtlAxWinTerm](reference/composite-control-global-functions.md#atlaxwinterm)|Uninitializes the control-hosting code.| - -The `HWND` parameters in the first three functions must be an existing window of (almost) any type. If you call any of these three functions explicitly (typically, you won't have to), do not pass a handle to a window that's already acting as a host (if you do, the existing host object won't be freed). - -The first seven functions call [AtlAxWinInit](reference/composite-control-global-functions.md#atlaxwininit) implicitly. - -> [!NOTE] -> The control-hosting API forms the foundation of ATL's support for ActiveX control containment. However, there is usually little need to call these functions directly if you take advantage of or make full use of ATL's wrapper classes. For more information, see [Which ATL Classes Facilitate ActiveX Control Containment](#which-atl-classes-facilitate-activex-control-containment). - -## What Is AtlAxWin100? - -`AtlAxWin100` is the name of a window class that helps provide ATL's control-hosting functionality. When you create an instance of this class, the window procedure will automatically use the control-hosting API to create a host object associated with the window and load it with the control that you specify as the title of the window. - -## When Do I Need to Call AtlAxWinInit? - -[AtlAxWinInit](reference/composite-control-global-functions.md#atlaxwininit) registers the **"AtlAxWin80"** window class (plus a couple of custom window messages) so this function must be called before you try to create a host window. However, you don't always need to call this function explicitly, since the hosting APIs (and the classes that use them) often call this function for you. There is no harm in calling this function more than once. - -## What Is a Host Object? - -A host object is a COM object that represents the ActiveX control container supplied by ATL for a particular window. The host object subclasses the container window so that it can reflect messages to the control, it provides the necessary container interfaces to be used by the control, and it exposes the [IAxWinHostWindow](../atl/reference/iaxwinhostwindow-interface.md) and [IAxWinAmbientDispatch](../atl/reference/iaxwinambientdispatch-interface.md) interfaces to allow you to configure the environment of the control. - -You can use the host object to set the ambient properties of the container. - -## Can I Host More Than One Control in a Single Window? - -It is not possible to host more than one control in a single ATL host window. Each host window is designed to hold exactly one control at a time (this allows for a simple mechanism for handling message reflection and per-control ambient properties). However, if you need the user to see multiple controls in a single window, it's a simple matter to create multiple host windows as children of that window. - -## Can I Reuse a Host Window? - -It is not recommended that you reuse host windows. To ensure the robustness of your code, you should tie the lifetime of your host window to the lifetime of a single control. - -## When Do I Need to Call AtlAxWinTerm? - -[AtlAxWinTerm](reference/composite-control-global-functions.md#atlaxwinterm) unregisters the **"AtlAxWin80"** window class. You should call this function (if you no longer need to create host windows) after all existing host windows have been destroyed. If you don't call this function, the window class will be unregistered automatically when the process terminates. - -## Hosting ActiveX Controls Using ATL AXHost - -The sample in this section shows how to create AXHost and how to host an ActiveX control using various ATL functions. It also shows how to access the control and sink events (using [IDispEventImpl](../atl/reference/idispeventimpl-class.md)) from the control that is hosted. The sample hosts the Calendar control in a main window or in a child window. - -Notice the definition of the `USE_METHOD` symbol. You can change the value of this symbol to vary between 1 and 8. The value of the symbol determines how the control will be created: - -- For even-numbered values of `USE_METHOD`, the call to create the host subclasses a window and converts it into a control host. For odd-numbered values, the code creates a child window that acts as a host. - -- For values of `USE_METHOD` between 1 and 4, access to the control and sinking of events are accomplished in the call that also creates the host. Values between 5 and 8 query the host for interfaces and hook the sink. - -Here's a summary: - -|USE_METHOD|Host|Control access and event sinking|Function demonstrated| -|-----------------|----------|--------------------------------------|---------------------------| -|1|Child window|One step|CreateControlLicEx| -|2|Main window|One step|AtlAxCreateControlLicEx| -|3|Child window|One step|CreateControlEx| -|4|Main window|One step|AtlAxCreateControlEx| -|5|Child window|Multiple steps|CreateControlLic| -|6|Main window|Multiple steps|AtlAxCreateControlLic| -|7|Child window|Multiple steps|CreateControl| -|8|Main window|Multiple steps|AtlAxCreateControl| - -[!code-cpp[NVC_ATL_AxHost#1](../atl/codesnippet/cpp/hosting-activex-controls-using-atl-axhost_1.cpp)] - -## See also - -[Control Containment FAQ](../atl/atl-control-containment-faq.md)
-[AtlAxCreateControl](reference/composite-control-global-functions.md#atlaxcreatecontrol)
-[AtlAxCreateControlEx](reference/composite-control-global-functions.md#atlaxcreatecontrolex)
-[AtlAxCreateControlLic](reference/composite-control-global-functions.md#atlaxcreatecontrollic)
-[AtlAxCreateControlLicEx](reference/composite-control-global-functions.md#atlaxcreatecontrolex)
-[CAxWindow2T Class](../atl/reference/caxwindow2t-class.md)
-[IAxWinHostWindowLic Interface](../atl/reference/iaxwinhostwindowlic-interface.md) diff --git a/docs/atl/atl-control-containment-faq.yml b/docs/atl/atl-control-containment-faq.yml new file mode 100644 index 0000000000..51c1ecd623 --- /dev/null +++ b/docs/atl/atl-control-containment-faq.yml @@ -0,0 +1,122 @@ +### YamlMime:FAQ +metadata: + description: "Learn more about: ATL Control Containment FAQ" + title: "ATL Control Containment FAQ" + ms.date: "11/04/2016" + helpviewer_keywords: ["hosting controls using ATL", "ActiveX control containers [C++], ATL control hosting", "ATL, hosting ActiveX controls", "ActiveX controls [C++], hosting", "controls [ATL]"] + ms.assetid: d4bdfbe0-82ca-4f2f-bb95-cb89bdcc9b53 + ms.topic: faq +title: ATL Control Containment FAQ +summary: | + +sections: + - name: Ignored + questions: + - question: | + Which ATL Classes Facilitate ActiveX Control Containment? + answer: | + ATL's control-hosting code doesn't require you to use any ATL classes; you can simply create an **"AtlAxWin80"** window and use the control-hosting API if necessary (for more information, see **What Is the ATL Control-Hosting API**. However, the following classes make the containment features easier to use. + + |Class|Description| + |-----------|-----------------| + |[CAxWindow](../atl/reference/caxwindow-class.md)|Wraps an **"AtlAxWin80"** window, providing methods for creating the window, creating a control and/or attaching a control to the window, and retrieving interface pointers on the host object.| + |[CAxWindow2T](../atl/reference/caxwindow2t-class.md)|Wraps an **"AtlAxWinLic80"** window, providing methods for creating the window, creating a control and/or attaching a licensed control to the window, and retrieving interface pointers on the host object.| + |[CComCompositeControl](../atl/reference/ccomcompositecontrol-class.md)|Acts as a base class for ActiveX control classes based on a dialog resource. Such controls can contain other ActiveX controls.| + |[CAxDialogImpl](../atl/reference/caxdialogimpl-class.md)|Acts as a base class for dialog classes based on a dialog resource. Such dialogs can contain ActiveX controls.| + |[CWindow](../atl/reference/cwindow-class.md)|Provides a method, [GetDlgControl](../atl/reference/cwindow-class.md#getdlgcontrol), that will return an interface pointer on a control, given the ID of its host window. In addition, the Windows API wrappers exposed by `CWindow` generally make window management easier.| + + - question: | + What Is the ATL Control-Hosting API? + answer: | + ATL's control-hosting API is the set of functions that allows any window to act as an ActiveX control container. These functions can be statically or dynamically linked into your project since they are available as source code and exposed by ATL90.dll. The control-hosting functions are listed in the table below. + + |Function|Description| + |--------------|-----------------| + |[AtlAxAttachControl](reference/composite-control-global-functions.md#atlaxattachcontrol)|Creates a host object, connects it to the supplied window, then attaches an existing control.| + |[AtlAxCreateControl](reference/composite-control-global-functions.md#atlaxcreatecontrol)|Creates a host object, connects it to the supplied window, then loads a control.| + |[AtlAxCreateControlLic](reference/composite-control-global-functions.md#atlaxcreatecontrollic)|Creates a licensed ActiveX control, initializes it, and hosts it in the specified window, similar to [AtlAxCreateControl](reference/composite-control-global-functions.md#atlaxcreatecontrol).| + |[AtlAxCreateControlEx](reference/composite-control-global-functions.md#atlaxcreatecontrolex)|Creates a host object, connects it to the supplied window, then loads a control (also allows event sinks to be set up).| + |[AtlAxCreateControlLicEx](reference/composite-control-global-functions.md#atlaxcreatecontrollicex)|Creates a licensed ActiveX control, initializes it, and hosts it in the specified window, similar to [AtlAxCreateControlLic](reference/composite-control-global-functions.md#atlaxcreatecontrollic).| + |[AtlAxCreateDialog](reference/composite-control-global-functions.md#atlaxcreatedialog)|Creates a modeless dialog box from a dialog resource and returns the window handle.| + |[AtlAxDialogBox](reference/composite-control-global-functions.md#atlaxdialogbox)|Creates a modal dialog box from a dialog resource.| + |[AtlAxGetControl](reference/composite-control-global-functions.md#atlaxgetcontrol)|Returns the **IUnknown** interface pointer of the control hosted in a window.| + |[AtlAxGetHost](reference/composite-control-global-functions.md#atlaxgethost)|Returns the **IUnknown** interface pointer of the host object connected to a window.| + |[AtlAxWinInit](reference/composite-control-global-functions.md#atlaxwininit)|Initializes the control-hosting code.| + |[AtlAxWinTerm](reference/composite-control-global-functions.md#atlaxwinterm)|Uninitializes the control-hosting code.| + + The `HWND` parameters in the first three functions must be an existing window of (almost) any type. If you call any of these three functions explicitly (typically, you won't have to), do not pass a handle to a window that's already acting as a host (if you do, the existing host object won't be freed). + + The first seven functions call [AtlAxWinInit](reference/composite-control-global-functions.md#atlaxwininit) implicitly. + + > [!NOTE] + > The control-hosting API forms the foundation of ATL's support for ActiveX control containment. However, there is usually little need to call these functions directly if you take advantage of or make full use of ATL's wrapper classes. For more information, see [Which ATL Classes Facilitate ActiveX Control Containment](#which-atl-classes-facilitate-activex-control-containment-). + + - question: | + What Is AtlAxWin100? + answer: | + `AtlAxWin100` is the name of a window class that helps provide ATL's control-hosting functionality. When you create an instance of this class, the window procedure will automatically use the control-hosting API to create a host object associated with the window and load it with the control that you specify as the title of the window. + + - question: | + When Do I Need to Call AtlAxWinInit? + answer: | + [AtlAxWinInit](reference/composite-control-global-functions.md#atlaxwininit) registers the **"AtlAxWin80"** window class (plus a couple of custom window messages) so this function must be called before you try to create a host window. However, you don't always need to call this function explicitly, since the hosting APIs (and the classes that use them) often call this function for you. There is no harm in calling this function more than once. + + - question: | + What Is a Host Object? + answer: | + A host object is a COM object that represents the ActiveX control container supplied by ATL for a particular window. The host object subclasses the container window so that it can reflect messages to the control, it provides the necessary container interfaces to be used by the control, and it exposes the [IAxWinHostWindow](../atl/reference/iaxwinhostwindow-interface.md) and [IAxWinAmbientDispatch](../atl/reference/iaxwinambientdispatch-interface.md) interfaces to allow you to configure the environment of the control. + + You can use the host object to set the ambient properties of the container. + + - question: | + Can I Host More Than One Control in a Single Window? + answer: | + It is not possible to host more than one control in a single ATL host window. Each host window is designed to hold exactly one control at a time (this allows for a simple mechanism for handling message reflection and per-control ambient properties). However, if you need the user to see multiple controls in a single window, it's a simple matter to create multiple host windows as children of that window. + + - question: | + Can I Reuse a Host Window? + answer: | + It is not recommended that you reuse host windows. To ensure the robustness of your code, you should tie the lifetime of your host window to the lifetime of a single control. + + - question: | + When Do I Need to Call AtlAxWinTerm? + answer: | + [AtlAxWinTerm](reference/composite-control-global-functions.md#atlaxwinterm) unregisters the **"AtlAxWin80"** window class. You should call this function (if you no longer need to create host windows) after all existing host windows have been destroyed. If you don't call this function, the window class will be unregistered automatically when the process terminates. + + - question: | + Hosting ActiveX Controls Using ATL AXHost + answer: | + The sample in this section shows how to create AXHost and how to host an ActiveX control using various ATL functions. It also shows how to access the control and sink events (using [IDispEventImpl](../atl/reference/idispeventimpl-class.md)) from the control that is hosted. The sample hosts the Calendar control in a main window or in a child window. + + Notice the definition of the `USE_METHOD` symbol. You can change the value of this symbol to vary between 1 and 8. The value of the symbol determines how the control will be created: + + - For even-numbered values of `USE_METHOD`, the call to create the host subclasses a window and converts it into a control host. For odd-numbered values, the code creates a child window that acts as a host. + + - For values of `USE_METHOD` between 1 and 4, access to the control and sinking of events are accomplished in the call that also creates the host. Values between 5 and 8 query the host for interfaces and hook the sink. + + Here's a summary: + + |USE_METHOD|Host|Control access and event sinking|Function demonstrated| + |-----------------|----------|--------------------------------------|---------------------------| + |1|Child window|One step|CreateControlLicEx| + |2|Main window|One step|AtlAxCreateControlLicEx| + |3|Child window|One step|CreateControlEx| + |4|Main window|One step|AtlAxCreateControlEx| + |5|Child window|Multiple steps|CreateControlLic| + |6|Main window|Multiple steps|AtlAxCreateControlLic| + |7|Child window|Multiple steps|CreateControl| + |8|Main window|Multiple steps|AtlAxCreateControl| + + [!code-cpp[NVC_ATL_AxHost#1](../atl/codesnippet/cpp/hosting-activex-controls-using-atl-axhost_1.cpp)] + +additionalContent: | + + ## See also + + [Control Containment FAQ](../atl/atl-control-containment-faq.yml)
+ [AtlAxCreateControl](reference/composite-control-global-functions.md#atlaxcreatecontrol)
+ [AtlAxCreateControlEx](reference/composite-control-global-functions.md#atlaxcreatecontrolex)
+ [AtlAxCreateControlLic](reference/composite-control-global-functions.md#atlaxcreatecontrollic)
+ [AtlAxCreateControlLicEx](reference/composite-control-global-functions.md#atlaxcreatecontrolex)
+ [CAxWindow2T Class](../atl/reference/caxwindow2t-class.md)
+ [IAxWinHostWindowLic Interface](../atl/reference/iaxwinhostwindowlic-interface.md) diff --git a/docs/atl/atl-utilities-reference.md b/docs/atl/atl-utilities-reference.md index 1fe2da4303..b332716189 100644 --- a/docs/atl/atl-utilities-reference.md +++ b/docs/atl/atl-utilities-reference.md @@ -1,8 +1,7 @@ --- -description: "Learn more about: ATL utilities reference" title: "ATL utilities reference" +description: "Learn more about: ATL utilities reference" ms.date: "11/04/2016" -ms.assetid: dd8a2888-34f4-461e-9bf4-834218f9b95b --- # ATL utilities reference @@ -47,8 +46,7 @@ ATL provides code for manipulating paths and URLs in the form of [CPathT](../atl | [AtlIsUnsafeUrlChar](../atl/reference/atl-http-utility-functions.md#atlisunsafeurlchar) | Call this function to find out whether a character is safe for use in a URL. | | [AtlUnescapeUrl](../atl/reference/atl-http-utility-functions.md#atlunescapeurl) | Call this function to convert escaped characters back to their original values. | | [SystemTimeToHttpDate](../atl/reference/atl-http-utility-functions.md#systemtimetohttpdate) | Call this function to convert a system time to a string in a format suitable for using in HTTP headers. | -| [ATLPath::AddBackslash](../atl/reference/atl-path-functions.md#addbackslash) | This function is an overloaded wrapper for [PathAddBackslash](/windows/desktop/api/shlwapi/nf-shlwapi-pathaddbackslasha | -| ). | +| [ATLPath::AddBackslash](../atl/reference/atl-path-functions.md#addbackslash) | This function is an overloaded wrapper for [PathAddBackslash](/windows/win32/api/shlwapi/nf-shlwapi-pathaddbackslasha). | | [ATLPath::AddExtension](../atl/reference/atl-path-functions.md#addextension) | This function is an overloaded wrapper for [PathAddExtension](/windows/win32/api/shlwapi/nf-shlwapi-pathaddextensionw). | | [ATLPath::Append](../atl/reference/atl-path-functions.md#append) | This function is an overloaded wrapper for [PathAppend](/windows/win32/api/shlwapi/nf-shlwapi-pathappendw). | | [ATLPath::BuildRoot](../atl/reference/atl-path-functions.md#buildroot) | This function is an overloaded wrapper for [PathBuildRoot](/windows/win32/api/shlwapi/nf-shlwapi-pathbuildrootw). | @@ -87,5 +85,5 @@ ATL provides code for manipulating paths and URLs in the form of [CPathT](../atl ## See also -[Concepts](../atl/active-template-library-atl-concepts.md)
+[Concepts](../atl/active-template-library-atl-concepts.md)\ [ATL COM desktop components](../atl/atl-com-desktop-components.md) diff --git a/docs/atl/changing-the-drawing-code-atl-tutorial-part-4.md b/docs/atl/changing-the-drawing-code-atl-tutorial-part-4.md index f84b417b34..ae8149664e 100644 --- a/docs/atl/changing-the-drawing-code-atl-tutorial-part-4.md +++ b/docs/atl/changing-the-drawing-code-atl-tutorial-part-4.md @@ -151,7 +151,7 @@ After adding `FireViewChange`, rebuild and try the control again in the ActiveX In the next step, you will add an event. -[Back to Step 3](../atl/adding-a-property-to-the-control-atl-tutorial-part-3.md) | [On to Step 5](../atl/adding-an-event-atl-tutorial-part-5.md) +[Back to Step 3](../atl/adding-a-property-to-the-control-atl-tutorial-part-3.md) \| [On to Step 5](../atl/adding-an-event-atl-tutorial-part-5.md) ## See also diff --git a/docs/atl/control-containment-classes.md b/docs/atl/control-containment-classes.md index 836054b9dc..1446101b69 100644 --- a/docs/atl/control-containment-classes.md +++ b/docs/atl/control-containment-classes.md @@ -20,7 +20,7 @@ The following classes provide containment support for hosting controls: ## Related Articles -[ATL Control Containment FAQ](../atl/atl-control-containment-faq.md) +[ATL Control Containment FAQ](../atl/atl-control-containment-faq.yml) ## See also diff --git a/docs/atl/example-implementing-a-property-page.md b/docs/atl/example-implementing-a-property-page.md index ef24851d29..c6e44f85f6 100644 --- a/docs/atl/example-implementing-a-property-page.md +++ b/docs/atl/example-implementing-a-property-page.md @@ -7,7 +7,7 @@ ms.assetid: c30b67fe-ce08-4249-ae29-f3060fa8d61e --- # Example: Implementing a Property Page -::: moniker range="msvc-160" +::: moniker range=">=msvc-160" The ATL Property Page wizard is not available in Visual Studio 2019 and later. @@ -60,7 +60,7 @@ Click **OK** to have the wizard generate your property page. Now that your property page has been generated, you'll need to add a few controls to the dialog resource representing your page. Add an edit box, a static text control, and a check box and set their IDs as shown below: -![Editing a dialog resource](../atl/media/ppgresourcelabeled.gif "Editing a dialog resource") +![Screenshot of a dialog resource in the visual editor.](../atl/media/ppgresourcelabeled.gif "Editing a dialog resource") These controls will be used to display the file name of the document and its read-only status. diff --git a/docs/atl/fundamentals-of-atl-com-objects.md b/docs/atl/fundamentals-of-atl-com-objects.md index 0d17dbab7e..afc7adb434 100644 --- a/docs/atl/fundamentals-of-atl-com-objects.md +++ b/docs/atl/fundamentals-of-atl-com-objects.md @@ -9,7 +9,7 @@ ms.assetid: 0f9c9d98-cc28-45da-89ac-dc94cee422fe The following illustration depicts the relationship among the classes and interfaces that are used to define an ATL COM object. -![ATL structure](../atl/media/vc307y1.gif "ATL structure") +![Diagram of the classes and interfaces used to define an A T L object.](../atl/media/vc307y1.gif "ATL structure") > [!NOTE] > This diagram shows that `CComObject` is derived from `CYourClass` whereas `CComAggObject` and `CComPolyObject` include `CYourClass` as a member variable. diff --git a/docs/atl/identifying-the-elements-of-the-dhtml-control-project.md b/docs/atl/identifying-the-elements-of-the-dhtml-control-project.md index 2a88218b4a..dcf9ebc388 100644 --- a/docs/atl/identifying-the-elements-of-the-dhtml-control-project.md +++ b/docs/atl/identifying-the-elements-of-the-dhtml-control-project.md @@ -19,7 +19,7 @@ A DHTML control is similar to any ATL control, except: The following graphic illustrates the relationship between your DLL, the DHTML control, the Web browser, and the HTML resource. -![Elements of a DHTML control project](../atl/media/vc52en1.gif "Elements of a DHTML control project") +![Diagram of the elements of a DHTML control project.](../atl/media/vc52en1.gif "Elements of a DHTML control project") > [!NOTE] > The names on this graphic are placeholders. The names of your HTML resource and the interfaces exposed on your control are based on the names you assign them in the ATL Control Wizard. @@ -40,7 +40,7 @@ In this graphic, the elements are: The ATL Control Wizard generates a control with default code in both the HTML resource and the .cpp file. You can compile and run the control as generated by the wizard, and then view the control in either the Web browser or the ActiveX Control Test Container. The picture below shows the default ATL DHTML control with three buttons displayed in Test Container: -![ATL DHTML control](../atl/media/vc52en2.gif "ATL DHTML control") +![ATL DHTML control.](../atl/media/vc52en2.gif "ATL DHTML control") See [Creating an ATL DHTML Control](../atl/creating-an-atl-dhtml-control.md) to get started building a DHTML control. See [Testing Properties and Events with Test Container](../mfc/testing-properties-and-events-with-test-container.md) for information on how to access Test Container. diff --git a/docs/atl/implementing-property-pages.md b/docs/atl/implementing-property-pages.md index fe87f6889c..3dcdced9d0 100644 --- a/docs/atl/implementing-property-pages.md +++ b/docs/atl/implementing-property-pages.md @@ -7,7 +7,7 @@ ms.assetid: 62f29440-33a7-40eb-a1ef-3634c95f640c --- # Implementing Property Pages -::: moniker range="msvc-160" +::: moniker range=">=msvc-160" The ATL Property Page wizard is not available in Visual Studio 2019 and later. diff --git a/docs/atl/object-safety-classes.md b/docs/atl/object-safety-classes.md index 29b2fbdcae..8021fd778b 100644 --- a/docs/atl/object-safety-classes.md +++ b/docs/atl/object-safety-classes.md @@ -1,6 +1,6 @@ --- description: "Learn more about: Object Safety Classes" -title: "Object Safety Classes (ATL)| Microsoft Docs" +title: Object Safety Classes (ATL) ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["safety classes", "object safety classes"] diff --git a/docs/atl/programming-with-ccombstr-atl.md b/docs/atl/programming-with-ccombstr-atl.md index a50354b3b6..74c5c54465 100644 --- a/docs/atl/programming-with-ccombstr-atl.md +++ b/docs/atl/programming-with-ccombstr-atl.md @@ -27,9 +27,7 @@ Although several `CComBSTR` methods will automatically convert an ANSI string ar [!code-cpp[NVC_ATL_Utilities#114](../atl/codesnippet/cpp/programming-with-ccombstr-atl_1.cpp)] -If you are using a string literal to modify a `CComBSTR` object, use wide character strings. This will reduce unnecessary conversions. - -### Example +If you're using a string literal to modify a `CComBSTR` object, use wide character strings to reduce unnecessary conversions. [!code-cpp[NVC_ATL_Utilities#115](../atl/codesnippet/cpp/programming-with-ccombstr-atl_2.cpp)] diff --git a/docs/atl/putting-the-control-on-a-web-page-atl-tutorial-part-7.md b/docs/atl/putting-the-control-on-a-web-page-atl-tutorial-part-7.md index 9bfba0d873..14db4bbf4c 100644 --- a/docs/atl/putting-the-control-on-a-web-page-atl-tutorial-part-7.md +++ b/docs/atl/putting-the-control-on-a-web-page-atl-tutorial-part-7.md @@ -15,30 +15,30 @@ In this step, you add functionality to the control and script the Web page to re ### To add control features -1. Open PolyCtl.cpp and replace the following code: - - ```cpp - if (PtInRegion(hRgn, xPos, yPos)) - Fire_ClickIn(xPos, yPos); - else - Fire_ClickOut(xPos, yPos); - ``` - - with - - ```cpp - short temp = m_nSides; - if (PtInRegion(hRgn, xPos, yPos)) - { - Fire_ClickIn(xPos, yPos); - put_Sides(++temp); - } - else - { - Fire_ClickOut(xPos, yPos); - put_Sides(--temp); - } - ``` +Open PolyCtl.cpp and replace the following code: + +```cpp +if (PtInRegion(hRgn, xPos, yPos)) + Fire_ClickIn(xPos, yPos); +else + Fire_ClickOut(xPos, yPos); +``` + +with + +```cpp +short temp = m_nSides; +if (PtInRegion(hRgn, xPos, yPos)) +{ + Fire_ClickIn(xPos, yPos); + put_Sides(++temp); +} +else +{ + Fire_ClickOut(xPos, yPos); + put_Sides(--temp); +} +``` The shape will now add or remove sides depending on where you click. diff --git a/docs/atl/queryinterface.md b/docs/atl/queryinterface.md index e0c5084ff7..3d982e0e93 100644 --- a/docs/atl/queryinterface.md +++ b/docs/atl/queryinterface.md @@ -6,15 +6,15 @@ ms.topic: "reference" helpviewer_keywords: ["interfaces, pointers", "interfaces, availability", "QueryInterface method"] ms.assetid: 62fce95e-aafa-4187-b50b-e6611b74c3b3 --- -# QueryInterface +# `QueryInterface` -Although there are mechanisms by which an object can express the functionality it provides statically (before it is instantiated), the fundamental COM mechanism is to use the `IUnknown` method called [QueryInterface](/windows/win32/api/unknwn/nf-unknwn-iunknown-queryinterface(q)). +Although there are mechanisms by which an object can express the functionality it provides statically (before it is instantiated), the fundamental COM mechanism is to use the `IUnknown` method called [`QueryInterface`](/windows/win32/api/unknwn/nf-unknwn-iunknown-queryinterface(q)). -Every interface is derived from `IUnknown`, so every interface has an implementation of `QueryInterface`. Regardless of implementation, this method queries an object using the IID of the interface to which the caller wants a pointer. If the object supports that interface, `QueryInterface` retrieves a pointer to the interface, while also calling `AddRef`. Otherwise, it returns the E_NOINTERFACE error code. +Every interface is derived from `IUnknown`, so every interface has an implementation of `QueryInterface`. Regardless of implementation, this method queries an object using the `IID` of the interface to which the caller wants a pointer. If the object supports that interface, `QueryInterface` retrieves a pointer to the interface, while also calling `AddRef`. Otherwise, it returns the `E_NOINTERFACE` error code. -Note that you must obey [Reference Counting](../atl/reference-counting.md) rules at all times. If you call `Release` on an interface pointer to decrement the reference count to zero, you should not use that pointer again. Occasionally you may need to obtain a weak reference to an object (that is, you may wish to obtain a pointer to one of its interfaces without incrementing the reference count), but it is not acceptable to do this by calling `QueryInterface` followed by `Release`. The pointer obtained in such a manner is invalid and should not be used. This more readily becomes apparent when [_ATL_DEBUG_INTERFACES](reference/debugging-and-error-reporting-macros.md#_atl_debug_interfaces) is defined, so defining this macro is a useful way of finding reference counting bugs. +Note that you must obey [Reference Counting](../atl/reference-counting.md) rules at all times. If you call `Release` on an interface pointer to decrement the reference count to zero, you should not use that pointer again. Occasionally you may need to obtain a weak reference to an object (that is, you may wish to obtain a pointer to one of its interfaces without incrementing the reference count), but it is not acceptable to do this by calling `QueryInterface` followed by `Release`. The pointer obtained in such a manner is invalid and should not be used. This more readily becomes apparent when [`_ATL_DEBUG_INTERFACES`](reference/debugging-and-error-reporting-macros.md#_atl_debug_interfaces) is defined, so defining this macro is a useful way of finding reference counting bugs. ## See also [Introduction to COM](../atl/introduction-to-com.md)
-[QueryInterface: Navigating in an Object](/windows/win32/com/queryinterface--navigating-in-an-object) +[`QueryInterface`: Navigating in an Object](/windows/win32/com/queryinterface--navigating-in-an-object) diff --git a/docs/atl/reference/adding-an-atl-active-server-page-component.md b/docs/atl/reference/adding-an-atl-active-server-page-component.md index 253100c577..508bf1fbfc 100644 --- a/docs/atl/reference/adding-an-atl-active-server-page-component.md +++ b/docs/atl/reference/adding-an-atl-active-server-page-component.md @@ -6,7 +6,7 @@ ms.assetid: 7be2204c-6e58-4099-8892-001b848c8987 --- # Adding an ATL Active Server Page Component -::: moniker range="msvc-160" +::: moniker range=">=msvc-160" The ATL Active Server Pages component wizard is not available in Visual Studio 2019 and later. diff --git a/docs/atl/reference/adding-an-atl-com-plus-1-0-component.md b/docs/atl/reference/adding-an-atl-com-plus-1-0-component.md index 603ba47fad..6df0a367ba 100644 --- a/docs/atl/reference/adding-an-atl-com-plus-1-0-component.md +++ b/docs/atl/reference/adding-an-atl-com-plus-1-0-component.md @@ -6,7 +6,7 @@ ms.assetid: c6c95e64-9ee4-4a6e-8804-5930202ce1b9 --- # Adding an ATL COM+ 1.0 Component -::: moniker range="msvc-160" +::: moniker range=">=msvc-160" The ATL COM+ 1.0 Component wizard is not available in Visual Studio 2019 and later. diff --git a/docs/atl/reference/adding-an-atl-ole-db-consumer.md b/docs/atl/reference/adding-an-atl-ole-db-consumer.md index d44cc88f16..52b1acc39a 100644 --- a/docs/atl/reference/adding-an-atl-ole-db-consumer.md +++ b/docs/atl/reference/adding-an-atl-ole-db-consumer.md @@ -7,7 +7,7 @@ ms.assetid: f940a513-4e42-4148-b521-dd0d7dc89fa2 --- # Adding an ATL OLE DB Consumer -::: moniker range="msvc-160" +::: moniker range=">=msvc-160" The ATL OLE DB Consumer wizard is not available in Visual Studio 2019 and later. You can still add the functionality manually. For more information, see [Creating a Consumer Without Using a Wizard](../../data/oledb/creating-a-consumer-without-using-a-wizard.md). diff --git a/docs/atl/reference/adding-an-atl-ole-db-provider.md b/docs/atl/reference/adding-an-atl-ole-db-provider.md index 0b588ceece..3aba76e606 100644 --- a/docs/atl/reference/adding-an-atl-ole-db-provider.md +++ b/docs/atl/reference/adding-an-atl-ole-db-provider.md @@ -7,7 +7,7 @@ ms.assetid: 26fba1e3-880f-4bc6-90e5-2096a48a3a6c --- # Adding an ATL OLE DB Provider -::: moniker range="msvc-160" +::: moniker range=">=msvc-160" The ATL OLE DB Provider wizard is not available in Visual Studio 2019 and later. diff --git a/docs/atl/reference/atl-active-server-page-component-wizard.md b/docs/atl/reference/atl-active-server-page-component-wizard.md index fa5cc0a0e8..ceab8c73f9 100644 --- a/docs/atl/reference/atl-active-server-page-component-wizard.md +++ b/docs/atl/reference/atl-active-server-page-component-wizard.md @@ -7,7 +7,7 @@ ms.assetid: 5a5cb904-dbbf-44ea-ad3d-2ddd14c1d3c5 --- # ATL Active Server Page Component Wizard -::: moniker range="msvc-160" +::: moniker range=">=msvc-160" This wizard is not available in Visual Studio 2019 and later. diff --git a/docs/atl/reference/atl-classes.md b/docs/atl/reference/atl-classes.md index 7d62887623..36a3ed3f0d 100644 --- a/docs/atl/reference/atl-classes.md +++ b/docs/atl/reference/atl-classes.md @@ -1,9 +1,8 @@ --- description: "Learn more about: ATL classes and structs" -title: "ATL classes and structs| Microsoft Docs" +title: ATL classes and structs ms.date: "05/03/2018" helpviewer_keywords: ["classes [C++], ATL", "ATL, classes"] -ms.assetid: 7da42e2d-ac84-4506-92bd-502a86d68bdc --- # ATL classes and structs @@ -11,211 +10,211 @@ The Active Template Library (ATL) includes the following classes and structs. To |Class / struct|Description|Header file| |-----------|-----------------|-----------------| -|[ATL_DRAWINFO](../../atl/reference/atl-drawinfo-structure.md)|Contains information used for rendering to various targets, such as a printer, metafile, or ActiveX control.|atlctl.h| -|[_AtlCreateWndData](../../atl/reference/atlcreatewnddata-structure.md)|Contains class instance data in windowing code in ATL.|atlbase.h| -|[_ATL_BASE_MODULE70](../../atl/reference/atl-base-module70-structure.md)|Used by any project that uses ATL.|atlbase.h| -|[_ATL_COM_MODULE70](../../atl/reference/atl-com-module70-structure.md)|Used by COM-related code in ATL.| atlbase.h| -|[_ATL_FUNC_INFO](../../atl/reference/atl-func-info-structure.md)|Contains type information used to describe a method or property on a dispinterface.|atlcom.h| -|[_ATL_MODULE70](../../atl/reference/atl-module70-structure.md)|Contains data used by every ATL module.|atlbase.h| -|[_ATL_WIN_MODULE70](../../atl/reference/atl-win-module70-structure.md)|Used by windowing code in ATL.|atlbase.h| -|[CA2AEX](../../atl/reference/ca2aex-class.md)|This class is used by the string conversion macros CA2TEX and CT2AEX, and the typedef CA2A.|atlconv.h| -|[CA2CAEX](../../atl/reference/ca2caex-class.md)|This class is used by string conversion macros CA2CTEX and CT2CAEX, and the typedef CA2CA.|atlconv.h| -|[CA2WEX](../../atl/reference/ca2wex-class.md)|This class is used by the string conversion macros CA2TEX, CA2CTEX, CT2WEX, and CT2CWEX, and the typedef CA2W.|atlconv.h| -|[CAccessToken](../../atl/reference/caccesstoken-class.md)|This class is a wrapper for an access token.|atlsecurity.h| -|[CAcl](../../atl/reference/cacl-class.md)|This class is a wrapper for an ACL (access-control list) structure.|atlsecurity.h| -|[CAdapt](../../atl/reference/cadapt-class.md)|This template is used to wrap classes that redefine the address-of operator to return something other than the address of the object.|atlcomcli.h| -|[CAtlArray](../../atl/reference/catlarray-class.md)|This class implements an array object.|atlcoll.h| -|[CAtlAutoThreadModule](../../atl/reference/catlautothreadmodule-class.md)|This class implements a thread-pooled, apartment-model COM server.|atlbase.h| -|[CAtlAutoThreadModuleT](../../atl/reference/catlautothreadmodulet-class.md)|This class provides methods for implementing a thread-pooled, apartment-model COM server.|atlbase.h| -|[CAtlBaseModule](../../atl/reference/catlbasemodule-class.md)|This class is instantiated in every ATL project.|atlcore.h| -|[CAtlComModule](../../atl/reference/catlcommodule-class.md)|This class implements a COM server module.|atlbase.h| -|[CAtlDebugInterfacesModule](../../atl/reference/catldebuginterfacesmodule-class.md)|This class provides support for debugging interfaces.|atlbase.h| -|[CAtlDllModuleT](../../atl/reference/catldllmodulet-class.md)|This class represents the module for a DLL.|atlbase.h| -|[CAtlException](../../atl/reference/catlexception-class.md)|This class defines an ATL exception.|atlexcept.h| -|[CAtlExeModuleT](../../atl/reference/catlexemodulet-class.md)|This class represents the module for an application.|atlbase.h| -|[CAtlFile](../../atl/reference/catlfile-class.md)|This class provides a thin wrapper around the Windows file-handling API.|atlfile.h| -|[CAtlFileMapping](../../atl/reference/catlfilemapping-class.md)|This class represents a memory-mapped file, adding a cast operator to the methods of [CAtlFileMappingBase](../../atl/reference/catlfilemappingbase-class.md).|atlfile.h| -|[CAtlFileMappingBase](../../atl/reference/catlfilemappingbase-class.md)|This class represents a memory-mapped file.|atlfile.h| -|[CAtlList](../../atl/reference/catllist-class.md)|This class provides methods for creating and managing a list object.|atlcoll.h| -|[CAtlMap](../../atl/reference/catlmap-class.md)|This class provides methods for creating and managing a map object.|atlcoll.h| -|[CAtlModule](../../atl/reference/catlmodule-class.md)|This class provides methods used by several ATL module classes.|atlbase.h| -|[CAtlModuleT](../../atl/reference/catlmodulet-class.md)|This class implements an ATL module.|atlbase.h| -|[CAtlPreviewCtrlImpl](../../atl/reference/catlpreviewctrlimpl-class.md)|This class is an ATL implementation of a window that is placed on a host window provided by the Shell for Rich Preview.|atlpreviewctrlimpl.h| -|[CAtlServiceModuleT](../../atl/reference/catlservicemodulet-class.md)|This class implements a service.|atlbase.h| -|[CAtlTemporaryFile](../../atl/reference/catltemporaryfile-class.md)|This class provides methods for the creation and use of a temporary file.|atlfile.h| -|[CAtlTransactionManager](../../atl/reference/catltransactionmanager-class.md)|This class provides a wrapper to Kernel Transaction Manager (KTM) functions.|atltransactionmanager.h| -|[CAtlWinModule](../../atl/reference/catlwinmodule-class.md)|This class provides support for ATL windowing components.|atlbase.h| -|[CAutoPtr](../../atl/reference/cautoptr-class.md)|This class represents a smart pointer object.|atlbase.h| -|[CAutoPtrArray](../../atl/reference/cautoptrarray-class.md)|This class provides methods useful when constructing an array of smart pointers.|atlbase.h| -|[CAutoPtrElementTraits](../../atl/reference/cautoptrelementtraits-class.md)|This class provides methods, static functions, and typedefs useful when creating collections of smart pointers.|atlcoll.h| -|[CAutoPtrList](../../atl/reference/cautoptrlist-class.md)|This class provides methods useful when constructing a list of smart pointers.|atlcoll.h| -|[CAutoVectorPtr](../../atl/reference/cautovectorptr-class.md)|This class represents a smart pointer object using vector new and delete operators.|atlbase.h| -|[CAutoVectorPtrElementTraits](../../atl/reference/cautovectorptrelementtraits-class.md)|This class provides methods, static functions, and typedefs useful when creating collections of smart pointers using vector new and delete operators.|atlcoll.h| -|[CAxDialogImpl](../../atl/reference/caxdialogimpl-class.md)|This class implements a dialog box (modal or modeless) that hosts ActiveX controls.|atlwin.h| -|[CAxWindow](../../atl/reference/caxwindow-class.md)|This class provides methods for manipulating a window hosting an ActiveX control.|atlwin.h| -|[CAxWindow2T](../../atl/reference/caxwindow2t-class.md)|This class provides methods for manipulating a window that hosts an ActiveX control and also has support for hosting licensed ActiveX controls.|atlwin.h| -|[CBindStatusCallback](../../atl/reference/cbindstatuscallback-class.md)|This class implements the `IBindStatusCallback` interface.|atlctl.h| -|[CComAggObject](../../atl/reference/ccomaggobject-class.md)|This class implements [IUnknown](/windows/win32/api/unknwn/nn-unknwn-iunknown) for an aggregated object.|atlcom.h| -|[CComAllocator](../../atl/reference/ccomallocator-class.md)|This class provides methods for managing memory using COM memory routines.|atlbase.h| -|[CComApartment](../../atl/reference/ccomapartment-class.md)|This class provides support for managing an apartment in a thread-pooled EXE module.|atlbase.h| -|[CComAutoCriticalSection](../../atl/reference/ccomautocriticalsection-class.md)|This class provides methods for obtaining and releasing ownership of a critical section object.|atlcore.h| -|[CComAutoThreadModule](../../atl/reference/ccomautothreadmodule-class.md)|As of ATL 7.0, `CComAutoThreadModule` is obsolete: see [ATL Modules](../../atl/atl-module-classes.md) for more details.|atlbase.h| -|[CComBSTR](../../atl/reference/ccombstr-class.md)|This class is a wrapper for BSTRs.|atlbase.h| -|[CComCachedTearOffObject](../../atl/reference/ccomcachedtearoffobject-class.md)|This class implements [IUnknown](/windows/win32/api/unknwn/nn-unknwn-iunknown) for a tear-off interface.|atlcom.h| -|[CComClassFactory](../../atl/reference/ccomclassfactory-class.md)|This class implements the [IClassFactory](/windows/win32/api/unknwnbase/nn-unknwnbase-iclassfactory) interface.|atlcom.h| -|[CComClassFactory2](../../atl/reference/ccomclassfactory2-class.md)|This class implements the [IClassFactory2](/windows/win32/api/ocidl/nn-ocidl-iclassfactory2) interface.|atlcom.h| -|[CComClassFactoryAutoThread](../../atl/reference/ccomclassfactoryautothread-class.md)|This class implements the [IClassFactory](/windows/win32/api/unknwnbase/nn-unknwnbase-iclassfactory) interface and allows objects to be created in multiple apartments.|atlcom.h| -|[CComClassFactorySingleton](../../atl/reference/ccomclassfactorysingleton-class.md)|This class derives from [CComClassFactory](../../atl/reference/ccomclassfactory-class.md) and uses [CComObjectGlobal](../../atl/reference/ccomobjectglobal-class.md) to construct a single object.|atlcom.h| -|[CComCoClass](../../atl/reference/ccomcoclass-class.md)|This class provides methods for creating instances of a class and obtaining its properties.|atlcom.h| -|[CComCompositeControl](../../atl/reference/ccomcompositecontrol-class.md)|This class provides the methods required to implement a composite control.|atlctl.h| -|[CComContainedObject](../../atl/reference/ccomcontainedobject-class.md)|This class implements [IUnknown](/windows/win32/api/unknwn/nn-unknwn-iunknown) by delegating to the owner object's `IUnknown`.|atlcom.h| -|[CComControl](../../atl/reference/ccomcontrol-class.md)|This class provides methods for creating and managing ATL controls.|atlctl.h| -|[CComControlBase](../../atl/reference/ccomcontrolbase-class.md)|This class provides methods for creating and managing ATL controls.|atlctl.h| -|[CComCriticalSection](../../atl/reference/ccomcriticalsection-class.md)|This class provides methods for obtaining and releasing ownership of a critical section object.|atlcore.h| -|[CComCritSecLock](../../atl/reference/ccomcritseclock-class.md)|This class provides methods for locking and unlocking a critical section object.|atlbase.h| -|[CComCurrency](../../atl/reference/ccomcurrency-class.md)|This class has methods and operators for creating and managing a CURRENCY object.|atlcur.h| -|[CComDynamicUnkArray](../../atl/reference/ccomdynamicunkarray-class.md)|This class stores an array of `IUnknown` pointers.|atlcom.h| -|[CComEnum](../../atl/reference/ccomenum-class.md)|This class defines a COM enumerator object based on an array.|atlcom.h| -|[CComEnumImpl](../../atl/reference/ccomenumimpl-class.md)|This class provides the implementation for a COM enumerator interface where the items being enumerated are stored in an array.|atlcom.h| -|[CComEnumOnSTL](../../atl/reference/ccomenumonstl-class.md)|This class defines a COM enumerator object based on a C++ Standard Library collection.|atlcom.h| -|[CComFakeCriticalSection](../../atl/reference/ccomfakecriticalsection-class.md)|This class provides the same methods as [CComCriticalSection](../../atl/reference/ccomcriticalsection-class.md) but does not provide a critical section.|atlcore.h| -|[CComGITPtr](../../atl/reference/ccomgitptr-class.md)|This class provides methods for dealing with interface pointers and the global interface table (GIT).|atlbase.h| -|[CComHeap](../../atl/reference/ccomheap-class.md)|This class implements [IAtlMemMgr](../../atl/reference/iatlmemmgr-class.md) using the COM memory allocation functions.|ATLComMem.h| -|[CComHeapPtr](../../atl/reference/ccomheapptr-class.md)|A smart pointer class for managing heap pointers.|atlbase.h| -|[CComModule](../../atl/reference/ccommodule-class.md)|As of ATL 7.0, `CComModule` is obsolete: see [ATL Modules](../../atl/atl-module-classes.md) for more details.|atlbase.h| -|[CComMultiThreadModel](../../atl/reference/ccommultithreadmodel-class.md)|This class provides thread-safe methods for incrementing and decrementing the value of a variable.|atlbase.h| -|[CComMultiThreadModelNoCS](../../atl/reference/ccommultithreadmodelnocs-class.md)|This class provides thread-safe methods for incrementing and decrementing the value of a variable, without critical section locking or unlocking functionality.|atlbase.h| -|[CComObject](../../atl/reference/ccomobject-class.md)|This class implements `IUnknown` for a nonaggregated object.|atlcom.h| -|[CComObjectGlobal](../../atl/reference/ccomobjectglobal-class.md)|This class manages a reference count on the module containing your `Base` object.|atlcom.h| -|[CComObjectNoLock](../../atl/reference/ccomobjectnolock-class.md)|This class implements `IUnknown` for a nonaggregated object, but does not increment the module lock count in the constructor.|atlcom.h| -|[CComObjectRoot](../../atl/reference/ccomobjectroot-class.md)|This typedef of [CComObjectRootEx](../../atl/reference/ccomobjectrootex-class.md) is templatized on the default threading model of the server.|atlcom.h| -|[CComObjectRootEx](../../atl/reference/ccomobjectrootex-class.md)|This class provides methods to handle object reference count management for both nonaggregated and aggregated objects.|atlcom.h| -|[CComObjectStack](../../atl/reference/ccomobjectstack-class.md)|This class creates a temporary COM object and provides it with a skeletal implementation of `IUnknown`.|atlcom.h| -|[CComPolyObject](../../atl/reference/ccompolyobject-class.md)|This class implements `IUnknown` for an aggregated or nonaggregated object.|atlcom.h| -|[CComPtr](../../atl/reference/ccomptr-class.md)|A smart pointer class for managing COM interface pointers.|atlcomcli.h| -|[CComPtrBase](../../atl/reference/ccomptrbase-class.md)|This class provides a basis for smart pointer classes using COM-based memory routines.|atlcomcli.h| -|[CComQIPtr](../../atl/reference/ccomqiptr-class.md)|A smart pointer class for managing COM interface pointers.|atlcomcli.h| -|[CComQIPtrElementTraits](../../atl/reference/ccomqiptrelementtraits-class.md)|This class provides methods, static functions, and typedefs useful when creating collections of COM interface pointers.|atlcoll.h| -|[CComSafeArray](../../atl/reference/ccomsafearray-class.md)|This class is a wrapper for the `SAFEARRAY Data Type` structure.|atlsafe.h| -|[CComSafeArrayBound](../../atl/reference/ccomsafearraybound-class.md)|This class is a wrapper for a `SAFEARRAYBOUND` structure.|atlsafe.h| -|[CComSimpleThreadAllocator](../../atl/reference/ccomsimplethreadallocator-class.md)|This class manages thread selection for the class [CComAutoThreadModule](../../atl/reference/ccomautothreadmodule-class.md).|atlbase.h| -|[CComSingleThreadModel](../../atl/reference/ccomsinglethreadmodel-class.md)|This class provides methods for incrementing and decrementing the value of a variable.|atlbase.h| -|[CComTearOffObject](../../atl/reference/ccomtearoffobject-class.md)|This class implements a tear-off interface.|atlcom.h| -|[CComUnkArray](../../atl/reference/ccomunkarray-class.md)|This class stores `IUnknown` pointers and is designed to be used as a parameter to the [IConnectionPointImpl](../../atl/reference/iconnectionpointimpl-class.md) template class.|atlcom.h| -|[CComVariant](../../atl/reference/ccomvariant-class.md)|This class wraps the VARIANT type, providing a member indicating the type of data stored.|atlcomcli.h| -|[CContainedWindowT](../../atl/reference/ccontainedwindowt-class.md)|This class implements a window contained within another object.|atlwin.h| -|[CCRTAllocator](../../atl/reference/ccrtallocator-class.md)|This class provides methods for managing memory using CRT memory routines.|atlcore.h| -|[CCRTHeap](../../atl/reference/ccrtheap-class.md)|This class implements [IAtlMemMgr](../../atl/reference/iatlmemmgr-class.md) using the CRT heap functions.|atlmem.h| -|[CDacl](../../atl/reference/cdacl-class.md)|This class is a wrapper for a DACL (discretionary access-control list) structure.|atlsecurity.h| -|[CDebugReportHook Class](../../atl/reference/cdebugreporthook-class.md)|Use this class to send debug reports to a named pipe.|atlutil.h| -|[CDefaultCharTraits](../../atl/reference/cdefaultchartraits-class.md)|This class provides two static functions for converting characters between uppercase and lowercase.|atlcoll.h| -|[CDefaultCompareTraits](../../atl/reference/cdefaultcomparetraits-class.md)|This class provides default element comparison functions.|atlcoll.h| -|[CDefaultElementTraits](../../atl/reference/cdefaultelementtraits-class.md)|This class provides default methods and functions for a collection class.|atlcoll.h| -|[CDefaultHashTraits](../../atl/reference/cdefaulthashtraits-class.md)|This class provides a static function for calculating hash values.|atlcoll.h| -|[CDialogImpl](../../atl/reference/cdialogimpl-class.md)|This class provides methods for creating a modal or modeless dialog box.|atlwin.h| -|[CDynamicChain](../../atl/reference/cdynamicchain-class.md)|This class provides methods supporting the dynamic chaining of message maps.|atlwin.h| -|[CElementTraits](../../atl/reference/celementtraits-class.md)|This class is used by collection classes to provide methods and functions for moving, copying, comparison, and hashing operations.|atlcoll.h| -|[CElementTraitsBase](../../atl/reference/celementtraitsbase-class.md)|This class provides default copy and move methods for a collection class.|atlcoll.h| -|[CFirePropNotifyEvent](../../atl/reference/cfirepropnotifyevent-class.md)|This class provides methods for notifying the container's sink regarding control property changes.|atlctl.h| -|[CGlobalHeap](../../atl/reference/cglobalheap-class.md)|This class implements [IAtlMemMgr](../../atl/reference/iatlmemmgr-class.md) using the Win32 global heap functions.|atlmem.h| -|[CHandle](../../atl/reference/chandle-class.md)|This class provides methods for creating and using a handle object.|atlbase.h| -|[CHeapPtr](../../atl/reference/cheapptr-class.md)|A smart pointer class for managing heap pointers.|atlcore.h| -|[CHeapPtrBase](../../atl/reference/cheapptrbase-class.md)|This class forms the basis for several smart heap pointer classes.|atlcore.h| -|[CHeapPtrElementTraits Class](../../atl/reference/cheapptrelementtraits-class.md)|This class provides methods, static functions, and typedefs useful when creating collections of heap pointers.|atlcoll.h| -|[CHeapPtrList](../../atl/reference/cheapptrlist-class.md)|This class provides methods useful when constructing a list of heap pointers.|atlcoll.h| -|[CImage](../../atl-mfc-shared/reference/cimage-class.md)|Provides enhanced bitmap support, including the ability to load and save images in JPEG, GIF, BMP, and Portable Network Graphics (PNG) formats.|atlimage.h| -|[CInterfaceArray](../../atl/reference/cinterfacearray-class.md)|This class provides methods useful when constructing an array of COM interface pointers.|atlcoll.h| -|[CInterfaceList](../../atl/reference/cinterfacelist-class.md)|This class provides methods useful when constructing a list of COM interface pointers.|atlcoll.h| -|[CLocalHeap](../../atl/reference/clocalheap-class.md)|This class implements [IAtlMemMgr](../../atl/reference/iatlmemmgr-class.md) using the Win32 local heap functions.|atlmem.h| -|[CMessageMap](../../atl/reference/cmessagemap-class.md)|This class allows an object's message maps to be accessed by another object.|atlwin.h| -|[CNonStatelessWorker Class](../../atl/reference/cnonstatelessworker-class.md)|Receives requests from a thread pool and passes them on to a worker object that is created and destroyed on each request.|atlutil.h| -|[CNoWorkerThread Class](../../atl/reference/cnoworkerthread-class.md)|Use this class as the argument for the `MonitorClass` template parameter cache classes if you want to disable dynamic cache maintenance.|atlutil.h| -|[CPathT Class](../../atl/reference/cpatht-class.md)|This class represents a path.|atlpath.h| -|[CPrimitiveElementTraits](../../atl/reference/cprimitiveelementtraits-class.md)|This class provides default methods and functions for a collection class composed of primitive data types.|atlcoll.h| -|[CPrivateObjectSecurityDesc](../../atl/reference/cprivateobjectsecuritydesc-class.md)|This class represents a private object security descriptor object.|atlsecurity.h| -|[CRBMap](../../atl/reference/crbmap-class.md)|This class represents a mapping structure, using a Red-Black binary tree.|atlcoll.h| -|[CRBMultiMap](../../atl/reference/crbmultimap-class.md)|This class represents a mapping structure that allows each key to be associated with more than one value, using a Red-Black binary tree.|atlcoll.h| -|[CRBTree](../../atl/reference/crbtree-class.md)|This class provides methods for creating and utilizing a Red-Black tree.|atlcoll.h| -|[CRegKey](../../atl/reference/cregkey-class.md)|This class provides methods for manipulating entries in the system registry.|atlbase.h| -|[CRTThreadTraits](../../atl/reference/crtthreadtraits-class.md)|This class provides the creation function for a CRT thread. Use this class if the thread will use CRT functions.|atlbase.h| -|[CSacl](../../atl/reference/csacl-class.md)|This class is a wrapper for a SACL (system access-control list) structure.|atlsecurity.h| -|[CSecurityAttributes](../../atl/reference/csecurityattributes-class.md)|This class is a thin wrapper for the `SECURITY_ATTRIBUTES` structure.|atlsecurity.h| -|[CSecurityDesc](../../atl/reference/csecuritydesc-class.md)|This class is a wrapper for the `SECURITY_DESCRIPTOR` structure.|atlsecurity.h| -|[CSid](../../atl/reference/csid-class.md)|This class is a wrapper for a `SID` (security identifier) structure.|atlsecurity.h| -|[CSimpleArray](../../atl/reference/csimplearray-class.md)|This class provides methods for managing a simple array.|atlsimpcoll.h| -|[CSimpleArrayEqualHelper](../../atl/reference/csimplearrayequalhelper-class.md)|This class is a helper for the [CSimpleArray](../../atl/reference/csimplearray-class.md) class.|atlsimpcoll.h| -|[CSimpleArrayEqualHelperFalse](../../atl/reference/csimplearrayequalhelperfalse-class.md)|This class is a helper for the [CSimpleArray](../../atl/reference/csimplearray-class.md) class.|atlsimpcoll.h| -|[CSimpleDialog](../../atl/reference/csimpledialog-class.md)|This class implements a basic modal dialog box.|atlwin.h| -|[CSimpleMap](../../atl/reference/csimplemap-class.md)|This class provides support for a simple mapping array.|atlsimpcoll.h| -|[CSimpleMapEqualHelper](../../atl/reference/csimplemapequalhelper-class.md)|This class is a helper for the [CSimpleMap](../../atl/reference/csimplemap-class.md) class.|atlsimpcoll.h| -|[CSimpleMapEqualHelperFalse](../../atl/reference/csimplemapequalhelperfalse-class.md)|This class is a helper for the [CSimpleMap](../../atl/reference/csimplemap-class.md) class.|atlsimpcoll.h| -|[CSnapInItemImpl](../../atl/reference/csnapinitemimpl-class.md)|This class provides methods for implementing a snap-in node object.|atlsnap.h| -|[CSnapInPropertyPageImpl](../../atl/reference/csnapinpropertypageimpl-class.md)|This class provides methods for implementing a snap-in property page object.|atlsnap.h| -|[CStockPropImpl](../../atl/reference/cstockpropimpl-class.md)|This class provides methods for supporting stock property values.|atlctl.h| -|[CStringElementTraits](../../atl/reference/cstringelementtraits-class.md)|This class provides static functions used by collection classes storing `CString` objects.|cstringt.h| -|[CStringElementTraitsI](../../atl/reference/cstringelementtraitsi-class.md)|This class provides static functions related to strings stored in collection class objects. It is similar to [CStringElementTraits](../../atl/reference/cstringelementtraits-class.md), but performs case-insensitive comparisons.|atlcoll.h| -|[CStringRefElementTraits](../../atl/reference/cstringrefelementtraits-class.md)|This class provides static functions related to strings stored in collection class objects. The string objects are dealt with as references.|atlcoll.h| -|[CThreadPool Class](../../atl/reference/cthreadpool-class.md)|This class provides a pool of worker threads that process a queue of work items.|atlutil.h| -|[CTokenGroups](../../atl/reference/ctokengroups-class.md)|This class is a wrapper for the `TOKEN_GROUPS` structure.|atlsecurity.h| -|[CTokenPrivileges](../../atl/reference/ctokenprivileges-class.md)|This class is a wrapper for the `TOKEN_PRIVILEGES` structure.|atlsecurity.h| -|[CUrl Class](../../atl/reference/curl-class.md)|This class represents a URL. It allows you to manipulate each element of the URL independently of the others whether parsing an existing URL string or building a string from scratch.|atlutil.h| -|[CW2AEX](../../atl/reference/cw2aex-class.md)|This class is used by the string conversion macros CT2AEX, CW2TEX, CW2CTEX, and CT2CAEX, and the typedef CW2A.|atlconv.h| -|[CW2CWEX](../../atl/reference/cw2cwex-class.md)|This class is used by the string conversion macros CW2CTEX and CT2CWEX, and the typedef CW2CW.|atlconv.h| -|[CW2WEX](../../atl/reference/cw2wex-class.md)|This class is used by the string conversion macros CW2TEX and CT2WEX, and the typedef CW2W.|atlconv.h| -|[CWin32Heap](../../atl/reference/cwin32heap-class.md)|This class implements [IAtlMemMgr](../../atl/reference/iatlmemmgr-class.md) using the Win32 heap allocation functions.|atlmem.h| -|[CWindow](../../atl/reference/cwindow-class.md)|This class provides methods for manipulating a window.|atlwin.h| -|[CWindowImpl](../../atl/reference/cwindowimpl-class.md)|This class provides methods for creating or subclassing a window.|atlwin.h| -|[CWinTraits](../../atl/reference/cwintraits-class.md)|This class provides a method for standardizing the styles used when creating a window object.|atlwin.h| -|[CWinTraitsOR](../../atl/reference/cwintraitsor-class.md)|This class provides a method for standardizing the styles used when creating a window object.|atlwin.h| -|[CWndClassInfo](../../atl/reference/cwndclassinfo-class.md)|This class provides methods for registering information for a window class.|atlwin.h| -|[CWorkerThread Class](../../atl/reference/cworkerthread-class.md)|This class creates a worker thread or uses an existing one, waits on one or more kernel object handles, and executes a specified client function when one of the handles is signaled.|atlutil.h| -|[IAtlAutoThreadModule](../../atl/reference/iatlautothreadmodule-class.md)|This class represents an interface to a `CreateInstance` method.|atlbase.h| -|[IAtlMemMgr](../../atl/reference/iatlmemmgr-class.md)|This class represents the interface to a memory manager.|atlmem.h| -|[IAxWinAmbientDispatch](../../atl/reference/iaxwinambientdispatch-interface.md)|This interface provides methods for specifying characteristics of the hosted control or container.|atlbase.h, ATLIFace.h| -|[IAxWinAmbientDispatchEx](../../atl/reference/iaxwinambientdispatchex-interface.md)|This interface implements supplemental ambient properties for a hosted control.|atlbase.h, ATLIFace.h| -|[IAxWinHostWindow](../../atl/reference/iaxwinhostwindow-interface.md)|This interface provides methods for manipulating a control and its host object.|atlbase.h, ATLIFace.h| -|[IAxWinHostWindowLic](../../atl/reference/iaxwinhostwindowlic-interface.md)|This interface provides methods for manipulating a licensed control and its host object.|atlbase.h, ATLIFace.h| -|[ICollectionOnSTLImpl](../../atl/reference/icollectiononstlimpl-class.md)|This class provides methods used by a collection class.|atlcom.h| -|[IConnectionPointContainerImpl](../../atl/reference/iconnectionpointcontainerimpl-class.md)|This class implements a connection point container to manage a collection of [IConnectionPointImpl](../../atl/reference/iconnectionpointimpl-class.md) objects.|atlcom.h| -|[IConnectionPointImpl](../../atl/reference/iconnectionpointimpl-class.md)|This class implements a connection point.|atlcom.h| -|[IDataObjectImpl](../../atl/reference/idataobjectimpl-class.md)|This class provides methods for supporting Uniform Data Transfer and managing connections.|atlctl.h| -|[IDispatchImpl](../../atl/reference/idispatchimpl-class.md)|This class provides a default implementation for the `IDispatch` portion of a dual interface.|atlcom.h| -|[IDispEventImpl](../../atl/reference/idispeventimpl-class.md)|This class provides implementations of the `IDispatch` methods.|atlcom.h| -|[IDispEventSimpleImpl](../../atl/reference/idispeventsimpleimpl-class.md)|This class provides implementations of the `IDispatch` methods, without getting type information from a type library.|atlcom.h| -|[IDocHostUIHandlerDispatch](../../atl/reference/idochostuihandlerdispatch-interface.md)|An interface to the Microsoft HTML parsing and rendering engine.|atlbase.h, ATLIFace.h| -|[IEnumOnSTLImpl](../../atl/reference/ienumonstlimpl-class.md)|This class defines an enumerator interface based on a C++ Standard Library collection.|atlcom.h| -|[IObjectSafetyImpl](../../atl/reference/iobjectsafetyimpl-class.md)|This class provides a default implementation of the `IObjectSafety` interface to allow a client to retrieve and set an object's safety levels.|atlctl.h| -|[IObjectWithSiteImpl](../../atl/reference/iobjectwithsiteimpl-class.md)|This class provides methods allowing an object to communicate with its site.|atlcom.h| -|[IOleControlImpl](../../atl/reference/iolecontrolimpl-class.md)|This class provides a default implementation of the `IOleControl` interface and implements `IUnknown`.|atlctl.h| -|[IOleInPlaceActiveObjectImpl](../../atl/reference/ioleinplaceactiveobjectimpl-class.md)|This class provides methods for assisting communication between an in-place control and its container.|atlctl.h| -|[IOleInPlaceObjectWindowlessImpl](../../atl/reference/ioleinplaceobjectwindowlessimpl-class.md)|This class implements `IUnknown` and provides methods that enable a windowless control to receive window messages and to participate in drag-and-drop operations.|atlctl.h| -|[IOleObjectImpl](../../atl/reference/ioleobjectimpl-class.md)|This class implements `IUnknown` and is the principal interface through which a container communicates with a control.|atlctl.h| -|[IPerPropertyBrowsingImpl](../../atl/reference/iperpropertybrowsingimpl-class.md)|This class implements `IUnknown` and allows a client to access the information in an object's property pages.|atlctl.h| -|[IPersistPropertyBagImpl](../../atl/reference/ipersistpropertybagimpl-class.md)|This class implements `IUnknown` and allows an object to save its properties to a client-supplied property bag.|atlcom.h| -|[IPersistStorageImpl](../../atl/reference/ipersiststorageimpl-class.md)|This class implements the [IPersistStorage](/windows/win32/api/objidl/nn-objidl-ipersiststorage) interface.|atlcom.h| -|[IPersistStreamInitImpl](../../atl/reference/ipersiststreaminitimpl-class.md)|This class implements `IUnknown` and provides a default implementation of the [IPersistStreamInit](/windows/win32/api/ocidl/nn-ocidl-ipersiststreaminit) interface.|atlcom.h| -|[IPointerInactiveImpl](../../atl/reference/ipointerinactiveimpl-class.md)|This class implements `IUnknown` and the [IPointerInactive](/windows/win32/api/ocidl/nn-ocidl-ipointerinactive) interface methods.|atlctl.h| -|[IPropertyNotifySinkCP](../../atl/reference/ipropertynotifysinkcp-class.md)|This class exposes the [IPropertyNotifySink](/windows/win32/api/ocidl/nn-ocidl-ipropertynotifysink) interface as an outgoing interface on a connectable object.|atlctl.h| -|[IPropertyPage2Impl](../../atl/reference/ipropertypage2impl-class.md)|This class implements `IUnknown` and inherits the default implementation of [IPropertyPageImpl](../../atl/reference/ipropertypageimpl-class.md).|atlctl.h| -|[IPropertyPageImpl](../../atl/reference/ipropertypageimpl-class.md)|This class implements `IUnknown` and provides a default implementation of the [IPropertyPage](/windows/win32/api/ocidl/nn-ocidl-ipropertypage) interface.|atlctl.h| -|[IProvideClassInfo2Impl](../../atl/reference/iprovideclassinfo2impl-class.md)|This class provides a default implementation of the [IProvideClassInfo](/windows/win32/api/ocidl/nn-ocidl-iprovideclassinfo) and [IProvideClassInfo2](/windows/win32/api/ocidl/nn-ocidl-iprovideclassinfo2) methods.|atlcom.h| -|[IQuickActivateImpl](../../atl/reference/iquickactivateimpl-class.md)|This class combines containers' control initialization into a single call.|atlctl.h| -|[IRunnableObjectImpl](../../atl/reference/irunnableobjectimpl-class.md)|This class implements `IUnknown` and provides a default implementation of the [IRunnableObject](/windows/win32/api/objidl/nn-objidl-irunnableobject) interface.|atlctl.h| -|[IServiceProviderImpl](../../atl/reference/iserviceproviderimpl-class.md)|This class provides a default implementation of the `IServiceProvider` interface.|atlcom.h| -|[ISpecifyPropertyPagesImpl](../../atl/reference/ispecifypropertypagesimpl-class.md)|This class implements `IUnknown` and provides a default implementation of the [ISpecifyPropertyPages](/windows/win32/api/ocidl/nn-ocidl-ispecifypropertypages) interface.|atlcom.h| -|[ISupportErrorInfoImpl](../../atl/reference/isupporterrorinfoimpl-class.md)|This class provides a default implementation of the `ISupportErrorInfo Interface` interface and can be used when only a single interface generates errors on an object.|atlcom.h| -|[IThreadPoolConfig Interface](../../atl/reference/ithreadpoolconfig-interface.md)|This interface provides methods for configuring a thread pool.|atlutil.h| -|[IViewObjectExImpl](../../atl/reference/iviewobjecteximpl-class.md)|This class implements `IUnknown` and provides default implementations of the [IViewObject](/windows/win32/api/oleidl/nn-oleidl-iviewobject), [IViewObject2](/windows/win32/api/oleidl/nn-oleidl-iviewobject2), and [IViewObjectEx](/windows/win32/api/ocidl/nn-ocidl-iviewobjectex) interfaces.|atlctl.h| -|[IWorkerThreadClient Interface](../../atl/reference/iworkerthreadclient-interface.md)|`IWorkerThreadClient` is the interface implemented by clients of the [CWorkerThread](../../atl/reference/cworkerthread-class.md) class.|atlutil.h| -|[_U_MENUorID](../../atl/reference/u-menuorid-class.md)|This class provides wrappers for `CreateWindow` and `CreateWindowEx`.|atlwin.h| -|[_U_RECT](../../atl/reference/u-rect-class.md)|This argument adapter class allows either `RECT` pointers or references to be passed to a function that is implemented in terms of pointers.|atlwin.h| -|[_U_STRINGorID](../../atl/reference/u-stringorid-class.md)|This argument adapter class allows either resource names (LPCTSTRs) or resource IDs (UINTs) to be passed to a function without requiring the caller to convert the ID to a string using the MAKEINTRESOURCE macro.|atlwin.h| -|[Win32ThreadTraits](../../atl/reference/win32threadtraits-class.md)|This class provides the creation function for a Windows thread. Use this class if the thread will not use CRT functions.|atlbase.h| +|[`ATL_DRAWINFO`](../../atl/reference/atl-drawinfo-structure.md)|Contains information used for rendering to various targets, such as a printer, metafile, or ActiveX control.|`atlctl.h`| +|[`_AtlCreateWndData`](../../atl/reference/atlcreatewnddata-structure.md)|Contains class instance data in windowing code in ATL.|`atlbase.h`| +|[`_ATL_BASE_MODULE70`](../../atl/reference/atl-base-module70-structure.md)|Used by any project that uses ATL.|`atlbase.h`| +|[`_ATL_COM_MODULE70`](../../atl/reference/atl-com-module70-structure.md)|Used by COM-related code in ATL.| `atlbase.h`| +|[`_ATL_FUNC_INFO`](../../atl/reference/atl-func-info-structure.md)|Contains type information used to describe a method or property on a dispinterface.|`atlcom.h`| +|[`_ATL_MODULE70`](../../atl/reference/atl-module70-structure.md)|Contains data used by every ATL module.|`atlbase.h`| +|[`_ATL_WIN_MODULE70`](../../atl/reference/atl-win-module70-structure.md)|Used by windowing code in ATL.|`atlbase.h`| +|[`CA2AEX`](../../atl/reference/ca2aex-class.md)|This class is used by the string conversion macros `CA2TEX` and `CT2AEX`, and the typedef `CA2A`.|`atlconv.h`| +|[`CA2CAEX`](../../atl/reference/ca2caex-class.md)|This class is used by string conversion macros `CA2CTEX` and `CT2CAEX`, and the typedef `CA2CA`.|`atlconv.h`| +|[`CA2WEX`](../../atl/reference/ca2wex-class.md)|This class is used by the string conversion macros `CA2TEX`, `CA2CTEX`, `CT2WEX`, and `CT2CWEX`, and the typedef `CA2W`.|`atlconv.h`| +|[`CAccessToken`](../../atl/reference/caccesstoken-class.md)|This class is a wrapper for an access token.|`atlsecurity.h`| +|[`CAcl`](../../atl/reference/cacl-class.md)|This class is a wrapper for an ACL (access-control list) structure.|`atlsecurity.h`| +|[`CAdapt`](../../atl/reference/cadapt-class.md)|This template is used to wrap classes that redefine the address-of operator to return something other than the address of the object.|`atlcomcli.h`| +|[`CAtlArray`](../../atl/reference/catlarray-class.md)|This class implements an array object.|`atlcoll.h`| +|[`CAtlAutoThreadModule`](../../atl/reference/catlautothreadmodule-class.md)|This class implements a thread-pooled, apartment-model COM server.|`atlbase.h`| +|[`CAtlAutoThreadModuleT`](../../atl/reference/catlautothreadmodulet-class.md)|This class provides methods for implementing a thread-pooled, apartment-model COM server.|`atlbase.h`| +|[`CAtlBaseModule`](../../atl/reference/catlbasemodule-class.md)|This class is instantiated in every ATL project.|`atlcore.h`| +|[`CAtlComModule`](../../atl/reference/catlcommodule-class.md)|This class implements a COM server module.|`atlbase.h`| +|[`CAtlDebugInterfacesModule`](../../atl/reference/catldebuginterfacesmodule-class.md)|This class provides support for debugging interfaces.|`atlbase.h`| +|[`CAtlDllModuleT`](../../atl/reference/catldllmodulet-class.md)|This class represents the module for a DLL.|`atlbase.h`| +|[`CAtlException`](../../atl/reference/catlexception-class.md)|This class defines an ATL exception.|`atlexcept.h`| +|[`CAtlExeModuleT`](../../atl/reference/catlexemodulet-class.md)|This class represents the module for an application.|`atlbase.h`| +|[`CAtlFile`](../../atl/reference/catlfile-class.md)|This class provides a thin wrapper around the Windows file-handling API.|`atlfile.h`| +|[`CAtlFileMapping`](../../atl/reference/catlfilemapping-class.md)|This class represents a memory-mapped file, adding a cast operator to the methods of [`CAtlFileMappingBase`](../../atl/reference/catlfilemappingbase-class.md).|`atlfile.h`| +|[`CAtlFileMappingBase`](../../atl/reference/catlfilemappingbase-class.md)|This class represents a memory-mapped file.|`atlfile.h`| +|[`CAtlList`](../../atl/reference/catllist-class.md)|This class provides methods for creating and managing a list object.|`atlcoll.h`| +|[`CAtlMap`](../../atl/reference/catlmap-class.md)|This class provides methods for creating and managing a map object.|`atlcoll.h`| +|[`CAtlModule`](../../atl/reference/catlmodule-class.md)|This class provides methods used by several ATL module classes.|`atlbase.h`| +|[`CAtlModuleT`](../../atl/reference/catlmodulet-class.md)|This class implements an ATL module.|`atlbase.h`| +|[`CAtlPreviewCtrlImpl`](../../atl/reference/catlpreviewctrlimpl-class.md)|This class is an ATL implementation of a window that is placed on a host window provided by the Shell for Rich Preview.|`atlpreviewctrlimpl`.h| +|[`CAtlServiceModuleT`](../../atl/reference/catlservicemodulet-class.md)|This class implements a service.|`atlbase.h`| +|[`CAtlTemporaryFile`](../../atl/reference/catltemporaryfile-class.md)|This class provides methods for the creation and use of a temporary file.|`atlfile.h`| +|[`CAtlTransactionManager`](../../atl/reference/catltransactionmanager-class.md)|This class provides a wrapper to Kernel Transaction Manager (KTM) functions.|`atltransactionmanager`.h| +|[`CAtlWinModule`](../../atl/reference/catlwinmodule-class.md)|This class provides support for ATL windowing components.|`atlbase.h`| +|[`CAutoPtr`](../../atl/reference/cautoptr-class.md)|This class represents a smart pointer object.|`atlbase.h`| +|[`CAutoPtrArray`](../../atl/reference/cautoptrarray-class.md)|This class provides methods useful when constructing an array of smart pointers.|`atlbase.h`| +|[`CAutoPtrElementTraits`](../../atl/reference/cautoptrelementtraits-class.md)|This class provides methods, static functions, and typedefs useful when creating collections of smart pointers.|`atlcoll.h`| +|[`CAutoPtrList`](../../atl/reference/cautoptrlist-class.md)|This class provides methods useful when constructing a list of smart pointers.|`atlcoll.h`| +|[`CAutoVectorPtr`](../../atl/reference/cautovectorptr-class.md)|This class represents a smart pointer object using vector new and delete operators.|`atlbase.h`| +|[`CAutoVectorPtrElementTraits`](../../atl/reference/cautovectorptrelementtraits-class.md)|This class provides methods, static functions, and typedefs useful when creating collections of smart pointers using vector new and delete operators.|`atlcoll.h`| +|[`CAxDialogImpl`](../../atl/reference/caxdialogimpl-class.md)|This class implements a dialog box (modal or modeless) that hosts ActiveX controls.|`atlwin.h`| +|[`CAxWindow`](../../atl/reference/caxwindow-class.md)|This class provides methods for manipulating a window hosting an ActiveX control.|`atlwin.h`| +|[`CAxWindow2T`](../../atl/reference/caxwindow2t-class.md)|This class provides methods for manipulating a window that hosts an ActiveX control and also has support for hosting licensed ActiveX controls.|`atlwin.h`| +|[`CBindStatusCallback`](../../atl/reference/cbindstatuscallback-class.md)|This class implements the `IBindStatusCallback` interface.|`atlctl.h`| +|[`CComAggObject`](../../atl/reference/ccomaggobject-class.md)|This class implements [`IUnknown`](/windows/win32/api/unknwn/nn-unknwn-iunknown) for an aggregated object.|`atlcom.h`| +|[`CComAllocator`](../../atl/reference/ccomallocator-class.md)|This class provides methods for managing memory using COM memory routines.|`atlbase.h`| +|[`CComApartment`](../../atl/reference/ccomapartment-class.md)|This class provides support for managing an apartment in a thread-pooled EXE module.|`atlbase.h`| +|[`CComAutoCriticalSection`](../../atl/reference/ccomautocriticalsection-class.md)|This class provides methods for obtaining and releasing ownership of a critical section object.|`atlcore.h`| +|[`CComAutoThreadModule`](../../atl/reference/ccomautothreadmodule-class.md)|As of ATL 7.0, `CComAutoThreadModule` is obsolete: see [ATL Modules](../../atl/atl-module-classes.md) for more details.|`atlbase.h`| +|[`CComBSTR`](../../atl/reference/ccombstr-class.md)|This class is a wrapper for BSTRs.|`atlbase.h`| +|[`CComCachedTearOffObject`](../../atl/reference/ccomcachedtearoffobject-class.md)|This class implements [`IUnknown`](/windows/win32/api/unknwn/nn-unknwn-iunknown) for a tear-off interface.|`atlcom.h`| +|[`CComClassFactory`](../../atl/reference/ccomclassfactory-class.md)|This class implements the [`IClassFactory`](/windows/win32/api/unknwnbase/nn-unknwnbase-iclassfactory) interface.|`atlcom.h`| +|[`CComClassFactory2`](../../atl/reference/ccomclassfactory2-class.md)|This class implements the [`IClassFactory2`](/windows/win32/api/ocidl/nn-ocidl-iclassfactory2) interface.|`atlcom.h`| +|[`CComClassFactoryAutoThread`](../../atl/reference/ccomclassfactoryautothread-class.md)|This class implements the [`IClassFactory`](/windows/win32/api/unknwnbase/nn-unknwnbase-iclassfactory) interface and allows objects to be created in multiple apartments.|`atlcom.h`| +|[`CComClassFactorySingleton`](../../atl/reference/ccomclassfactorysingleton-class.md)|This class derives from [`CComClassFactory`](../../atl/reference/ccomclassfactory-class.md) and uses [`CComObjectGlobal`](../../atl/reference/ccomobjectglobal-class.md) to construct a single object.|`atlcom.h`| +|[`CComCoClass`](../../atl/reference/ccomcoclass-class.md)|This class provides methods for creating instances of a class and obtaining its properties.|`atlcom.h`| +|[`CComCompositeControl`](../../atl/reference/ccomcompositecontrol-class.md)|This class provides the methods required to implement a composite control.|`atlctl.h`| +|[`CComContainedObject`](../../atl/reference/ccomcontainedobject-class.md)|This class implements [`IUnknown`](/windows/win32/api/unknwn/nn-unknwn-iunknown) by delegating to the owner object's `IUnknown`.|`atlcom.h`| +|[`CComControl`](../../atl/reference/ccomcontrol-class.md)|This class provides methods for creating and managing ATL controls.|`atlctl.h`| +|[`CComControlBase`](../../atl/reference/ccomcontrolbase-class.md)|This class provides methods for creating and managing ATL controls.|`atlctl.h`| +|[`CComCriticalSection`](../../atl/reference/ccomcriticalsection-class.md)|This class provides methods for obtaining and releasing ownership of a critical section object.|`atlcore.h`| +|[`CComCritSecLock`](../../atl/reference/ccomcritseclock-class.md)|This class provides methods for locking and unlocking a critical section object.|`atlbase.h`| +|[`CComCurrency`](../../atl/reference/ccomcurrency-class.md)|This class has methods and operators for creating and managing a `CURRENCY` object.|`atlcur.h`| +|[`CComDynamicUnkArray`](../../atl/reference/ccomdynamicunkarray-class.md)|This class stores an array of `IUnknown` pointers.|`atlcom.h`| +|[`CComEnum`](../../atl/reference/ccomenum-class.md)|This class defines a COM enumerator object based on an array.|`atlcom.h`| +|[`CComEnumImpl`](../../atl/reference/ccomenumimpl-class.md)|This class provides the implementation for a COM enumerator interface where the items being enumerated are stored in an array.|`atlcom.h`| +|[`CComEnumOnSTL`](../../atl/reference/ccomenumonstl-class.md)|This class defines a COM enumerator object based on a C++ Standard Library collection.|`atlcom.h`| +|[`CComFakeCriticalSection`](../../atl/reference/ccomfakecriticalsection-class.md)|This class provides the same methods as [`CComCriticalSection`](../../atl/reference/ccomcriticalsection-class.md) but doesn't provide a critical section.|`atlcore.h`| +|[`CComGITPtr`](../../atl/reference/ccomgitptr-class.md)|This class provides methods for dealing with interface pointers and the global interface table (GIT).|`atlbase.h`| +|[`CComHeap`](../../atl/reference/ccomheap-class.md)|This class implements [`IAtlMemMgr`](../../atl/reference/iatlmemmgr-class.md) using the COM memory allocation functions.|`ATLComMem.h`| +|[`CComHeapPtr`](../../atl/reference/ccomheapptr-class.md)|A smart pointer class for managing heap pointers.|`atlbase.h`| +|[`CComModule`](../../atl/reference/ccommodule-class.md)|As of ATL 7.0, `CComModule` is obsolete: see [ATL Modules](../../atl/atl-module-classes.md) for more details.|`atlbase.h`| +|[`CComMultiThreadModel`](../../atl/reference/ccommultithreadmodel-class.md)|This class provides thread-safe methods for incrementing and decrementing the value of a variable.|`atlbase.h`| +|[`CComMultiThreadModelNoCS`](../../atl/reference/ccommultithreadmodelnocs-class.md)|This class provides thread-safe methods for incrementing and decrementing the value of a variable, without critical section locking or unlocking functionality.|`atlbase.h`| +|[`CComObject`](../../atl/reference/ccomobject-class.md)|This class implements `IUnknown` for a nonaggregated object.|`atlcom.h`| +|[`CComObjectGlobal`](../../atl/reference/ccomobjectglobal-class.md)|This class manages a reference count on the module containing your `Base` object.|`atlcom.h`| +|[`CComObjectNoLock`](../../atl/reference/ccomobjectnolock-class.md)|This class implements `IUnknown` for a nonaggregated object, but doesn't increment the module lock count in the constructor.|`atlcom.h`| +|[`CComObjectRoot`](../../atl/reference/ccomobjectroot-class.md)|This typedef of [`CComObjectRootEx`](../../atl/reference/ccomobjectrootex-class.md) is templatized on the default threading model of the server.|`atlcom.h`| +|[`CComObjectRootEx`](../../atl/reference/ccomobjectrootex-class.md)|This class provides methods to handle object reference count management for both nonaggregated and aggregated objects.|`atlcom.h`| +|[`CComObjectStack`](../../atl/reference/ccomobjectstack-class.md)|This class creates a temporary COM object and provides it with a skeletal implementation of `IUnknown`.|`atlcom.h`| +|[`CComPolyObject`](../../atl/reference/ccompolyobject-class.md)|This class implements `IUnknown` for an aggregated or nonaggregated object.|`atlcom.h`| +|[`CComPtr`](../../atl/reference/ccomptr-class.md)|A smart pointer class for managing COM interface pointers.|`atlcomcli.h`| +|[`CComPtrBase`](../../atl/reference/ccomptrbase-class.md)|This class provides a basis for smart pointer classes using COM-based memory routines.|`atlcomcli.h`| +|[`CComQIPtr`](../../atl/reference/ccomqiptr-class.md)|A smart pointer class for managing COM interface pointers.|`atlcomcli.h`| +|[`CComQIPtrElementTraits`](../../atl/reference/ccomqiptrelementtraits-class.md)|This class provides methods, static functions, and typedefs useful when creating collections of COM interface pointers.|`atlcoll.h`| +|[`CComSafeArray`](../../atl/reference/ccomsafearray-class.md)|This class is a wrapper for the `SAFEARRAY Data Type` structure.|`atlsafe.h`| +|[`CComSafeArrayBound`](../../atl/reference/ccomsafearraybound-class.md)|This class is a wrapper for a `SAFEARRAYBOUND` structure.|`atlsafe.h`| +|[`CComSimpleThreadAllocator`](../../atl/reference/ccomsimplethreadallocator-class.md)|This class manages thread selection for the class [`CComAutoThreadModule`](../../atl/reference/ccomautothreadmodule-class.md).|`atlbase.h`| +|[`CComSingleThreadModel`](../../atl/reference/ccomsinglethreadmodel-class.md)|This class provides methods for incrementing and decrementing the value of a variable.|`atlbase.h`| +|[`CComTearOffObject`](../../atl/reference/ccomtearoffobject-class.md)|This class implements a tear-off interface.|`atlcom.h`| +|[`CComUnkArray`](../../atl/reference/ccomunkarray-class.md)|This class stores `IUnknown` pointers and is designed to be used as a parameter to the [`IConnectionPointImpl`](../../atl/reference/iconnectionpointimpl-class.md) template class.|`atlcom.h`| +|[`CComVariant`](../../atl/reference/ccomvariant-class.md)|This class wraps the `VARIANT` type, providing a member indicating the type of data stored.|`atlcomcli.h`| +|[`CContainedWindowT`](../../atl/reference/ccontainedwindowt-class.md)|This class implements a window contained within another object.|`atlwin.h`| +|[`CCRTAllocator`](../../atl/reference/ccrtallocator-class.md)|This class provides methods for managing memory using CRT memory routines.|`atlcore.h`| +|[`CCRTHeap`](../../atl/reference/ccrtheap-class.md)|This class implements [`IAtlMemMgr`](../../atl/reference/iatlmemmgr-class.md) using the CRT heap functions.|`atlmem.h`| +|[`CDacl`](../../atl/reference/cdacl-class.md)|This class is a wrapper for a DACL (discretionary access-control list) structure.|`atlsecurity.h`| +|[`CDebugReportHook` Class](../../atl/reference/cdebugreporthook-class.md)|Use this class to send debug reports to a named pipe.|`atlutil.h`| +|[`CDefaultCharTraits`](../../atl/reference/cdefaultchartraits-class.md)|This class provides two static functions for converting characters between uppercase and lowercase.|`atlcoll.h`| +|[`CDefaultCompareTraits`](../../atl/reference/cdefaultcomparetraits-class.md)|This class provides default element comparison functions.|`atlcoll.h`| +|[`CDefaultElementTraits`](../../atl/reference/cdefaultelementtraits-class.md)|This class provides default methods and functions for a collection class.|`atlcoll.h`| +|[`CDefaultHashTraits`](../../atl/reference/cdefaulthashtraits-class.md)|This class provides a static function for calculating hash values.|`atlcoll.h`| +|[`CDialogImpl`](../../atl/reference/cdialogimpl-class.md)|This class provides methods for creating a modal or modeless dialog box.|`atlwin.h`| +|[`CDynamicChain`](../../atl/reference/cdynamicchain-class.md)|This class provides methods supporting the dynamic chaining of message maps.|`atlwin.h`| +|[`CElementTraits`](../../atl/reference/celementtraits-class.md)|This class is used by collection classes to provide methods and functions for moving, copying, comparison, and hashing operations.|`atlcoll.h`| +|[`CElementTraitsBase`](../../atl/reference/celementtraitsbase-class.md)|This class provides default copy and move methods for a collection class.|`atlcoll.h`| +|[`CFirePropNotifyEvent`](../../atl/reference/cfirepropnotifyevent-class.md)|This class provides methods for notifying the container's sink regarding control property changes.|`atlctl.h`| +|[`CGlobalHeap`](../../atl/reference/cglobalheap-class.md)|This class implements [`IAtlMemMgr`](../../atl/reference/iatlmemmgr-class.md) using the Win32 global heap functions.|`atlmem.h`| +|[`CHandle`](../../atl/reference/chandle-class.md)|This class provides methods for creating and using a handle object.|`atlbase.h`| +|[`CHeapPtr`](../../atl/reference/cheapptr-class.md)|A smart pointer class for managing heap pointers.|`atlcore.h`| +|[`CHeapPtrBase`](../../atl/reference/cheapptrbase-class.md)|This class forms the basis for several smart heap pointer classes.|`atlcore.h`| +|[`CHeapPtrElementTraits` Class](../../atl/reference/cheapptrelementtraits-class.md)|This class provides methods, static functions, and typedefs useful when creating collections of heap pointers.|`atlcoll.h`| +|[`CHeapPtrList`](../../atl/reference/cheapptrlist-class.md)|This class provides methods useful when constructing a list of heap pointers.|`atlcoll.h`| +|[`CImage`](../../atl-mfc-shared/reference/cimage-class.md)|Provides enhanced bitmap support, including the ability to load and save images in JPEG, GIF, BMP, and Portable Network Graphics (PNG) formats.|`atlimage.h`| +|[`CInterfaceArray`](../../atl/reference/cinterfacearray-class.md)|This class provides methods useful when constructing an array of COM interface pointers.|`atlcoll.h`| +|[`CInterfaceList`](../../atl/reference/cinterfacelist-class.md)|This class provides methods useful when constructing a list of COM interface pointers.|`atlcoll.h`| +|[`CLocalHeap`](../../atl/reference/clocalheap-class.md)|This class implements [`IAtlMemMgr`](../../atl/reference/iatlmemmgr-class.md) using the Win32 local heap functions.|`atlmem.h`| +|[`CMessageMap`](../../atl/reference/cmessagemap-class.md)|This class allows an object's message maps to be accessed by another object.|`atlwin.h`| +|[`CNonStatelessWorker` Class](../../atl/reference/cnonstatelessworker-class.md)|Receives requests from a thread pool and passes them on to a worker object that is created and destroyed on each request.|`atlutil.h`| +|[`CNoWorkerThread` Class](../../atl/reference/cnoworkerthread-class.md)|Use this class as the argument for the `MonitorClass` template parameter cache classes if you want to disable dynamic cache maintenance.|`atlutil.h`| +|[`CPathT` Class](../../atl/reference/cpatht-class.md)|This class represents a path.|`atlpath.h`| +|[`CPrimitiveElementTraits`](../../atl/reference/cprimitiveelementtraits-class.md)|This class provides default methods and functions for a collection class composed of primitive data types.|`atlcoll.h`| +|[`CPrivateObjectSecurityDesc`](../../atl/reference/cprivateobjectsecuritydesc-class.md)|This class represents a private object security descriptor object.|`atlsecurity.h`| +|[`CRBMap`](../../atl/reference/crbmap-class.md)|This class represents a mapping structure, using a Red-Black binary tree.|`atlcoll.h`| +|[`CRBMultiMap`](../../atl/reference/crbmultimap-class.md)|This class represents a mapping structure that allows each key to be associated with more than one value, using a Red-Black binary tree.|`atlcoll.h`| +|[`CRBTree`](../../atl/reference/crbtree-class.md)|This class provides methods for creating and utilizing a Red-Black tree.|`atlcoll.h`| +|[`CRegKey`](../../atl/reference/cregkey-class.md)|This class provides methods for manipulating entries in the system registry.|`atlbase.h`| +|[`CRTThreadTraits`](../../atl/reference/crtthreadtraits-class.md)|This class provides the creation function for a CRT thread. Use this class if the thread will use CRT functions.|`atlbase.h`| +|[`CSacl`](../../atl/reference/csacl-class.md)|This class is a wrapper for a SACL (system access-control list) structure.|`atlsecurity.h`| +|[`CSecurityAttributes`](../../atl/reference/csecurityattributes-class.md)|This class is a thin wrapper for the `SECURITY_ATTRIBUTES` structure.|`atlsecurity.h`| +|[`CSecurityDesc`](../../atl/reference/csecuritydesc-class.md)|This class is a wrapper for the `SECURITY_DESCRIPTOR` structure.|`atlsecurity.h`| +|[`CSid`](../../atl/reference/csid-class.md)|This class is a wrapper for a `SID` (security identifier) structure.|`atlsecurity.h`| +|[`CSimpleArray`](../../atl/reference/csimplearray-class.md)|This class provides methods for managing a simple array.|`atlsimpcoll.h`| +|[`CSimpleArrayEqualHelper`](../../atl/reference/csimplearrayequalhelper-class.md)|This class is a helper for the [`CSimpleArray`](../../atl/reference/csimplearray-class.md) class.|`atlsimpcoll.h`| +|[`CSimpleArrayEqualHelperFalse`](../../atl/reference/csimplearrayequalhelperfalse-class.md)|This class is a helper for the [`CSimpleArray`](../../atl/reference/csimplearray-class.md) class.|`atlsimpcoll.h`| +|[`CSimpleDialog`](../../atl/reference/csimpledialog-class.md)|This class implements a basic modal dialog box.|`atlwin.h`| +|[`CSimpleMap`](../../atl/reference/csimplemap-class.md)|This class provides support for a simple mapping array.|`atlsimpcoll.h`| +|[`CSimpleMapEqualHelper`](../../atl/reference/csimplemapequalhelper-class.md)|This class is a helper for the [`CSimpleMap`](../../atl/reference/csimplemap-class.md) class.|`atlsimpcoll.h`| +|[`CSimpleMapEqualHelperFalse`](../../atl/reference/csimplemapequalhelperfalse-class.md)|This class is a helper for the [`CSimpleMap`](../../atl/reference/csimplemap-class.md) class.|`atlsimpcoll.h`| +|[`CSnapInItemImpl`](../../atl/reference/csnapinitemimpl-class.md)|This class provides methods for implementing a snap-in node object.|`atlsnap.h`| +|[`CSnapInPropertyPageImpl`](../../atl/reference/csnapinpropertypageimpl-class.md)|This class provides methods for implementing a snap-in property page object.|`atlsnap.h`| +|[`CStockPropImpl`](../../atl/reference/cstockpropimpl-class.md)|This class provides methods for supporting stock property values.|`atlctl.h`| +|[`CStringElementTraits`](../../atl/reference/cstringelementtraits-class.md)|This class provides static functions used by collection classes storing `CString` objects.|`cstringt`.h| +|[`CStringElementTraitsI`](../../atl/reference/cstringelementtraitsi-class.md)|This class provides static functions related to strings stored in collection class objects. It's similar to [`CStringElementTraits`](../../atl/reference/cstringelementtraits-class.md), but performs case-insensitive comparisons.|`atlcoll.h`| +|[`CStringRefElementTraits`](../../atl/reference/cstringrefelementtraits-class.md)|This class provides static functions related to strings stored in collection class objects. The string objects are dealt with as references.|`atlcoll.h`| +|[`CThreadPool` Class](../../atl/reference/cthreadpool-class.md)|This class provides a pool of worker threads that process a queue of work items.|`atlutil.h`| +|[`CTokenGroups`](../../atl/reference/ctokengroups-class.md)|This class is a wrapper for the `TOKEN_GROUPS` structure.|`atlsecurity.h`| +|[`CTokenPrivileges`](../../atl/reference/ctokenprivileges-class.md)|This class is a wrapper for the `TOKEN_PRIVILEGES` structure.|`atlsecurity.h`| +|[`CUrl` Class](../../atl/reference/curl-class.md)|This class represents a URL. It allows you to manipulate each element of the URL independently of the others whether parsing an existing URL string or building a string from scratch.|`atlutil.h`| +|[`CW2AEX`](../../atl/reference/cw2aex-class.md)|This class is used by the string conversion macros `CT2AEX`, `CW2TEX`, `CW2CTEX`, and `CT2CAEX`, and the typedef `CW2A`.|`atlconv.h`| +|[`CW2CWEX`](../../atl/reference/cw2cwex-class.md)|This class is used by the string conversion macros `CW2CTEX` and `CT2CWEX`, and the typedef `CW2CW`.|`atlconv.h`| +|[`CW2WEX`](../../atl/reference/cw2wex-class.md)|This class is used by the string conversion macros `CW2TEX` and `CT2WEX`, and the typedef `CW2W`.|`atlconv.h`| +|[`CWin32Heap`](../../atl/reference/cwin32heap-class.md)|This class implements [`IAtlMemMgr`](../../atl/reference/iatlmemmgr-class.md) using the Win32 heap allocation functions.|`atlmem.h`| +|[`CWindow`](../../atl/reference/cwindow-class.md)|This class provides methods for manipulating a window.|`atlwin.h`| +|[`CWindowImpl`](../../atl/reference/cwindowimpl-class.md)|This class provides methods for creating or subclassing a window.|`atlwin.h`| +|[`CWinTraits`](../../atl/reference/cwintraits-class.md)|This class provides a method for standardizing the styles used when creating a window object.|`atlwin.h`| +|[`CWinTraitsOR`](../../atl/reference/cwintraitsor-class.md)|This class provides a method for standardizing the styles used when creating a window object.|`atlwin.h`| +|[`CWndClassInfo`](../../atl/reference/cwndclassinfo-class.md)|This class provides methods for registering information for a window class.|`atlwin.h`| +|[`CWorkerThread` Class](../../atl/reference/cworkerthread-class.md)|This class creates a worker thread or uses an existing one, waits on one or more kernel object handles, and executes a specified client function when one of the handles is signaled.|`atlutil.h`| +|[`IAtlAutoThreadModule`](../../atl/reference/iatlautothreadmodule-class.md)|This class represents an interface to a `CreateInstance` method.|`atlbase.h`| +|[`IAtlMemMgr`](../../atl/reference/iatlmemmgr-class.md)|This class represents the interface to a memory manager.|`atlmem.h`| +|[`IAxWinAmbientDispatch`](../../atl/reference/iaxwinambientdispatch-interface.md)|This interface provides methods for specifying characteristics of the hosted control or container.|`atlbase.h`, `ATLIFace.h`| +|[`IAxWinAmbientDispatchEx`](../../atl/reference/iaxwinambientdispatchex-interface.md)|This interface implements supplemental ambient properties for a hosted control.|`atlbase.h`, `ATLIFace.h`| +|[`IAxWinHostWindow`](../../atl/reference/iaxwinhostwindow-interface.md)|This interface provides methods for manipulating a control and its host object.|`atlbase.h`, `ATLIFace.h`| +|[`IAxWinHostWindowLic`](../../atl/reference/iaxwinhostwindowlic-interface.md)|This interface provides methods for manipulating a licensed control and its host object.|`atlbase.h`, `ATLIFace.h`| +|[`ICollectionOnSTLImpl`](../../atl/reference/icollectiononstlimpl-class.md)|This class provides methods used by a collection class.|`atlcom.h`| +|[`IConnectionPointContainerImpl`](../../atl/reference/iconnectionpointcontainerimpl-class.md)|This class implements a connection point container to manage a collection of [`IConnectionPointImpl`](../../atl/reference/iconnectionpointimpl-class.md) objects.|`atlcom.h`| +|[`IConnectionPointImpl`](../../atl/reference/iconnectionpointimpl-class.md)|This class implements a connection point.|`atlcom.h`| +|[`IDataObjectImpl`](../../atl/reference/idataobjectimpl-class.md)|This class provides methods for supporting Uniform Data Transfer and managing connections.|`atlctl.h`| +|[`IDispatchImpl`](../../atl/reference/idispatchimpl-class.md)|This class provides a default implementation for the `IDispatch` portion of a dual interface.|`atlcom.h`| +|[`IDispEventImpl`](../../atl/reference/idispeventimpl-class.md)|This class provides implementations of the `IDispatch` methods.|`atlcom.h`| +|[`IDispEventSimpleImpl`](../../atl/reference/idispeventsimpleimpl-class.md)|This class provides implementations of the `IDispatch` methods, without getting type information from a type library.|`atlcom.h`| +|[`IDocHostUIHandlerDispatch`](../../atl/reference/idochostuihandlerdispatch-interface.md)|An interface to the Microsoft HTML parsing and rendering engine.|`atlbase.h`, `ATLIFace.h`| +|[`IEnumOnSTLImpl`](../../atl/reference/ienumonstlimpl-class.md)|This class defines an enumerator interface based on a C++ Standard Library collection.|`atlcom.h`| +|[`IObjectSafetyImpl`](../../atl/reference/iobjectsafetyimpl-class.md)|This class provides a default implementation of the `IObjectSafety` interface to allow a client to retrieve and set an object's safety levels.|`atlctl.h`| +|[`IObjectWithSiteImpl`](../../atl/reference/iobjectwithsiteimpl-class.md)|This class provides methods allowing an object to communicate with its site.|`atlcom.h`| +|[`IOleControlImpl`](../../atl/reference/iolecontrolimpl-class.md)|This class provides a default implementation of the `IOleControl` interface and implements `IUnknown`.|`atlctl.h`| +|[`IOleInPlaceActiveObjectImpl`](../../atl/reference/ioleinplaceactiveobjectimpl-class.md)|This class provides methods for assisting communication between an in-place control and its container.|`atlctl.h`| +|[`IOleInPlaceObjectWindowlessImpl`](../../atl/reference/ioleinplaceobjectwindowlessimpl-class.md)|This class implements `IUnknown` and provides methods that enable a windowless control to receive window messages and to participate in drag-and-drop operations.|`atlctl.h`| +|[`IOleObjectImpl`](../../atl/reference/ioleobjectimpl-class.md)|This class implements `IUnknown` and is the principal interface through which a container communicates with a control.|`atlctl.h`| +|[`IPerPropertyBrowsingImpl`](../../atl/reference/iperpropertybrowsingimpl-class.md)|This class implements `IUnknown` and allows a client to access the information in an object's property pages.|`atlctl.h`| +|[`IPersistPropertyBagImpl`](../../atl/reference/ipersistpropertybagimpl-class.md)|This class implements `IUnknown` and allows an object to save its properties to a client-supplied property bag.|`atlcom.h`| +|[`IPersistStorageImpl`](../../atl/reference/ipersiststorageimpl-class.md)|This class implements the [`IPersistStorage`](/windows/win32/api/objidl/nn-objidl-ipersiststorage) interface.|`atlcom.h`| +|[`IPersistStreamInitImpl`](../../atl/reference/ipersiststreaminitimpl-class.md)|This class implements `IUnknown` and provides a default implementation of the [`IPersistStreamInit`](/windows/win32/api/ocidl/nn-ocidl-ipersiststreaminit) interface.|`atlcom.h`| +|[`IPointerInactiveImpl`](../../atl/reference/ipointerinactiveimpl-class.md)|This class implements `IUnknown` and the [`IPointerInactive`](/windows/win32/api/ocidl/nn-ocidl-ipointerinactive) interface methods.|`atlctl.h`| +|[`IPropertyNotifySinkCP`](../../atl/reference/ipropertynotifysinkcp-class.md)|This class exposes the [`IPropertyNotifySink`](/windows/win32/api/ocidl/nn-ocidl-ipropertynotifysink) interface as an outgoing interface on a connectable object.|`atlctl.h`| +|[`IPropertyPage2Impl`](../../atl/reference/ipropertypage2impl-class.md)|This class implements `IUnknown` and inherits the default implementation of [`IPropertyPageImpl`](../../atl/reference/ipropertypageimpl-class.md).|`atlctl.h`| +|[`IPropertyPageImpl`](../../atl/reference/ipropertypageimpl-class.md)|This class implements `IUnknown` and provides a default implementation of the [`IPropertyPage`](/windows/win32/api/ocidl/nn-ocidl-ipropertypage) interface.|`atlctl.h`| +|[`IProvideClassInfo2Impl`](../../atl/reference/iprovideclassinfo2impl-class.md)|This class provides a default implementation of the [`IProvideClassInfo`](/windows/win32/api/ocidl/nn-ocidl-iprovideclassinfo) and [`IProvideClassInfo2`](/windows/win32/api/ocidl/nn-ocidl-iprovideclassinfo2) methods.|`atlcom.h`| +|[`IQuickActivateImpl`](../../atl/reference/iquickactivateimpl-class.md)|This class combines containers' control initialization into a single call.|`atlctl.h`| +|[`IRunnableObjectImpl`](../../atl/reference/irunnableobjectimpl-class.md)|This class implements `IUnknown` and provides a default implementation of the [`IRunnableObject`](/windows/win32/api/objidl/nn-objidl-irunnableobject) interface.|`atlctl.h`| +|[`IServiceProviderImpl`](../../atl/reference/iserviceproviderimpl-class.md)|This class provides a default implementation of the `IServiceProvider` interface.|`atlcom.h`| +|[`ISpecifyPropertyPagesImpl`](../../atl/reference/ispecifypropertypagesimpl-class.md)|This class implements `IUnknown` and provides a default implementation of the [`ISpecifyPropertyPages`](/windows/win32/api/ocidl/nn-ocidl-ispecifypropertypages) interface.|`atlcom.h`| +|[`ISupportErrorInfoImpl`](../../atl/reference/isupporterrorinfoimpl-class.md)|This class provides a default implementation of the `ISupportErrorInfo Interface` interface and can be used when only a single interface generates errors on an object.|`atlcom.h`| +|[`IThreadPoolConfig` Interface](../../atl/reference/ithreadpoolconfig-interface.md)|This interface provides methods for configuring a thread pool.|`atlutil.h`| +|[`IViewObjectExImpl`](../../atl/reference/iviewobjecteximpl-class.md)|This class implements `IUnknown` and provides default implementations of the [`IViewObject`](/windows/win32/api/oleidl/nn-oleidl-iviewobject), [`IViewObject2`](/windows/win32/api/oleidl/nn-oleidl-iviewobject2), and [`IViewObjectEx`](/windows/win32/api/ocidl/nn-ocidl-iviewobjectex) interfaces.|`atlctl.h`| +|[`IWorkerThreadClient` Interface](../../atl/reference/iworkerthreadclient-interface.md)|`IWorkerThreadClient` is the interface implemented by clients of the [`CWorkerThread`](../../atl/reference/cworkerthread-class.md) class.|`atlutil.h`| +|[`_U_MENUorID`](../../atl/reference/u-menuorid-class.md)|This class provides wrappers for `CreateWindow` and `CreateWindowEx`.|`atlwin.h`| +|[`_U_RECT`](../../atl/reference/u-rect-class.md)|This argument adapter class allows either `RECT` pointers or references to be passed to a function that is implemented in terms of pointers.|`atlwin.h`| +|[`_U_STRINGorID`](../../atl/reference/u-stringorid-class.md)|This argument adapter class allows either resource names (LPCTSTRs) or resource IDs (UINTs) to be passed to a function without requiring the caller to convert the ID to a string using the `MAKEINTRESOURCE` macro.|`atlwin.h`| +|[`Win32ThreadTraits`](../../atl/reference/win32threadtraits-class.md)|This class provides the creation function for a Windows thread. Use this class if the thread won't use CRT functions.|`atlbase.h`| ## See also -[ATL COM Desktop Components](../../atl/atl-com-desktop-components.md)
-[Functions](../../atl/reference/atl-functions.md)
-[Global Variables](../../atl/reference/atl-global-variables.md)
-[Typedefs](../../atl/reference/atl-typedefs.md)
+[ATL COM Desktop Components](../../atl/atl-com-desktop-components.md)\ +[Functions](../../atl/reference/atl-functions.md)\ +[Global Variables](../../atl/reference/atl-global-variables.md)\ +[Typedefs](../../atl/reference/atl-typedefs.md)\ [Class Overview](../../atl/atl-class-overview.md) diff --git a/docs/atl/reference/atl-com-plus-1-0-component-wizard.md b/docs/atl/reference/atl-com-plus-1-0-component-wizard.md index 2234a04e69..4f342caa93 100644 --- a/docs/atl/reference/atl-com-plus-1-0-component-wizard.md +++ b/docs/atl/reference/atl-com-plus-1-0-component-wizard.md @@ -7,7 +7,7 @@ ms.assetid: 11670681-8671-4122-96a4-2e52f8dadce0 --- # ATL COM+ 1.0 Component Wizard -::: moniker range="msvc-160" +::: moniker range=">=msvc-160" This wizard is not available in Visual Studio 2019 and later. diff --git a/docs/atl/reference/atl-ole-db-consumer-wizard.md b/docs/atl/reference/atl-ole-db-consumer-wizard.md index 9689825beb..da09ffeebb 100644 --- a/docs/atl/reference/atl-ole-db-consumer-wizard.md +++ b/docs/atl/reference/atl-ole-db-consumer-wizard.md @@ -7,7 +7,7 @@ ms.assetid: dcb68ed1-2224-422f-9f7b-108a74864204 --- # ATL OLE DB Consumer Wizard -::: moniker range="msvc-160" +::: moniker range=">=msvc-160" This wizard is not available in Visual Studio 2019 and later. diff --git a/docs/atl/reference/atl-ole-db-provider-wizard.md b/docs/atl/reference/atl-ole-db-provider-wizard.md index 571ebc9495..29417f6f85 100644 --- a/docs/atl/reference/atl-ole-db-provider-wizard.md +++ b/docs/atl/reference/atl-ole-db-provider-wizard.md @@ -7,7 +7,7 @@ ms.assetid: cf91ba78-01d1-4d12-b673-e95d96bfbebe --- # ATL OLE DB Provider Wizard -::: moniker range="msvc-160" +::: moniker range=">=msvc-160" This wizard is not available in Visual Studio 2019 and later. diff --git a/docs/atl/reference/atl-property-page-wizard.md b/docs/atl/reference/atl-property-page-wizard.md index 895ff9bbb7..16c0045690 100644 --- a/docs/atl/reference/atl-property-page-wizard.md +++ b/docs/atl/reference/atl-property-page-wizard.md @@ -8,7 +8,7 @@ ms.assetid: 6113e325-facd-4f68-b491-144d75209922 --- # ATL Property Page Wizard -::: moniker range="msvc-160" +::: moniker range=">=msvc-160" This wizard is not available in Visual Studio 2019 and later. diff --git a/docs/atl/reference/atl-text-encoding-functions.md b/docs/atl/reference/atl-text-encoding-functions.md index 1ecb343932..aa50e31f2e 100644 --- a/docs/atl/reference/atl-text-encoding-functions.md +++ b/docs/atl/reference/atl-text-encoding-functions.md @@ -335,13 +335,13 @@ The length in characters of the converted string. Possible conversions performed by this function are shown in the table: -|Source|Destination| -|------------|-----------------| -|\<|<| -|>|>| -|&|&| -|'|'| -|"|"| +| Source | Destination | +|--|--| +| \< | \< | +| > | \> | +| & | \& | +| ' | \' | +| " | \" | ## GetExtendedChars diff --git a/docs/atl/reference/cadapt-class.md b/docs/atl/reference/cadapt-class.md index ee86649138..e3596e34f0 100644 --- a/docs/atl/reference/cadapt-class.md +++ b/docs/atl/reference/cadapt-class.md @@ -92,7 +92,7 @@ T m_T; This **`public`** data member can be accessed directly or indirectly with [operator const T&](#operator_const_t_amp) and [operator T&](#operator_t_amp). -## CAdapt::operator const T& +## CAdapt::operator const T& Returns a **`const`** reference to the [m_T](#m_t) member, allowing the adapter object to be treated as if it were an object of type *T*. @@ -104,7 +104,7 @@ operator const T&() const; A **`const`** reference to `m_T`. -## CAdapt::operator T& +## CAdapt::operator T& Returns a reference to the [m_T](#m_t) member, allowing the adapter object to be treated as if it were an object of type *T*. @@ -116,7 +116,7 @@ operator T&(); A reference to `m_T`. -## CAdapt::operator < +## `CAdapt::operator <` Compares an object of the adapted type with [m_T](#m_t). diff --git a/docs/atl/reference/category-macros.md b/docs/atl/reference/category-macros.md index ecb6b7b4a5..2520af5960 100644 --- a/docs/atl/reference/category-macros.md +++ b/docs/atl/reference/category-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: Category Macros" title: "Category Macros" ms.date: "11/04/2016" -f1_keywords: ["atlcom/ATL::BEGIN_CATEGORY_MAP", "atlcom/ATL::END_CATEGORY_MAP", "atlcom/ATL::IMPLEMENTED_CATEGORY", "atlcom/ATL::REQUIRED_CATEGORY"] +f1_keywords: ["ATLCOM/BEGIN_CATEGORY_MAP", "ATLCOM/END_CATEGORY_MAP", "ATLCOM/IMPLEMENTED_CATEGORY", "ATLCOM/REQUIRED_CATEGORY", "atlcom/ATL::BEGIN_CATEGORY_MAP", "atlcom/ATL::END_CATEGORY_MAP", "atlcom/ATL::IMPLEMENTED_CATEGORY", "atlcom/ATL::REQUIRED_CATEGORY"] ms.assetid: 223578cb-6180-4787-a8d8-ba3787a5d3ee --- # Category Macros diff --git a/docs/atl/reference/catlarray-class.md b/docs/atl/reference/catlarray-class.md index 2f8dcb02a2..e2ff7b40f5 100644 --- a/docs/atl/reference/catlarray-class.md +++ b/docs/atl/reference/catlarray-class.md @@ -54,7 +54,7 @@ The code used to copy or move elements. |Operator|Description| |-|-| -|[operator []](#operator_at)|Call this operator to return a reference to an element in the array.| +|[`operator []`](#operator_at)|Call this operator to return a reference to an element in the array.| ### Typedefs diff --git a/docs/atl/reference/catltemporaryfile-class.md b/docs/atl/reference/catltemporaryfile-class.md index ac4ae6210e..9878d4a0d9 100644 --- a/docs/atl/reference/catltemporaryfile-class.md +++ b/docs/atl/reference/catltemporaryfile-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CAtlTemporaryFile Class" title: "CAtlTemporaryFile Class" -ms.date: "11/04/2016" +description: "Learn more about: CAtlTemporaryFile Class" +ms.date: 11/04/2016 f1_keywords: ["CAtlTemporaryFile", "ATLFILE/ATL::CAtlTemporaryFile", "ATLFILE/ATL::CAtlTemporaryFile::CAtlTemporaryFile", "ATLFILE/ATL::CAtlTemporaryFile::Close", "ATLFILE/ATL::CAtlTemporaryFile::Create", "ATLFILE/ATL::CAtlTemporaryFile::Flush", "ATLFILE/ATL::CAtlTemporaryFile::GetPosition", "ATLFILE/ATL::CAtlTemporaryFile::GetSize", "ATLFILE/ATL::CAtlTemporaryFile::HandsOff", "ATLFILE/ATL::CAtlTemporaryFile::HandsOn", "ATLFILE/ATL::CAtlTemporaryFile::LockRange", "ATLFILE/ATL::CAtlTemporaryFile::Read", "ATLFILE/ATL::CAtlTemporaryFile::Seek", "ATLFILE/ATL::CAtlTemporaryFile::SetSize", "ATLFILE/ATL::CAtlTemporaryFile::TempFileName", "ATLFILE/ATL::CAtlTemporaryFile::UnlockRange", "ATLFILE/ATL::CAtlTemporaryFile::Write"] helpviewer_keywords: ["CAtlTemporaryFile class"] -ms.assetid: 05f0f2a5-94f6-4594-8dae-b114292ff5f9 --- # CAtlTemporaryFile Class @@ -357,7 +356,7 @@ Returns the LPCTSTR pointing to the file name. ### Remarks -The file name is generated in [CAtlTemporaryFile::CAtlTemporaryFile](#catltemporaryfile) with a call to the [GetTempFile](/windows/win32/api/fileapi/nf-fileapi-gettempfilenamew)Windows SDK function. The file extension will always be "TFR" for the temporary file. +The file name is generated in [CAtlTemporaryFile::CAtlTemporaryFile](#catltemporaryfile) with a call to the [GetTempFile](/windows/win32/api/fileapi/nf-fileapi-gettempfilenamew) Windows SDK function. The file extension will always be "TFR" for the temporary file. ## CAtlTemporaryFile::UnlockRange diff --git a/docs/atl/reference/catltransactionmanager-class.md b/docs/atl/reference/catltransactionmanager-class.md index 9a3cf494d6..3b7a42f274 100644 --- a/docs/atl/reference/catltransactionmanager-class.md +++ b/docs/atl/reference/catltransactionmanager-class.md @@ -165,7 +165,7 @@ inline HANDLE CreateFile( The name of an object to be created or opened. *dwDesiredAccess*
-The access to the object, which can be summarized as read, write, both, or neither (zero). The most commonly used values are GENERIC_READ, GENERIC_WRITE, or both: GENERIC_READ | GENERIC_WRITE. +The access to the object, which can be summarized as read, write, both, or neither (zero). The most commonly used values are `GENERIC_READ`, `GENERIC_WRITE`, or both: `GENERIC_READ | GENERIC_WRITE`. *dwShareMode*
The sharing mode of an object, which can be read, write, both, delete, all of these, or none: 0, FILE_SHARE_DELETE, FILE_SHARE_READ, FILE_SHARE_WRITE. diff --git a/docs/atl/reference/cautoptr-class.md b/docs/atl/reference/cautoptr-class.md index 68abb80ad8..ec51839b4b 100644 --- a/docs/atl/reference/cautoptr-class.md +++ b/docs/atl/reference/cautoptr-class.md @@ -1,12 +1,12 @@ --- -description: "Learn more about: CAutoPtr Class" -title: "CAutoPtr Class" +description: "Learn more about: CAutoPtr class" +title: "CAutoPtr class" ms.date: "11/04/2016" f1_keywords: ["CAutoPtr", "ATLBASE/ATL::CAutoPtr", "ATLBASE/ATL::CAutoPtr::CAutoPtr", "ATLBASE/ATL::CAutoPtr::Attach", "ATLBASE/ATL::CAutoPtr::Detach", "ATLBASE/ATL::CAutoPtr::Free", "ATLBASE/ATL::CAutoPtr::m_p"] helpviewer_keywords: ["CAutoPtr class"] ms.assetid: 08988d53-4fb0-4711-bdfc-8ac29c63f410 --- -# CAutoPtr Class +# `CAutoPtr` class This class represents a smart pointer object. @@ -22,51 +22,51 @@ class CAutoPtr ### Parameters -*T*
+*`T`*\ The pointer type. ## Members -### Public Constructors +### Public constructors -|Name|Description| -|----------|-----------------| -|[CAutoPtr::CAutoPtr](#cautoptr)|The constructor.| -|[CAutoPtr::~CAutoPtr](#dtor)|The destructor.| +| Name | Description | +|--|--| +| [`CAutoPtr::CAutoPtr`](#cautoptr) | The constructor. | +| [`CAutoPtr::~CAutoPtr`](#dtor) | The destructor. | -### Public Methods +### Public methods -|Name|Description| -|----------|-----------------| -|[CAutoPtr::Attach](#attach)|Call this method to take ownership of an existing pointer.| -|[CAutoPtr::Detach](#detach)|Call this method to release ownership of a pointer.| -|[CAutoPtr::Free](#free)|Call this method to delete an object pointed to by a `CAutoPtr`.| +| Name | Description | +|--|--| +| [`CAutoPtr::Attach`](#attach) | Call this method to take ownership of an existing pointer. | +| [`CAutoPtr::Detach`](#detach) | Call this method to release ownership of a pointer. | +| [`CAutoPtr::Free`](#free) | Call this method to delete an object pointed to by a `CAutoPtr`. | -### Public Operators +### Public operators -|Name|Description| -|----------|-----------------| -|[CAutoPtr::operator T*](#operator_t_star)|The cast operator.| -|[CAutoPtr::operator =](#operator_eq)|The assignment operator.| -|[CAutoPtr::operator ->](#operator_ptr)|The pointer-to-member operator.| +| Name | Description | +|--|--| +| [`CAutoPtr::operator T*`](#operator_t_star) | The cast operator. | +| [`CAutoPtr::operator =`](#operator_eq) | The assignment operator. | +| [`CAutoPtr::operator ->`](#operator_ptr) | The pointer-to-member operator. | -### Public Data Members +### Public data members -|Name|Description| -|----------|-----------------| -|[CAutoPtr::m_p](#m_p)|The pointer data member variable.| +| Name | Description | +|--|--| +| [`CAutoPtr::m_p`](#m_p) | The pointer data member variable. | ## Remarks -This class provides methods for creating and managing a smart pointer, which will help protect against memory leaks by automatically freeing resources when it falls out of scope. +This class provides methods for creating and managing a smart pointer. Smart pointers help protect against memory leaks by automatically freeing resources when it falls out of scope. -Further, `CAutoPtr`'s copy constructor and assignment operator transfer ownership of the pointer, copying the source pointer to the destination pointer and setting the source pointer to NULL. It is therefore impossible to have two `CAutoPtr` objects each storing the same pointer, and this reduces the possibility of deleting the same pointer twice. +Further, `CAutoPtr`'s copy constructor and assignment operator transfer ownership of the pointer, copying the source pointer to the destination pointer and setting the source pointer to NULL. That's why it's impossible to have two `CAutoPtr` objects each storing the same pointer, and it reduces the possibility of deleting the same pointer twice. `CAutoPtr` also simplifies the creation of collections of pointers. Instead of deriving a collection class and overriding the destructor, it's simpler to make a collection of `CAutoPtr` objects. When the collection is deleted, the `CAutoPtr` objects will go out of scope and automatically delete themselves. -[CHeapPtr](../../atl/reference/cheapptr-class.md) and variants work in the same way as `CAutoPtr`, except that they allocate and free memory using different heap functions instead of the C++ **`new`** and **`delete`** operators. [CAutoVectorPtr](../../atl/reference/cautovectorptr-class.md) is similar to `CAutoPtr`, the only difference being that it uses **vector new[]** and **vector delete[]** to allocate and free memory. +[`CHeapPtr`](../../atl/reference/cheapptr-class.md) and variants work in the same way as `CAutoPtr`, except that they allocate and free memory using different heap functions instead of the C++ **`new`** and **`delete`** operators. [`CAutoVectorPtr`](../../atl/reference/cautovectorptr-class.md) is similar to `CAutoPtr`, the only difference being that it uses **vector new[]** and **vector delete[]** to allocate and free memory. -See also [CAutoPtrArray](../../atl/reference/cautoptrarray-class.md) and [CAutoPtrList](../../atl/reference/cautoptrlist-class.md) when arrays or lists of smart pointers are required. +See also [`CAutoPtrArray`](../../atl/reference/cautoptrarray-class.md) and [`CAutoPtrList`](../../atl/reference/cautoptrlist-class.md) when arrays or lists of smart pointers are required. ## Requirements @@ -76,7 +76,7 @@ See also [CAutoPtrArray](../../atl/reference/cautoptrarray-class.md) and [CAutoP [!code-cpp[NVC_ATL_Utilities#74](../../atl/codesnippet/cpp/cautoptr-class_1.cpp)] -## CAutoPtr::Attach +## `CAutoPtr::Attach` Call this method to take ownership of an existing pointer. @@ -86,20 +86,20 @@ void Attach(T* p) throw(); ### Parameters -*p*
+*`p`*\ The `CAutoPtr` object will take ownership of this pointer. ### Remarks -When a `CAutoPtr` object takes ownership of a pointer, it will automatically delete the pointer and any allocated data when it goes out of scope. If [CAutoPtr::Detach](#detach) is called, the programmer is again given responsibility for freeing any allocated resources. +When a `CAutoPtr` object takes ownership of a pointer, it will automatically delete the pointer and any allocated data when it goes out of scope. If [`CAutoPtr::Detach`](#detach) is called, the programmer is again given responsibility for freeing any allocated resources. -In debug builds, an assertion failure will occur if the [CAutoPtr::m_p](#m_p) data member currently points to an existing value; that is, it is not equal to NULL. +In debug builds, an assertion failure will occur if the [`CAutoPtr::m_p`](#m_p) data member currently points to an existing value; that is, it's not equal to NULL. ### Example -See the example in the [CAutoPtr Overview](../../atl/reference/cautoptr-class.md). +See the example in the [`CAutoPtr` Overview](../../atl/reference/cautoptr-class.md). -## CAutoPtr::CAutoPtr +## `CAutoPtr::CAutoPtr` The constructor. @@ -116,10 +116,10 @@ CAutoPtr(CAutoPtr& p) throw(); ### Parameters -*p*
+*`p`*\ An existing pointer. -*TSrc*
+*`TSrc`*\ The type being managed by another `CAutoPtr`, used to initialize the current object. ### Remarks @@ -128,9 +128,9 @@ The `CAutoPtr` object can be created using an existing pointer, in which case it ### Example -See the example in the [CAutoPtr Overview](../../atl/reference/cautoptr-class.md). +See the example in the [`CAutoPtr` overview](../../atl/reference/cautoptr-class.md). -## CAutoPtr::~CAutoPtr +## `CAutoPtr::~CAutoPtr` The destructor. @@ -140,9 +140,9 @@ The destructor. ### Remarks -Frees any allocated resources. Calls [CAutoPtr::Free](#free). +Frees any allocated resources. Calls [`CAutoPtr::Free`](#free). -## CAutoPtr::Detach +## `CAutoPtr::Detach` Call this method to release ownership of a pointer. @@ -150,19 +150,19 @@ Call this method to release ownership of a pointer. T* Detach() throw(); ``` -### Return Value +### Return value Returns a copy of the pointer. ### Remarks -Releases ownership of a pointer, sets the [CAutoPtr::m_p](#m_p) data member variable to NULL, and returns a copy of the pointer. After calling `Detach`, it is up to the programmer to free any allocated resources over which the `CAutoPtr` object may have previously assumed reponsibility. +Releases ownership of a pointer, sets the [`CAutoPtr::m_p`](#m_p) data member variable to NULL, and returns a copy of the pointer. After calling `Detach`, it's up to the programmer to free any allocated resources over which the `CAutoPtr` object may have previously assumed responsibility. ### Example -See the example in the [CAutoPtr Overview](../../atl/reference/cautoptr-class.md). +See the example in the [`CAutoPtr` overview](../../atl/reference/cautoptr-class.md). -## CAutoPtr::Free +## `CAutoPtr::Free` Call this method to delete an object pointed to by a `CAutoPtr`. @@ -172,9 +172,9 @@ void Free() throw(); ### Remarks -The object pointed to by the `CAutoPtr` is freed, and the [CAutoPtr::m_p](#m_p) data member variable is set to NULL. +The object pointed to by the `CAutoPtr` is freed, and the [`CAutoPtr::m_p`](#m_p) data member variable is set to NULL. -## CAutoPtr::m_p +## `CAutoPtr::m_p` The pointer data member variable. @@ -186,7 +186,7 @@ T* m_p; This member variable holds the pointer information. -## CAutoPtr::operator = +## `CAutoPtr::operator =` The assignment operator. @@ -200,25 +200,25 @@ CAutoPtr& operator= (CAutoPtr& p); ### Parameters -*p*
+*`p`*\ A pointer. -*TSrc*
+*`TSrc`*\ A class type. -### Return Value +### Return value -Returns a reference to a **CAutoPtr\< T >**. +Returns a reference to a `CAutoPtr< T >`. ### Remarks -The assignment operator detaches the `CAutoPtr` object from any current pointer and attaches the new pointer, *p*, in its place. +The assignment operator detaches the `CAutoPtr` object from any current pointer and attaches the new pointer, *`p`*, in its place. ### Example -See the example in the [CAutoPtr Overview](../../atl/reference/cautoptr-class.md). +See the example in the [`CAutoPtr` overview](../../atl/reference/cautoptr-class.md). -## CAutoPtr::operator -> +## `CAutoPtr::operator ->` The pointer-to-member operator. @@ -226,9 +226,9 @@ The pointer-to-member operator. T* operator->() const throw(); ``` -### Return Value +### Return value -Returns the value of the [CAutoPtr::m_p](#m_p) data member variable. +Returns the value of the [`CAutoPtr::m_p`](#m_p) data member variable. ### Remarks @@ -236,9 +236,9 @@ Use this operator to call a method in a class pointed to by the `CAutoPtr` objec ### Example -See the example in the [CAutoPtr Overview](../../atl/reference/cautoptr-class.md). +See the example in the [`CAutoPtr` Overview](../../atl/reference/cautoptr-class.md). -## CAutoPtr::operator T* +## `CAutoPtr::operator T*` The cast operator. @@ -246,16 +246,16 @@ The cast operator. operator T* () const throw(); ``` -### Return Value +### Return value Returns a pointer to the object data type defined in the class template. ### Example -See the example in the [CAutoPtr Overview](../../atl/reference/cautoptr-class.md). +See the example in the [`CAutoPtr` overview](../../atl/reference/cautoptr-class.md). ## See also -[CHeapPtr Class](../../atl/reference/cheapptr-class.md)
-[CAutoVectorPtr Class](../../atl/reference/cautovectorptr-class.md)
-[Class Overview](../../atl/atl-class-overview.md) +[`CHeapPtr` class](../../atl/reference/cheapptr-class.md)\ +[`CAutoVectorPtr` class](../../atl/reference/cautovectorptr-class.md)\ +[Class overview](../../atl/atl-class-overview.md) diff --git a/docs/atl/reference/cautovectorptr-class.md b/docs/atl/reference/cautovectorptr-class.md index b448e16ca0..be4c474bcc 100644 --- a/docs/atl/reference/cautovectorptr-class.md +++ b/docs/atl/reference/cautovectorptr-class.md @@ -58,7 +58,7 @@ The pointer type. ## Remarks -This class provides methods for creating and managing a smart pointer, which will help protect against memory leaks by automatically freeing resources when it falls out of scope. `CAutoVectorPtr` is similar to `CAutoPtr`, the only difference being that `CAutoVectorPtr` uses [vector new[]](../../standard-library/new-operators.md#op_new_arr) and [vector delete[]](../../standard-library/new-operators.md#op_delete_arr) to allocate and free memory instead of the C++ **`new`** and **`delete`** operators. See [CAutoVectorPtrElementTraits](../../atl/reference/cautovectorptrelementtraits-class.md) if collection classes of `CAutoVectorPtr` are required. +This class provides methods for creating and managing a smart pointer, which will help protect against memory leaks by automatically freeing resources when it falls out of scope. `CAutoVectorPtr` is similar to `CAutoPtr`, the only difference being that `CAutoVectorPtr` uses [`vector new[]`](../../standard-library/new-operators.md#op_new_arr) and [`vector delete[]`](../../standard-library/new-operators.md#op_delete_arr) to allocate and free memory instead of the C++ **`new`** and **`delete`** operators. See [CAutoVectorPtrElementTraits](../../atl/reference/cautovectorptrelementtraits-class.md) if collection classes of `CAutoVectorPtr` are required. See [CAutoPtr](../../atl/reference/cautoptr-class.md) for an example of using a smart pointer class. diff --git a/docs/atl/reference/caxdialogimpl-class.md b/docs/atl/reference/caxdialogimpl-class.md index 79b8cc070f..76937ed12b 100644 --- a/docs/atl/reference/caxdialogimpl-class.md +++ b/docs/atl/reference/caxdialogimpl-class.md @@ -65,7 +65,7 @@ See [Implementing a Dialog Box](../../atl/implementing-a-dialog-box.md) for more Note that an ActiveX control on a modal dialog box created with `CAxDialogImpl` will not support accelerator keys. To support accelerator keys on a dialog box created with `CAxDialogImpl`, create a modeless dialog box and, using your own message loop, use [CAxDialogImpl::IsDialogMessage](#isdialogmessage) after getting a message from the queue to handle an accelerator key. -For more information on `CAxDialogImpl`, see [ATL Control Containment FAQ](../../atl/atl-control-containment-faq.md). +For more information on `CAxDialogImpl`, see [ATL Control Containment FAQ](../../atl/atl-control-containment-faq.yml). ## Inheritance Hierarchy diff --git a/docs/atl/reference/caxwindow-class.md b/docs/atl/reference/caxwindow-class.md index 56b25499ba..1817a66fc3 100644 --- a/docs/atl/reference/caxwindow-class.md +++ b/docs/atl/reference/caxwindow-class.md @@ -5,6 +5,12 @@ ms.date: "11/04/2016" f1_keywords: ["CAxWindow", "ATLWIN/ATL::CAxWindow", "ATLWIN/ATL::AttachControl", "ATLWIN/ATL::CreateControl", "ATLWIN/ATL::CreateControlEx", "ATLWIN/ATL::GetWndClassName", "ATLWIN/ATL::QueryControl", "ATLWIN/ATL::QueryHost", "ATLWIN/ATL::SetExternalDispatch", "ATLWIN/ATL::SetExternalUIHandler"] helpviewer_keywords: ["CAxWindow class", "ATL, hosting ActiveX controls"] ms.assetid: 85e79261-43e4-4770-bde0-1ff87f222b0f +api_type: +- DllExport +api_location: +- atlhost.dll +api_name: +- CAxWindow::CreateControlEx --- # CAxWindow Class @@ -153,7 +159,7 @@ See [CAxWindow2T::CreateControlLic](../../atl/reference/caxwindow2t-class.md#cre ### Example -See [Hosting ActiveX Controls Using ATL AXHost](../../atl/atl-control-containment-faq.md#hosting-activex-controls-using-atl-axhost) for a sample that uses `CreateControl`. +See [Hosting ActiveX Controls Using ATL AXHost](../../atl/atl-control-containment-faq.yml#hosting-activex-controls-using-atl-axhost) for a sample that uses `CreateControl`. ## CAxWindow::CreateControlEx @@ -225,7 +231,7 @@ See [CAxWindow2T::CreateControlLicEx](../../atl/reference/caxwindow2t-class.md#c ### Example -See [Hosting ActiveX Controls Using ATL AXHost](../../atl/atl-control-containment-faq.md#hosting-activex-controls-using-atl-axhost) for a sample that uses `CreateControlEx`. +See [Hosting ActiveX Controls Using ATL AXHost](../../atl/atl-control-containment-faq.yml#hosting-activex-controls-using-atl-axhost) for a sample that uses `CreateControlEx`. ## CAxWindow::GetWndClassName @@ -354,4 +360,4 @@ The external `IDocHostUIHandlerDispatch` interface is used by controls that quer [CWindow Class](../../atl/reference/cwindow-class.md)
[Composite Control Fundamentals](../../atl/atl-composite-control-fundamentals.md)
[Class Overview](../../atl/atl-class-overview.md)
-[Control Containment FAQ](../../atl/atl-control-containment-faq.md) +[Control Containment FAQ](../../atl/atl-control-containment-faq.yml) diff --git a/docs/atl/reference/caxwindow2t-class.md b/docs/atl/reference/caxwindow2t-class.md index ee55c3db29..866f52ad95 100644 --- a/docs/atl/reference/caxwindow2t-class.md +++ b/docs/atl/reference/caxwindow2t-class.md @@ -60,7 +60,7 @@ Class `CAxWindow2` is implemented as a specialization of the `CAxWindow2T` class > [!NOTE] > `CAxWindowT` members are documented under [CAxWindow](../../atl/reference/caxwindow-class.md). -See [Hosting ActiveX Controls Using ATL AXHost](../../atl/atl-control-containment-faq.md#hosting-activex-controls-using-atl-axhost) for a sample that uses the members of this class. +See [Hosting ActiveX Controls Using ATL AXHost](../../atl/atl-control-containment-faq.yml#hosting-activex-controls-using-atl-axhost) for a sample that uses the members of this class. ## Inheritance Hierarchy @@ -112,7 +112,7 @@ See `CWindow::Create` for a description of the parameters and return value. ### Example -See [Hosting ActiveX Controls Using ATL AXHost](../../atl/atl-control-containment-faq.md#hosting-activex-controls-using-atl-axhost) for a sample that uses `CAxWindow2T::Create`. +See [Hosting ActiveX Controls Using ATL AXHost](../../atl/atl-control-containment-faq.yml#hosting-activex-controls-using-atl-axhost) for a sample that uses `CAxWindow2T::Create`. ## CAxWindow2T::CreateControlLic @@ -143,7 +143,7 @@ See [CAxWindow::CreateControl](../../atl/reference/caxwindow-class.md#createcont ### Example -See [Hosting ActiveX Controls Using ATL AXHost](../../atl/atl-control-containment-faq.md#hosting-activex-controls-using-atl-axhost) for a sample that uses `CAxWindow2T::CreateControlLic`. +See [Hosting ActiveX Controls Using ATL AXHost](../../atl/atl-control-containment-faq.yml#hosting-activex-controls-using-atl-axhost) for a sample that uses `CAxWindow2T::CreateControlLic`. ## CAxWindow2T::CreateControlLicEx @@ -180,7 +180,7 @@ See [CAxWindow::CreateControlEx](../../atl/reference/caxwindow-class.md#createco ### Example -See [Hosting ActiveX Controls Using ATL AXHost](../../atl/atl-control-containment-faq.md#hosting-activex-controls-using-atl-axhost) for a sample that uses `CAxWindow2T::CreateControlLicEx`. +See [Hosting ActiveX Controls Using ATL AXHost](../../atl/atl-control-containment-faq.yml#hosting-activex-controls-using-atl-axhost) for a sample that uses `CAxWindow2T::CreateControlLicEx`. ## CAxWindow2T::GetWndClassName @@ -210,4 +210,4 @@ A handle of an existing window. ## See also [Class Overview](../../atl/atl-class-overview.md)
-[Control Containment FAQ](../../atl/atl-control-containment-faq.md) +[Control Containment FAQ](../../atl/atl-control-containment-faq.yml) diff --git a/docs/atl/reference/ccombstr-class.md b/docs/atl/reference/ccombstr-class.md index 30fb9b98c6..14c7a7e8d8 100644 --- a/docs/atl/reference/ccombstr-class.md +++ b/docs/atl/reference/ccombstr-class.md @@ -6,9 +6,9 @@ f1_keywords: ["CComBSTR", "ATLBASE/ATL::CComBSTR", "ATLBASE/ATL::CComBSTR::CComB helpviewer_keywords: ["BSTRs, wrapper", "CComBSTR class", "CComBSTR"] ms.assetid: 8fea1879-a05e-47a5-a803-8dec60eaa534 --- -# CComBSTR Class +# `CComBSTR` Class -This class is a wrapper for [BSTR](/previous-versions/windows/desktop/automat/bstr)s. +This class is a wrapper for [`BSTR`](/previous-versions/windows/desktop/automat/bstr)s. ## Syntax @@ -22,57 +22,57 @@ class CComBSTR |Name|Description| |----------|-----------------| -|[CComBSTR::CComBSTR](#ccombstr)|The constructor.| -|[CComBSTR::~CComBSTR](#dtor)|The destructor.| +|[`CComBSTR::CComBSTR`](#ccombstr)|The constructor.| +|[`CComBSTR::~CComBSTR`](#dtor)|The destructor.| ### Public Methods |Name|Description| |----------|-----------------| -|[CComBSTR::Append](#append)|Appends a string to `m_str`.| -|[CComBSTR::AppendBSTR](#appendbstr)|Appends a BSTR to `m_str`.| -|[CComBSTR::AppendBytes](#appendbytes)|Appends a specified number of bytes to `m_str`.| -|[CComBSTR::ArrayToBSTR](#arraytobstr)|Creates a BSTR from the first character of each element in the safearray and attaches it to the `CComBSTR` object.| -|[CComBSTR::AssignBSTR](#assignbstr)|Assigns a BSTR to `m_str`.| -|[CComBSTR::Attach](#attach)|Attaches a BSTR to the `CComBSTR` object.| -|[CComBSTR::BSTRToArray](#bstrtoarray)|Creates a zero-based one-dimensional safearray, where each element of the array is a character from the `CComBSTR` object.| -|[CComBSTR::ByteLength](#bytelength)|Returns the length of `m_str` in bytes.| -|[CComBSTR::Copy](#copy)|Returns a copy of `m_str`.| -|[CComBSTR::CopyTo](#copyto)|Returns a copy of `m_str` via an **[out]** parameter| -|[CComBSTR::Detach](#detach)|Detaches `m_str` from the `CComBSTR` object.| -|[CComBSTR::Empty](#empty)|Frees `m_str`.| -|[CComBSTR::Length](#length)|Returns the length of `m_str`.| -|[CComBSTR::LoadString](#loadstring)|Loads a string resource.| -|[CComBSTR::ReadFromStream](#readfromstream)|Loads a BSTR object from a stream.| -|[CComBSTR::ToLower](#tolower)|Converts the string to lowercase.| -|[CComBSTR::ToUpper](#toupper)|Converts the string to uppercase.| -|[CComBSTR::WriteToStream](#writetostream)|Saves `m_str` to a stream.| +|[`CComBSTR::Append`](#append)|Appends a string to `m_str`.| +|[`CComBSTR::AppendBSTR`](#appendbstr)|Appends a `BSTR` to `m_str`.| +|[`CComBSTR::AppendBytes`](#appendbytes)|Appends a specified number of bytes to `m_str`.| +|[`CComBSTR::ArrayToBSTR`](#arraytobstr)|Creates a `BSTR` from the first character of each element in the safearray and attaches it to the `CComBSTR` object.| +|[`CComBSTR::AssignBSTR`](#assignbstr)|Assigns a `BSTR` to `m_str`.| +|[`CComBSTR::Attach`](#attach)|Attaches a `BSTR` to the `CComBSTR` object.| +|[`CComBSTR::BSTRToArray`](#bstrtoarray)|Creates a zero-based one-dimensional safearray, where each element of the array is a character from the `CComBSTR` object.| +|[`CComBSTR::ByteLength`](#bytelength)|Returns the length of `m_str` in bytes.| +|[`CComBSTR::Copy`](#copy)|Returns a copy of `m_str`.| +|[`CComBSTR::CopyTo`](#copyto)|Returns a copy of `m_str` via an **`[out]`** parameter| +|[`CComBSTR::Detach`](#detach)|Detaches `m_str` from the `CComBSTR` object.| +|[`CComBSTR::Empty`](#empty)|Frees `m_str`.| +|[`CComBSTR::Length`](#length)|Returns the length of `m_str`.| +|[`CComBSTR::LoadString`](#loadstring)|Loads a string resource.| +|[`CComBSTR::ReadFromStream`](#readfromstream)|Loads a `BSTR` object from a stream.| +|[`CComBSTR::ToLower`](#tolower)|Converts the string to lowercase.| +|[`CComBSTR::ToUpper`](#toupper)|Converts the string to uppercase.| +|[`CComBSTR::WriteToStream`](#writetostream)|Saves `m_str` to a stream.| ### Public Operators |Name|Description| |----------|-----------------| -|[CComBSTR::operator BSTR](#operator_bstr)|Casts a `CComBSTR` object to a BSTR.| -|[CComBSTR::operator !](#operator_not)|Returns TRUE or FALSE, depending on whether `m_str` is NULL.| -|[CComBSTR::operator !=](#operator_neq)|Compares a `CComBSTR` with a string.| -|[CComBSTR::operator &](#operator_amp)|Returns the address of `m_str`.| -|[CComBSTR::operator +=](#operator_add_eq)|Appends a `CComBSTR` to the object.| -|[CComBSTR::operator <](#operator_lt)|Compares a `CComBSTR` with a string.| -|[CComBSTR::operator =](#operator_eq)|Assigns a value to `m_str`.| -|[CComBSTR::operator ==](#operator_eq_eq)|Compares a `CComBSTR` with a string.| -|[CComBSTR::operator >](#operator_gt)|Compares a `CComBSTR` with a string.| +|[`CComBSTR::operator BSTR`](#operator_bstr)|Casts a `CComBSTR` object to a BSTR.| +|[`CComBSTR::operator !`](#operator_not)|Returns TRUE or FALSE, depending on whether `m_str` is NULL.| +|[`CComBSTR::operator !=`](#operator_neq)|Compares a `CComBSTR` with a string.| +|[`CComBSTR::operator &`](#operator_amp)|Returns the address of `m_str`.| +|[`CComBSTR::operator +=`](#operator_add_eq)|Appends a `CComBSTR` to the object.| +|[`CComBSTR::operator <`](#operator_lt)|Compares a `CComBSTR` with a string.| +|[`CComBSTR::operator =`](#operator_eq)|Assigns a value to `m_str`.| +|[`CComBSTR::operator ==`](#operator_eq_eq)|Compares a `CComBSTR` with a string.| +|[`CComBSTR::operator >`](#operator_gt)|Compares a `CComBSTR` with a string.| ### Public Data Members |Name|Description| |----------|-----------------| -|[CComBSTR::m_str](#m_str)|Contains the BSTR associated with the `CComBSTR` object.| +|[`CComBSTR::m_str`](#m_str)|Contains the `BSTR` associated with the `CComBSTR` object.| ## Remarks -The `CComBSTR` class is a wrapper for BSTRs, which are length-prefixed strings. The length is stored as an integer at the memory location preceding the data in the string. +The `CComBSTR` class is a wrapper for `BSTR`s, which are length-prefixed strings. The length is stored as an integer at the memory location preceding the data in the string. -A [BSTR](/previous-versions/windows/desktop/automat/bstr) is null-terminated after the last counted character but may also contain null characters embedded within the string. The string length is determined by the character count, not the first null character. +A [`BSTR`](/previous-versions/windows/desktop/automat/bstr) is null-terminated after the last counted character but may also contain null characters embedded within the string. The string length is determined by the character count, not the first null character. > [!NOTE] > The `CComBSTR` class provides a number of members (constructors, assignment operators, and comparison operators) that take either ANSI or Unicode strings as arguments. The ANSI versions of these functions are less efficient than their Unicode counterparts because temporary Unicode strings are often created internally. For efficiency, use the Unicode versions where possible. @@ -80,15 +80,15 @@ A [BSTR](/previous-versions/windows/desktop/automat/bstr) is null-terminated aft > [!NOTE] > Because of the improved lookup behavior implemented in Visual Studio .NET, code such as `bstr = L"String2" + bstr;`, which may have compiled in previous releases, should instead be implemented as `bstr = CStringW(L"String2") + bstr`. -For a list of cautions when using `CComBSTR`, see [Programming with CComBSTR](../../atl/programming-with-ccombstr-atl.md). +For a list of cautions when using `CComBSTR`, see [Programming with `CComBSTR`](../../atl/programming-with-ccombstr-atl.md). ## Requirements -**Header:** atlbase.h +**Header:** `atlbase.h` -## CComBSTR::Append +## `CComBSTR::Append` -Appends either *lpsz* or the BSTR member of *bstrSrc* to [m_str](#m_str). +Appends either *`lpsz`* or the BSTR member of *`bstrSrc`* to [`m_str`](#m_str). ``` HRESULT Append(const CComBSTR& bstrSrc) throw(); @@ -101,21 +101,21 @@ HRESULT Append(LPCOLESTR lpsz, int nLen) throw(); ### Parameters -*bstrSrc*
+*`bstrSrc`*
[in] A `CComBSTR` object to append. -*ch*
+*`ch`*
[in] A character to append. -*lpsz*
-[in] A zero-terminated character string to append. You can pass a Unicode string via the LPCOLESTR overload or an ANSI string via the LPCSTR version. +*`lpsz`*
+[in] A zero-terminated character string to append. You can pass a Unicode string via the `LPCOLESTR` overload or an ANSI string via the `LPCSTR` version. -*nLen*
-[in] The number of characters from *lpsz* to append. +*`nLen`*
+[in] The number of characters from *`lpsz`* to append. ### Return Value -S_OK on success, or any standard HRESULT error value. +`S_OK` on success, or any standard `HRESULT` error value. ### Remarks @@ -125,9 +125,9 @@ An ANSI string will be converted to Unicode before being appended. [!code-cpp[NVC_ATL_Utilities#32](../../atl/codesnippet/cpp/ccombstr-class_1.cpp)] -## CComBSTR::AppendBSTR +## `CComBSTR::AppendBSTR` -Appends the specified BSTR to [m_str](#m_str). +Appends the specified `BSTR` to [`m_str`](#m_str). ``` HRESULT AppendBSTR(BSTR p) throw(); @@ -135,12 +135,12 @@ HRESULT AppendBSTR(BSTR p) throw(); ### Parameters -*p*
-[in] A BSTR to append. +*`p`*
+[in] A `BSTR` to append. ### Return Value -S_OK on success, or any standard HRESULT error value. +`S_OK` on success, or any standard `HRESULT` error value. ### Remarks @@ -150,9 +150,9 @@ Do not pass an ordinary wide-character string to this method. The compiler canno [!code-cpp[NVC_ATL_Utilities#33](../../atl/codesnippet/cpp/ccombstr-class_2.cpp)] -## CComBSTR::AppendBytes +## `CComBSTR::AppendBytes` -Appends the specified number of bytes to [m_str](#m_str) without conversion. +Appends the specified number of bytes to [`m_str`](#m_str) without conversion. ``` HRESULT AppendBytes(const char* lpsz, int nLen) throw(); @@ -160,23 +160,23 @@ HRESULT AppendBytes(const char* lpsz, int nLen) throw(); ### Parameters -*lpsz*
+*`lpsz`*
[in] A pointer to an array of bytes to append. -*p*
+*`p`*
[in] The number of bytes to append. ### Return Value -S_OK on success, or any standard HRESULT error value. +`S_OK` on success, or any standard `HRESULT` error value. ### Example [!code-cpp[NVC_ATL_Utilities#34](../../atl/codesnippet/cpp/ccombstr-class_3.cpp)] -## CComBSTR::ArrayToBSTR +## `CComBSTR::ArrayToBSTR` -Frees any existing string held in the `CComBSTR` object, then creates a BSTR from the first character of each element in the safearray and attaches it to the `CComBSTR` object. +Frees any existing string held in the `CComBSTR` object, then creates a `BSTR` from the first character of each element in the safearray and attaches it to the `CComBSTR` object. ``` HRESULT ArrayToBSTR(const SAFEARRAY* pSrc) throw(); @@ -184,16 +184,16 @@ HRESULT ArrayToBSTR(const SAFEARRAY* pSrc) throw(); ### Parameters -*pSrc*
+*`pSrc`*
[in] The safearray containing the elements used to create the string. ### Return Value -S_OK on success, or any standard HRESULT error value. +`S_OK` on success, or any standard `HRESULT` error value. -## CComBSTR::AssignBSTR +## `CComBSTR::AssignBSTR` -Assigns a BSTR to [m_str](#m_str). +Assigns a `BSTR` to [`m_str`](#m_str). ``` HRESULT AssignBSTR(const BSTR bstrSrc) throw(); @@ -201,16 +201,16 @@ HRESULT AssignBSTR(const BSTR bstrSrc) throw(); ### Parameters -*bstrSrc*
+*`bstrSrc`*
[in] A BSTR to assign to the current `CComBSTR` object. ### Return Value -S_OK on success, or any standard HRESULT error value. +`S_OK` on success, or any standard `HRESULT` error value. -## CComBSTR::Attach +## `CComBSTR::Attach` -Attaches a BSTR to the `CComBSTR` object by setting the [m_str](#m_str) member to *src*. +Attaches a `BSTR` to the `CComBSTR` object by setting the [`m_str`](#m_str) member to *`src`*. ```cpp void Attach(BSTR src) throw(); @@ -218,8 +218,8 @@ void Attach(BSTR src) throw(); ### Parameters -*src*
-[in] The BSTR to attach to the object. +*`src`*
+[in] The `BSTR` to attach to the object. ### Remarks @@ -232,7 +232,7 @@ Do not pass an ordinary wide-character string to this method. The compiler canno [!code-cpp[NVC_ATL_Utilities#35](../../atl/codesnippet/cpp/ccombstr-class_4.cpp)] -## CComBSTR::BSTRToArray +## `CComBSTR::BSTRToArray` Creates a zero-based one-dimensional safearray, where each element of the array is a character from the `CComBSTR` object. @@ -242,14 +242,14 @@ HRESULT BSTRToArray(LPSAFEARRAY* ppArray) throw(); ### Parameters -*ppArray*
+*`ppArray`*
[out] The pointer to the safearray used to hold the results of the function. ### Return Value -S_OK on success, or any standard HRESULT error value. +`S_OK` on success, or any standard `HRESULT` error value. -## CComBSTR::ByteLength +## `CComBSTR::ByteLength` Returns the number of bytes in `m_str`, excluding the terminating null character. @@ -259,19 +259,19 @@ unsigned int ByteLength() const throw(); ### Return Value -The length of the [m_str](#m_str) member in bytes. +The length of the [`m_str`](#m_str) member in bytes. ### Remarks -Returns 0 if `m_str` is NULL. +Returns 0 if `m_str` is `NULL`. ### Example [!code-cpp[NVC_ATL_Utilities#36](../../atl/codesnippet/cpp/ccombstr-class_5.cpp)] -## CComBSTR::CComBSTR +## `CComBSTR::CComBSTR` -The constructor. The default constructor sets the [m_str](#m_str) member to NULL. +The constructor. The default constructor sets the [`m_str`](#m_str) member to `NULL`. ``` CComBSTR() throw(); @@ -287,26 +287,26 @@ CComBSTR(CComBSTR&& src) throw(); // (Visual Studio 2017) ### Parameters -*nSize*
-[in] The number of characters to copy from *sz* or the initial size in characters for the `CComBSTR`. +*`nSize`*
+[in] The number of characters to copy from *`sz`* or the initial size in characters for the `CComBSTR`. -*sz*
-[in] A string to copy. The Unicode version specifies an LPCOLESTR; the ANSI version specifies an LPCSTR. +*`sz`*
+[in] A string to copy. The Unicode version specifies an `LPCOLESTR`; the ANSI version specifies an LPCSTR. -*pSrc*
-[in] A string to copy. The Unicode version specifies an LPCOLESTR; the ANSI version specifies an LPCSTR. +*`pSrc`*
+[in] A string to copy. The Unicode version specifies an `LPCOLESTR`; the ANSI version specifies an LPCSTR. -*src*
+*`src`*
[in] A `CComBSTR` object. -*guid*
+*`guid`*
[in] A reference to a `GUID` structure. ### Remarks -The copy constructor sets `m_str` to a copy of the BSTR member of *src*. The `REFGUID` constructor converts the GUID to a string using `StringFromGUID2` and stores the result. +The copy constructor sets `m_str` to a copy of the BSTR member of *`src`*. The `REFGUID` constructor converts the GUID to a string using `StringFromGUID2` and stores the result. -The other constructors set `m_str` to a copy of the specified string. If you pass a value for *nSize*, then only *nSize* characters will be copied, followed by a terminating null character. +The other constructors set `m_str` to a copy of the specified string. If you pass a value for *`nSize`*, then only *`nSize`* characters will be copied, followed by a terminating null character. `CComBSTR` supports move semantics. You can use the move constructor (the constructor that takes an rvalue reference (`&&`) to create a new object that uses the same underlying data as the old object you pass in as an argument, without the overhead of copying the object. @@ -316,7 +316,7 @@ The destructor frees the string pointed to by `m_str`. [!code-cpp[NVC_ATL_Utilities#37](../../atl/codesnippet/cpp/ccombstr-class_6.cpp)] -## CComBSTR::~CComBSTR +## `CComBSTR::~CComBSTR` The destructor. @@ -328,7 +328,7 @@ The destructor. The destructor frees the string pointed to by `m_str`. -## CComBSTR::Copy +## `CComBSTR::Copy` Allocates and returns a copy of `m_str`. @@ -338,15 +338,15 @@ BSTR Copy() const throw(); ### Return Value -A copy of the [m_str](#m_str) member. If `m_str` is NULL, returns NULL. +A copy of the [`m_str`](#m_str) member. If `m_str` is `NULL`, returns `NULL`. ### Example [!code-cpp[NVC_ATL_Utilities#38](../../atl/codesnippet/cpp/ccombstr-class_7.cpp)] -## CComBSTR::CopyTo +## `CComBSTR::CopyTo` -Allocates and returns a copy of [m_str](#m_str) via the parameter. +Allocates and returns a copy of [`m_str`](#m_str) via the parameter. ``` HRESULT CopyTo(BSTR* pbstr) throw(); @@ -356,27 +356,27 @@ HRESULT CopyTo(VARIANT* pvarDest) throw(); ### Parameters -*pbstr*
-[out] The address of a BSTR in which to return the string allocated by this method. +*`pbstr`*
+[out] The address of a `BSTR` in which to return the string allocated by this method. -*pvarDest*
-[out] The address of a VARIANT in which to return the string allocated by this method. +*`pvarDest`*
+[out] The address of a `VARIANT` in which to return the string allocated by this method. ### Return Value -A standard HRESULT value indicating the success or failure of the copy. +A standard `HRESULT` value indicating the success or failure of the copy. ### Remarks -After calling this method, the VARIANT pointed to by *pvarDest* will be of type VT_BSTR. +After calling this method, the `VARIANT` pointed to by *`pvarDest`* will be of type `VT_BSTR`. ### Example [!code-cpp[NVC_ATL_Utilities#39](../../atl/codesnippet/cpp/ccombstr-class_8.cpp)] -## CComBSTR::Detach +## `CComBSTR::Detach` -Detaches [m_str](#m_str) from the `CComBSTR` object and sets `m_str` to NULL. +Detaches [`m_str`](#m_str) from the `CComBSTR` object and sets `m_str` to `NULL`. ``` BSTR Detach() throw(); @@ -384,15 +384,15 @@ BSTR Detach() throw(); ### Return Value -The BSTR associated with the `CComBSTR` object. +The `BSTR` associated with the `CComBSTR` object. ### Example [!code-cpp[NVC_ATL_Utilities#40](../../atl/codesnippet/cpp/ccombstr-class_9.cpp)] -## CComBSTR::Empty +## `CComBSTR::Empty` -Frees the [m_str](#m_str) member. +Frees the [`m_str`](#m_str) member. ```cpp void Empty() throw(); @@ -402,7 +402,7 @@ void Empty() throw(); [!code-cpp[NVC_ATL_Utilities#41](../../atl/codesnippet/cpp/ccombstr-class_10.cpp)] -## CComBSTR::Length +## `CComBSTR::Length` Returns the number of characters in `m_str`, excluding the terminating null character. @@ -412,15 +412,15 @@ unsigned int Length() const throw(); ### Return Value -The length of the [m_str](#m_str) member. +The length of the [`m_str`](#m_str) member. ### Example [!code-cpp[NVC_ATL_Utilities#42](../../atl/codesnippet/cpp/ccombstr-class_11.cpp)] -## CComBSTR::LoadString +## `CComBSTR::LoadString` -Loads a string resource specified by *nID* and stores it in this object. +Loads a string resource specified by *`nID`* and stores it in this object. ``` bool LoadString(HINSTANCE hInst, UINT nID) throw(); @@ -429,23 +429,23 @@ bool LoadString(UINT nID) throw(); ### Parameters -See [LoadString](/windows/win32/api/winuser/nf-winuser-loadstringw) in the Windows SDK. +See [`LoadString`](/windows/win32/api/winuser/nf-winuser-loadstringw) in the Windows SDK. ### Return Value -Returns TRUE if the string is successfully loaded; otherwise, returns FALSE. +Returns `TRUE` if the string is successfully loaded; otherwise, returns `FALSE`. ### Remarks -The first function loads the resource from the module identified by you via the *hInst* parameter. The second function loads the resource from the resource module associated with the [CComModule](../../atl/reference/ccommodule-class.md)-derived object used in this project. +The first function loads the resource from the module identified by you via the *`hInst`* parameter. The second function loads the resource from the resource module associated with the [`CComModule`](../../atl/reference/ccommodule-class.md)-derived object used in this project. ### Example [!code-cpp[NVC_ATL_Utilities#43](../../atl/codesnippet/cpp/ccombstr-class_12.cpp)] -## CComBSTR::m_str +## `CComBSTR::m_str` -Contains the BSTR associated with the `CComBSTR` object. +Contains the `BSTR` associated with the `CComBSTR` object. ``` BSTR m_str; @@ -455,9 +455,9 @@ BSTR m_str; [!code-cpp[NVC_ATL_Utilities#49](../../atl/codesnippet/cpp/ccombstr-class_13.cpp)] -## CComBSTR::operator BSTR +## `CComBSTR::operator BSTR` -Casts a `CComBSTR` object to a BSTR. +Casts a `CComBSTR` object to a `BSTR`. ``` operator BSTR() const throw(); @@ -465,15 +465,15 @@ operator BSTR() const throw(); ### Remarks -Allows you to pass `CComBSTR` objects to functions that have **[in] BSTR** parameters. +Allows you to pass `CComBSTR` objects to functions that have **[in] `BSTR`** parameters. ### Example -See the example for [CComBSTR::m_str](#m_str). +See the example for [`CComBSTR::m_str`](#m_str). -## CComBSTR::operator ! +## `CComBSTR::operator !` -Checks whether BSTR string is NULL. +Checks whether `BSTR` string is `NULL`. ``` bool operator!() const throw(); @@ -481,19 +481,19 @@ bool operator!() const throw(); ### Return Value -Returns TRUE if the [m_str](#m_str) member is NULL; otherwise, FALSE. +Returns `TRUE` if the [`m_str`](#m_str) member is `NULL`; otherwise, `FALSE`. ### Remarks -This operator only checks for a NULL value, not for an empty string. +This operator only checks for a `NULL` value, not for an empty string. ### Example [!code-cpp[NVC_ATL_Utilities#35](../../atl/codesnippet/cpp/ccombstr-class_4.cpp)] -## CComBSTR::operator != +## `CComBSTR::operator !=` -Returns the logical opposite of [operator ==](#operator_eq_eq). +Returns the logical opposite of [`operator ==`](#operator_eq_eq). ``` bool operator!= (const CComBSTR& bstrSrc) const throw(); @@ -504,26 +504,26 @@ bool operator!= (int nNull) const throw(); ### Parameters -*bstrSrc*
+*`bstrSrc`*
[in] A `CComBSTR` object. -*pszSrc*
+*`pszSrc`*
[in] A zero-terminated string. -*nNull*
+*`nNull`*
[in] Must be NULL. ### Return Value -Returns TRUE if the item being compared is not equal to the `CComBSTR` object; otherwise, returns FALSE. +Returns `TRUE` if the item being compared is not equal to the `CComBSTR` object; otherwise, returns `FALSE`. ### Remarks -`CComBSTR`s are compared textually in the context of the user's default locale. The final comparison operator just compares the contained string against NULL. +`CComBSTR`s are compared textually in the context of the user's default locale. The final comparison operator just compares the contained string against `NULL`. -## CComBSTR::operator & +## `CComBSTR::operator &` -Returns the address of the BSTR stored in the [m_str](#m_str) member. +Returns the address of the `BSTR` stored in the [`m_str`](#m_str) member. ``` BSTR* operator&() throw(); @@ -531,9 +531,9 @@ BSTR* operator&() throw(); ### Remarks -`CComBstr operator &` has a special assertion associated with it to help identify memory leaks. The program will assert when the `m_str` member is initialized. This assertion was created to identify situations where a programmer uses the `& operator` to assign a new value to `m_str` member without freeing the first allocation of `m_str`. If `m_str` equals NULL, the program assumes that m_str wasn't allocated yet. In this case, the program will not assert. +`CComBstr operator &` has a special assertion associated with it to help identify memory leaks. The program will assert when the `m_str` member is initialized. This assertion was created to identify situations where a programmer uses the `& operator` to assign a new value to `m_str` member without freeing the first allocation of `m_str`. If `m_str` equals `NULL`, the program assumes that m_str wasn't allocated yet. In this case, the program will not assert. -This assertion is not enabled by default. Define ATL_CCOMBSTR_ADDRESS_OF_ASSERT to enable this assertion. +This assertion is not enabled by default. Define `ATL_CCOMBSTR_ADDRESS_OF_ASSERT` to enable this assertion. ### Example @@ -541,7 +541,7 @@ This assertion is not enabled by default. Define ATL_CCOMBSTR_ADDRESS_OF_ASSERT [!code-cpp[NVC_ATL_Utilities#47](../../atl/codesnippet/cpp/ccombstr-class_15.cpp)] -## CComBSTR::operator += +## `CComBSTR::operator +=` Appends a string to the `CComBSTR` object. @@ -552,21 +552,21 @@ CComBSTR& operator+= (const LPCOLESTR pszSrc); ### Parameters -*bstrSrc*
+*`bstrSrc`*
[in] A `CComBSTR` object to append. -*pszSrc*
+*`pszSrc`*
[in] A zero-terminated string to append. ### Remarks -`CComBSTR`s are compared textually in the context of the user's default locale. The LPCOLESTR comparison is done using `memcmp` on the raw data in each string. The LPCSTR comparison is carried out in the same way once a temporary Unicode copy of *pszSrc* has been created. The final comparison operator just compares the contained string against NULL. +`CComBSTR`s are compared textually in the context of the user's default locale. The `LPCOLESTR` comparison is done using `memcmp` on the raw data in each string. The `LPCSTR` comparison is carried out in the same way once a temporary Unicode copy of *`pszSrc`* has been created. The final comparison operator just compares the contained string against `NULL`. ### Example [!code-cpp[NVC_ATL_Utilities#48](../../atl/codesnippet/cpp/ccombstr-class_16.cpp)] -## CComBSTR::operator < +## `CComBSTR::operator <` Compares a `CComBSTR` with a string. @@ -578,15 +578,15 @@ bool operator<(LPCSTR pszSrc) const throw(); ### Return Value -Returns TRUE if the item being compared is less than the `CComBSTR` object; otherwise, returns FALSE. +Returns `TRUE` if the item being compared is less than the `CComBSTR` object; otherwise, returns `FALSE`. ### Remarks The comparison is performed using the user's default locale. -## CComBSTR::operator = +## `CComBSTR::operator =` -Sets the [m_str](#m_str) member to a copy of *pSrc* or to a copy of the BSTR member of *src*. The move assignment operator moves `src` without copying it. +Sets the [`m_str`](#m_str) member to a copy of *`pSrc`* or to a copy of the `BSTR` member of *`src`*. The move assignment operator moves `src` without copying it. ``` CComBSTR& operator= (const CComBSTR& src); @@ -597,13 +597,13 @@ CComBSTR& operator= (CComBSTR&& src) throw(); // (Visual Studio 2017) ### Remarks -The *pSrc* parameter specifies either an LPCOLESTR for Unicode versions or LPCSTR for ANSI versions. +The *`pSrc`* parameter specifies either an `LPCOLESTR` for Unicode versions or `LPCSTR` for ANSI versions. ### Example -See the example for [CComBSTR::Copy](#copy). +See the example for [`CComBSTR::Copy`](#copy). -## CComBSTR::operator == +## `CComBSTR::operator ==` Compares a `CComBSTR` with a string. `CComBSTR`s are compared textually in the context of the user's default locale. @@ -616,24 +616,24 @@ bool operator== (int nNull) const throw(); ### Parameters -*bstrSrc*
+*`bstrSrc`*
[in] A `CComBSTR` object. -*pszSrc*
+*`pszSrc`*
[in] A zero-terminated string. -*nNull*
-[in] Must be NULL. +*`nNull`*
+[in] Must be `NULL`. ### Return Value -Returns TRUE if the item being compared is equal to the `CComBSTR` object; otherwise, returns FALSE. +Returns `TRUE` if the item being compared is equal to the `CComBSTR` object; otherwise, returns `FALSE`. ### Remarks -The final comparison operator just compares the contained string against NULL. +The final comparison operator just compares the contained string against `NULL`. -## CComBSTR::operator > +## `CComBSTR::operator >` Compares a `CComBSTR` with a string. @@ -643,15 +643,15 @@ bool operator>(const CComBSTR& bstrSrc) const throw(); ### Return Value -Returns TRUE if the item being compared is greater than the `CComBSTR` object; otherwise, returns FALSE. +Returns `TRUE` if the item being compared is greater than the `CComBSTR` object; otherwise, returns `FALSE`. ### Remarks The comparison is performed using the user's default locale. -## CComBSTR::ReadFromStream +## `CComBSTR::ReadFromStream` -Sets the [m_str](#m_str) member to the BSTR contained in the specified stream. +Sets the [`m_str`](#m_str) member to the `BSTR` contained in the specified stream. ``` HRESULT ReadFromStream(IStream* pStream) throw(); @@ -659,22 +659,22 @@ HRESULT ReadFromStream(IStream* pStream) throw(); ### Parameters -*pStream*
-[in] A pointer to the [IStream](/windows/win32/api/objidl/nn-objidl-istream) interface on the stream containing the data. +*`pStream`*
+[in] A pointer to the [`IStream`](/windows/win32/api/objidl/nn-objidl-istream) interface on the stream containing the data. ### Return Value -A standard HRESULT value. +A standard `HRESULT` value. ### Remarks -`ReadToStream` requires the contents of the stream at the current position to be compatible with the data format written out by a call to [WriteToStream](#writetostream). +`ReadToStream` requires the contents of the stream at the current position to be compatible with the data format written out by a call to [`WriteToStream`](#writetostream). ### Example [!code-cpp[NVC_ATL_Utilities#44](../../atl/codesnippet/cpp/ccombstr-class_17.cpp)] -## CComBSTR::ToLower +## `CComBSTR::ToLower` Converts the contained string to lowercase. @@ -684,13 +684,13 @@ HRESULT ToLower() throw(); ### Return Value -A standard HRESULT value. +A standard `HRESULT` value. ### Remarks See `CharLowerBuff` for more information on how the conversion is performed. -## CComBSTR::ToUpper +## `CComBSTR::ToUpper` Converts the contained string to uppercase. @@ -700,15 +700,15 @@ HRESULT ToUpper() throw(); ### Return Value -A standard HRESULT value. +A standard `HRESULT` value. ### Remarks See `CharUpperBuff` for more information on how the conversion is performed. -## CComBSTR::WriteToStream +## `CComBSTR::WriteToStream` -Saves the [m_str](#m_str) member to a stream. +Saves the [`m_str`](#m_str) member to a stream. ``` HRESULT WriteToStream(IStream* pStream) throw(); @@ -716,16 +716,16 @@ HRESULT WriteToStream(IStream* pStream) throw(); ### Parameters -*pStream*
-[in] A pointer to the [IStream](/windows/win32/api/objidl/nn-objidl-istream) interface on a stream. +*`pStream`*
+[in] A pointer to the [`IStream`](/windows/win32/api/objidl/nn-objidl-istream) interface on a stream. ### Return Value -A standard HRESULT value. +A standard `HRESULT` value. ### Remarks -You can recreate a BSTR from the contents of the stream using the [ReadFromStream](#readfromstream) function. +You can recreate a `BSTR` from the contents of the stream using the [`ReadFromStream`](#readfromstream) function. ### Example diff --git a/docs/atl/reference/ccomcoclass-class.md b/docs/atl/reference/ccomcoclass-class.md index 1cea7aa58c..2101a31f89 100644 --- a/docs/atl/reference/ccomcoclass-class.md +++ b/docs/atl/reference/ccomcoclass-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CComCoClass Class" title: "CComCoClass Class" +description: "Learn more about: CComCoClass Class" ms.date: "11/04/2016" f1_keywords: ["CComCoClass", "ATLCOM/ATL::CComCoClass", "ATLCOM/ATL::CComCoClass::CreateInstance", "ATLCOM/ATL::CComCoClass::Error", "ATLCOM/ATL::CComCoClass::GetObjectCLSID", "ATLCOM/ATL::CComCoClass::GetObjectDescription"] helpviewer_keywords: ["CComCoClass class", "aggregation [C++], aggregation models"] -ms.assetid: 67cfefa4-8df9-47fa-ad58-2d1a1ae25762 --- # CComCoClass Class @@ -12,29 +11,29 @@ This class provides methods for creating instances of a class, and obtaining its ## Syntax -``` +```cpp template class CComCoClass ``` #### Parameters -*T*
+*T*\ Your class, derived from `CComCoClass`. -*pclsid*
+*pclsid*\ A pointer to the CLSID of the object. ## Members ### Public Methods -|Name|Description| -|----------|-----------------| -|[CComCoClass::CreateInstance](#createinstance)|(Static) Creates an instance of the class and queries for an interface.| -|[CComCoClass::Error](#error)|(Static) Returns rich error information to the client.| -|[CComCoClass::GetObjectCLSID](#getobjectclsid)|(Static) Returns the object's class identifier.| -|[CComCoClass::GetObjectDescription](#getobjectdescription)|(Static) Override to return the object's description.| +| Name | Description | +| ---------------------------------------------------------- | ----------------------------------------------------------------------- | +| [CComCoClass::CreateInstance](#createinstance) | (Static) Creates an instance of the class and queries for an interface. | +| [CComCoClass::Error](#error) | (Static) Returns rich error information to the client. | +| [CComCoClass::GetObjectCLSID](#getobjectclsid) | (Static) Returns the object's class identifier. | +| [CComCoClass::GetObjectDescription](#getobjectdescription) | (Static) Override to return the object's description. | ## Remarks @@ -58,23 +57,23 @@ You can override either of these defaults by specifying another macro in your cl Use these `CreateInstance` functions to create an instance of a COM object and retrieve an interface pointer without using the COM API. -``` -template -static HRESULT CreateInstance( Q** pp); +```cpp +template +static HRESULT CreateInstance(Q** pp); -template +template static HRESULT CreateInstance(IUnknown* punkOuter, Q** pp); ``` ### Parameters -*Q*
+*Q*\ The COM interface that should be returned via *pp*. -*punkOuter*
+*punkOuter*\ [in] The outer unknown or controlling unknown of the aggregate. -*pp*
+*pp*\ [out] The address of a pointer variable that receives the requested interface pointer if creation succeeds. ### Return Value @@ -101,7 +100,7 @@ In the following example, `CDocument` is a wizard-generated ATL class derived fr This static function sets up the `IErrorInfo` interface to provide error information to the client. -``` +```cpp static HRESULT WINAPI Error( LPCOLESTR lpszDesc, const IID& iid = GUID_NULL, @@ -130,7 +129,7 @@ static HRESULT WINAPI Error( UINT nID, const IID& iid = GUID_NULL, HRESULT hRes = 0, - HINSTANCE hInst = _AtlBaseModule.GetResourceInstance ()); + HINSTANCE hInst = _AtlBaseModule.GetResourceInstance()); static HRESULT Error( UINT nID, @@ -143,25 +142,25 @@ static HRESULT Error( ### Parameters -*lpszDesc*
+*lpszDesc*\ [in] The string describing the error. The Unicode version of `Error` specifies that *lpszDesc* is of type LPCOLESTR; the ANSI version specifies a type of LPCSTR. -*iid*
+*iid*\ [in] The IID of the interface defining the error or GUID_NULL (the default value) if the error is defined by the operating system. -*hRes*
+*hRes*\ [in] The HRESULT you want returned to the caller. The default value is 0. For more details about *hRes*, see Remarks. -*nID*
+*nID*\ [in] The resource identifier where the error description string is stored. This value should lie between 0x0200 and 0xFFFF, inclusively. In debug builds, an **ASSERT** will result if *nID* does not index a valid string. In release builds, the error description string will be set to "Unknown Error." -*dwHelpID*
+*dwHelpID*\ [in] The help context identifier for the error. -*lpszHelpFile*
+*lpszHelpFile*\ [in] The path and name of the help file describing the error. -*hInst*
+*hInst*\ [in] The handle to the resource. By default, this parameter is `_AtlModule::GetResourceInstance`, where `_AtlModule` is the global instance of [CAtlModule](../../atl/reference/catlmodule-class.md). ### Return Value @@ -170,7 +169,7 @@ A standard HRESULT value. For details, see Remarks. ### Remarks -To call `Error`, your object must implement the `ISupportErrorInfo Interface` interface. +To call `Error`, your object must implement the `ISupportErrorInfo` interface. If the *hRes* parameter is nonzero, then `Error` returns the value of *hRes*. If *hRes* is zero, then the first four versions of `Error` return DISP_E_EXCEPTION. The last two versions return the result of the macro **MAKE_HRESULT( 1, FACILITY_ITF,** *nID* **)**. @@ -178,7 +177,7 @@ If the *hRes* parameter is nonzero, then `Error` returns the value of *hRes*. If Provides a consistent way of retrieving the object's CLSID. -``` +```cpp static const CLSID& WINAPI GetObjectCLSID(); ``` @@ -190,7 +189,7 @@ The object's class identifier. This static function retrieves the text description for your class object. -``` +```cpp static LPCTSTR WINAPI GetObjectDescription(); ``` diff --git a/docs/atl/reference/ccomcontrolbase-class.md b/docs/atl/reference/ccomcontrolbase-class.md index f6b457426f..f65f6c90ee 100644 --- a/docs/atl/reference/ccomcontrolbase-class.md +++ b/docs/atl/reference/ccomcontrolbase-class.md @@ -252,7 +252,7 @@ One of the standard HRESULT values. ### Example [!code-cpp[NVC_ATL_COM#19](../../atl/codesnippet/cpp/ccomcontrolbase-class_2.cpp)] - +  [!code-cpp[NVC_ATL_COM#20](../../atl/codesnippet/cpp/ccomcontrolbase-class_3.h)] ## CComControlBase::FireViewChange diff --git a/docs/atl/reference/ccomcurrency-class.md b/docs/atl/reference/ccomcurrency-class.md index 55f0b3fc6e..cee7bfd016 100644 --- a/docs/atl/reference/ccomcurrency-class.md +++ b/docs/atl/reference/ccomcurrency-class.md @@ -1,93 +1,92 @@ --- -description: "Learn more about: CComCurrency Class" title: "CComCurrency Class" -ms.date: "11/04/2016" +description: "Learn more about: CComCurrency Class" +ms.date: 11/04/2016 f1_keywords: ["CComCurrency", "ATLCUR/ATL::CComCurrency", "ATLCUR/ATL::CComCurrency::CComCurrency", "ATLCUR/ATL::CComCurrency::GetCurrencyPtr", "ATLCUR/ATL::CComCurrency::GetFraction", "ATLCUR/ATL::CComCurrency::GetInteger", "ATLCUR/ATL::CComCurrency::Round", "ATLCUR/ATL::CComCurrency::SetFraction", "ATLCUR/ATL::CComCurrency::SetInteger", "ATLCUR/ATL::CComCurrency::m_currency"] helpviewer_keywords: ["CComCurrency class"] -ms.assetid: a1c3d10a-bba6-40cc-8bcf-aed9023c8a9e --- -# CComCurrency Class +# `CComCurrency` Class -`CComCurrency` has methods and operators for creating and managing a CURRENCY object. +`CComCurrency` has methods and operators for creating and managing a `CURRENCY` object. ## Syntax -``` -class CComCurrency +```cpp +class CComCurrency; ``` ## Members -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[CComCurrency::CComCurrency](#ccomcurrency)|The constructor for a `CComCurrency` object.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|[CComCurrency::GetCurrencyPtr](#getcurrencyptr)|Returns the address of an `m_currency` data member.| -|[CComCurrency::GetFraction](#getfraction)|Call this method to return the fractional component of a `CComCurrency` object.| -|[CComCurrency::GetInteger](#getinteger)|Call this method to return the integer component of a `CComCurrency` object.| -|[CComCurrency::Round](#round)|Call this method to round a `CComCurrency` object to the nearest integer value.| -|[CComCurrency::SetFraction](#setfraction)|Call this method to set the fractional component of a `CComCurrency` object.| -|[CComCurrency::SetInteger](#setinteger)|Call this method to set the integer component of a `CComCurrency` object.| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|[CComCurrency::operator -](#operator_-)|This operator is used to perform subtraction on a `CComCurrency` object.| -|[CComCurrency::operator !=](#operator_neq)|Compares two `CComCurrency` objects for inequality.| -|[CComCurrency::operator *](#operator_star)|This operator is used to perform multiplication on a `CComCurrency` object.| -|[CComCurrency::operator *=](#operator_star_eq)|This operator is used to perform multiplication on a `CComCurrency` object and assign it the result.| -|[CComCurrency::operator /](#operator_div)|This operator is used to perform division on a `CComCurrency` object.| -|[CComCurrency::operator /=](#operator_div_eq)|This operator is used to perform division on a `CComCurrency` object and assign it the result.| -|[CComCurrency::operator +](#operator_add)|This operator is used to perform addition on a `CComCurrency` object.| -|[CComCurrency::operator +=](#operator_add_eq)|This operator is used to perform addition on a `CComCurrency` object and assign the result to the current object.| -|[CComCurrency::operator <](#operator_lt)|This operator compares two `CComCurrency` objects to determine the lesser.| -|[CComCurrency::operator <=](#operator_lt_eq)|This operator compares two `CComCurrency` objects to determine equality or the lesser.| -|[CComCurrency::operator =](#operator_eq)|This operator assigns the `CComCurrency` object to a new value.| -|[CComCurrency::operator -=](#operator_-_eq)|This operator is used to perform subtraction on a `CComCurrency` object and assign it the result.| -|[CComCurrency::operator ==](#operator_eq_eq)|This operator compares two `CComCurrency` objects for equality.| -|[CComCurrency::operator >](#operator_gt)|This operator compares two `CComCurrency` objects to determine the larger.| -|[CComCurrency::operator >=](#operator_gt_eq)|This operator compares two `CComCurrency` objects to determine equality or the larger.| -|[CComCurrency::operator CURRENCY](#operator_currency)|Casts a CURRENCY object.| - -### Public Data Members - -|Name|Description| -|----------|-----------------| -|[CComCurrency::m_currency](#m_currency)|The CURRENCY variable created by your class instance.| +### Public constructors + +| Name | Description | +|--|--| +| [`CComCurrency::CComCurrency`](#ccomcurrency) | The constructor for a `CComCurrency` object. | + +### Public methods + +| Name | Description | +|--|--| +| [`CComCurrency::GetCurrencyPtr`](#getcurrencyptr) | Returns the address of an `m_currency` data member. | +| [`CComCurrency::GetFraction`](#getfraction) | Call this method to return the fractional component of a `CComCurrency` object. | +| [`CComCurrency::GetInteger`](#getinteger) | Call this method to return the integer component of a `CComCurrency` object. | +| [`CComCurrency::Round`](#round) | Call this method to round a `CComCurrency` object to the nearest integer value. | +| [`CComCurrency::SetFraction`](#setfraction) | Call this method to set the fractional component of a `CComCurrency` object. | +| [`CComCurrency::SetInteger`](#setinteger) | Call this method to set the integer component of a `CComCurrency` object. | + +### Public operators + +| Name | Description | +|--|--| +| [`CComCurrency::operator -`](#operator_-) | This operator is used to perform subtraction on a `CComCurrency` object. | +| [`CComCurrency::operator !=`](#operator_neq) | Compares two `CComCurrency` objects for inequality. | +| [`CComCurrency::operator *`](#operator_star) | This operator is used to perform multiplication on a `CComCurrency` object. | +| [`CComCurrency::operator *=`](#operator_star_eq) | This operator is used to perform multiplication on a `CComCurrency` object and assign it the result. | +| [`CComCurrency::operator /`](#operator_div) | This operator is used to perform division on a `CComCurrency` object. | +| [`CComCurrency::operator /=`](#operator_div_eq) | This operator is used to perform division on a `CComCurrency` object and assign it the result. | +| [`CComCurrency::operator +`](#operator_add) | This operator is used to perform addition on a `CComCurrency` object. | +| [`CComCurrency::operator +=`](#operator_add_eq) | This operator is used to perform addition on a `CComCurrency` object and assign the result to the current object. | +| [`CComCurrency::operator <`](#operator_lt) | This operator compares two `CComCurrency` objects to determine the lesser. | +| [`CComCurrency::operator <=`](#operator_lt_eq) | This operator compares two `CComCurrency` objects to determine equality or the lesser. | +| [`CComCurrency::operator =`](#operator_eq) | This operator assigns the `CComCurrency` object to a new value. | +| [`CComCurrency::operator -=`](#operator_-_eq) | This operator is used to perform subtraction on a `CComCurrency` object and assign it the result. | +| [`CComCurrency::operator ==`](#operator_eq_eq) | This operator compares two `CComCurrency` objects for equality. | +| [`CComCurrency::operator >`](#operator_gt) | This operator compares two `CComCurrency` objects to determine the larger. | +| [`CComCurrency::operator >=`](#operator_gt_eq) | This operator compares two `CComCurrency` objects to determine equality or the larger. | +| [`CComCurrency::operator CURRENCY`](#operator_currency) | Casts a `CURRENCY` object. | + +### Public data members + +| Name | Description | +|--|--| +| [`CComCurrency::m_currency`](#m_currency) | The `CURRENCY` variable created by your class instance. | ## Remarks -`CComCurrency` is a wrapper for the CURRENCY data type. CURRENCY is implemented as an 8-byte two's-complement integer value scaled by 10,000. This gives a fixed-point number with 15 digits to the left of the decimal point and 4 digits to the right. The CURRENCY data type is extremely useful for calculations involving money, or for any fixed-point calculations where accuracy is important. +`CComCurrency` is a wrapper for the `CURRENCY` data type. `CURRENCY` is implemented as an 8-byte two's-complement integer value scaled by 10,000. This scaling gives a fixed-point number with 15 digits left of the decimal point and 4 digits to the right. The `CURRENCY` data type is useful for calculations involving money, or for any fixed-point calculations where accuracy is important. The `CComCurrency` wrapper implements arithmetic, assignment, and comparison operations for this fixed-point type. The supported applications have been selected to control the rounding errors that can occur during fixed-point calculations. -The `CComCurrency` object provides access to the numbers on either side of the decimal point in the form of two components: an integer component which stores the value to the left of the decimal point, and a fractional component which stores the value to the right of the decimal point. The fractional component is stored internally as an integer value between -9999 (CY_MIN_FRACTION) and +9999 (CY_MAX_FRACTION). The method [CComCurrency::GetFraction](#getfraction) returns a value scaled by a factor of 10000 (CY_SCALE). +The `CComCurrency` object provides access to the numbers on either side of the decimal point in the form of two components: an integer component, which stores the value to the left of the decimal point, and a fractional component, which stores the value to the right of the decimal point. The fractional component is stored internally as an integer value between -9999 (`CY_MIN_FRACTION`) and +9999 (`CY_MAX_FRACTION`). The method [`CComCurrency::GetFraction`](#getfraction) returns a value scaled by a factor of 10000 (`CY_SCALE`). -When specifying the integer and fractional components of a `CComCurrency` object, remember that the fractional component is a number in the range 0 to 9999. This is important when dealing with a currency such as the US dollar that expresses amounts using only two significant digits after the decimal point. Even though the last two digits are not displayed, they must be taken into account. +When specifying the integer and fractional components of a `CComCurrency` object, remember that the fractional component is a number in the range 0 to 9999. This consideration is important when dealing with a currency such as the US dollar. Dollar amounts are commonly expressed using only two significant digits after the decimal point. Even though the last two digits aren't displayed, they must be taken into account. -|Value|Possible CComCurrency assignments| -|-----------|---------------------------------------| -|$10.50|CComCurrency(10,5000) *or* CComCurrency(10.50)| -|$10.05|CComCurrency(10,500) *or* CComCurrency(10.05)| +| Value | Possible CComCurrency assignments | +|--|--| +| $10.50 | `CComCurrency(10,5000)` or `CComCurrency(10.50)` | +| $10.05 | `CComCurrency(10,500)` or `CComCurrency(10.05)` | -The values CY_MIN_FRACTION, CY_MAX_FRACTION, and CY_SCALE are defined in atlcur.h. +The values `CY_MIN_FRACTION`, `CY_MAX_FRACTION`, and `CY_SCALE` are defined in atlcur.h. ## Requirements **Header:** atlcur.h -## CComCurrency::CComCurrency +## `CComCurrency::CComCurrency` The constructor. -``` +```cpp CComCurrency() throw(); CComCurrency(const CComCurrency& curSrc) throw(); CComCurrency(CURRENCY cySrc) throw(); @@ -109,79 +108,79 @@ explicit CComCurrency(LPCSTR szSrc); ### Parameters -*curSrc*
+*`curSrc`*\ An existing `CComCurrency` object. -*cySrc*
-A variable of type CURRENCY. +*`cySrc`*\ +A variable of type `CURRENCY`. -*bSrc*, *dSrc*, *fSrc*, *lSrc*, *sSrc*, *ulSrc, usSrc*
+*`bSrc`*, *`dSrc`*, *`fSrc`*, *`lSrc`*, *`sSrc`*, *`ulSrc`*, *`usSrc`*\ The initial value given to the member variable `m_currency`. -*cSrc*
+*`cSrc`*\ A character containing the initial value given to the member variable `m_currency`. -*nInteger*, *nFraction*
-The integer and fractional components of the initial monetary value. See the [CComCurrency](../../atl/reference/ccomcurrency-class.md) overview for more information. +*`nInteger`*, *`nFraction`*\ +The initial monetary value's integer and fractional components. For more information, see the [`CComCurrency`](../../atl/reference/ccomcurrency-class.md) overview. -*pDispSrc*
+*`pDispSrc`*\ An `IDispatch` pointer. -*varSrc*
-A variable of type VARIANT. The locale of the current thread is used to perform the conversion. +*`varSrc`*\ +A variable of type `VARIANT`. The locale of the current thread is used to perform the conversion. -*szSrc*
+*`szSrc`*\ A Unicode or ANSI string containing the initial value. The locale of the current thread is used to perform the conversion. ### Remarks -The constructor sets the initial value of [CComCurrency::m_currency](#m_currency), and accepts a wide range of data types, including integers, strings, floating-point numbers, CURRENCY variables, and other `CComCurrency` objects. If no value is provided, `m_currency` is set to 0. +The constructor sets the initial value of [`CComCurrency::m_currency`](#m_currency), and accepts a wide range of data types, including integers, strings, floating-point numbers, `CURRENCY` variables, and other `CComCurrency` objects. If no value is provided, `m_currency` is set to 0. -In the event of an error, such as an overflow, the constructors lacking an empty exception specification (**throw()**) call `AtlThrow` with an HRESULT describing the error. +If there's an error, such as an overflow, the constructors lacking an empty exception specification (**`throw()`**) call `AtlThrow` with an `HRESULT` describing the error. -When using floating-point or double values to assign a value, note that `CComCurrency(10.50)` is equivalent to `CComCurrency(10,5000)` and not `CComCurrency(10,50)`. +When using floating-point or double values to assign a value, remember that `CComCurrency(10.50)` is equivalent to `CComCurrency(10,5000)`, and not `CComCurrency(10,50)`. -## CComCurrency::GetCurrencyPtr +## `CComCurrency::GetCurrencyPtr` Returns the address of an `m_currency` data member. -``` +```cpp CURRENCY* GetCurrencyPtr() throw(); ``` -### Return Value +### Return value Returns the address of an `m_currency` data member -## CComCurrency::GetFraction +## `CComCurrency::GetFraction` Call this method to return the fractional component of the `CComCurrency` object. -``` +```cpp SHORT GetFraction() const; ``` -### Return Value +### Return value Returns the fractional component of the `m_currency` data member. ### Remarks -The fractional component is a 4-digit integer value between -9999 (CY_MIN_FRACTION) and +9999 (CY_MAX_FRACTION). `GetFraction` returns this value scaled by 10000 (CY_SCALE). The values of CY_MIN_FRACTION, CY_MAX_FRACTION, and CY_SCALE are defined in atlcur.h. +The fractional component is a 4-digit integer value between -9999 (`CY_MIN_FRACTION`) and +9999 (`CY_MAX_FRACTION`). `GetFraction` returns this value scaled by 10000 (`CY_SCALE`). The values of `CY_MIN_FRACTION`, `CY_MAX_FRACTION`, and `CY_SCALE` are defined in atlcur.h. ### Example [!code-cpp[NVC_ATL_Utilities#50](../../atl/codesnippet/cpp/ccomcurrency-class_1.cpp)] -## CComCurrency::GetInteger +## `CComCurrency::GetInteger` Call this method to get the integer component of a `CComCurrency` object. -``` +```cpp LONGLONG GetInteger() const; ``` -### Return Value +### Return value Returns the integer component of the `m_currency` data member. @@ -189,11 +188,11 @@ Returns the integer component of the `m_currency` data member. [!code-cpp[NVC_ATL_Utilities#51](../../atl/codesnippet/cpp/ccomcurrency-class_2.cpp)] -## CComCurrency::m_currency +## `CComCurrency::m_currency` -The CURRENCY data member. +The `CURRENCY` data member. -``` +```cpp CURRENCY m_currency; ``` @@ -201,113 +200,113 @@ CURRENCY m_currency; This member holds the currency accessed and manipulated by the methods of this class. -## CComCurrency::operator - +## `CComCurrency::operator -` This operator is used to perform subtraction on a `CComCurrency` object. -``` +```cpp CComCurrency operator-() const; CComCurrency operator-(const CComCurrency& cur) const; ``` ### Parameters -*cur*
+*`cur`*\ A `CComCurrency` object. -### Return Value +### Return value -Returns a `CComCurrency` object representing the result of the subtraction. In the event of an error, such as an overflow, this operator calls `AtlThrow` with an HRESULT describing the error. +Returns a `CComCurrency` object representing the result of the subtraction. If there's an error, such as an overflow, this operator calls `AtlThrow` with an `HRESULT` describing the error. ### Example [!code-cpp[NVC_ATL_Utilities#55](../../atl/codesnippet/cpp/ccomcurrency-class_3.cpp)] -## CComCurrency::operator != +## `CComCurrency::operator !=` This operator compares two objects for inequality. -``` +```cpp bool operator!= (const CComCurrency& cur) const; ``` ### Parameters -*cur*
+*`cur`*\ The `CComCurrency` object to be compared. -### Return Value +### Return value -Returns TRUE if the item being compared is not equal to the `CComCurrency` object; otherwise, FALSE. +Returns `TRUE` if the item being compared isn't equal to the `CComCurrency` object; otherwise, `FALSE`. ### Example [!code-cpp[NVC_ATL_Utilities#56](../../atl/codesnippet/cpp/ccomcurrency-class_4.cpp)] -## CComCurrency::operator * +## `CComCurrency::operator *` This operator is used to perform multiplication on a `CComCurrency` object. -``` +```cpp CComCurrency operator*(long nOperand) const; CComCurrency operator*(const CComCurrency& cur) const; ``` ### Parameters -*nOperand*
+*`nOperand`*\ The multiplier. -*cur*
+*`cur`*\ The `CComCurrency` object used as the multiplier. -### Return Value +### Return value -Returns a `CComCurrency` object representing the result of the multiplication. In the event of an error, such as an overflow, this operator calls `AtlThrow` with an HRESULT describing the error. +Returns a `CComCurrency` object representing the result of the multiplication. If there's an error, such as an overflow, this operator calls `AtlThrow` with an `HRESULT` describing the error. ### Example [!code-cpp[NVC_ATL_Utilities#57](../../atl/codesnippet/cpp/ccomcurrency-class_5.cpp)] -## CComCurrency::operator \*= +## `CComCurrency::operator *=` This operator is used to perform multiplication on a `CComCurrency` object and assign it the result. -``` +```cpp const CComCurrency& operator*= (long nOperand); const CComCurrency& operator*= (const CComCurrency& cur); ``` ### Parameters -*nOperand*
+*`nOperand`*\ The multiplier. -*cur*
+*`cur`*\ The `CComCurrency` object used as the multiplier. -### Return Value +### Return value -Returns the updated `CComCurrency` object. In the event of an error, such as an overflow, this operator calls `AtlThrow` with an HRESULT describing the error. +Returns the updated `CComCurrency` object. If there's an error, such as an overflow, this operator calls `AtlThrow` with an `HRESULT` describing the error. ### Example [!code-cpp[NVC_ATL_Utilities#58](../../atl/codesnippet/cpp/ccomcurrency-class_6.cpp)] -## CComCurrency::operator / +## `CComCurrency::operator /` This operator is used to perform division on a `CComCurrency` object. -``` +```cpp CComCurrency operator/(long nOperand) const; ``` ### Parameters -*nOperand*
+*`nOperand`*\ The divisor. -### Return Value +### Return value Returns a `CComCurrency` object representing the result of the division. If the divisor is 0, an assert failure will occur. @@ -315,20 +314,20 @@ Returns a `CComCurrency` object representing the result of the division. If the [!code-cpp[NVC_ATL_Utilities#59](../../atl/codesnippet/cpp/ccomcurrency-class_7.cpp)] -## CComCurrency::operator /= +## `CComCurrency::operator /=` This operator is used to perform division on a `CComCurrency` object and assign it the result. -``` +```cpp const CComCurrency& operator/= (long nOperand); ``` ### Parameters -*nOperand*
+*`nOperand`*\ The divisor. -### Return Value +### Return value Returns the updated `CComCurrency` object. If the divisor is 0, an assert failure will occur. @@ -336,95 +335,95 @@ Returns the updated `CComCurrency` object. If the divisor is 0, an assert failur [!code-cpp[NVC_ATL_Utilities#60](../../atl/codesnippet/cpp/ccomcurrency-class_8.cpp)] -## CComCurrency::operator + +## `CComCurrency::operator +` This operator is used to perform addition on a `CComCurrency` object. -``` +```cpp CComCurrency operator+(const CComCurrency& cur) const; ``` ### Parameters -*cur*
+*`cur`*\ The `CComCurrency` object to be added to the original object. -### Return Value +### Return value -Returns a `CComCurrency` object representing the result of the addition. In the event of an error, such as an overflow, this operator calls `AtlThrow` with an HRESULT describing the error. +Returns a `CComCurrency` object representing the result of the addition. If there's an error, such as an overflow, this operator calls `AtlThrow` with an `HRESULT` describing the error. ### Example [!code-cpp[NVC_ATL_Utilities#61](../../atl/codesnippet/cpp/ccomcurrency-class_9.cpp)] -## CComCurrency::operator += +## `CComCurrency::operator +=` This operator is used to perform addition on a `CComCurrency` object and assign the result to the current object. -``` +```cpp const CComCurrency& operator+= (const CComCurrency& cur); ``` ### Parameters -*cur*
+*`cur`*\ The `CComCurrency` object. -### Return Value +### Return value -Returns the updated `CComCurrency` object. In the event of an error, such as an overflow, this operator calls `AtlThrow` with an HRESULT describing the error. +Returns the updated `CComCurrency` object. If there's an error, such as an overflow, this operator calls `AtlThrow` with an `HRESULT` describing the error. ### Example [!code-cpp[NVC_ATL_Utilities#62](../../atl/codesnippet/cpp/ccomcurrency-class_10.cpp)] -## CComCurrency::operator < +## `CComCurrency::operator <` This operator compares two `CComCurrency` objects to determine the lesser. -``` +```cpp bool operator<(const CComCurrency& cur) const; ``` ### Parameters -*cur*
+*`cur`*\ A `CComCurrency` object. -### Return Value +### Return value -Returns TRUE if the first object is less than the second, FALSE otherwise. +Returns `TRUE` if the first object is less than the second, `FALSE` otherwise. ### Example [!code-cpp[NVC_ATL_Utilities#63](../../atl/codesnippet/cpp/ccomcurrency-class_11.cpp)] -## CComCurrency::operator <= +## `CComCurrency::operator <=` This operator compares two `CComCurrency` objects to determine equality or the lesser. -``` +```cpp bool operator<= (const CComCurrency& cur) const; ``` ### Parameters -*cur*
+*`cur`*\ A `CComCurrency` object. -### Return Value +### Return value -Returns TRUE if the first object is less than or equal to the second, FALSE otherwise. +Returns `TRUE` if the first object is less than or equal to the second, `FALSE` otherwise. ### Example [!code-cpp[NVC_ATL_Utilities#64](../../atl/codesnippet/cpp/ccomcurrency-class_12.cpp)] -## CComCurrency::operator = +## `CComCurrency::operator =` This operator assigns the `CComCurrency` object to a new value. -``` +```cpp const CComCurrency& operator= (const CComCurrency& curSrc) throw(); const CComCurrency& operator= (CURRENCY cySrc) throw(); const CComCurrency& operator= (FLOAT fSrc); @@ -440,184 +439,184 @@ const CComCurrency& operator= (DECIMAL dSrc); ### Parameters -*curSrc*
+*`curSrc`*\ A `CComCurrency` object. -*cySrc*
-A variable of type CURRENCY. +*`cySrc`*\ +A variable of type `CURRENCY`. -*sSrc*, *fSrc*, *lSrc*, *bSrc*, *usSrc*, *dSrc*, *cSrc*, *ulSrc*, *dSrc*
+*`sSrc`*, *`fSrc`*, *`lSrc`*, *`bSrc`*, *`usSrc`*, *`dSrc`*, *`cSrc`*, *`ulSrc`*, *`dSrc`*\ The numeric value to assign to the `CComCurrency` object. -### Return Value +### Return value -Returns the updated `CComCurrency` object. In the event of an error, such as an overflow, this operator calls `AtlThrow` with an HRESULT describing the error. +Returns the updated `CComCurrency` object. If there's an error, such as an overflow, this operator calls `AtlThrow` with an `HRESULT` describing the error. ### Example [!code-cpp[NVC_ATL_Utilities#65](../../atl/codesnippet/cpp/ccomcurrency-class_13.cpp)] -## CComCurrency::operator -= +## `CComCurrency::operator -=` This operator is used to perform subtraction on a `CComCurrency` object and assign it the result. -``` +```cpp const CComCurrency& operator-= (const CComCurrency& cur); ``` ### Parameters -*cur*
+*`cur`*\ A `CComCurrency` object. -### Return Value +### Return value -Returns the updated `CComCurrency` object. In the event of an error, such as an overflow, this operator calls `AtlThrow` with an HRESULT describing the error. +Returns the updated `CComCurrency` object. If there's an error, such as an overflow, this operator calls `AtlThrow` with an `HRESULT` describing the error. ### Example [!code-cpp[NVC_ATL_Utilities#66](../../atl/codesnippet/cpp/ccomcurrency-class_14.cpp)] -## CComCurrency::operator == +## `CComCurrency::operator ==` This operator compares two `CComCurrency` objects for equality. -``` +```cpp bool operator== (const CComCurrency& cur) const; ``` ### Parameters -*cur*
+*`cur`*\ The `CComCurrency` object to compare. -### Return Value +### Return value -Returns TRUE if the objects are equal (that is, the `m_currency` data members, both integer and fractional, in both objects have the same value), FALSE otherwise. +Returns `TRUE` if the objects are equal (that is, the `m_currency` data members, both integer and fractional, in both objects have the same value), `FALSE` otherwise. ### Example [!code-cpp[NVC_ATL_Utilities#67](../../atl/codesnippet/cpp/ccomcurrency-class_15.cpp)] -## CComCurrency::operator > +## `CComCurrency::operator >` This operator compares two `CComCurrency` objects to determine the larger. -``` +```cpp bool operator>(const CComCurrency& cur) const; ``` ### Parameters -*cur*
+*`cur`*\ A `CComCurrency` object. -### Return Value +### Return value -Returns TRUE if the first object is greater than the second, FALSE otherwise. +Returns `TRUE` if the first object is greater than the second, `FALSE` otherwise. ### Example [!code-cpp[NVC_ATL_Utilities#68](../../atl/codesnippet/cpp/ccomcurrency-class_16.cpp)] -## CComCurrency::operator >= +## `CComCurrency::operator >=` This operator compares two `CComCurrency` objects to determine equality or the larger. -``` +```cpp bool operator>= (const CComCurrency& cur) const; ``` ### Parameters -*cur*
+*`cur`*\ A `CComCurrency` object. -### Return Value +### Return value -Returns TRUE if the first object is greater than or equal to the second, FALSE otherwise. +Returns `TRUE` if the first object is greater than or equal to the second, `FALSE` otherwise. ### Example [!code-cpp[NVC_ATL_Utilities#69](../../atl/codesnippet/cpp/ccomcurrency-class_17.cpp)] -## CComCurrency::operator CURRENCY +## `CComCurrency::operator CURRENCY` -These operators are used to cast a `CComCurrency` object to a CURRENCY data type. +These operators are used to cast a `CComCurrency` object to a `CURRENCY` data type. -``` +```cpp operator CURRENCY&() throw(); operator const CURRENCY&() const throw(); ``` -### Return Value +### Return value -Returns a reference to a CURRENCY object. +Returns a reference to a `CURRENCY` object. ### Example [!code-cpp[NVC_ATL_Utilities#70](../../atl/codesnippet/cpp/ccomcurrency-class_18.cpp)] -## CComCurrency::Round +## `CComCurrency::Round` Call this method to round the currency to a specified number of decimal places. -``` -HRESULT Roundint nDecimals); +```cpp +HRESULT Round(int nDecimals); ``` ### Parameters -*nDecimals*
+*`nDecimals`*\ The number of digits to which `m_currency` will be rounded, in the range 0 to 4. -### Return Value +### Return value -Returns S_OK on success, or an error HRESULT on failure. +Returns `S_OK` on success, or an error `HRESULT` on failure. ### Example [!code-cpp[NVC_ATL_Utilities#52](../../atl/codesnippet/cpp/ccomcurrency-class_19.cpp)] -## CComCurrency::SetFraction +## `CComCurrency::SetFraction` Call this method to set the fractional component of a `CComCurrency` object. -``` +```cpp HRESULT SetFraction(SHORT nFraction); ``` ### Parameters -*nFraction*
-The value to be assigned to the fractional component of the `m_currency` data member. The sign of the fractional component must the same as the integer component, and the value must be in range -9999 (CY_MIN_FRACTION) to +9999 (CY_MAX_FRACTION). +*`nFraction`*\ +The value to assign to the fractional component of the `m_currency` data member. The sign of the fractional component must be the same as the integer component, and the value must be in the range -9999 (`CY_MIN_FRACTION`) to +9999 (`CY_MAX_FRACTION`). -### Return Value +### Return value -Returns S_OK on success, or an error HRESULT on failure. +Returns `S_OK` on success, or an error `HRESULT` on failure. ### Example [!code-cpp[NVC_ATL_Utilities#53](../../atl/codesnippet/cpp/ccomcurrency-class_20.cpp)] -## CComCurrency::SetInteger +## `CComCurrency::SetInteger` Call this method to set the integer component of a `CComCurrency` object. -``` +```cpp HRESULT SetInteger(LONGLONG nInteger); ``` ### Parameters -*nInteger*
+*`nInteger`*\ The value to be assigned to the integer component of the `m_currency` data member. The sign of the integer component must match the sign of the existing fractional component. -*nInteger* must be in the range CY_MIN_INTEGER to CY_MAX_INTEGER inclusive. These values are defined in atlcur.h. +*`nInteger`* must be in the range `CY_MIN_INTEGER` to `CY_MAX_INTEGER`, inclusive. These values are defined in atlcur.h. -### Return Value +### Return value -Returns S_OK on success, or an error HRESULT on failure. +Returns `S_OK` on success, or an error `HRESULT` on failure. ### Example @@ -625,6 +624,6 @@ Returns S_OK on success, or an error HRESULT on failure. ## See also -[COleCurrency Class](../../mfc/reference/colecurrency-class.md)
-[CURRENCY](/windows/win32/api/wtypes/ns-wtypes-cy-r1)
-[Class Overview](../../atl/atl-class-overview.md) +[`COleCurrency` class](../../mfc/reference/colecurrency-class.md)\ +[`CURRENCY`](/windows/win32/api/wtypes/ns-wtypes-cy-r1)\ +[Class overview](../../atl/atl-class-overview.md) diff --git a/docs/atl/reference/ccomdynamicunkarray-class.md b/docs/atl/reference/ccomdynamicunkarray-class.md index 19adbd15a5..0c0f142ee6 100644 --- a/docs/atl/reference/ccomdynamicunkarray-class.md +++ b/docs/atl/reference/ccomdynamicunkarray-class.md @@ -35,7 +35,7 @@ class CComDynamicUnkArray |[CComDynamicUnkArray::end](#end)|Returns a pointer to one past the last `IUnknown` pointer in the collection.| |[CComDynamicUnkArray::GetAt](#getat)|Retrieves the element at the specified index.| |[CComDynamicUnkArray::GetCookie](#getcookie)|Call this method to get the cookie associated with a given `IUnknown` pointer.| -|[CComDynamicUnkArray::GetSize](#getsize)|Returns the length of an array.| +|[CComDynamicUnkArray::GetSize](#getsize)|Returns the number of elements the array can store.| |[CComDynamicUnkArray::GetUnknown](#getunknown)|Call this method to get the `IUnknown` pointer associated with a given cookie.| |[CComDynamicUnkArray::Remove](#remove)|Call this method to remove an `IUnknown` pointer from the array.| @@ -69,7 +69,12 @@ The `IUnknown` pointer to add to the array. ### Return Value -Returns the cookie associated with the newly added pointer. +Returns the cookie associated with the newly added pointer. Use this cookie to retrieve the pointer from the array with [CComDynamicUnkArray::GetAt](#getat). + +### Remarks + +The position where this item is inserted won't necessarily be directly after the last-inserted item if `Remove()` was previously called on this array. Use the returned cookie to reliably access the inserted pointer. +The array's size might be increased to accommodate more items. Use `GetSize()` to get the new size. ## CComDynamicUnkArray::begin @@ -92,7 +97,7 @@ Before using the `IUnknown` interface, you should check that it is not NULL. ## CComDynamicUnkArray::clear -Empties the array. +Empties the array. Resets the size to 0. ```cpp void clear(); @@ -124,7 +129,9 @@ Frees resources allocated by the class constructor. ## CComDynamicUnkArray::end -Returns a pointer to one past the last `IUnknown` pointer in the collection. +Returns a pointer to one-past the last element in the array's allocated buffer. + +Note: this means that the last-inserted pointer is not guaranteed to be at `end()-1` because the array may not be filled to capacity. ``` IUnknown** @@ -150,7 +157,7 @@ The index of the element to retrieve. ### Return Value -A pointer to an [IUnknown](/windows/win32/api/unknwn/nn-unknwn-iunknown) interface. +A pointer to an [IUnknown](/windows/win32/api/unknwn/nn-unknwn-iunknown) interface if an element was previously added and exists at this index; otherwise `NULL`. ## CComDynamicUnkArray::GetCookie @@ -175,7 +182,9 @@ If there is more than one instance of the same `IUnknown` pointer, this function ## CComDynamicUnkArray::GetSize -Returns the length of an array. +Returns the allocated capacity of the array. + +Note: this is not the same as the number of non-NULL elements currently in the array. ``` int GetSize() const; @@ -183,9 +192,9 @@ int GetSize() const; ### Return Value -The length of the array. +The number of elements the array can store. `GetSize() == end() - begin()`. -## CComDynamicUnkArray::GetUnknown +## CComDynamicUnkArray::GetUnknown Call this method to get the `IUnknown` pointer associated with a given cookie. @@ -206,6 +215,8 @@ Returns the `IUnknown` pointer, or NULL if no matching cookie is found. Call this method to remove an `IUnknown` pointer from the array. +All other elements are unchanged and retain their index and cookie. + ``` BOOL Remove(DWORD dwCookie); ``` diff --git a/docs/atl/reference/ccomenum-class.md b/docs/atl/reference/ccomenum-class.md index 8ca27ce7d6..874c02b84c 100644 --- a/docs/atl/reference/ccomenum-class.md +++ b/docs/atl/reference/ccomenum-class.md @@ -76,7 +76,7 @@ The code shown below provides a reusable function for creating and initializing [!code-cpp[NVC_ATL_COM#32](../../atl/codesnippet/cpp/ccomenum-class_1.h)] -This template function can be used to implement the `_NewEnum` property of a collection interface as shown below: +This function template can be used to implement the `_NewEnum` property of a collection interface as shown below: [!code-cpp[NVC_ATL_COM#33](../../atl/codesnippet/cpp/ccomenum-class_2.h)] diff --git a/docs/atl/reference/ccomenumonstl-class.md b/docs/atl/reference/ccomenumonstl-class.md index c84d245c6b..7ab682b506 100644 --- a/docs/atl/reference/ccomenumonstl-class.md +++ b/docs/atl/reference/ccomenumonstl-class.md @@ -85,7 +85,7 @@ The code shown below provides a generic function to handle the creation and init [!code-cpp[NVC_ATL_COM#34](../../atl/codesnippet/cpp/ccomenumonstl-class_1.h)] -This template function can be used to implement the `_NewEnum` property of a collection interface as shown below: +This function template can be used to implement the `_NewEnum` property of a collection interface as shown below: [!code-cpp[NVC_ATL_COM#35](../../atl/codesnippet/cpp/ccomenumonstl-class_2.h)] diff --git a/docs/atl/reference/ccomheap-class.md b/docs/atl/reference/ccomheap-class.md index 4d6da24e95..f561ecf30d 100644 --- a/docs/atl/reference/ccomheap-class.md +++ b/docs/atl/reference/ccomheap-class.md @@ -6,39 +6,39 @@ f1_keywords: ["CComHeap", "ATLCOMMEM/ATL::CComHeap", "ATLCOMMEM/ATL::CComHeap::A helpviewer_keywords: ["CComHeap class"] ms.assetid: c74183ce-98ae-46fb-b186-93ea4cf0222b --- -# CComHeap Class +# `CComHeap` Class -This class implements [IAtlMemMgr](../../atl/reference/iatlmemmgr-class.md) using the COM memory allocation functions. +This class implements [`IAtlMemMgr`](../../atl/reference/iatlmemmgr-class.md) using the COM memory allocation functions. > [!IMPORTANT] > This class and its members cannot be used in applications that execute in the Windows Runtime. ## Syntax -``` +```cpp class CComHeap : public IAtlMemMgr ``` ## Members -### Public Methods +### Public methods |Name|Description| |----------|-----------------| -|[CComHeap::Allocate](#allocate)|Call this method to allocate a block of memory.| -|[CComHeap::Free](#free)|Call this method to free a block of memory allocated by this memory manager.| -|[CComHeap::GetSize](#getsize)|Call this method to get the allocated size of a memory block allocated by this memory manager.| -|[CComHeap::Reallocate](#reallocate)|Call this method to reallocate memory allocated by this memory manager.| +|[`CComHeap::Allocate`](#allocate)|Call this method to allocate a block of memory.| +|[`CComHeap::Free`](#free)|Call this method to free a block of memory allocated by this memory manager.| +|[`CComHeap::GetSize`](#getsize)|Call this method to get the allocated size of a memory block allocated by this memory manager.| +|[`CComHeap::Reallocate`](#reallocate)|Call this method to reallocate memory allocated by this memory manager.| ## Remarks -`CComHeap` implements memory allocation functions using the COM allocation functions, including [CoTaskMemAlloc](/windows/win32/api/combaseapi/nf-combaseapi-cotaskmemalloc), [CoTaskMemFree](/windows/win32/api/combaseapi/nf-combaseapi-cotaskmemfree), [IMalloc::GetSize](/windows/win32/api/objidlbase/nf-objidlbase-imalloc-getsize), and [CoTaskMemRealloc](/windows/win32/api/combaseapi/nf-combaseapi-cotaskmemrealloc). The maximum amount of memory that can be allocated is equal to INT_MAX (2147483647) bytes. +`CComHeap` implements memory allocation functions using the COM allocation functions, including [`CoTaskMemAlloc`](/windows/win32/api/combaseapi/nf-combaseapi-cotaskmemalloc), [`CoTaskMemFree`](/windows/win32/api/combaseapi/nf-combaseapi-cotaskmemfree), [`IMalloc::GetSize`](/windows/win32/api/objidlbase/nf-objidlbase-imalloc-getsize), and [`CoTaskMemRealloc`](/windows/win32/api/combaseapi/nf-combaseapi-cotaskmemrealloc). The maximum amount of memory that can be allocated is equal to `INT_MAX` (2147483647) bytes. ## Example -See the example for [IAtlMemMgr](../../atl/reference/iatlmemmgr-class.md). +See the example for [`IAtlMemMgr`](../../atl/reference/iatlmemmgr-class.md). -## Inheritance Hierarchy +## Inheritance hierarchy `IAtlMemMgr` @@ -52,95 +52,95 @@ See the example for [IAtlMemMgr](../../atl/reference/iatlmemmgr-class.md). Call this method to allocate a block of memory. -``` +```cpp virtual __declspec(allocator) void* Allocate(size_t nBytes) throw(); ``` ### Parameters -*nBytes*
+*`nBytes`*\ The requested number of bytes in the new memory block. -### Return Value +### Return value Returns a pointer to the start of the newly allocated memory block. ### Remarks -Call [CComHeap::Free](#free) or [CComHeap::Reallocate](#reallocate) to free the memory allocated by this method. +Call [`CComHeap::Free`](#free) or [`CComHeap::Reallocate`](#reallocate) to free the memory allocated by this method. -Implemented using [CoTaskMemAlloc](/windows/win32/api/combaseapi/nf-combaseapi-cotaskmemalloc). +Implemented using [`CoTaskMemAlloc`](/windows/win32/api/combaseapi/nf-combaseapi-cotaskmemalloc). ## CComHeap::Free Call this method to free a block of memory allocated by this memory manager. -``` +```cpp virtual void Free(void* p) throw(); ``` ### Parameters -*p*
+*`p`*\ Pointer to memory previously allocated by this memory manager. NULL is a valid value and does nothing. ### Remarks -Implemented using [CoTaskMemFree](/windows/win32/api/combaseapi/nf-combaseapi-cotaskmemfree). +Implemented using [`CoTaskMemFree`](/windows/win32/api/combaseapi/nf-combaseapi-cotaskmemfree). ## CComHeap::GetSize Call this method to get the allocated size of a memory block allocated by this memory manager. -``` +```cpp virtual size_t GetSize(void* p) throw(); ``` ### Parameters -*p*
+*`p`*\ Pointer to memory previously allocated by this memory manager. -### Return Value +### Return value Returns the size of the allocated memory block in bytes. ### Remarks -Implemented using [IMalloc::GetSize](/windows/win32/api/objidlbase/nf-objidlbase-imalloc-getsize). +Implemented using [`IMalloc::GetSize`](/windows/win32/api/objidlbase/nf-objidlbase-imalloc-getsize). ## CComHeap::Reallocate Call this method to reallocate memory allocated by this memory manager. -``` +```cpp virtual __declspec(allocator) void* Reallocate(void* p, size_t nBytes) throw(); ``` ### Parameters -*p*
+*`p`*\ Pointer to memory previously allocated by this memory manager. -*nBytes*
+*`nBytes`*\ The requested number of bytes in the new memory block. -### Return Value +### Return value Returns a pointer to the start of the newly allocated memory block. ### Remarks -Call [CComHeap::Free](#free) to free the memory allocated by this method. +Call [`CComHeap::Free`](#free) to free the memory allocated by this method. -Implemented using [CoTaskMemRealloc](/windows/win32/api/combaseapi/nf-combaseapi-cotaskmemrealloc). +Implemented using [`CoTaskMemRealloc`](/windows/win32/api/combaseapi/nf-combaseapi-cotaskmemrealloc). ## See also -[DynamicConsumer Sample](../../overview/visual-cpp-samples.md)
-[Class Overview](../../atl/atl-class-overview.md)
-[CWin32Heap Class](../../atl/reference/cwin32heap-class.md)
-[CLocalHeap Class](../../atl/reference/clocalheap-class.md)
-[CGlobalHeap Class](../../atl/reference/cglobalheap-class.md)
-[CCRTHeap Class](../../atl/reference/ccrtheap-class.md)
-[IAtlMemMgr Class](../../atl/reference/iatlmemmgr-class.md) +[DynamicConsumer Sample](../../overview/visual-cpp-samples.md)\ +[Class Overview](../../atl/atl-class-overview.md)\ +[`CWin32Heap` Class](../../atl/reference/cwin32heap-class.md)\ +[`CLocalHeap` Class](../../atl/reference/clocalheap-class.md)\ +[`CGlobalHeap` Class](../../atl/reference/cglobalheap-class.md)\ +[`CCRTHeap` Class](../../atl/reference/ccrtheap-class.md)\ +[`IAtlMemMgr` Class](../../atl/reference/iatlmemmgr-class.md) diff --git a/docs/atl/reference/ccommultithreadmodel-class.md b/docs/atl/reference/ccommultithreadmodel-class.md index 167fe9c3c7..651aa91f66 100644 --- a/docs/atl/reference/ccommultithreadmodel-class.md +++ b/docs/atl/reference/ccommultithreadmodel-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CComMultiThreadModel Class" title: "CComMultiThreadModel Class" +description: "Learn more about: CComMultiThreadModel Class" ms.date: "11/04/2016" f1_keywords: ["CComMultiThreadModel", "ATLBASE/ATL::CComMultiThreadModel", "ATLBASE/ATL::CComMultiThreadModel::AutoCriticalSection", "ATLBASE/ATL::CComMultiThreadModel::CriticalSection", "ATLBASE/ATL::CComMultiThreadModel::ThreadModelNoCS", "ATLBASE/ATL::CComMultiThreadModel::Decrement", "ATLBASE/ATL::CComMultiThreadModel::Increment"] helpviewer_keywords: ["ATL, multithreading", "CComMultiThreadModel class", "threading [ATL]"] -ms.assetid: db8f1662-2f7a-44b3-b341-ffbfb6e422a3 --- # CComMultiThreadModel Class @@ -12,7 +11,7 @@ ms.assetid: db8f1662-2f7a-44b3-b341-ffbfb6e422a3 ## Syntax -``` +```cpp class CComMultiThreadModel ``` @@ -35,7 +34,7 @@ class CComMultiThreadModel ## Remarks -Typically, you use `CComMultiThreadModel` through one of two **`typedef`** names, either [CComObjectThreadModel](atl-typedefs.md#ccomobjectthreadmodel or [CComGlobalsThreadModel](atl-typedefs.md#ccomglobalsthreadmodel. The class referenced by each **`typedef`** depends on the threading model used, as shown in the following table: +Typically, you use `CComMultiThreadModel` through one of two **`typedef`** names, either [CComObjectThreadModel](atl-typedefs.md#ccomobjectthreadmodel) or [CComGlobalsThreadModel](atl-typedefs.md#ccomglobalsthreadmodel). The class referenced by each **`typedef`** depends on the threading model used, as shown in the following table: |typedef|Single threading|Apartment threading|Free threading| |-------------|----------------------|-------------------------|--------------------| @@ -54,7 +53,7 @@ S= `CComSingleThreadModel`; M= `CComMultiThreadModel` When using `CComMultiThreadModel`, the **`typedef`** name `AutoCriticalSection` references class [CComAutoCriticalSection](ccomautocriticalsection-class.md), which provides methods for obtaining and releasing ownership of a critical section object. -``` +```cpp typedef CComAutoCriticalSection AutoCriticalSection; ``` @@ -120,7 +119,7 @@ The following tables show the results of the `InternalAddRef` and `Lock` methods When using `CComMultiThreadModel`, the **`typedef`** name `CriticalSection` references class [CComCriticalSection](ccomcriticalsection-class.md), which provides methods for obtaining and releasing ownership of a critical section object. -``` +```cpp typedef CComCriticalSection CriticalSection; ``` @@ -144,13 +143,13 @@ See [CComMultiThreadModel::AutoCriticalSection](#autocriticalsection). This static function calls the Win32 function [InterlockedDecrement](/windows/win32/api/winnt/nf-winnt-interlockeddecrement), which decrements the value of the variable pointed to by *p*. -``` +```cpp static ULONG WINAPI Decrement(LPLONG p) throw (); ``` ### Parameters -*p*
+*p*\ [in] Pointer to the variable to be decremented. ### Return Value @@ -165,13 +164,13 @@ If the result of the decrement is 0, then `Decrement` returns 0. If the result o This static function calls the Win32 function [InterlockedIncrement](/windows/win32/api/winnt/nf-winnt-interlockedincrement), which increments the value of the variable pointed to by *p*. -``` +```cpp static ULONG WINAPI Increment(LPLONG p) throw (); ``` ### Parameters -*p*
+*p*\ [in] Pointer to the variable to be incremented. ### Return Value @@ -186,7 +185,7 @@ If the result of the increment is 0, then `Increment` returns 0. If the result o When using `CComMultiThreadModel`, the **`typedef`** name `ThreadModelNoCS` references class [CComMultiThreadModelNoCS](ccommultithreadmodelnocs-class.md). -``` +```cpp typedef CComMultiThreadModelNoCS ThreadModelNoCS; ``` @@ -208,7 +207,7 @@ See [CComMultiThreadModel::AutoCriticalSection](#autocriticalsection). ## See also -[CComSingleThreadModel Class](ccomsinglethreadmodel-class.md)
-[CComAutoCriticalSection Class](ccomautocriticalsection-class.md)
-[CComCriticalSection Class](ccomcriticalsection-class.md)
+[CComSingleThreadModel Class](ccomsinglethreadmodel-class.md)\ +[CComAutoCriticalSection Class](ccomautocriticalsection-class.md)\ +[CComCriticalSection Class](ccomcriticalsection-class.md)\ [Class Overview](../atl-class-overview.md) diff --git a/docs/atl/reference/ccomobject-class.md b/docs/atl/reference/ccomobject-class.md index 7c63e2eca1..940285715a 100644 --- a/docs/atl/reference/ccomobject-class.md +++ b/docs/atl/reference/ccomobject-class.md @@ -125,7 +125,7 @@ If you do not need direct access to the object, but still want to create a new o ### Example [!code-cpp[NVC_ATL_COM#38](../../atl/codesnippet/cpp/ccomobject-class_1.h)] - +  [!code-cpp[NVC_ATL_COM#39](../../atl/codesnippet/cpp/ccomobject-class_2.cpp)] ## CComObject::QueryInterface diff --git a/docs/atl/reference/ccomptr-class.md b/docs/atl/reference/ccomptr-class.md index cfc07923e8..6ccf609038 100644 --- a/docs/atl/reference/ccomptr-class.md +++ b/docs/atl/reference/ccomptr-class.md @@ -6,7 +6,7 @@ f1_keywords: ["CComPtr", "ATLBASE/ATL::CComPtr", "ATLBASE/ATL::CComPtr::CComPtr" helpviewer_keywords: ["CComPtr class"] ms.assetid: 22d9ea8d-ed66-4c34-940f-141db11e83bd --- -# CComPtr Class +# `CComPtr` Class A smart pointer class for managing COM interface pointers. @@ -19,7 +19,7 @@ class CComPtr ### Parameters -*T*
+*`T`*
A COM interface specifying the type of pointer to be stored. ## Members @@ -28,37 +28,37 @@ A COM interface specifying the type of pointer to be stored. |Name|Description| |----------|-----------------| -|[CComPtr::CComPtr](#ccomptr)|The constructor.| +|[`CComPtr::CComPtr`](#ccomptr)|The constructor.| ### Public Operators |Name|Description| |----------|-----------------| -|[CComPtr::operator =](#operator_eq)|Assigns a pointer to the member pointer.| +|[`CComPtr::operator =`](#operator_eq)|Assigns a pointer to the member pointer.| ## Remarks -ATL uses `CComPtr` and [CComQIPtr](../../atl/reference/ccomqiptr-class.md) to manage COM interface pointers. Both are derived from [CComPtrBase](../../atl/reference/ccomptrbase-class.md), and both do automatic reference counting. +ATL uses `CComPtr` and [`CComQIPtr`](../../atl/reference/ccomqiptr-class.md) to manage COM interface pointers. Both are derived from [`CComPtrBase`](../../atl/reference/ccomptrbase-class.md), and both do automatic reference counting. -The `CComPtr` and [CComQIPtr](../../atl/reference/ccomqiptr-class.md) classes can help eliminate memory leaks by performing automatic reference counting. The following functions both do the same logical operations. However, the second version may be less error-prone because it uses the `CComPtr` class: +The `CComPtr` and [`CComQIPtr`](../../atl/reference/ccomqiptr-class.md) classes can help eliminate memory leaks by performing automatic reference counting. The following functions both do the same logical operations. However, the second version may be less error-prone because it uses the `CComPtr` class: [!code-cpp[NVC_ATL_Utilities#130](../../atl/codesnippet/cpp/ccomptr-class_1.cpp)] - +  [!code-cpp[NVC_ATL_Utilities#131](../../atl/codesnippet/cpp/ccomptr-class_2.cpp)] In Debug builds, link atlsd.lib for code tracing. ## Inheritance Hierarchy -[CComPtrBase](../../atl/reference/ccomptrbase-class.md) +[`CComPtrBase`](../../atl/reference/ccomptrbase-class.md) `CComPtr` ## Requirements -**Header:** atlbase.h +**Header:** `atlbase.h` -## CComPtr::CComPtr +## `CComPtr::CComPtr` The constructor. @@ -70,17 +70,17 @@ CComPtr (const CComPtr& lp) throw (); ### Parameters -*lp*
+*`lp`*
Used to initialize the interface pointer. -*T*
+*`T`*
A COM interface. ### Remarks -The constructors that take an argument call `AddRef` on *lp*, if it isn't a null pointer. A non-null owned object gets a `Release` call upon the CComPtr object's destruction, or if a new object is assigned to the CComPtr object. +The constructors that take an argument call `AddRef` on *`lp`*, if it isn't a null pointer. A non-null owned object gets a `Release` call upon the CComPtr object's destruction, or if a new object is assigned to the CComPtr object. -## CComPtr::operator = +## `CComPtr::operator =` Assignment operator. @@ -99,6 +99,6 @@ This operation AddRefs the new object and releases the existing object, if one e ## See also -[CComPtr::CComPtr](#ccomptr)
-[CComQIPtr::CComQIPtr](../../atl/reference/ccomqiptr-class.md#ccomqiptr)
+[`CComPtr::CComPtr`](#ccomptr)
+[`CComQIPtr::CComQIPtr`](../../atl/reference/ccomqiptr-class.md#ccomqiptr)
[Class Overview](../../atl/atl-class-overview.md) diff --git a/docs/atl/reference/ccomptrbase-class.md b/docs/atl/reference/ccomptrbase-class.md index 3ba4288403..c2363d848e 100644 --- a/docs/atl/reference/ccomptrbase-class.md +++ b/docs/atl/reference/ccomptrbase-class.md @@ -6,75 +6,75 @@ f1_keywords: ["CComPtrBase", "ATLCOMCLI/ATL::CComPtrBase", "ATLCOMCLI/ATL::CComP helpviewer_keywords: ["CComPtrBase class"] ms.assetid: 6dbe9543-dee8-4a97-b02f-dd3a25f4a1a0 --- -# CComPtrBase Class +# `CComPtrBase` Class This class provides a basis for smart pointer classes using COM-based memory routines. ## Syntax -``` +```cpp template class CComPtrBase ``` -#### Parameters +### Parameters -*T*
+*`T`*\ The object type to be referenced by the smart pointer. ## Members -### Public Constructors +### Public constructors -|Name|Description| -|----------|-----------------| -|[CComPtrBase::~CComPtrBase](#dtor)|The destructor.| +| Name | Description | +|--|--| +| [`CComPtrBase::~CComPtrBase`](#dtor) | The destructor. | -### Public Methods +### Public methods -|Name|Description| -|----------|-----------------| -|[CComPtrBase::Advise](#advise)|Call this method to create a connection between the `CComPtrBase`'s connection point and a client's sink.| -|[CComPtrBase::Attach](#attach)|Call this method to take ownership of an existing pointer.| -|[CComPtrBase::CoCreateInstance](#cocreateinstance)|Call this method to create an object of the class associated with a specified Class ID or Program ID.| -|[CComPtrBase::CopyTo](#copyto)|Call this method to copy the `CComPtrBase` pointer to another pointer variable.| -|[CComPtrBase::Detach](#detach)|Call this method to release ownership of a pointer.| -|[CComPtrBase::IsEqualObject](#isequalobject)|Call this method to check if the specified `IUnknown` points to the same object associated with the `CComPtrBase` object.| -|[CComPtrBase::QueryInterface](#queryinterface)|Call this method to return a pointer to a specified interface.| -|[CComPtrBase::Release](#release)|Call this method to release the interface.| -|[CComPtrBase::SetSite](#setsite)|Call this method to set the site of the `CComPtrBase` object to the `IUnknown` of the parent object.| +| Name | Description | +|--|--| +| [`CComPtrBase::Advise`](#advise) | Call this method to create a connection between the `CComPtrBase`'s connection point and a client's sink. | +| [`CComPtrBase::Attach`](#attach) | Call this method to take ownership of an existing pointer. | +| [`CComPtrBase::CoCreateInstance`](#cocreateinstance) | Call this method to create an object of the class associated with a specified Class ID or Program ID. | +| [`CComPtrBase::CopyTo`](#copyto) | Call this method to copy the `CComPtrBase` pointer to another pointer variable. | +| [`CComPtrBase::Detach`](#detach) | Call this method to release ownership of a pointer. | +| [`CComPtrBase::IsEqualObject`](#isequalobject) | Call this method to check if the specified `IUnknown` points to the same object associated with the `CComPtrBase` object. | +| [`CComPtrBase::QueryInterface`](#queryinterface) | Call this method to return a pointer to a specified interface. | +| [`CComPtrBase::Release`](#release) | Call this method to release the interface. | +| [`CComPtrBase::SetSite`](#setsite) | Call this method to set the site of the `CComPtrBase` object to the `IUnknown` of the parent object. | -### Public Operators +### Public operators -|Name|Description| -|----------|-----------------| -|[CComPtrBase::operator T*](#operator_t_star)|The cast operator.| -|[CComPtrBase::operator !](#operator_not)|The NOT operator.| -|[CComPtrBase::operator &](#operator_amp)|The & operator.| -|[CComPtrBase::operator *](#operator_star)|The \* operator.| -|[CComPtrBase::operator <](#ccomptrbase__operator lt)|The less-than operator.| -|[CComPtrBase::operator ==](#operator_eq_eq)|The equality operator.| -|[CComPtrBase::operator ->](#operator_ptr)|The pointer-to-members operator.| +| Name | Description | +|--|--| +| [`CComPtrBase::operator T*`](#operator_t_star) | The cast operator. | +| [`CComPtrBase::operator !`](#operator_not) | The NOT operator. | +| [`CComPtrBase::operator &`](#operator_amp) | The address-of `&` operator. | +| [`CComPtrBase::operator *`](#operator_star) | The pointer-to `*` operator. | +| [`CComPtrBase::operator <`](#operator_lt) | The less-than operator. | +| [`CComPtrBase::operator ==`](#operator_eq_eq) | The equality operator. | +| [`CComPtrBase::operator ->`](#operator_ptr) | The pointer-to-members operator. | -### Public Data Members +### Public data members -|Name|Description| -|----------|-----------------| -|[CComPtrBase::p](#p)|The pointer data member variable.| +| Name | Description | +|--|--| +| [`CComPtrBase::p`](#p) | The pointer data member variable. | ## Remarks -This class provides the basis for other smart pointers which use COM memory management routines, such as [CComQIPtr](../../atl/reference/ccomqiptr-class.md) and [CComPtr](../../atl/reference/ccomptr-class.md). The derived classes add their own constructors and operators, but rely on the methods provided by `CComPtrBase`. +This class provides the basis for other smart pointers that use COM memory management routines, such as [`CComQIPtr`](../../atl/reference/ccomqiptr-class.md) and [`CComPtr`](../../atl/reference/ccomptr-class.md). The derived classes add their own constructors and operators, but rely on the methods provided by `CComPtrBase`. ## Requirements **Header:** atlcomcli.h -## CComPtrBase::Advise +## `CComPtrBase::Advise` Call this method to create a connection between the `CComPtrBase`'s connection point and a client's sink. -``` +```cpp HRESULT Advise( IUnknown* pUnk, const IID& iid, @@ -83,24 +83,24 @@ HRESULT Advise( ### Parameters -*pUnk*
+*`pUnk`*\ A pointer to the client's `IUnknown`. -*iid*
-The GUID of the connection point. Typically, this is the same as the outgoing interface managed by the connection point. +*`iid`*\ +The GUID of the connection point. Typically, this GUID is the same as the outgoing interface managed by the connection point. -*pdw*
+*`pdw`*\ A pointer to the cookie that uniquely identifies the connection. -### Return Value +### Return value -Returns S_OK on success, or an error HRESULT on failure. +Returns `S_OK` on success, or an error `HRESULT` on failure. ### Remarks -See [AtlAdvise](connection-point-global-functions.md#atladvise) for more information. +For more information, see [`AtlAdvise`](connection-point-global-functions.md#atladvise). -## CComPtrBase::Attach +## `CComPtrBase::Attach` Call this method to take ownership of an existing pointer. @@ -110,18 +110,18 @@ void Attach(T* p2) throw(); ### Parameters -*p2*
+*`p2`*\ The `CComPtrBase` object will take ownership of this pointer. ### Remarks -`Attach` calls [CComPtrBase::Release](#release) on the existing [CComPtrBase::p](#p) member variable and then assigns *p2* to `CComPtrBase::p`. When a `CComPtrBase` object takes ownership of a pointer, it will automatically call `Release` on the pointer which will delete the pointer and any allocated data if the reference count on the object goes to 0. +`Attach` calls [`CComPtrBase::Release`](#release) on the existing [`CComPtrBase::p`](#p) member variable and then assigns *`p2`* to `CComPtrBase::p`. When a `CComPtrBase` object takes ownership of a pointer, it will automatically call `Release` on the pointer, which deletes the pointer and any allocated data if the reference count on the object goes to 0. -## CComPtrBase::~CComPtrBase +## `CComPtrBase::~CComPtrBase` The destructor. -``` +```cpp ~CComPtrBase() throw(); ``` @@ -129,11 +129,11 @@ The destructor. Releases the interface pointed to by `CComPtrBase`. -## CComPtrBase::CoCreateInstance +## `CComPtrBase::CoCreateInstance` Call this method to create an object of the class associated with a specified Class ID or Program ID. -``` +```cpp HRESULT CoCreateInstance( LPCOLESTR szProgID, LPUNKNOWN pUnkOuter = NULL, @@ -147,177 +147,177 @@ HRESULT CoCreateInstance( ### Parameters -*szProgID*
+*`szProgID`*\ Pointer to a ProgID, used to recover the CLSID. -*pUnkOuter*
-If NULL, indicates that the object is not being created as part of an aggregate. If non- NULL, is a pointer to the aggregate object's `IUnknown` interface (the controlling `IUnknown`). +*`pUnkOuter`*\ +If NULL, indicates that the object isn't being created as part of an aggregate. If non- NULL, is a pointer to the aggregate object's `IUnknown` interface (the controlling `IUnknown`). -*dwClsContext*
+*`dwClsContext`*\ Context in which the code that manages the newly created object will run. -*rclsid*
+*`rclsid`*\ CLSID associated with the data and code that will be used to create the object. -### Return Value +### Return value -Returns S_OK on success, or REGDB_E_CLASSNOTREG, CLASS_E_NOAGGREGATION, CO_E_CLASSSTRING or E_NOINTERFACE on failure. See [CoCreateClassInstance](/windows/win32/api/combaseapi/nf-combaseapi-cocreateinstance) and [CLSIDFromProgID](/windows/win32/api/combaseapi/nf-combaseapi-clsidfromprogid) for a description of these errors. +Returns `S_OK` on success, or `REGDB_E_CLASSNOTREG`, `CLASS_E_NOAGGREGATION`, `CO_E_CLASSSTRING`, or `E_NOINTERFACE` on failure. See [`CoCreateClassInstance`](/windows/win32/api/combaseapi/nf-combaseapi-cocreateinstance) and [`CLSIDFromProgID`](/windows/win32/api/combaseapi/nf-combaseapi-clsidfromprogid) for a description of these errors. ### Remarks -If the first form of the method is called, [CLSIDFromProgID](/windows/win32/api/combaseapi/nf-combaseapi-clsidfromprogid) is used to recover the CLSID. Both forms then call [CoCreateClassInstance](/windows/win32/api/combaseapi/nf-combaseapi-cocreateinstance). +If the first form of the method is called, [`CLSIDFromProgID`](/windows/win32/api/combaseapi/nf-combaseapi-clsidfromprogid) is used to recover the CLSID. Both forms then call [`CoCreateClassInstance`](/windows/win32/api/combaseapi/nf-combaseapi-cocreateinstance). -In debug builds, an assertion error will occur if [CComPtrBase::p](#p) is not equal to NULL. +In debug builds, an assertion error will occur if [`CComPtrBase::p`](#p) isn't equal to NULL. -## CComPtrBase::CopyTo +## `CComPtrBase::CopyTo` Call this method to copy the `CComPtrBase` pointer to another pointer variable. -``` +```cpp HRESULT CopyTo(T** ppT) throw(); ``` ### Parameters -*ppT*
-Address of the variable which will receive the `CComPtrBase` pointer. +*`ppT`*\ +Address of the variable to receive the `CComPtrBase` pointer. -### Return Value +### Return value -Returns S_OK on success, E_POINTER on failure. +Returns `S_OK` on success, `E_POINTER` on failure. ### Remarks -Copies the `CComPtrBase` pointer to *ppT*. The reference count on the [CComPtrBase::p](#p) member variable is incremented. +Copies the `CComPtrBase` pointer to *`ppT`*. The reference count on the [`CComPtrBase::p`](#p) member variable is incremented. -An error HRESULT will be returned if *ppT* is equal to NULL. In debug builds, an assertion error will occur if *ppT* is equal to NULL. +An error `HRESULT` will be returned if *`ppT`* is equal to NULL. In debug builds, an assertion error will occur if *`ppT`* is equal to NULL. -## CComPtrBase::Detach +## `CComPtrBase::Detach` Call this method to release ownership of a pointer. -``` +```cpp T* Detach() throw(); ``` -### Return Value +### Return value Returns a copy of the pointer. ### Remarks -Releases ownership of a pointer, sets the [CComPtrBase::p](#p) data member variable to NULL, and returns a copy of the pointer. +Releases ownership of a pointer, sets the [`CComPtrBase::p`](#p) data member variable to NULL, and returns a copy of the pointer. -## CComPtrBase::IsEqualObject +## `CComPtrBase::IsEqualObject` Call this method to check if the specified `IUnknown` points to the same object associated with the `CComPtrBase` object. -``` +```cpp bool IsEqualObject(IUnknown* pOther) throw(); ``` ### Parameters -*pOther*
+*`pOther`*\ The `IUnknown *` to compare. -### Return Value +### Return value Returns true if the objects are identical, false otherwise. -## CComPtrBase::operator ! +## `CComPtrBase::operator !` The NOT operator. -``` +```cpp bool operator!() const throw(); ``` -### Return Value +### Return value Returns true if the `CComHeapPtr` pointer is equal to NULL, false otherwise. -## CComPtrBase::operator & +## `CComPtrBase::operator &` -The & operator. +The address-of `&` operator. -``` +```cpp T** operator&() throw(); ``` -### Return Value +### Return value Returns the address of the object pointed to by the `CComPtrBase` object. -## CComPtrBase::operator \* +## `CComPtrBase::operator *` -The \* operator. +The pointer-to `*` operator. -``` +```cpp T& operator*() const throw(); ``` -### Return Value +### Return value -Returns the value of [CComPtrBase::p](#p); that is, a pointer to the object referenced by the `CComPtrBase` object. +Returns the value of [`CComPtrBase::p`](#p); that is, a pointer to the object referenced by the `CComPtrBase` object. -If debug builds, an assertion error will occur if [CComPtrBase::p](#p) is not equal to NULL. +If debug builds, an assertion error will occur if [`CComPtrBase::p`](#p) isn't equal to NULL. -## CComPtrBase::operator == +## `CComPtrBase::operator ==` The equality operator. -``` +```cpp bool operator== (T* pT) const throw(); ``` ### Parameters -*pT*
+*`pT`*\ A pointer to an object. -### Return Value +### Return value -Returns true if `CComPtrBase` and *pT* point to the same object, false otherwise. +Returns true if `CComPtrBase` and *`pT`* point to the same object, false otherwise. -## CComPtrBase::operator -> +## `CComPtrBase::operator ->` The pointer-to-member operator. -``` +```cpp _NoAddRefReleaseOnCComPtr* operator->() const throw(); ``` -### Return Value +### Return value -Returns the value of the [CComPtrBase::p](#p) data member variable. +Returns the value of the [`CComPtrBase::p`](#p) data member variable. ### Remarks Use this operator to call a method in a class pointed to by the `CComPtrBase` object. In debug builds, an assertion failure will occur if the `CComPtrBase` data member points to NULL. -## CComPtrBase::operator < +## `CComPtrBase::operator <` The less-than operator. -``` +```cpp bool operator<(T* pT) const throw(); ``` ### Parameters -*pT*
+*`pT`*\ A pointer to an object. -### Return Value +### Return value -Returns true if the pointer managed by current object is less than the pointer to which it is being compared. +Returns true if the pointer managed by current object is less than the pointer to which it's being compared. -## CComPtrBase::operator T\* +## `CComPtrBase::operator T*` The cast operator. -``` +```cpp operator T*() const throw(); ``` @@ -325,11 +325,11 @@ operator T*() const throw(); Returns a pointer to the object data type defined in the class template. -## CComPtrBase::p +## `CComPtrBase::p` The pointer data member variable. -``` +```cpp T* p; ``` @@ -337,34 +337,34 @@ T* p; This member variable holds the pointer information. -## CComPtrBase::QueryInterface +## `CComPtrBase::QueryInterface` Call this method to return a pointer to a specified interface. -``` +```cpp template HRESULT QueryInterface(Q ** pp) const throw(); ``` ### Parameters -*Q*
+*`Q`*\ The object type whose interface pointer is required. -*pp*
+*`pp`*\ Address of output variable that receives the requested interface pointer. -### Return Value +### Return value -Returns S_OK on success, or E_NOINTERFACE on failure. +Returns `S_OK` on success, or `E_NOINTERFACE` on failure. ### Remarks -This method calls [IUnknown::QueryInterface](/windows/win32/api/unknwn/nf-unknwn-iunknown-queryinterface(q)). +This method calls [`IUnknown::QueryInterface`](/windows/win32/api/unknwn/nf-unknwn-iunknown-queryinterface(q)). -In debug builds, an assertion error will occur if *pp* is not equal to NULL. +In debug builds, an assertion error will occur if *`pp`* isn't equal to NULL. -## CComPtrBase::Release +## `CComPtrBase::Release` Call this method to release the interface. @@ -374,29 +374,29 @@ void Release() throw(); ### Remarks -The interface is released, and [CComPtrBase::p](#p) is set to NULL. +The interface is released, and [`CComPtrBase::p`](#p) is set to NULL. -## CComPtrBase::SetSite +## `CComPtrBase::SetSite` Call this method to set the site of the `CComPtrBase` object to the `IUnknown` of the parent object. -``` +```cpp HRESULT SetSite(IUnknown* punkParent) throw(); ``` ### Parameters -*punkParent*
+*`punkParent`*\ A pointer to the `IUnknown` interface of the parent. -### Return Value +### Return value -Returns S_OK on success, or an error HRESULT on failure. +Returns `S_OK` on success, or an error `HRESULT` on failure. ### Remarks -This method calls [AtlSetChildSite](composite-control-global-functions.md#atlsetchildsite). +This method calls [`AtlSetChildSite`](composite-control-global-functions.md#atlsetchildsite). ## See also -[Class Overview](../../atl/atl-class-overview.md) +[Class overview](../../atl/atl-class-overview.md) diff --git a/docs/atl/reference/ccomsafearray-class.md b/docs/atl/reference/ccomsafearray-class.md index 79187fb155..d9c6729e91 100644 --- a/docs/atl/reference/ccomsafearray-class.md +++ b/docs/atl/reference/ccomsafearray-class.md @@ -4,22 +4,21 @@ title: "CComSafeArray Class" ms.date: "05/06/2019" f1_keywords: ["CComSafeArray", "ATLSAFE/ATL::CComSafeArray", "ATLSAFE/ATL::CComSafeArray::CComSafeArray", "ATLSAFE/ATL::CComSafeArray::Add", "ATLSAFE/ATL::CComSafeArray::Attach", "ATLSAFE/ATL::CComSafeArray::CopyFrom", "ATLSAFE/ATL::CComSafeArray::CopyTo", "ATLSAFE/ATL::CComSafeArray::Create", "ATLSAFE/ATL::CComSafeArray::Destroy", "ATLSAFE/ATL::CComSafeArray::Detach", "ATLSAFE/ATL::CComSafeArray::GetAt", "ATLSAFE/ATL::CComSafeArray::GetCount", "ATLSAFE/ATL::CComSafeArray::GetDimensions", "ATLSAFE/ATL::CComSafeArray::GetLowerBound", "ATLSAFE/ATL::CComSafeArray::GetSafeArrayPtr", "ATLSAFE/ATL::CComSafeArray::GetType", "ATLSAFE/ATL::CComSafeArray::GetUpperBound", "ATLSAFE/ATL::CComSafeArray::IsSizable", "ATLSAFE/ATL::CComSafeArray::MultiDimGetAt", "ATLSAFE/ATL::CComSafeArray::MultiDimSetAt", "ATLSAFE/ATL::CComSafeArray::Resize", "ATLSAFE/ATL::CComSafeArray::SetAt", "ATLSAFE/ATL::CComSafeArray::m_psa"] helpviewer_keywords: ["CComSafeArray class"] -ms.assetid: ee349aef-33db-4c85-bd08-5d86a3c9d53a --- -# CComSafeArray Class +# `CComSafeArray` Class This class is a wrapper for the `SAFEARRAY` structure. ## Syntax -``` +```cpp template ::type> class CComSafeArray ``` -#### Parameters +### Parameters -*T*
+*`T`*\ The type of data to be stored in the array. ## Members @@ -28,90 +27,90 @@ The type of data to be stored in the array. |Name|Description| |----------|-----------------| -|[CComSafeArray::CComSafeArray](#ccomsafearray)|The constructor.| -|[CComSafeArray::~CComSafeArray](#dtor)|The destructor.| +|[`CComSafeArray::CComSafeArray`](#ccomsafearray)|The constructor.| +|[`CComSafeArray::~CComSafeArray`](#dtor)|The destructor.| ### Public Methods |Name|Description| |----------|-----------------| -|[CComSafeArray::Add](#add)|Adds one or more elements, or a `SAFEARRAY` structure, to a `CComSafeArray`.| -|[CComSafeArray::Attach](#attach)|Attaches a `SAFEARRAY` structure to a `CComSafeArray` object.| -|[CComSafeArray::CopyFrom](#copyfrom)|Copies the contents of a `SAFEARRAY` structure into the `CComSafeArray` object.| -|[CComSafeArray::CopyTo](#copyto)|Creates a copy of the `CComSafeArray` object.| -|[CComSafeArray::Create](#create)|Creates a `CComSafeArray` object.| -|[CComSafeArray::Destroy](#destroy)|Destroys a `CComSafeArray` object.| -|[CComSafeArray::Detach](#detach)|Detaches a `SAFEARRAY` from a `CComSafeArray` object.| -|[CComSafeArray::GetAt](#getat)|Retrieves a single element from a single-dimensional array.| -|[CComSafeArray::GetCount](#getcount)|Returns the number of elements in the array.| -|[CComSafeArray::GetDimensions](#getdimensions)|Returns the number of dimensions in the array.| -|[CComSafeArray::GetLowerBound](#getlowerbound)|Returns the lower bound for a given dimension of the array.| -|[CComSafeArray::GetSafeArrayPtr](#getsafearrayptr)|Returns the address of the `m_psa` data member.| -|[CComSafeArray::GetType](#gettype)|Returns the type of data stored in the array.| -|[CComSafeArray::GetUpperBound](#getupperbound)|Returns the upper bound for any dimension of the array.| -|[CComSafeArray::IsSizable](#issizable)|Tests if a `CComSafeArray` object can be resized.| -|[CComSafeArray::MultiDimGetAt](#multidimgetat)|Retrieves a single element from a multidimensional array.| -|[CComSafeArray::MultiDimSetAt](#multidimsetat)|Sets the value of an element in a multidimensional array.| -|[CComSafeArray::Resize](#resize)|Resizes a `CComSafeArray` object.| -|[CComSafeArray::SetAt](#setat)|Sets the value of an element in a single-dimensional array.| +|[`CComSafeArray::Add`](#add)|Adds one or more elements, or a `SAFEARRAY` structure, to a `CComSafeArray`.| +|[`CComSafeArray::Attach`](#attach)|Attaches a `SAFEARRAY` structure to a `CComSafeArray` object.| +|[`CComSafeArray::CopyFrom`](#copyfrom)|Copies the contents of a `SAFEARRAY` structure into the `CComSafeArray` object.| +|[`CComSafeArray::CopyTo`](#copyto)|Creates a copy of the `CComSafeArray` object.| +|[`CComSafeArray::Create`](#create)|Creates a `CComSafeArray` object.| +|[`CComSafeArray::Destroy`](#destroy)|Destroys a `CComSafeArray` object.| +|[`CComSafeArray::Detach`](#detach)|Detaches a `SAFEARRAY` from a `CComSafeArray` object.| +|[`CComSafeArray::GetAt`](#getat)|Retrieves a single element from a single-dimensional array.| +|[`CComSafeArray::GetCount`](#getcount)|Returns the number of elements in the array.| +|[`CComSafeArray::GetDimensions`](#getdimensions)|Returns the number of dimensions in the array.| +|[`CComSafeArray::GetLowerBound`](#getlowerbound)|Returns the lower bound for a given dimension of the array.| +|[`CComSafeArray::GetSafeArrayPtr`](#getsafearrayptr)|Returns the address of the `m_psa` data member.| +|[`CComSafeArray::GetType`](#gettype)|Returns the type of data stored in the array.| +|[`CComSafeArray::GetUpperBound`](#getupperbound)|Returns the upper bound for any dimension of the array.| +|[`CComSafeArray::IsSizable`](#issizable)|Tests if a `CComSafeArray` object can be resized.| +|[`CComSafeArray::MultiDimGetAt`](#multidimgetat)|Retrieves a single element from a multidimensional array.| +|[`CComSafeArray::MultiDimSetAt`](#multidimsetat)|Sets the value of an element in a multidimensional array.| +|[`CComSafeArray::Resize`](#resize)|Resizes a `CComSafeArray` object.| +|[`CComSafeArray::SetAt`](#setat)|Sets the value of an element in a single-dimensional array.| ### Public Operators |Name|Description| |----------|-----------------| -|[CComSafeArray::operator LPSAFEARRAY](#operator_lpsafearray)|Casts a value to a `SAFEARRAY` pointer.| -|[CComSafeArray::operator\[\]](ccomsafearray-class.md#operator_at)|Retrieves an element from the array.| -|[CComSafeArray::operator =](#operator_eq)|Assignment operator.| +|[`CComSafeArray::operator LPSAFEARRAY`](#operator_lpsafearray)|Casts a value to a `SAFEARRAY` pointer.| +|[`CComSafeArray::operator[]`](ccomsafearray-class.md#operator_at)|Retrieves an element from the array.| +|[`CComSafeArray::operator =`](#operator_eq)|Assignment operator.| ### Public Data Members |Name|Description| |----------|-----------------| -|[CComSafeArray::m_psa](#m_psa)|This data member holds the address of the `SAFEARRAY` structure.| +|[`CComSafeArray::m_psa`](#m_psa)|This data member holds the address of the `SAFEARRAY` structure.| ## Remarks -`CComSafeArray` provides a wrapper for the [SAFEARRAY Data Type](/windows/win32/api/oaidl/ns-oaidl-safearray) class, making it a simple matter to create and manage single- and multidimensional arrays of almost any of the VARIANT-supported types. +`CComSafeArray` provides a wrapper for the [`SAFEARRAY` data type](/windows/win32/api/oaidl/ns-oaidl-safearray) class, making it a simple matter to create and manage single- and multidimensional arrays of almost any of the supported `VARIANT` types. `CComSafeArray` simplifies passing arrays between processes, and in addition provides extra security by checking array index values against upper and lower bounds. The lower bound of a `CComSafeArray` can start at any user-defined value; however, arrays that are accessed through C++ should use a lower bound of 0. Other languages such as Visual Basic may use other bounding values (for example, -10 to 10). -Use [CComSafeArray::Create](#create) to create a `CComSafeArray` object, and [CComSafeArray::Destroy](#destroy) to delete it. - -A `CComSafeArray` can contain the following subset of VARIANT data types: - -|VARTYPE|Description| -|-------------|-----------------| -|VT_I1|char| -|VT_I2|short| -|VT_I4|int| -|VT_I4|long| -|VT_I8|longlong| -|VT_UI1|byte| -|VT_UI2|ushort| -|VT_UI4|uint| -|VT_UI4|ulong| -|VT_UI8|ulonglong| -|VT_R4|float| -|VT_R8|double| -|VT_DECIMAL|decimal pointer| -|VT_VARIANT|variant pointer| -|VT_CY|Currency data type| +Use [`CComSafeArray::Create`](#create) to create a `CComSafeArray` object, and [`CComSafeArray::Destroy`](#destroy) to delete it. + +A `CComSafeArray` can contain the following subset of `VARIANT` data types: + +| `VARTYPE` | Description | +|--|--| +| `VT_I1` | `char` | +| `VT_I2` | `short` | +| `VT_I4` | `int` | +| `VT_I4` | `long` | +| `VT_I8` | `longlong` | +| `VT_UI1` | `byte` | +| `VT_UI2` | `ushort` | +| `VT_UI4` | `uint` | +| `VT_UI4` | `ulong` | +| `VT_UI8` | `ulonglong` | +| `VT_R4` | `float` | +| `VT_R8` | `double` | +| `VT_DECIMAL` | decimal pointer | +| `VT_VARIANT` | variant pointer | +| `VT_CY` | Currency data type | ## Requirements -**Header:** atlsafe.h +**Header:** `atlsafe.h` ## Example [!code-cpp[NVC_ATL_Utilities#75](../../atl/codesnippet/cpp/ccomsafearray-class_1.cpp)] -## CComSafeArray::Add +## `CComSafeArray::Add` Adds one or more elements, or a `SAFEARRAY` structure, to a `CComSafeArray`. -``` +```cpp HRESULT Add(const SAFEARRAY* psaSrc); HRESULT Add(ULONG ulCount, const T* pT, BOOL bCopy = TRUE); HRESULT Add(const T& t, BOOL bCopy = TRUE); @@ -119,57 +118,57 @@ HRESULT Add(const T& t, BOOL bCopy = TRUE); ### Parameters -*psaSrc*
+*`psaSrc`*\ A pointer to a `SAFEARRAY` object. -*ulCount*
+*`ulCount`*\ The number of objects to add to the array. -*pT*
+*`pT`*\ A pointer to one or more objects to be added to the array. -*t*
+*`t`*\ A reference to the object to be added to the array. -*bCopy*
-Indicates whether a copy of the data should be created. The default value is TRUE. +*`bCopy`*\ +Indicates whether a copy of the data should be created. The default value is `TRUE`. -### Return Value +### Return value -Returns S_OK on success, or an error HRESULT on failure. +Returns `S_OK` on success, or an error `HRESULT` on failure. ### Remarks -The new objects are appended to the end of the existing `SAFEARRAY` object. Adding an object to a multidimensional `SAFEARRAY` object is not supported. When adding an existing array of objects, both arrays must contain elements of the same type. +The new objects are appended to the end of the existing `SAFEARRAY` object. Adding an object to a multidimensional `SAFEARRAY` object isn't supported. When adding an existing array of objects, both arrays must contain elements of the same type. -The *bCopy* flag is taken into account when elements of type BSTR or VARIANT are added to an array. The default value of TRUE ensures that a new copy is made of the data when the element is added to the array. +The *`bCopy`* flag is taken into account when elements of type `BSTR` or `VARIANT` are added to an array. The default value of `TRUE` ensures that a new copy is made of the data when the element is added to the array. -## CComSafeArray::Attach +## `CComSafeArray::Attach` Attaches a `SAFEARRAY` structure to a `CComSafeArray` object. -``` +```cpp HRESULT Attach(const SAFEARRAY* psaSrc); ``` ### Parameters -*psaSrc*
+*`psaSrc`*\ A pointer to the `SAFEARRAY` structure. -### Return Value +### Return value -Returns S_OK on success, or an error HRESULT on failure. +Returns `S_OK` on success, or an error `HRESULT` on failure. ### Remarks Attaches a `SAFEARRAY` structure to a `CComSafeArray` object, making the existing `CComSafeArray` methods available. -## CComSafeArray::CComSafeArray +## `CComSafeArray::CComSafeArray` The constructor. -``` +```cpp CComSafeArray(); CComSafeArray(const SAFEARRAYBOUND& bound); CComSafeArray(ULONG ulCount, LONG lLBound = 0); @@ -181,36 +180,36 @@ CComSafeArray(const SAFEARRAY* psaSrc); ### Parameters -*bound*
+*`bound`*\ A `SAFEARRAYBOUND` structure. -*ulCount*
+*`ulCount`*\ The number of elements in the array. -*lLBound*
+*`lLBound`*\ The lower bound value; that is, the index of the first element in the array. -*pBound*
+*`pBound`*\ A pointer to a `SAFEARRAYBOUND` structure. -*uDims*
+*`uDims`*\ The count of dimensions in the array. -*saSrc*
-A reference to a `SAFEARRAY` structure or `CComSafeArray` object. In either case the constructor uses this reference to make a copy of the array, so the array is not referenced after construction. +*`saSrc`*\ +A reference to a `SAFEARRAY` structure or `CComSafeArray` object. In either case, the constructor uses this reference to make a copy of the array, so the array isn't referenced after construction. -*psaSrc*
-A pointer to a `SAFEARRAY` structure. The constructor uses this address to make a copy of the array, so the array is not referenced after construction. +*`psaSrc`*\ +A pointer to a `SAFEARRAY` structure. The constructor uses this address to make a copy of the array, so the array is never referenced after construction. ### Remarks Creates a `CComSafeArray` object. -## CComSafeArray::~CComSafeArray +## `CComSafeArray::~CComSafeArray` The destructor. -``` +```cpp ~CComSafeArray() throw() ``` @@ -218,104 +217,104 @@ The destructor. Frees all allocated resources. -## CComSafeArray::CopyFrom +## `CComSafeArray::CopyFrom` Copies the contents of a `SAFEARRAY` structure into the `CComSafeArray` object. -``` +```cpp HRESULT CopyFrom(LPSAFEARRAY* ppArray); ``` ### Parameters -*ppArray*
+*`ppArray`*\ Pointer to the `SAFEARRAY` to copy. -### Return Value +### Return value -Returns S_OK on success, or an error HRESULT on failure. +Returns `S_OK` on success, or an error `HRESULT` on failure. ### Remarks This method copies the contents of a `SAFEARRAY` into the current `CComSafeArray` object. The existing contents of the array are replaced. -## CComSafeArray::CopyTo +## `CComSafeArray::CopyTo` Creates a copy of the `CComSafeArray` object. -``` +```cpp HRESULT CopyTo(LPSAFEARRAY* ppArray); ``` ### Parameters -*ppArray*
+*`ppArray`*\ A pointer to a location in which to create the new `SAFEARRAY`. -### Return Value +### Return value -Returns S_OK on success, or an error HRESULT on failure. +Returns `S_OK` on success, or an error `HRESULT` on failure. ### Remarks This method copies the contents of a `CComSafeArray` object into a `SAFEARRAY` structure. -## CComSafeArray::Create +## `CComSafeArray::Create` Creates a `CComSafeArray`. -``` +```cpp HRESULT Create(const SAFEARRAYBOUND* pBound, UINT uDims = 1); HRESULT Create(ULONG ulCount = 0, LONG lLBound = 0); ``` ### Parameters -*pBound*
+*`pBound`*\ A pointer to a `SAFEARRAYBOUND` object. -*uDims*
+*`uDims`*\ The number of dimensions in the array. -*ulCount*
+*`ulCount`*\ The number of elements in the array. -*lLBound*
+*`lLBound`*\ The lower bound value; that is, the index of the first element in the array. -### Return Value +### Return value -Returns S_OK on success, or an error HRESULT on failure. +Returns `S_OK` on success, or an error `HRESULT` on failure. ### Remarks A `CComSafeArray` object can be created from an existing `SAFEARRAYBOUND` structure and the number of dimensions, or by specifying the number of elements in the array and the lower bound. If the array is to be accessed from C++, the lower bound should be 0. Other languages may allow other values for the lower bound (for example, Visual Basic supports arrays with elements with a range such as -10 to 10). -## CComSafeArray::Destroy +## `CComSafeArray::Destroy` Destroys a `CComSafeArray` object. -``` +```cpp HRESULT Destroy(); ``` -### Return Value +### Return value -Returns S_OK on success, or an error HRESULT on failure. +Returns `S_OK` on success, or an error `HRESULT` on failure. ### Remarks Destroys an existing `CComSafeArray` object and all of the data it contains. -## CComSafeArray::Detach +## `CComSafeArray::Detach` Detaches a `SAFEARRAY` from a `CComSafeArray` object. -``` +```cpp LPSAFEARRAY Detach(); ``` -### Return Value +### Return value Returns a pointer to a `SAFEARRAY` object. @@ -323,37 +322,37 @@ Returns a pointer to a `SAFEARRAY` object. This method detaches the `SAFEARRAY` object from the `CComSafeArray` object. -## CComSafeArray::GetAt +## `CComSafeArray::GetAt` Retrieves a single element from a single-dimensional array. -``` +```cpp T& GetAt(LONG lIndex) const; ``` ### Parameters -*lIndex*
+*`lIndex`*\ The index number of the value in the array to return. -### Return Value +### Return value Returns a reference to the required array element. -## CComSafeArray::GetCount +## `CComSafeArray::GetCount` Returns the number of elements in the array. -``` +```cpp ULONG GetCount(UINT uDim = 0) const; ``` ### Parameters -*uDim*
+*`uDim`*\ The array dimension. -### Return Value +### Return value Returns the number of elements in the array. @@ -361,279 +360,279 @@ Returns the number of elements in the array. When used with a multidimensional array, this method will return the number of elements in a specific dimension only. -## CComSafeArray::GetDimensions +## `CComSafeArray::GetDimensions` Returns the number of dimensions in the array. -``` +```cpp UINT GetDimensions() const; ``` -### Return Value +### Return value Returns the number of dimensions in the array. -## CComSafeArray::GetLowerBound +## `CComSafeArray::GetLowerBound` Returns the lower bound for a given dimension of the array. -``` +```cpp LONG GetLowerBound(UINT uDim = 0) const; ``` ### Parameters -*uDim*
+*`uDim`*\ The array dimension for which to get the lower bound. If omitted, the default is 0. -### Return Value +### Return value Returns the lower bound. ### Remarks -If the lower bound is 0, this indicates a C-like array whose first element is element number 0. In the event of an error, for example, an invalid dimension argument, this method calls `AtlThrow` with an HRESULT describing the error. +If the lower bound is 0, this indicates a C-like array whose first element is element number 0. In the event of an error, for example, an invalid dimension argument, this method calls `AtlThrow` with an `HRESULT` describing the error. -## CComSafeArray::GetSafeArrayPtr +## `CComSafeArray::GetSafeArrayPtr` Returns the address of the `m_psa` data member. -``` +```cpp LPSAFEARRAY* GetSafeArrayPtr() throw(); ``` -### Return Value +### Return value -Returns a pointer to the [CComSafeArray::m_psa](#m_psa) data member. +Returns a pointer to the [`CComSafeArray::m_psa`](#m_psa) data member. -## CComSafeArray::GetType +## `CComSafeArray::GetType` Returns the type of data stored in the array. -``` +```cpp VARTYPE GetType() const; ``` -### Return Value +### Return value Returns the type of data stored in the array, which could be any of the following types: -|VARTYPE|Description| -|-------------|-----------------| -|VT_I1|char| -|VT_I2|short| -|VT_I4|int| -|VT_I4|long| -|VT_I8|longlong| -|VT_UI1|byte| -|VT_UI2|ushort| -|VT_UI4|uint| -|VT_UI4|ulong| -|VT_UI8|ulonglong| -|VT_R4|float| -|VT_R8|double| -|VT_DECIMAL|decimal pointer| -|VT_VARIANT|variant pointer| -|VT_CY|Currency data type| - -## CComSafeArray::GetUpperBound +| `VARTYPE` | Description | +|--|--| +| `VT_I1` | `char` | +| `VT_I2` | `short` | +| `VT_I4` | `int` | +| `VT_I4` | `long` | +| `VT_I8` | `longlong` | +| `VT_UI1` | `byte` | +| `VT_UI2` | `ushort` | +| `VT_UI4` | `uint` | +| `VT_UI4` | `ulong` | +| `VT_UI8` | `ulonglong` | +| `VT_R4` | `float` | +| `VT_R8` | `double` | +| `VT_DECIMAL` | decimal pointer | +| `VT_VARIANT` | variant pointer | +| `VT_CY` | Currency data type | + +## `CComSafeArray::GetUpperBound` Returns the upper bound for any dimension of the array. -``` +```cpp LONG GetUpperBound(UINT uDim = 0) const; ``` ### Parameters -*uDim*
+*`uDim`*\ The array dimension for which to get the upper bound. If omitted, the default is 0. -### Return Value +### Return value Returns the upper bound. This value is inclusive, the maximum valid index for this dimension. ### Remarks -In the event of an error, for example, an invalid dimension argument, this method calls `AtlThrow` with an HRESULT describing the error. +In the event of an error, for example, an invalid dimension argument, this method calls `AtlThrow` with an `HRESULT` describing the error. -## CComSafeArray::IsSizable +## `CComSafeArray::IsSizable` Tests if a `CComSafeArray` object can be resized. -``` +```cpp bool IsSizable() const; ``` -### Return Value +### Return value -Returns TRUE if the `CComSafeArray` can be resized, FALSE if it cannot. +Returns `TRUE` if the `CComSafeArray` can be resized, `FALSE` if it cannot. -## CComSafeArray::m_psa +## `CComSafeArray::m_psa` Holds the address of the `SAFEARRAY` structure accessed. -``` +```cpp LPSAFEARRAY m_psa; ``` -## CComSafeArray::MultiDimGetAt +## `CComSafeArray::MultiDimGetAt` Retrieves a single element from a multidimensional array. -``` +```cpp HRESULT MultiDimGetAt(const LONG* alIndex, T& t); ``` ### Parameters -*alIndex*
+*`alIndex`*\ Pointer to a vector of indexes for each dimension in the array. The leftmost (most significant) dimension is `alIndex[0]`. -*t*
+*`t`*\ A reference to the data returned. -### Return Value +### Return value -Returns S_OK on success, or an error HRESULT on failure. +Returns `S_OK` on success, or an error `HRESULT` on failure. -## CComSafeArray::MultiDimSetAt +## `CComSafeArray::MultiDimSetAt` Sets the value of an element in a multidimensional array. -``` +```cpp HRESULT MultiDimSetAt(const LONG* alIndex, const T& t); ``` ### Parameters -*alIndex*
-Pointer to a vector of indexes for each dimension in the array. The rightmost (least significant) dimension is `alIndex`[0]. +*`alIndex`*\ +Pointer to a vector of indexes for each dimension in the array. The rightmost (least significant) dimension is `alIndex[0]`. -*T*
+*`T`*\ Specifies the value of the new element. -### Return Value +### Return value -Returns S_OK on success, or an error HRESULT on failure. +Returns `S_OK` on success, or an error `HRESULT` on failure. ### Remarks -This is a multidimensional version of [CComSafeArray::SetAt](#setat). +This is a multidimensional version of [`CComSafeArray::SetAt`](#setat). -## CComSafeArray::operator \[\] +## `CComSafeArray::operator []` Retrieves an element from the array. -``` +```cpp T& operator[](long lindex) const; -T& operator[]int nindex) const; +T& operator[](int nindex) const; ``` ### Parameters -*lIndex, nIndex*
+*`lIndex`*, *`nIndex`*\ The index number of the required element in the array. -### Return Value +### Return value Returns the appropriate array element. ### Remarks -Performs a similar function to [CComSafeArray::GetAt](#getat), however this operator only works with single-dimensional arrays. +Performs a similar function to [`CComSafeArray::GetAt`](#getat), however this operator only works with single-dimensional arrays. -## CComSafeArray::operator = +## `CComSafeArray::operator =` Assignment operator. -``` +```cpp ATL::CComSafeArray& operator=(const ATL::CComSafeArray& saSrc); ATL::CComSafeArray& operator=(const SAFEARRAY* psaSrc); ``` ### Parameters -*saSrc*
+*`saSrc`*\ A reference to a `CComSafeArray` object. -*psaSrc*
+*`psaSrc`*\ A pointer to a `SAFEARRAY` object. -### Return Value +### Return value Returns the type of data stored in the array. -## CComSafeArray::operator LPSAFEARRAY +## `CComSafeArray::operator LPSAFEARRAY` Casts a value to a `SAFEARRAY` pointer. -``` +```cpp operator LPSAFEARRAY() const; ``` -### Return Value +### Return value Casts a value to a `SAFEARRAY` pointer. -## CComSafeArray::Resize +## `CComSafeArray::Resize` Resizes a `CComSafeArray` object. -``` +```cpp HRESULT Resize(const SAFEARRAYBOUND* pBound); HRESULT Resize(ULONG ulCount, LONG lLBound = 0); ``` ### Parameters -*pBound*
+*`pBound`*\ A pointer to a `SAFEARRAYBOUND` structure that contains information on the number of elements and the lower bound of an array. -*ulCount*
+*`ulCount`*\ The requested number of objects in the resized array. -*lLBound*
+*`lLBound`*\ The lower bound. -### Return Value +### Return value -Returns S_OK on success, or an error HRESULT on failure. +Returns `S_OK` on success, or an error `HRESULT` on failure. ### Remarks -This method only resizes the rightmost dimension. It will not resize arrays that return `IsResizable` as FALSE. +This method only resizes the rightmost dimension. It will not resize arrays that return `IsResizable` as `FALSE`. -## CComSafeArray::SetAt +## `CComSafeArray::SetAt` Sets the value of an element in a single-dimensional array. -``` +```cpp HRESULT SetAt(LONG lIndex, const T& t, BOOL bCopy = TRUE); ``` ### Parameters -*lIndex*
+*`lIndex`*\ The index number of the array element to set. -*t*
+*`t`*\ The new value of the specified element. -*bCopy*
-Indicates whether a copy of the data should be created. The default value is TRUE. +*`bCopy`*\ +Indicates whether a copy of the data should be created. The default value is `TRUE`. -### Return Value +### Return value -Returns S_OK on success, or an error HRESULT on failure. +Returns `S_OK` on success, or an error `HRESULT` on failure. ### Remarks -The *bCopy* flag is taken into account when elements of type BSTR or VARIANT are added to an array. The default value of TRUE ensures that a new copy is made of the data when the element is added to the array. +The *`bCopy`* flag is taken into account when elements of type `BSTR` or `VARIANT` are added to an array. The default value of `TRUE` ensures that a new copy is made of the data when the element is added to the array. ## See also -[SAFEARRAY Data Type](/windows/win32/api/oaidl/ns-oaidl-safearray)
-[CComSafeArray::Create](#create)
-[CComSafeArray::Destroy](#destroy)
+[`SAFEARRAY` Data Type](/windows/win32/api/oaidl/ns-oaidl-safearray)\ +[`CComSafeArray::Create`](#create)\ +[`CComSafeArray::Destroy`](#destroy)\ [Class Overview](../../atl/atl-class-overview.md) diff --git a/docs/atl/reference/ccomvariant-class.md b/docs/atl/reference/ccomvariant-class.md index 3141851979..e3b806e113 100644 --- a/docs/atl/reference/ccomvariant-class.md +++ b/docs/atl/reference/ccomvariant-class.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: CComVariant Class" -title: "CComVariant Class" +description: "Learn more about: CComVariant class" +title: "CComVariant class" ms.date: "11/04/2016" f1_keywords: ["CComVariant", "ATLCOMCLI/ATL::CComVariant", "ATLCOMCLI/ATL::CComVariant::CComVariant", "ATLCOMCLI/ATL::CComVariant::Attach", "ATLCOMCLI/ATL::CComVariant::ChangeType", "ATLCOMCLI/ATL::CComVariant::Clear", "ATLCOMCLI/ATL::CComVariant::Copy", "ATLCOMCLI/ATL::CComVariant::CopyTo", "ATLCOMCLI/ATL::CComVariant::Detach", "ATLCOMCLI/ATL::CComVariant::GetSize", "ATLCOMCLI/ATL::CComVariant::ReadFromStream", "ATLCOMCLI/ATL::CComVariant::SetByRef", "ATLCOMCLI/ATL::CComVariant::WriteToStream"] helpviewer_keywords: ["VARIANT macro", "CComVariant class", "VARIANT macro, ATL"] -ms.assetid: 4d31149c-d005-44b5-a509-10f84afa2b61 --- -# CComVariant Class +# `CComVariant` class -This class wraps the VARIANT type, providing a member indicating the type of data stored. +This class wraps the `VARIANT` type, providing a member indicating the type of data stored. ## Syntax @@ -18,80 +17,79 @@ class CComVariant : public tagVARIANT ## Members -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[CComVariant::CComVariant](#ccomvariant)|The constructor.| -|[CComVariant::~CComVariant](#dtor)|The destructor.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|[CComVariant::Attach](#attach)|Attaches a VARIANT to the `CComVariant` object.| -|[CComVariant::ChangeType](#changetype)|Converts the `CComVariant` object to a new type.| -|[CComVariant::Clear](#clear)|Clears the `CComVariant` object.| -|[CComVariant::Copy](#copy)|Copies a VARIANT to the `CComVariant` object.| -|[CComVariant::CopyTo](#copyto)|Copies the contents of the `CComVariant` object.| -|[CComVariant::Detach](#detach)|Detaches the underlying VARIANT from the `CComVariant` object.| -|[CComVariant::GetSize](#getsize)|Returns the size in number of bytes of the contents of the `CComVariant` object.| -|[CComVariant::ReadFromStream](#readfromstream)|Loads a VARIANT from a stream.| -|[CComVariant::SetByRef](#setbyref)|Initializes the `CComVariant` object and sets the `vt` member to VT_BYREF.| -|[CComVariant::WriteToStream](#writetostream)|Saves the underlying VARIANT to a stream.| - -### Public Operators - -|Operator|Description| -|-|-| -|[CComVariant::operator <](#operator_lt)|Indicates whether the `CComVariant` object is less than the specified VARIANT.| -|[CComVariant::operator >](#operator_gt)|Indicates whether the `CComVariant` object is greater than the specified VARIANT.| -|[operator !=](#operator_neq)|Indicates whether the `CComVariant` object does not equal the specified VARIANT.| -|[operator =](#operator_eq)|Assigns a value to the `CComVariant` object.| -|[operator ==](#operator_eq_eq)|Indicates whether the `CComVariant` object equals the specified VARIANT.| +### Public constructors + +| Name | Description | +|--|--| +| [`CComVariant::CComVariant`](#ccomvariant) | The constructor. | +| [`CComVariant::~CComVariant`](#dtor) | The destructor. | + +### Public methods + +| Name | Description | +|--|--| +| [`CComVariant::Attach`](#attach) | Attaches a `VARIANT` to the `CComVariant` object. | +| [`CComVariant::ChangeType`](#changetype) | Converts the `CComVariant` object to a new type. | +| [`CComVariant::Clear`](#clear) | Clears the `CComVariant` object. | +| [`CComVariant::Copy`](#copy) | Copies a `VARIANT` to the `CComVariant` object. | +| [`CComVariant::CopyTo`](#copyto) | Copies the contents of the `CComVariant` object. | +| [`CComVariant::Detach`](#detach) | Detaches the underlying `VARIANT` from the `CComVariant` object. | +| [`CComVariant::GetSize`](#getsize) | Returns the size in number of bytes of the contents of the `CComVariant` object. | +| [`CComVariant::ReadFromStream`](#readfromstream) | Loads a `VARIANT` from a stream. | +| [`CComVariant::SetByRef`](#setbyref) | Initializes the `CComVariant` object and sets the `vt` member to `VT_BYREF`. | +| [`CComVariant::WriteToStream`](#writetostream) | Saves the underlying `VARIANT` to a stream. | + +### Public operators + +| Operator | Description | +|--|--| +| [`CComVariant::operator <`](#operator_lt) | Indicates whether the `CComVariant` object is less than the specified `VARIANT`. | +| [`CComVariant::operator >`](#operator_gt) | Indicates whether the `CComVariant` object is greater than the specified `VARIANT`. | +| [`CComVariant::operator !=`](#operator_neq) | Indicates whether the `CComVariant` object doesn't equal the specified `VARIANT`. | +| [`CComVariant::operator =`](#operator_eq) | Assigns a value to the `CComVariant` object. | +| [`CComVariant::operator ==`](#operator_eq_eq) | Indicates whether the `CComVariant` object equals the specified `VARIANT`. | ## Remarks -`CComVariant` wraps the VARIANT and VARIANTARG type, which consists of a union and a member indicating the type of the data stored in the union. VARIANTs are typically used in Automation. +`CComVariant` wraps the `VARIANT` and `VARIANTARG` type, which consists of a union and a member indicating the type of the data stored in the union. `VARIANT`s are typically used in Automation. -`CComVariant` derives from the VARIANT type so it can be used wherever a VARIANT can be used. You can, for example, use the V_VT macro to extract the type of a `CComVariant` or you can access the `vt` member directly just as you can with a VARIANT. +`CComVariant` derives from the `VARIANT` type so it can be used wherever a `VARIANT` can be used. You can, for example, use the `V_VT` macro to extract the type of a `CComVariant` or you can access the `vt` member directly just as you can with a `VARIANT`. -## Inheritance Hierarchy +## Inheritance hierarchy -`tagVARIANT` - -`CComVariant` +[`tagVARIANT`](/windows/win32/api/oaidl/ns-oaidl-variant)\ + └ [`CComVariant`](ccomvariant-class.md) ## Requirements -**Header:** atlcomcli.h +**Header:** `atlcomcli.h` -## CComVariant::Attach +## `CComVariant::Attach` -Safely clears the current contents of the `CComVariant` object, copies the contents of *pSrc* into this object, then sets the variant type of *pSrc* to VT_EMPTY. +Safely clears the current contents of the `CComVariant` object, copies the contents of *`pSrc`* into this object, then sets the variant type of *`pSrc`* to `VT_EMPTY`. -``` +```cpp HRESULT Attach(VARIANT* pSrc); ``` ### Parameters -*pSrc*
-[in] Points to the [VARIANT](/windows/win32/api/oaidl/ns-oaidl-variant) to be attached to the object. +*`pSrc`*\ +[in] Points to the [`VARIANT`](/windows/win32/api/oaidl/ns-oaidl-variant) to be attached to the object. -### Return Value +### Return value -A standard HRESULT value. +A standard `HRESULT` value. ### Remarks -Ownership of the data held by *pSrc* is transferred to the `CComVariant` object. +Ownership of the data held by *`pSrc`* is transferred to the `CComVariant` object. -## CComVariant::CComVariant +## `CComVariant::CComVariant` Each constructor handles the safe initialization of the `CComVariant` object by calling the `VariantInit` Win32 function or by setting the object's value and type according to the parameters passed. -``` +```cpp CComVariant() throw(); CComVariant(const CComVariant& varSrc); CComVariant(const VARIANT& varSrc); @@ -119,181 +117,181 @@ CComVariant(const CComBSTR& bstrSrc); ### Parameters -*varSrc*
-[in] The `CComVariant` or VARIANT used to initialize the `CComVariant` object. The contents of the source variant are copied to the destination without conversion. +*`varSrc`*\ +[in] The `CComVariant` or `VARIANT` used to initialize the `CComVariant` object. The contents of the source variant are copied to the destination without conversion. -*lpszSrc*
-[in] The character string used to initialize the `CComVariant` object. You can pass a zero-terminated wide (Unicode) character string to the LPCOLESTR version of the constructor or an ANSI string to the LPCSTR version. In either case the string is converted to a Unicode BSTR allocated using `SysAllocString`. The type of the `CComVariant` object will be VT_BSTR. +*`lpszSrc`*\ +[in] The character string used to initialize the `CComVariant` object. You can pass a zero-terminated wide (Unicode) character string to the `LPCOLESTR` version of the constructor or an ANSI string to the `LPCSTR` version. In either case, the string is converted to a Unicode `BSTR` allocated using `SysAllocString`. The type of the `CComVariant` object is `VT_BSTR`. -*bSrc*
-[in] The **`bool`** used to initialize the `CComVariant` object. The **`bool`** argument is converted to a VARIANT_BOOL before being stored. The type of the `CComVariant` object will be VT_BOOL. +*`bSrc`*\ +[in] The **`bool`** used to initialize the `CComVariant` object. The **`bool`** argument is converted to a `VARIANT_BOOL` before being stored. The type of the `CComVariant` object is `VT_BOOL`. -*nSrc*
-[in] The **`int`**, **BYTE**, **`short`**, **`long`**, LONGLONG, ULONGLONG, **`unsigned short`**, **`unsigned long`**, or **`unsigned int`** used to initialize the `CComVariant` object. The type of the `CComVariant` object will be VT_I4, VT_UI1, VT_I2, VT_I4, VT_I8, VT_UI8, VT_UI2, VT_UI4, or VT_UI4, respectively. +*`nSrc`*\ +[in] The **`int`**, `BYTE`, **`short`**, **`long`**, `LONGLONG`, `ULONGLONG`, **`unsigned short`**, **`unsigned long`**, or **`unsigned int`** used to initialize the `CComVariant` object. The type of the `CComVariant` object is `VT_I4`, `VT_UI1`, `VT_I2`, `VT_I4`, `VT_I8`, `VT_UI8`, `VT_UI2`, `VT_UI4`, or `VT_UI4`, respectively. -*vtSrc*
-[in] The type of the variant. When the first parameter is **`int`**, valid types are VT_I4 and VT_INT. When the first parameter is **`long`**, valid types are VT_I4 and VT_ERROR. When the first parameter is **`double`**, valid types are VT_R8 and VT_DATE. When the first parameter is **`unsigned int`**, valid types are VT_UI4 and VT_UINT. +*`vtSrc`*\ +[in] The type of the variant. When the first parameter is **`int`**, valid types are `VT_I4` and `VT_INT`. When the first parameter is **`long`**, valid types are `VT_I4` and `VT_ERROR`. When the first parameter is **`double`**, valid types are `VT_R8` and `VT_DATE`. When the first parameter is **`unsigned int`**, valid types are `VT_UI4` and `VT_UINT`. -*fltSrc*
-[in] The **`float`** used to initialize the `CComVariant` object. The type of the `CComVariant` object will be VT_R4. +*`fltSrc`*\ +[in] The **`float`** used to initialize the `CComVariant` object. The type of the `CComVariant` object is `VT_R4`. -*dblSrc*
-[in] The **`double`** used to initialize the `CComVariant` object. The type of the `CComVariant` object will be VT_R8. +*`dblSrc`*\ +[in] The **`double`** used to initialize the `CComVariant` object. The type of the `CComVariant` object is `VT_R8`. -*cySrc*
-[in] The `CY` used to initialize the `CComVariant` object. The type of the `CComVariant` object will be VT_CY. +*`cySrc`*\ +[in] The `CY` used to initialize the `CComVariant` object. The type of the `CComVariant` object is `VT_CY`. -*pSrc*
-[in] The `IDispatch` or `IUnknown` pointer used to initialize the `CComVariant` object. `AddRef` will be called on the interface pointer. The type of the `CComVariant` object will be VT_DISPATCH or VT_UNKNOWN, respectively. +*`pSrc`*\ +[in] The `IDispatch` or `IUnknown` pointer used to initialize the `CComVariant` object. `AddRef` is called on the interface pointer. The type of the `CComVariant` object is `VT_DISPATCH` or `VT_UNKNOWN`, respectively. -Or, the SAFERRAY pointer used to initialize the `CComVariant` object. A copy of the SAFEARRAY is stored in the `CComVariant` object. The type of the `CComVariant` object will be a combination of the original type of the SAFEARRAY and VT_ARRAY. +Or, the `SAFERRAY` pointer used to initialize the `CComVariant` object. A copy of the `SAFEARRAY` is stored in the `CComVariant` object. The type of the `CComVariant` object is a combination of the original type of the `SAFEARRAY` and `VT_ARRAY`. -*cSrc*
-[in] The **`char`** used to initialize the `CComVariant` object. The type of the `CComVariant` object will be VT_I1. +*`cSrc`*\ +[in] The **`char`** used to initialize the `CComVariant` object. The type of the `CComVariant` object is `VT_I1`. -*bstrSrc*
-[in] The BSTR used to initialize the `CComVariant` object. The type of the `CComVariant` object will be VT_BSTR. +*`bstrSrc`*\ +[in] The `BSTR` used to initialize the `CComVariant` object. The type of the `CComVariant` object is `VT_BSTR`. ### Remarks -The destructor manages cleanup by calling [CComVariant::Clear](#clear). +The destructor manages cleanup by calling [`CComVariant::Clear`](#clear). -## CComVariant::~CComVariant +## `CComVariant::~CComVariant` The destructor. -``` +```cpp ~CComVariant() throw(); ``` ### Remarks -This method manages cleanup by calling [CComVariant::Clear](#clear). +This method manages cleanup by calling [`CComVariant::Clear`](#clear). -## CComVariant::ChangeType +## `CComVariant::ChangeType` Converts the `CComVariant` object to a new type. -``` +```cpp HRESULT ChangeType(VARTYPE vtNew, const VARIANT* pSrc = NULL); ``` ### Parameters -*vtNew*
+*`vtNew`*\ [in] The new type for the `CComVariant` object. -*pSrc*
-[in] A pointer to the VARIANT whose value will be converted to the new type. The default value is NULL, meaning the `CComVariant` object will be converted in place. +*`pSrc`*\ +[in] A pointer to the `VARIANT` whose value is converted to the new type. The default value is `NULL`, meaning the `CComVariant` object is converted in place. -### Return Value +### Return value -A standard HRESULT value. +A standard `HRESULT` value. ### Remarks -If you pass a value for *pSrc*, `ChangeType` will use this VARIANT as the source for the conversion. Otherwise, the `CComVariant` object will be the source. +If you pass a value for *`pSrc`*, `ChangeType` will use this `VARIANT` as the source for the conversion. Otherwise, the `CComVariant` object is the source. -## CComVariant::Clear +## `CComVariant::Clear` Clears the `CComVariant` object by calling the `VariantClear` Win32 function. -``` +```cpp HRESULT Clear(); ``` -### Return Value +### Return value -A standard HRESULT value. +A standard `HRESULT` value. ### Remarks The destructor automatically calls `Clear`. -## CComVariant::Copy +## `CComVariant::Copy` -Frees the `CComVariant` object and then assigns it a copy of the specified VARIANT. +Frees the `CComVariant` object and then assigns it a copy of the specified `VARIANT`. -``` +```cpp HRESULT Copy(const VARIANT* pSrc); ``` ### Parameters -*pSrc*
-[in] A pointer to the [VARIANT](/windows/win32/api/oaidl/ns-oaidl-variant) to be copied. +*`pSrc`*\ +[in] A pointer to the [`VARIANT`](/windows/win32/api/oaidl/ns-oaidl-variant) to be copied. -### Return Value +### Return value -A standard HRESULT value. +A standard `HRESULT` value. -## CComVariant::CopyTo +## `CComVariant::CopyTo` Copies the contents of the `CComVariant` object. -``` +```cpp HRESULT CopyTo(BSTR* pstrDest); ``` ### Parameters -*pstrDest*
-Points to a BSTR that will receive a copy of the contents of the `CComVariant` object. +*`pstrDest`*\ +Points to a `BSTR` that will receive a copy of the contents of the `CComVariant` object. -### Return Value +### Return value -A standard HRESULT value. +A standard `HRESULT` value. ### Remarks -The `CComVariant` object must be of type VT_BSTR. +The `CComVariant` object must be of type `VT_BSTR`. -## CComVariant::Detach +## `CComVariant::Detach` -Detaches the underlying VARIANT from the `CComVariant` object and sets the object's type to VT_EMPTY. +Detaches the underlying `VARIANT` from the `CComVariant` object and sets the object's type to `VT_EMPTY`. -``` +```cpp HRESULT Detach(VARIANT* pDest); ``` ### Parameters -*pDest*
-[out] Returns the underlying VARIANT value of the object. +*`pDest`*\ +[out] Returns the underlying `VARIANT` value of the object. -### Return Value +### Return value -A standard HRESULT value. +A standard `HRESULT` value. ### Remarks -Note that the contents of the VARIANT referenced by *pDest* will automatically be cleared before being assigned the value and type of the calling `CComVariant` object. +The contents of the `VARIANT` referenced by *`pDest`* are automatically cleared before being assigned the value and type of the calling `CComVariant` object. -## CComVariant::GetSize +## `CComVariant::GetSize` -For simple-fixed size VARIANTs, this method returns the **`sizeof`** value for the underlying data type plus **sizeof(VARTYPE)**. +For simple-fixed size `VARIANT`s, this method returns the **`sizeof`** value for the underlying data type plus `sizeof(VARTYPE)`. -``` +```cpp ULONG GetSize() const; ``` -### Return Value +### Return value The size in bytes of the current contents of the `CComVariant` object. ### Remarks -If the VARIANT contains an interface pointer, `GetSize` queries for `IPersistStream` or `IPersistStreamInit`. If successful, the return value is the low-order 32 bits of the value returned by `GetSizeMax` plus `sizeof(CLSID)` and `sizeof(VARTYPE)`. If the interface pointer is NULL, `GetSize` returns `sizeof(CLSID)` plus `sizeof(VARTYPE)`. If the total size is larger than ULONG_MAX, `GetSize` returns `sizeof(VARTYPE)` which indicates an error. +If the `VARIANT` contains an interface pointer, `GetSize` queries for `IPersistStream` or `IPersistStreamInit`. If successful, the return value is the low-order 32 bits of the value returned by `GetSizeMax` plus `sizeof(CLSID)` and `sizeof(VARTYPE)`. If the interface pointer is `NULL`, `GetSize` returns `sizeof(CLSID)` plus `sizeof(VARTYPE)`. If the total size is larger than `ULONG_MAX`, `GetSize` returns `sizeof(VARTYPE)`, which indicates an error. -In all other cases, a temporary VARIANT of type VT_BSTR is coerced from the current VARIANT. The length of this BSTR is calculated as the size of the length of the string plus the length of the string itself plus the size of the null character plus **sizeof(VARTYPE)**. If the VARIANT cannot be coerced to a VARIANT of type VT_BSTR, `GetSize` returns **sizeof(VARTYPE)**. +In all other cases, a temporary `VARIANT` of type `VT_BSTR` is coerced from the current `VARIANT`. The length of this `BSTR` is calculated as the size of the length of the string plus the length of the string itself plus the size of the `NULL` character plus `sizeof(VARTYPE)`. If the `VARIANT` can't be coerced to a `VARIANT` of type `VT_BSTR`, `GetSize` returns `sizeof(VARTYPE)`. -The size returned by this method matches the number of bytes used by [CComVariant::WriteToStream](#writetostream) under successful conditions. +The size returned by this method matches the number of bytes used by [`CComVariant::WriteToStream`](#writetostream) under successful conditions. -## CComVariant::operator = +## `CComVariant::operator =` Assigns a value and corresponding type to the `CComVariant` object. -``` +```cpp CComVariant& operator=(const CComVariant& varSrc); CComVariant& operator=(const VARIANT& varSrc); CComVariant& operator=(const CComBSTR& bstrSrc); @@ -320,151 +318,151 @@ CComVariant& operator=(char cSrc) throw(); ### Parameters -*varSrc*
-[in] The `CComVariant` or [VARIANT](/windows/win32/api/oaidl/ns-oaidl-variant) to be assigned to the `CComVariant` object. The contents of the source variant are copied to the destination without conversion. +*`varSrc`*\ +[in] The `CComVariant` or [`VARIANT`](/windows/win32/api/oaidl/ns-oaidl-variant) to be assigned to the `CComVariant` object. The contents of the source variant are copied to the destination without conversion. -*bstrSrc*
-[in] The BSTR to be assigned to the `CComVariant` object. The type of the `CComVariant` object will be VT_BSTR. +*`bstrSrc`*\ +[in] The `BSTR` to be assigned to the `CComVariant` object. The type of the `CComVariant` object is `VT_BSTR`. -*lpszSrc*
-[in] The character string to be assigned to the `CComVariant` object. You can pass a zero-terminated wide (Unicode) character string to the LPCOLESTR version of the operator or an ANSI string to the LPCSTR version. In either case, the string is converted to a Unicode BSTR allocated using `SysAllocString`. The type of the `CComVariant` object will be VT_BSTR. +*`lpszSrc`*\ +[in] The character string to be assigned to the `CComVariant` object. You can pass a zero-terminated wide (Unicode) character string to the `LPCOLESTR` version of the operator or an ANSI string to the `LPCSTR` version. In either case, the string is converted to a Unicode `BSTR` allocated using `SysAllocString`. The type of the `CComVariant` object is `VT_BSTR`. -*bSrc*
-[in] The **`bool`** to be assigned to the `CComVariant` object. The **`bool`** argument is converted to a VARIANT_BOOL before being stored. The type of the `CComVariant` object will be VT_BOOL. +*`bSrc`*\ +[in] The **`bool`** to be assigned to the `CComVariant` object. The **`bool`** argument is converted to a `VARIANT_BOOL` before being stored. The type of the `CComVariant` object is `VT_BOOL`. -*nSrc*
-[in] The **`int`**, BYTE, **`short`**, **`long`**, LONGLONG, ULONGLONG, **`unsigned short`**, **`unsigned long`**, or **`unsigned int`** to be assigned to the `CComVariant` object. The type of the `CComVariant` object will be VT_I4, VT_UI1, VT_I2, VT_I4, VT_I8, VT_UI8, VT_UI2, VT_UI4, or VT_UI4, respectively. +*`nSrc`*\ +[in] The **`int`**, `BYTE`, **`short`**, **`long`**, `LONGLONG`, `ULONGLONG`, **`unsigned short`**, **`unsigned long`**, or **`unsigned int`** to be assigned to the `CComVariant` object. The type of the `CComVariant` object is `VT_I4`, `VT_UI1`, `VT_I2`, `VT_I4`, `VT_I8`, `VT_UI8`, `VT_UI2`, `VT_UI4`, or `VT_UI4`, respectively. -*fltSrc*
-[in] The **`float`** to be assigned to the `CComVariant` object. The type of the `CComVariant` object will be VT_R4. +*`fltSrc`*\ +[in] The **`float`** to be assigned to the `CComVariant` object. The type of the `CComVariant` object is `VT_R4`. -*dblSrc*
-[in] The **`double`** to be assigned to the `CComVariant` object. The type of the `CComVariant` object will be VT_R8. +*`dblSrc`*\ +[in] The **`double`** to be assigned to the `CComVariant` object. The type of the `CComVariant` object is `VT_R8`. -*cySrc*
-[in] The `CY` to be assigned to the `CComVariant` object. The type of the `CComVariant` object will be VT_CY. +*`cySrc`*\ +[in] The `CY` to be assigned to the `CComVariant` object. The type of the `CComVariant` object is `VT_CY`. -*pSrc*
-[in] The `IDispatch` or `IUnknown` pointer to be assigned to the `CComVariant` object. `AddRef` will be called on the interface pointer. The type of the `CComVariant` object will be VT_DISPATCH or VT_UNKNOWN, respectively. +*`pSrc`*\ +[in] The `IDispatch` or `IUnknown` pointer to be assigned to the `CComVariant` object. `AddRef` is called on the interface pointer. The type of the `CComVariant` object is `VT_DISPATCH` or `VT_UNKNOWN`, respectively. -Or, a SAFEARRAY pointer to be assigned to the `CComVariant` object. A copy of the SAFEARRAY is stored in the `CComVariant` object. The type of the `CComVariant` object will be a combination of the original type of the SAFEARRAY and VT_ARRAY. +Or, a `SAFEARRAY` pointer to be assigned to the `CComVariant` object. A copy of the `SAFEARRAY` is stored in the `CComVariant` object. The type of the `CComVariant` object is a combination of the original type of the `SAFEARRAY` and `VT_ARRAY`. -*cSrc*
-[in] The char to be assigned to the `CComVariant` object. The type of the `CComVariant` object will be VT_I1. +*`cSrc`*\ +[in] The char to be assigned to the `CComVariant` object. The type of the `CComVariant` object is `VT_I1`. -## CComVariant::operator == +## `CComVariant::operator ==` -Indicates whether the `CComVariant` object equals the specified VARIANT. +Indicates whether the `CComVariant` object equals the specified `VARIANT`. -``` +```cpp bool operator==(const VARIANT& varSrc) const throw(); ``` ### Remarks -Returns TRUE if the value and type of *varSrc* are equal to the value and type, respectively, of the `CComVariant` object. Otherwise, FALSE. The operator uses the user's default locale to perform the comparison. +Returns `TRUE` if the value and type of *`varSrc`* are equal to the value and type, respectively, of the `CComVariant` object. Otherwise, `FALSE`. The operator uses the user's default locale to perform the comparison. The operator compares only the value of the variant types. It compares strings, integers, and floating points, but not arrays or records. -## CComVariant::operator != +## `CComVariant::operator !=` -Indicates whether the `CComVariant` object does not equal the specified VARIANT. +Indicates whether the `CComVariant` object doesn't equal the specified `VARIANT`. -``` +```cpp bool operator!=(const VARIANT& varSrc) const throw(); ``` ### Remarks -Returns TRUE if either the value or type of *varSrc* is not equal to the value or type, respectively, of the `CComVariant` object. Otherwise, FALSE. The operator uses the user's default locale to perform the comparison. +Returns `TRUE` if either the value or type of *`varSrc`* isn't equal to the value or type, respectively, of the `CComVariant` object. Otherwise, `FALSE`. The operator uses the user's default locale to perform the comparison. The operator compares only the value of the variant types. It compares strings, integers, and floating points, but not arrays or records. -## CComVariant::operator < +## `CComVariant::operator <` -Indicates whether the `CComVariant` object is less than the specified VARIANT. +Indicates whether the `CComVariant` object is less than the specified `VARIANT`. -``` +```cpp bool operator<(const VARIANT& varSrc) const throw(); ``` ### Remarks -Returns TRUE if the value of the `CComVariant` object is less than the value of *varSrc*. Otherwise, FALSE. The operator uses the user's default locale to perform the comparison. +Returns `TRUE` if the value of the `CComVariant` object is less than the value of *`varSrc`*. Otherwise, `FALSE`. The operator uses the user's default locale to perform the comparison. -## CComVariant::operator > +## `CComVariant::operator >` -Indicates whether the `CComVariant` object is greater than the specified VARIANT. +Indicates whether the `CComVariant` object is greater than the specified `VARIANT`. -``` +```cpp bool operator>(const VARIANT& varSrc) const throw(); ``` ### Remarks -Returns TRUE if the value of the `CComVariant` object is greater than the value of *varSrc*. Otherwise, FALSE. The operator uses the user's default locale to perform the comparison. +Returns `TRUE` if the value of the `CComVariant` object is greater than the value of *`varSrc`*. Otherwise, `FALSE`. The operator uses the user's default locale to perform the comparison. -## CComVariant::ReadFromStream +## `CComVariant::ReadFromStream` -Sets the underlying VARIANT to the VARIANT contained in the specified stream. +Sets the underlying `VARIANT` to the `VARIANT` contained in the specified stream. -``` +```cpp HRESULT ReadFromStream(IStream* pStream); ``` ### Parameters -*pStream*
-[in] A pointer to the [IStream](/windows/win32/api/objidl/nn-objidl-istream) interface on the stream containing the data. +*`pStream`*\ +[in] A pointer to the [`IStream`](/windows/win32/api/objidl/nn-objidl-istream) interface on the stream containing the data. -### Return Value +### Return value -A standard HRESULT value. +A standard `HRESULT` value. ### Remarks -`ReadToStream` requires a previous call to [WriteToStream](#writetostream). +`ReadToStream` requires a previous call to [`WriteToStream`](#writetostream). -## CComVariant::SetByRef +## `CComVariant::SetByRef` -Initializes the `CComVariant` object and sets the `vt` member to VT_BYREF. +Initializes the `CComVariant` object and sets the `vt` member to `VT_BYREF`. -``` +```cpp template < typename T > void SetByRef(T* pT) throw(); ``` ### Parameters -*T*
-The type of VARIANT, for example, BSTR, **`int`**, or **`char`**. +*`T`*\ +The type of `VARIANT`, for example, `BSTR`, **`int`**, or **`char`**. -*pT*
+*`pT`*\ The pointer used to initialize the `CComVariant` object. ### Remarks -`SetByRef` is a function template that initializes the `CComVariant` object to the pointer *pT* and sets the `vt` member to VT_BYREF. For example: +`SetByRef` is a function template that initializes the `CComVariant` object to the pointer *`pT`* and sets the `vt` member to `VT_BYREF`. For example: [!code-cpp[NVC_ATL_Utilities#76](../../atl/codesnippet/cpp/ccomvariant-class_1.cpp)] -## CComVariant::WriteToStream +## `CComVariant::WriteToStream` -Saves the underlying VARIANT to a stream. +Saves the underlying `VARIANT` to a stream. -``` +```cpp HRESULT WriteToStream(IStream* pStream); ``` ### Parameters -*pStream*
-[in] A pointer to the [IStream](/windows/win32/api/objidl/nn-objidl-istream) interface on a stream. +*`pStream`*\ +[in] A pointer to the [`IStream`](/windows/win32/api/objidl/nn-objidl-istream) interface on a stream. -### Return Value +### Return value -A standard HRESULT value. +A standard `HRESULT` value. ## See also -[Class Overview](../../atl/atl-class-overview.md) +[Class overview](../../atl/atl-class-overview.md) diff --git a/docs/atl/reference/ccontainedwindowt-class.md b/docs/atl/reference/ccontainedwindowt-class.md index 2324c43241..92e55f8f39 100644 --- a/docs/atl/reference/ccontainedwindowt-class.md +++ b/docs/atl/reference/ccontainedwindowt-class.md @@ -75,9 +75,9 @@ A traits class that defines styles for your window. The default is `CControlWinT When you use the **Add control based on** option in the ATL Project Wizard, the wizard will automatically add a `CContainedWindowT` data member to the class implementing the control. The following example shows how the contained window is declared: [!code-cpp[NVC_ATL_Windowing#38](../../atl/codesnippet/cpp/ccontainedwindowt-class_1.h)] - +  [!code-cpp[NVC_ATL_Windowing#39](../../atl/codesnippet/cpp/ccontainedwindowt-class_2.h)] - +  [!code-cpp[NVC_ATL_Windowing#40](../../atl/codesnippet/cpp/ccontainedwindowt-class_3.h)] |For more information about|See| @@ -197,7 +197,7 @@ HWND Create( [in] Specifies the name of the window. The default value is NULL. *dwStyle*
-[in] The style of the window. The default value is WS_CHILD | WS_VISIBLE. For a list of possible values, see [CreateWindow](/windows/win32/api/winuser/nf-winuser-createwindoww) in the Windows SDK. +[in] The style of the window. The default value is `WS_CHILD | WS_VISIBLE`. For a list of possible values, see [CreateWindow](/windows/win32/api/winuser/nf-winuser-createwindoww) in the Windows SDK. *dwExStyle*
[in] The extended window style. The default value is 0, meaning no extended style. For a list of possible values, see [CreateWindowEx](/windows/win32/api/winuser/nf-winuser-createwindowexw) in the Windows SDK. diff --git a/docs/atl/reference/cheapptrbase-class.md b/docs/atl/reference/cheapptrbase-class.md index 5a99acaea5..8ba15f0fb6 100644 --- a/docs/atl/reference/cheapptrbase-class.md +++ b/docs/atl/reference/cheapptrbase-class.md @@ -1,12 +1,12 @@ --- -description: "Learn more about: CHeapPtrBase Class" -title: "CHeapPtrBase Class" +description: "Learn more about: CHeapPtrBase class" +title: "CHeapPtrBase class" ms.date: "11/04/2016" f1_keywords: ["CHeapPtrBase", "ATLCORE/ATL::CHeapPtrBase", "ATLCORE/ATL::CHeapPtrBase::AllocateBytes", "ATLCORE/ATL::CHeapPtrBase::Attach", "ATLCORE/ATL::CHeapPtrBase::Detach", "ATLCORE/ATL::CHeapPtrBase::Free", "ATLCORE/ATL::CHeapPtrBase::ReallocateBytes", "ATLCORE/ATL::CHeapPtrBase::m_pData"] helpviewer_keywords: ["CHeapPtrBase class"] ms.assetid: 501ac1b2-fb34-4c72-b7e6-a4f1fc8fda21 --- -# CHeapPtrBase Class +# `CHeapPtrBase` class This class forms the basis for several smart heap pointer classes. @@ -15,81 +15,81 @@ This class forms the basis for several smart heap pointer classes. ## Syntax -``` +```cpp template class CHeapPtrBase ``` #### Parameters -*T*
+*`T`*\ The object type to be stored on the heap. -*Allocator*
+*`Allocator`*\ The memory allocation class to use. By default CRT routines are used to allocate and free memory. ## Members -### Public Constructors +### Public constructors -|Name|Description| -|----------|-----------------| -|[CHeapPtrBase::~CHeapPtrBase](#dtor)|The destructor.| +| Name | Description | +|--|--| +| [`CHeapPtrBase::~CHeapPtrBase`](#dtor) | The destructor. | -### Public Methods +### Public methods -|Name|Description| -|----------|-----------------| -|[CHeapPtrBase::AllocateBytes](#allocatebytes)|Call this method to allocate memory.| -|[CHeapPtrBase::Attach](#attach)|Call this method to take ownership of an existing pointer.| -|[CHeapPtrBase::Detach](#detach)|Call this method to release ownership of a pointer.| -|[CHeapPtrBase::Free](#free)|Call this method to delete an object pointed to by a `CHeapPtrBase`.| -|[CHeapPtrBase::ReallocateBytes](#reallocatebytes)|Call this method to reallocate memory.| +| Name | Description | +|--|--| +| [`CHeapPtrBase::AllocateBytes`](#allocatebytes) | Call this method to allocate memory. | +| [`CHeapPtrBase::Attach`](#attach) | Call this method to take ownership of an existing pointer. | +| [`CHeapPtrBase::Detach`](#detach) | Call this method to release ownership of a pointer. | +| [`CHeapPtrBase::Free`](#free) | Call this method to delete an object pointed to by a `CHeapPtrBase`. | +| [`CHeapPtrBase::ReallocateBytes`](#reallocatebytes) | Call this method to reallocate memory. | -### Public Operators +### Public operators -|Name|Description| -|----------|-----------------| -|[CHeapPtrBase::operator T*](#operator_t_star)|The cast operator.| -|[CHeapPtrBase::operator &](#operator_amp)|The & operator.| -|[CHeapPtrBase::operator ->](#operator_ptr)|The pointer-to-member operator.| +| Name | Description | +|--|--| +| [`CHeapPtrBase::operator T*`](#operator_t_star) | The cast operator. | +| [`CHeapPtrBase::operator &`](#operator_amp) | The & operator. | +| [`CHeapPtrBase::operator ->`](#operator_ptr) | The pointer-to-member operator. | -### Public Data Members +### Public data members -|Name|Description| -|----------|-----------------| -|[CHeapPtrBase::m_pData](#m_pdata)|The pointer data member variable.| +| Name | Description | +|--|--| +| [`CHeapPtrBase::m_pData`](#m_pdata) | The pointer data member variable. | ## Remarks -This class forms the basis for several smart heap pointer classes. The derived classes, for example, [CHeapPtr](../../atl/reference/cheapptr-class.md) and [CComHeapPtr](../../atl/reference/ccomheapptr-class.md), add their own constructors and operators. See these classes for implementation examples. +This class forms the basis for several smart heap pointer classes. The derived classes, for example, [`CHeapPtr`](../../atl/reference/cheapptr-class.md) and [`CComHeapPtr`](../../atl/reference/ccomheapptr-class.md), add their own constructors and operators. See these classes for implementation examples. ## Requirements **Header:** atlcore.h -## CHeapPtrBase::AllocateBytes +## `CHeapPtrBase::AllocateBytes` Call this method to allocate memory. -``` +```cpp bool AllocateBytes(size_t nBytes) throw(); ``` ### Parameters -*nBytes*
+*`nBytes`*\ The number of bytes of memory to allocate. -### Return Value +### Return value Returns true if the memory is successfully allocated, false otherwise. ### Remarks -In debug builds, an assertion failure will occur if the [CHeapPtrBase::m_pData](#m_pdata) member variable currently points to an existing value; that is, it is not equal to NULL. +In debug builds, an assertion failure will occur if the [`CHeapPtrBase::m_pData`](#m_pdata) member variable currently points to an existing value; that is, it's not equal to NULL. -## CHeapPtrBase::Attach +## `CHeapPtrBase::Attach` Call this method to take ownership of an existing pointer. @@ -99,20 +99,20 @@ void Attach(T* pData) throw(); ### Parameters -*pData*
+*`pData`*\ The `CHeapPtrBase` object will take ownership of this pointer. ### Remarks When a `CHeapPtrBase` object takes ownership of a pointer, it will automatically delete the pointer and any allocated data when it goes out of scope. -In debug builds, an assertion failure will occur if the [CHeapPtrBase::m_pData](#m_pdata) member variable currently points to an existing value; that is, it is not equal to NULL. +In debug builds, an assertion failure will occur if the [`CHeapPtrBase::m_pData`](#m_pdata) member variable currently points to an existing value; that is, it's not equal to NULL. -## CHeapPtrBase::~CHeapPtrBase +## `CHeapPtrBase::~CHeapPtrBase` The destructor. -``` +```cpp ~CHeapPtrBase() throw(); ``` @@ -120,23 +120,23 @@ The destructor. Frees all allocated resources. -## CHeapPtrBase::Detach +## `CHeapPtrBase::Detach` Call this method to release ownership of a pointer. -``` +```cpp T* Detach() throw(); ``` -### Return Value +### Return value Returns a copy of the pointer. ### Remarks -Releases ownership of a pointer, sets the [CHeapPtrBase::m_pData](#m_pdata) member variable to NULL, and returns a copy of the pointer. +Releases ownership of a pointer, sets the [`CHeapPtrBase::m_pData`](#m_pdata) member variable to NULL, and returns a copy of the pointer. -## CHeapPtrBase::Free +## `CHeapPtrBase::Free` Call this method to delete an object pointed to by a `CHeapPtrBase`. @@ -146,13 +146,13 @@ void Free() throw(); ### Remarks -The object pointed to by the `CHeapPtrBase` is freed, and the [CHeapPtrBase::m_pData](#m_pdata) member variable is set to NULL. +The object pointed to by the `CHeapPtrBase` is freed, and the [`CHeapPtrBase::m_pData`](#m_pdata) member variable is set to NULL. -## CHeapPtrBase::m_pData +## `CHeapPtrBase::m_pData` The pointer data member variable. -``` +```cpp T* m_pData; ``` @@ -160,65 +160,65 @@ T* m_pData; This member variable holds the pointer information. -## CHeapPtrBase::operator & +## `CHeapPtrBase::operator &` The & operator. -``` +```cpp T** operator&() throw(); ``` -### Return Value +### Return value Returns the address of the object pointed to by the `CHeapPtrBase` object. -## CHeapPtrBase::operator -> +## `CHeapPtrBase::operator ->` The pointer-to-member operator. -``` +```cpp T* operator->() const throw(); ``` -### Return Value +### Return value -Returns the value of the [CHeapPtrBase::m_pData](#m_pdata) member variable. +Returns the value of the [`CHeapPtrBase::m_pData`](#m_pdata) member variable. ### Remarks Use this operator to call a method in a class pointed to by the `CHeapPtrBase` object. In debug builds, an assertion failure will occur if the `CHeapPtrBase` points to NULL. -## CHeapPtrBase::operator T* +## `CHeapPtrBase::operator T*` The cast operator. -``` +```cpp operator T*() const throw(); ``` ### Remarks -Returns [CHeapPtrBase::m_pData](#m_pdata). +Returns [`CHeapPtrBase::m_pData`](#m_pdata). -## CHeapPtrBase::ReallocateBytes +## `CHeapPtrBase::ReallocateBytes` Call this method to reallocate memory. -``` +```cpp bool ReallocateBytes(size_t nBytes) throw(); ``` ### Parameters -*nBytes*
+*`nBytes`*\ The new amount of memory to allocate, in bytes. -### Return Value +### Return value Returns true if the memory is successfully allocated, false otherwise. ## See also -[CHeapPtr Class](../../atl/reference/cheapptr-class.md)
-[CComHeapPtr Class](../../atl/reference/ccomheapptr-class.md)
-[Class Overview](../../atl/atl-class-overview.md) +[`CHeapPtr` class](../../atl/reference/cheapptr-class.md)\ +[`CComHeapPtr` class](../../atl/reference/ccomheapptr-class.md)\ +[Class overview](../../atl/atl-class-overview.md) diff --git a/docs/atl/reference/com-map-macros.md b/docs/atl/reference/com-map-macros.md index cb755491ea..6734604721 100644 --- a/docs/atl/reference/com-map-macros.md +++ b/docs/atl/reference/com-map-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: COM Map Macros" title: "COM Map Macros" ms.date: "11/04/2016" -f1_keywords: ["atlcom/ATL::BEGIN_COM_MAP", "atlcom/ATL::END_COM_MAP"] +f1_keywords: ["atlcom/ATL::BEGIN_COM_MAP", "atlcom/ATL::END_COM_MAP", "ATLCOM/BEGIN_COM_MAP", "ATLCOM/END_COM_MAP"] helpviewer_keywords: ["COM interfaces, COM map macros"] ms.assetid: 0f33656d-321f-4996-90cc-9a7f21ab73c3 --- diff --git a/docs/atl/reference/com-plus-1-0-atl-com-plus-1-0-component-wizard.md b/docs/atl/reference/com-plus-1-0-atl-com-plus-1-0-component-wizard.md index be124f9048..0a12524551 100644 --- a/docs/atl/reference/com-plus-1-0-atl-com-plus-1-0-component-wizard.md +++ b/docs/atl/reference/com-plus-1-0-atl-com-plus-1-0-component-wizard.md @@ -7,7 +7,7 @@ ms.assetid: 2fbe259c-6be1-4d0e-9cfe-721c75c97cb1 --- # COM+ 1.0, ATL COM+ 1.0 Component Wizard -::: moniker range="msvc-160" +::: moniker range=">=msvc-160" This wizard is not available in Visual Studio 2019 and later. diff --git a/docs/atl/reference/compiler-options-macros.md b/docs/atl/reference/compiler-options-macros.md index 6cf7d8a0d3..4c80bb5d9b 100644 --- a/docs/atl/reference/compiler-options-macros.md +++ b/docs/atl/reference/compiler-options-macros.md @@ -1,10 +1,9 @@ --- description: "Learn more about: Compiler Options Macros" title: "Compiler Options Macros" -ms.date: "08/19/2019" -f1_keywords: ["_ATL_ALL_WARNINGS", "_ATL_APARTMENT_THREADED", "_ATL_CSTRING_EXPLICIT_CONSTRUCTORS ", "_ATL_ENABLE_PTM_WARNING", "_ATL_FREE_THREADED", "_ATL_MULTI_THREADED", "_ATL_NO_AUTOMATIC_NAMESPACE", "_ATL_NO_COM_SUPPORT", "ATL_NO_VTABLE", "ATL_NOINLINE", "_ATL_SINGLE_THREADED"] +ms.date: 02/01/2023 +f1_keywords: ["_ATL_ALL_WARNINGS", "_ATL_APARTMENT_THREADED", "_ATL_CSTRING_EXPLICIT_CONSTRUCTORS ", "_ATL_ENABLE_PTM_WARNING", "_ATL_FREE_THREADED", "_ATL_MODULES", "_ATL_MULTI_THREADED", "_ATL_NO_AUTOMATIC_NAMESPACE", "_ATL_NO_COM_SUPPORT", "ATL_NO_VTABLE", "ATL_NOINLINE", "_ATL_SINGLE_THREADED"] helpviewer_keywords: ["compiler options, macros"] -ms.assetid: a869adc6-b3de-4299-b040-9ae20b45f82c --- # Compiler Options Macros @@ -12,23 +11,24 @@ These macros control specific compiler features. |Macro|Description| |-|-| -|[_ATL_ALL_WARNINGS](#_atl_all_warnings)|A symbol that enables errors in projects converted from previous versions of ATL.| -|[_ATL_APARTMENT_THREADED](#_atl_apartment_threaded)|Define if one or more of your objects use apartment threading.| -|[_ATL_CSTRING_EXPLICIT_CONSTRUCTORS](#_atl_cstring_explicit_constructors)|Makes certain `CString` constructors explicit, preventing any unintentional conversions.| -|[_ATL_ENABLE_PTM_WARNING](#_atl_enable_ptm_warning)|Define this macro in order to use C++ standard compliant syntax, which generates the C4867 compiler error when a non-standard syntax is used to initialize a pointer to a member function.| -|[_ATL_FREE_THREADED](#_atl_free_threaded)|Define if one or more of your objects use free or neutral threading.| -|[_ATL_MULTI_THREADED](#_atl_multi_threaded)|A symbol that indicates the project will have objects that are marked as Both, Free or Neutral. The macro [_ATL_FREE_THREADED](#_atl_free_threaded) should be used instead.| -|[_ATL_NO_AUTOMATIC_NAMESPACE](#_atl_no_automatic_namespace)|A symbol that prevents the default use of namespace as ATL.| -|[_ATL_NO_COM_SUPPORT](#_atl_no_com_support)|A symbol that prevents COM-related code from being compiled with your project.| -|[ATL_NO_VTABLE](#atl_no_vtable)|A symbol that prevents the vtable pointer from being initialized in the class's constructor and destructor.| -|[ATL_NOINLINE](#atl_noinline)|A symbol that indicates a function should not be inlined.| -|[_ATL_SINGLE_THREADED](#_atl_single_threaded)|Define if all of your objects use the single threading model.| - -## _ATL_ALL_WARNINGS +|[`_ATL_ALL_WARNINGS`](#_atl_all_warnings)|A symbol that enables errors in projects converted from previous versions of ATL.| +|[`_ATL_APARTMENT_THREADED`](#_atl_apartment_threaded)|Define if one or more of your objects use apartment threading.| +|[`_ATL_CSTRING_EXPLICIT_CONSTRUCTORS`](#_atl_cstring_explicit_constructors)|Makes certain `CString` constructors explicit, preventing any unintentional conversions.| +|[`_ATL_ENABLE_PTM_WARNING`](#_atl_enable_ptm_warning)|Define this macro to require C++ standard syntax. It generates the C4867 compiler error when nonstandard syntax is used to initialize a pointer to a member function.| +|[`_ATL_FREE_THREADED`](#_atl_free_threaded)|Define if one or more of your objects use free or neutral threading.| +|[`_ATL_MODULES`](#_ATL_MODULES)|Allows you to compile ATL projects with [permissive-](../../build/reference/permissive-standards-conformance.md) and use ATL with [C++ modules](../../cpp/modules-cpp.md).| +|[`_ATL_MULTI_THREADED`](#_atl_multi_threaded)|A symbol that indicates the project has objects marked as Both, Free or Neutral. The macro [`_ATL_FREE_THREADED`](#_atl_free_threaded) should be used instead.| +|[`_ATL_NO_AUTOMATIC_NAMESPACE`](#_atl_no_automatic_namespace)|A symbol that prevents the default use of namespace as ATL.| +|[`_ATL_NO_COM_SUPPORT`](#_atl_no_com_support)|A symbol that prevents COM-related code from being compiled with your project.| +|[`ATL_NO_VTABLE`](#atl_no_vtable)|A symbol that prevents the vtable pointer from being initialized in the class's constructor and destructor.| +|[`ATL_NOINLINE`](#atl_noinline)|A symbol that indicates a function shouldn't be inlined.| +|[`_ATL_SINGLE_THREADED`](#_atl_single_threaded)|Define if all of your objects use the single threading model.| + +## `_ATL_ALL_WARNINGS` A symbol that enables errors in projects converted from previous versions of ATL. -``` +```cpp #define _ATL_ALL_WARNINGS ``` @@ -52,27 +52,27 @@ Before Visual C++ .NET 2002, ATL disabled many warnings and left them disabled s In projects converted from previous versions, these warnings are still disabled by the libraries headers. -By adding the following line to the *pch.h* (*stdafx.h* in Visual Studio 2017 and earlier) file before including libraries headers, this behavior can be changed. +To change this behavior, add the following line to the *`pch.h`* (*`stdafx.h`* in Visual Studio 2017 and earlier) file before including libraries headers. [!code-cpp[NVC_ATL_Utilities#97](../../atl/codesnippet/cpp/compiler-options-macros_1.h)] -If this `#define` is added, the ATL headers are careful to preserve the state of these warnings so that they are not disabled globally (or if the user explicitly disables individual warnings, not to enable them). +If this `#define` is added, the ATL headers are careful to preserve the state of these warnings so that they're not disabled globally (or if the user explicitly disables individual warnings, not to enable them). New projects have this `#define` set in *pch.h* (*stdafx.h* in Visual Studio 2017 and earlier) by default. -## _ATL_APARTMENT_THREADED +## `_ATL_APARTMENT_THREADED` Define if one or more of your objects use apartment threading. -``` +```cpp _ATL_APARTMENT_THREADED ``` ### Remarks -Specifies apartment threading. See [Specifying the Project's Threading Model](../../atl/specifying-the-threading-model-for-a-project-atl.md) for other threading options, and [Options, ATL Simple Object Wizard](../../atl/reference/options-atl-simple-object-wizard.md) for a description of the threading models available for an ATL object. +Specifies apartment threading. For other options, and a description of the threading models available for an ATL object, see [Specifying the Project's Threading Model](../../atl/specifying-the-threading-model-for-a-project-atl.md) and [Options, ATL Simple Object Wizard](../../atl/reference/options-atl-simple-object-wizard.md). -## _ATL_CSTRING_EXPLICIT_CONSTRUCTORS +## `_ATL_CSTRING_EXPLICIT_CONSTRUCTORS` Makes certain `CString` constructors explicit, preventing any unintentional conversions. @@ -82,25 +82,25 @@ _ATL_CSTRING_EXPLICIT_CONSTRUCTORS ### Remarks -When this constructor is defined, all CString constructors that take a single parameter are compiled with the explicit keyword, which prevents implicit conversions of input arguments. This means, for example, that when _UNICODE is defined, if you attempt to use a char* string as a CString constructor argument, a compiler error will result. Use this macro in situations where you need to prevent implicit conversions between narrow and wide string types. +When this constructor is defined, all `CString` constructors that take a single parameter are compiled with the explicit keyword, which prevents implicit conversions of input arguments. This means, for example, that when `_UNICODE` is defined, if you attempt to use a `char*` string as a `CString` constructor argument, a compiler error results. Use this macro in situations where you need to prevent implicit conversions between narrow and wide string types. -By using the _T macro on all constructor string arguments, you can define _ATL_CSTRING_EXPLICIT_CONSTRUCTORS and avoid compile errors regardless of whether _UNICODE is defined. +By using the `_T` macro on all constructor string arguments, you can define `_ATL_CSTRING_EXPLICIT_CONSTRUCTORS` and avoid compile errors regardless of whether `_UNICODE` is defined. -## _ATL_ENABLE_PTM_WARNING +## `_ATL_ENABLE_PTM_WARNING` -Define this macro in order to force the use of ANSI C++ standard-compliant syntax for pointer to member functions. Using this macro will cause the C4867 compiler error to be generated when non-standard syntax is used to initialize a pointer to a member function. +Define this macro in order to force the use of ANSI C++ standard-conforming syntax for pointer to member functions. Using this macro causes the C4867 compiler error to be generated when nonstandard syntax is used to initialize a pointer to a member function. -``` +```cpp #define _ATL_ENABLE_PTM_WARNING ``` ### Remarks -The ATL and MFC libraries have been changed to match the Microsoft C++ compiler's improved standard C++ compliance. According to the ANSI C++ standard, the syntax of a pointer to a class member function should be `&CMyClass::MyFunc`. +The ATL and MFC libraries have been changed to match the Microsoft C++ compiler's improved standard C++ conformance. According to the ANSI C++ standard, the syntax of a pointer to a class member function should be `&CMyClass::MyFunc`. -When [_ATL_ENABLE_PTM_WARNING](#_atl_enable_ptm_warning) is not defined (the default case), ATL/MFC disables the C4867 error in macro maps (notably message maps) so that code that was created in earlier versions can continue to build as before. If you define **_ATL_ENABLE_PTM_WARNING**, your code should be C++ standard compliant. +When [`_ATL_ENABLE_PTM_WARNING`](#_atl_enable_ptm_warning) isn't defined (the default case), ATL/MFC disables the C4867 error in macro maps (notably message maps) so that code that was created in earlier versions can continue to build as before. If you define `_ATL_ENABLE_PTM_WARNING`, your code should conform to the C++ standard. -However, the non-standard form has been deprecated. You need to move existing code to C++ standard compliant syntax. For example, the following code: +However, the nonstandard form has been deprecated. You need to move existing code to C++ standard syntax. For example, the following code: [!code-cpp[NVC_MFCListView#14](../../atl/reference/codesnippet/cpp/compiler-options-macros_2.cpp)] @@ -110,7 +110,7 @@ Should be changed to: For map macros, add the ampersand '&' character. You shouldn't add the character again in your code. -## _ATL_FREE_THREADED +## `_ATL_FREE_THREADED` Define if one or more of your objects use free or neutral threading. @@ -122,9 +122,17 @@ _ATL_FREE_THREADED Specifies free threading. Free threading is equivalent to a multithread apartment model. See [Specifying the Project's Threading Model](../../atl/specifying-the-threading-model-for-a-project-atl.md) for other threading options, and [Options, ATL Simple Object Wizard](../../atl/reference/options-atl-simple-object-wizard.md) for a description of the threading models available for an ATL object. -## _ATL_MULTI_THREADED +## `_ATL_MODULES` + +Allows you to compile ATL projects with [`permissive-`](../../build/reference/permissive-standards-conformance.md) and use ATL with [C++ modules](../../cpp/modules-cpp.md). + +``` +_ATL_MODULES +``` + +## `_ATL_MULTI_THREADED` -A symbol that indicates the project will have objects that are marked as Both, Free or Neutral. +A symbol that indicates the project has objects that are marked as Both, Free or Neutral. ``` _ATL_MULTI_THREADED @@ -132,9 +140,9 @@ _ATL_MULTI_THREADED ### Remarks -If this symbol is defined, ATL will pull in code that will correctly synchronize access to global data. New code should use the equivalent macro [_ATL_FREE_THREADED](#_atl_free_threaded) instead. +If this symbol is defined, ATL pulls in code that will correctly synchronize access to global data. New code should use the equivalent macro [`_ATL_FREE_THREADED`](#_atl_free_threaded) instead. -## _ATL_NO_AUTOMATIC_NAMESPACE +## `_ATL_NO_AUTOMATIC_NAMESPACE` A symbol that prevents the default use of namespace as ATL. @@ -144,9 +152,9 @@ _ATL_NO_AUTOMATIC_NAMESPACE ### Remarks -If this symbol is not defined, including atlbase.h will perform **using namespace ATL** by default, which may lead to naming conflicts. To prevent this, define this symbol. +If this symbol isn't defined, including `atlbase.h` performs `using namespace ATL` by default, which may lead to naming conflicts. To prevent this, define this symbol. -## _ATL_NO_COM_SUPPORT +## `_ATL_NO_COM_SUPPORT` A symbol that prevents COM-related code from being compiled with your project. @@ -154,7 +162,7 @@ A symbol that prevents COM-related code from being compiled with your project. _ATL_NO_COM_SUPPORT ``` -## ATL_NO_VTABLE +## `ATL_NO_VTABLE` A symbol that prevents the vtable pointer from being initialized in the class's constructor and destructor. @@ -164,13 +172,13 @@ ATL_NO_VTABLE ### Remarks -If the vtable pointer is prevented from being initialized in the class's constructor and destructor, the linker can eliminate the vtable and all of the functions to which it points. Expands to **`__declspec(novtable)`**. +If the vtable pointer is prevented from being initialized in the class's constructor and destructor, the linker can eliminate the vtable and all of the functions to which it points. Expands to `__declspec(novtable)`. ### Example [!code-cpp[NVC_ATL_COM#53](../../atl/codesnippet/cpp/compiler-options-macros_4.h)] -## ATL_NOINLINE +## `ATL_NOINLINE` A symbol that indicates a function shouldn't be inlined. @@ -184,14 +192,14 @@ A symbol that indicates a function shouldn't be inlined. ### Parameters -*myfunction*
-The function that should not be inlined. +*`myfunction`*\ +The function that shouldn't be inlined. ### Remarks -Use this symbol if you want to ensure a function does not get inlined by the compiler, even though it must be declared as inline so that it can be placed in a header file. Expands to **`__declspec(noinline)`**. +Use this symbol if you want to ensure a function doesn't get inlined by the compiler, even though it must be declared as inline so that it can be placed in a header file. Expands to `__declspec(noinline)`. -## _ATL_SINGLE_THREADED +## `_ATL_SINGLE_THREADED` Define if all of your objects use the single threading model diff --git a/docs/atl/reference/composite-control-global-functions.md b/docs/atl/reference/composite-control-global-functions.md index d3454949a4..b55042bb27 100644 --- a/docs/atl/reference/composite-control-global-functions.md +++ b/docs/atl/reference/composite-control-global-functions.md @@ -279,7 +279,7 @@ One of the standard HRESULT values. ### Example -See [Hosting ActiveX Controls Using ATL AXHost](../../atl/atl-control-containment-faq.md#hosting-activex-controls-using-atl-axhost) for a sample of how to use `AtlAxCreateControlLic`. +See [Hosting ActiveX Controls Using ATL AXHost](../../atl/atl-control-containment-faq.yml#hosting-activex-controls-using-atl-axhost) for a sample of how to use `AtlAxCreateControlLic`. ## AtlAxCreateControlLicEx @@ -346,7 +346,7 @@ One of the standard HRESULT values. ### Example -See [Hosting ActiveX Controls Using ATL AXHost](../../atl/atl-control-containment-faq.md#hosting-activex-controls-using-atl-axhost) for a sample of how to use `AtlAxCreateControlLicEx`. +See [Hosting ActiveX Controls Using ATL AXHost](../../atl/atl-control-containment-faq.yml#hosting-activex-controls-using-atl-axhost) for a sample of how to use `AtlAxCreateControlLicEx`. ## AtlAxAttachControl diff --git a/docs/atl/reference/composite-control-macros.md b/docs/atl/reference/composite-control-macros.md index 2d9e4e9fee..9721f16031 100644 --- a/docs/atl/reference/composite-control-macros.md +++ b/docs/atl/reference/composite-control-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: Composite Control Macros" title: "Composite Control Macros" ms.date: "05/06/2019" -f1_keywords: ["atlcom/ATL::BEGIN_SINK_MAP", "atlcom/ATL::END_SINK_MAP", "atlcom/ATL::SINK_ENTRY"] +f1_keywords: ["atlcom/ATL::BEGIN_SINK_MAP", "atlcom/ATL::END_SINK_MAP", "atlcom/ATL::SINK_ENTRY", "ATLCOM/BEGIN_SINK_MAP", "ATLCOM/END_SINK_MAP", "ATLCOM/SINK_ENTRY", "ATLCOM/SINK_ENTRY_EX", "ATLCOM/SINK_ENTRY_EX_P", "ATLCOM/SINK_ENTRY_INFO", "ATLCOM/SINK_ENTRY_INFO_P", "BEGIN_SINK_MAP", "END_SINK_MAP", "SINK_ENTRY", "SINK_ENTRY_EX", "SINK_ENTRY_EX_P", "SINK_ENTRY_INFO", "SINK_ENTRY_INFO_P"] helpviewer_keywords: ["composite controls, macros"] ms.assetid: 17f2dd5e-07e6-4aa6-b965-7a361c78c45e --- @@ -15,7 +15,7 @@ These macros define event sink maps and entries. |[BEGIN_SINK_MAP](#begin_sink_map)|Marks the beginning of the event sink map for the composite control.| |[END_SINK_MAP](#end_sink_map)|Marks the end of the event sink map for the composite control.| |[SINK_ENTRY](#sink_entry)|Entry to the event sink map.| -|[SINK_ENTRY_EX](#sink_entry_ex)|Entry to the event sink map with an additional parameter.| +|[SINK_ENTRY_EX](#sink_entry_ex)|Entry to the event sink map with an extra parameter.| |[SINK_ENTRY_EX_P](#sink_entry_ex)| (Visual Studio 2017) Similar to SINK_ENTRY_EX except that it takes a pointer to iid.| |[SINK_ENTRY_INFO](#sink_entry_info)|Entry to the event sink map with manually supplied type information for use with [IDispEventSimpleImpl](../../atl/reference/idispeventsimpleimpl-class.md).| |[SINK_ENTRY_INFO_P](#sink_entry_info)| (Visual Studio 2017) Similar to SINK_ENTRY_INFO except that it takes a pointer to iid.| @@ -43,7 +43,7 @@ BEGIN_SINK_MAP(_class) ### Remarks -CE ATL implementation of ActiveX event sinks only supports return values of type HRESULT or void from your event handler methods; any other return value is unsupported and its behavior is undefined. +CE ATL implementation of ActiveX event sinks only supports return values of type HRESULT or void from your event handler methods. Any other return value is unsupported and its behavior is undefined. ## END_SINK_MAP @@ -59,7 +59,7 @@ END_SINK_MAP() ### Remarks -CE ATL implementation of ActiveX event sinks only supports return values of type HRESULT or void from your event handler methods; any other return value is unsupported and its behavior is undefined. +CE ATL implementation of ActiveX event sinks only supports return values of type HRESULT or void from your event handler methods. Any other return value is unsupported and its behavior is undefined. ## SINK_ENTRY @@ -86,7 +86,7 @@ SINK_ENTRY( id, dispid, fn ) ### Remarks -CE ATL implementation of ActiveX event sinks only supports return values of type HRESULT or void from your event handler methods; any other return value is unsupported and its behavior is undefined. +CE ATL implementation of ActiveX event sinks only supports return values of type HRESULT or void from your event handler methods. Any other return value is unsupported and its behavior is undefined. ## SINK_ENTRY_EX and SINK_ENTRY_EX_P @@ -120,7 +120,7 @@ SINK_ENTRY_EX_P( id, piid, dispid, fn ) // (Visual Studio 2017) ### Remarks -CE ATL implementation of ActiveX event sinks only supports return values of type HRESULT or void from your event handler methods; any other return value is unsupported and its behavior is undefined. +CE ATL implementation of ActiveX event sinks only supports return values of type HRESULT or void from your event handler methods. Any other return value is unsupported and its behavior is undefined. ## SINK_ENTRY_INFO and SINK_ENTRY_INFO_P @@ -153,7 +153,7 @@ SINK_ENTRY_INFO_P( id, piid, dispid, fn, info ) // (Visual Studio 2017) ### Remarks -The first four macro parameters are the same as those for the [SINK_ENTRY_EX](#sink_entry_ex) macro. The final parameter provides type information for the event. CE ATL implementation of ActiveX event sinks only supports return values of type HRESULT or void from your event handler methods; any other return value is unsupported and its behavior is undefined. +The first four macro parameters are the same as the ones for the [SINK_ENTRY_EX](#sink_entry_ex) macro. The final parameter provides type information for the event. CE ATL implementation of ActiveX event sinks only supports return values of type HRESULT or void from your event handler methods. Any other return value is unsupported and its behavior is undefined. ## See also diff --git a/docs/atl/reference/connection-point-macros.md b/docs/atl/reference/connection-point-macros.md index 5fb40db7d0..490abb2c38 100644 --- a/docs/atl/reference/connection-point-macros.md +++ b/docs/atl/reference/connection-point-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: Connection Point Macros" title: "Connection Point Macros" ms.date: "11/04/2016" -f1_keywords: ["atlcom/ATL::BEGIN_CONNECTION_POINT_MAP", "atlcom/ATL::END_CONNECTION_POINT_MAP"] +f1_keywords: ["atlcom/ATL::BEGIN_CONNECTION_POINT_MAP", "atlcom/ATL::END_CONNECTION_POINT_MAP", "ATLCOM/BEGIN_CONNECTION_POINT_MAP", "ATLCOM/END_CONNECTION_POINT_MAP", "ATLCOM/CONNECTION_POINT_ENTRY", "ATLCOM/CONNECTION_POINT_ENTRY_P", "BEGIN_CONNECTION_POINT_MAP", "END_CONNECTION_POINT_MAP", "CONNECTION_POINT_ENTRY", "CONNECTION_POINT_ENTRY_P"] helpviewer_keywords: ["connection points [C++], macros"] ms.assetid: cc3a6dd3-5538-45df-b027-1f34963c31e5 --- diff --git a/docs/atl/reference/cpatht-class.md b/docs/atl/reference/cpatht-class.md index 902d18e0af..32b31a3db1 100644 --- a/docs/atl/reference/cpatht-class.md +++ b/docs/atl/reference/cpatht-class.md @@ -60,14 +60,14 @@ The ATL/MFC string class to use for the path (see [CStringT](../../atl-mfc-share |[CPathT::GetDriveNumber](#getdrivenumber)|Call this method to search the path for a drive letter within the range of 'A' to 'Z' and return the corresponding drive number.| |[CPathT::GetExtension](#getextension)|Call this method to get the file extension from the path.| |[CPathT::IsDirectory](#isdirectory)|Call this method to check whether the path is a valid directory.| -|[CPathT::IsFileSpec](#isfilespec)|Call this method to search a path for any path-delimiting characters (for example, ':' or '\\' ). If there are no path-delimiting characters present, the path is considered to be a File Spec path.| +|[CPathT::IsFileSpec](#isfilespec)|Call this method to search a path for any path-delimiting characters (for example, `:` or `\`). If there are no path-delimiting characters present, the path is considered to be a File Spec path.| |[CPathT::IsPrefix](#isprefix)|Call this method to determine whether a path contains a valid prefix of the type passed by *pszPrefix*.| |[CPathT::IsRelative](#isrelative)|Call this method to determine if the path is relative.| |[CPathT::IsRoot](#isroot)|Call this method to determine if the path is a directory root.| |[CPathT::IsSameRoot](#issameroot)|Call this method to determine whether another path has a common root component with the current path.| |[CPathT::IsUNC](#isunc)|Call this method to determine whether the path is a valid UNC (universal naming convention) path for a server and share.| |[CPathT::IsUNCServer](#isuncserver)|Call this method to determine whether the path is a valid UNC (universal naming convention) path for a server only.| -|[CPathT::IsUNCServerShare](#isuncservershare)|Call this method to determine whether the path is a valid UNC (universal naming convention) share path, \\\ *server*\ *share*.| +|[CPathT::IsUNCServerShare](#isuncservershare)|Call this method to determine whether the path is a valid UNC (universal naming convention) share path, *`\\server\share`*.| |[CPathT::MakePretty](#makepretty)|Call this method to convert a path to all lowercase characters to give the path a consistent appearance.| |[CPathT::MatchSpec](#matchspec)|Call this method to search the path for a string containing a wildcard match type.| |[CPathT::QuoteSpaces](#quotespaces)|Call this method to enclose the path in quotation marks if it contains any spaces.| @@ -177,7 +177,7 @@ void BuildRoot(int iDrive); ### Parameters *iDrive*
-The drive number (0 is A:, 1 is B:, and so on). +The drive number (0 is *`A:`*, 1 is *`B:`*, and so on). ### Remarks @@ -396,7 +396,7 @@ For more information, see [PathIsDirectory](/windows/win32/api/shlwapi/nf-shlwap ## CPathT::IsFileSpec -Call this method to search a path for any path-delimiting characters (for example, ':' or '\\' ). If there are no path-delimiting characters present, the path is considered to be a File Spec path. +Call this method to search a path for any path-delimiting characters (for example, `:` or `\`). If there are no path-delimiting characters present, the path is considered to be a File Spec path. ``` BOOL IsFileSpec() const; @@ -598,7 +598,7 @@ The string to append. Returns the updated path. -## CPathT::operator const StringType & +## CPathT::operator const StringType & This operator allows the object to be treated like a string. @@ -622,7 +622,7 @@ operator PCXSTR() const throw(); Returns a string representing the current path managed by this object. -## CPathT::operator StringType & +## CPathT::operator StringType & This operator allows the object to be treated like a string. diff --git a/docs/atl/reference/cregkey-class.md b/docs/atl/reference/cregkey-class.md index 6738e5cb07..175495ad2e 100644 --- a/docs/atl/reference/cregkey-class.md +++ b/docs/atl/reference/cregkey-class.md @@ -4,9 +4,8 @@ title: "CRegKey Class" ms.date: "11/04/2016" f1_keywords: ["CRegKey", "ATLBASE/ATL::CRegKey", "ATLBASE/ATL::CRegKey::CRegKey", "ATLBASE/ATL::CRegKey::Attach", "ATLBASE/ATL::CRegKey::Close", "ATLBASE/ATL::CRegKey::Create", "ATLBASE/ATL::CRegKey::DeleteSubKey", "ATLBASE/ATL::CRegKey::DeleteValue", "ATLBASE/ATL::CRegKey::Detach", "ATLBASE/ATL::CRegKey::EnumKey", "ATLBASE/ATL::CRegKey::Flush", "ATLBASE/ATL::CRegKey::GetKeySecurity", "ATLBASE/ATL::CRegKey::NotifyChangeKeyValue", "ATLBASE/ATL::CRegKey::Open", "ATLBASE/ATL::CRegKey::QueryBinaryValue", "ATLBASE/ATL::CRegKey::QueryDWORDValue", "ATLBASE/ATL::CRegKey::QueryGUIDValue", "ATLBASE/ATL::CRegKey::QueryMultiStringValue", "ATLBASE/ATL::CRegKey::QueryQWORDValue", "ATLBASE/ATL::CRegKey::QueryStringValue", "ATLBASE/ATL::CRegKey::QueryValue", "ATLBASE/ATL::CRegKey::RecurseDeleteKey", "ATLBASE/ATL::CRegKey::SetBinaryValue", "ATLBASE/ATL::CRegKey::SetDWORDValue", "ATLBASE/ATL::CRegKey::SetGUIDValue", "ATLBASE/ATL::CRegKey::SetKeySecurity", "ATLBASE/ATL::CRegKey::SetKeyValue", "ATLBASE/ATL::CRegKey::SetMultiStringValue", "ATLBASE/ATL::CRegKey::SetQWORDValue", "ATLBASE/ATL::CRegKey::SetStringValue", "ATLBASE/ATL::CRegKey::SetValue", "ATLBASE/ATL::CRegKey::m_hKey", "ATLBASE/ATL::CRegKey::m_pTM"] helpviewer_keywords: ["CRegKey class", "ATL, registry", "registry, deleting values", "registry, writing to", "registry, deleting keys"] -ms.assetid: 3afce82b-ba2c-4c1a-8404-dc969e1af74b --- -# CRegKey Class +# `CRegKey` Class This class provides methods for manipulating entries in the system registry. @@ -25,55 +24,55 @@ class CRegKey |Name|Description| |----------|-----------------| -|[CRegKey::CRegKey](#cregkey)|The constructor.| -|[CRegKey::~CRegKey](#dtor)|The destructor.| +|[`CRegKey::CRegKey`](#cregkey)|The constructor.| +|[`CRegKey::~CRegKey`](#dtor)|The destructor.| ### Public Methods |Name|Description| |----------|-----------------| -|[CRegKey::Attach](#attach)|Call this method to attach an HKEY to the `CRegKey` object by setting the [m_hKey](#m_hkey) member handle to `hKey`.| -|[CRegKey::Close](#close)|Call this method to release the [m_hKey](#m_hkey) member handle and set it to NULL.| -|[CRegKey::Create](#create)|Call this method to create the specified key, if it does not exist as a subkey of `hKeyParent`.| -|[CRegKey::DeleteSubKey](#deletesubkey)|Call this method to remove the specified key from the registry.| -|[CRegKey::DeleteValue](#deletevalue)|Call this method to remove a value field from [m_hKey](#m_hkey).| -|[CRegKey::Detach](#detach)|Call this method to detach the [m_hKey](#m_hkey) member handle from the `CRegKey` object and set `m_hKey` to NULL.| -|[CRegKey::EnumKey](#enumkey)|Call this method to enumerate the subkeys of the open registry key.| -|[CRegKey::Flush](#flush)|Call this method to write all of the attributes of the open registry key into the registry.| -|[CRegKey::GetKeySecurity](#getkeysecurity)|Call this method to retrieve a copy of the security descriptor protecting the open registry key.| -|[CRegKey::NotifyChangeKeyValue](#notifychangekeyvalue)|This method notifies the caller about changes to the attributes or contents of the open registry key.| -|[CRegKey::Open](#open)|Call this method to open the specified key and set [m_hKey](#m_hkey) to the handle of this key.| -|[CRegKey::QueryBinaryValue](#querybinaryvalue)|Call this method to retrieve the binary data for a specified value name.| -|[CRegKey::QueryDWORDValue](#querydwordvalue)|Call this method to retrieve the DWORD data for a specified value name.| -|[CRegKey::QueryGUIDValue](#queryguidvalue)|Call this method to retrieve the GUID data for a specified value name.| -|[CRegKey::QueryMultiStringValue](#querymultistringvalue)|Call this method to retrieve the multistring data for a specified value name.| -|[CRegKey::QueryQWORDValue](#queryqwordvalue)|Call this method to retrieve the QWORD data for a specified value name.| -|[CRegKey::QueryStringValue](#querystringvalue)|Call this method to retrieve the string data for a specified value name.| -|[CRegKey::QueryValue](#queryvalue)|Call this method to retrieve the data for the specified value field of [m_hKey](#m_hkey). Earlier versions of this method are no longer supported and are marked as ATL_DEPRECATED.| -|[CRegKey::RecurseDeleteKey](#recursedeletekey)|Call this method to remove the specified key from the registry and explicitly remove any subkeys.| -|[CRegKey::SetBinaryValue](#setbinaryvalue)|Call this method to set the binary value of the registry key.| -|[CRegKey::SetDWORDValue](#setdwordvalue)|Call this method to set the DWORD value of the registry key.| -|[CRegKey::SetGUIDValue](#setguidvalue)|Call this method to set the GUID value of the registry key.| -|[CRegKey::SetKeySecurity](#setkeysecurity)|Call this method to set the security of the registry key.| -|[CRegKey::SetKeyValue](#setkeyvalue)|Call this method to store data in a specified value field of a specified key.| -|[CRegKey::SetMultiStringValue](#setmultistringvalue)|Call this method to set the multistring value of the registry key.| -|[CRegKey::SetQWORDValue](#setqwordvalue)|Call this method to set the QWORD value of the registry key.| -|[CRegKey::SetStringValue](#setstringvalue)|Call this method to set the string value of the registry key.| -|[CRegKey::SetValue](#setvalue)|Call this method to store data in the specified value field of [m_hKey](#m_hkey). Earlier versions of this method are no longer supported and are marked as ATL_DEPRECATED.| +|[`CRegKey::Attach`](#attach)|Call this method to attach an HKEY to the `CRegKey` object by setting the [`m_hKey`](#m_hkey) member handle to `hKey`.| +|[`CRegKey::Close`](#close)|Call this method to release the [`m_hKey`](#m_hkey) member handle and set it to `NULL`.| +|[`CRegKey::Create`](#create)|Call this method to create the specified key, if it doesn't exist as a subkey of `hKeyParent`.| +|[`CRegKey::DeleteSubKey`](#deletesubkey)|Call this method to remove the specified key from the registry.| +|[`CRegKey::DeleteValue`](#deletevalue)|Call this method to remove a value field from [`m_hKey`](#m_hkey).| +|[`CRegKey::Detach`](#detach)|Call this method to detach the [`m_hKey`](#m_hkey) member handle from the `CRegKey` object and set `m_hKey` to `NULL`.| +|[`CRegKey::EnumKey`](#enumkey)|Call this method to enumerate the subkeys of the open registry key.| +|[`CRegKey::Flush`](#flush)|Call this method to write all of the attributes of the open registry key into the registry.| +|[`CRegKey::GetKeySecurity`](#getkeysecurity)|Call this method to retrieve a copy of the security descriptor protecting the open registry key.| +|[`CRegKey::NotifyChangeKeyValue`](#notifychangekeyvalue)|This method notifies the caller about changes to the attributes or contents of the open registry key.| +|[`CRegKey::Open`](#open)|Call this method to open the specified key and set [`m_hKey`](#m_hkey) to the handle of this key.| +|[`CRegKey::QueryBinaryValue`](#querybinaryvalue)|Call this method to retrieve the binary data for a specified value name.| +|[`CRegKey::QueryDWORDValue`](#querydwordvalue)|Call this method to retrieve the `DWORD` data for a specified value name.| +|[`CRegKey::QueryGUIDValue`](#queryguidvalue)|Call this method to retrieve the GUID data for a specified value name.| +|[`CRegKey::QueryMultiStringValue`](#querymultistringvalue)|Call this method to retrieve the multistring data for a specified value name.| +|[`CRegKey::QueryQWORDValue`](#queryqwordvalue)|Call this method to retrieve the `QWORD` data for a specified value name.| +|[`CRegKey::QueryStringValue`](#querystringvalue)|Call this method to retrieve the string data for a specified value name.| +|[`CRegKey::QueryValue`](#queryvalue)|Call this method to retrieve the data for the specified value field of [`m_hKey`](#m_hkey). Earlier versions of this method are no longer supported and are marked as `ATL_DEPRECATED`.| +|[`CRegKey::RecurseDeleteKey`](#recursedeletekey)|Call this method to remove the specified key from the registry and explicitly remove any subkeys.| +|[`CRegKey::SetBinaryValue`](#setbinaryvalue)|Call this method to set the binary value of the registry key.| +|[`CRegKey::SetDWORDValue`](#setdwordvalue)|Call this method to set the `DWORD` value of the registry key.| +|[`CRegKey::SetGUIDValue`](#setguidvalue)|Call this method to set the GUID value of the registry key.| +|[`CRegKey::SetKeySecurity`](#setkeysecurity)|Call this method to set the security of the registry key.| +|[`CRegKey::SetKeyValue`](#setkeyvalue)|Call this method to store data in a specified value field of a specified key.| +|[`CRegKey::SetMultiStringValue`](#setmultistringvalue)|Call this method to set the multistring value of the registry key.| +|[`CRegKey::SetQWORDValue`](#setqwordvalue)|Call this method to set the `QWORD` value of the registry key.| +|[`CRegKey::SetStringValue`](#setstringvalue)|Call this method to set the string value of the registry key.| +|[`CRegKey::SetValue`](#setvalue)|Call this method to store data in the specified value field of [`m_hKey`](#m_hkey). Earlier versions of this method are no longer supported and are marked as `ATL_DEPRECATED`.| ### Public Operators |Name|Description| |----------|-----------------| -|[CRegKey::operator HKEY](#operator_hkey)|Converts a `CRegKey` object to an HKEY.| -|[CRegKey::operator =](#operator_eq)|Assignment operator.| +|[`CRegKey::operator HKEY`](#operator_hkey)|Converts a `CRegKey` object to an `HKEY`.| +|[`CRegKey::operator =`](#operator_eq)|Assignment operator.| ### Public Data Members |Name|Description| |----------|-----------------| -|[CRegKey::m_hKey](#m_hkey)|Contains a handle of the registry key associated with the `CRegKey` object.| -|[CRegKey::m_pTM](#m_ptm)|Pointer to `CAtlTransactionManager` object| +|[`CRegKey::m_hKey`](#m_hkey)|Contains a handle of the registry key associated with the `CRegKey` object.| +|[`CRegKey::m_pTM`](#m_ptm)|Pointer to `CAtlTransactionManager` object| ## Remarks @@ -81,18 +80,18 @@ class CRegKey `CRegKey` provides a programming interface to the system registry for a given machine. For example, to open a particular registry key, call `CRegKey::Open`. To retrieve or modify a data value, call `CRegKey::QueryValue` or `CRegKey::SetValue`, respectively. To close a key, call `CRegKey::Close`. -When you close a key, its registry data is written (flushed) to the hard disk. This process may take several seconds. If your application must explicitly write registry data to the hard disk, you can call the [RegFlushKey](/windows/win32/api/winreg/nf-winreg-regflushkey) Win32 function. However, `RegFlushKey` uses many system resources and should be called only when absolutely necessary. +When you close a key, its registry data is written (flushed) to the hard disk. This process may take several seconds. If your application must explicitly write registry data to the hard disk, you can call the [`RegFlushKey`](/windows/win32/api/winreg/nf-winreg-regflushkey) Win32 function. However, `RegFlushKey` uses many system resources and should be called only when absolutely necessary. > [!IMPORTANT] -> Any methods that allow the caller to specify a registry location have the potential to read data that cannot be trusted. Methods that make use of [RegQueryValueEx](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) should take into consideration that this function does not explicitly handle strings which are NULL terminated. Both conditions should be checked for by the calling code. +> Any methods that allow the caller to specify a registry location have the potential to read data that cannot be trusted. Methods that make use of [`RegQueryValueEx`](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) should take into consideration that this function does not explicitly handle strings which are null-terminated. Both conditions should be checked for by the calling code. ## Requirements -**Header:** atlbase.h +**Header:** `atlbase.h` -## CRegKey::Attach +## `CRegKey::Attach` -Call this method to attach an HKEY to the `CRegKey` object by setting the [m_hKey](#m_hkey) member handle to *hKey*. +Call this method to attach an `HKEY` to the `CRegKey` object by setting the [`m_hKey`](#m_hkey) member handle to *`hKey`*. ```cpp void Attach(HKEY hKey) throw(); @@ -100,16 +99,16 @@ void Attach(HKEY hKey) throw(); ### Parameters -*hKey*
+`hKey`\ The handle of a registry key. ### Remarks -`Attach` will assert if `m_hKey` is non-NULL. +`Attach` will assert if `m_hKey` is non-`NULL`. -## CRegKey::Close +## `CRegKey::Close` -Call this method to release the [m_hKey](#m_hkey) member handle and set it to NULL. +Call this method to release the [`m_hKey`](#m_hkey) member handle and set it to `NULL`. ``` LONG Close() throw(); @@ -117,11 +116,11 @@ LONG Close() throw(); ### Return Value -If successful, returns ERROR_SUCCESS; otherwise returns an error value. +If successful, returns `ERROR_SUCCESS`; otherwise returns an error value. -## CRegKey::Create +## `CRegKey::Create` -Call this method to create the specified key, if it does not exist as a subkey of *hKeyParent*. +Call this method to create the specified key, if it doesn't exist as a subkey of *`hKeyParent`*. ``` LONG Create( @@ -136,36 +135,36 @@ LONG Create( ### Parameters -*hKeyParent*
+*`hKeyParent`*\ The handle of an open key. -*lpszKeyName*
-Specifies the name of a key to be created or opened. This name must be a subkey of *hKeyParent*. +*`lpszKeyName`*\ +Specifies the name of a key to be created or opened. This name must be a subkey of *`hKeyParent`*. -*lpszClass*
+*`lpszClass`*\ Specifies the class of the key to be created or opened. The default value is REG_NONE. -*dwOptions*
-Options for the key. The default value is REG_OPTION_NON_VOLATILE. For a list of possible values and descriptions, see [RegCreateKeyEx](/windows/win32/api/winreg/nf-winreg-regcreatekeyexw) in the Windows SDK. +*`dwOptions`*\ +Options for the key. The default value is `REG_OPTION_NON_VOLATILE`. For a list of possible values and descriptions, see [`RegCreateKeyEx`](/windows/win32/api/winreg/nf-winreg-regcreatekeyexw) in the Windows SDK. -*samDesired*
-The security access for the key. The default value is KEY_READ | KEY_WRITE. For a list of possible values and descriptions, see `RegCreateKeyEx`. +*`samDesired`*\ +The security access for the key. The default value is `KEY_READ | KEY_WRITE`. For a list of possible values and descriptions, see `RegCreateKeyEx`. -*lpSecAttr*
-A pointer to a [SECURITY_ATTRIBUTES](/previous-versions/windows/desktop/legacy/aa379560\(v=vs.85\)) structure that indicates whether the handle of the key can be inherited by a child process. By default, this parameter is NULL (meaning the handle cannot be inherited). +*`lpSecAttr`*\ +A pointer to a [`SECURITY_ATTRIBUTES`](/previous-versions/windows/desktop/legacy/aa379560\(v=vs.85\)) structure that indicates whether the handle of the key can be inherited by a child process. By default, this parameter is `NULL` (meaning the handle can't be inherited). -*lpdwDisposition*
-[out] If non-NULL, retrieves either REG_CREATED_NEW_KEY (if the key did not exist and was created) or REG_OPENED_EXISTING_KEY (if the key existed and was opened). +*`lpdwDisposition`*\ +[out] If non-`NULL`, retrieves either `REG_CREATED_NEW_KEY` (if the key didn't exist and was created) or `REG_OPENED_EXISTING_KEY` (if the key existed and was opened). ### Return Value -If successful, returns ERROR_SUCCESS and opens the key. If the method fails, the return value is a nonzero error code defined in WINERROR.H. +If successful, returns `ERROR_SUCCESS` and opens the key. If the method fails, the return value is a nonzero error code defined in `WINERROR.H`. ### Remarks -`Create` sets the [m_hKey](#m_hkey) member to the handle of this key. +`Create` sets the [`m_hKey`](#m_hkey) member to the handle of this key. -## CRegKey::CRegKey +## `CRegKey::CRegKey` The constructor. @@ -178,20 +177,20 @@ CRegKey(CAtlTransactionManager* pTM) throw(); ### Parameters -*key*
+*`key`*\ A reference to a `CRegKey` object. -*hKey*
+`hKey`\ A handle to a registry key. -*pTM*
-Pointer to CAtlTransactionManager object +*`pTM`*\ +Pointer to `CAtlTransactionManager` object ### Remarks Creates a new `CRegKey` object. The object can be created from an existing `CRegKey` object, or from a handle to a registry key. -## CRegKey::~CRegKey +## `CRegKey::~CRegKey` The destructor. @@ -203,7 +202,7 @@ The destructor. The destructor releases `m_hKey`. -## CRegKey::DeleteSubKey +## `CRegKey::DeleteSubKey` Call this method to remove the specified key from the registry. @@ -213,20 +212,20 @@ LONG DeleteSubKey(LPCTSTR lpszSubKey) throw(); ### Parameters -*lpszSubKey*
-Specifies the name of the key to delete. This name must be a subkey of [m_hKey](#m_hkey). +*`lpszSubKey`*\ +Specifies the name of the key to delete. This name must be a subkey of [`m_hKey`](#m_hkey). ### Return Value -If successful, returns ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H. +If successful, returns `ERROR_SUCCESS`. If the method fails, the return value is a nonzero error code defined in `WINERROR.H`. ### Remarks -`DeleteSubKey` can only delete a key that has no subkeys. If the key has subkeys, call [RecurseDeleteKey](#recursedeletekey) instead. +`DeleteSubKey` can only delete a key that has no subkeys. If the key has subkeys, call [`RecurseDeleteKey`](#recursedeletekey) instead. -## CRegKey::DeleteValue +## `CRegKey::DeleteValue` -Call this method to remove a value field from [m_hKey](#m_hkey). +Call this method to remove a value field from [`m_hKey`](#m_hkey). ``` LONG DeleteValue(LPCTSTR lpszValue) throw(); @@ -234,16 +233,16 @@ LONG DeleteValue(LPCTSTR lpszValue) throw(); ### Parameters -*lpszValue*
+*`lpszValue`*\ Specifies the value field to remove. ### Return Value -If successful, returns ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H. +If successful, returns `ERROR_SUCCESS`. If the method fails, the return value is a nonzero error code defined in `WINERROR.H`. -## CRegKey::Detach +## `CRegKey::Detach` -Call this method to detach the [m_hKey](#m_hkey) member handle from the `CRegKey` object and set `m_hKey` to NULL. +Call this method to detach the [`m_hKey`](#m_hkey) member handle from the `CRegKey` object and set `m_hKey` to `NULL`. ``` HKEY Detach() throw(); @@ -253,7 +252,7 @@ HKEY Detach() throw(); The HKEY associated with the `CRegKey` object. -## CRegKey::EnumKey +## `CRegKey::EnumKey` Call this method to enumerate the subkeys of the open registry key. @@ -267,27 +266,27 @@ LONG EnumKey( ### Parameters -*iIndex*
+*`iIndex`*\ The subkey index. This parameter should be zero for the first call and then incremented for subsequent calls -*pszName*
+*`pszName`*\ Pointer to a buffer that receives the name of the subkey, including the terminating null character. Only the name of the subkey is copied to the buffer, not the full key hierarchy. -*pnNameLength*
-Pointer to a variable that specifies the size, in TCHARs, of the buffer specified by the *pszName* parameter. This size should include the terminating null character. When the method returns, the variable pointed to by *pnNameLength* contains the number of characters stored in the buffer. The count returned does not include the terminating null character. +*`pnNameLength`*\ +Pointer to a variable that specifies the size, in `TCHARs`, of the buffer specified by the *`pszName`* parameter. This size should include the terminating null character. When the method returns, the variable pointed to by *`pnNameLength`* contains the number of characters stored in the buffer. The count returned doesn't include the terminating null character. -*pftLastWriteTime*
+*`pftLastWriteTime`*\ Pointer to a variable that receives the time the enumerated subkey was last written to. ### Return Value -If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H. +If the method succeeds, the return value is `ERROR_SUCCESS`. If the method fails, the return value is a nonzero error code defined in `WINERROR.H`. ### Remarks -To enumerate the subkeys, call `CRegKey::EnumKey` with an index of zero. Increment the index value and repeat until the method returns ERROR_NO_MORE_ITEMS. For more information, see [RegEnumKeyEx](/windows/win32/api/winreg/nf-winreg-regenumkeyexw) in the Windows SDK. +To enumerate the subkeys, call `CRegKey::EnumKey` with an index of zero. Increment the index value and repeat until the method returns `ERROR_NO_MORE_ITEMS`. For more information, see [`RegEnumKeyEx`](/windows/win32/api/winreg/nf-winreg-regenumkeyexw) in the Windows SDK. -## CRegKey::Flush +## `CRegKey::Flush` Call this method to write all of the attributes of the open registry key into the registry. @@ -297,13 +296,13 @@ LONG Flush() throw(); ### Return Value -If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H. +If the method succeeds, the return value is `ERROR_SUCCESS`. If the method fails, the return value is a nonzero error code defined in `WINERROR.H`. ### Remarks -For more information, see [RegEnumFlush](/windows/win32/api/winreg/nf-winreg-regflushkey) in the Windows SDK. +For more information, see [`RegEnumFlush`](/windows/win32/api/winreg/nf-winreg-regflushkey) in the Windows SDK. -## CRegKey::GetKeySecurity +## `CRegKey::GetKeySecurity` Call this method to retrieve a copy of the security descriptor protecting the open registry key. @@ -316,24 +315,24 @@ LONG GetKeySecurity( ### Parameters -*si*
-The [SECURITY_INFORMATION](/windows/win32/SecAuthZ/security-information) value that indicates the requested security information. +*`si`*\ +The [`SECURITY_INFORMATION`](/windows/win32/SecAuthZ/security-information) value that indicates the requested security information. -*psd*
+*`psd`*\ A pointer to a buffer that receives a copy of the requested security descriptor. -*pnBytes*
-The size, in bytes, of the buffer pointed to by *psd*. +*`pnBytes`*\ +The size, in bytes, of the buffer pointed to by *`psd`*. ### Return Value -If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code is defined in WINERROR.H. +If the method succeeds, the return value is `ERROR_SUCCESS`. If the method fails, the return value is a nonzero error code is defined in `WINERROR.H`. ### Remarks -For more information, see [RegGetKeySecurity](/windows/win32/api/winreg/nf-winreg-reggetkeysecurity). +For more information, see [`RegGetKeySecurity`](/windows/win32/api/winreg/nf-winreg-reggetkeysecurity). -## CRegKey::m_hKey +## `CRegKey::m_hKey` Contains a handle of the registry key associated with the `CRegKey` object. @@ -341,7 +340,7 @@ Contains a handle of the registry key associated with the `CRegKey` object. HKEY m_hKey; ``` -## CRegKey::m_pTM +## `CRegKey::m_pTM` Pointer to a `CAtlTransactionManager` object. @@ -351,7 +350,7 @@ CAtlTransactionManager* m_pTM; ### Remarks -## CRegKey::NotifyChangeKeyValue +## `CRegKey::NotifyChangeKeyValue` This method notifies the caller about changes to the attributes or contents of the open registry key. @@ -365,39 +364,39 @@ LONG NotifyChangeKeyValue( ### Parameters -*bWatchSubtree*
-Specifies a flag that indicates whether to report changes in the specified key and all of its subkeys or only in the specified key. If this parameter is TRUE, the method reports changes in the key and its subkeys. If the parameter is FALSE, the method reports changes only in the key. +*`bWatchSubtree`*\ +Specifies a flag that indicates whether to report changes in the specified key and all of its subkeys or only in the specified key. If this parameter is `TRUE`, the method reports changes in the key and its subkeys. If the parameter is `FALSE`, the method reports changes only in the key. -*dwNotifyFilter*
+*`dwNotifyFilter`*\ Specifies a set of flags that control which changes should be reported. This parameter can be a combination of the following values: |Value|Meaning| |-----------|-------------| -|REG_NOTIFY_CHANGE_NAME|Notify the caller if a subkey is added or deleted.| -|REG_NOTIFY_CHANGE_ATTRIBUTES|Notify the caller of changes to the attributes of the key, such as the security descriptor information.| -|REG_NOTIFY_CHANGE_LAST_SET|Notify the caller of changes to a value of the key. This can include adding or deleting a value, or changing an existing value.| -|REG_NOTIFY_CHANGE_SECURITY|Notify the caller of changes to the security descriptor of the key.| +|`REG_NOTIFY_CHANGE_NAME`|Notify the caller if a subkey is added or deleted.| +|`REG_NOTIFY_CHANGE_ATTRIBUTES`|Notify the caller of changes to the attributes of the key, such as the security descriptor information.| +|`REG_NOTIFY_CHANGE_LAST_SET`|Notify the caller of changes to a value of the key. This can include adding or deleting a value, or changing an existing value.| +|`REG_NOTIFY_CHANGE_SECURITY`|Notify the caller of changes to the security descriptor of the key.| -*hEvent*
-Handle to an event. If the *bAsync* parameter is TRUE, the method returns immediately and changes are reported by signaling this event. If *bAsync* is FALSE, *hEvent* is ignored. +*`hEvent`*\ +Handle to an event. If the *`bAsync`* parameter is `TRUE`, the method returns immediately and changes are reported by signaling this event. If *`bAsync`* is `FALSE`, *`hEvent`* is ignored. -*bAsync*
-Specifies a flag that indicates how the method reports changes. If this parameter is TRUE, the method returns immediately and reports changes by signaling the specified event. When this parameter is FALSE, the method does not return until a change has occurred. If *hEvent* does not specify a valid event, the *bAsync* parameter cannot be TRUE. +*`bAsync`*\ +Specifies a flag that indicates how the method reports changes. If this parameter is `TRUE`, the method returns immediately and reports changes by signaling the specified event. When this parameter is `FALSE`, the method doesn't return until a change has occurred. If *`hEvent`* doesn't specify a valid event, the *`bAsync`* parameter can't be `TRUE`. ### Return Value -If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H. +If the method succeeds, the return value is `ERROR_SUCCESS`. If the method fails, the return value is a nonzero error code defined in `WINERROR.H`. ### Remarks > [!NOTE] > This method does not notify the caller if the specified key is deleted. -For more details and a sample program, see [RegNotifyChangeKeyValue](/windows/win32/api/winreg/nf-winreg-regnotifychangekeyvalue). +For more details and a sample program, see [`RegNotifyChangeKeyValue`](/windows/win32/api/winreg/nf-winreg-regnotifychangekeyvalue). -## CRegKey::Open +## `CRegKey::Open` -Call this method to open the specified key and set [m_hKey](#m_hkey) to the handle of this key. +Call this method to open the specified key and set [`m_hKey`](#m_hkey) to the handle of this key. ``` LONG Open( @@ -408,34 +407,34 @@ LONG Open( ### Parameters -*hKeyParent*
+*`hKeyParent`*\ The handle of an open key. -*lpszKeyName*
-Specifies the name of a key to be created or opened. This name must be a subkey of *hKeyParent*. +*`lpszKeyName`*\ +Specifies the name of a key to be created or opened. This name must be a subkey of *`hKeyParent`*. -*samDesired*
-The security access for the key. The default value is KEY_ALL_ACCESS. For a list of possible values and descriptions, see [RegCreateKeyEx](/windows/win32/api/winreg/nf-winreg-regcreatekeyexw) in the Windows SDK. +*`samDesired`*\ +The security access for the key. The default value is `KEY_ALL_ACCESS`. For a list of possible values and descriptions, see [`RegCreateKeyEx`](/windows/win32/api/winreg/nf-winreg-regcreatekeyexw) in the Windows SDK. ### Return Value -If successful, returns ERROR_SUCCESS; otherwise, a non-zero error value defined in WINERROR.H. +If successful, returns `ERROR_SUCCESS`; otherwise, a non-zero error value defined in `WINERROR.H`. ### Remarks -If the *lpszKeyName* parameter is NULL or points to an empty string, `Open` opens a new handle of the key identified by *hKeyParent*, but does not close any previously opened handle. +If the *`lpszKeyName`* parameter is `NULL` or points to an empty string, `Open` opens a new handle of the key identified by *`hKeyParent`*, but doesn't close any previously opened handle. -Unlike [CRegKey::Create](#create), `Open` will not create the specified key if it does not exist. +Unlike [`CRegKey::Create`](#create), `Open` won't create the specified key if it doesn't exist. -## CRegKey::operator HKEY +## `CRegKey::operator HKEY` -Converts a `CRegKey` object to an HKEY. +Converts a `CRegKey` object to an `HKEY`. ``` operator HKEY() const throw(); ``` -## CRegKey::operator = +## `CRegKey::operator =` Assignment operator. @@ -445,7 +444,7 @@ CRegKey& operator= (CRegKey& key) throw(); ### Parameters -*key*
+*`key`*\ The key to copy. ### Return Value @@ -454,9 +453,9 @@ Returns a reference to the new key. ### Remarks -This operator detaches *key* from its current object and assigns it to the `CRegKey` object instead. +This operator detaches *`key`* from its current object and assigns it to the `CRegKey` object instead. -## CRegKey::QueryBinaryValue +## `CRegKey::QueryBinaryValue` Call this method to retrieve the binary data for a specified value name. @@ -469,29 +468,29 @@ LONG QueryBinaryValue( ### Parameters -*pszValueName*
-Pointer to a null-terminated string containing the name of the value to query. +*`pszValueName`*\ +Pointer to a `NULL`-terminated string containing the name of the value to query. -*pValue*
+*`pValue`*\ Pointer to a buffer that receives the value's data. -*pnBytes*
-Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the *pValue* parameter. When the method returns, this variable contains the size of the data copied to the buffer. +*`pnBytes`*\ +Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the *`pValue`* parameter. When the method returns, this variable contains the size of the data copied to the buffer. ### Return Value -If the method succeeds, ERROR_SUCCESS is returned. If the method fails to read a value, it returns a nonzero error code defined in WINERROR.H. If the data referenced is not of type REG_BINARY, ERROR_INVALID_DATA is returned. +If the method succeeds, `ERROR_SUCCESS` is returned. If the method fails to read a value, it returns a nonzero error code defined in `WINERROR.H`. If the data referenced isn't of type `REG_BINARY`, `ERROR_INVALID_DATA` is returned. ### Remarks -This method makes use of `RegQueryValueEx` and confirms that the correct type of data is returned. See [RegQueryValueEx](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) for more details. +This method makes use of `RegQueryValueEx` and confirms that the correct type of data is returned. See [`RegQueryValueEx`](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) for more details. > [!IMPORTANT] -> This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. Also, the [RegQueryValueEx](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) function used by this method does not explicitly handle strings which are NULL terminated. Both conditions should be checked for by the calling code. +> This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. Also, the [`RegQueryValueEx`](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) function used by this method does not explicitly handle strings which are null-terminated. Both conditions should be checked for by the calling code. -## CRegKey::QueryDWORDValue +## `CRegKey::QueryDWORDValue` -Call this method to retrieve the DWORD data for a specified value name. +Call this method to retrieve the `DWORD` data for a specified value name. ``` LONG QueryDWORDValue( @@ -501,24 +500,24 @@ LONG QueryDWORDValue( ### Parameters -*pszValueName*
-Pointer to a null-terminated string containing the name of the value to query. +*`pszValueName`*\ +Pointer to a `NULL`-terminated string containing the name of the value to query. -*dwValue*
-Pointer to a buffer that receives the DWORD. +*`dwValue`*\ +Pointer to a buffer that receives the `DWORD`. ### Return Value -If the method succeeds, ERROR_SUCCESS is returned. If the method fails to read a value, it returns a nonzero error code defined in WINERROR.H. If the data referenced is not of type REG_DWORD, ERROR_INVALID_DATA is returned. +If the method succeeds, `ERROR_SUCCESS` is returned. If the method fails to read a value, it returns a nonzero error code defined in `WINERROR.H`. If the data referenced isn't of type `REG_DWORD`, `ERROR_INVALID_DATA` is returned. ### Remarks -This method makes use of `RegQueryValueEx` and confirms that the correct type of data is returned. See [RegQueryValueEx](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) for more details. +This method makes use of `RegQueryValueEx` and confirms that the correct type of data is returned. See [`RegQueryValueEx`](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) for more details. > [!IMPORTANT] -> This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. Also, the [RegQueryValueEx](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) function used by this method does not explicitly handle strings which are NULL terminated. Both conditions should be checked for by the calling code. +> This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. Also, the [`RegQueryValueEx`](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) function used by this method does not explicitly handle strings which are null-terminated. Both conditions should be checked for by the calling code. -## CRegKey::QueryGUIDValue +## `CRegKey::QueryGUIDValue` Call this method to retrieve the GUID data for a specified value name. @@ -530,24 +529,24 @@ LONG QueryGUIDValue( ### Parameters -*pszValueName*
-Pointer to a null-terminated string containing the name of the value to query. +*`pszValueName`*\ +Pointer to a `NULL`-terminated string containing the name of the value to query. -*guidValue*
+*`guidValue`*\ Pointer to a variable that receives the GUID. ### Return Value -If the method succeeds, ERROR_SUCCESS is returned. If the method fails to read a value, it returns a nonzero error code defined in WINERROR.H. If the data referenced is not a valid GUID, ERROR_INVALID_DATA is returned. +If the method succeeds, `ERROR_SUCCESS` is returned. If the method fails to read a value, it returns a nonzero error code defined in `WINERROR.H`. If the data referenced isn't a valid GUID, `ERROR_INVALID_DATA` is returned. ### Remarks -This method makes use of `CRegKey::QueryStringValue` and converts the string into a GUID using [CLSIDFromString](/windows/win32/api/combaseapi/nf-combaseapi-clsidfromstring). +This method makes use of `CRegKey::QueryStringValue` and converts the string into a GUID using [`CLSIDFromString`](/windows/win32/api/combaseapi/nf-combaseapi-clsidfromstring). > [!IMPORTANT] > This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. -## CRegKey::QueryMultiStringValue +## `CRegKey::QueryMultiStringValue` Call this method to retrieve the multistring data for a specified value name. @@ -560,29 +559,29 @@ LONG QueryMultiStringValue( ### Parameters -*pszValueName*
-Pointer to a null-terminated string containing the name of the value to query. +*`pszValueName`*\ +Pointer to a `NULL`-terminated string containing the name of the value to query. -*pszValue*
-Pointer to a buffer that receives the multistring data. A multistring is an array of null-terminated strings, terminated by two null characters. +*`pszValue`*\ +Pointer to a buffer that receives the multistring data. A multistring is an array of `NULL`-terminated strings, terminated by two null characters. -*pnChars*
-The size, in TCHARs, of the buffer pointed to by *pszValue*. When the method returns, *pnChars* contains the size, in TCHARs, of the multistring retrieved, including a terminating null character. +*`pnChars`*\ +The size, in `TCHARs`, of the buffer pointed to by *`pszValue`*. When the method returns, *`pnChars`* contains the size, in `TCHARs`, of the multistring retrieved, including a terminating null character. ### Return Value -If the method succeeds, ERROR_SUCCESS is returned. If the method fails to read a value, it returns a nonzero error code defined in WINERROR.H. If the data referenced is not of type REG_MULTI_SZ, ERROR_INVALID_DATA is returned. +If the method succeeds, `ERROR_SUCCESS` is returned. If the method fails to read a value, it returns a nonzero error code defined in `WINERROR.H`. If the data referenced isn't of type `REG_MULTI_SZ`, `ERROR_INVALID_DATA` is returned. ### Remarks -This method makes use of `RegQueryValueEx` and confirms that the correct type of data is returned. See [RegQueryValueEx](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) for more details. +This method makes use of `RegQueryValueEx` and confirms that the correct type of data is returned. See [`RegQueryValueEx`](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) for more details. > [!IMPORTANT] -> This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. Also, the [RegQueryValueEx](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) function used by this method does not explicitly handle strings which are NULL terminated. Both conditions should be checked for by the calling code. +> This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. Also, the [`RegQueryValueEx`](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) function used by this method does not explicitly handle strings which are null-terminated. Both conditions should be checked for by the calling code. -## CRegKey::QueryQWORDValue +## `CRegKey::QueryQWORDValue` -Call this method to retrieve the QWORD data for a specified value name. +Call this method to retrieve the `QWORD` data for a specified value name. ``` LONG QueryQWORDValue( @@ -592,24 +591,24 @@ LONG QueryQWORDValue( ### Parameters -*pszValueName*
-Pointer to a null-terminated string containing the name of the value to query. +*`pszValueName`*\ +Pointer to a `NULL`-terminated string containing the name of the value to query. -*qwValue*
-Pointer to a buffer that receives the QWORD. +*`qwValue`*\ +Pointer to a buffer that receives the `QWORD`. ### Return Value -If the method succeeds, ERROR_SUCCESS is returned. If the method fails to read a value, it returns a nonzero error code defined in WINERROR.H. If the data referenced is not of type REG_QWORD, ERROR_INVALID_DATA is returned. +If the method succeeds, `ERROR_SUCCESS` is returned. If the method fails to read a value, it returns a nonzero error code defined in `WINERROR.H`. If the data referenced isn't of type `REG_QWORD`, `ERROR_INVALID_DATA` is returned. ### Remarks -This method makes use of `RegQueryValueEx` and confirms that the correct type of data is returned. See [RegQueryValueEx](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) for more details. +This method makes use of `RegQueryValueEx` and confirms that the correct type of data is returned. See [`RegQueryValueEx`](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) for more details. > [!IMPORTANT] -> This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. Also, the [RegQueryValueEx](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) function used by this method does not explicitly handle strings which are NULL terminated. Both conditions should be checked for by the calling code. +> This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. Also, the [`RegQueryValueEx`](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) function used by this method does not explicitly handle strings which are null-terminated. Both conditions should be checked for by the calling code. -## CRegKey::QueryStringValue +## `CRegKey::QueryStringValue` Call this method to retrieve the string data for a specified value name. @@ -622,29 +621,29 @@ LONG QueryStringValue( ### Parameters -*pszValueName*
-Pointer to a null-terminated string containing the name of the value to query. +*`pszValueName`*\ +Pointer to a `NULL`-terminated string containing the name of the value to query. -*pszValue*
+*`pszValue`*\ Pointer to a buffer that receives the string data. -*pnChars*
-The size, in TCHARs, of the buffer pointed to by *pszValue*. When the method returns, *pnChars* contains the size, in TCHARs, of the string retrieved, including a terminating null character. +*`pnChars`*\ +The size, in TCHARs, of the buffer pointed to by *`pszValue`*. When the method returns, *`pnChars`* contains the size, in `TCHARs`, of the string retrieved, including a terminating null character. ### Return Value -If the method succeeds, ERROR_SUCCESS is returned. If the method fails to read a value, it returns a nonzero error code defined in WINERROR.H. If the data referenced is not of type REG_SZ, ERROR_INVALID_DATA is returned. If the method returns ERROR_MORE_DATA, *pnChars* equals zero, not the required buffer size in bytes. +If the method succeeds, `ERROR_SUCCESS` is returned. If the method fails to read a value, it returns a nonzero error code defined in `WINERROR.H`. If the data referenced isn't of type `REG_SZ`, `ERROR_INVALID_DATA` is returned. If the method returns `ERROR_MORE_DATA`, *`pnChars`* equals zero, not the required buffer size in bytes. ### Remarks -This method makes use of `RegQueryValueEx` and confirms that the correct type of data is returned. See [RegQueryValueEx](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) for more details. +This method makes use of `RegQueryValueEx` and confirms that the correct type of data is returned. See [`RegQueryValueEx`](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) for more details. > [!IMPORTANT] -> This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. Also, the [RegQueryValueEx](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) function used by this method does not explicitly handle strings which are NULL terminated. Both conditions should be checked for by the calling code. +> This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. Also, the [`RegQueryValueEx`](/windows/win32/api/winreg/nf-winreg-regqueryvalueexw) function used by this method does not explicitly handle strings which are null-terminated. Both conditions should be checked for by the calling code. -## CRegKey::QueryValue +## `CRegKey::QueryValue` -Call this method to retrieve the data for the specified value field of [m_hKey](#m_hkey). Earlier versions of this method are no longer supported and are marked as ATL_DEPRECATED. +Call this method to retrieve the data for the specified value field of [`m_hKey`](#m_hkey). Earlier versions of this method are no longer supported and are marked as `ATL_DEPRECATED`. ``` LONG QueryValue( @@ -665,44 +664,44 @@ ATL_DEPRECATED LONG QueryValue( ### Parameters -*pszValueName*
-Pointer to a null-terminated string containing the name of the value to query. If *pszValueName* is NULL or an empty string, "", the method retrieves the type and data for the key's unnamed or default value, if any. +*`pszValueName`*\ +Pointer to a `NULL`-terminated string containing the name of the value to query. If *`pszValueName`* is `NULL` or an empty string, `""`, the method retrieves the type and data for the key's unnamed or default value, if any. -*pdwType*
-Pointer to a variable that receives a code indicating the type of data stored in the specified value. The *pdwType* parameter can be NULL if the type code is not required. +*`pdwType`*\ +Pointer to a variable that receives a code indicating the type of data stored in the specified value. The *`pdwType`* parameter can be `NULL` if the type code isn't required. -*pData*
-Pointer to a buffer that receives the value's data. This parameter can be NULL if the data is not required. +*`pData`*\ +Pointer to a buffer that receives the value's data. This parameter can be `NULL` if the data isn't required. -*pnBytes*
-Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the *pData* parameter. When the method returns, this variable contains the size of the data copied to *pData.* +*`pnBytes`*\ +Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the *`pData`* parameter. When the method returns, this variable contains the size of the data copied to *`pData`*. -*dwValue*
+*`dwValue`*\ The value field's numerical data. -*lpszValueName*
+*`lpszValueName`*\ Specifies the value field to be queried. -*szValue*
+*`szValue`*\ The value field's string data. -*pdwCount*
-The size of the string data. Its value is initially set to the size of the *szValue* buffer. +*`pdwCount`*\ +The size of the string data. Its value is initially set to the size of the *`szValue`* buffer. ### Return Value -If successful, returns ERROR_SUCCESS; otherwise, a nonzero error code defined in WINERROR.H. +If successful, returns `ERROR_SUCCESS`; otherwise, a nonzero error code defined in `WINERROR.H`. ### Remarks -The two original versions of `QueryValue` are no longer supported and are marked as ATL_DEPRECATED. The compiler will issue a warning if these forms are used. +The two original versions of `QueryValue` are no longer supported and are marked as `ATL_DEPRECATED`. The compiler will issue a warning if these forms are used. -The remaining method calls RegQueryValueEx. +The remaining method calls `RegQueryValueEx`. > [!IMPORTANT] -> This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. Also, the RegQueryValueEx function used by this method does not explicitly handle strings which are NULL terminated. Both conditions should be checked for by the calling code. +> This method allows the caller to specify any registry location, potentially reading data which cannot be trusted. Also, the `RegQueryValueEx` function used by this method does not explicitly handle strings which are null-terminated. Both conditions should be checked for by the calling code. -## CRegKey::RecurseDeleteKey +## `CRegKey::RecurseDeleteKey` Call this method to remove the specified key from the registry and explicitly remove any subkeys. @@ -712,18 +711,18 @@ LONG RecurseDeleteKey(LPCTSTR lpszKey) throw(); ### Parameters -*lpszKey*
-Specifies the name of the key to delete. This name must be a subkey of [m_hKey](#m_hkey). +*`lpszKey`*\ +Specifies the name of the key to delete. This name must be a subkey of [`m_hKey`](#m_hkey). ### Return Value -If successful, returns ERROR_SUCCESS; otherwise, a non-zero error value defined in WINERROR.H. +If successful, returns `ERROR_SUCCESS`; otherwise, a non-zero error value defined in `WINERROR.H`. ### Remarks If the key has subkeys, you must call this method to delete the key. -## CRegKey::SetBinaryValue +## `CRegKey::SetBinaryValue` Call this method to set the binary value of the registry key. @@ -736,26 +735,26 @@ LONG SetBinaryValue( ### Parameters -*pszValueName*
-Pointer to a string containing the name of the value to set. If a value with this name is not already present, the method adds it to the key. +*`pszValueName`*\ +Pointer to a string containing the name of the value to set. If a value with this name isn't already present, the method adds it to the key. -*pValue*
+*`pValue`*\ Pointer to a buffer containing the data to be stored with the specified value name. -*nBytes*
-Specifies the size, in bytes, of the information pointed to by the *pValue* parameter. +*`nBytes`*\ +Specifies the size, in bytes, of the information pointed to by the *`pValue`* parameter. ### Return Value -If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H. +If the method succeeds, the return value is `ERROR_SUCCESS`. If the method fails, the return value is a nonzero error code defined in `WINERROR.H`. ### Remarks -This method uses [RegSetValueEx](/windows/win32/api/winreg/nf-winreg-regsetvalueexw) to write the value to the registry. +This method uses [`RegSetValueEx`](/windows/win32/api/winreg/nf-winreg-regsetvalueexw) to write the value to the registry. -## CRegKey::SetDWORDValue +## `CRegKey::SetDWORDValue` -Call this method to set the DWORD value of the registry key. +Call this method to set the `DWORD` value of the registry key. ``` LONG SetDWORDValue(LPCTSTR pszValueName, DWORD dwValue) throw(); @@ -763,21 +762,21 @@ LONG SetDWORDValue(LPCTSTR pszValueName, DWORD dwValue) throw(); ### Parameters -*pszValueName*
-Pointer to a string containing the name of the value to set. If a value with this name is not already present, the method adds it to the key. +*`pszValueName`*\ +Pointer to a string containing the name of the value to set. If a value with this name isn't already present, the method adds it to the key. -*dwValue*
-The DWORD data to be stored with the specified value name. +*`dwValue`*\ +The `DWORD` data to be stored with the specified value name. ### Return Value -If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H. +If the method succeeds, the return value is `ERROR_SUCCESS`. If the method fails, the return value is a nonzero error code defined in `WINERROR.H`. ### Remarks -This method uses [RegSetValueEx](/windows/win32/api/winreg/nf-winreg-regsetvalueexw) to write the value to the registry. +This method uses [`RegSetValueEx`](/windows/win32/api/winreg/nf-winreg-regsetvalueexw) to write the value to the registry. -## CRegKey::SetGUIDValue +## `CRegKey::SetGUIDValue` Call this method to set the GUID value of the registry key. @@ -787,21 +786,21 @@ LONG SetGUIDValue(LPCTSTR pszValueName, REFGUID guidValue) throw(); ### Parameters -*pszValueName*
-Pointer to a string containing the name of the value to set. If a value with this name is not already present, the method adds it to the key. +*`pszValueName`*\ +Pointer to a string containing the name of the value to set. If a value with this name isn't already present, the method adds it to the key. -*guidValue*
+*`guidValue`*\ Reference to the GUID to be stored with the specified value name. ### Return Value -If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H. +If the method succeeds, the return value is `ERROR_SUCCESS`. If the method fails, the return value is a nonzero error code defined in `WINERROR.H`. ### Remarks -This method makes use of `CRegKey::SetStringValue` and converts the GUID into a string using [StringFromGUID2](/windows/win32/api/combaseapi/nf-combaseapi-stringfromguid2). +This method makes use of `CRegKey::SetStringValue` and converts the GUID into a string using [`StringFromGUID2`](/windows/win32/api/combaseapi/nf-combaseapi-stringfromguid2). -## CRegKey::SetKeyValue +## `CRegKey::SetKeyValue` Call this method to store data in a specified value field of a specified key. @@ -814,24 +813,24 @@ LONG SetKeyValue( ### Parameters -*lpszKeyName*
-Specifies the name of the key to be created or opened. This name must be a subkey of [m_hKey](#m_hkey). +*`lpszKeyName`*\ +Specifies the name of the key to be created or opened. This name must be a subkey of [`m_hKey`](#m_hkey). -*lpszValue*
-Specifies the data to be stored. This parameter must be non-NULL. +*`lpszValue`*\ +Specifies the data to be stored. This parameter must be non-`NULL`. -*lpszValueName*
-Specifies the value field to be set. If a value field with this name does not already exist in the key, it is added. +*`lpszValueName`*\ +Specifies the value field to be set. If a value field with this name doesn't already exist in the key, it's added. ### Return Value -If successful, returns ERROR_SUCCESS; otherwise, a nonzero error code defined in WINERROR.H. +If successful, returns `ERROR_SUCCESS`; otherwise, a nonzero error code defined in `WINERROR.H`. ### Remarks -Call this method to create or open the *lpszKeyName* key and store the *lpszValue* data in the *lpszValueName* value field. +Call this method to create or open the *`lpszKeyName`* key and store the *`lpszValue`* data in the *`lpszValueName`* value field. -## CRegKey::SetKeySecurity +## `CRegKey::SetKeySecurity` Call this method to set the security of the registry key. @@ -841,28 +840,28 @@ LONG SetKeySecurity(SECURITY_INFORMATION si, PSECURITY_DESCRIPTOR psd) throw(); ### Parameters -*si*
+*`si`*\ Specifies the components of the security descriptor to set. The value can be a combination of the following values: |Value|Meaning| |-----------|-------------| -|DACL_SECURITY_INFORMATION|Sets the key's discretionary access-control list (DACL). The key must have WRITE_DAC access, or the calling process must be the object's owner.| -|GROUP_SECURITY_INFORMATION|Sets the key's primary group security identifier (SID). The key must have WRITE_OWNER access, or the calling process must be the object's owner.| -|OWNER_SECURITY_INFORMATION|Sets the key's owner SID. The key must have WRITE_OWNER access, or the calling process must be the object's owner or have the SE_TAKE_OWNERSHIP_NAME privilege enabled.| -|SACL_SECURITY_INFORMATION|Sets the key's system access-control list (SACL). The key must have ACCESS_SYSTEM_SECURITY access. The proper way to get this access is to enable the SE_SECURITY_NAME [privilege](/windows/win32/secauthz/privileges) in the caller's current access token, open the handle for ACCESS_SYSTEM_SECURITY access, and then disable the privilege.| +|`DACL_SECURITY_INFORMATION`|Sets the key's discretionary access-control list (DACL). The key must have `WRITE_DAC` access, or the calling process must be the object's owner.| +|`GROUP_SECURITY_INFORMATION`|Sets the key's primary group security identifier (SID). The key must have `WRITE_OWNER` access, or the calling process must be the object's owner.| +|`OWNER_SECURITY_INFORMATION`|Sets the key's owner SID. The key must have `WRITE_OWNER` access, or the calling process must be the object's owner or have the `SE_TAKE_OWNERSHIP_NAME` privilege enabled.| +|`SACL_SECURITY_INFORMATION`|Sets the key's system access-control list (SACL). The key must have `ACCESS_SYSTEM_SECURITY` access. The proper way to get this access is to enable the `SE_SECURITY_NAME` [privilege](/windows/win32/secauthz/privileges) in the caller's current access token, open the handle for `ACCESS_SYSTEM_SECURITY` access, and then disable the privilege.| -*psd*
-Pointer to a [SECURITY_DESCRIPTOR](/windows/win32/api/winnt/ns-winnt-security_descriptor) structure that specifies the security attributes to set for the specified key. +*`psd`*\ +Pointer to a [`SECURITY_DESCRIPTOR`](/windows/win32/api/winnt/ns-winnt-security_descriptor) structure that specifies the security attributes to set for the specified key. ### Return Value -If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H. +If the method succeeds, the return value is `ERROR_SUCCESS`. If the method fails, the return value is a nonzero error code defined in `WINERROR.H`. ### Remarks -Sets the key's security attributes. See [RegSetKeySecurity](/windows/win32/api/winreg/nf-winreg-regsetkeysecurity) for more details. +Sets the key's security attributes. See [`RegSetKeySecurity`](/windows/win32/api/winreg/nf-winreg-regsetkeysecurity) for more details. -## CRegKey::SetMultiStringValue +## `CRegKey::SetMultiStringValue` Call this method to set the multistring value of the registry key. @@ -872,23 +871,23 @@ LONG SetMultiStringValue(LPCTSTR pszValueName, LPCTSTR pszValue) throw(); ### Parameters -*pszValueName*
-Pointer to a string containing the name of the value to set. If a value with this name is not already present, the method adds it to the key. +*`pszValueName`*\ +Pointer to a string containing the name of the value to set. If a value with this name isn't already present, the method adds it to the key. -*pszValue*
-Pointer to the multistring data to be stored with the specified value name. A multistring is an array of null-terminated strings, terminated by two null characters. +*`pszValue`*\ +Pointer to the multistring data to be stored with the specified value name. A multistring is an array of `NULL`-terminated strings, terminated by two null characters. ### Return Value -If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H. +If the method succeeds, the return value is `ERROR_SUCCESS`. If the method fails, the return value is a nonzero error code defined in `WINERROR.H`. ### Remarks -This method uses [RegSetValueEx](/windows/win32/api/winreg/nf-winreg-regsetvalueexw) to write the value to the registry. +This method uses [`RegSetValueEx`](/windows/win32/api/winreg/nf-winreg-regsetvalueexw) to write the value to the registry. -## CRegKey::SetQWORDValue +## `CRegKey::SetQWORDValue` -Call this method to set the QWORD value of the registry key. +Call this method to set the `QWORD` value of the registry key. ``` LONG SetQWORDValue(LPCTSTR pszValueName, ULONGLONG qwValue) throw(); @@ -896,21 +895,21 @@ LONG SetQWORDValue(LPCTSTR pszValueName, ULONGLONG qwValue) throw(); ### Parameters -*pszValueName*
-Pointer to a string containing the name of the value to set. If a value with this name is not already present, the method adds it to the key. +*`pszValueName`*\ +Pointer to a string containing the name of the value to set. If a value with this name isn't already present, the method adds it to the key. -*qwValue*
-The QWORD data to be stored with the specified value name. +*`qwValue`*\ +The `QWORD` data to be stored with the specified value name. ### Return Value -If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H. +If the method succeeds, the return value is `ERROR_SUCCESS`. If the method fails, the return value is a nonzero error code defined in `WINERROR.H`. ### Remarks -This method uses [RegSetValueEx](/windows/win32/api/winreg/nf-winreg-regsetvalueexw) to write the value to the registry. +This method uses [`RegSetValueEx`](/windows/win32/api/winreg/nf-winreg-regsetvalueexw) to write the value to the registry. -## CRegKey::SetStringValue +## `CRegKey::SetStringValue` Call this method to set the string value of the registry key. @@ -923,26 +922,26 @@ LONG SetStringValue( ### Parameters -*pszValueName*
-Pointer to a string containing the name of the value to set. If a value with this name is not already present, the method adds it to the key. +*`pszValueName`*\ +Pointer to a string containing the name of the value to set. If a value with this name isn't already present, the method adds it to the key. -*pszValue*
+*`pszValue`*\ Pointer to the string data to be stored with the specified value name. -*dwType*
-The type of the string to write to the registry: either REG_SZ (the default) or REG_EXPAND_SZ (for multistrings). +*`dwType`*\ +The type of the string to write to the registry: either `REG_SZ` (the default) or `REG_EXPAND_SZ` (for multistrings). ### Return Value -If the method succeeds, the return value is ERROR_SUCCESS. If the method fails, the return value is a nonzero error code defined in WINERROR.H. +If the method succeeds, the return value is `ERROR_SUCCESS`. If the method fails, the return value is a nonzero error code defined in `WINERROR.H`. ### Remarks -This method uses [RegSetValueEx](/windows/win32/api/winreg/nf-winreg-regsetvalueexw) to write the value to the registry. +This method uses [`RegSetValueEx`](/windows/win32/api/winreg/nf-winreg-regsetvalueexw) to write the value to the registry. -## CRegKey::SetValue +## `CRegKey::SetValue` -Call this method to store data in the specified value field of [m_hKey](#m_hkey). Earlier versions of this method are no longer supported and are marked as ATL_DEPRECATED. +Call this method to store data in the specified value field of [`m_hKey`](#m_hkey). Earlier versions of this method are no longer supported and are marked as `ATL_DEPRECATED`. ``` LONG SetValue( @@ -970,50 +969,50 @@ ATL_DEPRECATED LONG SetValue( ### Parameters -*pszValueName*
-Pointer to a string containing the name of the value to set. If a value with this name is not already present in the key, the method adds it to the key. If *pszValueName* is NULL or an empty string, "", the method sets the type and data for the key's unnamed or default value. +*`pszValueName`*\ +Pointer to a string containing the name of the value to set. If a value with this name isn't already present in the key, the method adds it to the key. If *`pszValueName`* is `NULL` or an empty string, `""`, the method sets the type and data for the key's unnamed or default value. -*dwType*
-Specifies a code indicating the type of data pointed to by the *pValue* parameter. +*`dwType`*\ +Specifies a code indicating the type of data pointed to by the *`pValue`* parameter. -*pValue*
+*`pValue`*\ Pointer to a buffer containing the data to be stored with the specified value name. -*nBytes*
-Specifies the size, in bytes, of the information pointed to by the *pValue* parameter. If the data is of type REG_SZ, REG_EXPAND_SZ, or REG_MULTI_SZ, *nBytes* must include the size of the terminating null character. +*`nBytes`*\ +Specifies the size, in bytes, of the information pointed to by the *`pValue`* parameter. If the data is of type `REG_SZ`, `REG_EXPAND_SZ`, or `REG_MULTI_SZ`, *`nBytes`* must include the size of the terminating null character. -*hKeyParent*
+*`hKeyParent`*\ The handle of an open key. -*lpszKeyName*
-Specifies the name of a key to be created or opened. This name must be a subkey of *hKeyParent*. +*`lpszKeyName`*\ +Specifies the name of a key to be created or opened. This name must be a subkey of *`hKeyParent`*. -*lpszValue*
-Specifies the data to be stored. This parameter must be non-NULL. +*`lpszValue`*\ +Specifies the data to be stored. This parameter must be non-`NULL`. -*lpszValueName*
-Specifies the value field to be set. If a value field with this name does not already exist in the key, it is added. +*`lpszValueName`*\ +Specifies the value field to be set. If a value field with this name doesn't already exist in the key, it's added. -*dwValue*
+*`dwValue`*\ Specifies the data to be stored. -*bMulti*
-If false, indicates the string is of type REG_SZ. If true, indicates the string is a multistring of type REG_MULTI_SZ. +*`bMulti`*\ +If false, indicates the string is of type `REG_SZ`. If true, indicates the string is a multistring of type `REG_MULTI_SZ`. -*nValueLen*
-If *bMulti* is true, *nValueLen* is the length of the *lpszValue* string in characters. If *bMulti* is false, a value of -1 indicates that the method will calculate the length automatically. +*`nValueLen`*\ +If *`bMulti`* is true, *`nValueLen`* is the length of the *`lpszValue`* string in characters. If *`bMulti`* is false, a value of -1 indicates that the method will calculate the length automatically. ### Return Value -If successful, returns ERROR_SUCCESS; otherwise, a nonzero error code defined in WINERROR.H. +If successful, returns `ERROR_SUCCESS`; otherwise, a nonzero error code defined in `WINERROR.H`. ### Remarks -The two original versions of `SetValue` are marked as ATL_DEPRECATED and should no longer be used. The compiler will issue a warning if these forms are used. +The two original versions of `SetValue` are marked as `ATL_DEPRECATED` and should no longer be used. The compiler will issue a warning if these forms are used. -The third method calls [RegSetValueEx](/windows/win32/api/winreg/nf-winreg-regsetvalueexw). +The third method calls [`RegSetValueEx`](/windows/win32/api/winreg/nf-winreg-regsetvalueexw). ## See also -[DCOM Sample](../../overview/visual-cpp-samples.md)
+[DCOM Sample](../../overview/visual-cpp-samples.md)\ [Class Overview](../../atl/atl-class-overview.md) diff --git a/docs/atl/reference/csid-class.md b/docs/atl/reference/csid-class.md index 3306d49395..49be86aa61 100644 --- a/docs/atl/reference/csid-class.md +++ b/docs/atl/reference/csid-class.md @@ -1,79 +1,79 @@ --- -description: "Learn more about: CSid Class" -title: "CSid Class" +description: "Learn more about: CSid class" +title: "CSid class" ms.date: "03/27/2019" f1_keywords: ["CSid", "ATLSECURITY/ATL::CSid", "ATLSECURITY/ATL::CSid::CSidArray", "ATLSECURITY/ATL::CSid::CSid", "ATLSECURITY/ATL::CSid::AccountName", "ATLSECURITY/ATL::CSid::Domain", "ATLSECURITY/ATL::CSid::EqualPrefix", "ATLSECURITY/ATL::CSid::GetLength", "ATLSECURITY/ATL::CSid::GetPSID", "ATLSECURITY/ATL::CSid::GetPSID_IDENTIFIER_AUTHORITY", "ATLSECURITY/ATL::CSid::GetSubAuthority", "ATLSECURITY/ATL::CSid::GetSubAuthorityCount", "ATLSECURITY/ATL::CSid::IsValid", "ATLSECURITY/ATL::CSid::LoadAccount", "ATLSECURITY/ATL::CSid::Sid", "ATLSECURITY/ATL::CSid::SidNameUse"] helpviewer_keywords: ["CSid class"] ms.assetid: be58b7ca-5958-49c3-a833-ca341aaaf753 --- -# CSid Class +# `CSid` class This class is a wrapper for a `SID` (security identifier) structure. > [!IMPORTANT] -> This class and its members cannot be used in applications that execute in the Windows Runtime. +> This class and its members can't be used in applications that execute in the Windows Runtime. ## Syntax -``` -class CSid +```cpp +class CSid; ``` ## Members -### Public Typedefs +### Public typedefs -|Name|Description| -|----------|-----------------| -|[CSid::CSidArray](#csidarray)|An array of `CSid` objects.| +| Name | Description | +|--|--| +| [`CSid::CSidArray`](#csidarray) | An array of `CSid` objects. | -### Public Constructors +### Public constructors -|Name|Description| -|----------|-----------------| -|[CSid::CSid](#csid)|The constructor.| -|[CSid::~CSid](#dtor)|The destructor.| +| Name | Description | +|--|--| +| [`CSid::CSid`](#csid) | The constructor. | +| [`CSid::~CSid`](#dtor) | The destructor. | -### Public Methods +### Public methods -|Name|Description| -|----------|-----------------| -|[CSid::AccountName](#accountname)|Returns the name of the account associated with the `CSid` object.| -|[CSid::Domain](#domain)|Returns the name of the domain associated with the `CSid` object.| -|[CSid::EqualPrefix](#equalprefix)|Tests `SID` (security identifier) prefixes for equality.| -|[CSid::GetLength](#getlength)|Returns the length of the `CSid` object.| -|[CSid::GetPSID](#getpsid)|Returns a pointer to a `SID` structure.| -|[CSid::GetPSID_IDENTIFIER_AUTHORITY](#getpsid_identifier_authority)|Returns a pointer to the `SID_IDENTIFIER_AUTHORITY` structure.| -|[CSid::GetSubAuthority](#getsubauthority)|Returns a specified subauthority in a `SID` structure.| -|[CSid::GetSubAuthorityCount](#getsubauthoritycount)|Returns the subauthority count.| -|[CSid::IsValid](#isvalid)|Tests the `CSid` object for validity.| -|[CSid::LoadAccount](#loadaccount)|Updates the `CSid` object given the account name and domain, or an existing `SID` structure.| -|[CSid::Sid](#sid)|Returns the ID string.| -|[CSid::SidNameUse](#sidnameuse)|Returns a description of the state of the `CSid` object.| +| Name | Description | +|--|--| +| [`CSid::AccountName`](#accountname) | Returns the name of the account associated with the `CSid` object. | +| [`CSid::Domain`](#domain) | Returns the name of the domain associated with the `CSid` object. | +| [`CSid::EqualPrefix`](#equalprefix) | Tests `SID` (security identifier) prefixes for equality. | +| [`CSid::GetLength`](#getlength) | Returns the length of the `CSid` object. | +| [`CSid::GetPSID`](#getpsid) | Returns a pointer to a `SID` structure. | +| [`CSid::GetPSID_IDENTIFIER_AUTHORITY`](#getpsid_identifier_authority) | Returns a pointer to the `SID_IDENTIFIER_AUTHORITY` structure. | +| [`CSid::GetSubAuthority`](#getsubauthority) | Returns a specified subauthority in a `SID` structure. | +| [`CSid::GetSubAuthorityCount`](#getsubauthoritycount) | Returns the subauthority count. | +| [`CSid::IsValid`](#isvalid) | Tests the `CSid` object for validity. | +| [`CSid::LoadAccount`](#loadaccount) | Updates the `CSid` object given the account name and domain, or an existing `SID` structure. | +| [`CSid::Sid`](#sid) | Returns the ID string. | +| [`CSid::SidNameUse`](#sidnameuse) | Returns a description of the state of the `CSid` object. | ### Operators -|Name|Description| -|-|-| -|[operator =](#operator_eq)|Assignment operator.| -|[operator const SID *](#operator_const_sid__star)|Casts a `CSid` object to a pointer to a `SID` structure.| +| Name | Description | +|--|--| +| [`CSid::operator =`](#operator_eq) | Assignment operator. | +| [`CSid::operator const SID *`](#operator_const_sid__star) | Casts a `CSid` object to a pointer to a `SID` structure. | ### Global Operators -|Name|Description| -|-|-| -|[operator ==](#operator_eq_eq)|Tests two security descriptor objects for equality| -|[operator !=](#operator_neq)|Tests two security descriptor objects for inequality| -|[operator \<](#operator_lt)|Compares relative value of two security descriptor objects.| -|[operator >](#operator_gt)|Compares relative value of two security descriptor objects.| -|[operator \<=](#operator_lt__eq)|Compares relative value of two security descriptor objects.| -|[operator >=](#operator_gt__eq)|Compares relative value of two security descriptor objects.| +| Name | Description | +|--|--| +| [`operator ==`](#operator_eq_eq) | Tests two security descriptor objects for equality | +| [`operator !=`](#operator_neq) | Tests two security descriptor objects for inequality | +| [`operator <`](#operator_lt) | Compares relative value of two security descriptor objects. | +| [`operator >`](#operator_gt) | Compares relative value of two security descriptor objects. | +| [`operator <=`](#operator_lt__eq) | Compares relative value of two security descriptor objects. | +| [`operator >=`](#operator_gt__eq) | Compares relative value of two security descriptor objects. | ## Remarks The `SID` structure is a variable-length structure used to uniquely identify users or groups. -Applications should not modify the `SID` structure directly, but instead use the methods provided in this wrapper class. See also [AtlGetOwnerSid](security-global-functions.md#atlgetownersid), [AtlSetGroupSid](security-global-functions.md#atlsetgroupsid), [AtlGetGroupSid](security-global-functions.md#atlgetgroupsid), and [AtlSetOwnerSid](security-global-functions.md#atlsetownersid). +Applications shouldn't modify the `SID` structure directly, but instead use the methods provided in this wrapper class. See also [`AtlGetOwnerSid`](security-global-functions.md#atlgetownersid), [`AtlSetGroupSid`](security-global-functions.md#atlsetgroupsid), [`AtlGetGroupSid`](security-global-functions.md#atlgetgroupsid), and [`AtlSetOwnerSid`](security-global-functions.md#atlsetownersid). For an introduction to the access control model in Windows, see [Access Control](/windows/win32/SecAuthZ/access-control) in the Windows SDK. @@ -81,29 +81,29 @@ For an introduction to the access control model in Windows, see [Access Control] **Header:** atlsecurity.h -## CSid::AccountName +## `CSid::AccountName` Returns the name of the account associated with the `CSid` object. -``` +```cpp LPCTSTR AccountName() const throw(...); ``` -### Return Value +### Return value -Returns the LPCTSTR pointing to the name of the account. +Returns the `LPCTSTR` pointing to the name of the account. ### Remarks -This method attempts to find a name for the specified `SID` (security identifier). For full details, see [LookupAccountSid](/windows/win32/api/winbase/nf-winbase-lookupaccountsidw). +This method attempts to find a name for the specified `SID` (security identifier). For full details, see [`LookupAccountSid`](/windows/win32/api/winbase/nf-winbase-lookupaccountsidw). -If no account name for the `SID` can be found, `AccountName` returns an empty string. This can occur if a network timeout prevents this method from finding the name. It also occurs for security identifiers with no corresponding account name, such as an `SID` that identifies a sign-in session. +If no account name for the `SID` can be found, `AccountName` returns an empty string. This result can occur if a network timeout prevents this method from finding the name. It also occurs for security identifiers with no corresponding account name, such as an `SID` that identifies a sign-in session. -## CSid::CSid +## `CSid::CSid` The constructor. -``` +```cpp CSid() throw(); CSid(const SID& rhs) throw(...); CSid(const CSid& rhs) throw(...); @@ -124,35 +124,35 @@ explicit CSid( ### Parameters -*rhs*
+*`rhs`*\ An existing `CSid` object or `SID` (security identifier) structure. -*IdentifierAuthority*
+*`IdentifierAuthority`*\ The authority. -*nSubAuthorityCount*
+*`nSubAuthorityCount`*\ The subauthority count. -*pszAccountName*
+*`pszAccountName`*\ The account name. -*pszSystem*
+*`pszSystem`*\ The system name. This string can be the name of a remote computer. If this string is NULL, the local system is used instead. -*pSid*
+*`pSid`*\ A pointer to a `SID` structure. ### Remarks -The constructor initializes the `CSid` object, setting an internal data member to *SidTypeInvalid*, or by copying the settings from an existing `CSid`, `SID`, or existing account. +The constructor initializes the `CSid` object, setting an internal data member to *`SidTypeInvalid`*, or by copying the settings from an existing `CSid`, `SID`, or existing account. -If initialization fails, the constructor will throw a [CAtlException Class](../../atl/reference/catlexception-class.md). +If initialization fails, the constructor will throw a [`CAtlException` Class](../../atl/reference/catlexception-class.md). -## CSid::~CSid +## `CSid::~CSid` The destructor. -``` +```cpp virtual ~CSid() throw(); ``` @@ -160,166 +160,166 @@ virtual ~CSid() throw(); The destructor frees any resources acquired by the object. -## CSid::CSidArray +## `CSid::CSidArray` -An array of [CSid](../../atl/reference/csid-class.md) objects. +An array of [`CSid`](../../atl/reference/csid-class.md) objects. -``` +```cpp typedef CAtlArray CSidArray; ``` ### Remarks -This typedef specifies the array type that can be used to retrieve security identifiers from an ACL (access-control list). See [CAcl::GetAclEntries](../../atl/reference/cacl-class.md#getaclentries). +This typedef specifies the array type that can be used to retrieve security identifiers from an ACL (access-control list). See [`CAcl::GetAclEntries`](../../atl/reference/cacl-class.md#getaclentries). -## CSid::Domain +## `CSid::Domain` Returns the name of the domain associated with the `CSid` object. -``` +```cpp LPCTSTR Domain() const throw(...); ``` -### Return Value +### Return value Returns the `LPCTSTR` pointing to the domain. ### Remarks -This method attempts to find a name for the specified `SID` (security identifier). For full details, see [LookupAccountSid](/windows/win32/api/winbase/nf-winbase-lookupaccountsidw). +This method attempts to find a name for the specified `SID` (security identifier). For full details, see [`LookupAccountSid`](/windows/win32/api/winbase/nf-winbase-lookupaccountsidw). -If no account name for the `SID` can be found, `Domain` returns the domain as an empty string. This can occur if a network timeout prevents this method from finding the name. It also occurs for security identifiers with no corresponding account name, such as an `SID` that identifies a sign-in session. +If no account name for the `SID` can be found, `Domain` returns the domain as an empty string. This result can occur if a network timeout prevents this method from finding the name. It also occurs for security identifiers with no corresponding account name, such as an `SID` that identifies a sign-in session. -## CSid::EqualPrefix +## `CSid::EqualPrefix` Tests `SID` (security identifier) prefixes for equality. -``` +```cpp bool EqualPrefix(const SID& rhs) const throw(); bool EqualPrefix(const CSid& rhs) const throw(); ``` ### Parameters -*rhs*
+*`rhs`*\ The `SID` (security identifier) structure or `CSid` object to compare. -### Return Value +### Return value -Returns TRUE on success, FALSE on failure. +Returns `TRUE` on success, `FALSE` on failure. ### Remarks -See [EqualPrefixSid](/windows/win32/api/securitybaseapi/nf-securitybaseapi-equalprefixsid) in the Windows SDK for more details. +For more information, see [`EqualPrefixSid`](/windows/win32/api/securitybaseapi/nf-securitybaseapi-equalprefixsid). -## CSid::GetLength +## `CSid::GetLength` Returns the length of the `CSid` object. -``` +```cpp UINT GetLength() const throw(); ``` -### Return Value +### Return value Returns the length in bytes of the `CSid` object. ### Remarks -If the `CSid` structure is not valid, the return value is undefined. Before calling `GetLength`, use the [CSid::IsValid](#isvalid) member function to verify that `CSid` is valid. +If the `CSid` structure isn't valid, the return value is undefined. Before calling `GetLength`, use the [`CSid::IsValid`](#isvalid) member function to verify that `CSid` is valid. > [!NOTE] -> Under debug builds the function will cause an ASSERT if the `CSid` object is not valid. +> Under debug builds the function will cause an ASSERT if the `CSid` object isn't valid. -## CSid::GetPSID +## `CSid::GetPSID` Returns a pointer to a `SID` (security identifier) structure. -``` +```cpp const SID* GetPSID() const throw(...); ``` -### Return Value +### Return value Returns the address of the `CSid` object's underlying `SID` structure. -## CSid::GetPSID_IDENTIFIER_AUTHORITY +## `CSid::GetPSID_IDENTIFIER_AUTHORITY` Returns a pointer to the `SID_IDENTIFIER_AUTHORITY` structure. -``` +```cpp const SID_IDENTIFIER_AUTHORITY* GetPSID_IDENTIFIER_AUTHORITY() const throw(); ``` -### Return Value +### Return value -If the method succeeds, it returns the address of the `SID_IDENTIFIER_AUTHORITY` structure. If it fails, the return value is undefined. Failure may occur if the `CSid` object is not valid, in which case the [CSid::IsValid](#isvalid) method returns FALSE. The function `GetLastError` can be called for extended error information. +If the method succeeds, it returns the address of the `SID_IDENTIFIER_AUTHORITY` structure. If it fails, the return value is undefined. Failure may occur if the `CSid` object isn't valid, in which case the [`CSid::IsValid`](#isvalid) method returns `FALSE`. The function `GetLastError` can be called for extended error information. > [!NOTE] -> Under debug builds the function will cause an ASSERT if the `CSid` object is not valid. +> Under debug builds the function will cause an ASSERT if the `CSid` object isn't valid. -## CSid::GetSubAuthority +## `CSid::GetSubAuthority` Returns a specified subauthority in a `SID` (security identifier) structure. -``` +```cpp DWORD GetSubAuthority(DWORD nSubAuthority) const throw(); ``` ### Parameters -*nSubAuthority*
+*`nSubAuthority`*\ The subauthority. -### Return Value +### Return value -Returns the subauthority referenced by *nSubAuthority.* The subauthority value is a relative identifier (RID). +Returns the subauthority referenced by *`nSubAuthority`*. The subauthority value is a relative identifier (RID). ### Remarks -The *nSubAuthority* parameter specifies an index value identifying the subauthority array element the method will return. The method performs no validation tests on this value. An application can call [CSid::GetSubAuthorityCount](#getsubauthoritycount) to discover the range of acceptable values. +The *`nSubAuthority`* parameter specifies an index value identifying the subauthority array element the method will return. The method performs no validation tests on this value. An application can call [`CSid::GetSubAuthorityCount`](#getsubauthoritycount) to discover the range of acceptable values. > [!NOTE] -> Under debug builds the function will cause an ASSERT if the `CSid` object is not valid. +> Under debug builds the function will cause an ASSERT if the `CSid` object isn't valid. -## CSid::GetSubAuthorityCount +## `CSid::GetSubAuthorityCount` Returns the subauthority count. -``` +```cpp UCHAR GetSubAuthorityCount() const throw(); ``` -### Return Value +### Return value If the method succeeds, the return value is the subauthority count. If the method fails, the return value is undefined. The method fails if the `CSid` object is invalid. To get extended error information, call `GetLastError`. > [!NOTE] -> Under debug builds the function will cause an ASSERT if the `CSid` object is not valid. +> Under debug builds the function will cause an ASSERT if the `CSid` object isn't valid. -## CSid::IsValid +## `CSid::IsValid` Tests the `CSid` object for validity. -``` +```cpp bool IsValid() const throw(); ``` -### Return Value +### Return value -Returns TRUE if the `CSid` object is valid, FALSE if not. There is no extended error information for this method; do not call `GetLastError`. +Returns `TRUE` if the `CSid` object is valid, `FALSE` if not. There's no extended error information for this method; don't call `GetLastError`. ### Remarks The `IsValid` method validates the `CSid` object by verifying that the revision number is within a known range and that the number of subauthorities is less than the maximum. -## CSid::LoadAccount +## `CSid::LoadAccount` -Updates the `CSid` object given the account name and domain, or an existing SID (security identifier) structure. +Updates the `CSid` object given the account name and domain, or an existing `SID` (security identifier) structure. -``` +```cpp bool LoadAccount( LPCTSTR pszAccountName, LPCTSTR pszSystem = NULL) throw(...); @@ -331,46 +331,46 @@ bool LoadAccount( ### Parameters -*pszAccountName*
+*`pszAccountName`*\ The account name. -*pszSystem*
+*`pszSystem`*\ The system name. This string can be the name of a remote computer. If this string is NULL, the local system is used instead. -*pSid*
-A pointer to a [SID](/windows/win32/api/winnt/ns-winnt-sid) structure. +*`pSid`*\ +A pointer to a [`SID`](/windows/win32/api/winnt/ns-winnt-sid) structure. -### Return Value +### Return value -Returns TRUE on success, FALSE on failure. To get extended error information, call `GetLastError`. +Returns `TRUE` on success, `FALSE` on failure. To get extended error information, call `GetLastError`. ### Remarks -`LoadAccount` attempts to find a security identifier for the specified name. See [LookupAccountSid](/windows/win32/api/winbase/nf-winbase-lookupaccountsidw) for more details. +`LoadAccount` attempts to find a security identifier for the specified name. For more information, see [`LookupAccountSid`](/windows/win32/api/winbase/nf-winbase-lookupaccountsidw). -## CSid::operator = +## `CSid::operator =` Assignment operator. -``` +```cpp CSid& operator= (const CSid& rhs) throw(...); CSid& operator= (const SID& rhs) throw(...); ``` ### Parameters -*rhs*
+*`rhs`*\ The `SID` (security identifier) or `CSid` to assign to the `CSid` object. -### Return Value +### Return value Returns a reference to the updated `CSid` object. -## CSid::operator == +## `operator ==` Tests two security descriptor objects for equality. -``` +```cpp bool operator==( const CSid& lhs, const CSid& rhs) throw(); @@ -378,21 +378,21 @@ bool operator==( ### Parameters -*lhs*
-The `SID` (security identifier) or `CSid` that appears on the left side of the == operator. +*`lhs`*\ +The `SID` (security identifier) or `CSid` that appears on the left side of the **`==`** operator. -*rhs*
-The `SID` (security identifier) or `CSid` that appears on the right side of the == operator. +*`rhs`*\ +The `SID` (security identifier) or `CSid` that appears on the right side of the **`==`** operator. -### Return Value +### Return value -TRUE if the security descriptors are equal, otherwise FALSE. +`TRUE` if the security descriptors are equal, otherwise `FALSE`. -## CSid::operator != +## `operator !=` Tests two security descriptor objects for inequality. -``` +```cpp bool operator!=( const CSid& lhs, const CSid& rhs) throw(); @@ -400,21 +400,21 @@ bool operator!=( ### Parameters -*lhs*
-The `SID` (security identifier) or `CSid` that appears on the left side of the != operator. +*`lhs`*\ +The `SID` (security identifier) or `CSid` that appears on the left side of the **`!=`** operator. -*rhs*
-The `SID` (security identifier) or `CSid` that appears on the right side of the != operator. +*`rhs`*\ +The `SID` (security identifier) or `CSid` that appears on the right side of the **`!=`** operator. -### Return Value +### Return value -TRUE if the security descriptors are not equal, otherwise FALSE. +`TRUE` if the security descriptors aren't equal, otherwise `FALSE`. -## CSid::operator < +## `operator <` Compares relative value of two security descriptor objects. -``` +```cpp bool operator<( const CSid& lhs, const CSid& rhs) throw(); @@ -422,21 +422,21 @@ bool operator<( ### Parameters -*lhs*
-The `SID` (security identifier) or `CSid` that appears on the left side of the != operator. +*`lhs`*\ +The `SID` (security identifier) or `CSid` that appears on the left side of the **`<`** operator. -*rhs*
-The `SID` (security identifier) or `CSid` that appears on the right side of the != operator. +*`rhs`*\ +The `SID` (security identifier) or `CSid` that appears on the right side of the **`<`** operator. -### Return Value +### Return value -TRUE if *lhs* is less than *rhs*, otherwise FALSE. +`TRUE` if *`lhs`* is less than *`rhs`*, otherwise `FALSE`. -## CSid::operator <= +## `operator <=` Compares relative value of two security descriptor objects. -``` +```cpp bool operator<=( const CSid& lhs, const CSid& rhs) throw(); @@ -444,21 +444,21 @@ bool operator<=( ### Parameters -*lhs*
-The `SID` (security identifier) or `CSid` that appears on the left side of the != operator. +*`lhs`*\ +The `SID` (security identifier) or `CSid` that appears on the left side of the **`<=`** operator. -*rhs*
-The `SID` (security identifier) or `CSid` that appears on the right side of the != operator. +*`rhs`*\ +The `SID` (security identifier) or `CSid` that appears on the right side of the **`<=`** operator. -### Return Value +### Return value -TRUE if *lhs* is less than or equal to *rhs*, otherwise FALSE. +`TRUE` if *`lhs`* is less than or equal to *`rhs`*, otherwise `FALSE`. -## CSid::operator > +## `operator >` Compares relative value of two security descriptor objects. -``` +```cpp bool operator>( const CSid& lhs, const CSid& rhs) throw(); @@ -466,21 +466,21 @@ bool operator>( ### Parameters -*lhs*
-The `SID` (security identifier) or `CSid` that appears on the left side of the != operator. +*`lhs`*\ +The `SID` (security identifier) or `CSid` that appears on the left side of the **`>`** operator. -*rhs*
-The `SID` (security identifier) or `CSid` that appears on the right side of the != operator. +*`rhs`*\ +The `SID` (security identifier) or `CSid` that appears on the right side of the **`>`** operator. -### Return Value +### Return value -TRUE if *lhs* is greater than *rhs*, otherwise FALSE. +`TRUE` if *`lhs`* is greater than *`rhs`*, otherwise `FALSE`. -## CSid::operator >= +## `operator >=` Compares relative value of two security descriptor objects. -``` +```cpp bool operator>=( const CSid& lhs, const CSid& rhs) throw()); @@ -488,71 +488,71 @@ bool operator>=( ### Parameters -*lhs*
-The `SID` (security identifier) or `CSid` that appears on the left side of the != operator. +*`lhs`*\ +The `SID` (security identifier) or `CSid` that appears on the left side of the **`>=`** operator. -*rhs*
-The `SID` (security identifier) or `CSid` that appears on the right side of the != operator. +*`rhs`*\ +The `SID` (security identifier) or `CSid` that appears on the right side of the **`>=`** operator. -### Return Value +### Return value -TRUE if *lhs* is greater than or equal to *rhs*, otherwise FALSE. +`TRUE` if *`lhs`* is greater than or equal to *`rhs`*, otherwise `FALSE`. -## CSid::operator const SID \* +## `CSid::operator const SID *` Casts a `CSid` object to a pointer to a `SID` (security identifier) structure. -``` -operator const SID *() const throw(...); +```cpp +operator const SID *() const; ``` ### Remarks Returns the address of the `SID` structure. -## CSid::Sid +## `CSid::Sid` Returns the `SID` (security identifier) structure as a string. -``` +```cpp LPCTSTR Sid() const throw(...); ``` -### Return Value +### Return value -Returns the `SID` structure as a string in a format suitable for display, storage, or transmission. Equivalent to [ConvertSidToStringSid](/windows/win32/api/sddl/nf-sddl-convertsidtostringsidw). +Returns the `SID` structure as a string in a format suitable for display, storage, or transmission. Equivalent to [`ConvertSidToStringSid`](/windows/win32/api/sddl/nf-sddl-convertsidtostringsidw). -## CSid::SidNameUse +## `CSid::SidNameUse` Returns a description of the state of the `CSid` object. -``` +```cpp SID_NAME_USE SidNameUse() const throw(); ``` -### Return Value +### Return value Returns the value of the data member that stores a value describing the state of the `CSid` object. -|Value|Description| -|-----------|-----------------| -|SidTypeUser|Indicates a user `SID` (security identifier).| -|SidTypeGroup|Indicates a group `SID`.| -|SidTypeDomain|Indicates a domain `SID`.| -|SidTypeAlias|Indicates an alias `SID`.| -|SidTypeWellKnownGroup|Indicates a `SID` for a well-known group.| -|SidTypeDeletedAccount|Indicates a `SID` for a deleted account.| -|SidTypeInvalid|Indicates an invalid `SID`.| -|SidTypeUnknown|Indicates an unknown `SID` type.| -|SidTypeComputer|Indicates a `SID` for a computer.| +| Value | Description | +|--|--| +| SidTypeUser | Indicates a user `SID` (security identifier). | +| SidTypeGroup | Indicates a group `SID`. | +| SidTypeDomain | Indicates a domain `SID`. | +| SidTypeAlias | Indicates an alias `SID`. | +| SidTypeWellKnownGroup | Indicates a `SID` for a well-known group. | +| SidTypeDeletedAccount | Indicates a `SID` for a deleted account. | +| SidTypeInvalid | Indicates an invalid `SID`. | +| SidTypeUnknown | Indicates an unknown `SID` type. | +| SidTypeComputer | Indicates a `SID` for a computer. | ### Remarks -Call [CSid::LoadAccount](#loadaccount) to update the `CSid` object before calling `SidNameUse` to return its state. `SidNameUse` does not change the state of the object (by calling to `LookupAccountName` or `LookupAccountSid`), but only returns the current state. +Call [`CSid::LoadAccount`](#loadaccount) to update the `CSid` object before calling `SidNameUse` to return its state. `SidNameUse` doesn't change the state of the object (by calling to `LookupAccountName` or `LookupAccountSid`), but only returns the current state. ## See also -[Security Sample](../../overview/visual-cpp-samples.md)
-[Class Overview](../../atl/atl-class-overview.md)
-[Security Global Functions](../../atl/reference/security-global-functions.md)
+[Security sample](../../overview/visual-cpp-samples.md)\ +[Class overview](../../atl/atl-class-overview.md)\ +[Security global functions](../../atl/reference/security-global-functions.md)\ [Operators](../../atl/reference/atl-operators.md) diff --git a/docs/atl/reference/csimplearray-class.md b/docs/atl/reference/csimplearray-class.md index b79b7e57ab..12a7cd1332 100644 --- a/docs/atl/reference/csimplearray-class.md +++ b/docs/atl/reference/csimplearray-class.md @@ -252,7 +252,7 @@ Removes all elements currently stored in the array. Removes the specified element from the array. ``` -BOOL RemoveAtint nIndex); +BOOL RemoveAt(int nIndex); ``` ### Parameters diff --git a/docs/atl/reference/cstockpropimpl-class.md b/docs/atl/reference/cstockpropimpl-class.md index 29b1619156..1f4959941f 100644 --- a/docs/atl/reference/cstockpropimpl-class.md +++ b/docs/atl/reference/cstockpropimpl-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CStockPropImpl Class" title: "CStockPropImpl Class" +description: "Learn more about: CStockPropImpl Class" ms.date: "05/06/2019" f1_keywords: ["CStockPropImpl", "ATLCTL/ATL::CStockPropImpl", "ATLCTL/ATL::get_Appearance", "ATLCTL/ATL::get_AutoSize", "ATLCTL/ATL::get_BackColor", "ATLCTL/ATL::get_BackStyle", "ATLCTL/ATL::get_BorderColor", "ATLCTL/ATL::get_BorderStyle", "ATLCTL/ATL::get_BorderVisible", "ATLCTL/ATL::get_BorderWidth", "ATLCTL/ATL::get_Caption", "ATLCTL/ATL::get_DrawMode", "ATLCTL/ATL::get_DrawStyle", "ATLCTL/ATL::get_DrawWidth", "ATLCTL/ATL::get_Enabled", "ATLCTL/ATL::get_FillColor", "ATLCTL/ATL::get_FillStyle", "ATLCTL/ATL::get_Font", "ATLCTL/ATL::get_ForeColor", "ATLCTL/ATL::get_HWND", "ATLCTL/ATL::get_MouseIcon", "ATLCTL/ATL::get_MousePointer", "ATLCTL/ATL::get_Picture", "ATLCTL/ATL::get_ReadyState", "ATLCTL/ATL::get_TabStop", "ATLCTL/ATL::get_Text", "ATLCTL/ATL::getvalid", "ATLCTL/ATL::get_Window", "ATLCTL/ATL::put_Appearance", "ATLCTL/ATL::put_AutoSize", "ATLCTL/ATL::put_BackColor", "ATLCTL/ATL::put_BackStyle", "ATLCTL/ATL::put_BorderColor", "ATLCTL/ATL::put_BorderStyle", "ATLCTL/ATL::put_BorderVisible", "ATLCTL/ATL::put_BorderWidth", "ATLCTL/ATL::put_Caption", "ATLCTL/ATL::put_DrawMode", "ATLCTL/ATL::put_DrawStyle", "ATLCTL/ATL::put_DrawWidth", "ATLCTL/ATL::put_Enabled", "ATLCTL/ATL::put_FillColor", "ATLCTL/ATL::put_FillStyle", "ATLCTL/ATL::put_Font", "ATLCTL/ATL::put_ForeColor", "ATLCTL/ATL::put_HWND", "ATLCTL/ATL::put_MouseIcon", "ATLCTL/ATL::put_MousePointer", "ATLCTL/ATL::put_Picture", "ATLCTL/ATL::put_ReadyState", "ATLCTL/ATL::put_TabStop", "ATLCTL/ATL::put_Text", "ATLCTL/ATL::putvalid", "ATLCTL/ATL::put_Window", "ATLCTL/ATL::putref_Font", "ATLCTL/ATL::putref_MouseIcon", "ATLCTL/ATL::putref_Picture"] helpviewer_keywords: ["CStockPropImpl class", "controls [ATL], stock properties", "stock properties, ATL controls"] -ms.assetid: 45f11d7d-6580-4a0e-872d-3bc8b836cfda --- # CStockPropImpl Class @@ -607,7 +606,7 @@ Returns S_OK on success, or an error HRESULT on failure. Call this method to set the value of flag that indicates if the control cannot be any other size. ``` -HRESULT STDMETHODCALLTYPE put_AutoSize(VARIANT_BOOL bAutoSize,); +HRESULT STDMETHODCALLTYPE put_AutoSize(VARIANT_BOOL bAutoSize); ``` ### Parameters @@ -1100,5 +1099,5 @@ The same as [CStockPropImpl::put_Picture](#put_picture), but with a reference co ## See also -[Class Overview](../../atl/atl-class-overview.md)
+[Class Overview](../../atl/atl-class-overview.md)\ [IDispatchImpl Class](../../atl/reference/idispatchimpl-class.md) diff --git a/docs/atl/reference/cthreadpool-class.md b/docs/atl/reference/cthreadpool-class.md index e5834d8409..0cca6b473f 100644 --- a/docs/atl/reference/cthreadpool-class.md +++ b/docs/atl/reference/cthreadpool-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CThreadPool Class" title: "CThreadPool Class" -ms.date: "11/04/2016" +description: "Learn more about: CThreadPool Class" +ms.date: 11/04/2016 f1_keywords: ["CThreadPool", "ATLUTIL/ATL::CThreadPool", "ATLUTIL/ATL::CThreadPool::CThreadPool", "ATLUTIL/ATL::CThreadPool::AddRef", "ATLUTIL/ATL::CThreadPool::GetNumThreads", "ATLUTIL/ATL::CThreadPool::GetQueueHandle", "ATLUTIL/ATL::CThreadPool::GetSize", "ATLUTIL/ATL::CThreadPool::GetTimeout", "ATLUTIL/ATL::CThreadPool::Initialize", "ATLUTIL/ATL::CThreadPool::QueryInterface", "ATLUTIL/ATL::CThreadPool::QueueRequest", "ATLUTIL/ATL::CThreadPool::Release", "ATLUTIL/ATL::CThreadPool::SetSize", "ATLUTIL/ATL::CThreadPool::SetTimeout", "ATLUTIL/ATL::CThreadPool::Shutdown"] helpviewer_keywords: ["CThreadPool class"] -ms.assetid: 06683718-01b9-413c-9481-2dc1734ec70f --- # CThreadPool Class @@ -265,7 +264,7 @@ This class does not implement lifetime control using reference counting. Call this method to set the number of threads in the pool. ``` -HRESULT STDMETHODCALLTYPE SetSizeint nNumThreads) throw(); +HRESULT STDMETHODCALLTYPE SetSize(int nNumThreads) throw(); ``` ### Parameters diff --git a/docs/atl/reference/cw2aex-class.md b/docs/atl/reference/cw2aex-class.md index 0be05310ba..9029cccbe7 100644 --- a/docs/atl/reference/cw2aex-class.md +++ b/docs/atl/reference/cw2aex-class.md @@ -4,11 +4,10 @@ title: "CW2AEX Class" ms.date: "11/04/2016" f1_keywords: ["CW2AEX", "ATLCONV/ATL::CW2AEX", "ATLCONV/ATL::CW2AEX::CW2AEX", "ATLCONV/ATL::CW2AEX::m_psz", "ATLCONV/ATL::CW2AEX::m_szBuffer"] helpviewer_keywords: ["CW2AEX class"] -ms.assetid: 44dc2cf5-dd30-440b-a9b9-b21b43f49843 --- -# CW2AEX Class +# `CW2AEX` Class -This class is used by the string conversion macros CT2AEX, CW2TEX, CW2CTEX, and CT2CAEX, and the typedef CW2A. +This class is used by the string conversion macros `CT2AEX`, `CW2TEX`, `CW2CTEX`, and `CT2CAEX`, and the typedef `CW2A`. > [!IMPORTANT] > This class and its members cannot be used in applications that execute in the Windows Runtime. @@ -22,7 +21,7 @@ class CW2AEX #### Parameters -*t_nBufferLength*
+*`t_nBufferLength`*\ The size of the buffer used in the translation process. The default length is 128 bytes. ## Members @@ -31,8 +30,8 @@ The size of the buffer used in the translation process. The default length is 12 |Name|Description| |----------|-----------------| -|[CW2AEX::CW2AEX](#cw2aex)|The constructor.| -|[CW2AEX::~CW2AEX](#dtor)|The destructor.| +|[`CW2AEX::CW2AEX`](#cw2aex)|The constructor.| +|[`CW2AEX::~CW2AEX`](#dtor)|The destructor.| ### Public Operators @@ -44,32 +43,32 @@ The size of the buffer used in the translation process. The default length is 12 |Name|Description| |----------|-----------------| -|[CW2AEX::m_psz](#m_psz)|The data member that stores the source string.| -|[CW2AEX::m_szBuffer](#m_szbuffer)|The static buffer, used to store the converted string.| +|[`CW2AEX::m_psz`](#m_psz)|The data member that stores the source string.| +|[`CW2AEX::m_szBuffer`](#m_szbuffer)|The static buffer, used to store the converted string.| ## Remarks -Unless extra functionality is required, use CT2AEX, CW2TEX, CW2CTEX, CT2CAEX, or CW2A in your code. +Unless extra functionality is required, use `CT2AEX`, `CW2TEX`, `CW2CTEX`, `CT2CAEX`, or `CW2A` in your code. -This class contains a fixed-size static buffer which is used to store the result of the conversion. If the result is too large to fit into the static buffer, the class allocates memory using **malloc**, freeing the memory when the object goes out of scope. This ensures that, unlike text conversion macros available in previous versions of ATL, this class is safe to use in loops and that it won't overflow the stack. +This class contains a fixed-size static buffer that is used to store the result of the conversion. If the result is too large to fit into the static buffer, the class allocates memory using **`malloc`**, freeing the memory when the object goes out of scope. This ensures that, unlike text conversion macros available in previous versions of ATL, this class is safe to use in loops and that it won't overflow the stack. -If the class tries to allocate memory on the heap and fails, it will call `AtlThrow` with an argument of E_OUTOFMEMORY. +If the class tries to allocate memory on the heap and fails, it will call `AtlThrow` with an argument of `E_OUTOFMEMORY`. By default, the ATL conversion classes and macros use the current thread's ANSI code page for the conversion. If you want to override that behavior for a specific conversion, specify the code page as the second parameter to the constructor for the class. The following macros are based on this class: -- CT2AEX +- `CT2AEX` -- CW2TEX +- `CW2TEX` -- CW2CTEX +- `CW2CTEX` -- CT2CAEX +- `CT2CAEX` The following typedef is based on this class: -- CW2A +- `CW2A` For a discussion of these text conversion macros, see [ATL and MFC String Conversion Macros](string-conversion-macros.md). @@ -79,9 +78,9 @@ See [ATL and MFC String Conversion Macros](string-conversion-macros.md) for an e ## Requirements -**Header:** atlconv.h +**Header:** `atlconv.h` -## CW2AEX::CW2AEX +## `CW2AEX::CW2AEX` The constructor. @@ -92,17 +91,17 @@ CW2AEX(LPCWSTR psz) throw(...); ### Parameters -*psz*
+*`psz`*\ The text string to be converted. -*nCodePage*
-The code page used to perform the conversion. See the code page parameter discussion for the Windows SDK function [MultiByteToWideChar](/windows/win32/api/stringapiset/nf-stringapiset-multibytetowidechar) for more details. +*`nCodePage`*\ +The code page used to perform the conversion. See the code page parameter discussion for the Windows SDK function [`MultiByteToWideChar`](/windows/win32/api/stringapiset/nf-stringapiset-multibytetowidechar) for more details. ### Remarks Allocates the buffer used in the translation process. -## CW2AEX::~CW2AEX +## `CW2AEX::~CW2AEX` The destructor. @@ -114,7 +113,7 @@ The destructor. Frees the allocated buffer. -## CW2AEX::m_psz +## `CW2AEX::m_psz` The data member that stores the source string. @@ -122,7 +121,7 @@ The data member that stores the source string. LPSTR m_psz; ``` -## CW2AEX::m_szBuffer +## `CW2AEX::m_szBuffer` The static buffer, used to store the converted string. @@ -130,7 +129,7 @@ The static buffer, used to store the converted string. char m_szBuffer[t_nBufferLength]; ``` -## CW2AEX::operator LPSTR +## `CW2AEX::operator LPSTR` Conversion operator. @@ -140,13 +139,13 @@ operator LPSTR() const throw(); ### Return Value -Returns the text string as type LPSTR. +Returns the text string as type `LPSTR`. ## See also -[CA2AEX Class](../../atl/reference/ca2aex-class.md)
-[CA2CAEX Class](../../atl/reference/ca2caex-class.md)
-[CA2WEX Class](../../atl/reference/ca2wex-class.md)
-[CW2CWEX Class](../../atl/reference/cw2cwex-class.md)
-[CW2WEX Class](../../atl/reference/cw2wex-class.md)
+[`CA2AEX` Class](../../atl/reference/ca2aex-class.md)\ +[`CA2CAEX` Class](../../atl/reference/ca2caex-class.md)\ +[`CA2WEX` Class](../../atl/reference/ca2wex-class.md)\ +[`CW2CWEX` Class](../../atl/reference/cw2cwex-class.md)\ +[`CW2WEX` Class](../../atl/reference/cw2wex-class.md)\ [Class Overview](../../atl/atl-class-overview.md) diff --git a/docs/atl/reference/cw2wex-class.md b/docs/atl/reference/cw2wex-class.md index 3c0cfb0946..d5c15f69f2 100644 --- a/docs/atl/reference/cw2wex-class.md +++ b/docs/atl/reference/cw2wex-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CW2WEX Class" title: "CW2WEX Class" +description: "Learn more about: CW2WEX Class" ms.date: "11/04/2016" f1_keywords: ["CW2WEX", "ATLCONV/ATL::CW2WEX", "ATLCONV/ATL::CW2WEX::CW2WEX", "ATLCONV/ATL::CW2WEX::m_psz", "ATLCONV/ATL::CW2WEX::m_szBuffer"] helpviewer_keywords: ["CW2WEX class"] -ms.assetid: 46262e56-e0d2-41fe-855b-0b67ecc8fcd7 --- # CW2WEX Class @@ -100,7 +99,7 @@ Creates the buffer required for the translation. ## CW2WEX::~CW2WEX -The destructor.. +The destructor. ``` ~CW2WEX() throw(); @@ -140,9 +139,9 @@ Returns the text string as type LPWSTR. ## See also -[CA2AEX Class](../../atl/reference/ca2aex-class.md)
-[CA2CAEX Class](../../atl/reference/ca2caex-class.md)
-[CA2WEX Class](../../atl/reference/ca2wex-class.md)
-[CW2AEX Class](../../atl/reference/cw2aex-class.md)
-[CW2CWEX Class](../../atl/reference/cw2cwex-class.md)
+[CA2AEX Class](../../atl/reference/ca2aex-class.md)\ +[CA2CAEX Class](../../atl/reference/ca2caex-class.md)\ +[CA2WEX Class](../../atl/reference/ca2wex-class.md)\ +[CW2AEX Class](../../atl/reference/cw2aex-class.md)\ +[CW2CWEX Class](../../atl/reference/cw2cwex-class.md)\ [Class Overview](../../atl/atl-class-overview.md) diff --git a/docs/atl/reference/cwindow-class.md b/docs/atl/reference/cwindow-class.md index 280ec8c398..c91fae3db6 100644 --- a/docs/atl/reference/cwindow-class.md +++ b/docs/atl/reference/cwindow-class.md @@ -4,9 +4,8 @@ title: "CWindow Class" ms.date: "11/04/2016" f1_keywords: ["CWindow", "ATLWIN/ATL::CWindow", "ATLWIN/ATL::CWindow::CWindow", "ATLWIN/ATL::CWindow::ArrangeIconicWindows", "ATLWIN/ATL::CWindow::Attach", "ATLWIN/ATL::CWindow::BeginPaint", "ATLWIN/ATL::CWindow::BringWindowToTop", "ATLWIN/ATL::CWindow::CenterWindow", "ATLWIN/ATL::CWindow::ChangeClipboardChain", "ATLWIN/ATL::CWindow::CheckDlgButton", "ATLWIN/ATL::CWindow::CheckRadioButton", "ATLWIN/ATL::CWindow::ChildWindowFromPoint", "ATLWIN/ATL::CWindow::ChildWindowFromPointEx", "ATLWIN/ATL::CWindow::ClientToScreen", "ATLWIN/ATL::CWindow::Create", "ATLWIN/ATL::CWindow::CreateCaret", "ATLWIN/ATL::CWindow::CreateGrayCaret", "ATLWIN/ATL::CWindow::CreateSolidCaret", "ATLWIN/ATL::CWindow::DeferWindowPos", "ATLWIN/ATL::CWindow::DestroyWindow", "ATLWIN/ATL::CWindow::Detach", "ATLWIN/ATL::CWindow::DlgDirList", "ATLWIN/ATL::CWindow::DlgDirListComboBox", "ATLWIN/ATL::CWindow::DlgDirSelect", "ATLWIN/ATL::CWindow::DlgDirSelectComboBox", "ATLWIN/ATL::CWindow::DragAcceptFiles", "ATLWIN/ATL::CWindow::DrawMenuBar", "ATLWIN/ATL::CWindow::EnableScrollBar", "ATLWIN/ATL::CWindow::EnableWindow", "ATLWIN/ATL::CWindow::EndPaint", "ATLWIN/ATL::CWindow::FlashWindow", "ATLWIN/ATL::CWindow::GetClientRect", "ATLWIN/ATL::CWindow::GetDC", "ATLWIN/ATL::CWindow::GetDCEx", "ATLWIN/ATL::CWindow::GetDescendantWindow", "ATLWIN/ATL::CWindow::GetDlgControl", "ATLWIN/ATL::CWindow::GetDlgCtrlID", "ATLWIN/ATL::CWindow::GetDlgHost", "ATLWIN/ATL::CWindow::GetDlgItem", "ATLWIN/ATL::CWindow::GetDlgItemInt", "ATLWIN/ATL::CWindow::GetDlgItemText", "ATLWIN/ATL::CWindow::GetExStyle", "ATLWIN/ATL::CWindow::GetFont", "ATLWIN/ATL::CWindow::GetHotKey", "ATLWIN/ATL::CWindow::GetIcon", "ATLWIN/ATL::CWindow::GetLastActivePopup", "ATLWIN/ATL::CWindow::GetMenu", "ATLWIN/ATL::CWindow::GetNextDlgGroupItem", "ATLWIN/ATL::CWindow::GetNextDlgTabItem", "ATLWIN/ATL::CWindow::GetParent", "ATLWIN/ATL::CWindow::GetScrollInfo", "ATLWIN/ATL::CWindow::GetScrollPos", "ATLWIN/ATL::CWindow::GetScrollRange", "ATLWIN/ATL::CWindow::GetStyle", "ATLWIN/ATL::CWindow::GetSystemMenu", "ATLWIN/ATL::CWindow::GetTopLevelParent", "ATLWIN/ATL::CWindow::GetTopLevelWindow", "ATLWIN/ATL::CWindow::GetTopWindow", "ATLWIN/ATL::CWindow::GetUpdateRect", "ATLWIN/ATL::CWindow::GetUpdateRgn", "ATLWIN/ATL::CWindow::GetWindow", "ATLWIN/ATL::CWindow::GetWindowContextHelpId", "ATLWIN/ATL::CWindow::GetWindowDC", "ATLWIN/ATL::CWindow::GetWindowLong", "ATLWIN/ATL::CWindow::GetWindowLongPtr", "ATLWIN/ATL::CWindow::GetWindowPlacement", "ATLWIN/ATL::CWindow::GetWindowProcessID", "ATLWIN/ATL::CWindow::GetWindowRect", "ATLWIN/ATL::CWindow::GetWindowRgn", "ATLWIN/ATL::CWindow::GetWindowText", "ATLWIN/ATL::CWindow::GetWindowTextLength", "ATLWIN/ATL::CWindow::GetWindowThreadID", "ATLWIN/ATL::CWindow::GetWindowWord", "ATLWIN/ATL::CWindow::GotoDlgCtrl", "ATLWIN/ATL::CWindow::HideCaret", "ATLWIN/ATL::CWindow::HiliteMenuItem", "ATLWIN/ATL::CWindow::Invalidate", "ATLWIN/ATL::CWindow::InvalidateRect", "ATLWIN/ATL::CWindow::InvalidateRgn", "ATLWIN/ATL::CWindow::IsChild", "ATLWIN/ATL::CWindow::IsDialogMessage", "ATLWIN/ATL::CWindow::IsDlgButtonChecked", "ATLWIN/ATL::CWindow::IsIconic", "ATLWIN/ATL::CWindow::IsParentDialog", "ATLWIN/ATL::CWindow::IsWindow", "ATLWIN/ATL::CWindow::IsWindowEnabled", "ATLWIN/ATL::CWindow::IsWindowUnicode", "ATLWIN/ATL::CWindow::IsWindowVisible", "ATLWIN/ATL::CWindow::IsZoomed", "ATLWIN/ATL::CWindow::KillTimer", "ATLWIN/ATL::CWindow::LockWindowUpdate", "ATLWIN/ATL::CWindow::MapWindowPoints", "ATLWIN/ATL::CWindow::MessageBox", "ATLWIN/ATL::CWindow::ModifyStyle", "ATLWIN/ATL::CWindow::ModifyStyleEx", "ATLWIN/ATL::CWindow::MoveWindow", "ATLWIN/ATL::CWindow::NextDlgCtrl", "ATLWIN/ATL::CWindow::OpenClipboard", "ATLWIN/ATL::CWindow::PostMessage", "ATLWIN/ATL::CWindow::PrevDlgCtrl", "ATLWIN/ATL::CWindow::Print", "ATLWIN/ATL::CWindow::PrintClient", "ATLWIN/ATL::CWindow::RedrawWindow", "ATLWIN/ATL::CWindow::ReleaseDC", "ATLWIN/ATL::CWindow::ResizeClient", "ATLWIN/ATL::CWindow::ScreenToClient", "ATLWIN/ATL::CWindow::ScrollWindow", "ATLWIN/ATL::CWindow::ScrollWindowEx", "ATLWIN/ATL::CWindow::SendDlgItemMessage", "ATLWIN/ATL::CWindow::SendMessage", "ATLWIN/ATL::CWindow::SendMessageToDescendants", "ATLWIN/ATL::CWindow::SendNotifyMessage", "ATLWIN/ATL::CWindow::SetActiveWindow", "ATLWIN/ATL::CWindow::SetCapture", "ATLWIN/ATL::CWindow::SetClipboardViewer", "ATLWIN/ATL::CWindow::SetDlgCtrlID", "ATLWIN/ATL::CWindow::SetDlgItemInt", "ATLWIN/ATL::CWindow::SetDlgItemText", "ATLWIN/ATL::CWindow::SetFocus", "ATLWIN/ATL::CWindow::SetFont", "ATLWIN/ATL::CWindow::SetHotKey", "ATLWIN/ATL::CWindow::SetIcon", "ATLWIN/ATL::CWindow::SetMenu", "ATLWIN/ATL::CWindow::SetParent", "ATLWIN/ATL::CWindow::SetRedraw", "ATLWIN/ATL::CWindow::SetScrollInfo", "ATLWIN/ATL::CWindow::SetScrollPos", "ATLWIN/ATL::CWindow::SetScrollRange", "ATLWIN/ATL::CWindow::SetTimer", "ATLWIN/ATL::CWindow::SetWindowContextHelpId", "ATLWIN/ATL::CWindow::SetWindowLong", "ATLWIN/ATL::CWindow::SetWindowLongPtr", "ATLWIN/ATL::CWindow::SetWindowPlacement", "ATLWIN/ATL::CWindow::SetWindowPos", "ATLWIN/ATL::CWindow::SetWindowRgn", "ATLWIN/ATL::CWindow::SetWindowText", "ATLWIN/ATL::CWindow::SetWindowWord", "ATLWIN/ATL::CWindow::ShowCaret", "ATLWIN/ATL::CWindow::ShowOwnedPopups", "ATLWIN/ATL::CWindow::ShowScrollBar", "ATLWIN/ATL::CWindow::ShowWindow", "ATLWIN/ATL::CWindow::ShowWindowAsync", "ATLWIN/ATL::CWindow::UpdateWindow", "ATLWIN/ATL::CWindow::ValidateRect", "ATLWIN/ATL::CWindow::ValidateRgn", "ATLWIN/ATL::CWindow::WinHelp", "ATLWIN/ATL::CWindow::m_hWnd", "ATLWIN/ATL::CWindow::rcDefault"] helpviewer_keywords: ["CWindow class"] -ms.assetid: fefa00c8-f053-4bcf-87bc-dc84f5386683 --- -# CWindow Class +# `CWindow` Class This class provides methods for manipulating a window. @@ -25,206 +24,206 @@ class CWindow |Name|Description| |----------|-----------------| -|[CWindow::CWindow](#cwindow)|Constructor.| +|[`CWindow::CWindow`](#cwindow)|Constructor.| ### Public Methods |Name|Description| |----------|-----------------| -|[CWindow::ArrangeIconicWindows](#arrangeiconicwindows)|Arranges all minimized child windows.| -|[CWindow::Attach](#attach)|Attaches a window to the `CWindow` object.| -|[CWindow::BeginPaint](#beginpaint)|Prepares the window for painting.| -|[CWindow::BringWindowToTop](#bringwindowtotop)|Brings the window to the top of the Z order.| -|[CWindow::CenterWindow](#centerwindow)|Centers the window against a given window.| -|[CWindow::ChangeClipboardChain](#changeclipboardchain)|Removes the window from the chain of Clipboard viewers.| -|[CWindow::CheckDlgButton](#checkdlgbutton)|Changes the check state of the specified button.| -|[CWindow::CheckRadioButton](#checkradiobutton)|Checks the specified radio button.| -|[CWindow::ChildWindowFromPoint](#childwindowfrompoint)|Retrieves the child window containing the specified point.| -|[CWindow::ChildWindowFromPointEx](#childwindowfrompointex)|Retrieves a particular type of child window containing the specified point.| -|[CWindow::ClientToScreen](#clienttoscreen)|Converts client coordinates to screen coordinates.| -|[CWindow::Create](#create)|Creates a window.| -|[CWindow::CreateCaret](#createcaret)|Creates a new shape for the system caret.| -|[CWindow::CreateGrayCaret](#creategraycaret)|Creates a gray rectangle for the system caret.| -|[CWindow::CreateSolidCaret](#createsolidcaret)|Creates a solid rectangle for the system caret.| -|[CWindow::DeferWindowPos](#deferwindowpos)|Updates the specified multiple-window-position structure for the specified window.| -|[CWindow::DestroyWindow](#destroywindow)|Destroys the window associated with the `CWindow` object.| -|[CWindow::Detach](#detach)|Detaches the window from the `CWindow` object.| -|[CWindow::DlgDirList](#dlgdirlist)|Fills a list box with the names of all files matching a specified path or file name.| -|[CWindow::DlgDirListComboBox](#dlgdirlistcombobox)|Fills a combo box with the names of all files matching a specified path or file name.| -|[CWindow::DlgDirSelect](#dlgdirselect)|Retrieves the current selection from a list box.| -|[CWindow::DlgDirSelectComboBox](#dlgdirselectcombobox)|Retrieves the current selection from a combo box.| -|[CWindow::DragAcceptFiles](#dragacceptfiles)|Registers whether the window accepts dragged files.| -|[CWindow::DrawMenuBar](#drawmenubar)|Redraws the window's menu bar.| -|[CWindow::EnableScrollBar](#enablescrollbar)|Enables or disables the scroll bar arrows.| -|[CWindow::EnableWindow](#enablewindow)|Enables or disables input.| -|[CWindow::EndPaint](#endpaint)|Marks the end of painting.| -|[CWindow::FlashWindow](#flashwindow)|Flashes the window once.| -|[CWindow::GetClientRect](#getclientrect)|Retrieves the coordinates of the client area.| -|[CWindow::GetDC](#getdc)|Retrieves a device context for the client area.| -|[CWindow::GetDCEx](#getdcex)|Retrieves a device context for the client area and allows clipping options.| -|[CWindow::GetDescendantWindow](#getdescendantwindow)|Retrieves the specified descendant window.| -|[CWindow::GetDlgControl](#getdlgcontrol)|Retrieves an interface on the specified control.| -|[CWindow::GetDlgCtrlID](#getdlgctrlid)|Retrieves the window's identifier (for child windows only).| -|[CWindow::GetDlgHost](#getdlghost)|Retrieves a pointer to an interface to the ATL Control hosting container.| -|[CWindow::GetDlgItem](#getdlgitem)|Retrieves the specified child window.| -|[CWindow::GetDlgItemInt](#getdlgitemint)|Translates a control's text to an integer.| -|[CWindow::GetDlgItemText](#getdlgitemtext)|Retrieves a control's text.| -|[CWindow::GetExStyle](#getexstyle)|Retrieves the extended window styles.| -|[CWindow::GetFont](#getfont)|Retrieves the window's current font.| -|[CWindow::GetHotKey](#gethotkey)|Determines the hot key associated with the window.| -|[CWindow::GetIcon](#geticon)|Retrieves the window's large or small icon.| -|[CWindow::GetLastActivePopup](#getlastactivepopup)|Retrieves the most recently active pop-up window.| -|[CWindow::GetMenu](#getmenu)|Retrieves the window's menu.| -|[CWindow::GetNextDlgGroupItem](#getnextdlggroupitem)|Retrieves the previous or next control within a group of controls.| -|[CWindow::GetNextDlgTabItem](#getnextdlgtabitem)|Retrieves the previous or next control having the WS_TABSTOP style.| -|[CWindow::GetParent](#getparent)|Retrieves the immediate parent window.| -|[CWindow::GetScrollInfo](#getscrollinfo)|Retrieves the parameters of a scroll bar.| -|[CWindow::GetScrollPos](#getscrollpos)|Retrieves the position of the scroll box.| -|[CWindow::GetScrollRange](#getscrollrange)|Retrieves the scroll bar range.| -|[CWindow::GetStyle](#getstyle)|Retrieves the window styles.| -|[CWindow::GetSystemMenu](#getsystemmenu)|Creates a copy of the system menu for modification.| -|[CWindow::GetTopLevelParent](#gettoplevelparent)|Retrieves the top-level parent or owner window.| -|[CWindow::GetTopLevelWindow](#gettoplevelwindow)|Retrieves the top-level owner window.| -|[CWindow::GetTopWindow](#gettopwindow)|Retrieves the top-level child window.| -|[CWindow::GetUpdateRect](#getupdaterect)|Retrieves the coordinates of the smallest rectangle that completely encloses the update region.| -|[CWindow::GetUpdateRgn](#getupdatergn)|Retrieves the update region and copies it into a specified region.| -|[CWindow::GetWindow](#getwindow)|Retrieves the specified window.| -|[CWindow::GetWindowContextHelpId](#getwindowcontexthelpid)|Retrieves the window's help context identifier.| -|[CWindow::GetWindowDC](#getwindowdc)|Retrieves a device context for the entire window.| -|[CWindow::GetWindowLong](#getwindowlong)|Retrieves a 32-bit value at a specified offset into the extra window memory.| -|[CWindow::GetWindowLongPtr](#getwindowlongptr)|Retrieves information about the specified window, including a value at a specified offset into the extra window memory.| -|[CWindow::GetWindowPlacement](#getwindowplacement)|Retrieves the show state and positions.| -|[CWindow::GetWindowProcessID](#getwindowprocessid)|Retrieves the identifier of the process that created the window.| -|[CWindow::GetWindowRect](#getwindowrect)|Retrieves the window's bounding dimensions.| -|[CWindow::GetWindowRgn](#getwindowrgn)|Obtains a copy of the window region of a window.| -|[CWindow::GetWindowText](#getwindowtext)|Retrieves the window's text.| -|[CWindow::GetWindowTextLength](#getwindowtextlength)|Retrieves the length of the window's text.| -|[CWindow::GetWindowThreadID](#getwindowthreadid)|Retrieves the identifier of the thread that created the specified window.| -|[CWindow::GetWindowWord](#getwindowword)|Retrieves a 16-bit value at a specified offset into the extra window memory.| -|[CWindow::GotoDlgCtrl](#gotodlgctrl)|Sets the keyboard focus to a control in the dialog box.| -|[CWindow::HideCaret](#hidecaret)|Hides the system caret.| -|[CWindow::HiliteMenuItem](#hilitemenuitem)|Highlights or removes the highlight from a top-level menu item.| -|[CWindow::Invalidate](#invalidate)|Invalidates the entire client area.| -|[CWindow::InvalidateRect](#invalidaterect)|Invalidates the client area within the specified rectangle.| -|[CWindow::InvalidateRgn](#invalidatergn)|Invalidates the client area within the specified region.| -|[CWindow::IsChild](#ischild)|Determines whether the specified window is a child window.| -|[CWindow::IsDialogMessage](#isdialogmessage)|Determines whether a message is intended for the specified dialog box.| -|[CWindow::IsDlgButtonChecked](#isdlgbuttonchecked)|Determines the check state of the button.| -|[CWindow::IsIconic](#isiconic)|Determines whether the window is minimized.| -|[CWindow::IsParentDialog](#isparentdialog)|Determines if the parent window of a control is a dialog window.| -|[CWindow::IsWindow](#iswindow)|Determines whether the specified window handle identifies an existing window.| -|[CWindow::IsWindowEnabled](#iswindowenabled)|Determines whether the window is enabled for input.| -|[CWindow::IsWindowUnicode](#iswindowunicode)|Determines whether the specified window is a native Unicode window.| -|[CWindow::IsWindowVisible](#iswindowvisible)|Determines the window's visibility state.| -|[CWindow::IsZoomed](#iszoomed)|Determines whether the window is maximized.| -|[CWindow::KillTimer](#killtimer)|Destroys a timer event.| -|[CWindow::LockWindowUpdate](#lockwindowupdate)|Disables or enables drawing in the window.| -|[CWindow::MapWindowPoints](#mapwindowpoints)|Converts a set of points from the window's coordinate space to the coordinate space of another window.| -|[CWindow::MessageBox](#messagebox)|Displays a message box.| -|[CWindow::ModifyStyle](#modifystyle)|Modifies the window styles.| -|[CWindow::ModifyStyleEx](#modifystyleex)|Modifies the extended window styles.| -|[CWindow::MoveWindow](#movewindow)|Changes the window's size and position.| -|[CWindow::NextDlgCtrl](#nextdlgctrl)|Sets the keyboard focus to the next control in the dialog box.| -|[CWindow::OpenClipboard](#openclipboard)|Opens the Clipboard.| -|[CWindow::PostMessage](#postmessage)|Places a message in the message queue associated with the thread that created the window. Returns without waiting for the thread to process the message.| -|[CWindow::PrevDlgCtrl](#prevdlgctrl)|Sets the keyboard focus to the previous control in the dialog box.| -|[CWindow::Print](#print)|Requests that the window be drawn in a specified device context.| -|[CWindow::PrintClient](#printclient)|Requests that the window's client area be drawn in a specified device context.| -|[CWindow::RedrawWindow](#redrawwindow)|Updates a specified rectangle or region in the client area.| -|[CWindow::ReleaseDC](#releasedc)|Releases a device context.| -|[CWindow::ResizeClient](#resizeclient)|Resizes the window.| -|[CWindow::ScreenToClient](#screentoclient)|Converts screen coordinates to client coordinates.| -|[CWindow::ScrollWindow](#scrollwindow)|Scrolls the specified client area.| -|[CWindow::ScrollWindowEx](#scrollwindowex)|Scrolls the specified client area with additional features.| -|[CWindow::SendDlgItemMessage](#senddlgitemmessage)|Sends a message to a control.| -|[CWindow::SendMessage](#sendmessage)|Sends a message to the window and does not return until the window procedure has processed the message.| -|[CWindow::SendMessageToDescendants](#sendmessagetodescendants)|Sends a message to the specified descendant windows.| -|[CWindow::SendNotifyMessage](#sendnotifymessage)|Sends a message to the window. If the window was created by the calling thread, `SendNotifyMessage` does not return until the window procedure has processed the message. Otherwise, it returns immediately.| -|[CWindow::SetActiveWindow](#setactivewindow)|Activates the window.| -|[CWindow::SetCapture](#setcapture)|Sends all subsequent mouse input to the window.| -|[CWindow::SetClipboardViewer](#setclipboardviewer)|Adds the window to the Clipboard viewer chain.| -|[CWindow::SetDlgCtrlID](#setdlgctrlid)|Changes the window's identifier.| -|[CWindow::SetDlgItemInt](#setdlgitemint)|Changes a control's text to the string representation of an integer value.| -|[CWindow::SetDlgItemText](#setdlgitemtext)|Changes a control's text.| -|[CWindow::SetFocus](#setfocus)|Sets the input focus to the window.| -|[CWindow::SetFont](#setfont)|Changes the window's current font.| -|[CWindow::SetHotKey](#sethotkey)|Associates a hot key with the window.| -|[CWindow::SetIcon](#seticon)|Changes the window's large or small icon.| -|[CWindow::SetMenu](#setmenu)|Changes the window's current menu.| -|[CWindow::SetParent](#setparent)|Changes the parent window.| -|[CWindow::SetRedraw](#setredraw)|Sets or clears the redraw flag.| -|[CWindow::SetScrollInfo](#setscrollinfo)|Sets the parameters of a scroll bar.| -|[CWindow::SetScrollPos](#setscrollpos)|Changes the position of the scroll box.| -|[CWindow::SetScrollRange](#setscrollrange)|Changes the scroll bar range.| -|[CWindow::SetTimer](#settimer)|Creates a timer event.| -|[CWindow::SetWindowContextHelpId](#setwindowcontexthelpid)|Sets the window's help context identifier.| -|[CWindow::SetWindowLong](#setwindowlong)|Sets a 32-bit value at a specified offset into the extra window memory.| -|[CWindow::SetWindowLongPtr](#setwindowlongptr)|Changes an attribute of the specified window, and also sets a value at the specified offset in the extra window memory.| -|[CWindow::SetWindowPlacement](#setwindowplacement)|Sets the show state and positions.| -|[CWindow::SetWindowPos](#setwindowpos)|Sets the size, position, and Z order.| -|[CWindow::SetWindowRgn](#setwindowrgn)|Sets the window region of a window.| -|[CWindow::SetWindowText](#setwindowtext)|Changes the window's text.| -|[CWindow::SetWindowWord](#setwindowword)|Sets a 16-bit value at a specified offset into the extra window memory.| -|[CWindow::ShowCaret](#showcaret)|Displays the system caret.| -|[CWindow::ShowOwnedPopups](#showownedpopups)|Shows or hides the pop-up windows owned by the window.| -|[CWindow::ShowScrollBar](#showscrollbar)|Shows or hides a scroll bar.| -|[CWindow::ShowWindow](#showwindow)|Sets the window's show state.| -|[CWindow::ShowWindowAsync](#showwindowasync)|Sets the show state of a window created by a different thread.| -|[CWindow::UpdateWindow](#updatewindow)|Updates the client area.| -|[CWindow::ValidateRect](#validaterect)|Validates the client area within the specified rectangle.| -|[CWindow::ValidateRgn](#validatergn)|Validates the client area within the specified region.| -|[CWindow::WinHelp](#winhelp)|Starts Windows Help.| +|[`CWindow::ArrangeIconicWindows`](#arrangeiconicwindows)|Arranges all minimized child windows.| +|[`CWindow::Attach`](#attach)|Attaches a window to the `CWindow` object.| +|[`CWindow::BeginPaint`](#beginpaint)|Prepares the window for painting.| +|[`CWindow::BringWindowToTop`](#bringwindowtotop)|Brings the window to the top of the Z order.| +|[`CWindow::CenterWindow`](#centerwindow)|Centers the window against a given window.| +|[`CWindow::ChangeClipboardChain`](#changeclipboardchain)|Removes the window from the chain of Clipboard viewers.| +|[`CWindow::CheckDlgButton`](#checkdlgbutton)|Changes the check state of the specified button.| +|[`CWindow::CheckRadioButton`](#checkradiobutton)|Checks the specified radio button.| +|[`CWindow::ChildWindowFromPoint`](#childwindowfrompoint)|Retrieves the child window containing the specified point.| +|[`CWindow::ChildWindowFromPointEx`](#childwindowfrompointex)|Retrieves a particular type of child window containing the specified point.| +|[`CWindow::ClientToScreen`](#clienttoscreen)|Converts client coordinates to screen coordinates.| +|[`CWindow::Create`](#create)|Creates a window.| +|[`CWindow::CreateCaret`](#createcaret)|Creates a new shape for the system caret.| +|[`CWindow::CreateGrayCaret`](#creategraycaret)|Creates a gray rectangle for the system caret.| +|[`CWindow::CreateSolidCaret`](#createsolidcaret)|Creates a solid rectangle for the system caret.| +|[`CWindow::DeferWindowPos`](#deferwindowpos)|Updates the specified multiple-window-position structure for the specified window.| +|[`CWindow::DestroyWindow`](#destroywindow)|Destroys the window associated with the `CWindow` object.| +|[`CWindow::Detach`](#detach)|Detaches the window from the `CWindow` object.| +|[`CWindow::DlgDirList`](#dlgdirlist)|Fills a list box with the names of all files matching a specified path or file name.| +|[`CWindow::DlgDirListComboBox`](#dlgdirlistcombobox)|Fills a combo box with the names of all files matching a specified path or file name.| +|[`CWindow::DlgDirSelect`](#dlgdirselect)|Retrieves the current selection from a list box.| +|[`CWindow::DlgDirSelectComboBox`](#dlgdirselectcombobox)|Retrieves the current selection from a combo box.| +|[`CWindow::DragAcceptFiles`](#dragacceptfiles)|Registers whether the window accepts dragged files.| +|[`CWindow::DrawMenuBar`](#drawmenubar)|Redraws the window's menu bar.| +|[`CWindow::EnableScrollBar`](#enablescrollbar)|Enables or disables the scroll bar arrows.| +|[`CWindow::EnableWindow`](#enablewindow)|Enables or disables input.| +|[`CWindow::EndPaint`](#endpaint)|Marks the end of painting.| +|[`CWindow::FlashWindow`](#flashwindow)|Flashes the window once.| +|[`CWindow::GetClientRect`](#getclientrect)|Retrieves the coordinates of the client area.| +|[`CWindow::GetDC`](#getdc)|Retrieves a device context for the client area.| +|[`CWindow::GetDCEx`](#getdcex)|Retrieves a device context for the client area and allows clipping options.| +|[`CWindow::GetDescendantWindow`](#getdescendantwindow)|Retrieves the specified descendant window.| +|[`CWindow::GetDlgControl`](#getdlgcontrol)|Retrieves an interface on the specified control.| +|[`CWindow::GetDlgCtrlID`](#getdlgctrlid)|Retrieves the window's identifier (for child windows only).| +|[`CWindow::GetDlgHost`](#getdlghost)|Retrieves a pointer to an interface to the ATL Control hosting container.| +|[`CWindow::GetDlgItem`](#getdlgitem)|Retrieves the specified child window.| +|[`CWindow::GetDlgItemInt`](#getdlgitemint)|Translates a control's text to an integer.| +|[`CWindow::GetDlgItemText`](#getdlgitemtext)|Retrieves a control's text.| +|[`CWindow::GetExStyle`](#getexstyle)|Retrieves the extended window styles.| +|[`CWindow::GetFont`](#getfont)|Retrieves the window's current font.| +|[`CWindow::GetHotKey`](#gethotkey)|Determines the hot key associated with the window.| +|[`CWindow::GetIcon`](#geticon)|Retrieves the window's large or small icon.| +|[`CWindow::GetLastActivePopup`](#getlastactivepopup)|Retrieves the most recently active pop-up window.| +|[`CWindow::GetMenu`](#getmenu)|Retrieves the window's menu.| +|[`CWindow::GetNextDlgGroupItem`](#getnextdlggroupitem)|Retrieves the previous or next control within a group of controls.| +|[`CWindow::GetNextDlgTabItem`](#getnextdlgtabitem)|Retrieves the previous or next control having the `WS_TABSTOP` style.| +|[`CWindow::GetParent`](#getparent)|Retrieves the immediate parent window.| +|[`CWindow::GetScrollInfo`](#getscrollinfo)|Retrieves the parameters of a scroll bar.| +|[`CWindow::GetScrollPos`](#getscrollpos)|Retrieves the position of the scroll box.| +|[`CWindow::GetScrollRange`](#getscrollrange)|Retrieves the scroll bar range.| +|[`CWindow::GetStyle`](#getstyle)|Retrieves the window styles.| +|[`CWindow::GetSystemMenu`](#getsystemmenu)|Creates a copy of the system menu for modification.| +|[`CWindow::GetTopLevelParent`](#gettoplevelparent)|Retrieves the top-level parent or owner window.| +|[`CWindow::GetTopLevelWindow`](#gettoplevelwindow)|Retrieves the top-level owner window.| +|[`CWindow::GetTopWindow`](#gettopwindow)|Retrieves the top-level child window.| +|[`CWindow::GetUpdateRect`](#getupdaterect)|Retrieves the coordinates of the smallest rectangle that completely encloses the update region.| +|[`CWindow::GetUpdateRgn`](#getupdatergn)|Retrieves the update region and copies it into a specified region.| +|[`CWindow::GetWindow`](#getwindow)|Retrieves the specified window.| +|[`CWindow::GetWindowContextHelpId`](#getwindowcontexthelpid)|Retrieves the window's help context identifier.| +|[`CWindow::GetWindowDC`](#getwindowdc)|Retrieves a device context for the entire window.| +|[`CWindow::GetWindowLong`](#getwindowlong)|Retrieves a 32-bit value at a specified offset into the extra window memory.| +|[`CWindow::GetWindowLongPtr`](#getwindowlongptr)|Retrieves information about the specified window, including a value at a specified offset into the extra window memory.| +|[`CWindow::GetWindowPlacement`](#getwindowplacement)|Retrieves the show state and positions.| +|[`CWindow::GetWindowProcessID`](#getwindowprocessid)|Retrieves the identifier of the process that created the window.| +|[`CWindow::GetWindowRect`](#getwindowrect)|Retrieves the window's bounding dimensions.| +|[`CWindow::GetWindowRgn`](#getwindowrgn)|Obtains a copy of the window region of a window.| +|[`CWindow::GetWindowText`](#getwindowtext)|Retrieves the window's text.| +|[`CWindow::GetWindowTextLength`](#getwindowtextlength)|Retrieves the length of the window's text.| +|[`CWindow::GetWindowThreadID`](#getwindowthreadid)|Retrieves the identifier of the thread that created the specified window.| +|[`CWindow::GetWindowWord`](#getwindowword)|Retrieves a 16-bit value at a specified offset into the extra window memory.| +|[`CWindow::GotoDlgCtrl`](#gotodlgctrl)|Sets the keyboard focus to a control in the dialog box.| +|[`CWindow::HideCaret`](#hidecaret)|Hides the system caret.| +|[`CWindow::HiliteMenuItem`](#hilitemenuitem)|Highlights or removes the highlight from a top-level menu item.| +|[`CWindow::Invalidate`](#invalidate)|Invalidates the entire client area.| +|[`CWindow::InvalidateRect`](#invalidaterect)|Invalidates the client area within the specified rectangle.| +|[`CWindow::InvalidateRgn`](#invalidatergn)|Invalidates the client area within the specified region.| +|[`CWindow::IsChild`](#ischild)|Determines whether the specified window is a child window.| +|[`CWindow::IsDialogMessage`](#isdialogmessage)|Determines whether a message is intended for the specified dialog box.| +|[`CWindow::IsDlgButtonChecked`](#isdlgbuttonchecked)|Determines the check state of the button.| +|[`CWindow::IsIconic`](#isiconic)|Determines whether the window is minimized.| +|[`CWindow::IsParentDialog`](#isparentdialog)|Determines if the parent window of a control is a dialog window.| +|[`CWindow::IsWindow`](#iswindow)|Determines whether the specified window handle identifies an existing window.| +|[`CWindow::IsWindowEnabled`](#iswindowenabled)|Determines whether the window is enabled for input.| +|[`CWindow::IsWindowUnicode`](#iswindowunicode)|Determines whether the specified window is a native Unicode window.| +|[`CWindow::IsWindowVisible`](#iswindowvisible)|Determines the window's visibility state.| +|[`CWindow::IsZoomed`](#iszoomed)|Determines whether the window is maximized.| +|[`CWindow::KillTimer`](#killtimer)|Destroys a timer event.| +|[`CWindow::LockWindowUpdate`](#lockwindowupdate)|Disables or enables drawing in the window.| +|[`CWindow::MapWindowPoints`](#mapwindowpoints)|Converts a set of points from the window's coordinate space to the coordinate space of another window.| +|[`CWindow::MessageBox`](#messagebox)|Displays a message box.| +|[`CWindow::ModifyStyle`](#modifystyle)|Modifies the window styles.| +|[`CWindow::ModifyStyleEx`](#modifystyleex)|Modifies the extended window styles.| +|[`CWindow::MoveWindow`](#movewindow)|Changes the window's size and position.| +|[`CWindow::NextDlgCtrl`](#nextdlgctrl)|Sets the keyboard focus to the next control in the dialog box.| +|[`CWindow::OpenClipboard`](#openclipboard)|Opens the Clipboard.| +|[`CWindow::PostMessage`](#postmessage)|Places a message in the message queue associated with the thread that created the window. Returns without waiting for the thread to process the message.| +|[`CWindow::PrevDlgCtrl`](#prevdlgctrl)|Sets the keyboard focus to the previous control in the dialog box.| +|[`CWindow::Print`](#print)|Requests that the window be drawn in a specified device context.| +|[`CWindow::PrintClient`](#printclient)|Requests that the window's client area be drawn in a specified device context.| +|[`CWindow::RedrawWindow`](#redrawwindow)|Updates a specified rectangle or region in the client area.| +|[`CWindow::ReleaseDC`](#releasedc)|Releases a device context.| +|[`CWindow::ResizeClient`](#resizeclient)|Resizes the window.| +|[`CWindow::ScreenToClient`](#screentoclient)|Converts screen coordinates to client coordinates.| +|[`CWindow::ScrollWindow`](#scrollwindow)|Scrolls the specified client area.| +|[`CWindow::ScrollWindowEx`](#scrollwindowex)|Scrolls the specified client area with additional features.| +|[`CWindow::SendDlgItemMessage`](#senddlgitemmessage)|Sends a message to a control.| +|[`CWindow::SendMessage`](#sendmessage)|Sends a message to the window and doesn't return until the window procedure has processed the message.| +|[`CWindow::SendMessageToDescendants`](#sendmessagetodescendants)|Sends a message to the specified descendant windows.| +|[`CWindow::SendNotifyMessage`](#sendnotifymessage)|Sends a message to the window. If the window was created by the calling thread, `SendNotifyMessage` doesn't return until the window procedure has processed the message. Otherwise, it returns immediately.| +|[`CWindow::SetActiveWindow`](#setactivewindow)|Activates the window.| +|[`CWindow::SetCapture`](#setcapture)|Sends all subsequent mouse input to the window.| +|[`CWindow::SetClipboardViewer`](#setclipboardviewer)|Adds the window to the Clipboard viewer chain.| +|[`CWindow::SetDlgCtrlID`](#setdlgctrlid)|Changes the window's identifier.| +|[`CWindow::SetDlgItemInt`](#setdlgitemint)|Changes a control's text to the string representation of an integer value.| +|[`CWindow::SetDlgItemText`](#setdlgitemtext)|Changes a control's text.| +|[`CWindow::SetFocus`](#setfocus)|Sets the input focus to the window.| +|[`CWindow::SetFont`](#setfont)|Changes the window's current font.| +|[`CWindow::SetHotKey`](#sethotkey)|Associates a hot key with the window.| +|[`CWindow::SetIcon`](#seticon)|Changes the window's large or small icon.| +|[`CWindow::SetMenu`](#setmenu)|Changes the window's current menu.| +|[`CWindow::SetParent`](#setparent)|Changes the parent window.| +|[`CWindow::SetRedraw`](#setredraw)|Sets or clears the redraw flag.| +|[`CWindow::SetScrollInfo`](#setscrollinfo)|Sets the parameters of a scroll bar.| +|[`CWindow::SetScrollPos`](#setscrollpos)|Changes the position of the scroll box.| +|[`CWindow::SetScrollRange`](#setscrollrange)|Changes the scroll bar range.| +|[`CWindow::SetTimer`](#settimer)|Creates a timer event.| +|[`CWindow::SetWindowContextHelpId`](#setwindowcontexthelpid)|Sets the window's help context identifier.| +|[`CWindow::SetWindowLong`](#setwindowlong)|Sets a 32-bit value at a specified offset into the extra window memory.| +|[`CWindow::SetWindowLongPtr`](#setwindowlongptr)|Changes an attribute of the specified window, and also sets a value at the specified offset in the extra window memory.| +|[`CWindow::SetWindowPlacement`](#setwindowplacement)|Sets the show state and positions.| +|[`CWindow::SetWindowPos`](#setwindowpos)|Sets the size, position, and Z order.| +|[`CWindow::SetWindowRgn`](#setwindowrgn)|Sets the window region of a window.| +|[`CWindow::SetWindowText`](#setwindowtext)|Changes the window's text.| +|[`CWindow::SetWindowWord`](#setwindowword)|Sets a 16-bit value at a specified offset into the extra window memory.| +|[`CWindow::ShowCaret`](#showcaret)|Displays the system caret.| +|[`CWindow::ShowOwnedPopups`](#showownedpopups)|Shows or hides the pop-up windows owned by the window.| +|[`CWindow::ShowScrollBar`](#showscrollbar)|Shows or hides a scroll bar.| +|[`CWindow::ShowWindow`](#showwindow)|Sets the window's show state.| +|[`CWindow::ShowWindowAsync`](#showwindowasync)|Sets the show state of a window created by a different thread.| +|[`CWindow::UpdateWindow`](#updatewindow)|Updates the client area.| +|[`CWindow::ValidateRect`](#validaterect)|Validates the client area within the specified rectangle.| +|[`CWindow::ValidateRgn`](#validatergn)|Validates the client area within the specified region.| +|[`CWindow::WinHelp`](#winhelp)|Starts Windows Help.| ### Public Operators |Name|Description| |----------|-----------------| -|[CWindow::operator HWND](#operator_hwnd)|Converts the `CWindow` object to an HWND.| -|[CWindow::operator =](#operator_eq)|Assigns an HWND to the `CWindow` object.| +|[`CWindow::operator HWND`](#operator_hwnd)|Converts the `CWindow` object to an `HWND`.| +|[`CWindow::operator =`](#operator_eq)|Assigns an `HWND` to the `CWindow` object.| ### Public Data Members |Name|Description| |----------|-----------------| -|[CWindow::m_hWnd](#m_hwnd)|The handle to the window associated with the `CWindow` object.| -|[CWindow::rcDefault](#rcdefault)|Contains default window dimensions.| +|[`CWindow::m_hWnd`](#m_hwnd)|The handle to the window associated with the `CWindow` object.| +|[`CWindow::rcDefault`](#rcdefault)|Contains default window dimensions.| ## Remarks `CWindow` provides the base functionality for manipulating a window in ATL. Many of the `CWindow` methods simply wrap one of the Win32 API functions. For example, compare the prototypes for `CWindow::ShowWindow` and `ShowWindow`: -|CWindow method|Win32 function| -|--------------------|--------------------| -|**BOOL ShowWindow( int** `nCmdShow` **);**|**BOOL ShowWindow( HWND** `hWnd` **, int** `nCmdShow` **);**| +| CWindow method | Win32 function | +|--|--| +| `BOOL ShowWindow( int nCmdShow );` | `BOOL ShowWindow( HWND hWnd , int nCmdShow );` | `CWindow::ShowWindow` calls the Win32 function `ShowWindow` by passing `CWindow::m_hWnd` as the first parameter. Every `CWindow` method that directly wraps a Win32 function passes the `m_hWnd` member; therefore, much of the `CWindow` documentation will refer you to the Windows SDK. > [!NOTE] > Not every window-related Win32 function is wrapped by `CWindow`, and not every `CWindow` method wraps a Win32 function. -`CWindow::m_hWnd` stores the HWND that identifies a window. An HWND is attached to your object when you: +`CWindow::m_hWnd` stores the `HWND` that identifies a window. An `HWND` is attached to your object when you: -- Specify an HWND in `CWindow`'s constructor. +- Specify an `HWND` in `CWindow`'s constructor. - Call `CWindow::Attach`. -- Use `CWindow`'s **operator =**. +- Use `CWindow`'s **`operator =`**. - Create or subclass a window using one of the following classes derived from `CWindow`: -[CWindowImpl](../../atl/reference/cwindowimpl-class.md) Allows you to create a new window or subclass an existing window. +[`CWindowImpl`](../../atl/reference/cwindowimpl-class.md) Allows you to create a new window or subclass an existing window. -[CContainedWindow](../../atl/reference/ccontainedwindowt-class.md) Implements a window contained within another object. You can create a new window or subclass an existing window. +[`CContainedWindow`](../../atl/reference/ccontainedwindowt-class.md) Implements a window contained within another object. You can create a new window or subclass an existing window. -[CDialogImpl](../../atl/reference/cdialogimpl-class.md) Allows you to create a modal or modeless dialog box. +[`CDialogImpl`](../../atl/reference/cdialogimpl-class.md) Allows you to create a modal or modeless dialog box. For more information about windows, see [Windows](/windows/win32/winmsg/windows) and subsequent topics in the Windows SDK. For more information about using windows in ATL, see the article [ATL Window Classes](../../atl/atl-window-classes.md). ## Requirements -**Header:** atlwin.h +**Header:** `atlwin.h` -## CWindow::ArrangeIconicWindows +## `CWindow::ArrangeIconicWindows` Arranges all minimized child windows. @@ -234,11 +233,11 @@ UINT ArrangeIconicWindows() throw(); ### Remarks -See [ArrangeIconicWindows](/windows/win32/api/winuser/nf-winuser-arrangeiconicwindows) in the Windows SDK. +See [`ArrangeIconicWindows`](/windows/win32/api/winuser/nf-winuser-arrangeiconicwindows) in the Windows SDK. -## CWindow::Attach +## `CWindow::Attach` -Attaches the window identified by *hWndNew* to the `CWindow` object. +Attaches the window identified by *`hWndNew`* to the `CWindow` object. ```cpp void Attach(HWND hWndNew) throw(); @@ -246,14 +245,14 @@ void Attach(HWND hWndNew) throw(); ### Parameters -*hWndNew*
+*`hWndNew`*\ [in] The handle to a window. ### Example [!code-cpp[NVC_ATL_Windowing#1](../../atl/codesnippet/cpp/cwindow-class_1.cpp)] -## CWindow::BeginPaint +## `CWindow::BeginPaint` Prepares the window for painting. @@ -263,13 +262,13 @@ HDC BeginPaint(LPPAINTSTRUCT lpPaint) throw(); ### Remarks -See [BeginPaint](/windows/win32/api/winuser/nf-winuser-beginpaint) in the Windows SDK. +See [`BeginPaint`](/windows/win32/api/winuser/nf-winuser-beginpaint) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#2](../../atl/codesnippet/cpp/cwindow-class_2.cpp)] -## CWindow::BringWindowToTop +## `CWindow::BringWindowToTop` Brings the window to the top of the Z order. @@ -279,13 +278,13 @@ BOOL BringWindowToTop() throw(); ### Remarks -See [BringWindowToTop](/windows/win32/api/winuser/nf-winuser-bringwindowtotop) in the Windows SDK. +See [`BringWindowToTop`](/windows/win32/api/winuser/nf-winuser-bringwindowtotop) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#3](../../atl/codesnippet/cpp/cwindow-class_3.cpp)] -## CWindow::CenterWindow +## `CWindow::CenterWindow` Centers the window against a given window. @@ -295,18 +294,18 @@ BOOL CenterWindow(HWND hWndCenter = NULL) throw(); ### Parameters -*hWndCenter*
-[in] The handle to the window against which to center. If this parameter is NULL (the default value), the method will set *hWndCenter* to the window's parent window if it is a child window. Otherwise, it will set *hWndCenter* to the window's owner window. +*`hWndCenter`*\ +[in] The handle to the window against which to center. If this parameter is `NULL` (the default value), the method will set *`hWndCenter`* to the window's parent window if it's a child window. Otherwise, it will set *`hWndCenter`* to the window's owner window. ### Return Value -TRUE if the window is successfully centered; otherwise, FALSE. +`TRUE` if the window is successfully centered; otherwise, `FALSE`. ### Example [!code-cpp[NVC_ATL_Windowing#4](../../atl/codesnippet/cpp/cwindow-class_4.cpp)] -## CWindow::ChangeClipboardChain +## `CWindow::ChangeClipboardChain` Removes the window from the chain of Clipboard viewers. @@ -316,9 +315,9 @@ BOOL ChangeClipboardChain(HWND hWndNewNext) throw(); ### Remarks -See [ChangeClipboardChain](/windows/win32/api/winuser/nf-winuser-changeclipboardchain) in the Windows SDK. +See [`ChangeClipboardChain`](/windows/win32/api/winuser/nf-winuser-changeclipboardchain) in the Windows SDK. -## CWindow::CheckDlgButton +## `CWindow::CheckDlgButton` Changes the check state of the specified button. @@ -328,9 +327,9 @@ BOOL CheckDlgButton(int nIDButton, UINT nCheck) throw(); ### Remarks -See [CheckDlgButton](/windows/win32/api/winuser/nf-winuser-checkdlgbutton) in the Windows SDK. +See [`CheckDlgButton`](/windows/win32/api/winuser/nf-winuser-checkdlgbutton) in the Windows SDK. -## CWindow::CheckRadioButton +## `CWindow::CheckRadioButton` Checks the specified radio button. @@ -343,9 +342,9 @@ BOOL CheckRadioButton( ### Remarks -See [CheckRadioButton](/windows/win32/api/winuser/nf-winuser-checkradiobutton) in the Windows SDK. +See [`CheckRadioButton`](/windows/win32/api/winuser/nf-winuser-checkradiobutton) in the Windows SDK. -## CWindow::ChildWindowFromPoint +## `CWindow::ChildWindowFromPoint` Retrieves the child window containing the specified point. @@ -355,9 +354,9 @@ HWND ChildWindowFromPoint(POINT point) const throw(); ### Remarks -See [ChildWindowFromPoint](/windows/win32/api/winuser/nf-winuser-childwindowfrompoint) in the Windows SDK. +See [`ChildWindowFromPoint`](/windows/win32/api/winuser/nf-winuser-childwindowfrompoint) in the Windows SDK. -## CWindow::ChildWindowFromPointEx +## `CWindow::ChildWindowFromPointEx` Retrieves a particular type of child window containing the specified point. @@ -367,9 +366,9 @@ HWND ChildWindowFromPoint(POINT point, UINT uFlags) const throw(); ### Remarks -See [ChildWindowFromPointEx](/windows/win32/api/winuser/nf-winuser-childwindowfrompointex) in the Windows SDK. +See [`ChildWindowFromPointEx`](/windows/win32/api/winuser/nf-winuser-childwindowfrompointex) in the Windows SDK. -## CWindow::ClientToScreen +## `CWindow::ClientToScreen` Converts client coordinates to screen coordinates. @@ -380,11 +379,11 @@ BOOL ClientToScreen(LPRECT lpRect) const throw(); ### Remarks -See [ClientToScreen](/windows/win32/api/winuser/nf-winuser-clienttoscreen) in the Windows SDK. +See [`ClientToScreen`](/windows/win32/api/winuser/nf-winuser-clienttoscreen) in the Windows SDK. -The second version of this method allows you to convert the coordinates of a [RECT](/windows/win32/api/windef/ns-windef-rect) structure. +The second version of this method allows you to convert the coordinates of a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure. -## CWindow::Create +## `CWindow::Create` Creates a window. @@ -402,43 +401,43 @@ HWND Create( ### Parameters -*lpstrWndClass*
+*`lpstrWndClass`*\ [in] A pointer to the window's class. -*hWndParent*
+*`hWndParent`*\ [in] The handle to the parent or owner window. -*rect*
-[in] A variable of type [_U_RECT](../../atl/reference/u-rect-class.md) specifying the position of the window. The default value is NULL. When this parameter is NULL, the value of `CWindow::rcDefault` is used. +*`rect`*\ +[in] A variable of type [`_U_RECT`](../../atl/reference/u-rect-class.md) specifying the position of the window. The default value is `NULL`. When this parameter is `NULL`, the value of `CWindow::rcDefault` is used. -*szWindowName*
-[in] Specifies the name of the window. The default value is NULL. +*`szWindowName`*\ +[in] Specifies the name of the window. The default value is `NULL`. -*dwStyle*
-[in] The style of the window. The default value is 0, meaning no style is specified. For a list of possible values, see [CreateWindow](/windows/win32/api/winuser/nf-winuser-createwindoww) in the Windows SDK. +*`dwStyle`*\ +[in] The style of the window. The default value is 0, meaning no style is specified. For a list of possible values, see [`CreateWindow`](/windows/win32/api/winuser/nf-winuser-createwindoww) in the Windows SDK. -*dwExStyle*
-[in] The extended window style. The default value is 0, meaning no extended style is specified. For a list of possible values, see [CreateWindowEx](/windows/win32/api/winuser/nf-winuser-createwindowexw) in the Windows SDK. +*`dwExStyle`*\ +[in] The extended window style. The default value is 0, meaning no extended style is specified. For a list of possible values, see [`CreateWindowEx`](/windows/win32/api/winuser/nf-winuser-createwindowexw) in the Windows SDK. -*MenuOrID*
-[in] A variable of type [_U_MENUorID](../../atl/reference/u-menuorid-class.md) specifying a handle to a menu or a window identifier. The default value is 0U. +*`MenuOrID`*\ +[in] A variable of type [`_U_MENUorID`](../../atl/reference/u-menuorid-class.md) specifying a handle to a menu or a window identifier. The default value is `0U`. -*lpCreateParam*
-A pointer to the window-creation data contained in a [CREATESTRUCT](/windows/win32/api/winuser/ns-winuser-createstructw) structure. +*`lpCreateParam`*\ +A pointer to the window-creation data contained in a [`CREATESTRUCT`](/windows/win32/api/winuser/ns-winuser-createstructw) structure. ### Return Value -If successful, the handle to the newly created window, specified by [m_hWnd](#m_hwnd). Otherwise, NULL. +If successful, the handle to the newly created window, specified by [`m_hWnd`](#m_hwnd). Otherwise, `NULL`. ### Remarks `CWindow::rcDefault` is defined as `__declspec(selectany) RECT CWindow::rcDefault = {CW_USEDEFAULT, CW_USEDEFAULT, 0, 0};`. -See [CreateWindow](/windows/win32/api/winuser/nf-winuser-createwindoww) in the Windows SDK for more information. +See [`CreateWindow`](/windows/win32/api/winuser/nf-winuser-createwindoww) in the Windows SDK for more information. -**Note** If 0 is used as the value for the *MenuOrID* parameter, it must be specified as 0U (the default value) to avoid a compiler error. +**Note** If 0 is used as the value for the *`MenuOrID`* parameter, it must be specified as `0U` (the default value) to avoid a compiler error. -## CWindow::CreateCaret +## `CWindow::CreateCaret` Creates a new shape for the system caret. @@ -448,9 +447,9 @@ BOOL CreateCaret(HBITMAP pBitmap) throw(); ### Remarks -See [CreateCaret](/windows/win32/api/winuser/nf-winuser-createcaret) in the Windows SDK. +See [`CreateCaret`](/windows/win32/api/winuser/nf-winuser-createcaret) in the Windows SDK. -## CWindow::CreateGrayCaret +## `CWindow::CreateGrayCaret` Creates a gray rectangle for the system caret. @@ -460,11 +459,11 @@ BOOL CreateGrayCaret(int nWidth, int nHeight) throw(); ### Remarks -See [CreateCaret](/windows/win32/api/winuser/nf-winuser-createcaret) in the Windows SDK. +See [`CreateCaret`](/windows/win32/api/winuser/nf-winuser-createcaret) in the Windows SDK. -Passes (HBITMAP) 1 for the bitmap handle parameter to the Win32 function. +Passes `(HBITMAP) 1` for the bitmap handle parameter to the Win32 function. -## CWindow::CreateSolidCaret +## `CWindow::CreateSolidCaret` Creates a solid rectangle for the system caret. @@ -474,11 +473,11 @@ BOOL CreateSolidCaret(int nWidth, int nHeight) throw(); ### Remarks -See [CreateCaret](/windows/win32/api/winuser/nf-winuser-createcaret) in the Windows SDK. +See [`CreateCaret`](/windows/win32/api/winuser/nf-winuser-createcaret) in the Windows SDK. -Passes (HBITMAP) 0 for the bitmap handle parameter to the Win32 function. +Passes `(HBITMAP) 0` for the bitmap handle parameter to the Win32 function. -## CWindow::CWindow +## `CWindow::CWindow` The constructor. @@ -488,17 +487,17 @@ CWindow(HWND hWnd = NULL) throw(); ### Parameters -*hWnd*
+*`hWnd`*\ [in] The handle to a window. ### Remarks -Initializes the [m_hWnd](#m_hwnd) member to *hWnd*, which by default is NULL. +Initializes the [`m_hWnd`](#m_hwnd) member to *`hWnd`*, which by default is `NULL`. > [!NOTE] -> `CWindow::CWindow` does not create a window. Classes [CWindowImpl](../../atl/reference/cwindowimpl-class.md), [CContainedWindow](../../atl/reference/ccontainedwindowt-class.md), and [CDialogImpl](../../atl/reference/cdialogimpl-class.md) (all of which derive from `CWindow`) provide a method to create a window or dialog box, which is then assigned to `CWindow::m_hWnd`. You can also use the [CreateWindow](/windows/win32/api/winuser/nf-winuser-createwindoww) Win32 function. +> `CWindow::CWindow` does not create a window. Classes [`CWindowImpl`](../../atl/reference/cwindowimpl-class.md), [`CContainedWindow`](../../atl/reference/ccontainedwindowt-class.md), and [`CDialogImpl`](../../atl/reference/cdialogimpl-class.md) (all of which derive from `CWindow`) provide a method to create a window or dialog box, which is then assigned to `CWindow::m_hWnd`. You can also use the [`CreateWindow`](/windows/win32/api/winuser/nf-winuser-createwindoww) Win32 function. -## CWindow::DeferWindowPos +## `CWindow::DeferWindowPos` Updates the specified multiple-window-position structure for the specified window. @@ -515,11 +514,11 @@ HDWP DeferWindowPos( ### Remarks -See [DeferWindowPos](/windows/win32/api/winuser/nf-winuser-deferwindowpos) in the Windows SDK. +See [`DeferWindowPos`](/windows/win32/api/winuser/nf-winuser-deferwindowpos) in the Windows SDK. -## CWindow::DestroyWindow +## `CWindow::DestroyWindow` -Destroys the window associated with the `CWindow` object and sets [m_hWnd](#m_hwnd) to NULL. +Destroys the window associated with the `CWindow` object and sets [`m_hWnd`](#m_hwnd) to `NULL`. ``` BOOL DestroyWindow() throw(); @@ -527,17 +526,17 @@ BOOL DestroyWindow() throw(); ### Remarks -See [DestroyWindow](/windows/win32/api/winuser/nf-winuser-destroywindow) in the Windows SDK. +See [`DestroyWindow`](/windows/win32/api/winuser/nf-winuser-destroywindow) in the Windows SDK. -It does not destroy the `CWindow` object itself. +It doesn't destroy the `CWindow` object itself. ### Example [!code-cpp[NVC_ATL_Windowing#5](../../atl/codesnippet/cpp/cwindow-class_5.cpp)] -## CWindow::Detach +## `CWindow::Detach` -Detaches [m_hWnd](#m_hwnd) from the `CWindow` object and sets `m_hWnd` to NULL. +Detaches [`m_hWnd`](#m_hwnd) from the `CWindow` object and sets `m_hWnd` to `NULL`. ``` HWND Detach() throw(); @@ -545,13 +544,13 @@ HWND Detach() throw(); ### Return Value -The HWND associated with the `CWindow` object. +The `HWND` associated with the `CWindow` object. ### Example [!code-cpp[NVC_ATL_Windowing#6](../../atl/codesnippet/cpp/cwindow-class_6.cpp)] -## CWindow::DlgDirList +## `CWindow::DlgDirList` Fills a list box with the names of all files matching a specified path or file name. @@ -565,9 +564,9 @@ int DlgDirList( ### Remarks -See [DlgDirList](/windows/win32/api/winuser/nf-winuser-dlgdirlistw) in the Windows SDK. +See [`DlgDirList`](/windows/win32/api/winuser/nf-winuser-dlgdirlistw) in the Windows SDK. -## CWindow::DlgDirListComboBox +## `CWindow::DlgDirListComboBox` Fills a combo box with the names of all files matching a specified path or file name. @@ -581,9 +580,9 @@ int DlgDirListComboBox( ### Remarks -See [DlgDirListComboBox](/windows/win32/api/winuser/nf-winuser-dlgdirlistcomboboxw) in the Windows SDK. +See [`DlgDirListComboBox`](/windows/win32/api/winuser/nf-winuser-dlgdirlistcomboboxw) in the Windows SDK. -## CWindow::DlgDirSelect +## `CWindow::DlgDirSelect` Retrieves the current selection from a list box. @@ -596,9 +595,9 @@ BOOL DlgDirSelect( ### Remarks -See [DlgDirSelectEx](/windows/win32/api/winuser/nf-winuser-dlgdirselectexw) in the Windows SDK. +See [`DlgDirSelectEx`](/windows/win32/api/winuser/nf-winuser-dlgdirselectexw) in the Windows SDK. -## CWindow::DlgDirSelectComboBox +## `CWindow::DlgDirSelectComboBox` Retrieves the current selection from a combo box. @@ -611,9 +610,9 @@ BOOL DlgDirSelectComboBox( ### Remarks -See [DlgDirSelectComboBoxEx](/windows/win32/api/winuser/nf-winuser-dlgdirselectcomboboxexw) in the Windows SDK. +See [`DlgDirSelectComboBoxEx`](/windows/win32/api/winuser/nf-winuser-dlgdirselectcomboboxexw) in the Windows SDK. -## CWindow::DragAcceptFiles +## `CWindow::DragAcceptFiles` Registers whether the window accepts dragged files. @@ -623,9 +622,9 @@ void DragAcceptFiles(BOOL bAccept = TRUE); ### Remarks -See [DragAcceptFiles](/windows/win32/api/shellapi/nf-shellapi-dragacceptfiles) in the Windows SDK. +See [`DragAcceptFiles`](/windows/win32/api/shellapi/nf-shellapi-dragacceptfiles) in the Windows SDK. -## CWindow::DrawMenuBar +## `CWindow::DrawMenuBar` Redraws the window's menu bar. @@ -635,9 +634,9 @@ BOOL DrawMenuBar() throw(); ### Remarks -See [DrawMenuBar](/windows/win32/api/winuser/nf-winuser-drawmenubar) in the Windows SDK. +See [`DrawMenuBar`](/windows/win32/api/winuser/nf-winuser-drawmenubar) in the Windows SDK. -## CWindow::EnableScrollBar +## `CWindow::EnableScrollBar` Enables or disables the scroll bar arrows. @@ -647,9 +646,9 @@ BOOL EnableScrollBar(UINT uSBFlags, UINT uArrowFlags = ESB_ENABLE_BOTH) throw(); ### Remarks -See [EnableScrollBar](/windows/win32/api/winuser/nf-winuser-enablescrollbar) in the Windows SDK. +See [`EnableScrollBar`](/windows/win32/api/winuser/nf-winuser-enablescrollbar) in the Windows SDK. -## CWindow::EnableWindow +## `CWindow::EnableWindow` Enables or disables input. @@ -659,13 +658,13 @@ BOOL EnableWindow(BOOL bEnable = TRUE) throw(); ### Remarks -See [EnableWindow](/windows/win32/api/winuser/nf-winuser-enablewindow) in the Windows SDK. +See [`EnableWindow`](/windows/win32/api/winuser/nf-winuser-enablewindow) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#7](../../atl/codesnippet/cpp/cwindow-class_7.cpp)] -## CWindow::EndPaint +## `CWindow::EndPaint` Marks the end of painting. @@ -675,13 +674,13 @@ void EndPaint(LPPAINTSTRUCT lpPaint) throw(); ### Remarks -See [EndPaint](/windows/win32/api/winuser/nf-winuser-endpaint) in the Windows SDK. +See [`EndPaint`](/windows/win32/api/winuser/nf-winuser-endpaint) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#2](../../atl/codesnippet/cpp/cwindow-class_2.cpp)] -## CWindow::FlashWindow +## `CWindow::FlashWindow` Flashes the window once. @@ -691,9 +690,9 @@ BOOL FlashWindow(BOOL bInvert) throw(); ### Remarks -See [FlashWindow](/windows/win32/api/winuser/nf-winuser-flashwindow) in the Windows SDK. +See [`FlashWindow`](/windows/win32/api/winuser/nf-winuser-flashwindow) in the Windows SDK. -## CWindow::GetClientRect +## `CWindow::GetClientRect` Retrieves the coordinates of the client area. @@ -703,13 +702,13 @@ BOOL GetClientRect(LPRECT lpRect) const throw(); ### Remarks -See [GetClientRect](/windows/win32/api/winuser/nf-winuser-getclientrect) in the Windows SDK. +See [`GetClientRect`](/windows/win32/api/winuser/nf-winuser-getclientrect) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#8](../../atl/codesnippet/cpp/cwindow-class_8.cpp)] -## CWindow::GetDC +## `CWindow::GetDC` Retrieves a device context for the client area. @@ -719,13 +718,13 @@ HDC GetDC() throw(); ### Remarks -See [GetDC](/windows/win32/api/winuser/nf-winuser-getdc) in the Windows SDK. +See [`GetDC`](/windows/win32/api/winuser/nf-winuser-getdc) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#9](../../atl/codesnippet/cpp/cwindow-class_9.cpp)] -## CWindow::GetDCEx +## `CWindow::GetDCEx` Retrieves a device context for the client area and allows clipping options. @@ -735,9 +734,9 @@ HDC GetDCEx(HRGN hRgnClip, DWORD flags) throw(); ### Remarks -See [GetDCEx](/windows/win32/api/winuser/nf-winuser-getdcex) in the Windows SDK. +See [`GetDCEx`](/windows/win32/api/winuser/nf-winuser-getdcex) in the Windows SDK. -## CWindow::GetDescendantWindow +## `CWindow::GetDescendantWindow` Finds the descendant window specified by the given identifier. @@ -747,7 +746,7 @@ HWND GetDescendantWindow(int nID) const throw(); ### Parameters -*nID*
+*`nID`*\ [in] The identifier of the descendant window to be retrieved. ### Return Value @@ -758,7 +757,7 @@ The handle to a descendant window. `GetDescendantWindow` searches the entire tree of child windows, not only the windows that are immediate children. -## CWindow::GetDlgControl +## `CWindow::GetDlgControl` Call this function to get a pointer to an interface of an ActiveX control that is hosted by a composite control or a control-hosting dialog. @@ -771,24 +770,24 @@ HRESULT GetDlgControl( ### Parameters -*nID*
+*`nID`*\ [in] The resource ID of the control being retrieved. -*iid*
+*`iid`*\ [in] The ID of the interface you would like to get from the control. -*ppCtrl*
+*`ppCtrl`*\ [out] The pointer to the interface. ### Return Value -Returns S_OK on success or any valid error HRESULT. For example, the function returns E_FAIL if the control specified by *nID* cannot be found and it returns E_NOINTERFACE if the control can be found, but it doesn't support the interface specified by *iid*. +Returns `S_OK` on success or any valid error `HRESULT`. For example, the function returns `E_FAIL` if the control specified by *`nID`* can't be found and it returns `E_NOINTERFACE` if the control can be found, but it doesn't support the interface specified by *`iid`*. ### Remarks Using this pointer, you can call methods on the interface. -## CWindow::GetDlgCtrlID +## `CWindow::GetDlgCtrlID` Retrieves the window's identifier (for child windows only). @@ -798,9 +797,9 @@ int GetDlgCtrlID() const throw(); ### Remarks -See [GetDlgCtrlID](/windows/win32/api/winuser/nf-winuser-getdlgctrlid) in the Windows SDK. +See [`GetDlgCtrlID`](/windows/win32/api/winuser/nf-winuser-getdlgctrlid) in the Windows SDK. -## CWindow::GetDlgHost +## `CWindow::GetDlgHost` Retrieves a pointer to an interface to the ATL Control hosting container. @@ -813,24 +812,24 @@ HRESULT GetDlgHost( ### Parameters -*nID*
+*`nID`*\ [in] The resource ID of the control being retrieved. -*iid*
+*`iid`*\ [in] The ID of the interface you would like to get from the control. -*ppHost*
+*`ppHost`*\ [out] The pointer to the interface. ### Return Value -Returns S_OK if the window specified by *iid* is a Control Container, and the requested interface could be retrieved. Returns E_FAIL if the window is not a Control Container, or if the interface requested could not be retrieved. If a window with the specified ID could not be found, then the return value is equal to HRESULT_FROM_WIN32(ERROR_CONTROL_ID_NOT_FOUND). +Returns `S_OK` if the window specified by *`iid`* is a Control Container, and the requested interface could be retrieved. Returns `E_FAIL` if the window isn't a Control Container, or if the interface requested couldn't be retrieved. If a window with the specified ID couldn't be found, then the return value is equal to `HRESULT_FROM_WIN32(ERROR_CONTROL_ID_NOT_FOUND)`. ### Remarks Using this pointer, you can call methods on the interface. -## CWindow::GetDlgItem +## `CWindow::GetDlgItem` Retrieves the specified child window. @@ -842,7 +841,7 @@ HWND GetDlgItem(int nID) const throw(); See [GetDlgItem](/windows/win32/api/winuser/nf-winuser-getdlgitem) in the Windows SDK. -## CWindow::GetDlgItemInt +## `CWindow::GetDlgItemInt` Translates a control's text to an integer. @@ -855,9 +854,9 @@ UINT GetDlgItemInt( ### Remarks -See [GetDlgItemInt](/windows/win32/api/winuser/nf-winuser-getdlgitemint) in the Windows SDK. +See [`GetDlgItemInt`](/windows/win32/api/winuser/nf-winuser-getdlgitemint) in the Windows SDK. -## CWindow::GetDlgItemText +## `CWindow::GetDlgItemText` Retrieves a control's text. @@ -874,13 +873,11 @@ BOOL GetDlgItemText( ### Remarks -See [GetDlgItemText](/windows/win32/api/winuser/nf-winuser-getdlgitemtextw) in the Windows SDK. +For more information, see [`GetDlgItemText`](/windows/win32/api/winuser/nf-winuser-getdlgitemtextw) in the Windows SDK. -### Remarks - -The second version of this method allows you to copy the control's text to a BSTR. This version returns TRUE if the text is successfully copied; otherwise, FALSE. +The second version of this method allows you to copy the control's text to a `BSTR`. This version returns `TRUE` if the text is successfully copied; otherwise, `FALSE`. -## CWindow::GetExStyle +## `CWindow::GetExStyle` Retrieves the extended window styles of the window. @@ -894,15 +891,15 @@ The window's extended styles. ### Remarks -To retrieve the regular window styles, call [GetStyle](#getstyle). +To retrieve the regular window styles, call [`GetStyle`](#getstyle). ### Example [!code-cpp[NVC_ATL_Windowing#10](../../atl/codesnippet/cpp/cwindow-class_10.cpp)] -## CWindow::GetFont +## `CWindow::GetFont` -Retrieves the window's current font by sending a [WM_GETFONT](/windows/win32/winmsg/wm-getfont) message to the window. +Retrieves the window's current font by sending a [`WM_GETFONT`](/windows/win32/winmsg/wm-getfont) message to the window. ``` HFONT GetFont() const throw(); @@ -912,9 +909,9 @@ HFONT GetFont() const throw(); A font handle. -## CWindow::GetHotKey +## `CWindow::GetHotKey` -Determines the hot key associated with the window by sending a WM_GETHOTKEY message. +Determines the hot key associated with the window by sending a `WM_GETHOTKEY` message. ``` DWORD GetHotKey() const throw(); @@ -922,9 +919,9 @@ DWORD GetHotKey() const throw(); ### Return Value -The virtual key code and modifiers for the hot key associated with the window. For a list of possible modifiers, see [WM_GETHOTKEY](/windows/win32/inputdev/wm-gethotkey) in the Windows SDK. For a list of standard virtual key codes, see Winuser.h. +The virtual key code and modifiers for the hot key associated with the window. For a list of possible modifiers, see [`WM_GETHOTKEY`](/windows/win32/inputdev/wm-gethotkey) in the Windows SDK. For a list of standard virtual key codes, see `Winuser.h`. -## CWindow::GetIcon +## `CWindow::GetIcon` Retrieves the handle to the window's large or small icon. @@ -934,8 +931,8 @@ HICON GetIcon(BOOL bBigIcon = TRUE) const; ### Parameters -*bBigIcon*
-[in] If TRUE (the default value) the method returns the large icon. Otherwise, it returns the small icon. +*`bBigIcon`*\ +[in] If `TRUE` (the default value) the method returns the large icon. Otherwise, it returns the small icon. ### Return Value @@ -943,9 +940,9 @@ An icon handle. ### Remarks -`GetIcon` sends a [WM_GETICON](/windows/win32/winmsg/wm-geticon) message to the window. +`GetIcon` sends a [`WM_GETICON`](/windows/win32/winmsg/wm-geticon) message to the window. -## CWindow::GetLastActivePopup +## `CWindow::GetLastActivePopup` Retrieves the most recently active pop-up window. @@ -955,9 +952,9 @@ HWND GetLastActivePopup() const throw(); ### Remarks -See [GetLastActivePopup](/windows/win32/api/winuser/nf-winuser-getlastactivepopup) in the Windows SDK. +See [`GetLastActivePopup`](/windows/win32/api/winuser/nf-winuser-getlastactivepopup) in the Windows SDK. -## CWindow::GetMenu +## `CWindow::GetMenu` Retrieves the window's menu. @@ -967,9 +964,9 @@ HMENU GetMenu() const throw(); ### Remarks -See [GetMenu](/windows/win32/api/winuser/nf-winuser-getmenu) in the Windows SDK. +See [`GetMenu`](/windows/win32/api/winuser/nf-winuser-getmenu) in the Windows SDK. -## CWindow::GetNextDlgGroupItem +## `CWindow::GetNextDlgGroupItem` Retrieves the previous or next control within a group of controls. @@ -979,11 +976,11 @@ HWND GetNextDlgGroupItem(HWND hWndCtl, BOOL bPrevious = FALSE) const throw(); ### Remarks -See [GetNextDlgGroupItem](/windows/win32/api/winuser/nf-winuser-getnextdlggroupitem) in the Windows SDK. +See [`GetNextDlgGroupItem`](/windows/win32/api/winuser/nf-winuser-getnextdlggroupitem) in the Windows SDK. -## CWindow::GetNextDlgTabItem +## `CWindow::GetNextDlgTabItem` -Retrieves the previous or next control having the WS_TABSTOP style. +Retrieves the previous or next control having the `WS_TABSTOP` style. ``` HWND GetNextDlgTabItem(HWND hWndCtl, BOOL bPrevious = FALSE) const throw(); @@ -991,9 +988,9 @@ HWND GetNextDlgTabItem(HWND hWndCtl, BOOL bPrevious = FALSE) const throw(); ### Remarks -See [GetNextDlgTabItem](/windows/win32/api/winuser/nf-winuser-getnextdlgtabitem) in the Windows SDK. +See [`GetNextDlgTabItem`](/windows/win32/api/winuser/nf-winuser-getnextdlgtabitem) in the Windows SDK. -## CWindow::GetParent +## `CWindow::GetParent` Retrieves the immediate parent window. @@ -1003,13 +1000,13 @@ HWND GetParent() const throw(); ### Remarks -See [GetParent](/windows/win32/api/winuser/nf-winuser-getparent) in the Windows SDK. +See [`GetParent`](/windows/win32/api/winuser/nf-winuser-getparent) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#11](../../atl/codesnippet/cpp/cwindow-class_11.cpp)] -## CWindow::GetScrollInfo +## `CWindow::GetScrollInfo` Retrieves the parameters of a scroll bar. @@ -1019,9 +1016,9 @@ BOOL GetScrollInfo(int nBar, LPSCROLLINFO lpScrollInfo) throw(); ### Remarks -See [GetScrollInfo](/windows/win32/api/winuser/nf-winuser-getscrollinfo) in the Windows SDK. +See [`GetScrollInfo`](/windows/win32/api/winuser/nf-winuser-getscrollinfo) in the Windows SDK. -## CWindow::GetScrollPos +## `CWindow::GetScrollPos` Retrieves the position of the scroll box. @@ -1031,9 +1028,9 @@ int GetScrollPos(int nBar) const throw(); ### Remarks -See [GetScrollPos](/windows/win32/api/winuser/nf-winuser-getscrollpos) in the Windows SDK. +See [`GetScrollPos`](/windows/win32/api/winuser/nf-winuser-getscrollpos) in the Windows SDK. -## CWindow::GetScrollRange +## `CWindow::GetScrollRange` Retrieves the scroll bar range. @@ -1046,9 +1043,9 @@ BOOL GetScrollRange( ### Remarks -See [GetScrollRange](/windows/win32/api/winuser/nf-winuser-getscrollrange) in the Windows SDK. +See [`GetScrollRange`](/windows/win32/api/winuser/nf-winuser-getscrollrange) in the Windows SDK. -## CWindow::GetStyle +## `CWindow::GetStyle` Retrieves the window styles of the window. @@ -1062,13 +1059,13 @@ The window's styles. ### Remarks -To retrieve the extended window styles, call [GetExStyle](#getexstyle). +To retrieve the extended window styles, call [`GetExStyle`](#getexstyle). ### Example [!code-cpp[NVC_ATL_Windowing#12](../../atl/codesnippet/cpp/cwindow-class_12.cpp)] -## CWindow::GetSystemMenu +## `CWindow::GetSystemMenu` Creates a copy of the system menu for modification. @@ -1078,9 +1075,9 @@ HMENU GetSystemMenu(BOOL bRevert) const throw(); ### Remarks -See [GetSystemMenu](/windows/win32/api/winuser/nf-winuser-getsystemmenu) in the Windows SDK. +See [`GetSystemMenu`](/windows/win32/api/winuser/nf-winuser-getsystemmenu) in the Windows SDK. -## CWindow::GetTopLevelParent +## `CWindow::GetTopLevelParent` Retrieves the window's top-level parent window. @@ -1092,7 +1089,7 @@ HWND GetTopLevelParent() const throw(); The handle to the top-level parent window. -## CWindow::GetTopLevelWindow +## `CWindow::GetTopLevelWindow` Retrieves the window's top-level parent or owner window. @@ -1104,7 +1101,7 @@ HWND GetTopLevelWindow() const throw(); The handle to the top-level owner window. -## CWindow::GetTopWindow +## `CWindow::GetTopWindow` Retrieves the top-level child window. @@ -1114,13 +1111,13 @@ HWND GetTopWindow() const throw(); ### Remarks -See [GetTopWindow](/windows/win32/api/winuser/nf-winuser-gettopwindow) in the Windows SDK. +See [`GetTopWindow`](/windows/win32/api/winuser/nf-winuser-gettopwindow) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#13](../../atl/codesnippet/cpp/cwindow-class_13.cpp)] -## CWindow::GetUpdateRect +## `CWindow::GetUpdateRect` Retrieves the coordinates of the smallest rectangle that completely encloses the update region. @@ -1130,9 +1127,9 @@ BOOL GetUpdateRect(LPRECT lpRect, BOOL bErase = FALSE) throw(); ### Remarks -See [GetUpdateRect](/windows/win32/api/winuser/nf-winuser-getupdaterect) in the Windows SDK. +See [`GetUpdateRect`](/windows/win32/api/winuser/nf-winuser-getupdaterect) in the Windows SDK. -## CWindow::GetUpdateRgn +## `CWindow::GetUpdateRgn` Retrieves the update region and copies it into a specified region. @@ -1142,9 +1139,9 @@ int GetUpdateRgn(HRGN hRgn, BOOL bErase = FALSE) throw(); ### Remarks -See [GetUpdateRgn](/windows/win32/api/winuser/nf-winuser-getupdatergn) in the Windows SDK. +See [`GetUpdateRgn`](/windows/win32/api/winuser/nf-winuser-getupdatergn) in the Windows SDK. -## CWindow::GetWindow +## `CWindow::GetWindow` Retrieves the specified window. @@ -1156,7 +1153,7 @@ HWND GetWindow(UINT nCmd) const throw(); See `GetWindow` in the Windows SDK. -## CWindow::GetWindowContextHelpId +## `CWindow::GetWindowContextHelpId` Retrieves the window's help context identifier. @@ -1166,9 +1163,9 @@ DWORD GetWindowContextHelpId() const throw(); ### Remarks -See [GetWindowContextHelpId](/windows/win32/api/winuser/nf-winuser-getwindowcontexthelpid) in the Windows SDK. +See [`GetWindowContextHelpId`](/windows/win32/api/winuser/nf-winuser-getwindowcontexthelpid) in the Windows SDK. -## CWindow::GetWindowDC +## `CWindow::GetWindowDC` Retrieves a device context for the entire window. @@ -1178,13 +1175,13 @@ HDC GetWindowDC() throw(); ### Remarks -See [GetWindowDC](/windows/win32/api/winuser/nf-winuser-getwindowdc) in the Windows SDK. +See [`GetWindowDC`](/windows/win32/api/winuser/nf-winuser-getwindowdc) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#14](../../atl/codesnippet/cpp/cwindow-class_14.cpp)] -## CWindow::GetWindowLong +## `CWindow::GetWindowLong` Retrieves a 32-bit value at a specified offset into the extra window memory. @@ -1194,12 +1191,12 @@ LONG GetWindowLong(int nIndex) const throw(); ### Remarks -See [GetWindowLong](/windows/win32/api/winuser/nf-winuser-getwindowlongw) in the Windows SDK. +See [`GetWindowLong`](/windows/win32/api/winuser/nf-winuser-getwindowlongw) in the Windows SDK. > [!NOTE] -> To write code that is compatible with both 32-bit and 64-bit versions of Windows, use [CWindow::GetWindowLongPtr](#getwindowlongptr). +> To write code that is compatible with both 32-bit and 64-bit versions of Windows, use [`CWindow::GetWindowLongPtr`](#getwindowlongptr). -## CWindow::GetWindowLongPtr +## `CWindow::GetWindowLongPtr` Retrieves information about the specified window, including a value at a specified offset into the extra window memory. @@ -1209,18 +1206,16 @@ LONG_PTR GetWindowLongPtr(int nIndex) const throw(); ### Remarks -See [GetWindowLongPtr](/windows/win32/api/winuser/nf-winuser-getwindowlongptrw) in the Windows SDK. - -### Remarks +For more information, see [`GetWindowLongPtr`](/windows/win32/api/winuser/nf-winuser-getwindowlongptrw) in the Windows SDK. -If you are retrieving a pointer or a handle, this function supersedes the `CWindow::GetWindowLong` method. +If you're retrieving a pointer or a handle, this function supersedes the `CWindow::GetWindowLong` method. > [!NOTE] > Pointers and handles are 32 bits on 32-bit Windows and 64 bits on 64-bit Windows. To write code that is compatible with both 32-bit and 64-bit versions of Windows, use `CWindow::GetWindowLongPtr`. -## CWindow::GetWindowPlacement +## `CWindow::GetWindowPlacement` Retrieves the show state and positions. @@ -1230,9 +1225,9 @@ BOOL GetWindowPlacement(WINDOWPLACEMENT FAR* lpwndpl) const throw(); ### Remarks -See [GetWindowPlacement](/windows/win32/api/winuser/nf-winuser-getwindowplacement) in the Windows SDK. +See [`GetWindowPlacement`](/windows/win32/api/winuser/nf-winuser-getwindowplacement) in the Windows SDK. -## CWindow::GetWindowProcessID +## `CWindow::GetWindowProcessID` Retrieves the identifier of the process that created the window. @@ -1242,13 +1237,13 @@ DWORD GetWindowProcessID() throw(); ### Remarks -See [GetWindowThreadProcessID](/windows/win32/api/winuser/nf-winuser-getwindowthreadprocessid) in the Windows SDK. +See [`GetWindowThreadProcessID`](/windows/win32/api/winuser/nf-winuser-getwindowthreadprocessid) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#15](../../atl/codesnippet/cpp/cwindow-class_15.cpp)] -## CWindow::GetWindowRect +## `CWindow::GetWindowRect` Retrieves the window's bounding dimensions. @@ -1258,9 +1253,9 @@ BOOL GetWindowRect(LPRECT lpRect) const throw(); ### Remarks -See [GetWindowRect](/windows/win32/api/winuser/nf-winuser-getwindowrect) in the Windows SDK. +See [`GetWindowRect`](/windows/win32/api/winuser/nf-winuser-getwindowrect) in the Windows SDK. -## CWindow::GetWindowRgn +## `CWindow::GetWindowRgn` Obtains a copy of the window region of a window. @@ -1270,9 +1265,9 @@ int GetWindowRgn(HRGN hRgn) throw(); ### Remarks -See [GetWindowRgn](/windows/win32/api/winuser/nf-winuser-getwindowrgn) in the Windows SDK. +See [`GetWindowRgn`](/windows/win32/api/winuser/nf-winuser-getwindowrgn) in the Windows SDK. -## CWindow::GetWindowText +## `CWindow::GetWindowText` Retrieves the window's text. @@ -1284,29 +1279,29 @@ int GetWindowText(CSimpleString& strText) const; ### Parameters -*lpszStringBuf*
+*`lpszStringBuf`*\ A buffer to which to write the window text. -*nMaxCount*
+*`nMaxCount`*\ The size of the buffer in characters; also the maximum number of characters to write. -*bstrText*
-A BSTR in which to store the window text. +*`bstrText`*\ +A `BSTR` in which to store the window text. -*strText*
+*`strText`*\ A `CString` in which to store the window text. ### Return Value -If the text is successfully copied, the return value is TRUE; otherwise, the return value is FALSE. +If the text is successfully copied, the return value is `TRUE`; otherwise, the return value is `FALSE`. ### Remarks -See [GetWindowText](/windows/win32/api/winuser/nf-winuser-getwindowtextw) in the Windows SDK. +See [`GetWindowText`](/windows/win32/api/winuser/nf-winuser-getwindowtextw) in the Windows SDK. -The second version of this method allows you to store the text in a BSTR; the third version allows you to store the result in a [CString](../../atl-mfc-shared/reference/cstringt-class.md), since `CSimpleString` is the base class of `CString`. +The second version of this method allows you to store the text in a `BSTR`; the third version allows you to store the result in a [`CString`](../../atl-mfc-shared/reference/cstringt-class.md), since `CSimpleString` is the base class of `CString`. -## CWindow::GetWindowTextLength +## `CWindow::GetWindowTextLength` Retrieves the length of the window's text. @@ -1316,9 +1311,9 @@ int GetWindowTextLength() const throw(); ### Remarks -See [GetWindowTextLength](/windows/win32/api/winuser/nf-winuser-getwindowtextlengthw) in the Windows SDK. +See [`GetWindowTextLength`](/windows/win32/api/winuser/nf-winuser-getwindowtextlengthw) in the Windows SDK. -## CWindow::GetWindowThreadID +## `CWindow::GetWindowThreadID` Retrieves the identifier of the thread that created the specified window. @@ -1328,13 +1323,13 @@ DWORD GetWindowThreadID() throw(); ### Remarks -See [GetWindowThreadProcessID](/windows/win32/api/winuser/nf-winuser-getwindowthreadprocessid) in the Windows SDK. +See [`GetWindowThreadProcessID`](/windows/win32/api/winuser/nf-winuser-getwindowthreadprocessid) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#16](../../atl/codesnippet/cpp/cwindow-class_16.cpp)] -## CWindow::GetWindowWord +## `CWindow::GetWindowWord` Retrieves a 16-bit value at a specified offset into the extra window memory. @@ -1344,9 +1339,9 @@ WORD GetWindowWord(int nIndex) const throw(); ### Remarks -See [GetWindowLong](/windows/win32/api/winuser/nf-winuser-getwindowlongw) in the Windows SDK. +See [`GetWindowLong`](/windows/win32/api/winuser/nf-winuser-getwindowlongw) in the Windows SDK. -## CWindow::GotoDlgCtrl +## `CWindow::GotoDlgCtrl` Sets the keyboard focus to a control in the dialog box. @@ -1356,9 +1351,9 @@ void GotoDlgCtrl(HWND hWndCtrl) const throw(); ### Remarks -See [WM_NEXTDLGCTL](/windows/win32/dlgbox/wm-nextdlgctl) in the Windows SDK. +See [`WM_NEXTDLGCTL`](/windows/win32/dlgbox/wm-nextdlgctl) in the Windows SDK. -## CWindow::HideCaret +## `CWindow::HideCaret` Hides the system caret. @@ -1368,13 +1363,13 @@ BOOL HideCaret() throw(); ### Remarks -See [HideCaret](/windows/win32/api/winuser/nf-winuser-hidecaret) in the Windows SDK. +See [`HideCaret`](/windows/win32/api/winuser/nf-winuser-hidecaret) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#17](../../atl/codesnippet/cpp/cwindow-class_17.cpp)] -## CWindow::HiliteMenuItem +## `CWindow::HiliteMenuItem` Highlights or removes the highlight from a top-level menu item. @@ -1387,9 +1382,9 @@ BOOL HiliteMenuItem( ### Remarks -See [HiliteMenuItem](/windows/win32/api/winuser/nf-winuser-hilitemenuitem) in the Windows SDK. +See [`HiliteMenuItem`](/windows/win32/api/winuser/nf-winuser-hilitemenuitem) in the Windows SDK. -## CWindow::Invalidate +## `CWindow::Invalidate` Invalidates the entire client area. @@ -1399,15 +1394,15 @@ BOOL Invalidate(BOOL bErase = TRUE) throw(); ### Remarks -See [InvalidateRect](/windows/win32/api/winuser/nf-winuser-invalidaterect) in the Windows SDK. +See [`InvalidateRect`](/windows/win32/api/winuser/nf-winuser-invalidaterect) in the Windows SDK. -Passes NULL for the `RECT` parameter to the `InvalidateRect` Win32 function. +Passes `NULL` for the `RECT` parameter to the `InvalidateRect` Win32 function. ### Example [!code-cpp[NVC_ATL_Windowing#18](../../atl/codesnippet/cpp/cwindow-class_18.cpp)] -## CWindow::InvalidateRect +## `CWindow::InvalidateRect` Invalidates the client area within the specified rectangle. @@ -1417,9 +1412,9 @@ BOOL InvalidateRect(LPCRECT lpRect, BOOL bErase = TRUE) throw(); ### Remarks -See [InvalidateRect](/windows/win32/api/winuser/nf-winuser-invalidaterect) in the Windows SDK. +See [`InvalidateRect`](/windows/win32/api/winuser/nf-winuser-invalidaterect) in the Windows SDK. -## CWindow::InvalidateRgn +## `CWindow::InvalidateRgn` Invalidates the client area within the specified region. @@ -1429,13 +1424,11 @@ void InvalidateRgn(HRGN hRgn, BOOL bErase = TRUE) throw(); ### Remarks -See [InvalidateRgn](/windows/win32/api/winuser/nf-winuser-invalidatergn) in the Windows SDK. - -### Remarks +For more information, see [`InvalidateRgn`](/windows/win32/api/winuser/nf-winuser-invalidatergn) in the Windows SDK. -Specifies a **`void`** return type, while the `InvalidateRgn` Win32 function always returns TRUE. +Specifies a **`void`** return type, while the `InvalidateRgn` Win32 function always returns `TRUE`. -## CWindow::IsChild +## `CWindow::IsChild` Determines whether the specified window is a child window. @@ -1445,9 +1438,9 @@ BOOL IsChild(const HWND hWnd) const throw(); ### Remarks -See [IsChild](/windows/win32/api/winuser/nf-winuser-ischild) in the Windows SDK. +See [`IsChild`](/windows/win32/api/winuser/nf-winuser-ischild) in the Windows SDK. -## CWindow::IsDialogMessage +## `CWindow::IsDialogMessage` Determines whether a message is intended for the specified dialog box. @@ -1457,9 +1450,9 @@ BOOL IsDialogMessage(LPMSG lpMsg) throw(); ### Remarks -See [IsDialogMessage](/windows/win32/api/winuser/nf-winuser-isdialogmessagew) in the Windows SDK. +See [`IsDialogMessage`](/windows/win32/api/winuser/nf-winuser-isdialogmessagew) in the Windows SDK. -## CWindow::IsDlgButtonChecked +## `CWindow::IsDlgButtonChecked` Determines the check state of the button. @@ -1469,9 +1462,9 @@ UINT IsDlgButtonChecked(int nIDButton) const throw(); ### Remarks -See [IsDlgButtonChecked](/windows/win32/api/winuser/nf-winuser-isdlgbuttonchecked) in the Windows SDK. +See [`IsDlgButtonChecked`](/windows/win32/api/winuser/nf-winuser-isdlgbuttonchecked) in the Windows SDK. -## CWindow::IsIconic +## `CWindow::IsIconic` Determines whether the window is minimized. @@ -1481,13 +1474,13 @@ BOOL IsIconic() const throw(); ### Remarks -See [IsIconic](/windows/win32/api/winuser/nf-winuser-isiconic) in the Windows SDK. +See [`IsIconic`](/windows/win32/api/winuser/nf-winuser-isiconic) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#19](../../atl/codesnippet/cpp/cwindow-class_19.cpp)] -## CWindow::IsParentDialog +## `CWindow::IsParentDialog` Determines if the parent window of the control is a dialog window. @@ -1497,9 +1490,9 @@ BOOL IsParentDialog() throw(); ### Return Value -Returns TRUE if the parent window is a dialog, FALSE otherwise. +Returns `TRUE` if the parent window is a dialog, `FALSE` otherwise. -## CWindow::IsWindow +## `CWindow::IsWindow` Determines whether the specified window handle identifies an existing window. @@ -1509,13 +1502,13 @@ BOOL IsWindow() throw(); ### Remarks -See [IsWindow](/windows/win32/api/winuser/nf-winuser-iswindow) in the Windows SDK. +See [`IsWindow`](/windows/win32/api/winuser/nf-winuser-iswindow) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#20](../../atl/codesnippet/cpp/cwindow-class_20.cpp)] -## CWindow::IsWindowEnabled +## `CWindow::IsWindowEnabled` Determines whether the window is enabled for input. @@ -1525,13 +1518,13 @@ BOOL IsWindowEnabled() const throw(); ### Remarks -See [IsWindowEnabled](/windows/win32/api/winuser/nf-winuser-iswindowenabled) in the Windows SDK. +See [`IsWindowEnabled`](/windows/win32/api/winuser/nf-winuser-iswindowenabled) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#21](../../atl/codesnippet/cpp/cwindow-class_21.cpp)] -## CWindow::IsWindowVisible +## `CWindow::IsWindowVisible` Determines the window's visibility state. @@ -1541,13 +1534,13 @@ BOOL IsWindowVisible() const throw(); ### Remarks -See [IsWindowVisible](/windows/win32/api/winuser/nf-winuser-iswindowvisible) in the Windows SDK. +See [`IsWindowVisible`](/windows/win32/api/winuser/nf-winuser-iswindowvisible) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#22](../../atl/codesnippet/cpp/cwindow-class_22.cpp)] -## CWindow::IsWindowUnicode +## `CWindow::IsWindowUnicode` Determines whether the specified window is a native Unicode window. @@ -1557,13 +1550,13 @@ BOOL IsWindowUnicode() throw(); ### Remarks -See [IsWindowUnicode](/windows/win32/api/winuser/nf-winuser-iswindowunicode) in the Windows SDK. +See [`IsWindowUnicode`](/windows/win32/api/winuser/nf-winuser-iswindowunicode) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#23](../../atl/codesnippet/cpp/cwindow-class_23.cpp)] -## CWindow::IsZoomed +## `CWindow::IsZoomed` Determines whether the window is maximized. @@ -1573,9 +1566,9 @@ BOOL IsZoomed() const throw(); ### Remarks -See [IsZoomed](/windows/win32/api/winuser/nf-winuser-iszoomed) in the Windows SDK. +See [`IsZoomed`](/windows/win32/api/winuser/nf-winuser-iszoomed) in the Windows SDK. -## CWindow::KillTimer +## `CWindow::KillTimer` Destroys a timer event created by `CWindow::SetTimer`. @@ -1585,11 +1578,11 @@ BOOL KillTimer(UINT nIDEvent) throw(); ### Remarks -See [KillTimer](/windows/win32/api/winuser/nf-winuser-killtimer) in the Windows SDK. +See [`KillTimer`](/windows/win32/api/winuser/nf-winuser-killtimer) in the Windows SDK. -## CWindow::LockWindowUpdate +## `CWindow::LockWindowUpdate` -Disables or enables drawing in the window by calling the [LockWindowUpdate](/windows/win32/api/winuser/nf-winuser-lockwindowupdate) Win32 function. +Disables or enables drawing in the window by calling the [`LockWindowUpdate`](/windows/win32/api/winuser/nf-winuser-lockwindowupdate) Win32 function. ``` BOOL LockWindowUpdate(BOOL bLock = TRUE) throw(); @@ -1597,18 +1590,18 @@ BOOL LockWindowUpdate(BOOL bLock = TRUE) throw(); ### Parameters -*bLock*
-[in] If TRUE (the default value), the window will be locked. Otherwise, it will be unlocked. +*`bLock`*\ +[in] If `TRUE` (the default value), the window will be locked. Otherwise, it will be unlocked. ### Return Value -TRUE if the window is successfully locked; otherwise, FALSE. +`TRUE` if the window is successfully locked; otherwise, `FALSE`. ### Remarks -If *bLock* is TRUE, this method passes [m_hWnd](#m_hwnd) to the Win32 function; otherwise, it passes NULL. +If *`bLock`* is `TRUE`, this method passes [`m_hWnd`](#m_hwnd) to the Win32 function; otherwise, it passes `NULL`. -## CWindow::m_hWnd +## `CWindow::m_hWnd` Contains a handle to the window associated with the `CWindow` object. @@ -1616,7 +1609,7 @@ Contains a handle to the window associated with the `CWindow` object. HWND m_hWnd throw() throw(); ``` -## CWindow::MapWindowPoints +## `CWindow::MapWindowPoints` Converts a set of points from the window's coordinate space to the coordinate space of another window. @@ -1633,11 +1626,11 @@ int MapWindowPoints( ### Remarks -See [MapWindowPoints](/windows/win32/api/winuser/nf-winuser-mapwindowpoints) in the Windows SDK. +See [`MapWindowPoints`](/windows/win32/api/winuser/nf-winuser-mapwindowpoints) in the Windows SDK. -The second version of this method allows you to convert the coordinates of a [RECT](/windows/win32/api/windef/ns-windef-rect) structure. +The second version of this method allows you to convert the coordinates of a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure. -## CWindow::MessageBox +## `CWindow::MessageBox` Displays a message box. @@ -1650,13 +1643,13 @@ int MessageBox( ### Remarks -See [MessageBox](/windows/win32/api/winuser/nf-winuser-messagebox) in the Windows SDK. +See [`MessageBox`](/windows/win32/api/winuser/nf-winuser-messagebox) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#24](../../atl/codesnippet/cpp/cwindow-class_24.cpp)] -## CWindow::ModifyStyle +## `CWindow::ModifyStyle` Modifies the window styles of the `CWindow` object. @@ -1669,40 +1662,40 @@ BOOL ModifyStyle( ### Parameters -*dwRemove*
+*`dwRemove`*\ [in] Specifies the window styles to be removed during style modification. -*dwAdd*
+*`dwAdd`*\ [in] Specifies the window styles to be added during style modification. -*nFlags*
-[in] Window-positioning flags. For a list of possible values, see the [SetWindowPos](/windows/win32/api/winuser/nf-winuser-setwindowpos) function in the Windows SDK. +*`nFlags`*\ +[in] Window-positioning flags. For a list of possible values, see the [`SetWindowPos`](/windows/win32/api/winuser/nf-winuser-setwindowpos) function in the Windows SDK. ### Return Value -TRUE if the window styles are modified; otherwise, FALSE. +`TRUE` if the window styles are modified; otherwise, `FALSE`. ### Remarks -Styles to be added or removed can be combined by using the bitwise OR ( | ) operator. See the [CreateWindow](/windows/win32/api/winuser/nf-winuser-createwindoww) function in the Windows SDKfor information about the available window styles. +Styles to be added or removed can be combined by using the bitwise "or" (`|`) operator. See the [`CreateWindow`](/windows/win32/api/winuser/nf-winuser-createwindoww) function in the Windows SDKfor information about the available window styles. -If *nFlags* is nonzero, `ModifyStyle` calls the Win32 function `SetWindowPos`, and redraws the window by combining *nFlags* with the following four flags: +If *`nFlags`* is nonzero, `ModifyStyle` calls the Win32 function `SetWindowPos`, and redraws the window by combining *`nFlags`* with the following four flags: -- SWP_NOSIZE Retains the current size. +- `SWP_NOSIZE` Retains the current size. -- SWP_NOMOVE Retains the current position. +- `SWP_NOMOVE` Retains the current position. -- SWP_NOZORDER Retains the current Z order. +- `SWP_NOZORDER` Retains the current Z order. -- SWP_NOACTIVATE Does not activate the window. +- `SWP_NOACTIVATE` Doesn't activate the window. -To modify a window's extended styles, call [ModifyStyleEx](#modifystyleex). +To modify a window's extended styles, call [`ModifyStyleEx`](#modifystyleex). ### Example [!code-cpp[NVC_ATL_Windowing#25](../../atl/codesnippet/cpp/cwindow-class_25.cpp)] -## CWindow::ModifyStyleEx +## `CWindow::ModifyStyleEx` Modifies the extended window styles of the `CWindow` object. @@ -1715,40 +1708,40 @@ BOOL ModifyStyleEx( ### Parameters -*dwRemove*
+*`dwRemove`*\ [in] Specifies the extended styles to be removed during style modification. -*dwAdd*
+*`dwAdd`*\ [in] Specifies the extended styles to be added during style modification. -*nFlags*
-[in] Window-positioning flags. For a list of possible values, see the [SetWindowPos](/windows/win32/api/winuser/nf-winuser-setwindowpos) function in the Windows SDK. +*`nFlags`*\ +[in] Window-positioning flags. For a list of possible values, see the [`SetWindowPos`](/windows/win32/api/winuser/nf-winuser-setwindowpos) function in the Windows SDK. ### Return Value -TRUE if the extended window styles are modified; otherwise, FALSE. +`TRUE` if the extended window styles are modified; otherwise, `FALSE`. ### Remarks -Styles to be added or removed can be combined by using the bitwise OR ( | ) operator. See the [CreateWindowEx](/windows/win32/api/winuser/nf-winuser-createwindowexw) function in the Windows SDKfor information about the available extended styles. +Styles to be added or removed can be combined by using the bitwise "or" (`|`) operator. See the [`CreateWindowEx`](/windows/win32/api/winuser/nf-winuser-createwindowexw) function in the Windows SDK for information about the available extended styles. -If *nFlags* is nonzero, `ModifyStyleEx` calls the Win32 function `SetWindowPos`, and redraws the window by combining *nFlags* with the following four flags: +If *`nFlags`* is nonzero, `ModifyStyleEx` calls the Win32 function `SetWindowPos`, and redraws the window by combining *`nFlags`* with the following four flags: -- SWP_NOSIZE Retains the current size. +- `SWP_NOSIZE` Retains the current size. -- SWP_NOMOVE Retains the current position. +- `SWP_NOMOVE` Retains the current position. -- SWP_NOZORDER Retains the current Z order. +- `SWP_NOZORDER` Retains the current Z order. -- SWP_NOACTIVATE Does not activate the window. +- `SWP_NOACTIVATE` Doesn't activate the window. -To modify windows using regular window styles, call [ModifyStyle](#modifystyle). +To modify windows using regular window styles, call [`ModifyStyle`](#modifystyle). ### Example [!code-cpp[NVC_ATL_Windowing#26](../../atl/codesnippet/cpp/cwindow-class_26.cpp)] -## CWindow::MoveWindow +## `CWindow::MoveWindow` Changes the window's size and position. @@ -1767,11 +1760,11 @@ BOOL MoveWindow( ### Remarks -For a top-level window object, the x and y parameters are relative to the upper-left corner of the screen. For a child window object, they are relative to the upper-left corner of the parent window's client area. +For a top-level window object, the `x` and `y` parameters are relative to the upper-left corner of the screen. For a child window object, they're relative to the upper-left corner of the parent window's client area. -The second version of this method uses a [RECT](/windows/win32/api/windef/ns-windef-rect) structure to determine the window's new position, width, and height. +The second version of this method uses a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure to determine the window's new position, width, and height. -## CWindow::NextDlgCtrl +## `CWindow::NextDlgCtrl` Sets the keyboard focus to the next control in the dialog box. @@ -1781,9 +1774,9 @@ void NextDlgCtrl() const throw(); ### Remarks -See [WM_NEXTDLGCTL](/windows/win32/dlgbox/wm-nextdlgctl) in the Windows SDK. +See [`WM_NEXTDLGCTL`](/windows/win32/dlgbox/wm-nextdlgctl) in the Windows SDK. -## CWindow::OpenClipboard +## `CWindow::OpenClipboard` Opens the Clipboard. @@ -1793,25 +1786,25 @@ BOOL OpenClipboard() throw(); ### Remarks -See [OpenClipboard](/windows/win32/api/winuser/nf-winuser-openclipboard) in the Windows SDK. +See [`OpenClipboard`](/windows/win32/api/winuser/nf-winuser-openclipboard) in the Windows SDK. -## CWindow::operator HWND +## `CWindow::operator HWND` -Converts a `CWindow` object to an HWND. +Converts a `CWindow` object to an `HWND`. ``` operator HWND() const throw(); ``` -## CWindow::operator = +## `CWindow::operator =` -Assigns an HWND to the `CWindow` object by setting the [m_hWnd](#m_hwnd) member to `hWnd`. +Assigns an `HWND` to the `CWindow` object by setting the [`m_hWnd`](#m_hwnd) member to `hWnd`. ``` CWindow& operator= (HWND hWnd) throw(); ``` -## CWindow::PostMessage +## `CWindow::PostMessage` Places a message in the message queue associated with the thread that created the window. @@ -1824,7 +1817,7 @@ BOOL PostMessage( ### Remarks -See [PostMessage](/windows/win32/api/winuser/nf-winuser-postmessagew) in the Windows SDK. +See [`PostMessage`](/windows/win32/api/winuser/nf-winuser-postmessagew) in the Windows SDK. Returns without waiting for the thread to process the message. @@ -1832,7 +1825,7 @@ Returns without waiting for the thread to process the message. [!code-cpp[NVC_ATL_Windowing#27](../../atl/codesnippet/cpp/cwindow-class_27.cpp)] -## CWindow::PrevDlgCtrl +## `CWindow::PrevDlgCtrl` Sets the keyboard focus to the previous control in the dialog box. @@ -1842,11 +1835,11 @@ void PrevDlgCtrl() const throw(); ### Remarks -See [WM_NEXTDLGCTL](/windows/win32/dlgbox/wm-nextdlgctl) in the Windows SDK. +See [`WM_NEXTDLGCTL`](/windows/win32/dlgbox/wm-nextdlgctl) in the Windows SDK. -## CWindow::Print +## `CWindow::Print` -Sends a [WM_PRINT](/windows/win32/gdi/wm-print) message to the window to request that it draw itself in the specified device context. +Sends a [`WM_PRINT`](/windows/win32/gdi/wm-print) message to the window to request that it draw itself in the specified device context. ```cpp void Print(HDC hDC, DWORD dwFlags) const throw(); @@ -1854,27 +1847,27 @@ void Print(HDC hDC, DWORD dwFlags) const throw(); ### Parameters -*hDC*
+*`hDC`*\ [in] The handle to a device context. -*dwFlags*
+*`dwFlags`*\ [in] Specifies the drawing options. You can combine one or more of the following flags: -- PRF_CHECKVISIBLE Draw the window only if it is visible. +- `PRF_CHECKVISIBLE` Draw the window only if it's visible. -- PRF_CHILDREN Draw all visible child windows. +- `PRF_CHILDREN` Draw all visible child windows. -- PRF_CLIENT Draw the client area of the window. +- `PRF_CLIENT` Draw the client area of the window. -- PRF_ERASEBKGND Erase the background before drawing the window. +- `PRF_ERASEBKGND` Erase the background before drawing the window. -- PRF_NONCLIENT Draw the non-client area of the window. +- `PRF_NONCLIENT` Draw the non-client area of the window. -- PRF_OWNED Draw all owned windows. +- `PRF_OWNED` Draw all owned windows. -## CWindow::PrintClient +## `CWindow::PrintClient` -Sends a [WM_PRINTCLIENT](/windows/win32/gdi/wm-printclient) message to the window to request that it draw its client area in the specified device context. +Sends a [`WM_PRINTCLIENT`](/windows/win32/gdi/wm-printclient) message to the window to request that it draw its client area in the specified device context. ```cpp void PrintClient(HDC hDC, DWORD dwFlags) const throw(); @@ -1882,25 +1875,25 @@ void PrintClient(HDC hDC, DWORD dwFlags) const throw(); ### Parameters -*hDC*
+*`hDC`*\ [in] The handle to a device context. -*dwFlags*
+*`dwFlags`*\ [in] Specifies drawing options. You can combine one or more of the following flags: -- PRF_CHECKVISIBLE Draw the window only if it is visible. +- `PRF_CHECKVISIBLE` Draw the window only if it's visible. -- PRF_CHILDREN Draw all visible child windows. +- `PRF_CHILDREN` Draw all visible child windows. -- PRF_CLIENT Draw the client area of the window. +- `PRF_CLIENT` Draw the client area of the window. -- PRF_ERASEBKGND Erase the background before drawing the window. +- `PRF_ERASEBKGND` Erase the background before drawing the window. -- PRF_NONCLIENT Draw the non-client area of the window. +- `PRF_NONCLIENT` Draw the non-client area of the window. -- PRF_OWNED Draw all owned windows. +- `PRF_OWNED` Draw all owned windows. -## CWindow::rcDefault +## `CWindow::rcDefault` Contains default window dimensions. @@ -1908,7 +1901,7 @@ Contains default window dimensions. static RECT rcDefault; ``` -## CWindow::RedrawWindow +## `CWindow::RedrawWindow` Updates a specified rectangle or region in the client area. @@ -1923,13 +1916,13 @@ throw() ### Remarks -See [RedrawWindow](/windows/win32/api/winuser/nf-winuser-redrawwindow) in the Windows SDK. +See [`RedrawWindow`](/windows/win32/api/winuser/nf-winuser-redrawwindow) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#28](../../atl/codesnippet/cpp/cwindow-class_28.cpp)] -## CWindow::ReleaseDC +## `CWindow::ReleaseDC` Releases a device context. @@ -1939,13 +1932,13 @@ int ReleaseDC(HDC hDC); ### Remarks -See [ReleaseDC](/windows/win32/api/winuser/nf-winuser-releasedc) in the Windows SDK. +See [`ReleaseDC`](/windows/win32/api/winuser/nf-winuser-releasedc) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#9](../../atl/codesnippet/cpp/cwindow-class_9.cpp)] -## CWindow::ResizeClient +## `CWindow::ResizeClient` Resizes the window to the specified client area size. @@ -1958,16 +1951,16 @@ BOOL ResizeClient( ### Parameters -*nWidth*
+*`nWidth`*\ New width of the window in pixels. -*nHeight*
+*`nHeight`*\ New height of the window in pixels. -*bRedraw*
-A flag indicating whether to redraw changes. Default is FALSE, indicating the window does not redraw changes. +*`bRedraw`*\ +A flag indicating whether to redraw changes. Default is `FALSE`, indicating the window doesn't redraw changes. -## CWindow::ScreenToClient +## `CWindow::ScreenToClient` Converts screen coordinates to client coordinates. @@ -1978,11 +1971,11 @@ BOOL ScreenToClient(LPRECT lpRect) const throw(); ### Remarks -See [ScreenToClient](/windows/win32/api/winuser/nf-winuser-screentoclient) in the Windows SDK. +See [`ScreenToClient`](/windows/win32/api/winuser/nf-winuser-screentoclient) in the Windows SDK. -The second version of this method allows you to convert the coordinates of a [RECT](/windows/win32/api/windef/ns-windef-rect) structure. +The second version of this method allows you to convert the coordinates of a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure. -## CWindow::ScrollWindow +## `CWindow::ScrollWindow` Scrolls the specified client area. @@ -1996,9 +1989,9 @@ BOOL ScrollWindow( ### Remarks -See [ScrollWindow](/windows/win32/api/winuser/nf-winuser-scrollwindow) in the Windows SDK. +See [`ScrollWindow`](/windows/win32/api/winuser/nf-winuser-scrollwindow) in the Windows SDK. -## CWindow::ScrollWindowEx +## `CWindow::ScrollWindowEx` Scrolls the specified client area with additional features. @@ -2015,9 +2008,9 @@ int ScrollWindowEx( ### Remarks -See [ScrollWindowEx](/windows/win32/api/winuser/nf-winuser-scrollwindowex) in the Windows SDK. +See [`ScrollWindowEx`](/windows/win32/api/winuser/nf-winuser-scrollwindowex) in the Windows SDK. -## CWindow::SendDlgItemMessage +## `CWindow::SendDlgItemMessage` Sends a message to a control. @@ -2031,11 +2024,11 @@ LRESULT SendDlgItemMessage( ### Remarks -See [SendDlgItemMessage](/windows/win32/api/winuser/nf-winuser-senddlgitemmessagew) in the Windows SDK. +See [`SendDlgItemMessage`](/windows/win32/api/winuser/nf-winuser-senddlgitemmessagew) in the Windows SDK. -## CWindow::SendMessage +## `CWindow::SendMessage` -Sends a message to the window and does not return until the window procedure has processed the message. +Sends a message to the window and doesn't return until the window procedure has processed the message. ``` LRESULT SendMessage( @@ -2052,13 +2045,13 @@ static LRESULT SendMessage( ### Remarks -See [SendMessage](/windows/win32/api/winuser/nf-winuser-sendmessage) in the Windows SDK. +See [`SendMessage`](/windows/win32/api/winuser/nf-winuser-sendmessage) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#29](../../atl/codesnippet/cpp/cwindow-class_29.cpp)] -## CWindow::SendMessageToDescendants +## `CWindow::SendMessageToDescendants` Sends the specified message to all immediate children of the `CWindow` object. @@ -2072,23 +2065,23 @@ void SendMessageToDescendants( ### Parameters -*message*
+*`message`*\ [in] The message to be sent. -*wParam*
+*`wParam`*\ [in] Additional message-specific information. -*lParam*
+*`lParam`*\ [in] Additional message-specific information. -*bDeep*
-[in] If TRUE (the default value), the message will be sent to all descendant windows; otherwise, it will be sent only to the immediate child windows. +*`bDeep`*\ +[in] If `TRUE` (the default value), the message will be sent to all descendant windows; otherwise, it will be sent only to the immediate child windows. ### Remarks -If *bDeep* is TRUE, the message is additionally sent to all other descendant windows. +If *`bDeep`* is `TRUE`, the message is additionally sent to all other descendant windows. -## CWindow::SendNotifyMessage +## `CWindow::SendNotifyMessage` Sends a message to the window. @@ -2101,11 +2094,11 @@ BOOL SendNotifyMessage( ### Remarks -See [SendNotifyMessage](/windows/win32/api/winuser/nf-winuser-sendnotifymessagew) in the Windows SDK. +See [`SendNotifyMessage`](/windows/win32/api/winuser/nf-winuser-sendnotifymessagew) in the Windows SDK. -If the window was created by the calling thread, `SendNotifyMessage` does not return until the window procedure has processed the message. Otherwise, it returns immediately. +If the window was created by the calling thread, `SendNotifyMessage` doesn't return until the window procedure has processed the message. Otherwise, it returns immediately. -## CWindow::SetActiveWindow +## `CWindow::SetActiveWindow` Activates the window. @@ -2115,13 +2108,13 @@ HWND SetActiveWindow() throw(); ### Remarks -See [SetActiveWindow](/windows/win32/api/winuser/nf-winuser-setactivewindow) in the Windows SDK. +See [`SetActiveWindow`](/windows/win32/api/winuser/nf-winuser-setactivewindow) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#30](../../atl/codesnippet/cpp/cwindow-class_30.cpp)] -## CWindow::SetCapture +## `CWindow::SetCapture` Sends all subsequent mouse input to the window. @@ -2131,9 +2124,9 @@ HWND SetCapture() throw(); ### Remarks -See [SetCapture](/windows/win32/api/winuser/nf-winuser-setcapture) in the Windows SDK. +See [`SetCapture`](/windows/win32/api/winuser/nf-winuser-setcapture) in the Windows SDK. -## CWindow::SetClipboardViewer +## `CWindow::SetClipboardViewer` Adds the window to the Clipboard viewer chain. @@ -2143,9 +2136,9 @@ HWND SetClipboardViewer() throw(); ### Remarks -See [SetClipboardViewer](/windows/win32/api/winuser/nf-winuser-setclipboardviewer) in the Windows SDK. +See [`SetClipboardViewer`](/windows/win32/api/winuser/nf-winuser-setclipboardviewer) in the Windows SDK. -## CWindow::SetDlgCtrlID +## `CWindow::SetDlgCtrlID` Sets the identifier of the window to the specified value. @@ -2155,14 +2148,14 @@ int SetDlgCtrlID(int nID) throw(); ### Parameters -*nID*
+*`nID`*\ [in] The new value to set for the window's identifier. ### Return Value If successful, the previous identifier of the window; otherwise 0. -## CWindow::SetDlgItemInt +## `CWindow::SetDlgItemInt` Changes a control's text to the string representation of an integer value. @@ -2175,9 +2168,9 @@ BOOL SetDlgItemInt( ### Remarks -See [SetDlgItemInt](/windows/win32/api/winuser/nf-winuser-setdlgitemint) in the Windows SDK. +See [`SetDlgItemInt`](/windows/win32/api/winuser/nf-winuser-setdlgitemint) in the Windows SDK. -## CWindow::SetDlgItemText +## `CWindow::SetDlgItemText` Changes a control's text. @@ -2187,9 +2180,9 @@ BOOL SetDlgItemText(int nID, LPCTSTR lpszString) throw(); ### Remarks -See [SetDlgItemText](/windows/win32/api/winuser/nf-winuser-setdlgitemtextw) in the Windows SDK. +See [`SetDlgItemText`](/windows/win32/api/winuser/nf-winuser-setdlgitemtextw) in the Windows SDK. -## CWindow::SetFocus +## `CWindow::SetFocus` Sets the input focus to the window. @@ -2199,15 +2192,15 @@ HWND SetFocus() throw(); ### Remarks -See [SetFocus](/windows/win32/api/winuser/nf-winuser-setfocus) in the Windows SDK. +See [`SetFocus`](/windows/win32/api/winuser/nf-winuser-setfocus) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#31](../../atl/codesnippet/cpp/cwindow-class_31.cpp)] -## CWindow::SetFont +## `CWindow::SetFont` -Changes the window's current font by sending a [WM_SETFONT](/windows/win32/winmsg/wm-setfont) message to the window. +Changes the window's current font by sending a [`WM_SETFONT`](/windows/win32/winmsg/wm-setfont) message to the window. ```cpp void SetFont(HFONT hFont, BOOL bRedraw = TRUE) throw(); @@ -2215,15 +2208,15 @@ void SetFont(HFONT hFont, BOOL bRedraw = TRUE) throw(); ### Parameters -*hFont*
+*`hFont`*\ [in] The handle to the new font. -*bRedraw*
-[in] If TRUE (the default value), the window is redrawn. Otherwise, it is not. +*`bRedraw`*\ +[in] If `TRUE` (the default value), the window is redrawn. Otherwise, it isn't. -## CWindow::SetHotKey +## `CWindow::SetHotKey` -Associates a hot key with the window by sending a WM_SETHOTKEY message. +Associates a hot key with the window by sending a `WM_SETHOTKEY` message. ``` int SetHotKey(WORD wVirtualKeyCode, WORD wModifiers) throw(); @@ -2231,19 +2224,19 @@ int SetHotKey(WORD wVirtualKeyCode, WORD wModifiers) throw(); ### Parameters -*wVirtualKeyCode*
-[in] The virtual key code of the hot key. For a list of standard virtual key codes, see Winuser.h. +*`wVirtualKeyCode`*\ +[in] The virtual key code of the hot key. For a list of standard virtual key codes, see `Winuser.h`. -*wModifiers*
-[in] The modifiers of the hot key. For a list of possible values, see WM_SETHOTKEY in the Windows SDK. +*`wModifiers`*\ +[in] The modifiers of the hot key. For a list of possible values, see `WM_SETHOTKEY` in the Windows SDK. ### Return Value -For a list of possible return values, see [WM_SETHOTKEY](/windows/win32/inputdev/wm-sethotkey) in the Windows SDK. +For a list of possible return values, see [`WM_SETHOTKEY`](/windows/win32/inputdev/wm-sethotkey) in the Windows SDK. -## CWindow::SetIcon +## `CWindow::SetIcon` -Sets the window's large or small icon to the icon identified by *hIcon*. +Sets the window's large or small icon to the icon identified by *`hIcon`*. ``` HICON SetIcon(HICON hIcon, BOOL bBigIcon = TRUE) throw(); @@ -2251,11 +2244,11 @@ HICON SetIcon(HICON hIcon, BOOL bBigIcon = TRUE) throw(); ### Parameters -*hIcon*
+*`hIcon`*\ [in] The handle to a new icon. -*bBigIcon*
-[in] If TRUE (the default value), the method sets a large icon. Otherwise, it sets a small icon. +*`bBigIcon`*\ +[in] If `TRUE` (the default value), the method sets a large icon. Otherwise, it sets a small icon. ### Return Value @@ -2263,9 +2256,9 @@ The handle to the previous icon. ### Remarks -`SetIcon` sends a [WM_SETICON](/windows/win32/winmsg/wm-seticon) message to the window. +`SetIcon` sends a [`WM_SETICON`](/windows/win32/winmsg/wm-seticon) message to the window. -## CWindow::SetMenu +## `CWindow::SetMenu` Changes the window's current menu. @@ -2275,9 +2268,9 @@ BOOL SetMenu(HMENU hMenu) throw(); ### Remarks -See [SetMenu](/windows/win32/api/winuser/nf-winuser-setmenu) in the Windows SDK. +See [`SetMenu`](/windows/win32/api/winuser/nf-winuser-setmenu) in the Windows SDK. -## CWindow::SetParent +## `CWindow::SetParent` Changes the parent window. @@ -2287,15 +2280,15 @@ HWND SetParent(HWND hWndNewParent) throw(); ### Remarks -See [SetParent](/windows/win32/api/winuser/nf-winuser-setparent) in the Windows SDK. +See [`SetParent`](/windows/win32/api/winuser/nf-winuser-setparent) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#32](../../atl/codesnippet/cpp/cwindow-class_32.cpp)] -## CWindow::SetRedraw +## `CWindow::SetRedraw` -Sets or clears the redraw flag by sending a [WM_SETREDRAW](/windows/win32/gdi/wm-setredraw) message to the window. +Sets or clears the redraw flag by sending a [`WM_SETREDRAW`](/windows/win32/gdi/wm-setredraw) message to the window. ```cpp void SetRedraw(BOOL bRedraw = TRUE) throw(); @@ -2303,8 +2296,8 @@ void SetRedraw(BOOL bRedraw = TRUE) throw(); ### Parameters -*bRedraw*
-[in] Specifies the state of the redraw flag. If TRUE (the default value), the redraw flag is set; if FALSE, the flag is cleared. +*`bRedraw`*\ +[in] Specifies the state of the redraw flag. If `TRUE` (the default value), the redraw flag is set; if `FALSE`, the flag is cleared. ### Remarks @@ -2314,7 +2307,7 @@ Call `SetRedraw` to allow changes to be redrawn or to prevent changes from being [!code-cpp[NVC_ATL_Windowing#33](../../atl/codesnippet/cpp/cwindow-class_33.cpp)] -## CWindow::SetScrollInfo +## `CWindow::SetScrollInfo` Sets the parameters of a scroll bar. @@ -2327,9 +2320,9 @@ int SetScrollInfo( ### Remarks -See [SetScrollInfo](/windows/win32/api/winuser/nf-winuser-setscrollinfo) in the Windows SDK. +See [`SetScrollInfo`](/windows/win32/api/winuser/nf-winuser-setscrollinfo) in the Windows SDK. -## CWindow::SetScrollPos +## `CWindow::SetScrollPos` Changes the position of the scroll box. @@ -2342,9 +2335,9 @@ int SetScrollPos( ### Remarks -See [SetScrollPos](/windows/win32/api/winuser/nf-winuser-setscrollpos) in the Windows SDK. +See [`SetScrollPos`](/windows/win32/api/winuser/nf-winuser-setscrollpos) in the Windows SDK. -## CWindow::SetScrollRange +## `CWindow::SetScrollRange` Changes the scroll bar range. @@ -2358,9 +2351,9 @@ BOOL SetScrollRange( ### Remarks -See [SetScrollRange](/windows/win32/api/winuser/nf-winuser-setscrollrange) in the Windows SDK. +See [`SetScrollRange`](/windows/win32/api/winuser/nf-winuser-setscrollrange) in the Windows SDK. -## CWindow::SetTimer +## `CWindow::SetTimer` Creates a timer event. @@ -2373,9 +2366,9 @@ UINT SetTimer( ### Remarks -See [SetTimer](/windows/win32/api/winuser/nf-winuser-settimer) in the Windows SDK. +See [`SetTimer`](/windows/win32/api/winuser/nf-winuser-settimer) in the Windows SDK. -## CWindow::SetWindowContextHelpId +## `CWindow::SetWindowContextHelpId` Sets the window's help context identifier. @@ -2385,9 +2378,9 @@ BOOL SetWindowContextHelpId(DWORD dwContextHelpId) throw(); ### Remarks -See [SetWindowContextHelpId](/windows/win32/api/winuser/nf-winuser-setwindowcontexthelpid) in the Windows SDK. +See [`SetWindowContextHelpId`](/windows/win32/api/winuser/nf-winuser-setwindowcontexthelpid) in the Windows SDK. -## CWindow::SetWindowLong +## `CWindow::SetWindowLong` Sets a 32-bit value at a specified offset into the extra window memory. @@ -2397,12 +2390,12 @@ LONG SetWindowLong(int nIndex, LONG dwNewLong) throw(); ### Remarks -See [SetWindowLong](/windows/win32/api/winuser/nf-winuser-setwindowlongw) in the Windows SDK. +See [`SetWindowLong`](/windows/win32/api/winuser/nf-winuser-setwindowlongw) in the Windows SDK. > [!NOTE] -> To write code that is compatible with both 32-bit and 64-bit versions of Windows, use [CWindow::SetWindowLongPtr](#setwindowlongptr). +> To write code that is compatible with both 32-bit and 64-bit versions of Windows, use [`CWindow::SetWindowLongPtr`](#setwindowlongptr). -## CWindow::SetWindowLongPtr +## `CWindow::SetWindowLongPtr` Changes an attribute of the specified window, and also sets a value at the specified offset in the extra window memory. @@ -2412,11 +2405,11 @@ LONG_PTR SetWindowLongPtr(int nIndex, LONG_PTR dwNewLong) throw(); ### Remarks -See [SetWindowLongPtr](/windows/win32/api/winuser/nf-winuser-setwindowlongptrw) in the Windows SDK. +See [`SetWindowLongPtr`](/windows/win32/api/winuser/nf-winuser-setwindowlongptrw) in the Windows SDK. This function supersedes the `CWindow::SetWindowLong` method. To write code that is compatible with both 32-bit and 64-bit versions of Windows, use `CWindow::SetWindowLongPtr`. -## CWindow::SetWindowPlacement +## `CWindow::SetWindowPlacement` Sets the show state and positions. @@ -2426,9 +2419,9 @@ BOOL SetWindowPlacement(const WINDOWPLACEMENT FAR* lpwndpl); ### Remarks -See [SetWindowPlacement](/windows/win32/api/winuser/nf-winuser-setwindowplacement) in the Windows SDK. +See [`SetWindowPlacement`](/windows/win32/api/winuser/nf-winuser-setwindowplacement) in the Windows SDK. -## CWindow::SetWindowPos +## `CWindow::SetWindowPos` Sets the size, position, and Z order. @@ -2449,11 +2442,11 @@ BOOL SetWindowPos( ### Remarks -See [SetWindowPos](/windows/win32/api/winuser/nf-winuser-setwindowpos) in the Windows SDK. +See [`SetWindowPos`](/windows/win32/api/winuser/nf-winuser-setwindowpos) in the Windows SDK. -The second version of this method uses a [RECT](/windows/win32/api/windef/ns-windef-rect) structure to set the window's new position, width, and height. +The second version of this method uses a [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure to set the window's new position, width, and height. -## CWindow::SetWindowRgn +## `CWindow::SetWindowRgn` Sets the window region of a window. @@ -2463,9 +2456,9 @@ int SetWindowRgn(HRGN hRgn, BOOL bRedraw = FALSE) throw(); ### Remarks -See [SetWindowRgn](/windows/win32/api/winuser/nf-winuser-setwindowrgn) in the Windows SDK. +See [`SetWindowRgn`](/windows/win32/api/winuser/nf-winuser-setwindowrgn) in the Windows SDK. -## CWindow::SetWindowText +## `CWindow::SetWindowText` Changes the window's text. @@ -2475,13 +2468,13 @@ BOOL SetWindowText(LPCTSTR lpszString) throw(); ### Remarks -See [SetWindowText](/windows/win32/api/winuser/nf-winuser-setwindowtextw) in the Windows SDK. +See [`SetWindowText`](/windows/win32/api/winuser/nf-winuser-setwindowtextw) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#34](../../atl/codesnippet/cpp/cwindow-class_34.cpp)] -## CWindow::SetWindowWord +## `CWindow::SetWindowWord` Sets a 16-bit value at a specified offset into the extra window memory. @@ -2491,9 +2484,9 @@ WORD SetWindowWord(int nIndex, WORD wNewWord) throw(); ### Remarks -See [SetWindowLong](/windows/win32/api/winuser/nf-winuser-setwindowlongw) in the Windows SDK. +See [`SetWindowLong`](/windows/win32/api/winuser/nf-winuser-setwindowlongw) in the Windows SDK. -## CWindow::ShowCaret +## `CWindow::ShowCaret` Displays the system caret. @@ -2503,13 +2496,13 @@ BOOL ShowCaret() throw(); ### Remarks -See [ShowCaret](/windows/win32/api/winuser/nf-winuser-showcaret) in the Windows SDK. +See [`ShowCaret`](/windows/win32/api/winuser/nf-winuser-showcaret) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#35](../../atl/codesnippet/cpp/cwindow-class_35.cpp)] -## CWindow::ShowOwnedPopups +## `CWindow::ShowOwnedPopups` Shows or hides the pop-up windows owned by the window. @@ -2519,9 +2512,9 @@ BOOL ShowOwnedPopups(BOOL bShow = TRUE) throw(); ### Remarks -See [ShowOwnedPopups](/windows/win32/api/winuser/nf-winuser-showownedpopups) in the Windows SDK. +See [`ShowOwnedPopups`](/windows/win32/api/winuser/nf-winuser-showownedpopups) in the Windows SDK. -## CWindow::ShowScrollBar +## `CWindow::ShowScrollBar` Shows or hides a scroll bar. @@ -2531,9 +2524,9 @@ BOOL ShowScrollBar(UINT nBar, BOOL bShow = TRUE) throw(); ### Remarks -See [ShowScrollBar](/windows/win32/api/winuser/nf-winuser-showscrollbar) in the Windows SDK. +See [`ShowScrollBar`](/windows/win32/api/winuser/nf-winuser-showscrollbar) in the Windows SDK. -## CWindow::ShowWindow +## `CWindow::ShowWindow` Sets the window's show state. @@ -2543,13 +2536,13 @@ BOOL ShowWindow(int nCmdShow) throw(); ### Remarks -See [ShowWindow](/windows/win32/api/winuser/nf-winuser-showwindow) in the Windows SDK. +See [`ShowWindow`](/windows/win32/api/winuser/nf-winuser-showwindow) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#36](../../atl/codesnippet/cpp/cwindow-class_36.cpp)] -## CWindow::ShowWindowAsync +## `CWindow::ShowWindowAsync` Sets the show state of a window created by a different thread. @@ -2559,9 +2552,9 @@ BOOL ShowWindowAsync(int nCmdShow) throw(); ### Remarks -See [ShowWindowAsync](/windows/win32/api/winuser/nf-winuser-showwindowasync) in the Windows SDK. +See [`ShowWindowAsync`](/windows/win32/api/winuser/nf-winuser-showwindowasync) in the Windows SDK. -## CWindow::UpdateWindow +## `CWindow::UpdateWindow` Updates the client area. @@ -2571,13 +2564,13 @@ BOOL UpdateWindow() throw(); ### Remarks -See [UpdateWindow](/windows/win32/api/winuser/nf-winuser-updatewindow) in the Windows SDK. +See [`UpdateWindow`](/windows/win32/api/winuser/nf-winuser-updatewindow) in the Windows SDK. ### Example [!code-cpp[NVC_ATL_Windowing#37](../../atl/codesnippet/cpp/cwindow-class_37.cpp)] -## CWindow::ValidateRect +## `CWindow::ValidateRect` Validates the client area within the specified rectangle. @@ -2587,9 +2580,9 @@ BOOL ValidateRect(LPCRECT lpRect) throw(); ### Remarks -See [ValidateRect](/windows/win32/api/winuser/nf-winuser-validaterect) in the Windows SDK. +See [`ValidateRect`](/windows/win32/api/winuser/nf-winuser-validaterect) in the Windows SDK. -## CWindow::ValidateRgn +## `CWindow::ValidateRgn` Validates the client area within the specified region. @@ -2599,9 +2592,9 @@ BOOL ValidateRgn(HRGN hRgn) throw(); ### Remarks -See [ValidateRgn](/windows/win32/api/winuser/nf-winuser-validatergn) in the Windows SDK. +See [`ValidateRgn`](/windows/win32/api/winuser/nf-winuser-validatergn) in the Windows SDK. -## CWindow::WinHelp +## `CWindow::WinHelp` Starts Windows Help. @@ -2614,7 +2607,7 @@ BOOL WinHelp( ### Remarks -See [WinHelp](/windows/win32/api/winuser/nf-winuser-winhelpw) in the Windows SDK. +See [`WinHelp`](/windows/win32/api/winuser/nf-winuser-winhelpw) in the Windows SDK. ## See also diff --git a/docs/atl/reference/cwindowimpl-class.md b/docs/atl/reference/cwindowimpl-class.md index 79957ded9b..d2041bc669 100644 --- a/docs/atl/reference/cwindowimpl-class.md +++ b/docs/atl/reference/cwindowimpl-class.md @@ -276,7 +276,7 @@ virtual void OnFinalMessage(HWND hWnd); ### Remarks -The default implementation of `OnFinalMessage` does nothing, but you can override this function to handle cleanup before destroying a window. If you want to automatically delete your object upon the window destruction, you can call **delete this;** in this function. +The default implementation of `OnFinalMessage` does nothing, but you can override this function to handle cleanup before destroying a window. If you want to automatically delete your object upon the window destruction, you can call `delete this;` in this function. ## CWindowImpl::SubclassWindow diff --git a/docs/atl/reference/debugging-and-error-reporting-macros.md b/docs/atl/reference/debugging-and-error-reporting-macros.md index 59543bc784..463ef4c007 100644 --- a/docs/atl/reference/debugging-and-error-reporting-macros.md +++ b/docs/atl/reference/debugging-and-error-reporting-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: Debugging and Error Reporting Macros" title: "Debugging and Error Reporting Macros" ms.date: "05/06/2019" -f1_keywords: ["atldef/ATL::_ATL_DEBUG_INTERFACES", "atldef/ATL::_ATL_DEBUG_QI", "atldef/ATL::ATLASSERT", "afx/ATL::ATLENSURE", "atltrace/ATL::ATLTRACENOTIMPL", "atltrace/ATL::ATLTRACE"] +f1_keywords: ["atldef/ATL::_ATL_DEBUG_INTERFACES", "atldef/ATL::_ATL_DEBUG_QI", "atldef/ATL::ATLASSERT", "afx/ATL::ATLENSURE", "atltrace/ATL::ATLTRACENOTIMPL", "atltrace/ATL::ATLTRACE", "ATLDEF/_ATL_DEBUG_INTERFACES", "ATLDEF/_ATL_DEBUG_QI", "ATLDEF/ATLASSERT", "AFX/ATLENSURE", "ATLTRACE/ATLTRACENOTIMPL", "ATLTRACE/ATLTRACE", "ATLDEF/ATLSTATIC_ASSERT"] helpviewer_keywords: ["macros, error reporting"] ms.assetid: 4da9b87f-ec5c-4a32-ab93-637780909b9d --- diff --git a/docs/atl/reference/exception-handling-macros.md b/docs/atl/reference/exception-handling-macros.md index b68a348f62..44f9993452 100644 --- a/docs/atl/reference/exception-handling-macros.md +++ b/docs/atl/reference/exception-handling-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: Exception Handling Macros" title: "Exception Handling Macros" ms.date: "11/04/2016" -f1_keywords: ["atldef/ATL::_ATLCATCH", "atldef/ATL::_ATLCATCHALL", "atldef/ATL::_ATLTRY"] +f1_keywords: ["atldef/ATL::_ATLCATCH", "atldef/ATL::_ATLCATCHALL", "atldef/ATL::_ATLTRY", "ATLDEF/_ATLCATCH", "ATLDEF/_ATLCATCHALL", "ATLDEF/_ATLTRY"] helpviewer_keywords: ["exception handling, macros", "C++ exception handling, macros"] ms.assetid: a8385d34-3fb0-4006-a42a-de045cacf0f4 --- diff --git a/docs/atl/reference/iatlmemmgr-class.md b/docs/atl/reference/iatlmemmgr-class.md index 0a2d4ae395..46acd30174 100644 --- a/docs/atl/reference/iatlmemmgr-class.md +++ b/docs/atl/reference/iatlmemmgr-class.md @@ -923,7 +923,7 @@ Calling this method is equivalent to calling [IAxWinHostWindowLic::CreateControl ### Example -See [Hosting ActiveX Controls Using ATL AXHost](../../atl/atl-control-containment-faq.md#hosting-activex-controls-using-atl-axhost) for a sample that uses `IAxWinHostWindowLic::CreateControlLic`. +See [Hosting ActiveX Controls Using ATL AXHost](../../atl/atl-control-containment-faq.yml#hosting-activex-controls-using-atl-axhost) for a sample that uses `IAxWinHostWindowLic::CreateControlLic`. ## IAxWinHostWindowLic::CreateControlLicEx @@ -951,7 +951,7 @@ See [IAxWinHostWindow::CreateControlEx](#createcontrolex) for a description of t ### Example -See [Hosting ActiveX Controls Using ATL AXHost](../../atl/atl-control-containment-faq.md#hosting-activex-controls-using-atl-axhost) for a sample that uses `IAxWinHostWindowLic::CreateControlLicEx`. +See [Hosting ActiveX Controls Using ATL AXHost](../../atl/atl-control-containment-faq.yml#hosting-activex-controls-using-atl-axhost) for a sample that uses `IAxWinHostWindowLic::CreateControlLicEx`. ## See also diff --git a/docs/atl/reference/iaxwinambientdispatch-interface.md b/docs/atl/reference/iaxwinambientdispatch-interface.md index e2b35e3d4c..f1799cf5b2 100644 --- a/docs/atl/reference/iaxwinambientdispatch-interface.md +++ b/docs/atl/reference/iaxwinambientdispatch-interface.md @@ -62,7 +62,7 @@ This interface is exposed by ATL's ActiveX control hosting objects. Call the met If you are linking to ATL90.dll, **AXHost** will load the type information from the typelib in the DLL. -See [Hosting ActiveX Controls Using ATL AXHost](../../atl/atl-control-containment-faq.md#hosting-activex-controls-using-atl-axhost) for more details. +See [Hosting ActiveX Controls Using ATL AXHost](../../atl/atl-control-containment-faq.yml#hosting-activex-controls-using-atl-axhost) for more details. ## Requirements diff --git a/docs/atl/reference/iaxwinambientdispatchex-interface.md b/docs/atl/reference/iaxwinambientdispatchex-interface.md index a33505b351..4df19f4e98 100644 --- a/docs/atl/reference/iaxwinambientdispatchex-interface.md +++ b/docs/atl/reference/iaxwinambientdispatchex-interface.md @@ -37,7 +37,7 @@ This interface is exposed by ATL's ActiveX control hosting objects. Derived from If you are linking to ATL90.dll, **AXHost** will load the type information from the type library in the DLL. -See [Hosting ActiveX Controls Using ATL AXHost](../../atl/atl-control-containment-faq.md#hosting-activex-controls-using-atl-axhost) for more details. +See [Hosting ActiveX Controls Using ATL AXHost](../../atl/atl-control-containment-faq.yml#hosting-activex-controls-using-atl-axhost) for more details. ## Requirements diff --git a/docs/atl/reference/iaxwinhostwindowlic-interface.md b/docs/atl/reference/iaxwinhostwindowlic-interface.md index b37e6f1f25..e2d65671f2 100644 --- a/docs/atl/reference/iaxwinhostwindowlic-interface.md +++ b/docs/atl/reference/iaxwinhostwindowlic-interface.md @@ -29,7 +29,7 @@ interface IAxWinHostWindowLic : IAxWinHostWindow `IAxWinHostWindowLic` inherits from [IAxWinHostWindow](../../atl/reference/iaxwinhostwindow-interface.md) and adds methods that support the creation of licensed controls. -See [Hosting ActiveX Controls Using ATL AXHost](../../atl/atl-control-containment-faq.md#hosting-activex-controls-using-atl-axhost) for a sample that uses the members of this interface. +See [Hosting ActiveX Controls Using ATL AXHost](../../atl/atl-control-containment-faq.yml#hosting-activex-controls-using-atl-axhost) for a sample that uses the members of this interface. ## Requirements @@ -65,7 +65,7 @@ Calling this method is equivalent to calling [IAxWinHostWindowLic::CreateControl ### Example -See [Hosting ActiveX Controls Using ATL AXHost](../../atl/atl-control-containment-faq.md#hosting-activex-controls-using-atl-axhost) for a sample that uses `IAxWinHostWindowLic::CreateControlLic`. +See [Hosting ActiveX Controls Using ATL AXHost](../../atl/atl-control-containment-faq.yml#hosting-activex-controls-using-atl-axhost) for a sample that uses `IAxWinHostWindowLic::CreateControlLic`. ## IAxWinHostWindowLic::CreateControlLicEx @@ -93,4 +93,4 @@ See [IAxWinHostWindow::CreateControlEx](../../atl/reference/iaxwinhostwindow-int ### Example -See [Hosting ActiveX Controls Using ATL AXHost](../../atl/atl-control-containment-faq.md#hosting-activex-controls-using-atl-axhost) for a sample that uses `IAxWinHostWindowLic::CreateControlLicEx`. +See [Hosting ActiveX Controls Using ATL AXHost](../../atl/atl-control-containment-faq.yml#hosting-activex-controls-using-atl-axhost) for a sample that uses `IAxWinHostWindowLic::CreateControlLicEx`. diff --git a/docs/atl/reference/idispeventimpl-class.md b/docs/atl/reference/idispeventimpl-class.md index 74fd3e72c2..ef54c3c7b5 100644 --- a/docs/atl/reference/idispeventimpl-class.md +++ b/docs/atl/reference/idispeventimpl-class.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: IDispEventImpl Class" title: "IDispEventImpl Class" -ms.date: "11/04/2016" +description: "Learn more about: IDispEventImpl Class" +ms.date: 11/04/2016 f1_keywords: ["IDispEventImpl", "ATLCOM/ATL::IDispEventImpl", "ATLCOM/ATL::IDispEventImpl::IDispEventImpl", "ATLCOM/ATL::IDispEventImpl::GetFuncInfoFromId", "ATLCOM/ATL::IDispEventImpl::GetIDsOfNames", "ATLCOM/ATL::IDispEventImpl::GetTypeInfo", "ATLCOM/ATL::IDispEventImpl::GetTypeInfoCount", "ATLCOM/ATL::IDispEventImpl::GetUserDefinedType"] helpviewer_keywords: ["IDispEventImpl class"] -ms.assetid: a64b5288-35cb-4638-aad6-2d15b1c7cf7b --- -# IDispEventImpl Class +# `IDispEventImpl` Class This class provides implementations of the `IDispatch` methods. @@ -15,7 +14,7 @@ This class provides implementations of the `IDispatch` methods. ## Syntax -``` +```cpp template #### Parameters -*nID*
+*`nID`*\ A unique identifier for the source object. When `IDispEventImpl` is the base class for a composite control, use the resource ID of the desired contained control for this parameter. In other cases, use an arbitrary positive integer. -*T*
+*`T`*\ The user's class, which is derived from `IDispEventImpl`. -*pdiid*
-The pointer to the IID of the event dispinterface implemented by this class. This interface must be defined in the type library denoted by *plibid*, *wMajor*, and *wMinor*. +*`pdiid`*\ +The pointer to the IID of the event dispinterface implemented by this class. This interface must be defined in the type library denoted by *`plibid`*, *`wMajor`*, and *`wMinor`*. -*plibid*
-A pointer to the type library that defines the dispatch interface pointed to by *pdiid*. If **&GUID_NULL**, the type library will be loaded from the object sourcing the events. +*`plibid`*\ +A pointer to the type library that defines the dispatch interface pointed to by *`pdiid`*. If **`&GUID_NULL`**, the type library will be loaded from the object sourcing the events. -*wMajor*
+*`wMajor`*\ The major version of the type library. The default value is 0. -*wMinor*
+*`wMinor`*\ The minor version of the type library. The default value is 0. -*tihclass*
-The class used to manage the type information for *T*. The default value is a class of type `CComTypeInfoHolder`; however, you can override this template parameter by providing a class of a type other than `CComTypeInfoHolder`. +*`tihclass`*\ +The class used to manage the type information for *`T`*. The default value is a class of type `CComTypeInfoHolder`; however, you can override this template parameter by providing a class of a type other than `CComTypeInfoHolder`. ## Members @@ -54,23 +53,23 @@ The class used to manage the type information for *T*. The default value is a cl |Name|Description| |----------|-----------------| -|[IDispEventImpl::_tihclass](../../atl/reference/idispeventimpl-class.md)|The class used to manage the type information. By default, `CComTypeInfoHolder`.| +|[`IDispEventImpl::_tihclass`](#_tihclass)|The class used to manage the type information. By default, `CComTypeInfoHolder`.| ### Public Constructors |Name|Description| |----------|-----------------| -|[IDispEventImpl::IDispEventImpl](#idispeventimpl)|The constructor.| +|[`IDispEventImpl::IDispEventImpl`](#idispeventimpl)|The constructor.| ### Public Methods |Name|Description| |----------|-----------------| -|[IDispEventImpl::GetFuncInfoFromId](#getfuncinfofromid)|Locates the function index for the specified dispatch identifier.| -|[IDispEventImpl::GetIDsOfNames](#getidsofnames)|Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs.| -|[IDispEventImpl::GetTypeInfo](#gettypeinfo)|Retrieves the type information for an object.| -|[IDispEventImpl::GetTypeInfoCount](#gettypeinfocount)|Retrieves the number of type information interfaces.| -|[IDispEventImpl::GetUserDefinedType](#getuserdefinedtype)|Retrieves the basic type of a user-defined type.| +|[`IDispEventImpl::GetFuncInfoFromId`](#getfuncinfofromid)|Locates the function index for the specified dispatch identifier.| +|[`IDispEventImpl::GetIDsOfNames`](#getidsofnames)|Maps a single member and an optional set of argument names to a corresponding set of integer `DISPID`s.| +|[`IDispEventImpl::GetTypeInfo`](#gettypeinfo)|Retrieves the type information for an object.| +|[`IDispEventImpl::GetTypeInfoCount`](#gettypeinfocount)|Retrieves the number of type information interfaces.| +|[`IDispEventImpl::GetUserDefinedType`](#getuserdefinedtype)|Retrieves the basic type of a user-defined type.| ## Remarks @@ -78,18 +77,18 @@ The class used to manage the type information for *T*. The default value is a cl `IDispEventImpl` works in conjunction with the event sink map in your class to route events to the appropriate handler function. To use this class: -Add a [SINK_ENTRY](composite-control-macros.md#sink_entry) or [SINK_ENTRY_EX](composite-control-macros.md#sink_entry_ex) macro to the event sink map for each event on each object that you want to handle. When using `IDispEventImpl` as a base class of a composite control, you can call [AtlAdviseSinkMap](connection-point-global-functions.md#atladvisesinkmap) to establish and break the connection with the event sources for all entries in the event sink map. In other cases, or for greater control, call [DispEventAdvise](idispeventsimpleimpl-class.md#dispeventadvise) to establish the connection between the source object and the base class. Call [DispEventUnadvise](idispeventsimpleimpl-class.md#dispeventunadvise) to break the connection. +Add a [`SINK_ENTRY`](composite-control-macros.md#sink_entry) or [`SINK_ENTRY_EX`](composite-control-macros.md#sink_entry_ex) macro to the event sink map for each event on each object that you want to handle. When using `IDispEventImpl` as a base class of a composite control, you can call [`AtlAdviseSinkMap`](connection-point-global-functions.md#atladvisesinkmap) to establish and break the connection with the event sources for all entries in the event sink map. In other cases, or for greater control, call [`DispEventAdvise`](idispeventsimpleimpl-class.md#dispeventadvise) to establish the connection between the source object and the base class. Call [`DispEventUnadvise`](idispeventsimpleimpl-class.md#dispeventunadvise) to break the connection. -You must derive from `IDispEventImpl` (using a unique value for *nID*) for each object for which you need to handle events. You can reuse the base class by unadvising against one source object then advising against a different source object, but the maximum number of source objects that can be handled by a single object at one time is limited by the number of `IDispEventImpl` base classes. +You must derive from `IDispEventImpl` (using a unique value for *`nID`*) for each object for which you need to handle events. You can reuse the base class by unadvising against one source object then advising against a different source object, but the maximum number of source objects that can be handled by a single object at one time is limited by the number of `IDispEventImpl` base classes. -`IDispEventImpl` provides the same functionality as [IDispEventSimpleImpl](../../atl/reference/idispeventsimpleimpl-class.md), except it gets type information about the interface from a type library rather than having it supplied as a pointer to an [_ATL_FUNC_INFO](../../atl/reference/atl-func-info-structure.md) structure. Use `IDispEventSimpleImpl` when you do not have a type library describing the event interface or want to avoid the overhead associated with using the type library. +`IDispEventImpl` provides the same functionality as [`IDispEventSimpleImpl`](idispeventsimpleimpl-class.md), except it gets type information about the interface from a type library rather than having it supplied as a pointer to an [`_ATL_FUNC_INFO`](atl-func-info-structure.md) structure. Use `IDispEventSimpleImpl` when you do not have a type library describing the event interface or want to avoid the overhead associated with using the type library. > [!NOTE] > `IDispEventImpl` and `IDispEventSimpleImpl` provide their own implementation of `IUnknown::QueryInterface` enabling each `IDispEventImpl` and `IDispEventSimpleImpl` base class to act as a separate COM identity while still allowing direct access to class members in your main COM object. -CE ATL implementation of ActiveX event sinks only supports return values of type HRESULT or void from your event handler methods; any other return value is unsupported and its behavior is undefined. +CE ATL implementation of ActiveX event sinks only supports return values of type `HRESULT` or `void` from your event handler methods; any other return value is unsupported and its behavior is undefined. -For more information, see [Supporting IDispEventImpl](../../atl/supporting-idispeventimpl.md). +For more information, see [Supporting `IDispEventImpl`](../supporting-idispeventimpl.md). ## Inheritance Hierarchy @@ -97,19 +96,19 @@ For more information, see [Supporting IDispEventImpl](../../atl/supporting-idisp `_IDispEventLocator` -[IDispEventSimpleImpl](../../atl/reference/idispeventsimpleimpl-class.md) +[`IDispEventSimpleImpl`](idispeventsimpleimpl-class.md) `IDispEventImpl` ## Requirements -**Header:** atlcom.h +**Header:** `atlcom.h` -## IDispEventImpl::GetFuncInfoFromId +## `IDispEventImpl::GetFuncInfoFromId` Locates the function index for the specified dispatch identifier. -``` +```cpp HRESULT GetFuncInfoFromId( const IID& iid, DISPID dispidMember, @@ -119,27 +118,27 @@ HRESULT GetFuncInfoFromId( ### Parameters -*iid*
+*`iid`*\ [in] A reference to the ID of the function. -*dispidMember*
+*`dispidMember`*\ [in] The dispatch ID of the function. -*lcid*
+*`lcid`*\ [in] The locale context of the function ID. -*info*
+*`info`*\ [in] The structure indicating how the function is called. ### Return Value -A standard HRESULT value. +A standard `HRESULT` value. -## IDispEventImpl::GetIDsOfNames +## `IDispEventImpl::GetIDsOfNames` -Maps a single member and an optional set of argument names to a corresponding set of integer DISPIDs, which can be used on subsequent calls to [IDispatch::Invoke](/windows/win32/api/oaidl/nf-oaidl-idispatch-invoke). +Maps a single member and an optional set of argument names to a corresponding set of integer `DISPID`s, which can be used on subsequent calls to [`IDispatch::Invoke`](/windows/win32/api/oaidl/nf-oaidl-idispatch-invoke). -``` +```cpp STDMETHOD(GetIDsOfNames)( REFIID riid, LPOLESTR* rgszNames, @@ -150,38 +149,36 @@ STDMETHOD(GetIDsOfNames)( ### Remarks -See [IDispatch::GetIDsOfNames](/windows/win32/api/oaidl/nf-oaidl-idispatch-getidsofnames) in the Windows SDK. +See [`IDispatch::GetIDsOfNames`](/windows/win32/api/oaidl/nf-oaidl-idispatch-getidsofnames) in the Windows SDK. -## IDispEventImpl::GetTypeInfo +## `IDispEventImpl::GetTypeInfo` Retrieves the type information for an object, which can then be used to get the type information for an interface. -``` +```cpp STDMETHOD(GetTypeInfo)( UINT itinfo, LCID lcid, ITypeInfo** pptinfo); ``` -### Remarks - -## IDispEventImpl::GetTypeInfoCount +## `IDispEventImpl::GetTypeInfoCount` Retrieves the number of type information interfaces that an object provides (either 0 or 1). -``` +```cpp STDMETHOD(GetTypeInfoCount)(UINT* pctinfo); ``` ### Remarks -See [IDispatch::GetTypeInfoCount](/windows/win32/api/oaidl/nf-oaidl-idispatch-gettypeinfocount) in the Windows SDK. +See [`IDispatch::GetTypeInfoCount`](/windows/win32/api/oaidl/nf-oaidl-idispatch-gettypeinfocount) in the Windows SDK. -## IDispEventImpl::GetUserDefinedType +## `IDispEventImpl::GetUserDefinedType` Retrieves the basic type of a user-defined type. -``` +```cpp VARTYPE GetUserDefinedType( ITypeInfo* pTI, HREFTYPE hrt); @@ -189,10 +186,10 @@ VARTYPE GetUserDefinedType( ### Parameters -*pTI*
-[in] A pointer to the [ITypeInfo](/windows/win32/api/oaidl/nn-oaidl-itypeinfo) interface containing the user-defined type. +*`pTI`*\ +[in] A pointer to the [`ITypeInfo`](/windows/win32/api/oaidl/nn-oaidl-itypeinfo) interface containing the user-defined type. -*hrt*
+*`hrt`*\ [in] A handle to the type description to be retrieved. ### Return Value @@ -201,21 +198,21 @@ The type of variant. ### Remarks -See [ITypeInfo::GetRefTypeInfo](/windows/win32/api/oaidl/nf-oaidl-itypeinfo-getreftypeinfo). +See [`ITypeInfo::GetRefTypeInfo`](/windows/win32/api/oaidl/nf-oaidl-itypeinfo-getreftypeinfo). -## IDispEventImpl::IDispEventImpl +## `IDispEventImpl::IDispEventImpl` -The constructor. Stores the values of the class template parameters *plibid*, *pdiid*, *wMajor*, and *wMinor*. +The constructor. Stores the values of the class template parameters *`plibid`*, *`pdiid`*, *`wMajor`*, and *`wMinor`*. -``` +```cpp IDispEventImpl(); ``` -## IDispEventImpl::tihclass +## `IDispEventImpl::_tihclass` -This typedef is an instance of the class template parameter *tihclass*. +This typedef is an instance of the class template parameter *`tihclass`*. -``` +```cpp typedef tihclass _tihclass; ``` @@ -225,10 +222,10 @@ By default, the class is `CComTypeInfoHolder`. `CComTypeInfoHolder` manages the ## See also -[_ATL_FUNC_INFO Structure](../../atl/reference/atl-func-info-structure.md)
-[IDispatchImpl Class](../../atl/reference/idispatchimpl-class.md)
-[IDispEventSimpleImpl Class](../../atl/reference/idispeventsimpleimpl-class.md)
-[SINK_ENTRY](composite-control-macros.md#sink_entry)
-[SINK_ENTRY_EX](composite-control-macros.md#sink_entry_ex)
-[SINK_ENTRY_INFO](composite-control-macros.md#sink_entry_info)
-[Class Overview](../../atl/atl-class-overview.md) +[`_ATL_FUNC_INFO` Structure](atl-func-info-structure.md)\ +[`IDispatchImpl` Class](idispatchimpl-class.md)\ +[`IDispEventSimpleImpl` Class](idispeventsimpleimpl-class.md)\ +[`SINK_ENTRY`](composite-control-macros.md#sink_entry)\ +[`SINK_ENTRY_EX`](composite-control-macros.md#sink_entry_ex)\ +[`SINK_ENTRY_INFO`](composite-control-macros.md#sink_entry_info)\ +[Class Overview](../atl-class-overview.md) diff --git a/docs/atl/reference/iolecontrolimpl-class.md b/docs/atl/reference/iolecontrolimpl-class.md index 6dc7d0f8a8..6c3430e9ce 100644 --- a/docs/atl/reference/iolecontrolimpl-class.md +++ b/docs/atl/reference/iolecontrolimpl-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: IOleControlImpl Class" title: "IOleControlImpl Class" +description: "Learn more about: IOleControlImpl Class" ms.date: "11/04/2016" f1_keywords: ["IOleControlImpl", "ATLCTL/ATL::IOleControlImpl", "ATLCTL/ATL::IOleControlImpl::FreezeEvents", "ATLCTL/ATL::IOleControlImpl::GetControlInfo", "ATLCTL/ATL::IOleControlImpl::OnAmbientPropertyChange", "ATLCTL/ATL::IOleControlImpl::OnMnemonic"] helpviewer_keywords: ["IOleControlImpl class"] -ms.assetid: 5a4255ad-ede4-49ca-ba9a-07c2e919fa85 --- # IOleControlImpl Class @@ -22,7 +21,7 @@ class IOleControlImpl #### Parameters -*T*
+*T*\ Your class, derived from `IOleControlImpl`. ## Members @@ -76,7 +75,7 @@ HRESULT GetControlInfo(LPCONTROLINFO pCI); ### Remarks -See [IOleControl:GetControlInfo](/windows/win32/api/ocidl/nf-ocidl-iolecontrol-getcontrolinfo) in the Windows SDK. +See [IOleControl::GetControlInfo](/windows/win32/api/ocidl/nf-ocidl-iolecontrol-getcontrolinfo) in the Windows SDK. ### Return Value @@ -116,6 +115,6 @@ See [IOleControl::OnMnemonic](/windows/win32/api/ocidl/nf-ocidl-iolecontrol-onmn ## See also -[IOleObjectImpl Class](../../atl/reference/ioleobjectimpl-class.md)
-[ActiveX Controls Interfaces](/windows/win32/com/activex-controls-interfaces)
+[IOleObjectImpl Class](../../atl/reference/ioleobjectimpl-class.md)\ +[ActiveX Controls Interfaces](/windows/win32/com/activex-controls-interfaces)\ [Class Overview](../../atl/atl-class-overview.md) diff --git a/docs/atl/reference/iperpropertybrowsingimpl-class.md b/docs/atl/reference/iperpropertybrowsingimpl-class.md index f81692daec..c5f0e2678e 100644 --- a/docs/atl/reference/iperpropertybrowsingimpl-class.md +++ b/docs/atl/reference/iperpropertybrowsingimpl-class.md @@ -16,7 +16,6 @@ This class implements `IUnknown` and allows a client to access the information i ## Syntax ``` - template class ATL_NO_VTABLE IPerPropertyBrowsingImpl : public IPerPropertyBrowsing diff --git a/docs/atl/reference/ipersiststorageimpl-class.md b/docs/atl/reference/ipersiststorageimpl-class.md index 9b8e3de985..a5396bee53 100644 --- a/docs/atl/reference/ipersiststorageimpl-class.md +++ b/docs/atl/reference/ipersiststorageimpl-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: IPersistStorageImpl Class" title: "IPersistStorageImpl Class" +description: "Learn more about: IPersistStorageImpl Class" ms.date: "11/04/2016" f1_keywords: ["IPersistStorageImpl", "ATLCOM/ATL::IPersistStorageImpl", "ATLCOM/ATL::IPersistStorageImpl::GetClassID", "ATLCOM/ATL::IPersistStorageImpl::HandsOffStorage", "ATLCOM/ATL::IPersistStorageImpl::InitNew", "ATLCOM/ATL::IPersistStorageImpl::IsDirty", "ATLCOM/ATL::IPersistStorageImpl::Load", "ATLCOM/ATL::IPersistStorageImpl::Save", "ATLCOM/ATL::IPersistStorageImpl::SaveCompleted"] helpviewer_keywords: ["storage, ATL", "IPersistStorageImpl class"] -ms.assetid: d652f02c-239c-47c7-9a50-3e9fc3014fff --- # IPersistStorageImpl Class @@ -22,7 +21,7 @@ class ATL_NO_VTABLE IPersistStorageImpl : public IPersistStorage #### Parameters -*T*
+*T*\ Your class, derived from `IPersistStorageImpl`. ## Members @@ -97,7 +96,7 @@ STDMETHOD(InitNew)(IStorage*); The ATL implementation delegates to the [IPersistStreamInit](/windows/win32/api/ocidl/nn-ocidl-ipersiststreaminit) interface. -See [IPersistStorage:InitNew](/windows/win32/api/objidl/nf-objidl-ipersiststorage-initnew) in the Windows SDK. +See [IPersistStorage::InitNew](/windows/win32/api/objidl/nf-objidl-ipersiststorage-initnew) in the Windows SDK. ## IPersistStorageImpl::IsDirty @@ -111,7 +110,7 @@ STDMETHOD(IsDirty)(void); The ATL implementation delegates to the [IPersistStreamInit](/windows/win32/api/ocidl/nn-ocidl-ipersiststreaminit) interface. -See [IPersistStorage:IsDirty](/windows/win32/api/objidl/nf-objidl-ipersiststorage-isdirty) in the Windows SDK. +See [IPersistStorage::IsDirty](/windows/win32/api/objidl/nf-objidl-ipersiststorage-isdirty) in the Windows SDK. ## IPersistStorageImpl::Load @@ -125,7 +124,7 @@ STDMETHOD(Load)(IStorage* pStorage); The ATL implementation delegates to the [IPersistStreamInit](/windows/win32/api/ocidl/nn-ocidl-ipersiststreaminit) interface. `Load` uses a stream named "Contents" to retrieve the object's data. The [Save](#save) method originally creates this stream. -See [IPersistStorage:Load](/windows/win32/api/objidl/nf-objidl-ipersiststorage-load) in the Windows SDK. +See [IPersistStorage::Load](/windows/win32/api/objidl/nf-objidl-ipersiststorage-load) in the Windows SDK. ## IPersistStorageImpl::Save @@ -139,7 +138,7 @@ STDMETHOD(Save)(IStorage* pStorage, BOOL fSameAsLoad); The ATL implementation delegates to the [IPersistStreamInit](/windows/win32/api/ocidl/nn-ocidl-ipersiststreaminit) interface. When `Save` is first called, it creates a stream named "Contents" on the specified storage. This stream is then used in later calls to `Save` and in calls to [Load](#load). -See [IPersistStorage:Save](/windows/win32/api/objidl/nf-objidl-ipersiststorage-save) in the Windows SDK. +See [IPersistStorage::Save](/windows/win32/api/objidl/nf-objidl-ipersiststorage-save) in the Windows SDK. ## IPersistStorageImpl::SaveCompleted @@ -155,11 +154,11 @@ Returns S_OK. ### Remarks -See [IPersistStorage:SaveCompleted](/windows/win32/api/objidl/nf-objidl-ipersiststorage-savecompleted) in the Windows SDK. +See [IPersistStorage::SaveCompleted](/windows/win32/api/objidl/nf-objidl-ipersiststorage-savecompleted) in the Windows SDK. ## See also -[Storages and Streams](/windows/win32/Stg/storages-and-streams)
-[IPersistStreamInitImpl Class](../../atl/reference/ipersiststreaminitimpl-class.md)
-[IPersistPropertyBagImpl Class](../../atl/reference/ipersistpropertybagimpl-class.md)
+[Storages and Streams](/windows/win32/Stg/storages-and-streams)\ +[IPersistStreamInitImpl Class](../../atl/reference/ipersiststreaminitimpl-class.md)\ +[IPersistPropertyBagImpl Class](../../atl/reference/ipersistpropertybagimpl-class.md)\ [Class Overview](../../atl/atl-class-overview.md) diff --git a/docs/atl/reference/message-map-macros-atl.md b/docs/atl/reference/message-map-macros-atl.md index 5752c16d10..99775caee5 100644 --- a/docs/atl/reference/message-map-macros-atl.md +++ b/docs/atl/reference/message-map-macros-atl.md @@ -2,7 +2,7 @@ description: "Learn more about: Message Map Macros (ATL)" title: "Message Map Macros (ATL)" ms.date: "11/04/2016" -f1_keywords: ["atlwin/ATL::ALT_MSG_MAP", "atlwin/ATL::BEGIN_MSG_MAP", "atlwin/ATL::CHAIN_MSG_MAP_ALT", "atlwin/ATL::CHAIN_MSG_MAP_ALT_MEMBER", "atlwin/ATL::CHAIN_MSG_MAP", "atlwin/ATL::CHAIN_MSG_MAP_DYNAMIC", "atlwin/ATL::CHAIN_MSG_MAP_MEMBER", "atlwin/ATL::COMMAND_CODE_HANDLER", "atlwin/ATL::COMMAND_HANDLER", "atlwin/ATL::COMMAND_ID_HANDLER", "atlwin/ATL::COMMAND_RANGE_CODE_HANDLER", "atlwin/ATL::COMMAND_RANGE_HANDLER", "atlwin/ATL::DECLARE_EMPTY_MSG_MAP", "atlwin/ATL::DEFAULT_REFLECTION_HANDLER", "atlwin/ATL::END_MSG_MAP", "atlwin/ATL::FORWARD_NOTIFICATIONS", "atlwin/ATL::MESSAGE_HANDLER", "atlwin/ATL::MESSAGE_RANGE_HANDLER", "atlwin/ATL::NOTIFY_CODE_HANDLER", "atlwin/ATL::NOTIFY_HANDLER", "atlwin/ATL::NOTIFY_ID_HANDLER", "atlwin/ATL::NOTIFY_RANGE_CODE_HANDLER", "atlwin/ATL::NOTIFY_RANGE_HANDLER", "atlwin/ATL::REFLECT_NOTIFICATIONS", "atlwin/ATL::REFLECTED_COMMAND_CODE_HANDLER", "atlwin/ATL::REFLECTED_COMMAND_HANDLER", "atlwin/ATL::REFLECTED_COMMAND_ID_HANDLER", "atlwin/ATL::REFLECTED_COMMAND_RANGE_CODE_HANDLER", "atlwin/ATL::REFLECTED_COMMAND_RANGE_HANDLER", "atlwin/ATL::REFLECTED_NOTIFY_CODE_HANDLER", "atlwin/ATL::REFLECTED_NOTIFY_HANDLER", "atlwin/ATL::REFLECTED_NOTIFY_ID_HANDLER", "atlwin/ATL::REFLECTED_NOTIFY_RANGE_CODE_HANDLER", "atlwin/ATL::REFLECTED_NOTIFY_RANGE_HANDLER"] +f1_keywords: ["atlwin/ATL::ALT_MSG_MAP", "atlwin/ATL::BEGIN_MSG_MAP", "atlwin/ATL::CHAIN_MSG_MAP_ALT", "atlwin/ATL::CHAIN_MSG_MAP_ALT_MEMBER", "atlwin/ATL::CHAIN_MSG_MAP", "atlwin/ATL::CHAIN_MSG_MAP_DYNAMIC", "atlwin/ATL::CHAIN_MSG_MAP_MEMBER", "atlwin/ATL::COMMAND_CODE_HANDLER", "atlwin/ATL::COMMAND_HANDLER", "atlwin/ATL::COMMAND_ID_HANDLER", "atlwin/ATL::COMMAND_RANGE_CODE_HANDLER", "atlwin/ATL::COMMAND_RANGE_HANDLER", "atlwin/ATL::DECLARE_EMPTY_MSG_MAP", "atlwin/ATL::DEFAULT_REFLECTION_HANDLER", "atlwin/ATL::END_MSG_MAP", "atlwin/ATL::FORWARD_NOTIFICATIONS", "atlwin/ATL::MESSAGE_HANDLER", "atlwin/ATL::MESSAGE_RANGE_HANDLER", "atlwin/ATL::NOTIFY_CODE_HANDLER", "atlwin/ATL::NOTIFY_HANDLER", "atlwin/ATL::NOTIFY_ID_HANDLER", "atlwin/ATL::NOTIFY_RANGE_CODE_HANDLER", "atlwin/ATL::NOTIFY_RANGE_HANDLER", "atlwin/ATL::REFLECT_NOTIFICATIONS", "atlwin/ATL::REFLECTED_COMMAND_CODE_HANDLER", "atlwin/ATL::REFLECTED_COMMAND_HANDLER", "atlwin/ATL::REFLECTED_COMMAND_ID_HANDLER", "atlwin/ATL::REFLECTED_COMMAND_RANGE_CODE_HANDLER", "atlwin/ATL::REFLECTED_COMMAND_RANGE_HANDLER", "atlwin/ATL::REFLECTED_NOTIFY_CODE_HANDLER", "atlwin/ATL::REFLECTED_NOTIFY_HANDLER", "atlwin/ATL::REFLECTED_NOTIFY_ID_HANDLER", "atlwin/ATL::REFLECTED_NOTIFY_RANGE_CODE_HANDLER", "atlwin/ATL::REFLECTED_NOTIFY_RANGE_HANDLER", "ATLWIN/ALT_MSG_MAP", "ATLWIN/BEGIN_MSG_MAP", "ATLWIN/CHAIN_MSG_MAP_ALT", "ATLWIN/CHAIN_MSG_MAP_ALT_MEMBER", "ATLWIN/CHAIN_MSG_MAP", "ATLWIN/CHAIN_MSG_MAP_DYNAMIC", "ATLWIN/CHAIN_MSG_MAP_MEMBER", "ATLWIN/COMMAND_CODE_HANDLER", "ATLWIN/COMMAND_HANDLER", "ATLWIN/COMMAND_ID_HANDLER", "ATLWIN/COMMAND_RANGE_CODE_HANDLER", "ATLWIN/COMMAND_RANGE_HANDLER", "ATLWIN/DECLARE_EMPTY_MSG_MAP", "ATLWIN/DEFAULT_REFLECTION_HANDLER", "ATLWIN/END_MSG_MAP", "ATLWIN/FORWARD_NOTIFICATIONS", "ATLWIN/MESSAGE_HANDLER", "ATLWIN/MESSAGE_RANGE_HANDLER", "ATLWIN/NOTIFY_CODE_HANDLER", "ATLWIN/NOTIFY_HANDLER", "ATLWIN/NOTIFY_ID_HANDLER", "ATLWIN/NOTIFY_RANGE_CODE_HANDLER", "ATLWIN/NOTIFY_RANGE_HANDLER", "ATLWIN/REFLECT_NOTIFICATIONS", "ATLWIN/REFLECTED_COMMAND_CODE_HANDLER", "ATLWIN/REFLECTED_COMMAND_HANDLER", "ATLWIN/REFLECTED_COMMAND_ID_HANDLER", "ATLWIN/REFLECTED_COMMAND_RANGE_CODE_HANDLER", "ATLWIN/REFLECTED_COMMAND_RANGE_HANDLER", "ATLWIN/REFLECTED_NOTIFY_CODE_HANDLER", "ATLWIN/REFLECTED_NOTIFY_HANDLER", "ATLWIN/REFLECTED_NOTIFY_ID_HANDLER", "ATLWIN/REFLECTED_NOTIFY_RANGE_CODE_HANDLER", "ATLWIN/REFLECTED_NOTIFY_RANGE_HANDLER"] ms.assetid: eefdd546-8934-4a30-b263-9c06a8addcbd --- # Message Map Macros (ATL) diff --git a/docs/atl/reference/object-map-macros.md b/docs/atl/reference/object-map-macros.md index c9ebdbdbbe..e0d53e8236 100644 --- a/docs/atl/reference/object-map-macros.md +++ b/docs/atl/reference/object-map-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: Object Map Macros" title: "Object Map Macros" ms.date: "11/04/2016" -f1_keywords: ["atlcom/ATL::DECLARE_OBJECT_DESCRIPTION", "atlcom/ATL::OBJECT_ENTRY_AUTO", "atlcom/ATL::OBJECT_ENTRY_NON_CREATEABLE_EX_AUTO"] +f1_keywords: ["atlcom/ATL::DECLARE_OBJECT_DESCRIPTION", "atlcom/ATL::OBJECT_ENTRY_AUTO", "atlcom/ATL::OBJECT_ENTRY_NON_CREATEABLE_EX_AUTO", "ATLCOM/DECLARE_OBJECT_DESCRIPTION", "ATLCOM/OBJECT_ENTRY_AUTO", "ATLCOM/OBJECT_ENTRY_NON_CREATEABLE_EX_AUTO"] ms.assetid: 680087f4-9894-41dd-a79c-6f337e1f13c1 --- # Object Map Macros diff --git a/docs/atl/reference/object-status-macros.md b/docs/atl/reference/object-status-macros.md index 81f8189659..06a9bdb39f 100644 --- a/docs/atl/reference/object-status-macros.md +++ b/docs/atl/reference/object-status-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: Object Status Macros" title: "Object Status Macros" ms.date: "11/04/2016" -f1_keywords: ["atlcom/ATL::DECLARE_OLEMISC_STATUS"] +f1_keywords: ["atlcom/ATL::DECLARE_OLEMISC_STATUS", "ATLCOM/DECLARE_OLEMISC_STATUS"] ms.assetid: 727dbef2-a342-4157-9d64-a421805d9747 --- # Object Status Macros diff --git a/docs/atl/reference/options-atl-property-page-wizard.md b/docs/atl/reference/options-atl-property-page-wizard.md index bb5185ae7b..a49caf9d07 100644 --- a/docs/atl/reference/options-atl-property-page-wizard.md +++ b/docs/atl/reference/options-atl-property-page-wizard.md @@ -8,7 +8,7 @@ ms.assetid: a7107779-b2ea-4f99-b84b-7f3e0c504bc8 --- # Options, ATL Property Page Wizard -::: moniker range="msvc-160" +::: moniker range=">=msvc-160" The ATL Property Page wizard is not available in Visual Studio 2019 and later. diff --git a/docs/atl/reference/property-map-macros.md b/docs/atl/reference/property-map-macros.md index 038b525d2f..c0e785543d 100644 --- a/docs/atl/reference/property-map-macros.md +++ b/docs/atl/reference/property-map-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: Property Map Macros" title: "Property Map Macros" ms.date: "11/04/2016" -f1_keywords: ["atlcom/ATL::BEGIN_PROP_MAP", "atlcom/ATL::PROP_DATA_ENTRY", "atlcom/ATL::PROP_ENTRY_TYPE", "atlcom/ATL::PROP_ENTRY_TYPE_EX", "atlcom/ATL::PROP_PAGE", "atlcom/ATL::END_PROP_MAP"] +f1_keywords: ["atlcom/ATL::BEGIN_PROP_MAP", "atlcom/ATL::PROP_DATA_ENTRY", "atlcom/ATL::PROP_ENTRY_TYPE", "atlcom/ATL::PROP_ENTRY_TYPE_EX", "atlcom/ATL::PROP_PAGE", "atlcom/ATL::END_PROP_MAP", "ATLCOM/BEGIN_PROP_MAP", "ATLCOM/PROP_DATA_ENTRY", "ATLCOM/PROP_ENTRY_TYPE", "ATLCOM/PROP_ENTRY_TYPE_EX", "ATLCOM/PROP_PAGE", "ATLCOM/END_PROP_MAP"] helpviewer_keywords: ["property maps"] ms.assetid: 128bc742-2b98-4b97-a243-684dbb83db77 --- @@ -78,7 +78,7 @@ When you create an ActiveX control, the wizard inserts this macro after the prop In the following example, the extent of the object (`m_sizeExtent`) is being persisted. [!code-cpp[NVC_ATL_Windowing#131](../../atl/codesnippet/cpp/property-map-macros_2.h)] - +  [!code-cpp[NVC_ATL_Windowing#132](../../atl/codesnippet/cpp/property-map-macros_3.h)] ## PROP_ENTRY_TYPE diff --git a/docs/atl/reference/registry-data-exchange-macros.md b/docs/atl/reference/registry-data-exchange-macros.md index 06dce60c45..98857707a3 100644 --- a/docs/atl/reference/registry-data-exchange-macros.md +++ b/docs/atl/reference/registry-data-exchange-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: Registry Data Exchange Macros" title: "Registry Data Exchange Macros" ms.date: "11/04/2016" -f1_keywords: ["atlplus/ATL::BEGIN_RDX_MAP", "atlplus/ATL::END_RDX_MAP", "atlplus/ATL::RDX_BINARY", "atlplus/ATL::RDX_CSTRING_TEXT", "atlplus/ATL::RDX_DWORD", "atlplus/ATL::RDX_TEXT"] +f1_keywords: ["atlplus/ATL::BEGIN_RDX_MAP", "atlplus/ATL::END_RDX_MAP", "atlplus/ATL::RDX_BINARY", "atlplus/ATL::RDX_CSTRING_TEXT", "atlplus/ATL::RDX_DWORD", "atlplus/ATL::RDX_TEXT", "ATLPLUS/BEGIN_RDX_MAP", "ATLPLUS/END_RDX_MAP", "ATLPLUS/RDX_BINARY", "ATLPLUS/RDX_CSTRING_TEXT", "ATLPLUS/RDX_DWORD", "ATLPLUS/RDX_TEXT"] helpviewer_keywords: ["RegistryDataExchange function, macros"] ms.assetid: c1bc5e79-2307-43d2-9d10-3a62ffadf473 --- diff --git a/docs/atl/reference/registry-macros.md b/docs/atl/reference/registry-macros.md index 930c43fb1a..f18617f0fe 100644 --- a/docs/atl/reference/registry-macros.md +++ b/docs/atl/reference/registry-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: Registry Macros" title: "Registry Macros" ms.date: "08/19/2019" -f1_keywords: ["atlcom/ATL::_ATL_STATIC_REGISTRY", "atlcom/ATL::DECLARE_LIBID", "atlcom/ATL::DECLARE_NO_REGISTRY", "atlcom/ATL::DECLARE_REGISTRY", "atlcom/ATL::DECLARE_REGISTRY_APPID_RESOURCEID", "atlcom/ATL::DECLARE_REGISTRY_RESOURCE", "atlcom/ATL::DECLARE_REGISTRY_RESOURCEID"] +f1_keywords: ["ATLBASE/_ATL_STATIC_REGISTRY", "ATLBASE/DECLARE_LIBID", "ATLBASE/DECLARE_NO_REGISTRY", "ATLBASE/DECLARE_REGISTRY", "ATLBASE/DECLARE_REGISTRY_APPID_RESOURCEID", "ATLBASE/DECLARE_REGISTRY_RESOURCE", "ATLBASE/DECLARE_REGISTRY_RESOURCEID", "_ATL_STATIC_REGISTRY", "DECLARE_LIBID", "DECLARE_NO_REGISTRY", "DECLARE_REGISTRY", "DECLARE_REGISTRY_APPID_RESOURCEID", "DECLARE_REGISTRY_RESOURCE", "DECLARE_REGISTRY_RESOURCEID"] helpviewer_keywords: ["registry, ATL macros"] ms.assetid: 3ee041da-c63b-42a4-89cf-2a4b2a6f81ae --- diff --git a/docs/atl/reference/service-map-macros.md b/docs/atl/reference/service-map-macros.md index 76906d95cc..b42010306a 100644 --- a/docs/atl/reference/service-map-macros.md +++ b/docs/atl/reference/service-map-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: Service Map Macros" title: "Service Map Macros" ms.date: "11/04/2016" -f1_keywords: ["atlcom/ATL::BEGIN_SERVICE_MAP", "atlcom/ATL::END_SERVICE_MAP", "atlcom/ATL::SERVICE_ENTRY", "atlcom/ATL::SERVICE_ENTRY_CHAIN"] +f1_keywords: ["atlcom/ATL::BEGIN_SERVICE_MAP", "atlcom/ATL::END_SERVICE_MAP", "atlcom/ATL::SERVICE_ENTRY", "atlcom/ATL::SERVICE_ENTRY_CHAIN", "ATLCOM/BEGIN_SERVICE_MAP", "ATLCOM/END_SERVICE_MAP", "ATLCOM/SERVICE_ENTRY", "ATLCOM/SERVICE_ENTRY_CHAIN"] ms.assetid: ca02a125-454a-4cf6-aac2-1c5585025ed4 --- # Service Map Macros @@ -115,7 +115,7 @@ STDMETHOD(QueryService)( ### Return Value -The returned HRESULT value is one of the following: +The returned HRESULT is one of the following values: |Return value|Meaning| |------------------|-------------| @@ -123,23 +123,23 @@ The returned HRESULT value is one of the following: |E_INVALIDARG|One or more of the arguments is invalid.| |E_OUTOFMEMORY|Memory is insufficient to create the service.| |E_UNEXPECTED|An unknown error occurred.| -|E_NOINTERFACE|The requested interface is not part of this service, or the service is unknown.| +|E_NOINTERFACE|The requested interface isn't part of this service, or the service is unknown.| ### Remarks -`QueryService` returns an indirect pointer to the requested interface in the specified service. The caller is responsible for releasing this pointer when it is no longer required. +`QueryService` returns an indirect pointer to the requested interface in the specified service. The caller is responsible for releasing this pointer when it's no longer required. When you call `QueryService`, you pass both a service identifier (*guidService*) and an interface identifier (*riid*). The *guidService* specifies the service to which you want access, and the *riid* identifies an interface that is part of the service. In return, you receive an indirect pointer to the interface. -The object that implements the interface might also implement interfaces that are part of other services. Consider the following: +The object that implements the interface might also implement interfaces that are part of other services. Consider the following possibilities: - Some of these interfaces might be optional. Not all interfaces defined in the service description are necessarily present on every implementation of the service or on every returned object. -- Unlike calls to `QueryInterface`, passing a different service identifier does not necessarily mean that a different Component Object Model (COM) object is returned. +- Unlike calls to `QueryInterface`, passing a different service identifier doesn't necessarily mean that a different Component Object Model (COM) object is returned. -- The returned object might have additional interfaces that are not part of the definition of the service. +- The returned object might have other interfaces that aren't part of the definition of the service. -Two different services, such as SID_SMyService and SID_SYourService, can both specify the use of the same interface, even though the implementation of the interface might have nothing in common between the two services. This works, because a call to `QueryService` (SID_SMyService, IID_IDispatch) can return a different object than `QueryService` (SID_SYourService, IID_IDispatch). Object identity is not assumed when you specify a different service identifier. +Two different services, such as SID_SMyService and SID_SYourService, can both specify the use of the same interface, even though the implementation of the interface might have nothing in common between the two services. This approach works, because a call to `QueryService` (SID_SMyService, IID_IDispatch) can return a different object than `QueryService` (SID_SYourService, IID_IDispatch). Object identity isn't assumed when you specify a different service identifier. ## See also diff --git a/docs/atl/reference/snap-in-object-macros.md b/docs/atl/reference/snap-in-object-macros.md index 434f4d34ca..380f4cf116 100644 --- a/docs/atl/reference/snap-in-object-macros.md +++ b/docs/atl/reference/snap-in-object-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: Snap-In Object Macros" title: "Snap-In Object Macros" ms.date: "11/04/2016" -f1_keywords: ["atlsnap/ATL::BEGIN_EXTENSION_SNAPIN_NODEINFO_MAP", "atlsnap/ATL::BEGIN_SNAPINTOOLBARID_MAP", "atlsnap/ATL::END_EXTENSION_SNAPIN_NODEINFO_MAP", "atlsnap/ATL::END_SNAPINTOOLBARID_MAP", "atlsnap/ATL::EXTENSION_SNAPIN_DATACLASS", "atlsnap/ATL::EXTENSION_SNAPIN_NODEINFO_ENTRY", "atlsnap/ATL::SNAPINMENUID", "atlsnap/ATL::SNAPINTOOLBARID_ENTRY"] +f1_keywords: ["atlsnap/ATL::BEGIN_EXTENSION_SNAPIN_NODEINFO_MAP", "atlsnap/ATL::BEGIN_SNAPINTOOLBARID_MAP", "atlsnap/ATL::END_EXTENSION_SNAPIN_NODEINFO_MAP", "atlsnap/ATL::END_SNAPINTOOLBARID_MAP", "atlsnap/ATL::EXTENSION_SNAPIN_DATACLASS", "atlsnap/ATL::EXTENSION_SNAPIN_NODEINFO_ENTRY", "atlsnap/ATL::SNAPINMENUID", "atlsnap/ATL::SNAPINTOOLBARID_ENTRY", "ATLSNAP/BEGIN_EXTENSION_SNAPIN_NODEINFO_MAP", "ATLSNAP/BEGIN_SNAPINTOOLBARID_MAP", "ATLSNAP/END_EXTENSION_SNAPIN_NODEINFO_MAP", "ATLSNAP/END_SNAPINTOOLBARID_MAP", "ATLSNAP/EXTENSION_SNAPIN_DATACLASS", "ATLSNAP/EXTENSION_SNAPIN_NODEINFO_ENTRY", "ATLSNAP/SNAPINMENUID", "ATLSNAP/SNAPINTOOLBARID_ENTRY"] ms.assetid: 4e9850c0-e395-4929-86c9-584a81828053 --- # Snap-In Object Macros diff --git a/docs/atl/reference/string-conversion-macros.md b/docs/atl/reference/string-conversion-macros.md index 9930172187..9b67e45e5f 100644 --- a/docs/atl/reference/string-conversion-macros.md +++ b/docs/atl/reference/string-conversion-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: String Conversion Macros" title: "String Conversion Macros" ms.date: "11/04/2016" -f1_keywords: ["atlconv/ATL::DEVMODEA2W", "atlconv/ATL::TEXTMETRICA2W", "atlconv/ATL::DEVMODEOLE2T", "atlconv/ATL::TEXTMETRICOLE2T", "atlconv/ATL::DEVMODET2OLE", "atlconv/ATL::TEXTMETRICT2OLE", "atlconv/ATL::DEVMODEW2A", "atlconv/ATL::TEXTMETRICW2A"] +f1_keywords: ["atlconv/ATL::DEVMODEA2W", "atlconv/ATL::TEXTMETRICA2W", "atlconv/ATL::DEVMODEOLE2T", "atlconv/ATL::TEXTMETRICOLE2T", "atlconv/ATL::DEVMODET2OLE", "atlconv/ATL::TEXTMETRICT2OLE", "atlconv/ATL::DEVMODEW2A", "atlconv/ATL::TEXTMETRICW2A", "ATLCONV/DEVMODEA2W", "ATLCONV/TEXTMETRICA2W", "ATLCONV/DEVMODEOLE2T", "ATLCONV/TEXTMETRICOLE2T", "ATLCONV/DEVMODET2OLE", "ATLCONV/TEXTMETRICT2OLE", "ATLCONV/DEVMODEW2A", "ATLCONV/TEXTMETRICW2A"] ms.assetid: 2ff7c0b6-2bde-45fe-897f-6128e18e0c27 --- # String Conversion Macros diff --git a/docs/atl/reference/strings-atl-property-page-wizard.md b/docs/atl/reference/strings-atl-property-page-wizard.md index 93fd1d9f38..af7682dd9f 100644 --- a/docs/atl/reference/strings-atl-property-page-wizard.md +++ b/docs/atl/reference/strings-atl-property-page-wizard.md @@ -8,7 +8,7 @@ ms.assetid: 00547db6-911f-49eb-92e1-2ba67079d4df --- # Strings, ATL Property Page Wizard -::: moniker range="msvc-160" +::: moniker range=">=msvc-160" The ATL Property Page wizard is not available in Visual Studio 2019 and later. diff --git a/docs/atl/reference/window-class-macros.md b/docs/atl/reference/window-class-macros.md index 1e0a546539..4804e4b723 100644 --- a/docs/atl/reference/window-class-macros.md +++ b/docs/atl/reference/window-class-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: Window Class Macros" title: "Window Class Macros" ms.date: "11/04/2016" -f1_keywords: ["atlwin/ATL::DECLARE_WND_CLASS", "atlwin/ATL::DECLARE_WND_SUPERCLASS", "atlwin/ATL::DECLARE_WND_CLASS_EX"] +f1_keywords: ["atlwin/ATL::DECLARE_WND_CLASS", "atlwin/ATL::DECLARE_WND_SUPERCLASS", "atlwin/ATL::DECLARE_WND_CLASS_EX", "ATLWIN/DECLARE_WND_CLASS", "ATLWIN/DECLARE_WND_SUPERCLASS", "ATLWIN/DECLARE_WND_CLASS_EX"] ms.assetid: ce18681a-2bab-4453-9895-0f3ea47c2b24 --- # Window Class Macros diff --git a/docs/atl/reference/windows-messages-macros.md b/docs/atl/reference/windows-messages-macros.md index 3bcec790e6..0675305320 100644 --- a/docs/atl/reference/windows-messages-macros.md +++ b/docs/atl/reference/windows-messages-macros.md @@ -2,7 +2,7 @@ description: "Learn more about: Windows Messages Macros" title: "Windows Messages Macros" ms.date: "11/04/2016" -f1_keywords: ["atlbase/ATL::WM_FORWARDMSG"] +f1_keywords: ["atlbase/ATL::WM_FORWARDMSG", "ATLBASE/WM_FORWARDMSG"] ms.assetid: 63abd22c-372d-4148-bb04-c605950ae64f --- # Windows Messages Macros diff --git a/docs/atl/supporting-idispatch-and-ierrorinfo.md b/docs/atl/supporting-idispatch-and-ierrorinfo.md index 177b65623f..7d0c89d28e 100644 --- a/docs/atl/supporting-idispatch-and-ierrorinfo.md +++ b/docs/atl/supporting-idispatch-and-ierrorinfo.md @@ -9,7 +9,7 @@ ms.assetid: 7db2220f-319d-4ce9-9382-d340019f14f7 You can use the template class [IDispatchImpl](../atl/reference/idispatchimpl-class.md) to provide a default implementation of the `IDispatch Interface` portion of any dual interfaces on your object. -If your object uses the `IErrorInfo` interface to report errors back to the client, then your object must support the `ISupportErrorInfo Interface` interface. The template class [ISupportErrorInfoImpl](../atl/reference/isupporterrorinfoimpl-class.md) provides an easy way to implement this if you only have a single interface that generates errors on your object. +If your object uses the `IErrorInfo` interface to report errors back to the client, then your object must support the `ISupportErrorInfo` interface. The template class [ISupportErrorInfoImpl](../atl/reference/isupporterrorinfoimpl-class.md) provides an easy way to implement this if you only have a single interface that generates errors on your object. ## See also diff --git a/docs/atl/toc.yml b/docs/atl/toc.yml index 1ab642aac9..931fbffd52 100644 --- a/docs/atl/toc.yml +++ b/docs/atl/toc.yml @@ -1,3 +1,4 @@ +items: - name: Active Template Library (ATL) href: atl-com-desktop-components.md - name: Active Template Library (ATL) concepts @@ -98,7 +99,7 @@ - name: Building and testing the ATL project href: building-and-testing-the-atl-project.md - name: ATL control containment FAQ - href: atl-control-containment-faq.md + href: atl-control-containment-faq.yml - name: ATL COM property pages expanded: false items: diff --git a/docs/atl/using-replaceable-parameters-the-registrar-s-preprocessor.md b/docs/atl/using-replaceable-parameters-the-registrar-s-preprocessor.md index be5b134903..1b9ef3d2d4 100644 --- a/docs/atl/using-replaceable-parameters-the-registrar-s-preprocessor.md +++ b/docs/atl/using-replaceable-parameters-the-registrar-s-preprocessor.md @@ -1,11 +1,11 @@ --- -description: "Learn more about: Using Replaceable Parameters (The Registrar's Preprocessor)" +description: "Learn more about: Using Replaceable Parameters (The Registrar's Preprocessor)" title: "Using Replaceable Parameters (ATL Registrar)" ms.date: "11/04/2016" helpviewer_keywords: ["%MODULE%"] ms.assetid: 0b376994-84a6-4967-8d97-8c01dfc94efe --- -# Using Replaceable Parameters (The Registrar's Preprocessor) +# Using Replaceable Parameters (The Registrar's Preprocessor) Replaceable parameters allow a Registrar's client to specify run-time data. To do this, the Registrar maintains a replacement map into which it enters the values associated with the replaceable parameters in your script. The Registrar makes these entries at run time. diff --git a/docs/build-insights/get-started-with-cpp-build-insights.md b/docs/build-insights/get-started-with-cpp-build-insights.md index 92eba771f2..0ee6e8c583 100644 --- a/docs/build-insights/get-started-with-cpp-build-insights.md +++ b/docs/build-insights/get-started-with-cpp-build-insights.md @@ -3,17 +3,18 @@ title: "Get started with C++ Build Insights" description: "A high-level overview of C++ Build Insights." ms.date: "11/03/2019" helpviewer_keywords: ["C++ Build Insights", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.custom: intro-get-started --- # Get started with C++ Build Insights ::: moniker range="<=msvc-150" -The C++ Build Insights tools are available in Visual Studio 2019. To see the documentation for that version, set the Visual Studio **Version** selector control for this article to Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights tools are available in Visual Studio 2019 and later. To see the documentation for that version, set the Visual Studio **Version** selector control for this article to Visual Studio 2019 or later. It's found at the top of the table of contents on this page. ::: moniker-end -::: moniker range="msvc-160" +::: moniker range=">=msvc-160" -C++ Build Insights is a collection of tools that provides increased visibility into the Microsoft Visual C++ (MSVC) tool chain. The tools collect data about your C++ builds, and present it in a format that can help you answer common questions, like: +C++ Build Insights is a collection of tools that collect data about your C++ builds, and present it in a format that can help you answer common questions such as: - Are my builds sufficiently parallelized? - What should I include in my pre-compiled header (PCH)? @@ -21,16 +22,16 @@ C++ Build Insights is a collection of tools that provides increased visibility i The main components of this technology are: -- *vcperf.exe*, a command-line utility that you can use to collect traces for your builds, -- a Windows Performance Analyzer (WPA) extension that allows you to view build traces in WPA, and -- the C++ Build Insights SDK, a software development kit for creating your own tools that consume C++ Build Insights data. +- `vcperf.exe`, a command-line utility that you can use to collect traces for your builds +- A Windows Performance Analyzer (WPA) extension that allows you to view build traces in WPA, and +- The C++ Build Insights software development kit for creating your own tools that consume C++ Build Insights data. ## Documentation sections -[Tutorial: vcperf and Windows Performance Analyzer](tutorials/vcperf-and-wpa.md)\ +[vcperf and Windows Performance Analyzer](tutorials/vcperf-and-wpa.md)\ Learn how to collect build traces for your C++ projects and how to view them in WPA. -[Tutorial: Windows Performance Basics](tutorials/wpa-basics.md)\ +[Windows Performance Basics](tutorials/wpa-basics.md)\ Discover useful WPA tips for analyzing your build traces. [C++ Build Insights SDK](reference/sdk/overview.md)\ @@ -40,12 +41,13 @@ An overview of the C++ Build Insights SDK. Read these articles from the official C++ team blog for more information on C++ Build Insights: -[Introducing C++ Build Insights](https://devblogs.microsoft.com/cppblog/introducing-c-build-insights/) - -[Analyze your builds programmatically with the C++ Build Insights SDK](https://devblogs.microsoft.com/cppblog/analyze-your-builds-programmatically-with-the-c-build-insights-sdk/) - -[Finding build bottlenecks with C++ Build Insights](https://devblogs.microsoft.com/cppblog/finding-build-bottlenecks-with-cpp-build-insights/) - -[Faster builds with PCH suggestions from C++ Build Insights](https://devblogs.microsoft.com/cppblog/faster-builds-with-pch-suggestions-from-c-build-insights/) +[Introducing C++ Build Insights](https://devblogs.microsoft.com/cppblog/introducing-c-build-insights/)\ +[Analyze your builds programmatically with the C++ Build Insights SDK](https://devblogs.microsoft.com/cppblog/analyze-your-builds-programmatically-with-the-c-build-insights-sdk/)\ +[Finding build bottlenecks with C++ Build Insights](https://devblogs.microsoft.com/cppblog/finding-build-bottlenecks-with-cpp-build-insights/)\ +[Faster builds with PCH suggestions from C++ Build Insights](https://devblogs.microsoft.com/cppblog/faster-builds-with-pch-suggestions-from-c-build-insights/)\ +[Profiling template metaprograms with C++ Build Insights](https://devblogs.microsoft.com/cppblog/profiling-template-metaprograms-with-cpp-build-insights/)\ +[Improving code generation time with C++ Build Insights](https://devblogs.microsoft.com/cppblog/improving-code-generation-time-with-cpp-build-insights/)\ +[Introducing vcperf /timetrace for C++ build time analysis](https://devblogs.microsoft.com/cppblog/introducing-vcperf-timetrace-for-cpp-build-time-analysis/)\ +[Faster C++ builds, simplified: a new metric for time](https://devblogs.microsoft.com/cppblog/faster-cpp-builds-simplified-a-new-metric-for-time/) ::: moniker-end diff --git a/docs/build-insights/index.yml b/docs/build-insights/index.yml index 2cef8570c4..876c27600a 100644 --- a/docs/build-insights/index.yml +++ b/docs/build-insights/index.yml @@ -3,12 +3,13 @@ title: C++ Build Insights | Automate build tool chain analysis # < 60 chars summary: Use C++ Build Insights for real-time and automated build analysis and optimization. # < 160 chars metadata: - title: C++ Build Insights # Required; page title displayed in search results. Include the brand. < 60 chars. + title: C++ Build Insights description: Learn how to use C++ Build Insights to analyze and optimize your builds. ms.topic: landing-page - author: corob-msft - ms.author: corob + author: tylermsft + ms.author: twhitney ms.date: 05/26/2020 + ms.custom: intro-landing-hub # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new @@ -24,6 +25,10 @@ landingContent: url: get-started-with-cpp-build-insights.md - linkListType: tutorial links: + - text: Build Insights function view + url: tutorials/build-insights-function-view.md + - text: Build Insights included files view + url: tutorials/build-insights-included-files-view.md - text: vcperf and Windows Performance Analyzer url: tutorials/vcperf-and-wpa.md - text: Windows Performance Analyzer basics diff --git a/docs/build-insights/reference/sdk/c-event-data-types/cl-pass-data-struct.md b/docs/build-insights/reference/sdk/c-event-data-types/cl-pass-data-struct.md index a670a652c4..60655fba34 100644 --- a/docs/build-insights/reference/sdk/c-event-data-types/cl-pass-data-struct.md +++ b/docs/build-insights/reference/sdk/c-event-data-types/cl-pass-data-struct.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "CL_PASS_D ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/c-event-data-types/event-collection-data-struct.md b/docs/build-insights/reference/sdk/c-event-data-types/event-collection-data-struct.md index 4fef60b896..b3301f97a3 100644 --- a/docs/build-insights/reference/sdk/c-event-data-types/event-collection-data-struct.md +++ b/docs/build-insights/reference/sdk/c-event-data-types/event-collection-data-struct.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "EVENT_COL ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/c-event-data-types/event-data-struct.md b/docs/build-insights/reference/sdk/c-event-data-types/event-data-struct.md index f3b03f71d0..734b468058 100644 --- a/docs/build-insights/reference/sdk/c-event-data-types/event-data-struct.md +++ b/docs/build-insights/reference/sdk/c-event-data-types/event-data-struct.md @@ -1,19 +1,21 @@ --- -title: "EVENT_DATA structure" -description: "The C++ Build Insights SDK EVENT_DATA structure reference." -ms.date: "02/12/2020" +title: "C++ Build Insights SDK EVENT_DATA structure" +description: "The C++ Build Insights SDK EVENT_DATA structure reference. The EVENT_DATA structure describes an event received from an analysis or relogging session." +ms.date: "04/27/2022" +ms.topic: language-reference +ms.custom: kr2b-contr-experiment helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "EVENT_DATA", "throughput analysis", "build time analysis", "vcperf.exe"] --- # EVENT_DATA structure ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" -The `EVENT_DATA` structure describes an event received from an analysis or relogging session. These sessions are started by calling the [Analyze](../functions/analyze.md), [AnalyzeA](../functions/analyze-a.md), [AnalyzeW](../functions/analyze-w.md), [Relog](../functions/relog.md), [RelogA](../functions/relog-a.md), or [RelogW](../functions/relog-w.md) functions. +The `EVENT_DATA` structure describes an event from an analysis or relogging session. The [Analyze](../functions/analyze.md), [AnalyzeA](../functions/analyze-a.md), [AnalyzeW](../functions/analyze-w.md), [Relog](../functions/relog.md), [RelogA](../functions/relog-a.md), or [RelogW](../functions/relog-w.md) functions start these sessions. ## Syntax @@ -51,14 +53,14 @@ typedef struct EVENT_DATA_TAG | `EventId` | A number that identifies the event. For a list of event identifiers, see [EVENT_ID](event-id-enum.md). | | `EventInstanceId` | A number that uniquely identifies the current event inside a trace. This value doesn't change when analyzing or relogging the same trace multiple times. Use this field to identify the same event in multiple analysis or relogging passes over the same trace. | | `TickFrequency` | The number of ticks per second to use when evaluating a duration measured in ticks. | -| `StartTimestamp` | When the event is an *Activity*, this field is set to a tick value captured at the time the activity started. If this event is a *Simple Event*, this field is set to a tick value captured at the time the event occurred. | -| `StopTimestamp` | When the event is an *Activity*, this field is set to a tick value captured at the time the activity stopped. If the stop event hasn't yet been received for this activity, this field is set to zero. If this event is a *Simple Event*, this field is set to zero. | -| `ExclusiveDurationTicks` | If this event is an *Activity*, this field is set to the number of ticks that occurred directly in this activity. The number of ticks that occurred in a child activity are excluded. This field is set to zero for *Simple Events*. | -| `CPUTicks` | If this event is an *Activity*, this field is set to the number of CPU ticks that occurred during this activity. A CPU tick is different from a regular tick. CPU ticks are only counted when the CPU is executing code in an activity. CPU ticks aren't counted when the thread associated with the activity is sleeping. This field is set to zero for *Simple Events*. | -| `ExclusiveCPUTicks` | This field has the same meaning as `CPUTicks`, except that it doesn't include CPU ticks that occurred in children activities. This field is set to zero for *Simple Events*. | -| `WallClockTimeResponsibilityTicks` | If this event is an *Activity*, this field is set to a tick count that represents this activity's contribution to overall wall-clock time. A wall-clock time responsibility tick is different from a regular tick. Wall-clock time responsibility ticks take into account parallelism between activities. For example, two parallel activities may have a duration of 50 ticks and the same start and stop time. In this case, both will be assigned a wall-clock time responsibility of 25 ticks. This field is set to zero for *Simple Events*. | -| `ExclusiveWallClockTimeResponsibilityTicks` | This field has the same meaning as `WallClockTimeResponsibilityTicks`, except that it doesn't include the wall-clock time responsibility ticks of children activities. This field is set to zero for *Simple Events*. | -| `Data` | Points to additional data stored in the event. The type of data pointed to is different, depending on the `EventId` field. | +| `StartTimestamp` | When the event is an *Activity*, this field is the tick value captured at the time the activity started. If this event is a *Simple Event*, this field is a tick value captured at the time the event occurred. | +| `StopTimestamp` | When the event is an *Activity*, this field is the tick value captured at the time the activity stopped. If the stop event hasn't yet been received for this activity, this field is zero. If this event is a *Simple Event*, this field is zero. | +| `ExclusiveDurationTicks` | If this event is an *Activity*, this field is the number of ticks that occurred directly in this activity. The number of ticks that occurred in a child activity are excluded. This field is zero for *Simple Events*. | +| `CPUTicks` | If this event is an *Activity*, this field is the number of CPU ticks that occurred during this activity. A CPU tick is different from a regular tick. CPU ticks are only counted when the CPU is executing code in an activity. CPU ticks aren't counted when the thread associated with the activity is sleeping. This field is zero for *Simple Events*. | +| `ExclusiveCPUTicks` | This field has the same meaning as `CPUTicks`, except that it doesn't include CPU ticks that occurred in children activities. This field is zero for *Simple Events*. | +| `WallClockTimeResponsibilityTicks` | If this event is an *Activity*, this field is a tick count that represents this activity's contribution to overall wall-clock time. A wall-clock time responsibility tick is different from a regular tick. Wall-clock time responsibility ticks take into account parallelism between activities. For example, two parallel activities may have a duration of 50 ticks and the same start and stop time. In this case, both will be assigned a wall-clock time responsibility of 25 ticks. This field is zero for *Simple Events*. | +| `ExclusiveWallClockTimeResponsibilityTicks` | This field has the same meaning as `WallClockTimeResponsibilityTicks`, except that it doesn't include the wall-clock time responsibility ticks of children activities. This field is zero for *Simple Events*. | +| `Data` | Points to other data stored in the event. The type of data pointed to is different, depending on the `EventId` field. | | `ProcessId` | The identifier for the process in which the event occurred. | | `ThreadId` | The identifier for the thread in which the event occurred. | | `ProcessorIndex` | The zero-indexed CPU number on which the event occurred. | @@ -67,9 +69,13 @@ typedef struct EVENT_DATA_TAG ## Remarks -Many fields in `EVENT_DATA` contain tick counts. C++ Build Insights uses Window's performance counter as a source of ticks. A tick count must be used with the `TickFrequency` field to convert it into an appropriate time unit such as seconds. See the example below for performing this conversion. `EVENT_DATA` doesn't contain a field for the regular tick count of an activity. To obtain this value, subtract `StartTimestamp` from `StopTimestamp`. `EVENT_DATA` is a structure that's meant to be used by C API users. For C++ API users, classes like [Event](../cpp-event-data-types/event.md) do time conversions automatically. +Many fields in `EVENT_DATA` contain tick counts. C++ Build Insights uses the Windows performance counter as a source of ticks. A tick count must be used with the `TickFrequency` field to convert it into an appropriate time unit such as seconds. See the [tick conversion example](#tick-conversion-example), below. -The value of the `EVENT_DATA` `Data` field depends on the value of its `EventId` field. The value of `Data` is described in the table below. Some entity identifiers may be missing from the table below. In this case, the `Data` field is set to **`nullptr`** or zero. +`EVENT_DATA` doesn't contain a field for the regular tick count of an activity. To obtain this value, subtract `StartTimestamp` from `StopTimestamp`. + +`EVENT_DATA` is a structure that's meant to be used by C API users. For C++ API users, classes like [Event](../cpp-event-data-types/event.md) do time conversions automatically. + +The value of the `EVENT_DATA` `Data` field depends on the value of its `EventId` field. The value of `Data` is described in the table below. Some entity identifiers may be missing from the table below. In this case, the `Data` field is set to `nullptr` or zero. | `EventId` value | Type pointed to by `Data` | |--|--| diff --git a/docs/build-insights/reference/sdk/c-event-data-types/event-id-enum.md b/docs/build-insights/reference/sdk/c-event-data-types/event-id-enum.md index 0127ff97b1..496af5fae9 100644 --- a/docs/build-insights/reference/sdk/c-event-data-types/event-id-enum.md +++ b/docs/build-insights/reference/sdk/c-event-data-types/event-id-enum.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "EVENT_ID" ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/c-event-data-types/file-data-struct.md b/docs/build-insights/reference/sdk/c-event-data-types/file-data-struct.md index cc25afa7aa..6ee47af9c3 100644 --- a/docs/build-insights/reference/sdk/c-event-data-types/file-data-struct.md +++ b/docs/build-insights/reference/sdk/c-event-data-types/file-data-struct.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "FILE_DATA ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/c-event-data-types/file-type-code-enum.md b/docs/build-insights/reference/sdk/c-event-data-types/file-type-code-enum.md index 90f2c8aa74..1b1626e9f7 100644 --- a/docs/build-insights/reference/sdk/c-event-data-types/file-type-code-enum.md +++ b/docs/build-insights/reference/sdk/c-event-data-types/file-type-code-enum.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "FILE_TYPE ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/c-event-data-types/front-end-file-data-struct.md b/docs/build-insights/reference/sdk/c-event-data-types/front-end-file-data-struct.md index d486812a0b..b4c5f345c3 100644 --- a/docs/build-insights/reference/sdk/c-event-data-types/front-end-file-data-struct.md +++ b/docs/build-insights/reference/sdk/c-event-data-types/front-end-file-data-struct.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "FRONT_END ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/c-event-data-types/function-data-struct.md b/docs/build-insights/reference/sdk/c-event-data-types/function-data-struct.md index c52267d3d7..f4bbfea723 100644 --- a/docs/build-insights/reference/sdk/c-event-data-types/function-data-struct.md +++ b/docs/build-insights/reference/sdk/c-event-data-types/function-data-struct.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "FUNCTION_ ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/c-event-data-types/function-force-inlinee-data-struct.md b/docs/build-insights/reference/sdk/c-event-data-types/function-force-inlinee-data-struct.md index c9010546f4..122800678c 100644 --- a/docs/build-insights/reference/sdk/c-event-data-types/function-force-inlinee-data-struct.md +++ b/docs/build-insights/reference/sdk/c-event-data-types/function-force-inlinee-data-struct.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "FUNCTION_ ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/c-event-data-types/invocation-data-struct.md b/docs/build-insights/reference/sdk/c-event-data-types/invocation-data-struct.md index d677a9ba2a..2a188c9c00 100644 --- a/docs/build-insights/reference/sdk/c-event-data-types/invocation-data-struct.md +++ b/docs/build-insights/reference/sdk/c-event-data-types/invocation-data-struct.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "INVOCATIO ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/c-event-data-types/invocation-version-data-struct.md b/docs/build-insights/reference/sdk/c-event-data-types/invocation-version-data-struct.md index 1b509de566..29407ee025 100644 --- a/docs/build-insights/reference/sdk/c-event-data-types/invocation-version-data-struct.md +++ b/docs/build-insights/reference/sdk/c-event-data-types/invocation-version-data-struct.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "INVOCATIO ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/c-event-data-types/msvc-tool-code-enum.md b/docs/build-insights/reference/sdk/c-event-data-types/msvc-tool-code-enum.md index 085b863e04..c0c00c4d11 100644 --- a/docs/build-insights/reference/sdk/c-event-data-types/msvc-tool-code-enum.md +++ b/docs/build-insights/reference/sdk/c-event-data-types/msvc-tool-code-enum.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "MSVC_TOOL ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/c-event-data-types/name-value-pair-data-struct.md b/docs/build-insights/reference/sdk/c-event-data-types/name-value-pair-data-struct.md index d23ec9633a..f748ff97c1 100644 --- a/docs/build-insights/reference/sdk/c-event-data-types/name-value-pair-data-struct.md +++ b/docs/build-insights/reference/sdk/c-event-data-types/name-value-pair-data-struct.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "NAME_VALU ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/c-event-data-types/symbol-name-data-struct.md b/docs/build-insights/reference/sdk/c-event-data-types/symbol-name-data-struct.md index 2686e887ec..933167d616 100644 --- a/docs/build-insights/reference/sdk/c-event-data-types/symbol-name-data-struct.md +++ b/docs/build-insights/reference/sdk/c-event-data-types/symbol-name-data-struct.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "SYMBOL_NA ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/c-event-data-types/template-instantiation-data-struct.md b/docs/build-insights/reference/sdk/c-event-data-types/template-instantiation-data-struct.md index 32acf5af8c..a2056df0d0 100644 --- a/docs/build-insights/reference/sdk/c-event-data-types/template-instantiation-data-struct.md +++ b/docs/build-insights/reference/sdk/c-event-data-types/template-instantiation-data-struct.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TEMPLATE_ ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/c-event-data-types/template-instantiation-kind-code-enum.md b/docs/build-insights/reference/sdk/c-event-data-types/template-instantiation-kind-code-enum.md index 5d3d2f0e7e..f258401a81 100644 --- a/docs/build-insights/reference/sdk/c-event-data-types/template-instantiation-kind-code-enum.md +++ b/docs/build-insights/reference/sdk/c-event-data-types/template-instantiation-kind-code-enum.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TEMPLATE_ ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/c-event-data-types/trace-info-data-struct.md b/docs/build-insights/reference/sdk/c-event-data-types/trace-info-data-struct.md index 951e3ec00b..e5ab1bc130 100644 --- a/docs/build-insights/reference/sdk/c-event-data-types/trace-info-data-struct.md +++ b/docs/build-insights/reference/sdk/c-event-data-types/trace-info-data-struct.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TRACE_INF ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/c-event-data-types/translation-unit-pass-code-enum.md b/docs/build-insights/reference/sdk/c-event-data-types/translation-unit-pass-code-enum.md index f4a0700f2d..b309165509 100644 --- a/docs/build-insights/reference/sdk/c-event-data-types/translation-unit-pass-code-enum.md +++ b/docs/build-insights/reference/sdk/c-event-data-types/translation-unit-pass-code-enum.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TRANSLATI ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/c-event-data-types/translation-unit-type-data.md b/docs/build-insights/reference/sdk/c-event-data-types/translation-unit-type-data.md new file mode 100644 index 0000000000..6d7821bfa3 --- /dev/null +++ b/docs/build-insights/reference/sdk/c-event-data-types/translation-unit-type-data.md @@ -0,0 +1,38 @@ +--- +title: "TRANSLATION_UNIT_TYPE_DATA enum" +description: "The C++ Build Insights SDK TRANSLATION_UNIT_TYPE_DATA enum reference." +ms.date: "06/10/2021" +helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TRANSLATION_UNIT_TYPE_DATA", "throughput analysis", "build time analysis", "vcperf.exe"] +--- +# TRANSLATION_UNIT_TYPE_DATA enum + +::: moniker range="<=msvc-140" + +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. + +::: moniker-end +::: moniker range=">=msvc-150" + +The `TRANSLATION_UNIT_TYPE_DATA` structure describes the type of the translation unit in the compiler front end pass. + +## Syntax + +```cpp +typedef struct TRANSLATION_UNIT_TYPE_DATA_TAG +{ + int TranslationUnitType; + +} TRANSLATION_UNIT_TYPE_DATA; +``` + +## Members + +| Name | Description | +|--|--| +| `TranslationUnitType` | The type of this translation unit (either modules, header unit, or precompiled header). | + +## Remarks + +Used by the C SDK functions. + +::: moniker-end diff --git a/docs/build-insights/reference/sdk/c-event-data-types/translation-unit-type.md b/docs/build-insights/reference/sdk/c-event-data-types/translation-unit-type.md new file mode 100644 index 0000000000..1ee8e38e00 --- /dev/null +++ b/docs/build-insights/reference/sdk/c-event-data-types/translation-unit-type.md @@ -0,0 +1,30 @@ +--- +title: "TRANSLATION_UNIT_TYPE enum" +description: "The C++ Build Insights SDK TRANSLATION_UNIT_TYPE enum reference." +ms.date: "06/10/2021" +helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TRANSLATION_UNIT_TYPE", "throughput analysis", "build time analysis", "vcperf.exe"] +--- +# TRANSLATION_UNIT_TYPE enum + +::: moniker range="<=msvc-140" + +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. + +::: moniker-end +::: moniker range=">=msvc-150" + +The `TRANSLATION_UNIT_TYPE` enum. + +## Members + +| Name | Value | Description | +|--|--|--| +| `TRANSLATION_UNIT_TYPE_MODULE` | 0 (0x00000000) | The type of this translation unit is a module interface. | +| `TRANSLATION_UNIT_TYPE_HEADER_UNIT` | 1 (0x00000001) | The type of this translation unit is a header unit. | +| `TRANSLATION_UNIT_TYPE_PRECOMPILED_HEADER` | 2 (0x00000002) | The type of this translation unit is a precompiled header (PCH). | + +## Remarks + +Used by the C SDK functions. + +::: moniker-end diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/activity.md b/docs/build-insights/reference/sdk/cpp-event-data-types/activity.md index b70dc7053b..fbf985fe5d 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/activity.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/activity.md @@ -1,14 +1,17 @@ --- -title: "Activity class" -description: "The C++ Build Insights SDK Activity class reference." -ms.date: "02/12/2020" +title: "Activity class - C++ Build Insights SDK" +description: "The C++ Build Insights SDK Activity class reference. Use the Activity class to match any activity event." +ms.date: "06/16/2022" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Activity", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference +ms.custom: kr2b-contr-experiment --- + # Activity class ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/back-end-pass.md b/docs/build-insights/reference/sdk/cpp-event-data-types/back-end-pass.md index 176f95d945..076d93d4d9 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/back-end-pass.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/back-end-pass.md @@ -1,14 +1,17 @@ --- -title: "BackEndPass class" -description: "The C++ Build Insights SDK BackEndPass class reference." -ms.date: "02/12/2020" +title: "BackEndPass class - C++ Build Insights SDK" +description: "The C++ Build Insights SDK BackEndPass class reference. Use the BackEndPass class to match a BACK_END_PASS event." +ms.date: "06/16/2022" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "BackEndPass", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference +ms.custom: kr2b-contr-experiment --- + # BackEndPass class ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/bottom-up.md b/docs/build-insights/reference/sdk/cpp-event-data-types/bottom-up.md index ab3716c283..125c2478e5 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/bottom-up.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/bottom-up.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "BottomUp" ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/c1-dll.md b/docs/build-insights/reference/sdk/cpp-event-data-types/c1-dll.md index 24e19d6ec2..3982034e86 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/c1-dll.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/c1-dll.md @@ -1,14 +1,17 @@ --- -title: "C1DLL class" -description: "The C++ Build Insights SDK C1DLL class reference." -ms.date: "02/12/2020" +title: "C1DLL class - C++ Build Insights SDK" +description: "The C++ Build Insights SDK C1DLL class reference. Use the C1DLL class to match a C1_DLL event." +ms.date: "06/16/2022" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "C1DLL", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference +ms.custom: kr2b-contr-experiment --- + # C1DLL class ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/c2-dll.md b/docs/build-insights/reference/sdk/cpp-event-data-types/c2-dll.md index 2c90aacf1a..677326609c 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/c2-dll.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/c2-dll.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "C2DLL", " ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/code-generation.md b/docs/build-insights/reference/sdk/cpp-event-data-types/code-generation.md index 04ac8aecce..0ae7671e26 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/code-generation.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/code-generation.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "CodeGener ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/command-line.md b/docs/build-insights/reference/sdk/cpp-event-data-types/command-line.md index 0efc1ac555..9fcaa9a69f 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/command-line.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/command-line.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "CommandLi ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/compiler-pass.md b/docs/build-insights/reference/sdk/cpp-event-data-types/compiler-pass.md index 6342fd5e10..5fc55fa2ab 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/compiler-pass.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/compiler-pass.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "CompilerP ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" @@ -56,7 +56,7 @@ Along with the inherited members from its [Activity](activity.md) base class, th [InputSourcePath](#input-source-path)\ [OutputObjectPath](#output-object-path)\ -[PassCode](#pass-code)\ +[PassCode](#pass-code) ## CompilerPass diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/compiler.md b/docs/build-insights/reference/sdk/cpp-event-data-types/compiler.md index 6b8e9cfe64..12cc382a39 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/compiler.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/compiler.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Compiler" ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/environment-variable.md b/docs/build-insights/reference/sdk/cpp-event-data-types/environment-variable.md index 2e8b32922e..133484cb32 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/environment-variable.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/environment-variable.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Environme ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" @@ -38,7 +38,7 @@ Along with the inherited members from its [SimpleEvent](simple-event.md) base cl ### Functions -[Name](#name) +[Name](#name)\ [Value](#value) ## EnvironmentVariable diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/event-group.md b/docs/build-insights/reference/sdk/cpp-event-data-types/event-group.md index e68ba3afcf..6eeabda6f4 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/event-group.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/event-group.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "EventGrou ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" @@ -42,11 +42,11 @@ The activity type contained in the group. ### Functions -[Back](#back) -[begin](#begin) -[end](#end) -[Front](#front) -[operator[]](#subscript-operator) +[Back](#back)\ +[begin](#begin)\ +[end](#end)\ +[Front](#front)\ +[operator[]](#subscript-operator)\ [Size](#size) ## Back diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/event-stack.md b/docs/build-insights/reference/sdk/cpp-event-data-types/event-stack.md index f87fd70250..e206d537cf 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/event-stack.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/event-stack.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "EventStac ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" @@ -37,8 +37,8 @@ public: ### Functions -[Back](#back) -[operator[]](#subscript-operator) +[Back](#back)\ +[operator[]](#subscript-operator)\ [Size](#size) ## Back diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/event.md b/docs/build-insights/reference/sdk/cpp-event-data-types/event.md index df73263560..e4518cef9e 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/event.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/event.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Event", " ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" @@ -43,7 +43,7 @@ public: ### Functions -[Data](#data) +[Data](#data)\ [EventId](#event-id)\ [EventInstanceId](#event-instance-id)\ [EventName](#event-name)\ diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/executable-image-output.md b/docs/build-insights/reference/sdk/cpp-event-data-types/executable-image-output.md index 3cd217107f..850aea985c 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/executable-image-output.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/executable-image-output.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Executabl ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/exp-output.md b/docs/build-insights/reference/sdk/cpp-event-data-types/exp-output.md index 778f155738..179919e9a5 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/exp-output.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/exp-output.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "ExpOutput ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/file-input.md b/docs/build-insights/reference/sdk/cpp-event-data-types/file-input.md index 4d09203476..1607802410 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/file-input.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/file-input.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "FileInput ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" @@ -48,7 +48,7 @@ Along with the inherited members from its [SimpleEvent](simple-event.md) base cl ### Functions -[Path](#path) +[Path](#path)\ [Type](#type) ## FileInput diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/file-output.md b/docs/build-insights/reference/sdk/cpp-event-data-types/file-output.md index 2806b5c27e..f339588c6e 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/file-output.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/file-output.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "FileOutpu ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" @@ -48,7 +48,7 @@ Along with the inherited members from its [SimpleEvent](simple-event.md) base cl ### Functions -[Path](#path) +[Path](#path)\ [Type](#type) ## FileOutput diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/force-inlinee.md b/docs/build-insights/reference/sdk/cpp-event-data-types/force-inlinee.md index d22e076add..ee9bac8bc6 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/force-inlinee.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/force-inlinee.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "ForceInli ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" @@ -38,7 +38,7 @@ Along with the inherited members from its [SimpleEvent](simple-event.md) base cl ### Functions -[Name](#name) +[Name](#name)\ [Size](#size) ## ForceInlinee diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/front-end-file-group.md b/docs/build-insights/reference/sdk/cpp-event-data-types/front-end-file-group.md index 89cce934ec..d6a370160f 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/front-end-file-group.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/front-end-file-group.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "FrontEndF ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/front-end-file.md b/docs/build-insights/reference/sdk/cpp-event-data-types/front-end-file.md index efcced34c3..6cf0901f5e 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/front-end-file.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/front-end-file.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "FrontEndF ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/front-end-pass.md b/docs/build-insights/reference/sdk/cpp-event-data-types/front-end-pass.md index 23453b45c9..8d61fc735d 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/front-end-pass.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/front-end-pass.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "FrontEndP ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/function.md b/docs/build-insights/reference/sdk/cpp-event-data-types/function.md index 094719677a..bc81e6fbcf 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/function.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/function.md @@ -1,14 +1,16 @@ --- -title: "Function class" -description: "The C++ Build Insights SDK Function class reference." -ms.date: "02/12/2020" +title: "C++ Build Insights SDK Function class" +description: "The C++ Build Insights SDK Function class reference. Use the Function class to match a FUNCTION event." +ms.date: "04/27/2022" +ms.topic: language-reference +ms.custom: kr2b-contr-experiment helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Function", "throughput analysis", "build time analysis", "vcperf.exe"] --- # Function class ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" @@ -29,7 +31,7 @@ public: ## Members -Along with the inherited members from its [Activity](activity.md) base class, the `Function` class contains the following members: +Along with the inherited members from the [Activity](activity.md) base class, the `Function` class contains the following members: ### Constructors @@ -39,7 +41,7 @@ Along with the inherited members from its [Activity](activity.md) base class, th [Name](#name) -## Function +## Function ```cpp Function(const RawEvent& event); @@ -50,7 +52,7 @@ Function(const RawEvent& event); *event*\ A [FUNCTION](../event-table.md#function) event. -## Name +## Name ```cpp const char* Name() const; diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/header-unit.md b/docs/build-insights/reference/sdk/cpp-event-data-types/header-unit.md new file mode 100644 index 0000000000..d94130ba30 --- /dev/null +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/header-unit.md @@ -0,0 +1,51 @@ +--- +title: "HeaderUnit class" +description: "The C++ Build Insights SDK HeaderUnit class reference." +ms.date: "06/08/2021" +helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "HeaderUnit", "throughput analysis", "build time analysis", "vcperf.exe"] +--- +# HeaderUnit class + +::: moniker range="<=msvc-140" + +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. + +::: moniker-end +::: moniker range=">=msvc-150" + +The `HeaderUnit` class is used with the [MatchEvent](../functions/match-event.md), [MatchEventInMemberFunction](../functions/match-event-in-member-function.md), [MatchEventStack](../functions/match-event-stack.md), and [MatchEventStackInMemberFunction](../functions/match-event-stack-in-member-function.md) functions. Use it to match a [HEADER_UNIT](../event-table.md#header-unit) event. + +## Syntax + +```cpp +class HeaderUnit : public TranslationUnitType +{ +public: + HeaderUnit(const RawEvent& event); +}; +``` + +## Members + +Along with the inherited members from its [TranslationUnitType](translation-unit-type.md) base class, the `HeaderUnit` class contains the following members: + +### Constructors + +[HeaderUnit](#header-unit) + +### Functions + +None + +## HeaderUnit + +```cpp +HeaderUnit(const RawEvent& event); +``` + +### Parameters + +*event*\ +A [HEADER_UNIT](../event-table.md#header-unit) event. + +::: moniker-end diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/imp-lib-output.md b/docs/build-insights/reference/sdk/cpp-event-data-types/imp-lib-output.md index 94c6ab8344..88b5bcdbed 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/imp-lib-output.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/imp-lib-output.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "ImpLibOut ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/invocation-group.md b/docs/build-insights/reference/sdk/cpp-event-data-types/invocation-group.md index 8028237962..6fdae35fd4 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/invocation-group.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/invocation-group.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Invocatio ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/invocation.md b/docs/build-insights/reference/sdk/cpp-event-data-types/invocation.md index 01d7d5144a..3dc40659f7 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/invocation.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/invocation.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Invocatio ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" @@ -50,10 +50,10 @@ Along with the inherited members from its [Activity](activity.md) base class, th ### Functions -[ToolPath](#tool-path) -[ToolVersion](#tool-version) -[ToolVersionString](#tool-version-string) -[Type](#type) +[ToolPath](#tool-path)\ +[ToolVersion](#tool-version)\ +[ToolVersionString](#tool-version-string)\ +[Type](#type)\ [WorkingDirectory](#working-directory) ## Invocation diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/lib-output.md b/docs/build-insights/reference/sdk/cpp-event-data-types/lib-output.md index eeb5162255..aec337bdb0 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/lib-output.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/lib-output.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "LibOutput ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/linker-group.md b/docs/build-insights/reference/sdk/cpp-event-data-types/linker-group.md index a51e1850f5..ee1feada4d 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/linker-group.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/linker-group.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "LinkerGro ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/linker-pass.md b/docs/build-insights/reference/sdk/cpp-event-data-types/linker-pass.md index 16fde07fe3..d0219af45b 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/linker-pass.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/linker-pass.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "LinkerPas ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/linker.md b/docs/build-insights/reference/sdk/cpp-event-data-types/linker.md index 683aaaec43..4275f822e4 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/linker.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/linker.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Linker", ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/ltcg.md b/docs/build-insights/reference/sdk/cpp-event-data-types/ltcg.md index f049e4be9d..8895f29552 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/ltcg.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/ltcg.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "LTCG", "t ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/module.md b/docs/build-insights/reference/sdk/cpp-event-data-types/module.md new file mode 100644 index 0000000000..cbefd56200 --- /dev/null +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/module.md @@ -0,0 +1,51 @@ +--- +title: "Module class" +description: "The C++ Build Insights SDK Module class reference." +ms.date: "06/08/2021" +helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Module", "throughput analysis", "build time analysis", "vcperf.exe"] +--- +# Module class + +::: moniker range="<=msvc-140" + +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. + +::: moniker-end +::: moniker range=">=msvc-150" + +The `Module` class is used with the [MatchEvent](../functions/match-event.md), [MatchEventInMemberFunction](../functions/match-event-in-member-function.md), [MatchEventStack](../functions/match-event-stack.md), and [MatchEventStackInMemberFunction](../functions/match-event-stack-in-member-function.md) functions. Use it to match a [MODULE](../event-table.md#module) event. + +## Syntax + +```cpp +class Module : public TranslationUnitType +{ +public: + Module(const RawEvent& event); +}; +``` + +## Members + +Along with the inherited members from its [TranslationUnitType](translation-unit-type.md) base class, the `Module` class contains the following members: + +### Constructors + +[Module](#module) + +### Functions + +None + +## Module + +```cpp +Module(const RawEvent& event); +``` + +### Parameters + +*event*\ +A [MODULE](../event-table.md#module) event. + +::: moniker-end diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/obj-output.md b/docs/build-insights/reference/sdk/cpp-event-data-types/obj-output.md index e9f2ce5793..45c53b88f9 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/obj-output.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/obj-output.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "ObjOutput ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/opt-icf.md b/docs/build-insights/reference/sdk/cpp-event-data-types/opt-icf.md index f797d13613..dd1818a3aa 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/opt-icf.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/opt-icf.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "OptICF", ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/opt-lbr.md b/docs/build-insights/reference/sdk/cpp-event-data-types/opt-lbr.md index 38bde915c0..f4df6a6cdc 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/opt-lbr.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/opt-lbr.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "OptLBR", ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/opt-ref.md b/docs/build-insights/reference/sdk/cpp-event-data-types/opt-ref.md index 3e3a6d14cf..6b6b402ccd 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/opt-ref.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/opt-ref.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "OptRef", ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/pass1.md b/docs/build-insights/reference/sdk/cpp-event-data-types/pass1.md index 7d0036431a..6063aeef27 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/pass1.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/pass1.md @@ -1,14 +1,16 @@ --- -title: "Pass1 class" -description: "The C++ Build Insights SDK Pass1 class reference." -ms.date: "02/12/2020" +title: "C++ Build Insights SDK Pass1 class" +description: "The C++ Build Insights SDK Pass1 class reference. Use the Pass1 class to match a PASS1 event" +ms.date: "04/27/2022" +ms.topic: language-reference +ms.custom: kr2b-contr-experiment helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Pass1", "throughput analysis", "build time analysis", "vcperf.exe"] --- # Pass1 class ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" @@ -27,13 +29,13 @@ public: ## Members -Along with the inherited members from its [LinkerPass](linker-pass.md) base class, the `Pass1` class contains the following members: +Along with the inherited members from the [LinkerPass](linker-pass.md) base class, the `Pass1` class contains the following members: ### Constructors [Pass1](#pass1) -## Pass1 +## Pass1 ```cpp Pass1(const RawEvent& event); diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/pass2.md b/docs/build-insights/reference/sdk/cpp-event-data-types/pass2.md index 793d91826f..c99c01f596 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/pass2.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/pass2.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Pass2", " ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/pre-ltcg-opt-ref.md b/docs/build-insights/reference/sdk/cpp-event-data-types/pre-ltcg-opt-ref.md index 39129c4446..61bae8e818 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/pre-ltcg-opt-ref.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/pre-ltcg-opt-ref.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "PreLTCGOp ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/precompiled-header.md b/docs/build-insights/reference/sdk/cpp-event-data-types/precompiled-header.md new file mode 100644 index 0000000000..d2dcf369bd --- /dev/null +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/precompiled-header.md @@ -0,0 +1,51 @@ +--- +title: "PrecompiledHeader class" +description: "The C++ Build Insights SDK PrecompiledHeader class reference." +ms.date: "06/08/2021" +helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "PrecompiledHeader", "throughput analysis", "build time analysis", "vcperf.exe"] +--- +# PrecompiledHeader class + +::: moniker range="<=msvc-140" + +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. + +::: moniker-end +::: moniker range=">=msvc-150" + +The `PrecompiledHeader` class is used with the [MatchEvent](../functions/match-event.md), [MatchEventInMemberFunction](../functions/match-event-in-member-function.md), [MatchEventStack](../functions/match-event-stack.md), and [MatchEventStackInMemberFunction](../functions/match-event-stack-in-member-function.md) functions. Use it to match a [PRECOMPILED_HEADER](../event-table.md#precompiled-header) event. + +## Syntax + +```cpp +class PrecompiledHeader : public TranslationUnitType +{ +public: + PrecompiledHeader(const RawEvent& event); +}; +``` + +## Members + +Along with the inherited members from its [TranslationUnitType](translation-unit-type.md) base class, the `PrecompiledHeader` class contains the following members: + +### Constructors + +[PrecompiledHeader](#precompiled-header) + +### Functions + +None + +## PrecompiledHeader + +```cpp +PrecompiledHeader(const RawEvent& event); +``` + +### Parameters + +*event*\ +A [PRECOMPILED_HEADER](../event-table.md#precompiled-header) event. + +::: moniker-end diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/raw-event.md b/docs/build-insights/reference/sdk/cpp-event-data-types/raw-event.md index 86083f6154..ef78df1ffc 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/raw-event.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/raw-event.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "RawEvent" ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" @@ -67,8 +67,8 @@ If you don't want to convert ticks yourself, the `RawEvent` class provides membe [CPUTime](#cpu-time)\ [Data](#data)\ [Duration](#duration)\ -[EventId](#event-id) -[EventInstanceId](#event-instance-id) +[EventId](#event-id)\ +[EventInstanceId](#event-instance-id)\ [EventName](#event-name)\ [EventWideName](#event-wide-name)\ [ExclusiveCPUTicks](#exclusive-cpu-ticks)\ diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/simple-event.md b/docs/build-insights/reference/sdk/cpp-event-data-types/simple-event.md index c19a400570..b811c0bab2 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/simple-event.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/simple-event.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "SimpleEve ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/symbol-name.md b/docs/build-insights/reference/sdk/cpp-event-data-types/symbol-name.md index 21e57ba144..a172bccaea 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/symbol-name.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/symbol-name.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "SymbolNam ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" @@ -38,7 +38,7 @@ Along with the inherited members from its [SimpleEvent](simple-event.md) base cl ### Functions -[Key](#key) +[Key](#key)\ [Name](#name) ## Key diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/template-instantiation-group.md b/docs/build-insights/reference/sdk/cpp-event-data-types/template-instantiation-group.md index 7cc7a8d71e..1af54668f6 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/template-instantiation-group.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/template-instantiation-group.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TemplateI ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/template-instantiation.md b/docs/build-insights/reference/sdk/cpp-event-data-types/template-instantiation.md index e4b8a26e2d..b73bc7f4fb 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/template-instantiation.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/template-instantiation.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TemplateI ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" @@ -48,8 +48,8 @@ Along with the inherited members from its [Activity](activity.md) base class, th ### Functions -[Kind](#kind) -[PrimaryTemplateSymbolKey](#primary-template-symbol-key) +[Kind](#kind)\ +[PrimaryTemplateSymbolKey](#primary-template-symbol-key)\ [SpecializationSymbolKey](#specialization-symbol-key) ## Kind diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/thread.md b/docs/build-insights/reference/sdk/cpp-event-data-types/thread.md index 4bfaf7d8d7..290d7e8275 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/thread.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/thread.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Thread", ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/top-down.md b/docs/build-insights/reference/sdk/cpp-event-data-types/top-down.md index 1e1b264cf6..ecf52e8165 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/top-down.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/top-down.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TopDown", ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/trace-info.md b/docs/build-insights/reference/sdk/cpp-event-data-types/trace-info.md index 4172cc6060..0d7d0284f4 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/trace-info.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/trace-info.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TraceInfo ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" @@ -47,10 +47,10 @@ If you don't want to convert ticks yourself, the `TraceInfo` class provides a me ### Functions -[Duration](#duration) -[LogicalProcessorCount](#logical-processor-count) -[StartTimestamp](#start-timestamp) -[StopTimestamp](#stop-timestamp) +[Duration](#duration)\ +[LogicalProcessorCount](#logical-processor-count)\ +[StartTimestamp](#start-timestamp)\ +[StopTimestamp](#stop-timestamp)\ [TickFrequency](#tick-frequency) ## Duration diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/translation-unit-type.md b/docs/build-insights/reference/sdk/cpp-event-data-types/translation-unit-type.md new file mode 100644 index 0000000000..985dc0d3d4 --- /dev/null +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/translation-unit-type.md @@ -0,0 +1,70 @@ +--- +title: "TranslationUnitType class" +description: "The C++ Build Insights SDK TranslationUnitType class reference." +ms.date: "06/08/2021" +helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TranslationUnitType", "throughput analysis", "build time analysis", "vcperf.exe"] +--- +# TranslationUnitType class + +::: moniker range="<=msvc-140" + +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. + +::: moniker-end +::: moniker range=">=msvc-150" + +The `TranslationUnitType` class is used with the [MatchEvent](../functions/match-event.md), [MatchEventInMemberFunction](../functions/match-event-in-member-function.md), [MatchEventStack](../functions/match-event-stack.md), and [MatchEventStackInMemberFunction](../functions/match-event-stack-in-member-function.md) functions. Use it to match a [TRANSLATION_UNIT_TYPE](../event-table.md#translation-unit-type) event. + +## Syntax + +```cpp +class TranslationUnitType : public SimpleEvent +{ +public: + enum class Type + { + MODULE = TRANSLATION_UNIT_TYPE_MODULE, + HEADER_UNIT = TRANSLATION_UNIT_TYPE_HEADER_UNIT, + PCH = TRANSLATION_UNIT_TYPE_PRECOMPILED_HEADER + }; + + TranslationUnitType(const RawEvent& event); + + Type Type() const; +}; +``` + +## Members + +Along with the inherited members from its [SimpleEvent](simple-event.md) base class, the `TranslationUnitType` class contains the following members: + +### Constructors + +[TranslationUnitType](#translation-unit-type) + +### Functions + +[Type](#type) + +## Type + +```cpp +Type Type() const; +``` + +### Return Value + +The type of the translation unit: either MODULE, HEADER_UNIT, or PCH. + +## TranslationUnitType + +```cpp +TranslationUnitType(const RawEvent& event); +``` + +### Parameters + +*event*\ +A [TRANSLATION_UNIT_TYPE](../event-table.md#translation-unit-type) event. + +::: moniker-end diff --git a/docs/build-insights/reference/sdk/cpp-event-data-types/whole-program-analysis.md b/docs/build-insights/reference/sdk/cpp-event-data-types/whole-program-analysis.md index 4dbfbb9425..1afce1de2b 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/whole-program-analysis.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/whole-program-analysis.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "WholeProg ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/event-table.md b/docs/build-insights/reference/sdk/event-table.md index 84ccd6bc4b..2a2993364f 100644 --- a/docs/build-insights/reference/sdk/event-table.md +++ b/docs/build-insights/reference/sdk/event-table.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Events", ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" @@ -28,7 +28,10 @@ The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To s [C1_DLL](#c1-dll)\ [FRONT_END_FILE](#front-end-file)\ [TEMPLATE_INSTANTIATION](#template-instantiation)\ -[SYMBOL_NAME](#symbol-name) +[SYMBOL_NAME](#symbol-name)\ +[MODULE](#module)\ +[HEADER_UNIT](#header-unit)\ +[PRECOMPILED_HEADER](#precompiled-header) ## Compiler back-end events @@ -143,7 +146,7 @@ The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To s | | Description | Occurs when the compiler front end starts and stops processing a file. This event is recursive. Recursion happens when the front end is parsing included files. | | FRONT_END_PASS | Type | Activity | | | Parents | [COMPILER](#compiler) | -| | Children | [C1_DLL](#c1-dll) | +| | Children | [C1_DLL](#c1-dll)
[MODULE](#module)
[HEADER_UNIT](#header-unit)
[PRECOMPILED_HEADER](#precompiled-header) | | | Properties | - Absolute path to input source file
- Absolute path to output object file | | | Capture classes | [Activity](cpp-event-data-types/activity.md)
[CompilerPass](cpp-event-data-types/compiler-pass.md)
[FrontEndPass](cpp-event-data-types/front-end-pass.md) | | | Description | Occurs at the start and stop of the compiler front-end pass. This pass is responsible for parsing C/C++ source code and converting it into intermediate language. | @@ -153,6 +156,12 @@ The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To s | | Properties | - Name of the function | | | Capture classes | [Activity](cpp-event-data-types/activity.md)
[Function](cpp-event-data-types/function.md) | | | Description | Occurs when starting and ending generating the code for a function. | +| HEADER_UNIT | Type | Activity | +| | Parents | [FRONT_END_PASS](#front-end-pass) | +| | Children | None | +| | Properties | None | +| | Capture classes | [SimpleEvent](cpp-event-data-types/simple-event.md)
[TranslationUnitType](cpp-event-data-types/translation-unit-type.md)
[HeaderUnit](cpp-event-data-types/header-unit.md) | +| | Description | Occurs at the start of the front-end pass and represents that a header unit translation unit is being processed. | | IMP_LIB_OUTPUT | Type | Simple Event | | | Parents | [LINKER](#linker) | | | Children | None | @@ -177,6 +186,12 @@ The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To s | | Properties | None | | | Capture classes | [Activity](cpp-event-data-types/activity.md)
[LTCG](cpp-event-data-types/ltcg.md) | | | Description | Occurs at the start and stop of link-time code generation. | +| MODULE | Type | Activity | +| | Parents | [FRONT_END_PASS](#front-end-pass) | +| | Children | None | +| | Properties | None | +| | Capture classes | [SimpleEvent](cpp-event-data-types/simple-event.md)
[TranslationUnitType](cpp-event-data-types/translation-unit-type.md)
[Module](cpp-event-data-types/module.md) | +| | Description | Occurs at the start of the front-end pass and represents that a module translation unit is being processed. | | OBJ_OUTPUT | Type | Simple Event | | | Parents | [COMPILER](#compiler) | | | Children | None | @@ -213,6 +228,12 @@ The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To s | | Properties | None | | | Capture classes | [Activity](cpp-event-data-types/activity.md)
[Pass2](cpp-event-data-types/pass2.md) | | | Description | Occurs at the start and stop of the linker's pass 2. | +| PRECOMPILED_HEADER | Type | Activity | +| | Parents | [FRONT_END_PASS](#front-end-pass) | +| | Children | None | +| | Properties | None | +| | Capture classes | [SimpleEvent](cpp-event-data-types/simple-event.md)
[TranslationUnitType](cpp-event-data-types/translation-unit-type.md)
[PrecompiledHeader](cpp-event-data-types/precompiled-header.md) | +| | Description | Occurs at the start of the front-end pass and represents that a precompiled header (PCH) translation unit is being processed. | | PRE_LTCG_OPT_REF | Type | Activity | | | Parents | [PASS1](#pass1) | | | Children | None | @@ -243,6 +264,12 @@ The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To s | | Properties | None | | | Capture classes | [Activity](cpp-event-data-types/activity.md)
[TopDown](cpp-event-data-types/top-down.md) | | | Description | Occurs at the start and stop of the whole program analysis' top-down pass. | +| TRANSLATION_UNIT_TYPE | Type | Activity | +| | Parents | [FRONT_END_PASS](#front-end-pass) | +| | Children | [MODULE](#module)
[HEADER_UNIT](#header-unit)
[PRECOMPILED_HEADER](#precompiled-header) | +| | Properties | - The type of translation unit. | +| | Capture classes | [SimpleEvent](cpp-event-data-types/simple-event.md)
[TranslationUnitType](cpp-event-data-types/translation-unit-type.md) | +| | Description | Occurs at the start of the front-end pass. The type identifies whether this pass is processing a module, header unit, or precompiled header. | | WHOLE_PROGRAM_ANALYSIS | Type | Activity | | | Parents | [C2_DLL](#c2-dll) | | | Children | [BOTTOM_UP](#bottom-up)
[TOP_DOWN](#top-down) | diff --git a/docs/build-insights/reference/sdk/functions/analyze-a.md b/docs/build-insights/reference/sdk/functions/analyze-a.md index c0326a8f65..2f690eaa29 100644 --- a/docs/build-insights/reference/sdk/functions/analyze-a.md +++ b/docs/build-insights/reference/sdk/functions/analyze-a.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "AnalyzeA" ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/functions/analyze-w.md b/docs/build-insights/reference/sdk/functions/analyze-w.md index 822c1b931c..f7dc804272 100644 --- a/docs/build-insights/reference/sdk/functions/analyze-w.md +++ b/docs/build-insights/reference/sdk/functions/analyze-w.md @@ -1,14 +1,17 @@ --- -title: "AnalyzeW" -description: "The C++ Build Insights SDK AnalyzeW function reference." -ms.date: "02/12/2020" +title: "AnalyzeW - C++ Build Insights SDK" +description: "The C++ Build Insights SDK AnalyzeW function reference. Use the AnalyzeW function to analyze MSVC events read from an input Event Tracing for Windows trace." +ms.date: "06/16/2022" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "AnalyzeW", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference +ms.custom: kr2b-contr-experiment --- -# AnalyzeW + +# AnalyzeW function ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/functions/analyze.md b/docs/build-insights/reference/sdk/functions/analyze.md index 33b367ebaf..32e5bd369c 100644 --- a/docs/build-insights/reference/sdk/functions/analyze.md +++ b/docs/build-insights/reference/sdk/functions/analyze.md @@ -1,14 +1,17 @@ --- -title: "Analyze" -description: "The C++ Build Insights SDK Analyze function reference." -ms.date: "02/12/2020" +title: "Analyze - C++ Build Insights SDK" +description: "The C++ Build Insights SDK Analyze function reference. Use the Analyze function to analyze an Event Tracing for Windows trace from MSVC while tracing a build." +ms.date: "06/16/2022" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Analyze", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference +ms.custom: kr2b-contr-experiment --- -# Analyze + +# Analyze function ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/functions/inject-event.md b/docs/build-insights/reference/sdk/functions/inject-event.md index 90edbd03ab..e642578856 100644 --- a/docs/build-insights/reference/sdk/functions/inject-event.md +++ b/docs/build-insights/reference/sdk/functions/inject-event.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "InjectEve ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/functions/make-dynamic-analyzer-group.md b/docs/build-insights/reference/sdk/functions/make-dynamic-analyzer-group.md index 6125035362..0f67ad4504 100644 --- a/docs/build-insights/reference/sdk/functions/make-dynamic-analyzer-group.md +++ b/docs/build-insights/reference/sdk/functions/make-dynamic-analyzer-group.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "MakeDynam ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/functions/make-dynamic-relogger-group.md b/docs/build-insights/reference/sdk/functions/make-dynamic-relogger-group.md index dc581e7b9a..97ea2529d9 100644 --- a/docs/build-insights/reference/sdk/functions/make-dynamic-relogger-group.md +++ b/docs/build-insights/reference/sdk/functions/make-dynamic-relogger-group.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "MakeDynam ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/functions/make-static-analyzer-group.md b/docs/build-insights/reference/sdk/functions/make-static-analyzer-group.md index ea06633d31..e6aac87710 100644 --- a/docs/build-insights/reference/sdk/functions/make-static-analyzer-group.md +++ b/docs/build-insights/reference/sdk/functions/make-static-analyzer-group.md @@ -1,19 +1,21 @@ --- -title: "MakeStaticAnalyzerGroup" -description: "The C++ Build Insights SDK MakeStaticAnalyzerGroup function reference." -ms.date: "02/12/2020" +title: "C++ Build Insights SDK MakeStaticAnalyzerGroup" +description: "The C++ Build Insights SDK MakeStaticAnalyzerGroup function reference. Use this function to create a static analyzer group for functions like Analyze or Relog." +ms.date: "04/27/2022" +ms.topic: language-reference +ms.custom: kr2b-contr-experiment helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "MakeStaticAnalyzerGroup", "throughput analysis", "build time analysis", "vcperf.exe"] --- # MakeStaticAnalyzerGroup ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" -The `MakeStaticAnalyzerGroup` function is used to create a static analyzer group that can be passed to functions such as [`Analyze`](analyze.md) or [`Relog`](relog.md). Members of an analyzer group receive events one by one from left to right, until all events in a trace get analyzed. +The `MakeStaticAnalyzerGroup` function creates a static analyzer group that you can pass to functions such as [`Analyze`](analyze.md) or [`Relog`](relog.md). Members of an analyzer group receive events one by one from left to right, until all events in a trace are analyzed. ## Syntax @@ -32,10 +34,12 @@ A parameter pack of [`IAnalyzer`](../other-types/ianalyzer-class.md) pointers in ### Return Value -A static analyzer group. Use the **`auto`** keyword to capture the return value. +A static analyzer group. Use the `auto` keyword to capture the return value. ## Remarks -Unlike dynamic analyzer groups, the members of a static analyzer group must be known at compile time. Additionally, a static analyzer group contains [`IAnalyzer`](../other-types/ianalyzer-class.md) pointers that don't have polymorphic behavior. When using a static analyzer group to analyze an Event Tracing for Windows (ETW) trace, calls to the `IAnalyzer` interface always resolve to the object directly pointed to by the analyzer group member. This loss of flexibility comes with a possibility of faster event processing times. If the members of an analyzer group can't be known at compile time, or if you require polymorphic behavior on your `IAnalyzer` pointers, consider using a dynamic analyzer group. To use a dynamic analyzer group, call [`MakeDynamicAnalyzerGroup`](make-static-analyzer-group.md) instead. +Unlike dynamic analyzer groups, the members of a static analyzer group must be known at compile time. Also, a static analyzer group contains [`IAnalyzer`](../other-types/ianalyzer-class.md) pointers that don't have polymorphic behavior. When a static analyzer group analyzes an Event Tracing for Windows (ETW) trace, calls to the `IAnalyzer` interface always resolve to the object directly pointed to by the analyzer group member. This loss of flexibility comes with a possibility of faster event processing. + +If the members of an analyzer group can't be known at compile time, or if you require polymorphic behavior on your `IAnalyzer` pointers, consider using a dynamic analyzer group. To use a dynamic analyzer group, call [`MakeDynamicAnalyzerGroup`](make-static-analyzer-group.md) instead. ::: moniker-end diff --git a/docs/build-insights/reference/sdk/functions/make-static-relogger-group.md b/docs/build-insights/reference/sdk/functions/make-static-relogger-group.md index a800e6f7c9..1ea522b7e8 100644 --- a/docs/build-insights/reference/sdk/functions/make-static-relogger-group.md +++ b/docs/build-insights/reference/sdk/functions/make-static-relogger-group.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "MakeStati ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/functions/match-event-in-member-function.md b/docs/build-insights/reference/sdk/functions/match-event-in-member-function.md index ab5b1166aa..d0817f3dc9 100644 --- a/docs/build-insights/reference/sdk/functions/match-event-in-member-function.md +++ b/docs/build-insights/reference/sdk/functions/match-event-in-member-function.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "MatchEven ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/functions/match-event-stack-in-member-function.md b/docs/build-insights/reference/sdk/functions/match-event-stack-in-member-function.md index a9ad2bb234..2237139e8f 100644 --- a/docs/build-insights/reference/sdk/functions/match-event-stack-in-member-function.md +++ b/docs/build-insights/reference/sdk/functions/match-event-stack-in-member-function.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "MatchEven ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/functions/match-event-stack.md b/docs/build-insights/reference/sdk/functions/match-event-stack.md index b3f1b75759..55a15df0fa 100644 --- a/docs/build-insights/reference/sdk/functions/match-event-stack.md +++ b/docs/build-insights/reference/sdk/functions/match-event-stack.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "MatchEven ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/functions/match-event.md b/docs/build-insights/reference/sdk/functions/match-event.md index 65a738ebae..e392c3184d 100644 --- a/docs/build-insights/reference/sdk/functions/match-event.md +++ b/docs/build-insights/reference/sdk/functions/match-event.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "MatchEven ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/functions/relog-a.md b/docs/build-insights/reference/sdk/functions/relog-a.md index 166793f23b..ca57d0fdb6 100644 --- a/docs/build-insights/reference/sdk/functions/relog-a.md +++ b/docs/build-insights/reference/sdk/functions/relog-a.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "RelogA", ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/functions/relog-w.md b/docs/build-insights/reference/sdk/functions/relog-w.md index 091372d548..c4ed0ad3d9 100644 --- a/docs/build-insights/reference/sdk/functions/relog-w.md +++ b/docs/build-insights/reference/sdk/functions/relog-w.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "RelogW", ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/functions/relog.md b/docs/build-insights/reference/sdk/functions/relog.md index 8567b6cf17..13259b2978 100644 --- a/docs/build-insights/reference/sdk/functions/relog.md +++ b/docs/build-insights/reference/sdk/functions/relog.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Relog", " ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" @@ -77,4 +77,6 @@ The input trace is passed through the analyzer group *numberOfAnalysisPasses* ti The relogging of system events like CPU samples from within a relogger class isn't supported. Use the *systemEventsRetentionFlags* parameter to decide which system events to keep in the output trace. +The `relog` function depends on the COM API. You must call `CoInitialize` before you call `relog`. Call `CoUninitialize` once `relog` has finished. If you call `relog` without a call to `CoInitialize` first, you'll get error code 9 (`RESULT_CODE_FAILURE_START_RELOGGER`). + ::: moniker-end diff --git a/docs/build-insights/reference/sdk/functions/start-tracing-session-a.md b/docs/build-insights/reference/sdk/functions/start-tracing-session-a.md index 2c9dffc90e..117dcf7e3b 100644 --- a/docs/build-insights/reference/sdk/functions/start-tracing-session-a.md +++ b/docs/build-insights/reference/sdk/functions/start-tracing-session-a.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "StartTrac ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/functions/start-tracing-session-w.md b/docs/build-insights/reference/sdk/functions/start-tracing-session-w.md index 479e3bcc51..cac3ec1202 100644 --- a/docs/build-insights/reference/sdk/functions/start-tracing-session-w.md +++ b/docs/build-insights/reference/sdk/functions/start-tracing-session-w.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "StartTrac ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/functions/start-tracing-session.md b/docs/build-insights/reference/sdk/functions/start-tracing-session.md index 3cfc133416..78270e8aa0 100644 --- a/docs/build-insights/reference/sdk/functions/start-tracing-session.md +++ b/docs/build-insights/reference/sdk/functions/start-tracing-session.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "StartTrac ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/functions/stop-and-analyze-tracing-session-a.md b/docs/build-insights/reference/sdk/functions/stop-and-analyze-tracing-session-a.md index 24e3816509..34d8cff662 100644 --- a/docs/build-insights/reference/sdk/functions/stop-and-analyze-tracing-session-a.md +++ b/docs/build-insights/reference/sdk/functions/stop-and-analyze-tracing-session-a.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "StopAndAn ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/functions/stop-and-analyze-tracing-session-w.md b/docs/build-insights/reference/sdk/functions/stop-and-analyze-tracing-session-w.md index 7f281f5f41..3018e6ca94 100644 --- a/docs/build-insights/reference/sdk/functions/stop-and-analyze-tracing-session-w.md +++ b/docs/build-insights/reference/sdk/functions/stop-and-analyze-tracing-session-w.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "StopAndAn ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/functions/stop-and-analyze-tracing-session.md b/docs/build-insights/reference/sdk/functions/stop-and-analyze-tracing-session.md index 258262d408..fafece4a2d 100644 --- a/docs/build-insights/reference/sdk/functions/stop-and-analyze-tracing-session.md +++ b/docs/build-insights/reference/sdk/functions/stop-and-analyze-tracing-session.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "StopAndAn ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/functions/stop-and-relog-tracing-session-a.md b/docs/build-insights/reference/sdk/functions/stop-and-relog-tracing-session-a.md index b09f546576..408010651c 100644 --- a/docs/build-insights/reference/sdk/functions/stop-and-relog-tracing-session-a.md +++ b/docs/build-insights/reference/sdk/functions/stop-and-relog-tracing-session-a.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "StopAndRe ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/functions/stop-and-relog-tracing-session-w.md b/docs/build-insights/reference/sdk/functions/stop-and-relog-tracing-session-w.md index 665dfd4ed7..307e96dc1b 100644 --- a/docs/build-insights/reference/sdk/functions/stop-and-relog-tracing-session-w.md +++ b/docs/build-insights/reference/sdk/functions/stop-and-relog-tracing-session-w.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "StopAndRe ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/functions/stop-and-relog-tracing-session.md b/docs/build-insights/reference/sdk/functions/stop-and-relog-tracing-session.md index 857a335489..b89dc7f62f 100644 --- a/docs/build-insights/reference/sdk/functions/stop-and-relog-tracing-session.md +++ b/docs/build-insights/reference/sdk/functions/stop-and-relog-tracing-session.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "StopAndRe ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/functions/stop-tracing-session-a.md b/docs/build-insights/reference/sdk/functions/stop-tracing-session-a.md index 8636f81695..39ac969bab 100644 --- a/docs/build-insights/reference/sdk/functions/stop-tracing-session-a.md +++ b/docs/build-insights/reference/sdk/functions/stop-tracing-session-a.md @@ -8,12 +8,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "StopTraci ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" -The `StopTracingSessionA` function stops an ongoing tracing session and produces a raw trace file. Raw trace files can be passed to the [Analyze](analyze.md), [AnalzeA](analyze-a.md), and [AnalyzeW](analyze-w.md) functions to start an analysis session. Raw trace files can also be passed to the [Relog](relog.md), [RelogA](relog-a.md), and [RelogW](relog-w.md) functions to start relogging session. Executables calling `StopTracingSessionA` must have administrator privileges. +The `StopTracingSessionA` function stops an ongoing tracing session and produces a raw trace file. Raw trace files can be passed to the [Analyze](analyze.md), [AnalyzeA](analyze-a.md), and [AnalyzeW](analyze-w.md) functions to start an analysis session. Raw trace files can also be passed to the [Relog](relog.md), [RelogA](relog-a.md), and [RelogW](relog-w.md) functions to start relogging session. Executables calling `StopTracingSessionA` must have administrator privileges. ## Syntax diff --git a/docs/build-insights/reference/sdk/functions/stop-tracing-session-w.md b/docs/build-insights/reference/sdk/functions/stop-tracing-session-w.md index cc0f1adbbc..32e05f8ce8 100644 --- a/docs/build-insights/reference/sdk/functions/stop-tracing-session-w.md +++ b/docs/build-insights/reference/sdk/functions/stop-tracing-session-w.md @@ -8,12 +8,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "StopTraci ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" -The `StopTracingSessionW` function stops an ongoing tracing session and produces a raw trace file. Raw trace files can be passed to the [Analyze](analyze.md), [AnalzeA](analyze-a.md), and [AnalyzeW](analyze-w.md) functions to start an analysis session. Raw trace files can also be passed to the [Relog](relog.md), [RelogA](relog-a.md), and [RelogW](relog-w.md) functions to start relogging session. Executables calling `StopTracingSessionW` must have administrator privileges. +The `StopTracingSessionW` function stops an ongoing tracing session and produces a raw trace file. Raw trace files can be passed to the [Analyze](analyze.md), [AnalyzeA](analyze-a.md), and [AnalyzeW](analyze-w.md) functions to start an analysis session. Raw trace files can also be passed to the [Relog](relog.md), [RelogA](relog-a.md), and [RelogW](relog-w.md) functions to start relogging session. Executables calling `StopTracingSessionW` must have administrator privileges. ## Syntax diff --git a/docs/build-insights/reference/sdk/functions/stop-tracing-session.md b/docs/build-insights/reference/sdk/functions/stop-tracing-session.md index 69f30697de..9e52425ed8 100644 --- a/docs/build-insights/reference/sdk/functions/stop-tracing-session.md +++ b/docs/build-insights/reference/sdk/functions/stop-tracing-session.md @@ -1,19 +1,23 @@ --- -title: "StopTracingSession" -description: "The C++ Build Insights SDK StopTracingSession function reference." -ms.date: "02/12/2020" +title: "C++ Build Insights SDK StopTracingSession" +description: "The C++ Build Insights SDK StopTracingSession function reference. StopTracingSession stops an ongoing tracing session and produces a raw trace file." +ms.date: "04/27/2022" +ms.topic: language-reference +ms.custom: kr2b-contr-experiment helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "StopTracingSession", "throughput analysis", "build time analysis", "vcperf.exe"] --- # StopTracingSession ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" -The `StopTracingSession` function stops an ongoing tracing session and produces a raw trace file. Raw trace files can be passed to the [Analyze](analyze.md), [AnalzeA](analyze-a.md), and [AnalyzeW](analyze-w.md) functions to start an analysis session. Raw trace files can also be passed to the [Relog](relog.md), [RelogA](relog-a.md), and [RelogW](relog-w.md) functions to start a relogging session. Executables calling `StopTracingSession` must have administrator privileges. +The `StopTracingSession` function stops an ongoing tracing session and produces a raw trace file. You can pass raw trace files to the [Analyze](analyze.md), [AnalyzeA](analyze-a.md), and [AnalyzeW](analyze-w.md) functions to start an analysis session. You can pass raw trace files to the [Relog](relog.md), [RelogA](relog-a.md), and [RelogW](relog-w.md) functions to start a relogging session. + +The caller must have administrator permissions to use `StopTracingSession`. ## Syntax @@ -24,7 +28,7 @@ inline RESULT_CODE StopTracingSession( TRACING_SESSION_STATISTICS* statistics); inline RESULT_CODE StopTracingSession( - const wchar_t* sessionName + const wchar_t* sessionName, const wchar_t* outputLogFile, TRACING_SESSION_STATISTICS* statistics); ``` @@ -32,10 +36,10 @@ inline RESULT_CODE StopTracingSession( ### Parameters *sessionName*\ -The name of the tracing session to stop. Use the same session name as the one passed to [StartTracingSession](start-tracing-session.md), [StartTracingSessionA](start-tracing-session-a.md), or [StartTracingSessionW](start-tracing-session-w.md). +The name of the tracing session to stop. Use the same session name as used for [StartTracingSession](start-tracing-session.md), [StartTracingSessionA](start-tracing-session-a.md), or [StartTracingSessionW](start-tracing-session-w.md). *outputLogFile*\ -Path to the final output log file where the raw trace should be saved. +Full path of the final output log file to save the raw trace. *statistics*\ Pointer to a [TRACING_SESSION_STATISTICS](../other-types/tracing-session-statistics-struct.md) object. `StopTracingSession` writes trace collection statistics in this object before returning. diff --git a/docs/build-insights/reference/sdk/other-types/analysis-callbacks-struct.md b/docs/build-insights/reference/sdk/other-types/analysis-callbacks-struct.md index d95f2c2221..2957df07f1 100644 --- a/docs/build-insights/reference/sdk/other-types/analysis-callbacks-struct.md +++ b/docs/build-insights/reference/sdk/other-types/analysis-callbacks-struct.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "ANALYSIS_ ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/other-types/analysis-control-enum-class.md b/docs/build-insights/reference/sdk/other-types/analysis-control-enum-class.md index 79cd00995b..b3426f035e 100644 --- a/docs/build-insights/reference/sdk/other-types/analysis-control-enum-class.md +++ b/docs/build-insights/reference/sdk/other-types/analysis-control-enum-class.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "AnalysisC ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/other-types/analysis-descriptor-struct.md b/docs/build-insights/reference/sdk/other-types/analysis-descriptor-struct.md index 16835e82d1..73012b0d9a 100644 --- a/docs/build-insights/reference/sdk/other-types/analysis-descriptor-struct.md +++ b/docs/build-insights/reference/sdk/other-types/analysis-descriptor-struct.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "ANALYSIS_ ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/other-types/callback-code-enum.md b/docs/build-insights/reference/sdk/other-types/callback-code-enum.md index 671f852f51..157b5e4534 100644 --- a/docs/build-insights/reference/sdk/other-types/callback-code-enum.md +++ b/docs/build-insights/reference/sdk/other-types/callback-code-enum.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "CALLBACK_ ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/other-types/ianalyzer-class.md b/docs/build-insights/reference/sdk/other-types/ianalyzer-class.md index 99c29eade9..b08d6a4ab3 100644 --- a/docs/build-insights/reference/sdk/other-types/ianalyzer-class.md +++ b/docs/build-insights/reference/sdk/other-types/ianalyzer-class.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "IAnalyzer ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/other-types/irelogger-class.md b/docs/build-insights/reference/sdk/other-types/irelogger-class.md index 5d5a44a2bd..8fedb9fc5b 100644 --- a/docs/build-insights/reference/sdk/other-types/irelogger-class.md +++ b/docs/build-insights/reference/sdk/other-types/irelogger-class.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "IRelogger ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/other-types/on-analysis-event-func-typedef.md b/docs/build-insights/reference/sdk/other-types/on-analysis-event-func-typedef.md index 63f993e60f..d063b48e89 100644 --- a/docs/build-insights/reference/sdk/other-types/on-analysis-event-func-typedef.md +++ b/docs/build-insights/reference/sdk/other-types/on-analysis-event-func-typedef.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "OnAnalysi ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/other-types/on-begin-end-pass-func-typedef.md b/docs/build-insights/reference/sdk/other-types/on-begin-end-pass-func-typedef.md index c07cb82d6c..505cc21c6e 100644 --- a/docs/build-insights/reference/sdk/other-types/on-begin-end-pass-func-typedef.md +++ b/docs/build-insights/reference/sdk/other-types/on-begin-end-pass-func-typedef.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "OnBeginEn ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/other-types/on-relog-event-func-typedef.md b/docs/build-insights/reference/sdk/other-types/on-relog-event-func-typedef.md index ac61f5ae45..af1d88f1ff 100644 --- a/docs/build-insights/reference/sdk/other-types/on-relog-event-func-typedef.md +++ b/docs/build-insights/reference/sdk/other-types/on-relog-event-func-typedef.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "OnRelogEv ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/other-types/on-trace-info-func-typedef.md b/docs/build-insights/reference/sdk/other-types/on-trace-info-func-typedef.md index 15f6bba012..9d90ce108a 100644 --- a/docs/build-insights/reference/sdk/other-types/on-trace-info-func-typedef.md +++ b/docs/build-insights/reference/sdk/other-types/on-trace-info-func-typedef.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "OnTraceIn ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/other-types/relog-callbacks-struct.md b/docs/build-insights/reference/sdk/other-types/relog-callbacks-struct.md index db6fa74b8c..4232ac43f4 100644 --- a/docs/build-insights/reference/sdk/other-types/relog-callbacks-struct.md +++ b/docs/build-insights/reference/sdk/other-types/relog-callbacks-struct.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "RELOG_CAL ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/other-types/relog-descriptor-struct.md b/docs/build-insights/reference/sdk/other-types/relog-descriptor-struct.md index 934f9e431c..756616dbbc 100644 --- a/docs/build-insights/reference/sdk/other-types/relog-descriptor-struct.md +++ b/docs/build-insights/reference/sdk/other-types/relog-descriptor-struct.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "RELOG_DES ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/other-types/relog-retention-system-event-flags-constants.md b/docs/build-insights/reference/sdk/other-types/relog-retention-system-event-flags-constants.md index daa02b1fd3..103d7f456b 100644 --- a/docs/build-insights/reference/sdk/other-types/relog-retention-system-event-flags-constants.md +++ b/docs/build-insights/reference/sdk/other-types/relog-retention-system-event-flags-constants.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "RELOG_RET ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/other-types/result-code-enum.md b/docs/build-insights/reference/sdk/other-types/result-code-enum.md index 27318139aa..6cc9ba32d4 100644 --- a/docs/build-insights/reference/sdk/other-types/result-code-enum.md +++ b/docs/build-insights/reference/sdk/other-types/result-code-enum.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "RESULT_CO ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/other-types/tracing-session-msvc-event-flags-constants.md b/docs/build-insights/reference/sdk/other-types/tracing-session-msvc-event-flags-constants.md index 95f5ed3c19..f54881ad7f 100644 --- a/docs/build-insights/reference/sdk/other-types/tracing-session-msvc-event-flags-constants.md +++ b/docs/build-insights/reference/sdk/other-types/tracing-session-msvc-event-flags-constants.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TRACING_S ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/other-types/tracing-session-options-struct.md b/docs/build-insights/reference/sdk/other-types/tracing-session-options-struct.md index db91e7a130..88116edfe1 100644 --- a/docs/build-insights/reference/sdk/other-types/tracing-session-options-struct.md +++ b/docs/build-insights/reference/sdk/other-types/tracing-session-options-struct.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TRACING_S ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/other-types/tracing-session-statistics-struct.md b/docs/build-insights/reference/sdk/other-types/tracing-session-statistics-struct.md index 4f427f8e7c..67374d0acf 100644 --- a/docs/build-insights/reference/sdk/other-types/tracing-session-statistics-struct.md +++ b/docs/build-insights/reference/sdk/other-types/tracing-session-statistics-struct.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TRACING_S ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/other-types/tracing-session-system-event-flags-constants.md b/docs/build-insights/reference/sdk/other-types/tracing-session-system-event-flags-constants.md index 694868c710..4e24aea5d9 100644 --- a/docs/build-insights/reference/sdk/other-types/tracing-session-system-event-flags-constants.md +++ b/docs/build-insights/reference/sdk/other-types/tracing-session-system-event-flags-constants.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TRACING_S ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" diff --git a/docs/build-insights/reference/sdk/overview.md b/docs/build-insights/reference/sdk/overview.md index 27f3ac328e..483b547d4f 100644 --- a/docs/build-insights/reference/sdk/overview.md +++ b/docs/build-insights/reference/sdk/overview.md @@ -8,7 +8,7 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Analyzing ::: moniker range="<=msvc-140" -The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights SDK is compatible with Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end ::: moniker range=">=msvc-150" @@ -135,7 +135,7 @@ int main() | Functionality | C++ API | C API | Notes | |--|--|--|--| | Matching and filtering events | [MatchEventStackInMemberFunction](functions/match-event-stack-in-member-function.md)
[MatchEventStack](functions/match-event-stack.md)
[MatchEventInMemberFunction](functions/match-event-in-member-function.md)
[MatchEvent](functions/match-event.md) | | The C++ API offers functions that make it easy to extract the events you care about from your traces. With the C API, this filtering must be done by hand. | -| Event data types | [Activity](cpp-event-data-types/activity.md)
[BackEndPass](cpp-event-data-types/back-end-pass.md)
[BottomUp](cpp-event-data-types/bottom-up.md)
[C1DLL](cpp-event-data-types/c1-dll.md)
[C2DLL](cpp-event-data-types/c2-dll.md)
[CodeGeneration](cpp-event-data-types/code-generation.md)
[CommandLine](cpp-event-data-types/command-line.md)
[Compiler](cpp-event-data-types/compiler.md)
[CompilerPass](cpp-event-data-types/compiler-pass.md)
[EnvironmentVariable](cpp-event-data-types/environment-variable.md)
[Event](cpp-event-data-types/event.md)
[EventGroup](cpp-event-data-types/event-group.md)
[EventStack](cpp-event-data-types/event-stack.md)
[ExecutableImageOutput](cpp-event-data-types/executable-image-output.md)
[ExpOutput](cpp-event-data-types/exp-output.md)
[FileInput](cpp-event-data-types/file-input.md)
[FileOutput](cpp-event-data-types/file-output.md)
[ForceInlinee](cpp-event-data-types/force-inlinee.md)
[FrontEndFile](cpp-event-data-types/front-end-file.md)
[FrontEndFileGroup](cpp-event-data-types/front-end-file-group.md)
[FrontEndPass](cpp-event-data-types/front-end-pass.md)
[Function](cpp-event-data-types/function.md)
[ImpLibOutput](cpp-event-data-types/imp-lib-output.md)
[Invocation](cpp-event-data-types/invocation.md)
[InvocationGroup](cpp-event-data-types/invocation-group.md)
[LibOutput](cpp-event-data-types/lib-output.md)
[Linker](cpp-event-data-types/linker.md)
[LinkerGroup](cpp-event-data-types/linker-group.md)
[LinkerPass](cpp-event-data-types/linker-pass.md)
[LTCG](cpp-event-data-types/ltcg.md)
[ObjOutput](cpp-event-data-types/obj-output.md)
[OptICF](cpp-event-data-types/opt-icf.md)
[OptLBR](cpp-event-data-types/opt-lbr.md)
[OptRef](cpp-event-data-types/opt-ref.md)
[Pass1](cpp-event-data-types/pass1.md)
[Pass2](cpp-event-data-types/pass2.md)
[PreLTCGOptRef](cpp-event-data-types/pre-ltcg-opt-ref.md)
[SimpleEvent](cpp-event-data-types/simple-event.md)
[SymbolName](cpp-event-data-types/symbol-name.md)
[TemplateInstantiation](cpp-event-data-types/template-instantiation.md)
[TemplateInstantiationGroup](cpp-event-data-types/template-instantiation-group.md)
[Thread](cpp-event-data-types/thread.md)
[TopDown](cpp-event-data-types/top-down.md)
[TraceInfo](cpp-event-data-types/trace-info.md)
[WholeProgramAnalysis](cpp-event-data-types/whole-program-analysis.md) | [CL_PASS_DATA](c-event-data-types/cl-pass-data-struct.md)
[EVENT_COLLECTION_DATA](c-event-data-types/event-collection-data-struct.md)
[EVENT_DATA](c-event-data-types/event-data-struct.md)
[EVENT_ID](c-event-data-types/event-id-enum.md)
[FILE_DATA](c-event-data-types/file-data-struct.md)
[FILE_TYPE_CODE](c-event-data-types/file-type-code-enum.md)
[FRONT_END_FILE_DATA](c-event-data-types/front-end-file-data-struct.md)
[FUNCTION_DATA](c-event-data-types/function-data-struct.md)
[FUNCTION_FORCE_INLINEE_DATA](c-event-data-types/function-force-inlinee-data-struct.md)
[INVOCATION_DATA](c-event-data-types/invocation-data-struct.md)
[INVOCATION_VERSION_DATA](c-event-data-types/invocation-version-data-struct.md)
[MSVC_TOOL_CODE](c-event-data-types/msvc-tool-code-enum.md)
[NAME_VALUE_PAIR_DATA](c-event-data-types/name-value-pair-data-struct.md)
[SYMBOL_NAME_DATA](c-event-data-types/symbol-name-data-struct.md)
[TEMPLATE_INSTANTIATION_DATA](c-event-data-types/template-instantiation-data-struct.md)
[TEMPLATE_INSTANTIATION_KIND_CODE](c-event-data-types/template-instantiation-kind-code-enum.md)
[TRACE_INFO_DATA](c-event-data-types/trace-info-data-struct.md)
[TRANSLATION_UNIT_PASS_CODE](c-event-data-types/translation-unit-pass-code-enum.md) | | +| Event data types | [Activity](cpp-event-data-types/activity.md)
[BackEndPass](cpp-event-data-types/back-end-pass.md)
[BottomUp](cpp-event-data-types/bottom-up.md)
[C1DLL](cpp-event-data-types/c1-dll.md)
[C2DLL](cpp-event-data-types/c2-dll.md)
[CodeGeneration](cpp-event-data-types/code-generation.md)
[CommandLine](cpp-event-data-types/command-line.md)
[Compiler](cpp-event-data-types/compiler.md)
[CompilerPass](cpp-event-data-types/compiler-pass.md)
[EnvironmentVariable](cpp-event-data-types/environment-variable.md)
[Event](cpp-event-data-types/event.md)
[EventGroup](cpp-event-data-types/event-group.md)
[EventStack](cpp-event-data-types/event-stack.md)
[ExecutableImageOutput](cpp-event-data-types/executable-image-output.md)
[ExpOutput](cpp-event-data-types/exp-output.md)
[FileInput](cpp-event-data-types/file-input.md)
[FileOutput](cpp-event-data-types/file-output.md)
[ForceInlinee](cpp-event-data-types/force-inlinee.md)
[FrontEndFile](cpp-event-data-types/front-end-file.md)
[FrontEndFileGroup](cpp-event-data-types/front-end-file-group.md)
[FrontEndPass](cpp-event-data-types/front-end-pass.md)
[Function](cpp-event-data-types/function.md)
[HeaderUnit](cpp-event-data-types/header-unit.md)
[ImpLibOutput](cpp-event-data-types/imp-lib-output.md)
[Invocation](cpp-event-data-types/invocation.md)
[InvocationGroup](cpp-event-data-types/invocation-group.md)
[LibOutput](cpp-event-data-types/lib-output.md)
[Linker](cpp-event-data-types/linker.md)
[LinkerGroup](cpp-event-data-types/linker-group.md)
[LinkerPass](cpp-event-data-types/linker-pass.md)
[LTCG](cpp-event-data-types/ltcg.md)
[Module](cpp-event-data-types/module.md)
[ObjOutput](cpp-event-data-types/obj-output.md)
[OptICF](cpp-event-data-types/opt-icf.md)
[OptLBR](cpp-event-data-types/opt-lbr.md)
[OptRef](cpp-event-data-types/opt-ref.md)
[Pass1](cpp-event-data-types/pass1.md)
[Pass2](cpp-event-data-types/pass2.md)
[PrecompiledHeader](cpp-event-data-types/precompiled-header.md)
[PreLTCGOptRef](cpp-event-data-types/pre-ltcg-opt-ref.md)
[SimpleEvent](cpp-event-data-types/simple-event.md)
[SymbolName](cpp-event-data-types/symbol-name.md)
[TemplateInstantiation](cpp-event-data-types/template-instantiation.md)
[TemplateInstantiationGroup](cpp-event-data-types/template-instantiation-group.md)
[Thread](cpp-event-data-types/thread.md)
[TopDown](cpp-event-data-types/top-down.md)
[TraceInfo](cpp-event-data-types/trace-info.md)
[TranslationUnitType](cpp-event-data-types/translation-unit-type.md)
[WholeProgramAnalysis](cpp-event-data-types/whole-program-analysis.md) | [CL_PASS_DATA](c-event-data-types/cl-pass-data-struct.md)
[EVENT_COLLECTION_DATA](c-event-data-types/event-collection-data-struct.md)
[EVENT_DATA](c-event-data-types/event-data-struct.md)
[EVENT_ID](c-event-data-types/event-id-enum.md)
[FILE_DATA](c-event-data-types/file-data-struct.md)
[FILE_TYPE_CODE](c-event-data-types/file-type-code-enum.md)
[FRONT_END_FILE_DATA](c-event-data-types/front-end-file-data-struct.md)
[FUNCTION_DATA](c-event-data-types/function-data-struct.md)
[FUNCTION_FORCE_INLINEE_DATA](c-event-data-types/function-force-inlinee-data-struct.md)
[INVOCATION_DATA](c-event-data-types/invocation-data-struct.md)
[INVOCATION_VERSION_DATA](c-event-data-types/invocation-version-data-struct.md)
[MSVC_TOOL_CODE](c-event-data-types/msvc-tool-code-enum.md)
[NAME_VALUE_PAIR_DATA](c-event-data-types/name-value-pair-data-struct.md)
[SYMBOL_NAME_DATA](c-event-data-types/symbol-name-data-struct.md)
[TEMPLATE_INSTANTIATION_DATA](c-event-data-types/template-instantiation-data-struct.md)
[TEMPLATE_INSTANTIATION_KIND_CODE](c-event-data-types/template-instantiation-kind-code-enum.md)
[TRACE_INFO_DATA](c-event-data-types/trace-info-data-struct.md)
[TRANSLATION_UNIT_PASS_CODE](c-event-data-types/translation-unit-pass-code-enum.md)
[TRANSLATION_UNIT_TYPE](c-event-data-types/translation-unit-type.md)
[TRANSLATION_UNIT_TYPE_DATA](c-event-data-types/translation-unit-type-data.md) | | ### Activities and simple events diff --git a/docs/build-insights/reference/vcperf-commands.md b/docs/build-insights/reference/vcperf-commands.md index 6710813003..ed8342bf1b 100644 --- a/docs/build-insights/reference/vcperf-commands.md +++ b/docs/build-insights/reference/vcperf-commands.md @@ -8,32 +8,33 @@ helpviewer_keywords: ["C++ Build Insights", "throughput analysis", "build time a ::: moniker range="<=msvc-150" -The C++ Build Insights tools are available in Visual Studio 2019. To see the documentation for that version, set the Visual Studio **Version** selector control for this article to Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights tools are available starting in Visual Studio 2019 and later. To see the documentation for that version, set the Visual Studio **Version** selector control for this article to Visual Studio 2019 or later. It's found at the top of the table of contents on this page. ::: moniker-end -::: moniker range="msvc-160" +::: moniker range=">=msvc-160" -This article lists and describes the commands available in *vcperf.exe*, and how to use them. +This article lists and describes the commands available in *`vcperf.exe`*, and how to use them. ## Commands to start and stop traces -*IMPORTANT: the following commands all require administrative privileges.* +> [!IMPORTANT] +> Unless you specify `/noadmin`, the following commands require administrative privileges. | Option | Arguments and description | |------------------|---------------------------| -| `/start` | `[/nocpusampling]` `` | -| | Tells *vcperf.exe* to start a trace under the given session name. There can only be one active session at a time on a given machine.

If the `/nocpusampling` option is specified, *vcperf.exe* doesn't collect CPU samples. It prevents the use of the CPU Usage (Sampled) view in Windows Performance Analyzer, but makes the collected traces smaller.

Once tracing is started, *vcperf.exe* returns immediately. Events are collected system-wide for all processes running on the machine. That means that you don't need to build your project from the same command prompt as the one you used to run *vcperf.exe*. For example, you can build your project from Visual Studio. | -| `/stop` | `` `` | -| | Stops the trace identified by the given session name. Runs a post-processing step on the trace to generate a file viewable in Windows Performance Analyzer (WPA). For the best viewing experience, use a version of WPA that includes the C++ Build Insights add-in. For more information, see [Get started with C++ Build Insights](../get-started-with-cpp-build-insights.md). The `` parameter specifies where to save the output file. | -| `/stopnoanalyze` | `` `` | -| | Stops the trace identified by the given session name and writes the raw, unprocessed data in the specified output file. The resulting file isn't meant to be viewed in WPA.

The post-processing step involved in the `/stop` command can sometimes be lengthy. You can use the `/stopnoanalyze` command to delay this post-processing step. Use the `/analyze` command when you're ready to produce a file viewable in Windows Performance Analyzer. | +| `/start` | [`/noadmin`] [`/nocpusampling`] [`/level1` \| `/level2` \| `/level3`] `` | +| | Starts a trace under the given session name.

The `/noadmin` option runs *vcperf.exe* without admin privileges, and it ignores the `/nocpusampling` option. When you run vcperf without admin privileges, there can be more than one active session on a given machine.

The `/nocpusampling` option specifies *vcperf.exe* doesn't collect CPU samples. It prevents the use of the CPU Usage (Sampled) view in Windows Performance Analyzer, but makes the collected traces smaller.

The `/level1`, `/level2`, or `/level3` options specify which MSVC events to collect, in increasing level of information. Level 3 includes all events. Level 2 includes all events except template instantiation events. Level 1 includes all events except template instantiation, function, and file events. If unspecified, `/level2` is selected by default.

Once *vcperf.exe* starts the trace, it returns immediately. The trace collects events system-wide for all processes running on the machine. That means that you don't need to build your project in the same command prompt window as the one you use to run *vcperf.exe*. For example, you can build your project in Visual Studio. | +| `/stop` | (1) [`/templates`] ` `
(2) [`/templates`] ` /timetrace ` | +| | Stops the trace identified by the given session name. Runs a post-processing step on the trace to generate a file specified by the `` parameter.

The `/templates` option includes template instantiation events in the file.

(1) Generates a file viewable in Windows Performance Analyzer (WPA). The output file requires a `.etl` extension.
(2) Generates a file viewable in the Microsoft Edge trace viewer (`edge://tracing`). The output file requires a `.json` extension. | +| `/stopnoanalyze` | ` ` | +| | Stops the trace identified by the given session name and writes the raw, unprocessed data in the specified output file. The resulting file isn't meant for viewing in WPA.

The post-processing step involved in the `/stop` command can sometimes be lengthy. You can use the `/stopnoanalyze` command to delay this post-processing step. Use the `/analyze` command when you're ready to produce a file viewable in Windows Performance Analyzer or the Microsoft Edge trace viewer. | ## Miscellaneous commands | Option | Arguments and description | |------------|---------------------------| -| `/analyze` | ` ` | -| | Accepts a raw trace file produced by the `/stopnoanalyze` command. Runs a post-processing step on this trace to generate a file viewable in Windows Performance Analyzer. For the best viewing experience, use a version of WPA that includes the C++ Build Insights add-in. For more information, see [Get started with C++ Build Insights](../get-started-with-cpp-build-insights.md). | +| `/analyze` | (1) [`/templates`] ` `
(2) [`/templates`] ` /timetrace ` | +| | Accepts a raw trace file produced by the `/stopnoanalyze` command. Runs a post-processing step on this trace to generate the file specified by the `` parameter.

The `/templates` option includes template instantiation events in the file.

(1) Generates a file viewable in Windows Performance Analyzer (WPA). The output file requires a `.etl` extension.

(2) Generates a file viewable in the Microsoft Edge trace viewer (`edge://tracing`). The output file requires a `.json` extension. | ## See also diff --git a/docs/build-insights/reference/wpa-views.md b/docs/build-insights/reference/wpa-views.md index b12a0c99fa..a7c5391f5c 100644 --- a/docs/build-insights/reference/wpa-views.md +++ b/docs/build-insights/reference/wpa-views.md @@ -8,10 +8,10 @@ helpviewer_keywords: ["C++ Build Insights", "throughput analysis", "build time a ::: moniker range="<=msvc-150" -The C++ Build Insights tools are available in Visual Studio 2019. To see the documentation for this version, set the Visual Studio **Version** selector control for this article to Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights tools are available in Visual Studio 2019 and later. To see the documentation for this version, set the Visual Studio **Version** selector control for this article to Visual Studio 2019 or later. It's found at the top of the table of contents on this page. ::: moniker-end -::: moniker range="msvc-160" +::: moniker range=">=msvc-160" This article provides details on each of the C++ Build Insights views available in Windows Performance Analyzer (WPA). Use this page to find: diff --git a/docs/build-insights/toc.yml b/docs/build-insights/toc.yml index f571b06818..99cea23e5b 100644 --- a/docs/build-insights/toc.yml +++ b/docs/build-insights/toc.yml @@ -1,3 +1,4 @@ +items: - name: "C++ Build Insights" href: ../build-insights/index.yml - name: "Get started with C++ Build Insights" @@ -5,6 +6,12 @@ - name: "Tutorials" expanded: true items: + - name: "Troubleshoot function inlining on build time" + href: ../build-insights/tutorials/build-insights-function-view.md + - name: "Troubleshoot header file impact on build time" + href: ../build-insights/tutorials/build-insights-included-files-view.md + - name: "Build Insights tips and tricks" + href: ../build-insights/tutorials/build-insights-tips.md - name: "vcperf and Windows Performance Analyzer" href: ../build-insights/tutorials/vcperf-and-wpa.md - name: "Windows Performance Analyzer basics" @@ -123,6 +130,8 @@ href: ../build-insights/reference/sdk/cpp-event-data-types/front-end-pass.md - name: "Function" href: ../build-insights/reference/sdk/cpp-event-data-types/function.md + - name: "HeaderUnit" + href: ../build-insights/reference/sdk/cpp-event-data-types/header-unit.md - name: "ImpLibOutput" href: ../build-insights/reference/sdk/cpp-event-data-types/imp-lib-output.md - name: "Invocation" @@ -139,6 +148,8 @@ href: ../build-insights/reference/sdk/cpp-event-data-types/linker-pass.md - name: "LTCG" href: ../build-insights/reference/sdk/cpp-event-data-types/ltcg.md + - name: "Module" + href: ../build-insights/reference/sdk/cpp-event-data-types/module.md - name: "ObjOutput" href: ../build-insights/reference/sdk/cpp-event-data-types/obj-output.md - name: "OptICF" @@ -151,6 +162,8 @@ href: ../build-insights/reference/sdk/cpp-event-data-types/pass1.md - name: "Pass2" href: ../build-insights/reference/sdk/cpp-event-data-types/pass2.md + - name: "PrecompiledHeader" + href: ../build-insights/reference/sdk/cpp-event-data-types/precompiled-header.md - name: "PreLTCGOptRef" href: ../build-insights/reference/sdk/cpp-event-data-types/pre-ltcg-opt-ref.md - name: "RawEvent" @@ -169,6 +182,8 @@ href: ../build-insights/reference/sdk/cpp-event-data-types/top-down.md - name: "TraceInfo" href: ../build-insights/reference/sdk/cpp-event-data-types/trace-info.md + - name: "TranslationUnitType" + href: ../build-insights/reference/sdk/cpp-event-data-types/translation-unit-type.md - name: "WholeProgramAnalysis" href: ../build-insights/reference/sdk/cpp-event-data-types/whole-program-analysis.md - name: "Event data types (C)" @@ -209,6 +224,10 @@ href: ../build-insights/reference/sdk/c-event-data-types/trace-info-data-struct.md - name: "TRANSLATION_UNIT_PASS_CODE" href: ../build-insights/reference/sdk/c-event-data-types/translation-unit-pass-code-enum.md + - name: "TRANSLATION_UNIT_TYPE" + href: ../build-insights/reference/sdk/c-event-data-types/translation-unit-type.md + - name: "TRANSLATION_UNIT_TYPE_DATA" + href: ../build-insights/reference/sdk/c-event-data-types/translation-unit-type-data.md - name: "Other types" items: - name: "ANALYSIS_CALLBACKS" diff --git a/docs/build-insights/tutorials/build-insights-function-view.md b/docs/build-insights/tutorials/build-insights-function-view.md new file mode 100644 index 0000000000..598ea77cf2 --- /dev/null +++ b/docs/build-insights/tutorials/build-insights-function-view.md @@ -0,0 +1,151 @@ +--- +title: "Troubleshoot function inlining on build time" +description: "Tutorial for how to use Build Insights function view to troubleshoot the impact of function inlining on build time in your C++ projects." +ms.date: 5/30/2024 +helpviewer_keywords: ["C++ Build Insights", "inline function analysis", "build time analysis", "__forceinline analysis", "inlines analysis"] +--- +# Troubleshoot function inlining on build time + +Use Build Insights **Functions** view to troubleshoot the impact of function inlining on build time in your C++ projects. + +## Prerequisites + +- Visual Studio 2022 17.8 or greater. +- C++ Build insights is enabled by default if you install either the Desktop development with C++ workload or the Game development with C++ workload. + +:::image type="complex" source="./media/installer-desktop-cpp-build-insights.png" alt-text="Screenshot of the Visual Studio Installer with the Desktop development with C++ workload selected."::: +The list of installed components is shown. C++ Build Insights is highlighted and is selected which means it's installed. +:::image-end::: + +:::image type="complex" source="./media/installer-gamedev-cpp-build-insights.png" alt-text="Screenshot of the Visual Studio Installer with the Game development with C++ workload selected."::: +The list of installed components is shown. C++ Build Insights is highlighted and is selected which means it's installed. +:::image-end::: + +## Overview + +Build Insights, now integrated into Visual Studio, helps you optimize your build times--especially for large projects like AAA games. Build Insights provides analytics such as **Functions** view, which helps diagnose expensive code generation during build time. It displays the time it takes to generate code for each function, and shows the impact of [`__forceinline`](../../cpp/inline-functions-cpp.md#inline-__inline-and-__forceinline). + +The `__forceinline` directive tells the compiler to inline a function regardless of its size or complexity. Inlining a function can improve runtime performance by reducing the overhead of calling the function. The tradeoff is that it can increase the size of the binary and impact your build times. + +For optimized builds, the time spent generating code contributes significantly to the total build time. In general, C++ function optimization happens quickly. In exceptional cases, some functions can become large enough and complex enough to put pressure on the optimizer and noticeably slow down your builds. + +In this article, learn how to use the Build Insights **Functions** view to find inlining bottlenecks in your build. + +## Set build options + +To measure the results of `__forceinline`, use a **Release** build because debug builds don't inline `__forceinline` since debug builds use the [`/Ob0`](../../build/reference/ob-inline-function-expansion.md) compiler switch, which disables that optimization. Set the build for **Release** and **x64**: + +1. In the **Solution Configurations** dropdown, choose **Release**. +1. In the **Solution Platforms** dropdown, choose **x64**. + +:::image type="content" source="./media/build-options-release.png" alt-text="Screenshot of the Solution Configuration dropdown set to Release, and the Solution Platform dropdown set to x64."::: + +Set the optimization level to maximum optimizations: + +1. In the **Solution Explorer**, right-click the project name and select **Properties**. +1. In the project properties, navigate to **C/C++** > **Optimization**. +1. Set the **Optimization** dropdown to **Maximum Optimization (Favor Speed) ([`/O2`](../../build/reference/ob-inline-function-expansion.md))**. + + :::image type="content" source="./media/max-optimization-setting.png" alt-text="Screenshot of the project property pages dialog. The settings are open to Configuration Properties > C/C++ > Optimization. The Optimization dropdown is set to Maximum Optimization (Favor Speed) (/O2)."::: + +1. Click **OK** to close the dialog. + +## Run Build Insights + +On a project of your choosing, and using the **Release** build options set in the previous section, run Build Insights by choosing from the main menu **Build** > **Run Build Insights on Selection** > **Rebuild**. You can also right-click a project in the solution explorer and choose **Run Build Insights** > **Rebuild**. Choose **Rebuild** instead of **Build** to measure the build time for the entire project and not for just the few files may be dirty right now. + +:::image type="content" source="./media/build-insights-rebuild-project.png" alt-text="Screenshot of the main menu with Run Build Insights on Selection > Rebuild selected."::: + +When the build finishes, an Event Trace Log (ETL) file opens. It's saved in the folder pointed to by the Windows `TEMP` environment variable. The generated name is based on the collection time. + +## Function view + +In the window for the ETL file, choose the **Functions** tab. It shows the functions that were compiled and the time it took to generate the code for each function. If the amount of code generated for a function is negligible, it won't appear in the list to avoid degrading build event collection performance. + +:::image type="complex" source="./media/functions-view-before-fix.png" alt-text="Screenshot of the Build Insights Functions view file."::: +In the Function Name column, performPhysicsCalculations() is highlighted and marked with a fire icon. +:::image-end::: + +The **Time [sec, %]** column shows how long it took to compile each function in [wall clock responsibility time (WCTR)](https://devblogs.microsoft.com/cppblog/faster-cpp-builds-simplified-a-new-metric-for-time/#:~:text=Today%2C%20we%E2%80%99d%20like%20to%20teach%20you%20about%20a,your%20build%2C%20even%20in%20the%20presence%20of%20parallelism). This metric distributes the wall clock time among functions based on their use of parallel compiler threads. For example, if two different threads are compiling two different functions simultaneously within a one-second period, each function's WCTR is recorded as 0.5 seconds. This reflects each function's proportional share of the total compilation time, taking into account the resources each consumed during parallel execution. Thus, WCTR provides a better measure of the impact each function has on the overall build time in environments where multiple compilation activities occur simultaneously. + +The **Forceinline Size** column shows roughly how many instructions were generated for the function. Click the chevron before the function name to see the individual inlined functions that were expanded in that function how roughly how many instructions were generated for each. + +You can sort the list by clicking on the **Time** column to see which functions are taking the most time to compile. A 'fire' icon indicates that cost of generating that function is high and is worth investigating. Excessive use of `__forceinline` functions can significantly slow compilation. + +You can search for a specific function by using the **Filter Functions** box. If a function's code generation time is too small, it doesn't appear in the **Functions** View. + +## Improve build time by adjusting function inlining + +In this example, the `performPhysicsCalculations` function is taking the most time to compile. + +:::image type="complex" source="./media/functions-view-before-fix.png" alt-text="Screenshot of the Build Insights Functions view."::: +In the Function Name column, performPhysicsCalculations() is highlighted and marked with a fire icon. +:::image-end::: + +Investigating further, by selecting the chevron before that function, and then sorting the **Forceinline Size** column from highest to lowest, we see the biggest contributors to the problem. + +:::image type="complex" source="./media/functions-view-expanded.png" alt-text="Screenshot of the Build Insights Functions view with an expanded function."::: +performPhysicsCalculations() is expanded and shows a long list of functions that were inlined inside it. There are multiple instances of functions such as complexOperation(), recursiveHelper(), and sin() shown. The Forceinline Size column shows that complexOperation() is the largest inlined function at 315 instructions. recursiveHelper() has 119 instructions. Sin() has 75 instructions, but there are many more instances of it than the other functions. +:::image-end::: + +There are some larger inlined functions, such as `Vector2D::complexOperation()` and `Vector2D::recursiveHelper()` that are contributing to the problem. But there are many more instances (not all shown here) of `Vector2d::sin(float)`, `Vector2d::cos(float)`, `Vector2D::power(float,int)`, and `Vector2D::factorial(int)`. When you add those up, the total number of generated instructions quickly exceeds the few larger generated functions. + +Looking at those functions in the source code, we see that execution time is going to be spent inside loops. For example, here's the code for `factorial()`: + +```cpp +static __forceinline T factorial(int n) +{ + T result = 1; + for (int i = 1; i <= n; ++i) { + for (int j = 0; j < i; ++j) { + result *= (i - j) / (T)(j + 1); + } + } + return result; +} +``` + +Perhaps the overall cost of calling this function is insignificant compared to the cost of the function itself. Making a function inline is most beneficial when the time it takes to call the function (pushing arguments on the stack, jumping to the function, popping return arguments, and returning from the function) is roughly similar to the time it takes to execute the function, and when the function is called a lot. When that's not the case, there may be diminishing returns on making it inline. We can try removing the `__forceinline` directive from it to see if it helps the build time. The code for `power`, `sin()` and `cos()` is similar in that the code consists of a loop that will execute many times. We can try removing the `__forceinline` directive from those functions as well. + +We rerun Build Insights from the main menu by choosing **Build** > **Run Build Insights on Selection** > **Rebuild**. You can also right-click a project in the solution explorer and choose **Run Build Insights** > **Rebuild**. We choose **Rebuild** instead of **Build** to measure the build time for the entire project, as before, and not for just the few files may be dirty right now. + +The build time goes from 25.181 seconds to 13.376 seconds and the `performPhysicsCalculations` function doesn't show up anymore in the **Functions** view because it doesn't contribute enough to the build time to be counted. + +:::image type="complex" source="./media/functions-view-after-fix.png" alt-text="Screenshot of the 2D vector header file."::: +In the Function Name column, performPhysicsCalculations() is highlighted and marked with a fire icon. +:::image-end::: + +The Diagnostics Session time is the overall time it took do the build plus any overhead for gathering the Build Insights data. + +The next step would be to profile the application to see if the performance of the application is negatively impacted by the change. If it is, we can selectively add `__forceinline` back as needed. + +## Navigate to the source code + +Double-click, right-click, or press **Enter** while on a file in the **Functions** view to open the source code for that file. + +:::image type="content" source="./media/functions-view-goto-file.png" alt-text="Screenshot of a right-click on a file in the Functions view. The menu option Go To Source File is highlighted."::: + +## Tips + +- You can **File** > **Save As** the ETL file to a more permanent location to keep a record of the build time. You can then compare it to future builds to see if your changes are improving build time. +- If you inadvertently close the Build Insights window, reopen it by finding the `.etl` file in your temporary folder. The `TEMP` Windows environment variable provides the path of your temporary files folder. +- To dig into the Build Insights data with Windows Performance Analyzer (WPA), click the **Open in WPA** button in the bottom right of the ETL window. +- Drag columns to change the order of the columns. For instance, you may prefer moving the **Time** column to be the first column. You can hide columns by right-clicking on the column header and deselecting the columns you don't want to see. +- The **Functions** view provides a filter box to find a function that you're interested in. It does partial matches on the name you provide. +- If you forget how to interpret what the **Functions** view is trying to show you, hover over the tab to see a tooltip that describes the view. If you hover over the **Functions** tab, the tooltip says: "View that shows statistics for functions where the children nodes are force-inlined functions." + +## Troubleshooting + +- If the Build Insights window doesn't appear, do a rebuild instead of a build. The Build Insights window doesn't appear if nothing actually builds; which may be the case if no files changed since the last build. +- If the Functions view doesn't show any functions, you may not be building with the right optimization settings. Ensure that you're building Release with full optimizations, as described in [Set build options](#set-build-options). Also, if a function's code generation time is too small, it doesn't appear in the list. + +## See also + +[Build Insights tips and tricks](build-insights-tips.md)\ +[Inline functions (C++)](../../cpp/inline-functions-cpp.md)\ +[Faster C++ builds, simplified: a new metric for time](https://devblogs.microsoft.com/cppblog/faster-cpp-builds-simplified-a-new-metric-for-time)\ +[Build Insights in Visual Studio video - Pure Virtual C++ 2023](/events/pure-virtual-cpp-2023/build-insights-in-visual-studio)\ +[Troubleshoot header file impact on build time](build-insights-included-files-view.md)\ +[Functions View for Build Insights in Visual Studio 2022 17.8](https://devblogs.microsoft.com/cppblog/functions-view-for-build-insights-in-visual-studio-2022-17-8/)\ +[Tutorial: vcperf and Windows Performance Analyzer](vcperf-and-wpa.md)\ +[Improving code generation time with C++ Build Insights](https://devblogs.microsoft.com/cppblog/improving-code-generation-time-with-cpp-build-insights) diff --git a/docs/build-insights/tutorials/build-insights-included-files-view.md b/docs/build-insights/tutorials/build-insights-included-files-view.md new file mode 100644 index 0000000000..3563f96d71 --- /dev/null +++ b/docs/build-insights/tutorials/build-insights-included-files-view.md @@ -0,0 +1,188 @@ +--- +title: "Troubleshoot header file impact on build time" +description: "Tutorial on how to use Build Insights Includes Files and Includes Tree views to troubleshoot the impact of #include files on build time." +ms.date: 5/30/2024 +helpviewer_keywords: ["C++ Build Insights", "header file build time", "included files view", "include tree view", "#include analysis", "build time analysis"] +--- +# Troubleshoot header file impact on build time + +Use Build Insights **Included Files** and **Include Tree** views to troubleshoot the impact of `#include` files on C and C++ build times. + +## Prerequisites + +- Visual Studio 2022 17.8 or greater. +- C++ Build Insights is enabled by default if you install either the Desktop development with C++ workload using the Visual Studio installer: + +:::image type="complex" source="./media/installer-desktop-cpp-build-insights.png" alt-text="Screenshot of the Visual Studio Installer with the Desktop development with C++ workload selected."::: +The list of installed components is shown. C++ Build Insights is highlighted and is selected which means it's installed. +:::image-end::: + +Or the Game development with C++ workload: + +:::image type="complex" source="./media/installer-gamedev-cpp-build-insights.png" alt-text="Screenshot of the Visual Studio Installer with the Game development with C++ workload selected."::: +The list of installed components is shown. C++ Build Insights is highlighted and is selected which means it's installed. +:::image-end::: + +## Overview + +Build Insights, now integrated into Visual Studio, helps you optimize your build times--especially for large projects like triple-A games. When a large header file is parsed, and especially when it's repeatedly parsed, there's an impact on build time. + +Build Insights provides analytics in the **Included Files** view, which helps diagnose the impact of parsing `#include` files in your project. It displays the time it takes to parse each header file and a view of the relationships between header files. + +In this article, learn how to use the Build Insights **Included Files** and **Include Tree** views to identify the most expensive header files to parse and how to optimize build time by creating a precompiled header file. + +## Set build options + +Before gathering Build Insights data, set the build options for the type of build you want to measure. For example, if you're concerned about your x64 debug build time, set the build for **Debug** and **x64**: + +- In the **Solution Configurations** dropdown, choose **Debug**. +- In the **Solution Platforms** dropdown, choose **x64**. + + :::image type="complex" source="./media/build-options-debug.png" alt-text="Screenshot of the Solution Configuration dropdowns."::: + The Solution Configuration dropdown is shown. It has options for Debug, Release, and Configuration manager. The Solution Platform dropdown is set to x64. + :::image-end::: + +## Run Build Insights + +On a project of your choosing, and using the **Debug** build options set in the previous section, run Build Insights by choosing from the main menu **Build** > **Run Build Insights on \** > **Rebuild**. You can also right-click a project in the solution explorer and choose **Run Build Insights** > **Rebuild**. Choose **Rebuild** instead of **Build** to measure the build time for the entire project and not for just the few files may be dirty right now. + +:::image type="content" source="./media/build-insights-rebuild-project.png" alt-text="Screenshot of the main menu with Run Build Insights on Selection > Rebuild selected."::: + +When the build finishes, an Event Trace Log (ETL) file opens. It's saved in the folder pointed to by the Windows `TEMP` environment variable. The generated name is based on the collection time. + +## Included Files view + +The trace file shows the build time--which for this example was 16.404 seconds. The **Diagnostics Session** is the overall time taken to run the Build Insights session. Choose the **Included Files** tab. + +This view shows the time spent processing `#include` files. + +:::image type="complex" source="./media/included-files-before-fix.png" alt-text="Screenshot of the included files view."::: +In the file path column, several files with a fire icon are highlighted because they take over 10% of the build time to parse. winrtHeaders.h is the biggest one at 8.581 seconds or 52.3% of the 16.404-second build time. +:::image-end::: + +In the **File Path** column, some files have a fire icon next to them to indicate that they take up 10% or more of the build time. + +The **Time [sec, %]** column shows how long it took to compile each function in [wall clock responsibility time (WCTR)](https://devblogs.microsoft.com/cppblog/faster-cpp-builds-simplified-a-new-metric-for-time/#:~:text=Today%2C%20we%E2%80%99d%20like%20to%20teach%20you%20about%20a,your%20build%2C%20even%20in%20the%20presence%20of%20parallelism). This metric distributes the wall clock time it takes to parse files based on their use of parallel threads. For example, if two different threads are parsing two different files simultaneously within a one-second period, each file's WCTR is recorded as 0.5 seconds. This reflects each file's proportional share of the total compilation time, taking into account the resources each consumed during parallel execution. Thus, WCTR provides a better measure of the impact each file has on the overall build time in environments where multiple compilation activities occur simultaneously. + +The **Parse Count** column shows how many time the header file was parsed. + +The first header file highlighted in this list is `winrtHeaders.h` It takes 8.581 seconds of the overall 16.404-second build time, or 52.3% of the build time. The next most expensive is `Windows.UI.Xaml.Interop.h`, and then `Windows.Xaml.h`. + +To see which file includes `winrtHeaders.h`, click the chevron next to it. The **Parse Count** column can be helpful by pointing out how many times a header file is included by other files. Perhaps a header file is included multiple times, which could be a sign that it's a good candidate for a precompiled header file or refactoring. + +The **Translation Unit** column shows which file was being processed when the included file was processed. In this example, `winrtHeaders.h` was included while `Grapher.cpp` was compiled: + +:::image type="complex" source="./media/included-files-translation-unit.png" alt-text="Screenshot of the Included Files view."::: +An example ETL file showing the includes files for a sample project. In the file path column, winrtHeaders.h is selected and expanded. It takes 8.219 seconds to build which is 50.1% of the build time. Its child node is Grapher.cpp, which is also listed as the translation unit." +:::image-end::: + +The translation unit column can help disambiguate which file was being compiled in cases where a header file is included many times and you want to find out where that happens the most. + +We know that `winrtHeaders.h` is expensive to parse, but we can learn more. + +## Include Tree view + +In this view, the children nodes are the files included by the parent node. This can help you understand the relationships between header files and identify opportunities to reduce the number of times a header file is parsed. + +Select the **Include Tree** tab in the ETL file to see the Include Tree view: + +:::image type="complex" source="./media/include-tree-view.png" alt-text="Screenshot of the Include Tree view."::: +Shows the include tree for a project. In the file path column, each file that includes other files is listed, along with how many files it includes and the time to parse it. +:::image-end::: + +In this view, the **File Path** column shows each file that includes other files. The **Include Count** lists how many files this header file includes. The time to parse this file is listed, and when expanded, lists the time to parse each individual header file that this header file includes. + +Earlier, we saw that parsing `winrtHeaders.h` is time consuming. In the **Filter Files** text box, if we enter `winrtHeaders.h`, we can filter the view to only the entries that contain `winrtHeaders.h` in the name. Clicking the chevron next to `winrtHeaders.h` shows which files it includes: + +:::image type="complex" source="./media/include-tree-view-expanded.png" alt-text="Screenshot of the expanded Include Tree view."::: +The file path column lists each file that includes other files, along with how many files it includes and the time it took to parse it. winrtHeaders.h is selected and expanded to show the files it includes. Windows.UI.Xaml.Interop.h is one of those files and is expanded to show Windows.UI.Xaml.Interop.h that is expanded to show the header files it includes. +:::image-end::: + +We see that `winrtHeaders.h` includes `Windows.UI.Xaml.Interop.h`. Remember from the **Included Files** view that this was also time consuming to parse. Click the chevron next to `Windows.UI.Xaml.Interop.h` to see that it includes `Windows.UI.Xaml.h`, which includes 21 other header files, two of which are also on the hot list. + +Having identified some of the most expensive header files to parse, and seeing that `winrtHeaders.h` is responsible for bringing them in, suggests that we can use a precompiled header to make including `winrtHeaders.h` faster. + +## Improve build time with precompiled headers + +Because we know from the **Included Files** view that `winrtHeaders.h` is time consuming to parse, and because we know from the **Include Tree** view that `winrtHeaders.h` includes several other header files that are time consuming to parse, we build a [Precompiled header file](../../build/creating-precompiled-header-files.md) (PCH) to speed that up by only parsing them once into a PCH. + +We add a `pch.h` to include `winrtHeaders.h`, which would look like this: + +```cpp +#ifndef CALC_PCH +#define CALC_PCH + +#include + +#endif // CALC_PCH +``` + +PCH files must be compiled before they can be used, so we add a file to the project, arbitrarily named `pch.cpp`, that includes `pch.h`. It contains one line: + +```cpp +#include "pch.h" +``` + +Then we set our project to use the PCH. That's done in project properties via **C/C++** > **Precompiled Headers** and setting **Precompiled Header** to **Use (/Yu)** and **Precompiled Header File** to **pch.h**. + +:::image type="complex" source="./media/precompiled-header-settings.png" alt-text="Screenshot of the project properties dialog with the Precompiled Headers settings open."::: +Precompiled Header is set to: Use (/Yu). The Precompiled Header File is set to pch.h. +:::image-end::: + +To use the PCH, we include it as the first line in the source files that use `winrtHeaders.h`. It must come before any other include files. Or, for simplicity, we could modify the project properties to include `pch.h` at the beginning of every file in the solution by setting the project property: **C/C++** > **Advanced** > **Forced Include File** to `pch.h`: + +:::image type="complex" source="./media/precompiled-header-settings-force-include.png" alt-text="Screenshot of the project properties dialog with the Advanced settings open."::: +Forced Include File is set to pch.h. +:::image-end::: + +Since the PCH includes `winrtHeaders.h`, we could remove `winrtHeaders.h` from all the files that currently include it. It's not strictly necessary because the compiler realizes that `winrtHeaders.h` is already included and doesn't parse it again. Some developers prefer to keep the `#include` in the source file for clarity, or in case the PCH is likely to be refactored and may not include that header file anymore. + +## Test the changes + +We first clean the project to make sure we're comparing building the same files as before. To clean just one project, right-click the project in the **Solution Explorer** and choose **Project only** > **Clean only \**. + +Because this project now uses a precompiled header (PCH), we don't want to measure the time spent building the PCH because that only happens once. We do this by loading the `pch.cpp` file and choosing **Ctrl+F7** to build just that file. We could also compile this file by right-clicking `pch.cpp` in the Solution Explorer and choosing `Compile`. + +Now we rerun Build Insights in the **Solution Explorer** by right-clicking the project and choosing **Project Only** > **Run Build Insights on Build**. You can also right-click a project in the solution explorer and choose **Run Build Insights** > **Build**. We don't want **Rebuild** this time because that will rebuild the PCH, which we don't want to measure. We cleaned the project earlier, which means that a normal build compiles all the project files we want to measure. + +When the ETL files appear, we see that build time went from 16.404 seconds to 6.615 seconds. Put `winrtHeaders.h` into the filter box and nothing appears. This is because the time spent parsing it is now negligible since it's being pulled in by the precompiled header. + +:::image type="content" source="./media/included-files-after-fix.png" alt-text="Screenshot of the Include Tree pane in the trace file. winrtHeaders is no longer listed."::: + +This example uses precompiled headers because they're a common solution before C++20. However, starting with C++20, there are other, faster, less brittle, ways to include header files--such as header units and modules. For more information, see [Compare header units, modules, and precompiled headers](../../build/compare-inclusion-methods.md). + +## Navigate between views + +There are some navigation features for both the **Included Files** and **Include Tree** views: + +- Double-click a file (or press **Enter**) in either the **Included Files** or **Include Tree** to open the source code for that file. +- Right-click on a header file to find that file in the other view. For example, in the **Included File**s view, right-click on `winrtHeaders.h` and choose **Find in Include Tree** to see it in the **Include Tree** view. + +:::image type="content" source="./media/included-files-show-in-include-tree.png" alt-text="Screenshot of a right-click on a file in the Included Files view. The menu option Show in Include Tree View is highlighted."::: + +Or, you can right-click a file in the **Include Tree** view to jump to it in the **Included Files** view. + +## Tips + +- You can **File** > **Save As** the ETL file to a more permanent location to keep a record of the build time. You can then compare it to future builds to see if your changes are improving build time. +- If you inadvertently close the Build Insights window, reopen it by finding the `.etl` file in your temporary folder. The `TEMP` Windows environment variable provides the path of your temporary files folder. +- To dig into the Build Insights data with Windows Performance Analyzer (WPA), click the **Open in WPA** button in the bottom right of the ETL window. +- Drag columns to change the order of the columns. For instance, you may prefer moving the **Time** column to be the first column. You can hide columns by right-clicking on the column header and deselecting the columns you don't want to see. +- The **Included Files** and **Include Tree** views provide a filter box to find a header file that you're interested in. It does partial matches on the name you provide. +- Sometimes the parse time reported for a header file is different depending on which file includes it. This can be due to the interplay of different `#define`s that affect which parts of the header are expanded, file caching, and other system factors. +- If you forget what the **Included Files** or **Include Tree** view is trying to show you, hover over the tab to see a tooltip that describes the view. For example, if you hover over the **Include Tree** tab, the tooltip says: "View that shows include statistics for every file where the children nodes are the files included by the parent node." +- You may see cases (like `Windows.h`) where the aggregated duration of all the times for a header file is longer than the duration of the entire build. What's happening is that headers are being parsed on multiple threads at the same time. If two threads simultaneously spend one second parsing a header file, that's 2 seconds of build time even though only one second of wall clock time has gone by. For more information, see [wall clock responsibility time (WCTR)](https://devblogs.microsoft.com/cppblog/faster-cpp-builds-simplified-a-new-metric-for-time/#:~:text=Today%2C%20we%E2%80%99d%20like%20to%20teach%20you%20about%20a,your%20build%2C%20even%20in%20the%20presence%20of%20parallelism). + +## Troubleshooting + +- If the Build Insights window doesn't appear, do a rebuild instead of a build. The Build Insights window doesn't appear if nothing actually builds; which may be the case if no files changed since the last build. +- If a header file you're interested in doesn't appear in the **Included Files** or **Include Tree** views, it either didn't build or its build time isn't significant enough to be listed. + +## See also + +[Build Insights tips and tricks](build-insights-tips.md)\ +[Compare header units, modules, and precompiled headers](../../build/compare-inclusion-methods.md)\ +[Build Insights in Visual Studio video - Pure Virtual C++ 2023](/events/pure-virtual-cpp-2023/build-insights-in-visual-studio)\ +[Faster C++ builds, simplified: a new metric for time](https://devblogs.microsoft.com/cppblog/faster-cpp-builds-simplified-a-new-metric-for-time)\ +[Troubleshoot function inlining on build time](build-insights-function-view.md)\ +[vcperf and Windows Performance Analyzer](vcperf-and-wpa.md) \ No newline at end of file diff --git a/docs/build-insights/tutorials/build-insights-tips.md b/docs/build-insights/tutorials/build-insights-tips.md new file mode 100644 index 0000000000..d071aaddda --- /dev/null +++ b/docs/build-insights/tutorials/build-insights-tips.md @@ -0,0 +1,79 @@ +--- +title: "Build Insights tips and tricks" +description: "Learn time-saving tips for using Build Insights." +ms.date: 1/8/2025 +author: tylermsft +ms.author: twhitney +ms.topic: article +helpviewer_keywords: ["C++ Build Insights tips and tricks"] +--- +# Build Insights tips and tricks + +Learn time-saving tips for using Build Insights. + +## Run Build Insights on selected files + +This feature requires Visual Studio 2022 17.12 or later. + +If you're working on a specific file or files, and want to see how they impact your build time, you can run Build Insights on just those files. This feature is useful when you want to focus on a subset of files in your project. + +To try it, in **Solution Explorer** select the files in your project you want to profile, right-click, and choose **Run Build Insights on Selected Files**: + + :::image type="content" source="./media/build-insights-run-on-selected-files.png" alt-text="A screenshot of files in the Solution Explorer. The context menu is open and the option to Run Build Insights on Selected Files is highlighted."::: + +## Filter Build Insights results + +This feature requires Visual Studio 2022 17.12 or later. + +If you have a large solution with many projects, you can filter the Build Insights results to see files only the projects you're interested in. This feature is useful when you want to focus on a subset of projects in your solution. + +To try it, click the filter button on the filter column header and select the projects you want to see results for: + + :::image type="complex" source="./media/build-insights-filter-by-project.png" alt-text="A screenshot of the Build Insights window with the Included Files tab open."::: + The filter button is selected and a list of projects appears. Checkboxes next to two projects are checked. + :::image-end::: + +You can also use file wildcards to filter results. The search is case-insensitive and you should use forward slashes (`/`) as path separators: + + :::image type="content" source="./media/build-insights-glob-filter.png" alt-text="A screenshot of the build insights filter dialog. There's a files to include text box and a files to exclude text box."::: + +This allows you to exclude files from a specific folder or only include files from a specific folder. For example, if your source is located at `C:\src\`, you could include files only from the renderer directory and its subdirectories by putting `C:/src/dev/renderer/**` into the **files to include** text box. Use forward slashes (`/`) as path separators. + +Here are some other examples: + +- All files in the renderer directory: `C:/src/dev/renderer/*` +- All files in the `C:/src/dev/renderer/` directory *and all its subdirectories*: `C:/src/dev/renderer/**` +- All header files in the `C:/src/dev/renderer/` directory *and all its subdirectories*: `C:/src/dev/renderer/**/*.h` + +For more examples, see the [online glob pattern tester](https://globster.xyz/). + +The filter you enter into either text box persists per solution. Filtering by wildcards isn't supported for CMAKE projects. + +## Save Build Insights reports to a designated folder + +This feature requires Visual Studio 2022 17.12 or later. + +Now you can designate a folder to automatically save Build Insight reports to so you can easily access them. + +To set the designated folder, go to **Tools** > **Options** > **C++ Build Insights** > **Trace Collection**. Set a path in the **Store Build Insights reports in this directory** textbox: + + :::image type="complex" source="./media/build-insights-reports-directory.png" alt-text="A screenshot of the options window."::: + In the left pane, Build Insights > Trace Collection is selected. In the collection settings, the checkbox for Store Build Insights reports in this directory is selected, and the directory text box contains the path c:\users\contoso\workspace as an example. + :::image-end::: + +Reports are automatically saved to this folder when you run Build Insights. If a path isn't set, the `TEMP` folder is used. + +## Get help about the Build Insight window + +This feature requires Visual Studio 2022 17.12 or later. + +To see a short description for the tabs in the Build Insights window, along with a link to the documentation for a detailed explanation, click the question mark icon in the Build Insights window: + + :::image type="content" source="./media/build-insights-view-explanations.png" alt-text="A screenshot of the Build Insights window with the view explanations button (a question mark in a circle) highlighted."::: + +## See also + +[Build Insights in Visual Studio video - Pure Virtual C++ 2023](/events/pure-virtual-cpp-2023/build-insights-in-visual-studio)\ +[Improving code generation time with C++ Build Insights](https://devblogs.microsoft.com/cppblog/improving-code-generation-time-with-cpp-build-insights)\ +[Troubleshoot header file impact on build time](build-insights-included-files-view.md)\ +[Tutorial: Troubleshoot function inlining on build time](build-insights-function-view.md) diff --git a/docs/build-insights/tutorials/media/build-insights-filter-by-project.png b/docs/build-insights/tutorials/media/build-insights-filter-by-project.png new file mode 100644 index 0000000000..4a2f902081 Binary files /dev/null and b/docs/build-insights/tutorials/media/build-insights-filter-by-project.png differ diff --git a/docs/build-insights/tutorials/media/build-insights-glob-filter.png b/docs/build-insights/tutorials/media/build-insights-glob-filter.png new file mode 100644 index 0000000000..98395c240f Binary files /dev/null and b/docs/build-insights/tutorials/media/build-insights-glob-filter.png differ diff --git a/docs/build-insights/tutorials/media/build-insights-rebuild-project.png b/docs/build-insights/tutorials/media/build-insights-rebuild-project.png new file mode 100644 index 0000000000..63ceed7705 Binary files /dev/null and b/docs/build-insights/tutorials/media/build-insights-rebuild-project.png differ diff --git a/docs/build-insights/tutorials/media/build-insights-reports-directory.png b/docs/build-insights/tutorials/media/build-insights-reports-directory.png new file mode 100644 index 0000000000..e9c751814f Binary files /dev/null and b/docs/build-insights/tutorials/media/build-insights-reports-directory.png differ diff --git a/docs/build-insights/tutorials/media/build-insights-run-on-selected-files.png b/docs/build-insights/tutorials/media/build-insights-run-on-selected-files.png new file mode 100644 index 0000000000..1a5c0f8556 Binary files /dev/null and b/docs/build-insights/tutorials/media/build-insights-run-on-selected-files.png differ diff --git a/docs/build-insights/tutorials/media/build-insights-view-explanations.png b/docs/build-insights/tutorials/media/build-insights-view-explanations.png new file mode 100644 index 0000000000..3b33e677bc Binary files /dev/null and b/docs/build-insights/tutorials/media/build-insights-view-explanations.png differ diff --git a/docs/build-insights/tutorials/media/build-options-debug.png b/docs/build-insights/tutorials/media/build-options-debug.png new file mode 100644 index 0000000000..156abb7646 Binary files /dev/null and b/docs/build-insights/tutorials/media/build-options-debug.png differ diff --git a/docs/build-insights/tutorials/media/build-options-release.png b/docs/build-insights/tutorials/media/build-options-release.png new file mode 100644 index 0000000000..2fe4589daf Binary files /dev/null and b/docs/build-insights/tutorials/media/build-options-release.png differ diff --git a/docs/build-insights/tutorials/media/functions-view-after-fix.png b/docs/build-insights/tutorials/media/functions-view-after-fix.png new file mode 100644 index 0000000000..9df70ef0b9 Binary files /dev/null and b/docs/build-insights/tutorials/media/functions-view-after-fix.png differ diff --git a/docs/build-insights/tutorials/media/functions-view-before-fix.png b/docs/build-insights/tutorials/media/functions-view-before-fix.png new file mode 100644 index 0000000000..109d81e391 Binary files /dev/null and b/docs/build-insights/tutorials/media/functions-view-before-fix.png differ diff --git a/docs/build-insights/tutorials/media/functions-view-expanded.png b/docs/build-insights/tutorials/media/functions-view-expanded.png new file mode 100644 index 0000000000..9f0483a4cf Binary files /dev/null and b/docs/build-insights/tutorials/media/functions-view-expanded.png differ diff --git a/docs/build-insights/tutorials/media/functions-view-goto-file.png b/docs/build-insights/tutorials/media/functions-view-goto-file.png new file mode 100644 index 0000000000..378c335781 Binary files /dev/null and b/docs/build-insights/tutorials/media/functions-view-goto-file.png differ diff --git a/docs/build-insights/tutorials/media/include-tree-view-expanded.png b/docs/build-insights/tutorials/media/include-tree-view-expanded.png new file mode 100644 index 0000000000..d011bb41ee Binary files /dev/null and b/docs/build-insights/tutorials/media/include-tree-view-expanded.png differ diff --git a/docs/build-insights/tutorials/media/include-tree-view.png b/docs/build-insights/tutorials/media/include-tree-view.png new file mode 100644 index 0000000000..629ad3f125 Binary files /dev/null and b/docs/build-insights/tutorials/media/include-tree-view.png differ diff --git a/docs/build-insights/tutorials/media/included-files-after-fix.png b/docs/build-insights/tutorials/media/included-files-after-fix.png new file mode 100644 index 0000000000..42691ef4b6 Binary files /dev/null and b/docs/build-insights/tutorials/media/included-files-after-fix.png differ diff --git a/docs/build-insights/tutorials/media/included-files-before-fix.png b/docs/build-insights/tutorials/media/included-files-before-fix.png new file mode 100644 index 0000000000..e4eee66cf0 Binary files /dev/null and b/docs/build-insights/tutorials/media/included-files-before-fix.png differ diff --git a/docs/build-insights/tutorials/media/included-files-show-in-include-tree.png b/docs/build-insights/tutorials/media/included-files-show-in-include-tree.png new file mode 100644 index 0000000000..75df957eb5 Binary files /dev/null and b/docs/build-insights/tutorials/media/included-files-show-in-include-tree.png differ diff --git a/docs/build-insights/tutorials/media/included-files-translation-unit.png b/docs/build-insights/tutorials/media/included-files-translation-unit.png new file mode 100644 index 0000000000..65ad65bcaa Binary files /dev/null and b/docs/build-insights/tutorials/media/included-files-translation-unit.png differ diff --git a/docs/build-insights/tutorials/media/installer-desktop-cpp-build-insights.png b/docs/build-insights/tutorials/media/installer-desktop-cpp-build-insights.png new file mode 100644 index 0000000000..152ce06514 Binary files /dev/null and b/docs/build-insights/tutorials/media/installer-desktop-cpp-build-insights.png differ diff --git a/docs/build-insights/tutorials/media/installer-gamedev-cpp-build-insights.png b/docs/build-insights/tutorials/media/installer-gamedev-cpp-build-insights.png new file mode 100644 index 0000000000..3eaa8c2df1 Binary files /dev/null and b/docs/build-insights/tutorials/media/installer-gamedev-cpp-build-insights.png differ diff --git a/docs/build-insights/tutorials/media/max-optimization-setting.png b/docs/build-insights/tutorials/media/max-optimization-setting.png new file mode 100644 index 0000000000..78510f0af3 Binary files /dev/null and b/docs/build-insights/tutorials/media/max-optimization-setting.png differ diff --git a/docs/build-insights/tutorials/media/precompiled-header-settings-force-include.png b/docs/build-insights/tutorials/media/precompiled-header-settings-force-include.png new file mode 100644 index 0000000000..f53b2faf6a Binary files /dev/null and b/docs/build-insights/tutorials/media/precompiled-header-settings-force-include.png differ diff --git a/docs/build-insights/tutorials/media/precompiled-header-settings.png b/docs/build-insights/tutorials/media/precompiled-header-settings.png new file mode 100644 index 0000000000..4198430bce Binary files /dev/null and b/docs/build-insights/tutorials/media/precompiled-header-settings.png differ diff --git a/docs/build-insights/tutorials/vcperf-and-wpa.md b/docs/build-insights/tutorials/vcperf-and-wpa.md index 84b4268b16..e4bf41a1e1 100644 --- a/docs/build-insights/tutorials/vcperf-and-wpa.md +++ b/docs/build-insights/tutorials/vcperf-and-wpa.md @@ -8,18 +8,18 @@ helpviewer_keywords: ["C++ Build Insights", "throughput analysis", "build time a ::: moniker range="<=msvc-150" -The C++ Build Insights tools are available in Visual Studio 2019. To see the documentation for this version, set the Visual Studio **Version** selector control for this article to Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights tools are available in Visual Studio 2019 and later. To see the documentation for this version, set the Visual Studio **Version** selector control for this article to Visual Studio 2019 or later. It's found at the top of the table of contents on this page. ::: moniker-end -::: moniker range="msvc-160" +::: moniker range=">=msvc-160" -In this tutorial, you'll learn how to use *vcperf.exe* to collect a trace of your C++ build. You'll also learn how to view this trace in Windows Performance Analyzer. +In this tutorial, you'll learn how to use *`vcperf.exe`* to collect a trace of your C++ build. You'll also learn how to view this trace in Windows Performance Analyzer. ## Step 1: Install and configure Windows Performance Analyzer WPA is a trace viewer available in the Windows Assessment and Deployment Kit (ADK). It's a separate utility that's not part of the components you can install with the Visual Studio installer. -A version of WPA that supports C++ Build Insights is currently only available in the Windows ADK Insider Preview. To access this preview, you must sign up for the [Windows Insider program](https://insider.windows.com). You don't need to install the Windows 10 Insider Preview operating system to obtain the Windows ADK preview. You only need to register your Microsoft account with the Windows Insider Program. +A version of WPA that supports C++ Build Insights is only available in versions of the Windows ADK numbered 10.1.19041.0 or later. ### To download and install WPA @@ -31,21 +31,22 @@ NOTE: Windows 8 or above is required for installing the Windows Performance Anal 1. When prompted for the features that you want to install, select the **Windows Performance Toolkit**. You may select other features if you wish, but they're not required to install WPA. - ![The Windows Performance Analyzer installer's feature selection screen](media/wpa-installation.png) + ![The Windows Performance Analyzer installer's feature selection screen.](media/wpa-installation.png) ### To configure WPA Viewing C++ Build Insights traces in WPA requires a special add-in. Follow these steps to install it: 1. Obtain the add-in by downloading one of the components below. You don't need to get both. Choose the one that you find most convenient. - 1. [Visual Studio 2019 version 16.6 and above](https://visualstudio.microsoft.com/downloads/), or, - 1. [C++ Build Insights NuGet package](https://www.nuget.org/packages/Microsoft.Cpp.BuildInsights/). + - Visual Studio 2019 version 16.6 and above. For the latest version, see [Visual Studio Downloads](https://visualstudio.microsoft.com/downloads/). + - [C++ Build Insights NuGet package](https://www.nuget.org/packages/Microsoft.Cpp.BuildInsights/). 1. Copy the `perf_msvcbuildinsights.dll` file into your WPA installation directory. - 1. In Visual Studio 2019 version 16.6 and above, this file is located here: `C:\Program Files (x86)\Microsoft Visual Studio\2019\{Edition}\VC\Tools\MSVC\{Version}\bin\Host{Architecture}\{Architecture}`. + 1. In Visual Studio 2019 version 16.6 and above, this file is located here: `C:\Program Files (x86)\Microsoft Visual Studio\{Year}\{Edition}\VC\Tools\MSVC\{Version}\bin\Host{Architecture}\{Architecture}`. 1. In the C++ Build Insights NuGet package, this file is located here: `wpa\{Architecture}`. 1. In the paths above, replace the variables surrounded by curly brackets as follows: - 1. `{Edition}` is your Visual Studio 2019 edition such as Community, Professional, or Enterprise. + 1. `{Year}` is your Visual Studio product year, such as 2019 or 2022. + 1. `{Edition}` is your Visual Studio edition such as Community, Professional, or Enterprise. 1. `{Version}` is your MSVC version. Choose the highest one available. 1. `{Architecture}`: choose `x64` if you have a 64-bit version of Windows. Otherwise, choose `x86`. 1. The WPA installation directory is typically: `C:\Program Files (x86)\Windows Kits\10\Windows Performance Toolkit`. @@ -56,7 +57,7 @@ Viewing C++ Build Insights traces in WPA requires a special add-in. Follow these To view C++ Build Insights data, first collect it into a trace file by following these steps: -1. Open an **x64** or **x86 Native Tools Command Prompt for VS 2019** in administrator mode. (Right-click the Start menu item and choose **More** > **Run as administrator**.) +1. Open an **x64** or **x86 Native Tools Command Prompt for VS** in administrator mode. (Right-click the Start menu item and choose **More** > **Run as administrator**.) 1. Choose **x64** if you have a 64-bit version of Windows. Otherwise, choose **x86**. 1. In the command prompt window, enter this command: @@ -75,7 +76,7 @@ To view C++ Build Insights data, first collect it into a trace file by following Here's what a typical *vcperf.exe* command sequence looks like in a developer command prompt window: -![A simple vcperf.exe usage scenario](media/vcperf-simple-usage.png) +![Screenshot of a command window showing vcperf.exe commands and results.](media/vcperf-simple-usage.png) ### Important notes about vcperf.exe @@ -104,7 +105,7 @@ Launch WPA and open the trace you just collected. WPA should recognize it as a C If you can't see these views, double-check that WPA is configured correctly, as described in [Step 1](#configuration-steps). You can view your build data by dragging the views into the empty Analysis window on the right, as shown here: -![Viewing a C++ Build Insights trace in Windows Performance Analyzer](media/wpa-viewing-trace.gif) +![View of a C++ Build Insights trace in Windows Performance Analyzer.](media/wpa-viewing-trace.gif) Other views are available in the Graph Explorer panel. Drag them into the Analysis window when you're interested in the information they contain. A useful one is the CPU (Sampled) view, which shows CPU utilization throughout your build. diff --git a/docs/build-insights/tutorials/wpa-basics.md b/docs/build-insights/tutorials/wpa-basics.md index 7c4c748f28..9ac76d830c 100644 --- a/docs/build-insights/tutorials/wpa-basics.md +++ b/docs/build-insights/tutorials/wpa-basics.md @@ -8,10 +8,10 @@ helpviewer_keywords: ["C++ Build Insights", "throughput analysis", "build time a ::: moniker range="<=msvc-150" -The C++ Build Insights tools are available in Visual Studio 2019. To see the documentation for this version, set the Visual Studio **Version** selector control for this article to Visual Studio 2019. It's found at the top of the table of contents on this page. +The C++ Build Insights tools are available in Visual Studio 2019 and later. To see the documentation for this version, set the Visual Studio **Version** selector control for this article to Visual Studio 2019 or later. It's found at the top of the table of contents on this page. ::: moniker-end -::: moniker range="msvc-160" +::: moniker range=">=msvc-160" Using C++ Build Insights effectively requires some knowledge of Windows Performance Analyzer (WPA). This article helps you become familiar with common WPA operations. For more information on how to use WPA, see the [Windows Performance Analyzer](/windows-hardware/test/wpt/windows-performance-analyzer) documentation. diff --git a/docs/build/adding-references-in-visual-cpp-projects.md b/docs/build/adding-references-in-visual-cpp-projects.md index 9d03daa364..17676d6d6b 100644 --- a/docs/build/adding-references-in-visual-cpp-projects.md +++ b/docs/build/adding-references-in-visual-cpp-projects.md @@ -4,7 +4,6 @@ title: "Consuming libraries and components in C++ projects" ms.date: 12/18/2020 f1_keywords: ["VC.Project.References"] helpviewer_keywords: ["Add References Dialog Box (C++)", ".NET Framework (C++), Add References Dialog Box"] -ms.assetid: 12b8f571-0f21-40b3-9404-5318a57e9cb5 --- # Consuming libraries and components @@ -12,19 +11,23 @@ C++ projects often need to call functions or access data in a binary file such a ## Consuming libraries downloaded via vcpkg -To consume a library that you have downloaded by using the **vcpkg** package manager, you can ignore the instructions below. See [vcpkg.io](https://vcpkg.io/) for more information. +To consume a library that you have downloaded by using the **vcpkg** package manager, you can ignore the instructions below. For more information, see: +- [vcpkg in CMake projects](/vcpkg/users/buildsystems/cmake-integration) +- [Install and use packages with CMake in Visual Studio](/vcpkg/get_started/get-started-vs) +- [vcpkg in MSBuild projects](/vcpkg/users/buildsystems/msbuild-integration) +- [Tutorial: Install and use packages with MSBuild in Visual Studio](/vcpkg/get_started/get-started-msbuild) ## Consuming static libraries If your static library project gets built in the same solution: -1. #include the header file(s) for the static library using quotation marks. In a typical solution, the path starts with `../`. IntelliSense will help you find it. +1. `#include` the header file(s) for the static library using quotation marks. In a typical solution, the path starts with `../`. IntelliSense will help you find it. 2. Add a reference to the static library project. Right-click on **References** under the application project node in **Solution Explorer** and choose **Add Reference**. If the static library isn't part of the solution: 1. Right-click on the application project node in **Solution Explorer** and then choose **Properties**. -2. In the **VC++ Directories** property page, add the path to the directory that contains the LIB file to **Library Paths**. Then, add the path to the library header file(s) to **Include Directories**. +2. In the **VC++ Directories** property page, add the path to the directory that contains the LIB file to **Library Directories**. Then, add the path to the library header file(s) to **Include Directories**. 3. In the **Linker > Input** property page, add the name of the LIB file to **Additional Dependencies**. ## Dynamic link libraries @@ -33,7 +36,7 @@ If the DLL gets built as part of the same solution as the application, follow th If the DLL isn't part of the application solution, you need: the DLL file, the header(s) with prototypes for the exported functions and classes, and a LIB file that provides the necessary linking information. -1. Copy the DLL to the output folder of your project, or to another folder in the standard Windows search path for DLLs. See [Dynamic-Link Library Search Order](/windows/win32/dlls/dynamic-link-library-search-order). +1. Copy the DLL to the output folder of your project, or to another folder in the standard Windows search path for DLLs. For more information, see [Dynamic-Link Library Search Order](/windows/win32/dlls/dynamic-link-library-search-order). 2. Follow steps 1-3 for static libraries to provide the paths to the headers and LIB file. ## COM objects @@ -158,5 +161,5 @@ The following properties exist on COM and .NET assembly references, and aren't m ## See also -[C++ project property page reference](reference/property-pages-visual-cpp.md)
+[C++ project property page reference](reference/property-pages-visual-cpp.md)\ [Set C++ compiler and build properties in Visual Studio](working-with-project-properties.md) diff --git a/docs/build/arm-exception-handling.md b/docs/build/arm-exception-handling.md index 4f4cc2e07e..f2f9b9a13e 100644 --- a/docs/build/arm-exception-handling.md +++ b/docs/build/arm-exception-handling.md @@ -1,18 +1,18 @@ --- description: "Learn more about: ARM Exception Handling" title: "ARM Exception Handling" -ms.date: "07/11/2018" +ms.date: 12/15/2021 ms.assetid: fe0e615f-c033-4ad5-97f4-ff96af45b201 --- # ARM Exception Handling -Windows on ARM uses the same structured exception handling mechanism for asynchronous hardware-generated exceptions and synchronous software-generated exceptions. Language-specific exception handlers are built on top of Windows structured exception handling by using language helper functions. This document describes exception handling in Windows on ARM, and the language helpers used by code that's generated by the Microsoft ARM assembler and the MSVC compiler. +Windows on ARM uses the same structured exception-handling mechanism for asynchronous hardware-generated exceptions and synchronous software-generated exceptions. Language-specific exception handlers are built on top of Windows structured exception handling by using language helper functions. This document describes exception handling in Windows on ARM, and the language helpers both the Microsoft ARM assembler and the MSVC compiler generate. ## ARM Exception Handling -Windows on ARM uses *unwind codes* to control stack unwinding during [structured exception handling](/windows/win32/debug/structured-exception-handling) (SEH). Unwind codes are a sequence of bytes stored in the `.xdata` section of the executable image. They describe the operation of function prologue and epilogue code in an abstract way, so that the effects of a function's prologue can be undone in preparation for unwinding to the caller's stack frame. +Windows on ARM uses *unwind codes* to control stack unwinding during [structured exception handling](/windows/win32/debug/structured-exception-handling) (SEH). Unwind codes are a sequence of bytes stored in the `.xdata` section of the executable image. These codes describe the operation of function prologue and epilogue code in an abstract way. The handler uses them to undo the function prologue's effects when it unwinds to the caller's stack frame. -The ARM EABI (embedded application binary interface) specifies an exception unwinding model that uses unwind codes, but it's not sufficient for SEH unwinding in Windows, which must handle asynchronous cases where the processor is in the middle of the prologue or epilogue of a function. Windows also separates unwinding control into function-level unwinding and language-specific scope unwinding, which is unified in the ARM EABI. For these reasons, Windows on ARM specifies more details for the unwinding data and procedure. +The ARM EABI (embedded application binary interface) specifies a model for exception unwinding that uses unwind codes. The model isn't sufficient for SEH unwinding in Windows. It must handle asynchronous cases where the processor is in the middle of the prologue or epilogue of a function. Windows also separates unwinding control into function-level unwinding and language-specific scope unwinding, which is unified in the ARM EABI. For these reasons, Windows on ARM specifies more details for the unwinding data and procedure. ### Assumptions @@ -20,15 +20,15 @@ Executable images for Windows on ARM use the Portable Executable (PE) format. Fo The exception handling mechanism makes certain assumptions about code that follows the ABI for Windows on ARM: -- When an exception occurs within the body of a function, it does not matter whether the prologue's operations are undone, or the epilogue's operations are performed in a forward manner. Both should produce identical results. +- When an exception occurs within the body of a function, the handler could undo the prologue's operations, or do the epilogue's operations in a forward manner. Both should produce identical results. -- Prologues and epilogues tend to mirror each other. This can be used to reduce the size of the metadata needed to describe unwinding. +- Prologues and epilogues tend to mirror each other. This feature can be used to reduce the size of the metadata needed to describe unwinding. -- Functions tend to be relatively small. Several optimizations rely on this for efficient packing of data. +- Functions tend to be relatively small. Several optimizations rely on this observation for efficient packing of data. - If a condition is placed on an epilogue, it applies equally to each instruction in the epilogue. -- If the stack pointer (SP) is saved in another register in the prologue, that register must remain unchanged throughout the function, so that the original SP may be recovered at any time. +- If the prologue saves the stack pointer (SP) in another register, that register must remain unchanged throughout the function, so the original SP may be recovered at any time. - Unless the SP is saved in another register, all manipulation of it must occur strictly within the prologue and epilogue. @@ -48,7 +48,7 @@ The exception handling mechanism makes certain assumptions about code that follo ### `.pdata` Records -The `.pdata` records in a PE-format image are an ordered array of fixed-length items that describe every stack-manipulating function. Leaf functions, which are functions that do not call other functions, don't require `.pdata` records when they don't manipulate the stack. (That is, they don't require any local storage and don't have to save or restore non-volatile registers.). Records for these functions can be omitted from the `.pdata` section to save space. An unwind operation from one of these functions can just copy the return address from the Link Register (LR) to the program counter (PC) to move up to the caller. +The `.pdata` records in a PE-format image are an ordered array of fixed-length items that describe every stack-manipulating function. Leaf functions (functions that don't call other functions) don't require `.pdata` records when they don't manipulate the stack. (That is, they don't require any local storage and don't have to save or restore non-volatile registers.). Records for these functions can be omitted from the `.pdata` section to save space. An unwind operation from one of these functions can just copy the return address from the Link Register (LR) to the program counter (PC) to move up to the caller. Every `.pdata` record for ARM is 8 bytes long. The general format of a record places the relative virtual address (RVA) of the function start in the first 32-bit word, followed by a second word that contains either a pointer to a variable-length `.xdata` block, or a packed word that describes a canonical function unwinding sequence, as shown in this table: @@ -60,28 +60,28 @@ Every `.pdata` record for ARM is 8 bytes long. The general format of a record pl ### Packed Unwind Data -For functions whose prologues and epilogues follow the canonical form described below, packed unwind data can be used. This eliminates the need for an `.xdata` record and significantly reduces the space required to provide unwind data. The canonical prologues and epilogues are designed to meet the common requirements of a simple function that does not require an exception handler, and performs its setup and teardown operations in a standard order. +For functions whose prologues and epilogues follow the canonical form described below, packed unwind data can be used. It eliminates the need for an `.xdata` record and significantly reduces the space required to provide the unwind data. The canonical prologues and epilogues are designed to meet the common requirements of a simple function that doesn't require an exception handler, and performs its setup and teardown operations in a standard order. This table shows the format of a `.pdata` record that has packed unwind data: -|Word Offset|Bits|Purpose| -|-----------------|----------|-------------| -|0|0-31|*`Function Start RVA`* is the 32-bit RVA of the start of the function. If the function contains thumb code, the low bit of this address must be set.| -|1|0-1|*`Flag`* is a 2-bit field that has these meanings:

- 00 = packed unwind data not used; remaining bits point to `.xdata` record.
- 01 = packed unwind data.
- 10 = packed unwind data where the function is assumed to have no prologue. This is useful for describing function fragments that are discontiguous with the start of the function.
- 11 = reserved.| -|1|2-12|*`Function Length`* is an 11-bit field that provides the length of the entire function in bytes divided by 2. If the function is larger than 4K bytes, a full `.xdata` record must be used instead.| -|1|13-14|*`Ret`* is a 2-bit field that indicates how the function returns:

- 00 = return via pop {pc} (the *`L`* flag bit must be set to 1 in this case).
- 01 = return by using a 16-bit branch.
- 10 = return by using a 32-bit branch.
- 11 = no epilogue at all. This is useful for describing a discontiguous function fragment that may only contain a prologue, but whose epilogue is elsewhere.| -|1|15|*`H`* is a 1-bit flag that indicates whether the function "homes" the integer parameter registers (r0-r3) by pushing them at the start of the function, and deallocates the 16 bytes of stack before returning. (0 = does not home registers, 1 = homes registers.)| -|1|16-18|*`Reg`* is a 3-bit field that indicates the index of the last saved non-volatile register. If the *`R`* bit is 0, then only integer registers are being saved, and are assumed to be in the range of r4-rN, where N is equal to 4 + *`Reg`*. If the *`R`* bit is 1, then only floating-point registers are being saved, and are assumed to be in the range of d8-dN, where N is equal to 8 + *`Reg`*. The special combination of *`R`* = 1 and *`Reg`* = 7 indicates that no registers are saved.| -|1|19|*`R`* is a 1-bit flag that indicates whether the saved non-volatile registers are integer registers (0) or floating-point registers (1). If *`R`* is set to 1 and the *`Reg`* field is set to 7, no non-volatile registers were pushed.| -|1|20|*`L`* is a 1-bit flag that indicates whether the function saves/restores LR, along with other registers indicated by the *`Reg`* field. (0 = does not save/restore, 1 = does save/restore.)| -|1|21|*`C`* is a 1-bit flag that indicates whether the function includes extra instructions to set up a frame chain for fast stack walking (1) or not (0). If this bit is set, r11 is implicitly added to the list of integer non-volatile registers saved. (See restrictions below if the *`C`* flag is used.)| -|1|22-31|*`Stack Adjust`* is a 10-bit field that indicates the number of bytes of stack that are allocated for this function, divided by 4. However, only values between 0x000-0x3F3 can be directly encoded. Functions that allocate more than 4044 bytes of stack must use a full `.xdata` record. If the *`Stack Adjust`* field is 0x3F4 or larger, then the low 4 bits have special meaning:

- Bits 0-1 indicate the number of words of stack adjustment (1-4) minus 1.
- Bit 2 is set to 1 if the prologue combined this adjustment into its push operation.
- Bit 3 is set to 1 if the epilogue combined this adjustment into its pop operation.| +| Word Offset | Bits | Purpose | +|--|--|--| +| 0 | 0-31 | *`Function Start RVA`* is the 32-bit RVA of the start of the function. If the function contains thumb code, the low bit of this address must be set. | +| 1 | 0-1 | *`Flag`* is a 2-bit field that has these meanings:

- 00 = packed unwind data not used; remaining bits point to `.xdata` record.
- 01 = packed unwind data.
- 10 = packed unwind data where the function is assumed to have no prologue. This is useful for describing function fragments that are discontiguous with the start of the function.
- 11 = reserved. | +| 1 | 2-12 | *`Function Length`* is an 11-bit field that provides the length of the entire function in bytes divided by 2. If the function is larger than 4K bytes, a full `.xdata` record must be used instead. | +| 1 | 13-14 | *`Ret`* is a 2-bit field that indicates how the function returns:

- 00 = return via pop {pc} (the *`L`* flag bit must be set to 1 in this case).
- 01 = return by using a 16-bit branch.
- 10 = return by using a 32-bit branch.
- 11 = no epilogue at all. This is useful for describing a discontiguous function fragment that may only contain a prologue, but whose epilogue is elsewhere. | +| 1 | 15 | *`H`* is a 1-bit flag that indicates whether the function "homes" the integer parameter registers (r0-r3) by pushing them at the start of the function, and deallocates the 16 bytes of stack before returning. (0 = doesn't home registers, 1 = homes registers.) | +| 1 | 16-18 | *`Reg`* is a 3-bit field that indicates the index of the last saved non-volatile register. If the *`R`* bit is 0, then only integer registers are being saved, and are assumed to be in the range of r4-rN, where N is equal to 4 + *`Reg`*. If the *`R`* bit is 1, then only floating-point registers are being saved, and are assumed to be in the range of d8-dN, where N is equal to 8 + *`Reg`*. The special combination of *`R`* = 1 and *`Reg`* = 7 indicates that no registers are saved. | +| 1 | 19 | *`R`* is a 1-bit flag that indicates whether the saved non-volatile registers are integer registers (0) or floating-point registers (1). If *`R`* is set to 1 and the *`Reg`* field is set to 7, no non-volatile registers were pushed. | +| 1 | 20 | *`L`* is a 1-bit flag that indicates whether the function saves/restores LR, along with other registers indicated by the *`Reg`* field. (0 = doesn't save/restore, 1 = does save/restore.) | +| 1 | 21 | *`C`* is a 1-bit flag that indicates whether the function includes extra instructions to set up a frame chain for fast stack walking (1) or not (0). If this bit is set, r11 is implicitly added to the list of integer non-volatile registers saved. (See restrictions below if the *`C`* flag is used.) | +| 1 | 22-31 | *`Stack Adjust`* is a 10-bit field that indicates the number of bytes of stack that are allocated for this function, divided by 4. However, only values between 0x000-0x3F3 can be directly encoded. Functions that allocate more than 4044 bytes of stack must use a full `.xdata` record. If the *`Stack Adjust`* field is 0x3F4 or larger, then the low 4 bits have special meaning:

- Bits 0-1 indicate the number of words of stack adjustment (1-4) minus 1.
- Bit 2 is set to 1 if the prologue combined this adjustment into its push operation.
- Bit 3 is set to 1 if the epilogue combined this adjustment into its pop operation. | Due to possible redundancies in the encodings above, these restrictions apply: - If the *`C`* flag is set to 1: - - The *`L`* flag must also be set to 1, because frame chaining required both r11 and LR. + - The *`L`* flag must also be set to 1, because frame chaining requires both r11 and LR. - r11 must not be included in the set of registers described by *`Reg`*. That is, if r4-r11 are pushed, *`Reg`* should only describe r4-r10, because the *`C`* flag implies r11. @@ -97,14 +97,14 @@ For purposes of the discussion below, two pseudo-flags are derived from *`Stack Prologues for canonical functions may have up to 5 instructions (notice that 3a and 3b are mutually exclusive): -|Instruction|Opcode is assumed present if:|Size|Opcode|Unwind Codes| -|-----------------|-----------------------------------|----------|------------|------------------| -|1|*`H`*==1|16|`push {r0-r3}`|04| -|2|*`C`*==1 or *`L`*==1 or *`R`*==0 or *`PF`*==1|16/32|`push {registers}`|80-BF/D0-DF/EC-ED| -|3a|*`C`*==1 and (*`L`*==0 and *`R`*==1 and *`PF`*==0)|16|`mov r11,sp`|C0-CF/FB| -|3b|*`C`*==1 and (*`L`*==1 or *`R`*==0 or *`PF`*==1)|32|`add r11,sp,#xx`|FC| -|4|*`R`*==1 and *`Reg`* != 7|32|`vpush {d8-dE}`|E0-E7| -|5|*`Stack Adjust`* != 0 and *`PF`*==0|16/32|`sub sp,sp,#xx`|00-7F/E8-EB| +| Instruction | Opcode is assumed present if: | Size | Opcode | Unwind Codes | +|--|--|--|--|--| +| 1 | *`H`*==1 | 16 | `push {r0-r3}` | 04 | +| 2 | *`C`*==1 or *`L`*==1 or *`R`*==0 or *`PF`*==1 | 16/32 | `push {registers}` | 80-BF/D0-DF/EC-ED | +| 3a | *`C`*==1 and (*`R`*==1 and *`PF`*==0) | 16 | `mov r11,sp` | FB | +| 3b | *`C`*==1 and (*`R`*==0 or *`PF`*==1) | 32 | `add r11,sp,#xx` | FC | +| 4 | *`R`*==1 and *`Reg`* != 7 | 32 | `vpush {d8-dE}` | E0-E7 | +| 5 | *`Stack Adjust`* != 0 and *`PF`*==0 | 16/32 | `sub sp,sp,#xx` | 00-7F/E8-EB | Instruction 1 is always present if the *`H`* bit is set to 1. @@ -114,44 +114,44 @@ If a non-folded adjustment is specified, instruction 5 is the explicit stack adj Instructions 2 and 4 are set based on whether a push is required. This table summarizes which registers are saved based on the *`C`*, *`L`*, *`R`*, and *`PF`* fields. In all cases, *`N`* is equal to *`Reg`* + 4, *`E`* is equal to *`Reg`* + 8, and *`S`* is equal to (~*`Stack Adjust`*) & 3. -|C|L|R|PF|Integer Registers Pushed|VFP Registers pushed| -|-------|-------|-------|--------|------------------------------|--------------------------| -|0|0|0|0|r4 - r*`N`*|none| -|0|0|0|1|r*`S`* - r*`N`*|none| -|0|0|1|0|none|d8 - d*`E`*| -|0|0|1|1|r*`S`* - r3|d8 - d*`E`*| -|0|1|0|0|r4 - r*`N`*, LR|none| -|0|1|0|1|r*`S`* - r*`N`*, LR|none| -|0|1|1|0|LR|d8 - d*`E`*| -|0|1|1|1|r*`S`* - r3, LR|d8 - d*`E`*| -|1|0|0|0|r4 - r*`N`*, r11|none| -|1|0|0|1|r*`S`* - r*`N`*, r11|none| -|1|0|1|0|r11|d8 - d*`E`*| -|1|0|1|1|r*`S`* - r3, r11|d8 - d*`E`*| -|1|1|0|0|r4 - r*`N`*, r11, LR|none| -|1|1|0|1|r*`S`* - r*`N`*, r11, LR|none| -|1|1|1|0|r11, LR|d8 - d*`E`*| -|1|1|1|1|r*`S`* - r3, r11, LR|d8 - d*`E`*| +| C | L | R | PF | Integer Registers Pushed | VFP Registers pushed | +|--|--|--|--|--|--| +| 0 | 0 | 0 | 0 | r4 - r*`N`* | none | +| 0 | 0 | 0 | 1 | r*`S`* - r*`N`* | none | +| 0 | 0 | 1 | 0 | none | d8 - d*`E`* | +| 0 | 0 | 1 | 1 | r*`S`* - r3 | d8 - d*`E`* | +| 0 | 1 | 0 | 0 | r4 - r*`N`*, LR | none | +| 0 | 1 | 0 | 1 | r*`S`* - r*`N`*, LR | none | +| 0 | 1 | 1 | 0 | LR | d8 - d*`E`* | +| 0 | 1 | 1 | 1 | r*`S`* - r3, LR | d8 - d*`E`* | +| 1 | 0 | 0 | 0 | (invalid encoding) | (invalid encoding) | +| 1 | 0 | 0 | 1 | (invalid encoding) | (invalid encoding) | +| 1 | 0 | 1 | 0 | (invalid encoding) | (invalid encoding) | +| 1 | 0 | 1 | 1 | (invalid encoding) | (invalid encoding) | +| 1 | 1 | 0 | 0 | r4 - r*`N`*, r11, LR | none | +| 1 | 1 | 0 | 1 | r*`S`* - r*`N`*, r11, LR | none | +| 1 | 1 | 1 | 0 | r11, LR | d8 - d*`E`* | +| 1 | 1 | 1 | 1 | r*`S`* - r3, r11, LR | d8 - d*`E`* | The epilogues for canonical functions follow a similar form, but in reverse and with some additional options. The epilogue may be up to 5 instructions long, and its form is strictly dictated by the form of the prologue. -|Instruction|Opcode is assumed present if:|Size|Opcode| -|-----------------|-----------------------------------|----------|------------| -|6|*`Stack Adjust`*!=0 and *`EF`*==0|16/32|`add sp,sp,#xx`| -|7|*`R`*==1 and *`Reg`*!=7|32|`vpop {d8-dE}`| -|8|*`C`*==1 or (*`L`*==1 and *`H`*==0) or *`R`*==0 or *`EF`*==1|16/32|`pop {registers}`| -|9a|*`H`*==1 and *`L`*==0|16|`add sp,sp,#0x10`| -|9b|*`H`*==1 and *`L`*==1|32|`ldr pc,[sp],#0x14`| -|10a|*`Ret`*==1|16|`bx reg`| -|10b|*`Ret`*==2|32|`b address`| +| Instruction | Opcode is assumed present if: | Size | Opcode | +|--|--|--|--| +| 6 | *`Stack Adjust`*!=0 and *`EF`*==0 | 16/32 | `add sp,sp,#xx` | +| 7 | *`R`*==1 and *`Reg`*!=7 | 32 | `vpop {d8-dE}` | +| 8 | *`C`*==1 or (*`L`*==1 and (*`H`*==0 or *`Ret`* !=0)) or *`R`*==0 or *`EF`*==1 | 16/32 | `pop {registers}` | +| 9a | *`H`*==1 and (*`L`*==0 or *`Ret`*!=0) | 16 | `add sp,sp,#0x10` | +| 9b | *`H`*==1 and *`L`*==1 and *`Ret`*==0 | 32 | `ldr pc,[sp],#0x14` | +| 10a | *`Ret`*==1 | 16 | `bx reg` | +| 10b | *`Ret`*==2 | 32 | `b address` | Instruction 6 is the explicit stack adjustment if a non-folded adjustment is specified. Because *`PF`* is independent of *`EF`*, it is possible to have instruction 5 present without instruction 6, or vice-versa. -Instructions 7 and 8 use the same logic as the prologue to determine which registers are restored from the stack, but with these two changes: first, *`EF`* is used in place of *`PF`*; second, if *`Ret`* = 0, then LR is replaced with PC in the register list and the epilogue ends immediately. +Instructions 7 and 8 use the same logic as the prologue to determine which registers are restored from the stack, but with these three changes: first, *`EF`* is used in place of *`PF`*; second, if *`Ret`* = 0 and *`H`* = 0, then LR is replaced with PC in the register list and the epilogue ends immediately; third, if *`Ret`* = 0 and *`H`* = 1, then LR is omitted from the register list and popped by instruction 9b. -If *`H`* is set, then either instruction 9a or 9b is present. Instruction 9a is used when *`L`* is 0, to indicate that the LR is not on the stack. In this case, the stack is manually adjusted and *`Ret`* must be 1 or 2 to specify an explicit return. Instruction 9b is used when *`L`* is 1, to indicate an early end to the epilogue, and to return and adjust the stack at the same time. +If *`H`* is set, then either instruction 9a or 9b is present. Instruction 9a is used when *`Ret`* is nonzero, which also implies the presence of either 10a or 10b. If L=1, then LR was popped as part of instruction 8. Instruction 9b is used when *`L`* is 1 and *`Ret`* is zero, to indicate an early end to the epilogue, and to return and adjust the stack at the same time. -If the epilogue has not already ended, then either instruction 10a or 10b is present, to indicate a 16-bit or 32-bit branch, based on the value of *`Ret`*. +If the epilogue hasn't already ended, then either instruction 10a or 10b is present, to indicate a 16-bit or 32-bit branch, based on the value of *`Ret`*. ### `.xdata` Records @@ -165,8 +165,8 @@ When the packed unwind format is insufficient to describe the unwinding of a fun |0|18-19|*Vers* is a 2-bit field that describes the version of the remaining`.xdata`. Only version 0 is currently defined; values of 1-3 are reserved.| |0|20|*X* is a 1-bit field that indicates the presence (1) or absence (0) of exception data.| |0|21|*`E`* is a 1-bit field that indicates that information that describes a single epilogue is packed into the header (1) rather than requiring additional scope words later (0).| - |0|22|*F* is a 1-bit field that indicates that this record describes a function fragment (1) or a full function (0). A fragment implies that there is no prologue and that all prologue processing should be ignored.| - |0|23-27|*Epilogue Count* is a 5-bit field that has two meanings, depending on the state of the *`E`* bit:

- If *`E`* is 0, this field is a count of the total number of exception scopes described in section 3. If more than 31 scopes exist in the function, then this field and the *Code Words* field must both be set to 0 to indicate that an extension word is required.
- If *`E`* is 1, this field specifies the index of the first unwind code that describes the only epilogue.| + |0|22|*F* is a 1-bit field that indicates that this record describes a function fragment (1) or a full function (0). A fragment implies that there's no prologue and that all prologue processing should be ignored.| + |0|23-27|*Epilogue Count* is a 5-bit field that has two meanings, depending on the state of the *`E`* bit:

- If *`E`* is 0, this field is a count of the total number of epilogue scopes described in section 2. If more than 31 scopes exist in the function, then this field and the *Code Words* field must both be set to 0 to indicate that an extension word is required.
- If *`E`* is 1, this field specifies the index of the first unwind code that describes the only epilogue.| |0|28-31|*Code Words* is a 4-bit field that specifies the number of 32-bit words required to contain all of the unwind codes in section 4. If more than 15 words are required for more than 63 unwind code bytes, this field and the *Epilogue Count* field must both be set to 0 to indicate that an extension word is required.| |1|0-15|*Extended Epilogue Count* is a 16-bit field that provides more space for encoding an unusually large number of epilogues. The extension word that contains this field is only present if the *Epilogue Count* and *Code Words* fields in the first header word are both set to 0.| |1|16-23|*Extended Code Words* is an 8-bit field that provides more space for encoding an unusually large number of unwind code words. The extension word that contains this field is only present if the *Epilogue Count* and *Code Words* fields in the first header word are both set to 0.| @@ -218,7 +218,7 @@ ULONG ComputeXdataSize(PULONG Xdata) } ``` -Although the prologue and each epilogue has an index into the unwind codes, the table is shared between them. It is not uncommon that they can all share the same unwind codes. We recommend that compiler writers optimize for this case, because the largest index that can be specified is 255, and that limits the total number of unwind codes possible for a particular function. +Although the prologue and each epilogue has an index into the unwind codes, the table is shared between them. It's not uncommon that they can all share the same unwind codes. We recommend that compiler writers optimize for this case, because the largest index that can be specified is 255, and that limits the total number of unwind codes possible for a particular function. ### Unwind Codes @@ -234,32 +234,32 @@ If exceptions were guaranteed to only ever occur within a function body, and nev The following table shows the mapping from unwind codes to opcodes. The most common codes are just one byte, while less common ones require two, three, or even four bytes. Each code is stored from most significant byte to least significant byte. The unwind code structure differs from the encoding described in the ARM EABI, because these unwind codes are designed to have a one-to-one mapping to the opcodes in the prologue and epilogue to allow for unwinding of partially executed prologues and epilogues. -|Byte 1|Byte 2|Byte 3|Byte 4|Opsize|Explanation| -|------------|------------|------------|------------|------------|-----------------| -|00-7F||||16|`add sp,sp,#X`

where X is (Code & 0x7F) \* 4| -|80-BF|00-FF|||32|`pop {r0-r12, lr}`

where LR is popped if Code & 0x2000 and r0-r12 are popped if the corresponding bit is set in Code & 0x1FFF| -|C0-CF||||16|`mov sp,rX`

where X is Code & 0x0F| -|D0-D7||||16|`pop {r4-rX,lr}`

where X is (Code & 0x03) + 4 and LR is popped if Code & 0x04| -|D8-DF||||32|`pop {r4-rX,lr}`

where X is (Code & 0x03) + 8 and LR is popped if Code & 0x04| -|E0-E7||||32|`vpop {d8-dX}`

where X is (Code & 0x07) + 8| -|E8-EB|00-FF|||32|`addw sp,sp,#X`

where X is (Code & 0x03FF) \* 4| -|EC-ED|00-FF|||16|`pop {r0-r7,lr}`

where LR is popped if Code & 0x0100 and r0-r7 are popped if the corresponding bit is set in Code & 0x00FF| -|EE|00-0F|||16|Microsoft-specific| -|EE|10-FF|||16|Available| -|EF|00-0F|||32|`ldr lr,[sp],#X`

where X is (Code & 0x000F) \* 4| -|EF|10-FF|||32|Available| -|F0-F4||||-|Available| -|F5|00-FF|||32|`vpop {dS-dE}`

where S is (Code & 0x00F0) >> 4 and E is Code & 0x000F| -|F6|00-FF|||32|`vpop {dS-dE}`

where S is ((Code & 0x00F0) >> 4) + 16 and E is (Code & 0x000F) + 16| -|F7|00-FF|00-FF||16|`add sp,sp,#X`

where X is (Code & 0x00FFFF) \* 4| -|F8|00-FF|00-FF|00-FF|16|`add sp,sp,#X`

where X is (Code & 0x00FFFFFF) \* 4| -|F9|00-FF|00-FF||32|`add sp,sp,#X`

where X is (Code & 0x00FFFF) \* 4| -|FA|00-FF|00-FF|00-FF|32|`add sp,sp,#X`

where X is (Code & 0x00FFFFFF) \* 4| -|FB||||16|nop (16-bit)| -|FC||||32|nop (32-bit)| -|FD||||16|end + 16-bit nop in epilogue| -|FE||||32|end + 32-bit nop in epilogue| -|FF||||-|end| +| Byte 1 | Byte 2 | Byte 3 | Byte 4 | Opsize | Explanation | +|--|--|--|--|--|--| +| 00-7F | | | | 16 | `add sp,sp,#X`

where X is (Code & 0x7F) \* 4 | +| 80-BF | 00-FF | | | 32 | `pop {r0-r12, lr}`

where LR is popped if Code & 0x2000 and r0-r12 are popped if the corresponding bit is set in Code & 0x1FFF | +| C0-CF | | | | 16 | `mov sp,rX`

where X is Code & 0x0F | +| D0-D7 | | | | 16 | `pop {r4-rX,lr}`

where X is (Code & 0x03) + 4 and LR is popped if Code & 0x04 | +| D8-DF | | | | 32 | `pop {r4-rX,lr}`

where X is (Code & 0x03) + 8 and LR is popped if Code & 0x04 | +| E0-E7 | | | | 32 | `vpop {d8-dX}`

where X is (Code & 0x07) + 8 | +| E8-EB | 00-FF | | | 32 | `addw sp,sp,#X`

where X is (Code & 0x03FF) \* 4 | +| EC-ED | 00-FF | | | 16 | `pop {r0-r7,lr}`

where LR is popped if Code & 0x0100 and r0-r7 are popped if the corresponding bit is set in Code & 0x00FF | +| EE | 00-0F | | | 16 | Microsoft-specific | +| EE | 10-FF | | | 16 | Available | +| EF | 00-0F | | | 32 | `ldr lr,[sp],#X`

where X is (Code & 0x000F) \* 4 | +| EF | 10-FF | | | 32 | Available | +| F0-F4 | | | | - | Available | +| F5 | 00-FF | | | 32 | `vpop {dS-dE}`

where S is (Code & 0x00F0) >> 4 and E is Code & 0x000F | +| F6 | 00-FF | | | 32 | `vpop {dS-dE}`

where S is ((Code & 0x00F0) >> 4) + 16 and E is (Code & 0x000F) + 16 | +| F7 | 00-FF | 00-FF | | 16 | `add sp,sp,#X`

where X is (Code & 0x00FFFF) \* 4 | +| F8 | 00-FF | 00-FF | 00-FF | 16 | `add sp,sp,#X`

where X is (Code & 0x00FFFFFF) \* 4 | +| F9 | 00-FF | 00-FF | | 32 | `add sp,sp,#X`

where X is (Code & 0x00FFFF) \* 4 | +| FA | 00-FF | 00-FF | 00-FF | 32 | `add sp,sp,#X`

where X is (Code & 0x00FFFFFF) \* 4 | +| FB | | | | 16 | nop (16-bit) | +| FC | | | | 32 | nop (32-bit) | +| FD | | | | 16 | end + 16-bit nop in epilogue | +| FE | | | | 32 | end + 32-bit nop in epilogue | +| FF | | | | - | end | This shows the range of hexadecimal values for each byte in an unwind code *Code*, along with the opcode size *Opsize* and the corresponding original instruction interpretation. Empty cells indicate shorter unwind codes. In instructions that have large values covering multiple bytes, the most significant bits are stored first. The *Opsize* field shows the implicit opcode size associated with each Thumb-2 operation. The apparent duplicate entries in the table with different encodings are used to distinguish between different opcode sizes. @@ -300,7 +300,7 @@ In the example, if an exception occurs while the function body between the prolo Similar logic works in reverse for the prologue. If unwinding from offset 0 in the prologue, nothing has to be executed. If unwinding from one instruction in, the unwind sequence should start one unwind code from the end because prologue unwind codes are stored in reverse order. In the general case, if unwinding from instruction *n* in the prologue, unwinding should start executing at *n* unwind codes from the end of the list of codes. -Prologue and epilogue unwind codes do not always match exactly. In that case, the unwind code array may have to contain several sequences of codes. To determine the offset to begin processing codes, use this logic: +Prologue and epilogue unwind codes don't always match exactly. In that case, the unwind code array may have to contain several sequences of codes. To determine the offset to begin processing codes, use this logic: 1. If unwinding from within the body of the function, begin executing unwind codes at index 0 and continue until an end opcode is reached. @@ -308,7 +308,7 @@ Prologue and epilogue unwind codes do not always match exactly. In that case, th 3. If unwinding from within the prologue, start from index 0 in the unwind codes. Calculate the length of the prologue code from the sequence, and then calculate how many bytes the PC is from the end of the prologue. Skip forward through the unwind codes until all of the unexecuted instructions are accounted for. Execute the unwind sequence starting at that point. -The unwind codes for the prologue must always be the first in the array. They are also the codes used to unwind in the general case of unwinding from within the body. Any epilogue-specific code sequences should follow immediately after the prologue code sequence. +The unwind codes for the prologue must always be the first in the array. they're also the codes used to unwind in the general case of unwinding from within the body. Any epilogue-specific code sequences should follow immediately after the prologue code sequence. ### Function Fragments @@ -318,31 +318,31 @@ Assuming that the function prologue is at the beginning of the function and can' - Prologue only; all epilogues in other fragments. -- Prologue and one or more epilogues; additional epilogues in other fragments. +- Prologue and one or more epilogues; more epilogues in other fragments. - No prologue or epilogues; prologue and one or more epilogues in other fragments. -- Epilogues only; prologue and possibly additional epilogues in other fragments. +- Epilogues only; prologue and possibly more epilogues in other fragments. In the first case, only the prologue must be described. This can be done in compact `.pdata` form by describing the prologue normally and specifying a *`Ret`* value of 3 to indicate no epilogue. In the full `.xdata` form, this can be done by providing the prologue unwind codes at index 0 as usual, and specifying an epilogue count of 0. The second case is just like a normal function. If there's only one epilogue in the fragment, and it is at the end of the fragment, then a compact `.pdata` record can be used. Otherwise, a full `.xdata` record must be used. Keep in mind that the offsets specified for the epilogue start are relative to the start of the fragment, not the original start of the function. -The third and fourth cases are variants of the first and second cases, respectively, except they don't contain a prologue. In these situations, it is assumed that there is code before the start of the epilogue and it is considered part of the body of the function, which would normally be unwound by undoing the effects of the prologue. These cases must therefore be encoded with a pseudo-prologue, which describes how to unwind from within the body, but which is treated as 0-length when determining whether to perform a partial unwind at the start of the fragment. Alternatively, this pseudo-prologue may be described by using the same unwind codes as the epilogue because they presumably perform equivalent operations. +The third and fourth cases are variants of the first and second cases, respectively, except they don't contain a prologue. In these situations, it is assumed that there's code before the start of the epilogue and it is considered part of the body of the function, which would normally be unwound by undoing the effects of the prologue. These cases must therefore be encoded with a pseudo-prologue, which describes how to unwind from within the body, but which is treated as 0-length when determining whether to perform a partial unwind at the start of the fragment. Alternatively, this pseudo-prologue may be described by using the same unwind codes as the epilogue because they presumably perform equivalent operations. In the third and fourth cases, the presence of a pseudo-prologue is specified either by setting the *`Flag`* field of the compact `.pdata` record to 2, or by setting the *F* flag in the `.xdata` header to 1. In either case, the check for a partial prologue unwind is ignored, and all non-epilogue unwinds are considered to be full. #### Large Functions -Fragments can be used to describe functions larger than the 512 KB limit imposed by the bit fields in the `.xdata` header. To describe a very large function, just break it into fragments smaller than 512 KB. Each fragment should be adjusted so that it does not split an epilogue into multiple pieces. +Fragments can be used to describe functions larger than the 512 KB limit imposed by the bit fields in the `.xdata` header. To describe a larger function, just break it into fragments smaller than 512 KB. Each fragment should be adjusted so it doesn't split an epilogue into multiple pieces. -Only the first fragment of the function contains a prologue; all other fragments are marked as having no prologue. Depending on the number of epilogues, each fragment may contain zero or more epilogues. Keep in mind that each epilogue scope in a fragment specifies its starting offset relative to the start of the fragment, not the start of the function. +Only the first fragment of the function contains a prologue. All other fragments are marked as having no prologue. Depending on the number of epilogues, each fragment may contain zero or more epilogues. Keep in mind that each epilogue scope in a fragment specifies its starting offset relative to the start of the fragment, not the start of the function. If a fragment has no prologue and no epilogue, it still requires its own `.pdata`—and possibly `.xdata`—record to describe how to unwind from within the body of the function. #### Shrink-wrapping -A more complex special case of function fragments is *shrink-wrapping*, a technique for deferring register saves from the start of the function to later in the function, to optimize for simple cases that don't require register saving. This can be described as an outer region that allocates the stack space but saves a minimal set of registers, and an inner region that saves and restores additional registers. +A more complex special case of function fragments is called *shrink-wrapping*. It's a technique for deferring register saves from the start of the function to later in the function. It optimizes for simple cases that don't require register saving. This case has two parts: there's an outer region that allocates the stack space but saves a minimal set of registers, and an inner region that saves and restores other registers. ```asm ShrinkWrappedFunction @@ -358,19 +358,19 @@ ShrinkWrappedFunction pop {r4, pc} ; C: ``` -Shrink-wrapped functions are typically expected to pre-allocate the space for the extra register saves in the regular prologue, and then perform the register saves by using `str` or `stm` instead of `push`. This keeps all stack-pointer manipulation in the function's original prologue. +Shrink-wrapped functions are typically expected to pre-allocate the space for the extra register saves in the regular prologue, and then save the registers by using `str` or `stm` instead of `push`. This action keeps all stack-pointer manipulation in the function's original prologue. -The example shrink-wrapped function must be broken into three regions, which are marked as A, B, and C in the comments. The first A region covers the start of the function through the end of the additional non-volatile saves. A `.pdata` or `.xdata` record must be constructed to describe this fragment as having a prologue and no epilogues. +The example shrink-wrapped function must be broken into three regions, which are marked as `A`, `B`, and `C` in the comments. The first `A` region covers the start of the function through the end of the additional non-volatile saves. A `.pdata` or `.xdata` record must be constructed to describe this fragment as having a prologue and no epilogues. -The middle B region gets its own `.pdata` or `.xdata` record that describes a fragment that has no prologue and no epilogue. However, the unwind codes for this region must still be present because it's considered a function body. The codes must describe a composite prologue that represents both the original registers saved in the region-A prologue and the additional registers saved before entering region B, as if they were produced by one sequence of operations. +The middle `B` region gets its own `.pdata` or `.xdata` record that describes a fragment that has no prologue and no epilogue. However, the unwind codes for this region must still be present because it's considered a function body. The codes must describe a composite prologue that represents both the original registers saved in the region `A` prologue and the extra registers saved before entering region `B`, as if they were produced by one sequence of operations. -The register saves for region B can't be considered as an "inner prologue" because the composite prologue described for region B must describe both the region-A prologue and the additional registers saved. If fragment B were described as having a prologue, the unwind codes would also imply the size of that prologue, and there is no way to describe the composite prologue in a way that maps one-to-one with the opcodes that only save the additional registers. +The register saves for region `B` can't be considered as an "inner prologue" because the composite prologue described for region `B` must describe both the region `A` prologue and the additional registers saved. If fragment `B` had a prologue, the unwind codes would also imply the size of that prologue, and there's no way to describe the composite prologue in a way that maps one-to-one with the opcodes that only save the additional registers. -The additional register saves must be considered part of region A, because until they are complete, the composite prologue does not accurately describe the state of the stack. +The extra register saves must be considered part of region `A`, because until they're complete, the composite prologue doesn't accurately describe the state of the stack. -The last C region gets its own `.pdata` or `.xdata` record, describing a fragment that has no prologue but does have an epilogue. +The last `C` region gets its own `.pdata` or `.xdata` record, describing a fragment that has no prologue but does have an epilogue. -An alternative approach can also work if the stack manipulation done before entering region B can be reduced to one instruction: +An alternative approach can also work if the stack manipulation done before entering region `B` can be reduced to one instruction: ```asm ShrinkWrappedFunction @@ -384,23 +384,23 @@ ShrinkWrappedFunction pop {r4, pc} ; C: restore non-volatile registers ``` -The key here is that on each instruction boundary, the stack is fully consistent with the unwind codes for the region. If an unwind occurs before the inner push in this example, it is considered part of region A, and only the region A prologue is unwound. If the unwind occurs after the inner push, it is considered part of region B, which has no prologue, but has unwind codes that describe both the inner push and the original prologue from region A. Similar logic holds for the inner pop. +The key insight is that on each instruction boundary, the stack is fully consistent with the unwind codes for the region. If an unwind occurs before the inner push in this example, it's considered part of region `A`. Only the region `A` prologue is unwound. If the unwind occurs after the inner push, it's considered part of region `B`, which has no prologue. However, it has unwind codes that describe both the inner push and the original prologue from region `A`. Similar logic holds for the inner pop. ### Encoding Optimizations -Because of the richness of the unwind codes, and the ability to leverage compact and expanded forms of data, there are many opportunities to optimize the encoding to further reduce space. With aggressive use of these techniques, the net overhead of describing functions and fragments by using unwind codes can be minimized. +The richness of the unwind codes, and the ability to make use of compact and expanded forms of data, provide many opportunities to optimize the encoding to further reduce space. With aggressive use of these techniques, the net overhead of describing functions and fragments by using unwind codes can be minimized. -The most important optimization is to be careful not to confuse prologue/epilogue boundaries for unwinding purposes with logical prologue/epilogue boundaries from a compiler perspective. The unwinding boundaries can be shrunk and made tighter to improve efficiency. For example, a prologue may contain code after the stack setup to perform additional verification checks. But once all the stack manipulation is complete, there is no need to encode further operations, and anything beyond that can be removed from the unwinding prologue. +The most important optimization idea: Don't confuse prologue and epilogue boundaries for unwinding purposes with logical prologue and epilogue boundaries from a compiler perspective. The unwinding boundaries can be shrunk and made tighter to improve efficiency. For example, a prologue may contain code after the stack setup to do verification checks. But once all the stack manipulation is complete, there's no need to encode further operations, and anything beyond that can be removed from the unwinding prologue. -This same rule applies to the function length. If there's data—for example, a literal pool—that follows an epilogue in a function, it shouldn't be included as part of the function length. By shrinking the function to just the code that's part of the function, the chances are much greater that the epilogue will be at the very end and a compact `.pdata` record can be used. +This same rule applies to the function length. If there's data (such as a literal pool) that follows an epilogue in a function, it shouldn't be included as part of the function length. By shrinking the function to just the code that's part of the function, the chances are much greater that the epilogue is at the very end and a compact `.pdata` record can be used. -In a prologue, once the stack pointer is saved to another register, there's typically no need to record any further opcodes. To unwind the function, the first thing that's done is to recover SP from the saved register, and so further operations don't have any impact on the unwind. +In a prologue, once the stack pointer is saved to another register, there's typically no need to record any further opcodes. To unwind the function, the first thing that's done is to recover SP from the saved register. Further operations don't have any effect on the unwind. -Single-instruction epilogues don't have to be encoded at all, either as scopes or as unwind codes. If an unwind takes place before that instruction is executed, then it can be assumed to be from within the body of the function; just executing the prologue unwind codes is sufficient. If the unwind takes place after the single instruction is executed, then by definition it takes place in another region. +Single-instruction epilogues don't have to be encoded at all, either as scopes or as unwind codes. If an unwind takes place before that instruction is executed, then it's safe to assume it's from within the body of the function. Just executing the prologue unwind codes is sufficient. When the unwind takes place after the single instruction is executed, then by definition it takes place in another region. -Multi-instruction epilogues don't have to encode the first instruction of the epilogue, for the same reason as the previous point: if the unwind takes place before that instruction executes, a full prologue unwind is sufficient. If the unwind takes place after that instruction, then only the subsequent operations have to be considered. +Multi-instruction epilogues don't have to encode the first instruction of the epilogue, for the same reason as the previous point: if the unwind takes place before that instruction executes, a full prologue unwind is sufficient. If the unwind takes place after that instruction, then only the later operations have to be considered. -Unwind code reuse should be aggressive. The index specified by each epilogue scope points to an arbitrary starting point in the array of unwind codes. It does not have to point to the start of a previous sequence; it can point in the middle. The best approach here is to generate the desired code sequence and then scan for an exact byte match in the already-encoded pool of sequences. Use any perfect match as a starting point for reuse. +Unwind code reuse should be aggressive. The index each epilogue scope specifies points to an arbitrary starting point in the array of unwind codes. It doesn't have to point to the start of a previous sequence; it can point in the middle. The best approach is to generate the unwind code sequence. Then, scan for an exact byte match in the already-encoded pool of sequences. Use any perfect match as a starting point for reuse. After single-instruction epilogues are ignored, if there are no remaining epilogues, consider using a compact `.pdata` form; it becomes much more likely in the absence of an epilogue. @@ -418,7 +418,7 @@ Epilogue: 00453658: 4770 bx lr ``` -.pdata (fixed, 2 words): +`.pdata` (fixed, 2 words): - Word 0 @@ -434,7 +434,7 @@ Epilogue: - *`H`* = 0, indicating the parameters weren't homed - - *`R`*=0 and *`Reg`* = 1, indicating push/pop of r4-r5 + - *`R`* = 0 and *`Reg`* = 1, indicating push/pop of r4-r5 - *`L`* = 0, indicating no LR save/restore @@ -453,7 +453,7 @@ Epilogue: 00453414: BDF0 pop {r4-r7, pc} ``` -.pdata (fixed, 2 words): +`.pdata` (fixed, 2 words): - Word 0 @@ -469,7 +469,7 @@ Epilogue: - *`H`* = 0, indicating the parameters weren't homed - - *`R`*=0 and *`Reg`* = 3, indicating push/pop of r4-r7 + - *`R`* = 0 and *`Reg`* = 3, indicating push/pop of r4-r7 - *`L`* = 1, indicating LR was saved/restored @@ -488,7 +488,7 @@ Epilogue: 004539D8: F85D FB14 ldr pc, [sp], #0x14 ``` -.pdata (fixed, 2 words): +`.pdata` (fixed, 2 words): - Word 0 @@ -504,7 +504,7 @@ Epilogue: - *`H`* = 1, indicating the parameters were homed - - *`R`*=0 and *`Reg`* = 2, indicating push/pop of r4-r6 + - *`R`* = 0 and *`Reg`* = 2, indicating push/pop of r4-r6 - *`L`* = 1, indicating LR was saved/restored @@ -534,7 +534,7 @@ Epilogues: 00459636: F028 FF0F bl KeBugCheckEx ; end of function ``` -.pdata (fixed, 2 words): +`.pdata` (fixed, 2 words): - Word 0 @@ -552,17 +552,17 @@ Epilogues: - *`Function Length`* = 0x0001A3 (= 0x000346/2) - - *Vers* = 0, indicating the first version of`.xdata` + - *`Vers`* = 0, indicating the first version of`.xdata` - - *X* = 0, indicating no exception data + - *`X`* = 0, indicating no exception data - *`E`* = 0, indicating a list of epilogue scopes - - *F* = 0, indicating a full function description, including prologue + - *`F`* = 0, indicating a full function description, including prologue - - *Epilogue Count* = 0x04, indicating the 4 total epilogue scopes + - *`Epilogue Count`* = 0x04, indicating the 4 total epilogue scopes - - *Code Words* = 0x01, indicating one 32-bit word of unwind codes + - *`Code Words`* = 0x01, indicating one 32-bit word of unwind codes - Words 1-4, describing 4 epilogue scopes at 4 locations. Each scope has a common set of unwind codes, shared with the prologue, at offset 0x00, and is unconditional, specifying condition 0x0E (always). @@ -594,7 +594,7 @@ Epilogue: 00485E2A: F7FF BE7D b #0x485B28 ; end of function ``` -.pdata (fixed, 2 words): +`.pdata` (fixed, 2 words): - Word 0 @@ -612,17 +612,17 @@ Epilogue: - *`Function Length`* = 0x0001A3 (= 0x000346/2) - - *Vers* = 0, indicating the first version of`.xdata` + - *`Vers`* = 0, indicating the first version of`.xdata` - - *X* = 0, indicating no exception data + - *`X`* = 0, indicating no exception data - *`E`* = 0, indicating a list of epilogue scopes - - *F* = 0, indicating a full function description, including prologue + - *`F`* = 0, indicating a full function description, including prologue - - *Epilogue Count* = 0x001, indicating the 1 total epilogue scope + - *`Epilogue Count`* = 0x001, indicating the 1 total epilogue scope - - *Code Words* = 0x01, indicating one 32-bit word of unwind codes + - *`Code Words`* = 0x01, indicating one 32-bit word of unwind codes - Word 1: Epilogue scope at offset 0xC6 (= 0x18C/2), starting unwind code index at 0x00, and with a condition of 0x0E (always) @@ -652,7 +652,7 @@ Epilogue: 00488C70: BD90 pop {r4, r7, pc} ``` -.pdata (fixed, 2 words): +`.pdata` (fixed, 2 words): - Word 0 @@ -670,17 +670,17 @@ Epilogue: - *`Function Length`* =0x000027 (= 0x00004E/2) - - *Vers* = 0, indicating the first version of`.xdata` + - *`Vers`* = 0, indicating the first version of`.xdata` - - *X* = 1, indicating exception data present + - *`X`* = 1, indicating exception data present - *`E`* = 1, indicating a single epilogue - - *F* = 0, indicating a full function description, including prologue + - *`F`* = 0, indicating a full function description, including prologue - - *Epilogue Count* = 0x00, indicating epilogue unwind codes start at offset 0x00 + - *`Epilogue Count`* = 0x00, indicating epilogue unwind codes start at offset 0x00 - - *Code Words* = 0x02, indicating two 32-bit words of unwind codes + - *`Code Words`* = 0x02, indicating two 32-bit words of unwind codes - Unwind codes, starting at Word 1: @@ -692,7 +692,7 @@ Epilogue: - Unwind code 4 = 0xFF: end -- Word 3 specifies an exception handler = 0x0019A7ED (= 0x0059A7ED - 0x00400000) +- Word 3 specifies an exception handler = 0x0019A7ED (= 0x0059A7ED - 0x00400000) - Words 4 and beyond are inlined exception data @@ -711,7 +711,7 @@ Function: 00488C86: BD00 pop {pc} ``` -.pdata (fixed, 2 words): +`.pdata` (fixed, 2 words): - Word 0 @@ -727,7 +727,7 @@ Function: - *`H`* = 0, indicating the parameters weren't homed - - *`R`*=0 and *`Reg`* = 7, indicating no registers were saved/restored + - *`R`* = 0 and *`Reg`* = 7, indicating no registers were saved/restored - *`L`* = 1, indicating LR was saved/restored diff --git a/docs/build/arm64-exception-handling.md b/docs/build/arm64-exception-handling.md index 54ed0165de..9bad5d2883 100644 --- a/docs/build/arm64-exception-handling.md +++ b/docs/build/arm64-exception-handling.md @@ -1,55 +1,55 @@ --- title: "ARM64 exception handling" description: Describes the exception handling conventions and data used by windows on ARM64. -ms.date: "11/19/2018" +ms.date: 01/13/2023 --- # ARM64 exception handling -Windows on ARM64 uses the same structured exception handling mechanism for asynchronous hardware-generated exceptions and synchronous software-generated exceptions. Language-specific exception handlers are built on top of Windows structured exception handling by using language helper functions. This document describes exception handling in Windows on ARM64, and the language helpers used by code that's generated by the Microsoft ARM assembler and the MSVC compiler. +Windows on ARM64 uses the same structured exception handling mechanism for asynchronous hardware-generated exceptions and synchronous software-generated exceptions. Language-specific exception handlers are built on top of Windows structured exception handling by using language helper functions. This document describes exception handling in Windows on ARM64. It illustrates the language helpers used by code that's generated by the Microsoft ARM assembler and the MSVC compiler. ## Goals and motivation The exception unwinding data conventions, and this description, are intended to: -1. Provide enough description to allow unwinding without code probing in all cases. +- Provide enough description to allow unwinding without code probing in all cases. - - Analyzing the code requires the code to be paged in. This prevents unwinding in some circumstances where it's useful (tracing, sampling, debugging). + - Analyzing the code requires the code to be paged in. It prevents unwinding in some circumstances where it's useful (tracing, sampling, debugging). - - Analyzing the code is complex; the compiler must be careful to only generate instructions that the unwinder can decode. + - Analyzing the code is complex; the compiler must be careful to only generate instructions that the unwinder can decode. - - If unwinding can't be fully described through the use of unwind codes, then in some cases it must fall back to instruction decoding. This increases the overall complexity, and ideally should be avoided. + - If unwinding can't be fully described by using unwind codes, then in some cases it must fall back to instruction decoding. Instruction decoding increases the overall complexity, and ideally should be avoided. -1. Support unwinding in mid-prolog and mid-epilog. +- Support unwinding in mid-prolog and mid-epilog. - - Unwinding is used in Windows for more than exception handling. It's critical that code can unwind accurately even when in the middle of a prolog or epilog code sequence. + - Unwinding is used in Windows for more than exception handling. It's critical that code can unwind accurately even when in the middle of a prolog or epilog code sequence. -1. Take up a minimal amount of space. +- Take up a minimal amount of space. - - The unwind codes must not aggregate to significantly increase the binary size. + - The unwind codes must not aggregate to significantly increase the binary size. - - Since the unwind codes are likely to be locked in memory, a small footprint ensures a minimal overhead for each loaded binary. + - Since the unwind codes are likely to be locked in memory, a small footprint ensures a minimal overhead for each loaded binary. ## Assumptions These assumptions are made in the exception handling description: -1. Prologs and epilogs tend to mirror each other. By taking advantage of this common trait, the size of the metadata needed to describe unwinding can be greatly reduced. Within the body of the function, it doesn't matter whether the prolog's operations are undone, or the epilog's operations are done in a forward manner. Both should produce identical results. +- Prologs and epilogs tend to mirror each other. By taking advantage of this common trait, the size of the metadata needed to describe unwinding can be greatly reduced. Within the body of the function, it doesn't matter whether the prolog's operations are undone, or the epilog's operations are done in a forward manner. Both should produce identical results. -1. Functions tend on the whole to be relatively small. Several optimizations for space rely on this fact to achieve the most efficient packing of data. +- Functions tend on the whole to be relatively small. Several optimizations for space rely on this fact to achieve the most efficient packing of data. -1. There's no conditional code in epilogs. +- There's no conditional code in epilogs. -1. Dedicated frame pointer register: If the sp is saved in another register (x29) in the prolog, that register remains untouched throughout the function. It means the original sp may be recovered at any time. +- Dedicated frame pointer register: If the `sp` is saved in another register (`x29`) in the prolog, that register remains untouched throughout the function. It means the original `sp` may be recovered at any time. -1. Unless the sp is saved in another register, all manipulation of the stack pointer occurs strictly within the prolog and epilog. +- Unless the `sp` is saved in another register, all manipulation of the stack pointer occurs strictly within the prolog and epilog. -1. The stack frame layout is organized as described in the next section. +- The stack frame layout is organized as described in the next section. ## ARM64 stack frame layout -![stack frame layout](media/arm64-exception-handling-stack-frame.png "stack frame layout") +![Diagram that shows the stack frame layout for functions.](media/arm64-exception-handling-stack-frame.png "stack frame layout") -For frame chained functions, the fp and lr pair can be saved at any position in the local variable area, depending on optimization considerations. The goal is to maximize the number of locals that can be reached by a single instruction based on the frame pointer (x29) or stack pointer (sp). However, for `alloca` functions, it must be chained, and x29 must point to the bottom of stack. To allow for better register-pair-addressing-mode coverage, nonvolatile register save areas are positioned at the top of the Local area stack. Here are examples that illustrate several of the most efficient prolog sequences. For the sake of clarity and better cache locality, the order of storing callee-saved registers in all canonical prologs is in "growing up" order. `#framesz` below represents the size of entire stack (excluding alloca area). `#localsz` and `#outsz` denote local area size (including the save area for the \ pair) and outgoing parameter size, respectively. +For frame chained functions, the `fp` and `lr` pair can be saved at any position in the local variable area, depending on optimization considerations. The goal is to maximize the number of locals that can be reached by a single instruction based on the frame pointer (`x29`) or stack pointer (`sp`). However, for `alloca` functions, it must be chained, and `x29` must point to the bottom of stack. To allow for better register-pair-addressing-mode coverage, nonvolatile register save areas are positioned at the top of the Local area stack. Here are examples that illustrate several of the most efficient prolog sequences. For the sake of clarity and better cache locality, the order of storing callee-saved registers in all canonical prologs is in "growing up" order. `#framesz` below represents the size of entire stack (excluding `alloca` area). `#localsz` and `#outsz` denote local area size (including the save area for the `` pair) and outgoing parameter size, respectively. 1. Chained, #localsz \<= 512 @@ -59,7 +59,7 @@ For frame chained functions, the fp and lr pair can be saved at any position in stp x0,x1,[sp,#32] // home params (optional) stp x2,x3,[sp,#48] stp x4,x5,[sp,#64] - stp x6,x7,[sp,#72] + stp x6,x7,[sp,#82] stp x29,lr,[sp,#-localsz]! // save at bottom of local area mov x29,sp // x29 points to bottom of local sub sp,sp,#outsz // (optional for #outsz != 0) @@ -73,13 +73,13 @@ For frame chained functions, the fp and lr pair can be saved at any position in stp x0,x1,[sp,#32] // home params (optional) stp x2,x3,[sp,#48] stp x4,x5,[sp,#64] - stp x6,x7,[sp,#72] + stp x6,x7,[sp,#82] sub sp,sp,#(localsz+outsz) // allocate remaining frame stp x29,lr,[sp,#outsz] // save at bottom of local area add x29,sp,#outsz // setup x29 points to bottom of local area ``` -1. Unchained, leaf functions (lr unsaved) +1. Unchained, leaf functions (`lr` unsaved) ```asm stp x19,x20,[sp,#-80]! // pre-indexed, save in 1st FP/INT reg-pair @@ -90,9 +90,9 @@ For frame chained functions, the fp and lr pair can be saved at any position in sub sp,sp,#(framesz-80) // allocate the remaining local area ``` - All locals are accessed based on SP. \ points to the previous frame. For frame size \<= 512, the "sub sp, ..." can be optimized away if the regs saved area is moved to the bottom of stack. The downside is that it's not consistent with other layouts above, and saved regs take part of the range for pair-regs and pre- and post-indexed offset addressing mode. + All locals are accessed based on `sp`. `` points to the previous frame. For frame size \<= 512, the `sub sp, ...` can be optimized away if the regs saved area is moved to the bottom of stack. The downside is that it's not consistent with other layouts above. And, saved regs take part of the range for pair-regs and pre- and post-indexed offset addressing mode. -1. Unchained, non-leaf functions (lr is saved in Int saved area) +1. Unchained, non-leaf functions (saves `lr` in Int saved area) ```asm stp x19,x20,[sp,#-80]! // pre-indexed, save in 1st FP/INT reg-pair @@ -114,7 +114,7 @@ For frame chained functions, the fp and lr pair can be saved at any position in sub sp,sp,#(framesz-80) // allocate the remaining local area ``` - Only x19 saved: + Only `x19` saved: ```asm sub sp,sp,#16 // reg save area allocation* @@ -122,9 +122,9 @@ For frame chained functions, the fp and lr pair can be saved at any position in sub sp,sp,#(framesz-16) // allocate the remaining local area ``` - \* The reg save area allocation isn't folded into the stp because a pre-indexed reg-lr stp can't be represented with the unwind codes. + \* The reg save area allocation isn't folded into the `stp` because a pre-indexed reg-lr `stp` can't be represented with the unwind codes. - All locals are accessed based on SP. \ points to the previous frame. + All locals are accessed based on `sp`. `` points to the previous frame. 1. Chained, #framesz \<= 512, #outsz = 0 @@ -135,9 +135,9 @@ For frame chained functions, the fp and lr pair can be saved at any position in stp d8,d9,[sp,#(framesz-16)] // save FP pair ``` - Compared to the first prolog example above, the advantage here is that all register save instructions are ready to execute after only one stack allocation instruction. That means there's no anti-dependence on sp that prevents instruction level parallelism. + Compared to the first prolog example above, this example has an advantage: all register save instructions are ready to execute after only one stack allocation instruction. That means there's no anti-dependence on `sp` that prevents instruction level parallelism. -1. Chained, frame size > 512 (optional for functions without alloca) +1. Chained, frame size > 512 (optional for functions without `alloca`) ```asm stp x29,lr,[sp,#-80]! // pre-indexed, save @@ -149,7 +149,7 @@ For frame chained functions, the fp and lr pair can be saved at any position in sub sp,sp,#(framesz-80) // allocate the remaining local area ``` - For optimization purpose, x29 can be put at any position in local area to provide a better coverage for "reg-pair" and pre-/post-indexed offset addressing mode. Locals below frame pointers can be accessed based on SP. + For optimization purpose, `x29` can be put at any position in local area to provide a better coverage for "reg-pair" and pre-/post-indexed offset addressing mode. Locals below frame pointers can be accessed based on `sp`. 1. Chained, frame size > 4K, with or without alloca(), @@ -176,41 +176,41 @@ For frame chained functions, the fp and lr pair can be saved at any position in ## ARM64 exception handling information -### .pdata records +### `.pdata` records -The .pdata records are an ordered array of fixed-length items that describe every stack-manipulating function in a PE binary. The phrase "stack-manipulating" is significant: leaf functions that don't require any local storage, and don't need to save/restore non-volatile registers, do not require a .pdata record. These records should be explicitly omitted to save space. An unwind from one of these functions can get the return address directly from LR to move up to the caller. +The `.pdata` records are an ordered array of fixed-length items that describe every stack-manipulating function in a PE binary. The phrase "stack-manipulating" is significant: leaf functions that don't require any local storage, and don't need to save/restore non-volatile registers, don't require a `.pdata` record. These records should be explicitly omitted to save space. An unwind from one of these functions can get the return address directly from `lr` to move up to the caller. -Each .pdata record for ARM64 is 8 bytes in length. The general format of each record places the 32-bit RVA of the function start in the first word, followed by a second word that contains either a pointer to a variable-length .xdata block, or a packed word describing a canonical function unwinding sequence. +Each `.pdata` record for ARM64 is 8 bytes in length. The general format of each record places the 32-bit RVA of the function start in the first word, followed by a second word that contains either a pointer to a variable-length `.xdata` block, or a packed word describing a canonical function unwinding sequence. -![.pdata record layout](media/arm64-exception-handling-pdata-record.png ".pdata record layout") +![.pdata record layout.](media/arm64-exception-handling-pdata-record.png ".pdata record layout") The fields are as follows: - **Function Start RVA** is the 32-bit RVA of the start of the function. -- **Flag** is a 2-bit field that indicates how to interpret the remaining 30 bits of the second .pdata word. If **Flag** is 0, then the remaining bits form an **Exception Information RVA** (with the two lowest bits implicitly 0). If **Flag** is non-zero, then the remaining bits form a **Packed Unwind Data** structure. +- **Flag** is a 2-bit field that indicates how to interpret the remaining 30 bits of the second `.pdata` word. If **Flag** is 0, then the remaining bits form an **Exception Information RVA** (with the two lowest bits implicitly 0). If **Flag** is non-zero, then the remaining bits form a **Packed Unwind Data** structure. -- **Exception Information RVA** is the address of the variable-length exception information structure, stored in the .xdata section. This data must be 4-byte aligned. +- **Exception Information RVA** is the address of the variable-length exception information structure, stored in the `.xdata` section. This data must be 4-byte aligned. -- **Packed Unwind Data** is a compressed description of the operations needed to unwind from a function, assuming a canonical form. In this case, no .xdata record is required. +- **Packed Unwind Data** is a compressed description of the operations needed to unwind from a function, assuming a canonical form. In this case, no `.xdata` record is required. -### .xdata records +### `.xdata` records -When the packed unwind format is insufficient to describe the unwinding of a function, a variable-length .xdata record must be created. The address of this record is stored in the second word of the .pdata record. The format of the .xdata is a packed variable-length set of words: +When the packed unwind format is insufficient to describe the unwinding of a function, a variable-length `.xdata` record must be created. The address of this record is stored in the second word of the `.pdata` record. The format of the `.xdata` is a packed variable-length set of words: -![.xdata record layout](media/arm64-exception-handling-xdata-record.png ".xdata record layout") +![.xdata record layout.](media/arm64-exception-handling-xdata-record.png ".xdata record layout") This data is broken into four sections: -1. A 1 or 2-word header describing the overall size of the structure and providing key function data. The second word is only present if both the **Epilog Count** and **Code Words** fields are set to 0. The header has these bit fields: +1. A 1-word or 2-word header describing the overall size of the structure and providing key function data. The second word is only present if both the **Epilog Count** and **Code Words** fields are set to 0. The header has these bit fields: - a. **Function Length** is an 18-bit field. It indicates the total length of the function in bytes, divided by 4. If a function is larger than 1M, then multiple .pdata and .xdata records must be used to describe the function. For more information, see the [Large functions](#large-functions) section. + a. **Function Length** is an 18-bit field. It indicates the total length of the function in bytes, divided by 4. If a function is larger than 1M, then multiple `.pdata` and `.xdata` records must be used to describe the function. For more information, see the [Large functions](#large-functions) section. - b. **Vers** is a 2-bit field. It describes the version of the remaining .xdata. Currently, only version 0 is defined, so values of 1-3 aren't permitted. + b. **Vers** is a 2-bit field. It describes the version of the remaining `.xdata`. Currently, only version 0 is defined, so values of 1-3 aren't permitted. c. **X** is a 1-bit field. It indicates the presence (1) or absence (0) of exception data. - d. **E** is a 1-bit field. It indicates that information describing a single epilog is packed into the header (1) rather than requiring additional scope words later (0). + d. **E** is a 1-bit field. It indicates that information describing a single epilog is packed into the header (1) rather than requiring more scope words later (0). e. **Epilog Count** is a 5-bit field that has two meanings, depending on the state of **E** bit: @@ -218,11 +218,11 @@ This data is broken into four sections: 2. If **E** is 1, then this field specifies the index of the first unwind code that describes the one and only epilog. - f. **Code Words** is a 5-bit field that specifies the number of 32-bit words needed to contain all of the unwind codes in section 3. If more than 31 words are required (that is, if there are more than 124 unwind code bytes), then this field must be 0 to indicate that an extension word is required. + f. **Code Words** is a 5-bit field that specifies the number of 32-bit words needed to contain all of the unwind codes in section 3. If more than 31 words (that is, 124 unwind codes) are required, then this field must be 0 to indicate that an extension word is required. g. **Extended Epilog Count** and **Extended Code Words** are 16-bit and 8-bit fields, respectively. They provide more space for encoding an unusually large number of epilogs, or an unusually large number of unwind code words. The extension word that contains these fields is only present if both the **Epilog Count** and **Code Words** fields in the first header word are 0. -1. If **Epilog Count** isn't zero, a list of information about epilog scopes, packed one to a word, comes after the header and optional extended header. They're stored in order of increasing starting offset. Each scope contains the following bits: +1. If the count of epilogs isn't zero, a list of information about epilog scopes, packed one to a word, comes after the header and optional extended header. They're stored in order of increasing starting offset. Each scope contains the following bits: a. **Epilog Start Offset** is an 18-bit field that has the offset in bytes, divided by 4, of the epilog relative to the start of the function. @@ -230,11 +230,11 @@ This data is broken into four sections: c. **Epilog Start Index** is a 10-bit field (2 more bits than **Extended Code Words**). It indicates the byte index of the first unwind code that describes this epilog. -1. After the list of epilog scopes comes an array of bytes that contain unwind codes, described in detail in a later section. This array is padded at the end to the nearest full word boundary. Unwind codes are written to this array. They start with the one closest to the body of the function, and move towards the edges of the function. The bytes for each unwind code are stored in big-endian order so they can be fetched directly, starting with the most significant byte first, which identifies the operation and the length of the rest of the code. +1. After the list of epilog scopes comes an array of bytes that contain unwind codes, described in detail in a later section. This array is padded at the end to the nearest full word boundary. Unwind codes are written to this array. They start with the one closest to the body of the function, and move towards the edges of the function. The bytes for each unwind code are stored in big-endian order so the most significant byte gets fetched first, which identifies the operation and the length of the rest of the code. 1. Finally, after the unwind code bytes, if the **X** bit in the header was set to 1, comes the exception handler information. It consists of a single **Exception Handler RVA** that provides the address of the exception handler itself. It's followed immediately by a variable-length amount of data required by the exception handler. -The .xdata record is designed so it's possible to fetch the first 8 bytes, and use them to compute the full size of the record, minus the length of the variable-sized exception data that follows. The following code snippet computes the record size: +The `.xdata` record is designed so it's possible to fetch the first 8 bytes, and use them to compute the full size of the record, minus the length of the variable-sized exception data that follows. The following code snippet computes the record size: ```cpp ULONG ComputeXdataSize(PULONG Xdata) @@ -267,126 +267,147 @@ ULONG ComputeXdataSize(PULONG Xdata) } ``` -Although the prolog and each epilog has its own index into the unwind codes, the table is shared between them. It's entirely possible (and not altogether uncommon) that they can all share the same codes. (For an example, see Example 2 in the [Examples](#examples) section.) Compiler writers should optimize for this case, in particular, because the largest index that can be specified is 255, which limits the total number of unwind codes for a particular function. +Although the prolog and each epilog has its own index into the unwind codes, the table is shared between them. It's entirely possible (and not altogether uncommon) that they can all share the same codes. (For an example, see Example 2 in the [Examples](#examples) section.) Compiler writers should optimize for this case in particular. It's because the largest index that can be specified is 255, which limits the total number of unwind codes for a particular function. ### Unwind codes -The array of unwind codes is pool of sequences that describe exactly how to undo the effects of the prolog, stored in the same order the operations need to be undone. The unwind codes can be thought of as a small instruction set, encoded as a string of bytes. When execution is complete, the return address to the calling function is in the lr register. And, all non-volatile registers are restored to their values at the time the function was called. +The array of unwind codes is a pool of sequences that describe exactly how to undo the effects of the prolog. They're stored in the same order the operations need to be undone. The unwind codes can be thought of as a small instruction set, encoded as a string of bytes. When execution is complete, the return address to the calling function is in the `lr` register. And, all non-volatile registers are restored to their values at the time the function was called. If exceptions were guaranteed to only ever occur within a function body, and never within a prolog or any epilog, then only a single sequence would be necessary. However, the Windows unwinding model requires that code can unwind from within a partially executed prolog or epilog. To meet this requirement, the unwind codes have been carefully designed so they unambiguously map 1:1 to each relevant opcode in the prolog and epilog. This design has several implications: -1. By counting the number of unwind codes, it's possible to compute the length of the prolog and epilog. - -1. By counting the number of instructions past the start of an epilog scope, it's possible to skip the equivalent number of unwind codes. Then we can execute the rest of a sequence to complete the partially executed unwind done by the epilog. - -1. By counting the number of instructions before the end of the prolog, it's possible to skip the equivalent number of unwind codes. Then we can execute the rest of the sequence to undo only those parts of the prolog that have completed execution. - -The unwind codes are encoded according to the table below. All unwind codes are a single/double byte, except the one that allocates a huge stack. Totally there are 21 unwind code. Each unwind code maps exactly one instruction in the prolog/epilog, to allow for unwinding of partially executed prologs and epilogs. - -|Unwind code|Bits and interpretation| -|-|-| -|`alloc_s`|000xxxxx: allocate small stack with size \< 512 (2^5 * 16).| -|`save_r19r20_x`| 001zzzzz: save \ pair at `[sp-#Z*8]!`, pre-indexed offset >= -248 | -|`save_fplr`| 01zzzzzz: save \ pair at `[sp+#Z*8]`, offset \<= 504. | -|`save_fplr_x`| 10zzzzzz: save \ pair at `[sp-(#Z+1)*8]!`, pre-indexed offset >= -512 | -|`alloc_m`| 11000xxx'xxxxxxxx: allocate large stack with size \< 16k (2^11 * 16). | -|`save_regp`| 110010xx'xxzzzzzz: save x(19+#X) pair at `[sp+#Z*8]`, offset \<= 504 | -|`save_regp_x`| 110011xx'xxzzzzzz: save pair x(19+#X) at `[sp-(#Z+1)*8]!`, pre-indexed offset >= -512 | -|`save_reg`| 110100xx'xxzzzzzz: save reg x(19+#X) at `[sp+#Z*8]`, offset \<= 504 | -|`save_reg_x`| 1101010x'xxxzzzzz: save reg x(19+#X) at `[sp-(#Z+1)*8]!`, pre-indexed offset >= -256 | -|`save_lrpair`| 1101011x'xxzzzzzz: save pair \ at `[sp+#Z*8]`, offset \<= 504 | -|`save_fregp`| 1101100x'xxzzzzzz: save pair d(8+#X) at `[sp+#Z*8]`, offset \<= 504 | -|`save_fregp_x`| 1101101x'xxzzzzzz: save pair d(8+#X), at `[sp-(#Z+1)*8]!`, pre-indexed offset >= -512 | -|`save_freg`| 1101110x'xxzzzzzz: save reg d(8+#X) at `[sp+#Z*8]`, offset \<= 504 | -|`save_freg_x`| 11011110'xxxzzzzz: save reg d(8+#X) at `[sp-(#Z+1)*8]!`, pre-indexed offset >= -256 | -|`alloc_l`| 11100000'xxxxxxxx'xxxxxxxx'xxxxxxxx: allocate large stack with size \< 256M (2^24 *16) | -|`set_fp`| 11100001: set up x29: with: `mov x29,sp` | -|`add_fp`| 11100010'xxxxxxxx: set up x29 with: `add x29,sp,#x*8` | -|`nop`| 11100011: no unwind operation is required. | -|`end`| 11100100: end of unwind code. Implies ret in epilog. | -|`end_c`| 11100101: end of unwind code in current chained scope. | -|`save_next`| 11100110: save next non-volatile Int or FP register pair. | -| | 11100111: reserved | -| | 11101xxx: reserved for custom stack cases below only generated for asm routines | -| | 11101000: Custom stack for MSFT_OP_TRAP_FRAME | -| | 11101001: Custom stack for MSFT_OP_MACHINE_FRAME | -| | 11101010: Custom stack for MSFT_OP_CONTEXT | -| | 11101100: Custom stack for MSFT_OP_CLEAR_UNWOUND_TO_CALL | -| | 1111xxxx: reserved | - -In instructions with large values covering multiple bytes, the most significant bits are stored first. This design makes it possible to find the total size in bytes of the unwind code by looking up only the first byte of the code. Since each unwind code is exactly mapped to an instruction in a prolog or epilog, you can compute the size of the prolog or epilog. You can walk from the start of the sequence to the end, and use a lookup table or similar device to determine how long the corresponding opcode is. - -Post-indexed offset addressing isn't allowed in a prolog. All offset ranges (#Z) match the encoding of STP/STR addressing except `save_r19r20_x`, in which 248 is sufficient for all save areas (10 Int registers + 8 FP registers + 8 input registers). - -`save_next` must follow a save for Int or FP volatile register pair: `save_regp`, `save_regp_x`, `save_fregp`, `save_fregp_x`, `save_r19r20_x`, or another `save_next`. It saves the next register pair at the next 16-byte slot in "growing up" order. A `save_next` refers to the first FP register pair when it follows the `save-next` that denotes the last Int register pair. - -Since the size of regular return and jump instructions are the same, there's no need of a separated `end` unwind code for tail-call scenarios. - -`end_c` is designed to handle noncontiguous function fragments for optimization purposes. An `end_c` that indicates the end of unwind codes in the current scope must be followed by another series of unwind code ended with a real `end`. The unwind codes between `end_c` and `end` represent the prolog operations in the parent region ("phantom" prolog). More details and examples are described in the section below. +- By counting the number of unwind codes, it's possible to compute the length of the prolog and epilog. + +- By counting the number of instructions past the start of an epilog scope, it's possible to skip the equivalent number of unwind codes. We can execute the rest of a sequence to complete the partially executed unwind done by the epilog. + +- By counting the number of instructions before the end of the prolog, it's possible to skip the equivalent number of unwind codes. We can execute the rest of the sequence to undo only those parts of the prolog that have completed execution. + +The unwind codes are encoded according to the table below. All unwind codes are a single/double byte, except the one that allocates a huge stack (`alloc_l`). There are 22 unwind codes in total. Each unwind code maps exactly one instruction in the prolog/epilog, to allow for unwinding of partially executed prologs and epilogs. + +| Unwind code | Bits and interpretation | +|--|--| +| `alloc_s` | 000xxxxx: allocate small stack with size \< 512 (2^5 * 16). | +| `save_r19r20_x` | 001zzzzz: save `` pair at `[sp-#Z*8]!`, pre-indexed offset >= -248 | +| `save_fplr` | 01zzzzzz: save `` pair at `[sp+#Z*8]`, offset \<= 504. | +| `save_fplr_x` | 10zzzzzz: save `` pair at `[sp-(#Z+1)*8]!`, pre-indexed offset >= -512 | +| `alloc_m` | 11000xxx'xxxxxxxx: allocate large stack with size \< 32K (2^11 * 16). | +| `save_regp` | 110010xx'xxzzzzzz: save `x(19+#X)` pair at `[sp+#Z*8]`, offset \<= 504 | +| `save_regp_x` | 110011xx'xxzzzzzz: save pair `x(19+#X)` at `[sp-(#Z+1)*8]!`, pre-indexed offset >= -512 | +| `save_reg` | 110100xx'xxzzzzzz: save reg `x(19+#X)` at `[sp+#Z*8]`, offset \<= 504 | +| `save_reg_x` | 1101010x'xxxzzzzz: save reg `x(19+#X)` at `[sp-(#Z+1)*8]!`, pre-indexed offset >= -256 | +| `save_lrpair` | 1101011x'xxzzzzzz: save pair `` at `[sp+#Z*8]`, offset \<= 504 | +| `save_fregp` | 1101100x'xxzzzzzz: save pair `d(8+#X)` at `[sp+#Z*8]`, offset \<= 504 | +| `save_fregp_x` | 1101101x'xxzzzzzz: save pair `d(8+#X)` at `[sp-(#Z+1)*8]!`, pre-indexed offset >= -512 | +| `save_freg` | 1101110x'xxzzzzzz: save reg `d(8+#X)` at `[sp+#Z*8]`, offset \<= 504 | +| `save_freg_x` | 11011110'xxxzzzzz: save reg `d(8+#X)` at `[sp-(#Z+1)*8]!`, pre-indexed offset >= -256 | +| `alloc_z` | 11011111'zzzzzzzz: allocate stack with size `z * SVE-VL` | +| `alloc_l` | 11100000'xxxxxxxx'xxxxxxxx'xxxxxxxx: allocate large stack with size \< 256M (2^24 * 16) | +| `set_fp` | 11100001: set up `x29` with `mov x29,sp` | +| `add_fp` | 11100010'xxxxxxxx: set up `x29` with `add x29,sp,#x*8` | +| `nop` | 11100011: no unwind operation is required. | +| `end` | 11100100: end of unwind code. Implies `ret` in epilog. | +| `end_c` | 11100101: end of unwind code in current chained scope. | +| `save_next` | 11100110: save next register pair. | +| `save_any_xreg` | 11100111'0pxrrrrr'00oooooo: save register(s)
  • `p`: 0/1 => single `X(#r)` vs pair `X(#r)` + `X(#r+1)`
  • `x`: 0/1 => positive vs negative pre-indexed stack offset
  • `o`: offset = `o` * 16, if x=1 or p=1, else `o` * 8
(Windows >= 11 required) | +| `save_any_dreg` | 11100111'0pxrrrrr'01oooooo: save register(s)
  • `p`: 0/1 => single `D(#r)` vs pair `D(#r)` + `D(#r+1)`
  • `x`: 0/1 => positive vs negative pre-indexed stack offset
  • `o`: offset = `o` * 16, if x=1 or p=1, else `o` * 8
(Windows >= 11 required) | +| `save_any_qreg` | 11100111'0pxrrrrr'10oooooo: save register(s)
  • `p`: 0/1 => single `Q(#r)` vs pair `Q(#r)` + `Q(#r+1)`
  • `x`: 0/1 => positive vs negative pre-indexed stack offset
  • `o`: offset = `o` * 16
(Windows >= 11 required) | +| `save_zreg` | 11100111'0oo0rrrr'11oooooo: save reg `Z(#r+8)` at `[sp + #o * VL]`, (`Z8` through `Z23`) +| `save_preg` | 11100111'0oo1rrrr'11oooooo: save reg `P(#r)` at `[sp + #o * (VL / 8)]`, (`P4` through `P15`; `r` values `[0, 3]` are reserved) +| | 11100111'1yyyyyyy': reserved | +| | 11101xxx: reserved for custom stack cases below only generated for asm routines | +| | 11101000: Custom stack for `MSFT_OP_TRAP_FRAME` | +| | 11101001: Custom stack for `MSFT_OP_MACHINE_FRAME` | +| | 11101010: Custom stack for `MSFT_OP_CONTEXT` | +| | 11101011: Custom stack for `MSFT_OP_EC_CONTEXT` | +| | 11101100: Custom stack for `MSFT_OP_CLEAR_UNWOUND_TO_CALL` | +| | 11101101: reserved | +| | 11101110: reserved | +| | 11101111: reserved | +| | 11110xxx: reserved | +| | 11111000'yyyyyyyy : reserved | +| | 11111001'yyyyyyyy'yyyyyyyy : reserved | +| | 11111010'yyyyyyyy'yyyyyyyy'yyyyyyyy : reserved | +| | 11111011'yyyyyyyy'yyyyyyyy'yyyyyyyy'yyyyyyyy : reserved | +| `pac_sign_lr` | 11111100: sign the return address in `lr` with `pacibsp` | +| | 11111101: reserved | +| | 11111110: reserved | +| | 11111111: reserved | + +In instructions with large values covering multiple bytes, the most significant bits are stored first. This design makes it possible to find the total size in bytes of the unwind code by looking up only the first byte of the code. Since each unwind code is exactly mapped to an instruction in a prolog or epilog, you can compute the size of the prolog or epilog. Walk from the sequence start to the end, and use a lookup table or similar device to determine the length of the corresponding opcode. + +Post-indexed offset addressing isn't allowed in a prolog. All offset ranges (#Z) match the encoding of `stp`/`str` addressing except `save_r19r20_x`, in which 248 is sufficient for all save areas (10 Int registers + 8 FP registers + 8 input registers). + +`save_next` must follow a save for a register pair: `save_regp`, `save_regp_x`, `save_fregp`, `save_fregp_x`, `save_r19r20_x`, or another `save_next`. It can also be used in conjunction with `save_any_xreg`, `save_any_dreg` or `save_any_qreg` but only when `p = 1`. It saves the next register pair in numerically increasing order to the next stack space. `save_next` must not be used beyond the last register of the same kind. + +Since the sizes of regular return and jump instructions are the same, there's no need for a separated `end` unwind code in tail-call scenarios. + +`end_c` is designed to handle noncontiguous function fragments for optimization purposes. An `end_c` that indicates the end of unwind codes in the current scope must be followed by another series of unwind codes ending with a real `end`. The unwind codes between `end_c` and `end` represent the prolog operations in the parent region (a "phantom" prolog). More details and examples are described in the section below. ### Packed unwind data -For functions whose prologs and epilogs follow the canonical form described below, packed unwind data can be used. It eliminates the need for an .xdata record entirely, and significantly reduces the cost of providing unwind data. The canonical prologs and epilogs are designed to meet the common requirements of a simple function: One that doesn't require an exception handler, and which does its setup and teardown operations in a standard order. +For functions whose prologs and epilogs follow the canonical form described below, packed unwind data can be used. It eliminates the need for an `.xdata` record entirely, and significantly reduces the cost of providing unwind data. The canonical prologs and epilogs are designed to meet the common requirements of a simple function: One that doesn't require an exception handler, and which does its setup and teardown operations in a standard order. -The format of a .pdata record with packed unwind data looks like this: +The format of a `.pdata` record with packed unwind data looks like this: -![.pdata record with packed unwind data](media/arm64-exception-handling-packed-unwind-data.png ".pdata record with packed unwind data") +![.pdata record with packed unwind data.](media/arm64-exception-handling-packed-unwind-data.png ".pdata record with packed unwind data") The fields are as follows: - **Function Start RVA** is the 32-bit RVA of the start of the function. - **Flag** is a 2-bit field as described above, with the following meanings: - - 00 = packed unwind data not used; remaining bits point to an .xdata record + - 00 = packed unwind data not used; remaining bits point to an `.xdata` record - 01 = packed unwind data used with a single prolog and epilog at the beginning and end of the scope - 10 = packed unwind data used for code without any prolog and epilog. Useful for describing separated function segments - 11 = reserved. -- **Function Length** is an 11-bit field providing the length of the entire function in bytes, divided by 4. If the function is larger than 8k, a full .xdata record must be used instead. -- **Frame Size** is a 9-bit field indicating the number of bytes of stack that is allocated for this function, divided by 16. Functions that allocate greater than (8k-16) bytes of stack must use a full .xdata record. It includes the local variable area, outgoing parameter area, callee-saved Int and FP area, and home parameter area, but excludes the dynamic allocation area. +- **Function Length** is an 11-bit field providing the length of the entire function in bytes, divided by 4. If the function is larger than 8k, a full `.xdata` record must be used instead. +- **Frame Size** is a 9-bit field indicating the number of bytes of stack that is allocated for this function, divided by 16. Functions that allocate greater than (8k-16) bytes of stack must use a full `.xdata` record. It includes the local variable area, outgoing parameter area, callee-saved Int and FP area, and home parameter area. It excludes the dynamic allocation area. - **CR** is a 2-bit flag indicating whether the function includes extra instructions to set up a frame chain and return link: - - 00 = unchained function, \ pair is not saved in stack. - - 01 = unchained function, \ is saved in stack - - 10 = reserved; - - 11 = chained function, a store/load pair instruction is used in prolog/epilog \ -- **H** is a 1-bit flag indicating whether the function homes the integer parameter registers (x0-x7) by storing them at the very start of the function. (0=does not home registers, 1=homes registers). + - 00 = unchained function, `` pair isn't saved in stack + - 01 = unchained function, `` is saved in stack + - 10 = chained function with a `pacibsp` signed return address + - 11 = chained function, a store/load pair instruction is used in prolog/epilog `` +- **H** is a 1-bit flag indicating whether the function homes the integer parameter registers (x0-x7) by storing them at the very start of the function. (0 = doesn't home registers, 1 = homes registers). - **RegI** is a 4-bit field indicating the number of non-volatile INT registers (x19-x28) saved in the canonical stack location. - **RegF** is a 3-bit field indicating the number of non-volatile FP registers (d8-d15) saved in the canonical stack location. (RegF=0: no FP register is saved; RegF>0: RegF+1 FP registers are saved). Packed unwind data can't be used for function that save only one FP register. -Canonical prologs that fall into categories 1, 2 (without outgoing parameter area), 3 and 4 in section above can be represented by packed unwind format. The epilogs for canonical functions follow a similar form, except **H** has no effect, the `set_fp` instruction is omitted, and the order of steps and the instructions in each step are reversed in the epilog. The algorithm for packed .xdata follows these steps, detailed in the following table: +Canonical prologs that fall into categories 1, 2 (without outgoing parameter area), 3 and 4 in section above can be represented by packed unwind format. The epilogs for canonical functions follow a similar form, except **H** has no effect, the `set_fp` instruction is omitted, and the order of steps and the instructions in each step are reversed in the epilog. The algorithm for packed `.xdata` follows these steps, detailed in the following table: Step 0: Pre-compute of the size of each area. -Step 1: Save Int callee-saved registers. +Step 1: Sign the return address. -Step 2: This step is specific for type 4 in early sections. lr is saved at the end of Int area. +Step 2: Save Int callee-saved registers. -Step 3: Save FP callee-saved registers. +Step 3: This step is specific for type 4 in early sections. `lr` is saved at the end of Int area. -Step 4: Save input arguments in the home parameter area. +Step 4: Save FP callee-saved registers. -Step 5: Allocate remaining stack, including local area, \ pair, and outgoing parameter area. 5a corresponds to canonical type 1. 5b and 5c are for canonical type 2. 5d and 5e are for both type 3 and type 4. +Step 5: Save input arguments in the home parameter area. -Step #|Flag values|# of instructions|Opcode|Unwind Code --|-|-|-|- -0|||`#intsz = RegI * 8;`
`if (CR==01) #intsz += 8; // lr`
`#fpsz = RegF * 8;`
`if(RegF) #fpsz += 8;`
`#savsz=((#intsz+#fpsz+8*8*H)+0xf)&~0xf)`
`#locsz = #famsz - #savsz`| -1|0 < **RegI** <= 10|RegI / 2 + **RegI** % 2|`stp x19,x20,[sp,#savsz]!`
`stp x21,x22,[sp,#16]`
`...`|`save_regp_x`
`save_regp`
`...` -2|**CR**==01*|1|`str lr,[sp,#(intsz-8)]`\*|`save_reg` -3|0 < **RegF** <=7|(RegF + 1) / 2 +
(RegF + 1) % 2)|`stp d8,d9,[sp,#intsz]`\*\*
`stp d10,d11,[sp,#(intsz+16)]`
`...`
`str d(8+RegF),[sp,#(intsz+fpsz-8)]`|`save_fregp`
`...`
`save_freg` -4|**H** == 1|4|`stp x0,x1,[sp,#(intsz+fpsz)]`
`stp x2,x3,[sp,#(intsz+fpsz+16)]`
`stp x4,x5,[sp,#(intsz+fpsz+32)]`
`stp x6,x7,[sp,#(intsz+fpsz+48)]`|`nop`
`nop`
`nop`
`nop` -5a|**CR** == 11 && #locsz
<= 512|2|`stp x29,lr,[sp,#-locsz]!`
`mov x29,sp`\*\*\*|`save_fplr_x`
`set_fp` -5b|**CR** == 11 &&
512 < #locsz <= 4080|3|`sub sp,sp,#locsz`
`stp x29,lr,[sp,0]`
`add x29,sp,0`|`alloc_m`
`save_fplr`
`set_fp` -5c|**CR** == 11 && #locsz > 4080|4|`sub sp,sp,4080`
`sub sp,sp,#(locsz-4080)`
`stp x29,lr,[sp,0]`
`add x29,sp,0`|`alloc_m`
`alloc_s`/`alloc_m`
`save_fplr`
`set_fp` -5d|(**CR** == 00 \|\| **CR**==01) &&
#locsz <= 4080|1|`sub sp,sp,#locsz`|`alloc_s`/`alloc_m` -5e|(**CR** == 00 \|\| **CR**==01) &&
#locsz > 4080|2|`sub sp,sp,4080`
`sub sp,sp,#(locsz-4080)`|`alloc_m`
`alloc_s`/`alloc_m` +Step 6: Allocate remaining stack, including local area, `` pair, and outgoing parameter area. 6a corresponds to canonical type 1. 6b and 6c are for canonical type 2. 6d and 6e are for both type 3 and type 4. -\* If **CR** == 01 and **RegI** is an odd number, Step 2 and last save_rep in step 1 are merged into one save_regp. +| Step # | Flag values | # of instructions | Opcode | Unwind code | +|--|--|--|--|--| +| 0 | | | `#intsz = RegI * 8;`
`if (CR==01) #intsz += 8; // lr`
`#fpsz = RegF * 8;`
`if(RegF) #fpsz += 8;`
`#savsz=((#intsz+#fpsz+8*8*H)+0xf)&~0xf)`
`#locsz = #famsz - #savsz` | +| 1 | **CR** == 10 | 1 | `pacibsp` | `pac_sign_lr` | +| 2 | 0 < **RegI** <= 10 | **RegI** / 2 +
**RegI** % 2 | `stp x19,x20,[sp,#savsz]!`
`stp x21,x22,[sp,#16]`
`...` | `save_regp_x`
`save_regp`
`...` | +| 3 | **CR** == 01\* | 1 | `str lr,[sp,#(intsz-8)]`\* | `save_reg` | +| 4 | 0 < **RegF** <= 7 | (**RegF** + 1) / 2 +
(**RegF** + 1) % 2) | `stp d8,d9,[sp,#intsz]`\*\*
`stp d10,d11,[sp,#(intsz+16)]`
`...`
`str d(8+RegF),[sp,#(intsz+fpsz-8)]` | `save_fregp`
`...`
`save_freg` | +| 5 | **H** == 1 | 4 | `stp x0,x1,[sp,#(intsz+fpsz)]`
`stp x2,x3,[sp,#(intsz+fpsz+16)]`
`stp x4,x5,[sp,#(intsz+fpsz+32)]`
`stp x6,x7,[sp,#(intsz+fpsz+48)]` | `nop`
`nop`
`nop`
`nop` | +| 6a | (**CR** == 10 \|\| **CR** == 11) &&
`#locsz` <= 512 | 2 | `stp x29,lr,[sp,#-locsz]!`
`mov x29,sp`\*\*\* | `save_fplr_x`
`set_fp` | +| 6b | (**CR** == 10 \|\| **CR** == 11) &&
512 < `#locsz` <= 4080 | 3 | `sub sp,sp,#locsz`
`stp x29,lr,[sp,0]`
`add x29,sp,0` | `alloc_m`
`save_fplr`
`set_fp` | +| 6c | (**CR** == 10 \|\| **CR** == 11) &&
`#locsz` > 4080 | 4 | `sub sp,sp,4080`
`sub sp,sp,#(locsz-4080)`
`stp x29,lr,[sp,0]`
`add x29,sp,0` | `alloc_m`
`alloc_s`/`alloc_m`
`save_fplr`
`set_fp` | +| 6d | (**CR** == 00 \|\| **CR** == 01) &&
`#locsz` <= 4080 | 1 | `sub sp,sp,#locsz` | `alloc_s`/`alloc_m` | +| 6e | (**CR** == 00 \|\| **CR** == 01) &&
`#locsz` > 4080 | 2 | `sub sp,sp,4080`
`sub sp,sp,#(locsz-4080)` | `alloc_m`
`alloc_s`/`alloc_m` | -\*\* If **RegI** == **CR** == 0, and **RegF** != 0, the first stp for the floating-point does the predecrement. +\* If **CR** == 01 and **RegI** is an odd number, step 3 and the last `save_reg` in step 2 are merged into one `save_regp`. -\*\*\* No instruction corresponding to `mov x29,sp` is present in the epilog. Packed unwind data can't be used if a function requires restoration of sp from x29. +\*\* If **RegI** == **CR** == 0, and **RegF** != 0, the first `stp` for the floating-point does the predecrement. + +\*\*\* No instruction corresponding to `mov x29,sp` is present in the epilog. Packed unwind data can't be used if a function requires restoration of `sp` from `x29`. ### Unwinding partial prologs and epilogs -The most common unwinding situation is one where the exception or call occurred in the body of the function, away from the prolog and all epilogs. In this situation, unwinding is straightforward: the unwinder simply begins executing the codes in the unwind array beginning at index 0 and continuing until an end opcode is detected. +In the most common unwinding situations, the exception or call occurs in the body of the function, away from the prolog and all epilogs. In these situations, unwinding is straightforward: the unwinder simply executes the codes in the unwind array. It begins at index 0 and continues until an `end` opcode is detected. It's more difficult to correctly unwind in the case where an exception or interrupt occurs while executing a prolog or epilog. In these situations, the stack frame is only partially constructed. The problem is to determine exactly what's been done, to correctly undo it. @@ -405,19 +426,19 @@ For example, take this prolog and epilog sequence: 0110: ret lr // end ``` -Next to each opcode is the appropriate unwind code describing this operation. You can see how the series of unwind codes for the prolog is an exact mirror image of the unwind codes for the epilog (not counting the final instruction of the epilog). It's a common situation, and it's why we always assume the unwind codes for the prolog are stored in reverse order from the prolog's execution order. +Next to each opcode is the appropriate unwind code describing this operation. You can see how the series of unwind codes for the prolog is an exact mirror image of the unwind codes for the epilog (not counting the final instruction of the epilog). It's a common situation: It's why we always assume the unwind codes for the prolog are stored in reverse order from the prolog's execution order. So, for both the prolog and epilog, we're left with a common set of unwind codes: `set_fp`, `save_regp 0,240`, `save_fregp,0,224`, `save_fplr_x_256`, `end` -The epilog case is straightforward, since it's in normal order. Starting at offset 0 within the epilog (which starts at offset 0x100 in the function), we'd expect to execute the full unwind sequence, as no cleanup has yet been done. If we find ourselves one instruction in (at offset 2 in the epilog), we can successfully unwind by skipping the first unwind code. We can generalize this situation, and assume a 1:1 mapping between opcodes and unwind codes. Then, to start unwinding from instruction *n* in the epilog, we should skip the first *n* unwind codes, and begin executing from there. +The epilog case is straightforward, since it's in normal order. Starting at offset 0 within the epilog (which starts at offset 0x100 in the function), we'd expect the full unwind sequence to execute, as no cleanup has yet been done. If we find ourselves one instruction in (at offset 2 in the epilog), we can successfully unwind by skipping the first unwind code. We can generalize this situation, and assume a 1:1 mapping between opcodes and unwind codes. Then, to start unwinding from instruction *n* in the epilog, we should skip the first *n* unwind codes, and begin executing from there. -It turns out that a similar logic works for the prolog, except in reverse. If we start unwinding from offset 0 in the prolog, we want to execute nothing. If we unwind from offset 2, which is one instruction in, then we want to start executing the unwind sequence one unwind code from the end. (Remember, the codes are stored in reverse order.) And here too, we can generalize: if we start unwinding from instruction n in the prolog, we should start executing n unwind codes from the end of the list of codes. +It turns out that a similar logic works for the prolog, except in reverse. If we start unwinding from offset 0 in the prolog, we want to execute nothing. If we unwind from offset 2, which is one instruction in, then we want to start executing the unwind sequence one unwind code from the end. (Remember, the codes are stored in reverse order.) And here too, we can generalize: if we start unwinding from instruction *n* in the prolog, we should start executing *n* unwind codes from the end of the list of codes. -It's not always the case that the prolog and epilog codes match exactly. That's why the unwind array may need to contain several sequences of codes. To determine the offset of where to begin processing codes, use the following logic: +Prolog and epilog codes don't always match exactly, which is why the unwind array may need to contain several sequences of codes. To determine the offset of where to begin processing codes, use the following logic: -1. If unwinding from within the body of the function, begin executing unwind codes at index 0 and continue until hitting an "end" opcode. +1. If unwinding from within the body of the function, begin executing unwind codes at index 0 and continue until hitting an `end` opcode. 1. If unwinding from within an epilog, use the epilog-specific starting index provided with the epilog scope as a starting point. Compute how many bytes the PC in question is from the start of the epilog. Then advance forward through the unwind codes, skipping unwind codes until all of the already-executed instructions are accounted for. Then execute starting at that point. @@ -427,11 +448,11 @@ These rules mean the unwind codes for the prolog must always be the first in the ### Function fragments -For code optimization purposes and other reasons, it may be preferable to split a function into separated fragments (also called regions). When split, each resulting function fragment requires its own separate .pdata (and possibly .xdata) record. +For code optimization purposes and other reasons, it may be preferable to split a function into separated fragments (also called *regions*). When split, each resulting function fragment requires its own separate `.pdata` (and possibly `.xdata`) record. -For each separated secondary fragment that has its own prolog, it's expected that no stack adjustment is done in its prolog. All stack space required by a secondary region must be pre-allocated by its parent region (or called host region). This keeps stack pointer manipulation strictly in the function's original prolog. +For each separated secondary fragment that has its own prolog, it's expected that no stack adjustment is done in its prolog. All stack space required by a secondary region must be pre-allocated by its parent region (or called host region). This preallocation keeps stack pointer manipulation strictly in the function's original prolog. -A typical case of function fragments is "code separation" with that compiler may move a region of code out of its host function. There are three unusual cases that could be resulted by code separation. +A typical case of function fragments is "code separation", where the compiler may move a region of code out of its host function. There are three unusual cases that could result from code separation. #### Example @@ -468,19 +489,19 @@ A typical case of function fragments is "code separation" with that compiler may 1. Prolog only (region 1: all epilogs are in separated regions): - Only the prolog must be described. This can't be represented in the compact .pdata format. In the full .xdata case, it can be represented by setting Epilog Count = 0. See region 1 in the example above. + Only the prolog must be described. This prolog can't be represented in the compact `.pdata` format. In the full `.xdata` case, it can be represented by setting Epilog Count = 0. See region 1 in the example above. Unwind codes: `set_fp`, `save_regp 0,240`, `save_fplr_x_256`, `end`. 1. Epilogs only (region 2: prolog is in host region) - It's assumed that by the time control jumping into this region, all prolog codes have been executed. Partial unwind can happen in epilogs the same way as in a normal function. This type of region can't be represented by compact .pdata. In full .xdata record, it can be encoded with a "phantom" prolog, bracketed by an `end_c` and `end` unwind code pair. The leading `end_c` indicates the size of prolog is zero. Epilog start index of the single epilog points to `set_fp`. + It's assumed that by the time control jumps into this region, all prolog codes have been executed. Partial unwind can happen in epilogs the same way as in a normal function. This type of region can't be represented by compact `.pdata`. In a full `.xdata` record, it can be encoded with a "phantom" prolog, bracketed by an `end_c` and `end` unwind code pair. The leading `end_c` indicates the size of prolog is zero. Epilog start index of the single epilog points to `set_fp`. Unwind code for region 2: `end_c`, `set_fp`, `save_regp 0,240`, `save_fplr_x_256`, `end`. 1. No prologs or epilogs (region 3: prologs and all epilogs are in other fragments): - Compact .pdata format can be applied via setting Flag = 10. With full .xdata record, Epilog Count = 1. Unwind code is the same as the code for region 2 above, but Epilog Start Index also points to `end_c`. Partial unwind will never happen in this region of code. + Compact `.pdata` format can be applied via setting Flag = 10. With full `.xdata` record, Epilog Count = 1. Unwind code is the same as the code for region 2 above, but Epilog Start Index also points to `end_c`. Partial unwind will never happen in this region of code. Another more complicated case of function fragments is "shrink wrapping." The compiler may choose to delay saving some callee-saved registers until outside of the function entry prolog. @@ -515,17 +536,17 @@ Another more complicated case of function fragments is "shrink wrapping." The co In the prolog of region 1, stack space is pre-allocated. You can see that region 2 will have the same unwind code even it's moved out of its host function. -Region 1: `set_fp`, `save_regp 0,240`, `save_fplr_x_256`, `end` with Epilog Start Index points to `set_fp` as usual. +Region 1: `set_fp`, `save_regp 0,240`, `save_fplr_x_256`, `end`. Epilog Start Index points to `set_fp` as usual. Region 2: `save_regp 2, 224`, `end_c`, `set_fp`, `save_regp 0,240`, `save_fplr_x_256`, `end`. Epilog Start Index points to first unwind code `save_regp 2, 224`. ### Large functions -Fragments can be used to describe functions larger than the 1M limit imposed by the bit fields in the .xdata header. To describe a very large function like this, it needs to be broken into fragments smaller than 1M. Each fragment should be adjusted so that it doesn't split an epilog into multiple pieces. +Fragments can be used to describe functions larger than the 1M limit imposed by the bit fields in the `.xdata` header. To describe an unusually large function like this, it needs to be broken into fragments smaller than 1M. Each fragment should be adjusted so that it doesn't split an epilog into multiple pieces. Only the first fragment of the function will contain a prolog; all other fragments are marked as having no prolog. Depending on the number of epilogs present, each fragment may contain zero or more epilogs. Keep in mind that each epilog scope in a fragment specifies its starting offset relative to the start of the fragment, not the start of the function. -If a fragment has no prolog and no epilog, it still requires its own .pdata (and possibly .xdata) record, to describe how to unwind from within the body of the function. +If a fragment has no prolog and no epilog, it still requires its own `.pdata` (and possibly `.xdata`) record, to describe how to unwind from within the body of the function. ## Examples @@ -538,7 +559,7 @@ If a fragment has no prolog and no epilog, it still requires its own .pdata (and sub sp,sp,#0x810 // alloc_m stp fp,lr,[sp] // save_fplr mov fp,sp // set_fp - // end of prolog + // end of prolog ... |$pdata$Foo| @@ -624,5 +645,5 @@ Epilog Start Index [4] points to the middle of Prolog unwind code (partially reu ## See also -[Overview of ARM64 ABI conventions](arm64-windows-abi-conventions.md)
-[ARM Exception Handling](arm-exception-handling.md) +[Overview of ARM64 ABI conventions](arm64-windows-abi-conventions.md)\ +[ARM exception handling](arm-exception-handling.md) diff --git a/docs/build/arm64-windows-abi-conventions.md b/docs/build/arm64-windows-abi-conventions.md index 0418d8cff3..db01bfefe2 100644 --- a/docs/build/arm64-windows-abi-conventions.md +++ b/docs/build/arm64-windows-abi-conventions.md @@ -1,15 +1,15 @@ --- description: "Learn more about: Overview of ARM64 ABI conventions" title: "Overview of ARM64 ABI conventions" -ms.date: "03/27/2019" +ms.date: 04/08/2025 --- # Overview of ARM64 ABI conventions -The basic application binary interface (ABI) for Windows when compiled and run on ARM processors in 64-bit mode (ARMv8 or later architectures), for the most part, follows ARM's standard AArch64 EABI. This article highlights some of the key assumptions and changes from what is documented in the EABI. For information about the 32-bit ABI, see [Overview of ARM ABI conventions](overview-of-arm-abi-conventions.md). For more information about the standard ARM EABI, see [Application Binary Interface (ABI) for the ARM Architecture](http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.subset.swdev.abi/index.html) (external link). +The basic application binary interface (ABI) for Windows when compiled and run on ARM processors in 64-bit mode (ARMv8 or later architectures), usually follows ARM's standard AArch64 EABI. This article highlights some of the key assumptions and changes from what is documented in the EABI. For information about the 32-bit ABI, see [Overview of ARM ABI conventions](overview-of-arm-abi-conventions.md). For more information about the standard ARM EABI, see [Application Binary Interface (ABI) for the ARM Architecture](https://github.com/ARM-software/abi-aa) (external link). ## Definitions -With the introduction of 64-bit support, ARM has defined several terms: +With the introduction of 64-bit support, ARM defined several terms: - **AArch32** – the legacy 32-bit instruction set architecture (ISA) defined by ARM, including Thumb mode execution. - **AArch64** – the new 64-bit instruction set architecture (ISA) defined by ARM. @@ -19,8 +19,9 @@ With the introduction of 64-bit support, ARM has defined several terms: Windows also uses these terms: - **ARM** – refers to the 32-bit ARM architecture (AArch32), sometimes referred to as WoA (Windows on ARM). -- **ARM32** – same as ARM, above; used in this document for clarity. +- **ARM32** – same as **ARM**. Used in this document for clarity. - **ARM64** – refers to the 64-bit ARM architecture (AArch64). There's no such thing as WoA64. +- **ARM64EC** - code built as ARM64EC can interoperate with x64 code running under emulation in the same process. The Arm64EC code in the process runs with native performance, while the x64 code runs using emulation. Finally, when referring to data types, the following definitions from ARM are referenced: @@ -30,7 +31,7 @@ Finally, when referring to data types, the following definitions from ARM are re ## Base requirements -The ARM64 version of Windows presupposes that it's running on an ARMv8 or later architecture at all times. Both floating-point and NEON support are presumed to be present in hardware. +The ARM64 version of Windows always presupposes that it's running on an ARMv8 or later architecture. Both floating-point and NEON support are presumed to be present in hardware. The ARMv8 specification describes new optional crypto and CRC helper opcodes for both AArch32 and AArch64. Support for them is currently optional, but recommended. To take advantage of these opcodes, apps should first make runtime checks for their existence. @@ -66,16 +67,15 @@ Default layout alignment for globals and statics: The AArch64 architecture supports 32 integer registers: -| Register | Volatile? | Role | +| Register | Volatility | Role | | - | - | - | -| x0 | Volatile | Parameter/scratch register 1, result register | -| x1-x7 | Volatile | Parameter/scratch register 2-8 | -| x8-x15 | Volatile | Scratch registers | +| x0-x8 | Volatile | Parameter/Result scratch registers | +| x9-x15 | Volatile | Scratch registers | | x16-x17 | Volatile | Intra-procedure-call scratch registers | -| x18 | Non-volatile | Platform register: in kernel mode, points to KPCR for the current processor; in user mode, points to TEB | +| x18 | N/A | Reserved platform register: in kernel mode, points to KPCR for the current processor; In user mode, points to TEB | | x19-x28 | Non-volatile | Scratch registers | | x29/fp | Non-volatile | Frame pointer | -| x30/lr | Non-volatile | Link registers | +| x30/lr | Both | Link Register: Callee function must preserve it for its own return, but caller's value is lost. | Each register may be accessed as a full 64-bit value (via x0-x30) or as a 32-bit value (via w0-w30). 32-bit operations zero-extend their results up to 64 bits. @@ -87,20 +87,19 @@ The frame pointer (x29) is required for compatibility with fast stack walking us ## Floating-point/SIMD registers -The AArch64 architecture also supports 32 floating-point/SIMD registers, summarized below: +The AArch64 architecture also supports these 32 floating-point/SIMD registers: -| Register | Volatile? | Role | +| Register | Volatility | Role | | - | - | - | -| v0 | Volatile | Parameter/scratch register 1, result register | -| v1-v7 | Volatile | Parameter/scratch registers 2-8 | -| v8-v15 | Non-volatile | Scratch registers (only the low 64 bits are non-volatile) | +| v0-v7 | Volatile | Parameter/Result scratch registers | +| v8-v15 | Both | Low 64 bits are Non-Volatile. High 64 bits are Volatile. | | v16-v31 | Volatile | Scratch registers | Each register may be accessed as a full 128-bit value (via v0-v31 or q0-q31). It may be accessed as a 64-bit value (via d0-d31), as a 32-bit value (via s0-s31), as a 16-bit value (via h0-h31), or as an 8-bit value (via b0-b31). Accesses smaller than 128 bits only access the lower bits of the full 128-bit register. They leave the remaining bits untouched unless otherwise specified. (AArch64 is different from AArch32, where the smaller registers were packed on top of the larger registers.) The floating-point control register (FPCR) has certain requirements on the various bitfields within it: -| Bits | Meaning | Volatile? | Role | +| Bits | Meaning | Volatility | Role | | - | - | - | - | | 26 | AHP | Non-Volatile | Alternative half-precision control. | | 25 | DN | Non-Volatile | Default NaN mode control. | @@ -120,7 +119,11 @@ Like AArch32, the AArch64 specification provides three system-controlled "thread ## Floating-point exceptions -Support for IEEE floating-point exceptions is optional on AArch64 systems. For processor variants that do have hardware floating-point exceptions, the Windows kernel silently catches the exceptions and implicitly disables them in the FPCR register. This trap ensures normalized behavior across processor variants. Otherwise, code developed on a platform without exception support may find itself taking unexpected exceptions when running on a platform with support. +To determine if an ARM CPU supports exceptions, write a value that enables exceptions to the FPCR register and then read it back. If the CPU supports floating-point exceptions, the bits corresponding to supported exceptions remain set, while the CPU resets the bits for unsupported exceptions. + +On ARM64, Windows delivers exceptions for processors that support hardware floating-point exceptions. + +The [`_set_controlfp`](/cpp/c-runtime-library/reference/controlfp-s) function on ARM platforms correctly changes the FPCR register when unmasking floating-point exceptions. However, instead of raising an unmasked exception, Windows resets the FPCR register to its defaults every time an FP exception is about to be raised. ## Parameter passing @@ -150,7 +153,7 @@ For each argument in the list, the first matching rule from the following list i ### Stage C – Assignment of arguments to registers and stack -For each argument in the list, the following rules are applied in turn until the argument has been allocated. When an argument is assigned to a register, any unused bits in the register have unspecified value. If an argument is assigned to a stack slot, any unused padding bytes have unspecified value. +For each argument in the list, the following rules are applied in turn until the argument is allocated. When an argument is assigned to a register, any unused bits in the register have unspecified value. If an argument is assigned to a stack slot, any unused padding bytes have unspecified value. 1. If the argument is a Half-, Single-, Double- or Quad-precision Floating-point or Short Vector Type, and the NSRN is less than 8, then the argument is allocated to the least significant bits of register v\[NSRN]. The NSRN is incremented by one. The argument has now been allocated. @@ -160,7 +163,7 @@ For each argument in the list, the following rules are applied in turn until the 1. If the argument is an HFA, an HVA, a Quad-precision Floating-point or Short Vector Type, then the NSAA is rounded up to the larger of 8 or the Natural Alignment of the argument's type. -1. If the argument is a Half- or Single-precision Floating Point type, then the size of the argument is set to 8 bytes. The effect is as if the argument had been copied to the least significant bits of a 64-bit register, and the remaining bits filled with unspecified values. +1. If the argument is a Half- or Single-precision Floating Point type, then the size of the argument is set to 8 bytes. The effect is as if the argument were copied to the least significant bits of a 64-bit register, and the remaining bits filled with unspecified values. 1. If the argument is an HFA, an HVA, a Half-, Single-, Double-, or Quad-precision Floating-point or Short Vector Type, then the argument is copied to memory at the adjusted NSAA. The NSAA is incremented by the size of the argument. The argument has now been allocated. @@ -201,10 +204,10 @@ Floating-point values are returned in s0, d0, or v0, as appropriate. A type is considered to be an HFA or HVA if all of the following hold: - It's non-empty, -- It doesn't have any non-trivial default or copy constructors, destructors, or assignment operators, +- It doesn't have any nontrivial default or copy constructors, destructors, or assignment operators, - All of its members have the same HFA or HVA type, or are float, double, or neon types that match the other members' HFA or HVA types. -HFA and HVA values with four or fewer elements are returned in s0-s3, d0-d3, or v0-v3, as appropriate. +HVA values with four or fewer elements are returned in s0-s3, d0-d3, or v0-v3, as appropriate. Types returned by value are handled differently depending on whether they have certain properties, and whether the function is a non-static member function. Types which have all of these properties, @@ -212,11 +215,12 @@ Types returned by value are handled differently depending on whether they have c - they have a trivial copy-assignment operator, and - they have a trivial destructor, -and are returned by non-member functions or static member functions, use the following return style: +and are returned by nonmember functions or static member functions, use the following return style: +- Types that are HFAs with four or fewer elements are returned in s0-s3, d0-d3, or v0-v3, as appropriate. - Types less than or equal to 8 bytes are returned in x0. - Types less than or equal to 16 bytes are returned in x0 and x1, with x0 containing the lower-order 8 bytes. -- For types greater than 16 bytes, the caller shall reserve a block of memory of sufficient size and alignment to hold the result. The address of the memory block shall be passed as an additional argument to the function in x8. The callee may modify the result memory block at any point during the execution of the subroutine. The callee isn't required to preserve the value stored in x8. +- For other aggregate types, the caller shall reserve a block of memory of sufficient size and alignment to hold the result. The address of the memory block shall be passed as another argument to the function in x8. The callee may modify the result memory block at any point during the execution of the subroutine. The callee isn't required to preserve the value stored in x8. All other types use this convention: @@ -224,9 +228,9 @@ All other types use this convention: ## Stack -Following the ABI put forth by ARM, the stack must remain 16-byte aligned at all times. AArch64 contains a hardware feature that generates stack alignment faults whenever the SP isn't 16-byte aligned and an SP-relative load or store is done. Windows runs with this feature enabled at all times. +Following the ABI put forth by ARM, the stack must always remain 16-byte aligned. AArch64 contains a hardware feature that generates stack alignment faults whenever the SP isn't 16-byte aligned and an SP-relative load or store is done. Windows always runs with this feature enabled. -Functions that allocate 4k or more worth of stack must ensure that each page prior to the final page is touched in order. This action ensures no code can "leap over" the guard pages that Windows uses to expand the stack. Typically the touching is done by the `__chkstk` helper, which has a custom calling convention that passes the total stack allocation divided by 16 in x15. +Functions that allocate 4k or more worth of stack must ensure that each page before the final page is touched in order. This action ensures no code can "leap over" the guard pages that Windows uses to expand the stack. Typically the touching is done by the `__chkstk` helper, which has a custom calling convention that passes the total stack allocation divided by 16 in x15. ## Red zone @@ -242,7 +246,7 @@ Code within Windows is compiled with frame pointers enabled ([/Oy-](reference/oy ## Exception unwinding -Unwinding during exception handling is assisted through the use of unwind codes. The unwind codes are a sequence of bytes stored in the .xdata section of the executable. They describe the operation of the prologue and epilogue in an abstract manner, such that the effects of a function's prologue can be undone in preparation for backing up to the caller's stack frame. For more information on the unwind codes, see [ARM64 exception handling](arm64-exception-handling.md). +Unwinding during exception handling is assisted by using unwind codes. The unwind codes are a sequence of bytes stored in the .xdata section of the executable. They describe the operation of the prologue and epilogue in an abstract manner, such that the effects of a function's prologue can be undone in preparation for backing up to the caller's stack frame. For more information on the unwind codes, see [ARM64 exception handling](arm64-exception-handling.md). The ARM EABI also specifies an exception unwinding model that uses unwind codes. However, the specification as presented is insufficient for unwinding in Windows, which must handle cases where the PC is in the middle of a function prologue or epilogue. @@ -252,7 +256,7 @@ Code that is dynamically generated should be described with dynamic function tab All ARMv8 CPUs are required to support a cycle counter register, a 64-bit register that Windows configures to be readable at any exception level, including user mode. It can be accessed via the special PMCCNTR_EL0 register, using the MSR opcode in assembly code, or the `_ReadStatusReg` intrinsic in C/C++ code. -The cycle counter here is a true cycle counter, not a wall clock. The counting frequency will vary with the processor frequency. If you feel you must know the frequency of the cycle counter, you shouldn't be using the cycle counter. Instead, you want to measure wall clock time, for which you should use `QueryPerformanceCounter`. +The cycle counter here is a true cycle counter, not a wall clock. The counting frequency varies with the processor frequency. If you feel you must know the frequency of the cycle counter, you shouldn't be using the cycle counter. Instead, you want to measure wall clock time, for which you should use `QueryPerformanceCounter`. ## See also diff --git a/docs/build/arm64ec-windows-abi-conventions.md b/docs/build/arm64ec-windows-abi-conventions.md new file mode 100644 index 0000000000..9c78bc39f5 --- /dev/null +++ b/docs/build/arm64ec-windows-abi-conventions.md @@ -0,0 +1,192 @@ +--- +title: "Overview of ARM64EC ABI conventions" +description: "Learn more about: Overview of ARM64EC ABI conventions" +ms.date: "06/03/2022" +--- +# Overview of ARM64EC ABI conventions + +ARM64EC is an application binary interface (ABI) that enables ARM64 binaries to run natively and interoperably with x64 code. Specifically, the ARM64EC ABI follows x64 software conventions including calling convention, stack usage, and data alignment, making ARM64EC and x64 code interoperable. The operating system emulates the x64 portion of the binary. (The EC in ARM64EC stands for *emulation compatible*.) + +For more information on the x64 and ARM64 ABIs, see [Overview of x64 ABI conventions](x64-software-conventions.md) and [Overview of ARM64 ABI conventions](arm64-windows-abi-conventions.md). + +ARM64EC doesn't solve memory model differences between x64 and ARM based architectures. For more information, see [Common Visual C++ ARM migration issues](common-visual-cpp-arm-migration-issues.md). + +## Definitions + +- **ARM64** - The code stream for ARM64 processes that contains traditional ARM64 code. +- **ARM64EC** - The code stream that utilizes a subset of the ARM64 register set to provide interoperability with x64 code. + +## Register mapping + +x64 processes may have threads running ARM64EC code. So it's always possible to retrieve an x64 register context, ARM64EC uses a subset of the ARM64 core registers that map 1:1 to emulated x64 registers. Importantly, ARM64EC never uses registers outside of this subset, except to read the Thread Environment Block (TEB) address from `x18`. + +Native ARM64 processes shouldn't regress in performance when some or many functions are recompiled as ARM64EC. To maintain performance, the ABI follows these principles: + +- The ARM64EC register subset includes all registers that are part of the ARM64 function calling convention. + +- The ARM64EC calling convention directly maps to the ARM64 calling convention. + +Special helper routines like `__chkstk_arm64ec` use custom calling conventions and registers. These registers are also included in the ARM64EC subset of registers. + +## Register mapping for integer registers + +| ARM64EC register | x64 register | ARM64EC calling convention | ARM64 calling convention | x64 calling convention | +|--|--|--|--|--| +| `x0` | `rcx` | volatile | volatile | volatile | +| `x1` | `rdx` | volatile | volatile | volatile | +| `x2` | `r8` | volatile | volatile | volatile | +| `x3` | `r9` | volatile | volatile | volatile | +| `x4` | `r10` | volatile | volatile | volatile | +| `x5` | `r11` | volatile | volatile | volatile | +| `x6` | `mm1` (low 64 bits of x87 `R1` register) | volatile | volatile | volatile | +| `x7` | `mm2` (low 64 bits of x87 `R2` register) | volatile | volatile | volatile | +| `x8` | `rax` | volatile | volatile | volatile | +| `x9` | `mm3` (low 64 bits of x87 `R3` register) | volatile | volatile | volatile | +| `x10` | `mm4` (low 64 bits of x87 `R4` register) | volatile | volatile | volatile | +| `x11` | `mm5` (low 64 bits of x87 `R5` register) | volatile | volatile | volatile | +| `x12` | `mm6` (low 64 bits of x87 `R6` register) | volatile | volatile | volatile | +| `x13` | N/A | disallowed | volatile | N/A | +| `x14` | N/A | disallowed | volatile | N/A | +| `x15` | `mm7` (low 64 bits of x87 `R7` register) | volatile | volatile | volatile | +| `x16` | High 16 bits of each of the x87 `R0`-`R3` registers | volatile(`xip0`) | volatile(`xip0`) | volatile | +| `x17` | High 16 bits of each of the x87 `R4`-`R7` registers | volatile(`xip1`) | volatile(`xip1`) | volatile | +| `x18` | GS.base | fixed(TEB) | fixed(TEB) | fixed(TEB) | +| `x19` | `r12` | non-volatile | non-volatile | non-volatile | +| `x20` | `r13` | non-volatile | non-volatile | non-volatile | +| `x21` | `r14` | non-volatile | non-volatile | non-volatile | +| `x22` | `r15` | non-volatile | non-volatile | non-volatile | +| `x23` | N/A | disallowed | non-volatile | N/A | +| `x24` | N/A | disallowed | non-volatile | N/A | +| `x25` | `rsi` | non-volatile | non-volatile | non-volatile | +| `x26` | `rdi` | non-volatile | non-volatile | non-volatile | +| `x27` | `rbx` | non-volatile | non-volatile | non-volatile | +| `x28` | N/A | disallowed | disallowed | N/A | +| `fp` | `rbp` | non-volatile | non-volatile | non-volatile | +| `lr` | `mm0` (low 64 bits of x87 `R0` register) | both | both | both | +| `sp` | `rsp` | non-volatile | non-volatile | non-volatile | +| `pc` | `rip` | instruction pointer | instruction pointer | instruction pointer | +| `PSTATE` subset: `N`/`Z`/`C`/`V`/`SS` 1, 2 | `RFLAGS` subset: `SF`/`ZF`/`CF`/`OF`/`TF` | volatile | volatile | volatile | +| N/A | `RFLAGS` subset: `PF`/`AF` | N/A | N/A | volatile | +| N/A | `RFLAGS` subset: `DF` | N/A | N/A | non-volatile | + +1 Avoid directly reading, writing or computing mappings between `PSTATE` and `RFLAGS`. These bits may be used in the future and are subject to change. + +2 The ARM64EC carry flag `C` is the inverse of the x64 carry flag `CF` for subtraction operations. There's no special handling, because the flag is volatile and is therefore trashed when transitioning between (ARM64EC and x64) functions. + +## Register mapping for vector registers + +| ARM64EC register | x64 register | ARM64EC calling convention | ARM64 calling convention | x64 calling convention | +|--|--|--|--|--| +| `v0`-`v5` | `xmm0`-`xmm5` | volatile | volatile | volatile | +| `v6`-`v7` | `xmm6`-`xmm7` | volatile | volatile | non-volatile | +| `v8`-`v15` | `xmm8`-`xmm15` | volatile 1 | volatile 1 | non-volatile | +| `v16`-`v31` | `xmm16`-`xmm31` | disallowed | volatile | disallowed (x64 emulator doesn't support AVX-512) | +| `FPCR` 2 | `MXCSR[15:6]` | non-volatile | non-volatile | non-volatile | +| `FPSR` 2 | `MXCSR[5:0]` | volatile | volatile | volatile | + +1 These ARM64 registers are special in that the lower 64 bits are non-volatile but the upper 64 bits are volatile. From the point of view of an x64 caller, they're effectively volatile because the callee would trash data. + +2 Avoid directly reading, writing, or computing mappings of `FPCR` and `FPSR`. These bits may be used in the future and are subject to change. + +## Struct packing + +ARM64EC follows the same struct packing rules used for x64 to ensure interoperability between ARM64EC code and x64 code. For more information and examples of x64 struct packing, see [Overview of x64 ABI conventions](x64-software-conventions.md). + +## Floating-point exceptions + +To determine if an ARM CPU supports exceptions, write a value that enables exceptions to the FPCR register and then read it back. If the CPU supports floating-point exceptions, the bits corresponding to supported exceptions remain set, while the CPU resets the bits for unsupported exceptions. + +On ARM64EC, Windows catches processor floating-point exceptions and disables them in the FPCR register. This ensures consistent behavior across different processor variants. + +## Emulation helper ABI routines + +ARM64EC code and [thunks](#thunks) use emulation helper routines to transition between x64 and ARM64EC functions. + +The following table describes each special ABI routine and the registers the ABI uses. The routines don't modify the listed preserved registers under the ABI column. No assumptions should be made about unlisted registers. On-disk, the ABI routine pointers are null. At load time, the loader updates the pointers to point to the x64 emulator routines. + +| Name | Description | ABI | +|--|--|--| +| `__os_arm64x_dispatch_call_no_redirect` | Called by an exit thunk to call an x64 target (either an x64 function or an x64 fast-forward sequence). The routine pushes the ARM64EC return address (in the `LR` register) followed by the address of the instruction that succeeds a `blr x16` instruction that invokes the x64 emulator. It then runs the `blr x16` instruction | return value in `x8` (`rax`) | +| `__os_arm64x_dispatch_ret` | Called by an entry thunk to return to its x64 caller. It pops the x64 return address from the stack and invokes the x64 emulator to jump to it | N/A | +| `__os_arm64x_check_call` | Called by ARM64EC code with a pointer to an exit thunk and the indirect ARM64EC target address to execute. The ARM64EC target is considered patchable, and execution always returns to the caller with either the same data it was called with, or with modified data | Arguments:
`x9`: The target address
`x10`: The exit thunk address
`x11`: The fast forward sequence address

Out:
`x9`: If the target function was detoured, it contains the address of the fast forward sequence
`x10`: The exit thunk address
`x11`: If the function was detoured, it contains the exit thunk address. Otherwise, the target address jumped to

Preserved registers: `x0`-`x8`, `x15` (`chkstk`). and `q0`-`q7` | +| `__os_arm64x_check_icall` | Called by ARM64EC code, with a pointer to an exit thunk, to handle a jump to either a target address that is either x64 or ARM64EC. If the target is x64 and the x64 code hasn't been patched, the routine sets the target address register. It points to the ARM64EC version of the function if one exists. Otherwise, it sets the register to point to the exit thunk that transitions to the x64 target. Then, it returns to the calling ARM64EC code, which then jumps to the address in the register. This routine is a non-optimized version of `__os_arm64x_check_call`, where the target address isn't known at compile time

Used at a call-site of an indirect call | Arguments:
`x9`: The target address
`x10`: The exit thunk address
`x11`: The fast forward sequence address

Out:
`x9`: If the target function was detoured, it contains the address of the fast forward sequence
`x10`: The exit thunk address
`x11`: If the function was detoured, it contains the exit thunk address. Otherwise, the target address jumped to

Preserved registers: `x0`-`x8`, `x15` (`chkstk`), and `q0`-`q7` | +| `__os_arm64x_check_icall_cfg` | Same as `__os_arm64x_check_icall` but also checks that the specified address is a valid Control Flow Graph indirect call target | Arguments:
`x10`: The address of the exit thunk
`x11`: The address of the target function

Out:
`x9`: If the target is x64, the address to the function. Otherwise, undefined
`x10`: The address of the exit thunk
`x11`: If the target is x64, it contains the address of the exit thunk. Otherwise, the address of the function

Preserved registers: `x0`-`x8`, `x15` (`chkstk`), and `q0`-`q7` | +| `__os_arm64x_get_x64_information` | Gets the requested part of the live x64 register context | `_Function_class_(ARM64X_GET_X64_INFORMATION) NTSTATUS LdrpGetX64Information(_In_ ULONG Type, _Out_ PVOID Output, _In_ PVOID ExtraInfo)` | +| `__os_arm64x_set_x64_information` | Sets the requested part of the live x64 register context | `_Function_class_(ARM64X_SET_X64_INFORMATION) NTSTATUS LdrpSetX64Information(_In_ ULONG Type,_In_ PVOID Input, _In_ PVOID ExtraInfo)` | +| `__os_arm64x_x64_jump` | Used in signature-less adjustor and other thunks that directly forward (`jmp`) a call to another function that can have any signature, deferring the potential application of the right thunk to the real target | Arguments:
`x9`: target to jump to

All parameter registers preserved (forwarded) | + +## Thunks + +Thunks are the low-level mechanisms to support ARM64EC and x64 functions calling each other. There are two types: *entry thunks* for entering ARM64EC functions and *exit thunks* for calling x64 functions. + +### Entry thunk and intrinsic entry thunks: x64 to ARM64EC function call + +To support x64 callers when a C/C++ function is compiled as ARM64EC, the toolchain generates a single entry thunk consisting of ARM64EC machine code. Intrinsics have an entry thunk of their own. All other functions share an entry thunk with all functions that have a matching calling convention, parameters, and return type. The content of the thunk depends on the calling convention of the C/C++ function. + +In addition to handling parameters and the return address, the thunk bridges the differences in volatility between ARM64EC and x64 vector registers caused by [ARM64EC vector register mapping](#register-mapping-for-vector-registers): + +| ARM64EC register | x64 register | ARM64EC calling convention | ARM64 calling convention | x64 calling convention | +|--|--|--|--|--| +| `v6`-`v15` | `xmm6`-`xmm15` | volatile, but saved/restored in the entry thunk (x64 to ARM64EC) | volatile or partially volatile upper 64 bits | non-volatile | + +The entry thunk performs the following actions: + +| Parameter number | Stack usage | +|--|--| +| 0-4 | Stores ARM64EC `v6` and `v7` into the caller-allocated home space

Since the callee is ARM64EC, which doesn't have the notion of a home space, the stored values aren't clobbered.

Allocates an extra 128 bytes on the stack and store ARM64EC `v8` through `v15`. | +| 5-8 | `x4` = 5th parameter from the stack
`x5` = 6th parameter from the stack
`x6` = 7th parameter from the stack
`x7` = 8th parameter from the stack

If the parameter is SIMD, the `v4`-`v7` registers are used instead | +| 9+ | Allocates `AlignUp(NumParams - 8 , 2) * 8` bytes on the stack. \*

Copies the 9th and remaining parameters to this area | + +\* Aligning the value to an even number guarantees that the stack remains aligned to 16 bytes + +If the function accepts a 32-bit integer parameter, the thunk is permitted to only push 32 bits instead of the full 64 bits of the parent register. + +Next, the thunk uses an ARM64 `bl` instruction to call the ARM64EC function. After the function returns, the thunk: + +1. Undoes any stack allocations +1. Calls the `__os_arm64x_dispatch_ret` emulator helper to pop the x64 return address and resume x64 emulation. + +### Exit thunk: ARM64EC to x64 function call + +For every call that an ARM64EC C/C++ function makes to potential x64 code, the MSVC toolchain generates an exit thunk. The content of the thunk depends on the parameters of the x64 callee and whether the callee is using the standard calling convention or `__vectorcall`. The compiler obtains this information from a function declaration for the callee. + +First, The thunk pushes the return address that's in the ARM64EC `lr` register and a dummy 8-byte value to guarantee that the stack is aligned to 16 bytes. Second, the thunk handles the parameters: + +| Parameter number | Stack usage | +|--|--| +| 0-4 | Allocates 32 bytes of home space on the stack | +| 5-8 | Allocates `AlignUp(NumParams - 4, 2) * 8` more bytes higher up on the stack. \*

Copies the 5th and any subsequent parameters from ARM64EC's `x4`-`x7` to this extra space | +| 9+ | Copies the 9th and remaining parameters to the extra space | + +\* Aligning the value to an even number guarantees that the stack remains aligned to 16 bytes. + +Third, the thunk calls the `__os_arm64x_dispatch_call_no_redirect` emulator helper to invoke the x64 emulator to run the x64 function. The call must be a `blr x16` instruction (conveniently, `x16` is a volatile register). A `blr x16` instruction is required because the x64 emulator parses this instruction as a hint. + +The x64 function usually attempts to return to the emulator helper by using an x64 `ret` instruction. At this point, the x64 emulator detects that it's in ARM64EC code. It then reads the preceding 4-byte hint that happens to be the ARM64 `blr x16` instruction. Since this hint indicates that the return address is in this helper, the emulator jumps directly to this address. + +The x64 function is permitted to return to the emulator helper using any branch instruction, including x64 `jmp` and `call`. The emulator handles these scenarios as well. + +When the helper then returns to the thunk, the thunk: + +1. Undoes any stack allocation +1. Pops the ARM64EC `lr` register +1. Executes an ARM64 `ret lr` instruction. + +## ARM64EC function name decoration + +An ARM64EC function name has a secondary decoration applied after any language-specific decoration. For functions with C linkage (whether compiled as C or by using `extern "C"`), a `#` is prepended to the name. For C++ decorated functions, a `$$h` tag is inserted into the name. + +``` +foo => #foo +?foo@@YAHXZ => ?foo@@$$hYAHXZ +``` + +## `__vectorcall` + +The ARM64EC toolchain currently doesn't support `__vectorcall`. The compiler emits an error when it detects `__vectorcall` usage with ARM64EC. + +## See also + +[Understanding ARM64EC ABI and assembly code](/windows/arm/arm64ec-abi)\ +[Common Visual C++ ARM migration issues](common-visual-cpp-arm-migration-issues.md)\ +[Decorated names](./reference/decorated-names.md) diff --git a/docs/build/building-on-the-command-line.md b/docs/build/building-on-the-command-line.md index ecbaff9bb2..06332dd523 100644 --- a/docs/build/building-on-the-command-line.md +++ b/docs/build/building-on-the-command-line.md @@ -2,7 +2,7 @@ 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/21/2020" +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 --- @@ -11,25 +11,40 @@ ms.assetid: 7ca9daed-a003-4162-842d-908f79058365 You can build C and C++ applications on the command line by using tools that are included in Visual Studio. The Microsoft C++ (MSVC) compiler toolset is also downloadable as a standalone package. You don't need to install the Visual Studio IDE if you don't plan to use it. > [!NOTE] -> This article is about how to set up an environment to use the individual compilers, linkers, librarian, and other basic tools. The native project build system, MSBuild, does not use the environment as described in this article. For more information on how to use MSBuild from the command line, see [MSBuild on the command line - C++](msbuild-visual-cpp.md). +> This article is about how to set up an environment to use the individual compilers, linkers, librarian, and other basic tools. The native project build system in Visual Studio, based on MSBuild, doesn't use the environment as described in this article. For more information on how to use MSBuild from the command line, see [MSBuild on the command line - C++](msbuild-visual-cpp.md). ## Download and install the tools -If you've installed Visual Studio and a C++ workload, you have all the command-line tools. For information on how to install C++ and Visual Studio, see [Install C++ support in Visual Studio](vscpp-step-0-installation.md). If you only want the command-line toolset, download the [Build Tools for Visual Studio](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019). When you run the downloaded executable, it updates and runs the Visual Studio Installer. To install only the tools you need for C++ development, select the **C++ build tools** workload. You can select optional libraries and toolsets to include under **Installation details**. To build code by using the Visual Studio 2015 or 2017 toolsets, select the optional MSVC v140 or MSVC v141 build tools. When you're satisfied with your selections, choose **Install**. +::: moniker range=">=msvc-160" + +If you've installed Visual Studio and a C++ workload, you have all the command-line tools. For information on how to install C++ and Visual Studio, see [Install C++ support in Visual Studio](vscpp-step-0-installation.md). If you only want the command-line toolset, download the [Build Tools for Visual Studio](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022). When you run the downloaded executable, it updates and runs the Visual Studio Installer. To install only the tools you need for C++ development, select the **Desktop development with C++** workload. You can select optional libraries and toolsets to include under **Installation details**. To build code by using the Visual Studio 2015, 2017, or 2019 toolsets, select the optional MSVC v140, v141, or v142 build tools. When you're satisfied with your selections, choose **Install**. + +::: moniker-end +::: moniker range="<=msvc-150" + +If you've installed Visual Studio and a C++ workload, you have all the command-line tools. For information on how to install C++ and Visual Studio, see [Install C++ support in Visual Studio](vscpp-step-0-installation.md). If you only want the command-line toolset, download the [Build Tools for Visual Studio 2017](https://my.visualstudio.com/Downloads?q=2017). When you run the downloaded executable, it updates and runs the Visual Studio Installer. To install only the tools you need for C++ development, select the **Visual C++ build tools** workload. You can select optional libraries and toolsets to include under **Installation details**. To build code by using the Visual Studio 2015 toolset, select the optional MSVC v140 build tools. When you're satisfied with your selections, choose **Install**. + +::: moniker-end ## How to use the command-line tools -When you choose one of the C++ workloads in the Visual Studio Installer, it installs the Visual Studio *platform toolset*. A platform toolset has all the C and C++ tools for a specific Visual Studio version. The tools include the C/C++ compilers, linkers, assemblers, and other build tools, and matching libraries. You can use all of these tools at the command line. They're also used internally by the Visual Studio IDE. There are separate x86-hosted and x64-hosted compilers and tools to build code for x86, x64, ARM, and ARM64 targets. Each set of tools for a particular host and target build architecture is stored in its own directory. +When you choose one of the C++ workloads in the Visual Studio Installer, it installs the Visual Studio *platform toolset*. A platform toolset has all the C and C++ tools for a specific Visual Studio version. The tools include the C/C++ compilers, linkers, assemblers, and other build tools, and matching libraries and header files. You can use all of these tools at the command line. They're also used internally by the Visual Studio IDE. There are separate x86-hosted and x64-hosted compilers and tools to build code for x86, x64, ARM, and ARM64 targets. Each set of tools for a particular host and target build architecture is stored in its own directory. + +To work correctly, the tools require several specific environment variables to be set. These variables are used to add the tools to the path, and to set the locations of include files, library files, and SDKs. To make it easy to set these environment variables, the installer creates customized *command files*, or batch files, during installation. You can run one of these command files to set a specific host and target build architecture, Windows SDK version, and platform toolset. For convenience, the installer also creates shortcuts in your Start menu. The shortcuts open developer command prompt windows by using these command files for specific combinations of host and target. These shortcuts ensure all the required environment variables are set and ready to use. -To work correctly, the tools require several specific environment variables to be set. These variables are used to add the tools to the path, and to set include file, library file, and SDK locations. To make it easy to set these environment variables, the installer creates customized *command files*, or batch files, during installation. You can run one of these command files to set a specific host and target build architecture, Windows SDK version, and platform toolset. For convenience, the installer also creates shortcuts in your Start menu. The shortcuts start developer command prompt windows by using these command files for specific combinations of host and target. These shortcuts ensure all the required environment variables are set and ready to use. +The required environment variables are specific to your installation and to the build architecture you choose. They also might be changed by product updates or upgrades. This variability is one reason why we recommend you use an installed command prompt shortcut or command file, instead of setting the environment variables yourself. -The required environment variables are specific to your installation and to the build architecture you choose. They also might be changed by product updates or upgrades. That's why we recommend you use an installed command prompt shortcut or command file, instead of setting the environment variables yourself. For more information, see [Set the path and environment variables for command-line builds](setting-the-path-and-environment-variables-for-command-line-builds.md). +The toolsets, command files, and shortcuts installed depend on your computer processor and the options you selected during installation. The x86-hosted tools and cross tools that build x86 and x64 code are always installed. If you have 64-bit Windows, the x64-hosted tools and cross tools that build x86 and x64 code are also installed. If you choose the optional C++ Universal Windows Platform tools, then the x86 and x64 tools that build ARM and ARM64 code also get installed. Other workloads may install these and other tools. -The toolsets, command files, and shortcuts installed depend on your computer processor and the options you selected during installation. The x86-hosted tools and cross tools that build x86 and x64 code are always installed. If you have 64-bit Windows, the x64-hosted tools and cross tools that build x86 and x64 code are also installed. If you choose the optional C++ Universal Windows Platform tools, then the x86 and x64 tools that build ARM and ARM64 code also get installed. Other workloads may install additional tools. +## Path and environment variables for command-line builds + +The MSVC command-line tools use the `PATH`, `TMP`, `INCLUDE`, `LIB`, and `LIBPATH` environment variables, and also use other environment variables specific to your installed tools, platforms, and SDKs. Even a simple Visual Studio installation may set twenty or more environment variables. This complexity is why we strongly recommend that you use a [developer command prompt shortcut](#developer_command_prompt_shortcuts) or one of the [customized command files](#developer_command_file_locations). We don't recommend you set these variables in the Windows environment yourself. + +To see which environment variables are set by a developer command prompt shortcut, you can use the `SET` command. Open a plain command prompt window and capture the output of the `SET` command for a baseline. Open a developer command prompt window and capture the output of the `SET` command for comparison. Use a diff tool such as the one built into Visual Studio to highlight the environment variables set by the developer command prompt. For more information about the compiler and linker environment variables, see [CL environment variables](reference/cl-environment-variables.md). ## Developer command prompt shortcuts -The command prompt shortcuts are installed in a version-specific Visual Studio folder in your Start menu. Here's a list of the base command prompt shortcuts and the build architectures they support: +The command prompt shortcuts are installed in a version-specific Visual Studio folder in your Windows Start menu. Here's a list of the base command prompt shortcuts and the build architectures they support: - **Developer Command Prompt** - Sets the environment to use 32-bit, x86-native tools to build 32-bit, x86-native code. - **x86 Native Tools Command Prompt** - Sets the environment to use 32-bit, x86-native tools to build 32-bit, x86-native code. @@ -39,10 +54,10 @@ The command prompt shortcuts are installed in a version-specific Visual Studio f ::: moniker range=">= msvc-160" -The Start menu folder and shortcut names vary depending on the installed version of Visual Studio. If you set one, they also depend on the installation **Nickname**. For example, suppose you installed Visual Studio 2019, and you gave it a nickname of *Latest*. The developer command prompt shortcut is named **Developer Command Prompt for VS 2019 (Latest)**, in a folder named **Visual Studio 2019**. +The Start menu folder and shortcut names vary depending on the installed version of Visual Studio. If you set one, they also depend on the installation **Nickname**. For example, suppose you installed Visual Studio 2022, and you gave it a nickname of *Latest*. The developer command prompt shortcut is named **Developer Command Prompt for VS 2022 (Latest)**, in a folder named **Visual Studio 2022**. ::: moniker-end -::: moniker range="= msvc-150" +::: moniker range="msvc-150" The Start menu folder and shortcut names vary depending on the installed version of Visual Studio. If you set one, they also depend on the installation **Nickname**. For example, suppose you installed Visual Studio 2017, and you gave it a nickname of *Latest*. The developer command prompt shortcut is named **Developer Command Prompt for VS 2017 (Latest)**, in a folder named **Visual Studio 2017**. @@ -53,35 +68,46 @@ The Start menu folder and shortcut names vary depending on the installed version ::: moniker-end +> [!NOTE] +> Several command-line tools or tool options may require Administrator permission. If you have permission issues when you use them, we recommend that you open the developer command prompt window by using the **Run as Administrator** option. Right-click to open the shortcut menu for the command prompt window, then choose **More**, **Run as administrator**. + ### To open a developer command prompt window -1. On the desktop, open the Windows **Start** menu, and then scroll to find and open the folder for your version of Visual Studio, for example, **Visual Studio 2019**. +1. On the desktop, open the Windows **Start** menu. In Windows 11, choose the **All apps** button to open the list of installed apps. In Windows 10, the list is open to the left. Scroll down the list to find and open the folder (not the app) for your version of Visual Studio, for example, **Visual Studio 2022**. 1. In the folder, choose the **Developer Command Prompt** for your version of Visual Studio. This shortcut starts a developer command prompt window that uses the default build architecture of 32-bit, x86-native tools to build 32-bit, x86-native code. If you prefer a non-default build architecture, choose one of the native or cross tools command prompts to specify the host and target architecture. 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*. + ## 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-160" +::: 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 (x86)\\Microsoft Visual Studio\\2019\\*edition*. *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 2019, the typical installation location on a 64-bit system is in *`\Program Files\Microsoft Visual Studio\2022\`*. The *``* may be Community, Professional, Enterprise, BuildTools, or another nickname you supplied. + +::: moniker-end +::: moniker range="= msvc-160" + +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 (x86)\Microsoft Visual Studio\2019\`*. The *``* may be Community, Professional, Enterprise, BuildTools, or another nickname you supplied. ::: moniker-end ::: moniker range="= msvc-150" -The command file location depends on the version of Visual Studio you installed, and on choices you made during installation. For Visual Studio 2017, the typical installation location on a 64-bit system is in \\Program Files (x86)\\Microsoft Visual Studio\\2017\\*edition*. *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 2017, the typical installation location on a 64-bit system is in *`\Program Files (x86)\Microsoft Visual Studio\2017\`*. The *``* may be Community, Professional, Enterprise, BuildTools, or another nickname you supplied. ::: moniker-end ::: moniker range="< msvc-150" -The command file location depends on the Visual Studio version, and the installation directory. For Visual Studio 2015, the typical installation location is in \\Program Files (x86)\\Microsoft Visual Studio 14.0. +The command file location depends on the Visual Studio version, and the installation directory. For Visual Studio 2015, the typical installation location on a 64-bit system is in *`\Program Files (x86)\Microsoft Visual Studio 14.0`*. ::: moniker-end -The primary developer command prompt command file, VsDevCmd.bat, is located in the Common7\\Tools subdirectory. When no parameters are specified, it sets the environment to use the x86-native tools to build 32-bit x86 code. +The primary developer command prompt command file, *`VsDevCmd.bat`*, is located in the *`Common7\Tools`* subdirectory. When no parameters are specified, it sets the environment to use the x86-native tools to build 32-bit x86 code. ::: moniker range=">= msvc-150" @@ -94,61 +120,63 @@ More command files are available to set up specific build architectures. The com ::: moniker-end -These command files set default parameters and call VsDevCmd.bat to set up the specified build architecture environment. A typical installation may include these command files: +These command files set default parameters and call *`VsDevCmd.bat`* to set up the specified build architecture environment. A typical installation may include these command files: -|Command File|Host and Target architectures| -|---|---| -|**vcvars32.bat**| Use the 32-bit x86-native tools to build 32-bit x86 code.| -|**vcvars64.bat**| Use the 64-bit x64-native tools to build 64-bit x64 code.| -|**vcvarsx86_amd64.bat**| Use the 32-bit x86-native cross tools to build 64-bit x64 code.| -|**vcvarsamd64_x86.bat**| Use the 64-bit x64-native cross tools to build 32-bit x86 code.| -|**vcvarsx86_arm.bat**| Use the 32-bit x86-native cross tools to build ARM code.| -|**vcvarsamd64_arm.bat**| Use the 64-bit x64-native cross tools to build ARM code.| -|**vcvarsall.bat**| Use parameters to specify the host and target architectures, Windows SDK, and platform choices. For a list of supported options, call by using a **/help** parameter.| +| Command File | Host and Target architectures | +|--|--| +| *`vcvars32.bat`* | Use the 32-bit x86-native tools to build 32-bit x86 code. | +| *`vcvars64.bat`* | Use the 64-bit x64-native tools to build 64-bit x64 code. | +| *`vcvarsx86_amd64.bat`* | Use the 32-bit x86-native cross tools to build 64-bit x64 code. | +| *`vcvarsamd64_x86.bat`* | Use the 64-bit x64-native cross tools to build 32-bit x86 code. | +| *`vcvarsx86_arm.bat`* | Use the 32-bit x86-native cross tools to build ARM code. | +| *`vcvarsamd64_arm.bat`* | Use the 64-bit x64-native cross tools to build ARM code. | +| *`vcvarsx86_arm64.bat`* | Use the 32-bit x86-native cross tools to build ARM64 code. | +| *`vcvarsamd64_arm64.bat`* | Use the 64-bit x64-native cross tools to build ARM64 code. | +| *`vcvarsall.bat`* | Use parameters to specify the host and target architectures, Windows SDK, and platform choices. For a list of supported options, call by using a `/help` parameter. | > [!CAUTION] -> The vcvarsall.bat file and other Visual Studio command files can vary from computer to computer. Do not replace a missing or damaged vcvarsall.bat file by using a file from another computer. Rerun the Visual Studio installer to replace the missing file. +> The *`vcvarsall.bat`* file and other Visual Studio command files can vary from computer to computer. Do not replace a missing or damaged *`vcvarsall.bat`* file by using a file from another computer. Rerun the Visual Studio installer to replace the missing file. > -> The vcvarsall.bat file also varies from version to version. If the current version of Visual Studio is installed on a computer that also has an earlier version of Visual Studio, do not run vcvarsall.bat or another Visual Studio command file from different versions in the same command prompt window. +> The *`vcvarsall.bat`* file also varies from version to version. If the current version of Visual Studio is installed on a computer that also has an earlier version of Visual Studio, do not run *`vcvarsall.bat`* or another Visual Studio command file from different versions in the same command prompt window. ## Use the developer tools in an existing command window -The simplest way to specify a particular build architecture in an existing command window is to use the vcvarsall.bat file. Use vcvarsall.bat to set environment variables to configure the command line for native 32-bit or 64-bit compilation. Arguments let you specify cross-compilation to x86, x64, ARM, or ARM64 processors. You can target Microsoft Store, Universal Windows Platform, or Windows Desktop platforms. You can even specify which Windows SDK to use, and select the platform toolset version. +The simplest way to specify a particular build architecture in an existing command window is to use the *`vcvarsall.bat`* file. Use *`vcvarsall.bat`* to set environment variables to configure the command line for native 32-bit or 64-bit compilation. Arguments let you specify cross-compilation to x86, x64, ARM, or ARM64 processors. You can target Microsoft Store, Universal Windows Platform, or Windows Desktop platforms. You can even specify which Windows SDK to use, and select the platform toolset version. -When used with no arguments, vcvarsall.bat configures the environment variables to use the current x86-native compiler for 32-bit Windows Desktop targets. You can add arguments to configure the environment to use any of the native or cross compiler tools. vcvarsall.bat displays an error message if you specify a configuration that's not installed, or not available on your computer. +When used with no arguments, *`vcvarsall.bat`* configures the environment variables to use the current x86-native compiler for 32-bit Windows Desktop targets. You can add arguments to configure the environment to use any of the native or cross compiler tools. *`vcvarsall.bat`* displays an error message if you specify a configuration that's not installed, or not available on your computer. -### vcvarsall syntax +### `vcvarsall` syntax -> **vcvarsall.bat** [*architecture*] [*platform_type*] [*winsdk_version*] [**-vcvars_ver=**_vcversion_] +> **`vcvarsall.bat`** [*`architecture`*] [*`platform_type`*] [*`winsdk_version`*] [**`-vcvars_ver=`***`vcversion`*] [*`spectre_mode`*] -*architecture*
+*`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| -|----------------------------|--------------|----------------------------------|-------------------------------| -|**x86**|x86 32-bit native|x86, x64|x86| -|**x86\_amd64** or **x86\_x64**|x64 on x86 cross|x86, x64|x64| -|**x86_arm**|ARM on x86 cross|x86, x64|ARM| -|**x86_arm64**|ARM64 on x86 cross|x86, x64|ARM64| -|**amd64** or **x64**|x64 64-bit native|x64|x64| -|**amd64\_x86** or **x64\_x86**|x86 on x64 cross|x64|x86| -|**amd64\_arm** or **x64\_arm**|ARM on x64 cross|x64|ARM| -|**amd64\_arm64** or **x64\_arm64**|ARM64 on x64 cross|x64|ARM64| +| *`architecture`* | Compiler | Host computer architecture | Build output (target) architecture | +|--|--|--|--| +| `x86` | x86 32-bit native | x86, x64 | x86 | +| `x86_amd64` or `x86_x64` | x64 on x86 cross | x86, x64 | x64 | +| `x86_arm` | ARM on x86 cross | x86, x64 | ARM | +| `x86_arm64` | ARM64 on x86 cross | x86, x64 | ARM64 | +| `amd64` or `x64` | x64 64-bit native | x64 | x64 | +| `amd64_x86` or `x64_x86` | x86 on x64 cross | x64 | x86 | +| `amd64_arm` or `x64_arm` | ARM on x64 cross | x64 | ARM | +| `amd64_arm64` or `x64_arm64` | ARM64 on x64 cross | x64 | ARM64 | -*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. +*`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*
-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 10 SDK number such as **10.0.10240.0**, or specify **8.1** to use the Windows 8.1 SDK. +*`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*
+*`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" Use **-vcvars_ver=14.2x.yyyyy** to specify a specific version of the Visual Studio 2019 compiler toolset. -Use **-vcvars_ver=14.16** to specify the latest version of the Visual Studio 2017 compiler toolset. +Use **-vcvars_ver=14.29** to specify the latest version of the Visual Studio 2019 compiler toolset. ::: moniker-end ::: moniker range="= msvc-150" @@ -161,6 +189,9 @@ Use **-vcvars_ver=14.1x.yyyyy** to specify a specific version of the Visual Stud Use **-vcvars_ver=14.0** to specify the Visual Studio 2015 compiler toolset. +*`spectre_mode`*\ +Leave this parameter out to use libraries without Spectre mitigations. Use the value **`spectre`** to use libraries with Spectre mitigations. + #### 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. @@ -193,21 +224,21 @@ Open the Properties dialog for a developer command prompt shortcut to see the co ::: 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: +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.16` +`%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.0` +`%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=12.0` +`%comspec% /k "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" amd64 -vcvars_ver=14.0` ::: moniker-end @@ -217,26 +248,32 @@ Adjust the path to reflect your Visual Studio installation directory. The vcvars 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)
+[`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)
+[`Link`](reference/linking.md)
Use the linker (link.exe) to link compiled object files and libraries into apps and DLLs. -[NMAKE](reference/nmake-reference.md)
-Use NMAKE (nmake.exe) on Windows to build C++ projects based on a traditional makefile. - -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 docs.microsoft.com, enter your query in the search box at the top of any article. +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. ## Command-line project management tools -The Visual Studio IDE uses a native project build system based on MSBuild. You can invoke MSBuild directly, or use the native project system without using the IDE: +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/). + +[`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. -[MSBuild](msbuild-visual-cpp.md)
-Use MSBuild (msbuild.exe) and a project file (.vcxproj) to configure a build and invoke the toolset indirectly. It's equivalent to running the **Build** project or **Build Solution** command in the Visual Studio IDE. Running MSBuild from the command line is an advanced scenario and not commonly recommended. Starting in Visual Studio version 16.5, MSBuild doesn't use the command-line environment to control the toolset and libraries used. +[`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#). -[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. In general, DEVENV is preferred over using MSBuild directly, because you can let Visual Studio handle the complexities of MSBuild. Starting in Visual Studio version 16.5, DEVENV does not use the command-line environment to control the toolset and libraries used. +[`NMAKE`](reference/nmake-reference.md)\ +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. ## In this section @@ -254,9 +291,6 @@ Describes how to create and compile a C++/CLI program that uses the .NET Framewo [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. -[Set the path and environment variables for command-line builds](setting-the-path-and-environment-variables-for-command-line-builds.md)
-How to set environment variables to use a 32-bit or 64-bit toolset to target x86, x64, ARM, and ARM64 platforms. - [NMAKE reference](reference/nmake-reference.md)
Provides links to articles that describe the Microsoft Program Maintenance Utility (NMAKE.EXE). diff --git a/docs/build/clang-support-cmake.md b/docs/build/clang-support-cmake.md index 1d8e8f405f..157c3259d9 100644 --- a/docs/build/clang-support-cmake.md +++ b/docs/build/clang-support-cmake.md @@ -9,23 +9,35 @@ helpviewer_keywords: ["Clang support for C++ CMake projects"] ::: moniker range="<=msvc-150" -Clang support is available in Visual Studio 2019. +Clang support is available starting in Visual Studio 2019. ::: moniker-end - -::: moniker range="msvc-160" +::: moniker range=">=msvc-160" You can use Visual Studio with Clang to edit and debug C++ CMake projects that target Windows or Linux. -**Windows**: Visual Studio 2019 version 16.1 includes support for editing, building, and debugging with Clang/LLVM in CMake projects targeting Windows. +**Windows**: Starting in Visual Studio 2019 version 16.1, Visual Studio includes support for editing, building, and debugging with Clang/LLVM in CMake projects targeting Windows. **Linux**: For Linux CMake projects, no special Visual Studio support is required. You can install Clang using your distro's package manager, and add the appropriate commands in the CMakeLists.txt file. ## Install +::: moniker-end +::: moniker range="msvc-160" + +For the best IDE support in Visual Studio, we recommend using the latest Clang compiler tools for Windows. If you don't already have those, you can install them by opening the Visual Studio Installer and choosing **C++ Clang compiler for Windows** under **Desktop development with C++** optional components. You may prefer to use an existing Clang installation on your machine; if so, choose the **C++ Clang-cl for v142 build tools** or **C++ Clang-cl for v143 build tools** component. + +![Screenshot of the Visual Studio Installer Individual Components page that shows Clang components available for installation.](media/clang-install-vs2019.png) -For best IDE support in Visual Studio, we recommend using the latest Clang compiler tools for Windows. If you don't already have those, you can install them by opening the Visual Studio Installer and choosing **C++ Clang compiler for Windows** under **Desktop development with C++** optional components. When using a custom Clang installation, check the **C++ Clang-cl for v142 build tools** component. +::: moniker-end +::: moniker range="msvc-170" + +For the best IDE support in Visual Studio, we recommend using the latest Clang compiler tools for Windows. If you don't already have those, you can install them by opening the Visual Studio Installer and choosing **C++ Clang compiler for Windows** under **Desktop development with C++** optional components. You may prefer to use an existing Clang installation on your machine; if so, choose the **MSBuild support for LLVM (clang-cl) toolset** component. + +![Screenshot of the Visual Studio Installer Individual Components page that shows Clang components available for installation.](media/clang-install-vs2022.png) + +::: moniker-end +::: moniker range=">=msvc-160" -![Clang component installation](media/clang-install-vs2019.png) ## Create a new configuration @@ -35,11 +47,11 @@ To add a new Clang configuration to a CMake project: 1. Under **Configurations**, press the **Add Configuration** button: - ![Add configuration](media/cmake-add-config-icon.png) + ![Screenshot of the controls at the top of the C Make Settings dialog, with the Add Configuration control highlighted.](media/cmake-add-config-icon.png) 1. Choose the desired Clang configuration (note that separate Clang configurations are provided for Windows and Linux), then press **Select**: - ![CMake Clang configuration](media/cmake-clang-configuration.png) + ![Screenshot of the Add Configuration to C Make Settings dialog for Clang configuration.](media/cmake-clang-configuration.png) 1. To make modifications to this configuration, use the **CMake Settings Editor**. For more information, see [Customize CMake build settings in Visual Studio](customize-cmake-settings.md). @@ -72,10 +84,10 @@ You can modify these values in **CMake Settings** under **CMake variables and ca ## Edit, build, and debug -After you have set up a Clang configuration, you can build and debug the project. Visual Studio detects that you are using the Clang compiler and provides IntelliSense, highlighting, navigation, and other editing features. Errors and warnings are displayed in the **Output Window**. +After you have set up a Clang configuration, you can build and debug the project. Visual Studio detects that you're using the Clang compiler and provides IntelliSense, highlighting, navigation, and other editing features. Errors and warnings are displayed in the **Output Window**. -When debugging, you can use breakpoints, memory and data visualization, and most other debugging features. Some compiler-dependent features such as Edit and Continue are not available for Clang configurations. +When debugging, you can use breakpoints, memory and data visualization, and most other debugging features. Some compiler-dependent features such as Edit and Continue aren't available for Clang configurations. -![CMake Clang debugging](media/clang-debug-visualize.png) +![Screenshot of the Visual Studio debugger debugging a CMake Clang project.](media/clang-debug-visualize.png) ::: moniker-end diff --git a/docs/build/clang-support-msbuild.md b/docs/build/clang-support-msbuild.md index 19f5d4ec2a..6e44fbb42a 100644 --- a/docs/build/clang-support-msbuild.md +++ b/docs/build/clang-support-msbuild.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: Clang/LLVM support in Visual Studio projects" title: "Clang/LLVM support in Visual Studio projects" -ms.date: 02/05/2021 +description: "Learn more about: Clang/LLVM support in Visual Studio projects" +ms.date: 03/13/2024 ms.description: "Configure a Visual Studio MSBuild project to use the Clang/LLVM toolchain." helpviewer_keywords: ["Clang support for C++ MSBuild projects"] --- @@ -9,33 +9,57 @@ helpviewer_keywords: ["Clang support for C++ MSBuild projects"] ::: moniker range="<=msvc-150" -Clang support for both CMake and MSBuild projects is available in Visual Studio 2019. +Clang/LLVM support for both CMake and MSBuild projects is available in Visual Studio 2019 and Visual Studio 2022. ::: moniker-end +::: moniker range=">=msvc-160" -::: moniker range="msvc-160" +You can use Visual Studio 2019 version 16.2 and later with Clang/LLVM to edit, build, and debug C++ Visual Studio projects (MSBuild) that target Windows or Linux. + +::: moniker-end -You can use Visual Studio 2019 version 16.2 and later with Clang to edit, build, and debug C++ Visual Studio projects (MSBuild) that target Windows or Linux. +::: moniker range="=msvc-160" +## Install +For the best IDE support in Visual Studio, we recommend using the latest Clang compiler tools for Windows. If you don't already have the tools, you can install them by opening the Visual Studio Installer and choosing **C++ Clang tools for Windows** under **Desktop development with C++** optional components. You may prefer to use an existing Clang installation on your machine; if so, choose **C++ Clang-cl for v142 build tools** or **C++ Clang-cl for v143 build tools**. +::: moniker-end +::: moniker range=">=msvc-170" ## Install -For best IDE support in Visual Studio, we recommend using the latest Clang compiler tools for Windows. If you don't already have the tools, you can install them by opening the Visual Studio Installer and choosing **C++ Clang tools for Windows** under **Desktop development with C++** optional components. You may prefer to use an existing Clang installation on your machine; if so, choose the **C++ Clang-cl for v142 build tools.** optional component. +For the best IDE support in Visual Studio, we recommend using the latest Clang compiler tools for Windows. If you don't already have the tools, you can install them by opening the Visual Studio Installer and choosing **C++ Clang tools for Windows** under **Desktop development with C++** optional components. You may prefer to use an existing Clang installation on your machine; if so, choose **MSBuild support for LLVM (clang-cl) toolset**. +::: moniker-end +::: moniker range=">=msvc-160" The Microsoft C++ Standard Library requires at least Clang 8.0.0. +::: moniker-end -![Screenshot of the Visual Studio installer with the Individual components tab selected and the C plus plus Clang components visible.](media/clang-install-vs2019.png) +::: moniker range="=msvc-160" +:::image type="complex" source="media/clang-install-vs2019.png" alt-text="Screenshot of the Visual Studio 2019 installer"::: +The Individual components tab is selected in the installer. C++ Clang Compiler for Windows is selected. C++ Clang-cl for v142 build tools (x64/x86) is also selected. +:::image-end::: -Later versions of Visual Studio provide newer versions of the Clang toolset. The bundled version of Clang gets updated automatically to stay current with updates in the Microsoft implementation of the Standard Library. For example, Visual Studio 2019 version 16.9 includes Clang v11. +::: moniker-end +::: moniker range=">=msvc-170" +:::image type="complex" source="media/clang-install-vs2022.png" alt-text="Screenshot of the Visual Studio 2022 installer." +The Individual components tab is selected in the installer. C++ Clang Compiler for Windows is selected. MSBuild support for LLVM (clang-cl) toolset is also selected. +::: image-end ::: + +::: moniker-end + +::: moniker range=">=msvc-160" +Later versions of Visual Studio provide newer versions of the Clang toolset. The bundled version of Clang gets updated automatically to stay current with updates in the Microsoft implementation of the Standard Library. For example, Visual Studio 2019 version 16.11 includes Clang v12. ## Configure a Windows project to use Clang tools To configure a Visual Studio project to use Clang, right-click on the project node in **Solution Explorer** and choose **Properties**. Typically, you should first choose **All configurations** at the top of the dialog. Then, under **General** > **Platform Toolset**, choose **LLVM (clang-cl)** and then **OK**. -![Screenshot of the Property Pages dialog box with Configuration Properties > General selected and the Platform Toolset and L L V M (clang c l) options highlighted.](media/clang-msbuild-prop-page.png) +:::image type="complex" source="media/llvm-msbuild-prop-page.png" alt-text="Screenshot of the Visual Studio project Property Pages dialog box."::: +The project properties page is open to the Configuration Properties > General page. The Platform Toolset dropdown is selected, on which LLVM (clang-cl) is selected. +:::image-end::: -If you're using the Clang tools that are bundled with Visual Studio, no extra steps are required. For Windows projects, Visual Studio by default invokes Clang in [clang-cl](https://llvm.org/devmtg/2014-04/PDFs/Talks/clang-cl.pdf) mode. It links with the Microsoft implementation of the Standard Library. By default, **clang-cl.exe** is located in *%VCINSTALLDIR%\\Tools\\Llvm\\bin\\* and *%VCINSTALLDIR%\\Tools\\Llvm\\x64\\bin\\*. +If you're using the Clang tools that are bundled with Visual Studio, no extra steps are required. For Windows projects, Visual Studio by default invokes Clang in [clang-cl](https://llvm.org/devmtg/2014-04/PDFs/Talks/clang-cl.pdf) mode. It links with the Microsoft implementation of the Standard Library. By default, **clang-cl.exe** is located in *`%VCINSTALLDIR%\Tools\Llvm\bin\`* and *`%VCINSTALLDIR%\Tools\Llvm\x64\bin\`*. -If you're using a custom Clang installation, you can either modify **Project** > **Properties** > **VC++ DIrectories** > **Configuration Properties** > **Executable Directories** by adding the custom Clang installation root as the first directory there, or change the value of the `LLVMInstallDir` property. For more information, see [Set a custom LLVM location](#custom_llvm_location). +If you're using a custom Clang installation, you can change the value of the `LLVMInstallDir` property. For more information, see [Set a custom LLVM location](#custom_llvm_location). ## Configure a Linux project to use Clang tools @@ -45,36 +69,37 @@ To configure a Visual Studio Linux project to use Clang: 1. Right-click on the project node in **Solution Explorer** and choose **Properties**. 1. Typically, you should first choose **All configurations** at the top of the dialog. -1. Under **General** > **Platform Toolset**, choose **WSL_Clang_1_0** if you're using Windows Subsystem for Linux (WSL). Choose **Remote_Clang_1_0** if you're using a remote machine or VM. +1. Under **General** > **Platform Toolset**, choose **Clang for Windows Subsystem for Linux** if you're using Windows Subsystem for Linux (WSL). Choose **Clang for Remote Linux** if you're using a remote machine or VM. 1. Press **OK**. -![Screenshot of the Console App clang Visual Studio 2019 Property Pages dialog box with Configuration Properties > General selected and the Platform Toolset and L L V M (clang c l) options highlighted.](media/clang-msbuild-prop-page.png) +:::image type="complex" source="media/clang-msbuild-prop-page.png" alt-text="Screenshot of the Visual Studio 2019 project Property Pages dialog box"::: +The project properties page is open to the Configuration Properties > General page. Platform Toolset is selected and from the list of options, LLVM (clang- c l) is selected." +:::image-end::: On Linux, Visual Studio by default uses the first Clang location that it finds in the PATH environment property. If you're using a custom Clang installation, then either change the value of the `LLVMInstallDir` property or else enter the path under **Project** > **Properties** > **Configuration Properties** > **VC++ DIrectories** > **Executable Directories**. For more information, see [Set a custom LLVM location](#custom_llvm_location). -## Set a custom LLVM location +## Set a custom LLVM location and toolset -You can set a custom path to LLVM for one or more projects by creating a *Directory.build.props* file. Then, add that file to the root folder of any project. You can add it to the root solution folder to apply it to all projects in the solution. The file should look like this (but use your actual LLVM path): +To set a custom path to LLVM and set a custom LLVM toolset version for one or more projects, create a *Directory.build.props* file. Then, add that file to the root folder of any project. You can add it to the root solution folder to apply it to all projects in the solution. The file should look like this example (but use your actual LLVM path and version number): ```xml C:\MyLLVMRootDir + 15.0.0 ``` -You can combine this property with a custom LLVM toolset version. For more information, see [Set a custom LLVM toolset version](#custom_llvm_toolset). +## Set a custom LLVM toolset version in the IDE -## Set a custom LLVM toolset version +Starting in Visual Studio 2019 version 16.9, you can set a custom toolset version for LLVM in Visual Studio. To set this property in a project: -Starting in Visual Studio 2019 version 16.9, you can set a custom toolset version for LLVM. To set this property in a project 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. Open the project's **Property Pages** dialog box. For more information, see [Set C++ compiler and build properties](./working-with-project-properties.md). 1. Select the **Configuration Properties** > **General** property page. -1. Modify the **Platform Toolset** property to *LLVM (clang-cl)*, if it isn't already set. +1. Modify the **Platform Toolset** property to *LLVM (clang-cl)*, if it isn't already set. Choose **Apply** to save your changes. 1. Select the **Configuration Properties** > **Advanced** property page. @@ -82,35 +107,16 @@ Starting in Visual Studio 2019 version 16.9, you can set a custom toolset versio The **LLVM Toolset Version** property only appears when the LLVM platform toolset is selected. -You can set the toolset version for one or more projects by creating a *Directory.build.props* file. Then, add that file to the root folder of any project. Add it to the root solution folder to apply it to all projects in the solution. The file should look like this (but use your actual LLVM path): - -```xml - - - 11.0.0 - - -``` - -You can also combine this property with a custom LLVM location. For example, your *Directory.build.props* file could look like: - -```xml - - - C:\MyLLVMRootDir - 11.0.0 - - -``` - -When you add a *Directory.build.props* file, the settings appear as the default in the project Property Pages dialog. However, changes to these properties in Visual Studio override the settings in the *Directory.build.props* file. +When you add a `Directory.build.props` file to a project or solution, the settings appear as the default in the project Property Pages dialog. However, changes to these properties in Visual Studio override the settings in the `Directory.build.props` file. -## Set additional properties, edit, build, and debug +## Set properties, edit, build, and debug After you have set up a Clang configuration, right-click again on the project node and choose **Reload project**. You can now build and debug the project using the Clang tools. Visual Studio detects that you're using the Clang compiler and provides IntelliSense, highlighting, navigation, and other editing features. Errors and warnings are displayed in the **Output Window**. The project property pages for a Clang configuration are similar to the ones for MSVC. However, some compiler-dependent features such as Edit and Continue aren't available for Clang configurations. You can set a Clang compiler or linker option that isn't available in the property pages. Add it manually in the property pages under **Configuration Properties** > **C/C++ (or Linker)** > **Command Line** > **Additional Options**. When debugging, you can use breakpoints, memory and data visualization, and most other debugging features. -![Clang debugging](media/clang-debug-msbuild.png) +:::image type="complex" source="media/clang-debug-msbuild.png" alt-text="Screenshot of Visual Studio debugging a sample app"::: +The portion of the app that is visible creates a string vector and adds some strings to it. Execution has stopped on a breakpoint for the code: v.push_back("Clang/LLVM");. +:::image-end::: ::: moniker-end diff --git a/docs/build/cmake-predefined-configuration-reference.md b/docs/build/cmake-predefined-configuration-reference.md index e59b0c86a8..d9597573d8 100644 --- a/docs/build/cmake-predefined-configuration-reference.md +++ b/docs/build/cmake-predefined-configuration-reference.md @@ -2,7 +2,7 @@ description: "Learn more about: CMake predefined build configurations" title: "CMake predefined configuration reference" ms.description: "Visual Studio provides several predefined build configurations for CMake projects on Linux, Windows, ARM, and IoT." -ms.date: "06/12/2019" +ms.date: 08/03/2021 helpviewer_keywords: ["CMake redefined configurations"] --- # CMake predefined build configurations @@ -15,7 +15,7 @@ CMake projects are supported in Visual Studio 2017 and later. ::: moniker range=">=msvc-150" -In a CMake project, build configurations are stored in a CMakeSettings.json file. When you choose **Manage Configurations** from the build configuration dropdown in the main toolbar, a dialog appears that shows the default CMake configurations available in Visual Studio: +In a CMake project, build configurations are stored in a *`CMakeSettings.json`* file. When you choose **Manage Configurations** from the build configuration dropdown in the main toolbar, a dialog appears that shows the default CMake configurations available in Visual Studio: - x86 Debug - x86 Release @@ -28,7 +28,7 @@ In a CMake project, build configurations are stored in a CMakeSettings.json file - MinGW Debug - MinGW Release -When you choose a configuration, it is added to the *CMakeSettings.json* file in the project's root folder. You can then use it to build your project. For information about the configuration properties, see [CMakeSettings reference](cmakesettings-reference.md). +When you choose a configuration, it's added to the *`CMakeSettings.json`* file in the project's root folder. You can then use it to build your project. For information about the configuration properties, see [CMakeSettings reference](cmakesettings-reference.md). ## Linux predefined build configurations: @@ -92,7 +92,6 @@ When you choose a configuration, it is added to the *CMakeSettings.json* file in }, ``` - You can use these optional settings for more control: ```json @@ -348,9 +347,9 @@ These options allow you to run commands on the remote system before and after bu ::: moniker-end -::: moniker range="msvc-160" +::: moniker range=">=msvc-160" -In a CMake project, build configurations are stored in a CMakeSettings.json file. When you choose **Manage Configurations** from the build configuration dropdown in the main toolbar, a dialog appears that shows the default CMake configurations available in Visual Studio: +In a CMake project, build configurations are stored in a *`CMakeSettings.json`* file. When you choose **Manage Configurations** from the build configuration dropdown in the main toolbar, a dialog appears that shows the default CMake configurations available in Visual Studio: - x86 Debug - x86 Clang Debug @@ -374,7 +373,7 @@ In a CMake project, build configurations are stored in a CMakeSettings.json file - WSL Clang Release - Clang -When you choose a configuration, it is added to the CMakeSettings.json file in the project's root folder. You can then use it to build your project. +When you choose a configuration, it's added to the *`CMakeSettings.json`* file in the project's root folder. You can then use it to build your project. ```json { diff --git a/docs/build/cmake-presets-json-reference.md b/docs/build/cmake-presets-json-reference.md index c3283de8fa..07b08b79e8 100644 --- a/docs/build/cmake-presets-json-reference.md +++ b/docs/build/cmake-presets-json-reference.md @@ -1,74 +1,74 @@ --- description: "Schema reference for `CMakePresets.json` and `CMakeUserPresets.json` Microsoft vendor maps" title: "CMakeUserPresets.json" -ms.date: "4/13/2021" +ms.date: 02/07/2022 helpviewer_keywords: ["CMake in Visual C++"] --- # `CMakePresets.json` and `CMakeUserPresets.json` Microsoft vendor maps -CMake supports two files, `CMakePresets.json` and `CMakeUserPresets.json`, that allow users to specify common configure, build, and test options and share them with others. +CMake supports two files, *`CMakePresets.json`* and *`CMakeUserPresets.json`*, that allow users to specify common configure, build, and test options and share them with others. -`CMakePresets.json` and `CMakeUserPresets.json` can be used to drive CMake in Visual Studio, in Visual Studio Code, in a Continuous Integration (CI) pipeline, and from the command line. +*`CMakePresets.json`* and *`CMakeUserPresets.json`* can be used to drive CMake in Visual Studio, in Visual Studio Code, in a Continuous Integration (CI) pipeline, and from the command line. -`CMakePresets.json` is intended to save project-wide builds, and `CMakeUserPresets.json` is intended for developers to save their own local builds. The schema for both files is identical. +*`CMakePresets.json`* is intended to save project-wide builds, and *`CMakeUserPresets.json`* is intended for developers to save their own local builds. The schema for both files is identical. -`CMakePresets.json` and `CMakeUserPresets.json` support vendor maps to store vendor-specific information. Microsoft maintains two vendor maps with options specific to Visual Studio and Visual Studio Code. Here we document two Microsoft vendor maps and vendor macros. For documentation about the rest of the schema, including Configure Presets, Build Presets, and Test Presets, see the official [CMake documentation](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html). +*`CMakePresets.json`* and *`CMakeUserPresets.json`* support vendor maps to store vendor-specific information. Microsoft maintains two vendor maps with options specific to Visual Studio and Visual Studio Code. Here we document two Microsoft vendor maps and vendor macros. For more information about the rest of the schema, see the official [CMake documentation](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html). It includes information about Configure Presets, Build Presets, and Test Presets. -For more information about how to use `CMakePresets.json` in Visual Studio, see [Configure and build with CMake Presets in Visual Studio](cmake-presets-vs.md) +For more information about how to use *`CMakePresets.json`* in Visual Studio, see [Configure and build with CMake Presets in Visual Studio](cmake-presets-vs.md) -For more information about how to use `CMakePresets.json` in Visual Studio Code, see [Configure and build with CMake Presets in VS Code](https://github.com/microsoft/vscode-cmake-tools/blob/develop/docs/cmake-presets.md) +For more information about how to use *`CMakePresets.json`* in Visual Studio Code, see [Configure and build with CMake Presets in VS Code](https://github.com/microsoft/vscode-cmake-tools/blob/main/docs/cmake-presets.md) ## Visual Studio Settings vendor map One vendor map with the vendor URI `microsoft.com/VisualStudioSettings/CMake/` is allowed per Configure Preset and contains options specific to CMake integration in Visual Studio and Visual Studio Code. All options in the vendor map apply to Visual Studio. Options that apply to both Visual Studio and Visual Studio Code have been explicitly marked. -All settings in the Visual Studio Settings vendor map are optional and inherited from Configure Presets specified by the `inherits` key. Only options that have been modified are written to the file. The Visual Studio Settings vendor map is supported by both `CMakePresets.json` and `CMakeUserPresets.json`. +All settings in the Visual Studio Settings vendor map are optional and inherited from Configure Presets specified by the `inherits` key. Only options that have been modified are written to the file. The Visual Studio Settings vendor map is supported by both *`CMakePresets.json`* and *`CMakeUserPresets.json`*. -None of the options in the Visual Studio Settings vendor map impact the construction of the CMake or CTest command line. This ensures that the same `CMakePresets.json` file can be used to drive CMake with Visual Studio, Visual Studio Code, and from the command line. The exceptions to this are the `cacheRoot` and `cmakeGenerateCommand` options. These options are specific to the [Open Existing Cache](https://devblogs.microsoft.com/cppblog/open-existing-cmake-caches-in-visual-studio/) scenario in Visual Studio and cannot be reproduced from the command line. +The options in the Visual Studio Settings vendor map don't affect the construction of the CMake or CTest command line. It's so the same *`CMakePresets.json`* file can be used to drive CMake with Visual Studio, Visual Studio Code, and from the command line. The exceptions are the `cacheRoot` and `cmakeGenerateCommand` options. These options are specific to the [Open Existing Cache](https://devblogs.microsoft.com/cppblog/open-existing-cmake-caches-in-visual-studio/) scenario in Visual Studio and can't be reproduced from the command line. | Setting | Description | |--|--| | `hostOS` | An array of supported operating systems (OS). Accepted values are `Windows`, `Linux`, and `macOS`.

The value of `hostOS` is used by Visual Studio and Visual Studio Code to hide Configure Presets that don't apply to the OS of the target system and provide a better user experience.

If `hostOS` is unspecified, then Visual Studio and Visual Studio Code will always show all Configure Presets for selection. This field can also be a string, which is equivalent to an array containing one string

This option is supported by both Visual Studio and Visual Studio Code. | -| `intelliSenseMode` | Specifies the mode used for computing IntelliSense information in Visual Studio with the format `--`.

Accepted values:

`android-clang-arm`
`android-clang-arm64`
`android-clang-x6`
`android-clang-x86`
`ios-clang-ar`
`ios-clang-arm64`
`ios-clang-x6`
`ios-clang-x86`
`linux-gcc-arm`
`linux-gcc-x64`
`linux-gcc-x86`
`windows-clang-arm`
`windows-clang-arm64`
`windows-clang-x64`
`windows-clang-x86`
`windows-msvc-arm`
`windows-msvc-arm64`
`windows-msvc-x64`
`windows-msvc-x86`

If `intelliSenseMode` is unspecified, then Visual Studio will use the IntelliSense mode that matches your specified compilers and target architecture. `intelliSenseMode` is usually used to provide accurate IntelliSense for cross-compilation.

In Visual Studio 2019, you must explicitly specify a clang IntelliSense mode when building with clang or clang-cl. | -| `intelliSenseOptions` | A map of additional IntelliSense configuration options.

`useCompilerDefaults`: A `bool` that specifies whether to use the compilers’ default defines and include paths for IntelliSense. Should only be `false` if the compilers in use don't support gcc-style arguments. Defaults to `true`.

`additionalCompilerArgs`: An array of additional options to control IntelliSense in Visual Studio. This option supports macro expansion. | +| `intelliSenseMode` | Specifies the mode used for computing IntelliSense information in Visual Studio with the format `--`.

Accepted values:

`android-clang-arm`
`android-clang-arm64`
`android-clang-x6`
`android-clang-x86`
`ios-clang-ar`
`ios-clang-arm64`
`ios-clang-x6`
`ios-clang-x86`
`linux-gcc-arm`
`linux-gcc-x64`
`linux-gcc-x86`
`windows-clang-arm`
`windows-clang-arm64`
`windows-clang-x64`
`windows-clang-x86`
`windows-msvc-arm`
`windows-msvc-arm64`
`windows-msvc-x64`
`windows-msvc-x86`

If `intelliSenseMode` is unspecified, then Visual Studio uses the IntelliSense mode that matches your specified compilers and target architecture. `intelliSenseMode` is often used to provide improved IntelliSense for cross-compilation.

In Visual Studio 2019, you must explicitly specify a clang IntelliSense mode when building with clang or clang-cl. | +| `intelliSenseOptions` | A map of extra IntelliSense configuration options.

`useCompilerDefaults`: A `bool` that specifies whether to use the compiler default defines and include paths for IntelliSense. Should only be `false` if the compilers in use don't support gcc-style arguments. Defaults to `true`.

`additionalCompilerArgs`: An array of extra options to control IntelliSense in Visual Studio. This option supports macro expansion. | | `enableMicrosoftCodeAnalysis` | A `bool` that enables Microsoft code analysis in Visual Studio when building with `cl` or `clang-cl`. Defaults to `false`. | -| `codeAnalysisRulset` | Specifies the ruleset to use when running Microsoft code analysis in Visual Studio. This can be a path to a ruleset file, or the name of a ruleset file installed with Visual Studio. This option supports macro expansion. | +| `codeAnalysisRuleset` | Specifies the ruleset to use when running Microsoft code analysis in Visual Studio. You can use a path to a ruleset file, or the name of a ruleset file installed with Visual Studio. This option supports macro expansion. | | `disableExternalAnalysis` | A `bool` that specifies whether code analysis should run on external headers in Visual Studio. | -| `codeAnalysisExternalRuleset` | Specifies the ruleset to use when running Microsoft code analysis on external header in Visual Studio. This can be a path to a ruleset file, or the name of a ruleset file installed with Visual Studio. This option supports macro expansion. | +| `codeAnalysisExternalRuleset` | Specifies the ruleset to use when running Microsoft code analysis on external header in Visual Studio. You can use a path to a ruleset file, or the name of a ruleset file installed with Visual Studio. This option supports macro expansion. | | `enableClangTidyCodeAnalysis` | A bool that enables clang-tidy code analysis in Visual Studio when building with `clang-cl`. Defaults to `false`. | -| `clangTidyChecks` | A comma-separated list of warnings passed to clang-tidy when running clang-tidy code analysis in Visual Studio. Wildcards are allowed, and the `–` prefix will remove checks. | -| `cacheRoot` | Specifies the path to a CMake cache. This directory should contain an existing `CMakeCache.txt` file. This key is only supported by the Open Existing Cache scenario in Visual Studio. This option supports macro expansion. | -| `cmakeGenerateCommand` | A command-line tool (specified as a command-line program + arguments, for example, "gencache.bat debug") to generate the CMake cache. This command will run from the shell in the preset’s specified environment when CMake configure is invoked. This key is only supported by the [Open Existing Cache](https://devblogs.microsoft.com/cppblog/open-existing-cmake-caches-in-visual-studio/) scenario in Visual Studio. This option supports macro expansion | +| `clangTidyChecks` | A comma-separated list of warnings passed to clang-tidy when running clang-tidy code analysis in Visual Studio. Wildcards are allowed, and the `-` prefix will remove checks. | +| `cacheRoot` | Specifies the path to a CMake cache. This directory should contain an existing *`CMakeCache.txt`* file. This key is only supported by the Open Existing Cache scenario in Visual Studio. This option supports macro expansion. | +| `cmakeGenerateCommand` | A command-line tool (specified as a command-line program and arguments, for example, **`gencache.bat debug`**) to generate the CMake cache. This command runs in the shell using the specified environment of the preset when CMake configure is invoked. This key is only supported by the [Open Existing Cache](https://devblogs.microsoft.com/cppblog/open-existing-cmake-caches-in-visual-studio/) scenario in Visual Studio. This option supports macro expansion. | ## Visual Studio Remote Settings vendor map -One vendor map with the vendor URI ` microsoft.com/VisualStudioRemoteSettings/CMake/` is allowed per Configure Preset and contains options specific to remote development in Visual Studio. Remote development means you're invoking CMake on a remote SSH connection or WSL. None of the options in the Visual Studio Remote Settings vendor map apply to Visual Studio Code. +One vendor map with the vendor URI `microsoft.com/VisualStudioRemoteSettings/CMake/` is allowed per Configure Preset and contains options specific to remote development in Visual Studio. Remote development means you're invoking CMake on a remote SSH connection or WSL. None of the options in the Visual Studio Remote Settings vendor map apply to Visual Studio Code. -All settings in the Visual Studio Remote Settings vendor map are optional and inherited from Configure Presets specified by the `inherits` key. Only options that have been modified are written to the file. The Visual Studio Remote Settings vendor map is supported by both `CMakePresets.json` and `CMakeUserPresets.json`. +All settings in the Visual Studio Remote Settings vendor map are optional and inherited from Configure Presets specified by the `inherits` key. Only options that have been modified are written to the file. The Visual Studio Remote Settings vendor map is supported by both *`CMakePresets.json`* and *`CMakeUserPresets.json`*. -None of the options in the Visual Studio Settings vendor map impact the construction of the CMake or CTest command line. This ensures that the same `CMakePresets.json` file can be used to drive CMake with Visual Studio, Visual Studio Code, and from the command line. +The options in the Visual Studio Settings vendor map don't affect the construction of the CMake or CTest command line. It's so the same *`CMakePresets.json`* file can be used to drive CMake with Visual Studio, Visual Studio Code, and from the command line. -Many of the options in the Visual Studio Remote Settings vendor map are ignored when targeting WSL1. This is because the WSL1 toolset executes all commands locally and relies on Windows drives mounted under the `/mnt` folder to access local source files from WSL1. No source file copy is required. Options that are ignored when targeting WSL1 have been explicitly marked. +Many of the options in the Visual Studio Remote Settings vendor map are ignored when targeting WSL1. It's because the WSL1 toolset executes all commands locally and relies on Windows drives mounted under the `/mnt` folder to access local source files from WSL1. No source file copy is required. Options that are ignored when targeting WSL1 have been explicitly marked. | Setting | Description | |--|--| -|`sourceDir` | Path to the directory on the remote system where the project will be copied. Defaults to `$env{HOME}/.vs/$ms{projectDirName}`. This option supports macro expansion.

In remote copy scenarios, the macro` ${sourceDir}` evaluates to the project source directory on the remote system and not the project source directory on the Windows machine. Remote copy scenarios include targeting a remote SSH connection. In these cases, the project source directory on the remote system will be determined by the value of sourceDir in the Visual Studio Remote Settings vendor map. This option is ignored when targeting WSL1. | -|`copySources` | If `true`, Visual Studio will copy sources from Windows to the remote system. Set to `false` if you manage file synchronization yourself. Defaults to true. This option is ignored when targeting WSL1. | -|`copySourcesOptions` | An object of options related to the source copy from Windows to the remote system. This object is ignored when targeting WSL1.

`copySourcesOptions.exclusionList`: A list of paths to be excluded when copying source files to the remote system. A path can be the name of a file or directory, or a path relative to the root of the copy. Defaults to `[ ".vs", ".git", "out" ]`. This option supports macro expansion.

`copySourcesOptions.method`: The method used to copy source files to the remote system. Accepted values are `rsync` and `sftp`. Defaults to `rsync`.

`copySourcesOptions.concurrentCopies`: The number of concurrent copies used during the synchronization of sources to the remote system. Defaults to `5`.

`copySourcesOptions.outputVerbosity`: The verbosity level of source copy operations to the remote system. Accepted levels are `Normal`, `Verbose`, and `Diagnostic`. Defaults to `Normal`.| -|`rsyncCommandArgs` | A list of additional command-line arguments passed to `rsync`. Defaults to `[ "-t", "--delete", "--delete-excluded" ]`. This option supports macro expansion and is ignored when targeting WSL1. | -|`copyBuildOutput` | Specifies whether to copy build output from the remote system back to Windows. Defaults to `false`. This option is ignored when targeting WSL1. | -|`copyOptimizations` | An object of options related to source copy optimizations. These options are ignored when targeting WSL1.

`copyOptimizations.maxSmallChange`: The maximum number of files to copy using sftp instead of rsync. Defaults to 10.

`copyOptimizations.useOptimizations`: Specifies the copy optimizations in use. Accepted values are no copy optimizations (`None`), rsync only optimizations (`RsyncOnly`), or rsync and sftp optimizations (`RsyncAndSftp`). Defaults to `RsyncAndSftp`.

`copyOptimizations.rsyncSingleDirectoryCommandArgs`: A list of additional command-line arguments passed to rsync when copying the contents of a single directory to the remote system. Defaults to `[ "-t", "-d" ]`. This option supports macro expansion. | -|`copyAdditionalIncludeDirectoriesList` | A list of paths to remote header directories to be copied locally for IntelliSense. This option supports macro expansion. | -|`copyExcludeDirectoriesList` | A list of paths to remote header directories to not be copied locally for IntelliSense. This option supports macro expansion. | -|`forceWSL1Toolset` | If `true`, Visual Studio will always use the WSL1 toolset when targeting WSL from Visual Studio. The WSL1 toolset executes all commands locally and relies on Windows drives mounted under the `/mnt` folder to access local source files from WSL. These options may be slower with WSL2. Defaults to `false`.

The WSL1 toolset will always be used in Visual Studio 2019 version 16.10. This option will be relevant once native support for WSL2 is available. | +| `sourceDir` | Path to the directory on the remote system where the project will be copied. Defaults to `$env{HOME}/.vs/$ms{projectDirName}`. This option supports macro expansion.

In remote copy scenarios, the macro `${sourceDir}` evaluates to the project source directory on the remote system and not the project source directory on the Windows machine. Remote copy scenarios include targeting a remote SSH connection. In these cases, the project source directory on the remote system is determined by the value of `sourceDir` in the Visual Studio Remote Settings vendor map. This option is ignored when targeting WSL1. | +| `copySources` | If `true`, Visual Studio will copy sources from Windows to the remote system. Set to `false` if you manage file synchronization yourself. Defaults to `true`. This option is ignored when targeting WSL1. | +| `copySourcesOptions` | An object of options related to the source copy from Windows to the remote system. This object is ignored when targeting WSL1.

`copySourcesOptions.exclusionList`: A list of paths to be excluded when copying source files to the remote system. A path can be the name of a file or directory, or a relative path from the root of the copy. Defaults to `[ ".vs", ".git", "out" ]`. This option supports macro expansion.

`copySourcesOptions.method`: The method used to copy source files to the remote system. Accepted values are `rsync` and `sftp`. Defaults to `rsync`.

`copySourcesOptions.concurrentCopies`: The number of concurrent copies used during the synchronization of sources to the remote system. Defaults to `5`.

`copySourcesOptions.outputVerbosity`: The verbosity level of source copy operations to the remote system. Accepted levels are `Normal`, `Verbose`, and `Diagnostic`. Defaults to `Normal`. | +| `rsyncCommandArgs` | A list of command-line arguments passed to `rsync`. Defaults to `[ "-t", "--delete", "--delete-excluded" ]`. This option supports macro expansion and is ignored when targeting WSL1. | +| `copyBuildOutput` | Specifies whether to copy build output from the remote system back to Windows. Defaults to `false`. This option is ignored when targeting WSL1. | +| `copyOptimizations` | An object of options related to source copy optimizations. These options are ignored when targeting WSL1.

`copyOptimizations.maxSmallChange`: The maximum number of files to copy using sftp instead of rsync. Defaults to 10.

`copyOptimizations.useOptimizations`: Specifies the copy optimizations in use. Accepted values are no copy optimizations (`None`), rsync only optimizations (`RsyncOnly`), or rsync and sftp optimizations (`RsyncAndSftp`). Defaults to `RsyncAndSftp`.

`copyOptimizations.rsyncSingleDirectoryCommandArgs`: A list of command-line arguments passed to rsync when copying the contents of a single directory to the remote system. Defaults to `[ "-t", "-d" ]`. This option supports macro expansion. | +| `copyAdditionalIncludeDirectoriesList` | A list of paths to remote header directories to be copied locally for IntelliSense. This option supports macro expansion. | +| `copyExcludeDirectoriesList` | A list of paths to remote header directories to not be copied locally for IntelliSense. This option supports macro expansion. | +| `forceWSL1Toolset` | If `true`, Visual Studio will always use the WSL1 toolset when targeting WSL from Visual Studio. The WSL1 toolset executes all commands locally and relies on Windows drives mounted under the `/mnt` folder to access local source files from WSL. These options may be slower with WSL2. Defaults to `false`.

The WSL1 toolset will always be used in Visual Studio 2019 version 16.10. This option will be relevant once native support for WSL2 is available. | ## Remote pre-build and post-build events -Options for a `remotePrebuildEvent` and `remotePostbuildEvent` have been deprecated with the adoption of `CMakePresets.json`. +Options for a `remotePrebuildEvent` and `remotePostbuildEvent` have been deprecated with the adoption of *`CMakePresets.json`*. - Encode pre-build, pre-link, and post-build events in your CMakeLists.txt using [add_custom_command](https://cmake.org/cmake/help/latest/command/add_custom_command.html#build-events). This will ensure the same behavior when building with Visual Studio and from the command line. +Encode pre-build, pre-link, and post-build events in your *`CMakeLists.txt`* using [`add_custom_command`](https://cmake.org/cmake/help/latest/command/add_custom_command.html#build-events). It ensures the same behavior when building with Visual Studio and from the command line. -If you need behavior that is specific to Visual Studio, you can add a custom remote task in` tasks.vs.json`. To get started, right-click on your root `CMakeLists.txt` in the **Solution Explorer** from **Folder View** and select **Configure Tasks**. You can then [add a new remote task](/cpp/build/tasks-vs-json-schema-reference-cpp#remote-properties) to your `tasks.vs.json` file. +If you need behavior that is specific to Visual Studio, you can add a custom remote task in *`tasks.vs.json`*. To get started, right-click on your root *`CMakeLists.txt`* in the **Solution Explorer** from **Folder View** and select **Configure Tasks**. You can then [add a new remote task](./tasks-vs-json-schema-reference-cpp.md#remote-properties) to your *`tasks.vs.json`* file. The following remote task creates a directory called test on the remote Linux system: @@ -82,13 +82,13 @@ The following remote task creates a directory called test on the remote Linux sy } ``` -Right-click on any `CMakeLists.txt` and select the **mkdir** option to execute this task. +Right-click on any *`CMakeLists.txt`* and select the **mkdir** option to execute this task. The value of `remoteMachineName` must match the Host Name of a connection in the **Connection Manager**. ## Microsoft vendor macros -The two Microsoft vendor maps, `Visual Studio Settings` and `Visual Studio Remote Settings`, support all the macros defined by CMake. Our vendor maps support all the macros defined by CMake. See [cmake-presets Macro Expansion](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#macro-expansion) for more information. All macros and environment variables are expanded before being passed to `cmake.exe`. +The two Microsoft vendor maps, `Visual Studio Settings` and `Visual Studio Remote Settings`, support all the macros defined by CMake. Our vendor maps support all the macros defined by CMake. For more information, see [cmake-presets Macro Expansion](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#macro-expansion). All macros and environment variables are expanded before being passed to CMake. Visual Studio supports vendor macros with the prefix `ms`. Microsoft vendor macros can only be used in Microsoft vendor maps. CMake can't use presets that have vendor macros outside of a vendor map. @@ -100,19 +100,19 @@ Visual Studio supports vendor macros with the prefix `ms`. Microsoft vendor macr |Macro |Description | |---------|---------| -| `$env{}`
`$penv{}`| Reference environment variables using this syntax supported by CMake. See [cmake-presets Macro Expansion](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#macro-expansion) for more information. | +| `$env{}`
`$penv{}`| Reference environment variables using this syntax supported by CMake. For more information, see [cmake-presets Macro Expansion](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#macro-expansion). | ## Deprecated macros -A few macros that were supported by CMakeSettings.json have been deprecated with the adoption of `CMakePresets.json`. +A few macros that were supported by *`CMakeSettings.json`* have been deprecated with the adoption of *`CMakePresets.json`*. -Use the macros supported by CMake to construct your file paths. This will ensure that the same `CMakePresets.json` file works inside Visual Studio and from the command line. +Use the macros supported by CMake to construct your file paths. When you use the macros, it ensures that the same *`CMakePresets.json`* file works inside Visual Studio and from the command line. -| Deprecated macro | Recommendation | -|---------|---------| -|`${projectFile} ` | `${sourceDir}/CMakeLists.txt` | -| `${thisFile}` | ` ${sourceDir}/CMakePresets.json` | +| Deprecated macro | Recommendation | +|--|--| +| `${projectFile}` | `${sourceDir}/CMakeLists.txt` | +| `${thisFile}` | `${sourceDir}/CMakePresets.json` | ## Accepted shell syntax -Use the `$env{HOME}` syntax to reference `$HOME` when constructing Linux paths in the Microsoft vendor maps. \ No newline at end of file +Use the `$env{HOME}` syntax to reference `$HOME` when constructing Linux paths in the Microsoft vendor maps. diff --git a/docs/build/cmake-presets-vs.md b/docs/build/cmake-presets-vs.md index 8c97b0947d..8aface6d9b 100644 --- a/docs/build/cmake-presets-vs.md +++ b/docs/build/cmake-presets-vs.md @@ -1,51 +1,62 @@ --- title: Configure and build with CMake Presets description: "Reference for using CMake Presets to configure and build CMake projects." -ms.date: 04/15/2021 +ms.date: 06/09/2023 ms.topic: reference --- # Configure and build with CMake Presets in Visual Studio -CMake supports two files that allow users to specify common configure, build, and test options and share them with others: `CMakePresets.json` and `CMakeUserPresets.json`. Use these files to drive CMake in Visual Studio and Visual Studio Code, in a continuous integration (CI) pipeline, and from the command line. +CMake supports two files that allow users to specify common configure, build, and test options and share them with others: *`CMakePresets.json`* and *`CMakeUserPresets.json`*. Use these files to drive CMake in Visual Studio and Visual Studio Code, in a continuous integration (CI) pipeline, and from the command line. -`CMakePresets.json` is for saving project-wide builds. `CMakeUserPresets.json` is for developers to save their own local builds. Both files are supported in Visual Studio 2019 version 16.10 or later. +*`CMakePresets.json`* is for saving project-wide builds. *`CMakeUserPresets.json`* is for developers to save their own local builds. Both files are supported in Visual Studio 2019 version 16.10 or later. -This article contains information about `CMakePresets.json` integration with Visual Studio. Here are helpful links: +This article contains information about *`CMakePresets.json`* integration with Visual Studio. Here are helpful links: -- For more information about the format of `CMakePresets.json`, see the official [CMake documentation](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#id1). +- For more information about the format of *`CMakePresets.json`*, see the official [CMake documentation](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#id1). - For more information about the Microsoft vendor maps and macro expansion, see [`CMakePresets.json` and `CMakeUserPresets.json` Microsoft vendor maps](cmake-presets-json-reference.md). -- For more information about how to use `CMakePresets.json` in Visual Studio Code, see [Configure and build with CMake Presets](https://github.com/microsoft/vscode-cmake-tools/tree/develop/docs/cmake-presets.md). +- For more information about how to use *`CMakePresets.json`* in Visual Studio Code, see [Configure and build with CMake Presets](https://github.com/microsoft/vscode-cmake-tools/blob/main/docs/cmake-presets.md). -We recommend `CMakePresets.json` as an alternative to `CMakeSettings.json`. Visual Studio will never read from both `CMakePresets.json` and `CMakeSettings.json` at the same time. To enable or disable `CMakePresets.json` integration in Visual Studio, see [Enable `CMakePresets.json` in Visual Studio 2019](#enable-cmakepresetsjson-integration-in-visual-studio-2019). +We recommend *`CMakePresets.json`* as an alternative to *`CMakeSettings.json`*. Visual Studio never reads from both *`CMakePresets.json`* and *`CMakeSettings.json`* at the same time. To enable or disable *`CMakePresets.json`* integration in Visual Studio, see [Enable `CMakePresets.json` in Visual Studio 2019](#enable-cmakepresets-json-integration). -## Supported CMake and `CMakePresets.json` versions +## Supported CMake and *`CMakePresets.json`* versions -Visual Studio supports version 2 or later for the `CMakePresets.json` and `CMakeUserPresets.json` files. You can update your file version by incrementing the version field in the root object. For an example and more information, see [`CMakePresets.json` format](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#format). +The supported *`CMakePresets.json`* and *`CMakeUserPresets.json`* schema versions depend on your version of Visual Studio: +- Visual Studio 2019 version 16.10 and later support schema versions 2 and 3. +- Visual Studio 2022 version 17.4 preview 1 adds support for schema version 4. +- Visual Studio 2022 version 17.5 preview 1 adds support for schema version 5. -CMake version 3.20 or later is required when you're invoking CMake with `CMakePresets.json` (version 2 or later) from the command line. However, Visual Studio reads and evaluates `CMakePresets.json` and `CMakeUserPresets.json` itself and doesn't invoke CMake directly with the `--preset` option. So, CMake version 3.20 or later isn't strictly required when you're building with `CMakePresets.json` inside Visual Studio. We recommend using CMake version 3.14 or later. +You can update the version by changing the `"version"` field in the root object. For an example and more information, see [`CMakePresets.json` format](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#format). -## Enable `CMakePresets.json` integration in Visual Studio 2019 +CMake version 3.20 or later is required when you're invoking CMake with *`CMakePresets.json`* from the command line. However, Visual Studio reads and evaluates *`CMakePresets.json`* and *`CMakeUserPresets.json`* itself and doesn't invoke CMake directly with the `--preset` option. So, CMake version 3.20 or later isn't strictly required when you're building with *`CMakePresets.json`* inside Visual Studio. -`CMakePresets.json` integration isn't enabled by default in Visual Studio 2019. You can enable it for all CMake projects in **Tools** > **Options** > **CMake** > **General**: +We recommend using at least CMake version 3.14 or later. -![Screenshot showing the checkbox to enable CMakePresets.json on the CMake General page of the Tools Options dialog.](./media/enable-cmakepresets.png) +## Enable *`CMakePresets.json`* integration in Visual Studio -> [!Important] +*`CMakePresets.json`* integration isn't enabled by default in Visual Studio. You can enable it in **Tools** > **Options** > **CMake** > **General**: + +:::image type="complex" source="./media/enable-cmakepresets-new.png" alt-text="Screenshot showing 'Always use CMakePresets.json' selected."::: +This screen is reached from the Visual Studio 2022 menu: Tools > Options > CMake > General. The option is under the CMake configure file section. +:::image-end::: + +> [!IMPORTANT] > Close and reopen the folder in Visual Studio to activate the integration. -If you don't want to enable `CMakePresets.json` integration for all CMake projects, you can enable `CMakePresets.json` integration for a single CMake project by adding a `CMakePresets.json` file to the root of the open folder. You must close and reopen the folder in Visual Studio to activate the integration. +In some older versions of Visual Studio, **Tools** > **Options** > **CMake** > **General** only has a single option to enable *`CMakePresets.json`* integration: -The following table indicates when `CMakePresets.json` is used instead of `CMakeSettings.json` to drive CMake configuration and build. If no configuration file is present, default Configure Presets are used. +:::image type="content" source="./media/enable-cmakepresets.png" alt-text="Screenshot of an older version of Visual Studio. There is a checkbox labeled 'Use C Make Presets .json to drive CMake configure, build, and test.'"::: + +The following table indicates when *`CMakePresets.json`* is used instead of *`CMakeSettings.json`* to drive CMake configuration and build in Visual Studio 2022 and Visual Studio 2019 version 16.10 and later. If no configuration file is present, default Configure Presets are used. In the table, "**Tools** > **Options** enabled" means **Use CMakePresets.json to drive CMake configure, build, and test** is selected in **Tools** > **Options** > **CMake** > **General**. | Configuration files | Tools > Options disabled | Tools > Options enabled | |--|--|--| -| No configuration file present | `CMakeSettings.json` | `CMakePresets.json` | -| `CMakeSettings.json` present | `CMakeSettings.json` | `CMakePresets.json` | -| `CMakePresets.json` present | `CMakePresets.json` | `CMakePresets.json` | -| Both configuration files present | `CMakePresets.json` | `CMakePresets.json` | +| No configuration file present | *`CMakeSettings.json`* | *`CMakePresets.json`* | +| *`CMakeSettings.json`* present | *`CMakeSettings.json`* | *`CMakePresets.json`* | +| *`CMakePresets.json`* present | *`CMakePresets.json`* | *`CMakePresets.json`* | +| Both configuration files present | *`CMakePresets.json`* | *`CMakePresets.json`* | ## Modify automatic configuration and cache notifications @@ -53,9 +64,9 @@ By default, Visual Studio automatically invokes `configure` each time the active ## Default Configure Presets -If no `CMakePresets.json` or `CMakeUserPresets.json` file exists, or if `CMakePresets.json` or `CMakeUserPresets.json` is invalid, Visual Studio will fall back on the following default Configure Presets: +If no *`CMakePresets.json`* or *`CMakeUserPresets.json`* file exists, or if *`CMakePresets.json`* or *`CMakeUserPresets.json`* is invalid, Visual Studio falls back on the following default Configure Presets: -**Windows example** +### Windows example ```json { @@ -80,7 +91,7 @@ If no `CMakePresets.json` or `CMakeUserPresets.json` file exists, or if `CMakePr }, ``` -**Linux example** +### Linux example ```json { @@ -104,19 +115,21 @@ If no `CMakePresets.json` or `CMakeUserPresets.json` file exists, or if `CMakePr } ``` -If you try to open or modify a `CMakePresets.json` file that doesn't exist, Visual Studio automatically creates a `CMakePresets.json` file with the default Configure Presets at the root of your project. +If you try to open or modify a *`CMakePresets.json`* file that doesn't exist, Visual Studio automatically creates a *`CMakePresets.json`* file with the default Configure Presets at the root of your project. ## Configure and build -Visual Studio provides three dropdown lists when `CMakePresets.json` integration is enabled: +On the Visual Studio toolbar, there are dropdowns for the Target Systems, Configure Presets, and Build Presets when *`CMakePresets.json`* integration is enabled: -![Screenshot that shows the dropdown lists for the Target System](./media/target-system-dropdown.png) +:::image type="content" source="./media/target-system-dropdown.png" alt-text="Screenshot showing the dropdowns for target system set to Local Machine, configuration set to windows-arm64, and build preset set to default."::: ### Select a Target System The dropdown list on the left indicates the active *Target System*. It's the system on which CMake is invoked to configure and build the project. This dropdown list includes your local machine, all SSH connections in Connection Manager by host name, and all Windows Subsystem for Linux (WSL) installations that Visual Studio can find: -![Screenshot of the selections in the dropdown list for the Target System.](./media/target-system-selections.png) +:::image type="complex" source="./media/target-system-selections.png" alt-text="Screenshot of the Target System dropdown list"::: +The dropdown list contains several entries including Local Machine, an ip address 192.168.0.5, WSL: ubuntu2004, WSL: debian, and Manage Connections. +:::image-end::: In the preceding example: @@ -127,23 +140,23 @@ Select **Manage Connections** to open Connection Manager. ### Select a Configure Preset -The dropdown list in the middle indicates the active *Configure Preset*. It's the `configurePreset` value that's used when CMake is invoked to generate the project build system. This dropdown list includes the union of non-hidden Configure Presets defined in `CMakePresets.json` and `CMakeUserPresets.json`. +The dropdown list in the middle indicates the active *Configure Preset*. It's the `configurePreset` value that's used when CMake is invoked to generate the project build system. This dropdown list includes the union of non-hidden Configure Presets defined in *`CMakePresets.json`* and *`CMakeUserPresets.json`*. -Visual Studio will use the value of `hostOS` in the Microsoft Visual Studio Settings vendor map to hide Configure Presets that don't apply to the active Target System. For more information, see the entry for `hostOS` in the table under [Visual Studio Settings vendor map](cmake-presets-json-reference.md#visual-studio-settings-vendor-map). +Visual Studio uses the value of `hostOS` in the Microsoft Visual Studio Settings vendor map to hide Configure Presets that don't apply to the active Target System. For more information, see the entry for `hostOS` in the table under [Visual Studio Settings vendor map](cmake-presets-json-reference.md#visual-studio-settings-vendor-map). -Select **Manage Configurations** to open the `CMakePresets.json` file located at the root of the project. `CMakePresets.json` is created if it doesn't already exist. +Select **Manage Configurations** to open the *`CMakePresets.json`* file located at the root of the project. *`CMakePresets.json`* is created if it doesn't already exist. ### Select a Build Preset -The dropdown list on the right indicates the active *Build Preset*. It's the `buildPreset` value that's used when CMake is invoked to build the project. This dropdown list includes the union of non-hidden Build Presets defined in `CMakePresets.json` and `CMakeUserPresets.json`. +The dropdown list on the right indicates the active *Build Preset*. It's the `buildPreset` value that's used when CMake is invoked to build the project. This dropdown list includes the union of non-hidden Build Presets defined in *`CMakePresets.json`* and *`CMakeUserPresets.json`*. -All Build Presets are required to specify an associated `configurePreset` value. Visual Studio hides Build Presets that don't apply to the active Configure Preset. For more information, see the [list of Build Presets](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#build-preset). +All Build Presets are required to specify an associated `configurePreset` value. Visual Studio hides Build Presets that don't apply to the active Configure Preset. For more information, see the [list of Build Presets](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#build-preset). -If there are no Build Presets associated with the active Configure Preset, Visual Studio will list the default Build Preset. The default Build Preset is equivalent to passing `cmake --build` with no other arguments from the command line. +If there are no Build Presets associated with the active Configure Preset, Visual Studio lists the default Build Preset. The default Build Preset is equivalent to passing `cmake --build` with no other arguments from the command line. ### Configure -Visual Studio automatically tries to configure the project when it detects that the CMake cache is out of date. To manually invoke the configuration, select **Project** > **Configure \** from the main menu. It's the same as running `cmake --preset ` from the command line, where `` is the name of the active Configure Preset. +Visual Studio automatically tries to configure the project when it detects that the CMake cache is out of date. To manually invoke the configuration, select **Project** > **Configure \** from the main menu. It's the same as running `cmake --preset ` from the command line, where `` is the name of the active Configure Preset. To disable automatic cache generation, see [Automatic configuration and cache notifications](#modify-automatic-configuration-and-cache-notifications). @@ -154,36 +167,36 @@ To build the entire project, select **Build** > **Build All** from the main menu To build a single target, switch to **CMake Targets View** in Solution Explorer. Then right-click any target and select **Build** from the shortcut menu. > [!NOTE] -> Visual Studio 2019 doesn't support the `buildPresets.targets` option to build a subset of targets specified in `CMakePresets.json`. +> Visual Studio 2019 doesn't support the `buildPresets.targets` option to build a subset of targets specified in *`CMakePresets.json`*. ## Run CTest -`CMakePresets.json` supports two menu options in Visual Studio 2019: +*`CMakePresets.json`* supports two menu options in Visual Studio 2019: - **Test** > **Run CTests** for \ invokes CTest and runs all tests associated with the active Configure Preset and Build Preset, with no other arguments passed to CTest. - **Test** > **Run Test Preset** for \ expands to show all Test Presets associated with the active Configure Preset. Selecting a single Test Preset is the same as running `ctest --preset ` from the command line, where `` is the name of the selected Test Preset. This option is unavailable if no Test Presets are defined for the active Configure Preset. -In Visual Studio 2019, Test Explorer isn't integrated with `CMakePresets.json`. +In Visual Studio 2019, Test Explorer isn't integrated with *`CMakePresets.json`*. ## Add new presets -In Visual Studio 2019, all commands and preset templates modify `CMakePresets.json`. You can add new user-level presets by directly editing `CMakeUserPresets.json`. +In Visual Studio 2019, all commands and preset templates modify *`CMakePresets.json`*. You can add new user-level presets by directly editing *`CMakeUserPresets.json`*. -Use a forward slash (`/`) for paths in `CMakePresets.json` and `CMakeUserPresets.json`. +Use a forward slash (`/`) for paths in *`CMakePresets.json`* and *`CMakeUserPresets.json`*. ### Add new Configure Presets -To add a new Configure Preset to `CMakePresets.json`, from **Solution Explorer**, right-click `CMakePresets.json` from **Folder View** and select **Add Configure Preset** from the shortcut menu. The dialog to select a Configure Preset template appears: +To add a new Configure Preset to *`CMakePresets.json`*, from **Solution Explorer**, right-click *`CMakePresets.json`* from **Folder View** and select **Add Configuration** from the shortcut menu. The dialog to select a Configure Preset template appears: -![Screenshot of the dialog for adding a Configure Preset to the J S O N file.](./media/add-configure-preset-to-cmakepresets.png) +:::image type="content" source="./media/add-configure-preset-to-cmakepresets.png" alt-text="Screenshot of the Add Configure Preset to the JSON file dialog. It contains entries such as Linux Debug, macOS Debug, x64 Debug, and so on."::: -Select the **Windows x64 Debug** template to configure on Windows systems. Select the **Linux Debug** template to configure on WSL and remote Linux systems. For more information about editing `CMakePresets.json`, see [Edit presets](#edit-presets). +Select the **Windows x64 Debug** template to configure on Windows systems. Select the **Linux Debug** template to configure on WSL and remote Linux systems. For more information about editing *`CMakePresets.json`*, see [Edit presets](#edit-presets). -The selected template is added to `CMakePresets.json` if it exists. Otherwise, the template is copied into a new `CMakePresets.json` file. +The selected template is added to *`CMakePresets.json`* if it exists. Otherwise, the template is copied into a new *`CMakePresets.json`* file. ### Add new Build Presets and Test Presets -Visual Studio 2019 doesn't offer templates for new Build Presets and Test Presets. You can add Build Presets and Test Presets by directly editing `CMakePresets.json`. For more information, see the [list of Build Presets](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#build-preset), the [list of Test Presets](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#test-preset), or [an example `CMakePresets.json` file](#example-cmakepresetsjson-file). +Visual Studio 2019 doesn't offer templates for new Build Presets and Test Presets. You can add Build Presets and Test Presets by directly editing *`CMakePresets.json`*. For more information, see the [list of Build Presets](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#build-preset), the [list of Test Presets](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#test-preset), or [an example `CMakePresets.json` file](#example-cmakepresetsjson-file). ## Edit presets @@ -223,6 +236,25 @@ Build with `clang`: } ``` +If you use either `Visual Studio 16 2019` or `Visual Studio 17 2022` as your generator, you can use the `toolset` Configure Preset to specify the `ClangCL` toolset: + +```json +"cacheVariables": { + "CMAKE_BUILD_TYPE": "Debug", + "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}", +}, + +"toolset": "ClangCL", + +"vendor": { + "microsoft.com/VisualStudioSettings/CMake/1.0": { + "intelliSenseMode": "windows-clang-x64" + } +} +``` + +For more information on generators that support the `toolset` specification, see [`CMAKE_GENERATOR_TOOLSET`](https://cmake.org/cmake/help/latest/variable/CMAKE_GENERATOR_TOOLSET.html) in the CMake documentation. + > [!IMPORTANT] > In Visual Studio 2019, you must explicitly specify a Clang IntelliSense mode when you're building with `clang` or `clang-cl`. @@ -260,9 +292,15 @@ You can set the target architecture (x64, Win32, ARM64, or ARM) by using `archit You can set the host architecture (x64 or x86) and toolset by using `toolset.value`. It's equivalent to passing `-T` to CMake from the command line. For more information, see [Toolset Selection](https://cmake.org/cmake/help/latest/generator/Visual%20Studio%2016%202019.html#toolset-selection). -The `architecture.strategy` and `toolset.strategy` values tell CMake how to handle the architecture and toolset fields. `set` means CMake will set the respective value, and `external` means CMake won't set the respective value. +The `architecture.strategy` and `toolset.strategy` values tell CMake how to handle the architecture and toolset fields. `set` means CMake sets the respective value, and `external` means CMake won't set the respective value. + +We recommend using `set` with IDE generators like the Visual Studio Generator. Use `external` with command-line generators like Ninja. These values allow vendors like Visual Studio to supply the required environment before CMake is invoked. For more information about the architecture and toolset fields, see the [list of Configure Presets](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#configure-preset). -You should use `set` with IDE generators like the Visual Studio Generator. You should use `external` with command-line generators like Ninja. These values allow vendors like Visual Studio to source the required environment before CMake is invoked. For more information about the architecture and toolset fields, see the [list of Configure Presets](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#configure-preset). +If you don't want to source an environment, you can set `architecture.strategy` to `external` and `architecture.value` to `unspecified`. You might find it useful not to source an environment for any one of these reasons: + +- You use a toolset other than MSVC. +- You use a custom toolchain, such as in embedded scenarios. +- You don't need a specific environment to build. For a full list of IDE generators that support the architecture field, see [`CMAKE_GENERATOR_PLATFORM`](https://cmake.org/cmake/help/latest/variable/CMAKE_GENERATOR_PLATFORM.html). For a full list of IDE generators that support the toolset field, see [`CMAKE_GENERATOR_TOOLSET`](https://cmake.org/cmake/help/latest/variable/CMAKE_GENERATOR_TOOLSET.html). @@ -284,9 +322,9 @@ Use the following examples to target ARM64 with the Ninja generator, or to targe ### Set and reference environment variables -You can set environment variables by using the environment map. Environment variables are inherited through the `inherits` field, but you can override them as you like. +You can set environment variables by using the environment map. Environment variables are inherited through the `inherits` field, but you can override them as you like. -A preset's environment is the union of its own environment and the environment from all its parents. If multiple `inherits` presets provide conflicting values for the same variable, the earlier preset in the `inherits` list is preferred. You can unset a variable inherited from another preset by setting it to `null`. +A preset's environment is the union of its own environment and the environment from all its parents. If multiple `inherits` presets provide conflicting values for the same variable, the earlier preset in the `inherits` list is preferred. You can unset a variable inherited from another preset by setting it to `null`. Environment variables set in a Configure Preset also automatically flow through to associated Build Presets and Test Presets, unless `inheritConfigureEnvironment` is set to `false`. For more information, see the [list of Configure Presets](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#configure-preset). @@ -298,11 +336,11 @@ By default, Visual Studio uses the IntelliSense mode that matches your specified ## Configure and build on a remote system or the Windows Subsystem for Linux -With `CMakePresets.json` support in Visual Studio, you can easily configure and build your project on Windows, WSL, and remote systems. The steps to [configure and build](#configure-and-build) your project on Windows, a remote system, or WSL are the same. However, a few behaviors are specific to remote development. +With *`CMakePresets.json`* support in Visual Studio, you can easily configure and build your project on Windows, WSL, and remote systems. The steps to [configure and build](#configure-and-build) your project on Windows, a remote system, or WSL are the same. However, a few behaviors are specific to remote development. ### `${sourceDir}` behavior in remote copy scenarios -In local scenarios (including WSL1), `${sourceDir}` evaluates to the path to the project source directory that's open in Visual Studio. In remote copy scenarios, `${sourceDir}` evaluates to the path to the project source directory on the Target System and not the project source directory on the local machine. +In local scenarios (including WSL1), `${sourceDir}` evaluates to the path to the project source directory that's open in Visual Studio. In remote copy scenarios, `${sourceDir}` evaluates to the path to the project source directory on the Target System and not the project source directory on the local machine. The value of `sourceDir` in the Visual Studio Remote Settings vendor map determines the project source directory on the Target System (defaults to `$env{HOME}/.vs/$ms{projectDirName}`). For more information, see the entry for `sourceDir` in the table under [Visual Studio Settings vendor map](cmake-presets-json-reference.md#visual-studio-settings-vendor-map). @@ -312,7 +350,7 @@ Remote copy scenarios require a local directory to copy some remote files like C ### Invoking the same Configure Preset on Windows and WSL1 -You'll see an error if you try to use the same Configure Preset on Windows and WSL1. Windows and WSL1 both use the Windows file system, so CMake will try to use the same output directory (`binaryDir`) for both the Windows and WSL1 build trees. +You'll see an error if you try to use the same Configure Preset on Windows and WSL1. Windows and WSL1 both use the Windows file system, so CMake will try to use the same output directory (`binaryDir`) for both the Windows and WSL1 build trees. If you want to use the same Configure Preset with both Windows and the WSL1 toolset, create a second Configure Preset that inherits from the original preset and specifies a new `binaryDir` value. In the following example, `windows-preset` can be used on Windows and `base-preset` can be used on WSL1: @@ -336,9 +374,9 @@ If you want to use the same Configure Preset with both Windows and the WSL1 tool Vcpkg helps you manage C and C++ libraries on Windows, Linux, and macOS. A vcpkg toolchain file (`vcpkg.cmake`) must be passed to CMake to enable vcpkg integration. For more information, see the [vcpkg documentation](https://github.com/microsoft/vcpkg#vcpkg-overview). -Visual Studio no longer passes your vcpkg toolchain file to CMake automatically when `CMakePresets.json` integration is enabled. This change eliminates Visual Studio-specific behavior and ensures that you can reproduce your build from the command line. +Visual Studio no longer passes your vcpkg toolchain file to CMake automatically when *`CMakePresets.json`* integration is enabled. This change eliminates Visual Studio-specific behavior and ensures that you can reproduce your build from the command line. -Instead, set the path to `vcpkg.cmake` by using the `VCPKG_ROOT` environment variable in `CMakePresets.json`: +Instead, set the path to `vcpkg.cmake` by using the `VCPKG_ROOT` environment variable in *`CMakePresets.json`*: ```json "cacheVariables": { @@ -349,31 +387,31 @@ Instead, set the path to `vcpkg.cmake` by using the `VCPKG_ROOT` environment var }, ``` -`VCPKG_ROOT` should be set to the root of your vcpkg installation. For more information, see [vcpkg environment variables](https://github.com/microsoft/vcpkg/blob/master/docs/users/config-environment.md). +`VCPKG_ROOT` should be set to the root of your vcpkg installation. For more information, see [vcpkg environment variables](/vcpkg/users/config-environment). -If you're already using a CMake toolchain file and want to enable vcpkg integration, see [Using multiple toolchain files](https://github.com/microsoft/vcpkg/blob/master/docs/users/integration.md#using-multiple-toolchain-files). Follow those instructions to use an external toolchain file with a project by using vcpkg. +If you're already using a CMake toolchain file and want to enable vcpkg integration, see [Using multiple toolchain files](/vcpkg/users/buildsystems/cmake-integration#using-multiple-toolchain-files). Follow those instructions to use an external toolchain file with a project by using vcpkg. -## Substitute variables in `launch.vs.json` and `tasks.vs.json` +## Variable substitution in *`launch.vs.json`* and *`tasks.vs.json`* -`CMakePresets.json` supports variable substitution in `launch.vs.json` and `tasks.vs.json`. Here are some considerations: +*`CMakePresets.json`* supports variable substitution in *`launch.vs.json`* and *`tasks.vs.json`*. Here are some considerations: -- Environment variables set in the active Configure Preset automatically flow through to `launch.vs.json` and `tasks.vs.json` configurations. You can unset individual environment variables in `launch.vs.json` and `tasks.vs.json` by setting them to `null`. The following example sets the variable `DEBUG_LOGGING_LEVEL` to `null` in `launch.vs.json`: `"env": { "DEBUG_LOGGING_LEVEL": null }`. +- Environment variables set in the active Configure Preset automatically flow through to *`launch.vs.json`* and *`tasks.vs.json`* configurations. You can unset individual environment variables in *`launch.vs.json`* and *`tasks.vs.json`* by setting them to `null`. The following example sets the variable `DEBUG_LOGGING_LEVEL` to `null` in *`launch.vs.json`*: `"env": { "DEBUG_LOGGING_LEVEL": null }`. -- Key values set in the active Configure Preset are available for consumption in `launch.vs.json` and `tasks.vs.json` with the syntax `${cmake.}`. For example, use `${cmake.binaryDir}` to reference the output directory of the active Configure Preset. +- Key values set in the active Configure Preset are available for consumption in *`launch.vs.json`* and *`tasks.vs.json`* with the syntax `${cmake.}`. For example, use `${cmake.binaryDir}` to reference the output directory of the active Configure Preset. -- Individual environment variables set in the environment map of the active Configure Preset are available for consumption in `launch.vs.json` and `tasks.vs.json` through the syntax `${env.}`. +- Individual environment variables set in the environment map of the active Configure Preset are available for consumption in *`launch.vs.json`* and *`tasks.vs.json`* through the syntax `${env.}`. -Update your `launch.vs.json` and `task.vs.json` files to reference `CMakePresets.json` syntax instead of `CMakeSettings.json` syntax. Macros that reference the old `CMakeSettings.json` syntax when `CMakePresets.json` is the active configuration file are slated for deprecation in a future release. For example, reference the output directory of the active Configure Preset with `${cmake.binaryDir}` instead of `${cmake.buildRoot}`, because `CMakePresets.json` uses the `binaryDir` syntax. +Update your *`launch.vs.json`* and *`task.vs.json`* files to reference *`CMakePresets.json`* syntax instead of *`CMakeSettings.json`* syntax. Macros that reference the old *`CMakeSettings.json`* syntax when *`CMakePresets.json`* is the active configuration file are slated for deprecation in a future release. For example, reference the output directory of the active Configure Preset with `${cmake.binaryDir}` instead of `${cmake.buildRoot}`, because *`CMakePresets.json`* uses the `binaryDir` syntax. ## Troubleshoot If things aren't working as expected, you can try a few troubleshooting steps. -If either `CMakePresets.json` or `CMakeUserPresets.json` is invalid, Visual Studio will fall back on its default behavior and show only the default Configure Presets. Visual Studio IntelliSense can help you catch many of these JSON errors, but it won't know if you're referencing a preset with `inherits` or `configurePreset` by the wrong name. +If either *`CMakePresets.json`* or *`CMakeUserPresets.json`* is invalid, Visual Studio will fall back on its default behavior and show only the default Configure Presets. Visual Studio IntelliSense can help you catch many of these JSON errors, but it won't know if you're referencing a preset with `inherits` or `configurePreset` by the wrong name. To check if your preset files are valid, run `cmake --list-presets` from the command line at the root of your project directory. (CMake 3.20 or later is required.) If either file is invalid, you'll see the following error: -```DOS +```cmd CMake Error: Could not read presets from C:/Users//source/repos/: JSON parse error ``` @@ -388,15 +426,15 @@ If you've identified a problem, the best way to report it is by selecting the ** ## Enable logging for remote connections -You can enable logging for remote connections if you're having trouble connecting or copying files to a remote system. For more information, see [Logging for remote connections](/cpp/linux/connect-to-your-remote-linux-computer#logging-for-remote-connections). +You can enable logging for remote connections if you're having trouble connecting or copying files to a remote system. For more information, see [Logging for remote connections](../linux/connect-to-your-remote-linux-computer.md#logging-for-remote-connections). ## Enable AddressSanitizer for Windows and Linux -AddressSanitizer (ASan) is a runtime memory error detector for C and C++ that's supported in Visual Studio for both Windows and Linux development. AddressSanitizer was enabled with an option (`addressSanitizerEnabled`) in `CMakeSettings.json`. `CMakePresets.json` doesn't support this behavior. +Visual Studio supports AddressSanitizer (ASAN), a C and C++ runtime memory error detector, for both Windows and Linux development. The `addressSanitizerEnabled` option in *`CMakeSettings.json`* enables AddressSanitizer. *`CMakePresets.json`* doesn't support this behavior. -Instead, enable and disable AddressSanitizer by setting the required compiler and linker flags yourself. Setting them removes Visual Studio-specific behavior and ensures that the same `CMakePresets.json` file can reproduce your build from the command line. +Instead, enable and disable AddressSanitizer by setting the required compiler and linker flags yourself. Setting them removes Visual Studio-specific behavior and ensures that the same *`CMakePresets.json`* file can reproduce your build from the command line. -You can add the following sample to `CMakeLists.txt` to enable or disable AddressSanitizer for a target: +You can add the following sample to *`CMakeLists.txt`* to enable or disable AddressSanitizer for a target: ```cmd option(ASAN_ENABLED "Build this target with AddressSanitizer" ON) @@ -411,25 +449,25 @@ if(ASAN_ENABLED) endif() ``` -The `` part lists other compilation flags, like `"-fno-omit-frame-pointer"`. For more information about AddressSanitizer for Linux, see [Using AddressSanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizer#using-addresssanitizer). For more information about using AddressSanitizer with the Microsoft Visual C++ (MSVC) compiler, see [Use AddressSanitizer from a developer command prompt](/cpp/sanitizers/asan#command-prompt). +The `` part lists other compilation flags, like `"-fno-omit-frame-pointer"`. For more information about AddressSanitizer for Linux, see [Using AddressSanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizer#using-addresssanitizer). For more information about using AddressSanitizer with MSVC, see [Use AddressSanitizer from a developer command prompt](../sanitizers/asan.md#command-prompt). -Pass runtime flags to AddressSanitizer by using the `ASAN_OPTIONS` field in `launch.vs.json`. `ASAN_OPTIONS` defaults to `detect_leaks=0` when no other runtime options are specified because LeakSanitizer isn't supported in Visual Studio. +Pass runtime flags to AddressSanitizer by using the `ASAN_OPTIONS` field in *`launch.vs.json`*. `ASAN_OPTIONS` defaults to `detect_leaks=0` when no other runtime options are specified because LeakSanitizer isn't supported in Visual Studio. ## Run CMake from the command line or a CI pipeline -You can use the same `CMakePresets.json` and `CMakeUserPresets.json` files to invoke CMake in Visual Studio and from the command line. The [CMake](https://cmake.org/cmake/help/latest/manual/cmake.1.html) and [CTest](https://cmake.org/cmake/help/latest/manual/ctest.1.html) documentation are the best resources for invoking CMake and CTest with `--preset`. CMake version 3.20 or later is required. +You can use the same *`CMakePresets.json`* and *`CMakeUserPresets.json`* files to invoke CMake in Visual Studio and from the command line. The [CMake](https://cmake.org/cmake/help/latest/manual/cmake.1.html) and [CTest](https://cmake.org/cmake/help/latest/manual/ctest.1.html) documentation are the best resources for invoking CMake and CTest with `--preset`. CMake version 3.20 or later is required. ### Sourcing the environment when building with command-line generators on Windows -It's up to the user to configure the environment before CMake is invoked in building with a command-line generator. If you're building with Ninja and the Visual C++ toolset on Windows, set the environment before CMake is called to generate the build system. You can do it by calling `vcvarsall.bat` with the `architecture` argument. The `architecture` argument specifies the host and target architecture to use. For more information, see [`vcvarsall` syntax](/cpp/build/building-on-the-command-line#vcvarsall-syntax). If you build on Linux or on Windows with a Visual Studio Generator, you don't need to take this step. +It's up to the user to configure the environment before CMake is invoked in building with a command-line generator. If you're building with Ninja and the Visual C++ toolset on Windows, set the environment before CMake is called to generate the build system. You can do it by calling *`vcvarsall.bat`* with the `architecture` argument. The `architecture` argument specifies the host and target architecture to use. For more information, see [`vcvarsall` syntax](./building-on-the-command-line.md#vcvarsall-syntax). If you build on Linux or on Windows with a Visual Studio Generator, you don't need to take this step. -It's the same step that Visual Studio takes for you when the IDE invokes CMake. Visual Studio parses the active Configure Preset for the host and target architecture specified by `toolset` and `architecture`. Visual Studio then sources the specified environment from `vcvarsall.bat`. When you build from the Windows command line with Ninja, you'll need to take this step yourself. +It's the same step that Visual Studio takes for you when the IDE invokes CMake. Visual Studio parses the active Configure Preset for the host and target architecture specified by `toolset` and `architecture`. Visual Studio then sources the specified environment from *`vcvarsall.bat`*. When you build from the Windows command line with Ninja, you'll need to take this step yourself. -`vcvarsall.bat` is installed with the Build Tools for Visual Studio. By default, `vcvarsall.bat` is installed in `C:\Program Files (x86)\Microsoft Visual Studio\2019\\VC\Auxiliary\Build`. You can add `vcvarsall.bat` to `PATH` if you use the command-line workflow often. +*`vcvarsall.bat`* is installed with the Build Tools for Visual Studio. By default, *`vcvarsall.bat`* is installed in `C:\Program Files (x86)\Microsoft Visual Studio\2019\\VC\Auxiliary\Build`. You can add *`vcvarsall.bat`* to `PATH` if you use the command-line workflow often. ### Example command-line workflow -You can use the following commands to configure and build a CMake project that uses Ninja to target ARM64 with x64 build tools. CMake version 3.20 or later is required. Run these commands from the directory where your `CMakePresets.json` file is located: +You can use the following commands to configure and build a CMake project that uses Ninja to target ARM64 with x64 build tools. CMake version 3.20 or later is required. Run these commands from the directory where your *`CMakePresets.json`* file is located: ```cmd /path/to/vcvarsall.bat x64_arm64 @@ -438,17 +476,17 @@ cmake --preset cmake --build --preset ``` -## Example `CMakePresets.json` file +## Example *`CMakePresets.json`* file -The `CMakePresets.json` file in [box2d-lite](https://github.com/esweet431/box2d-lite/blob/main/CMakePresets.json) contains examples of Configure Presets, Build Presets, and Test Presets. +The *`CMakePresets.json`* file in [box2d-lite](https://github.com/esweet431/box2d-lite/blob/vs-launch/CMakePresets.json) contains examples of Configure Presets, Build Presets, and Test Presets. For more information about this example, see the presentation [An Introduction to CMakePresets.json](/events/cpp-pure-virtual-cpp-2021/an-introduction-to-cmakepresetsjson). You can see another example in the [DirectXTK](https://github.com/microsoft/DirectXTK/blob/main/CMakePresets.json) project, which shows many build targets in its `configurePresets` section. ## Next steps Learn more about configuring and debugging CMake projects in Visual Studio: > [!div class="nextstepaction"] -> [CMake Projects in Visual Studio](cmake-projects-in-visual-studio.md)

-> [Customize CMake build settings](customize-cmake-settings.md)

-> [Configure CMake debugging sessions](configure-cmake-debugging-sessions.md)

+> [CMake Projects in Visual Studio](cmake-projects-in-visual-studio.md)\ +> [Customize CMake build settings](customize-cmake-settings.md)\ +> [Configure CMake debugging sessions](configure-cmake-debugging-sessions.md)\ > [CMake predefined configuration reference](cmake-predefined-configuration-reference.md) > diff --git a/docs/build/cmake-projects-in-visual-studio.md b/docs/build/cmake-projects-in-visual-studio.md index 491d15084e..a164d943fe 100644 --- a/docs/build/cmake-projects-in-visual-studio.md +++ b/docs/build/cmake-projects-in-visual-studio.md @@ -1,266 +1,402 @@ --- title: "CMake projects in Visual Studio" -description: "How to create and build C++ projects using CMake in Visual Studio." -ms.date: "01/08/2020" -helpviewer_keywords: ["CMake in Visual C++"] -ms.assetid: 444d50df-215e-4d31-933a-b41841f186f8 +description: "Learn how to create and build C++ projects using CMake in Visual Studio." +ms.date: 03/18/2025 +ms.topic: concept-article +f1_keywords: ["VS.ToolsOptionsPages.CMake.General", "VS.ToolsOptionsPages.CMake.LanguageServices"] --- # CMake projects in Visual Studio -[CMake](https://cmake.org) is a cross-platform, open-source tool for defining build processes that run on multiple platforms. This article assumes you're familiar with CMake. For more information about CMake, see the [CMake documentation](https://cmake.org/cmake/help/latest/index.html#). The [CMake tutorial](https://cmake.org/cmake/help/latest/guide/tutorial/index.html#guide:CMake%20Tutorial) is a good starting point to learn more. +[CMake](https://cmake.org) is a cross-platform, open-source tool for defining build processes that run on multiple platforms. This article assumes you're familiar with CMake. For more information about CMake, see the [CMake documentation](https://cmake.org/cmake/help/latest/index.html#). The [CMake tutorial](https://cmake.org/cmake/help/latest/guide/tutorial/index.html#guide:CMake%20Tutorial) is a good starting point to learn more. > [!NOTE] -> CMake has become more and more integrated with Visual Studio over the past few releases. To see the documentation for your preferred version of Visual Studio, use the **Version** selector control. It's found at the top of the table of contents on this page. +> CMake has become more and more integrated with Visual Studio over the past few releases. To see the documentation for your preferred version of Visual Studio, use the **Version** selector located at the top of the table of contents on this page. -::: moniker range="msvc-160" +::: moniker range=">=msvc-160" -The **C++ CMake tools for Windows** component uses the [Open Folder](open-folder-projects-cpp.md) feature to consume CMake project files (such as *CMakeLists.txt*) directly for the purposes of IntelliSense and browsing. Both Ninja and Visual Studio generators are supported. If you use a Visual Studio generator, it generates a temporary project file and passes it to msbuild.exe. However, the project is never loaded for IntelliSense or browsing purposes. You can also import an existing CMake cache. +Visual Studio's native support for CMake allows you to edit, build, and debug CMake projects on Windows, the Windows Subsystem for Linux (WSL), and remote systems from the same instance of Visual Studio. CMake project files (such as *`CMakeLists.txt`*) are consumed directly by Visual Studio for the purposes of IntelliSense and browsing. Visual Studio invokes `cmake.exe` directly for CMake configuration and build. ## Installation -**C++ CMake tools for Windows** is installed as part of the **Desktop development with C++** and **Linux Development with C++** workloads. For more information, see [Cross-platform CMake projects](../linux/cmake-linux-project.md). +**C++ CMake tools for Windows** is installed as part of the **Desktop development with C++** and **Linux Development with C++** workloads. Both **C++ CMake tools for Windows** and **Linux Development with C++** are required for cross-platform CMake development. -![Screenshot of the Desktop development with C plus plus dropdown selected and the C plus plus C Make tools for Windows option called out.](media/cmake-install-2019.png) +:::image type="complex" source="media/cmake-install-2022.png" alt-text="Screenshot of the Visual Studio installer."::: +In the installer, the Desktop development with C plus plus dropdown is selected and C plus plus C Make tools for Windows is selected." +:::image-end::: For more information, see [Install the C++ Linux workload in Visual Studio](../linux/download-install-and-setup-the-linux-development-workload.md). -## IDE Integration +## IDE integration + +When you **open a folder** containing a *`CMakeLists.txt`* file, the following things happen. -When you choose **File > Open > Folder** to open a folder containing a *CMakeLists.txt* file, the following things happen: +:::image type="complex" source="media/start-window.png" alt-text="Screenshot of the first dialog that opens when Visual Studio is started."::: +The dialog offers these options: clone a repository, open a project or solution, open a local folder, or create a new project. Open a local folder is called out in the screenshot. +:::image-end::: - Visual Studio adds **CMake** items to the **Project** menu, with commands for viewing and editing CMake scripts. -- **Solution Explorer** displays the folder structure and files. +- The **Solution Explorer** displays the folder structure and files. -- Visual Studio runs cmake.exe and generates the CMake cache file (*CMakeCache.txt*) for the default (x64 Debug) configuration. The CMake command line is displayed in the **Output Window**, along with additional output from CMake. +- Visual Studio runs CMake and generates the CMake cache file (*`CMakeCache.txt`*) for the default configuration. The CMake command line is displayed in the **Output Window**, along with other output from CMake. - In the background, Visual Studio starts to index the source files to enable IntelliSense, browsing information, refactoring, and so on. As you work, Visual Studio monitors changes in the editor and also on disk to keep its index in sync with the sources. -You can open folders containing any number of CMake projects. Visual Studio detects and configures all the "root" *CMakeLists.txt* files in your workspace. CMake operations (configure, build, debug), C++ IntelliSense, and browsing are available to all CMake projects in your workspace. +> [!NOTE] +> Starting in Visual Studio 2022 version 17.1 Preview 2, if your top-level *`CMakeLists.txt`* exists in a subfolder and not at the root of the workspace, you're prompted whether you'd like to enable CMake integration or not. For more information, see [CMake partial activation](#cmake-partial-activation). -![CMake project with multiple roots](media/cmake-multiple-roots.png) +Once CMake cache generation has succeeded, you can also view your projects organized logically by targets. Choose the **Select View** button on the **Solution Explorer** toolbar. From the list in **Solution Explorer - Views**, select **CMake Targets View** and press **Enter** to open the targets view: -You can also view your projects organized logically by targets. Choose **Targets view** from the dropdown in the **Solution Explorer** toolbar: +:::image type="content" source="media/cmake-targets-view2.png" alt-text="Screenshot of the Solution Explorer Views window. The folder view is open. The C Make Targets View option is highlighted."::: -![CMake targets view button](media/cmake-targets-view.png) +Choose the **Show All Files** button at the top of **Solution Explorer** to see all the CMake-generated output in the *`out/build/`* folders. -Click the **Show All Files** button at the top of **Solution Explorer** to see all the CMake-generated output in the *out/build/\* folders. +Use the *`CMakeLists.txt`* file in each project folder just as you would in any CMake project. You can specify source files, find libraries, set compiler and linker options, and specify other build system-related information. For more information on CMake language services provided by Visual Studio, see [Editing CMakeLists.txt files](#editing-cmakeliststxt-files). -Visual Studio uses a configuration file called **CMakeSettings.json**. This file lets you define and store multiple build configurations, and conveniently switch between them in the IDE. A *configuration* is a Visual Studio construct that encapsulates settings that are specific to a given build type. The settings are used to configure the default command-line options that Visual Studio passes to cmake.exe. You can also specify additional CMake options here, and define any additional variables you like. All options are written to the CMake cache either as internal or external variables. In Visual Studio 2019, the **CMake Settings Editor** provides a convenient way to edit your settings. For more information, see [Customize CMake settings](customize-cmake-settings.md). +Visual Studio uses a CMake configuration file to drive CMake cache generation and build. For more information, see [Configuring CMake projects](#configuring-cmake-projects) and [Building CMake projects](#building-cmake-projects). -One setting, `intelliSenseMode` isn't passed to CMake, but is used only by Visual Studio. +To pass arguments to an executable at debug time, you can use another file called *`launch.vs.json`*. For more information on debugging cross-platform CMake projects in Visual Studio, see [Debugging CMake projects](#debugging-cmake-projects). -Use the **CMakeLists.txt** file in each project folder just as you would in any CMake project. You can specify source files, find libraries, set compiler and linker options, and specify other build system-related information. +Most Visual Studio and C++ language features are supported by CMake projects in Visual Studio. Examples include: -To pass arguments to an executable at debug time, you can use another file called **launch.vs.json**. In some scenarios, Visual Studio automatically generates these files. You can edit them manually, or even create the file yourself. +- [Edit and Continue for CMake projects](#edit-and-continue-for-cmake-projects) +- [Incredibuild integration for CMake projects](https://devblogs.microsoft.com/cppblog/seamlessly-accelerate-cmake-projects-in-visual-studio-with-incredibuild/) +- [AddressSanitizer support for CMake projects](cmake-presets-vs.md#enable-addresssanitizer-for-windows-and-linux) +- [Clang/LLVM support](https://devblogs.microsoft.com/cppblog/clang-llvm-support-in-visual-studio/) > [!NOTE] -> For other kinds of Open Folder projects, two additional JSON files are used: **CppProperties.json** and **tasks.vs.json**. Neither of these are relevant for CMake projects. +> For other kinds of Open Folder projects, an additional JSON file *`CppProperties.json`* is used. This file isn't relevant for CMake projects. -## Open an existing cache +## Configuring CMake projects -When you open an existing CMake cache file (*CMakeCache.txt*), Visual Studio doesn't try to manage your cache and build tree for you. Your custom or preferred tools have complete control over how CMake configures your project. To open an existing cache in Visual Studio, choose **File > Open > CMake**. Then, navigate to an existing *CMakeCache.txt* file. +The CMake configure step generates the project build system. It's equivalent to invoking *`cmake.exe`* from the command line. For more information on the CMake configure step, see the [CMake documentation](https://cmake.org/cmake/help/latest/manual/cmake.1.html#generate-a-project-buildsystem). -You can add an existing CMake cache to an open project. It's done the same way you'd add a new configuration. For more information, see our blog post on [opening an existing cache in Visual Studio](https://devblogs.microsoft.com/cppblog/open-existing-cmake-caches-in-visual-studio/). +Visual Studio uses a CMake configuration file to drive CMake generation and build. *`CMakePresets.json`* is supported by Visual Studio 2019 version 16.10 or later and is the recommended CMake configuration file. *`CMakePresets.json`* is supported directly by CMake and can be used to drive CMake generation and build from Visual Studio, from VS Code, in a continuous integration pipeline, and from the command line on Windows, Linux, and Mac. For more information on *`CMakePresets.json`*, see [Configure and build with CMake Presets](cmake-presets-vs.md). *`CMakeSettings.json`* is available for customers using an earlier version of Visual Studio. For more information on *`CMakeSettings.json`*, see [Customize CMake build settings](customize-cmake-settings.md). + +When you make significant changes to your CMake configuration file or a *`CMakeLists.txt`* file, Visual Studio automatically runs the CMake configure step. You can invoke the configure step manually: Select **Project > Configure Cache** from the toolbar. You can also change your configuration preferences in **Tools** > **Options** > **CMake** > **General**. + +:::image type="complex" source="media/cmake-configure-options.png" alt-text="Screenshot of the C Make configuration options in the Visual Studio settings window."::: +The C Make configure settings are called out. Show C Make cache notifications is selected. Under 'When cache is out of date', the option 'Never run configure step automatically' is selected. +:::image-end::: + +If the configure step finishes without errors, then the information that's available drives C++ IntelliSense and language services. It's also used in build and debug operations. + +You can also open an existing CMake cache in Visual Studio. For more information, see [Open an existing cache](#open-an-existing-cache). + +### Customize configuration feedback and notifications + +By default, most configuration messages are suppressed unless there's an error. To see all messages, select **Tools** > **Options** > **CMake** > **Enable verbose CMake diagnostic output**. + +You can also disable all CMake cache notifications (gold bars) by deselecting **Show CMake cache notification**. + +### Customize Targets View source groups + +By default, the CMake Targets View ignores the following source groups: *Source Files*, *Header Files*, *Resources*, *Object Files*. These groups are included by default in most CMake projects and would unnecessarily increase the number of clicks required to navigate the Targets View. + +You can enable the use of these source groups by selecting **Tools** > **Options** > **CMake** > **Enable the use of ignored source groups in CMake Targets View**. + +### Troubleshooting CMake cache errors + +If you need more information about the state of the CMake cache to diagnose a problem, open the **Project** main menu or the *`CMakeLists.txt`* context menu in **Solution Explorer** to run one of these commands: + +- **View CMakeCache.txt** opens the *`CMakeCache.txt`* file from the build directory in the editor. Any edits you make here to *`CMakeCache.txt`* are wiped out if you clean the cache. To make changes that persist after you clean the cache, see [Customize CMake settings](customize-cmake-settings.md) or [Configure and build with CMake Presets](cmake-presets-vs.md). + +- **Delete Cache and Reconfigure** deletes the build directory and reconfigures from a clean cache. + +- **Configure Cache** forces the generate step to run even if Visual Studio considers the environment up to date. ## Building CMake projects -To build a CMake project, you have these choices: +The CMake build step builds an already generated project binary tree. It's equivalent to invoking `cmake --build` from the command line. For more information on the CMake build step, see the [CMake documentation](https://cmake.org/cmake/help/latest/manual/cmake.1.html#build-a-project). -1. In the General toolbar, find the **Configurations** dropdown. It probably shows "x64-Debug" by default. Select the preferred configuration and press **F5**, or click the **Run** (green triangle) button on the toolbar. The project automatically builds first, just like a Visual Studio solution. +To build a CMake project, you have these choices: -1. Right click on *CMakeLists.txt* and select **Build** from the context menu. If you have multiple targets in your folder structure, you can choose to build all or only one specific target. +1. In the toolbar, find the **Startup Item** dropdown. Select the preferred target and press **F5**, or choose the **Run** button on the toolbar. The project automatically builds first, just like a Visual Studio solution. -1. From the main menu, select **Build > Build All** (**F7** or **Ctrl+Shift+B**). Make sure that a CMake target is already selected in the **Startup Item** dropdown in the **General** toolbar. +1. Right-click on CMake target with **CMake Targets View** active in the **Solution Explorer** and select **Build** from the context menu. -![CMake build menu command](media/cmake-build-menu.png "CMake build command menu") +1. From the main menu, select **Build > Build All**. Make sure that a CMake target is already selected in the **Startup Item** dropdown in the toolbar. As you would expect, build results are shown in the **Output Window** and **Error List**. -![CMake build errors](media/cmake-build-errors.png "CMake build errors") +:::image type="complex" source="media/cmake-build-errors.png" alt-text="Screenshot of the Visual Studio Error List window"::: +C Make build warnings about conversions that might result in data loss such as converting from a float to an integer, are visible. +:::image-end::: -In a folder with multiple build targets, you can specify which CMake target to build: Choose the **Build** item on the **CMake** menu or the *CMakeLists.txt* context menu to specify the target. If you enter **Ctrl+Shift+B** in a CMake project, it builds the current active document. +### Edit build settings + +Visual Studio uses a CMake configuration file to drive CMake builds. CMake configuration files encapsulate build options like native build tool switches and environment variables. If *`CMakePresets.json`* is your active configuration file, see [Configure and build with CMake Presets](cmake-presets-vs.md#configure-and-build). If *`CMakeSettings.json`* is your active configuration file, see [Customize CMake build settings](customize-cmake-settings.md). *`CMakePresets.json`* is available in Visual Studio 2019 version 16.10 or later and is the recommended CMake configuration file. ## Debugging CMake projects -To debug a CMake project, choose the preferred configuration and press **F5**, or press the **Run** button in the toolbar. If the **Run** button says "Select Startup Item", select the dropdown arrow. Choose the target that you want to run. (In a CMake project, the "Current document" option is only valid for .cpp files.) +All executable CMake targets are shown in the **Startup Item** dropdown in the toolbar. To start debugging, select one and press the **Debug > Start Debugging** button in the toolbar. In a CMake project, the **Current document** option is only valid for .cpp files. -![CMake run button](media/cmake-run-button.png "CMake run button") +:::image type="complex" source="media/debug-target.png" alt-text="Screenshot of the Visual Studio debug dropdown."::: +The dropdown has these options: Show / Hide debug targets, current document, samples (which is highlighted), box2d_tests, and samples-noGUI. +:::image-end::: -The **Run** or **F5** commands first build the project if changes have been made since the previous build. Changes to *CMakeSettings.json* cause the CMake cache to be regenerated. +The **Debug** or **F5** commands first build the project if changes have been made since the previous build. Changes to the CMake configuration file (*`CMakePresets.json`* or *`CMakeSettings.json`*) or a *`CMakeLists.txt`* causes the CMake cache to be regenerated. -You can customize a CMake debugging session by setting properties in the **launch.vs.json** file. For more information, see [Configure CMake debugging sessions](configure-cmake-debugging-sessions.md). +You can customize a CMake debugging session by setting properties in the *`launch.vs.json`* file. To customize debug settings for a specific target, select the target in the **Startup Item** dropdown and choose **Debug > Debug and Launch Settings for \**. For more information on CMake debugging sessions, see [Configure CMake debugging sessions](configure-cmake-debugging-sessions.md). -## Just My Code for CMake projects +### Just My Code for CMake projects -When you build for Windows using the MSVC compiler, CMake projects have support for Just My Code debugging. To change the Just My Code setting, go to **Tools** > **Options** > **Debugging** > **General**. +When you build for Windows using the MSVC compiler, CMake projects have support for Just My Code debugging. To change the Just My Code setting, go to **Tools** > **Options** > **Debugging** > **General**. For more information on Just My Code debugging, see [Debug only user code with Just My Code](/visualstudio/debugger/just-my-code). -## Vcpkg integration +### Edit and Continue for CMake projects -If you have installed [vcpkg](https://vcpkg.io/), CMake projects opened in Visual Studio automatically integrate the vcpkg toolchain file. That means no additional configuration is required to use vcpkg with your CMake projects. This support works for both local vcpkg installations and vcpkg installations on remote systems that you're targeting. This behavior is disabled automatically when you specify any other toolchain in your CMake Settings configuration. +When you build for Windows with the MSVC compiler, CMake projects have support for Edit and Continue. Add the following code to your *`CMakeLists.txt`* file to enable Edit and Continue. -## Customize configuration feedback +``` +if(MSVC) + target_compile_options( PUBLIC "/ZI") + target_link_options( PUBLIC "/INCREMENTAL") +endif() +``` -By default, most configuration messages are suppressed unless there's an error. You can see all messages by enabling this feature in **Tools** > **Options** > **CMake**. +For more information on Edit and Continue, see [Configure Edit and Continue (C#, VB, C++)](/visualstudio/debugger/how-to-enable-and-disable-edit-and-continue). - ![Configuring CMake diagnostic options](media/vs2019-cmake-configure-options.png "CMake diagnostic options") +### Attach to a CMake project running on Linux -## Editing CMakeLists.txt files +Visual Studio allows you to debug a process running on a remote Linux system or WSL and debug it with the GDB debugger. To get started, select **Debug** > **Attach to Process...**, set the **Connection type** to **SSH**, and select your **Connection target** from the list of connections in the Connection Manager. Select a process from the list of available processes and press **Attach**. GDB must be installed on your Linux machine. For more information on SSH connections, see the [Connection Manager](../linux/connect-to-your-remote-linux-computer.md) -To edit a *CMakeLists.txt* file, right-click on the file in **Solution Explorer** and choose **Open**. If you make changes to the file, a yellow status bar appears and informs you that IntelliSense will update. It gives you a chance to cancel the update operation. For information about *CMakeLists.txt*, see the [CMake documentation](https://cmake.org/documentation/). +:::image type="complex" source="media/attach-to-process.png" alt-text="Screenshot of the Attach to Process menu in Visual Studio."::: +The following options are available on the dialog: Connection type (set to SSH), the connection target (set to demo@ 172. 20. 60. 6), and a list of available processes you can attach to." +:::image-end::: - ![CMakeLists.txt file editing](media/cmake-cmakelists.png "CMakeLists.txt file editing") +## CMake partial activation -As soon as you save the file, the configuration step automatically runs again and displays information in the **Output** window. Errors and warnings are shown in the **Error List** or **Output** window. Double-click on an error in the **Error List** to navigate to the offending line in *CMakeLists.txt*. +In Visual Studio 2022 version 17.1 and later, CMake functionality isn't enabled automatically if your root folder doesn't contain a *`CMakeLists.txt`* file. Instead, a dialog prompts you on whether you'd like to enable CMake functionality for your project. If you decline, CMake cache generation doesn't start and CMake configurations (from *`CMakeSettings.json`* or *`CMakePresets.json`*) doesn't appear in the configuration dropdown. If you accept, you're taken to a workspace-level configuration file, *`CMakeWorkspaceSettings.json`* (stored in the *`.vs`* directory), to specify the folders you'd like to enable CMake for. (These folders contain your root *`CMakeLists.txt`* files). - ![CMakeLists.txt file errors](media/cmake-cmakelists-error.png "CMakeLists.txt file errors") +The accepted properties are: -## CMake configure step +| Property | Description | +|--|--| +| `enableCMake` | Enable Visual Studio's integration for this workspace. | +| `sourceDirectory` | A string or array of strings specifying the directory or directories with *`CMakeLists.txt`*. Macros (such as `${workspaceRoot}`) are allowed. Relative paths are based on the workspace root. Directories outside of the current workspace are ignored. | -When you make significant changes to the *CMakeSettings.json* or to *CMakeLists.txt* files, Visual Studio automatically reruns the CMake configure step. If the configure step finishes without errors, the information that's collected is available in C++ IntelliSense and language services. It's also used in build and debug operations. +You can reach *`CMakeWorkspaceSettings.json`* through the **Project** > **CMake Workspace Settings** menu command at any time, even if CMake functionality is currently disabled. -## Troubleshooting CMake cache errors +## Open an existing cache -If you need more information about the state of the CMake cache to diagnose a problem, open the **Project** main menu or the *CMakeLists.txt* context menu in **Solution Explorer** to run one of these commands: +When you open an existing CMake cache file (*`CMakeCache.txt`*), Visual Studio doesn't try to manage your cache and build tree for you. Your custom or preferred tools have complete control over how CMake configures your project. -- **View Cache** opens the *CMakeCache.txt* file from the build root folder in the editor. (Any edits you make here to *CMakeCache.txt* are wiped out if you clean the cache. To make changes that persist after the cache is cleaned, see [Customize CMake settings](customize-cmake-settings.md).) +You can add an existing CMake cache to an open project. It's done the same way you'd add a new configuration. For more information, see our blog post on [opening an existing cache in Visual Studio](https://devblogs.microsoft.com/cppblog/open-existing-cmake-caches-in-visual-studio/). -- **Open Cache Folder** opens an Explorer window to the build root folder. +> [!NOTE] +> The default existing cache experience relies on `cmake-server`, which was removed from CMake in version 3.20. To continue using existing cache functionality in Visual Studio 2019 version 16.10 and later, take one of these steps: +> +> - Manually install CMake version 3.19 or lower. Then, set the `cmakeExecutable` property in your existing cache configuration to use that version of CMake. +> - In your existing cache configuration, set the `cacheGenerationCommand` property to let Visual Studio request the necessary CMake file-based API files. For more information on that property, see [CMakeSettings.json reference](cmakesettings-reference.md#configurations). +> - Use a query file to request the CMake file-based API files when generating your cache before it's opened in Visual Studio. For query file instructions, see the next section, [Advanced CMake cache troubleshooting](#advanced). -- **Clean Cache** deletes the build root folder so that the next CMake configure step starts from a clean cache. +### Advanced CMake cache troubleshooting -- **Generate Cache** forces the generate step to run even if Visual Studio considers the environment up to date. +Visual Studio uses the CMake [file-based API](https://cmake.org/cmake/help/latest/manual/cmake-file-api.7.html) (in versions 3.14 and later) to populate the editor with information specific to your project structure. For more information, see the C++ team blog post on [multi-root workspaces and file-based API](https://devblogs.microsoft.com/cppblog/visual-studio-code-cmake-tools-extension-multi-root-workspaces-and-file-based-api/). -Automatic cache generation can be disabled in the **Tools > Options > CMake > General** dialog. +Before generating the CMake cache, your custom or preferred tools might need to create a query file named *`.cmake/api/v1/query/client-MicrosoftVS/query.json`* in your build output folder (the folder that contains *`CMakeCache.txt`*). The query file should contain this content: + +```json +{"requests":[{"kind":"cache","version":2},{"kind":"cmakeFiles","version":1},{"kind":"codemodel","version":2}]} +``` + +When your custom or preferred tools generate your cache, CMake places files under *`.cmake/api/v1/response`* that Visual Studio uses to populate the editor with information specific to your project structure. + +## Editing *`CMakeLists.txt`* files + +To edit a *`CMakeLists.txt`* file, right-click on the file in **Solution Explorer** and choose **Open**. If you make changes to the file, a yellow status bar appears and informs you that IntelliSense will update. It gives you a chance to cancel the update operation. For information about *`CMakeLists.txt`*, see the [CMake documentation](https://cmake.org/documentation/). + +:::image type="complex" source="media/cmake-cmakelists.png" alt-text="Screenshot of a C Make Lists TXT file being edited in Visual Studio." +It contains the lines project (hello-cmake), add_subdirectory (tests), add_executable (hello hello.cpp), and install (TARGETS hello DESTINATION hello/bin). A message at the top of the window says that c plus plus IntelliSense info will refresh after C Make finishes generating the cache. +:::image-end::: + +As soon as you save the file, the configuration step automatically runs again and displays information in the **Output** window. Errors and warnings are shown in the **Error List** or **Output** window. Double-click on an error in the **Error List** to navigate to the offending line in *`CMakeLists.txt`*. + +:::image type="complex" source="media/cmake-cmakelists-error.png" alt-text="Screenshot of a C Make error in the Visual Studio error list."::: +A C Make error message on line 3 of CMakeLists.txt is highlighted. The details are that C Make couldn't find a package configuration file provided by sqlite3. C Make looked for it in CMAKE_MODULE_PATH but couldn't find it. The suggestion is to add the installation prefix 'sqlite3' to CMAKE_PREFIX_PATH or set sqlite3_DIR to a directory containing sqlite3Config.cmake and/or sqlitet3-config.cmake. +:::image-end::: + +### Language services for CMake + +Language services for CMake are available in Visual Studio 2019 version 16.5 or later. Language services support code navigation features like *Go To Definition*, *Peek Definition*, and *Find All References* for CMake variables, functions, and targets in CMake script files. For more information, see [Code Navigation for CMake Scripts](https://devblogs.microsoft.com/cppblog/code-navigation-for-cmake-scripts/). + +:::image type="complex" source="media/cmake-find-all-refs.png" alt-text="Screenshot of the Visual Studio Find All References window."::: +Results of where SUPERTUX_SOURCES_CXX are found are shown. For example, in list(SORT SSUPERTUX_SOURCES_CXX), file(GLOB SUPERTUX_SOURCES_CXX) and so on. +:::image-end::: + +### CMake project manipulation + +CMake project manipulation is available in Visual Studio 2019 version 16.5 or later. Project manipulation lets you add, remove, and rename source files and targets in your CMake project without manually editing your CMake scripts. When you add or remove files from the Solution Explorer, Visual Studio automatically edits your CMake project. There could be more than one place where it makes sense to add or remove a reference to a CMake script. If so, Visual Studio asks you where you want to make the change and displays a preview of the proposed changes. For step-by-step instructions, see [Add, Remove, and Rename Files and Targets in CMake Projects](https://devblogs.microsoft.com/cppblog/easily-add-remove-and-rename-files-and-targets-in-cmake-projects/). + +:::image type="complex" source="media/cmake-project-manipulation.png" alt-text="Screenshot of the Visual Studio Preview Changes dialog box."::: +A tree view shows CMakeLists.txt, under which are two items: add_executable and set. Set is checked. The preview window shows where changes will be made. The line set PROJECT_SRC "CmakeProject4.cpp" "CMakeProject4.h" shows "Demo.cpp" highlighted before the closing parenthesis. The apply button accepts the change, or you can press cancel. +:::image-end::: + +## IntelliSense for CMake projects + +By default, Visual Studio uses the IntelliSense mode that matches the compiler and target architecture specified by the active CMake configuration. + +If *`CMakePresets.json`* is your active CMake configuration file, then you can specify IntelliSense options using `intelliSenseMode` and `intelliSenseOptions` in the Visual Studio Settings vendor map. For more information, see the [Visual Studio Settings vendor map reference](cmake-presets-json-reference.md#visual-studio-settings-vendor-map). + +If *`CMakeSettings.json`* is your active CMake configuration file, then you can specify IntelliSense options using `intelliSenseMode` in *`CMakeSettings.json`*. For more information, see the [`CMakeSettings.json` reference](cmakesettings-reference.md). + +### Configure IntelliSense with CMake toolchain files + +In Visual Studio 2019 version 16.9 and later, Visual Studio automatically configures IntelliSense in CMake projects based on CMake variables when you use a CMake toolchain file. For more information, see [Configure IntelliSense with CMake Toolchain Files](https://devblogs.microsoft.com/cppblog/configure-intellisense-with-cmake-toolchain-files-in-visual-studio-2019-16-9-preview-2/). + +## Vcpkg integration + +CMake projects opened in Visual Studio integrate with vcpkg, a cross-platform C/C++ dependency manager. Before using vcpkg with Visual Studio, you must run `vcpkg integrate install`. For instructions and more information about vcpkg, see: + +- [Install and use packages with CMake in Visual Studio](/vcpkg/get_started/get-started-vs) +- [vcpkg in CMake projects](/vcpkg/users/buildsystems/cmake-integration) + +If *`CMakeSettings.json`* is your active configuration file, Visual Studio automatically passes the vcpkg toolchain file (`vcpkg.cmake`) to CMake. This behavior is disabled automatically when you specify any other toolchain in your CMake Settings configuration. + +If *`CMakePresets.json`* is your active configuration file, you need to set the path to `vcpkg.cmake` in *`CMakePresets.json`*. We recommend using the `VCPKG_ROOT` environment variable instead of an absolute path to keep the file shareable. For more information, see [Enable vcpkg integration with CMake Presets](cmake-presets-vs.md#enable-vcpkg-integration). *`CMakePresets.json`* is available in Visual Studio 2019 version 16.10 or later and is the recommended CMake configuration file. ## Run CMake from the command line -If you have installed CMake from the Visual Studio Installer, you can run it from the command line by following these steps: +If *`CMakePresets.json`* is your active CMake configuration file, then you can easily reproduce your local builds outside of Visual Studio. For more information, see [Run CMake from the command line or a CI pipeline](cmake-presets-vs.md#run-cmake-from-the-command-line-or-a-ci-pipeline). *`CMakePresets.json`* is supported in Visual Studio 2019 version 16.10 or later and is the recommended CMake configuration file. + +If *`CMakeSettings.json`* is your active CMake configuration file, then you need to manually pass the arguments that are encoded in your *`CMakeSettings.json`* file to CMake. If you installed CMake from the Visual Studio Installer, you can run it from the command line by following these steps: -1. Run the appropriate vsdevcmd.bat (x86/x64). For more information, see [Building on the Command Line](building-on-the-command-line.md). +1. Run the appropriate *`vsdevcmd.bat`* file (x86/x64). For more information, see [Use the Microsoft C++ toolset from the command line](building-on-the-command-line.md) . 1. Switch to your output folder. -1. Run CMake to build/configure your app. +1. Run CMake to build or configure your app. ::: moniker-end ::: moniker range="msvc-150" -Visual Studio 2017 has rich support for CMake, including [cross-platform CMake projects](../linux/cmake-linux-project.md). The **Visual C++ Tools for CMake** component uses the **Open Folder** feature to enable the IDE to consume CMake project files (such as *CMakeLists.txt*) directly for the purposes of IntelliSense and browsing. Both Ninja and Visual Studio generators are supported. If you use a Visual Studio generator, it generates a temporary project file and passes it to msbuild.exe. However, the project is never loaded for IntelliSense or browsing purposes. You also can import an existing CMake cache. +Visual Studio 2017 has rich support for CMake, including [cross-platform CMake projects](../linux/cmake-linux-project.md). The **Visual C++ Tools for CMake** component uses the **Open Folder** feature to enable the IDE to consume CMake project files (such as *`CMakeLists.txt`*) directly for the purposes of IntelliSense and browsing. Both Ninja and Visual Studio generators are supported. If you use a Visual Studio generator, it generates a temporary project file and passes it to MSBuild. However, the project is never loaded for IntelliSense or browsing purposes. You also can import an existing CMake cache. ## Installation **Visual C++ Tools for CMake** is installed as part of the **Desktop development with C++** and **Linux Development with C++** workloads. -![Screenshot of the Individual components tab with the Visual C plus plus tools for C make option called out.](media/cmake-install.png) +:::image type="content" source="media/cmake-install.png" alt-text="Screenshot of the Visual Studio Installer. The Individual components tab is selected on which Visual C plus plus tools for C Make is selected."::: For more information, see [Install the C++ Linux workload in Visual Studio](../linux/download-install-and-setup-the-linux-development-workload.md). ## IDE integration -When you choose **File > Open > Folder** to open a folder containing a *CMakeLists.txt* file, the following things happen: +When you choose **File > Open > Folder** to open a folder containing a *`CMakeLists.txt`* file, the following happens: - Visual Studio adds a **CMake** menu item to the main menu, with commands for viewing and editing CMake scripts. - **Solution Explorer** displays the folder structure and files. -- Visual Studio runs CMake.exe and optionally generates the CMake cache for the default *configuration*, which is x86 Debug. The CMake command line is displayed in the **Output Window**, along with additional output from CMake. +- Visual Studio runs CMake and optionally generates the CMake cache for the default *configuration*, which is x86 Debug. The CMake command line is displayed in the **Output Window**, along with other output from CMake. - In the background, Visual Studio starts to index the source files to enable IntelliSense, browsing information, refactoring, and so on. As you work, Visual Studio monitors changes in the editor and also on disk to keep its index in sync with the sources. -You can open folders containing any number of CMake projects. Visual Studio detects and configures all the "root" *CMakeLists.txt* files in your workspace. CMake operations (configure, build, debug), C++ IntelliSense, and browsing are available to all CMake projects in your workspace. +You can open folders containing any number of CMake projects. Visual Studio detects and configures all the top-level *`CMakeLists.txt`* files in your workspace. CMake operations (configure, build, debug), C++ IntelliSense, and browsing are available to all CMake projects in your workspace. -![CMake project with multiple roots](media/cmake-multiple-roots.png) +:::image type="complex" source="media/cmake-multiple-roots.png" alt-text="Screenshot of the Visual Studio Solution Explorer."::: +The files and folders of a C Make project are visible. There's a tests subdirectory, CMakeLists.txt, and hello.cpp. There's a hello-cmake-vcpkg folder that contains CMakeLists.txt, CMakeSettings.json, and hello.cpp. +:::image-end::: You can also view your projects organized logically by targets. Choose **Targets view** from the dropdown in the **Solution Explorer** toolbar: -![CMake targets view button](media/cmake-targets-view.png) +:::image type="content" source="media/cmake-targets-view.png" alt-text="Screenshot of the dropdown button in the Visual Studio Solution Explorer that offers the CMake targets view option. Which is selected."::: -Visual Studio uses a file called *CMakeSettings.json* to store environment variables or command-line options for Cmake.exe. *CMakeSettings.json* also enables you to define and store multiple CMake build configurations. You can conveniently switch between them in the IDE. +Visual Studio uses a file called *`CMakeSettings.json`* to store environment variables or command-line options for CMake. *`CMakeSettings.json`* also lets you define and store multiple CMake build configurations. You can conveniently switch between them in the IDE. -Otherwise, use the *CMakeLists.txt* just as you would in any CMake project to specify source files, find libraries, set compiler and linker options, and specify other build system-related information. +Otherwise, use the *`CMakeLists.txt`* just as you would in any CMake project to specify source files, find libraries, set compiler and linker options, and specify other build system-related information. -If you need to pass arguments to an executable at debug time, you can use another file called **launch.vs.json**. In some scenarios, Visual Studio automatically generates these files. You can edit them manually, or even create the file yourself. +If you need to pass arguments to an executable at debug time, you can use another file called *`launch.vs.json`*. In some scenarios, Visual Studio automatically generates these files. You can edit them manually, or even create the file yourself. > [!NOTE] -> For other kinds of Open Folder projects, two additional JSON files are used: **CppProperties.json** and **tasks.vs.json**. Neither of these are relevant for CMake projects. +> For other kinds of Open Folder projects, two additional JSON files are used: *`CppProperties.json`* and *`tasks.vs.json`*. Neither of these are relevant for CMake projects. ## Import an existing cache -When you import an existing *CMakeCache.txt* file, Visual Studio automatically extracts customized variables and creates a pre-populated *CMakeSettings.json* file based on them. The original cache isn't modified in any way. It can still be used from the command line, or with whatever tool or IDE used to generate it. The new *CMakeSettings.json* file is placed alongside the project's root *CMakeLists.txt*. Visual Studio generates a new cache based the settings file. You can override automatic cache generation in the **Tools > Options > CMake > General** dialog. +When you import an existing *`CMakeCache.txt`* file, Visual Studio automatically extracts customized variables and creates a prepopulated *`CMakeSettings.json`* file based on them. The original cache isn't modified in any way. It can still be used from the command line, or with whatever tool or IDE used to generate it. The new *`CMakeSettings.json`* file is placed alongside the project's root *`CMakeLists.txt`*. Visual Studio generates a new cache based the settings file. You can override automatic cache generation in the **Tools > Options > CMake > General** dialog. -Not everything in the cache is imported. Properties such as the generator and the location of the compilers are replaced with defaults that are known to work well with the IDE. +Not everything in the cache is imported. Properties such as the generator and the location of the compilers are replaced with defaults that are known to work well with the IDE. ### To import an existing cache 1. From the main menu, choose **File > Open > CMake**: - ![Open CMake](media/cmake-file-open.png "File, Open, CMake") + :::image type="content" source="media/cmake-file-open.png" alt-text="Screenshot of the Visual Studio main menu with C Make selected."::: This command brings up the **Import CMake from Cache** wizard. -2. Navigate to the *CMakeCache.txt* file that you want to import, and then click **OK**. The **Import CMake Project from Cache** wizard appears: +2. Navigate to the *`CMakeCache.txt`* file that you want to import, and then choose **OK**. The **Import CMake Project from Cache** wizard appears: - ![Import a CMake cache](media/cmake-import-wizard.png "Open the CMake import cache wizard") + :::image type="content" source="media/cmake-import-wizard.png" alt-text="Screenshot of the Import C Make Project from Cache wizard. The directory path of the C Make project to import goes in the folder textbox."::: - When the wizard completes, you can see the new *CMakeCache.txt* file in **Solution Explorer** next to the root *CMakeLists.txt* file in your project. + When the wizard completes, you can see the new *`CMakeCache.txt`* file in **Solution Explorer** next to the root *`CMakeLists.txt*` file in your project. ## Building CMake projects To build a CMake project, you have these choices: -1. In the General toolbar, find the **Configurations** dropdown. It's probably showing "Linux-Debug" or "x64-Debug" by default. Select the preferred configuration and press **F5**, or click the **Run** (green triangle) button on the toolbar. The project automatically builds first, just like a Visual Studio solution. +1. In the General toolbar, find the **Configurations** dropdown. It's probably showing **Linux-Debug** or **x64-Debug** by default. Select the preferred configuration and press **F5**, or choose the **Run** (green triangle) button on the toolbar. The project automatically builds first, just like a Visual Studio solution. -1. Right click on the *CMakeLists.txt* and select **Build** from the context menu. If you have multiple targets in your folder structure, you can choose to build all or only one specific target. +1. Right-click on *`CMakeLists.txt`* in **Solution Explorer** and select **Build** from the context menu. If you have multiple targets in your folder structure, you can choose to build all or only one specific target. 1. From the main menu, select **Build > Build Solution** (**F7** or **Ctrl+Shift+B**). Make sure that a CMake target is already selected in the **Startup Item** dropdown in the **General** toolbar. -![CMake build menu command](media/cmake-build-menu.png "CMake build command menu") +:::image type="complex" source="media/cmake-build-menu.png" alt-text="Screenshot of the Visual Studio Solution Explorer after right-clicking C Make Lists dot t x t."::: +The menu has options such as Add, Open, Configure tasks, Build, Clean all, and so on. +:::image-end::: -You can customize build configurations, environment variables, command-line arguments, and other settings in the *CMakeSettings.json* file. It lets you make changes without modifying the *CMakeLists.txt* file. For more information, see [Customize CMake settings](customize-cmake-settings.md). +You can customize build configurations, environment variables, command-line arguments, and other settings in the *`CMakeSettings.json`* file. It lets you make changes without modifying the *`CMakeLists.txt`* file. For more information, see [Customize CMake build settings](customize-cmake-settings.md). As you would expect, build results are shown in the **Output Window** and **Error List**. -![CMake build errors](media/cmake-build-errors.png "CMake build errors") +:::image type="complex" source="media/cmake-build-errors.png" alt-text="Screenshot of the Visual Studio Error List window."::: +C Make build warnings about conversions that might result in data loss such as converting from a float to an integer are visible. +:::image-end::: -In a folder with multiple build targets, you can specify which CMake target to build: Choose the **Build** item on the **CMake** menu or the *CMakeLists.txt* context menu to specify the target. If you enter **Ctrl+Shift+B** in a CMake project, it builds the current active document. +In a folder with multiple build targets, you can specify which CMake target to build: Choose the **Build** item on the **CMake** menu or the *`CMakeLists.txt`* context menu to specify the target. If you enter **Ctrl+Shift+B** in a CMake project, it builds the current active document. ## Debugging CMake projects -To debug a CMake project, choose the preferred configuration and press **F5**. Or, press the **Run** button in the toolbar. If the **Run** button says "Select Startup Item", select the dropdown arrow and choose the target that you want to run. (In a CMake project, the "Current document" option is only valid for .cpp files.) +To debug a CMake project, choose the preferred configuration and press **F5**. Or, press the **Run** button in the toolbar. If the **Run** button says **Select Startup Item**, select the dropdown arrow and choose the target that you want to run. (In a CMake project, the **Current document** option is only valid for .cpp files.) -![CMake run button](media/cmake-run-button.png "CMake run button") +:::image type="content" source="media/cmake-run-button.png" alt-text="Screenshot of the Select Startup Item dropdown for a C Make project. You can select current document or hello-cmake."::: The **Run** or **F5** commands first build the project if changes have been made since the previous build. -You can customize a CMake debugging session by setting properties in the **launch.vs.json** file. For more information, see [Configure CMake debugging sessions](configure-cmake-debugging-sessions.md). +You can customize a CMake debugging session by setting properties in the *`launch.vs.json`* file. For more information, see [Configure CMake debugging sessions](configure-cmake-debugging-sessions.md). -## Editing CMakeLists.txt files +## Editing *`CMakeLists.txt`* files -To edit a *CMakeLists.txt* file, right-click on the file in **Solution Explorer** and choose **Open**. If you make changes to the file, a yellow status bar appears and informs you that IntelliSense will update. It gives you a chance to cancel the update operation. For information about *CMakeLists.txt*, see the [CMake documentation](https://cmake.org/documentation/). +To edit a *`CMakeLists.txt`* file, right-click on the file in **Solution Explorer** and choose **Open**. If you make changes to the file, a yellow status bar appears and informs you that IntelliSense will update. It gives you a chance to cancel the update operation. For information about *`CMakeLists.txt`*, see the [CMake documentation](https://cmake.org/documentation/). - ![CMakeLists.txt file editing](media/cmake-cmakelists.png "CMakeLists.txt file editing") + :::image type="complex" source="media/cmake-cmakelists.png" alt-text="Screenshot of a C Make Lists file being edited in Visual Studio."::: + The file contains project (hello-cmake), add_subdirectory (tests), add_executable (hello hello.cpp), and install (TARGETS hello DESTINATION hello/bin). A message at the top of the window says that c plus plus IntelliSense info will refresh after C Make finishes generating the cache. + :::image-end::: -As soon as you save the file, the configuration step automatically runs again and displays information in the **Output** window. Errors and warnings are shown in the **Error List** or **Output** window. Double-click on an error in the **Error List** to navigate to the offending line in *CMakeLists.txt*. +As soon as you save the file, the configuration step automatically runs again and displays information in the **Output** window. Errors and warnings are shown in the **Error List** or **Output** window. Double-click on an error in the **Error List** to navigate to the offending line in *`CMakeLists.txt`*. - ![CMakeLists.txt file errors](media/cmake-cmakelists-error.png "CMakeLists.txt file errors") + :::image type="complex" source="media/cmake-cmakelists-error.png" alt-text="Screenshot of a C Make error in the Visual Studio error list."::: + A C Make error message on line 3 of CMakeLists.txt is highlighted. The details are that C Make can't find a package configuration file provided by sqlite3. C Make looked for it in CMAKE_MODULE_PATH but couldn't find it. The suggestion is to add the installation prefix 'sqlite3' to CMAKE_PREFIX_PATH or set sqlite3_DIR to a directory containing sqlite3Config.cmake and/or sqlitet3-config.cmake. + :::image-end::: ## CMake configure step -When significant changes are made to the *CMakeSettings.json* or to *CMakeLists.txt* files, Visual Studio automatically reruns the CMake configure step. If the configure step finishes without errors, the information that's collected is available in C++ IntelliSense and language services. It's also used in build and debug operations. +When significant changes are made to the *`CMakeSettings.json`* or to *`CMakeLists.txt`* files, Visual Studio automatically reruns the CMake configure step. If the configure step finishes without errors, the information that's collected is available in C++ IntelliSense and language services. It's also used in build and debug operations. -Multiple CMake projects may use the same CMake configuration name (for example, x86-Debug). All of them are configured and built (in their own build root folder) when that configuration is selected. You can debug the targets from all of the CMake projects that participate in that CMake configuration. +Multiple CMake projects might use the same CMake configuration name (for example, *x86-Debug*). All of them are configured and built (in their own build root folder) when that configuration is selected. You can debug the targets from all of the CMake projects that participate in that CMake configuration. - ![CMake Build Only menu item](media/cmake-build-only.png "CMake Build Only menu item") + :::image type="complex" source="media/cmake-build-only.png" alt-text="Screenshot of Visual Studio's main menu, open to C Make Build Only."::: + The context menu shows what can be built. In this case hello-cmake-a \ hello-cmake.exe (Project hello-cmake) and hello-cmake-b\hello-cmake.exe (Project hello-cmake). The latter is highlighted. + :::image-end::: -You can limit builds and debug sessions to a subset of the projects in the workspace. Create a new configuration with a unique name in the *CMakeSettings.json* file. Then, apply the configuration to those projects only. When that configuration is selected, IntelliSense and the build and debug commands only apply to those specified projects. +You can limit builds and debug sessions to a subset of the projects in the workspace. Create a new configuration with a unique name in the *`CMakeSettings.json`* file. Then, apply the configuration to those projects only. When that configuration is selected, IntelliSense and the build and debug commands only apply to those specified projects. ## Troubleshooting CMake cache errors -If you need more information about the state of the CMake cache to diagnose a problem, open the **CMake** main menu or the *CMakeLists.txt* context menu in **Solution Explorer** to run one of these commands: +If you need more information about the state of the CMake cache to diagnose a problem, open the **CMake** main menu or the *`CMakeLists.txt`* context menu in **Solution Explorer** to run one of these commands: -- **View Cache** opens the *CMakeCache.txt* file from the build root folder in the editor. (Any edits you make here to *CMakeCache.txt* are wiped out if you clean the cache. To make changes that persist after the cache is cleaned, see [Customize CMake settings](customize-cmake-settings.md).) +- **View Cache** opens the *`CMakeCache.txt`* file from the build root folder in the editor. Any edits you make here to *`CMakeCache.txt`* are wiped out if you clean the cache. To make changes that persist after the cache is cleaned, see [Customize CMake settings](customize-cmake-settings.md). - **Open Cache Folder** opens an Explorer window to the build root folder. @@ -274,17 +410,17 @@ Automatic cache generation can be disabled in the **Tools > Options > CMake > Ge To build a single file in a CMake project, right-click on the file in **Solution Explorer**. Choose **Compile** from the pop-up menu. You can also build the currently open file in the editor by using the main **CMake** menu: -![CMake single file compilation](media/cmake-single-file-compile.png) +:::image type="content" source="media/cmake-single-file-compile.png" alt-text="Screenshot of the C Make Compile context menu. It contains one entry, Bullet 3 Collision."::: ## Run CMake from the command line -If you have installed CMake from the Visual Studio Installer, you can run it from the command line by following these steps: +If you installed CMake from the Visual Studio Installer, you can run it from the command line by following these steps: -1. Run the appropriate vsdevcmd.bat (x86/x64). For more information, see [Building on the command line](building-on-the-command-line.md) . +1. Run the appropriate *`vsdevcmd.bat`* file (x86/x64). For more information, see [Building on the Command Line](building-on-the-command-line.md). 1. Switch to your output folder. -1. Run CMake to build/configure your app. +1. Run CMake to build or configure your app. ::: moniker-end @@ -294,13 +430,15 @@ In Visual Studio 2015, Visual Studio users can use a [CMake generator](https://c ::: moniker-end -## See also - -[Tutorial: Create C++ cross-platform projects in Visual Studio](get-started-linux-cmake.md)\ -[Configure a Linux CMake project](../linux/cmake-linux-project.md)\ -[Connect to your remote Linux computer](../linux/connect-to-your-remote-linux-computer.md)\ -[Customize CMake build settings](customize-cmake-settings.md)\ -[CMakeSettings.json schema reference](cmakesettings-reference.md)\ -[Configure CMake debugging sessions](configure-cmake-debugging-sessions.md)\ -[Deploy, run, and debug your Linux project](../linux/deploy-run-and-debug-your-linux-project.md)\ -[CMake predefined configuration reference](cmake-predefined-configuration-reference.md) +## Related content + +- [Tutorial: Create C++ cross-platform projects in Visual Studio](get-started-linux-cmake.md) +- [Configure a Linux CMake project](../linux/cmake-linux-project.md) +- [Connect to your remote Linux computer](../linux/connect-to-your-remote-linux-computer.md) +- [Customize CMake build settings](customize-cmake-settings.md) +- [*`CMakeSettings.json`* schema reference](cmakesettings-reference.md) +- [Configure CMake debugging sessions](configure-cmake-debugging-sessions.md) +- [Deploy, run, and debug your Linux project](../linux/deploy-run-and-debug-your-linux-project.md) +- [CMake predefined configuration reference](cmake-predefined-configuration-reference.md) +- [vcpkg in CMake projects](/vcpkg/users/buildsystems/cmake-integration) +- [Install and use packages with CMake in Visual Studio](/vcpkg/get_started/get-started-vs) diff --git a/docs/build/cmake-remote-debugging.md b/docs/build/cmake-remote-debugging.md index a5df37710d..41645840b3 100644 --- a/docs/build/cmake-remote-debugging.md +++ b/docs/build/cmake-remote-debugging.md @@ -1,15 +1,15 @@ --- title: "Tutorial: Debug a CMake project on a remote Windows machine" +description: "How to use Visual Studio C++ on Windows to create and build a CMake project. You'll then deploy and debug it on a remote Windows machine." ms.date: "12/4/2020" ms.topic: tutorial -description: "How to use Visual Studio C++ on Windows to create and build a CMake project. You'll then deploy and debug it on a remote Windows machine." --- # Tutorial: Debug a CMake project on a remote Windows machine -This tutorial uses Visual Studio C++ on Windows to create and build a CMake project that you can deploy and debug on a remote Windows machine. This tutorial is specific to Windows ARM64, but the steps can be generalized for other architectures. +This tutorial uses Visual Studio C++ on Windows to create and build a CMake project that you can deploy and debug on a remote Windows machine. The tutorial is specific to Windows ARM64, but the steps can be generalized for other architectures. -In Visual Studio, the default debugging experience for ARM64 is remote debugging an ARM64 Windows machine. If you try to debug an ARM64 CMake project without configuring your debug settings as shown in this tutorial, you'll get an error that Visual Studio can't find the remote machine. +In Visual Studio, the default debugging experience for ARM64 is remote debugging an ARM64 Windows machine. Configure your debug settings as shown in this tutorial. Otherwise, when you try to debug an ARM64 CMake project, you'll get an error that Visual Studio can't find the remote machine. In this tutorial, you'll learn how to: @@ -24,7 +24,7 @@ In this tutorial, you'll learn how to: ### On the host machine -To set up Visual Studio for cross-platform C++ development, install the build tools for the target architecture. For this tutorial, install the ARM64 build tools by doing the following: +To set up Visual Studio for cross-platform C++ development, install the build tools for the target architecture. For this tutorial, install the ARM64 build tools by doing these steps: 1. Run the Visual Studio Installer. If you haven't installed Visual Studio yet, see [Install Visual Studio](/visualstudio/install/install-visual-studio) 1. On the Visual Studio Installer home screen, choose **Modify**. @@ -43,6 +43,7 @@ To set up Visual Studio for cross-platform C++ development, install the build to ## Create a CMake project On the Windows host machine: + 1. Run Visual Studio 1. From the main menu, select **File** > **New** > **Project**. 1. Select **CMake Project** > **Next** @@ -56,25 +57,25 @@ To target an ARM64 Windows machine, you need to build using ARM64 build tools. Select the Visual Studio **Configuration** dropdown and select **Manage Configurations**. -![Choose Manage Configurations in the Visual Studio configurations drop-down](media/vs2019-cmake-manage-configurations.png) +![Choose Manage Configurations in the Visual Studio configurations drop-down.](media/vs2019-cmake-manage-configurations.png) Add a new configuration by selecting **Add a new configuration** (the green **+** button).\ -In the **CMakeSettings** dialog that appears, select **arm64-debug**, and then press **Select**: +In the **CMakeSettings** dialog that appears, select **arm64-debug**, and then choose **Select**: -![Add arm64-debug configuration](media/cmake-add-config-icon-with-target-dialog.png) +![Add arm64-debug configuration.](media/cmake-add-config-icon-with-target-dialog.png) -This adds a debug configuration named **arm64-Debug** to your *`CmakeSettings.json`* file. This configuration name is a unique, friendly name that makes it easier for you to identify these settings in the **Configuration** dropdown. +This command adds a debug configuration named `arm64-Debug` to your *`CmakeSettings.json`* file. This configuration name is a unique, friendly name that makes it easier for you to identify these settings in the **Configuration** dropdown. -The **Toolset** dropdown will be set to **msvc_arm64_x64**. Your settings should now look like this: +The **Toolset** dropdown is set to **msvc_arm64_x64**. Your settings should now look like this: -![CMake settings dialog](media/cmake-settings-editor2.png) +![CMake settings dialog.](media/cmake-settings-editor2.png) > [!Note] -> In the **Toolset** dropdown, **msvc_arm64** selects 32-bit host tools to cross-compile to ARM64, whereas **msvc_arm64 x64** selects 64-bit host tools to cross-compile to ARM64--which is what you will do in this tutorial. +> In the **Toolset** dropdown, **msvc_arm64** selects 32-bit host tools to cross-compile to ARM64, whereas **msvc_arm64 x64** selects 64-bit host tools to cross-compile to ARM64, which is what you'll do in this tutorial. For more information about the available toolset environments, see [Pre-defined environments](cppproperties-schema-reference.md#pre-defined-environments). -Save the `CMakeSettings.json` file. In the configuration dropdown, select **arm64-debug** (it may take a moment after saving the `CMakeSettings.json` file for it to appear in the list): +Save the *`CMakeSettings.json`* file. In the configuration dropdown, select **arm64-debug**. (It may take a moment after saving the *`CMakeSettings.json`* file for it to appear in the list): -![Ensure that arm64-debug is selected in the Visual Studio configurations drop-down](media/vs2019-cmake-manage-configurations-arm.png) +![Ensure that arm64-debug is selected in the Visual Studio configurations drop-down.](media/vs2019-cmake-manage-configurations-arm.png) ## Add a debug configuration file @@ -82,26 +83,27 @@ Next, add configuration information that tells Visual Studio where to find your Change the **Solution Explorer** view to targets view by selecting the **Switch Views** button: -![Solution explorer switch view button](media/solution-explorer-switch-view.png) +![Solution explorer switch view button.](media/solution-explorer-switch-view.png) Then, in the **Solution Explorer**, double-click **CMake Targets View** to see the project. Open the project folder (in this example, **CMakeProject3 Project**), and then right-click the executable and select **Add Debug Configuration**: -![Select add debug configuration](media/cmake-targets-add-debug-configuration.png) +![Select add debug configuration.](media/cmake-targets-add-debug-configuration.png) -This creates a `launch.vs.json` file in your project. Open it and change the following entries to enable remote debugging: +This command creates a *`launch.vs.json`* file in your project. Open it and change the following entries to enable remote debugging: -- `projectTarget`: this is set for you if you added the debug configuration file from the **Solution Explorer** targets view per the instructions above. +- `projectTarget`: this value is set for you if you added the debug configuration file from the **Solution Explorer** targets view per the instructions above. - `remoteMachineName`: set to the IP address of the remote ARM64 machine, or its machine name. -For more information about `launch.vs.json` settings, see [launch.vs.json schema reference](launch-vs-schema-reference-cpp.md). +For more information about *`launch.vs.json`* settings, see [`launch.vs.json` schema reference](launch-vs-schema-reference-cpp.md). > [!Note] -> If you're using the folder view instead of the targets view in **Solution Explorer**, right-click the `CMakeLists.txt` file and select **Add Debug Configuration**. This experience differs from adding the debug configuration from the targets view in the following ways: +> If you're using the folder view instead of the targets view in **Solution Explorer**, right-click the *`CMakeLists.txt`* file and select **Add Debug Configuration**. This experience differs from adding the debug configuration from the targets view in the following ways: +> > - You'll be asked to select a debugger (select **C/C++ Remote Windows Debug**). -> - Visual Studio will provide less configuration template information in the `launch.vs.json` file so you'll need to add it yourself. You'll need to provide the `remoteMachineName` and `projectTarget` entries. When you add the configuration from the targets view, you only need to specify `remoteMachineName`. -> - For the `projectTarget` setting value, check the startup item dropdown to get the unique name of your target, for example, in this tutorial it is `CMakeProject3.exe'. +> - Visual Studio will provide less configuration template information in the *`launch.vs.json`* file so you'll need to add it yourself. You'll need to provide the `remoteMachineName` and `projectTarget` entries. When you add the configuration from the targets view, you only need to specify `remoteMachineName`. +> - For the `projectTarget` setting value, check the startup item dropdown to get the unique name of your target, for example, in this tutorial it is *`CMakeProject3.exe`*'. ## Start the remote debugger monitor on the remote Windows machine @@ -109,11 +111,11 @@ Before you run your CMake project, ensure that the Visual Studio 2019 remote deb For example, on the remote machine, from the Visual Studio Remote Debugger menu bar, select **Tools** > **Options**. Set the **authentication mode** to match how your environment is set up: -![Remote debugger authentication options](media/remote-debugger-options.png) +![Remote debugger authentication options.](media/remote-debugger-options.png) -Then, in Visual Studio on the host machine, update the `launch.vs.json` file to match. For example, if you choose **No Authentication** on the remote debugger, update the `launch.vs.json` file in your project by adding **"authenticationType": "none"** to the `configurations` section `launch.vs.json`. Otherwise, `"authenticationType"` defaults to `"windows"` and doesn't need to be explicitly stated. This example shows a `launch.vs.json` file configured for no authentication: +Then, in Visual Studio on the host machine, update the *`launch.vs.json`* file to match. For example, if you choose **No Authentication** on the remote debugger, update the *`launch.vs.json`* file in your project by adding `"authenticationType": "none"` to the `configurations` section *`launch.vs.json`*. Otherwise, `"authenticationType"` defaults to `"windows"` and doesn't need to be explicitly stated. This example shows a *`launch.vs.json`* file configured for no authentication: -``` XAML +```XAML { "version": "0.2.1", "defaults": {}, @@ -147,23 +149,24 @@ On the host machine, in the Visual Studio **Solution Explorer**, open the CPP fi The default CPP file is a simple hello world console app. Set a breakpoint on `return 0;`. -On the Visual Studio toolbar, use the **Startup Item** dropdown to select the name you specified for `"name"` in your `launch.vs.json` file: +On the Visual Studio toolbar, use the **Startup Item** dropdown to select the name you specified for `"name"` in your *`launch.vs.json`* file: -![Example startup item dropdown with CMakeProject3.exe selected](media/startup-item.png) +![Example startup item dropdown with CMakeProject3.exe selected.](media/startup-item.png) To start debugging, on the Visual Studio toolbar choose **Debug** > **Start Debugging** (or press **F5**). -If it doesn't start, ensure that the following are set correctly in the `launch.vs.json` file: +If it doesn't start, ensure that the following are set correctly in the *`launch.vs.json`* file: + - `"remoteMachineName"` should be set to the IP address, or the machine name, of the remote ARM64 Windows machine. - `"name"` should match the selection in the Visual Studio startup item dropdown. - `"projectTarget"` should match the name of the CMake target you want to debug. - `"type"` should be `"remoteWindows"` -- If the authentication type on the remote debugger is set to **No Authentication**, you should have `"authenticationType": "none"` set in the `launch.vs.json` file. -- If you are using Windows authentication, sign in when prompted using an account recognized by the remote machine. +- If the authentication type on the remote debugger is set to **No Authentication**, you should have `"authenticationType": "none"` set in the *`launch.vs.json`* file. +- If you're using Windows authentication, sign in when prompted using an account recognized by the remote machine. After the project builds, the app should appear on the remote ARM64 Windows machine: -![Hello CMake console app running on remote Windows ARM64 machine](media/remote-cmake-app.png) +![Hello CMake console app running on remote Windows ARM64 machine.](media/remote-cmake-app.png) Visual Studio on the host machine should be stopped at the breakpoint for `return 0;`. @@ -180,4 +183,4 @@ Learn more about configuring and debugging CMake projects in Visual Studio: > [Customize CMake build settings](customize-cmake-settings.md)\ > [Configure CMake debugging sessions](configure-cmake-debugging-sessions.md)\ > [CMake predefined configuration reference](cmake-predefined-configuration-reference.md)\ -[launch.vs.json schema reference](launch-vs-schema-reference-cpp.md) +> [`launch.vs.json` schema reference](launch-vs-schema-reference-cpp.md) diff --git a/docs/build/cmakesettings-reference.md b/docs/build/cmakesettings-reference.md index cabbb63a01..e9a6acdb8f 100644 --- a/docs/build/cmakesettings-reference.md +++ b/docs/build/cmakesettings-reference.md @@ -5,7 +5,7 @@ ms.date: "11/22/2019" helpviewer_keywords: ["CMake in Visual C++"] ms.assetid: 444d50df-215e-4d31-933a-b41841f186f8 --- -# CMakeSettings.json schema reference +# `CMakeSettings.json` schema reference ::: moniker range="msvc-140" @@ -15,114 +15,114 @@ CMake projects are supported in Visual Studio 2017 and later. ::: moniker range=">=msvc-150" -The **CMakeSettings.json** file contains information that Visual Studio uses for IntelliSense and to construct the command-line arguments that it passes to cmake.exe for a specified *configuration* and compiler *environment*. A configuration specifies properties that apply to a specific platform and build-type, for example, `x86-Debug` or `Linux-Release`. Each configuration specifies an environment, which encapsulates information about the compiler toolset, for example MSVC, GCC, or Clang. CMake uses the command-line arguments to regenerate the root *CMakeCache.txt* file and other project files for the project. The values can be overridden in the *CMakeLists.txt* files. +The *`CMakeSettings.json`* file contains information that Visual Studio uses for IntelliSense and to construct the command-line arguments that it passes to CMake for a specified configuration and compiler environment. A *configuration* specifies properties that apply to a specific platform and build-type, for example, `x86-Debug` or `Linux-Release`. Each configuration specifies an *environment*, which encapsulates information about the compiler toolset, for example MSVC, GCC, or Clang. CMake uses the command-line arguments to regenerate the root *`CMakeCache.txt`* file and other project files for the project. The values can be overridden in the *`CMakeLists.txt`* files. -You can add or remove configurations in the IDE and then edit them directly in the JSON file or use the **CMake Settings editor** (Visual Studio 2019 and later). You can switch between the configurations easily in the IDE to generate the various project files. See [Customize CMake build settings in Visual Studio](customize-cmake-settings.md) for more information. +You can add or remove configurations in the IDE and then edit them directly in the JSON file or use the **CMake Settings editor** (Visual Studio 2019 and later). You can switch between the configurations easily in the IDE to generate the various project files. For more information, see [Customize CMake build settings in Visual Studio](customize-cmake-settings.md). ## Configurations -The `configurations` array contains all the configurations for a CMake project. See [CMake predefined configuration reference](cmake-predefined-configuration-reference.md) for more information about the pre-defined configurations. You can add any number of pre-defined or custom configurations to the file. +The `configurations` array contains all the configurations for a CMake project. For more information about the pre-defined configurations, see [CMake predefined configuration reference](cmake-predefined-configuration-reference.md). You can add any number of pre-defined or custom configurations to the file. A `configuration` has these properties: -- `addressSanitizerEnabled`: if **`true`** compiles the program with [AddressSanitizer](../sanitizers/asan.md). On Linux, compile with -fno-omit-frame-pointer and compiler optimization level -Os or -Oo for best results. -- `addressSanitizerRuntimeFlags`: runtime flags passed to [AddressSanitizer](../sanitizers/asan.md) via the ASAN_OPTIONS environment variable. Format: flag1=value:flag2=value2. -- `buildCommandArgs`: specifies native build switches passed to CMake after --build --. For example, passing -v when using the Ninja generator forces Ninja to output command lines. See [Ninja command line arguments](#ninja) for more information on Ninja commands. -- `buildRoot`: specifies the directory in which CMake generates build scripts for the chosen generator. Maps to **-DCMAKE_BINARY_DIR** switch and specifies where *CMakeCache.txt* will be created. If the folder does not exist, it is created. Supported macros include `${workspaceRoot}`, `${workspaceHash}`, `${projectFile}`, `${projectDir}`, `${thisFile}`, `${thisFileDir}`, `${name}`, `${generator}`, `${env.VARIABLE}`. -- `cacheGenerationCommand`: specifies a command line tool and arguments, for example *gencache.bat debug* to generate the cache. The command is run from the shell in the specified environment for the configuration when the user explicitly requests regeneration, or a CMakeLists.txt or CMakeSettings.json file is modified. -- `cacheRoot`: specifies the path to a CMake cache. This directory should contain an existing *CMakeCache.txt* file. -- `clangTidyChecks`: comma-separated list of warnings that will be passed to clang-tidy; wildcards are allowed and '-' prefix will remove checks. -- `cmakeCommandArgs`: specifies additional command-line options passed to CMake when invoked to generate the project files. -- `cmakeToolchain`: specifies the toolchain file. This is passed to CMake using -DCMAKE_TOOLCHAIN_FILE." -- `codeAnalysisRuleset`: specifies the ruleset to use when running code analysis. This can be a full path or the file name of a ruleset file installed by Visual Studio. -- `configurationType`: specifies the build type configuration for the selected generator. May be one of: - - - Debug - - Release - - MinSizeRel - - RelWithDebInfo +- `addressSanitizerEnabled`: If **`true`**, compiles the program using [AddressSanitizer](../sanitizers/asan.md). On Linux, compile with `-fno-omit-frame-pointer` and compiler optimization level `-Os` or `-Oo` for best results. +- `addressSanitizerRuntimeFlags`: The runtime flags passed to [AddressSanitizer](../sanitizers/asan.md) in the `ASAN_OPTIONS` environment variable. Format: flag1=value:flag2=value2. +- `buildCommandArgs`: Specifies native build switches passed to CMake after `--build --`. For example, passing `-v` when using the Ninja generator forces Ninja to output command lines. For more information on Ninja commands, see [Ninja command line arguments](#ninja). +- `buildRoot`: Specifies the directory in which CMake generates build scripts for the chosen generator. Maps to **`-DCMAKE_BINARY_DIR`** switch and specifies where *`CMakeCache.txt`* is created. If the folder doesn't exist, it's created. Supported macros include `${workspaceRoot}`, `${workspaceHash}`, `${projectFile}`, `${projectDir}`, `${thisFile}`, `${thisFileDir}`, `${name}`, `${generator}`, `${env.VARIABLE}`. +- `cacheGenerationCommand`: Specifies a command-line tool and arguments, for example **`gencache.bat debug`** to generate the cache. The command is run from the shell in the specified environment for the configuration when the user explicitly requests regeneration, or a *`CMakeLists.txt`* or *`CMakeSettings.json`* file is modified. +- `cacheRoot`: Specifies the path to a CMake cache. This directory should contain an existing *`CMakeCache.txt`* file. +- `clangTidyChecks`: comma-separated list of warnings that's passed to clang-tidy; wildcards are allowed and a '-' prefix removes checks. +- `cmakeCommandArgs`: Specifies any extra command-line options to pass to CMake when invoked to generate the project files. +- `cmakeToolchain`: Specifies the toolchain file. It's passed to CMake using `-DCMAKE_TOOLCHAIN_FILE`. +- `codeAnalysisRuleset`: Specifies the ruleset to use when running code analysis. You can use a full path or the filename of a ruleset file installed by Visual Studio. +- `configurationType`: Specifies the build type configuration for the selected generator. May be one of: + + - `Debug` + - `Release` + - `MinSizeRel` + - `RelWithDebInfo` -- `ctestCommandArgs`: specifies additional command-line options passed to CTest when running the tests." -- `description`: description of this configuration that will appear in menus. -- `enableClangTidyCodeAnalysis`: use Clang-Tidy for code analysis. -- `enableMicrosoftCodeAnalysis`: use Microsoft code analysis tools for code analysis. -- `generator`: specifies CMake generator to use for this configuration. May be one of: +- `ctestCommandArgs`: Specifies any extra command-line options to pass to CTest when running the tests. +- `description`: The description of this configuration that appears in menus. +- `enableClangTidyCodeAnalysis`: Use Clang-Tidy for code analysis. +- `enableMicrosoftCodeAnalysis`: Use Microsoft code analysis tools for code analysis. +- `generator`: Specifies the CMake generator to use for this configuration. May be one of: **Visual Studio 2019 only:** - - Visual Studio 16 2019 - - Visual Studio 16 2019 Win64 - - Visual Studio 16 2019 ARM + - `Visual Studio 16 2019` + - `Visual Studio 16 2019 Win64` + - `Visual Studio 16 2019 ARM` **Visual Studio 2017 and later:** - - Visual Studio 15 2017 - - Visual Studio 15 2017 Win64 - - Visual Studio 15 2017 ARM - - Visual Studio 14 2015 - - Visual Studio 14 2015 Win64 - - Visual Studio 14 2015 ARM - - Unix Makefiles - - Ninja - -Because Ninja is designed for fast build speeds instead of flexibility and function, it is set as the default. However, some CMake projects may be unable to correctly build using Ninja. If this occurs, you can instruct CMake to generate Visual Studio projects instead. - -To specify a Visual Studio generator in Visual Studio 2017, open the settings editor from the main menu by choosing **CMake | Change CMake Settings**. Delete "Ninja" and type "V". This activates IntelliSense, which enables you to choose the generator you want. - -To specify a Visual Studio generator in Visual Studio 2019, right-click on the *CMakeLists.txt* file in **Solution Explorer** and choose **CMake Settings for project** > **Show Advanced Settings** > **CMake Generator**. - -When the active configuration specifies a Visual Studio generator, by default MSBuild.exe is invoked with `-m -v:minimal` arguments. To customize the build, inside the *CMakeSettings.json* file, you can specify additional [MSBuild command line arguments](../build/reference/msbuild-visual-cpp-overview.md) to be passed to the build system via the `buildCommandArgs` property: - - ```json - "buildCommandArgs": "-m:8 -v:minimal -p:PreferredToolArchitecture=x64" - ``` - -- `installRoot`: specifies the directory in which CMake generates install targets for the chosen generator. Supported macros include `${workspaceRoot}`, `${workspaceHash}`, `${projectFile}`, `${projectDir}`, `${thisFile}`, `${thisFileDir}`, `${name}`, `${generator}`, `${env.VARIABLE}`. -- `inheritEnvironments`: specifies one or more compiler environments that this configuration depends on. May be any custom environment or one of the predefined environments. For more information, see [Environments](#environments). -- `intelliSenseMode`: specifies the mode used for computing intellisense information". May be one of: - - - windows-msvc-x86 - - windows-msvc-x64 - - windows-msvc-arm - - windows-msvc-arm64 - - android-clang-x86 - - android-clang-x64 - - android-clang-arm - - android-clang-arm64 - - ios-clang-x86 - - ios-clang-x64 - - ios-clang-arm - - ios-clang-arm64 - - windows-clang-x86 - - windows-clang-x64 - - windows-clang-arm - - windows-clang-arm64 - - linux-gcc-x86 - - linux-gcc-x64 - - linux-gcc-arm" - -- `name`: names the configuration. See [CMake predefined configuration reference](cmake-predefined-configuration-reference.md) for more information about the pre-defined configurations. + - `Visual Studio 15 2017` + - `Visual Studio 15 2017 Win64` + - `Visual Studio 15 2017 ARM` + - `Visual Studio 14 2015` + - `Visual Studio 14 2015 Win64` + - `Visual Studio 14 2015 ARM` + - `Unix Makefiles` + - `Ninja` + +Because Ninja is designed for fast build speeds instead of flexibility and function, it's set as the default. However, some CMake projects may be unable to correctly build using Ninja. If a build failure occurs, you can instruct CMake to generate Visual Studio projects instead. + +To specify a Visual Studio generator in Visual Studio 2017, open the settings editor from the main menu by choosing **CMake | Change CMake Settings**. Delete "Ninja" and enter "V". This change activates IntelliSense, which lets you choose the generator you want. + +To specify a Visual Studio generator in Visual Studio 2019, right-click on the *`CMakeLists.txt`* file in **Solution Explorer** and choose **CMake Settings for project** > **Show Advanced Settings** > **CMake Generator**. + +By default, when the active configuration specifies a Visual Studio generator, it invokes MSBuild with `-m -v:minimal` arguments. To customize the build, use the `buildCommandArgs` property inside the *`CMakeSettings.json`* file. Here, you can specify [MSBuild command line arguments](../build/reference/msbuild-visual-cpp-overview.md) to pass to the build system: + +```json +"buildCommandArgs": "-m:8 -v:minimal -p:PreferredToolArchitecture=x64" +``` + +- `installRoot`: Specifies the directory in which CMake generates install targets for the chosen generator. Supported macros include `${workspaceRoot}`, `${workspaceHash}`, `${projectFile}`, `${projectDir}`, `${thisFile}`, `${thisFileDir}`, `${name}`, `${generator}`, `${env.VARIABLE}`. +- `inheritEnvironments`: Specifies one or more compiler environments that this configuration depends on. May be any custom environment or one of the predefined environments. For more information, see [Environments](#environments). +- `intelliSenseMode`: Specifies the mode used for computing intellisense information". The value may be one of: + + - `windows-msvc-x86` + - `windows-msvc-x64` + - `windows-msvc-arm` + - `windows-msvc-arm64` + - `android-clang-x86` + - `android-clang-x64` + - `android-clang-arm` + - `android-clang-arm64` + - `ios-clang-x86` + - `ios-clang-x64` + - `ios-clang-arm` + - `ios-clang-arm64` + - `windows-clang-x86` + - `windows-clang-x64` + - `windows-clang-arm` + - `windows-clang-arm64` + - `linux-gcc-x86` + - `linux-gcc-x64` + - `linux-gcc-arm` + +- `name`: names the configuration. For more information about the pre-defined configurations, see [CMake predefined configuration reference](cmake-predefined-configuration-reference.md). - `wslPath`: the path to the launcher of an instance of Windows Subsystem for Linux. -### Additional settings for CMake Linux projects +### Settings for CMake Linux projects -- `remoteMachineName`: specifies the name of the remote Linux machine that hosts CMake, builds, and the debugger. Use the Connection Manager for adding new Linux machines. Supported macros include `${defaultRemoteMachineName}`. -- `remoteCopySourcesOutputVerbosity`: specifies the verbosity level of the source copying operation to the remote machine. May be one of ""Normal", "Verbose", or "Diagnostic". -- `remoteCopySourcesConcurrentCopies`: specifies the number of concurrent copies used during the synchronization of the sources to the remote machine (sftp only). -- `remoteCopySourcesMethod`: specifies the method to copy files to the remote machine. May be "rsync" or "sftp". -- `remoteCMakeListsRoot`: specifies the directory on the remote machine that contains the CMake project. Supported macros include `${workspaceRoot}`, `${workspaceHash}`, `${projectFile}`, `${projectDir}`, `${thisFile}`, `${thisFileDir}`, `${name}`, `${generator}`, `${env.VARIABLE}`. -- `remoteBuildRoot`: specifies the directory on the remote machine in which CMake generates build scripts for the chosen generator. Supported macros include `${workspaceRoot}`, `${workspaceHash}`, `${projectFile}`, `${projectDir}`, `${thisFile}`, `${thisFileDir}`, `${name}`, `${generator}`, `${env.VARIABLE}`. -- `remoteInstallRoot`: specifies the directory on the remote machine in which CMake generates install targets for the chosen generator. Supported macros include `${workspaceRoot}`, `${workspaceHash}`, `${projectFile}`, `${projectDir}`, `${thisFile}`, `${thisFileDir}`, `${name}`, `${generator}`, and `${env.VARIABLE}` where `VARIABLE` is an environment variable that has been defined at the system, user, or session level. +- `remoteMachineName`: Specifies the name of the remote Linux machine that hosts CMake, builds, and the debugger. Use the Connection Manager for adding new Linux machines. Supported macros include `${defaultRemoteMachineName}`. +- `remoteCopySourcesOutputVerbosity`: Specifies the verbosity level of the source copying operation to the remote machine. May be one of `Normal`, `Verbose`, or `Diagnostic`. +- `remoteCopySourcesConcurrentCopies`: Specifies the concurrent copies to use during synchronization of the sources to the remote machine (sftp only). +- `remoteCopySourcesMethod`: Specifies the method to copy files to the remote machine. May be `rsync` or `sftp`. +- `remoteCMakeListsRoot`: Specifies the directory on the remote machine that contains the CMake project. Supported macros include `${workspaceRoot}`, `${workspaceHash}`, `${projectFile}`, `${projectDir}`, `${thisFile}`, `${thisFileDir}`, `${name}`, `${generator}`, and `${env.VARIABLE}`. +- `remoteBuildRoot`: Specifies the directory on the remote machine in which CMake generates build scripts for the chosen generator. Supported macros include `${workspaceRoot}`, `${workspaceHash}`, `${projectFile}`, `${projectDir}`, `${thisFile}`, `${thisFileDir}`, `${name}`, `${generator}`, `${env.VARIABLE}`. +- `remoteInstallRoot`: Specifies the directory on the remote machine in which CMake generates install targets for the chosen generator. Supported macros include `${workspaceRoot}`, `${workspaceHash}`, `${projectFile}`, `${projectDir}`, `${thisFile}`, `${thisFileDir}`, `${name}`, `${generator}`, and `${env.VARIABLE}`, where `VARIABLE` is an environment variable that's been defined at the system, user, or session level. - `remoteCopySources`: A `boolean` that specifies whether Visual Studio should copy source files to the remote machine. The default is true. Set to false if you manage file synchronization yourself. - `remoteCopyBuildOutput`: A `boolean` that specifies whether to copy the build outputs from the remote system. - `remoteCopyAdditionalIncludeDirectories`: Additional include directories to be copied from the remote machine to support IntelliSense. Format as "/path1;/path2...". - `remoteCopyExcludeDirectories`: Include directories NOT to copy from the remote machine. Format as "/path1;/path2...". - `remoteCopyUseCompilerDefaults`: Specifies whether to use the compiler's default defines and include paths for IntelliSense. Should only be false if the compilers in use to not support gcc-style arguments. -- `rsyncCommandArgs`: specifies a set of additional command-line options passed to rsync. -- `remoteCopySourcesExclusionList`: A `array` that specifies a list of paths to be excluded when copying source files`: a path can be the name of a file/directory, or a path relative to root of the copy. Wildcards \\\"*\\\" and \\\"?\\\" can be used for glob pattern matching. -- `cmakeExecutable`: specifies the full path to the CMake program executable, including the file name and extension. -- `remotePreGenerateCommand`: specifies the command to run before running CMake to parse the *CMakeLists.txt* file. -- `remotePrebuildCommand`: specifies the command to run on the remote machine before building. -- `remotePostbuildCommand`: specifies the command to run on the remote machine after building. -- `variables`: contains a name-value pair of CMake variables that will get passed as **-D** *_name_=_value_* to CMake. If your CMake project build instructions specify the addition of any variables directly to the *CMakeCache.txt* file, it is recommended that you add them here instead. The following example shows how to specify the name-value pairs for the 14.14.26428 MSVC toolset: +- `rsyncCommandArgs`: Specifies a set of command-line options passed to rsync. +- `remoteCopySourcesExclusionList`: An `array` that specifies a list of paths to be excluded when copying source files: a path can be the name of a file/directory, or a relative path from the root of the copy. Wildcards `*` and `?` can be used for glob pattern matching. +- `cmakeExecutable`: Specifies the full path to the CMake program executable, including the file name and extension. +- `remotePreGenerateCommand`: Specifies the command to run before running CMake to parse the *`CMakeLists.txt`* file. +- `remotePrebuildCommand`: Specifies the command to run on the remote machine before building. +- `remotePostbuildCommand`: Specifies the command to run on the remote machine after building. +- `variables`: Contains a name-value pair of CMake variables that get passed as **`-D name=value`** to CMake. If your CMake project build instructions specify the addition of any variables directly to the *`CMakeCache.txt`* file, we recommend you add them here instead. This example shows how to specify the name-value pairs to use the 14.14.26428 MSVC toolset: ```json "variables": [ @@ -139,46 +139,48 @@ When the active configuration specifies a Visual Studio generator, by default MS ] ``` -Note that if you do not define the `"type"`, the `"STRING"` type will be assumed by default. +If you don't define the `"type"`, the `"STRING"` type is assumed by default. - `remoteCopyOptimizations`: **Visual Studio 2019 version 16.5 or later** properties for controlling source copy to the remote target. Optimizations are enabled by default. Includes `remoteCopyUseOptimizations`, `rsyncSingleDirectoryCommandArgs`, and `remoteCopySourcesMaxSmallChange`. ## Environments -An *environment* encapsulates the environment variables that are set in the process that Visual Studio uses to invoke cmake.exe. For MSVC projects, the variables are those that are set in a [developer command prompt](building-on-the-command-line.md) for a specific platform. For example, the `msvc_x64_x64` environment is the same as running the **Developer Command Prompt for VS 2017** or **Developer Command Prompt for VS 2019** with the **-arch=amd64 -host_arch=amd64** arguments. You can use the `env.{}` syntax in *CMakeSettings.json* to reference the individual environment variables, for example to construct paths to folders. The following predefined environments are provided: +An *environment* encapsulates the environment variables set in the process that Visual Studio uses to invoke CMake. For MSVC projects, it captures the variables set in a [developer command prompt](building-on-the-command-line.md) for a specific platform. For example, the `msvc_x64_x64` environment is the same as running the **Developer Command Prompt for VS {version}** with the **-arch=amd64 -host_arch=amd64** arguments. You can use the `env.{}` syntax in *`CMakeSettings.json`* to reference the individual environment variables, for example to construct paths to folders. The following predefined environments are provided: -- linux_arm: Target ARM Linux remotely. -- linux_x64: Target x64 Linux remotely. -- linux_x86: Target x86 Linux remotely. -- msvc_arm: Target ARM Windows with the MSVC compiler. -- msvc_arm_x64: Target ARM Windows with the 64-bit MSVC compiler. -- msvc_arm64: Target ARM64 Windows with the MSVC compiler. -- msvc_arm64_x64: Target ARM64 Windows with the 64-bit MSVC compiler. -- msvc_x64: Target x64 Windows with the MSVC compiler. -- msvc_x64_x64: Target x64 Windows with the 64-bit MSVC compiler. -- msvc_x86: Target x86 Windows with the MSVC compiler. -- msvc_x86_x64: Target x86 Windows with the 64-bit MSVC compiler. +- `linux_arm`: Target ARM Linux remotely. +- `linux_x64`: Target x64 Linux remotely. +- `linux_x86`: Target x86 Linux remotely. +- `msvc_arm`: Target ARM Windows with the MSVC compiler. +- `msvc_arm_x64`: Target ARM Windows with the 64-bit MSVC compiler. +- `msvc_arm64`: Target ARM64 Windows with the MSVC compiler. +- `msvc_arm64_x64`: Target ARM64 Windows with the 64-bit MSVC compiler. +- `msvc_arm64ec`: Target ARM64EC Windows with the MSVC compiler. +- `msvc_arm64ec_x64`: Target ARM64EC Windows with the 64-bit MSVC compiler. +- `msvc_x64`: Target x64 Windows with the MSVC compiler. +- `msvc_x64_x64`: Target x64 Windows with the 64-bit MSVC compiler. +- `msvc_x86`: Target x86 Windows with the MSVC compiler. +- `msvc_x86_x64`: Target x86 Windows with the 64-bit MSVC compiler. -### Accessing environment variables from CMakeLists.txt +### Accessing environment variables from *`CMakeLists.txt`* -From a CMakeLists.txt file, all environment variables are referenced by the syntax `$ENV{variable_name}`. To see the available variables for an environment, open the corresponding command prompt and type `SET`. Some of the information in environment variables is also available through CMake system introspection variables, but you may find it more convenient to use the environment variable. For example, the MSVC compiler version or Windows SDK version are easily retrieved through the environment variables. +From a *`CMakeLists.txt`* file, all environment variables are referenced by the syntax `$ENV{variable_name}`. To see the available variables for an environment, open the corresponding command prompt and type `SET`. Some of the information in environment variables is also available through CMake system introspection variables, but you may find it more convenient to use the environment variable. For example, you can easily retrieve the MSVC compiler version or Windows SDK version through the environment variables. ### Custom environment variables -In `CMakeSettings.json`, you can define custom environment variables globally or per-configuration in the `environments` array. A custom environment is a convenient way to group a set of properties that you can use in place of a predefined environment, or to extend or modify a predefined environment. Each item in the `environments` array consists of: +In *`CMakeSettings.json`*, you can define custom environment variables globally or per-configuration in the `environments` array. A custom environment is a convenient way to group a set of properties. You can use it in place of a predefined environment, or to extend or modify a predefined environment. Each item in the `environments` array consists of: -- `namespace`: names the environment so that its variables can be referenced from a configuration in the form `namespace.variable`. The default environment object is called `env` and is populated with certain system environment variables including `%USERPROFILE%`. -- `environment`: uniquely identifies this group of variables. Allows the group to be inherited later in an `inheritEnvironments` entry. +- `namespace`: Names the environment so that its variables can be referenced from a configuration in the form `namespace.variable`. The default environment object is called `env` and is populated with certain system environment variables including `%USERPROFILE%`. +- `environment`: Uniquely identifies this group of variables. Allows the group to be inherited later in an `inheritEnvironments` entry. - `groupPriority`: An integer that specifies the priority of these variables when evaluating them. Higher number items are evaluated first. -- `inheritEnvironments`: An array of values that specify the set of environments that are inherited by this group. This feature enables you to inherit default environments and create custom environment variables that are passed to CMake.exe when it runs. +- `inheritEnvironments`: An array of values that specify the set of environments that are inherited by this group. This feature lets you inherit default environments and create custom environment variables to pass to CMake when it runs. -**Visual Studio 2019 version 16.4 and later:** Debug targets are automatically launched with the environment you specify in *CMakeSettings.json*. You can override or add environment variables on a per-target or per-task basis in [launch.vs.json](launch-vs-schema-reference-cpp.md) and [tasks.vs.json](tasks-vs-json-schema-reference-cpp.md). +**Visual Studio 2019 version 16.4 and later:** Debug targets are automatically launched with the environment you specify in *`CMakeSettings.json`*. You can override or add environment variables on a per-target or per-task basis in [`launch.vs.json`](launch-vs-schema-reference-cpp.md) and [`tasks.vs.json`](tasks-vs-json-schema-reference-cpp.md). -The following example defines one global variable, **BuildDir**, which is inherited in both the x86-Debug and x64-Debug configurations. Each configuration uses the variable to specify the value for the **buildRoot** property for that configuration. Note also how each configuration uses the **inheritEnvironments** property to specify a variable that applies only to that configuration. +The following example defines one global variable, `BuildDir`, which is inherited in both the x86-Debug and x64-Debug configurations. Each configuration uses the variable to specify the value for the `buildRoot` property for that configuration. Note also how each configuration uses the `inheritEnvironments` property to specify a variable that applies only to that configuration. ```json { - // The "environments" property is an array of key value pairs of the form + // The "environments" property is an array of key-value pairs of the form // { "EnvVar1": "Value1", "EnvVar2": "Value2" } "environments": [ { @@ -225,7 +227,7 @@ In the next example, the x86-Debug configuration defines its own value for the * { // Replace the global property entirely. "BuildDir": "D:\\custom-builddir" - // This environment does not specify a namespace, hence by default "env" will be assumed. + // This environment does not specify a namespace, hence by default "env" is assumed. // "namespace" : "name" would require that this variable be referenced with "${name.BuildDir}". } ], @@ -252,21 +254,22 @@ In the next example, the x86-Debug configuration defines its own value for the * ## Macros -The following macros can be used in *CMakeSettings.json*: +The following macros can be used in *`CMakeSettings.json`*: - `${workspaceRoot}` – the full path of the workspace folder - `${workspaceHash}` – hash of workspace location; useful for creating a unique identifier for the current workspace (for example, to use in folder paths) -- `${projectFile}` – the full path of the root CMakeLists.txt file -- `${projectDir}` – the full path of the folder of the root CMakeLists.txt file -- `${thisFile}` – the full path of the `CMakeSettings.json` file +- `${projectFile}` – the full path of the root *`CMakeLists.txt`* file +- `${projectDir}` – the full path of the folder containing the root *`CMakeLists.txt`* file +- `${projectDirName}` – the name of the folder containing the root *`CMakeLists.txt`* file +- `${thisFile}` – the full path of the *`CMakeSettings.json`* file - `${name}` – the name of the configuration - `${generator}` – the name of the CMake generator used in this configuration -All references to macros and environment variables in *CMakeSettings.json* are expanded before being passed to the cmake.exe command line. +All references to macros and environment variables in *`CMakeSettings.json`* are expanded before being passed to the CMake command line. -## Ninja command line arguments +## Ninja command-line arguments -If targets are unspecified, builds the 'default' target. +If targets are unspecified, Ninja builds the 'default' target. ```cmd C:\Program Files (x86)\Microsoft Visual Studio\Preview\Enterprise>ninja -? @@ -274,18 +277,18 @@ ninja: invalid option -- `-?' usage: ninja [options] [targets...] ``` -|Option|Description| -|--------------|------------| -| --version | print ninja version ("1.7.1")| -| -C DIR | change to DIR before doing anything else| -| -f FILE | specify input build file (default=build.ninja)| -| -j N | run N jobs in parallel (default=14, derived from CPUs available)| -| -k N | keep going until N jobs fail (default=1)| -| -l N | do not start new jobs if the load average is greater than N| -| -n | dry run (don't run commands but act like they succeeded)| -| -v | show all command lines while building| -| -d MODE | enable debugging (use -d list to list modes)| -| -t TOOL | run a subtool (use -t list to list subtools). terminates top-level options; further flags are passed to the tool| -| -w FLAG | adjust warnings (use -w list to list warnings)| +| Option | Description | +|--|--| +| `--version` | Print ninja version ("1.7.1") | +| `-C DIR` | Change to DIR before doing anything else | +| `-f FILE` | Specify input build file (default=*`build.ninja`*) | +| `-j N` | Run `N` jobs in parallel (default=14, derived from CPUs available) | +| `-k N` | Keep going until `N` jobs fail (default=1) | +| `-l N` | Don't start new jobs if the load average is greater than `N` | +| `-n` | Dry run (don't run commands but act like they succeeded) | +| `-v` | Show all command lines while building | +| `-d MODE` | Enable debugging (use `-d list` to list modes) | +| `-t TOOL` | Run a subtool (use `-t list` to list subtools). Ends any top-level options; further flags are passed to the tool | +| `-w FLAG` | Adjust warnings (use `-w list` to list warnings) | ::: moniker-end diff --git a/docs/build/common-visual-cpp-arm-migration-issues.md b/docs/build/common-visual-cpp-arm-migration-issues.md index f723c06625..36035c044b 100644 --- a/docs/build/common-visual-cpp-arm-migration-issues.md +++ b/docs/build/common-visual-cpp-arm-migration-issues.md @@ -2,28 +2,30 @@ description: "Learn more about: Common Visual C++ ARM Migration Issues" title: "Common Visual C++ ARM Migration Issues" ms.date: "05/06/2019" -ms.assetid: 0f4c434e-0679-4331-ba0a-cc15dd435a46 --- -# Common Visual C++ ARM Migration Issues +# Common Visual C++ ARM migration issues -When using the Microsoft C++ compiler (MSVC), the same C++ source code might produce different results on the ARM architecture than it does on x86 or x64 architectures. +This document describes some of the common issues that you might encounter when you migrate code from x86 or x64 architectures to the ARM architecture. It also describes how to avoid these issues, and how to use the compiler to help identify them. + +> [!NOTE] +> When this article refers to the ARM architecture, it applies to both ARM32 and ARM64. ## Sources of migration issues Many issues that you might encounter when you migrate code from the x86 or x64 architectures to the ARM architecture are related to source-code constructs that might invoke undefined, implementation-defined, or unspecified behavior. -*Undefined behavior* is behavior that the C++ standard does not define, and that's caused by an operation that has no reasonable result: for example, converting a floating-point value to an unsigned integer, or shifting a value by a number of positions that is negative or exceeds the number of bits in its promoted type. +*Undefined behavior* is behavior that the C++ standard doesn't define, and that's caused by an operation that has no reasonable result: for example, converting a floating-point value to an unsigned integer, or shifting a value by a number of positions that is negative or exceeds the number of bits in its promoted type. *Implementation-defined behavior* is behavior that the C++ standard requires the compiler vendor to define and document. A program can safely rely on implementation-defined behavior, even though doing so might not be portable. Examples of implementation-defined behavior include the sizes of built-in data types and their alignment requirements. An example of an operation that might be affected by implementation-defined behavior is accessing the variable arguments list. -*Unspecified behavior* is behavior that the C++ standard leaves intentionally non-deterministic. Although the behavior is considered non-deterministic, particular invocations of unspecified behavior are determined by the compiler implementation. However, there is no requirement for a compiler vendor to predetermine the result or guarantee consistent behavior between comparable invocations, and there is no requirement for documentation. An example of unspecified behavior is the order in which sub-expressions, which include arguments to a function call, are evaluated. +*Unspecified behavior* is behavior that the C++ standard leaves intentionally nondeterministic. Although the behavior is considered nondeterministic, particular invocations of unspecified behavior are determined by the compiler implementation. However, there's no requirement for a compiler vendor to predetermine the result or guarantee consistent behavior between comparable invocations, and there's no requirement for documentation. An example of unspecified behavior is the order in which sub-expressions, which include arguments to a function call, are evaluated. -Other migration issues can be attributed to hardware differences between ARM and x86 or x64 architectures that interact with the C++ standard differently. For example, the strong memory model of the x86 and x64 architecture gives **`volatile`**-qualified variables some additional properties that have been used to facilitate certain kinds of inter-thread communication in the past. But the ARM architecture's weak memory model doesn't support this use, nor does the C++ standard require it. +Other migration issues can be attributed to hardware differences between ARM and x86 or x64 architectures that interact with the C++ standard differently. For example, the strong memory model of the x86 and x64 architecture gives **`volatile`**-qualified variables some extra properties that have been used to facilitate certain kinds of inter-thread communication in the past. But the ARM architecture's weak memory model doesn't support this use, nor does the C++ standard require it. > [!IMPORTANT] -> Although **`volatile`** gains some properties that can be used to implement limited forms of inter-thread communication on x86 and x64, these additional properties are not sufficient to implement inter-thread communication in general. The C++ standard recommends that such communication be implemented by using appropriate synchronization primitives instead. +> Although **`volatile`** gains some properties that can be used to implement limited forms of inter-thread communication on x86 and x64, these properties aren't sufficient to implement inter-thread communication in general. The C++ standard recommends that such communication be implemented by using appropriate synchronization primitives instead. -Because different platforms might express these kinds of behavior differently, porting software between platforms can be difficult and bug-prone if it depends on the behavior of a specific platform. Although many of these kinds of behavior can be observed and might appear stable, relying on them is at least non-portable, and in the cases of undefined or unspecified behavior, is also an error. Even the behavior that's cited in this document should not be relied on, and could change in future compilers or CPU implementations. +Because different platforms might express these kinds of behavior differently, porting software between platforms can be difficult and bug-prone if it depends on the behavior of a specific platform. Although many of these kinds of behavior can be observed and might appear stable, relying on them is at least non-portable, and in the cases of undefined or unspecified behavior, is also an error. Even the behavior cited in this document shouldn't be relied on, and could change in future compilers or CPU implementations. ## Example migration issues @@ -41,15 +43,15 @@ These platforms also differ in how they handle conversion of NaN (Not-a-Number) Floating-point conversion can only be relied on if you know that the value is within the range of the integer type that it's being converted to. -### Shift operator (\<\< >>) behavior +### Shift operator (`<<` `>>`) behavior -On the ARM architecture, a value can be shifted left or right up to 255 bits before the pattern begins to repeat. On x86 and x64 architectures, the pattern is repeated at every multiple of 32 unless the source of the pattern is a 64-bit variable; in that case, the pattern repeats at every multiple of 64 on x64, and every multiple of 256 on x86, where a software implementation is employed. For example, for a 32-bit variable that has a value of 1 shifted left by 32 positions, on ARM the result is 0, on x86 the result is 1, and on x64 the result is also 1. However, if the source of the value is a 64-bit variable, then the result on all three platforms is 4294967296, and the value doesn't "wrap around" until it's shifted 64 positions on x64, or 256 positions on ARM and x86. +On the ARM architecture, a value can be shifted left or right up to 255 bits before the pattern begins to repeat. On x86 and x64 architectures, the pattern is repeated at every multiple of 32 unless the source of the pattern is a 64-bit variable. In that case, the pattern repeats at every multiple of 64 on x64, and every multiple of 256 on x86, where a software implementation is employed. For example, for a 32-bit variable that has a value of 1 shifted left by 32 positions, on ARM the result is 0, on x86 the result is 1, and on x64 the result is also 1. However, if the source of the value is a 64-bit variable, then the result on all three platforms is 4294967296, and the value doesn't "wrap around" until it's shifted 64 positions on x64, or 256 positions on ARM and x86. -Because the result of a shift operation that exceeds the number of bits in the source type is undefined, the compiler is not required to have consistent behavior in all situations. For example, if both operands of a shift are known at compile time, the compiler may optimize the program by using an internal routine to precompute the result of the shift and then substituting the result in place of the shift operation. If the shift amount is too large, or negative, the result of the internal routine might be different than the result of the same shift expression as executed by the CPU. +Because the result of a shift operation that exceeds the number of bits in the source type is undefined, the compiler isn't required to have consistent behavior in all situations. For example, if both operands of a shift are known at compile time, the compiler may optimize the program by using an internal routine to precompute the result of the shift and then substituting the result in place of the shift operation. If the shift amount is too large, or negative, the result of the internal routine might be different than the result of the same shift expression as executed by the CPU. ### Variable arguments (varargs) behavior -On the ARM architecture, parameters from the variable arguments list that are passed on the stack are subject to alignment. For example, a 64-bit parameter is aligned on a 64-bit boundary. On x86 and x64, arguments that are passed on the stack are not subject to alignment and pack tightly. This difference can cause a variadic function like `printf` to read memory addresses that were intended as padding on ARM if the expected layout of the variable arguments list is not matched exactly, even though it might work for a subset of some values on the x86 or x64 architectures. Consider this example: +On the ARM architecture, parameters from the variable arguments list that are passed on the stack are subject to alignment. For example, a 64-bit parameter is aligned on a 64-bit boundary. On x86 and x64, arguments that are passed on the stack aren't subject to alignment and pack tightly. This difference can cause a variadic function like `printf` to read memory addresses that were intended as padding on ARM if the expected layout of the variable arguments list isn't matched exactly, even though it might work for a subset of some values on the x86 or x64 architectures. Consider this example: ```C // notice that a 64-bit integer is passed to the function, but '%d' is used to read it. @@ -69,7 +71,7 @@ printf("%I64d\n", 1LL); Because ARM, x86, and x64 processors are so different, they can present different requirements to compiler implementations, and also different opportunities for optimizations. Because of this, together with other factors like calling-convention and optimization settings, a compiler might evaluate function arguments in a different order on different architectures or when the other factors are changed. This can cause the behavior of an app that relies on a specific evaluation order to change unexpectedly. -This kind of error can occur when arguments to a function have side effects that impact other arguments to the function in the same call. Usually this kind of dependency is easy to avoid, but it can sometimes be obscured by dependencies that are difficult to discern, or by operator overloading. Consider this code example: +This kind of error can occur when arguments to a function have side effects that impact other arguments to the function in the same call. Usually this kind of dependency is easy to avoid but can be obscured by dependencies that are difficult to discern or by operator overloading. Consider this code example: ```cpp handle memory_handle; @@ -83,15 +85,15 @@ This appears well-defined, but if `->` and `*` are overloaded operators, then th Handle::acquire(operator->(memory_handle), operator*(p)); ``` -And if there's a dependency between `operator->(memory_handle)` and `operator*(p)`, the code might rely on a specific evaluation order, even though the original code looks like there is no possible dependency. +And if there's a dependency between `operator->(memory_handle)` and `operator*(p)`, the code might rely on a specific evaluation order, even though the original code looks like there's no possible dependency. -### volatile keyword default behavior +### `volatile` keyword default behavior The MSVC compiler supports two different interpretations of the **`volatile`** storage qualifier that you can specify by using compiler switches. The [/volatile:ms](reference/volatile-volatile-keyword-interpretation.md) switch selects the Microsoft extended volatile semantics that guarantee strong ordering, as has been the traditional case for x86 and x64 because of the strong memory model on those architectures. The [/volatile:iso](reference/volatile-volatile-keyword-interpretation.md) switch selects the strict C++ standard volatile semantics that don't guarantee strong ordering. -On the ARM architecture, the default is **/volatile:iso** because ARM processors have a weakly ordered memory model, and because ARM software doesn't have a legacy of relying on the extended semantics of **/volatile:ms** and doesn't usually have to interface with software that does. However, it's still sometimes convenient or even required to compile an ARM program to use the extended semantics. For example, it may be too costly to port a program to use the ISO C++ semantics, or driver software might have to adhere to the traditional semantics to function correctly. In these cases, you can use the **/volatile:ms** switch; however, to recreate the traditional volatile semantics on ARM targets, the compiler must insert memory barriers around each read or write of a **`volatile`** variable to enforce strong ordering, which can have a negative impact on performance. +On the ARM architecture (except ARM64EC), the default is **/volatile:iso** because ARM processors have a weakly ordered memory model, and because ARM software doesn't have a legacy of relying on the extended semantics of **/volatile:ms** and doesn't usually have to interface with software that does. However, it's still sometimes convenient or even required to compile an ARM program to use the extended semantics. For example, it may be too costly to port a program to use the ISO C++ semantics, or driver software might have to adhere to the traditional semantics to function correctly. In these cases, you can use the **/volatile:ms** switch; however, to recreate the traditional volatile semantics on ARM targets, the compiler must insert memory barriers around each read or write of a **`volatile`** variable to enforce strong ordering, which can have a negative impact on performance. -On the x86 and x64 architectures, the default is **/volatile:ms** because much of the software that has already been created for these architectures by using MSVC relies on them. When you compile x86 and x64 programs, you can specify the **/volatile:iso** switch to help avoid unnecessary reliance on the traditional volatile semantics, and to promote portability. +On the x86, x64, and ARM64EC architectures, the default is **/volatile:ms** because much of the software that has already been created for these architectures by using MSVC relies on them. When you compile x86, x64 and ARM64EC programs, you can specify the **/volatile:iso** switch to help avoid unnecessary reliance on the traditional volatile semantics, and to promote portability. ## See also diff --git a/docs/build/compare-inclusion-methods.md b/docs/build/compare-inclusion-methods.md new file mode 100644 index 0000000000..8c16032aee --- /dev/null +++ b/docs/build/compare-inclusion-methods.md @@ -0,0 +1,43 @@ +--- +description: "Learn about the different ways to include library headers in C++: header files vs modules vs header units vs precompiled headers." +title: "Compare header units, modules, and precompiled headers" +ms.date: 11/30/2022 +f1_keywords: ["#include", "header file", "header unit", "module", "named module", "PCH", "precompiled header file", "IFC"] +helpviewer_keywords: ["headers, C++ library", "libraries, Standard C++", "C++ Standard Library, headers", "STL", "Standard template library, headers", "precompiled header files, creating", "PCH files, creating", "import", "header unit", "ifc", "modules [C++]", "named modules [C++]", "import standard library (STL) using named modules"] +--- +# Compare header units, modules, and precompiled headers + +Historically, you'd include the standard library with a directive like `#include `. However, it's expensive to include header files because they're reprocessed by every source file that includes them. + +Precompiled headers (PCH) were introduced to speed compilation by translating them once and reusing the result. But precompiled headers can be difficult to maintain. + +In C++20, modules were introduced as a significant improvement on header files and precompiled headers. + +Header units were introduced in C++20 as a way to temporarily bridge the gap between header files and modules. They provide some of the speed and robustness benefits of modules, while you migrate your code to use modules. + +Then, the C++23 standard library introduced support for importing the standard library as named modules. This is the fastest and most robust way to consume the standard library. + +To help you sort out the different options, this article compares the traditional `#include` method against precompiled headers, header units, and importing named modules. + +The following table is arranged by compiler processing speed and robustness, with `#include` being the slowest and least robust, and `import` being the fastest and most robust. + +| Method | Summary | +|---|---| +| `#include` | One disadvantage is that they expose macros and internal implementation. Internal implementation is often exposed as functions and types that start with an underscore. That's a convention to indicate that something is part of the internal implementation and shouldn't be used.

Header files are fragile because the order of #includes can modify behavior or break code and are affected by macro definitions.

Header files slow compilation. Particularly when multiple files include the same file because then the header file is reprocessed multiple times. | +| [Precompiled header](../build/creating-precompiled-header-files.md) | A precompiled header (PCH) improves compile time by creating a compiler memory snapshot of a set of header files. This is an improvement on repeatedly rebuilding header files.

PCH files have restrictions that make them difficult to maintain.

PCH files are faster than `#include` but slower than `import`.| +| [Header units](../build/walkthrough-header-units.md) | This is a new feature in C++20 that allows you to import 'well-behaved' header files as modules.

Header units are faster than `#include`, and are easier to maintain, significantly smaller, and also faster than pre-compiled header files (PCH).

Header units are an 'in-between' step meant to help transition to named modules in cases where you rely on macros defined in header files, since named modules don't expose macros.

Header units are slower than importing a named module.

Header units aren't affected by macro defines unless they're specified on the command line when the header unit is built--making them more robust than header files.

Header units expose the macros and internal implementation defined in them just as header file do, which named modules don't.

As a rough approximation of file size, a 250-megabyte PCH file might be represented by an 80-megabyte header unit file. | +| [Modules](../cpp/modules-cpp.md) | This is the fastest and most robust way to import functionality.

Support for importing modules was introduced in C++20. The C++23 standard library introduces the two named modules described in this topic.

When you import `std`, you get the standard names such as `std::vector`, `std::cout`, but no extensions, no internal helpers such as `_Sort_unchecked`, and no macros.

The order of imports doesn't matter because there are no macro or other side-effects.

As a rough approximation of file size, a 250-megabyte PCH file might be represented by an 80-megabyte header unit file, which might be represented by a 25-megabyte module.

Named modules are faster because when a named module is compiled into an `.ifc` file and an `.obj` file, the compiler emits a structured representation of the source code that can be loaded quickly when the module is imported. The compiler can do some work (like name resolution) before emitting the `.ifc` file because of how named modules are order-independent and macro-independent--so this work doesn't have to be done when the module is imported. In contrast, when a header file is consumed with `#include`, its contents must be preprocessed and compiled again and again in every translation unit.

Precompiled headers, which are compiler memory snapshots, can mitigate those costs, but not as well as named modules. | + +If you can use C++20 features and the C++23 standard library in your app, use named modules. + +If you can use C++20 features but want to transition over time to modules, use header units in the interim. + +If you can't use C++20 features, use `#include` and consider precompiled headers. + +## See also + +[Precompiled header files](creating-precompiled-header-files.md)\ +[Overview of modules in C++](../cpp/modules-cpp.md)\ +[Tutorial: Import the C++ standard library using modules](../cpp/tutorial-import-stl-named-module.md)\ +[Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md#approach1)\ +[Walkthrough: Build and import header units in your Visual C++ projects](walkthrough-header-units.md) \ No newline at end of file diff --git a/docs/build/configure-cmake-debugging-sessions.md b/docs/build/configure-cmake-debugging-sessions.md index 873a377928..896d5a3bf4 100644 --- a/docs/build/configure-cmake-debugging-sessions.md +++ b/docs/build/configure-cmake-debugging-sessions.md @@ -1,14 +1,14 @@ --- title: "Configure CMake debugging sessions in Visual Studio" description: "Describes how to use Visual Studio to configure CMake debugger settings." -ms.date: 12/16/2020 +ms.date: 10/26/2023 helpviewer_keywords: ["CMake debugging"] --- # Configure CMake debugging sessions ::: moniker range="msvc-140" -Native CMake support is available in Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +Native CMake support is available in Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or later. It's found at the top of the table of contents on this page. ::: moniker-end @@ -16,29 +16,43 @@ Native CMake support is available in Visual Studio 2017 and later. To see the do All executable CMake targets are shown in the **Startup Item** dropdown in the toolbar. Select one to start a debugging session and launch the debugger. -![CMake startup item dropdown](media/cmake-startup-item-dropdown.png "CMake startup item dropdown") +:::image type="complex" source="media/new-dropdowns.png" alt-text="Screenshot of the CMake startup items dropdown."::: +The dropdown provides a list of debug targets to choose from. The selected item appears as a play button followed by the name of the selected debug target to run. In this example, the selected debug target is Hello World .exe. +:::image-end::: You can also start a debug session from Solution Explorer. First, switch to **CMake Targets View** in the **Solution Explorer** window. -![CMake targets view button](media/cmake-targets-view.png "CMake Targets View menu item") +:::image type="complex" source="media/switch-to-targets-view.png" alt-text="Screenshot of the CMake Targets View menu."::: +The solution explorer is shown. A right-click on an item in the Folder View has opened a menu that shows options such as Open, Open with, Compare with, and so on. The Switch to Targets View menu item is highlighted. +:::image-end::: Then, right-click on an executable and select **Debug**. This command automatically starts debugging the selected target based on your active configuration. +:::image type="complex" source="media/debug-targets-view.png" alt-text="Screenshot of the CMake Targets View debug option menu."::: +A right-click on a target in the CMake Targets view has opened a menu with options such as Set as Startup item, Build, Clean All, and so on. The Debug menu option is highlighted. +:::image-end::: + +Starting in Visual Studio 2022 Version 17.6, you can also start a debugging session on your CMakeLists.txt file. To do so, just set a breakpoint in your CMakeLists.txt file and run **Configure Project with CMake Debugger** from the **Project** dropdown. + +:::image type="complex" source="media/cmake-debugger-entry.png" alt-text="Screenshot of the CMake Debugger dropdown."::: +The Project dropdown is shown. The menu option to Configure Project with CMake debugger is highlighted. +:::image-end::: + ## Customize debugger settings You can customize the debugger settings for any executable CMake target in your project. They're found in a configuration file called *launch.vs.json*, located in a *`.vs`* folder in your project root. A launch configuration file is useful in most debugging scenarios, because you can configure and save your debugging setup details. There are three entry points to this file: - **Debug Menu:** Select **Debug > Debug and Launch Settings for ${activeDebugTarget}** from the main menu to customize the debug configuration specific to your active debug target. If you don't have a debug target selected, this option is grayed out. -![Debug menu entry point](media/cmake-debug-menu.png "Debug menu entry point") +![Screenshot of the Debug menu command Debug and launch settings for the project.](media/cmake-debug-menu.png "Debug menu entry point") - **Targets View:** Navigate to **Targets View** in Solution Explorer. Then, right-click on a debug target and select **Add Debug Configuration** to customize the debug configuration specific to the selected target. -![Targets view entry point](media/cmake-targets-add-debug-configuration.png "Targets view entry point") +![Screenshot of the Add Debug Configuration command on the shortcut menu for the target.](media/cmake-targets-add-debug-configuration.png "Targets view entry point") - **Root CMakeLists.txt:** Right-click on a root *CMakeLists.txt* and select **Add Debug Configuration** to open the **Select a Debugger** dialog box. The dialog allows you to add *any* type of debug configuration, but you must manually specify the CMake target to invoke via the `projectTarget` property. -![Select a debugger dialog box](media/cmake-select-a-debugger.png "Select a debugger dialog box") +![Screenshot of the Select a debugger dialog box.](media/cmake-select-a-debugger.png "Select a debugger dialog box") You can edit the *launch.vs.json* file to create debug configurations for any number of CMake targets. When you save the file, Visual Studio creates an entry for each new configuration in the **Startup Item** dropdown. @@ -111,7 +125,8 @@ In Visual Studio 2019 version 16.6, we added a new debug configuration of `type: - `remoteMachineName`: Defaults to `"${debugInfo.remoteMachineName}"`. Name of the remote system that hosts the program to debug. Only required if different than the build system. Must have an existing entry in the [Connection Manager](../linux/connect-to-your-remote-linux-computer.md). Press **Ctrl+Space** to view a list of all existing remote connections. - `cwd`: Defaults to `"${debugInfo.defaultWorkingDirectory}"`. Full Unix path to the directory on the remote system where `program` is run. The directory must exist. -- `gdbPath`: Defaults to `${debugInfo.vsInstalledGdb}`. Full Windows path to the `gdb` used to debug. Defaults to the `gdb` installed with the Linux development with C/C++ workload. +- `gdbPath`: Full Windows path to the `gdb` used to debug. + - `gdbserverPath`: Defaults to `usr/bin/gdbserver`. Full Unix path to the `gdbserver` used to debug. - `preDebugCommand`: A Linux command to run immediately before starting `gdbserver`. `gdbserver` doesn't start until the command completes. diff --git a/docs/build/configuring-programs-for-arm-processors-visual-cpp.md b/docs/build/configuring-programs-for-arm-processors-visual-cpp.md index 94614dd10f..fc99baa1b2 100644 --- a/docs/build/configuring-programs-for-arm-processors-visual-cpp.md +++ b/docs/build/configuring-programs-for-arm-processors-visual-cpp.md @@ -2,7 +2,6 @@ description: "Learn more about: Configure C++ projects for ARM processors" title: "Configure C++ projects for ARM processors" ms.date: "07/11/2018" -ms.assetid: 3d95f221-656a-480d-9651-9ad263895747 --- # Configure C++ projects for ARM processors @@ -17,7 +16,7 @@ Describes the application binary interface used by Windows on ARM for register u Describes the application binary interface used by Windows on ARM64 for register usage, calling conventions and exception handling. [Common MSVC ARM migration issues](common-visual-cpp-arm-migration-issues.md)\ -Describes C++ code elements that are commonly assumed to be portable across architectures, but which produce different results for ARM than for x86 and x64. +Describes C++ code elements that are commonly assumed to be portable across architectures, but that produce different results for ARM than for x86 and x64. [ARM exception handling](arm-exception-handling.md)\ Describes the encoding scheme for stack unwinding during structured exception handling in Windows on ARM. @@ -27,8 +26,14 @@ Describes the encoding scheme for stack unwinding during structured exception ha ## Related Sections +[Get started with Arm64EC](/windows/arm/arm64ec-build)\ +Describes how to get started building your app or project using [Arm64EC](/windows/arm/arm64ec). + +[How to: Configure projects to target platforms](/visualstudio/ide/how-to-configure-projects-to-target-platforms)\ +Describes how to set up your build to target different processor architectures, including Arm64. + [ARM intrinsics](../intrinsics/arm-intrinsics.md)\ Describes compiler intrinsics for processors that use the ARM architecture. -[ARM64 intrinsics](../intrinsics/arm-intrinsics.md)\ +[ARM64 intrinsics](../intrinsics/arm64-intrinsics.md)\ Describes compiler intrinsics for processors that use the ARM64 architecture. diff --git a/docs/build/configuring-programs-for-windows-xp.md b/docs/build/configuring-programs-for-windows-xp.md index 0793c6fca8..3e96c4f48e 100644 --- a/docs/build/configuring-programs-for-windows-xp.md +++ b/docs/build/configuring-programs-for-windows-xp.md @@ -1,16 +1,16 @@ --- title: "Configuring Programs for Windows XP" description: "How to install and use the C++ Windows XP toolsets in Visual Studio." -ms.date: "03/16/2020" +ms.date: 09/17/2021 ms.assetid: 1e4487b3-d815-4123-878b-5718b22f0fd5 --- # Configuring Programs for Windows XP Visual Studio supports multiple platform toolsets. That means it's possible to target operating systems and runtime libraries that aren't supported by the default toolset. For example, by switching the platform toolset, you can use the Visual Studio 2017 C++ compiler to create apps that target Windows XP and Windows Server 2003. You can also use older platform toolsets to maintain binary-compatible legacy code and still take advantage of the latest features of the Visual Studio IDE. -::: moniker range="msvc-160" +::: moniker range=">=msvc-160" -The v142 toolset supplied in Visual Studio 2019 doesn't include support for creating code for Windows XP. Support for Windows XP development by using the Visual Studio 2017 v141_xp toolset is available as an individual component option in the Visual Studio Installer. +The toolset supplied in Visual Studio 2019 and later doesn't include support for creating code for Windows XP. Support for Windows XP development is available by using the Visual Studio 2017 v141_xp toolset. You can install the v141_xp toolset as an individual component option in the Visual Studio Installer. ::: moniker-end @@ -22,7 +22,7 @@ To get the Visual Studio 2017 platform toolset and components to target Windows ::: moniker-end -::: moniker range="msvc-160" +::: moniker range=">=msvc-160" To get the v141_xp platform toolset and components to target Windows XP and Windows Server 2003, run the Visual Studio Installer. When you initially install Visual Studio, or when you modify an existing installation, make sure the **Desktop development with C++** workload is selected. In the **Individual components** tab, under **Compilers, build tools, and runtimes**, choose **C++ Windows XP Support for VS 2017 (v141) tools \[Deprecated]**, and then choose **Install** or **Modify**. @@ -36,11 +36,23 @@ The Windows XP platform toolset that's included in Visual Studio is a version of 1. In **Solution Explorer**, open the shortcut menu for your project, and then choose **Properties**. -1. In the **Property Pages** dialog box for the project, select **Configuration Properties** > **General**. Set the **Platform Toolset** property to your preferred Windows XP toolset. For example, choose **Visual Studio 2017 - Windows XP (v141_xp)** to create code for Windows XP and Windows Server 2003 by using the Microsoft C++ compiler in Visual Studio 2017. +1. In the **Property Pages** dialog box for the project, set the **Configuration** dropdown to **All configurations**. + +1. Select the **Configuration Properties** > **General** property page. Set the **Platform Toolset** property to your preferred Windows XP toolset. For example, choose **Visual Studio 2017 - Windows XP (v141_xp)** to create code for Windows XP and Windows Server 2003 by using the Microsoft C++ compiler from Visual Studio 2017. ### C++ runtime support -Along with the Windows XP platform toolset, several libraries include runtime support for Windows XP and Windows Server 2003. These libraries are: the C Runtime Library (CRT), C++ Standard Library, Active Template Library (ATL), Concurrency Runtime Library (ConCRT), Parallel Patterns Library (PPL), Microsoft Foundation Class Library (MFC), and C++ AMP (C++ Accelerated Massive Programming) library. For these operating systems, the minimum supported versions are: Windows XP Service Pack 3 (SP3) for x86, Windows XP Service Pack 2 (SP2) for x64, and Windows Server 2003 Service Pack 2 (SP2) for both x86 and x64. +Along with the Windows XP platform toolset, several libraries include runtime support for Windows XP and Windows Server 2003: + +- Universal C Runtime Library (UCRT) +- C++ Standard Library +- Active Template Library (ATL) +- Concurrency Runtime Library (ConcRT) +- Parallel Patterns Library (PPL) +- Microsoft Foundation Class Library (MFC) +- C++ AMP (C++ Accelerated Massive Programming) library. + +The minimum supported versions of these operating systems are: Windows XP Service Pack 3 (SP3) for x86, Windows XP Service Pack 2 (SP2) for x64, and Windows Server 2003 Service Pack 2 (SP2) for both x86 and x64. These libraries are supported by the platform toolsets installed by Visual Studio, depending on the target: @@ -49,7 +61,7 @@ These libraries are supported by the platform toolsets installed by Visual Studi |CRT|X|X|X| |C++ Standard Library|X|X|X| |ATL|X|X|X| -|ConCRT/PPL|X|X|X| +|ConcRT/PPL|X|X|X| |MFC|X||X| |C++ AMP|X|X|| @@ -58,24 +70,33 @@ These libraries are supported by the platform toolsets installed by Visual Studi ### Differences between the toolsets -Because of differences in platform and library support, the development experience for apps that use a Windows XP platform toolset isn't as complete as for apps that use the default Visual Studio platform toolset. +Because of differences in platform and library support, the development experience for apps that use a Windows XP platform toolset isn't as complete as for apps that use the default platform toolset. - **C++ language features** - Only C++ language features implemented in Visual Studio 2012 are supported in apps that use the v110\_xp platform toolset. Only C++ language features implemented in Visual Studio 2013 are supported in apps that use the v120\_xp platform toolset. Only C++ language features implemented in Visual Studio 2015 are supported in apps that use the v140\_xp platform toolset. Only C++ language features implemented in Visual Studio 2017 are supported in apps that use the v141\_xp platform toolset. Visual Studio uses the corresponding compiler when it builds using the older platform toolsets. Use the most recent Windows XP platform toolset to take advantage of additional C++ language features implemented in that version of the compiler. + Only C++ language features implemented in Visual Studio 2017 are supported in apps that use the v141\_xp platform toolset. Only C++ language features implemented in Visual Studio 2015 are supported in apps that use the v140\_xp platform toolset. Visual Studio uses the corresponding compiler when it builds using the older platform toolsets. Use the most recent Windows XP platform toolset to take advantage of the latest C++ language features implemented in that version of the compiler. For more information about language feature support by compiler version, see [Microsoft C/C++ language conformance](../overview/visual-cpp-language-conformance.md). - **Remote debugging** - Remote Tools for Visual Studio doesn't support remote debugging on Windows XP or Windows Server 2003. To debug an app locally or remotely on Windows XP or Windows Server 2003, use a debugger from an older version of Visual Studio. It's similar to debugging an app on Windows Vista, which is a runtime target of the platform toolset, but not a remote debugging target. + Remote debugging on Windows XP or Windows Server 2003 isn't supported by Remote Tools for Visual Studio. To debug an app locally or remotely on Windows XP or Windows Server 2003, use a debugger from an older version of Visual Studio. It's similar to debugging an app on Windows Vista: Vista is a *runtime* target of the platform toolset, but not a *remote debugging* target. - **Static analysis** - The Windows XP platform toolsets don't support static analysis because the SAL annotations for the Windows 7 SDK and the runtime libraries are incompatible. You can still perform static analysis on an app that supports Windows XP or Windows Server 2003. Temporarily switch the solution to target the default platform toolset for the analysis, and then switch back to the Windows XP platform toolset to build the app. + The Windows XP platform toolsets don't support static analysis. The SAL annotations for the Windows 7 SDK and the runtime libraries are incompatible. You can still run static analysis on an app that supports Windows XP or Windows Server 2003. Temporarily switch the solution to target the default platform toolset for the analysis, and then switch back to the Windows XP platform toolset to build the app. - **Debugging of DirectX graphics** - Because the Graphics Debugger doesn't support the Direct3D 9 API, it can't be used to debug apps that use Direct3D on Windows XP or Windows Server 2003. However, if the app implements an alternative renderer based on Direct3D 10 or Direct3D 11 APIs, you can use the Graphics Debugger to diagnose problems. + The Graphics Debugger doesn't support the Direct3D 9 API. It can't be used to debug apps that use Direct3D on Windows XP or Windows Server 2003. However, if the app implements an alternative renderer based on Direct3D 10 or Direct3D 11 APIs, you can use the Graphics Debugger to diagnose problems. - **Building HLSL** The Windows XP toolset doesn't compile HLSL source code files by default. To compile HLSL files, download and install the June 2010 DirectX SDK, and then set the project's VC directories to include it. For more information, see the "DirectX SDK Does Not Register Include/Library Paths with Visual Studio 2010" section of the [June 2010 DirectX SDK download page](https://web.archive.org/web/20161026183606/https://www.microsoft.com/en-us/download/details.aspx?displaylang=en&id=6812) (Archived link). + +## Windows XP deployment + +> [!IMPORTANT] +> Because it lacks support for SHA-256 code signing certificates, runtime library support for Windows XP is no longer available in the [latest Visual C++ Redistributable](../windows/latest-supported-vc-redist.md) for Visual Studio 2015, 2017, 2019, and 2022. The last Redistributable to support Windows XP shipped in Visual Studio 2019 version 16.7. Use a Redistributable that has a file version starting with **14.27**. If your Windows XP apps are deployed with or updated to a later version of the redistributable, the apps won't run. + +If you're using a version of Visual Studio later than Visual Studio 2019 version 16.7, the redistributable files won't work on Windows XP. To get a copy of the redistributable files that support Windows XP, you'll need a Visual Studio account. Use the account you use to sign in to Visual Studio. Or, you can create an account for free at [my.visualstudio.com](https://my.visualstudio.com). The redistributable file is available in the Downloads section, as [Visual C++ Redistributable for Visual Studio 2019 - Version 16.7](https://my.visualstudio.com/Downloads?q=Redistributable%20for%20Visual%20Studio%202019%20Version%2016.7). To download the files, select the platform and language you need, and then choose the Download button. + +You can use central deployment or local deployment to install runtime library support for your Windows XP app. For more information, see [Walkthrough: Deploying a Visual C++ Application By Using the Visual C++ Redistributable Package](../windows/deploying-visual-cpp-application-by-using-the-vcpp-redistributable-package.md). diff --git a/docs/build/cppproperties-schema-reference.md b/docs/build/cppproperties-schema-reference.md index 86131cae78..cafd37a1e7 100644 --- a/docs/build/cppproperties-schema-reference.md +++ b/docs/build/cppproperties-schema-reference.md @@ -1,87 +1,87 @@ --- description: "Learn more about: CppProperties.json reference" title: "CppProperties.json reference" -ms.date: "08/09/2019" +ms.date: 09/19/2022 helpviewer_keywords: ["CppProperties.json file [C++]"] --- -# CppProperties.json reference +# `CppProperties.json` reference -Open Folder projects that don't use CMake can store project configuration settings for IntelliSense in a *CppProperties.json* file. (CMake projects use a [CMakeSettings.json](customize-cmake-settings.md) file.) A configuration consists of name/value pairs and defines #include paths, compiler switches, and other parameters. See [Open Folder projects for C++](open-folder-projects-cpp.md) for more information about how to add configurations in an Open Folder project. The following sections summarize the various settings. For a complete description of the schema, navigate to *CppProperties_schema.json*, whose full path is given at the top of the code editor when *CppProperties.json* is open. +Open Folder projects that don't use CMake can store project configuration settings for IntelliSense in a *`CppProperties.json`* file. (CMake projects use a [`CMakeSettings.json`](customize-cmake-settings.md) file.) A configuration consists of name/value pairs and defines #include paths, compiler switches, and other parameters. For more information about how to add configurations in an Open Folder project, see [Open Folder projects for C++](open-folder-projects-cpp.md). The following sections summarize the various settings. For a complete description of the schema, navigate to *CppProperties_schema.json*, whose full path is given at the top of the code editor when *`CppProperties.json`* is open. ## Configuration properties A configuration may have any of the following properties: -|Name|Description| -|-|-| -|`inheritEnvironments`| Specifies which environments apply to this configuration.| -|`name`|The configuration name that will appear in the C++ configuration dropdown| -|`includePath`|A comma-separated list of folders that should be specified in the include path (maps to /I for most compilers)| -|`defines`|The list of macros that should be defined (maps to /D for most compilers)| -|`compilerSwitches`|One or more additional switches that can influence IntelliSense behavior| -|`forcedInclude`|Header to be automatically included in every compilation unit (maps to /FI for MSVC or -include for clang)| -|`undefines`|The list of macros to be undefined (maps to /U for MSVC)| -|`intelliSenseMode`|The IntelliSense engine to be used. You can specify one of the predefined architecture-specific variants for MSVC, gcc, or Clang.| -|`environments`|User-defined sets of variables that behave like environment variables in a command prompt and are accessed with the ${env.\} macro.| +| Name | Description | +|--|--| +| `inheritEnvironments` | Specifies which environments apply to this configuration. | +| `name` | The configuration name that will appear in the C++ configuration dropdown | +| `includePath` | A comma-separated list of folders that should be specified in the include path (maps to `/I` for most compilers) | +| `defines` | The list of macros that should be defined (maps to `/D` for most compilers) | +| `compilerSwitches` | One or more additional switches that can influence IntelliSense behavior | +| `forcedInclude` | Header to be automatically included in every compilation unit (maps to `/FI` for MSVC or `-include` for clang) | +| `undefines` | The list of macros to be undefined (maps to `/U` for MSVC) | +| `intelliSenseMode` | The IntelliSense engine to be used. You can specify one of the predefined architecture-specific variants for MSVC, gcc, or Clang. | +| `environments` | User-defined sets of variables that behave like environment variables in a command prompt and are accessed with the `${env.VARIABLE}` macro. | ### intelliSenseMode values The code editor shows the available options when you start to type: -![Open Folder IntelliSense](media/open-folder-intellisense-mode.png "Open Folder IntelliSense") - -These are the supported values: - -- windows-msvc-x86 -- windows-msvc-x64 -- windows-msvc-arm -- windows-msvc-arm64 -- android-clang-x86 -- android-clang-x64 -- android-clang-arm -- android-clang-arm64 -- ios-clang-x86 -- ios-clang-x64 -- ios-clang-arm -- ios-clang-arm64 -- windows-clang-x86 -- windows-clang-x64 -- windows-clang-arm -- windows-clang-arm64 -- linux-gcc-x86 -- linux-gcc-x64 -- linux-gcc-arm +![Screenshot of the IntelliSense pop-up in the editor.](media/open-folder-intellisense-mode.png "Open Folder IntelliSense") + +This list shows the supported values: + +- `windows-msvc-x86` +- `windows-msvc-x64` +- `windows-msvc-arm` +- `windows-msvc-arm64` +- `android-clang-x86` +- `android-clang-x64` +- `android-clang-arm` +- `android-clang-arm64` +- `ios-clang-x86` +- `ios-clang-x64` +- `ios-clang-arm` +- `ios-clang-arm64` +- `windows-clang-x86` +- `windows-clang-x64` +- `windows-clang-arm` +- `windows-clang-arm64` +- `linux-gcc-x86` +- `linux-gcc-x64` +- `linux-gcc-arm` Note: The values `msvc-x86` and `msvc-x64` are supported for legacy reasons only. Use the `windows-msvc-*` variants instead. ## Pre-defined Environments -Visual Studio provides the following predefined environments for Microsoft C++ which map to the corresponding Developer Command Prompt. When you inherit one of these environments, you can refer to any of the environment variables by using the global property `env` with this macro syntax: ${env.\}. +Visual Studio provides the following predefined environments for Microsoft C++ which map to the corresponding Developer Command Prompt. When you inherit one of these environments, you can refer to any of the environment variables by using the global property `env` with this macro syntax: `${env.VARIABLE}`. -|Variable Name|Description| -|-----------|-----------------| -|vsdev|The default Visual Studio environment| -|msvc_x86|Compile for x86 using x86 tools| -|msvc_x64|Compile for AMD64 using 64-bit tools| -|msvc_arm|Compile for ARM using x86 tools| -|msvc_arm64|Compile for ARM64 using x86 tools| -|msvc_x86_x64|Compile for AMD64 using x86 tools| -|msvc_arm_x64|Compile for ARM using 64-bit tools| -|msvc_arm64_x64|Compile for ARM64 using 64-bit tools| +| Variable Name | Description | +|--|--| +| `vsdev` | The default Visual Studio environment | +| `msvc_x86` | Compile for x86 using x86 tools | +| `msvc_x64` | Compile for AMD64 using 64-bit tools | +| `msvc_arm` | Compile for ARM using x86 tools | +| `msvc_arm64` | Compile for ARM64 using x86 tools | +| `msvc_x86_x64` | Compile for AMD64 using x86 tools | +| `msvc_arm_x64` | Compile for ARM using 64-bit tools | +| `msvc_arm64_x64` | Compile for ARM64 using 64-bit tools | When the Linux workload is installed, the following environments are available for remotely targeting Linux and WSL: -|Variable Name|Description| -|-----------|-----------------| -|linux_x86|Target x86 Linux remotely| -|linux_x64|Target x64 Linux remotely| -|linux_arm|Target ARM Linux remotely| +| Variable Name | Description | +|--|--| +| `linux_x86` | Target x86 Linux remotely | +| `linux_x64` | Target x64 Linux remotely | +| `linux_arm` | Target ARM Linux remotely | ## User-defined environments -You can optionally use the `environments` property to define sets of variables in *CppProperties.json* either globally or per-configuration. These variables behave like environment variables in the context of an Open Folder project and can be accessed with the ${env.\} syntax from *tasks.vs.json* and *launch.vs.json* after they are defined here. However, they are not necessarily set as actual environment variables in any command prompt that Visual Studio uses internally. +You can optionally use the `environments` property to define sets of variables in *`CppProperties.json`* either globally or per-configuration. These variables behave like environment variables in the context of an Open Folder project. You can access them with the `${env.VARIABLE}` syntax from *`tasks.vs.json`* and *`launch.vs.json`* after they're defined here. However, they aren't necessarily set as actual environment variables in any command prompt that Visual Studio uses internally. -**Visual Studio 2019 version 16.4 and later:** Configuration-specific variables defined in *CppProperties.json* are automatically picked up by debug targets and tasks without the need to set `inheritEnvironments`. Debug targets are launched automatically with the environment you specify in *CppProperties.json*. +**Visual Studio 2019 version 16.4 and later:** Configuration-specific variables defined in *`CppProperties.json`* are automatically picked up by debug targets and tasks without the need to set `inheritEnvironments`. Debug targets are launched automatically with the environment you specify in *`CppProperties.json`*. **Visual Studio 2019 version 16.3 and earlier:** When you consume an environment, then you have to specify it in the `inheritsEnvironments` property even if the environment is defined as part of the same configuration; the `environment` property specifies the name of the environment. The following example shows a sample configuration for enabling IntelliSense for GCC in an MSYS2 installation. Note how the configuration both defines and inherits the `mingw_64` environment, and how the `includePath` property can access the `INCLUDE` variable. @@ -113,21 +113,21 @@ You can optionally use the `environments` property to define sets of variables i ] ``` -When you define an **environments** property inside a configuration, it overrides any global variables of the same name. +When you define an `"environments"` property inside a configuration, it overrides any global variables that have the same names. ## Built-in macros -You have access to the following built-in macros inside *CppProperties.json*: +You have access to the following built-in macros inside *`CppProperties.json`*: -|Macro|Description| -|-|-| -|`${workspaceRoot}`| The full path to the workspace folder| -|`${projectRoot}`| The full path to the folder where *CppProperties.json* is placed| -|`${env.vsInstallDir}`| The full path to the folder where the running instance of Visual Studio is installed| +| Macro | Description | +|--|--| +| `${workspaceRoot}` | The full path to the workspace folder | +| `${projectRoot}` | The full path to the folder where *`CppProperties.json`* is placed | +| `${env.vsInstallDir}` | The full path to the folder where the running instance of Visual Studio is installed | ### Example -If your project has an include folder and also includes *windows.h* and other common headers from the Windows SDK, you may want to update your *CppProperties.json* configuration file with the following includes: +If your project has an include folder and also includes `*windows.h`* and other common headers from the Windows SDK, you may want to update your *`CppProperties.json`* configuration file with the following includes: ```json { @@ -136,28 +136,28 @@ If your project has an include folder and also includes *windows.h* and other co "name": "Windows", "includePath": [ // local include folder - "${workspaceRoot}\include", + "${workspaceRoot}\\include", // Windows SDK and CRT headers - "${env.WindowsSdkDir}\include\${env.WindowsSDKVersion}\ucrt", - "${env.NETFXSDKDir}\include\um", - "${env.WindowsSdkDir}\include\${env.WindowsSDKVersion}\um", - "${env.WindowsSdkDir}\include\${env.WindowsSDKVersion}\shared", - "${env.VCToolsInstallDir}\include" + "${env.WindowsSdkDir}\\include\\${env.WindowsSDKVersion}\\ucrt", + "${env.NETFXSDKDir}\\include\\um", + "${env.WindowsSdkDir}\\include\\${env.WindowsSDKVersion}\\um", + "${env.WindowsSdkDir}\\include\\${env.WindowsSDKVersion}\\shared", + "${env.VCToolsInstallDir}\\include" ] } ] } ``` -> [!Note] -> `%WindowsSdkDir%` and `%VCToolsInstallDir%` are not set as global environment variables so make sure you start devenv.exe from a Developer Command Prompt that defines these variables. (Type "developer" in the Windows Start Menu.) +> [!NOTE] +> `%WindowsSdkDir%` and `%VCToolsInstallDir%` are not set as global environment variables. Make sure you start *`devenv.exe`* from a Developer Command Prompt that defines these variables. (Type "developer" in the Windows Start Menu to find a Developer Command Prompt shortcut.) ## Troubleshoot IntelliSense errors -If you are not seeing the IntelliSense that you expect, you can troubleshoot by going to **Tools** > **Options** > **Text Editor** > **C/C++** > **Advanced** and setting **Enable Logging** to **`true`**. To start with, try setting **Logging Level** to 5, and **Logging Filters** to 8. +If you aren't seeing the IntelliSense that you expect, you can troubleshoot by going to **Tools** > **Options** > **Text Editor** > **C/C++** > **Advanced** and setting **Enable Logging** to **`true`**. To start with, try setting **Logging Level** to 5, and **Logging Filters** to 8. -![Diagnostic logging](media/diagnostic-logging.png) +![Screenshot of the Diagnostic logging settings in the Options dialog.](media/diagnostic-logging.png) -Output is piped to the **Output Window** and is visible when you choose **Show Output From: Visual C++ Log**. The output contains, among other things, the list of actual include paths that IntelliSense is trying to use. If the paths do not match the ones in *CppProperties.json*, try closing the folder and deleting the *.vs* sub-folder which contains cached browsing data. +Output is piped to the **Output Window** and is visible when you choose **Show Output From: Visual C++ Log**. The output contains, among other things, the list of actual include paths that IntelliSense is trying to use. If the paths don't match the ones in *`CppProperties.json`*, try closing the folder and deleting the *`.vs`* subfolder that contains cached browsing data. -To troubleshoot IntelliSense errors caused by missing include paths, open the **Error List** and filter its output to "IntelliSense only" and error code E1696 "cannot open source file ...". +To troubleshoot IntelliSense errors caused by missing include paths, open the **Error List** tab, and then filter its output to "IntelliSense only" and error code E1696 "cannot open source file ...". diff --git a/docs/build/create-reusable-property-configurations.md b/docs/build/create-reusable-property-configurations.md index 499d806185..d046426504 100644 --- a/docs/build/create-reusable-property-configurations.md +++ b/docs/build/create-reusable-property-configurations.md @@ -1,45 +1,45 @@ --- description: "Learn more about: Share or reuse Visual Studio project settings" title: "Share or reuse Visual Studio project settings - C++" -ms.date: "07/17/2019" +ms.date: 02/07/2022 helpviewer_keywords: ["project properties [C++], reusable"] --- # Share or reuse Visual Studio project settings -To create a custom group of settings that you can share with others or reuse in multiple projects, use **Property Manager** to create a *property sheet* (.props file) to store the settings for each kind of project that you want to be able to reuse or share with others. Using property sheets are far less error-prone than other ways of creating "global" settings. +To create a custom group of settings that you can share with others or reuse in multiple projects, use **Property Manager** to create a *property sheet* (a *`.props`* file) to store the settings for each kind of project that you want to be able to reuse or share with others. Using property sheets are far less error-prone than other ways of creating "global" settings. > [!IMPORTANT] -> **.user files and why they are problematic** +> **The problem with *`*.user`* files** > -> Past versions of Visual Studio used global property sheets that had a .user file name extension and were located in the \\AppData\Local\Microsoft\MSBuild\v4.0\ folder. We no longer recommend these files because they set properties for project configurations on a per-user, per-computer basis. Such "global" settings can interfere with builds, especially when you are targeting more than one platform on your build computer. For example, if you have both an MFC project and Windows Phone project, the .user properties would be invalid for one of them. Reusable property sheets are more flexible and more robust. +> Past versions of Visual Studio used global property sheets that had a *`.user`* file name extension and were located in the *`\\AppData\Local\Microsoft\MSBuild\v4.0\`* folder. We no longer recommend these files because they set properties for project configurations on a per-user, per-computer basis. Such "global" settings can interfere with builds, especially when you are targeting more than one platform on your build computer. For example, if you have both an MFC project and Windows Phone project, the *`.user`* properties would be invalid for one of them. Reusable property sheets are more flexible and more robust. > -> Although .user files are still installed by Visual Studio and participate in property inheritance, they are empty by default. The best practice is to delete the reference to them in **Property Manager** to ensure that your projects operate independently of any per-user, per-computer settings This is important to ensure correct behavior in a SCC (source code control) environment. +> Although *`.user`* files are still installed by Visual Studio and participate in property inheritance, they're empty by default. The best practice is to delete any reference to them in **Property Manager** to ensure that your projects operate independently of any per-user, per-computer settings. This practice is important to ensure correct behavior in a SCC (source code control) environment. To display **Property Manager**, on the menu bar, choose **View** > **Property Manager** or **View** > **Other Windows** > **Property Manager**, depending on your settings. -If you have a common, frequently used set of properties that you want to apply to multiple projects, you can use **Property Manager** to capture them in a reusable *property sheet* file, which by convention has a .props file name extension. You can apply the sheet (or sheets) to new projects so that you don't have to set its properties from scratch. +If you want to apply a common, frequently used set of properties to multiple projects, you can use **Property Manager** to capture them in a reusable *property sheet* file, which by convention has a *`.props`* file name extension. You can apply the sheet (or sheets) to new projects so you don't have to set those properties from scratch. -![Property Manager shortcut menu](media/sharingnew.png "SharingNew") +![Screenshot of the Property Manager shortcut menu.](media/sharingnew.png "SharingNew") -Under each configuration node, you see nodes for each property sheet that applies to that configuration. The system adds property sheets that set values based on options you choose in the app wizard when you create the project. Right-click any node and choose Properties to see the properties that apply to that node. All the property sheets are imported automatically into the project's "master" property sheet (ms.cpp.props) and are evaluated in the order they appear in Property Manager. You can move them to change the evaluation order. Property sheets that are evaluated later will override the values in previously-evaluated sheets. See [Project property inheritance](project-property-inheritance.md) for more information about the order of evaluation in the .vcxproj file, the .props and .targets files, environment variables and the command line. +Under each configuration node, you see nodes for each property sheet that applies to that configuration. The system adds property sheets that set common values based on options you choose in the app wizard when you create the project. Right-click any node and choose Properties to see the properties that apply to that node. All the property sheets are imported automatically into the project's primary property sheet (*`ms.cpp.props`*) and are evaluated in the order they appear in Property Manager. You can move them to change the evaluation order. Property sheets that are evaluated later override the values in previously evaluated sheets. For more information about the order of evaluation in the *`.vcxproj`* file, the *`.props`* and *`.targets`* files, environment variables, and the command line, see [Project property inheritance](project-property-inheritance.md). If you choose **Add New Project Property Sheet** and then select, for example, the MyProps.props property sheet, a property page dialog box appears. Notice that it applies to the MyProps property sheet; any changes you make are written to the sheet, not to the project file (.vcxproj). -Properties in a property sheet are overridden if the same property is set directly in the .vcxproj file. +Properties in a property sheet are overridden if the same property is set directly in the *`.vcxproj`* file. You can import a property sheet as often as required. Multiple projects in a solution can inherit settings from the same property sheet, and a project can have multiple sheets. A property sheet itself can inherit settings from another property sheet. -You can also create one property sheet for multiple configurations. To do this, create a property sheet for each configuration, open the shortcut menu for one of them, choose **Add Existing Property Sheet**, and then add the other sheets. However, if you use one common property sheet, be aware that when you set a property, it gets set for all configurations that the sheet applies to, and that the IDE doesn't show which projects or other property sheets are inheriting from a given property sheet. +You can also create a common property sheet for multiple configurations. To create a property sheet for each configuration, open the shortcut menu for one of them, choose **Add Existing Property Sheet**, and then add the other sheets. However, if you use a common property sheet, properties you set for all configurations that the sheet applies to. The IDE doesn't show which projects or other property sheets inherit from a given property sheet. -In large solutions that will have many projects, it can be useful to create a property sheet at the solution level. When you add a project to the solution, use **Property Manager** to add that property sheet to the project. If required at the project level, you can add a new property sheet to set project-specific values. +In large solutions that have many projects, it can be useful to create a common property sheet for all the projects in the solution. Create the property sheet as usual. Use **Property Manager** to add that property sheet to each project in the solution. If necessary at the project level, you can add another property sheet to set project-specific values. > [!IMPORTANT] -> A .props file by default does not participate in source control because it isn't created as a project item. You can manually add the file as a solution item if you want to include it in source control. +> A *`.props`* file by default does not participate in source control because it isn't created as a project item. You can manually add the file as a solution item if you want to include it in source control. #### To create a property sheet 1. On the menu bar, choose **View** > **Property Manager** or **View** > **Other Windows** > **Property Manager**. The **Property Manager** opens. -2. To define the scope of the property sheet, select the item to which it applies. This can be a particular configuration, or another property sheet. Open the shortcut menu for this item and then choose **Add New Project Property Sheet**. Specify a name and location. +2. To define the scope of the property sheet, select the item to which it applies. This item can be a particular configuration, or another property sheet. Open the shortcut menu for this item and then choose **Add New Project Property Sheet**. Specify a name and location. 3. In **Property Manager**, open the new property sheet and then set the properties you want to include. diff --git a/docs/build/creating-and-managing-visual-cpp-projects.md b/docs/build/creating-and-managing-visual-cpp-projects.md index e0828dba47..2441a8b327 100644 --- a/docs/build/creating-and-managing-visual-cpp-projects.md +++ b/docs/build/creating-and-managing-visual-cpp-projects.md @@ -1,80 +1,92 @@ --- -description: "Learn more about: Visual Studio projects - C++" -title: "Visual Studio Projects - C++" -ms.date: "10/25/2019" -helpviewer_keywords: ["ATL projects, creating", "Visual Studio C++ projects, creating", "projects [C++], creating", "Visual Studio C++ projects", "ATL projects"] -ms.assetid: 11003cd8-9046-4630-a189-a32bf3b88047 +title: "Create and Configure Visual Studio C++ Projects" +description: "Learn how to create a Visual Studio C++ project, and then add code and build your project." +ms.date: 03/24/2025 +ms.topic: concept-article +helpviewer_keywords: ["Visual Studio C++ projects, creating", "projects [C++], creating", "Visual Studio C++ projects"] --- -# Visual Studio projects - C++ +# Visual Studio C++ projects -A *Visual Studio project* is a project based on the MSBuild build system. MSBuild is the native build system for Visual Studio and is generally the best build system to use for Windows-specific programs. MSBuild is tightly integrated with Visual Studio, but you can also use it from the command line. For cross-platform projects, or projects that use open-source libraries, we recommend using [CMake projects in Visual Studio](cmake-projects-in-visual-studio.md) in Visual Studio 2017 and later. For information about upgrading MSBuild projects from older versions of Visual Studio, see the [Microsoft C++ Porting and Upgrading Guide](../porting/visual-cpp-porting-and-upgrading-guide.md). +A *Visual Studio project* is a collection of code files and assets such as icons, images, and so on, that are built together using the MSBuild system. MSBuild is the native build system for Visual Studio and is generally the best build system to use for Windows-specific programs. MSBuild is tightly integrated with Visual Studio, but you can also use it from the command line. -## Create a project +For information about upgrading MSBuild projects from older versions of Visual Studio, see the [Microsoft C++ porting and upgrading guide](../porting/visual-cpp-porting-and-upgrading-guide.md). -::: moniker range="msvc-160" +For cross-platform projects, or projects that use open-source libraries, we recommend using [CMake projects in Visual Studio](cmake-projects-in-visual-studio.md). -You can create C++ projects by choosing **File** > **New** > **Project**, then setting the **Language** to C++. In the results list you see a list of project templates which you can filter by setting the **Platform** or **Project Type** and by typing keywords into the search box. +## Create a Visual Studio C++ project - ![Visual Studio 2019 Project Templates](../build/media/vs2019-choose-console-app.png "Visual Studio 2019 New Project Dialog") +::: moniker range=">=msvc-160" -::: moniker-end +1. Create a C++ project by choosing **File** > **New** > **Project**. -::: moniker range="msvc-150" +1. In the **Create a new project** dialog, set the **Language** dropdown to **C++**. This filters the list of project templates to C++ projects. You can filter the templates by setting the **Platform**, **Project Type**, or by entering keywords in the search box. + + :::image type="content" source="../build/media/vs2019-choose-console-app.png" alt-text="Screenshot of the Create a new project wizard. The Console App project template is selected."::: -You can create C++ projects by choosing **File** > **New** > **Project**, then choosing Visual C++ in the left pane. In the center pane you see a list of project templates: +1. Select a project template, then choose **Next**. - ![Project Templates](../overview/media/vs2017-new-project.png "Visual Studio 2017 New Project Dialog") +1. On the **Configure your new project page**, enter project-specific settings such as the project name or location and then choose **Create** to create your project. ::: moniker-end -For more information about all the default project templates that are included in Visual Studio, see [C++ project templates in Visual Studio](reference/visual-cpp-project-types.md). You can create your own project templates. For more information, see [How to: Create project templates](/visualstudio/ide/how-to-create-project-templates). +::: moniker range="msvc-150" -After you create a project, it appears in the [Solution Explorer](/visualstudio/ide/solutions-and-projects-in-visual-studio) window: +1. Create a C++ project by choosing **File** > **New** > **Project**. + +1. Choose **Visual C++** in the left pane. In the center pane, a list of project templates appears: - ![Solution Explorer](media/mathlibrary-solution-explorer-153.png) + :::image type="content" source="../overview/media/vs2017-new-project.png" alt-text="Screenshot of the New Project dialog, showing available project templates for C++ such as Windows Console Application."::: -When you create a new project, a solution file (.sln) is also created. You can add additional projects to the solution by right-clicking on it in **Solution Explorer**. The solution file is used to coordinate build dependencies when you have multiple related projects but doesn't do much more than that. All the compiler options are set at the project level. +::: moniker-end -## Add items +For more information about the default project templates included in Visual Studio, see [C++ project templates in Visual Studio](reference/visual-cpp-project-types.md). -Add source code files, icons, or any other items to your project by right-clicking on the project in **Solution Explorer** and choosing **Add > New** or **Add > Existing**. +You can create your own project templates. For more information, see [Create project templates](/visualstudio/ide/how-to-create-project-templates). + +After you create a project, it appears in the [Solution Explorer](/visualstudio/ide/solutions-and-projects-in-visual-studio) window: + +:::image type="content" source="media/mathlibrary-solution-explorer-153.png" alt-text="Screenshot of the Solution Explorer window, showing source files, header files, and resource files."::: -## Add third party libraries +When you create a new project, a solution file (*`.sln`*) is also created. A *Visual Studio solution* is a collection of one or more projects. You can add another project to the solution by right-clicking the solution name in **Solution Explorer** > **Add** > **New project**. -To add third-party libraries, use the [vcpkg](https://vcpkg.io/) package manager. Run the Visual Studio integration step to set up the paths to that library when you reference it from any Visual Studio project. +The solution file coordinates build dependencies when you have multiple related projects. Compiler options are set at the project level. -## Set compiler options and other build properties +## Add code, icons, and other assets to a project -To configure build settings for a project, right-click on the project in **Solution Explorer** and choose **Properties**. For more information, see [Set C++ compiler and build properties in Visual Studio](working-with-project-properties.md). +Add source code files, icons, or any other items to your project by right-clicking on the project in **Solution Explorer** and choosing **Add > New** or **Add > Existing**. -## Compile and run +## Add third-party libraries to a project -To compile and run the new project, press **F5** or click the *debug dropdown* with the green arrow on the main toolbar. The *configuration dropdown* is where you choose whether to perform a *Debug* or *Release* build (or some other custom configuration). +Over 900 C++ open source libraries are available via the [vcpkg](/vcpkg/) package manager. Run the Visual Studio integration step to set up the paths to that library when you reference it from any Visual Studio project. -A new project compiles without errors. When adding your own code, you may occasionally introduce an error or trigger a warning. An error prevents the build from completing; a warning does not. All errors and warnings will appear both in the Output Window and in the Error List when you build the project. +For more information about consuming a library that you have downloaded by using the **vcpkg** package manager, see: +- [vcpkg in CMake projects](/vcpkg/users/buildsystems/cmake-integration) +- [Install and use packages with CMake in Visual Studio](/vcpkg/get_started/get-started-vs) +- [vcpkg in MSBuild projects](/vcpkg/users/buildsystems/msbuild-integration) +- [Tutorial: Install and use packages with MSBuild in Visual Studio](/vcpkg/get_started/get-started-msbuild) - ![Output window and error list](../overview/media/vs2017-output-error-list.png) +There are also commercial third-party libraries that you can install. Follow their installation instructions. -In the Error List, you can press **F1** on a highlighted error to go to its documentation topic. +## Set compiler options and build properties -## In This Section +To configure build settings for a project, right-click on the project in **Solution Explorer** and choose **Properties**. For more information, see [Set compiler and build properties](working-with-project-properties.md). -[Set C++ compiler and build properties in Visual Studio](working-with-project-properties.md)
-How to use Property Pages and Property Sheets to specify your project settings. +## Compile and run a project -[Reference libraries and components at build time](adding-references-in-visual-cpp-projects.md)
-How to include libs, DLLs, COM and .NET components in a project. +To compile and run the new project, press **F5** or select the *debug dropdown* with the green arrow on the main toolbar. The *configuration dropdown* is where you choose whether to perform a *Debug* or *Release* build (or some other custom configuration). -[Organize Project Output Files](how-to-organize-project-output-files-for-builds.md)
-How to customize the location of the executable files created in the build process. +A new project compiles without errors. When adding your own code, you might occasionally introduce an error or trigger a warning. An error prevents the build from completing; a warning doesn't. All errors and warnings appear both in the Output Window and in the Error List when you build the project. -[Custom Build Steps and Build Events](understanding-custom-build-steps-and-build-events.md)
-How to add any arbitrary command to the build process at specified points. +:::image type="content" source="../overview/media/vs2017-output-error-list.png" alt-text="Screenshot of the Output window and Error list, showing a syntax error for a misplaced colon."::: -[Create a project from existing code](how-to-create-a-cpp-project-from-existing-code.md)
-How to create a new Visual Studio project from a loose collection of source files. +In the **Error List**, you can press **F1** on the highlighted error to go to its documentation topic. -## See also +## Related content -[Projects and build systems](projects-and-build-systems-cpp.md)
-[Microsoft C++ Porting and Upgrading Guide](../porting/visual-cpp-porting-and-upgrading-guide.md) +- [Create a project from existing code](how-to-create-a-cpp-project-from-existing-code.md) +- [Set C++ compiler and build properties in Visual Studio](working-with-project-properties.md) +- [Custom build steps and build events](understanding-custom-build-steps-and-build-events.md) +- [Reference libraries and components at build time](adding-references-in-visual-cpp-projects.md) +- [Organize project output files](how-to-organize-project-output-files-for-builds.md) +- [Projects and build systems](projects-and-build-systems-cpp.md) +- [Microsoft C++ porting and upgrade guide](../porting/visual-cpp-porting-and-upgrading-guide.md) diff --git a/docs/build/creating-precompiled-header-files.md b/docs/build/creating-precompiled-header-files.md index 0a4f7032a2..2b0f1f5ebe 100644 --- a/docs/build/creating-precompiled-header-files.md +++ b/docs/build/creating-precompiled-header-files.md @@ -1,86 +1,85 @@ --- -description: "Learn more about: Precompiled Header Files" title: "Precompiled Header Files" -ms.date: "10/24/2019" +description: "Learn more about: Precompiled header files" +ms.date: 06/29/2022 helpviewer_keywords: ["precompiled header files, creating", "PCH files, creating", "cl.exe compiler, precompiling code", ".pch files, creating"] -ms.assetid: e2cdb404-a517-4189-9771-c869c660cb1b --- -# Precompiled Header Files +# Precompiled header files -When you create a new project in Visual Studio, a *precompiled header file* named *pch.h* is added to the project. (In Visual Studio 2017 and earlier, the file was called *stdafx.h*.) The purpose of the file is to speed up the build process. Any stable header files, for example Standard Library headers such as ``, should be included here. The precompiled header is compiled only when it, or any files it includes, are modified. If you only make changes in your project source code, the build will skip compilation for the precompiled header. +When you create a new project in Visual Studio, a *precompiled header file* named *`pch.h`* is added to the project. (In Visual Studio 2017 and earlier, the file was called *`stdafx.h`*.) The purpose of the file is to speed up the build process. Any stable header files, for example Standard Library headers such as ``, should be included here. The precompiled header is compiled only when it, or any files it includes, are modified. If you only make changes in your project source code, the build will skip compilation for the precompiled header. -The compiler options for precompiled headers are [/Y](reference/y-precompiled-headers.md). In the project property pages, the options are located under **Configuration Properties > C/C++ > Precompiled Headers**. You can choose to not use precompiled headers, and you can specify the header file name and the name and path of the output file. +The compiler options for precompiled headers are [`/Y`](reference/y-precompiled-headers.md). In the project property pages, the options are located under **Configuration Properties** > **C/C++** > **Precompiled Headers**. You can choose to not use precompiled headers, and you can specify the header file name and the name and path of the output file. ## Custom precompiled code -For large projects that take significant time to build, you may want to consider creating custom precompiled files. The Microsoft C and C++ compilers provide options for precompiling any C or C++ code, including inline code. Using this performance feature, you can compile a stable body of code, store the compiled state of the code in a file, and, during subsequent compilations, combine the precompiled code with code that is still under development. Each subsequent compilation is faster because the stable code does not need to be recompiled. +For large projects that take significant time to build, you may want to consider creating custom precompiled files. The Microsoft C and C++ compilers provide options for precompiling any C or C++ code, including inline code. Using this performance feature, you can compile a stable body of code, store the compiled state of the code in a file, and, during subsequent compilations, combine the precompiled code with code that's still under development. Each later compilation is faster because the stable code doesn't need to be recompiled. -## When to Precompile Source Code +## When to precompile source code Precompiled code is useful during the development cycle to reduce compilation time, especially if: - You always use a large body of code that changes infrequently. -- Your program comprises multiple modules, all of which use a standard set of include files and the same compilation options. In this case, all include files can be precompiled into one precompiled header. +- Your program comprises multiple modules, all of which use a standard set of include files and the same compilation options. In this case, all include files can be precompiled into one precompiled header. For more information about newer ways to handle include files, see [Compare header units, modules, and precompiled headers](compare-inclusion-methods.md). -The first compilation — the one that creates the precompiled header (PCH) file — takes a bit longer than subsequent compilations. Subsequent compilations can proceed more quickly by including the precompiled code. +The first compilation (the one that creates the precompiled header file) takes a bit longer than subsequent compilations. Subsequent compilations can proceed more quickly by including the precompiled code. -You can precompile both C and C++ programs. In C++ programming, it is common practice to separate class interface information into header files. These header files can later be included in programs that use the class. By precompiling these headers, you can reduce the time a program takes to compile. +You can precompile both C and C++ programs. In C++ programming, it's common practice to separate class interface information into header files. These header files can later be included in programs that use the class. By precompiling these headers, you can reduce the time a program takes to compile. > [!NOTE] -> Although you can use only one precompiled header (.pch) file per source file, you can use multiple .pch files in a project. +> Although you can use only one precompiled header (*`.pch`*) file per source file, you can use multiple *`.pch`* files in a project. -## Two Choices for Precompiling Code +## Two choices for precompiling code -You can precompile any C or C++ code; you are not limited to precompiling only header files. +You can precompile any C or C++ code; you're not limited to precompiling only header files. -Precompiling requires planning, but it offers significantly faster compilations if you precompile source code other than simple header files. +Precompiling requires planning, but it offers much faster compilations if you precompile source code other than simple header files. -Precompile code when you know that your source files use common sets of header files but don't include them in the same order, or when you want to include source code in your precompilation. +Precompile code when you know that your source files use common sets of header files, or when you want to include source code in your precompilation. -The precompiled-header options are [/Yc (Create Precompiled Header File)](reference/yc-create-precompiled-header-file.md) and [/Yu (Use Precompiled Header File)](reference/yu-use-precompiled-header-file.md). Use **/Yc** to create a precompiled header. When used with the optional [hdrstop](../preprocessor/hdrstop.md) pragma, **/Yc** lets you precompile both header files and source code. Select **/Yu** to use an existing precompiled header in the existing compilation. You can also use **/Fp** with the **/Yc** and **/Yu** options to provide an alternative name for the precompiled header. +The precompiled-header options are [`/Yc` (Create Precompiled Header File)](reference/yc-create-precompiled-header-file.md) and [`/Yu` (Use Precompiled Header File)](reference/yu-use-precompiled-header-file.md). Use **`/Yc`** to create a precompiled header. When used with the optional [`hdrstop`](../preprocessor/hdrstop.md) pragma, **`/Yc`** lets you precompile both header files and source code. Select **`/Yu`** to use an existing precompiled header in the existing compilation. You can also use **`/Fp`** with the **`/Yc`** and **`/Yu`** options to provide an alternative name for the precompiled header. -The compiler option reference topics for **/Yu** and **/Yc** discuss how to access this functionality in the development environment. +The compiler option reference articles for **`/Yu`** and **`/Yc`** discuss how to access this functionality in the development environment. -## Precompiled Header Consistency Rules +## Precompiled header consistency rules -Because PCH files contain information about the machine environment as well as memory address information about the program, you should only use a PCH file on the machine where it was created. +Because PCH files contain information about the machine environment and memory address information about the program, you should only use a PCH file on the machine where it was created. -## Consistency Rules for Per-File Use of Precompiled Headers +## Consistency rules for per-file use of precompiled headers -The [/Yu](reference/yu-use-precompiled-header-file.md) compiler option lets you specify which PCH file to use. +The [`/Yu`](reference/yu-use-precompiled-header-file.md) compiler option lets you specify which PCH file to use. -When you use a PCH file, the compiler assumes the same compilation environment — one that uses consistent compiler options, pragmas, and so on — that was in effect when you created the PCH file, unless you specify otherwise. If the compiler detects an inconsistency, it issues a warning and identifies the inconsistency where possible. Such warnings do not necessarily indicate a problem with the PCH file; they simply warn you of possible conflicts. Consistency requirements for PCH files are described in the following sections. +When you use a PCH file, the compiler assumes the same compilation environment that was in effect when you created the PCH file, unless you specify otherwise. The compilation environment includes the compiler options, pragmas, and so on. If the compiler detects an inconsistency, it issues a warning and identifies the inconsistency where possible. Such warnings don't necessarily indicate a problem with the PCH file; they simply warn you of possible conflicts. Consistency requirements for PCH files are described in the following sections. -### Compiler Option Consistency +### Compiler option consistency The following compiler options can trigger an inconsistency warning when using a PCH file: -- Macros created using the Preprocessor (/D) option must be the same between the compilation that created the PCH file and the current compilation. The state of defined constants is not checked, but unpredictable results can occur if these change. +- Macros created using the Preprocessor (**`/D`**) option must be the same between the compilation that created the PCH file and the current compilation. The state of defined constants isn't checked, but unpredictable results can occur if these macros change. -- PCH files do not work with the /E and /EP options. +- PCH files don't work with the **`/E`** and **`/EP`** options. -- PCH files must be created using either the Generate Browse Info (/FR) option or the Exclude Local Variables (/Fr) option before subsequent compilations that use the PCH file can use these options. +- PCH files must be created using either the Generate Browse Info (**`/FR`**) option or the Exclude Local Variables (**`/Fr`**) option before subsequent compilations that use the PCH file can use these options. -### C 7.0-Compatible (/Z7) +### C 7.0-compatible (`/Z7`) -If this option is in effect when the PCH file is created, subsequent compilations that use the PCH file can use the debugging information. +If this option is in effect when the PCH file is created, later compilations that use the PCH file can use the debugging information. -If the C 7.0-Compatible (/Z7) option is not in effect when the PCH file is created, subsequent compilations that use the PCH file and /Z7 trigger a warning. The debugging information is placed in the current .obj file, and local symbols defined in the PCH file are not available to the debugger. +If the C 7.0-Compatible (**`/Z7`**) option isn't in effect when the PCH file is created, later compilations that use the PCH file and **`/Z7`** trigger a warning. The debugging information is placed in the current *`.obj`* file, and local symbols defined in the PCH file aren't available to the debugger. -### Include Path Consistency +### Include path consistency -A PCH file does not contain information about the include path that was in effect when it was created. When you use a PCH file, the compiler always uses the include path specified in the current compilation. +A PCH file doesn't contain information about the header include path that was in effect when it was created. When you use a PCH file, the compiler always uses the header include path specified in the current compilation. -### Source File Consistency +### Source file consistency -When you specify the Use Precompiled Header File (/Yu) option, the compiler ignores all preprocessor directives (including pragmas) that appear in the source code that will be precompiled. The compilation specified by such preprocessor directives must be the same as the compilation used for the Create Precompiled Header File (/Yc) option. +When you specify the Use Precompiled Header File (**`/Yu`**) option, the compiler ignores all preprocessor directives (including pragmas) that appear in the source code that will be precompiled. The compilation specified by such preprocessor directives must be the same as the compilation used for the Create Precompiled Header File (**`/Yc`**) option. -### Pragma Consistency +### Pragma consistency -Pragmas processed during the creation of a PCH file usually affect the file with which the PCH file is subsequently used. The `comment` and `message` pragmas do not affect the remainder of the compilation. +Pragmas processed during the creation of a PCH file usually affect the file with which the PCH file is later used. The `comment` and `message` pragmas don't affect the remainder of the compilation. -These pragmas affect only the code within the PCH file; they do not affect code that subsequently uses the PCH file: +These pragmas affect only the code within the PCH file; they don't affect code that later uses the PCH file: :::row::: :::column span=""::: @@ -131,57 +130,60 @@ These pragmas are retained as part of a precompiled header, and affect the remai :::column-end::: :::row-end::: -## Consistency Rules for /Yc and /Yu +## Consistency rules for /Yc and /Yu -When you use a precompiled header created using /Yc or /Yu, the compiler compares the current compilation environment to the one that existed when you created the PCH file. Be sure to specify an environment consistent with the previous one (using consistent compiler options, pragmas, and so on) for the current compilation. If the compiler detects an inconsistency, it issues a warning and identifies the inconsistency where possible. Such warnings don't necessarily indicate a problem with the PCH file; they simply warn you of possible conflicts. The following sections explain the consistency requirements for precompiled headers. +When you use a precompiled header created using **`/Yc`** or **`/Yu`**, the compiler compares the current compilation environment to the one that existed when you created the PCH file. Be sure to specify an environment consistent with the previous one (using consistent compiler options, pragmas, and so on) for the current compilation. If the compiler detects an inconsistency, it issues a warning and identifies the inconsistency where possible. Such warnings don't necessarily indicate a problem with the PCH file; they simply warn you of possible conflicts. The following sections explain the consistency requirements for precompiled headers. -### Compiler Option Consistency +### Compiler option consistency This table lists compiler options that might trigger an inconsistency warning when using a precompiled header: -|Option|Name|Rule| -|------------|----------|----------| -|/D|Define constants and macros|Must be the same between the compilation that created the precompiled header and the current compilation. The state of defined constants is not checked, but unpredictable results can occur if your files depend on the values of the changed constants.| -|/E or /EP|Copy preprocessor output to standard output|Precompiled headers do not work with the /E or /EP option.| -|/Fr or /FR|Generate Microsoft Source Browser information|For the /Fr and /FR options to be valid with the /Yu option, they must also have been in effect when the precompiled header was created. Subsequent compilations that use the precompiled header also generate Source Browser information. Browser information is placed in a single .sbr file and is referenced by other files in the same manner as CodeView information. You cannot override the placement of Source Browser information.| -|/GA, /GD, /GE, /Gw, or /GW|Windows protocol options|Must be the same between the compilation that created the precompiled header and the current compilation. If these options differ, a warning message results.| -|/Zi|Generate complete debugging information|If this option is in effect when the precompiled header is created, subsequent compilations that use the precompilation can use that debugging information. If /Zi is not in effect when the precompiled header is created, subsequent compilations that use the precompilation and the /Zi option trigger a warning. The debugging information is placed in the current object file, and local symbols defined in the precompiled header are not available to the debugger.| +| Option | Name | Rule | +|--|--|--| +| **`/D`**| Define constants and macros | Must be the same between the compilation that created the precompiled header and the current compilation. The state of defined constants isn't checked. However, unpredictable results can occur if your files depend on the values of the changed constants. | +| **`/E`** or **`/EP`** | Copy preprocessor output to standard output | Precompiled headers don't work with the **`/E`** or **`/EP`** option. | +| **`/Fr`** or **`/FR`** | Generate Microsoft Source Browser information | For the **`/Fr`** and **`/FR`** options to be valid with the **`/Yu`** option, they must also have been in effect when the precompiled header was created. Subsequent compilations that use the precompiled header also generate Source Browser information. Browser information is placed in a single *`.sbr`* file and is referenced by other files in the same manner as CodeView information. You can't override the placement of Source Browser information. | +| **`/GA`**, **`/GD`**, **`/GE`**, **`/Gw`**, or **`/GW`** | Windows protocol options | Must be the same between the compilation that created the precompiled header and the current compilation. The compiler emits a warning if these options differ. | +| **`/Zi`** | Generate complete debugging information | If this option is in effect when the precompiled header is created, subsequent compilations that use the precompilation can use that debugging information. If **`/Zi`** isn't in effect when the precompiled header is created, subsequent compilations that use the precompilation and the **`/Zi`** option trigger a warning. The debugging information is placed in the current object file, and local symbols defined in the precompiled header aren't available to the debugger. | > [!NOTE] > The precompiled header facility is intended for use only in C and C++ source files. -## Using Precompiled Headers in a Project +## Using precompiled headers in a project Previous sections present an overview of precompiled headers: /Yc and /Yu, the /Fp option, and the [hdrstop](../preprocessor/hdrstop.md) pragma. This section describes a method for using the manual precompiled-header options in a project; it ends with an example makefile and the code that it manages. -For another approach to using the manual precompiled-header options in a project, study one of the makefiles located in the MFC\SRC directory that is created during the default setup of Visual Studio. These makefiles take a similar approach to the one presented in this section but make greater use of Microsoft Program Maintenance Utility (NMAKE) macros, and offer greater control of the build process. +For another approach to using the manual precompiled-header options in a project, study one of the makefiles located in the *`MFC\SRC`* directory that's created during the default setup of Visual Studio. These makefiles take a similar approach to the one presented in this section. They make greater use of Microsoft Program Maintenance Utility (NMAKE) macros, and offer greater control of the build process. -## PCH Files in the Build Process +## PCH files in the build process -The code base of a software project is usually contained in multiple C or C++ source files, object files, libraries, and header files. Typically, a makefile coordinates the combination of these elements into an executable file. The following figure shows the structure of a makefile that uses a precompiled header file. The NMAKE macro names and the file names in this diagram are consistent with those in the example code found in [Sample Makefile for PCH](#sample-makefile-for-pch) and [Example Code for PCH](#example-code-for-pch). +The code base of a software project is often contained in multiple C or C++ source files, object files, libraries, and header files. Typically, a makefile coordinates the combination of these elements into an executable file. The following figure shows the structure of a makefile that uses a precompiled header file. The NMAKE macro names and the file names in this diagram are consistent with the example code found in [Sample makefile for PCH](#sample-makefile-for-pch) and [Example code for PCH](#example-code-for-pch). The figure uses three diagrammatic devices to show the flow of the build process. Named rectangles represent each file or macro; the three macros represent one or more files. Shaded areas represent each compile or link action. Arrows show which files and macros are combined during the compilation or linking process. -![Structure of a makefile that uses a precompiled header file](media/vc30ow1.gif "Structure of a makefile that uses a precompiled header file")
-Structure of a Makefile That Uses a Precompiled Header File +Structure of a makefile that uses a precompiled header file: -Beginning at the top of the diagram, both STABLEHDRS and BOUNDRY are NMAKE macros in which you list files not likely to need recompilation. These files are compiled by the command string +:::image type="complex" source="media/vc30ow1.gif" alt-text="Diagram showing example inputs and outputs of a makefile that uses a precompiled header file."::: +The diagram shows `$(STABLEHDRS)` and `$(BOUNDRY)` feeding into CL /c /W3 /Yc$(BOUNDRY) applib.cpp myapp.cpp. The output of that is $(STABLE.PCH). Then, applib.cpp and $(UNSTABLEHDRS) and $(STABLE.PCH) feed into CL /c /w3 /Yu $(BOUNDRY) applib.cpp, which produces applib.obj. myapp.cpp, $(UNSTABLEHDR), and $(STABLE.PCH) feed into CL /c /w3 /Yu $(BOUNDRY) myapp.cpp, which produces myapp.obj. Finally, applib.obj and myapp.obj are combined by LINK /NOD ONERROR:NOEXE $(OBJS), myapp, NUL, $(LIBS), NUL to produce myapp.exe. +:::image-end::: + +Beginning at the top of the diagram, both `STABLEHDRS` and `BOUNDRY` are NMAKE macros in which you list files not likely to need recompilation. These files are compiled by the command string `CL /c /W3 /Yc$(BOUNDRY) applib.cpp myapp.cpp` -only if the precompiled header file (STABLE.pch) does not exist or if you make changes to the files listed in the two macros. In either case, the precompiled header file will contain code only from the files listed in the STABLEHDRS macro. List the last file you want precompiled in the BOUNDRY macro. +only if the precompiled header file (*`STABLE.pch`*) doesn't exist or if you make changes to the files listed in the two macros. In either case, the precompiled header file will contain code only from the files listed in the `STABLEHDRS` macro. List the last file you want precompiled in the `BOUNDRY` macro. -The files you list in these macros can be either header files or C or C++ source files. (A single PCH file cannot be used with both C and C++ modules.) Note that you can use the **hdrstop** macro to stop precompilation at some point within the BOUNDRY file. See [hdrstop](../preprocessor/hdrstop.md) for more information. +The files you list in these macros can be either header files or C or C++ source files. (A single PCH file can't be used with both C and C++ sources.) You can use the **`hdrstop`** macro to stop precompilation at some point within the `BOUNDRY` file. For more information, see [`hdrstop`](../preprocessor/hdrstop.md). -Continuing down the diagram, APPLIB.obj represents the support code used in your final application. It is created from APPLIB.cpp, the files listed in the UNSTABLEHDRS macro, and precompiled code from the precompiled header. +Next in the diagram, *`APPLIB.obj`* represents the support code used in your final application. It's created from *`APPLIB.cpp`*, the files listed in the `UNSTABLEHDRS` macro, and precompiled code from the precompiled header. -MYAPP.obj represents your final application. It is created from MYAPP.cpp, the files listed in the UNSTABLEHDRS macro, and precompiled code from the precompiled header. +*`MYAPP.obj`* represents your final application. It's created from *`MYAPP.cpp`*, the files listed in the `UNSTABLEHDRS` macro, and precompiled code from the precompiled header. -Finally, the executable file (MYAPP.EXE) is created by linking the files listed in the OBJS macro (APPLIB.obj and MYAPP.obj). +Finally, the executable file (*`MYAPP.EXE`*) is created by linking the files listed in the `OBJS` macro (*`APPLIB.obj`* and *`MYAPP.obj`*). -## Sample Makefile for PCH +## Sample makefile for PCH -The following makefile uses macros and an !IF, !ELSE, !ENDIF flow-of-control command structure to simplify its adaptation to your project. +The following makefile uses macros and an `!IF`, `!ELSE`, `!ENDIF` flow-of-control command structure to simplify its adaptation to your project. ```NMAKE # Makefile : Illustrates the effective use of precompiled @@ -227,26 +229,28 @@ stable.pch : $(STABLEHDRS) $(CPP) $(CLFLAGS) /Yc$(BOUNDRY) applib.cpp myapp.cpp ``` -Aside from the STABLEHDRS, BOUNDRY, and UNSTABLEHDRS macros shown in the figure "Structure of a Makefile That Uses a Precompiled Header File" in [PCH Files in the Build Process](#pch-files-in-the-build-process), this makefile provides a CLFLAGS macro and a LINKFLAGS macro. You must use these macros to list compiler and linker options that apply whether you build a debug or final version of the application's executable file. There is also a LIBS macro where you list the libraries your project requires. +Aside from the `STABLEHDRS`, `BOUNDRY`, and `UNSTABLEHDRS` macros shown in the figure "Structure of a Makefile That Uses a Precompiled Header File" in [PCH files in the build process](#pch-files-in-the-build-process), this makefile provides a `CLFLAGS` macro and a `LINKFLAGS` macro. You must use these macros to list compiler and linker options that apply whether you build a debug or final version of the application's executable file. There's also a `LIBS` macro where you list the libraries your project requires. -The makefile also uses !IF, !ELSE, !ENDIF to detect whether you define a DEBUG symbol on the NMAKE command line: +The makefile also uses `!IF`, `!ELSE`, `!ENDIF` to detect whether you define a `DEBUG` symbol on the NMAKE command line: ```NMAKE NMAKE DEBUG=[1|0] ``` -This feature makes it possible for you to use the same makefile during development and for the final versions of your program — use DEBUG=0 for the final versions. The following command lines are equivalent: +This feature makes it possible for you to use the same makefile during development and for the final versions of your program. Use `DEBUG=0` for the final versions. The following command lines are equivalent: ```NMAKE NMAKE NMAKE DEBUG=0 ``` -For more information on makefiles, see [NMAKE Reference](reference/nmake-reference.md). Also see [MSVC Compiler Options](reference/compiler-options.md) and the [MSVC Linker Options](reference/linker-options.md). +For more information on makefiles, see [NMAKE reference](reference/nmake-reference.md). Also see [MSVC compiler options](reference/compiler-options.md) and the [MSVC linker options](reference/linker-options.md). + +## Example code for PCH -## Example Code for PCH +The following source files are used in the makefile described in [PCH files in the build process](#pch-files-in-the-build-process) and [Sample makefile for PCH](#sample-makefile-for-pch). The comments contain important information. -The following source files are used in the makefile described in [PCH Files in the Build Process](#pch-files-in-the-build-process) and [Sample Makefile for PCH](#sample-makefile-for-pch). Note that the comments contain important information. +Source file `ANOTHER.H`: ```cpp // ANOTHER.H : Contains the interface to code that is not @@ -254,11 +258,13 @@ The following source files are used in the makefile described in [PCH Files in t // #ifndef __ANOTHER_H #define __ANOTHER_H -#include +#include void savemoretime( void ); #endif // __ANOTHER_H ``` +Source file `STABLE.H`: + ```cpp // STABLE.H : Contains the interface to code that is not likely // to change. List code that is likely to change @@ -266,11 +272,13 @@ void savemoretime( void ); // #ifndef __STABLE_H #define __STABLE_H -#include +#include void savetime( void ); #endif // __STABLE_H ``` +Source file `UNSTABLE.H`: + ```cpp // UNSTABLE.H : Contains the interface to code that is // likely to change. As the code in a header @@ -280,19 +288,21 @@ void savetime( void ); // #ifndef __UNSTABLE_H #define __UNSTABLE_H -#include +#include void notstable( void ); #endif // __UNSTABLE_H ``` +Source file `APPLIB.CPP`: + ```cpp // APPLIB.CPP : This file contains the code that implements // the interface code declared in the header // files STABLE.H, ANOTHER.H, and UNSTABLE.H. // -#include"another.h" -#include"stable.h" -#include"unstable.h" +#include "another.h" +#include "stable.h" +#include "unstable.h" using namespace std; // The following code represents code that is deemed stable and // not likely to change. The associated interface code is @@ -310,6 +320,8 @@ void notstable( void ) } ``` +Source file `MYAPP.CPP`: + ```cpp // MYAPP.CPP : Sample application // All precompiled code other than the file listed @@ -318,9 +330,9 @@ void notstable( void ) // listed in the BOUNDRY macro. Unstable code must // be included after the precompiled code. // -#include"another.h" -#include"stable.h" -#include"unstable.h" +#include "another.h" +#include "stable.h" +#include "unstable.h" int main( void ) { savetime(); @@ -331,5 +343,10 @@ int main( void ) ## See also -[C/C++ Building Reference](reference/c-cpp-building-reference.md)
-[MSVC Compiler Options](reference/compiler-options.md) +[Compare header units, modules, and precompiled headers](compare-inclusion-methods.md)\ +[C/C++ building reference](reference/c-cpp-building-reference.md)\ +[MSVC compiler options](reference/compiler-options.md)\ +[Overview of modules in C++](../cpp/modules-cpp.md)\ +[Tutorial: Import the C++ standard library using modules](../cpp/tutorial-import-stl-named-module.md)\ +[Walkthrough: Build and import header units in your Visual C++ projects](walkthrough-header-units.md)\ +[Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md#approach1) diff --git a/docs/build/customize-cmake-settings.md b/docs/build/customize-cmake-settings.md index 5b71085dbb..3ccdd13da6 100644 --- a/docs/build/customize-cmake-settings.md +++ b/docs/build/customize-cmake-settings.md @@ -1,26 +1,30 @@ --- description: "Learn more about: Customize CMake build settings" title: "Customize CMake build settings in Visual Studio" -ms.date: "08/20/2019" +ms.date: 12/15/2021 helpviewer_keywords: ["CMake build settings"] --- # Customize CMake build settings -::: moniker range="msvc-160" +::: moniker range=">=msvc-160" -In Visual Studio 2019 and later, you can add configurations and customize their settings by using the **CMake settings editor**. The editor is intended to be a simpler alternative to manually editing the *CMakeSettings.json* file, but if you prefer to edit the file directly, you can click the **Edit JSON** link in the upper right of the editor. +Visual Studio uses a CMake configuration file to drive CMake generation and build. *`CMakePresets.json`* is supported by Visual Studio 2019 version 16.10 or later and is the recommended CMake configuration file. *`CMakePresets.json`* is supported directly by CMake and can be used to drive CMake generation and build from Visual Studio, from VS Code, in a Continuous Integration pipeline, and from the command line on Windows, Linux, and Mac. For more information on *`CMakePresets.json`*, see [Configure and build with CMake Presets](cmake-presets-vs.md). -To open the editor, click on the **Configuration** drop-down in the main toolbar and choose **Manage Configurations**. +If you maintain projects that use a *`CMakeSettings.json`* file for CMake build configuration, Visual Studio 2019 and later versions provide a **CMake settings editor**. The editor lets you add CMake configurations and customize their settings easily. It's intended to be a simpler alternative to manually editing the *`CMakeSettings.json`* file. However, if you prefer to edit the file directly, you can select the **Edit JSON** link in the upper right of the editor. -![CMake configurations drop-down](media/vs2019-cmake-manage-configurations.png) +To open the CMake settings editor, select the **Configuration** drop-down in the main toolbar and choose **Manage Configurations**. + +![Screenshot of the CMake configuration drop-down. Manage Configurations is highlighted.](media/vs2019-cmake-manage-configurations.png) Now you see the **Settings Editor** with the installed configurations on the left. -![CMake settings editor](media/cmake-settings-editor.png) +:::image type="complex" source="media/cmake-settings-editor.png" alt-text="Screenshot of the CMake settings editor."::: +The left pane shows the installed configurations (x86-Debug). The right pane shows the settings for the selected configuration. The settings include the configuration name, configuration type (set to Debug), toolset (set to msvc_x86), CMake toolchain file (empty), build root (contains ${env:USERPROFILE}\CMakeBuilds\${workspaceHash}\build\${name}), CMake command arguments (empty), and build command arguments (-v). +:::image-end::: -Visual Studio provides one `x64-Debug` configuration by default. You can add additional configurations by clicking the green plus sign. The settings that you see in the editor might vary depending on which configuration is selected. +Visual Studio provides one `x64-Debug` configuration by default. You can add more configurations by choosing the green plus sign. The settings that you see in the editor might vary depending on which configuration is selected. -The options that you choose in the editor are written to a file called *CMakeSettings.json*. This file provides command-line arguments and environment variables that are passed to CMake when you build the projects. Visual Studio never modifies *CMakeLists.txt* automatically; by using *CMakeSettings.json* you can customize the build through Visual Studio while leaving the CMake project files untouched so that others on your team can consume them with whatever tools they're using. +The options that you choose in the editor are written to a file called *`CMakeSettings.json`*. This file provides command-line arguments and environment variables that are passed to CMake when you build the projects. Visual Studio never modifies *`CMakeLists.txt`* automatically; by using *`CMakeSettings.json`* you can customize the build through Visual Studio while leaving the CMake project files untouched so that others on your team can consume them with whatever tools they're using. ## CMake General Settings @@ -32,19 +36,19 @@ Corresponds to the **name** setting. This name appears in the C++ configuration ### Configuration type -Corresponds to the **configurationType** setting. Defines the build configuration type for the selected generator. Currently supported values are "Debug", "MinSizeRel", "Release", and "RelWithDebInfo". It maps to [CMAKE_BUILD_TYPE](https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html). +Corresponds to the **configurationType** setting. Defines the build configuration type for the selected generator. Currently supported values are Debug, MinSizeRel, Release, and RelWithDebInfo. It maps to [`CMAKE_BUILD_TYPE`](https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html). ### Toolset -Corresponds to the **inheritedEnvironments** setting. Defines the compiler environment that's used to build the selected configuration. Supported values depend on the type of configuration. To create a custom environment, choose the **Edit JSON** link in the upper right corner of the Settings editor, and edit the *CMakeSettings.json* file directly. +Corresponds to the **inheritedEnvironments** setting. Defines the compiler environment that's used to build the selected configuration. Supported values depend on the type of configuration. To create a custom environment, choose the **Edit JSON** link in the upper right corner of the Settings editor, and edit the *`CMakeSettings.json`* file directly. ### CMake toolchain file -Path to the [CMake toolchain file](https://cmake.org/cmake/help/latest/variable/CMAKE_TOOLCHAIN_FILE.html). This path is passed to CMake as "-DCMAKE_TOOLCHAIN_FILE = \". Toolchain files specify locations of compilers and toolchain utilities, and other target platform and compiler related information. By default, Visual Studio uses the [vcpkg toolchain file](https://github.com/microsoft/vcpkg/blob/master/docs/examples/installing-and-using-packages.md#cmake) if this setting is unspecified. +Path to the [CMake toolchain file](https://cmake.org/cmake/help/latest/variable/CMAKE_TOOLCHAIN_FILE.html). This path is passed to CMake as `"-DCMAKE_TOOLCHAIN_FILE = `. Toolchain files specify locations of compilers and toolchain utilities, and other target platform and compiler-related information. By default, Visual Studio uses the [vcpkg toolchain file](https://github.com/microsoft/vcpkg-docs/blob/main/vcpkg/examples/installing-and-using-packages.md#cmake) if this setting is unspecified. ### Build root -Corresponds to **buildRoot**. Maps to [CMAKE_BINARY_DIR](https://cmake.org/cmake/help/v3.15/variable/CMAKE_BINARY_DIR.html), and specifies where to create the CMake cache. The specified folder is created if it doesn't exist. +Corresponds to **buildRoot**. Maps to [`CMAKE_BINARY_DIR`](https://cmake.org/cmake/help/v3.15/variable/CMAKE_BINARY_DIR.html), and specifies where to create the CMake cache. The specified folder is created if it doesn't exist. ## Command arguments @@ -52,35 +56,35 @@ The following settings are available under the **Command arguments** heading: ### CMake command arguments -Corresponds to **cmakeCommandArgs**. Specifies any additional [command line options](https://cmake.org/cmake/help/latest/manual/cmake.1.html) passed to CMake.exe. +Corresponds to **cmakeCommandArgs**. Specifies any more [command-line options](https://cmake.org/cmake/help/latest/manual/cmake.1.html) passed to CMake. ### Build command arguments -Corresponds to **buildCommandArgs**. Specifies additional switches to pass to the underlying build system. For example, passing `-v` when using the Ninja generator forces Ninja to output command lines. +Corresponds to **buildCommandArgs**. Specifies more switches to pass to the underlying build system. For example, passing `-v` when using the Ninja generator forces Ninja to output command lines. ### CTest command arguments -Corresponds to **ctestCommandArgs**. Specifies additional [command line options](https://cmake.org/cmake/help/v3.15/manual/ctest.1.html) to pass to CTest when running tests. +Corresponds to **ctestCommandArgs**. Specifies more [command-line options](https://cmake.org/cmake/help/v3.15/manual/ctest.1.html) to pass to CTest when running tests. ## General settings for remote builds For configurations such as Linux that use remote builds, the following settings are also available: -### rsync command arguments +### `rsync` command arguments -Additional command line options passed to [rsync](https://download.samba.org/pub/rsync/rsync.html), a fast and versatile file-copying tool. +Extra command-line options passed to [`rsync`](https://download.samba.org/pub/rsync/), a fast, versatile file-copying tool. ## CMake variables and cache -These settings enable you to set CMake variables and save them in *CMakeSettings.json*. They're passed to CMake at build time, and override whatever values are in the *CMakeLists.txt* file. You can use this section in the same way that you might use the CMakeGUI to view a list of all the CMake variables available to edit. Click the **Save and generate cache** button to view a list of all CMake variables available to edit, including advanced variables (per the CMakeGUI). You can filter the list by variable name. +These settings enable you to set CMake variables and save them in *`CMakeSettings.json`*. They're passed to CMake at build time, and override whatever values are in the *`CMakeLists.txt`* file. You can use this section in the same way that you might use the CMakeGUI to view a list of all the CMake variables available to edit. Choose the **Save and generate cache** button to view a list of all CMake variables available to edit, including advanced variables (per the CMakeGUI). You can filter the list by variable name. -Corresponds to **variables**. Contains a name-value pair of CMake variables passed as **-D** *_name_=_value_* to CMake. If your CMake project build instructions specify the addition of any variables directly to the CMake cache file, we recommend you add them here instead. +Corresponds to **variables**. Contains a name-value pair of CMake variables passed as **`-D name=value`** to CMake. If your CMake project build instructions specify the addition of any variables directly to the CMake cache file, we recommend you add them here instead. ## Advanced settings ### CMake generator -Corresponds to **generator**. Maps to the CMake **-G** switch, and specifies the [CMake generator](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html) to use. This property can also be used as a macro, `${generator}`, when composing other property values. Visual Studio currently supports the following CMake generators: +Corresponds to **generator**. Maps to the CMake **`-G`** switch, and specifies the [CMake generator](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html) to use. This property can also be used as a macro, `${generator}`, when composing other property values. Visual Studio currently supports the following CMake generators: - "Ninja" - "Unix Makefiles" @@ -94,15 +98,15 @@ Corresponds to **generator**. Maps to the CMake **-G** switch, and specifies the - "Visual Studio 14 2015 Win64" - "Visual Studio 14 2015 ARM" -Because Ninja is designed for fast build speeds instead of flexibility and function, it's set as the default. However, some CMake projects may be unable to correctly build using Ninja. If that occurs, you can instruct CMake to generate a Visual Studio project instead. +Because Ninja is designed for fast build speeds instead of flexibility and function, it's set as the default. However, some CMake projects might be unable to correctly build using Ninja. If that occurs, you can instruct CMake to generate a Visual Studio project instead. ### IntelliSense mode -The IntelliSense mode used by the IntelliSense engine. If no mode is selected then Visual Studio will inherit from the specified toolset. +The IntelliSense mode used by the IntelliSense engine. If no mode is selected, Visual Studio inherits the mode from the specified toolset. ### Install directory -The directory in which CMake installs targets. Maps to [CMAKE_INSTALL_PREFIX](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html). +The directory in which CMake installs targets. Maps to [`CMAKE_INSTALL_PREFIX`](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html). ### CMake executable @@ -112,11 +116,11 @@ For configurations such as Linux that use remote builds, the following settings ### Remote CMakeLists.txt root -The directory on the remote machine that contains the root *CMakeLists.txt* file. +The directory on the remote machine that contains the root *`CMakeLists.txt`* file. ### Remote install root -The directory on the remote machine in which CMake installs targets. Maps to [CMAKE_INSTALL_PREFIX](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html). +The directory on the remote machine in which CMake installs targets. Maps to [`CMAKE_INSTALL_PREFIX`](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html). ### Remote copy sources @@ -124,7 +128,7 @@ Specifies whether to copy source files to the remote machine, and lets you speci ## Directly edit CMakeSettings.json -You can also directly edit *CMakeSettings.json* to create custom configurations. The **Settings Editor** has an **Edit JSON** button in the upper right that opens the file for editing. +You can also directly edit *`CMakeSettings.json`* to create custom configurations. The **Settings Editor** has an **Edit JSON** button in the upper right that opens the file for editing. The following example shows a sample configuration, which you can use as a starting point: @@ -142,9 +146,9 @@ The following example shows a sample configuration, which you can use as a start }, ``` -JSON IntelliSense helps you edit the *CMakeSettings.json* file: +JSON IntelliSense helps you edit the *`CMakeSettings.json`* file: - ![CMake JSON IntelliSense](media/cmake-json-intellisense.png "CMake JSON IntelliSense") + ![Screenshot of the CMake JSON IntelliSense pop-up in the editor.](media/cmake-json-intellisense.png "CMake JSON IntelliSense") The JSON editor also informs you when you choose incompatible settings. @@ -154,23 +158,23 @@ For more information about each of the properties in the file, see [CMakeSetting ::: moniker range="<=msvc-150" -Visual Studio 2017 provides several CMake configurations that define how CMake.exe is invoked to create the CMake cache for a given project. To add a new configuration, click the configuration drop-down in the toolbar and choose **Manage Configurations**: +Visual Studio 2017 provides several CMake configurations that define how CMake is invoked to create the CMake cache for a given project. To add a new configuration, select the configuration drop-down in the toolbar and choose **Manage Configurations**: - ![CMake manage configurations](media/cmake-manage-configurations.png) + ![Screenshot of Manage configurations selected in the drop-down.](media/cmake-manage-configurations.png) You can choose from the list of predefined configurations: - ![CMake predefined configurations](media/cmake-configurations.png) + ![Add Configuration to CMake Settings dialog list of predefined configurations.](media/cmake-configurations.png) -The first time you select a configuration, Visual Studio creates a *CMakeSettings.json* file in your project's root folder. This file is used to re-create the CMake cache file, for example after a **Clean** operation. +The first time you select a configuration, Visual Studio creates a *`CMakeSettings.json`* file in your project's root folder. This file is used to re-create the CMake cache file, for example after a **Clean** operation. -To add an additional configuration, right click *CMakeSettings.json* and choose **Add Configuration**. +To add another configuration, right-click *`CMakeSettings.json`* and choose **Add Configuration**. - ![CMake Add configuration](media/cmake-add-configuration.png "CMake Add Configuration") + ![Screenshot of the shortcut menu with Add configuration selected.](media/cmake-add-configuration.png "CMake Add Configuration") -You can also edit the file using the **CMake Settings Editor**. Right-click on *CMakeSettings.json* in **Solution Explorer** and choose **Edit CMake Settings**. Or, select **Manage Configurations** from the configuration drop-down at the top of the editor window. +You can also edit the file using the **CMake Settings Editor**. Right-click on *`CMakeSettings.json`* in **Solution Explorer** and choose **Edit CMake Settings**. Or, select **Manage Configurations** from the configuration drop-down at the top of the editor window. -You can also directly edit *CMakeSettings.json* to create custom configurations. The following example shows a sample configuration, which you can use as a starting point: +You can also directly edit *`CMakeSettings.json`* to create custom configurations. The following example shows a sample configuration, which you can use as a starting point: ```json { @@ -186,11 +190,13 @@ You can also directly edit *CMakeSettings.json* to create custom configurations. }, ``` -JSON IntelliSense helps you edit the *CMakeSettings.json* file: - - ![CMake JSON IntelliSense](media/cmake-json-intellisense.png "CMake JSON IntelliSense") +JSON IntelliSense helps you edit the *`CMakeSettings.json`* file: -For more information about each of the properties in the file, see [CMakeSettings.json schema reference](cmakesettings-reference.md). + :::image type="complex" source="media/cmake-json-intellisense.png" alt-text="Screenshot of the CMake JSON IntelliSense pop-up in the editor."::: + The JSON IntelliSense pop-up for "configurations" shows buildCommandArgs, buildRoot, cmakeCommandArgs, configurationType, among several others. + :::image-end::: + +For more information about each of the properties in the file, see [`CMakeSettings.json` schema reference](cmakesettings-reference.md). ::: moniker-end diff --git a/docs/build/dll-frequently-asked-questions.md b/docs/build/dll-frequently-asked-questions.md deleted file mode 100644 index fc2a05c57a..0000000000 --- a/docs/build/dll-frequently-asked-questions.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -description: "Learn more about: DLL Frequently Asked Questions" -title: "MFC DLL Frequently Asked Questions" -ms.date: "05/06/2019" -helpviewer_keywords: ["troubleshooting [C++], DLLs", "DLLs [C++], frequently asked questions", "FAQs [C++], DLLs"] -ms.assetid: 09dd068e-fc33-414e-82f7-289c70680256 ---- -# DLL Frequently Asked Questions - -Following are some frequently asked questions (FAQ) about DLLs. - -- [Can an MFC DLL create multiple threads?](#mfc_multithreaded_1) - -- [Can a multithreaded application access an MFC DLL in different threads?](#mfc_multithreaded_2) - -- [Are there any MFC classes or functions that cannot be used in an MFC DLL?](#mfc_prohibited_classes) - -- [What optimization techniques should I use to improve the client application's performance when loading?](#mfc_optimization) - -- [There's a memory leak in my regular MFC DLL, but my code looks fine. How can I find the memory leak?](#memory_leak) - -## Can an MFC DLL create multiple threads? - -Except during initialization, an MFC DLL can safely create multiple threads as long as it uses the Win32 thread local storage (TLS) functions such as **TlsAlloc** to allocate thread local storage. However, if an MFC DLL uses **`__declspec(thread)`** to allocate thread local storage, the client application must be implicitly linked to the DLL. If the client application explicitly links to the DLL, the call to **LoadLibrary** will not successfully load the DLL. For more information about thread-local variables in DLLs, see [thread](../cpp/thread.md). - -An MFC DLL that creates a new MFC thread during startup will stop responding when it is loaded by an application. This includes whenever a thread is created by calling `AfxBeginThread` or `CWinThread::CreateThread` inside: - -- The `InitInstance` of a `CWinApp`-derived object in a regular MFC DLL. - -- A supplied `DllMain` or **RawDllMain** function in a regular MFC DLL. - -- A supplied `DllMain` or **RawDllMain** function in an MFC extension DLL. - -## Can a multithreaded application access an MFC DLL in different threads? - -Multithreaded applications can access regular MFC DLLs that dynamically link to MFC and MFC extension DLLs from different threads. An application can access regular MFC DLLs that statically link to MFC from multiple threads created in the application. - -## Are there any MFC classes or functions that cannot be used in an MFC DLL? - -Extension DLLs use the `CWinApp`-derived class of the client application. They must not have their own `CWinApp`-derived class. - -Regular MFC DLLs must have a `CWinApp`-derived class and a single object of that application class, as does an MFC application. Unlike the `CWinApp` object of an application, the `CWinApp` object of the DLL does not have a main message pump. - -Note that because the `CWinApp::Run` mechanism does not apply to a DLL, the application owns the main message pump. If the DLL opens modeless dialog boxes or has a main frame window of its own, the application's main message pump must call a routine exported by the DLL, which in turn calls the `CWinApp::PreTranslateMessage` member function of the DLL's application object. - -## What optimization techniques should I use to improve the client application's performance when loading? - -If your DLL is a regular MFC DLL that is statically linked to MFC, changing it to a regular MFC DLL that is dynamically linked to MFC reduces the file size. - -If the DLL has a large number of exported functions, use a .def file to export the functions (instead of using **`__declspec(dllexport)`**) and use the .def file [NONAME attribute](exporting-functions-from-a-dll-by-ordinal-rather-than-by-name.md) on each exported function. The NONAME attribute causes only the ordinal value and not the function name to be stored in the DLL's export table, which reduces the file size. - -DLLs that are implicitly linked to an application are loaded when the application loads. To improve the performance when loading, try dividing the DLL into different DLLs. Put all the functions that the calling application needs immediately after loading into one DLL and have the calling application implicitly link to that DLL. Put the other functions that the calling application does not need right away into another DLL and have the application explicitly link to that DLL. For more information, see [Link an executable to a DLL](linking-an-executable-to-a-dll.md#determining-which-linking-method-to-use). - -## There's a memory leak in my regular MFC DLL, but my code looks fine. How can I find the memory leak? - -One possible cause of the memory leak is that MFC creates temporary objects that are used inside message handler functions. In MFC applications, these temporary objects are automatically cleaned up in the `CWinApp::OnIdle()` function that is called in between processing messages. However, in MFC dynamic-link libraries (DLLs), the `OnIdle()` function is not automatically called. As a result, temporary objects are not automatically cleaned up. To clean up temporary objects, the DLL must explicitly call `OnIdle(1)` periodically. - -## See also - -[Create C/C++ DLLs in Visual Studio](dlls-in-visual-cpp.md) diff --git a/docs/build/dll-frequently-asked-questions.yml b/docs/build/dll-frequently-asked-questions.yml new file mode 100644 index 0000000000..d35f75948d --- /dev/null +++ b/docs/build/dll-frequently-asked-questions.yml @@ -0,0 +1,60 @@ +### YamlMime:FAQ +metadata: + description: "Learn more about: DLL frequently asked questions" + title: "MFC DLL frequently asked questions" + ms.date: "05/06/2019" + helpviewer_keywords: ["troubleshooting [C++], DLLs", "DLLs [C++], frequently asked questions", "FAQs [C++], DLLs"] + ms.assetid: 09dd068e-fc33-414e-82f7-289c70680256 + ms.topic: faq +title: DLL frequently asked questions +summary: | + +sections: + - name: Ignored + questions: + - question: | + Can an MFC DLL create multiple threads? + answer: | + Except during initialization, an MFC DLL can safely create multiple threads as long as it uses the Win32 thread local storage (TLS) functions such as **TlsAlloc** to allocate thread local storage. However, if an MFC DLL uses **`__declspec(thread)`** to allocate thread local storage, the client application must be implicitly linked to the DLL. If the client application explicitly links to the DLL, the call to **LoadLibrary** will not successfully load the DLL. For more information about thread-local variables in DLLs, see [thread](../cpp/thread.md). + + An MFC DLL that creates a new MFC thread during startup will stop responding when it is loaded by an application. This includes whenever a thread is created by calling `AfxBeginThread` or `CWinThread::CreateThread` inside: + + - The `InitInstance` of a `CWinApp`-derived object in a regular MFC DLL. + + - A supplied `DllMain` or **RawDllMain** function in a regular MFC DLL. + + - A supplied `DllMain` or **RawDllMain** function in an MFC extension DLL. + + - question: | + Can a multithreaded application access an MFC DLL in different threads? + answer: | + Multithreaded applications can access regular MFC DLLs that dynamically link to MFC and MFC extension DLLs from different threads. An application can access regular MFC DLLs that statically link to MFC from multiple threads created in the application. + + - question: | + Are there any MFC classes or functions that cannot be used in an MFC DLL? + answer: | + Extension DLLs use the `CWinApp`-derived class of the client application. They must not have their own `CWinApp`-derived class. + + Regular MFC DLLs must have a `CWinApp`-derived class and a single object of that application class, as does an MFC application. Unlike the `CWinApp` object of an application, the `CWinApp` object of the DLL does not have a main message pump. + + Note that because the `CWinApp::Run` mechanism does not apply to a DLL, the application owns the main message pump. If the DLL opens modeless dialog boxes or has a main frame window of its own, the application's main message pump must call a routine exported by the DLL, which in turn calls the `CWinApp::PreTranslateMessage` member function of the DLL's application object. + + - question: | + What optimization techniques should I use to improve the client application's performance when loading? + answer: | + If your DLL is a regular MFC DLL that is statically linked to MFC, changing it to a regular MFC DLL that is dynamically linked to MFC reduces the file size. + + If the DLL has a large number of exported functions, use a .def file to export the functions (instead of using **`__declspec(dllexport)`**) and use the .def file [NONAME attribute](exporting-functions-from-a-dll-by-ordinal-rather-than-by-name.md) on each exported function. The NONAME attribute causes only the ordinal value and not the function name to be stored in the DLL's export table, which reduces the file size. + + DLLs that are implicitly linked to an application are loaded when the application loads. To improve the performance when loading, try dividing the DLL into different DLLs. Put all the functions that the calling application needs immediately after loading into one DLL and have the calling application implicitly link to that DLL. Put the other functions that the calling application does not need right away into another DLL and have the application explicitly link to that DLL. For more information, see [Link an executable to a DLL](linking-an-executable-to-a-dll.md#determining-which-linking-method-to-use). + + - question: | + There's a memory leak in my regular MFC DLL, but my code looks fine. How can I find the memory leak? + answer: | + One possible cause of the memory leak is that MFC creates temporary objects that are used inside message handler functions. In MFC applications, these temporary objects are automatically cleaned up in the `CWinApp::OnIdle()` function that is called in between processing messages. However, in MFC dynamic-link libraries (DLLs), the `OnIdle()` function is not automatically called. As a result, temporary objects are not automatically cleaned up. To clean up temporary objects, the DLL must explicitly call `OnIdle(1)` periodically. + +additionalContent: | + + ## See also + + [Create C/C++ DLLs in Visual Studio](dlls-in-visual-cpp.md) diff --git a/docs/build/dlls-in-visual-cpp.md b/docs/build/dlls-in-visual-cpp.md index 99b9239f5e..a1974a8268 100644 --- a/docs/build/dlls-in-visual-cpp.md +++ b/docs/build/dlls-in-visual-cpp.md @@ -59,7 +59,7 @@ Describes how to create and use a DLL using Visual Studio. [Kinds of DLLs](kinds-of-dlls.md)\ Provides information about the different kinds of DLLs that can be built. -[DLL frequently asked questions](dll-frequently-asked-questions.md)\ +[DLL frequently asked questions](dll-frequently-asked-questions.yml)\ Provides answers to frequently asked questions about DLLs. [Link an executable to a DLL](linking-an-executable-to-a-dll.md)\ diff --git a/docs/build/exception-handling-x64.md b/docs/build/exception-handling-x64.md index 3447b9f6af..41a6e29b6e 100644 --- a/docs/build/exception-handling-x64.md +++ b/docs/build/exception-handling-x64.md @@ -440,6 +440,8 @@ typedef enum _UNWIND_OP_CODES { UWOP_PUSH_MACHFRAME /* info == 0: no error-code, 1: error-code */ } UNWIND_CODE_OPS; +typedef unsigned char UBYTE; + typedef union _UNWIND_CODE { struct { UBYTE CodeOffset; @@ -488,7 +490,7 @@ typedef struct _RUNTIME_FUNCTION { ((PRUNTIME_FUNCTION)((base) + *(PULONG)GetLanguageSpecificDataPtr(info))) #define GetExceptionDataPtr(info) \ - ((PVOID)((PULONG)GetLanguageSpecificData(info) + 1) + ((PVOID)((PULONG)GetLanguageSpecificData(info) + 1)) ``` ## See also diff --git a/docs/build/exporting-c-functions-for-use-in-c-or-cpp-language-executables.md b/docs/build/exporting-c-functions-for-use-in-c-or-cpp-language-executables.md index ae89cbf097..2386881514 100644 --- a/docs/build/exporting-c-functions-for-use-in-c-or-cpp-language-executables.md +++ b/docs/build/exporting-c-functions-for-use-in-c-or-cpp-language-executables.md @@ -1,15 +1,15 @@ --- -description: "Learn more about: Exporting C Functions for Use in C or C++ Language Executables" -title: "Exporting C Functions for Use in C or C++ Language Executables" -ms.date: "11/04/2016" +description: "Learn more about: Exporting C functions for use in C or C++ language executables" +title: "Export C functions for use in C or C++ language executables" +ms.date: 05/24/2022 helpviewer_keywords: ["functions [C], exporting", "functions [C], C or C++ executables and", "__cplusplus macro", "exporting DLLs [C++], C functions in C++ executables", "exporting functions [C++], C functions in C++ executables"] ms.assetid: b51d6e5e-37cf-4c1c-b0bf-fcf188c82f00 --- -# Exporting C Functions for Use in C or C++ Language Executables +# Export C functions for use in C or C++ language executables -If you have functions in a DLL written in C that you want to access from a C language or C++ language module, you should use the **__cplusplus** preprocessor macro to determine which language is being compiled, and then declare these functions with C linkage if being used from a C++ language module. If you use this technique and provide header files for your DLL, these functions can be used by C and C++ users with no change. +If you have functions in a DLL written in C, you can use a preprocessor macro to make them easy to access from both C language and C++ language code. The **`__cplusplus`** preprocessor macro indicates which language is being compiled. You may use it to declare the functions with C linkage when called from C++ language code. If you use this technique and provide header files for your DLL, these functions can be used by C and C++ users with no change. -The following code shows a header file that can be used by C and C++ client applications: +The following code shows a header file that both C and C++ client applications can use: ```h // MyCFuncs.h @@ -26,7 +26,7 @@ __declspec( dllimport ) void AnotherCFunc(); #endif ``` -If you need to link C functions to your C++ executable and the function declaration header files have not used the above technique, in the C++ source file, do the following to prevent the compiler from decorating the C function names: +Sometimes you may need to link C functions to your C++ executable, but the function declaration header files haven't used the above technique. You can still call the functions from C++. In the C++ source file, wrap the `#include` directive to prevent the compiler from decorating the C function names: ```cpp extern "C" { @@ -36,15 +36,15 @@ extern "C" { ## What do you want to do? -- [Export from a DLL using .def files](exporting-from-a-dll-using-def-files.md) +- [Export from a DLL using `.def` files](exporting-from-a-dll-using-def-files.md) -- [Export from a DLL using __declspec(dllexport)](exporting-from-a-dll-using-declspec-dllexport.md) +- [Export from a DLL using `__declspec(dllexport)`](exporting-from-a-dll-using-declspec-dllexport.md) -- [Export and import using AFX_EXT_CLASS](exporting-and-importing-using-afx-ext-class.md) +- [Export and import using `AFX_EXT_CLASS`](exporting-and-importing-using-afx-ext-class.md) - [Determine which exporting method to use](determining-which-exporting-method-to-use.md) -- [Import into an application using __declspec(dllimport)](importing-into-an-application-using-declspec-dllimport.md) +- [Import into an application using `__declspec(dllimport)`](importing-into-an-application-using-declspec-dllimport.md) - [Initialize a DLL](run-time-library-behavior.md#initializing-a-dll) @@ -52,7 +52,7 @@ extern "C" { - [Decorated names](reference/decorated-names.md) -- [Using extern to Specify Linkage](../cpp/extern-cpp.md) +- [Using `extern` to specify linkage](../cpp/extern-cpp.md) ## See also diff --git a/docs/build/formatting-the-output-of-a-custom-build-step-or-build-event.md b/docs/build/formatting-the-output-of-a-custom-build-step-or-build-event.md index 14b67bab22..938dc06425 100644 --- a/docs/build/formatting-the-output-of-a-custom-build-step-or-build-event.md +++ b/docs/build/formatting-the-output-of-a-custom-build-step-or-build-event.md @@ -1,11 +1,11 @@ --- -description: "Learn more about: Formatting the Output of a Custom Build Step or Build Event" -title: "Formatting the Output of a Custom Build Step or Build Event" -ms.date: "08/27/2018" +description: "Learn more about: Formatting the output of a custom build step or build event" +title: "Formatting the output of a custom build step or build event" +ms.date: 03/15/2022 helpviewer_keywords: ["builds [C++], build events", "custom build steps [C++], output format", "events [C++], build", "build events [C++], output format", "build steps [C++], output format", "builds [C++], custom build steps"] ms.assetid: 92ad3e38-24d7-4b89-90e6-5a16f5f998da --- -# Formatting the Output of a Custom Build Step or Build Event +# Formatting the output of a custom build step or build event If the output of a custom build step or build event is formatted correctly, users get the following benefits: @@ -13,28 +13,30 @@ If the output of a custom build step or build event is formatted correctly, user - Output appears in the **Task List** window. -- Clicking on the output in the **Output** window displays the appropriate topic. +- Clicking on the output in the **Output** window displays the appropriate location. -- F1 operations are enabled in the **Task List** window or **Output** window. +- **F1** operations are enabled in the **Task List** window or **Output** window. + +## Output format The format of the output should be: -> {filename**(**line# \[**,** column#]**)** | *toolname*} **:** \[ any text ] {**error** | **warning**} code+number**:**localizable string \[ any text ] +> { *filename*`(`*line-number* \[`,` *column-number*]`)` \| *tool-name* } `:` \[ *any-text* ] {`error` \| `warning`} *code-type-and-number* `:` *localizable-string* \[ *any-text* ] Where: -- {*a* | *b*} is a choice of either *a* or *b*. +- { *a* \| *b* } is a choice of either *a* or *b*, -- \[item] is an optional string or parameter. +- \[ *item* ] is an optional string or parameter, -- **Bold** represents a literal. +- `text` represents a literal. For example: -> C:\\*sourcefile.cpp*(134) : error C2143: syntax error : missing ';' before '}' +> C:\\sourcefile.cpp(134) : error C2143: syntax error : missing ';' before '}' > -> LINK : fatal error LNK1104: cannot open file '*somelib.lib*' +> LINK : fatal error LNK1104: cannot open file 'some-library.lib' ## See also -[Understanding Custom Build Steps and Build Events](understanding-custom-build-steps-and-build-events.md) +[Understanding custom build steps and build events](understanding-custom-build-steps-and-build-events.md) diff --git a/docs/build/get-started-linux-cmake.md b/docs/build/get-started-linux-cmake.md index 0550b4c754..1ffb0fb6d2 100644 --- a/docs/build/get-started-linux-cmake.md +++ b/docs/build/get-started-linux-cmake.md @@ -2,7 +2,7 @@ title: Create C++ cross-platform projects in Visual Studio description: "How to set up, compile, and debug a C++ open-source CMake project in Visual Studio that targets both Linux and Windows." ms.topic: tutorial -ms.date: "01/08/2020" +ms.date: 02/07/2022 --- # Tutorial: Create C++ cross-platform projects in Visual Studio @@ -21,11 +21,13 @@ In this tutorial, you learn how to: ## Prerequisites * Set up Visual Studio for Cross Platform C++ Development + * First, [install Visual Studio](https://visualstudio.microsoft.com/vs/) and choose the **Desktop development with C++** and **Linux development with C++ workloads**. This minimal install is only 3 GB. Depending on your download speed, installation shouldn't take more than 10 minutes. * Set up a Linux machine for Cross Platform C++ Development - * Visual Studio doesn't require any specific distribution of Linux. The OS can be running on a physical machine, in a VM, or in the cloud. You could also use the Windows Subsystem for Linux (WSL). However, for this tutorial a graphical environment is required. WSL isn't recommended here, because it's intended primarily for command-line operations. - * Visual Studio requires these tools on the Linux machine: C++ compilers, gdb, ssh, rsync, make, and zip. On Debian-based systems, you can use this command to install these dependencies: + + * Visual Studio doesn't require any specific distribution of Linux. The OS can be running on a physical machine, in a VM, or in the cloud. You could also use the Windows Subsystem for Linux (WSL). However, for this tutorial, a graphical environment is required. WSL isn't recommended here, because it's intended primarily for command-line operations. + * Visual Studio requires these tools on the Linux machine: C++ compilers, `gdb`, `ssh`, `rsync`, `make`, and `zip`. On Debian-based systems, you can use this command to install these dependencies: ```cmd sudo apt install -y openssh-server build-essential gdb rsync make zip @@ -38,7 +40,7 @@ In this tutorial, you learn how to: chmod +x cmake-3.11.18033000-MSVC_2-Linux-x86_64.sh ``` - * You can see the options for running the script with `-–help`. We recommend that you use the `–prefix` option to specify installing in the **/usr** path, because **/usr/bin** is the default location where Visual Studio looks for CMake. The following example shows the Linux-x86_64 script. Change it as needed if you're using a different target platform. + * You can see the options for running the script with `--help`. We recommend that you use the `-prefix` option to specify installing in the **/usr** path, because **/usr/bin** is the default location where Visual Studio looks for CMake. The following example shows the Linux-x86_64 script. Change it as needed if you're using a different target platform. ```cmd sudo ./cmake-3.11.18033000-MSVC_2-Linux-x86_64.sh --skip-license --prefix=/usr @@ -49,43 +51,43 @@ In this tutorial, you learn how to: ## Clone an open-source CMake project from GitHub -This tutorial uses the Bullet Physics SDK on GitHub. It provides collision detection and physics simulations for many applications. The SDK includes sample executable programs that compile and run without having to write additional code. This tutorial doesn't modify any of the source code or build scripts. To start, clone the *bullet3* repository from GitHub on the machine where you have Visual Studio installed. +This tutorial uses the Bullet Physics SDK on GitHub. It provides collision detection and physics simulations for many applications. The SDK includes sample executable programs that compile and run without having to write other code. This tutorial doesn't modify any of the source code or build scripts. To start, clone the *bullet3* repository from GitHub on the machine where you have Visual Studio installed. ```cmd git clone https://github.com/bulletphysics/bullet3.git ``` -1. On the Visual Studio main menu, choose **File > Open > CMake**. Navigate to the CMakeLists.txt file in the root of the bullet3 repo you just downloaded. +1. On the Visual Studio main menu, choose **File > Open > CMake**. Navigate to the `CMakeLists.txt` file in the root of the bullet3 repo you downloaded. - ![Visual Studio menu for File > Open > CMake](media/cmake-open-cmake.png) + ![Screenshot of Visual Studio menu showing File > Open > C Make. A folder has yet to be opened. This is just the menu opened to this point.](media/cmake-open-cmake.png) As soon as you open the folder, your folder structure becomes visible in the **Solution Explorer**. - ![Visual Studio Solution Explorer Folder View](media/cmake-bullet3-solution-explorer.png) + ![Screenshot of the Solution Explorer window in Folder View mode. It displays the contents of the project (files and folders) and CMakeLists.txt is highlighted.](media/cmake-bullet3-solution-explorer.png) This view shows you exactly what is on disk, not a logical or filtered view. By default, it doesn't show hidden files. 1. Choose the **Show all files** button to see all the files in the folder. - ![Visual Studio Solution Explorer Show All Files button](media/cmake-bullet3-show-all-files.png) + ![Screenshot of the Solution Explorer window with the Show All Files button highlighted. This button sits on top of the solution explorer window and to the right.](media/cmake-bullet3-show-all-files.png) ## Switch to targets view When you open a folder that uses CMake, Visual Studio automatically generates the CMake cache. This operation might take a few moments, depending on the size of your project. -1. In the **Output Window**, select **Show output from** and then choose **CMake** to monitor the status of the cache generation process. When the operation is complete, it says "Target info extraction done". +1. In the **Output Window**, select **Show output from** and then choose **CMake** to monitor the status of the cache generation process. When the operation is complete, it says "Target info extraction done." - ![Visual Studio Output window showing output from CMake](media/cmake-bullet3-output-window.png) + ![Screenshot of the Output window. The Show output from: dropdown is set to CMake.](media/cmake-bullet3-output-window.png) After this operation completes, IntelliSense is configured. You can build the project, and debug the application. Visual Studio now shows a logical view of the solution, based on the targets specified in the CMakeLists files. 1. Use the **Solutions and Folders** button in the **Solution Explorer** to switch to CMake Targets View. - ![Solutions and Folders button in the Solution Explorer to show CMake targets view](media/cmake-bullet3-show-targets.png) + ![Screenshot of the Solutions and Folders button in the Solution Explorer. It is selected, showing a dropdown with a choice for c:\projects\bullet3 and another choice for CMake Targets View, which is selected.](media/cmake-bullet3-show-targets.png) - Here is what that view looks like for the Bullet SDK: + Here's what that view looks like for the Bullet SDK: - ![Solution Explorer CMake targets view](media/cmake-bullet3-targets-view.png) + ![Screenshot of the Solution Explorer CMake targets view. It contains an entry called BULLET_PHYSICS Project, under which are entries like App_BasicExample (executable), App_ExampleBrowser (executable), and so on.](media/cmake-bullet3-targets-view.png) Targets view provides a more intuitive view of what is in this source base. You can see some targets are libraries and others are executables. @@ -97,17 +99,17 @@ Visual Studio creates a default **x64-Debug** configuration for Windows. Configu 1. Add a new configuration. Open the **Configuration** drop-down in the toolbar and select **Manage Configurations**. - ![Manage Configuration drop-down](media/cmake-bullet3-manage-configurations.png) + ![Screenshot of the Configuration drop-down in the toolbar. Manage Configurations... is selected.](media/cmake-bullet3-manage-configurations.png) - The [CMake Settings Editor](customize-cmake-settings.md) opens. Select the green plus sign on the left-hand side of the editor to add a new configuration. The **Add Configuration to CMakeSettings** dialog appears. + The [CMake Settings Editor](customize-cmake-settings.md) opens. Select the green plus sign on the left-hand side of the editor to add a new configuration. The **Add Configuration to CMakeSettings** dialog appears: - ![Add Configuration to CMakeSettings dialog](media/cmake-bullet3-add-configuration-x64-debug.png) + ![Screenshot of the Add Configuration to CMakeSettings dialog. It has entries such as Linux-Debug, x86-Debug. x64-Debug is selected.](media/cmake-bullet3-add-configuration-x64-debug.png) - This dialog shows all the configurations included with Visual Studio, plus any custom configurations that you create. If you want to continue to use a **x64-Debug** configuration, that should be the first one you add. Select **x64-Debug**, and then choose the **Select** button. Visual Studio creates the CMakeSettings.json file with a configuration for **x64-Debug**, and saves it to disk. You can use whatever names you like for your configurations by changing the name parameter directly in CMakeSettings.json. + This dialog shows all the configurations included with Visual Studio, plus any custom configurations that you create. If you want to continue to use a **x64-Debug** configuration that should be the first one you add. Select **x64-Debug**, and then choose the **Select** button. Visual Studio creates the CMakeSettings.json file with a configuration for **x64-Debug**, and saves it to disk. You can use whatever names you like for your configurations by changing the name parameter directly in CMakeSettings.json. ## Set a breakpoint, build, and run on Windows -In this step, we'll debug an example program that demonstrates the Bullet Physics library. +In this step, we debug an example program that demonstrates the Bullet Physics library. 1. In **Solution Explorer**, select AppBasicExampleGui and expand it. @@ -121,17 +123,17 @@ In this step, we'll debug an example program that demonstrates the Bullet Physic 1. In the browser view above your source, you should see that you're in the `CommonRigidBodyBase`. To the right, you can select members to examine. Open the drop-down and select `mouseButtonCallback` to go to the definition of that function in the header. - ![Visual Studio member list toolbar](media/cmake-bullet3-member-list-toolbar.png) + ![Screenshot of the Member list toolbar drop-down in the editor window. It list functions such as getRayTo(in x, int y). The mouse button callback method is highlighted.](media/cmake-bullet3-member-list-toolbar.png) 1. Place a breakpoint on the first line within this function. It gets hit when you click a mouse button within the window of the application, when run under the Visual Studio debugger. -1. To launch the application, select the launch drop-down in the toolbar. It's the one with the green play icon that says "Select Startup Item". In the drop-down, select AppBasicExampleGui.exe. The executable name now displays on the launch button: +1. To launch the application, select the launch drop-down in the toolbar. It's the one with the green play icon that says "Select Startup Item." In the drop-down, select AppBasicExampleGui.exe. The executable name now displays on the launch button: - ![Visual Studio toolbar launch drop-down for Select Startup Item](media/cmake-bullet3-launch-button.png) + ![Screenshot of the Visual Studio toolbar launch drop-down. AppBasicExampleGui.exe is selected, but other options are visible such as App_ExampleBrowser.exe, App_HelloWorld.exe, and others.](media/cmake-bullet3-launch-button.png) 1. Choose the launch button to build the application and necessary dependencies, then launch it with the Visual Studio debugger attached. After a few moments, the running application appears: - ![Visual Studio debugging a Windows application](media/cmake-bullet3-launched.png) + ![Screenshot of the running application. It's a collection of colored blocks on a yellow plane.](media/cmake-bullet3-launched.png) 1. Move your mouse into the application window, then click a button to trigger the breakpoint. The breakpoint brings Visual Studio back to the foreground, and the editor shows the line where execution is paused. You can inspect the application variables, objects, threads, and memory, or step through your code interactively. Choose **Continue** to let the application resume, and then exit it normally. Or, halt execution within Visual Studio by using the stop button. @@ -143,19 +145,21 @@ In this step, we'll debug an example program that demonstrates the Bullet Physic 1. Select **Linux-Debug** in the configuration drop-down. - ![Launch configuration drop-down with X64-Debug and Linux-Debug options](media/cmake-bullet3-linux-configuration-item.png) + ![Screenshot of the launch configuration drop-down. The visible options are: x64-Debug, Linux-Debug, and Manage Configurations.](media/cmake-bullet3-linux-configuration-item.png) If it's the first time you're connecting to a Linux system, the **Connect to Remote System** dialog appears. - ![Visual Studio Connect to Remote System dialog](media/cmake-bullet3-connection-manager.png) - + :::image type="complex" source="./media/cmake-bullet3-connection-manager.png" alt-text="Screenshot of the Visual Studio Connect to Remote System dialog."::: + The dialog has fields for the host name, port, user name, authentication type, and password. All of the fields are blank except Port is set to 22 and Authentication type is set to Password. + :::image-end::: + If you've already added a remote connection, you can open this window by navigating to **Tools > Options > Cross Platform > Connection Manager**. -1. Provide the [connection information to your Linux machine](../linux/connect-to-your-remote-linux-computer.md) and choose **Connect**. Visual Studio adds that machine as to CMakeSettings.json as your default connection for **Linux-Debug**. It also pulls down the headers from your remote machine, so you get [IntelliSense specific to that remote connection](../linux/configure-a-linux-project.md#remote_intellisense). Next, Visual Studio sends your files to the remote machine and generates the CMake cache on the remote system. These steps may take some time, depending on the speed of your network and power of your remote machine. You'll know it's complete when the message "Target info extraction done" appears in the CMake output window. +1. Provide the [connection information to your Linux machine](../linux/connect-to-your-remote-linux-computer.md) and choose **Connect**. Visual Studio adds that machine as to CMakeSettings.json as your default connection for **Linux-Debug**. It also pulls down the headers from your remote machine, so you get [IntelliSense specific to that remote connection](../linux/configure-a-linux-project.md#remote_intellisense). Next, Visual Studio sends your files to the remote machine and generates the CMake cache on the remote system. These steps might take some time, depending on the speed of your network and power of your remote machine. You know it's complete when the message "Target info extraction done" appears in the CMake output window. ## Set a breakpoint, build, and run on Linux -Because it's a desktop application, you need to provide some additional configuration information to the debug configuration. +Because it's a desktop application, you need to provide some more configuration information to the debug configuration. 1. In the CMake Targets view, right-click AppBasicExampleGui and choose **Debug and Launch Settings** to open the launch.vs.json file that's in the hidden **.vs** subfolder. This file is local to your development environment. You can move it into the root of your project if you wish to check it in and save it with your team. In this file, a configuration has been added for AppBasicExampleGui. These default settings work in most cases, but not here. Because it's a desktop application, you need to provide some additional information to launch the program so you can see it on your Linux machine. @@ -165,7 +169,7 @@ Because it's a desktop application, you need to provide some additional configur echo $DISPLAY ``` - In the configuration for AppBasicExampleGui, there's a parameter array, "pipeArgs". It contains a line: "${debuggerCommand}". It's the command that launches gdb on the remote machine. Visual Studio must export the display into this context before that command runs. For example, if the value of your display is `:1`, modify that line as follows: + In the configuration for AppBasicExampleGui, there's a parameter array, "pipeArgs". It contains a line: "${debuggerCommand}". It's the command that launches `gdb` on the remote machine. Visual Studio must export the display into this context before that command runs. For example, if the value of your display is `:1`, modify that line as follows: ```cmd "export DISPLAY=:1;${debuggerCommand}", @@ -175,13 +179,17 @@ Because it's a desktop application, you need to provide some additional configur 1. Move your mouse into the application window, and click a button. The breakpoint is hit. Program execution pauses, Visual Studio comes back to the foreground, and you see your breakpoint. You should also see a Linux Console Window appear in Visual Studio. The window provides output from the remote Linux machine, and it can also accept input for `stdin`. Like any Visual Studio window, you can dock it where you prefer to see it. Its position is persisted in future sessions. - ![Visual Studio Linux Console Window](media/cmake-bullet3-linux-console.png) + :::image type="complex" source="media/cmake-bullet3-linux-console.png" alt-text="Screenshot of the Visual Studio Linux Console Window."::: + The output in the window indicates that the C11 functions dynamically loaded using dlopen/dlsym is OK, a GL 3.0 context has been created and the Direct GLX rendering context obtained and made current. The window has various version information for GL_VENDOR, GL_VERSION, GL_SHADING_LANGUAGE_VERSION, and so on. + :::image-end::: -1. You can inspect the application variables, objects, threads, memory, and step through your code interactively using Visual Studio. But this time, you're doing it all on a remote Linux machine instead of your local Windows environment. You can choose **Continue** to let the application resume and exit normally, or you can choose the stop button, just as with local execution. +1. You can inspect the application variables, objects, threads, memory, and step through your code interactively using Visual Studio. But this time, you're doing it all on a remote Linux machine instead of your local Windows environment. You can choose **Continue** to let the application resume and exit normally, or you can choose the stop button, as with local execution. 1. Look at the Call Stack window and view the Calls to `x11OpenGLWindow` since Visual Studio launched the application on Linux. - ![Call Stack window showing Linux call stack](media/cmake-bullet3-linux-callstack.png) + :::image type="complex" source="media/cmake-bullet3-linux-callstack.png" alt-text="The Visual Studio Call Stack window, showing Linux call stack."::: + The callstack shows the breakpoint on CommonRigidBodyBase::mouseMoveCallback, and the calls that precede it such as OnMouseMove, X11OpenGLWindow::pumpMessage, and so on. + :::image-end::: ## What you learned @@ -199,4 +207,5 @@ Learn more about configuring and debugging CMake projects in Visual Studio: > [Configure CMake debugging sessions](configure-cmake-debugging-sessions.md)

> [Deploy, run, and debug your Linux project](../linux/deploy-run-and-debug-your-linux-project.md)

> [CMake predefined configuration reference](cmake-predefined-configuration-reference.md) -> +> [vcpkg in CMake projects](/vcpkg/users/buildsystems/cmake-integration) +> [Install and use packages with CMake in Visual Studio](/vcpkg/get_started/get-started-vs) diff --git a/docs/build/how-to-add-custom-build-tools-to-msbuild-projects.md b/docs/build/how-to-add-custom-build-tools-to-msbuild-projects.md index 979b34abdb..ca0ed06ff1 100644 --- a/docs/build/how-to-add-custom-build-tools-to-msbuild-projects.md +++ b/docs/build/how-to-add-custom-build-tools-to-msbuild-projects.md @@ -1,25 +1,27 @@ --- -description: "Learn more about: How to: Add Custom Build Tools to MSBuild Projects" -title: "How to: Add Custom Build Tools to MSBuild Projects" -ms.date: "11/04/2016" +description: "Learn more about how to add custom build tools to MSBuild projects" +title: "How to: Add custom build tools to MSBuild projects" +ms.date: 03/15/2022 helpviewer_keywords: ["msbuild (c++), howto: add custom build tools"] ms.assetid: de03899a-371d-4396-9bf9-34f45a65e909 --- -# How to: Add Custom Build Tools to MSBuild Projects +# How to: Add custom build tools to MSBuild projects -A custom build tool is a user-defined, command-line tool that is associated with a particular file. +A custom build tool is a user-defined, command-line tool that's associated with a particular file. -For a particular file, specify in the project file (.vcxproj) the command line to execute, any additional input or output files, and a message to display. If **MSBuild** determines that your output files are out of date with regard to your input files, it displays the message and executes the command-line tool. +For a particular file, specify in the project file (*`.vcxproj`*) the command line to execute, any other input or output files, and a message to display. If **MSBuild** determines that your output files are out of date relative to your input files, it displays the message and executes the command-line tool. -To specify when the custom build tool executes, use one or both of the `CustomBuildBeforeTargets` and `CustomBuildAfterTargets` XML elements in the project file. For example, you might specify that your custom build tool run after the MIDL compiler and before the C/C++ compiler. Specify the `CustomBuildBeforeTargets` element to execute the tool before a particular target runs; the `CustomBuildAfterTargets` element to execute the tool after a particular target; or both elements to run the tool between execution of two targets. If neither element is specified, your custom build tool executes at its default location, which is before the **MIDL** target. +## Specify custom build tools and custom build steps + +To specify when the custom build tool executes, use one or both of the `CustomBuildBeforeTargets` and `CustomBuildAfterTargets` XML elements in the project file. For example, you might specify that your custom build tool run after the MIDL compiler and before the C/C++ compiler. Specify the `CustomBuildBeforeTargets` element to execute the tool before a particular target runs. Use the `CustomBuildAfterTargets` element to execute the tool after a particular target runs. Use both elements to run the tool between execution of two targets. If neither element is specified, your custom build tool executes at its default location, which is before the **MIDL** target. Custom build steps and custom build tools share the information specified in the `CustomBuildBeforeTargets` and `CustomBuildAfterTargets` XML elements. Specify those targets one time in your project file. ### To add a custom build tool -1. Add an item group to the project file and add an item for each input file. Specify the command, additional inputs, outputs, and a message as item metadata, as shown here. This example assumes that a "faq.txt" file exists in the same directory as your project. +1. Add an item group to the project file and add an item for each input file. Specify the command and its inputs, outputs, and a message as item metadata, as shown here. This example assumes that a "faq.txt" file exists in the same directory as your project. The custom build step copies it to the output directory. - ``` + ```xml Copying readme... @@ -29,11 +31,11 @@ Custom build steps and custom build tools share the information specified in the ``` -### To define where in the build the custom build tools will execute +### To define where in the build the custom build tools execute -1. Add the following property group to the project file. You have to specify at least one of the targets, but you can omit the other if you are only interested in having your build step execute before (or after) a particular target. This example performs the custom step after compiling but before linking. +1. Add the following property group to the project file. You have to specify at least one of the targets. You can omit the other if you're only interested in having your build step execute before (or after) a particular target. This example performs the custom step after compiling but before linking. - ``` + ```xml ClCompile Link @@ -42,6 +44,8 @@ Custom build steps and custom build tools share the information specified in the ## See also -[Walkthrough: Using MSBuild to Create a C++ Project](walkthrough-using-msbuild-to-create-a-visual-cpp-project.md)
-[How to: Use Build Events in MSBuild Projects](how-to-use-build-events-in-msbuild-projects.md)
-[How to: Add a Custom Build Step to MSBuild Projects](how-to-add-a-custom-build-step-to-msbuild-projects.md) +[Walkthrough: Using MSBuild to create a C++ project](walkthrough-using-msbuild-to-create-a-visual-cpp-project.md)\ +[How to: Use build events in MSBuild projects](how-to-use-build-events-in-msbuild-projects.md)\ +[How to: Add a custom build step to MSBuild projects](how-to-add-a-custom-build-step-to-msbuild-projects.md)\ +[Common macros for MSBuild commands and properties](reference/common-macros-for-build-commands-and-properties.md)\ +[MSBuild well-known item metadata](/visualstudio/msbuild/msbuild-well-known-item-metadata) diff --git a/docs/build/how-to-create-a-cpp-project-from-existing-code.md b/docs/build/how-to-create-a-cpp-project-from-existing-code.md index 03fb0fd65d..7d4b11a4b2 100644 --- a/docs/build/how-to-create-a-cpp-project-from-existing-code.md +++ b/docs/build/how-to-create-a-cpp-project-from-existing-code.md @@ -1,21 +1,26 @@ --- description: "Learn more about: How to: Create a C++ Project from Existing Code" title: "How to: Create a C++ Project from Existing Code" -ms.date: "05/06/2019" +ms.date: 08/12/2024 helpviewer_keywords: ["C++, creating projects from existing code", "Create New Project From Existing Code Files Wizard, project settings"] f1_keywords: ["vc.appwiz.importwiz.location", "vc.appwiz.importwiz.appsettings", "vc.appwiz.importwiz.debugsettings", "vc.appwiz.importwiz.releasesettings"] -ms.assetid: e328a938-395c-48ea-9e35-dd433de12b31 --- # How to: Create a C++ Project from Existing Code -In Visual Studio, you can port existing code files into a C++ project using the **Create New Project From Existing Code Files** wizard. This wizard creates a project solution that uses the MSBuild system to manage source files and build configuration. It works best with relatively simple projects that do not have complex folder hierarchies. The wizard isn't available in older Express editions of Visual Studio. +In Visual Studio, you can port existing code files into a C++ project using the **Create New Project From Existing Code Files** wizard. This wizard creates a project solution that uses the MSBuild system to manage source files and build configuration. It works best with relatively simple projects that don't have complex folder hierarchies. The wizard isn't available in older Express editions of Visual Studio. Porting existing code files into a C++ project enables the use of native MSBuild project management features built into the IDE. If you prefer to use your existing build system, such as nmake makefiles, CMake, or alternatives, you can use the Open Folder or CMake options instead. For more information, see [Open Folder projects for C++](open-folder-projects-cpp.md) or [CMake projects in Visual Studio](cmake-projects-in-visual-studio.md). Both options let you use IDE features such as [IntelliSense](/visualstudio/ide/using-intellisense) and [Project Properties](working-with-project-properties.md). ### To create a C++ project from existing code +The following instructions assume that Visual Studio is running and is past the start page. If you are on the Visual Studio start page, choose **Continue without code** to open the IDE. + 1. On the **File** menu, select **New** > **Project From Existing Code**. +1. The **Create New Project from Existing Code Files** wizard opens. Choose what type of project to create from the dropdown: **Visual C++**, **Visual Basic**, or **C#**. Then choose **Next** to continue. + :::image type="complex" source="./media/create-from-existing-code-wizard.png" alt-text="Screenshot showing the Create New Project from Existing Code dialog."::: + The project type dropdown shows the options Visual C++ (which is selected), Visual Basic, and C#. + :::image-end::: 1. Specify your project location, the directory for your source files, and the kinds of files the wizard imports into the new project. Choose **Next** to continue. | Setting | Description | @@ -25,7 +30,7 @@ Porting existing code files into a C++ project enables the use of native MSBuild | **Add files to the project from these folders** | Check to set the wizard to copy existing code files from their original directories (that are specified in the list box below this control) into the new project.

Check **Add Subfolders** to specify copying code files from all subdirectories into the project. The directories are listed in the **Folder** column.
- Select **Add** to display the **Add files to the project from this folder** dialog box, to specify directories the wizard searches for existing code files.
- Select **Remove** to delete the directory path selected in the list box.

In the **File types to add to the project** box, specify the kinds of files that the wizard adds to the new project based on the given file extensions. File extensions are preceded with the asterisk wildcard character and are delimited in the list of file extensions by a semicolon. | | **Show all files in Solution Explorer** | Specifies that all files in the new project to be visible and displayed in the **Solution Explorer** window. This option is enabled by default. | - ![Project location](media/location.png) + ![Create New Project from Existing Code dialog, showing Project location settings.](media/location.png) 1. Specify the project settings to use such as the build environment for the new project and the build settings to match a specific type of new project to generate. Choose **Next** to continue. @@ -34,7 +39,7 @@ Porting existing code files into a C++ project enables the use of native MSBuild | **Use Visual Studio** | Specifies to use build tools that are included in Visual Studio for building the new project. This option is selected by default.

Select **Project Type** to specify the type of project the wizard generates. Choose **Windows application project**, **Console application project**, **Dynamically linked library (DLL) project**, or **Static library (LIB) project**.

Check **Add support for ATL** to add ATL support to the new project.

Check **Add support for MFC** to add MFC support to the new project.

Check **Add support for the Common Language Runtime** to add CLR programming support to the project. Choose the **Common Language Runtime Support** for compliance type, such as **Common Language Runtime (old syntax)** for compliance with Managed Extensions for C++ syntax, the CLR programming syntax before Visual Studio 2005. | | **Use external build system** | Specifies to use build tools that aren't included in Visual Studio for building the new project. When this option is selected, you can specify build command lines on the **Specify Debug Configuration Settings** and **Specify Release Configuration Settings** pages. | - ![Project settings](media/settings.png) + ![Create New Project from Existing Code dialog, showing Project build settings.](media/settings.png) > [!NOTE] > When the **Use External Build System** option is checked, the IDE doesn't build the project, so the /D, /I, /FI, /AI, or /FU options aren't required for compilation. However, these options must be set correctly in order for IntelliSense to function properly. @@ -53,12 +58,13 @@ Porting existing code files into a C++ project enables the use of native MSBuild | **.NET assembly search path (/AI)** | Specifies the directory paths that the compiler searches to resolve .NET assembly references passed to preprocessor directives in the project, see [/AI (Specify Metadata Directories)](../build/reference/ai-specify-metadata-directories.md). | | **Forced using .NET assemblies (/FU)** | Specifies .NET assemblies to process when building the project, see [/FU (Name Forced #using File)](../build/reference/fu-name-forced-hash-using-file.md). | - ![Project configuration](media/config.png) + ![Create New Project from Existing Code dialog, showing Debug and Release configuration settings.](media/config.png) > [!NOTE] > The **Build**, **Rebuild**, **Clean** command line, and **Output (for debugging)** settings are only enabled if the **Use external build system** option is selected on the **Specify Project Settings** page. -1. Specify the Release configuration settings to use, these settings are the same as the Debug configuration settings. Choose **Finish** to generate the new project. +1. Specify the Release configuration settings to use, these settings are the same as the Debug configuration settings. +1. Choose **Finish** to generate the new project. > [!NOTE] > Here you can check **Same as Debug configuration** to specify that the wizard will generate Release configuration project settings identical to Debug configuration project settings. This option is checked by default. All other options on this page are inactive unless you uncheck this box. diff --git a/docs/build/how-to-debug-a-release-build.md b/docs/build/how-to-debug-a-release-build.md index bb260ccf93..3063cfc32b 100644 --- a/docs/build/how-to-debug-a-release-build.md +++ b/docs/build/how-to-debug-a-release-build.md @@ -1,31 +1,27 @@ --- description: "Learn more about: How to: Debug a Release Build" title: "How to: Debug a Release Build" -ms.date: "11/04/2016" +ms.date: 03/14/2025 helpviewer_keywords: ["debugging [C++], release builds", "release builds, debugging"] -ms.assetid: d333e4d1-4e6c-4384-84a9-cb549702da25 --- # How to: Debug a Release Build -You can debug a release build of an application. +This article explains which compiler and linker switches to set to enable you to debug a release build of an application. -### To debug a release build +A better experience is available starting in Visual Studio 2022 version 17.14 that allows you to debug optimized code as if it were compiled unoptimized, while retaining the speed of optimized code. For more information, see [C++ Dynamic Debugging (Preview)](/visualstudio/debugger/cpp-dynamic-debugging). -1. Open the **Property Pages** dialog box for the project. For details, see [Set C++ compiler and build properties in Visual Studio](working-with-project-properties.md). +## To debug a release build +1. Open the **Property Pages** dialog box for the project. For details, see [Set C++ compiler and build properties in Visual Studio](working-with-project-properties.md). 1. Click the **C/C++** node. Set **Debug Information Format** to [C7 compatible (/Z7)](reference/z7-zi-zi-debug-information-format.md) or **Program Database (/Zi)**. - 1. Expand **Linker** and click the **General** node. Set **Enable Incremental Linking** to [No (/INCREMENTAL:NO)](reference/incremental-link-incrementally.md). - -1. Select the **Debugging** node. Set **Generate Debug Info** to [Yes (/DEBUG)](reference/debug-generate-debug-info.md). - -1. Select the **Optimization** node. Set **References** to [/OPT:REF](reference/opt-optimizations.md) and **Enable COMDAT Folding** to [/OPT:ICF](reference/opt-optimizations.md). - +1. Under **Linker**, select the **Debugging** node. Set **Generate Debug Info** to [Yes (/DEBUG)](reference/debug-generate-debug-info.md). +1. Under **Linker**, select the **Optimization** node. Set **References** to [No (/OPT:NOREF)](reference/opt-optimizations.md) and **Enable COMDAT Folding** to [No (/OPT:NOICF)](reference/opt-optimizations.md). 1. You can now debug your release build application. To find a problem, step through the code (or use Just-In-Time debugging) until you find where the failure occurs, and then determine the incorrect parameters or code. If an application works in a debug build, but fails in a release build, one of the compiler optimizations may be exposing a defect in the source code. To isolate the problem, disable selected optimizations for each source code file until you locate the file and the optimization that is causing the problem. (To expedite the process, you can divide the files into two groups, disable optimization on one group, and when you find a problem in a group, continue dividing until you isolate the problem file.) - You can use [/RTC](reference/rtc-run-time-error-checks.md) to try to expose such bugs in your debug builds. + Use [/RTC](reference/rtc-run-time-error-checks.md) to try to expose such bugs in your debug builds. For more information, see [Optimizing Your Code](optimizing-your-code.md). diff --git a/docs/build/how-to-embed-a-manifest-inside-a-c-cpp-application.md b/docs/build/how-to-embed-a-manifest-inside-a-c-cpp-application.md deleted file mode 100644 index cb98e6dabb..0000000000 --- a/docs/build/how-to-embed-a-manifest-inside-a-c-cpp-application.md +++ /dev/null @@ -1,254 +0,0 @@ ---- -description: "Learn more about: How to: Embed a Manifest Inside a C/C++ Application" -title: "How to: Embed a Manifest Inside a C/C++ Application" -ms.date: "05/06/2019" -helpviewer_keywords: ["manifests [C++]", "embedding manifests", "makefiles, updating to embed manifest"] -ms.assetid: ec0bac69-2fdc-466c-ab0d-710a22974e5d ---- -# How to: Embed a Manifest Inside a C/C++ Application - -We recommended that you embed the manifest of your application or library inside the final binary because this guarantees correct runtime behavior in most scenarios. By default, Visual Studio tries to embed the manifest when it builds a project. For more information, see [Manifest Generation in Visual Studio](manifest-generation-in-visual-studio.md). However, if you build your application by using nmake, you have to make some changes to the makefile. This section shows how to change the makefiles so that it automatically embeds the manifest inside the final binary. - -## Two approaches - -There are two ways to embed the manifest inside an application or library. - -- If you are not doing an incremental build you can directly embed the manifest using a command line similar to the following as a post-build step: - - ```cmd - mt.exe -manifest MyApp.exe.manifest -outputresource:MyApp.exe;1 - ``` - - or - - ```cmd - mt.exe -manifest MyLibrary.dll.manifest -outputresource:MyLibrary.dll;2 - ``` - - Use 1 for an EXE and 2 for a DLL. - -- If you are doing an incremental build, use the following steps: - - - Link the binary to generate the MyApp.exe.manifest file. - - - Convert the manifest to a resource file. - - - Re-link (incrementally) to embed the manifest resource into the binary. - -The following examples show how to change makefiles to incorporate both techniques. - -## Makefiles (Before) - -Consider the nmake script for MyApp.exe, a simple application built from one file: - -``` -# build MyApp.exe -!if "$(DEBUG)" == "1" -CPPFLAGS=$(CPPFLAGS) /MDd -LFLAGS=$(LFLAGS) /INCREMENTAL -!else -CPPFLAGS=$(CPPFLAGS) /MD -!endif - -MyApp.exe : MyApp.obj - link $** /out:$@ $(LFLAGS) - -MyApp.obj : MyApp.cpp - -clean : - del MyApp.obj MyApp.exe -``` - -If this script is run unchanged with Visual Studio, it successfully creates MyApp.exe. It also creates the external manifest file MyApp.exe.manifest, for use by the operating system to load dependent assemblies at runtime. - -The nmake script for MyLibrary.dll looks very similar: - -``` -# build MyLibrary.dll -!if "$(DEBUG)" == "1" -CPPFLAGS=$(CPPFLAGS) /MDd -LFLAGS=$(LFLAGS) /DLL /INCREMENTAL - -!else -CPPFLAGS=$(CPPFLAGS) /MD -LFLAGS=$(LFLAGS) /DLL - -!endif - -MyLibrary.dll : MyLibrary.obj - link $** /out:$@ $(LFLAGS) - -MyLibrary.obj : MyLibrary.cpp - -clean : - del MyLibrary.obj MyLibrary.dll -``` - -## Makefiles (After) - -To build with embedded manifests you have to make four small changes to the original makefiles. For the MyApp.exe makefile: - -``` -# build MyApp.exe -!include makefile.inc -#^^^^^^^^^^^^^^^^^^^^ Change #1. (Add full path if necessary.) - -!if "$(DEBUG)" == "1" -CPPFLAGS=$(CPPFLAGS) /MDd -LFLAGS=$(LFLAGS) /INCREMENTAL -!else -CPPFLAGS=$(CPPFLAGS) /MD -!endif - -MyApp.exe : MyApp.obj - link $** /out:$@ $(LFLAGS) - $(_VC_MANIFEST_EMBED_EXE) -#^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Change #2 - -MyApp.obj : MyApp.cpp - -clean : - del MyApp.obj MyApp.exe - $(_VC_MANIFEST_CLEAN) -#^^^^^^^^^^^^^^^^^^^^^^^^ Change #3 - -!include makefile.targ.inc -#^^^^^^^^^^^^^^^^^^^^^^^^^ Change #4. (Add full path if necessary.) -``` - -For the MyLibrary.dll makefile: - -``` -# build MyLibrary.dll -!include makefile.inc -#^^^^^^^^^^^^^^^^^^^^ Change #1. (Add full path if necessary.) - -!if "$(DEBUG)" == "1" -CPPFLAGS=$(CPPFLAGS) /MDd -LFLAGS=$(LFLAGS) /DLL /INCREMENTAL - -!else -CPPFLAGS=$(CPPFLAGS) /MD -LFLAGS=$(LFLAGS) /DLL - -!endif - -MyLibrary.dll : MyLibrary.obj - link $** /out:$@ $(LFLAGS) - $(_VC_MANIFEST_EMBED_DLL) -#^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Change #2. - -MyLibrary.obj : MyLibrary.cpp - -clean : - del MyLibrary.obj MyLibrary.dll - $(_VC_MANIFEST_CLEAN) -#^^^^^^^^^^^^^^^^^^^^^^^^ Change #3. - -!include makefile.targ.inc -#^^^^^^^^^^^^^^^^^^^^^^^^^ Change #4. (Add full path if necessary.) -``` - -The makefiles now include two files that do the real work, makefile.inc and makefile.targ.inc. - -Create makefile.inc and copy the following into it: - -``` -# makefile.inc -- Include this file into existing makefile at the very top. - -# _VC_MANIFEST_INC specifies whether build is incremental (1 - incremental). -# _VC_MANIFEST_BASENAME specifies name of a temporary resource file. - -!if "$(DEBUG)" == "1" -CPPFLAGS=$(CPPFLAGS) /MDd -LFLAGS=$(LFLAGS) /INCREMENTAL -_VC_MANIFEST_INC=1 -_VC_MANIFEST_BASENAME=__VC90.Debug - -!else -CPPFLAGS=$(CPPFLAGS) /MD -_VC_MANIFEST_INC=0 -_VC_MANIFEST_BASENAME=__VC90 - -!endif - -#################################################### -# Specifying name of temporary resource file used only in incremental builds: - -!if "$(_VC_MANIFEST_INC)" == "1" -_VC_MANIFEST_AUTO_RES=$(_VC_MANIFEST_BASENAME).auto.res -!else -_VC_MANIFEST_AUTO_RES= -!endif - -#################################################### -# _VC_MANIFEST_EMBED_EXE - command to embed manifest in EXE: - -!if "$(_VC_MANIFEST_INC)" == "1" - -#MT_SPECIAL_RETURN=1090650113 -#MT_SPECIAL_SWITCH=-notify_resource_update -MT_SPECIAL_RETURN=0 -MT_SPECIAL_SWITCH= -_VC_MANIFEST_EMBED_EXE= \ -if exist $@.manifest mt.exe -manifest $@.manifest -out:$(_VC_MANIFEST_BASENAME).auto.manifest $(MT_SPECIAL_SWITCH) & \ -if "%ERRORLEVEL%" == "$(MT_SPECIAL_RETURN)" \ -rc /r $(_VC_MANIFEST_BASENAME).auto.rc & \ -link $** /out:$@ $(LFLAGS) - -!else - -_VC_MANIFEST_EMBED_EXE= \ -if exist $@.manifest mt.exe -manifest $@.manifest -outputresource:$@;1 - -!endif - -#################################################### -# _VC_MANIFEST_CLEAN - command to clean resources files generated temporarily: - -!if "$(_VC_MANIFEST_INC)" == "1" - -_VC_MANIFEST_CLEAN=-del $(_VC_MANIFEST_BASENAME).auto.res \ - $(_VC_MANIFEST_BASENAME).auto.rc \ - $(_VC_MANIFEST_BASENAME).auto.manifest - -!else - -_VC_MANIFEST_CLEAN= - -!endif - -# End of makefile.inc -#################################################### -``` - -Now create **makefile.targ.inc** and copy the following into it: - -``` -# makefile.targ.inc - include this at the very bottom of the existing makefile - -#################################################### -# Commands to generate initial empty manifest file and the RC file -# that references it, and for generating the .res file: - -$(_VC_MANIFEST_BASENAME).auto.res : $(_VC_MANIFEST_BASENAME).auto.rc - -$(_VC_MANIFEST_BASENAME).auto.rc : $(_VC_MANIFEST_BASENAME).auto.manifest - type <<$@ -#include -1RT_MANIFEST"$(_VC_MANIFEST_BASENAME).auto.manifest" -<< KEEP - -$(_VC_MANIFEST_BASENAME).auto.manifest : - type <<$@ - - - -<< KEEP - -# end of makefile.targ.inc -``` - -## See also - -[Understanding Manifest Generation for C/C++ Programs](understanding-manifest-generation-for-c-cpp-programs.md) diff --git a/docs/build/how-to-enable-a-64-bit-visual-cpp-toolset-on-the-command-line.md b/docs/build/how-to-enable-a-64-bit-visual-cpp-toolset-on-the-command-line.md index d25c42ecde..4e5fb87009 100644 --- a/docs/build/how-to-enable-a-64-bit-visual-cpp-toolset-on-the-command-line.md +++ b/docs/build/how-to-enable-a-64-bit-visual-cpp-toolset-on-the-command-line.md @@ -3,7 +3,6 @@ description: "Learn more about: How to: Enable a 64-Bit, x64 hosted MSVC toolset title: "How to: Enable a 64-Bit MSVC Toolset on the Command Line" ms.date: "07/24/2019" helpviewer_keywords: ["x64 [C++]", "64-bit compiler [C++], command line usage", "64-bit compiler [C++], toolset enabling at command line", "command line [C++], 64-bit compiler", "Itanium [C++], command-line compiler", "IPF", "Itanium [C++]", "IPF, command-line compiler", "x64 [C++], command-line compiler"] -ms.assetid: 4da93a19-e20d-4778-902a-5eee9a6a90b5 --- # How to: Enable a 64-Bit, x64 hosted MSVC toolset on the command line @@ -11,11 +10,13 @@ Visual Studio includes C++ compilers, linkers, and other tools that you can use ## Use a 64-bit hosted developer command prompt shortcut -To access these command prompts on Windows 10, on the **Start** menu, open the folder for your version of Visual Studio, for example **Visual Studio 2019**, and then choose one of the x64 native or cross-tool developer command prompts. +To access these command prompts on Windows, on the **Start** menu type `x64` and then choose one of the x64 native or cross-tool developer command prompts. -![x64 Native Tools Command Prompt](media/x64-native-tools-command-prompt.png "x64 Native Tools in Start Menu") +:::image type="complex" source="./media/x64-native-tools-command-prompt.png" alt-text="Screenshot showing the start menu with x64 in the search box and the x64 Native Tools Command Prompt shortcut selected."::: +If you have different versions of Visual Studio installed, other versions of the prompt appear. Choose the prompt for the version of Visual Studio that you want to use. +:::image-end::: -To access these command prompts on Windows 8, on the **Start** screen, open **All apps**. Under the heading for the installed version of Visual Studio, open the **Visual Studio** folder (in older versions of Visual Studio, it may be named **Visual Studio Tools**). On earlier versions of Windows, choose **Start**, expand **All Programs**, the folder for your version of **Visual Studio** (and on older versions of Visual Studio, **Visual Studio Tools**). For more information, see [Developer command prompt shortcuts](building-on-the-command-line.md#developer_command_prompt_shortcuts). +On earlier versions of Windows, choose **Start**, expand **All Programs**, and then expand the folder for your version of **Visual Studio** (and on older versions of Visual Studio, **Visual Studio Tools**). For more information, see [Developer command prompt shortcuts](building-on-the-command-line.md#developer_command_prompt_shortcuts). ## Use Vcvarsall.bat to set a 64-bit hosted build architecture diff --git a/docs/build/how-to-modify-the-target-framework-and-platform-toolset.md b/docs/build/how-to-modify-the-target-framework-and-platform-toolset.md index 5b02d58d9d..a91d9d9158 100644 --- a/docs/build/how-to-modify-the-target-framework-and-platform-toolset.md +++ b/docs/build/how-to-modify-the-target-framework-and-platform-toolset.md @@ -1,7 +1,6 @@ --- description: "Learn more about: How to: Modify the Target Framework and Platform Toolset" title: "How to: Modify the Target Framework and Platform Toolset" -ms.custom: "contperf-fy21q3" ms.date: 03/31/2021 helpviewer_keywords: ["msbuild (c++), howto: modify target framework and platform toolset"] --- @@ -16,6 +15,7 @@ The platform toolset consists of the C++ compiler (cl.exe) and linker (link.exe) - Visual Studio 2015: v140 - Visual Studio 2017: v141 - Visual Studio 2019: v142 +- Visual Studio 2022: v143 These toolsets support the .NET Framework 4.5 and later. @@ -23,7 +23,7 @@ Visual Studio also supports multitargeting for C++ projects. You can use the lat ## Target framework (C++/CLI project only) -When you change the target Framework, also change the platform toolset to a version that supports that Framework. For example, to target the .NET Framework 4.5, you must use a compatible platform toolset. These toolsets include Visual Studio 2015 (v140), Visual Studio 2013 (v120), or Visual Studio 2012 (v110). You can use the [Windows 7.1 SDK](https://www.microsoft.com/download/details.aspx?id=8279) to target .NET Framework 2.0, 3.0, 3.5, and 4. +When you change the target Framework, also change the platform toolset to a version that supports that Framework. For example, to target the .NET Framework 4.5, you must use a compatible platform toolset. These toolsets include Visual Studio 2015 (v140), Visual Studio 2013 (v120), or Visual Studio 2012 (v110). You can use the [Windows 7.1 SDK](https://www.microsoft.com/en-us/download/details.aspx?id=8442) to target .NET Framework 2.0, 3.0, 3.5, and 4. You can extend the target platform further by creating a custom platform toolset. For more information, see [C++ Native Multi-Targeting](https://devblogs.microsoft.com/cppblog/c-native-multi-targeting/) on the Visual C++ blog. diff --git a/docs/build/how-to-use-build-events-in-msbuild-projects.md b/docs/build/how-to-use-build-events-in-msbuild-projects.md index c747397334..72aea3d96a 100644 --- a/docs/build/how-to-use-build-events-in-msbuild-projects.md +++ b/docs/build/how-to-use-build-events-in-msbuild-projects.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: How to: Use Build Events in MSBuild Projects" title: "How to: Use Build Events in MSBuild Projects" +description: "Learn more about: How to: Use Build Events in MSBuild Projects" ms.date: "11/04/2016" helpviewer_keywords: ["msbuild (c++), howto: use build events in projects"] -ms.assetid: 2a58dc9d-3d50-4e49-97c1-86c5a05ce218 --- # How to: Use Build Events in MSBuild Projects @@ -33,7 +32,7 @@ The following table lists each *use-in-build* element: The following example can be added inside of the Project element of the myproject.vcxproj file created in [Walkthrough: Using MSBuild to Create a C++ Project](walkthrough-using-msbuild-to-create-a-visual-cpp-project.md). A *pre-build* event makes a copy of main.cpp; a *pre-link* event makes a copy of main.obj; and a *post-build* event makes a copy of myproject.exe. If the project is built using a release configuration, the build events are executed. If the project is built using a debug configuration, the build events are not executed. -``` xml +```xml copy $(ProjectDir)main.cpp $(ProjectDir)copyOfMain.cpp @@ -64,5 +63,5 @@ The following example can be added inside of the Project element of the myprojec ## See also -[MSBuild on the command line - C++](msbuild-visual-cpp.md)
+[MSBuild on the command line - C++](msbuild-visual-cpp.md)\ [Walkthrough: Using MSBuild to Create a C++ Project](walkthrough-using-msbuild-to-create-a-visual-cpp-project.md) diff --git a/docs/build/launch-vs-schema-reference-cpp.md b/docs/build/launch-vs-schema-reference-cpp.md index 04f78ebf35..290cc1a1ce 100644 --- a/docs/build/launch-vs-schema-reference-cpp.md +++ b/docs/build/launch-vs-schema-reference-cpp.md @@ -1,104 +1,149 @@ --- title: "launch.vs.json schema reference (C++)" description: "Describes the schema elements for the `launch.vs.json` file" -ms.date: "12/02/2020" +ms.date: 07/15/2021 helpviewer_keywords: ["launch.vs.json file [C++]"] --- -# launch.vs.json schema reference (C++) +# `launch.vs.json` schema reference (C++) -Use the *launch.vs.json* file to configure debugging parameters. To create the file. right-click on an executable file in **Solution Explorer** and choose **Debug and Launch Settings**. Choose the option that most closely matches your project and then use the following properties to modify the configuration as needed. For more information on debugging CMake projects, see [Configure CMake debugging sessions](./configure-cmake-debugging-sessions.md). +In Visual Studio 2017 and later versions, you can open and build code from nearly any directory-based project without requiring a solution or project file. When there's no project or solution file, you can specify custom build tasks and launch parameters through JSON configuration files. This article describes the `launch.vs.json` file, which specifies debugging parameters. For more information about the "Open Folder" feature, see [Develop code in Visual Studio without projects or solutions](/visualstudio/ide/develop-code-in-visual-studio-without-projects-or-solutions). + +To create the file, right-click on an executable file in **Solution Explorer** and choose **Debug and Launch Settings**. Choose the option that most closely matches your project and then use the following properties to modify the configuration as needed. For more information on debugging CMake projects, see [Configure CMake debugging sessions](./configure-cmake-debugging-sessions.md). ## Default properties -|Property|Type|Description| -|-|-|-| -|`args`|array|Specifies the command-line arguments passed to the launched program.| -|`buildConfigurations`|array| A key-value pair that specifies the name of the build mode to apply the configurations. For example, `Debug` or `Release` and the configurations to use according to the selected build mode. -|`currentDir`|string|Specifies the full directory path to the Build Target. This will automatically be detected unless this parameter is set.| -|`cwd`|string|Full path to the directory on the remote system where the program will run. Defaults to `"${debugInfo.defaultWorkingDirectory}"`| -|`debugType`|string|Specifies the debugging mode according to the type of code (native, managed, or mixed). This is automatically detected unless this parameter is set. Allowed values: `"native"`", `"managed"`, `"mixed"`.| -|`env`|array| Specifies a key-value list of custom environment variables. For example: `env:{"myEnv":"myVal"}`.| -|`inheritEnvironments`|array|Specifies a set of environment variables inherited from multiple sources. You can define some variables in files like *`CMakeSettings.json`* or *`CppProperties.json`* and make them available to debug context. **Visual Studio 16.4:** Specify environment variables on a per-target basis using the `env.VARIABLE_NAME` syntax. To unset a variable, set it to `"null"`.| -|`name`|string|Specifies the name of the entry in the **Startup Item** dropdown.| -|`noDebug`|boolean|Specifies whether to debug the launched program. The default value for this parameter is **`false`** if not specified.| -|`portName`|string|Specifies the name of port when attaching to a running process.| -| `program`|string|The debug command to execute. Defaults to `"${debugInfo.fullTargetPath}"`.| -|`project`|string|Specifies the relative path to the project file. Normally, you don't need to change this value when debugging a CMake project. | -|`projectTarget`|string|Specifies the optional target invoked when building `project`. The target must match the name in the **Startup Item** dropdown.| -|`stopOnEntry`|boolean|Specifies whether to break a soon as the process is launched and the debugger attaches. The default value for this parameter is **`false`**.| -|`remoteMachine`|string|Specifies the name of the remote machine where the program is launched.| -|`type`|string|Specifies whether the project is a `dll` or `exe` Defaults to .exe| +| Property | Type | Description | +|--|--|--| +| `args` | array | Specifies the command-line arguments passed to the launched program. | +| `buildConfigurations` | array | A key-value pair that specifies the name of the build mode to apply the configurations. For example, `Debug` or `Release` and the configurations to use according to the selected build mode. | +| `currentDir` | string | Specifies the full directory path to the Build Target. The directory is detected automatically unless this parameter is set. | +| `cwd` | string | Full path to the directory on the remote system where the program will run. Defaults to `"${debugInfo.defaultWorkingDirectory}"` | +| `debugType` | string | Specifies the debugging mode according to the type of code (native, managed, or mixed). The mode is automatically detected unless this parameter is set. Allowed values: `"native"`, `"managed"`, `"mixed"`. | +| `env` | array | Specifies a key-value list of custom environment variables. For example: `env:{"myEnv":"myVal"}`. | +| `inheritEnvironments` | array | Specifies a set of environment variables inherited from multiple sources. You can define some variables in files like *`CMakeSettings.json`* or *`CppProperties.json`* and make them available to debug context. **Visual Studio 16.4:** Specify environment variables on a per-target basis using the `env.VARIABLE_NAME` syntax. To unset a variable, set it to `"null"`. | +| `name` | string | Specifies the name of the entry in the **Startup Item** dropdown. | +| `noDebug` | boolean | Specifies whether to debug the launched program. The default value for this parameter is **`false`** if not specified. | +| `portName` | string | Specifies the name of port when attaching to a running process. | +| `program` | string | The debug command to execute. Defaults to `"${debugInfo.fullTargetPath}"`. | +| `project` | string | Specifies the relative path to the project file. Normally, you don't need to change this value when debugging a CMake project. | +| `projectTarget` | string | Specifies the optional target invoked when building `project`. The target must match the name in the **Startup Item** dropdown. | +| `stopOnEntry` | boolean | Specifies whether to break a soon as the process is launched and the debugger attaches. The default value for this parameter is **`false`**. | +| `remoteMachine` | string | Specifies the name of the remote machine where the program is launched. | +| `type` | string | Specifies whether the project is a `dll` or `exe` Defaults to .exe | ## C++ Linux properties -|Property|Type|Description| -|-|-|-| -|`program`|string|Full path to program executable on the remote machine. When using CMake, the macro `${debugInfo.fullTargetPath}` can be used as the value of this field.| -|`processId`|integer|Optional process ID to attach the debugger to.| -|`sourceFileMap`|object|Optional source file mappings passed to the debug engine. Format: `{ "\": "\" }` or `{ "\": { "editorPath": "\", "useForBreakpoints": true } }`. Example: `{ "/home/user/foo": "C:\\foo" }` or `{ "/home/user/foo": { "editorPath": "c:\\foo", "useForBreakpoints": true } }`. See [Source file map options](#source_file_map_options).| -|`additionalProperties`|string|One of the sourceFileMapOptions. (See below.)| -|`MIMode`|string|Indicates the type of MI-enabled console debugger that the MIDebugEngine will connect to. Allowed values are `"gdb"`, `"lldb"`.| -|`args`|array|Command-line arguments passed to the program.| -|`environment`|array|Environment variables to add to the environment for the program. Example: `[ { "name": "squid", "value": "clam" } ]`.| -|`targetArchitecture`|string|The architecture of the debuggee. This will automatically be detected unless this parameter is set. Allowed values are `x86`, `arm`, `arm64`, `mips`, `x64`, `amd64`, `x86_64`.| -|`visualizerFile`|string|The .natvis file to be used when debugging this process. This option isn't compatible with GDB pretty printing. See `"showDisplayString"` if you use this setting.| -|`showDisplayString`|boolean|When a visualizerFile is specified, `showDisplayString` will enable the display string. Turning on this option can slow performance during debugging.| -|`remoteMachineName`|string|The remote Linux machine that hosts gdb and the program to debug. Use the Connection Manager for adding new Linux machines. When using CMake, the macro `${debugInfo.remoteMachineName}` can be used as the value of this field.| -|`miDebuggerPath`|string|The path to the MI-enabled debugger (such as gdb). When unspecified, it will search PATH first for the debugger.| -|`miDebuggerServerAddress`|string|Network address of the MI-enabled debugger server to connect to. Example: localhost:1234.| -|`setupCommands`|array|One or more GDB/LLDB commands to execute to set up the underlying debugger. Example: `"setupCommands": [ { "text": "-enable-pretty-printing", "description": "Enable GDB pretty printing", "ignoreFailures": true }]`. See [Launch setup commands](#launch_setup_commands).| -|`customLaunchSetupCommands`|array|If provided, this replaces the default commands used to launch a target with some other commands. For example, this can be "-target-attach" to attach to a target process. An empty command list replaces the launch commands with nothing, which can be useful if the debugger is being provided launch options as command-line options. Example: `"customLaunchSetupCommands": [ { "text": "target-run", "description": "run target", "ignoreFailures": false }]`.| -|`launchCompleteCommand`|string|The command to execute after the debugger is fully set up, to cause the target process to run. Allowed values are "exec-run", "exec-continue", "None". The default value is "exec-run".| -|`debugServerPath`|string|Optional full path to debug server to launch. Defaults to null.| -|`debugServerArgs`|string|Optional debug server args. Defaults to null.| -|`filterStderr`|boolean|Search stderr stream for server-started pattern and log stderr to debug output. Defaults to **`false`**.| -|`coreDumpPath`|string|Optional full path to a core dump file for the specified program. Defaults to null.| -externalConsole|boolean|If true, a console is launched for the debuggee. If **`false`**, no console is launched. The default for this setting is **`false`**. This option is ignored in some cases for technical reasons.| -|`pipeTransport`|string|When present, this tells the debugger to connect to a remote computer using another executable as a pipe that will relay standard input/output between Visual Studio and the MI-enabled debugger (such as gdb). Allowed values: one or more [Pipe Transport Options](#pipe_transport_options).| +| Property | Type | Description | +|--|--|--| +| `program` | string | Full path to program executable on the remote machine. When using CMake, the macro `${debugInfo.fullTargetPath}` can be used as the value of this field. | +| `processId` | integer | Optional process ID to attach the debugger to. | +| `sourceFileMap` | object | Optional source file mappings passed to the debug engine. Format: `{ "\": "\" }` or `{ "\": { "editorPath": "\", "useForBreakpoints": true } }`. Example: `{ "/home/user/foo": "C:\\foo" }` or `{ "/home/user/foo": { "editorPath": "c:\\foo", "useForBreakpoints": true } }`. For more information, see [Source file map options](#source_file_map_options). | +| `additionalProperties` | string | One of the sourceFileMapOptions. (See below.) | +| `MIMode` | string | Indicates the type of MI-enabled console debugger that the MIDebugEngine will connect to. Allowed values are `"gdb"`, `"lldb"`. | +| `args` | array | Command-line arguments passed to the program. | +| `environment` | array | Environment variables to add to the environment for the program. Example: `[ { "name": "squid", "value": "clam" } ]`. | +| `targetArchitecture` | string | The architecture of the debuggee. The architecture is detected automatically unless this parameter is set. Allowed values are `x86`, `arm`, `arm64`, `mips`, `x64`, `amd64`, `x86_64`. | +| `visualizerFile` | string | The .natvis file to be used when debugging this process. This option isn't compatible with GDB pretty printing. See `"showDisplayString"` if you use this setting. | +| `showDisplayString` | boolean | When a visualizerFile is specified, `showDisplayString` will enable the display string. Turning on this option can slow performance during debugging. | +| `remoteMachineName` | string | The remote Linux machine that hosts gdb and the program to debug. Use the Connection Manager for adding new Linux machines. When using CMake, the macro `${debugInfo.remoteMachineName}` can be used as the value of this field. | +| `miDebuggerPath` | string | The path to the MI-enabled debugger (such as gdb). When unspecified, it will search PATH first for the debugger. | +| `miDebuggerServerAddress` | string | Network address of the MI-enabled debugger server to connect to. Example: `"localhost:1234"`. | +| `setupCommands` | array | One or more GDB/LLDB commands to execute to set up the underlying debugger. Example: `"setupCommands": [ { "text": "-enable-pretty-printing", "description": "Enable GDB pretty printing", "ignoreFailures": true }]`. For more information, see [Launch setup commands](#launch_setup_commands). | +| `customLaunchSetupCommands` | array | If provided, this value replaces the default commands used to launch a target with some other commands. For example, use "-target-attach" to attach to a target process. An empty command list replaces the launch commands with nothing, which can be useful if the debugger is being provided launch options as command-line options. Example: `"customLaunchSetupCommands": [ { "text": "target-run", "description": "run target", "ignoreFailures": false }]`. | +| `launchCompleteCommand` | string | The command to execute after the debugger is fully set up, to cause the target process to run. Allowed values are "exec-run", "exec-continue", "None". The default value is "exec-run". | +| `debugServerPath` | string | Optional full path to debug server to launch. Defaults to null. | +| `debugServerArgs` | string | Optional debug server args. Defaults to null. | +| `filterStderr` | boolean | Search stderr stream for server-started pattern and log stderr to debug output. Defaults to **`false`**. | +| `coreDumpPath` | string | Optional full path to a core dump file for the specified program. Defaults to null. | +| `externalConsole` | boolean | If true, a console is launched for the debuggee. If **`false`**, no console is launched. The default for this setting is **`false`**. This option is ignored in some cases for technical reasons. | +| `pipeTransport` | string | When present, this value tells the debugger to connect to a remote computer using another executable as a pipe that will relay standard input/output between Visual Studio and the MI-enabled debugger (such as gdb). Allowed values: one or more [Pipe Transport Options](#pipe_transport_options). | + +## debugInfo macros + +The following macros provide information about the debugging environment. They're useful for customizing the launch of your app for debugging. + +| Macro | Description | Example | +|--|--|--| +| `addressSanitizerRuntimeFlags` | Runtime flags used to customize behavior of the address sanitizer. Used to set the environment variable `"ASAN_OPTIONS"`. | `"env": {"ASAN_OPTIONS": "${addressSanitizerRuntimeFlags}:anotherFlag=true"`} | +| `defaultWorkingDirectory` | Set to the directory part of `"fullTargetPath"`. If the CMake variable `VS_DEBUGGER_WORKING_DIRECTORY` is defined, then `defaultWorkingDirectory` is set to that value, instead. | `"cwd":"${debugInfo.defaultWorkingDirectory}"` | +| `fullTargetPath` | The full path to the binary being debugged. | `"program": "${debugInfo.fullTargetPath}"` | +| `linuxNatvisPath` | The full windows path to the VS linux `.natvis` file. Usually appears as the value `"visualizerFile"`. | | +| `parentProcessId` | The process ID for the current Visual Studio instance. Used as a parameter to shellexec. | See pipeTransport example below. | +| `remoteMachineId` | A unique, numeric identifier for the connection to the remote machine. Used as a parameter to shellexec. | See pipeTransport example below. | +| `remoteWorkspaceRoot` | Linux path to the remote copy of the workspace. | Specify file locations on the remote machine. For example: `"args": ["${debugInfo.remoteWorkspaceRoot}/Data/MyInputFile.dat"]` | +| `resolvedRemoteMachineName` | The name of the target remote machine. | `"targetMachine"` value in a deployment directive | +| `shellexecPath` | The path to the shellexec program that Visual Studio is using to manage the remote machine connection. | See pipeTransport example below | +| `tty` | gdb will redirect input and output to this device for the program being debugged. Used as a parameter to gdb (-tty). | See pipeTransport example below. | +| `windowsSubsystemPath` | The full path to the Windows Subsystem for Linux instance. | | + +The pipeTransport example below shows how to use some of the `debugInfo` macros defined above: + +```json +"pipeTransport": { + "pipeProgram": "${debugInfo.shellexecPath}", + "pipeArgs": [ + "/s", + "${debugInfo.remoteMachineId}", + "/p", + "${debugInfo.parentProcessId}", + "/c", + "${debuggerCommand}", + "--tty=${debugInfo.tty}" + ], + "pipeCmd": [ + "/s", + "${debugInfo.remoteMachineId}", + "/p", + "${debugInfo.parentProcessId}", + "/c", + "${debuggerCommand}" + ] + } +``` ## C++ Windows remote debug and deploy properties Used when debugging and deploying an app on a remote machine. -|Property|Type|Description| -|-|-|-| -|`cwd`|string|The working directory of the target on the remote machine. When using CMake, the macro `${debugInfo.defaultWorkingDirectory}` can be used as the value of this field. The default value is the directory of the debug program/command.| -|`deploy`|string|Specifies extra files or directories to deploy. For example:
`"deploy": {"sourcePath":"", "targetPath":""}` | -|`deployDirectory`|string|The location on the remote machine where project outputs are automatically deployed to. Defaults to "`C:\Windows Default Deploy Directory\`| -|`deployDebugRuntimeLibraries`|string|Specifies whether to deploy the debug runtime libraries for the active platform. Defaults to `"true"` if the active configurationType is `"Debug"`| -|`deployRuntimeLibraries`|string|Specifies whether to deploy the runtime libraries for the active platform. Defaults to `"true"` if the active configurationType is `"MinSizeRel"`, `"RelWithDebInfo"`, or `"Release"`.| -|`disableDeploy` | boolean | Specifies whether files should be deployed. | -|`remoteMachineName`|string|Specifies the name of the remote ARM64 Windows machine where the program is launched. May be the server name or the remote machine's IP address. | -|`authenticationType`|string|Specifies the type of remote connection. Possible values are `"windows"` and `"none"`. The default is `"windows"`. This should match the authentication setting specified on the remote debugger that is running on the remote machine.| +| Property | Type | Description | +|--|--|--| +| `cwd` | string | The working directory of the target on the remote machine. When using CMake, the macro `${debugInfo.defaultWorkingDirectory}` can be used as the value of this field. The default value is the directory of the debug program/command. | +| `deploy` | string | Specifies extra files or directories to deploy. For example:
`"deploy": {"sourcePath":"", "targetPath":""}` | +| `deployDirectory` | string | The location on the remote machine where project outputs are automatically deployed to. Defaults to "`C:\Windows Default Deploy Directory\` | +| `deployDebugRuntimeLibraries` | string | Specifies whether to deploy the debug runtime libraries for the active platform. Defaults to `"true"` if the active configurationType is `"Debug"` | +| `deployRuntimeLibraries` | string | Specifies whether to deploy the runtime libraries for the active platform. Defaults to `"true"` if the active configurationType is `"MinSizeRel"`, `"RelWithDebInfo"`, or `"Release"`. | +| `disableDeploy` | boolean | Specifies whether files should be deployed. | +| `remoteMachineName` | string | Specifies the name of the remote ARM64 Windows machine where the program is launched. May be the server name or the remote machine's IP address. | +| `authenticationType` | string | Specifies the type of remote connection. Possible values are `"windows"` and `"none"`. The default is `"windows"`. This value should match the authentication setting specified on the remote debugger that is running on the remote machine. | ## Launch setup commands Used with the `setupCommands` property: -|Property|Type|Description| -|-|-|-| -|`text`|string|The debugger command to execute.| -|`description`|string|Optional description for the command.| -|`ignoreFailures`|boolean|If true, failures from the command should be ignored. Defaults to **`false`**.| +| Property | Type | Description | +|--|--|--| +| `text` | string | The debugger command to execute. | +| `description` | string | Optional description for the command. | +| `ignoreFailures` | boolean | If true, failures from the command should be ignored. Defaults to **`false`**. | ## Pipe transport options Used with the `pipeTransport` property: -|Property|Type|Description| -|-|-|-| -|`pipeCwd`|string|The fully qualified path to the working directory for the pipe program.| -|`pipeProgram`|string|The fully qualified pipe command to execute.| -|`pipeArgs`|array|Command line arguments passed to the pipe program to configure the connection.| -|`debuggerPath`|string|The full path to the debugger on the target machine, for example /usr/bin/gdb.| -|`pipeEnv`|object|Environment variables passed to the pipe program.| -|`quoteArgs`|boolean|If individual arguments contain characters (such as spaces or tabs), should it be quoted? If **`false`**, the debugger command will no longer be automatically quoted. Default is **`true`**.| +| Property | Type | Description | +|--|--|--| +| `pipeCwd` | string | The fully qualified path to the working directory for the pipe program. | +| `pipeProgram` | string | The fully qualified pipe command to execute. | +| `pipeArgs` | array | Command-line arguments passed to the pipe program to configure the connection. | +| `debuggerPath` | string | The full path to the debugger on the target machine, for example /usr/bin/gdb. | +| `pipeEnv` | object | Environment variables passed to the pipe program. | +| `quoteArgs` | boolean | If individual arguments contain characters (such as spaces or tabs), should it be quoted? If **`false`**, the debugger command will no longer be automatically quoted. Default is **`true`**. | ## Source file map options Use with the `sourceFileMap` property: -|Property|Type|Description| -|-|-|-| -|`editorPath`|string|The location of the source code for the editor to locate.| -|`useForBreakpoints`|boolean|When setting breakpoints, this source mapping should be used. If **`false`**, only the filename and line number is used for setting breakpoints. If **`true`**, breakpoints will be set with the full path to the file and line number only when this source mapping is used. Otherwise just filename and line number will be used when setting breakpoints. Default is **`true`**.| +| Property | Type | Description | +|--|--|--| +| `editorPath` | string | The location of the source code for the editor to locate. | +| `useForBreakpoints` | boolean | When setting breakpoints, this source mapping should be used. If **`false`**, only the filename and line number is used for setting breakpoints. If **`true`**, breakpoints will be set with the full path to the file and line number only when this source mapping is used. Otherwise just filename and line number will be used when setting breakpoints. Default is **`true`**. | diff --git a/docs/build/manifest-generation-at-the-command-line.md b/docs/build/manifest-generation-at-the-command-line.md deleted file mode 100644 index e7acf1a1d6..0000000000 --- a/docs/build/manifest-generation-at-the-command-line.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -description: "Learn more about: Manifest Generation at the Command Line" -title: "Manifest Generation at the Command Line" -ms.date: "11/04/2016" -helpviewer_keywords: ["manifests [C++]", "manifest tool (mt.exe)"] -ms.assetid: fc2ff255-82b1-4c44-af76-8405c5850292 ---- -# Manifest Generation at the Command Line - -When building C/C++ applications from the command line using nmake or similar tools, the manifest is generated after the linker has processed all object files and built the final binary. The linker collects assembly information stored in the object files and combines this information into a final manifest file. By default the linker will generate a file named *binary_name*.*extension*.manifest to describe the final binary. The linker does not embed a manifest file inside the binary and can only generate a manifest as an external file. There are several ways to embed a manifest inside the final binary, such as using the [Manifest Tool (mt.exe)](/windows/win32/sbscs/mt-exe) or compiling the manifest into a resource file. It is important to keep in mind that specific rules have to be followed when embedding a manifest inside the final binary to enable such features as incremental linking, signing, and edit and continue. These and other options are discussed in [How to: Embed a Manifest Inside a C/C++ Application](how-to-embed-a-manifest-inside-a-c-cpp-application.md) when building on the command line. - -## See also - -[Manifests](/windows/win32/sbscs/manifests)
-[/INCREMENTAL (Link Incrementally)](reference/incremental-link-incrementally.md)
-[Strong Name Assemblies (Assembly Signing) (C++/CLI)](../dotnet/strong-name-assemblies-assembly-signing-cpp-cli.md)
-[Edit and Continue](/visualstudio/debugger/edit-and-continue)
-[Understanding Manifest Generation for C/C++ Programs](understanding-manifest-generation-for-c-cpp-programs.md)
diff --git a/docs/build/manifest-generation-in-visual-studio.md b/docs/build/manifest-generation-in-visual-studio.md deleted file mode 100644 index e8c943d4a3..0000000000 --- a/docs/build/manifest-generation-in-visual-studio.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -description: "Learn more about: Manifest Generation in Visual Studio" -title: "Manifest Generation in Visual Studio" -ms.date: "11/04/2016" -helpviewer_keywords: ["manifests [C++]"] -ms.assetid: 0af60aa9-d223-42cd-8426-b3fc543a2a81 ---- -# Manifest Generation in Visual Studio - -Generation of a manifest file for a particular project can be controlled in the project **Property Pages** dialog. On the **Configuration Properties** tab, click **Linker**, then **Manifest File**, then **Generate Manifest**. By default the project properties of new projects are set to generate a manifest file. However it is possible to disable generation of the manifest for a project using the **Generate Manifest** property of the project. When this property is set to **Yes**, the manifest for this project is generated. Otherwise the linker ignores assembly information when resolving dependencies of the application code, and does not generate the manifest. - -The build system in Visual Studio allows the manifest to be embedded in the final binary application file, or generated as an external file. This behavior is controlled by the **Embed Manifest** option in the **Project Properties** dialog. To set this property, open the **Manifest Tool** node, then select **Input and Output**. If the manifest is not embedded, it is generated as an external file and saved in the same directory as the final binary. If the manifest is embedded, Visual Studio embeds the final manifests using the following process: - -1. After the source code is compiled to object files, the linker collects dependent assembly information. While linking the final binary, the linker generates an intermediate manifest that is used later to generate the final manifest. - -1. After the intermediate manifest and linking are finished, the manifest tool will be executed to merge a final manifest and save it as an external file. - -1. The project build system then detects whether the manifest generated by the manifest tool contains different information than the manifest already embedded in the binary. - -1. If the manifest embedded in the binary is different from the manifest generated by the manifest tool, or the binary does not contain an embedded manifest, Visual Studio will invoke the linker one more time to embed the external manifest file inside the binary as a resource. - -1. If the manifest embedded in the binary is the same as the manifest generated by the manifest tool, the build will continue to the next build steps. - -The manifest is embedded inside the final binary as a text resource and it can be viewed by opening the final binary as a file in Visual Studio. To ensure that the manifest points to the correct libraries, follow the steps described in [Understanding the Dependencies of a Visual C++ Application](../windows/understanding-the-dependencies-of-a-visual-cpp-application.md) or follow the suggestions described in the [Troubleshooting](troubleshooting-c-cpp-isolated-applications-and-side-by-side-assemblies.md) section. - -## See also - -[Understanding Manifest Generation for C/C++ Programs](understanding-manifest-generation-for-c-cpp-programs.md) diff --git a/docs/build/media/add-configure-preset-to-cmakepresets.png b/docs/build/media/add-configure-preset-to-cmakepresets.png index 343e8a85ed..47d963209c 100644 Binary files a/docs/build/media/add-configure-preset-to-cmakepresets.png and b/docs/build/media/add-configure-preset-to-cmakepresets.png differ diff --git a/docs/build/media/attach-to-process.png b/docs/build/media/attach-to-process.png new file mode 100644 index 0000000000..ab965b8547 Binary files /dev/null and b/docs/build/media/attach-to-process.png differ diff --git a/docs/build/media/clang-install-vs2022.png b/docs/build/media/clang-install-vs2022.png new file mode 100644 index 0000000000..cd97b752d3 Binary files /dev/null and b/docs/build/media/clang-install-vs2022.png differ diff --git a/docs/build/media/clang-msbuild-prop-page.png b/docs/build/media/clang-msbuild-prop-page.png index a4c1c4d653..245604d11f 100644 Binary files a/docs/build/media/clang-msbuild-prop-page.png and b/docs/build/media/clang-msbuild-prop-page.png differ diff --git a/docs/build/media/cmake-build-errors.png b/docs/build/media/cmake-build-errors.png index 089db013a3..80127fdebd 100644 Binary files a/docs/build/media/cmake-build-errors.png and b/docs/build/media/cmake-build-errors.png differ diff --git a/docs/build/media/cmake-bullet3-connection-manager.png b/docs/build/media/cmake-bullet3-connection-manager.png index afdedb01e3..345ec7ec4b 100644 Binary files a/docs/build/media/cmake-bullet3-connection-manager.png and b/docs/build/media/cmake-bullet3-connection-manager.png differ diff --git a/docs/build/media/cmake-cmakelists-error.png b/docs/build/media/cmake-cmakelists-error.png index 6601ecbed3..5c0877845b 100644 Binary files a/docs/build/media/cmake-cmakelists-error.png and b/docs/build/media/cmake-cmakelists-error.png differ diff --git a/docs/build/media/cmake-cmakelists.png b/docs/build/media/cmake-cmakelists.png index f957bb6c1d..58f4729779 100644 Binary files a/docs/build/media/cmake-cmakelists.png and b/docs/build/media/cmake-cmakelists.png differ diff --git a/docs/build/media/cmake-configure-options.png b/docs/build/media/cmake-configure-options.png new file mode 100644 index 0000000000..3f8b79977d Binary files /dev/null and b/docs/build/media/cmake-configure-options.png differ diff --git a/docs/build/media/cmake-debugger-entry.png b/docs/build/media/cmake-debugger-entry.png new file mode 100644 index 0000000000..0f7eae51a2 Binary files /dev/null and b/docs/build/media/cmake-debugger-entry.png differ diff --git a/docs/build/media/cmake-find-all-refs.png b/docs/build/media/cmake-find-all-refs.png new file mode 100644 index 0000000000..2f886879b7 Binary files /dev/null and b/docs/build/media/cmake-find-all-refs.png differ diff --git a/docs/build/media/cmake-general-prefer-cmake-presets.png b/docs/build/media/cmake-general-prefer-cmake-presets.png new file mode 100644 index 0000000000..1026817075 Binary files /dev/null and b/docs/build/media/cmake-general-prefer-cmake-presets.png differ diff --git a/docs/build/media/cmake-install-2022.png b/docs/build/media/cmake-install-2022.png new file mode 100644 index 0000000000..870db48e1c Binary files /dev/null and b/docs/build/media/cmake-install-2022.png differ diff --git a/docs/build/media/cmake-project-manipulation.png b/docs/build/media/cmake-project-manipulation.png new file mode 100644 index 0000000000..a82c94d608 Binary files /dev/null and b/docs/build/media/cmake-project-manipulation.png differ diff --git a/docs/build/media/cmake-select-a-debugger.png b/docs/build/media/cmake-select-a-debugger.png index 3efa18ca0e..ac9f31e613 100644 Binary files a/docs/build/media/cmake-select-a-debugger.png and b/docs/build/media/cmake-select-a-debugger.png differ diff --git a/docs/build/media/cmake-targets-view.png b/docs/build/media/cmake-targets-view.png index f756047205..ac9dab9002 100644 Binary files a/docs/build/media/cmake-targets-view.png and b/docs/build/media/cmake-targets-view.png differ diff --git a/docs/build/media/cmake-targets-view2.png b/docs/build/media/cmake-targets-view2.png index 04ae1e2a13..673ddd555b 100644 Binary files a/docs/build/media/cmake-targets-view2.png and b/docs/build/media/cmake-targets-view2.png differ diff --git a/docs/build/media/create-from-existing-code-wizard.png b/docs/build/media/create-from-existing-code-wizard.png new file mode 100644 index 0000000000..881cbe8a36 Binary files /dev/null and b/docs/build/media/create-from-existing-code-wizard.png differ diff --git a/docs/build/media/debug-target.png b/docs/build/media/debug-target.png new file mode 100644 index 0000000000..f02a5e62a1 Binary files /dev/null and b/docs/build/media/debug-target.png differ diff --git a/docs/build/media/debug-targets-view.png b/docs/build/media/debug-targets-view.png new file mode 100644 index 0000000000..a9ba70b3c5 Binary files /dev/null and b/docs/build/media/debug-targets-view.png differ diff --git a/docs/build/media/desktop-app-project-run-150.gif b/docs/build/media/desktop-app-project-run-150.gif deleted file mode 100644 index a46faeb947..0000000000 Binary files a/docs/build/media/desktop-app-project-run-150.gif and /dev/null differ diff --git a/docs/build/media/enable-cmakepresets-new.png b/docs/build/media/enable-cmakepresets-new.png new file mode 100644 index 0000000000..52ede6453c Binary files /dev/null and b/docs/build/media/enable-cmakepresets-new.png differ diff --git a/docs/build/media/llvm-msbuild-prop-page.png b/docs/build/media/llvm-msbuild-prop-page.png new file mode 100644 index 0000000000..8b834b3ea8 Binary files /dev/null and b/docs/build/media/llvm-msbuild-prop-page.png differ diff --git a/docs/build/media/new-dropdowns.png b/docs/build/media/new-dropdowns.png new file mode 100644 index 0000000000..47a83973c6 Binary files /dev/null and b/docs/build/media/new-dropdowns.png differ diff --git a/docs/build/media/start-window.png b/docs/build/media/start-window.png new file mode 100644 index 0000000000..9974c9643c Binary files /dev/null and b/docs/build/media/start-window.png differ diff --git a/docs/build/media/switch-to-targets-view.png b/docs/build/media/switch-to-targets-view.png new file mode 100644 index 0000000000..455bbfebc9 Binary files /dev/null and b/docs/build/media/switch-to-targets-view.png differ diff --git a/docs/build/media/vcppdir_libdir_macros.png b/docs/build/media/vcppdir_libdir_macros.png index 430fd309e7..80f0d633ed 100644 Binary files a/docs/build/media/vcppdir_libdir_macros.png and b/docs/build/media/vcppdir_libdir_macros.png differ diff --git a/docs/build/media/visual-c---project-defaults.png b/docs/build/media/visual-c---project-defaults.png index 3b3db949ce..659946ac9c 100644 Binary files a/docs/build/media/visual-c---project-defaults.png and b/docs/build/media/visual-c---project-defaults.png differ diff --git a/docs/build/media/visual-c---property-pages-showing-active-configuration.png b/docs/build/media/visual-c---property-pages-showing-active-configuration.png index 57e12a4419..521ba2fec9 100644 Binary files a/docs/build/media/visual-c---property-pages-showing-active-configuration.png and b/docs/build/media/visual-c---property-pages-showing-active-configuration.png differ diff --git a/docs/build/media/visual-c---property-pages-showing-release-config.png b/docs/build/media/visual-c---property-pages-showing-release-config.png index 763a22945a..39ff39170d 100644 Binary files a/docs/build/media/visual-c---property-pages-showing-release-config.png and b/docs/build/media/visual-c---property-pages-showing-release-config.png differ diff --git a/docs/build/media/vs-debug-dropdown-menu-cmake.png b/docs/build/media/vs-debug-dropdown-menu-cmake.png new file mode 100644 index 0000000000..48098b24b4 Binary files /dev/null and b/docs/build/media/vs-debug-dropdown-menu-cmake.png differ diff --git a/docs/build/media/vs-output-window-cmake-generation.png b/docs/build/media/vs-output-window-cmake-generation.png new file mode 100644 index 0000000000..542c8a92c6 Binary files /dev/null and b/docs/build/media/vs-output-window-cmake-generation.png differ diff --git a/docs/build/media/vs2019-scan-module-dependencies.png b/docs/build/media/vs2019-scan-module-dependencies.png index 5b207ea85c..8541eff487 100644 Binary files a/docs/build/media/vs2019-scan-module-dependencies.png and b/docs/build/media/vs2019-scan-module-dependencies.png differ diff --git a/docs/build/media/vs2022-ActivePresetDropdown.png b/docs/build/media/vs2022-ActivePresetDropdown.png new file mode 100644 index 0000000000..eaea813808 Binary files /dev/null and b/docs/build/media/vs2022-ActivePresetDropdown.png differ diff --git a/docs/build/media/vs2022-get-started.png b/docs/build/media/vs2022-get-started.png new file mode 100644 index 0000000000..81ec95e8c4 Binary files /dev/null and b/docs/build/media/vs2022-get-started.png differ diff --git a/docs/build/media/vs2022-project-configure.png b/docs/build/media/vs2022-project-configure.png new file mode 100644 index 0000000000..93b9bd180e Binary files /dev/null and b/docs/build/media/vs2022-project-configure.png differ diff --git a/docs/build/media/vs2022-supported-cmake-not-present-prompt.png b/docs/build/media/vs2022-supported-cmake-not-present-prompt.png new file mode 100644 index 0000000000..33a3e4db38 Binary files /dev/null and b/docs/build/media/vs2022-supported-cmake-not-present-prompt.png differ diff --git a/docs/build/media/vs2022-target-system-dropdown.png b/docs/build/media/vs2022-target-system-dropdown.png new file mode 100644 index 0000000000..8d146e5940 Binary files /dev/null and b/docs/build/media/vs2022-target-system-dropdown.png differ diff --git a/docs/build/media/vscpp-quickstart-first-run.gif b/docs/build/media/vscpp-quickstart-first-run.gif deleted file mode 100644 index 10d887cbcb..0000000000 Binary files a/docs/build/media/vscpp-quickstart-first-run.gif and /dev/null differ diff --git a/docs/build/media/walkthrough-build-debug-wsl2-breakpoint.png b/docs/build/media/walkthrough-build-debug-wsl2-breakpoint.png new file mode 100644 index 0000000000..54cf3dd4c1 Binary files /dev/null and b/docs/build/media/walkthrough-build-debug-wsl2-breakpoint.png differ diff --git a/docs/build/media/wsl-platform-toolset-selection.png b/docs/build/media/wsl-platform-toolset-selection.png new file mode 100644 index 0000000000..bc392e8b04 Binary files /dev/null and b/docs/build/media/wsl-platform-toolset-selection.png differ diff --git a/docs/build/media/x64-native-tools-command-prompt.png b/docs/build/media/x64-native-tools-command-prompt.png index ac088d3aa2..bc48f40b7a 100644 Binary files a/docs/build/media/x64-native-tools-command-prompt.png and b/docs/build/media/x64-native-tools-command-prompt.png differ diff --git a/docs/build/modify-project-properties-without-changing-project-file.md b/docs/build/modify-project-properties-without-changing-project-file.md index 55a167526f..aebbc2c0f7 100644 --- a/docs/build/modify-project-properties-without-changing-project-file.md +++ b/docs/build/modify-project-properties-without-changing-project-file.md @@ -1,7 +1,7 @@ --- description: "Learn more about: How to: Modify C++ project properties and targets without changing the project file" title: "How to: Modify C++ project properties and targets without changing the project file" -ms.date: "11/28/2018" +ms.date: "7/28/2023" helpviewer_keywords: ["project properties [C++], modifying outside project file"] --- # How to: Modify C++ project properties and targets without changing the project file @@ -13,27 +13,27 @@ You can override project properties and targets from the MSBuild command prompt *To override project properties:* -1. Create a .props file that specifies the properties you want to override. +1. Create a `.props` file that specifies the properties you want to override. -1. From the command prompt: set ForceImportBeforeCppTargets="C:\sources\my_props.props" +1. From the command prompt: `set ForceImportBeforeCppTargets="C:\sources\my_props.props"` *To override project targets:* -1. Create a .targets file with their implementation or a particular target +1. Create a `.targets` file with their implementation or a particular target -2. From the command prompt: set ForceImportAfterCppTargets ="C:\sources\my_target.targets" +2. From the command prompt: `set ForceImportAfterCppTargets ="C:\sources\my_target.targets"` -You can also set either option on the msbuild command line by using the /p: option: +You can also set either option on the msbuild command line by using the `/p:` option: ```cmd -> msbuild myproject.sln /p:ForceImportBeforeCppTargets="C:\sources\my_props.props" -> msbuild myproject.sln /p:ForceImportAfterCppTargets="C:\sources\my_target.targets" +msbuild myproject.sln /p:ForceImportBeforeCppTargets="C:\sources\my_props.props" +msbuild myproject.sln /p:ForceImportAfterCppTargets="C:\sources\my_target.targets" ``` -Overriding properties and targets in this way is equivalent to adding the following imports to all .vcxproj files in the solution: +Overriding properties and targets in this way is equivalent to adding the following imports to all `.vcxproj` files in the solution: -```cmd - +```xml + - + ``` diff --git a/docs/build/mutual-imports.md b/docs/build/mutual-imports.md index 8dea060de9..47743d4ff1 100644 --- a/docs/build/mutual-imports.md +++ b/docs/build/mutual-imports.md @@ -25,7 +25,7 @@ The general solution for handling mutual imports is: The following illustration shows a solution for two mutually importing DLLs, DLL1 and DLL2. Step 1 is to run LIB, with the /DEF option set, on DLL1. Step 1 produces DLL1.lib, an import library, and DLL1.exp. In step 2, the import library is used to build DLL2, which in turn produces an import library for DLL2's symbols. Step 3 builds DLL1, by using DLL1.exp and DLL2.lib as input. Note that an .exp file for DLL2 is not necessary because LIB was not used to build DLL2's import library. -![Using mutual imports to link two DLLs](media/vc37yj1.gif "Using mutual imports to link two DLLs")
+![Diagram that shows the inputs and outputs when you use mutual imports to link two DLLs.](media/vc37yj1.gif "Using mutual imports to link two DLLs")
Linking Two DLLs with Mutual Imports ## Limitations of _AFXEXT diff --git a/docs/build/open-folder-projects-cpp.md b/docs/build/open-folder-projects-cpp.md index 139285105e..dff693a632 100644 --- a/docs/build/open-folder-projects-cpp.md +++ b/docs/build/open-folder-projects-cpp.md @@ -35,11 +35,11 @@ To use the Visual Studio IDE with a build system or compiler toolset that is not For IntelliSense and browsing behavior such as **Go to Definition** to work correctly, Visual Studio needs to know which compiler you are using, where the system headers are, and where any additional include files are located if they are not directly in the folder you have opened (the workspace folder). To specify a configuration, you can choose **Manage Configurations** from the dropdown in the main toolbar: -![Manage configurations dropdown](media/manage-configurations-dropdown.png) +![Configuration dropdown on the toolbar showing the Manage configurations selection.](media/manage-configurations-dropdown.png) Visual Studio offers the following default configurations: -![Default configurations](media/default-configurations.png) +![Add Configuration to CppProperties dialog, showing list of Default configurations: x86-Debug, x86-Release, x64-Debug, x64-Release, and so on.](media/default-configurations.png) If, for example, you choose **x64-Debug**, Visual Studio creates a file called *CppProperties.json* in your root project folder: @@ -74,7 +74,7 @@ This configuration inherits the environment variables of the Visual Studio [x64 ## Default configuration for MinGW-w64 -If you add the MinGW-W64 configuration, the JSON looks this this: +If you add the MinGW-W64 configuration, the JSON looks this: ```json { @@ -111,13 +111,13 @@ The `intelliSenseMode` property is set to a value appropriate for GCC. For more When everything is working correctly, you will see IntelliSense from the GCC headers when you hover over a type: -![GCC IntelliSense](media/gcc-intellisense.png) +![Screenshot of a GCC IntelliSense pop-up showing the header documentation.](media/gcc-intellisense.png) ## Enable IntelliSense diagnostics If you are not seeing the IntelliSense that you expect, you can troubleshoot by going to **Tools** > **Options** > **Text Editor** > **C/C++** > **Advanced** and setting **Enable Logging** to **`true`**. To start with, try setting **Logging Level** to 5, and **Logging Filters** to 8. -![Diagnostic logging](media/diagnostic-logging.png) +![Options dialog, showing the Diagnostic logging settings.](media/diagnostic-logging.png) Output is piped to the **Output Window** and is visible when you choose **Show Output From: Visual C++ Log*. The output contains, among other things, the list of actual include paths that IntelliSense is trying to use. If the paths do not match the ones in *CppProperties.json*, try closing the folder and deleting the *.vs* subfolder which contains cached browsing data. @@ -125,7 +125,7 @@ Output is piped to the **Output Window** and is visible when you choose **Show O You can automate build scripts or any other external operations on the files you have in your current workspace by running them as tasks directly in the IDE. You can configure a new task by right-clicking on a file or folder and selecting **Configure Tasks**. -![Open Folder Configure Tasks](media/configure-tasks.png) +![Solution Explorer shortcut menu showing the Configure Tasks command.](media/configure-tasks.png) This creates (or opens) the *tasks.vs.json* file in the .vs folder which Visual Studio creates in your root project folder. You can define any arbitrary task in this file and then invoke it from the **Solution Explorer** context menu. To continue the GCC example, the following snippet shows a complete *tasks.vs.json* file with as single task that invokes *g++.exe* to build a project. Assume the project contains a single file called *hello.cpp*. @@ -147,7 +147,6 @@ This creates (or opens) the *tasks.vs.json* file in the .vs folder which Visual } ] } - ``` The JSON file is placed in the *.vs* subfolder. To see that folder, click on the **Show All Files** button at the top of **Solution Explorer**. You can run this task by right-clicking on the root node in **Solution Explorer** and choosing **build hello**. When the task completes you should see a new file, *hello.exe* in **Solution Explorer**. @@ -194,12 +193,11 @@ To customize your program's command line arguments and debugging instructions, r } ] } - ``` To start debugging, choose the executable in the debug dropdown, then click the green arrow: -![Launch debugger](media/launch-debugger-gdb.png) +![Toolbar debug target dropdown, showing the green arrow to start the debugger.](media/launch-debugger-gdb.png) You should see the **Initializing Debugger** dialog and then an external console window that is running your program. diff --git a/docs/build/optimization-best-practices.md b/docs/build/optimization-best-practices.md index e4ea65279d..ce428f701b 100644 --- a/docs/build/optimization-best-practices.md +++ b/docs/build/optimization-best-practices.md @@ -94,8 +94,6 @@ A pointer that is modified with **`__restrict`** is referred to as a *__restrict **`__restrict`** can be a powerful tool for the Microsoft C++ optimizer, but use it with great care. If used improperly, the optimizer might perform an optimization that would break your application. -The **`__restrict`** keyword replaces the **/Oa** switch from previous versions. - With **`__assume`**, a developer can tell the compiler to make assumptions about the value of some variable. For example `__assume(a < 5);` tells the optimizer that at that line of code the variable `a` is less than 5. Again this is a promise to the compiler. If `a` is actually 6 at this point in the program then the behavior of the program after the compiler has optimized may not be what you would expect. **`__assume`** is most useful prior to switch statements and/or conditional expressions. diff --git a/docs/build/optimizing-your-code.md b/docs/build/optimizing-your-code.md index 3ec610bace..a30267f382 100644 --- a/docs/build/optimizing-your-code.md +++ b/docs/build/optimizing-your-code.md @@ -69,7 +69,7 @@ The following topics provide information about how to optimize building, loading - [Specifying Compiler Optimization for an ATL Project](../atl/reference/specifying-compiler-optimization-for-an-atl-project.md) -- [What optimization techniques should I use to improve the client application's performance when loading?](../build/dll-frequently-asked-questions.md#mfc_optimization) +- [What optimization techniques should I use to improve the client application's performance when loading?](../build/dll-frequently-asked-questions.yml#what-optimization-techniques-should-i-use-to-improve-the-client-application-s-performance-when-loading-) ## In this section diff --git a/docs/build/overview-of-arm-abi-conventions.md b/docs/build/overview-of-arm-abi-conventions.md index 30cbe4766d..3e61981e84 100644 --- a/docs/build/overview-of-arm-abi-conventions.md +++ b/docs/build/overview-of-arm-abi-conventions.md @@ -6,25 +6,25 @@ ms.assetid: 23f4ae8c-3148-4657-8c47-e933a9f387de --- # Overview of ARM32 ABI Conventions -The application binary interface (ABI) for code compiled for Windows on ARM processors is based on the standard ARM EABI. This article highlights key differences between Windows on ARM and the standard. This document covers the ARM32 ABI. For information about the ARM64 ABI, see [Overview of ARM64 ABI conventions](arm64-windows-abi-conventions.md). For more information about the standard ARM EABI, see [Application Binary Interface (ABI) for the ARM Architecture](http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.subset.swdev.abi/index.html) (external link). +The application binary interface (ABI) for code compiled for Windows on ARM processors is based on the standard ARM EABI. This article highlights key differences between Windows on ARM and the standard. This document covers the ARM32 ABI. For information about the ARM64 ABI, see [Overview of ARM64 ABI conventions](arm64-windows-abi-conventions.md). For more information about the standard ARM EABI, see [Application Binary Interface (ABI) for the ARM Architecture](https://github.com/ARM-software/abi-aa) (external link). ## Base Requirements -Windows on ARM presumes that it is running on an ARMv7 architecture at all times. Floating-point support in the form of VFPv3-D32 or later must be present in hardware. The VFP must support both single-precision and double-precision floating-point in hardware. The Windows runtime does not support emulation of floating-point to enable running on non-VFP hardware. +Windows on ARM always presumes that it's running on an ARMv7 architecture. Floating-point support in the form of VFPv3-D32 or later must be present in hardware. The VFP must support both single-precision and double-precision floating-point in hardware. The Windows runtime doesn't support emulation of floating-point to enable running on non-VFP hardware. -Advanced SIMD Extensions (NEON) support—this includes both integer and floating-point operations—must also be present in hardware. No run-time support for emulation is provided. +Advanced SIMD Extensions (NEON) support, including both integer and floating-point operations, must also be present in hardware. No run-time support for emulation is provided. -Integer divide support (UDIV/SDIV) is strongly recommended but not required. Platforms that lack integer divide support may incur a performance penalty because these operations have to be trapped and possibly patched. +Integer divide support (UDIV/SDIV) is recommended but not required. Platforms that lack integer divide support may incur a performance penalty because these operations have to be trapped and possibly patched. ## Endianness -Windows on ARM executes in little-endian mode. Both the MSVC compiler and the Windows runtime expect little-endian data at all times. Although the SETEND instruction in the ARM instruction set architecture (ISA) allows even user-mode code to change the current endianness, doing so is discouraged because it's dangerous for an application. If an exception is generated in big-endian mode, the behavior is unpredictable and may lead to an application fault in user mode, or a bugcheck in kernel mode. +Windows on ARM executes in little-endian mode. Both the MSVC compiler and the Windows runtime always expect little-endian data. The SETEND instruction in the ARM instruction set architecture (ISA) allows even user-mode code to change the current endianness. However, doing so is discouraged because it's dangerous for an application. If an exception is generated in big-endian mode, the behavior is unpredictable. It may lead to an application fault in user mode, or a bugcheck in kernel mode. ## Alignment Although Windows enables the ARM hardware to handle misaligned integer accesses transparently, alignment faults still may be generated in some situations. Follow these rules for alignment: -- Half-word-sized (16-bit) and word-sized (32-bit) integer loads and stores do not have to be aligned. The hardware handles them efficiently and transparently. +- You don't have to align half-word-sized (16-bit) and word-sized (32-bit) integer loads and stores. The hardware handles them efficiently and transparently. - Floating-point loads and stores should be aligned. The kernel handles unaligned loads and stores transparently, but with significant overhead. @@ -34,37 +34,13 @@ Although Windows enables the ARM hardware to handle misaligned integer accesses ## Instruction Set -The instruction set for Windows on ARM is strictly limited to Thumb-2. All code executed on this platform is expected to start and remain in Thumb mode at all times. An attempt to switch into the legacy ARM instruction set may succeed, but if it does, any exceptions or interrupts that occur may lead to an application fault in user mode, or a bugcheck in kernel mode. +The instruction set for Windows on ARM is strictly limited to Thumb-2. All code executed on this platform is expected to start and always remain in Thumb mode. An attempt to switch into the legacy ARM instruction set may succeed. However, if it does, any exceptions or interrupts that occur may lead to an application fault in user mode, or a bugcheck in kernel mode. -A side-effect of this requirement is that all code pointers must have the low bit set. This is so that when they are loaded and branched to via BLX or BX, the processor will remain in Thumb mode and not try to execute the target code as 32-bit ARM instructions. - -### IT Instructions - -The use of IT instructions in Thumb-2 code is disallowed except for these specific cases: - -- The IT instruction can only be used to modify one target instruction. - -- The target instruction must be a 16-bit instruction. - -- The target instruction must be one of these: - - |16-Bit Opcodes|Class|Restrictions| - |---------------------|-----------|------------------| - |MOV, MVN|Move|Rm != PC, Rd != PC| - |LDR, LDR[S]B, LDR[S]H|Load from memory|But not LDR literal forms| - |STR, STRB, STRH|Store to memory|| - |ADD, ADC, RSB, SBC, SUB|Add or subtract|But not ADD/SUB SP, SP, imm7 forms

Rm != PC, Rdn != PC, Rdm != PC| - |CMP, CMN|Compare|Rm != PC, Rn != PC| - |MUL|Multiply|| - |ASR, LSL, LSR, ROR|Bit shift|| - |AND, BIC, EOR, ORR, TST|Bitwise arithmetic|| - |BX|Branch to register|Rm != PC| - -Although current ARMv7 CPUs cannot report the use of disallowed instruction forms, future generations are expected to. If these forms are detected, any program that uses them may be terminated with an undefined instruction exception. +A side-effect of this requirement is that all code pointers must have the low bit set. Then, when they're loaded and branched to via BLX or BX, the processor remains in Thumb mode. It doesn't try to execute the target code as 32-bit ARM instructions. ### SDIV/UDIV instructions -The use of integer divide instructions SDIV and UDIV is fully supported, even on platforms without native hardware to handle them. The overhead per SDIV or UDIV divide on a Cortex-A9 processor is approximately 80 cycles, in addition to the overall divide time of 20-250 cycles, depending on the inputs. +The use of integer divide instructions SDIV and UDIV is fully supported, even on platforms without native hardware to handle them. The extra overhead per SDIV or UDIV divide on a Cortex-A9 processor is approximately 80 cycles. That's added to the overall divide time of 20-250 cycles, depending on the inputs. ## Integer registers @@ -91,11 +67,11 @@ The ARM processor supports 16 integer registers: For details about how to use the parameter and return value registers, see the Parameter Passing section in this article. -Windows uses r11 for fast-walking of the stack frame. For more information, see the Stack Walking section. Because of this requirement, r11 must point to the topmost link in the chain at all times. Do not use r11 for general purposes—your code will not generate correct stack walks during analysis. +Windows uses r11 for fast-walking of the stack frame. For more information, see the Stack Walking section. Because of this requirement, r11 must always point to the topmost link in the chain. Don't use r11 for general purposes, because your code won't generate correct stack walks during analysis. ## VFP registers -Windows only supports ARM variants that have VFPv3-D32 coprocessor support. This means that floating-point registers are always present and can be relied on for parameter passing, and that the full set of 32 registers is available for use. The VFP registers and their usage are summarized in this table: +Windows only supports ARM variants that have VFPv3-D32 coprocessor support. It means floating-point registers are always present and can be relied on for parameter passing. And, the full set of 32 registers is available for use. The VFP registers and their usage are summarized in this table: |Singles|Doubles|Quads|Volatile?|Role| |-------------|-------------|-----------|---------------|----------| @@ -121,16 +97,16 @@ The next table illustrates the floating-point status and control register (FPSCR |23-22|RMode|Non-volatile|Rounding mode control| |21-20|Stride|Non-volatile|Vector Stride, must always be 0| |18-16|Len|Non-volatile|Vector Length, must always be 0| -|15, 12-8|IDE, IXE, etc.|Non-volatile|Exception trap enable bits, must always be 0| -|7, 4-0|IDC, IXC, etc.|Volatile|Cumulative exception flags| +|15, 12-8|IDE, IXE, and so on|Non-volatile|Exception trap enable bits, must always be 0| +|7, 4-0|IDC, IXC, and so on|Volatile|Cumulative exception flags| ## Floating-point exceptions -Most ARM hardware does not support IEEE floating-point exceptions. On processor variants that do have hardware floating-point exceptions, the Windows kernel silently catches the exceptions and implicitly disables them in the FPSCR register. This ensures normalized behavior across processor variants. Otherwise, code developed on a platform that doesn't have exception support could receive unexpected exceptions when it's running on a platform that has exception support. +Most ARM hardware doesn't support IEEE floating-point exceptions. On processor variants that do have hardware floating-point exceptions, the Windows kernel silently catches the exceptions and implicitly disables them in the FPSCR register. This action ensures normalized behavior across processor variants. Otherwise, code developed on a platform that doesn't have exception support could receive unexpected exceptions when it's running on a platform that does have exception support. ## Parameter passing -For non-variadic functions, the Windows on ARM ABI follows the ARM rules for parameter passing—this includes the VFP and Advanced SIMD extensions. These rules follow the [Procedure Call Standard for the ARM Architecture](http://infocenter.arm.com/help/topic/com.arm.doc.ihi0042c/IHI0042C_aapcs.pdf), consolidated with the VFP extensions. By default, the first four integer arguments and up to eight floating-point or vector arguments are passed in registers, and additional arguments are passed on the stack. Arguments are assigned to registers or the stack by using this procedure: +The Windows on ARM ABI follows the ARM rules for parameter passing for non-variadic functions. The ABI rules include the VFP and Advanced SIMD extensions. These rules follow the [Procedure Call Standard for the ARM Architecture](https://developer.arm.com/documentation/ihi0042/latest/), combined with the VFP extensions. By default, the first four integer arguments and up to eight floating-point or vector arguments are passed in registers. Any further arguments are passed on the stack. Arguments are assigned to registers or the stack by using this procedure: ### Stage A: Initialization @@ -166,27 +142,27 @@ For each argument in the list, the following rules are applied in turn until the 1. If the size of the argument in 32-bit words is not more than r4 minus NCRN, the argument is copied into core registers, starting at the NCRN, with the least significant bits occupying the lower-numbered registers. The NCRN is incremented by the number of registers used. -1. If the NCRN is less than r4 and the NSAA is equal to the SP, the argument is split between core registers and the stack. The first part of the argument is copied into the core registers, starting at the NCRN, up to and including r3. The remainder of the argument is copied onto the stack, starting at the NSAA. The NCRN is set to r4 and the NSAA is incremented by the size of the argument minus the amount passed in registers. +1. If the NCRN is less than r4 and the NSAA is equal to the SP, the argument is split between core registers and the stack. The first part of the argument is copied into the core registers, starting at the NCRN, up to and including r3. The rest of the argument is copied onto the stack, starting at the NSAA. The NCRN is set to r4 and the NSAA is incremented by the size of the argument minus the amount passed in registers. 1. If the argument requires 8-byte alignment, the NSAA is rounded up to the next 8-byte aligned address. 1. The argument is copied into memory at the NSAA. The NSAA is incremented by the size of the argument. -The VFP registers are not used for variadic functions, and Stage C rules 1 and 2 are ignored. This means that a variadic function can begin with an optional push {r0-r3} to prepend the register arguments to any additional arguments passed by the caller, and then access the entire argument list directly from the stack. +The VFP registers aren't used for variadic functions, and Stage C rules 1 and 2 are ignored. It means that a variadic function can begin with an optional push {r0-r3} to prepend the register arguments to any additional arguments passed by the caller, and then access the entire argument list directly from the stack. Integer type values are returned in r0, optionally extended to r1 for 64-bit return values. VFP/NEON floating-point or SIMD type values are returned in s0, d0, or q0, as appropriate. ## Stack -The stack must remain 4-byte aligned at all times, and must be 8-byte aligned at any function boundary. This is required to support the frequent use of interlocked operations on 64-bit stack variables. The ARM EABI states that the stack is 8-byte aligned at any public interface. For consistency, the Windows on ARM ABI considers any function boundary to be a public interface. +The stack must always remain 4-byte aligned, and must be 8-byte aligned at any function boundary. It's required to support the frequent use of interlocked operations on 64-bit stack variables. The ARM EABI states that the stack is 8-byte aligned at any public interface. For consistency, the Windows on ARM ABI considers any function boundary to be a public interface. -Functions that have to use a frame pointer—for example, functions that call `alloca` or that change the stack pointer dynamically—must set up the frame pointer in r11 in the function prologue and leave it unchanged until the epilogue. Functions that do not require a frame pointer must perform all stack updates in the prologue and leave the stack pointer unchanged until the epilogue. +Functions that have to use a frame pointer—for example, functions that call `alloca` or that change the stack pointer dynamically—must set up the frame pointer in r11 in the function prologue and leave it unchanged until the epilogue. Functions that don't require a frame pointer must perform all stack updates in the prologue and leave the stack pointer unchanged until the epilogue. -Functions that allocate 4 KB or more on the stack must ensure that each page prior to the final page is touched in order. This ensures that no code can "leap over" the guard pages that Windows uses to expand the stack. Typically, this is done by the `__chkstk` helper, which is passed the total stack allocation in bytes divided by 4 in r4, and which returns the final stack allocation amount in bytes back in r4. +Functions that allocate 4 KB or more on the stack must ensure that each page prior to the final page is touched in order. This order ensures that no code can "leap over" the guard pages that Windows uses to expand the stack. Typically, the expansion is done by the `__chkstk` helper, which is passed the total stack allocation in bytes divided by 4 in r4, and which returns the final stack allocation amount in bytes back in r4. ### Red zone -The 8-byte area immediately below the current stack pointer is reserved for analysis and dynamic patching. This permits carefully generated code to be inserted, which stores 2 registers at [sp, #-8] and temporarily uses them for arbitrary purposes. The Windows kernel guarantees that those 8 bytes will not be overwritten if an exception or interrupt occurs in both user mode and kernel mode. +The 8-byte area immediately below the current stack pointer is reserved for analysis and dynamic patching. It permits carefully generated code to be inserted, which stores 2 registers at `[sp, #-8]` and temporarily uses them for arbitrary purposes. The Windows kernel guarantees that those 8 bytes won't be overwritten if an exception or interrupt occurs in both user mode and kernel mode. ### Kernel stack @@ -206,7 +182,7 @@ Windows code is compiled with frame pointers enabled ([/Oy (Frame-Pointer Omissi Stack unwinding during exception handling is enabled by the use of unwind codes. The unwind codes are a sequence of bytes stored in the .xdata section of the executable image. They describe the operation of the function prologue and epilogue code in an abstract manner, so that the effects of a function's prologue can be undone in preparation for unwinding to the caller's stack frame. -The ARM EABI specifies an exception unwinding model that uses unwind codes. However, this specification is not sufficient for unwinding in Windows, which must handle cases where the processor is in the middle of the prologue or epilogue of a function. For more information about Windows on ARM exception data and unwinding, see [ARM Exception Handling](arm-exception-handling.md). +The ARM EABI specifies an exception unwinding model that uses unwind codes. However, this specification isn't sufficient for unwinding in Windows, which must handle cases where the processor is in the middle of the prologue or epilogue of a function. For more information about Windows on ARM exception data and unwinding, see [ARM Exception Handling](arm-exception-handling.md). We recommend that dynamically generated code be described by using dynamic function tables specified in calls to `RtlAddFunctionTable` and associated functions, so that the generated code can participate in exception handling. diff --git a/docs/build/profile-guided-optimizations.md b/docs/build/profile-guided-optimizations.md index 4c6cdc579d..065565ef0d 100644 --- a/docs/build/profile-guided-optimizations.md +++ b/docs/build/profile-guided-optimizations.md @@ -9,7 +9,7 @@ ms.assetid: 2225c307-d3ae-42c1-8345-a5a959d132dc Profile-guided optimization (PGO) lets you optimize a whole executable file, where the optimizer uses data from test runs of the .exe or .dll file. The data represents the likely performance of the program in a production environment. -Profile-guided optimizations are only available for x86 or x64 native targets. Profile-guided optimizations aren't available for executable files that run on the common language runtime. Even if you produce an assembly with mixed native and managed code (by using the **/clr** compiler option), you can't use profile-guided optimization on just the native code. If you attempt to build a project with these options set in the IDE, a build error results. +Profile-guided optimizations are only available for x86, x64, or ARM64 native targets. Profile-guided optimizations aren't available for executable files that run on the common language runtime. Even if you produce an assembly with mixed native and managed code (by using the **/clr** compiler option), you can't use profile-guided optimization on just the native code. If you attempt to build a project with these options set in the IDE, a build error results. > [!NOTE] > Information that's gathered from profiling test runs overrides optimizations that would otherwise be in effect if you specify **/Ob**, **/Os**, or **/Ot**. For more information, see [/Ob (Inline Function Expansion)](reference/ob-inline-function-expansion.md) and [/Os, /Ot (Favor Small Code, Favor Fast Code)](reference/os-ot-favor-small-code-favor-fast-code.md). diff --git a/docs/build/project-property-inheritance.md b/docs/build/project-property-inheritance.md index 28a1be04c0..3456a29290 100644 --- a/docs/build/project-property-inheritance.md +++ b/docs/build/project-property-inheritance.md @@ -24,7 +24,7 @@ Project properties are stored in several files. Some are stored directly in the ::: moniker range=">=msvc-160" -Project properties are stored in several files. Some are stored directly in the *`.vcxproj`* project file. Others come from other *`.targets`* or *`.props`* files that the project file imports and which supply default values. You'll find the Visual Studio project files in a locale-specific folder under the base directory, *`%VSINSTALLDIR%MSBuild\Microsoft\VC\`*. The `` is specific to the version of Visual Studio. It's *`v160`* for Visual Studio 2019. +Project properties are stored in several files. Some are stored directly in the *`.vcxproj`* project file. Others come from other *`.targets`* or *`.props`* files that the project file imports and which supply default values. You'll find the Visual Studio project files in a locale-specific folder under the base directory, *`%VSINSTALLDIR%\MSBuild\Microsoft\VC\`*. The `` is specific to the version of Visual Studio. It's *`v160`* for Visual Studio 2019. ::: moniker-end @@ -75,7 +75,7 @@ A configuration is just an arbitrary group of properties that are given a name. To get a better idea of build configurations, open **Property Manager**. You can open it by choosing **View > Property Manager** or **View > Other Windows > Property Manager**, depending on your settings. **Property Manager** has nodes for each configuration and platform pair in the project. Under each of these nodes are nodes for property sheets (*`.props`* files) that set some specific properties for that configuration. -![Property Manager](media/property-manager.png "Property Manager") +![Screenshot of the Property Manager window.](media/property-manager.png "Property Manager") For example, you can go to the General pane in the Property Pages. Change the Character Set property to "Not Set" instead of "Use Unicode", and then click **OK**. The Property Manager now shows no **Unicode Support** property sheet. It's removed for the current configuration, but it's still there for other configurations. diff --git a/docs/build/projects-and-build-systems-cpp.md b/docs/build/projects-and-build-systems-cpp.md index ef71571b40..156cd4acfd 100644 --- a/docs/build/projects-and-build-systems-cpp.md +++ b/docs/build/projects-and-build-systems-cpp.md @@ -5,6 +5,7 @@ ms.date: "07/17/2019" helpviewer_keywords: ["builds [C++]", "C++ projects, building", "projects [C++], building", "builds [C++], options", "C++, build options"] ms.assetid: fa6ed4ff-334a-4d99-b5e2-a1f83d2b3008 ms.topic: "overview" +ms.custom: intro-overview --- # C/C++ projects and build systems in Visual Studio @@ -22,7 +23,7 @@ Basic C++ compilation involves three main steps: ## The MSVC toolset -The Microsoft C++ compiler, linker, standard libraries, and related utilities make up the MSVC compiler toolset (also called a toolchain or "build tools"). These are included in Visual Studio. You can also download and use the toolset as a free standalone package from [Build Tools for Visual Studio 2019 download](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2019). +The Microsoft C++ compiler, linker, standard libraries, and related utilities make up the MSVC compiler toolset (also called a toolchain or "build tools"). These are included in Visual Studio. You can also download and use the command-line toolset as a free standalone package. For more information, see [Build Tools for Visual Studio](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022) on the Visual Studio Downloads page. You can build simple programs by invoking the MSVC compiler (cl.exe) directly from the command line. The following command accepts a single source code file, and invokes cl.exe to build an executable called *hello.exe*: diff --git a/docs/build/reference/advanced-property-page.md b/docs/build/reference/advanced-property-page.md index 9152958872..f119173610 100644 --- a/docs/build/reference/advanced-property-page.md +++ b/docs/build/reference/advanced-property-page.md @@ -1,106 +1,137 @@ --- -description: "Learn more about: Advanced Property Page" +description: "Use the Advanced property page in Visual Studio 2019 to set various properties for C++ projects." title: "Advanced Property Page (Project)" -ms.date: 02/05/2021 -f1_keywords: ["VC.Project.VCConfiguration.VCToolsVersion","VC.Project.VCConfiguration.LLVMToolsVersion"] -ms.description: "Use the Advanced property page in Visual Studio 2019 to set various properties for C++ projects." +ms.date: 08/31/2022 +f1_keywords: ["VC.Project.VCConfiguration.TargetExt", "VC.Project.VCConfiguration.DeleteExtensionsOnClean", "VC.Project.VCConfiguration.BuildLogFile", "VC.Project.VCConfiguration.PreferredToolArchitecture", "VC.Project.VCConfiguration.UseDebugLibraries", "VC.Project.VCConfiguration.EnableUnitySupport", "VC.Project.VCConfiguration.CopyLocalDeploymentContent", "VC.Project.VCConfiguration.CopyLocalProjectReference", "VC.Project.VCConfiguration.CopyLocalDebugSymbols", "VC.Project.VCConfiguration.CopyCppRuntimeToOutputDir", "VC.Project.VCConfiguration.useOfMfc", "VC.Project.VCConfiguration.CharacterSet", "VC.Project.VCConfiguration.WholeProgramOptimization", "VC.Project.VCConfiguration.VCToolsVersion", "VC.Project.VCConfiguration.LLVMToolsVersion", "VC.Project.VCConfiguration.ManagedExtensions", "VC.Project.TargetFrameworkVersion", "VC.Project.VCConfiguration.EnableManagedIncrementalBuild", "VC.Project.VCConfiguration.ManagedAssembly"] --- + # Advanced Property Page ::: moniker range="<=msvc-150" -The Advanced property page is available in Visual Studio 2019 and later. To see the documentation for that version, set the Visual Studio **Version** selector control for this article to Visual Studio 2019. It's found at the top of the table of contents on this page. +The Advanced property page is available in Visual Studio 2019 and later. To see the documentation for that version, set the Visual Studio **Version** selector control for this article to Visual Studio 2019 or later. It's found at the top of the table of contents on this page. In earlier versions of Visual Studio, these properties appear on the [General property page](./general-property-page-project.md): + +- [Target Extension](./general-property-page-project.md#target-extension) +- [Extensions to Delete on Clean](./general-property-page-project.md#extensions-to-delete-on-clean) +- [Build Log File](./general-property-page-project.md#build-log-file) +- [Enable Managed Incremental Build](./general-property-page-project.md#enable-managed-incremental-build) +- [Use of MFC](./general-property-page-project.md#use-of-mfc) +- [Character Set](./general-property-page-project.md#character-set) +- [Whole Program Optimization](./general-property-page-project.md#whole-program-optimization) +- [Common Language Runtime support](./general-property-page-project.md#common-language-runtime-support) +- [.NET Target Framework Version](./general-property-page-project.md#net-target-framework-version) ::: moniker-end -::: moniker range="msvc-160" +::: moniker range=">=msvc-160" -The Advanced property page is available in Visual Studio 2019 and later. +The Advanced property page is available in Visual Studio 2019 and later. The specific properties shown depend on the project type. Windows Runtime (Universal Windows Platform, or UWP) projects don't show this page. ## Advanced Properties -- **Target File Extension** +### Target File Extension + +Specifies the file extension to use for the build output. Defaults to *`.exe`* for applications, *`.lib`* for static libraries and *`.dll`* for DLLs. + +### Extensions to Delete on Clean - Specifies the file extension to use for the build output. Defaults to *`.exe`* for applications, *`.lib`* for static libraries and *`.dll`* for DLLs. +The **Build** > **Clean** menu command deletes files from the intermediate directory where a project's configuration is built. The build system deletes files that have the specified extensions when you run the **Clean** command or when you rebuild. The build system also deletes any known output of the build no matter where it's located. Deleted files include any intermediate outputs such as *`.obj`* files. Use semicolons (**`;`**) to separate extensions. You can specify wildcard characters (**`*`**, **`?`**) in the extensions. -- **Extensions to Delete on Clean** +To programmatically access this property, see . - The **Clean** option (**Build** menu) deletes files from the intermediate directory where a project's configuration is built. Files with extensions specified in this property get deleted when **Clean** is run or when you rebuild. The build system deletes any files that have these extensions in the intermediate directory. It also deletes any known output of the build, no matter where it's located. (That includes the intermediate outputs such as *`.obj`* files.) You can specify wildcard characters in this property. +### Build Log File - To programmatically access this property, see . +Allows you to specify a non-default location for the log file that's created whenever you build a project. The default location is specified by the macros `$(IntDir)$(MSBuildProjectName).log`. -- **Build Log File** +You can use project macros to change the directory location. For more information, see [Common macros for build commands and properties](common-macros-for-build-commands-and-properties.md). - Allows you to specify a non-default location for the log file that's created whenever you build a project. The default location is specified by the macros `$(IntDir)$(MSBuildProjectName).log`. +### Preferred Build Tool Architecture - You can use project macros to change the directory location. See [Common macros for build commands and properties](common-macros-for-build-commands-and-properties.md). +Specifies whether to use the x86 or x64 build tools. -- **Preferred Build Tool Architecture** +### Use Debug Libraries - Specifies whether to use the x86 or x64 build tools. +Specifies whether to create a Debug or Release build. Despite the name, **Use Debug Libraries** is a build system-specific property that is effectively shorthand for "Make a Debug build" or "Make a Release build". It sets several compiler and linker properties for Debug or Release builds, including the library settings. You can use it to create Debug or Release configurations for a new platform or in a new template. We don't recommend you change this property in an existing configuration. Use the individual compiler and linker properties instead. -- **Use Debug Libraries** +### Enable Unity (JUMBO) build - Specifies whether to create a Debug or Release build. +Enables a faster build process that combines many C++ source files into one or more files before compilation. These combined files are known as *unity* files. They're unrelated to the Unity game engine. -- **Enable Unity (JUMBO) build** +### Copy Content to OutDir - Enables a faster build process that combines many C++ source files into one or more files before compilation. These combined files are known as *unity* files. They're unrelated to the Unity game engine. +Copy the items marked as *content* in the project to the project's output directory (`$(OutDir)`). This setting can simplify deployment. This property is available starting in Visual Studio 2019 version 16.7. -- **Copy Content to OutDir** +### Copy Project References to OutDir - Copy the items marked as *content* in the project to the project's output directory (`$(OutDir)`). This setting can simplify deployment. This property is available starting in Visual Studio 2019 version 16.7. +Copy the executable (DLL and EXE file) project reference items to the project's output directory (`$(OutDir)`). In C++/CLI ([`/clr`](clr-common-language-runtime-compilation.md)) projects, this property is ignored. Instead, the **Copy Local** property on each project reference controls whether it's copied to the output directory. This setting can simplify local deployment. It's available starting in Visual Studio 2019 version 16.7. -- **Copy Project References to OutDir** +### Copy Project References' Symbols to OutDir - Copy the executable (DLL and EXE file) project reference items to the project's output directory (`$(OutDir)`). In C++/CLI ([`/clr`](clr-common-language-runtime-compilation.md)) projects, this property is ignored. Instead, the **Copy Local** property on each project reference controls whether it's copied to the output directory. This setting can simplify local deployment. It's available starting in Visual Studio 2019 version 16.7. +Copy the PDB files for project reference items along with the project reference executable items to the project's output directory (`$(OutDir)`). This property is always enabled for C++/CLI projects. This setting can simplify debug deployment. It's available starting in Visual Studio 2019 version 16.7. -- **Copy Project References' Symbols to OutDir** +### Copy C++ Runtime to OutDir - Copy the PDB files for project reference items along with the project reference executable items to the project's output directory (`$(OutDir)`). This property is always enabled for C++/CLI projects. This setting can simplify debug deployment. It's available starting in Visual Studio 2019 version 16.7. +Copy the runtime DLLs to the project's output directory (`$(OutDir)`). This setting can simplify local deployment. It's available starting in Visual Studio 2019 version 16.7. -- **Copy C++ Runtime to OutDir** +### Use of MFC - Copy the runtime DLLs to the project's output directory (`$(OutDir)`). This setting can simplify local deployment. It's available starting in Visual Studio 2019 version 16.7. +Specifies whether the MFC project statically or dynamically links to the MFC DLL. Non-MFC projects select **Use Standard Windows Libraries**. -- **Use of MFC** +To programmatically access this property, see . - Specifies whether the MFC project statically or dynamically links to the MFC DLL. In non-MFC projects, select **Use Standard Windows Libraries** to link the Win32 libraries included by MFC. +### Character Set - To programmatically access this property, see . +Specifies whether the `_UNICODE` or `_MBCS` preprocessor macro should be set. Also affects the linker entry point, where appropriate. -- **Character Set** +To programmatically access this property, see . - Defines whether `_UNICODE` or `_MBCS` should be set. Also affects the linker entry point where appropriate. +### Whole Program Optimization - To programmatically access this property, see . +Specifies the [`/GL`](gl-whole-program-optimization.md) compiler option and [`/LTCG`](ltcg-link-time-code-generation.md) linker option. By default, this property is disabled for Debug configurations, and enabled for Release configurations. -- **Whole Program Optimization** +### MSVC Toolset Version - Specifies the [`/GL`](gl-whole-program-optimization.md) compiler option and [`/LTCG`](ltcg-link-time-code-generation.md) linker option. By default, whole program optimization is disabled for Debug configurations, and enabled for Release configurations. +Specifies the full version of the MSVC toolset that's used to build the project. You may have various update and preview versions of a toolset installed. You can specify which one to use here. -- **MSVC Toolset Version** +### LLVM Toolset Version - Specifies the full version of the MSVC toolset that's used to build the project. You may have various update and preview versions of a toolset installed. You can specify which one to use here. +Specifies the full version of the LLVM toolset that's used to build the project. This property is available when **LLVM (clang-cl)** is selected as the platform toolset, starting in Visual Studio 2019 version 16.9. For more information, see [Set a custom LLVM toolset version](..\clang-support-msbuild.md#custom_llvm_toolset). -- **LLVM Toolset Version** +### Enable MSVC Structured Output - Specifies the full version of the LLVM toolset that's used to build the project. This property is available when **LLVM (clang-cl)** is selected as the platform toolset, starting in Visual Studio 2019 version 16.9. For more information, see [Set a custom LLVM toolset version](..\clang-support-msbuild.md#custom_llvm_toolset). +Specifies whether to enable [structured SARIF output](sarif-output.md), which enables the [**Problem Details** window](/visualstudio/ide/reference/problem-details-window) and hierarchical output in the [**Output** window](/visualstudio/ide/reference/output-window) in Visual Studio. ## C++/CLI Properties -- **Common Language Runtime support** +### Common Language Runtime support + +Causes the [`/clr`](clr-common-language-runtime-compilation.md) compiler option to be used. + +To programmatically access this property, see . + +### .NET Target Framework Version - Causes the [`/clr`](clr-common-language-runtime-compilation.md) compiler option to be used. +This property only applies when the **Common Language Runtime support** property is set to **.NET Framework Runtime Support**, that is the project targets [.NET Framework](/dotnet/standard/glossary#net-framework), and it specifies the version of the .NET Framework. - To programmatically access this property, see . +### .NET Target Framework -- **.NET Target Framework Version** +This property only applies when the **Common Language Runtime support** property is set to **.NET Runtime Support**, that is the project targets [.NET](/dotnet/standard/glossary#net). - In managed projects, specifies the .NET framework version to target. +This property specifies the .NET 5+ Target Framework Moniker this project targets, for example `net6.0-windows` or `net7.0-windows8.0`. -- **Enable Managed Incremental Build** +### Enable Managed Incremental Build - For managed projects, this option enables detection of external visibility when you generate assemblies. If a change to a managed project isn't visible to other projects, dependent projects aren't rebuilt. Managed incremental builds can dramatically improve build times in solutions that include managed projects. +For managed projects, this option enables detection of external visibility when you generate assemblies. If a change to a managed project isn't visible to other projects, dependent projects aren't rebuilt. Managed incremental builds can dramatically improve build times in solutions that include managed projects. + +### Enable CLR Support for Individual Files + +This option sets a `ManagedAssembly` build property that enables building only some files in the project as managed code. You must set **Enable CLR Support for Individual Files** to **Yes** if some but not all of your project files are built as managed code. This property is only available in projects that use the v143 or later toolset in Visual Studio 2022 and later versions. + +### .NET Target Windows Version + +This property only applies when the **Common Language Runtime support** property is set to **.NET Runtime Support**, that is the project targets [.NET](/dotnet/standard/glossary#net). + +This property specifies the minimum Windows version that the project supports. This value is used by NuGet to determine the compatibility of projects and NuGet package dependencies. If a project A depends on project B, project A's .NET target Windows version must be greater or equal to project B's. ::: moniker-end + diff --git a/docs/build/reference/align-section-alignment.md b/docs/build/reference/align-section-alignment.md index a0c6d73a80..083eacba6b 100644 --- a/docs/build/reference/align-section-alignment.md +++ b/docs/build/reference/align-section-alignment.md @@ -1,30 +1,31 @@ --- -description: "Learn more about: /ALIGN (Section Alignment)" -title: "/ALIGN (Section Alignment)" -ms.date: "12/29/2017" +description: "Learn more about: /ALIGN (Section alignment)" +title: "/ALIGN (Section alignment)" +ms.date: 05/11/2022 f1_keywords: ["VC.Project.VCLinkerTool.Alignment", "/align"] helpviewer_keywords: ["sections, specifying alignment", "ALIGN linker option", "/ALIGN linker option", "-ALIGN linker option", "section alignment", "sections"] --- -# /ALIGN (Section Alignment) +# `/ALIGN` (Section alignment) +Specify the alignment of each section within the executable image. ## Syntax -> **/ALIGN**[**:**_number_] +> **`/ALIGN`**\[**`:`*`number`***] ### Arguments -*number*
+*`number`*\ The alignment value in bytes. ## Remarks -The **/ALIGN** option specifies the alignment of each section within the linear address space of the program. The *number* argument is in bytes and must be a power of two. The default is 4K (4096). The linker issues a warning if the alignment produces an invalid image. +The **`/ALIGN`** linker option specifies the alignment of each section within the linear address space of the program. The *`number`* argument is in bytes and must be a power of two. The default is 4K (4096). The linker issues a warning if the alignment produces an invalid image. -Unless you are writing an application such as a device driver, you should not need to modify the alignment. +Unless you're writing an application such as a device driver, you shouldn't need to modify the alignment. -It is possible to modify the alignment of a particular section with the align parameter to the [/SECTION](section-specify-section-attributes.md) option. +It's possible to modify the alignment of a particular section with the *`align`* parameter to the [`/SECTION`](section-specify-section-attributes.md) option. -The alignment value that you specify cannot be smaller than the largest section alignment. +The alignment value that you specify can't be smaller than the largest section alignment. ### To set this linker option in the Visual Studio development environment @@ -40,5 +41,5 @@ The alignment value that you specify cannot be smaller than the largest section ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/allowbind-prevent-dll-binding.md b/docs/build/reference/allowbind-prevent-dll-binding.md index f3d1146904..583b85e26a 100644 --- a/docs/build/reference/allowbind-prevent-dll-binding.md +++ b/docs/build/reference/allowbind-prevent-dll-binding.md @@ -1,22 +1,24 @@ --- -description: "Learn more about: /ALLOWBIND (Prevent DLL Binding)" -title: "/ALLOWBIND (Prevent DLL Binding)" -ms.date: "11/04/2016" +description: "Learn more about: /ALLOWBIND (Prevent DLL binding)" +title: "/ALLOWBIND (Prevent DLL binding)" +ms.date: 05/11/2022 f1_keywords: ["VC.Project.VCLinkerTool.PreventDLLBinding", "/allowbind"] helpviewer_keywords: ["/ALLOWBIND linker option", "binding DLLs", "preventing DLL binding", "ALLOWBIND linker option", "-ALLOWBIND linker option", "DLLs [C++], preventing binding"] ms.assetid: 30e37e24-12e4-407e-988a-39d357403598 --- -# /ALLOWBIND (Prevent DLL Binding) +# `/ALLOWBIND` (Prevent DLL binding) -``` -/ALLOWBIND[:NO] -``` +Set a flag to disallow DLL binding. + +## Syntax + +> **`/ALLOWBIND`**\[**`:NO`**] ## Remarks -/ALLOWBIND:NO sets a bit in a DLL's header that indicates to Bind.exe that the image is not allowed to be bound. You may not want a DLL to be bound if it has been digitally signed (binding invalidates the signature). +The **`/ALLOWBIND:NO`** linker option sets a bit in a DLL's header that indicates to Bind.exe that the image can't be bound. You may not want a DLL to be bound if it's been digitally signed (binding invalidates the signature). -You can edit an existing DLL for /ALLOWBIND functionality with the [/ALLOWBIND](allowbind.md) option of the EDITBIN utility. +You can edit an existing DLL for **`/ALLOWBIND`** functionality with the [`/ALLOWBIND`](allowbind.md) option of the EDITBIN utility. ### To set this linker option in the Visual Studio development environment @@ -24,7 +26,7 @@ You can edit an existing DLL for /ALLOWBIND functionality with the [/ALLOWBIND]( 1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. -1. Enter `/ALLOWBIND:NO` into **Additional Options**. +1. Enter *`/ALLOWBIND:NO`* into **Additional Options**. Choose **OK** or **Apply** to apply the change. ### To set this linker option programmatically @@ -32,7 +34,7 @@ You can edit an existing DLL for /ALLOWBIND functionality with the [/ALLOWBIND]( ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md)
-[BindImage function](/windows/win32/api/imagehlp/nf-imagehlp-bindimage)
-[BindImageEx function](/windows/win32/api/imagehlp/nf-imagehlp-bindimageex) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md)\ +[`BindImage` function](/windows/win32/api/imagehlp/nf-imagehlp-bindimage)\ +[`BindImageEx` function](/windows/win32/api/imagehlp/nf-imagehlp-bindimageex) diff --git a/docs/build/reference/allowbind.md b/docs/build/reference/allowbind.md index c57e11a615..b7404db175 100644 --- a/docs/build/reference/allowbind.md +++ b/docs/build/reference/allowbind.md @@ -11,7 +11,6 @@ ms.assetid: eaadbb8c-4339-4281-9a75-3a1ce2352ff8 Specifies whether a DLL can be bound. ``` - /ALLOWBIND[:NO] ``` diff --git a/docs/build/reference/allowisolation-manifest-lookup.md b/docs/build/reference/allowisolation-manifest-lookup.md index 7b475485b1..4d178ade64 100644 --- a/docs/build/reference/allowisolation-manifest-lookup.md +++ b/docs/build/reference/allowisolation-manifest-lookup.md @@ -1,32 +1,30 @@ --- -description: "Learn more about: /ALLOWISOLATION (Manifest Lookup)" -title: "/ALLOWISOLATION (Manifest Lookup)" -ms.date: "11/04/2016" +description: "Learn more about: /ALLOWISOLATION (Manifest lookup)" +title: "/ALLOWISOLATION (Manifest lookup)" +ms.date: 05/11/2022 f1_keywords: ["/ALLOWISOLATION", "VC.Project.VCLinkerTool.AllowIsolation"] helpviewer_keywords: ["-ALLOWISOLATION linker option", "/ALLOWISOLATION linker option"] ms.assetid: 6d41851e-b3c1-4bdf-beaa-031773089d6f --- -# /ALLOWISOLATION (Manifest Lookup) +# `/ALLOWISOLATION` (Manifest lookup) Specifies behavior for manifest lookup. ## Syntax -``` -/ALLOWISOLATION[:NO] -``` +> **`/ALLOWISOLATION`**\[**`:NO`**] ## Remarks -**/ALLOWISOLATION:NO** indicates DLLs are loaded as if there was no manifest and causes the linker to set the `IMAGE_DLLCHARACTERISTICS_NO_ISOLATION` bit in the optional header's `DllCharacteristics` field. +The **`/ALLOWISOLATION:NO`** linker option indicates DLLs are loaded as if there was no manifest and causes the linker to set the `IMAGE_DLLCHARACTERISTICS_NO_ISOLATION` bit in the optional header's `DllCharacteristics` field. -**/ALLOWISOLATION** causes the operating system to do manifest lookups and loads. +**`/ALLOWISOLATION`** causes the operating system to do manifest lookups and loads. -**/ALLOWISOLATION** is the default. +**`/ALLOWISOLATION`** is the default. -When isolation is disabled for an executable, the Windows loader will not attempt to find an application manifest for the newly created process. The new process will not have a default activation context, even if there is a manifest inside the executable or placed in the same directory as the executable with name executable-name**.exe.manifest**. +When isolation is disabled for an executable, the Windows loader won't attempt to find an application manifest for the newly created process. The new process won't have a default activation context, even if there's a manifest inside the executable or placed in the same directory as the executable with name *`.exe.manifest`*. -For more information, see [Manifest Files Reference](/windows/win32/SbsCs/manifest-files-reference). +For more information, see [Manifest files reference](/windows/win32/SbsCs/manifest-files-reference). ### To set this linker option in the Visual Studio development environment @@ -38,5 +36,5 @@ For more information, see [Manifest Files Reference](/windows/win32/SbsCs/manife ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/allowisolation.md b/docs/build/reference/allowisolation.md index 28ab8b6038..579f9900b3 100644 --- a/docs/build/reference/allowisolation.md +++ b/docs/build/reference/allowisolation.md @@ -13,7 +13,6 @@ Specifies behavior for manifest lookup. ## Syntax ``` - /ALLOWISOLATION[:NO] ``` diff --git a/docs/build/reference/analyze-code-analysis.md b/docs/build/reference/analyze-code-analysis.md index aa495ab414..8064dc9e98 100644 --- a/docs/build/reference/analyze-code-analysis.md +++ b/docs/build/reference/analyze-code-analysis.md @@ -1,10 +1,9 @@ --- title: "/analyze (Code analysis)" description: "The Microsoft C++ compiler /analyze option syntax and usage." -ms.date: 05/21/2021 -f1_keywords: ["VC.Project.VCCLCompilerTool.EnablePREfast", "/analyze", "VC.Project.VCCLCompilerTool.PREfastAdditionalOptions", "VC.Project.VCCLCompilerTool.PREfastAdditionalPlugins"] +ms.date: 02/17/2022 +f1_keywords: ["VC.Project.VCCLCompilerTool.EnablePREfast", "/analyze", "VC.Project.VCCLCompilerTool.PREfastAdditionalOptions", "VC.Project.VCCLCompilerTool.PREfastAdditionalPlugins", "VC.Project.VCCLCompilerTool.DisableAnalyzeExternal", "VC.Project.VCCLCompilerTool.AnalyzeExternalRuleset"] helpviewer_keywords: ["/analyze compiler option [C++]", "-analyze compiler option [C++]", "analyze compiler option [C++]"] -ms.assetid: 81da536a-e030-4bd4-be18-383927597d08 --- # `/analyze` (Code analysis) @@ -73,7 +72,7 @@ Ruleset options: **`/analyze`**\[**`-`**]\ Turns on code analysis. Use **`/analyze-`** to explicitly turn off analysis. **`/analyze-`** is the default behavior. -By default, analysis output goes to the console or the Visual Studio Output window like other error messages. Code analysis also creates a log file named *`filename.nativeanalysis.xml`*, where *`filename`* is the name of the analyzed source file. +By default, analysis output goes to the console or the Visual Studio Output window like other error messages. Code analysis also creates a log file named *`filename.nativecodeanalysis.xml`*, where *`filename`* is the name of the analyzed source file. **`/analyze:only`**\ By default, the compiler compiles the code to generate object files before code analysis runs. The **`/analyze:only`** option makes the compiler skip the code generation pass, and does code analysis directly. Compiler errors still prevent code analysis from running. However, the compiler won't report other warnings that it might find during the code generation pass. If the program isn't free of code-generation warnings, analysis results might be unreliable. We recommend you use this option only if the code passes code-generation syntax checks without errors or warnings. @@ -135,7 +134,7 @@ Then, use compiler option `/analyze:plugin EspXEngine.dll` to use the EspXEngine #### External file analysis options -Starting in Visual Studio 2019 version 16.10, you can specify different analysis rules and behavior for external headers. By using the **`/external:I`**, **`/external:env`**, or **`/external:anglebrackets`** options, directories can be specified as "external" directories. Any files that are included by using `#include`from an external directory or one of its subdirectories are considered as external headers. For more information, see [`/external` (External headers diagnostics)](external-external-headers-diagnostics.md). +Starting in Visual Studio 2019 version 16.10, you can specify different analysis rules and behavior for external headers. Use the **`/external:I`**, **`/external:env`**, or **`/external:anglebrackets`** options to specify directories as "external" directories. Any files that are included by using `#include` from an external directory or its subdirectories are considered as external headers. For more information, see [`/external` (External headers diagnostics)](external-external-headers-diagnostics.md). Code analysis provides these options to control analysis of external files: @@ -206,14 +205,14 @@ Specifies the current project directory. If the ruleset (or an item it includes) Specifies a semicolon-separated list of ruleset search paths. If the ruleset (or an item it includes) is a file name, then the compiler first looks for the file under the *`project_directory`* specified by **`/analyze:projectdirectory`**, if any, followed by the specified *`ruleset_directories`*. This option is available starting in Visual Studio 2019 version 16.9. **`/analyze:ruleset`** *`ruleset_files`*\ -Specifies one or more ruleset files to use for analysis. This option can make analysis more efficient. That's because the analysis engine tries to exclude checkers that have no active rules specified in the ruleset files before running. Otherwise, the engine runs all checkers enabled. +Specifies one or more ruleset files to use for analysis. This option can make analysis more efficient; the analysis engine tries to exclude checkers that have no active rules specified in the ruleset files before running. Otherwise, the engine runs all checkers enabled. ::: moniker-end ::: moniker range="msvc-150" **`/analyze:ruleset`** *`ruleset_file`*\ -Specifies a ruleset file to use for analysis. This option can make analysis more efficient. That's because the analysis engine tries to exclude checkers that have no active rules specified in the ruleset file before running. Otherwise, the engine runs all checkers enabled. +Specifies a ruleset file to use for analysis. This option can make analysis more efficient; the analysis engine tries to exclude checkers that have no active rules specified in the ruleset file before running. Otherwise, the engine runs all checkers enabled. ::: moniker-end @@ -267,6 +266,26 @@ For more information, see [Code analysis for C/C++ overview](../../code-quality/ 1. Modify one or more of the **Code Analysis** properties. +1. Choose **OK** or **Apply** to save your changes. + +::: moniker range=">=msvc-160" + +To set external file analysis options in Visual Studio 2019 version 16.10 and later: + +1. Open the project's **Property Pages** dialog box. + +1. Select the **Configuration Properties** > **C/C++** > **External Includes** property page. + +1. Set properties: + + - **Disable Code Analysis for External Headers** sets the **`/analyze:external-`** option. + + - **Analysis Ruleset for External Headers** sets the **`/analyze:external:ruleset path`** option. + +1. Choose **OK** or **Apply** to save your changes. + +::: moniker-end + ### To set this compiler option programmatically 1. See . diff --git a/docs/build/reference/appcontainer-windows-store-app.md b/docs/build/reference/appcontainer-windows-store-app.md index 4d57c088f3..4c0e6f856c 100644 --- a/docs/build/reference/appcontainer-windows-store-app.md +++ b/docs/build/reference/appcontainer-windows-store-app.md @@ -1,26 +1,22 @@ --- -description: "Learn more about: /APPCONTAINER (Microsoft Store App)" -title: "/APPCONTAINER (UWP/Microsoft Store App)" -ms.date: "11/04/2016" +description: "Learn more about: /APPCONTAINER (Microsoft Store app)" +title: "/APPCONTAINER (UWP/Microsoft Store app)" +ms.date: 05/11/2022 ms.assetid: 9a432db5-7640-460b-ab18-6f61fa7daf6f --- -# /APPCONTAINER (Microsoft Store App) +# `/APPCONTAINER` (Microsoft Store app) -Specifies whether the linker creates an executable image that must be run in an app container. +Specifies whether the linker creates an executable image that must run in an AppContainer environment. ## Syntax -``` -/APPCONTAINER[:NO] -``` +> **`/APPCONTAINER`**\[**`:NO`**] ## Remarks -By default, /APPCONTAINER is off. +The **`/APPCONTAINER`** linker option modifies an executable to indicate whether the app must run in the AppContainer process-isolation environment. Specify **`/APPCONTAINER`** for an app that must run in the AppContainer environment—for example, a Universal Windows Platform (UWP) or Windows Phone 8.x app. The option is set automatically in Visual Studio when you create a Universal Windows app from a template. For a desktop app, specify **`/APPCONTAINER:NO`** or just omit the option. By default, **`/APPCONTAINER`** is off. -This option modifies an executable to indicate whether the app must be run in the appcontainer process-isolation environment. Specify /APPCONTAINER for an app that must run in the appcontainer environment—for example, a Universal Windows Platform (UWP) or Windows Phone 8.x app. (The option is set automatically in Visual Studio when you create a Universal Windows app from a template.) For a desktop app, specify /APPCONTAINER:NO or just omit the option. - -The /APPCONTAINER option was introduced in Windows 8. +The **`/APPCONTAINER`** option was introduced in Windows 8. ### To set this linker option in Visual Studio @@ -28,9 +24,9 @@ The /APPCONTAINER option was introduced in Windows 8. 1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. -1. In **Additional Options**, enter `/APPCONTAINER` or `/APPCONTAINER:NO`. +1. In **Additional Options**, enter *`/APPCONTAINER`* or *`/APPCONTAINER:NO`*. ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/appcontainer.md b/docs/build/reference/appcontainer.md index 3b0db522a6..7cf45709d1 100644 --- a/docs/build/reference/appcontainer.md +++ b/docs/build/reference/appcontainer.md @@ -11,7 +11,6 @@ ms.assetid: 0ca4f1ec-c8de-4a37-b3e2-deda7af0bb88 Marks an executable that must run in an app container—for example, a Microsoft Store or Universal Windows app. ``` - /APPCONTAINER[:NO] ``` diff --git a/docs/build/reference/arch-arm.md b/docs/build/reference/arch-arm.md index b622745e0e..8d7ebd3293 100644 --- a/docs/build/reference/arch-arm.md +++ b/docs/build/reference/arch-arm.md @@ -1,34 +1,31 @@ --- description: "Learn more about: /arch (ARM)" title: "/arch (ARM)" -ms.date: "11/04/2016" -ms.assetid: 4f1406ff-f174-487c-a126-8ab06cf447c1 +ms.date: 07/01/2022 --- -# /arch (ARM) +# `/arch` (ARM) -Specifies the architecture for code generation on ARM. See also [/arch (x86)](arch-x86.md) and [/arch (x64)](arch-x64.md). +Specifies the architecture for code generation on ARM. These switches apply to the ARM targeting version of the compiler. For more information on **`/arch`** for other target architectures, see [`/arch` (ARM64)](arch-arm64.md), [`/arch` (x64)](arch-x64.md), and [`/arch` (x86)](arch-x86.md) ## Syntax -``` -/arch:[ARMv7VE|VFPv4] -``` +> **`/arch:`**\[**`ARMv7VE`**|**`VFPv4`**] ## Arguments -**/arch:ARMv7VE**
+**`/arch:ARMv7VE`**\ Enables the use of ARMv7VE Virtualization Extensions instructions. -**/arch:VFPv4**
-Enables the use of ARM VFPv4 instructions. If this option is not specified, VFPv3 is the default. +**`/arch:VFPv4`**\ +Enables the use of ARM VFPv4 instructions. If this option isn't specified, VFPv3 is the default. ## Remarks -The `_M_ARM_FP` macro (for ARM only) indicates which, if any, **/arch** compiler option was used. For more information, see [Predefined Macros](../../preprocessor/predefined-macros.md). +The `_M_ARM_FP` macro (for ARM only) indicates which, if any, **`/arch`** compiler option was used. For more information, see [Predefined macros](../../preprocessor/predefined-macros.md). -When you use [/clr](clr-common-language-runtime-compilation.md) to compile, **/arch** has no effect on code generation for managed functions. **/arch** only affects code generation for native functions. +When you use [`/clr`](clr-common-language-runtime-compilation.md) to compile, **`/arch`** has no effect on code generation for managed functions. **`/arch`** only affects code generation for native functions. -### To set the /arch:ARMv7VE or /arch:VFPv4 compiler option in Visual Studio +### To set the `/arch:ARMv7VE` or `/arch:VFPv4` compiler option in Visual Studio 1. Open the **Property Pages** dialog box for the project. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). @@ -42,6 +39,6 @@ When you use [/clr](clr-common-language-runtime-compilation.md) to compile, **/a ## See also -[/arch (Minimum CPU Architecture)](arch-minimum-cpu-architecture.md)
-[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) +[`/arch` (Minimum CPU architecture)](arch-minimum-cpu-architecture.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/arch-arm64.md b/docs/build/reference/arch-arm64.md new file mode 100644 index 0000000000..7b432961ec --- /dev/null +++ b/docs/build/reference/arch-arm64.md @@ -0,0 +1,63 @@ +--- +title: "/arch (ARM64)" +description: "Learn more about: /arch (ARM64)" +ms.date: 05/24/2024 +--- +# `/arch` (ARM64) + +Specifies the Arm A-Profile architecture extension for code generation on ARM64. These switches apply to the ARM64 targeting version of the compiler. For more information about **`/arch`** for other target architectures, see [`/arch` (x86)](arch-x86.md), [`/arch` (x64)](arch-x64.md), and [`/arch` (ARM)](arch-arm.md). + +## Syntax + +>**`/arch:`**[[+feature]](feature-arm64.md)\ +>**`/arch:`**[[+feature]](feature-arm64.md) + +## Arguments + +**`/arch:armv8.x`**\ +Specifies the Armv8-A architecture, where **`x`** is a required extension value from **`0`** to **`9`**1. By default, the compiler uses the **`/arch:armv8.0`** behavior if no architecture is specified. + +**`/arch:armv9.x`**2\ +Specifies the Armv9-A architecture, where **`x`** is a required extension value from **`0`** to **`4`**. By default, the compiler uses the **`/arch:armv8.0`** behavior if no architecture is specified. + +## Remarks + +You can specify an ARM64 extension from Armv8.0-A through Armv8.9-A, and Armv9.0-A through Armv9.4-A. Optionally, enable one or more architecture features by appending a feature argument to the option3. For example, to target Armv8.0-A and enable feature `FEAT_LSE`, append feature argument **`lse`** so that the option becomes **`/arch:armv8.0+lse`**. For more information about available features and their requirements, see [`/feature` (ARM64)](feature-arm64.md)3. + +> [!NOTE] +> Depending on your version of Visual Studio, the compiler may not yet generate instructions from all feature sets required by the extension level you specify. For example, **`/arch:armv8.1`** allows the *`Interlocked`* intrinsic functions to use the appropriate atomic instruction introduced with the Armv8.1-A extension feature `FEAT_LSE`, but compiler support requires Visual Studio 2022 version 17.2 or later. + +The `_M_ARM64` macro is defined by default when compiling for an ARM64 target. For more information, see [Predefined macros](../../preprocessor/predefined-macros.md). + +The `__ARM_ARCH` macro is defined for `/arch:ARMv8.0` and higher. It indicates the ARM architecture extension level that the compiler is targeting. For more information, see [Predefined macros](../../preprocessor/predefined-macros.md). + +```cpp +#if __ARM_ARCH >= 802 + // code that requires ARMv8.2... +#endif +``` + +**`/arch`** only affects code generation for native functions. When you use [`/clr`](clr-common-language-runtime-compilation.md) to compile, **`/arch`** has no effect on code generation for managed functions. + +### To set the `/arch` compiler option in Visual Studio + +1. Open the **Property Pages** dialog box for the project. For more information, 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 the **Additional options** box, add *`/arch:armv8.0`* or replace `armv8.0` with a different ARM64 extension. Choose **OK** to save your changes. + +### To set this compiler option programmatically + +- See . + +1 Armv8-A architecture extension `armv8.9` is available starting in Visual Studio 2022 version 17.10.\ +2 Armv9-A architecture extensions are available starting in Visual Studio 2022 version 17.10.\ +3 Architecture feature enablement is available starting in Visual Studio 2022 version 17.10. + +## See also + +[`/arch` (Minimum CPU architecture)](arch-minimum-cpu-architecture.md)\ +[Predefined macros](../../preprocessor/predefined-macros.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/arch-minimum-cpu-architecture.md b/docs/build/reference/arch-minimum-cpu-architecture.md index 48a02679bc..3c17866868 100644 --- a/docs/build/reference/arch-minimum-cpu-architecture.md +++ b/docs/build/reference/arch-minimum-cpu-architecture.md @@ -1,22 +1,23 @@ --- description: "Learn more about: /arch (Minimum CPU Architecture)" title: "/arch (Minimum CPU Architecture)" -ms.date: "11/04/2016" +ms.date: 06/30/2022 f1_keywords: ["VC.Project.VCCLCompilerTool.EnableEnhancedInstructionSet", "/arch"] helpviewer_keywords: ["-arch compiler option [C++]", "/arch compiler option [C++]", "arch compiler option [C++]"] -ms.assetid: cc17da15-47bd-4e74-b905-4e73c3bdb8a0 --- -# /arch (Minimum CPU Architecture) +# `/arch` (Minimum CPU Architecture) -The architecture options specify the architecture for code generation. Select the base hardware architecture you are working with to see /arch options for that target platform. +The architecture options specify the architecture for code generation. Select the base hardware architecture you're working with to see **`/arch`** options for that target platform. -- [/arch (x86)](arch-x86.md) +- [`/arch (x86`)](arch-x86.md) -- [/arch (x64)](arch-x64.md) +- [`/arch (x64)`](arch-x64.md) -- [/arch (ARM)](arch-arm.md) +- [`/arch (ARM)`](arch-arm.md) + +- [`/arch (ARM64)`](arch-arm64.md) ## See also -[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/arch-x64.md b/docs/build/reference/arch-x64.md index ffa9f2996e..0bcf4ff202 100644 --- a/docs/build/reference/arch-x64.md +++ b/docs/build/reference/arch-x64.md @@ -1,57 +1,75 @@ --- description: "Learn more about: /arch (x64)" title: "/arch (x64)" -ms.date: "10/01/2019" -ms.assetid: ecda22bf-5bed-43f4-99fb-88aedd83d9d8 +ms.date: 06/30/2022 +f1_keywords: ["/arch:SSE2", "/arch:SSE4.2", "/arch:AVX", "/arch:AVX2", "/arch:AVX512", "/arch:AVX10.1"] +helpviewer_keywords: ["/arch:SSE2 compiler option [C++]", "/arch:SSE4.2 compiler option [C++]", "/arch:AVX compiler option [C++]", "/arch:AVX2 compiler option [C++]", "/arch:AVX512 compiler option [C++]", "/arch:AVX10.1 compiler option [C++]"] --- -# /arch (x64) +# `/arch` (x64) -Specifies the architecture for code generation on x64. Also see [/arch (x86)](arch-x86.md) and [/arch (ARM)](arch-arm.md). +Specifies the architecture for code generation on x64. These switches apply to the x64 targeting version of the compiler. For more information on **`/arch`** for other target architectures, see [`/arch` (x86)](arch-x86.md), [`/arch` (ARM64)](arch-arm64.md), and [`/arch` (ARM)](arch-arm.md). ## Syntax -``` -/arch:[AVX|AVX2|AVX512] -``` +> **`/arch:`**\[**`SSE2`**|**`SSE4.2`**|**`AVX`**|**`AVX2`**|**`AVX512`**|**`AVX10.1`**] ## Arguments -**/arch:AVX**
-Enables the use of Intel Advanced Vector Extensions instructions. +**`/arch:SSE2`**\ +Enables Intel Streaming SIMD Extensions 2. The default instruction set is SSE2 if no **`/arch`** option is specified. -**/arch:AVX2**
-Enables the use of Intel Advanced Vector Extensions 2 instructions. +**`/arch:SSE4.2`**\ +Enables Intel Streaming SIMD Extensions 4.2. -**/arch:AVX512**
-Enables the use of Intel Advanced Vector Extensions 512 instructions. +**`/arch:AVX`**\ +Enables Intel Advanced Vector Extensions. + +**`/arch:AVX2`**\ +Enables Intel Advanced Vector Extensions 2. + +**`/arch:AVX512`**\ +Enables Intel Advanced Vector Extensions 512. + +**`/arch:AVX10.1`**\ +Enables Intel Advanced Vector Extensions 10 version 1. ## Remarks -The **/arch** option enables the use of certain instruction set extensions, particularly for vector calculation, available in processors from Intel and AMD. In general, more recently introduced processors may support additional extensions over those supported by older processors, although you should consult the documentation for a particular processor or test for instruction set extension support using [__cpuid](../../intrinsics/cpuid-cpuidex.md) before executing code using an instruction set extension. +The **`/arch`** option enables the use of certain instruction set extensions, particularly for vector calculation, available in processors from Intel and AMD. In general, more recently introduced processors may support extensions beyond the ones supported by older processors, although you should consult the documentation for a particular processor or test for instruction set extension support using [`__cpuid`](../../intrinsics/cpuid-cpuidex.md) before executing code using an instruction set extension. You can also use the [`__check_isa_support`](../../intrinsics/check-isa-arch-support.md) intrinsic to check for more frequently used CPU features. -**/arch** only affects code generation for native functions. When you use [/clr](clr-common-language-runtime-compilation.md) to compile, **/arch** has no effect on code generation for managed functions. +**`/arch`** only affects code generation for native functions. When you use [`/clr`](clr-common-language-runtime-compilation.md) to compile, **`/arch`** has no effect on code generation for managed functions. The processor extensions have the following characteristics: -- The default mode uses SSE2 instructions for scalar floating-point and vector calculations. These instructions allow calculation with 128-bit vectors of single-precision, double-precision and 1, 2, 4 or 8 byte integer values, as well as single-precision and double-precision scalar floating-point values. +- The default mode uses SSE2 instructions for scalar floating-point and vector calculations. These instructions allow calculation with 128-bit vectors of single-precision, double-precision and 1, 2, 4 or 8-byte integer values, as well as single-precision and double-precision scalar floating-point values. + +- **`SSE4.2`** uses the full set of SSE instructions for floating-point scalar, vector, and integer vector calculations. + +- **`AVX`** introduced an alternative instruction encoding for vector and floating-point scalar instructions. It allows vectors of either 128 bits or 256 bits, and zero-extends all vector results to the full vector size. (For legacy compatibility, SSE-style vector instructions preserve all bits beyond bit 127.) Most floating-point operations are extended to 256 bits. -- **AVX** introduced an alternative instruction encoding for vector and floating-point scalar instructions that allows vectors of either 128 bits or 256 bits, and zero-extends all vector results to the full vector size. (For legacy compatibility, SSE-style vector instructions preserve all bits beyond bit 127.) Most floating-point operations are extended to 256 bits. +- **`AVX2`** extends most integer operations to 256-bit vectors and enables use of Fused Multiply-Add (FMA) instructions. -- **AVX2** extends most integer operations to 256-bit vectors and enables use of Fused Multiply-Add (FMA) instructions. +- **`AVX-512`** introduced another instruction encoding form that allows 512-bit vectors, masking, embedded rounding/broadcast, and new instructions. The default vector length for **`AVX-512`** is 512 bits and can be changed to 256 bits using the [`/vlen`](vlen.md) flag. -- **AVX-512** introduced another instruction encoding form that allows 512-bit vectors, plus certain other optional features. Instructions for additional operations were also added. +- **`AVX10.1`** adds more instructions on top of **`AVX-512`**. The default vector length for **`AVX10.1`** is 256 bits and can be changed to 512 bits using the [`/vlen`](vlen.md) flag. -Each **/arch** option may also enable the use of other non-vector instructions that are associated with that option. An example is the use of certain BMI instructions when **/arch:AVX2** is specified. +Each **`/arch`** option may also enable the use of other non-vector instructions that are associated with that option. An example is the use of certain BMI instructions when **`/arch:AVX2`** is specified. -The `__AVX__` preprocessor symbol is defined when the **/arch:AVX**, **/arch:AVX2** or **/arch:AVX512** compiler option is specified. The `__AVX2__` preprocessor symbol is defined when the **/arch:AVX2** or **/arch:AVX512** compiler option is specified. The `__AVX512F__`, `__AVX512CD__`, `__AVX512BW__`, `__AVX512DQ__` and `__AVX512VL__` preprocessor symbols are defined when the **/arch:AVX512** compiler option is specified. For more information, see [Predefined Macros](../../preprocessor/predefined-macros.md). The **/arch:AVX2** option was introduced in Visual Studio 2013 Update 2, version 12.0.34567.1. Limited support for **/arch:AVX512** was added in Visual Studio 2017, and expanded in Visual Studio 2019. +The `__AVX__` preprocessor symbol is defined when the **`/arch:AVX`**, **`/arch:AVX2`**, **`/arch:AVX512`**, or **`/arch:AVX10.1`** compiler option is specified. +The `__AVX2__` preprocessor symbol is defined when the **`/arch:AVX2`**, **`/arch:AVX512`**, or **`/arch:AVX10.1`** compiler option is specified. +The `__AVX512F__`, `__AVX512CD__`, `__AVX512BW__`, `__AVX512DQ__`, and `__AVX512VL__` preprocessor symbols are defined when the **`/arch:AVX512`**, or **`/arch:AVX10.1`** compiler option is specified. +The `__AVX10_VER__` preprocessor symbol is defined when the **`/arch:AVX10.1`** compiler option is specified. It indicates the AVX10 version the compiler is targeting. For more information, see [Predefined macros](../../preprocessor/predefined-macros.md). +The **`/arch:AVX2`** option was introduced in Visual Studio 2013 Update 2, version 12.0.34567.1. +Limited support for **`/arch:AVX512`** was added in Visual Studio 2017, and expanded in Visual Studio 2019. +Support for **`/arch:AVX10.1`** was added in Visual Studio 2022. -### To set the /arch:AVX, /arch:AVX2 or /arch:AVX512 compiler option in Visual Studio +### To set the `/arch` compiler option in Visual Studio 1. Open the **Property Pages** dialog box for the project. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **C/C++** > **Code Generation** property page. -1. In the **Enable Enhanced Instruction Set** drop-down box, choose **Advanced Vector Extensions (/arch:AVX)**, **Advanced Vector Extensions 2 (/arch:AVX2)** or **Advanced Vector Extensions 512 (/arch:AVX512)**. +1. Modify the **Enable Enhanced Instruction Set** property. ### To set this compiler option programmatically @@ -59,6 +77,6 @@ The `__AVX__` preprocessor symbol is defined when the **/arch:AVX**, **/arch:AVX ## See also -[/arch (Minimum CPU Architecture)](arch-minimum-cpu-architecture.md)
-[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) +[`/arch` (Minimum CPU Architecture)](arch-minimum-cpu-architecture.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/arch-x86.md b/docs/build/reference/arch-x86.md index 73eefc119a..cb71ce0716 100644 --- a/docs/build/reference/arch-x86.md +++ b/docs/build/reference/arch-x86.md @@ -1,64 +1,68 @@ --- description: "Learn more about: /arch (x86)" title: "/arch (x86)" -ms.date: "10/01/2019" -ms.assetid: 9dd5a75d-06e4-4674-aade-33228486078d +ms.date: 06/30/2022 +f1_keywords: ["/arch:IA32", "/arch:SSE", "/arch:SSE2", "/arch:AVX", "/arch:AVX2", "/arch:AVX512", "/arch:AVX10.1"] +helpviewer_keywords: ["/arch:IA32 compiler option [C++]", "/arch:SSE compiler option [C++]", "/arch:SSE2 compiler option [C++]", "/arch:AVX compiler option [C++]", "/arch:AVX2 compiler option [C++]", "/arch:AVX512 compiler option [C++]", "/arch:AVX10.1 compiler option [C++]"] --- -# /arch (x86) +# `/arch` (x86) -Specifies the architecture for code generation on x86. Also see [/arch (x64)](arch-x64.md) and [/arch (ARM)](arch-arm.md). +Specifies the architecture for code generation on x86. These switches apply to the x86 (32-bit) targeting version of the compiler. For more information on **`/arch`** for other target architectures, see [`/arch` (ARM64)](arch-arm64.md), [`/arch` (x64)](arch-x64.md), and [`/arch` (ARM)](arch-arm.md). ## Syntax -``` -/arch:[IA32|SSE|SSE2|AVX|AVX2|AVX512] -``` +> **`/arch:`**\[**`IA32`**|**`SSE`**|**`SSE2`**|**`AVX`**|**`AVX2`**|**`AVX512`**|**`AVX10.1`**] ## Arguments -**/arch:IA32**
+**`/arch:IA32`**\ Specifies no enhanced instructions and also specifies x87 for floating-point calculations. -**/arch:SSE**
-Enables the use of SSE instructions. +**`/arch:SSE`**\ +Enables Intel Streaming SIMD Extensions. -**/arch:SSE2**
-Enables the use of SSE2 instructions. This is the default instruction on x86 platforms if no **/arch** option is specified. +**`/arch:SSE2`**\ +Enables Intel Streaming SIMD Extensions 2. The default instruction set is SSE2 if no **`/arch`** option is specified. -**/arch:AVX**
-Enables the use of Intel Advanced Vector Extensions instructions. +**`/arch:AVX`**\ +Enables Intel Advanced Vector Extensions. -**/arch:AVX2**
-Enables the use of Intel Advanced Vector Extensions 2 instructions. +**`/arch:AVX2`**\ +Enables Intel Advanced Vector Extensions 2. -**/arch:AVX512**
-Enables the use of Intel Advanced Vector Extensions 512 instructions. +**`/arch:AVX512`**\ +Enables Intel Advanced Vector Extensions 512. + +**`/arch:AVX10.1`**\ +Enables Intel Advanced Vector Extensions 10 version 1. ## Remarks -The **/arch** option enables or disables the use of certain instruction set extensions, particularly for vector calculation, available in processors from Intel and AMD. In general, more recently introduced processors may support additional extensions over those supported by older processors, although you should consult the documentation for a particular processor or test for instruction set extension support using [__cpuid](../../intrinsics/cpuid-cpuidex.md) before executing code using an instruction set extension. +The **`/arch`** option enables or disables the use of certain instruction set extensions, particularly for vector calculation, available in processors from Intel and AMD. In general, more recently introduced processors may support extensions beyond the ones supported by older processors. You should consult the documentation for a particular processor or test for instruction set extension support using [`__cpuid`](../../intrinsics/cpuid-cpuidex.md) before executing code using an instruction set extension. You can also use the [`__check_isa_support`](../../intrinsics/check-isa-arch-support.md) intrinsic to check for more frequently used CPU features. + +**`/arch`** only affects code generation for native functions. When you use [`/clr`](clr-common-language-runtime-compilation.md) to compile, **`/arch`** has no effect on code generation for managed functions. -**/arch** only affects code generation for native functions. When you use [/clr](clr-common-language-runtime-compilation.md) to compile, **/arch** has no effect on code generation for managed functions. +The **`/arch`** options refer to instruction set extensions with the following characteristics: -The **/arch** options refer to instruction set extensions with the following characteristics: +- **`IA32`** is the legacy 32-bit x86 instruction set without any vector operations and using x87 for floating-point calculations. -- **IA32** is the legacy 32-bit x86 instruction set without any vector operations and using x87 for floating-point calculations. +- **`SSE`** allows calculation with vectors of up to four single-precision floating-point values. Corresponding scalar floating-point instructions were added as well. -- **SSE** allows calculation with vectors of up to four single-precision floating-point values. Corresponding scalar floating-point instructions were added as well. +- **`SSE2`** allows calculation with 128-bit vectors of single-precision, double-precision and 1, 2, 4, or 8-byte integer values. Double-precision scalar instructions were also added. -- **SSE2** allows calculation with 128-bit vectors of single-precision, double-precision and 1, 2, 4 or 8 byte integer values. Double-precision scalar instructions were also added. +- **`AVX`** introduced an alternative instruction encoding for vector and floating-point scalar instructions. It allows vectors of either 128 bits or 256 bits, and zero-extends all vector results to the full vector size. (For legacy compatibility, SSE-style vector instructions preserve all bits beyond bit 127.) Most floating-point operations are extended to 256 bits. -- **AVX** introduced an alternative instruction encoding for vector and floating-point scalar instructions that allows vectors of either 128 bits or 256 bits, and zero-extends all vector results to the full vector size. (For legacy compatibility, SSE-style vector instructions preserve all bits beyond bit 127.) Most floating-point operations are extended to 256 bits. +- **`AVX2`** extends most integer operations to 256-bit vectors, and enables use of Fused Multiply-Add (FMA) instructions. -- **AVX2** extends most integer operations to 256-bit vectors, and enables use of Fused Multiply-Add (FMA) instructions. +- **`AVX512`** introduced another instruction encoding form that allows 512-bit vectors, masking, embedded rounding/broadcast, and new instructions. The default vector length for **`AVX512`** is 512 bits and can be changed to 256 bits using the [`/vlen`](vlen.md) flag. -- **AVX512** introduced another instruction encoding form that allows 512-bit vectors, plus certain other optional features. Instructions for additional operations were also added. +- **`AVX10.1`** adds more instructions on top of **`AVX-512`**. The default vector length for **`AVX10.1`** is 256 bits and can be changed to 512 bits using the [`/vlen`](vlen.md) flag. -The optimizer chooses when and how to use vector instructions depending on which **/arch** is specified. Scalar floating-point computations are performed with SSE or AVX instructions when available. Some calling conventions specify passing floating-point arguments on the x87 stack, and as a result, your code may use a mixture of both x87 and SSE/AVX instructions for floating-point computations. Integer vector instructions can also be used for some 64-bit integer operations when available. +The optimizer chooses when and how to use vector instructions depending on which **`/arch`** is specified. Scalar floating-point computations are usually performed with SSE or AVX instructions when available. Some calling conventions specify passing floating-point arguments on the x87 stack, and as a result, your code may use a mixture of both x87 and SSE/AVX instructions for floating-point computations. Integer vector instructions can also be used for some 64-bit integer operations when available. -In addition to the vector and floating-point scalar instructions, each **/arch** option may also enable the use of other non-vector instructions that are associated with that option. An example is the CMOVcc instruction family that first appeared on the Intel Pentium Pro processors. Because SSE instructions were introduced with the subsequent Intel Pentium III processor, CMOVcc instructions may be generated except when **/arch:IA32** is specified. +In addition to the vector and floating-point scalar instructions, each **`/arch`** option may also enable the use of other non-vector instructions that are associated with that option. An example is the CMOVcc instruction family that first appeared on the Intel Pentium Pro processors. Because SSE instructions were introduced with the subsequent Intel Pentium III processor, CMOVcc instructions may be generated except when **`/arch:IA32`** is specified. -Floating-point operations are normally rounded to double-precision (64-bit) in x87 code, but you can use `_controlfp` to modify the FP control word, including setting the precision control to extended precision (80-bit) or single-precision (32-bit). For more information, see [_control87, _controlfp, \__control87_2](../../c-runtime-library/reference/control87-controlfp-control87-2.md). SSE and AVX have separate single-precision and double-precision instructions for each operation, so there is no equivalent for SSE/AVX code. This can change how results are rounded when the result of a floating-point operation is used directly in further calculation instead of assigning it to a user variable. Consider the following: +Floating-point operations are normally rounded to double-precision (64-bit) in x87 code, but you can use `_controlfp` to modify the FP control word, including setting the precision control to extended precision (80-bit) or single-precision (32-bit). For more information, see [`_control87`, `_controlfp`, `__control87_2`](../../c-runtime-library/reference/control87-controlfp-control87-2.md). SSE and AVX have separate single-precision and double-precision instructions for each operation, so there's no equivalent for SSE/AVX code. It can change how results are rounded when the result of a floating-point operation is used directly in further calculation instead of assigning it to a user variable. Consider the following operations: ```cpp r = f1 * f2 + d; // Different results are possible on SSE/SSE2. @@ -72,7 +76,7 @@ r = t + d; // This should produce the same overall result // whether x87 stack is used or SSE/SSE2 is used. ``` -**/arch** and [/QIfist](qifist-suppress-ftol.md) cannot be used on the same compiland. The **/QIfist** option changes the rounding behavior of floating-point to integer conversion. The default behavior is to truncate (round toward zero), whereas the **/QIfist** option specifies use of the floating-point environment rounding mode. Because this changes the behavior of all floating-point to integer conversions, this flag has been deprecated. When compiling for SSE or AVX you can round a floating-point value to an integer using the floating-point environment rounding mode by using an intrinsic function sequence: +**`/arch`** and [`/QIfist`](qifist-suppress-ftol.md) can't be used together. The **`/QIfist`** option changes the rounding behavior of floating-point to integer conversion. The default behavior is to truncate (round toward zero), whereas the **`/QIfist`** option specifies use of the [floating-point environment](fp-specify-floating-point-behavior.md) rounding mode. Because the option changes the behavior of all floating-point to integer conversions, **`/QIfist`** is deprecated. When compiling for SSE or AVX, you can round a floating-point value to an integer using the floating-point environment rounding mode by using an intrinsic function sequence: ```cpp int convert_float_to_int(float x) { @@ -84,9 +88,9 @@ int convert_double_to_int(double x) { } ``` -The `_M_IX86_FP`, `__AVX__`, `__AVX2__`, `__AVX512F__`, `__AVX512CD__`, `__AVX512BW__`, `__AVX512DQ__` and `__AVX512VL__` macros indicate which, if any, **/arch** compiler option was used. For more information, see [Predefined Macros](../../preprocessor/predefined-macros.md). The **/arch:AVX2** option and `__AVX2__` macro were introduced in Visual Studio 2013 Update 2, version 12.0.34567.1. Limited support for **/arch:AVX512** was added in Visual Studio 2017, and expanded in Visual Studio 2019. +The `_M_IX86_FP`, `__AVX__`, `__AVX2__`, `__AVX512F__`, `__AVX512CD__`, `__AVX512BW__`, `__AVX512DQ__`, `__AVX512VL__`, and `__AVX10_VER__` macros indicate which, if any, **`/arch`** compiler option was used. For more information, see [Predefined macros](../../preprocessor/predefined-macros.md). The **`/arch:AVX2`** option, and `__AVX2__` macro were introduced in Visual Studio 2013 Update 2, version 12.0.34567.1. Limited support for **`/arch:AVX512`** was added in Visual Studio 2017, and expanded in Visual Studio 2019. Support for **`/arch:AVX10.1`** was added in Visual Studio 2022. -### To set this compiler option for AVX, AVX2, AVX512, IA32, SSE, or SSE2 in Visual Studio +### To set the `/arch` compiler option in Visual Studio 1. Open the **Property Pages** dialog box for the project. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). @@ -100,6 +104,6 @@ The `_M_IX86_FP`, `__AVX__`, `__AVX2__`, `__AVX512F__`, `__AVX512CD__`, `__AVX51 ## See also -[/arch (Minimum CPU Architecture)](arch-minimum-cpu-architecture.md)
-[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) +[`/arch` (Minimum CPU Architecture)](arch-minimum-cpu-architecture.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/arm64-function-pad-min-x64.md b/docs/build/reference/arm64-function-pad-min-x64.md new file mode 100644 index 0000000000..28fabf8505 --- /dev/null +++ b/docs/build/reference/arm64-function-pad-min-x64.md @@ -0,0 +1,43 @@ +--- +description: "Learn more about: /ARM64XFUNCTIONPADMINX64 (Minimum padding between x64 functions in an ARM64X image)" +title: "/ARM64XFUNCTIONPADMINX64 (Minimum x64 function padding)" +ms.date: 01/08/2024 +helpviewer_keywords: ["/ARM64XFUNCTIONPADMINX64 linker option", "-ARM64XFUNCTIONPADMINX64 linker option", "ARM64XFUNCTIONPADMINX64 linker option"] +--- +# /ARM64XFUNCTIONPADMINX64 (Minimum x64 function padding) + +Specifies the minimum number of bytes of padding between x64 functions in ARM64X images. + +## Syntax + +``` +/ARM64XFUNCTIONPADMINX64:[number] +``` + +## Arguments + +*number*\ +The minimum number of bytes of padding between x64 functions. + +## Remarks + +This switch ensures that there is at least as much padding between X64 functions in an ARM64X image as specified. There may be more padding to meet architecture alignment requirements. + +This flag is available in Visual Studio 17.8 and later. + +### To set this linker option in the Visual Studio development environment + +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** > **Linker** > **Command Line** property page. +1. Modify the **Additional Options** property to include **/ARM64XFUNCTIONPADMINX64:**`number`, where `number` is the minimum number of bytes of padding to put between x64 functions, and then choose **OK**. + +### To set this linker option programmatically + +- See . + +## See also + +[`/FUNCTIONPADMIN` (Create hotpatchable image)](../reference/functionpadmin-create-hotpatchable-image.md)\ +[`/NOFUNCTIONPADSECTION`](no-function-pad-section.md)\ +[MSVC Linker Options](linker-options.md)\ +[MSVC linker reference](linking.md) diff --git a/docs/build/reference/assemblydebug-add-debuggableattribute.md b/docs/build/reference/assemblydebug-add-debuggableattribute.md index 62c71671dc..fb77f5d492 100644 --- a/docs/build/reference/assemblydebug-add-debuggableattribute.md +++ b/docs/build/reference/assemblydebug-add-debuggableattribute.md @@ -1,56 +1,58 @@ --- description: "Learn more about: /ASSEMBLYDEBUG (Add DebuggableAttribute)" title: "/ASSEMBLYDEBUG (Add DebuggableAttribute)" -ms.date: "11/04/2016" +ms.date: 05/11/2022 f1_keywords: ["VC.Project.VCLinkerTool.AssemblyDebug", "/ASSEMBLYDEBUG"] helpviewer_keywords: ["/ASSEMBLYDEBUG linker option", "-ASSEMBLYDEBUG linker option", "ASSEMBLYDEBUG linker option"] ms.assetid: 94443af3-470c-41d7-83a0-7434563d7982 --- -# /ASSEMBLYDEBUG (Add DebuggableAttribute) +# `/ASSEMBLYDEBUG` (Add DebuggableAttribute) -``` -/ASSEMBLYDEBUG[:DISABLE] -``` +Specify whether to emit the `DebuggableAttribute` attribute with debug information tracking and to disable JIT optimizations. -/ASSEMBLYDEBUG emits the **DebuggableAttribute** attribute with debug information tracking and disables JIT optimizations. This is the same as specifying the following attribute in source: +## Syntax -``` +> **`/ASSEMBLYDEBUG`**\[**`:DISABLE`**] + +## Remarks + +The **`/ASSEMBLYDEBUG`** linker option emits the `DebuggableAttribute` attribute with debug information tracking and disables JIT optimizations. This option is the same as specifying the following attribute in source: + +```cpp [assembly:Debuggable(true, true)]; // same as /ASSEMBLYDEBUG ``` -/ASSEMBLYDEBUG:DISABLE emits the **DebuggableAttribute** attribute but disables the tracking of debug information and enables JIT optimizations. This is the same as specifying the following attribute in source: +**`/ASSEMBLYDEBUG:DISABLE`** emits the `DebuggableAttribute` attribute but disables the tracking of debug information and enables JIT optimizations. This option is the same as specifying the following attribute in source: -``` +```cpp [assembly:Debuggable(false, false)]; // same as /ASSEMBLYDEBUG:DISABLE ``` -The default is to not emit the **DebuggableAttribute** attribute. +By default, the linker doesn't emit the `DebuggableAttribute` attribute. -DebuggableAttribute can also be added to an assembly directly in source code. For example, +`DebuggableAttribute` can also be added to an assembly directly in source code. For example: -``` +```cpp [assembly:Debuggable(true, true)]; // same as /ASSEMBLYDEBUG ``` -## Remarks - -It is necessary to explicitly specify that a managed image be debuggable. Using [/Zi](z7-zi-zi-debug-information-format.md) alone is not sufficient. +You must explicitly specify that a managed image is debuggable. The [`/Zi`](z7-zi-zi-debug-information-format.md) option alone is insufficient. Other linker options that affect assembly generation are: -- [/ASSEMBLYLINKRESOURCE](assemblylinkresource-link-to-dotnet-framework-resource.md) +- [`/ASSEMBLYLINKRESOURCE`](assemblylinkresource-link-to-dotnet-framework-resource.md) -- [/ASSEMBLYMODULE](assemblymodule-add-a-msil-module-to-the-assembly.md) +- [`/ASSEMBLYMODULE`](assemblymodule-add-a-msil-module-to-the-assembly.md) -- [/ASSEMBLYRESOURCE](assemblyresource-embed-a-managed-resource.md) +- [`/ASSEMBLYRESOURCE`](assemblyresource-embed-a-managed-resource.md) -- [/DELAYSIGN](delaysign-partially-sign-an-assembly.md) +- [`/DELAYSIGN`](delaysign-partially-sign-an-assembly.md) -- [/KEYCONTAINER](keycontainer-specify-a-key-container-to-sign-an-assembly.md) +- [`/KEYCONTAINER`](keycontainer-specify-a-key-container-to-sign-an-assembly.md) -- [/KEYFILE](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md) +- [`/KEYFILE`](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md) -- [/NOASSEMBLY](noassembly-create-a-msil-module.md) +- [`/NOASSEMBLY`](noassembly-create-a-msil-module.md) ### To set this linker option in the Visual Studio development environment @@ -66,5 +68,5 @@ Other linker options that affect assembly generation are: ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/assemblylinkresource-link-to-dotnet-framework-resource.md b/docs/build/reference/assemblylinkresource-link-to-dotnet-framework-resource.md index 8a36b426db..bb0cd45a3f 100644 --- a/docs/build/reference/assemblylinkresource-link-to-dotnet-framework-resource.md +++ b/docs/build/reference/assemblylinkresource-link-to-dotnet-framework-resource.md @@ -1,49 +1,51 @@ --- -description: "Learn more about: /ASSEMBLYLINKRESOURCE (Link to .NET Framework Resource)" -title: "/ASSEMBLYLINKRESOURCE (Link to .NET Framework Resource)" -ms.date: "11/04/2016" +description: "Learn more about: /ASSEMBLYLINKRESOURCE (Link to .NET Framework resource)" +title: "/ASSEMBLYLINKRESOURCE (Link to .NET Framework resource)" +ms.date: 05/11/2022 f1_keywords: ["/ASSEMBLYLINKRESOURCE", "VC.Project.VCLinkerTool.AssemblyLinkResource"] helpviewer_keywords: ["-ASSEMBLYLINKRESOURCE linker option", "ASSEMBLYLINKRESOURCE linker option", "/ASSEMBLYLINKRESOURCE linker option"] ms.assetid: 8b6ad184-1b33-47a4-8513-4803cf915b64 --- -# /ASSEMBLYLINKRESOURCE (Link to .NET Framework Resource) +# `/ASSEMBLYLINKRESOURCE` (Link to .NET Framework resource) -``` -/ASSEMBLYLINKRESOURCE:filename -``` +Create a link to a .NET Framework resource in the output file. + +## Syntax + +> **`/ASSEMBLYLINKRESOURCE:`*`filename`*** ## Arguments -*filename*
-The .NET Framework resource file to which you want to link from the assembly. +*`filename`* +The .NET Framework resource file to link from the assembly. ## Remarks -The /ASSEMBLYLINKRESOURCE option creates a link to a .NET Framework resource in the output file; the resource file is not placed in the output file. [/ASSEMBLYRESOURCE](assemblyresource-embed-a-managed-resource.md) embeds a resource file in the output file. +The **`/ASSEMBLYLINKRESOURCE`** linker option creates a link to a .NET Framework resource in the output file. The resource file isn't placed in the output file. Use the [`/ASSEMBLYRESOURCE`](assemblyresource-embed-a-managed-resource.md) option to embed a resource file in the output file. Linked resources are public in the assembly when created with the linker. -/ASSEMBLYLINKRESOURCE requires that the compilation include [/clr](clr-common-language-runtime-compilation.md); [/LN](ln-create-msil-module.md) or [/NOASSEMBLY](noassembly-create-a-msil-module.md) is not allowed with /ASSEMBLYLINKRESOURCE. +**`/ASSEMBLYLINKRESOURCE`** requires the [`/clr`](clr-common-language-runtime-compilation.md) compiler option. The [`/LN`](ln-create-msil-module.md) or [`/NOASSEMBLY`](noassembly-create-a-msil-module.md) options aren't allowed with **`/ASSEMBLYLINKRESOURCE`**. -If *filename* is a .NET Framework resource file created, for example, by [Resgen.exe](/dotnet/framework/tools/resgen-exe-resource-file-generator) or in the development environment, it can be accessed with members in the **System.Resources** namespace. For more information, see [System.Resources.ResourceManager](/dotnet/api/system.resources.resourcemanager). For all other resources, use the **GetManifestResource**\* methods in the **System.Reflection.Assembly** class to access the resource at run time. +If *`filename`* is a .NET Framework resource file that's created, for example, by [`Resgen.exe`](/dotnet/framework/tools/resgen-exe-resource-file-generator) or in the development environment, it can be accessed with members in the `System.Resources` namespace. For more information, see [`System.Resources.ResourceManager`](/dotnet/api/system.resources.resourcemanager). For all other resources, use the `GetManifestResource*` methods in the `System.Reflection.Assembly` class to access the resource at run time. -*filename* can be any file format. For example, you may want to make a native DLL part of the assembly, so it can be installed into the Global Assembly Cache and accessed from managed code in the assembly. +*`filename`* can have any file format. For example, you may want to make a native DLL part of the assembly. Then it can be installed into the Global Assembly Cache and accessed from managed code in the assembly. Other linker options that affect assembly generation are: -- [/ASSEMBLYDEBUG](assemblydebug-add-debuggableattribute.md) +- [`/ASSEMBLYDEBUG`](assemblydebug-add-debuggableattribute.md) -- [/ASSEMBLYMODULE](assemblymodule-add-a-msil-module-to-the-assembly.md) +- [`/ASSEMBLYMODULE`](assemblymodule-add-a-msil-module-to-the-assembly.md) -- [/ASSEMBLYRESOURCE](assemblyresource-embed-a-managed-resource.md) +- [`/ASSEMBLYRESOURCE`](assemblyresource-embed-a-managed-resource.md) -- [/DELAYSIGN](delaysign-partially-sign-an-assembly.md) +- [`/DELAYSIGN`](delaysign-partially-sign-an-assembly.md) -- [/KEYCONTAINER](keycontainer-specify-a-key-container-to-sign-an-assembly.md) +- [`/KEYCONTAINER`](keycontainer-specify-a-key-container-to-sign-an-assembly.md) -- [/KEYFILE](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md) +- [`/KEYFILE`](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md) -- [/NOASSEMBLY](noassembly-create-a-msil-module.md) +- [`/NOASSEMBLY`](noassembly-create-a-msil-module.md) ### To set this linker option in the Visual Studio development environment @@ -51,7 +53,7 @@ Other linker options that affect assembly generation are: 1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. -1. Type the option into the **Additional Options** box. +1. Enter the option in **Additional Options**. Choose **OK** or **Apply** to apply the change. ### To set this linker option programmatically @@ -59,5 +61,5 @@ Other linker options that affect assembly generation are: ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/assemblymodule-add-a-msil-module-to-the-assembly.md b/docs/build/reference/assemblymodule-add-a-msil-module-to-the-assembly.md index 59423c6bbc..60b001d27d 100644 --- a/docs/build/reference/assemblymodule-add-a-msil-module-to-the-assembly.md +++ b/docs/build/reference/assemblymodule-add-a-msil-module-to-the-assembly.md @@ -1,53 +1,53 @@ --- -description: "Learn more about: /ASSEMBLYMODULE (Add a MSIL Module to the Assembly)" -title: "/ASSEMBLYMODULE (Add a MSIL Module to the Assembly)" -ms.date: "11/04/2016" +description: "Learn more about: /ASSEMBLYMODULE (Add an MSIL module to the assembly)" +title: "/ASSEMBLYMODULE (Add an MSIL module to the assembly)" +ms.date: 05/11/2022 f1_keywords: ["/assemblymodule", "VC.Project.VCLinkerTool.AddModuleNamesToAssembly"] helpviewer_keywords: ["ASSEMBLYMODULE linker option", "assemblies [C++], adding modules to", "assemblies [C++]", "/ASSEMBLYMODULE linker option", "-ASSEMBLYMODULE linker option"] ms.assetid: 67357da8-e4b6-49fd-932c-329a5777f143 --- -# /ASSEMBLYMODULE (Add a MSIL Module to the Assembly) +# `/ASSEMBLYMODULE` (Add an MSIL module to the assembly) -``` -/ASSEMBLYMODULE:filename -``` +## Syntax -## Arguments +> **`/ASSEMBLYMODULE:`*`filename`*** -*filename*
+### Arguments + +*`filename`*\ The module you want to include in this assembly. ## Remarks -The /ASSEMBLYMODULE option allows you to add a module reference to an assembly. Type information in the module will not be available to the assembly program that added the module reference. However, type information in the module will be available to any program that references the assembly. +The **`/ASSEMBLYMODULE`** linker option allows you to add a module reference to an assembly. Type information in the module won't be available to the assembly program that added the module reference. However, type information in the module will be available to any program that references the assembly. -Use [#using](../../preprocessor/hash-using-directive-cpp.md) to both add a module reference to an assembly and make the module's type information available to the assembly program. +Use [`#using`](../../preprocessor/hash-using-directive-cpp.md) to both add a module reference to an assembly and make the module's type information available to the assembly program. For example, consider the following scenario: -1. Create a module with [/LN](ln-create-msil-module.md). +1. Create a module with [`/LN`](ln-create-msil-module.md). -1. Use /ASSEMBLYMODULE in a different project to include the module in the current compilation, which will create an assembly. This project will not reference the module with `#using`. +1. Use **`/ASSEMBLYMODULE`** in a different project to include the module in the current compilation, which creates an assembly. This project won't reference the module with `#using`. 1. Any project that references this assembly can now also use types from the module. Other linker options that affect assembly generation are: -- [/ASSEMBLYDEBUG](assemblydebug-add-debuggableattribute.md) +- [`/ASSEMBLYDEBUG`](assemblydebug-add-debuggableattribute.md) -- [/ASSEMBLYLINKRESOURCE](assemblylinkresource-link-to-dotnet-framework-resource.md) +- [`/ASSEMBLYLINKRESOURCE`](assemblylinkresource-link-to-dotnet-framework-resource.md) -- [/ASSEMBLYRESOURCE](assemblyresource-embed-a-managed-resource.md) +- [`/ASSEMBLYRESOURCE`](assemblyresource-embed-a-managed-resource.md) -- [/DELAYSIGN](delaysign-partially-sign-an-assembly.md) +- [`/DELAYSIGN`](delaysign-partially-sign-an-assembly.md) -- [/NOASSEMBLY](noassembly-create-a-msil-module.md) +- [`/NOASSEMBLY`](noassembly-create-a-msil-module.md) -- [/KEYFILE](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md) +- [`/KEYFILE`](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md) -- [/KEYCONTAINER](keycontainer-specify-a-key-container-to-sign-an-assembly.md) +- [`/KEYCONTAINER`](keycontainer-specify-a-key-container-to-sign-an-assembly.md) -The MSVC linker accepts .netmodule files as input and the output file produced by the linker will be an assembly or .netmodule with no run-time dependence on any of the .netmodules that were input to the linker. For more information, see [.netmodule Files as Linker Input](netmodule-files-as-linker-input.md). +The MSVC linker accepts *`.netmodule`* files as input and the output file produced by the linker will be an assembly or *`.netmodule`* file with no run-time dependence on any of the *`.netmodule`* files that were input to the linker. For more information, see [`.netmodule` files as linker input](netmodule-files-as-linker-input.md). ### To set this linker option in the Visual Studio development environment @@ -63,5 +63,5 @@ The MSVC linker accepts .netmodule files as input and the output file produced b ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/assemblyresource-embed-a-managed-resource.md b/docs/build/reference/assemblyresource-embed-a-managed-resource.md index ee50a4984d..c21d423109 100644 --- a/docs/build/reference/assemblyresource-embed-a-managed-resource.md +++ b/docs/build/reference/assemblyresource-embed-a-managed-resource.md @@ -1,50 +1,52 @@ --- -description: "Learn more about: /ASSEMBLYRESOURCE (Embed a Managed Resource)" -title: "/ASSEMBLYRESOURCE (Embed a Managed Resource)" -ms.date: "11/04/2016" +description: "Learn more about: /ASSEMBLYRESOURCE (Embed a managed resource)" +title: "/ASSEMBLYRESOURCE (Embed a managed resource)" +ms.date: 05/11/2022 f1_keywords: ["VC.Project.VCLinkerTool.EmbedManagedResourceFile", "/ASSEMBLYRESOURCE"] helpviewer_keywords: ["ASSEMBLYRESOURCE linker option", "assemblies [C++]", "-ASSEMBLYRESOURCE linker option", "assemblies [C++], linking resource files", "/ASSEMBLYRESOURCE linker option"] ms.assetid: 0ce6e1fb-921b-4b1b-a59c-d35388d789f2 --- -# /ASSEMBLYRESOURCE (Embed a Managed Resource) +# `/ASSEMBLYRESOURCE` (Embed a managed resource) -``` -/ASSEMBLYRESOURCE:filename[,[name][,PRIVATE]] -``` +Embeds a managed resource in an assembly. -## Parameters +## Syntax -*filename*
+> **`/ASSEMBLYRESOURCE:`*`filename`***\[**`,`**\[***`name`***]\[**`,PRIVATE`**]] + +## Arguments + +*`filename`*\ The managed resource you want to embed in this assembly. -*name*
+*`name`*\ Optional. The logical name for the resource; the name used to load the resource. The default is the name of the file. -Optionally, you can specify if the file should be private in the assembly manifest. By default, *name* is public in the assembly. +Optionally, you can use `PRIVATE` to specify if the file should be private in the assembly manifest. By default, *`name`* is public in the assembly. ## Remarks -Use the /ASSEMBLYRESOURCE option to embed a resource in an assembly. +Use the **`/ASSEMBLYRESOURCE`** linker option to embed a resource in an assembly. -Resources are public in the assembly when created with the linker. The linker does not allow you to rename the resource in the assembly. +Resources are public in the assembly when created with the linker. The linker doesn't allow you to rename the resource in the assembly. -If *filename* is a .NET Framework resource (.resources) file created, for example, by the [Resource File Generator (Resgen.exe)](/dotnet/framework/tools/resgen-exe-resource-file-generator) or in the development environment, it can be accessed with members in the **System.Resources** namespace (see [System.Resources.ResourceManager](/dotnet/api/system.resources.resourcemanager) for more information). For all other resources, use the **GetManifestResource**\* methods in **System.Reflection.Assembly** class to access the resource at run time. +If *`filename`* is a .NET Framework resource (*`.resources`*) file created, for example, by the [Resource file generator (`Resgen.exe`)](/dotnet/framework/tools/resgen-exe-resource-file-generator) or in the development environment, it can be accessed with members in the `System.Resources` namespace. For more information, see [`System.Resources.ResourceManager`](/dotnet/api/system.resources.resourcemanager). For all other resources, use the `GetManifestResource*` methods in the `System.Reflection.Assembly` class to access the resource at run time. Other linker options that affect assembly generation are: -- [/ASSEMBLYDEBUG](assemblydebug-add-debuggableattribute.md) +- [`/ASSEMBLYDEBUG`](assemblydebug-add-debuggableattribute.md) -- [/ASSEMBLYLINKRESOURCE](assemblylinkresource-link-to-dotnet-framework-resource.md) +- [`/ASSEMBLYLINKRESOURCE`](assemblylinkresource-link-to-dotnet-framework-resource.md) -- [/ASSEMBLYMODULE](assemblymodule-add-a-msil-module-to-the-assembly.md) +- [`/ASSEMBLYMODULE`](assemblymodule-add-a-msil-module-to-the-assembly.md) -- [/DELAYSIGN](delaysign-partially-sign-an-assembly.md) +- [`/DELAYSIGN`](delaysign-partially-sign-an-assembly.md) -- [/KEYFILE](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md) +- [`/KEYFILE`](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md) -- [/KEYCONTAINER](keycontainer-specify-a-key-container-to-sign-an-assembly.md) +- [`/KEYCONTAINER`](keycontainer-specify-a-key-container-to-sign-an-assembly.md) -- [/NOASSEMBLY](noassembly-create-a-msil-module.md) +- [`/NOASSEMBLY`](noassembly-create-a-msil-module.md) ### To set this linker option in the Visual Studio development environment @@ -60,5 +62,5 @@ Other linker options that affect assembly generation are: ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/at-specify-a-linker-response-file.md b/docs/build/reference/at-specify-a-linker-response-file.md index db8b195c3c..b72b81d9d8 100644 --- a/docs/build/reference/at-specify-a-linker-response-file.md +++ b/docs/build/reference/at-specify-a-linker-response-file.md @@ -1,37 +1,37 @@ --- -description: "Learn more about: @ (Specify a Linker Response File)" -title: "@ (Specify a Linker Response File)" -ms.date: "09/05/2018" +description: "Learn more about: @ (Specify a linker response file)" +title: "@ (Specify a linker response file)" +ms.date: 05/11/2022 f1_keywords: ["@"] helpviewer_keywords: ["linker [C++], response files", "command files [C++]", "command files [C++], linker response file", "@ linker option", "response files, C/C++ linker"] ms.assetid: 5530014f-17d0-4f6b-a6b0-a6ba34f34cfd --- -# @ (Specify a Linker Response File) +# `@` (Specify a linker response file) Specifies a linker response file. ## Syntax -> **\@**response_file +> **`@`** *`response_file`* ## Arguments -*response_file*
-A text file specifying linker commands. +*`response_file`*\ +A text file that contains linker commands. ## Remarks -See [@ (Specify a Compiler Response File)](at-specify-a-compiler-response-file.md) for more information. +For more information, see [`@` (Specify a compiler response file)](at-specify-a-compiler-response-file.md). ### To set this linker option in the Visual Studio development environment -- This linker option is not available from the Visual Studio development environment. +- This linker option isn't available from the Visual Studio development environment. ### To set this linker option programmatically -- This linker option cannot be changed programmatically. +- This linker option can't be changed programmatically. ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/atl-program-or-control-source-and-header-files.md b/docs/build/reference/atl-program-or-control-source-and-header-files.md index 827a02bd71..5057444504 100644 --- a/docs/build/reference/atl-program-or-control-source-and-header-files.md +++ b/docs/build/reference/atl-program-or-control-source-and-header-files.md @@ -1,26 +1,60 @@ --- -description: "Learn more about: ATL Program or Control Source and Header Files" -title: "ATL Program or Control Source and Header Files" -ms.date: "11/04/2016" +description: "Learn more about: ATL program or control source and header files" +title: "ATL program or control source and header files" +ms.date: 09/27/2022 helpviewer_keywords: ["file types [C++], ATL source and headers"] ms.assetid: cb65372f-4880-4007-b582-a52eaa568fd1 --- -# ATL Program or Control Source and Header Files +# ATL program or control source and header files -The following files are created when you create an ATL project in Visual Studio, depending on the options you select for the project you create. +The following files are created when you create an ATL project in Visual Studio, depending on the options you select for the project you create. The file names depend on the name you choose for your project, which we'll call *`ProjectName`*. -All of these files are located in the *Projname* directory, and in either the Header Files (.h files) folder or Source Files (.cpp files) folder in Solution Explorer. +All of the files created by the project template are located in the *`ProjectName`* and *`ProjectNamePS`* project directories. In Solution Explorer, the *`ProjectName`* files are located in the **Generated Files**, **Header Files**, **Resource Files**, and **Source Files** folders. The *`ProjectNamePS`* files are in the **Generated Files** and **Source Files** folders. Not all files listed here are generated for every project type. Files in the **Generated Files** folder are generated automatically by the MIDL compiler; they shouldn't be edited directly. -|File name|Description| -|---------------|-----------------| -|*Projname*.h|The main include file containing the C++ interface definitions and GUID declarations of the items defined in ATLSample.idl. It is regenerated by MIDL during compilation.| -|*Projname*.cpp|The main program source file. It contains the implementation of your DLL's exports for an in-process server and the implementation of `WinMain` for a local server. For a service, this additionally implements all the service management functions.| -|Resource.h|The header file for the resource file.| -|StdAfx.cpp|Includes the files StdAfx.h and Atlimpl.cpp.| -|StdAfx.h|Includes the ATL header files.| +::: moniker range=">=msvc-150" + +| File name | Description | +|--|--| +| *`ProjectName_i.c`* | The generated source file containing the C++ IID and CLSID definitions and GUID declarations of the items defined in *`ProjectName.idl`*. Don't edit this file; it's regenerated by MIDL during compilation. Link this file with the server and any clients. | +| *`ProjectName_i.h`* | The generated include file containing the C++ interface declarations and GUID declarations of the items defined in *`ProjectName.idl`*. Don't edit this file; it's regenerated by MIDL during compilation. Include this file in source files for the server and any clients. | +| *`ProjectName.rc`* | The main program resource file. | +| *`ProjectName.rgs`* | The main program registration file. | +| *`ProjectName.cpp`* | The main program source file. In DLL projects, it contains the implementation of your DLL's exports for an in-process server. In EXE projects, it contains the implementation of `WinMain` for a local server. For a service, this file implements all the service management functions. | +| *`ProjectName.def`* | In DLL projects, the definitions for your DLL's exports. | +| *`ProjectName.idl`* | The IDL source for your project. The MIDL tool processes this file to produce the type library (*`.tlb`*) and marshaling code. | +| *`framework.h`* | Sets preprocessor macros and includes the ATL header files, the *`targetver.h`* version support header, and the *`Resource.h`* resource file header. | +| *`dllmain.h`* | In DLL projects, the header file for the module class. | +| *`dllmain.cpp`* | In DLL projects, the source file for the `DllMain` function. | +| *`Resource.h`* | The header file for the resource file. | +| *`targetver.h`* | Includes *`SDKDDKVer.h`*. To build your application for a previous Windows platform, include *`WinSDKVer.h`* and set the `_WIN32_WINNT` macro to the platform you wish to support before including *`SDKDDKVer.h`*. | +| *`pch.cpp`* | Includes the file *`pch.h`*. | +| *`pch.h`* | Includes the *`framework.h`* header file. | + +::: moniker-end + +::: moniker range="msvc-140" + +| File name | Description | +|--|--| +| *`ProjectName_i.c`* | The generated source file containing the C++ IID and CLSID definitions and GUID declarations of the items defined in *`ProjectName.idl`*. Don't edit this file; it's regenerated by MIDL during compilation. Link this file with the server and any clients. | +| *`ProjectName_i.h`* | The generated include file containing the C++ interface declarations and GUID declarations of the items defined in *`ProjectName.idl`*. Don't edit this file; it's regenerated by MIDL during compilation. Include this file in source files for the server and any clients. | +| *`ProjectName.rc`* | The main program resource file. | +| *`ProjectName.rgs`* | The main program registration file. | +| *`ProjectName.cpp`* | The main program source file. In DLL projects, it contains the implementation of your DLL's exports for an in-process server. In EXE projects, it contains the implementation of `WinMain` for a local server. For a service, this file implements all the service management functions. | +| *`ProjectName.def`* | In DLL projects, the definitions for your DLL's exports. | +| *`ProjectName.idl`* | The IDL source for your project. The MIDL tool processes this file to produce the type library (*`.tlb`*) and marshaling code. | +| *`dllmain.h`* | In DLL projects, the header file for the module class. | +| *`dllmain.cpp`* | In DLL projects, the source file for the `DllMain` function. | +| *`resource.h`* | The header file for the resource file. | +| *`targetver.h`* | Includes *`SDKDDKVer.h`*. To build your application for a previous Windows platform, include *`WinSDKVer.h`* and set the `_WIN32_WINNT` macro to the platform you wish to support before including *`SDKDDKVer.h`*. | +| *`stdafx.cpp`* | Includes the file *`stdafx.h`*. | +| *`stdafx.h`* | Sets preprocessor macros and includes the ATL header files, the *`targetver.h`* version support header, and the *`resource.h`* resource file header. | + +::: moniker-end ## See also -[File Types Created for Visual Studio C++ projects](file-types-created-for-visual-cpp-projects.md)
-[MFC Program or Control Source and Header Files](mfc-program-or-control-source-and-header-files.md)
-[CLR Projects](files-created-for-clr-projects.md) +[File types created for Visual Studio C++ projects](file-types-created-for-visual-cpp-projects.md)\ +[MFC program or control source and header files](mfc-program-or-control-source-and-header-files.md)\ +[Add ATL support to an existing MFC executable or DLL](../../mfc/reference/adding-atl-support-to-your-mfc-project.md)\ +[CLR projects](files-created-for-clr-projects.md) diff --git a/docs/build/reference/await-enable-coroutine-support.md b/docs/build/reference/await-enable-coroutine-support.md index ba252f49b0..9595a434ff 100644 --- a/docs/build/reference/await-enable-coroutine-support.md +++ b/docs/build/reference/await-enable-coroutine-support.md @@ -6,19 +6,27 @@ f1_keywords: ["/await", "-await"] helpviewer_keywords: ["/await enable coroutine support [C++]", "-await enable coroutine support [C++]", "await enable coroutine support [C++]"] ms.assetid: 302c8e69-09b6-4c58-bcdd-0a6a8713a8df --- -# /await (Enable coroutine support) +# `/await` (Enable coroutine support) -Use the **/await** compiler option to enable compiler support for coroutines. +Use the **`/await`** compiler option to enable compiler support for coroutines. ## Syntax -> /await +> **`/await`**\ +> **`/await:strict`** ## Remarks -The **/await** compiler option enables compiler support for C++ coroutines and the keywords **`co_await`**, **`co_yield`**, and **`co_return`**. This option is off by default. For information about support for coroutines in Visual Studio, see the [Visual Studio Team Blog](https://devblogs.microsoft.com/cppblog/category/coroutine/). For more information about the coroutines standard proposal, see [N4628 Working Draft, Technical Specification for C++ Extensions for Coroutines](https://wg21.link/n4628). +The **`/await`** compiler option enables compiler support for C++ coroutines and the keywords **`co_await`**, **`co_yield`**, and **`co_return`**. This option is off by default. For information about support for coroutines in Visual Studio, see the [Visual Studio Team Blog](https://devblogs.microsoft.com/cppblog/category/coroutine/). For more information about the coroutines standard proposal, see [N4628 Working Draft, Technical Specification for C++ Extensions for Coroutines](https://wg21.link/n4628). -The **/await** option is available beginning in Visual Studio 2015. +The **`/await`** option is available beginning in Visual Studio 2015. + +Starting in Visual Studio 2019 version 16.10, the **`/await:strict`** option can be used in place of **`/await`**. The option provides C++20-compatible coroutine support in projects that build in C++14 or C++17 mode. In **`/await:strict`** mode, library support is provided in \ and in the `std` namespace. + +The **`/await:strict`** option disables language extensions present in **`/await`** that weren't adopted into the C++20 standard. Use of such features results in a compiler error. The option also implements coroutine behaviors such as promise parameter preview. These behaviors aren't available under **`/await`** because of binary compatibility issues in older versions of Visual Studio. + +> [!NOTE] +> Coroutine state objects obtained from `coroutine_handle::address()` aren't compatible between **`/await`** and **`/await:strict`** modes. Use of `coroutine_handle::from_address()` on an address obtained from a coroutine handle created by code compiled in an incompatible mode results in undefined behavior. ### To set this compiler option in the Visual Studio development environment @@ -26,7 +34,7 @@ The **/await** option is available beginning in Visual Studio 2015. 1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Enter the **/await** compiler option in the **Additional Options** box. Choose **OK** or **Apply** to save your changes. +1. Enter the **`/await`** or **`/await:strict`** compiler option in the **Additional Options** box. Choose **OK** or **Apply** to save your changes. ### To set this compiler option programmatically diff --git a/docs/build/reference/base-base-address.md b/docs/build/reference/base-base-address.md index e6d026d383..1728032bac 100644 --- a/docs/build/reference/base-base-address.md +++ b/docs/build/reference/base-base-address.md @@ -1,54 +1,51 @@ --- -description: "Learn more about: /BASE (Base Address)" -title: "/BASE (Base Address)" -ms.date: "09/05/2018" +description: "Learn more about: /BASE (Base address)" +title: "/BASE (Base address)" +ms.date: 03/27/2025 f1_keywords: ["/base", "VC.Project.VCLinkerTool.BaseAddress"] helpviewer_keywords: ["base addresses [C++]", "programs [C++], preventing relocation", "semicolon [C++], specifier", "-BASE linker option", "key address size", "environment variables [C++], LIB", "programs [C++], base address", "LIB environment variable", "BASE linker option", "DLLs [C++], linking", "/BASE linker option", "@ symbol for base address", "executable files [C++], base address", "at sign symbol for base address"] -ms.assetid: 00b9f6fe-0bd2-4772-a69c-7365eb199069 --- -# /BASE (Base Address) +# `/BASE` (Base address) Specifies the base address for a program. ## Syntax -> **/BASE:**{*address*[**,**size] | **\@**filename**,**key} +> **`/BASE:`**{*`address`*[**`,`***`size`*] | **`@`***`filename`***`,`***`key`*} ## Remarks > [!NOTE] -> For security reasons, Microsoft recommends you use the [/DYNAMICBASE](dynamicbase-use-address-space-layout-randomization.md) option instead of specifying base addresses for your executables. This generates an executable image that can be randomly rebased at load time by using the address space layout randomization (ASLR) feature of Windows. The /DYNAMICBASE option is on by default. +> For security reasons, Microsoft recommends you use the [`/DYNAMICBASE`](dynamicbase-use-address-space-layout-randomization.md) option instead of specifying base addresses for your executables. **`/DYNAMICBASE`** generates an executable image that can be randomly rebased at load time by using the address space layout randomization (ASLR) feature of Windows. The **`/DYNAMICBASE`** option is on by default. -The /BASE option sets a base address for the program, overriding the default location for an .exe or DLL file. The default base address for an .exe file is 0x400000 for 32-bit images or 0x140000000 for 64-bit images. For a DLL, the default base address is 0x10000000 for 32-bit images or 0x180000000 for 64-bit images. On operating systems that do not support address space layout randomization (ASLR), or when the /DYNAMICBASE:NO option was set, the operating system first attempts to load a program at its specified or default base address. If sufficient space is not available there, the system relocates the program. To prevent relocation, use the [/FIXED](fixed-fixed-base-address.md) option. +The **`/BASE`** linker option sets a base address for the program. It overrides the default location for an EXE or DLL file. The default base address for an EXE file is 0x400000 for 32-bit images or 0x140000000 for 64-bit images. For a DLL, the default base address is 0x10000000 for 32-bit images or 0x180000000 for 64-bit images. On operating systems that don't support address space layout randomization (ASLR), or when the **`/DYNAMICBASE:NO`** option was set, the operating system first attempts to load a program at its specified or default base address. If insufficient space is available there, the system relocates the program. To prevent relocation, use the [`/FIXED`](fixed-fixed-base-address.md) option. -The linker issues an error if *address* is not a multiple of 64K. You can optionally specify the size of the program; the linker issues a warning if the program can't fit in the size you specified. +The linker issues an error if *`address`* isn't a multiple of 64K. You can optionally specify the size of the program. The linker issues a warning if the program can't fit in the size you specified. -On the command line, another way to specify the base address is by using a base address response file. A base address response file is a text file that contains the base addresses and optional sizes of all the DLLs your program will use, and a unique text key for each base address. To specify a base address by using a response file, use an at sign (**\@**) followed by the name of the response file, *filename*, followed by a comma, then the *key* value for the base address to use in the file. The linker looks for *filename* in either the specified path, or if no path is specified, in the directories specified in the LIB environment variable. Each line in *filename* represents one DLL and has the following syntax: +On the command line, another way to specify the base address is by using a *base address response file*. A base address response file is a text file that contains the base addresses and optional sizes of all the DLLs your program uses, and a unique text key for each base address. To specify a base address by using a response file, use an at sign (**`@`**) followed by the name of the response file, *`filename`*, followed by a comma, then the *`key`* value for the base address to use in the file. The linker looks for *`filename`* in either the specified path, or if no path is specified, in the directories specified in the `LIB` environment variable. The fully qualified *`filename`* must not exceed `MAX_PATH` (260 characters). Each line in *`filename`* represents one DLL and has the following syntax: -> *key* *address* [*size*] **;** *comment* +> *`key`* *`address`* \[*`size`*] **`;`** *`comment`* -The *key* is a string of alphanumeric characters and is not case sensitive. It is usually the name of a DLL, but it need not be. The *key* is followed by a base *address* in C-language, hexadecimal, or decimal notation and an optional maximum *size*. All three arguments are separated by spaces or tabs. The linker issues a warning if the specified *size* is less than the virtual address space required by the program. A *comment* is specified by a semicolon (**;**) and can be on the same or a separate line. The linker ignores all text from the semicolon to the end of the line. This example shows part of such a file: +The *`key`* is a string of alphanumeric characters and isn't case sensitive. It's usually the name of a DLL, but that's not required. The *`key`* is followed by a base *`address`* in C-language, hexadecimal, or decimal notation and an optional maximum *`size`*. All three arguments are separated by spaces or tabs. The linker issues a warning if the specified *`size`* is less than the virtual address space required by the program. A *`comment`* is specified by a semicolon (**`;`**) and can be on the same or a separate line. The linker ignores all text from the semicolon to the end of the line. This example shows part of such a file: -``` +```txt main 0x00010000 0x08000000 ; for PROJECT.exe one 0x28000000 0x00100000 ; for DLLONE.DLL two 0x28100000 0x00300000 ; for DLLTWO.DLL ``` -If the file that contains these lines is called DLLS.txt, the following example command applies this information: +If the file that contains these lines is called `DLLS.txt`, the following example command applies this information: -``` +```cmd link dlltwo.obj /dll /base:@dlls.txt,two ``` -Another way to set the base address is by using the *BASE* argument in a [NAME](name-c-cpp.md) or [LIBRARY](library.md) statement. The /BASE and [/DLL](dll-build-a-dll.md) options together are equivalent to the **LIBRARY** statement. +Another way to set the base address is by using the *`BASE`* argument in a [`NAME`](name-c-cpp.md) or [`LIBRARY`](library.md) statement. The **`/BASE`** and [`/DLL`](dll-build-a-dll.md) options together are equivalent to the **`LIBRARY`** statement. ### To set this linker option in the Visual Studio development environment 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** > **Linker** > **Advanced** property page. - 1. Modify the **Base Address** property. ### To set this linker option programmatically @@ -57,5 +54,5 @@ Another way to set the base address is by using the *BASE* argument in a [NAME]( ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/batch-mode-rules.md b/docs/build/reference/batch-mode-rules.md deleted file mode 100644 index 54043e5df7..0000000000 --- a/docs/build/reference/batch-mode-rules.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -description: "Learn more about: Batch-Mode Rules" -title: "Batch-Mode Rules" -ms.date: "11/04/2016" -helpviewer_keywords: ["inference rules in NMAKE", "NMAKE program, inference rules", "batch-mode inference rules in NMAKE"] -ms.assetid: 0650b547-ef19-4455-9bba-fa567dcf88f2 ---- -# Batch-Mode Rules - -``` -{frompath}.fromext{topath}.toext:: - commands -``` - -Batch-mode inference rules provide only one invocation of the inference rule when N commands go through this inference rule. Without batch-mode inference rules, it would require N commands to be invoked. N is the number of dependents that trigger the inference rule. - -Makefiles that contain batch-mode inference rules must use NMAKE version 1.62 or higher. To check the NMAKE version, run the _NMAKE_VER macro available with NMAKE version 1.62 or higher. This macro returns a string representing the Visual C++ product version. - -The only syntactical difference from the standard inference rule is that the batch-mode inference rule is terminated with a double colon (::). - -> [!NOTE] -> The tool being invoked must be able to handle multiple files. The batch-mode inference rule must use `$<` as the macro to access dependent files. - -The batch-mode inference rules can speed up the build process. It is faster to supply files to the compiler in batch, because the compiler driver is invoked only once. For example, the C and C++ compiler performs better when handling a set of files because it can remain memory resident during the process. - -The following example shows how to use batch-mode inference rules: - -``` -# -# sample makefile to illustrate batch-mode inference rules -# -O = . -S = . -Objs = $O/foo1.obj $O/foo2.obj $O/foo2.obj $O/foo3.obj $O/foo4.obj -CFLAGS = -nologo - -all : $(Objs) - -!ifdef NOBatch -{$S}.cpp{$O}.obj: -!else -{$S}.cpp{$O}.obj:: -!endif - $(CC) $(CFLAGS) -Fd$O\ -c $< - -$(Objs) : - -#end of makefile -``` - -NMAKE produces the following output without batch-mode inference rules: - -``` -E:\tmp> nmake -f test.mak -a NOBatch=1 - -Microsoft (R) Program Maintenance Utility Version 7.00.0000 -Copyright (C) Microsoft Corp 1988-2001. All rights reserved. - cl -nologo -Fd.\ -c .\foo1.cpp -foo1.cpp - cl -nologo -Fd.\ -c .\foo2.cpp -foo2.cpp - cl -nologo -Fd.\ -c .\foo3.cpp -foo3.cpp - cl -nologo -Fd.\ -c .\foo4.cpp -foo4.cpp -``` - -NMAKE produces the following result with the batch-mode inference rules: - -``` -E:\tmp> nmake -f test.mak -a - -Microsoft (R) Program Maintenance Utility Version 7.00.0000 -Copyright (C) Microsoft Corp 1988-2001. All rights reserved. - - cl -nologo -Fd.\ -c .\foo1.cpp .\foo2.cpp .\foo3.cpp .\foo4.cpp -foo1.cpp -foo2.cpp -foo3.cpp -foo4.cpp -Generating Code... -``` - -## See also - -[Inference Rules](inference-rules.md) diff --git a/docs/build/reference/bscmake-options.md b/docs/build/reference/bscmake-options.md index 2bd54b3e3d..f9b87e68d5 100644 --- a/docs/build/reference/bscmake-options.md +++ b/docs/build/reference/bscmake-options.md @@ -1,63 +1,67 @@ --- -title: "BSCMAKE Options" +title: "BSCMAKE options" description: "Reference to the Microsoft BSCMAKE utility command-line options." -ms.date: "02/09/2020" +ms.date: 03/21/2022 f1_keywords: ["VC.Project.VCBscMakeTool.OutputFile", "VC.Project.VCBscMakeTool.SuppressStartupBanner", "VC.Project.VCBscMakeTool.PreserveSBR"] helpviewer_keywords: ["/v BSCMAKE option", "Iu BSCMAKE option", "browse information files (.bsc), content", "/Er BSCMAKE option", "NOLOGO BSCMAKE option", "/s BSCMAKE option", "/Ei BSCMAKE option", "/o BSCMAKE option", "/NOLOGO BSCMAKE option", "/Iu BSCMAKE option", "s BSCMAKE option (/s)", "/Em BSCMAKE option", "Em BSCMAKE option", "Es BSCMAKE option", "files [C++], BSCMAKE", "Er BSCMAKE option", "BSCMAKE, options for controlling files", "controlling BSCMAKE options", "El BSCMAKE option", "/El BSCMAKE option", "/Es BSCMAKE option", "Ei BSCMAKE option"] ms.assetid: fa2f1e06-c684-41cf-80dd-6a554835ebd2 --- -# BSCMAKE Options +# BSCMAKE options > [!WARNING] -> Although BSCMAKE is still installed with Visual Studio, it is no longer used by the IDE. Since Visual Studio 2008, browse and symbol information is stored automatically in a SQL Server *`.sdf`* file in the solution folder. +> Although BSCMAKE is still installed with Visual Studio, it's no longer used by the IDE. Since Visual Studio 2008, browse and symbol information is stored automatically in a SQL Server *`.sdf`* file in the solution folder. -This section describes the options available for controlling BSCMAKE. Several options control the content of the browse information file by excluding or including certain information. The exclusion options can allow BSCMAKE to run faster and may result in a smaller *`.bsc`* file. Option names are case-sensitive (except for **/HELP** and **/NOLOGO**). +This section describes the options available for controlling BSCMAKE. Several options control the content of the browse information file by excluding or including certain information. The exclusion options can allow BSCMAKE to run faster and may result in a smaller *`.bsc`* file. Option names are case-sensitive (except for **`/HELP`** and **`/NOLOGO`**). -Only **/NOLOGO** and **/o** are available from within the Visual Studio development environment. See [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md) for information on access a project's property pages. +Only **`/NOLOGO`** and **`/o`** are available from within the Visual Studio development environment. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). -**/Ei (**_filename_...**)**\ -Excludes the contents of the specified include files from the browse information file. To specify multiple files, separate the names with a space and enclose the list in parentheses. Parentheses aren't necessary if you specify only one *filename*. Use **/Ei** along with the **/Es** option to exclude files not excluded by **/Es**. +## Options -**/El**\ +**`/Ei (`** *`filename`* ... **`)`**\ +Excludes the contents of one or more specified *`filename`* include files from the browse information file. To specify multiple files, separate the names with a space and enclose the list in parentheses. Parentheses aren't necessary if you specify only one *`filename`*. Use **`/Ei`** along with the **`/Es`** option to exclude files not excluded by **`/Es`**. + +**`/El`**\ Excludes local symbols. The default is to include local symbols. For more information about local symbols, see [Creating an .sbr File](creating-an-dot-sbr-file.md). -**/Em**\ -Excludes symbols in the body of macros. Use **/Em** to include only the names of macros in the browse information file. The default is to include both the macro names and the result of the macro expansions. +**`/Em`**\ +Excludes symbols in the body of macros. Use **`/Em`** to include only the names of macros in the browse information file. The default is to include both the macro names and the result of the macro expansions. -**/Er (**_symbol_...**)**\ -Excludes the specified symbols from the browse information file. To specify multiple symbol names, separate the names with a space and enclose the list in parentheses. Parentheses are unnecessary if you specify only one *symbol*. +**`/Er (`** *`symbol`* ... **`)`**\ +Excludes one or more of the specified *`symbol`* symbols from the browse information file. To specify multiple symbol names, separate the names with a space and enclose the list in parentheses. Parentheses are unnecessary if you specify only one *`symbol`*. -**/Es**\ -Excludes every include file specified with an absolute path, or found in an absolute path specified in the INCLUDE environment variable. (Usually, these files are the system include files, which contain much information you may not need in your browse information file.) This option doesn't exclude files specified without a path, or with relative paths, or files found in a relative path in INCLUDE. You can use the **/Ei** option along with **/Es** to exclude files that **/Es** doesn't exclude. If you want to exclude only some of the files, use **/Ei** instead of **/Es**, and list the files you want to exclude. +**`/Es`**\ +Excludes every include file specified with an absolute path, or found in an absolute path specified in the INCLUDE environment variable. (Usually, these files are the system include files, which contain much information you may not need in your browse information file.) This option doesn't exclude files specified without a path, or with relative paths, or files found in a relative path in INCLUDE. You can use the **`/Ei`** option along with **`/Es`** to exclude files that **`/Es`** doesn't exclude. If you want to exclude only some of the files, use **`/Ei`** instead of **`/Es`**, and list the files you want to exclude. -**/errorreport:**[**none** | **prompt** | **queue** | **send**]\ -This option is deprecated. Starting in Windows Vista, error reporting is controlled by [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings. +**`/errorreport:`**\[ **`none`** \| **`prompt`** \| **`queue`** \| **`send`** ]\ +This option is deprecated. In Windows Vista and later, error reporting is controlled by [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings. -**/HELP**\ +**`/HELP`**\ Displays a summary of the BSCMAKE command-line syntax. -**/Iu**\ +**`/Iu`**\ Includes unreferenced symbols. By default, BSCMAKE doesn't record any symbols that are defined but not referenced. If an *`.sbr`* file has been packed, this option has no effect for that input file because the compiler has already removed the unreferenced symbols. -**/n**\ -Forces a nonincremental build. Use **/n** to force a full build of the browse information file whether a *`.bsc`* file exists or not, and to prevent *`.sbr`* files from being truncated. See [How BSCMAKE Builds a .bsc File](how-bscmake-builds-a-dot-bsc-file.md). +**`/n`**\ +Forces a non-incremental build. Use **`/n`** to force a full build of the browse information file whether a *`.bsc`* file exists or not, and to prevent *`.sbr`* files from being truncated. For more information, see [How BSCMAKE builds a `.bsc` file](how-bscmake-builds-a-dot-bsc-file.md). -**/NOLOGO**\ +**`/NOLOGO`**\ Suppresses the BSCMAKE copyright message. -**/o** *filename*\ -Specifies a name for the browse information file. By default, BSCMAKE gives the browse information file the base name of the first *`.sbr`* file and a *`.bsc`* extension. +**`/o`** *`filename`*\ +The *`filename`* option parameter specifies a name for the browse information file. By default, BSCMAKE gives the browse information file the base name of the first *`.sbr`* file and a *`.bsc`* extension. -**/S (**_filename_...**)**\ -Tells BSCMAKE to process the specified include file the first time it's encountered and to exclude it otherwise. Use this option to save processing time when a file (such as a header, or *`.h`*, file for a *`.c`* or *`.cpp`* source file) is included in several source files but is unchanged by preprocessing directives each time. Use this option if a file is changed in ways unimportant for the browse information file you're creating. To specify multiple files, separate the names with a space, and enclose the list in parentheses. Parentheses aren't necessary if you specify only one *filename*. If you want to exclude the file every time it's included, use the **/Ei** or **/Es** option. +**`/S (`** *`filename`* ... **`)`**\ +Tells BSCMAKE to process each specified *`filename`* include file the first time it's encountered and to exclude it otherwise. Use this option to save processing time when a file (such as a header, or *`.h`*, file for a *`.c`* or *`.cpp`* source file) is included in several source files but is unchanged by preprocessing directives each time. Use this option if a file is changed in ways unimportant for the browse information file you're creating. To specify multiple files, separate the names with a space, and enclose the list in parentheses. Parentheses aren't necessary if you specify only one *`filename`*. If you want to exclude the file every time it's included, use the **`/Ei`** or **`/Es`** option. -**/v**\ +**`/v`**\ Provides verbose output, which includes the name of each *`.sbr`* file being processed and information about the complete BSCMAKE run. -**/?**\ +**`/?`**\ Displays a brief summary of BSCMAKE command-line syntax. -The following command line tells BSCMAKE to do a full build of MAIN.bsc from three *`.sbr`* files. It also tells BSCMAKE to exclude duplicate instances of TOOLBOX.h: +## Example + +The following command line tells BSCMAKE to do a full build of *`main.bsc`* from three *`.sbr`* files. It also tells BSCMAKE to exclude duplicate instances of *`toolbox.h`*: ```cmd BSCMAKE /n /S toolbox.h /o main.bsc file1.sbr file2.sbr file3.sbr @@ -65,4 +69,4 @@ BSCMAKE /n /S toolbox.h /o main.bsc file1.sbr file2.sbr file3.sbr ## See also -[BSCMAKE Reference](bscmake-reference.md) +[BSCMAKE reference](bscmake-reference.md) diff --git a/docs/build/reference/building-browse-information-files-overview.md b/docs/build/reference/building-browse-information-files-overview.md index d69bc31429..c7217d48af 100644 --- a/docs/build/reference/building-browse-information-files-overview.md +++ b/docs/build/reference/building-browse-information-files-overview.md @@ -1,43 +1,43 @@ --- description: "Learn more about: Building Browse Information Files: Overview" title: "Building Browse Information Files: Overview" -ms.date: "05/06/2019" +ms.date: 03/02/2022 helpviewer_keywords: [".bsc files, about .bsc files", "bsc files, about bsc files", "browse information files (.bsc)", "browse information files (.bsc), creating"] ms.assetid: b5c12832-51f6-4953-8044-4264dd0fb242 --- # Building Browse Information Files: Overview > [!WARNING] -> Although BSCMAKE is still installed with Visual Studio, it is no longer used by the IDE. Since Visual Studio 2008, browse and symbol information is stored automatically in a SQL Server .sdf file in the solution folder. +> Although BSCMAKE is still installed with Visual Studio, it's no longer used by the IDE. Since Visual Studio 2008, browse and symbol information is stored automatically in a SQL Server *`.sdf`* file in the solution folder. -To create browse information for symbol browsing, the compiler creates an .sbr file for each source file in your project, then BSCMAKE.EXE concatenates the .sbr files into one .bsc file. +To create browse information for symbol browsing, the compiler creates an *`.sbr`* file for each source file in your project, then BSCMAKE.EXE concatenates the *`.sbr`* files into one *`.bsc`* file. -Generating .sbr and .bsc files takes time, so Visual Studio turns these functions off by default. If you want to browse current information, you must turn the browse options on and build your project again. +Generating *`.sbr`* and *`.bsc`* files takes time, so Visual Studio turns off these functions by default. If you want to browse current information, you must turn on the browse options and build your project again. -Use [/FR](fr-fr-create-dot-sbr-file.md) or [/Fr](fr-fr-create-dot-sbr-file.md) to tell the compiler to create .sbr files. To create .bsc files, you can call [BSCMAKE](bscmake-command-line.md) from the command line. Using BSCMAKE from the command line gives you more precise control over the manipulation of browse information files. See [BSCMAKE Reference](bscmake-reference.md) for more information. +Use [`/FR`](fr-fr-create-dot-sbr-file.md) or [`/Fr`](fr-fr-create-dot-sbr-file.md) to tell the compiler to create *`.sbr`* files. To create *`.bsc`* files, you can call [BSCMAKE](bscmake-command-line.md) from the command line. Using BSCMAKE from the command line gives you more precise control over the manipulation of browse information files. For more information, see [BSCMAKE reference](bscmake-reference.md). > [!TIP] -> You can turn on .sbr file generation but leave .bsc file generation turned off. This provides fast builds but also enables you to create a fresh .bsc file quickly by turning on .bsc file generation and building the project. +> You can turn on *`.sbr`* file generation but leave *`.bsc`* file generation turned off. This provides fast builds but also enables you to create a fresh *`.bsc`* file quickly by turning on *`.bsc`* file generation and building the project. -You can reduce the time, memory, and disk space required to build a .bsc file by reducing the size of the .bsc file. +You can reduce the time, memory, and disk space required to build a *`.bsc`* file by reducing the size of the *`.bsc`* file. See [General Property Page (Project)](general-property-page-project.md) for information on how to build a browser file in the development environment. -### To create a smaller .bsc file +### To create a smaller `.bsc` file 1. Use [BSCMAKE command-line options](bscmake-options.md) to exclude information from the browse information file. -1. Omit local symbols in one or more .sbr files when compiling or assembling. +1. Omit local symbols in one or more *`.sbr`* files when compiling or assembling. -1. If an object file does not contain information needed for your current stage of debugging, omit its .sbr file from the BSCMAKE command when you rebuild the browse information file. +1. If an object file doesn't contain information needed for your current stage of debugging, omit its *`.sbr`* file from the BSCMAKE command when you rebuild the browse information file. -### To combine the browse information from several projects into one browser file (.bsc) +### To combine the browse information from several projects into one browser file (`.bsc`) -1. Either don't build the .bsc file at the project level or use the /n switch to prevent the .sbr files from being truncated. +1. Either don't build the *`.bsc`* file at the project level or use the **`/n`** switch to prevent the *`.sbr`* files from being truncated. -1. After all the projects are built, run BSCMAKE with all of the .sbr files as input. Wildcards are accepted. For instance, if you had project directories C:\X, C:\Y, and C:\Z with .sbr files in them and you wanted to combine them all into one .bsc file, then use BSCMAKE C:\X\\\*.sbr C:\Y\\\*.sbr C:\Z\\\*.sbr /o c:\whatever_directory\combined.bsc to build the combined .bsc file. +1. After all the projects are built, run BSCMAKE with all of the *`.sbr`* files as input. Wildcards are accepted. For instance, if you had project directories *`C:\X`*, *`C:\Y`*, and *`C:\Z`* with *`.sbr`* files in them and you wanted to combine them all into one *`.bsc`* file, then use `BSCMAKE C:\X\*.sbr C:\Y\*.sbr C:\Z\*.sbr /o c:\whatever_directory\combined.bsc` to build the combined *`.bsc`* file. ## See also -[Additional MSVC Build Tools](c-cpp-build-tools.md)
-[BSCMAKE Reference](bscmake-reference.md) +[Additional MSVC build tools](c-cpp-build-tools.md)\ +[BSCMAKE reference](bscmake-reference.md) diff --git a/docs/build/reference/c-compile-without-linking.md b/docs/build/reference/c-compile-without-linking.md index 4a881375b4..e552d6a30e 100644 --- a/docs/build/reference/c-compile-without-linking.md +++ b/docs/build/reference/c-compile-without-linking.md @@ -41,7 +41,7 @@ CL /c FIRST.C SECOND.C THIRD.OBJ To create an executable file, you must invoke LINK: ``` -LINK firsti.obj second.obj third.obj /OUT:filename.exe +LINK first.obj second.obj third.obj /OUT:filename.exe ``` ## See also diff --git a/docs/build/reference/c-cpp-prop-page.md b/docs/build/reference/c-cpp-prop-page.md index a022d54e0d..4f92e38d17 100644 --- a/docs/build/reference/c-cpp-prop-page.md +++ b/docs/build/reference/c-cpp-prop-page.md @@ -1,9 +1,9 @@ --- title: "C/C++ Project Properties (Visual Studio)" description: "Reference guide to the Visual Studio Microsoft C/C++ project Property Pages properties." -ms.date: 09/03/2020 +ms.date: 6/9/2023 ms.topic: "article" -ms.assetid: 16375038-4917-4bd0-9a2a-26343c1708b7 +f1_keywords: ["VC.Project.VCCLCompilerTool.AdditionalModuleDirectories", "VC.Project.VCCLCompilerTool.ScanSourceForModuleDependencies"] --- # C/C++ Property Pages @@ -13,22 +13,44 @@ The following property pages are found under **Project** > **Properties** > **Co ### Additional Include Directories -Specifies one or more directories to add to the include path; separate with semi-colons if more than one. Sets [`/I` (Additional include directories)](i-additional-include-directories.md). +Specifies one or more directories to add to the include path. Separate directories with semi-colons ('`;`') if there's more than one. Sets the [`/I` (Additional include directories)](i-additional-include-directories.md) compiler option. ### Additional #using Directories -Specifies one or more directories (separate directory names with a semicolon) to be searched to resolve names passed to a #using directive. Sets [`/AI`](ai-specify-metadata-directories.md). +Specifies one or more directories to search to resolve names passed to a `#using` directive. Separate directories with semi-colons ('`;`') if there's more than one. Sets the [`/AI`](ai-specify-metadata-directories.md) compiler option. + +### Additional BMI Directories + +Specifies one or more directories to search to resolve names passed to an `import` directive. Separate directories with semi-colons ('`;`') if there's more than one. Sets the **`/ifcSearchDir[path]`** compiler option. + +### Additional Module Dependencies + +Specifies one or more modules to use to resolve names passed to an `import` directive. Separate directories with semi-colons ('`;`') if there's more than one. Sets the [`/reference`](module-reference.md) compiler option. + +### Additional Header Unit Dependencies + +Specifies one or more header units to use to resolve names passed to an `import` header directive. Separate directories with semi-colons ('`;`') if there's more than one. Sets the [`/headerUnit`](headerunit.md) compiler option. + +### Scan Sources for Module Dependencies + +When set to **Yes**, the compiler scans all C++ sources, not just module interface and header unit sources, for module and header units dependencies. The build system builds the full dependencies graph, which ensures that all imported modules and header units are built before compiling the files that depend on them. When combined with **Translate Includes to Imports**, any header file that's specified in a [`header-units.json`](header-unit-json-reference.md) file in the same directory as the header file is compiled into a header unit. + +Files that have the extension *`.ixx`*, and files that have their **File properties** > **C/C++** > **Compile As** property set to **Compile as C++ Header Unit (/exportHeader)**, are always scanned. + +### Translate Includes to Imports + +When set to **Yes**, the compiler treats a `#include` directive as an `import` directive if certain conditions are met: The header file is specified in a *`header-units.json`* file in the same directory, and a compiled header unit (an *`.ifc`* file) is available for the header file. Otherwise, the header file is treated as a normal `#include`. The *`header-units.json`* file is used to build header units for each `#include` without symbol duplication. When combined with **Scan Sources for Module Dependencies**, the compiler automatically finds all of the header files that can be compiled into header units. This property sets the [`/translateInclude`](translateinclude.md) compiler option. ### Debug Information Format -Specifies the type of debugging information generated by the compiler. This property requires compatible linker settings. Sets [`/Z7`, `/Zi`, `/ZI` (Debug information format)](z7-zi-zi-debug-information-format.md). +Specifies the type of debugging information generated by the compiler. This property requires compatible linker settings. Sets [`/Z7`, `/Zi`, `/ZI` (Debug information format)](z7-zi-zi-debug-information-format.md) compiler options. #### Choices - **None** - Produces no debugging information, so compilation may be faster. - **C7 compatible** - Select the type of debugging information created for your program and whether this information is kept in object (.obj) files or in a program database (PDB). - **Program Database** - Produces a program database (PDB) that contains type information and symbolic debugging information for use with the debugger. The symbolic debugging information includes the names and types of variables and functions, and line numbers. -- **Program Database for Edit And Continue** - Produces a program database, as described above, in a format that supports the [Edit and Continue](/visualstudio/debugger/edit-and-continue) feature. +- **Program Database for Edit And Continue** - Produces a program database, as described previously, in a format that supports the [Edit and Continue](/visualstudio/debugger/edit-and-continue) feature. ### Support Just My Code Debugging @@ -90,7 +112,11 @@ Additional Security Development Lifecycle (SDL) recommended checks; includes ena ### Multi-processor Compilation -Multi-processor Compilation. +Enable multi-processor compilation. Sets the [`/MP`](mp-build-with-multiple-processes.md) compiler option. + +### Enable Address Sanitizer + +Compiles and links the program with AddressSanitizer instrumentation. This property currently supports x86 and x64 target builds. Sets the [`/fsanitize`](fsanitize.md) compiler option. ## C/C++ Optimization Properties @@ -115,7 +141,7 @@ Select the level of [inline function](../../cpp/inline-functions-cpp.md) expansi - **Default** - **Disabled** - Disables inline expansion, which is on by default. - **Only __inline** - Expands only functions marked as **`inline`**, **`__forceinline`**, or **`__inline`**. Or, in a C++ member function, defined within a class declaration. -- **Any Suitable** - Expands functions marked as **`inline`** or **`__inline`** and any other function that the compiler chooses. (Expansion occurs at the compiler's discretion, often referred to as *auto-inlining*.) +- **Any Suitable** - Expands functions marked as **`inline`** or **`__inline`** and any other function that the compiler chooses. (Expansion occurs at the compiler's discretion, often referred to as *autoinlining*.) ### Enable Intrinsic Functions @@ -216,9 +242,9 @@ Specify runtime library for linking. Sets [`/MT`, `/MTd`, `/MD`, `/MDd`](md-mt-l #### Choices - **Multi-threaded** - Causes your application to use the multithread, static version of the run-time library. -- **Multi-threaded Debug** - Defines _DEBUG and _MT. This option also causes the compiler to place the library name *LIBCMTD.lib* into the *`.obj`* file so that the linker will use *LIBCMTD.lib* to resolve external symbols. +- **Multi-threaded Debug** - Defines `_DEBUG` and `_MT`. This option also causes the compiler to place the library name *`LIBCMTD.lib`* into the *`.obj`* file so that the linker will use *`LIBCMTD.lib`* to resolve external symbols. - **Multi-threaded DLL** - Causes your application to use the multithread- and DLL-specific version of the run-time library. Defines `_MT` and `_DLL` and causes the compiler to place the library name *MSVCRT.lib* into the *`.obj`* file. -- **Multi-threaded Debug DLL** - Defines `_DEBUG`, `_MT`, and `_DLL` and causes your application to use the debug multithread- and DLL-specific version of the run-time library. It also causes the compiler to place the library name *MSVCRTD.lib* into the *`.obj`* file. +- **Multi-threaded Debug DLL** - Defines `_DEBUG`, `_MT`, and `_DLL` and causes your application to use the debug multithread- and DLL-specific version of the run-time library. It also causes the compiler to place the library name *`MSVCRTD.lib`* into the *`.obj`* file. ### Struct Member Alignment @@ -226,11 +252,11 @@ Specifies 1, 2, 4, or 8-byte boundaries for struct member alignment. Sets [`/Zp` #### Choices -- **1 Byte** - Packs structures on 1-byte boundaries. Same as **`/Zp`**. -- **2 Bytes** - Packs structures on 2-byte boundaries. -- **4 Bytes** - Packs structures on 4-byte boundaries. -- **8 Bytes** - Packs structures on 8-byte boundaries (default). -- **16 Bytes** - Packs structures on 16-byte boundaries. +- **1 Byte** - Packs structures on one-byte boundaries. Same as **`/Zp`**. +- **2 Bytes** - Packs structures on two-byte boundaries. +- **4 Bytes** - Packs structures on four-byte boundaries. +- **8 Bytes** - Packs structures on eight-byte boundaries (default). +- **16 Bytes** - Packs structures on sixteen-byte boundaries. - **Default** - Default alignment settings. ### Security Check @@ -261,7 +287,7 @@ Allows the compiler to generate parallel code for loops identified using `#pragm ### Enable Enhanced Instruction Set -Enable use of instructions found on processors that support enhanced instruction sets. For example, the SSE, SSE2, AVX, and AVX2 enhancements to IA-32. And, the AVX and AVX2 enhancements to x64. Currently **`/arch:SSE`** and **`/arch:SSE2`** are only available when building for the x86 architecture. If no option is specified, the compiler will use instructions found on processors that support SSE2. Use of enhanced instructions can be disabled with **`/arch:IA32`**. For more information, see [`/arch (x86)`](arch-x86.md), [`/arch (x64)`](arch-x64.md), and [`/arch (ARM)`](arch-arm.md). +Enable use of instructions found on processors that support enhanced instruction sets. For example, the SSE, SSE2, AVX, and AVX2 enhancements to IA-32. And, the AVX and AVX2 enhancements to x64. Currently **`/arch:SSE`** and **`/arch:SSE2`** are only available when building for the x86 architecture. If no option is specified, the compiler uses instructions found on processors that support SSE2. Use of enhanced instructions can be disabled with **`/arch:IA32`**. For more information, see [`/arch (x86)`](arch-x86.md), [`/arch (x64)`](arch-x64.md), [`/arch (ARM64)`](arch-arm64.md), and [`/arch (ARM)`](arch-arm.md). #### Choices @@ -280,7 +306,7 @@ Sets the floating point model. Sets [`/fp:precise`, `/fp:strict`, `/fp:fast`](fp - **Precise** - Default. Improves the consistency of floating-point tests for equality and inequality. - **Strict** - The strictest floating-point model. **`/fp:strict`** causes **`fp_contract`** to be OFF and **`fenv_access`** to be ON. **`/fp:except`** is implied and can be disabled by explicitly specifying **`/fp:except-`**. When used with **`/fp:except-`**, **`/fp:strict`** enforces strict floating-point semantics but without respect for exceptional events. -- **Fast** - Creates the fastest code in the majority of cases. +- **Fast** - Creates the fastest code in most cases. ### Enable Floating Point Exceptions @@ -305,11 +331,7 @@ Spectre mitigations for CVE 2017-5753. Sets [`/Qspectre`](qspectre.md). Suppresses or enables language extensions. Sets [`/Za`](za-ze-disable-language-extensions.md). -### Conformance mode - -Enables or suppresses conformance mode. Sets [`/permissive-`](permissive-standards-conformance.md). - -### Treat wchar_t As Built in Type +### Treat WChar_t As Built in Type When specified, the type **`wchar_t`** becomes a native type that maps to **`__wchar_t`** in the same way that **`short`** maps to **`__int16`**. [`/Zc:wchar_t`](zc-wchar-t-wchar-t-is-native-type.md) is on by default. @@ -333,21 +355,40 @@ Adds code for checking C++ object types at run time (*runtime type information*, Enables OpenMP 2.0 language extensions. Sets [`/openmp`](openmp-enable-openmp-2-0-support.md). -### C++ Language Standard +### C++ Language Standard -Determines the C++ language standard the compiler enables. Use the latest version when possible. Sets [`/std:c++14`, `/std:c++17`, `/std:c++latest`](std-specify-language-standard-version.md). +Determines the C++ language standard that the compiler enables. The default value doesn't set a standard option, so the compiler uses its default C++14 setting. If you select a specific value, the corresponding [`/std`](std-specify-language-standard-version.md) compiler option is set.md). #### Choices -- **Default** -- **ISO C++14 Standard** -- **ISO C++17 Standard** -- **Preview - Features from the Latest C++ Working Draft** +- **Default (ISO C++14 Standard)** +- **ISO C++14 Standard (/std:c++14)** +- **ISO C++17 Standard (/std:c++17)** +- **ISO C++20 Standard (/std:c++20)** +- **Preview - Features from the Latest C++ Working Draft (/std:c++latest)** + +### C Language Standard + +Determines the C language standard that the compiler enables. The default value doesn't set a standard option, so the compiler uses its default legacy MSVC setting. If you select a specific value, the corresponding [`/std`](std-specify-language-standard-version.md) compiler option is set.md). -### Enable C++ Modules (experimental) +#### Choices + +- **Default (Legacy MSVC)** +- **ISO C11 Standard (/std:c11)** +- **ISO C17 (2018) Standard (/std:c17)** + +### Conformance mode + +Enables or suppresses conformance mode. Sets [`/permissive-`](permissive-standards-conformance.md). + +### Enable Experimental C++ Standard Library Modules Experimental support for the C++ Modules TS and Standard Library modules. +### Build ISO C++23 Standard Library Modules + +Starting in Visual Studio 17.6, when this property is enabled and [C++ Language Standard](#cpplang) is set to `/std:c++latest`, Visual C++ projects automatically find and build ISO C++23 Standard Library modules. This enables you to `import std` or `import std.compat` in your C++ code. + ## C/C++ Precompiled Headers Properties ### Create/Use Precompiled Header @@ -420,6 +461,28 @@ Specifies level of browse information in *`.bsc`* file. Sets [`/FR`](fr-fr-creat Specifies optional name for browser information file. Sets [`/FR`\](fr-fr-create-dot-sbr-file.md). +## External Includes + +### Treat Files Included with Angle Brackets as External + +Specifies whether to treat files included with angle brackets as external. Set this property to **Yes** to set the [`/external:anglebrackets`](external-external-headers-diagnostics.md) compiler option. + +### External Header Warning Level + +Select how strict you want the compiler to be about code errors in external headers. This property sets the [`/external:Wn`](external-external-headers-diagnostics.md) compiler option. If this value is set to **Inherit Project Warning Level** or the default, other **`/external`** options are ignored. + +### Template Diagnostics in External Headers + +Specifies whether to evaluate the warning level across a template instantiation chain. Set this property to **Yes** to set the [`/external:templates-`](external-external-headers-diagnostics.md) compiler option. + +### Disable Code Analysis for External Headers + +Disables code analysis for external headers. Sets the [`/analyze:external-`](analyze-code-analysis.md) compiler option. + +### Analysis Ruleset for External Headers + +Specifies a code analysis ruleset override for external headers. If not specified, the Code Analysis setting is used. Sets the [`/analyze:external:ruleset path`](analyze-code-analysis.md) compiler option. + ## C/C++ Advanced Properties ### Calling Convention @@ -435,13 +498,16 @@ Select the default calling convention for your application (can be overridden by ### Compile As -Select compile language option for *`.c`* and *`.cpp`* files. Sets [`/TC`, `/TP`](tc-tp-tc-tp-specify-source-file-type.md). +Select compile language option for source files. Sets [`/TC`, `/TP`](tc-tp-tc-tp-specify-source-file-type.md), [/interface](./interface.md), [`/internalPartition`](./internal-partition.md), or [`/exportHeader`](./module-exportheader.md) options. #### Choices - **Default** - Default. -- **Compile as C Code** - Compile as C Code. -- **Compile as C++ Code** - Compile as C++ Code. +- **Compile as C Code ([`/TC`](./tc-tp-tc-tp-specify-source-file-type.md))** - Compile specified source files as C code. By default, files with a *`.c`* extension are compiled as C. +- **Compile as C++ Code ([`/TP`](./tc-tp-tc-tp-specify-source-file-type.md))** - Compile specified source files as C++ code. By default, all source files that don't have a *`.c`*, *`.ixx`*, *`.cppm`*, *`.h`*, or no extension are compiled as C++. +- **Compile as C++ Module Code ([`/interface`](./interface.md))** - Compile specified source files as C++ module code. By default, files with a *`.ixx`* or *`.cppm`* extension are compiled as C++ module code. +- **Compile as C++ Module Internal Partition ([`/internalPartition`](./internal-partition.md))** - Compile specified source files as C++ module internal partition. +- **Compile as C++ Header Unit ([`/exportHeader`](./module-exportheader.md))** - Compile specified source files as C++ header unit. By default, files with a *`.h`* extension or no extension are compiled as header units. ### Disable Specific Warnings diff --git a/docs/build/reference/c-visual-cpp.md b/docs/build/reference/c-visual-cpp.md index 985f3dd8ad..ebfab859c0 100644 --- a/docs/build/reference/c-visual-cpp.md +++ b/docs/build/reference/c-visual-cpp.md @@ -1,29 +1,29 @@ --- -description: "Learn more about: <c>" -title: "<c> (C++ documentation comments)" +description: "Learn more about: XML documentation tag " +title: " (C++ documentation comments)" ms.date: "11/04/2016" f1_keywords: [""] helpviewer_keywords: [" C++ XML tag", "c C++ XML tag"] ms.assetid: 3b23fc0f-e10d-4dd0-b197-48a46cbddd9f --- -# <c> +# `` documentation tag -The \ tag indicates that text within a description should be marked as code. Use [\](code-visual-cpp.md) to indicate multiple lines as code. +The `` tag indicates that text within a description should be marked as code. Use [``](code-visual-cpp.md) to indicate multiple lines as code. ## Syntax -``` -text +```cpp +/// text ``` -#### Parameters +### Parameters -*text*
+*`text`*\ The text you want to indicate as code. ## Remarks -Compile with [/doc](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. +Compile with [`/doc`](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. ## Example @@ -48,4 +48,4 @@ public: ## See also -[XML Documentation](xml-documentation-visual-cpp.md) +[XML documentation](xml-documentation-visual-cpp.md) diff --git a/docs/build/reference/cetcompat.md b/docs/build/reference/cetcompat.md index 5115f03120..d5c8870b4c 100644 --- a/docs/build/reference/cetcompat.md +++ b/docs/build/reference/cetcompat.md @@ -1,13 +1,13 @@ --- description: "Learn more about: /CETCOMPAT (CET Shadow Stack compatible)" title: "/CETCOMPAT (CET Shadow Stack compatible)" -ms.date: "09/01/2020" -f1_keywords: ["/CETCOMPAT"] +ms.date: 09/22/2021 +f1_keywords: ["VC.Project.VCLinkerTool.CETCompat", "/CETCOMPAT"] helpviewer_keywords: ["/CETCOMPAT linker option", "/CETCOMPAT"] --- -# /CETCOMPAT (CET Shadow Stack compatible) +# `/CETCOMPAT` (CET Shadow Stack compatible) -Specifies whether to mark an executable image as compatible with Control-flow Enforcement Technology (CET) Shadow Stack. +Specifies whether the linker marks an executable image as compatible with Control-flow Enforcement Technology (CET) Shadow Stack. ## Syntax @@ -21,7 +21,7 @@ Specifies that the executable shouldn't be marked compatible with CET Shadow Sta ## Remarks -Control-flow Enforcement Technology (CET) Shadow Stack is a computer processor feature that provides capabilities to defend against return-oriented programming (ROP) based malware attacks. For more information, see [Intel Control-flow Enforcement Technology Preview](https://software.intel.com/sites/default/files/managed/4d/2a/control-flow-enforcement-technology-preview.pdf). +Control-flow Enforcement Technology (CET) Shadow Stack is a computer processor feature. It provides capabilities to defend against return-oriented programming (ROP) based malware attacks. For more information, see [A Technical Look at Intel's Control-flow Enforcement Technology](https://software.intel.com/content/www/us/en/develop/articles/technical-look-control-flow-enforcement-technology.html). The **`/CETCOMPAT`** linker option tells the linker to mark the binary as CET Shadow Stack-compatible. **`/CETCOMPAT:NO`** marks the binary as not compatible with CET Shadow Stack. If both options are specified on the command line, the last one specified is used. This switch is currently only applicable to x86 and x64 architectures. @@ -31,17 +31,17 @@ The **`/CETCOMPAT`** option is available beginning in Visual Studio 2019. Starting in Visual Studio 2019 version 16.7: -1. Open the **Property Pages** dialog box for the project. For more information, see [Working with Project Properties](../working-with-project-properties.md). +1. Open the **Property Pages** dialog box for the project. For more information, see [Set compiler and build properties](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. 1. Select the **CET Shadow Stack Compatible** property. -1. In the dropdown control, choose **`Yes (/CETCOMPAT)`** to mark the binary as CET Shadow Stack compatible , or **`No (/CETCOMPAT:NO)`** to mark it as non-compatible. +1. In the dropdown control, choose **`Yes (/CETCOMPAT)`** to mark the binary as CET Shadow Stack compatible, or **`No (/CETCOMPAT:NO)`** to mark it as non-compatible. In previous versions of Visual Studio 2019: -1. Open the **Property Pages** dialog box for the project. For more information, see [Working with Project Properties](../working-with-project-properties.md). +1. Open the **Property Pages** dialog box for the project. For more information, see [Set compiler and build properties](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. diff --git a/docs/build/reference/cl-environment-variables.md b/docs/build/reference/cl-environment-variables.md index dfd2f922b7..4be22b5fbe 100644 --- a/docs/build/reference/cl-environment-variables.md +++ b/docs/build/reference/cl-environment-variables.md @@ -26,7 +26,7 @@ You can use these environment variables to define the files and options you use You can't use the [/D](d-preprocessor-definitions.md) option to define a symbol that uses an equal sign (**=**). Instead, you can use the number sign (**#**) for an equal sign. In this way, you can use the CL or \_CL_ environment variables to define preprocessor constants with explicit values—for example, `/DDEBUG#1` to define `DEBUG=1`. -For related information, see [Set Environment Variables](../setting-the-path-and-environment-variables-for-command-line-builds.md). +For more information, see [Use the MSVC toolset from the command line](../building-on-the-command-line.md). ## Examples diff --git a/docs/build/reference/clr-common-language-runtime-compilation.md b/docs/build/reference/clr-common-language-runtime-compilation.md index 063fff6b89..d8189c75f6 100644 --- a/docs/build/reference/clr-common-language-runtime-compilation.md +++ b/docs/build/reference/clr-common-language-runtime-compilation.md @@ -23,7 +23,7 @@ One or more of the following comma-separated arguments. With no options, **`/clr`** creates metadata for the component. The metadata can be consumed by other CLR applications, and enables the component to consume types and data in the metadata of other CLR components. For more information, see [Mixed (Native and Managed) Assemblies](../../dotnet/mixed-native-and-managed-assemblies.md). -::: moniker range="msvc-160" +::: moniker range=">=msvc-160" - **`netcore`** diff --git a/docs/build/reference/clr-restrictions.md b/docs/build/reference/clr-restrictions.md index 13ab850c9f..7f929098e7 100644 --- a/docs/build/reference/clr-restrictions.md +++ b/docs/build/reference/clr-restrictions.md @@ -1,74 +1,74 @@ --- description: "Learn more about: /clr Restrictions" title: "/clr Restrictions" -ms.date: "11/04/2016" +ms.date: 03/02/2022 helpviewer_keywords: ["/clr compiler option [C++], restrictions"] ms.assetid: 385f6462-2c68-46d6-810e-469553ead447 --- -# /clr Restrictions +# `/clr` Restrictions -Note the following restrictions on the use of **/clr**: +Note the following restrictions on the use of **`/clr`**: -- In a structured exception handler, there are restrictions on using `_alloca` when compiling with **/clr**. For more information, see [_alloca](../../c-runtime-library/reference/alloca.md). +- In a structured exception handler, there are restrictions on using `_alloca` when compiling with **`/clr`**. For more information, see [`_alloca`](../../c-runtime-library/reference/alloca.md). -- The use of run-time error checks is not valid with **/clr**. For more information, see [How to: Use Native Run-Time Checks](/visualstudio/debugger/how-to-use-native-run-time-checks). +- The use of run-time error checks isn't valid with **`/clr`**. For more information, see [How to: Use native run-time checks](/visualstudio/debugger/how-to-use-native-run-time-checks). -- When **/clr** is used to compile a program that only uses standard C++ syntax, the following guidelines apply to the use of inline assembly: +- When **`/clr`** is used to compile a program that only uses standard C++ syntax, the following guidelines apply to the use of inline assembly: - - Inline assembly code that assumes knowledge of the native stack layout, calling conventions outside of the current function, or other low-level information about the computer may fail if that knowledge is applied to the stack frame for a managed function. Functions containing inline assembly code are generated as unmanaged functions, as if they were placed in a separate module that was compiled without **/clr**. + - Inline assembly code that assumes knowledge of the native stack layout, calling conventions outside of the current function, or other low-level information about the computer may fail if that knowledge is applied to the stack frame for a managed function. Functions containing inline assembly code are generated as unmanaged functions, as if they were placed in a separate module that was compiled without **`/clr`**. - - Inline assembly code in functions that pass copy-constructed function parameters is not supported. + - Inline assembly code in functions that pass copy-constructed function parameters isn't supported. -- The [vprintf Functions](../../c-runtime-library/vprintf-functions.md) cannot be called from a program compiled with **/clr**. +- The [`vprintf` Functions](../../c-runtime-library/vprintf-functions.md) can't be called from a program compiled with **`/clr`**. -- The [naked](../../cpp/naked-cpp.md) [__declspec](../../cpp/declspec.md) modifier is ignored under /clr. +- The [`naked`](../../cpp/naked-cpp.md) [`__declspec`](../../cpp/declspec.md) modifier is ignored under **`/clr`**. -- The translator function set by [_set_se_translator](../../c-runtime-library/reference/set-se-translator.md) will affect only catches in unmanaged code. See [Exception Handling](../../extensions/exception-handling-cpp-component-extensions.md) for more information. +- The translator function set by [`_set_se_translator`](../../c-runtime-library/reference/set-se-translator.md) will affect only catches in unmanaged code. For more information, see [Exception handling](../../extensions/exception-handling-cpp-component-extensions.md). -- The comparison of function pointers is not permitted under **/clr**. +- The comparison of function pointers isn't permitted under **`/clr`**. -- The use of functions that are not fully prototyped is not permitted under **/clr**. +- The use of functions that aren't fully prototyped isn't permitted under **`/clr`**. -- The following compiler options are not supported with **/clr**: +- The following compiler options aren't supported with **`/clr`**: - - **/EHsc** and **/EHs** (**/clr** implies **/EHa** (see [/EH (Exception Handling Model)](eh-exception-handling-model.md)) + - **`/EHsc`** and **`/EHs`** (**`/clr`** implies **`/EHa`** (see [`/EH` (Exception Handling Model)](eh-exception-handling-model.md)) - - **/fp:strict** and **/fp:except** (see [/fp (Specify Floating-Point Behavior)](fp-specify-floating-point-behavior.md)) + - **`/fp:strict`** and **`/fp:except`** (see [`/fp` (Specify Floating-Point Behavior)](fp-specify-floating-point-behavior.md)) - - [/Zd](z7-zi-zi-debug-information-format.md) + - [`/Zd`](z7-zi-zi-debug-information-format.md) - - [/Gm](gm-enable-minimal-rebuild.md) + - [`/Gm`](gm-enable-minimal-rebuild.md) - - [/MT](md-mt-ld-use-run-time-library.md) + - [`/MT`](md-mt-ld-use-run-time-library.md) - - [/RTC](rtc-run-time-error-checks.md) + - [`/RTC`](rtc-run-time-error-checks.md) - - [/ZI](z7-zi-zi-debug-information-format.md) + - [`/ZI`](z7-zi-zi-debug-information-format.md) -- The combination of the `_STATIC_CPPLIB` preprocessor definition (`/D_STATIC_CPPLIB`) and the **/clr** compiler option is not supported. This is so because the definition would cause your application to link with the static multithreaded C++ Standard Library, which is not supported. For more information, see the [/MD, /MT, /LD (Use Run-Time Library)](md-mt-ld-use-run-time-library.md) topic. +- The combination of the `_STATIC_CPPLIB` preprocessor definition (`/D_STATIC_CPPLIB`) and the **`/clr`** compiler option isn't supported. It's because the definition would cause your application to link with the static, multithreaded C++ Standard Library, which isn't supported. For more information, see [`/MD`, `/MT`, `/LD` (Use Run-Time Library)](md-mt-ld-use-run-time-library.md). -- When using **/Zi** with **/clr**, there are performance implications. For more information, see [/Zi](z7-zi-zi-debug-information-format.md). +- When you use **`/Zi`** with **`/clr`**, there are performance implications. For more information, see [`/Zi`](z7-zi-zi-debug-information-format.md). -- Passing a wide character to a .NET Framework output routine without also specifying [/Zc:wchar_t](zc-wchar-t-wchar-t-is-native-type.md) or without casting the character to **`__wchar_t`** will cause the output to appear as an `unsigned short int`. For example: +- Passing a wide character to a .NET Framework output routine without also specifying [`/Zc:wchar_t`](zc-wchar-t-wchar-t-is-native-type.md) or without casting the character to **`_wchar_t`** will cause the output to appear as an `unsigned short int`. For example: ```cpp Console::WriteLine(L' ') // Will output 32. Console::WriteLine((__wchar_t)L' ') // Will output a space. ``` -- [/GS](gs-buffer-security-check.md) is ignored when compiling with **/clr**, unless a function is under `#pragma` [unmanaged](../../preprocessor/managed-unmanaged.md) or if the function must be compiled to native, in which case the compiler will generate warning C4793, which is off by default. +- [`/GS`](gs-buffer-security-check.md) is ignored when compiling with **`/clr`**, unless a function is under [`#pragma unmanaged`](../../preprocessor/managed-unmanaged.md) or if the function must be compiled as native code, in which case the compiler will generate warning C4793, which is off by default. -- See [/ENTRY](entry-entry-point-symbol.md) for function signature requirements of a managed application. +- See [`/ENTRY`](entry-entry-point-symbol.md) for function signature requirements of a managed application. -- Applications compiled with **/openmp** and **/clr** can only be run in a single appdomain process. See [/openmp (Enable OpenMP 2.0 Support)](openmp-enable-openmp-2-0-support.md) for more information. +- Applications compiled with **`/openmp`** and **`/clr`** can only be run in a single appdomain process. For more information, see [`/openmp` (Enable OpenMP 2.0 Support)](openmp-enable-openmp-2-0-support.md). -- Functions that take a variable number of arguments (varargs) will be generated as native functions. Any managed data types in the variable argument position will be marshaled to native types. Note that types are actually wide-character strings, but they are marshaled to single-byte character strings. So if a printf specifier is %S (wchar_t*), it will marshal to a %s string instead. +- Functions that take a variable number of arguments (varargs) will be generated as native functions. Any managed data types in the variable argument position will be marshaled to native types. Any types are actually wide-character strings, but they're marshaled to single-byte character strings. So if a `printf` specifier is `%S` (`wchar_t*`), it will marshal to a `%s` string instead. -- When using the va_arg macro, you may get unexpected results when compiling with **/clr:pure**. For more information, see [va_arg, va_copy, va_end, va_start](../../c-runtime-library/reference/va-arg-va-copy-va-end-va-start.md). The **/clr:pure** and **/clr:safe** compiler options are deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017 and later. Code that must be "pure" or "safe" should be ported to C#. +- When using the `va_arg` macro, you may get unexpected results when compiling with **`/clr:pure`**. For more information, see [`va_arg`, `va_copy`, `va_end`, `va_start`](../../c-runtime-library/reference/va-arg-va-copy-va-end-va-start.md). The **`/clr:pure`** and **`/clr:safe`** compiler options are deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017 and later. Code that must be "pure" or "safe" should be ported to C#. -- You should not call, from managed code, any functions that walk the stack to get parameter information (function arguments); the P/Invoke layer causes that information to be further down the stack. For example, do not compile proxy/stub with **/clr**. +- You shouldn't call any functions that walk the stack to get parameter information (function arguments) from managed code. The P/Invoke layer causes that information to be further down the stack. For example, don't compile proxy/stub with **`/clr`**. -- Functions will be compiled to managed code whenever possible, but not all C++ constructs can be translated to managed code. This determination is made on a function-by-function basis. If any part of a function cannot be converted to managed code, the entire function will be converted to native code instead. The following cases prevent the compiler from generating managed code. +- Functions will be compiled to managed code whenever possible, but not all C++ constructs can be translated to managed code. This determination is made on a function-by-function basis. If any part of a function can't be converted to managed code, the entire function will be converted to native code instead. The following cases prevent the compiler from generating managed code. - Compiler-generated thunks or helper functions. Native thunks are generated for any function call through a function pointer, including virtual function calls. @@ -76,10 +76,10 @@ Note the following restrictions on the use of **/clr**: - Functions that use certain intrinsic routines to directly manipulate machine resources. For example, the use of `__enable` and `__disable`, `_ReturnAddress` and `_AddressOfReturnAddress`, or multimedia intrinsics will all result in native code. - - Functions that follow the `#pragma unmanaged` directive. (Note that the inverse, `#pragma managed`, is also supported.) + - Functions that follow the `#pragma unmanaged` directive. (The inverse, `#pragma managed`, is also supported.) - A function that contains references to aligned types, that is, types declared using `__declspec(align(...))`. ## See also -- [/clr (Common Language Runtime Compilation)](clr-common-language-runtime-compilation.md) +- [/clr (Common Language Runtime compilation)](clr-common-language-runtime-compilation.md) diff --git a/docs/build/reference/clrsupportlasterror-preserve-last-error-code-for-pinvoke-calls.md b/docs/build/reference/clrsupportlasterror-preserve-last-error-code-for-pinvoke-calls.md index ef9e5e1e0d..7ab680d3cf 100644 --- a/docs/build/reference/clrsupportlasterror-preserve-last-error-code-for-pinvoke-calls.md +++ b/docs/build/reference/clrsupportlasterror-preserve-last-error-code-for-pinvoke-calls.md @@ -1,39 +1,39 @@ --- description: "Learn more about: /CLRSUPPORTLASTERROR (Preserve Last Error Code for PInvoke Calls)" title: "/CLRSUPPORTLASTERROR (Preserve Last Error Code for PInvoke Calls)" -ms.date: "11/04/2016" -f1_keywords: ["/CLRSUPPORTLASTERROR"] +ms.date: 09/19/2022 +f1_keywords: ["VC.Project.VCLinkerTool.CLRSupportLastError", "/CLRSUPPORTLASTERROR"] helpviewer_keywords: ["/CLRSUPPORTLASTERROR linker option", "-CLRSUPPORTLASTERROR linker option"] ms.assetid: b7057990-4154-4b1d-9fc9-6236f7be7575 --- -# /CLRSUPPORTLASTERROR (Preserve Last Error Code for PInvoke Calls) +# `/CLRSUPPORTLASTERROR` (Preserve Last Error Code for PInvoke Calls) -**/CLRSUPPORTLASTERROR**, which is on by default, preserves the last error code of functions called through the P/Invoke mechanism, which allows you to call native functions in DLLS, from code compiled with **/clr**. +**`/CLRSUPPORTLASTERROR`**, which is on by default, preserves the last error code of functions called through the P/Invoke mechanism, which allows you to call native functions in DLLS, from code compiled with **`/clr`**. ## Syntax -``` -/CLRSUPPORTLASTERROR{:NO | SYSTEMDLL} -``` +> **`/CLRSUPPORTLASTERROR`**\ +> **`/CLRSUPPORTLASTERROR:NO`**\ +> **`/CLRSUPPORTLASTERROR:SYSTEMDLL`** ## Remarks -Preserving the last error code implies a decrease in performance. If you do not want to incur the performance impact of preserving the last error code, link with **/CLRSUPPORTLASTERROR:NO**. +Preserving the last error code implies a decrease in performance. If you don't want to incur the performance cost of preserving the last error code, link by using **`/CLRSUPPORTLASTERROR:NO`**. -You can minimize the performance impact by linking with **/CLRSUPPORTLASTERROR:SYSTEMDLL**, which only preserves the last error code for functions in system DLLs. +You can minimize the performance penalty by linking with **`/CLRSUPPORTLASTERROR:SYSTEMDLL`**, which only preserves the last error code for functions in system DLLs. > [!NOTE] -> Preserving the last error is not supported for unmanaged functions that are consumed by CLR code, in the same module. +> Preserving the last error isn't supported for unmanaged functions that are consumed by CLR code in the same module. -- For more information, see [/clr (Common Language Runtime Compilation)](clr-common-language-runtime-compilation.md). +- For more information, see [`/clr` (Common Language Runtime Compilation)](clr-common-language-runtime-compilation.md). ### To set this linker option in the Visual Studio development environment -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. Open the **Property Pages** dialog box for the project. For more information, see [Set compiler and build properties](../working-with-project-properties.md). -1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. +1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. -1. Enter the option into the **Additional Options** box. +1. Modify the **Preserve Last Error Code for PInvoke Calls** property. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically @@ -56,7 +56,7 @@ __declspec(dllexport) double MySqrt(__int64 n) { } ``` -The following sample consumes the DLL, demonstrating how to use **/CLRSUPPORTLASTERROR**. +The following sample consumes the DLL, demonstrating how to use **`/CLRSUPPORTLASTERROR`**. ```cpp // CLRSUPPORTLASTERROR_client.cpp @@ -109,5 +109,5 @@ GetLastError for system call succeeded (183). ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md b/docs/build/reference/clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md index 80494a5a17..ffc60a41e9 100644 --- a/docs/build/reference/clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md +++ b/docs/build/reference/clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md @@ -1,37 +1,38 @@ --- description: "Learn more about: /CLRUNMANAGEDCODECHECK (Remove SuppressUnmanagedCodeSecurityAttribute)" title: "/CLRUNMANAGEDCODECHECK (Remove SuppressUnmanagedCodeSecurityAttribute)" -ms.date: "05/16/2019" +ms.date: 09/19/2022 ms.topic: "reference" -f1_keywords: ["/CLRUNMANAGEDCODECHECK"] +f1_keywords: ["VC.Project.VCLinkerTool.CLRUnmanagedCodeCheck", "/CLRUNMANAGEDCODECHECK"] helpviewer_keywords: ["-CLRUNMANAGEDCODECHECK linker option", "/CLRUNMANAGEDCODECHECK linker option"] ms.assetid: 73abc426-dab0-45e2-be85-0f9a14206cc2 -author: "corob-msft" -ms.author: "corob" +author: "tylermsft" +ms.author: "twhitney" --- -# /CLRUNMANAGEDCODECHECK (Remove SuppressUnmanagedCodeSecurityAttribute) +# `/CLRUNMANAGEDCODECHECK` (Remove SuppressUnmanagedCodeSecurityAttribute) -**/CLRUNMANAGEDCODECHECK** specifies that the linker does not apply to linker-generated `PInvoke` calls from managed code into native DLLs. +**`/CLRUNMANAGEDCODECHECK`** specifies that the linker doesn't apply to linker-generated `PInvoke` calls from managed code into native DLLs. ## Syntax -> **/CLRUNMANAGEDCODECHECK**[**:NO**] +> **`/CLRUNMANAGEDCODECHECK`**\ +> **`/CLRUNMANAGEDCODECHECK:NO`** ## Remarks -By default, the linker applies the **SuppressUnmanagedCodeSecurityAttribute** to linker-generated `PInvoke` calls. When **/CLRUNMANAGEDCODECHECK** is in effect, **SuppressUnmanagedCodeSecurityAttribute** is removed. To explicitly apply the **SuppressUnmanagedCodeSecurityAttribute** to linker-generated `PInvoke` calls, you can use **/CLRUNMANAGEDCODECHECK:NO**. +By default, the linker applies the `SuppressUnmanagedCodeSecurityAttribute` attribute to linker-generated `PInvoke` calls. When **`/CLRUNMANAGEDCODECHECK`** is in effect, `SuppressUnmanagedCodeSecurityAttribute` is removed. To explicitly apply the `SuppressUnmanagedCodeSecurityAttribute` attribute to linker-generated `PInvoke` calls, you can use **`/CLRUNMANAGEDCODECHECK:NO`**. -The linker only adds the attribute to objects that are compiled using **/clr** or **/clr:pure**. However, the **/clr:pure** compiler option is deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017 and later. +The linker only adds the attribute to objects that are compiled using **`/clr`** or **`/clr:pure`**. However, the **`/clr:pure`** compiler option is deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017 and later. -A `PInvoke` call is generated by the linker when the linker cannot find a managed symbol to satisfy a reference from a managed caller but can find a native symbol to satisfy that reference. For more information about `PInvoke`, see [Calling Native Functions from Managed Code](../../dotnet/calling-native-functions-from-managed-code.md). +A `PInvoke` call is generated by the linker when the linker can't find a managed symbol to satisfy a reference from a managed caller but can find a native symbol to satisfy that reference. For more information about `PInvoke`, see [Calling Native Functions from Managed Code](../../dotnet/calling-native-functions-from-managed-code.md). -Note that if you use in your code, you should explicitly set **/CLRUNMANAGEDCODECHECK** to remove the **SuppressUnmanagedCodeSecurity** attribute. It is a potential security vulnerability if an image contains both the **SuppressUnmanagedCodeSecurity** and **AllowPartiallyTrustedCallers** attributes. +If you use in your code, you should explicitly set **`/CLRUNMANAGEDCODECHECK`** to remove the `SuppressUnmanagedCodeSecurity` attribute. It's a potential security vulnerability if an image contains both the `SuppressUnmanagedCodeSecurity` and `AllowPartiallyTrustedCallers` attributes. -See [Secure Coding Guidelines for Unmanaged Code](/dotnet/framework/security/secure-coding-guidelines-for-unmanaged-code) for more information about the implications of using **SuppressUnmanagedCodeSecurityAttribute**. +For more information about the implications of using `SuppressUnmanagedCodeSecurityAttribute`, see [Secure Coding Guidelines for Unmanaged Code](/previous-versions/dotnet/framework/windows-identity-foundation/secure-coding-guidelines-for-unmanaged-code). ### To set this linker option in the Visual Studio development environment -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. Open the **Property Pages** dialog box for the project. For more information, see [Set compiler and build properties](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. @@ -43,5 +44,5 @@ See [Secure Coding Guidelines for Unmanaged Code](/dotnet/framework/security/sec ## See also -- [MSVC linker reference](linking.md) -- [MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/code-visual-cpp.md b/docs/build/reference/code-visual-cpp.md index cba638edb9..2ae857a3e2 100644 --- a/docs/build/reference/code-visual-cpp.md +++ b/docs/build/reference/code-visual-cpp.md @@ -1,36 +1,41 @@ --- -description: "Learn more about: <code>" -title: "<code> (C++ documentation comments)" -ms.date: "11/04/2016" +description: "Learn more about: XML Documentation tag " +title: " (C++ documentation comments)" +ms.date: 12/03/2021 f1_keywords: [""] helpviewer_keywords: [" C++ XML tag", "code C++ XML tag"] ms.assetid: 687db3f8-d435-4a90-b781-8da503fa39bc --- -# <code> +# `` documentation tag -The \ tag gives you a way to indicate one or more lines as code. +The `` tag gives you a way to indicate one or more lines as code. ## Syntax -``` -content +```cpp +/// content + +/// +/// content +/// content +/// ``` -#### Parameters +### Parameters -*content*
+*`content`*\ The text you want marked as code. ## Remarks -Use [\](c-visual-cpp.md) to indicate a portion of text should be marked as code. +Use [``](c-visual-cpp.md) to indicate a portion of text should be marked as code. -Compile with [/doc](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. +Compile with [`/doc`](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. ## Example -See the [\](example-visual-cpp.md) topic for an example of how to use the \ tag. +For an example of how to use the `` tag, see [``](example-visual-cpp.md). ## See also -[XML Documentation](xml-documentation-visual-cpp.md) +[XML documentation](xml-documentation-visual-cpp.md) diff --git a/docs/build/reference/command-line-property-pages.md b/docs/build/reference/command-line-property-pages.md index 9f7efcc20a..3e5ab9a2c5 100644 --- a/docs/build/reference/command-line-property-pages.md +++ b/docs/build/reference/command-line-property-pages.md @@ -1,20 +1,33 @@ --- -description: "Learn more about: Command Line Property Pages" -title: "Command Line Property Pages" -ms.date: "11/04/2016" +description: "Learn more about: Command line property pages" +title: "Command line property pages" +ms.date: 09/21/2022 f1_keywords: ["vc.project.AdditionalOptionsPage", "vc.project.CommandLinePage"] helpviewer_keywords: ["Command Line property pages"] ms.assetid: e1721b6c-8b39-4b44-a41e-69b5bb470cc9 --- -# Command Line Property Pages +# Command line property pages -Most property page folders contain a **Command Line** property page. This page displays which properties are set in the folder. The **Command Line** property page also contains an **Additional Options** box where you can specify properties that are valid for the tool but for which there is no property in the folder. +Most property page folders that correspond with a command-line tool contain a **Command Line** property page. For information on how to access the **Command Line** property pages, see [Set compiler and build properties](../working-with-project-properties.md). -Any command that you enter in the edit box will be passed through to the tool for the folder. No verification or checks will be done on the input, nor will there be any dependency checking. +## Command Line property page -For information on how to access the **Command Line** property pages, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +### All Options + +The **All Options** display-only control shows the tool command line created by the properties set in the folder. + +### Additional Options + +This property's edit control lets you specify other command-line options that are valid for the tool but that don't have a corresponding property. + +The options that you enter in the edit box are passed through to the tool for the folder after the options listed in **All Options**. No verification or validity checks are done on the options you enter, and there's no dependency checking. ## See also -[C++ project property page reference](property-pages-visual-cpp.md)
-[.Lib Files as Linker Input](dot-lib-files-as-linker-input.md) +[Windows C++ project property page reference](property-pages-visual-cpp.md)\ +[Linux C++ property page reference](../../linux/prop-pages-linux.md)\ +[Linker property pages](./linker-property-pages.md)\ +[Manifest tool property pages](manifest-tool-property-pages.md)\ +[MIDL property pages](midl-property-pages.md)\ +[NMake property page](nmake-property-page.md)\ +[XML document generator tool property pages](xml-document-generator-tool-property-pages.md) diff --git a/docs/build/reference/command-macros-and-options-macros.md b/docs/build/reference/command-macros-and-options-macros.md deleted file mode 100644 index c466bd09f5..0000000000 --- a/docs/build/reference/command-macros-and-options-macros.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: "Command macros and options macros" -description: "Describes the predefined NMAKE macros for build tools and their options." -ms.date: "11/20/2019" -helpviewer_keywords: ["options macros", "command macros in NMAKE", "macros, options macros", "macros, command macros"] -ms.assetid: 50dff03c-0dc3-4a8a-9a17-57e0e4ea9bac -no-loc: [AS, AFLAGS, CC, CFLAGS, CPP, CPPFLAGS, CXX, CXXFLAGS, RC, RFLAGS, ias, ml, ml64, cl, rc] ---- -# Command macros and options macros - -Command macros are predefined for Microsoft products. Options macros represent options to these products and are undefined by default. Both are used in predefined inference rules and can be used in description blocks or user-defined inference rules. Command macros can be redefined to represent part or all of a command line, including options. Options macros generate a null string if left undefined. - -|Microsoft product|Command macro|Defined as|Options macro| -|-----------------------|-------------------|----------------|-------------------| -|Macro Assembler|**AS**|ml, ias, or ml64|**AFLAGS**| -|C Compiler|**CC**|cl|**CFLAGS**| -|C++ Compiler|**CPP**|cl|**CPPFLAGS**| -|C++ Compiler|**CXX**|cl|**CXXFLAGS**| -|Resource Compiler|**RC**|rc|**RFLAGS**| - -## See also - -[Special NMAKE Macros](special-nmake-macros.md) diff --git a/docs/build/reference/command-modifiers.md b/docs/build/reference/command-modifiers.md deleted file mode 100644 index 280bb85df7..0000000000 --- a/docs/build/reference/command-modifiers.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -description: "Learn more about: Command Modifiers" -title: "Command Modifiers" -ms.date: "11/04/2016" -helpviewer_keywords: ["NMAKE program, command modifiers", "command modifiers"] -ms.assetid: b661c432-210f-4f05-bc56-744a46e0fc0b ---- -# Command Modifiers - -You can specify one or more command modifiers preceding a command, optionally separated by spaces or tabs. As with commands, modifiers must be indented. - -|Modifier|Purpose| -|--------------|-------------| -|\@*command*|Prevents display of the command. Display by commands is not suppressed. By default, NMAKE echoes all executed commands. Use /S to suppress display for the entire makefile; use **.SILENT** to suppress display for part of the makefile.| -|**-**\[*number*] *command*|Turns off error checking for *command*. By default, NMAKE halts when a command returns a nonzero exit code. If -*number* is used, NMAKE stops if the exit code exceeds *number*. Spaces or tabs cannot appear between the dash and *number.* At least one space or tab must appear between `number` and *command*. Use /I to turn off error checking for the entire makefile; use **.IGNORE** to turn off error checking for part of the makefile.| -|**!** *command*|Executes *command* for each dependent file if *command* uses $\*\* (all dependent files in the dependency) or **$?** (all dependent files in the dependency with a later timestamp than the target).| - -## See also - -[Commands in a Makefile](commands-in-a-makefile.md) diff --git a/docs/build/reference/commands-in-a-makefile.md b/docs/build/reference/commands-in-a-makefile.md index 3dc87f5181..9929e2f05b 100644 --- a/docs/build/reference/commands-in-a-makefile.md +++ b/docs/build/reference/commands-in-a-makefile.md @@ -1,29 +1,60 @@ --- description: "Learn more about: Commands in a Makefile" title: "Commands in a Makefile" -ms.date: "11/04/2016" -helpviewer_keywords: ["commands, makefiles"] -ms.assetid: 8085517e-42f4-493b-b8f8-44311fc08c64 +ms.date: 09/30/2021 +helpviewer_keywords: ["commands, makefiles", "NMAKE program, command modifiers", "command modifiers", "syntax, filename-parts", "filename-parts syntax in NMAKE"] --- -# Commands in a Makefile +# Commands in a makefile -A description block or inference rule specifies a block of commands to run if the dependency is out-of-date. NMAKE displays each command before running it, unless /S, **.SILENT**, **!CMDSWITCHES**, or \@ is used. NMAKE looks for a matching inference rule if a description block is not followed by a commands block. +A description block or inference rule specifies a block of commands to run if the dependency is out-of-date. NMAKE displays each command before running it, unless **`/S`**, **`.SILENT`**, **`!CMDSWITCHES`**, or **`@`** is used. NMAKE looks for a matching inference rule if a description block isn't followed by a commands block. A commands block contains one or more commands, each on its own line. No blank line can appear between the dependency or rule and the commands block. However, a line containing only spaces or tabs can appear; this line is interpreted as a null command, and no error occurs. Blank lines are permitted between command lines. -A command line begins with one or more spaces or tabs. A backslash ( \ ) followed by a newline character is interpreted as a space in the command; use a backslash at the end of a line to continue a command onto the next line. NMAKE interprets the backslash literally if any other character, including a space or tab, follows the backslash. +A command line begins with one or more spaces or tabs. A backslash (**`\`**) followed by a newline character is interpreted as a space in the command. Use a backslash at the end of a line to continue a command onto the next line. NMAKE interprets the backslash literally if any other character, including a space or tab, follows the backslash. -A command preceded by a semicolon (;) can appear on a dependency line or inference rule, whether or not a commands block follows: +A command preceded by a semicolon (**`;`**) can appear on a dependency line or inference rule, whether a commands block follows or not: -``` +```makefile project.obj : project.c project.h ; cl /c project.c ``` -## What do you want to know more about? +## Command modifiers + +You can specify one or more command modifiers preceding a command, optionally separated by spaces or tabs. As with commands, modifiers must be indented. + +| Modifier | Purpose | +|--|--| +| **`@`**_command_ | Prevents display of the command. Display by commands is not suppressed. By default, NMAKE echoes all executed commands. Use **`/S`** to suppress display for the entire makefile; use **`.SILENT`** to suppress display for part of the makefile. | +| **`-`**\[*number*] *command* | Turns off error checking for *command*. By default, NMAKE halts when a command returns a nonzero exit code. If *-number* is used, NMAKE stops if the exit code exceeds *number*. Spaces or tabs can't appear between the dash and *number.* At least one space or tab must appear between *number* and *command*. Use **`/I`** to turn off error checking for the entire makefile; use **`.IGNORE`** to turn off error checking for part of the makefile. | +| **`!`** *command* | Executes *command* for each dependent file if *command* uses **`$**`** (all dependent files in the dependency) or **`$?`** (all dependent files in the dependency with a later timestamp than the target). | + +## Filename-parts syntax + +Filename-parts syntax in commands represents components of the first dependent filename (which may be an implied dependent). Filename components are the file's drive, path, base name, and extension as specified, not as it exists on disk. Use **`%s`** to represent the complete filename. Use **`%|`**\[*parts*]**`F`** (a vertical bar character follows the percent symbol) to represent parts of the filename, where *parts* can be zero or more of the following letters, in any order. + +| Letter | Description | +|--|--| +| No letter | Complete name (same as **`%s`**) | +| **`d`** | Drive | +| **`p`** | Path | +| **`f`** | File base name | +| **`e`** | File extension | -[Command modifiers](command-modifiers.md) +For example, if the filename is `c:\prog.exe`: -[Filename-parts syntax](filename-parts-syntax.md) +- `%s` becomes `c:\prog.exe` + +- `%|F` becomes `c:\prog.exe` + +- `%|dF` becomes `c` + +- `%|pF` becomes `c:\` + +- `%|fF` becomes `prog` + +- `%|eF` becomes `exe` + +## What do you want to know more about? [Inline files in a makefile](inline-files-in-a-makefile.md) diff --git a/docs/build/reference/comments-in-a-makefile.md b/docs/build/reference/comments-in-a-makefile.md deleted file mode 100644 index 2aa6732916..0000000000 --- a/docs/build/reference/comments-in-a-makefile.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -description: "Learn more about: Comments in a Makefile" -title: "Comments in a Makefile" -ms.date: "11/04/2016" -helpviewer_keywords: ["makefiles, comments"] -ms.assetid: 76fd9e3d-5966-47f4-a091-c9e80b232b49 ---- -# Comments in a Makefile - -Precede a comment with a number sign (#). NMAKE ignores text from the number sign to the next newline character. Examples: - -``` -# Comment on line by itself -OPTIONS = /MAP # Comment on macro definition line - -all.exe : one.obj two.obj # Comment on dependency line - link one.obj two.obj -# Comment in commands block -# copy *.obj \objects # Command turned into comment - copy one.exe \release - -.obj.exe: # Comment on inference rule line - link $< - -my.exe : my.obj ; link my.obj # Err: cannot comment this -# Error: # must be the first character -.obj.exe: ; link $< # Error: cannot comment this -``` - -To specify a literal number sign, precede it with a caret (**^**), as follows: - -``` -DEF = ^#define #Macro for a C preprocessing directive -``` - -## See also - -[Contents of a Makefile](contents-of-a-makefile.md) diff --git a/docs/build/reference/common-macros-for-build-commands-and-properties.md b/docs/build/reference/common-macros-for-build-commands-and-properties.md index 337ab792fb..dfe8c6a5c0 100644 --- a/docs/build/reference/common-macros-for-build-commands-and-properties.md +++ b/docs/build/reference/common-macros-for-build-commands-and-properties.md @@ -1,77 +1,87 @@ --- description: "Learn more about: Common macros for MSBuild commands and properties" title: "Common macros for MSBuild commands and properties" -ms.date: "08/02/2019" +ms.date: 01/12/2024 helpviewer_keywords: ["$(FrameworkSDKDir) macro", "ProjectName macro $(ProjectName)", "DevEnvDir macro $(DevEnvDir)", "$(DevEnvDir) macro", "TargetPath macro $(TargetPath)", "VSInstallDir macro $(VSInstallDir)", "$(InputFileName) macro", "$(SolutionFileName) macro", "macros [C++], build macros", "InputFileName macro $(InputFileName)", "$(VCInstallDir) macro", "$(IntDir) macro", "$(ConfigurationName) macro", "SolutionDir macro $(SolutionDir)", "$(TargetPath) macro", "$(Inherit) macro", "$(SolutionPath) macro", "WebDeployRoot macro $(WebDeployRoot)", "WebDeployPath macro $(WebDeployPath)", "StopEvaluating macro $(StopEvaluating)", "$(RootNamespace) macro", "$(WebDeployRoot) macro", "ProjectPath macro $(ProjectPath)", "$(ProjectPath) macro", "$(InputDir) macro", "SolutionName macro $(SolutionName)", "ProjectExt macro $(ProjectExt)", "$(TargetExt) macro", "$(ProjectFileName) macro", "TargetName macro $(TargetName)", "$(References) macro", "References macro $(References)", "TargetExt macro $(TargetExt)", "ProjectDir macro $(ProjectDir)", "$(TargetDir) macro", "SolutionExt macro $(SolutionExt)", "$(SolutionDir) macro", "ProjectFileName macro $(ProjectFileName)", "VCInstallDir macro $(VCInstallDir)", "$(InputExt) macro", "$(TargetFileName) macro", "$(SolutionExt) macro", "PlatformName macro $(PlatformName)", "IntDir macro $(IntDir)", "$(FrameworkVersion) macro", "$(ProjectDir) macro", "build macros [C++]", "InputPath macro $(InputPath)", "$(VSInstallDir) macro", "$(WebDeployPath) macro", "TargetFileName macro $(TargetFileName)", "NoInherit macro $(NoInherit)", "ConfigurationName macro $(ConfigurationName)", "$(ProjectExt) macro", "TargetDir macro $(TargetDir)", "InputName macro $(InputName)", "$(ProjectName) macro", "FrameworkSDKDir macro $(FrameworkSDKDir)", "$(ParentName) macro", "InputExt macro $(InputExt)", "$(SafeRootNamespace) macro", "InputDir macro $(InputDir)", "$(FxCopDir) macro", "$(RemoteMachine) macro", "Inherit macro $(Inherit)", "FrameworkVersion macro $(FrameworkVersion)", "$(StopEvaluating) macro", "$(OutDir) macro", "FrameworkDir macro $(FrameworkDir)", "SolutionFileName macro $(SolutionFileName)", "$(NoInherit) macro", "RemoteMachine macro $(RemoteMachine)", "properties [C++], build property macros", "$(TargetName) macro", "$(SolutionName) macro", "$(InputPath) macro", "ParentName macro $(ParentName)", "OutDir macro $(OutDir)", "SafeRootNamespace macro $(SafeRootNamespace)", "FxCopDir macro $(FxCopDir)", "$(InputName) macro", "RootNamespace macro $(RootNamespace)", "builds [C++], macros", "$(FrameworkDir) macro", "$(PlatformName) macro", "$(PlatformShortName) macro","SolutionPath macro $(SolutionPath)"] -ms.assetid: 239bd708-2ea9-4687-b264-043f1febf98b --- # Common macros for MSBuild commands and properties -Depending on your installation options, Visual Studio can make hundreds of macros available to you in a Visual Studio project (based on MSBuild). They correspond to the MSBuild properties that are set by default, or in .props or .targets files, or in your project settings. You can use these macros anywhere in a project's **Property Pages** dialog box where strings are accepted. These macros aren't case-sensitive. +Depending on your installation options, Visual Studio can make hundreds of macros available to you in an MSBuild-based *`.vcxproj`* Visual Studio project. The macros correspond to the MSBuild properties that are set by default, or in *`.props`* or *`.targets`* files, or in your project settings. You can use these macros anywhere in a project's **Property Pages** dialog box where strings are accepted. These macros aren't case-sensitive. ## View the current properties and macros -To display all of the currently available macros, in the **Property Pages** dialog, under **VC++ Directories**, choose the drop-down arrow at the end of a property row. Click on **Edit** and then in the edit dialog box, choose the **Macros** button. The current set of properties and macros visible to Visual Studio is listed along with the current value for each. For more information, see the **Specifying User-Defined Values** section of [C++ project property page reference](property-pages-visual-cpp.md). +To display all of the currently available macros, open the project property pages from the main menu by selecting **Project** > **Properties**. In the **Property Pages** dialog, choose an entry that has a macro in it. You can recognize a macro by the dollar sign and parenthesis that surround its name. -![VC++ macros button](../media/vcppdir_libdir_macros.png "Macros menu") +For example, in the left pane, select **Configuration Properties** > **VC++ Directories**, and then in the right pane, select **Include directories**. The value for **Include directories** is `$(VC_IncludePath);$(WindowsSDK_IncludePath);`. + +The dollar sign and parenthesis surrounding these two values indicates that they're macros. The expansion of those two macros sets the include directories to search. + +Select **Include Directories** and a dropdown appears at the end of the row. Select the dropdown button, then select **Edit**. In the **Include Directories** dialog box that appears, select the **Macros>>** button. + +That expands the dialog to show the current set of properties and macros visible to Visual Studio, along with the current value for each. For more information, see the **Specifying User-Defined Values** section of [C++ project property page reference](property-pages-visual-cpp.md). + +:::image type="complex" source="../media/vcppdir_libdir_macros.png" alt-text="Screenshot of the Visual Studio Include Directories dialog after choosing the Macros button."::: +On the right is a list of Visual Studio macros such as $(AllowLocalNetworkLoopback). The left pane shows the evaluated value of the include directory property. The bottom pane shows which macros were expanded, if any, to produce the include directory property value. Because the Include Directories macro is a combination of two other macros, $(VC_IncludePath) and $(WindowsSDK_IncludePath), the bottom pane, labeled Inherited values, lists those two macros. +:::image-end::: ## List of common macros -This table describes a commonly used subset of the available macros; there are many more not listed here. Go to the **Macros** dialog to see all of the properties and their current values in your project. For details on how MSBuild property definitions are created and used as macros in .props, .targets, and .vcxproj files, see [MSBuild Properties](/visualstudio/msbuild/msbuild-properties). - -|Macro|Description| -|-----------|-----------------| -|**$(Configuration)**|The name of the current project configuration, for example, "Debug".| -|**$(DevEnvDir)**|The installation directory of Visual Studio (defined as drive + path); includes the trailing backslash '\\'.| -|**$(FrameworkDir)**|The directory into which the .NET Framework was installed.| -|**$(FrameworkSDKDir)**|The directory into which you installed the .NET Framework. The .NET Framework could have been installed as part of Visual Studio or separately.| -|**$(FrameworkVersion)**|The version of the .NET Framework used by Visual Studio. Combined with **$(FrameworkDir)**, the full path to the version of the .NET Framework use by Visual Studio.| -|**$(FxCopDir)**|The path to the fxcop.cmd file. The fxcop.cmd file is not installed with all Visual Studio editions.| -|**$(IntDir)**|Path to the directory specified for intermediate files. If it's a relative path, intermediate files go to this path appended to the project directory. This path should have a trailing slash. It resolves to the value for the **Intermediate Directory** property. Don't use **$(OutDir)** to define this property.| -|**$(OutDir)**|Path to the output file directory. If it's a relative path, output files go to this path appended to the project directory. This path should have a trailing slash. It resolves to the value for the **Output Directory** property. Don't use **$(IntDir)** to define this property.| -|**$(Platform)**|The name of current project platform, for example, "Win32".| -|**$(PlatformShortName)**|The short name of current architecture, for example, "x86" or "x64".| -|**$(ProjectDir)**|The directory of the project (defined as drive + path); includes the trailing backslash '\\'.| -|**$(ProjectExt)**|The file extension of the project. It includes the '.' before the file extension.| -|**$(ProjectFileName)**|The file name of the project (defined as base name + file extension).| -|**$(ProjectName)**|The base name of the project.| -|**$(ProjectPath)**|The absolute path name of the project (defined as drive + path + base name + file extension).| -|**$(PublishDir)**|The output location for the publish target; includes the trailing backslash '\\'. Defaults to the **$(OutDir)app.publish\\** folder.| -|**$(RemoteMachine)**|Set to the value of the **Remote Machine** property on the Debug property page. See [Changing Project Settings for a C/C++ Debug Configuration](/visualstudio/debugger/project-settings-for-a-cpp-debug-configuration) for more information.| -|**$(RootNameSpace)**|The namespace, if any, containing the application.| -|**$(SolutionDir)**|The directory of the solution (defined as drive + path); includes the trailing backslash '\\'. Defined only when building a solution in the IDE.| -|**$(SolutionExt)**|The file extension of the solution. It includes the '.' before the file extension. Defined only when building a solution in the IDE.| -|**$(SolutionFileName)**|The file name of the solution (defined as base name + file extension). Defined only when building a solution in the IDE.| -|**$(SolutionName)**|The base name of the solution. Defined only when building a solution in the IDE.| -|**$(SolutionPath)**|The absolute path name of the solution (defined as drive + path + base name + file extension). Defined only when building a solution in the IDE.| -|**$(TargetDir)**|The directory of the primary output file for the build (defined as drive + path); includes the trailing backslash '\\'.| -|**$(TargetExt)**|The file extension of the primary output file for the build. It includes the '.' before the file extension.| -|**$(TargetFileName)**|The file name of the primary output file for the build (defined as base name + file extension).| -|**$(TargetName)**|The base name of the primary output file for the build.| -|**$(TargetPath)**|The absolute path name of the primary output file for the build (defined as drive + path + base name + file extension).| -|**$(VCInstallDir)**|The directory that contains the C++ content of your Visual Studio installation. This property contains the version of the targeted Microsoft C++ (MSVC) toolset, which might be different that the host Visual Studio. For example, when building with `$(PlatformToolset) = v140`, **$(VCInstallDir)** contains the path to the Visual Studio 2015 installation.| -|**$(VSInstallDir)**|The directory into which you installed Visual Studio. This property contains the version of the targeted Visual Studio toolset, which might be different that the host Visual Studio. For example, when building with `$(PlatformToolset) = v110`, **$(VSInstallDir)** contains the path to the Visual Studio 2012 installation.| -|**$(WebDeployPath)**|The relative path from the web deployment root to where the project outputs belong.| -|**$(WebDeployRoot)**|The absolute path to the location of **\**. For example, c:\inetpub\wwwroot.| +This table describes a commonly used subset of the available macros; there are many more not listed here. Go to the **Macros** dialog to see all of the properties and their current values in your project. For details on how MSBuild property definitions are created and used as macros in *`.props`*, *`.targets`*, and *`.vcxproj`* files, see [MSBuild Properties](/visualstudio/msbuild/msbuild-properties). + +| Macro | Description | +|--|--| +| **`$(Configuration)`** | The name of the current project configuration, for example, "Debug". | +| **`$(DevEnvDir)`** | The installation directory of Visual Studio (defined as drive + path); includes the trailing backslash (\\). | +| **`$(FrameworkDir)`** | The directory into which the .NET Framework was installed. | +| **`$(FrameworkSDKDir)`** | The directory into which you installed the .NET Framework. The .NET Framework may have been installed as part of Visual Studio or separately. | +| **`$(FrameworkVersion)`** | The version of the .NET Framework used by Visual Studio. Combined with **`$(FrameworkDir)`**, the full path to the version of the .NET Framework use by Visual Studio. | +| **`$(FxCopDir)`** | The path to the *`fxcop.cmd`* file. The *`fxcop.cmd`* file isn't installed in all Visual Studio editions. | +| **`$(IntDir)`** | Path to the directory specified for intermediate files. If it's a relative path, intermediate files go to this path appended to the project directory. This path should have a trailing backslash (\\). It resolves to the value for the **Intermediate Directory** property. Don't use **`$(OutDir)`** to define this property. | +| **`$(OutDir)`** | Path to the output file directory. If it's a relative path, output files go to this path appended to the project directory. This path should have a trailing backslash (\\). It resolves to the value for the **Output Directory** property. Don't use **`$(IntDir)`** to define this property. | +| **`$(Platform)`** | The name of current project platform, for example, "Win32". | +| **`$(PlatformShortName)`** | The short name of current architecture, for example, "x86" or "x64". | +| **`$(ProjectDir)`** | The directory of the project (defined as drive + path); includes the trailing backslash (\\). | +| **`$(ProjectExt)`** | The file extension of the project. It includes the '.' before the file extension. | +| **`$(ProjectFileName)`** | The file name of the project (defined as base name + file extension). | +| **`$(ProjectName)`** | The base name of the project. | +| **`$(ProjectPath)`** | The absolute path name of the project (defined as drive + path + base name + file extension). | +| **`$(PublishDir)`** | The output location for the publish target; includes the trailing backslash (\\). Defaults to the **`$(OutDir)app.publish\`** folder. | +| **`$(RemoteMachine)`** | Set to the value of the **Remote Machine** property on the Debug property page. For more information, see [Changing Project Settings for a C/C++ Debug Configuration](/visualstudio/debugger/project-settings-for-a-cpp-debug-configuration). | +| **`$(RootNameSpace)`** | The namespace, if any, containing the application. | +| **`$(SolutionDir)`** | The directory of the solution (defined as drive + path); includes the trailing backslash (\\). Defined only when building a solution in the IDE. | +| **`$(SolutionExt)`** | The file extension of the solution. It includes the '.' before the file extension. Defined only when building a solution in the IDE. | +| **`$(SolutionFileName)`** | The file name of the solution (defined as base name + file extension). Defined only when building a solution in the IDE. | +| **`$(SolutionName)`** | The base name of the solution. Defined only when building a solution in the IDE. | +| **`$(SolutionPath)`** | The absolute path name of the solution (defined as drive + path + base name + file extension). Defined only when building a solution in the IDE. | +| **`$(TargetDir)`** | The directory of the primary output file for the build (defined as drive + path); includes the trailing backslash (\\). | +| **`$(TargetExt)`** | The file extension of the primary output file for the build. It includes the '.' before the file extension. | +| **`$(TargetFileName)`** | The file name of the primary output file for the build (defined as base name + file extension). | +| **`$(TargetName)`** | The base name of the primary output file for the build. | +| **`$(TargetPath)`** | The absolute path name of the primary output file for the build (defined as drive + path + base name + file extension). | +| **`$(VCInstallDir)`** | The directory that contains the C++ content of your Visual Studio installation. This property contains the version of the targeted Microsoft C++ (MSVC) toolset, which might be different that the host Visual Studio. For example, when building with `$(PlatformToolset) = v140`, **`$(VCInstallDir)`** contains the path to the Visual Studio 2015 installation. | +| **`$(VSInstallDir)`** | The directory into which you installed Visual Studio. This property contains the version of the targeted Visual Studio toolset, which might be different that the host Visual Studio. For example, when building with `$(PlatformToolset) = v110`, **`$(VSInstallDir)`** contains the path to the Visual Studio 2012 installation. | +| **`$(WebDeployPath)`** | The relative path from the web deployment root to where the project outputs belong. | +| **`$(WebDeployRoot)`** | The absolute path to the location of **``**. For example, *`c:\inetpub\wwwroot`*. | ## Obsolete macros -The build system for C++ was significantly changed between Visual Studio 2008 and Visual Studio 2010. Many macros used in earlier project types have been changed to new ones. These macros are no longer used or have been replaced by one or more equivalent properties or [item metadata macro](/visualstudio/msbuild/itemmetadata-element-msbuild) (**%(**_name_**)**) values. Macros that are marked "migrated" can be updated by the project migration tool. If the project that contains the macro is migrated from Visual Studio 2008 or earlier to Visual Studio 2010, Visual Studio converts the macro to the equivalent current macro. Later versions of Visual Studio can't convert projects from Visual Studio 2008 and earlier to the new project type. You must convert these projects in two steps; first convert them to Visual Studio 2010, and then convert the result to your newer version of Visual Studio. For more information, see [Overview of potential upgrade issues](../../porting/overview-of-potential-upgrade-issues-visual-cpp.md). +The build system for C++ was changed significantly between Visual Studio 2008 and Visual Studio 2010. Many macros used in earlier project types changed to new ones. These macros are no longer used or are replaced by one or more equivalent properties or [item metadata macro](/visualstudio/msbuild/itemmetadata-element-msbuild) (**`%(item-name)`**) values. The migration tool can update macros marked "migrated". If a project containing the macro is migrated from Visual Studio 2008 or earlier to Visual Studio 2010, Visual Studio converts the macro to the equivalent current macro. Later versions of Visual Studio can't convert projects from Visual Studio 2008 and earlier to the new project type. You must convert these projects in two steps; first convert them to Visual Studio 2010, and then convert the result to your newer version of Visual Studio. For more information, see [Overview of potential upgrade issues](../../porting/overview-of-potential-upgrade-issues-visual-cpp.md). -|Macro|Description| -|-----------|-----------------| -|**$(InputDir)**|(Migrated.) The directory of the input file (defined as drive + path); includes the trailing backslash '\\'. If the project is the input, then this macro is equivalent to **$(ProjectDir)**.| -|**$(InputExt)**|(Migrated.) The file extension of the input file. It includes the '.' before the file extension. If the project is the input, then this macro is equivalent to **$(ProjectExt)**. For source files, this is **%(Extension)**.| -|**$(InputFileName)**|(Migrated.) The file name of the input file (defined as base name + file extension). If the project is the input, then this macro is equivalent to **$(ProjectFileName)**. For source files, this is **%(Identity)**.| -|**$(InputName)**|(Migrated.) The base name of the input file. If the project is the input, then this macro is equivalent to **$(ProjectName)**. For source files, this is **%(Filename)**.| -|**$(InputPath)**|(Migrated.) The absolute path name of the input file (defined as drive + path + base name + file extension). If the project is the input, then this macro is equivalent to **$(ProjectPath)**. For source files, this is **%(FullPath)**.| -|**$(ParentName)**|Name of the item containing this project item. This will be the parent folder name, or project name.| -|**$(SafeInputName)**|The name of the file as a valid class name, minus file extension. This property does not have an exact equivalent.| -|**$(SafeParentName)**|The name of the immediate parent in valid name format. For example, a form is the parent of a .resx file. This property does not have an exact equivalent.| -|**$(SafeRootNamespace)**|The namespace name in which the project wizards will add code. This namespace name will only contain characters that would be permitted in a valid C++ identifier. This property does not have an exact equivalent.| +| Macro | Description | +|--|--| +| **`$(InputDir)`** | (Migrated.) The directory of the input file (defined as drive + path); includes the trailing backslash (\\). If the project is the input, then this macro is equivalent to **`$(ProjectDir)`**. | +| **`$(InputExt)`** | (Migrated.) The file extension of the input file. It includes the '.' before the file extension. If the project is the input, then this macro is equivalent to **`$(ProjectExt)`**. For source files, it's equivalent to **`%(Extension)`**. | +| **`$(InputFileName)`** | (Migrated.) The file name of the input file (defined as base name + file extension). If the project is the input, then this macro is equivalent to **`$(ProjectFileName)`**. For source files, it's equivalent to **`%(Identity)`**. | +| **`$(InputName)`** | (Migrated.) The base name of the input file. If the project is the input, then this macro is equivalent to **`$(ProjectName)`**. For source files, it's equivalent to **`%(Filename)`**. | +| **`$(InputPath)`** | (Migrated.) The absolute path name of the input file (defined as drive + path + base name + file extension). If the project is the input, then this macro is equivalent to **`$(ProjectPath)`**. For source files, it's equivalent to **`%(FullPath)`**. | +| **`$(ParentName)`** | Name of the item containing this project item. This macro is the parent folder name, or project name. | +| **`$(SafeInputName)`** | The name of the file as a valid class name, minus file extension. This property doesn't have an exact equivalent. | +| **`$(SafeParentName)`** | The name of the immediate parent in valid name format. For example, a form is the parent of a *`.resx`* file. This property doesn't have an exact equivalent. | +| **`$(SafeRootNamespace)`** | The namespace name where the project wizards should add code. This namespace name only contains characters that would be permitted in a valid C++ identifier. This property doesn't have an exact equivalent. | ## See also [Visual Studio Projects - C++](../creating-and-managing-visual-cpp-projects.md)\ [Visual C++ porting and upgrading guide](../../porting/visual-cpp-porting-and-upgrading-guide.md)\ -[Overview of potential upgrade issues](../../porting/overview-of-potential-upgrade-issues-visual-cpp.md) +[Overview of potential upgrade issues](../../porting/overview-of-potential-upgrade-issues-visual-cpp.md)\ +[MSBuild well-known item metadata](/visualstudio/msbuild/msbuild-well-known-item-metadata) diff --git a/docs/build/reference/compiler-command-line-syntax.md b/docs/build/reference/compiler-command-line-syntax.md index 8cea8f4ff5..0f56baaed5 100644 --- a/docs/build/reference/compiler-command-line-syntax.md +++ b/docs/build/reference/compiler-command-line-syntax.md @@ -17,10 +17,10 @@ The following table describes input to the CL command. |Entry|Meaning| |-----------|-------------| -|*option*|One or more [CL options](compiler-options.md). Note that all options apply to all specified source files. Options are specified by either a forward slash (/) or a dash (-). If an option takes an argument, the option's description documents whether a space is allowed between the option and the arguments. Option names (except for the /HELP option) are case sensitive. See [Order of CL Options](order-of-cl-options.md) for more information.| -|`file`|The name of one or more source files, .obj files, or libraries. CL compiles source files and passes the names of the .obj files and libraries to the linker. See [CL Filename Syntax](cl-filename-syntax.md) for more information.| +|*option*|One or more [CL options](compiler-options.md). All options apply to all specified source files. Specify options using either a forward slash (/) or a dash (-). Generally, there can't be a space between the option and argument. The option's description states when a space is allowed. Options are case-sensitive--except for `/HELP`. For more information, see [Order of CL Options](order-of-cl-options.md).| +|`file`|The name of one or more source files, .obj files, or libraries. CL compiles source files and passes the names of the .obj files and libraries to the linker. For more information, see [CL Filename Syntax](cl-filename-syntax.md).| |*lib*|One or more library names. CL passes these names to the linker.| -|*command-file*|A file that contains multiple options and filenames. See [CL Command Files](cl-command-files.md) for more information.| +|*command-file*|A file that contains multiple options and filenames. For more information, see [CL Command Files](cl-command-files.md).| |*link-opt*|One or more [MSVC Linker Options](linker-options.md). CL passes these options to the linker.| You can specify any number of options, filenames, and library names, as long as the number of characters on the command line does not exceed 1024, the limit dictated by the operating system. diff --git a/docs/build/reference/compiler-option-warning-level.md b/docs/build/reference/compiler-option-warning-level.md index 4b89c26f11..251396f31f 100644 --- a/docs/build/reference/compiler-option-warning-level.md +++ b/docs/build/reference/compiler-option-warning-level.md @@ -1,8 +1,8 @@ --- title: "/w, /W0, /W1, /W2, /W3, /W4, /w1, /w2, /w3, /w4, /Wall, /wd, /we, /wo, /Wv, /WX (Warning level)" description: "Reference for the Microsoft C/C++ compiler options: /w, /W0, /W1, /W2, /W3, /W4, /w1, /w2, /w3, /w4, /Wall, /wd, /we, /wo, /Wv, and /WX." -ms.date: "01/31/2020" -f1_keywords: ["VC.Project.VCCLCompilerTool.DisableSpecificWarnings", "VC.Project.VCCLCompilerTool.WarningLevel", "VC.Project.VCCLWCECompilerTool.DisableSpecificWarnings", "VC.Project.VCCLCompilerTool.WarnAsError", "VC.Project.VCCLWCECompilerTool.WarnAsError", "/wx", "VC.Project.VCCLWCECompilerTool.WarningLevel", "/wall", "VC.Project.VCCLCompilerTool.TreatSpecificWarningsAsErrors", "/Wv", "/w0", "/w1", "/w2", "/w3", "/w4", "/wd", "/we", "/wo"] +ms.date: 02/17/2022 +f1_keywords: ["VC.Project.VCCLCompilerTool.DisableSpecificWarnings", "VC.Project.VCCLCompilerTool.WarningLevel", "VC.Project.VCCLWCECompilerTool.DisableSpecificWarnings", "VC.Project.VCCLCompilerTool.WarnAsError", "VC.Project.VCCLWCECompilerTool.WarnAsError", "VC.Project.VCCLCompilerTool.WarningVersion", "/wx", "VC.Project.VCCLWCECompilerTool.WarningLevel", "/wall", "VC.Project.VCCLCompilerTool.TreatSpecificWarningsAsErrors", "/Wv", "/w0", "/w1", "/w2", "/w3", "/w4", "/wd", "/we", "/wo"] helpviewer_keywords: ["/W1 compiler option [C++]", "w compiler option [C++]", "-wo compiler option [C++]", "Warning Level compiler option", "W1 compiler option [C++]", "-we compiler option [C++]", "/WX compiler option [C++]", "-wd compiler option [C++]", "WX compiler option [C++]", "wo compiler option [C++]", "Wall compiler option [C++]", "/w compiler option", "W2 compiler option [C++]", "-W2 compiler option [C++]", "wd compiler option [C++]", "/we compiler option [C++]", "we compiler option [C++]", "-W1 compiler option [C++]", "-W4 compiler option [C++]", "-Wall compiler option [C++]", "/Wall compiler option [C++]", "-W0 compiler option [C++]", "W0 compiler option [C++]", "-WX compiler option [C++]", "/wo compiler option [C++]", "W4 compiler option [C++]", "W3 compiler option [C++]", "/wd compiler option [C++]", "warnings, as errors compiler option", "/W3 compiler option [C++]", "/W0 compiler option [C++]", "/W4 compiler option [C++]", "-W3 compiler option [C++]", "-w compiler option [C++]", "/W2 compiler option [C++]", "/Wv compiler option [C++]"] --- # /w, /W0, /W1, /W2, /W3, /W4, /w1, /w2, /w3, /w4, /Wall, /wd, /we, /wo, /Wv, /WX (Warning level) diff --git a/docs/build/reference/compiler-options-listed-alphabetically.md b/docs/build/reference/compiler-options-listed-alphabetically.md index 2aea452174..686023b214 100644 --- a/docs/build/reference/compiler-options-listed-alphabetically.md +++ b/docs/build/reference/compiler-options-listed-alphabetically.md @@ -1,7 +1,7 @@ --- title: "Compiler options listed alphabetically" description: "Reference listing in alphabetical order of the Microsoft C/C++ compiler command-line options." -ms.date: 04/13/2021 +ms.date: 2/5/2025 helpviewer_keywords: ["compiler options, C++"] --- # Compiler options listed alphabetically @@ -14,169 +14,256 @@ This table contains an alphabetical list of compiler options. For a list of comp |--|--| | [`@`](at-specify-a-compiler-response-file.md) | Specifies a response file. | | [`/?`](help-compiler-command-line-help.md) | Lists the compiler options. | -| [`/AI`](ai-specify-metadata-directories.md) | Specifies a directory to search to resolve file references passed to the [`#using`](../../preprocessor/hash-using-directive-cpp.md) directive. | -| [`/analyze`](analyze-code-analysis.md) | Enable code analysis. | -| [`/arch`](arch-minimum-cpu-architecture.md) | Specifies the architecture for code generation. | +| [`/AI`](ai-specify-metadata-directories.md) | Specifies a directory to search to resolve file references passed to the [`#using`](../../preprocessor/hash-using-directive-cpp.md) directive. | +| [`/analyze`](analyze-code-analysis.md) | Enables code analysis. | +| [`/arch`](arch-minimum-cpu-architecture.md) | Minimum CPU architecture requirements. | +| `/arm64EC` | Generate code compatible with the arm64EC ABI. | | [`/await`](await-enable-coroutine-support.md) | Enable coroutines (resumable functions) extensions. | +| [`/await:strict`](await-enable-coroutine-support.md) | Enable standard C++20 coroutine support with earlier language versions. | | [`/bigobj`](bigobj-increase-number-of-sections-in-dot-obj-file.md) | Increases the number of addressable sections in an .obj file. | | [`/C`](c-preserve-comments-during-preprocessing.md) | Preserves comments during preprocessing. | | [`/c`](c-compile-without-linking.md) | Compiles without linking. | -| [`/cgthreads`](cgthreads-code-generation-threads.md) | Specifies number of cl.exe threads to use for optimization and code generation. | +| [`/cgthreads`](cgthreads-code-generation-threads.md) | Specifies number of *cl.exe* threads to use for optimization and code generation. | | [`/clr`](clr-common-language-runtime-compilation.md) | Produces an output file to run on the common language runtime. | -| [`/constexpr`](constexpr-control-constexpr-evaluation.md) | Control **`constexpr`** evaluation at compile time. | -| [`/D`](d-preprocessor-definitions.md) | Defines constants and macros. | -| [`/diagnostics`](diagnostics-compiler-diagnostic-options.md) | Controls the format of diagnostic messages. | -| [`/doc`](doc-process-documentation-comments-c-cpp.md) | Process documentation comments to an XML file. | +| [`/clr:implicitKeepAlive-`](clr-common-language-runtime-compilation.md) | Turn off implicit emission of `System::GC::KeepAlive(this)`. | +| [`/clr:initialAppDomain`](clr-common-language-runtime-compilation.md) | Enable initial AppDomain behavior of Visual C++ 2002. | +| [`/clr:netcore`](clr-common-language-runtime-compilation.md) | Produce assemblies targeting .NET Core runtime. | +| [`/clr:noAssembly`](clr-common-language-runtime-compilation.md) | Don't produce an assembly. | +| [`/clr:nostdimport`](clr-common-language-runtime-compilation.md) | Don't import any required assemblies implicitly. | +| [`/clr:nostdlib`](clr-common-language-runtime-compilation.md) | Ignore the system .NET framework directory when searching for assemblies. | +| [`/clr:pure`](clr-common-language-runtime-compilation.md) | Produce an IL-only output file (no native executable code). | +| [`/clr:safe`](clr-common-language-runtime-compilation.md) | Produce an IL-only verifiable output file. | +| [`/constexpr:backtrace`](constexpr-control-constexpr-evaluation.md) | Show N `constexpr` evaluations in diagnostics (default: 10). | +| [`/constexpr:depth`](constexpr-control-constexpr-evaluation.md) | Recursion depth limit for `constexpr` evaluation (default: 512). | +| [`/constexpr:steps`](constexpr-control-constexpr-evaluation.md) | Terminate `constexpr` evaluation after N steps (default: 100000) | +| [`/D{=|#}`](d-preprocessor-definitions.md) | Defines constants and macros. | +| [`/dynamicdeopt`](dynamic-deopt.md) | Enable [C++ Dynamic Debugging (Preview)](/visualstudio/debugger/cpp-dynamic-debugging) and step in anywhere with on-demand function deoptimization. | +| [`/diagnostics`](diagnostics-compiler-diagnostic-options.md) | Diagnostics format: prints column information. | +| [`/diagnostics:caret[-]`](diagnostics-compiler-diagnostic-options.md) | Diagnostics format: prints column and the indicated line of source. | +| [`/diagnostics:classic`](diagnostics-compiler-diagnostic-options.md) | Use legacy diagnostics format. | +| [`/doc`](doc-process-documentation-comments-c-cpp.md) | Processes documentation comments to an XML file. | | [`/E`](e-preprocess-to-stdout.md) | Copies preprocessor output to standard output. | -| [`/EH`](eh-exception-handling-model.md) | Specifies the model of exception handling. | +| [`/EHa`](eh-exception-handling-model.md) | Enable C++ exception handling (with SEH exceptions). | +| [`/EHc`](eh-exception-handling-model.md) | `extern "C"` defaults to `nothrow`. | +| [`/EHr`](eh-exception-handling-model.md) | Always generate `noexcept` runtime termination checks. | +| [`/EHs`](eh-exception-handling-model.md) | Enable C++ exception handling (no SEH exceptions). | | [`/EP`](ep-preprocess-to-stdout-without-hash-line-directives.md) | Copies preprocessor output to standard output. | -| [`/errorReport`](errorreport-report-internal-compiler-errors.md) | Deprecated. Error reporting is controlled by [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings. | -| [`/execution-charset`](execution-charset-set-execution-character-set.md) | Set the execution character set. | -| [`/experimental:external`](external-external-headers-diagnostics.md) | Enables experimental external headers support. | +| [`/errorReport`](errorreport-report-internal-compiler-errors.md) | Deprecated. [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings control error reporting. | +| [`/execution-charset`](execution-charset-set-execution-character-set.md) | Set execution character set. | +| [`/experimental:log`](experimental-log.md) | Enables experimental structured SARIF output. | | [`/experimental:module`](experimental-module.md) | Enables experimental module support. | -| [`/experimental:preprocessor`](experimental-preprocessor.md) | Deprecated. Enables experimental conforming preprocessor support. Use [`/Zc:preprocessor`](zc-preprocessor.md) | -| [`/exportHeader`](module-exportheader.md) | Create the header units (*`.ifc`*) files specified by the input arguments. | -| [`/external`](external-external-headers-diagnostics.md) | Allows control of diagnostics in external headers. | +| [`/exportHeader`](module-exportheader.md) | Create the header units files (*`.ifc`*) specified by the input arguments. | +| [`/external:anglebrackets`](external-external-headers-diagnostics.md) | Treat all headers included via `<>` as external. | +| [`/external:env:`](external-external-headers-diagnostics.md) | Specify an environment variable with locations of external headers. | +| [`/external:I `](external-external-headers-diagnostics.md) | Specify location of external headers. | +| [`/external:templates[-]`](external-external-headers-diagnostics.md) | Evaluate warning level across template instantiation chain. | +| [`/external:W`](external-external-headers-diagnostics.md) | Set warning level for external headers. | | [`/F`](f-set-stack-size.md) | Sets stack size. | -| [`/favor`](favor-optimize-for-architecture-specifics.md) | Produces code optimized for a specific x64 architecture. Or, for the specific micro-architectures in both the AMD64 and EM64T architectures. | -| [`/FA`](fa-fa-listing-file.md) | Creates a listing file. | -| [`/Fa`](fa-fa-listing-file.md) | Sets the listing file name. | -| [`/FC`](fc-full-path-of-source-code-file-in-diagnostics.md) | Display full path of source code files passed to cl.exe in diagnostic text. | +| [`/FA`](fa-fa-listing-file.md) | Configures an assembly listing file. | +| [`/Fa`](fa-fa-listing-file.md) | Creates an assembly listing file. | +| `/fastfail` | Enable fast-fail mode. | +| [`/favor:`](favor-optimize-for-architecture-specifics.md) | Produces code that is optimized for a specified architecture, or for a range of architectures. | +| [`/FC`](fc-full-path-of-source-code-file-in-diagnostics.md) | Displays the full path of source code files passed to *cl.exe* in diagnostic text. | | [`/Fd`](fd-program-database-file-name.md) | Renames program database file. | | [`/Fe`](fe-name-exe-file.md) | Renames the executable file. | -| [`/FI`](fi-name-forced-include-file.md) | Preprocesses the specified include file. | -| [`/Fi`](fi-preprocess-output-file-name.md) | Sets the preprocessed output file name. | -| [`/Fm`](fm-name-mapfile.md) | Creates a map file. | +| [`/feature`](feature-arm64.md) | Enable architecture features.17.10 | +| [`/forceInterlockedFunctions`](force-interlocked-functions.md) | Dynamically selects between Armv8.0 load, store exclusive instructions or Armv8.1 LSE atomic instructions based on target CPU.17.14 | +| [`/FI`](fi-name-forced-include-file.md) | Preprocesses the specified include file. | +| [`/Fi`](fi-preprocess-output-file-name.md) | Specifies the preprocessed output file name. | +| [`/Fm`](fm-name-mapfile.md) | Creates a mapfile. | | [`/Fo`](fo-object-file-name.md) | Creates an object file. | -| [`/fp`](fp-specify-floating-point-behavior.md) | Specify floating-point behavior. | | [`/Fp`](fp-name-dot-pch-file.md) | Specifies a precompiled header file name. | -| [`/FR`](fr-fr-create-dot-sbr-file.md)

[`/Fr`](fr-fr-create-dot-sbr-file.md) | Generates browser files. **`/Fr`** is deprecated. | -| [`/FS`](fs-force-synchronous-pdb-writes.md) | Forces serialization of all writes to the program database (PDB) file through MSPDBSRV.EXE. | +| [`/fp:contract`](fp-specify-floating-point-behavior.md) | Consider floating-point contractions when generating code. | +| [`/fp:except[-]`](fp-specify-floating-point-behavior.md) | Consider floating-point exceptions when generating code. | +| [`/fp:fast`](fp-specify-floating-point-behavior.md) | "fast" floating-point model; results are less predictable. | +| [`/fp:precise`](fp-specify-floating-point-behavior.md) | "precise" floating-point model; results are predictable. | +| [`/fp:strict`](fp-specify-floating-point-behavior.md) | "strict" floating-point model (implies `/fp:except`). | +| [`/fpcvt:BC`](fpcvt.md) | Backward-compatible floating-point to unsigned integer conversions. | +| [`/fpcvt:IA`](fpcvt.md) | Intel native floating-point to unsigned integer conversion behavior. | +| [`/FR`, `/Fr`](fr-fr-create-dot-sbr-file.md) | Name generated *`.sbr`* browser files. **`/Fr`** is deprecated. | +| [`/FS`](fs-force-synchronous-pdb-writes.md) | Forces writes to the PDB file to be serialized through *MSPDBSRV.EXE*. | | [`/fsanitize`](fsanitize.md) | Enables compilation of sanitizer instrumentation such as AddressSanitizer. | -| [`/FU`](fu-name-forced-hash-using-file.md) | Forces the use of a file name as if it had been passed to the [`#using`](../../preprocessor/hash-using-directive-cpp.md) directive. | -| [`/Fx`](fx-merge-injected-code.md) | Merges injected code with source file. | -| [`/GA`](ga-optimize-for-windows-application.md) | Optimizes code for Windows application. | -| [`/Gd`](gd-gr-gv-gz-calling-convention.md) | Uses the **`__cdecl`** calling convention (x86 only). | +| [`/fsanitize-coverage`](fsanitize-coverage.md) | Enables compilation of code coverage instrumentation for libraries such as LibFuzzer. | +| `/Ft` | Location of the header files generated for `#import`. | +| [`/FU`](fu-name-forced-hash-using-file.md) | Forces the use of a file name, as if it were passed to the [`#using`](../../preprocessor/hash-using-directive-cpp.md) directive. | +| [`/Fx`](fx-merge-injected-code.md) | Merges injected code with the source file. | +| [`/GA`](ga-optimize-for-windows-application.md) | Optimizes for Windows applications. | +| [`/Gd`](gd-gr-gv-gz-calling-convention.md) | Uses the **`__cdecl`** calling convention. (x86 only) | | [`/Ge`](ge-enable-stack-probes.md) | Deprecated. Activates stack probes. | | [`/GF`](gf-eliminate-duplicate-strings.md) | Enables string pooling. | | [`/GH`](gh-enable-pexit-hook-function.md) | Calls hook function `_pexit`. | | [`/Gh`](gh-enable-penter-hook-function.md) | Calls hook function `_penter`. | -| [`/GL`](gl-whole-program-optimization.md) | Enables whole program optimization. | -| [`/Gm`](gm-enable-minimal-rebuild.md) | Deprecated. Enables minimal rebuild. | -| [`/GR`](gr-enable-run-time-type-information.md) | Enables run-time type information (RTTI). | -| [`/Gr`](gd-gr-gv-gz-calling-convention.md) | Uses the **`__fastcall`** calling convention (x86 only). | -| [`/GS`](gs-buffer-security-check.md) | Buffers security check. | -| [`/Gs`](gs-control-stack-checking-calls.md) | Controls stack probes. | -| [`/GT`](gt-support-fiber-safe-thread-local-storage.md) | Supports fiber safety for data allocated using static thread-local storage. | -| [`/guard:cf`](guard-enable-control-flow-guard.md) | Adds control flow guard security checks. | -| [`/guard:ehcont`](guard-enable-eh-continuation-metadata.md) | Enables EH continuation metadata. | +| [`/GL[-]`](gl-whole-program-optimization.md) | Enables whole program optimization. | +| [`/Gm[-]`](gm-enable-minimal-rebuild.md) | Deprecated. Enables minimal rebuild. | +| [`/GR[-]`](gr-enable-run-time-type-information.md) | Enables run-time type information (RTTI). | +| [`/Gr`](gd-gr-gv-gz-calling-convention.md) | Uses the **`__fastcall`** calling convention. (x86 only) | +| [`/GS[-]`](gs-buffer-security-check.md) | Checks buffer security. | +| [`/Gs[n]`](gs-control-stack-checking-calls.md) | Controls stack probes. | +| [`/GT`](gt-support-fiber-safe-thread-local-storage.md) | Supports fiber safety for data allocated by using static thread-local storage. | +| `/Gu[-]` | Ensure distinct functions have distinct addresses. | +| [`/guard:cf[-]`](guard-enable-control-flow-guard.md) | Adds control flow guard security checks. | +| [`/guard:ehcont[-]`](guard-enable-eh-continuation-metadata.md) | Enables EH continuation metadata. | | [`/Gv`](gd-gr-gv-gz-calling-convention.md) | Uses the **`__vectorcall`** calling convention. (x86 and x64 only) | -| [`/Gw`](gw-optimize-global-data.md) | Enables whole-program global data optimization. | -| [`/GX`](gx-enable-exception-handling.md) | Deprecated. Enables synchronous exception handling. Use [`/EH`](eh-exception-handling-model.md) instead. | -| [`/Gy`](gy-enable-function-level-linking.md) | Enables function-level linking. | -| [`/GZ`](gz-enable-stack-frame-run-time-error-checking.md) | Deprecated. Same as [`/RTC1`](rtc-run-time-error-checks.md). | -| [`/Gz`](gd-gr-gv-gz-calling-convention.md) | Uses the **`__stdcall`** calling convention (x86 only). | +| [`/Gw[-]`](gw-optimize-global-data.md) | Enables whole-program global data optimization. | +| [`/GX[-]`](gx-enable-exception-handling.md) | Deprecated. Enables synchronous exception handling. Use [`/EH`](eh-exception-handling-model.md) instead. | +| [`/Gy[-]`](gy-enable-function-level-linking.md) | Enables function-level linking. | +| [`/GZ`](gz-enable-stack-frame-run-time-error-checking.md) | Deprecated. Enables fast checks. (Same as [`/RTC1`](rtc-run-time-error-checks.md)) | +| [`/Gz`](gd-gr-gv-gz-calling-convention.md) | Uses the **`__stdcall`** calling convention. (x86 only) | | [`/H`](h-restrict-length-of-external-names.md) | Deprecated. Restricts the length of external (public) names. | | [`/headerName`](headername.md) | Build a header unit from the specified header. | | [`/headerUnit`](headerunit.md) | Specify where to find the header unit file (`.ifc`) for the specified header. | | [`/HELP`](help-compiler-command-line-help.md) | Lists the compiler options. | | [`/homeparams`](homeparams-copy-register-parameters-to-stack.md) | Forces parameters passed in registers to be written to their locations on the stack upon function entry. This compiler option is only for the x64 compilers (native and cross compile). | -| [`/hotpatch`](hotpatch-create-hotpatchable-image.md) | Creates a hot-patchable image. | -| [`/I`](i-additional-include-directories.md) | Searches a directory for include files. | +| [`/hotpatch`](hotpatch-create-hotpatchable-image.md) | Creates a hotpatchable image. | +| [`/I`](i-additional-include-directories.md) | Searches a directory for include files. | +| [`/ifcOutput`](ifc-output.md) | Specify output file name or directory for built *`.ifc`* files. | +| [`/interface`](interface.md) | Treat the input file as a module interface unit. | +| [`/internalPartition`](internal-partition.md) | Treat the input file as an internal partition unit. | | [`/J`](j-default-char-type-is-unsigned.md) | Changes the default **`char`** type. | +| [`/jumptablerdata`](jump-table-rdata.md) | Put switch case statement jump tables in the `.rdata` section. | | [`/JMC`](jmc.md) | Supports native C++ Just My Code debugging. | -| [`/kernel`](kernel-create-kernel-mode-binary.md) | The compiler and linker will create a binary that can be executed in the Windows kernel. | +| [`/kernel`](kernel-create-kernel-mode-binary.md) | The compiler and linker create a binary that can be executed in the Windows kernel. | | [`/LD`](md-mt-ld-use-run-time-library.md) | Creates a dynamic-link library. | | [`/LDd`](md-mt-ld-use-run-time-library.md) | Creates a debug dynamic-link library. | | [`/link`](link-pass-options-to-linker.md) | Passes the specified option to LINK. | -| [`/LN`](ln-create-msil-module.md) | Creates an MSIL module. | -| [`/MD`](md-mt-ld-use-run-time-library.md) | Creates a multithreaded DLL using MSVCRT.lib. | -| [`/MDd`](md-mt-ld-use-run-time-library.md) | Creates a debug multithreaded DLL using MSVCRTD.lib. | -| [`/MP`](mp-build-with-multiple-processes.md) | Compiles multiple source files by using multiple processes. | -| [`/MT`](md-mt-ld-use-run-time-library.md) | Creates a multithreaded executable file using LIBCMT.lib. | -| [`/MTd`](md-mt-ld-use-run-time-library.md) | Creates a debug multithreaded executable file using LIBCMTD.lib. | +| [`/LN`](ln-create-msil-module.md) | Creates an MSIL `.netmodule`. | +| [`/MD`](md-mt-ld-use-run-time-library.md) | Compiles to create a multithreaded DLL, by using *MSVCRT.lib*. | +| [`/MDd`](md-mt-ld-use-run-time-library.md) | Compiles to create a debug multithreaded DLL, by using *MSVCRTD.lib*. | +| [`/MP`](mp-build-with-multiple-processes.md) | Builds multiple source files concurrently. | +| [`/MT`](md-mt-ld-use-run-time-library.md) | Compiles to create a multithreaded executable file, by using *LIBCMT.lib*. | +| [`/MTd`](md-mt-ld-use-run-time-library.md) | Compiles to create a debug multithreaded executable file, by using *LIBCMTD.lib*. | | [`/nologo`](nologo-suppress-startup-banner-c-cpp.md) | Suppresses display of sign-on banner. | | [`/O1`](o1-o2-minimize-size-maximize-speed.md) | Creates small code. | | [`/O2`](o1-o2-minimize-size-maximize-speed.md) | Creates fast code. | -| [`/Ob`](ob-inline-function-expansion.md) | Controls inline expansion. | +| [`/Ob`](ob-inline-function-expansion.md) | Controls inline expansion. | | [`/Od`](od-disable-debug.md) | Disables optimization. | | [`/Og`](og-global-optimizations.md) | Deprecated. Uses global optimizations. | -| [`/Oi`](oi-generate-intrinsic-functions.md) | Generates intrinsic functions. | -| [`/openmp`](openmp-enable-openmp-2-0-support.md) | Enables the [`#pragma omp`](../../preprocessor/omp.md) directive in source code. | +| [`/Oi[-]`](oi-generate-intrinsic-functions.md) | Generates intrinsic functions. | +| [`/openmp`](openmp-enable-openmp-2-0-support.md) | Enables [`#pragma omp`](../../preprocessor/omp.md) in source code. | +| [`/openmp:experimental`](openmp-enable-openmp-2-0-support.md) | Enable OpenMP 2.0 language extensions plus select OpenMP 3.0+ language extensions. | +| [`/openmp:llvm`](openmp-enable-openmp-2-0-support.md) | OpenMP language extensions using LLVM runtime. | +| [`/options:strict`](options-strict.md) | Unrecognized compiler options are errors. | | [`/Os`](os-ot-favor-small-code-favor-fast-code.md) | Favors small code. | | [`/Ot`](os-ot-favor-small-code-favor-fast-code.md) | Favors fast code. | | [`/Ox`](ox-full-optimization.md) | A subset of /O2 that doesn't include /GF or /Gy. | -| [`/Oy`](oy-frame-pointer-omission.md) | Omits frame pointer (x86 only). | +| [`/Oy`](oy-frame-pointer-omission.md) | Omits frame pointer. (x86 only) | | [`/P`](p-preprocess-to-a-file.md) | Writes preprocessor output to a file. | -| [`/permissive-`](permissive-standards-conformance.md) | Set standard-conformance mode. | +| `/PD` | Print all macro definitions. | +| [`/permissive[-]`](permissive-standards-conformance.md) | Set standard-conformance mode. | +| `/PH` | Generate `#pragma file_hash` when preprocessing. | +| `/presetPadding` | Zero initialize padding for stack based class types. | | [`/Qfast_transcendentals`](qfast-transcendentals-force-fast-transcendentals.md) | Generates fast transcendentals. | -| [`/QIfist`](qifist-suppress-ftol.md) | Deprecated. Suppresses `_ftol` when a conversion from a floating-point type to an integral type is required (x86 only). | +| [`/QIfist`](qifist-suppress-ftol.md) | Deprecated. Suppresses the call of the helper function `_ftol` when a conversion from a floating-point type to an integral type is required. (x86 only) | | [`/Qimprecise_fwaits`](qimprecise-fwaits-remove-fwaits-inside-try-blocks.md) | Removes `fwait` commands inside **`try`** blocks. | | [`/QIntel-jcc-erratum`](qintel-jcc-erratum.md) | Mitigates the performance impact of the Intel JCC erratum microcode update. | -| [/Qpar (Auto-Parallelizer)](qpar-auto-parallelizer.md) | Enables automatic parallelization of loops that are marked with the [#pragma loop()](../../preprocessor/loop.md) directive. | +| [`/Qpar-report:`](qpar-report-auto-parallelizer-reporting-level.md) | Enables reporting levels for automatic parallelization. | +| [`/Qpar`](qpar-auto-parallelizer.md) | Enables automatic parallelization of loops. | | [`/Qsafe_fp_loads`](qsafe-fp-loads.md) | Uses integer move instructions for floating-point values and disables certain floating point load optimizations. | -| [`/Qspectre`](qspectre.md) | Specifies compiler generation of instructions to mitigate certain Spectre variant 1 security vulnerabilities. | -| [`/Qspectre-load`](qspectre-load.md) | Specifies compiler generation of serializing instructions to mitigate Spectre security vulnerabilities based on load instructions. | -| [`/Qspectre-load-cf`](qspectre-load-cf.md) | Specifies compiler generation of serializing instructions to mitigate Spectre security vulnerabilities based on control flow instructions that load memory. | -| [`/Qvec-report` (Auto-vectorizer reporting level)](qvec-report-auto-vectorizer-reporting-level.md) | Enables reporting levels for automatic vectorization. | +| [`/Qspectre[-]`](qspectre.md) | Enable mitigations for CVE 2017-5753, for a class of Spectre attacks. | +| [`/Qspectre-load`](qspectre-load.md) | Generate serializing instructions for every load instruction. | +| [`/Qspectre-load-cf`](qspectre-load-cf.md) | Generate serializing instructions for every control flow instruction that loads memory. | +| [`/Qvec-report:`](qvec-report-auto-vectorizer-reporting-level.md) | Enables reporting levels for automatic vectorization. | | [`/reference`](module-reference.md) | Use named module IFC. | -| [`/RTC`](rtc-run-time-error-checks.md) | Enables run-time error checking. | -| [`/sdl`](sdl-enable-additional-security-checks.md) | Enables additional security features and warnings. | -| [`/showIncludes`](showincludes-list-include-files.md) | Displays a list of include files during compilation. | +| [`/RTC1`](rtc-run-time-error-checks.md) | Enable fast runtime checks (equivalent to `/RTCsu`). | +| [`/RTCc`](rtc-run-time-error-checks.md) | Convert to smaller type checks at run-time. | +| [`/RTCs`](rtc-run-time-error-checks.md) | Enable stack frame runtime checks. | +| [`/RTCu`](rtc-run-time-error-checks.md) | Enables uninitialized local usage checks. | +| [`/scanDependencies`](scandependencies.md) | List module dependencies in C++ Standard JSON form. | +| [`/sdl`](sdl-enable-additional-security-checks.md) | Enable more security features and warnings. | +| [`/showIncludes`](showincludes-list-include-files.md) | Displays a list of all include files during compilation. | | [`/source-charset`](source-charset-set-source-character-set.md) | Set source character set. | | [`/sourceDependencies`](sourcedependencies.md) | List all source-level dependencies. | -| [`/sourceDependencies:directives`](sourcedependencies-directives.md) |List module and header unit dependencies. | -| [`/std`](std-specify-language-standard-version.md) | C++ standard version compatibility selector. | -| [`/Tc`](tc-tp-tc-tp-specify-source-file-type.md) | Specifies a C source file. | +| [`/sourceDependencies:directives`](sourcedependencies-directives.md) | List module and header unit dependencies. | +| [`/std:c++14`](std-specify-language-standard-version.md) | C++14 standard ISO/IEC 14882:2014 (default). | +| [`/std:c++17`](std-specify-language-standard-version.md) | C++17 standard ISO/IEC 14882:2017. | +| [`/std:c++20`](std-specify-language-standard-version.md) | C++20 standard ISO/IEC 14882:2020. | +| [`/std:c++latest`](std-specify-language-standard-version.md) | The latest draft C++ standard preview features. | +| [`/std:c11`](std-specify-language-standard-version.md) | C11 standard ISO/IEC 9899:2011. | +| [`/std:c17`](std-specify-language-standard-version.md) | C17 standard ISO/IEC 9899:2018. | +| [`/std:clatest`](std-specify-language-standard-version.md) | The latest draft C standard preview features. | | [`/TC`](tc-tp-tc-tp-specify-source-file-type.md) | Specifies all source files are C. | -| [`/Tp`](tc-tp-tc-tp-specify-source-file-type.md) | Specifies a C++ source file. | +| [`/Tc`](tc-tp-tc-tp-specify-source-file-type.md) | Specifies a C source file. | | [`/TP`](tc-tp-tc-tp-specify-source-file-type.md) | Specifies all source files are C++. | +| [`/Tp`](tc-tp-tc-tp-specify-source-file-type.md) | Specifies a C++ source file. | | [`/translateInclude`](translateinclude.md) | Treat `#include` as `import`. | -| [`/U`](u-u-undefine-symbols.md) | Removes a predefined macro. | +| [`/U`](u-u-undefine-symbols.md) | Removes a predefined macro. | | [`/u`](u-u-undefine-symbols.md) | Removes all predefined macros. | | [`/utf-8`](utf-8-set-source-and-executable-character-sets-to-utf-8.md) | Set source and execution character sets to UTF-8. | -| [`/V`](v-version-number.md) | Deprecated. Sets the .obj file version string. | +| [`/V`](v-version-number.md) | Deprecated. Sets the version string. | | [`/validate-charset`](validate-charset-validate-for-compatible-characters.md) | Validate UTF-8 files for only compatible characters. | -| [`/vd`](vd-disable-construction-displacements.md) | Suppresses or enables hidden vtordisp class members. | +| [`/vd{0|1|2}`](vd-disable-construction-displacements.md) | Suppresses or enables hidden `vtordisp` class members. | +| [`/vlen`](vlen.md) | Specifies vector length. | | [`/vmb`](vmb-vmg-representation-method.md) | Uses best base for pointers to members. | | [`/vmg`](vmb-vmg-representation-method.md) | Uses full generality for pointers to members. | | [`/vmm`](vmm-vms-vmv-general-purpose-representation.md) | Declares multiple inheritance. | | [`/vms`](vmm-vms-vmv-general-purpose-representation.md) | Declares single inheritance. | | [`/vmv`](vmm-vms-vmv-general-purpose-representation.md) | Declares virtual inheritance. | -| [`/volatile`](volatile-volatile-keyword-interpretation.md) | Selects how the volatile keyword is interpreted. | -| [`/w`](compiler-option-warning-level.md) | Disables all warnings. | -| [`/W0`, `/W1`, `/W2`, `/W3`, `/W4`](compiler-option-warning-level.md) | Sets which warning level to output. | -| [`/w1`, `/w2`, `/w3`, `/w4`](compiler-option-warning-level.md) | Sets the warning level for the specified warning. | -| [`/Wall`](compiler-option-warning-level.md) | Enables all warnings, including warnings that are disabled by default. | -| [`/wd`](compiler-option-warning-level.md) | Disables the specified warning. | -| [`/we`](compiler-option-warning-level.md) | Treats the specified warning as an error. | -| [`/WL`](wl-enable-one-line-diagnostics.md) | Enables one-line diagnostics for error and warning messages when compiling C++ source code from the command line. | -| [`/wo`](compiler-option-warning-level.md) | Displays the specified warning only once. | -| [`/Wp64`](wp64-detect-64-bit-portability-issues.md) | Obsolete. Detects 64-bit portability problems. | -| [`/Wv`](compiler-option-warning-level.md) | Displays no warnings introduced after the specified version of the compiler. | -| [`/WX`](compiler-option-warning-level.md) | Treats all warnings as errors. | +| [`/volatile:iso`](volatile-volatile-keyword-interpretation.md) | Acquire/release semantics not guaranteed on volatile accesses. | +| [`/volatile:ms`](volatile-volatile-keyword-interpretation.md) | Acquire/release semantics guaranteed on volatile accesses. | +| [`/volatileMetadata`](volatile.md) | Generate metadata on volatile memory accesses. | +| [`/w`](compiler-option-warning-level.md) | Disable all warnings. | +| [`/W0`, `/W1`, `/W2`, `/W3`, `/W4`](compiler-option-warning-level.md) | Set output warning level. | +| [`/w1`, `/w2`, `/w3`, `/w4`](compiler-option-warning-level.md) | Set warning level for the specified warning. | +| [`/Wall`](compiler-option-warning-level.md) | Enable all warnings, including warnings that are disabled by default. | +| [`/wd`](compiler-option-warning-level.md) | Disable the specified warning. | +| [`/we`](compiler-option-warning-level.md) | Treat the specified warning as an error. | +| [`/WL`](wl-enable-one-line-diagnostics.md) | Enable one-line diagnostics for error and warning messages when compiling C++ source code from the command line. | +| [`/wo`](compiler-option-warning-level.md) | Display the specified warning only once. | +| [`/Wv:xx[.yy[.zzzzz]]`](compiler-option-warning-level.md) | Disable warnings introduced after the specified version of the compiler. | +| [`/WX`](compiler-option-warning-level.md) | Treat warnings as errors. | | [`/X`](x-ignore-standard-include-paths.md) | Ignores the standard include directory. | | [`/Y-`](y-ignore-precompiled-header-options.md) | Ignores all other precompiled-header compiler options in the current build. | -| [`/Yc`](yc-create-precompiled-header-file.md) | Creates a precompiled header file. | +| [`/Yc`](yc-create-precompiled-header-file.md) | Create *`.PCH`* file. | | [`/Yd`](yd-place-debug-information-in-object-file.md) | Deprecated. Places complete debugging information in all object files. Use [`/Zi`](z7-zi-zi-debug-information-format.md) instead. | -| [`/Yl`](yl-inject-pch-reference-for-debug-library.md) | Injects a PCH reference when creating a debug library | +| [`/Yl`](yl-inject-pch-reference-for-debug-library.md) | Injects a PCH reference when creating a debug library. | | [`/Yu`](yu-use-precompiled-header-file.md) | Uses a precompiled header file during build. | | [`/Z7`](z7-zi-zi-debug-information-format.md) | Generates C 7.0-compatible debugging information. | -| [`/Za`](za-ze-disable-language-extensions.md) | Disables language extensions. | -| [`/Zc`](zc-conformance.md) | Specifies standard behaviors. | -| [`/Ze`](za-ze-disable-language-extensions.md) | Deprecated. Enables language extensions. | +| [`/Za`](za-ze-disable-language-extensions.md) | Disables some C89 language extensions in C code. | +| [`/Zc:__cplusplus[-]`](zc-cplusplus.md) | Enable the `__cplusplus` macro to report the supported standard (off by default). | +| [`/Zc:__STDC__`](zc-stdc.md) | Enable the `__STDC__` macro to report the C standard is supported (off by default). | +| [`/Zc:alignedNew[-]`](zc-alignednew.md) | Enable C++17 over-aligned dynamic allocation (on by default in C++17). | +| [`/Zc:auto[-]`](zc-auto-deduce-variable-type.md) | Enforce the new Standard C++ meaning for **`auto`** (on by default). | +| [`/Zc:char8_t[-]`](zc-char8-t.md) | Enable or disable C++20 native `u8` literal support as `const char8_t` (off by default, except under **`/std:c++20`**). | +| [`/Zc:enumTypes[-]`](zc-enumtypes.md) | Enable Standard C++ rules for `enum` type deduction (off by default). | +| [`/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). | +| [`/Zc:tlsGuards[-]`](zc-tlsguards.md) | Generate runtime checks for TLS variable initialization (on by default). | +| [`/Zc:trigraphs`](zc-trigraphs-trigraphs-substitution.md) | Enable trigraphs (obsolete, off by default). | +| [`/Zc:twoPhase[-]`](zc-twophase.md) | Use nonconforming template parsing behavior (conforming by default). | +| [`/Zc:wchar_t[-]`](zc-wchar-t-wchar-t-is-native-type.md) | **`wchar_t`** is a native type, not a typedef (on by default). | +| [`/Zc:zeroSizeArrayNew[-]`](zc-zerosizearraynew.md) | Call member `new`/`delete` for zero-size arrays of objects (on by default). | +| [`/Ze`](za-ze-disable-language-extensions.md) | Deprecated. Enables C89 language extensions. | | [`/Zf`](zf.md) | Improves PDB generation time in parallel builds. | -| [`/Zg`](zg-generate-function-prototypes.md) | Removed in Visual Studio 2015. Generates function prototypes. | -| [`/ZH`](zh.md) | Specifies MD5, SHA-1, or SHA-256 for checksums in debug info. | -| [`/ZI`](z7-zi-zi-debug-information-format.md) | Includes debug information in a program database compatible with Edit and Continue. | +| [`/ZH:[MD5|SHA1|SHA_256]`](zh.md) | Specifies MD5, SHA-1, or SHA-256 for checksums in debug info. | +| [`/ZI`](z7-zi-zi-debug-information-format.md) | Includes debug information in a program database compatible with Edit and Continue. (x86 only) | | [`/Zi`](z7-zi-zi-debug-information-format.md) | Generates complete debugging information. | -| [`/Zl`](zl-omit-default-library-name.md) | Removes default library name from .obj file (x86 only). | +| [`/Zl`](zl-omit-default-library-name.md) | Removes the default library name from the *`.obj`* file. | | [`/Zm`](zm-specify-precompiled-header-memory-allocation-limit.md) | Specifies the precompiled header memory allocation limit. | -| [`/Zo`](zo-enhance-optimized-debugging.md) | Generates enhanced debugging information for optimized code. | -| [`/Zp`](zp-struct-member-alignment.md) | Packs structure members. | +| [`/Zo[-]`](zo-enhance-optimized-debugging.md) | Generate richer debugging information for optimized code. | +| [`/Zp[n]`](zp-struct-member-alignment.md) | Packs structure members. | | [`/Zs`](zs-syntax-check-only.md) | Checks syntax only. | | [`/ZW`](zw-windows-runtime-compilation.md) | Produces an output file to run on the Windows Runtime. | +17.10 This option is available starting in Visual Studio 2022 version 17.10.\ +17.14 This option is available starting in Visual Studio 2022 version 17.14. + ## See also [MSVC compiler options](compiler-options.md)\ diff --git a/docs/build/reference/compiler-options-listed-by-category.md b/docs/build/reference/compiler-options-listed-by-category.md index ec95e10c9b..2fbfbc1357 100644 --- a/docs/build/reference/compiler-options-listed-by-category.md +++ b/docs/build/reference/compiler-options-listed-by-category.md @@ -1,9 +1,8 @@ --- title: "Compiler Options Listed by Category" description: "Reference listing by category of the Microsoft C/C++ compiler command-line options." -ms.date: 07/29/2020 +ms.date: 2/5/2025 helpviewer_keywords: ["compiler options, C++"] -ms.assetid: c4750dcf-dba0-4229-99b6-45cdecc11729 --- # Compiler options listed by category @@ -13,62 +12,91 @@ This article contains a categorical list of compiler options. For an alphabetica | Option | Purpose | |--|--| +| [`/dynamicdeopt`](dynamic-deopt.md) | Enable [C++ Dynamic Debugging (Preview)](/visualstudio/debugger/cpp-dynamic-debugging) to debug optimized code as if it had been compiled deoptimized. | +| [`/favor:`](favor-optimize-for-architecture-specifics.md) | Produces code that is optimized for a specified architecture, or for a range of architectures. | | [`/O1`](o1-o2-minimize-size-maximize-speed.md) | Creates small code. | | [`/O2`](o1-o2-minimize-size-maximize-speed.md) | Creates fast code. | -| [`/Ob`](ob-inline-function-expansion.md) | Controls inline expansion. | +| [`/Ob`](ob-inline-function-expansion.md) | Controls inline expansion. | | [`/Od`](od-disable-debug.md) | Disables optimization. | | [`/Og`](og-global-optimizations.md) | Deprecated. Uses global optimizations. | -| [`/Oi`](oi-generate-intrinsic-functions.md) | Generates intrinsic functions. | +| [`/Oi[-]`](oi-generate-intrinsic-functions.md) | Generates intrinsic functions. | | [`/Os`](os-ot-favor-small-code-favor-fast-code.md) | Favors small code. | | [`/Ot`](os-ot-favor-small-code-favor-fast-code.md) | Favors fast code. | | [`/Ox`](ox-full-optimization.md) | A subset of /O2 that doesn't include /GF or /Gy. | | [`/Oy`](oy-frame-pointer-omission.md) | Omits frame pointer. (x86 only) | -| [`/favor`](favor-optimize-for-architecture-specifics.md) | Produces code that is optimized for a specified architecture, or for a range of architectures. | ## Code generation | Option | Purpose | |--|--| -| [`/arch`](arch-x86.md) | Use SSE or SSE2 instructions in code generation. (x86 only) | +| [`/arch`](arch-minimum-cpu-architecture.md) | Minimum CPU architecture requirements. | | [`/clr`](clr-common-language-runtime-compilation.md) | Produces an output file to run on the common language runtime. | -| [`/EH`](eh-exception-handling-model.md) | Specifies the model of exception handling. | -| [`/fp`](fp-specify-floating-point-behavior.md) | Specifies floating-point behavior. | +| [`/clr:implicitKeepAlive-`](clr-common-language-runtime-compilation.md) | Turn off implicit emission of `System::GC::KeepAlive(this)`. | +| [`/clr:initialAppDomain`](clr-common-language-runtime-compilation.md) | Enable initial AppDomain behavior of Visual C++ 2002. | +| [`/clr:netcore`](clr-common-language-runtime-compilation.md) | Produce assemblies targeting .NET Core runtime. | +| [`/clr:noAssembly`](clr-common-language-runtime-compilation.md) | Don't produce an assembly. | +| [`/clr:nostdimport`](clr-common-language-runtime-compilation.md) | Don't import any required assemblies implicitly. | +| [`/clr:nostdlib`](clr-common-language-runtime-compilation.md) | Ignore the system .NET framework directory when searching for assemblies. | +| [`/clr:pure`](clr-common-language-runtime-compilation.md) | Produce an IL-only output file (no native executable code). | +| [`/clr:safe`](clr-common-language-runtime-compilation.md) | Produce an IL-only verifiable output file. | +| [`/EHa`](eh-exception-handling-model.md) | Enable C++ exception handling (with SEH exceptions). | +| [`/EHc`](eh-exception-handling-model.md) | `extern "C"` defaults to `nothrow`. | +| [`/EHr`](eh-exception-handling-model.md) | Always generate `noexcept` runtime termination checks. | +| [`/EHs`](eh-exception-handling-model.md) | Enable C++ exception handling (no SEH exceptions). | +| [`/feature`](feature-arm64.md) | Enable architecture features.17.10 | +| [`/forceInterlockedFunctions`](force-interlocked-functions.md) | Dynamically selects between Armv8.0 load, store exclusive instructions or Armv8.1 LSE atomic instructions based on target CPU.17.14 | +| [`/fp:contract`](fp-specify-floating-point-behavior.md) | Consider floating-point contractions when generating code. | +| [`/fp:except[-]`](fp-specify-floating-point-behavior.md) | Consider floating-point exceptions when generating code. | +| [`/fp:fast`](fp-specify-floating-point-behavior.md) | "fast" floating-point model; results are less predictable. | +| [`/fp:precise`](fp-specify-floating-point-behavior.md) | "precise" floating-point model; results are predictable. | +| [`/fp:strict`](fp-specify-floating-point-behavior.md) | "strict" floating-point model (implies `/fp:except`). | +| [`/fpcvt:BC`](fpcvt.md) | Backward-compatible floating-point to unsigned integer conversions. | +| [`/fpcvt:IA`](fpcvt.md) | Intel native floating-point to unsigned integer conversion behavior. | +| [`/fsanitize`](fsanitize.md) | Enables compilation of sanitizer instrumentation such as AddressSanitizer. | +| [`/fsanitize-coverage`](fsanitize-coverage.md) | Enables compilation of code coverage instrumentation for libraries such as LibFuzzer. | | [`/GA`](ga-optimize-for-windows-application.md) | Optimizes for Windows applications. | | [`/Gd`](gd-gr-gv-gz-calling-convention.md) | Uses the **`__cdecl`** calling convention. (x86 only) | | [`/Ge`](ge-enable-stack-probes.md) | Deprecated. Activates stack probes. | | [`/GF`](gf-eliminate-duplicate-strings.md) | Enables string pooling. | | [`/Gh`](gh-enable-penter-hook-function.md) | Calls hook function `_penter`. | | [`/GH`](gh-enable-pexit-hook-function.md) | Calls hook function `_pexit`. | -| [`/GL`](gl-whole-program-optimization.md) | Enables whole program optimization. | -| [`/Gm`](gm-enable-minimal-rebuild.md) | Deprecated. Enables minimal rebuild. | -| [`/GR`](gr-enable-run-time-type-information.md) | Enables run-time type information (RTTI). | +| [`/GL[-]`](gl-whole-program-optimization.md) | Enables whole program optimization. | +| [`/Gm[-]`](gm-enable-minimal-rebuild.md) | Deprecated. Enables minimal rebuild. | | [`/Gr`](gd-gr-gv-gz-calling-convention.md) | Uses the **`__fastcall`** calling convention. (x86 only) | -| [`/GS`](gs-buffer-security-check.md) | Checks buffer security. | -| [`/Gs`](gs-control-stack-checking-calls.md) | Controls stack probes. | +| [`/GR[-]`](gr-enable-run-time-type-information.md) | Enables run-time type information (RTTI). | +| [`/GS[-]`](gs-buffer-security-check.md) | Checks buffer security. | +| [`/Gs[n]`](gs-control-stack-checking-calls.md) | Controls stack probes. | | [`/GT`](gt-support-fiber-safe-thread-local-storage.md) | Supports fiber safety for data allocated by using static thread-local storage. | -| [`/guard:cf`](guard-enable-control-flow-guard.md) | Adds control flow guard security checks. | -| [`/guard:ehcont`](guard-enable-eh-continuation-metadata.md) | Enables EH continuation metadata. | +| `/Gu[-]` | Ensure distinct functions have distinct addresses. | +| [`/guard:cf[-]`](guard-enable-control-flow-guard.md) | Adds control flow guard security checks. | +| [`/guard:ehcont[-]`](guard-enable-eh-continuation-metadata.md) | Enables EH continuation metadata. | | [`/Gv`](gd-gr-gv-gz-calling-convention.md) | Uses the **`__vectorcall`** calling convention. (x86 and x64 only) | -| [`/Gw`](gw-optimize-global-data.md) | Enables whole-program global data optimization. | -| [`/GX`](gx-enable-exception-handling.md) | Deprecated. Enables synchronous exception handling. Use [`/EH`](eh-exception-handling-model.md) instead. | -| [`/Gy`](gy-enable-function-level-linking.md) | Enables function-level linking. | -| [`/GZ`](gz-enable-stack-frame-run-time-error-checking.md) | Deprecated. Enables fast checks. (Same as [`/RTC1`](rtc-run-time-error-checks.md)) | +| [`/Gw[-]`](gw-optimize-global-data.md) | Enables whole-program global data optimization. | +| [`/GX[-]`](gx-enable-exception-handling.md) | Deprecated. Enables synchronous exception handling. Use [`/EH`](eh-exception-handling-model.md) instead. | +| [`/Gy[-]`](gy-enable-function-level-linking.md) | Enables function-level linking. | | [`/Gz`](gd-gr-gv-gz-calling-convention.md) | Uses the **`__stdcall`** calling convention. (x86 only) | +| [`/GZ`](gz-enable-stack-frame-run-time-error-checking.md) | Deprecated. Enables fast checks. (Same as [`/RTC1`](rtc-run-time-error-checks.md)) | | [`/homeparams`](homeparams-copy-register-parameters-to-stack.md) | Forces parameters passed in registers to be written to their locations on the stack upon function entry. This compiler option is only for the x64 compilers (native and cross compile). | | [`/hotpatch`](hotpatch-create-hotpatchable-image.md) | Creates a hotpatchable image. | +| [`/jumptablerdata`](jump-table-rdata.md) | Put switch case statement jump tables in the `.rdata` section. | | [`/Qfast_transcendentals`](qfast-transcendentals-force-fast-transcendentals.md) | Generates fast transcendentals. | | [`/QIfist`](qifist-suppress-ftol.md) | Deprecated. Suppresses the call of the helper function `_ftol` when a conversion from a floating-point type to an integral type is required. (x86 only) | | [`/Qimprecise_fwaits`](qimprecise-fwaits-remove-fwaits-inside-try-blocks.md) | Removes `fwait` commands inside **`try`** blocks. | | [`/QIntel-jcc-erratum`](qintel-jcc-erratum.md) | Mitigates the performance impact of the Intel JCC erratum microcode update. | | [`/Qpar`](qpar-auto-parallelizer.md) | Enables automatic parallelization of loops. | -| [`/Qpar-report`](qpar-report-auto-parallelizer-reporting-level.md) | Enables reporting levels for automatic parallelization. | +| [`/Qpar-report:n`](qpar-report-auto-parallelizer-reporting-level.md) | Enables reporting levels for automatic parallelization. | | [`/Qsafe_fp_loads`](qsafe-fp-loads.md) | Uses integer move instructions for floating-point values and disables certain floating point load optimizations. | -| [`/Qspectre`](qspectre.md) | Enable mitigations for CVE 2017-5753, for a class of Spectre attacks. | +| [`/Qspectre[-]`](qspectre.md) | Enable mitigations for CVE 2017-5753, for a class of Spectre attacks. | | [`/Qspectre-load`](qspectre-load.md) | Generate serializing instructions for every load instruction. | | [`/Qspectre-load-cf`](qspectre-load-cf.md) | Generate serializing instructions for every control flow instruction that loads memory. | -| [`/Qvec-report`](qvec-report-auto-vectorizer-reporting-level.md) | Enables reporting levels for automatic vectorization. | -| [`/RTC`](rtc-run-time-error-checks.md) | Enables run-time error checking. | -| [`/volatile`](volatile-volatile-keyword-interpretation.md) | Selects how the volatile keyword is interpreted. | +| [`/Qvec-report:n`](qvec-report-auto-vectorizer-reporting-level.md) | Enables reporting levels for automatic vectorization. | +| [`/RTC1`](rtc-run-time-error-checks.md) | Enable fast runtime checks (equivalent to `/RTCsu`). | +| [`/RTCc`](rtc-run-time-error-checks.md) | Convert to smaller type checks at run-time. | +| [`/RTCs`](rtc-run-time-error-checks.md) | Enable stack frame runtime checks. | +| [`/RTCu`](rtc-run-time-error-checks.md) | Enables uninitialized local usage checks. | +| [`/vlen`](vlen.md) | Specifies vector length. | +| [`/volatile:iso`](volatile-volatile-keyword-interpretation.md) | Acquire/release semantics not guaranteed on volatile accesses. | +| [`/volatile:ms`](volatile-volatile-keyword-interpretation.md) | Acquire/release semantics guaranteed on volatile accesses. | ## Output files @@ -83,34 +111,41 @@ This article contains a categorical list of compiler options. For an alphabetica | [`/Fm`](fm-name-mapfile.md) | Creates a mapfile. | | [`/Fo`](fo-object-file-name.md) | Creates an object file. | | [`/Fp`](fp-name-dot-pch-file.md) | Specifies a precompiled header file name. | -| [`/FR`, `/Fr`](fr-fr-create-dot-sbr-file.md) | Name generated *`.sbr`* browser files. | +| [`/FR`, `/Fr`](fr-fr-create-dot-sbr-file.md) | Name generated *`.sbr`* browser files. **`/Fr`** is deprecated. | +| `/Ft` | Location of the header files generated for `#import`. | ## Preprocessor | Option | Purpose | |--|--| -| [`/AI`](ai-specify-metadata-directories.md) | Specifies a directory to search to resolve file references passed to the [#using](../../preprocessor/hash-using-directive-cpp.md) directive. | +| [`/AI`](ai-specify-metadata-directories.md) | Specifies a directory to search to resolve file references passed to the [`#using`](../../preprocessor/hash-using-directive-cpp.md) directive. | | [`/C`](c-preserve-comments-during-preprocessing.md) | Preserves comments during preprocessing. | -| [`/D`](d-preprocessor-definitions.md) | Defines constants and macros. | +| [`/D{=|#}`](d-preprocessor-definitions.md) | Defines constants and macros. | | [`/E`](e-preprocess-to-stdout.md) | Copies preprocessor output to standard output. | | [`/EP`](ep-preprocess-to-stdout-without-hash-line-directives.md) | Copies preprocessor output to standard output. | -| [`/FI`](fi-name-forced-include-file.md) | Preprocesses the specified include file. | -| [`/FU`](fu-name-forced-hash-using-file.md) | Forces the use of a file name, as if it had been passed to the [#using](../../preprocessor/hash-using-directive-cpp.md) directive. | +| [`/FI`](fi-name-forced-include-file.md) | Preprocesses the specified include file. | +| [`/FU`](fu-name-forced-hash-using-file.md) | Forces the use of a file name, as if it had been passed to the [`#using`](../../preprocessor/hash-using-directive-cpp.md) directive. | | [`/Fx`](fx-merge-injected-code.md) | Merges injected code with the source file. | -| [`/I`](i-additional-include-directories.md) | Searches a directory for include files. | +| [`/I`](i-additional-include-directories.md) | Searches a directory for include files. | | [`/P`](p-preprocess-to-a-file.md) | Writes preprocessor output to a file. | -| [`/U`](u-u-undefine-symbols.md) | Removes a predefined macro. | +| `/PD` | Print all macro definitions. | +| `/PH` | Generate `#pragma file_hash` when preprocessing. | +| [`/U`](u-u-undefine-symbols.md) | Removes a predefined macro. | | [`/u`](u-u-undefine-symbols.md) | Removes all predefined macros. | | [`/X`](x-ignore-standard-include-paths.md) | Ignores the standard include directory. | -## Header units +## Header units/modules | Option | Purpose | |--|--| | [`/exportHeader`](module-exportheader.md) | Create the header units files (*`.ifc`*) specified by the input arguments. | -| [`/headerUnit`](headerunit.md) | Specify where to find the header unit file (`.ifc`) for the specified header. | +| [`/headerUnit`](headerunit.md) | Specify where to find the header unit file (*`.ifc`*) for the specified header. | | [`/headerName`](headername.md) | Build a header unit from the specified header. | +| [`/ifcOutput`](ifc-output.md) | Specify the output file name or directory for built *`.ifc`* files. | +| [`/interface`](interface.md) | Treat the input file as a module interface unit. | +| [`/internalPartition`](internal-partition.md) | Treat the input file as an internal partition unit. | | [`/reference`](module-reference.md) | Use named module IFC. | +| [`/scanDependencies`](scandependencies.md) | List module and header unit dependencies in C++ Standard JSON form. | | [`/sourceDependencies`](sourcedependencies.md) | List all source-level dependencies. | | [`/sourceDependencies:directives`](sourcedependencies-directives.md) | List module and header unit dependencies. | | [`/translateInclude`](translateinclude.md) | Treat `#include` as `import`. | @@ -119,24 +154,68 @@ This article contains a categorical list of compiler options. For an alphabetica | Option | Purpose | |--|--| -| [`/constexpr`](constexpr-control-constexpr-evaluation.md) | Control **`constexpr`** evaluation at compile time. | +| [`/await`](await-enable-coroutine-support.md) | Enable coroutines (resumable functions) extensions. | +| [`/await:strict`](await-enable-coroutine-support.md) | Enable standard C++20 coroutine support with earlier language versions. | +| [`/constexpr:backtrace`](constexpr-control-constexpr-evaluation.md) | Show N `constexpr` evaluations in diagnostics (default: 10). | +| [`/constexpr:depth`](constexpr-control-constexpr-evaluation.md) | Recursion depth limit for `constexpr` evaluation (default: 512). | +| [`/constexpr:steps`](constexpr-control-constexpr-evaluation.md) | Terminate `constexpr` evaluation after N steps (default: 100000) | | [`/openmp`](openmp-enable-openmp-2-0-support.md) | Enables [`#pragma omp`](../../preprocessor/omp.md) in source code. | -| [`/vd`](vd-disable-construction-displacements.md) | Suppresses or enables hidden `vtordisp` class members. | +| [`/openmp:experimental`](openmp-enable-openmp-2-0-support.md) | Enable OpenMP 2.0 language extensions plus select OpenMP 3.0+ language extensions. | +| [`/openmp:llvm`](openmp-enable-openmp-2-0-support.md) | OpenMP language extensions using LLVM runtime. | +| [`/permissive[-]`](permissive-standards-conformance.md) | Set standard-conformance mode. | +| [`/std:c++14`](std-specify-language-standard-version.md) | C++14 standard ISO/IEC 14882:2014 (default). | +| [`/std:c++17`](std-specify-language-standard-version.md) | C++17 standard ISO/IEC 14882:2017. | +| [`/std:c++20`](std-specify-language-standard-version.md) | C++20 standard ISO/IEC 14882:2020. | +| [`/std:c++latest`](std-specify-language-standard-version.md) | The latest draft C++ standard preview features. | +| [`/std:c11`](std-specify-language-standard-version.md) | C11 standard ISO/IEC 9899:2011. | +| [`/std:c17`](std-specify-language-standard-version.md) | C17 standard ISO/IEC 9899:2018. | +| [`/std:clatest`](std-specify-language-standard-version.md) | The latest draft C standard preview features. | +| [`/vd{0|1|2}`](vd-disable-construction-displacements.md) | Suppresses or enables hidden `vtordisp` class members. | | [`/vmb`](vmb-vmg-representation-method.md) | Uses best base for pointers to members. | | [`/vmg`](vmb-vmg-representation-method.md) | Uses full generality for pointers to members. | | [`/vmm`](vmm-vms-vmv-general-purpose-representation.md) | Declares multiple inheritance. | | [`/vms`](vmm-vms-vmv-general-purpose-representation.md) | Declares single inheritance. | | [`/vmv`](vmm-vms-vmv-general-purpose-representation.md) | Declares virtual inheritance. | | [`/Z7`](z7-zi-zi-debug-information-format.md) | Generates C 7.0-compatible debugging information. | -| [`/Za`](za-ze-disable-language-extensions.md) | Disables C89 language extensions. | -| [`/Zc`](zc-conformance.md) | Specifies standard behavior under [`/Ze`](za-ze-disable-language-extensions.md). | +| [`/Za`](za-ze-disable-language-extensions.md) | Disables some C89 language extensions in C code. | +| [`/Zc:__cplusplus[-]`](zc-cplusplus.md) | Enable the `__cplusplus` macro to report the supported standard (off by default). | +| [`/Zc:__STDC__`](zc-stdc.md) | Enable the `__STDC__` macro to report the C standard is supported (off by default). | +| [`/Zc:alignedNew[-]`](zc-alignednew.md) | Enable C++17 over-aligned dynamic allocation (on by default in C++17). | +| [`/Zc:auto[-]`](zc-auto-deduce-variable-type.md) | Enforce the new Standard C++ meaning for **`auto`** (on by default). | +| [`/Zc:char8_t[-]`](zc-char8-t.md) | Enable or disable C++20 native `u8` literal support as `const char8_t` (off by default, except under **`/std:c++20`**). | +| [`/Zc:enumTypes[-]`](zc-enumtypes.md) | Enable Standard C++ rules for inferred `enum` base types (Off b y default, not implied by **`/permissive-`**). | +| [`/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). | +| [`/Zc:tlsGuards[-]`](zc-tlsguards.md) | Generate runtime checks for TLS variable initialization (on by default). | +| [`/Zc:trigraphs`](zc-trigraphs-trigraphs-substitution.md) | Enable trigraphs (obsolete, off by default). | +| [`/Zc:twoPhase[-]`](zc-twophase.md) | Use nonconforming template parsing behavior (conforming by default). | +| [`/Zc:wchar_t[-]`](zc-wchar-t-wchar-t-is-native-type.md) | **`wchar_t`** is a native type, not a typedef (on by default). | +| [`/Zc:zeroSizeArrayNew[-]`](zc-zerosizearraynew.md) | Call member `new`/`delete` for 0-size arrays of objects (on by default). | | [`/Ze`](za-ze-disable-language-extensions.md) | Deprecated. Enables C89 language extensions. | | [`/Zf`](zf.md) | Improves PDB generation time in parallel builds. | -| [`/ZH`](zh.md) | Specifies MD5, SHA-1, or SHA-256 for checksums in debug info. | +| [`/ZH`:[MD5|SHA1|SHA_256]](zh.md) | Specifies MD5, SHA-1, or SHA-256 for checksums in debug info. | | [`/ZI`](z7-zi-zi-debug-information-format.md) | Includes debug information in a program database compatible with Edit and Continue. (x86 only) | | [`/Zi`](z7-zi-zi-debug-information-format.md) | Generates complete debugging information. | | [`/Zl`](zl-omit-default-library-name.md) | Removes the default library name from the *`.obj`* file. | -| [`/Zp`](zp-struct-member-alignment.md) *n* | Packs structure members. | +| [`/Zo[-]`](zo-enhance-optimized-debugging.md) | Generate richer debugging information for optimized code. | +| [`/Zp[n]`](zp-struct-member-alignment.md) | Packs structure members. | | [`/Zs`](zs-syntax-check-only.md) | Checks syntax only. | | [`/ZW`](zw-windows-runtime-compilation.md) | Produces an output file to run on the Windows Runtime. | @@ -148,7 +227,7 @@ This article contains a categorical list of compiler options. For an alphabetica | [`/LD`](md-mt-ld-use-run-time-library.md) | Creates a dynamic-link library. | | [`/LDd`](md-mt-ld-use-run-time-library.md) | Creates a debug dynamic-link library. | | [`/link`](link-pass-options-to-linker.md) | Passes the specified option to LINK. | -| [`/LN`](ln-create-msil-module.md) | Creates an MSIL module. | +| [`/LN`](ln-create-msil-module.md) | Creates an MSIL `.netmodule`. | | [`/MD`](md-mt-ld-use-run-time-library.md) | Compiles to create a multithreaded DLL, by using *MSVCRT.lib*. | | [`/MDd`](md-mt-ld-use-run-time-library.md) | Compiles to create a debug multithreaded DLL, by using *MSVCRTD.lib*. | | [`/MT`](md-mt-ld-use-run-time-library.md) | Compiles to create a multithreaded executable file, by using *LIBCMT.lib*. | @@ -164,49 +243,60 @@ This article contains a categorical list of compiler options. For an alphabetica | [`/bigobj`](bigobj-increase-number-of-sections-in-dot-obj-file.md) | Increases the number of addressable sections in an .obj file. | | [`/c`](c-compile-without-linking.md) | Compiles without linking. | | [`/cgthreads`](cgthreads-code-generation-threads.md) | Specifies number of *cl.exe* threads to use for optimization and code generation. | -| [`/errorReport`](errorreport-report-internal-compiler-errors.md) | Deprecated. Error reporting is controlled by [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings. | -| [`/external`](external-external-headers-diagnostics.md) | Allows control of diagnostics in external headers. | +| [`/errorReport`](errorreport-report-internal-compiler-errors.md) | Deprecated. [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings control error reporting. | +| [`/execution-charset`](execution-charset-set-execution-character-set.md) | Set execution character set. | +| `/fastfail` | Enable fast-fail mode. | | [`/FC`](fc-full-path-of-source-code-file-in-diagnostics.md) | Displays the full path of source code files passed to *cl.exe* in diagnostic text. | | [`/FS`](fs-force-synchronous-pdb-writes.md) | Forces writes to the PDB file to be serialized through *MSPDBSRV.EXE*. | -| [`/fsanitize`](fsanitize.md) | Enables compilation of sanitizer instrumentation such as AddressSanitizer. | | [`/H`](h-restrict-length-of-external-names.md) | Deprecated. Restricts the length of external (public) names. | | [`/HELP`](help-compiler-command-line-help.md) | Lists the compiler options. | | [`/J`](j-default-char-type-is-unsigned.md) | Changes the default **`char`** type. | | [`/JMC`](jmc.md) | Supports native C++ Just My Code debugging. | -| [`/kernel`](kernel-create-kernel-mode-binary.md) | The compiler and linker will create a binary that can be executed in the Windows kernel. | +| [`/kernel`](kernel-create-kernel-mode-binary.md) | The compiler and linker create a binary that can be executed in the Windows kernel. | | [`/MP`](mp-build-with-multiple-processes.md) | Builds multiple source files concurrently. | | [`/nologo`](nologo-suppress-startup-banner-c-cpp.md) | Suppresses display of sign-on banner. | -| [`/sdl`](sdl-enable-additional-security-checks.md) | Enables additional security features and warnings. | +| `/presetPadding` | Zero initialize padding for stack based class types. | | [`/showIncludes`](showincludes-list-include-files.md) | Displays a list of all include files during compilation. | +| [`/source-charset`](source-charset-set-source-character-set.md) | Set source character set. | | [`/Tc`](tc-tp-tc-tp-specify-source-file-type.md) | Specifies a C source file. | | [`/TC`](tc-tp-tc-tp-specify-source-file-type.md) | Specifies all source files are C. | | [`/Tp`](tc-tp-tc-tp-specify-source-file-type.md) | Specifies a C++ source file. | | [`/TP`](tc-tp-tc-tp-specify-source-file-type.md) | Specifies all source files are C++. | +| [`/utf-8`](utf-8-set-source-and-executable-character-sets-to-utf-8.md) | Set source and execution character sets to UTF-8. | | [`/V`](v-version-number.md) | Deprecated. Sets the version string. | -| [`/w`](compiler-option-warning-level.md) | Disables all warnings. | -| [`/W0`, `/W1`, `/W2`, `/W3`, `/W4`](compiler-option-warning-level.md) | Sets output warning level. | -| [`/w1`, `/w2`, `/w3`, `/w4`](compiler-option-warning-level.md) | Sets warning level for the specified warning. | -| [`/Wall`](compiler-option-warning-level.md) | Enables all warnings, including warnings that are disabled by default. | -| [`/wd`](compiler-option-warning-level.md) | Disables the specified warning. | -| [`/we`](compiler-option-warning-level.md) | Treats the specified warning as an error. | -| [`/WL`](wl-enable-one-line-diagnostics.md) | Enables one-line diagnostics for error and warning messages when compiling C++ source code from the command line. | -| [`/wo`](compiler-option-warning-level.md) | Displays the specified warning only once. | -| [`/Wv`](compiler-option-warning-level.md) | Disables warnings introduced by later versions of the compiler. | -| [`/WX`](compiler-option-warning-level.md) | Treats warnings as errors. | +| [`/validate-charset`](validate-charset-validate-for-compatible-characters.md) | Validate UTF-8 files for only compatible characters. | +| [`/volatileMetadata`](volatile.md) | Generate metadata on volatile memory accesses. | | [`/Yc`](yc-create-precompiled-header-file.md) | Create *`.PCH`* file. | | [`/Yd`](yd-place-debug-information-in-object-file.md) | Deprecated. Places complete debugging information in all object files. Use [`/Zi`](z7-zi-zi-debug-information-format.md) instead. | | [`/Yl`](yl-inject-pch-reference-for-debug-library.md) | Injects a PCH reference when creating a debug library. | | [`/Yu`](yu-use-precompiled-header-file.md) | Uses a precompiled header file during build. | | [`/Y-`](y-ignore-precompiled-header-options.md) | Ignores all other precompiled-header compiler options in the current build. | | [`/Zm`](zm-specify-precompiled-header-memory-allocation-limit.md) | Specifies the precompiled header memory allocation limit. | -| [`/await`](await-enable-coroutine-support.md) | Enable coroutines (resumable functions) extensions. | -| [`/source-charset`](source-charset-set-source-character-set.md) | Set source character set. | -| [`/execution-charset`](execution-charset-set-execution-character-set.md) | Set execution character set. | -| [`/utf-8`](utf-8-set-source-and-executable-character-sets-to-utf-8.md) | Set source and execution character sets to UTF-8. | -| [`/validate-charset`](validate-charset-validate-for-compatible-characters.md) | Validate UTF-8 files for only compatible characters. | -| [`/diagnostics`](diagnostics-compiler-diagnostic-options.md) | Controls the format of diagnostic messages. | -| [`/permissive-`](permissive-standards-conformance.md) | Set standard-conformance mode. | -| [`/std`](std-specify-language-standard-version.md) | C++ standard version compatibility selector. | + +## Diagnostics + +| Option | Purpose | +|--|--| +| [`/diagnostics:caret[-]`](diagnostics-compiler-diagnostic-options.md) | Diagnostics format: prints column and the indicated line of source. | +| [`/diagnostics:classic`](diagnostics-compiler-diagnostic-options.md) | Use legacy diagnostics format. | +| [`/diagnostics`](diagnostics-compiler-diagnostic-options.md) | Diagnostics format: prints column information. | +| [`/external:anglebrackets`](external-external-headers-diagnostics.md) | Treat all headers included via `<>` as external. | +| [`/external:env:`](external-external-headers-diagnostics.md) | Specify an environment variable with locations of external headers. | +| [`/external:I `](external-external-headers-diagnostics.md) | Specify location of external headers. | +| [`/external:templates[-]`](external-external-headers-diagnostics.md) | Evaluate warning level across template instantiation chain. | +| [`/external:W`](external-external-headers-diagnostics.md) | Set warning level for external headers. | +| [`/options:strict`](options-strict.md) | Unrecognized compiler options are errors. | +| [`/sdl`](sdl-enable-additional-security-checks.md) | Enable more security features and warnings. | +| [`/w`](compiler-option-warning-level.md) | Disable all warnings. | +| [`/W0`, `/W1`, `/W2`, `/W3`, `/W4`](compiler-option-warning-level.md) | Set output warning level. | +| [`/w1`, `/w2`, `/w3`, `/w4`](compiler-option-warning-level.md) | Set warning level for the specified warning. | +| [`/Wall`](compiler-option-warning-level.md) | Enable all warnings, including warnings that are disabled by default. | +| [`/wd`](compiler-option-warning-level.md) | Disable the specified warning. | +| [`/we`](compiler-option-warning-level.md) | Treat the specified warning as an error. | +| [`/WL`](wl-enable-one-line-diagnostics.md) | Enable one-line diagnostics for error and warning messages when compiling C++ source code from the command line. | +| [`/wo`](compiler-option-warning-level.md) | Display the specified warning only once. | +| [`/Wv:xx[.yy[.zzzzz]]`](compiler-option-warning-level.md) | Disable warnings introduced after the specified version of the compiler. | +| [`/WX`](compiler-option-warning-level.md) | Treat warnings as errors. | ## Experimental options @@ -214,8 +304,8 @@ Experimental options may only be supported by certain versions of the compiler. | Option | Purpose | |--|--| +| [`/experimental:log`](experimental-log.md) | Enables experimental structured SARIF output. | | [`/experimental:module`](experimental-module.md) | Enables experimental module support. | -| [`/experimental:preprocessor`](experimental-preprocessor.md) | Deprecated. Enables experimental conforming preprocessor support. Use [`/Zc:preprocessor`](zc-preprocessor.md) | ## Deprecated and removed compiler options @@ -223,6 +313,7 @@ Experimental options may only be supported by certain versions of the compiler. |--|--| | [`/clr:noAssembly`](clr-common-language-runtime-compilation.md) | Deprecated. Use [`/LN` (Create MSIL Module)](ln-create-msil-module.md) instead. | | [`/errorReport`](errorreport-report-internal-compiler-errors.md) | Deprecated. Error reporting is controlled by [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings. | +| [`/experimental:preprocessor`](experimental-preprocessor.md) | Deprecated. Enables experimental conforming preprocessor support. Use [`/Zc:preprocessor`](zc-preprocessor.md) | | [`/Fr`](fr-fr-create-dot-sbr-file.md) | Deprecated. Creates a browse information file without local variables. | | [`/Ge`](ge-enable-stack-probes.md) | Deprecated. Activates stack probes. On by default. | | [`/Gm`](gm-enable-minimal-rebuild.md) | Deprecated. Enables minimal rebuild. | @@ -238,6 +329,9 @@ Experimental options may only be supported by certain versions of the compiler. | [`/Ze`](za-ze-disable-language-extensions.md) | Deprecated. Enables language extensions. | | [`/Zg`](zg-generate-function-prototypes.md) | Removed in Visual Studio 2015. Generates function prototypes. | +17.10 This option is available starting in Visual Studio 2022 version 17.10.\ +17.14 This option is available starting in Visual Studio 2022 version 17.14. + ## See also [C/C++ building reference](c-cpp-building-reference.md)\ diff --git a/docs/build/reference/compiling-a-c-cpp-program.md b/docs/build/reference/compiling-a-c-cpp-program.md index 5bb1e6e938..04b7733c86 100644 --- a/docs/build/reference/compiling-a-c-cpp-program.md +++ b/docs/build/reference/compiling-a-c-cpp-program.md @@ -11,7 +11,7 @@ C and C++ compiler options can be set either in the Visual Studio IDE or on the ## In Visual Studio -You can set compiler options for each project in its Visual Studio **Property Pages** dialog box. In the left pane, select **Configuration Properties**, **C/C++** and then choose the compiler option category. The topic for each compiler option describes how it can be set and where it is found in the development environment. See [MSVC Compiler Options](compiler-options.md) for a complete list. +You can set compiler options for each project in its Visual Studio **Property Pages** dialog box. In the left pane, select **Configuration Properties**, **C/C++** and then choose the compiler option category. The topic for each compiler option describes how it can be set and where it is found in the development environment. For more information and a complete list of options, see [MSVC compiler options](compiler-options.md). ## From the command line diff --git a/docs/build/reference/constexpr-control-constexpr-evaluation.md b/docs/build/reference/constexpr-control-constexpr-evaluation.md index 6bee6fa00a..9052345e64 100644 --- a/docs/build/reference/constexpr-control-constexpr-evaluation.md +++ b/docs/build/reference/constexpr-control-constexpr-evaluation.md @@ -1,45 +1,42 @@ --- description: "Learn more about: /constexpr (Control constexpr evaluation)" title: "/constexpr (Control constexpr evaluation)" -ms.date: "08/15/2017" +ms.date: 04/14/2025 f1_keywords: ["/constexpr", "-constexpr"] helpviewer_keywords: ["/constexpr control constexpr evaluation [C++]", "-constexpr control constexpr evaluation [C++]", "constexpr control constexpr evaluation [C++]"] -ms.assetid: 76d56784-f5ad-401d-841d-09d1059e8b8c --- # /constexpr (Control constexpr evaluation) -Use the **/constexpr** compiler options to control parameters for **`constexpr`** evaluation at compile time. +Use the **`/constexpr`** compiler options to control parameters for **`constexpr`** evaluation at compile time. ## Syntax -> **/constexpr:depth**N\ -> **/constexpr:backtrace**N\ -> **/constexpr:steps**N +> `/constexpr:depth`N\ +> `/constexpr:backtrace`N\ +> `/constexpr:steps`N ## Arguments -**depth**N +**`depth`**N\ Limit the depth of recursive **`constexpr`** function invocation to *N* levels. The default is 512. -**backtrace**N +**`backtrace`**N\ Show up to *N* **`constexpr`** evaluations in diagnostics. The default is 10. -**steps**N -Terminate **`constexpr`** evaluation after *N* steps. The default is 100,000. +**`steps`**N\ +Terminate **`constexpr`** evaluation after *N* steps. The default is 100,000. A step refers to an individual computation taken towards evaluating the constant expression. Increasing the maximum number of steps might cause compilation to take longer in cases where compilation would otherwise fail. ## Remarks -The **/constexpr** compiler options control compile-time evaluation of **`constexpr`** expressions. Evaluation steps, recursion levels, and backtrace depth are controlled to prevent the compiler from spending too much time on **`constexpr`** evaluation. For more information on the **`constexpr`** language element, see [constexpr (C++)](../../cpp/constexpr-cpp.md). +The **`/constexpr`** compiler options control compile-time evaluation of **`constexpr`** expressions. Evaluation steps, recursion levels, and backtrace depth are controlled to prevent the compiler from spending too much time on **`constexpr`** evaluation. For more information on the **`constexpr`** language element, see [`constexpr` (C++)](../../cpp/constexpr-cpp.md). -The **/constexpr** options are available beginning in Visual Studio 2015. +The **`/constexpr`** flag is available beginning in Visual Studio 2015. ### To set this compiler option in the Visual Studio development environment 1. Open your project's **Property Pages** dialog box. - 1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. - -1. Enter any **/constexpr** compiler options in the **Additional Options** box. Choose **OK** or **Apply** to save your changes. +1. Enter **/constexpr** compiler options in the **Additional Options** box. Choose **OK** to save your changes. ### To set this compiler option programmatically @@ -47,5 +44,5 @@ The **/constexpr** options are available beginning in Visual Studio 2015. ## See also -[MSVC Compiler Options](compiler-options.md)
+[MSVC Compiler Options](compiler-options.md)\ [MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/contents-of-a-makefile.md b/docs/build/reference/contents-of-a-makefile.md index c11e1c45a5..8883cd8cc7 100644 --- a/docs/build/reference/contents-of-a-makefile.md +++ b/docs/build/reference/contents-of-a-makefile.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Contents of a Makefile" -title: "Contents of a Makefile" -ms.date: "11/04/2016" -helpviewer_keywords: ["makefiles", "makefiles, contents"] -ms.assetid: 29362adb-d963-4c00-84a6-b38c2ffe6a36 +title: "NMAKE makefile contents and features" +description: "Learn more about: NMAKE makefile contents and features" +ms.date: 09/30/2021 +helpviewer_keywords: ["makefiles", "makefiles, contents", "NMAKE program, special characters", "makefiles, special characters", "special characters, in NMAKE macros", "macros, special characters", "NMAKE program, long filenames", "makefiles, comments", "NMAKE program, wildcards", "wildcards, expanding"] --- -# Contents of a Makefile +# NMAKE makefile contents and features A makefile contains: @@ -21,11 +20,65 @@ A makefile contains: - [Preprocessing directives](makefile-preprocessing.md) -## Remarks +For a sample, see [Sample makefile](sample-makefile.md). -Other features you can use in a makefile are [wildcards](wildcards-and-nmake.md), [long filenames](long-filenames-in-a-makefile.md), [comments](comments-in-a-makefile.md), and [special characters](special-characters-in-a-makefile.md). +NMAKE supports other features, such as wildcards, long filenames, comments, and escapes for special characters. -For a sample, see [Sample Makefile](sample-makefile.md). +## Wildcards and NMAKE + +NMAKE expands filename wildcards (**`*`** and **`?`**) in dependency lines. A wildcard specified in a command is passed to the command; NMAKE doesn't expand it. + +## Long filenames in a makefile + +Enclose long filenames in double quotation marks, as follows: + +```makefile +all : "VeryLongFileName.exe" +``` + +## Comments in a makefile + +Precede a comment with a number sign (**`#`**). NMAKE ignores text from the number sign to the next newline character. + +Examples: + +```makefile +# Comment on line by itself +OPTIONS = /MAP # Comment on macro definition line + +all.exe : one.obj two.obj # Comment on dependency line + link one.obj two.obj +# Comment in commands block +# copy *.obj \objects # Command turned into comment + copy one.exe \release + +.obj.exe: # Comment on inference rule line + link $< + +my.exe : my.obj ; link my.obj # Err: cannot comment this +# Error: # must be the first character +.obj.exe: ; link $< # Error: cannot comment this +``` + +To specify a literal number sign, precede it with a caret (**`^`**), as follows: + +```makefile +DEF = ^#define #Macro for a C preprocessing directive +``` + +## Special characters in a makefile + +To use an NMAKE special character as a literal character, place a caret (**`^`**) in front of it as an escape. NMAKE ignores carets that precede other characters. The special characters are: + +`: ; # ( ) $ ^ \ { } ! @ —` + +A caret (**`^`**) within a quoted string is treated as a literal caret character. A caret at the end of a line inserts a literal newline character in a string or macro. + +In macros, a backslash (**`\`**) followed by a newline character is replaced by a space. + +In commands, a percent symbol (**`%`**) is a file specifier. To represent `%` literally in a command, specify a double percent sign (**`%%`**) in place of a single one. In other situations, NMAKE interprets a single `%` literally, but it always interprets a double `%%` as a single `%`. Therefore, to represent a literal `%%`, specify either three percent signs, `%%%`, or four percent signs, `%%%%`. + +To use the dollar sign (**`$`**) as a literal character in a command, specify two dollar signs (**`$$`**). This method can also be used in other situations where `^$` works. ## See also diff --git a/docs/build/reference/creating-a-makefile-project.md b/docs/build/reference/creating-a-makefile-project.md index eb2bcf1242..1f88156dfd 100644 --- a/docs/build/reference/creating-a-makefile-project.md +++ b/docs/build/reference/creating-a-makefile-project.md @@ -1,23 +1,22 @@ --- -description: "Learn more about: Create a C++ makefile project" title: "Create a C++ makefile project in Visual Studio" -ms.date: "08/05/2019" +description: "Learn more about: Create a makefile project" +ms.date: 09/30/2021 f1_keywords: ["vc.appwiz.makefile.project"] helpviewer_keywords: ["Makefile projects [C++]"] -ms.assetid: dd077af3-97a8-48fb-baaa-cf7e07ddef61 --- # Create a C++ makefile project -A *makefile* is a text file that contains instructions for how to compile and link (or *build*) a set of C++ source code files. A *make* program reads the makefile and invokes a compiler, linker and possibly other programs to make an executable file. Microsoft's implementation of the *make* program is called [NMAKE](nmake-reference.md). +A *makefile* is a text file that contains instructions for how to compile and link (or *build*) a set of source code files. A program (often called a *make* program) reads the makefile and invokes a compiler, linker, and possibly other programs to make an executable file. The Microsoft program is called [NMAKE](nmake-reference.md). -If you have an existing makefile project, you have these choices if you want to code and/or debug it in the Visual Studio IDE: +If you have an existing makefile project, you have these choices if you want to edit, build, and debug in the Visual Studio IDE: -- Create a makefile project in Visual Studio that uses your existing makefile to configure a .vcxproj file that Visual Studio will use for IntelliSense. (You will not have all the IDE features that you get with a native MSBuild project.) See [To create a makefile project](#create_a_makefile_project) below. -- Use the **Create New Project from Existing Code Files** wizard to create a native MSBuild project from your source code. The original makefile will not be used after this. For more information, see [How to: Create a C++ Project from Existing Code](../how-to-create-a-cpp-project-from-existing-code.md). +- Create a makefile project in Visual Studio that uses your existing makefile to configure a .vcxproj file that Visual Studio will use for IntelliSense. (You won't have all the IDE features that you get with a native MSBuild project.) See [To create a makefile project](#create_a_makefile_project) below. +- Use the **Create New Project from Existing Code Files** wizard to create a native MSBuild project from your source code. The original makefile won't be used anymore. For more information, see [How to: Create a C++ Project from Existing Code](../how-to-create-a-cpp-project-from-existing-code.md). - **Visual Studio 2017 and later**: Use the **Open Folder** feature to edit and build a makefile project as-is without any involvement of the MSBuild system. For more information, see [Open Folder projects for C++](../open-folder-projects-cpp.md). - **Visual Studio 2019 and later**: Create a UNIX makefile project for Linux. -## To create a makefile project with the makefile project template +## To create a makefile project with the makefile project template In Visual Studio 2017 and later, the Makefile project template is available when the C++ Desktop Development workload is installed. @@ -25,17 +24,17 @@ Follow the wizard to specify the commands and environment used by your makefile. By default, the makefile project displays no files in Solution Explorer. The makefile project specifies the build settings, which are reflected in the project's property page. -The output file that you specify in the project has no effect on the name that the build script generates; it declares only an intention. Your makefile still controls the build process and specifies the build targets. +The output file that you specify in the project has no effect on the name that the build script generates. It declares only an intention. Your makefile still controls the build process and specifies the build targets. -::: moniker range="msvc-160" +::: moniker range=">=msvc-160" -### To create a makefile project in Visual Studio 2019 +### To create a makefile project in Visual Studio -1. From the Visual Studio main menu, choose **File** > **New** > **Project** and type "makefile" into the search box. Or, in the **New Project** dialog box, expand **Visual C++** > **General** (Visual Studio 2015) or **Other** (Visual Studio 2017) and then select from the two options depending on whether you will be targeting Windows or Linux. +1. From the Visual Studio main menu, choose **File** > **New** > **Project** and type "makefile" into the search box. If you see more than one project template, select from the options depending on your target platform. -1. **Windows only**: In the **Debug Configuration Settings** page, provide the command, output, clean, and rebuild information for debug and retail builds. Click **Next** if you want to specify different settings for a Release configuration. +1. **Windows only**: In the Makefile project **Debug Configuration Settings** page, provide the command, output, clean, and rebuild information for debug and retail builds. Choose **Next** if you want to specify different settings for a Release configuration. -1. Click **Finish** to close the dialog and open the newly created project in **Solution Explorer**. +1. Choose **Finish** to close the dialog and open the newly created project in **Solution Explorer**. ::: moniker-end @@ -47,11 +46,11 @@ The output file that you specify in the project has no effect on the name that t 1. In the **Application Settings** page, provide the command, output, clean, and rebuild information for debug and retail builds. -1. Click **Finish** to close the wizard and open the newly created project in **Solution Explorer**. +1. Choose **Finish** to close the wizard and open the newly created project in **Solution Explorer**. ::: moniker-end -You can view and edit the project's properties in its property page. See [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md) for information about displaying the property page. +You can view and edit the project's properties in its property page. For more information about displaying the property page, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). ## Makefile project wizard @@ -69,25 +68,25 @@ After you create a makefile project, you can view and edit each of the following IntelliSense fails in makefile projects when certain project settings or compiler options are set up incorrectly. Follow these steps to configure makefile projects so that IntelliSense works as expected: -1. Open the **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the **Property Pages** dialog box. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **NMake** property page. 1. Modify properties under **IntelliSense** as appropriate: - - Set the **Preprocessor Definitions** property to define any preprocessor symbols in your makefile project. See [/D (Preprocessor Definitions)](d-preprocessor-definitions.md), for more information. + - Set the **Preprocessor Definitions** property to define any preprocessor symbols in your makefile project. For more information, see [`/D` (Preprocessor Definitions)](d-preprocessor-definitions.md). - - Set the **Include Search Path** property to specify the list of directories that the compiler will search to resolve file references that are passed to preprocessor directives in your makefile project. See [/I (Additional Include Directories)](i-additional-include-directories.md), for more information. + - Set the **Include Search Path** property to specify the list of directories that the compiler will search to resolve file references that are passed to preprocessor directives in your makefile project. For more information, see [`/I` (Additional Include Directories)](i-additional-include-directories.md). - For projects that are built using CL.EXE from a Command Window, set the **INCLUDE** environment variable to specify directories that the compiler will search to resolve file references that are passed to preprocessor directives in your makefile project. - - Set the **Forced Includes** property to specify which header files to process when building your makefile project. See [/FI (Name Forced Include File)](fi-name-forced-include-file.md), for more information. + - Set the **Forced Includes** property to specify which header files to process when building your makefile project. For more information, see [`/FI` (Name Forced Include File)](fi-name-forced-include-file.md). - - Set the **Assembly Search Path** property to specify the list of directories that the compiler will search to resolve references to .NET assemblies in your project. See [/AI (Specify Metadata Directories)](ai-specify-metadata-directories.md), for more information. + - Set the **Assembly Search Path** property to specify the list of directories that the compiler will search to resolve references to .NET assemblies in your project. For more information, see [`/AI` (Specify Metadata Directories)](ai-specify-metadata-directories.md). - - Set the **Forced Using Assemblies** property to specify which .NET assemblies to process when building your makefile project. See [/FU (Name Forced #using File)](fu-name-forced-hash-using-file.md), for more information. + - Set the **Forced Using Assemblies** property to specify which .NET assemblies to process when building your makefile project. For more information, see [`/FU` (Name Forced #using File)](fu-name-forced-hash-using-file.md). - - Set the **Additional Options** property to specify additional compiler switches to be used by IntelliSense when parsing C++ files. + - Set the **Additional Options** property to specify other compiler switches to be used by IntelliSense when parsing C++ files. 1. Choose **OK** to close the property pages. @@ -97,8 +96,8 @@ The next time you open your makefile project in the Visual Studio development en ## See also -[Using IntelliSense](/visualstudio/ide/using-intellisense)
-[NMAKE Reference](nmake-reference.md)
-[How to: Create a C++ Project from Existing Code](../how-to-create-a-cpp-project-from-existing-code.md)
-[Special Characters in a Makefile](special-characters-in-a-makefile.md)
-[Contents of a Makefile](contents-of-a-makefile.md)
+[Using IntelliSense](/visualstudio/ide/using-intellisense)\ +[NMAKE Reference](nmake-reference.md)\ +[How to: Create a C++ project from existing code](../how-to-create-a-cpp-project-from-existing-code.md)\ +[Special characters in a makefile](contents-of-a-makefile.md#special-characters-in-a-makefile)\ +[Makefile contents and features](contents-of-a-makefile.md) diff --git a/docs/build/reference/creating-an-dot-sbr-file.md b/docs/build/reference/creating-an-dot-sbr-file.md index 47312c2da9..37096da3b1 100644 --- a/docs/build/reference/creating-an-dot-sbr-file.md +++ b/docs/build/reference/creating-an-dot-sbr-file.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Creating an .Sbr File" title: "Creating an .Sbr File" +description: "Learn more about: Creating an .Sbr File" ms.date: "11/04/2016" helpviewer_keywords: ["SBR files", "BSCMAKE, input files", ".sbr files", "source browser files", "local symbols in browse information", "symbols"] -ms.assetid: bdb4b93c-a88a-441a-84fd-01087d03be25 --- # Creating an .Sbr File @@ -14,7 +13,7 @@ The input files for BSCMAKE are .sbr files. The compiler creates an .sbr file fo To create an .sbr file with all possible information, specify [/FR](fr-fr-create-dot-sbr-file.md). -To create an .sbr file that doesn't contain local symbols, specify [/Fr](fr-fr-create-dot-sbr-file.md). If the .sbr files contain local symbols, you can still omit them from the .bsc file by using BSCMAKE's [/El option](bscmake-options.md)`.` +To create an .sbr file that doesn't contain local symbols, specify [/Fr](fr-fr-create-dot-sbr-file.md). If the .sbr files contain local symbols, you can still omit them from the .bsc file by using BSCMAKE's [/El option](bscmake-options.md). You can create an .sbr file without performing a full compile. For example, you can specify the /Zs option to the compiler to perform a syntax check and still generate an .sbr file if you specify /FR or /Fr. diff --git a/docs/build/reference/creating-inline-file-text.md b/docs/build/reference/creating-inline-file-text.md deleted file mode 100644 index 4454728539..0000000000 --- a/docs/build/reference/creating-inline-file-text.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -description: "Learn more about: Creating Inline File Text" -title: "Creating Inline File Text" -ms.date: "11/04/2016" -helpviewer_keywords: ["inline files, creating text", "NMAKE program, inline files", "text, inline file"] -ms.assetid: b8a332ed-8244-4ff8-89e6-029d7f659725 ---- -# Creating Inline File Text - -Inline files are temporary or permanent. - -## Syntax - -``` -inlinetext -. -. -. -<<[KEEP | NOKEEP] -``` - -## Remarks - -Specify *inlinetext* on the first line after the command. Mark the end with double angle brackets (<<) at the beginning of a separate line. The file contains all *inlinetext* before the delimiting brackets. The *inlinetext* can have macro expansions and substitutions, but not directives or makefile comments. Spaces, tabs, and newline characters are treated literally. - -A temporary file exists for the duration of the session and can be reused by other commands. Specify **KEEP** after the closing angle brackets to retain the file after the NMAKE session; an unnamed file is preserved on disk with the generated filename. Specify **NOKEEP** or nothing for a temporary file. **KEEP** and **NOKEEP** are not case sensitive. - -## See also - -[Inline Files in a Makefile](inline-files-in-a-makefile.md) diff --git a/docs/build/reference/debug-generate-debug-info.md b/docs/build/reference/debug-generate-debug-info.md old mode 100755 new mode 100644 index 7bc0fcc21b..85a515deba --- a/docs/build/reference/debug-generate-debug-info.md +++ b/docs/build/reference/debug-generate-debug-info.md @@ -1,52 +1,52 @@ --- -description: "Learn more about: /DEBUG (Generate Debug Info)" +description: "Learn more about: /DEBUG (Generate debug info)" title: "/DEBUG (Generate Debug Info)" -ms.date: "05/16/2019" +ms.date: 10/26/2023 f1_keywords: ["VC.Project.VCLinkerTool.GenerateDebugInformation", "/debug"] helpviewer_keywords: ["DEBUG linker option", "/DEBUG linker option", "-DEBUG linker option", "PDB files", "debugging [C++], debug information files", "generate debug info linker option", "pdb files, generating debug info", ".pdb files, generating debug info", "debugging [C++], linker option", "program databases [C++]"] ms.assetid: 1af389ae-3f8b-4d76-a087-1cdf861e9103 --- -# /DEBUG (Generate Debug Info) +# `/DEBUG` (Generate debug info) -``` -/DEBUG[:{FASTLINK|FULL|NONE}] -``` +The **`/DEBUG`** linker option creates a debugging information file for the executable. + +## Syntax + +> **`/DEBUG`**\[**`:`**{**`FASTLINK`**|**`FULL`**|**`NONE`**}] ## Remarks -The **/DEBUG** option creates debugging information for the executable. +The **`/DEBUG`** option puts the debugging information from linked object and library files into a program database (PDB) file. It updates the PDB during subsequent builds of the program. -The linker puts the debugging information into a program database (PDB) file. It updates the PDB during subsequent builds of the program. +An executable (an EXE or DLL file) created for debugging contains the name and path of the corresponding PDB. The debugger reads the embedded name and uses the PDB when you debug the program. The linker uses the base name of the program and the extension *`.pdb`* to name the program database, and embeds the path where it was created. To override this default, set the [`/PDB`](pdb-use-program-database.md) option and specify a different file name. -An executable (.exe file or DLL) created for debugging contains the name and path of the corresponding PDB. The debugger reads the embedded name and uses the PDB when you debug the program. The linker uses the base name of the program and the extension .pdb to name the program database, and embeds the path where it was created. To override this default, set [/PDB](pdb-use-program-database.md) and specify a different file name. +The **`/DEBUG:FASTLINK`** option is available in Visual Studio 2017 and later. This option generates a limited PDB that indexes into the debug information in the object files and libraries used to build the executable instead of making a full copy. You can only use this limited PDB to debug from the computer where the binary and its libraries were built. If you deploy the binary elsewhere, you may debug it remotely from the build computer, but not directly on the test computer. Since Visual Studio 2019, **`/DEBUG:FULL`** linking times have improved significantly, and **`/DEBUG:FASTLINK`** isn't always faster than **`/DEBUG:FULL`**. Since **`/DEBUG:FASTLINK`** no longer provides large build time improvements and results in a slower debugging experience versus **`/DEBUG:FULL`**, this option is no longer recommended. -The **/DEBUG:FASTLINK** option is available in Visual Studio 2017 and later. This option leaves private symbol information in the individual compilation products used to build the executable. It generates a limited PDB that indexes into the debug information in the object files and libraries used to build the executable instead of making a full copy. This option can link from two to four times as fast as full PDB generation, and is recommended when you are debugging locally and have the build products available. This limited PDB can't be used for debugging when the required build products are not available, such as when the executable is deployed on another computer. In a developer command prompt, you can use the mspdbcmf.exe tool to generate a full PDB from this limited PDB. In Visual Studio, use the Project or Build menu items for generating a full PDB file to create a full PDB for the project or solution. +A **`/DEBUG:FASTLINK`** PDB can be converted to a full PDB that you can deploy to a test machine for local debugging. In Visual Studio, use the **Property Pages** dialog as described below to create a full PDB for the project or solution. In a developer command prompt, you can use the `mspdbcmf.exe` tool to create a full PDB. -The **/DEBUG:FULL** option moves all private symbol information from individual compilation products (object files and libraries) into a single PDB, and can be the most time-consuming part of the link. However, the full PDB can be used to debug the executable when no other build products are available, such as when the executable is deployed. +The **`/DEBUG:FULL`** option moves all private symbol information from individual compilation products (object files and libraries) into a single PDB, and can be the most time-consuming part of the link. However, the full PDB can be used to debug the executable when no other build products are available, such as when the executable is deployed. -The **/DEBUG:NONE** option does not generate a PDB. +The **`/DEBUG:NONE`** option doesn't generate a PDB. -When you specify **/DEBUG** with no additional options, the linker defaults to **/DEBUG:FULL** for command line and makefile builds, for release builds in the Visual Studio IDE, and for both debug and release builds in Visual Studio 2015 and earlier versions. Beginning in Visual Studio 2017, the build system in the IDE defaults to **/DEBUG:FASTLINK** when you specify the **/DEBUG** option for debug builds. Other defaults are unchanged to maintain backward compatibility. +Specifying **`/DEBUG`** with no extra arguments is equivalent to specifying **`/DEBUG:FULL`**. -The compiler's [C7 Compatible](z7-zi-zi-debug-information-format.md) (/Z7) option causes the compiler to leave the debugging information in the .obj files. You can also use the [Program Database](z7-zi-zi-debug-information-format.md) (/Zi) compiler option to store the debugging information in a PDB for the .obj file. The linker looks for the object's PDB first in the absolute path written in the .obj file, and then in the directory that contains the .obj file. You cannot specify an object's PDB file name or location to the linker. +The compiler's [`/Z7`](z7-zi-zi-debug-information-format.md) (C7 Compatible) option causes the compiler to leave the debugging information in the object (OBJ) files. You can also use the [`/Zi`](z7-zi-zi-debug-information-format.md) (Program Database) compiler option to store the debugging information in a PDB for the OBJ file. The linker looks for the object's PDB first in the absolute path written in the OBJ file, and then in the directory that contains the OBJ file. You can't specify an object's PDB file name or location to the linker. -[/INCREMENTAL](incremental-link-incrementally.md) is implied when /DEBUG is specified. +[`/INCREMENTAL`](incremental-link-incrementally.md) is implied when **`/DEBUG`** is specified. -/DEBUG changes the defaults for the [/OPT](opt-optimizations.md) option from REF to NOREF and from ICF to NOICF, so if you want the original defaults, you must explicitly specify /OPT:REF or /OPT:ICF. +**`/DEBUG`** changes the defaults for the [`/OPT`](opt-optimizations.md) option from **`REF`** to **`NOREF`** and from **`ICF`** to **`NOICF`**, so if you want the original defaults, you must explicitly specify **`/OPT:REF`** or **`/OPT:ICF`** after the **`/DEBUG`** option. -It is not possible to create an .exe or .dll that contains debug information. Debug information is always placed in a .obj or .pdb file. +It isn't possible to create an EXE or DLL that contains debug information. Debug information is always placed in an OBJ or PDB file. ### To set this linker option in the Visual Studio development environment 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. Click the **Linker** folder. - -1. Click the **Debugging** property page. +1. Select the **Linker** > **Debugging** property page. -1. Modify the **Generate Debug Info** property to enable PDB generation. This enables /DEBUG:FASTLINK by default in Visual Studio 2017 and later. +1. Modify the **Generate Debug Info** property to enable or disable PDB generation. This property enables **`/DEBUG:FASTLINK`** by default in Visual Studio 2017 and later. -1. Modify the **Generate Full Program Database File** property to enable /DEBUG:FULL for full PDB generation for every incremental build. +1. Modify the **Generate Full Program Database File** property to enable **`/DEBUG:FULL`** for full PDB generation for every incremental build. ### To set this linker option programmatically @@ -54,5 +54,5 @@ It is not possible to create an .exe or .dll that contains debug information. De ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/decorated-names.md b/docs/build/reference/decorated-names.md index 70a2e2d05d..6370302c0d 100644 --- a/docs/build/reference/decorated-names.md +++ b/docs/build/reference/decorated-names.md @@ -1,22 +1,22 @@ --- -description: "Learn more about: Decorated Names" -title: "Decorated Names" -ms.date: "09/05/2018" +description: "Learn more about: Decorated names" +title: "Decorated names" +ms.date: 06/08/2022 helpviewer_keywords: ["decorated names, definition", "name decoration [C++]", "names [C++], decorated"] ms.assetid: a4e9ae8e-b239-4454-b401-4102793cb344 --- -# Decorated Names +# Decorated names Functions, data, and objects in C and C++ programs are represented internally by their decorated names. A *decorated name* is an encoded string created by the compiler during compilation of an object, data, or function definition. It records calling conventions, types, function parameters and other information together with the name. This name decoration, also known as *name mangling*, helps the linker find the correct functions and objects when linking an executable. The decorated naming conventions have changed in various versions of Visual Studio, and can also be different on different target architectures. To link correctly with source files created by using Visual Studio, C and C++ DLLs and libraries should be compiled by using the same compiler toolset, flags, and target architecture. > [!NOTE] -> Libraries built with Visual Studio 2015 can be consumed by applications built with Visual Studio 2017 or Visual Studio 2019. +> Libraries built by Visual Studio 2015 or later can be consumed by applications built with later versions of Visual Studio through Visual Studio 2022. For more information, see [C++ binary compatibility between Visual Studio versions](../../porting/binary-compat-2015-2017.md). ## Using decorated names -Normally, you don't have to know the decorated name to write code that compiles and links successfully. Decorated names are an implementation detail internal to the compiler and linker. The tools can usually handle the name in its undecorated form. However, a decorated name is sometimes required when you specify a function name to the linker and other tools. For example, to match overloaded C++ functions, members of namespaces, class constructors, destructors and special member functions, you must specify the decorated name. For details about the option flags and other situations that require decorated names, see the documentation for the tools and options that you are using. +Normally, you don't have to know the decorated name to write code that compiles and links successfully. Decorated names are an implementation detail internal to the compiler and linker. The tools can usually handle the name in its undecorated form. However, a decorated name is sometimes required when you specify a function name to the linker and other tools. For example, to match overloaded C++ functions, members of namespaces, class constructors, destructors and special member functions, you must specify the decorated name. For details about the option flags and other situations that require decorated names, see the documentation for the tools and options that you're using. If you change the function name, class, calling convention, return type, or any parameter, the decorated name also changes. In this case, you must get the new decorated name and use it everywhere the decorated name is specified. @@ -28,9 +28,9 @@ A decorated name for a C++ function contains the following information: - The function name. -- The class that the function is a member of, if it is a member function. This may include the class that encloses the class that contains the function, and so on. +- The class that the function is a member of, if it's a member function. The decoration may include the class that encloses the class that contains the function, and so on. -- The namespace the function belongs to, if it is part of a namespace. +- The namespace the function belongs to, if it's part of a namespace. - The types of the function parameters. @@ -38,47 +38,51 @@ A decorated name for a C++ function contains the following information: - The return type of the function. +- An optional target-specific element. In ARM64EC objects, a **`$$h`** tag is inserted into the name. + The function and class names are encoded in the decorated name. The rest of the decorated name is a code that has internal meaning only for the compiler and the linker. The following are examples of undecorated and decorated C++ names. -|Undecorated name|Decorated name| -|----------------------|--------------------| -|`int a(char){int i=3;return i;};`|`?a@@YAHD@Z`| -|`void __stdcall b::c(float){};`|`?c@b@@AAGXM@Z`| +| Undecorated name | Decorated name | +|--|--| +| `int a(char){int i=3;return i;};` | `?a@@YAHD@Z` | +| `void __stdcall b::c(float){};` | `?c@b@@AAGXM@Z` | ## Format of a C decorated name -The form of decoration for a C function depends on the calling convention used in its declaration, as shown in the following table. This is also the decoration format that is used when C++ code is declared to have `extern "C"` linkage. The default calling convention is **`__cdecl`**. Note that in a 64-bit environment, functions are not decorated. +The form of decoration for a C function depends on the calling convention used in its declaration, as shown in the following table. It's also the decoration format that's used when C++ code is declared to have `extern "C"` linkage. The default calling convention is **`__cdecl`**. In a 64-bit environment, C or `extern "C"` functions are only decorated when using the `__vectorcall` calling convention. + +| Calling convention | Decoration | +|--|--| +| **`__cdecl`** | Leading underscore (**`_`**) | +| **`__stdcall`** | Leading underscore (**`_`**) and a trailing at sign (**`@`**) followed by the number of bytes in the parameter list in decimal | +| **`__fastcall`** | Leading and trailing at signs (**`@`**) followed by a decimal number representing the number of bytes in the parameter list | +| **`__vectorcall`** | Two trailing at signs (**`@@`**) followed by a decimal number of bytes in the parameter list | -|Calling convention|Decoration| -|------------------------|----------------| -|**`__cdecl`**|Leading underscore (**`_`**)| -|**`__stdcall`**|Leading underscore (**`_`**) and a trailing at sign (**`@`**) followed by the number of bytes in the parameter list in decimal| -|**`__fastcall`**|Leading and trailing at signs (**`@`**) followed by a decimal number representing the number of bytes in the parameter list| -|**`__vectorcall`**|Two trailing at signs (**`@@`**) followed by a decimal number of bytes in the parameter list| +For ARM64EC functions with C linkage (whether compiled as C or by using `extern "C"`), a **`#`** is prepended to the decorated name. -## Viewing decorated names +## View decorated names You can get the decorated form of a symbol name after you compile the source file that contains the data, object, or function definition or prototype. To examine decorated names in your program, you can use one of the following methods: -#### To use a listing to view decorated names +### To use a listing to view decorated names -1. Generate a listing by compiling the source file that contains the data, object, or function definition or prototype with the [Listing File Type](fa-fa-listing-file.md) compiler option set to Assembly with Source Code (**/FAs**). +1. Generate a listing by compiling the source file that contains the data, object, or function definition or prototype with the [`/FA` (Listing file type)](fa-fa-listing-file.md) compiler option set to assembly with source code (**`/FAs`**). - For example, enter `cl /c /FAs example.cpp` at a developer command prompt to generate a listing file, example.asm. + For example, enter `cl /c /FAs example.cpp` at a developer command prompt to generate a listing file, *`example.asm`*. -2. In the resulting listing file, find the line that starts with PUBLIC and ends a semicolon followed by the undecorated data or function name. The symbol between PUBLIC and the semicolon is the decorated name. +1. In the resulting listing file, find the line that starts with `PUBLIC` and ends a semicolon (**`;`**) followed by the undecorated data or function name. The symbol between `PUBLIC` and the semicolon is the decorated name. -#### To use DUMPBIN to view decorated names +### To use DUMPBIN to view decorated names -1. To see the exported symbols in an .obj or .lib file, enter `dumpbin /exports ` at a developer command prompt. +1. To see the exported symbols in an OBJ or LIB file, enter `dumpbin /exports ` at a developer command prompt. -2. To find the decorated form of a symbol, look for the undecorated name in parentheses. The decorated name is on the same line, before the undecorated name. +1. To find the decorated form of a symbol, look for the undecorated name in parentheses. The decorated name is on the same line, before the undecorated name. ## Viewing undecorated names You can use undname.exe to convert a decorated name to its undecorated form. This example shows how it works: -``` +```cmd C:\>undname ?func1@a@@AAEXH@Z Microsoft (R) C++ Name Undecorator Copyright (C) Microsoft Corporation. All rights reserved. @@ -89,5 +93,5 @@ is :- "private: void __thiscall a::func1(int)" ## See also -[Additional MSVC Build Tools](c-cpp-build-tools.md)
-[Using extern to Specify Linkage](../../cpp/extern-cpp.md) +[Additional MSVC build tools](c-cpp-build-tools.md)\ +[Using `extern` to specify linkage](../../cpp/extern-cpp.md) diff --git a/docs/build/reference/def-specify-module-definition-file.md b/docs/build/reference/def-specify-module-definition-file.md index ad5e6a38fa..42e938c3ff 100644 --- a/docs/build/reference/def-specify-module-definition-file.md +++ b/docs/build/reference/def-specify-module-definition-file.md @@ -1,37 +1,34 @@ --- -description: "Learn more about: /DEF (Specify Module-Definition File)" -title: "/DEF (Specify Module-Definition File)" -ms.date: "11/04/2016" +description: "Learn more about: /DEF (Specify module-definition file)" +title: "/DEF (Specify module-definition file)" +ms.date: 03/27/2025 f1_keywords: ["VC.Project.VCLinkerTool.ModuleDefinitionFile", "/def"] helpviewer_keywords: ["module definition files, specifying", "DEF linker option", "-DEF linker option", "module definition files", "/DEF linker option"] -ms.assetid: 6497fa68-65f0-48ca-8f66-b87166fc631a --- -# /DEF (Specify Module-Definition File) +# `/DEF` (Specify module-definition file) -``` -/DEF:filename -``` +Specifies a module-definition file to the linker. -## Arguments +## Syntax -*filename*
-The name of a module-definition file (.def) to be passed to the linker. +> **`/DEF:`***`filename`* -## Remarks +## Arguments -The /DEF option passes a module-definition file (.def) to the linker. Only one .def file can be specified to LINK. For details about .def files, see [Module-Definition Files](module-definition-dot-def-files.md). +*`filename`*\ +The name of a module-definition file (*`.def`*) to be passed to the linker. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). -### To set this linker option in the Visual Studio development environment - -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). +## Remarks -1. Click the **Linker** folder. +The **`/DEF`** linker option passes a module-definition file (*`.def`*) to the linker. Only one *`.def`* file can be specified to LINK. For details about *`.def`* files, see [Module-definition files](module-definition-dot-def-files.md). -1. Click the **Input** property page. +To specify a *`.def`* file from within the development environment, add it to the project along with your other source files and then specify the file in the project's **Property Pages** dialog. -1. Modify the **Module Definition File** property. +### To set this linker option in the Visual Studio development environment -To specify a .def file from within the development environment, you should add it to the project along with other files and then specify the file to the /DEF option. +1. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). +1. Select the **Configuration Properties** > **Linker** > **Input** property page. +1. Modify the **Module Definition File** property. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically @@ -39,5 +36,5 @@ To specify a .def file from within the development environment, you should add i ## See also -[MSVC linker reference](linking.md)
+[MSVC linker reference](linking.md)\ [MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/defining-a-rule.md b/docs/build/reference/defining-a-rule.md deleted file mode 100644 index d5e00bd129..0000000000 --- a/docs/build/reference/defining-a-rule.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -description: "Learn more about: Defining a Rule" -title: "Defining a Rule" -ms.date: "11/04/2016" -helpviewer_keywords: ["NMAKE program, inference rules", "defining inference rules"] -ms.assetid: 071cd092-3f2e-4065-b0fb-36a9d393cfa8 ---- -# Defining a Rule - -The *fromext* represents the extension of a dependent file, and *toext* represents the extension of a target file. - -``` -.fromext.toext: - commands -``` - -## Remarks - -Extensions are not case sensitive. Macros can be invoked to represent *fromext* and *toext*; the macros are expanded during preprocessing. The period (.) preceding *fromext* must appear at the beginning of the line. The colon (:) is preceded by zero or more spaces or tabs. It can be followed only by spaces or tabs, a semicolon (;) to specify a command, a number sign (#) to specify a comment, or a newline character. No other spaces are allowed. Commands are specified as in description blocks. - -## What do you want to know more about? - -[Search paths in rules](search-paths-in-rules.md) - -## See also - -[Inference Rules](inference-rules.md) diff --git a/docs/build/reference/defining-an-nmake-macro.md b/docs/build/reference/defining-an-nmake-macro.md index 3ae40f6e04..dd09538893 100644 --- a/docs/build/reference/defining-an-nmake-macro.md +++ b/docs/build/reference/defining-an-nmake-macro.md @@ -1,34 +1,63 @@ --- +title: "Define an NMAKE Macro" description: "Learn more about: Defining an NMAKE Macro" -title: "Defining an NMAKE Macro" -ms.date: "11/04/2016" -helpviewer_keywords: ["macros, NMAKE", "defining NMAKE macros", "NMAKE macros, defining"] -ms.assetid: 45aae451-9d33-4a3d-8799-2e0cae17070d +ms.date: 09/30/2021 +helpviewer_keywords: ["macros, NMAKE", "defining NMAKE macros", "NMAKE macros, defining", "defining macros", "NMAKE program, defining macros", "NMAKE program, undefined macros", "Null macros in NMAKE", "macros, null and undefined", "undefined macros and NMAKE", "NMAKE program, null macros", "special characters, in NMAKE macros"] --- -# Defining an NMAKE Macro +# Define an NMAKE macro -## Syntax +An NMAKE macro is defined by using this syntax: +```makefile +macro_name=string ``` -macroname=string +The *macro_name* is a case-sensitive combination of letters, digits, and underscores (**`_`**) up to 1,024 characters long. The *macro_name* can contain an invoked macro. If *macro_name* consists entirely of an invoked macro, the macro being invoked can't be null or undefined. + +The *string* can be any sequence of zero or more characters. A *null* string contains zero characters or only spaces or tabs. The *string* can contain a macro invocation. + +## Special characters in macros + +A number sign (**`#`**) after a definition specifies a comment. To specify a literal number sign in a macro, use a caret (**`^`**) to escape it, as in **`^#`**. + +A dollar sign (**`$`**) specifies a macro invocation. To specify a literal `$`, use **`$$`**. + +To extend a definition to a new line, end the line with a backslash (**`\`**). When the macro is invoked, the backslash and following newline character is replaced with a space. To specify a literal backslash at the end of the line, precede it with a caret (**`^`**) escape, or follow it with a comment specifier (**`#`**). + +To specify a literal newline character, end the line with a caret (**`^`**) escape, as in this example: + +```makefile +CMDS = cls^ +dir ``` -## Remarks +## Null and undefined macros + +Both null and undefined macros expand to null strings, but a macro defined as a null string is considered defined in preprocessing expressions. To define a macro as a null string, specify no characters except spaces or tabs after the equal sign (**`=`**) in a command line or command file, and enclose the null string or definition in double quotation marks (**`" "`**). To undefine a macro, use **`!UNDEF`**. For more information, see [Makefile preprocessing directives](makefile-preprocessing.md#makefile-preprocessing-directives). + +## Where to define macros + +Define macros in a command line, command file, makefile, or the *`Tools.ini`* file. + +In a makefile or the *`Tools.ini`* file, each macro definition must appear on a separate line and can't start with a space or tab. Spaces or tabs around the equal sign are ignored. All *string* characters are literal, including surrounding quotation marks and embedded spaces. + +In a command line or command file, spaces and tabs delimit arguments and can't surround the equal sign. If *string* has embedded spaces or tabs, enclose either the string itself or the entire macro in double quotation marks (**`" "`**). + +## Precedence in macro definitions -The *macroname* is a combination of letters, digits, and underscores (_) up to 1,024 characters, and is case sensitive. The *macroname* can contain an invoked macro. If *macroname* consists entirely of an invoked macro, the macro being invoked cannot be null or undefined. +If a macro has multiple definitions, NMAKE uses the highest-precedence definition. The following list shows the order of precedence, from highest to lowest: -The `string` can be any sequence of zero or more characters. A null string contains zero characters or only spaces or tabs. The `string` can contain a macro invocation. +1. A macro defined on the command line -## What do you want to know more about? +1. A macro defined in a makefile or include file -[Special characters in macros](special-characters-in-macros.md) +1. An inherited environment-variable macro -[Null and undefined macros](null-and-undefined-macros.md) +1. A macro defined in the *`Tools.ini`* file -[Where to define macros](where-to-define-macros.md) +1. A predefined macro, such as [`CC`](special-nmake-macros.md#command-macros-and-options-macros) and [`AS`](special-nmake-macros.md#command-macros-and-options-macros) -[Precedence in macro definitions](precedence-in-macro-definitions.md) +Use **`/E`** to cause macros inherited from environment variables to override makefile macros with the same name. Use **`!UNDEF`** to override a command line. ## See also diff --git a/docs/build/reference/delay-delay-load-import-settings.md b/docs/build/reference/delay-delay-load-import-settings.md index 07856d7724..a1054d65b8 100644 --- a/docs/build/reference/delay-delay-load-import-settings.md +++ b/docs/build/reference/delay-delay-load-import-settings.md @@ -1,8 +1,8 @@ --- description: "Learn more about: /DELAY (Delay load import settings)" title: "/DELAY (Delay load import settings)" -ms.date: 01/28/2021 -f1_keywords: ["/delay", "VC.Project.VCLinkerTool.DelayNoBind", "VC.Project.VCLinkerTool.SupportUnloadOfDelayLoadedDLL", "VC.Project.VCLinkerTool.DelayUnload"] +ms.date: 09/19/2022 +f1_keywords: ["/delay", "VC.Project.VCLinkerTool.DelayNoBind", "VC.Project.VCLinkerTool.SupportUnloadOfDelayLoadedDLL", "VC.Project.VCLinkerTool.DelayUnload", "VC.Project.VCLinkerTool.SupportNobindOfDelayLoadedDLL"] helpviewer_keywords: ["delayed loading of DLLs, /DELAY option", "DELAY linker option", "/DELAY linker option", "-DELAY linker option"] --- # `/DELAY` (Delay load import settings) @@ -32,15 +32,15 @@ To specify DLLs to delay load, use the [`/DELAYLOAD`](delayload-delay-load-impor ### To set this linker option in the Visual Studio development environment -1. Open the project's **Property Pages** dialog box. For information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the **Property Pages** dialog box for the project. For more information, see [Set compiler and build properties](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. -1. Modify the **Delay Loaded DLL** property. Choose **OK** to save your changes. +1. Modify the **Unload delay loaded DLL** property or the **Unbind delay loaded DLL** property. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically -- See . +- See . ## See also diff --git a/docs/build/reference/delimiters-for-visual-cpp-documentation-tags.md b/docs/build/reference/delimiters-for-visual-cpp-documentation-tags.md index 8b4c741c97..78d0cb2f1c 100644 --- a/docs/build/reference/delimiters-for-visual-cpp-documentation-tags.md +++ b/docs/build/reference/delimiters-for-visual-cpp-documentation-tags.md @@ -1,30 +1,30 @@ --- -description: "Learn more about: Delimiters for Visual C++ Documentation Tags" -title: "Delimiters for Visual C++ Documentation Tags" -ms.date: "11/04/2016" +description: "Learn more about: Delimiters for Visual C++ documentation tags" +title: "Delimiters for Visual C++ documentation tags" +ms.date: 12/03/2021 helpviewer_keywords: ["XML documentation, delimiters"] ms.assetid: debfbdd9-63fa-4c58-a18e-a4d203d241d7 --- -# Delimiters for Visual C++ Documentation Tags +# Delimiters for Visual C++ documentation tags -The use of documentation tags requires delimiters, which indicate to the compiler where a documentation comment begins and ends. +The use of documentation tags requires *delimiters*, which indicate to the compiler where a documentation comment begins and ends. You can use the following kinds of delimiters with the XML documentation tags: | Delimiter | Description | -|-|-| -| `///` | This is the form that is shown in documentation examples and used by the Visual Studio C++ project templates. | -| `/** */` | These are multiline delimiters. | +|--|--| +| `///` | This is the form that's shown in documentation examples and used by the Visual Studio C++ project templates. | +| `/** */` | These are multiline delimiters. | There are some formatting rules when using the `/** */` delimiters: -- For the line that contains the `/**` delimiter, if the remainder of the line is white space, the line is not processed for comments. If the first character is white space, that white space character is ignored and the rest of the line is processed. Otherwise, the entire text of the line after the `/**` delimiter is processed as part of the comment. +- For the line that contains the `/**` delimiter, if the rest of the line is whitespace, the line isn't processed for comments. If the first character is whitespace, that whitespace character is ignored and the rest of the line is processed. Otherwise, the entire text of the line after the `/**` delimiter is processed as part of the comment. -- For the line that contains the `*/` delimiter, if there is only white space up to the `*/` delimiter, that line is ignored. Otherwise, the text on the line up to the `*/` delimiter is processed as part of the comment, subject to the pattern-matching rules described in the following bullet. +- For the line that contains the `*/` delimiter, if there's only whitespace up to the `*/` delimiter, that line is ignored. Otherwise, the text on the line up to the `*/` delimiter is processed as part of the comment, subject to the pattern-matching rules described in the following bullet. -- For the lines after the one that begins with the `/**` delimiter, the compiler looks for a common pattern at the beginning of each line that consists of optional white space and an asterisk (`*`), followed by more optional white space. If the compiler finds a common set of characters at the beginning of each line, it will ignore that pattern for all lines after the `/**` delimiter, up to and possibly including the line that contains the `*/` delimiter. +- For the lines after the one that begins with the `/**` delimiter, the compiler looks for a common pattern at the beginning of each line that consists of optional white space and an asterisk (`*`), followed by more optional whitespace. If the compiler finds a common set of characters at the beginning of each line, it will ignore that pattern for all lines after the `/**` delimiter, up to and possibly including the line that contains the `*/` delimiter. -Some examples: +## Examples - The only part of the following comment that will be processed is the line that begins with ``. The following two tag formats will produce the same comments: @@ -43,7 +43,7 @@ Some examples: * text */ ``` -- The compiler finds no pattern in this comment because there is no asterisk on the second line. Therefore, all text on the second and third lines, up till the `*/`, will be processed as part of the comment. +- The compiler finds no pattern in this comment because there's no asterisk on the second line. All text on the second and third lines, up until the `*/`, will be processed as part of the comment. ```cpp /** @@ -51,7 +51,7 @@ Some examples: text */ ``` -- The compiler finds no pattern in this comment for two reasons. First, there is no line that begins with a consistent number of spaces before the asterisk. Second, the fifth line begins with a tab, which does not match spaces. Therefore, all text from the second line until the `*/` will be processed as part of the comment. +- The compiler finds no pattern in this comment for two reasons. First, there's no line that begins with a consistent number of spaces before the asterisk. Second, the fifth line begins with a tab, which doesn't match spaces. All text from the second line until the `*/` will be processed as part of the comment. ```cpp /** @@ -64,4 +64,4 @@ Some examples: ## See also -[XML Documentation](xml-documentation-visual-cpp.md) +[XML documentation](xml-documentation-visual-cpp.md) diff --git a/docs/build/reference/dependentloadflag.md b/docs/build/reference/dependentloadflag.md index 0f4401a29c..f44b4223a0 100644 --- a/docs/build/reference/dependentloadflag.md +++ b/docs/build/reference/dependentloadflag.md @@ -40,7 +40,7 @@ In both cases, if you specify the link option `/DEPENDENTLOADFLAG:0x800` (the va To see the value set by the **/DEPENDENTLOADFLAG** option in any DLL, use the [DUMPBIN](dumpbin-reference.md) command with the [/LOADCONFIG](loadconfig.md) option. -The **/DEPENDENTLOADFLAG** option is new in Visual Studio 2017. It applies only to apps running on Windows 10 RS1 and later versions. This option is ignored by other operating systems that run the app. +The **/DEPENDENTLOADFLAG** option is new in Visual Studio 2017. It applies only to apps running on Windows 10 RS1 and later Windows versions. This option is ignored by other operating systems that run the app. ### To set the DEPENDENTLOADFLAG linker option in the Visual Studio development environment diff --git a/docs/build/reference/description-blocks.md b/docs/build/reference/description-blocks.md index 869a829275..3f45702146 100644 --- a/docs/build/reference/description-blocks.md +++ b/docs/build/reference/description-blocks.md @@ -1,9 +1,8 @@ --- title: "Description blocks" description: "NMAKE uses description blocks to associate targets, dependencies, and commands in a makefile." -ms.date: "10/29/2019" +ms.date: 09/30/2021 helpviewer_keywords: ["description blocks", "NMAKE program, description blocks", "blocks, description"] -ms.assetid: 1321f228-d389-40ac-b0cd-4f6e9293602b --- # Description blocks @@ -157,7 +156,7 @@ In this example, UPDATE is a pseudotarget. ```makefile UPDATE : *.* -!COPY $** c:\product\release +COPY $** c:\product\release ``` When UPDATE is evaluated, NMAKE copies all files in the current directory to the specified drive and directory. diff --git a/docs/build/reference/directives.md b/docs/build/reference/directives.md index 6be5f21715..94c1814fb2 100644 --- a/docs/build/reference/directives.md +++ b/docs/build/reference/directives.md @@ -14,7 +14,7 @@ ms.assetid: cb85d679-6d20-4244-ba0b-6f495228e970 ## Remarks -This option dumps the compiler-generated .drective section of an image. +This option dumps the compiler-generated .drectve section of an image. Only the [/HEADERS](headers.md) DUMPBIN option is available for use on files produced with the [/GL](gl-whole-program-optimization.md) compiler option. diff --git a/docs/build/reference/dot-directives.md b/docs/build/reference/dot-directives.md index 2c12a5282a..951b71d2e0 100644 --- a/docs/build/reference/dot-directives.md +++ b/docs/build/reference/dot-directives.md @@ -1,34 +1,33 @@ --- description: "Learn more about: Dot Directives" -title: "Dot Directives" -ms.date: "11/04/2016" +title: "Dot directives" +ms.date: 09/30/2021 helpviewer_keywords: ["NMAKE program, dot directives", "dot directives in NMAKE"] -ms.assetid: ab35da65-30b6-48b7-87d6-61503d7faf9f --- -# Dot Directives +# Dot directives -Specify dot directives outside a description block, at the start of a line. Dot directives begin with a period ( . ) and are followed by a colon (:). Spaces and tabs are allowed. Dot directive names are case sensitive and are uppercase. +Specify dot directives outside a description block, at the start of a line. Dot directives begin with a period ( **`.`** ) and are followed by a colon (**`:`**). Spaces and tabs are allowed. Dot directive names are case-sensitive and must be uppercase. -|Directive|Purpose| -|---------------|-------------| -|**.IGNORE :**|Ignores nonzero exit codes returned by commands, from the place it is specified to the end of the makefile. By default, NMAKE halts if a command returns a nonzero exit code. To restore error checking, use **!CMDSWITCHES**. To ignore the exit code for a single command, use the dash (-) modifier. To ignore exit codes for an entire file, use /I.| -|**.PRECIOUS :** *targets*|Preserves *targets* on disk if the commands to update them are halted; has no effect if a command handles an interrupt by deleting the file. Separate the target names with one or more spaces or tabs. By default, NMAKE deletes a target if a build is interrupted by CTRL+C or CTRL+BREAK. Each use of **.PRECIOUS** applies to the entire makefile; multiple specifications are cumulative.| -|**.SILENT :**|Suppresses display of executed commands, from the place it is specified to the end of the makefile. By default, NMAKE displays the commands it invokes. To restore echoing, use **!CMDSWITCHES**. To suppress echoing of a single command, use the **@** modifier. To suppress echoing for an entire file, use /S.| -|**.SUFFIXES :** `list`|Lists extensions for inference-rule matching; predefined to include the following extensions: .exe .obj .asm .c .cpp .cxx .bas .cbl .for .pas .res .rc .f .f90| +| Directive | Purpose | +|--|--| +| **`.IGNORE :`** | Ignores nonzero exit codes returned by commands, from the place it is specified to the end of the makefile. By default, NMAKE halts if a command returns a nonzero exit code. To restore error checking, use **`!CMDSWITCHES`**. To ignore the exit code for a single command, use the dash (**`-`**) modifier. To ignore exit codes for an entire file, use **`/I`**. | +| **`.PRECIOUS :`** *targets* | Preserves *targets* on disk if the commands to update them are halted; has no effect if a command handles an interrupt by deleting the file. Separate the target names with one or more spaces or tabs. By default, NMAKE deletes a target if a build is interrupted by CTRL+C or CTRL+BREAK. Each use of **`.PRECIOUS`** applies to the entire makefile; multiple specifications are cumulative. | +| **`.SILENT`** | Suppresses display of executed commands, from the place it is specified to the end of the makefile. By default, NMAKE displays the commands it invokes. To restore echoing, use **`!CMDSWITCHES`**. To suppress echoing of a single command, use the **`@`** modifier. To suppress echoing for an entire file, use **`/S`**. | +| **`.SUFFIXES :`** *list* | Lists extensions for inference-rule matching; predefined to include the following extensions: `.exe .obj .asm .c .cpp .cxx .bas .cbl .for .pas .res .rc .f .f90` | -To change the **.SUFFIXES** list order or to specify a new list, clear the list and specify a new setting. To clear the list, specify no extensions after the colon: +To change the **`.SUFFIXES`** list order or to specify a new list, clear the list and specify a new setting. To clear the list, specify no extensions after the colon: -``` +```makefile .SUFFIXES : ``` To add additional suffixes to the end of the list, specify -``` -.SUFFIXES : suffixlist +```makefile +.SUFFIXES : suffix_list ``` -where *suffixlist* is a list of the additional suffixes, separated by one or more spaces or tabs. To see the current setting of **.SUFFIXES**, run NMAKE with /P. +where *suffix_list* is a list of the additional suffixes, separated by one or more spaces or tabs. To see the current setting of **`.SUFFIXES`**, run NMAKE with **`/P`**. ## See also diff --git a/docs/build/reference/dot-ilk-files-as-linker-input.md b/docs/build/reference/dot-ilk-files-as-linker-input.md index e53baf1be6..5e5e761ff8 100644 --- a/docs/build/reference/dot-ilk-files-as-linker-input.md +++ b/docs/build/reference/dot-ilk-files-as-linker-input.md @@ -1,15 +1,19 @@ --- -description: "Learn more about: .Ilk Files as Linker Input" -title: ".Ilk Files as Linker Input" -ms.date: "11/04/2016" -helpviewer_keywords: ["ILK files", ".ilk files"] +description: "Learn more about: .ilk files as linker input" +title: ".ilk files as linker input" +ms.date: 09/07/2022 +helpviewer_keywords: [".ilk files", ".ilk files"] ms.assetid: 7324c104-9e5d-423d-b268-b59f92607bf2 --- -# .Ilk Files as Linker Input +# `.ilk` files as linker input -When linking incrementally, LINK updates the .ilk status file that it created during the first incremental link. This file has the same base name as the .exe file or the .dll file, and it has the extension .ilk. During subsequent incremental links, LINK updates the .ilk file. If the .ilk file is missing, LINK performs a full link and creates a new .ilk file. If the .ilk file is unusable, LINK performs a nonincremental link. For details about incremental linking, see the [Link Incrementally (/INCREMENTAL)](incremental-link-incrementally.md) option. +The linker creates and uses a *`.ilk`* database file for incremental link information. + +## Remarks + +When linking incrementally, LINK updates the *`.ilk`* status file that it created during the first incremental link. This file has the same base name as the target EXE or DLL file, and it has the extension *`.ilk`*. During subsequent incremental links, LINK updates the *`.ilk`* file. If the *`.ilk`* file is missing, LINK performs a full link and creates a new *`.ilk`* file. If the *`.ilk`* file is unusable, LINK performs a non-incremental link. For more information about incremental linking, see the [`/INCREMENTAL` (Link incrementally)](incremental-link-incrementally.md) linker option. For information about how to specify the name and location of the file, see [`/ILK` (Name incremental database file)](./ilk-name-incremental-database-file.md). ## See also -[LINK Input Files](link-input-files.md)
-[MSVC Linker Options](linker-options.md) +[LINK input files](link-input-files.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/dot-lib-files-as-linker-input.md b/docs/build/reference/dot-lib-files-as-linker-input.md index dc12e4a0bb..875c8694c9 100644 --- a/docs/build/reference/dot-lib-files-as-linker-input.md +++ b/docs/build/reference/dot-lib-files-as-linker-input.md @@ -1,32 +1,36 @@ --- -description: "Learn more about: .Lib Files as Linker Input" -title: ".Lib Files as Linker Input" -ms.date: "11/04/2016" +description: "Learn more about: .lib files as linker input" +title: ".lib files as linker input" +ms.date: 09/09/2022 f1_keywords: ["VC.Project.VCLinkerTool.AdditionalDependencies"] helpviewer_keywords: ["OMF libraries", "linking [C++], OMF libraries", "import libraries, linker files", "libraries [C++], .lib files as linker input", "COFF files, import libraries", "default libraries [C++], linker output", "default libraries [C++]", "defaults [C++], libraries", ".lib files"] ms.assetid: dc5d2b1c-2487-41fa-aa71-ad1e0647958b --- -# .Lib Files as Linker Input +# `.lib` files as linker input -LINK accepts COFF standard libraries and COFF import libraries, both of which usually have the extension .lib. Standard libraries contain objects and are created by the LIB tool. Import libraries contain information about exports in other programs and are created either by LINK when it builds a program that contains exports or by the LIB tool. For information on using LIB to create standard or import libraries, see [LIB Reference](lib-reference.md). For details on using LINK to create an import library, see the [/DLL](dll-build-a-dll.md) option. +LINK accepts COFF standard libraries and COFF import libraries, both of which usually have the extension *`.lib`*. Standard libraries contain objects and are created by the LIB tool. Import libraries contain information about exports in other programs and are created either by LINK when it builds a program that contains exports or by the LIB tool. For information on using LIB to create standard or import libraries, see [LIB Reference](lib-reference.md). For details on using LINK to create an import library, see the [`/DLL`](dll-build-a-dll.md) option. -A library is specified to LINK as either a file name argument or a default library. LINK resolves external references by searching first in libraries specified on the command line, then in default libraries specified with the [/DEFAULTLIB](defaultlib-specify-default-library.md) option, and then in default libraries named in .obj files. If a path is specified with the library name, LINK looks for the library in that directory. If no path is specified, LINK looks first in the directory that LINK is running from, and then in any directories specified in the LIB environment variable. +A library is specified to LINK as either a file name argument or a default library. LINK resolves external references by searching first in libraries specified on the command line, then in default libraries specified with the [`/DEFAULTLIB`](defaultlib-specify-default-library.md) option, and then in default libraries named in *`.obj`* files. If a path is specified with the library name, LINK looks for the library in that directory. If no path is specified, LINK looks first in the directory that LINK is running from, and then in any directories specified in the `LIB` environment variable. -## To add .lib files as linker input in the development environment +## To add `.lib` files as linker input in the development environment -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. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). -1. Choose the **Input** property page in the **Linker** folder. +1. Choose the **Configuration Properties** > **Linker** > **Input** property page. -1. Modify the **Additional Dependencies** property to add the .lib files. +1. Modify the **Additional Dependencies** property to add the *`.lib`* files. -## To programmatically add .lib files as linker input +1. Choose **OK** or **Apply** to save your changes. -- See [AdditionalDependencies](/dotnet/api/microsoft.visualstudio.vcprojectengine.vclinkertool.additionaldependencies). +## To programmatically add `.lib` files as linker input + +- See . ## Example -The following sample shows how to build and use a .lib file. First, build a .lib file: +The following sample shows how to build and use a *`.lib`* file. + +First, build the *`.lib`* file: ```cpp // lib_link_input_1.cpp @@ -36,7 +40,7 @@ __declspec(dllexport) int Test() { } ``` -And then, compile this sample by using the .lib file you just created: +And then, compile this sample by using the *`.lib`* file you just created: ```cpp // lib_link_input_2.cpp @@ -54,5 +58,5 @@ int main() { ## See also -[LINK Input Files](link-input-files.md)
-[MSVC Linker Options](linker-options.md) +[LINK input files](link-input-files.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/dot-xml-file-processing.md b/docs/build/reference/dot-xml-file-processing.md index 8ed1da3973..eb1f67631c 100644 --- a/docs/build/reference/dot-xml-file-processing.md +++ b/docs/build/reference/dot-xml-file-processing.md @@ -1,15 +1,15 @@ --- -description: "Learn more about: .Xml File Processing" -title: ".Xml File Processing" -ms.date: "11/04/2016" +description: "Learn more about: XML documentation file processing" +title: "XML documentation file processing" +ms.date: 12/03/2021 helpviewer_keywords: ["XML documentation, processing XML file"] ms.assetid: e70fdeae-80ac-4872-ab24-771c5635cfbf --- -# .Xml File Processing +# XML documentation file processing -The compiler generates an ID string for each construct in your code that is tagged to generate documentation. For more information, see [Recommended Tags Documentation Comments](recommended-tags-for-documentation-comments-visual-cpp.md). The ID string uniquely identifies the construct. Programs that process the .xml file can use the ID string to identify the corresponding .NET Framework metadata or reflection item to which the documentation applies. +The compiler generates an ID string for each construct in your code that is tagged to generate documentation. For more information, see [Recommended tags documentation comments](recommended-tags-for-documentation-comments-visual-cpp.md). The ID string uniquely identifies the construct. Programs that process the XML file can use the ID string to identify the corresponding .NET Framework metadata or reflection item to which the documentation applies. -The .xml file is not a hierarchical representation of your code, it is a flat list with a generated ID for each element. +The XML file isn't a hierarchical representation of your code, it's a flat list with a generated ID for each element. The compiler observes the following rules when it generates the ID strings: @@ -19,50 +19,50 @@ The compiler observes the following rules when it generates the ID strings: | Character | Description | |---------------|-----------------| - | N | namespace

You cannot add documentation comments to a namespace, cref references to a namespace are possible. | - | T | type: class, interface, struct, enum, delegate | - | D | typedef | - | F | field | - | P | property (including indexers or other indexed properties) | - | M | method (including such special methods as constructors, operators, and so forth) | - | E | event | - | ! | error string

The rest of the string provides information about the error. The MSVC compiler generates error information for links that cannot be resolved. | + | N | Namespace

You can't add documentation comments to a namespace, cref references to a namespace are possible. | + | T | Type: class, interface, struct, enum, delegate | + | D | Typedef | + | F | Field | + | P | Property (including indexers or other indexed properties) | + | M | Method (including such special methods as constructors, operators, and so forth) | + | E | Event | + | ! | Error string

The rest of the string provides information about the error. The MSVC compiler generates error information for links that can't be resolved. | -- The second part of the string is the fully qualified name of the item, starting at the root of the namespace. The name of the item, its enclosing type or types, and namespace are separated by periods. If the name of the item itself has periods, they are replaced by the hash-sign ('#'). It is assumed that no item has an hash-sign directly in its name. For example, the fully qualified name of the `String` constructor would be "System.String.#ctor". +- The second part of the string is the fully qualified name of the item, starting at the root of the namespace. The name of the item, its enclosing type or types, and namespace are separated by periods. If the name of the item itself has periods, they're replaced by the hash-sign ('#'). It's assumed that no item has a hash-sign directly in its name. For example, the fully qualified name of the `String` constructor would be `System.String.#ctor`. -- For properties and methods, if there are arguments to the method, the argument list enclosed in parentheses follows. If there are no arguments, no parentheses are present. The arguments are separated by commas. The encoding of each argument follows directly how it is encoded in a .NET Framework signature: +- For properties and methods, if there are arguments to the method, the argument list enclosed in parentheses follows. If there are no arguments, no parentheses are present. The arguments are separated by commas. Each argument is encoded the same way it's encoded in a .NET Framework signature: - - Base types. Regular types (ELEMENT_TYPE_CLASS or ELEMENT_TYPE_VALUETYPE) are represented as the fully qualified name of the type. + - Base types. Regular types (`ELEMENT_TYPE_CLASS` or `ELEMENT_TYPE_VALUETYPE`) are represented as the fully qualified name of the type. - - Intrinsic types (for example, ELEMENT_TYPE_I4, ELEMENT_TYPE_OBJECT, ELEMENT_TYPE_STRING, ELEMENT_TYPE_TYPEDBYREF. and ELEMENT_TYPE_VOID) are represented as the fully qualified name of the corresponding full type, for example, **System.Int32** or **System.TypedReference**. + - Intrinsic types (for example, `ELEMENT_TYPE_I4`, `ELEMENT_TYPE_OBJECT`, `ELEMENT_TYPE_STRING`, `ELEMENT_TYPE_TYPEDBYREF`, and `ELEMENT_TYPE_VOID`) are represented as the fully qualified name of the corresponding full type, for example, **`System.Int32`** or **`System.TypedReference`**. - - ELEMENT_TYPE_PTR is represented as a '*' following the modified type. + - `ELEMENT_TYPE_PTR` is represented as a '`*`' following the modified type. - - ELEMENT_TYPE_BYREF is represented as a '\@' following the modified type. + - `ELEMENT_TYPE_BYREF` is represented as a '`@`' following the modified type. - - ELEMENT_TYPE_PINNED is represented as a '^' following the modified type. The MSVC compiler never generates this. + - `ELEMENT_TYPE_PINNED` is represented as a '`^`' following the modified type. The MSVC compiler never generates this element. - - ELEMENT_TYPE_CMOD_REQ is represented as a '|' and the fully qualified name of the modifier class, following the modified type. The MSVC compiler never generates this. + - `ELEMENT_TYPE_CMOD_REQ` is represented as a '`|`' and the fully qualified name of the modifier class, following the modified type. The MSVC compiler never generates this element. - - ELEMENT_TYPE_CMOD_OPT is represented as a '!' and the fully qualified name of the modifier class, following the modified type. + - `ELEMENT_TYPE_CMOD_OPT` is represented as a '`!`' and the fully qualified name of the modifier class, following the modified type. - - ELEMENT_TYPE_SZARRAY is represented as "[]" following the element type of the array. + - `ELEMENT_TYPE_SZARRAY` is represented as "`[]`" following the element type of the array. - - ELEMENT_TYPE_GENERICARRAY is represented as "[?]" following the element type of the array. The MSVC compiler never generates this. + - `ELEMENT_TYPE_GENERICARRAY` is represented as "`[?]`" following the element type of the array. The MSVC compiler never generates this element. - - ELEMENT_TYPE_ARRAY is represented as [*lowerbound*:`size`,*lowerbound*:`size`] where the number of commas is the rank - 1, and the lower bounds and size of each dimension, if known, are represented in decimal. If a lower bound or size is not specified, it is simply omitted. If the lower bound and size for a particular dimension are omitted, the ':' is omitted as well. For example, a 2-dimensional array with 1 as the lower bounds and unspecified sizes is [1:,1:]. + - `ELEMENT_TYPE_ARRAY` is represented as `[`lower bound`:`size`,`lower bound`:`size`]` where the number of commas is the rank - 1, and the lower bound and size of each dimension, if known, are represented in decimal. If a lower bound or size isn't specified, it's omitted. If the lower bound and size are omitted for a particular dimension, the '`:`' is omitted as well. For example, a 2-dimensional array with 1 as the lower bound and unspecified sizes is represented as `[1:,1:]`. - - ELEMENT_TYPE_FNPTR is represented as "=FUNC:`type`(*signature*)", where `type` is the return type, and *signature* is the arguments of the method. If there are no arguments, the parentheses are omitted. The MSVC compiler never generates this. + - `ELEMENT_TYPE_FNPTR` is represented as "=FUNC:`type`(*signature*)", where `type` is the return type, and *signature* is the arguments of the method. If there are no arguments, the parentheses are omitted. The MSVC compiler never generates this element. - The following signature components are not represented because they are never used for differentiating overloaded methods: + The following signature components aren't represented because they're never used for differentiating overloaded methods: - - calling convention + - Calling convention - - return type + - Return type - - ELEMENT_TYPE_SENTINEL + - `ELEMENT_TYPE_SENTINEL` -- For conversion operators only, the return value of the method is encoded as a '~' followed by the return type, as previously encoded. +- For conversion operators only, the return value of the method is encoded as a '`~`' followed by the return type, as previously encoded. - For generic types, the name of the type will be followed by a back tick and then a number that indicates the number of generic type parameters. For example, @@ -70,9 +70,9 @@ The compiler observes the following rules when it generates the ID strings: ``` - For a type that is defined as `public class MyClass`. + The example shows a type that's defined as `public class MyClass`. - For methods taking generic types as parameters, the generic type parameters are specified as numbers prefaced with back ticks (for example \`0, \`1). Each number representing a zero-based array notation for the type's generic parameters. + For methods that take generic types as parameters, the generic type parameters are specified as numbers prefaced with back ticks (for example \`0, \`1). Each number represents a zero-based array position for the type's generic parameters. ## Example @@ -174,4 +174,4 @@ namespace N { ## See also -[XML Documentation](xml-documentation-visual-cpp.md) +[XML documentation](xml-documentation-visual-cpp.md) diff --git a/docs/build/reference/dumpbin-options.md b/docs/build/reference/dumpbin-options.md index 2bedc34b9e..71bd3a9c66 100644 --- a/docs/build/reference/dumpbin-options.md +++ b/docs/build/reference/dumpbin-options.md @@ -1,9 +1,8 @@ --- title: "DUMPBIN options" description: "Reference guide to the Microsoft DUMPBIN utility command-line options." -ms.date: "02/09/2020" +ms.date: 02/09/2020 helpviewer_keywords: ["DUMPBIN program, options"] -ms.assetid: 563b696e-7599-4480-94b9-014776289ec8 --- # DUMPBIN options @@ -49,7 +48,7 @@ DUMPBIN has the following options: - [/PDBPATH\[:VERBOSE\]](pdbpath.md) -- [/RANGEE:vaMin\[,vaMax\]](range.md) +- [/RANGE:vaMin\[,vaMax\]](range.md) - [/RAWDATA\[:{NONE\|1\|2\|4\|8}\[,#\]\]](rawdata.md) diff --git a/docs/build/reference/dumpbin-reference.md b/docs/build/reference/dumpbin-reference.md index 1e87a71a4e..fd5a44b32a 100644 --- a/docs/build/reference/dumpbin-reference.md +++ b/docs/build/reference/dumpbin-reference.md @@ -1,7 +1,7 @@ --- description: "Learn more about: DUMPBIN Reference" title: "DUMPBIN Reference" -ms.date: "11/04/2016" +ms.date: 08/09/2021 f1_keywords: ["dumpbin"] helpviewer_keywords: ["binary data, binary file dumper", "DUMPBIN program", "Microsoft COFF binary file dumper", "COFF files, displaying information about", "binary file dumper"] ms.assetid: 4bc06822-5330-44b4-8a3f-6180dfd41dfb @@ -11,7 +11,7 @@ ms.assetid: 4bc06822-5330-44b4-8a3f-6180dfd41dfb The Microsoft COFF Binary File Dumper (DUMPBIN.EXE) displays information about Common Object File Format (COFF) binary files. You can use DUMPBIN to examine COFF object files, standard libraries of COFF objects, executable files, and dynamic-link libraries (DLLs). > [!NOTE] -> You can start this tool only from the Visual Studio command prompt. You cannot start it from a system command prompt or from File Explorer. +> We recommend you run DUMPBIN from the Visual Studio command prompt. You can't start it from a system command prompt unless you set the environment correctly. For more information, see [Use the Microsoft C++ toolset from the command line](../building-on-the-command-line.md). Only the [/HEADERS](headers.md) DUMPBIN option is available for use on files produced with the [/GL](gl-whole-program-optimization.md) compiler option. diff --git a/docs/build/reference/dynamic-deopt-linker.md b/docs/build/reference/dynamic-deopt-linker.md new file mode 100644 index 0000000000..6d4602acfc --- /dev/null +++ b/docs/build/reference/dynamic-deopt-linker.md @@ -0,0 +1,53 @@ +--- +title: "/DYNAMICDEOPT (Support C++ Dynamic Debugging) (Preview)" +description: "Learn more about: /DYNAMICDEOPT (Support C++ Dynamic Debugging)." +ms.date: 03/14/2025 +f1_keywords: ["VC.Project.VCLinkerTool.GenerateDynamicDeoptInformation", "/dynamicdeopt"] +helpviewer_keywords: ["DYNAMICDEOPT linker option", "/DYNAMICDEOPT linker option", "-DYNAMICDEOPT linker option", "c++ dynamic debugging"] +--- +# `/DYNAMICDEOPT` (Support C++ Dynamic Debugging) (Preview) + +> [!IMPORTANT] +> The `/DYNAMICDEOPT` linker switch is currently in PREVIEW. +> This information relates to a prerelease feature that might be substantially modified before release. Microsoft makes no warranties, expressed or implied, with respect to the information provided here. + +The **`/DYNAMICDEOPT`** linker option, when used with the compiler switch [`/dynamicdeopt`](dynamic-deopt.md), enables [C++ Dynamic Debugging (Preview)](/visualstudio/debugger/cpp-dynamic-debugging), which allows you to debug optimized code as if it were compiled deoptimized and step in anywhere with on-demand function deoptimization. + +## Syntax + +> **`/DYNAMICDEOPT`**\ +> **`/DYNAMICDEOPT:SUFFIX=`**\ +> **`/DYNAMICDEOPT:SYNC`** + +## Arguments + +*`suffix`*\ +Specify the file extension for the deoptimized output. + +With no options and given `test.cpp` as input, the compiler output includes `test.obj`, `test.exe`, and `test.pdb`, as well as `test.alt.obj`, `test.alt.exe`, and `test.alt.pdb`. This switch allows you to change the suffix for the unoptimized binary build artifacts from `.alt` to something else. If you change the suffix, all files must use the new suffix, and it needs to match the name passed to the compiler using [`/dynamicdeopt:suffix` (Preview)](dynamic-deopt.md). You typically don't use this switch unless you need to avoid filename collisions with other files that you have. + +*`SYNC`*\ +Builds the deoptimized output after building the optimized output instead of in parallel. By default, the compiler spawns a parallel linker to link the unoptimized binary. This switch makes the second link run serially after the first one. This switch is provided in case this better suits your build environment. + +## Remarks + +This preview flag, available starting with Visual Studio 2022 Version 17.14 Preview 2, applies only to x64 projects. + +IncrediBuild 10.24 supports C++ Dynamic Debugging builds.\ +FastBuild v1.15 supports C++ Dynamic Debugging builds. + +### Set this linker option in the Visual Studio development environment + +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 **Linker** > **Debugging** property page. + +### Set this linker option programmatically + +- See . + +## See also + +[`/dynamicdeopt` (Enable C++ Dynamic Debugging) (Preview)](dynamic-deopt.md)\ +[C++ Dynamic Debugging (Preview)](/visualstudio/debugger/cpp-dynamic-debugging)\ +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/dynamic-deopt.md b/docs/build/reference/dynamic-deopt.md new file mode 100644 index 0000000000..33edd942e3 --- /dev/null +++ b/docs/build/reference/dynamic-deopt.md @@ -0,0 +1,78 @@ +--- +title: "/dynamicdeopt (Enable C++ Dynamic Debugging (Preview))" +description: "Enable the Microsoft C++ compiler option /dynamicdeopt to use C++ Dynamic Debugging." +ms.date: 04/01/2025 +f1_keywords: ["/dynamicdeopt"] +helpviewer_keywords: ["-dynamicdeopt compiler option [C++]", "dynamicdeopt compiler option [C++]"] +--- +# `/dynamicdeopt` (Enable C++ Dynamic Debugging) (Preview) + +> [!IMPORTANT] +> The `/dynamicdeopt` compiler switch is currently in PREVIEW. +> This information relates to a prerelease feature that might be substantially modified before release. Microsoft makes no warranties, expressed or implied, with respect to the information provided here. + +Enable [C++ Dynamic Debugging (Preview)](/visualstudio/debugger/cpp-dynamic-debugging) so you can debug optimized code as if it were compiled deoptimized and step in anywhere with on-demand function deoptimization. + +## Syntax + +> **`/dynamicdeopt`**\ +> **`/dynamicdeopt:suffix `**\ +> **`/dynamicdeopt:sync`** + +## Arguments + +*`suffix`*\ +Specify the file extension for the deoptimized output. + +With no options and given `test.cpp` as input, your output includes `test.obj`, `test.exe`, and `test.pdb`, as well as `test.alt.obj`, `test.alt.exe`, and `test.alt.pdb`. This switch allows you to change the suffix of the unoptimized binary build artifacts from `.alt` to something else. If you change the suffix, all files must use the new suffix, and it needs to match the name passed to the linker using [`/dynamicdeopt:suffix` (Preview)](dynamic-deopt-linker.md). You typically don't use this switch unless you need to avoid filename collisions with other files that you have. + +*`sync`*\ +Builds the deoptimized output after building the optimized output instead of in parallel. By default, the compiler spawns a parallel instance of the code generator. This switch makes them run serially instead. This switch is provided in case this better suits your build environment. + +## Remarks + +This preview flag, available starting with Visual Studio 2022 Version 17.14 Preview 2, applies only to x64 projects and must be used with the corresponding linker flag, [`/DYNAMICDEOPT`](dynamic-deopt-linker.md). + +Compiling with `/dynamicdeopt` generates other binaries that are used for debugging. When you debug an optimized function in an optimized file, the debugger steps into the alternate binary instead. This allows you to debug as if you're debugging unoptimized code while still getting the performance advantages of optimized code. + +`/dynamicdeopt` requires: + +`/DEBUG` or `/DEBUG:FULL`. If you don't specify `/DEBUG`, or if you specify `/DEBUG:FASTLINK`, the linker gives a fatal error. +If you specify `/INCREMENTAL`, the compiler generates a warning and automatically turns off `/INCREMENTAL`. +If you specify `/OPT:ICF`, the compiler generates a warning that the debug experience isn't as good. This is because ICF can cause functions to be removed from the alt file, which means you can't step into them. + +IncrediBuild 10.24 supports C++ Dynamic Debugging builds.\ +FastBuild v1.15 supports C++ Dynamic Debugging builds. + +`/dynamicdeopt` is incompatible with edit-and-continue and the following compiler switches: + +```cpp +/GL +/ZI +/RTC1 +/RTCs +/RTCc +/RTCu +/GH +/Gh +/fastcap +/callcap +/ZW +/fsanitize=address +/fsanitize=kernel-address +All of the CLR flags +``` + +### Set this linker option in the Visual Studio development environment + +You can set this switch inside Visual Studio. For more information, see [C++ Dynamic Debugging (Preview)](/visualstudio/debugger/cpp-dynamic-debugging#build-system-integration). There are advantages to setting the switch in Visual Studio because MSBuild automatically suppresses some of the incompatible switches such as `/GL` and `/OPT:ICF`. It also sets the corresponding linker option (`/DYNAMICDEOPT`). You can also set the switch in the command line. + +### Set this compiler option programmatically + +- See . + +## See also + +[C++ Dynamic Debugging (Preview)](/visualstudio/debugger/cpp-dynamic-debugging)\ +[MSVC Compiler Options](compiler-options.md)\ +[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/dynamicbase-use-address-space-layout-randomization.md b/docs/build/reference/dynamicbase-use-address-space-layout-randomization.md index a611af178f..b5ca6135c2 100644 --- a/docs/build/reference/dynamicbase-use-address-space-layout-randomization.md +++ b/docs/build/reference/dynamicbase-use-address-space-layout-randomization.md @@ -1,24 +1,26 @@ --- description: "Learn more about: /DYNAMICBASE (Use address space layout randomization)" title: "/DYNAMICBASE (Use address space layout randomization)" -ms.date: "06/12/2018" +ms.date: 05/05/2022 f1_keywords: ["VC.Project.VCLinkerTool.RandomizedBaseAddress"] helpviewer_keywords: ["-DYNAMICBASE linker option", "/DYNAMICBASE linker option", "DYNAMICBASE linker option"] ms.assetid: 6c0ced8e-fe9c-4b63-b956-eb8a55fbceb2 --- -# /DYNAMICBASE (Use address space layout randomization) +# `/DYNAMICBASE` (Use address space layout randomization) -Specifies whether to generate an executable image that can be randomly rebased at load time by using the address space layout randomization (ASLR) feature of Windows that was first available in Windows Vista. +Specifies whether to generate an executable image that can be randomly rebased at load time by using the address space layout randomization (ASLR) feature of Windows. ASLR was first available in Windows Vista. ## Syntax -> **/DYNAMICBASE**[**:NO**] +> **`/DYNAMICBASE`**[**`:NO`**] ## Remarks -The **/DYNAMICBASE** option modifies the header of an *executable image*, a .dll or .exe file, to indicate whether the application should be randomly rebased at load time, and enables virtual address allocation randomization, which affects the virtual memory location of heaps, stacks, and other operating system allocations. The **/DYNAMICBASE** option applies to both 32-bit and 64-bit images. ASLR is supported on Windows Vista and later operating systems. The option is ignored by earlier operating systems. +The **`/DYNAMICBASE`** option modifies the header of an *executable image*, a .dll or .exe file, to indicate whether the application should be randomly rebased at load time, and enables virtual address allocation randomization, which affects the virtual memory location of heaps, stacks, and other operating system allocations. The **`/DYNAMICBASE`** option applies to both 32-bit and 64-bit images. ASLR is supported on Windows Vista and later operating systems. The option is ignored by earlier operating systems. -By default, **/DYNAMICBASE** is enabled. To disable this option, use **/DYNAMICBASE:NO**. The **/DYNAMICBASE** option is required for the [/HIGHENTROPYVA](highentropyva-support-64-bit-aslr.md) option to have an effect. +By default, **`/DYNAMICBASE`** is enabled. To disable this option, use **`/DYNAMICBASE:NO`**. The **`/DYNAMICBASE`** option is required for the [`/HIGHENTROPYVA`](highentropyva-support-64-bit-aslr.md) option to have an effect. + +Because ASLR can't be disabled on ARM, ARM64, or ARM64EC architectures, **`/DYNAMICBASE:NO`** isn't supported for these targets. ### To set this linker option in Visual Studio @@ -35,6 +37,6 @@ By default, **/DYNAMICBASE** is enabled. To disable this option, use **/DYNAMICB ## See also - [MSVC linker reference](linking.md) -- [MSVC Linker Options](linker-options.md) -- [/HIGHENTROPYVA](highentropyva-support-64-bit-aslr.md) +- [MSVC linker options](linker-options.md) +- [`/HIGHENTROPYVA`](highentropyva-support-64-bit-aslr.md) - [Windows ISV Software Security Defenses](/previous-versions/bb430720(v=msdn.10)) diff --git a/docs/build/reference/dynamicbase.md b/docs/build/reference/dynamicbase.md index 7d42ad401b..9ccddd3219 100644 --- a/docs/build/reference/dynamicbase.md +++ b/docs/build/reference/dynamicbase.md @@ -1,24 +1,26 @@ --- description: "Learn more about: /DYNAMICBASE" title: "/DYNAMICBASE" -ms.date: "06/12/2018" +ms.date: "05/05/2022" f1_keywords: ["/dynamicbase"] helpviewer_keywords: ["-DYNAMICBASE editbin option", "DYNAMICBASE editbin option", "/DYNAMICBASE editbin option"] ms.assetid: edb3df90-7b07-42fb-a94a-f5a4c1d325d6 --- -# /DYNAMICBASE +# `/DYNAMICBASE` Specifies whether to generate an executable image that can be randomly rebased at load time by using the address space layout randomization (ASLR) feature of Windows that was first available in Windows Vista. ## Syntax -> **/DYNAMICBASE**[**:NO**] +> **`/DYNAMICBASE`**[**`:NO`**] ## Remarks -The **/DYNAMICBASE** option modifies the header of an *executable image*, a .dll or .exe file, to indicate whether the application should be randomly rebased at load time, and enables virtual address allocation randomization, which affects the virtual memory location of heaps, stacks, and other operating system allocations. The **/DYNAMICBASE** option applies to both 32-bit and 64-bit images. ASLR is supported on Windows Vista and later operating systems. The option is ignored by earlier operating systems. +The **`/DYNAMICBASE`** option modifies the header of an *executable image*, a .dll or .exe file, to indicate whether the application should be randomly rebased at load time, and enables virtual address allocation randomization, which affects the virtual memory location of heaps, stacks, and other operating system allocations. The **`/DYNAMICBASE`** option applies to both 32-bit and 64-bit images. ASLR is supported on Windows Vista and later operating systems. The option is ignored by earlier operating systems. -By default, **/DYNAMICBASE** is enabled. To disable this option, use **/DYNAMICBASE:NO**. The **/DYNAMICBASE** option is required for the [/HIGHENTROPYVA](highentropyva-support-64-bit-aslr.md) option to have an effect. +By default, **`/DYNAMICBASE`** is enabled. To disable this option, use **`/DYNAMICBASE:NO`**. The **`/DYNAMICBASE`** option is required for the [`/HIGHENTROPYVA`](highentropyva-support-64-bit-aslr.md) option to have an effect. + +Because ASLR can't be disabled on ARM, ARM64, or ARM64EC architectures, **`/DYNAMICBASE:NO`** isn't supported for these targets. ## See also diff --git a/docs/build/reference/environment-variable-macros.md b/docs/build/reference/environment-variable-macros.md deleted file mode 100644 index 26d95444d8..0000000000 --- a/docs/build/reference/environment-variable-macros.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -description: "Learn more about: Environment-Variable Macros" -title: "Environment-Variable Macros" -ms.date: "11/04/2016" -helpviewer_keywords: ["NMAKE program, environment variable macros", "environment variables, macros in NMAKE", "macros, environment-variable"] -ms.assetid: f8e96635-0906-47b0-9f56-12a6fdf5e347 ---- -# Environment-Variable Macros - -NMAKE inherits macro definitions for environment variables that exist before the start of the session. If a variable was set in the operating-system environment, it is available as an NMAKE macro. The inherited names are converted to uppercase. Inheritance occurs before preprocessing. Use the /E option to cause macros inherited from environment variables to override any macros with the same name in the makefile. - -Environment-variable macros can be redefined in the session, and this changes the corresponding environment variable. You can also change environment variables with the SET command. Using the SET command to change an environment variable in a session does not change the corresponding macro, however. - -For example: - -``` -PATH=$(PATH);\nonesuch - -all: - echo %%PATH%% -``` - -In this example, changing `PATH` changes the corresponding environment variable `PATH`; it appends `\nonesuch` to your path. - -If an environment variable is defined as a string that would be syntactically incorrect in a makefile, no macro is created and no warning is generated. If a variable's value contains a dollar sign ($), NMAKE interprets it as the beginning of a macro invocation. Using the macro can cause unexpected behavior. - -## See also - -[Special NMAKE Macros](special-nmake-macros.md) diff --git a/docs/build/reference/example-visual-cpp.md b/docs/build/reference/example-visual-cpp.md index 476048e4e3..95e9710e46 100644 --- a/docs/build/reference/example-visual-cpp.md +++ b/docs/build/reference/example-visual-cpp.md @@ -1,29 +1,29 @@ --- -description: "Learn more about: <example>" -title: "<example> (C++ documentation comments)" -ms.date: "11/04/2016" +description: "Learn more about: XML documentation tag " +title: " (C++ documentation comments)" +ms.date: 12/03/2021 f1_keywords: [""] helpviewer_keywords: [" C++ XML tag", "example C++ XML tag"] ms.assetid: c821aaa7-7ea7-4bee-9922-6705ad57f877 --- -# <example> +# `` documentation tag -The \ tag lets you specify an example of how to use a method or other library member. Commonly, this would also involve use of the [\](code-visual-cpp.md) tag. +The `` tag lets you specify an example of how to use a method or other library member. Commonly, use of this tag would also involve the [``](code-visual-cpp.md) tag. ## Syntax -``` -description +```cpp +/// description ``` -#### Parameters +### Parameters -*description*
+*`description`*\ A description of the code sample. ## Remarks -Compile with [/doc](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. +Compile with [`/doc`](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. ## Example @@ -54,4 +54,4 @@ public: ## See also -[XML Documentation](xml-documentation-visual-cpp.md) +[XML documentation](xml-documentation-visual-cpp.md) diff --git a/docs/build/reference/exception-visual-cpp.md b/docs/build/reference/exception-visual-cpp.md index b0e291b5cb..0e047d8a41 100644 --- a/docs/build/reference/exception-visual-cpp.md +++ b/docs/build/reference/exception-visual-cpp.md @@ -1,37 +1,37 @@ --- -description: "Learn more about: <exception> tag" -title: "<exception> (C++ documentation comments)" +description: "Learn more about: XML documentation tag " +title: " (C++ documentation comments)" ms.date: "11/04/2016" helpviewer_keywords: [" C++ XML tag", "exception C++ XML tag"] ms.assetid: 24451e79-9b89-4b77-98fb-702c6516b818 --- -# <exception> tag +# `` documentation tag -The \ tag lets you specify which exceptions can be thrown. This tag is applied to a method definition. +The `` tag lets you specify which exceptions can be thrown. This tag is applied to a method definition. ## Syntax -``` -description +```cpp +/// description ``` -#### Parameters +### Parameters -*member*
-A reference to an exception that is available from the current compilation environment. Using name lookup rules, the compiler checks that the given exception exists, and translates `member` to the canonical element name in the output XML. The compiler issues a warning if it does not find `member`. +*`member`*\ +A reference to an exception that's available from the current compilation environment. Using name lookup rules, the compiler checks that the given exception exists, and translates `member` to the canonical element name in the output XML. The compiler issues a warning if it doesn't find `member`. Enclose the name in single or double quotation marks. -For information on how to create a cref reference to a generic type, see [\](see-visual-cpp.md). +For more information on how to create a `cref` reference to a generic type, see [``](see-visual-cpp.md). -*description*
+*`description`*\ A description. ## Remarks -Compile with [/doc](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. +Compile with [`/doc`](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. -The MSVC compiler will attempt to resolve cref references in one pass through the documentation comments. Therefore, if using the C++ lookup rules, a symbol is not found by the compiler the reference will be marked as unresolved. See [\](seealso-visual-cpp.md) for more information. +The MSVC compiler attempts to resolve `cref` references in one pass through the documentation comments. If using the C++ lookup rules, when a symbol isn't found by the compiler the reference is marked as unresolved. For more information, see [``](seealso-visual-cpp.md). ## Example @@ -59,4 +59,4 @@ public ref class TestClass { ## See also -[XML Documentation](xml-documentation-visual-cpp.md) +[XML documentation](xml-documentation-visual-cpp.md) diff --git a/docs/build/reference/executing-a-program-in-preprocessing.md b/docs/build/reference/executing-a-program-in-preprocessing.md deleted file mode 100644 index dd03f6ea92..0000000000 --- a/docs/build/reference/executing-a-program-in-preprocessing.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -description: "Learn more about: Executing a Program in Preprocessing" -title: "Executing a Program in Preprocessing" -ms.date: "11/04/2016" -helpviewer_keywords: ["program execution [C++]"] -ms.assetid: 5ecf123a-20e5-40cd-b8d8-dd5a9fdd4b24 ---- -# Executing a Program in Preprocessing - -To use a command's exit code during preprocessing, specify the command, with any arguments, within brackets ([ ]). Any macros are expanded before the command is executed. NMAKE replaces the command specification with the command's exit code, which can be used in an expression to control preprocessing. - -## See also - -[Expressions in Makefile Preprocessing](expressions-in-makefile-preprocessing.md) diff --git a/docs/build/reference/execution-charset-set-execution-character-set.md b/docs/build/reference/execution-charset-set-execution-character-set.md index fda1c306f4..2d67217025 100644 --- a/docs/build/reference/execution-charset-set-execution-character-set.md +++ b/docs/build/reference/execution-charset-set-execution-character-set.md @@ -1,51 +1,49 @@ --- -description: "Learn more about: /execution-charset (Set Execution Character Set)" -title: "/execution-charset (Set Execution Character Set)" -ms.date: "02/06/2019" +description: "Learn more about: /execution-charset (Set execution character set)" +title: "/execution-charset (Set execution character set)" +ms.date: 01/31/2022 f1_keywords: ["execution-charset", "/execution-charset"] helpviewer_keywords: ["/execution-charset compiler option", "-execution-charset compiler option"] ms.assetid: 0e02f487-2236-45bc-95f3-5760933a8f96 --- -# /execution-charset (Set Execution Character Set) +# `/execution-charset` (Set execution character set) -Lets you specify the execution character set for your executable. +This option lets you specify the execution character set for your executable. ## Syntax -``` -/execution-charset:[IANA_name|.CPID] -``` +> **`/execution-charset:`**[*`IANA_name`* | *`.CPID`*] ## Arguments -*IANA_name*
+*`IANA_name`*\ The IANA-defined character set name. -*CPID*
-The code page identifier. +*`.CPID`*\ +The code page identifier, preceded by a `.` character. ## Remarks -You can use the **/execution-charset** option to specify an execution character set. The execution character set is the encoding used for the text of your program that is input to the compilation phase after all preprocessing steps. This character set is used for the internal representation of any string or character literals in the compiled code. Set this option to specify the extended execution character set to use when your source files include characters that are not representable in the basic execution character set. You can use either the IANA or ISO character set name, or a dot (.) followed by a 3 to 5 digit decimal code page identifier to specify the character set to use. For a list of supported code page identifiers and character set names, see [Code Page Identifiers](/windows/win32/Intl/code-page-identifiers). +You can use the **`/execution-charset`** option to specify an execution character set. The execution character set is the encoding used for the text of your program that is input to the compilation phase after all preprocessing steps. This character set is used for the internal representation of any string or character literals in the compiled code. Set this option to specify the extended execution character set to use when your source files include characters that are not representable in the basic execution character set. You can use either the IANA or ISO character set name, or a dot (`.`) followed by 3-5 decimal digits that specify the code page identifier of the character set to use. For a list of supported code page identifiers and character set names, see [Code Page Identifiers](/windows/win32/Intl/code-page-identifiers). -By default, Visual Studio detects a byte-order mark to determine if the source file is in an encoded Unicode format, for example, UTF-16 or UTF-8. If no byte-order mark is found, it assumes the source file is encoded using the current user code page, unless you have specified a character set name or code page by using the **/source-charset** option or the **/utf-8** option. Visual Studio allows you to save your C++ source code by using any of several character encodings. For information about source and execution character sets, see [Character Sets](../../cpp/character-sets.md) in the language documentation. +By default, Visual Studio detects a byte-order mark to determine if the source file is in an encoded Unicode format, for example, UTF-16 or UTF-8. If no byte-order mark is found, it assumes that the source file is encoded in the current user code page, unless you used the **`/source-charset`** or **`/utf-8`** option to specify a character set name or code page. Visual Studio allows you to save your C++ source code in any of several character encodings. For information about source and execution character sets, see [Character sets](../../cpp/character-sets.md) in the language documentation. -If you want to set both the source character set and the execution character set to UTF-8, you can use the **/utf-8** compiler option as a shortcut. It is equivalent to specifying **/source-charset:utf-8 /execution-charset:utf-8** on the command line. Any of these options also enables the **/validate-charset** option by default. +If you want to set both the source character set and the execution character set to UTF-8, you can use the **`/utf-8`** compiler option as a shortcut. It's equivalent to **`/source-charset:utf-8 /execution-charset:utf-8`** on the command line. Any of these options also enables the **`/validate-charset`** option by default. ### To set this compiler option in the Visual Studio development environment -1. Open the project **Property Pages** dialog box. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the **Property Pages** dialog box for your project. For more information, 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 the **/execution-charset** option, and specify your preferred encoding. +1. In **Additional Options**, add the **`/execution-charset`** option, and specify your preferred encoding. 1. Choose **OK** to save your changes. ## See also -[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md)
-[/source-charset (Set Source Character Set)](source-charset-set-source-character-set.md)
-[/utf-8 (Set Source and Executable character sets to UTF-8)](utf-8-set-source-and-executable-character-sets-to-utf-8.md)
-[/validate-charset (Validate for compatible characters)](validate-charset-validate-for-compatible-characters.md) +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md)\ +[`/source-charset` (Set source character set)](source-charset-set-source-character-set.md)\ +[`/utf-8` (Set source and execution character sets to UTF-8)](utf-8-set-source-and-executable-character-sets-to-utf-8.md)\ +[`/validate-charset` (Validate for compatible characters)](validate-charset-validate-for-compatible-characters.md) diff --git a/docs/build/reference/experimental-log.md b/docs/build/reference/experimental-log.md new file mode 100644 index 0000000000..413151fd86 --- /dev/null +++ b/docs/build/reference/experimental-log.md @@ -0,0 +1,56 @@ +--- +title: "/experimental:log (Structured SARIF diagnostics)" +description: "The /experimental:log compiler option outputs experimental structured SARIF output for diagnostics." +ms.date: 06/05/2025 +f1_keywords: ["/experimental:log"] +helpviewer_keywords: ["/experimental:log", "SARIF", "structured diagnostics"] +--- +# `/experimental:log` (Structured SARIF diagnostics) + +Output [SARIF](https://sarifweb.azurewebsites.net/) diagnostics to the specified file or directory. For more information, see [Structured SARIF Diagnostics](sarif-output.md). + +## Syntax + +> **`/experimental:log`** *filename*\ +> **`/experimental:log`** *directoryname\\* + +## Arguments + +*filename* + +The output file for SARIF diagnostics. The compiler automatically adds the `.sarif` extension to *filename*. The space between `/experimental:log` and *filename* is optional. Use double quotes around paths containing spaces. Both relative and absolute paths are supported. + +*directoryname\\* + +The output directory for SARIF diagnostics (for example, `/experimental:log sarif_output\`). Remember to add the trailing backslash (`\`) to indicate it's a directory. Each source file name forms the base name for each SARIF file saved in the directory. The compiler automatically adds the `.sarif` extension to each file name. The space between `/experimental:log` and *directoryname\\* is optional. Use double quotes around paths containing spaces. Both relative and absolute paths are supported. + +## Remarks + +This option is available starting in Visual Studio 2022 version 17.8. + +Diagnostics are also output as text to the console as usual. + +### To set this compiler option in the Visual Studio development environment + +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 specific project **Configuration** and **Platform** for which you want to change the property. You can also choose **"All Configurations"** and **"All Platforms"**. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. +1. Modify the **Additional Options** property, and then choose **OK**. + +## Examples + +The following command produces SARIF information for the compilation of `main.cpp` and saves it in the file `mySarifInfo.sarif`: + +```cmd +cl /experimental:log mySarifInfo main.cpp +``` + +The following command produces SARIF information for the entire compilation and saves it in the `sarif_output` directory in the files `main.sarif` and `other.sarif`: + +```cmd +cl /experimental:log sarif_output\ main.cpp other.cpp +``` + +## See also + +[Structured SARIF Diagnostics](sarif-output.md) diff --git a/docs/build/reference/experimental-module.md b/docs/build/reference/experimental-module.md index 2539602b29..bfbcec74a8 100644 --- a/docs/build/reference/experimental-module.md +++ b/docs/build/reference/experimental-module.md @@ -1,38 +1,60 @@ --- title: "/experimental:module (Enable module support)" description: "Use the /experimental:module compiler option to enable experimental compiler support for named modules." -ms.date: "04/13/2021" +ms.date: 02/12/2025 f1_keywords: ["module", "/experimental:module"] helpviewer_keywords: ["module", "/experimental:module", "Enable module support"] --- -# `/experimental:module` (Enable module support) +# `/experimental:module` (Enable experimental module support) -Enables experimental compiler support for Standard Template Library named modules. +Enables compiler support for Microsoft's experimental form of C++ Standard modules. This option is obsolete in Visual Studio 2019 version 16.11 and later. ## Syntax -> **/experimental:module**[**-**] +> **`/experimental:module`**\[**`-`**] ## Remarks -You can enable experimental modules support by use of the **`/experimental:module`** compiler option along with the [/std:c++latest](std-specify-language-standard-version.md) option. Use **`/experimental:module-`** to disable module support explicitly. + This switch applies to the time before the new, standardized, way of consuming the C++ Standard Library as modules was available. Although you can use this switch to use the older experimental named modules, we recommend that you use the new, standardized, way of consuming the C++ Standard Library as modules described in [Import the C++ standard library using modules](../../cpp/tutorial-import-stl-named-module.md). -This option is available starting in Visual Studio 2015 Update 1. As of Visual Studio 2019 version 16.2, Draft C++20 Standard modules aren't fully implemented in the Microsoft C++ compiler. You can use the modules feature to create single-partition modules and to import the Standard Library modules provided by Microsoft. A module and the code that consumes it must be compiled with the same compiler options. +This compiler switch is available starting in Visual Studio 2015 Update 1. In the VS Installer under the **Individual components** tab, ensure that **C++ Modules for v143 build tools (x64/x86 - experimental)** is selected. You can use the search box with **experimental** to find it. For more information, see [Install C and C++ support in Visual Studio](../vscpp-step-0-installation.md). -For more information on modules and how to use and create them, see [Overview of modules in C++](../../cpp/modules-cpp.md). +| Version | Status | +|---|---| +| Visual Studio 2015 Update 1 | `/experimental:module` introduced. | +| Visual Studio 2019 version 16.10 | C++20 modules support is feature complete. | +| Visual Studio 2019 16.11 and earlier | Enable experimental modules support using **`/experimental:module`** along with [`/std:c++latest`](std-specify-language-standard-version.md). | +| Visual Studio 2019 version 16.11 and later | Modules support is enabled automatically with **`/std:c++20`** or later, or **`/std:c++latest`**. Use **`/experimental:module-`** to disable experimental module support. | + +The experimental library consists of the following named modules: + +- `std.regex` provides the content of header `` +- `std.filesystem` provides the content of header `` +- `std.memory` provides the content of header `` +- `std.threading` provides the contents of headers ``, ``, ``, ``, ``, and `` +- `std.core` provides everything else in the C++ Standard Library + +To consume these modules, add an import declaration to the top of the source code file. For example: + +```cpp +import std.core; +import std.regex; +``` + +To consume the experimental Microsoft Standard Library modules, compile your program with the [`/EHsc`](eh-exception-handling-model.md) and [`/MD`](md-mt-ld-use-run-time-library.md) options. ### To set this compiler option in the Visual Studio development environment 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. Set the **Configuration** drop-down to **All Configurations**. - 1. Select the **Configuration Properties** > **C/C++** > **Language** property page. - 1. Modify the **Enable C++ Modules (experimental)** property, and then choose **OK**. +For more information about how to use and create modules, see [Overview of modules in C++](../../cpp/modules-cpp.md). + ## See also +[Import the C++ standard library using modules](../../cpp/tutorial-import-stl-named-module.md)\ [`/headerUnit` (Use header unit IFC)](headerunit.md)\ [`/exportHeader` (Create header units)](module-exportheader.md)\ [`/reference` (Use named module IFC)](module-reference.md)\ diff --git a/docs/build/reference/expressions-in-makefile-preprocessing.md b/docs/build/reference/expressions-in-makefile-preprocessing.md deleted file mode 100644 index 8ebc1c00b8..0000000000 --- a/docs/build/reference/expressions-in-makefile-preprocessing.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -description: "Learn more about: Expressions in Makefile Preprocessing" -title: "Expressions in Makefile Preprocessing" -ms.date: "11/04/2016" -helpviewer_keywords: ["preprocessing makefiles", "expressions [C++], makefile preprocessing", "makefiles, preprocessing"] -ms.assetid: 37f0f413-97e0-452c-a83f-3c9002c44c92 ---- -# Expressions in Makefile Preprocessing - -The **!IF** or **!ELSE IF** `constantexpression` consists of integer constants (in decimal or C-language notation), string constants, or commands. Use parentheses to group expressions. Expressions use C-style signed long integer arithmetic; numbers are in 32-bit two's-complement form in the range - 2147483648 to 2147483647. - -Expressions can use operators that act on constant values, exit codes from commands, strings, macros, and file-system paths. - -## What do you want to know more about? - -[Makefile preprocessing operators](makefile-preprocessing-operators.md) - -[Executing a program in preprocessing](executing-a-program-in-preprocessing.md) - -## See also - -[Makefile Preprocessing](makefile-preprocessing.md) diff --git a/docs/build/reference/external-external-headers-diagnostics.md b/docs/build/reference/external-external-headers-diagnostics.md index 017731d1a8..30134f5f93 100644 --- a/docs/build/reference/external-external-headers-diagnostics.md +++ b/docs/build/reference/external-external-headers-diagnostics.md @@ -1,34 +1,38 @@ --- title: "/external (External headers diagnostics)" description: "The Microsoft C++ compiler /external headers diagnostic options syntax and usage." -ms.date: 05/14/2021 -f1_keywords: ["/external", "/external:anglebrackets", "/external:env:", "/external:I", "/external:W0", "/external:W1", "/external:W2", "/external:W3", "/external:W4", "/external:templates-", "/experimental:external"] +ms.date: 06/29/2022 +f1_keywords: ["/external", "/external:anglebrackets", "/external:env:", "/external:I", "/external:W0", "/external:W1", "/external:W2", "/external:W3", "/external:W4", "/external:templates-", "/experimental:external", "VC.Project.VCCLCompilerTool.ExternalDirectoriesEnv", "VC.Project.VCCLCompilerTool.ExternalIncludeDirectories", "VC.Project.VCCLCompilerTool.ExternalWarningLevel", "VC.Project.VCCLCompilerTool.TreatExternalTemplatesAsInternal"] helpviewer_keywords: ["/external compiler option [C++]", "-external compiler option [C++]", "external compiler option [C++]"] --- # `/external` (External headers diagnostics) -The **`/external`** compiler options let you specify compiler diagnostic behavior for certain header files. "External" headers are the natural complement of "Just my code": Header files such as system files or third-party library files that you can't or don't intend to change. Since you aren't going to change these files, you may decide it isn't useful to see diagnostic messages from the compiler about them. The `/external` compiler options give you control over these warnings. +The **`/external`** compiler options let you specify compiler diagnostic behavior for certain header files. "External" headers are the natural complement of "Just my code": Header files such as system files or third-party library files that you can't or don't intend to change. Since you aren't going to change these files, you may decide it isn't useful to see diagnostic messages from the compiler about them. The **`/external`** compiler options give you control over these warnings. -The **`/external`** compiler options are available starting in Visual Studio 2017 version 15.6. The **`/external`** options require you also set the **`/experimental:external`** compiler option. +The **`/external`** compiler options are available starting in Visual Studio 2017 version 15.6. In versions of Visual Studio before Visual Studio 2019 version 16.10, the **`/external`** options require you also set the **`/experimental:external`** compiler option. ## Syntax -Use external header options: +Use external header options (Not required in 16.10 and later): > **`/experimental:external`** Specify external headers: > **`/external:anglebrackets`**\ -> **`/external:env:`**_`var`_\ +> **`/external:env:`***`var`*\ > **`/external:I`** *`path`* Specify diagnostics behavior: -> **`/external:W`**_`n`_\ +> **`/external:W0`**\ +> **`/external:W1`**\ +> **`/external:W2`**\ +> **`/external:W3`**\ +> **`/external:W4`**\ > **`/external:templates-`** ### Arguments **`/experimental:external`**\ -Enables the external headers options, starting in Visual Studio 2017 version 15.6. +Enables the external headers options. This option isn't required in Visual Studio 2019 version 16.10 and later. **`/external:anglebrackets`**\ Treats all headers included by `#include
`, where the *`header`* file is enclosed in angle brackets (**`< >`**), as external headers. @@ -36,11 +40,13 @@ Treats all headers included by `#include
`, where the *`header`* file is **`/external:I`** *`path`*\ Defines a root directory that contains external headers. All recursive subdirectories of *`path`* are considered external, but only the *`path`* value is added to the list of directories the compiler searches for include files. The space between **`/external:I`** and *`path`* is optional. Directories that include spaces must be enclosed in double quotes. A directory may be an absolute path or a relative path. -**`/external:env:`**_`var`_\ +**`/external:env:`***`var`*\ Specifies the name of an environment variable *`var`* that holds a semicolon-separated list of external header directories. It's useful for build systems that rely on environment variables such as `INCLUDE`, which you use to specify the list of external include files. Or, `CAExcludePath`, for files that shouldn't be analyzed by `/analyze`. For example, you can specify `/external:env:INCLUDE` to make every directory in `INCLUDE` an external header directory at once. It's the same as using **`/external:I`** to specify the individual directories, but much less verbose. There should be no space between *`var`* and **`/external:env:`**. **`/external:Wn`**\ -This option sets the default warning level to *`n`* (a value from 0 to 4) for external headers. For example, **`/external:W0`** effectively turns off warnings for external headers. The **`/external:Wn`** option has an effect similar to wrapping an included header in a `#pragma warning` directive: +This option sets the default warning level to *`n`* (a value from 0 to 4) for external headers. For example, **`/external:W0`** effectively turns off warnings for external headers. If this option isn't specified, the compiler issues command line warning D9007 for other **`/external`** options. Those options are ignored, because they would have no effect. + +The **`/external:Wn`** option has an effect similar to wrapping an included header in a `#pragma warning` directive: ```cpp #pragma warning (push, 0) @@ -62,6 +68,8 @@ All the existing mechanisms to enable, disable, and suppress warnings still work This sample program has two source files, *`program.cpp`* and *`header_file.h`*. The *`header_file.h`* file is in an *`include_dir`* subdirectory of the directory containing the *`program.cpp`* file: +Source file `include_dir/header_file.h`: + ```cpp // External header: include_dir/header_file.h @@ -73,6 +81,8 @@ struct sample_struct }; ``` +Source file `program.cpp`: + ```cpp // User code: program.cpp #include @@ -91,7 +101,7 @@ cl /EHsc /I include_dir /W4 program.cpp As expected, this sample generates a warning: -```console +```Output program.cpp include_dir\header_file.h(6): warning C4245: 'initializing': conversion from 'int' to 'const T', signed/unsigned mismatch with @@ -101,20 +111,20 @@ include_dir\header_file.h(6): warning C4245: 'initializing': conversion from 'in program.cpp(6): note: see reference to class template instantiation 'sample_struct' being compiled ``` -To treat the header file as an external file and suppress the warning, you can use this command line instead: +To treat the header file as an external file and suppress the warning, you can use this command line instead[\*](#note_experimental): ```cmd -cl /EHsc /experimental:external /I include_dir /external:anglebrackets /external:W0 /W4 program.cpp +cl /EHsc /I include_dir /external:anglebrackets /external:W0 /W4 program.cpp ``` This command line suppresses the warning inside *`header_file.h`* while preserving warnings inside *`program.cpp`*. ### Warnings across the internal and external boundary -Setting a low warning level for external headers can hide some actionable warnings. In particular, it can turn off warnings emitted on template instantiations in user code. These warnings might indicate a problem in your code that only happens in instantiations for particular types. (For example, if you forgot to apply a type trait removing `const` or `&`.) To avoid silencing warnings inside templates defined in external headers, you can use the **`/external:templates-`** option. The compiler considers both the effective warning level in the file that defines the template, and the warning level where template instantiation occurs. Warnings emitted inside an external template appear if the template is instantiated within non-external code. For example, this command line re-enables warnings from template sources in the sample code: +Setting a low warning level for external headers can hide some actionable warnings. In particular, it can turn off warnings emitted on template instantiations in user code. These warnings might indicate a problem in your code that only happens in instantiations for particular types. (For example, if you forgot to apply a type trait removing `const` or `&`.) To avoid silencing warnings inside templates defined in external headers, you can use the **`/external:templates-`** option. The compiler considers both the effective warning level in the file that defines the template, and the warning level where template instantiation occurs. Warnings emitted inside an external template appear if the template is instantiated within non-external code. For example, this command line re-enables warnings from template sources in the sample code[\*](#note_experimental): ```cmd -cl /EHsc /experimental:external /I include_dir /external:anglebrackets /external:W0 /external:templates- /W4 program.cpp +cl /EHsc /I include_dir /external:anglebrackets /external:W0 /external:templates- /W4 program.cpp ``` The C4245 warning appears again in the output, even though the template code is inside an external header. @@ -151,24 +161,52 @@ struct sample_struct With this change to the library header, the author of the library ensures that the global warning level in this header is 4, no matter what gets specified in **`/external:Wn`**. Now all level 4 and above warnings are reported. The library author can also force certain warnings to be errors, disabled, suppressed, or emitted only once in the header. The **`/external`** options don't override that deliberate choice. -`#pragma system_header` is an intrusive header marker that allows library writers to mark certain headers as external. These headers have the warning level specified by **`/external:Wn`**, if any. +### `system_header` pragma + +`#pragma system_header` is an intrusive marker that allows library writers to mark certain headers as external. A file containing `#pragma system_header` is considered external from the point of the pragma to the end of the file, as if it were specified as external on the command line. The compiler emits any diagnostics after the pragma at the warning level specified by **`/external:Wn`**. For more information, see [`system_header` pragma](../../preprocessor/system-header-pragma.md). ### Limitations -Some warnings emitted by the compiler's back-end code generation aren't affected by the **`/external`** options. These warnings usually start with C47XX, though not all C47XX warnings are back-end warnings. You can still disable these warnings by using `/wd47XX`. Code analysis warnings are also unaffected, since they don't have warning levels. +Some warnings emitted by the compiler's back-end code generation aren't affected by the **`/external`** options. These warnings usually start with C47XX, though not all C47XX warnings are back-end warnings. You can still disable these warnings individually by using `/wd47XX`. Code analysis warnings are also unaffected, since they don't have warning levels. ### To set this compiler option in the Visual Studio development environment +In Visual Studio 2019 version 16.10 and later: + +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** > **VC++ Directories** property page. + +1. Set the **External Include Directories** property to specify the IDE equivalent of the **`/external:I path`** option for each semicolon-delimited path. + +1. Select the **Configuration Properties** > **C/C++** > **External Includes** property page. + +1. Set properties: + + - Set **Treat Files Included with Angle Brackets as External** to **Yes** to set the **`/external:anglebrackets`** option. + + - **External Header Warning Level** allows you to set the **`/external:Wn`** option. If this value is set to **Inherit Project Warning Level** or the default, other **`/external`** options are ignored. + + - Set **Template Diagnostics in External Headers** to **Yes** to set the **`/external:templates-`** option. + +1. Choose **OK** or **Apply** to save your changes. + +In versions of Visual Studio before Visual Studio 2019 version 16.10: + 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. Enter the compiler options in the **Additional Options** box. +1. Enter the **`/experimental:external`** option and other **`/external`** compiler options in the **Additional Options** box. + +1. Choose **OK** or **Apply** to save your changes. ### To set this compiler option programmatically - See . +\* Add the **`/experimental:external`** option to enable the external headers options in versions of Visual Studio before Visual Studio 2019 version 16.10. + ## See also [MSVC compiler options](compiler-options.md)\ diff --git a/docs/build/reference/f-set-stack-size.md b/docs/build/reference/f-set-stack-size.md index 094d35d102..9d489f868e 100644 --- a/docs/build/reference/f-set-stack-size.md +++ b/docs/build/reference/f-set-stack-size.md @@ -1,35 +1,35 @@ --- description: "Learn more about: /F (Set Stack Size)" title: "/F (Set Stack Size)" -ms.date: "11/04/2016" -f1_keywords: ["/f"] +ms.date: 06/22/2021 +f1_keywords: ["/f", "-f"] helpviewer_keywords: ["set stack size compiler option", "F compiler option [C++]", "-F compiler option [C++]", "/F compiler option [C++]", "stack, setting size"] ms.assetid: 17320b6f-8305-445b-9ec2-75833f4b29e0 --- -# /F (Set Stack Size) +# `/F` (Set Stack Size) Sets the program stack size in bytes. ## Syntax -> **/F** *number* +> **`/F`** *`number`* ## Arguments -*number*
+*`number`*
The stack size in bytes. ## Remarks -Without this option the stack size defaults to 1 MB. The *number* argument can be in decimal or C-language notation. The argument can range from 1 to the maximum stack size accepted by the linker. The linker rounds up the specified value to the nearest 4 bytes. The space between **/F** and *number* is optional. +Without this option, the stack size defaults to 1 MB. The *`number`* argument can be in decimal or C-language notation. The argument can range from 1 to the maximum stack size accepted by the linker. The linker rounds up the specified value to the nearest multiple of 4 bytes. The space between **`/F`** and *`number`* is optional. -You may need to increase the stack size if your program gets stack-overflow messages. +You may need to increase the stack size if your program gets stack-overflow messages at runtime. You can also set the stack size by: -- Using the **/STACK** linker option. For more information, see [/STACK](stack.md). +- Using the **`/STACK`** linker option. For more information, see [`/STACK` (Stack allocations)](stack-stack-allocations.md). -- Using EDITBIN on the .exe file. For more information, see [EDITBIN Reference](editbin-reference.md). +- Using EDITBIN on the EXE file. For more information, see [EDITBIN reference](editbin-reference.md). ### To set this compiler option in the Visual Studio development environment @@ -45,5 +45,5 @@ You can also set the stack size by: ## See also -[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/fc-full-path-of-source-code-file-in-diagnostics.md b/docs/build/reference/fc-full-path-of-source-code-file-in-diagnostics.md index 5cc1c4a4eb..82e2b082db 100644 --- a/docs/build/reference/fc-full-path-of-source-code-file-in-diagnostics.md +++ b/docs/build/reference/fc-full-path-of-source-code-file-in-diagnostics.md @@ -37,7 +37,7 @@ With **`/FC`**, the compiler output looks similar to this diagnostic text: - c:\test\compiler_option_fc.cpp(5): error C2143: syntax error: missing ';' before '}' ::: moniker-end -::: moniker range="msvc-160" +::: moniker range=">=msvc-160" - C:\test\compiler_option_FC.cpp(5): error C2143: syntax error: missing ';' before '}' diff --git a/docs/build/reference/fe-name-exe-file.md b/docs/build/reference/fe-name-exe-file.md index 1da185271b..3defab99e3 100644 --- a/docs/build/reference/fe-name-exe-file.md +++ b/docs/build/reference/fe-name-exe-file.md @@ -22,7 +22,7 @@ The relative or absolute path and base file name, or relative or absolute path t ## Remarks -The **/Fe** option allows you to specify the output directory, output executable name, or both, for the generated executable file. If *pathname* ends in a path separator (**\**), it is assumed to specify only the output directory. Otherwise, the last component of *pathname* is used as the output file base name, and the rest of *pathname* specifies the output directory. If *pathname* does not have any path separators, it's assumed to specify the output file name in the current directory. The *pathname* must be enclosed in double quotes (**"**) if it contains any characters that can't be in a short path, such as spaces, extended characters, or path components more than eight characters long. +The **/Fe** option allows you to specify the output directory, output executable name, or both, for the generated executable file. If *pathname* ends in a path separator (**`\`**), it is assumed to specify only the output directory. Otherwise, the last component of *pathname* is used as the output file base name, and the rest of *pathname* specifies the output directory. If *pathname* does not have any path separators, it's assumed to specify the output file name in the current directory. The *pathname* must be enclosed in double quotes (**"**) if it contains any characters that can't be in a short path, such as spaces, extended characters, or path components more than eight characters long. When the **/Fe** option is not specified, or when a file base name is not specified in *pathname*, the compiler gives the output file a default name using the base name of the first source or object file specified on the command line and the extension .exe or .dll. diff --git a/docs/build/reference/feature-arm64.md b/docs/build/reference/feature-arm64.md new file mode 100644 index 0000000000..2954b4fed1 --- /dev/null +++ b/docs/build/reference/feature-arm64.md @@ -0,0 +1,47 @@ +--- +description: "Learn more about: /feature (ARM64)" +title: "/feature (ARM64)" +ms.date: 05/28/2024 +--- +# `/feature` (ARM64) + +Enable one or more Arm A-Profile architecture features for an ARM64 extension as specified by **`/arch`** (ARM64). For more information about **`/arch`** (ARM64), see [`/arch` (ARM64)](arch-arm64.md). + +## Syntax + +> **`/feature:`**[**`+arg2`**] + +## Arguments +To enable one or more features the targeted ARM64 extension supports, specify one or more of the following feature arguments: + +| Feature argument | Feature identifier | Optional from | Enabled by default | Description | Supported in version +|--|--|--|--|--|--| +|**`lse`** | `FEAT_LSE` | Armv8.0 | Armv8.1 | Large System Extensions. | Visual Studio 2022 17.10 +|**`rcpc`** | `FEAT_LRCPC` | Armv8.2 | Armv8.3 | Load-Acquire RCpc instructions. | Visual Studio 2022 17.10 +|**`rcpc2`** | `FEAT_LRCPC2` | Armv8.2 | Armv8.4 | Load-Acquire RCpc instructions v2. | Visual Studio 2022 17.11 + +## Remarks + +Example usage: to enable `FEAT_LSE`, specify **`/feature:lse`**. + +If there are conflicting feature arguments specified by **`/feature`**, the right-most feature is enabled. Enabling a feature the targeted ARM64 extension doesn't support may cause unexpected behavior, especially if a CPU doesn't implement the feature. + +Use either **`/feature`** or only **`/arch`** (ARM64) to specify features. For example, to enable `FEAT_LSE` when targeting Armv8.0-A, use both **`/feature:lse`** and **`/arch:armv8.0`**, or specify **`/arch:armv8.0+lse`**. **`/feature`** is a way to specify features without specifying them in **`/arch`** (ARM64). + +### To set the `/feature` compiler option in Visual Studio + +1. Open the **Property Pages** dialog box for the project. For more information, 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 the **Additional options** box, add *`/feature:lse`* or replace `lse` with the feature to enable. Choose **OK** to save your changes. + +### To set this compiler option programmatically + +- See . + +## See also + +[`/arch` (Minimum CPU architecture)](arch-minimum-cpu-architecture.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/filealign.md b/docs/build/reference/filealign.md index 31f8c859d1..1e794ab0e1 100644 --- a/docs/build/reference/filealign.md +++ b/docs/build/reference/filealign.md @@ -8,7 +8,7 @@ ms.assetid: c1017a35-8d71-4ad9-934b-a3e3ea037fa0 --- # /FILEALIGN (Align sections in files) -The **/FILEALIGN** linker option lets you specify the alignment of sections written to your output file as a multiple of an specified size. +The **/FILEALIGN** linker option lets you specify the alignment of sections written to your output file as a multiple of a specified size. ## Syntax diff --git a/docs/build/reference/filename-macros.md b/docs/build/reference/filename-macros.md deleted file mode 100644 index fc8ece7a2a..0000000000 --- a/docs/build/reference/filename-macros.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -description: "Learn more about: Filename Macros" -title: "Filename Macros" -ms.date: "11/04/2016" -helpviewer_keywords: ["macros, NMAKE", "filename macros in NMAKE", "NMAKE program, filename macros"] -ms.assetid: 20afd6b3-5b6c-4e33-9d01-309ce98ef9db ---- -# Filename Macros - -Filename macros are predefined as filenames specified in the dependency (not full filename specifications on disk). These macros do not need to be enclosed in parentheses when invoked; specify only a $ as shown. - -|Macro|Meaning| -|-----------|-------------| -|**$\@**|Current target's full name (path, base name, extension), as currently specified.| -|**$$\@**|Current target's full name (path, base name, extension), as currently specified. Valid only as a dependent in a dependency.| -|**$***|Current target's path and base name minus file extension.| -|**$****|All dependents of the current target.| -|**$?**|All dependents with a later timestamp than the current target.| -|**$<**|Dependent file with a later timestamp than the current target. Valid only in commands in inference rules.| - -To specify part of a predefined filename macro, append a macro modifier and enclose the modified macro in parentheses. - -|Modifier|Resulting filename part| -|--------------|-----------------------------| -|**D**|Drive plus directory| -|**B**|Base name| -|**F**|Base name plus extension| -|**R**|Drive plus directory plus base name| - -## See also - -[Special NMAKE Macros](special-nmake-macros.md) diff --git a/docs/build/reference/filename-parts-syntax.md b/docs/build/reference/filename-parts-syntax.md deleted file mode 100644 index 10d898fd79..0000000000 --- a/docs/build/reference/filename-parts-syntax.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -description: "Learn more about: Filename-Parts Syntax" -title: "Filename-Parts Syntax" -ms.date: "11/04/2016" -helpviewer_keywords: ["syntax, filename-parts", "filename-parts syntax in NMAKE", "NMAKE program, syntax"] -ms.assetid: 48fe38e0-3f3b-40e6-894c-330ee775a656 ---- -# Filename-Parts Syntax - -Filename-parts syntax in commands represents components of the first dependent filename (which may be an implied dependent). Filename components are the file's drive, path, base name, and extension as specified, not as it exists on disk. Use **%s** to represent the complete filename. Use **%|**[*parts*]**F** (a vertical bar character follows the percent symbol) to represent parts of the filename, where *parts* can be zero or more of the following letters, in any order. - -|Letter|Description| -|------------|-----------------| -|No letter|Complete name (same as **%s**)| -|**d**|Drive| -|**p**|Path| -|**f**|File base name| -|**e**|File extension| - -For example, if the filename is c:\prog.exe: - -- %s will be c:\prog.exe - -- %|F will be c:\prog.exe - -- %|dF will be c - -- %|pF will be c:\ - -- %|fF will be prog - -- %|eF will be exe - -## See also - -[Commands in a Makefile](commands-in-a-makefile.md) diff --git a/docs/build/reference/fo-object-file-name.md b/docs/build/reference/fo-object-file-name.md index ea78434297..a0be19b447 100644 --- a/docs/build/reference/fo-object-file-name.md +++ b/docs/build/reference/fo-object-file-name.md @@ -1,35 +1,47 @@ --- title: "/Fo (Object file name)" description: "Reference guide to the Microsoft C++ /Fo (Object file name) compiler option in Visual Studio." -ms.date: "04/20/2020" +ms.date: 01/29/2024 f1_keywords: ["/Fo", "VC.Project.VCCLCompilerTool.ObjectFile", "VC.Project.VCCLWCECompilerTool.ObjectFile"] helpviewer_keywords: ["Fo compiler option [C++]", "object files, naming", "/Fo compiler option [C++]", "-Fo compiler option [C++]"] -ms.assetid: 0e6d593e-4e7f-4990-9e6e-92e1dcbcf6e6 --- -# /Fo (Object File Name) +# `/Fo` (Object File Name) Specifies an object (*`.obj`*) file name or directory to be used instead of the default. ## Syntax -> **`/Fo`**_pathname_ +> **`/Fo"pathname"`**\ +> **`/Fo:[ ]"pathname"`** ## Remarks -You can use the **`/Fo`** compiler option to set an output directory for all the object files generated by the CL compiler command. Or, you can use it to rename a single object file. +You can use the **`/Fo`** compiler option to set an output directory for all the object files generated by the CL compiler command. Or, you can use it to rename a single object file. Don't put a space between the **`/Fo`** option and the *`pathname`* argument. By default, the object files generated by the compiler are placed in the current directory. They're given the base name of the source file and a *`.obj`* extension. -To use the **`/Fo`** option to rename an object file, specify the output filename as the *pathname* argument. When you rename an object file, you can use any name and extension you want, but the recommended convention is to use *`.obj`*. The compiler generates command line error D8036 if you specify a filename to **`/Fo`** when you've specified more than one source file to compile. +To use the **`/Fo`** option to rename an object file, specify the output filename as the *`pathname`* argument. When you rename an object file, you can use any name and extension you want, but the recommended convention is to use an *`.obj`* extension. The compiler generates command line error D8036 if you specify a filename to **`/Fo`** when you've specified more than one source file to compile. -To use the **`/Fo`** option to set an output directory for all object files created by the CL command, specify the directory as the *pathname* argument. A directory is indicated by a trailing slash in the *pathname* argument. The specified directory must exist; it's not created automatically. +To use the **`/Fo`** option to set an output directory for all object files created by the CL command, specify the directory as the *`pathname`* argument. A directory is indicated by a trailing slash or backslash in the *`pathname`* argument. Use an escaped backslash (a double backslash), if you're using a quoted path. The directory path can be absolute, or relative to the source directory. The specified directory must exist, or the compiler reports error D8003. The directory isn't created automatically. ## Example -The following command line creates an object file named *sample.obj* in an existing directory, *\\intermediate*, on drive D. +This command line demonstrates the format that allows for an optional space between the `/Fo` option and the *`pathname`* argument. It creates an object file named *`test.obj`* in the current directory. ```cmd -CL /Fo"D:\intermediate\" /EHsc /c sample.cpp +CL /Fo: "test" /EHsc /c sample1.cpp +``` + +The following command line creates object files named *`sample1.obj`* and *`sample2.obj`* in an existing directory, *`D:\intermediate\`*. It uses escaped backslash characters as path segment separators in a quoted path: + +```cmd +CL /Fo"D:\\intermediate\\" /EHsc /c sample1.cpp sample2.cpp +``` + +This command line creates object files named *`sample1.obj`* and *`sample2.obj`* in an existing directory, *`output\`*, relative to the source directory. + +```cmd +CL /Fooutput\ /EHsc /c sample1.cpp sample2.cpp ``` ## Set the option in Visual Studio or programmatically @@ -40,7 +52,7 @@ CL /Fo"D:\intermediate\" /EHsc /c sample.cpp 1. Select the **Configuration Properties** > **C/C++** > **Output Files** property page. -1. Modify the **Object File Name** property to set the output directory. In the IDE, the object file must have an extension of *`.obj`*. +1. Modify the **Object File Name** property to set the output directory. In the IDE, the object files must have an extension of *`.obj`*. ### To set this compiler option programmatically @@ -48,7 +60,7 @@ CL /Fo"D:\intermediate\" /EHsc /c sample.cpp ## See also -[Output-File (/F) Options](output-file-f-options.md)
-[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md)
-[Specifying the Pathname](specifying-the-pathname.md) +[Output-file (`/F`) options](output-file-f-options.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md)\ +[Specifying the pathname](specifying-the-pathname.md) diff --git a/docs/build/reference/force-force-file-output.md b/docs/build/reference/force-force-file-output.md index 1e013395bb..0df90153e1 100644 --- a/docs/build/reference/force-force-file-output.md +++ b/docs/build/reference/force-force-file-output.md @@ -1,44 +1,45 @@ --- -description: "Learn more about: /FORCE (Force File Output)" -title: "/FORCE (Force File Output)" -ms.date: "07/19/2019" -f1_keywords: ["VC.Project.VCLinkerTool.ForceLink", "/force"] +description: "Learn more about: /FORCE (Force file output)" +title: "/FORCE (Force file output)" +ms.date: 09/08/2022 +f1_keywords: ["VC.Project.VCLinkerTool.ForceFileOutput", "VC.Project.VCLinkerTool.ForceLink", "/force"] helpviewer_keywords: ["FORCE linker option", "file output in linker", "/FORCE linker option", "-FORCE linker option"] ms.assetid: b1e9a218-a5eb-4e60-a4a4-65b4be15e5da --- -# /FORCE (Force File Output) +# `/FORCE` (Force file output) -``` -/FORCE:[MULTIPLE|UNRESOLVED] -``` +Tells the linker to create an executable even if symbols are undefined or multiply defined. -## Remarks +## Syntax -The /FORCE option tells the linker to create a valid .exe file or DLL even if a symbol is referenced but not defined or is multiply defined. +> **`/FORCE`**\[**`:MULTIPLE`**\|**`:UNRESOLVED`**] -The /FORCE option can take an optional argument: +## Remarks -- Use /FORCE:MULTIPLE to create an output file whether or not LINK finds more than one definition for a symbol. +The **`/FORCE`** linker option tells the linker to create an executable image (EXE file or DLL) even if a symbol is referenced but not defined or is defined more than once. -- Use /FORCE:UNRESOLVED to create an output file whether or not LINK finds an undefined symbol. /FORCE:UNRESOLVED is ignored if the entry point symbol is unresolved. +> [!IMPORTANT] +> The **`/FORCE`** option can create an executable that crashes or misbehaves at runtime if it references an undefined symbol or, when a multiply defined symbol has different definitions, if it invokes an unexpected definition in context. -/FORCE with no arguments implies both multiple and unresolved. +The **`/FORCE`** option can take an optional argument: -A file created with this option may not run as expected. The linker will not link incrementally when the /FORCE option is specified. +- Use **`/FORCE:MULTIPLE`** to create an output file whether or not LINK finds more than one definition for a symbol. -If a module is compiled with **/clr**, **/FORCE** will not create an image. +- Use **`/FORCE:UNRESOLVED`** to create an output file whether or not LINK finds an undefined symbol. **`/FORCE:UNRESOLVED`** is ignored if the entry point symbol is unresolved. -### To set this linker option in the Visual Studio development environment +**`/FORCE`** with no arguments implies both **`/FORCE:MULTIPLE`** and **`/FORCE:UNRESOLVED`**. -1. Right-click on the project in **Solution Explorer** and choose **Properties**. +The linker won't link incrementally when the **`/FORCE`** option is specified. -1. Click the **Linker** folder. +If a module is compiled with **`/clr`**, the linker ignores the **`/FORCE`** option. + +### To set this linker option in the Visual Studio development environment -1. Click the **Command Line** property page. +1. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). -1. Type the option into the **Additional Options** box. +1. Select the **Configuration Properties** > **Linker** > **General** property page. -For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Modify the **Force File Output** property. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically @@ -46,5 +47,5 @@ For more information, see [Set C++ compiler and build properties in Visual Studi ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/force-interlocked-functions.md b/docs/build/reference/force-interlocked-functions.md new file mode 100644 index 0000000000..b0fb4df6fa --- /dev/null +++ b/docs/build/reference/force-interlocked-functions.md @@ -0,0 +1,55 @@ +--- +title: "/forceInterlockedFunctions" +description: "Learn more about /forceInterlockedFunctions" +ms.date: 03/07/2025 +--- +# `/forceInterlockedFunctions` + +Dynamically selects between Armv8.0 load, store exclusive instructions or Armv8.1 Large System Extension (LSE) atomic instructions based on CPU capability at runtime. + +## Syntax + +> **`/forceInterlockedFunctions`**[**`-`**] + +## Remarks +When possible, this flag avoids using Armv8.0 load and store exclusive instructions, as these instructions can result in livelocks. +This flag forces the following interlocked intrinsics to be generated as out-of-line functions: + +|Operation|8|16|32|64|128|Pointer| +|-|-------|--------|--------|--------|-------|-------| +|Add|None|None|Full|Full|None|None| +|And|Full|Full|Full|Full|None|None| +|CompareExchange|Full|Full|Full|Full|Full|Full| +|Decrement|None|Full|Full|Full|None|None| +|Exchange|Full|Full|Full|Full|None|Full| +|ExchangeAdd|Full|Full|Full|Full|None|None| +|Increment|None|Full|Full|Full|None|None| +|Or|Full|Full|Full|Full|None|None| +|Xor|Full|Full|Full|Full|None|None| +|bittestandreset|None|None|Full|Full|None|None| +|bittestandset|None|None|Full|Full|None|None| + +Key: + +- **Full**: supports plain, `_acq`, `_rel`, and `_nf` forms. + +- **None**: Not supported + +For more information about interlocked intrinsics, see the "Interlocked intrinsics" section in [Arm64 Intrinsics](../../intrinsics/arm64-intrinsics.md). + +### To set the `/forceInterlockedFunctions` compiler option in Visual Studio + +1. Open the **Property Pages** dialog box for the project. For more information, 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 the **Additional options** box, add *`/forceInterlockedFunctions`* to enable. Choose **OK** to save your changes. + +### To set this compiler option programmatically + +- See . + +## See also +[Arm64 Intrinsics](../../intrinsics/arm64-intrinsics.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/fp-name-dot-pch-file.md b/docs/build/reference/fp-name-dot-pch-file.md index 2f15689076..05e9fda8d3 100644 --- a/docs/build/reference/fp-name-dot-pch-file.md +++ b/docs/build/reference/fp-name-dot-pch-file.md @@ -1,12 +1,12 @@ --- -title: "/Fp (Name .pch file)" +title: "/Fp (Name .pch file)" description: "Use the /Fp compiler option to specify the precompiled header file name." ms.date: "05/31/2019" f1_keywords: ["VC.Project.VCCLCompilerTool.PrecompiledHeaderFile", "VC.Project.VCCLWCECompilerTool.PrecompiledHeaderFile"] helpviewer_keywords: ["Fp compiler option [C++]", "-Fp compiler option [C++]", "naming precompiler header files", "PCH files, naming", "names [C++], PCH", ".pch files, naming", "precompiled header files, naming", "/Fp compiler option [C++]"] ms.assetid: 0fcd9cbd-e09f-44d3-9715-b41efb5d0be2 --- -# /Fp (Name .pch file) +# /Fp (Name .pch file) Provides a path name for a precompiled header instead of using the default path name. diff --git a/docs/build/reference/fp-specify-floating-point-behavior.md b/docs/build/reference/fp-specify-floating-point-behavior.md index 870c64dca9..47f650de28 100644 --- a/docs/build/reference/fp-specify-floating-point-behavior.md +++ b/docs/build/reference/fp-specify-floating-point-behavior.md @@ -1,71 +1,125 @@ --- description: "Learn more about: /fp (Specify floating-point behavior)" title: "/fp (Specify floating-point behavior)" -ms.date: "11/09/2018" +ms.date: 09/29/2021 f1_keywords: ["VC.Project.VCCLCompilerTool.floatingPointModel", "VC.Project.VCCLWCECompilerTool.FloatingPointExceptions", "/fp", "VC.Project.VCCLWCECompilerTool.floatingPointModel", "VC.Project.VCCLCompilerTool.FloatingPointExceptions"] helpviewer_keywords: ["-fp compiler option [C++]", "/fp compiler option [C++]"] ms.assetid: 10469d6b-e68b-4268-8075-d073f4f5d57e --- -# /fp (Specify floating-point behavior) +# `/fp` (Specify floating-point behavior) -Specifies how the compiler treats floating-point expressions, optimizations, and exceptions. The **/fp** options specify whether the generated code allows floating-point environment changes to the rounding mode, exception masks, and subnormal behavior, and whether floating-point status checks return current, accurate results. It controls whether the compiler generates code that maintains source operation and expression ordering and conforms to the standard for NaN propagation, or if it instead generates more efficient code that may reorder or combine operations and use simplifying algebraic transformations that are not allowed by the standard. +Specifies how the compiler treats floating-point expressions, optimizations, and exceptions. The **`/fp`** options specify whether the generated code allows floating-point environment changes to the rounding mode, exception masks, and subnormal behavior, and whether floating-point status checks return current, accurate results. It controls whether the compiler generates code that maintains source operation and expression order, and conforms to the standard for NaN propagation. Or, if it instead generates more efficient code that may reorder or combine operations and use simplifying algebraic transformations that aren't allowed by the IEEE-754 standard. ## Syntax -> **/fp:**[**precise** | **strict** | **fast** | **except**[**-**]] +::: moniker range=">=msvc-170" + +**`/fp:contract`**\ +**`/fp:except`**\[**`-`**]\ +**`/fp:fast`**\ +**`/fp:precise`**\ +**`/fp:strict`** + +::: moniker-end + +::: moniker range="<=msvc-160" + +**`/fp:except`**\[**`-`**]\ +**`/fp:fast`**\ +**`/fp:precise`**\ +**`/fp:strict`** + +::: moniker-end ### Arguments -#### precise +::: moniker range=">=msvc-170" + +#### `/fp:contract` + +The **`/fp:contract`** option allows the compiler to generate floating-point contractions when you specify the **`/fp:precise`** and **`/fp:except`** options. A *contraction* is a machine instruction that combines floating-point operations, such as Fused-Multiply-Add (FMA). FMA, defined as a basic operation by IEEE-754, doesn't round the intermediate product before the addition, so the result can differ from separate multiplication and addition operations. Since it's implemented as a single instruction, it can be faster than separate instructions. The speed comes at a cost of bitwise exact results, and an inability to examine the intermediate value. + +By default, the **`/fp:fast`** option enables **`/fp:contract`**. The **`/fp:contract`** option isn't compatible with **`/fp:strict`**. + +The **`/fp:contract`** option is new in Visual Studio 2022. + +::: moniker-end + +#### `/fp:precise` + +By default, the compiler uses **`/fp:precise`** behavior. + +Under **`/fp:precise`**, the compiler preserves the source expression ordering and rounding properties of floating-point code when it generates and optimizes object code for the target machine. The compiler rounds to source code precision at four specific points during expression evaluation: at assignments, typecasts, when floating-point arguments get passed to a function call, and when a function call returns a floating-point value. Intermediate computations may be performed at machine precision. Typecasts can be used to explicitly round intermediate computations. -By default, the compiler uses `/fp:precise` behavior. +::: moniker range=">=msvc-170" -Under `/fp:precise` the compiler preserves the source expression ordering and rounding properties of floating-point code when it generates and optimizes object code for the target machine. The compiler rounds to source code precision at four specific points during expression evaluation: at assignments, at typecasts, when a floating-point argument is passed to a function call, and when a floating-point value is returned from a function call. Intermediate computations may be performed at machine precision. Typecasts can be used to explicitly round intermediate computations. +The compiler doesn't perform algebraic transformations on floating-point expressions, such as reassociation or distribution, unless it can guarantee the transformation produces a bitwise identical result. Expressions that involve special values (NaN, +infinity, -infinity, -0.0) are processed according to IEEE-754 specifications. For example, `x != x` evaluates to **`true`** if `x` is NaN. Floating-point contractions aren't generated by default under **`/fp:precise`**. This behavior is new in Visual Studio 2022. Previous compiler versions could generate contractions by default under **`/fp:precise`**. -The compiler does not perform algebraic transformations on floating-point expressions, such as reassociation or distribution, unless the transformation is guaranteed to produce a bitwise identical result. -Expressions that involve special values (NaN, +infinity, -infinity, -0.0) are processed according to IEEE-754 specifications. For example, `x != x` evaluates to **`true`** if x is NaN. Floating-point *contractions*, that is, machine instructions that combine floating-point operations, may be generated under `/fp:precise`. +::: moniker-end +::: moniker range="<=msvc-160" -The compiler generates code intended to run in the [default floating-point environment](#the-default-floating-point-environment) and assumes that the floating-point environment is not accessed or modified at runtime. That is, it assumes that the code does not unmask floating-point exceptions, read or write floating-point status registers, or change rounding modes. +The compiler doesn't perform algebraic transformations on floating-point expressions, such as reassociation or distribution, unless it can guarantee the transformation produces a bitwise identical result. Expressions that involve special values (NaN, +infinity, -infinity, -0.0) are processed according to IEEE-754 specifications. For example, `x != x` evaluates to **`true`** if `x` is NaN. Floating-point contractions may be generated under **`/fp:precise`**. -If your floating-point code does not depend on the order of operations and expressions in your floating-point statements (for example, if you don't care whether `a * b + a * c` is computed as `(b + c) * a` or `2 * a` as `a + a`), consider the [/fp:fast](#fast) option, which can produce faster, more efficient code. If your code both depends on the order of operations and expressions, and accesses or alters the floating-point environment (for example, to change rounding modes or to trap floating-point exceptions), use [/fp:strict](#strict). +::: moniker-end -#### strict +The compiler generates code intended to run in the [default floating-point environment](#the-default-floating-point-environment). It also assumes the floating-point environment isn't accessed or modified at runtime. That is, it assumes the code: leaves floating-point exceptions masked, doesn't read or write floating-point status registers, and doesn't change rounding modes. -`/fp:strict` has behavior similar to `/fp:precise`, that is, the compiler preserves the source ordering and rounding properties of floating-point code when it generates and optimizes object code for the target machine, and observes the standard when handling special values. In addition, the program may safely access or modify the floating-point environment at runtime. +If your floating-point code doesn't depend on the order of operations and expressions in your floating-point statements (for example, if you don't care whether `a * b + a * c` is computed as `(b + c) * a` or `2 * a` as `a + a`), consider the [`/fp:fast`](#fast) option, which can produce faster, more efficient code. If your code both depends on the order of operations and expressions, and accesses or alters the floating-point environment (for example, to change rounding modes or to trap floating-point exceptions), use [`/fp:strict`](#strict). -Under `/fp:strict`, the compiler generates code that allows the program to safely unmask floating-point exceptions, read or write floating-point status registers, or change rounding modes. It rounds to source code precision at four specific points during expression evaluation: at assignments, at typecasts, when a floating-point argument is passed to a function call, and when a floating-point value is returned from a function call. Intermediate computations may be performed at machine precision. Typecasts can be used to explicitly round intermediate computations. The compiler does not perform algebraic transformations on floating-point expressions, such as reassociation or distribution, unless the transformation is guaranteed to produce a bitwise identical result. Expressions that involve special values (NaN, +infinity, -infinity, -0.0) are processed according to IEEE-754 specifications. For example, `x != x` evaluates to **`true`** if x is NaN. Floating-point contractions are not generated under `/fp:strict`. +#### `/fp:strict` -`/fp:strict` is computationally more expensive than `/fp:precise` because the compiler must insert additional instructions to trap exceptions and allow programs to access or modify the floating-point environment at runtime. If your code doesn't use this capability, but requires source code ordering and rounding, or relies on special values, use `/fp:precise`. Otherwise, consider using `/fp:fast`, which can produce faster and smaller code. +**`/fp:strict`** has behavior similar to **`/fp:precise`**, that is, the compiler preserves the source ordering and rounding properties of floating-point code when it generates and optimizes object code for the target machine, and observes the standard when handling special values. The program may also safely access or modify the floating-point environment at runtime. -#### fast +Under **`/fp:strict`**, the compiler generates code that allows the program to safely unmask floating-point exceptions, read or write floating-point status registers, or change rounding modes. It rounds to source code precision at four specific points during expression evaluation: at assignments, typecasts, when floating-point arguments get passed to a function call, and when a function call returns a floating-point value. Intermediate computations may be performed at machine precision. Typecasts can be used to explicitly round intermediate computations. The compiler doesn't make any algebraic transformations on floating-point expressions, such as reassociation or distribution, unless it can guarantee the transformation produces a bitwise identical result. Expressions that involve special values (NaN, +infinity, -infinity, -0.0) are processed according to IEEE-754 specifications. For example, `x != x` evaluates to **`true`** if `x` is NaN. Floating-point contractions aren't generated under **`/fp:strict`**. -The `/fp:fast` option allows the compiler to reorder, combine, or simplify floating-point operations to optimize floating-point code for speed and space. The compiler may omit rounding at assignment statements, typecasts, or function calls. It may reorder operations or perform algebraic transforms, for example, by use of associative and distributive laws, even if such transformations result in observably different rounding behavior. Because of this enhanced optimization, the result of some floating-point computations may differ from those produced by other `/fp` options. Special values (NaN, +infinity, -infinity, -0.0) may not be propagated or behave strictly according to the IEEE-754 standard. Floating-point contractions may be generated under `/fp:fast`. The compiler is still bound by the underlying architecture under `/fp:fast`, and additional optimizations may be available through use of the [/arch](arch-minimum-cpu-architecture.md) option. +**`/fp:strict`** is computationally more expensive than **`/fp:precise`** because the compiler must insert extra instructions to trap exceptions and allow programs to access or modify the floating-point environment at runtime. If your code doesn't use this capability, but requires source code ordering and rounding, or relies on special values, use **`/fp:precise`**. Otherwise, consider using **`/fp:fast`**, which can produce faster and smaller code. -Under `/fp:fast`, the compiler generates code intended to run in the default floating-point environment and assumes that the floating-point environment isn't accessed or modified at runtime. That is, it assumes that the code does not unmask floating-point exceptions, read or write floating-point status registers, or change rounding modes. +#### `/fp:fast` -`/fp:fast` is intended for programs that do not require strict source code ordering and rounding of floating-point expressions, and do not rely on the standard rules for handling special values such as NaN. If your floating-point code requires preservation of source code ordering and rounding, or relies on standard behavior of special values, use [/fp:precise](#precise). If your code accesses or modifies the floating-point environment to change rounding modes, unmask floating-point exceptions, or check floating-point status, use [/fp:strict](#strict). +The **`/fp:fast`** option allows the compiler to reorder, combine, or simplify floating-point operations to optimize floating-point code for speed and space. The compiler may omit rounding at assignment statements, typecasts, or function calls. It may reorder operations or make algebraic transforms, for example, by use of associative and distributive laws. It may reorder code even if such transformations result in observably different rounding behavior. Because of this enhanced optimization, the result of some floating-point computations may differ from the ones produced by other **`/fp`** options. Special values (NaN, +infinity, -infinity, -0.0) may not be propagated or behave strictly according to the IEEE-754 standard. Floating-point contractions may be generated under **`/fp:fast`**. The compiler is still bound by the underlying architecture under **`/fp:fast`**, and more optimizations may be available through use of the [`/arch`](arch-minimum-cpu-architecture.md) option. -#### except +Under **`/fp:fast`**, the compiler generates code intended to run in the default floating-point environment and assumes the floating-point environment isn't accessed or modified at runtime. That is, it assumes the code: leaves floating-point exceptions masked, doesn't read or write floating-point status registers, and doesn't change rounding modes. -The `/fp:except` option generates code to ensures that any unmasked floating-point exceptions are raised at the exact point at which they occur, and that no additional floating-point exceptions are raised. By default, the `/fp:strict` option enables `/fp:except`, and `/fp:precise` does not. The `/fp:except` option is not compatible with `/fp:fast`. The option can be explicitly disabled by us of `/fp:except-`. +**`/fp:fast`** is intended for programs that don't require strict source code ordering and rounding of floating-point expressions, and don't rely on the standard rules for handling special values such as `NaN`. If your floating-point code requires preservation of source code ordering and rounding, or relies on standard behavior of special values, use [`/fp:precise`](#precise). If your code accesses or modifies the floating-point environment to change rounding modes, unmask floating-point exceptions, or check floating-point status, use [`/fp:strict`](#strict). -Note that `/fp:except` does not enable any floating-point exceptions by itself, but it is required for programs to enable floating-point exceptions. See [_controlfp](../../c-runtime-library/reference/control87-controlfp-control87-2.md) for information on how to enable floating-point exceptions. +#### `/fp:except` + +The **`/fp:except`** option generates code to ensures that any unmasked floating-point exceptions are raised at the exact point at which they occur, and that no other floating-point exceptions are raised. By default, the **`/fp:strict`** option enables **`/fp:except`**, and **`/fp:precise`** doesn't. The **`/fp:except`** option isn't compatible with **`/fp:fast`**. The option can be explicitly disabled by use of **`/fp:except-`**. + +By itself, **`/fp:except`** doesn't enable any floating-point exceptions. However, it's required for programs to enable floating-point exceptions. For more information on how to enable floating-point exceptions, see [`_controlfp`](../../c-runtime-library/reference/control87-controlfp-control87-2.md). ## Remarks -Multiple `/fp` options can be specified in the same compiler command line. Only one of `/fp:strict`, `/fp:fast`, and `/fp:precise` options can be in effect at a time. If more than one of these options is specified on the command line, the later option takes precedence and the compiler generates a warning. The `/fp:strict` and `/fp:except` options are not compatible with `/clr`. +Multiple **`/fp`** options can be specified in the same compiler command line. Only one of **`/fp:strict`**, **`/fp:fast`**, and **`/fp:precise`** options can be in effect at a time. If you specify more than one of these options on the command line, the later option takes precedence and the compiler generates a warning. The **`/fp:strict`** and **`/fp:except`** options aren't compatible with **`/clr`**. + +The [`/Za`](za-ze-disable-language-extensions.md) (ANSI compatibility) option isn't compatible with **`/fp`**. + +### Using compiler directives to control floating-point behavior + +The compiler provides three pragma directives to override the floating-point behavior specified on the command line: [`float_control`](../../preprocessor/float-control.md), [`fenv_access`](../../preprocessor/fenv-access.md), and [`fp_contract`](../../preprocessor/fp-contract.md). You can use these directives to control floating-point behavior at function-level, not within a function. These directives don't correspond directly to the **`/fp`** options. This table shows how the **`/fp`** options and pragma directives map to each other. For more information, see the documentation for the individual options and pragma directives. + +::: moniker range=">=msvc-170" + +| Option | `float_control(precise, *)` | `float_control(except, *)` | `fenv_access(*)` | `fp_contract(*)` | +|--|--|--|--|--| +| **`/fp:fast`** | `off` | `off` | `off` | `on` | +| **`/fp:precise`** | `on` | `off` | `off` | `off`\* | +| **`/fp:strict`** | `on` | `on` | `on` | `off` | -The [/Za](za-ze-disable-language-extensions.md) (ANSI compatibility) option is not compatible with `/fp`. +\* In versions of Visual Studio before Visual Studio 2022, the **`/fp:precise`** behavior defaulted to `fp_contract(on)`. -### Using Compiler Directives to Control Floating-Point Behavior +::: moniker-end +::: moniker range="<=msvc-160" -The compiler provides three pragma directives to override the floating-point behavior specified on the command-line: [float_control](../../preprocessor/float-control.md), [fenv_access](../../preprocessor/fenv-access.md), and [fp_contract](../../preprocessor/fp-contract.md). You can use these directives to control floating-point behavior at function-level, not within a function. Note that these directives do not correspond directly to the `/fp` options. This table shows how the `/fp` options and pragma directives map to each other. For more information, see the documentation for the individual options and pragma directives. +| Option | `float_control(precise, *)` | `float_control(except, *)` | `fenv_access(*)` | `fp_contract(*)` | +|--|--|--|--|--| +| **`/fp:fast`** | `off` | `off` | `off` | `on` | +| **`/fp:precise`** | `on` | `off` | `off` | `on`\* | +| **`/fp:strict`** | `on` | `on` | `on` | `off` | -| Option | float_control(precise) | float_control(except) | fenv_access | fp_contract | -|-|-|-|-|-| -|`/fp:fast`|off|off|off|on| -|`/fp:precise`|on|off|off|on| -|`/fp:strict`|on|on|on|off| +\* In versions of Visual Studio starting with Visual Studio 2022, the **`/fp:precise`** behavior defaults to `fp_contract(off)`. + +::: moniker-end ### The default floating point environment @@ -73,20 +127,25 @@ When a process is initialized, the *default floating point environment* is set. ### Floating-point environment access and modification -The Microsoft Visual C++ runtime provides several functions to access and modify the floating-point environment. These include [_controlfp](../../c-runtime-library/reference/control87-controlfp-control87-2.md), [_clearfp](../../c-runtime-library/reference/clear87-clearfp.md), and [_statusfp](../../c-runtime-library/reference/status87-statusfp-statusfp2.md) and their variants. To ensure correct program behavior when your code accesses or modifies the floating-point environment, `fenv_access` must be enabled, either by the `/fp:strict` option or by use of the `fenv_access` pragma, for these functions to have any effect. When `fenv_access` is not enabled, access or modification of the floating-point environment may result in unexpected program behavior: code may not honor requested changes to the floating-point environment; the floating-point status registers may not report expected or current results; and unexpected floating-point exceptions may occur or expected floating-point exceptions may not occur. +The Microsoft Visual C++ runtime provides several functions to access and modify the floating-point environment. These include [`_controlfp`](../../c-runtime-library/reference/control87-controlfp-control87-2.md), [`_clearfp`](../../c-runtime-library/reference/clear87-clearfp.md), and [`_statusfp`](../../c-runtime-library/reference/status87-statusfp-statusfp2.md) and their variants. To ensure correct program behavior when your code accesses or modifies the floating-point environment, `fenv_access` must be enabled, either by the **`/fp:strict`** option or by use of the `fenv_access` pragma, for these functions to have any effect. When `fenv_access` isn't enabled, access or modification of the floating-point environment may result in unexpected program behavior: + +- Code may not honor requested changes to the floating-point environment, + +- The floating-point status registers may not report expected or current results, -When your code accesses or modifies the floating-point environment, you must be careful when you combine code where `fenv_access` is enabled with code that does not have `fenv_access` enabled. In code where `fenv_access` is not enabled, the compiler assumes that the platform default floating-point environment is in effect, and that the floating-point status is not accessed or modified. We recommend you save and restore the local floating-point environment to its default state before control is transferred to a function that does not have `fenv_access` enabled. This example demonstrates how the `float_control` pragma can be set and restored: +- Unexpected floating-point exceptions may occur or expected floating-point exceptions may not occur. + +When your code accesses or modifies the floating-point environment, you must be careful when you combine code where `fenv_access` is enabled with code that doesn't have `fenv_access` enabled. In code where `fenv_access` isn't enabled, the compiler assumes the platform default floating-point environment is in effect. It also assumes the floating-point status isn't accessed or modified. We recommend you save and restore the local floating-point environment to its default state before control is transferred to a function that doesn't have `fenv_access` enabled. This example demonstrates how the `float_control` pragma can be set and restored: ```cpp -#pragma float_control(strict, on, push) +#pragma float_control(precise, on, push) // Code that uses /fp:strict mode #pragma float_control(pop) ``` ### Floating-point rounding modes -Under both `/fp:precise` and `/fp:fast` the compiler generates code intended to run in the default floating-point environment and assumes that the environment isn't accessed or modified at runtime. That is, it assumes that the code does not unmask floating-point exceptions, read or write floating-point status registers, or change rounding modes. However, some programs need to -alter the floating-point environment. For example, this sample computes error bounds of a floating-point multiplication by altering floating-point rounding modes: +Under both **`/fp:precise`** and **`/fp:fast`**, the compiler generates code intended to run in the default floating-point environment. It assumes that the environment isn't accessed or modified at runtime. That is, the compiler assumes the code never unmasks floating-point exceptions, reads or writes floating-point status registers, or changes rounding modes. However, some programs need to alter the floating-point environment. For example, this sample computes error bounds of a floating-point multiplication by altering floating-point rounding modes: ```cpp // fp_error_bounds.cpp @@ -134,14 +193,14 @@ int main(void) } ``` -Since the compiler assumes the default floating point environment under `/fp:fast` and `/fp:precise` it is free to ignore the calls to `_controlfp_s`. For example, when compiled by using both `/O2` and `/fp:precise` for the x86 architecture, the bounds are not computed, and the sample program outputs: +Since the compiler assumes the default floating point environment under **`/fp:fast`** and **`/fp:precise`**, it's free to ignore the calls to `_controlfp_s`. For example, when compiled by using both **`/O2`** and **`/fp:precise`** for the x86 architecture, the bounds aren't computed, and the sample program outputs: ```Output cLower = -inf cUpper = -inf ``` -When compiled with both `/O2` and `/fp:strict` for the x86 architecture, the sample program outputs: +When compiled by using both **`/O2`** and **`/fp:strict`** for the x86 architecture, the sample program outputs: ```Output cLower = -inf @@ -150,9 +209,9 @@ cUpper = -3.40282e+38 ### Floating-point special values -Under `/fp:precise` and `/fp:strict`, expressions that involve special values (NaN, +infinity, -infinity, -0.0) behave according to the IEEE-754 specifications. Under `/fp:fast`, the behavior of these special values may be inconsistent with IEEE-754. +Under **`/fp:precise`** and **`/fp:strict`**, expressions that involve special values (NaN, +infinity, -infinity, -0.0) behave according to the IEEE-754 specifications. Under **`/fp:fast`**, the behavior of these special values may be inconsistent with IEEE-754. -This sample demonstrates the different behavior of special values under `/fp:precise`, `/fp:strict` and `/fp:fast`: +This sample demonstrates the different behavior of special values under **`/fp:precise`**, **`/fp:strict`**, and **`/fp:fast`**: ```cpp // fp_special_values.cpp @@ -172,28 +231,27 @@ int main() b = (f2 == f2); c = (f1 - f1); d = (f2 - f2); + e = (gf0 / f3); printf("INFINITY == INFINITY : %d\n", a); printf("NAN == NAN : %d\n", b); printf("INFINITY - INFINITY : %f\n", c); printf("NAN - NAN : %f\n", d); - - e = gf0 / abs(f3); - printf("std::signbit(-0.0/-INFINITY): %d\n", std::signbit(c)); + printf("std::signbit(-0.0/-INFINITY): %d\n", std::signbit(e)); return 0; } ``` -When compiled with `/O2` `/fp:precise` or `/O2` `/fp:strict` for x86 architecture, the outputs are consistent with the IEEE-754 specification: +When compiled by using `/O2 /fp:precise` or `/O2 /fp:strict` for x86 architecture, the outputs are consistent with the IEEE-754 specification: ```Output INFINITY == INFINITY : 1 NAN == NAN : 0 INFINITY - INFINITY : -nan(ind) -NAN - NAN : -nan(ind) -std::signbit(-0.0/-INFINITY): 1 +NAN - NAN : nan +std::signbit(-0.0/-INFINITY): 0 ``` -When compiled with `/O2` `/fp:fast` for x86 architecture, the outputs are not consistent with IEEE-754: +When compiled by using `/O2 /fp:fast`** for x86 architecture, the outputs aren't consistent with IEEE-754: ```Output INFINITY == INFINITY : 1 @@ -205,7 +263,7 @@ std::signbit(-0.0/-INFINITY): 0 ### Floating-point algebraic transformations -Under `/fp:precise` and `/fp:strict`, the compiler does not perform mathematical transformations unless the transformation is guaranteed to produce a bitwise identical result. The compiler may perform such transformations under `/fp:fast`. For example, the expression `a * b + a * c` in the sample function `algebraic_transformation` may be compiled into `a * (b + c)` under `/fp:fast`. Such transformations aren't performed under `/fp:precise` or `/fp:strict`, and the compiler generates `a * b + a * c`. +Under **`/fp:precise`** and **`/fp:strict`**, the compiler doesn't do any mathematical transformation unless the transformation is guaranteed to produce a bitwise identical result. The compiler may make such transformations under **`/fp:fast`**. For example, the expression `a * b + a * c` in the sample function `algebraic_transformation` may be compiled into `a * (b + c)` under **`/fp:fast`**. Such transformations aren't done under **`/fp:precise`** or **`/fp:strict`**, and the compiler generates `a * b + a * c`. ```cpp float algebraic_transformation (float a, float b, float c) @@ -216,7 +274,7 @@ float algebraic_transformation (float a, float b, float c) ### Floating-point explicit casting points -Under `/fp:precise` and `/fp:strict`, the compiler rounds to source code precision at four specific points during expression evaluation: at assignments, at typecasts, when a floating-point argument is passed to a function call, and when a floating-point value is returned from a function call. Typecasts can be used to explicitly round intermediate computations. Under `/fp:fast`, the compiler does not generate explicit casts at these points to guarantee source code precision. This sample demonstrates the behavior under different `/fp` options: +Under **`/fp:precise`** and **`/fp:strict`**, the compiler rounds to source code precision at four specific points during expression evaluation: at assignments, typecasts, when floating-point arguments get passed to a function call, and when a function call returns a floating-point value. Typecasts can be used to explicitly round intermediate computations. Under **`/fp:fast`**, the compiler doesn't generate explicit casts at these points to guarantee source code precision. This sample demonstrates the behavior under different **`/fp`** options: ```cpp float casting(float a, float b) @@ -225,7 +283,7 @@ float casting(float a, float b) } ``` -When compiled by using `/O2` `/fp:precise` or `/O2` `/fp:strict`, you can see that explicit type casts are inserted at both the typecast and at the function return point in the generated code for the x64 architecture: +When compiled by using `/O2 /fp:precise` or `/O2 /fp:strict`, you can see that explicit type casts are inserted at both the typecast and at the function return point in the generated code for the x64 architecture: ```asm addss xmm0, xmm1 @@ -235,7 +293,7 @@ When compiled by using `/O2` `/fp:precise` or `/O2` `/fp:strict`, you can see th ret 0 ``` -Under `/O2` `/fp:fast` the generated code is simplified, because all type casts are optimized away: +Under `/O2 /fp:fast` the generated code is simplified, because all type casts are optimized away: ```asm addss xmm0, xmm1 @@ -257,5 +315,5 @@ Under `/O2` `/fp:fast` the generated code is simplified, because all type casts ## See also -[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md)
+[MSVC compiler options](compiler-options.md)
+[MSVC compiler command-line syntax](compiler-command-line-syntax.md)
diff --git a/docs/build/reference/fpcvt.md b/docs/build/reference/fpcvt.md new file mode 100644 index 0000000000..8661d649c9 --- /dev/null +++ b/docs/build/reference/fpcvt.md @@ -0,0 +1,65 @@ +--- +description: "Learn more about: /fpcvt (Floating-point to integer conversion compatibility)" +title: "/fpcvt (Floating-point to unsigned integer conversion compatibility)" +ms.date: 11/03/2021 +f1_keywords: ["/fpcvt", "-fpcvt"] +helpviewer_keywords: ["-fpcvt compiler option [C++]", "/fpcvt compiler option [C++]"] +--- +# `/fpcvt` (Floating-point to integer conversion compatibility) + +Specifies how the compiler treats floating-point conversions to integer types. + +## Syntax + +> **`/fpcvt:IA`**\ +> **`/fpcvt:BC`** + +### Arguments + +#### `/fpcvt:IA` + +The **`/fpcvt:IA`** option tells the compiler to convert floating point values to integers so the results are compatible with the Intel AVX-512 conversion instructions. This behavior is the usual behavior in Visual Studio 2019 for x86 targets. + +#### `/fpcvt:BC` + +The **`/fpcvt:BC`** option tells the compiler to convert floating point values to unsigned integers so the results are compatible with the Visual Studio 2017 and earlier compilers. This behavior is the default in Visual Studio 2022. + +## Remarks + +In Visual Studio 2019 version 16.8 and later versions, the **`/fpcvt`** compiler option can be used to control the results of floating-point to integer conversions. The **`/fpcvt:BC`** option specifies the default behavior of Visual Studio 2022, which is the same as the behavior of Visual Studio 2017 and earlier versions. The **`/fpcvt:IA`** option specifies behavior compatible with Intel Architecture (IA) AVX-512 conversion instruction behavior. This option can be used with either 32-bit x86 or 64-bit x64 targets, and it applies whether [`/arch:AVX512`](arch-x86.md) is specified or not. + +For Visual Studio 2019, the default behavior for x64 targets is consistent with **`/fpcvt:BC`** unless **`/arch:AVX512`** is specified. Usually, the behavior for x86 targets is consistent with **`/fpcvt:IA`**, except under **`/arch:IA32`**, **`/arch:SSE`**, or sometimes where the result of a function call is directly converted to an unsigned integer. Use of **`/fpcvt`** overrides the default, so all conversions are handled consistently on either target. The behavior of conversions for ARM and ARM64 targets isn't consistent with either **`/fpcvt:BC`** or **`/fpcvt:IA`**. + +Standard C++ specifies that if a truncated floating-point value is exactly representable in an integer type, it must have that value when converted to that type. Otherwise, any behavior at all is allowed. Both **`/fpcvt`** options conform with Standard C++. The only difference is in what values are returned for invalid source values. + +The **`/fpcvt:IA`** option causes any invalid conversion to return a single *sentinel* value, which is the destination value farthest from zero. For conversion to signed types, the sentinel is the minimum value for that type. Unsigned types use the maximum value. Floating-point operations may return a Not-a-Number (NaN) value to indicate an invalid operation. That indicator isn't an option for conversion to integer types, which don't have NaN values. The sentinel is used as a proxy for a NaN value, although it can also be the result of a valid conversion. + +The **`/fpcvt:BC`** option also makes conversion to signed types return the minimum possible value when the source is invalid. However, conversion to unsigned integer types is based on conversion to **`long long`**. To convert a value to **`unsigned int`**, the compiler first converts it to type **`long long`**. The compiler then truncates the result to 32 bits. To convert a value to **`unsigned long long`**, valid source values that are too high for a **`long long`** are handled as a special case. All other values are first converted to **`long long`** and then recast to **`unsigned long long`**. + +The **`/fpcvt`** options are new in Visual Studio 2019 version 16.8. If you specify more than one **`/fpcvt`** option on the command line, the later option takes precedence and the compiler generates a warning. + +### Intrinsic functions for conversions + +You can specify the behavior of a specific conversion independently of the **`/fpcvt `** option, which applies globally. The compiler provides intrinsic sentinel conversion functions for conversions compatible with **`/fpcvt:IA`**. For more information, see [Sentinel conversion functions](../../intrinsics/sentinel-conversion-functions.md). The compiler also provides saturation conversion functions compatible with conversions on ARM or ARM64 target architectures. For more information, see [Saturation conversion functions](../../intrinsics/saturation-conversion-functions.md). + +The compiler also supports intrinsic conversion functions that execute as quickly as possible for valid conversions. These functions may generate any value or throw an exception for an invalid conversion. The results depend on the target platform, compiler options, and context. They're useful for handling values that have already been range-checked, or values generated in a way that can't cause an invalid conversion. For more information, see [Fast conversion functions](../../intrinsics/fast-conversion-functions.md). + +### To set this compiler option in the Visual Studio development environment + +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. Modify the **Additional Options** property to add **`/fpcvt:IA`** or **`/fpcvt:BC`**. Choose **OK** to save your changes. + +### To set this compiler option programmatically + +- See . + +## See also + +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md)\ +[Fast conversion functions](../../intrinsics/fast-conversion-functions.md)\ +[Saturation conversion functions](../../intrinsics/saturation-conversion-functions.md)\ +[Sentinel conversion functions](../../intrinsics/sentinel-conversion-functions.md) diff --git a/docs/build/reference/fr-fr-create-dot-sbr-file.md b/docs/build/reference/fr-fr-create-dot-sbr-file.md index 18ee204b7f..4090865e8f 100644 --- a/docs/build/reference/fr-fr-create-dot-sbr-file.md +++ b/docs/build/reference/fr-fr-create-dot-sbr-file.md @@ -1,39 +1,40 @@ --- -description: "Learn more about: /FR, /Fr (Create .Sbr File)" -title: "/FR, /Fr (Create .Sbr File)" -ms.date: "11/04/2016" +description: "Learn more about: /FR, /Fr (Name SBR file)" +title: "/FR, /Fr (Name SBR file)" +ms.date: 08/30/2022 f1_keywords: ["VC.Project.VCCLWCECompilerTool.BrowseInformation", "VC.Project.VCCLCompilerTool.BrowseInformation", "/fr", "VC.Project.VCCLCompilerTool.BrowseInformationFile", "VC.Project.VCCLWCECompilerTool.BrowseInformationFile"] helpviewer_keywords: ["/FR compiler option [C++]", "-FR compiler option [C++]", "FR compiler option [C++]", "symbolic browser information"] ms.assetid: 3fd8f88b-3924-4feb-9393-287036a28896 --- -# /FR, /Fr (Create .Sbr File) +# `/FR`, `/Fr` (Name SBR file) -Creates .sbr files. +Creates *`.sbr`* (source browser) files, used by [Code maps](/visualstudio/modeling/code-maps-for-cpp), BSCMAKE, and some third-party code browsing tools. ## Syntax -``` -/FR[pathname[\filename]] -/Fr[pathname[\filename]] -``` +> **`/FR`**\[*`pathname`*\[*`\filename`*]]\ +> **`/Fr`**\[*`pathname`*\[*`\filename`*]] -## Remarks +### Arguments + +*`pathname`*\ +The optional destination directory for the generated *`.sbr`* files. If this value isn't specified, the files are created in the default output directory. For more information, see [Specifying the pathname](specifying-the-pathname.md). -> [!WARNING] -> Although BSCMAKE is still installed with Visual Studio, it is no longer used by the IDE. Since Visual Studio 2008, browse and symbol information is stored automatically in a SQL Server .sdf file in the solution folder. +*`filename`*\ +An optional filename for the generated *`.sbr`* file. If this value isn't specified, the compiler uses the base name of the source file with a *`.sbr`* extension. For more information, see [Specifying the pathname](specifying-the-pathname.md). -During the build process, the Microsoft Browse Information File Maintenance Utility (BSCMAKE) uses these files to create a .BSC file, which is used to display browse information. +## Remarks -**/FR** creates an .sbr file with complete symbolic information. +**`/FR`** creates an *`.sbr`* file with complete symbolic information. -**/Fr** creates an .sbr file without information on local variables. +**`/Fr`** creates an *`.sbr`* file without information on local variables. **`/Fr`** is deprecated; use **`/FR`** instead. For more information, see the Deprecated and removed compiler options section in [Compiler options listed by category](compiler-options-listed-by-category.md). -If you do not specify `filename`, the .sbr file gets the same base name as the source file. +The Visual Studio [Code Maps](/visualstudio/modeling/code-maps-for-cpp) feature requires the *`.sbr`* files generated by **`/FR`**. -**/Fr** is deprecated; use **/FR** instead. For more information, see Deprecated and Removed Compiler Options in [Compiler Options Listed by Category](compiler-options-listed-by-category.md). +The Microsoft Browse Information File Maintenance Utility (BSCMAKE) uses *`.sbr`* files to create a *`.bsc`* file, used to display browse information in some third-party tools. For more information, see [BSCMAKE reference](bscmake-reference.md). > [!NOTE] -> Do not change the .sbr extension. BSCMAKE requires the intermediary files to have that extension. +> Although BSCMAKE is still installed with Visual Studio, it's no longer used by the IDE. Since Visual Studio 2008, browse and symbol information is stored automatically in a SQL Server SDF file in the solution folder. If you use BSCMAKE, don't change the *`.sbr`* extension. BSCMAKE requires the intermediate files to have that extension. ### To set this compiler option in the Visual Studio development environment @@ -49,7 +50,7 @@ If you do not specify `filename`, the .sbr file gets the same base name as the s ## See also -[Output-File (/F) Options](output-file-f-options.md)
-[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md)
-[Specifying the Pathname](specifying-the-pathname.md) +[Output-File (`/F`) options](output-file-f-options.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md)\ +[Specifying the pathname](specifying-the-pathname.md) diff --git a/docs/build/reference/fsanitize-coverage.md b/docs/build/reference/fsanitize-coverage.md new file mode 100644 index 0000000000..771a5b7ad5 --- /dev/null +++ b/docs/build/reference/fsanitize-coverage.md @@ -0,0 +1,86 @@ +--- +description: "Learn more about the /fsanitize-coverage (Configure sanitizer coverage) compiler option." +title: "/fsanitize-coverage (Configure sanitizer coverage)" +ms.date: 09/15/2021 +f1_keywords: ["/fsanitize-coverage", "-fsanitize-coverage", "/fsanitize-coverage=inline-8bit-counters", "/fsanitize-coverage=edge", "/fsanitize-coverage=trace-cmp", "/fsanitize-coverage=trace-div", "/fno-sanitize-coverage=inline-8bit-counters", "/fno-sanitize-coverage=edge", "/fno-sanitize-coverage=trace-cmp", "/fno-sanitize-coverage=trace-div"] +helpviewer_keywords: ["/fsanitize-coverage [C++]", "sanitizer compiler option [C++]", "/fsanitize-coverage=inline-8bit-counters", "/fsanitize-coverage=edge", "/fsanitize-coverage=trace-cmp", "/fsanitize-coverage=trace-div", "/fno-sanitize-coverage=inline-8bit-counters", "/fno-sanitize-coverage=edge", "/fno-sanitize-coverage=trace-cmp", "/fno-sanitize-coverage=trace-div"] +--- +# `/fsanitize-coverage` (Configure sanitizer coverage) + +The **`/fsanitize-coverage`** compiler options instruct the compiler to add various kinds of instrumentation points where user-defined functions are called. These options are useful for fuzzing scenarios that use **`/fsanitize=fuzzer`**, like OneFuzz. For more information, see the [OneFuzz documentation](https://www.microsoft.com/research/project/project-onefuzz/) and [OneFuzz GitHub project](https://github.com/microsoft/onefuzz). + +## Syntax + +> **`/fsanitize-coverage=edge`**\ +> **`/fsanitize-coverage=inline-8bit-counters`**\ +> **`/fsanitize-coverage=trace-cmp`**\ +> **`/fsanitize-coverage=trace-div`**\ +> **`/fno-sanitize-coverage=edge`**\ +> **`/fno-sanitize-coverage=inline-8bit-counters`**\ +> **`/fno-sanitize-coverage=trace-cmp`**\ +> **`/fno-sanitize-coverage=trace-div`** + +## Remarks + +The experimental **`/fsanitize-coverage`** compiler options offer code coverage support and various options to modify which compiler-provided instrumentation is generated. All these options are automatically set when the [`/fsanitize=fuzzer`](fsanitize.md) option is specified. The **`/fsanitize=fuzzer`** option requires the same instrumentation points and callbacks mentioned in these options. + +The **`/fsanitize-coverage`** options don't allow comma-separated syntax, for example: **`/fsanitize-coverage=edge,inline-8bit-counters,trace-cmp,trace-div`**. Specify these options individually. + +The **`/fsanitize-coverage`** options are available beginning in Visual Studio 2022 version 17.0. + +### Code coverage + +The **`/fsanitize-coverage=edge`** compiler option enables code coverage instrumentation along all non-redundant edges. Use **`/fno-sanitize-coverage=edge`** to disable this option if it's already provided or implied by another option. + +### Inline counters + +The **`/fsanitize-coverage=inline-8bit-counters`** compiler option instructs the compiler to add an inline counter increment on every relevant edge. This option also adds a call to `extern "C" void __sanitizer_cov_8bit_counters_init(uint8_t *start, uint8_t *stop)` that you must implement. The arguments correspond to the start and end of an array that contains all the 8-bit counters created. Use **`/fno-sanitize-coverage=inline-8bit-counters`** to disable this option if it's already provided or implied by another option. + +### Trace comparisons + +The **`/fsanitize-coverage=trace-cmp`** compiler option instructs the compiler to insert calls to the following functions: + +```C +// Before each comparison instruction of the stated size. +void __sanitizer_cov_trace_cmp1(uint8_t Arg1, uint8_t Arg2); +void __sanitizer_cov_trace_cmp2(uint16_t Arg1, uint16_t Arg2); +void __sanitizer_cov_trace_cmp4(uint32_t Arg1, uint32_t Arg2); +void __sanitizer_cov_trace_cmp8(uint64_t Arg1, uint64_t Arg2); + +// Before each comparison instruction of the stated size, if one of the operands (Arg1) is constant. +void __sanitizer_cov_trace_const_cmp1(uint8_t Arg1, uint8_t Arg2); +void __sanitizer_cov_trace_const_cmp2(uint16_t Arg1, uint16_t Arg2); +void __sanitizer_cov_trace_const_cmp4(uint32_t Arg1, uint32_t Arg2); +void __sanitizer_cov_trace_const_cmp8(uint64_t Arg1, uint64_t Arg2); +``` + +Use **`/fno-sanitize-coverage=trace-cmp`** to disable this option if it's already provided or implied by another option. + +### Trace divisions + +The **`/fsanitize-coverage=trace-div`** compiler option instructs the compiler to insert calls to the following functions: + +```C +// Before a division instruction of the stated size. +void __sanitizer_cov_trace_div4(uint32_t Val); +void __sanitizer_cov_trace_div8(uint64_t Val); +``` + +Use **`/fno-sanitize-coverage=trace-div`** to disable this option if it's already provided or implied by another option. + +### To set the advanced compiler options + +1. Open your project's **Property Pages** dialog box. + +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. + +1. Modify the **Additional Options** property to set **/fsanitize-coverage** options. + +1. Choose **OK** or **Apply** to save your changes. + +## See also + +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md)\ +[`/fsanitize` (Enable Sanitizers)](fsanitize.md)\ +[AddressSanitizer build and language reference](../../sanitizers/asan-building.md) diff --git a/docs/build/reference/fsanitize.md b/docs/build/reference/fsanitize.md index eeb828ebfe..6e9e8c9439 100644 --- a/docs/build/reference/fsanitize.md +++ b/docs/build/reference/fsanitize.md @@ -1,27 +1,35 @@ --- description: "Learn more about the /fsanitize (enable sanitizers) compiler option" title: "/fsanitize (Enable sanitizers)" -ms.date: 02/24/2021 -f1_keywords: ["/fsanitize", "-fsanitize", "/fsanitize=address", "/fsanitize-address-use-after-return", "-fsanitize-address-use-after-return", "/fno-sanitize-address-vcasan-lib", "-fno-sanitize-address-vcasan-lib"] +ms.date: 02/17/2022 +f1_keywords: ["/fsanitize", "-fsanitize", "/fsanitize=address", "/fsanitize=fuzzer", "/fsanitize-address-use-after-return", "-fsanitize-address-use-after-return", "/fno-sanitize-address-vcasan-lib", "-fno-sanitize-address-vcasan-lib", "VC.Project.VCCLCompilerTool.EnableASAN"] helpviewer_keywords: ["/fsanitize [C++]", "-fsanitize=address [C++]", "address sanitizer compiler option [C++]", "/fsanitize-address-use-after-return", "/fno-sanitize-address-vcasan-lib"] --- # `/fsanitize` (Enable sanitizers) -Use the **`/fsanitize`** compiler options to enable sanitizers. As of Visual Studio 2019 16.9, the only supported sanitizer is [AddressSanitizer](../../sanitizers/asan.md). +Use the **`/fsanitize`** compiler options to enable sanitizers. ## Syntax > **`/fsanitize=address`**\ +> **`/fsanitize=kernel-address`**\ +> **`/fsanitize=fuzzer`**\ > **`/fsanitize-address-use-after-return`**\ > **`/fno-sanitize-address-vcasan-lib`** +> **`/fsanitize-address-asan-compat-lib`** +> **`/fno-sanitize-address-asan-compat-lib`** ## Remarks -The **`/fsanitize=address`** compiler option enables [AddressSanitizer](../../sanitizers/asan.md), a powerful compiler and runtime technology to light up [hard-to-find bugs](../../sanitizers/asan.md#error-types). +The **`/fsanitize=address`** compiler option enables [AddressSanitizer](../../sanitizers/asan.md), a powerful compiler and runtime technology to uncover [hard-to-find bugs](../../sanitizers/asan.md#error-types). Support for the **`/fsanitize=address`** option is available starting in Visual Studio 2019 version 16.9. -The **`/fsanitize-address-use-after-return`** and **`/fno-sanitize-address-vcasan-lib`** compiler options, and the [`/INFERASANLIBS` (Use inferred sanitizer libs)](./inferasanlibs.md) and **`/INFERASANLIBS:NO`** linker options offer support for advanced users. For more information, see [AddressSanitizer build and language reference](../../sanitizers/asan-building.md). +The **`/fsanitize=kernel-address`** compiler option enables [Kernel AddressSanitizer (KASan)](/windows-hardware/drivers/devtest/kasan). KASan is the kernel-mode variant of AddressSanitizer, available starting in Visual Studio 2022 version 17.11. KASan is only supported on Windows 11 24H2 or Windows Server 2025 and higher, and requires building using a Windows SDK 10.0.26100.2161 and higher. Building with KASan also implies the **`/fsanitize-address-asan-compat-lib`** compiler option. -The **`/fsanitize`** options are available beginning in Visual Studio 2019 version 16.9. +The **`/fsanitize=fuzzer`** compiler option enables experimental support for [LibFuzzer](https://llvm.org/docs/LibFuzzer.html). LibFuzzer is a coverage-guided fuzzing library that can be used to find bugs and crashes caused by user-provided input. We recommended you use **`/fsanitize=address`** with LibFuzzer. This option is useful for fuzzing tools such as OneFuzz. For more information, see the [OneFuzz documentation](https://www.microsoft.com/research/project/project-onefuzz/) and [OneFuzz GitHub project](https://github.com/microsoft/onefuzz). Support for the **`/fsanitize=fuzzer`** option is available starting in Visual Studio 2022 version 17.0. + +The **`/fsanitize`** option doesn't allow comma-separated syntax, for example: **`/fsanitize=address,fuzzer`**. These options must be specified individually. + +The **`/fsanitize-address-use-after-return`**, **`/fno-sanitize-address-vcasan-lib`**, **`/fsanitize-address-asan-compat-lib`**, and **`/fno-sanitize-address-asan-compat-lib`** compiler options, and the [`/INFERASANLIBS` (Use inferred sanitizer libs)](./inferasanlibs.md) and **`/INFERASANLIBS:NO`** linker options offer support for advanced users. For more information, see [AddressSanitizer build and language reference](../../sanitizers/asan-building.md). ### To set the **`/fsanitize=address`** compiler option in the Visual Studio development environment @@ -33,6 +41,16 @@ The **`/fsanitize`** options are available beginning in Visual Studio 2019 versi 1. Choose **OK** or **Apply** to save your changes. +### To set the **`/fsanitize=fuzzer`** compiler option in the Visual Studio development environment + +1. Open your project's **Property Pages** dialog box. + +1. Select the **Configuration Properties** > **C/C++** > **General** property page. + +1. Modify the **Enable Fuzzer** property. To enable it, choose **Yes (/fsanitize=fuzzer)**. + +1. Choose **OK** or **Apply** to save your changes. + ### To set the advanced compiler options 1. Open your project's **Property Pages** dialog box. @@ -52,6 +70,7 @@ The **`/fsanitize`** options are available beginning in Visual Studio 2019 versi [MSVC compiler options](compiler-options.md)\ [MSVC compiler command-line syntax](compiler-command-line-syntax.md)\ [`/INFERASANLIBS` (Use inferred sanitizer libs)](./inferasanlibs.md)\ +[`/fsanitize-coverage` (Configure sanitizer coverage)](fsanitize-coverage.md)\ [AddressSanitizer overview](../../sanitizers/asan.md)\ [AddressSanitizer known issues](../../sanitizers/asan-known-issues.md)\ [AddressSanitizer build and language reference](../../sanitizers/asan-building.md) diff --git a/docs/build/reference/functionpadmin-create-hotpatchable-image.md b/docs/build/reference/functionpadmin-create-hotpatchable-image.md index 3795500ad1..98057d1ebd 100644 --- a/docs/build/reference/functionpadmin-create-hotpatchable-image.md +++ b/docs/build/reference/functionpadmin-create-hotpatchable-image.md @@ -1,37 +1,37 @@ --- -description: "Learn more about: /FUNCTIONPADMIN (Create Hotpatchable Image)" -title: "/FUNCTIONPADMIN (Create Hotpatchable Image)" -ms.date: "03/09/2018" -f1_keywords: ["/functionpadmin"] +description: "Learn more about: /FUNCTIONPADMIN (Create hotpatchable image)" +title: "/FUNCTIONPADMIN (Create hotpatchable image)" +ms.date: 09/09/2022 +f1_keywords: ["VC.Project.VCLinkerTool.CreateHotPatchableImage", "/functionpadmin"] helpviewer_keywords: ["-FUNCTIONPADMIN linker option", "/FUNCTIONPADMIN linker option"] ms.assetid: 25b02c13-1add-4fbd-add9-fcb30eb2cae7 --- -# /FUNCTIONPADMIN (Create Hotpatchable Image) +# `/FUNCTIONPADMIN` (Create hotpatchable image) -Prepares an image for hotpatching. +Tells the linker to prepare an executable image for hot patching. ## Syntax -> **/FUNCTIONPADMIN**[**:**_space_] +> **`/FUNCTIONPADMIN`**[**`:`***`size`*] ### Arguments -*space*
-The amount of padding to add to the beginning of each function in bytes. On x86 this defaults to 5 bytes of padding and on x64 this defaults to 6 bytes. On other targets a value must be provided. +*`size`*\ +The amount of padding to add to the beginning of each function in bytes. On x86 the default is 5 bytes of padding and on x64 the default is 6 bytes. On other targets a value must be provided. ## Remarks -In order for the linker to produce a hotpatchable image, the .obj files must have been compiled with [/hotpatch (Create Hotpatchable Image)](hotpatch-create-hotpatchable-image.md). +In order for the linker to produce a hotpatchable image, the *`.obj`* files must be compiled by using the [`/hotpatch` (Create hotpatchable image)](hotpatch-create-hotpatchable-image.md) compiler option. -When you compile and link an image with a single invocation of cl.exe, **/hotpatch** implies **/functionpadmin**. +When you compile and link an image with a single invocation of cl.exe, **`/hotpatch`** implies **`/FUNCTIONPADMIN`**. ### To set this linker option in the Visual Studio development environment -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. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). -1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. +1. Select the **Configuration Properties** > **Linker** > **General** property page. -1. Enter the **/FUNCTIONPADMIN** option in **Additional Options**. Choose **OK** to save your changes. +1. Modify the **Create Hot Patchable Image** property. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically @@ -39,5 +39,5 @@ When you compile and link an image with a single invocation of cl.exe, **/hotpat ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/gd-gr-gv-gz-calling-convention.md b/docs/build/reference/gd-gr-gv-gz-calling-convention.md index 834a53189c..50380ebb09 100644 --- a/docs/build/reference/gd-gr-gv-gz-calling-convention.md +++ b/docs/build/reference/gd-gr-gv-gz-calling-convention.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: /Gd, /Gr, /Gv, /Gz (Calling Convention)" title: "/Gd, /Gr, /Gv, /Gz (Calling Convention)" -ms.date: "09/05/2018" +description: "Learn more about: /Gd, /Gr, /Gv, /Gz (Calling Convention)" +ms.date: 09/05/2018 f1_keywords: ["/Gr", "/Gv", "/Gd", "VC.Project.VCCLCompilerTool.CallingConvention"] helpviewer_keywords: ["-Gd compiler option [C++]", "-Gv compiler option [C++]", "/Gv compiler option [C++]", "-Gr compiler option [C++]", "Gd compiler option [C++]", "Gr compiler option [C++]", "/Gz compiler option [C++]", "-Gz compiler option [C++]", "/Gd compiler option [C++]", "Gz compiler option [C++]", "Gv compiler option [C++]", "/Gr compiler option [C++]"] -ms.assetid: fd3110cb-2d77-49f2-99cf-a03f9ead00a3 --- # /Gd, /Gr, /Gv, /Gz (Calling Convention) @@ -44,7 +43,7 @@ For more information about calling conventions, see [Calling Conventions](../../ On x86 processors, all function arguments are passed on the stack from right to left. On ARM and x64 architectures, some arguments are passed by register and the rest are passed on the stack from right to left. The calling routine pops the arguments from the stack. -For C, the **`__cdecl`** naming convention uses the function name preceded by an underscore ( `_` ); no case translation is performed. Unless declared as `extern "C"`, C++ functions use a different name-decorating scheme. For more information, see [Decorated Names](decorated-names.md). +For C, the **`__cdecl`** naming convention uses the function name preceded by an underscore (`_`); no case translation is performed. Unless declared as `extern "C"`, C++ functions use a different name-decorating scheme. For more information, see [Decorated Names](decorated-names.md). ## __fastcall Specifics diff --git a/docs/build/reference/general-property-page-file.md b/docs/build/reference/general-property-page-file.md index deafd92180..f4dc2206c6 100644 --- a/docs/build/reference/general-property-page-file.md +++ b/docs/build/reference/general-property-page-file.md @@ -21,11 +21,11 @@ When you right-click on a file node **Solution Explorer**, the **General** prope - **Item Type** - The **Item Type** specifies the tool that will be used to process the file during the build process. [Files whose extension is known to Visual Studio](/visualstudio/extensibility/visual-cpp-project-extensibility#project-items) have a default value in this property. You can specify a custom tool here if you have a custom file type or wish to override the default tool for a known file type. See [Specifying Custom Build Tools](../specifying-custom-build-tools.md) for more information. You can also use this property page to specify that a file is not part of the build process. + The **Item Type** specifies the tool that will be used to process the file during the build process. [Files whose extension is known to Visual Studio](/visualstudio/extensibility/visual-cpp-project-extensibility#project-items) have a default value in this property. You can specify a custom tool here if you have a custom file type or wish to override the default tool for a known file type. For more information, see [Specifying Custom Build Tools](../specifying-custom-build-tools.md). You can also use this property page to specify that a file is not part of the build process. The following illustration shows the property page for a *.cpp* file. The default **Item Type** for this kind of file is the **C/C++ Compiler** (*cl.exe*) and the property page exposes various compiler settings that can be applied to this file only. - ![General property page for a project item](media/file-general-item-type.png "Item type choices") + ![Screenshot of the Property Pages dialog showing the General property page for a project item.](media/file-general-item-type.png "Item type choices") The following table lists the default Item Types: diff --git a/docs/build/reference/general-property-page-project.md b/docs/build/reference/general-property-page-project.md index 5749b053de..5fd0640279 100644 --- a/docs/build/reference/general-property-page-project.md +++ b/docs/build/reference/general-property-page-project.md @@ -1,205 +1,193 @@ --- description: "Learn more about: General Property Page (Project)" title: "General Property Page (Project)" -ms.date: "07/17/2019" -f1_keywords: ["VC.Project.VCConfiguration.IntermediateDirectory", "VC.Project.VCConfiguration.ConfigurationType", "VC.Project.VCConfiguration.ManagedExtensions", "VC.Project.VCConfiguration.BuildBrowserInformation", "VC.Project.VCConfiguration.BuildLogFile", "VC.Project.VCConfiguration.PlatformToolset", "VC.Project.VCConfiguration.TargetName", "VC.Project.VCConfiguration.", "VC.Project.VCConfiguration.TargetExt", "VC.Project.VCConfiguration.ATLMinimizesCRunTimeLibraryUsage", "VC.Project.VCConfiguration.ReferencesPath", "VC.Project.VCConfiguration.DeleteExtensionsOnClean", "VC.Project.VCConfiguration.useOfMfc", "VC.Project.VCConfiguration.CharacterSet", "VC.Project.VCGeneralMakefileSettings.ConfigurationType", "VC.Project.VCConfiguration.OutputDirectory", "VC.Project.VCConfiguration.AppSupport", "VC.Project.VCConfiguration.ToolFiles", "VC.Project.VCConfiguration.useOfATL"] +ms.date: 05/28/2021 +f1_keywords: ["VC.Project.VCConfiguration.IntermediateDirectory", "VC.Project.VCConfiguration.ConfigurationType", "VC.Project.VCConfiguration.BuildBrowserInformation", "VC.Project.VCConfiguration.PlatformToolset", "VC.Project.VCConfiguration.TargetName", "VC.Project.VCConfiguration.", "VC.Project.VCConfiguration.ATLMinimizesCRunTimeLibraryUsage", "VC.Project.VCConfiguration.ReferencesPath", "VC.Project.VCGeneralMakefileSettings.ConfigurationType", "VC.Project.VCConfiguration.OutputDirectory", "VC.Project.VCConfiguration.AppSupport", "VC.Project.VCConfiguration.ToolFiles", "VC.Project.VCConfiguration.useOfATL", "VC.Project.VCConfiguration.DesktopCompatible"] helpviewer_keywords: ["Clean Build option", "output files, setting directory", "Unicode, creating C++ build configuration"] --- # General Property Page (Project) -::: moniker range=">=msvc-160" - -This topic applies to Visual Studio projects for Windows. For Linux projects, see [Linux C++ Property Page Reference](../../linux/prop-pages-linux.md). For CMake projects, see [CMake projects in Visual Studio](../cmake-projects-in-visual-studio.md). For Android projects, see [General Project Properties (Android C++)](../../cross-platform/general-android-prop-page.md). For Android Makefile projects, see [General Project Properties (Android C++ Makefile)](../../cross-platform/general-makefile-android-prop-page.md) - -When you right-click on a project node in Solution Explorer, and select **Properties**, the **General** property page under the **Configuration Properties** node in the left pane displays these properties: - -- **Output Directory** - - Specifies the directory where tools such as the linker will place all final output files that are created during the build process. Typically, this includes the output of tools such as the linker, librarian, or BSCMake. By default, this property is the directory specified by the macros $(SolutionDir)$(Configuration)\. - - To programmatically access this property, see . +This article applies to Visual Studio projects for Windows. For Linux projects, see [Linux C++ Property page reference](../../linux/prop-pages-linux.md). For CMake projects, see [CMake projects in Visual Studio](../cmake-projects-in-visual-studio.md). For Android projects, see [General project properties (Android C++)](../../cross-platform/general-android-prop-page.md). For Android Makefile projects, see [General project properties (Android C++ Makefile)](../../cross-platform/general-makefile-android-prop-page.md). In Visual Studio 2019, some properties for non-UWP (Windows Runtime or Universal Windows Platform) projects have moved to the [Advanced property page](./advanced-property-page.md). -- **Intermediate Directory** +To open the Property Pages dialog for a project, select the project (not the solution) in Solution Explorer. Next, select the **Project** > **Project-name Properties** menu from the menu bar. Or, right-click on the project node in Solution Explorer and select **Properties** from the shortcut menu. - Specifies the directory where tools such as the compiler will place all intermediate files created during the build process. Typically, this includes the output of tools such as the C/C++ compiler, MIDL, and the resource compiler. By default, this property is the directory specified by the macro $(Configuration)\. +In the Property Pages dialog, the **Configuration Properties** > **General** property page displays project properties based on project type. These properties are gathered under one or two headings, depending on project type: - To programmatically access this property, see . - -- **Target Name** +- General - Specifies the file name this project generates. By default, this property is the filename specified by the macro $(ProjectName). +- Project Defaults -- **Configuration Type** +## General - There are several configuration types from which to choose: +The General property heading includes some combination of these properties: - - **Application (.exe)** +### Target Platform - Displays linker toolset (C/C++ Compiler, MIDL, Resource Compiler, Linker, BSCMake, XML Web Service Proxy Generator, custom build, prebuild, prelink, postbuild events). +Specifies the platform that the project runs on. For example, Windows, Android, or iOS. The value **Windows 10** means the project targets the Universal Windows Platform. If you're targeting other versions of Windows, the version isn't listed and the value in this field appears as just **Windows**. This property is a read-only field that's set when you create a project. - - **Dynamic Library (.dll)** +### Target Platform Version - Displays linker toolset, specifies /DLL linker option, and adds the _WINDLL define to CL. +Specifies the version of the Windows SDK used to build the project. This property appears only if the project type supports it. You can select 10.0 to specify the latest version of the Windows SDK. If your app can take advantage of features in this Windows SDK version, but can still run on earlier versions without those features, perhaps with some loss of functionality, then the value of this property and the **Target Platform Min. Version** property might be different. If so, your code should check the version of the platform it's running against at runtime and disable features that aren't available in older platform versions. - - **Makefile** +### Target Platform Min. Version - Displays makefile toolset (NMake). +Specifies the lowest version of the platform that the project can run on. This property appears only if the project type supports it. Set this value if your app can take advantage of features in a newer Windows SDK version, but still runs on earlier versions, perhaps with some loss of functionality. If set to a lower value, your code should check the version of the platform it's running against at runtime. Then, disable features that aren't available in older platform versions. - - **Static Library (.lib)** +The C++ project system doesn't enforce this option. It's included for consistency with other languages, such as C# and JavaScript, and as a guide for anyone who uses your project. Microsoft C++ won't generate an error if you use a feature that's not available in the minimum version. - Displays librarian toolset (same as linker toolset except substitute librarian for linker and omit XML Web Service Proxy Generator). +### Windows SDK Version - - **Utility** +For the Windows target platform, this property specifies the version of the Windows SDK that your project requires. When the Visual Studio Installer installs a C++ Workload, it also installs the required parts of the Windows SDK. If you have other Windows SDK versions on your computer, each version installed appears in the dropdown. - Displays utility toolset (MIDL, custom build, prebuild, postbuild events). +To target Windows 7 or Windows Vista, use the value **8.1**, since Windows SDK 8.1 is backward compatible to those platforms. When you target an earlier version, define the appropriate value for `_WIN32_WINNT` in *`targetver.h`*. For Windows 7, that's 0x0601. For more information, see [Modifying `WINVER` and `_WIN32_WINNT`](../../porting/modifying-winver-and-win32-winnt.md). - To programmatically access this property, see . +You can install the Windows XP platform toolset included as an optional component in Visual Studio Installer to build Windows XP and Windows 2003 Server projects. For information on how to obtain and use this platform toolset, see [Configuring programs for Windows XP](../configuring-programs-for-windows-xp.md). For more information on changing the platform toolset, see [How to: Modify the target framework and platform toolset](../how-to-modify-the-target-framework-and-platform-toolset.md). -- **Windows SDK Version** +### Output Directory - For the Windows target platform, this specifies the version of the Windows SDK that your project requires. When you install a C++ Workload by using the Visual Studio installer, the required parts of the Windows SDK are also installed. If you have other Windows SDK versions on your computer, each version of the SDK tools that you have installed appears in the dropdown. +Specifies the directory where build tools such as the linker place all final output files created during the build process. Typically, this directory holds the output of tools such as the linker, librarian, or BSCMake. By default, this property is the directory specified by the macro combination `$(SolutionDir)$(Configuration)\`. - To target Windows 7 or Windows Vista, use the value **8.1**, since Windows SDK 8.1 is backward compatible to those platforms. In addition, you should define the appropriate value for **_WIN32_WINNT** in targetver.h. For Windows 7, that's 0x0601. See [Modifying WINVER and _WIN32_WINNT](../../porting/modifying-winver-and-win32-winnt.md). +To programmatically access this property, see . - You can install the Windows XP platform toolset included in Visual Studio to use the current version of the libraries to build Windows XP and Windows 2003 Server projects. For information on how to obtain and use this platform toolset, see [Configuring Programs for Windows XP](../configuring-programs-for-windows-xp.md). For additional information on changing the platform toolset, see [How to: Modify the Target Framework and Platform Toolset](../how-to-modify-the-target-framework-and-platform-toolset.md). +### Intermediate Directory -- **Platform Toolset** +Specifies the directory where tools such as the compiler place all intermediate files created during the build process. Typically, this directory holds the output of tools such as the C/C++ compiler, MIDL, and the resource compiler. By default, this property is the directory specified by the macro `$(Configuration)\`. - Allows the project to target a different version of the Visual C++ libraries and compiler. Visual Studio C++ projects can target either the default toolset installed by Visual Studio, or one of the toolsets installed by several previous versions of Visual Studio, including toolsets that create executables that can run on Windows XP. For information on changing the platform toolset, see [How to: Modify the Target Framework and Platform Toolset](../how-to-modify-the-target-framework-and-platform-toolset.md). +To programmatically access this property, see . -- **C++ Language Standard** +### Target Name - Specifies which language standard to use. The default is /std:c++14. Specify /std:c++17 to use C++17 features, or /std:c+++latest to use C++20 or other experimental features. For more information, see [/std (Specify Language Standard Version)](std-specify-language-standard-version.md) +Specifies the file name this project generates. By default, this property is the filename specified by the macro `$(ProjectName)`. -::: moniker-end +### Target Extension -::: moniker range="<=msvc-150" +Specifies the file extension this project generates, such as *`.exe`* or *`.dll`*. For some Visual Studio 2019 project types, this property has moved to the [Advanced property page](./advanced-property-page.md). -In Visual Studio 2015 and Visual Studio 2017, when you right-click on a project node in **Solution Explorer**, and select **Properties**, the **General** property page under the **Configuration Properties** node in the left pane displays two sections of properties: +### Extensions to Delete on Clean -- General +The **Build** > **Clean** menu command deletes files from the intermediate directory where a project's configuration is built. The build system deletes files that have the specified extensions when you run the **Clean** command or when you rebuild. The build system also deletes any known output of the build no matter where it's located. Deleted files include any intermediate outputs such as *`.obj`* files. Use semicolons (**`;`**) to separate extensions. You can specify wildcard characters (**`*`**, **`?`**) in the extensions. -- Project Defaults +To programmatically access this property, see . For some Visual Studio 2019 project types, this property has moved to the [Advanced property page](./advanced-property-page.md). -## General +### Build Log File -- **Target Platform** +Allows you to specify a non-default location for the log file that's created whenever you build a project. The default location is specified by the macro combination `$(IntDir)$(MSBuildProjectName).log`. For some Visual Studio 2019 project types, this property has moved to the [Advanced property page](./advanced-property-page.md). - Specifies the platform that the project will run on. For example, Windows, Android, or iOS. The value **Windows 10** means the project targets the Universal Windows Platform. If you are targeting earlier versions of Windows, the version is not listed and the value in this field appears as just **Windows**. This is a read-only field that is set when you create a project. +You can use project macros to change the directory location. For more information, see [Common macros for build commands and properties](common-macros-for-build-commands-and-properties.md). -- **Target Platform Version (Visual Studio 2015)** +### Platform Toolset - Specifies the lowest version of the platform that the project can run on. This property appears only if the project type supports it. If your app can take advantage of features in a newer Windows SDK version, but can still run on earlier versions without those features, perhaps with some loss of functionality, then the value of these two properties might be different. If so, your code should check the version of the platform it is running against at runtime and not try to use features that aren't available in older platform version. +Specifies the toolset used for building the current configuration. This property allows the project to target a different version of the Visual C++ libraries and compiler. By default, Visual Studio C++ projects target the latest toolset installed by Visual Studio. You can choose one of the toolsets installed by several previous versions of Visual Studio instead. Some older toolsets can create executables that run on Windows XP or Vista. For more information on how to change the platform toolset, see [How to: Modify the target framework and platform toolset](../how-to-modify-the-target-framework-and-platform-toolset.md). - The C++ project system does not enforce this option. It is included for consistency with other languages, such as C# and JavaScript, and as a guide for anyone who uses your project. Visual C++ won't generate an error if you use a feature that is not available in the minimum version. +### Enable Managed Incremental Build -- **Windows SDK Version (Visual Studio 2017)** +For managed projects, this property enables detection of external visibility when you generate assemblies. If a change to a managed project isn't visible to other projects, then dependent projects don't get rebuilt. This option can dramatically improve build times in solutions that include managed projects. In Visual Studio 2019 projects, this property has moved to the [Advanced property page](./advanced-property-page.md). - For the Windows target platform, this specifies the version of the Windows SDK that your project requires. When you install a C++ Workload by using the Visual Studio installer, the required parts of the Windows SDK are also installed. If you have other Windows SDK versions on your computer, each version of the SDK tools that you have installed appears in the dropdown. +::: moniker range=">=msvc-160" - To target Windows 7 or Windows Vista, use the value **8.1**, since Windows SDK 8.1 is backward compatible to those platforms. In addition, you should define the appropriate value for **_WIN32_WINNT** in targetver.h. For Windows 7, that's 0x0601. See [Modifying WINVER and _WIN32_WINNT](../../porting/modifying-winver-and-win32-winnt.md). +### Configuration Type - You can install the Windows XP platform toolset included in Visual Studio to use the current version of the libraries to build Windows XP and Windows 2003 Server projects. For information on how to obtain and use this platform toolset, see [Configuring Programs for Windows XP](../configuring-programs-for-windows-xp.md). For additional information on changing the platform toolset, see [How to: Modify the Target Framework and Platform Toolset](../how-to-modify-the-target-framework-and-platform-toolset.md). +Specifies the project output and its required tools. In UWP projects, this property appears under the **Project Defaults** heading. There are several configuration types from which to choose, depending on your project type: -- **Output Directory** +#### Application (.exe) - Specifies the directory where tools such as the linker will place all final output files that are created during the build process. Typically, this includes the output of tools such as the linker, librarian, or BSCMake. By default, this property is the directory specified by the macros $(SolutionDir)$(Configuration)\. +Displays the linker toolset: The C/C++ Compiler, MIDL, Resource Compiler, Linker, BSCMake, XML Web Service Proxy Generator, custom build, prebuild, prelink, and postbuild events. - To programmatically access this property, see . +#### Dynamic Library (.dll) -- **Intermediate Directory** +Displays the linker toolset, specifies the **`/DLL`** linker option, and adds the `_WINDLL` preprocessor definition to the CL command line. - Specifies the directory where tools such as the compiler will place all intermediate files created during the build process. Typically, this includes the output of tools such as the C/C++ compiler, MIDL, and the resource compiler. By default, this property is the directory specified by the macro $(Configuration)\. +#### Makefile - To programmatically access this property, see . +Displays the makefile toolset (NMake). -- **Target Name** +#### Static Library (.lib) - Specifies the file name this project generates. By default, this property is the filename specified by the macro $(ProjectName). +Displays the librarian toolset. It's the same as the linker toolset, except it replaces the linker with the librarian and omits XML Web Service Proxy Generator. -- **Target Extension** +#### Utility - Specifies the file name extension this project generates; for example, .exe or .dll. +Displays the utility toolset (MIDL, custom build, prebuild, and postbuild events). -- **Extensions to Delete on Clean** +To programmatically access this property, see . - The **Clean** option (**Build** menu) deletes files from the intermediate directory where a project's configuration is built. Files with extensions specified with this property will be deleted when **Clean** is run or when you perform a rebuild. In addition to files of these extensions in the intermediate directory, the build system will also delete any known output of the build regardless of where it is located (including intermediate outputs such as .obj files). Note that you can specify wildcard characters. +### C++ Language Standard - To programmatically access this property, see . +Specifies which C++ language standard to use. The default is **`/std:c++14`**. Specify **`/std:c++17`** to use C++17 features, **`/std:c++20`** to use C++20 features, and **`/std:c++latest`** to use proposed C++23 features or other experimental features. For more information, see [`/std` (Specify language standard version)](std-specify-language-standard-version.md). -- **Build Log File** +### C Language Standard - Allows you to specify a non-default location for the log file that is created whenever you build a project. The default location is specified by the macros $(IntDir)$(MSBuildProjectName).log. +Specifies which C language standard to use. The default is Legacy MSVC, which implements C89, some of C99, and Microsoft-specific extensions. Specify **`/std:c11`** to use C11 features, and **`/std:c17`** to use C17 features. For more information, see [`/std` (Specify language standard version)](std-specify-language-standard-version.md) - You can use project macros to change the directory location. See [Common macros for build commands and properties](common-macros-for-build-commands-and-properties.md). +::: moniker-end -- **Platform Toolset** +## Project Defaults - Allows the project to target a different version of the Visual C++ libraries and compiler. Visual Studio C++ projects can target either the default toolset installed by Visual Studio, or one of the toolsets installed by several previous versions of Visual Studio, including toolsets that create executables that can run on Windows XP. For information on changing the platform toolset, see [How to: Modify the Target Framework and Platform Toolset](../how-to-modify-the-target-framework-and-platform-toolset.md). +::: moniker range="<=msvc-150" -- **Enable Managed Incremental Build** +### Configuration Type - For managed projects, this enables detection of external visibility when you generate assemblies. If a change to a managed project is not visible to other projects, then dependent projects are not rebuilt. This can dramatically improve build times in solutions that include managed projects. +Specifies the project output and its required tools. In UWP projects, this property appears under the **Project Defaults** heading. There are several configuration types from which to choose, depending on your project type: -## Project Defaults +#### Application (.exe) -The properties in the Project Default section represent default properties that you can modify. The definition for these properties can be found in the .props files in *Installation Directory*\VC\VCProjectDefaults. +Displays the linker toolset: The C/C++ Compiler, MIDL, Resource Compiler, Linker, BSCMake, XML Web Service Proxy Generator, custom build, prebuild, prelink, and postbuild events. -- **Configuration Type** +#### Dynamic Library (.dll) - There are several configuration types from which to choose: +Displays the linker toolset, specifies the **`/DLL`** linker option, and adds the `_WINDLL` preprocessor definition to the CL command line. - - **Application (.exe)** +#### Makefile - Displays linker toolset (C/C++ Compiler, MIDL, Resource Compiler, Linker, BSCMake, XML Web Service Proxy Generator, custom build, prebuild, prelink, postbuild events). +Displays the makefile toolset (NMake). - - **Dynamic Library (.dll)** +#### Static Library (.lib) - Displays linker toolset, specifies /DLL linker option, and adds the _WINDLL define to CL. +Displays the librarian toolset. It's the same as the linker toolset, except it replaces the linker with the librarian and omits XML Web Service Proxy Generator. - - **Makefile** +#### Utility - Displays makefile toolset (NMake). +Displays the utility toolset (MIDL, custom build, prebuild, and postbuild events). - - **Static Library (.lib)** +To programmatically access this property, see . - Displays librarian toolset (same as linker toolset except substitute librarian for linker and omit XML Web Service Proxy Generator). +::: moniker-end - - **Utility** +### Use of MFC - Displays utility toolset (MIDL, custom build, prebuild, postbuild events). +Specifies whether the MFC project statically or dynamically links to the MFC DLL. Non-MFC projects select **Use Standard Windows Libraries**. In Visual Studio 2019 projects, this property has moved to the [Advanced property page](./advanced-property-page.md). - To programmatically access this property, see . +To programmatically access this property, see . -- **Use of MFC** +### Character Set - Specifies whether the MFC project will statically or dynamically link to the MFC DLL. Non-MFC projects can select **Use Standard Windows Libraries** to link to various Win32 libraries that are included when you use MFC. +Specifies whether the `_UNICODE` or `_MBCS` preprocessor macro should be set. Also affects the linker entry point, where appropriate. In Visual Studio 2019 projects, this property has moved to the [Advanced property page](./advanced-property-page.md). - To programmatically access this property, see . +To programmatically access this property, see . -- **Character Set** +### Common Language Runtime support - Defines whether _UNICODE or _MBCS should be set. Also affects the linker entry point where appropriate. +Causes the [`/clr`](clr-common-language-runtime-compilation.md) compiler option to be used. In Visual Studio 2019 projects, this property has moved to the [Advanced property page](./advanced-property-page.md). - To programmatically access this property, see . +To programmatically access this property, see . -- **Common Language Runtime support** +### .NET Target Framework Version - Causes the [/clr](clr-common-language-runtime-compilation.md) compiler option to be used. +In managed projects, specifies the .NET framework version to target. In Visual Studio 2019 projects, this property has moved to the [Advanced property page](./advanced-property-page.md). - To programmatically access this property, see . +### Whole Program Optimization -- **.NET Target Framework Version** +Specifies the [`/GL`](gl-whole-program-optimization.md) compiler option and [`/LTCG`](ltcg-link-time-code-generation.md) linker option. By default, this property is disabled for Debug configurations, and enabled for Release configurations. In Visual Studio 2019 projects, this property has moved to the [Advanced property page](./advanced-property-page.md). - In managed projects, specifies the .NET framework version to target. +### Windows Store App Support -- **Whole Program Optimization** +Specifies whether this project supports Windows Runtime (Universal Windows Platform or UWP) apps. For more information, see [`/ZW` (Windows Runtime Compilation)](zw-windows-runtime-compilation.md), and the Windows Developer [UWP documentation](/windows/uwp/). - Specifies the [/GL](gl-whole-program-optimization.md) compiler option and [/LTCG](ltcg-link-time-code-generation.md) linker option. By default, this is disabled for Debug configurations, and enabled for Retail configurations. +::: moniker range=">=msvc-160" -- **Windows Store App Support** +### Windows Desktop Compatible - Specifies whether this project supports Windows Runtime (Universal Windows Platform) apps. For more information, see [/ZW (Windows Runtime Compilation)](zw-windows-runtime-compilation.md), and the Windows Developer Center. +Enables the output of this Windows Runtime project to also support desktop apps. This property sets the `` value in the project file. The **Windows Desktop Compatible** property is available starting in Visual Studio 2019 version 16.9. ::: moniker-end diff --git a/docs/build/reference/genprofile-fastgenprofile-generate-profiling-instrumented-build.md b/docs/build/reference/genprofile-fastgenprofile-generate-profiling-instrumented-build.md index e77bc2bfd9..37657efee2 100644 --- a/docs/build/reference/genprofile-fastgenprofile-generate-profiling-instrumented-build.md +++ b/docs/build/reference/genprofile-fastgenprofile-generate-profiling-instrumented-build.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: /GENPROFILE, /FASTGENPROFILE (Generate Profiling Instrumented Build)" title: "/GENPROFILE, /FASTGENPROFILE (Generate Profiling Instrumented Build)" -ms.date: 04/14/2021 +description: "Learn more about: /GENPROFILE, /FASTGENPROFILE (Generate Profiling Instrumented Build)" +ms.date: 03/27/2025 f1_keywords: ["GENPROFILE", "FASTGENPROFILE", "/GENPROFILE", "/FASTGENPROFILE"] helpviewer_keywords: ["GENPROFILE", "FASTGENPROFILE"] --- @@ -12,7 +12,7 @@ Specifies generation of a *`.pgd`* file by the linker to support profile-guided ## Syntax > **`/GENPROFILE`**\[**`:`**_`profile-argument`_\[**`,`**_`profile-argument`_ ...]]\ -> **`/FASTGENPROFILE`**\[**`:`**_`profile-argument`_\[**`,`**_`profile-argument`_ ...]]\ +> **`/FASTGENPROFILE`**\[**`:`**_`profile-argument`_\[**`,`**_`profile-argument`_ ...]] > *`profile-argument`*\ >  { **`COUNTER32`** | **`COUNTER64`** }\ @@ -43,7 +43,7 @@ Use **`PATH`** to specify a separate set of PGO counters for each unique path t Specifies whether to use extra counters to keep an accurate count when exceptions are thrown during training. Use **`TRACKEH`** to specify extra counters for an exact count. Use **`NOTRACKEH`** to specify single counters for code that doesn't use exception handling or that doesn't run into exceptions in your training scenarios. When you specify **`/GENPROFILE`**, the default is **`TRACKEH`** . When you specify **`/FASTGENPROFILE`**, the default is **`NOTRACKEH`** . **`PGD`**=*filename*\ -Specifies a base file name for the *`.pgd`* file. By default, the linker uses the base executable image file name with a *`.pgd`* extension. +Specifies a base filename for the *`.pgd`* file. By default, the linker uses the base executable image filename with a *`.pgd`* extension. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). ## Remarks diff --git a/docs/build/reference/gh-enable-penter-hook-function.md b/docs/build/reference/gh-enable-penter-hook-function.md index 12a83774da..fbf4459ec3 100644 --- a/docs/build/reference/gh-enable-penter-hook-function.md +++ b/docs/build/reference/gh-enable-penter-hook-function.md @@ -1,7 +1,7 @@ --- title: "/Gh (Enable _penter hook function)" description: "Describes the /Gh compiler option to call the supplied _penter function." -ms.date: "07/06/2020" +ms.date: 06/29/2022 f1_keywords: ["_penter"] helpviewer_keywords: ["/Gh compiler option [C++]", "Gh compiler option [C++]", "_penter function", "-Gh compiler option [C++]"] ms.assetid: 1510a082-8a0e-486e-a309-6add814b494f @@ -42,6 +42,8 @@ This declaration isn't available for 64-bit projects. The following code, when compiled with **/Gh**, shows how `_penter` is called twice; once when entering function `main` and once when entering function `x`. The example consists of two source files, which you compile separately. +Source file `local_penter.cpp`: + ```cpp // local_penter.cpp // compile with: cl /EHsc /c local_penter.cpp @@ -74,6 +76,8 @@ extern "C" void __declspec(naked) __cdecl _penter( void ) { } ``` +Source file `Gh_compiler_option.cpp`: + ```cpp // Gh_compiler_option.cpp // compile with: cl /EHsc /Gh Gh_compiler_option.cpp local_penter.obj @@ -90,7 +94,6 @@ int main() { When run, the local `_penter` function is called on entry to `main` and `x`: ```Output - In a function! In a function! ``` diff --git a/docs/build/reference/gs-buffer-security-check.md b/docs/build/reference/gs-buffer-security-check.md index 227124b814..41fe1b082c 100644 --- a/docs/build/reference/gs-buffer-security-check.md +++ b/docs/build/reference/gs-buffer-security-check.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: /GS (Buffer Security Check)" title: "/GS (Buffer Security Check)" -ms.date: "11/04/2016" +description: "Learn more about: /GS (Buffer Security Check)" +ms.date: 11/04/2016 f1_keywords: ["VC.Project.VCCLWCECompilerTool.BufferSecurityCheck", "VC.Project.VCCLCompilerTool.BufferSecurityCheck"] helpviewer_keywords: ["buffers [C++], buffer overruns", "buffer overruns, compiler /GS switch", "GS compiler option [C++]", "/GS compiler option [C++]", "security check compiler option [C++]", "-GS compiler option [C++]", "buffers [C++], avoiding overruns"] -ms.assetid: 8d8a5ea1-cd5e-42e1-bc36-66e1cd7e731e --- # /GS (Buffer Security Check) @@ -29,11 +28,8 @@ On functions that the compiler recognizes as subject to buffer overrun problems, A buffer overrun security check is performed on a *GS buffer*. A GS buffer can be one of these: - An array that is larger than 4 bytes, has more than two elements, and has an element type that is not a pointer type. - - A data structure whose size is more than 8 bytes and contains no pointers. - -- A buffer allocated by using the [_alloca](../../c-runtime-library/reference/alloca.md) function. - +- A buffer allocated by using the [`_alloca`](../../c-runtime-library/reference/alloca.md) function. - Any class or structure that contains a GS buffer. For example, the following statements declare GS buffers. @@ -57,16 +53,14 @@ struct { int a; int b; }; ## Initialize the Security Cookie -The **/GS** compiler option requires that the security cookie be initialized before any function that uses the cookie is run. The security cookie must be initialized immediately on entry to an EXE or DLL. This is done automatically if you use the default VCRuntime entry points: mainCRTStartup, wmainCRTStartup, WinMainCRTStartup, wWinMainCRTStartup, or _DllMainCRTStartup. If you use an alternate entry point, you must manually initialize the security cookie by calling [__security_init_cookie](../../c-runtime-library/reference/security-init-cookie.md). +The **/GS** compiler option requires that the security cookie be initialized before any function that uses the cookie is run. The security cookie must be initialized immediately on entry to an EXE or DLL. This is done automatically if you use the default VCRuntime entry points: `mainCRTStartup`, `wmainCRTStartup`, `WinMainCRTStartup`, `wWinMainCRTStartup`, or `_DllMainCRTStartup`. If you use an alternate entry point, you must manually initialize the security cookie by calling [`__security_init_cookie`](../../c-runtime-library/reference/security-init-cookie.md). ## What Is Protected The **/GS** compiler option protects the following items: - The return address of a function call. - - The address of an exception handler for a function. - - Vulnerable function parameters. On all platforms, **/GS** attempts to detect buffer overruns into the return address. Buffer overruns are more easily exploited on platforms such as x86 and x64, which use calling conventions that store the return address of a function call on the stack. @@ -80,15 +74,10 @@ A vulnerable parameter is allocated before the cookie and local variables. A buf The compiler does not make copies of vulnerable parameters in the following situations: - Functions that do not contain a GS buffer. - -- Optimizations ([/O options](o-options-optimize-code.md)) are not enabled. - +- Optimizations ([`/O` options](o-options-optimize-code.md)) are not enabled. - Functions that have a variable argument list (...). - - Functions that are marked with [naked](../../cpp/naked-cpp.md). - - Functions that contain inline assembly code in the first statement. - - A parameter is used only in ways that are less likely to be exploitable in the event of a buffer overrun. ## What Is Not Protected @@ -100,9 +89,7 @@ Even if you use **/GS**, always try to write secure code that has no buffer over ### 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++** > **Code Generation** property page. - 1. Modify the **Buffer Security Check** property. ### To set this compiler option programmatically @@ -138,5 +125,5 @@ int main() { ## See also -[MSVC Compiler Options](compiler-options.md)
+[MSVC Compiler Options](compiler-options.md)\ [MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/gs-control-stack-checking-calls.md b/docs/build/reference/gs-control-stack-checking-calls.md index f681a54a15..4e1ff0eb87 100644 --- a/docs/build/reference/gs-control-stack-checking-calls.md +++ b/docs/build/reference/gs-control-stack-checking-calls.md @@ -1,44 +1,44 @@ --- description: "Learn more about: /Gs (Control Stack Checking Calls)" title: "/Gs (Control Stack Checking Calls)" -ms.date: "10/25/2018" +ms.date: 02/16/2023 f1_keywords: ["/GS"] helpviewer_keywords: ["disabling stack probes", "GS compiler option [C++]", "/GS compiler option [C++]", "stack, stack probes", "stack probes", "-GS compiler option [C++]", "stack checking calls"] ms.assetid: 40daed7c-f942-4085-b872-01e12b37729e --- -# /Gs (Control Stack Checking Calls) +# `/Gs` (Control stack checking calls) Controls the threshold for stack probes. ## Syntax -> **/Gs**[*size*] +> **`/Gs`**[*`size`*] ## Arguments -*size*
-(Optional) The number of bytes that local variables can occupy before a stack probe is initiated. No space is allowed between **/Gs** and *size*. +*`size`*\ +(Optional) The number of bytes that local variables can occupy before a stack probe is initiated. No whitespace is allowed between **`/Gs`** and *`size`*. ## Remarks -A *stack probe* is a sequence of code that the compiler inserts at the beginning of a function call. When initiated, a stack probe reaches benignly into memory by the amount of space that is required to store the function's local variables. This causes the operating system to transparently page in additional stack memory if required, before the rest of the function runs. +A *stack probe* is a sequence of code that the compiler inserts at the beginning of a function call. When initiated, a stack probe reaches benignly into memory by the amount of space required to store the function's local variables. This probe causes the operating system to transparently page in more stack memory if necessary, before the rest of the function runs. -By default, the compiler generates code that initiates a stack probe when a function requires more than one page of stack space. This is equivalent to a compiler option of **/Gs4096** for x86, x64, ARM, and ARM64 platforms. This value allows an application and the Windows memory manager to increase the amount of memory committed to the program stack dynamically at run time. +By default, the compiler generates code that initiates a stack probe when a function requires more than one page of stack space. This default is equivalent to a compiler option of **`/Gs4096`** for x86, x64, ARM, and ARM64 platforms. This value allows an application and the Windows memory manager to increase the amount of memory committed to the program stack dynamically at run time. > [!NOTE] -> The default value of **/Gs4096** allows the program stack of applications for Windows to grow correctly at run time. We recommend that you do not change the default value unless you know exactly why you have to change it. +> The default value of **`/Gs4096`** allows the program stack of applications for Windows to grow correctly at run time. We recommend that you do not change the default value unless you know exactly why you have to change it. -Some programs—for example, virtual device drivers—do not require this default stack-growth mechanism. In such cases, the stack probes are not necessary and you can stop the compiler from generating them by setting *size* to a value that is larger than any function will require for local variable storage. +Some programs—for example, virtual device drivers—don't require this default stack-growth mechanism. In such cases, the stack probes aren't necessary and you can stop the compiler from generating them by setting *`size`* to a value that is larger than any function requires for local variable storage. -**/Gs0** initiates stack probes for every function call that requires storage for local variables. This can have a negative impact on performance. +**`/Gs0`** initiates stack probes for every function call that requires storage for local variables. This value can have a negative impact on performance. -For x64 targets, if the **/Gs** option is specified without a *size* argument, it is the same as **/Gs0**. If the *size* argument is 1 through 9, warning D9014 is emitted, and the effect is the same as specifying **/Gs0**. +For x64 targets, if you specify the **`/Gs`** option without a *`size`* argument, it's the same as **`/Gs0`**. If the *`size`* argument is 1 through 9, the compiler emits warning D9014, and the effect is the same as specifying **`/Gs0`**. -For x86, ARM, and ARM64 targets, the **/Gs** option without a *size* argument is the same as **/Gs4096**. If the *size* argument is 1 through 9, warning D9014 is emitted, and the effect is the same as specifying **/Gs4096**. +For x86, ARM, and ARM64 targets, the **`/Gs`** option without a *`size`* argument is the same as **`/Gs4096`**. If the *`size`* argument is 1 through 9, the compiler emits warning D9014, and the effect is the same as specifying **`/Gs4096`**. -For all targets, a *size* argument between 10 and 2147485647 sets the threshold at the specified value. A *size* of 2147485648 or greater causes fatal error C1049. +For all targets, a *`size`* argument between 10 and 2147483647 sets the threshold at the specified value. A *`size`* of 2147483648 or greater causes fatal error C1049. -You can turn stack probes on or off by using the [check_stack](../../preprocessor/check-stack.md) directive. **/Gs** and the `check_stack` pragma have no effect on standard C library routines; they affect only the functions you compile. +You can turn stack probes on or off by using the [`check_stack`](../../preprocessor/check-stack.md) directive. **`/Gs`** and the `check_stack` pragma have no effect on standard C library routines; they affect only the functions you compile. ### To set this compiler option in the Visual Studio development environment @@ -54,5 +54,5 @@ You can turn stack probes on or off by using the [check_stack](../../preprocesso ## See also -[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/guard-enable-control-flow-guard.md b/docs/build/reference/guard-enable-control-flow-guard.md index b4d970ac8c..61a24b9f5a 100644 --- a/docs/build/reference/guard-enable-control-flow-guard.md +++ b/docs/build/reference/guard-enable-control-flow-guard.md @@ -1,47 +1,48 @@ --- description: "Learn more about: /guard (Enable Control Flow Guard)" title: "/guard (Enable Control Flow Guard)" -ms.date: "11/04/2016" +ms.date: 2/24/2025 f1_keywords: ["/guard", "VC.Project.VCCLCompilerTool.ControlFlowGuard"] -ms.assetid: be495323-f59f-4cf3-a6b6-8ee69e6a19dd --- -# /guard (Enable Control Flow Guard) +# `/guard` (Enable Control Flow Guard) Enable compiler generation of Control Flow Guard security checks. ## Syntax -``` -/guard:cf[-] -``` +> **`/guard:cf`**\ +> **`/guard:cf-`** ## Remarks -The **/guard:cf** option causes the compiler to analyze control flow for indirect call targets at compile time, and then to insert code to verify the targets at runtime. By default, **/guard:cf** is off and must be explicitly enabled. To explicitly disable this option, use **/guard:cf-**. +The **`/guard:cf`** option causes the compiler to analyze control flow for indirect call targets at compile time, and inserts code at runtime to verify the targets. By default, **`/guard:cf`** is off and must be explicitly enabled. To explicitly disable this option, use **`/guard:cf-`**. **Visual Studio 2017 and later**: This option adds guards for **`switch`** statements that generate jump tables. -When the **/guard:cf** Control Flow Guard (CFG) option is specified, the compiler and linker insert extra runtime security checks to detect attempts to compromise your code. During compiling and linking, all indirect calls in your code are analyzed to find every location that the code can reach when it runs correctly. This information is stored in extra structures in the headers of your binaries. The compiler also injects a check before every indirect call in your code that ensures the target is one of the verified locations. If the check fails at runtime on a CFG-aware operating system, the operating system closes the program. +When the **`/guard:cf`** Control Flow Guard (CFG) option is specified, the compiler and linker insert extra runtime security checks to detect attempts to compromise your code. During compiling and linking, all indirect calls in your code are analyzed to find every location that the code can reach when it runs correctly. This information is stored in extra structures in the headers of your binaries. The compiler also injects a check before every indirect call in your code that ensures the target is one of the verified locations. If the check fails at runtime on a CFG-aware operating system, the operating system closes the program. -A common attack on software takes advantage of bugs in handling extreme or unexpected inputs. Carefully crafted input to the application may overwrite a location that contains a pointer to executable code. This can be used to redirect control flow to code controlled by the attacker. The CFG runtime checks do not fix the data corruption bugs in your executable. They instead make it more difficult for an attacker to use them to execute arbitrary code. CFG is a mitigation tool that prevents calls to locations other than function entry points in your code. It's similar to how Data Execution Prevention (DEP), [/GS](gs-buffer-security-check.md) stack checks, and [/DYNAMICBASE](dynamicbase-use-address-space-layout-randomization.md) and [/HIGHENTROPYVA](highentropyva-support-64-bit-aslr.md) address space layout randomization (ASLR) lower the chances that your code becomes an exploit vector. +A common attack on software takes advantage of bugs in handling extreme or unexpected inputs. Carefully crafted input to the application may overwrite a location that contains a pointer to executable code. This technique can be used to redirect control flow to code controlled by the attacker. The CFG runtime checks don't fix the data corruption bugs in your executable. They instead make it more difficult for an attacker to use them to execute arbitrary code. CFG is a mitigation tool that prevents calls to locations other than function entry points in your code. It's similar to how Data Execution Prevention (DEP), [/GS](gs-buffer-security-check.md) stack checks, and [`/DYNAMICBASE`](dynamicbase-use-address-space-layout-randomization.md) and [/HIGHENTROPYVA](highentropyva-support-64-bit-aslr.md) address space layout randomization (ASLR) lower the chances that your code becomes an exploit vector. -The **/guard:cf** option must be passed to both the compiler and linker to build code that uses the CFG exploit mitigation technique. If your binary is built by using a single `cl` command, the compiler passes the option to the linker. If you compile and link separately, the option must be set on both the compiler and linker commands. The /DYNAMICBASE linker option is also required. To verify that your binary has CFG data, use the `dumpbin /headers /loadconfig` command. CFG-enabled binaries have `Guard` in the list of EXE or DLL characteristics, and Guard Flags include `CF Instrumented` and `FID table present`. +To use the CFG exploit mitigation technique, pass **`/guard:cf`** to the compiler and **`/GUARD:CF`** to the linker. -The **/guard:cf** option is incompatible with [/ZI](z7-zi-zi-debug-information-format.md) (Edit and Continue debug information) or [/clr](clr-common-language-runtime-compilation.md) (Common Language Runtime Compilation). +To disable the CFG exploit mitigation technique, pass **`/guard:cf-`** to the compiler **`/GUARD:NO`** to the linker. -Code compiled by using **/guard:cf** can be linked to libraries and object files that are not compiled by using the option. Only this code, when also linked by using the **/guard:cf** option and run on a CFG-aware operating system, has CFG protection. Because code compiled without the option will not stop an attack, we recommend that you use the option on all the code you compile. There is a small runtime cost for CFG checks, but the compiler analysis attempts to optimize away the checks on indirect jumps that can be proven to be safe. +If you build using a single `cl` command, the compiler passes the option to the linker. If you compile and link separately, set the option for both the compiler and linker commands. The `/DYNAMICBASE` linker option is also required. -### To set this compiler option in the Visual Studio development environment +To verify that your binary has CFG data, use the `dumpbin /headers /loadconfig` command. CFG-enabled binaries have `Guard` in the list of EXE or DLL characteristics, and Guard Flags include `CF Instrumented` and `FID table present`. -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). +The **`/guard:cf`** option is incompatible with [`/ZI`](z7-zi-zi-debug-information-format.md) (Edit and Continue debug information) or [`/clr`](clr-common-language-runtime-compilation.md) (Common Language Runtime Compilation). -1. Select the **Configuration Properties** > **C/C++** > **Code Generation** property page. +Code compiled by using **`/guard:cf`** can be linked to libraries and object files that aren't compiled by using the option. Only this code, when also linked by using the **`/guard:cf`** option and run on a CFG-aware operating system, has CFG protection. Because code compiled without the option won't stop an attack, we recommend that you use the option on all the code you compile. There's a small runtime cost for CFG checks, but the compiler analysis attempts to optimize away the checks on indirect jumps that can be proven to be safe. -1. Select the **Control Flow Guard** property. +### To set this compiler option in the Visual Studio development environment +1. Open the **Property Pages** dialog box for the project. For more information, see [Set compiler and build properties](../working-with-project-properties.md). +1. Select the **Configuration Properties** > **C/C++** > **Code Generation** property page. +1. Select the **Control Flow Guard** property. 1. In the dropdown control, choose **Yes** to enable Control Flow Guard, or **No** to disable it. ## See also -[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/guard-enable-guard-checks.md b/docs/build/reference/guard-enable-guard-checks.md index 85afea2c3c..3df932fa31 100644 --- a/docs/build/reference/guard-enable-guard-checks.md +++ b/docs/build/reference/guard-enable-guard-checks.md @@ -1,37 +1,41 @@ --- -description: "Learn more about: /GUARD (Enable Guard Checks)" +description: "Learn more about: /GUARD (Enable Guard Checks) linker option" title: "/GUARD (Enable Guard Checks)" -ms.date: "11/04/2016" +ms.date: 09/21/2022 +f1_keywords: ["VC.Project.VCCLCompilerTool.LinkControlFlowGuard"] ms.assetid: 72758e23-70ac-4616-94d7-d767477406d1 --- -# /GUARD (Enable Guard Checks) +# `/GUARD` (Enable Guard Checks) -Specifies support for Control Flow Guard checks in the executable image. +Tells the linker whether to support Control Flow Guard checks in the executable image. ## Syntax -``` -/GUARD:{CF|NO} -``` +> **`/GUARD:CF`**\ +> **`/GUARD:NO`** ## Remarks -When /GUARD:CF is specified, the linker modifies the header of a .dll or .exe to indicate support for Control Flow Guard (CFG) runtime checks. The linker also adds the required control flow target address data to the header. By default, /GUARD:CF is disabled. It can be explicitly disabled by using /GUARD:NO. To be effective, /GUARD:CF also requires the [/DYNAMICBASE (Use address space layout randomization)](dynamicbase-use-address-space-layout-randomization.md) linker option, which is on by default. +The **`/GUARD:CF`** linker option modifies the header of a DLL or EXE file to indicate support for Control Flow Guard (CFG) runtime checks. The linker also adds the required control flow target address data to the header. By default, **`/GUARD:CF`** is disabled. It can be explicitly disabled by using **`/GUARD:NO`**. To be effective, **`/GUARD:CF`** also requires the [`/DYNAMICBASE` (Use address space layout randomization)](dynamicbase-use-address-space-layout-randomization.md) linker option, which is on by default. -When source code is compiled by using the [/guard:cf](guard-enable-control-flow-guard.md) option, the compiler analyzes the control flow by examining all indirect calls for possible target addresses. The compiler inserts code to verify the target address of an indirect call instruction is in the list of known target addresses at runtime. Operating systems that support CFG stop a program that fails a CFG runtime check. This makes it more difficult for an attacker to execute malicious code by using data corruption to change a call target. +When source code is compiled by using the [`/guard:cf`](guard-enable-control-flow-guard.md) compiler option, the compiler analyzes the control flow by examining all indirect calls for possible target addresses. The compiler inserts code to verify the target address of an indirect call instruction is in the list of known target addresses at runtime. Operating systems that support CFG stop a program that fails a CFG runtime check. This check makes it more difficult for an attacker to execute malicious code by using data corruption to change a call target. -The /GUARD:CF option must be specified to both the compiler and linker to create CFG-enabled executable images. Code compiled but not linked by using /GUARD:CF incurs the cost of runtime checks, but does not enable CFG protection. When the /GUARD:CF option is specified to the `cl` command to compile and link in one step, the compiler passes the flag to the linker. When the **Control Flow Guard** property is set in Visual Studio, the /GUARD:CF option is passed to both the compiler and linker. When object files or libraries have been compiled separately, the option must be explicitly specified in the `link` command. +The **`/GUARD:CF`** option must be specified to both the compiler and linker to create CFG-enabled executable images. Code compiled but not linked by using **`/GUARD:CF`** incurs the cost of runtime checks, but doesn't enable CFG protection. When the **`/guard:cf`** option is specified to the `cl` command to compile and link in one step, the compiler passes the flag to the linker. When the **Control Flow Guard** property is set in Visual Studio, the **`/GUARD:CF`** option is passed to both the compiler and linker. When object files or libraries have been compiled separately, the option must be explicitly specified in the `link` command. ### To set this linker option in Visual Studio -1. Open the project **Property Pages** dialog box. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the **Property Pages** dialog box for the project. For more information, see [Set compiler and build properties](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. -1. In **Additional Options**, enter `/GUARD:CF`. +1. In **Additional Options**, enter *`/GUARD:CF`*. Choose **OK** or **Apply** to save your changes. + +### To set this linker option programmatically + +- See . ## See also -[/guard (Enable Control Flow Guard)](guard-enable-control-flow-guard.md)
-[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[`/guard` (Enable Control Flow Guard)](guard-enable-control-flow-guard.md)\ +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/header-unit-json-reference.md b/docs/build/reference/header-unit-json-reference.md new file mode 100644 index 0000000000..cc0a1bf2c5 --- /dev/null +++ b/docs/build/reference/header-unit-json-reference.md @@ -0,0 +1,115 @@ +--- +description: "Reference for header-units.json file" +title: "C++ header unit.json reference" +ms.date: 11/09/2022 +author: "tylermsft" +ms.author: "twhitney" +f1_keywords: ["header-units.json"] +helpviewer_keywords: ["header-units.json", "header unit"] +monikerRange: '>=msvc-160' +--- + +# C++ header-units.json reference + +The `header-units.json` file serves two purposes: +- Specify which header files can be translated into header units when [`/translateInclude`](translateinclude.md) is specified. +- Minimize duplicated symbols to increase build throughput. + +This file must be in the same directory as the included header file. This file is only used when [`/translateInclude`](translateinclude.md) is specified along with either [`/scanDependencies`](scandependencies.md) or [`/sourceDependencies:directives`](sourcedependencies-directives.md). + +## Rationale + +Some header files can't be safely translated to header units. Header files that depend on macros that aren't defined on the command line, or that aren't defined in the header files included by the header, can't be translated to header units. + +If a header defines macros that affect whether other headers are included, it can't be safely translated. For example, given `a.h`, `b.h` and `macros.h`, which are all in the same directory: + +```cpp +// a.h + +#include "macros.h" // #defines MACRO=1 +#ifdef MACRO +#include "b.h" +#endif +``` + +The `header-units.json` in this directory can contain `a.h` and `b.h`, but not `macros.h`. The `header-units.json` for this example would be similar to this: + +```json +{ + "Version": "1.0", + "BuildAsHeaderUnits": [ + // macros.h should not be listed + "a.h", + "b.h" + ] +} +``` + +The reason `macros.h` can't be listed in this `header-units.json` file is that during the scan phase, the header unit (`.ifc`) might not be compiled yet for `macros.h`. In that case, `MACRO` won't be defined when `a.h` is compiled. That means `b.h` will be missing from the list of dependencies for `a.h`. Since it isn't in the list of dependencies, the build system won't build a header unit for `b.h` despite it being listed in the `header-units.json` file. + +To avoid this problem, when there's a dependency on a macro in another header file, the header file that defines the macro is excluded from the list of files that can be compiled into a header unit. This way the header file that defines the macro is treated as a normal `#include` and `MACRO` will be visible so that `b.h` is included and listed as one of the dependencies. + +### Preventing duplicated symbols + +The `header-units.json` file is also important because it allows for automatic header unit creation without duplicated symbols. It does this by creating "atomic" header units for the files listed in `header-units.json`. The imported header units don't contain duplicated symbols from the various `#include` directives that were processed while translating the header file. + +For example, consider two header files that both include a common header file. Both header files are included by the same source file: + +```cpp +// a.h +#include "b.h" + +// c.h +#include "b.h" + +// Source.cpp +import "a.h"; +import "c.h"; +``` + +If the compiler built header units for `a.h`, `b.h` and `c.h`, then the compiled header units `a.h.ifc`, `b.h.ifc`, and `c.h.ifc` would each contain all of the types from `b.h`. Compiling `Source.cpp`, which imports both `a.h` and `c.h`, would require the compiler to deduplicate the `b.h` types, which would impact build performance. + +But if there's a `header-units.json` in the `b.h` directory, and `/translateInclude` is specified, then the following happens: + +1. The scan of `a.h` and `c.h` lists `b.h` as a header unit import in the dependency scan files generated by the compiler. +1. The build system reads the dependency scan files and determines to build `b.h.ifc` first. +1. Then the build system adds `/headerUnit` for `b.h.ifc` to the command lines for compiling `a.h` and `c.h`. It calls the compiler to build the header units `a.h.ifc` and `c.h.ifc`. Because `/translateInclude` is specified, and `/headerUnit for b.h.ifc` is also specified, `a.h.ifc` and `c.h.ifc` won't contain `b.h` types, so there won't be any duplication in the produced header units. + +## Schema + +There's a `headerunits.json` file for the Standard Template Library (STL) headers. The build system uses it to determine whether to create a header unit for an STL header file, and for its dependencies. If the STL header file isn't on the list, it's treated as a normal `#include` instead of importing it as a header unit. + +You can see the `header-units.json` file under the installation directory for Visual Studio. For example: `%ProgramFiles%\Microsoft Visual Studio\2022\Enterprise\VC\Tools\MSVC\14.30.30705\include\header-units.json` + +The `header-units.json` file starts with the schema version, followed by an array of filenames for headers that can be built into header units. + +The schema also supports comments, as shown here: + +```json +{ + "Version": "1.0", + "BuildAsHeaderUnits": [ + // "__msvc_all_public_headers.hpp", // for testing, not production + "__msvc_system_error_abi.hpp", + "__msvc_tzdb.hpp", + "__msvc_xlocinfo_types.hpp", + "algorithm", + "any", + "array", + "atomic", + "barrier", + "bit", + "bitset", + // "cassert", // design is permanently incompatible with header units + ... +} +``` + +## Search rules + +The compiler looks for this file in the same directory as the header file being processed. If your library is organized into subdirectories, each subdirectory needs its own `header-units.json` file. + +## See also + +[Walkthrough: Import STL libraries as header units](..\walkthrough-import-stl-header-units.md#approach1)\ +[Walkthrough: Build and import header units in your Visual C++ projects](..\walkthrough-header-units.md) \ No newline at end of file diff --git a/docs/build/reference/headername.md b/docs/build/reference/headername.md index f02520a15f..2f7824ddfb 100644 --- a/docs/build/reference/headername.md +++ b/docs/build/reference/headername.md @@ -1,7 +1,7 @@ --- title: "/headerName (Build a header unit from the specified header)" description: "Use the /headerName compiler option to establish a mapping between a header file and the header unit to build." -ms.date: 04/13/2021 +ms.date: 11/16/2022 author: "tylermsft" ms.author: "twhitney" f1_keywords: ["/headerName"] @@ -23,51 +23,53 @@ The name of a header file that the compiler should compile into a header unit (* ## Remarks -The **`/headerName`** compiler option is available starting in Visual Studio 2019 version 16.10 preview 2. +The **`/headerName:quote`** and **`/headerName:angle`** compiler options are available starting in Visual Studio 2019 version 16.10. -The **`/headerName`** compiler option, in all its forms, requires the [/std:c++latest](std-specify-language-standard-version.md) option.\ -If you specify **`/headerName:{quote,angle}`**, you must also specify [`/exportHeader`](module-exportheader.md). +The **`/headerName`** compiler options, in all their forms, require the [`/std:c++20`](std-specify-language-standard-version.md) or later compiler option (such as **`/std:c++latest`**).\ +If you specify a **`/headerName`** option, you must also specify [`/exportHeader`](module-exportheader.md). -**`/headerName:quote`** looks up *`header-filename`* using the same rules as `#include "header-name"` and builds it as a header unit (*`.ifc`* file).\ -**`/headerName:angle`** looks up *`header-filename`* using the same rules as `#include ` and builds it as a header unit (*`.ifc`* file). +- **`/headerName:quote`** looks up *`header-filename`* using the same rules as `#include "header-filename"` and builds it as a header unit (*`.ifc`* file). +- **`/headerName:angle`** looks up *`header-filename`* using the same rules as `#include ` and builds it as a header unit (*`.ifc`* file). + +For more information about the path searching rules for included files in quotes or angle brackets, see [`#include` directive](../../preprocessor/hash-include-directive-c-cpp.md). ### Examples -Given a project that references a header file it defines called `m.h`, the compiler option to compile it into a header unit looks similar to this: +Given a project that references a header file it defines called *`m.h`*, the compiler option to compile it into a header unit looks similar to this example: -```Bash -$ cl /std:c++latest /exportHeader /headerName:quote m.h /Fom.h.obj +```bash +cl /std:c++latest /exportHeader /headerName:quote m.h /Fom.h.obj ``` -The `/headerName:{quote,angle}`switch acts like a flag and does not explicitly need an argument. The following examples are valid: +The **`/headerName:quote`** and **`/headerName:angle`** options act like a flag and don't need an argument. The following examples are valid: -```Bash -$ cl /std:c++latest /exportHeader /headerName:angle /MP /Fo.\ vector iostream algorithm -$ cl /std:c++latest /exportHeader /headerName:quote /MP /Fo.\ my-utilities.h a/b/my-core.h +```bash +cl /std:c++latest /exportHeader /headerName:angle /MP /Fo.\ vector iostream algorithm +cl /std:c++latest /exportHeader /headerName:quote /MP /Fo.\ my-utilities.h a/b/my-core.h ``` -You can specify multiple `/headerName` switches on the same command line, and every argument after that switch will be processed with the specified *`header-filename`* lookup rules. The following example processes all the headers as the previous two command line examples in the same way. It looks up the headers using the lookup rules applied as if they had been specified as: `#include `, `#include "my-utilties.h"`, and `#include "a/b/my-core.h"`: +You can specify multiple **`/headerName`** options on the same command line. Every argument after a **`/headerName`** option is processed with the specified include file lookup rules for quotes or angle brackets until the next **`/headerName`** option. The following example processes all the headers as the previous two command line examples in the same way as before. It looks up the headers using the lookup rules applied as if they had been specified as: `#include `, `#include `, `#include `, `#include "my-utilties.h"`, and `#include "a/b/my-core.h"`: ```bash -$ cl /std:c++latest /exportHeader /headerName:angle /MP /Fo.\ vector iostream algorithm /headerName:quote my-utilities.h a/b/my-core.h +cl /std:c++latest /exportHeader /headerName:angle /MP /Fo.\ vector iostream algorithm /headerName:quote my-utilities.h a/b/my-core.h ``` ### To set this compiler option in the Visual Studio development environment > [!NOTE] -> Users don't typically set this command line switch. It is set by the build system. +> You normally shouldn't set this option in the Visual Studio development environment. It's set by the build system. 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. Set the **Configuration** drop-down to **All Configurations**. +1. Set the **Configuration** drop-down to **All Configurations**. Set the **Platform** drop-down to **All Platforms**. 1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Modify the **Additional Options** property to add the *`/headerName`* options and arguments. Then, choose **OK** or **Apply** to save your changes. +1. Modify the **Additional Options** property to add the *`/headerName:quote`* or *`/headerName:angle`* options and the header filenames the options apply to. Then, choose **OK** or **Apply** to save your changes. ## See also [`/exportHeader` (Create header units)](module-exportheader.md)\ -[`/headerUnit` (Create header units)](headerunit.md)\ +[`/headerUnit` (Use header unit IFC)](headerunit.md)\ [`/reference` (Use named module IFC)](module-reference.md)\ [`/translateInclude` (Translate include directives into import directives)](translateinclude.md) diff --git a/docs/build/reference/headerunit.md b/docs/build/reference/headerunit.md index 5957c4afcd..6ee2d63554 100644 --- a/docs/build/reference/headerunit.md +++ b/docs/build/reference/headerunit.md @@ -1,7 +1,7 @@ --- title: "/headerUnit (Use header unit IFC)" description: "Use the /headerUnit compiler option to associate a header file with the header unit to import in its place." -ms.date: 04/13/2021 +ms.date: 5/28/2024 f1_keywords: ["/headerUnit"] helpviewer_keywords: ["/headerUnit", "Use header unit IFC"] author: "tylermsft" @@ -9,13 +9,13 @@ ms.author: "twhitney" --- # `/headerUnit` (Use header unit IFC) -Used to import a header unit. Tells the compiler where to find the *`.ifc`* file (the binary representation of the header unit) for the specified header. +Imports a header unit. Tells the compiler where to find the *`.ifc`* file (the binary representation of the header unit) for the specified header. ## Syntax > **`/headerUnit`** *`header-filename`*=*`ifc-filename`*\ -> **`/headerUnit:quote`** \[*`header-filename`*=*`ifc-filename`*\]\ -> **`/headerUnit:angle`** \[*`header-filename`*=*`ifc-filename`*\] +> **`/headerUnit:quote`** *`header-filename`*=*`ifc-filename`*\ +> **`/headerUnit:angle`** *`header-filename`*=*`ifc-filename`* ### Arguments @@ -27,34 +27,34 @@ The name of a file that contains compiled header unit information. To import mor ## Remarks -The **`/headerUnit`** compiler option requires the [/std:c++latest](std-specify-language-standard-version.md) option. +The **`/headerUnit`** compiler option requires [`/std:c++20`](std-specify-language-standard-version.md) or later. -The **`/headerUnit`** compiler option is available starting in Visual Studio 2019 version 16.10 preview 2. +The **`/headerUnit`** compiler option is available in Visual Studio 2019 version 16.10 or later. -When the compiler comes across `import "file";` or `import ;`, this compiler switch helps the compiler find the compiled header unit (*`.ifc`*) for the specified header file. The path to this file can be expressed in three ways: +When the compiler comes across `import "file";` or `import ;` this compiler option helps the compiler find the compiled header unit (*`.ifc`*) for the specified header file. The path to this file can be expressed in these ways: -**`/headerUnit`** looks up the compiled header unit in the current directory, or at the location specified in *`ifc-filename`*. +- **`/headerUnit`** looks up the compiled header unit in the current directory, or at the location specified by *`ifc-filename`*. -**`/headerUnit:quote`** looks up the compiled header unit file using the same rules as `#include "file"`. +- **`/headerUnit:quote`** looks up the compiled header unit file using the same rules as `#include "file"`. -**`/headerUnit:angle`** looks up the compiled header unit file using the same rules as `#include `. +- **`/headerUnit:angle`** looks up the compiled header unit file using the same rules as `#include `. -The compiler can't map a single *`header-name`* to multiple *`.ifc`* files. While mapping multiple *`header-name`* arguments to a single *`.ifc`* is possible, we don't recommend it. The contents of the *`.ifc`* get imported as if it was only the header specified by *`header-name`*. +The compiler can't map a single *`header-name`* to multiple *`.ifc`* files. You can map multiple *`header-name`* arguments to a single *`.ifc`*. The contents of the *`.ifc`* are imported as if it was only the header specified by *`header-name`*. -The compiler implicitly enables the new preprocessor when this switch is used. That is, [`/Zc:preprocessor`](zc-preprocessor.md) is added to the command line by the compiler if any form of `/headerUnit` is specified on the command line. To opt out of the implicit `/Zc:preprocessor`, specify: `/Zc:preprocessor-` +The compiler implicitly enables the new preprocessor when this option is used. If any form of `/headerUnit` is specified on the command line, then [`/Zc:preprocessor`](zc-preprocessor.md) is added to the command line by the compiler. To opt out of the implicit `/Zc:preprocessor`, specify: `/Zc:preprocessor-` If you disable the new preprocessor, but a file you compile imports a header unit, the compiler will report an error. ### Examples -Given a project that references two header files and their header units, listed in this table: +Given a project that references two header files and their header units as listed in this table: | Header file | IFC file | |--|--| | *`C:\utils\util.h`* | *`C:\util.h.ifc`* | | *`C:\app\app.h`* | *`C:\app\app.h.ifc`* | -The compiler options to reference the header units for these particular header files would look similar to this: +The compiler options to reference the header units for these particular header files would look like this: ```CMD cl ... /std:c++latest /headerUnit C:\utils\util.h=C:\util.h.ifc /headerUnit:quote app.h=app.h.ifc @@ -62,10 +62,11 @@ cl ... /std:c++latest /headerUnit C:\utils\util.h=C:\util.h.ifc /headerUnit:quot ### To set this compiler option in the Visual Studio development environment -You normally shouldn't set this in the Visual Studio development environment. It is set by the build system. +You normally shouldn't set this in the Visual Studio development environment. It's set by the build system. ## See also [`/exportHeader` (Create header units)](module-exportheader.md)\ [`/headerName` (Create a header unit from the specified header)](headername.md)\ -[`/reference` (Use named module IFC)](module-reference.md) +[`/reference` (Use named module IFC)](module-reference.md)\ +[`/translateInclude` (Translate include directives into import directives)](translateinclude.md) diff --git a/docs/build/reference/hint-files.md b/docs/build/reference/hint-files.md index c5c722c719..374b605e6f 100644 --- a/docs/build/reference/hint-files.md +++ b/docs/build/reference/hint-files.md @@ -155,7 +155,7 @@ The illustration shows some of the physical directories in a Visual Studio C++ p ### Hint File Directories -![Common and project-specific hint file directories.](media/hintfile.png "HintFile") +![Diagram showing the common and project specific hint file directories.](media/hintfile.png) ### Directories and Hint File Contents diff --git a/docs/build/reference/hotpatch-create-hotpatchable-image.md b/docs/build/reference/hotpatch-create-hotpatchable-image.md index 2930f364f7..ecd2b6467e 100644 --- a/docs/build/reference/hotpatch-create-hotpatchable-image.md +++ b/docs/build/reference/hotpatch-create-hotpatchable-image.md @@ -1,7 +1,7 @@ --- description: "Learn more about: /hotpatch (Create Hotpatchable Image)" title: "/hotpatch (Create Hotpatchable Image)" -ms.date: "11/12/2018" +ms.date: "12/7/2021" f1_keywords: ["/hotpatch", "VC.Project.VCCLCompilerTool.CreateHotpatchableImage"] helpviewer_keywords: ["hot patching", "-hotpatch compiler option [C++]", "/hotpatch compiler option [C++]", "hotpatching"] ms.assetid: aad539b6-c053-4c78-8682-853d98327798 @@ -18,7 +18,7 @@ Prepares an image for hot patching. ## Remarks -When **/hotpatch** is used in a compilation, the compiler ensures that first instruction of each function is at least two bytes, which is required for hot patching. +When **/hotpatch** is used in a compilation, the compiler ensures that the first instruction of each function is at least two bytes, and no jump within the function goes to the first instruction. These conditions are required for hot patching. To complete the preparation for making an image hotpatchable, after you use **/hotpatch** to compile, you must use [/FUNCTIONPADMIN (Create Hotpatchable Image)](functionpadmin-create-hotpatchable-image.md) to link. When you compile and link an image by using one invocation of cl.exe, **/hotpatch** implies **/functionpadmin**. diff --git a/docs/build/reference/idlout-name-midl-output-files.md b/docs/build/reference/idlout-name-midl-output-files.md index 38b277f76d..3c18293306 100644 --- a/docs/build/reference/idlout-name-midl-output-files.md +++ b/docs/build/reference/idlout-name-midl-output-files.md @@ -1,51 +1,45 @@ --- -description: "Learn more about: /IDLOUT (Name MIDL Output Files)" title: "/IDLOUT (Name MIDL Output Files)" -ms.date: "11/04/2016" +description: "Learn more about: /IDLOUT (Name MIDL Output Files)" +ms.date: 03/27/2025 f1_keywords: ["/idlout", "VC.Project.VCLinkerTool.MergedIDLBaseFileName"] helpviewer_keywords: ["MIDL, output file names", ".idl files, path", "MIDL", "/IDLOUT linker option", "IDL files, path", "-IDLOUT linker option", "IDLOUT linker option"] -ms.assetid: 10d00a6a-85b4-4de1-8732-e422c6931509 --- # /IDLOUT (Name MIDL Output Files) -``` -/IDLOUT:[path\]filename -``` +## Syntax -## Parameters +> /IDLOUT:[path\]filename -*path*
-An absolute or relative path specification. By specifying a path, you affect only the location of an .idl file; all other files are placed in the project directory. +## Argument -*filename*
-Specifies the name of the .idl file created by the MIDL compiler. No file extension is assumed; specify *filename*.idl if you want an .idl extension. +*`path`*\ +An absolute or relative path specification. By specifying a path, you affect only the location of an `.idl` file; all other files are placed in the project directory. + +*`filename`*\ +Specifies the name of the `.idl` file created by the MIDL compiler. No file extension is assumed; specify *`filename.idl` if you want an `.idl` extension. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). ## Remarks -The /IDLOUT option specifies the name and extension of the .idl file. +The `/IDLOUT` option specifies the name and extension of the `.idl` file. -The MIDL compiler is called by the MSVC linker when linking projects that have the [module](../../windows/attributes/module-cpp.md) attribute. +The MIDL compiler is called by the MSVC linker when linking projects that have the [`module`](../../windows/attributes/module-cpp.md) attribute. -/IDLOUT also specifies the file names of the other output files associated with the MIDL compiler: +`/IDLOUT` also specifies the file names of the other output files associated with the MIDL compiler: - *filename*.tlb - - *filename*_p.c - - *filename*_i.c - - *filename*.h -*filename* is the parameter that you pass to /IDLOUT. If [/TLBOUT](tlbout-name-dot-tlb-file.md) is specified, the .tlb file will get its name from /TLBOUT *filename*. +*`filename`* is the parameter that you pass to `/IDLOUT`. If [`/TLBOUT`](tlbout-name-dot-tlb-file.md) is specified, the .tlb file will get its name from `/TLBOUT` *`filename`*. -If you specify neither /IDLOUT nor /TLBOUT, the linker will create vc70.tlb, vc70.idl, vc70_p.c, vc70_i.c, and vc70.h. +If you specify neither `/IDLOUT` nor `/TLBOUT`, the linker will create vc70.tlb, vc70.idl, vc70_p.c, vc70_i.c, and vc70.h. ### To set this linker option in the Visual Studio development environment 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** > **Linker** > **Embedded IDL** property page. - 1. Modify the **Merge IDL Base File Name** property. ### To set this linker option programmatically @@ -54,8 +48,8 @@ If you specify neither /IDLOUT nor /TLBOUT, the linker will create vc70.tlb, vc7 ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md)
-[/IGNOREIDL (Don't Process Attributes into MIDL)](ignoreidl-don-t-process-attributes-into-midl.md)
-[/MIDL (Specify MIDL Command Line Options)](midl-specify-midl-command-line-options.md)
+[MSVC linker reference](linking.md)\ +[MSVC Linker Options](linker-options.md)\ +[/IGNOREIDL (Don't Process Attributes into MIDL)](ignoreidl-don-t-process-attributes-into-midl.md)\ +[/MIDL (Specify MIDL Command Line Options)](midl-specify-midl-command-line-options.md)\ [Building an Attributed Program](../../windows/attributes/cpp-attributes-com-net.md) diff --git a/docs/build/reference/ifc-map.md b/docs/build/reference/ifc-map.md new file mode 100644 index 0000000000..7466fd2b00 --- /dev/null +++ b/docs/build/reference/ifc-map.md @@ -0,0 +1,88 @@ +--- +title: "/ifcMap" +description: "Map named modules and header units to IFC files." +ms.date: 10/16/2023 +author: "tylermsft" +ms.author: "twhitney" +f1_keywords: ["/ifcMap"] +helpviewer_keywords: ["/ifcMap", "Specify named module and header unit mappings to IFC files."] +--- +# `/ifcMap` + +This switch tells the compiler where to find the IFC reference map file, which maps references to named modules and header units to their corresponding IFC (`.ifc`) files. + +## Syntax + +> **`/ifcMap`** *`filename`* + +## Remarks + +The *`filename`* argument specifies the IFC reference map file. It can be relative to the compiler's working directory, or an absolute path. + +You can provide multiple `/ifcMap` arguments to the compiler. + +The IFC reference map file format is a subset of the [TOML](https://toml.io/en/) file format. The IFC reference map file can contain a mix of `[[module]]` and `[[header-unit]]` references. + +Syntax errors or unrecognized table names result in compiler error `C7696` (TOML parse error). + +### Map named modules + +The format of the IFC reference map file for named modules is: + +``` +# Using literal strings +[[module]] +name = 'M' +ifc = 'C:\modules\M.ifc' + +# Using basic strings +[[module]] +name = "N" +ifc = "C:\\modules\\N.ifc" +``` + +This IFC reference map file maps the named modules `'M'` and `'N'` to their respective IFC files. The equivalent [`/reference`](module-reference.md) is: + +```cmd +/reference M=C:\modules\M.ifc /reference N=C:\modules\N.ifc +``` + +For more information about what types of module names are valid for the `name` field, see [`/reference remarks`](module-reference.md#remarks). + +### Map header units + +The format of the IFC reference map file for header units is: + +``` +# Using literal strings +[[header-unit]] +name = ['quote', 'my-utility.h'] +ifc = 'C:\header-units\my-utility.h.ifc' + +[[header-unit]] +name = ['angle', 'vector'] +ifc = 'C:\header-units\vector.ifc' + +# Using basic strings +[[header-unit]] +name = ["quote", "my-engine.h"] +ifc = "C:\\header-units\\my-engine.h.ifc" + +[[header-unit]] +name = ["angle", "algorithm"] +ifc = "C:\\header-units\\algorithm.ifc" +``` + +This IFC reference map file maps `"my-utility.h"` to `C:\header-units\my-utility.h.ifc`, and `` to `C:\header-units\vector.ifc`, and so on. The equivalent [`/headerUnit`](headerunit.md) is: + +```cmd +/headerUnit:quote my-utility=C:\header-units\my-utility.h.ifc /headerUnit:angle vector=C:\header-units\vector.ifc /headerUnit:quote my-engine.h=C:\header-units\my-engine.h.ifc /headerUnit:angle algorithm=C:\header-units\algorithm.ifc +``` + +When `[[header-unit]]` is specified in an IFC reference map file, the compiler implicitly enables [`/Zc:preprocessor`](zc-preprocessor.md), just as it's implicitly enabled when [`/headerUnit`](headerunit.md) is used. For more information about the behavior of the `angle` and `quote` lookup methods, see [/headerUnit remarks](headerunit.md#remarks). + +## See also + +[Overview of modules in C++](../../cpp/modules-cpp.md)\ +[Walkthrough: Build and import header units in Visual C++ projects](../walkthrough-header-units.md)\ +[Using C++ Modules in MSVC from the Command Line](https://devblogs.microsoft.com/cppblog/using-cpp-modules-in-msvc-from-the-command-line-part-1/) \ No newline at end of file diff --git a/docs/build/reference/ifc-output.md b/docs/build/reference/ifc-output.md new file mode 100644 index 0000000000..2fd60fcca2 --- /dev/null +++ b/docs/build/reference/ifc-output.md @@ -0,0 +1,56 @@ +--- +title: "/ifcOutput" +description: "Specify output file or directory for `.ifc` files." +ms.date: 11/21/2022 +author: "tylermsft" +ms.author: "twhitney" +f1_keywords: ["/ifcOutput", "VC.Project.VCCLCompilerTool.ifcOutput"] +helpviewer_keywords: ["/ifcOutput", "Specify where the compiled `.ifc` should go"] +--- +# `/ifcOutput` + +This switch tells the compiler where to output built *`.ifc`* files. If the destination is a directory, then the compiler generates the name of each `.ifc` file based on the interface name or the header unit name. + +## Syntax + +> **`/ifcOutput`** *`filename`*\ +> **`/ifcOutput`** *`directory\`* + +## Remarks + +By default, the compiler derives the name for each generated *`.ifc`* file from the module interface name. For example, given a module name `MyModule`, the generated *`.ifc`* will be named *`MyModule.ifc`*, unless you override the name with the `/ifcOutput` switch. + +Use this switch to specify an alternative *`.ifc`* filename or directory. If you want to use the default built *`.ifc`* filenames, but specify a directory where they should be built, ensure that you add a trailing backslash (`\`) to the directory name. + +When you're building multiple *`.ifc`* files, only use the directory form of the `/ifcOutput` switch. If you provide multiple `/ifcOutput` switches, the compiler only uses the last one. + +If you build with the [`/MP` (Build with multiple processes)](mp-build-with-multiple-processes.md) switch, we recommend that you use the directory form of the `/ifcOutput` switch if you have multiple input module files. + +In the following example, the *`.ifc`* file for module `m` defined in *`m.ixx`* is built as `c:\example\m.ifc`. + +```bash +cl ... /c /std:c++latest m.ixx /ifcOutput c:\example\ +``` + +In the following example, the built *`.ifc`* file for module `m` defined in *`m.ixx`** is built as `c:\example\MyModule.ifc`: + +```bash +cl ... /c /std:c++latest m.ixx /ifcOutput c:\example\MyModule.ifc +``` + +### To set this compiler option in the Visual Studio development environment + +1. To apply the **`/ifcOutput`** option to one file in the IDE, select the file in **Solution Explorer**. Right-click to open the context menu and select **Properties** to open the **Property Pages** dialog. + +1. Set the **Configuration** dropdown to **All Configurations**. Set the **Platform** dropdown to **All Platforms**. + +1. Open the **Configuration Properties** > **C/C++** > **Output Files** property page. + +1. Use the dropdown control to modify the **Module Output File Name** property to a directory name (ending in `\`) or an alternate file name. Or you can specify a directory + file name, for example, `c:\example\mymodule.ifc`. Choose **OK** or **Apply** to save your changes. + +Alternatively, you can specify the `/ifcOutput` switch with a right-click on the project name in the **Solution Explorer** > **Configuration Properties** > **C/C++** > **Command Line**. + +## See also + +[Overview of modules in C++](../../cpp/modules-cpp.md)\ +[Using C++ Modules in MSVC from the Command Line](https://devblogs.microsoft.com/cppblog/using-cpp-modules-in-msvc-from-the-command-line-part-1/) \ No newline at end of file diff --git a/docs/build/reference/ignoreidl-don-t-process-attributes-into-midl.md b/docs/build/reference/ignoreidl-don-t-process-attributes-into-midl.md index 763269225c..319cc90f88 100644 --- a/docs/build/reference/ignoreidl-don-t-process-attributes-into-midl.md +++ b/docs/build/reference/ignoreidl-don-t-process-attributes-into-midl.md @@ -1,12 +1,12 @@ --- -description: "Learn more about: /IGNOREIDL (Don't Process Attributes into MIDL)" -title: "/IGNOREIDL (Don't Process Attributes into MIDL)" +description: "Learn more about: /IGNOREIDL (Don't Process Attributes into MIDL)" +title: "/IGNOREIDL (Don't Process Attributes into MIDL)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCLinkerTool.IgnoreEmbeddedIDL", "/ignoreidl"] helpviewer_keywords: ["IGNOREIDL linker option", "-IGNOREIDL linker option", "/IGNOREIDL linker option"] ms.assetid: 29514098-6a1c-4317-af2f-1dc268972780 --- -# /IGNOREIDL (Don't Process Attributes into MIDL) +# /IGNOREIDL (Don't Process Attributes into MIDL) ``` /IGNOREIDL diff --git a/docs/build/reference/ilk-name-incremental-database-file.md b/docs/build/reference/ilk-name-incremental-database-file.md new file mode 100644 index 0000000000..ab1d1d456e --- /dev/null +++ b/docs/build/reference/ilk-name-incremental-database-file.md @@ -0,0 +1,39 @@ +--- +title: "/ILK (Name incremental database file)" +description: "The MSVC linker option /ILK specifies the incremental link database file pathname." +ms.date: 03/27/2025 +f1_keywords: ["VC.Project.VCLinkerTool.IncrementalLinkDatabaseFile", "/ilk", "ilk"] +helpviewer_keywords: ["Name incremental database file in C++ linker", "/ILK linker option", "-ILK linker option", "ILK linker option"] +--- +# `/ILK` (Name incremental database file) + +The **`/ILK`** linker option tells the linker where to put the *`.ilk`* database file for incremental link information ([`/INCREMENTAL`](./incremental-link-incrementally.md)). + +## Syntax + +> **`/ILK:`**\[*`pathname`*] + +### Arguments + +*`pathname`*\ +The destination directory and filename for the generated *`.ilk`* file. If the **`/ILK`** option isn't specified when **`/INCREMENTAL`** is used, the filename is created by appending *`.ilk`* to the target base filename. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). + +## Remarks + +The **`/ILK`** linker option tells the linker the path and filename to use for the *`.ilk`* incremental database file when you specify [`/INCREMENTAL`](./incremental-link-incrementally.md). + +### To set this compiler option in the Visual Studio development environment + +1. Open the project **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). +1. Select the **Configuration Properties** > **Linker** > **General** property page. +1. Modify the **Incremental Link Database File** property. The default value is `$(IntDir)$(TargetName).ilk`. + +### To set this compiler option programmatically + +- See . + +## See also + +[`/INCREMENTAL`](./incremental-link-incrementally.md)\ +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) \ No newline at end of file diff --git a/docs/build/reference/implib-name-import-library.md b/docs/build/reference/implib-name-import-library.md index 9bf0f23ef3..93ad9b6efb 100644 --- a/docs/build/reference/implib-name-import-library.md +++ b/docs/build/reference/implib-name-import-library.md @@ -1,38 +1,35 @@ --- description: "Learn more about: /IMPLIB (Name Import Library)" title: "/IMPLIB (Name Import Library)" -ms.date: "11/04/2016" +ms.date: 03/24/2025 f1_keywords: ["/implib", "VC.Project.VCLinkerTool.ImportLIbrary"] helpviewer_keywords: ["IMPLIB linker option", "/IMPLIB linker option", "-IMPLIB linker option", "import libraries, overriding default name"] -ms.assetid: fe8f71ab-7055-41b5-8ef8-2b97cfa4a432 --- -# /IMPLIB (Name Import Library) +# `/IMPLIB` (Name Import Library) + +## Syntax > /IMPLIB:*filename* -## Parameters +## Argument -*filename*
-A user-specified name for the import library. It replaces the default name. +*`filename`*\ +A user-specified name for the import library. It replaces the default name. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). ## Remarks -The /IMPLIB option overrides the default name for the import library that LINK creates when it builds a program that contains exports. The default name is formed from the base name of the main output file and the extension .lib. A program contains exports if one or more of the following are specified: +The `/IMPLIB` option overrides the default name for the import library that LINK creates when it builds a program that contains exports. The default name is formed from the base name of the main output file and the extension `.lib`. A program contains exports if one or more of the following are specified: - The [__declspec(dllexport)](../../cpp/dllexport-dllimport.md) keyword in the source code - - [EXPORTS](exports.md) statement in a .def file - - An [/EXPORT](export-exports-a-function.md) specification in a LINK command -LINK ignores /IMPLIB when an import library is not being created. If no exports are specified, LINK does not create an import library. If an export file is used in the build, LINK assumes that an import library already exists and does not create one. For information on import libraries and export files, see [LIB Reference](lib-reference.md). +LINK ignores `/IMPLIB` when an import library isn't being created. If no exports are specified, LINK doesn't create an import library. If an export file is used in the build, LINK assumes that an import library already exists and doesn't create one. For information on import libraries and export files, see [LIB Reference](lib-reference.md). ### To set this linker option in the Visual Studio development environment 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** > **Linker** > **Advanced** property page. - 1. Modify the **Import Library** property. ### To set this linker option programmatically @@ -41,5 +38,5 @@ LINK ignores /IMPLIB when an import library is not being created. If no exports ## See also -[MSVC linker reference](linking.md)
+[MSVC linker reference](linking.md)\ [MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/include-visual-cpp.md b/docs/build/reference/include-visual-cpp.md index 43276ff176..532ad182b6 100644 --- a/docs/build/reference/include-visual-cpp.md +++ b/docs/build/reference/include-visual-cpp.md @@ -1,44 +1,44 @@ --- -description: "Learn more about: <include>" -title: "<include> (C++ documentation comments)" -ms.date: "11/04/2016" +description: "Learn more about: XML documentation tag " +title: " (C++ documentation comments)" +ms.date: 12/03/2021 f1_keywords: [""] helpviewer_keywords: ["include C++ XML tag", " C++ XML tag"] ms.assetid: 392a3e61-0371-4617-8362-446650876ce3 --- -# <include> +# `` documentation tag -The \ tag lets you refer to comments in another file that describe the types and members in your source code. This is an alternative to placing documentation comments directly in your source code file. For example, you can use \ to insert standard "boilerplate" comments that are used throughout your team or company. +The `` tag lets you refer to comments in another file that describe the types and members in your source code. This tag is an alternative to placing documentation comments directly in your source code file. For example, you can use `` to insert standard "boilerplate" comments that are used throughout your team or company. ## Syntax -``` - +```cpp +/// ``` -#### Parameters +### Parameters -*filename*
-The name of the file containing the documentation. The file name can be qualified with a path. Enclose the name in single or double quotation marks. The compiler issues a warning if it does not find `filename`. +*`filename`*\ +The name of the file containing the documentation. The file name can be qualified with a path. Enclose the name in single or double quotation marks. The compiler issues a warning if it doesn't find *`filename`*. -*tagpath*
-A valid XPath expression that selects the desired node-set contained in the file. +*`tag-path`*\ +A valid XPath expression that selects the wanted node-set contained in the file. -*name*
-The name specifier in the tag that precedes the comments; `name` will have an `id`. +*`name`*\ +The name specifier in the tag that precedes the comments; *`name`* will have an *`ID`*. -*id*
-The ID for the tag that precedes the comments. Enclose the name in single or double quotation marks. +*`ID`*\ +The ID for the tag that precedes the comments. Enclose the ID in single or double quotation marks. ## Remarks -The \ tag uses the XML XPath syntax. Refer to XPath documentation for ways to customize using \. +The `` tag uses the XML XPath syntax. Refer to XPath documentation for ways to customize using ``. -Compile with [/doc](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. +Compile with [`/doc`](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. ## Example -This is a multifile example. The first file, which uses \, contains the following documentation comments: +This example uses multiple files. The first file, which uses ``, contains the following documentation comments: ```cpp // xml_include_tag.cpp @@ -58,7 +58,7 @@ public ref class Test2 { }; ``` -The second file, xml_include_tag.doc, contains the following documentation comments: +The second file, *`xml_include_tag.doc`*, contains the following documentation comments: ```xml @@ -103,4 +103,4 @@ The summary for this other type. ## See also -[XML Documentation](xml-documentation-visual-cpp.md) +[XML documentation](xml-documentation-visual-cpp.md) diff --git a/docs/build/reference/incremental-link-incrementally.md b/docs/build/reference/incremental-link-incrementally.md index ef569a1246..581ba2ccd8 100644 --- a/docs/build/reference/incremental-link-incrementally.md +++ b/docs/build/reference/incremental-link-incrementally.md @@ -1,24 +1,26 @@ --- -description: "Learn more about: /INCREMENTAL (Link Incrementally)" -title: "/INCREMENTAL (Link Incrementally)" -ms.date: "11/04/2016" +description: "Learn more about: /INCREMENTAL (Link incrementally)" +title: "/INCREMENTAL (Link incrementally)" +ms.date: 09/07/2022 f1_keywords: ["/incremental", "VC.Project.VCLinkerTool.LinkIncremental"] helpviewer_keywords: ["/INCREMENTAL linker option", "-INCREMENTAL linker option", "INCREMENTAL linker option", "link incrementally option", "LINK tool [C++], options for full linking", "incremental linking"] ms.assetid: 135656ff-94fa-4ad4-a613-22e1a2a5d16b --- -# /INCREMENTAL (Link Incrementally) +# `/INCREMENTAL` (Link incrementally) -``` -/INCREMENTAL[:NO] -``` +Specifies whether to link incrementally or always perform a full link. + +## Syntax + +> **`/INCREMENTAL`**\[**`:NO`**] ## Remarks -Controls how the linker handles incremental linking. +The **`/INCREMENTAL`** linker option controls how the linker handles incremental linking. -By default, the linker runs in incremental mode. To override a default incremental link, specify /INCREMENTAL:NO. +By default, the linker runs in incremental mode. To override a default incremental link, specify **`/INCREMENTAL:NO`**. -An incrementally linked program is functionally equivalent to a program that is non-incrementally linked. However, because it is prepared for subsequent incremental links, an incrementally linked executable, static library, or dynamic-link library file: +An incrementally linked program is functionally equivalent to a program that is non-incrementally linked. However, because it's prepared for subsequent incremental links, an incrementally linked executable, static library, or dynamic-link library file: - Is larger than a non-incrementally linked program because of padding of code and data. Padding enables the linker to increase the size of functions and data without recreating the file. @@ -27,35 +29,37 @@ An incrementally linked program is functionally equivalent to a program that is > [!NOTE] > To ensure that your final release build does not contain padding or thunks, link your program non-incrementally. -To link incrementally regardless of the default, specify /INCREMENTAL. When this option is selected, the linker issues a warning if it cannot link incrementally, and then links the program non-incrementally. Certain options and situations override /INCREMENTAL. +To link incrementally regardless of the default, specify **`/INCREMENTAL`**. When this option is selected, the linker issues a warning if it can't link incrementally, and then links the program non-incrementally. Certain options and situations override **`/INCREMENTAL`**. Most programs can be linked incrementally. However, some changes are too great, and some options are incompatible with incremental linking. LINK performs a full link if any of the following options are specified: -- Link Incrementally is not selected (/INCREMENTAL:NO) +- Link Incrementally isn't selected (**`/INCREMENTAL:NO`**) -- /OPT:REF is selected +- **`/OPT:REF`** is selected -- /OPT:ICF is selected +- **`/OPT:ICF`** is selected -- /OPT:LBR is selected +- **`/OPT:LBR`** is selected -- /ORDER is selected +- **`/ORDER`** is selected -/INCREMENTAL is implied when [/DEBUG](debug-generate-debug-info.md) is specified. +**`/INCREMENTAL`** is implied when [`/DEBUG`](debug-generate-debug-info.md) is specified. Additionally, LINK performs a full link if any of the following situations occur: -- The incremental status (.ilk) file is missing. (LINK creates a new .ilk file in preparation for subsequent incremental linking.) +- The incremental status (*`.ilk`*) file is missing. (LINK creates a new *`.ilk`* file in preparation for subsequent incremental linking.) -- There is no write permission for the .ilk file. (LINK ignores the .ilk file and links non-incrementally.) +- There's no write permission for the *`.ilk`* file. (LINK ignores the *`.ilk`* file and links non-incrementally.) -- The .exe or .dll output file is missing. +- The *`.exe`* or *`.dll`* output file is missing. -- The timestamp of the .ilk, .exe, or .dll is changed. +- The timestamp of the *`.ilk`*, *`.exe`*, or *`.dll`* is changed. - A LINK option is changed. Most LINK options, when changed between builds, cause a full link. -- An object (.obj) file is added or omitted. +- An object (*`.obj`*) file is added or omitted. + +An incremental link creates or updates an incremental link database *`.ilk`* file. You can specify the name and location of this file by using the [`/ILK` (Name incremental database file)](./ilk-name-incremental-database-file.md) linker option. For more information about the *`.ilk`* file, see [`.ilk` files as linker input](./dot-ilk-files-as-linker-input.md). ### To set this linker option in the Visual Studio development environment @@ -71,5 +75,6 @@ Additionally, LINK performs a full link if any of the following situations occur ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md)\ +[`.ilk` files as linker input](./dot-ilk-files-as-linker-input.md) diff --git a/docs/build/reference/inference-rules.md b/docs/build/reference/inference-rules.md index 864f29f6bb..ebb37cb557 100644 --- a/docs/build/reference/inference-rules.md +++ b/docs/build/reference/inference-rules.md @@ -1,28 +1,184 @@ --- -description: "Learn more about: Inference Rules" -title: "Inference Rules" -ms.date: "11/04/2016" -helpviewer_keywords: ["inference rules in NMAKE", "rules, inference", "NMAKE program, inference rules"] -ms.assetid: caff320f-fb07-4eea-80c3-a6a2133a8492 +title: "Inference rules" +description: "Learn more about: NMAKE inference rules" +ms.date: 09/30/2021 +helpviewer_keywords: ["inference rules in NMAKE", "rules, inference", "NMAKE program, inference rules", "search paths in NMAKE inference rules", "defining inference rules", "batch-mode inference rules in NMAKE", "rules, predefined", "NMAKE program, predefined rules", "predefined rules in NMAKE", "rules, inferred", "inferred dependents in NMAKE", "inferred rules in NMAKE", "dependents, inferred", "precedence, inference rule"] --- -# Inference Rules +# Inference rules -Inference rules supply commands to update targets and to infer dependents for targets. Extensions in an inference rule match a single target and dependent that have the same base name. Inference rules are user-defined or predefined; predefined rules can be redefined. +Inference rules in NMAKE supply commands to update targets and to infer dependents for targets. Extensions in an inference rule match a single target and dependent that have the same base name. Inference rules are user-defined or predefined; predefined rules can be redefined. -If an out-of-date dependency has no commands, and if [.SUFFIXES](dot-directives.md) contains the dependent's extension, NMAKE uses a rule whose extensions match the target and an existing file in the current or specified directory. If more than one rule matches existing files, the **.SUFFIXES** list determines which to use; list priority descends from left to right. If a dependent file does not exist and is not listed as a target in another description block, an inference rule can create the missing dependent from another file with the same base name. If a description block's target has no dependents or commands, an inference rule can update the target. Inference rules can build a command-line target even if no description block exists. NMAKE may invoke a rule for an inferred dependent even if an explicit dependent is specified. +If an out-of-date dependency has no commands, and if [`.SUFFIXES`](dot-directives.md) contains the dependent's extension, NMAKE uses a rule whose extensions match the target and an existing file in the current or specified directory. If more than one rule matches existing files, the **`.SUFFIXES`** list determines which to use; list priority descends from left to right. If a dependent file doesn't exist and isn't listed as a target in another description block, an inference rule can create the missing dependent from another file that has the same base name. If a description block's target has no dependents or commands, an inference rule can update the target. Inference rules can build a command-line target even if no description block exists. NMAKE may invoke a rule for an inferred dependent even if an explicit dependent is specified. -## What do you want to know more about? +## Defining a rule -[Defining a rule](defining-a-rule.md) +The *from_ext* represents the extension of a dependent file, and *to_ext* represents the extension of a target file. -[Batch-mode rules](batch-mode-rules.md) +```makefile +.from_ext.to_ext: + commands +``` -[Predefined rules](predefined-rules.md) +Extensions aren't case-sensitive. Macros can be invoked to represent *from_ext* and *to_ext*; the macros are expanded during preprocessing. The period (**`.`**) that precedes *from_ext* must appear at the beginning of the line. The colon (**`:`**) is preceded by zero or more spaces or tabs. It can be followed only by spaces or tabs, a semicolon (**`;`**) to specify a command, a number sign (**`#`**) to specify a comment, or a newline character. No other spaces are allowed. Commands are specified as in description blocks. -[Inferred dependents and rules](inferred-dependents-and-rules.md) +## Search paths in rules -[Precedence in inference rules](precedence-in-inference-rules.md) +```makefile +{from_path}.from_ext{to_path}.to_ext: + commands +``` + +An inference rule applies to a dependency only if paths specified in the dependency exactly match the inference-rule paths. Specify the dependent's directory in *from_path* and the target's directory in *to_path*; no spaces are allowed. Specify only one path for each extension. A path on one extension requires a path on the other. To specify the current directory, use either a period (**`.`**) or empty braces (**`{ }`**). Macros can represent *from_path* and *to_path*; they are invoked during preprocessing. + +### Example of search paths + +```makefile +{dbi\}.cpp{$(ODIR)}.obj:: + $(CC) $(CFLAGS) $(YUDBI) $< + +{ilstore\}.cpp{$(ODIR)}.obj:: + $(CC) $(CFLAGS) $< + +{misc\}.cpp{$(ODIR)}.obj:: + $(CC) $(CFLAGS) $(YUPDB) $< + +{misc\}.c{$(ODIR)}.obj:: + $(CC) $(CFLAGS) $< + +{msf\}.cpp{$(ODIR)}.obj:: + $(CC) $(CFLAGS) $< + +{bsc\}.cpp{$(ODIR)}.obj:: + $(CC) $(CFLAGS) $(YUPDB) $< + +{mre\}.cpp{$(ODIR)}.obj:: + $(CC) $(CFLAGS) $(YUPDB) $< + +{namesrvr\}.cpp{$(ODIR)}.obj:: + $(CC) $(CFLAGS) $(YUPDB) $< + +{src\cvr\}.cpp{$(ODIR)}.obj:: + $(CC) $(CFLAGS) $< +``` + +## Batch-mode rules + +```makefile +{from_path}.from_ext{to_path}.to_ext:: + commands +``` + +Batch-mode inference rules provide only one invocation of the inference rule when N commands go through this inference rule. Without batch-mode inference rules, it would require N commands to be invoked. N is the number of dependents that trigger the inference rule. + +The only syntactical difference from the standard inference rule is that a batch-mode inference rule ends with a double colon (**`::`**). + +> [!NOTE] +> The tool being invoked must be able to handle multiple files. The batch-mode inference rule must use **`$<`** as the macro to access dependent files. + +The batch-mode inference rules can speed up the build process. It's faster to supply files to the compiler in batch mode, because the compiler driver is invoked only once. For example, the C and C++ compiler runs faster when handling a set of files, because it can remain memory resident during the entire process. + +The following example shows how to use batch-mode inference rules: + +```makefile +# +# sample makefile to illustrate batch-mode inference rules +# +O = . +S = . +Objs = $O/foo1.obj $O/foo2.obj $O/foo2.obj $O/foo3.obj $O/foo4.obj +CFLAGS = -nologo + +all : $(Objs) + +!ifdef NOBatch +{$S}.cpp{$O}.obj: +!else +{$S}.cpp{$O}.obj:: +!endif + $(CC) $(CFLAGS) -Fd$O\ -c $< + +$(Objs) : + +#end of makefile +``` + +NMAKE produces the following output without batch-mode inference rules: + +```cmd +E:\tmp> nmake -f test.mak -a NOBatch=1 + +Microsoft (R) Program Maintenance Utility Version 7.00.0000 +Copyright (C) Microsoft Corp 1988-2001. All rights reserved. + cl -nologo -Fd.\ -c .\foo1.cpp +foo1.cpp + cl -nologo -Fd.\ -c .\foo2.cpp +foo2.cpp + cl -nologo -Fd.\ -c .\foo3.cpp +foo3.cpp + cl -nologo -Fd.\ -c .\foo4.cpp +foo4.cpp +``` + +NMAKE produces the following result with the batch-mode inference rules: + +```cmd +E:\tmp> nmake -f test.mak -a + +Microsoft (R) Program Maintenance Utility Version 7.00.0000 +Copyright (C) Microsoft Corp 1988-2001. All rights reserved. + + cl -nologo -Fd.\ -c .\foo1.cpp .\foo2.cpp .\foo3.cpp .\foo4.cpp +foo1.cpp +foo2.cpp +foo3.cpp +foo4.cpp +Generating Code... +``` + +## Predefined rules + +Predefined inference rules use NMAKE-supplied command and options macros. + +| Rule | Command | Default action | Batch rule | Platform | +|--|--|--|--|--| +| `.asm.exe` | `$(AS) $(AFLAGS) $<` | `ml $<` | no | x86 | +| `.asm.obj` | `$(AS) $(AFLAGS) /c $<` | `ml /c $<` | yes | x86 | +| `.asm.exe` | `$(AS) $(AFLAGS) $<` | `ml64 $<` | no | x64 | +| `.asm.obj` | `$(AS) $(AFLAGS) /c $<` | `ml64 /c $<` | yes | x64 | +| `.c.exe` | `$(CC) $(CFLAGS) $<` | `cl $<` | no | all | +| `.c.obj` | `$(CC) $(CFLAGS) /c $<` | `cl /c $<` | yes | all | +| `.cc.exe` | `$(CC) $(CFLAGS) $<` | `cl $<` | no | all | +| `.cc.obj` | `$(CC) $(CFLAGS) /c $<` | `cl /c $<` | yes | all | +| `.cpp.exe` | `$(CPP) $(CPPFLAGS) $<` | `cl $<` | no | all | +| `.cpp.obj` | `$(CPP) $(CPPFLAGS) /c $<` | `cl /c $<` | yes | all | +| `.cxx.exe` | `$(CXX) $(CXXFLAGS) $<` | `cl $<` | no | all | +| `.cxx.obj` | `$(CXX) $(CXXFLAGS) /c $<` | `cl /c $<` | yes | all | +| `.rc.res` | `$(RC) $(RFLAGS) /r $<` | `rc /r $<` | no | all | + +## Inferred dependents and rules + +NMAKE assumes an inferred dependent for a target if an applicable inference rule exists. A rule applies if: + +- *to_ext* matches the target's extension. + +- *from_ext* matches the extension of a file that has the target's base name and that exists in the current or specified directory. + +- *from_ext* is in [`.SUFFIXES`](dot-directives.md); no other *from_ext* in a matching rule has a higher **`.SUFFIXES`** priority. + +- No explicit dependent has a higher **`.SUFFIXES`** priority. + +Inferred dependents can cause unexpected side effects. If the target's description block contains commands, NMAKE executes those commands instead of the commands in the rule. + +## Precedence in inference rules + +If an inference rule is defined more than once, NMAKE uses the highest-precedence definition. The following list shows the order of precedence from highest to lowest: + +1. An inference rule defined in a makefile; later definitions have precedence. + +1. An inference rule defined in *`Tools.ini`*; later definitions have precedence. + +1. A predefined inference rule. ## See also -[NMAKE Reference](nmake-reference.md) +[NMAKE reference](nmake-reference.md) diff --git a/docs/build/reference/inferred-dependents-and-rules.md b/docs/build/reference/inferred-dependents-and-rules.md deleted file mode 100644 index 3cec11a0ae..0000000000 --- a/docs/build/reference/inferred-dependents-and-rules.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -description: "Learn more about: Inferred Dependents and Rules" -title: "Inferred Dependents and Rules" -ms.date: "11/04/2016" -helpviewer_keywords: ["rules, inferred", "inferred dependents in NMAKE", "inferred rules in NMAKE", "dependents, inferred"] -ms.assetid: 9381e74a-53d9-445c-836d-0ff7ef6112d9 ---- -# Inferred Dependents and Rules - -NMAKE assumes an inferred dependent for a target if an applicable inference rule exists. A rule applies if: - -- *toext* matches the target's extension. - -- *fromext* matches the extension of a file that has the target's base name and that exists in the current or specified directory. - -- *fromext* is in [.SUFFIXES](dot-directives.md); no other *fromext* in a matching rule has a higher **.SUFFIXES** priority. - -- No explicit dependent has a higher **.SUFFIXES** priority. - -Inferred dependents can cause unexpected side effects. If the target's description block contains commands, NMAKE executes those commands instead of the commands in the rule. - -## See also - -[Inference Rules](inference-rules.md) diff --git a/docs/build/reference/inline-files-in-a-makefile.md b/docs/build/reference/inline-files-in-a-makefile.md index ca4dd519d1..b18211ffdc 100644 --- a/docs/build/reference/inline-files-in-a-makefile.md +++ b/docs/build/reference/inline-files-in-a-makefile.md @@ -1,23 +1,58 @@ --- -description: "Learn more about: Inline Files in a Makefile" -title: "Inline Files in a Makefile" -ms.date: "11/04/2016" -helpviewer_keywords: ["inline files [C++], in makefiles", "inline files [C++]", "NMAKE program, inline files", "makefiles, inline files", "files [C++], inline"] -ms.assetid: ff48a64f-773d-410c-9726-f867ad4c8030 +title: "Inline files in a makefile" +description: "Learn more about: Inline files in a makefile" +ms.date: 09/30/2021 +helpviewer_keywords: ["inline files [C++], in makefiles", "inline files [C++]", "NMAKE program, inline files", "makefiles, inline files", "files [C++], inline", "inline files, multiple NMAKE", "multiple inline files", "inline files, reusing NMAKE", "reusing inline files", "inline files, creating text", "inline files [C++], specifying NMAKE"] --- -# Inline Files in a Makefile +# Inline files in a makefile An inline file contains text you specify in the makefile. Its name can be used in commands as input (for example, a LINK command file), or it can pass commands to the operating system. The file is created on disk when a command that creates the file is run. -## What do you want to know more about? +## Specify an inline file -[Specifying an inline file](specifying-an-inline-file.md) +Specify two angle brackets (**`<<`**) in the command where *filename* is to appear. The angle brackets can't be a macro expansion. The *filename* is optional: -[Creating inline file text](creating-inline-file-text.md) +```makefile +< Create inline file text + +Inline files are temporary or permanent. + +```makefile +inline_text +. +. +. +<<[KEEP | NOKEEP] +``` + +Specify your *inline_text* on the first line after the command. Mark the end with double angle brackets (**`<<`**) at the beginning of a separate line, followed by an optional **`KEEP`** or **`NOKEEP`**. The file contains all *inline_text* before the delimiting brackets. The *inline_text* can have macro expansions and substitutions, but not directives or makefile comments. Spaces, tabs, and newline characters are treated literally. + +A temporary file exists for the duration of the session and can be reused by other commands. Specify **`KEEP`** after the closing angle brackets to retain the file after the NMAKE session; an unnamed file is preserved on disk with the generated filename. Specify **`NOKEEP`** or nothing for a temporary file. **`KEEP`** and **`NOKEEP`** are not case sensitive. + +## Reuse inline files + +To reuse an inline file, specify `< Multiple inline files + +A command can create more than one inline file: + +```makefile +command << << +inline_text +<<[KEEP | NOKEEP] +inline_text +. . . +inline_text +<<[KEEP | NOKEEP] +``` + +For each file, specify one or more lines of inline text followed by a closing line containing the delimiter and optional **`KEEP`** or **`NOKEEP`**. Begin the second file's text on the line following the delimiting line for the first file. ## See also diff --git a/docs/build/reference/integritycheck-require-signature-check.md b/docs/build/reference/integritycheck-require-signature-check.md index e8786d6bd6..2e154fe960 100644 --- a/docs/build/reference/integritycheck-require-signature-check.md +++ b/docs/build/reference/integritycheck-require-signature-check.md @@ -1,23 +1,23 @@ --- description: "Learn more about: /INTEGRITYCHECK (Require signature check)" title: "/INTEGRITYCHECK (Require signature check)" -ms.date: 04/21/2021 +ms.date: 08/29/2023 --- # `/INTEGRITYCHECK` (Require signature check) Specifies that the digital signature of the binary image must be checked at load time. -> **`/INTEGRITYCHECK`**[**`:NO`**] +> **`/INTEGRITYCHECK`** ## Remarks By default, **`/INTEGRITYCHECK`** is off. -The **`/INTEGRITYCHECK`** linker option sets a flag, `IMAGE_DLLCHARACTERISTICS_FORCE_INTEGRITY`, in the PE header of the DLL file or executable file. This flag tells the memory manager to check for a digital signature in order to load the image in Windows. This option must be set for both 32-bit and 64-bit DLLs that implement kernel-mode code loaded by certain Windows features. It's recommended for all device drivers on Windows Vista, Windows Server 2008, and all later versions of Windows and Windows Server. Versions of Windows prior to Windows Vista ignore this flag. For more information, see [Forced Integrity Signing of Portable Executable (PE) files](https://social.technet.microsoft.com/wiki/contents/articles/255.forced-integrity-signing-of-portable-executable-pe-files.aspx). +The **`/INTEGRITYCHECK`** linker option sets a flag, `IMAGE_DLLCHARACTERISTICS_FORCE_INTEGRITY`, in the PE header of the DLL file or executable file. This flag tells the memory manager to check for a digital signature in order to load the image in Windows. This option must be set for both 32-bit and 64-bit DLLs that certain Windows features load. It's recommended for all device drivers on Windows Vista, Windows Server 2008, and all later versions of Windows and Windows Server. Versions of Windows prior to Windows Vista ignore this flag. For more information, see [Forced Integrity Signing of Portable Executable (PE) files](https://social.technet.microsoft.com/wiki/contents/articles/255.forced-integrity-signing-of-portable-executable-pe-files.aspx). ### Signing `/INTEGRITYCHECK` files -Microsoft has new signing guidance for DLL and executable files linked by using **`/INTEGRITYCHECK`**. The guidance used to recommend a cross-signed certificate from the [cross-signing program](/windows-hardware/drivers/install/cross-certificates-for-kernel-mode-code-signing). However, the [cross-signing program is now deprecated](/windows-hardware/drivers/install/deprecation-of-software-publisher-certificates-and-commercial-release-certificates). We recommend you sign your **`/INTEGRITYCHECK`** files by using the Microsoft [Azure Code Signing](https://techcommunity.microsoft.com/t5/video-hub/reduce-developer-friction-with-azure-code-signing/m-p/1698637) program instead. +Microsoft has new signing guidance for DLL and executable files linked by using **`/INTEGRITYCHECK`**. The guidance used to recommend a cross-signed certificate from the [cross-signing program](/windows-hardware/drivers/install/cross-certificates-for-kernel-mode-code-signing). However, the [cross-signing program is now deprecated](/windows-hardware/drivers/install/deprecation-of-software-publisher-certificates-and-commercial-release-certificates). You must now sign your **`/INTEGRITYCHECK`** files by using the Microsoft [Trusted Signing service](/azure/trusted-signing/) program instead. ### To set this linker option in Visual Studio @@ -25,12 +25,14 @@ Microsoft has new signing guidance for DLL and executable files linked by using 1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. -1. In **Additional Options**, enter *`/INTEGRITYCHECK`* or *`/INTEGRITYCHECK:NO`*. Choose **OK** to save your changes. +1. To create a digitally signed image, include `/INTEGRITYCHECK` in the **Additional Options** command line. A digitally signed image must pass a verification check before it's loaded. This feature is disabled by default. + +1. Choose **OK** to save your changes. ## See also -[MSVC linker reference](linking.md)
-[MSVC linker options](linker-options.md)
-[Forced integrity signing of portable executable (PE) files](https://social.technet.microsoft.com/wiki/contents/articles/255.forced-integrity-signing-of-portable-executable-pe-files.aspx)
-[Kernel-mode code signing requirements](/windows-hardware/drivers/install/kernel-mode-code-signing-requirements--windows-vista-and-later-)
+[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md)\ +[Forced integrity signing of portable executable (PE) files](https://social.technet.microsoft.com/wiki/contents/articles/255.forced-integrity-signing-of-portable-executable-pe-files.aspx)\ +[Kernel-mode code signing requirements](/windows-hardware/drivers/install/kernel-mode-code-signing-requirements--windows-vista-and-later-)\ [AppInit DLLs and Secure Boot](/windows/win32/dlls/secure-boot-and-appinit-dlls) diff --git a/docs/build/reference/interface.md b/docs/build/reference/interface.md new file mode 100644 index 0000000000..743215fc73 --- /dev/null +++ b/docs/build/reference/interface.md @@ -0,0 +1,50 @@ +--- +title: "/interface" +description: "Use the /interface compiler option to treat the input file as a module interface unit." +ms.date: 11/16/2022 +author: "tylermsft" +ms.author: "twhitney" +f1_keywords: ["/interface", "VC.Project.VCCLCompilerTool.Interface"] +helpviewer_keywords: ["/interface", "Translate include directives into import directives"] +--- +# `/interface` + +This switch instructs the compiler to treat the input file on the command line as a module interface unit. + +## Syntax + +> **`/interface`** *`filename`* + +## Remarks + +Use this switch when a module interface has a different extension than `.ixx`. + +In the following example, the module interface has a `.cppm` extension instead of `.ixx`, so the `/interface` switch is used to compile it as a module interface: + +```bash +cl /c /std:c++latest /interface /TP my-module.cppm +``` + +The compiler derives the name for the generated `.ifc` file from the module interface name. For example, given a module name `MyModule` defined in `my-module.cppm`, the generated `.ifc` will be named `MyModule.ifc`. + +This switch must be used in with the [`/TP` (Specify source file type)](tc-tp-tc-tp-specify-source-file-type.md) compiler flag. + +**`/interface`** is available in Visual Studio 2019 version 16.10, or later.\ +**`/interface`** requires [/std:c++20](std-specify-language-standard-version.md) or later. + +### To set this compiler option in the Visual Studio development environment + +You normally shouldn't set this option in the Visual Studio development environment unless you use a different extension for your module interface files. By default, the build system applies this option to files that have a *`.ixx`** extension. + +1. To apply the **`/interface`** option to a file explicitly in the IDE, select the file in **Solution Explorer**. Right-click to open the context menu and select **Properties** to open the Property Pages dialog. + +1. Set the **Configuration** dropdown to **All Configurations**. Set the **Platform** dropdown to **All Platforms**. + +1. Open the **Configuration Properties** > **C/C++** > **Advanced** property page. + +1. Use the dropdown control to modify the **Compile As** property to **Compile as C++ Module Code (/interface)**. Choose **OK** or **Apply** to save your changes. + +## See also + +[Overview of modules in C++](../../cpp/modules-cpp.md)\ +[Using C++ Modules in MSVC from the Command Line](https://devblogs.microsoft.com/cppblog/using-cpp-modules-in-msvc-from-the-command-line-part-1/) \ No newline at end of file diff --git a/docs/build/reference/internal-partition.md b/docs/build/reference/internal-partition.md new file mode 100644 index 0000000000..393c44956a --- /dev/null +++ b/docs/build/reference/internal-partition.md @@ -0,0 +1,69 @@ +--- +title: "/internalPartition" +description: "Use the /internalPartition compiler option to treat the input file as an internal partition unit." +ms.date: 11/16/2022 +author: "tylermsft" +ms.author: "twhitney" +f1_keywords: ["/internalPartition", "VC.Project.VCCLCompilerTool.Interface"] +helpviewer_keywords: ["/internalPartition", "Translate include directives into import directives"] +--- +# `/internalPartition` + +Use the **`/internalPartition`** compiler option to treat the input file as an *internal partition unit*, which is a [module partition implementation unit](../../cpp/modules-cpp.md#implementing-modules) that doesn't contribute to the external interface of the module. + +## Syntax + +> **`/internalPartition`** *`filename`* + +## Remarks + +The following example demonstrates how to use the `/internalPartition` option: + +Source file `m-internals.cpp`: + +```cpp +// m-internals.cpp +module m:internals; + +void internalFunc() {} // cannot have `export` since this is an internal partition +``` + +Source file `m.ixx`: + +```cpp +// m.ixx +export module m; +import :internals; // Cannot export this partition. + +export +void wrapper() { internalFunc(); } +``` + +To compile this interface: + +```bash +cl /std:c++latest /internalPartition /c m-internals.cpp +``` + +This option can't be used with the [`/interface`](interface.md) compiler option. + +**`/internalPartition`** is available in Visual Studio 2019 version 16.10, or later.\ +**`/internalPartition`** requires [/std:c++20](std-specify-language-standard-version.md) or later. + +### To set this compiler option in the Visual Studio development environment + +You normally shouldn't set this option in the Visual Studio development environment unless you use a different extension for your partition files. By default, the build system applies this option to files that have a *`.ixx`** extension. + +1. To apply the **`/internalPartition`** option to a file explicitly in the IDE, select the file in **Solution Explorer**. Right-click to open the context menu and select **Properties** to open the Property Pages dialog. + +1. Set the **Configuration** dropdown to **All Configurations**. Set the **Platform** dropdown to **All Platforms**. + +1. Open the **Configuration Properties** > **C/C++** > **Advanced** property page. + +1. Use the dropdown control to modify the **Compile As** property to **Compile as C++ Module Internal Partition (/internalPartition)**. Choose **OK** or **Apply** to save your changes. + +## See also + +[Overview of modules in C++](../../cpp/modules-cpp.md)\ +[Using C++ Modules in MSVC from the Command Line](https://devblogs.microsoft.com/cppblog/using-cpp-modules-in-msvc-from-the-command-line-part-1/)\ +[C++ Modules conformance improvements with MSVC in Visual Studio 2019 16.5](https://devblogs.microsoft.com/cppblog/c-modules-conformance-improvements-with-msvc-in-visual-studio-2019-16-5/#module-partitions) \ No newline at end of file diff --git a/docs/build/reference/jmc.md b/docs/build/reference/jmc.md index ebff0e2dec..c78e3b3eb1 100644 --- a/docs/build/reference/jmc.md +++ b/docs/build/reference/jmc.md @@ -1,25 +1,27 @@ --- description: "Learn more about: /JMC (Just My Code debugging)" title: "/JMC (Just My Code debugging)" -ms.date: "08/20/2018" +ms.date: 03/01/2022 f1_keywords: ["VC.Project.VCCLCompilerTool.SupportJustMyCode"] helpviewer_keywords: ["/JMC compiler option [C++]", "Just my code [C++]", "-JMC compiler option [C++]", "User code, debugging", "JMC compiler option [C++]"] --- -# /JMC (Just My Code debugging) +# `/JMC` (Just My Code debugging) -Specifies compiler support for native *Just My Code* debugging in the Visual Studio debugger. This option supports the user settings that allow Visual Studio to step over system, framework, library, and other non-user calls, and to collapse those calls in the call stack window. The **/JMC** compiler option is available starting in Visual Studio 2017 version 15.8. +Specifies compiler support for native *Just My Code* debugging in the Visual Studio debugger. This option supports the user settings that allow Visual Studio to step over system, framework, library, and other non-user calls, and to collapse those calls in the call stack window. The **`/JMC`** compiler option is available starting in Visual Studio 2017 version 15.8. ## Syntax -> **/JMC**\[**-**] +> **`/JMC`**\[**`-`**] ## Remarks -The Visual Studio [Just My Code](/visualstudio/debugger/just-my-code) settings specify whether the Visual Studio debugger steps over system, framework, library, and other non-user calls. The **/JMC** compiler option enables support for Just My Code debugging in your native C++ code. When **/JMC** is enabled, the compiler inserts calls to a helper function, `__CheckForDebuggerJustMyCode`, in the function prolog. The helper function provides hooks that support Visual Studio debugger Just My Code step operations. To enable Just My Code in the Visual Studio debugger, on the menu bar, choose **Tools** > **Options**, and then set the option in **Debugging** > **General** > **Enable Just My Code**. +The Visual Studio [Just My Code](/visualstudio/debugger/just-my-code#BKMK_C___Just_My_Code) settings specify whether the Visual Studio debugger steps over system, framework, library, and other non-user calls. The **`/JMC`** compiler option enables support for Just My Code debugging in your native C++ code. When **`/JMC`** is enabled, the compiler inserts calls to a helper function, `__CheckForDebuggerJustMyCode`, in the function prolog. The helper function provides hooks that support Visual Studio debugger Just My Code step operations. To enable Just My Code in the Visual Studio debugger, on the menu bar, choose **Tools** > **Options**, and then set the option in **Debugging** > **General** > **Enable Just My Code**. -The **/JMC** option requires that your code links to the C Runtime Library (CRT), which provides the `__CheckForDebuggerJustMyCode` helper function. If your project does not link to the CRT, you may see linker error **LNK2019: unresolved external symbol __CheckForDebuggerJustMyCode**. To resolve this error, either link to the CRT, or disable the **/JMC** option. +The **`/JMC`** option requires that your code links to the C Runtime Library (CRT), which provides the `__CheckForDebuggerJustMyCode` helper function. If your project doesn't link to the CRT, you may see linker error **LNK2019: unresolved external symbol __CheckForDebuggerJustMyCode**. To resolve this error, either link to the CRT, or disable the **`/JMC`** option. -By default, the **/JMC** compiler option is off. However, starting in Visual Studio 2017 version 15.8 this option is enabled in most Visual Studio project templates. To explicitly disable this option, use the **/JMC-** option on the command line. In Visual Studio, open the project Property Pages dialog box, and change the **Support Just My Code Debugging** property in the **Configuration Properties** > **C/C++** > **General** property page to **No**. +When the **`/JMC`** option is enabled, the PDB file is annotated with extra line number information. In versions before Visual Studio 2019 version 16.8, this information may appear in code coverage reports as occurring at line 15732480 (0xF00F00) or 16707566 (0xFEEFEE). These fictitious line numbers are used as markers to delineate user code from non-user code. To include non-user code in code coverage reports without these unexpected line numbers, build your code with the **`/JMC-`** option. + +By default, the **`/JMC`** compiler option is off. However, starting in Visual Studio 2017 version 15.8 this option is enabled in most Visual Studio project templates. To explicitly disable this option, use the **`/JMC-`** option on the command line. In Visual Studio, open the project Property Pages dialog box, and change the **Support Just My Code Debugging** property in the **Configuration Properties** > **C/C++** > **General** property page to **No**. For more information, see [C++ Just My Code](/visualstudio/debugger/just-my-code#BKMK_C___Just_My_Code) in [Specify whether to debug only user code using Just My Code in Visual Studio](/visualstudio/debugger/just-my-code), and the Visual C++ Team Blog post [Announcing C++ Just My Code Stepping in Visual Studio](https://devblogs.microsoft.com/cppblog/announcing-jmc-stepping-in-visual-studio/). @@ -37,5 +39,5 @@ For more information, see [C++ Just My Code](/visualstudio/debugger/just-my-code ## See also -[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md)
+[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/jump-table-rdata.md b/docs/build/reference/jump-table-rdata.md new file mode 100644 index 0000000000..9cb7dd4fdc --- /dev/null +++ b/docs/build/reference/jump-table-rdata.md @@ -0,0 +1,40 @@ +--- +description: "Learn more about: /jumptablerdata (Place switch case jump tables in .rdata)" +title: "/jumptablerdata (put switch case jump tables in `.rdata`)" +ms.date: 06/02/2023 +f1_keywords: ["/jumptable"] +helpviewer_keywords: ["-jumptablerdata compiler option [C++]", "/jumptablerdata compiler option [C++]"] +--- +# /jumptablerdata (put switch case jump tables in `.rdata`) + +Puts the generated switch case jump tables in the `.rdata` section instead of alongside code in the `.text` section. + +## Syntax + +```cpp +/jumptablerdata +``` + +## Remarks + +Putting jump tables generated for switch case statements in the `.rdata` section prevents the jump table from being loaded into both the instruction cache (iCache) and data cache (dCache), potentially increasing performance. The `.rdata` section is where const initialized data is stored. + +> [!IMPORTANT] +> This flag only applies to x64 code. This flag was introduced in Visual Studio 17.7. + +### To set this compiler option in the Visual Studio development environment + +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. Modify the **Additional Options** property to include `/jumptablerdata` and then choose **OK**. + +### To set this compiler option programmatically + +- See . + +## See also + +[MSVC Compiler Options](compiler-options.md)\ +[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/keycontainer-specify-a-key-container-to-sign-an-assembly.md b/docs/build/reference/keycontainer-specify-a-key-container-to-sign-an-assembly.md index cb7054b09a..8ee29e44c0 100644 --- a/docs/build/reference/keycontainer-specify-a-key-container-to-sign-an-assembly.md +++ b/docs/build/reference/keycontainer-specify-a-key-container-to-sign-an-assembly.md @@ -23,7 +23,7 @@ The linker creates a signed assembly by inserting a public key into the assembly If you compile with [/LN](ln-create-msil-module.md), the name of the key file is held in the module and incorporated into the assembly that is created when you compile an assembly that includes an explicit reference to the module, via [#using](../../preprocessor/hash-using-directive-cpp.md), or when linking with [/ASSEMBLYMODULE](assemblymodule-add-a-msil-module-to-the-assembly.md). -You can also pass your encryption information to the compiler with [/KEYFILE](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md). Use [/DELAYSIGN](delaysign-partially-sign-an-assembly.md) if you want a partially signed assembly. See [Strong Name Assemblies (Assembly Signing) (C++/CLI)](../../dotnet/strong-name-assemblies-assembly-signing-cpp-cli.md) for more information on signing an assembly. +You can also pass your encryption information to the compiler with [/KEYFILE](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md). Use [/DELAYSIGN](delaysign-partially-sign-an-assembly.md) if you want a partially signed assembly. For more information on signing an assembly, see [Strong Name Assemblies (Assembly Signing) (C++/CLI)](../../dotnet/strong-name-assemblies-assembly-signing-cpp-cli.md). Other linker options that affect assembly generation are: diff --git a/docs/build/reference/keyfile-specify-key-or-key-pair-to-sign-an-assembly.md b/docs/build/reference/keyfile-specify-key-or-key-pair-to-sign-an-assembly.md index 2ef01ea543..3d1a74d531 100644 --- a/docs/build/reference/keyfile-specify-key-or-key-pair-to-sign-an-assembly.md +++ b/docs/build/reference/keyfile-specify-key-or-key-pair-to-sign-an-assembly.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: /KEYFILE (Specify Key or Key Pair to Sign an Assembly)" title: "/KEYFILE (Specify Key or Key Pair to Sign an Assembly)" -ms.date: "11/04/2016" +description: "Learn more about: /KEYFILE (Specify Key or Key Pair to Sign an Assembly)" +ms.date: 03/24/2025 f1_keywords: ["/keyfile", "VC.Project.VCLinkerTool.KeyFile"] helpviewer_keywords: ["/KEYFILE linker option", "-KEYFILE linker option", "KEYFILE linker option"] -ms.assetid: 9b71f8c0-541c-4fe5-a0c7-9364f42ecb06 --- -# /KEYFILE (Specify Key or Key Pair to Sign an Assembly) +# `/KEYFILE` (Specify Key or Key Pair to Sign an Assembly) ``` /KEYFILE:filename @@ -14,39 +13,33 @@ ms.assetid: 9b71f8c0-541c-4fe5-a0c7-9364f42ecb06 ## Arguments -*filename*
+*`filename`*\ File that contains the key. Place the string in double quotation marks (" ") if it contains a space. ## Remarks -The linker inserts the public key into the assembly manifest and then signs the final assembly with the private key. To generate a key file, type [sn -k](/dotnet/framework/tools/sn-exe-strong-name-tool) *filename* at the command line. A signed assembly is said to have a strong name. +The linker inserts the public key into the assembly manifest and then signs the final assembly with the private key. To generate a key file, type [`sn -k`](/dotnet/framework/tools/sn-exe-strong-name-tool) *filename* at the command line. A signed assembly is said to have a strong name. -If you compile with [/LN](ln-create-msil-module.md), the name of the key file is held in the module and incorporated into the assembly that is created when you compile an assembly that includes an explicit reference to the module, via [#using](../../preprocessor/hash-using-directive-cpp.md), or when linking with [/ASSEMBLYMODULE](assemblymodule-add-a-msil-module-to-the-assembly.md). +If you compile with [`/LN`](ln-create-msil-module.md), the name of the key file is held in the module and incorporated into the assembly that is created when you compile an assembly that includes an explicit reference to the module, via [`#using`](../../preprocessor/hash-using-directive-cpp.md), or when linking with [`/ASSEMBLYMODULE`](assemblymodule-add-a-msil-module-to-the-assembly.md). -You can also pass your encryption information to the linker with [/KEYCONTAINER](keycontainer-specify-a-key-container-to-sign-an-assembly.md). Use [/DELAYSIGN](delaysign-partially-sign-an-assembly.md) if you want a partially signed assembly. For more information on signing an assembly, see [Strong Name Assemblies (Assembly Signing) (C++/CLI)](../../dotnet/strong-name-assemblies-assembly-signing-cpp-cli.md) and [Creating and Using Strong-Named Assemblies](/dotnet/framework/app-domains/create-and-use-strong-named-assemblies). +You can also pass your encryption information to the linker with [`/KEYCONTAINER`](keycontainer-specify-a-key-container-to-sign-an-assembly.md). Use [`/DELAYSIGN`](delaysign-partially-sign-an-assembly.md) if you want a partially signed assembly. For more information on signing an assembly, see [Strong Name Assemblies (Assembly Signing) (C++/CLI)](../../dotnet/strong-name-assemblies-assembly-signing-cpp-cli.md) and [Creating and Using Strong-Named Assemblies](/dotnet/framework/app-domains/create-and-use-strong-named-assemblies). -In case both **/KEYFILE** and **/KEYCONTAINER** are specified (either by command-line option or by custom attribute), the linker will first try the key container. If that succeeds, then the assembly is signed with the information in the key container. If the linker doesn't find the key container, it will try the file specified with /KEYFILE. If that succeeds, the assembly is signed with the information in the key file and the key information will be installed in the key container (similar to sn -i) so that on the next compilation, the key container will be valid. +In case both **`/KEYFILE`** and **`/KEYCONTAINER`** are specified (either by command-line option or by custom attribute), the linker will first try the key container. If that succeeds, then the assembly is signed with the information in the key container. If the linker doesn't find the key container, it will try the file specified with /KEYFILE. If that succeeds, the assembly is signed with the information in the key file and the key information will be installed in the key container (similar to sn -i) so that on the next compilation, the key container will be valid. A key file might contain only the public key. Other linker options that affect assembly generation are: -- [/ASSEMBLYDEBUG](assemblydebug-add-debuggableattribute.md) - -- [/ASSEMBLYLINKRESOURCE](assemblylinkresource-link-to-dotnet-framework-resource.md) - -- [/ASSEMBLYMODULE](assemblymodule-add-a-msil-module-to-the-assembly.md) - -- [/ASSEMBLYRESOURCE](assemblyresource-embed-a-managed-resource.md) - -- [/NOASSEMBLY](noassembly-create-a-msil-module.md) +- [`/ASSEMBLYDEBUG`](assemblydebug-add-debuggableattribute.md) +- [`/ASSEMBLYLINKRESOURCE`](assemblylinkresource-link-to-dotnet-framework-resource.md) +- [`/ASSEMBLYMODULE`](assemblymodule-add-a-msil-module-to-the-assembly.md) +- [`/ASSEMBLYRESOURCE`](assemblyresource-embed-a-managed-resource.md) +- [`/NOASSEMBLY`](noassembly-create-a-msil-module.md) ### To set this linker option in the Visual Studio development environment 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** > **Linker** > **Command Line** property page. - 1. Enter the option into the **Additional Options** box. ### To set this linker option programmatically @@ -55,5 +48,5 @@ Other linker options that affect assembly generation are: ## See also -[MSVC linker reference](linking.md)
+[MSVC linker reference](linking.md)\ [MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/largeaddressaware-handle-large-addresses.md b/docs/build/reference/largeaddressaware-handle-large-addresses.md index e63c9bf10e..4d3910054e 100644 --- a/docs/build/reference/largeaddressaware-handle-large-addresses.md +++ b/docs/build/reference/largeaddressaware-handle-large-addresses.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: /LARGEADDRESSAWARE (Handle Large Addresses)" title: "/LARGEADDRESSAWARE (Handle Large Addresses)" -ms.date: "11/04/2016" +description: "Learn more about: /LARGEADDRESSAWARE (Handle Large Addresses)" +ms.date: "02/12/2024" f1_keywords: ["VC.Project.VCLinkerTool.LargeAddressAware", "/largeaddressaware"] helpviewer_keywords: ["LARGEADDRESSAWARE linker option", "-LARGEADDRESSAWARE linker option", "/LARGEADDRESSAWARE linker option"] -ms.assetid: a29756c8-e893-47a9-9750-1f0d25359385 --- # /LARGEADDRESSAWARE (Handle Large Addresses) @@ -14,9 +13,11 @@ ms.assetid: a29756c8-e893-47a9-9750-1f0d25359385 ## Remarks -The /LARGEADDRESSAWARE option tells the linker that the application can handle addresses larger than 2 gigabytes. In the 64-bit compilers, this option is enabled by default. In the 32-bit compilers, /LARGEADDRESSAWARE:NO is enabled if /LARGEADDRESSAWARE is not otherwise specified on the linker line. +The /LARGEADDRESSAWARE option tells the linker that the application can handle addresses larger than 2 gigabytes. In the 64-bit compilers, this option is enabled by default. In the 32-bit compilers, `/LARGEADDRESSAWARE:NO` is enabled if `/LARGEADDRESSAWARE` is not otherwise specified on the linker line. + +If an application was linked with `/LARGEADDRESSAWARE`, `DUMPBIN` [/HEADERS](headers.md) will display information to that effect. -If an application was linked with /LARGEADDRESSAWARE, DUMPBIN [/HEADERS](headers.md) will display information to that effect. +Linking 64-bit applications with **`/LARGEADDRESSAWARE:NO`** is not recommended because it restricts the available address space, which can result in runtime failures if the app exhausts memory. It may also prevent x64 apps from running on ARM64 systems because the emulation runtime will try to reserve 4GB of virtual address space. If the app was linked with `/LARGEADDRESSAWARE:NO`, the app won't launch because it can't allocate that much address space. ### To set this linker option in the Visual Studio development environment @@ -32,5 +33,5 @@ If an application was linked with /LARGEADDRESSAWARE, DUMPBIN [/HEADERS](headers ## See also -[MSVC linker reference](linking.md)
+[MSVC linker reference](linking.md)\ [MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/libpath-additional-libpath.md b/docs/build/reference/libpath-additional-libpath.md index 1ac84a5485..64cfdd3f94 100644 --- a/docs/build/reference/libpath-additional-libpath.md +++ b/docs/build/reference/libpath-additional-libpath.md @@ -1,32 +1,29 @@ --- description: "Learn more about: /LIBPATH (Additional Libpath)" title: "/LIBPATH (Additional Libpath)" -ms.date: "11/04/2016" +ms.date: 03/27/2025 f1_keywords: ["/libpath", "VC.Project.VCLinkerTool.AdditionalLibraryDirectories"] helpviewer_keywords: ["LIBPATH linker option", "/LIBPATH linker option", "Additional Libpath linker option", "environment library path override", "-LIBPATH linker option", "library path linker option"] -ms.assetid: 7240af0b-9a3d-4d53-8169-2a92cd6958ba --- -# /LIBPATH (Additional Libpath) +# `/LIBPATH` (Additional Libpath) -``` -/LIBPATH:dir -``` +## Syntax -## Parameters +> /LIBPATH:dir -*dir*
-Specifies a path that the linker will search before it searches the path specified in the LIB environment option. +## Argument + +*`dir`*\ +Specifies a path that the linker searches before it searches the path specified in the `LIB` environment option. When expanded, the fully qualified directory must not exceed `MAX_PATH` (260 characters). ## Remarks -Use the /LIBPATH option to override the environment library path. The linker will first search in the path specified by this option, and then search in the path specified in the LIB environment variable. You can specify only one directory for each /LIBPATH option you enter. If you want to specify more than one directory, you must specify multiple /LIBPATH options. The linker will then search the specified directories in order. +Use the `/LIBPATH` option to override the environment library path. The linker first searches in the path specified by this option, and then searches in the path specified in the `LIB` environment variable. You can specify only one directory for each `/LIBPATH` option you enter. To specify more than one directory, specify multiple `/LIBPATH` options. The linker searches the specified directories in order. ### To set this linker option in the Visual Studio development environment 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** > **Linker** > **General** property page. - 1. Modify the **Additional Library Directories** property. ### To set this linker option programmatically @@ -35,5 +32,5 @@ Use the /LIBPATH option to override the environment library path. The linker wil ## See also -[MSVC linker reference](linking.md)
+[MSVC linker reference](linking.md)\ [MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/link-code-for-kernel-mode.md b/docs/build/reference/link-code-for-kernel-mode.md new file mode 100644 index 0000000000..6a9d5e3901 --- /dev/null +++ b/docs/build/reference/link-code-for-kernel-mode.md @@ -0,0 +1,34 @@ +--- +description: "Learn more about: /KERNEL (Create kernel mode binary)." +title: /KERNEL +ms.date: "08/25/2023" +--- +# /KERNEL (Create kernel mode binary) + +Create a binary that is suitable for running in kernel mode. + +## Syntax + +> **`/KERNEL`** + +## Remarks + +Causes the linker to emit a warning if any object file or library linked in the binary wasn't compiled with [/kernel](kernel-create-kernel-mode-binary.md). + +Code that can run in kernel mode must be compiled with the **`/kernel`** option. If you link a binary that contains code that wasn't compiled with **`/kernel`**, the binary might not run correctly in kernel mode. + +Code for kernel mode is compiled with a simplified set of C++ language features that are specific to code that runs in kernel mode. The compiler produces warnings for C++ language features that are potentially disruptive but can't be disabled. For more information about compiling code in kernel mode, see [/kernel (Create kernel mode binary)](kernel-create-kernel-mode-binary.md). + +### To set this linker option in Visual Studio + +1. Open the project **Property Pages** dialog box. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. + +1. In **Additional Options**, enter `/KERNELMODE`. + +## See also + +- [MSVC linker reference](linking.md) +- [MSVC linker options](linker-options.md) +- [Compiler options: /kernel](kernel-create-kernel-mode-binary.md) \ No newline at end of file diff --git a/docs/build/reference/link-input-files.md b/docs/build/reference/link-input-files.md index 793f81974a..80664636c6 100644 --- a/docs/build/reference/link-input-files.md +++ b/docs/build/reference/link-input-files.md @@ -1,42 +1,42 @@ --- description: "Learn more about: LINK Input Files" title: "LINK Input Files" -ms.date: "11/04/2016" +ms.date: 09/01/2022 helpviewer_keywords: ["files [C++], LINK", "module definition files", "resources [C++], linker files", "LINK tool [C++], input files", "module definition files, linker files", "input files [C++], LINK", "linker [C++], input files", "import libraries [C++], linker files", "command input to linker files [C++]"] ms.assetid: bb26fcc5-509a-4620-bc3e-b6c6e603a412 --- -# LINK Input Files +# LINK input files -You provide the linker with files that contain objects, import and standard libraries, resources, module definitions, and command input. LINK does not use file extensions to make assumptions about the contents of a file. Instead, LINK examines each input file to determine what kind of file it is. +You provide the linker with files that contain objects, import and standard libraries, resources, module definitions, and command input. LINK doesn't use file extensions to make assumptions about the contents of a file. Instead, LINK examines each input file to determine what kind of file it is. -Object files on the command line are processed in the order they appear on the command line. Libraries are searched in command line order as well, with the following caveat: Symbols that are unresolved when bringing in an object file from a library are searched for in that library first, and then the following libraries from the command line and [/DEFAULTLIB (Specify Default Library)](defaultlib-specify-default-library.md) directives, and then to any libraries at the beginning of the command line. +Object files on the command line are processed in the order they appear on the command line. Libraries are searched in command line order as well, with the following caveat: Symbols that are unresolved when bringing in an object file from a library are searched for in that library first, and then the following libraries from the command line and [`/DEFAULTLIB` (Specify default library)](defaultlib-specify-default-library.md) directives, and then to any libraries at the beginning of the command line. > [!NOTE] -> LINK no longer accepts a semicolon (or any other character) as the start of a comment in response files and order files. Semicolons are recognized only as the start of comments in module-definition files (.def). +> LINK no longer accepts a semicolon (or any other character) as the start of a comment in response files and order files. Semicolons are recognized only as the start of comments in module-definition files (`.def`). LINK uses the following types of input files: -- [.obj files](dot-obj-files-as-linker-input.md) +- [`.obj` files](dot-obj-files-as-linker-input.md) -- [.netmodule files](netmodule-files-as-linker-input.md) +- [`.netmodule` files](netmodule-files-as-linker-input.md) -- [.lib files](dot-lib-files-as-linker-input.md) +- [`.lib` files](dot-lib-files-as-linker-input.md) -- [.exp files](dot-exp-files-as-linker-input.md) +- [`.exp` files](dot-exp-files-as-linker-input.md) -- [.def files](dot-def-files-as-linker-input.md) +- [`.def` files](dot-def-files-as-linker-input.md) -- [.pdb files](dot-pdb-files-as-linker-input.md) +- [`.pdb` files](dot-pdb-files-as-linker-input.md) -- [.res files](dot-res-files-as-linker-input.md) +- [`.res` files](dot-res-files-as-linker-input.md) -- [.exe files](dot-exe-files-as-linker-input.md) +- [`.exe` files](dot-exe-files-as-linker-input.md) -- [.txt files](dot-txt-files-as-linker-input.md) +- [`.txt` files](dot-txt-files-as-linker-input.md) -- [.ilk files](dot-ilk-files-as-linker-input.md) +- [`.ilk` files](dot-ilk-files-as-linker-input.md) ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/link-repro-full-path-rsp.md b/docs/build/reference/link-repro-full-path-rsp.md new file mode 100644 index 0000000000..c08892e4c7 --- /dev/null +++ b/docs/build/reference/link-repro-full-path-rsp.md @@ -0,0 +1,51 @@ +--- +description: "Learn more about: /LINKREPROFULLPATHRSP (Generate file containing absolute paths of linked files)" +title: "/LINKREPROFULLPATHRSP (Generate file containing absolute paths of linked files)" +ms.date: 03/27/2025 +f1_keywords: ["VC.Project.VCLinkerTool.LinkReproFullPathRSP", "/LINKREPROFULLPATHRSP"] +helpviewer_keywords: ["/LINKREPROFULLPATHRSP linker option", "-LINKREPROFULLPATHRSP linker option", "LINKREPROFULLPATHRSP linker option"] +--- +# `/LINKREPROFULLPATHRSP` (Generate file containing absolute paths of linked files) + +Generates a response file (`.RSP`) containing the absolute paths of all the files the linker took as input. + +This flag was introduced in Visual Studio 2022 version 17.11. + +## Syntax + +> **/LINKREPROFULLPATHRSP:filename** + +## Argument + +*`filename`*\ +Specifies the name of the response file to create. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). + +## Remarks + +Rather than generate a full link repro like `/LINKREPRO`, which copies all the files to a directory and creates a response file with relative paths to that directory, this option writes the names of the files used during linking to the specified file. + +For example, given: +- a directory `c:\temp\test` that contains the files `test.cpp`, `f1.cpp`, `f2.cpp` +- the linker command line: `link f1.obj f2.obj test.obj /out:test.exe /LINKREPROFULLPATHRSP:test.rsp` +The linker produces `test.rsp` containing the following lines to reflect the fully qualified paths of the input files: + +```cmd +"c:\temp\test\f1.obj" +"c:\temp\test\f2.obj" +"c:\temp\test\test.obj" +``` + +### To set this linker option in the Visual Studio development environment + +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** > **Linker** > **Command Line** property page. +1. Enter *`/LINKREPROFULLPATHRSP:file.rsp`* into **Additional Options**. Choose **OK** or **Apply** to apply the change. + +### To set this linker option programmatically + +- See [VCLinkerTool.AdditionalOptions](/dotnet/api/microsoft.visualstudio.vcprojectengine.vclinkertool.additionaloptions) + +## See also + +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/linker-options.md b/docs/build/reference/linker-options.md index 4fb8cbd463..5749d0c236 100644 --- a/docs/build/reference/linker-options.md +++ b/docs/build/reference/linker-options.md @@ -1,136 +1,140 @@ --- title: "MSVC Linker options" description: "A list of the options supported by the Microsoft LINK linker." -ms.date: "09/01/2020" +ms.date: 03/14/2025 f1_keywords: ["link"] helpviewer_keywords: ["linker [C++]", "linker [C++], options listed", "libraries [C++], linking to COFF", "LINK tool [C++], linker options"] -ms.assetid: c1d51b8a-bd23-416d-81e4-900e02b2c129 --- # Linker options -LINK.exe links Common Object File Format (COFF) object files and libraries to create an executable (.exe) file or a dynamic-link library (DLL). +LINK.exe links Common Object File Format (COFF) object files and libraries to create an executable (EXE) file or a dynamic-link library (DLL). -The following table lists options for LINK.exe. For more information about LINK, see: +The following table lists options for `LINK.exe`. For more information about LINK, see: -- [Compiler-Controlled LINK Options](compiler-controlled-link-options.md) +- [Compiler-controlled LINK options](compiler-controlled-link-options.md) +- [LINK input files](link-input-files.md) +- [LINK output](link-output.md) +- [Reserved words](reserved-words.md) -- [LINK Input Files](link-input-files.md) +Linker options aren't case-sensitive; for example, `/base` and `/BASE` mean the same thing. For details on how to specify each option on the command line or in Visual Studio, see the documentation for that option. -- [LINK Output](link-output.md) - -- [Reserved Words](reserved-words.md) - -On the command line, linker options aren't case-sensitive; for example, `/base` and `/BASE` mean the same thing. For details on how to specify each option on the command line or in Visual Studio, see the documentation for that option. - -You can use the [comment](../../preprocessor/comment-c-cpp.md) pragma to specify some linker options. +You can use the [`comment`](../../preprocessor/comment-c-cpp.md) pragma to specify some linker options. ## Linker options listed alphabetically -|Option|Purpose| -|------------|-------------| -|[@](at-specify-a-linker-response-file.md)|Specifies a response file.| -|[/ALIGN](align-section-alignment.md)|Specifies the alignment of each section.| -|[/ALLOWBIND](allowbind-prevent-dll-binding.md)|Specifies that a DLL can't be bound.| -|[/ALLOWISOLATION](allowisolation-manifest-lookup.md)|Specifies behavior for manifest lookup.| -|[/APPCONTAINER](appcontainer-windows-store-app.md)|Specifies whether the app must run within an appcontainer process environment.| -|[/ASSEMBLYDEBUG](assemblydebug-add-debuggableattribute.md)|Adds the to a managed image.| -|[/ASSEMBLYLINKRESOURCE](assemblylinkresource-link-to-dotnet-framework-resource.md)|Creates a link to a managed resource.| -|[/ASSEMBLYMODULE](assemblymodule-add-a-msil-module-to-the-assembly.md)|Specifies that a Microsoft intermediate language (MSIL) module should be imported into the assembly.| -|[/ASSEMBLYRESOURCE](assemblyresource-embed-a-managed-resource.md)|Embeds a managed resource file in an assembly.| -|[/BASE](base-base-address.md)|Sets a base address for the program.| -|[/CETCOMPAT](cetcompat.md)|Marks the binary as CET Shadow Stack compatible.| -|[/CGTHREADS](cgthreads-compiler-threads.md)|Sets number of cl.exe threads to use for optimization and code generation when link-time code generation is specified.| -|[/CLRIMAGETYPE](clrimagetype-specify-type-of-clr-image.md)|Sets the type (IJW, pure, or safe) of a CLR image.| -|[/CLRSUPPORTLASTERROR](clrsupportlasterror-preserve-last-error-code-for-pinvoke-calls.md)|Preserves the last error code of functions that are called through the P/Invoke mechanism.| -|[/CLRTHREADATTRIBUTE](clrthreadattribute-set-clr-thread-attribute.md)|Specifies the threading attribute to apply to the entry point of your CLR program.| -|[/CLRUNMANAGEDCODECHECK](clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md)|Specifies whether the linker will apply the SuppressUnmanagedCodeSecurity attribute to linker-generated PInvoke stubs that call from managed code into native DLLs.| -|[/DEBUG](debug-generate-debug-info.md)|Creates debugging information.| -|[/DEBUGTYPE](debugtype-debug-info-options.md)|Specifies which data to include in debugging information.| -|[/DEF](def-specify-module-definition-file.md)|Passes a module-definition (.def) file to the linker.| -|[/DEFAULTLIB](defaultlib-specify-default-library.md)|Searches the specified library when external references are resolved.| -|[/DELAY](delay-delay-load-import-settings.md)|Controls the delayed loading of DLLs.| -|[/DELAYLOAD](delayload-delay-load-import.md)|Causes the delayed loading of the specified DLL.| -|[/DELAYSIGN](delaysign-partially-sign-an-assembly.md)|Partially signs an assembly.| -|[/DEPENDENTLOADFLAG](dependentloadflag.md)|Sets default flags on dependent DLL loads.| -|[/DLL](dll-build-a-dll.md)|Builds a DLL.| -|[/DRIVER](driver-windows-nt-kernel-mode-driver.md)|Creates a kernel mode driver.| -|[/DYNAMICBASE](dynamicbase-use-address-space-layout-randomization.md)|Specifies whether to generate an executable image that's rebased at load time by using the address space layout randomization (ASLR) feature.| -|[/ENTRY](entry-entry-point-symbol.md)|Sets the starting address.| -|[/ERRORREPORT](errorreport-report-internal-linker-errors.md)| Deprecated. Error reporting is controlled by [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings. | -|[/EXPORT](export-exports-a-function.md)|Exports a function.| -|[/FILEALIGN](filealign.md)|Aligns sections within the output file on multiples of a specified value.| -|[/FIXED](fixed-fixed-base-address.md)|Creates a program that can be loaded only at its preferred base address.| -|[/FORCE](force-force-file-output.md)|Forces a link to complete even with unresolved symbols or symbols defined more than once.| -|[/FUNCTIONPADMIN](functionpadmin-create-hotpatchable-image.md)|Creates an image that can be hot patched.| -|[/GENPROFILE, /FASTGENPROFILE](genprofile-fastgenprofile-generate-profiling-instrumented-build.md)|Both of these options specify generation of a *`.pgd`* file by the linker to support profile-guided optimization (PGO). /GENPROFILE and /FASTGENPROFILE use different default parameters.| -|[/GUARD](guard-enable-guard-checks.md)|Enables Control Flow Guard protection.| -|[/HEAP](heap-set-heap-size.md)|Sets the size of the heap, in bytes.| -|[/HIGHENTROPYVA](highentropyva-support-64-bit-aslr.md)|Specifies support for high-entropy 64-bit address space layout randomization (ASLR).| -|[/IDLOUT](idlout-name-midl-output-files.md)|Specifies the name of the *`.idl`* file and other MIDL output files.| -|[/IGNORE](ignore-ignore-specific-warnings.md)|Suppresses output of specified linker warnings.| -|[/IGNOREIDL](ignoreidl-don-t-process-attributes-into-midl.md)|Prevents the processing of attribute information into an *`.idl`* file.| -|[/IMPLIB](implib-name-import-library.md)|Overrides the default import library name.| -|[/INCLUDE](include-force-symbol-references.md)|Forces symbol references.| -|[/INCREMENTAL](incremental-link-incrementally.md)|Controls incremental linking.| -|[/INFERASANLIBS](inferasanlibs.md)|Uses inferred sanitizer libraries.| -|[/INTEGRITYCHECK](integritycheck-require-signature-check.md)|Specifies that the module requires a signature check at load time.| -|[/KEYCONTAINER](keycontainer-specify-a-key-container-to-sign-an-assembly.md)|Specifies a key container to sign an assembly.| -|[/KEYFILE](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md)|Specifies a key or key pair to sign an assembly.| -|[/LARGEADDRESSAWARE](largeaddressaware-handle-large-addresses.md)|Tells the compiler that the application supports addresses larger than two gigabytes| -|[/LIBPATH](libpath-additional-libpath.md)|Specifies a path to search before the environmental library path.| -|[/LINKREPRO](linkrepro.md)|Specifies a path to generate link repro artifacts in.| -|[/LINKREPROTARGET](linkreprotarget.md)|Generates a link repro only when producing the specified target.16.1| -|[/LTCG](ltcg-link-time-code-generation.md)|Specifies link-time code generation.| -|[/MACHINE](machine-specify-target-platform.md)|Specifies the target platform.| -|[/MANIFEST](manifest-create-side-by-side-assembly-manifest.md)|Creates a side-by-side manifest file and optionally embeds it in the binary.| -|[/MANIFESTDEPENDENCY](manifestdependency-specify-manifest-dependencies.md)|Specifies a \ section in the manifest file.| -|[/MANIFESTFILE](manifestfile-name-manifest-file.md)|Changes the default name of the manifest file.| -|[/MANIFESTINPUT](manifestinput-specify-manifest-input.md)|Specifies a manifest input file for the linker to process and embed in the binary. You can use this option multiple times to specify more than one manifest input file.| -|[/MANIFESTUAC](manifestuac-embeds-uac-information-in-manifest.md)|Specifies whether User Account Control (UAC) information is embedded in the program manifest.| -|[/MAP](map-generate-mapfile.md)|Creates a mapfile.| -|[/MAPINFO](mapinfo-include-information-in-mapfile.md)|Includes the specified information in the mapfile.| -|[/MERGE](merge-combine-sections.md)|Combines sections.| -|[/MIDL](midl-specify-midl-command-line-options.md)|Specifies MIDL command-line options.| -|[/NATVIS](natvis-add-natvis-to-pdb.md)|Adds debugger visualizers from a Natvis file to the program database (PDB).| -|[/NOASSEMBLY](noassembly-create-a-msil-module.md)|Suppresses the creation of a .NET Framework assembly.| -|[/NODEFAULTLIB](nodefaultlib-ignore-libraries.md)|Ignores all (or the specified) default libraries when external references are resolved.| -|[/NOENTRY](noentry-no-entry-point.md)|Creates a resource-only DLL.| -|[/NOLOGO](nologo-suppress-startup-banner-linker.md)|Suppresses the startup banner.| -|[/NXCOMPAT](nxcompat-compatible-with-data-execution-prevention.md)|Marks an executable as verified to be compatible with the Windows Data Execution Prevention feature.| -|[/OPT](opt-optimizations.md)|Controls LINK optimizations.| -|[/ORDER](order-put-functions-in-order.md)|Places COMDATs into the image in a predetermined order.| -|[/OUT](out-output-file-name.md)|Specifies the output file name.| -|[/PDB](pdb-use-program-database.md)|Creates a PDB file.| -|[/PDBALTPATH](pdbaltpath-use-alternate-pdb-path.md)|Uses an alternate location to save a PDB file.| -|[/PDBSTRIPPED](pdbstripped-strip-private-symbols.md)|Creates a PDB file that has no private symbols.| -|[/PGD](pgd-specify-database-for-profile-guided-optimizations.md)|Specifies a *`.pgd`* file for profile-guided optimizations.| -|[/POGOSAFEMODE](pogosafemode-linker-option.md)|**Obsolete** Creates a thread-safe PGO instrumented build.| -|[/PROFILE](profile-performance-tools-profiler.md)|Produces an output file that can be used with the Performance Tools profiler.| -|[/RELEASE](release-set-the-checksum.md)|Sets the Checksum in the *`.exe`* header.| -|[/SAFESEH](safeseh-image-has-safe-exception-handlers.md)|Specifies that the image will contain a table of safe exception handlers.| -|[/SECTION](section-specify-section-attributes.md)|Overrides the attributes of a section.| -|[/SOURCELINK](sourcelink.md)|Specifies a SourceLink file to add to the PDB.| -|[/STACK](stack-stack-allocations.md)|Sets the size of the stack in bytes.| -|[/STUB](stub-ms-dos-stub-file-name.md)|Attaches an MS-DOS stub program to a Win32 program.| -|[/SUBSYSTEM](subsystem-specify-subsystem.md)|Tells the operating system how to run the *`.exe`* file.| -|[/SWAPRUN](swaprun-load-linker-output-to-swap-file.md)|Tells the operating system to copy the linker output to a swap file before it's run.| -|[/TLBID](tlbid-specify-resource-id-for-typelib.md)|Specifies the resource ID of the linker-generated type library.| -|[/TLBOUT](tlbout-name-dot-tlb-file.md)|Specifies the name of the *`.tlb`* file and other MIDL output files.| -|[/TSAWARE](tsaware-create-terminal-server-aware-application.md)|Creates an application that is designed specifically to run under Terminal Server.| -|[/USEPROFILE](useprofile.md)|Uses profile-guided optimization training data to create an optimized image.| -|[/VERBOSE](verbose-print-progress-messages.md)|Prints linker progress messages.| -|[/VERSION](version-version-information.md)|Assigns a version number.| -|[/WHOLEARCHIVE](wholearchive-include-all-library-object-files.md)|Includes every object file from specified static libraries.| -|[/WINMD](winmd-generate-windows-metadata.md)|Enables generation of a Windows Runtime Metadata file.| -|[/WINMDFILE](winmdfile-specify-winmd-file.md)|Specifies the file name for the Windows Runtime Metadata (winmd) output file that's generated by the [/WINMD](winmd-generate-windows-metadata.md) linker option.| -|[/WINMDKEYFILE](winmdkeyfile-specify-winmd-key-file.md)|Specifies a key or key pair to sign a Windows Runtime Metadata file.| -|[/WINMDKEYCONTAINER](winmdkeycontainer-specify-key-container.md)|Specifies a key container to sign a Windows Metadata file.| -|[/WINMDDELAYSIGN](winmddelaysign-partially-sign-a-winmd.md)|Partially signs a Windows Runtime Metadata (.winmd) file by placing the public key in the winmd file.| -|[/WX](wx-treat-linker-warnings-as-errors.md)|Treats linker warnings as errors.| +| Option | Purpose | +|--|--| +| [`@`](at-specify-a-linker-response-file.md) | Specifies a response file. | +| [`/ALIGN`](align-section-alignment.md) | Specifies the alignment of each section. | +| [`/ALLOWBIND`](allowbind-prevent-dll-binding.md) | Specifies that a DLL can't be bound. | +| [`/ALLOWISOLATION`](allowisolation-manifest-lookup.md) | Specifies behavior for manifest lookup. | +| [`/APPCONTAINER`](appcontainer-windows-store-app.md) | Specifies whether the app must run within an appcontainer process environment. | +| [`/ARM64XFUNCTIONPADMINX64`](arm64-function-pad-min-x64.md) | Specifies the minimum number of bytes of padding between x64 functions in ARM64X images.17.8 | +| [`/ASSEMBLYDEBUG`](assemblydebug-add-debuggableattribute.md) | Adds the to a managed image. | +| [`/ASSEMBLYLINKRESOURCE`](assemblylinkresource-link-to-dotnet-framework-resource.md) | Creates a link to a managed resource. | +| [`/ASSEMBLYMODULE`](assemblymodule-add-a-msil-module-to-the-assembly.md) | Specifies that a Microsoft intermediate language (MSIL) module should be imported into the assembly. | +| [`/ASSEMBLYRESOURCE`](assemblyresource-embed-a-managed-resource.md) | Embeds a managed resource file in an assembly. | +| [`/BASE`](base-base-address.md) | Sets a base address for the program. | +| [`/CETCOMPAT`](cetcompat.md) | Marks the binary as CET Shadow Stack compatible. | +| [`/CGTHREADS`](cgthreads-compiler-threads.md) | Sets number of cl.exe threads to use for optimization and code generation when link-time code generation is specified. | +| [`/CLRIMAGETYPE`](clrimagetype-specify-type-of-clr-image.md) | Sets the type (IJW, pure, or safe) of a CLR image. | +| [`/CLRSUPPORTLASTERROR`](clrsupportlasterror-preserve-last-error-code-for-pinvoke-calls.md) | Preserves the last error code of functions that are called through the P/Invoke mechanism. | +| [`/CLRTHREADATTRIBUTE`](clrthreadattribute-set-clr-thread-attribute.md) | Specifies the threading attribute to apply to the entry point of your CLR program. | +| [`/CLRUNMANAGEDCODECHECK`](clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md) | Specifies whether the linker applies the `SuppressUnmanagedCodeSecurity` attribute to linker-generated P/Invoke stubs that call from managed code into native DLLs. | +| [`/DEBUG`](debug-generate-debug-info.md) | Creates debugging information. | +| [`/DEBUGTYPE`](debugtype-debug-info-options.md) | Specifies which data to include in debugging information. | +| [`/DEF`](def-specify-module-definition-file.md) | Passes a module-definition (.def) file to the linker. | +| [`/DEFAULTLIB`](defaultlib-specify-default-library.md) | Searches the specified library when external references are resolved. | +| [`/DELAY`](delay-delay-load-import-settings.md) | Controls the delayed loading of DLLs. | +| [`/DELAYLOAD`](delayload-delay-load-import.md) | Causes the delayed loading of the specified DLL. | +| [`/DELAYSIGN`](delaysign-partially-sign-an-assembly.md) | Partially signs an assembly. | +| [`/DEPENDENTLOADFLAG`](dependentloadflag.md) | Sets default flags on dependent DLL loads. | +| [`/DLL`](dll-build-a-dll.md) | Builds a DLL. | +| [`/DRIVER`](driver-windows-nt-kernel-mode-driver.md) | Creates a kernel mode driver. | +| [`/DYNAMICBASE`](dynamicbase-use-address-space-layout-randomization.md) | Specifies whether to generate an executable image that's rebased at load time by using the address space layout randomization (ASLR) feature. | +| [`/DYNAMICDEOPT`](dynamic-deopt-linker.md) | Enable [C++ Dynamic Debugging (Preview)](/visualstudio/debugger/cpp-dynamic-debugging) and step in anywhere with on-demand function deoptimization. | +| [`/ENTRY`](entry-entry-point-symbol.md) | Sets the starting address. | +| [`/ERRORREPORT`](errorreport-report-internal-linker-errors.md) | Deprecated. Error reporting is controlled by [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings. | +| [`/EXPORT`](export-exports-a-function.md) | Exports a function. | +| [`/FILEALIGN`](filealign.md) | Aligns sections within the output file on multiples of a specified value. | +| [`/FIXED`](fixed-fixed-base-address.md) | Creates a program that can be loaded only at its preferred base address. | +| [`/FORCE`](force-force-file-output.md) | Forces a link to complete even with unresolved symbols or symbols defined more than once. | +| [`/FUNCTIONPADMIN`](functionpadmin-create-hotpatchable-image.md) | Creates an image that can be hot patched. | +| [`/GENPROFILE`, `/FASTGENPROFILE`](genprofile-fastgenprofile-generate-profiling-instrumented-build.md) | Both of these options specify generation of a *`.pgd`* file by the linker to support profile-guided optimization (PGO). /GENPROFILE and /FASTGENPROFILE use different default parameters. | +| [`/GUARD`](guard-enable-guard-checks.md) | Enables Control Flow Guard protection. | +| [`/HEAP`](heap-set-heap-size.md) | Sets the size of the heap, in bytes. | +| [`/HIGHENTROPYVA`](highentropyva-support-64-bit-aslr.md) | Specifies support for high-entropy 64-bit address space layout randomization (ASLR). | +| [`/IDLOUT`](idlout-name-midl-output-files.md) | Specifies the name of the *`.idl`* file and other MIDL output files. | +| [`/IGNORE`](ignore-ignore-specific-warnings.md) | Suppresses output of specified linker warnings. | +| [`/IGNOREIDL`](ignoreidl-don-t-process-attributes-into-midl.md) | Prevents the processing of attribute information into an *`.idl`* file. | +| [`/ILK`](ilk-name-incremental-database-file.md) | Overrides the default incremental database file name. | +| [`/IMPLIB`](implib-name-import-library.md) | Overrides the default import library name. | +| [`/INCLUDE`](include-force-symbol-references.md) | Forces symbol references. | +| [`/INCREMENTAL`](incremental-link-incrementally.md) | Controls incremental linking. | +| [`/INFERASANLIBS`](inferasanlibs.md) | Uses inferred sanitizer libraries. | +| [`/INTEGRITYCHECK`](integritycheck-require-signature-check.md) | Specifies that the module requires a signature check at load time. | +| [`/KERNEL`](link-code-for-kernel-mode.md) | Create a kernel mode binary. | +| [`/KEYCONTAINER`](keycontainer-specify-a-key-container-to-sign-an-assembly.md) | Specifies a key container to sign an assembly. | +| [`/KEYFILE`](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md) | Specifies a key or key pair to sign an assembly. | +| [`/LARGEADDRESSAWARE`](largeaddressaware-handle-large-addresses.md) | Tells the compiler that the application supports addresses larger than 2 gigabytes | +| [`/LIBPATH`](libpath-additional-libpath.md) | Specifies a path to search before the environmental library path. | +| [`/LINKREPRO`](linkrepro.md) | Specifies a path to generate link repro artifacts in. | +| [`/LINKREPROFULLPATHRSP`](link-repro-full-path-rsp.md) | Generates a response file containing the absolute paths to all the files that the linker took as input. | +| [`/LINKREPROTARGET`](linkreprotarget.md) | Generates a link repro only when producing the specified target.16.1 | +| [`/LTCG`](ltcg-link-time-code-generation.md) | Specifies link-time code generation. | +| [`/MACHINE`](machine-specify-target-platform.md) | Specifies the target platform. | +| [`/MANIFEST`](manifest-create-side-by-side-assembly-manifest.md) | Creates a side-by-side manifest file and optionally embeds it in the binary. | +| [`/MANIFESTDEPENDENCY`](manifestdependency-specify-manifest-dependencies.md) | Specifies a \ section in the manifest file. | +| [`/MANIFESTFILE`](manifestfile-name-manifest-file.md) | Changes the default name of the manifest file. | +| [`/MANIFESTINPUT`](manifestinput-specify-manifest-input.md) | Specifies a manifest input file for the linker to process and embed in the binary. You can use this option multiple times to specify more than one manifest input file. | +| [`/MANIFESTUAC`](manifestuac-embeds-uac-information-in-manifest.md) | Specifies whether User Account Control (UAC) information is embedded in the program manifest. | +| [`/MAP`](map-generate-mapfile.md) | Creates a mapfile. | +| [`/MAPINFO`](mapinfo-include-information-in-mapfile.md) | Includes the specified information in the mapfile. | +| [`/MERGE`](merge-combine-sections.md) | Combines sections. | +| [`/MIDL`](midl-specify-midl-command-line-options.md) | Specifies MIDL command-line options. | +| [`/NATVIS`](natvis-add-natvis-to-pdb.md) | Adds debugger visualizers from a Natvis file to the program database (PDB). | +| [`/NOASSEMBLY`](noassembly-create-a-msil-module.md) | Suppresses the creation of a .NET Framework assembly. | +| [`/NODEFAULTLIB`](nodefaultlib-ignore-libraries.md) | Ignores all (or the specified) default libraries when external references are resolved. | +| [`/NOENTRY`](noentry-no-entry-point.md) | Creates a resource-only DLL. | +| [`/NOFUNCTIONPADSECTION`](no-function-pad-section.md) | Disables function padding for functions in the specified section.17.8 | +| [`/NOLOGO`](nologo-suppress-startup-banner-linker.md) | Suppresses the startup banner. | +| [`/NXCOMPAT`](nxcompat-compatible-with-data-execution-prevention.md) | Marks an executable as verified to be compatible with the Windows Data Execution Prevention feature. | +| [`/OPT`](opt-optimizations.md) | Controls LINK optimizations. | +| [`/ORDER`](order-put-functions-in-order.md) | Places COMDATs into the image in a predetermined order. | +| [`/OUT`](out-output-file-name.md) | Specifies the output file name. | +| [`/PDB`](pdb-use-program-database.md) | Creates a PDB file. | +| [`/PDBALTPATH`](pdbaltpath-use-alternate-pdb-path.md) | Uses an alternate location to save a PDB file. | +| [`/PDBSTRIPPED`](pdbstripped-strip-private-symbols.md) | Creates a PDB file that has no private symbols. | +| [`/PGD`](pgd-specify-database-for-profile-guided-optimizations.md) | Specifies a *`.pgd`* file for profile-guided optimizations. | +| [`/POGOSAFEMODE`](pogosafemode-linker-option.md) | **Obsolete** Creates a thread-safe PGO instrumented build. | +| [`/PROFILE`](profile-performance-tools-profiler.md) | Produces an output file that can be used with the Performance Tools profiler. | +| [`/RELEASE`](release-set-the-checksum.md) | Sets the Checksum in the *`.exe`* header. | +| [`/SAFESEH`](safeseh-image-has-safe-exception-handlers.md) | Specifies that the image will contain a table of safe exception handlers. | +| [`/SECTION`](section-specify-section-attributes.md) | Overrides the attributes of a section. | +| [`/SOURCELINK`](sourcelink.md) | Specifies a SourceLink file to add to the PDB. | +| [`/STACK`](stack-stack-allocations.md) | Sets the size of the stack in bytes. | +| [`/STUB`](stub-ms-dos-stub-file-name.md) | Attaches an MS-DOS stub program to a Win32 program. | +| [`/SUBSYSTEM`](subsystem-specify-subsystem.md) | Tells the operating system how to run the *`.exe`* file. | +| [`/SWAPRUN`](swaprun-load-linker-output-to-swap-file.md) | Tells the operating system to copy the linker output to a swap file before it's run. | +| [`/TIME`](time-linker-time-information.md) | Output linker pass timing information. | +| [`/TLBID`](tlbid-specify-resource-id-for-typelib.md) | Specifies the resource ID of the linker-generated type library. | +| [`/TLBOUT`](tlbout-name-dot-tlb-file.md) | Specifies the name of the *`.tlb`* file and other MIDL output files. | +| [`/TSAWARE`](tsaware-create-terminal-server-aware-application.md) | Creates an application that is designed specifically to run under Terminal Server. | +| [`/USEPROFILE`](useprofile.md) | Uses profile-guided optimization training data to create an optimized image. | +| [`/VERBOSE`](verbose-print-progress-messages.md) | Prints linker progress messages. | +| [`/VERSION`](version-version-information.md) | Assigns a version number. | +| [`/WHOLEARCHIVE`](wholearchive-include-all-library-object-files.md) | Includes every object file from specified static libraries. | +| [`/WINMD`](winmd-generate-windows-metadata.md) | Enables generation of a Windows Runtime Metadata file. | +| [`/WINMDFILE`](winmdfile-specify-winmd-file.md) | Specifies the file name for the Windows Runtime Metadata (winmd) output file that's generated by the [`/WINMD`](winmd-generate-windows-metadata.md) linker option. | +| [`/WINMDKEYFILE`](winmdkeyfile-specify-winmd-key-file.md) | Specifies a key or key pair to sign a Windows Runtime Metadata file. | +| [`/WINMDKEYCONTAINER`](winmdkeycontainer-specify-key-container.md) | Specifies a key container to sign a Windows Metadata file. | +| [`/WINMDDELAYSIGN`](winmddelaysign-partially-sign-a-winmd.md) | Partially signs a Windows Runtime Metadata (*`.winmd`*) file by placing the public key in the winmd file. | +| [`/WX`](wx-treat-linker-warnings-as-errors.md) | Treats linker warnings as errors. | -16.1 This option is available starting in Visual Studio 2019 version 16.1. +16.1 This option is available starting in Visual Studio 2019 version 16.1.\ +17.8 This option is available starting in Visual Studio 2022 version 17.8. ## See also -[C/C++ Building Reference](c-cpp-building-reference.md)\ +[C/C++ building reference](c-cpp-building-reference.md)\ [MSVC linker reference](linking.md) diff --git a/docs/build/reference/linker-property-pages.md b/docs/build/reference/linker-property-pages.md index b198808f57..27a8a52d11 100644 --- a/docs/build/reference/linker-property-pages.md +++ b/docs/build/reference/linker-property-pages.md @@ -1,9 +1,9 @@ --- -description: "Learn more about: Linker Property Pages" title: "Linker Property Pages" -ms.date: "07/24/2019" +description: "Learn more about: Linker Property Pages" +ms.date: 09/07/2022 ms.topic: "article" -ms.assetid: 7e7671e5-a35a-4e67-9bdb-661d75c4d11e +f1_keywords: ["VC.Project.VCLinkerTool.IgnoreImportLibrary", "VC.Project.VCLinkerTool.RegisterOutput", "VC.Project.VCLinkerTool.PerUserRedirection", "VC.Project.VCLinkerTool.LinkLibraryDependencies", "VC.Project.VCLinkerTool.UseLibraryDependencyInputs"] --- # Linker Property Pages @@ -13,7 +13,7 @@ The following properties are found under **Project** > **Properties** > **Config ### Output File -The [/OUT](out-output-file-name.md) option overrides the default name and location of the program that the linker creates. +The [`/OUT`](out-output-file-name.md) option overrides the default name and location of the program that the linker creates. ### Show Progress @@ -31,150 +31,150 @@ Prints Linker Progress Messages ### Version -The [/VERSION](version-version-information.md) option tells the linker to put a version number in the header of the .exe or .dll file. Use DUMPBIN /HEADERS to see the image version field of the OPTIONAL HEADER VALUES to see the effect of **/VERSION**. +The [`/VERSION`](version-version-information.md) option tells the linker to put a version number in the header of the *`.exe`* or *`.dll`* file. Use `DUMPBIN /HEADERS` to see the image version field of the `OPTIONAL HEADER VALUES` to see the effect of **`/VERSION`**. ### Enable Incremental Linking -Enables incremental linking. ([/INCREMENTAL](incremental-link-incrementally.md), /INCREMENTAL:NO) +Enables incremental linking. ([`/INCREMENTAL, /INCREMENTAL:NO`](incremental-link-incrementally.md)) ### Suppress Startup Banner -The [/NOLOGO](nologo-suppress-startup-banner-linker.md) option prevents display of the copyright message and version number. +The [`/NOLOGO`](nologo-suppress-startup-banner-linker.md) option prevents display of the copyright message and version number. ### Ignore Import Library -This property tells the linker not to link any .lib output generated from this build into any dependent project. It allows the project system to handle .dll files that don't produce a .lib file when built. If a project depends on another project that produces a DLL, the project system automatically links the .lib file produced by that child project. This property may be unnecessary in projects that produce COM DLLs or resource-only DLLs, because these DLLs don't have any meaningful exports. If a DLL has no exports, the linker doesn't generate a .lib file. If no export .lib file is present, and the project system tells the linker to link with the missing DLL, the link fails. Use the **Ignore Import Library** property to resolve this problem. When set to **Yes**, the project system ignores the presence or absence of the .lib file, and causes any project that depends on this project to not link with the nonexistent .lib file. +This property tells the linker not to link any *`.lib`* output generated from this build into any dependent project. It allows the project system to handle *`.dll`* files that don't produce a *`.lib`* file when built. If a project depends on another project that produces a DLL, the project system automatically links the *`.lib`* file produced by that child project. This property may be unnecessary in projects that produce COM DLLs or resource-only DLLs, because these DLLs don't have any meaningful exports. If a DLL has no exports, the linker doesn't generate a *`.lib`* file. If no export *`.lib`* file is present, and the project system tells the linker to link with the missing DLL, the link fails. Use the **Ignore Import Library** property to resolve this problem. When set to **Yes**, the project system ignores the presence or absence of the *`.lib`* file, and causes any project that depends on this project to not link with the nonexistent *`.lib`* file. To programmatically access this property, see . ### Register Output -Runs `regsvr32.exe /s $(TargetPath)` on the build output, which is valid only on .dll projects. For .exe projects, this property is ignored. To register an .exe output, set a postbuild event on the configuration to do the custom registration that is always required for registered .exe files. +Runs `regsvr32.exe /s $(TargetPath)` on the build output, which is valid only on *`.dll`* projects. For *`.exe`* projects, this property is ignored. To register an *`.exe`* output, set a postbuild event on the configuration to do the custom registration that is always required for registered *`.exe`* files. To programmatically access this property, see . ### Per-user Redirection -Registration in Visual Studio has traditionally been done in HKEY_CLASSES_ROOT (HKCR). With Windows Vista and later operating systems, to access HKCR you must run Visual Studio in elevated mode. Developers don't always want to run in elevated mode but still must work with registration. Per-user redirection allows you to register without having to run in elevated mode. +Registration in Visual Studio has traditionally been done in `HKEY_CLASSES_ROOT` (HKCR). With Windows Vista and later operating systems, to access HKCR you must run Visual Studio in elevated mode. Developers don't always want to run in elevated mode but still must work with registration. Per-user redirection allows you to register without having to run in elevated mode. -Per-user redirection forces any writes to HKCR to be redirected to HKEY\_CURRENT\_USER (HKCU). If per-user redirection is turned off, it can cause [Project Build Error PRJ0050](../../error-messages/tool-errors/project-build-error-prj0050.md) when the program tries to write to HKCR. +Per-user redirection forces any writes to HKCR to be redirected to `HKEY_CURRENT_USER` (HKCU). If per-user redirection is turned off, it can cause [Project Build Error PRJ0050](../../error-messages/tool-errors/project-build-error-prj0050.md) when the program tries to write to HKCR. ### Additional Library Directories -Allows the user to override the environmental library path. ([/LIBPATH](libpath-additional-libpath.md):folder) +Allows the user to override the environment's library path. ([`/LIBPATH:folder`](libpath-additional-libpath.md)) ### Link Library Dependencies -Specifies whether to link the .lib files that are produced by dependent projects. Typically, you want to link in the .lib files, but it may not be the case for certain DLLs. +Specifies whether to link the *`.lib`* files that are produced by dependent projects. Typically, you want to link in the *`.lib`* files, but it may not be the case for certain DLLs. -You can also specify a .obj file by providing the file name and relative path, for example "..\\..\MyLibProject\MyObjFile.obj". If the source code for the .obj file #includes a precompiled header, for example pch.h, then the pch.obj file is located in the same folder as MyObjFile.obj. You must also add pch.obj as an additional dependency. +You can also specify a *`.obj`* file by providing the file name and relative path, for example, *`..\..\MyLibProject\MyObjFile.obj`*. If the source code for the *`.obj`* file has a `#include` for a precompiled header, for example, *`pch.h`*, then the *`pch.obj`* file is located in the same folder as *`MyObjFile.obj`*. You must also add *`pch.obj`* as an additional dependency. ### Use Library Dependency Inputs -Specifies whether to use the inputs to the librarian tool, rather than the library file itself, when linking in library outputs of project dependencies. In a large project, when a dependent project produces a .lib file, incremental linking is disabled. If there are many dependent projects that produce .lib files, building the application can take a long time. When this property is set to **Yes**, the project system links in the .obj files for .libs produced by dependent projects, enabling incremental linking. +Specifies whether to use the inputs to the librarian tool, rather than the library file itself, when linking in library outputs of project dependencies. In a large project, when a dependent project produces a *`.lib`* file, incremental linking is disabled. If there are many dependent projects that produce *`.lib`* files, building the application can take a long time. When this property is set to **Yes**, the project system links in the *`.obj`* files for *`.lib`* files produced by dependent projects, enabling incremental linking. -For information about how to access the **General** linker property page, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +For information about how to access the **General** linker property page, see [Set compiler and build properties](../working-with-project-properties.md). ### Link Status -Specifies whether the linker should display a progress indicator showing what percentage of the link is complete. The default is to not display this status information. ([/LTCG](ltcg-link-time-code-generation.md):STATUS|LTCG:NOSTATUS) +Specifies whether the linker should display a progress indicator showing what percentage of the link is complete. The default is to not display this status information. ([`/LTCG:STATUS|LTCG:NOSTATUS`](ltcg-link-time-code-generation.md)) ### Prevent DLL Binding -[/ALLOWBIND](allowbind-prevent-dll-binding.md):NO sets a bit in a DLL's header that indicates to Bind.exe that the image isn't allowed to be bound. You may not want a DLL to be bound if it has been digitally signed (binding invalidates the signature). +[`/ALLOWBIND:NO`](allowbind-prevent-dll-binding.md) sets a bit in a DLL's header that indicates to *`Bind.exe`* that binding the image isn't allowed. You may not want a DLL to be bound if it has been digitally signed (binding invalidates the signature). ### Treat Linker Warning As Errors -[/WX](wx-treat-linker-warnings-as-errors.md) causes no output file to be generated if the linker generates a warning. +[`/WX`](wx-treat-linker-warnings-as-errors.md) causes no output file to be generated if the linker generates a warning. ### Force File Output -The [/FORCE](force-force-file-output.md) option tells the linker to create an .exe file or DLL even if a symbol is referenced but not defined, or is multiply defined. It may create invalid .exe file. +The [`/FORCE`](force-force-file-output.md) option tells the linker to create an *`.exe`* file or DLL even if a symbol is referenced but not defined (**`UNRESOLVED`**), or is defined multiple times (**`MULTIPLE`**). It may create an invalid *`.exe`* file. **Choices** -- **Enabled** - /FORCE with no arguments implies both multiple and unresolved. -- **Multiply Defined Symbol Only** - Use /FORCE:MULTIPLE to create an output file, even if LINK finds more than one definition for a symbol. -- **Undefined Symbol Only** - Use /FORCE:UNRESOLVED to create an output file whether or not LINK finds an undefined symbol. /FORCE:UNRESOLVED is ignored if the entry point symbol is unresolved. +- **Enabled** - **`/FORCE`** with no arguments implies both **`/FORCE:MULTIPLE`** and **`/FORCE:UNRESOLVED`**. +- **Multiply Defined Symbol Only** - Use **`/FORCE:MULTIPLE`** to create an output file, even if LINK finds more than one definition for a symbol. +- **Undefined Symbol Only** - Use **`/FORCE:UNRESOLVED`** to create an output file whether or not LINK finds an undefined symbol. **`/FORCE:UNRESOLVED`** is ignored if the entry point symbol is unresolved. ### Create Hot Patchable Image -Prepares an image for hotpatching. +Prepares an image for hot patching. **Choices** -- **Enabled** - Prepares an image for hotpatching. -- **X86 Image Only** - Prepares an X86 image for hotpatching. -- **X64 Image Only** - Prepares an X64 image for hotpatching. -- **Itanium Image Only** - Prepares an Itanium image for hotpatching. +- **Enabled** - Prepares an image for hot patching. +- **X86 Image Only** - Prepares an X86 image for hot patching. +- **X64 Image Only** - Prepares an X64 image for hot patching. +- **Itanium Image Only** - Prepares an Itanium image for hot patching. ### Specify Section Attributes -The [/SECTION](section-specify-section-attributes.md) option changes the attributes of a section, overriding the attributes set when the .obj file for the section was compiled. +The [`/SECTION`](section-specify-section-attributes.md) option changes the attributes of a section, overriding the attributes set when the *`.obj`* file for the section was compiled. ## Input Property Page ### Additional Dependencies -Specifies additional items to add to the link command line, for example *kernel32.lib*. +Specifies extra dependency items to add to the link command line, for example *`kernel32.lib`*. ### Ignore All Default Libraries -The [/NODEFAULTLIB](nodefaultlib-ignore-libraries.md) option tells the linker to remove one or more default libraries from the list of libraries it searches when resolving external references. +The [`/NODEFAULTLIB`](nodefaultlib-ignore-libraries.md) option tells the linker to remove one or more default libraries from the list of libraries it searches when resolving external references. ### Ignore Specific Default Libraries -Specifies one or more names of default libraries to ignore. Separate multiple libraries with semi-colons. (/NODEFAULTLIB:[name, name, ...]) +Specifies one or more names of default libraries to ignore. Separate multiple libraries with semi-colons. ([`/NODEFAULTLIB:[name, name, ...]`](nodefaultlib-ignore-libraries.md)) ### Module Definition File -The [/DEF](def-specify-module-definition-file.md) option passes a module-definition file (.def) to the linker. Only one .def file can be specified to LINK. +The [`/DEF`](def-specify-module-definition-file.md) option passes a module-definition file (*`.def`*) to the linker. Only one *`.def`* file can be specified to LINK. ### Add Module to Assembly -The [/ASSEMBLYMODULE](assemblymodule-add-a-msil-module-to-the-assembly.md) option allows you to add a module reference to an assembly. Type information in the module will not be available to the assembly program that added the module reference. However, type information in the module will be available to any program that references the assembly. +The [`/ASSEMBLYMODULE`](assemblymodule-add-a-msil-module-to-the-assembly.md) option allows you to add a module reference to an assembly. Type information in the module won't be available to the assembly program that added the module reference. However, type information in the module will be available to any program that references the assembly. ### Embed Managed Resource File -[/ASSEMBLYRESOURCE](assemblyresource-embed-a-managed-resource.md) embeds a resource file in the output file. +[`/ASSEMBLYRESOURCE`](assemblyresource-embed-a-managed-resource.md) embeds a resource file in the output file. ### Force Symbol References -The [/INCLUDE](include-force-symbol-references.md) option tells the linker to add a specified symbol to the symbol table. +The [`/INCLUDE`](include-force-symbol-references.md) option tells the linker to add a specified symbol to the symbol table. ### Delay Loaded DLLs -The [/DELAYLOAD](delayload-delay-load-import.md) option causes delayed loading of DLLs. The dll name specifies a DLL to delay load. +The [`/DELAYLOAD`](delayload-delay-load-import.md) option causes delayed loading of DLLs. The dll name specifies a DLL to delay load. ### Assembly Link Resource -The [/ASSEMBLYLINKRESOURCE](assemblylinkresource-link-to-dotnet-framework-resource.md) option creates a link to a .NET Framework resource in the output file; the resource file is not placed in the output file. +The [`/ASSEMBLYLINKRESOURCE`](assemblylinkresource-link-to-dotnet-framework-resource.md) option creates a link to a .NET Framework resource in the output file. The linker doesn't place the resource file in the output file. ## Manifest File Property Page ### Generate Manifest -[/MANIFEST](manifest-create-side-by-side-assembly-manifest.md) specifies that the linker should create a side-by-side manifest file. +[`/MANIFEST`](manifest-create-side-by-side-assembly-manifest.md) specifies that the linker should create a side-by-side manifest file. ### Manifest File -[/MANIFESTFILE](manifestfile-name-manifest-file.md) lets you change the default name of the manifest file. The default name of the manifest file is the file name with .manifest appended. +[`/MANIFESTFILE`](manifestfile-name-manifest-file.md) lets you change the default name of the manifest file. The default name of the manifest file is the file name with *`.manifest`* appended. ### Additional Manifest Dependencies -[/MANIFESTDEPENDENCY](manifestdependency-specify-manifest-dependencies.md) lets you specify attributes that will be placed in the dependency section of the manifest file. +[`/MANIFESTDEPENDENCY`](manifestdependency-specify-manifest-dependencies.md) lets you specify attributes that will be placed in the dependency section of the manifest file. ### Allow Isolation -Specifies behavior for manifest lookup. ([/ALLOWISOLATION](allowisolation-manifest-lookup.md):NO) +Specifies behavior for manifest lookup. ([`/ALLOWISOLATION:NO`](allowisolation-manifest-lookup.md)) ### Enable User Account Control (UAC) -Specifies whether or not User Account Control is enabled. ([/MANIFESTUAC](manifestuac-embeds-uac-information-in-manifest.md), /MANIFESTUAC:NO) +Specifies whether or not User Account Control is enabled. ([`/MANIFESTUAC, /MANIFESTUAC:NO`](manifestuac-embeds-uac-information-in-manifest.md)) ### UAC Execution Level -Specifies the requested execution level for the application when running with User Account Control. (/MANIFESTUAC:level=[value]) +Specifies the requested execution level for the application when running with User Account Control. ([`/MANIFESTUAC:level=[value]`](manifestuac-embeds-uac-information-in-manifest.md)) **Choices** @@ -184,32 +184,32 @@ Specifies the requested execution level for the application when running with Us ### UAC Bypass UI Protection -Specifies whether or not to bypass user interface protection levels for other windows on the desktop. Set this property to 'Yes' only for accessibility applications. ([/MANIFESTUAC](manifestuac-embeds-uac-information-in-manifest.md):uiAccess=[true | false]) +Specifies whether or not to bypass user interface protection levels for other windows on the desktop. Set this property to 'Yes' only for accessibility applications. ([`/MANIFESTUAC:uiAccess=[true | false]`](manifestuac-embeds-uac-information-in-manifest.md)) ## Debugging Property Page ### Generate Debug Info -This option enables creation of debugging information for the .exe file or the DLL. +This option enables creation of debugging information for the *`.exe`* file or the DLL. **Choices** - **No** - Produces no debugging information. - **Generate Debug Information** - Create a complete Program Database (PDB) ideal for distribution to Microsoft Symbol Server. -- **Generate Debug Information optimized for faster links** - Produces a program database (PDB) ideal for edit-link-debug cycle. -- **Generate Debug Information optimized for sharing and publishing** - Produces a program database (PDB) ideal for edit-link-debug cycle. +- **Generate Debug Information optimized for faster links** - Produces a program database (PDB) ideal for a fast edit-link-debug cycle. +- **Generate Debug Information optimized for sharing and publishing** - Produces a program database (PDB) ideal for a shared edit-link-debug cycle. ### Generate Program Database File -By default, when [/DEBUG](debug-generate-debug-info.md) is specified, the linker creates a program database (PDB) which holds debugging information. The default file name for the PDB has the base name of the program and the extension .pdb. +By default, when [`/DEBUG`](debug-generate-debug-info.md) is specified, the linker creates a program database (PDB) which holds debugging information. The default file name for the PDB has the base name of the program and the extension *`.pdb`*. ### Strip Private Symbols -The [/PDBSTRIPPED](pdbstripped-strip-private-symbols.md) option creates a second program database (PDB) file when you build your program image with any of the compiler or linker options that generate a PDB file (/DEBUG, /Z7, /Zd, or /Zi). +The [`/PDBSTRIPPED`](pdbstripped-strip-private-symbols.md) option creates a second program database (PDB) file when you build your program image with any of the compiler or linker options that generate a PDB file (**`/DEBUG`**, **`/Z7`**, **`/Zd`**, or **`/Zi`**). ### Generate Map File -The [/MAP](map-generate-mapfile.md) option tells the linker to create a mapfile. +The [`/MAP`](map-generate-mapfile.md) option tells the linker to create a mapfile. ### Map File Name @@ -217,24 +217,24 @@ A user-specified name for the mapfile. It replaces the default name. ### Map Exports -The [/MAPINFO](mapinfo-include-information-in-mapfile.md) option tells the linker to include the specified information in a mapfile, which is created if you specify the /MAP option. EXPORTS tells the linker to include exported functions. +The [`/MAPINFO`](mapinfo-include-information-in-mapfile.md) option tells the linker to include the specified information in a mapfile, which is created if you specify the **`/MAP`** option. **`EXPORTS`** tells the linker to include exported functions. ### Debuggable Assembly -[/ASSEMBLYDEBUG](assemblydebug-add-debuggableattribute.md) emits the DebuggableAttribute attribute with debug information tracking and disables JIT optimizations. +[`/ASSEMBLYDEBUG`](assemblydebug-add-debuggableattribute.md) emits the `DebuggableAttribute` attribute with debug information tracking and disables JIT optimizations. ## System Property Page ### SubSystem -The [/SUBSYSTEM](subsystem-specify-subsystem.md) option tells the operating system how to run the .exe file. The choice of subsystem affects the entry point symbol (or entry point function) that the linker will choose. +The [`/SUBSYSTEM`](subsystem-specify-subsystem.md) option tells the operating system how to run the *`.exe`* file. The choice of subsystem affects the entry point symbol (or entry point function) that the linker will choose. **Choices** - **Not Set** - No subsystem set. -- **Console** - Win32 character-mode application. Console applications are given a console by the operating system. If main or wmain is defined, CONSOLE is the default. -- **Windows** - Application does not require a console, probably because it creates its own windows for interaction with the user. If WinMain or wWinMain is defined, WINDOWS is the default. -- **Native** - Device drivers for Windows NT. If /DRIVER:WDM is specified, NATIVE is the default. +- **Console** - Win32 character-mode application. Console applications are given a console by the operating system. If `main` or `wmain` is defined, `CONSOLE` is the default. +- **Windows** - Application doesn't require a console, probably because it creates its own windows for interaction with the user. If `WinMain` or `wWinMain` is defined, `WINDOWS` is the default. +- **Native** - Device drivers for Windows NT. If **`/DRIVER:WDM`** is specified, `NATIVE` is the default. - **EFI Application** - EFI Application. - **EFI Boot Service Driver** - EFI Boot Service Driver. - **EFI ROM** - EFI ROM. @@ -243,109 +243,109 @@ The [/SUBSYSTEM](subsystem-specify-subsystem.md) option tells the operating syst ### Minimum Required Version -Specify the minimum required version of the subsystem. The arguments are decimal numbers in the range 0 through 65,535. +Specify the minimum required version of the subsystem. The arguments are decimal numbers in the range 0 through 65535. ### Heap Reserve Size -Specifies total heap allocation size in virtual memory. Default is 1 MB. ([/HEAP](heap-set-heap-size.md):reserve) +Specifies total heap allocation size in virtual memory. Default is 1 MB. ([`/HEAP:reserve`](heap-set-heap-size.md)) ### Heap Commit Size -Specifies total heap allocation size in physical memory. Default is 4 KB. ([/HEAP](heap-set-heap-size.md):reserve,commit) +Specifies total heap allocation size in physical memory. Default is 4 KB. ([`/HEAP:reserve,commit`](heap-set-heap-size.md)) ### Stack Reserve Size -Specifies the total stack allocation size in virtual memory. Default is 1 MB. ([/STACK](stack-stack-allocations.md):reserve) +Specifies the total stack allocation size in virtual memory. Default is 1 MB. ([`/STACK:reserve`](stack-stack-allocations.md)) ### Stack Commit Size -Specifies the total stack allocation size in physical memory. Default is 4 KB. ([/STACK](stack-stack-allocations.md):reserve,commit) +Specifies the total stack allocation size in physical memory. Default is 4 KB. ([`/STACK:reserve,commit`](stack-stack-allocations.md)) ### Enable Large Addresses -The [/LARGEADDRESSAWARE](largeaddressaware-handle-large-addresses.md) option tells the linker that the application can handle addresses larger than 2 gigabytes. By default, /LARGEADDRESSAWARE:NO is enabled if /LARGEADDRESSAWARE is not otherwise specified on the linker line. +The [`/LARGEADDRESSAWARE`](largeaddressaware-handle-large-addresses.md) option tells the linker that the application can handle addresses larger than 2 gigabytes. By default, **`/LARGEADDRESSAWARE:NO`** is enabled if **`/LARGEADDRESSAWARE`** isn't otherwise specified on the linker line. ### Terminal Server -The [/TSAWARE](tsaware-create-terminal-server-aware-application.md) option sets a flag in the IMAGE_OPTIONAL_HEADER DllCharacteristics field in the program image's optional header. When this flag is set, Terminal Server will not make certain changes to the application. +The [`/TSAWARE`](tsaware-create-terminal-server-aware-application.md) option sets a flag in the `IMAGE_OPTIONAL_HEADER` `DllCharacteristics` field in the program image's optional header. When this flag is set, Terminal Server won't make certain changes to the application. ### Swap Run From CD -The [/SWAPRUN](swaprun-load-linker-output-to-swap-file.md) option tells the operating system to first copy the linker output to a swap file, and then run the image from there. This option is a Windows NT 4.0 (and later) feature. When **CD** is specified, the operating system will copy the image on a removable disk to a page file and then load it. +The [`/SWAPRUN`](swaprun-load-linker-output-to-swap-file.md) option tells the operating system to first copy the linker output to a swap file, and then run the image from there. This option is a Windows NT 4.0 (and later) feature. When **`CD`** is specified, the operating system will copy the image on a removable disk to a page file, and then load it. ### Swap Run From Network -The [/SWAPRUN](swaprun-load-linker-output-to-swap-file.md) option tells the operating system to first copy the linker output to a swap file, and then run the image from there. This option is a Windows NT 4.0 (and later) feature. If **NET** is specified, the operating system will first copy the binary image from the network to a swap file and load it from there. This option is useful for running applications over the network. +The [`/SWAPRUN`](swaprun-load-linker-output-to-swap-file.md) option tells the operating system to first copy the linker output to a swap file, and then run the image from there. This option is a Windows NT 4.0 (and later) feature. If **`NET`** is specified, the operating system will first copy the binary image from the network to a swap file and load it from there. This option is useful for running applications over the network. ### Driver -Use the [/DRIVER](driver-windows-nt-kernel-mode-driver.md) linker option to build a Windows NT kernel mode driver. +Use the [`/DRIVER`](driver-windows-nt-kernel-mode-driver.md) linker option to build a Windows NT kernel mode driver. **Choices** - **Not Set** - Default driver setting. - **Driver** - Driver -- **UP Only** - /DRIVER:UPONLY causes the linker to add the IMAGE_FILE_UP_SYSTEM_ONLY bit to the characteristics in the output header to specify that it is a uniprocessor (UP) driver. The operating system will refuse to load a UP driver on a multiprocessor (MP) system. -- **WDM** - /DRIVER:WDM causes the linker to set the IMAGE_DLLCHARACTERISTICS_WDM_DRIVER bit in the optional header's DllCharacteristics field. +- **UP Only** - **`/DRIVER:UPONLY`** causes the linker to add the `IMAGE_FILE_UP_SYSTEM_ONLY` bit to the characteristics in the output header to specify that it's a uniprocessor (UP) driver. The operating system will refuse to load a UP driver on a multiprocessor (MP) system. +- **WDM** - **`/DRIVER:WDM`** causes the linker to set the `IMAGE_DLLCHARACTERISTICS_WDM_DRIVER` bit in the optional header's `DllCharacteristics` field. ## Optimization Property Page ### References -[/OPT](opt-optimizations.md):REF eliminates functions and/or data that's never referenced while /OPT:NOREF keeps functions and/or data that's never referenced. +[`/OPT:REF`](opt-optimizations.md) eliminates functions and/or data that's never referenced while **`/OPT:NOREF`** keeps functions and/or data that's never referenced. ### Enable COMDAT Folding -Use [/OPT](opt-optimizations.md):ICF\[=iterations] to perform identical COMDAT folding. +Use [`/OPT:ICF[=iterations]`](opt-optimizations.md) to perform identical COMDAT folding. ### Function Order -The [/ORDER](order-put-functions-in-order.md)option tells LINK to optimize your program by placing certain COMDATs into the image in a predetermined order. LINK places the functions in the specified order within each section in the image. +The [`/ORDER`](order-put-functions-in-order.md) option tells LINK to optimize your program by placing certain COMDATs into the image in a predetermined order. LINK places the functions in the specified order within each section in the image. ### Profile Guided Database -Specify .pgd file for profile guided optimizations. ([/PGD](pgd-specify-database-for-profile-guided-optimizations.md)) +Specify the *`.pgd`* file for profile guided optimizations. ([`/PGD`](pgd-specify-database-for-profile-guided-optimizations.md)) ### Link Time Code Generation -Specifies link-time code generation. ([/LTCG](ltcg-link-time-code-generation.md)) +Specifies link-time code generation. ([`/LTCG`](ltcg-link-time-code-generation.md)) **Choices** - **Default** - Default LTCG setting. -- **Use Fast Link Time Code Generation** - Use Link Time Code Generation with [/FASTGENPROFILE](genprofile-fastgenprofile-generate-profiling-instrumented-build.md). +- **Use Fast Link Time Code Generation** - Use Link Time Code Generation with [`/FASTGENPROFILE`](genprofile-fastgenprofile-generate-profiling-instrumented-build.md). - **Use Link Time Code Generation** - Use [Link Time Code Generation](ltcg-link-time-code-generation.md). -- **Profile Guided Optimization - Instrument** - Use [profile guided optimization](../profile-guided-optimizations.md) with :PGINSTRUMENT. +- **Profile Guided Optimization - Instrument** - Use [profile guided optimization](../profile-guided-optimizations.md) with `:PGINSTRUMENT`. - **Profile Guided Optimization - Optimization** - Specifies that the linker should use the profile data created after running the instrumented binary to create an optimized image. -- **Profile Guided Optimization - Update** - Allows and tracks list of input files to be added or modified from what was specified in the :PGINSTRUMENT phase. +- **Profile Guided Optimization - Update** - Allows and tracks list of input files to be added or modified from what was specified in the `:PGINSTRUMENT` phase. ## Embedded IDL Property Page ### MIDL Commands -Specify MIDL command line Options. ([/MIDL](midl-specify-midl-command-line-options.md):@responsefile) +Specify MIDL command line options. ([`/MIDL:@responsefile`](midl-specify-midl-command-line-options.md)) ### Ignore Embedded IDL -The [/IGNOREIDL](ignoreidl-don-t-process-attributes-into-midl.md) option specifies that any IDL attributes in source code should not be processed into an .idl file. +The [`/IGNOREIDL`](ignoreidl-don-t-process-attributes-into-midl.md) option specifies that any IDL attributes in source code shouldn't be processed into an *`.idl`* file. ### Merged IDL Base File Name -The [/IDLOUT](idlout-name-midl-output-files.md) option specifies the name and extension of the .idl file. +The [`/IDLOUT`](idlout-name-midl-output-files.md) option specifies the name and extension of the *`.idl`* file. ### Type Library -The [/TLBOUT](tlbout-name-dot-tlb-file.md) option specifies the name and extension of the .tlb file. +The [`/TLBOUT`](tlbout-name-dot-tlb-file.md) option specifies the name and extension of the *`.tlb`* file. ### TypeLib Resource ID -Allows you to specify the resource ID of the linker-generated type library. ([/TLBID](tlbid-specify-resource-id-for-typelib.md):id) +Allows you to specify the resource ID of the linker-generated type library. ([`/TLBID:id`](tlbid-specify-resource-id-for-typelib.md)) ## Windows Metadata Property Page ### Generate Windows Metadata -Enables or disable generation of Windows Metadata. +Enables or disables generation of Windows Metadata. **Choices** @@ -354,73 +354,73 @@ Enables or disable generation of Windows Metadata. ### Windows Metadata File -The [/WINMDFILE](winmdfile-specify-winmd-file.md) option switch. +The [`/WINMDFILE`](winmdfile-specify-winmd-file.md) option switch. ### Windows Metadata Key File -Specify key or key pair to sign an Windows Metadata. ([/WINMDKEYFILE](winmdkeyfile-specify-winmd-key-file.md):filename) +Specify a key or key pair to sign the Windows Metadata. ([`/WINMDKEYFILE:filename`](winmdkeyfile-specify-winmd-key-file.md)) ### Windows Metadata Key Container -Specify a key container to sign an Windows Metadata. ([/WINMDKEYCONTAINER](winmdkeycontainer-specify-key-container.md):name) +Specify a key container to sign the Windows Metadata. ([`/WINMDKEYCONTAINER:name`](winmdkeycontainer-specify-key-container.md)) ### Windows Metadata Delay Sign -Partially sign an Windows Metadata. Use [/WINMDDELAYSIGN](winmddelaysign-partially-sign-a-winmd.md) if you only want to place the public key in the Windows Metadata. The default is /WINMDDELAYSIGN:NO. +Partially sign the Windows Metadata. Use [`/WINMDDELAYSIGN`](winmddelaysign-partially-sign-a-winmd.md) if you only want to place the public key in the Windows Metadata. The default is **`/WINMDDELAYSIGN:NO`**. ## Advanced Property Page ### Entry Point -The [/ENTRY](entry-entry-point-symbol.md) option specifies an entry point function as the starting address for an .exe file or DLL. +The [`/ENTRY`](entry-entry-point-symbol.md) option specifies an entry point function as the starting address for an *`.exe`* file or DLL. ### No Entry Point -The [/NOENTRY](noentry-no-entry-point.md)option is required for creating a resource-only DLL.Use this option to prevent LINK from linking a reference to `_main` into the DLL. +The [`/NOENTRY`](noentry-no-entry-point.md) option is required for creating a resource-only DLL. Use this option to prevent LINK from linking a reference to `_main` into the DLL. ### Set Checksum -The [/RELEASE](release-set-the-checksum.md) option sets the Checksum in the header of an .exe file. +The [`/RELEASE`](release-set-the-checksum.md) option sets the Checksum in the header of an *`.exe`* file. ### Base Address -Sets a base address for the program. ([/BASE](base-base-address.md):{address\[,size] | @filename,key}) +Sets a base address for the program. ([`/BASE:{address[,size] | @filename,key}`](base-base-address.md)) ### Randomized Base Address -Randomized Base Address. ([/DYNAMICBASE](dynamicbase-use-address-space-layout-randomization.md)\[:NO]) +Randomized Base Address. ([`/DYNAMICBASE[:NO]`](dynamicbase-use-address-space-layout-randomization.md)) ### Fixed Base Address -Creates a program that can be loaded only at its preferred base address. ([/FIXED](fixed-fixed-base-address.md)\[:NO]) +Creates a program that can be loaded only at its preferred base address. ([`/FIXED[:NO]`](fixed-fixed-base-address.md)) ### Data Execution Prevention (DEP) -Marks an executable as having been tested to be compatible with Windows Data Execution Prevention feature. ([/NXCOMPAT](nxcompat-compatible-with-data-execution-prevention.md)\[:NO]) +Marks an executable as having been tested to be compatible with Windows Data Execution Prevention feature. ([`/NXCOMPAT[:NO]`](nxcompat-compatible-with-data-execution-prevention.md)) ### Turn Off Assembly Generation -The [/NOASSEMBLY](noassembly-create-a-msil-module.md) option tells the linker to create an image for the current output file without a .NET Framework assembly. +The [`/NOASSEMBLY`](noassembly-create-a-msil-module.md) option tells the linker to create an image for the current output file without a .NET Framework assembly. ### Unload delay loaded DLL -The **UNLOAD** qualifier tells the delay-load helper function to support explicit unloading of the DLL. ([/DELAY](delay-delay-load-import-settings.md):UNLOAD) +The **`UNLOAD`** qualifier tells the delay-load helper function to support explicit unloading of the DLL. ([`/DELAY:UNLOAD`](delay-delay-load-import-settings.md)) ### Nobind delay loaded DLL -The **NOBIND** qualifier tells the linker not to include a bindable IAT in the final image. The default is to create the bindable IAT for delay-loaded DLLs. ([/DELAY](delay-delay-load-import-settings.md):NOBIND) +The **`NOBIND`** qualifier tells the linker not to include a bindable Import Address Table (IAT) in the final image. The default is to create the bindable IAT for delay-loaded DLLs. ([`/DELAY:NOBIND`](delay-delay-load-import-settings.md)) ### Import Library -Overrides the default import library name. ([/IMPLIB](implib-name-import-library.md):filename) +Overrides the default import library name. ([`/IMPLIB:filename`](implib-name-import-library.md)) ### Merge Sections -The [/MERGE](merge-combine-sections.md) option combines the first section (from) with the second section (to), naming the resulting section to. For example, /merge:.rdata=.text. +The [`/MERGE`](merge-combine-sections.md) option combines the first section with the second section, and gives the resulting section the second section name. For example, `/merge:.rdata=.text` merges the `.rdata` section with the `.text` section, and names the combined section `.text`. ### Target Machine -The [/MACHINE](machine-specify-target-platform.md) option specifies the target platform for the program. +The [`/MACHINE`](machine-specify-target-platform.md) option specifies the target platform for the program. **Choices** @@ -440,7 +440,7 @@ The [/MACHINE](machine-specify-target-platform.md) option specifies the target p ### Profile -Produces an output file that can be used with the Performance Tools profiler. Requires GenerateDebugInformation (/[/DEBUG](debug-generate-debug-info.md)) to be set. ([/PROFILE](profile-performance-tools-profiler.md)) +Produces an output file that can be used with the Performance Tools profiler. Requires the **Generate Debug Info** property be set to **GenerateDebugInformation (/DEBUG)**. ([`/PROFILE`](profile-performance-tools-profiler.md)) ### CLR Thread Attribute @@ -450,7 +450,7 @@ Explicitly specify the threading attribute for the entry point of your CLR progr - **MTA threading attribute** - Applies the MTAThreadAttribute attribute to the entry point of your program. - **STA threading attribute** - Applies the STAThreadAttribute attribute to the entry point of your program. -- **Default threading attribute** - Same as not specifying [/CLRTHREADATTRIBUTE](clrthreadattribute-set-clr-thread-attribute.md). Lets the Common Language Runtime (CLR) set the default threading attribute. +- **Default threading attribute** - Same as not specifying [`/CLRTHREADATTRIBUTE`](clrthreadattribute-set-clr-thread-attribute.md). Lets the Common Language Runtime (CLR) set the default threading attribute. ### CLR Image Type @@ -465,45 +465,45 @@ Sets the type (IJW, pure, or safe) of a CLR image. ### Key File -Specify key or key pair to sign an assembly. ([/KEYFILE](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md):filename) +Specify key or key pair to sign an assembly. ([`/KEYFILE:filename`](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md)) ### Key Container -Specify a key container to sign an assembly. ([/KEYCONTAINER](keycontainer-specify-a-key-container-to-sign-an-assembly.md):name) +Specify a key container to sign an assembly. ([`/KEYCONTAINER:name`](keycontainer-specify-a-key-container-to-sign-an-assembly.md)) ### Delay Sign -Partially sign an assembly. Use [/DELAYSIGN](delaysign-partially-sign-an-assembly.md) if you only want to place the public key in the assembly. The default is /DELAYSIGN:NO. +Partially sign an assembly. Use [`/DELAYSIGN`](delaysign-partially-sign-an-assembly.md) if you only want to place the public key in the assembly. The default is **`/DELAYSIGN:NO`**. ### CLR Unmanaged Code Check -[/CLRUNMANAGEDCODECHECK](clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md) specifies whether the linker will apply SuppressUnmanagedCodeSecurityAttribute to linker-generated PInvoke calls from managed code into native DLLs. +[`/CLRUNMANAGEDCODECHECK`](clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md) specifies whether the linker will apply `SuppressUnmanagedCodeSecurityAttribute` to linker-generated P/Invoke calls from managed code into native DLLs. ### Error Reporting -Allows you to provide internal compiler error (ICE) information directly to the Visual C++ team. +Allows you to provide internal compiler error (ICE) information directly to the Visual Studio C++ team. **Choices** - **PromptImmediately** - Prompt immediately. -- **Queue For Next Login** - Queue for next login. +- **Queue For Next Login** - Queue for next sign-in. - **Send Error Report** - Send error report. - **No Error Report** - No error report. ### SectionAlignment -The [/ALIGN](align-section-alignment.md) option specifies the alignment of each section within the linear address space of the program. The number argument is in bytes and must be a power of two. +The [`/ALIGN`](align-section-alignment.md) option specifies the alignment of each section within the linear address space of the program. The number argument is in bytes and must be a power of two. ### Preserve Last Error Code for PInvoke Calls -[/CLRSUPPORTLASTERROR](clrsupportlasterror-preserve-last-error-code-for-pinvoke-calls.md), which is on by default, preserves the last error code of functions called through the P/Invoke mechanism, which allows you to call native functions in DLLS, from code compiled with /clr. +[`/CLRSUPPORTLASTERROR`](clrsupportlasterror-preserve-last-error-code-for-pinvoke-calls.md), which is on by default, preserves the last error code of functions called through the P/Invoke mechanism, which allows you to call native functions in DLLS, from code compiled with **`/clr`**. **Choices** -- **Enabled** - Enable CLRSupportLastError. -- **Disabled** - Disable CLRSupportLastError. -- **System Dlls Only** - Enable CLRSupportLastError for system dlls only. +- **Enabled** - Enable **`/CLRSupportLastError`**. +- **Disabled** - Disable **`/CLRSupportLastError`**. +- **System DLLs Only** - Enable **`/CLRSupportLastError`** for system DLLs only. ### Image Has Safe Exception Handlers -When [/SAFESEH](safeseh-image-has-safe-exception-handlers.md) is specified, the linker will only produce an image if it can also produce a table of the image's safe exception handlers. This table specifies for the operating system which exception handlers are valid for the image. +When [`/SAFESEH`](safeseh-image-has-safe-exception-handlers.md) is specified, the linker will only produce an image if it can also produce a table of the image's safe exception handlers. This table specifies for the operating system which exception handlers are valid for the image. diff --git a/docs/build/reference/linking.md b/docs/build/reference/linking.md index 3cc16467a7..8891ebf554 100644 --- a/docs/build/reference/linking.md +++ b/docs/build/reference/linking.md @@ -1,83 +1,80 @@ --- description: "Learn more about: Linking" title: "MSVC linker reference" -ms.date: "12/10/2018" -ms.assetid: bb736587-d13b-4f3c-8982-3cc2c015c59c +ms.date: 03/27/2025 --- # Linking -In a C++ project, the *linking* step is performed after the compiler has compiled the source code into object files (*.obj). The linker (link.exe) combines the object files into a single executable file. +In a C++ project, the *linking* step is performed after the compiler compiles the source code into object files (*.obj). The linker (`link.exe`) combines the object files into a single executable file. Linker options can be set inside or outside of Visual Studio. Within Visual Studio, you access linker options by right-clicking on a project node in **Solution Explorer** and choosing **Properties** to display the property pages. Choose **Linker** in the left pane to expand the node and see all the options. ## Linker command-line syntax -When you run LINK outside of Visual Studio, you can specify input in one or more ways: +When you run the linker outside of Visual Studio, you can specify input in one or more ways: - On the command line - - Using command files - - In environment variables -LINK first processes options specified in the LINK environment variable, followed by options in the order they are specified on the command line and in command files. If an option is repeated with different arguments, the last one processed takes precedence. +The linker first processes options specified in the `LINK` environment variable, followed by options in the order they're specified on the command line and in command files. If an option is repeated with different arguments, the last one processed takes precedence. Options apply to the entire build; no options can be applied to specific input files. -To run LINK.EXE, use the following command syntax: +To run `link.exe`, use the following command syntax: -``` -LINK arguments +```cmd +link arguments ``` The `arguments` include options and filenames and can be specified in any order. Options are processed first, then files. Use one or more spaces or tabs to separate arguments. > [!NOTE] -> You can start this tool only from the Visual Studio command prompt. You cannot start it from a system command prompt or from File Explorer. +> You can start this tool only from the Visual Studio command prompt. You can't start it from a system command prompt or from File Explorer. ## Command line -On the command line, an option consists of an option specifier, either a dash (-) or a forward slash (/), followed by the name of the option. Option names cannot be abbreviated. Some options take an argument, specified after a colon (:). No spaces or tabs are allowed within an option specification, except within a quoted string in the /COMMENT option. Specify numeric arguments in decimal or C-language notation. Option names and their keyword or filename arguments are not case sensitive, but identifiers as arguments are case sensitive. +On the command line, an option consists of an option specifier, either a dash (`-`) or a forward slash (`/`), followed by the name of the option. Option names can't be abbreviated. Some options take an argument, specified after a colon (`:`). No spaces or tabs are allowed within an option specification, except within a quoted string in the `/COMMENT` option. Specify numeric arguments in decimal or C-language notation. Option names and their keyword or filename arguments aren't case sensitive, but identifiers as arguments are case sensitive. -To pass a file to the linker, specify the filename on the command line after the LINK command. You can specify an absolute or relative path with the filename, and you can use wildcards in the filename. If you omit the dot (.) and filename extension, LINK assumes .obj for the purpose of finding the file. LINK does not use filename extensions or the lack of them to make assumptions about the contents of files; it determines the type of file by examining it, and processes it accordingly. +To pass a file to the linker, specify the filename on the command line after the `link.exe` command. You can specify an absolute or relative path with the filename, and you can use wildcards in the filename. If you omit the dot (`.`) and filename extension, the linker assumes an extension of `.obj` to find the file. The linker doesn't use filename extensions or the lack of them to make assumptions about the contents of files. It determines the type of file by examining it, and processes it accordingly. -link.exe returns zero for success (no errors). Otherwise, the linker returns the error number that stopped the link. For example, if the linker generates LNK1104, the linker returns 1104. Accordingly, the lowest error number returned on an error by the linker is 1000. A return value of 128 represents a configuration problem with either the operating system or a .config file; the loader didn't load either link.exe or c2.dll. +> [!NOTE] +> Various linker flags take a filename. Whether you specify a relative path or an absolute path, if the fully-qualified filename exceeds `MAX_PATH` (260 characters), the linker may fail--particularly while searching for libraries. If you encounter this problem, try using a shorter path. -## LINK Command Files +The linker returns zero for success (no errors). Otherwise, it returns the error number that stopped the link. For example, if the linker generates `LNK1104`, the linker returns 1104. Accordingly, the lowest error number returned on an error by the linker is 1000. A return value of 128 represents a configuration problem with either the operating system or a .config file; the loader didn't load either `link.exe` or `c2.dll`. -You can pass command-line arguments to LINK in the form of a command file. To specify a command file to the linker, use the following syntax: +## Linker command files -> **LINK \@**commandfile +You can pass command-line arguments to `link.exe` in the form of a command file. To specify a command file to the linker, use the following syntax: -The *commandfile* is the name of a text file. No space or tab is allowed between the at sign (**\@**) and the filename. There is no default extension; you must specify the full filename, including any extension. Wildcards cannot be used. You can specify an absolute or relative path with the filename. LINK does not use an environment variable to search for the file. +> `link @commandfile` -In the command file, arguments can be separated by spaces or tabs (as on the command line) and by newline characters. +The *`commandfile`* is the name of a text file. No space or tab is allowed between the at sign (**\@**) and the filename. There's no default extension; you must specify the full filename, including any extension. Wildcards can't be used. You can specify an absolute or relative path with the filename. Must not exceed `MAX_PATH` (260 characters). The linker doesn't use an environment variable to search for the file. -You can specify all or part of the command line in a command file. You can use more than one command file in a LINK command. LINK accepts the command-file input as if it were specified in that location on the command line. Command files cannot be nested. LINK echoes the contents of command files, unless the [/NOLOGO](nologo-suppress-startup-banner-linker.md) option is specified. +In the command file, arguments are separated by spaces or tabs (as on the command line) and by newline characters. + +You can specify all or part of the command line in a command file. You can use more than one command file in a `link.exe` command. The linker accepts the command-file input as if it was specified in that location on the command line. Command files can't be nested. The linker echoes the contents of command files, unless [`/NOLOGO`](nologo-suppress-startup-banner-linker.md) is specified. ## Example -The following command to build a DLL passes the names of object files and libraries in separate command files and uses a third command file for specification of the /EXPORTS option: +The following command builds a DLL. It passes the names of object files and libraries in separate command files and uses a third command file for specification of the `/EXPORTS` option: ```cmd link /dll @objlist.txt @liblist.txt @exports.txt ``` -## LINK Environment Variables - -The LINK tool uses the following environment variables: - -- LINK and \_LINK\_, if defined. The LINK tool prepends the options and arguments defined in the LINK environment variable and appends the options and arguments defined in the \_LINK\_ environment variable to the command line arguments before processing. - -- LIB, if defined. The LINK tools uses the LIB path when searching for an object, library, or other file specified on the command line or by the [/BASE](base-base-address.md) option. It also uses the LIB path to find a .pdb file named in an object. The LIB variable can contain one or more path specifications, separated by semicolons. One path must point to the \lib subdirectory of your Visual C++ installation. +## LINK environment variables -- PATH, if the tool needs to run CVTRES and cannot find the file in the same directory as LINK itself. (LINK requires CVTRES to link a .res file.) PATH must point to the \bin subdirectory of your Visual C++ installation. +The linker recognizes the following environment variables: -- TMP, to specify a directory when linking OMF or .res files. +- `LINK` and `_LINK_`, if defined. The linker prepends the options and arguments defined in the `LINK` environment variable and appends the options and arguments defined in the `_LINK_` environment variable to the command line arguments before processing. +- `LIB`, if defined. The linker uses the `LIB` path when it searches for an object, library, or other file specified on the command line or by the [`/BASE`](base-base-address.md) option. It also uses the `LIB` path to find a `.pdb` file named in an object. The `LIB` variable can contain one or more path specifications, separated by semicolons. One path must point to the `\lib` subdirectory of your Visual C++ installation. +- `PATH`, if the tool needs to run `CVTRES` and can't find the file in the same directory as `link.exe` itself. (`link.exe` requires `CVTRES` to link a `.res` file.) `PATH` must point to the `\bin` subdirectory of your Visual C++ installation. +- `TMP`, to specify a directory when linking OMF or `.res` files. ## See also -[C/C++ Building Reference](c-cpp-building-reference.md) -[MSVC Linker Options](linker-options.md) -[Module-Definition (.def) Files](module-definition-dot-def-files.md) +[C/C++ Building Reference](c-cpp-building-reference.md)\ +[MSVC Linker Options](linker-options.md)\ +[Module-Definition (.def) Files](module-definition-dot-def-files.md)\ [Linker Support for Delay-Loaded DLLs](linker-support-for-delay-loaded-dlls.md) diff --git a/docs/build/reference/linkrepro.md b/docs/build/reference/linkrepro.md index 9d00525a14..a106200fdc 100644 --- a/docs/build/reference/linkrepro.md +++ b/docs/build/reference/linkrepro.md @@ -1,7 +1,7 @@ --- title: "/LINKREPRO (Link repro directory name)" description: Linker or library tool option to set the directory for a link repro. -ms.date: "09/24/2019" +ms.date: 03/28/2025 f1_keywords: ["/LINKREPRO"] helpviewer_keywords: ["LINKREPRO linker option", "/LINKREPRO linker option", "-LINKREPRO linker option", "linker repro reporting"] --- @@ -11,12 +11,12 @@ Tells the linker or library tool to generate a link repro in a specified directo ## Syntax -> **/LINKREPRO:**_directory-name_ +> `/LINKREPRO:` **_directory-name_** ### Arguments -**/LINKREPRO:**_directory-name_\ -The user-specified directory to store the link repro in. Directory names that include spaces must be enclosed in double quotes. +**_directory-name_**\ +The user-specified directory to store the link repro in. Directory names that include spaces must be enclosed in double quotes. When expanded, the fully qualified link repro filename must not exceed `MAX_PATH` (260 characters). ## Remarks diff --git a/docs/build/reference/list-visual-cpp.md b/docs/build/reference/list-visual-cpp.md index c28e5ac3d0..56154a07e8 100644 --- a/docs/build/reference/list-visual-cpp.md +++ b/docs/build/reference/list-visual-cpp.md @@ -1,14 +1,14 @@ --- -description: "Learn more about: <list> and <listheader>" -title: "<list> (C++ documentation comments)" -ms.date: "11/04/2016" +description: "Learn more about: and " +title: " (C++ documentation comments)" +ms.date: 12/03/2021 f1_keywords: ["list"] helpviewer_keywords: ["list C++ XML tag", " C++ XML tag"] ms.assetid: c792a10b-0451-422c-9aa0-604116e69d64 --- -# <list> and <listheader> +# `` and `` documentation tags -The \ block is used to define the heading row of either a table or definition list. When defining a table, you only need to supply an entry for term in the heading. +The `` block is used to define the heading row of either a table or definition list. When defining a table, you only need to supply an entry for term in the heading. ## Syntax @@ -25,21 +25,21 @@ The \ block is used to define the heading row of either a table or d ``` -#### Parameters +### Parameters -*term*
-A term to define, which will be defined in `description`. +*`term`*\ +A term to define, which will be defined in *`description`*. -*description*
-Either an item in a bullet or numbered list or the definition of a `term`. +*`description`*\ +Either an item in a bullet or numbered list or the definition of a *`term`*. ## Remarks -Each item in the list is specified with an \ block. When creating a definition list, you will need to specify both `term` and `description`. However, for a table, bulleted list, or numbered list, you only need to supply an entry for `description`. +Each item in the list is specified with an `` block. When creating a definition list, you'll need to specify both *`term`* and *`description`*. However, for a table, bulleted list, or numbered list, you only need to supply an entry for *`description`*. -A list or table can have as many \ blocks as needed. +A list or table can have as many `` blocks as needed. -Compile with [/doc](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. +Compile with [`/doc`](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. ## Example @@ -62,4 +62,4 @@ class MyClass {}; ## See also -[XML Documentation](xml-documentation-visual-cpp.md) +[XML documentation](xml-documentation-visual-cpp.md) diff --git a/docs/build/reference/long-filenames-in-a-makefile.md b/docs/build/reference/long-filenames-in-a-makefile.md deleted file mode 100644 index e3692cdc0d..0000000000 --- a/docs/build/reference/long-filenames-in-a-makefile.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -description: "Learn more about: Long Filenames in a Makefile" -title: "Long Filenames in a Makefile" -ms.date: "11/04/2016" -helpviewer_keywords: ["NMAKE program, long filenames", "long filenames"] -ms.assetid: 626d56fc-8879-46ba-9c2d-dd386c78cccc ---- -# Long Filenames in a Makefile - -Enclose long filenames in double quotation marks, as follows: - -``` -all : "VeryLongFileName.exe" -``` - -## See also - -[Contents of a Makefile](contents-of-a-makefile.md) diff --git a/docs/build/reference/ltcg-link-time-code-generation.md b/docs/build/reference/ltcg-link-time-code-generation.md index c4e9a8f14a..1a22070855 100644 --- a/docs/build/reference/ltcg-link-time-code-generation.md +++ b/docs/build/reference/ltcg-link-time-code-generation.md @@ -1,8 +1,8 @@ --- title: "/LTCG (Link-time code generation)" description: "The MSVC linker option /LTCG enables link-time code generation for whole-program optimization." -ms.date: 07/08/2020 -f1_keywords: ["VC.Project.VCLinkerTool.LinkTimeCodeGeneration", "VC.Project.VCConfiguration.WholeProgramOptimization", "VC.Project.VCCLWCECompilerTool.WholeProgramOptimization", "/ltcg", "VC.Project.VCCLCompilerTool.WholeProgramOptimization"] +ms.date: 09/08/2022 +f1_keywords: ["VC.Project.VCLinkerTool.LinkTimeCodeGeneration", "VC.Project.VCCLWCECompilerTool.WholeProgramOptimization", "/ltcg", "VC.Project.VCCLCompilerTool.WholeProgramOptimization", "VC.Project.VCLinkerTool.LinkStatus"] helpviewer_keywords: ["link-time code generation in C++ linker", "/LTCG linker option", "-LTCG linker option", "LTCG linker option"] ms.assetid: 788c6f52-fdb8-40c2-90af-4026ea2cf2e2 --- @@ -12,22 +12,22 @@ Use **`/LTCG`** to perform whole-program optimization, or to create profile-guid ## Syntax -> **`/LTCG`**[**`:`**{**`INCREMENTAL`**|**`NOSTATUS`**|**`STATUS`**|**`OFF`**}] +> **`/LTCG`**[**`:`**{**`INCREMENTAL`**\|**`NOSTATUS`**\|**`STATUS`**\|**`OFF`**}] These options are deprecated starting in Visual Studio 2015: -> **`/LTCG:`**{**`PGINSTRUMENT`**|**`PGOPTIMIZE`**|**`PGUPDATE`**} +> **`/LTCG:`**{**`PGINSTRUMENT`**\|**`PGOPTIMIZE`**\|**`PGUPDATE`**} ### Arguments **`INCREMENTAL`**
(Optional) Specifies that the linker only applies whole program optimization or link-time code generation (LTCG) to files affected by an edit, instead of the entire project. By default, this flag isn't set when **`/LTCG`** is specified, and the entire project is linked by using whole program optimization. -**`NOSTATUS`** | **`STATUS`**
+**`NOSTATUS`** \| **`STATUS`**
(Optional) Specifies whether the linker displays a progress indicator that shows what percentage of the link is complete. By default, this status information isn't displayed. **`OFF`**
-(Optional) Disables link-time code generation. This behavior is the same as when **`/LTCG`** isn't specified on the command line. +(Optional) Disables link-time code generation. The linker treats all modules compiled with **`/GL`** as if they're compiled without that option, and any MSIL modules cause the link to fail. **`PGINSTRUMENT`**
(Optional) This option is deprecated starting in Visual Studio 2015. Instead, use **`/LTCG`** and [`/GENPROFILE` or `/FASTGENPROFILE`](genprofile-fastgenprofile-generate-profiling-instrumented-build.md) to generate an instrumented build for profile-guided optimization. The data that is collected from instrumented runs is used to create an optimized image. For more information, see [Profile-Guided Optimizations](../profile-guided-optimizations.md). The short form of this option is **`/LTCG:PGI`**. @@ -76,7 +76,7 @@ The rest of this article discusses the link-time code generation done by **`/LTC The linker invokes link-time code generation if it's passed a module that was compiled by using **`/GL`** or an MSIL module (see [`.netmodule` Files as Linker Input](netmodule-files-as-linker-input.md)). If you don't explicitly specify **`/LTCG`** when you pass **`/GL`** or MSIL modules to the linker, the linker eventually detects this situation and restarts the link by using **`/LTCG`**. Explicitly specify **`/LTCG`** when you pass **`/GL`** and MSIL modules to the linker for the fastest possible build performance. -For even faster performance, use **`/LTCG:INCREMENTAL`**. This option tells the linker to reoptimize only the files affected by a source file change, instead of the entire project. This option can significantly reduce the link time required. This option isn't the same option as [incremental linking](incremental-link-incrementally.md). +For even faster performance, use **`/LTCG:INCREMENTAL`**. This option tells the linker to reoptimize only the files affected by a source file change, instead of the entire project. This option can significantly reduce the link time required. This option isn't the same option as [incremental linking](incremental-link-incrementally.md). If you remove the **`/LTCG:INCREMENTAL`** option, also remove any [`/LTCGOUT`](./ltcgout.md) option to improve build times and disk utilization. **`/LTCG`** isn't valid for use with [`/INCREMENTAL`](incremental-link-incrementally.md). @@ -101,7 +101,7 @@ Using **`/LTCG`** and **`/O2`** causes double-alignment optimization. If **`/LTCG`** and **`/O1`** are specified, double alignment isn't performed. If most of the functions in an application are compiled for speed, with a few functions compiled for size (for example, by using the [`optimize`](../../preprocessor/optimize.md) pragma), the compiler double-aligns the functions that are optimized for size if they call functions that require double alignment. -If the compiler can identify all of the call sites of a function, the compiler ignores explicit calling-convention modifiers on a function and tries to optimize the function's calling convention: +If the compiler can identify all of the call sites of a function, the compiler ignores explicit calling-convention modifiers, and tries to optimize the function's calling convention: - pass parameters in registers @@ -124,14 +124,40 @@ Modules that are compiled by using [`/GL`](gl-whole-program-optimization.md) and ### To set this compiler option in the Visual Studio development environment -1. Open the project **Property Pages** dialog box. See [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +The Whole Program Optimization property sets several compiler and linker options, including **`/LTCG`**. We recommend you use this property to change the settings for an entire build configuration. To set Whole Program Optimization for your project: + +1. Open the project **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **General** property page. -1. Modify the **Whole Program Optimization** property. +1. Modify the **Whole Program Optimization** property. Choose **OK** or **Apply** to save your changes. You can also apply **`/LTCG`** to specific builds by choosing **Build** > **Profile Guided Optimization** on the menu bar, or by choosing one of the Profile Guided Optimization options on the shortcut menu for the project. +To enable Link Time Code Generation separately or set a specific Link Time Code Generation option: + +1. Open the project **Property Pages** dialog box. + +1. Select the **Configuration Properties** > **Linker** > **Optimization** property page. + +1. Modify the **Link Time Code Generation** property to one of the following options: + - **Default** + - **Use Fast Link Time Code Generation (LTCG:incremental)** + - **Use Link Time Code Generation (LTCG)** + - **Profile Guided Optimization - Instrument (LTCG:PGInstrument)** + - **Profile Guided Optimization - Optimization (LTCG:PGOptimize)** + - **Profile Guided Optimization - Update (LTCG:PGUpdate)** + +1. Choose **OK** or **Apply** to save your changes. + +To specify whether the linker displays a progress indicator for Link Time Code Generation: + +1. Open the project **Property Pages** dialog box. + +1. Select the **Configuration Properties** > **Linker** > **General** property page. + +1. Modify the **Link Status** property. Choose **OK** or **Apply** to save your changes. + ### To set this compiler option programmatically - See . diff --git a/docs/build/reference/ltcgout.md b/docs/build/reference/ltcgout.md new file mode 100644 index 0000000000..6a02243c24 --- /dev/null +++ b/docs/build/reference/ltcgout.md @@ -0,0 +1,40 @@ +--- +title: "/LTCGOUT (Name LTCG incremental object file)" +description: "The MSVC linker option /LTCGOUT names the incremental link-time code generation object file." +ms.date: 08/31/2022 +f1_keywords: ["VC.Project.VCLinkerTool.LinkTimeCodeGenerationObjectFile", "/ltcgout", "ltcgout"] +helpviewer_keywords: ["Name link-time code generation file in C++ linker", "/LTCGOUT linker option", "-LTCGOUT linker option", "LTCGOUT linker option"] +--- +# `/LTCGOUT` (Name LTCG incremental object file) + +The **`/LTCGOUT`** linker option tells the linker where to put the intermediate *`.iobj`* object file for incremental link-time code generation (**`/LTCG:INCREMENTAL`**). + +## Syntax + +> **`/LTCGOUT:`**\[*`pathname`*] + +### Arguments + +*`pathname`*\ +The optional destination directory and filename for the generated *`.iobj`* file. If the **`/LTCGOUT`** option isn't specified when **`/LTCG:INCREMENTAL`** is used, the filename is created by appending *`.iobj`* to the target base filename. If the **`/LTCGOUT`** option is specified with an empty *`pathname`* when **`/LTCG:INCREMENTAL`** isn't used, no *`.iobj`* file is generated. + +## Remarks + +The **`/LTCGOUT`** linker option tells the linker the path and filename to use for the intermediate *`.iobj`* object file when you specify [`/LTCG:INCREMENTAL`](./ltcg-link-time-code-generation.md). If you remove the **`/LTCG:INCREMENTAL`** option from your project, you should also remove any **`/LTCGOUT`** option. + +### To set this compiler option in the Visual Studio development environment + +1. Open the project **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **Linker** > **Optimization** property page. + +1. Modify the **Link Time Code Generation Object File** property. The option isn't set if this property is empty. + +### To set this compiler option programmatically + +- See . + +## See also + +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/machine-specify-target-platform.md b/docs/build/reference/machine-specify-target-platform.md index f5cf171020..203ac3a325 100644 --- a/docs/build/reference/machine-specify-target-platform.md +++ b/docs/build/reference/machine-specify-target-platform.md @@ -1,22 +1,20 @@ --- description: "Learn more about: /MACHINE (Specify Target Platform)" title: "/MACHINE (Specify Target Platform)" -ms.date: "11/04/2016" +ms.date: 03/25/2022 f1_keywords: ["VC.Project.VCLinkerTool.TargetMachine", "/machine"] helpviewer_keywords: ["mapfiles, creating linker", "target platform", "-MACHINE linker option", "/MACHINE linker option", "MACHINE linker option"] ms.assetid: 8d41bf4b-7e53-4ab9-9085-d852b08d31c2 --- # /MACHINE (Specify Target Platform) -``` -/MACHINE:{ARM|EBC|X64|X86} -``` +> **`/MACHINE:`**{**`ARM`**|**`ARM64`**|**`ARM64EC`**|**`EBC`**|**`X64`**|**`X86`**} ## Remarks -The /MACHINE option specifies the target platform for the program. +The **`/MACHINE`** option specifies the target platform for the program. -Usually, you don't have to specify the /MACHINE option. LINK infers the machine type from the .obj files. However, in some circumstances, LINK cannot determine the machine type and issues a [linker tools error LNK1113](../../error-messages/tool-errors/linker-tools-error-lnk1113.md). If such an error occurs, specify /MACHINE. +Usually, you don't have to specify the **`/MACHINE`** option. LINK infers the machine type from the *`.obj`* files. However, in some circumstances, LINK cannot determine the machine type and issues a [linker tools error LNK1113](../../error-messages/tool-errors/linker-tools-error-lnk1113.md). If such an error occurs, specify **`/MACHINE`**. ### To set this linker option in the Visual Studio development environment @@ -32,5 +30,5 @@ Usually, you don't have to specify the /MACHINE option. LINK infers the machine ## See also -[MSVC linker reference](linking.md)
+[MSVC linker reference](linking.md)\ [MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/macro-substitution.md b/docs/build/reference/macro-substitution.md deleted file mode 100644 index 9d03eb6701..0000000000 --- a/docs/build/reference/macro-substitution.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -description: "Learn more about: Macro Substitution" -title: "Macro Substitution" -ms.date: "11/04/2016" -helpviewer_keywords: ["NMAKE program, macro substitution", "macros, NMAKE", "substitution macros in NMAKE"] -ms.assetid: 47465cfe-fd92-49db-aebe-7c2d7ecceb73 ---- -# Macro Substitution - -When *macroname* is invoked, each occurrence of *string1* in its definition string is replaced by *string2*. - -## Syntax - -``` -$(macroname:string1=string2) -``` - -## Remarks - -Macro substitution is case sensitive and is literal; *string1* and *string2* cannot invoke macros. Substitution does not modify the original definition. You can substitute text in any predefined macro except [$$@](filename-macros.md). - -No spaces or tabs precede the colon; any after the colon are interpreted as literal. If *string2* is null, all occurrences of *string1* are deleted from the macro's definition string. - -## See also - -[Using an NMAKE Macro](using-an-nmake-macro.md) diff --git a/docs/build/reference/makefile-preprocessing-directives.md b/docs/build/reference/makefile-preprocessing-directives.md deleted file mode 100644 index 02a16b32e9..0000000000 --- a/docs/build/reference/makefile-preprocessing-directives.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -description: "Learn more about: Makefile Preprocessing Directives" -title: "Makefile Preprocessing Directives" -ms.date: "08/11/2019" -f1_keywords: ["!UNDEF", "!INCLUDE", "!IFNDEF", "!MESSAGE"] -helpviewer_keywords: ["ERROR directive", "!MESSAGE directive", "IF directive", "!UNDEF directive", "IFDEF directive", "!ELSEIF directive", "!IFDEF directive", "!IF directive", "UNDEF directive", "!CMDSWITCHES directive", "ENDIF directive", "directives, makefile preprocessing", "INCLUDE directive", "IFNDEF directive", "preprocessing directives, makefiles", "!IFNDEF directive", "ELSEIFNDEF directive", "NMAKE program, expressions", "ELSEIF directive", "!ERROR directive", "!ENDIF directive", "MESSAGE directive", "!INCLUDE directive", "!ELSEIFNDEF directive", "CMDSWITCHES directive", "!ELSEIFDEF directive", "!ELSE directive", "NMAKE program, preprocessor directives", "makefiles, preprocessing directives", "ELSE directive", "ELSEIFDEF directive"] -ms.assetid: bcedeccb-d981-469d-b9e8-ab5d097fd8c2 ---- -# Makefile Preprocessing Directives - -Preprocessing directives aren't case-sensitive. The initial exclamation point (!) must appear at the beginning of the line. Zero or more spaces or tabs can appear after the exclamation point, for indentation. - -- `!CMDSWITCHES` {`+` | `-`}*option* ... - - Turns each *option* listed on or off. Spaces or tabs must appear before the `+` or `-` operator; none can appear between the operator and the [option letters](running-nmake.md#nmake-options). Letters aren't case-sensitive and are specified without a slash (`/`). To turn on some options and turn off others, use separate specifications of `!CMDSWITCHES`. - - Only /D, /I, /N, and /S can be used in a makefile. In Tools.ini, all options are allowed except /F, /HELP, /NOLOGO, /X, and /?. Changes specified in a description block don't take effect until the next description block. This directive updates **MAKEFLAGS**; changes are inherited during recursion if **MAKEFLAGS** is specified. - -- `!ERROR` *text* - - Displays *text* in error U1050, then halts NMAKE, even if /K, /I, `.IGNORE`, `!CMDSWITCHES`, or the dash (`-`) command modifier is used. Spaces or tabs before *text* are ignored. - -- `!MESSAGE` *text* - - Displays *text* to standard output. Spaces or tabs before *text* are ignored. - -- `!INCLUDE` [ `<` ] *filename* [ `>` ] - - Reads *filename* as a makefile, then continues with the current makefile. NMAKE searches for *filename* first in the specified or current directory, then recursively through directories of any parent makefiles, then, if *filename* is enclosed by angle brackets (`< >`), in directories specified by the **INCLUDE** macro, which is initially set to the INCLUDE environment variable. Useful to pass `.SUFFIXES` settings, `.PRECIOUS`, and inference rules to recursive makefiles. - -- `!IF` *constant_expression* - - Processes statements between `!IF` and the next `!ELSE` or `!ENDIF` if *constant_expression* evaluates to a nonzero value. - -- `!IFDEF` *macroname* - - Processes statements between `!IFDEF` and the next `!ELSE` or `!ENDIF` if *macroname* is defined. A null macro is considered to be defined. - -- `!IFNDEF` *macroname* - - Processes statements between `!IFNDEF` and the next `!ELSE` or `!ENDIF` if *macroname* isn't defined. - -- `!ELSE` [`IF` *constant_expression* | `IFDEF` *macroname* | `IFNDEF` *macroname*] - - Processes statements between `!ELSE` and the next `!ENDIF` if the prior `!IF`, `!IFDEF`, or `!IFNDEF` statement evaluated to zero. The optional keywords give further control of preprocessing. - -- `!ELSEIF` - - Synonym for `!ELSE IF`. - -- `!ELSEIFDEF` - - Synonym for `!ELSE IFDEF`. - -- `!ELSEIFNDEF` - - Synonym for `!ELSE IFNDEF`. - -- `!ENDIF` - - Marks the end of an `!IF`, `!IFDEF`, or `!IFNDEF` block. Any text after `!ENDIF` on the same line is ignored. - -- `!UNDEF` *macroname* - - Undefines *macroname*. - -## See also - -- [Makefile Preprocessing](makefile-preprocessing.md) diff --git a/docs/build/reference/makefile-preprocessing-operators.md b/docs/build/reference/makefile-preprocessing-operators.md deleted file mode 100644 index 6bd7731acd..0000000000 --- a/docs/build/reference/makefile-preprocessing-operators.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -description: "Learn more about: Makefile Preprocessing Operators" -title: "Makefile Preprocessing Operators" -ms.date: "06/14/2018" -helpviewer_keywords: ["operators [C++], makefile preprocessing", "EXIST operator", "preprocessing NMAKE makefile operators", "NMAKE program, operators", "DEFINED operator", "makefiles, preprocessing operators"] -ms.assetid: a46e4d39-afdb-43c1-ac3b-025d33e6ebdb ---- -# Makefile Preprocessing Operators - -Makefile preprocessing expressions can use operators that act on constant values, exit codes from commands, strings, macros, and file-system paths. To evaluate the expression, the preprocessor first expands macros, and then executes commands, and then performs the operations. Operations are evaluated in the order of explicit grouping in parentheses, and then in the order of operator precedence. The result is a constant value. - -The **DEFINED** operator is a logical operator that acts on a macro name. The expression **DEFINED(**_macroname_**)** is true if *macroname* is defined, even if it does not have an assigned value. **DEFINED** in combination with **!IF** or **!ELSE IF** is equivalent to **!IFDEF** or **!ELSE IFDEF**. However, unlike these directives, **DEFINED** can be used in complex expressions. - -The **EXIST** operator is a logical operator that acts on a file-system path. **EXIST(**_path_**)** is true if *path* exists. The result from **EXIST** can be used in binary expressions. If *path* contains spaces, enclose it in double quotation marks. - -To compare two strings, use the equality (**==**) operator or the inequality (**!=**) operator. Enclose strings in double quotation marks. - -Integer constants can use the unary operators for numerical negation (**-**), one's complement (**~**), and logical negation (**!**). - -Expressions can use the following operators. The operators of equal precedence are grouped together, and the groups are listed in decreasing order of precedence. Unary operators associate with the operand to the right. Binary operators of equal precedence associate operands from left to right. - -|Operator|Description| -|--------------|-----------------| -|**DEFINED(** *macroname* **)**|Produces a logical value for the current definition state of *macroname*.| -|**EXIST(** *path* **)**|Produces a logical value for the existence of a file at *path*.| -||| -|**!**|Unary logical NOT.| -|**~**|Unary one's complement.| -|**-**|Unary negation.| -||| -|*****|Multiplication.| -|**/**|Division.| -|**%**|Modulus (remainder).| -||| -|**+**|Addition.| -|**-**|Subtraction.| -||| -|**\<\<**|Bitwise shift left.| -|**>>**|Bitwise shift right.| -||| -|**\<=**|Less than or equal.| -|**>=**|Greater than or equal.| -|**\<**|Less than.| -|**>**|Greater than.| -||| -|**==**|Equality.| -|**!=**|Inequality.| -||| -|**&**|Bitwise AND.| -|**^**|Bitwise XOR.| -|**|**|Bitwise OR.| -||| -|**&&**|Logical AND.| -||| -|**||**|Logical OR.| - -> [!NOTE] -> The bitwise XOR operator (**^**) is the same as the escape character, and must be escaped (as **^^**) when it is used in an expression. - -## See also - -- [Expressions in Makefile Preprocessing](expressions-in-makefile-preprocessing.md) diff --git a/docs/build/reference/makefile-preprocessing.md b/docs/build/reference/makefile-preprocessing.md index 89f476e540..7092de7a26 100644 --- a/docs/build/reference/makefile-preprocessing.md +++ b/docs/build/reference/makefile-preprocessing.md @@ -1,19 +1,141 @@ --- +title: "Makefile preprocessing" description: "Learn more about: Makefile Preprocessing" -title: "Makefile Preprocessing" -ms.date: "11/04/2016" -helpviewer_keywords: ["preprocessing makefiles", "makefiles, preprocessing"] -ms.assetid: a9185139-97c9-4adb-b4a9-1ec395cce9f8 +ms.date: 09/30/2021 +f1_keywords: ["!UNDEF", "!INCLUDE", "!IFNDEF", "!MESSAGE"] +helpviewer_keywords: ["preprocessing makefiles", "makefiles, preprocessing", "!CMDSWITCHES directive", "!ELSE directive", "!ELSEIF directive", "!ELSEIFDEF directive", "!ELSEIFNDEF directive", "!ENDIF directive", "!ERROR directive", "!IF directive", "!IFDEF directive", "!IFNDEF directive", "!INCLUDE directive", "!MESSAGE directive", "!UNDEF directive", "directives, makefile preprocessing", "preprocessing directives, makefiles", "NMAKE program, expressions", "NMAKE program, preprocessor directives", "makefiles, preprocessing directives", "expressions [C++], makefile preprocessing", "operators [C++], makefile preprocessing", "EXIST operator", "preprocessing NMAKE makefile operators", "NMAKE program, operators", "DEFINED operator", "makefiles, preprocessing operators"] --- -# Makefile Preprocessing +# Makefile preprocessing -You can control the NMAKE session by using preprocessing directives and expressions. Preprocessing instructions can be placed in the makefile or in Tools.ini. Using directives, you can conditionally process your makefile, display error messages, include other makefiles, undefine a macro, and turn certain options on or off. +You can control the NMAKE session by using preprocessing directives and expressions. Preprocessing instructions can be placed in the makefile or in *`Tools.ini`*. Using directives, you can conditionally process your makefile, display error messages, include other makefiles, undefine a macro, and turn certain options on or off. -## What do you want to know more about? +## Makefile Preprocessing Directives -[Makefile preprocessing directives](makefile-preprocessing-directives.md) +Preprocessing directives aren't case-sensitive. The initial exclamation point (**`!`**) must appear at the beginning of the line. Zero or more spaces or tabs can appear after the exclamation point, for indentation. -[Expressions in makefile preprocessing](expressions-in-makefile-preprocessing.md) +- **`!CMDSWITCHES`** { **`+`**_option_ \| **`-`**_option_ } ... + + Turns each listed *option* on or off. Spaces or tabs must appear before the **`+`** or **`-`** operator. No spaces can appear between the operator and the [option letters](running-nmake.md#nmake-options). Letters aren't case-sensitive and are specified without a slash (`/`). To turn on some options and turn off others, use separate specifications of **`!CMDSWITCHES`**. + + Only **`/D`**, **`/I`**, **`/N`**, and **`/S`** can be used in a makefile. In *`Tools.ini`*, all options are allowed except **`/F`**, **`/HELP`**, **`/NOLOGO`**, **`/X`**, and **`/?`**. Changes specified in a description block don't take effect until the next description block. This directive updates **`MAKEFLAGS`**; changes are inherited during recursion if **`MAKEFLAGS`** is specified. + +- **`!ERROR`** *text* + + Displays *text* in error U1050, then halts NMAKE, even if **`/K`**, **`/I`**, **`.IGNORE`**, **`!CMDSWITCHES`**, or the dash (**`-`**) command modifier is used. Spaces or tabs before *text* are ignored. + +- **`!MESSAGE`** *text* + + Displays *text* to standard output. Spaces or tabs before *text* are ignored. + +- **`!INCLUDE`** [ **`<`** ] *filename* [ **`>`** ] + + Reads *filename* as a makefile, then continues with the current makefile. NMAKE searches for *filename* first in the specified or current directory, then recursively through directories of any parent makefiles, then, if *filename* is enclosed by angle brackets (**`< >`**), in directories specified by the **`INCLUDE`** macro, which is initially set to the `INCLUDE` environment variable. Useful to pass `.SUFFIXES` settings, `.PRECIOUS`, and inference rules to recursive makefiles. + +- **`!IF`** *constant_expression* + + Processes statements between **`!IF`** and the next **`!ELSE`** or **`!ENDIF`** if *constant_expression* evaluates to a nonzero value. + +- **`!IFDEF`** *macro_name* + + Processes statements between **`!IFDEF`** and the next **`!ELSE`** or **`!ENDIF`** if *macro_name* is defined. A null macro is considered to be defined. + +- **`!IFNDEF`** *macro_name* + + Processes statements between **`!IFNDEF`** and the next **`!ELSE`** or **`!ENDIF`** if *macro_name* isn't defined. + +- **`!ELSE`** [ **`IF`** *constant_expression* \| **`IFDEF`** *macro_name* \| **`IFNDEF`** *macro_name* ] + + Processes statements between **`!ELSE`** and the next **`!ENDIF`** if the prior **`!IF`**, **`!IFDEF`**, or **`!IFNDEF`** statement evaluated to zero. The optional keywords give further control of preprocessing. + +- **`!ELSEIF`** + + Synonym for **`!ELSE IF`**. + +- **`!ELSEIFDEF`** + + Synonym for **`!ELSE IFDEF`**. + +- **`!ELSEIFNDEF`** + + Synonym for **`!ELSE IFNDEF`**. + +- **`!ENDIF`** + + Marks the end of an **`!IF`**, **`!IFDEF`**, or **`!IFNDEF`** block. Any text after **`!ENDIF`** on the same line is ignored. + +- **`!UNDEF`** *macro_name* + + Undefines *macro_name*. + +## Expressions in makefile preprocessing + +The **`!IF`** or **`!ELSE IF`** *constant_expression* consists of integer constants (in decimal or C-language notation), string constants, or commands. Use parentheses to group expressions. Expressions use C-style signed long integer arithmetic; numbers are in 32-bit two's-complement form in the range -2147483648 to 2147483647. + +Expressions can use operators that act on constant values, exit codes from commands, strings, macros, and file-system paths. + +## Makefile preprocessing operators + +Makefile preprocessing expressions can use operators that act on constant values, exit codes from commands, strings, macros, and file-system paths. To evaluate the expression, the preprocessor first expands macros, and then executes commands, and then does the operations. It evaluates operations in order of explicit grouping in parentheses, and then in order of operator precedence. The result is a constant value. + +The **`DEFINED`** operator is a logical operator that acts on a macro name. The expression **`DEFINED( macro_name )`** is true if *macro_name* is defined, even if it doesn't have an assigned value. **`DEFINED`** in combination with **`!IF`** or **`!ELSE IF`** is equivalent to **`!IFDEF`** or **`!ELSE IFDEF`**. However, unlike these directives, **`DEFINED`** can be used in complex expressions. + +The **`EXIST`** operator is a logical operator that acts on a file-system path. **`EXIST( path )`** is true if *path* exists. The result from **`EXIST`** can be used in binary expressions. If *path* contains spaces, enclose it in double quotation marks. + +To compare two strings, use the equality (**`==`**) operator or the inequality (**`!=`**) operator. Enclose strings in double quotation marks. + +Integer constants can use the unary operators for numerical negation (**`-`**), one's complement (**`~`**), and logical negation (**`!`**). + +Expressions can use the following operators. The operators of equal precedence are grouped together, and the groups are listed in decreasing order of precedence. Unary operators associate with the operand to the right. Binary operators of equal precedence associate operands from left to right. + +| Operator | Description | +|--|--| +| **`DEFINED(`** *macro_name* **`)`** | Produces a logical value for the current definition state of *macro_name*. | +| **`EXIST(`** *path* **`)`** | Produces a logical value for the existence of a file at *path*. | +| | | +| **`!`** | Unary logical NOT. | +| **`~`** | Unary one's complement. | +| **`-`** | Unary negation. | +| | | +| **`*`** | Multiplication. | +| **`/`** | Division. | +| **`%`** | Modulus (remainder). | +| | | +| **`+`** | Addition. | +| **`-`** | Subtraction. | +| | | +| **`<<`** | Bitwise shift left. | +| **`>>`** | Bitwise shift right. | +| | | +| **`<=`** | Less than or equal. | +| **`>=`** | Greater than or equal. | +| **`<`** | Less than. | +| **`>`** | Greater than. | +| | | +| **`==`** | Equality. | +| **`!=`** | Inequality. | +| | | +| **`&`** | Bitwise AND. | +| **`^`** | Bitwise XOR. | +| **` | `** | Bitwise OR. | +| | | +| **`&&`** | Logical AND. | +| | | +| **` || `** | Logical OR. | + +> [!NOTE] +> The bitwise XOR operator (**`^`**) is the same as the escape character, and must be escaped (as **`^^`**) when it's used in an expression. + +## Executing a program in preprocessing + +To use a command's exit code during preprocessing, specify the command, with any arguments, within brackets (**`[ ]`**). Any macros are expanded before the command is executed. NMAKE replaces the command specification with the command's exit code, which can be used in an expression to control preprocessing. + +### Example + +```Makefile +!IF [my_command.exe arg1 arg2] != 0 +!MESSAGE my_command.exe failed! +!ENDIF +``` ## See also diff --git a/docs/build/reference/managing-a-library.md b/docs/build/reference/managing-a-library.md index 12b8cb236a..5ea56fcb14 100644 --- a/docs/build/reference/managing-a-library.md +++ b/docs/build/reference/managing-a-library.md @@ -1,49 +1,47 @@ --- description: "Learn more about: Managing a Library" title: "Managing a Library" -ms.date: "11/04/2016" +ms.date: 03/02/2022 f1_keywords: ["VC.Project.VCLibrarianTool.OVERWRITEAllDefaultLibraries", "VC.Project.VCLibrarianTool.AdditionalDependencies", "VC.Project.VCLibrarianTool.RemoveObjects", "VC.Project.VCLibrarianTool.LibraryPaths", "VC.Project.VCLibrarianTool.OutputFile", "VC.Project.VCLibrarianTool.OVERWRITEDefaultLibraryNames", "VC.Project.VCLibrarianTool.AdditionalLibraryDirectories", "VC.Project.VCLibrarianTool.ListContentsFile", "VC.Project.VCLibrarianTool.ListContents", "VC.Project.VCLibrarianTool.SubSystemVersion", "VC.Project.VCLibrarianTool.OVERWRITEDefaultLibraryName", "VC.Project.VCLibrarianTool.SubSystem"] helpviewer_keywords: ["/LIBPATH library manager option", "OUT library manager option", "CONVERT library manager option", "LIBPATH library manager option", "/LIST library manager option", "object files, building and modifying", "-LINK50COMPAT library manager option", "REMOVE library manager option", "SUBSYSTEM library manager option", "/LINK50COMPAT library manager option", "/OUT library manager option", "LIB [C++], managing COFF libraries", "-CONVERT library manager option", "LINK50COMPAT library manager option", "-OUT library manager option", "-REMOVE library manager option", "-LIST library manager option", "/SUBSYSTEM library manager option", "-SUBSYSTEM library manager option", "/REMOVE library manager option", "-LIBPATH library manager option", "object files", "LIST library manager option", "/CONVERT library manager option"] ms.assetid: f56a8b85-fbdc-4c09-8d8e-00f0ffe1da53 --- # Managing a Library -The default mode for LIB is to build or modify a library of COFF objects. LIB runs in this mode when you do not specify /EXTRACT (to copy an object to a file) or /DEF (to build an import library). +The default mode for LIB is to build or modify a library of COFF objects. LIB runs in this mode when you don't specify **`/EXTRACT`** (to copy an object to a file) or **`/DEF`** (to build an import library). To build a library from objects and/or libraries, use the following syntax: -``` -LIB [options...] files... -``` +> **`LIB`** [*`options...`*] *`files...`* -This command creates a library from one or more input *files*. The *files* can be COFF object files, 32-bit OMF object files, or existing COFF libraries. LIB creates one library that contains all objects in the specified files. If an input file is a 32-bit OMF object file, LIB converts it to COFF before building the library. LIB cannot accept a 32-bit OMF object that is in a library created by the 16-bit version of LIB. You must first use the 16-bit LIB to extract the object; then you can use the extracted object file as input to the 32-bit LIB. +This command creates a library from one or more input files, *`files`*. The *`files`* can be COFF object files, 32-bit OMF object files, or existing COFF libraries. LIB creates one library that contains all objects in the specified files. If an input file is a 32-bit OMF object file, LIB converts it to COFF before building the library. LIB can't accept a 32-bit OMF object that's in a library created by the 16-bit version of LIB. You must first use the 16-bit LIB to extract the object; then you can use the extracted object file as input to the 32-bit LIB. -By default, LIB names the output file using the base name of the first object or library file and the extension .lib. The output file is put in the current directory. If a file already exists with the same name, the output file replaces the existing file. To preserve an existing library, use the /OUT option to specify a name for the output file. +By default, LIB names the output file using the base name of the first object or library file and the extension *`.lib`*. The output file is put in the current directory. If a file already exists with the same name, the output file replaces the existing file. To preserve an existing library, use the **`/OUT`** option to specify a name for the output file. The following options apply to building and modifying a library: -**/LIBPATH:** *dir*
-Overrides the environment library path. For details, see the description of the LINK [/LIBPATH](libpath-additional-libpath.md) option. +**`/LIBPATH:`** *`dir`*\ +Overrides the environment library path and sets it to *`dir`*. For details, see the description of the LINK [`/LIBPATH`](libpath-additional-libpath.md) option. -**/LIST**
-Displays information about the output library to standard output. The output can be redirected to a file. You can use /LIST to determine the contents of an existing library without modifying it. +**`/LIST`**\ +Displays information about the output library to standard output. The output can be redirected to a file. You can use **`/LIST`** to determine the contents of an existing library without modifying it. -**/NAME:** *filename*
-When building an import library, specifies the name of the DLL for which the import library is being built. +**`/NAME:`** *`filename`*\ +When building an import library, *`filename`* specifies the name of the DLL for which the import library is being built. -**/NODEFAULTLIB**
-Removes one or more default libraries from the list of libraries it searches when resolving external references. See [/NODEFAULTLIB](nodefaultlib-ignore-libraries.md) for more information. +**`/NODEFAULTLIB`**\ +Removes one or more default libraries from the list of libraries it searches when resolving external references. For more information, see [`/NODEFAULTLIB`](nodefaultlib-ignore-libraries.md). -**/OUT:** *filename*
-Overrides the default output filename. By default, the output library is created in the current directory, with the base name of the first library or object file on the command line and the extension .lib. +**`/OUT:`** *`filename`*\ +Overrides the default output filename and replaces it with *`filename`*. By default, the output library is created in the current directory, with the base name of the first library or object file on the command line and the extension *`.lib`*. -**/REMOVE:** *object*
-Omits the specified *object* from the output library. LIB creates an output library by combining all objects (whether in object files or libraries), and then deleting any objects specified with /REMOVE. +**`/REMOVE:`** *`object`*\ +Omits the specified *`object`* from the output library. LIB creates an output library by combining all objects (whether in object files or libraries), and then deleting any objects specified with **`/REMOVE`**. -**/SUBSYSTEM:**{**CONSOLE** | **EFI_APPLICATION** | **EFI_BOOT_SERVICE_DRIVER** | **EFI_ROM** | **EFI_RUNTIME_DRIVER** | **NATIVE** | **POSIX** | **WINDOWS** | **WINDOWSCE**}[,#[.##]]
-Tells the operating system how to run a program created by linking to the output library. For more information, see the description of the LINK [/SUBSYSTEM](subsystem-specify-subsystem.md) option. +**`/SUBSYSTEM:`**{**`CONSOLE`** \| **`EFI_APPLICATION`** \| **`EFI_BOOT_SERVICE_DRIVER`** \| **`EFI_ROM`** \| **`EFI_RUNTIME_DRIVER`** \| **`NATIVE`** \| **`POSIX`** \| **`WINDOWS`** \| **`WINDOWSCE`**}[,#[.##]]\ +Tells the operating system how to run a program created by linking to the output library. For more information, see the description of the LINK [`/SUBSYSTEM`](subsystem-specify-subsystem.md) option. -LIB options specified on the command line are not case sensitive. +LIB options specified on the command line aren't case sensitive. You can use LIB to perform the following library-management tasks: @@ -56,7 +54,7 @@ You can use LIB to perform the following library-management tasks: - To delete a member from a library, use the /REMOVE option. LIB processes any specifications of /REMOVE after combining all input objects, regardless of command-line order. > [!NOTE] -> You cannot both delete a member and extract it to a file in the same step. You must first extract the member object using /EXTRACT, then run LIB again using /REMOVE. This behavior differs from that of the 16-bit LIB (for OMF libraries) provided in other Microsoft products. +> You can't both delete a member and extract it to a file in the same step. You must first extract the member object using **`/EXTRACT`**, then run LIB again using **`/REMOVE`**. This behavior differs from that of the 16-bit LIB (for OMF libraries) provided in other Microsoft products. ## See also diff --git a/docs/build/reference/manifest-create-side-by-side-assembly-manifest.md b/docs/build/reference/manifest-create-side-by-side-assembly-manifest.md index 6b8a9ce9ea..0cfe26b687 100644 --- a/docs/build/reference/manifest-create-side-by-side-assembly-manifest.md +++ b/docs/build/reference/manifest-create-side-by-side-assembly-manifest.md @@ -1,44 +1,46 @@ --- -description: "Learn more about: /MANIFEST (Create Side-by-Side Assembly Manifest)" -title: "/MANIFEST (Create Side-by-Side Assembly Manifest)" +description: "Learn more about: /MANIFEST (Create side-by-side assembly manifest)" +title: "/MANIFEST (Create side-by-side assembly manifest)" ms.date: "11/04/2016" -f1_keywords: ["VC.Project.VCLinkerTool.GenerateManifest"] +f1_keywords: ["VC.Project.VCLinkerTool.GenerateManifest", "VC.Project.VCLinkerTool.ManifestEmbed"] helpviewer_keywords: ["-MANIFEST linker option", "/MANIFEST linker option", "MANIFEST linker option"] ms.assetid: 98c52e1e-712c-4f49-b149-4d0a3501b600 --- -# /MANIFEST (Create Side-by-Side Assembly Manifest) +# `/MANIFEST` (Create side-by-side assembly manifest) -``` -/MANIFEST[:{EMBED[,ID=#]|NO}] -``` +Specifies whether the linker should create a side-by-side manifest file. + +## Syntax + +> **`/MANIFEST`**\[**`:`**{**`EMBED`**\[**`,ID=`***`resource_id`*]\|**`NO`**}] ## Remarks -/MANIFEST specifies that the linker should create a side-by-side manifest file. For more information about manifest files, see [Manifest Files Reference](/windows/win32/SbsCs/manifest-files-reference). +The **`/MANIFEST`** linker option tells the linker to create a side-by-side manifest file. For more information about manifest files, see [Manifest files reference](/windows/win32/SbsCs/manifest-files-reference). -The default is /MANIFEST. +The default is **`/MANIFEST`**. -The /MANIFEST:EMBED option specifies that the linker should embed the manifest file in the image as a resource of type RT_MANIFEST. The optional `ID` parameter is the resource ID to use for the manifest. Use a value of 1 for an executable file. Use a value of 2 for a DLL to enable it to specify private dependencies. If the `ID` parameter is not specified, the default value is 2 if the /DLL option is set; otherwise, the default value is 1. +The **`/MANIFEST:EMBED`** option specifies that the linker should embed the manifest file in the image as a resource of type `RT_MANIFEST`. The optional `ID` parameter sets the resource ID to use for the manifest. Use a *`resource_id`* value of 1 for an executable file. Use a value of 2 for a DLL to enable it to specify private dependencies. If the `ID` parameter isn't specified, the default value is 2 if the **`/DLL`** option is set; otherwise, the default value is 1. -Beginning with Visual Studio 2008, manifest files for executables contain a section that specifies User Account Control (UAC) information. If you specify /MANIFEST but specify neither [/MANIFESTUAC](manifestuac-embeds-uac-information-in-manifest.md) nor [/DLL](dll-build-a-dll.md), a default UAC fragment that has the UAC level set to *asInvoker* is inserted into the manifest. For more information about UAC levels, see [/MANIFESTUAC (Embeds UAC information in manifest)](manifestuac-embeds-uac-information-in-manifest.md). +Beginning with Visual Studio 2008, manifest files for executables contain a section that specifies User Account Control (UAC) information. If you specify **`/MANIFEST`** but don't specify either [`/MANIFESTUAC`](manifestuac-embeds-uac-information-in-manifest.md) or [`/DLL`](dll-build-a-dll.md), a default UAC fragment that has the UAC level set to *`asInvoker`* is inserted into the manifest. For more information about UAC levels, see [`/MANIFESTUAC` (Embeds UAC information in manifest)](manifestuac-embeds-uac-information-in-manifest.md). -To change the default behavior for UAC, do one of these: +To change the default behavior for UAC, set one of these options: -- Specify the /MANIFESTUAC option and set the UAC level to the desired value. +- Specify the **`/MANIFESTUAC`** option and set the UAC level to the desired value. -- Or specify the /MANIFESTUAC:NO option if you do not want to generate a UAC fragment in the manifest. +- Or, specify the **`/MANIFESTUAC:NO`** option if you don't want to generate a UAC fragment in the manifest. -If you do not specify /MANIFEST but do specify [/MANIFESTDEPENDENCY](manifestdependency-specify-manifest-dependencies.md) comments, a manifest file is created. A manifest file is not created if you specify /MANIFEST:NO. +If you don't specify **`/MANIFEST`** but do specify [`/MANIFESTDEPENDENCY`](manifestdependency-specify-manifest-dependencies.md) attributes, a manifest file is created. A manifest file isn't created if you specify **`/MANIFEST:NO`**. -If you specify /MANIFEST, the name of the manifest file is the same as the name of your output file, but with .manifest appended to the file name. For example, if your output file name is MyFile.exe, the manifest file name is MyFile.exe.manifest. If you specify /MANIFESTFILE:*name*, the name of the manifest is what you specify in *name*. +If you specify **`/MANIFEST`**, the name of the manifest file is the same as the full name of your output file, but with *`.manifest`* appended to the file name. For example, if your output file name is *`MyFile.exe`*, the manifest file name is *`MyFile.exe.manifest`*. If you specify **`/MANIFESTFILE:`***`name`*, the name of the manifest is what you specify in *`name`*. ### To set this linker option in the Visual Studio development environment -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. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **Linker** > **Manifest File** property page. -1. Modify the **Generate Manifest** property. +1. Modify the **Generate Manifest** property. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically @@ -46,5 +48,9 @@ If you specify /MANIFEST, the name of the manifest file is the same as the name ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[Manifest files reference](/windows/win32/SbsCs/manifest-files-reference)\ +[`/MANIFESTDEPENDENCY` (Specify manifest dependencies)](./manifestdependency-specify-manifest-dependencies.md)\ +[`/MANIFESTFILE` (Name manifest file)](./manifestfile-name-manifest-file.md)\ +[`/MANIFESTUAC` (Embeds UAC information in manifest)](./manifestuac-embeds-uac-information-in-manifest.md)\ +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/manifest-tool-property-pages.md b/docs/build/reference/manifest-tool-property-pages.md index 1c24cfe746..cdf705d3d8 100644 --- a/docs/build/reference/manifest-tool-property-pages.md +++ b/docs/build/reference/manifest-tool-property-pages.md @@ -1,8 +1,7 @@ --- description: "Learn more about: Manifest Tool Property Pages" title: "Manifest Tool Property Pages" -ms.date: "07/24/2019" -ms.topic: "article" +ms.date: 11/30/2021 f1_keywords: - VC.Project.VCManifestTool.SuppressStartupBanner - VC.Project.VCManifestTool.VerboseOutput @@ -23,38 +22,38 @@ f1_keywords: - VC.Project.VCManifestTool.ReplacementsFile - VC.Project.VCManifestTool.UpdateFileHashes - VC.Project.VCManifestTool.UpdateFileHashesSearchPath - - vc.project.AdditionalOptionsPage -ms.assetid: f33499c4-7733-42d9-80e3-8a5018786965 --- # Manifest Tool Property Pages -Use these pages to specify general options for [Mt.exe](/windows/win32/sbscs/mt-exe). These pages are found under **Project** > **Properties** > **Configuration Properties** > **Manifest Tool**. +Use these pages to specify general options for [`Mt.exe`](/windows/win32/sbscs/mt-exe). These pages are found under **Project** > **Properties** > **Configuration Properties** > **Manifest Tool**. ## General Property Page ### Suppress Startup Banner - **Yes (/nologo)** specifies that standard Microsoft copyright data will be concealed when the manifest tool is started. Use this option to suppress unwanted output in log files, when you run mt.exe as part of a build process or from a build environment. + **Yes (`/nologo`)** specifies that standard Microsoft copyright data will be concealed when the manifest tool is started. Use this option to suppress unwanted output in log files when you run *`mt.exe`*, either as part of a build process or from a build environment. ### Verbose Output - **Yes (/verbose)** specifies that additional build information will be displayed during manifest generation. + **Yes (`/verbose`)** specifies that more build information will be displayed during manifest generation. ### Assembly Identity -Uses the /identity option to specify an identity string, which comprises the attributes for the [\ Element](/visualstudio/deployment/assemblyidentity-element-clickonce-application). An identity string begins with the value for the `name` attribute, and is followed by *attribute* = *value* pairs. The attributes in an identity string are delimited by a comma. +Uses the **`/identity`** option to specify an identity string, which holds the attributes for the [`` element](/visualstudio/deployment/assemblyidentity-element-clickonce-application). An identity string begins with the value for the `name` attribute, and is followed by *attribute* = *value* pairs. The attributes in an identity string are delimited by a comma. -This is an example identity string: `Microsoft.Windows.Common-Controls, processorArchitecture=x86, version=6.0.0.0, type=win32, publicKeyToken=6595b64144ccf1df` +Here's an example identity string: + +`Microsoft.Windows.Common-Controls, processorArchitecture=x86, version=6.0.0.0, type=win32, publicKeyToken=6595b64144ccf1df` ## Input and Output Property Page ### Additional Manifest Files -Uses the **/manifest** option to specify the full paths of additional manifest files that the manifest tool will process or merge. Full paths are delimited by a semicolon. (-manifest [manifest1] [manifest2] ...) +Uses the **`/manifest`** option to specify the full paths of more manifest files that the manifest tool will process or merge. Full paths are delimited by a semicolon. (`/manifest [manifest1] [manifest2] ...`) ### Input Resource Manifests -Uses the **/inputresource** option to specify the full path of a resource of type RT_MANIFEST, to input into the manifest tool. The path can be followed by the specified resource ID. For example: +Uses the **`/inputresource`** option to specify the full path of a resource of type `RT_MANIFEST`, to input into the manifest tool. The path can be followed by the specified resource ID. For example: `dll_with_manifest.dll;#1` @@ -66,7 +65,7 @@ Uses the **/inputresource** option to specify the full path of a resource of typ ### Output Manifest File -Specifies the name of the output manifest file. This property is optional when only one manifest file is operated upon by the manifest tool. (-out:[file];#[resource ID]) +Specifies the name of the output manifest file. This property is optional when only one manifest file is operated upon by the manifest tool. (`/out:[file];#[resource ID]`) ### Manifest Resource File @@ -74,23 +73,23 @@ Specifies the output resources file used to embed the manifest into the project ### Generate Catalog Files -Uses the **/makecdfs** option to specify that the manifest tool will generate catalog definition files (.cdf files), which are used to make catalogs. (/makecdfs) +Uses the **`/makecdfs`** option to specify that the manifest tool will generate catalog definition files (*`.cdf`* files), which are used to make catalogs. (`/makecdfs`) ### Generate Manifest From ManagedAssembly -Generates a manifest from a managed assembly. (-managedassemblyname:\[file]) +Generates a manifest from a managed assembly. (`/managedassemblyname:[file]`) ### Suppress Dependency Element -Used with -managedassembly. suppresses the generation of dependency elements in the final manifest. (-nodependency) +Used with **`/managedassemblyname`**. Suppresses the generation of dependency elements in the final manifest. (`/nodependency`) ### Generate Category Tags -Used with -managedassembly. -category causes the category tags to be generated. (-category) +Used with **`/managedassemblyname`**. **`/category`** causes the category tags to be generated. (`/category`) ### DPI Awareness -Specifies whether the application is DPI-aware. By default, the setting is **Yes** for MFC projects and **No** otherwise because only MFC projects have built in DPI awareness. You can override the setting to **Yes** if you add code to handle different DPI settings. Your application might appear fuzzy or small if you set it as DPI-aware when it is not. +Specifies whether the application is DPI-aware. By default, the setting is **Yes** for MFC projects and **No** otherwise because only MFC projects have built in DPI awareness. You can override the setting to **Yes** if you add code to handle different DPI settings. Your application might appear fuzzy or small if it isn't DPI-aware, but you set a DPI-aware option. **Choices** @@ -100,29 +99,29 @@ Specifies whether the application is DPI-aware. By default, the setting is **Yes ## Isolated COM Property Page -For more information about isolated COM, see [Isolated Applications](/windows/win32/SbsCs/isolated-applications) and [How to: Build Isolated Applications to Consume COM Components](../how-to-build-isolated-applications-to-consume-com-components.md). +For more information about isolated COM, see [Isolated applications](/windows/win32/SbsCs/isolated-applications) and [How to: Build isolated applications to consume COM components](../how-to-build-isolated-applications-to-consume-com-components.md). ### Type Library File -Specifies the type library to use for regfree COM manifest support. (-tlb:[file]) +Specifies the type library to use for regfree COM manifest support. (`/tlb:[file]`) ### Registrar Script File -Specifies the registrar script file to use for regfree COM manifest support. (-rgs:[file]) +Specifies the registrar script file to use for regfree COM manifest support. (`/rgs:[file]`) ### Component File Name -Specifies the file name of the component that is built from the .tlb or .rgs specified. (-dll:[file]) +Specifies the file name of the component that is built from the .tlb or .rgs specified. (`/dll:[file]`) ### Replacements File -Specifies the file that contains values for replaceable strings in the RGS file. (replacements:[file]) +Specifies the file that contains values for replaceable strings in the RGS file. (`/replacements:[file]`) ## Advanced Property Page ### Update File Hashes -Computes the hash of files specified in the file elements and updates the hash attribute with this value. (hashupdate:[path]) +Computes the hash of files specified in the `file` elements, and then updates the hash attribute with this value. (`/hashupdate:[path]`) ### Update File Hashes Search Path @@ -130,7 +129,7 @@ Specifies the search path to use when updating the file hashes. ### Additional Options -Additional Options +Allows you to specify more options. ## See also diff --git a/docs/build/reference/manifestfile-name-manifest-file.md b/docs/build/reference/manifestfile-name-manifest-file.md index acd17845b9..32a06f368e 100644 --- a/docs/build/reference/manifestfile-name-manifest-file.md +++ b/docs/build/reference/manifestfile-name-manifest-file.md @@ -4,26 +4,28 @@ title: "/MANIFESTFILE (Name Manifest File)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCLinkerTool.ManifestFile"] helpviewer_keywords: ["MANIFESTFILE linker option", "-MANIFESTFILE linker option", "/MANIFESTFILE linker option"] -ms.assetid: befa5ab2-a9cf-4c9b-969a-e7b4a930f08d --- # /MANIFESTFILE (Name Manifest File) -``` -/MANIFESTFILE:filename -``` +Change the default name of the manifest file. -## Remarks +## Syntax + +> `/MANIFESTFILE:`**filename** -/MANIFESTFILE lets you change the default name of the manifest file. The default name of the manifest file is the file name with .manifest appended. +## Arguments -/MANIFESTFILE will have no effect if you do not also link with [/MANIFEST](manifest-create-side-by-side-assembly-manifest.md). +**filename**\ +The default name of the manifest file is *filename* with `.manifest` appended. + +## Remarks + +`/MANIFESTFILE` has no effect if you do not also link with [/MANIFEST](manifest-create-side-by-side-assembly-manifest.md). ### To set this linker option in the Visual Studio development environment 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** > **Linker** > **Manifest File** property page. - 1. Modify the **Manifest File** property. ### To set this linker option programmatically @@ -32,5 +34,5 @@ ms.assetid: befa5ab2-a9cf-4c9b-969a-e7b4a930f08d ## See also -[MSVC linker reference](linking.md)
+[MSVC linker reference](linking.md)\ [MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/manifestinput-specify-manifest-input.md b/docs/build/reference/manifestinput-specify-manifest-input.md index 3b71cd47df..df8b326f7d 100644 --- a/docs/build/reference/manifestinput-specify-manifest-input.md +++ b/docs/build/reference/manifestinput-specify-manifest-input.md @@ -1,8 +1,8 @@ --- description: "Learn more about: /MANIFESTINPUT (Specify Manifest Input)" title: "/MANIFESTINPUT (Specify Manifest Input)" -ms.date: "07/24/2019" -ms.assetid: a0b0c21e-1f9b-4d8c-bb3f-178f57fa7f1b +ms.date: 03/27/2025 +f1_keywords: ["VC.Project.VCLinkerTool.ManifestInput"] --- # /MANIFESTINPUT (Specify Manifest Input) @@ -10,22 +10,20 @@ Specifies a manifest input file to include in the manifest that's embedded in th ## Syntax -``` -/MANIFESTINPUT:filename -``` +> `/MANIFESTINPUT:`*filename* ### Parameters -*filename*
-The manifest file to include in the embedded manifest. +*filename*\ +The manifest file to include in the embedded manifest. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). ## Remarks -The **/MANIFESTINPUT** option specifies the path of an input file to use to create the embedded manifest in an executable image. If you have multiple manifest input files, use the switch multiple times—once for each input file. The manifest input files are merged to create the embedded manifest. This option requires the **/MANIFEST:EMBED** option. +The **`/MANIFESTINPUT`** option specifies the path of an input file to use to create the embedded manifest in an executable image. If you have multiple manifest input files, use the switch multiple times: once for each input file. The manifest input files are merged to create the embedded manifest. This option requires the **`/MANIFEST:EMBED`** option. -This option can't be set directly in Visual Studio. Instead, use the **Additional Manifest Files** property of the project to specify additional manifest files to include. For more information, see [Manifest Tool Property Pages](manifest-tool-property-pages.md). +This option can't be set directly in Visual Studio. Instead, use the **Additional Manifest Files** property of the project to specify other manifest files to include. For more information, see [Manifest Tool Property Pages](manifest-tool-property-pages.md). ## See also -[MSVC linker reference](linking.md)
+[MSVC linker reference](linking.md)\ [MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/md-mt-ld-use-run-time-library.md b/docs/build/reference/md-mt-ld-use-run-time-library.md index 0db8d589cb..0867d33ed0 100644 --- a/docs/build/reference/md-mt-ld-use-run-time-library.md +++ b/docs/build/reference/md-mt-ld-use-run-time-library.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: /MD, /MT, /LD (Use Run-Time Library)" -title: "/MD, -MT, -LD (Use Run-Time Library)" -ms.date: "07/17/2019" +title: "/MD, /MT, /LD (Use runtime library)" +description: "Learn more about: /MD, /MT, /LD (Use runtime library)" +ms.date: "01/13/2025" f1_keywords: ["/ld", "/mt", "VC.Project.VCCLWCECompilerTool.RuntimeLibrary", "VC.Project.VCCLCompilerTool.RuntimeLibrary", "/md", "/ml"] helpviewer_keywords: ["/MT compiler option [C++]", "-MD compiler option [C++]", "threading [C++], multithread compiler option", "MSVCRTD.lib", "MSVCRT.lib", "LIBCMT.lib", "MD compiler option [C++]", "/MD compiler option [C++]", "MT compiler option [C++]", "LD compiler option [C++]", "MDd compiler option [C++]", "-MDd compiler option [C++]", "LIBCD.lib", "-MTd compiler option [C++]", "MTd compiler option [C++]", "/MTd compiler option [C++]", "-LD compiler option [C++]", "/MDd compiler option [C++]", "multithread compiler option", "_STATIC_CPPLIB symbol", "LIBC.lib", "/LD compiler option [C++]", "DLLs [C++], compiler options", "LIBCMTD.lib", "-MT compiler option [C++]"] -ms.assetid: cf7ed652-dc3a-49b3-aab9-ad60e5395579 --- -# /MD, /MT, /LD (Use Run-Time Library) +# /MD, /MT, /LD (Use runtime library) -Indicates whether a multithreaded module is a DLL and specifies retail or debug versions of the run-time library. +Indicates whether a multithreaded module is a DLL and specifies retail or debug versions of the runtime library. ## Syntax @@ -22,27 +21,25 @@ Indicates whether a multithreaded module is a DLL and specifies retail or debug |Option|Description| |------------|-----------------| -|**/MD**|Causes the application to use the multithread-specific and DLL-specific version of the run-time library. Defines `_MT` and `_DLL` and causes the compiler to place the library name MSVCRT.lib into the .obj file.

Applications compiled with this option are statically linked to MSVCRT.lib. This library provides a layer of code that enables the linker to resolve external references. The actual working code is contained in MSVCR*versionnumber*.DLL, which must be available at run time to applications linked with MSVCRT.lib.| -|**/MDd**|Defines `_DEBUG`, `_MT`, and `_DLL` and causes the application to use the debug multithread-specific and DLL-specific version of the run-time library. It also causes the compiler to place the library name MSVCRTD.lib into the .obj file.| -|**/MT**|Causes the application to use the multithread, static version of the run-time library. Defines `_MT` and causes the compiler to place the library name LIBCMT.lib into the .obj file so that the linker will use LIBCMT.lib to resolve external symbols.| -|**/MTd**|Defines `_DEBUG` and `_MT`. This option also causes the compiler to place the library name LIBCMTD.lib into the .obj file so that the linker will use LIBCMTD.lib to resolve external symbols.| -|**/LD**|Creates a DLL.

Passes the **/DLL** option to the linker. The linker looks for, but does not require, a `DllMain` function. If you do not write a `DllMain` function, the linker inserts a `DllMain` function that returns TRUE.

Links the DLL startup code.

Creates an import library (.lib), if an export (.exp) file is not specified on the command line. You link the import library to applications that call your DLL.

Interprets [/Fe (Name EXE File)](fe-name-exe-file.md) as naming a DLL rather than an .exe file. By default, the program name becomes *basename*.dll instead of *basename*.exe.

Implies **/MT** unless you explicitly specify **/MD**.| -|**/LDd**|Creates a debug DLL. Defines `_MT` and `_DEBUG`.| +|**/MD**|Use the multithread-specific and DLL-specific version of the runtime library. Defines `_MT` and `_DLL`. The linker uses the `MSVCRT.lib` import library to resolve runtime symbols.| +|**/MDd**|Use the debug multithread-specific and DLL-specific version of the runtime library. Defines `_DEBUG`, `_MT`, and `_DLL`. The linker uses the `MSVCRTD.lib` import library to resolve runtime symbols.| +|**/MT**| Use the multithread, static version of the runtime library. Defines `_MT`. The linker uses `LIBCMT.lib` to resolve runtime symbols.| +|**/MTd**| Use the debug multithread, static version of the runtime library. Defines `_DEBUG` and `_MT`. The linker uses `LIBCMTD.lib` to resolve runtime symbols.| +|**/LD**|Create a DLL.

Passes the **/DLL** option to the linker. The linker looks for, but does not require, a `DllMain` function. If you don't write a `DllMain` function, the linker inserts a `DllMain` function that returns TRUE.

Links the DLL startup code.

Creates an import library (`.lib`), if an export (`.exp`) file is not specified on the command line. You link the import library to applications that call your DLL.

Interprets [/Fe (Name EXE File)](fe-name-exe-file.md) as naming a DLL rather than an `.exe` file. By default, the program name becomes *basename*.dll instead of *basename*.exe.

Implies **/MT** unless you explicitly specify **/MD**.| +|**/LDd**|Create a debug DLL. Defines `_MT` and `_DEBUG`.| -For more information about C run-time libraries and which libraries are used when you compile with [/clr (Common Language Runtime Compilation)](clr-common-language-runtime-compilation.md), see [CRT Library Features](../../c-runtime-library/crt-library-features.md). +For more information about C runtime libraries and which libraries are used when you compile with [/clr (Common Language Runtime Compilation)](clr-common-language-runtime-compilation.md), see [CRT Library Features](../../c-runtime-library/crt-library-features.md). -All modules passed to a given invocation of the linker must have been compiled with the same run-time library compiler option (**/MD**, **/MT**, **/LD**). +All modules passed to a given invocation of the linker must have been compiled with the same runtime library compiler option (**/MD**, **/MT**, **/LD**). -For more information about how to use the debug versions of the run-time libraries, see [C Run-Time Library Reference](../../c-runtime-library/c-run-time-library-reference.md). +For more information about how to use the debug versions of the runtime libraries, see [C runtime Library Reference](../../c-runtime-library/c-run-time-library-reference.md). For more about DLLs, see [Create C/C++ DLLs in Visual Studio](../dlls-in-visual-cpp.md). ### To set this compiler option in the Visual Studio development environment 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++** > **Code Generation** property page. - 1. Modify the **Runtime Library** property. ### To set this compiler option programmatically @@ -51,5 +48,6 @@ For more about DLLs, see [Create C/C++ DLLs in Visual Studio](../dlls-in-visual- ## See also -[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) +[MSVC Compiler Options](compiler-options.md)\ +[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md)\ +[The Great C Runtime (CRT) Refactoring](https://devblogs.microsoft.com/cppblog/the-great-c-runtime-crt-refactoring/) \ No newline at end of file diff --git a/docs/build/reference/microsoft-extensions-to-c-and-cpp.md b/docs/build/reference/microsoft-extensions-to-c-and-cpp.md index 17f74d81fd..77eceff58e 100644 --- a/docs/build/reference/microsoft-extensions-to-c-and-cpp.md +++ b/docs/build/reference/microsoft-extensions-to-c-and-cpp.md @@ -1,108 +1,103 @@ --- description: "Learn more about: Microsoft extensions to C and C++" title: "Microsoft extensions to C and C++" -ms.date: "06/14/2018" +ms.date: 03/15/2022 helpviewer_keywords: ["or_eq operator", "~ operator, extensions to C/C++", "& operator, extensions to C/C++", "&= operator", "iso646.h header", "Xor operator, Microsoft extensions to C/C++", "!= operator", "! operator, extension to C++", "Or operator, Microsoft extensions to C/C++", "^ operator, extensions to C/C++", "^= operator, C++ extensions", "xor_eq operator", "and_eq operator", "Microsoft extensions to C/C++", "|= operator", "|| operator", "And operator, extensions to C/C++", "NOT operator", "&& operator", "extensions, C language", "Visual C++, extensions to C/C++", "| operator, extensions", "not_eq operator", "Visual C, Microsoft extensions", "extensions", "compl method"] -ms.assetid: e811a74a-45ba-4c00-b206-2f2321b8689a --- # Microsoft extensions to C and C++ -Visual C++ extends the ANSI C and ANSI C++ standards as follows. +Microsoft Visual C++ (MSVC) extends the C and C++ language standards in several ways, detailed in this article. -## Keywords - -Several keywords are added. In the list in [Keywords](../../cpp/keywords-cpp.md), the keywords that have two leading underscores are Visual C++ extensions. +The MSVC C++ compiler defaults to support for ISO C++14 with some ISO C++17 features and some Microsoft-specific language extensions. For more information on supported features, see [Microsoft C/C++ language conformance by Visual Studio version](../../overview/visual-cpp-language-conformance.md). You can use the **`/std`** compiler option to enable full support for ISO C++17 and ISO C++20 language features. For more information, see [`/std` (Specify language standard version)](std-specify-language-standard-version.md). -## Out of class definition of static const integral (or enum) members +Where specified, some MSVC C++ language extensions can be disabled by use of the **`/Za`** compiler option. In Visual Studio 2017 and later versions, the **`/permissive-`** compiler option disables Microsoft-specific C++ language extensions. The **`/permissive-`** compiler option is implicitly enabled by the **`/std:c++20`** and **`/std:c++latest`** compiler options. -Under the standard (**/Za**), you must make an out-of-class definition for data members, as shown here: +By default, when MSVC compiles code as C, it implements ANSI C89 with Microsoft-specific language extensions. Some of these MSVC extensions are standardized in ISO C99 and later. Most MSVC C extensions can be disabled by use of the **`/Za`** compiler option, as detailed later in this article. You can use the **`/std`** compiler option to enable support for ISO C11 and C17. For more information, see [`/std` (Specify language standard version)](std-specify-language-standard-version.md). -```cpp -class CMyClass { - static const int max = 5; - int m_array[max]; -} -// . . . -const int CMyClass::max; // out of class definition -``` +The standard C runtime library is implemented by the Universal C runtime library (UCRT) in Windows. The UCRT also implements many POSIX and Microsoft-specific library extensions. The UCRT supports the ISO C11 and C17 C runtime library standards, with certain implementation-specific caveats. It doesn't support the full ISO C99 standard C runtime library. For more information, see [compatibility](../../c-runtime-library/compatibility.md) in the Universal C runtime library documentation. -Under **/Ze**, the out-of-class definition is optional for static, const integral, and const enum data members. Only integrals and enums that are static and const can have initializers in a class; the initializing expression must be a const expression. +## Keywords -To avoid errors when an out-of-class definition is provided in a header file and the header file is included in multiple source files, use [selectany](../../cpp/selectany.md). For example: - -```cpp -__declspec(selectany) const int CMyClass::max = 5; -``` +MSVC adds several Microsoft-specific keywords to C and C++. In the list in [Keywords](../../cpp/keywords-cpp.md), the keywords that have two leading underscores are MSVC extensions. ## Casts -Both the C++ compiler and C compiler support these kinds of non-ANSI casts: +Both the C++ compiler and C compiler support these kinds of non-standard casts: -- Non-ANSI casts to produce l-values. For example: +- The C compiler supports non-standard casts to produce l-values. For example: ```C char *p; (( int * ) p )++; + // In C with /W4, both by default and under /Ze: + // warning C4213: nonstandard extension used: cast on l-value + // Under /TP or /Za: + // error C2105: '++' needs l-value ``` > [!NOTE] - > This extension is available in the C language only. You can use the following ANSI C standard form in C++ code to modify a pointer as if it is a pointer to a different type. + > This extension is available in the C language only. You can use the following C standard form in C++ code to modify a pointer as if it's a pointer to a different type. - The preceding example could be rewritten as follows to conform to the ANSI C standard. + The preceding example could be rewritten as follows to conform to the C standard. ```C p = ( char * )(( int * )p + 1 ); ``` -- Non-ANSI casts of a function pointer to a data pointer. For example: +- Both the C and C++ compilers support non-standard casts of a function pointer to a data pointer. For example: ```C int ( * pfunc ) (); int *pdata; pdata = ( int * ) pfunc; - ``` - - To perform the same cast and also maintain ANSI compatibility, you can cast the function pointer to a `uintptr_t` before you cast it to a data pointer: - - ```C - pdata = ( int * ) (uintptr_t) pfunc; + /* No diagnostic at any level, whether compiled with default options or under /Za */ ``` ## Variable-length argument lists -Both the C++ compiler and C compiler support a function declarator that specifies a variable number of arguments, followed by a function definition that provides a type instead: +Both C and C++ compilers support a function declarator that specifies a variable number of arguments, followed by a function definition that provides a type instead: ```cpp void myfunc( int x, ... ); void myfunc( int x, char * c ) { } +// In C with /W4, either by default or under /Ze: +// warning C4212: nonstandard extension used: function declaration used ellipsis +// In C with /W4, under /Za: +// warning C4028: formal parameter 2 different from declaration +// In C++, no diagnostic by default or under /Za. ``` ## Single-line comments -The C compiler supports single-line comments, which are introduced by using two forward slash (//) characters: +The C compiler supports single-line comments, which are introduced by using two forward slash (`//`) characters: ```C // This is a single-line comment. ``` +Single-line comments are a C99 feature. They're unaffected by **`/Za`** and cause no diagnostic at any level. + ## Scope The C compiler supports the following scope-related features. -- Redefinitions of extern items as static: +- Redefinitions of `extern` items as `static`: ```C extern int clip(); - static int clip() - {} + static int clip() {} + // In C and C++ with /W4, either by default or under /Ze: + // warning C4211: nonstandard extension used: redefined extern to static + // In C and C++ under /Za: + // error C2375: 'clip': redefinition; different linkage ``` - Use of benign typedef redefinitions within the same scope: ```C typedef int INT; - typedef int INT; + typedef int INT; // No diagnostic at any level in C or C++ ``` - Function declarators have file scope: @@ -110,7 +105,8 @@ The C compiler supports the following scope-related features. ```C void func1() { - extern int func2( double ); + extern double func2( double ); + // In C at /W4: warning C4210: nonstandard extension used: function given file scope } int main( void ) { @@ -118,7 +114,7 @@ The C compiler supports the following scope-related features. } // /Za passes 4 as type int ``` -- Use of block-scope variables that are initialized by using nonconstant expressions: +- Use of block-scope variables that are initialized by using non-constant expressions: ```C int clip( int ); @@ -144,7 +140,11 @@ The C compiler supports the following data declaration and definition features. - Mixed character and string constants in an initializer: ```C - char arr[5] = {'a', 'b', "cde"}; + char arr[6] = {'a', 'b', "cde"}; + // In C with /W4, either by default or under /Ze: + // warning C4207: nonstandard extension used: extended initializer form + // Under /Za: + // error C2078: too many initializers ``` - Bit fields that have base types other than **`unsigned int`** or **`signed int`**. @@ -153,6 +153,10 @@ The C compiler supports the following data declaration and definition features. ```C x; + // By default or under /Ze, /Za, /std:c11, and /std:c17, when /W4 is specified: + // warning C4431: missing type specifier - int assumed. Note: C no longer supports default-int + // warning C4218: nonstandard extension used: must specify at least a storage class or a type + */ int main( void ) { x = 1; @@ -166,6 +170,10 @@ The C compiler supports the following data declaration and definition features. { char *c; int zarray[]; + // In C with /W4, either by default, under /Ze, /std:c11, and /std:c17: + // warning C4200: nonstandard extension used: zero-sized array in struct/union + // Under /Za: + // error C2133: 'zarray': unknown size }; ``` @@ -177,6 +185,10 @@ The C compiler supports the following data declaration and definition features. int i; char *s; }; + // By default or under /Ze, /std:c11, and /std:c17, when /W4 is specified: + // warning C4094: untagged 'struct' declared no symbols + // Under /Za: + // error C2059: syntax error: 'empty declaration' ``` - Unnamed (anonymous) unions: @@ -187,88 +199,38 @@ The C compiler supports the following data declaration and definition features. int i; float fl; }; - ``` - -- Unnamed members: - - ```C - struct s - { - unsigned int flag : 1; - unsigned int : 31; - } + // By default or under /Ze, /std:c11, and /std:c17, when /W4 is specified: + // warning C4094: untagged 'union' declared no symbols + // Under /Za: + // error C2059: syntax error: 'empty declaration' ``` ## Intrinsic floating-point functions -Both the x86 C++ compiler and C compiler support inline generation of the `atan`, `atan2`, `cos`, `exp`, `log`, `log10`, `sin`, `sqrt`, and `tan` functions when **/Oi** is specified. For the C compiler, ANSI conformance is lost when these intrinsics are used, because they do not set the `errno` variable. - -## Passing a non-const pointer parameter to a function that expects a reference to a const pointer parameter - -This is an extension to C++. This code will compile with **/Ze**: +Both the x86 C++ compiler and C compiler support inline generation of the `atan`, `atan2`, `cos`, `exp`, `log`, `log10`, `sin`, `sqrt`, and `tan` functions when **`/Oi`** is specified. These intrinsics don't conform to the standard, because they don't set the `errno` variable. -```cpp -typedef int T; - -const T acT = 9; // A constant of type 'T' -const T* pcT = &acT; // A pointer to a constant of type 'T' - -void func2 ( const T*& rpcT ) // A reference to a pointer to a constant of type 'T' -{ - rpcT = pcT; -} - -T* pT; // A pointer to a 'T' - -void func () -{ - func2 ( pT ); // Should be an error, but isn't detected - *pT = 7; // Invalidly overwrites the constant 'acT' -} -``` - -## ISO646.H not enabled - -Under **/Ze**, you have to include iso646.h if you want to use text forms of the following operators: - -- && (and) - -- &= (and_eq) - -- & (bitand) +## *`ISO646.H`* not enabled -- | (bitor) +Under **`/Ze`**, you have to include *`iso646.h`* if you want to use text forms of the following operators: -- ~ (compl) +| Operator | Text form | +|--|--| +| `&&` | `and` | +| `&=` | `and_eq` | +| `&` | `bitand` | +| `|` | `bitor` | +| `~` | `compl` | +| `!` | `not` | +| `!=` | `not_eq` | +| `||` | `or` | +| `|=` | `or_eq` | +| `^` | `xor` | +| `^=` | `xor_eq` | -- ! (not) - -- != (not_eq) - -- || (or) - -- |= (or_eq) - -- ^ (xor) - -- ^= (xor_eq) - -## Address of string literal has type const char [], not const char (*) [] - -The following example will output `char const (*)[4]` under **/Za**, but `char const [4]` under **/Ze**. - -```cpp -#include -#include - -int main() -{ - printf_s("%s\n", typeid(&"abc").name()); -} -``` +These text forms are available as C++ keywords under **`/Za`** or when **`/permissive-`** is specified or implied. ## See also -- [/Za, /Ze (Disable Language Extensions)](za-ze-disable-language-extensions.md) -- [MSVC Compiler Options](compiler-options.md) -- [MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) +[`/Za`, `/Ze` (Disable language extensions)](za-ze-disable-language-extensions.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/midl-property-pages.md b/docs/build/reference/midl-property-pages.md index 612fa24307..66c3955c39 100644 --- a/docs/build/reference/midl-property-pages.md +++ b/docs/build/reference/midl-property-pages.md @@ -47,7 +47,6 @@ f1_keywords: - VC.Project.VCMidlTool.StructMemberAlignment - VC.Project.VCMidlTool.RedirectOutputAndErrors - VC.Project.VCMidlTool.MinimumTargetSystem - - vc.project.AdditionalOptionsPage --- # MIDL Property Pages diff --git a/docs/build/reference/module-exportheader.md b/docs/build/reference/module-exportheader.md index bf2899dee7..5c1b8a839c 100644 --- a/docs/build/reference/module-exportheader.md +++ b/docs/build/reference/module-exportheader.md @@ -23,13 +23,13 @@ The argument to `/exportHeader` is a `/headerName` command-line option that spec ## Remarks -**`/exportHeader`** is available starting in Visual Studio 2019 version 16.10 Preview 2. +**`/exportHeader`** is available starting in Visual Studio 2019 version 16.10. -The **`/exportHeader`** compiler option requires you enable the [/std:c++latest](std-specify-language-standard-version.md) option. +The **`/exportHeader`** compiler option requires you enable the [`/std:c++20`](std-specify-language-standard-version.md) or later compiler option (such as **`/std:c++latest`**). One **`/exportHeader`** compiler option can specify as many header-name arguments as your build requires. You don't need to specify them separately. -The compiler implicitly enables the new preprocessor when this switch is used. That is, [`/Zc:preprocessor`](zc-preprocessor.md) is added to the command line by the compiler if any form of `/exportHeader` is used on the command line. To opt out of the implicit `/Zc:preprocessor`, use: `/Zc:preprocessor-` +The compiler implicitly enables the new preprocessor when this option is used. That is, [`/Zc:preprocessor`](zc-preprocessor.md) is added to the command line by the compiler if any form of `/exportHeader` is used on the command line. To opt out of the implicit `/Zc:preprocessor`, use: `/Zc:preprocessor-` By default, the compiler doesn't produce an object file when a header unit is compiled. To produce an object file, specify the **`/Fo`** compiler option. For more information, see [`/Fo` (Object File Name)](fo-object-file-name.md). @@ -53,11 +53,19 @@ cl . . . /std:c++latest /exportHeader /headerName:quote util/util.h ### To set this compiler option in the Visual Studio development environment -You normally shouldn't set this in the Visual Studio development environment. It is set by the build system. +You normally shouldn't set this option in the Visual Studio development environment unless you use a different extension for your header files. By default, the build system applies this option to compiled files that have a *`.h`* extension, or no extension. + +1. To apply the **`/exportHeader`** option to a file explicitly in the IDE, select the file in **Solution Explorer**. Right-click to open the context menu and select **Properties** to open the Property Pages dialog. + +1. Set the **Configuration** dropdown to **All Configurations**. Set the **Platform** dropdown to **All Platforms**. + +1. Open the **Configuration Properties** > **C/C++** > **Advanced** property page. + +1. Use the dropdown control to modify the **Compile As** property to **Compile as C++ Header Unit (/exportHeader)**. Choose **OK** or **Apply** to save your changes. ## See also -[`/headerName (Build a header unit from the specified header)`](headername.md) \ +[`/headerName` (Build a header unit from the specified header)](headername.md)\ [`/headerUnit` (Use header unit IFC)](headerunit.md)\ [`/reference` (Use named module IFC)](module-reference.md)\ [`/translateInclude` (Translate include directives into import directives)](translateinclude.md) diff --git a/docs/build/reference/module-reference.md b/docs/build/reference/module-reference.md index fafe887f2f..10f51331a9 100644 --- a/docs/build/reference/module-reference.md +++ b/docs/build/reference/module-reference.md @@ -1,8 +1,8 @@ --- title: "/reference (Use named module IFC)" description: "Use the /reference compiler option to create module header units for the header-name or include files specified." -ms.date: 04/13/2020 -f1_keywords: ["/reference"] +ms.date: 02/17/2022 +f1_keywords: ["/reference", "VC.Project.VCCLCompilerTool.AdditionalModuleDependencies"] helpviewer_keywords: ["/reference", "Use named module IFC"] --- # `/reference` (Use named module IFC) @@ -24,9 +24,9 @@ A valid name of an exported primary module interface unit name or full module pa ## Remarks -In most cases you won't need to specify this switch because the project system discovers module dependencies within a solution automatically. +In most cases, you won't need to specify this switch because the project system discovers module dependencies within a solution automatically. -The **`/reference`** compiler option requires you enable the [/std:c++latest](std-specify-language-standard-version.md) option. The **`/reference`** option is available starting in Visual Studio 2019 version 16.10 Preview 2. +The **`/reference`** compiler option requires you enable the [`/std:c++20`](std-specify-language-standard-version.md) or later compiler option (such as **`/std:c++latest`**). The **`/reference`** option is available starting in Visual Studio 2019 version 16.10. If the **`/reference`** argument is a *`filename`* without a *`module-name`*, the file gets opened at runtime to verify the *`filename`* argument names a specific import. It can result in slower runtime performance in scenarios that have many **`/reference`** arguments. @@ -76,6 +76,7 @@ cl ... /std:c++latest /reference m=m.ifc /reference M:Part1=m-part.ifc /referenc ## See also +[`/scanDependencies` (List module dependencies in standard form)](scandependencies.md)\ [`/sourceDependencies:directives` (List module and header unit dependencies)](sourcedependencies-directives.md)\ [`/headerUnit` (Use header unit IFC)](headerunit.md)\ [`/exportHeader` (Create header units)](module-exportheader.md) diff --git a/docs/build/reference/mp-build-with-multiple-processes.md b/docs/build/reference/mp-build-with-multiple-processes.md index b63a912e7b..de05d5234b 100644 --- a/docs/build/reference/mp-build-with-multiple-processes.md +++ b/docs/build/reference/mp-build-with-multiple-processes.md @@ -1,122 +1,122 @@ --- -description: "Learn more about: /MP (Build with Multiple Processes)" -title: "/MP (Build with Multiple Processes)" -ms.date: "04/08/2019" +description: "Learn more about: /MP (Build with multiple processes)" +title: "/MP (Build with multiple processes)" +ms.date: 06/13/2022 f1_keywords: ["VC.Project.VCCLCompilerTool.MultiProcessorCompilation"] helpviewer_keywords: ["-MP compiler option (C++)", "/MP compiler option (C++)", "MP compiler option (C++)", "cl.exe compiler, multi-process build"] --- -# /MP (Build with Multiple Processes) +# `/MP` (Build with multiple processes) -The **/MP** option can reduce the total time to compile the source files on the command line. The **/MP** option causes the compiler to create one or more copies of itself, each in a separate process. Then these copies simultaneously compile the source files. Consequently, the total time to build the source files can be significantly reduced. +The **`/MP`** option can reduce the total time to compile the source files on the command line. The **`/MP`** option causes the compiler to create one or more copies of itself, each in a separate process. Then these instances simultaneously compile the source files. In some cases, the total time to build the source files can be reduced significantly. ## Syntax -> **/MP**[*processMax*] +> **`/MP`**[*`processMax`*] ## Arguments -*processMax*
+*`processMax`*\ (Optional) The maximum number of processes that the compiler can create. -The *processMax* argument must range from 1 through 65536. Otherwise, the compiler issues warning message **D9014**, ignores the *processMax* argument, and assumes the maximum number of processes is 1. +The *`processMax`* argument must range from 1 through 65536. Otherwise, the compiler issues warning message **D9014**, ignores the *`processMax`* argument, and assumes the maximum number of processes is 1. -If you omit the *processMax* argument, the compiler retrieves the number of [effective processors](#effective_processors) on your computer from the operating system, and creates a process for each processor. +If you omit the *`processMax`* argument, the compiler retrieves the number of [effective processors](#effective_processors) on your computer from the operating system, and creates a process for each processor. ## Remarks -The **/MP** compiler option can significantly reduce build time when you compile many files. To improve build time, the compiler creates up to *processMax* copies of itself, and then uses those copies to compile your source files at the same time. The **/MP** option applies to compilations, but not to linking or link-time code generation. By default the **/MP** option is off. +The **`/MP`** compiler option can significantly reduce build time when you compile many files. To improve build time, the compiler creates up to *`processMax`* copies of itself, and then uses those copies to compile your source files at the same time. The **`/MP`** option applies to compilations, but not to linking or link-time code generation. By default the **`/MP`** option is off. -The improvement in build time depends on the number of processors on a computer, the number of files to compile, and the availability of system resources, such as I/O capacity. Experiment with the **/MP** option to determine the best setting to build a particular project. For advice to help you make that decision, see [Guidelines](#guidelines). +The improvement in build time depends on the number of processors on a computer, the number of files to compile, and the availability of system resources, such as I/O capacity. Experiment with the **`/MP`** option to determine the best setting to build a particular project. For advice to help you make that decision, see [Guidelines](#guidelines). -## Incompatible Options and Language Features +## Incompatible options and language features -The **/MP** option is incompatible with some compiler options and language features. If you use an incompatible compiler option with the **/MP** option, the compiler issues warning **D9030** and ignores the **/MP** option. If you use an incompatible language feature, the compiler issues error [C2813](../../error-messages/compiler-errors-2/compiler-error-c2813.md) then ends or continues depending on the current compiler warning level option. +The **`/MP`** option is incompatible with some compiler options and language features. If you use an incompatible compiler option with the **`/MP`** option, the compiler issues warning **D9030** and ignores the **`/MP`** option. If you use an incompatible language feature, the compiler issues error [C2813](../../error-messages/compiler-errors-2/compiler-error-c2813.md) then ends or continues depending on the current compiler warning level option. > [!NOTE] > Most options are incompatible because if they were permitted, the concurrently executing compilers would write their output at the same time to the console or to a particular file. As a result, the output would intermix and be garbled. In some cases, the combination of options would make the performance worse. -The following table lists compiler options and language features that are incompatible with the **/MP** option: +The following table lists compiler options and language features that are incompatible with the **`/MP`** option: -|Option or Language Feature|Description| -|--------------------------------|-----------------| -|[#import](../../preprocessor/hash-import-directive-cpp.md) preprocessor directive|Converts the types in a type library into C++ classes, and then writes those classes to a header file.| -|[/E](e-preprocess-to-stdout.md), [/EP](ep-preprocess-to-stdout-without-hash-line-directives.md)|Copies preprocessor output to the standard output (**stdout**).| -|[/Gm](gm-enable-minimal-rebuild.md)|Deprecated. Enables an incremental rebuild.| -|[/showIncludes](showincludes-list-include-files.md)|Writes a list of include files to the standard error (**stderr**).| -|[/Yc](yc-create-precompiled-header-file.md)|Writes a precompiled header file.| +| Option or Language Feature | Description | +|--|--| +| [`#import`](../../preprocessor/hash-import-directive-cpp.md) preprocessor directive | Converts the types in a type library into C++ classes, and then writes those classes to a header file. | +| [`/E`](e-preprocess-to-stdout.md), [`/EP`](ep-preprocess-to-stdout-without-hash-line-directives.md) | Copies preprocessor output to the standard output (**`stdout`**). | +| [`/Gm`](gm-enable-minimal-rebuild.md) | Deprecated. Enables an incremental rebuild. | +| [`/showIncludes`](showincludes-list-include-files.md) | Writes a list of include files to the standard error (**`stderr`**). | +| [`/Yc`](yc-create-precompiled-header-file.md) | Writes a precompiled header file. | -## Diagnostic Messages +## Diagnostic messages -If you specify an option or language feature that is incompatible with the **/MP** option, you will receive a diagnostic message. The following table lists the messages and the behavior of the compiler: +If you specify an option or language feature that is incompatible with the **`/MP`** option, you'll receive a diagnostic message. The following table lists the messages and the behavior of the compiler: -|Diagnostic Message|Description|Compiler Behavior| -|------------------------|-----------------|-----------------------| -|**C2813**|The **#import** directive is not compatible with the **/MP** option.|The compilation ends unless a [compiler warning level](compiler-option-warning-level.md) option specifies otherwise.| -|**D9014**|An invalid value is specified for the *processMax* argument.|The compiler ignores the invalid value and assumes a value of 1.| -|**D9030**|The specified option is incompatible with **/MP**.|The compiler ignores the **/MP** option.| +| Diagnostic Message | Description | Compiler Behavior | +|--|--|--| +| **C2813** | The **`#import`** directive isn't compatible with the **`/MP`** option. | The compilation ends unless a [compiler warning level](compiler-option-warning-level.md) option specifies otherwise. | +| **D9014** | An invalid value is specified for the *`processMax`* argument. | The compiler ignores the invalid value and assumes a value of 1. | +| **D9030** | The specified option is incompatible with **`/MP`**. | The compiler ignores the **`/MP`** option. | ## Guidelines -### Measure Performance +### Measure performance Use total build time to measure performance. You can measure the build time with a physical clock, or you can use software that calculates the difference between when the build starts and stops. If your computer has multiple processors, a physical clock might yield more accurate results than a software time measurement. -### Effective Processors +### Effective processors A computer can have one or more virtual processors, which are also known as *effective processors*, for each of its physical processors. Each physical processor can have one or more cores, and if the operating system enables hyperthreading for a core, each core appears to be two virtual processors. For example, a computer has one effective processor if it has one physical processor that has one core, and hyperthreading is disabled. In contrast, a computer has eight effective processors if it has two physical processors, each of which has two cores, and all the cores have hyperthreading enabled. That is, (8 effective processors) = (2 physical processors) x (2 cores per physical processor) x (2 effective processors per core because of hyperthreading). -If you omit the *processMax* argument in the **/MP** option, the compiler obtains the number of effective processors from the operating system, and then creates one process per effective processor. However, the compiler cannot guarantee which process executes on a particular processor; the operating system makes that decision. +If you omit the *`processMax`* argument in the **`/MP`** option, the compiler obtains the number of effective processors from the operating system, and then creates one process per effective processor. However, the compiler can't guarantee which process executes on a particular processor; the operating system makes that decision. -### Number of Processes +### Number of processes -The compiler calculates the number of processes that it will use to compile the source files. That value is the lesser of the number of source files that you specify on the command line, and the number of processes that you explicitly or implicitly specify with the **/MP** option. You can explicitly set the maximum number of processes if you provide the *processMax* argument of the **/MP** option. Or you can use the default, which is equal to the number of effective processors in a computer, if you omit the *processMax* argument. +The compiler calculates the number of processes that it will use to compile the source files. That value is the lesser of the number of source files that you specify on the command line, and the number of processes that you explicitly or implicitly specify with the **`/MP`** option. You can explicitly set the maximum number of processes if you provide the *`processMax`* argument of the **`/MP`** option. Or you can use the default, which is equal to the number of effective processors in a computer, if you omit the *`processMax`* argument. For example, suppose you specify the following command line: `cl /MP7 a.cpp b.cpp c.cpp d.cpp e.cpp` -In this case the compiler uses five processes because that is the lesser of five source files and a maximum of seven processes. Alternatively, suppose your computer has two effective processors and you specify the following command line: +In this case, the compiler uses five processes because that is the lesser of five source files and a maximum of seven processes. Alternatively, suppose your computer has two effective processors and you specify the following command line: `cl /MP a.cpp b.cpp c.cpp` -In this case the operating system reports two processors; therefore, the compiler uses two processes in its calculation. As a result, the compiler will execute the build with two processes because that is the lesser of two processes and three source files. +In this case, the operating system reports two processors, so the compiler uses two processes in its calculation. As a result, the compiler uses two processes to execute the build because that's the lesser of two processes and three source files. -### Source Files and Build Order +### Source files and build order -The source files might not be compiled in the same order in which they appear on the command line. Although the compiler creates a set of processes that contain copies of the compiler, the operating system schedules when each process executes. Consequently, you cannot guarantee that the source files will be compiled in a particular order. +The source files might not be compiled in the same order in which they appear on the command line. Although the compiler creates a set of processes that contain copies of the compiler, the operating system schedules when each process executes. The **`/MP`** option can't guarantee that the source files will be compiled in a particular order. A source file is compiled when a process is available to compile it. If there are more files than processes, the first set of files is compiled by the available processes. The remaining files are processed when a process finishes handling a previous file and is available to work on one of the remaining files. -Do not specify the same source file multiple times on a command line. This might occur, for example, if a tool automatically creates a [makefile](contents-of-a-makefile.md) that is based on dependency information in a project. If you do not specify the **/MP** option, the compiler processes the list of files sequentially and recompiles each occurrence of the file. However, if you specify the **/MP** option, different compilers might compile the same file at the same time. Consequently, the different compilers will try to write to the same output file at the same time. One compiler will acquire exclusive write access to the output file and succeed, and the other compilers will fail with a file access error. +Don't specify the same source file multiple times on a command line. Multiple specifications could occur, for example, if a tool automatically creates a [makefile](contents-of-a-makefile.md) that's based on dependency information in a project. If you don't specify the **`/MP`** option, the compiler processes the list of files sequentially and recompiles each occurrence of the file. However, if you specify the **`/MP`** option, different compiler instances might compile the same file at the same time. The different instances may try to write to the same output file at the same time. One compiler instance acquires exclusive write access to the output file and succeed, and the other compiler instances fail with a file access error. -### Using Type Libraries (#import) +### Using type libraries (`#import`) -The compiler does not support the use of the [#import](../../preprocessor/hash-import-directive-cpp.md) directive with the **/MP** switch. If possible, follow these steps to work around this problem: +The compiler doesn't support the use of the [`#import`](../../preprocessor/hash-import-directive-cpp.md) directive with the **`/MP`** switch. If possible, follow these steps to work around this problem: -- Move all the `#import` directives in your various source files to one or more files, and then compile those files without the **/MP** option. The result is a set of generated header files. +- Move all the `#import` directives in your various source files to one or more files, and then compile those files without the **`/MP`** option. The result is a set of generated header files. -- In your remaining source files, insert [#include](../../preprocessor/hash-include-directive-c-cpp.md) directives that specify the generated headers, and then compile your remaining source files by using the **/MP** option. +- In your remaining source files, insert [`#include`](../../preprocessor/hash-include-directive-c-cpp.md) directives that specify the generated headers, and then compile your remaining source files by using the **`/MP`** option. -### Visual Studio Project Settings +### Visual Studio Project settings -#### The MSBUILD.exe Tool +#### The MSBuild tool -Visual Studio uses the [MSBuild.exe](/visualstudio/msbuild/msbuild-reference) tool to build solutions and projects. The **/maxcpucount:**_number_ (or **/m:**_number_) command-line option of the MSBuild.exe tool can build multiple projects at the same time. And the **/MP** compiler option can build multiple compilation units at the same time. If it is appropriate for your application, improve your solution's build time by using either or both **/MP** and **/maxcpucount**. +Visual Studio uses the [`MSBuild`](/visualstudio/msbuild/msbuild-reference) tool (`msbuild.exe`) to build solutions and projects. The **`/maxcpucount:number`** (or **`/m:number`**) command-line option of the MSBuild tool can build multiple projects at the same time. And the **`/MP`** compiler option can build multiple compilation units at the same time. If it's appropriate for your application, improve your solution's build time by using either or both **`/MP`** and **`/maxcpucount`**. -The build time of your solution partly depends on the number of processes that perform the build. The *number* argument of the [/maxcpucount](/visualstudio/msbuild/msbuild-command-line-reference) MSBuild option specifies the maximum number of projects to build at the same time. Similarly, the *processMax* argument of the **/MP** compiler option specifies the maximum number of compilation units to build at the same time. If the **/maxcpucount** option specifies *P* projects and the **/MP** option specifies *C* processes, a maximum of *P* x *C* processes execute at the same time. +The build time of your solution partly depends on the number of processes that perform the build. The *`number`* argument of the [`/maxcpucount`](/visualstudio/msbuild/msbuild-command-line-reference) MSBuild option specifies the maximum number of projects to build at the same time. Similarly, the *`processMax`* argument of the **`/MP`** compiler option specifies the maximum number of compilation units to build at the same time. If the **`/maxcpucount`** option specifies *P* projects and the **`/MP`** option specifies *C* processes, a maximum of *P* x *C* processes execute at the same time. -The guideline for deciding whether to use MSBuild or **/MP** technology is as follows: +The guideline for deciding whether to use MSBuild or **`/MP`** technology is as follows: -- If there are many projects with few files in each project, use the MSBuild tool. +- If there are many projects with few files in each project, use the MSBuild tool with the **`/maxcpucount`** option. -- If there are few projects with many files in each project, use the **/MP** option. +- If there are few projects with many files in each project, use the **`/MP`** option. -- If the number of projects and files per project is balanced, use both MSBuild and **/MP**. Initially set the **/maxcpucount** option to the number of projects to build and the **/MP** option to the number of processors on your computer. Measure performance and then adjust your settings to yield the best results. Repeat that cycle until you are satisfied with the total build time. +- If the number of projects and files per project is balanced, use both MSBuild and **`/MP`**. Initially set the **`/maxcpucount`** option to the number of projects to build and the **`/MP`** option to the number of processors on your computer. Measure performance and then adjust your settings to yield the best results. Repeat that cycle until you're satisfied with the total build time. ## See also -[#import Directive](../../preprocessor/hash-import-directive-cpp.md)
-[Command-Line Reference](/visualstudio/msbuild/msbuild-command-line-reference)
-[/Zf (Faster PDB generation)](zf.md)
+[`#import` directive](../../preprocessor/hash-import-directive-cpp.md)\ +[MSBuild command-line reference](/visualstudio/msbuild/msbuild-command-line-reference)\ +[`/Zf` (Faster PDB generation)](zf.md) diff --git a/docs/build/reference/msbuild-reference-cpp.md b/docs/build/reference/msbuild-reference-cpp.md index e779a699b2..bbc889a922 100644 --- a/docs/build/reference/msbuild-reference-cpp.md +++ b/docs/build/reference/msbuild-reference-cpp.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: MSBuild reference for C++ projects" title: "MSBuild reference for C++ projects in Visual Studio" -ms.date: "12/08/2018" +description: "Learn more about: MSBuild reference for C++ projects" +ms.date: 12/08/2018 helpviewer_keywords: ["MSBuild reference [C++]"] --- # MSBuild reference for C++ projects @@ -12,25 +12,25 @@ If for some reason you wish to use MSBuild directly from the command line, see [ ## In this section -[MSBuild internals for C++ projects](msbuild-visual-cpp-overview.md)
+[MSBuild internals for C++ projects](msbuild-visual-cpp-overview.md)\ Information about how properties and targets are stored and consumed. -[Common macros for build commands and properties](common-macros-for-build-commands-and-properties.md)
+[Common macros for build commands and properties](common-macros-for-build-commands-and-properties.md)\ Describes macros (compile-time constants) that can be used to define properties such as paths and product versions. -[File types created for C++ projects](file-types-created-for-visual-cpp-projects.md)
+[File types created for C++ projects](file-types-created-for-visual-cpp-projects.md)\ Describes the various kinds of files that Visual Studio creates for different project types. -[Visual Studio C++ project templates](visual-cpp-project-types.md)
+[Visual Studio C++ project templates](visual-cpp-project-types.md)\ Describes the MSBuild-based project types that are available for C++. -[C++ new item templates](using-visual-cpp-add-new-item-templates.md)
+[C++ new item templates](using-visual-cpp-add-new-item-templates.md)\ Describes source files and other items you can add to a Visual Studio project. -[Precompiled header files](../creating-precompiled-header-files.md) +[Precompiled header files](../creating-precompiled-header-files.md)\ How to use precompiled header files and how to create your own custom precompiled code to speed up build times. -[Visual Studio project property reference](property-pages-visual-cpp.md)
+[Visual Studio project property reference](property-pages-visual-cpp.md)\ Reference documentation for project properties that are set in the Visual Studio IDE. ## See also diff --git a/docs/build/reference/msbuild-visual-cpp-overview.md b/docs/build/reference/msbuild-visual-cpp-overview.md index 85b0314b00..e614f2f98a 100644 --- a/docs/build/reference/msbuild-visual-cpp-overview.md +++ b/docs/build/reference/msbuild-visual-cpp-overview.md @@ -1,7 +1,7 @@ --- title: "MSBuild internals for C++ projects in Visual Studio" description: "The support files, properties, and targets used by MSBuild for Visual Studio C++ projects." -ms.date: 10/14/2020 +ms.date: 02/10/2022 helpviewer_keywords: ["MSBuild overview"] --- # MSBuild internals for C++ projects @@ -16,11 +16,11 @@ By default, the primary Visual Studio support files are located in the following ::: moniker range=">=msvc-160" -### Visual Studio 2019 +### Visual Studio 2022 and 2019 - *`%VSINSTALLDIR%MSBuild\Microsoft\VC\\`* - Contains the primary target files (.targets) and property files (.props) that are used by the targets. By default, the $(VCTargetsPath) macro references this directory. The *``* placeholder refers to the Visual Studio version: v160 for Visual Studio 2019, v150 for Visual Studio 2017. + Contains the primary target files (*`.targets`*) and property files (*`.props`*) that are used by the targets. By default, the `$(VCTargetsPath)` macro references this directory. The *``* placeholder refers to the Visual Studio version: v170 for Visual Studio 2022, v160 for Visual Studio 2019, or v150 for Visual Studio 2017. - *`%VSINSTALLDIR%MSBuild\Microsoft\VC\\Platforms\\`* @@ -52,19 +52,19 @@ By default, the primary Visual Studio support files are located in the following ### Visual Studio 2015 and earlier -- *`:\Program Files (x86)\MSBuild\Microsoft.Cpp\v4.0\\`* +- *`:\Program Files[ (x86)]\MSBuild\Microsoft.Cpp\v4.0\\`* - Contains the primary target files (.targets) and property files (.props) that are used by the targets. By default, the $(VCTargetsPath) macro references this directory. + Contains the primary target files (*`.targets`*) and property files (*`.props`*) that are used by the targets. By default, the $(VCTargetsPath) macro references this directory. -- *`:\Program Files (x86)\MSBuild\Microsoft.Cpp\v4.0\\Platforms\\`* +- *`:\Program Files[ (x86)]\MSBuild\Microsoft.Cpp\v4.0\\Platforms\\`* Contains platform-specific target and property files that override targets and properties in its parent directory. This directory also contains a DLL that defines the tasks that are used by the targets in this directory. The *``* placeholder represents the ARM, Win32, or x64 subdirectory. -- *`:\Program Files (x86)\MSBuild\Microsoft.Cpp\v4.0\\Platforms\\PlatformToolsets\\`* +- *`:\Program Files[ (x86)]\MSBuild\Microsoft.Cpp\v4.0\\Platforms\\PlatformToolsets\\`* Contains the directories that enable the build to generate C++ applications by using the specified *``*. The *``* placeholder is V110 for Visual Studio 2012, V120 for Visual Studio 2013, and V140 for Visual Studio 2015. The *``* placeholder represents the ARM, Win32, or x64 subdirectory. The *``* placeholder represents the toolset subdirectory. For example, it's v140 for building Windows apps by using the Visual Studio 2015 toolset. Or, v120_xp to build for Windows XP using the Visual Studio 2013 toolset. -- *`:\Program Files (x86)\MSBuild\Microsoft.Cpp\v4.0\Platforms\\PlatformToolsets\\`* +- *`:\Program Files[ (x86)]\MSBuild\Microsoft.Cpp\v4.0\Platforms\\PlatformToolsets\\`* The paths that enable the build to generate either Visual Studio 2008 or Visual Studio 2010 applications don't include the *``*. In those versions, the *``* placeholder represents the Itanium, Win32, or x64 subdirectory. The *``* placeholder represents the v90 or v100 toolset subdirectory. @@ -74,13 +74,13 @@ The support file directories contain files with these extensions: | Extension | Description | | --------- | ----------- | -| *`.targets`* | Contains `Target` XML elements that specify the tasks that are executed by the target. May also contain `PropertyGroup`, `ItemGroup`, `ItemDefinitionGroup`, and user-defined `Item` elements that are used to assign files and command-line options to task parameters.

For more information, see [Target Element (MSBuild)](/visualstudio/msbuild/target-element-msbuild). | -| *`.props`* | Contains `Property Group` and user-defined `Property` XML elements that specify file and parameter settings that are used during a build.

May also contain `ItemDefinitionGroup` and user-defined `Item` XML elements that specify additional settings. Items defined in an item definition group resemble properties, but can't be accessed from the command line. Visual Studio project files frequently use items instead of properties to represent settings.

For more information, see [ItemGroup Element (MSBuild)](/visualstudio/msbuild/itemgroup-element-msbuild), [ItemDefinitionGroup Element (MSBuild)](/visualstudio/msbuild/itemdefinitiongroup-element-msbuild), and [Item Element (MSBuild)](/visualstudio/msbuild/item-element-msbuild). | +| *`.targets`* | Contains `Target` XML elements that specify the tasks that are executed by the target. May also contain `PropertyGroup`, `ItemGroup`, `ItemDefinitionGroup`, and user-defined `Item` elements that are used to assign files and command-line options to task parameters.

For more information, see [`Target` Element (MSBuild)](/visualstudio/msbuild/target-element-msbuild). | +| *`.props`* | Contains `Property Group` and user-defined `Property` XML elements that specify file and parameter settings that are used during a build.

May also contain `ItemDefinitionGroup` and user-defined `Item` XML elements that specify additional settings. Items defined in an item definition group resemble properties, but can't be accessed from the command line. Visual Studio project files frequently use items instead of properties to represent settings.

For more information, see [`ItemGroup` Element (MSBuild)](/visualstudio/msbuild/itemgroup-element-msbuild), [`ItemDefinitionGroup` Element (MSBuild)](/visualstudio/msbuild/itemdefinitiongroup-element-msbuild), and [`Item` Element (MSBuild)](/visualstudio/msbuild/item-element-msbuild). | | *`.xml`* | Contains XML elements that declare and initialize IDE user interface elements. For example, property sheets, property pages, textbox controls, and listbox controls.

The *`.xml`* files directly support the IDE, not MSBuild. However, the values of IDE properties are assigned to build properties and items.

Most *`.xml`* files are in a locale-specific subdirectory. For example, files for the English-US region are in `$(VCTargetsPath)\1033\`. | ## User targets and properties -To use MSBuild effectively, it helps to know which properties and targets are useful and relevant. Most properties and targets help implement the Visual Studio build system, and consequently aren't relevant to the user. This section describes user-oriented properties and targets worth knowing about. +To use MSBuild effectively, it helps to know which properties and targets are useful and relevant. Most properties and targets help implement the Visual Studio build system, and aren't relevant to the user. This section describes user-oriented properties and targets worth knowing about. ### `PlatformToolset` property @@ -100,7 +100,7 @@ For example, set the `PreferredToolArchitecture` property to `x64` to use the 64 ### `UseEnv` property -By default, the platform-specific settings for the current project override the PATH, INCLUDE, LIB, LIBPATH, CONFIGURATION, and PLATFORM environment variables. Set the `UseEnv` property to **`true`** to guarantee that the environment variables don't get overridden. +By default, the platform-specific settings for the current project override the `PATH`, `INCLUDE`, `LIB`, `LIBPATH`, `CONFIGURATION`, and `PLATFORM` environment variables. Set the `UseEnv` property to **`true`** to guarantee that the environment variables don't get overridden. > `msbuild myProject.vcxproj /p:UseEnv=true` @@ -112,33 +112,33 @@ The following table lists several useful user-oriented targets. | Target | Description | | ------ | ----------- | -| BscMake | Executes the Microsoft Browse Information Maintenance Utility tool, bscmake.exe. | -| Build | Builds the project.

This target is the default for a project. | -| ClCompile | Executes the MSVC compiler tool, cl.exe. | -| Clean | Deletes temporary and intermediate build files. | -| Lib | Executes the Microsoft 32-Bit Library Manager tool, lib.exe. | -| Link | Executes the MSVC linker tool, link.exe. | -| ManifestResourceCompile | Extracts a list of resources from a manifest and then executes the Microsoft Windows Resource Compiler tool, rc.exe. | -| Midl | Executes the Microsoft Interface Definition Language (MIDL) compiler tool, midl.exe. | -| Rebuild | Cleans and then builds your project. | -| ResourceCompile | Executes the Microsoft Windows Resource Compiler tool, rc.exe. | -| XdcMake | Executes the XML Documentation tool, xdcmake.exe. | -| Xsd | Executes the XML Schema Definition tool, xsd.exe. *See note.* | +| `BscMake` | Executes the Microsoft Browse Information Maintenance Utility tool, *`bscmake.exe`*. | +| `Build` | Builds the project.

This target is the default for a project. | +| `ClCompile` | Executes the MSVC compiler tool, *`cl.exe`*. | +| `Clean` | Deletes temporary and intermediate build files. | +| `Lib` | Executes the Microsoft 32-Bit Library Manager tool, *`lib.exe`*. | +| `Link` | Executes the MSVC linker tool, *`link.exe`*. | +| `ManifestResourceCompile` | Extracts a list of resources from a manifest and then executes the Microsoft Windows Resource Compiler tool, *`rc.exe`*. | +| `Midl` | Executes the Microsoft Interface Definition Language (MIDL) compiler tool, *`midl.exe`*. | +| `Rebuild` | Cleans and then builds your project. | +| `ResourceCompile` | Executes the Microsoft Windows Resource Compiler tool, *`rc.exe`*. | +| `XdcMake` | Executes the XML Documentation tool, *`xdcmake.exe`*. | +| `Xsd` | Executes the XML Schema Definition tool, *`xsd.exe`*. *See note.* | > [!NOTE] -> In Visual Studio 2017 and later, C++ project support for **xsd** files is deprecated. You can still use **Microsoft.VisualC.CppCodeProvider** by adding **CppCodeProvider.dll** manually to the GAC. +> In Visual Studio 2017 and later, C++ project support for *`.xsd`* files is deprecated. You can still use `Microsoft.VisualC.CppCodeProvider` by adding *`CppCodeProvider.dll`* manually to the GAC. ## See also -[MSBuild Task Reference](/visualstudio/msbuild/msbuild-task-reference)\ -[BscMake Task](/visualstudio/msbuild/bscmake-task)\ -[CL Task](/visualstudio/msbuild/cl-task)\ -[CPPClean Task](/visualstudio/msbuild/cppclean-task)\ -[LIB Task](/visualstudio/msbuild/lib-task)\ -[Link Task](/visualstudio/msbuild/link-task)\ -[MIDL Task](/visualstudio/msbuild/midl-task)\ -[MT Task](/visualstudio/msbuild/mt-task)\ -[RC Task](/visualstudio/msbuild/rc-task)\ -[SetEnv Task](/visualstudio/msbuild/setenv-task)\ -[VCMessage Task](/visualstudio/msbuild/vcmessage-task)\ -[XDCMake Task](/visualstudio/msbuild/xdcmake-task) +[MSBuild task reference](/visualstudio/msbuild/msbuild-task-reference)\ +[`BscMake` task](/visualstudio/msbuild/bscmake-task)\ +[`CL` task](/visualstudio/msbuild/cl-task)\ +[`CPPClean` task](/visualstudio/msbuild/cppclean-task)\ +[`LIB` task](/visualstudio/msbuild/lib-task)\ +[`Link` task](/visualstudio/msbuild/link-task)\ +[`MIDL` task](/visualstudio/msbuild/midl-task)\ +[`MT` task](/visualstudio/msbuild/mt-task)\ +[`RC` task](/visualstudio/msbuild/rc-task)\ +[`SetEnv` task](/visualstudio/msbuild/setenv-task)\ +[`VCMessage` task](/visualstudio/msbuild/vcmessage-task)\ +[`XDCMake` task](/visualstudio/msbuild/xdcmake-task) diff --git a/docs/build/reference/multiple-inline-files.md b/docs/build/reference/multiple-inline-files.md deleted file mode 100644 index d58b5d77a1..0000000000 --- a/docs/build/reference/multiple-inline-files.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -description: "Learn more about: Multiple Inline Files" -title: "Multiple Inline Files" -ms.date: "11/04/2016" -helpviewer_keywords: ["inline files, multiple NMAKE", "multiple inline files", "NMAKE program, inline files"] -ms.assetid: 6d381dcf-0ed8-45d1-8df3-b4598d860b99 ---- -# Multiple Inline Files - -A command can create more than one inline file. - -## Syntax - -``` -command << << -inlinetext -<<[KEEP | NOKEEP] -inlinetext -<<[KEEP | NOKEEP] -``` - -## Remarks - -For each file, specify one or more lines of inline text followed by a closing line containing the delimiter. Begin the second file's text on the line following the delimiting line for the first file. - -## See also - -[Inline Files in a Makefile](inline-files-in-a-makefile.md) diff --git a/docs/build/reference/natvis-add-natvis-to-pdb.md b/docs/build/reference/natvis-add-natvis-to-pdb.md index 326072d5fa..dbc59b4eb0 100644 --- a/docs/build/reference/natvis-add-natvis-to-pdb.md +++ b/docs/build/reference/natvis-add-natvis-to-pdb.md @@ -1,39 +1,43 @@ --- description: "Learn more about: /NATVIS (Add Natvis to PDB)" title: "/NATVIS (Add Natvis to PDB)" -ms.date: "08/10/2017" -f1_keywords: ["/natvis"] +ms.date: 09/08/2022 +f1_keywords: ["/natvis", "natvis"] helpviewer_keywords: ["NATVIS linker option", "/NATVIS linker option", "-NATVIS linker option", "Add Natvis file to PDB"] ms.assetid: 8747fc0c-701a-4796-bb4d-818ab4465cca --- -# /NATVIS (Add Natvis to PDB) +# `/NATVIS` (Add Natvis to PDB) -> /NATVIS:*filename* +Specifies a debugger visualization file (a Natvis file) to embed in the PDB file generated by the linker. + +## Syntax + +> **`/NATVIS:`***`filename`* ## Parameters -*filename*
-A Natvis file to add to the PDB file. It embeds the debugger visualizations in the Natvis file into the PDB. +*`filename`*\ +The pathname for a Natvis file to add to the PDB file. It embeds the debugger visualizations in the Natvis file into the PDB. ## Remarks -The /NATVIS option embeds the debugger visualizations defined in the Natvis file *filename* into the PDB file generated by LINK. This allows the debugger to display the visualizations independently of the .natvis file. You can use multiple /NATVIS options to embed more than one Natvis file in the generated PDB file. +The **`/NATVIS`** linker option embeds the debugger visualizations defined in the Natvis file *`filename`* into the PDB file generated by LINK. A Natvis file has a *`.natvis`* extension. Embedding the information allows the debugger to display the visualizations independently of the Natvis file. You can use multiple **`/NATVIS`** options to embed more than one Natvis file in the generated PDB file. For more information on how to create and use Natvis files, see [Create custom views of native objects in the Visual Studio debugger](/visualstudio/debugger/create-custom-views-of-native-objects). -LINK ignores /NATVIS when a PDB file is not created by using a [/DEBUG](debug-generate-debug-info.md) option. For information on creation and use of .natvis files, see [Create custom views of native objects in the Visual Studio debugger](/visualstudio/debugger/create-custom-views-of-native-objects). +LINK ignores **`/NATVIS`** when a PDB file isn't created by using a [`/DEBUG`](debug-generate-debug-info.md) option. ### To set this linker option in the Visual Studio development environment -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. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. -1. Add the *`/NATVIS`* option to the **Additional Options** text box. +1. Add the *`/NATVIS`* option to the **Additional Options** text box. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically -- This option does not have a programmatic equivalent. +- See . ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/netmodule-files-as-linker-input.md b/docs/build/reference/netmodule-files-as-linker-input.md index b37ff928f0..5bd54dc8df 100644 --- a/docs/build/reference/netmodule-files-as-linker-input.md +++ b/docs/build/reference/netmodule-files-as-linker-input.md @@ -16,7 +16,7 @@ link.exe accepts MSIL *`.obj`* and *`.netmodule`* files as input. The output fil The linker must be passed the *`.obj`* file from the C++ compilation that created the *`.netmodule`*. Passing in a *`.netmodule`* is no longer supported because the **/clr:pure** and **/clr:safe** compiler options are deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017 and later. -For information on how to invoke the linker from the command line, see [Linker command-line syntax](linking.md), [Use the MSVC toolset from the command line](../building-on-the-command-line.md), and [Set the path and environment variables for command-line builds](../setting-the-path-and-environment-variables-for-command-line-builds.md). +For information on how to invoke the linker from the command line, see [Linker command-line syntax](linking.md) and [Use the MSVC toolset from the command line](../building-on-the-command-line.md). Passing a *`.netmodule`* or *`.dll`* file to the linker that was compiled by the MSVC compiler with **/clr** can result in a linker error. For more information, see [Choosing the format of .netmodule input files](choosing-the-format-of-netmodule-input-files.md). diff --git a/docs/build/reference/nmake-function-abspath.md b/docs/build/reference/nmake-function-abspath.md new file mode 100644 index 0000000000..49297c7264 --- /dev/null +++ b/docs/build/reference/nmake-function-abspath.md @@ -0,0 +1,46 @@ +--- +description: "Learn more about: abspath NMAKE function" +title: "abspath NMAKE function" +ms.date: "9/30/2021" +helpviewer_keywords: ["abspath NMAKE function", "NMAKE function, abspath"] +monikerRange: '>=msvc-170' +--- +# `abspath` NMAKE function + +Gets the absolute path for each item in a list. + +## Syntax + +```makefile +$(abspath input) +``` + +### Parameters + +*`input`*\ +The [list](using-an-nmake-macro.md#function-list-syntax) of file paths to convert. + +## Return value + +A [list](using-an-nmake-macro.md#function-list-syntax) with each of the items from *`input`* converted to their absolute form. + +## Remarks + +`abspath` supports extended-length paths, either by using the `\\?\` prefix, or when long paths are enabled. For more information about long paths, see [Maximum Path Length Limitation](/windows/win32/fileio/maximum-file-path-limitation). + +This macro function is available starting in Visual Studio 2022 version 17.1, in NMAKE version 14.31 or later. + +## Example + +```makefile +$(abspath relative\path\file.c) # If run from "c:\temp", evaluates to "c:\temp\relative\path\file.c" +$(abspath c:\temp\..\file1.cpp c:\\temp\/dir//) # Evaluates to "c:\file1.cpp c:\temp\dir\". Follows path traversals and normalizes directory separators. + +# abspath can be combined with filter to find which items exist within a directory tree +TEMP_SOURCES=$(filteri c:\temp\\%,$(abspath $(SOURCES))) +``` + +## See also + +[Macros and NMAKE](macros-and-nmake.md)\ +[NMAKE functions by category](using-an-nmake-macro.md#functions-by-category) diff --git a/docs/build/reference/nmake-function-basename.md b/docs/build/reference/nmake-function-basename.md new file mode 100644 index 0000000000..c72a40b563 --- /dev/null +++ b/docs/build/reference/nmake-function-basename.md @@ -0,0 +1,46 @@ +--- +description: "Learn more about: basename NMAKE function" +title: "basename NMAKE function" +ms.date: "9/30/2021" +helpviewer_keywords: ["basename NMAKE function", "NMAKE function, basename"] +monikerRange: '>=msvc-170' +--- +# `basename` NMAKE function + +Gets the base name for each item in a list. + +## Syntax + +```makefile +$(basename input) +``` + +### Parameters + +*`input`*\ +The [list](using-an-nmake-macro.md#function-list-syntax) of file paths to convert. + +## Return value + +A [list](using-an-nmake-macro.md#function-list-syntax) with each of the items from *`input`* converted to their base name (that is, with their extensions removed). + +## Remarks + +`basename` doesn't have any maximum path limitations. + +The `basename` function is equivalent to using the [`R` modifier in a filename macro](special-nmake-macros.md#filename-macros). + +This macro function is available starting in Visual Studio 2022 version 17.1, in NMAKE version 14.31 or later. + +## Example + +```makefile +$(basename c:\temp\file.txt) # Evaluates to "c:\temp\file" +$(basename c:\temp\ c:\file) # Evaluates to "c:\temp\ c:\file" - Directories and files without extensions are left as-is +$(basename c:\src\.gitignore) # Evaluates to "c:\src\" - Dot files are considered to be extensions and so are removed +``` + +## See also + +[Macros and NMAKE](macros-and-nmake.md)\ +[NMAKE functions by category](using-an-nmake-macro.md#functions-by-category) diff --git a/docs/build/reference/nmake-function-filter.md b/docs/build/reference/nmake-function-filter.md new file mode 100644 index 0000000000..1dd25e3aaf --- /dev/null +++ b/docs/build/reference/nmake-function-filter.md @@ -0,0 +1,56 @@ +--- +description: "Learn more about: filter, filteri NMAKE functions" +title: "filter, filteri NMAKE functions" +ms.date: "9/30/2021" +helpviewer_keywords: ["filter NMAKE function", "filteri NMAKE function", "NMAKE function, filter", "NMAKE function, filteri"] +monikerRange: '>=msvc-170' +--- +# `filter`, `filteri` NMAKE functions + +Evaluates to a list of items that matched at least one pattern. + +## Syntax + +```makefile +$(filter filters,input) +$(filteri filters,input) +``` + +### Parameters + +*`filters`*\ +A [list](using-an-nmake-macro.md#function-list-syntax) of one or more [patterns](using-an-nmake-macro.md#function-pattern-syntax) to filter by. + +*`input`*\ +The [list](using-an-nmake-macro.md#function-list-syntax) to be filtered. + +## Return value + +A list of all of the items in *`input`* that match at least one pattern in *`filters`*. + +## Remarks + +`filteri` is the case-insensitive version of `filter`. + +This macro function is available starting in Visual Studio 2022, in NMAKE version 14.30 or later. + +## Example + +```makefile +$(filter He%,Hello Hey Hi) # Evaluates to "Hello Hey" - "Hi" doesn't match the filter +$(filter %y %i,Hello Hey Hi) # Evaluates to "Hey Hi" - items are kept if they match any filter, "Hello" is dropped as it doesn't match any +$(filter Not%Found,Hello Hey Hi) # Evaluates to "" - none of the items match any filters + +$(filter he%,Hello Hey Hi) # Evaluates to "" - filter is case-sensitive +$(filteri he%,Hello Hey Hi) # Evaluates to "Hello Hey" - filteri is case-insensitive + +# filteri is commonly used to filter a list of files by their extensions +CPP_SOURCES=$(filteri %.cpp %.cxx,$(SOURCES)) +C_SOURCES=$(filteri %.c,$(SOURCES)) +``` + +## See also + +[Macros and NMAKE](macros-and-nmake.md)\ +[NMAKE functions by category](using-an-nmake-macro.md#functions-by-category)\ +[`filterout`, `filterouti`](nmake-function-filterout.md) diff --git a/docs/build/reference/nmake-function-filterout.md b/docs/build/reference/nmake-function-filterout.md new file mode 100644 index 0000000000..930c08280b --- /dev/null +++ b/docs/build/reference/nmake-function-filterout.md @@ -0,0 +1,52 @@ +--- +description: "Learn more about: filterout, filterouti NMAKE functions" +title: "filterout, filterouti NMAKE functions" +ms.date: "9/30/2021" +helpviewer_keywords: ["filterout NMAKE function", "filterouti NMAKE function", "NMAKE function, filterout", "NMAKE function, filterouti"] +monikerRange: '>=msvc-170' +--- +# `filterout`, `filterouti` NMAKE functions + +Evaluates to a list of items that don't match any patterns. + +## Syntax + +```makefile +$(filterout filters,input) +$(filterouti filters,input) +``` + +### Parameters + +*`filters`*\ +A [list](using-an-nmake-macro.md#function-list-syntax) of one or more [patterns](using-an-nmake-macro.md#function-pattern-syntax) to filter by. + +*`input`*\ +The [list](using-an-nmake-macro.md#function-list-syntax) to be filtered. + +## Return value + +A [list](using-an-nmake-macro.md#function-list-syntax) of all of the items in *`input`* that don't match any patterns in *`filters`*. + +## Remarks + +`filterouti` is the case-insensitive version of `filterout`. + +This macro function is available starting in Visual Studio 2022, in NMAKE version 14.30 or later. + +## Example + +```makefile +$(filterout He%,Hello Hey Hi) # Evaluates to "Hi" - "Hello" and "Hey" match the filter +$(filterout %y %i,Hello Hey Hi) # Evaluates to "Hello" - items are kept if they don't match any filters, "Hey" and "Hi" each match one filter +$(filterout H%,Hello Hey Hi) # Evaluates to "" - each of the items matched the filter + +$(filterout he%,Hello Hey Hi) # Evaluates to "Hello Hey Hi" - filterout is case-sensitive +$(filterouti he%,Hello Hey Hi) # Evaluates to "Hi" - filterouti is case-insensitive +``` + +## See also + +[Macros and NMAKE](macros-and-nmake.md)\ +[NMAKE functions by category](using-an-nmake-macro.md#functions-by-category)\ +[`filter`, `filteri`](nmake-function-filter.md) diff --git a/docs/build/reference/nmake-function-findstring.md b/docs/build/reference/nmake-function-findstring.md new file mode 100644 index 0000000000..7e08373085 --- /dev/null +++ b/docs/build/reference/nmake-function-findstring.md @@ -0,0 +1,50 @@ +--- +description: "Learn more about: findstring, findstringi NMAKE functions" +title: "findstring, findstringi NMAKE functions" +ms.date: "9/30/2021" +helpviewer_keywords: ["findstring NMAKE function", "findstringi NMAKE function", "NMAKE function, findstring", "NMAKE function, findstringi"] +monikerRange: '>=msvc-170' +--- +# `findstring`, `findstringi` NMAKE functions + +Evaluates to the searched-for string if it's found within another string. + +## Syntax + +```makefile +$(findstring searchFor,input) +$(findstringi searchFor,input) +``` + +### Parameters + +*`searchFor`*\ +The string to search for. + +*`input`*\ +The string to search in. + +## Return value + +If *`searchFor`* is found within *`input`*, then the function returns *`searchFor`*, otherwise it returns null. + +## Remarks + +`findstringi` is the case-insensitive version of `findstring`. + +This macro function is available starting in Visual Studio 2022, in NMAKE version 14.30 or later. + +## Example + +```makefile +$(findstring Hello,Hello World!) # Evaluates to "Hello" +$(findstring Hey,Hello World!) # Evaluates to "" + +$(findstring hello,Hello World!) # Evaluates to "" - findstring is case-sensitive +$(findstringi hello,Hello World!) # Evaluates to "hello" - findstringi is case-insensitive +``` + +## See also + +[Macros and NMAKE](macros-and-nmake.md)\ +[NMAKE functions by category](using-an-nmake-macro.md#functions-by-category) diff --git a/docs/build/reference/nmake-function-lowercase.md b/docs/build/reference/nmake-function-lowercase.md new file mode 100644 index 0000000000..bacd24a70b --- /dev/null +++ b/docs/build/reference/nmake-function-lowercase.md @@ -0,0 +1,40 @@ +--- +description: "Learn more about: lowercase NMAKE function" +title: "lowercase NMAKE function" +ms.date: "2/23/2022" +helpviewer_keywords: ["lowercase NMAKE function", "NMAKE function, lowercase"] +monikerRange: '>=msvc-170' +--- +# `lowercase` NMAKE function + +Evaluates to a string where all characters have been converted to their lowercase equivalent. + +## Syntax + +```makefile +$(lowercase input) +``` + +### Parameters + +*`input`*\ +The string to convert. + +## Return value + +Returns *`input`*, but all characters have been converted to their lowercase equivalent. + +## Remarks + +This macro function is available starting in Visual Studio 2022 version 17.2, in NMAKE version 14.32 or later. + +## Example + +```makefile +$(lowercase Hello World!) # Evaluates to "hello world!" +``` + +## See also + +[Macros and NMAKE](macros-and-nmake.md)\ +[NMAKE functions by category](using-an-nmake-macro.md#functions-by-category) diff --git a/docs/build/reference/nmake-function-patsubst.md b/docs/build/reference/nmake-function-patsubst.md new file mode 100644 index 0000000000..c060a65350 --- /dev/null +++ b/docs/build/reference/nmake-function-patsubst.md @@ -0,0 +1,61 @@ +--- +description: "Learn more about: patsubst, patsubsti NMAKE functions" +title: "patsubst, patsubsti NMAKE functions" +ms.date: "9/30/2021" +helpviewer_keywords: ["patsubst NMAKE function", "patsubsti NMAKE function", "NMAKE function, patsubst", "NMAKE function, patsubsti"] +monikerRange: '>=msvc-170' +--- +# `patsubst`, `patsubsti` NMAKE functions + +Evaluates to a list of items with each item that matches a pattern replaced by a substitution, and items that don't match kept as-is. + +## Syntax + +```makefile +$(patsubst pattern,replacement,input) +$(patsubsti pattern,replacement,input) +``` + +### Parameters + +*`pattern`*\ +The [pattern](using-an-nmake-macro.md#function-pattern-syntax) to search for. + +*`replacement`*\ +The [pattern](using-an-nmake-macro.md#function-pattern-syntax) to replace *`pattern`* with. If a wildcard is present in *`replacement`*, then it will be replaced with the text that the wildcard in *`pattern`* matched. + +*`input`*\ +The [list](using-an-nmake-macro.md#function-list-syntax) of items to be replaced or kept. + +## Return value + +Returns *`input`*, but each item that matches *`pattern`* is replaced by *`replacement`*. Items that don't match *`pattern`* are kept as-is. + +## Remarks + +`patsubsti` is the case-insensitive version of `patsubst`. + +This macro function is available starting in Visual Studio 2022 version 17.1, in NMAKE version 14.31 or later. + +## Example + +```makefile +$(patsubst He%,_%_,Hello Hey Hi) # Evaluates to "_llo_ _y_ Hi" +# "He" matches "Hello" and "Hey", and so "llo" and "y" are matched by the wildcard +# and used to substitute the wildcard in the replacement. "Hi" is not matched and so is kept as-is + +$(patsubst Hi,Bye,Hello Hey Hi) # Evaluates to "Hello Hey Bye" - No wildcard is required +$(patsubst %lo,Bye,Hello Hey Hi) # Evaluates to "Bye Hey Hi" +# A wildcard can be used in the pattern without a wildcard in the replacement + +$(patsubst he%,_%_,Hello Hey Hi) # Evaluates to "Hello Hey Hi" - patsubst is case-sensitive, so no substitutions performed +$(patsubsti he%,_%_,Hello Hey Hi) # Evaluates to "_llo_ _y_ Hi" - patsubsti is case-insensitive + +# patsubsti is commonly used to change the file extensions of a list of files +OBJ_FILES=$(patsubst %.c,%.obj,$(C_SOURCES)) $(patsubst %.cpp,%.obj,$(patsubst %.cxx,%.obj,$(CPP_SOURCES))) +``` + +## See also + +[Macros and NMAKE](macros-and-nmake.md)\ +[NMAKE functions by category](using-an-nmake-macro.md#functions-by-category) diff --git a/docs/build/reference/nmake-function-strip.md b/docs/build/reference/nmake-function-strip.md new file mode 100644 index 0000000000..b5ea7247dd --- /dev/null +++ b/docs/build/reference/nmake-function-strip.md @@ -0,0 +1,46 @@ +--- +description: "Learn more about: strip NMAKE function" +title: "strip NMAKE function" +ms.date: "9/30/2021" +helpviewer_keywords: ["strip NMAKE function", "NMAKE function, strip"] +monikerRange: '>=msvc-170' +--- +# `strip` NMAKE function + +Cleans up whitespace in and around a list of items. + +## Syntax + +```makefile +$(strip input) +``` + +### Parameters + +*`input`*\ +The [list](using-an-nmake-macro.md#function-list-syntax) to be cleaned. + +## Return value + +A [list](using-an-nmake-macro.md#function-list-syntax) of the exact same items as *`input`*. + +## Remarks + +NMAKE outputs a [list](using-an-nmake-macro.md#function-list-syntax) that has a single space between each item and no leading or trailing whitespace. `strip` doesn't change any item within a list, but it does ensure that the returned list is in this canonical form. The canonical form can be useful for later operations that operate on strings instead of lists. + +This macro function is available starting in Visual Studio 2022, in NMAKE version 14.30 or later. + +## Example + +```makefile +$(strip a b c d ) # Evaluates to "a b c d" + +# strip is useful to get a canonical form of a list, which can then be transformed into a different format +SINGLESPACE=$(subst ',,' ') # Use "subst" since a normal assignment trims trailing whitespace. +INCLUDE_PATH=$(subst $(SINGLESPACE),;,$(strip $(INCLUDES))) +``` + +## See also + +[Macros and NMAKE](macros-and-nmake.md)\ +[NMAKE functions by category](using-an-nmake-macro.md#functions-by-category) diff --git a/docs/build/reference/nmake-function-subst.md b/docs/build/reference/nmake-function-subst.md new file mode 100644 index 0000000000..90fb0f506d --- /dev/null +++ b/docs/build/reference/nmake-function-subst.md @@ -0,0 +1,54 @@ +--- +description: "Learn more about: subst, substi NMAKE functions" +title: "subst, substi NMAKE functions" +ms.date: "9/30/2021" +helpviewer_keywords: ["subst NMAKE function", "substi NMAKE function", "NMAKE function, subst", "NMAKE function, substi"] +monikerRange: '>=msvc-170' +--- +# `subst`, `substi` NMAKE functions + +Evaluates to a string where all instances of one string have been replaced with another. + +## Syntax + +```makefile +$(subst oldString,newString,input) +$(substi oldString,newString,input) +``` + +### Parameters + +*`oldString`*\ +The string to replace. + +*`newString`*\ +The string that replaces *`oldString`*. This argument can be null. + +*`input`*\ +The string to search. + +## Return value + +Returns *`input`*, but all instances of *`oldString`* are replaced by *`newString`*. If *`newString`* is null, then all instances of *`oldString`* are removed. + +## Remarks + +`substi` is the case-insensitive version of `subst`. + +This macro function is available starting in Visual Studio 2022, in NMAKE version 14.30 or later. + +## Example + +```makefile +$(subst Hello,Hey,Hello World!) # Evaluates to "Hey World!" +$(subst ed,ing,red ring mended) # Evaluates to "ring ring mending" +$(subst Hello ,,Hello World!) # Evaluates to "World!" + +$(subst hello,Hey,Hello World!) # Evaluates to "Hello World!" - subst is case-sensitive, so no substitution performed +$(substi hello,Hey,Hello World!) # Evaluates to "Hey World!" - substi is case-insensitive +``` + +## See also + +[Macros and NMAKE](macros-and-nmake.md)\ +[NMAKE functions by category](using-an-nmake-macro.md#functions-by-category) diff --git a/docs/build/reference/nmake-function-uppercase.md b/docs/build/reference/nmake-function-uppercase.md new file mode 100644 index 0000000000..0b0a64969e --- /dev/null +++ b/docs/build/reference/nmake-function-uppercase.md @@ -0,0 +1,40 @@ +--- +description: "Learn more about: uppercase NMAKE function" +title: "uppercase NMAKE function" +ms.date: "2/23/2022" +helpviewer_keywords: ["uppercase NMAKE function", "NMAKE function, uppercase"] +monikerRange: '>=msvc-170' +--- +# `uppercase` NMAKE function + +Evaluates to a string where all characters have been converted to their uppercase equivalent. + +## Syntax + +```makefile +$(uppercase input) +``` + +### Parameters + +*`input`*\ +The string to convert. + +## Return value + +Returns *`input`*, but all characters have been converted to their uppercase equivalent. + +## Remarks + +This macro function is available starting in Visual Studio 2022 version 17.2, in NMAKE version 14.32 or later. + +## Example + +```makefile +$(uppercase Hello World!) # Evaluates to "HELLO WORLD!" +``` + +## See also + +[Macros and NMAKE](macros-and-nmake.md)\ +[NMAKE functions by category](using-an-nmake-macro.md#functions-by-category) diff --git a/docs/build/reference/nmake-property-page.md b/docs/build/reference/nmake-property-page.md index c44c478a15..d726226b5a 100644 --- a/docs/build/reference/nmake-property-page.md +++ b/docs/build/reference/nmake-property-page.md @@ -1,6 +1,6 @@ --- description: "Learn more about: NMake Property Page" -title: "NMake Property Page (Windows C++)| Microsoft Docs" +title: NMake Property Page (Windows C++) ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCNMakeTool.ReBuildCommandLine", "VC.Project.VCNMakeTool.CleanCommandLine", "VC.Project.VCNMakeTool.Output", "VC.Project.VCNMakeTool.BuildCommandLine"] helpviewer_keywords: ["NMake property page"] @@ -8,13 +8,13 @@ ms.assetid: bd20cb52-9f1d-4240-b4fc-4f43205ac94b --- # NMake Property Page -The **NMake** property page lets you specify build settings for NMake projects. (NMAKE is the Microsoft implementation of [Make](https://wikipedia.org/wiki/Make_(software)).) +The **NMake** property page lets you specify build settings for *Makefile* projects. (NMAKE is the Microsoft implementation of [Make](https://wikipedia.org/wiki/Make_(software)).) -For more information about NMake projects, see [Creating a Makefile Project](creating-a-makefile-project.md). For non-Windows MakeFile projects, see [MakeFile Project Properties (Linux C++)](../../linux/prop-pages/makefile-linux.md), [General Project Properties (Android C++ Makefile)](/visualstudio/cross-platform/general-makefile-android-prop-page) or [NMake Properties (Android C++)](/visualstudio/cross-platform/nmake-android-prop-page). +For more information about Makefile projects, see [Creating a Makefile Project](creating-a-makefile-project.md). For non-Windows Makefile projects, see [Makefile Project Properties (Linux C++)](../../linux/prop-pages/makefile-linux.md), [General Project Properties (Android C++ Makefile)](/visualstudio/cross-platform/general-makefile-android-prop-page) or [NMake Properties (Android C++)](/visualstudio/cross-platform/nmake-android-prop-page). -The **NMake** property page contains the following properties. +The property page contains the following properties: -## UIElement List +## General - **Build Command Line** @@ -32,6 +32,8 @@ The **NMake** property page contains the following properties. Specifies the name of the file that will contain the output for the command line. By default, this file name is based on the project name. +## IntelliSense + - **Preprocessor Definitions** Specifies any preprocessor definitions that the source files use. The default value is determined by the current platform and configuration. @@ -42,11 +44,11 @@ The **NMake** property page contains the following properties. - **Forced Includes** - Specifies files that the preprocessor automatically processes even if they are not included in the project files. + Specifies files that the preprocessor automatically processes even if they aren't included in the project files. - **Assembly Search Path** - Specifies the directories where the .NET Framework searches when it trys to resolve .NET assemblies. + Specifies the directories where the .NET Framework searches when it resolves .NET assemblies. - **Forced Using Assemblies** @@ -54,9 +56,9 @@ The **NMake** property page contains the following properties. - **Additional Options** - Specifies any additional compiler switches for IntelliSense to use when it parses C++ files. + Specifies any extra compiler switches for IntelliSense to use when it parses C++ files. -For information about how to access the **NMake** property page, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +For information about how to access this property page, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). For information about how to programmatically access members of this object, see . diff --git a/docs/build/reference/nmake-reference.md b/docs/build/reference/nmake-reference.md index c6a17e9737..18d37d08a5 100644 --- a/docs/build/reference/nmake-reference.md +++ b/docs/build/reference/nmake-reference.md @@ -1,21 +1,22 @@ --- description: "Learn more about: NMAKE Reference" title: "NMAKE Reference" -ms.date: "11/04/2016" +ms.date: 09/30/2021 helpviewer_keywords: ["Microsoft program maintenance utility", "preprocessing NMAKE", "program execution [C++]", "NMAKE program"] -ms.assetid: 24fab6e3-7e43-4da4-957a-88afbbcf8661 --- # NMAKE Reference -The Microsoft Program Maintenance Utility (NMAKE.EXE) is a command-line tool included with Visual Studio that builds projects based on commands that are contained in a description file. +The Microsoft Program Maintenance Utility (NMAKE.EXE) is a command-line tool included with Visual Studio. It builds projects based on commands that are contained in a description file, usually called a *makefile*. -To use NMAKE, you must run it in a Developer Command Prompt window. A Developer Command Prompt window has the environment variables set for the tools, libraries, and include file paths required to build at the command line. For details on how to open a Developer Command Prompt window, see [Use the MSVC toolset from the command line](../building-on-the-command-line.md). +NMAKE must run in a Developer Command Prompt window. A Developer Command Prompt window has the environment variables set for the tools, libraries, and include file paths required to build at the command line. For details on how to open a Developer Command Prompt window, see [Use the MSVC toolset from the command line](../building-on-the-command-line.md). ## What do you want to know more about? [Running NMAKE](running-nmake.md) -[Contents of a Makefile](contents-of-a-makefile.md) +[Makefile contents and features](contents-of-a-makefile.md) + +[Sample Makefile](sample-makefile.md) [Description blocks](description-blocks.md) diff --git a/docs/build/reference/no-function-pad-section.md b/docs/build/reference/no-function-pad-section.md new file mode 100644 index 0000000000..a63675b5cd --- /dev/null +++ b/docs/build/reference/no-function-pad-section.md @@ -0,0 +1,43 @@ +--- +description: "Learn more about: /NOFUNCTIONPADSECTION (Disable function padding)" +title: "/NOFUNCTIONPADSECTION (Disable function padding)" +ms.date: 01/09/2024 +helpviewer_keywords: ["/NOFUNCTIONPADSECTION linker option", "-NOFUNCTIONPADSECTION linker option", "NOFUNCTIONPADSECTION linker option"] +--- +# /NOFUNCTIONPADSECTION (Disable function padding) + +Disables function padding for functions in the specified section. + +## Syntax + +``` +/NOFUNCTIONPADSECTION:[name] +``` + +## Arguments + +*name*\ +The name of the section to disable x64 function padding in. + +## Remarks + +You can instruct the linker to put a specified minimum number of bytes between functions with [`/FUNCTIONPADMIN` (Create hotpatchable image)](../reference/functionpadmin-create-hotpatchable-image.md) and [`/ARM64XFUNCTIONPADMINX64`](arm64-function-pad-min-x64.md). This flag disables adding that padding for the specified sections. + +To exclude multiple sections, specify the switch multiple times. + +This flag is available starting with in Visual Studio 17.8 and later. + +### To set this linker option in the Visual Studio development environment + +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** > **Linker** > **Command Line** property page. +1. Modify the **Additional Options** property to include **/NOFUNCTIONPADSECTION:**`name`, where `name` is the name of the section to disable x64 function padding in, and then choose **OK**. + +### To set this linker option programmatically + +- See . + +## See also + +[MSVC Linker Options](linker-options.md)\ +[MSVC linker reference](linking.md) diff --git a/docs/build/reference/nodefaultlib-ignore-libraries.md b/docs/build/reference/nodefaultlib-ignore-libraries.md index f5c94dc4a6..646e515a1e 100644 --- a/docs/build/reference/nodefaultlib-ignore-libraries.md +++ b/docs/build/reference/nodefaultlib-ignore-libraries.md @@ -1,41 +1,41 @@ --- -description: "Learn more about: /NODEFAULTLIB (Ignore Libraries)" -title: "/NODEFAULTLIB (Ignore Libraries)" -ms.date: "03/26/2019" -f1_keywords: ["VC.Project.VCLinkerTool.OVERWRITEAllDefaultLibraries", "VC.Project.VCLinkerTool.OVERWRITEDefaultLibraryNames", "/nodefaultlib"] +description: "Learn more about: /NODEFAULTLIB (Ignore libraries)" +title: "/NODEFAULTLIB (Ignore libraries)" +ms.date: 04/16/2025 +f1_keywords: ["VC.Project.VCLinkerTool.IgnoreAllDefaultLibraries", "VC.Project.VCLinkerTool.IgnoreDefaultLibraryNames", "VC.Project.VCLinkerTool.OVERWRITEAllDefaultLibraries", "VC.Project.VCLinkerTool.OVERWRITEDefaultLibraryNames", "/nodefaultlib"] helpviewer_keywords: ["default libraries, removing", "-NODEFAULTLIB linker option", "libraries, ignore", "NODEFAULTLIB linker option", "/NODEFAULTLIB linker option", "ignore libraries linker option"] -ms.assetid: 7270b673-6711-468e-97a7-c2925ac2be6e --- -# /NODEFAULTLIB (Ignore Libraries) +# `/NODEFAULTLIB` (Ignore Libraries) -> **/NODEFAULTLIB**[__:__*library*] +Unless an optional library name is provided, the `/NODEFAULTLIB` linker option removes all libraries not explicitly specified on the linker command-line. This also includes `#pragma`, `cl.exe` command-line switches, libs referenced by other libs, and so on. + +## Syntax + +> **`/NODEFAULTLIB`**\[**`:`***`library`*] ## Arguments -*library*
-A library that you want the linker to ignore when it resolves external references. +*`library`*\ +An optional library name that you want the linker to ignore when it resolves external references. ## Remarks -The /NODEFAULTLIB option tells the linker to remove one or more default libraries from the list of libraries it searches when resolving external references. - -To create an .obj file that contains no references to default libraries, use [/Zl (Omit Default Library Name)](zl-omit-default-library-name.md). +To create an *`.obj`* file that contains no references to default libraries, use [`/Zl` (Omit default library name)](zl-omit-default-library-name.md). -By default, /NODEFAULTLIB removes all default libraries from the list of libraries it searches when resolving external references. The optional *library* parameter lets you remove a specified library from the list of libraries it searches when resolving external references. Specify one /NODEFAULTLIB option for each library you want to exclude. +By default, **`/NODEFAULTLIB`** removes all default libraries from the list of libraries it searches when resolving external references. The optional *`library`* parameter lets you remove a specified library from the list of libraries it searches when resolving external references. Specify one **`/NODEFAULTLIB`** option for each library you want to exclude. -The linker resolves references to external definitions by searching first in libraries that you explicitly specify, then in default libraries specified with the [/DEFAULTLIB:](defaultlib-specify-default-library.md) option, and then in default libraries named in .obj files. +The linker resolves references to external definitions by searching first in libraries that you explicitly specify, then in default libraries specified by the [`/DEFAULTLIB`](defaultlib-specify-default-library.md) option, and then in default libraries named in *`.obj`* files. -/NODEFAULTLIB:*library* overrides /DEFAULTLIB:*library* when the same *library* name is specified in both. +**`/NODEFAULTLIB:`***`library`* overrides **`/DEFAULTLIB:`***`library`* when the same *`library`* name is specified in both. -If you use /NODEFAULTLIB to build your program without the C run-time library, you may have to also use [/ENTRY](entry-entry-point-symbol.md) to specify the entry-point function in your program. For more information, see [CRT Library Features](../../c-runtime-library/crt-library-features.md). +If you use **`/NODEFAULTLIB`** to build your program without the C run-time library, you may also have to use the [`/ENTRY`](entry-entry-point-symbol.md) option to specify the entry-point function in your program. For more information, see [CRT library features](../../c-runtime-library/crt-library-features.md). ### To set this linker option in the Visual Studio development environment -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. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **Linker** > **Input** property page. - -1. Select the **Ignore All Default Libraries** property. Or, specify a semicolon-separated list of the libraries you want to ignore in the **Ignore Specific Default Libraries** property. The **Command Line** property page shows the effect of the changes you make to these properties. +1. Modify the **Ignore All Default Libraries** property. Or, specify a semicolon-separated list of the libraries you want to ignore in the **Ignore Specific Default Libraries** property. The **Linker** > **Command Line** property page shows the effect of the changes you make to these properties. +1. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically @@ -43,5 +43,5 @@ If you use /NODEFAULTLIB to build your program without the C run-time library, y ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/null-and-undefined-macros.md b/docs/build/reference/null-and-undefined-macros.md deleted file mode 100644 index 2f1236d73e..0000000000 --- a/docs/build/reference/null-and-undefined-macros.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -description: "Learn more about: Null and Undefined Macros" -title: "Null and Undefined Macros" -ms.date: "11/04/2016" -helpviewer_keywords: ["NMAKE program, undefined macros", "Null macros in NMAKE", "macros, null and undefined", "undefined macros and NMAKE", "NMAKE program, null macros"] -ms.assetid: 1db4611a-1755-4328-b00f-d35365af8b6c ---- -# Null and Undefined Macros - -Both null and undefined macros expand to null strings, but a macro defined as a null string is considered defined in preprocessing expressions. To define a macro as a null string, specify no characters except spaces or tabs after the equal sign (=) in a command line or command file, and enclose the null string or definition in double quotation marks (" "). To undefine a macro, use **!UNDEF.** For more information, see [Makefile Preprocessing Directives](makefile-preprocessing-directives.md). - -## See also - -[Defining an NMAKE Macro](defining-an-nmake-macro.md) diff --git a/docs/build/reference/nxcompat-compatible-with-data-execution-prevention.md b/docs/build/reference/nxcompat-compatible-with-data-execution-prevention.md index c723f7ca02..b8497a078d 100644 --- a/docs/build/reference/nxcompat-compatible-with-data-execution-prevention.md +++ b/docs/build/reference/nxcompat-compatible-with-data-execution-prevention.md @@ -1,23 +1,23 @@ --- title: "/NXCOMPAT (Compatible with Data Execution Prevention)" description: "Describes the Microsoft C/C++ (MSVC) /NXCOMPAT linker option, which marks an executable as compatible with Data Execution Prevention (DEP)." -ms.date: "12/17/2019" -f1_keywords: ["/NXCOMPAT"] +ms.date: 09/19/2022 +f1_keywords: ["VC.Project.VCLinkerTool.DataExecutionPrevention", "/NXCOMPAT"] helpviewer_keywords: ["/NXCOMPAT linker option", "-NXCOMPAT linker option", "NXCOMPAT linker option"] --- -# /NXCOMPAT (Compatible with Data Execution Prevention) +# `/NXCOMPAT` (Compatible with Data Execution Prevention) Indicates that an executable is compatible with the Windows Data Execution Prevention feature. ## Syntax -> **/NXCOMPAT**[**:NO**] +> **`/NXCOMPAT`**[**`:NO`**] ## Remarks -By default, **/NXCOMPAT** is on. +By default, **`/NXCOMPAT`** is on. -**/NXCOMPAT:NO** can be used to explicitly specify an executable as incompatible with Data Execution Prevention. +**`/NXCOMPAT:NO`** can be used to explicitly specify an executable as incompatible with Data Execution Prevention. For more information about Data Execution Prevention, see these articles: @@ -27,17 +27,17 @@ For more information about Data Execution Prevention, see these articles: ### To set this linker option in Visual Studio -1. Open the project **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the **Property Pages** dialog box for the project. For more information, see [Set compiler and build properties](../working-with-project-properties.md). -1. Choose the **Configuration Properties** > **Linker** > **Command Line** property page. +1. Choose the **Configuration Properties** > **Linker** > **Advanced** property page. -1. Enter the option in the **Additional Options** box. Choose **OK** or **Apply** to apply the change. +1. Modify the **Data Execution Prevention (DEP)** property. Choose **OK** or **Apply** to apply the change. ### To set this linker option programmatically -- See . +- See . ## See also [MSVC linker reference](linking.md)\ -[MSVC Linker Options](linker-options.md) +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/og-global-optimizations.md b/docs/build/reference/og-global-optimizations.md index f1fd19d541..b098037fcc 100644 --- a/docs/build/reference/og-global-optimizations.md +++ b/docs/build/reference/og-global-optimizations.md @@ -1,7 +1,7 @@ --- title: "/Og (Global Optimizations)" description: "Describes the deprecated MSVC compiler option /Og, formerly used to enable global optimizations." -ms.date: 07/08/2020 +ms.date: 10/19/2021 f1_keywords: ["VC.Project.VCCLCompilerTool.GlobalOptimizations", "/og"] helpviewer_keywords: ["-Og compiler option [C++]", "global optimizations compiler option [C++]", "automatic register allocation", "/Og compiler option [C++]", "loop structures, optimizing", "common subexpression elimination", "Og compiler option [C++]"] ms.assetid: d10630cc-b9cf-4e97-bde3-8d7ee79e9435 @@ -34,7 +34,7 @@ The following optimizations are available under **`/Og`**: - Automatic register allocation - This optimization allows the compiler to store frequently used variables and subexpressions in registers; the **`register`** keyword is ignored. + This optimization allows the compiler to store frequently used variables and subexpressions in registers. The **`register`** keyword is ignored by default, and causes a diagnostic under **`/std:c++17`** or later. - Loop optimization @@ -62,7 +62,7 @@ The following optimizations are available under **`/Og`**: > [!NOTE] > You can enable or disable global optimization on a function-by-function basis using the `optimize` pragma together with the `g` option. -For related information, see [`/Oi` (Generate intrinsic functions)](oi-generate-intrinsic-functions.md) and [`/Ox`(Enable most speed optimizations)](ox-full-optimization.md). +For related information, see [`/Oi` (Generate intrinsic functions)](oi-generate-intrinsic-functions.md) and [`/Ox` (Enable most speed optimizations)](ox-full-optimization.md). ### To set this compiler option in the Visual Studio development environment diff --git a/docs/build/reference/oi-generate-intrinsic-functions.md b/docs/build/reference/oi-generate-intrinsic-functions.md index 7eb1b3e971..22b21114a4 100644 --- a/docs/build/reference/oi-generate-intrinsic-functions.md +++ b/docs/build/reference/oi-generate-intrinsic-functions.md @@ -4,7 +4,6 @@ title: "/Oi (Generate Intrinsic Functions)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCCLCompilerTool.EnableIntrinsicFunctions", "/oi", "VC.Project.VCCLWCECompilerTool.EnableIntrinsicFunctions"] helpviewer_keywords: ["Oi compiler option [C++]", "intrinsic functions, generate", "/Oi compiler option [C++]", "-Oi compiler option [C++]", "generate intrinsic functions compiler option [C++]"] -ms.assetid: fa4a3bf6-0ed8-481b-91c0-add7636132b4 --- # /Oi (Generate Intrinsic Functions) @@ -18,17 +17,18 @@ Replaces some function calls with intrinsic or otherwise special forms of the fu ## Remarks -Programs that use intrinsic functions are faster because they do not have the overhead of function calls, but may be larger because of the additional code created. +Programs that use intrinsic functions are faster because they don't have the overhead of function calls but may be larger because of the extra code created. -See [intrinsic](../../preprocessor/intrinsic.md) for more information on which functions have intrinsic forms. +For more information about which functions have intrinsic forms, see [intrinsic](../../preprocessor/intrinsic.md). -**/Oi** is only a request to the compiler to replace some function calls with intrinsics; the compiler may call the function (and not replace the function call with an intrinsic) if it will result in better performance. +**/Oi** is only a request to the compiler to replace some function calls with intrinsics. The compiler may call the function (and not replace the function call with an intrinsic) if it results in better performance.\ +**/Oi-** turns off this behavior, which may be useful if `/Oi` has been specified elsewhere and you want to override it. **x86 Specific** -The intrinsic floating-point functions do not perform any special checks on input values and so work in restricted ranges of input, and have different exception handling and boundary conditions than the library routines with the same name. Using the true intrinsic forms implies loss of IEEE exception handling, and loss of `_matherr` and `errno` functionality; the latter implies loss of ANSI conformance. However, the intrinsic forms can considerably speed up floating-point-intensive programs, and for many programs, the conformance issues are of little practical value. +The intrinsic floating-point functions don't perform any special checks on input values and so work in restricted ranges of input, and have different exception handling and boundary conditions than the library routines with the same name. Using the true intrinsic forms implies loss of IEEE exception handling, and loss of `_matherr` and `errno` functionality; the latter implies loss of ANSI conformance. However, the intrinsic forms can considerably speed up floating-point-intensive programs, and for many programs, the conformance issues are of little practical value. -You can use the [Za](za-ze-disable-language-extensions.md) compiler option to override generation of true intrinsic floating-point options. In this case, the functions are generated as library routines that pass arguments directly to the floating-point chip instead of pushing them onto the program stack. +You can use the [`Za`](za-ze-disable-language-extensions.md) compiler option to override generation of true intrinsic floating-point options. In this case, the functions are generated as library routines that pass arguments directly to the floating-point chip instead of pushing them onto the program stack. **END x86 Specific** @@ -37,9 +37,7 @@ You also use [intrinsic](../../preprocessor/intrinsic.md) to create intrinsic fu ### To set this compiler option in the Visual Studio development environment 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++** > **Optimization** property page. - 1. Modify the **Enable Intrinsic Functions** property. ### To set this compiler option programmatically @@ -48,7 +46,7 @@ You also use [intrinsic](../../preprocessor/intrinsic.md) to create intrinsic fu ## See also -[/O Options (Optimize Code)](o-options-optimize-code.md)
-[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md)
+[/O Options (Optimize Code)](o-options-optimize-code.md)\ +[MSVC Compiler Options](compiler-options.md)\ +[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md)\ [Compiler Intrinsics](../../intrinsics/compiler-intrinsics.md) diff --git a/docs/build/reference/openmp-enable-openmp-2-0-support.md b/docs/build/reference/openmp-enable-openmp-2-0-support.md index 388695f426..3e1687f5a2 100644 --- a/docs/build/reference/openmp-enable-openmp-2-0-support.md +++ b/docs/build/reference/openmp-enable-openmp-2-0-support.md @@ -1,7 +1,7 @@ --- description: "Learn more about: /openmp (Enable OpenMP Support)" title: "/openmp (Enable OpenMP Support)" -ms.date: 04/01/2021 +ms.date: 07/05/2023 f1_keywords: ["/openmp", "/openmp:experimental", "/openmp:llvm", "VC.Project.VCCLCompilerTool.OpenMP"] helpviewer_keywords: ["/openmp compiler option [C++]", "/openmp:experimental compiler option [C++]", "/openmp:llvm compiler option [C++]", "-openmp compiler option [C++]"] --- @@ -31,11 +31,11 @@ Causes the compiler to process [`#pragma omp`](../../preprocessor/omp.md) direct ::: moniker range=">= msvc-160" -The C++ compiler currently supports the OpenMP 2.0 standard. However, Visual Studio 2019 also now offers SIMD functionality. To use SIMD, compile by using the **`/openmp:experimental`** option. This option enables both the usual OpenMP features, and OpenMP SIMD features not available when using the **`/openmp`** switch. +The C++ compiler currently supports the OpenMP 2.0 standard. Visual Studio 2019 also now offers SIMD functionality. To use SIMD, compile using the **`/openmp:experimental`** option. This option enables both the usual OpenMP features, and OpenMP SIMD features not available when using the **`/openmp`** switch. Starting in Visual Studio 2019 version 16.9, you can use the experimental **`/openmp:llvm`** option instead of **`/openmp`** to target the LLVM OpenMP runtime. Support currently isn't available for production code, since the required libomp DLLs aren't redistributable. The option supports the same OpenMP 2.0 directives as **`/openmp`**. And, it supports all the SIMD directives supported by the **`/openmp:experimental`** option. It also supports unsigned integer indices in parallel for loops according to the OpenMP 3.0 standard. For more information, see [Improved OpenMP Support for C++ in Visual Studio](https://devblogs.microsoft.com/cppblog/improved-openmp-support-for-cpp-in-visual-studio/). -Currently, the **`/openmp:llvm`** option only works on the x64 architecture. The option isn't compatible with **`/clr`** or **`/ZW`**. +The **`/openmp:llvm`** option supports the x64 architecture. Starting with Visual Studio 2019 version 16.10, it also supports the x86 and ARM64 architectures. This option isn't compatible with **`/clr`** or **`/ZW`**. ::: moniker-end diff --git a/docs/build/reference/opt-optimizations.md b/docs/build/reference/opt-optimizations.md index 0c2494f2bf..e02850e624 100644 --- a/docs/build/reference/opt-optimizations.md +++ b/docs/build/reference/opt-optimizations.md @@ -18,7 +18,7 @@ Controls the optimizations that LINK performs during a build. ## Arguments -**REF** | **NOREF** +**REF** \| **NOREF** **/OPT:REF** eliminates functions and data that are never referenced; **/OPT:NOREF** keeps functions and data that are never referenced. @@ -30,7 +30,7 @@ By default, **/OPT:REF** is enabled by the linker unless **/OPT:NOREF** or [/DEB If [/DEBUG](debug-generate-debug-info.md) is specified, the default for **/OPT** is **NOREF**, and all functions are preserved in the image. To override this default and optimize a debug build, specify **/OPT:REF**. This can reduce the size of your executable, and can be a useful optimization even in debug builds. We recommend that you also specify **/OPT:NOICF** to preserve identical functions in debug builds. This makes it easier to read stack traces and set breakpoints in functions that would otherwise be folded together. -**ICF**\[**=**_iterations_] | **NOICF** +**ICF**\[**=**_iterations_] \| **NOICF** Use **ICF**\[**=**_iterations_] to perform identical COMDAT folding. Redundant COMDATs can be removed from the linker output. The optional *iterations* parameter specifies the number of times to traverse the symbols for duplicates. The default number of iterations is 1. Additional iterations may locate more duplicates that are uncovered through folding in the previous iteration. @@ -41,7 +41,7 @@ In a debug build, you must explicitly specify **/OPT:ICF** to enable COMDAT fold > [!NOTE] > Because **/OPT:ICF** can cause the same address to be assigned to different functions or read-only data members (that is, **`const`** variables when compiled by using **/Gy**), it can break a program that depends on unique addresses for functions or read-only data members. For more information, see [/Gy (Enable Function-Level Linking)](gy-enable-function-level-linking.md). -**LBR** | **NOLBR** +**LBR** \| **NOLBR** The **/OPT:LBR** and **/OPT:NOLBR** options apply only to ARM binaries. Because certain ARM processor branch instructions have a limited range, if the linker detects a jump to an out-of-range address, it replaces the branch instruction's destination address with the address of a code "island" that contains a branch instruction that targets the actual destination. You can use **/OPT:LBR** to optimize the detection of long branch instructions and the placement of intermediate code islands to minimize overall code size. **/OPT:NOLBR** instructs the linker to generate code islands for long branch instructions as they are encountered, without optimization. diff --git a/docs/build/reference/options-strict.md b/docs/build/reference/options-strict.md new file mode 100644 index 0000000000..5ed025a7d3 --- /dev/null +++ b/docs/build/reference/options-strict.md @@ -0,0 +1,32 @@ +--- +description: "Learn more about: /options:strict (Unrecognized compiler options are errors)" +title: "/options:strict (Unrecognized compiler options are errors)" +ms.date: 12/15/2021 +f1_keywords: ["/options:strict"] +helpviewer_keywords: ["/options:strict compiler option (C++)"] +--- +# `/options:strict` (Unrecognized compiler options are errors) + +The **`/options:strict`** compiler option tells the compiler to return an error code if a compiler option isn't recognized. + +## Syntax + +> **`/options:strict`** + +## Remarks + +The **`/options:strict`** compiler option causes the compiler driver cl.exe to exit with an error code after all command-line options are parsed if another command-line option or argument isn't recognized. The compiler emits error D8043 for any command-line option or argument that isn't recognized. + +The **`/options:strict`** option is available starting in Visual Studio 2022 version 17.0. In earlier versions of the compiler, or if **`/options:strict`** isn't specified, the compiler doesn't exit on an unrecognized option. It emits warning D9002, ignores the unrecognized option, and continues processing. + +### 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. Add **`/options:strict`** to the **Additional options:** pane. + +## See also + +[`/Zc` (Conformance)](zc-conformance.md) diff --git a/docs/build/reference/os-ot-favor-small-code-favor-fast-code.md b/docs/build/reference/os-ot-favor-small-code-favor-fast-code.md index 7d66878bd7..9325d11012 100644 --- a/docs/build/reference/os-ot-favor-small-code-favor-fast-code.md +++ b/docs/build/reference/os-ot-favor-small-code-favor-fast-code.md @@ -1,14 +1,14 @@ --- title: "/Os, /Ot (Favor Small Code, Favor Fast Code)" description: "The MSVC compiler options /Os and /Ot specify whether to favor size or speed when optimizing code." -ms.date: 07/08/2020 +ms.date: 04/18/2022 f1_keywords: ["VC.Project.VCCLWCECompilerTool.FavorSizeOrSpeed", "/os", "VC.Project.VCCLCompilerTool.FavorSizeOrSpeed"] helpviewer_keywords: ["favor fast code compiler option [C++]", "/Os compiler option [C++]", "Ot compiler option [C++]", "/Ot compiler option [C++]", "small machine code", "-Ot compiler option [C++]", "fast code", "favor small code compiler option [C++]", "Os compiler option [C++]", "-Os compiler option [C++]"] ms.assetid: 9a340806-fa15-4308-892c-355d83cac0f2 --- # `/Os`, `/Ot` (Favor Small Code, Favor Fast Code) -Minimizes or maximizes the size of EXEs and DLLs. +The **`/Os`** and **`/Ot`** compiler options specify whether to favor size (**`/Os`**) or speed (**`/Ot`**) when optimizing code. ## Syntax diff --git a/docs/build/reference/out-output-file-name.md b/docs/build/reference/out-output-file-name.md index f43bb724dc..f671586c63 100644 --- a/docs/build/reference/out-output-file-name.md +++ b/docs/build/reference/out-output-file-name.md @@ -1,29 +1,26 @@ --- description: "Learn more about: /OUT (Output File Name)" title: "/OUT (Output File Name)" -ms.date: "11/04/2016" +ms.date: 03/24/2025 f1_keywords: ["VC.Project.VCLinkerTool.OutputFile", "/out"] helpviewer_keywords: ["output files, name linker option", "-OUT linker option", "OUT linker option", "/OUT C++ linker option", "linker [C++], output files"] -ms.assetid: 976210a4-e51f-4cfb-af5e-c16344455834 --- # /OUT (Output File Name) -``` -/OUT:filename -``` +> /OUT:filename ## Arguments -*filename*
-A user-specified name for the output file. It replaces the default name. +*`filename`*\ +A user-specified name for the output file. It replaces the default name. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). ## Remarks -The /OUT option overrides the default name and location of the program that the linker creates. +The `/OUT` option overrides the default name and location of the program that the linker creates. -By default, the linker forms the file name using the base name of the first .obj file specified and the appropriate extension (.exe or .dll). +By default, the linker forms the file name using the base name of the first `.obj` file specified and the appropriate extension (`.exe` or `.dll`). -This option the default base name for a .mapfile or import library. For details, see [Generate Mapfile](map-generate-mapfile.md) (/MAP) and [/IMPLIB](implib-name-import-library.md). +This option the default base name for a `.mapfile` or import library. For details, see [Generate Mapfile](map-generate-mapfile.md) (`/MAP`) and [/IMPLIB](implib-name-import-library.md). ### To set this linker option in the Visual Studio development environment @@ -39,5 +36,5 @@ This option the default base name for a .mapfile or import library. For details, ## See also -[MSVC linker reference](linking.md)
+[MSVC linker reference](linking.md)\ [MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/para-visual-cpp.md b/docs/build/reference/para-visual-cpp.md index 52104fae8a..e9b4e2dbcb 100644 --- a/docs/build/reference/para-visual-cpp.md +++ b/docs/build/reference/para-visual-cpp.md @@ -1,34 +1,34 @@ --- -description: "Learn more about: <para>" -title: "<para>" -ms.date: "11/04/2016" +description: "Learn more about: XML documentation tag " +title: " documentation tag" +ms.date: 12/03/2021 f1_keywords: [""] helpviewer_keywords: [" C++ XML tag", "para C++ XML tag"] ms.assetid: 35f2a1b3-bc14-4f13-bcb0-c39ccbf74d59 --- -# <para> +# `` documentation tag -The \ tag is for use inside a tag, such as [\](summary-visual-cpp.md), [\](remarks-visual-cpp.md), or [\](returns-visual-cpp.md), and lets you add structure to the text. +The `` tag is for use inside a tag, such as [``](summary-visual-cpp.md), [``](remarks-visual-cpp.md), or [``](returns-visual-cpp.md), and lets you add structure to the text. ## Syntax -``` -content +```cpp +/// content ``` -#### Parameters +### Parameters -*content*
+*`content`*\ The text of the paragraph. ## Remarks -Compile with [/doc](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. +Compile with [`/doc`](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. ## Example -See [\](summary-visual-cpp.md) for an example of using \. +See [``](summary-visual-cpp.md) for an example of using ``. ## See also -[XML Documentation](xml-documentation-visual-cpp.md) +[XML documentation](xml-documentation-visual-cpp.md) diff --git a/docs/build/reference/param-visual-cpp.md b/docs/build/reference/param-visual-cpp.md index 76915775ed..3f11c6ab64 100644 --- a/docs/build/reference/param-visual-cpp.md +++ b/docs/build/reference/param-visual-cpp.md @@ -1,34 +1,34 @@ --- -description: "Learn more about: <param>" -title: "<param> (C++ documentation comments)" -ms.date: "11/04/2016" +description: "Learn more about: XML documentation tag " +title: " (C++ documentation comments)" +ms.date: 12/03/2021 f1_keywords: [""] helpviewer_keywords: ["param C++ XML tag", " C++ XML tag"] ms.assetid: 66c1a1c3-4f98-4bcf-8c7d-9a40308982fb --- -# <param> +# `` documentation tag -The \ tag should be used in the comment for a method declaration to describe one of the parameters for the method. +The `` tag should be used in the comment for a method declaration to describe one of the parameters for the method. ## Syntax -``` -description +```cpp +/// description ``` -#### Parameters +### Parameters -*name*
-The name of a method parameter. Enclose the name in single or double quotation marks. The compiler issues a warning if it does not find `name`. +*`param-name`*\ +The name of a method parameter. Enclose the name in single or double quotation marks. The compiler issues a warning if it doesn't find *`param-name`*. -*description*
+*`description`*\ A description for the parameter. ## Remarks -The text for the \ tag will be displayed in IntelliSense, the [Object Browser](/visualstudio/ide/viewing-the-structure-of-code), and in the Code Comment Web Report. +The text for the `` tag will be displayed in IntelliSense, the [Object Browser](/visualstudio/ide/viewing-the-structure-of-code), and in the Code Comment Web Report. -Compile with [/doc](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. +Compile with [`/doc`](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. ## Example @@ -46,4 +46,4 @@ public ref class MyClass { ## See also -[XML Documentation](xml-documentation-visual-cpp.md) +[XML documentation](xml-documentation-visual-cpp.md) diff --git a/docs/build/reference/paramref-visual-cpp.md b/docs/build/reference/paramref-visual-cpp.md index 3a526db1a2..1ff58d4850 100644 --- a/docs/build/reference/paramref-visual-cpp.md +++ b/docs/build/reference/paramref-visual-cpp.md @@ -1,29 +1,29 @@ --- -title: "<paramref> (C++ documentation comments)" +title: " (C++ documentation comments)" description: "Learn more about the paramref C++ XML documentation tag." -ms.date: "11/04/2016" +ms.date: 12/03/2021 f1_keywords: [""] helpviewer_keywords: ["paramref C++ XML tag", " C++ XML tag"] ms.assetid: c5730dc2-7159-421f-b2d5-bb971e307122 --- -# <paramref> +# `` documentation tag -The \ tag gives you a way to indicate that a word is a parameter. The .xml file can be processed to format this parameter in some distinct way. +The `` tag gives you a way to indicate that a word is a parameter. The XML file can be processed to format this parameter in some distinct way. ## Syntax -``` - +```cpp +/// ``` -#### Parameters +### Parameters -*name*
-The name of the parameter to refer to. Enclose the name in single or double quotation marks. The compiler issues a warning if it does not find `name`. +*`ref-name`*\ +The name of the parameter to refer to. Enclose the name in single or double quotation marks. The compiler issues a warning if it doesn't find *`ref-name`*. ## Remarks -Compile with [/doc](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. +Compile with [`/doc`](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. ## Example @@ -42,4 +42,4 @@ public ref class MyClass { ## See also -[XML Documentation](xml-documentation-visual-cpp.md) +[XML documentation](xml-documentation-visual-cpp.md) diff --git a/docs/build/reference/pdb-use-program-database.md b/docs/build/reference/pdb-use-program-database.md index 3801076b0d..9d61dad7b1 100644 --- a/docs/build/reference/pdb-use-program-database.md +++ b/docs/build/reference/pdb-use-program-database.md @@ -1,38 +1,37 @@ --- -description: "Learn more about: /PDB (Use Program Database)" title: "/PDB (Use Program Database)" -ms.date: "11/04/2016" +description: "Learn more about: /PDB (Use Program Database)" +ms.date: 03/24/2025 f1_keywords: ["/pdb", "VC.Project.VCLinkerTool.ProgramDatabaseFile"] helpviewer_keywords: ["-PDB linker option", "/PDB linker option", "PDB linker option", "PDB files, creating", ".pdb files, creating"] -ms.assetid: d23db0ce-10cb-427a-bc60-d6b2a852723d --- # /PDB (Use Program Database) -``` -/PDB:filename -``` +Specify the name of the program database (PDB) file that the linker creates. + +## Syntax + +> /PDB:filename ## Arguments -*filename*
-A user-specified name for the program database (PDB) that the linker creates. It replaces the default name. +*`filename`*\ +A user-specified name for the program database (PDB) that the linker creates. It replaces the default name. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). ## Remarks -By default, when [/DEBUG](debug-generate-debug-info.md) is specified, the linker creates a program database (PDB) which holds debugging information. The default file name for the PDB has the base name of the program and the extension .pdb. +By default, when [`/DEBUG`](debug-generate-debug-info.md) is specified, the linker creates a program database (PDB) which holds debugging information. The default file name for the PDB has the base name of the program and the extension .pdb. -Use /PDB:*filename* to specify the name of the PDB file. If /DEBUG is not specified, the /PDB option is ignored. +Use `/PDB:`*`filename`* to specify the name of the PDB file. If `/DEBUG` is not specified, the `/PDB` option is ignored. -A PDB file can be up to 2GB. +A PDB file can be up to 2GB in size. For more information, see [.pdb Files as Linker Input](dot-pdb-files-as-linker-input.md). ### To set this linker option in the Visual Studio development environment 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** > **Linker** > **Debug** property page. - 1. Modify the **Generate Program Database File** property. ### To set this linker option programmatically @@ -41,5 +40,5 @@ For more information, see [.pdb Files as Linker Input](dot-pdb-files-as-linker-i ## See also -[MSVC linker reference](linking.md)
+[MSVC linker reference](linking.md)\ [MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/pdbaltpath-use-alternate-pdb-path.md b/docs/build/reference/pdbaltpath-use-alternate-pdb-path.md index 654278e537..6c198f7815 100644 --- a/docs/build/reference/pdbaltpath-use-alternate-pdb-path.md +++ b/docs/build/reference/pdbaltpath-use-alternate-pdb-path.md @@ -1,29 +1,30 @@ --- description: "Learn more about: /PDBALTPATH (Use Alternate PDB Path)" title: "/PDBALTPATH (Use Alternate PDB Path)" -ms.date: "11/04/2016" +ms.date: 03/24/2025 f1_keywords: ["/pdbaltpath"] helpviewer_keywords: [".pdb files, path", "PDBALTPATH dumpbin option", "-PDBALTPATH dumpbin option", "/PDBALTPATH dumpbin option", "PDB files, path"] -ms.assetid: 72e200aa-e2c3-4ad8-b687-25528da1aaaf --- # /PDBALTPATH (Use Alternate PDB Path) -``` -/PDBALTPATH:pdb_file_name -``` +Provide an alternate location for the Program Database (`.pdb`) file in a compiled binary file. + +## Syntax + +> /PDBALTPATH:pdb_file_name ## Arguments -*pdb_file_name*
-The path and file name for the .pdb file. +*`pdb_file_name`*\ +The path and filename for the `.pdb` file. The path may exceed `MAX_PATH` (260 characters). The filename (not including the path) must not exceed `MAX_PATH`. ## Remarks -Use this option to provide an alternate location for the Program Database (.pdb) file in a compiled binary file. Normally, the linker records the location of the .pdb file in the binaries that it produces. You can use this option to provide a different path and file name for the .pdb file. The information provided with /PDBALTPATH does not change the location or name of the actual .pdb file; it changes the information that the linker writes in the binary file. This enables you to provide a path that is independent of the file structure of the build computer. Two common uses for this option are to provide a network path or a file that has no path information. +Use this option to provide an alternate location for the Program Database (`.pdb`) file in a compiled binary file. Normally, the linker records the location of the `.pdb` file in the binaries that it produces. You can use this option to provide a different path and file name for the `.pdb` file. The information provided with `/PDBALTPATH` does not change the location or name of the actual `.pdb` file; it changes the information that the linker writes in the binary file. This enables you to provide a path that is independent of the file structure of the build computer. Two common uses for this option are to provide a network path or a file that has no path information. -The value of *pdb_file_name* can be an arbitrary string, an environment variable, or **%_PDB%**. The linker will expand an environment variable, such as **%SystemRoot%**, to its value. The linker defines the environment variables **%_PDB%** and **%_EXT%**. **%_PDB%** expands to the file name of the actual .pdb file without any path information and **%_EXT%** is the extension of the generated executable. +The value of *`pdb_file_name`* can be an arbitrary string, an environment variable, or `%_PDB%`. The linker will expand an environment variable, such as `%SystemRoot%`, to its value. The linker defines the environment variables `%_PDB%` and `%_EXT%`. `%_PDB%` expands to the file name of the actual `.pdb` file without any path information and `%_EXT%` is the extension of the generated executable. ## See also -[DUMPBIN Options](dumpbin-options.md)
-[/PDBPATH](pdbpath.md) +[DUMPBIN Options](dumpbin-options.md)\ +[`/PDBPATH`](pdbpath.md) diff --git a/docs/build/reference/pdbpath.md b/docs/build/reference/pdbpath.md index f97ea47913..b88420f081 100644 --- a/docs/build/reference/pdbpath.md +++ b/docs/build/reference/pdbpath.md @@ -2,11 +2,10 @@ description: "Learn more about: /PDBPATH" title: "/PDBPATH" ms.date: "11/04/2016" -f1_keywords: ["/pdbpath"] +f1_keywords: ["/PDBPATH"] helpviewer_keywords: [".pdb files, path", "-PDBPATH dumpbin option", "/PDBPATH dumpbin option", "PDBPATH dumpbin option", "PDB files, path"] -ms.assetid: ccf67dcd-0b23-4250-ad47-06c48acbe82b --- -# /PDBPATH +# `/PDBPATH` ``` /PDBPATH[:VERBOSE] filename @@ -14,31 +13,27 @@ ms.assetid: ccf67dcd-0b23-4250-ad47-06c48acbe82b ### Parameters -*filename*
-The name of the .dll or .exe file for which you want to find the matching .pdb file. +*filename*\ +The name of the .dll or `.exe` file for which you want to find the matching `.pdb` file. -**:VERBOSE**
-(Optional) Reports all directories where an attempt was made to locate the .pdb file. +**`:VERBOSE`**\ +(Optional) Reports all directories where an attempt was made to locate the `.pdb` file. ## Remarks -/PDBPATH will search your computer along the same paths that the debugger would search for a .pdb file and will report which, if any, .pdb files correspond to the file specified in *filename*. +`/PDBPATH` searches your computer along the same paths that the debugger searches for a `.pdb` file and reports which, if any, `.pdb` files correspond to the file specified in *filename*. -When using the Visual Studio debugger, you may experience a problem due to the fact that the debugger is using a .pdb file for a different version of the file you are debugging. +When using the Visual Studio debugger, you may experience a problem because the debugger is using a `.pdb` file for a different version of the file you're debugging. -/PDBPATH will search for .pdb files along the following paths: +`/PDBPATH` will search for `.pdb` files along the following paths: - Check the location where the executable resides. - - Check the location of the PDB written into the executable. This is usually the location at the time the image was linked. - - Check along the search path configured in the Visual Studio IDE. - -- Check along the paths in the _NT_SYMBOL_PATH and _NT_ALT_SYMBOL_PATH environment variables. - +- Check along the paths in the `_NT_SYMBOL_PATH` and `_NT_ALT_SYMBOL_PATH` environment variables. - Check in the Windows directory. ## See also -[DUMPBIN Options](dumpbin-options.md)
-[/PDBALTPATH (Use Alternate PDB Path)](pdbaltpath-use-alternate-pdb-path.md) +[`DUMPBIN` Options](dumpbin-options.md)\ +[`/PDBALTPATH` (Use Alternate PDB Path)](pdbaltpath-use-alternate-pdb-path.md) diff --git a/docs/build/reference/permission-visual-cpp.md b/docs/build/reference/permission-visual-cpp.md index f91aaa0d0a..007e807a83 100644 --- a/docs/build/reference/permission-visual-cpp.md +++ b/docs/build/reference/permission-visual-cpp.md @@ -1,38 +1,38 @@ --- -description: "Learn more about: <permission>" -title: "<permission> (C++ documentation comments)" -ms.date: "11/04/2016" +description: "Learn more about: XML documentation tag " +title: " (C++ documentation comments)" +ms.date: 12/03/2021 f1_keywords: [""] helpviewer_keywords: [" C++ XML tag", "permission C++ XML tag"] ms.assetid: 537ee2bc-95bd-48e4-9ce6-3420c3da87f4 --- -# <permission> +# `` documentation tag -The \ tag lets you document the access of a member. lets you specify access to a member. +The `` tag lets you document the access of a member. lets you specify access to a member. ## Syntax -``` -description +```cpp +/// description ``` -#### Parameters +### Parameters -*member*
-A reference to a member or field that is available to be called from the current compilation environment. The compiler checks that the given code element exists and translates `member` to the canonical element name in the output XML. Enclose the name in single or double quotation marks. +*`member`*\ +A reference to a member or field that is available to be called from the current compilation environment. The compiler checks that the given code element exists and translates *`member`* to the canonical element name in the output XML. Enclose the name in single or double quotation marks. -The compiler issues a warning if it does not find `member`. +The compiler issues a warning if it doesn't find *`member`*. -For information on how to create a cref reference to a generic type, see [\](see-visual-cpp.md). +For information on how to create a `cref` reference to a generic type, see [``](see-visual-cpp.md). -*description*
+*`description`*\ A description of the access to the member. ## Remarks -Compile with [/doc](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. +Compile with [`/doc`](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. -The MSVC compiler will attempt to resolve cref references in one pass through the documentation comments. Therefore, if using the C++ lookup rules, a symbol is not found by the compiler the reference will be marked as unresolved. See [\](seealso-visual-cpp.md) for more information. +The MSVC compiler will attempt to resolve `cref` references in one pass through the documentation comments. If the compiler doesn't find a symbol when using the C++ lookup rules, the reference will be marked as unresolved. For more information, see [``](seealso-visual-cpp.md). ## Example @@ -50,4 +50,4 @@ public ref class TestClass { ## See also -[XML Documentation](xml-documentation-visual-cpp.md) +[XML documentation](xml-documentation-visual-cpp.md) diff --git a/docs/build/reference/permissive-standards-conformance.md b/docs/build/reference/permissive-standards-conformance.md index ef5bd151e9..3a182cb84d 100644 --- a/docs/build/reference/permissive-standards-conformance.md +++ b/docs/build/reference/permissive-standards-conformance.md @@ -1,12 +1,11 @@ --- title: "/permissive- (Standards conformance)" description: "Reference guide to the Microsoft C++ /permissive- (Standards conformance) compiler option." -ms.date: 10/28/2020 +ms.date: 10/12/2023 f1_keywords: ["/permissive", "VC.Project.VCCLCompilerTool.ConformanceMode"] helpviewer_keywords: ["/permissive compiler options [C++]", "-permissive compiler options [C++]", "Standards conformance compiler options", "permissive compiler options [C++]"] -ms.assetid: db1cc175-6e93-4a2e-9396-c3725d2d8f71 --- -# /permissive- (Standards conformance) +# `/permissive-` (Standards conformance) Specify standards conformance mode to the compiler. Use this option to help you identify and fix conformance issues in your code, to make it both more correct and more portable. @@ -21,9 +20,9 @@ The **`/permissive-`** option is supported in Visual Studio 2017 and later. **`/ You can use the **`/permissive-`** compiler option to specify standards-conforming compiler behavior. This option disables permissive behaviors, and sets the [`/Zc`](zc-conformance.md) compiler options for strict conformance. In the IDE, this option also makes the IntelliSense engine underline non-conforming code. -The **`/permissive-`** option uses the conformance support in the current compiler version to determine which language constructs are non-conforming. The option doesn't determine if your code conforms to a specific version of the C++ standard. To enable all implemented compiler support for the latest draft standard, use the [`/std:c++latest`](std-specify-language-standard-version.md) option. To restrict the compiler support to the currently implemented C++17 standard, use the [`/std:c++17`](std-specify-language-standard-version.md) option. To restrict the compiler support to more closely match the C++14 standard, use the [`/std:c++14`](std-specify-language-standard-version.md) option, which is the default. +The **`/permissive-`** option uses the conformance support in the current compiler version to determine which language constructs are non-conforming. The option doesn't determine if your code conforms to a specific version of the C++ standard. To enable all implemented compiler support for the latest draft standard, use the [`/std:c++latest`](std-specify-language-standard-version.md) option. To restrict the compiler support to the currently implemented C++20 standard, use the [`/std:c++20`](std-specify-language-standard-version.md) option. To restrict the compiler support to the currently implemented C++17 standard, use the [`/std:c++17`](std-specify-language-standard-version.md) option. To restrict the compiler support to more closely match the C++14 standard, use the [`/std:c++14`](std-specify-language-standard-version.md) option, which is the default. -Starting in Visual Studio 2019 version 16.8, the **`/std:c++latest`** option implicitly sets the **`/permissive-`** option. It's required for C++20 Modules support. Perhaps your code doesn't need modules support but requires other features enabled under **`/std:c++latest`**. You can explicitly enable Microsoft extension support by using the **`/permissive`** option without the trailing dash. +The **`/permissive-`** option is implicitly set by the **`/std:c++latest`** option starting in Visual Studio 2019 version 16.8, and in version 16.11 by the **`/std:c++20`** option. **`/permissive-`** is required for C++20 Modules support. Perhaps your code doesn't need modules support but requires other features enabled under **`/std:c++20`** or **`/std:c++latest`**. You can explicitly enable Microsoft extension support by using the **`/permissive`** option without the trailing dash. The **`/permissive`** option must come after any option that sets **`/permissive-`** implicitly. By default, the **`/permissive-`** option is set in new projects created by Visual Studio 2017 version 15.5 and later versions. It's not set by default in earlier versions. When the option is set, the compiler generates diagnostic errors or warnings when non-standard language constructs are detected in your code. These constructs include some common bugs in pre-C++11 code. @@ -33,15 +32,17 @@ The **`/permissive-`** option sets the [`/Zc:referenceBinding`](zc-referencebind In versions of the compiler beginning in Visual Studio 2017 version 15.3, the **`/permissive-`** option sets the [`/Zc:ternary`](zc-ternary.md) option. The compiler also implements more of the requirements for two-phase name look-up. When the **`/permissive-`** option is set, the compiler parses function and class template definitions, and identifies dependent and non-dependent names used in the templates. In this release, only name dependency analysis is performed. -Environment-specific extensions and language areas that the standard leaves up to the implementation are not affected by **`/permissive-`**. For example, the Microsoft-specific **`__declspec`**, calling convention and structured exception handling keywords, and compiler-specific pragma directives or attributes are not flagged by the compiler in **`/permissive-`** mode. +As of Visual Studio 2022 Update 17.6, the **`/permissive-`** option sets the [`/Zc:lambda`](zc-lambda.md) and [`/Zc:externConstexpr`](zc-externconstexpr.md) options. In prior versions, **`/permissive-`** didn't set either one. -Not all C++11, C++14, or C++17 standards-conforming code is supported by the MSVC compiler in all versions of Visual Studio 2017. Depending on the version of Visual Studio, the **`/permissive-`** option may not detect issues in some aspects of two-phase name lookup, binding a non-const reference to a temporary, treating copy init as direct init, allowing multiple user-defined conversions in initialization, or alternative tokens for logical operators, and other non-supported conformance areas. For more information about conformance issues in Visual C++, see [Nonstandard Behavior](../../cpp/nonstandard-behavior.md). To get the most out of **`/permissive-`**, update Visual Studio to the latest version. +Environment-specific extensions and language areas that the standard leaves up to the implementation aren't affected by **`/permissive-`**. For example, the Microsoft-specific **`__declspec`**, calling convention and structured exception handling keywords, and compiler-specific `pragma` directives or attributes aren't flagged by the compiler in **`/permissive-`** mode. + +The MSVC compiler in earlier versions of Visual Studio 2017 doesn't support all C++11, C++14, or C++17 standards-conforming code. Depending on the version of Visual Studio, the **`/permissive-`** option may not detect issues in some aspects of two-phase name lookup, binding a non-const reference to a temporary, treating copy init as direct init, allowing multiple user-defined conversions in initialization, or alternative tokens for logical operators, and other non-supported conformance areas. For more information about conformance issues in Visual C++, see [Nonstandard Behavior](../../cpp/nonstandard-behavior.md). To get the most out of **`/permissive-`**, update Visual Studio to the latest version. ### How to fix your code Here are some examples of code that is detected as non-conforming when you use **`/permissive-`**, along with suggested ways to fix the issues. -#### Use default as an identifier in native code +#### Use `default` as an identifier in native code ```cpp void func(int default); // Error C2321: 'default' is a keyword, and @@ -52,27 +53,45 @@ void func(int default); // Error C2321: 'default' is a keyword, and ```cpp template -struct B { - void f(); +struct B +{ + void f() {} + template + struct S { void operator()(){ return; } }; }; template struct D : public B // B is a dependent base because its type // depends on the type of T. { - // One possible fix is to uncomment the following line. - // If this is a type, don't forget the 'typename' keyword. + // One possible fix for non-template members and function + // template members is a using statement: // using B::f; + // If it's a type, don't forget the 'typename' keyword. - void g() { + void g() + { f(); // error C3861: 'f': identifier not found - // Another fix is to change it to 'this->f();' + // Another fix is to change the call to 'this->f();' + } + + void h() + { + S s; // C2065 or C3878 + // Since template S is dependent, the type must be qualified + // with the `typename` keyword. + // To fix, replace the declaration of s with: + // typename B::template S s; + // Or, use this: + // typename D::template S s; + s(); } }; void h() { D d; d.g(); + d.h(); } ``` @@ -103,6 +122,8 @@ union U #### Hidden friend name lookup rules +A declaration outside a class can make a hidden friend visible: + ```cpp // Example 1 struct S { @@ -115,6 +136,8 @@ using type = void (*)(S *); type p = &f; // error C2065: 'f': undeclared identifier. ``` +Use of literal `nullptr` can prevent argument dependent lookup: + ```cpp // Example 2 struct S { @@ -158,7 +181,9 @@ void func() { } ``` -#### Use of ATL Attributes +#### Use of ATL attributes + +Microsoft-specific ATL attributes can cause issues under **`/permissive-`**: ```cpp // Example 1 @@ -166,11 +191,15 @@ void func() { class A {}; ``` +You can fix the issue by using the **`__declspec`** form instead: + ```cpp // Fix for example 1 class __declspec(uuid("594382D9-44B0-461A-8DE3-E06A3E73C5EB")) B {}; ``` +A more complex example: + ```cpp // Example 2 [emitidl]; @@ -187,6 +216,8 @@ class CFoo : public ICustom {}; ``` +Resolution requires extra build steps. In this case, create an IDL file: + ```cpp // Fix for example 2 // First, create the *.idl file. The vc140.idl generated file can be @@ -241,7 +272,7 @@ Common errors that may result from this change include: - `error C2446: ':': no conversion from 'B' to 'A'` -A typical code pattern that can cause this issue is when some class C provides both a non-explicit constructor from another type T and a non-explicit conversion operator to type T. In this case, both the conversion of the second argument to the type of the third argument, and the conversion of the third argument to the type of the second argument, are valid conversions. Since both are valid, it's ambiguous according to the standard. +A typical code pattern that can cause this issue is when some class `C` provides both a non-explicit constructor from another type `T` and a non-explicit conversion operator to type `T`. The conversion of the second argument to the third argument's type is a valid conversion. So is the conversion of the third argument to the second argument's type. Since both are valid, it's ambiguous according to the standard. ```cpp // Example 1: class that provides conversion to and initialization from some type T @@ -261,7 +292,7 @@ auto y = cond ? 7 : int(a); auto z = cond ? A(7) : a; ``` -There's an important exception to this common pattern when T represents one of the null-terminated string types (for example, `const char *`, `const char16_t *`, and so on) and the actual argument to `?:` is a string literal of corresponding type. C++17 has changed semantics from C++14. As a result, the code in example 2 is accepted under **`/std:c++14`** and rejected under **`/std:c++17`** when **`/Zc:ternary`** or **`/permissive-`** is used. +There's an important exception to this common pattern when T represents one of the null-terminated string types (for example, `const char *`, `const char16_t *`, and so on) and the actual argument to `?:` is a string literal of corresponding type. C++17 has changed semantics from C++14. As a result, the code in example 2 is accepted under **`/std:c++14`** and rejected under **`/std:c++17`** or later when **`/Zc:ternary`** or **`/permissive-`** is used. ```cpp // Example 2: exception from the above @@ -282,7 +313,7 @@ auto x = cond ? "A" : s; auto y = cond ? "A" : static_cast(s); ``` -Another case where you may see errors is in conditional operators with one argument of type **`void`**. This case may be common in ASSERT-like macros. +You may also see errors in conditional operators with one argument of type **`void`**. This case may be common in ASSERT-like macros. ```cpp // Example 3: void arguments @@ -343,7 +374,7 @@ Certain header files in the Windows April 2018 Update SDK (10.0.17134.0), the Wi These WinRT WRL headers released in the Windows April 2018 Update SDK (10.0.17134.0) aren't clean with **`/permissive-`**. To work around these issues, either don't use **`/permissive-`**, or use **`/permissive-`** with **`/Zc:twoPhase-`** when you work with these headers: -- Issues in winrt/wrl/async.h +- Issues in *`winrt/wrl/async.h`* ```Output C:\Program Files (x86)\Windows Kits\10\Include\10.0.17134.0\winrt\wrl\async.h(483): error C3861: 'TraceDelegateAssigned': identifier not found @@ -352,7 +383,7 @@ These WinRT WRL headers released in the Windows April 2018 Update SDK (10.0.1713 C:\Program Files (x86)\Windows Kits\10\Include\10.0.17134.0\winrt\wrl\async.h(513): error C3861: 'TraceProgressNotificationComplete': identifier not found ``` -- Issue in winrt/wrl/implements.h +- Issue in *`winrt/wrl/implements.h`* ```Output C:\Program Files (x86)\Windows Kits\10\include\10.0.17134.0\winrt\wrl\implements.h(2086): error C2039: 'SetStrongReference': is not a member of 'Microsoft::WRL::Details::WeakReferenceImpl' @@ -360,7 +391,7 @@ These WinRT WRL headers released in the Windows April 2018 Update SDK (10.0.1713 These User Mode headers released in the Windows April 2018 Update SDK (10.0.17134.0) aren't clean with **`/permissive-`**. To work around these issues, don't use **`/permissive-`** when working with these headers: -- Issues in um/Tune.h +- Issues in *`um/Tune.h`* ```Output C:\ProgramFiles(x86)\Windows Kits\10\include\10.0.17134.0\um\tune.h(139): error C3861: 'Release': identifier not found @@ -369,13 +400,13 @@ These User Mode headers released in the Windows April 2018 Update SDK (10.0.1713 C:\Program Files (x86)\Windows Kits\10\include\10.0.17134.0\um\tune.h(1240): note: 'Release': function declaration must be available as none of the arguments depend on a template parameter ``` -- Issue in um/spddkhlp.h +- Issue in *`um/spddkhlp.h`* ```Output C:\Program Files (x86)\Windows Kits\10\include\10.0.17134.0\um\spddkhlp.h(759): error C3861: 'pNode': identifier not found ``` -- Issues in um/refptrco.h +- Issues in *`um/refptrco.h`* ```Output C:\Program Files (x86)\Windows Kits\10\include\10.0.17134.0\um\refptrco.h(179): error C2760: syntax error: unexpected token 'identifier', expected 'type specifier' @@ -385,9 +416,9 @@ These User Mode headers released in the Windows April 2018 Update SDK (10.0.1713 These issues are specific to User Mode headers in the Windows Fall Creators Update SDK (10.0.16299.0): -- Issue in um/Query.h +- Issue in *`um/Query.h`* - When using the **`/permissive-`** compiler switch, the `tagRESTRICTION` structure doesn't compile because of the case(RTOr) member 'or'. + When you use the **`/permissive-`** compiler switch, the `tagRESTRICTION` structure doesn't compile because of the `case(RTOr)` member `or`. ```cpp struct tagRESTRICTION @@ -409,21 +440,21 @@ These issues are specific to User Mode headers in the Windows Fall Creators Upda }; ``` - To address this issue, compile files that include Query.h without the **`/permissive-`** option. + To address this issue, compile files that include *`Query.h`* without the **`/permissive-`** option. -- Issue in um/cellularapi_oem.h +- Issue in *`um/cellularapi_oem.h`* - When using the **`/permissive-`** compiler switch, the forward declaration of `enum UICCDATASTOREACCESSMODE` causes a warning: + When you use the **`/permissive-`** compiler switch, the forward declaration of `enum UICCDATASTOREACCESSMODE` causes a warning: ```cpp typedef enum UICCDATASTOREACCESSMODE UICCDATASTOREACCESSMODE; // C4471 ``` - The forward declaration of unscoped enum is a Microsoft extension. To address this issue, compile files that include cellularapi_oem.h without the **`/permissive-`** option, or use the [`/wd`](compiler-option-warning-level.md) option to silence warning C4471. + The forward declaration of an unscoped `enum` is a Microsoft extension. To address this issue, compile files that include *`cellularapi_oem.h`* without the **`/permissive-`** option, or use the [`/wd`](compiler-option-warning-level.md) option to silence warning C4471. -- Issue in um/omscript.h +- Issue in *`um/omscript.h`* - In C++03, a conversion from a string literal to BSTR (which is a typedef to 'wchar_t *') is deprecated but allowed. In C++11, the conversion is no longer allowed. + In C++03, a conversion from a string literal to `BSTR` (which is a typedef to `wchar_t *`) is deprecated but allowed. In C++11, the conversion is no longer allowed. ```cpp virtual /* [id] */ HRESULT STDMETHODCALLTYPE setExpression( diff --git a/docs/build/reference/pgd-specify-database-for-profile-guided-optimizations.md b/docs/build/reference/pgd-specify-database-for-profile-guided-optimizations.md index 219bd6b023..77539e99b0 100644 --- a/docs/build/reference/pgd-specify-database-for-profile-guided-optimizations.md +++ b/docs/build/reference/pgd-specify-database-for-profile-guided-optimizations.md @@ -1,14 +1,13 @@ --- description: "Learn more about: /PGD (Specify Database for Profile-Guided Optimizations)" title: "/PGD (Specify Database for Profile-Guided Optimizations)" -ms.date: "03/14/2018" +ms.date: 03/24/2025 f1_keywords: ["VC.Project.VCLinkerTool.ProfileGuidedDatabase"] helpviewer_keywords: ["-PGD linker option", "/PGD linker option"] -ms.assetid: 9f312498-493b-461f-886f-92652257e443 --- # /PGD (Specify Database for Profile-Guided Optimizations) -**The /PGD option is deprecated.** Starting in Visual Studio 2015, prefer the [/GENPROFILE or /FASTGENPROFILE](genprofile-fastgenprofile-generate-profiling-instrumented-build.md) linker options instead. This option is used to specify the name of the .pgd file used by the profile-guided optimization process. +**The /PGD option is deprecated.** Starting in Visual Studio 2015, prefer the [`/GENPROFILE`or `/FASTGENPROFILE`](genprofile-fastgenprofile-generate-profiling-instrumented-build.md) linker options instead. This option is used to specify the name of the .pgd file used by the profile-guided optimization process. ## Syntax @@ -16,14 +15,14 @@ ms.assetid: 9f312498-493b-461f-886f-92652257e443 ## Argument -*filename*
-Specifies the name of the .pgd file that is used to hold information about the running program. +`filename`\ +Specifies the name of the `.pgd` file that is used to hold information about the running program. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). ## Remarks -When using the deprecated [/LTCG:PGINSTRUMENT](ltcg-link-time-code-generation.md) option, use **/PGD** to specify a nondefault name or location for the .pgd file. If you do not specify **/PGD**, the .pgd file base name is the same as the output file (.exe or .dll) base name and is created in the same directory from which the link was invoked. +When using the deprecated [`/LTCG:PGINSTRUMENT`](ltcg-link-time-code-generation.md) option, use **`/PGD`** to specify a nondefault name or location for the `.pgd` file. If you don't specify **`/PGD`**, the `.pgd` file base name is the same as the output file (`.exe` or `.dll`) base name and is created in the same directory from which the link was invoked. -When using the deprecated **/LTCG:PGOPTIMIZE** option, use the **/PGD** option to specify the name of the .pgd file to use to create the optimized image. The *filename* argument should match the *filename* specified to **/LTCG:PGINSTRUMENT**. +When using the deprecated **`/LTCG:PGOPTIMIZE`** option, use the **`/PGD`** option to specify the name of the `.pgd` file to use to create the optimized image. The *`filename`* argument should match the *`filename`* specified to **`/LTCG:PGINSTRUMENT`**. For more information, see [Profile-Guided Optimizations](../profile-guided-optimizations.md). @@ -41,5 +40,5 @@ For more information, see [Profile-Guided Optimizations](../profile-guided-optim ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md)
+[MSVC linker reference](linking.md)\ +[MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/precedence-in-inference-rules.md b/docs/build/reference/precedence-in-inference-rules.md deleted file mode 100644 index 2947fa0e9b..0000000000 --- a/docs/build/reference/precedence-in-inference-rules.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -description: "Learn more about: Precedence in Inference Rules" -title: "Precedence in Inference Rules" -ms.date: "11/04/2016" -helpviewer_keywords: ["inference rules in NMAKE", "rules, inference", "precedence, inference rule"] -ms.assetid: 69e3dc02-0815-4c3a-b02b-1cb85fceaf24 ---- -# Precedence in Inference Rules - -If an inference rule is multiply defined, NMAKE uses the highest-precedence definition. The following list shows the order of precedence from highest to lowest: - -1. An inference rule defined in a makefile; later definitions have precedence. - -1. An inference rule defined in Tools.ini; later definitions have precedence. - -1. A predefined inference rule. - -## See also - -[Inference Rules](inference-rules.md) diff --git a/docs/build/reference/precedence-in-macro-definitions.md b/docs/build/reference/precedence-in-macro-definitions.md deleted file mode 100644 index 079e3c2ed0..0000000000 --- a/docs/build/reference/precedence-in-macro-definitions.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -description: "Learn more about: Precedence in Macro Definitions" -title: "Precedence in Macro Definitions" -ms.date: "11/04/2016" -helpviewer_keywords: ["NMAKE program, precedence in macro definitions", "macros, precedence"] -ms.assetid: 0c13182d-83cb-4cbd-af2d-f4c916b62aeb ---- -# Precedence in Macro Definitions - -If a macro has multiple definitions, NMAKE uses the highest-precedence definition. The following list shows the order of precedence, from highest to lowest: - -1. A macro defined on the command line - -1. A macro defined in a makefile or include file - -1. An inherited environment-variable macro - -1. A macro defined in the Tools.ini file - -1. A predefined macro, such as [CC](command-macros-and-options-macros.md) and [AS](command-macros-and-options-macros.md) - -Use /E to cause macros inherited from environment variables to override makefile macros with the same name. Use **!UNDEF** to override a command line. - -## See also - -[Defining an NMAKE Macro](defining-an-nmake-macro.md) diff --git a/docs/build/reference/predefined-rules.md b/docs/build/reference/predefined-rules.md deleted file mode 100644 index c98ec544cc..0000000000 --- a/docs/build/reference/predefined-rules.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -description: "Learn more about: Predefined Rules" -title: "Predefined Rules" -ms.date: "11/04/2016" -helpviewer_keywords: ["rules, predefined", "NMAKE program, predefined rules", "predefined rules in NMAKE"] -ms.assetid: 638cdc3f-4aba-4b4f-96e3-ad65b0364f12 ---- -# Predefined Rules - -Predefined inference rules use NMAKE-supplied command and options macros. - -|Rule|Command|Default

action|Batch

Rule|Platform nmake runs on| -|----------|-------------|------------------------|--------------------|----------------------------| -|.asm.exe|$(AS) $(AFLAGS) $<|ml $<|no|x86| -|.asm.obj|$(AS) $(AFLAGS) /c $<|ml /c $<|yes|x86| -|.asm.exe|$(AS) $(AFLAGS) $<|ml64 $<|no|x64| -|.asm.obj|$(AS) $(AFLAGS) /c $<|ml64 /c $<|yes|x64| -|.c.exe|$(CC) $(CFLAGS) $<|cl $<|no|all| -|.c.obj|$(CC) $(CFLAGS) /c $<|cl /c $<|yes|all| -|.cc.exe|$(CC) $(CFLAGS) $<|cl $<|no|all| -|.cc.obj|$(CC) $(CFLAGS) /c $<|cl /c $<|yes|all| -|.cpp.exe|$(CPP) $(CPPFLAGS) $<|cl $<|no|all| -|.cpp.obj|$(CPP) $(CPPFLAGS) /c $<|cl /c $<|yes|all| -|.cxx.exe|$(CXX) $(CXXFLAGS) $<|cl $<|no|all| -|.cxx.obj|$(CXX) $(CXXFLAGS) /c $<|cl /c $<|yes|all| -|.rc.res|$(RC) $(RFLAGS) /r $<|rc /r $<|no|all| - -## See also - -[Inference Rules](inference-rules.md) diff --git a/docs/build/reference/profile-performance-tools-profiler.md b/docs/build/reference/profile-performance-tools-profiler.md index c2c656139b..d1273f084d 100644 --- a/docs/build/reference/profile-performance-tools-profiler.md +++ b/docs/build/reference/profile-performance-tools-profiler.md @@ -1,36 +1,35 @@ --- description: "Learn more about: /PROFILE (Performance Tools Profiler)" title: "/PROFILE (Performance Tools Profiler)" -ms.date: "11/04/2016" +ms.date: 10/13/2021 f1_keywords: ["VC.Project.VCLinkerTool.Profile"] helpviewer_keywords: ["-PROFILE linker option", "/PROFILE linker option"] -ms.assetid: e676baa1-5063-47a3-a357-ba0d1f0d1699 --- -# /PROFILE (Performance Tools Profiler) +# `/PROFILE` (Performance Tools Profiler) Produces an output file that can be used with the Performance Tools profiler. ## Syntax -``` -/PROFILE -``` +> **`/PROFILE`** ## Remarks /PROFILE implies the following linker options: -- [/OPT:REF](opt-optimizations.md) +- [`/DEBUG:FULL`](debug-generate-debug-info.md) -- /OPT:NOICF +- [`/DEBUGTYPE:cv,fixup`](debugtype-debug-info-options.md) -- [/INCREMENTAL:NO](incremental-link-incrementally.md) +- [`/OPT:REF`](opt-optimizations.md) -- [/FIXED:NO](fixed-fixed-base-address.md) +- [`/OPT:NOICF`](opt-optimizations.md) -/PROFILE causes the linker to generate a relocation section in the program image. A relocation section allows the profiler to transform the program image to get profile data. +- [`/INCREMENTAL:NO`](incremental-link-incrementally.md) -**/PROFILE** is only available only in Enterprise (team development) versions. For more information on PREfast, see [Code Analysis for C/C++ Overview](../../code-quality/code-analysis-for-c-cpp-overview.md). +- [`/FIXED:NO`](fixed-fixed-base-address.md) + +**`/PROFILE`** is used to support the Performance Tools for Visual Studio Profiler utility [`VSInstr.exe`](/visualstudio/profiling/vsinstr). ### To set this linker option in the Visual Studio development environment @@ -44,21 +43,21 @@ Produces an output file that can be used with the Performance Tools profiler. 1. See . -### To set this linker option within Visual Studio CMake project +### To set this linker option in a Visual Studio CMake project -**CMake** project does not have a **Property Pages**, the linker options can be set by modifing the CMakeLists.txt. +Because a **CMake** project doesn't have the usual **Property Pages** support, the linker option can be set by modifying the *`CMakeLists.txt`* file. -1. Open the CMakeLists.txt in the project root directory. +1. Open the *`CMakeLists.txt`* file in the project root directory. -1. Add code below. For details, see [CMake references](https://cmake.org/cmake/help/v3.0/command/set_target_properties.html) +1. Add the code below. For more information, see the CMake [`set_target_properties`](https://cmake.org/cmake/help/latest/command/set_target_properties.html) documentation. -1. Rebuild your solution. + ```txt + SET_TARGET_PROPERTIES(${PROJECT_NAME} PROPERTIES LINK_FLAGS "/PROFILE") + ``` -``` -SET_TARGET_PROPERTIES(${PROJECT_NAME} PROPERTIES LINK_FLAGS "/PROFILE") -``` +1. Rebuild your solution. ## See Also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/property-page-xml-files.md b/docs/build/reference/property-page-xml-files.md index f74c8a72b5..b7d32df9fb 100644 --- a/docs/build/reference/property-page-xml-files.md +++ b/docs/build/reference/property-page-xml-files.md @@ -35,9 +35,9 @@ You only need to understand the internal workings of these files and the Visual First, let's open the property pages for a project. Right-click on the project node in **Solution Explorer** and choose **Properties**: -![Shows the Visual Studio C++ Project Properties dialog](../media/cpp-property-page-2017.png) +![Screenshot of the project Property Pages dialog.](../media/cpp-property-page-2017.png) -Each node under **Configuration Properties** is called a *rule*. A rule sometimes represents a single tool like the compiler. In general, the term refers to something that has properties, that executes and that may produce some output. Each rule is populated from an XML file in the default rules folder. For example, the C/C++ rule that's shown here is populated by *`cl.xml'*. +Each node under **Configuration Properties** is called a *rule*. A rule sometimes represents a single tool like the compiler. In general, the term refers to something that has properties, that executes and that may produce some output. Each rule is populated from an XML file in the default rules folder. For example, the C/C++ rule that's shown here is populated by *`cl.xml`*. Each rule has a set of properties, which are organized into *categories*. Each sub-node under a rule represents a category. For example, the **Optimization** node under **C/C++** contains all the optimization-related properties of the compiler tool. The properties and their values get rendered in a grid format on the right pane. diff --git a/docs/build/reference/property-pages-visual-cpp.md b/docs/build/reference/property-pages-visual-cpp.md index d6855d9aae..a265d2aaf9 100644 --- a/docs/build/reference/property-pages-visual-cpp.md +++ b/docs/build/reference/property-pages-visual-cpp.md @@ -9,7 +9,7 @@ ms.assetid: 13ffe3ea-1bc3-4bee-be5e-053a8a99cce4 In Visual Studio, you specify compiler and linker options, file paths, and other build settings through the property pages for the project. The properties and property pages that are available depend on the project type. For example, a makefile project has an NMake property page, which is not present in an MFC or Win32 console project. To open the **Property Pages**, choose **Project** > **Properties** from the main menu, or right-click on the project node in **Solution Explorer** and choose **Properties**. Individual files also have property pages that enable you to set compile and build options for just that file. The following image shows the property pages for an MFC project. -![Property Pages for C++ project](media/example-prop-page.png) +![Screenshot of the project Property Pages dialog.](media/example-prop-page.png) This section provides a quick reference for the property pages themselves. The options and settings exposed in the property pages are documented more completely in their own topics and are linked from the property page topics. For more information about project properties, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). diff --git a/docs/build/reference/qfast-transcendentals-force-fast-transcendentals.md b/docs/build/reference/qfast-transcendentals-force-fast-transcendentals.md index 7259b4b09e..4cff2b6e29 100644 --- a/docs/build/reference/qfast-transcendentals-force-fast-transcendentals.md +++ b/docs/build/reference/qfast-transcendentals-force-fast-transcendentals.md @@ -1,26 +1,24 @@ --- -description: "Learn more about: /Qfast_transcendentals (Force Fast Transcendentals)" -title: "/Qfast_transcendentals (Force Fast Transcendentals)" -ms.date: "11/04/2016" +description: "Learn more about: /Qfast_transcendentals (Force fast transcendentals)" +title: "/Qfast_transcendentals (Force fast transcendentals)" +ms.date: 03/02/2022 f1_keywords: ["/Qfast_transcendentals"] helpviewer_keywords: ["/Qfast_transcendentals", "Force Fast Transcendentals"] ms.assetid: 4de24bd1-38e6-49d4-9a05-04c9937d24ac --- -# /Qfast_transcendentals (Force Fast Transcendentals) +# `/Qfast_transcendentals` (Force fast transcendentals) Generates inline code for transcendental functions. ## Syntax -``` -/Qfast_transcendentals -``` +> **`/Qfast_transcendentals`** ## Remarks -This compiler option forces transcendental functions to be converted to inline code to improve execution speed. This option has an effect only when paired with **/fp:except** or **/fp:precise**. Generating inline code for transcendental functions is already the default behavior under **/fp:fast**. +This compiler option forces transcendental functions to be converted to inline code to improve execution speed. This option has an effect only when paired with **`/fp:except`** or **`/fp:precise`**. Generating inline code for transcendental functions is already the default behavior under **`/fp:fast`**. -This option is incompatible with **/fp:strict**. See [/fp (Specify Floating-Point Behavior)](fp-specify-floating-point-behavior.md) for more information about floating point compiler options. +This option is incompatible with **`/fp:strict`**. For more information about floating point compiler options, see [`/fp` (Specify Floating-Point Behavior)](fp-specify-floating-point-behavior.md). ### To set this compiler option in the Visual Studio development environment @@ -36,6 +34,6 @@ This option is incompatible with **/fp:strict**. See [/fp (Specify Floating-Poin ## See also -[/Q Options (Low-Level Operations)](q-options-low-level-operations.md)
-[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) +[`/Q` Options (Low-level operations)](q-options-low-level-operations.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/qpar-auto-parallelizer.md b/docs/build/reference/qpar-auto-parallelizer.md index c50be3c3e1..37cedc2517 100644 --- a/docs/build/reference/qpar-auto-parallelizer.md +++ b/docs/build/reference/qpar-auto-parallelizer.md @@ -1,45 +1,43 @@ --- -description: "Learn more about: /Qpar (Auto-Parallelizer)" -title: "/Qpar (Auto-Parallelizer)" -ms.date: "11/04/2016" +description: "Learn more about: /Qpar (Auto-parallelizer)" +title: "/Qpar (Auto-parallelizer)" +ms.date: 02/22/2022 f1_keywords: ["VC.Project.VCCLCompilerTool.EnableParallelCodeGeneration"] ms.assetid: 33ecf49d-c0d5-4f34-bce3-84ff03f38918 --- -# /Qpar (Auto-Parallelizer) +# `/Qpar` (Auto-parallelizer) -Enables the [Auto-Parallelizer](../../parallel/auto-parallelization-and-auto-vectorization.md) feature of the compiler to automatically parallelize loops in your code. +Enables the [Auto-parallelizer](../../parallel/auto-parallelization-and-auto-vectorization.md) feature of the compiler to automatically parallelize loops in your code. ## Syntax -``` -/Qpar -``` +> **`/Qpar`** ## Remarks -When the compiler automatically parallelizes loops in code, it spreads computation across multiple processor cores. A loop is parallelized only if the compiler determines that it is legal to do so and that parallelization would improve performance. +When the compiler automatically parallelizes loops in code, it spreads computation across multiple processor cores. The compiler parallelizes a loop only if it determines that it's legal to do so and that parallelization would improve performance. -The `#pragma loop()` directives are available to help the optimizer parallelize specific loops. For more information, see [loop](../../preprocessor/loop.md). +The `#pragma loop()` directives are available to help the optimizer parallelize specific loops. For more information, see [`loop`](../../preprocessor/loop.md). -For information about how to enable output messages for the auto-parallelizer, see [/Qpar-report (Auto-Parallelizer Reporting Level)](qpar-report-auto-parallelizer-reporting-level.md). +For information about how to enable output messages for the auto-parallelizer, see [`/Qpar-report` (Auto-parallelizer reporting level)](qpar-report-auto-parallelizer-reporting-level.md). -### To set the /Qpar compiler option in Visual Studio +### To set the `/Qpar` 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. Select the **Configuration Properties** > **C/C++** > **Code Generation** property page. -1. In the **Additional Options** box, enter *`/Qpar`*. +1. Modify the **Enable Parallel Code Generation** property. Choose **OK** or **Apply** to save your changes. -### To set the /Qpar compiler option programmatically +### To set the `/Qpar` compiler option programmatically - Use the code example in . ## See also -[/Q Options (Low-Level Operations)](q-options-low-level-operations.md)
-[/Qpar-report (Auto-Parallelizer Reporting Level)](qpar-report-auto-parallelizer-reporting-level.md)
-[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md)
-[#pragma loop()](../../preprocessor/loop.md)
+[`/Q` options (Low-level operations)](q-options-low-level-operations.md)\ +[`/Qpar-report` (Auto-parallelizer reporting level)](qpar-report-auto-parallelizer-reporting-level.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md)\ +[`#pragma loop()`](../../preprocessor/loop.md)\ [Native code vectorization in Visual Studio](/archive/blogs/nativeconcurrency/auto-vectorizer-in-visual-studio-2012-overview) diff --git a/docs/build/reference/qspectre-jmp.md b/docs/build/reference/qspectre-jmp.md new file mode 100644 index 0000000000..b04d970480 --- /dev/null +++ b/docs/build/reference/qspectre-jmp.md @@ -0,0 +1,38 @@ +--- +title: "/Qspectre-jmp" +description: "Describes the Microsoft C/C++ compiler (MSVC) /Qspectre-jmp option." +ms.date: 11/30/2023 +helpviewer_keywords: ["/Qspectre-jmp"] +--- +# `/Qspectre-jmp` + +Causes the compiler to generate an `int3` instruction (software interrupt) after unconditional direct branches. This option extends the [`/Qspectre`](qspectre.md) flag and mitigates speculative execution side-channel attacks on unconditional direct branches. + +## Syntax + +> **/Qspectre-jmp** + +## Remarks + +**`/Qspectre-jmp`** causes the compiler to detect executable instructions following unconditional direct branches. An `int3` is inserted following unconditional direct branches to ensure that no instructions are speculatively executed beyond the branch. For example, the compiler mitigates `jmp addr` by adding an `int3` instruction following the `jmp` instruction as shown here: + +```asm +jmp addr +int3 +``` + +`/Qspectre-jmp` is off by default. It's supported for all optimization levels. + +### Set this compiler option programmatically + +To set this option programmatically, see [VCCLCompilerTool.AdditionalOptions property](/dotnet/api/microsoft.visualstudio.vcprojectengine.vcclcompilertool.additionaloptions). + +## See also + +[`/Qspectre`](qspectre.md)\ +[`/Qspectre-jmp`](qspectre-jmp.md)\ +[`/Qspectre-load`](qspectre-load.md)\ +[`/Qspectre-load-cf`](qspectre-load-cf.md)\ +[/Q options (Low-Level Operations)](q-options-low-level-operations.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/qspectre-load-cf.md b/docs/build/reference/qspectre-load-cf.md index 063058a264..0d0640ab81 100644 --- a/docs/build/reference/qspectre-load-cf.md +++ b/docs/build/reference/qspectre-load-cf.md @@ -15,7 +15,7 @@ Specifies compiler generation of serializing instructions for every control-flow ## Remarks -**/Qspectre-load-cf** causes the compiler to detect `JMP`, `RET`, and `CALL` control-flow instructions that load from memory, and to insert serializing instructions after the load. Where possible, these instructions are split into a load and a control flow transfer. The load is followed by an `LFENCE` to ensure the load is protected. There are cases where the compiler can't split instructions, such as the `JMP` instruction, so it uses an alternate mitigation technique. For example, the compiler mitigates `jmp [rax]` by adding instructions to load the target non-destructively before inserting an LFENCE, as shown here: +**/Qspectre-load-cf** causes the compiler to detect `JMP`, `RET`, and `CALL` control-flow instructions that load from memory, and to insert serializing instructions after the load. Where possible, these instructions are split into a load and a control flow transfer. The load is followed by an `LFENCE` to ensure the load is protected. There are cases where the compiler can't split instructions, such as the `JMP` instruction, so it uses an alternate mitigation technique. For example, the compiler mitigates `jmp [rax]` by adding instructions to load the target nondestructively before inserting an LFENCE, as shown here: ```asm xor rbx, [rax] @@ -44,6 +44,9 @@ The **/Qspectre-load-cf** option is available in Visual Studio 2019 version 16.5 ## See also +[`/Qspectre`](qspectre.md)\ +[`/Qspectre-jmp`](qspectre-jmp.md)\ +[`/Qspectre-load`](qspectre-load.md)\ [/Q options (Low-level operations)](q-options-low-level-operations.md)\ [MSVC compiler options](compiler-options.md)\ [MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/qspectre-load.md b/docs/build/reference/qspectre-load.md index 6d37e74ffd..728c2cad9b 100644 --- a/docs/build/reference/qspectre-load.md +++ b/docs/build/reference/qspectre-load.md @@ -14,7 +14,7 @@ Specifies compiler generation of serializing instructions for every load instruc ## Remarks -**/Qspectre-load** causes the compiler to detect loads from memory, and insert serializing instructions after them. Control flow instructions that load memory, including `RET` and `CALL`, are split into a load and a control flow transfer. The load is followed by an `LFENCE` to ensure the load is protected. There are cases where the compiler can't split control flow instructions, such as the `jmp` instruction, so it uses an alternate mitigation technique. For example, the compiler mitigates `jmp [rax]` by adding instructions to load the target non-destructively before inserting an LFENCE, as shown here: +**/Qspectre-load** causes the compiler to detect loads from memory, and insert serializing instructions after them. Control flow instructions that load memory, including `RET` and `CALL`, are split into a load and a control flow transfer. The load is followed by an `LFENCE` to ensure the load is protected. There are cases where the compiler can't split control flow instructions, such as the `jmp` instruction, so it uses an alternate mitigation technique. For example, the compiler mitigates `jmp [rax]` by adding instructions to load the target nondestructively before inserting an LFENCE, as shown here: ```asm xor rbx, [rax] @@ -43,6 +43,9 @@ The **/Qspectre-load** option is available in Visual Studio 2019 version 16.5 an ## See also +[`/Qspectre`](qspectre.md)\ +[`/Qspectre-jmp`](qspectre-jmp.md)\ +[`/Qspectre-load-cf`](qspectre-load-cf.md)\ [/Q options (Low-Level Operations)](q-options-low-level-operations.md)\ [MSVC compiler options](compiler-options.md)\ [MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/qspectre.md b/docs/build/reference/qspectre.md index 57079df912..2eace5222a 100644 --- a/docs/build/reference/qspectre.md +++ b/docs/build/reference/qspectre.md @@ -1,27 +1,29 @@ --- -description: "Learn more about: /Qspectre" title: "/Qspectre" -ms.date: "09/06/2019" +description: "Learn more about: /Qspectre" +ms.date: 07/02/2021 f1_keywords: ["VC.Project.VCCLCompilerTool.SpectreMitigation"] helpviewer_keywords: ["/Qspectre"] --- -# /Qspectre +# `/Qspectre` Specifies compiler generation of instructions to mitigate certain Spectre variant 1 security vulnerabilities. ## Syntax -> **/Qspectre** +> **`/Qspectre`** ## Remarks -The **/Qspectre** option is available in Visual Studio 2017 version 15.5.5 and later, and in Visual Studio 2015 Update 3 through [KB 4338871](https://support.microsoft.com/help/4338871/visual-studio-2015-update-3-spectre-variant-1-toolset-qspectre). It causes the compiler to insert instructions to mitigate certain [Spectre security vulnerabilities](https://spectreattack.com/spectre.pdf). These vulnerabilities are called *speculative execution side-channel attacks*. They affect many operating systems and modern processors, including processors from Intel, AMD, and ARM. +The **`/Qspectre`** option causes the compiler to insert instructions to mitigate certain [Spectre security vulnerabilities](https://spectreattack.com/spectre.pdf). These vulnerabilities are called *speculative execution side-channel attacks*. They affect many operating systems and modern processors, including processors from Intel, AMD, and ARM. -The **/Qspectre** option is off by default. +The **`/Qspectre`** option is available starting in Visual Studio 2017 version 15.5.5 and all later versions. It's available in Visual Studio 2015 Update 3 through [KB 4338871](https://support.microsoft.com/help/4338871/visual-studio-2015-update-3-spectre-variant-1-toolset-qspectre). -In its initial release, the **/Qspectre** option only worked on optimized code. In Visual Studio 2017 version 15.7 and later, the **/Qspectre** option is supported at all optimization levels. +The **`/Qspectre`** option is off by default. -Microsoft Visual C++ libraries are also available in versions with Spectre mitigation. The Spectre-mitigated libraries for Visual Studio 2017 and later can be downloaded in the Visual Studio Installer. They're found in the **Individual Components** tab under **Compilers, build tools, and runtimes**, and have "Libs for Spectre" in the name. Both DLL and static runtime libraries with mitigation enabled are available for a subset of the Visual C++ runtimes: VC++ start-up code, vcruntime140, msvcp140, concrt140, and vcamp140. The DLLs are supported for application-local deployment only. The contents of the Visual C++ 2017 and later Runtime Libraries Redistributable haven't been modified. +In its initial release, the **`/Qspectre`** option only worked on optimized code. Starting in Visual Studio 2017 version 15.7, the **`/Qspectre`** option is supported at all optimization levels. + +Several Microsoft C++ libraries are also available in versions with Spectre mitigation. The Spectre-mitigated libraries for Visual Studio can be downloaded in the Visual Studio Installer. They're found in the **Individual Components** tab under **Compilers, build tools, and runtimes**, and have "Libs for Spectre" in the name. Both DLL and static runtime libraries with mitigation enabled are available for a subset of the Visual C++ runtimes: VC++ start-up code, vcruntime140, msvcp140, concrt140, and vcamp140. The DLLs are supported for application-local deployment only. The contents of the Visual C++ Runtime Libraries Redistributable are unmodified. You can also install Spectre-mitigated libraries for MFC and ATL. They're found in the **Individual Components** tab under **SDKs, libraries, and frameworks**. @@ -30,41 +32,79 @@ You can also install Spectre-mitigated libraries for MFC and ATL. They're found ### Applicability -If your code operates on data that crosses a trust boundary, then we recommend you use the **/Qspectre** option to rebuild and redeploy your code to mitigate this issue as soon as possible. An example of such code is code that loads untrusted input that can affect execution. For example, code that makes remote procedure calls, parses untrusted input or files, or uses other local inter-process communication (IPC) interfaces. Standard sandboxing techniques may not be sufficient. Investigate your sandboxes carefully before you decide your code doesn't cross a trust boundary. +If your code operates on data that crosses a trust boundary, then we recommend you use the **`/Qspectre`** option to rebuild and redeploy your code to mitigate this issue as soon as possible. An example of such code is code that loads untrusted input that can affect execution. For example, code that makes remote procedure calls, parses untrusted input or files, or uses other local inter-process communication (IPC) interfaces. Standard sandboxing techniques may not be sufficient. Investigate your sandboxes carefully before you decide your code doesn't cross a trust boundary. ### Availability -The **/Qspectre** option is available in Visual Studio 2017 version 15.5.5, and in all updates to Microsoft C++ compilers (MSVC) made on or after January 23, 2018. Use the Visual Studio Installer to update the compiler, and to install the Spectre-mitigated libraries as individual components. The **/Qspectre** option is also available in Visual Studio 2015 Update 3 through a patch. For more information, see [KB 4338871](https://support.microsoft.com/help/4338871). +The **`/Qspectre`** option is available starting in Visual Studio 2017 version 15.5.5, and in all updates to Microsoft C/C++ compilers (MSVC) made on or after January 23, 2018. Use the Visual Studio Installer to update the compiler, and to install the Spectre-mitigated libraries as individual components. The **`/Qspectre`** option is also available in Visual Studio 2015 Update 3 through a patch. For more information, see [KB 4338871](https://support.microsoft.com/help/4338871). -All versions of Visual Studio 2017 version 15.5, and all Previews of Visual Studio 2017 version 15.6. include an undocumented option, **/d2guardspecload**. It's equivalent to the initial behavior of **/Qspectre**. You can use **/d2guardspecload** to apply the same mitigations to your code in these versions of the compiler. We recommend you update your build to use **/Qspectre** in compilers that support the option. The **/Qspectre** option may also support new mitigations in later versions of the compiler. +All versions of Visual Studio 2017 version 15.5, and all Previews of Visual Studio 2017 version 15.6. include an undocumented option, **`/d2guardspecload`**. It's equivalent to the initial behavior of **`/Qspectre`**. You can use **`/d2guardspecload`** to apply the same mitigations to your code in these versions of the compiler. We recommend you update your build to use **`/Qspectre`** in compilers that support the option. The **`/Qspectre`** option may also support new mitigations in later versions of the compiler. ### Effect -The **/Qspectre** option outputs code to mitigate Specter variant 1, Bounds Check Bypass, [CVE-2017-5753](https://nvd.nist.gov/vuln/detail/CVE-2017-5753). It works by insertion of instructions that act as a speculative code execution barrier. The specific instructions used to mitigate processor speculation depend upon the processor and its micro-architecture, and may change in future versions of the compiler. +The **`/Qspectre`** option outputs code to mitigate Specter variant 1, Bounds Check Bypass, [CVE-2017-5753](https://nvd.nist.gov/vuln/detail/CVE-2017-5753). It works by insertion of instructions that act as a speculative code execution barrier. The specific instructions used to mitigate processor speculation depend upon the processor and its micro-architecture, and may change in future versions of the compiler. -When you enable the **/Qspectre** option, the compiler attempts to identify instances where speculative execution may bypass bounds checks. That's where it inserts the barrier instructions. It's important to be aware of the limits to the analysis that a compiler can do to identify instances of variant 1. As such, there's no guarantee that all possible instances of variant 1 are instrumented under **/Qspectre**. +When you enable the **`/Qspectre`** option, the compiler attempts to identify instances where speculative execution may bypass bounds checks. That's where it inserts the barrier instructions. It's important to be aware of the limits to the analysis that a compiler can do to identify instances of variant 1. As such, there's no guarantee that all possible instances of variant 1 are instrumented under **`/Qspectre`**. ### Performance impact -The performance impact of **/Qspectre** appeared to be negligible in several sizable code bases. However, there are no guarantees that performance of your code under **/Qspectre** remains unaffected. You should benchmark your code to determine the effect of the option on performance. If you know that the mitigation isn't required in a performance-critical block or loop, You can selectively disable the mitigation by use of a [__declspec(spectre(nomitigation))](../../cpp/spectre.md) directive. This directive isn't available in compilers that only support the **/d2guardspecload** option. +The effect of **`/Qspectre`** on performance appeared to be negligible in several sizable code bases. However, there are no guarantees that performance of your code under **`/Qspectre`** remains unaffected. You should benchmark your code to determine the effect of the option on performance. If you know that the mitigation isn't required in a performance-critical block or loop, you can selectively disable the mitigation by use of a [`__declspec(spectre(nomitigation))`](../../cpp/spectre.md) directive. This directive isn't available in compilers that only support the **`/d2guardspecload`** option. ### Required libraries -The **/Qspectre** compiler option generates code that implicitly links versions of the runtime libraries built to provide Spectre mitigations. These libraries are optional components that must be installed by using the Visual Studio Installer: +The **`/Qspectre`** compiler option mitigates issues in your own code. For greater protection, we strongly recommend you also use libraries built to provide Spectre mitigations. Several of the Microsoft runtime libraries are available with Spectre mitigations. + +::: moniker range=">=msvc-150" + +These libraries are optional components that must be installed by using the Visual Studio Installer: - MSVC version *version_numbers* Libs for Spectre \[(x86 and x64) | (ARM) | (ARM64)] - Visual C++ ATL for \[(x86/x64) | ARM | ARM64] with Spectre Mitigations - Visual C++ MFC for \[x86/x64 | ARM | ARM64] with Spectre Mitigations -If you build your code by using **/Qspectre** and these libraries aren't installed, the build system reports **warning MSB8038: Spectre mitigation is enabled but Spectre mitigated libraries are not found**. If your MFC or ATL code fails to build, and the linker reports an error such as **fatal error LNK1104: cannot open file 'oldnames.lib'**, these missing libraries may be the cause. +::: moniker-end + +::: moniker range=">=msvc-160" + +The default MSBuild-based project system in the Visual Studio IDE lets you specify a [Spectre Mitigation](./c-cpp-prop-page.md#spectre-mitigation) property for your projects. This property sets the **`/Qspectre`** compiler option and changes the library paths to link the Spectre-mitigated runtime libraries. If these libraries aren't installed when you build your code, the build system reports warning [MSB8040](/visualstudio/msbuild/errors/msb8040). If your MFC or ATL code fails to build, and the linker reports an error such as "fatal error LNK1104: cannot open file 'oldnames.lib'", these missing libraries may be the cause. + +::: moniker-end + +::: moniker range="msvc-150" + +The default MSBuild-based project system in the Visual Studio IDE lets you specify a [Spectre Mitigation](./c-cpp-prop-page.md#spectre-mitigation) property for your projects. This property sets the **`/Qspectre`** compiler option and changes the library paths to link the Spectre-mitigated runtime libraries. If these libraries aren't installed when you build your code, the build system reports warning MSB8038: "Spectre mitigation is enabled but Spectre mitigated libraries are not found." If your MFC or ATL code fails to build, and the linker reports an error such as "fatal error LNK1104: cannot open file 'oldnames.lib'", these missing libraries may be the cause. + +::: moniker-end + +::: moniker range=">=msvc-150" + +There are several ways to specify the Spectre-mitigated libraries to the build command line. You can specify the path to the Spectre-mitigated libraries by using the [`/LIBPATH`](./libpath-additional-libpath.md) linker option to make them the default libraries. You can use the [`/NODEFAULTLIB`](./nodefaultlib-ignore-libraries.md) linker option and explicitly link the Spectre-mitigated libraries. Or, you can set the `LIBPATH` environment variable to include the path to the Spectre-mitigated libraries for your target platform. One way to set this path in the environment is to use a developer command prompt set up by using the `spectre_mode` option. For more information, see [Use the developer tools in an existing command window](../building-on-the-command-line.md#use-the-developer-tools-in-an-existing-command-window). + +::: moniker-end + +::: moniker range="msvc-140" + +Spectre-mitigated runtime libraries for x86, x64 and ARM platforms are available as part of the patch available through [KB 4338871](https://support.microsoft.com/help/4338871). By default, these libraries are installed in the following directories: + +- x86: *`C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\lib\spectre`* +- x64: *`C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\lib\spectre\amd64`* +- ARM: *`C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\lib\spectre\arm`* + +There are several ways to specify the Spectre-mitigated libraries to the build command line. You can specify the path to the Spectre-mitigated libraries by using the [`/LIBPATH`](./libpath-additional-libpath.md) linker option to make them the default libraries. You can use the [`/NODEFAULTLIB`](./nodefaultlib-ignore-libraries.md) linker option and explicitly link the Spectre-mitigated libraries. Or, you can set the `LIBPATH` environment variable to include the path to the Spectre-mitigated libraries for your target architecture. For more information, see [Use the Microsoft C++ toolset from the command line](../building-on-the-command-line.md). + +::: moniker-end ### Additional information -For more information, see the official [Microsoft Security Advisory ADV180002, Guidance to mitigate speculative execution side-channel vulnerabilities](https://portal.msrc.microsoft.com/en-US/security-guidance/advisory/ADV180002). Guidance is also available from Intel, [Speculative Execution Side Channel Mitigations](https://software.intel.com/sites/default/files/managed/c5/63/336996-Speculative-Execution-Side-Channel-Mitigations.pdf), and ARM, [Cache Speculation Side-channels](https://developer.arm.com/-/media/Files/pdf/Cache_Speculation_Side-channels.pdf). For a Windows-specific overview of Spectre and Meltdown mitigations, see [Understanding the performance impact of Spectre and Meltdown mitigations on Windows Systems](https://www.microsoft.com/security/blog/2018/01/09/understanding-the-performance-impact-of-spectre-and-meltdown-mitigations-on-windows-systems/). For an overview of Spectre vulnerabilities addressed by the MSVC mitigations, see [Spectre mitigations in MSVC](https://devblogs.microsoft.com/cppblog/spectre-mitigations-in-msvc./) on the C++ Team Blog. +For more information, see the official [Microsoft Security Advisory ADV180002, Guidance to mitigate speculative execution side-channel vulnerabilities](https://msrc.microsoft.com/update-guide/vulnerability/ADV180002). Guidance is also available from Intel, [Speculative Execution Side Channel Mitigations](https://software.intel.com/sites/default/files/managed/c5/63/336996-Speculative-Execution-Side-Channel-Mitigations.pdf), and ARM, [Cache Speculation Side-channels](https://developer.arm.com/-/media/Files/pdf/Cache_Speculation_Side-channels.pdf). + +For a Windows-specific overview of Spectre and Meltdown mitigations, see [Understanding the performance impact of Spectre and Meltdown mitigations on Windows Systems](https://www.microsoft.com/security/blog/2018/01/09/understanding-the-performance-impact-of-spectre-and-meltdown-mitigations-on-windows-systems/). + +For an overview of Spectre vulnerabilities addressed by the MSVC mitigations, see [Spectre mitigations in MSVC](https://devblogs.microsoft.com/cppblog/spectre-mitigations-in-msvc./) on the C++ Team Blog. ### To set this compiler option in the Visual Studio development environment -::: moniker range="msvc-160" +::: moniker range=">=msvc-150" 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). @@ -74,13 +114,17 @@ For more information, see the official [Microsoft Security Advisory ADV180002, G ::: moniker-end -::: moniker range="<=msvc-150" +::: moniker range="msvc-140" 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. Enter the **/Qspectre** compiler option in the **Additional Options** box. Choose **OK** to apply the change. +1. Enter the *`/Qspectre`* compiler option in the **Additional Options** box. Choose **Apply** to apply the change. + +1. Select the **Configuration Properties** > **Linker** > **General** property page. + +1. For each Platform in your project properties, edit the **Additional Library Directories** property. Set the path to the Spectre-mitigated runtime library directory for the target platform, and then choose **Apply** to apply the change. When done, choose **OK**. ::: moniker-end @@ -90,6 +134,9 @@ For more information, see the official [Microsoft Security Advisory ADV180002, G ## See also -[/Q Options (Low-Level Operations)](q-options-low-level-operations.md)
-[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) +[`/Qspectre-jmp`](qspectre-jmp.md)\ +[`/Qspectre-load`](qspectre-load.md)\ +[`/Qspectre-load-cf`](qspectre-load-cf.md)\ +[`/Q` options (Low-level operations)](q-options-low-level-operations.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/recommended-tags-for-documentation-comments-visual-cpp.md b/docs/build/reference/recommended-tags-for-documentation-comments-visual-cpp.md index 140a33b14f..d62d51b252 100644 --- a/docs/build/reference/recommended-tags-for-documentation-comments-visual-cpp.md +++ b/docs/build/reference/recommended-tags-for-documentation-comments-visual-cpp.md @@ -1,43 +1,43 @@ --- -description: "Learn more about: Recommended Tags for Documentation Comments" -title: "Recommended Tags for Documentation Comments (C++ documentation comments)" -ms.date: "11/04/2016" +description: "Learn more about: Recommended tags for documentation comments" +title: "Recommended tags for documentation comments (C++ documentation comments)" +ms.date: 12/03/2021 ms.assetid: 6548e798-5235-4a38-9482-bdc7b88f40a9 --- -# Recommended Tags for Documentation Comments +# Recommended tags for documentation comments -The MSVC compiler will process documentation comments in your code and creates an .xdc file for each compiland, and xdcmake.exe will process the .xdc files to an .xml file. Processing the .xml file to create documentation is a detail that needs to be implemented at your site. +The MSVC compiler processes documentation comments in your code to create an XDC file for each compiled source file. Then, xdcmake.exe processes the XDC files to create an XML documentation file. Processing the XML file to create documentation is a detail that needs to be implemented at your site. Tags are processed on constructs such as types and type members. Tags must immediately precede types or members. > [!NOTE] -> Documentation comments cannot be applied to a namespace or on out of line definition for properties and events; documentation comments must on the in-class declarations. +> Documentation comments can't be applied to a namespace or on out of line definitions for properties and events; documentation comments must be on the in-class declarations. The compiler will process any tag that is valid XML. The following tags provide commonly used functionality in user documentation: -[``](c-visual-cpp.md) -[``](code-visual-cpp.md) -[``](example-visual-cpp.md) -[``](exception-visual-cpp.md)1 -[``](include-visual-cpp.md)1 -[``](list-visual-cpp.md) -[``](para-visual-cpp.md) -[``](param-visual-cpp.md)1 -[``](paramref-visual-cpp.md)1 -[``](permission-visual-cpp.md)1 -[``](remarks-visual-cpp.md) -[``](returns-visual-cpp.md) -[``](see-visual-cpp.md)1 -[``](seealso-visual-cpp.md)1 -[``](summary-visual-cpp.md) +[``](c-visual-cpp.md)\ +[``](code-visual-cpp.md)\ +[``](example-visual-cpp.md)\ +[``](exception-visual-cpp.md)1\ +[``](include-visual-cpp.md)1\ +[``](list-visual-cpp.md)\ +[``](para-visual-cpp.md)\ +[``](param-visual-cpp.md)1\ +[``](paramref-visual-cpp.md)1\ +[``](permission-visual-cpp.md)1\ +[``](remarks-visual-cpp.md)\ +[``](returns-visual-cpp.md)\ +[``](see-visual-cpp.md)1\ +[``](seealso-visual-cpp.md)1\ +[``](summary-visual-cpp.md)\ [``](value-visual-cpp.md) 1. Compiler verifies syntax. -In the current release, the MSVC compiler does not support ``, a tag that is supported by other Visual Studio compilers. Visual C++ may support `` in a future release. +In the current release, the MSVC compiler doesn't support ``, a tag that's supported by other Visual Studio compilers. Visual C++ may support `` in a future release. ## See also -[XML Documentation](xml-documentation-visual-cpp.md) +[XML documentation](xml-documentation-visual-cpp.md) diff --git a/docs/build/reference/recursion-macros.md b/docs/build/reference/recursion-macros.md deleted file mode 100644 index e76a1f02b7..0000000000 --- a/docs/build/reference/recursion-macros.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: "Recursion macros" -description: "Describes the macros you use to call NMAKE in recursive sessions." -ms.date: "11/20/2019" -helpviewer_keywords: ["NMAKE program, recursion macros", "recursion macros", "macros, recursion"] -ms.assetid: c53e5ae7-619e-46b1-bdc2-86d8c7798b1d -no-loc: [MAKE, MAKEDIR, MAKEFLAGS] ---- -# Recursion macros - -Use recursion macros to call NMAKE recursively. Recursive sessions inherit command-line and environment-variable macros and Tools.ini information. They don't inherit makefile-defined inference rules or `.SUFFIXES` and `.PRECIOUS` specifications. There are three ways to pass macros to a recursive NMAKE session: Set an environment variable with a :::no-loc text="SET"::: command before the recursive call. Define a macro in the command for the recursive call. Or, define a macro in Tools.ini. - -|Macro|Definition| -|-----------|----------------| -|**MAKE**|Command used originally to invoke NMAKE.

The `$(MAKE)` macro gives the full path to nmake.exe.| -|**MAKEDIR**|Current directory when NMAKE was invoked.| -|**MAKEFLAGS**|Options currently in effect. Use as `/$(MAKEFLAGS)`. The **/F** option isn't included.| - -## See also - -[Special NMAKE macros](special-nmake-macros.md) diff --git a/docs/build/reference/remarks-visual-cpp.md b/docs/build/reference/remarks-visual-cpp.md index 632ce84deb..0c455a623e 100644 --- a/docs/build/reference/remarks-visual-cpp.md +++ b/docs/build/reference/remarks-visual-cpp.md @@ -1,29 +1,29 @@ --- -description: "Learn more about: <remarks>" -title: "<remarks> (C++ documentation comments)" -ms.date: "11/04/2016" +description: "Learn more about: XML documentation tag " +title: " (C++ documentation comments)" +ms.date: 12/03/2021 f1_keywords: [""] helpviewer_keywords: [" C++ XML tag", "remarks C++ XML tag"] ms.assetid: c820083b-3192-40ab-9ec8-1472c55b4247 --- -# <remarks> +# `` documentation tag -The \ tag is used to add information about a type, supplementing the information specified with [\](summary-visual-cpp.md). This information is displayed in the [Object Browser](/visualstudio/ide/viewing-the-structure-of-code) and in the Code Comment Web Report. +The `` tag is used to add information about a type, supplementing the information specified with [``](summary-visual-cpp.md). This information is displayed in the [Object Browser](/visualstudio/ide/viewing-the-structure-of-code) and in the Code Comment Web Report. ## Syntax -``` -description +```cpp +/// description ``` -#### Parameters +### Parameters -*description*
+*`description`*\ A description of the member. ## Remarks -Compile with [/doc](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. +Compile with [`/doc`](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. ## Example @@ -45,4 +45,4 @@ public ref class MyClass {}; ## See also -[XML Documentation](xml-documentation-visual-cpp.md) +[XML documentation](xml-documentation-visual-cpp.md) diff --git a/docs/build/reference/resources-property-pages.md b/docs/build/reference/resources-property-pages.md index 0f09208f2b..cea6e5ba33 100644 --- a/docs/build/reference/resources-property-pages.md +++ b/docs/build/reference/resources-property-pages.md @@ -14,7 +14,6 @@ f1_keywords: - VC.Project.VCResourceCompilerTool.SuppressStartupBanner - VC.Project.VCResourceCompilerTool.ResourceOutputFileName - VC.Project.VCResourceCompilerTool.NullTerminateStrings - - vc.project.AdditionalOptionsPage --- # Resources property page diff --git a/docs/build/reference/return-value-of-cl-exe.md b/docs/build/reference/return-value-of-cl-exe.md index 383007f232..ceb9ff7972 100644 --- a/docs/build/reference/return-value-of-cl-exe.md +++ b/docs/build/reference/return-value-of-cl-exe.md @@ -11,7 +11,7 @@ cl.exe returns zero for success (no errors) and non-zero otherwise. The return value of cl.exe can be useful if you are compiling from a script, powershell, .cmd, or .bat file. We recommend that you capture the output of the compiler in case there are errors or warnings, so that you can resolve them. -There are too many possible error exit codes for cl.exe to list them all. You can look up an error code in the winerror.h or ntstatus.h files included in the Windows Software Development Kit in the %ProgramFiles(x86)%\Windows Kits\\version\Include\shared\ directory. Error codes returned in decimal must be converted to hexadecimal for search. For example, an error code of -1073741620 converted to hexadecimal is 0xC00000CC. This error is found in ntstatus.h, where the corresponding message is "The specified share name cannot be found on the remote server." For a downloadable list of Windows error codes, see [[MS-ERREF]: Windows Error Codes](/openspecs/windows_protocols/MS-ERREF). +There are too many possible error exit codes for cl.exe to list them all. You can look up an error code in the winerror.h or ntstatus.h files included in the Windows Software Development Kit in the %ProgramFiles(x86)%\Windows Kits\\version\Include\shared\ directory. Error codes returned in decimal must be converted to hexadecimal for search. For example, an error code of -1073741620 converted to hexadecimal is 0xC00000CC. This error is found in ntstatus.h, where the corresponding message is "The specified share name cannot be found on the remote server." For a downloadable list of Windows error codes, see [`[MS-ERREF]` Windows Error Codes](/openspecs/windows_protocols/MS-ERREF). You can also use the error lookup utility in Visual Studio to find out what a compiler error message means. In a Visual Studio command shell, enter **errlook.exe** to start the utility; or in the Visual Studio IDE, on the menu bar, choose **Tools**, **Error Lookup**. Enter the error value to find the descriptive text associated with the error. For more information see [ERRLOOK Reference](errlook-reference.md). diff --git a/docs/build/reference/returns-visual-cpp.md b/docs/build/reference/returns-visual-cpp.md index 4319af4341..9ed2a4ee6d 100644 --- a/docs/build/reference/returns-visual-cpp.md +++ b/docs/build/reference/returns-visual-cpp.md @@ -1,29 +1,29 @@ --- -description: "Learn more about: <returns>" -title: "<returns> (C++ Documentation Comments)" -ms.date: "11/04/2016" +description: "Learn more about: XML documentation tag " +title: " (C++ Documentation Comments)" +ms.date: 12/03/2021 f1_keywords: [""] helpviewer_keywords: ["returns C++ XML tag", " C++ XML tag"] ms.assetid: 5e3b0ed9-838d-4953-a93e-76d2d0a19fb9 --- -# <returns> +# `` documentation tag -The \ tag should be used in the comment for a method declaration to describe the return value. +The `` tag should be used in the comment for a method declaration to describe the return value. ## Syntax -``` -description +```cpp +/// description ``` -#### Parameters +### Parameters -*description*
+*`description`*\ A description of the return value. ## Remarks -Compile with [/doc](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. +Compile with [`/doc`](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. ## Example @@ -42,4 +42,4 @@ public: ## See also -[XML Documentation](xml-documentation-visual-cpp.md) +[XML documentation](xml-documentation-visual-cpp.md) diff --git a/docs/build/reference/reusing-inline-files.md b/docs/build/reference/reusing-inline-files.md deleted file mode 100644 index cdc9233edd..0000000000 --- a/docs/build/reference/reusing-inline-files.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -description: "Learn more about: Reusing Inline Files" -title: "Reusing Inline Files" -ms.date: "11/04/2016" -helpviewer_keywords: ["inline files, reusing NMAKE", "revising inline files", "NMAKE program, inline files"] -ms.assetid: d42dbffb-2cef-4ccb-9a1f-20b8ef81481c ---- -# Reusing Inline Files - -To reuse an inline file, specify <<*filename* where the file is defined and first used, then reuse *filename* without << later in the same or another command. The command to create the inline file must run before all commands that use the file. - -## See also - -[Inline Files in a Makefile](inline-files-in-a-makefile.md) diff --git a/docs/build/reference/running-lib.md b/docs/build/reference/running-lib.md index f469017355..0bfac11edc 100644 --- a/docs/build/reference/running-lib.md +++ b/docs/build/reference/running-lib.md @@ -32,7 +32,7 @@ An option consists of an option specifier, which is either a dash (**-**) or a f The following options apply to all modes of LIB: -> **/ERRORREPORT** \[**NONE** | **PROMPT** | **QUEUE** | **SEND**] +> **/ERRORREPORT** \[**NONE** \| **PROMPT** \| **QUEUE** \| **SEND**] The /ERRORREPORT option is deprecated. Starting in Windows Vista, error reporting is controlled by [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings. diff --git a/docs/build/reference/running-nmake.md b/docs/build/reference/running-nmake.md index be992ac71e..e9633b59a9 100644 --- a/docs/build/reference/running-nmake.md +++ b/docs/build/reference/running-nmake.md @@ -1,65 +1,66 @@ --- title: "Running NMAKE" description: "Learn about running NMAKE." -ms.date: "02/09/2020" +ms.date: 09/30/2021 helpviewer_keywords: ["targets, building", "response files, NMAKE", "targets", "command files", "NMAKE program, targets", "NMAKE program, running", "command files, NMAKE"] -ms.assetid: 0421104d-8b7b-4bf3-86c1-928d9b7c1a8c --- # Running NMAKE ## Syntax -> **NMAKE** [*option* ...] [*macros* ...] [*targets* ...] [**\@**_command-file_ ...] +> **`NMAKE`** [*option* ...] [*macros* ...] [*targets* ...] [**`@`**_command-file_ ...] ## Remarks -NMAKE builds only specified *targets* or, when none is specified, the first target in the makefile. The first makefile target can be a [pseudotarget](description-blocks.md#pseudotargets) that builds other targets. NMAKE uses makefiles specified with **/F**, or if **/F** isn't specified, the Makefile file in the current directory. If no makefile is specified, it uses inference rules to build command-line *targets*. +NMAKE must run in a Developer Command Prompt window. A Developer Command Prompt window has the environment variables set for the tools, libraries, and include file paths required to build at the command line. For details on how to open a Developer Command Prompt window, see [Use the MSVC toolset from the command line](../building-on-the-command-line.md). + +NMAKE builds only specified *targets* or, when none is specified, the first target in the makefile. The first makefile target can be a [pseudotarget](description-blocks.md#pseudotargets) that builds other targets. NMAKE uses makefiles specified with **`/F`**, or if **`/F`** isn't specified, the Makefile file in the current directory. If no makefile is specified, it uses inference rules to build command-line *targets*. The *command-file* text file (or response file) contains command-line input. Other input can precede or follow \@*command-file*. A path is permitted. In *command-file*, line breaks are treated as spaces. Enclose macro definitions in quotation marks if they contain spaces. -## NMAKE Options +## NMAKE options -NMAKE options are described in the following table. Options are preceded by either a slash (`/`) or a dash (`-`), and aren't case-sensitive. Use [`!CMDSWITCHES`](makefile-preprocessing-directives.md) to change option settings in a makefile or in Tools.ini. +NMAKE options are described in the following table. Options are preceded by either a slash (`/`) or a dash (`-`), and aren't case-sensitive. Use [`!CMDSWITCHES`](makefile-preprocessing.md#makefile-preprocessing-directives) to change option settings in a makefile or in *`Tools.ini`*. | Option | Purpose | -| ------------ | ------------- | -| **/A** | Forces build of all evaluated targets, even if not out-of-date compared to dependents. Doesn't force builds of unrelated targets. | -| **/B** | Forces build even if timestamps are equal. Recommended only for fast systems (resolution of two seconds or less). | -| **/C** | Suppresses default output, including nonfatal NMAKE errors or warnings, timestamps, and NMAKE copyright message. Suppresses warnings issued by **/K**. | -| **/D** | Displays timestamps of each evaluated target and dependent and a message when a target doesn't exist. Useful with **/P** for debugging a makefile. Use `!CMDSWITCHES` to set or clear **/D** for part of a makefile. | -| **/E** | Causes environment variables to override makefile macro definitions. | -| **/ERRORREPORT** [ **NONE** | **PROMPT** | **QUEUE** | **SEND** ] | Deprecated. [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings control reporting. | -| **/F** *filename* | Specifies *filename* as a makefile. Spaces or tabs can precede *filename*. Specify **/F** once for each makefile. To supply a makefile from standard input, specify a dash (`-`) for *filename*, and end keyboard input with either **F6** or **CTRL+Z**. | -| **/G** | Displays the makefiles included with the `!INCLUDE` directive. For more information, see [Makefile Preprocessing Directives](makefile-preprocessing-directives.md). | -| **/HELP**, **/?** | Displays a brief summary of NMAKE command-line syntax. | -| **/I** | Ignores exit codes from all commands. To set or clear **/I** for part of a makefile, use `!CMDSWITCHES`. To ignore exit codes for part of a makefile, use a dash (`-`) command modifier or [`.IGNORE`](dot-directives.md). Overrides **/K** if both are specified. | -| **/K** | Continues building unrelated dependencies, if a command returns an error. Also issues a warning and returns an exit code of 1. By default, NMAKE halts if any command returns a nonzero exit code. Warnings from **/K** are suppressed by **/C**; **/I** overrides **/K** if both are specified. | -| **/N** | Displays but doesn't execute commands; preprocessing commands are executed. Doesn't display commands in recursive NMAKE calls. Useful for debugging makefiles and checking timestamps. To set or clear **/N** for part of a makefile, use `!CMDSWITCHES`. | -| **/NOLOGO** | Suppresses the NMAKE copyright message. | -| **/P** | Displays information (macro definitions, inference rules, targets, [`.SUFFIXES`](dot-directives.md) list) to standard output, and then runs the build. If no makefile or command-line target exists, it displays information only. Use with **/D** to debug a makefile. | -| **/Q** | Checks timestamps of targets; doesn't run the build. Returns a zero exit code if all targets are up to date, and a nonzero exit code if any target is out of date. Preprocessing commands are executed. Useful when running NMAKE from a batch file. | -| **/R** | Clears the `.SUFFIXES` list and ignores inference rules and macros that are defined in the Tools.ini file or that are predefined. | -| **/S** | Suppresses display of executed commands. To suppress display in part of a makefile, use the **\@** command modifier or [`.SILENT`](dot-directives.md). To set or clear **/S** for part of a makefile, use `!CMDSWITCHES`. | -| **/T** | Updates timestamps of command-line targets (or first makefile target) and executes preprocessing commands but doesn't run the build. | -| **/U** | Must be used in conjunction with **/N**. Dumps inline NMAKE files so that the **/N** output can be used as a batch file. | -| **/X** *filename* | Sends NMAKE error output to *filename* instead of standard error. Spaces or tabs can precede *filename*. To send error output to standard output, specify a dash (`-`) for *filename*. Doesn't affect output from commands to standard error. | -| **/Y** | Disables batch-mode inference rules. When this option is selected, all batch-mode inference rules are treated as regular inference rules. | +|--|--| +| **`/A`** | Forces build of all evaluated targets, even if not out-of-date compared to dependents. Doesn't force builds of unrelated targets. | +| **`/B`** | Forces build even if timestamps are equal. Recommended only for fast systems (resolution of two seconds or less). | +| **`/C`** | Suppresses default output, including nonfatal NMAKE errors or warnings, timestamps, and NMAKE copyright message. Suppresses warnings issued by **`/K`**. | +| **`/D`** | Displays timestamps of each evaluated target and dependent and a message when a target doesn't exist. Useful with **`/P`** for debugging a makefile. Use `!CMDSWITCHES` to set or clear **`/D`** for part of a makefile. | +| **`/E`** | Causes environment variables to override makefile macro definitions. | +| **`/ERRORREPORT`** [ **`NONE`** \| **`PROMPT`** \| **`QUEUE`** \| **`SEND`** ] | Deprecated. [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings control reporting. | +| **`/F`** *filename* | Specifies *filename* as a makefile. Spaces or tabs can precede *filename*. Specify **`/F`** once for each makefile. To supply a makefile from standard input, specify a dash (`-`) for *filename*, and end keyboard input with either **F6** or **CTRL+Z**. | +| **`/G`** | Displays the makefiles included with the `!INCLUDE` directive. For more information, see [Makefile preprocessing directives](makefile-preprocessing.md#makefile-preprocessing-directives). | +| **`/HELP`**, **`/?`** | Displays a brief summary of NMAKE command-line syntax. | +| **`/I`** | Ignores exit codes from all commands. To set or clear **`/I`** for part of a makefile, use `!CMDSWITCHES`. To ignore exit codes for part of a makefile, use a dash (`-`) command modifier or [`.IGNORE`](dot-directives.md). Overrides **`/K`** if both are specified. | +| **`/K`** | Continues building unrelated dependencies, if a command returns an error. Also issues a warning and returns an exit code of 1. By default, NMAKE halts if any command returns a nonzero exit code. Warnings from **`/K`** are suppressed by **`/C`**; **`/I`** overrides **`/K`** if both are specified. | +| **`/N`** | Displays but doesn't execute commands; preprocessing commands are executed. Doesn't display commands in recursive NMAKE calls. Useful for debugging makefiles and checking timestamps. To set or clear **`/N`** for part of a makefile, use `!CMDSWITCHES`. | +| **`/NOLOGO`** | Suppresses the NMAKE copyright message. | +| **`/P`** | Displays information (macro definitions, inference rules, targets, [`.SUFFIXES`](dot-directives.md) list) to standard output, and then runs the build. If no makefile or command-line target exists, it displays information only. Use with **`/D`** to debug a makefile. | +| **`/Q`** | Checks timestamps of targets; doesn't run the build. Returns a zero exit code if all targets are up to date, and a nonzero exit code if any target is out of date. Preprocessing commands are executed. Useful when running NMAKE from a batch file. | +| **`/R`** | Clears the `.SUFFIXES` list and ignores inference rules and macros that are defined in the *`Tools.ini`* file or that are predefined. | +| **`/S`** | Suppresses display of executed commands. To suppress display in part of a makefile, use the **`@`** command modifier or [`.SILENT`](dot-directives.md). To set or clear **`/S`** for part of a makefile, use `!CMDSWITCHES`. | +| **`/T`** | Updates timestamps of command-line targets (or first makefile target) and executes preprocessing commands but doesn't run the build. | +| **`/U`** | Must be used in conjunction with **`/N`**. Dumps inline NMAKE files so that the **`/N`** output can be used as a batch file. | +| **`/X`** *filename* | Sends NMAKE error output to *filename* instead of standard error. Spaces or tabs can precede *filename*. To send error output to standard output, specify a dash (`-`) for *filename*. Doesn't affect output from commands to standard error. | +| **`/Y`** | Disables batch-mode inference rules. When this option is selected, all batch-mode inference rules are treated as regular inference rules. | ## Tools.ini and NMAKE -NMAKE reads Tools.ini before it reads makefiles, unless **/R** is used. It looks for Tools.ini first in the current directory, and then in the directory specified by the INIT environment variable. The section for NMAKE settings in the initialization file begins with `[NMAKE]` and can contain any makefile information. Specify a comment on a separate line beginning with a number sign (`#`). +NMAKE reads *`Tools.ini`* before it reads makefiles, unless **`/R`** is used. It looks for *`Tools.ini`* first in the current directory, and then in the directory specified by the INIT environment variable. The section for NMAKE settings in the initialization file begins with `[NMAKE]` and can contain any makefile information. Specify a comment on a separate line beginning with a number sign (**`#`**). ## Exit Codes from NMAKE NMAKE returns the following exit codes: | Code | Meaning | -| ---------- | ------------- | +|--|--| | 0 | No error (possibly a warning) | -| 1 | Incomplete build (issued only when **/K** is used) | +| 1 | Incomplete build (issued only when **`/K`** is used) | | 2 | Program error, possibly caused by one of these issues:
- A syntax error in the makefile
- An error or exit code from a command
- An interruption by the user | | 4 | System error — out of memory | -| 255 | Target isn't up to date (issued only when **/Q** is used) | +| 255 | Target isn't up to date (issued only when **`/Q`** is used) | ## See also diff --git a/docs/build/reference/safeseh-image-has-safe-exception-handlers.md b/docs/build/reference/safeseh-image-has-safe-exception-handlers.md index 23f40109f4..40de4d33be 100644 --- a/docs/build/reference/safeseh-image-has-safe-exception-handlers.md +++ b/docs/build/reference/safeseh-image-has-safe-exception-handlers.md @@ -1,34 +1,37 @@ --- description: "Learn more about: /SAFESEH (Image has Safe Exception Handlers)" title: "/SAFESEH (Image has Safe Exception Handlers)" -ms.date: "11/04/2016" -f1_keywords: ["/SAFESEH"] +ms.date: 09/19/2022 +f1_keywords: ["VC.Project.VCLinkerTool.ImageHasSafeExceptionHandlers", "/SAFESEH"] helpviewer_keywords: ["/SAFESEH linker option", "-SAFESEH linker option", "SAFESEH linker option"] ms.assetid: 7722ff99-b833-4c65-a855-aaca902ffcb7 --- -# /SAFESEH (Image has Safe Exception Handlers) +# `/SAFESEH` (Image has Safe Exception Handlers) -``` -/SAFESEH[:NO] -``` +When **`/SAFESEH`** is specified, the linker only produces an image if it can also produce a table of the image's safe exception handlers. This table specifies to the operating system which exception handlers are valid for the image. -When **/SAFESEH** is specified, the linker will only produce an image if it can also produce a table of the image's safe exception handlers. This table specifies for the operating system which exception handlers are valid for the image. +## Syntax -**/SAFESEH** is only valid when linking for x86 targets. **/SAFESEH** is not supported for platforms that already have the exception handlers noted. For example, on x64 and ARM, all exception handlers are noted in the PDATA. ML64.exe has support for adding annotations that emit SEH information (XDATA and PDATA) into the image, allowing you to unwind through ml64 functions. See [MASM for x64 (ml64.exe)](../../assembler/masm/masm-for-x64-ml64-exe.md) for more information. +> **`/SAFESEH`**\ +> **`/SAFESEH:NO`** -If **/SAFESEH** is not specified, the linker will produce an image with a table of safe exceptions handlers if all modules are compatible with the safe exception handling feature. If any modules were not compatible with safe exception handling feature, the resulting image will not contain a table of safe exception handlers. If [/SUBSYSTEM](subsystem-specify-subsystem.md) specifies WINDOWSCE or one of the EFI_* options, the linker will not attempt to produce an image with a table of safe exceptions handlers, as neither of those subsystems can make use of the information. +## Remarks -If **/SAFESEH:NO** is specified, the linker will not produce an image with a table of safe exceptions handlers even if all modules are compatible with the safe exception handling feature. +**`/SAFESEH`** is only valid when linking for x86 targets. **`/SAFESEH`** isn't supported for platforms that already have the exception handlers noted. For example, on x64 and ARM, all exception handlers are noted in the PDATA. ML64.exe has support for adding annotations that emit SEH information (XDATA and PDATA) into the image, allowing you to unwind through ml64 functions. For more information, see [MASM for x64 (ml64.exe)](../../assembler/masm/masm-for-x64-ml64-exe.md). -The most common reason for the linker not to be able to produce an image is because one or more of the input files (modules) to the linker was not compatible with the safe exception handlers feature. A common reason for a module to not be compatible with safe exception handlers is because it was created with a compiler from a previous version of Visual C++. +If **`/SAFESEH`** isn't specified, the linker will produce an image with a table of safe exceptions handlers if all code segments are compatible with the safe exception handling feature. If any code segments weren't compatible with the safe exception handling feature, the resulting image won't contain a table of safe exception handlers. If [`/SUBSYSTEM`](subsystem-specify-subsystem.md) specifies `WINDOWSCE` or one of the `EFI_*` options, the linker won't attempt to produce an image with a table of safe exceptions handlers, as neither of those subsystems can make use of the information. -You can also register a function as a structured exception handler by using [.SAFESEH](../../assembler/masm/dot-safeseh.md). +If **`/SAFESEH:NO`** is specified, the linker won't produce an image with a table of safe exceptions handlers even if all code segments are compatible with the safe exception handling feature. -It is not possible to mark an existing binary as having safe exception handlers (or no exception handlers); information on safe exception handling must be added at build time. +The most common reason the linker can't produce an image is because one or more of the input files to the linker was incompatible with the safe exception handlers feature. A common reason why code is incompatible with safe exception handlers is because it was created with a compiler from a previous version of Visual C++. -The linker's ability to build a table of safe exception handlers depends on the application using the C runtime library. If you link with [/NODEFAULTLIB](nodefaultlib-ignore-libraries.md) and you want a table of safe exception handlers, you need to supply a load config struct (such as can be found in loadcfg.c CRT source file) that contains all the entries defined for Visual C++. For example: +You can also register a function as a structured exception handler by using [`.SAFESEH`](../../assembler/masm/dot-safeseh.md). -``` +It isn't possible to mark an existing binary as having safe exception handlers (or no exception handlers); information on safe exception handling must be added at build time. + +The linker's ability to build a table of safe exception handlers depends on the application using the C runtime library. If you link with [`/NODEFAULTLIB`](nodefaultlib-ignore-libraries.md) and you want a table of safe exception handlers, you need to supply a load config struct (such as can be found in the *`loadcfg.c`* CRT source file) that contains all the entries defined for Visual C++. For example: + +```C #include extern DWORD_PTR __security_cookie; /* /GS security cookie */ @@ -89,13 +92,11 @@ const IMAGE_LOAD_CONFIG_DIRECTORY32_2 _load_config_used = { ### To set this linker option in the Visual Studio development environment -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 **Linker** folder. +1. Open the **Property Pages** dialog box for the project. For more information, see [Set compiler and build properties](../working-with-project-properties.md). -1. Select the **Command Line** property page. +1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. -1. Enter the option into the **Additional Options** box. +1. Modify the **Image Has Safe Exception Handlers** property. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically @@ -103,5 +104,5 @@ const IMAGE_LOAD_CONFIG_DIRECTORY32_2 _load_config_used = { ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/sample-makefile.md b/docs/build/reference/sample-makefile.md index eff1c0b0ce..911eecd6cb 100644 --- a/docs/build/reference/sample-makefile.md +++ b/docs/build/reference/sample-makefile.md @@ -1,8 +1,7 @@ --- description: "Learn more about: Sample Makefile" title: "Sample Makefile" -ms.date: "11/04/2016" -ms.assetid: 8343ce71-5556-4ae0-8d1e-7efd82673070 +ms.date: 09/30/2021 --- # Sample Makefile @@ -12,7 +11,7 @@ This topic contains a sample makefile. ### Code -``` +```makefile # Sample makefile !include @@ -31,4 +30,4 @@ challeng.exe: challeng.obj md4c.obj ## See also -[Contents of a Makefile](contents-of-a-makefile.md) +[Makefile contents and features](contents-of-a-makefile.md) diff --git a/docs/build/reference/sarif-output.md b/docs/build/reference/sarif-output.md new file mode 100644 index 0000000000..29e608baa8 --- /dev/null +++ b/docs/build/reference/sarif-output.md @@ -0,0 +1,151 @@ +--- +description: "How to make the compiler output diagnostics as structured SARIF" +title: "Structured SARIF Diagnostics" +ms.date: "10/26/2023" +author: tartanllama +ms.author: sybrand +manager: mluparu +helpviewer_keywords: ["SARIF", "structured diagnostics"] +--- + +# Structured SARIF Diagnostics + +The MSVC compiler can be made to output diagnostics as [SARIF](https://sarifweb.azurewebsites.net/) (Static Analysis Results Interchange Format). SARIF is a machine-readable JSON-based format. + +There are two ways to make the MSVC compiler produce SARIF diagnostics: + +- Pass the `/experimental:log` switch on the command line. See the [documentation for `/experimental:log`](experimental-log.md) for details. +- Launch `cl.exe` programmatically and set the `SARIF_OUTPUT_PIPE` environment variable to retrieve SARIF blocks through a pipe. + +## Retrieving SARIF through a pipe + +Tools that consume SARIF from the MSVC compiler while a compilation is in progress use a pipe. See the documentation for [`CreatePipe`](/windows/win32/api/namedpipeapi/nf-namedpipeapi-createpipe) for details about creating Windows pipes. + +To retrieve SARIF through a pipe, set the `SARIF_OUTPUT_PIPE` environment variable to be the UTF-16-encoded integer representation of the `HANDLE` to the write end of the pipe, then launch `cl.exe`. SARIF is sent along the pipe as follows: + +- When a new diagnostic is available, it is written to this pipe. +- Diagnostics are written to the pipe one-at-a-time rather than as an entire SARIF object. +- Each diagnostic is represented by a [JSON-RPC 2.0](https://www.jsonrpc.org/) message of type [Notification](https://www.jsonrpc.org/specification#notification:~:text=as%20binary%20fractions.-,4.1%20Notification,-A%20Notification%20is). +- The JSON-RPC message is prefixed with a `Content-Length` header with the form `Content-Length: ` followed by two newlines, where `` is the length of the following JSON-RPC message in bytes. +- The JSON-RPC message and header are both encoded in UTF-8. +- This JSON-RPC-with-header format is compatible with [vs-streamjsonrpc](https://github.com/microsoft/vs-streamjsonrpc). +- The method name for the JSON-RPC call is `OnSarifResult`. +- The call has a single parameter that is encoded [by-name](https://www.jsonrpc.org/specification#parameter_structures) with the parameter name `result`. +- The value of the argument is a single `result` object as specified by the [SARIF Version 2.1 standard](https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html#_Toc141790888). + +### Example + +Here's an example of a JSON-RPC SARIF result produced by `cl.exe`: + +```json +Content-Length: 334 + +{"jsonrpc":"2.0","method":"OnSarifResult","params":{"result":{"ruleId":"C1034","level":"fatal","message":{"text":"iostream: no include path set"},"locations":[{"physicalLocation":{"artifactLocation":{"uri":"file:///C:/Users/sybrand/source/repos/cppcon-diag/cppcon-diag/cppcon-diag.cpp"},"region":{"startLine":1,"startColumn":10}}}]}}}{"jsonrpc":"2.0","method":"OnSarifResult","params":{"result":{"ruleId":"C1034","level":"fatal","message":{"text":"iostream: no include path set"},"locations":[{"physicalLocation":{"artifactLocation":{"uri":"file:///C:/Users/sybrand/source/repos/cppcon-diag/cppcon-diag/cppcon-diag.cpp"},"region":{"startLine":1,"startColumn":10}}}]}}} +``` + +## SARIF result data + +The compiler outputs SARIF that may include additional information to represent the nested structure of some diagnostics. A diagnostic (represented by a `result` SARIF object) may contain a "diagnostic tree" of additional information in its `relatedLocations` field. This tree is encoded using a SARIF [property bag](https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html#_Toc141790698) as follows: + +A `location` object's `properties` field may contain a `nestingLevel` property whose value is the depth of this location in the diagnostic tree. If a location doesn't have a `nestingLevel` specified, the depth is considered to be `0` and this location is a child of the root diagnostic represented by the `result` object containing it. Otherwise, if the value is greater than the depth of the location immediately preceding this location in the `relatedLocations` field, this location is a child of that location. Otherwise, this location is a sibling of the closest preceding `location` in the `relatedLocations` field with the same depth. + +### Example + +Consider the following code: + +```cpp +struct dog {}; +struct cat {}; + +void pet(dog); +void pet(cat); + +struct lizard {}; + +int main() { + pet(lizard{}); +} +``` + +When this code is compiled, the compiler produces the following `result` object (`physicalLocation` properties have been removed for brevity): + +```json +{ + "ruleId": "C2665", + "level": "error", + "message": { + "text": "'pet': no overloaded function could convert all the argument types" + }, + "relatedLocations": [ + { + "id": 0, + "message": { + "text": "could be 'void pet(cat)'" + } + }, + { + "id": 1, + "message": { + "text": "'void pet(cat)': cannot convert argument 1 from 'lizard' to 'cat'" + }, + "properties": { + "nestingLevel": 1 + } + }, + { + "id": 2, + "message": { + "text": "No user-defined-conversion operator available that can perform this conversion, or the operator cannot be called" + }, + "properties": { + "nestingLevel": 2 + } + }, + { + "id": 3, + "message": { + "text": "or 'void pet(dog)'" + } + }, + { + "id": 4, + "message": { + "text": "'void pet(dog)': cannot convert argument 1 from 'lizard' to 'dog'" + }, + "properties": { + "nestingLevel": 1 + } + }, + { + "id": 5, + "message": { + "text": "No user-defined-conversion operator available that can perform this conversion, or the operator cannot be called" + }, + "properties": { + "nestingLevel": 2 + } + }, + { + "id": 6, + "message": { + "text": "while trying to match the argument list '(lizard)'" + } + } + ] +} +``` + +The logical diagnostics tree produced from the messages in this `result` object is: + +- 'pet': no overloaded function could convert all the argument types + - could be 'void pet(cat)' + - 'void pet(cat)': cannot convert argument 1 from 'lizard' to 'cat + - No user-defined-conversion operator available that can perform this conversion, or the operator cannot be called + - or 'void pet(dog)' + - 'void pet(dog)': cannot convert argument 1 from 'lizard' to 'dog' + - No user-defined-conversion operator available that can perform this conversion, or the operator cannot be called + - while trying to match the argument list '(lizard)' + +## See also + +[`/experimental:log` (Enable structured SARIF diagnostics)](experimental-log.md) \ No newline at end of file diff --git a/docs/build/reference/scandependencies.md b/docs/build/reference/scandependencies.md new file mode 100644 index 0000000000..d7a6f2f99c --- /dev/null +++ b/docs/build/reference/scandependencies.md @@ -0,0 +1,141 @@ +--- +title: "/scanDependencies (List module and header unit dependencies per Standard)" +description: "Reference guide to the /scanDependencies compiler option in Microsoft C++." +ms.date: 09/21/2022 +author: "tylermsft" +ms.author: "twhitney" +f1_keywords: ["/scanDependencies"] +helpviewer_keywords: ["/scanDependencies compiler option", "/scanDependencies"] +--- +# `/scanDependencies` (List module dependencies in standard form) + +This compiler option generates a JSON file that lists module and header-unit dependencies according to C++ Standard proposal [`P1689R5 Format for describing dependencies of source files`](https://wg21.link/P1689r5). + +## Syntax + +> **`/scanDependencies-`**\ +> **`/scanDependencies`** *`filename`*\ +> **`/scanDependencies`** *`directory`* + +## Arguments + +*`-`*\ +If the single dash is provided, then the compiler emits the source dependencies JSON to `stdout`, or to where compiler output is redirected. + +*`filename`*\ +The compiler writes the source dependency output to the specified filename, which may include a relative or absolute path. The file is created if it doesn't exist. + +*`directory`*\ +If the argument is a directory, the compiler generates source dependency files in the specified directory. The directory must exist, or the argument is treated as a *`filename`*. The output file name is based on the full name of the input file, with an appended *`.module.json`* extension. For example, if the file provided to the compiler is *`main.cpp`*, the generated output filename is *`main.cpp.module.json`*. + +## Remarks + +The **`/scanDependencies`** compiler option identifies which dependencies, modules, and header units must be compiled before you can compile the project that uses them. For instance, it lists `import ;` or `import "library";` as a header unit dependency, and `import name;` as a module dependency. The intent is to provide this information in a common format consumable by build tools such as CMake. To report module and header unit dependencies, you must also compile by using [`/std:c++20`](std-specify-language-standard-version.md) or later. + +This command-line option is similar to [`/sourceDependencies:directives`](sourcedependencies-directives.md) and [`/sourceDependencies`](sourcedependencies.md), but differs in the following ways: + +- The output uses the [`P1689R5`](https://wg21.link/P1689r5) schema, instead of the Microsoft-specific schema generated by **`/sourceDependencies:directives`**. +- Unlike **`/sourceDependencies`**, the compiler doesn't produce compiled output. Instead, the files are scanned for module directives. No compiled code, modules, or header units are produced. +- The output JSON file doesn't list imported modules and imported header units (*`.ifc`* files) because this option only scans the project files. There are no built modules or header units to list. +- Only directly imported modules or header units are listed. It doesn't list the dependencies of the imported modules or header units themselves. +- Textually included header files such as `#include ` or `#include "file"` aren't listed as dependencies unless translated to a header unit by using the [`/translateInclude`](translateinclude.md) option. +- **`/scanDependencies`** is meant to be used before *`.ifc`* files are built. + +**`/scanDependencies`** is available starting in Visual Studio 2022 version 17.2. It's not enabled by default. + +When you specify the [`/MP` (Build with multiple processes)](mp-build-with-multiple-processes.md) compiler option, we recommend that you use **`/scanDependencies`** with a directory argument. If you provide a single filename argument, two instances of the compiler may attempt to open the output file simultaneously and cause an error. Use of **`/MP`** with **`/scanDependencies-`** to send output to `stdout` could cause interleaved results. + +When a non-fatal compiler error occurs, the dependency information still gets written to the output file. + +All file paths appear as absolute paths in the output. + +For details on the format and schema used in the output JSON file, see [`P1689R5`](https://wg21.link/P1689r5#_format) section 6. + +### Examples + +Consider the following sample code: + +```cpp +//app.cpp: +#include + +import other.module; +import std; +import "t.h"; +import ; + +int main() {} +``` + +You can use this command line to report dependencies in *`app.cpp`*: + +> `cl /std:c++latest /scanDependencies output.json app.cpp` + +The compiler produces a JSON file, *`output.json`*, with content similar to: + +```JSON +{ + "version": 1, + "revision": 0, + "rules": [ + { + "primary-output": "app.obj", + "outputs": [ + "output.json" + ], + "requires": [ + { + "logical-name": "other.module" + }, + { + "logical-name": "std" + }, + { + "logical-name": "t.h", + "source-path": "C:\\Users\\username\\source\\repos\\app\\app\\t.h", + "lookup-method": "include-quote", + "unique-on-source-path": true + }, + { + "logical-name": "iostream", + "source-path": "C:\\Program Files\\...\\include\\iostream", + "lookup-method": "include-angle", + "unique-on-source-path": true + } + ] + } + ] +} +``` + +We've used `...` to abbreviate the reported paths. The report contains the absolute paths. The paths reported depend on where the compiler finds the dependencies. If the results are unexpected, you may want to check your project's include path settings. + +No *`.ifc`* files are listed in the output because they weren't built. Unlike **`/sourceDependencies`**, the compiler doesn't produce compiled output when **`/scanDependencies`** is specified, so no compiled modules or header units are produced to import. + +## To set this compiler option in Visual Studio + +You normally shouldn't set the **`/scanDependencies`** option in the Visual Studio development environment. The compiler doesn't generate object files when you set this option, which makes the link step fail and report an error. + +1. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. + +1. Modify the **Additional Options** property to add *`/scanDependencies-`* or *`/scanDependencies "pathname"`*, where *`"pathname"`* refers to a directory for output. + +1. Choose **OK** to save your changes. + +To report module and header unit dependencies, you must also set the **Configuration Properties** > **General** > **C++ Language Standard** property to **ISO C++20 Standard** or later. + +### To set this compiler option programmatically + +- See . + +## See also + +[Import the C++ standard library using modules](../../cpp/tutorial-import-stl-named-module.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md)\ +[`/sourceDependencies:directives`](sourcedependencies-directives.md)\ +[`/sourceDependencies`](sourcedependencies.md)\ +[`/std` (Specify language standard version)](std-specify-language-standard-version.md)\ +[`/translateInclude`](translateinclude.md) diff --git a/docs/build/reference/search-paths-in-rules.md b/docs/build/reference/search-paths-in-rules.md deleted file mode 100644 index a80e2d1f6a..0000000000 --- a/docs/build/reference/search-paths-in-rules.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -description: "Learn more about: Search Paths in Rules" -title: "Search Paths in Rules" -ms.date: "11/04/2016" -helpviewer_keywords: ["search paths in NMAKE inference rules", "inference rules in NMAKE", "rules, inference"] -ms.assetid: 38feded6-536d-425d-bf40-fff3173a5506 ---- -# Search Paths in Rules - -``` -{frompath}.fromext{topath}.toext: - commands -``` - -## Remarks - -An inference rule applies to a dependency only if paths specified in the dependency exactly match the inference-rule paths. Specify the dependent's directory in *frompath* and the target's directory in *topath*; no spaces are allowed. Specify only one path for each extension. A path on one extension requires a path on the other. To specify the current directory, use either a period (.) or empty braces ({ }). Macros can represent *frompath* and *topath*; they are invoked during preprocessing. - -## Example - -### Code - -``` -{dbi\}.cpp{$(ODIR)}.obj:: - $(CC) $(CFLAGS) $(YUDBI) $< - -{ilstore\}.cpp{$(ODIR)}.obj:: - $(CC) $(CFLAGS) $< - -{misc\}.cpp{$(ODIR)}.obj:: - $(CC) $(CFLAGS) $(YUPDB) $< - -{misc\}.c{$(ODIR)}.obj:: - $(CC) $(CFLAGS) $< - -{msf\}.cpp{$(ODIR)}.obj:: - $(CC) $(CFLAGS) $< - -{bsc\}.cpp{$(ODIR)}.obj:: - $(CC) $(CFLAGS) $(YUPDB) $< - -{mre\}.cpp{$(ODIR)}.obj:: - $(CC) $(CFLAGS) $(YUPDB) $< - -{namesrvr\}.cpp{$(ODIR)}.obj:: - $(CC) $(CFLAGS) $(YUPDB) $< - -{src\cvr\}.cpp{$(ODIR)}.obj:: - $(CC) $(CFLAGS) $< -``` - -## See also - -[Defining a Rule](defining-a-rule.md) diff --git a/docs/build/reference/section-specify-section-attributes.md b/docs/build/reference/section-specify-section-attributes.md index 50cd06a531..c994dd4799 100644 --- a/docs/build/reference/section-specify-section-attributes.md +++ b/docs/build/reference/section-specify-section-attributes.md @@ -1,79 +1,79 @@ --- description: "Learn more about: /SECTION (Specify Section Attributes)" title: "/SECTION (Specify Section Attributes)" -ms.date: "12/29/2017" -f1_keywords: ["/section"] +ms.date: 09/09/2022 +f1_keywords: ["VC.Project.VCLinkerTool.SpecifySectionAttributes", "/section"] helpviewer_keywords: ["SECTION linker option", "-SECTION linker option", "section attributes", "/SECTION linker option"] --- -# /SECTION (Specify Section Attributes) +# `/SECTION` (Specify Section Attributes) -> **/SECTION:**_name_,[[**!**]{**DEKPRSW**}][**,ALIGN=**_number_] +> **`/SECTION:`***`name`***`,`**\[\[**`!`**]{**`D`**\|**`E`**\|**`K`**\|**`P`**\|**`R`**\|**`S`**\|**`W`**}]\[**`,ALIGN=`***`number`*] ## Remarks -The **/SECTION** option changes the attributes of a section, overriding the attributes set when the .obj file for the section was compiled. +The **`/SECTION`** option changes the attributes of a section, overriding the attributes set when the *`.obj`* file for the section was compiled. -A *section* in a portable executable (PE) file is a named contiguous block of memory that contains either code or data. Some sections contain code or data that your program declared and uses directly, while other data sections are created for you by the linker and library manager (lib.exe) and contain information vital to the operating system. For more information, see [PE Format](/windows/win32/Debug/pe-format). +A *section* in a portable executable (PE) file is a named contiguous block of memory that contains either code or data. Some sections contain code or data that your program declared and uses directly. Other data sections are created for you by the linker and library manager (LIB) and contain information vital to the operating system. For more information, see [PE Format](/windows/win32/Debug/pe-format). -Specify a colon (:) and a section *name*. The *name* is case sensitive. +Specify a colon (**`:`**) and a section name *`name`*. The *`name`* is case sensitive. -Do not use the following names, as they conflict with standard names. For example, .sdata is used on RISC platforms: +Don't use the following names, as they conflict with standard names. For example, `.sdata` is used on RISC platforms: -- .arch +- `.arch` -- .bss +- `.bss` -- .data +- `.data` -- .edata +- `.edata` -- .idata +- `.idata` -- .pdata +- `.pdata` -- .rdata +- `.rdata` -- .reloc +- `.reloc` -- .rsrc +- `.rsrc` -- .sbss +- `.sbss` -- .sdata +- `.sdata` -- .srdata +- `.srdata` -- .text +- `.text` -- .xdata +- `.xdata` -Specify one or more attributes for the section. The attribute characters, listed below, are not case sensitive. You must specify all attributes that you want the section to have; an omitted attribute character causes that attribute bit to be turned off. If you do not specify R, W, or E, the existing read, write, or executable status remains unchanged. +Specify one or more attributes for the section. The attribute characters, listed below, aren't case sensitive. You must specify all attributes that you want the section to have. An omitted attribute character causes that attribute bit to be turned off. If you don't specify `R`, `W`, or `E`, the existing read, write, or executable status remains unchanged. -To negate an attribute, precede its character with an exclamation point (!). The meanings of the attribute characters are shown in this table: +To negate an attribute, precede its character with an exclamation point (`!`). The meanings of the attribute characters are shown in this table: -|Character|Attribute|Meaning| -|---------------|---------------|-------------| -|E|Execute|The section is executable| -|R|Read|Allows read operations on data| -|W|Write|Allows write operations on data| -|S|Shared|Shares the section among all processes that load the image| -|D|Discardable|Marks the section as discardable| -|K|Cacheable|Marks the section as not cacheable| -|P|Pageable|Marks the section as not pageable| +| Character | Attribute | Meaning | +|--|--|--| +| `E` | Execute | The section is executable | +| `R` | Read | Allows read operations on data | +| `W` | Write | Allows write operations on data | +| `S` | Shared | Shares the section among all processes that load the image | +| `D` | Discardable | Marks the section as discardable | +| `K` | Cacheable | Marks the section as not cacheable | +| `P` | Pageable | Marks the section as not pageable | -K and P are unusual in that the section flags that correspond to them are used in the negative sense. If you specify one of them on the .text section by using the **/SECTION:.text,K** option, there is no difference in the section flags when you run [DUMPBIN](dumpbin-options.md) with the [/HEADERS](headers.md) option; the section was already implicitly cached. To remove the default, specify **/SECTION:.text,!K** instead. DUMPBIN reveals section characteristics, including "Not Cached." +`K` and `P` are unusual in that the section flags that correspond to them are used in the negative sense. If you specify one of them on the `.text` section by using the **`/SECTION:.text,K`** option, there's no difference in the section flags when you run [`DUMPBIN`](dumpbin-options.md) with the [`/HEADERS`](headers.md) option; the section was already implicitly cached. To remove the default, specify **`/SECTION:.text,!K`** instead. DUMPBIN reveals section characteristics, including "Not Cached." -A section in the PE file that does not have E, R, or W set is probably invalid. +A section in the PE file that doesn't have `E`, `R`, or `W` set is probably invalid. -The **ALIGN=**_number_ argument lets you specify an alignment value for a particular section. The _number_ argument is in bytes and must be a power of two. See [/ALIGN](align-section-alignment.md) for more information. +The **`ALIGN=`***`number`* argument lets you specify an alignment value for a particular section. The *`number`* argument is in bytes and must be a power of two. For more information, see [`/ALIGN`](align-section-alignment.md). ### To set this linker option in the Visual Studio development environment -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. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). -1. Choose the **Configuration Properties** > **Linker** > **Command Line** property page. +1. Choose the **Configuration Properties** > **Linker** > **General** property page. -1. Enter the option in the **Additional Options** box. Choose **OK** or **Apply** to apply the change. +1. Modify the **Specify Section Attributes** property. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically @@ -81,5 +81,5 @@ The **ALIGN=**_number_ argument lets you specify an alignment value for a partic ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/see-visual-cpp.md b/docs/build/reference/see-visual-cpp.md index ac62c0b839..1118029155 100644 --- a/docs/build/reference/see-visual-cpp.md +++ b/docs/build/reference/see-visual-cpp.md @@ -1,39 +1,39 @@ --- -description: "Learn more about: <see>" -title: "<see> (C++ Documentation Comments)" -ms.date: "11/04/2016" +description: "Learn more about: XML documentation tag " +title: " (C++ Documentation Comments)" +ms.date: 12/03/2021 f1_keywords: [""] helpviewer_keywords: [" C++ XML tag", "see C++ XML tag"] ms.assetid: 20ef66f4-b278-45cf-8613-63919edf5720 --- -# <see> +# `` documentation tag -The \ tag lets you specify a link from within text. Use [\](seealso-visual-cpp.md) to indicate text that you might want to appear in a See Also section. +The `` tag lets you specify a link from within text. Use [``](seealso-visual-cpp.md) to indicate text that you might want to appear in a **See also** section. ## Syntax -``` - +```cpp +/// ``` -#### Parameters +### Parameters -*member*
-A reference to a member or field that is available to be called from the current compilation environment. Enclose the name in single or double quotation marks. +*`member`*\ +A reference to a member or field that is available to be called from the current compilation environment. Enclose the name in single or double quotation marks. -The compiler checks that the given code element exists and resolves `member` to the element name in the output XML. The compiler issues a warning if it does not find `member`. +The compiler checks that the given code element exists and resolves *`member`* to the element name in the output XML. The compiler issues a warning if it doesn't find *`member`*. ## Remarks -Compile with [/doc](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. +Compile with [`/doc`](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. -See [\](summary-visual-cpp.md) for an example of using \. +For an example of using ``, see [``](summary-visual-cpp.md). -The MSVC compiler will attempt to resolve cref references in one pass through the documentation comments. Therefore, if using the C++ lookup rules, a symbol is not found by the compiler the reference will be marked as unresolved. See [\](seealso-visual-cpp.md) for more information. +The MSVC compiler will attempt to resolve `cref` references in one pass through the documentation comments. If the compiler doesn't find a symbol when it's using the C++ lookup rules, it marks the reference as unresolved. For more information, see [``](seealso-visual-cpp.md). ## Example -The following sample shows how you can make cref reference to a generic type, such that, the compiler will resolve the reference. +The following sample shows how you can make `cref` reference to a generic type so the compiler will resolve the reference. ```cpp // xml_see_cref_example.cpp @@ -62,4 +62,4 @@ ref class C {}; ## See also -[XML Documentation](xml-documentation-visual-cpp.md) +[XML documentation](xml-documentation-visual-cpp.md) diff --git a/docs/build/reference/seealso-visual-cpp.md b/docs/build/reference/seealso-visual-cpp.md index 4b6234cbb1..317e154d8b 100644 --- a/docs/build/reference/seealso-visual-cpp.md +++ b/docs/build/reference/seealso-visual-cpp.md @@ -1,41 +1,41 @@ --- -description: "Learn more about: <seealso>" -title: "<seealso> (C++ Documentation Comments)" -ms.date: "11/04/2016" +description: "Learn more about: XML documentation tag " +title: " (C++ Documentation Comments)" +ms.date: 12/03/2021 f1_keywords: [""] helpviewer_keywords: ["seealso C++ XML tag", " C++ XML tag"] ms.assetid: cb33d100-9c50-4485-8d0c-573429eff155 --- -# <seealso> +# `` documentation tag -The \ tag lets you specify the text that you might want to appear in a See Also section. Use [\](see-visual-cpp.md) to specify a link from within text. +The `` tag lets you specify the text that you might want to appear in a See Also section. Use [``](see-visual-cpp.md) to specify a link from within text. ## Syntax -``` - +```cpp +/// ``` -#### Parameters +### Parameters -*member*
+*`member`*\ A reference to a member or field that is available to be called from the current compilation environment. Enclose the name in single or double quotation marks. -The compiler checks that the given code element exists and resolves `member` to the element name in the output XML. The compiler issues a warning if it does not find `member`. +The compiler checks that the given code element exists and resolves *`member`* to the element name in the output XML. The compiler issues a warning if it doesn't find *`member`*. -For information on how to create a cref reference to a generic type, see [\](see-visual-cpp.md). +For information on how to create a `cref` reference to a generic type, see [``](see-visual-cpp.md). ## Remarks -Compile with [/doc](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. +Compile with [`/doc`](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. -See [\](summary-visual-cpp.md) for an example of using \. +See [``](summary-visual-cpp.md) for an example of using ``. -The MSVC compiler will attempt to resolve cref references in one pass through the documentation comments. Therefore, if using the C++ lookup rules, a symbol is not found by the compiler the reference will be marked as unresolved. +The MSVC compiler attempts to resolve `cref` references in one pass through the documentation comments. If the compiler doesn't find a symbol when using the C++ lookup rules, it marks the reference as unresolved. ## Example -In the following sample, an unresolved symbol is referenced in a cref. The XML comment for the cref to B::Test will be ``, whereas the reference to A::Test is well-formed ``. +In the following sample, an unresolved symbol is referenced in a `cref`. The XML comment for the `cref` to `A::Test` is well formed: ``. However, the `cref` to `B::Test` becomes ``. ```cpp // xml_seealso_tag.cpp @@ -61,4 +61,4 @@ public ref struct B { ## See also -[XML Documentation](xml-documentation-visual-cpp.md) +[XML documentation](xml-documentation-visual-cpp.md) diff --git a/docs/build/reference/showincludes-list-include-files.md b/docs/build/reference/showincludes-list-include-files.md index 86a35f799f..ced65322f7 100644 --- a/docs/build/reference/showincludes-list-include-files.md +++ b/docs/build/reference/showincludes-list-include-files.md @@ -1,7 +1,7 @@ --- description: "Learn more about: /showIncludes (List include files)" title: "/showIncludes (List include files)" -ms.date: 04/15/2021 +ms.date: 05/24/2022 f1_keywords: ["VC.Project.VCCLWCECompilerTool.ShowIncludes", "VC.Project.VCCLCompilerTool.ShowIncludes", "/showincludes"] helpviewer_keywords: ["include files", "/showIncludes compiler option [C++]", "include files, displaying in compilation", "-showIncludes compiler option [C++]", "showIncludes compiler option [C++]"] --- @@ -30,8 +30,6 @@ Note: including file: d:\temp\2.h In this case, *`2.h`* was included from within *`1.h`*, causing the indentation. -The **`/showIncludes`** option emits to `stderr`, not `stdout`. - ### To set this compiler option in the Visual Studio development environment 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). diff --git a/docs/build/reference/source-charset-set-source-character-set.md b/docs/build/reference/source-charset-set-source-character-set.md index 0a0597a1c0..ed047dda01 100644 --- a/docs/build/reference/source-charset-set-source-character-set.md +++ b/docs/build/reference/source-charset-set-source-character-set.md @@ -1,53 +1,51 @@ --- -description: "Learn more about: /source-charset (Set Source Character Set)" -title: "/source-charset (Set Source Character Set)" -ms.date: "02/06/2019" +description: "Learn more about: /source-charset (Set source character set)" +title: "/source-charset (Set source character set)" +ms.date: 01/31/2022 f1_keywords: ["source-charset", "/source-charset"] helpviewer_keywords: ["/execution-charset compiler option"] ms.assetid: d3c5bf7f-526d-4ee4-acc5-c1a02a4fc481 --- -# /source-charset (Set Source Character Set) +# `/source-charset` (Set source character set) -Lets you specify the source character set for your executable. +This option lets you specify the source character set for your executable. ## Syntax -``` -/source-charset:[IANA_name|.CPID] -``` +> **`/source-charset:`**[*`IANA_name`* | *`.CPID`*] ## Arguments -**IANA_name**
+*`IANA_name`*\ The IANA-defined character set name. -**CPID**
-The code page identifier as a decimal number. +*`.CPID`*\ +The code page identifier as a decimal number, preceded by a `.` character. ## Remarks -You can use the **/source-charset** option to specify an extended source character set to use when your source files include characters that are not represented in the basic source character set. The source character set is the encoding used to interpret the source text of your program into the internal representation used as input to the preprocessing phases before compilation. The internal representation is then converted to the execution character set to store string and character values in the executable. You can use either the IANA or ISO character set name, or a dot (.) followed by a 3 to 5 digit decimal code page identifier to specify the character set to use. For a list of supported code page identifiers and character set names, see [Code Page Identifiers](/windows/win32/Intl/code-page-identifiers). +You can use the **`/source-charset`** option to specify an extended source character set to use when your source files include characters that are not represented in the basic source character set. The source character set is the encoding used to interpret the source text of your program. It's converted into the internal representation used as input to the preprocessing phases before compilation. The internal representation is then converted to the execution character set to store string and character values in the executable. You can use either the IANA or ISO character set name, or a dot (`.`) followed by 3-5 decimal digits that specify the code page identifier of the character set to use. For a list of supported code page identifiers and character set names, see [Code Page Identifiers](/windows/win32/Intl/code-page-identifiers). -By default, Visual Studio detects a byte-order mark to determine if the source file is in an encoded Unicode format, for example, UTF-16 or UTF-8. If no byte-order mark is found, it assumes the source file is encoded using the current user code page, unless you specify a character set name or code page by using the **/source-charset** option. Visual Studio allows you to save your C++ source code by using any of several character encodings. For more information about source and execution character sets, see [Character Sets](../../cpp/character-sets.md) in the language documentation. +By default, Visual Studio detects a byte-order mark to determine if the source file is in an encoded Unicode format, for example, UTF-16 or UTF-8. If no byte-order mark is found, it assumes that the source file is encoded in the current user code page, unless you use the **`/source-charset`** or **`/utf-8`** option to specify a character set name or code page. Visual Studio allows you to save your C++ source code in any of several character encodings. For more information about source and execution character sets, see [Character sets](../../cpp/character-sets.md) in the language documentation. -The source character set you supply must map the 7-bit ASCII characters to the same code points in your character set, or many compilation errors are likely to follow. Your source character set must also be mappable to the extended Unicode character set encodable by UTF-8. Characters that are not encodable in UTF-8 are represented by an implementation-specific substitute. The Microsoft compiler uses a question mark for these characters. +The source character set you supply must map the 7-bit ASCII characters to the same code points in your character set, or many compilation errors are likely to follow. Your source character set must also have a mapping to the extended Unicode character set of UTF-8. Characters that have no equivalent in UTF-8 are represented by an implementation-specific substitute. The Microsoft compiler uses a question mark for these characters. -If you want to set both the source character set and the execution character set to UTF-8, you can use the **/utf-8** compiler option as a shortcut. It is equivalent to specifying **`/source-charset:utf-8 /execution-charset:utf-8`** on the command line. Any of these options also enables the **/validate-charset** option by default. +If you want to set both the source character set and the execution character set to UTF-8, you can use the **`/utf-8`** compiler option as a shortcut. It's equivalent to **`/source-charset:utf-8 /execution-charset:utf-8`** on the command line. Any of these options also enables the **`/validate-charset`** option by default. ### To set this compiler option in the Visual Studio development environment -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. Open the **Property Pages** dialog box for your project. 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 the *`/source-charset`* option, and specify your preferred encoding. +1. In **Additional Options**, add the **`/source-charset`** option, and specify your preferred encoding. 1. Choose **OK** to save your changes. ## See also -[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md)
-[/execution-charset (Set Execution Character Set)](execution-charset-set-execution-character-set.md)
-[/utf-8 (Set Source and Executable character sets to UTF-8)](utf-8-set-source-and-executable-character-sets-to-utf-8.md)
-[/validate-charset (Validate for compatible characters)](validate-charset-validate-for-compatible-characters.md) +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md)\ +[`/execution-charset` (Set execution character set)](execution-charset-set-execution-character-set.md)\ +[`/utf-8` (Set source and execution character sets to UTF-8)](utf-8-set-source-and-executable-character-sets-to-utf-8.md)\ +[`/validate-charset` (Validate for compatible characters)](validate-charset-validate-for-compatible-characters.md) diff --git a/docs/build/reference/sourcedependencies-directives.md b/docs/build/reference/sourcedependencies-directives.md index 80785a5fdf..25cfd5f192 100644 --- a/docs/build/reference/sourcedependencies-directives.md +++ b/docs/build/reference/sourcedependencies-directives.md @@ -1,7 +1,7 @@ --- title: "/sourceDependencies:directives (List module and header unit dependencies)" description: "Reference guide to the /sourceDependencies:directives compiler option in Microsoft C++." -ms.date: 04/13/2020 +ms.date: 05/19/2022 author: "tylermsft" ms.author: "twhitney" f1_keywords: ["/sourceDependencies:directives"] @@ -9,45 +9,47 @@ helpviewer_keywords: ["/sourceDependencies:directives compiler option", "/source --- # `/sourceDependencies:directives` (List module and header unit dependencies) -This command-line switch generates a JSON file that lists module and header-unit dependencies. +This command-line option scans source files and their `#include` statements to generate a JSON file that lists module export and imports. A build system can use this information to determine the build order of modules and header units. -It identifies which modules and header units need to be compiled before the project that uses them is compiled. For instance, it will list `import ;` or `import "library";` as a header unit dependency, and `import name;` as a module dependency. +This option differs from [`/sourceDependencies`](sourcedependencies.md) in the following ways: -This command-line option is similar to [`/sourceDependencies`](sourcedependencies.md), but differs in the following ways: - -- The compiler doesn't produce compiled output. Instead, the files are scanned for module directives. No compiled code, modules, or header units are produced. -- The output JSON file doesn't list imported modules and imported header units (*`.ifc`* files) because this switch does a scan of the project files, not a compilation. So there are no built modules or header units to list. +- The compiler doesn't produce compiled output. No compiled code, modules, or header units are produced. Instead, the files are scanned for module directives. +- The JSON format is different from what `/sourceDependencies` produces. The `/sourceDependencies` option is intended to be used with other build tools, such as CMake. +- The output JSON file doesn't list imported modules and imported header units (*`.ifc`* files) because this option does a scan of the project files, not a compilation. So there are no built modules or header units to list. - Only directly imported modules or header units are listed. It doesn't list the dependencies of the imported modules or header units themselves. -- Header file dependencies are not listed. That is, `#include ` or `#include "file"` dependencies are not listed. +- Header file dependencies aren't listed. That is, `#include ` or `#include "file"` dependencies aren't listed. - `/sourceDependencies:directives` is meant to be used before *`.ifc`* files are built. +- `/sourceDependencies` causes the compiler to report all of the files, such as `#includes`, `.pch` files, `.ifc` files, and so on, that were used for a particular translation unit, whereas `/sourceDependencies:directives [file1]` scans the specified source file and reports all `import` and `export` statements. `/sourceDependencies` can be used with `/sourceDependencies:directives`. ## Syntax -> **`/sourceDependencies:directives`** -\ +> **`/sourceDependencies:directives-`**\ > **`/sourceDependencies:directives`** *filename*\ -> **`/sourceDependencies:directives`** *directory*\ +> **`/sourceDependencies:directives`** *directory* ## Arguments *`-`*\ -If the single dash is provided, then the compiler will emit the source dependencies JSON to `stdout`, or to where compiler output is redirected to. +If the single dash is provided, then the compiler will emit the source dependencies JSON to `stdout`, or to where compiler output is redirected. *`filename`*\ -The compiler writes the source dependency output to the specified filename, which may include a relative or absolute path. +The compiler writes the source dependency output to the specified filename, which may include a relative or absolute path. The file is created if it doesn't exist. *`directory`*\ -If the argument is a directory, the compiler generates source dependency files in the specified directory. The output file name is based on the full name of the input file, with an appended *`.json`* extension. For example, if the file provided to the compiler is *`main.cpp`*, the generated output filename is *`main.cpp.json`*. +If the argument is a directory, the compiler generates source dependency files in the specified directory. The directory must exist, or the argument is treated as a *`filename`*. The output file name is based on the full name of the input file, with an appended *`.json`* extension. For example, if the file provided to the compiler is *`main.cpp`*, the generated output filename is *`main.cpp.json`*. ## Remarks -**`/sourceDependencies:directives`** is available starting in Visual Studio 2019 version 16.10 Preview 2. It's not enabled by default. +**`/sourceDependencies:directives`** is available starting in Visual Studio 2019 version 16.10. -When you specify the **`/MP`** compiler option, we recommend you use **`/sourceDependencies`** with a directory argument. If you provide a single filename argument, two instances of the compiler may attempt to open the output file simultaneously and cause an error. For more information on **`/MP`**, see [`/MP` (Build with multiple processes)](mp-build-with-multiple-processes.md). +When you specify the [`/MP` (Build with multiple processes)](mp-build-with-multiple-processes.md) compiler option, we recommend that you use **`/sourceDependencies:directives`** with a directory argument. This option makes the compiler output a separate *`*.module.json`* file for each source file. If you provide a single filename argument, two instances of the compiler may attempt to open the output file simultaneously and cause an error. Use of **`/MP`** with **`/sourceDependencies:directives-`** to send output to `stdout` could cause interleaved results. When a non-fatal compiler error occurs, the dependency information still gets written to the output file. All file paths appear as absolute paths in the output. +This switch can be used with [`/translateInclude`](translateinclude.md). + ### Examples Given the following sample code: @@ -57,48 +59,54 @@ Given the following sample code: #include import m; -import std.core; - +import std; import ; - import "t.h"; int main() {} ``` -> `cl /std:c++latest /sourceDependencies:directives output.json main.cpp` +This following command line: + +`cl /std:c++latest /translateInclude /sourceDependencies:directives output.json main.cpp` -This command line produces a JSON file *`output.json`* with content like: +produces a JSON file *`output.json`* similar to: ```JSON { "Version":"1.1", "Data":{ - "Source":"C:\\a\\b\\main.cpp", + "Source":"C:\\test\\main.cpp", "ProvidedModule":"", "ImportedModules":[ "m", - "std.core" + "std" ], "ImportedHeaderUnits":[ "C:\\...\\utility", - "C:\\a\\b\\t.h" + "C:\\...\\vector", + "C:\\test\\t.h" ] } } ``` -We've used `...` to abbreviate the reported paths. The report will contain the absolute paths. The paths reported depend on where the compiler finds the dependencies. If the results are unexpected, you may want to check your project's include path settings. +For brevity, the previous example uses `...` to abbreviate the reported paths. The report contains the absolute paths. The paths reported depend on where the compiler finds the dependencies. If the results are unexpected, you might want to check your project's include path settings. `ProvidedModule` lists exported module or module partition names. -No *`.ifc`* files are listed in the output because they weren't built. Unlike `/sourceDependencies`, the compiler doesn't produce compiled output when `/sourceDependencies:directives` is specified, so no compiled modules or header units are produced to import. +No *`.ifc`* files are listed in the output because they weren't built. Unlike `/sourceDependencies`, the compiler doesn't produce compiled output when `/sourceDependencies:directives` is specified, so no compiled modules or header units are produced. ## To set this compiler option in Visual Studio -You normally shouldn't set this yourself in the Visual Studio development environment. It is set by the build system. +You normally shouldn't set this option yourself in the Visual Studio development environment. The build system sets it. ## See also +[Import the C++ standard library using modules](../../cpp/tutorial-import-stl-named-module.md)\ +[`/translateInclude`](translateinclude.md)\ +[C++ header-units.json reference](header-unit-json-reference.md)\ [MSVC compiler options](compiler-options.md)\ -[MSVC compiler command-line syntax](compiler-command-line-syntax.md) \ No newline at end of file +[MSVC compiler command-line syntax](compiler-command-line-syntax.md)\ +[`/scanDependencies` (List module dependencies in standard form)](scandependencies.md)\ +[`/sourceDependencies` (List all source-level dependencies)](sourcedependencies.md) diff --git a/docs/build/reference/sourcedependencies.md b/docs/build/reference/sourcedependencies.md index d5405349d6..e789466f8b 100644 --- a/docs/build/reference/sourcedependencies.md +++ b/docs/build/reference/sourcedependencies.md @@ -1,7 +1,7 @@ --- title: "/sourceDependencies (Report source-level dependencies)" description: "Describes the /sourceDependencies compiler option in Microsoft C++." -ms.date: 04/13/2020 +ms.date: 02/23/2024 author: "tylermsft" ms.author: "twhitney" f1_keywords: ["/sourceDependencies"] @@ -14,32 +14,32 @@ This command-line switch generates a JSON file that details the source-level dep - Header files. Both directly included and the list of headers included by those headers. - The PCH used (if **`/Yu`** is specified). - Names of imported modules -- File paths and names of imported header units. Both directly imported and those imported by those modules and headers units. +- File paths and names of both directly imported header units and of the modules and header units they import in turn. -This provides information necessary to build modules and header units in the proper dependency order. +This option provides information necessary to build modules and header units in the proper dependency order. ## Syntax -> **`/sourceDependencies`** -\ +> **`/sourceDependencies-`**\ > **`/sourceDependencies`** *filename*\ > **`/sourceDependencies`** *directory* ## Arguments *`-`*\ -If the single dash is provided, then the compiler will emit the source dependencies JSON to `stdout`, or to where compiler output is redirected to. +If the single dash is provided, then the compiler will emit the source dependencies JSON to `stdout`, or to where compiler output is redirected. *`filename`*\ -The compiler writes the source dependency output to the specified filename, which may include a relative or absolute path. +The compiler writes the source dependency output to the specified filename, which may include a relative or absolute path. The file is created if it doesn't exist. *`directory`*\ -If the argument is a directory, the compiler generates source dependency files in the specified directory. The output file name is based on the full name of the input file, with an appended *`.json`* extension. For example, if the file provided to the compiler is *`main.cpp`*, the generated output filename is *`main.cpp.json`*. +If the argument is a directory, the compiler generates source dependency files in the specified directory. The directory must exist, or the argument is treated as a *`filename`*. The output file name is based on the full name of the input file, with an appended *`.json`* extension. For example, if the file provided to the compiler is *`main.cpp`*, the generated output filename is *`main.cpp.json`*. ## Remarks The **`/sourceDependencies`** compiler option is available starting in Visual Studio 2019 version 16.7. It's not enabled by default. -When you specify the **`/MP`** compiler option, we recommend you use **`/sourceDependencies`** with a directory argument. If you provide a single filename argument, two instances of the compiler may attempt to open the output file simultaneously and cause an error. For more information on **`/MP`**, see [`/MP` (Build with multiple processes)](mp-build-with-multiple-processes.md). +When you specify the [`/MP` (Build with multiple processes)](mp-build-with-multiple-processes.md) compiler option, we recommend you use **`/sourceDependencies`** with a directory argument. If you provide a single filename argument, two instances of the compiler may attempt to open the output file simultaneously and cause an error. Use of **`/MP`** with **`/sourceDependencies-`** to send output to `stdout` could cause interleaved results. When a non-fatal compiler error occurs, the dependency information still gets written to the output file. @@ -61,11 +61,11 @@ You can use **`/sourceDependencies`** with the rest of your compiler options: > `cl ... /sourceDependencies output.json ... main.cpp` -where `...` represents your other compiler options. This command line produces a JSON file *`output.json`* with content like: +where `...` represents your other compiler options. This command line produces a JSON file *`output.json`* with content like: ```JSON { - "Version": "1.1", + "Version": "1.2", "Data": { "Source": "F:\\Sample\\myproject\\modulee.ixx", "ProvidedModule": "ModuleE", @@ -88,25 +88,23 @@ where `...` represents your other compiler options. This command line produces a { "Header": "f:\\visual studio 16 main\\vc\\tools\\msvc\\14.29.30030\\include\\iostream", "BMI": "F:\\Sample\\Outputs\\Intermediate\\HeaderUnits\\x64\\Debug\\iostream_W4L4JYGFJ3GL8OG9.ifc" - }, - { - "Header": "f:\\visual studio 16 main\\vc\\tools\\msvc\\14.29.30030\\include\\yvals_core.h", - "BMI": "F:\\Sample\\Outputs\\Intermediate\\HeaderUnits\\x64\\Debug\\yvals_core.h.ifc" } ] } } ``` -We've used `...` to abbreviate the reported paths. The report will contain the absolute paths. The paths reported depend on where the compiler finds the dependencies. If the results are unexpected, you may want to check your project's include path settings. +We've used `...` to abbreviate the reported paths. The report contains the absolute paths. The paths reported depend on where the compiler finds the dependencies. If the results are unexpected, you may want to check your project's include path settings. `ProvidedModule` lists exported module or module partition names. ### To set this compiler option in the Visual Studio development environment -You normally shouldn't set this yourself in the Visual Studio development environment. It is set by the build system. +You normally shouldn't set this option yourself in the Visual Studio development environment. It's set by the build system. ## See also -[MSVC compiler options](compiler-options.md)
-[MSVC compiler command-line syntax](compiler-command-line-syntax.md)
+[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md)\ +[`/scanDependencies`](scandependencies.md)\ +[`/sourceDependencies:directives`](sourcedependencies-directives.md) diff --git a/docs/build/reference/sourcelink.md b/docs/build/reference/sourcelink.md index 1e9b7002ed..2240b03d4b 100644 --- a/docs/build/reference/sourcelink.md +++ b/docs/build/reference/sourcelink.md @@ -16,11 +16,11 @@ Specifies a Source Link configuration file to include in the PDB file generated ## Arguments *filename*
-Specifies a JSON-formatted configuration file that contains a simple mapping of local file paths to URLs for source files to display in the debugger. For more information on the format of this file, see [Source Link JSON Schema](https://github.com/dotnet/designs/blob/master/accepted/2020/diagnostics/source-link.md#source-link-json-schema). +Specifies a JSON-formatted configuration file that contains a simple mapping of local file paths to URLs for source files to display in the debugger. For more information on the format of this file, see [Source Link JSON Schema](https://github.com/dotnet/designs/blob/main/accepted/2020/diagnostics/source-link.md#source-link-json-schema). ## Remarks -Source Link is a language- and source-control agnostic system for providing source debugging for binaries. Source Link is supported for native C++ binaries starting in Visual Studio 2017 version 15.8. For an overview of Source Link, see [Source Link](https://github.com/dotnet/designs/blob/master/accepted/2020/diagnostics/source-link.md). For information on how to use Source Link in your projects, and how to generate the SourceLink file as part of your project, see [Using Source Link](https://github.com/dotnet/sourcelink#using-source-link-in-c-projects). +Source Link is a language- and source-control agnostic system for providing source debugging for binaries. Source Link is supported for native C++ binaries starting in Visual Studio 2017 version 15.8. For an overview of Source Link, see [Source Link](https://github.com/dotnet/designs/blob/main/accepted/2020/diagnostics/source-link.md). For information on how to use Source Link in your projects, and how to generate the SourceLink file as part of your project, see [Using Source Link](https://github.com/dotnet/sourcelink#using-source-link-in-c-projects). ### To set the /SOURCELINK linker option in Visual Studio @@ -36,5 +36,5 @@ Source Link is a language- and source-control agnostic system for providing sour ## See also -[MSVC linker reference](linking.md)
+[MSVC linker reference](linking.md)\ [MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/special-characters-in-a-makefile.md b/docs/build/reference/special-characters-in-a-makefile.md deleted file mode 100644 index 822082bb5a..0000000000 --- a/docs/build/reference/special-characters-in-a-makefile.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -description: "Learn more about: Special Characters in a Makefile" -title: "Special Characters in a Makefile" -ms.date: "11/04/2016" -helpviewer_keywords: ["NMAKE program, special characters", "makefiles, special characters", "special characters, in NMAKE macros", "macros, special characters"] -ms.assetid: 92c34ab5-ca6b-4fc0-bcf4-3172eaeda9f0 ---- -# Special Characters in a Makefile - -To use an NMAKE special character as a literal character, place a caret (^) in front of it. NMAKE ignores carets that precede other characters. The special characters are: - -`: ; # ( ) $ ^ \ { } ! @ —` - -A caret (^) within a quoted string is treated as a literal caret character. A caret at the end of a line inserts a literal newline character in a string or macro. - -In macros, a backslash (\\) followed by a newline character is replaced by a space. - -In commands, a percent symbol (%) is a file specifier. To represent % literally in a command, specify a double percent sign (%%) in place of a single one. In other situations, NMAKE interprets a single % literally, but it always interprets a double %% as a single %. Therefore, to represent a literal %%, specify either three percent signs, %%%, or four percent signs, %%%%. - -To use the dollar sign ($) as a literal character in a command, specify two dollar signs ($$). This method can also be used in other situations where ^$ works. - -## See also - -[Contents of a Makefile](contents-of-a-makefile.md) diff --git a/docs/build/reference/special-characters-in-macros.md b/docs/build/reference/special-characters-in-macros.md deleted file mode 100644 index b2bbf6dabc..0000000000 --- a/docs/build/reference/special-characters-in-macros.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -description: "Learn more about: Special Characters in Macros" -title: "Special Characters in Macros" -ms.date: "11/04/2016" -helpviewer_keywords: ["special characters, in NMAKE macros"] -ms.assetid: c0a06cfc-7103-4ee2-a585-e8f6e85dccd7 ---- -# Special Characters in Macros - -A number sign (#) after a definition specifies a comment. To specify a literal number sign in a macro, use a caret (^), as in ^#. - -A dollar sign ($) specifies a macro invocation. To specify a literal $, use $$. - -To extend a definition to a new line, end the line with a backslash (\\). When the macro is invoked, the backslash plus newline character is replaced with a space. To specify a literal backslash at the end of the line, precede it with a caret (^), or follow it with a comment specifier (#). - -To specify a literal newline character, end the line with a caret (^), as in: - -``` -CMDS = cls^ -dir -``` - -## See also - -[Defining an NMAKE Macro](defining-an-nmake-macro.md) diff --git a/docs/build/reference/special-nmake-macros.md b/docs/build/reference/special-nmake-macros.md index ccbbc364cc..93dcf23449 100644 --- a/docs/build/reference/special-nmake-macros.md +++ b/docs/build/reference/special-nmake-macros.md @@ -1,21 +1,80 @@ --- -description: "Learn more about: Special NMAKE Macros" -title: "Special NMAKE Macros" -ms.date: "11/04/2016" -helpviewer_keywords: ["special NMAKE macros", "macros, NMAKE", "NMAKE macros, special"] -ms.assetid: d772e8ea-1e9f-4ad8-beec-663af76f2dd9 +title: "Special NMAKE macros" +description: "Learn more about: Special NMAKE macros" +ms.date: 09/30/2021 +helpviewer_keywords: ["special NMAKE macros", "macros, NMAKE", "NMAKE macros, special", "NMAKE program, environment variable macros", "environment variables, macros in NMAKE", "macros, environment-variable", "options macros", "command macros in NMAKE", "macros, options macros", "macros, command macros", "NMAKE program, recursion macros", "recursion macros", "macros, recursion", "filename macros in NMAKE", "NMAKE program, filename macros"] +no-loc: [AS, AFLAGS, CC, CFLAGS, CPP, CPPFLAGS, CXX, CXXFLAGS, RC, RFLAGS, ias, ml, ml64, cl, rc] --- -# Special NMAKE Macros +# Special NMAKE macros NMAKE provides several special macros to represent various filenames and commands. One use for some of these macros is in the predefined inference rules. Like all macros, the macros provided by NMAKE are case sensitive. -- [Filename macros](filename-macros.md) +## Filename Macros -- [Recursion macros](recursion-macros.md) +Filename macros are predefined as filenames specified in the dependency (not full filename specifications on disk). These macros don't need to be enclosed in parentheses when invoked; specify only a **`$`** as shown. -- [Command macros and options macros](command-macros-and-options-macros.md) +| Macro | Meaning | +|--|--| +| **`$@`** | Current target's full name (path, base name, extension), as currently specified. | +| **`$$@`** | Current target's full name (path, base name, extension), as currently specified. Valid only as a dependent in a dependency. | +| **`$*`** | Current target's path and base name minus file extension. | +| **`$**`** | All dependents of the current target. | +| **`$?`** | All dependents with a later timestamp than the current target. | +| **`$<`** | Dependent file with a later timestamp than the current target. Valid only in commands in inference rules. | -- [Environment-Variable Macros](environment-variable-macros.md) +To specify part of a predefined filename macro, append a macro modifier and enclose the modified macro in parentheses. + +| Modifier | Resulting filename part | +|--|--| +| **`D`** | Drive plus directory | +| **`B`** | Base name | +| **`F`** | Base name plus extension | +| **`R`** | Drive plus directory plus base name | + +## Recursion macros + +Use recursion macros to call NMAKE recursively. Recursive sessions inherit command-line and environment-variable macros and *`Tools.ini`* information. They don't inherit makefile-defined inference rules or `.SUFFIXES` and `.PRECIOUS` specifications. There are three ways to pass macros to a recursive NMAKE session: + +- Set an environment variable with a `SET` command before the recursive call. +- Define a macro in the command for the recursive call. +- Or, define a macro in *`Tools.ini`*. + +| Macro | Definition | +|--|--| +| **`MAKE`** | Command used originally to invoke NMAKE.

The `$(MAKE)` macro gives the full path to *`nmake.exe`*. | +| **`MAKEDIR`** | Current directory when NMAKE was invoked. | +| **`MAKEFLAGS`** | Options currently in effect. Use as `/$(MAKEFLAGS)`. The **`/F`** option isn't included. | + +## Command macros and options macros + +Command macros are predefined for Microsoft products. Options macros represent options to these products and are undefined by default. Both are used in predefined inference rules and can be used in description blocks or user-defined inference rules. Command macros can be redefined to represent part or all of a command line, including options. Options macros generate a null string if left undefined. + +| Tool | Command macro | Defined as | Options macro | +|--|--|--|--| +| Macro Assembler | **`AS`** | `ml` or `ml64` | **`AFLAGS`** | +| C Compiler | **`CC`** | `cl` | **`CFLAGS`** | +| C++ Compiler | **`CPP`** | `cl` | **`CPPFLAGS`** | +| C++ Compiler | **`CXX`** | `cl` | **`CXXFLAGS`** | +| Resource Compiler | **`RC`** | `rc` | **`RFLAGS`** | + +## Environment-variable macros + +NMAKE inherits macro definitions for environment variables that exist before the start of the session. If a variable was set in the operating-system environment, it is available as an NMAKE macro. The inherited names are converted to uppercase. Inheritance occurs before preprocessing. Use the /E option to cause macros inherited from environment variables to override any macros with the same name in the makefile. + +Environment-variable macros can be redefined in the session, and this changes the corresponding environment variable. You can also change environment variables with the SET command. Using the SET command to change an environment variable in a session does not change the corresponding macro, however. + +For example: + +```makefile +PATH=$(PATH);\nonesuch + +all: + echo %%PATH%% +``` + +In this example, changing `PATH` changes the corresponding environment variable `PATH`; it appends `\nonesuch` to your path. + +If an environment variable is defined as a string that would be syntactically incorrect in a makefile, no macro is created and no warning is generated. If a variable's value contains a dollar sign ($), NMAKE interprets it as the beginning of a macro invocation. Using the macro can cause unexpected behavior. ## See also diff --git a/docs/build/reference/specifying-an-inline-file.md b/docs/build/reference/specifying-an-inline-file.md deleted file mode 100644 index 56092294c2..0000000000 --- a/docs/build/reference/specifying-an-inline-file.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -description: "Learn more about: Specifying an Inline File" -title: "Specifying an Inline File" -ms.date: "11/04/2016" -helpviewer_keywords: ["NMAKE program, inline files", "inline files [C++], specifying NMAKE", "files [C++], inline"] -ms.assetid: 393eccfb-3fc9-4bac-a30c-8ac8d221cca3 ---- -# Specifying an Inline File - -Specify two angle brackets (<<) in the command where *filename* is to appear. The angle brackets cannot be a macro expansion. - -## Syntax - -``` -<<[filename] -``` - -## Remarks - -When the command is run, the angle brackets are replaced by *filename*, if specified, or by a unique NMAKE-generated name. If specified, *filename* must follow angle brackets without a space or tab. A path is permitted. No extension is required or assumed. If *filename* is specified, the file is created in the current or specified directory, overwriting any existing file by that name; otherwise, it is created in the TMP directory (or the current directory, if the TMP environment variable is not defined). If a previous *filename* is reused, NMAKE replaces the previous file. - -## See also - -[Inline Files in a Makefile](inline-files-in-a-makefile.md) diff --git a/docs/build/reference/stack-stack-allocations.md b/docs/build/reference/stack-stack-allocations.md index 995fbeeefd..5bd9529826 100644 --- a/docs/build/reference/stack-stack-allocations.md +++ b/docs/build/reference/stack-stack-allocations.md @@ -1,28 +1,26 @@ --- -description: "Learn more about: /STACK (Stack Allocations)" -title: "/STACK (Stack Allocations)" -ms.date: "11/04/2016" +description: "Learn more about: /STACK (Stack allocations)" +title: "/STACK (Stack allocations)" +ms.date: 02/22/2022 f1_keywords: ["VC.Project.VCLinkerTool.StackReserveSize", "VC.Project.VCLinkerTool.StackCommitSize", "/stack"] helpviewer_keywords: ["STACK linker option", "-STACK linker option", "memory allocation, stack", "/STACK linker option", "stack, setting size"] ms.assetid: 73283660-e4bd-47cc-b5ca-04c5d739034c --- -# /STACK (Stack Allocations) +# `/STACK` (Stack allocations) -``` -/STACK:reserve[,commit] -``` +> **`/STACK:`***`reserve`*[**`,`***`commit`*] ## Remarks -The /STACK option sets the size of the stack in bytes. Use this option only when you build an .exe file. +The **`/STACK`** linker option sets the size of the stack in bytes. Use this option only when you build an *`.exe`* file. The **`/STACK`** option is ignored when applied to *`.dll`* files. -The `reserve` value specifies the total stack allocation in virtual memory. For ARM, x86 and x64 machines, the default stack size is 1 MB. +The *`reserve`* value specifies the total stack allocation in virtual memory. For ARM64, x86, and x64 machines, the default stack size is 1 MB. -`commit` is subject to interpretation by the operating system. In Windows WindowsRT it specifies the amount of physical memory to allocate at a time. Committed virtual memory causes space to be reserved in the paging file. A higher `commit` value saves time when the application needs more stack space, but increases the memory requirements and possibly the startup time. For ARM, x86 and x64 machines, the default commit value is 4 KB. +The *`commit`* value is subject to interpretation by the operating system. In WindowsRT, it specifies the amount of physical memory to allocate at a time. Committed virtual memory causes space to be reserved in the paging file. A higher *`commit`* value saves time when the application needs more stack space, but increases the memory requirements and possibly the startup time. For ARM64, x86, and x64 machines, the default *`commit`* value is 4 KB. -Specify the `reserve` and `commit` values in decimal or C-language notation. +Specify the *`reserve`* and *`commit`* values in decimal or C-language hexadecimal notation (use a `0x` prefix). -Another way to set the size of the stack is with the [STACKSIZE](stacksize.md) statement in a module-definition (.def) file. **STACKSIZE** overrides the Stack Allocations (/STACK) option if both are specified. You can change the stack size after the .exe file is built by using the [EDITBIN](editbin-reference.md) tool. +Another way to set the size of the stack is with the [`STACKSIZE`](stacksize.md) statement in a module-definition (*`.def`*) file. **`STACKSIZE`** overrides the Stack Allocations (**`/STACK`**) option if both are specified. You can change the stack size after the *`.exe`* file is built by using the [`EDITBIN`](editbin-reference.md) tool. ### To set this linker option in the Visual Studio development environment @@ -42,5 +40,5 @@ Another way to set the size of the stack is with the [STACKSIZE](stacksize.md) s ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/std-specify-language-standard-version.md b/docs/build/reference/std-specify-language-standard-version.md index 80716ffc5c..c9eeb3f544 100644 --- a/docs/build/reference/std-specify-language-standard-version.md +++ b/docs/build/reference/std-specify-language-standard-version.md @@ -1,9 +1,8 @@ --- title: "/std (Specify Language Standard Version)" description: "The MSVC compiler option /std specifies the C or C++ language standard supported by the compiler." -ms.date: 10/29/2020 -f1_keywords: ["/std", "-std", "/std:c++14", "/std:c++17", "/std:c11", "/std:c17", "VC.Project.VCCLCompilerTool.CppLanguageStandard"] -ms.assetid: 0acb74ba-1aa8-4c05-b96c-682988dc19bd +ms.date: 1/29/2025 +f1_keywords: ["/std", "-std", "/std:c++14", "/std:c++17", "/std:c++20", "/std:c++23preview", "/std:c++latest", "/std:c11", "/std:c17", "/std:clatest", "VC.Project.VCCLCompilerTool.CppLanguageStandard"] --- # `/std` (Specify Language Standard Version) @@ -13,92 +12,129 @@ Enable supported C and C++ language features from the specified version of the C > **`/std:c++14`**\ > **`/std:c++17`**\ +> **`/std:c++20`**\ +> **`/std:c++23preview`**\ > **`/std:c++latest`**\ > **`/std:c11`**\ -> **`/std:c17`** +> **`/std:c17`**\ +> **`/std:clatest`** ## Remarks -The **`/std`** option is available in Visual Studio 2017 and later. It's used to control the version-specific ISO C or C++ programming language standard features enabled during compilation of your code. This option allows you to disable support for certain new language and library features: ones that may break your existing code that conforms to a particular version of the language standard. +The **`/std`** options are available in Visual Studio 2017 and later. They're used to control the version-specific ISO C or C++ programming language standard features enabled during compilation of your code. The options allow you to disable support for certain new language and library features: ones that may break your existing code that conforms to a particular version of the language standard. -### C++ standards support +The Microsoft C++ compiler in Visual Studio 2017 and later versions doesn't support C++ standards modes earlier than C++14 (**`/std:c++14`**). Such support isn't planned. As an imperfect workaround, it's possible to use older Visual C++ compiler toolsets that didn't implement features from later standards. For more information on how to install and use older compiler toolsets in Visual Studio, see [Use native multi-targeting in Visual Studio to build old projects](../../porting/use-native-multi-targeting.md). -By default, **`/std:c++14`** is specified, which disables language and standard library features found in later versions of the C++ language standard. Use **`/std:c++17`** to enable C++17 standard-specific features and behavior. To explicitly enable the currently implemented compiler and standard library features proposed for the next draft standard, use **`/std:c++latest`**. All C++20 features require **`/std:c++latest`**; when the implementation is complete, a new **`/std:c++20`** option will be enabled. +## C++ standards support -The default **`/std:c++14`** option enables the set of C++14 features implemented by the MSVC compiler. This option disables compiler and standard library support for features that are changed or new in more recent versions of the language standard. It doesn't disable some C++17 features already implemented in previous releases of the MSVC compiler. To avoid breaking changes for users who have already taken dependencies on the features available in or before Visual Studio 2015 Update 2, these features remain enabled when the **`/std:c++14`** option is specified: +Detect whether the **`/std`** option is in effect during a C++ compilation with the [`_MSVC_LANG`](../../preprocessor/predefined-macros.md) preprocessor macro. For more information, see [Preprocessor Macros](../../preprocessor/predefined-macros.md). -- [Rules for `auto` with braced-init-lists](https://wg21.link/n3922) +> [!IMPORTANT] +> Because some existing code depends on the value of the macro `__cplusplus` being `199711L`, the MSVC compiler doesn't change the value of this macro unless you explicitly opt in by setting [`/Zc:__cplusplus`](zc-cplusplus.md). Specify `/Zc:__cplusplus` and the **`/std`** option to set `__cplusplus` to the appropriate value. -- [`typename` in template template-parameters](https://wg21.link/n4051) +### `/std:c++14` -- [Removing trigraphs](https://wg21.link/n4086) +Enables C++14 standard-specific features implemented by the MSVC compiler. This option is the default for code compiled as C++. It's available starting in Visual Studio 2015 Update 3. -- [Attributes for namespaces and enumerators](https://wg21.link/n4266) +This option disables compiler and standard library support for features that are changed or new in more recent versions of the language standard. However, it doesn't disable some C++17 features already implemented in previous releases of the MSVC compiler. For more information, see [Microsoft C/C++ language conformance](../../overview/visual-cpp-language-conformance.md). The tables indicate which C++17 features are enabled when you specify **`/std:c++14`**. + +The following features remain enabled when the **`/std:c++14`** option is specified to avoid breaking changes for users who took dependencies on features available in or before Visual Studio 2015 Update 2: +- [Rules for `auto` with braced-init-lists](https://wg21.link/n3922) +- [`typename` in template template-parameters](https://wg21.link/n4051) +- [Removing trigraphs](https://wg21.link/n4086) +- [Attributes for namespaces and enumerators](https://wg21.link/n4266) - [u8 character literals](https://wg21.link/n4267) -A list of which C++14 and C++17 features are enabled when you specify **`/std:c++14`** is available. For more information, see the notes in [Microsoft C++ language conformance table](../../overview/visual-cpp-language-conformance.md). +### `/std:c++17` -The **`/std:c++17`** option enables the full set of C++17 features implemented by the MSVC compiler. This option disables compiler and standard library support for features that are new or changed after C++17. That includes post-C++17 changes in versions of the Working Draft and defect updates of the C++ Standard. +Enables C++17 standard-specific features and behavior. It enables the full set of C++17 features implemented by the MSVC compiler. This option disables compiler and standard library support for features that are new or changed after C++17. It specifically disables post-C++17 changes in the C++ Standard and versions of the Working Draft. It doesn't disable retroactive defect updates of the C++ Standard. This option is available starting in Visual Studio 2017 version 15.3. -The **`/std:c++latest`** option enables the post-C++17 language and library features currently implemented in the compiler and libraries. These features may include changes from the C++20 Working Draft, defect updates that aren't included in C++17, and experimental proposals for the draft standard. For a list of supported language and library features, see [What's New for Visual C++](../../overview/what-s-new-for-visual-cpp-in-visual-studio.md). The **`/std:c++latest`** option doesn't enable features guarded by the **`/experimental`** switch, but may be required to enable them. +Depending on the MSVC compiler version or update level, C++17 features may not be fully implemented or fully conforming when you specify the **`/std:c++17`** option. For an overview of C++ language conformance in Visual C++ by release version, see [Microsoft C/C++ language conformance](../../overview/visual-cpp-language-conformance.md). -> [!IMPORTANT] -> The compiler and library features enabled by **`/std:c++latest`** represent features that may appear in a future C++ standard, as well as C++20 features that are approved. Features that have not been approved are subject to breaking changes or removal without notice and are provided on an as-is basis. +### `/std:c++20` -The **`/std`** option in effect during a C++ compilation can be detected by use of the [\_MSVC\_LANG](../../preprocessor/predefined-macros.md) preprocessor macro. For more information, see [Preprocessor Macros](../../preprocessor/predefined-macros.md). +Enables C++20 standard-specific features and behavior. -The **`/std:c++14`** and **`/std:c++latest`** options are available beginning in Visual Studio 2015 Update 3. The **`/std:c++17`** option is available beginning in Visual Studio 2017 version 15.3. As noted above, some C++17 standard behavior is enabled by the **`/std:c++14`** option, but all other C++17 features are enabled by **`/std:c++17`**. C++20 features are enabled by **`/std:c++latest`** until the implementation is complete. +Enables the standard conformance mode provided by [**`/permissive-`**](./permissive-standards-conformance.md) unless explicitly overridden with **`/permissive`**. -> [!NOTE] -> Depending on the MSVC compiler version or update level, C++17 features may not be fully implemented or fully conforming when you specify the **`/std:c++17`** options. For an overview of C++ language conformance in Visual C++ by release version, see [Microsoft C++ language conformance table](../../overview/visual-cpp-language-conformance.md). +### `/std:c++23preview` + +Enables preview C++23 standard-specific features and behavior. Available starting in Visual Studio 2022 version 17.13 Preview 4. Preview features may change and may not be ABI compatible across releases. + +This switch will be removed when the `/std:c++23` switch is implemented--at which point C++23 features will be fully implemented and ABI stable. If in project properties **C/C++** > **Language** you specify **Preview - ISO C++ 23 Standard (/std:c++preview)**, it will automatically change to mean `/std:c++23` once the new switch is implemented. -### C standards support +This switch differs from `/std:c++latest` in that it only enables features that are part of the C++23 standard. It doesn't enable experimental or in-progress features. -By default, when code is compiled as C, the MSVC compiler doesn't conform to a particular C standard. It implements ANSI C89 with several Microsoft extensions, some of which are part of ISO C99. Some Microsoft extensions can be disabled by using the [`/Za`](za-ze-disable-language-extensions.md) compiler option, but others remain in effect. It isn't possible to specify strict C89 conformance. +### `/std:c++latest` -Starting in Visual Studio 2019 version 16.8, you may specify **`/std:c11`** or **`/std:c17`** for code compiled as C. These options specify conformance modes that correspond with ISO C11 and ISO C17. Because the new preprocessor is needed to support these standards, the **`/std:c11`** and **`/std:c17`** compiler options set the [`/Zc:preprocessor`](zc-preprocessor.md) option automatically. If you want to use the traditional (legacy) preprocessor for C11 or C17, you must set the **`/Zc:preprocessor-`** compiler option explicitly. Setting the **`/Zc:preprocessor-`** option may lead to unexpected behavior, and isn't recommended. +Enables all currently implemented compiler and standard library features proposed in the next ISO C++ working draft, as well as some in-progress and experimental features. This option is available starting with Visual Studio 2015 Update 3. + +Depending on the MSVC compiler version or update level, features from published C++ standards or proposed features in the current C++ working draft, may not be fully implemented or fully conforming when you specify the **`/std:c++latest`** option. We recommend you use the latest version of Visual Studio for maximum standards conformance. For an overview of C++ language and library conformance in Visual C++ by release version, see [Microsoft C/C++ language conformance](../../overview/visual-cpp-language-conformance.md). + +Since Visual Studio 2019 version 16.8, the **`/std:c++latest`** option has enabled the standard conformance mode provided by [**`/permissive-`**](./permissive-standards-conformance.md) unless explicitly overridden with **`/permissive`**. + +For a list of supported language and library features, see [What's New for C++ in Visual Studio](../../overview/what-s-new-for-visual-cpp-in-visual-studio.md). + +The **`/std:c++latest`** option doesn't enable features guarded by the **`/experimental`** switch, but may be required to enable them. > [!NOTE] -> At the time of release, the latest Windows SDK and UCRT libraries do not yet support C11 and C17 code. A pre-release version of the Windows SDK and UCRT is required. For more information and installation instructions, see [Install C11 and C17 support in Visual Studio](../../overview/install-c17-support.md). +> The compiler and library features enabled by **`/std:c++latest`** may appear in a future C++ standard. Features that haven't been approved are subject to breaking changes or removal without notice and are provided on an as-is basis. -When you specify **`/std:c11`** or **`/std:c17`**, MSVC supports all the required features of C11 and C17. The compiler options enable support for these functionalities: +## C standards support -- [`_Pragma`](../../preprocessor/pragma-directives-and-the-pragma-keyword.md#the-_pragma-preprocessing-operator-c99-c11) +You can invoke the Microsoft C compiler by using the [`/TC` or `/Tc`](tc-tp-tc-tp-specify-source-file-type.md) compiler option. It's used by default for code that has a *`.c`* file extension, unless overridden by a **`/TP`** or **`/Tp`** option. The default C compiler (that is, the compiler when **`/std:c11`** or **`/std:c17`** isn't specified) implements ANSI C89, but includes several Microsoft extensions, some of which are part of ISO C99. Some Microsoft extensions to C89 can be disabled by using the [`/Za`](za-ze-disable-language-extensions.md) compiler option, but others remain in effect. It isn't possible to specify strict C89 conformance. The compiler doesn't implement several required features of C99, so it isn't possible to specify C99 conformance, either. -- **`restrict`** +### `/std:c11` -- **`_Noreturn`** and \ +Enables ISO C11 conformance. It's available starting in Visual Studio 2019 version 16.8. -- **`_Alignas`**, **`_Alignof`** and \ +### `/std:c17` -- **`_Generic`** and \ +Enables ISO C17 conformance. It's available starting in Visual Studio 2019 version 16.8. + +Because the new preprocessor is needed to support these standards, the **`/std:c11`** and **`/std:c17`** compiler options set the [`/Zc:preprocessor`](zc-preprocessor.md) option automatically. If you want to use the traditional (legacy) preprocessor for C11 or C17, you must set the **`/Zc:preprocessor-`** compiler option explicitly. Setting the **`/Zc:preprocessor-`** option may lead to unexpected behavior, and isn't recommended. + +> [!NOTE] +> At the time of release and through Visual Studio 2019 version 16.10, the Windows SDK and UCRT libraries installed by Visual Studio don't yet support C11 and C17 code. An updated version of the Windows SDK and UCRT is required. For more information and installation instructions, see [Install C11 and C17 support in Visual Studio](../../overview/install-c17-support.md). -- **`_Static_assert`** +When you specify **`/std:c11`** or **`/std:c17`**, MSVC supports all the features of C11 and C17 required by the standards. The **`/std:c11`** and **`/std:c17`** compiler options enable support for these functionalities: -The IDE uses C settings for IntelliSense and code highlighting when your source files have a *`.c`* file extension, or when you specify the [`/TC`](tc-tp-tc-tp-specify-source-file-type.md) compiler option. Currently, IntelliSense highlighting is only available for keywords, and not the macros introduced by the standard headers. +- [`_Pragma`](../../preprocessor/pragma-directives-and-the-pragma-keyword.md#the-pragma-preprocessing-operator) +- [`restrict`](../../c-language/type-qualifiers.md#restrict) +- [`_Noreturn`](../../c-language/noreturn.md) and \ +- [`_Alignas`, `_Alignof`](../../c-language/alignment-c.md) and \ +- [`_Generic`](../../c-language/generic-selection.md) and \ +- [`_Static_assert`](../../c-language/static-assert-c.md) -Since C17 is largely a bug fix release of ISO C11, MSVC support for C11 already includes all the relevant defect reports. At present, there are no differences between the C11 and C17 versions except for the `__STDC_VERSION__` macro. It expands to `201112L` for C11, and `201710L` for C17. +The IDE uses C settings for IntelliSense and code highlighting when your source files have a *`.c`* file extension, or when you specify the [`/TC` or `/Tc`](tc-tp-tc-tp-specify-source-file-type.md) compiler option. Currently, IntelliSense in C highlights keywords `_Alignas`, `_Alignof`, `_Noreturn`, and `_Static_assert`, but not the equivalent macros defined in the standard headers: `alignas`, `alignof`, `noreturn`, and `static_assert`. -The compiler doesn't support any optional features of ISO C11. Several of these optional features of C11 were required features of C99 that MSVC hasn't implemented for architectural reasons. You can use the feature test macros such as `__STDC_NO_VLA__` to detect compiler support levels for individual features. For more information about C-specific predefined macros, see [Predefined macros](../../preprocessor/predefined-macros.md). +Since C17 is largely a bug-fix release of ISO C11, MSVC support for C11 already includes all the relevant defect reports. There are no differences between the C11 and C17 versions except for the `__STDC_VERSION__` macro. It expands to `201112L` for C11, and `201710L` for C17. -- There's no conforming multithreading, atomic, or complex number support in the Visual Studio 2019 version 16.8 release. +The compiler doesn't support most optional features of ISO C11. Several of these optional features of C11 were required features of C99 that MSVC hasn't implemented for architectural reasons. You can use the feature test macros such as `__STDC_NO_VLA__` to detect compiler support levels for individual features. For more information about C-specific predefined macros, see [Predefined macros](../../preprocessor/predefined-macros.md). + +- There's no conforming multithreading, atomic, or complex number support. - `aligned_alloc` support is missing, because of the Windows heap implementation. The alternative is to use [`_aligned_malloc`](../../c-runtime-library/reference/aligned-malloc.md). -- DR 400 support is currently unimplemented for `realloc`, because this change would break the ABI. +- [Defect report 400](https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2148.htm#dr_400) support is currently unimplemented for `realloc` because this change would break the ABI. -- Variable length array (VLA) support isn't planned. Variable length arrays are often less efficient than comparable fixed sized arrays. They're also inefficient compared to equivalent heap memory allocations, when safely and securely implemented. VLAs provide attack vectors comparable to `gets()`, which is deprecated and planned for removal. +- Variable length array (VLA) support isn't planned. VLAs provide attack vectors comparable to [`gets`](../../c-runtime-library/gets-getws.md), which is deprecated and planned for removal. -### To set this compiler option in the Visual Studio development environment +### `/std:clatest` -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). +The **`/std:clatest`** option behaves like the `/std:c++latest` switch for the C++ compiler. The switch enables all currently implemented compiler and standard library features proposed in the next draft C standard, as well as some in-progress and experimental features. -1. Select the **Configuration Properties** > **C/C++** > **Language** property page. +For more information, see the C Standard library features section of [Microsoft C/C++ language conformance](../../overview/visual-cpp-language-conformance.md). +### To set this compiler option in the Visual Studio development environment + +1. Open the project's **Property Pages** dialog box. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Select the **Configuration Properties** > **C/C++** > **Language** property page. 1. In **C++ Language Standard** (or for C, **C Language Standard**), choose the language standard to support from the dropdown control, then choose **OK** or **Apply** to save your changes. ## See also -[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) +[`/Zc:__cplusplus[-]`](zc-cplusplus.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/subsystem-specify-subsystem.md b/docs/build/reference/subsystem-specify-subsystem.md index 1a0ff36443..5669fa0e8b 100644 --- a/docs/build/reference/subsystem-specify-subsystem.md +++ b/docs/build/reference/subsystem-specify-subsystem.md @@ -1,63 +1,65 @@ --- description: "Learn more about: /SUBSYSTEM (Specify Subsystem)" title: "/SUBSYSTEM (Specify Subsystem)" -ms.date: "11/04/2016" -f1_keywords: ["/subsystem", "VC.Project.VCLinkerTool.SubSystem", "VC.Project.VCLinkerTool.SubSystemVersion"] +ms.date: 09/09/2022 +f1_keywords: ["/subsystem", "VC.Project.VCLinkerTool.SubSystem", "VC.Project.VCLinkerTool.SubSystemVersion", "VC.Project.VCLinkerTool.MinimumRequiredVersion"] helpviewer_keywords: ["/SUBSYSTEM linker option", "SUBSYSTEM linker option", "-SUBSYSTEM linker option", "subsystem specifications"] ms.assetid: d7b133cf-cf22-4da8-ab46-6552702c0b9b --- -# /SUBSYSTEM (Specify Subsystem) +# `/SUBSYSTEM` (Specify Subsystem) -``` -/SUBSYSTEM:{BOOT_APPLICATION|CONSOLE|EFI_APPLICATION| - EFI_BOOT_SERVICE_DRIVER|EFI_ROM|EFI_RUNTIME_DRIVER|NATIVE| - POSIX|WINDOWS} - [,major[.minor]] -``` +Specify the Windows subsystem targeted by the executable. + +## Syntax + +> **`/SUBSYSTEM:`** { **`BOOT_APPLICATION`** | **`CONSOLE`** | **`EFI_APPLICATION`** |\ +>   **`EFI_BOOT_SERVICE_DRIVER`** | **`EFI_ROM`** | **`EFI_RUNTIME_DRIVER`** | **`NATIVE`** |\ +>   **`POSIX`** | **`WINDOWS`** }\ +>   [ **`,`**_`major`_ [ **`.`**_`minor`_ ]] ## Arguments -**BOOT_APPLICATION**
+**`BOOT_APPLICATION`**\ An application that runs in the Windows boot environment. For more information about boot applications, see [About BCD](/previous-versions/windows/desktop/bcd/about-bcd). -**CONSOLE**
+**`CONSOLE`**\ Win32 character-mode application. The operating system provides a console for console applications. If `main` or `wmain` is defined for native code, `int main(array ^)` is defined for managed code, or you build the application completely by using `/clr:safe`, CONSOLE is the default. -**EFI_APPLICATION**
-**EFI_BOOT_SERVICE_DRIVER**
-**EFI_ROM**
-**EFI_RUNTIME_DRIVER**
-The Extensible Firmware Interface subsystems. See the EFI specification for more information. For examples, see the Intel Web site. The minimum version and default version is 1.0. +**`EFI_APPLICATION`**\ +**`EFI_BOOT_SERVICE_DRIVER`**\ +**`EFI_ROM`**\ +**`EFI_RUNTIME_DRIVER`**\ +The Extensible Firmware Interface subsystems. For more information, see the [UEFI specification](https://uefi.org/specifications). The minimum version and default version is 1.0. -**NATIVE**
-Kernel mode drivers for Windows NT. This option is usually reserved for Windows system components. If [/DRIVER:WDM](driver-windows-nt-kernel-mode-driver.md) is specified, NATIVE is the default. +**`NATIVE`**\ +Kernel mode drivers for Windows NT. This option is normally reserved for Windows system components. If [`/DRIVER:WDM`](driver-windows-nt-kernel-mode-driver.md) is specified, `NATIVE` is the default. -**POSIX**
+**`POSIX`**\ Application that runs with the POSIX subsystem in Windows NT. -**WINDOWS**
-Application does not require a console, probably because it creates its own windows for interaction with the user. If `WinMain` or `wWinMain` is defined for native code, or `WinMain(HISTANCE *, HINSTANCE *, char *, int)` or `wWinMain(HINSTANCE *, HINSTANCE *, wchar_t *, int)` is defined for managed code, WINDOWS is the default. +**`WINDOWS`**\ +The application doesn't require a console, probably because it creates its own windows for interaction with the user. If `WinMain` or `wWinMain` is defined for native code, or `WinMain(HINSTANCE *, HINSTANCE *, char *, int)` or `wWinMain(HINSTANCE *, HINSTANCE *, wchar_t *, int)` is defined for managed code, `WINDOWS` is the default. -*major* and *minor*
-(Optional) Specify the minimum required version of the subsystem. The arguments are decimal numbers in the range 0 through 65,535. See the Remarks for more information. There are no upper bounds for version numbers. +*`major`* and *`minor`*\ +(Optional) Specify the minimum required version of the subsystem. The arguments are decimal numbers in the range 0 through 65,535. There are no upper bounds for version numbers. ## Remarks -The **/SUBSYSTEM** option specifies the environment for the executable. +The **`/SUBSYSTEM`** option specifies the environment for the executable. The choice of subsystem affects the entry point symbol (or entry point function) that the linker will select. -The optional minimum and default *major* and *minor* version numbers for the subsystems are as follows. +The optional minimum and default *`major`* and *`minor`* version numbers for the subsystems are as follows: -|Subsystem|Minimum|Default| -|---------------|-------------|-------------| -|BOOT_APPLICATION|1.0|1.0| -|CONSOLE|5.01 (x86) 5.02 (x64) 6.02 (ARM)|6.00 (x86, x64) 6.02 (ARM)| -|WINDOWS|5.01 (x86) 5.02 (x64) 6.02 (ARM)|6.00 (x86, x64) 6.02 (ARM)| -|NATIVE (with DRIVER:WDM)|1.00 (x86) 1.10 (x64, ARM)|1.00 (x86) 1.10 (x64, ARM)| -|NATIVE (without /DRIVER:WDM)|4.00 (x86) 5.02 (x64) 6.02 (ARM)|4.00 (x86) 5.02 (x64) 6.02 (ARM)| -|POSIX|1.0|19.90| -|EFI_APPLICATION, EFI_BOOT_SERVICE_DRIVER, EFI_ROM, EFI_RUNTIME_DRIVER|1.0|1.0| +| Subsystem | Minimum | Default | +|--|--|--| +| `BOOT_APPLICATION` | 1.0 | 1.0 | +| `CONSOLE` | 5.01 (x86) 5.02 (x64) 6.02 (ARM) | 6.00 (x86, x64) 6.02 (ARM) | +| `WINDOWS` | 5.01 (x86) 5.02 (x64) 6.02 (ARM) | 6.00 (x86, x64) 6.02 (ARM) | +| `NATIVE` (with **`/DRIVER:WDM`**) | 1.00 (x86) 1.10 (x64, ARM) | 1.00 (x86) 1.10 (x64, ARM) | +| `NATIVE` (without **`/DRIVER:WDM`**) | 4.00 (x86) 5.02 (x64) 6.02 (ARM) | 4.00 (x86) 5.02 (x64) 6.02 (ARM) | +| `POSIX` | 1.0 | 19.90 | +| `EFI_APPLICATION`, `EFI_BOOT_SERVICE_DRIVER`, `EFI_ROM`, `EFI_RUNTIME_DRIVER` | 1.0 | 1.0 | ### To set this linker option in the Visual Studio development environment @@ -73,5 +75,5 @@ The optional minimum and default *major* and *minor* version numbers for the sub ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/summary-visual-cpp.md b/docs/build/reference/summary-visual-cpp.md index 5258ef38e3..7651f7a4bf 100644 --- a/docs/build/reference/summary-visual-cpp.md +++ b/docs/build/reference/summary-visual-cpp.md @@ -1,31 +1,31 @@ --- -description: "Learn more about: <summary>" -title: "<summary> (C++ Documentation Comments)" -ms.date: "11/04/2016" +description: "Learn more about: XML documentation tag " +title: " (C++ Documentation Comments)" +ms.date: 12/03/2021 f1_keywords: [""] helpviewer_keywords: [" C++ XML tag", "summary C++ XML tag"] ms.assetid: cdeeefbb-1339-45d6-9002-10042a9a2726 --- -# <summary> +# `` -The \ tag should be used to describe a type or a type member. Use [\](remarks-visual-cpp.md) to add supplemental information to a type description. +The `` tag should be used to describe a type or a type member. Use [``](remarks-visual-cpp.md) to add supplemental information to a type description. ## Syntax -``` -description +```cpp +/// description ``` -#### Parameters +### Parameters -*description*
+*`description`*\ A summary of the object. ## Remarks -The text for the \ tag is the only source of information about the type in IntelliSense, and is also displayed in the [Object Browser](/visualstudio/ide/viewing-the-structure-of-code) and in the Code Comment Web Report. +The text for the `` tag is the only source of information about the type in IntelliSense, and is also displayed in the [Object Browser](/visualstudio/ide/viewing-the-structure-of-code) and in the Code Comment Web Report. -Compile with [/doc](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. +Compile with [`/doc`](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. ## Example @@ -50,4 +50,4 @@ public: ## See also -[XML Documentation](xml-documentation-visual-cpp.md) +[XML documentation](xml-documentation-visual-cpp.md) diff --git a/docs/build/reference/time-linker-time-information.md b/docs/build/reference/time-linker-time-information.md new file mode 100644 index 0000000000..04c414de2d --- /dev/null +++ b/docs/build/reference/time-linker-time-information.md @@ -0,0 +1,35 @@ +--- +description: "Learn more about the /TIME (Linker time information) linker option." +title: "/TIME" +ms.date: 05/11/2022 +f1_keywords: ["/time"] +helpviewer_keywords: ["/time"] +--- +# `/TIME` (Linker time information) + +Output the time taken by linker steps and total link time. + +## Syntax + +> **`/TIME`** + +## Remarks + +The `/TIME` linker option displays the time taken by the linker steps and the total link time in seconds, with millisecond precision. + +### To set this linker option in the Visual Studio development environment + +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** > **Linker** > **Command Line** property page. + +1. In the **Additional Options** box, add the *`/TIME`* linker option. Choose **OK** or **Apply** to save your changes. + +### To set this linker option programmatically + +- See . + +## See also + +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/tlbout-name-dot-tlb-file.md b/docs/build/reference/tlbout-name-dot-tlb-file.md index a9fde3067b..3daba01380 100644 --- a/docs/build/reference/tlbout-name-dot-tlb-file.md +++ b/docs/build/reference/tlbout-name-dot-tlb-file.md @@ -1,32 +1,31 @@ --- description: "Learn more about: /TLBOUT (Name .TLB File)" title: "/TLBOUT (Name .TLB File)" -ms.date: "11/04/2016" +ms.date: 03/24/2025 f1_keywords: ["VC.Project.VCLinkerTool.TypeLibraryFile", "/tlbout"] helpviewer_keywords: ["tlb files, renaming", "TLBOUT linker option", "/TLBOUT linker option", ".tlb files, renaming", "-TLBOUT linker option"] -ms.assetid: 0df6d078-2e48-46c9-a1a5-02674d85dce8 --- -# /TLBOUT (Name .TLB File) +# `/TLBOUT` (Name .TLB File) -``` +```cmd /TLBOUT:[path\]filename ``` ## Arguments -*path*
+*`path`*\ An absolute or relative path specification for where the .tlb file should be created. -*filename*
-Specifies the name of the .tlb file created by the MIDL compiler. No file extension is assumed; specify *filename*.tlb if you want a .tlb extension. +*`filename`* +Specifies the name of the .tlb file created by the MIDL compiler. No file extension is assumed; specify *filename*.tlb if you want a .tlb extension. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). ## Remarks -The /TLBOUT option specifies the name and extension of the .tlb file. +The `/TLBOUT` option specifies the name and extension of the .tlb file. The MIDL compiler is called by the MSVC linker when linking projects that have the [module](../../windows/attributes/module-cpp.md) attribute. -If /TLBOUT is not specified, the .tlb file will get its name from [/IDLOUT](idlout-name-midl-output-files.md) *filename*. If /IDLOUT is not specified, the .tlb file will be called vc70.tlb. +If `/TLBOUT` is not specified, the .tlb file will get its name from [/IDLOUT](idlout-name-midl-output-files.md) *filename*. If /IDLOUT is not specified, the .tlb file will be called vc70.tlb. ### To set this linker option in the Visual Studio development environment @@ -42,8 +41,8 @@ If /TLBOUT is not specified, the .tlb file will get its name from [/IDLOUT](idlo ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md)
-[/IGNOREIDL (Don't Process Attributes into MIDL)](ignoreidl-don-t-process-attributes-into-midl.md)
-[/MIDL (Specify MIDL Command Line Options)](midl-specify-midl-command-line-options.md)
+[MSVC linker reference](linking.md)\ +[MSVC Linker Options](linker-options.md)\ +[/IGNOREIDL (Don't Process Attributes into MIDL)](ignoreidl-don-t-process-attributes-into-midl.md)\ +[/MIDL (Specify MIDL Command Line Options)](midl-specify-midl-command-line-options.md)\ [Building an Attributed Program](../../windows/attributes/cpp-attributes-com-net.md) diff --git a/docs/build/reference/translateinclude.md b/docs/build/reference/translateinclude.md index f8cf53733d..fa5cadac9e 100644 --- a/docs/build/reference/translateinclude.md +++ b/docs/build/reference/translateinclude.md @@ -1,77 +1,50 @@ --- -title: "/translateInclude (Translate include directives into import directives)" +title: "/translateInclude" description: "Use the /translateInclude compiler option to treat #include directives as import statements when an importable header unit is available." -ms.date: 4/13/2021 +ms.date: 02/17/2022 author: "tylermsft" ms.author: "twhitney" -f1_keywords: ["/translateInclude"] +f1_keywords: ["/translateInclude", "VC.Project.VCCLCompilerTool.TranslateIncludes"] helpviewer_keywords: ["/translateInclude", "Translate include directives into import directives"] --- -# `/translateInclude` (Translate include directives into import directives) +# `/translateInclude` -Instructs the compiler to treat `#include` as `import` for those headers that have been prebuilt into a header unit (`.ifc`) file. +This switch instructs the compiler to treat `#include` as `import` for header files that have been built into header unit (`.ifc`) files and that are specified on the command line with [`/headerUnit`](headerunit.md). -## Syntax - -> **`/translateInclude`** - -## Remarks - -The **`/translateInclude`** compiler option requires you enable the [/std:c++latest](std-specify-language-standard-version.md) option. `/translateInclude` is available starting in Visual Studio 2019 version 16.10 Preview 2. - -The **`/translateInclude`** option effectively makes the following transformation, where the example `` has been prebuilt into an importable header unit: - -```cpp -#include -``` - -The compiler replaces this directive with: +When used with [`/scanDependencies`](scandependencies.md) or [`/sourceDependencies-directives`](sourcedependencies-directives.md), the compiler lists as imported header units in the generated dependency file those headers that are both included in the source and have a corresponding entry in a `header-units.json` file. This dependency info is used by the build system to generate compiled header unit `.ifc` files. Once the header units are built, they're treated by the compiler as an `import` instead of an `#include`. -```cpp -import ; -``` +The `header-units.json` file is only consulted when `/translateInclude` is specified. For more information about the format and purpose of the `header-units.json` file, see [`header-units.json`](header-unit-json-reference.md). -In MSVC, available header units are made available by the **`/headerUnit`** option, which maps a header file to its corresponding prebuilt importable header unit. For more information, see [`/headerUnit` (Specify where to find the header unit file (`.ifc`) for the specified header)](headerunit.md). +If an `#include` file isn't listed in the `header-units.json` file, it's treated as a normal `#include`. -### Examples +For an example of how this switch is used, see [Walkthrough: Build and import header units in Microsoft Visual C++](../walkthrough-header-units.md). -Given a project that references two header files and their header units, listed in this table: - -| Header file | IFC file | -|--|--| -| *`C:\utils\util.h`* | *`C:\util.h.ifc`* | -| *`C:\app\app.h`* | *`C:\app.h.ifc`* | - -And a source *`.cpp`* file that includes the headers, - -```cpp -#include "utils/util.h" -#include "app/app.h" +## Syntax -int main() { } -``` +> **`/translateInclude`** -The **`/translateInclude`** option allows the compiler to treat an `#include` as an `import` for header files that have a corresponding compiled header unit file (*`.ifc`*) and that have been specified on the command line via the `/headerUnit` switch. +## Remarks -If an `#include` is encountered that doesn't have a corresponding header unit specified via the `/headerUnit` switch, it is processed by the preprocessor as a normal `#include` directive. +**`/translateInclude`** is available in Visual Studio 2019 version 16.10, or later.\ +**`/translateInclude`** requires [/std:c++20](std-specify-language-standard-version.md) or later. - Here's an example command line that translates the include directives for *`util.h`* and *`app.h`* into imports of the header units instead: +## To set this compiler option in Visual Studio -```CMD -cl /IC:\ /translateInclude /headerUnit C:\utils\util.h=C:\util.h.ifc /headerUnit C:\app\app.h=C:\app.h.ifc -``` +To enable `/translateInclude`, in the project properties dialog, set **Translate Includes to Imports**: -## To set this compiler option in Visual Studio +1. In the left-hand pane of the project property pages, select **Configuration Properties** > **C/C++** > **General**. -To enable `/translateInclude`, set the **Translate Includes to Imports** option in project properties: +1. Change the **Translate Includes to Imports** dropdown to **Yes**. -1. In the left-hand pane of the project property pages, select **Configuration Properties** > **C/C++** > **General** -1. Change the **Translate Includes to Imports** dropdown to **Yes** -![Project properties dialog set Translate Includes to Imports](../media/vs2019-translate-includes-option.png) + ![Screenshot of the Property Pages dialog with the Translate Includes to Imports property highlighted.](../media/vs2019-translate-includes-option.png) +1. Choose **OK** or **Apply** to save your changes. ## See also [`/headerUnit` (Use header unit IFC)](headerunit.md).\ [`/exportHeader` (Create header units)](module-exportheader.md)\ -[`/reference` (Use named module IFC)](module-reference.md) +[`/reference` (Use named module IFC)](module-reference.md)\ +[`/scanDependencies`](scandependencies.md)\ +[`/sourceDependencies-directives`](sourcedependencies-directives.md)\ +[Walkthrough: Build and import header units in Microsoft Visual C++](../walkthrough-header-units.md) diff --git a/docs/build/reference/tsaware-create-terminal-server-aware-application.md b/docs/build/reference/tsaware-create-terminal-server-aware-application.md index e5d398e9d6..3b060a4c75 100644 --- a/docs/build/reference/tsaware-create-terminal-server-aware-application.md +++ b/docs/build/reference/tsaware-create-terminal-server-aware-application.md @@ -1,32 +1,30 @@ --- -description: "Learn more about: /TSAWARE (Create Terminal Server Aware Application)" -title: "/TSAWARE (Create Terminal Server Aware Application)" -ms.date: "11/04/2016" +description: "Learn more about: /TSAWARE (Create Terminal Server aware application)" +title: "/TSAWARE (Create Terminal Server aware application)" +ms.date: 03/02/2022 f1_keywords: ["/tsaware", "VC.Project.VCLinkerTool.TerminalServerAware"] helpviewer_keywords: ["Terminal Server", "/TSAWARE linker option", "Terminal Server, Terminal Server-aware applications", "-TSAWARE linker option", "TSAWARE linker option"] ms.assetid: fe1c1846-de5b-4839-b562-93fbfe36cd29 --- -# /TSAWARE (Create Terminal Server Aware Application) +# `/TSAWARE` (Create Terminal Server aware application) -``` -/TSAWARE[:NO] -``` +> **`/TSAWARE`**\[**`:NO`**] ## Remarks -The /TSAWARE option sets a flag in the IMAGE_OPTIONAL_HEADER DllCharacteristics field in the program image's optional header. When this flag is set, Terminal Server will not make certain changes to the application. +The **`/TSAWARE`** option sets a flag in the `IMAGE_OPTIONAL_HEADER` `DllCharacteristics` field in the program image's optional header. When this flag is set, Terminal Server won't make certain changes to the application. -When an application is not Terminal Server aware (also known as a legacy application), Terminal Server makes certain modifications to the legacy application to make it work properly in a multiuser environment. For example, Terminal Server will create a virtual Windows folder, such that each user gets a Windows folder instead of getting the system's Windows directory. This gives users access to their own INI files. In addition, Terminal Server makes some adjustments to the registry for a legacy application. These modifications slow the loading of the legacy application on Terminal Server. +When an application isn't Terminal Server aware (also known as a legacy application), Terminal Server makes certain modifications to the legacy application to make it work properly in a multiuser environment. For example, Terminal Server creates a virtual *`Windows`* folder, such that each user gets a *`Windows`* folder instead of getting the system's *`Windows`* directory. This virtual folder gives users access to their own INI files. In addition, Terminal Server makes some adjustments to the registry for a legacy application. These modifications slow the loading of the legacy application on Terminal Server. -If an application is Terminal Server aware, it must neither rely on INI files nor write to the **HKEY_CURRENT_USER** registry during setup. +If an application is Terminal Server aware, it must not rely on INI files or write to the `HKEY_CURRENT_USER` registry during setup. -If you use /TSAWARE and your application still uses INI files, the files will be shared by all users of the system. If that is acceptable, you can still link your application with /TSAWARE; otherwise you need to use /TSAWARE:NO. +If you use **`/TSAWARE`** and your application still uses INI files, the files will be shared by all users of the system. If that's acceptable, you can still link your application with **`/TSAWARE`**; otherwise you need to use **`/TSAWARE:NO`**. -The /TSAWARE option is enabled by default for Windows and console applications. See [/SUBSYSTEM](subsystem-specify-subsystem.md) and [/VERSION](version-version-information.md) for information. +The **`/TSAWARE`** option is enabled by default for Windows and console applications. For more information, see [`/SUBSYSTEM`](subsystem-specify-subsystem.md) and [`/VERSION`](version-version-information.md). -/TSAWARE is not valid for drivers or DLLs. +**`/TSAWARE`** isn't valid for drivers or DLLs. -If an application was linked with /TSAWARE, DUMPBIN [/HEADERS](headers.md) will display information to that effect. +If an application was linked with **`/TSAWARE`**, [`DUMPBIN /HEADERS`](headers.md) will display information to that effect. ### To set this linker option in the Visual Studio development environment diff --git a/docs/build/reference/u-u-undefine-symbols.md b/docs/build/reference/u-u-undefine-symbols.md index 816c704527..cdc3cdd3ba 100644 --- a/docs/build/reference/u-u-undefine-symbols.md +++ b/docs/build/reference/u-u-undefine-symbols.md @@ -1,12 +1,11 @@ --- title: "/U, /u (Undefine symbols)" description: "Use the Microsoft C/C++ compiler /U and /u options to undefine preprocessor symbols." -ms.date: 09/03/2020 +ms.date: 04/14/2025 f1_keywords: ["VC.Project.VCCLCompilerTool.UndefinePreprocessorDefinitions", "VC.Project.VCCLWCECompilerTool.UndefinePreprocessorDefinitions", "VC.Project.VCCLCompilerTool.UndefineAllPreprocessorDefinitions", "/u", "VC.Project.VCCLWCECompilerTool.UndefineAllPreprocessorDefinitions"] helpviewer_keywords: ["-U compiler option [C++]", "Undefine Symbols compiler option", "/U compiler option [C++]", "U compiler option [C++]"] -ms.assetid: 7bc0474f-6d1f-419b-807d-0d8816763b2a --- -# /U, /u (Undefine symbols) +# `/U`, `/u` (Undefine symbols) The **`/U`** compiler option undefines the specified preprocessor symbol. The **`/u`** compiler option undefines the Microsoft-specific symbols that the compiler defines. @@ -17,7 +16,7 @@ The **`/U`** compiler option undefines the specified preprocessor symbol. The ** ## Arguments -*symbol*
+*`symbol`*\ The preprocessor symbol to undefine. ## Remarks @@ -44,9 +43,7 @@ For a complete list of Microsoft-specific predefined macros, see [Predefined mac ### To set this compiler option in the Visual Studio development environment 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++** > **Advanced** property page. - +1. Select the **Configuration Properties** > **C/C++** > **Preprocessor** property page. 1. Modify the **Undefine Preprocessor Definitions** or **Undefine All Preprocessor Definitions** properties. ### To set this compiler option programmatically @@ -55,9 +52,9 @@ For a complete list of Microsoft-specific predefined macros, see [Predefined mac ## See also -[MSVC compiler options](compiler-options.md)
-[MSVC compiler command-line syntax](compiler-command-line-syntax.md)
-[**`/J`** (Default char type is unsigned)](j-default-char-type-is-unsigned.md)
-[**`/GR`** (Enable run-time type information)](gr-enable-run-time-type-information.md)
-[**`/EH`** (Exception handling model)](eh-exception-handling-model.md)
+[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md)\ +[**`/J`** (Default char type is unsigned)](j-default-char-type-is-unsigned.md)\ +[**`/GR`** (Enable run-time type information)](gr-enable-run-time-type-information.md)\ +[**`/EH`** (Exception handling model)](eh-exception-handling-model.md)\ [**`/MD`**, **`/MT`**, **`/LD`** (Use run-time library)](md-mt-ld-use-run-time-library.md) diff --git a/docs/build/reference/useprofile.md b/docs/build/reference/useprofile.md index 9efe996529..9a9fde9e72 100644 --- a/docs/build/reference/useprofile.md +++ b/docs/build/reference/useprofile.md @@ -1,12 +1,12 @@ --- description: "Learn more about: /USEPROFILE (Run PGO in thread safe mode)" title: "/USEPROFILE (Use PGO data with LTCG)" -ms.date: "03/14/2018" +ms.date: 03/24/2025 f1_keywords: ["USEPROFILE"] --- # /USEPROFILE (Run PGO in thread safe mode) -This linker option together with [/LTCG (Link-time code generation](ltcg-link-time-code-generation.md) tells the linker to build by using profile-guided optimization (PGO) training data. +This linker option together with [`/LTCG` (Link-time code generation](ltcg-link-time-code-generation.md) tells the linker to build by using profile-guided optimization (PGO) training data. ## Syntax @@ -14,21 +14,21 @@ This linker option together with [/LTCG (Link-time code generation](ltcg-link-ti ### Arguments -**AGGRESSIVE**
+**`AGGRESSIVE`**\ This optional argument specifies that aggressive speed optimizations should be used during optimized code generation. -**PGD**=*filename*
-Specifies a base file name for the .pgd file. By default, the linker uses the base executable file name with a .pgd extension. +**`PGD`**=*filename*\ +Specifies a base filename for the `.pgd` file. By default, the linker uses the base executable filename with a `.pgd` extension. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). ## Remarks -The **/USEPROFILE** linker option is used together with **/LTCG** to generate or update an optimized build based on PGO training data. It is the equivalent of the deprecated **/LTCG:PGUPDATE** and **/LTCG:PGOPTIMIZE** options. +The **`/USEPROFILE`** linker option is used together with **`/LTCG`** to generate or update an optimized build based on PGO training data. It is the equivalent of the deprecated **`/LTCG:PGUPDATE`** and **`/LTCG:PGOPTIMIZE`** options. -The optional **AGGRESSIVE** argument disables size-related heuristics to attempt to optimize for speed. This may result in optimizations that substantially increase the size of your executable, and may not increase the resulting speed. You should profile and compare the results of using and not using **AGGRESSIVE**. This argument must be specified explicitly; it is not enabled by default. +The optional **`AGGRESSIVE`** argument disables size-related heuristics to attempt to optimize for speed. This may result in optimizations that substantially increase the size of your executable, and may not increase the resulting speed. You should profile and compare the results of using and not using **`AGGRESSIVE`**. This argument must be specified explicitly; it is not enabled by default. -The **PGD** argument specifies an optional name for the training data .pgd file to use, the same as in [/GENPROFILE or /FASTGENPROFILE](genprofile-fastgenprofile-generate-profiling-instrumented-build.md). It is the equivalent of the deprecated **/PGD** switch. By default, or if no *filename* is specified, a .pgd file that has the same base name as the executable is used. +The **`PGD`** argument specifies an optional name for the training data `.pgd` file to use, the same as in [`/GENPROFILE` or `/FASTGENPROFILE`](genprofile-fastgenprofile-generate-profiling-instrumented-build.md). It is the equivalent of the deprecated **/PGD** switch. By default, or if no *`filename`* is specified, a `.pgd` file that has the same base name as the executable is used. -The **/USEPROFILE** linker option is new in Visual Studio 2015. +The **`/USEPROFILE`** linker option is new in Visual Studio 2015. ### To set this linker option in the Visual Studio development environment @@ -48,7 +48,7 @@ The **/USEPROFILE** linker option is new in Visual Studio 2015. ## See also -[/GENPROFILE and /FASTGENPROFILE](genprofile-fastgenprofile-generate-profiling-instrumented-build.md)
-[/LTCG](ltcg-link-time-code-generation.md)
-[Profile-Guided Optimizations](../profile-guided-optimizations.md)
-[Environment Variables for Profile-Guided Optimizations](../environment-variables-for-profile-guided-optimizations.md)
+[`/GENPROFILE` and `/FASTGENPROFILE`](genprofile-fastgenprofile-generate-profiling-instrumented-build.md)\ +[`/LTCG`](ltcg-link-time-code-generation.md)\ +[Profile-Guided Optimizations](../profile-guided-optimizations.md)\ +[Environment Variables for Profile-Guided Optimizations](../environment-variables-for-profile-guided-optimizations.md) diff --git a/docs/build/reference/using-an-nmake-macro.md b/docs/build/reference/using-an-nmake-macro.md index 7858f0167d..f4b418744b 100644 --- a/docs/build/reference/using-an-nmake-macro.md +++ b/docs/build/reference/using-an-nmake-macro.md @@ -1,27 +1,110 @@ --- -description: "Learn more about: Using an NMAKE Macro" -title: "Using an NMAKE Macro" -ms.date: "11/04/2016" -helpviewer_keywords: ["macros, NMAKE", "NMAKE macros, using"] -ms.assetid: 95c87fbc-76e6-48c0-8536-9bfe179f328e +title: "Use an NMAKE macro" +description: "Learn more about: Using an NMAKE macro" +ms.date: 09/30/2021 +helpviewer_keywords: ["macros, NMAKE", "NMAKE macros, using", "NMAKE program, macro substitution", "substitution macros in NMAKE", "NMAKE functions", "functions, NMAKE"] --- -# Using an NMAKE Macro +# Use an NMAKE macro -To use a macro, enclose its name in parentheses preceded by a dollar sign ($) as follows. +To use a macro, enclose its name in parentheses preceded by a dollar sign (**`$`**) as follows: -## Syntax +```makefile +$(macro_name) +``` + +No spaces are allowed. The parentheses are optional if *macro_name* is a single character. The definition string replaces `$(macro_name)`; an undefined macro is replaced by a null string. + +## Macro substitution + +When *macro_name* is invoked, each occurrence of *string1* in its definition string is replaced by *string2*. + +```makefile +$(macro_name:string1=string2) +``` + +Macro substitution is case-sensitive and is literal; *string1* and *string2* can't invoke macros. Substitution doesn't modify the original definition. You can replace text in any predefined macro except [`$$@`](special-nmake-macros.md#filename-macros). + +No spaces or tabs precede the colon (**`:`**); any spaces or tabs after the colon are interpreted as literal. If *string2* is null, all occurrences of *string1* are deleted from the macro's definition string. + +::: moniker range=">=msvc-170" + +## Macro functions + +NMAKE provides a set of functions that can be used to modify strings, lists of items and file paths. These functions are available in NMAKE starting in Visual Studio 2022. + +### Function syntax + +Functions use the following syntax: + +```makefile +$(function_name arg0,arg1,arg2...) +``` + +Arguments to a function can be any string and may include nested macro invocations. Except in special cases, arguments can't be null. +Any extra whitespace between the function name and the argument list is ignored. If the first argument requires leading whitespace, then use a macro that contains the needed whitespace: + +```makefile +SINGLESPACE=$(subst ',,' ') # Use "subst" since a normal assignment trims trailing whitespace. +$(subst $(SINGLESPACE)an,irec,red ant) # Evaluates to "redirect" ``` -$(macroname) + +Commas within an argument list are always considered argument separators and can't be escaped. If any argument requires a literal comma, use a macro that contains a comma instead: + +```makefile +COMMA=, +INPUT=a, b +$(subst $(COMMA) , and ,$(INPUT)) # Evaluates to "a and b" +``` + +### List syntax + +Some functions support a whitespace-separated list of items. Extra whitespace is ignored at the beginning of the list, the end of the list, or between each item. Lists produced by a function use a single space between each item as a separator, and don't have leading or trailing whitespace. + +For example, the simplest list function is `strip`, which takes a single list argument and produces a list with the exact same items (but with the whitespace cleaned as above): + +```makefile +$(strip a b c d ) # Evaluates to "a b c d" ``` -## Remarks +### Pattern syntax + +Some functions support using a *pattern*. A pattern is a string that contains a single wildcard that can match any number of characters. The first `%` in a pattern is the wildcard, and any later `%` characters are treated as literals. A `%` anywhere before the actual wildcard can be escaped by using `\` (that is, `\%` is treated as a literal `%`). Any `\` that would escape the wildcard can be escaped with another `\` (so `\\%` is treated as a literal `\` followed by the wildcard). To be considered a match, all of the input characters must be matched by the pattern; partial matches aren't supported. + +Patterns can be demonstrated using the `filter` function, which only keeps items that match the pattern: + +```makefile +$(filter abc,abc) # Evaluates to "abc" - exactly matches +$(filter bc,abc) # Evaluates to "" - pattern "bc" only matches part of the item "abc" +$(filter %ef,abcdef) # Evaluates to "abcdef" - wildcard matches "abcd" +$(filter a%f,abcdef) # Evaluates to "abcdef" - wildcard matches "bcde" +$(filter %abc,abc) # Evaluates to "abc" - wildcard doesn't need to match any characters +$(filter a%c%d,abcd abc%d) # Evaluates to "abc%d" - only the first `%` is a wildcard, the rest are literals +$(filter a\%b%d,a%bcd) # Evaluates to "a%bcd" - `%` before the wildcard must be escaped with `\` +$(filter a\\%cd,a\bcd) # Evaluates to "a\bcd" - a `\` that would escape the wildcard must be escaped with another `\` +$(filter a%c\\%d,abc\\%d) # Evaluates to "abc\\%d" - any `\` after the wildcard isn't treated as an escape +$(filter \\a%f,\\abcdef) # Evaluates to "\\abcdef" - any `\\` that isn't directly before the wildcard isn't treated as an escape +``` -No spaces are allowed. The parentheses are optional if *macroname* is a single character. The definition string replaces $(*macroname*); an undefined macro is replaced by a null string. +### Functions by category -## What do you want to know more about? +| Function | Purpose | Supported | +|--|--|--| +| **Text functions** | **Purpose** | **Supported** | +|  [`findstring`, `findstringi`](nmake-function-findstring.md) | Checks if the input contains a string. | VS 2022 17.0 | +|  [`lowercase`](nmake-function-lowercase.md) | Converts a string to lowercase. | VS 2022 17.2 | +|  [`subst`, `substi`](nmake-function-subst.md) | Replaces all instances of one string with another. | VS 2022 17.0 | +|  [`uppercase`](nmake-function-uppercase.md) | Converts a string to uppercase. | VS 2022 17.2 | +| **List functions** | **Purpose** | **Supported** | +|  [`filter`, `filteri`](nmake-function-filter.md) | Keeps items in a list that match at least one pattern. | VS 2022 17.0 | +|  [`filterout`, `filterouti`](nmake-function-filterout.md) | Keeps items in a list that don't match any patterns. | VS 2022 17.0 | +|  [`patsubst`, `patsubsti`](nmake-function-patsubst.md) | Transforms each item that matches a pattern, items that don't match are left as-is. | VS 2022 17.1 | +|  [`strip`](nmake-function-strip.md) | Cleans the whitespace in and around a list of items. | VS 2022 17.0 | +| **File path functions** | **Purpose** | **Supported** | +|  [`abspath`](nmake-function-abspath.md) | Gets the absolute path for each item in a list. | VS 2022 17.1 | +|  [`basename`](nmake-function-basename.md) | Gets the base name for each item in a list. | VS 2022 17.1 | -[Macro substitution](macro-substitution.md) +::: moniker-end ## See also diff --git a/docs/build/reference/utf-8-set-source-and-executable-character-sets-to-utf-8.md b/docs/build/reference/utf-8-set-source-and-executable-character-sets-to-utf-8.md index f2524dd177..b0e8d0d005 100644 --- a/docs/build/reference/utf-8-set-source-and-executable-character-sets-to-utf-8.md +++ b/docs/build/reference/utf-8-set-source-and-executable-character-sets-to-utf-8.md @@ -1,13 +1,13 @@ --- -description: "Learn more about: `/utf-8` (Set Source and Executable character sets to UTF-8)" -title: "/utf-8 (Set Source and Executable character sets to UTF-8)" -ms.date: "04/26/2020" +description: "Learn more about: `/utf-8` (Set source and execution character sets to UTF-8)" +title: "/utf-8 (Set source and execution character sets to UTF-8)" +ms.date: 01/31/2022 f1_keywords: ["/utf-8"] helpviewer_keywords: ["/utf-8 compiler option"] ms.assetid: f0e1f3cb-6cae-46eb-9483-04ed13d9b504 no-loc: [UTF, UTF-8, UTF-16] --- -# `/utf-8` (Set Source and Executable character sets to UTF-8) +# `/utf-8` (Set source and execution character sets to UTF-8) Specifies both the source character set and the execution character set as UTF-8. @@ -19,7 +19,7 @@ Specifies both the source character set and the execution character set as UTF-8 You can use the **`/utf-8`** option to specify both the source and execution character sets as encoded by using UTF-8. It's equivalent to specifying **`/source-charset:utf-8 /execution-charset:utf-8`** on the command line. Any of these options also enables the **`/validate-charset`** option by default. For a list of supported code page identifiers and character set names, see [Code Page Identifiers](/windows/win32/Intl/code-page-identifiers). -By default, Visual Studio detects a byte-order mark to determine if the source file is in an encoded Unicode format, for example, UTF-16 or UTF-8. If no byte-order mark is found, it assumes the source file is encoded using the current user code page, unless you've specified a code page by using **`/utf-8`** or the **`/source-charset`** option. Visual Studio allows you to save your C++ source code by using any of several character encodings. For information about source and execution character sets, see [Character Sets](../../cpp/character-sets.md) in the language documentation. +By default, Visual Studio detects a byte-order mark to determine if the source file is in an encoded Unicode format, for example, UTF-16 or UTF-8. If no byte-order mark is found, it assumes that the source file is encoded in the current user code page, unless you've specified a code page by using **`/utf-8`** or the **`/source-charset`** option. Visual Studio allows you to save your C++ source code in any of several character encodings. For information about source and execution character sets, see [Character sets](../../cpp/character-sets.md) in the language documentation. ## Set the option in Visual Studio or programmatically @@ -39,8 +39,8 @@ By default, Visual Studio detects a byte-order mark to determine if the source f ## See also -[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md)
-[/execution-charset (Set Execution Character Set)](execution-charset-set-execution-character-set.md)
-[/source-charset (Set Source Character Set)](source-charset-set-source-character-set.md)
-[/validate-charset (Validate for compatible characters)](validate-charset-validate-for-compatible-characters.md) +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md)\ +[`/execution-charset` (Set execution character set)](execution-charset-set-execution-character-set.md)\ +[`/source-charset` (Set source character set)](source-charset-set-source-character-set.md)\ +[`/validate-charset` (Validate for compatible characters)](validate-charset-validate-for-compatible-characters.md) diff --git a/docs/build/reference/validate-charset-validate-for-compatible-characters.md b/docs/build/reference/validate-charset-validate-for-compatible-characters.md index 34faa7f57f..ec8e1a2a15 100644 --- a/docs/build/reference/validate-charset-validate-for-compatible-characters.md +++ b/docs/build/reference/validate-charset-validate-for-compatible-characters.md @@ -1,43 +1,41 @@ --- description: "Learn more about: /validate-charset (Validate for compatible characters)" title: "/validate-charset (Validate for compatible characters)" -ms.date: "02/06/2019" +ms.date: 01/31/2022 f1_keywords: ["/validate-charset", "validate-charset"] helpviewer_keywords: ["/validate-charset compiler option"] ms.assetid: 50360fd0-4d32-4a4f-95d0-53d38c12ad4c --- -# /validate-charset (Validate for compatible characters) +# `/validate-charset` (Validate for compatible characters) -Validates that the source file text contains only characters representable as UTF-8. +This compiler option validates that the source file text contains only characters representable as UTF-8. ## Syntax -``` -/validate-charset[-] -``` +> **`validate-charset`**[**`-`**] ## Remarks -You can use the **/validate-charset** option to validate that the source code contains only characters that can be represented in both the source character set and the execution character set. This check is enabled automatically when you specify **/source-charset**, **/execution-charset**, or **/utf-8** compiler options. You can explicitly disable this check by specifying the **/validate-charset-** option. +You can use the **`/validate-charset`** option to validate that the source code contains only characters that can be represented in both the source character set and the execution character set. This check is enabled automatically when you specify **`/source-charset`**, **`/execution-charset`**, or **`/utf-8`** compiler options. To explicitly disable this check, specify the **`/validate-charset-`** option. -By default, Visual Studio detects a byte-order mark to determine if the source file is in an encoded Unicode format, for example, UTF-16 or UTF-8. If no byte-order mark is found, it assumes the source file is encoded using the current user code page, unless you have specified a code page by using **/utf-8** or the **/source-charset** option. Visual Studio allows you to save your C++ source code by using any of several character encodings. For information about source and execution character sets, see [Character Sets](../../cpp/character-sets.md) in the language documentation. For a list of supported code page identifiers and character set names, see [Code Page Identifiers](/windows/win32/Intl/code-page-identifiers). +By default, Visual Studio detects a byte-order mark to determine if the source file is in an encoded Unicode format, for example, UTF-16 or UTF-8. If no byte-order mark is found, it assumes that the source file is encoded in the current user code page, unless you have specified a code page by using **`/utf-8`** or the **`/source-charset`** option. Visual Studio allows you to save your C++ source code in any of several character encodings. For information about source and execution character sets, see [Character sets](../../cpp/character-sets.md) in the language documentation. For a list of supported code page identifiers and character set names, see [Code Page Identifiers](/windows/win32/Intl/code-page-identifiers). -Visual Studio uses UTF-8 as the internal character encoding during conversion between the source character set and the execution character set. If a character in the source file cannot be represented in the execution character set, the UTF-8 conversion substitutes a question mark '?' character. The **/validate-charset** option causes the compilation to report a warning if this occurs. +Visual Studio uses UTF-8 as the internal character encoding during conversion between the source character set and the execution character set. If a character in the source file can't be represented in the execution character set, the UTF-8 conversion substitutes a question mark (`?`) character. If a substitution occurs, the **`/validate-charset`** option causes the compiler to report a warning. ### To set this compiler option in the Visual Studio development environment -1. Open the project's **Property Pages** dialog box. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the **Property Pages** dialog box for the project. For more information, 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 the **/validate-charset** option, and specify your preferred encoding. +1. In **Additional Options**, add the **`/validate-charset`** or **`/validate-charset-`** option. 1. Choose **OK** to save your changes. ## See also -[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md)
-[/execution-charset (Set Execution Character Set)](execution-charset-set-execution-character-set.md)
-[/source-charset (Set Source Character Set)](source-charset-set-source-character-set.md)
-[/utf-8 (Set Source and Executable character sets to UTF-8)](utf-8-set-source-and-executable-character-sets-to-utf-8.md) +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md)\ +[`/execution-charset` (Set execution character set)](execution-charset-set-execution-character-set.md)\ +[`/source-charset` (Set source character set)](source-charset-set-source-character-set.md)\ +[`/utf-8` (Set source and execution character sets to UTF-8)](utf-8-set-source-and-executable-character-sets-to-utf-8.md) diff --git a/docs/build/reference/value-visual-cpp.md b/docs/build/reference/value-visual-cpp.md index c718211db3..86aaa58d08 100644 --- a/docs/build/reference/value-visual-cpp.md +++ b/docs/build/reference/value-visual-cpp.md @@ -1,29 +1,29 @@ --- -description: "Learn more about: <value>" -title: "<value> (C++ Documentation Comments)" -ms.date: "11/04/2016" +description: "Learn more about: XML documentation tag " +title: " (C++ Documentation Comments)" +ms.date: 12/03/2021 f1_keywords: [""] helpviewer_keywords: ["value C++ XML tag", " C++ XML tag"] ms.assetid: 0ba0a0d5-bcd7-4862-a169-83f2721ad80e --- -# <value> +# `` documentation tag -The \ tag lets you describe a property and property accessor methods. Note that when you add a property with a code wizard in the Visual Studio integrated development environment, it will add a [\](summary-visual-cpp.md) tag for the new property. You should then manually add a \ tag to describe the value that the property represents. +The `` tag lets you describe a property and property accessor methods. When you add a property with a code wizard in the Visual Studio integrated development environment, it will add a [``](summary-visual-cpp.md) tag for the new property. You need to manually add a `` tag to describe the value that the property represents. ## Syntax -``` -property-description +```cpp +/// property-description ``` -#### Parameters +### Parameters -*property-description*
+*`property-description`*\ A description for the property. ## Remarks -Compile with [/doc](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. +Compile with [`/doc`](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file. ## Example @@ -51,4 +51,4 @@ public: ## See also -[XML Documentation](xml-documentation-visual-cpp.md) +[XML documentation](xml-documentation-visual-cpp.md) diff --git a/docs/build/reference/vcpp-directories-property-page.md b/docs/build/reference/vcpp-directories-property-page.md index a09151f118..4b5daa513b 100644 --- a/docs/build/reference/vcpp-directories-property-page.md +++ b/docs/build/reference/vcpp-directories-property-page.md @@ -1,34 +1,35 @@ --- description: "Learn more about: VC++ Directories Property Page (Windows)" title: "VC++ Directories Property Page" -ms.date: "07/17/2019" -f1_keywords: ["VC.Project.VCDirectories.IncludePath", "VC.Project.VCDirectories.ReferencePath", "VC.Project.VCDirectories.SourcePath", "VC.Project.VCDirectories.LibraryWPath", "VC.Project.VCDirectories.ExecutablePath", "VC.Project.VCDirectories.LibraryPath", "VS.ToolsOptionsPages.Projects.VCDirectories", "VC.Project.VCDirectories.ExcludePath"] +ms.date: 02/17/2022 +f1_keywords: ["VC.Project.VCDirectories.IncludePath", "VC.Project.VCDirectories.ReferencePath", "VC.Project.VCDirectories.SourcePath", "VC.Project.VCDirectories.LibraryWPath", "VC.Project.VCDirectories.ExecutablePath", "VC.Project.VCDirectories.LibraryPath", "VS.ToolsOptionsPages.Projects.VCDirectories", "VC.Project.VCDirectories.ExcludePath", "VC.Project.VCDirectories.ExternalIncludePath", "VC.Project.VCConfiguration.PublicIncludeDirectories", "VC.Project.VCConfiguration.AllProjectIncludesArePublic", "VC.Project.VCConfiguration.PublicModuleDirectories", "VC.Project.VCConfiguration.AllProjectBMIsArePublic"] helpviewer_keywords: ["VC++ Directories Property Page"] -ms.assetid: 428eeef6-f127-4271-b3ea-0ae6f2c3d624 --- # VC++ Directories Property Page (Windows) -Use this property page to tell Visual Studio which directories to use when building the currently-selected project. To set directories for multiple projects in a solution, use a custom property sheet as described in [Share or reuse Visual Studio C++ project settings](../create-reusable-property-configurations.md). +Use this property page to tell Visual Studio which directories to use when building the currently selected project. To set directories for multiple projects in a solution, use a custom property sheet as described in [Share or reuse Visual Studio C++ project settings](../create-reusable-property-configurations.md). For the Linux version of this page, see [VC++ Directories (Linux C++)](../../linux/prop-pages/directories-linux.md). To access the **VC++ Directories** property page: -1. If the **Solution Explorer** window is not visible, then on the main menu choose **View** > **Solution Explorer**. +1. If the **Solution Explorer** window isn't visible, choose **View** > **Solution Explorer** on the main menu. 1. Right-click on a project node (not the top-level solution) and choose **Properties** to open the **Property Pages** dialog box. 1. Select the **Configuration Properties** > **VC++ Directories** property page. -VC++ Directories properties apply to a project, not the top-level solution node. If you do not see **VC++ Directories** under **Configuration Properties**, select a C++ project node in the **Solution Explorer** window: +VC++ Directories properties apply to a project, not the top-level solution node. If you don't see **VC++ Directories** under **Configuration Properties**, select a C++ project node in the **Solution Explorer** window: -![Select the project node](../media/vcppdir.png "Select the project node to see the VC++ Directories properties") +:::image type="complex" source="../media/vcppdir.png" alt-text="Screenshot of the Solution Explorer window with the Project node selected."::: +In the property pages dialog, Configuration properties > VC++ directories is selected. The various C++ directories are listed, such as: executable directories, include directories, library directories, source directories, and so on. +:::image-end::: -Note that the **VC++ Directories** property page for cross-platform projects looks different. For information specific to Linux C++ projects, see [VC++ Directories (Linux C++)](../../linux/prop-pages/directories-linux.md). +The **VC++ Directories** property page for cross-platform projects looks different. For information specific to Linux C++ projects, see [VC++ Directories (Linux C++)](../../linux/prop-pages/directories-linux.md). -If you are not familiar with *project properties* in Visual Studio, you might find it helpful to first read [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +If you're not familiar with *project properties* in Visual Studio, you might find it helpful to first read [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). -The default settings for **VC++ Directories** properties depend on project type. For desktop projects they include the C++ tools locations for a particular Platform Toolset and the Windows SDK location. You can change the **Platform Toolset** and **Windows SDK version** on the **Configuration Properties** > **General** page. +The default settings for **VC++ Directories** properties depend on project type. For desktop projects, they include the C++ tools locations for a particular Platform Toolset and the Windows SDK location. You can change the **Platform Toolset** and **Windows SDK version** on the **Configuration Properties** > **General** page. To view the values for any of the directories: @@ -36,59 +37,80 @@ To view the values for any of the directories: 1. Choose the down-arrow button at the end of the property value field. 1. In the drop-down menu, choose **Edit**. -![Edit Library Directories](../media/vcppdir_libdir_edit.png "Dialog to edit library paths") +![Detail of the Library Directories property drop-down with the Edit command highlighted.](../media/vcppdir_libdir_edit.png "Dialog to edit library paths") You now see a dialog box like this: -![Show Library Directories](../media/vcppdir_libdir.png "Dialog to add or remove library paths") +:::image type="complex" source="../media/vcppdir_libdir.png" alt-text="Screenshot of the Library Directories dialog."::: +The library directories dialog has a library directories area and an evaluated value area that shows the path values after all macros have been expanded. There's an inherited values area that shows the macro values inherited from the parent or the project. There's a checkbox, checked, that says Inherit from parent or project defaults. There's a macros button and an OK and Cancel button. +:::image-end::: -Use this dialog to view the current directories. However, if you want to change or add a directory, it is better to use **Property Manager** to create a property sheet or modify the default user property sheet. For more information, see [Share or reuse Visual Studio C++ project settings](../create-reusable-property-configurations.md). +Use this dialog to view the current directories. However, if you want to change or add a directory, it's better to use **Property Manager** to create a property sheet or modify the default user property sheet. For more information, see [Share or reuse Visual Studio C++ project settings](../create-reusable-property-configurations.md). -As shown above, many of the inherited paths are given as macros. To examine the current value of a macro, choose the **Macros** button in the lower right corner of the dialog box. Note that many macros depend on the configuration type. A macro in a debug build might evaluate to a different path than the same macro in a release build. +As shown earlier, many of the inherited paths are provided as macros. To examine the current value of a macro, choose the **Macros** button in the lower right corner of the dialog box. Many macros depend on the configuration type. A macro in a debug build might evaluate to a different path than the same macro in a release build, for example. For information about examining macros values, see [Common macros for build commands and properties](common-macros-for-build-commands-and-properties.md). -You can search for partial or complete matches in the edit box. The following illustration shows all the macros that contain the string "WindowsSDK" and it also shows the current path that the macro evaluates to: +You can search for partial or complete matches of a macro in the edit box. The following screenshot shows all the macros that contain the string "WindowsSDK". It also shows the current path that each macro evaluates to: -![See macro values](../media/vcppdir_libdir_macros.png "Dialog to edit macros") +:::image type="complex" source="../media/vcppdir_libdir_macros.png" alt-text="Screenshot of the Library Directories dialog with the list of macro values displayed."::: +The Library Directories dialog is shown, and a filtered list of macros. Results include macros that contain the string "WindowsSDK", such as $ ( Windows SDK _ Executable Path ), $ ( Windows SDK _ Include Path ), $ ( Windows SDK _ Library Path ), and more. There's an inherited values area that shows which macro values are inherited from a parent or project. There's an evaluated value area that shows the path values after all macros have been expanded. There's a checkbox, checked, that says Inherit from parent or project defaults. There's a macros button and an Insert, OK, and Cancel button. +:::image-end::: -Note: The list is populated as you type. Don't press **Enter**. +This list is populated as you type. Don't press **Enter**. For more information about macros and why you should use them instead of hard-coded paths whenever possible, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). -For a list of commonly used macros, see [Common macros for build commands and properties](common-macros-for-build-commands-and-properties.md). +For information about examining the values of the macros, see [Common macros for build commands and properties](common-macros-for-build-commands-and-properties.md). That topic also lists commonly used macros. You can define your own macros in two ways: - Set environment variables in a developer command prompt. All environment variables are treated as MSBuild properties/macros. -- Define user macros in a .props file. For more information, see [Property page macros](../working-with-project-properties.md). +- Define user macros in a *`.props`* file. For more information, see [Property page macros](../working-with-project-properties.md). For more information, see [Property inheritance in Visual Studio projects](../project-property-inheritance.md), and these blog posts: [VC++ Directories](/archive/blogs/vsproject/vc-directories), [Visual Studio 2010 C++ Project Upgrade Guide](https://devblogs.microsoft.com/cppblog/visual-studio-2010-c-project-upgrade-guide/). -## Directory Types +## General You can also specify other directories, as follows. -**Executable Directories**
-Directories in which to search for executable files. Corresponds to the **PATH** environment variable. +**Executable Directories**\ +Directories in which to search for executable files. Corresponds to the **`PATH`** environment variable. -**Include Directories**
-Directories in which to search for include files that are referenced in the source code. Corresponds to the **INCLUDE** environment variable. +**Include Directories**\ +Directories in which to search for include files that are referenced in the source code. Corresponds to the **`INCLUDE`** environment variable. -**Reference Directories**
-Directories in which to search for assembly and module (metadata) files that are referenced in the source code by the [#using](../../preprocessor/hash-using-directive-cpp.md) directive. Corresponds to the **LIBPATH** environment variable. +**External Include Directories**\ +Paths for include files to treat as external or system files during compilation. These files are skipped in build up-to-date checks. These paths are also used by the [External Includes](c-cpp-prop-page.md#external-includes) properties. For more information on how to set these options in the IDE, see the [`/external`](../../build/reference/external-external-headers-diagnostics.md) compiler option. -**Library Directories**
-Directories in which to search for libraries (.lib) files; this includes run-time libraries. Corresponds to the **LIB** environment variable. This setting does not apply to .obj files; to link to an .obj file, on the **Configuration Properties** > **Linker** > **General** property page, select **Additional Library Dependencies** and then specify the relative path of the file. For more information, see [Linker property pages](linker-property-pages.md). +**Reference Directories**\ +Directories in which to search for assembly and module (metadata) files that are referenced in the source code by the [#using](../../preprocessor/hash-using-directive-cpp.md) directive. Corresponds to the **`LIBPATH`** environment variable. -**Library WinRT Directories**
+**Library Directories**\ +Directories to search for library (*`.lib`*) files. This search includes run-time libraries. Corresponds to the **`LIB`** environment variable. This setting doesn't apply to *`.obj`* files; to link to an *`.obj`* file, on the **Configuration Properties** > **Linker** > **General** property page, select **Additional Library Dependencies** and then specify the relative path of the file. For more information, see [Linker property pages](linker-property-pages.md). + +**Library WinRT Directories**\ Directories to search for WinRT library files for use in Universal Windows Platform (UWP) apps. -**Source Directories**
+**Source Directories**\ Directories in which to search for source files to use for IntelliSense. -**Exclude Directories**
+**Exclude Directories**\ Before each compilation, Visual Studio queries the timestamp on all files to determine whether any have been modified since the previous compilation. If your project has large stable libraries, you can potentially speed up build times by excluding those directories from the timestamp check. -## Sharing the Settings +## Public Project Content + +**Public Include Directories**\ +One or more directories to automatically add to the include path in projects that reference this project. + +**All Header Files are Public**\ +Specifies whether to automatically add public directories or all project header files to the include path in projects that reference this project. + +**Public C++ Module Directories**\ +One or more directories that contain C++ module or header unit sources to make available automatically to projects that reference this project. + +**All Modules are Public**\ +Specifies whether to make all project modules and header units available automatically to projects that reference this project. + +## Sharing the settings You can share project properties with other users or across multiple computers. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). diff --git a/docs/build/reference/vcxproj-file-structure.md b/docs/build/reference/vcxproj-file-structure.md index 0f0cd77c75..0ce1e28fb5 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 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). -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. diff --git a/docs/build/reference/vcxproj-filters-files.md b/docs/build/reference/vcxproj-filters-files.md index fbcb8dcf19..f03ac67005 100644 --- a/docs/build/reference/vcxproj-filters-files.md +++ b/docs/build/reference/vcxproj-filters-files.md @@ -6,19 +6,21 @@ helpviewer_keywords: ["vcxproj.filters", "filters file [C++]"] --- # vcxproj.filters files -The *filters* file (\*.vcxproj.filters) is an XML file in MSBuild format that is located in the root project folder. It specifies which file types go into which logical folder in **Solution Explorer**. In the following illustration, the *.cpp* files are under the **Source Files** node. the *.h* files are under the **Header Files** node, and *.ico* and *.rc* files are under **Resource Files**. This placement is controlled by the filters file. +The *filters* file (`*.vcxproj.filters`) is an XML file in MSBuild format that is located in the root project folder. It specifies which file types go into which logical folder in **Solution Explorer**. In the following illustration, the `.cpp` files are under the **Source Files** node. the `.h` files are under the **Header Files** node, and `.ico` and `.rc` files are under **Resource Files**. This placement is controlled by the filters file. -![Logical folders in Solution Explorer](media/solution-explorer-filters.png) +:::image type="complex" source="media/solution-explorer-filters.png" alt-text="Screenshot of the Logical folders view in Solution Explorer."::: +The solution explorer is shown with call outs for the following nodes: Header Files (which contains files like MFCApplication1.h), Resource Files (which contains files like MFCApplication1.ico), and Source Files (which contains files like MFCApplication1.cpp). +:::image-end::: ## Creating a custom filters file -Visual Studio creates this file automatically. For desktop applications, the predefined logical folders (filters) are: **Source Files**, **Header Files** and **Resource Files**. Other project types such as UWP might have a different set of default folders. Visual Studio automatically assigns known file types to each folder. If you want to create a filter with a custom name or a filter that holds custom file types, you can create your own filters file in the root folder of the project, or under an existing filter. (**References** and **External Dependencies** are special folders that do not participate in filtering.) +Visual Studio creates this file automatically. For desktop applications, the predefined logical folders (filters) are: **Source Files**, **Header Files** and **Resource Files**. Other project types such as UWP might have a different set of default folders. Visual Studio automatically assigns known file types to each folder. If you want to create a filter with a custom name or a filter that holds custom file types, you can create your own filters file in the root folder of the project, or under an existing filter. (**References** and **External Dependencies** are special folders that don't participate in filtering.) ## Example -The following example shows the filters file for the example show previously. It has a flat hierarchy; in other words, there are no nested logical folders. The `UniqueIdentifier` node is optional. It enables Visual Studio automation interfaces to find the filter. `Extensions` is also optional. When a new file is added to a project, it is added to the topmost filter with a matching file extension. To add a file to a specific filter, right-click on the filter and choose **Add New Item**. +The following example shows the filters file for the example show previously. It has a flat hierarchy; in other words, there are no nested logical folders. The `UniqueIdentifier` node is optional. It enables Visual Studio automation interfaces to find the filter. `Extensions` is also optional. When a new file is added to a project, it's added to the topmost filter with a matching file extension. To add a file to a specific filter, right-click on the filter and choose **Add New Item**. -The `ItemGroup` that contains the `ClInclude` nodes is created when the project is first launched. If you are generating your own vcxproj files, make sure that all project items also have an entry in the filters file. Values in a `ClInclude` node override the default filtering based on file extensions. When you use Visual Studio to add a new item to the project, the IDE will add an individual file entry in the filters file. The filter is not automatically reassigned if you change the file's extension. +The `ItemGroup` that contains the `ClInclude` nodes is created when the project is first launched. If you're generating your own vcxproj files, make sure that all project items also have an entry in the filters file. Values in a `ClInclude` node override the default filtering based on file extensions. When you use Visual Studio to add a new item to the project, the IDE adds an individual file entry in the filters file. The filter isn't automatically reassigned if you change the file's extension. ```xml @@ -83,7 +85,7 @@ The `ItemGroup` that contains the `ClInclude` nodes is created when the project ``` -To create nested logical folders, declare all nodes in filters `ItemGroup` as shown below. Each child node must declare the full logical path to the topmost parent. In the following example, an empty `ParentFilter` must be declared because it is referenced in later nodes. +To create nested logical folders, declare all nodes in filters `ItemGroup` as shown below. Each child node must declare the full logical path to the topmost parent. In the following example, an empty `ParentFilter` must be declared because it's referenced in later nodes. ```xml diff --git a/docs/build/reference/version-version-information.md b/docs/build/reference/version-version-information.md index 9d3cbf2c2c..d4ab8a430e 100644 --- a/docs/build/reference/version-version-information.md +++ b/docs/build/reference/version-version-information.md @@ -1,31 +1,29 @@ --- -description: "Learn more about: /VERSION (Version Information)" -title: "/VERSION (Version Information)" -ms.date: "11/04/2016" +description: "Learn more about: /VERSION (Version information)" +title: "/VERSION (Version information)" +ms.date: 03/02/2022 f1_keywords: ["VC.Project.VCLinkerTool.Version", "/version"] helpviewer_keywords: ["-VERSION linker option", "Version Information linker option", "version numbers, specifying in .exe", "/VERSION linker option", "VERSION linker option"] ms.assetid: b86d0e86-dca6-4316-aee2-d863ccb9f223 --- -# /VERSION (Version Information) +# `/VERSION` (Version information) -``` -/VERSION:major[.minor] -``` +> **`/VERSION:`***`major`*\[*`.minor`*] ## Arguments -*major* and *minor*
-The version number you want in the header of the .exe or .dll file. +*`major`* and *`minor`*
+The version number you want in the header of the EXE or DLL file. ## Remarks -The /VERSION option tells the linker to put a version number in the header of the .exe or .dll file. Use DUMPBIN [/HEADERS](headers.md) to see the image version field of the OPTIONAL HEADER VALUES to see the effect of /VERSION. +The **`/VERSION`** option tells the linker to put a version number in the header of the EXE or DLL file. Use [`DUMPBIN /HEADERS`](headers.md) to see the image version field of the `OPTIONAL HEADER VALUES` to see the effect of **`/VERSION`**. -The *major* and *minor* arguments are decimal numbers in the range 0 through 65,535. The default is version 0.0. +The *`major`* and *`minor`* arguments are decimal numbers in the range 0 through 65,535. The default is version `0.0`. -The information specified with /VERSION does not affect the version information that appears for an application when you view its properties in File Explorer. That version information comes from a resource file that is used to build the application. See [Version Information Editor](../../windows/version-information-editor.md) for more information. +The information specified with **`/VERSION`** doesn't affect the version information that appears for an application when you view its properties in File Explorer. That version information comes from a resource file that's used to build the application. For more information, see [Version Information Editor](../../windows/version-information-editor.md). -Another way to insert a version number is with the [VERSION](version-c-cpp.md) module-definition statement. +Another way to insert a version number is with the [`VERSION`](version-c-cpp.md) module-definition statement. ### To set this linker option in the Visual Studio development environment @@ -41,5 +39,5 @@ Another way to insert a version number is with the [VERSION](version-c-cpp.md) m ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/vlen.md b/docs/build/reference/vlen.md new file mode 100644 index 0000000000..6557c219ef --- /dev/null +++ b/docs/build/reference/vlen.md @@ -0,0 +1,52 @@ +--- +description: "Learn more about: /vlen" +title: "/vlen" +ms.date: 09/24/2024 +f1_keywords: ["/vlen", "-vlen"] +helpviewer_keywords: ["specify vector length", "-vlen compiler option [C++]", "vlen compiler option [C++]", "/vlen compiler option [C++]"] +--- +# `/vlen` + +Specifies the vector length for code generation on x86 and x64. For more information about **`/arch`** for x86 and x64, see [`/arch` (x86)](arch-x86.md) and [`/arch` (x64)](arch-x64.md). + +## Syntax + +> **`/vlen=`**\[**`256`**|**`512`**] + +> **`/vlen`** + +## Arguments + +**`/vlen=256`**\ +Specify a vector length of 256 bits for auto-vectorization and other optimizations. + +**`/vlen=512`**\ +Specify a vector length of 512 bits for auto-vectorization and other optimizations. + +**`/vlen`**\ +Specify the default vector length for the selected **`/arch`** setting. + +## Remarks + +If a specific **`/vlen`** value isn't specified, the default vector length depends on the **`/arch`** flag setting. The **`/vlen`** flag can override the default vector length specified by **`/arch:AVX512`** or **`/arch:AVX10.1`** flag. For example: + +- **`/arch:AVX512 /vlen=256`** overrides the default vector length of 512 bits specified by **`/arch:AVX512`** to be 256 bits. +- **`/arch:AVX10.1 /vlen=512`** overrides the default vector length of 256 bits specified by **`/arch:AVX10.1`** to be 512 bits. + +When the specified **`/vlen`** value is incompatible with specified **`/arch`** flag, a warning is generated and default vector length for the **`/arch`** setting is used. For example: + +- **`/arch:AVX2 /vlen=512`** generates a warning because AVX2 doesn't support 512-bit vectors. Vector length of 256 bits is used in this case. + +### To set the `/vlen=256` or `/vlen=512` compiler option in Visual Studio + +1. Open the **Property Pages** dialog box for the project. For more information, 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 the **Additional options** box, add *`/vlen=256`* or *`/vlen=512`*. Choose **OK** to save your changes. + +## See also + +[`/arch` (Minimum CPU Architecture)](arch-minimum-cpu-architecture.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/vmm-vms-vmv-general-purpose-representation.md b/docs/build/reference/vmm-vms-vmv-general-purpose-representation.md index d3d3a46753..eb33799c9c 100644 --- a/docs/build/reference/vmm-vms-vmv-general-purpose-representation.md +++ b/docs/build/reference/vmm-vms-vmv-general-purpose-representation.md @@ -54,7 +54,6 @@ When you specify one of these inheritance-model options, that model gets used fo 1. Enter the compiler option in the **Additional Options** box. - ### To set this compiler option programmatically - See . diff --git a/docs/build/reference/volatile-volatile-keyword-interpretation.md b/docs/build/reference/volatile-volatile-keyword-interpretation.md index e0f9e10d37..8e54521e89 100644 --- a/docs/build/reference/volatile-volatile-keyword-interpretation.md +++ b/docs/build/reference/volatile-volatile-keyword-interpretation.md @@ -17,10 +17,10 @@ Specifies how the [volatile](../../cpp/volatile-cpp.md) keyword is to be interpr ## Arguments **/volatile:iso**
-Selects strict **`volatile`** semantics as defined by the ISO-standard C++ language. Acquire/release semantics are not guaranteed on volatile accesses. If the compiler targets ARM, this is the default interpretation of **`volatile`**. +Selects strict **`volatile`** semantics as defined by the ISO-standard C++ language. Acquire/release semantics are not guaranteed on volatile accesses. If the compiler targets ARM (except ARM64EC), this is the default interpretation of **`volatile`**. **/volatile:ms**
-Selects Microsoft extended **`volatile`** semantics, which add memory ordering guarantees beyond the ISO-standard C++ language. Acquire/release semantics are guaranteed on volatile accesses. However, this option also forces the compiler to generate hardware memory barriers, which might add significant overhead on ARM and other weak memory-ordering architectures. If the compiler targets any platform except ARM, this is default interpretation of **`volatile`**. +Selects Microsoft extended **`volatile`** semantics, which add memory ordering guarantees beyond the ISO-standard C++ language. Acquire/release semantics are guaranteed on volatile accesses. However, this option also forces the compiler to generate hardware memory barriers, which might add significant overhead on ARM and other weak memory-ordering architectures. If the compiler targets ARM64EC or any non-ARM platform, this is default interpretation of **`volatile`**. ## Remarks diff --git a/docs/build/reference/volatile.md b/docs/build/reference/volatile.md new file mode 100644 index 0000000000..fb3cced847 --- /dev/null +++ b/docs/build/reference/volatile.md @@ -0,0 +1,40 @@ +--- +description: "Learn more about: /volatileMetadata" +title: "/volatileMetadata (Generate metadata on volatile memory accesses)" +ms.date: 5/30/2024 +f1_keywords: ["/volatileMetadata"] +helpviewer_keywords: ["/volatileMetadata", "-volatileMetadata compiler option", "/volatileMetadata compiler option", "volatileMetadata"] +--- +# `/volatileMetadata` (Generate metadata on volatile memory accesses) + +Generate metadata for volatile memory accesses to improve performance when running x64 code on ARM64. + +## Syntax + +```cpp +/volatileMetadata[-] +``` + +## Arguments + +**`-`**\ +Turns off `/volatileMetadata`. This may result in worse performance when your code runs in emulation mode on ARM64 because the emulator pessimistically assumes that every load/store needs a barrier. + +## Remarks + +Starting with Visual Studio 2019 16.10, `/volatileMetadata` is on by default when generating x64 code. It improves the emulation performance of x64 code on ARM64 by generating metadata that identifies volatile memory addresses. An emulator can use this metadata to improve performance by not using acquire/release semantics on those accesses it knows aren't volatile. Without this metadata, the emulator assumes that all addresses are volatile and uses acquire and release semantics. + +One side effect of `/volatileMetadata` is you may see `npad` macros used in the generated code. This macro expands to a specified number of `NOP` instructions that create an address to associate with a memory barrier. That address is then recorded in the metadata to indicate that acquire/release semantics should be used to access it. + +`/volatileMetadata` is ignored when targeting x86. + +`/volatileMetadata` can be disabled by using `/volatileMetadata-`. + +## Requirements + +Visual Studio 2019 version 16.10 or later. + +## See also + +[MSVC Compiler Options](compiler-options.md)\ +[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/where-to-define-macros.md b/docs/build/reference/where-to-define-macros.md deleted file mode 100644 index ca82e3257d..0000000000 --- a/docs/build/reference/where-to-define-macros.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -description: "Learn more about: Where to Define Macros" -title: "Where to Define Macros" -ms.date: "11/04/2016" -helpviewer_keywords: ["defining macros", "macros, NMAKE", "NMAKE program, defining macros"] -ms.assetid: 0fc59ec5-5f58-4644-b7da-7b021f7001af ---- -# Where to Define Macros - -Define macros in a command line, command file, makefile, or the Tools.ini file. - -In a makefile or the Tools.ini file, each macro definition must appear on a separate line and cannot start with a space or tab. Spaces or tabs around the equal sign are ignored. All [string characters](defining-an-nmake-macro.md) are literal, including surrounding quotation marks and embedded spaces. - -In a command line or command file, spaces and tabs delimit arguments and cannot surround the equal sign. If `string` has embedded spaces or tabs, enclose either the string itself or the entire macro in double quotation marks (" "). - -## See also - -[Defining an NMAKE Macro](defining-an-nmake-macro.md) diff --git a/docs/build/reference/wholearchive-include-all-library-object-files.md b/docs/build/reference/wholearchive-include-all-library-object-files.md index 4a1addad37..dafe4bcd5f 100644 --- a/docs/build/reference/wholearchive-include-all-library-object-files.md +++ b/docs/build/reference/wholearchive-include-all-library-object-files.md @@ -1,8 +1,7 @@ --- description: "Learn more about: /WHOLEARCHIVE (Include All Library Object Files)" title: "/WHOLEARCHIVE (Include All Library Object Files)" -ms.date: "02/12/2020" -ms.assetid: ee92d12f-18af-4602-9683-d6223be62ac9 +ms.date: 03/27/2025 --- # /WHOLEARCHIVE (Include All Library Object Files) @@ -15,26 +14,24 @@ Force the linker to include all object files in the static library in the linked ### Arguments -*library*\ -An optional pathname to a static library. The linker includes every object file from this library. +*`library`*\ +An optional pathname to a static library. The linker includes every object file from this library. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). ## Remarks -The /WHOLEARCHIVE option forces the linker to include every object file from either a specified static library, or if no library is specified, from all static libraries specified to the LINK command. To specify the /WHOLEARCHIVE option for multiple libraries, you can use more than one /WHOLEARCHIVE switch on the linker command line. By default, the linker includes object files in the linked output only if they export symbols referenced by other object files in the executable. The /WHOLEARCHIVE option makes the linker treat all object files archived in a static library as if they were specified individually on the linker command line. +The `/WHOLEARCHIVE` option forces the linker to include every object file from either a specified static library, or if no library is specified, from all static libraries specified to the LINK command. To specify the `/WHOLEARCHIVE` option for multiple libraries, you can use more than one `/WHOLEARCHIVE` switch on the linker command line. By default, the linker includes object files in the linked output only if they export symbols referenced by other object files in the executable. The `/WHOLEARCHIVE` option makes the linker treat all object files archived in a static library as if they were specified individually on the linker command line. -The /WHOLEARCHIVE option can be used to re-export all the symbols from a static library. This allows you to make sure that all of your library code, resources, and metadata are included when you create a component from more than one static library. If you see warning LNK4264 when you create a static library that contains Windows Runtime components for export, use the /WHOLEARCHIVE option when linking that library into another component or app. +The `/WHOLEARCHIVE` option can be used to re-export all the symbols from a static library. This allows you to make sure that all of your library code, resources, and metadata are included when you create a component from more than one static library. If you see warning LNK4264 when you create a static library that contains Windows Runtime components for export, use the `/WHOLEARCHIVE` option when linking that library into another component or app. -The /WHOLEARCHIVE option was introduced in Visual Studio 2015 Update 2. +The `/WHOLEARCHIVE` option was introduced in Visual Studio 2015 Update 2. ### To set this linker option in Visual Studio 1. Open the project **Property Pages** dialog box. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). - 1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. - 1. Add the *`/WHOLEARCHIVE`* option to the **Additional Options** text box. ## See also -[MSVC linker reference](linking.md)
+[MSVC linker reference](linking.md)\ [MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/wildcards-and-nmake.md b/docs/build/reference/wildcards-and-nmake.md deleted file mode 100644 index 41ff2ca211..0000000000 --- a/docs/build/reference/wildcards-and-nmake.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -description: "Learn more about: Wildcards and NMAKE" -title: "Wildcards and NMAKE" -ms.date: "11/04/2016" -helpviewer_keywords: ["NMAKE program, wildcards", "wildcards, expanding"] -ms.assetid: 8f5d4b2a-8fa7-46a9-92ac-c8185c99239b ---- -# Wildcards and NMAKE - -NMAKE expands filename wildcards (\* and ?) in dependency lines. A wildcard specified in a command is passed to the command; NMAKE does not expand it. - -## See also - -[Contents of a Makefile](contents-of-a-makefile.md) diff --git a/docs/build/reference/winmd-generate-windows-metadata.md b/docs/build/reference/winmd-generate-windows-metadata.md index d87f06e155..4694f1f317 100644 --- a/docs/build/reference/winmd-generate-windows-metadata.md +++ b/docs/build/reference/winmd-generate-windows-metadata.md @@ -24,7 +24,7 @@ The linker generates only the .winmd file, but not the binary executable file. ## Remarks -The **/WINMD** linker option is used for UWP apps and Windows runtime components to control the creation of a Windows Runtime metadata (.winmd) file. A .winmd file is a kind of DLL that contains metadata for Windows runtime types and, in the case of runtime components, the implementations of those types. The metadata follows the [ECMA-335](https://www.ecma-international.org/publications/standards/Ecma-335.htm) standard. +The **/WINMD** linker option is used for UWP apps and Windows runtime components to control the creation of a Windows Runtime metadata (.winmd) file. A .winmd file is a kind of DLL that contains metadata for Windows runtime types and, in the case of runtime components, the implementations of those types. The metadata follows the [ECMA-335](https://ecma-international.org/publications-and-standards/standards/ecma-335/) standard. By default, the output file name has the form *binaryname*.winmd. To specify a different file name, use the [/WINMDFILE](winmdfile-specify-winmd-file.md) option. diff --git a/docs/build/reference/winmdfile-specify-winmd-file.md b/docs/build/reference/winmdfile-specify-winmd-file.md index fb489848b5..69f135c446 100644 --- a/docs/build/reference/winmdfile-specify-winmd-file.md +++ b/docs/build/reference/winmdfile-specify-winmd-file.md @@ -1,21 +1,25 @@ --- -description: "Learn more about: /WINMDFILE (Specify winmd File)" title: "/WINMDFILE (Specify winmd File)" -ms.date: "11/04/2016" +description: "Learn more about: /WINMDFILE (Specify winmd File)" +ms.date: 03/27/2025 f1_keywords: ["VC.Project.VCLinkerTool.GenerateWindowsMetadataFile"] -ms.assetid: 062b41b3-14d6-432c-a361-fdb66e918931 --- # /WINMDFILE (Specify winmd File) -Specifies the file name for the Windows Runtime Metadata (.winmd) output file that is generated by the [/WINMD](winmd-generate-windows-metadata.md) linker option. +Specifies the filename for the Windows Runtime Metadata (`.winmd`) output file that is generated by the [`/WINMD`](winmd-generate-windows-metadata.md) linker option. ``` /WINMDFILE:filename ``` +## Argument + +*`filename`*\ +The filename for `.winmd` output file. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). + ## Remarks -Use the value that is specified in `filename` to override the default .winmd file name (`binaryname`.winmd). Notice that you do not append ".winmd" to `filename`. If multiple values are listed on the **/WINMDFILE** command line, the last one takes precedence. +Use the value that is specified in `filename` to override the default `.winmd` file name (`binaryname`.winmd). Don't append `".winmd"` to `filename`. If multiple values are listed on the **`/WINMDFILE`** command line, the last one takes precedence. The resulting name when combined with `.winmd` must not exceed `MAX_PATH` (260 characters). ### To set this linker option in the Visual Studio development environment @@ -27,6 +31,6 @@ Use the value that is specified in `filename` to override the default .winmd fil ## See also -[/WINMD (Generate Windows Metadata)](winmd-generate-windows-metadata.md)
-[MSVC linker reference](linking.md)
+[`/WINMD` (Generate Windows Metadata)](winmd-generate-windows-metadata.md)\ +[MSVC linker reference](linking.md)\ [MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/wx-treat-linker-warnings-as-errors.md b/docs/build/reference/wx-treat-linker-warnings-as-errors.md index 0d1b027b34..881a1ae174 100644 --- a/docs/build/reference/wx-treat-linker-warnings-as-errors.md +++ b/docs/build/reference/wx-treat-linker-warnings-as-errors.md @@ -1,38 +1,50 @@ --- -description: "Learn more about: /WX (Treat Linker Warnings as Errors)" -title: "/WX (Treat Linker Warnings as Errors)" -ms.date: "11/04/2016" -f1_keywords: ["/WX"] +description: "Learn more about: /WX (Treat linker warnings as errors)" +title: "/WX (Treat linker warnings as errors)" +ms.date: 02/02/2023 +f1_keywords: ["VC.Project.VCLinkerTool.TreatLinkerWarningsAsErrors"] helpviewer_keywords: ["/WX linker option", "-WX linker option", "WX linker option"] ms.assetid: e4ba97c7-93f7-43ae-a4bb-d866790926c9 --- -# /WX (Treat Linker Warnings as Errors) +# `/WX` (Treat linker warnings as errors) -``` -/WX[:NO] -``` +Specifies whether to treat linker warnings as errors. + +## Syntax + +> **`/WX`**\[**`:NO`**]\ +> **`/WX`**\[**`:`***`nnnn`*\[**`,`***`nnnn`*...]] ## Remarks -/WX causes no output file to be generated if the linker generates a warning. +The **`/WX`** linker option causes no output file to be generated if the linker generates a warning. + +This option is similar to **`/WX`** for the compiler. For more information, see [/w, /W0, /W1, /W2, /W3, /W4, /w1, /w2, /w3, /w4, /Wall, /wd, /we, /wo, /Wv, /WX (Warning Level)](compiler-option-warning-level.md). However, specifying **`/WX`** for the compilation doesn't imply that **`/WX`** will also be in effect for the link phase; you must explicitly specify **`/WX`** for each tool. -This option is similar to **/WX** for the compiler. For more information, see [/w, /W0, /W1, /W2, /W3, /W4, /w1, /w2, /w3, /w4, /Wall, /wd, /we, /wo, /Wv, /WX (Warning Level)](compiler-option-warning-level.md). However, specifying **/WX** for the compilation doesn't imply that **/WX** will also be in effect for the link phase; you must explicitly specify **/WX** for each tool. +In Visual Studio 2022 and later versions, you can specify **`/WX`** with one or more comma-separated *`nnnn`* arguments, where *`nnnn`* is a number between 4000 and 4999. The linker treats the corresponding *`LNKnnnn`* warnings as errors. -By default, **/WX** is not in effect. To treat linker warnings as errors, specify **/WX**. **/WX:NO** is the same as not specifying **/WX**. +By default, **`/WX`** isn't in effect. To treat linker warnings as errors, specify a **`/WX`** option. **`/WX:NO`** is the same as not specifying **`/WX`**, and overrides any previous **`/WX`** linker option. ### To set this linker option in the Visual Studio development environment -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. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). + +1. To set or unset all warnings as errors, select the **Configuration Properties** > **Linker** > **General** property page. + +1. Modify the **Treat Linker Warnings as Errors** property. + +1. To set specific warnings as errors, select the **Configuration Properties** > **Linker** > **Command Line** property page. -1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. +1. In the **Additional Options** edit control, add *`/WX:warnings`*, where *`warnings`* is a comma-separated list of linker warning numbers. -1. Enter the option into the **Additional Options** box. +1. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically -1. See . +- See . ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md)\ +[`/WX` compiler option](./compiler-option-warning-level.md) diff --git a/docs/build/reference/xdcmake-reference.md b/docs/build/reference/xdcmake-reference.md index 23a9a00438..64bb96cb6d 100644 --- a/docs/build/reference/xdcmake-reference.md +++ b/docs/build/reference/xdcmake-reference.md @@ -1,16 +1,16 @@ --- description: "Learn more about: XDCMake Reference" title: "XDCMake Reference" -ms.date: "11/04/2016" +ms.date: 12/03/2021 f1_keywords: ["xdcmake"] helpviewer_keywords: ["xdcmake program"] ms.assetid: 14e65747-d000-4343-854b-8393bf01cbac --- # XDCMake Reference -xdcmake.exe is a program that compiles .xdc files into an .xml file. An .xdc file is created by the MSVC compiler for each source code file when source code is compiled with [/doc](doc-process-documentation-comments-c-cpp.md) and when the source code file contains documentation comments marked up with XML tags. +The xdcmake.exe program compiles XDC files into an XML file. An XDC file is created by the MSVC compiler for each source code file when source code is compiled with [`/doc`](doc-process-documentation-comments-c-cpp.md) and when the source code file contains documentation comments marked up with XML tags. -### To use xdcmake.exe in the Visual Studio development environment +## To use xdcmake.exe in the Visual Studio development environment 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). @@ -23,29 +23,29 @@ xdcmake.exe is a program that compiles .xdc files into an .xml file. An .xdc fil ## Syntax -xdcmake `input_filename options` +`xdcmake input_filename options` ## Parameters -*input_filename*
-The file name of the *`.xdc`* files used as input to xdcmake.exe. Specify one or more *`.xdc`* files or use *.xdc to use all *`.xdc`* files in the current directory. +*`input_filename`*\ +The file name of the XDC files used as input to xdcmake.exe. Specify one or more XDC files or use `*.xdc` to use all XDC files in the current directory. -*options*
-Zero or more of the following: +*`options`*\ +You can supply zero or more of the following options: -|Option|Description| -|------------|-----------------| -|`/?`, `/help`|Display help for xdcmake.exe.| -|`/assembly:filename`|Lets you specify the value of the \ tag in the .xml file. By default, the value of the \ tag is the same as the filename of the .xml file.| -|/nologo|Suppress copyright message.| -|`/out:filename`|Lets you specify the name of the .xml file. By default, the name of the .xml file is the filename of the first .xdc file processed by xdcmake.exe.| +| Option | Description | +|--|--| +| `/?`, `/help` | Display help for xdcmake.exe. | +| `/assembly:filename` | Lets you specify the value of the `` tag in the XML file. By default, the value of the `` tag is the same as the filename of the XML file. | +| `/nologo` | Suppress copyright message. | +| `/out:filename` | Lets you specify the name of the XML file. By default, the name of the XML file is the filename of the first XDC file processed by xdcmake.exe. | ## Remarks -Visual Studio will invoke xdcmake.exe automatically when building a project. You can also invoke xdcmake.exe at the command line. +Visual Studio invokes xdcmake.exe automatically when building a project. You can also invoke xdcmake.exe at the command line. -See [Recommended Tags for Documentation Comments](recommended-tags-for-documentation-comments-visual-cpp.md) for more information on adding documentation comments to source code files. +For more information on adding documentation comments to source code files, see [Recommended tags for documentation comments](recommended-tags-for-documentation-comments-visual-cpp.md). ## See also -[XML Documentation](xml-documentation-visual-cpp.md) +[XML documentation](xml-documentation-visual-cpp.md) diff --git a/docs/build/reference/xml-document-generator-tool-property-pages.md b/docs/build/reference/xml-document-generator-tool-property-pages.md index 44c2fc716e..ddcf002fca 100644 --- a/docs/build/reference/xml-document-generator-tool-property-pages.md +++ b/docs/build/reference/xml-document-generator-tool-property-pages.md @@ -1,16 +1,16 @@ --- description: "Learn more about: XML Document Generator Tool Property Pages" title: "XML Document Generator Tool Property Pages" -ms.date: "11/04/2016" +ms.date: 03/02/2022 f1_keywords: ["VC.Project.VCXDCMakeTool.ValidateIntelliSense", "VC.Project.VCXDCMakeTool.SuppressStartupBanner", "VC.Project.VCXDCMakeTool.DocumentLibraryDependencies", "VC.Project.VCXDCMakeTool.OutputDocumentFile", "VC.Project.VCXDCMakeTool.AdditionalDocumentFiles"] ms.assetid: 645912b5-197a-4c36-ba58-64df09444ca0 --- # XML Document Generator Tool Property Pages -The XML Document Generator Tool property page exposes the functionality of xdcmake.exe. xdcmake.exe merges .xdc files into an .xml file when your source code contains documentation comments and [/doc (Process Documentation Comments) (C/C++)](doc-process-documentation-comments-c-cpp.md) is specified,. See [Recommended Tags for Documentation Comments](recommended-tags-for-documentation-comments-visual-cpp.md) for information on adding documentation comments to source code. +The XML Document Generator Tool property page exposes the functionality of *`xdcmake.exe`*, or XDCMake. XDCMake merges *`.xdc`* files into an *`.xml`* file when your source code contains documentation comments and [`/doc` (Process Documentation Comments) (C/C++)](doc-process-documentation-comments-c-cpp.md) is specified. For more information on adding documentation comments to source code, see [Recommended tags for documentation comments](recommended-tags-for-documentation-comments-visual-cpp.md). > [!NOTE] -> xdcmake.exe options in the development environment (property pages) differ from the options when xdcmake.exe is used at the command line. For information on using xdcmake.exe at the command line, see [XDCMake Reference](xdcmake-reference.md). +> XDCMake options in the development environment (property pages) differ from the options when *`xdcmake.exe`* is used at the command line. For information on using *`xdcmake.exe`* at the command line, see [XDCMake reference](xdcmake-reference.md). ## UIElement List @@ -20,15 +20,15 @@ The XML Document Generator Tool property page exposes the functionality of xdcma - **Additional Document Files** - Additional directories in which you want the project system to look for .xdc files. xdcmake will always look for .xdc files generated by the project. Multiple directories can be specified. + Additional directories in which you want the project system to look for *`.xdc`* files. XDCMake always looks for *`.xdc`* files generated by the project. Multiple directories can be specified. - **Output Document File** - The name and directory location of the .xml output file. See [Common macros for build commands and properties](common-macros-for-build-commands-and-properties.md) for information on using macros to specify directory locations. + The name and directory location of the *`.xml`* output file. For more information on using macros to specify directory locations, see [Common macros for build commands and properties](common-macros-for-build-commands-and-properties.md). - **Document Library Dependencies** - If your project has a dependency on a .lib project in the solution, you can process .xdc files from the .lib project into the .xml files for the current project. + If your project has a dependency on a *`.lib`* project in the solution, you can process *`.xdc`* files from the *`.lib`* project into the *`.xml`* files for the current project. ## See also diff --git a/docs/build/reference/xml-documentation-visual-cpp.md b/docs/build/reference/xml-documentation-visual-cpp.md index 47a9eaa60e..8bb4f674c0 100644 --- a/docs/build/reference/xml-documentation-visual-cpp.md +++ b/docs/build/reference/xml-documentation-visual-cpp.md @@ -1,38 +1,38 @@ --- -description: "Learn more about: XML Documentation (Visual C++)" -title: "XML Documentation (Visual C++)" -ms.date: "11/04/2016" +description: "Learn more about: XML documentation (Visual C++)" +title: "XML documentation (Visual C++)" +ms.date: 12/03/2021 helpviewer_keywords: ["XML documentation", "XML, documentation comments in source code", "comments, C++ source code files", "/// delimiter for C++ documentation"] ms.assetid: a1aec1c5-b2d1-4c74-83ae-1dbbbb76b506 --- -# XML Documentation (Visual C++) +# XML documentation (Visual C++) -In Visual C++, you can add comments to your source code that will be processed to an .xml file. This file can then be the input to a process that creates documentation for the classes in your code. +In Visual C++, you can add comments to your source code that are processed to an XML documentation file. This file can then be the input to a process that creates documentation for the classes in your code. -In a Visual C++ code file, XML documentation comments must be located directly prior to a method or type definition. The comments can be used to populate the IntelliSense QuickInfo data tip in the following scenarios: +In a Visual C++ code file, XML documentation comments must be located directly before a method or type definition. The comments can be used to populate the IntelliSense QuickInfo data tip in the following scenarios: -1. when the code is compiled as a Windows Runtime component with an accompanying .winmd file +1. When the code is compiled as a Windows Runtime component with a WINMD file -1. when the source code is included in the current project +1. When the source code is included in the current project -1. in a library whose type declarations and implementations are located in the same header file +1. In a library whose type declarations and implementations are located in the same header file > [!NOTE] -> In the current release, code comments are not processed on templates or anything containing a template type (for example, a function taking a parameter as a template). Adding such comments will result in undefined behavior. +> In the current release, code comments aren't processed on templates or anything containing a template type (for example, a function taking a parameter as a template). Adding such comments will result in undefined behavior. -For details on creating an .xml file with documentation comments, see the following topics. +For details on creating an XML file with documentation comments, see the following articles. -|For information about|See| -|---------------------------|---------| -|The compiler options to use|[/doc](doc-process-documentation-comments-c-cpp.md)| -|Tags you can use to provide commonly used functionality in documentation|[Recommended Tags for Documentation Comments](recommended-tags-for-documentation-comments-visual-cpp.md)| -|The ID strings that the compiler produces to identify the constructs in your code|[Processing the .xml File](dot-xml-file-processing.md)| -|How to delimit documentation tags|[Delimiters for Visual C++ Documentation Tags](delimiters-for-visual-cpp-documentation-tags.md)| -|Generating an .xml file from one or more .xdc files.|[XDCMake Reference](xdcmake-reference.md)| -|Links to information about XML as it relates to Visual Studio feature areas|[XML in Visual Studio](/visualstudio/xml-tools/xml-tools-in-visual-studio)| +| For information about | See | +|--|--| +| The compiler options to use | [`/doc`](doc-process-documentation-comments-c-cpp.md) | +| Tags you can use to provide commonly used functionality in documentation | [Recommended tags for documentation comments](recommended-tags-for-documentation-comments-visual-cpp.md) | +| The ID strings that the compiler produces to identify the constructs in your code | [Processing the XML File](dot-xml-file-processing.md) | +| How to delimit documentation tags | [Delimiters for Visual C++ documentation tags](delimiters-for-visual-cpp-documentation-tags.md) | +| Generating an XML file from one or more XDC files. | [XDCMake reference](xdcmake-reference.md) | +| Links to information about XML as it relates to Visual Studio feature areas | [XML in Visual Studio](/visualstudio/xml-tools/xml-tools-in-visual-studio) | If you need to put XML special characters in the text of a documentation comment, you must use XML entities or a CDATA section. ## See also -[Component Extensions for Runtime Platforms](../../extensions/component-extensions-for-runtime-platforms.md) +[Component extensions for runtime platforms](../../extensions/component-extensions-for-runtime-platforms.md) diff --git a/docs/build/reference/z7-zi-zi-debug-information-format.md b/docs/build/reference/z7-zi-zi-debug-information-format.md index 2a6a00bde2..6cc70e4d4c 100644 --- a/docs/build/reference/z7-zi-zi-debug-information-format.md +++ b/docs/build/reference/z7-zi-zi-debug-information-format.md @@ -1,11 +1,11 @@ --- description: "Learn more about: /Z7, /Zi, /ZI (Debug Information Format)" title: "/Z7, /Zi, /ZI (Debug Information Format)" -ms.date: "07/06/2020" +ms.date: 12/09/2021 f1_keywords: ["VC.Project.VCCLCompilerTool.DebugInformationFormat", "/ZI", "/Zi", "/Z7", "VC.Project.VCCLWCECompilerTool.DebugInformationFormat"] helpviewer_keywords: ["C7 compatible compiler option [C++]", "Debug Information Format compiler option", "ZI compiler option", "-Zi compiler option [C++]", "/ZI compiler option [C++]", "Z7 compiler option [C++]", "debugging [C++], debug information files", "Zi compiler option [C++]", "/Zi compiler option [C++]", "program database compiler option [C++]", "full symbolic debugging information", "/Z7 compiler option [C++]", "line numbers only compiler option [C++]", "cl.exe compiler, debugging options", "-Z7 compiler option [C++]"] --- -# /Z7, /Zi, /ZI (Debug Information Format) +# `/Z7`, `/Zi`, `/ZI` (Debug Information Format) The **`/Z7`**, **`/Zi`**, and **`/ZI`** compiler options specify the type of debugging information created for your program, and whether this information is kept in object files or in a program database (PDB) file. @@ -23,7 +23,7 @@ When you specify a debug option, the compiler produces symbol names for function By default, if no debug information format option is specified, the compiler produces no debugging information, so compilation is faster. -### /Z7 +### `/Z7` The **`/Z7`** option produces object files that also contain full symbolic debugging information for use with the debugger. These object files and any libraries built from them can be substantially larger than files that have no debugging information. The symbolic debugging information includes the names and types of variables, functions, and line numbers. No PDB file is produced by the compiler. However, a PDB file can still be generated from these object files or libraries if the linker is passed the **`/DEBUG`** option. @@ -31,7 +31,7 @@ For distributors of debug versions of third-party libraries, there's an advantag The deprecated [`/Gm` (Enable Minimal Rebuild)](gm-enable-minimal-rebuild.md) option is unavailable when **`/Z7`** is specified. -### /Zi +### `/Zi` The **`/Zi`** option produces a separate PDB file that contains all the symbolic debugging information for use with the debugger. The debugging information isn't included in the object files or executable, which makes them much smaller. @@ -43,7 +43,7 @@ The compiler names the PDB file *`.pdb`*, where *``* is the na If you create a library from objects that were compiled using **`/Zi`**, the associated PDB file must be available when the library is linked to a program. That means, if you distribute the library, you must also distribute the PDB file. To create a library that contains debugging information without using PDB files, you must select the **`/Z7`** option. If you use the precompiled headers options, debugging information for both the precompiled header and the rest of the source code is placed in the PDB file. -### /ZI +### `/ZI` The **`/ZI`** option is similar to **`/Zi`**, but it produces a PDB file in a format that supports the [Edit and Continue](/visualstudio/debugger/edit-and-continue-visual-cpp) feature. To use Edit and Continue debugging features, you must use this option. The Edit and Continue feature is useful for developer productivity, but can cause issues in code size, performance, and compiler conformance. Because most optimizations are incompatible with Edit and Continue, using **`/ZI`** disables any `#pragma optimize` statements in your code. The **`/ZI`** option is also incompatible with use of the [`__LINE__` predefined macro](../../preprocessor/predefined-macros.md); code compiled with **`/ZI`** can't use `__LINE__` as a non-type template argument, although `__LINE__` can be used in macro expansions. diff --git a/docs/build/reference/zc-alignednew.md b/docs/build/reference/zc-alignednew.md index 710d0be165..c591923268 100644 --- a/docs/build/reference/zc-alignednew.md +++ b/docs/build/reference/zc-alignednew.md @@ -1,29 +1,29 @@ --- -description: "Learn more about: /Zc:alignedNew (C++17 over-aligned allocation)" title: "/Zc:alignedNew (C++17 over-aligned allocation)" +description: "Learn more about: /Zc:alignedNew (C++17 over-aligned allocation)" ms.date: "05/18/2019" f1_keywords: ["/Zc:alignedNew"] helpviewer_keywords: ["/Zc:alignedNew", "Zc:alignedNew", "-Zc:alignedNew"] --- -# /Zc:alignedNew (C++17 over-aligned allocation) +# `/Zc:alignedNew` (C++17 over-aligned allocation) -Enable support for C++17 over-aligned **`new`**, dynamic memory allocation aligned on boundaries greater than the default for the maximum-sized standard aligned type, **max\_align\_t**. +Enable support for C++17 over-aligned **`new`**, dynamic memory allocation aligned on boundaries greater than the default for the maximum-sized standard aligned type, `max_align_t`. ## Syntax -> **/Zc:alignedNew**\[-] +> **`/Zc:alignedNew`**\[**`-`**] ## Remarks -The MSVC compiler and library support C++17 standard over-aligned dynamic memory allocation. When the **/Zc:alignedNew** option is specified, a dynamic allocation such as `new Example;` respects the alignment of *Example* even when it's greater than `max_align_t`, the largest alignment required for any fundamental type. When the alignment of the allocated type is no more than the alignment guaranteed by the original operator **`new`**, available as the value of the predefined macro **\_\_STDCPP\_DEFAULT\_NEW\_ALIGNMENT\_\_**, the statement `new Example;` results in a call to `::operator new(size_t)` as it did in C++14. When the alignment is greater than **\_\_STDCPP\_DEFAULT\_NEW\_ALIGNMENT\_\_**, the implementation instead obtains the memory by using `::operator new(size_t, align_val_t)`. Similarly, deletion of over-aligned types invokes `::operator delete(void*, align_val_t)` or the sized delete signature `::operator delete(void*, size_t, align_val_t)`. +The MSVC compiler and library support C++17 standard over-aligned dynamic memory allocation. When the **`/Zc:alignedNew`** option is specified, a dynamic allocation such as `new Example;` respects the alignment of `Example` even when it's greater than `max_align_t`, the largest alignment required for any fundamental type. When the alignment of the allocated type is no more than the alignment guaranteed by the original operator **`new`**, available as the value of the predefined macro `__STDCPP_DEFAULT_NEW_ALIGNMENT__`, the statement `new Example;` results in a call to `::operator new(size_t)` as it did in C++14. When the alignment is greater than `__STDCPP_DEFAULT_NEW_ALIGNMENT__`, the implementation instead obtains the memory by using `::operator new(size_t, align_val_t)`. Similarly, deletion of over-aligned types invokes `::operator delete(void*, align_val_t)` or the sized delete signature `::operator delete(void*, size_t, align_val_t)`. -The **/Zc:alignedNew** option is only available when [/std:c++17](std-specify-language-standard-version.md) or [/std:c++latest](std-specify-language-standard-version.md) is enabled. Under **/std:c++17** or **/std:c++latest**, **/Zc:alignedNew** is enabled by default to conform to the ISO C++17 standard. If the only reason you implement operator **`new`** and **`delete`** is to support over-aligned allocations, you may no longer need this code in C++17 mode. To turn off this option and revert to the C++14 behavior of **`new`** and **`delete`** when you use **/std::c++17** or **/std:c++latest**, specify **/Zc:alignedNew-**. If you implement operator **`new`** and **`delete`** but you're not ready to implement the over-aligned operator **`new`** and **`delete`** overloads that have the `align_val_t` parameter, use the **/Zc:alignedNew-** option to prevent the compiler and Standard Library from generating calls to the over-aligned overloads. The [/permissive-](permissive-standards-conformance.md) option doesn't change the default setting of **/Zc:alignedNew**. +The **`/Zc:alignedNew`** option is only available when [`/std:c++17`](std-specify-language-standard-version.md) or later is enabled. Under **`/std:c++17`** or later, **`/Zc:alignedNew`** is enabled by default to conform to the C++ standard. If the only reason you implement operator **`new`** and **`delete`** is to support over-aligned allocations, you may no longer need this code in C++17 or later modes. To turn off this option and revert to the C++14 behavior of **`new`** and **`delete`** when you use **`/std:c++17`** or later, specify **`/Zc:alignedNew-`**. If you implement operator **`new`** and **`delete`** but you're not ready to implement the over-aligned operator **`new`** and **`delete`** overloads that have the `align_val_t` parameter, use the **`/Zc:alignedNew-`** option to prevent the compiler and Standard Library from generating calls to the over-aligned overloads. The [`/permissive-`](permissive-standards-conformance.md) option doesn't change the default setting of **`/Zc:alignedNew`**. -Support for **/Zc:alignedNew** is available starting in Visual Studio 2017 version 15.5. +Support for **`/Zc:alignedNew`** is available starting in Visual Studio 2017 version 15.5. ## Example -This sample shows how operator **`new`** and operator **`delete`** behave when the **/Zc:alignedNew** option is set. +This sample shows how operator **`new`** and operator **`delete`** behave when the **`/Zc:alignedNew`** option is set. ```cpp // alignedNew.cpp @@ -94,7 +94,7 @@ For information about conformance issues in Visual C++, see [Nonstandard Behavio 1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Modify the **Additional Options** property to include **/Zc:alignedNew** or **/Zc:alignedNew-** and then choose **OK**. +1. Modify the **Additional Options** property to include **`/Zc:alignedNew`** or **`/Zc:alignedNew-`** and then choose **OK**. ## See also diff --git a/docs/build/reference/zc-char8-t.md b/docs/build/reference/zc-char8-t.md new file mode 100644 index 0000000000..fa3e7a623a --- /dev/null +++ b/docs/build/reference/zc-char8-t.md @@ -0,0 +1,40 @@ +--- +description: "Learn more about the /Zc:char8_t (Enable C++20 char8_t type) compiler option." +title: "/Zc:char8_t (Enable C++20 char8_t type)" +ms.date: 08/11/2021 +f1_keywords: ["/Zc:char8_t"] +helpviewer_keywords: ["-Zc:char8_t compiler option (C++)", "/Zc:char8_t compiler option (C++)"] +--- +# `/Zc:char8_t` (Enable C++20 char8_t type) + +The **`/Zc:char8_t`** compiler option enables C++20 conforming **`char8_t`** type support. **`char8_t`** is a character type that's used to represent UTF-8 code units. + +## Syntax + +> **`/Zc:char8_t`**[**`-`**] + +## Remarks + +The **`/Zc:char8_t`** compiler option enables the **`char8_t`** type keyword as specified in the C++20 standard. It causes the compiler to generate `u8` prefixed character or string literals as `const char8_t` or `const char8_t[N]` types, respectively, instead of as `const char` or `const char[N]` types. In C++17, arrays of **`char`** may be initialized using `u8` string literals. In C++20, this initialization is ill-formed, and causes compiler error [C2440](../../error-messages/compiler-errors-1/compiler-error-c2440.md). This behavior can be a source-breaking change. You can revert the compiler to C++14 or C++17 behavior explicitly by specifying **`/Zc:char8_t-`**. + +The **`/Zc:char8_t`** option is available starting in Visual Studio 2019 version 16.1. It's enabled automatically when you specify [`/std:c++20`](std-specify-language-standard-version.md) or later (such as **`/std:c++latest`**). Otherwise, it's off by default. + +### Example + +```cpp +const char* s = u8"Hello"; // Compiles in C++17, Error C2440 in C++20 +const char8_t* s = u8"Hello"; // Compiles in C++20 or with /Zc:char8_t +``` + +### 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. Add **`/Zc:char8_t`** or **`/Zc:char8_t-`** to the **Additional options:** pane. + +## See also + +[`/Zc` (Conformance)](zc-conformance.md)\ +[`/std` (Specify language standard version)](std-specify-language-standard-version.md) diff --git a/docs/build/reference/zc-check-gwodr.md b/docs/build/reference/zc-check-gwodr.md new file mode 100644 index 0000000000..2bec0383a7 --- /dev/null +++ b/docs/build/reference/zc-check-gwodr.md @@ -0,0 +1,34 @@ +--- +title: "/Zc:zc-checkGwOdr (Enforce Standard C++ ODR violations under /Gw)" +description: "Learn about the Microsoft C++ /Zc:checkGwOdr compiler option for improving C++ standards conformance when using /Gw (Optimize global data)" +ms.date: 08/31/2023 +f1_keywords: ["/Zc:checkGwOdr"] +helpviewer_keywords: ["/Zc:checkGwOdr", "Zc:checkGwOdr", "-Zc:checkGwOdr"] +--- +# `/Zc:checkGwOdr` (Enforce Standard C++ ODR violations under `/Gw`) + +This switch enforces C++ standards conformance when using [`/Gw` (Optimize global data)](gw-optimize-global-data.md). When using `/Gw`, certain One Definition Rule (ODR) violations are ignored. This flag ensures that the appropriate errors are raised. + +## Syntax + +> **`/Zc:checkGwOdr`**\[**`-`**] + +## Remarks + +This switch is off by default. + +To see an example of ODR violations that are ignored when using `/Gw`, see [Standards conformance improvements to /Gw](https://devblogs.microsoft.com/cppblog/standards-conformance-improvements-to-gw-in-visual-studio-version-17-5-preview-2/). + +### To set this compiler option in the Visual Studio development environment + +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. Modify the **Additional Options** property to include *`/Zc:checkGwOdr`* or *`/Zc:checkGwOdr-`* and then choose **OK**. + +## See also + +[`/Zc` (Conformance)](zc-conformance.md)\ +[One Definition Rule (ODR)](https://en.wikipedia.org/wiki/One_Definition_Rule)\ +[Standards conformance improvements to /Gw](https://devblogs.microsoft.com/cppblog/standards-conformance-improvements-to-gw-in-visual-studio-version-17-5-preview-2/) diff --git a/docs/build/reference/zc-conformance.md b/docs/build/reference/zc-conformance.md index 43e2dcd811..efa980dbb7 100644 --- a/docs/build/reference/zc-conformance.md +++ b/docs/build/reference/zc-conformance.md @@ -1,12 +1,12 @@ --- title: "/Zc (Conformance)" description: "The /Zc conformance compiler options enable or disable support for conforming or backward-compatible behavior." -ms.date: 01/23/2021 +ms.date: 08/31/2023 helpviewer_keywords: ["/Zc compiler options [C++]", "-Zc compiler options [C++]", "Conformance compiler options", "Zc compiler options [C++]"] --- # `/Zc` (Conformance) -You can use the **`/Zc`** compiler options to specify standard or Microsoft-specific compiler behavior. +Use the **`/Zc`** compiler options to specify standard or Microsoft-specific compiler behavior. ## Syntax @@ -22,30 +22,42 @@ Here are the **`/Zc`** compiler options: | Option | Behavior | |--|--| -| [`/Zc:alignedNew`](zc-alignednew.md) | Enable C++17 over-aligned dynamic allocation (on by default in C++17). | -| [`/Zc:auto`](zc-auto-deduce-variable-type.md) | Enforce the new Standard C++ meaning for **`auto`** (on by default). | -| [`/Zc:__cplusplus`](zc-cplusplus.md) | Enable the `__cplusplus` macro to report the supported standard (off by default). | -| [`/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: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:noexceptTypes`](zc-noexcepttypes.md) | Enforce C++17 **`noexcept`** rules (on by default in C++17 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: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). | -| [`/Zc:trigraphs`](zc-trigraphs-trigraphs-substitution.md) | Enable trigraphs (obsolete, off by default). | -| [`/Zc:twoPhase`](zc-twophase.md) | Use non-conforming template parsing behavior (conforming by default). | -| [`/Zc:wchar_t`](zc-wchar-t-wchar-t-is-native-type.md) | **`wchar_t`** is a native type, not a typedef (on by default). | +| [`/Zc:__cplusplus[-]`](zc-cplusplus.md) | Enable the `__cplusplus` macro to report the supported standard. Off by default. | +| [`/Zc:__STDC__`](zc-stdc.md) | Enable the `__STDC__` macro to report the C standard is supported. Off by default. | +| [`/Zc:alignedNew[-]`](zc-alignednew.md) | Enable C++17 over-aligned dynamic allocation. Off by default unless **`/std:c++17`** or later is specified. | +| [`/Zc:auto[-]`](zc-auto-deduce-variable-type.md) | Enforce the new Standard C++ meaning for **`auto`**. On by default. | +| [`/Zc:char8_t[-]`](zc-char8-t.md) | Enable or disable C++20 native `u8` literal support as `const char8_t`. Off by default unless **`/std:c++20`** or later is specified. | +| [`/Zc:checkGwOdr[-]`](zc-check-gwodr.md) | Enforce Standard C++ ODR violations under `/Gw`. | +| [`/Zc:enumTypes[-]`](zc-enumtypes.md) | Enable Standard C++ rules for `enum` type deduction. Off by default. | +| [`/Zc:externC[-]`](zc-externc.md) | Enforce Standard C++ rules for `extern "C"` functions. Off by default unless **`/permissive-`** is specified. | +| [`/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. Off by default unless **`/permissive-`** is specified. | +| [`/Zc:hiddenFriend[-]`](zc-hiddenfriend.md) | Enforce Standard C++ hidden friend rules. Off by default unless **`/permissive-`** is specified. | +| [`/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. Off by default unless **`/std:c++20`** or later is specified. | +| [`/Zc:noexceptTypes[-]`](zc-noexcepttypes.md) | Enforce C++17 **`noexcept`** rules. Off by default unless **`/std:c++17`** or later is specified. | +| [`/Zc:nrvo[-]`](zc-nrvo.md) | Enable optional copy and move elisions. Off by default unless **`/O2`**, **`/permissive-`**, or **`/std:c++20`** or later is specified. | +| [`/Zc:preprocessor[-]`](zc-preprocessor.md) | Use the new conforming preprocessor. Off by default unless **`/std:c11`** or later is specified. | +| [`/Zc:referenceBinding[-]`](zc-referencebinding-enforce-reference-binding-rules.md) | A UDT temporary won't bind to a nonconst lvalue reference. Off by default unless **`/permissive-`** is specified. | +| [`/Zc:rvalueCast[-]`](zc-rvaluecast-enforce-type-conversion-rules.md) | Enforce Standard C++ explicit type conversion rules. Off by default unless **`/permissive-`** is specified. | +| [`/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 unless **`/permissive-`** is specified. | +| [`/Zc:static_assert[-]`](zc-static-assert.md) | strict handling of `static_assert`. Off by default unless **`/permissive-`** is specified. | +| [`/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 unless **`/permissive-`** is specified. | +| [`/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. | +| [`/Zc:tlsGuards[-]`](zc-tlsguards.md) | Generate runtime checks for TLS variable initialization. On by default. | +| [`/Zc:trigraphs[-]`](zc-trigraphs-trigraphs-substitution.md) | Enable trigraphs (obsolete, off by default). | +| [`/Zc:twoPhase-`](zc-twophase.md) | Use nonconforming template parsing behavior (only applicable when **`/permissive-`** is specified, which defaults to conforming). | +| [`/Zc:wchar_t[-]`](zc-wchar-t-wchar-t-is-native-type.md) | **`wchar_t`** is a native type, not a typedef. On by default. | +| [`/Zc:zeroSizeArrayNew[-]`](zc-zerosizearraynew.md) | Call member `new`/`delete` for 0-size arrays of objects. On by default. | For more information about conformance issues in MSVC, see [Nonstandard behavior](../../cpp/nonstandard-behavior.md). ## See also -[MSVC compiler options](compiler-options.md)
+[MSVC compiler options](compiler-options.md)\ [MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/zc-cplusplus.md b/docs/build/reference/zc-cplusplus.md index 57f3f1f099..ef73099605 100644 --- a/docs/build/reference/zc-cplusplus.md +++ b/docs/build/reference/zc-cplusplus.md @@ -1,35 +1,36 @@ --- description: "Learn more about: /Zc:__cplusplus (Enable updated __cplusplus macro)" title: "/Zc:__cplusplus (Enable updated __cplusplus macro)" -ms.date: "05/16/2019" +ms.date: 08/11/2021 f1_keywords: ["/Zc:__cplusplus"] helpviewer_keywords: ["-Zc:__cplusplus compiler option (C++)", "__cplusplus macro (C++)"] --- -# /Zc:__cplusplus (Enable updated __cplusplus macro) +# `/Zc:__cplusplus` (Enable updated `__cplusplus` macro) -The **/Zc:__cplusplus** compiler option enables the **\_\_cplusplus** preprocessor macro to report an updated value for recent C++ language standards support. By default, Visual Studio always returns the value "199711L" for the **\_\_cplusplus** preprocessor macro. +The **`/Zc:__cplusplus`** compiler option enables the `__cplusplus` preprocessor macro to report an updated value for recent C++ language standards support. By default, Visual Studio always returns the value `199711L` for the `__cplusplus` preprocessor macro. ## Syntax -> **/Zc:__cplusplus**[**-**] +> **`/Zc:__cplusplus`**[**`-`**] ## Remarks -The **\_\_cplusplus** preprocessor macro is commonly used to report support for a particular version of the C++ standard. Because lots of existing code appears to depend on the value of this macro matching "199711L", the compiler does not change the value of the macro unless you explicitly opt-in by using the **/Zc:__cplusplus** compiler option. The **/Zc:__cplusplus** option is available starting in Visual Studio 2017 version 15.7, and is off by default. In earlier versions of Visual Studio, and by default, or if **/Zc:__cplusplus-** is specified, Visual Studio returns the value "199711L" for the **\_\_cplusplus** preprocessor macro. The [/permissive-](permissive-standards-conformance.md) option does not enable **/Zc:__cplusplus**. +The `__cplusplus` preprocessor macro is commonly used to report support for a particular version of the C++ standard. Because a lot of existing code appears to depend on the value of this macro matching `199711L`, the compiler doesn't change the value of the macro unless you explicitly opt in by using the **`/Zc:__cplusplus`** compiler option. The **`/Zc:__cplusplus`** option is available starting in Visual Studio 2017 version 15.7, and is off by default. In earlier versions of Visual Studio, and by default, or if **`/Zc:__cplusplus-`** is specified, Visual Studio returns the value `199711L` for the `__cplusplus` preprocessor macro. The [`/permissive-`](permissive-standards-conformance.md) option doesn't enable **`/Zc:__cplusplus`**. -When the **/Zc:__cplusplus** option is enabled, the value reported by the **\_\_cplusplus** macro depends on the [/std](std-specify-language-standard-version.md) version switch setting. This table shows the possible values for the macro: +When the **`/Zc:__cplusplus`** option is enabled, the value reported by the `__cplusplus` macro depends on the [`/std`](std-specify-language-standard-version.md) version option setting. This table shows the possible values for the macro: -|/Zc:__cplusplus switch|/std:c++ switch|__cplusplus value| -|-|-|-| -Zc:__cplusplus|/std:c++14 (default)|201402L -Zc:__cplusplus|/std:c++17|201703L -Zc:__cplusplus|/std:c++latest|201704L -Zc:__cplusplus- (disabled)|Any value|199711L -Not specified|Any value|199711L +| `/Zc:__cplusplus` option | `/std` option | `__cplusplus` value | +|--|--|--| +| `Zc:__cplusplus` | `/std:c++14` (default) | `201402L` | +| `Zc:__cplusplus` | `/std:c++17` | `201703L` | +| `Zc:__cplusplus` | `/std:c++20` | `202002L` | +| `Zc:__cplusplus` | `/std:c++latest` | see text | +| `Zc:__cplusplus-` (disabled) | Any value | `199711L` | +| Not specified | Any value | `199711L` | -The compiler does not support standards switches for C++98, C++03, or C++11. +The compiler doesn't support standards options for C++98, C++03, or C++11. The **`/std:c++20`** option is available starting in Visual Studio 2019 version 16.11. The value of `__cplusplus` with the **`/std:c++latest`** option depends on the version of Visual Studio. It's always at least one higher than the highest supported `__cplusplus` standard value supported by your version of Visual Studio. -For finer-grained detection of changes to the compiler toolset, use the [_MSC_VER](../../preprocessor/predefined-macros.md) predefined macro. The value of this built-in macro is incremented for every toolset update in Visual Studio 2017 and later versions. The [_MSVC_LANG](../../preprocessor/predefined-macros.md) predefined macro reports the standard version whether the **/Zc:__cplusplus** option is enabled or disabled. When **/Zc:__cplusplus** is enabled, `__cplusplus == _MSVC_LANG`. +For finer-grained detection of changes to the compiler toolset, use the [`_MSC_VER`](../../preprocessor/predefined-macros.md) predefined macro. The value of this built-in macro is incremented for every toolset update in Visual Studio 2017 and later versions. The [`_MSVC_LANG`](../../preprocessor/predefined-macros.md) predefined macro reports the standard version whether the **`/Zc:__cplusplus`** option is enabled or disabled. When **`/Zc:__cplusplus`** is enabled, `__cplusplus` has the same value as `_MSVC_LANG`. ### To set this compiler option in Visual Studio @@ -37,10 +38,10 @@ For finer-grained detection of changes to the compiler toolset, use the [_MSC_VE 1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Add **/Zc:__cplusplus** or **/Zc:__cplusplus-** to the **Additional options:** pane. +1. Add **`/Zc:__cplusplus`** or **`/Zc:__cplusplus-`** to the **Additional options:** pane. ## See also -- [/Zc (Conformance)](zc-conformance.md) -- [/std (Specify language standard version)](std-specify-language-standard-version.md) -- [Predefined macros](../../preprocessor/predefined-macros.md) +[`/Zc` (Conformance)](zc-conformance.md)\ +[`/std` (Specify language standard version)](std-specify-language-standard-version.md)\ +[Predefined macros](../../preprocessor/predefined-macros.md) diff --git a/docs/build/reference/zc-enumtypes.md b/docs/build/reference/zc-enumtypes.md new file mode 100644 index 0000000000..7c2f590e2f --- /dev/null +++ b/docs/build/reference/zc-enumtypes.md @@ -0,0 +1,88 @@ +--- +description: "Learn more about the /Zc:enumTypes (Enable enum type deduction) compiler option." +title: "/Zc:enumTypes (Enable enum type deduction)" +ms.date: 11/07/2022 +f1_keywords: ["/Zc:enumTypes"] +helpviewer_keywords: ["-Zc:enumTypes compiler option (C++)", "/Zc:enumTypes compiler option (C++)"] +--- +# `/Zc:enumTypes` (Enable enum type deduction) + +The **`/Zc:enumTypes`** compiler option enables C++ conforming **`enum`** underlying type and enumerator type deduction. + +## Syntax + +> **`/Zc:enumTypes`**\[**`-`**] + +## Remarks + +The **`/Zc:enumTypes`** compiler option implements Standard C++ conforming behavior for deduction of enumeration base types and the types of enumerators. + +The **`/Zc:enumTypes`** option is new in Visual Studio 2022 version 17.4. This option is off by default, and isn't enabled by **`/permissive-`**. To explicitly disable the option, use **`/Zc:enumTypes-`**. + +When enabled, the **`/Zc:enumTypes`** option is a potential source and binary breaking change. Some enumeration types change size when the conforming **`/Zc:enumTypes`** option is enabled. Certain Windows SDK headers include such enumeration definitions. + +The C++ Standard requires that the underlying type of an enumeration is large enough to hold all enumerators declared in it. Sufficiently large enumerators can set the underlying type of the **`enum`** to **`unsigned int`**, **`long long`**, or **`unsigned long long`**. Previously, such enumeration types always had an underlying type of **`int`** in the Microsoft compiler, regardless of enumerator values. + +The C++ Standard also specifies that, within an enumeration definition that has no fixed underlying type, the types of enumerators are determined by their initializers. Or, for the enumerators with no initializer, by the type of the previous enumerator (accounting for overflow). Previously, such enumerators were always given the deduced type of the enumeration, with a placeholder for the underlying type (typically **`int`**). + +In versions of Visual Studio before Visual Studio 2022 version 17.4, the C++ compiler didn't correctly determine the underlying type of an unscoped enumeration with no fixed base type. The compiler also didn't correctly model the types of enumerators. It could assume an incorrect type in enumerations without a fixed underlying type before the closing brace of the enumeration. Under **`/Zc:enumTypes`**, the compiler correctly implements the standard behavior. + +### Example: Underlying type of unscoped `enum` with no fixed type + +```cpp +enum Unsigned +{ + A = 0xFFFFFFFF // Value 'A' does not fit in 'int'. +}; + +// Previously, this static_assert failed. It passes with /Zc:enumTypes. +static_assert(std::is_same_v, unsigned int>); + +template +void f(T x) +{ +} + +int main() +{ + // Previously called f, now calls f. + f(+A); +} + +// Previously, this enum would have an underlying type of `int`, +// but Standard C++ requires this to have a 64-bit underlying type. +// The /Zc:enumTypes option changes the size of this enum from 4 to 8, +// which could impact binary compatibility with code compiled with an +// earlier compiler version, or without the switch. +enum Changed +{ + X = -1, + Y = 0xFFFFFFFF +}; +``` + +### Example: Enumerators within an `enum` definition with no fixed underlying type + +```cpp +enum Enum { + A = 'A', + B = sizeof(A) +}; + +static_assert(B == 1); // previously failed, now succeeds under /Zc:enumTypes +``` + +In this example the enumerator `A` should have type **`char`** prior to the closing brace of the enumeration, so `B` should be initialized using `sizeof(char)`. Before the **`/Zc:enumTypes`** fix, `A` had enumeration type `Enum` with a deduced underlying type **`int`**, and `B` was initialized using `sizeof(Enum)`, or 4. + +### 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:enumTypes`* or *`/Zc:enumTypes-`*. Choose **OK** or **Apply** to save your changes. + +## See also + +[`/Zc` (Conformance)](zc-conformance.md)\ +[`/std` (Specify language standard version)](std-specify-language-standard-version.md) diff --git a/docs/build/reference/zc-externc.md b/docs/build/reference/zc-externc.md new file mode 100644 index 0000000000..e810606b61 --- /dev/null +++ b/docs/build/reference/zc-externc.md @@ -0,0 +1,36 @@ +--- +description: 'Learn more about: /Zc:externC (Use Standard C++ extern "C" rules)' +title: '/Zc:externC (Use Standard C++ extern "C" rules)' +ms.date: 12/02/2021 +f1_keywords: ["/Zc:externC"] +helpviewer_keywords: ["-Zc:externConstexpr compiler option (C++)", "extern constexpr variables (C++)"] +ms.assetid: 4da5e33a-2e4d-4ed2-8616-bd8f43265c27 +--- +# `/Zc:externC` (Use Standard C++ `extern "C"` rules) + +The **`/Zc:externC`** compiler option tells the compiler to conform to the C++ standard and enforce consistent parameter declarations for functions declared as `extern "C"`. + +## Syntax + +> **`/Zc:externC`**\ +> **`/Zc:externC-`** + +## Remarks + +The **`/Zc:externC`** compiler option checks the definitions of functions declared by using `extern "C"`. + +The **`/Zc:externC`** option is available starting in Visual Studio 2019 version 16.3. It's off when the [`/permissive-`](permissive-standards-conformance.md) option isn't set. In earlier versions of Visual Studio, and by default or if **`/Zc:externC-`** is specified, Visual Studio is permissive about matching declarations of `extern "C"` functions. The **`/permissive-`** option enables **`/Zc:externC`**, so it's on by default in projects that use **`/std:c++20`** or **`/std:c++latest`**. The **`/Zc:externC`** option must come after a **`/permissive-`** option on the command line. + +Mismatched `extern "C"` declarations can cause compiler errors [C2116](../../error-messages/compiler-errors-1/compiler-error-c2116.md) and [C2733](../../error-messages/compiler-errors-2/compiler-error-c2733.md). In C++ code, an error can occur if you declare an `extern "C"` function more than once and use different parameter types, even if the types have the same definitions. The **`/Zc:externC-`** option relaxes this check, and doesn't produce these errors. + +### 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. Add **`/Zc:externC`** or **`/Zc:externC-`** to the **Additional options:** pane. + +## See also + +[`/Zc` (Conformance)](zc-conformance.md) diff --git a/docs/build/reference/zc-externconstexpr.md b/docs/build/reference/zc-externconstexpr.md index c689fee737..ee9c10b502 100644 --- a/docs/build/reference/zc-externconstexpr.md +++ b/docs/build/reference/zc-externconstexpr.md @@ -1,10 +1,9 @@ --- description: "Learn more about: `/Zc:externConstexpr` (Enable extern constexpr variables)" title: "/Zc:externConstexpr (Enable extern constexpr variables)" -ms.date: "02/28/2018" +ms.date: 10/12/2023 f1_keywords: ["/Zc:externConstexpr"] helpviewer_keywords: ["-Zc:externConstexpr compiler option (C++)", "extern constexpr variables (C++)"] -ms.assetid: 4da5e33a-2e4d-4ed2-8616-bd8f43265c27 --- # `/Zc:externConstexpr` (Enable extern constexpr variables) @@ -16,9 +15,13 @@ The **`/Zc:externConstexpr`** compiler option tells the compiler to conform to t ## Remarks -The **`/Zc:externConstexpr`** compiler option causes the compiler to apply external linkage to variables declared by using `extern constexpr`. In earlier versions of Visual Studio, and by default or if **`/Zc:externConstexpr-`** is specified, Visual Studio applies internal linkage to **`constexpr`** variables even if the **`extern`** keyword is used. The **`/Zc:externConstexpr`** option is available starting in Visual Studio 2017 Update 15.6. and is off by default. The [`/permissive-`](permissive-standards-conformance.md) option does not enable **`/Zc:externConstexpr`**. +The **`/Zc:externConstexpr`** compiler option causes the compiler to apply external linkage to variables declared by using `extern constexpr`. -If a header file contains a variable declared `extern constexpr`, it must be marked [`__declspec(selectany)`](../../cpp/selectany.md) in order to merge the duplicate declarations into a single instance in the linked binary. Otherwise you may see linker errors, for example, LNK2005, for violations of the one-definition rule. +In earlier versions of Visual Studio, by default or if **`/Zc:externConstexpr-`** is specified, Visual Studio applies internal linkage to **`constexpr`** variables even if the **`extern`** keyword is used. The **`/Zc:externConstexpr`** option is available starting in Visual Studio 2017 Update 15.6. and is off by default. + +As of Visual Studio 2022 Update 17.6, the **`/permissive-`** option enables both **`/Zc:externConstexpr`** and [`/Zc:lambda`](zc-lambda.md). In prior versions, **`/permissive-`** didn't enable either one. + +If a header file contains a variable declared **`extern constexpr`**, it must be marked [`__declspec(selectany)`](../../cpp/selectany.md) in order to merge the duplicate declarations into a single instance in the linked binary. Otherwise you may see linker errors, for example, LNK2005, for violations of the one-definition rule. ### To set this compiler option in Visual Studio @@ -30,5 +33,6 @@ If a header file contains a variable declared `extern constexpr`, it must be mar ## See also -[`/Zc` (Conformance)](zc-conformance.md)
-[`auto` Keyword](../../cpp/auto-cpp.md) +[`auto` Keyword](../../cpp/auto-cpp.md)\ +[`permissive`](permissive-standards-conformance.md)\ +[`/Zc` (Conformance)](zc-conformance.md) diff --git a/docs/build/reference/zc-gotoscope.md b/docs/build/reference/zc-gotoscope.md new file mode 100644 index 0000000000..e71d607142 --- /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-inline-remove-unreferenced-comdat.md b/docs/build/reference/zc-inline-remove-unreferenced-comdat.md index 0136602463..37f4265cea 100644 --- a/docs/build/reference/zc-inline-remove-unreferenced-comdat.md +++ b/docs/build/reference/zc-inline-remove-unreferenced-comdat.md @@ -1,30 +1,32 @@ --- description: "Learn more about: /Zc:inline (Remove unreferenced COMDAT)" title: "/Zc:inline (Remove unreferenced COMDAT)" -ms.date: "09/05/2019" +ms.date: 06/29/2022 f1_keywords: ["/Zc:inline", "VC.Project.VCCLCompilerTool.RemoveUnreferencedCodeData"] helpviewer_keywords: ["-Zc compiler options (C++)", "/Zc compiler options (C++)", "Zc compiler options (C++)", "/Zc:inline"] ms.assetid: a4c94224-1d73-4bea-a9d5-4fa73dc924df --- -# /Zc:inline (Remove unreferenced COMDAT) +# `/Zc:inline` (Remove unreferenced COMDAT) -Removes unreferenced data or functions that are COMDATs, or that only have internal linkage. Under **/Zc:inline**, the compiler specifies that translation units with inline data or functions must also include their definitions. +Removes unreferenced data or functions that are COMDATs, or that only have internal linkage. Under **`/Zc:inline`**, the compiler specifies that translation units with inline data or functions must also include their definitions. ## Syntax -> **/Zc:inline**[**-**] +> **`/Zc:inline`**[**`-`**] ## Remarks -When **/Zc:inline** is specified, the compiler doesn't emit symbol information for unreferenced COMDAT functions or data. Or, for data or functions that have internal linkage only. This optimization simplifies some of the work the linker does in release builds, or when you specify the [/OPT:REF](opt-optimizations.md) linker option. This compiler optimization can significantly reduce .obj file size and improve linker speeds. The compiler option isn't enabled when you disable optimizations ([/Od](od-disable-debug.md)). Or, when you specify [/GL (Whole Program Optimization)](gl-whole-program-optimization.md). +When **`/Zc:inline`** is specified, the compiler doesn't emit symbol information for unreferenced COMDAT functions or data. Or, for data or functions that have internal linkage only. This optimization simplifies some of the work the linker does in release builds, or when you specify the [`/OPT:REF`](opt-optimizations.md) linker option. This compiler optimization can significantly reduce .obj file size and improve linker speeds. The compiler option isn't enabled when you disable optimizations ([`/Od`](od-disable-debug.md)). Or, when you specify [`/GL` (Whole Program Optimization)](gl-whole-program-optimization.md). -By default, this option is off (**/Zc:inline-**) in command-line builds. The [/permissive-](permissive-standards-conformance.md) option doesn't enable **/Zc:inline**. In MSBuild projects, the option is set by the **Configuration Properties** > **C/C++** > **Language** > **Remove unreferenced code and data** property, which is set to **Yes** by default. +By default, this option is off (**`/Zc:inline-`**) in command-line builds. The [`/permissive-`](permissive-standards-conformance.md) option doesn't enable **`/Zc:inline`**. In MSBuild projects, the option is set by the **Configuration Properties** > **C/C++** > **Language** > **Remove unreferenced code and data** property, which is set to **Yes** by default. -If **/Zc:inline** is specified, the compiler enforces the C++11 requirement that all functions declared **`inline`** must have a definition available in the same translation unit if they are used. When the option is not specified, the Microsoft compiler allows non-conformant code that invokes functions declared **`inline`** even if no definition is visible. For more information, see the C++11 standard, in section 3.2 and section 7.1.2. This compiler option was introduced in Visual Studio 2013 Update 2. +If **`/Zc:inline`** is specified, the compiler enforces the C++11 requirement that all functions declared **`inline`** must have a definition available in the same translation unit if they're used. When the option isn't specified, the Microsoft compiler allows non-conformant code that invokes functions declared **`inline`** even if no definition is visible. For more information, see the C++11 standard, in section 3.2 and section 7.1.2. This compiler option was introduced in Visual Studio 2013 Update 2. -To use the **/Zc:inline** option, update non-compliant code. +To use the **`/Zc:inline`** option, update non-conforming code. -This example shows how the non-compliant use of an inline function declaration without a definition still compiles and links when the default **/Zc:inline-** option is used: +This example shows how the non-conforming use of an inline function declaration without a definition still compiles and links when the default **`/Zc:inline-`** option is used: + +Source file `example.h`: ```cpp // example.h @@ -39,6 +41,8 @@ public: }; ``` +Source file `example.cpp`: + ```cpp // example.cpp // Compile by using: cl /W4 /EHsc /O2 zcinline.cpp example.cpp @@ -55,6 +59,8 @@ void Example::normal_call() { } ``` +Source file `zcinline.cpp`: + ```cpp // zcinline.cpp // Compile by using: cl /W4 /EHsc /O2 zcinline.cpp example.cpp @@ -66,9 +72,11 @@ int main() { } ``` -When **/Zc:inline** is enabled, the same code causes a [LNK2019](../../error-messages/tool-errors/linker-tools-error-lnk2019.md) error, because the compiler does not emit a non-inlined code body for `Example::inline_call` in example.obj. This causes the non-inlined call in `main` to reference an undefined external symbol. +When **`/Zc:inline`** is enabled, the same code causes a [LNK2019](../../error-messages/tool-errors/linker-tools-error-lnk2019.md) error, because the compiler doesn't emit a non-inlined code body for `Example::inline_call` in `example.obj`. The missing code causes the non-inlined call in `main` to reference an undefined external symbol. -To resolve this error, you can remove the **`inline`** keyword from the declaration of `Example::inline_call`, move the definition of `Example::inline_call` into the header file, or move the implementation of `Example` into main.cpp. The next example moves the definition into the header file, where it is visible to any caller that includes the header. +To resolve this error, you can remove the **`inline`** keyword from the declaration of `Example::inline_call`, or move the definition of `Example::inline_call` into the header file, or move the implementation of `Example` into `main.cpp`. The next example moves the definition into the header file, where it's visible to any caller that includes the header. + +Source file `example2.h`: ```cpp // example2.h @@ -86,6 +94,8 @@ public: }; ``` +Source file `example2.cpp`: + ```cpp // example2.cpp // Compile by using: cl /W4 /EHsc /O2 zcinline2.cpp example2.cpp @@ -97,6 +107,8 @@ void Example2::normal_call() { } ``` +Source file `zcinline2.h`: + ```cpp // zcinline2.cpp // Compile by using: cl /W4 /EHsc /O2 zcinline2.cpp example2.cpp @@ -108,7 +120,7 @@ int main() { } ``` -For more information about conformance issues in Visual C++, see [Nonstandard Behavior](../../cpp/nonstandard-behavior.md). +For more information about conformance issues in Visual C++, see [Nonstandard behavior](../../cpp/nonstandard-behavior.md). ### To set this compiler option in the Visual Studio development environment @@ -120,4 +132,4 @@ For more information about conformance issues in Visual C++, see [Nonstandard Be ## See also -[/Zc (Conformance)](zc-conformance.md)
+[`/Zc` (Conformance)](zc-conformance.md) diff --git a/docs/build/reference/zc-lambda.md b/docs/build/reference/zc-lambda.md new file mode 100644 index 0000000000..6081969b7c --- /dev/null +++ b/docs/build/reference/zc-lambda.md @@ -0,0 +1,70 @@ +--- +description: "Learn more about: /Zc:lambda (Enable updated lambda processor)" +title: "/Zc:lambda (Enable updated lambda processor)" +ms.date: 06/01/2023 +f1_keywords: ["/Zc:lambda"] +helpviewer_keywords: ["-Zc:lambda compiler option (C++)", "/Zc:lambda compiler option (C++)"] +--- +# `/Zc:lambda` (Enable updated lambda processor) + +The **`/Zc:lambda`** compiler option enables conforming lambda grammar and processing support. + +## Syntax + +> **`/Zc:lambda`**[**`-`**] + +## Remarks + +The **`/Zc:lambda`** compiler option enables the conforming lambda processor. It parses and implements lambda code according to the C++ standard. This option is off by default, which uses the legacy lambda processor. Use this option to enable conformance-mode syntax checks of generic lambdas when you use the default [`/std:c++14`](std-specify-language-standard-version.md) or the [`/std:c++17`](std-specify-language-standard-version.md) compiler options. + +**`/Zc:lambda`** is automatically enabled by the [`/std:c++20`](std-specify-language-standard-version.md), [`/std:c++latest`](std-specify-language-standard-version.md), [`/permissive-`](permissive-standards-conformance.md), and [`/experimental:module`](experimental-module.md) options. You can disable it explicitly by using **`/Zc:lambda-`**. + +The **`/Zc:lambda`** option is available starting in Visual Studio 2019 version 16.8. It's available as **`/experimental:newLambdaProcessor`** starting in Visual Studio 2019 version 16.3, but this spelling is now deprecated. + +The legacy lambda processor has limitations when it parses and compiles lambdas. For example, this conforming code compiles correctly under **`/Zc:lambda`**, but reports errors under **`/Zc:lambda-`**: + +```cpp +void f1() +{ + constexpr auto c_value = 1; + auto func = []() + { + return c_value; // error C3493: 'c_value' cannot be implicitly captured + // because no default capture mode has been specified + }; + func(); // error C2064: term does not evaluate to a function taking 0 arguments +} +``` + +The legacy lambda processor compiles this code without warnings, but the new lambda processor produces error C2760: + +```cpp +void f2() { + auto a = [](auto arg) { + decltype(arg)::Type t; // C2760 syntax error: unexpected token 'identifier', expected ';' + }; +} +``` + +This example shows the correct syntax, now enforced by the compiler under **`/Zc:lambda`**: + +```cpp +void f3() { + auto a = [](auto arg) { + typename decltype(arg)::Type t; + }; +} +``` + +### 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. Add **`/Zc:lambda`** or **`/Zc:lambda-`** to the **Additional options:** pane. + +## See also + +[`/Zc` (Conformance)](zc-conformance.md)\ +[`/std` (Specify language standard version)](std-specify-language-standard-version.md) diff --git a/docs/build/reference/zc-noexcepttypes.md b/docs/build/reference/zc-noexcepttypes.md index d139665456..db977cceeb 100644 --- a/docs/build/reference/zc-noexcepttypes.md +++ b/docs/build/reference/zc-noexcepttypes.md @@ -6,7 +6,7 @@ f1_keywords: ["/Zc:noexceptTypes"] helpviewer_keywords: ["/Zc:noexceptTypes", "Zc:noexceptTypes", "-Zc:noexceptTypes"] ms.assetid: 1cbf7e3c-0f82-4f91-84dd-612bcf26d2c6 --- -# /Zc:noexceptTypes (C++17 noexcept rules) +# `/Zc:noexceptTypes` (C++17 noexcept rules) The C++17 standard makes `throw()` an alias for **`noexcept`**, removes `throw(`*`type-list`*`)` and `throw(...)`, and allows certain types to include **`noexcept`**. This change can cause a number of source compatibility issues in code that conforms to C++14 or earlier. The **`/Zc:noexceptTypes`** option specifies conformance to the C++17 standard. **`/Zc:noexceptTypes-`** allows the C++14 and earlier behavior when code is compiled in C++17 mode. @@ -16,7 +16,7 @@ The C++17 standard makes `throw()` an alias for **`noexcept`**, removes `throw(` ## Remarks -When the **`/Zc:noexceptTypes`** option is specified, the compiler conforms to the C++17 standard and treats [`throw()`](../../cpp/exception-specifications-throw-cpp.md) as an alias for [`noexcept`](../../cpp/noexcept-cpp.md), removes `throw(`*`type-list`*`)` and `throw(...)`, and allows certain types to include **`noexcept`**. The **`/Zc:noexceptTypes`** option is only available when [`/std:c++17`](std-specify-language-standard-version.md) or [`/std:c++latest`](std-specify-language-standard-version.md) is enabled. **`/Zc:noexceptTypes`** is enabled by default to conform to the ISO C++17 standard. The [`/permissive-`](permissive-standards-conformance.md) option doesn't affect **`/Zc:noexceptTypes`**. Turn off this option by specifying **`/Zc:noexceptTypes-`** to revert to the C++14 behavior of **`noexcept`** when **`/std:c++17`** or **`/std:c++latest`** is specified. +When the **`/Zc:noexceptTypes`** option is specified, the compiler conforms to the C++17 standard and treats [`throw()`](../../cpp/exception-specifications-throw-cpp.md) as an alias for [`noexcept`](../../cpp/noexcept-cpp.md), removes `throw(`*`type-list`*`)` and `throw(...)`, and allows certain types to include **`noexcept`**. The **`/Zc:noexceptTypes`** option is only available when [`/std:c++17`](std-specify-language-standard-version.md) or later is enabled. **`/Zc:noexceptTypes`** is enabled by default to conform to the ISO C++17 and later standards. The [`/permissive-`](permissive-standards-conformance.md) option doesn't affect **`/Zc:noexceptTypes`**. Turn off this option by specifying **`/Zc:noexceptTypes-`** to revert to the C++14 behavior of **`noexcept`** when **`/std:c++17`** or later is specified. Beginning in Visual Studio 2017 version 15.5, the C++ compiler diagnoses more mismatched exception specifications in declarations in C++17 mode, or when you specify the [`/permissive-`](permissive-standards-conformance.md) option. @@ -68,10 +68,10 @@ For more information about conformance issues in Visual C++, see [Nonstandard Be 1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Modify the **Additional Options** property to include *`/Zc:noexceptTypes`* or *`/Zc:noexceptTypes-`* and then choose **OK**. +1. Modify the **Additional Options** property to include **`/Zc:noexceptTypes`** or **`/Zc:noexceptTypes-`** and then choose **OK**. ## See also [`/Zc` (Conformance)](zc-conformance.md)\ -[noexcept](../../cpp/noexcept-cpp.md)\ +[`noexcept`](../../cpp/noexcept-cpp.md)\ [Exception specifications (throw)](../../cpp/exception-specifications-throw-cpp.md) diff --git a/docs/build/reference/zc-nrvo.md b/docs/build/reference/zc-nrvo.md new file mode 100644 index 0000000000..1248f10e14 --- /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-preprocessor.md b/docs/build/reference/zc-preprocessor.md index 6e8587f90a..fd8708017a 100644 --- a/docs/build/reference/zc-preprocessor.md +++ b/docs/build/reference/zc-preprocessor.md @@ -1,8 +1,8 @@ --- title: "/Zc:preprocessor (Enable preprocessor conformance mode)" description: "Use the /Zc:preprocessor compiler option to enable compiler support for a standard conforming preprocessor." -ms.date: 09/10/2020 -f1_keywords: ["preprocessor", "/Zc:preprocessor"] +ms.date: 02/17/2022 +f1_keywords: ["preprocessor", "/Zc:preprocessor", "VC.Project.VCCLCompilerTool.PreprocessorStandard"] helpviewer_keywords: ["preprocessor conformance", "/Zc:preprocessor", "Enable preprocessor conformance mode"] --- # `/Zc:preprocessor` (Enable preprocessor conformance mode) @@ -11,7 +11,7 @@ This option enables a token-based preprocessor that conforms to C99 and C++11 an ## Syntax -> **`/Zc:preprocessor`**[**-**] +> **`/Zc:preprocessor`**[**`-`**] ## Remarks @@ -23,9 +23,9 @@ The **`/Zc:preprocessor`** option is available starting in Visual Studio 2019 ve 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. Select the **Configuration Properties** > **C/C++** > **Preprocessor** property page. -1. Modify the **Additional Options** property to include *`/Zc:preprocessor`* and then choose **OK**. +1. Modify the **Use Standard Conforming Preprocessor** property and then choose **OK**. ## See also diff --git a/docs/build/reference/zc-static-assert.md b/docs/build/reference/zc-static-assert.md new file mode 100644 index 0000000000..9eb98b94a5 --- /dev/null +++ b/docs/build/reference/zc-static-assert.md @@ -0,0 +1,39 @@ +--- +description: "Learn more about: /Zc:static_assert (Strict static_assert handling)" +title: "/Zc:static_assert (Strict static_assert handling)" +ms.date: 1/15/2025 +f1_keywords: ["/Zc:static_assert"] +helpviewer_keywords: ["/Zc:static_assert compiler option (C++)"] +--- +# `/Zc:static_assert` (Strict static_assert handling) + +The **`/Zc:static_assert`** compiler option tells the compiler to evaluate `static_assert` calls with non-dependent test expressions when class or function templates are parsed. + +## Syntax + +> **`/Zc:static_assert`**\ +> **`/Zc:static_assert-`** + +## Remarks + +Starting with Visual Studio 17.10, `/Zc:static_assert` and `/Zc:static_assert-` have no effect. Both options are ignored to avoid breaking builds that use them. `static_assert` is now never evaluated when parsing class or function templates. + +The **`/Zc:static_assert`** compiler option tells the compiler to evaluate a `static_assert` in the body of a function template or in the body of a class template member function when first parsed, if the test expression isn't dependent. If the non-dependent test expression is `false`, the compiler emits an error immediately. When the test expression is dependent, the `static_assert` isn't evaluated until the template is instantiated. + +The **`/Zc:static_assert`** option is available starting in Visual Studio 2022 version 17.1. In earlier versions of Visual Studio, or if **`/Zc:static_assert-`** is specified, Visual Studio doesn't do dependent analysis if the `static_assert` is within the body of a function template or within the body of a member function of a class template. Instead, it only evaluates the `static_assert` when a template is instantiated. + +The **`/permissive-`** option enables **`/Zc:static_assert`**, so it's on by default in projects that use **`/std:c++20`** or **`/std:c++latest`**. The **`/Zc:static_assert-`** option must come after a **`/std:c++20`**, **`/std:c++latest`**, or **`/permissive-`** option on the command line. + +If the compiler is in the default C++14 mode and **`/permissive-`** or **`/Zc:static_assert`** is specified, it uses **`/Zc:static_assert`** behavior. However, if it evaluates a `static_assert` in a template body, it also reports off-by-default warning C5254, "language feature 'terse static assert' requires compiler flag '**`/std:c++17`**'", since this behavior isn't required until C++17. + +### 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. Add **`/Zc:static_assert`** or **`/Zc:static_assert-`** to the **Additional options:** pane. + +## See also + +[`/Zc` (Conformance)](zc-conformance.md) diff --git a/docs/build/reference/zc-stdc.md b/docs/build/reference/zc-stdc.md new file mode 100644 index 0000000000..7a55aafc98 --- /dev/null +++ b/docs/build/reference/zc-stdc.md @@ -0,0 +1,60 @@ +--- +description: "Learn more about the /Zc:__STDC__ (Enable __STDC__ macro) compiler option." +title: "/Zc:__STDC__ (Enable __STDC__ macro)" +ms.date: 11/07/2022 +f1_keywords: ["/Zc:__STDC__"] +helpviewer_keywords: ["-Zc:__STDC__ compiler option (C++)", "/Zc:__STDC__ compiler option (C++)"] +--- +# `/Zc:__STDC__` (Enable `__STDC__` macro) + +The **`/Zc:__STDC__`** compiler option defines the built-in `__STDC__` preprocessor macro as 1 in C code. + +## Syntax + +> **`/Zc:__STDC__`** + +## Remarks + +The **`/Zc:__STDC__`** compiler option implements Standard C conforming behavior for the `__STDC__` preprocessor macro, setting it to 1 when compiling C11 and C17 code. + +The **`/Zc:__STDC__`** option is new in Visual Studio 2022 version 17.2. This option is off by default, but can be enabled explicitly when **`/std:c11`** or **`/std:c17`** is specified. There's no negative version of the option. + +This option is a source breaking change. Due to the behavior of the UCRT, which doesn't expose POSIX functions when `__STDC__` is `1`, it isn't possible to define this macro for C by default without introducing breaking changes to the stable language versions. + +### Example + +```c +// test__STDC__.c +#include +#include +#include + +int main() { +#if __STDC__ + int f = _open("file.txt", _O_RDONLY); + _close(f); +#else + int f = open("file.txt", O_RDONLY); + close(f); +#endif +} + +/* Command line behavior + +C:\Temp>cl /EHsc /W4 /Zc:__STDC__ test__STDC__.c && test__STDC__ + +*/ +``` + +### 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:__STDC__`*. Choose **OK** or **Apply** to save your changes. + +## See also + +[`/Zc` (Conformance)](zc-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 0000000000..a6ca453833 --- /dev/null +++ b/docs/build/reference/zc-templatescope.md @@ -0,0 +1,49 @@ +--- +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 +*/ +``` + +### 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/reference/zc-ternary.md b/docs/build/reference/zc-ternary.md index 25e18e1179..b77f0d7739 100644 --- a/docs/build/reference/zc-ternary.md +++ b/docs/build/reference/zc-ternary.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: `/Zc:ternary` (Enforce conditional operator rules)" title: "/Zc:ternary (Enforce conditional operator rules)" -ms.date: "09/12/2019" +description: "Learn more about: `/Zc:ternary` (Enforce conditional operator rules)" +ms.date: 09/12/2019 f1_keywords: ["/Zc:ternary"] helpviewer_keywords: ["/Zc:ternary", "Zc:ternary", "-Zc:ternary"] --- @@ -23,7 +23,7 @@ The **`/Zc:ternary`** option is off by default in Visual Studio 2017. Use **`/Zc ### Examples -This sample shows how a class that provides both non-explicit initialization from a type, and conversion to a type, can lead to ambiguous conversions. This code is accepted by the compiler by default, but rejected when **/`Zc:ternary`** or **`/permissive-`** is specified. +This sample shows how a class that provides both non-explicit initialization from a type, and conversion to a type, can lead to ambiguous conversions. This code is accepted by the compiler by default, but rejected when **`/Zc:ternary`** or **`/permissive-`** is specified. ```cpp // zcternary1.cpp @@ -49,7 +49,7 @@ int main() To fix this code, make an explicit cast to the preferred common type, or prevent one direction of type conversion. You can keep the compiler from matching a type conversion by making the conversion explicit. -An important exception to this common pattern is when the type of the operands is one of the null-terminated string types, such as `const char*`, `const char16_t*`, and so on. You can also reproduce the effect with array types and the pointer types they decay to. The behavior when the actual second or third operand to `?:` is a string literal of corresponding type depends on the language standard used. C++17 has changed semantics for this case from C++14. As a result, the compiler accepts the code in the following example under the default **`/std:c++14`**, but rejects it when you specify **`/std:c++17`**. +An important exception to this common pattern is when the type of the operands is one of the null-terminated string types, such as `const char*`, `const char16_t*`, and so on. You can also reproduce the effect with array types and the pointer types they decay to. The behavior when the actual second or third operand to `?:` is a string literal of corresponding type depends on the language standard used. C++17 has changed semantics for this case from C++14. As a result, the compiler accepts the code in the following example under the default **`/std:c++14`**, but rejects it when you specify **`/std:c++17`** or later. ```cpp // zcternary2.cpp diff --git a/docs/build/reference/zc-tlsguards.md b/docs/build/reference/zc-tlsguards.md new file mode 100644 index 0000000000..15c36abf13 --- /dev/null +++ b/docs/build/reference/zc-tlsguards.md @@ -0,0 +1,32 @@ +--- +title: "/Zc:tlsGuards (Check TLS initialization)" +description: "Learn more about the /Zc:tlsGuards (Check TLS initialization) compiler option." +ms.date: 11/08/2022 +f1_keywords: ["/Zc:tlsGuards"] +helpviewer_keywords: ["-Zc:tlsGuards compiler option (C++)", "/Zc:tlsGuards compiler option (C++)"] +--- +# `/Zc:tlsGuards` (Check TLS initialization) + +The **`/Zc:tlsGuards`** compiler option generates runtime checks for thread local storage (TLS) initialization in DLLs. + +## Syntax + +> **`/Zc:tlsGuards`**\[**`-`**] + +## Remarks + +The **`/Zc:tlsGuards`** compiler option enables checks for initialization of thread-local variables in DLLs. Previously, thread-local variables in DLLs weren't correctly initialized. Other than on the thread that loaded the DLL, they weren't initialized before first use on threads that existed before the DLL was loaded. The **`/Zc:tlsGuards`** option enables code that corrects this defect. Thread-local variables in such a DLL get initialized immediately before their first use on such threads. + +The **`/Zc:tlsGuards`** option is new in Visual Studio 2019 version 16.5. This option is on by default in all compiler modes. The new behavior of testing for initialization on uses of thread-local variables may be disabled by using the **`/Zc:tlsGuards-`** compiler option. To disable checks for specific thread-local variables, use the [`[[msvc::no_tls_guard]]`](../../cpp/attributes.md) attribute. + +### 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:tlsGuards`*. Choose **OK** or **Apply** to save your changes. + +## See also + +[`/Zc` (Conformance)](zc-conformance.md) diff --git a/docs/build/reference/zc-twophase.md b/docs/build/reference/zc-twophase.md index d4e1d5506b..5675256313 100644 --- a/docs/build/reference/zc-twophase.md +++ b/docs/build/reference/zc-twophase.md @@ -1,29 +1,29 @@ --- title: "/Zc:twoPhase- (disable two-phase name lookup)" description: "Explains how /Zc:twoPhase- disables two-phase name lookup when /permissive- is specified." -ms.date: "12/03/2019" +ms.date: 09/27/2022 f1_keywords: ["twoPhase", "/Zc:twoPhase"] helpviewer_keywords: ["twoPhase", "disable two-phase name lookup", "/Zc:twoPhase"] --- -# /Zc:twoPhase- (disable two-phase name lookup) +# `/Zc:twoPhase-` (disable two-phase name lookup) -The **/Zc:twoPhase-** option, under **/permissive-**, tells the compiler to use the original, non-conforming Microsoft C++ compiler behavior to parse and instantiate class templates and function templates. +The **`/Zc:twoPhase-`** option, under **`/permissive-`**, tells the compiler to use the original, non-conforming Microsoft C++ compiler behavior to parse and instantiate class templates and function templates. ## Syntax -> **/Zc:twoPhase-** +> **`/Zc:twoPhase-`** ## Remarks -Visual Studio 2017 version 15.3 and later: Under [/permissive-](permissive-standards-conformance.md), the compiler uses two-phase name lookup for template name resolution. If you also specify **/Zc:twoPhase-**, the compiler reverts to its previous non-conforming class template and function template name resolution and substitution behavior. When **/permissive-** isn't specified, the non-conforming behavior is the default. +Visual Studio 2017 version 15.3 and later: Under [`/permissive-`](permissive-standards-conformance.md), the compiler uses two-phase name lookup for template name resolution. If you also specify **`/Zc:twoPhase-`**, the compiler reverts to its previous non-conforming class template and function template name resolution and substitution behavior. When **`/permissive-`** isn't specified, the non-conforming behavior is the default. -The Windows SDK header files in version 10.0.15063.0 (Creators Update or RS2) and earlier don't work in conformance mode. **/Zc:twoPhase-** is required to compile code for those SDK versions when you use **/permissive-**. Versions of the Windows SDK starting with version 10.0.15254.0 (Fall Creators Update or RS3) work correctly in conformance mode. They don't require the **/Zc:twoPhase-** option. +The Windows SDK header files in version 10.0.15063.0 (Creators Update or RS2) and earlier don't work in conformance mode. **`/Zc:twoPhase-`** is required to compile code for those SDK versions when you use **`/permissive-`**. Versions of the Windows SDK starting with version 10.0.15254.0 (Fall Creators Update or RS3) work correctly in conformance mode. They don't require the **`/Zc:twoPhase-`** option. -Use **/Zc:twoPhase-** if your code requires the old behavior to compile correctly. Strongly consider updating your code to conform to the standard. +Use **`/Zc:twoPhase-`** if your code requires the old behavior to compile correctly. Strongly consider updating your code to conform to the standard. -### Compiler behavior under /Zc:twoPhase- +### Compiler behavior under `/Zc:twoPhase-` -By default, or in Visual Studio 2017 version 15.3 and later when you specify both **/permissive-** and **/Zc:twoPhase-**, the compiler uses this behavior: +By default, or in Visual Studio 2017 version 15.3 and later when you specify both **`/permissive-`** and **`/Zc:twoPhase-`**, the compiler uses this behavior: - It parses only the template declaration, the class head, and the base class list. The template body is captured as a token stream. No function bodies, initializers, default arguments, or noexcept arguments are parsed. The class template is pseudo-instantiated on a tentative type to validate that the declarations in the class template are correct. Consider this class template: @@ -33,7 +33,7 @@ By default, or in Visual Studio 2017 version 15.3 and later when you specify bot The template declaration, `template `, the class head `class Derived`, and the base-class list `public Base` are parsed, but the template body is captured as a token stream. -- When parsing a function template, the compiler parses only the function signature. The function body is never parsed. Instead, it's captured as a token stream. +- When it parses a function template, the compiler parses only the function signature. The function body is never parsed. Instead, it's captured as a token stream. As a result, if the template body has syntax errors, but the template never gets instantiated, the compiler doesn't diagnose the errors. @@ -65,7 +65,7 @@ int main() } ``` -Here's the output when you use the default mode, conformance mode, and conformance mode with **/Zc:twoPhase-** compiler options: +Here's the output when you use the default mode, conformance mode, and conformance mode with **`/Zc:twoPhase-`** compiler options: ```cmd C:\Temp>cl /EHsc /nologo /W4 zctwophase.cpp && zctwophase @@ -81,11 +81,11 @@ zctwophase.cpp Microsoft one-phase ``` -When compiled in conformance mode under **/permissive-**, this program prints "`Standard two-phase`", because the second overload of `func` isn't visible when the compiler reaches the template. If you add **/Zc:twoPhase-**, the program prints "`Microsoft one-phase`". The output is the same as when you don't specify **/permissive-**. +When compiled in conformance mode under **`/permissive-`**, this program prints "`Standard two-phase`", because the second overload of `func` isn't visible when the compiler reaches the template. If you add **`/Zc:twoPhase-`**, the program prints "`Microsoft one-phase`". The output is the same as when you don't specify **`/permissive-`**. -*Dependent names* are names that depend on a template parameter. These names have lookup behavior that is also different under **/Zc:twoPhase-**. In conformance mode, dependent names aren't bound at the point of the template's definition. Instead, the compiler looks them up when it instantiates the template. For function calls with a dependent function name, the name gets bound to functions visible at the call site in the template definition. Additional overloads from argument-dependent lookup are added, both at the point of the template definition, and at the point of template instantiation. +*Dependent names* are names that depend on a template parameter. These names have lookup behavior that is also different under **`/Zc:twoPhase-`**. In conformance mode, dependent names aren't bound at the point of the template's definition. Instead, the compiler looks them up when it instantiates the template. For function calls with a dependent function name, the name gets bound to functions visible at the call site in the template definition. Other overloads from argument-dependent lookup are added, both at the point of the template definition, and at the point of template instantiation. -Two-phase lookup consists of two parts: The lookup for non-dependent names during template definition, and the lookup for dependent names during template instantiation. Under **/Zc:twoPhase-**, the compiler doesn't do argument-dependent lookup separately from unqualified lookup. That is, it doesn't do two-phase lookup, so the results of overload resolution may be different. +Two-phase lookup consists of two parts: The lookup for non-dependent names during template definition, and the lookup for dependent names during template instantiation. Under **`/Zc:twoPhase-`**, the compiler doesn't do argument-dependent lookup separately from unqualified lookup. That is, it doesn't do two-phase lookup, so the results of overload resolution may be different. Here's another example: @@ -118,28 +118,28 @@ int main() { } ``` -When compiled without **/permissive-**, this code prints: +When compiled without **`/permissive-`**, this code prints: ```Output func(int) NS::func(NS::S) ``` -When compiled with **/permissive-**, but without **/Zc:twoPhase-**, this code prints: +When compiled with **`/permissive-`**, but without **`/Zc:twoPhase-`**, this code prints: ```Output func(long) NS::func(NS::S) ``` -When compiled with both **/permissive-** and **/Zc:twoPhase-**, this code prints: +When compiled with both **`/permissive-`** and **`/Zc:twoPhase-`**, this code prints: ```Output func(int) NS::func(NS::S) ``` -In conformance mode under **/permissive-**, the call `tfunc(1729)` resolves to the `void func(long)` overload. It doesn't resolve to the `void func(int)` overload, as under **/Zc:twoPhase-**. That's because the unqualified `func(int)` is declared after the definition of the template, and it isn't found through argument-dependent lookup. But `void func(S)` does participate in argument-dependent lookup, so it's added to the overload set for the call `tfunc(s)`, even though it's declared after the template function. +In conformance mode under **`/permissive-`**, the call `tfunc(1729)` resolves to the `void func(long)` overload. It doesn't resolve to the `void func(int)` overload, as under **`/Zc:twoPhase-`**. The reason is, the unqualified `func(int)` is declared after the definition of the template, and it isn't found through argument-dependent lookup. But `void func(S)` does participate in argument-dependent lookup, so it's added to the overload set for the call `tfunc(s)`, even though it's declared after the function template. ### Update your code for two-phase conformance @@ -151,7 +151,7 @@ A conforming compiler parses `Foo` as a variable in the scope of `T`, meaning th `T::template Foo(c);` -In versions Visual Studio 2017 version 15.3 and later, when **/permissive-** and **/Zc:twoPhase-** are specified, the compiler allows this code without the **`template`** keyword. It interprets the code as a call to a function template with an argument of `a || b`, because it only parses templates in a limited fashion. The code above isn't parsed at all in the first phase. During the second phase, there's enough context to tell that `T::Foo` is a template rather than a variable, so the compiler doesn't enforce use of the keyword. +In versions Visual Studio 2017 version 15.3 and later, when **`/permissive-`** and **`/Zc:twoPhase-`** are specified, the compiler allows this code without the **`template`** keyword. It interprets the code as a call to a function template with an argument of `a || b`, because it only parses templates in a limited fashion. The code above isn't parsed at all in the first phase. During the second phase, there's enough context to tell that `T::Foo` is a template rather than a variable, so the compiler doesn't enforce use of the keyword. This behavior can also be seen by eliminating the keyword **`typename`** before names in function template bodies, initializers, default arguments, and noexcept arguments. For example: @@ -163,7 +163,7 @@ typename T::TYPE func(typename T::TYPE*) } ``` -If you don't use the keyword **`typename`** in the function body, this code compiles under **/permissive- /Zc:twoPhase-**, but not under **/permissive-** alone. The **`typename`** keyword is required to indicate that the `TYPE` is dependent. Because the body isn't parsed under **/Zc:twoPhase-**, the compiler does't require the keyword. In **/permissive-** conformance mode, code without the **`typename`** keyword generates errors. To migrate your code to conformance in Visual Studio 2017 version 15.3 and beyond, insert the **`typename`** keyword where it's missing. +If you don't use the keyword **`typename`** in the function body, this code compiles under **`/permissive- /Zc:twoPhase-`**, but not under **`/permissive-`** alone. The **`typename`** keyword is required to indicate that the `TYPE` is dependent. Because the body isn't parsed under **`/Zc:twoPhase-`**, the compiler doesn't require the keyword. In **`/permissive-`** conformance mode, code without the **`typename`** keyword generates errors. To migrate your code to conformance in Visual Studio 2017 version 15.3 and beyond, insert the **`typename`** keyword where it's missing. Similarly, consider this code sample: @@ -175,9 +175,9 @@ typename T::template X::TYPE func(typename T::TYPE) } ``` -Under **/permissive- /Zc:twoPhase-** and in older compilers, the compiler only requires the **`template`** keyword on line 2. In conformance mode, the compiler now also requires the **`template`** keyword on line 4 to indicate that `T::X` is a template. Look for code that is missing this keyword, and supply it to make your code conform to the standard. +Under **`/permissive- /Zc:twoPhase-`** and in older compilers, the compiler only requires the **`template`** keyword on line 2. In conformance mode, the compiler now also requires the **`template`** keyword on line 4 to indicate that `T::X` is a template. Look for code that is missing this keyword, and supply it to make your code conform to the standard. -For more information about conformance issues, see [C++ conformance improvements in Visual Studio](../../overview/cpp-conformance-improvements.md) and [Nonstandard Behavior](../../cpp/nonstandard-behavior.md). +For more information about conformance issues, see [C++ conformance improvements in Visual Studio](../../overview/cpp-conformance-improvements.md) and [Nonstandard behavior](../../cpp/nonstandard-behavior.md). ### To set this compiler option in the Visual Studio development environment @@ -185,8 +185,8 @@ For more information about conformance issues, see [C++ conformance improvements 1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Modify the **Additional Options** property to include **/Zc:twoPhase-** and then choose **OK**. +1. Modify the **Additional Options** property to include *`/Zc:twoPhase-`* and then choose **OK**. ## See also -[/Zc (Conformance)](zc-conformance.md) +[`/Zc` (Conformance)](zc-conformance.md) diff --git a/docs/build/reference/zc-zerosizearraynew.md b/docs/build/reference/zc-zerosizearraynew.md new file mode 100644 index 0000000000..05abb101da --- /dev/null +++ b/docs/build/reference/zc-zerosizearraynew.md @@ -0,0 +1,32 @@ +--- +title: "/Zc:zeroSizeArrayNew (Call member new/delete on arrays)" +description: "Learn more about the /Zc:zeroSizeArrayNew (Call member new/delete on arrays) compiler option." +ms.date: 11/08/2022 +f1_keywords: ["/Zc:zeroSizeArrayNew"] +helpviewer_keywords: ["-Zc:zeroSizeArrayNew compiler option (C++)", "/Zc:zeroSizeArrayNew compiler option (C++)"] +--- +# `/Zc:zeroSizeArrayNew` (Call member new/delete on arrays) + +The **`/Zc:zeroSizeArrayNew`** compiler option calls member `new` and `delete` for zero-length arrays of objects. + +## Syntax + +> **`/Zc:zeroSizeArrayNew`**\[**`-`**] + +## Remarks + +The **`/Zc:zeroSizeArrayNew`** compiler option enables calls to member `new` and `delete` for zero-length arrays of objects of class types with virtual destructors. This behavior conforms to the standard. This compiler option is new in Visual Studio 2019 version 16.9 and is enabled by default in all compiler modes. Previously, in code compiled by versions before Visual Studio 2019 version 16.9, the compiler invoked global `new` and `delete` on zero-length arrays of objects of class types with virtual destructors. + +The **`/Zc:zeroSizeArrayNew`** option may cause a breaking change in code that relied on the previous non-conforming behavior. To restore the previous behavior, use the **`/Zc:zeroSizeArrayNew-`** compiler option. + +### 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:zeroSizeArrayNew`* or *`/Zc:zeroSizeArrayNew-`*. Choose **OK** or **Apply** to save your changes. + +## See also + +[`/Zc` (Conformance)](zc-conformance.md) diff --git a/docs/build/reference/zf.md b/docs/build/reference/zf.md index ab3ffec213..d15547b2e8 100644 --- a/docs/build/reference/zf.md +++ b/docs/build/reference/zf.md @@ -19,7 +19,7 @@ The **/Zf** option enables compiler support for faster generation of PDB files w Because the **/Zf** option only applies to PDB generation, it requires the [/Zi](z7-zi-zi-debug-information-format.md) or [/ZI](z7-zi-zi-debug-information-format.md) option. -The **/Zf** option is available beginning in Visual Studio 2017 version 15.1, where it is off by default. Starting in Visual Studio 2017 version 15.7 Preview 3, this option is on by default when the **/Zi** or **/ZI** option is enabled. +The **/Zf** option is available beginning in Visual Studio 2017 version 15.1, where it is off by default. Starting in Visual Studio 2017 version 15.7, this option is on by default when the **/Zi** or **/ZI** option is enabled. ### To set this compiler option in the Visual Studio development environment diff --git a/docs/build/reference/zh.md b/docs/build/reference/zh.md index 728569bc3c..3cefaf8e71 100644 --- a/docs/build/reference/zh.md +++ b/docs/build/reference/zh.md @@ -1,48 +1,50 @@ --- title: "/ZH (Hash algorithm for calculation of file checksum in debug info)" description: "Use the /ZH compiler option to enable MD5, SHA-1, or SHA-256 source file checksums in debug info" -ms.date: "09/16/2019" +ms.date: 02/01/2022 f1_keywords: ["/ZH", "/ZH:MD5", "/ZH:SHA1", "/ZH:SHA_256"] helpviewer_keywords: ["/ZH", "/ZH:MD5", "/ZH:SHA1", "/ZH:SHA_256", "/ZH compiler option", "/ZH:MD5 compiler option", "/ZH:SHA1 compiler option", "/ZH:SHA_256 compiler option", "Hash algorithm for file checksum in debug info"] --- -# /ZH (Hash algorithm for calculation of file checksum in debug info) +# `/ZH` (Hash algorithm for calculation of file checksum in debug info) Specifies which cryptographic hash algorithm to use to generate a checksum of each source file. ## Syntax -> **/ZH:**{**MD5**|**SHA1**|**SHA_256**} +> **`/ZH:MD5`**\ +> **`/ZH:SHA1`**\ +> **`/ZH:SHA_256`** ## Arguments -**/ZH:MD5**\ -Use an MD5 hash for the checksum. This option is the default. +**`/ZH:MD5`**\ +Use an MD5 hash for the checksum. This option is the default in Visual Studio 2019. -**/ZH:SHA1**\ +**`/ZH:SHA1`**\ Use an SHA-1 hash for the checksum. -**/ZH:SHA_256**\ -Use an SHA-256 hash for the checksum. +**`/ZH:SHA_256`**\ +Use an SHA-256 hash for the checksum. This option is the default in Visual Studio 2022 version 17.0 and later. ## Remarks -PDB files store a checksum for each source file compiled into the object code in the associated executable. The checksum allows the debugger to verify that the source code it loads matches the executable. The compiler and debugger support MD5, SHA-1, and SHA-256 hash algorithms. By default, the compiler uses an MD5 hash to generate the checksum. You can specify this option explicitly by using the **/ZH:MD5** option. +PDB files store a checksum for each source file, compiled into the object code in the associated executable. The checksum allows the debugger to verify that the source code it loads matches the executable. The compiler and debugger support MD5, SHA-1, and SHA-256 hash algorithms. By default, in Visual Studio 2019 the compiler uses an MD5 hash to generate the checksum. To specify this hash algorithm explicitly, use the **`/ZH:MD5`** option. -Because of a risk of collision problems in MD5 and SHA-1, Microsoft recommends you use the **/ZH:SHA_256** option. The SHA-256 hash may result in a small increase in compile times. +Because of a risk of collision problems in MD5 and SHA-1, Microsoft recommends you use the **`/ZH:SHA_256`** option. The SHA-256 hash might result in a small increase in compile times. The **`/ZH:SHA_256`** option is the default in Visual Studio 2022 version 17.0 and later. -When more than one **/ZH** option is specified, the last option is used. +When more than one **`/ZH`** option is specified, the last option is used. -The **/ZH** option is available starting in Visual Studio 2019 version 16.4. +The **`/ZH`** option is available in Visual Studio 2019 version 16.4 and later. ### To set this compiler option in the Visual Studio development environment -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. Open the **Property Pages** dialog box for the project. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). -1. Set the **Configuration** drop-down to **All Configurations**. +1. Set the **Configuration** drop-down to **All Configurations**. Set the **Platform** drop-down to **All Platforms**. 1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Modify the **Additional options** property to add a **/ZH:MD5**, **/ZH:SHA1**, or **/ZH:SHA_256** option, and then choose **OK**. +1. Modify the **Additional options** property to add a **`/ZH:MD5`**, **`/ZH:SHA1`**, or **`/ZH:SHA_256`** option, and then choose **OK**. ## See also diff --git a/docs/build/reference/zm-specify-precompiled-header-memory-allocation-limit.md b/docs/build/reference/zm-specify-precompiled-header-memory-allocation-limit.md index 0eef814ed4..f587fd78fd 100644 --- a/docs/build/reference/zm-specify-precompiled-header-memory-allocation-limit.md +++ b/docs/build/reference/zm-specify-precompiled-header-memory-allocation-limit.md @@ -1,49 +1,47 @@ --- -description: "Learn more about: /Zm (Specify Precompiled Header Memory Allocation Limit)" -title: "/Zm (Specify Precompiled Header Memory Allocation Limit)" -ms.date: "03/08/2019" -f1_keywords: ["/zm"] +description: "Learn more about: /Zm (Specify precompiled header memory allocation limit)" +title: "/Zm (Specify precompiled header memory allocation limit)" +ms.date: 02/22/2022 +f1_keywords: ["/Zm"] helpviewer_keywords: ["PCH files, memory allocation limit", "Zm compiler option [C++]", "/Zm compiler option [C++]", "precompiled header files, memory allocation limit", "Specify Precompiled Header Memory Allocation Limit compiler option", "cl.exe compiler, memory allocation limit", ".pch files, memory allocation limit", "memory allocation, Memory Allocation Limit compiler option", "-Zm compiler option [C++]"] ms.assetid: 94c77d5e-6672-46a7-92e0-3f69e277727d --- -# /Zm (Specify Precompiled Header Memory Allocation Limit) +# `/Zm` (Specify precompiled header memory allocation limit) Determines the amount of memory that the compiler allocates to construct precompiled headers. ## Syntax -``` -/Zmfactor -``` +> **`/Zm`***`factor`* ## Arguments -*factor*
-A scaling factor that determines the amount of memory that the compiler uses to construct precompiled headers. +*`factor`*
+A scaling factor percentage that determines the amount of memory that the compiler uses to construct precompiled headers. -The *factor* argument is a percentage of the default size of a compiler-defined work buffer. The default value of *factor* is 100 (percent), but you can specify larger or smaller amounts. +The *`factor`* argument is a percentage of the default size of a compiler-defined work buffer. The default value of *`factor`* is 100 (percent), but you can specify larger or smaller amounts. ## Remarks -In versions before Visual Studio 2015, the C++ compiler used several discrete heaps, and each had a finite limit. Currently, the compiler dynamically grows the heaps as necessary up to a total heap size limit, and allows the precompiled header to comprise multiple address ranges. Consequently, the **/Zm** compiler option is rarely necessary. +In versions before Visual Studio 2015, the C++ compiler used several discrete heaps, and each had a finite limit. Currently, the compiler dynamically grows the heaps as necessary up to a total heap size limit, and allows the precompiled header to comprise multiple address ranges. Now, the **`/Zm`** compiler option is rarely necessary. -If the compiler runs out of heap space and emits the [C1060](../../error-messages/compiler-errors-1/fatal-error-c1060.md) error message when you use the **/Zm** compiler option, you might have reserved too much memory. Consider removing the **/Zm** option. +If the compiler runs out of heap space and emits the [C1060](../../error-messages/compiler-errors-1/fatal-error-c1060.md) error message when you use the **`/Zm`** compiler option, you might have reserved too much memory. Consider removing the **`/Zm`** option. -If the compiler emits the [C1076](../../error-messages/compiler-errors-1/fatal-error-c1076.md) error message, an accompanying [C3859](../../error-messages/compiler-errors-2/compiler-error-c3859.md) message specifies the *factor* argument to use when you recompile by using the **/Zm** compiler option. This message is only significant when a precompiled header uses `#pragma hdrstop`. In other cases, it is a spurious error caused by Windows virtual memory pressure issues, and the recommendation to use the **/Zm** option should be ignored. Instead, consider reducing the number of parallel processes when using the **/maxcpucount** option to MSBUILD.EXE in conjunction with the **/MP** option to CL.EXE. For more information, see [Precompiled Header (PCH) issues and recommendations](https://devblogs.microsoft.com/cppblog/precompiled-header-pch-issues-and-recommendations/). +If the compiler emits the [C1076](../../error-messages/compiler-errors-1/fatal-error-c1076.md) error message, an accompanying [C3859](../../error-messages/compiler-errors-2/compiler-error-c3859.md) message specifies the *`factor`* argument to use when you recompile by using the **`/Zm`** compiler option. This message is only significant when a precompiled header uses `#pragma hdrstop`. In other cases, it's a spurious error caused by Windows virtual memory pressure issues, and the recommendation to use the **`/Zm`** option should be ignored. Instead, consider reducing the number of parallel processes when using the **`/maxcpucount`** option to MSBUILD.EXE together with the **`/MP`** option to CL.EXE. For more information, see [Precompiled Header (PCH) issues and recommendations](https://devblogs.microsoft.com/cppblog/precompiled-header-pch-issues-and-recommendations/). -The following table shows how the *factor* argument affects the memory allocation limit if you assume the size of the default precompiled header buffer is 75 MB. +The following table shows how the *`factor`* argument affects the memory allocation limit. In the table, we assume the size of the default precompiled header buffer is 75 MB. -|Value of *factor*|Memory allocation limit| -|-----------------------|-----------------------------| -|10|7.5 MB| -|100|75 MB| -|200|150 MB| -|1000|750 MB| -|2000|1500 MB| +| Value of *`factor`* | Memory allocation limit | +|--|--| +| 10 | 7.5 MB | +| 100 | 75 MB | +| 200 | 150 MB | +| 1000 | 750 MB | +| 2000 | 1500 MB | -## Other Ways to Set the Memory Allocation Limit +## Other ways to set the memory allocation limit -### To set the /Zm compiler option in the Visual Studio development environment +### To set the `/Zm` compiler option in the Visual Studio development environment 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). @@ -51,11 +49,11 @@ The following table shows how the *factor* argument affects the memory allocatio 1. Enter the **/Zm** compiler option in the **Additional Options** box. -### To set the /Zm compiler option programmatically +### To set the `/Zm` compiler option programmatically - See . ## See also -[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) +[MSVC compiler options](compiler-options.md)
+[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/zo-enhance-optimized-debugging.md b/docs/build/reference/zo-enhance-optimized-debugging.md index c698def89f..c4ff8c18fa 100644 --- a/docs/build/reference/zo-enhance-optimized-debugging.md +++ b/docs/build/reference/zo-enhance-optimized-debugging.md @@ -1,7 +1,7 @@ --- description: "Learn more about: /Zo (Enhance Optimized Debugging)" title: "/Zo (Enhance Optimized Debugging)" -ms.date: "11/04/2016" +ms.date: 06/01/2022 f1_keywords: ["-Zo", "/Zo"] helpviewer_keywords: ["Zo compiler option [C++]", "/Zo compiler option [C++]", "-Zo compiler option [C++]"] ms.assetid: eea8d89a-7fe0-4fe1-86b2-7689bbebbd7f @@ -12,17 +12,17 @@ Generate enhanced debugging information for optimized code in non-debug builds. ## Syntax -```cpp -/Zo[-] -``` +> **`/Zo`**\[**`-`**] ## Remarks -The **/Zo** compiler switch generates enhanced debugging information for optimized code. Optimization may use registers for local variables, reorder code, vectorize loops, and inline function calls. These optimizations can obscure the relationship between the source code and the compiled object code. The **/Zo** switch tells the compiler to generate additional debugging information for local variables and inlined functions. Use it to see variables in the **Autos**, **Locals**, and **Watch** windows when you step through optimized code in the Visual Studio debugger. It also enables stack traces to show inlined functions in the WinDBG debugger. Debug builds that have disabled optimizations ([/Od](od-disable-debug.md)) do not need the additional debugging information generated when **/Zo** is specified. Use the **/Zo** switch to debug Release configurations with optimization turned on. For more information on optimization switches, see [/O Options (Optimize Code)](o-options-optimize-code.md). The **/Zo** option is enabled by default in Visual Studio when you specify debugging information with **/Zi** or **/Z7**. Specify **/Zo-** to explicitly disable this compiler option. +The **`/Zo`** compiler option generates enhanced debugging information for optimized code. Optimization may use registers for local variables, reorder code, vectorize loops, and inline function calls. These optimizations can obscure the relationship between the source code and the compiled object code. The **`/Zo`** option tells the compiler to generate extra debugging information for local variables and inlined functions. It allows you to see variables in the **Autos**, **Locals**, and **Watch** windows when you step through optimized code in the Visual Studio debugger. It also enables stack traces to show inlined functions in the WinDBG debugger. Debug builds that have disabled optimizations ([`/Od`](od-disable-debug.md)) don't need the extra debugging information generated when **`/Zo`** is specified. Use the **`/Zo`** option to debug Release configurations with optimization turned on. For more information on optimization options, see [`/O` options (Optimize Code)](o-options-optimize-code.md). -The **/Zo** switch is available starting in Visual Studio 2013 Update 3, and it replaces the previously undocumented **/d2Zi+** switch. +The **`/Zo`** option is enabled by default when you specify debugging information with **`/Zi`** or **`/Z7`**. It's disabled by the **`/ZI`** compiler option. Specify **`/Zo-`** to explicitly disable this compiler option. -### To set the /Zo compiler option in Visual Studio +The **`/Zo`** option is available starting in Visual Studio 2013 Update 3, and it replaces the previously undocumented **`/d2Zi+`** option. + +### To set the `/Zo` compiler option in Visual Studio 1. Open the **Property Pages** dialog box for the project. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). @@ -36,6 +36,6 @@ The **/Zo** switch is available starting in Visual Studio 2013 Update 3, and it ## See also -[/O Options (Optimize Code)](o-options-optimize-code.md)
-[/Z7, /Zi, /ZI (Debug Information Format)](z7-zi-zi-debug-information-format.md)
+[`/O` Options (Optimize code)](o-options-optimize-code.md)\ +[`/Z7`, `/Zi`, `/ZI` (Debug information format)](z7-zi-zi-debug-information-format.md)\ [Edit and Continue](/visualstudio/debugger/edit-and-continue) diff --git a/docs/build/reference/zp-struct-member-alignment.md b/docs/build/reference/zp-struct-member-alignment.md index ae6c91578b..cfb89975b2 100644 --- a/docs/build/reference/zp-struct-member-alignment.md +++ b/docs/build/reference/zp-struct-member-alignment.md @@ -26,12 +26,12 @@ The available packing values are described in the following table: |2|Packs structures on 2-byte boundaries.| |4|Packs structures on 4-byte boundaries.| |8|Packs structures on 8-byte boundaries (default for x86, ARM, and ARM64).| -|16| Packs structures on 16-byte boundaries (default for x64).| +|16| Packs structures on 16-byte boundaries (default for x64 and ARM64EC).| Don't use this option unless you have specific alignment requirements. > [!WARNING] -> The C/C++ headers in the Windows SDK assume **`/Zp8`** packing internally. Don't change the setting from the default when you include the Windows SDK headers, either by using **`/Zp`** on the command line or by using `#pragma pack`. Otherwise, your application may cause memory corruption at runtime. +> The C/C++ headers in the Windows SDK assume the platform's default alignment is used. Don't change the setting from the default when you include the Windows SDK headers, either by using **`/Zp`** on the command line or by using `#pragma pack`. Otherwise, your application may cause memory corruption at runtime. You can also use the [`pack` pragma](../../preprocessor/pack.md) to control structure packing. For more information about alignment, see: diff --git a/docs/build/reference/zw-windows-runtime-compilation.md b/docs/build/reference/zw-windows-runtime-compilation.md index b93a6d5745..6bba2c712c 100644 --- a/docs/build/reference/zw-windows-runtime-compilation.md +++ b/docs/build/reference/zw-windows-runtime-compilation.md @@ -1,16 +1,16 @@ --- description: "Learn more about: /ZW (Windows Runtime Compilation)" title: "/ZW (Windows Runtime Compilation)" -ms.date: "04/08/2019" +ms.date: 06/22/2023 f1_keywords: ["VC.Project.VCCLCompilerTool.CompileAsWinRT", "/zw"] helpviewer_keywords: ["/ZW", "-ZW compiler option", "/ZW compiler option", "-ZW", "Windows Runtime compiler option"] -ms.assetid: 0fe362b0-9526-498b-96e0-00d7a965a248 --- -# /ZW (Windows Runtime Compilation) +# `/ZW` (Windows Runtime Compilation) Compiles source code to support Microsoft C++ component extensions C++/CX for the creation of Universal Windows Platform (UWP) apps. -When you use **/ZW** to compile, always specify **/EHsc** as well. +When you use **`/ZW`** to compile, always specify **`/EHsc`** as well.\ +**`/ZW`** isn't compatible with **`/std:c++20`**. ## Syntax @@ -21,18 +21,18 @@ When you use **/ZW** to compile, always specify **/EHsc** as well. ## Arguments -**nostdlib**
-Indicates that Platform.winmd, Windows.Foundation.winmd, and other default Windows metadata (.winmd) files are not automatically included in the compilation. Instead, you must use the [/FU (Name Forced #using File)](fu-name-forced-hash-using-file.md) compiler option to explicitly specify Windows metadata files. +**`nostdlib`**\ +Indicates that `Platform.winmd`, `Windows.Foundation.winmd`, and other default Windows metadata (`.winmd`) files aren't automatically included in the compilation. Instead, you must use the [`/FU` (Name Forced #using File)](fu-name-forced-hash-using-file.md) compiler option to explicitly specify Windows metadata files. ## Remarks -When you specify the **/ZW** option, the compiler supports these features: +When you specify the **`/ZW`** option, the compiler supports these features: - The required metadata files, namespaces, data types, and functions that your app requires to execute in the Windows Runtime. - Automatic reference-counting of Windows Runtime objects, and automatic discarding of an object when its reference count goes to zero. -Because the incremental linker does not support the Windows metadata included in .obj files by using the **/ZW** option, the deprecated [/Gm (Enable Minimal Rebuild)](gm-enable-minimal-rebuild.md) option is incompatible with **/ZW**. +Because the incremental linker doesn't support the Windows metadata included in .obj files by using the **`/ZW`** option, the deprecated [/Gm (Enable Minimal Rebuild)](gm-enable-minimal-rebuild.md) option is incompatible with **`/ZW`**. For more information, see [Visual C++ Language Reference](../../cppcx/visual-c-language-reference-c-cx.md). @@ -40,5 +40,5 @@ For more information, see [Visual C++ Language Reference](../../cppcx/visual-c-l ## See also -[MSVC Compiler Options](compiler-options.md)
+[MSVC Compiler Options](compiler-options.md)\ [MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) diff --git a/docs/build/run-time-library-behavior.md b/docs/build/run-time-library-behavior.md index f2304bc108..1a85ae8d84 100644 --- a/docs/build/run-time-library-behavior.md +++ b/docs/build/run-time-library-behavior.md @@ -41,7 +41,7 @@ extern "C" BOOL WINAPI DllMain ( Some libraries wrap the `DllMain` function for you. For example, in a regular MFC DLL, implement the `CWinApp` object's `InitInstance` and `ExitInstance` member functions to perform initialization and termination required by your DLL. For more details, see the [Initialize regular MFC DLLs](#initializing-regular-dlls) section. > [!WARNING] -> There are significant limits on what you can safely do in a DLL entry point. See [General Best Practices](/windows/win32/Dlls/dynamic-link-library-best-practices) for specific Windows APIs that are unsafe to call in `DllMain`. If you need anything but the simplest initialization then do that in an initialization function for the DLL. You can require applications to call the initialization function after `DllMain` has run and before they call any other functions in the DLL. +> There are significant limits on what you can safely do in a DLL entry point. For more information about specific Windows APIs that are unsafe to call in `DllMain`, see [General Best Practices](/windows/win32/Dlls/dynamic-link-library-best-practices). If you need anything but the simplest initialization then do that in an initialization function for the DLL. You can require applications to call the initialization function after `DllMain` has run and before they call any other functions in the DLL. diff --git a/docs/build/setting-the-path-and-environment-variables-for-command-line-builds.md b/docs/build/setting-the-path-and-environment-variables-for-command-line-builds.md deleted file mode 100644 index 934702b9a1..0000000000 --- a/docs/build/setting-the-path-and-environment-variables-for-command-line-builds.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -description: "Learn more about: Set the Path and Environment Variables for Command-Line Builds" -title: "Set the Path and Environment Variables for Command-Line Builds" -ms.custom: "conceptual" -ms.date: "07/24/2019" -helpviewer_keywords: ["environment variables [C++]", "VCVARS32.bat file", "cl.exe compiler [C++], environment variables", "LINK tool [C++], environment variables", "PATH reserved word", "INCLUDE reserved word", "LINK tool [C++], path", "LIB environment variable", "compiling source code [C++], from command line", "environment variables [C++], CL compiler"] -ms.assetid: 99389528-deb5-43b9-b99a-03c8773ebaf4 ---- -# Set the Path and Environment Variables for Command-Line Builds - -The Microsoft C++ (MSVC) command-line build tools require several environment variables that are customized for your installation and build configuration. When a C++ workload is installed by the Visual Studio installer, it creates customized command files, or batch files, that set the required environment variables. The installer then uses these command files to create shortcuts for the Windows Start menu to open a developer command prompt window. These shortcuts set up the environment variables for a specific build configuration. When you want to use the command-line tools, you can run one of these shortcuts, or you can open a plain command prompt window and then run one of the custom command files to set the build configuration environment yourself. For more information, see [Use the MSVC toolset from the command line](building-on-the-command-line.md). To use the command files with a plain command prompt, see the section entitled [Developer command file locations](building-on-the-command-line.md#developer_command_file_locations). - -The MSVC command-line tools use the PATH, TMP, INCLUDE, LIB, and LIBPATH environment variables, and also use other environment variables specific to your installed tools, platforms, and SDKs. Even a simple Visual Studio installation may set twenty or more environment variables. Because the values of these environment variables are specific to your installation and your choice of build configuration, and can be changed by product updates or upgrades, we strongly recommend that you use a developer command prompt shortcut or one of the customized command files to set them, instead of setting them in the Windows environment yourself. - -To see which environment variables are set by a developer command prompt shortcut, you can use the SET command. Open a plain command prompt window and capture the output of the SET command for a baseline. Open a developer command prompt window and capture the output of the SET command for comparison. A diff tool such as the one built into the Visual Studio IDE can be useful to compare the environment variables and see what is set by the developer command prompt. For information about the specific environment variables used by the compiler and linker, see [CL Environment Variables](reference/cl-environment-variables.md). - -> [!NOTE] -> Several command-line tools or tool options may require Administrator permission. If you have permission issues when you use them, we recommend that you open the developer command prompt window by using the **Run as Administrator** option. On Windows 10, right-click to open the shortcut menu for the command prompt window, then choose **More**, **Run as administrator**. - -## See also - -[Use the MSVC toolset from the command line](building-on-the-command-line.md)
-[MSVC linker reference](reference/linking.md)
-[MSVC Linker Options](reference/linker-options.md)
-[MSVC Compiler Reference](reference/compiling-a-c-cpp-program.md)
-[MSVC Compiler Options](reference/compiler-options.md) diff --git a/docs/build/stack-usage.md b/docs/build/stack-usage.md index a5afa4b096..8bbec4908e 100644 --- a/docs/build/stack-usage.md +++ b/docs/build/stack-usage.md @@ -22,7 +22,7 @@ The stack will always be maintained 16-byte aligned, except within the prolog (f The following is an example of the stack layout where function A calls a non-leaf function B. Function A's prolog has already allocated space for all the register and stack parameters required by B at the bottom of the stack. The call pushes the return address and B's prolog allocates space for its local variables, nonvolatile registers, and the space needed for it to call functions. If B uses `alloca`, the space is allocated between the local variable/nonvolatile register save area and the parameter stack area. -![AMD conversion example](../build/media/vcamd_conv_ex_5.png "AMD conversion example") +![Diagram of the stack layout for the x64 conversion example.](../build/media/vcamd_conv_ex_5.png "AMD conversion example") When the function B calls another function, the return address is pushed just below the home address for RCX. diff --git a/docs/build/tips-for-improving-time-critical-code.md b/docs/build/tips-for-improving-time-critical-code.md index 851573a550..aa3481e9e2 100644 --- a/docs/build/tips-for-improving-time-critical-code.md +++ b/docs/build/tips-for-improving-time-critical-code.md @@ -7,7 +7,7 @@ ms.assetid: 3e95a8cc-6239-48d1-9d6d-feb701eccb54 --- # Tips for Improving Time-Critical Code -Writing fast code requires understanding all aspects of your application and how it interacts with the system. This topic suggests alternatives to some of the more obvious coding techniques to help you ensure that the time-critical portions of your code perform satisfactorily. +Writing fast code requires understanding all aspects of your application and how it interacts with the system. This article suggests alternatives to some of the more obvious coding techniques to help you ensure that the time-critical portions of your code perform satisfactorily. To summarize, improving time-critical code requires that you: @@ -41,13 +41,13 @@ To gather information on the performance of your code, you can use the performan Missed cache hits, on both the internal and external cache, as well as page faults (going to secondary storage for program instructions and data) slow the performance of a program. -A CPU cache hit can cost your program 10-20 clock cycles. An external cache hit can cost 20-40 clock cycles. A page fault can cost one million clock cycles (assuming a processor that handles 500 million instructions/second and a time of 2 millisecond for a page fault). Therefore, it is in the best interest of program execution to write code that will reduce the number of missed cache hits and page faults. +A CPU cache hit can cost your program 10-20 clock cycles. An external cache hit can cost 20-40 clock cycles. A page fault can cost a million clock cycles (assuming a processor that handles 500 million instructions/second and a time of 2 millisecond for a page fault). Therefore, it is in the best interest of program execution to write code that will reduce the number of missed cache hits and page faults. -One reason for slow programs is that they take more page faults or miss the cache more often than necessary. To avoid this, it's important to use data structures with good locality of reference, which means keeping related things together. Sometimes a data structure that looks great turns out to be horrible because of poor locality of reference, and sometimes the reverse is true. Here are two examples: +One reason for slow programs is that they take more page faults or miss the cache more often than necessary. To avoid this problem, it's important to use data structures with good locality of reference, which means keeping related things together. Sometimes a data structure that looks great turns out to be horrible because of poor locality of reference, and sometimes the reverse is true. Here are two examples: -- Dynamically allocated linked lists can reduce program performance because when you search for an item or when you traverse a list to the end, each skipped link could miss the cache or cause a page fault. A list implementation based on simple arrays might actually be much faster because of better caching and fewer page faults even — allowing for the fact that the array would be harder to grow, it still might be faster. +- Dynamically allocated linked lists can reduce program performance. When you search for an item, or when you traverse a list to the end, each skipped link could miss the cache or cause a page fault. A list implementation based on simple arrays might be faster because of better caching and fewer page faults. Even if you allow for the fact that the array would be harder to grow, it still might be faster. -- Hash tables that use dynamically allocated linked lists can degrade performance. By extension, hash tables that use dynamically allocated linked lists to store their contents might perform substantially worse. In fact, in the final analysis, a simple linear search through an array might actually be faster (depending on the circumstances). Array-based hash tables (so-called "closed hashing") is an often-overlooked implementation which frequently has superior performance. +- Hash tables that use dynamically allocated linked lists can degrade performance. By extension, hash tables that use dynamically allocated linked lists to store their contents might perform substantially worse. In fact, in the final analysis, a simple linear search through an array might actually be faster (depending on the circumstances). Use of an array-based hash table (so-called "closed hashing") is an often-overlooked implementation that frequently has superior performance. ## Sorting and Searching @@ -59,49 +59,49 @@ Sorting is inherently time consuming compared to many typical operations. The be - Sort only the part of the data that truly needs sorting. -Sometimes, you can build the list in sorted order. Be careful, because if you need to insert data in sorted order, you may require a more complicated data structure with poor locality of reference, leading to cache misses and page faults. There is no approach that works in all cases. Try several approaches and measure the differences. +Sometimes, you can build the list in sorted order. Be careful, because if you need to insert data in sorted order, you may require a more complicated data structure with poor locality of reference, leading to cache misses and page faults. There's no approach that works in all cases. Try several approaches and measure the differences. Here are some general tips for sorting: - Use a stock sort to minimize bugs. -- Any work you can do beforehand to reduce the complexity of the sort is worthwhile. If a one-time pass over your data simplifies the comparisons and reduces the sort from O(n log n) to O(n), you will almost certainly come out ahead. +- Any work you can do beforehand to reduce the complexity of the sort is worthwhile. If a one-time pass over your data simplifies the comparisons and reduces the sort from O(n log n) to O(n), you'll almost certainly come out ahead. - Think about the locality of reference of the sort algorithm and the data you expect it to run on. -There are fewer alternatives for searches than for sorting. If the search is time-critical, a binary search or hash table lookup is almost always best, but as with sorting, you must keep locality in mind. A linear search through a small array can be faster than a binary search through a data structure with a lot of pointers that causes page faults or cache misses. +There are fewer alternatives for searches than for sorting. If the search is time-critical, a binary search or hash table lookup is almost always best, but as with sorting, you must keep locality in mind. A linear search through a small array can be faster than a binary search through a data structure with many pointers that causes page faults or cache misses. ## MFC and Class Libraries The Microsoft Foundation Classes (MFC) can greatly simplify writing code. When writing time-critical code, you should be aware of the overhead inherent in some of the classes. Examine the MFC code that your time-critical code uses to see if it meets your performance requirements. The following list identifies MFC classes and functions you should be aware of: -- `CString` MFC calls the C run-time library to allocate memory for a [CString](../atl-mfc-shared/reference/cstringt-class.md) dynamically. Generally speaking, `CString` is as efficient as any other dynamically-allocated string. As with any dynamically allocated string, it has the overhead of dynamic allocation and release. Often, a simple **`char`** array on the stack can serve the same purpose and is faster. Don't use a `CString` to store a constant string. Use `const char *` instead. Any operation you perform with a `CString` object has some overhead. Using the run-time library [string functions](../c-runtime-library/string-manipulation-crt.md) may be faster. +- `CString` MFC calls the C run-time library to allocate memory for a [`CString`](../atl-mfc-shared/reference/cstringt-class.md) dynamically. Generally speaking, `CString` is as efficient as any other dynamically allocated string. As with any dynamically allocated string, it has the overhead of dynamic allocation and release. Often, a simple **`char`** array on the stack can serve the same purpose and is faster. Don't use a `CString` to store a constant string. Use `const char *` instead. Any operation you perform with a `CString` object has some overhead. Using the run-time library [string functions](../c-runtime-library/string-manipulation-crt.md) may be faster. -- `CArray` A [CArray](../mfc/reference/carray-class.md) provides flexibility that a regular array doesn't, but your program may not need that. If you know the specific limits for the array, you can use a global fixed array instead. If you use `CArray`, use `CArray::SetSize` to establish its size and specify the number of elements by which it grows when a reallocation is necessary. Otherwise, adding elements can cause your array to be frequently reallocated and copied, which is inefficient and can fragment memory. Also be aware that if you insert an item into an array, `CArray` moves subsequent items in memory and may need to grow the array. These actions can cause cache misses and page faults. If you look through the code that MFC uses, you may see that you can write something more specific to your scenario to improve performance. Since `CArray` is a template, for example, you might provide `CArray` specializations for specific types. +- `CArray` A [`CArray`](../mfc/reference/carray-class.md) provides flexibility that a regular array doesn't, but your program may not need that. If you know the specific limits for the array, you can use a global fixed array instead. If you use `CArray`, use `CArray::SetSize` to establish its size and specify the number of elements by which it grows when a reallocation is necessary. Otherwise, adding elements can cause your array to be frequently reallocated and copied, which is inefficient and can fragment memory. Also, if you insert an item into an array, `CArray` moves subsequent items in memory and may need to grow the array. These actions can cause cache misses and page faults. If you look through the code that MFC uses, you may see that you can write something more specific to your scenario to improve performance. Since `CArray` is a template, for example, you might provide `CArray` specializations for specific types. -- `CList` [CList](../mfc/reference/clist-class.md) is a doubly linked list, so element insertion is fast at the head, tail, and at a known position (`POSITION`) in the list. Looking up an element by value or index requires a sequential search, however, which can be slow if the list is long. If your code does not require a doubly linked list you may want to reconsider using `CList`. Using a singly linked list saves the overhead of updating an additional pointer for all operations as well as the memory for that pointer. The additional memory is not great, but it is another opportunity for cache misses or page faults. +- `CList` [`CList`](../mfc/reference/clist-class.md) is a doubly linked list, so element insertion is fast at the head, tail, and at a known position (`POSITION`) in the list. Looking up an element by value or index requires a sequential search, however, which can be slow if the list is long. If your code doesn't require a doubly linked list, you may want to reconsider using `CList`. Using a singly linked list saves the overhead of updating another pointer for all operations and the memory for that pointer. The extra memory isn't large, but it's another opportunity for cache misses or page faults. -- `IsKindOf` This function can generate many calls and access a lot of memory in different data areas, leading to bad locality of reference. It is useful for a debug build (in an ASSERT call, for example), but try to avoid using it in a release build. +- `IsKindOf` This function can generate many calls and may access memory in different data areas, leading to bad locality of reference. It's useful for a debug build (in an ASSERT call, for example), but try to avoid using it in a release build. -- `PreTranslateMessage` Use `PreTranslateMessage` when a particular tree of windows needs different keyboard accelerators or when you must insert message handling into the message pump. `PreTranslateMessage` alters MFC dispatch messages. If you override `PreTranslateMessage`, do so only at the level needed. For example, it is not necessary to override `CMainFrame::PreTranslateMessage` if you are interested only in messages going to children of a particular view. Override `PreTranslateMessage` for the view class instead. +- `PreTranslateMessage` Use `PreTranslateMessage` when a particular tree of windows needs different keyboard accelerators or when you must insert message handling into the message pump. `PreTranslateMessage` alters MFC dispatch messages. If you override `PreTranslateMessage`, do so only at the level needed. For example, it isn't necessary to override `CMainFrame::PreTranslateMessage` if you're interested only in messages going to children of a particular view. Override `PreTranslateMessage` for the view class instead. - Do not circumvent the normal dispatch path by using `PreTranslateMessage` to handle any message sent to any window. Use [window procedures](../mfc/registering-window-classes.md) and MFC message maps for that purpose. + Don't circumvent the normal dispatch path by using `PreTranslateMessage` to handle any message sent to any window. Use [window procedures](../mfc/registering-window-classes.md) and MFC message maps for that purpose. -- `OnIdle` Idle events can occur at times you do not expect, such as between `WM_KEYDOWN` and `WM_KEYUP` events. Timers may be a more efficient way to trigger your code. Do not force `OnIdle` to be called repeatedly by generating false messages or by always returning `TRUE` from an override of `OnIdle`, which would never allow your thread to sleep. Again, a timer or a separate thread might be more appropriate. +- `OnIdle` Idle events can occur at times you don't expect, such as between `WM_KEYDOWN` and `WM_KEYUP` events. Timers may be a more efficient way to trigger your code. Don't force `OnIdle` to be called repeatedly by generating false messages or by always returning `TRUE` from an override of `OnIdle`, which would never allow your thread to sleep. Again, a timer or a separate thread might be more appropriate. -## Shared Libraries +## Shared libraries -Code reuse is desirable. However, if you are going to use someone else's code, you should make sure you know exactly what it does in those cases where performance is critical to you. The best way to understand this is by stepping through the source code or by measuring with tools such as PView or Performance Monitor. +Code reuse is desirable. However, if you're going to use someone else's code, you should make sure you know exactly what it does in those cases where performance is critical to you. The best way to understand it is by stepping through the source code or by measuring with tools such as PView or Performance Monitor. ## Heaps Use multiple heaps with discretion. Additional heaps created with `HeapCreate` and `HeapAlloc` let you manage and then dispose of a related set of allocations. Don't commit too much memory. If you're using multiple heaps, pay special attention to the amount of memory that is initially committed. -Instead of multiple heaps, you can use helper functions to interface between your code and the default heap. Helper functions facilitate custom allocation strategies that can improve the performance of your application. For example, if you frequently perform small allocations, you may want to localize these allocations to one part of the default heap. You can allocate a large block of memory and then use a helper function to suballocate from that block. If you do this, you will not have additional heaps with unused memory because the allocation is coming out of the default heap. +Instead of multiple heaps, you can use helper functions to interface between your code and the default heap. Helper functions facilitate custom allocation strategies that can improve the performance of your application. For example, if you frequently perform small allocations, you may want to localize these allocations to one part of the default heap. You can allocate a large block of memory and then use a helper function to suballocate from that block. Then you won't have multiple heaps with unused memory, because the allocation is coming out of the default heap. In some cases, however, using the default heap can reduce locality of reference. Use Process Viewer, Spy++, or Performance Monitor to measure the effects of moving objects from heap to heap. -Measure your heaps so you can account for every allocation on the heap. Use the C run-time [debug heap routines](/visualstudio/debugger/crt-debug-heap-details) to checkpoint and dump your heap. You can read the output into a spreadsheet program like Microsoft Excel and use pivot tables to view the results. Note the total number, size, and distribution of allocations. Compare these with the size of working sets. Also look at the clustering of related-sized objects. +Measure your heaps so you can account for every allocation on the heap. Use the C run-time [debug heap routines](../c-runtime-library/crt-debug-heap-details.md) to checkpoint and dump your heap. You can read the output into a spreadsheet program like Microsoft Excel and use pivot tables to view the results. Note the total number, size, and distribution of allocations. Compare these results with the size of working sets. Also look at the clustering of related-sized objects. You can also use the performance counters to monitor memory usage. @@ -109,7 +109,7 @@ You can also use the performance counters to monitor memory usage. For background tasks, effective idle handling of events may be faster than using threads. It's easier to understand locality of reference in a single-threaded program. -A good rule of thumb is to use a thread only if an operating system notification that you block on is at the root of the background work. Threads are the best solution in such a case because it is impractical to block a main thread on an event. +A good rule of thumb is to use a thread only if an operating system notification that you block on is at the root of the background work. Threads are the best solution in such a case because it's impractical to block a main thread on an event. Threads also present communication problems. You must manage the communication link between your threads, with a list of messages or by allocating and using shared memory. Managing the communication link usually requires synchronization to avoid race conditions and deadlock problems. This complexity can easily turn into bugs and performance problems. @@ -119,9 +119,9 @@ For more information, see [Idle Loop Processing](../mfc/idle-loop-processing.md) Smaller working sets mean better locality of reference, fewer page faults, and more cache hits. The process working set is the closest metric the operating system directly provides for measuring locality of reference. -- To set the upper and lower limits of the working set, use [SetProcessWorkingSetSize](/windows/win32/api/winbase/nf-winbase-getprocessworkingsetsize). +- To set the upper and lower limits of the working set, use [`SetProcessWorkingSetSize`](/windows/win32/api/memoryapi/nf-memoryapi-setprocessworkingsetsize). -- To get the upper and lower limits of the working set, use [GetProcessWorkingSetSize](/windows/win32/api/winbase/nf-winbase-setprocessworkingsetsize). +- To get the upper and lower limits of the working set, use [`GetProcessWorkingSetSize`](/windows/win32/api/memoryapi/nf-memoryapi-getprocessworkingsetsize). - To view the size of the working set, use Spy++. diff --git a/docs/build/toc.yml b/docs/build/toc.yml index c3f7775539..444ec54501 100644 --- a/docs/build/toc.yml +++ b/docs/build/toc.yml @@ -1,3 +1,4 @@ +items: - name: Projects and build systems href: ../build/projects-and-build-systems-cpp.md - name: Visual Studio projects - C++ @@ -8,7 +9,7 @@ - name: Set C++ compiler and build properties in Visual Studio expanded: false items: - - name: Set C++ compiler and build properties in Visual Studio + - name: Set C++ compiler and build properties href: ../build/working-with-project-properties.md - name: Share or reuse Visual Studio project settings href: ../build/create-reusable-property-configurations.md @@ -55,6 +56,8 @@ href: ../build/cmake-projects-in-visual-studio.md - name: "Tutorial: Create C++ cross-platform projects in Visual Studio" href: ../build/get-started-linux-cmake.md + - name: "Walkthrough: Build and Debug C++ with WSL 2 in Visual Studio" + href: ../build/walkthrough-build-debug-wsl2.md - name: "Tutorial: Run and debug a CMake project remotely" href: ../build/cmake-remote-debugging.md - name: Clang/LLVM in CMake projects @@ -75,13 +78,17 @@ href: ../build/cmake-predefined-configuration-reference.md - name: "C++ Build Insights" href: ../build-insights/get-started-with-cpp-build-insights.md -- name: "Build and import header units" +- name: "Compare header units, modules, and precompiled headers" + href: ../build/compare-inclusion-methods.md +- name: "Header units" expanded: false items: - name: "Walkthrough: Build and import header units in Visual C++ projects" href: ../build/walkthrough-header-units.md - name: "Walkthrough: Import STL libraries as header units" href: ../build/walkthrough-import-stl-header-units.md + - name: C++ header unit.json reference + href: ../build/reference/header-unit-json-reference.md - name: Precompiled header files href: ../build/creating-precompiled-header-files.md - name: C++ release builds @@ -153,8 +160,6 @@ href: ../build/walkthrough-compiling-a-cpp-cli-program-on-the-command-line.md - name: "Walkthrough: Compiling a C++/CX program on the command line" href: ../build/walkthrough-compiling-a-cpp-cx-program-on-the-command-line.md - - name: Set the path and environment variables for command-line builds - href: ../build/setting-the-path-and-environment-variables-for-command-line-builds.md - name: Use MSBuild from the command line expanded: false items: @@ -195,7 +200,7 @@ - name: "MFC extension DLLs: Overview" href: ../build/extension-dlls-overview.md - name: MFC DLL frequently asked questions - href: ../build/dll-frequently-asked-questions.md + href: ../build/dll-frequently-asked-questions.yml - name: Link an executable to a DLL href: ../build/linking-an-executable-to-a-dll.md - name: DLLs and MSVC run-time library behavior @@ -282,16 +287,7 @@ - name: "How to: Build isolated applications to consume COM components" href: ../build/how-to-build-isolated-applications-to-consume-com-components.md - name: Understanding manifest generation for C/C++ programs - expanded: false - items: - - name: Understanding manifest generation for C/C++ programs - href: ../build/understanding-manifest-generation-for-c-cpp-programs.md - - name: Manifest generation in Visual Studio - href: ../build/manifest-generation-in-visual-studio.md - - name: Manifest generation at the command line - href: ../build/manifest-generation-at-the-command-line.md - - name: "How to: Embed a manifest inside a C/C++ application" - href: ../build/how-to-embed-a-manifest-inside-a-c-cpp-application.md + href: ../build/understanding-manifest-generation-for-c-cpp-programs.md - name: Troubleshooting C/C++ isolated applications and side-by-side assemblies href: ../build/troubleshooting-c-cpp-isolated-applications-and-side-by-side-assemblies.md - name: Configure MSVC for 64-bit, x64 targets @@ -305,10 +301,10 @@ href: ../build/how-to-enable-a-64-bit-visual-cpp-toolset-on-the-command-line.md - name: Common MSVC 64-bit migration issues href: ../build/common-visual-cpp-64-bit-migration-issues.md - - name: x64 software conventions + - name: x64 ABI conventions expanded: false items: - - name: x64 software conventions + - name: Overview of x64 ABI conventions href: ../build/x64-software-conventions.md - name: x64 calling convention href: ../build/x64-calling-convention.md @@ -329,6 +325,8 @@ href: ../build/overview-of-arm-abi-conventions.md - name: Overview of ARM64 ABI conventions href: ../build/arm64-windows-abi-conventions.md + - name: Overview of ARM64EC ABI conventions + href: ../build/arm64ec-windows-abi-conventions.md - name: ARM exception handling href: ../build/arm-exception-handling.md - name: ARM64 exception handling @@ -376,7 +374,7 @@ href: ../build/reference/help-files-html-help.md - name: Winhelp help files href: ../build/reference/help-files-winhelp.md - - name: Hint files for Intellisense + - name: Hint files for IntelliSense href: ../build/reference/hint-files.md - name: Property page XML files href: ../build/reference/property-page-xml-files.md @@ -480,6 +478,8 @@ href: ../build/reference/arch-x64.md - name: /arch (ARM) href: ../build/reference/arch-arm.md + - name: /arch (ARM64) + href: ../build/reference/arch-arm64.md - name: /await (Enable coroutine support) href: ../build/reference/await-enable-coroutine-support.md - name: /bigobj (Increase number of sections in .Obj file) @@ -515,6 +515,8 @@ href: ../build/reference/errorreport-report-internal-compiler-errors.md - name: /execution-charset (Set execution character set) href: ../build/reference/execution-charset-set-execution-character-set.md + - name: /experimental:log + href: ../build/reference/experimental-log.md - name: /experimental:module href: ../build/reference/experimental-module.md - name: /experimental:preprocessor @@ -558,12 +560,21 @@ href: ../build/reference/favor-optimize-for-architecture-specifics.md - name: /FC (Full path of source code file in diagnostics) href: ../build/reference/fc-full-path-of-source-code-file-in-diagnostics.md + - name: /feature (Enable architecture features) + href: ../build/reference/feature-arm64.md + - name: /forceInterlockedFunctions (Generate and link with out-of-line atomic + functions) + href: ./reference/force-interlocked-functions.md - name: /fp (Specify floating-point behavior) href: ../build/reference/fp-specify-floating-point-behavior.md + - name: /fpcvt (Floating-point to unsigned integer conversion behavior) + href: ../build/reference/fpcvt.md - name: /FS (Force synchronous PDB writes) href: ../build/reference/fs-force-synchronous-pdb-writes.md - name: /fsanitize (Enable sanitizers) href: ../build/reference/fsanitize.md + - name: /fsanitize-coverage (Configure sanitizer coverage) + href: ../build/reference/fsanitize-coverage.md - name: /GA (Optimize for Windows application) href: ../build/reference/ga-optimize-for-windows-application.md - name: /Gd, /Gr, /Gv, /Gz (Calling convention) @@ -614,10 +625,20 @@ href: ../build/reference/hotpatch-create-hotpatchable-image.md - name: /I (Additional include directories) href: ../build/reference/i-additional-include-directories.md + - name: /ifcOutput (Specify where the compiled `.ifc` should go.) + href: ../build/reference/ifc-output.md + - name: /ifcMap (Map named modules and header units to IFC files.) + href: ../build/reference/ifc-map.md + - name: /interface (Treat input file as a module interface unit) + href: ../build/reference/interface.md + - name: /internalPartition (Treat the input file as an internal partition unit) + href: ../build/reference/internal-partition.md - name: /J (Default char type is unsigned) href: ../build/reference/j-default-char-type-is-unsigned.md - name: /JMC (Just My Code debugging) href: ../build/reference/jmc.md + - name: /jumptablerdata (put switch case jump tables in .rdata) + href: ../build/reference/jump-table-rdata.md - name: /kernel (Create kernel mode binary) href: ../build/reference/kernel-create-kernel-mode-binary.md - name: /link (Pass options to linker) @@ -657,6 +678,8 @@ href: ../build/reference/oy-frame-pointer-omission.md - name: /openmp (Enable OpenMP 2.0 support) href: ../build/reference/openmp-enable-openmp-2-0-support.md + - name: /options:strict (Unrecognized compiler options are errors) + href: ../build/reference/options-strict.md - name: /P (Preprocess to a file) href: ../build/reference/p-preprocess-to-a-file.md - name: /permissive- (Standards conformance) @@ -682,6 +705,8 @@ href: ../build/reference/qsafe-fp-loads.md - name: /Qspectre href: ../build/reference/qspectre.md + - name: /Qspectre-jmp + href: ../build/reference/qspectre-jmp.md - name: /Qspectre-load href: ../build/reference/qspectre-load.md - name: /Qspectre-load-cf @@ -690,7 +715,9 @@ href: ../build/reference/qvec-report-auto-vectorizer-reporting-level.md - name: /RTC (Run-time error checks) href: ../build/reference/rtc-run-time-error-checks.md - - name: /sdl (Enable additional security checks) + - name: /scanDependencies (List module dependencies in standard form) + href: ../build/reference/scandependencies.md + - name: /sdl (Enable more security checks) href: ../build/reference/sdl-enable-additional-security-checks.md - name: /showIncludes (List include files) href: ../build/reference/showincludes-list-include-files.md @@ -708,7 +735,7 @@ href: ../build/reference/translateinclude.md - name: /U, /u (Undefine symbols) href: ../build/reference/u-u-undefine-symbols.md - - name: /utf-8 (Set source and executable character sets to UTF-8) + - name: /utf-8 (Set source and execution character sets to UTF-8) href: ../build/reference/utf-8-set-source-and-executable-character-sets-to-utf-8.md - name: /V (Version number) href: ../build/reference/v-version-number.md @@ -716,12 +743,16 @@ href: ../build/reference/validate-charset-validate-for-compatible-characters.md - name: /vd (Disable construction displacements) href: ../build/reference/vd-disable-construction-displacements.md + - name: /vlen (Specify vector length) + href: ../build/reference/vlen.md - name: /vmb, /vmg (Representation method) href: ../build/reference/vmb-vmg-representation-method.md - name: /vmm, /vms, /vmv (General purpose representation) href: ../build/reference/vmm-vms-vmv-general-purpose-representation.md - name: /volatile (volatile keyword interpretation) href: ../build/reference/volatile-volatile-keyword-interpretation.md + - name: /volatileMetadata + href: ../build/reference/volatile.md - name: /w, /W0, /W1, /W2, /W3, /W4, /w1, /w2, /w3, /w4, /Wall, /wd, /we, /wo, /Wv, /WX (Warning level) href: ../build/reference/compiler-option-warning-level.md - name: /WL (Enable one-line diagnostics) @@ -757,26 +788,42 @@ - name: /Zc (Conformance) expanded: false items: - - name: /Zc (Conformance) + - name: "/Zc (Conformance)" href: ../build/reference/zc-conformance.md + - name: "/Zc:__cplusplus (Enable updated __cplusplus macro)" + href: ../build/reference/zc-cplusplus.md + - name: "/Zc:__STDC__ (Enable __STDC__ macro)" + href: ../build/reference/zc-stdc.md - name: "/Zc:alignedNew (C++17 over-aligned allocation)" href: ../build/reference/zc-alignednew.md - name: "/Zc:auto (Deduce variable type)" href: ../build/reference/zc-auto-deduce-variable-type.md - - name: "/Zc:__cplusplus (Enable updated __cplusplus macro)" - href: ../build/reference/zc-cplusplus.md + - name: "/Zc:char8_t (Enable C++20 char8_t type)" + href: ../build/reference/zc-char8-t.md + - name: "/Zc:checkGwOdr (Enforce Standard C++ ODR violations under /Gw)" + href: ../build/reference/zc-check-gwodr.md + - name: "/Zc:enumTypes (Enable enum type deduction)" + href: ../build/reference/zc-enumtypes.md + - name: '/Zc:externC (Use Standard C++ extern "C" rules)' + href: ../build/reference/zc-externc.md - name: "/Zc:externConstexpr (Enable extern constexpr variables)" 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)" href: ../build/reference/zc-implicitnoexcept-implicit-exception-specifiers.md - name: "/Zc:inline (Remove unreferenced COMDAT)" href: ../build/reference/zc-inline-remove-unreferenced-comdat.md + - name: "/Zc:lambda (Enable updated lambda processor)" + 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)" @@ -785,20 +832,28 @@ href: ../build/reference/zc-rvaluecast-enforce-type-conversion-rules.md - name: "/Zc:sizedDealloc (Enable global sized deallocation functions)" href: ../build/reference/zc-sizeddealloc-enable-global-sized-dealloc-functions.md + - name: "/Zc:static_assert (Strict static_assert handling)" + 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)" + - name: "/Zc:threadSafeInit (Thread-safe local static initialization)" href: ../build/reference/zc-threadsafeinit-thread-safe-local-static-initialization.md - name: "/Zc:throwingNew (Assume operator new throws)" href: ../build/reference/zc-throwingnew-assume-operator-new-throws.md + - name: "/Zc:tlsGuards (Check TLS initialization)" + href: ../build/reference/zc-tlsguards.md - name: "/Zc:trigraphs (Trigraphs substitution)" href: ../build/reference/zc-trigraphs-trigraphs-substitution.md - name: "/Zc:twoPhase- (disable two-phase name lookup)" href: ../build/reference/zc-twophase.md - name: "/Zc:wchar_t (wchar_t is native type)" href: ../build/reference/zc-wchar-t-wchar-t-is-native-type.md + - name: "/Zc:zeroSizeArrayNew (Call member new/delete on arrays)" + href: ../build/reference/zc-zerosizearraynew.md - name: /Zf (Faster PDB generation) href: ../build/reference/zf.md - name: /Zg (Generate function prototypes) @@ -817,6 +872,8 @@ href: ../build/reference/zs-syntax-check-only.md - name: /ZW (Windows Runtime compilation) href: ../build/reference/zw-windows-runtime-compilation.md + - name: Structured SARIF output + href: ../build/reference/sarif-output.md - name: Unicode support in the compiler and linker href: ../build/reference/unicode-support-in-the-compiler-and-linker.md - name: MSVC linker reference @@ -875,6 +932,8 @@ href: ../build/reference/allowisolation-manifest-lookup.md - name: /APPCONTAINER (UWP/Microsoft Store app) href: ../build/reference/appcontainer-windows-store-app.md + - name: /ARM64XFUNCTIONPADMINX64 (Minimum x64 function padding) + href: ../build/reference/arm64-function-pad-min-x64.md - name: /ASSEMBLYDEBUG (Add DebuggableAttribute) href: ../build/reference/assemblydebug-add-debuggableattribute.md - name: /ASSEMBLYLINKRESOURCE (Link to .NET Framework resource) @@ -947,16 +1006,20 @@ href: ../build/reference/ignore-ignore-specific-warnings.md - name: /IGNOREIDL (Don't process attributes into MIDL) href: ../build/reference/ignoreidl-don-t-process-attributes-into-midl.md - - name: /INFERASANLIBS (Use inferred sanitizer libs) - href: ../build/reference/inferasanlibs.md + - name: /ILK (Name incremental database file) + href: ../build/reference/ilk-name-incremental-database-file.md - name: /IMPLIB (Name import library) href: ../build/reference/implib-name-import-library.md - name: /INCLUDE (Force symbol references) href: ../build/reference/include-force-symbol-references.md - name: /INCREMENTAL (Link incrementally) href: ../build/reference/incremental-link-incrementally.md + - name: /INFERASANLIBS (Use inferred sanitizer libs) + href: ../build/reference/inferasanlibs.md - name: /INTEGRITYCHECK (Require signature check) href: ../build/reference/integritycheck-require-signature-check.md + - name: /KERNEL (Create a kernel mode binary) + href: ../build/reference/link-code-for-kernel-mode.md - name: /KEYCONTAINER (Specify a key container to sign an assembly) href: ../build/reference/keycontainer-specify-a-key-container-to-sign-an-assembly.md - name: /KEYFILE (Specify key or key pair to sign an assembly) @@ -967,10 +1030,14 @@ href: ../build/reference/libpath-additional-libpath.md - name: /LINKREPRO (Link repro directory name) href: ../build/reference/linkrepro.md + - name: /LINKREPROFULLPATHRSP (Generate file containing absolute paths of linked files) + href: ../build/reference/link-repro-full-path-rsp.md - name: /LINKREPROTARGET (Link repro file name) href: ../build/reference/linkreprotarget.md - name: /LTCG (Link-time code generation) href: ../build/reference/ltcg-link-time-code-generation.md + - name: /LTCGOUT (Name LTCG .iobj file) + href: ../build/reference/ltcgout.md - name: /MACHINE (Specify target platform) href: ../build/reference/machine-specify-target-platform.md - name: /MANIFEST (Create side-by-side assembly manifest) @@ -999,6 +1066,8 @@ href: ../build/reference/nodefaultlib-ignore-libraries.md - name: /NOENTRY (No entry point) href: ../build/reference/noentry-no-entry-point.md + - name: /NOFUNCTIONPADSECTION (Disable function padding) + href: ../build/reference/no-function-pad-section.md - name: /NOLOGO (Suppress startup banner) (Linker) href: ../build/reference/nologo-suppress-startup-banner-linker.md - name: /NXCOMPAT (Compatible with Data Execution Prevention) @@ -1100,10 +1169,10 @@ href: ../build/reference/error-handling-and-notification.md - name: Understand the delay load helper function href: ../build/reference/understanding-the-helper-function.md - - name: Additional MSVC build tools + - name: Other MSVC build tools expanded: false items: - - name: Additional MSVC build tools + - name: Other MSVC build tools href: ../build/reference/c-cpp-build-tools.md - name: NMAKE reference expanded: false @@ -1114,21 +1183,10 @@ href: ../build/reference/creating-a-makefile-project.md - name: Running NMAKE href: ../build/reference/running-nmake.md - - name: Contents of a makefile - expanded: false - items: - - name: Contents of a makefile - href: ../build/reference/contents-of-a-makefile.md - - name: Wildcards and NMAKE - href: ../build/reference/wildcards-and-nmake.md - - name: Long filenames in a makefile - href: ../build/reference/long-filenames-in-a-makefile.md - - name: Comments in a makefile - href: ../build/reference/comments-in-a-makefile.md - - name: Special characters in a makefile - href: ../build/reference/special-characters-in-a-makefile.md - - name: Sample makefile - href: ../build/reference/sample-makefile.md + - name: Makefile contents and features + href: ../build/reference/contents-of-a-makefile.md + - name: Sample makefile + href: ../build/reference/sample-makefile.md - name: Description blocks href: ../build/reference/description-blocks.md - name: Commands in a makefile @@ -1136,99 +1194,48 @@ items: - name: Commands in a makefile href: ../build/reference/commands-in-a-makefile.md - - name: Command modifiers - href: ../build/reference/command-modifiers.md - - name: Filename-parts syntax - href: ../build/reference/filename-parts-syntax.md - name: Inline files in a makefile - expanded: false - items: - - name: Inline files in a makefile - href: ../build/reference/inline-files-in-a-makefile.md - - name: Specifying an inline file - href: ../build/reference/specifying-an-inline-file.md - - name: Creating inline file text - href: ../build/reference/creating-inline-file-text.md - - name: Reusing inline files - href: ../build/reference/reusing-inline-files.md - - name: Multiple inline files - href: ../build/reference/multiple-inline-files.md + href: ../build/reference/inline-files-in-a-makefile.md - name: Macros and NMAKE expanded: false items: - name: Macros and NMAKE href: ../build/reference/macros-and-nmake.md - - name: Defining an NMAKE macro - expanded: false - items: - - name: Defining an NMAKE macro - href: ../build/reference/defining-an-nmake-macro.md - - name: Special characters in macros - href: ../build/reference/special-characters-in-macros.md - - name: Null and undefined macros - href: ../build/reference/null-and-undefined-macros.md - - name: Where to define macros - href: ../build/reference/where-to-define-macros.md - - name: Precedence in macro definitions - href: ../build/reference/precedence-in-macro-definitions.md - - name: Using an NMAKE macro + - name: Define an NMAKE macro + href: ../build/reference/defining-an-nmake-macro.md + - name: Use an NMAKE macro expanded: false items: - - name: Using an NMAKE macro + - name: Use an NMAKE macro href: ../build/reference/using-an-nmake-macro.md - - name: Macro substitution - href: ../build/reference/macro-substitution.md + - name: abspath + href: ../build/reference/nmake-function-abspath.md + - name: basename + href: ../build/reference/nmake-function-basename.md + - name: filter, filteri + href: ../build/reference/nmake-function-filter.md + - name: filterout, filterouti + href: ../build/reference/nmake-function-filterout.md + - name: findstring, findstringi + href: ../build/reference/nmake-function-findstring.md + - name: lowercase + href: ../build/reference/nmake-function-lowercase.md + - name: patsubst, patsubsti + href: ../build/reference/nmake-function-patsubst.md + - name: strip + href: ../build/reference/nmake-function-strip.md + - name: subst, substi + href: ../build/reference/nmake-function-subst.md + - name: uppercase + href: ../build/reference/nmake-function-uppercase.md - name: Special NMAKE macros - expanded: false - items: - - name: Special NMAKE macros - href: ../build/reference/special-nmake-macros.md - - name: Filename macros - href: ../build/reference/filename-macros.md - - name: Recursion macros - href: ../build/reference/recursion-macros.md - - name: Command macros and options macros - href: ../build/reference/command-macros-and-options-macros.md - - name: Environment-variable macros - href: ../build/reference/environment-variable-macros.md + href: ../build/reference/special-nmake-macros.md - name: Inference rules - expanded: false - items: - - name: Inference rules - href: ../build/reference/inference-rules.md - - name: Defining a rule - expanded: false - items: - - name: Defining a rule - href: ../build/reference/defining-a-rule.md - - name: Search paths in rules - href: ../build/reference/search-paths-in-rules.md - - name: Batch-mode rules - href: ../build/reference/batch-mode-rules.md - - name: Predefined rules - href: ../build/reference/predefined-rules.md - - name: Inferred dependents and rules - href: ../build/reference/inferred-dependents-and-rules.md - - name: Precedence in inference rules - href: ../build/reference/precedence-in-inference-rules.md + href: ../build/reference/inference-rules.md - name: Dot directives href: ../build/reference/dot-directives.md - name: Makefile preprocessing - expanded: false - items: - - name: Makefile preprocessing - href: ../build/reference/makefile-preprocessing.md - - name: Makefile preprocessing directives - href: ../build/reference/makefile-preprocessing-directives.md - - name: Expressions in makefile preprocessing - expanded: false - items: - - name: Expressions in makefile preprocessing - href: ../build/reference/expressions-in-makefile-preprocessing.md - - name: Makefile preprocessing operators - href: ../build/reference/makefile-preprocessing-operators.md - - name: Executing a program in preprocessing - href: ../build/reference/executing-a-program-in-preprocessing.md + href: ../build/reference/makefile-preprocessing.md - name: LIB reference expanded: false items: diff --git a/docs/build/understanding-manifest-generation-for-c-cpp-programs.md b/docs/build/understanding-manifest-generation-for-c-cpp-programs.md index 412ec26186..2735311ee3 100644 --- a/docs/build/understanding-manifest-generation-for-c-cpp-programs.md +++ b/docs/build/understanding-manifest-generation-for-c-cpp-programs.md @@ -1,19 +1,291 @@ --- -description: "Learn more about: Understanding Manifest Generation for C/C++ Programs" -title: "Understanding Manifest Generation for C/C++ Programs" -ms.date: "11/04/2016" +title: "Understanding manifest generation for C/C++ programs" +description: "Learn more about: Understanding manifest generation for C/C++ programs" +ms.date: 06/10/2022 helpviewer_keywords: ["manifests [C++]"] -ms.assetid: a1f24221-5b09-4824-be48-92eae5644b53 --- -# Understanding Manifest Generation for C/C++ Programs +# Understanding manifest generation for C/C++ programs -A [manifest](/windows/win32/sbscs/manifests) is an XML document that can be an external XML file or a resource embedded inside an application or an assembly. The manifest of an [isolated application](/windows/win32/SbsCs/isolated-applications) is used to manage the names and versions of shared side-by-side assemblies to which the application should bind at run time. The manifest of a side-by-side assembly specifies its dependencies on names, versions, resources, and other assemblies. +A [manifest](/windows/win32/sbscs/manifests) is an XML document that uniquely identifies an assembly. It contains information used for binding and activation, such as COM classes, interfaces, and type libraries. A manifest can be an external XML file or a resource embedded inside an application or an assembly. The manifest of an [isolated application](/windows/win32/SbsCs/isolated-applications) is used to manage the names and versions of shared side-by-side assemblies the application should bind to at run time. The manifest of a side-by-side assembly specifies its dependencies on names, versions, resources, and other assemblies. -There are two ways to create a manifest for an isolated application or a side-by-side assembly. First, the author of the assembly can manually create a manifest file following rules and naming requirements. Alternatively, if a program only depends on Visual C++ assemblies such as CRT, MFC, ATL or others, then a manifest can be generated automatically by the linker. +There are two ways to create a manifest for an isolated application or a side-by-side assembly. First, the author of the assembly can manually create a manifest file by following the rules and naming requirements. For more information, see [Manifest files reference](/windows/win32/sbscs/manifest-files-reference). Alternatively, if a program only depends on MSVC assemblies such as CRT, MFC, ATL or others, then the linker can generate a manifest automatically. -The headers of Visual C++ libraries contain assembly information, and when the libraries are included in application code, this assembly information is used by the linker to form a manifest for the final binary. The linker does not embed the manifest file inside the binary, and can only generate the manifest as an external file. Having a manifest as an external file may not work for all scenarios. For example, it is recommended that private assemblies have embedded manifests. In command line builds such as those that use nmake to build code, a manifest can be embedded using the manifest tool; for more information see [Manifest Generation at the Command Line](manifest-generation-at-the-command-line.md). When building in Visual Studio, a manifest can be embedded by setting a property for the manifest tool in the **Project Properties** dialog; see [Manifest Generation in Visual Studio](manifest-generation-in-visual-studio.md). +The headers of MSVC libraries contain assembly information, and when the libraries are included in application code, this assembly information is used by the linker to form a manifest for the final binary. By default, the linker doesn't embed the manifest file inside the binary. Having a manifest as an external file may not work for all scenarios. For example, it's recommended that private assemblies have embedded manifests. In command line builds such as ones that use NMAKE to build code, you can use the [`/MANIFEST:EMBED`](./reference/manifest-create-side-by-side-assembly-manifest.md) linker option to embed the manifest. Alternatively, a manifest can be embedded using the manifest tool. For more information, see [Manifest generation at the command line](#manifest-generation-at-the-command-line). When you build in Visual Studio, a manifest can be embedded by setting a property for the manifest tool in the **Project Properties** dialog, as described in the next section. + +## Manifest generation in Visual Studio + +You can tell Visual Studio to generate a manifest file for a particular project in the project's **Property Pages** dialog. Under **Configuration Properties**, select **Linker** > **Manifest File** > **Generate Manifest**. By default, the project properties of new projects are set to generate a manifest file. However it's possible to disable generation of the manifest for a project by using the **Generate Manifest** property of the project. When this property is set to **Yes**, the manifest for the project is generated. Otherwise the linker ignores assembly information when resolving dependencies of the application code, and doesn't generate the manifest. + +The build system in Visual Studio allows the manifest to be embedded in the final binary application file, or generated as an external file. This behavior is controlled by the **Embed Manifest** option in the **Project Properties** dialog. To set this property, open the **Manifest Tool** node, then select **Input and Output**. If the manifest isn't embedded, it's generated as an external file and saved in the same directory as the final binary. If the manifest is embedded, Visual Studio embeds the final manifests using the following process: + +1. After the source code is compiled to object files, the linker collects dependent assembly information. While it links the final binary, the linker generates an intermediate manifest that's used later to generate the final manifest. + +1. After the intermediate manifest and linking are finished, the manifest tool merges a final manifest and saves it as an external file. + +1. The project build system then detects whether the manifest generated by the manifest tool contains different information than the manifest already embedded in the binary. + +1. If the manifest embedded in the binary is different from the manifest generated by the manifest tool, or the binary doesn't contain an embedded manifest, Visual Studio invokes the linker one more time to embed the external manifest file inside the binary as a resource. + +1. If the manifest embedded in the binary is the same as the manifest generated by the manifest tool, the build continues to the next build steps. + +The manifest is embedded inside the final binary as a text resource. You can view it by opening the final binary as a file in Visual Studio. To ensure that the manifest points to the correct libraries, follow the steps described in [Understanding the dependencies of a Visual C++ application](../windows/understanding-the-dependencies-of-a-visual-cpp-application.md). Or, follow the suggestions described in the [Troubleshooting](troubleshooting-c-cpp-isolated-applications-and-side-by-side-assemblies.md) article. + +## Manifest generation at the command line + +When you build C/C++ applications from the command line using NMAKE or similar tools, the manifest is generated after the linker has processed all object files and built the final binary. The linker collects assembly information stored in the object files and combines this information into a final manifest file. By default, the linker generates a file named *`..manifest`* to describe the final binary. The linker can embed a manifest file inside the binary by specifying the [`/MANIFEST:EMBED`](./reference/manifest-create-side-by-side-assembly-manifest.md) linker option. + +There are several other ways to embed a manifest inside the final binary, such as using the [Manifest tool (`mt.exe`)](/windows/win32/sbscs/mt-exe) or compiling the manifest into a resource file. You must follow specific rules when you embed a manifest to enable features such as incremental linking, signing, and Edit and Continue. These rules and other options are discussed in the next section. + +## How to embed a manifest inside a C/C++ application + +We recommended that you embed the manifest of your application or library inside the final binary. This approach guarantees correct runtime behavior in most scenarios. By default, Visual Studio tries to embed the manifest when it builds a project. However, if you build your application by using NMAKE, you have to make some changes to the makefile. This section shows how to change the makefiles so that it automatically embeds the manifest inside the final binary. + +### Two approaches + +There are two ways to embed the manifest inside an application or library. + +1. If you aren't doing an incremental build, you can directly embed the manifest using a command line similar to the following as a post-build step: + + ```cmd + mt.exe -manifest MyApp.exe.manifest -outputresource:MyApp.exe;1 + ``` + + or + + ```cmd + mt.exe -manifest MyLibrary.dll.manifest -outputresource:MyLibrary.dll;2 + ``` + + Use 1 for an EXE and 2 for a DLL. + +1. If you're doing an incremental build, use the following steps: + + - Link the binary to generate the *`MyApp.exe.manifest`* file. + + - Convert the manifest to a resource file. + + - Relink (incrementally) to embed the manifest resource into the binary. + +The following examples show how to change makefiles to incorporate both techniques. + +### Makefiles (Before) + +Consider the NMAKE script for *`MyApp.exe`*, a simple application built from one file: + +```makefile +# build MyApp.exe +!if "$(DEBUG)" == "1" +CPPFLAGS=$(CPPFLAGS) /MDd +LFLAGS=$(LFLAGS) /INCREMENTAL +!else +CPPFLAGS=$(CPPFLAGS) /MD +!endif + +MyApp.exe : MyApp.obj + link $** /out:$@ $(LFLAGS) + +MyApp.obj : MyApp.cpp + +clean : + del MyApp.obj MyApp.exe +``` + +If this script is run unchanged with Visual Studio, it successfully creates *`MyApp.exe`*. It also creates the external manifest file *`MyApp.exe.manifest`*, for use by the operating system to load dependent assemblies at runtime. + +The NMAKE script for *`MyLibrary.dll`* looks similar: + +```makefile +# build MyLibrary.dll +!if "$(DEBUG)" == "1" +CPPFLAGS=$(CPPFLAGS) /MDd +LFLAGS=$(LFLAGS) /DLL /INCREMENTAL + +!else +CPPFLAGS=$(CPPFLAGS) /MD +LFLAGS=$(LFLAGS) /DLL + +!endif + +MyLibrary.dll : MyLibrary.obj + link $** /out:$@ $(LFLAGS) + +MyLibrary.obj : MyLibrary.cpp + +clean : + del MyLibrary.obj MyLibrary.dll +``` + +### Makefiles (After) + +To build with embedded manifests, you have to make four small changes to the original makefiles. For the *`MyApp.exe`* makefile: + +```makefile +# build MyApp.exe +!include makefile.inc +#^^^^^^^^^^^^^^^^^^^^ Change #1. (Add full path if necessary.) + +!if "$(DEBUG)" == "1" +CPPFLAGS=$(CPPFLAGS) /MDd +LFLAGS=$(LFLAGS) /INCREMENTAL +!else +CPPFLAGS=$(CPPFLAGS) /MD +!endif + +MyApp.exe : MyApp.obj + link $** /out:$@ $(LFLAGS) + $(_VC_MANIFEST_EMBED_EXE) +#^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Change #2 + +MyApp.obj : MyApp.cpp + +clean : + del MyApp.obj MyApp.exe + $(_VC_MANIFEST_CLEAN) +#^^^^^^^^^^^^^^^^^^^^^^^^ Change #3 + +!include makefile.target.inc +#^^^^^^^^^^^^^^^^^^^^^^^^^ Change #4. (Add full path if necessary.) +``` + +For the MyLibrary.dll makefile: + +```makefile +# build MyLibrary.dll +!include makefile.inc +#^^^^^^^^^^^^^^^^^^^^ Change #1. (Add full path if necessary.) + +!if "$(DEBUG)" == "1" +CPPFLAGS=$(CPPFLAGS) /MDd +LFLAGS=$(LFLAGS) /DLL /INCREMENTAL + +!else +CPPFLAGS=$(CPPFLAGS) /MD +LFLAGS=$(LFLAGS) /DLL + +!endif + +MyLibrary.dll : MyLibrary.obj + link $** /out:$@ $(LFLAGS) + $(_VC_MANIFEST_EMBED_DLL) +#^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Change #2. + +MyLibrary.obj : MyLibrary.cpp + +clean : + del MyLibrary.obj MyLibrary.dll + $(_VC_MANIFEST_CLEAN) +#^^^^^^^^^^^^^^^^^^^^^^^^ Change #3. + +!include makefile.target.inc +#^^^^^^^^^^^^^^^^^^^^^^^^^ Change #4. (Add full path if necessary.) +``` + +The makefiles now include two files that do the real work, *`makefile.inc`* and *`makefile.target.inc`*. + +Create *`makefile.inc`* and copy the following content into it: + +```makefile +# makefile.inc -- Include this file into existing makefile at the very top. + +# _VC_MANIFEST_INC specifies whether build is incremental (1 - incremental). +# _VC_MANIFEST_BASENAME specifies name of a temporary resource file. + +!if "$(DEBUG)" == "1" +CPPFLAGS=$(CPPFLAGS) /MDd +LFLAGS=$(LFLAGS) /INCREMENTAL +_VC_MANIFEST_INC=1 +_VC_MANIFEST_BASENAME=__VC90.Debug + +!else +CPPFLAGS=$(CPPFLAGS) /MD +_VC_MANIFEST_INC=0 +_VC_MANIFEST_BASENAME=__VC90 + +!endif + +#################################################### +# Specifying name of temporary resource file used only in incremental builds: + +!if "$(_VC_MANIFEST_INC)" == "1" +_VC_MANIFEST_AUTO_RES=$(_VC_MANIFEST_BASENAME).auto.res +!else +_VC_MANIFEST_AUTO_RES= +!endif + +#################################################### +# _VC_MANIFEST_EMBED_EXE - command to embed manifest in EXE: + +!if "$(_VC_MANIFEST_INC)" == "1" + +#MT_SPECIAL_RETURN=1090650113 +#MT_SPECIAL_SWITCH=-notify_resource_update +MT_SPECIAL_RETURN=0 +MT_SPECIAL_SWITCH= +_VC_MANIFEST_EMBED_EXE= \ +if exist $@.manifest mt.exe -manifest $@.manifest -out:$(_VC_MANIFEST_BASENAME).auto.manifest $(MT_SPECIAL_SWITCH) & \ +if "%ERRORLEVEL%" == "$(MT_SPECIAL_RETURN)" \ +rc /r $(_VC_MANIFEST_BASENAME).auto.rc & \ +link $** /out:$@ $(LFLAGS) + +!else + +_VC_MANIFEST_EMBED_EXE= \ +if exist $@.manifest mt.exe -manifest $@.manifest -outputresource:$@;1 + +!endif + +#################################################### +# _VC_MANIFEST_CLEAN - command to clean resources files generated temporarily: + +!if "$(_VC_MANIFEST_INC)" == "1" + +_VC_MANIFEST_CLEAN=-del $(_VC_MANIFEST_BASENAME).auto.res \ + $(_VC_MANIFEST_BASENAME).auto.rc \ + $(_VC_MANIFEST_BASENAME).auto.manifest + +!else + +_VC_MANIFEST_CLEAN= + +!endif + +# End of makefile.inc +#################################################### +``` + +Now create *`makefile.target.inc`* and copy the following content into it: + +```makefile +# makefile.target.inc - include this at the very bottom of the existing makefile + +#################################################### +# Commands to generate initial empty manifest file and the RC file +# that references it, and for generating the .res file: + +$(_VC_MANIFEST_BASENAME).auto.res : $(_VC_MANIFEST_BASENAME).auto.rc + +$(_VC_MANIFEST_BASENAME).auto.rc : $(_VC_MANIFEST_BASENAME).auto.manifest + type <<$@ +#include +1RT_MANIFEST"$(_VC_MANIFEST_BASENAME).auto.manifest" +<< KEEP + +$(_VC_MANIFEST_BASENAME).auto.manifest : + type <<$@ + + + +<< KEEP + +# end of makefile.target.inc +``` ## See also -[Concepts of Isolated Applications and Side-by-side Assemblies](concepts-of-isolated-applications-and-side-by-side-assemblies.md)
-[Building C/C++ Isolated Applications and Side-by-side Assemblies](building-c-cpp-isolated-applications-and-side-by-side-assemblies.md) +[Building C/C++ isolated applications and side-by-side assemblies](building-c-cpp-isolated-applications-and-side-by-side-assemblies.md)\ +[Concepts of isolated applications and side-by-side assemblies](concepts-of-isolated-applications-and-side-by-side-assemblies.md)\ +[Troubleshooting C/C++ isolated applications and side-by-side assemblies](troubleshooting-c-cpp-isolated-applications-and-side-by-side-assemblies.md)\ +[`/INCREMENTAL` (Link incrementally)](./reference/incremental-link-incrementally.md)\ +[`/MANIFEST` (Create side-by-side assembly manifest)](./reference/manifest-create-side-by-side-assembly-manifest.md)\ +[Strong Name assemblies (Assembly signing) (C++/CLI)](../dotnet/strong-name-assemblies-assembly-signing-cpp-cli.md)\ +[Edit and Continue](/visualstudio/debugger/edit-and-continue) diff --git a/docs/build/vscpp-step-0-installation.md b/docs/build/vscpp-step-0-installation.md index 148cba3ddc..f6e9b8cea0 100644 --- a/docs/build/vscpp-step-0-installation.md +++ b/docs/build/vscpp-step-0-installation.md @@ -1,30 +1,132 @@ --- title: Install C and C++ support in Visual Studio -description: "Learn how to install Visual Studio with support for Microsoft C/C++ and related workloads." -ms.custom: "mvc" -ms.date: 11/05/2020 -ms.topic: "tutorial" +description: "Learn how to install Visual Studio with support for Microsoft C and C++ and related workloads." +ms.custom: vs-acquisition, intro-installation +ms.date: 03/18/2025 +ms.topic: tutorial ms.devlang: "cpp" -ms.assetid: 45138d70-719d-42dc-90d7-1d0ca31a2f54 --- # Install C and C++ support in Visual Studio -If you haven't downloaded and installed Visual Studio and the Microsoft C/C++ tools yet, here's how to get started. +If you haven't installed Visual Studio and the Microsoft C and C++ tools yet, here's how to get started. + +::: moniker range="msvc-170" + +## Visual Studio 2022 installation + +Welcome to Visual Studio 2022! In this version, it's easy to choose and install just the features you need. Because of its reduced minimum footprint, Visual Studio installs quickly and with less system impact. + +> [!NOTE] +> This article applies to installation of Visual Studio on Windows. [Visual Studio Code](https://code.visualstudio.com) is a lightweight, cross-platform development environment that runs on Windows, Mac, and Linux systems. The Microsoft [C/C++ for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) extension supports IntelliSense, debugging, code formatting, autocompletion. Visual Studio for Mac doesn't support Microsoft C++, but does support .NET languages and cross-platform development. For installation instructions, see [Install Visual Studio for Mac](/visualstudio/mac/installation/). + +To learn what else is new in this version, see the Visual Studio [release notes](/visualstudio/releases/2022/release-notes/). + +Ready to install? Use the following step-by-step guide. + +### Step 1 - Prepare your computer for Visual Studio + +Before you begin installing Visual Studio: + +1. Check the [system requirements](/visualstudio/releases/2022/system-requirements). These requirements help you know whether your computer supports Visual Studio 2022. + +1. Apply the latest Windows updates. These updates ensure that your computer has both the latest security updates and the required system components for Visual Studio. + +1. Reboot your computer. The reboot ensures that any pending installs or updates don't hinder the Visual Studio install. + +1. Free up disk space. Remove unneeded files and applications from your %SystemDrive% by, for example, running the Disk Cleanup app. + +For questions about running previous versions of Visual Studio side by side with Visual Studio 2022, see the [Visual Studio 2022 Platform Targeting and Compatibility](/visualstudio/releases/2022/compatibility/) page. + +### Step 2 - Download Visual Studio + +Select the following button to go to the Visual Studio download page, and download the Visual Studio bootstrapper file. Select the edition of Visual Studio that you want and choose the **Free trial** or **Free download** button. + +> [!div class="button"] +> [Download Visual Studio](https://visualstudio.microsoft.com/downloads/) + +>[!TIP] +> The Community edition is for individual developers, classroom learning, academic research, and open source development. For other uses, install Visual Studio 2022 Professional or Visual Studio 2022 Enterprise. + +### Step 3 - Install the Visual Studio Installer + +Run the bootstrapper file you downloaded to install the Visual Studio Installer. This new lightweight installer includes everything you need to both install and customize Visual Studio. + +1. From your *Downloads* folder, double-click the bootstrapper file called *VisualStudioSetup.exe*. + + If you receive a User Account Control notice, choose **Yes** to allow the bootstrapper to run. + +1. We ask you to acknowledge the Microsoft [License Terms](https://visualstudio.microsoft.com/license-terms/) and the Microsoft [Privacy Statement](https://privacy.microsoft.com/privacystatement). Choose **Continue**. + +### Step 4 - Choose workloads + +You can use the installer to customize your installation by selecting the *workloads*, or feature sets, that you want. + +1. Find the workload you want in the **Installing Visual Studio** screen. + + :::image type="content" source="../get-started/media/vs2022-installer-workloads.png" alt-text="Screenshot of the Visual Studio 2022 installer with the Desktop development with C plus plus workload selected." lightbox="../get-started/media/vs2022-installer-workloads.png"::: + + For core C and C++ support, choose the **Desktop development with C++** workload. It comes with the default core editor, which includes basic code editing support for more than 20 languages, the ability to open and edit code from any folder without requiring a project, and integrated source code control. + + The **Installation details** pane lists the included and optional components installed by each workload. You can select or deselect optional components in this list. For example, to support development by using the Visual Studio 2017 or 2015 compiler toolsets, choose the MSVC v141 or MSVC v140 optional components. You can add support for MFC, the experimental Modules language extension, IncrediBuild, and more. + + Other workloads support more kinds of development. For example, choose the **Universal Windows Platform development** workload to create apps that use the Windows Runtime for the Microsoft Store. Choose **Game development with C++** to create games that use DirectX, Unreal, or Cocos2d. Choose **Linux development with C++** to target Linux platforms, including IoT development. + +1. After you choose the workloads and optional components you want, choose **Install**. + + Next, status screens appear that show the progress of your Visual Studio installation. + +> [!TIP] +> At any time after installation, you can install workloads or components that you didn't install initially. If you have Visual Studio open, go to **Tools** > **Get Tools and Features...** which opens the Visual Studio Installer. Or, open **Visual Studio Installer** from the Start menu. From there, you can choose the workloads or components that you wish to install. Then, choose **Modify**. + +### Step 5 - Choose individual components (optional) + +If you don't want to use the Workloads feature to customize your Visual Studio installation, or you want to add more components than a workload installs, you can do so by installing or adding individual components from the **Individual components** tab. Choose what you want, and then follow the prompts. + +### Step 6 - Install language packs (optional) + +By default, the installer program tries to match the language of the operating system when it runs for the first time. To install Visual Studio in a language of your choosing, choose the **Language packs** tab from the Visual Studio Installer, and then follow the prompts. + + :::image type="content" source="../get-started/media/vs-installer-language-packs.png" alt-text="Screenshot of the Visual Studio Installer, showing the Install language packs tab view and the languages you can choose from like English, Spanish, Chinese (simplified or traditional)." lightbox="../get-started/media/vs-installer-language-packs.png"::: + +#### Change the installer language from the command line + +Another way that you can change the default language is by running the installer from the command line. For example, you can force the installer to run in English by using the following command: `vs_installer.exe --locale en-US`. The installer remembers this setting when it's run the next time. The installer supports the following language tokens: zh-cn, zh-tw, cs-cz, en-us, es-es, fr-fr, de-de, it-it, ja-jp, ko-kr, pl-pl, pt-br, ru-ru, and tr-tr. + +### Step 7 - Change the installation location (optional) + +You can reduce the installation footprint of Visual Studio on your system drive. You can choose to move the download cache, shared components, SDKs, and tools to different drives, and keep Visual Studio on the drive that runs it the fastest. + +> [!IMPORTANT] +> You can select a different drive only when you first install Visual Studio. If you've already installed it and want to change drives, you must uninstall Visual Studio and then reinstall it. + +### Step 8 - Start developing + +1. After Visual Studio installation is complete, choose the **Launch** button to get started developing with Visual Studio. + +1. On the start window, choose **Create a new project**. + +1. In the search box, enter the type of app you want to create to see a list of available templates. The list of templates depends on the workloads that you chose during installation. To see different templates, choose different workloads. + + You can also filter your search for a specific programming language by using the **Language** dropdown list. You can filter by using the **Platform** list and the **Project type** list, too. + +1. Visual Studio opens your new project, and you're ready to code! + +::: moniker-end ::: moniker range="msvc-160" -## Visual Studio 2019 Installation +## Visual Studio 2019 installation -Welcome to Visual Studio 2019! In this version, it's easy to choose and install just the features you need. And because of its reduced minimum footprint, it installs quickly and with less system impact. +Welcome to Visual Studio 2019! In this version, it's easy to choose and install just the features you need. Because of its reduced minimum footprint, Visual Studio installs quickly and with less system impact. > [!NOTE] -> This topic applies to installation of Visual Studio on Windows. [Visual Studio Code](https://code.visualstudio.com/) is a lightweight, cross-platform development environment that runs on Windows, Mac, and Linux systems. The Microsoft [C/C++ for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) extension supports IntelliSense, debugging, code formatting, auto-completion. Visual Studio for Mac doesn't support Microsoft C++, but does support .NET languages and cross-platform development. For installation instructions, see [Install Visual Studio for Mac](/visualstudio/mac/installation/). +> This article applies to installation of Visual Studio on Windows. [Visual Studio Code](https://code.visualstudio.com) is a lightweight, cross-platform development environment that runs on Windows, Mac, and Linux systems. The Microsoft [C/C++ for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools) extension supports IntelliSense, debugging, code formatting, autocompletion. Visual Studio for Mac doesn't support Microsoft C++, but does support .NET languages and cross-platform development. For installation instructions, see [Install Visual Studio for Mac](/visualstudio/mac/installation/). -Want to know more about what else is new in this version? See the Visual Studio [release notes](/visualstudio/releases/2019/release-notes/). +To learn what else is new in this version, see the Visual Studio [release notes](/visualstudio/releases/2019/release-notes/). -Ready to install? We'll walk you through it, step-by-step. +Ready to install? Use the following step-by-step guide. -### Step 1 - Make sure your computer is ready for Visual Studio +### Step 1 - Prepare your computer for Visual Studio Before you begin installing Visual Studio: @@ -32,75 +134,71 @@ Before you begin installing Visual Studio: 1. Apply the latest Windows updates. These updates ensure that your computer has both the latest security updates and the required system components for Visual Studio. -1. Reboot. The reboot ensures that any pending installs or updates don't hinder the Visual Studio install. +1. Reboot your computer. The reboot ensures that any pending installs or updates don't hinder the Visual Studio install. -1. Free up space. Remove unneeded files and applications from your %SystemDrive% by, for example, running the Disk Cleanup app. +1. Free up disk space. Remove unneeded files and applications from your %SystemDrive% by, for example, running the Disk Cleanup app. For questions about running previous versions of Visual Studio side by side with Visual Studio 2019, see the [Visual Studio 2019 Platform Targeting and Compatibility](/visualstudio/releases/2019/compatibility/) page. ### Step 2 - Download Visual Studio -Next, download the Visual Studio bootstrapper file. To do so, choose the following button to go to the Visual Studio download page. Select the edition of Visual Studio that you want and choose the **Free trial** or **Free download** button. +Select the following button to go to the Visual Studio older downloads page, and download the Visual Studio 2019 bootstrapper file. > [!div class="button"] - > [Download Visual Studio](https://visualstudio.microsoft.com/downloads/?utm_medium=microsoft&utm_source=docs.microsoft.com&utm_campaign=button+cta&utm_content=download+vs2019+rc) + > [Download Visual Studio 2019](https://visualstudio.microsoft.com/vs/older-downloads/#visual-studio-2019-and-other-products) -### Step 3 - Install the Visual Studio installer +### Step 3 - Install the Visual Studio Installer Run the bootstrapper file you downloaded to install the Visual Studio Installer. This new lightweight installer includes everything you need to both install and customize Visual Studio. -1. From your **Downloads** folder, double-click the bootstrapper that matches or is similar to one of the following files: - - - **vs_community.exe** for Visual Studio Community - - **vs_professional.exe** for Visual Studio Professional - - **vs_enterprise.exe** for Visual Studio Enterprise +1. From your *Downloads* folder, double-click the bootstrapper file. If you receive a User Account Control notice, choose **Yes** to allow the bootstrapper to run. -1. We'll ask you to acknowledge the Microsoft [License Terms](https://visualstudio.microsoft.com/license-terms/) and the Microsoft [Privacy Statement](https://privacy.microsoft.com/privacystatement). Choose **Continue**. +1. We ask you to acknowledge the Microsoft [License Terms](https://visualstudio.microsoft.com/license-terms/) and the Microsoft [Privacy Statement](https://privacy.microsoft.com/privacystatement). Choose **Continue**. ### Step 4 - Choose workloads -After the installer is installed, you can use it to customize your installation by selecting the *workloads*, or feature sets, that you want. Here's how. +You can use the installer to customize your installation by selecting the *workloads*, or feature sets, that you want. 1. Find the workload you want in the **Installing Visual Studio** screen. - ![Visual Studio 2019: Install a workload](../get-started/media/vs-installer-workloads.png) - - For core C and C++ support, choose the "Desktop development with C++" workload. It comes with the default core editor, which includes basic code editing support for over 20 languages, the ability to open and edit code from any folder without requiring a project, and integrated source code control. + :::image type="content" source="../get-started/media/vs-installer-workloads.png" alt-text="Screenshot of the Visual Studio 2019 installer." lightbox="../get-started/media/vs-installer-workloads.png"::: - Additional workloads support other kinds of development. For example, choose the "Universal Windows Platform development" workload to create apps that use the Windows Runtime for the Microsoft Store. Choose "Game development with C++" to create games that use DirectX, Unreal, and Cocos2d. Choose "Linux development with C++" to target Linux platforms, including IoT development. + For core C and C++ support, choose the **Desktop development with C++** workload. It comes with the default core editor, which includes basic code editing support for over 20 languages, the ability to open and edit code from any folder without requiring a project, and integrated source code control. The **Installation details** pane lists the included and optional components installed by each workload. You can select or deselect optional components in this list. For example, to support development by using the Visual Studio 2017 or 2015 compiler toolsets, choose the MSVC v141 or MSVC v140 optional components. You can add support for MFC, the experimental Modules language extension, IncrediBuild, and more. -1. After you choose the workload(s) and optional components you want, choose **Install**. + Other workloads support more kinds of development. For example, choose the **Universal Windows Platform development** workload to create apps that use the Windows Runtime for the Microsoft Store. Choose **Game development with C++** to create games that use DirectX, Unreal, and Cocos2d. Choose **Linux development with C++** to target Linux platforms, including IoT development. + +1. After you choose the workloads and optional components you want, choose **Install**. Next, status screens appear that show the progress of your Visual Studio installation. > [!TIP] > At any time after installation, you can install workloads or components that you didn't install initially. If you have Visual Studio open, go to **Tools** > **Get Tools and Features...** which opens the Visual Studio Installer. Or, open **Visual Studio Installer** from the Start menu. From there, you can choose the workloads or components that you wish to install. Then, choose **Modify**. -### Step 5 - Choose individual components (Optional) +### Step 5 - Choose individual components (optional) -If you don't want to use the Workloads feature to customize your Visual Studio installation, or you want to add more components than a workload installs, you can do so by installing or adding individual components from the **Individual components** tab. Choose what you want, and then follow the prompts. +If you don't want to use the Workloads feature to customize your Visual Studio installation, or if you want to add more components than a workload installs, you can do so by installing or adding individual components from the **Individual components** tab. Choose what you want, and then follow the prompts. - ![Visual Studio 2019 - Install individual components](../get-started/media/vs-installer-individual-components.png "Install Visual Studio individual components") +:::image type="content" source="../get-started/media/vs-installer-individual-components.png" alt-text="Screenshot of the Visual Studio Installer, showing the Install individual components tab view." lightbox="../get-started/media/vs-installer-individual-components.png"::: -### Step 6 - Install language packs (Optional) +### Step 6 - Install language packs (optional) By default, the installer program tries to match the language of the operating system when it runs for the first time. To install Visual Studio in a language of your choosing, choose the **Language packs** tab from the Visual Studio Installer, and then follow the prompts. - ![Visual Studio 2019 - Install language packs](../get-started/media/vs-installer-language-packs.png "Install Visual Studio language packs") +:::image type="content" source="../get-started/media/vs-installer-language-packs.png" alt-text="Screenshot of the Visual Studio Installer, showing the Install language packs tab view." lightbox="../get-started/media/vs-installer-language-packs.png"::: #### Change the installer language from the command line Another way that you can change the default language is by running the installer from the command line. For example, you can force the installer to run in English by using the following command: `vs_installer.exe --locale en-US`. The installer will remember this setting when it's run the next time. The installer supports the following language tokens: zh-cn, zh-tw, cs-cz, en-us, es-es, fr-fr, de-de, it-it, ja-jp, ko-kr, pl-pl, pt-br, ru-ru, and tr-tr. -### Step 7 - Change the installation location (Optional) +### Step 7 - Change the installation location (optional) You can reduce the installation footprint of Visual Studio on your system drive. You can choose to move the download cache, shared components, SDKs, and tools to different drives, and keep Visual Studio on the drive that runs it the fastest. - ![Visual Studio 2019 - Change installation locations](../get-started/media/vs-installer-installation-locations.png "Change the installation location") +:::image type="content" source="../get-started/media/vs-installer-installation-locations.png" alt-text="Screenshot of the Visual Studio Installer, showing the installation locations tab view." lightbox="../get-started/media/vs-installer-installation-locations.png"::: > [!IMPORTANT] > You can select a different drive only when you first install Visual Studio. If you've already installed it and want to change drives, you must uninstall Visual Studio and then reinstall it. @@ -111,9 +209,9 @@ You can reduce the installation footprint of Visual Studio on your system drive. 1. On the start window, choose **Create a new project**. -1. In the search box, enter the type of app you want to create to see a list of available templates. The list of templates depends on the workload(s) that you chose during installation. To see different templates, choose different workloads. +1. In the search box, enter the type of app you want to create to see a list of available templates. The list of templates depends on the workloads that you chose during installation. To see different templates, choose different workloads. - You can also filter your search for a specific programming language by using the **Language** drop-down list. You can filter by using the **Platform** list and the **Project type** list, too. + You can also filter your search for a specific programming language by using the **Language** dropdown list. You can filter by using the **Platform** list and the **Project type** list, too. 1. Visual Studio opens your new project, and you're ready to code! @@ -121,15 +219,13 @@ You can reduce the installation footprint of Visual Studio on your system drive. ::: moniker range="msvc-150" -## Visual Studio 2017 Installation +## Visual Studio 2017 installation -In Visual Studio 2017, it's easy to choose and install just the features you need. And because of its reduced minimum footprint, it installs quickly and with less system impact. +In Visual Studio 2017, it's easy to choose and install just the features you need. Because of its reduced minimum footprint, it installs quickly and with less system impact. ### Prerequisites -- A broadband internet connection. The Visual Studio installer can download several gigabytes of data. - -- A computer that runs Microsoft Windows 7 or later versions. We recommend Windows 10 for the best development experience. Make sure that the latest updates are applied to your system before you install Visual Studio. +- A computer that runs Microsoft Windows 7 or later versions. We recommend the latest version of Windows for the best development experience. Make sure that the latest updates are applied to your system before you install Visual Studio. - Enough free disk space. Visual Studio requires at least 7 GB of disk space, and can take 50 GB or more if many common options are installed. We recommend you install it on your C: drive. @@ -137,36 +233,29 @@ For details on the disk space and operating system requirements, see [Visual Stu ### Download and install -1. To download the latest Visual Studio 2017 installer for Windows, go to the Microsoft Visual Studio [Older downloads](https://www.visualstudio.com/vs/older-downloads/) page. Expand the **2017** section, and choose the **Download** button. - - >[!Tip] - > The Community edition is for individual developers, classroom learning, academic research, and open source development. For other uses, install Visual Studio 2017 Professional or Visual Studio 2017 Enterprise. +1. To download the Visual Studio 2017 installer for Windows, go to the Visual Studio [older downloads](https://visualstudio.microsoft.com/vs/older-downloads/#visual-studio-2017-and-other-products) page. Expand the **2017** section, and choose the **Download** button. -1. Find the installer file you downloaded and run it. The downloaded file may be displayed in your browser, or you may find it in your Downloads folder. The installer needs Administrator privileges to run. You may see a **User Account Control** dialog asking you to give permission to let the installer make changes to your system; choose **Yes**. If you're having trouble, find the downloaded file in File Explorer, right-click on the installer icon, and choose **Run as Administrator** from the context menu. +1. Find the installer file you downloaded and run it. The downloaded file might be displayed in your browser, or you might find it in your *Downloads* folder. The installer needs Administrator privileges to run. You might see a **User Account Control** dialog asking you to give permission to let the installer make changes to your system; choose **Yes**. If you're having trouble, find the downloaded file in File Explorer, right-click on the installer icon, and choose **Run as Administrator** from the context menu. - ![Download and install the Visual Studio Installer](media/vscpp-concierge-run-installer.gif "Download and install the Visual Studio Installer") + :::image type="content" source="media/vscpp-concierge-run-installer.gif" alt-text="Animation that shows the Visual Studio Installer."::: 1. The installer presents you with a list of workloads, which are groups of related options for specific development areas. Support for C++ is now part of optional workloads that aren't installed by default. - ![Desktop development with C++ workload](media/desktop-development-with-cpp.png "Desktop development with C++") + :::image type="content" source="media/desktop-development-with-cpp.png" alt-text="Screenshot showing the Desktop development with C plus plus workload."::: For C and C++, select the **Desktop development with C++** workload and then choose **Install**. - ![Install the Desktop development with C++ workload](media/vscpp-concierge-choose-workload.gif "Install the Desktop development with C++ workload") + :::image type="content" source="media/vscpp-concierge-choose-workload.gif" alt-text="Animation that shows the Desktop development with C plus plus workload then choose the Install button."::: 1. When the installation completes, choose the **Launch** button to start Visual Studio. The first time you run Visual Studio, you're asked to sign in with a Microsoft Account. If you don't have one, you can create one for free. You must also choose a theme. Don't worry, you can change it later if you want to. - It may take Visual Studio several minutes to get ready for use the first time you run it. Here's what it looks like in a quick time-lapse: - - ![Visual Studio 2017 sign in](media/vscpp-quickstart-first-run.gif "Visual Studio 2017 sign in") - - Visual Studio starts much faster when you run it again. + It might take Visual Studio several minutes to get ready for use the first time you run it. 1. When Visual Studio opens, check to see if the flag icon in the title bar is highlighted: - ![Visual Studio 2017 notification flag](media/vscpp-first-start-page-flag.png "Visual Studio 2017 notification flag") + :::image type="content" source="media/vscpp-first-start-page-flag.png" alt-text="Screenshot of the Visual Studio notification flag."::: If it's highlighted, select it to open the **Notifications** window. If there are any updates available for Visual Studio, we recommend you install them now. Once the installation is complete, restart Visual Studio. @@ -174,9 +263,9 @@ For details on the disk space and operating system requirements, see [Visual Stu ::: moniker range=" [!div class="nextstepaction"] -> [Create a C++ project](vscpp-step-1-create.md) - -