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/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 bc0cf04f4b..10b0192bf5 100644 --- a/.gitignore +++ b/.gitignore @@ -7,9 +7,10 @@ _themes.MSDN.Modern/ _themes.VS.Modern/ # Ignore local configuration changes -.github/ +#.github/ .openpublishing.buildcore.ps1 .vscode/ # Documentation build /docs/vcppdocs +debug.log 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 87f6e7c300..296bfe4f38 100644 --- a/.openpublishing.publish.config.json +++ b/.openpublishing.publish.config.json @@ -8,9 +8,12 @@ "locale": "en-us", "monikers": [], "moniker_ranges": [ - ">= vs-2015" + ">= 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 a9a617b267..dc66331425 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", @@ -16,7 +21,7 @@ "redirect_document_id": true }, { - "source_path": "docs/supported-platforms-visual-cpp.md.md", + "source_path": "docs/supported-platforms-visual-cpp.md", "redirect_url": "/cpp/overview/supported-platforms-visual-cpp", "redirect_document_id": true }, @@ -62,8 +67,8 @@ }, { "source_path": "docs/vcpkg.md", - "redirect_url": "/cpp/build/vcpkg", - "redirect_document_id": true + "redirect_url": "https://vcpkg.io/", + "redirect_document_id": false }, { "source_path": "docs/windows/universal-windows-apps-cpp.md", @@ -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,12 +502,102 @@ }, { "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 + }, + { + "source_path": "docs/build/reference/specifying-dlls-to-delay-load.md", + "redirect_url": "/cpp/build/reference/linker-support-for-delay-loaded-dlls#specify-dlls-to-delay-load", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/explicitly-unloading-a-delay-loaded-dll.md", + "redirect_url": "/cpp/build/reference/linker-support-for-delay-loaded-dlls#explicitly-unload-a-delay-loaded-dll", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/binding-imports.md", + "redirect_url": "/cpp/build/reference/linker-support-for-delay-loaded-dlls#binding-imports", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/loading-all-imports-for-a-delay-loaded-dll.md", + "redirect_url": "/cpp/build/reference/linker-support-for-delay-loaded-dlls#load-all-imports-for-a-delay-loaded-dll", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/dumping-delay-loaded-imports.md", + "redirect_url": "/cpp/build/reference/linker-support-for-delay-loaded-dlls#dump-delay-loaded-imports", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/constraints-of-delay-loading-dlls.md", + "redirect_url": "/cpp/build/reference/linker-support-for-delay-loaded-dlls#constraints-on-delay-load-dlls", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/notification-hooks.md", + "redirect_url": "/cpp/build/reference/error-handling-and-notification#notification-hooks", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/failure-hooks.md", + "redirect_url": "/cpp/build/reference/error-handling-and-notification#failure-hooks", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/exceptions-c-cpp.md", + "redirect_url": "/cpp/build/reference/error-handling-and-notification#delay-load-exception-codes", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/changes-in-the-dll-delayed-loading-helper-function-since-visual-cpp-6-0.md", + "redirect_url": "/cpp/build/reference/understanding-the-helper-function", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/calling-conventions-parameters-and-return-type.md", + "redirect_url": "/cpp/build/reference/understanding-the-helper-function#calling-conventions-parameters-and-return-type", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/structure-and-constant-definitions.md", + "redirect_url": "/cpp/build/reference/understanding-the-helper-function#structure-and-constant-definitions", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/calculating-necessary-values.md", + "redirect_url": "/cpp/build/reference/understanding-the-helper-function#calculate-necessary-values", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/unloading-a-delay-loaded-dll.md", + "redirect_url": "/cpp/build/reference/understanding-the-helper-function#unload-a-delay-loaded-dll", + "redirect_document_id": false + }, + { + "source_path": "docs/build/reference/developing-your-own-helper-function.md", + "redirect_url": "/cpp/build/reference/understanding-the-helper-function#develop-your-own-helper-function", "redirect_document_id": false }, { "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 }, { @@ -472,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 }, { @@ -492,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 }, { @@ -522,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 }, { @@ -557,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 }, { @@ -587,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 }, { @@ -607,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 }, { @@ -640,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", @@ -650,9 +890,39 @@ "redirect_url": "/cpp/build/reference/using-an-nmake-macro", "redirect_document_id": false }, + { + "source_path": "docs/build/vcpkg.md", + "redirect_url": "https://vcpkg.io/", + "redirect_document_id": false + }, + { + "source_path": "docs/build/install-vcpkg.md", + "redirect_url": "https://vcpkg.io/", + "redirect_document_id": false + }, + { + "source_path": "docs/build/integrate-vcpkg.md", + "redirect_url": "https://vcpkg.io/", + "redirect_document_id": false + }, + { + "source_path": "docs/build/manage-libraries-with-vcpkg.md", + "redirect_url": "https://vcpkg.io/", + "redirect_document_id": false + }, + { + "source_path": "docs/build/vcpkg-command-line-reference.md", + "redirect_url": "https://vcpkg.io/", + "redirect_document_id": false + }, { "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 }, { @@ -700,6 +970,46 @@ "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", + "redirect_document_id": false + }, + { + "source_path": "docs/c-language/punctuators.md", + "redirect_url": "/cpp/c-language/lexical-grammar", + "redirect_document_id": false + }, + { + "source_path": "docs/c-language/summary-of-constants.md", + "redirect_url": "/cpp/c-language/lexical-grammar", + "redirect_document_id": false + }, + { + "source_path": "docs/c-language/summary-of-identifiers.md", + "redirect_url": "/cpp/c-language/lexical-grammar", + "redirect_document_id": false + }, + { + "source_path": "docs/c-language/summary-of-keywords.md", + "redirect_url": "/cpp/c-language/lexical-grammar", + "redirect_document_id": false + }, + { + "source_path": "docs/c-language/summary-of-string-literals.md", + "redirect_url": "/cpp/c-language/lexical-grammar", + "redirect_document_id": false + }, + { + "source_path": "docs/c-language/summary-of-tokens.md", + "redirect_url": "/cpp/c-language/lexical-grammar", + "redirect_document_id": false + }, { "source_path": "docs/cloud/index.md", "redirect_url": "/cpp/cloud/cloud-and-web-programming-in-visual-cpp", @@ -755,6 +1065,16 @@ "redirect_url": "/cpp/cpp/attributes", "redirect_document_id": false }, + { + "source_path": "docs/cpp/bstr-t-member-functions.md", + "redirect_url": "/cpp/cpp/bstr-t-class", + "redirect_document_id": false + }, + { + "source_path": "docs/cpp/bstr-t-operators.md", + "redirect_url": "/cpp/cpp/bstr-t-class", + "redirect_document_id": false + }, { "source_path": "docs/cpp/character-sets2.md", "redirect_url": "/cpp/cpp/character-sets", @@ -1060,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", @@ -7121,7 +7436,7 @@ "redirect_document_id": false }, { - "source_path": "docs/dotnet/how-to-enumerate-data-types-in-assemblies-using-reflection-cpp-cli.md.md", + "source_path": "docs/dotnet/how-to-enumerate-data-types-in-assemblies-using-reflection-cpp-cli.md", "redirect_url": "/cpp/dotnet/reflection-cpp-cli#enumerate", "redirect_document_id": false }, @@ -7435,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", @@ -8377,12 +8707,12 @@ }, { "source_path": "docs/windows/editing-properties-for-an-activex-control.md", - "redirect_url": "/cpp/windows/viewing-and-adding-activex-controls-to-a-dialog-box", + "redirect_url": "/cpp/windows/adding-editing-or-deleting-controls", "redirect_document_id": false }, { "source_path": "docs/windows/insert-activex-control-dialog-box.md", - "redirect_url": "/cpp/windows/viewing-and-adding-activex-controls-to-a-dialog-box", + "redirect_url": "/cpp/windows/adding-editing-or-deleting-controls", "redirect_document_id": false }, { @@ -8607,42 +8937,42 @@ }, { "source_path": "docs/windows/creating-a-new-toolbar-button.md", - "redirect_url": "/cpp/windows/creating-moving-and-editing-toolbar-buttons", + "redirect_url": "/cpp/windows/toolbar-editor", "redirect_document_id": false }, { "source_path": "docs/windows/moving-a-toolbar-button.md", - "redirect_url": "/cpp/windows/creating-moving-and-editing-toolbar-buttons", + "redirect_url": "/cpp/windows/toolbar-editor", "redirect_document_id": false }, { "source_path": "docs/windows/copying-buttons-from-a-toolbar.md", - "redirect_url": "/cpp/windows/creating-moving-and-editing-toolbar-buttons", + "redirect_url": "/cpp/windows/toolbar-editor", "redirect_document_id": false }, { "source_path": "docs/windows/deleting-a-toolbar-button.md", - "redirect_url": "/cpp/windows/creating-moving-and-editing-toolbar-buttons", + "redirect_url": "/cpp/windows/toolbar-editor", "redirect_document_id": false }, { "source_path": "docs/windows/inserting-a-space-between-buttons-on-a-toolbar.md", - "redirect_url": "/cpp/windows/creating-moving-and-editing-toolbar-buttons", + "redirect_url": "/cpp/windows/toolbar-editor", "redirect_document_id": false }, { "source_path": "docs/windows/removing-space-between-buttons-on-a-toolbar.md", - "redirect_url": "/cpp/windows/creating-moving-and-editing-toolbar-buttons", + "redirect_url": "/cpp/windows/toolbar-editor", "redirect_document_id": false }, { "source_path": "docs/windows/changing-the-properties-of-a-toolbar-button.md", - "redirect_url": "/cpp/windows/creating-moving-and-editing-toolbar-buttons", + "redirect_url": "/cpp/windows/toolbar-editor", "redirect_document_id": false }, { "source_path": "docs/windows/toolbar-button-properties.md", - "redirect_url": "/cpp/windows/creating-moving-and-editing-toolbar-buttons", + "redirect_url": "/cpp/windows/toolbar-editor", "redirect_document_id": false }, { @@ -13419,6 +13749,21 @@ "source_path": "docs/parallel/openmp/a-31-thread-safe-lock-functions.md", "redirect_url": "/cpp/parallel/openmp/a-examples#a31-thread-safe-lock-functions", "redirect_document_id": false + }, + { + "source_path": "docs/c-runtime-library/operator-delete-crt.md", + "redirect_url": "/cpp/c-runtime-library/delete-operator-crt", + "redirect_document_id": false + }, + { + "source_path": "docs/c-runtime-library/operator-new-crt.md", + "redirect_url": "/cpp/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 new file mode 100644 index 0000000000..a5807f933e --- /dev/null +++ b/.whatsnew.json @@ -0,0 +1,53 @@ +{ + "$schema": "https://github.com/dotnet/docs-tools/blob/main/WhatsNew.Infrastructure/Configuration/reposettings.schema.json", + "docSetProductName": "C++, C, and Assembler", + "rootDirectory": "docs/", + "docLinkSettings": { + "linkFormat": "relative", + "relativeLinkPrefix": "../" + }, + "inclusionCriteria": { + "minAdditionsToFile": 2, + "pullRequestTitlesToIgnore": [ + "^Confirm merge from FromPublicMasterBranch", + "^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)"}, + {"names": ["build"], "heading": "C/C++ projects and build systems"}, + {"names": ["build-insights"], "heading": "Build insights"}, + {"names": ["c-language"], "heading": "C language"}, + {"names": ["cloud"], "heading": "Cloud programming with Microsoft C++"}, + {"names": ["code-quality"], "heading": "Code quality"}, + {"names": ["cpp"], "heading": "C++ in Visual Studio"}, + {"names": ["cppcx"], "heading": "C++ /CX"}, + {"names": ["cross-platform"], "heading": "Cross platform development"}, + {"names": ["c-runtime-library"], "heading": "C runtime library"}, + {"names": ["data"], "heading": "Data access in C/C++ in Visual Studio"}, + {"names": ["dotnet"], "heading":"STL/CLR library reference"}, + {"names": ["error-messages"], "heading":"C/C++ compiler and tools errors and warnings"}, + {"names": ["extensions"], "heading":"Component extensions for .NET and UWP"}, + {"names": ["get-started"], "heading":"C++ in Visual Studio tutorials"}, + {"names": ["ide"], "heading":"Read and write code using C++ in Visual Studio"}, + {"names": ["linux"], "heading":"Linux with C++ in Visual Studio"}, + {"names": ["overview"], "heading":"C/C++ in Visual Studio overview"}, + {"names": ["parallel"], "heading":"Parallel programming in C++ in Visual Studio"}, + {"names": ["porting"], "heading":"C++ porting and upgrade guide"}, + {"names": ["preprocessor"], "heading":"C/C++ preprocessor reference"}, + {"names": ["safeint", "security"], "heading":"Security best practices for C++"}, + {"names": ["standard-library"], "heading":"C++ Standard Template Library (STL) reference"}, + {"names": ["text"], "heading":"Text and strings in Visual Studio C++"}, + {"names": ["windows"], "heading":"Overview of Windows programming in C++"} + ] +} 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 ff29580110..363d1dad6b 100644 --- a/docs/_breadcrumb/toc.yml +++ b/docs/_breadcrumb/toc.yml @@ -1,125 +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: 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 0fbed68456..ebe3253ac4 100644 --- a/docs/assembler/arm/arm-assembler-diagnostic-messages.md +++ b/docs/assembler/arm/arm-assembler-diagnostic-messages.md @@ -1,23 +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 @@ -25,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 @@ -49,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 @@ -58,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 @@ -70,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| @@ -84,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 @@ -95,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 df7457cd0e..0dd3001b16 100644 --- a/docs/assembler/arm/arm-assembler-directives.md +++ b/docs/assembler/arm/arm-assembler-directives.md @@ -1,121 +1,122 @@ --- +description: "Learn more about: ARM Assembler Directives" title: "ARM Assembler Directives" ms.date: "08/30/2018" 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 cfc4a8215d..905ab3a72a 100644 --- a/docs/assembler/arm/arm-assembler-reference.md +++ b/docs/assembler/arm/arm-assembler-reference.md @@ -1,21 +1,25 @@ --- -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/accessing-c-or-cpp-data-in-asm-blocks.md b/docs/assembler/inline/accessing-c-or-cpp-data-in-asm-blocks.md index eaa6112fae..8dab8e0883 100644 --- a/docs/assembler/inline/accessing-c-or-cpp-data-in-asm-blocks.md +++ b/docs/assembler/inline/accessing-c-or-cpp-data-in-asm-blocks.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Accessing C or C++ Data in __asm Blocks" title: "Accessing C or C++ Data in __asm Blocks" ms.date: "08/30/2018" helpviewer_keywords: ["data members [C++], in __asm blocks", "data access [C++], in __asm blocks", "__asm keyword [C++], data members", "structure types in __asm blocks"] ms.assetid: e99f5a28-0381-4090-8ece-6af8f2436a49 +ms.topic: concept-article --- # Accessing C or C++ Data in __asm Blocks diff --git a/docs/assembler/inline/advantages-of-inline-assembly.md b/docs/assembler/inline/advantages-of-inline-assembly.md index 5eae8ca90a..4e531912eb 100644 --- a/docs/assembler/inline/advantages-of-inline-assembly.md +++ b/docs/assembler/inline/advantages-of-inline-assembly.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Advantages of Inline Assembly" title: "Advantages of Inline Assembly" ms.date: "08/30/2018" helpviewer_keywords: ["assembler [C++], advantages", "inline assembly [C++], about inline assembly", "inline assembly [C++], using"] diff --git a/docs/assembler/inline/asm.md b/docs/assembler/inline/asm.md index fa191496a4..a14c085469 100644 --- a/docs/assembler/inline/asm.md +++ b/docs/assembler/inline/asm.md @@ -1,32 +1,33 @@ --- title: "__asm" -ms.date: "10/09/2018" +description: "Learn more about: `__asm`" +ms.date: 10/09/2018 +ms.topic: reference f1_keywords: ["__asm", "_asm", "__asm_cpp"] helpviewer_keywords: ["__asm keyword [C++], vs. asm blocks", "__asm keyword [C++]"] -ms.assetid: 77ff3bc9-a492-4b5e-85e1-fa4e414e79cd --- # `__asm` **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 -If used without braces, the **`__asm`** keyword means that the rest of the line is an assembly-language statement. If used with braces, it means that each line between the braces is an assembly-language statement. For compatibility with previous versions, **`_asm`** is a synonym for **`__asm`**. +If used without braces, the **`__asm`** keyword means that the rest of the line is an assembly-language statement. If used with braces, it means that each line between the braces is an assembly-language statement. For compatibility with previous versions, **`_asm`** is a synonym for **`__asm`** unless compiler option [`/Za` (Disable language extensions)](../../build/reference/za-ze-disable-language-extensions.md) is specified. Since the **`__asm`** keyword is a statement separator, you can put assembly instructions on the same line. @@ -36,12 +37,10 @@ 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). -For compatibility with previous versions, **`_asm`** is a synonym for **`__asm`** unless compiler option [/Za \(Disable language extensions)](../../build/reference/za-ze-disable-language-extensions.md) is specified. - ## Example The following code fragment is a simple **`__asm`** block enclosed in braces: @@ -68,9 +67,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/assembly-language-comments.md b/docs/assembler/inline/assembly-language-comments.md index d2e0e29cd6..cf66d19647 100644 --- a/docs/assembler/inline/assembly-language-comments.md +++ b/docs/assembler/inline/assembly-language-comments.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Assembly-Language Comments" title: "Assembly-Language Comments" ms.date: "08/30/2018" helpviewer_keywords: ["assembly language [C++], comments", "comments [C++], assembly language", "macros [C++], assembly language", "__asm keyword [C++], instructions"] diff --git a/docs/assembler/inline/calling-c-functions-in-inline-assembly.md b/docs/assembler/inline/calling-c-functions-in-inline-assembly.md index 3bd9cb7eb7..74bf5c40de 100644 --- a/docs/assembler/inline/calling-c-functions-in-inline-assembly.md +++ b/docs/assembler/inline/calling-c-functions-in-inline-assembly.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Calling C Functions in Inline Assembly" title: "Calling C Functions in Inline Assembly" ms.date: "08/30/2018" helpviewer_keywords: ["function calls, C functions", "function calls, in inline assembly", "functions [C], calling in inline assembly", "Visual C, functions", "inline assembly, calling functions", "__asm keyword [C++], calling functions"] ms.assetid: f8a8d568-d175-4e23-9b24-36ef60a4cab3 +ms.topic: concept-article --- # Calling C Functions in Inline Assembly diff --git a/docs/assembler/inline/calling-cpp-functions-in-inline-assembly.md b/docs/assembler/inline/calling-cpp-functions-in-inline-assembly.md index 16236cbb7f..11c2763e43 100644 --- a/docs/assembler/inline/calling-cpp-functions-in-inline-assembly.md +++ b/docs/assembler/inline/calling-cpp-functions-in-inline-assembly.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Calling C++ Functions in Inline Assembly" title: "Calling C++ Functions in Inline Assembly" ms.date: "08/30/2018" helpviewer_keywords: ["functions [C++], calling in inline assembly", "function calls, C++ functions", "function calls, in inline assembly", "Visual C++, functions", "inline assembly, calling functions", "__asm keyword [C++], calling functions"] ms.assetid: 1f0d1eb3-54cf-45d5-838d-958188616b38 +ms.topic: concept-article --- # Calling C++ Functions in Inline Assembly 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 cdebbe28f3..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,17 +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/debugging-and-listings-for-inline-assembly.md b/docs/assembler/inline/debugging-and-listings-for-inline-assembly.md index 04b3819369..dbe6f30b37 100644 --- a/docs/assembler/inline/debugging-and-listings-for-inline-assembly.md +++ b/docs/assembler/inline/debugging-and-listings-for-inline-assembly.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Debugging and Listings for Inline Assembly" title: "Debugging and Listings for Inline Assembly" ms.date: "08/30/2018" helpviewer_keywords: ["source level debugger", "__asm keyword [C++], debugging", "inline assembly, listings", "bugs, __asm blocks", "debugging [C++], inline assembly code", "inline assembly, debugging"] ms.assetid: 69266930-6f9a-433d-b704-f4f44e7b2583 +ms.topic: concept-article --- # Debugging and Listings for Inline Assembly 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 ae3ca49930..ebea4aa8da 100644 --- a/docs/assembler/inline/defining-asm-blocks-as-c-macros.md +++ b/docs/assembler/inline/defining-asm-blocks-as-c-macros.md @@ -1,8 +1,9 @@ --- 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 +ms.topic: concept-article --- # Defining __asm Blocks as C Macros @@ -14,7 +15,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: @@ -38,7 +39,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/emit-pseudoinstruction.md b/docs/assembler/inline/emit-pseudoinstruction.md index 07900a17f1..b736701ca0 100644 --- a/docs/assembler/inline/emit-pseudoinstruction.md +++ b/docs/assembler/inline/emit-pseudoinstruction.md @@ -1,9 +1,11 @@ --- +description: "Learn more about: _emit Pseudoinstruction" title: "_emit Pseudoinstruction" ms.date: "08/30/2018" f1_keywords: ["_emit"] helpviewer_keywords: ["byte defining (inline assembly)", "_emit pseudoinstruction"] ms.assetid: 004c48f3-364c-4e82-9a51-e326f9cc7b2b +ms.topic: reference --- # _emit Pseudoinstruction diff --git a/docs/assembler/inline/even-and-align-directives.md b/docs/assembler/inline/even-and-align-directives.md index 6ac2e10db9..d98adc4b44 100644 --- a/docs/assembler/inline/even-and-align-directives.md +++ b/docs/assembler/inline/even-and-align-directives.md @@ -1,17 +1,17 @@ --- title: "EVEN and ALIGN Directives" -ms.date: "08/30/2018" +description: "Learn more about: EVEN and ALIGN Directives" +ms.date: 08/30/2018 helpviewer_keywords: ["EVEN directive", "directives, MASM", "MASM (Microsoft Macro Assembler), directives", "NOP (no operation instruction)", "ALIGN directive"] -ms.assetid: 7357ab2d-4a5c-43ca-accb-a5f21cdfcde5 --- -# EVEN and ALIGN Directives +# `EVEN` and `ALIGN` Directives **Microsoft Specific** -Although the inline assembler doesn't support most MASM directives, it does support `EVEN` and **ALIGN**. These directives put **NOP** (no operation) instructions in the assembly code as needed to align labels to specific boundaries. This makes instruction-fetch operations more efficient for some processors. +Although the inline assembler doesn't support most MASM directives, it does support [`EVEN`](../masm/even.md) and [`ALIGN`](../masm/align-masm.md). These directives put `NOP` (no operation) instructions in the assembly code as needed to align labels to specific boundaries. This makes instruction-fetch operations more efficient for some processors. **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](using-assembly-language-in-asm-blocks.md) diff --git a/docs/assembler/inline/inline-assembler-overview.md b/docs/assembler/inline/inline-assembler-overview.md index 774345b686..3b97cd7043 100644 --- a/docs/assembler/inline/inline-assembler-overview.md +++ b/docs/assembler/inline/inline-assembler-overview.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Inline Assembler Overview" title: "Inline Assembler Overview" ms.date: "08/30/2018" helpviewer_keywords: ["inline assembler", "__asm keyword [C++], invoking inline assembler", "invoking inline assembler", "inline assembly, inline assembler"] ms.assetid: d990331a-0e33-4760-8d7a-b720b0288335 +ms.topic: concept-article --- # Inline Assembler Overview diff --git a/docs/assembler/inline/inline-assembler.md b/docs/assembler/inline/inline-assembler.md index bffd6ae51a..70f47d71c8 100644 --- a/docs/assembler/inline/inline-assembler.md +++ b/docs/assembler/inline/inline-assembler.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Inline Assembler" title: "Inline Assembler" ms.date: "08/30/2018" helpviewer_keywords: ["assembler [C++]", "assembler [C++], inline", "assembly language [C++], inline", "inline assembler [C++]", "inline assembly [C++]"] diff --git a/docs/assembler/inline/instruction-set-for-inline-assembly.md b/docs/assembler/inline/instruction-set-for-inline-assembly.md index eeba8b6598..13b356b526 100644 --- a/docs/assembler/inline/instruction-set-for-inline-assembly.md +++ b/docs/assembler/inline/instruction-set-for-inline-assembly.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Instruction Set for Inline Assembly" title: "Instruction Set for Inline Assembly" ms.date: "08/30/2018" ms.topic: "reference" diff --git a/docs/assembler/inline/intel-s-mmx-instruction-set.md b/docs/assembler/inline/intel-s-mmx-instruction-set.md index d6957f0b1d..eb492df28d 100644 --- a/docs/assembler/inline/intel-s-mmx-instruction-set.md +++ b/docs/assembler/inline/intel-s-mmx-instruction-set.md @@ -1,11 +1,12 @@ --- -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/jumping-to-labels-in-inline-assembly.md b/docs/assembler/inline/jumping-to-labels-in-inline-assembly.md index 87e18c994f..6952971966 100644 --- a/docs/assembler/inline/jumping-to-labels-in-inline-assembly.md +++ b/docs/assembler/inline/jumping-to-labels-in-inline-assembly.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Jumping to Labels in Inline Assembly" title: "Jumping to Labels in Inline Assembly" ms.date: "08/30/2018" helpviewer_keywords: ["inline assembly, jumping to labels", "labels, in inline assembly", "__asm keyword [C++], labels", "case sensitivity, labels in inline assembly", "labels, in __asm blocks", "jumping to labels in inline assembly"] ms.assetid: 36c18b97-8981-4631-9dfd-af6c14a04297 +ms.topic: concept-article --- # Jumping to Labels in Inline Assembly diff --git a/docs/assembler/inline/masm-expressions-in-inline-assembly.md b/docs/assembler/inline/masm-expressions-in-inline-assembly.md index 99e43a96fa..59cf17282f 100644 --- a/docs/assembler/inline/masm-expressions-in-inline-assembly.md +++ b/docs/assembler/inline/masm-expressions-in-inline-assembly.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: MASM Expressions in Inline Assembly" title: "MASM Expressions in Inline Assembly" ms.date: "08/30/2018" helpviewer_keywords: ["expressions [C++], MASM", "expressions [C++], inline assembly", "inline assembly, MASM expressions", "MASM (Microsoft Macro Assembler), expressions"] 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 b3b82965c9..323a67036e 100644 --- a/docs/assembler/inline/masm-macro-directives-in-inline-assembly.md +++ b/docs/assembler/inline/masm-macro-directives-in-inline-assembly.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: MASM Macro Directives in Inline Assembly" title: "MASM Macro Directives in Inline Assembly" ms.date: "08/30/2018" helpviewer_keywords: ["directives, macros", "inline assembly, macro directives", "macros, directives", "MASM (Microsoft Macro Assembler), inline assembly macro directives"] @@ -8,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/optimizing-inline-assembly.md b/docs/assembler/inline/optimizing-inline-assembly.md index 0dc556eab7..7330cf7156 100644 --- a/docs/assembler/inline/optimizing-inline-assembly.md +++ b/docs/assembler/inline/optimizing-inline-assembly.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Optimizing Inline Assembly" title: "Optimizing Inline Assembly" ms.date: "08/30/2018" helpviewer_keywords: ["storage, optimizing in inline assembly", "optimization, inline assembly", "inline assembly, optimizing", "optimizing performance, inline assembly", "__asm keyword [C++], optimizing"] ms.assetid: 52a7ec83-9782-4d96-94c1-53bb2ac9e8c8 +ms.topic: concept-article --- # Optimizing Inline Assembly diff --git a/docs/assembler/inline/segment-references-in-inline-assembly.md b/docs/assembler/inline/segment-references-in-inline-assembly.md index e7c16c6df4..807453a33f 100644 --- a/docs/assembler/inline/segment-references-in-inline-assembly.md +++ b/docs/assembler/inline/segment-references-in-inline-assembly.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Segment References in Inline Assembly" title: "Segment References in Inline Assembly" ms.date: "08/30/2018" helpviewer_keywords: ["references, inline assembly", "segment references in inline assembly", "inline assembly, segment references", "registers", "inline assembly, registers", "registers, inline assembly"] diff --git a/docs/assembler/inline/type-and-variable-sizes-in-inline-assembly.md b/docs/assembler/inline/type-and-variable-sizes-in-inline-assembly.md index 6b21fdd0fe..f6dbd6e870 100644 --- a/docs/assembler/inline/type-and-variable-sizes-in-inline-assembly.md +++ b/docs/assembler/inline/type-and-variable-sizes-in-inline-assembly.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Type and Variable Sizes in Inline Assembly" title: "Type and Variable Sizes in Inline Assembly" ms.date: "08/30/2018" ms.topic: "reference" diff --git a/docs/assembler/inline/using-and-preserving-registers-in-inline-assembly.md b/docs/assembler/inline/using-and-preserving-registers-in-inline-assembly.md index 770a9a517b..b488b9fc60 100644 --- a/docs/assembler/inline/using-and-preserving-registers-in-inline-assembly.md +++ b/docs/assembler/inline/using-and-preserving-registers-in-inline-assembly.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Using and Preserving Registers in Inline Assembly" title: "Using and Preserving Registers in Inline Assembly" ms.date: "08/30/2018" helpviewer_keywords: ["__asm keyword [C++], register values", "inline assembly, registers", "registers, inline assembly", "preserving registers"] ms.assetid: dbcd7360-6f3e-4b22-9ee2-9f65ca6f2543 +ms.topic: concept-article --- # Using and Preserving Registers in Inline Assembly diff --git a/docs/assembler/inline/using-assembly-language-in-asm-blocks.md b/docs/assembler/inline/using-assembly-language-in-asm-blocks.md index 7dba755d3a..c2a33f53b5 100644 --- a/docs/assembler/inline/using-assembly-language-in-asm-blocks.md +++ b/docs/assembler/inline/using-assembly-language-in-asm-blocks.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Using Assembly Language in __asm Blocks" title: "Using Assembly Language in __asm Blocks" ms.date: "08/30/2018" helpviewer_keywords: ["assembly language [C++], features", "assembly language [C++]", "__asm keyword [C++], assembly language in"] ms.assetid: ad699356-1d16-4984-871f-c5fd7797c1fb +ms.topic: concept-article --- # Using Assembly Language in __asm Blocks diff --git a/docs/assembler/inline/using-c-or-cpp-in-asm-blocks.md b/docs/assembler/inline/using-c-or-cpp-in-asm-blocks.md index a5745d31e4..0a56b28c8f 100644 --- a/docs/assembler/inline/using-c-or-cpp-in-asm-blocks.md +++ b/docs/assembler/inline/using-c-or-cpp-in-asm-blocks.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Using C or C++ in __asm Blocks" title: "Using C or C++ in __asm Blocks" ms.date: "08/30/2018" helpviewer_keywords: ["inline assembly, mixing instructions with C/C++ statements", "symbols, in __asm blocks", "macros, __asm blocks", "preprocessor directives, used in __asm blocks", "type names, used in __asm blocks", "preprocessor directives", "preprocessor, directives", "constants, in __asm blocks", "comments, in __asm blocks", "typedef names, used in __asm blocks", "__asm keyword [C++], C/C++ elements in"] ms.assetid: ae8b2b52-6b75-42e3-ac0c-ad02d922ed97 +ms.topic: concept-article --- # Using C or C++ in __asm Blocks diff --git a/docs/assembler/inline/using-c-or-cpp-symbols-in-asm-blocks.md b/docs/assembler/inline/using-c-or-cpp-symbols-in-asm-blocks.md index 9ec91ba199..8dc38e5868 100644 --- a/docs/assembler/inline/using-c-or-cpp-symbols-in-asm-blocks.md +++ b/docs/assembler/inline/using-c-or-cpp-symbols-in-asm-blocks.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Using C or C++ Symbols in __asm Blocks" title: "Using C or C++ Symbols in __asm Blocks" ms.date: "08/30/2018" helpviewer_keywords: ["__asm keyword [C++], syntax", "symbols, in __asm blocks", "Visual C, symbols in __asm blocks", "__asm keyword [C++], C/C++ elements in", "Visual C++, in __asm blocks"] ms.assetid: 0758ffdc-dfe9-41c8-a5e1-fd395bcac328 +ms.topic: concept-article --- # Using C or C++ Symbols in __asm Blocks diff --git a/docs/assembler/inline/using-operators-in-asm-blocks.md b/docs/assembler/inline/using-operators-in-asm-blocks.md index e230a01bb0..b629032f99 100644 --- a/docs/assembler/inline/using-operators-in-asm-blocks.md +++ b/docs/assembler/inline/using-operators-in-asm-blocks.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Using Operators in __asm Blocks" title: "Using Operators in __asm Blocks" ms.date: "08/30/2018" helpviewer_keywords: ["brackets [ ]", "brackets [ ], __asm blocks", "__asm keyword [C++], operators", "square brackets [ ], __asm blocks", "operators [C++], using in __asm blocks", "square brackets [ ]"] ms.assetid: a26ccfd4-40ae-4a61-952f-c417982aa8dd +ms.topic: concept-article --- # Using Operators in __asm Blocks diff --git a/docs/assembler/inline/writing-functions-with-inline-assembly.md b/docs/assembler/inline/writing-functions-with-inline-assembly.md index 492bfe8688..d1082cff37 100644 --- a/docs/assembler/inline/writing-functions-with-inline-assembly.md +++ b/docs/assembler/inline/writing-functions-with-inline-assembly.md @@ -1,38 +1,47 @@ --- -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 +ms.topic: concept-article --- -# 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 @@ -66,10 +75,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/alias-masm.md b/docs/assembler/masm/alias-masm.md index 5a00d05d1f..e1d6bc49b7 100644 --- a/docs/assembler/masm/alias-masm.md +++ b/docs/assembler/masm/alias-masm.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ALIAS" title: "ALIAS (MASM)" ms.date: "12/17/2019" f1_keywords: ["Alias"] diff --git a/docs/assembler/masm/align-masm.md b/docs/assembler/masm/align-masm.md index c747ac0315..433270bcf3 100644 --- a/docs/assembler/masm/align-masm.md +++ b/docs/assembler/masm/align-masm.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ALIGN" title: "ALIGN (MASM)" ms.date: "12/17/2019" f1_keywords: ["align"] diff --git a/docs/assembler/masm/assume.md b/docs/assembler/masm/assume.md index d737faacab..78516979a1 100644 --- a/docs/assembler/masm/assume.md +++ b/docs/assembler/masm/assume.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ASSUME" title: "ASSUME" ms.date: "11/05/2019" f1_keywords: ["ASSUME"] diff --git a/docs/assembler/masm/at-at.md b/docs/assembler/masm/at-at.md index 2106bdf233..0dcf9cac95 100644 --- a/docs/assembler/masm/at-at.md +++ b/docs/assembler/masm/at-at.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: @@:" title: "@@:" ms.date: "12/17/2019" f1_keywords: ["@@:"] diff --git a/docs/assembler/masm/at-b.md b/docs/assembler/masm/at-b.md index 69d5ffd640..1bf4336248 100644 --- a/docs/assembler/masm/at-b.md +++ b/docs/assembler/masm/at-b.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: @B" title: "@B" ms.date: "12/17/2019" f1_keywords: ["@B"] diff --git a/docs/assembler/masm/at-catstr.md b/docs/assembler/masm/at-catstr.md index 76e37e914c..12ab4de6e4 100644 --- a/docs/assembler/masm/at-catstr.md +++ b/docs/assembler/masm/at-catstr.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: @CatStr" title: "@CatStr" ms.date: "12/17/2019" f1_keywords: ["@CatStr"] diff --git a/docs/assembler/masm/at-code.md b/docs/assembler/masm/at-code.md index bbcb648909..8d6fd81529 100644 --- a/docs/assembler/masm/at-code.md +++ b/docs/assembler/masm/at-code.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: @code" title: "@code" ms.date: "12/17/2019" f1_keywords: ["@code"] diff --git a/docs/assembler/masm/at-codesize.md b/docs/assembler/masm/at-codesize.md index e85a49aa63..bee5c85a23 100644 --- a/docs/assembler/masm/at-codesize.md +++ b/docs/assembler/masm/at-codesize.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: @CodeSize" title: "@CodeSize" ms.date: "11/21/2019" f1_keywords: ["@CodeSize"] diff --git a/docs/assembler/masm/at-cpu.md b/docs/assembler/masm/at-cpu.md index f281916613..46a3e4c90a 100644 --- a/docs/assembler/masm/at-cpu.md +++ b/docs/assembler/masm/at-cpu.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: @Cpu" title: "@Cpu" ms.date: "12/17/2019" f1_keywords: ["@Cpu"] diff --git a/docs/assembler/masm/at-curseg.md b/docs/assembler/masm/at-curseg.md index a232e162f6..c571409169 100644 --- a/docs/assembler/masm/at-curseg.md +++ b/docs/assembler/masm/at-curseg.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: @CurSeg" title: "@CurSeg" ms.date: "12/17/2019" f1_keywords: ["@CurSeg"] diff --git a/docs/assembler/masm/at-data.md b/docs/assembler/masm/at-data.md index 7ff06cfcfe..9c074d6ccc 100644 --- a/docs/assembler/masm/at-data.md +++ b/docs/assembler/masm/at-data.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: @data" title: "@data" ms.date: "12/17/2019" f1_keywords: ["@data"] diff --git a/docs/assembler/masm/at-datasize.md b/docs/assembler/masm/at-datasize.md index 94842ee0b0..b70bca6ced 100644 --- a/docs/assembler/masm/at-datasize.md +++ b/docs/assembler/masm/at-datasize.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: @DataSize" title: "@DataSize" ms.date: "12/17/2019" f1_keywords: ["@DataSize"] diff --git a/docs/assembler/masm/at-date.md b/docs/assembler/masm/at-date.md index 1e93f81f8f..2cccf9486e 100644 --- a/docs/assembler/masm/at-date.md +++ b/docs/assembler/masm/at-date.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: @Date" title: "@Date" ms.date: "12/17/2019" f1_keywords: ["@Date"] diff --git a/docs/assembler/masm/at-environ.md b/docs/assembler/masm/at-environ.md index 471e846b91..16f56a3d3d 100644 --- a/docs/assembler/masm/at-environ.md +++ b/docs/assembler/masm/at-environ.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: @Environ" title: "@Environ" ms.date: "12/17/2019" f1_keywords: ["@Environ"] diff --git a/docs/assembler/masm/at-f.md b/docs/assembler/masm/at-f.md index 6515fafe90..e6353e29a7 100644 --- a/docs/assembler/masm/at-f.md +++ b/docs/assembler/masm/at-f.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: @F" title: "@F" ms.date: "12/17/2019" f1_keywords: ["@F"] diff --git a/docs/assembler/masm/at-fardata-q.md b/docs/assembler/masm/at-fardata-q.md index d11d44469f..4a5d8f5f5f 100644 --- a/docs/assembler/masm/at-fardata-q.md +++ b/docs/assembler/masm/at-fardata-q.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: @fardata?" title: "@fardata?" ms.date: "12/17/2019" f1_keywords: ["@fardata?"] diff --git a/docs/assembler/masm/at-fardata.md b/docs/assembler/masm/at-fardata.md index e1cb845c67..07e4f11cd0 100644 --- a/docs/assembler/masm/at-fardata.md +++ b/docs/assembler/masm/at-fardata.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: @fardata" title: "@fardata" ms.date: "12/17/2019" f1_keywords: ["@fardata"] diff --git a/docs/assembler/masm/at-filecur.md b/docs/assembler/masm/at-filecur.md index 828cca07a2..2f6a4cf0a6 100644 --- a/docs/assembler/masm/at-filecur.md +++ b/docs/assembler/masm/at-filecur.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: @FileCur" title: "@FileCur" ms.date: "12/17/2019" f1_keywords: ["@FileCur"] diff --git a/docs/assembler/masm/at-filename.md b/docs/assembler/masm/at-filename.md index ea902b8024..458c2983e6 100644 --- a/docs/assembler/masm/at-filename.md +++ b/docs/assembler/masm/at-filename.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: @FileName" title: "@FileName" ms.date: "12/17/2019" f1_keywords: ["@FileName"] diff --git a/docs/assembler/masm/at-instr.md b/docs/assembler/masm/at-instr.md index 80d9d5e436..76770a7466 100644 --- a/docs/assembler/masm/at-instr.md +++ b/docs/assembler/masm/at-instr.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: @InStr" title: "@InStr" ms.date: "12/17/2019" f1_keywords: ["@InStr"] diff --git a/docs/assembler/masm/at-interface.md b/docs/assembler/masm/at-interface.md index af5eab2aa2..92f1fa4d66 100644 --- a/docs/assembler/masm/at-interface.md +++ b/docs/assembler/masm/at-interface.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: @Interface" title: "@Interface" ms.date: "12/17/2019" f1_keywords: ["@Interface"] diff --git a/docs/assembler/masm/at-line.md b/docs/assembler/masm/at-line.md index e907328655..d09079a78e 100644 --- a/docs/assembler/masm/at-line.md +++ b/docs/assembler/masm/at-line.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: @Line" title: "@Line" ms.date: "12/17/2019" f1_keywords: ["@Line"] diff --git a/docs/assembler/masm/at-model.md b/docs/assembler/masm/at-model.md index cf59240a8e..e9d65b8ac9 100644 --- a/docs/assembler/masm/at-model.md +++ b/docs/assembler/masm/at-model.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: @Model" title: "@Model" ms.date: "12/17/2019" f1_keywords: ["@Model"] diff --git a/docs/assembler/masm/at-sizestr.md b/docs/assembler/masm/at-sizestr.md index 04b128e07d..b3aacf4b7c 100644 --- a/docs/assembler/masm/at-sizestr.md +++ b/docs/assembler/masm/at-sizestr.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: @SizeStr" title: "@SizeStr" ms.date: "12/17/2019" f1_keywords: ["@SizeStr"] diff --git a/docs/assembler/masm/at-stack.md b/docs/assembler/masm/at-stack.md index 09aef4a532..762e72cd1e 100644 --- a/docs/assembler/masm/at-stack.md +++ b/docs/assembler/masm/at-stack.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: @stack" title: "@stack" ms.date: "12/17/2019" f1_keywords: ["@stack"] diff --git a/docs/assembler/masm/at-substr.md b/docs/assembler/masm/at-substr.md index 00c8b76567..f54e6f4eed 100644 --- a/docs/assembler/masm/at-substr.md +++ b/docs/assembler/masm/at-substr.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: @SubStr" title: "@SubStr" ms.date: "12/17/2019" f1_keywords: ["@SubStr"] diff --git a/docs/assembler/masm/at-time.md b/docs/assembler/masm/at-time.md index 2924f80d33..2e2995e143 100644 --- a/docs/assembler/masm/at-time.md +++ b/docs/assembler/masm/at-time.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: @Time" title: "@Time" ms.date: "12/17/2019" f1_keywords: ["@Time"] diff --git a/docs/assembler/masm/at-version.md b/docs/assembler/masm/at-version.md index e00766ea6b..692b6c96af 100644 --- a/docs/assembler/masm/at-version.md +++ b/docs/assembler/masm/at-version.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: @Version" title: "@Version" ms.date: "12/17/2019" f1_keywords: ["@Version"] diff --git a/docs/assembler/masm/at-wordsize.md b/docs/assembler/masm/at-wordsize.md index eb125ec847..9db1e69b6f 100644 --- a/docs/assembler/masm/at-wordsize.md +++ b/docs/assembler/masm/at-wordsize.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: @WordSize" title: "@WordSize" ms.date: "12/17/2019" f1_keywords: ["@WordSize"] diff --git a/docs/assembler/masm/byte-masm.md b/docs/assembler/masm/byte-masm.md index 45b9e1a0be..b02941c5cf 100644 --- a/docs/assembler/masm/byte-masm.md +++ b/docs/assembler/masm/byte-masm.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: BYTE" title: "BYTE (MASM)" ms.date: "12/17/2019" f1_keywords: ["byte"] diff --git a/docs/assembler/masm/catstr.md b/docs/assembler/masm/catstr.md index 799348a4c5..2afdee21c6 100644 --- a/docs/assembler/masm/catstr.md +++ b/docs/assembler/masm/catstr.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CATSTR" title: "CATSTR" ms.date: "12/17/2019" f1_keywords: ["CATSTR"] diff --git a/docs/assembler/masm/comm.md b/docs/assembler/masm/comm.md index 3e68711814..51364649cc 100644 --- a/docs/assembler/masm/comm.md +++ b/docs/assembler/masm/comm.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: COMM" title: "COMM" ms.date: "12/06/2019" f1_keywords: ["COMM"] diff --git a/docs/assembler/masm/comment-masm.md b/docs/assembler/masm/comment-masm.md index 2cc1e61c81..822bca1448 100644 --- a/docs/assembler/masm/comment-masm.md +++ b/docs/assembler/masm/comment-masm.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: COMMENT" title: "COMMENT (MASM)" ms.date: "12/17/2019" f1_keywords: ["Comment"] diff --git a/docs/assembler/masm/db.md b/docs/assembler/masm/db.md index 1ae16274ad..0648326174 100644 --- a/docs/assembler/masm/db.md +++ b/docs/assembler/masm/db.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: DB" title: "DB" ms.date: "12/17/2019" f1_keywords: ["DB"] diff --git a/docs/assembler/masm/dd.md b/docs/assembler/masm/dd.md index b76c7b92cb..2d8c039db7 100644 --- a/docs/assembler/masm/dd.md +++ b/docs/assembler/masm/dd.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: DD" title: "DD" ms.date: "12/17/2019" f1_keywords: ["dd"] diff --git a/docs/assembler/masm/df.md b/docs/assembler/masm/df.md index d65b52f278..9628effe71 100644 --- a/docs/assembler/masm/df.md +++ b/docs/assembler/masm/df.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: DF" title: "DF" ms.date: "12/17/2019" f1_keywords: ["DF"] diff --git a/docs/assembler/masm/directives-reference.md b/docs/assembler/masm/directives-reference.md index 3a2b41e0f2..c9f7208c7d 100644 --- a/docs/assembler/masm/directives-reference.md +++ b/docs/assembler/masm/directives-reference.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Directives Reference" title: "Directives Reference" ms.date: 07/15/2020 f1_keywords: ["Directives Reference"] @@ -11,13 +12,18 @@ ms.assetid: da6efcd1-18f7-41de-81cd-a002a02f9a22 :::row::: :::column span=""::: - [`.ALLOCSTACK`](dot-allocstack.md)
[`.ENDPROLOG`](dot-endprolog.md)
[`PROC`](proc.md) + [`.ALLOCSTACK`](dot-allocstack.md)\ + [`.ENDPROLOG`](dot-endprolog.md)\ + [`PROC`](proc.md) :::column-end::: :::column span=""::: - [`.PUSHFRAME`](dot-pushframe.md)
[`.PUSHREG`](dot-pushreg.md)
[`.SAVEREG`](dot-savereg.md) + [`.PUSHFRAME`](dot-pushframe.md)\ + [`.PUSHREG`](dot-pushreg.md)\ + [`.SAVEREG`](dot-savereg.md) :::column-end::: :::column span=""::: - [`.SAVEXMM128`](dot-savexmm128.md)
[`.SETFRAME`](dot-setframe.md) + [`.SAVEXMM128`](dot-savexmm128.md)\ + [`.SETFRAME`](dot-setframe.md) :::column-end::: :::row-end::: @@ -25,7 +31,8 @@ ms.assetid: da6efcd1-18f7-41de-81cd-a002a02f9a22 :::row::: :::column span=""::: - [`ALIGN`](align-masm.md)
[`EVEN`](even.md) + [`ALIGN`](align-masm.md)\ + [`EVEN`](even.md) :::column-end::: :::column span=""::: [`LABEL`](label-masm.md) @@ -39,13 +46,24 @@ ms.assetid: da6efcd1-18f7-41de-81cd-a002a02f9a22 :::row::: :::column span=""::: - [`ELSE`](else-masm.md)
[`ELSEIF`](elseif-masm.md)
[`ELSEIF2`](elseif2.md)
[`IF`](if-masm.md)
[`IF2`](if2.md) + [`ELSE`](else-masm.md)\ + [`ELSEIF`](elseif-masm.md)\ + [`ELSEIF2`](elseif2.md)\ + [`IF`](if-masm.md)\ + [`IF2`](if2.md) :::column-end::: :::column span=""::: - [`IFB`](ifb.md)
[`IFNB`](ifnb.md)
[`IFDEF`](ifdef.md)
[`IFNDEF`](ifndef.md)
[`IFDIF`](ifdif.md) + [`IFB`](ifb.md)\ + [`IFNB`](ifnb.md)\ + [`IFDEF`](ifdef.md)\ + [`IFNDEF`](ifndef.md)\ + [`IFDIF`](ifdif.md) :::column-end::: :::column span=""::: - [`IFDIFI`](ifdif.md)
[`IFE`](ife.md)
[`IFIDN`](ifidn.md)
[`IFIDNI`](ifidn.md) + [`IFDIFI`](ifdif.md)\ + [`IFE`](ife.md)\ + [`IFIDN`](ifidn.md)\ + [`IFIDNI`](ifidn.md) :::column-end::: :::row-end::: @@ -53,13 +71,21 @@ ms.assetid: da6efcd1-18f7-41de-81cd-a002a02f9a22 :::row::: :::column span=""::: - [`.BREAK`](dot-break.md)
[`.CONTINUE`](dot-continue.md)
[`.ELSE`](dot-else.md)
[`.ELSEIF`](dot-if.md) + [`.BREAK`](dot-break.md)\ + [`.CONTINUE`](dot-continue.md)\ + [`.ELSE`](dot-else.md)\ + [`.ELSEIF`](dot-if.md) :::column-end::: :::column span=""::: - [`.ENDIF`](dot-endif.md)
[`.ENDW`](dot-endw.md)
[`.IF`](dot-if.md)
[`.REPEAT`](dot-repeat.md) + [`.ENDIF`](dot-endif.md)\ + [`.ENDW`](dot-endw.md)\ + [`.IF`](dot-if.md)\ + [`.REPEAT`](dot-repeat.md) :::column-end::: :::column span=""::: - [`.UNTIL`](dot-until.md)
[`.UNTILCXZ`](dot-untilcxz.md)
[`.WHILE`](dot-while.md) + [`.UNTIL`](dot-until.md)\ + [`.UNTILCXZ`](dot-untilcxz.md)\ + [`.WHILE`](dot-while.md) :::column-end::: :::row-end::: @@ -67,13 +93,22 @@ ms.assetid: da6efcd1-18f7-41de-81cd-a002a02f9a22 :::row::: :::column span=""::: - [`.ERR`](dot-err.md)
[`.ERR2`](dot-err2.md)
[`.ERRB`](dot-errb.md)
[`.ERRDEF`](dot-errdef.md) + [`.ERR`](dot-err.md)\ + [`.ERR2`](dot-err2.md)\ + [`.ERRB`](dot-errb.md)\ + [`.ERRDEF`](dot-errdef.md) :::column-end::: :::column span=""::: - [`.ERRDIF`](dot-errdif.md)
[`.ERRDIFI`](dot-errdif.md)
[`.ERRE`](dot-erre.md)
[`.ERRIDN`](dot-erridn.md) + [`.ERRDIF`](dot-errdif.md)\ + [`.ERRDIFI`](dot-errdif.md)\ + [`.ERRE`](dot-erre.md)\ + [`.ERRIDN`](dot-erridn.md) :::column-end::: :::column span=""::: - [`.ERRIDNI`](dot-erridn.md)
[`.ERRNB`](dot-errnb.md)
[`.ERRNDEF`](dot-errndef.md)
[`.ERRNZ`](dot-errnz.md) + [`.ERRIDNI`](dot-erridn.md)\ + [`.ERRNB`](dot-errnb.md)\ + [`.ERRNDEF`](dot-errndef.md)\ + [`.ERRNZ`](dot-errnz.md) :::column-end::: :::row-end::: @@ -81,13 +116,26 @@ ms.assetid: da6efcd1-18f7-41de-81cd-a002a02f9a22 :::row::: :::column span=""::: - [`ALIGN`](align-masm.md)
[`BYTE`](byte-masm.md)
[`SBYTE`](sbyte-masm.md)
[`DWORD`](dword.md)
[`SDWORD`](sdword.md)
[`EVEN`](even.md) + [`ALIGN`](align-masm.md)\ + [`BYTE`](byte-masm.md)\ + [`SBYTE`](sbyte-masm.md)\ + [`DWORD`](dword.md)\ + [`SDWORD`](sdword.md)\ + [`EVEN`](even.md) :::column-end::: :::column span=""::: - [`FWORD`](fword.md)
[`LABEL`](label-masm.md)
[`ORG`](org.md)
[`QWORD`](qword.md)
[`REAL4`](real4.md) + [`FWORD`](fword.md)\ + [`LABEL`](label-masm.md)\ + [`ORG`](org.md)\ + [`QWORD`](qword.md)\ + [`REAL4`](real4.md) :::column-end::: :::column span=""::: - [`REAL8`](real8.md)
[`REAL10`](real10.md)
[`TBYTE`](tbyte.md)
[`WORD`](word.md)
[`SWORD`](sword.md) + [`REAL8`](real8.md)\ + [`REAL10`](real10.md)\ + [`TBYTE`](tbyte.md)\ + [`WORD`](word.md)\ + [`SWORD`](sword.md) :::column-end::: :::row-end::: @@ -109,13 +157,24 @@ ms.assetid: da6efcd1-18f7-41de-81cd-a002a02f9a22 :::row::: :::column span=""::: - [`.CREF`](dot-cref.md)
[`.LIST`](dot-list.md)
[`.LISTALL`](dot-listall.md)
[`.LISTIF`](dot-listif.md)
[`.LISTMACRO`](dot-listmacro.md) + [`.CREF`](dot-cref.md)\ + [`.LIST`](dot-list.md)\ + [`.LISTALL`](dot-listall.md)\ + [`.LISTIF`](dot-listif.md)\ + [`.LISTMACRO`](dot-listmacro.md) :::column-end::: :::column span=""::: - [`.LISTMACROALL`](dot-listmacroall.md)
[`.NOCREF`](dot-nocref.md)
[`.NOLIST`](dot-nolist.md)
[`.NOLISTIF`](dot-nolistif.md)
[`.NOLISTMACRO`](dot-nolistmacro.md) + [`.LISTMACROALL`](dot-listmacroall.md)\ + [`.NOCREF`](dot-nocref.md)\ + [`.NOLIST`](dot-nolist.md)\ + [`.NOLISTIF`](dot-nolistif.md)\ + [`.NOLISTMACRO`](dot-nolistmacro.md) :::column-end::: :::column span=""::: - [`PAGE`](page.md)
[`SUBTITLE`](subtitle.md)
[`.TFCOND`](dot-tfcond.md)
[`TITLE`](title.md) + [`PAGE`](page.md)\ + [`SUBTITLE`](subtitle.md)\ + [`.TFCOND`](dot-tfcond.md)\ + [`TITLE`](title.md) :::column-end::: :::row-end::: @@ -123,29 +182,43 @@ ms.assetid: da6efcd1-18f7-41de-81cd-a002a02f9a22 :::row::: :::column span=""::: - [`ENDM`](endm.md)
[`EXITM`](exitm.md) + [`ENDM`](endm.md)\ + [`EXITM`](exitm.md) :::column-end::: :::column span=""::: - [`GOTO`](goto-masm.md)
[`LOCAL`](local-masm.md) + [`GOTO`](goto-masm.md)\ + [`LOCAL`](local-masm.md) :::column-end::: :::column span=""::: - [`MACRO`](macro.md)
[`PURGE`](purge.md) + [`MACRO`](macro.md)\ + [`PURGE`](purge.md) :::column-end::: :::row-end::: -

- ## Miscellaneous :::row::: :::column span=""::: - [`ALIAS`](alias-masm.md)
[`ASSUME`](assume.md)
[`COMMENT`](comment-masm.md)
[`ECHO`](echo.md)
[`END`](end-masm.md)
[`.FPO`](dot-fpo.md) + [`ALIAS`](alias-masm.md)\ + [`ASSUME`](assume.md)\ + [`COMMENT`](comment-masm.md)\ + [`ECHO`](echo.md)\ + [`END`](end-masm.md)\ + [`.FPO`](dot-fpo.md) :::column-end::: :::column span=""::: - [`INCLUDE`](include-masm.md)
[`INCLUDELIB`](includelib-masm.md)
[`MMWORD`](mmword.md)
[`OPTION`](option-masm.md)
[`POPCONTEXT`](popcontext.md) + [`INCLUDE`](include-masm.md)\ + [`INCLUDELIB`](includelib-masm.md)\ + [`MMWORD`](mmword.md)\ + [`OPTION`](option-masm.md)\ + [`POPCONTEXT`](popcontext.md) :::column-end::: :::column span=""::: - [`PUSHCONTEXT`](pushcontext.md)
[`.RADIX`](dot-radix.md)
[`.SAFESEH`](dot-safeseh.md)
[`XMMWORD`](xmmword.md)
[`YMMWORD`](ymmword.md) + [`PUSHCONTEXT`](pushcontext.md)\ + [`.RADIX`](dot-radix.md)\ + [`.SAFESEH`](dot-safeseh.md)\ + [`XMMWORD`](xmmword.md)\ + [`YMMWORD`](ymmword.md) :::column-end::: :::row-end::: @@ -153,7 +226,8 @@ ms.assetid: da6efcd1-18f7-41de-81cd-a002a02f9a22 :::row::: :::column span=""::: - [`ENDP`](endp.md)
[`INVOKE`](invoke.md) + [`ENDP`](endp.md)\ + [`INVOKE`](invoke.md) :::column-end::: :::column span=""::: [`PROC`](proc.md) @@ -167,13 +241,22 @@ ms.assetid: da6efcd1-18f7-41de-81cd-a002a02f9a22 :::row::: :::column span=""::: - [`.386`](dot-386.md)
[`.386P`](dot-386p.md)
[`.387`](dot-387.md)
[`.486`](dot-486.md) + [`.386`](dot-386.md)\ + [`.386P`](dot-386p.md)\ + [`.387`](dot-387.md)\ + [`.486`](dot-486.md) :::column-end::: :::column span=""::: - [`.486P`](dot-486p.md)
[`.586`](dot-586.md)
[`.586P`](dot-586p.md)
[`.686`](dot-686.md) + [`.486P`](dot-486p.md)\ + [`.586`](dot-586.md)\ + [`.586P`](dot-586p.md)\ + [`.686`](dot-686.md) :::column-end::: :::column span=""::: - [`.686P`](dot-686p.md)
[`.K3D`](dot-k3d.md)
[`.MMX`](dot-mmx.md)
[`.XMM`](dot-xmm.md) + [`.686P`](dot-686p.md)\ + [`.K3D`](dot-k3d.md)\ + [`.MMX`](dot-mmx.md)\ + [`.XMM`](dot-xmm.md) :::column-end::: :::row-end::: @@ -181,13 +264,16 @@ ms.assetid: da6efcd1-18f7-41de-81cd-a002a02f9a22 :::row::: :::column span=""::: - [`ENDM`](endm.md)
[`FOR`](for-masm.md) + [`ENDM`](endm.md)\ + [`FOR`](for-masm.md) :::column-end::: :::column span=""::: - [`FORC`](forc.md)
[`GOTO`](goto-masm.md) + [`FORC`](forc.md)\ + [`GOTO`](goto-masm.md) :::column-end::: :::column span=""::: - [`REPEAT`](repeat.md)
[`WHILE`](while-masm.md) + [`REPEAT`](repeat.md)\ + [`WHILE`](while-masm.md) :::column-end::: :::row-end::: @@ -195,10 +281,12 @@ ms.assetid: da6efcd1-18f7-41de-81cd-a002a02f9a22 :::row::: :::column span=""::: - [`COMM`](comm.md)
[`EXTERN`](extern-masm.md) + [`COMM`](comm.md)\ + [`EXTERN`](extern-masm.md) :::column-end::: :::column span=""::: - [`EXTERNDEF`](externdef.md)
[`INCLUDELIB`](includelib-masm.md) + [`EXTERNDEF`](externdef.md)\ + [`INCLUDELIB`](includelib-masm.md) :::column-end::: :::column span=""::: [`PUBLIC`](public-masm.md) @@ -209,13 +297,18 @@ ms.assetid: da6efcd1-18f7-41de-81cd-a002a02f9a22 :::row::: :::column span=""::: - [`.ALPHA`](dot-alpha.md)
[`ASSUME`](assume.md)
[`.DOSSEG`](dot-dosseg.md) + [`.ALPHA`](dot-alpha.md)\ + [`ASSUME`](assume.md)\ + [`.DOSSEG`](dot-dosseg.md) :::column-end::: :::column span=""::: - [`END`](end-masm.md)
[`ENDS`](ends-masm.md)
[`GROUP`](group.md) + [`END`](end-masm.md)\ + [`ENDS`](ends-masm.md)\ + [`GROUP`](group.md) :::column-end::: :::column span=""::: - [`SEGMENT`](segment.md)
[`.SEQ`](dot-seq.md) + [`SEGMENT`](segment.md)\ + [`.SEQ`](dot-seq.md) :::column-end::: :::row-end::: @@ -223,13 +316,21 @@ ms.assetid: da6efcd1-18f7-41de-81cd-a002a02f9a22 :::row::: :::column span=""::: - [`.CODE`](dot-code.md)
[`.CONST`](dot-const.md)
[`.DATA`](dot-data.md)
[`.DATA?`](dot-data-q.md) + [`.CODE`](dot-code.md)\ + [`.CONST`](dot-const.md)\ + [`.DATA`](dot-data.md)\ + [`.DATA?`](dot-data-q.md) :::column-end::: :::column span=""::: - [`.DOSSEG`](dot-dosseg.md)
[`.EXIT`](dot-exit.md)
[`.FARDATA`](dot-fardata.md)
[`.FARDATA?`](dot-fardata-q.md) + [`.DOSSEG`](dot-dosseg.md)\ + [`.EXIT`](dot-exit.md)\ + [`.FARDATA`](dot-fardata.md)\ + [`.FARDATA?`](dot-fardata-q.md) :::column-end::: :::column span=""::: - [`.MODEL`](dot-model.md)
[`.STACK`](dot-stack.md)
[`.STARTUP`](dot-startup.md) + [`.MODEL`](dot-model.md)\ + [`.STACK`](dot-stack.md)\ + [`.STARTUP`](dot-startup.md) :::column-end::: :::row-end::: @@ -237,7 +338,8 @@ ms.assetid: da6efcd1-18f7-41de-81cd-a002a02f9a22 :::row::: :::column span=""::: - [`CATSTR`](catstr.md)
[`INSTR`](instr.md) + [`CATSTR`](catstr.md)\ + [`INSTR`](instr.md) :::column-end::: :::column span=""::: [`SIZESTR`](sizestr.md) @@ -251,10 +353,12 @@ ms.assetid: da6efcd1-18f7-41de-81cd-a002a02f9a22 :::row::: :::column span=""::: - [`ENDS`](ends-masm.md)
[`RECORD`](record-masm.md) + [`ENDS`](ends-masm.md)\ + [`RECORD`](record-masm.md) :::column-end::: :::column span=""::: - [`STRUCT`](struct-masm.md)
[`TYPEDEF`](typedef-masm.md) + [`STRUCT`](struct-masm.md)\ + [`TYPEDEF`](typedef-masm.md) :::column-end::: :::column span=""::: [`UNION`](union.md) diff --git a/docs/assembler/masm/dollar.md b/docs/assembler/masm/dollar.md index 4f9de0f6a7..b9d356c40c 100644 --- a/docs/assembler/masm/dollar.md +++ b/docs/assembler/masm/dollar.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: $" title: "$" ms.date: "12/17/2019" f1_keywords: ["$"] diff --git a/docs/assembler/masm/dosseg.md b/docs/assembler/masm/dosseg.md index d8cc6437d8..95f4f18a78 100644 --- a/docs/assembler/masm/dosseg.md +++ b/docs/assembler/masm/dosseg.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: DOSSEG" title: "DOSSEG" ms.date: "12/17/2019" f1_keywords: ["DOSSEG"] diff --git a/docs/assembler/masm/dot-386.md b/docs/assembler/masm/dot-386.md index aed5b9a4f5..b4dbcf437b 100644 --- a/docs/assembler/masm/dot-386.md +++ b/docs/assembler/masm/dot-386.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .386 (32-bit MASM)" title: ".386" ms.date: "11/05/2019" f1_keywords: [".386"] diff --git a/docs/assembler/masm/dot-386p.md b/docs/assembler/masm/dot-386p.md index e4cb896cf0..3029ae40f4 100644 --- a/docs/assembler/masm/dot-386p.md +++ b/docs/assembler/masm/dot-386p.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .386P (32-bit MASM)" title: ".386P" ms.date: "11/05/2019" f1_keywords: [".386P"] diff --git a/docs/assembler/masm/dot-387.md b/docs/assembler/masm/dot-387.md index 049950aa1c..151a50c1a1 100644 --- a/docs/assembler/masm/dot-387.md +++ b/docs/assembler/masm/dot-387.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .387 (32-bit MASM)" title: ".387" ms.date: "11/05/2019" f1_keywords: [".387"] diff --git a/docs/assembler/masm/dot-486.md b/docs/assembler/masm/dot-486.md index 1ef0298466..2b21fb85ea 100644 --- a/docs/assembler/masm/dot-486.md +++ b/docs/assembler/masm/dot-486.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .486 (32-bit MASM)" title: ".486" ms.date: "11/05/2019" f1_keywords: [".486"] diff --git a/docs/assembler/masm/dot-486p.md b/docs/assembler/masm/dot-486p.md index 58a2fca05b..d5dbb4ce79 100644 --- a/docs/assembler/masm/dot-486p.md +++ b/docs/assembler/masm/dot-486p.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .486P (32-bit MASM)" title: ".486P" ms.date: "11/05/2019" f1_keywords: [".486P"] diff --git a/docs/assembler/masm/dot-586.md b/docs/assembler/masm/dot-586.md index 98f5054039..6a513ad3d6 100644 --- a/docs/assembler/masm/dot-586.md +++ b/docs/assembler/masm/dot-586.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .586 (32-bit MASM)" title: ".586" ms.date: "11/05/2019" f1_keywords: [".586"] diff --git a/docs/assembler/masm/dot-586p.md b/docs/assembler/masm/dot-586p.md index 3ac54e4e9c..503781846a 100644 --- a/docs/assembler/masm/dot-586p.md +++ b/docs/assembler/masm/dot-586p.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .586P (32-bit MASM)" title: ".586P" ms.date: "11/05/2019" f1_keywords: [".586P"] diff --git a/docs/assembler/masm/dot-686.md b/docs/assembler/masm/dot-686.md index a556cc4d1e..d4786a4a06 100644 --- a/docs/assembler/masm/dot-686.md +++ b/docs/assembler/masm/dot-686.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .686 (32-bit MASM)" title: ".686" ms.date: "11/05/2019" f1_keywords: [".686"] diff --git a/docs/assembler/masm/dot-686p.md b/docs/assembler/masm/dot-686p.md index f70e50193a..6587e32bda 100644 --- a/docs/assembler/masm/dot-686p.md +++ b/docs/assembler/masm/dot-686p.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .686P (32-bit MASM)" title: ".686P" ms.date: "11/05/2019" f1_keywords: [".686P"] diff --git a/docs/assembler/masm/dot-allocstack.md b/docs/assembler/masm/dot-allocstack.md index b66e23edc0..13c5e6e114 100644 --- a/docs/assembler/masm/dot-allocstack.md +++ b/docs/assembler/masm/dot-allocstack.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .ALLOCSTACK" title: ".ALLOCSTACK" ms.date: "12/17/2019" f1_keywords: [".ALLOCSTACK"] diff --git a/docs/assembler/masm/dot-alpha.md b/docs/assembler/masm/dot-alpha.md index eec49aea1f..a47dff05c7 100644 --- a/docs/assembler/masm/dot-alpha.md +++ b/docs/assembler/masm/dot-alpha.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .ALPHA (32-bit MASM)" title: ".ALPHA" ms.date: "11/05/2019" f1_keywords: [".ALPHA"] diff --git a/docs/assembler/masm/dot-break.md b/docs/assembler/masm/dot-break.md index 09538b7cd9..d801b4ce75 100644 --- a/docs/assembler/masm/dot-break.md +++ b/docs/assembler/masm/dot-break.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .BREAK (32-bit MASM)" title: ".BREAK" ms.date: "11/05/2019" f1_keywords: [".BREAK"] diff --git a/docs/assembler/masm/dot-code.md b/docs/assembler/masm/dot-code.md index b724dbbca8..9bf447e91b 100644 --- a/docs/assembler/masm/dot-code.md +++ b/docs/assembler/masm/dot-code.md @@ -1,19 +1,21 @@ --- 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-const.md b/docs/assembler/masm/dot-const.md index f674ddb4e5..fb5f2b58d6 100644 --- a/docs/assembler/masm/dot-const.md +++ b/docs/assembler/masm/dot-const.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .CONST (32-bit MASM)" title: ".CONST" ms.date: "12/17/2019" f1_keywords: [".CONST"] diff --git a/docs/assembler/masm/dot-continue.md b/docs/assembler/masm/dot-continue.md index dcf49b1cf0..77e7a22a3a 100644 --- a/docs/assembler/masm/dot-continue.md +++ b/docs/assembler/masm/dot-continue.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .CONTINUE (32-bit MASM)" title: ".CONTINUE" ms.date: "11/05/2019" f1_keywords: [".CONTINUE"] diff --git a/docs/assembler/masm/dot-cref.md b/docs/assembler/masm/dot-cref.md index b6c10fd8e8..f289c83950 100644 --- a/docs/assembler/masm/dot-cref.md +++ b/docs/assembler/masm/dot-cref.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .CREF" title: ".CREF" ms.date: "12/17/2019" f1_keywords: [".CREF"] diff --git a/docs/assembler/masm/dot-data-q.md b/docs/assembler/masm/dot-data-q.md index b5479a5039..d033a01c4a 100644 --- a/docs/assembler/masm/dot-data-q.md +++ b/docs/assembler/masm/dot-data-q.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .DATA?" title: ".DATA?" ms.date: "12/17/2019" f1_keywords: [".DATA?"] diff --git a/docs/assembler/masm/dot-data.md b/docs/assembler/masm/dot-data.md index 1aa6881a8e..c36eb3fee1 100644 --- a/docs/assembler/masm/dot-data.md +++ b/docs/assembler/masm/dot-data.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .DATA" title: ".DATA" ms.date: "12/17/2019" f1_keywords: [".DATA"] @@ -7,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-dosseg.md b/docs/assembler/masm/dot-dosseg.md index 3382d6a5ee..13f0330bbc 100644 --- a/docs/assembler/masm/dot-dosseg.md +++ b/docs/assembler/masm/dot-dosseg.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .DOSSEG (32-bit MASM)" title: ".DOSSEG" ms.date: "11/05/2019" f1_keywords: [".DOSSEG"] diff --git a/docs/assembler/masm/dot-else.md b/docs/assembler/masm/dot-else.md index 39af77d231..1632b07c80 100644 --- a/docs/assembler/masm/dot-else.md +++ b/docs/assembler/masm/dot-else.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .ELSE (32-bit MASM)" title: ".ELSE" ms.date: "11/05/2019" f1_keywords: [".ELSE"] diff --git a/docs/assembler/masm/dot-endif.md b/docs/assembler/masm/dot-endif.md index 1f02167acc..8daea685cf 100644 --- a/docs/assembler/masm/dot-endif.md +++ b/docs/assembler/masm/dot-endif.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .ENDIF (32-bit MASM)" title: ".ENDIF" ms.date: "11/05/2019" f1_keywords: [".ENDIF"] diff --git a/docs/assembler/masm/dot-endprolog.md b/docs/assembler/masm/dot-endprolog.md index 1d9307f715..c864e0c849 100644 --- a/docs/assembler/masm/dot-endprolog.md +++ b/docs/assembler/masm/dot-endprolog.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .ENDPROLOG" title: ".ENDPROLOG" ms.date: "12/17/2019" f1_keywords: [".ENDPROLOG"] diff --git a/docs/assembler/masm/dot-endw.md b/docs/assembler/masm/dot-endw.md index fcf613932a..eb6769ad0f 100644 --- a/docs/assembler/masm/dot-endw.md +++ b/docs/assembler/masm/dot-endw.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .ENDW (32-bit MASM)" title: ".ENDW" ms.date: "11/05/2019" f1_keywords: [".ENDW"] diff --git a/docs/assembler/masm/dot-err.md b/docs/assembler/masm/dot-err.md index 7b2614813e..2bae97f8be 100644 --- a/docs/assembler/masm/dot-err.md +++ b/docs/assembler/masm/dot-err.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: `.ERR`" title: ".ERR" ms.date: "12/17/2019" f1_keywords: [".ERR"] diff --git a/docs/assembler/masm/dot-err2.md b/docs/assembler/masm/dot-err2.md index 673f6cf5c5..825a14ba4e 100644 --- a/docs/assembler/masm/dot-err2.md +++ b/docs/assembler/masm/dot-err2.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .ERR2" title: ".ERR2" ms.date: "12/17/2019" f1_keywords: [".ERR2"] diff --git a/docs/assembler/masm/dot-errb.md b/docs/assembler/masm/dot-errb.md index 61f6042e83..3d414a3d03 100644 --- a/docs/assembler/masm/dot-errb.md +++ b/docs/assembler/masm/dot-errb.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .ERRB" title: ".ERRB" ms.date: "12/17/2019" f1_keywords: [".ERRB"] diff --git a/docs/assembler/masm/dot-errdef.md b/docs/assembler/masm/dot-errdef.md index 36a4b41005..a7a7106c41 100644 --- a/docs/assembler/masm/dot-errdef.md +++ b/docs/assembler/masm/dot-errdef.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .ERRDEF" title: ".ERRDEF" ms.date: "12/17/2019" f1_keywords: [".ERRDEF"] diff --git a/docs/assembler/masm/dot-errdif.md b/docs/assembler/masm/dot-errdif.md index 648ab2182c..726624195f 100644 --- a/docs/assembler/masm/dot-errdif.md +++ b/docs/assembler/masm/dot-errdif.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .ERRDIF, .ERRDIFI" title: ".ERRDIF, .ERRDIFI" ms.date: "05/23/2019" f1_keywords: [".ERRDIF", ".ERRDIFI"] diff --git a/docs/assembler/masm/dot-erre.md b/docs/assembler/masm/dot-erre.md index 1a7b5afcb7..219a1a1688 100644 --- a/docs/assembler/masm/dot-erre.md +++ b/docs/assembler/masm/dot-erre.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .ERRE" title: ".ERRE" ms.date: "12/17/2019" f1_keywords: [".ERRE"] diff --git a/docs/assembler/masm/dot-erridn.md b/docs/assembler/masm/dot-erridn.md index c7b2c9fd60..35421fa294 100644 --- a/docs/assembler/masm/dot-erridn.md +++ b/docs/assembler/masm/dot-erridn.md @@ -1,22 +1,23 @@ --- -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-errnb.md b/docs/assembler/masm/dot-errnb.md index 49d18c2eee..46a545e29e 100644 --- a/docs/assembler/masm/dot-errnb.md +++ b/docs/assembler/masm/dot-errnb.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .ERRNB" title: ".ERRNB" ms.date: "12/17/2019" f1_keywords: [".ERRNB"] diff --git a/docs/assembler/masm/dot-errndef.md b/docs/assembler/masm/dot-errndef.md index 8dba23541b..4f3a4129b4 100644 --- a/docs/assembler/masm/dot-errndef.md +++ b/docs/assembler/masm/dot-errndef.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .ERRNDEF" title: ".ERRNDEF" ms.date: "12/17/2019" f1_keywords: [".ERRNDEF"] diff --git a/docs/assembler/masm/dot-errnz.md b/docs/assembler/masm/dot-errnz.md index 239b93a404..5275bf4d61 100644 --- a/docs/assembler/masm/dot-errnz.md +++ b/docs/assembler/masm/dot-errnz.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: `.ERRNZ`" title: ".ERRNZ" ms.date: "12/17/2019" f1_keywords: [".ERRNZ"] diff --git a/docs/assembler/masm/dot-exit.md b/docs/assembler/masm/dot-exit.md index cdd56a8296..5f466bdc81 100644 --- a/docs/assembler/masm/dot-exit.md +++ b/docs/assembler/masm/dot-exit.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .EXIT (32-bit MASM)" title: ".EXIT" ms.date: "11/05/2019" f1_keywords: [".EXIT"] diff --git a/docs/assembler/masm/dot-fardata-q.md b/docs/assembler/masm/dot-fardata-q.md index ce54b47c98..b49cd14fb6 100644 --- a/docs/assembler/masm/dot-fardata-q.md +++ b/docs/assembler/masm/dot-fardata-q.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .FARDATA? (32-bit MASM)" title: ".FARDATA?" ms.date: "11/05/2019" f1_keywords: [".FARDATA?"] diff --git a/docs/assembler/masm/dot-fardata.md b/docs/assembler/masm/dot-fardata.md index a25ea12a7c..9e2bbcb4d5 100644 --- a/docs/assembler/masm/dot-fardata.md +++ b/docs/assembler/masm/dot-fardata.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .FARDATA (32-bit MASM)" title: ".FARDATA" ms.date: "11/05/2019" f1_keywords: [".FARDATA"] diff --git a/docs/assembler/masm/dot-fpo.md b/docs/assembler/masm/dot-fpo.md index 7c754515bf..7c70aab623 100644 --- a/docs/assembler/masm/dot-fpo.md +++ b/docs/assembler/masm/dot-fpo.md @@ -1,37 +1,37 @@ --- +description: "Learn more about: .FPO (32-bit MASM)" title: ".FPO" ms.date: "11/05/2019" f1_keywords: [".FPO"] helpviewer_keywords: [".FPO directive"] -ms.assetid: 35f4cd61-32f9-4262-b657-73f04f775d09 --- # .FPO (32-bit MASM) -The **.FPO** directive controls the emission of debug records to the .debug$F segment or section. (32-bit MASM only.) +The `.FPO` directive controls the emission of debug records to the `.debug$F` segment or section. Use this directive with 32-bit MASM only. ## Syntax -> **.FPO** (*cdwLocals*, *cdwParams*, *cbProlog*, *cbRegs*, *fUseBP*, *cbFrame*) +> `.FPO` (*`cdwLocals`*, *`cdwParams`*, *`cbProlog`*, *`cbRegs`*, *`fUseBP`*, *`cbFrame`*) ### Parameters -*cdwLocals*\ -Number of local variables, an unsigned 32 bit value. +*`cdwLocals`*\ +Number of local variables, an unsigned 32-bit value. -*cdwParams*\ -Size of the parameters in DWORDS, an unsigned 16 bit value. +*`cdwParams`*\ +Size of the parameters in DWORDS, an unsigned 16-bit value. -*cbProlog*\ -Number of bytes in the function prolog code, an unsigned 8 bit value. +*`cbProlog`*\ +Number of bytes in the function prolog code, an unsigned 8-bit value. -*cbRegs*\ +*`cbRegs`*\ Number registers saved. -*fUseBP*\ -Indicates whether the EBP register has been allocated. either 0 or 1. +*`fUseBP`*\ +Indicates whether the EBP register is allocated. Use either 0 or 1. -*cbFrame*\ -Indicates the frame type. See [FPO_DATA](/windows/win32/api/winnt/ns-winnt-fpo_data) for more information. +*`cbFrame`*\ +Indicates the frame type. For more information, see [`FPO_DATA`](/windows/win32/api/winnt/ns-winnt-fpo_data). ## See also diff --git a/docs/assembler/masm/dot-if.md b/docs/assembler/masm/dot-if.md index 56136b18b7..65c9610670 100644 --- a/docs/assembler/masm/dot-if.md +++ b/docs/assembler/masm/dot-if.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .IF (32-bit MASM)" title: ".IF" ms.date: "11/05/2019" f1_keywords: [".IF"] diff --git a/docs/assembler/masm/dot-k3d.md b/docs/assembler/masm/dot-k3d.md index d749c68339..173b6d3e95 100644 --- a/docs/assembler/masm/dot-k3d.md +++ b/docs/assembler/masm/dot-k3d.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .K3D (32-bit MASM)" title: ".K3D" ms.date: "11/05/2019" f1_keywords: [".K3D"] diff --git a/docs/assembler/masm/dot-lall.md b/docs/assembler/masm/dot-lall.md index 5a4908d10d..bc0af46d7b 100644 --- a/docs/assembler/masm/dot-lall.md +++ b/docs/assembler/masm/dot-lall.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .LALL" title: ".LALL" ms.date: "12/17/2019" f1_keywords: [".LALL"] diff --git a/docs/assembler/masm/dot-lfcond.md b/docs/assembler/masm/dot-lfcond.md index 319e02505d..d181c262ef 100644 --- a/docs/assembler/masm/dot-lfcond.md +++ b/docs/assembler/masm/dot-lfcond.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .LFCOND" title: ".LFCOND" ms.date: "12/17/2019" f1_keywords: [".LFCOND"] diff --git a/docs/assembler/masm/dot-list.md b/docs/assembler/masm/dot-list.md index 46ad8fe9e1..e521914a91 100644 --- a/docs/assembler/masm/dot-list.md +++ b/docs/assembler/masm/dot-list.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .LIST" title: ".LIST" ms.date: "12/17/2019" f1_keywords: [".LIST"] diff --git a/docs/assembler/masm/dot-listall.md b/docs/assembler/masm/dot-listall.md index 5f8d1b7119..12becc0b8b 100644 --- a/docs/assembler/masm/dot-listall.md +++ b/docs/assembler/masm/dot-listall.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .LISTALL" title: ".LISTALL" ms.date: "12/17/2019" f1_keywords: [".LISTALL"] diff --git a/docs/assembler/masm/dot-listif.md b/docs/assembler/masm/dot-listif.md index e61f62dfcc..96be871841 100644 --- a/docs/assembler/masm/dot-listif.md +++ b/docs/assembler/masm/dot-listif.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .LISTIF" title: ".LISTIF" ms.date: "12/17/2019" f1_keywords: [".LISTIF"] diff --git a/docs/assembler/masm/dot-listmacro.md b/docs/assembler/masm/dot-listmacro.md index 99337913a2..23eb476543 100644 --- a/docs/assembler/masm/dot-listmacro.md +++ b/docs/assembler/masm/dot-listmacro.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .LISTMACRO" title: ".LISTMACRO" ms.date: "12/17/2019" f1_keywords: [".LISTMACRO"] diff --git a/docs/assembler/masm/dot-listmacroall.md b/docs/assembler/masm/dot-listmacroall.md index 124eb64773..1fa4872b5e 100644 --- a/docs/assembler/masm/dot-listmacroall.md +++ b/docs/assembler/masm/dot-listmacroall.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .LISTMACROALL" title: ".LISTMACROALL" ms.date: "12/17/2019" f1_keywords: [".LISTMACROALL"] diff --git a/docs/assembler/masm/dot-mmx.md b/docs/assembler/masm/dot-mmx.md index 5661807cd3..61bcbf63de 100644 --- a/docs/assembler/masm/dot-mmx.md +++ b/docs/assembler/masm/dot-mmx.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .MMX (32-bit MASM)" title: ".MMX" ms.date: "11/05/2019" f1_keywords: [".MMX"] diff --git a/docs/assembler/masm/dot-model.md b/docs/assembler/masm/dot-model.md index b4dcae5815..46a96135aa 100644 --- a/docs/assembler/masm/dot-model.md +++ b/docs/assembler/masm/dot-model.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .MODEL (32-bit MASM)" title: ".MODEL" ms.date: "11/05/2019" f1_keywords: [".MODEL"] @@ -42,7 +43,7 @@ The following table lists the possible values for each parameter when targeting ## Code -For MASM-related samples, download the Compiler samples from [Visual C++ Samples and Related Documentation for Visual Studio 2010](https://go.microsoft.com/fwlink/p/?linkid=178749). +For MASM-related samples, download the Compiler samples from [Visual C++ Samples and Related Documentation for Visual Studio 2010](https://github.com/Microsoft/vcsamples). The following example demonstrates the use of the `.MODEL` directive. diff --git a/docs/assembler/masm/dot-nocref.md b/docs/assembler/masm/dot-nocref.md index b1348caa03..17cdaa3823 100644 --- a/docs/assembler/masm/dot-nocref.md +++ b/docs/assembler/masm/dot-nocref.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .NOCREF" title: ".NOCREF" ms.date: "12/17/2019" f1_keywords: [".NOCREF"] diff --git a/docs/assembler/masm/dot-nolist.md b/docs/assembler/masm/dot-nolist.md index 239ee215b8..738898fb8c 100644 --- a/docs/assembler/masm/dot-nolist.md +++ b/docs/assembler/masm/dot-nolist.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .NOLIST" title: ".NOLIST" ms.date: "12/17/2019" f1_keywords: [".NOLIST"] diff --git a/docs/assembler/masm/dot-nolistif.md b/docs/assembler/masm/dot-nolistif.md index c16fc60f1c..37703a53fb 100644 --- a/docs/assembler/masm/dot-nolistif.md +++ b/docs/assembler/masm/dot-nolistif.md @@ -1,9 +1,9 @@ --- 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 @@ -19,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-nolistmacro.md b/docs/assembler/masm/dot-nolistmacro.md index 0cb43a6606..0d4184d5f3 100644 --- a/docs/assembler/masm/dot-nolistmacro.md +++ b/docs/assembler/masm/dot-nolistmacro.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .NOLISTMACRO" title: ".NOLISTMACRO" ms.date: "12/17/2019" f1_keywords: [".NOLISTMACRO"] diff --git a/docs/assembler/masm/dot-pushreg.md b/docs/assembler/masm/dot-pushreg.md index cb9b34d911..a433f688d6 100644 --- a/docs/assembler/masm/dot-pushreg.md +++ b/docs/assembler/masm/dot-pushreg.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .PUSHREG" title: ".PUSHREG" ms.date: "12/16/2019" f1_keywords: [".PUSHREG"] diff --git a/docs/assembler/masm/dot-radix.md b/docs/assembler/masm/dot-radix.md index 660d40b02f..911da7e83b 100644 --- a/docs/assembler/masm/dot-radix.md +++ b/docs/assembler/masm/dot-radix.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .RADIX" title: ".RADIX" ms.date: "12/17/2019" f1_keywords: [".RADIX"] diff --git a/docs/assembler/masm/dot-repeat.md b/docs/assembler/masm/dot-repeat.md index 5d83446148..7401234002 100644 --- a/docs/assembler/masm/dot-repeat.md +++ b/docs/assembler/masm/dot-repeat.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .REPEAT (32-bit MASM)" title: ".REPEAT" ms.date: "11/05/2019" f1_keywords: [".REPEAT"] diff --git a/docs/assembler/masm/dot-safeseh.md b/docs/assembler/masm/dot-safeseh.md index 201350f574..c8c354c906 100644 --- a/docs/assembler/masm/dot-safeseh.md +++ b/docs/assembler/masm/dot-safeseh.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .SAFESEH (32-bit MASM)" title: ".SAFESEH" ms.date: "11/05/2019" f1_keywords: [".SAFESEH"] diff --git a/docs/assembler/masm/dot-sall.md b/docs/assembler/masm/dot-sall.md index e9d9acc3b5..a8359e3ba4 100644 --- a/docs/assembler/masm/dot-sall.md +++ b/docs/assembler/masm/dot-sall.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .SALL" title: ".SALL" ms.date: "12/17/2019" f1_keywords: [".SALL"] diff --git a/docs/assembler/masm/dot-savereg.md b/docs/assembler/masm/dot-savereg.md index f0ab168d62..a786f88777 100644 --- a/docs/assembler/masm/dot-savereg.md +++ b/docs/assembler/masm/dot-savereg.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .SAVEREG" title: ".SAVEREG" ms.date: "12/16/2019" f1_keywords: [".SAVEREG"] diff --git a/docs/assembler/masm/dot-savexmm128.md b/docs/assembler/masm/dot-savexmm128.md index 1ef86aa9e4..6a914c5547 100644 --- a/docs/assembler/masm/dot-savexmm128.md +++ b/docs/assembler/masm/dot-savexmm128.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .SAVEXMM128" title: ".SAVEXMM128" ms.date: "12/17/2019" f1_keywords: [".SAVEXMM128"] diff --git a/docs/assembler/masm/dot-seq.md b/docs/assembler/masm/dot-seq.md index 079067cb21..5f24e72957 100644 --- a/docs/assembler/masm/dot-seq.md +++ b/docs/assembler/masm/dot-seq.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .SEQ (32-bit MASM)" title: ".SEQ" ms.date: "11/05/2019" f1_keywords: [".SEQ"] diff --git a/docs/assembler/masm/dot-setframe.md b/docs/assembler/masm/dot-setframe.md index 201ea7d1f5..d33281ed97 100644 --- a/docs/assembler/masm/dot-setframe.md +++ b/docs/assembler/masm/dot-setframe.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .SETFRAME" title: ".SETFRAME" ms.date: "12/17/2019" f1_keywords: [".SETFRAME"] diff --git a/docs/assembler/masm/dot-sfcond.md b/docs/assembler/masm/dot-sfcond.md index ea68e1c8d8..f5a5730e29 100644 --- a/docs/assembler/masm/dot-sfcond.md +++ b/docs/assembler/masm/dot-sfcond.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .SFCOND" title: ".SFCOND" ms.date: "12/16/2019" f1_keywords: [".SFCOND"] diff --git a/docs/assembler/masm/dot-stack.md b/docs/assembler/masm/dot-stack.md index a580d05368..be6b334744 100644 --- a/docs/assembler/masm/dot-stack.md +++ b/docs/assembler/masm/dot-stack.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .STACK (32-bit MASM)" title: ".STACK" ms.date: "11/05/2019" f1_keywords: [".STACK"] diff --git a/docs/assembler/masm/dot-startup.md b/docs/assembler/masm/dot-startup.md index 5e1e7c4f7c..dfbf90bdda 100644 --- a/docs/assembler/masm/dot-startup.md +++ b/docs/assembler/masm/dot-startup.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .STARTUP (32-bit MASM)" title: ".STARTUP" ms.date: "11/05/2019" f1_keywords: [".STARTUP"] diff --git a/docs/assembler/masm/dot-tfcond.md b/docs/assembler/masm/dot-tfcond.md index a292add3cc..f56635114e 100644 --- a/docs/assembler/masm/dot-tfcond.md +++ b/docs/assembler/masm/dot-tfcond.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .TFCOND" title: ".TFCOND" ms.date: "12/16/2019" f1_keywords: [".TFCOND"] diff --git a/docs/assembler/masm/dot-until.md b/docs/assembler/masm/dot-until.md index e49025f388..de85420362 100644 --- a/docs/assembler/masm/dot-until.md +++ b/docs/assembler/masm/dot-until.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .UNTIL (32-bit MASM)" title: ".UNTIL" ms.date: "11/05/2019" f1_keywords: [".UNTIL"] diff --git a/docs/assembler/masm/dot-untilcxz.md b/docs/assembler/masm/dot-untilcxz.md index 8e0f7bb185..c3c5d22acc 100644 --- a/docs/assembler/masm/dot-untilcxz.md +++ b/docs/assembler/masm/dot-untilcxz.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .UNTILCXZ (32-bit MASM)" title: ".UNTILCXZ" ms.date: "11/05/2019" f1_keywords: [".UNTILCXZ"] diff --git a/docs/assembler/masm/dot-while.md b/docs/assembler/masm/dot-while.md index 17518b3759..613f3bbb81 100644 --- a/docs/assembler/masm/dot-while.md +++ b/docs/assembler/masm/dot-while.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .WHILE (32-bit MASM)" title: ".WHILE" ms.date: "11/05/2019" f1_keywords: [".WHILE"] diff --git a/docs/assembler/masm/dot-xall.md b/docs/assembler/masm/dot-xall.md index 91bd6e813f..861406ddaa 100644 --- a/docs/assembler/masm/dot-xall.md +++ b/docs/assembler/masm/dot-xall.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .XALL" title: ".XALL" ms.date: "12/17/2019" f1_keywords: [".XALL"] diff --git a/docs/assembler/masm/dot-xcref.md b/docs/assembler/masm/dot-xcref.md index e866c501b0..02134c0c43 100644 --- a/docs/assembler/masm/dot-xcref.md +++ b/docs/assembler/masm/dot-xcref.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .XCREF" title: ".XCREF" ms.date: "12/17/2019" f1_keywords: [".XCREF"] diff --git a/docs/assembler/masm/dot-xlist.md b/docs/assembler/masm/dot-xlist.md index 537eaf605c..144a08fc4a 100644 --- a/docs/assembler/masm/dot-xlist.md +++ b/docs/assembler/masm/dot-xlist.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .XLIST" title: ".XLIST" ms.date: "12/17/2019" f1_keywords: [".XLIST"] diff --git a/docs/assembler/masm/dot-xmm.md b/docs/assembler/masm/dot-xmm.md index e49e2c2e99..9c0eae78b0 100644 --- a/docs/assembler/masm/dot-xmm.md +++ b/docs/assembler/masm/dot-xmm.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .XMM (32-bit MASM)" title: ".XMM" ms.date: "11/05/2019" f1_keywords: [".XMM"] @@ -7,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/dq.md b/docs/assembler/masm/dq.md index 7f89ec5c7c..b18ea0536b 100644 --- a/docs/assembler/masm/dq.md +++ b/docs/assembler/masm/dq.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: DQ" title: "DQ" ms.date: "12/17/2019" f1_keywords: ["DQ"] diff --git a/docs/assembler/masm/dt.md b/docs/assembler/masm/dt.md index 58d9b2a022..0e938d7df2 100644 --- a/docs/assembler/masm/dt.md +++ b/docs/assembler/masm/dt.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: DT" title: "DT" ms.date: "12/17/2019" f1_keywords: ["dt"] diff --git a/docs/assembler/masm/dw.md b/docs/assembler/masm/dw.md index 76fa74f4f1..c8b146c0bf 100644 --- a/docs/assembler/masm/dw.md +++ b/docs/assembler/masm/dw.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: DW" title: "DW" ms.date: "12/17/2019" f1_keywords: ["DW"] diff --git a/docs/assembler/masm/dword.md b/docs/assembler/masm/dword.md index 78387c8038..4bbc0b2e87 100644 --- a/docs/assembler/masm/dword.md +++ b/docs/assembler/masm/dword.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: DWORD" title: "DWORD" ms.date: "12/17/2019" helpviewer_keywords: ["DWORD directive"] diff --git a/docs/assembler/masm/echo.md b/docs/assembler/masm/echo.md index 29815748f9..c1be74d506 100644 --- a/docs/assembler/masm/echo.md +++ b/docs/assembler/masm/echo.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ECHO" title: "ECHO" ms.date: "12/17/2019" f1_keywords: ["ECHO"] diff --git a/docs/assembler/masm/else-masm.md b/docs/assembler/masm/else-masm.md index cc85b9fcbe..b9698f4856 100644 --- a/docs/assembler/masm/else-masm.md +++ b/docs/assembler/masm/else-masm.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ELSE (MASM)" title: "ELSE (MASM)" ms.date: "12/17/2019" helpviewer_keywords: ["ELSE directive"] diff --git a/docs/assembler/masm/elseif-masm.md b/docs/assembler/masm/elseif-masm.md index a723feeb52..b8d95c5318 100644 --- a/docs/assembler/masm/elseif-masm.md +++ b/docs/assembler/masm/elseif-masm.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ELSEIF" title: "ELSEIF (MASM)" ms.date: "12/16/2019" f1_keywords: ["ElseIf"] diff --git a/docs/assembler/masm/elseif2.md b/docs/assembler/masm/elseif2.md index 8f547c3f4b..4458f25c9a 100644 --- a/docs/assembler/masm/elseif2.md +++ b/docs/assembler/masm/elseif2.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ELSEIF2" title: "ELSEIF2" ms.date: "12/17/2019" f1_keywords: ["ELSEIF2"] diff --git a/docs/assembler/masm/end-masm.md b/docs/assembler/masm/end-masm.md index 93b05813ee..fb6653e719 100644 --- a/docs/assembler/masm/end-masm.md +++ b/docs/assembler/masm/end-masm.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: END" title: "END (MASM)" ms.date: "12/06/2019" f1_keywords: ["end"] diff --git a/docs/assembler/masm/endm.md b/docs/assembler/masm/endm.md index a759fb5e95..20eae17af1 100644 --- a/docs/assembler/masm/endm.md +++ b/docs/assembler/masm/endm.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ENDM" title: "ENDM" ms.date: "12/17/2019" f1_keywords: ["ENDM"] diff --git a/docs/assembler/masm/endp.md b/docs/assembler/masm/endp.md index 9b53b2eef6..2349e1aed3 100644 --- a/docs/assembler/masm/endp.md +++ b/docs/assembler/masm/endp.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ENDP" title: "ENDP" ms.date: "12/17/2019" f1_keywords: ["ENDP"] diff --git a/docs/assembler/masm/ends-masm.md b/docs/assembler/masm/ends-masm.md index 87859c6b48..fae9ac46b8 100644 --- a/docs/assembler/masm/ends-masm.md +++ b/docs/assembler/masm/ends-masm.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ENDS" title: "ENDS (MASM)" ms.date: "12/17/2019" f1_keywords: ["ENDS"] diff --git a/docs/assembler/masm/equ.md b/docs/assembler/masm/equ.md index f6637d84b0..b26e2efc5b 100644 --- a/docs/assembler/masm/equ.md +++ b/docs/assembler/masm/equ.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: EQU" title: "EQU" ms.date: "12/17/2019" f1_keywords: ["EQU"] diff --git a/docs/assembler/masm/equal.md b/docs/assembler/masm/equal.md index 99358f7558..4d275924db 100644 --- a/docs/assembler/masm/equal.md +++ b/docs/assembler/masm/equal.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: =" title: "=" ms.date: "12/17/2019" f1_keywords: ["="] diff --git a/docs/assembler/masm/even.md b/docs/assembler/masm/even.md index 1cd01181dc..f7b6a209b9 100644 --- a/docs/assembler/masm/even.md +++ b/docs/assembler/masm/even.md @@ -1,11 +1,11 @@ --- title: "EVEN" -ms.date: "12/17/2019" +description: "Learn more about: EVEN" +ms.date: 12/17/2019 f1_keywords: ["EVEN"] helpviewer_keywords: ["EVEN directive"] -ms.assetid: 68938ba4-8cb9-44d4-914e-9f9fee6bcbf4 --- -# EVEN +# `EVEN` Aligns the next variable or instruction on an even byte. @@ -15,5 +15,6 @@ Aligns the next variable or instruction on an even byte. ## See also +[`ALIGN`](align-masm.md)\ [Directives reference](directives-reference.md)\ [MASM BNF Grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/exitm.md b/docs/assembler/masm/exitm.md index a48bdee055..460ac7baac 100644 --- a/docs/assembler/masm/exitm.md +++ b/docs/assembler/masm/exitm.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: EXITM" title: "EXITM" ms.date: "12/17/2019" f1_keywords: ["EXITM"] diff --git a/docs/assembler/masm/extern-masm.md b/docs/assembler/masm/extern-masm.md index 0e6c8320f2..d261390d68 100644 --- a/docs/assembler/masm/extern-masm.md +++ b/docs/assembler/masm/extern-masm.md @@ -1,8 +1,8 @@ --- +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 @@ -16,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/externdef.md b/docs/assembler/masm/externdef.md index 28192b6870..161395a647 100644 --- a/docs/assembler/masm/externdef.md +++ b/docs/assembler/masm/externdef.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: EXTERNDEF" title: "EXTERNDEF" ms.date: "12/06/2019" f1_keywords: ["EXTERNDEF"] diff --git a/docs/assembler/masm/extrn.md b/docs/assembler/masm/extrn.md index 30cc67e29d..8d6e5bb536 100644 --- a/docs/assembler/masm/extrn.md +++ b/docs/assembler/masm/extrn.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: EXTRN" title: "EXTRN" ms.date: "12/17/2019" f1_keywords: ["EXTRN"] diff --git a/docs/assembler/masm/for-masm.md b/docs/assembler/masm/for-masm.md index a02a843827..ed50604521 100644 --- a/docs/assembler/masm/for-masm.md +++ b/docs/assembler/masm/for-masm.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: FOR" title: "FOR (MASM)" ms.date: "12/17/2019" helpviewer_keywords: ["FOR directive"] diff --git a/docs/assembler/masm/forc.md b/docs/assembler/masm/forc.md index ae95c6ec1d..ff9785c0fa 100644 --- a/docs/assembler/masm/forc.md +++ b/docs/assembler/masm/forc.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: FORC" title: "FORC" ms.date: "12/17/2019" f1_keywords: ["FORC"] diff --git a/docs/assembler/masm/fword.md b/docs/assembler/masm/fword.md index db7d609cf4..298c9ec16b 100644 --- a/docs/assembler/masm/fword.md +++ b/docs/assembler/masm/fword.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: FWORD" title: "FWORD" ms.date: "12/17/2019" f1_keywords: ["FWORD"] diff --git a/docs/assembler/masm/goto-masm.md b/docs/assembler/masm/goto-masm.md index 55055b91f8..c0c70f8b90 100644 --- a/docs/assembler/masm/goto-masm.md +++ b/docs/assembler/masm/goto-masm.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: GOTO" title: "GOTO (MASM)" ms.date: "12/16/2019" helpviewer_keywords: ["GOTO directive"] diff --git a/docs/assembler/masm/group.md b/docs/assembler/masm/group.md index e056091514..e384255db2 100644 --- a/docs/assembler/masm/group.md +++ b/docs/assembler/masm/group.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: GROUP" title: "GROUP" ms.date: "11/05/2019" f1_keywords: ["group"] diff --git a/docs/assembler/masm/if-masm.md b/docs/assembler/masm/if-masm.md index 6cb3c256cd..ecf95eaad2 100644 --- a/docs/assembler/masm/if-masm.md +++ b/docs/assembler/masm/if-masm.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IF" title: "IF (MASM)" ms.date: "12/17/2019" helpviewer_keywords: ["IF directive"] diff --git a/docs/assembler/masm/if2.md b/docs/assembler/masm/if2.md index 8d0fc79f72..b5662e321f 100644 --- a/docs/assembler/masm/if2.md +++ b/docs/assembler/masm/if2.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IF1 and IF2" title: "IF1 and IF2" ms.date: "11/21/2019" f1_keywords: ["IF2", "IF1"] diff --git a/docs/assembler/masm/ifb.md b/docs/assembler/masm/ifb.md index 6edfc832ad..59e18dc543 100644 --- a/docs/assembler/masm/ifb.md +++ b/docs/assembler/masm/ifb.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IFB" title: "IFB" ms.date: "12/17/2019" f1_keywords: ["IFB"] diff --git a/docs/assembler/masm/ifdef.md b/docs/assembler/masm/ifdef.md index d6103e527a..c29dadf56d 100644 --- a/docs/assembler/masm/ifdef.md +++ b/docs/assembler/masm/ifdef.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IFDEF" title: "IFDEF" ms.date: "12/17/2019" f1_keywords: ["IFDEF"] diff --git a/docs/assembler/masm/ifdif.md b/docs/assembler/masm/ifdif.md index 14c1d5d03c..e08aa1e108 100644 --- a/docs/assembler/masm/ifdif.md +++ b/docs/assembler/masm/ifdif.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IFDIF, IFDIFI" title: "IFDIF, IFDIFI" ms.date: "05/23/2019" f1_keywords: ["IFDIF", "IFDIFI"] diff --git a/docs/assembler/masm/ife.md b/docs/assembler/masm/ife.md index a67d5b88ae..749be29b11 100644 --- a/docs/assembler/masm/ife.md +++ b/docs/assembler/masm/ife.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IFE" title: "IFE" ms.date: "12/17/2019" f1_keywords: ["IFE"] diff --git a/docs/assembler/masm/ifidn.md b/docs/assembler/masm/ifidn.md index ca717384bf..fcbb8f24cf 100644 --- a/docs/assembler/masm/ifidn.md +++ b/docs/assembler/masm/ifidn.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IFIDN, IFIDNI" title: "IFIDN, IFIDNI" ms.date: "12/17/2019" f1_keywords: ["IFIDN", "IFIDNI"] diff --git a/docs/assembler/masm/ifnb.md b/docs/assembler/masm/ifnb.md index 823f6d148d..999a5f233d 100644 --- a/docs/assembler/masm/ifnb.md +++ b/docs/assembler/masm/ifnb.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IFNB" title: "IFNB" ms.date: "12/17/2019" f1_keywords: ["IFNB"] diff --git a/docs/assembler/masm/ifndef.md b/docs/assembler/masm/ifndef.md index e4c215bcae..713c2f6f33 100644 --- a/docs/assembler/masm/ifndef.md +++ b/docs/assembler/masm/ifndef.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IFNDEF" title: "IFNDEF" ms.date: "12/17/2019" f1_keywords: ["IFNDEF"] diff --git a/docs/assembler/masm/include-masm.md b/docs/assembler/masm/include-masm.md index 9cefb85629..9d588fc77b 100644 --- a/docs/assembler/masm/include-masm.md +++ b/docs/assembler/masm/include-masm.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: INCLUDE" title: "INCLUDE (MASM)" ms.date: "12/17/2019" helpviewer_keywords: ["INCLUDE directive"] diff --git a/docs/assembler/masm/includelib-masm.md b/docs/assembler/masm/includelib-masm.md index 0bab99df71..2bc504c53d 100644 --- a/docs/assembler/masm/includelib-masm.md +++ b/docs/assembler/masm/includelib-masm.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: INCLUDELIB" title: "INCLUDELIB (MASM)" ms.date: "12/17/2019" f1_keywords: ["INCLUDELIB"] diff --git a/docs/assembler/masm/instr.md b/docs/assembler/masm/instr.md index d47b071887..8aeb0098f1 100644 --- a/docs/assembler/masm/instr.md +++ b/docs/assembler/masm/instr.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: INSTR" title: "INSTR" ms.date: "12/17/2019" f1_keywords: ["InStr"] 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/invoke.md b/docs/assembler/masm/invoke.md index 9fc07b774c..c6e06f6aa5 100644 --- a/docs/assembler/masm/invoke.md +++ b/docs/assembler/masm/invoke.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: INVOKE" title: "INVOKE" ms.date: "11/05/2019" f1_keywords: ["Invoke"] diff --git a/docs/assembler/masm/irp.md b/docs/assembler/masm/irp.md index 50d71dd808..eae39c6b2d 100644 --- a/docs/assembler/masm/irp.md +++ b/docs/assembler/masm/irp.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IRP" title: "IRP" ms.date: "12/17/2019" f1_keywords: ["IRP"] diff --git a/docs/assembler/masm/irpc.md b/docs/assembler/masm/irpc.md index b88b03d7c6..85ad48b295 100644 --- a/docs/assembler/masm/irpc.md +++ b/docs/assembler/masm/irpc.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IRPC" title: "IRPC" ms.date: "12/17/2019" f1_keywords: ["IRPC"] diff --git a/docs/assembler/masm/label-masm.md b/docs/assembler/masm/label-masm.md index 075e99f073..7b89c60c7d 100644 --- a/docs/assembler/masm/label-masm.md +++ b/docs/assembler/masm/label-masm.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: LABEL" title: "LABEL (MASM)" ms.date: "12/17/2019" f1_keywords: ["Label"] diff --git a/docs/assembler/masm/local-masm.md b/docs/assembler/masm/local-masm.md index 0aa48121d0..5edfad2ea5 100644 --- a/docs/assembler/masm/local-masm.md +++ b/docs/assembler/masm/local-masm.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: LOCAL" title: "LOCAL (MASM)" ms.date: "12/16/2019" f1_keywords: ["Local"] diff --git a/docs/assembler/masm/macro.md b/docs/assembler/masm/macro.md index 28f57db033..c1bbf798c8 100644 --- a/docs/assembler/masm/macro.md +++ b/docs/assembler/masm/macro.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: MACRO" title: "MACRO" ms.date: "12/16/2019" f1_keywords: ["MACRO"] diff --git a/docs/assembler/masm/masm-bnf-grammar.md b/docs/assembler/masm/masm-bnf-grammar.md index 771ea71a16..65eea98ce0 100644 --- a/docs/assembler/masm/masm-bnf-grammar.md +++ b/docs/assembler/masm/masm-bnf-grammar.md @@ -1,1070 +1,1085 @@ --- title: "Microsoft Macro Assembler BNF Grammar" description: "BNF description of MASM for x64." -ms.date: "12/17/2019" +ms.date: 04/15/2021 helpviewer_keywords: ["MASM (Microsoft Macro Assembler), BNF reference"] --- # Microsoft Macro Assembler BNF Grammar This page contains a BNF description of the MASM grammar. It's provided as a supplement to the reference and isn't guaranteed to be complete. Consult the reference for full information on keywords, parameters, operations, and so on. -To illustrate the use of the BNF, the following diagram shows the definition of the TYPEDEF directive, starting with the nonterminal *`typedefDir`*. +To illustrate the use of the BNF, the following diagram shows the definition of the **`TYPEDEF`** directive, starting with the nonterminal *`typedefDir`*. -![MASM BNF Example](media/bnf.png) +![A chart showing the hierarchy of terminals and nonterminals that produce a typedefDir.](media/bnf.png) The entries under each horizontal brace are terminals, such as **`NEAR16`**, **`NEAR32`**, **`FAR16`**, and **`FAR32`**. Or, they're nonterminals such as *`qualifier`*, *`qualifiedType`*, *`distance`*, and *`protoSpec`* that can be further defined. Each italicized nonterminal in the *`typedefDir`* definition is also an entry in the BNF. Three vertical dots indicate a branching definition for a nonterminal that, for the sake of simplicity, this figure doesn't illustrate. -The BNF grammar allows recursive definitions. For example, the grammar uses qualifiedType as a possible definition for qualifiedType, which is also a component of the definition for qualifier. The "|" symbol specifies a choice between alternate expressions, for example *`endOfLine`* | *`comment`*. Double braces specify an optional parameter, for example ⟦ *`macroParmList`* ⟧. The brackets don't actually appear in the source code. +The BNF grammar allows recursive definitions. For example, the grammar uses *`qualifiedType`* as a possible definition for *`qualifiedType`*, which is also a component of the definition for *`qualifier`*. The "|" symbol specifies a choice between alternate expressions, for example *`endOfLine`* | *`comment`*. Double braces specify an optional parameter, for example ⟦ *`macroParmList`* ⟧. The brackets don't actually appear in the source code. ## MASM Nonterminals *`;;`*\ -    *`endOfLine`* | *`comment`* +  *`endOfLine`* | *`comment`* *`=Dir`*\ -    *`id`* = *`immExpr`* *`;;`* +  *`id`* **`=`** *`immExpr`* *`;;`* *`addOp`*\ -    **`+`** | **`-`** +  **`+`** | **`-`** *`aExpr`*\ -    *`term`* | *`aExpr`* **`&&`** *`term`* +  *`term`* | *`aExpr`* **`&&`** *`term`* *`altId`*\ -    *`id`* +  *`id`* + +*`alpha`*\ +  Any upper or lowercase letter (A-Z) or one of these four characters: `@ _ $ ?` *`arbitraryText`*\ -    *`charList`* +  *`charList`* *`asmInstruction`*\ -    *`mnemonic`* ⟦ *`exprList`* ⟧ +  *`mnemonic`* ⟦ *`exprList`* ⟧ *`assumeDir`*\ -    **`ASSUME`** *`assumeList`* *`;;`*\ -    | **`ASSUME NOTHING`** *`;;`* +  **`ASSUME`** *`assumeList`* *`;;`*\ +  | **`ASSUME NOTHING`** *`;;`* *`assumeList`*\ -    *`assumeRegister`* | *`assumeList`* **`,`** *`assumeRegister`*\ +  *`assumeRegister`* | *`assumeList`* **`,`** *`assumeRegister`* *`assumeReg`*\ -    *`register`* **`:`** *`assumeVal`* +  *`register`* **`:`** *`assumeVal`* *`assumeRegister`*\ -    *`assumeSegReg`* | *`assumeReg`* +  *`assumeSegReg`* | *`assumeReg`* *`assumeSegReg`*\ -    *`segmentRegister`* **`:`** *`assumeSegVal`* +  *`segmentRegister`* **`:`** *`assumeSegVal`* *`assumeSegVal`*\ -    *`frameExpr`* | **`NOTHING`** | **`ERROR`** +  *`frameExpr`* | **`NOTHING`** | **`ERROR`** *`assumeVal`*\ -    *`qualifiedType`* | **`NOTHING`** | **`ERROR`** +  *`qualifiedType`* | **`NOTHING`** | **`ERROR`** *`bcdConst`*\ -    ⟦ *`sign`* ⟧ *`decNumber`* +  ⟦ *`sign`* ⟧ *`decNumber`* *`binaryOp`*\ -    **`==`** | **`!=`** | **`>=`** | **`<=`** | **`>`** | **`<`** | **`&`** +  **`==`** | **`!=`** | **`>=`** | **`<=`** | **`>`** | **`<`** | **`&`** *`bitDef`*\ -    *`bitFieldId`* **`:`** *`bitFieldSize`* ⟦ **`=`** *`constExpr`* ⟧ +  *`bitFieldId`* **`:`** *`bitFieldSize`* ⟦ **`=`** *`constExpr`* ⟧ *`bitDefList`*\ -    *`bitDef`* | *`bitDefList`* **`,`** ⟦ *`;;`* ⟧ *`bitDef`* +  *`bitDef`* | *`bitDefList`* **`,`** ⟦ *`;;`* ⟧ *`bitDef`* *`bitFieldId`*\ -    *`id`* +  *`id`* *`bitFieldSize`*\ -    *`constExpr`* +  *`constExpr`* *`blockStatements`*\ -    *`directiveList`*\ -    | **`.CONTINUE`** **`.IF`** *`cExpr`* ⟧\ -    | **`.BREAK`** ⟦ **`.IF`** *`cExpr`* ⟧ +  *`directiveList`*\ +  | **`.CONTINUE`** ⟦ **`.IF`** *`cExpr`* ⟧\ +  | **`.BREAK`** ⟦ **`.IF`** *`cExpr`* ⟧ *`bool`*\ -    **`TRUE`** | **`FALSE`** +  **`TRUE`** | **`FALSE`** *`byteRegister`*\ -    **`AL`** | **`AH`** | **`CL`** | **`CH`** | **`DL`** | **`DH`** | **`BL`** | **`BH`** | **`R8B`** | **`R9B`** | **`R10B`** | **`R11B`** | **`R12B`** | **`R13B`** | **`R14B`** | **`R15B`** +  **`AL`** | **`AH`** | **`CL`** | **`CH`** | **`DL`** | **`DH`** | **`BL`** | **`BH`** | **`R8B`** | **`R9B`** | **`R10B`** | **`R11B`** | **`R12B`** | **`R13B`** | **`R14B`** | **`R15B`** *`cExpr`*\ -    *`aExpr`* | *`cExpr`* **`||`** *`aExpr`* +  *`aExpr`* | *`cExpr`* **`||`** *`aExpr`* *`character`*\ -    Any character with ordinal in the range 0–255 except linefeed (10). +  Any character with ordinal in the range 0–255 except linefeed (10). *`charList`*\ -    *`character`* | *`charList`* *`character`* +  *`character`* | *`charList`* *`character`* *`className`*\ -    *`string`* +  *`string`* *`commDecl`*\ -    ⟦ *`nearfar`* ⟧ ⟦ *`langType`* ⟧ *`id`* **`:`** *`commType`*\ -    ⟦ **`:`** *`constExpr`* ⟧ +  ⟦ *`nearfar`* ⟧ ⟦ *`langType`* ⟧ *`id`* **`:`** *`commType`*\ +  ⟦ **`:`** *`constExpr`* ⟧ *`commDir`*\ -    **`COMM`**\ -    *`commList`* *`;;`* +  **`COMM`**\ +  *`commList`* *`;;`* *`comment`*\ -    ; *`text`* *`;;`* +  **`;`** *`text`* *`;;`* *`commentDir`*\ -    **`COMMENT`** *`delimiter`*\ -    *`text`*\ -    *`text`* *`delimiter`* *`text`* *`;;`* +  **`COMMENT`** *`delimiter`*\ +  *`text`*\ +  *`text`* *`delimiter`* *`text`* *`;;`* *`commList`*\ -    *`commDecl`* | *`commList`* **`,`** *`commDecl`* +  *`commDecl`* | *`commList`* **`,`** *`commDecl`* *`commType`*\ -    *`type`* | *`constExpr`* +  *`type`* | *`constExpr`* *`constant`*\ -    *`digits`* ⟦ *`radixOverride`* ⟧ +  *`digits`* ⟦ *`radixOverride`* ⟧ *`constExpr`*\ -    *`expr`* +  *`expr`* *`contextDir`*\ -    **`PUSHCONTEXT`** *`contextItemList`* *`;;`*\ -    **`POPCONTEXT`** *`contextItemList`* *`;;`* +  **`PUSHCONTEXT`** *`contextItemList`* *`;;`*\ +  | **`POPCONTEXT`** *`contextItemList`* *`;;`* *`contextItem`*\ -    **`ASSUMES`** | **`RADIX`** | **`LISTING`** | **`CPU`** | **`ALL`** +  **`ASSUMES`** | **`RADIX`** | **`LISTING`** | **`CPU`** | **`ALL`** *`contextItemList`*\ -    *`contextItem`* | *`contextItemList`* **`,`** *`contextItem`* +  *`contextItem`* | *`contextItemList`* **`,`** *`contextItem`* *`controlBlock`*\ -    *`whileBlock`* | *`repeatBlock`* +  *`whileBlock`* | *`repeatBlock`* *`controlDir`*\ -    *`controlIf`* | *`controlBlock`* +  *`controlIf`* | *`controlBlock`* *`controlElseif`*\ -    **`.ELSEIF`** -    *`cExpr`* *`;;`*\ -    *`directiveList`* \ -    ⟦ *`controlElseif`* ⟧ +  **`.ELSEIF`** *`cExpr`* *`;;`*\ +  *`directiveList`* \ +  ⟦ *`controlElseif`* ⟧ *`controlIf`*\ -    **`.IF`** -    *`cExpr`* *`;;`*\ -    *`directiveList`*\ -    ⟦ *`controlElseif`* ⟧\ -    ⟦ **`.ELSE`** *`;;`*\ -    [*`directiveList`*⟧\ -    **`.ENDIF`** *`;;`* +  **`.IF`** *`cExpr`* *`;;`*\ +  *`directiveList`*\ +  ⟦ *`controlElseif`* ⟧\ +  ⟦ **`.ELSE`** *`;;`*\ +  *`directiveList`*⟧\ +  **`.ENDIF`** *`;;`* *`coprocessor`*\ -    **`.8087`** | **`.287`** | **`.387`** | **`.NO87`** +  **`.8087`** | **`.287`** | **`.387`** | **`.NO87`** *`crefDir`*\ -    *`crefOption`* *`;;`* +  *`crefOption`* *`;;`* *`crefOption`*\ -    **`.CREF`**\ -    | **`.XCREF`** ⟦ *`idList`* ⟧\ -    | **`.NOCREF`** ⟦ *`idList`* ⟧ +  **`.CREF`**\ +  | **`.XCREF`** ⟦ *`idList`* ⟧\ +  | **`.NOCREF`** ⟦ *`idList`* ⟧ *`cxzExpr`*\ -    *`expr`*\ -    | **`!`** *`expr`*\ -    | *`expr`* **`==`** *`expr`*\ -    | *`expr`* **`!=`** *`expr`* +  *`expr`*\ +  | **`!`** *`expr`*\ +  | *`expr`* **`==`** *`expr`*\ +  | *`expr`* **`!=`** *`expr`* *`dataDecl`*\ -    **`DB`** | **`DW`** | **`DD`** | **`DF`** | **`DQ`** | **`DT`** | *`dataType`* | *`typeId`* +  **`DB`** | **`DW`** | **`DD`** | **`DF`** | **`DQ`** | **`DT`** | *`dataType`* | *`typeId`* *`dataDir`*\ -    ⟦ *`id`* ⟧ *`dataItem`* *`;;`* +  ⟦ *`id`* ⟧ *`dataItem`* *`;;`* *`dataItem`*\ -    *`dataDecl`* *`scalarInstList`*\ -    | *`structTag`* *`structInstList`*\ -    | *`typeId`* *`structInstList`*\ -    | *`unionTag`* *`structInstList`*\ -    | *`recordTag`* *`recordInstList`* +  *`dataDecl`* *`scalarInstList`*\ +  | *`structTag`* *`structInstList`*\ +  | *`typeId`* *`structInstList`*\ +  | *`unionTag`* *`structInstList`*\ +  | *`recordTag`* *`recordInstList`* *`dataType`*\ -    **`BYTE`** | **`SBYTE`** | **`WORD`** | **`SWORD`** | **`DWORD`** | **`SDWORD`** | **`FWORD`** | **`QWORD`** | **`SQWORD`** | **`TBYTE`** | **`OWORD`** | **`REAL4`** | **`REAL8`** | **`REAL10`** | **`MMWORD`** | **`XMMWORD`** | **`YMMWORD`** +  **`BYTE`** | **`SBYTE`** | **`WORD`** | **`SWORD`** | **`DWORD`** | **`SDWORD`** | **`FWORD`** | **`QWORD`** | **`SQWORD`** | **`TBYTE`** | **`OWORD`** | **`REAL4`** | **`REAL8`** | **`REAL10`** | **`MMWORD`** | **`XMMWORD`** | **`YMMWORD`** *`decdigit`*\ -    **`0`** | **`1`** | **`2`** | **`3`** | **`4`** | **`5`** | **`6`** | **`7`** | **`8`** | **`9`** +  **`0`** | **`1`** | **`2`** | **`3`** | **`4`** | **`5`** | **`6`** | **`7`** | **`8`** | **`9`** *`decNumber`*\ -    *`decdigit`*\ -    | *`decNumber`* *`decdigit`* +  *`decdigit`*\ +  | *`decNumber`* *`decdigit`* *`delimiter`*\ -    Any character except *`whiteSpaceCharacter`* +  Any character except *`whiteSpaceCharacter`* *`digits`*\ -    *`decdigit`*\ -    | *`digits`* *`decdigit`*\ -    | *`digits`* *`hexdigit`* +  *`decdigit`*\ +  | *`digits`* *`decdigit`*\ +  | *`digits`* *`hexdigit`* *`directive`*\ -    *`generalDir`* | *`segmentDef`* +  *`generalDir`* | *`segmentDef`* *`directiveList`*\ -    *`directive`* | *`directiveList`* *`directive`* +  *`directive`* | *`directiveList`* *`directive`* *`distance`*\ -    *`nearfar`* | **`NEAR16`** | **`NEAR32`** | **`FAR16`** | **`FAR32`** +  *`nearfar`* | **`NEAR16`** | **`NEAR32`** | **`FAR16`** | **`FAR32`** *`e01`*\ -    *`e01`* *`orOp`* *`e02`* | *`e02`* +  *`e01`* *`orOp`* *`e02`* | *`e02`* *`e02`*\ -    *`e02`* **`AND`** *`e03`* | *`e03`* +  *`e02`* **`AND`** *`e03`* | *`e03`* *`e03`*\ -    **`NOT`** *`e04`* | *`e04`* +  **`NOT`** *`e04`* | *`e04`* *`e04`*\ -    *`e04`* *`relOp`* *`e05`* | *`e05`* +  *`e04`* *`relOp`* *`e05`* | *`e05`* *`e05`*\ -    *`e05`* *`addOp`* *`e06`* | *`e06`* +  *`e05`* *`addOp`* *`e06`* | *`e06`* *`e06`*\ -    *`e06`* *`mulOp`* *`e07`* | *`e06`* *`shiftOp`* *`e07`* | *`e07`* +  *`e06`* *`mulOp`* *`e07`* | *`e06`* *`shiftOp`* *`e07`* | *`e07`* *`e07`*\ -    *`e07`* *`addOp`* *`e08`* | *`e08`* +  *`e07`* *`addOp`* *`e08`* | *`e08`* *`e08`*\ -    **`HIGH`** *`e09`*\ -    | **`LOW`** *`e09`*\ -    | **`HIGHWORD`** *`e09`*\ -    | **`LOWWORD`** *`e09`*\ -    | *`e09`* +  **`HIGH`** *`e09`*\ +  | **`LOW`** *`e09`*\ +  | **`HIGHWORD`** *`e09`*\ +  | **`LOWWORD`** *`e09`*\ +  | *`e09`* *`e09`*\ -    **`OFFSET`** *`e10`*\ -    | **`SEG`** *`e10`*\ -    | **`LROFFSET`** *`e10`*\ -    | **`TYPE`** *`e10`*\ -    | **`THIS`** *`e10`*\ -    | *`e09`* **`PTR`** *`e10`*\ -    | *`e09`* **`:`** *`e10`*\ -    | *`e10`* +  **`OFFSET`** *`e10`*\ +  | **`SEG`** *`e10`*\ +  | **`LROFFSET`** *`e10`*\ +  | **`TYPE`** *`e10`*\ +  | **`THIS`** *`e10`*\ +  | *`e09`* **`PTR`** *`e10`*\ +  | *`e09`* **`:`** *`e10`*\ +  | *`e10`* *`e10`*\ -    *`e10`* **`.`** *`e11`*\ -    | *`e10`* ⟦ *`expr`* ⟧\ -    | *`e11`* +  *`e10`* **`.`** *`e11`*\ +  | *`e10`* ⟦ *`expr`* ⟧\ +  | *`e11`* *`e11`*\ -    **`(`** *`expr`* **`)`**\ -    | ⟦ *`expr`* ⟧\ -    | **`WIDTH`** *`id`*\ -    | **`MASK`** *`id`*\ -    | **`SIZE`** *`sizeArg`*\ -    | **`SIZEOF`** *`sizeArg`*\ -    | **`LENGTH`** *`id`*\ -    | **`LENGTHOF`** *`id`*\ -    | *`recordConst`*\ -    | *`string`*\ -    | *`constant`*\ -    | *`type`*\ -    | *`id`*\ -    | **`$`**\ -    | *`segmentRegister`*\ -    | *`register`*\ -    | **`ST`**\ -    | **`ST`** **`(`** *`expr`* **`)`** +  **`(`** *`expr`* **`)`**\ +  | ⟦ *`expr`* ⟧\ +  | **`WIDTH`** *`id`*\ +  | **`MASK`** *`id`*\ +  | **`SIZE`** *`sizeArg`*\ +  | **`SIZEOF`** *`sizeArg`*\ +  | **`LENGTH`** *`id`*\ +  | **`LENGTHOF`** *`id`*\ +  | *`recordConst`*\ +  | *`string`*\ +  | *`constant`*\ +  | *`type`*\ +  | *`id`*\ +  | **`$`**\ +  | *`segmentRegister`*\ +  | *`register`*\ +  | **`ST`**\ +  | **`ST`** **`(`** *`expr`* **`)`** *`echoDir`*\ -    **`ECHO`**\ -    *`arbitraryText`* *`;;`*\ -    **`%OUT`** *`arbitraryText`* *`;;`* +  **`ECHO`** *`arbitraryText`* *`;;`*\ +  **`%OUT`** *`arbitraryText`* *`;;`* *`elseifBlock`*\ -    *`elseifStatement`* *`;;`*\ -    *`directiveList`*\ -    ⟦ *`elseifBlock`* ⟧ +  *`elseifStatement`* *`;;`*\ +  *`directiveList`*\ +  ⟦ *`elseifBlock`* ⟧ *`elseifStatement`*\ -    **`ELSEIF`** *`constExpr`*\ -    | **`ELSEIFE`** *`constExpr`*\ -    | **`ELSEIFB`** *`textItem`*\ -    | **`ELSEIFNB`** *`textItem`*\ -    | **`ELSEIFDEF`** *`id`*\ -    | **`ELSEIFNDEF`** *`id`*\ -    | **`ELSEIFDIF`** *`textItem`* **`,`** *`textItem`*\ -    | **`ELSEIFDIFI`** *`textItem`* **`,`** *`textItem`*\ -    | **`ELSEIFIDN`** *`textItem`* **`,`** *`textItem`*\ -    | **`ELSEIFIDNI`** *`textItem`* **`,`** *`textItem`*\ -    | **`ELSEIF1`**\ -    | **`ELSEIF2`** +  **`ELSEIF`** *`constExpr`*\ +  | **`ELSEIFE`** *`constExpr`*\ +  | **`ELSEIFB`** *`textItem`*\ +  | **`ELSEIFNB`** *`textItem`*\ +  | **`ELSEIFDEF`** *`id`*\ +  | **`ELSEIFNDEF`** *`id`*\ +  | **`ELSEIFDIF`** *`textItem`* **`,`** *`textItem`*\ +  | **`ELSEIFDIFI`** *`textItem`* **`,`** *`textItem`*\ +  | **`ELSEIFIDN`** *`textItem`* **`,`** *`textItem`*\ +  | **`ELSEIFIDNI`** *`textItem`* **`,`** *`textItem`*\ +  | **`ELSEIF1`**\ +  | **`ELSEIF2`** *`endDir`*\ -    **`END`** ⟦ *`immExpr`* ⟧ *`;;`* +  **`END`** ⟦ *`immExpr`* ⟧ *`;;`* *`endpDir`*\ -    *`procId`* **`ENDP`** *`;;`* +  *`procId`* **`ENDP`** *`;;`* *`endsDir`*\ -    *`id`* **`ENDS`** *`;;`* +  *`id`* **`ENDS`** *`;;`* *`equDir`*\ -    *`textMacroId`* **`EQU`** *`equType`* *`;;`* +  *`textMacroId`* **`EQU`** *`equType`* *`;;`* *`equType`*\ -    *`immExpr`* | *`textLiteral`* +  *`immExpr`* | *`textLiteral`* *`errorDir`*\ -    *`errorOpt`* *`;;`* +  *`errorOpt`* *`;;`* *`errorOpt`*\ -    **`.ERR`** ⟦ *`textItem`* ⟧\ -    | **`.ERRE`** *`constExpr`* ⟦ *`optText`* ⟧\ -    | **`.ERRNZ`** *`constExpr`* ⟦ *`optText`* ⟧\ -    | **`.ERRB`** *`textItem`* ⟦ *`optText`* ⟧\ -    | **`.ERRNB`** *`textItem`* ⟦ *`optText`* ⟧\ -    | **`.ERRDEF`** *`id`* ⟦ *`optText`* ⟧\ -    | **`.ERRNDEF`** *`id`* ⟦ *`optText`* ⟧\ -    | **`.ERRDIF`** *`textItem`* **`,`** *`textItem`* ⟦ *`optText`* ⟧\ -    | **`.ERRDIFI`** *`textItem`* **`,`** *`textItem`* ⟦ *`optText`* ⟧\ -    | **`.ERRIDN`** *`textItem`* **`,`** *`textItem`* ⟦ *`optText`* ⟧\ -    | **`.ERRIDNI`** *`textItem`* **`,`** *`textItem`* ⟦ *`optText`* ⟧\ -    | **`.ERR1`** ⟦ *`textItem`* ⟧\ -    | **`.ERR2`** ⟦ *`textItem`* ⟧ +  **`.ERR`** ⟦ *`textItem`* ⟧\ +  | **`.ERRE`** *`constExpr`* ⟦ *`optText`* ⟧\ +  | **`.ERRNZ`** *`constExpr`* ⟦ *`optText`* ⟧\ +  | **`.ERRB`** *`textItem`* ⟦ *`optText`* ⟧\ +  | **`.ERRNB`** *`textItem`* ⟦ *`optText`* ⟧\ +  | **`.ERRDEF`** *`id`* ⟦ *`optText`* ⟧\ +  | **`.ERRNDEF`** *`id`* ⟦ *`optText`* ⟧\ +  | **`.ERRDIF`** *`textItem`* **`,`** *`textItem`* ⟦ *`optText`* ⟧\ +  | **`.ERRDIFI`** *`textItem`* **`,`** *`textItem`* ⟦ *`optText`* ⟧\ +  | **`.ERRIDN`** *`textItem`* **`,`** *`textItem`* ⟦ *`optText`* ⟧\ +  | **`.ERRIDNI`** *`textItem`* **`,`** *`textItem`* ⟦ *`optText`* ⟧\ +  | **`.ERR1`** ⟦ *`textItem`* ⟧\ +  | **`.ERR2`** ⟦ *`textItem`* ⟧ *`exitDir`*\ -    **`.EXIT`** -    ⟦ *`expr`* ⟧ *`;;`* +  **`.EXIT`** ⟦ *`expr`* ⟧ *`;;`* *`exitmDir`*\ -    : **`EXITM`** | **`EXITM`** *`textItem`* +  **`:`** **`EXITM`** | **`EXITM`** *`textItem`* *`exponent`*\ -    **`E`** ⟦ *`sign`* ⟧ *`decNumber`* +  **`E`** ⟦ *`sign`* ⟧ *`decNumber`* *`expr`*\ -    **`SHORT`** *`e05`*\ -    | **`.TYPE`** *`e01`*\ -    | **`OPATTR`** *`e01`*\ -    | *`e01`* +  **`SHORT`** *`e05`*\ +  | **`.TYPE`** *`e01`*\ +  | **`OPATTR`** *`e01`*\ +  | *`e01`* *`exprList`*\ -    *`expr`* | *`exprList`* **`,`** *`expr`* +  *`expr`* | *`exprList`* **`,`** *`expr`* *`externDef`*\ -    ⟦ *`langType`* ⟧ *`id`* ⟦ **`(`** *`altId`* **`)`** ⟧ **`:`** *`externType`* +  ⟦ *`langType`* ⟧ *`id`* ⟦ **`(`** *`altId`* **`)`** ⟧ **`:`** *`externType`* *`externDir`*\ -    *`externKey`* *`externList`* *`;;`* +  *`externKey`* *`externList`* *`;;`* *`externKey`*\ -    **`EXTRN`** | **`EXTERN`** | **`EXTERNDEF`** +  **`EXTRN`** | **`EXTERN`** | **`EXTERNDEF`** *`externList`*\ -    *`externDef`* | *`externList`* **`,`** ⟦ *`;;`* ⟧ *`externDef`* +  *`externDef`* | *`externList`* **`,`** ⟦ *`;;`* ⟧ *`externDef`* *`externType`*\ -    **`ABS`** | *`qualifiedType`* +  **`ABS`** | *`qualifiedType`* *`fieldAlign`*\ -    *`constExpr`* +  *`constExpr`* *`fieldInit`*\ -    ⟦ *`initValue`* ⟧ | *`structInstance`* +  ⟦ *`initValue`* ⟧ | *`structInstance`* *`fieldInitList`*\ -    *`fieldInit`* | *`fieldInitList`* **`,`** ⟦ *`;;`* ⟧ *`fieldInit`* +  *`fieldInit`* | *`fieldInitList`* **`,`** ⟦ *`;;`* ⟧ *`fieldInit`* *`fileChar`*\ -    *`delimiter`* +  *`delimiter`* *`fileCharList`*\ -    *`fileChar`* | *`fileCharList`* *`fileChar`* +  *`fileChar`* | *`fileCharList`* *`fileChar`* *`fileSpec`*\ -    *`fileCharList`* | *`textLiteral`* +  *`fileCharList`* | *`textLiteral`* *`flagName`*\ -    **`ZERO?`** | **`CARRY?`** | **`OVERFLOW?`** | **`SIGN?`** | **`PARITY?`** +  **`ZERO?`** | **`CARRY?`** | **`OVERFLOW?`** | **`SIGN?`** | **`PARITY?`** *`floatNumber`*\ -    ⟦ *`sign`* ⟧ *`decNumber`* **`.`** ⟦ *`decNumber`* ⟧ ⟦ *`exponent`* ⟧\ -    | *`digits`* **`R`** | *`digits`* **`r`** +  ⟦ *`sign`* ⟧ *`decNumber`* **`.`** ⟦ *`decNumber`* ⟧ ⟦ *`exponent`* ⟧\ +  | *`digits`* **`R`**\ +  | *`digits`* **`r`** *`forcDir`*\ -    **`FORC`** | **`IRPC`** +  **`FORC`** | **`IRPC`** *`forDir`*\ -    **`FOR`** | **`IRP`** +  **`FOR`** | **`IRP`** *`forParm`*\ -    *`id`* ⟦ **`:`** *`forParmType`* ⟧ +  *`id`* ⟦ **`:`** *`forParmType`* ⟧ *`forParmType`*\ -    **`REQ`** | **`=`** *`textLiteral`* +  **`REQ`** | **`=`** *`textLiteral`* *`fpuRegister`*\ -    **`ST`** *`expr`* +  **`ST`** *`expr`* *`frameExpr`*\ -    **`SEG`** *`id`*\ -    | **`DGROUP`** **`:`** *`id`*\ -    | *`segmentRegister`* **`:`** *`id`*\ -    | *`id`* +  **`SEG`** *`id`*\ +  | **`DGROUP`** **`:`** *`id`*\ +  | *`segmentRegister`* **`:`** *`id`*\ +  | *`id`* *`generalDir`*\ -    *`modelDir`* | *`segOrderDir`* | *`nameDir`*\ -    | *`includeLibDir`* | *`commentDir`*\ -    | *`groupDir`* | *`assumeDir`*\ -    | *`structDir`* | *`recordDir`* | *`typedefDir`*\ -    | *`externDir`* | *`publicDir`* | *`commDir`* | *`protoTypeDir`*\ -    | *`equDir`* | *`=Dir`* | *`textDir`*\ -    | *`contextDir`* | *`optionDir`* | *`processorDir`*\ -    | *`radixDir`*\ -    | *`titleDir`* | *`pageDir`* | *`listDir`*\ -    | *`crefDir`* | *`echoDir`*\ -    | *`ifDir`* | *`errorDir`* | *`includeDir`*\ -    | *`macroDir`* | *`macroCall`* | *`macroRepeat`* | *`purgeDir`*\ -    | *`macroWhile`* | *`macroFor`* | *`macroForc`*\ -    | *`aliasDir`* +  *`modelDir`* | *`segOrderDir`* | *`nameDir`*\ +  | *`includeLibDir`* | *`commentDir`*\ +  | *`groupDir`* | *`assumeDir`*\ +  | *`structDir`* | *`recordDir`* | *`typedefDir`*\ +  | *`externDir`* | *`publicDir`* | *`commDir`* | *`protoTypeDir`*\ +  | *`equDir`* | *`=Dir`* | *`textDir`*\ +  | *`contextDir`* | *`optionDir`* | *`processorDir`*\ +  | *`radixDir`*\ +  | *`titleDir`* | *`pageDir`* | *`listDir`*\ +  | *`crefDir`* | *`echoDir`*\ +  | *`ifDir`* | *`errorDir`* | *`includeDir`*\ +  | *`macroDir`* | *`macroCall`* | *`macroRepeat`* | *`purgeDir`*\ +  | *`macroWhile`* | *`macroFor`* | *`macroForc`*\ +  | *`aliasDir`* *`gpRegister`*\ -    **`AX`** | **`EAX`** | **`CX`** | **`ECX`** | **`DX`** | **`EDX`** | **`BX`** | **`EBX`** | **`DI`** | **`EDI`** | **`SI`** | **`ESI`** | **`BP`** | **`EBP`** | **`SP`** | **`ESP`** | **`RSP`** | **`R8W`** | **`R8D`** | **`R9W`** | **`R9D`** | **`R12D`** | **`R13W`** | **`R13D`** | **`R14W`** | **`R14D`** +  **`AX`** | **`EAX`** | **`CX`** | **`ECX`** | **`DX`** | **`EDX`** | **`BX`** | **`EBX`**\ +  | **`DI`** | **`EDI`** | **`SI`** | **`ESI`** | **`BP`** | **`EBP`** | **`SP`** | **`ESP`**\ +  | **`R8W`** | **`R8D`** | **`R9W`** | **`R9D`** | **`R12D`** | **`R13W`** | **`R13D`** | **`R14W`** | **`R14D`** *`groupDir`*\ -    *`groupId`* **`GROUP`** *`segIdList`* +  *`groupId`* **`GROUP`** *`segIdList`* *`groupId`*\ -    *`id`* +  *`id`* *`hexdigit`*\ -    **`a`** | **`b`** | **`c`** | **`d`** | **`e`** | **`f`** | **`A`** | **`B`** | **`C`** | **`D`** | **`E`** | **`F`** +  **`a`** | **`b`** | **`c`** | **`d`** | **`e`** | **`f`**\ +  | **`A`** | **`B`** | **`C`** | **`D`** | **`E`** | **`F`** *`id`*\ -    The first character of the identifier can be an upper or lower-case alphabetic character (`[A–Za-z]`) or any of these four characters: `@ _ $ ?` The remaining characters can be any of those same characters or a decimal digit (`[0–9]`). Maximum length is 247 characters. +  *`alpha`*\ +  | *`id`* *`alpha`*\ +  | *`id`* *`decdigit`*\ +  Maximum length is 247 characters. *`idList`*\ -    *`id`* | *`idList`* **`,`** *`id`* +  *`id`* | *`idList`* **`,`** *`id`* *`ifDir`*\ -    *`ifStatement`* *`;;`*\ -    *`directiveList`*\ -    ⟦ *`elseifBlock`* ⟧\ -    ⟦ **`ELSE`** *`;;`* \ -    *`directiveList`* ⟧ *`;;`* +  *`ifStatement`* *`;;`*\ +  *`directiveList`*\ +  ⟦ *`elseifBlock`* ⟧\ +  ⟦ **`ELSE`** *`;;`* \ +  *`directiveList`* ⟧ *`;;`* *`ifStatement`*\ -    **`IF`** *`constExpr`*\ -    | **`IFE`** *`constExpr`*\ -    | **`IFB`** *`textItem`*\ -    | **`IFNB`** *`textItem`*\ -    | **`IFDEF`** *`id`*\ -    | **`IFNDEF`** *`id`*\ -    | **`IFDIF`** *`textItem`* **`,`** *`textItem`*\ -    | **`IFDIFI`** *`textItem`* **`,`** *`textItem`*\ -    | **`IFIDN`** *`textItem`* **`,`** *`textItem`*\ -    | **`IFIDNI`** *`textItem`* **`,`** *`textItem`*\ -    | **`IF1`**\ -    | **`IF2`** +  **`IF`** *`constExpr`*\ +  | **`IFE`** *`constExpr`*\ +  | **`IFB`** *`textItem`*\ +  | **`IFNB`** *`textItem`*\ +  | **`IFDEF`** *`id`*\ +  | **`IFNDEF`** *`id`*\ +  | **`IFDIF`** *`textItem`* **`,`** *`textItem`*\ +  | **`IFDIFI`** *`textItem`* **`,`** *`textItem`*\ +  | **`IFIDN`** *`textItem`* **`,`** *`textItem`*\ +  | **`IFIDNI`** *`textItem`* **`,`** *`textItem`*\ +  | **`IF1`**\ +  | **`IF2`** *`immExpr`*\ -    *`expr`* +  *`expr`* *`includeDir`*\ -    **`INCLUDE`** *`fileSpec`* *`;;`* +  **`INCLUDE`** *`fileSpec`* *`;;`* *`includeLibDir`*\ -    **`INCLUDELIB`** *`fileSpec`* *`;;`* +  **`INCLUDELIB`** *`fileSpec`* *`;;`* *`initValue`*\ -    *`immExpr`*\ -    | *`string`*\ -    | **`?`**\ -    | *`constExpr`* **`DUP`** ( *`scalarInstList`* )\ -    | *`floatNumber`*\ -    | *`bcdConst`* +  *`immExpr`*\ +  | *`string`*\ +  | **`?`**\ +  | *`constExpr`* **`DUP`** **`(`** *`scalarInstList`* **`)`**\ +  | *`floatNumber`*\ +  | *`bcdConst`* *`inSegDir`*\ -    ⟦ *`labelDef`* ⟧ *`inSegmentDir`* +  ⟦ *`labelDef`* ⟧ *`inSegmentDir`* *`inSegDirList`*\ -    *`inSegDir`* | *`inSegDirList`* *`inSegDir`* +  *`inSegDir`* | *`inSegDirList`* *`inSegDir`* *`inSegmentDir`*\ -    *`instruction`*\ -    | *`dataDir`*\ -    | *`controlDir`*\ -    | *`startupDir`*\ -    | *`exitDir`*\ -    | *`offsetDir`*\ -    | *`labelDir`*\ -    | *`procDir`* ⟦ *`localDirList`* ⟧ ⟦ *`inSegDirList`* ⟧ *`endpDir`*\ -    | *`invokeDir`*\ -    | *`generalDir`* +  *`instruction`*\ +  | *`dataDir`*\ +  | *`controlDir`*\ +  | *`startupDir`*\ +  | *`exitDir`*\ +  | *`offsetDir`*\ +  | *`labelDir`*\ +  | *`procDir`* ⟦ *`localDirList`* ⟧ ⟦ *`inSegDirList`* ⟧ *`endpDir`*\ +  | *`invokeDir`*\ +  | *`generalDir`* *`instrPrefix`*\ -    **`REP`** | **`REPE`** | **`REPZ`** | **`REPNE`** | **`REPNZ`** | **`LOCK`** +  **`REP`** | **`REPE`** | **`REPZ`** | **`REPNE`** | **`REPNZ`** | **`LOCK`** *`instruction`*\ -    ⟦ *`instrPrefix`* ⟧ *`asmInstruction`* +  ⟦ *`instrPrefix`* ⟧ *`asmInstruction`* *`invokeArg`*\ -    *`register`* **`::`** *`register`* | *`expr`* | **`ADDR`** *`expr`* +  *`register`* **`::`** *`register`*\ +  | *`expr`*\ +  | **`ADDR`** *`expr`* *`invokeDir`*\ -    **`INVOKE`** *`expr`* ⟦ **`,`** ⟦ *`;;`* ⟧ *`invokeList`* ⟧ *`;;`* +  **`INVOKE`** *`expr`* ⟦ **`,`** ⟦ *`;;`* ⟧ *`invokeList`* ⟧ *`;;`* *`invokeList`*\ -    *`invokeArg`* | *`invokeList`* **`,`** ⟦ *`;;`* ⟧ *`invokeArg`* +  *`invokeArg`* | *`invokeList`* **`,`** ⟦ *`;;`* ⟧ *`invokeArg`* *`keyword`*\ -    Any reserved word. +  Any reserved word. *`keywordList`*\ -    *`keyword`* | *`keyword`* *`keywordList`* +  *`keyword`* | *`keyword`* *`keywordList`* *`labelDef`*\ -    *`id`* **`:`** | *`id`* **`::`** | **`@@:`** +  *`id`* **`:`** | *`id`* **`::`** | **`@@:`** *`labelDir`*\ -    *`id`* **`LABEL`** *`qualifiedType`* *`;;`* +  *`id`* **`LABEL`** *`qualifiedType`* *`;;`* *`langType`*\ -    **`C`** | **`PASCAL`** | **`FORTRAN`** | **`BASIC`** | **`SYSCALL`** | **`STDCALL`** +  **`C`** | **`PASCAL`** | **`FORTRAN`** | **`BASIC`** | **`SYSCALL`** | **`STDCALL`** *`listDir`*\ -    *`listOption`* *`;;`* +  *`listOption`* *`;;`* *`listOption`*\ -    **`.LIST`**\ -    | **`.NOLIST`**\ -    | **`.XLIST`**\ -    | **`.LISTALL`**\ -    | **`.LISTIF`**\ -    | **`.LFCOND`**\ -    | **`.NOLISTIF`**\ -    | **`.SFCOND`**\ -    | **`.TFCOND`**\ -    | **`.LISTMACROALL`** | **`.LALL`**\ -    | **`.NOLISTMACRO`** | **`.SALL`**\ -    | **`.LISTMACRO`** | **`.XALL`** +  **`.LIST`**\ +  | **`.NOLIST`**\ +  | **`.XLIST`**\ +  | **`.LISTALL`**\ +  | **`.LISTIF`**\ +  | **`.LFCOND`**\ +  | **`.NOLISTIF`**\ +  | **`.SFCOND`**\ +  | **`.TFCOND`**\ +  | **`.LISTMACROALL`** | **`.LALL`**\ +  | **`.NOLISTMACRO`** | **`.SALL`**\ +  | **`.LISTMACRO`** | **`.XALL`** *`localDef`*\ -    **`LOCAL`** *`idList`* *`;;`* +  **`LOCAL`** *`idList`* *`;;`* *`localDir`*\ -    **`LOCAL`** *`parmList`* *`;;`* +  **`LOCAL`** *`parmList`* *`;;`* *`localDirList`*\ -    *`localDir`* | *`localDirList`* *`localDir`* +  *`localDir`* | *`localDirList`* *`localDir`* *`localList`*\ -    *`localDef`* | *`localList`* *`localDef`* +  *`localDef`* | *`localList`* *`localDef`* *`macroArg`*\ -    **`%`** *`constExpr`*\ -    | **`%`** *`textMacroId`*\ -    | **`%`** *`macroFuncId`* **`(`** *`macroArgList`* **`)`**\ -    | *`string`*\ -    | *`arbitraryText`*\ -    | **`<`** *`arbitraryText`* **`>`** +  **`%`** *`constExpr`*\ +  | **`%`** *`textMacroId`*\ +  | **`%`** *`macroFuncId`* **`(`** *`macroArgList`* **`)`**\ +  | *`string`*\ +  | *`arbitraryText`*\ +  | **`<`** *`arbitraryText`* **`>`** *`macroArgList`*\ -    *`macroArg`* | *`macroArgList`* **`,`** *`macroArg`* +  *`macroArg`* | *`macroArgList`* **`,`** *`macroArg`* *`macroBody`*\ -    ⟦ *`localList`* ⟧ *`macroStmtList`* +  ⟦ *`localList`* ⟧ *`macroStmtList`* *`macroCall`*\ -    *`id`* *`macroArgList`* *`;;`*\ -    | *`id`* ( *`macroArgList`* ) +  *`id`* *`macroArgList`* *`;;`*\ +  | *`id`* **`(`** *`macroArgList`* **`)`** *`macroDir`*\ -    *`id`* **`MACRO`** ⟦ *`macroParmList`* ⟧ *`;;`*\ -    *`macroBody`*\ -    **`ENDM`** *`;;`* +  *`id`* **`MACRO`** ⟦ *`macroParmList`* ⟧ *`;;`*\ +  *`macroBody`*\ +  **`ENDM`** *`;;`* *`macroFor`*\ -    *`forDir`* *`forParm`* **`,`** **`<`** *`macroArgList`* **`>`** *`;;`*\ -    *`macroBody`*\ -    **`ENDM`** *`;;`* +  *`forDir`* *`forParm`* **`,`** **`<`** *`macroArgList`* **`>`** *`;;`*\ +  *`macroBody`*\ +  **`ENDM`** *`;;`* *`macroForc`*\ -    *`forcDir`* *`id`* **`,`** *`textLiteral`* *`;;`*\ -    *`macroBody`*\ -    **`ENDM`** *`;;`* +  *`forcDir`* *`id`* **`,`** *`textLiteral`* *`;;`*\ +  *`macroBody`*\ +  **`ENDM`** *`;;`* *`macroFuncId`*\ -    *`id`* +  *`id`* *`macroId`*\ -    *`macroProcId`* | *`macroFuncId`* +  *`macroProcId`* | *`macroFuncId`* *`macroIdList`*\ -    *`macroId`* | *`macroIdList`* **`,`** *`macroId`* +  *`macroId`* | *`macroIdList`* **`,`** *`macroId`* *`macroLabel`*\ -    *`id`* +  *`id`* *`macroParm`*\ -    *`id`* ⟦ **`:`** *`parmType`* ⟧ +  *`id`* ⟦ **`:`** *`parmType`* ⟧ *`macroParmList`*\ -    *`macroParm`* | *`macroParmList`* **`,`** ⟦ *`;;`* ⟧ *`macroParm`* +  *`macroParm`* | *`macroParmList`* **`,`** ⟦ *`;;`* ⟧ *`macroParm`* *`macroProcId`*\ -    *`id`* +  *`id`* *`macroRepeat`*\ -    *`repeatDir`* *`constExpr`* *`;;`*\ -    *`macroBody`*\ -    **`ENDM`** *`;;`* +  *`repeatDir`* *`constExpr`* *`;;`*\ +  *`macroBody`*\ +  **`ENDM`** *`;;`* *`macroStmt`*\ -    *`directive`* \ -    | *`exitmDir`*\ -    | **`:`** *`macroLabel`*\ -    | **`GOTO`** *`macroLabel`* +  *`directive`* \ +  | *`exitmDir`*\ +  | **`:`** *`macroLabel`*\ +  | **`GOTO`** *`macroLabel`* *`macroStmtList`*\ -    *`macroStmt`* *`;;`*\ -    | *`macroStmtList`* *`macroStmt`* *`;;`*\ +  *`macroStmt`* *`;;`*\ +  | *`macroStmtList`* *`macroStmt`* *`;;`* *`macroWhile`*\ -    **`WHILE`** *`constExpr`* *`;;`*\ -    *`macroBody`*\ -    **`ENDM`** *`;;`* +  **`WHILE`** *`constExpr`* *`;;`*\ +  *`macroBody`*\ +  **`ENDM`** *`;;`* *`mapType`*\ -    **`ALL`** | **`NONE`** | **`NOTPUBLIC`** +  **`ALL`** | **`NONE`** | **`NOTPUBLIC`** *`memOption`*\ -    **`TINY`** | **`SMALL`** | **`MEDIUM`** | **`COMPACT`** | **`LARGE`** | **`HUGE`** | **`FLAT`** +  **`TINY`** | **`SMALL`** | **`MEDIUM`** | **`COMPACT`** | **`LARGE`** | **`HUGE`** | **`FLAT`** *`mnemonic`*\ -    Instruction name. +  Instruction name. *`modelDir`*\ -    **`.MODEL`**\ -    *`memOption`* ⟦ **`,`** *`modelOptlist`* ⟧ *`;;`* +  **`.MODEL`** *`memOption`* ⟦ **`,`** *`modelOptlist`* ⟧ *`;;`* *`modelOpt`*\ -    *`langType`* | *`stackOption`* +  *`langType`* | *`stackOption`* *`modelOptlist`*\ -    *`modelOpt`* | *`modelOptlist`* **`,`** *`modelOpt`* +  *`modelOpt`* | *`modelOptlist`* **`,`** *`modelOpt`* *`module`*\ -    ⟦ *`directiveList`* ⟧ *`endDir`* +  ⟦ *`directiveList`* ⟧ *`endDir`* *`mulOp`*\ -    **`*`** | **`/`** | **`MOD`** +  **`*`** | **`/`** | **`MOD`** *`nameDir`*\ -    **`NAME`**\ -    *`id`* *`;;`* +  **`NAME`** *`id`* *`;;`* *`nearfar`*\ -    **`NEAR`** | **`FAR`** +  **`NEAR`** | **`FAR`** *`nestedStruct`*\ -    *`structHdr`* ⟦ *`id`* ⟧ *`;;`*\ -    *`structBody`*\ -    **`ENDS`** *`;;`* +  *`structHdr`* ⟦ *`id`* ⟧ *`;;`*\ +  *`structBody`*\ +  **`ENDS`** *`;;`* *`offsetDir`*\ -    *`offsetDirType`* *`;;`* +  *`offsetDirType`* *`;;`* *`offsetDirType`*\ -    **`EVEN`** | **`ORG`** *`immExpr`* | **`ALIGN`** ⟦ *`constExpr`* ⟧ +  **`EVEN`**\ +  | **`ORG`** *`immExpr`*\ +  | **`ALIGN`** ⟦ *`constExpr`* ⟧ *`offsetType`*\ -    **`GROUP`** | **`SEGMENT`** | **`FLAT`** +  **`GROUP`** | **`SEGMENT`** | **`FLAT`** *`oldRecordFieldList`*\ -    ⟦ *`constExpr`* ⟧ | *`oldRecordFieldList`* **`,`** ⟦ *`constExpr`* ⟧ +  ⟦ *`constExpr`* ⟧ | *`oldRecordFieldList`* **`,`** ⟦ *`constExpr`* ⟧ *`optionDir`*\ -    **`OPTION`** *`optionList`* *`;;`* +  **`OPTION`** *`optionList`* *`;;`* *`optionItem`*\ -    **`CASEMAP`** : *`mapType`*\ -    | **`DOTNAME`** | **`NODOTNAME`**\ -    | **`EMULATOR`** | **`NOEMULATOR`**\ -    | **`EPILOGUE`** **`:`** *`macroId`*\ -    | **`EXPR16`** | **`EXPR32`**\ -    | **`LANGUAGE`** **`:`** *`langType`*\ -    | **`LJMP`** | **`NOLJMP`**\ -    | **`M510`** | **`NOM510`**\ -    | **`NOKEYWORD`** **`:`** **`<`** *`keywordList`* **`>`**\ -    | **`NOSIGNEXTEND`**\ -    | **`OFFSET`** **`:`** *`offsetType`*\ -    | **`OLDMACROS`** | **`NOOLDMACROS`**\ -    | **`OLDSTRUCTS`** | **`NOOLDSTRUCTS`**\ -    | **`PROC`** **`:`** *`oVisibility`*\ -    | **`PROLOGUE`** : *`macroId`*\ -    | **`READONLY`** | **`NOREADONLY`**\ -    | **`SCOPED`** | **`NOSCOPED`**\ -    | **`SEGMENT`** **`:`** *`segSize`*\ -    | **`SETIF2`** **`:`** *`bool`* +  **`CASEMAP`** **`:`** *`mapType`*\ +  | **`DOTNAME`** | **`NODOTNAME`**\ +  | **`EMULATOR`** | **`NOEMULATOR`**\ +  | **`EPILOGUE`** **`:`** *`macroId`*\ +  | **`EXPR16`** | **`EXPR32`**\ +  | **`LANGUAGE`** **`:`** *`langType`*\ +  | **`LJMP`** | **`NOLJMP`**\ +  | **`M510`** | **`NOM510`**\ +  | **`NOKEYWORD`** **`:`** **`<`** *`keywordList`* **`>`**\ +  | **`NOSIGNEXTEND`**\ +  | **`OFFSET`** **`:`** *`offsetType`*\ +  | **`OLDMACROS`** | **`NOOLDMACROS`**\ +  | **`OLDSTRUCTS`** | **`NOOLDSTRUCTS`**\ +  | **`PROC`** **`:`** *`oVisibility`*\ +  | **`PROLOGUE`** **`:`** *`macroId`*\ +  | **`READONLY`** | **`NOREADONLY`**\ +  | **`SCOPED`** | **`NOSCOPED`**\ +  | **`SEGMENT`** **`:`** *`segSize`*\ +  | **`SETIF2`** **`:`** *`bool`* *`optionList`*\ -    *`optionItem`* | *`optionList`* **`,`** ⟦ *`;;`* ⟧ *`optionItem`* +  *`optionItem`* | *`optionList`* **`,`** ⟦ *`;;`* ⟧ *`optionItem`* *`optText`*\ -    **`,`** *`textItem`* +  **`,`** *`textItem`* *`orOp`*\ -    **`OR`** | **`XOR`** +  **`OR`** | **`XOR`** *`oVisibility`*\ -    **`PUBLIC`** | **`PRIVATE`** | **`EXPORT`** +  **`PUBLIC`** | **`PRIVATE`** | **`EXPORT`** *`pageDir`*\ -    **`PAGE`** ⟦ *`pageExpr`* ⟧ *`;;`* +  **`PAGE`** ⟦ *`pageExpr`* ⟧ *`;;`* *`pageExpr`*\ -    **`+`** | ⟦ *`pageLength`* ⟧ ⟦ **`,`** *`pageWidth`* ⟧ +  **`+`** | ⟦ *`pageLength`* ⟧ ⟦ **`,`** *`pageWidth`* ⟧ *`pageLength`*\ -    *`constExpr`* +  *`constExpr`* *`pageWidth`*\ -    *`constExpr`* +  *`constExpr`* *`parm`*\ -    *`parmId`* ⟦ **`:`** *`qualifiedType`* ⟧ | *`parmId`* ⟦ *`constExpr`* ⟧ ⟦ **`:`** *`qualifiedType`* ⟧ +  *`parmId`* ⟦ **`:`** *`qualifiedType`* ⟧\ +  | *`parmId`* ⟦ *`constExpr`* ⟧ ⟦ **`:`** *`qualifiedType`* ⟧ *`parmId`*\ -    *`id`* +  *`id`* *`parmList`*\ -    *`parm`* | *`parmList`* **`,`** ⟦ *`;;`* ⟧ *`parm`* +  *`parm`* | *`parmList`* **`,`** ⟦ *`;;`* ⟧ *`parm`* *`parmType`*\ -    **`REQ`** | **`=`** *`textLiteral`* | **`VARARG`** +  **`REQ`** | **`=`** *`textLiteral`* | **`VARARG`** *`pOptions`*\ -    ⟦ *`distance`* ⟧ ⟦ *`langType`* ⟧ ⟦ *`oVisibility`* ⟧ +  ⟦ *`distance`* ⟧ ⟦ *`langType`* ⟧ ⟦ *`oVisibility`* ⟧ *`primary`*\ -    *`expr`* *`binaryOp`* *`expr`* | *`flagName`* | *`expr`* +  *`expr`* *`binaryOp`* *`expr`* | *`flagName`* | *`expr`* *`procDir`*\ -    *`procId`* **`PROC`**\ -    ⟦ *`pOptions`* ⟧ ⟦ **`<`** *`macroArgList`* **`>`** ⟧\ -    ⟦ *`usesRegs`* ⟧ ⟦ *`procParmList`* ⟧ +  *`procId`* **`PROC`** ⟦ *`pOptions`* ⟧ ⟦ **`<`** *`macroArgList`* **`>`** ⟧\ +  ⟦ *`usesRegs`* ⟧ ⟦ *`procParmList`* ⟧ *`processor`*\ -    | **`.386`** | **`.386p`** | **`.486`** | **`.486P`**\ -    | **`.586`** | **`.586P`** | **`.686`** | **`.686P`** | **`.387`** +  | **`.386`** | **`.386p`** | **`.486`** | **`.486P`**\ +  | **`.586`** | **`.586P`** | **`.686`** | **`.686P`** | **`.387`** *`processorDir`*\ -    *`processor`* *`;;`*\ -    | *`coprocessor`* *`;;`* +  *`processor`* *`;;`*\ +  | *`coprocessor`* *`;;`* *`procId`*\ -    *`id`* +  *`id`* *`procItem`*\ -    *`instrPrefix`* | *`dataDir`* | *`labelDir`* | *`offsetDir`* | *`generalDir`* +  *`instrPrefix`* | *`dataDir`* | *`labelDir`* | *`offsetDir`* | *`generalDir`* *`procParmList`*\ -    ⟦ **`,`** ⟦ *`;;`* ⟧ *`parmList`* ⟧\ -    ⟦ **`,`** ⟦ *`;;`* ⟧ *`parmId`* **`:VARARG`** ⟧ +  ⟦ **`,`** ⟦ *`;;`* ⟧ *`parmList`* ⟧\ +  ⟦ **`,`** ⟦ *`;;`* ⟧ *`parmId`* **`:VARARG`** ⟧ *`protoArg`*\ -    ⟦ *`id`* ⟧ **`:`** *`qualifiedType`* +  ⟦ *`id`* ⟧ **`:`** *`qualifiedType`* *`protoArgList`*\ -    ⟦ **`,`** ⟦ *`;;`* ⟧ *`protoList`* ⟧\ -    ⟦ **`,`** ⟦ *`;;`* ⟧ ⟦ *`id`* ⟧ **`:VARARG`** ⟧ +  ⟦ **`,`** ⟦ *`;;`* ⟧ *`protoList`* ⟧\ +  ⟦ **`,`** ⟦ *`;;`* ⟧ ⟦ *`id`* ⟧ **`:VARARG`** ⟧ *`protoList`*\ -    *`protoArg`*\ -    | *`protoList`* **`,`** ⟦ *`;;`* ⟧ *`protoArg`* +  *`protoArg`*\ +  | *`protoList`* **`,`** ⟦ *`;;`* ⟧ *`protoArg`* *`protoSpec`*\ -    ⟦ *`distance`* ⟧ ⟦ *`langType`* ⟧ ⟦ *`protoArgList`* ⟧ | *`typeId`* +  ⟦ *`distance`* ⟧ ⟦ *`langType`* ⟧ ⟦ *`protoArgList`* ⟧\ +  | *`typeId`* *`protoTypeDir`*\ -    *`id`* **`PROTO`** *`protoSpec`* +  *`id`* **`PROTO`** *`protoSpec`* *`pubDef`*\ -    ⟦ *`langType`* ⟧ *`id`* +  ⟦ *`langType`* ⟧ *`id`* *`publicDir`*\ -    **`PUBLIC`** *`pubList`* *`;;`* +  **`PUBLIC`** *`pubList`* *`;;`* *`pubList`*\ -    *`pubDef`* | *`pubList`* **`,`** ⟦ *`;;`* ⟧ *`pubDef`* +  *`pubDef`* | *`pubList`* **`,`** ⟦ *`;;`* ⟧ *`pubDef`* *`purgeDir`*\ -    **`PURGE`** *`macroIdList`* +  **`PURGE`** *`macroIdList`* *`qualifiedType`*\ -    *`type`* | ⟦ *`distance`* ⟧ **`PTR`** ⟦ *`qualifiedType`* ⟧ +  *`type`*\ +  | ⟦ *`distance`* ⟧ **`PTR`** ⟦ *`qualifiedType`* ⟧ *`qualifier`*\ -    *`qualifiedType`* | **`PROTO`** *`protoSpec`* +  *`qualifiedType`* | **`PROTO`** *`protoSpec`* *`quote`*\ -    **`"`** | **`'`** +  **`"`** | **`'`** *`qwordRegister`*\ -    **`RAX`** | **`RCX`** | **`RDX`** | **`RBX`** | **`RDI`** | **`RSI`** | **`RBP`** | **`R8`** | **`R9`** | **`R10`** | **`R11`** | **`R12`** | **`R13`** | **`R14`** | **`R15`** +  **`RAX`** | **`RCX`** | **`RDX`** | **`RBX`** | **`RSP`** | **`RBP`** | **`RSI`** | **`RDI`**\ +  | **`R8`** | **`R9`** | **`R10`** | **`R11`** | **`R12`** | **`R13`** | **`R14`** | **`R15`** *`radixDir`*\ -    **`.RADIX`** *`constExpr`* *`;;`* +  **`.RADIX`** *`constExpr`* *`;;`* *`radixOverride`*\ -    **`h`** | **`o`** | **`q`** | **`t`** | **`y`** | **`H`** | **`O`** | **`Q`** | **`T`** | **`Y`** +  **`h`** | **`o`** | **`q`** | **`t`** | **`y`**\ +  | **`H`** | **`O`** | **`Q`** | **`T`** | **`Y`** *`recordConst`*\ -    *`recordTag`* **`{`** *`oldRecordFieldList`* **`}`** | *`recordTag`* **`<`** *`oldRecordFieldList`* **`>`** +  *`recordTag`* **`{`** *`oldRecordFieldList`* **`}`**\ +  | *`recordTag`* **`<`** *`oldRecordFieldList`* **`>`** *`recordDir`*\ -    *`recordTag`* **`RECORD`** *`bitDefList`* *`;;`* +  *`recordTag`* **`RECORD`** *`bitDefList`* *`;;`* *`recordFieldList`*\ -    ⟦ *`constExpr`* ⟧ | *`recordFieldList`* **`,`** ⟦ *`;;`* ⟧ ⟦ *`constExpr`* ⟧ +  ⟦ *`constExpr`* ⟧ | *`recordFieldList`* **`,`** ⟦ *`;;`* ⟧ ⟦ *`constExpr`* ⟧ *`recordInstance`*\ -    **`{`** ⟦ *`;;`* ⟧ *`recordFieldList`* ⟦ *`;;`* ⟧ **`}`**\ -    | **`<`** *`oldRecordFieldList`* **`>`**\ -    | *`constExpr`* **`DUP`** **`(`** *`recordInstance`* **`)`** +  **`{`** ⟦ *`;;`* ⟧ *`recordFieldList`* ⟦ *`;;`* ⟧ **`}`**\ +  | **`<`** *`oldRecordFieldList`* **`>`**\ +  | *`constExpr`* **`DUP`** **`(`** *`recordInstance`* **`)`** *`recordInstList`*\ -    *`recordInstance`* | *`recordInstList`* **`,`** ⟦ *`;;`* ⟧ *`recordInstance`* +  *`recordInstance`* | *`recordInstList`* **`,`** ⟦ *`;;`* ⟧ *`recordInstance`* *`recordTag`*\ -    *`id`* +  *`id`* *`register`*\ -    *`specialRegister`* | *`gpRegister`* | *`byteRegister`* | *`qwordRegister`* | *`fpuRegister`* | *`SIMDRegister`* | *`segmentRegister`* +  *`specialRegister`* | *`gpRegister`* | *`byteRegister`* | *`qwordRegister`* | *`fpuRegister`* | *`SIMDRegister`* | *`segmentRegister`* *`regList`*\ -    *`register`* | *`regList`* *`register`* +  *`register`* | *`regList`* *`register`* *`relOp`*\ -    **`EQ`** | **`NE`** | **`LT`** | **`LE`** | **`GT`** | **`GE`** +  **`EQ`** | **`NE`** | **`LT`** | **`LE`** | **`GT`** | **`GE`** *`repeatBlock`*\ -    **`.REPEAT`** *`;;`*\ -    *`blockStatements`* *`;;`* +  **`.REPEAT`** *`;;`*\ +  *`blockStatements`* *`;;`* *`untilDir`* *`;;`* *`repeatDir`*\ -    **`REPEAT`** | **`REPT`** +  **`REPEAT`** | **`REPT`** *`scalarInstList`*\ -    *`initValue`* | *`scalarInstList`* **`,`** ⟦ *`;;`* ⟧ *`initValue`* +  *`initValue`*\ +  | *`scalarInstList`* **`,`** ⟦ *`;;`* ⟧ *`initValue`* *`segAlign`*\ -    **`BYTE`** | **`WORD`** | **`DWORD`** | **`PARA`** | **`PAGE`** +  **`BYTE`** | **`WORD`** | **`DWORD`** | **`PARA`** | **`PAGE`** *`segAttrib`*\ -    **`PUBLIC`** | **`STACK`** | **`COMMON`** | **`MEMORY`** | **`AT`** *`constExpr`* | **`PRIVATE`** +  **`PUBLIC`** | **`STACK`** | **`COMMON`** | **`MEMORY`** | **`AT`** *`constExpr`* | **`PRIVATE`** *`segDir`*\ -    **`.CODE`**\ -    ⟦ *`segId`* ⟧\ -    | **`.DATA`**\ -    | **`.DATA?`**\ -    | **`.CONST`**\ -    | **`.FARDATA`**⟦ *`segId`* ⟧\ -    | **`.FARDATA?`** ⟦ *`segId`* ⟧\ -    | **`.STACK`** ⟦ *`constExpr`* ⟧ +  **`.CODE`** ⟦ *`segId`* ⟧\ +  | **`.DATA`**\ +  | **`.DATA?`**\ +  | **`.CONST`**\ +  | **`.FARDATA`** ⟦ *`segId`* ⟧\ +  | **`.FARDATA?`** ⟦ *`segId`* ⟧\ +  | **`.STACK`** ⟦ *`constExpr`* ⟧ *`segId`*\ -    *`id`* +  *`id`* *`segIdList`*\ -    *`segId`*\ -    | *`segIdList`* **`,`** *`segId`* +  *`segId`*\ +  | *`segIdList`* **`,`** *`segId`* *`segmentDef`*\ -    *`segmentDir`* ⟦ *`inSegDirList`* ⟧ *`endsDir`* | *`simpleSegDir`* ⟦ *`inSegDirList`* ⟧ ⟦ *`endsDir`* ⟧ +  *`segmentDir`* ⟦ *`inSegDirList`* ⟧ *`endsDir`* | *`simpleSegDir`* ⟦ *`inSegDirList`* ⟧ ⟦ *`endsDir`* ⟧ *`segmentDir`*\ -    *`segId`* **`SEGMENT`** ⟦ *`segOptionList`* ⟧ *`;;`* +  *`segId`* **`SEGMENT`** ⟦ *`segOptionList`* ⟧ *`;;`* *`segmentRegister`*\ -    **`CS`** | **`DS`** | **`ES`** | **`FS`** | **`GS`** | **`SS`** +  **`CS`** | **`DS`** | **`ES`** | **`FS`** | **`GS`** | **`SS`** *`segOption`*\ -    *`segAlign`*\ -    | *`segRO`*\ -    | *`segAttrib`*\ -    | *`segSize`*\ -    | *`className`* +  *`segAlign`*\ +  | *`segRO`*\ +  | *`segAttrib`*\ +  | *`segSize`*\ +  | *`className`* *`segOptionList`*\ -    *`segOption`* | *`segOptionList`* *`segOption`* +  *`segOption`* | *`segOptionList`* *`segOption`* *`segOrderDir`*\ -    **`.ALPHA`** | **`.SEQ`** | **`.DOSSEG`** | **`DOSSEG`** +  **`.ALPHA`** | **`.SEQ`** | **`.DOSSEG`** | **`DOSSEG`** *`segRO`*\ -    **`READONLY`** +  **`READONLY`** *`segSize`*\ -    **`USE16`** | **`USE32`** | **`FLAT`** +  **`USE16`** | **`USE32`** | **`FLAT`** *`shiftOp`*\ -    **`SHR`** | **`SHL`** +  **`SHR`** | **`SHL`** *`sign`*\ -    **`+`** | **`-`** +  **`+`** | **`-`** *`simdRegister`*\ -    **`MM0`** | **`MM1`** | **`MM2`** | **`MM3`** | **`MM4`** | **`MM5`** | **`MM6`** | **`MM7`**\ -    | *`xmmRegister`*\ -    | **`YMM0`** | **`YMM1`** | **`YMM2`** | **`YMM3`** | **`YMM4`** | **`YMM5`** | **`YMM6`** | **`YMM7`** | **`YMM8`** | **`YMM9`** | **`YMM10`** | **`YMM11`** | **`YMM12`** | **`YMM13`** | **`YMM14`** | **`YMM15`** +  **`MM0`** | **`MM1`** | **`MM2`** | **`MM3`** | **`MM4`** | **`MM5`** | **`MM6`** | **`MM7`**\ +  | *`xmmRegister`*\ +  | **`YMM0`** | **`YMM1`** | **`YMM2`** | **`YMM3`** | **`YMM4`** | **`YMM5`** | **`YMM6`** | **`YMM7`**\ +  | **`YMM8`** | **`YMM9`** | **`YMM10`** | **`YMM11`** | **`YMM12`** | **`YMM13`** | **`YMM14`** | **`YMM15`** *`simpleExpr`*\ -    **`(`** *`cExpr`* **`)`** | *`primary`* +  **`(`** *`cExpr`* **`)`** | *`primary`* *`simpleSegDir`*\ -    *`segDir`* *`;;`* +  *`segDir`* *`;;`* *`sizeArg`*\ -    *`id`* | *`type`* | *`e10`* +  *`id`* | *`type`* | *`e10`* *`specialChars`*\ -    **`:`** | **`.`** | **`[`** | **`]`** | **`(`** | **`)`** | **`<`** | **`>`** | **`{`** | **`}`**\ -    | **`+`** | **`-`** | **`/`** | **`*`** | **`&`** | **`%`** | **`!`**\ -    | **`'`** | **`\`** | **`=`** | **`;`** | **`,`** | **`"`**\ -    | *`whiteSpaceCharacter`*\ -    | *`endOfLine`* +  **`:`** | **`.`** | **`[`** | **`]`** | **`(`** | **`)`** | **`<`** | **`>`** | **`{`** | **`}`**\ +  | **`+`** | **`-`** | **`/`** | **`*`** | **`&`** | **`%`** | **`!`**\ +  | **`'`** | **`\`** | **`=`** | **`;`** | **`,`** | **`"`**\ +  | *`whiteSpaceCharacter`*\ +  | *`endOfLine`* *`specialRegister`*\ -    **`CR0`** | **`CR2`** | **`CR3`** | **`DR0`** | **`DR1`** | **`DR2`** | **`DR3`** | **`DR6`** | **`DR7`** | **`TR3`** | **`TR4`** | **`TR5`** | **`TR6`** | **`TR7`** +  **`CR0`** | **`CR2`** | **`CR3`**\ +  | **`DR0`** | **`DR1`** | **`DR2`** | **`DR3`** | **`DR6`** | **`DR7`**\ +  | **`TR3`** | **`TR4`** | **`TR5`** | **`TR6`** | **`TR7`** *`stackOption`*\ -    **`NEARSTACK`** | **`FARSTACK`** +  **`NEARSTACK`** | **`FARSTACK`** *`startupDir`*\ -    **`.STARTUP`** *`;;`* +  **`.STARTUP`** *`;;`* *`stext`*\ -    *`stringChar`* | *`stext`* *`stringChar`* +  *`stringChar`* | *`stext`* *`stringChar`* *`string`*\ -    *`quote`* ⟦ *`stext`* ⟧ *`quote`* +  *`quote`* ⟦ *`stext`* ⟧ *`quote`* *`stringChar`*\ -    *`quote`* *`quote`* | Any character except quote. +  *`quote`* *`quote`* | Any character except quote. *`structBody`*\ -    *`structItem`* *`;;`*\ -    | *`structBody`* *`structItem`* *`;;`* +  *`structItem`* *`;;`*\ +  | *`structBody`* *`structItem`* *`;;`* *`structDir`*\ -    *`structTag`* *`structHdr`* ⟦ *`fieldAlign`* ⟧\ -    ⟦ **`,`** **`NONUNIQUE`** ⟧ *`;;`*\ -    *`structBody`*\ -    *`structTag`*\ -    **`ENDS`** *`;;`* +  *`structTag`* *`structHdr`* ⟦ *`fieldAlign`* ⟧\ +  ⟦ **`,`** **`NONUNIQUE`** ⟧ *`;;`*\ +  *`structBody`*\ +  *`structTag`* **`ENDS`** *`;;`* *`structHdr`*\ -    **`STRUC`** | **`STRUCT`** | **`UNION`** +  **`STRUC`** | **`STRUCT`** | **`UNION`** *`structInstance`*\ -    **`<`** ⟦ *`fieldInitList`* ⟧ **`>`**\ -    | **`{`** ⟦ *`;;`* ⟧ ⟦ *`fieldInitList`* ⟧ ⟦ *`;;`* ⟧ **`}`**\ -    | *`constExpr`* **`DUP`** ( *`structInstList`* ) +  **`<`** ⟦ *`fieldInitList`* ⟧ **`>`**\ +  | **`{`** ⟦ *`;;`* ⟧ ⟦ *`fieldInitList`* ⟧ ⟦ *`;;`* ⟧ **`}`**\ +  | *`constExpr`* **`DUP`** ( *`structInstList`* ) *`structInstList`*\ -    *`structInstance`* | *`structInstList`* **`,`** ⟦ *`;;`* ⟧ *`structInstance`* +  *`structInstance`* | *`structInstList`* **`,`** ⟦ *`;;`* ⟧ *`structInstance`* *`structItem`*\ -    *`dataDir`*\ -    | *`generalDir`*\ -    | *`offsetDir`*\ -    | *`nestedStruct`* +  *`dataDir`*\ +  | *`generalDir`*\ +  | *`offsetDir`*\ +  | *`nestedStruct`* *`structTag`*\ -    *`id`* +  *`id`* *`term`*\ -    *`simpleExpr`* | **`!`** *`simpleExpr`* +  *`simpleExpr`* | **`!`** *`simpleExpr`* *`text`*\ -    *`textLiteral`* | *`text`* character | **`!`** *`character`* *`text`* | *`character`* | **`!`** *`character`* +  *`textLiteral`* | *`text`* *`character`* | **`!`** *`character`* *`text`* | *`character`* | **`!`** *`character`* *`textDir`*\ -    *`id`* *`textMacroDir`* *`;;`* +  *`id`* *`textMacroDir`* *`;;`* *`textItem`*\ -    *`textLiteral`* | *`textMacroId`* | **`%`** *`constExpr`* +  *`textLiteral`* | *`textMacroId`* | **`%`** *`constExpr`* *`textLen`*\ -    *`constExpr`* +  *`constExpr`* *`textList`*\ -    *`textItem`* | *`textList`* **`,`** ⟦ *`;;`* ⟧ *`textItem`* +  *`textItem`* | *`textList`* **`,`** ⟦ *`;;`* ⟧ *`textItem`* *`textLiteral`*\ -    **`<`** *`text`* **`>`** **`;;`** +  **`<`** *`text`* **`>`** **`;;`** *`textMacroDir`*\ -    **`CATSTR`** ⟦ *`textList`* ⟧\ -    | **`TEXTEQU`** ⟦ *`textList`* ⟧\ -    | **`SIZESTR`** *`textItem`*\ -    | **`SUBSTR`** *`textItem`* **`,`** *`textStart`* ⟦ **`,`** *`textLen`* ⟧\ -    | **`INSTR`** ⟦ *`textStart`* **`,`** ⟧ *`textItem`* **`,`** *`textItem`* +  **`CATSTR`** ⟦ *`textList`* ⟧\ +  | **`TEXTEQU`** ⟦ *`textList`* ⟧\ +  | **`SIZESTR`** *`textItem`*\ +  | **`SUBSTR`** *`textItem`* **`,`** *`textStart`* ⟦ **`,`** *`textLen`* ⟧\ +  | **`INSTR`** ⟦ *`textStart`* **`,`** ⟧ *`textItem`* **`,`** *`textItem`* *`textMacroId`*\ -    *`id`* +  *`id`* *`textStart`*\ -    *`constExpr`* +  *`constExpr`* *`titleDir`*\ -    *`titleType`* *`arbitraryText`* *`;;`* +  *`titleType`* *`arbitraryText`* *`;;`* *`titleType`*\ -    **`TITLE`** | **`SUBTITLE`** | **`SUBTTL`** +  **`TITLE`** | **`SUBTITLE`** | **`SUBTTL`** *`type`*\ -    *`structTag`*\ -    | *`unionTag`*\ -    | *`recordTag`*\ -    | *`distance`*\ -    | *`dataType`*\ -    | *`typeId`* +  *`structTag`*\ +  | *`unionTag`*\ +  | *`recordTag`*\ +  | *`distance`*\ +  | *`dataType`*\ +  | *`typeId`* *`typedefDir`*\ -    *`typeId`* **`TYPEDEF`** qualifier +  *`typeId`* **`TYPEDEF`** *`qualifier`* *`typeId`*\ -    *`id`* +  *`id`* *`unionTag`*\ -    *`id`* +  *`id`* *`untilDir`*\ -    **`.UNTIL`** *`cExpr`* *`;;`*\ -    **`.UNTILCXZ`** ⟦ *`cxzExpr`* ⟧ *`;;`* +  **`.UNTIL`** *`cExpr`* *`;;`*\ +  **`.UNTILCXZ`** ⟦ *`cxzExpr`* ⟧ *`;;`* *`usesRegs`*\ -    **`USES`** *`regList`* +  **`USES`** *`regList`* *`whileBlock`*\ -    **`.WHILE`**\ -    *`cExpr`* *`;;`*\ -    *`blockStatements`* *`;;`*\ -    **`.ENDW`** +  **`.WHILE`** *`cExpr`* *`;;`*\ +  *`blockStatements`* *`;;`*\ +  **`.ENDW`** *`whiteSpaceCharacter`*\ -    ASCII 8, 9, 11–13, 26, 32 +  ASCII 8, 9, 11–13, 26, 32 *`xmmRegister`*\ -    **`XMM0`** | **`XMM1`** | **`XMM2`** | **`XMM3`** | **`XMM4`** | **`XMM5`** | **`XMM6`** | **`XMM7`** | **`XMM8`** | **`XMM9`** | **`XMM10`** | **`XMM11`** | **`XMM12`** | **`XMM13`** | **`XMM14`** | **`XMM15`** +  **`XMM0`** | **`XMM1`** | **`XMM2`** | **`XMM3`** | **`XMM4`** | **`XMM5`** | **`XMM6`** | **`XMM7`**\ +  | **`XMM8`** | **`XMM9`** | **`XMM10`** | **`XMM11`** | **`XMM12`** | **`XMM13`** | **`XMM14`** | **`XMM15`** diff --git a/docs/assembler/masm/masm-for-x64-ml64-exe.md b/docs/assembler/masm/masm-for-x64-ml64-exe.md index 983bb96ce5..840b002083 100644 --- a/docs/assembler/masm/masm-for-x64-ml64-exe.md +++ b/docs/assembler/masm/masm-for-x64-ml64-exe.md @@ -1,22 +1,22 @@ --- +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 @@ -26,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) @@ -62,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 0c9394b9c7..1cf7f09461 100644 --- a/docs/assembler/masm/microsoft-macro-assembler-reference.md +++ b/docs/assembler/masm/microsoft-macro-assembler-reference.md @@ -1,20 +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. @@ -25,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 @@ -43,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 d76ec8d21c..60ef663335 100644 --- a/docs/assembler/masm/ml-error-messages.md +++ b/docs/assembler/masm/ml-error-messages.md @@ -1,7 +1,8 @@ --- +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 0885bc7cbe..64c18b9e37 100644 --- a/docs/assembler/masm/ml-fatal-error-a1000.md +++ b/docs/assembler/masm/ml-fatal-error-a1000.md @@ -1,7 +1,8 @@ --- +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 bf1eb8e527..26a5522b82 100644 --- a/docs/assembler/masm/ml-fatal-error-a1005.md +++ b/docs/assembler/masm/ml-fatal-error-a1005.md @@ -1,7 +1,8 @@ --- +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 8b15feba10..8f6c7940ef 100644 --- a/docs/assembler/masm/ml-fatal-error-a1007.md +++ b/docs/assembler/masm/ml-fatal-error-a1007.md @@ -1,7 +1,8 @@ --- +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 505eda9744..c18d2492c9 100644 --- a/docs/assembler/masm/ml-fatal-error-a1008.md +++ b/docs/assembler/masm/ml-fatal-error-a1008.md @@ -1,7 +1,8 @@ --- +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 12f74a4eff..23fe9aee2c 100644 --- a/docs/assembler/masm/ml-fatal-error-a1009.md +++ b/docs/assembler/masm/ml-fatal-error-a1009.md @@ -1,7 +1,8 @@ --- +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 9ac0f39f86..0229ad3136 100644 --- a/docs/assembler/masm/ml-fatal-error-a1010.md +++ b/docs/assembler/masm/ml-fatal-error-a1010.md @@ -1,7 +1,8 @@ --- +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 b28861f913..6a5e3ea920 100644 --- a/docs/assembler/masm/ml-fatal-error-a1011.md +++ b/docs/assembler/masm/ml-fatal-error-a1011.md @@ -1,7 +1,8 @@ --- +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 7841721ddb..193e1af425 100644 --- a/docs/assembler/masm/ml-fatal-error-a1016.md +++ b/docs/assembler/masm/ml-fatal-error-a1016.md @@ -1,7 +1,8 @@ --- +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 ca5415129e..186314b280 100644 --- a/docs/assembler/masm/ml-fatal-error-a1017.md +++ b/docs/assembler/masm/ml-fatal-error-a1017.md @@ -1,7 +1,8 @@ --- +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 2eee7ef097..cb40f2e8d3 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2004.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2004.md @@ -1,7 +1,8 @@ --- +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 69ac5ca546..5eb17a38e6 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2006.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2006.md @@ -1,7 +1,8 @@ --- +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 760a172725..b648e40ee5 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2008.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2008.md @@ -1,7 +1,8 @@ --- +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 10c8c345f0..0037f31377 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2010.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2010.md @@ -1,16 +1,19 @@ --- +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 9e4c1fb7aa..90bd405bec 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2019.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2019.md @@ -1,7 +1,8 @@ --- +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 04f41707a2..8751e3f61e 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2022.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2022.md @@ -1,7 +1,8 @@ --- +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 06f8d98c1f..ca2b604bdc 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2031.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2031.md @@ -1,7 +1,8 @@ --- +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 75bfc9bf48..3f39de593f 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2034.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2034.md @@ -1,30 +1,33 @@ --- +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 8a8932857e..8f3aa5c882 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2037.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2037.md @@ -1,7 +1,8 @@ --- +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 9978c22bcf..cc8d4dc964 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2038.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2038.md @@ -1,7 +1,8 @@ --- +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 336e5ee7cf..055cb0540a 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2039.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2039.md @@ -1,7 +1,8 @@ --- +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 bdfe38b746..0997887d02 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2044.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2044.md @@ -1,7 +1,8 @@ --- +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 db2d1b1fe0..6896fe8592 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2047.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2047.md @@ -1,7 +1,8 @@ --- +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 251548f27c..924f38d3f9 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2050.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2050.md @@ -1,7 +1,8 @@ --- +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 7e6996c395..febf4f6c4e 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2054.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2054.md @@ -1,7 +1,8 @@ --- +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 70567c050f..54e57104a9 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2055.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2055.md @@ -1,7 +1,8 @@ --- +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 1c7d925a6f..98ba11536a 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2057.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2057.md @@ -1,7 +1,8 @@ --- +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 730ddb36e4..4f563d54ac 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2059.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2059.md @@ -1,7 +1,8 @@ --- +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 a4a5407850..3e74b86485 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2060.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2060.md @@ -1,7 +1,8 @@ --- +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 46110709d5..2da91f339b 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2063.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2063.md @@ -1,7 +1,8 @@ --- +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 7f763527e0..ed06a37737 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2064.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2064.md @@ -1,7 +1,8 @@ --- +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 59e6bc3e41..316f95333e 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2065.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2065.md @@ -1,7 +1,8 @@ --- +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 ca7f95c00d..f1583f30b5 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2066.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2066.md @@ -1,7 +1,8 @@ --- +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 88f4d0c959..5ebda337f1 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2069.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2069.md @@ -1,7 +1,8 @@ --- +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 3791bd9c8d..2267b0ccdd 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2070.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2070.md @@ -1,7 +1,8 @@ --- +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 1377c20ad2..50f575f954 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2074.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2074.md @@ -1,7 +1,8 @@ --- +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 cd8a17011d..0b287e79bd 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2078.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2078.md @@ -1,7 +1,8 @@ --- +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 cbd0e704f2..f04053fcc4 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2079.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2079.md @@ -1,7 +1,8 @@ --- +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 f72bc0e051..0e852033cd 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2083.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2083.md @@ -1,7 +1,8 @@ --- +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 07ed1484ad..70def6928d 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2085.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2085.md @@ -1,7 +1,8 @@ --- +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 5ecf341f99..f670b73aca 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2096.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2096.md @@ -1,7 +1,8 @@ --- +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 44b4dca8d9..abeea9f8f9 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2097.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2097.md @@ -1,7 +1,8 @@ --- +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 69b4f7e0b6..0c7b3ad230 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2107.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2107.md @@ -1,7 +1,8 @@ --- +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 920b340c9e..e19e92eb19 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2119.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2119.md @@ -1,7 +1,8 @@ --- +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 e4f5be9e0c..fa9872a213 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2133.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2133.md @@ -1,7 +1,8 @@ --- +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 98f7b28bb5..d9c908f94f 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2137.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2137.md @@ -1,7 +1,8 @@ --- +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 9cad2a3e36..2fca4c0dc4 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2189.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2189.md @@ -1,7 +1,8 @@ --- +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 858c629d20..8a1264fe6c 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2206.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2206.md @@ -1,7 +1,8 @@ --- +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 b155ecf9c7..7d6dc6b457 100644 --- a/docs/assembler/masm/ml-nonfatal-error-a2219.md +++ b/docs/assembler/masm/ml-nonfatal-error-a2219.md @@ -1,7 +1,8 @@ --- +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 @@ -12,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 6679a85904..ee4e7df825 100644 --- a/docs/assembler/masm/ml-warning-a4004.md +++ b/docs/assembler/masm/ml-warning-a4004.md @@ -1,7 +1,8 @@ --- +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 a873a3c856..52fe3645e8 100644 --- a/docs/assembler/masm/ml-warning-a4012.md +++ b/docs/assembler/masm/ml-warning-a4012.md @@ -1,7 +1,8 @@ --- +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 bdeea67e31..dbecdeb23c 100644 --- a/docs/assembler/masm/ml-warning-a4014.md +++ b/docs/assembler/masm/ml-warning-a4014.md @@ -1,7 +1,8 @@ --- +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/mmword.md b/docs/assembler/masm/mmword.md index 77556ca1a4..98ca862949 100644 --- a/docs/assembler/masm/mmword.md +++ b/docs/assembler/masm/mmword.md @@ -1,9 +1,9 @@ --- title: "MMWORD" -ms.date: "12/17/2019" +description: "Learn more about: MMWORD" +ms.date: 12/17/2019 f1_keywords: ["MMWORD"] helpviewer_keywords: ["MMWORD directive"] -ms.assetid: b4c5a104-9078-4fb4-afc3-d1e63abe562a --- # MMWORD @@ -31,6 +31,6 @@ While both instructions work on 64-bit operands, **QWORD** is the type for 64-bi movq mm0, mmword ptr [ebx] ``` -## See Also +## See also [MASM BNF Grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/name-masm.md b/docs/assembler/masm/name-masm.md index 2042473f9c..539c8342d5 100644 --- a/docs/assembler/masm/name-masm.md +++ b/docs/assembler/masm/name-masm.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: NAME" title: "NAME (MASM)" ms.date: "12/17/2019" helpviewer_keywords: ["NAME directive"] diff --git a/docs/assembler/masm/operator-abs.md b/docs/assembler/masm/operator-abs.md index 87149bd0c5..29eae96cf3 100644 --- a/docs/assembler/masm/operator-abs.md +++ b/docs/assembler/masm/operator-abs.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator ABS" title: "operator ABS" ms.date: "12/17/2019" f1_keywords: ["operator ABS"] diff --git a/docs/assembler/masm/operator-add.md b/docs/assembler/masm/operator-add.md index 64b02fb321..dd0e3d93a1 100644 --- a/docs/assembler/masm/operator-add.md +++ b/docs/assembler/masm/operator-add.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator +" title: "operator +" ms.date: "12/17/2019" f1_keywords: ["+", "operator +"] diff --git a/docs/assembler/masm/operator-addr.md b/docs/assembler/masm/operator-addr.md index 4408aaa3b5..9687a8cd64 100644 --- a/docs/assembler/masm/operator-addr.md +++ b/docs/assembler/masm/operator-addr.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator ADDR" title: "operator ADDR" ms.date: "12/17/2019" f1_keywords: ["ADDR", "operator ADDR"] diff --git a/docs/assembler/masm/operator-and.md b/docs/assembler/masm/operator-and.md index f838c32427..341867453b 100644 --- a/docs/assembler/masm/operator-and.md +++ b/docs/assembler/masm/operator-and.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator AND" title: "operator AND" ms.date: "12/17/2019" f1_keywords: ["operator AND"] diff --git a/docs/assembler/masm/operator-bitwise-and.md b/docs/assembler/masm/operator-bitwise-and.md index ad59b563d9..1f90291924 100644 --- a/docs/assembler/masm/operator-bitwise-and.md +++ b/docs/assembler/masm/operator-bitwise-and.md @@ -1,19 +1,20 @@ --- -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-brackets.md b/docs/assembler/masm/operator-brackets.md index d48e375a96..bcc76eb4f0 100644 --- a/docs/assembler/masm/operator-brackets.md +++ b/docs/assembler/masm/operator-brackets.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator []" title: "operator brackets" ms.date: "12/17/2019" f1_keywords: ["operator []", "[]"] diff --git a/docs/assembler/masm/operator-carry-q.md b/docs/assembler/masm/operator-carry-q.md index f5ca6d09af..a8ec412a8e 100644 --- a/docs/assembler/masm/operator-carry-q.md +++ b/docs/assembler/masm/operator-carry-q.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator CARRY?" title: "operator CARRY?" ms.date: "12/17/2019" f1_keywords: ["CARRY?", "operator CARRY?"] diff --git a/docs/assembler/masm/operator-colon.md b/docs/assembler/masm/operator-colon.md index a41b1a59f1..c622821a44 100644 --- a/docs/assembler/masm/operator-colon.md +++ b/docs/assembler/masm/operator-colon.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator :" title: "operator :" ms.date: "12/17/2019" f1_keywords: ["operator :"] diff --git a/docs/assembler/masm/operator-dot-type.md b/docs/assembler/masm/operator-dot-type.md index d7177c255b..4248965791 100644 --- a/docs/assembler/masm/operator-dot-type.md +++ b/docs/assembler/masm/operator-dot-type.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator .TYPE" title: "operator .TYPE" ms.date: "12/17/2019" f1_keywords: [".TYPE", "operator .TYPE"] diff --git a/docs/assembler/masm/operator-dot.md b/docs/assembler/masm/operator-dot.md index 54583d1bc7..427eee21e9 100644 --- a/docs/assembler/masm/operator-dot.md +++ b/docs/assembler/masm/operator-dot.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator ." title: "operator dot" ms.date: "12/17/2019" f1_keywords: ["operator ."] diff --git a/docs/assembler/masm/operator-double-quote.md b/docs/assembler/masm/operator-double-quote.md index c9ac3f98ea..48a8d3702a 100644 --- a/docs/assembler/masm/operator-double-quote.md +++ b/docs/assembler/masm/operator-double-quote.md @@ -1,11 +1,12 @@ --- -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-dup.md b/docs/assembler/masm/operator-dup.md index bb924bbf79..1928d790e8 100644 --- a/docs/assembler/masm/operator-dup.md +++ b/docs/assembler/masm/operator-dup.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator DUP" title: "operator DUP" ms.date: "12/17/2019" f1_keywords: ["operator DUP"] diff --git a/docs/assembler/masm/operator-eq.md b/docs/assembler/masm/operator-eq.md index 1d596ac7f2..153676f93c 100644 --- a/docs/assembler/masm/operator-eq.md +++ b/docs/assembler/masm/operator-eq.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator EQ" title: "operator EQ" ms.date: "12/17/2019" f1_keywords: ["operator EQ", "EQ"] diff --git a/docs/assembler/masm/operator-equal-masm-run-time.md b/docs/assembler/masm/operator-equal-masm-run-time.md index 87eddc116f..d279d0bed2 100644 --- a/docs/assembler/masm/operator-equal-masm-run-time.md +++ b/docs/assembler/masm/operator-equal-masm-run-time.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator == (MASM Run Time)" title: "operator == (MASM Run Time)" ms.date: "12/17/2019" f1_keywords: ["operator =="] diff --git a/docs/assembler/masm/operator-ge.md b/docs/assembler/masm/operator-ge.md index 9c431b4a16..a4c7026c30 100644 --- a/docs/assembler/masm/operator-ge.md +++ b/docs/assembler/masm/operator-ge.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator GE" title: "operator GE" ms.date: "12/17/2019" f1_keywords: ["GE", "operator GE"] 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 7cf920d951..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,19 +1,20 @@ --- -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 f82a568cb7..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,19 +1,20 @@ --- -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-gt.md b/docs/assembler/masm/operator-gt.md index 594795cca0..b610c95c98 100644 --- a/docs/assembler/masm/operator-gt.md +++ b/docs/assembler/masm/operator-gt.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator GT" title: "operator GT" ms.date: "12/17/2019" f1_keywords: ["operator GT", "GT"] diff --git a/docs/assembler/masm/operator-high.md b/docs/assembler/masm/operator-high.md index c80b171daa..5b700b78b5 100644 --- a/docs/assembler/masm/operator-high.md +++ b/docs/assembler/masm/operator-high.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator HIGH" title: "operator HIGH" ms.date: "12/17/2019" f1_keywords: ["HIGH", "operator HIGH"] diff --git a/docs/assembler/masm/operator-high32.md b/docs/assembler/masm/operator-high32.md index 619cc18342..be18a1de41 100644 --- a/docs/assembler/masm/operator-high32.md +++ b/docs/assembler/masm/operator-high32.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator HIGH32" title: "operator HIGH32" ms.date: "12/17/2019" f1_keywords: ["HIGH32", "operator HIGH32"] diff --git a/docs/assembler/masm/operator-highword.md b/docs/assembler/masm/operator-highword.md index a6099ead8f..0402ac3e2c 100644 --- a/docs/assembler/masm/operator-highword.md +++ b/docs/assembler/masm/operator-highword.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator HIGHWORD" title: "operator HIGHWORD" ms.date: "12/17/2019" f1_keywords: ["HIGHWORD", "operator HIGHWORD"] diff --git a/docs/assembler/masm/operator-imagerel.md b/docs/assembler/masm/operator-imagerel.md index 8e5ab2e04d..0ce745b01d 100644 --- a/docs/assembler/masm/operator-imagerel.md +++ b/docs/assembler/masm/operator-imagerel.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator IMAGEREL" title: "operator IMAGEREL" ms.date: "12/17/2019" f1_keywords: ["operator IMAGEREL", "IMAGEREL"] diff --git a/docs/assembler/masm/operator-le.md b/docs/assembler/masm/operator-le.md index ecc9cad6a0..da98a3a8c5 100644 --- a/docs/assembler/masm/operator-le.md +++ b/docs/assembler/masm/operator-le.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator LE" title: "operator LE" ms.date: "12/17/2019" f1_keywords: ["LE", "operator LE"] diff --git a/docs/assembler/masm/operator-length.md b/docs/assembler/masm/operator-length.md index a4fd3be746..c186b48636 100644 --- a/docs/assembler/masm/operator-length.md +++ b/docs/assembler/masm/operator-length.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator LENGTH" title: "operator LENGTH" ms.date: "12/17/2019" f1_keywords: ["operator LENGTH"] diff --git a/docs/assembler/masm/operator-lengthof.md b/docs/assembler/masm/operator-lengthof.md index 7f8bb4600f..027059248f 100644 --- a/docs/assembler/masm/operator-lengthof.md +++ b/docs/assembler/masm/operator-lengthof.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator LENGTHOF" title: "operator LENGTHOF" ms.date: "12/17/2019" f1_keywords: ["operator LENGTHOF", "LENGTHOF"] 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 f75abe51d1..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,11 +1,12 @@ --- -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 bdf8e54cfd..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,11 +1,12 @@ --- -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 5a2faad22d..2eec929673 100644 --- a/docs/assembler/masm/operator-literal.md +++ b/docs/assembler/masm/operator-literal.md @@ -1,19 +1,20 @@ --- -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 4be1f43f01..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,19 +1,20 @@ --- -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-logical-and-masm.md b/docs/assembler/masm/operator-logical-and-masm.md index 0639d370ff..84b6b8981c 100644 --- a/docs/assembler/masm/operator-logical-and-masm.md +++ b/docs/assembler/masm/operator-logical-and-masm.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Substitution operator (MASM)" title: "Substitution operator (MASM)" ms.date: "12/17/2019" f1_keywords: ["operator &&"] diff --git a/docs/assembler/masm/operator-logical-not-masm-run-time.md b/docs/assembler/masm/operator-logical-not-masm-run-time.md index 2a44333e2f..dd254db150 100644 --- a/docs/assembler/masm/operator-logical-not-masm-run-time.md +++ b/docs/assembler/masm/operator-logical-not-masm-run-time.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator ! (MASM Run Time)" title: "operator ! (MASM Run Time)" ms.date: "12/17/2019" f1_keywords: ["operator !"] diff --git a/docs/assembler/masm/operator-logical-not-masm.md b/docs/assembler/masm/operator-logical-not-masm.md index c95e3af298..c5b1909164 100644 --- a/docs/assembler/masm/operator-logical-not-masm.md +++ b/docs/assembler/masm/operator-logical-not-masm.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator ! (MASM)" title: "operator ! (MASM)" ms.date: "12/17/2019" f1_keywords: ["operator !"] diff --git a/docs/assembler/masm/operator-logical-or.md b/docs/assembler/masm/operator-logical-or.md index f079783a1a..c8fde425c9 100644 --- a/docs/assembler/masm/operator-logical-or.md +++ b/docs/assembler/masm/operator-logical-or.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator ||" title: "operator ||" ms.date: "12/17/2019" f1_keywords: ["operator ||"] diff --git a/docs/assembler/masm/operator-low.md b/docs/assembler/masm/operator-low.md index abb0fd3aa1..b40a5f13bc 100644 --- a/docs/assembler/masm/operator-low.md +++ b/docs/assembler/masm/operator-low.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator LOW" title: "operator LOW" ms.date: "12/17/2019" f1_keywords: ["operator LOW", "LOW"] diff --git a/docs/assembler/masm/operator-low32.md b/docs/assembler/masm/operator-low32.md index ab28b7e2bd..e6a8db7138 100644 --- a/docs/assembler/masm/operator-low32.md +++ b/docs/assembler/masm/operator-low32.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator LOW32" title: "operator LOW32" ms.date: "12/17/2019" f1_keywords: ["LOW32", "operator LOW32"] diff --git a/docs/assembler/masm/operator-lowword.md b/docs/assembler/masm/operator-lowword.md index ac7774aed5..0c32373242 100644 --- a/docs/assembler/masm/operator-lowword.md +++ b/docs/assembler/masm/operator-lowword.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator LOWWORD" title: "operator LOWWORD" ms.date: "12/17/2019" f1_keywords: ["operator LOWWORD", "LOWWORD"] diff --git a/docs/assembler/masm/operator-lroffset.md b/docs/assembler/masm/operator-lroffset.md index 4c4ac2f419..366ec34e1c 100644 --- a/docs/assembler/masm/operator-lroffset.md +++ b/docs/assembler/masm/operator-lroffset.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator LROFFSET" title: "operator LROFFSET" ms.date: "12/17/2019" f1_keywords: ["LROFFSET", "operator LROFFSET"] diff --git a/docs/assembler/masm/operator-lt.md b/docs/assembler/masm/operator-lt.md index 2967263946..5a994b2ad8 100644 --- a/docs/assembler/masm/operator-lt.md +++ b/docs/assembler/masm/operator-lt.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator LT" title: "operator LT" ms.date: "12/17/2019" f1_keywords: ["LT", "operator LT"] diff --git a/docs/assembler/masm/operator-mask.md b/docs/assembler/masm/operator-mask.md index 04fdb4163c..fbe08e5ef7 100644 --- a/docs/assembler/masm/operator-mask.md +++ b/docs/assembler/masm/operator-mask.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator MASK" title: "operator MASK" ms.date: "12/17/2019" f1_keywords: ["operator MASK", "MASK"] diff --git a/docs/assembler/masm/operator-mod.md b/docs/assembler/masm/operator-mod.md index 3181e0f9a2..1857f5d6c1 100644 --- a/docs/assembler/masm/operator-mod.md +++ b/docs/assembler/masm/operator-mod.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator MOD" title: "operator MOD" ms.date: "12/17/2019" f1_keywords: ["Mod", "operator MOD"] diff --git a/docs/assembler/masm/operator-multiply.md b/docs/assembler/masm/operator-multiply.md index 9b1ac1e656..ebf65c017f 100644 --- a/docs/assembler/masm/operator-multiply.md +++ b/docs/assembler/masm/operator-multiply.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator *" title: "operator *" ms.date: "12/17/2019" f1_keywords: ["operator *"] diff --git a/docs/assembler/masm/operator-ne.md b/docs/assembler/masm/operator-ne.md index eda618c9f2..1b48faf214 100644 --- a/docs/assembler/masm/operator-ne.md +++ b/docs/assembler/masm/operator-ne.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator NE" title: "operator NE" ms.date: "12/17/2019" f1_keywords: ["NE", "operator NE"] diff --git a/docs/assembler/masm/operator-not-equal-masm.md b/docs/assembler/masm/operator-not-equal-masm.md index 178226fdf8..d3ff2ab438 100644 --- a/docs/assembler/masm/operator-not-equal-masm.md +++ b/docs/assembler/masm/operator-not-equal-masm.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator != (MASM)" title: "operator != (MASM)" ms.date: "12/17/2019" f1_keywords: ["operator !="] diff --git a/docs/assembler/masm/operator-not.md b/docs/assembler/masm/operator-not.md index bc16f1c5f8..d321f01a6e 100644 --- a/docs/assembler/masm/operator-not.md +++ b/docs/assembler/masm/operator-not.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator NOT" title: "operator NOT" ms.date: "12/17/2019" f1_keywords: ["operator NOT"] diff --git a/docs/assembler/masm/operator-offset.md b/docs/assembler/masm/operator-offset.md index 7dca685a8c..b384879e7e 100644 --- a/docs/assembler/masm/operator-offset.md +++ b/docs/assembler/masm/operator-offset.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator OFFSET" title: "operator OFFSET" ms.date: "12/17/2019" f1_keywords: ["Offset", "operator OFFSET"] diff --git a/docs/assembler/masm/operator-opattr.md b/docs/assembler/masm/operator-opattr.md index eef9c82ce6..fae2e7e95c 100644 --- a/docs/assembler/masm/operator-opattr.md +++ b/docs/assembler/masm/operator-opattr.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator OPATTR" title: "operator OPATTR" ms.date: "12/17/2019" f1_keywords: ["operator OPATTR", "OPATTR"] diff --git a/docs/assembler/masm/operator-or.md b/docs/assembler/masm/operator-or.md index 278d89db01..a0acf45803 100644 --- a/docs/assembler/masm/operator-or.md +++ b/docs/assembler/masm/operator-or.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator OR" title: "operator OR" ms.date: "12/17/2019" helpviewer_keywords: ["operator OR", "OR operator, bitwise"] diff --git a/docs/assembler/masm/operator-overflow-q.md b/docs/assembler/masm/operator-overflow-q.md index 39288f784f..8985bdb723 100644 --- a/docs/assembler/masm/operator-overflow-q.md +++ b/docs/assembler/masm/operator-overflow-q.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator OVERFLOW?" title: "operator OVERFLOW?" ms.date: "12/17/2019" f1_keywords: ["operator OVERFLOW?", "OVERFLOW?"] diff --git a/docs/assembler/masm/operator-parity-q.md b/docs/assembler/masm/operator-parity-q.md index 36505ba945..0922616359 100644 --- a/docs/assembler/masm/operator-parity-q.md +++ b/docs/assembler/masm/operator-parity-q.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator PARITY?" title: "operator PARITY?" ms.date: "12/17/2019" f1_keywords: ["PARITY?", "operator PARITY?"] diff --git a/docs/assembler/masm/operator-percent.md b/docs/assembler/masm/operator-percent.md index c10e30d481..a3f68d0ea8 100644 --- a/docs/assembler/masm/operator-percent.md +++ b/docs/assembler/masm/operator-percent.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator %" title: "operator %" ms.date: "12/17/2019" f1_keywords: ["%", "operator %"] diff --git a/docs/assembler/masm/operator-ptr.md b/docs/assembler/masm/operator-ptr.md index 2ec1e1231f..fa0e57c126 100644 --- a/docs/assembler/masm/operator-ptr.md +++ b/docs/assembler/masm/operator-ptr.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator PTR" title: "operator PTR" ms.date: "12/17/2019" f1_keywords: ["PTR", "operator PTR"] diff --git a/docs/assembler/masm/operator-sectionrel.md b/docs/assembler/masm/operator-sectionrel.md index 3cd8f316ae..df9ce907db 100644 --- a/docs/assembler/masm/operator-sectionrel.md +++ b/docs/assembler/masm/operator-sectionrel.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator SECTIONREL" title: "operator SECTIONREL" ms.date: "12/17/2019" f1_keywords: ["operator SECTIONREL", "SECTIONREL"] diff --git a/docs/assembler/masm/operator-seg.md b/docs/assembler/masm/operator-seg.md index 10316da742..194e31c5d4 100644 --- a/docs/assembler/masm/operator-seg.md +++ b/docs/assembler/masm/operator-seg.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator SEG" title: "operator SEG" ms.date: "12/17/2019" f1_keywords: ["operator SEG", "SEG"] diff --git a/docs/assembler/masm/operator-semicolon.md b/docs/assembler/masm/operator-semicolon.md index 618dde28f1..f59b680fd1 100644 --- a/docs/assembler/masm/operator-semicolon.md +++ b/docs/assembler/masm/operator-semicolon.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator ;" title: "operator ;" ms.date: "12/17/2019" f1_keywords: ["operator %3B", "%3B"] diff --git a/docs/assembler/masm/operator-semicolons.md b/docs/assembler/masm/operator-semicolons.md index ac8c0bf9f4..a2b9e2c4f3 100644 --- a/docs/assembler/masm/operator-semicolons.md +++ b/docs/assembler/masm/operator-semicolons.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator ;;" title: "operator ;;" ms.date: "12/17/2019" f1_keywords: ["%3B%3B", "operator %3B%3B"] diff --git a/docs/assembler/masm/operator-shl.md b/docs/assembler/masm/operator-shl.md index f6ef4ddec4..db4bfa104c 100644 --- a/docs/assembler/masm/operator-shl.md +++ b/docs/assembler/masm/operator-shl.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator SHL" title: "operator SHL" ms.date: "12/17/2019" f1_keywords: ["operator SHL", "SHL"] diff --git a/docs/assembler/masm/operator-short.md b/docs/assembler/masm/operator-short.md index 735cccde6d..93de1f8dec 100644 --- a/docs/assembler/masm/operator-short.md +++ b/docs/assembler/masm/operator-short.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator SHORT" title: "operator SHORT" ms.date: "12/17/2019" f1_keywords: ["operator SHORT"] diff --git a/docs/assembler/masm/operator-shr.md b/docs/assembler/masm/operator-shr.md index fede4b04ba..45bac081cf 100644 --- a/docs/assembler/masm/operator-shr.md +++ b/docs/assembler/masm/operator-shr.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator SHR" title: "operator SHR" ms.date: "12/17/2019" f1_keywords: ["SHR", "operator SHR"] diff --git a/docs/assembler/masm/operator-sign-q.md b/docs/assembler/masm/operator-sign-q.md index 2719b5c9c9..779a77baf5 100644 --- a/docs/assembler/masm/operator-sign-q.md +++ b/docs/assembler/masm/operator-sign-q.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator SIGN?" title: "operator SIGN?" ms.date: "12/17/2019" f1_keywords: ["SIGN?", "operator SIGN?"] diff --git a/docs/assembler/masm/operator-single-quote.md b/docs/assembler/masm/operator-single-quote.md index cda0b2ab29..a97eb12976 100644 --- a/docs/assembler/masm/operator-single-quote.md +++ b/docs/assembler/masm/operator-single-quote.md @@ -1,11 +1,12 @@ --- -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-size.md b/docs/assembler/masm/operator-size.md index 2a994c8987..ef640c2e95 100644 --- a/docs/assembler/masm/operator-size.md +++ b/docs/assembler/masm/operator-size.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator SIZE" title: "operator SIZE" ms.date: "12/17/2019" f1_keywords: ["size", "operator SIZE"] diff --git a/docs/assembler/masm/operator-sizeof.md b/docs/assembler/masm/operator-sizeof.md index 71d08d056c..7d2e824af0 100644 --- a/docs/assembler/masm/operator-sizeof.md +++ b/docs/assembler/masm/operator-sizeof.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator SIZEOF" title: "operator SIZEOF" ms.date: "12/17/2019" f1_keywords: ["operator SIZEOF"] diff --git a/docs/assembler/masm/operator-subtract-1.md b/docs/assembler/masm/operator-subtract-1.md index 93ac29d06a..4c97f88f48 100644 --- a/docs/assembler/masm/operator-subtract-1.md +++ b/docs/assembler/masm/operator-subtract-1.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator /" title: "operator /" ms.date: "12/17/2019" f1_keywords: ["/", "operator /"] diff --git a/docs/assembler/masm/operator-subtract-2.md b/docs/assembler/masm/operator-subtract-2.md index a3156bbd42..5d49dbeb55 100644 --- a/docs/assembler/masm/operator-subtract-2.md +++ b/docs/assembler/masm/operator-subtract-2.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator -" title: "operator -" ms.date: "12/17/2019" f1_keywords: ["operator -"] diff --git a/docs/assembler/masm/operator-this.md b/docs/assembler/masm/operator-this.md index 8a2df29a56..bf1695d145 100644 --- a/docs/assembler/masm/operator-this.md +++ b/docs/assembler/masm/operator-this.md @@ -1,17 +1,18 @@ --- +description: "Learn more about: operator THIS" title: "operator THIS" ms.date: "12/17/2019" 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/operator-type.md b/docs/assembler/masm/operator-type.md index 65382ed503..2fa7a06133 100644 --- a/docs/assembler/masm/operator-type.md +++ b/docs/assembler/masm/operator-type.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator TYPE" title: "operator TYPE" ms.date: "12/17/2019" f1_keywords: ["operator TYPE"] diff --git a/docs/assembler/masm/operator-width.md b/docs/assembler/masm/operator-width.md index dde2ecb1a2..14919305e6 100644 --- a/docs/assembler/masm/operator-width.md +++ b/docs/assembler/masm/operator-width.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator WIDTH" title: "operator WIDTH" ms.date: "12/17/2019" f1_keywords: ["Width", "operator WIDTH"] diff --git a/docs/assembler/masm/operator-xor.md b/docs/assembler/masm/operator-xor.md index f3c009bfbd..0ecfb236d5 100644 --- a/docs/assembler/masm/operator-xor.md +++ b/docs/assembler/masm/operator-xor.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator XOR" title: "operator XOR" ms.date: "12/17/2019" f1_keywords: ["operator XOR", "Xor"] diff --git a/docs/assembler/masm/operator-zero-q.md b/docs/assembler/masm/operator-zero-q.md index 9fae180c91..bf3dbb21a5 100644 --- a/docs/assembler/masm/operator-zero-q.md +++ b/docs/assembler/masm/operator-zero-q.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: operator ZERO?" title: "operator ZERO?" ms.date: "12/17/2019" f1_keywords: ["operator ZERO?", "ZERO?"] diff --git a/docs/assembler/masm/operators-reference.md b/docs/assembler/masm/operators-reference.md index 0fcee06c94..d81f8f6c16 100644 --- a/docs/assembler/masm/operators-reference.md +++ b/docs/assembler/masm/operators-reference.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: MASM Operators reference" title: "MASM Operators reference" ms.date: 07/15/2020 helpviewer_keywords: ["MASM (Microsoft Macro Assembler), operators reference", "operators [MASM]"] @@ -10,13 +11,17 @@ ms.assetid: c069cab7-d6b0-4f82-a6ce-0ca3fc7e6428 :::row::: :::column span=""::: - [`*` (multiply)](operator-multiply.md)
[`+` (add)](operator-add.md)
[`-` (subtract or negate)](operator-subtract-2.md) + [`*` (multiply)](operator-multiply.md)\ + [`+` (add)](operator-add.md)\ + [`-` (subtract or negate)](operator-subtract-2.md) :::column-end::: :::column span=""::: - [`.` (field)](operator-dot.md)
[`/` (divide)](operator-subtract-1.md) + [`.` (field)](operator-dot.md)\ + [`/` (divide)](operator-subtract-1.md) :::column-end::: :::column span=""::: - [`[]` (index)](operator-brackets.md)
[`MOD` (remainder)](operator-mod.md) + [`[]` (index)](operator-brackets.md)\ + [`MOD` (remainder)](operator-mod.md) :::column-end::: :::row-end::: @@ -24,13 +29,25 @@ ms.assetid: c069cab7-d6b0-4f82-a6ce-0ca3fc7e6428 :::row::: :::column span=""::: - [`!` (runtime logical not)](operator-logical-not-masm-run-time.md)
[`!=` (runtime not equal)](operator-not-equal-masm.md)
[`||` (runtime logical or)](operator-logical-or.md)
[`&&` (runtime logical and)](operator-logical-and-masm-run-time.md)
[`<` (runtime less than)](operator-less-than-masm-run-time.md) + [`!` (runtime logical not)](operator-logical-not-masm-run-time.md)\ + [`!=` (runtime not equal)](operator-not-equal-masm.md)\ + [`||` (runtime logical or)](operator-logical-or.md)\ + [`&&` (runtime logical and)](operator-logical-and-masm-run-time.md)\ + [`<` (runtime less than)](operator-less-than-masm-run-time.md) :::column-end::: :::column span=""::: - [`<=` (runtime less or equal)](operator-less-or-equal-masm-run-time.md)
[`==` (runtime equal)](operator-equal-masm-run-time.md)
[`>` (runtime greater than)](operator-greater-than-masm-run-time.md)
[`>=` (runtime greater or equal)](operator-greater-or-equal-masm-run-time.md)
[`&` (runtime bitwise and)](operator-bitwise-and.md) + [`<=` (runtime less or equal)](operator-less-or-equal-masm-run-time.md)\ + [`==` (runtime equal)](operator-equal-masm-run-time.md)\ + [`>` (runtime greater than)](operator-greater-than-masm-run-time.md)\ + [`>=` (runtime greater or equal)](operator-greater-or-equal-masm-run-time.md)\ + [`&` (runtime bitwise and)](operator-bitwise-and.md) :::column-end::: :::column span=""::: - [`CARRY?` (runtime carry test)](operator-carry-q.md)
[`OVERFLOW?` (runtime overflow test)](operator-overflow-q.md)
[`PARITY?` (runtime parity test)](operator-parity-q.md)
[`SIGN?` (runtime sign test)](operator-sign-q.md)
[`ZERO?` (runtime zero test)](operator-zero-q.md) + [`CARRY?` (runtime carry test)](operator-carry-q.md)\ + [`OVERFLOW?` (runtime overflow test)](operator-overflow-q.md)\ + [`PARITY?` (runtime parity test)](operator-parity-q.md)\ + [`SIGN?` (runtime sign test)](operator-sign-q.md)\ + [`ZERO?` (runtime zero test)](operator-zero-q.md) :::column-end::: :::row-end::: @@ -38,13 +55,16 @@ ms.assetid: c069cab7-d6b0-4f82-a6ce-0ca3fc7e6428 :::row::: :::column span=""::: - [`AND` (bitwise and)](operator-and.md)
[`NOT` (bitwise not)](operator-not.md) + [`AND` (bitwise and)](operator-and.md)\ + [`NOT` (bitwise not)](operator-not.md) :::column-end::: :::column span=""::: - [`OR` (bitwise or)](operator-or.md)
[`SHL` (shift bits left)](operator-shl.md) + [`OR` (bitwise or)](operator-or.md)\ + [`SHL` (shift bits left)](operator-shl.md) :::column-end::: :::column span=""::: - [`SHR` (shift bits right)](operator-shr.md)
[`XOR` (bitwise exclusive or)](operator-xor.md) + [`SHR` (shift bits right)](operator-shr.md)\ + [`XOR` (bitwise exclusive or)](operator-xor.md) :::column-end::: :::row-end::: @@ -52,10 +72,12 @@ ms.assetid: c069cab7-d6b0-4f82-a6ce-0ca3fc7e6428 :::row::: :::column span=""::: - [`!` (character literal)](operator-logical-not-masm.md)
[`%` (treat as text)](operator-percent.md) + [`!` (character literal)](operator-logical-not-masm.md)\ + [`%` (treat as text)](operator-percent.md) :::column-end::: :::column span=""::: - [`;;` (treat as comment)](operator-semicolons.md)
[`< >` (treat as one literal)](operator-literal.md) + [`;;` (treat as comment)](operator-semicolons.md)\ + [`< >` (treat as one literal)](operator-literal.md) :::column-end::: :::column span=""::: [`& &` (substitute parameter value)](operator-logical-and-masm.md) @@ -66,13 +88,17 @@ ms.assetid: c069cab7-d6b0-4f82-a6ce-0ca3fc7e6428 :::row::: :::column span=""::: - [`' '` (treat as string)](operator-single-quote.md)
[`" "` (treat as string)](operator-double-quote.md)
`:` (local label definition) + [`' '` (treat as string)](operator-single-quote.md)\ + [`" "` (treat as string)](operator-double-quote.md)\ + `:` (local label definition) :::column-end::: :::column span=""::: - `::` (register segment and offset)
`::` (global label definition) + `::` (register segment and offset)\ + `::` (global label definition) :::column-end::: :::column span=""::: - [`;` (treat as comment)](operator-semicolon.md)
[`DUP` (repeat declaration)](operator-dup.md) + [`;` (treat as comment)](operator-semicolon.md)\ + [`DUP` (repeat declaration)](operator-dup.md) :::column-end::: :::row-end::: @@ -91,13 +117,16 @@ ms.assetid: c069cab7-d6b0-4f82-a6ce-0ca3fc7e6428 :::row::: :::column span=""::: - [`EQ` (equal)](operator-eq.md)
[`GE` (greater or equal)](operator-ge.md) + [`EQ` (equal)](operator-eq.md)\ + [`GE` (greater or equal)](operator-ge.md) :::column-end::: :::column span=""::: - [`GT` (greater than)](operator-gt.md)
[`LE` (less or equal)](operator-le.md) + [`GT` (greater than)](operator-gt.md)\ + [`LE` (less or equal)](operator-le.md) :::column-end::: :::column span=""::: - [`LT` (less than)](operator-lt.md)
[`NE` (not equal)](operator-ne.md) + [`LT` (less than)](operator-lt.md)\ + [`NE` (not equal)](operator-ne.md) :::column-end::: :::row-end::: @@ -105,13 +134,17 @@ ms.assetid: c069cab7-d6b0-4f82-a6ce-0ca3fc7e6428 :::row::: :::column span=""::: - [`:` (segment override)](operator-colon.md)
`::` (register segment and offset)
[`IMAGEREL` (image relative offset)](operator-imagerel.md) + [`:` (segment override)](operator-colon.md)\ + `::` (register segment and offset)\ + [`IMAGEREL` (image relative offset)](operator-imagerel.md) :::column-end::: :::column span=""::: - [`LROFFSET` (loader resolved offset)](operator-lroffset.md)
[`OFFSET` (segment relative offset)](operator-offset.md) + [`LROFFSET` (loader resolved offset)](operator-lroffset.md)\ + [`OFFSET` (segment relative offset)](operator-offset.md) :::column-end::: :::column span=""::: - [`SECTIONREL` (section relative offset)](operator-sectionrel.md)
[`SEG` (get segment)](operator-seg.md) + [`SECTIONREL` (section relative offset)](operator-sectionrel.md)\ + [`SEG` (get segment)](operator-seg.md) :::column-end::: :::row-end::: @@ -119,13 +152,26 @@ ms.assetid: c069cab7-d6b0-4f82-a6ce-0ca3fc7e6428 :::row::: :::column span=""::: - [`HIGH` (high 8 bits of lowest 16 bits)](operator-high.md)
[`HIGH32` (high 32 bits of 64 bits)](operator-high32.md)
[`HIGHWORD` (high 16 bits of lowest 32 bits)](operator-highword.md)
[`LENGTH` (number of elements in array)](operator-length.md)
[`LENGTHOF` (number of elements in array)](operator-lengthof.md)
[`LOW` (low 8 bits)](operator-low.md) + [`HIGH` (high 8 bits of lowest 16 bits)](operator-high.md)\ + [`HIGH32` (high 32 bits of 64 bits)](operator-high32.md)\ + [`HIGHWORD` (high 16 bits of lowest 32 bits)](operator-highword.md)\ + [`LENGTH` (number of elements in array)](operator-length.md)\ + [`LENGTHOF` (number of elements in array)](operator-lengthof.md)\ + [`LOW` (low 8 bits)](operator-low.md) :::column-end::: :::column span=""::: - [`LOW32` (low 32 bits)](operator-low32.md)
[`LOWWORD` (low 16 bits)](operator-lowword.md)
[`OPATTR` (get argument type info)](operator-opattr.md)
[`PTR` (pointer to or as type)](operator-ptr.md)
[`SHORT` (mark short label type)](operator-short.md) + [`LOW32` (low 32 bits)](operator-low32.md)\ + [`LOWWORD` (low 16 bits)](operator-lowword.md)\ + [`OPATTR` (get argument type info)](operator-opattr.md)\ + [`PTR` (pointer to or as type)](operator-ptr.md)\ + [`SHORT` (mark short label type)](operator-short.md) :::column-end::: :::column span=""::: - [`SIZE` (size of type or variable)](operator-size.md)
[`SIZEOF` (size of type or variable)](operator-sizeof.md)
[`THIS` (current location)](operator-this.md)
[`TYPE` (get expression type)](operator-type.md)
[`.TYPE` (get argument type info)](operator-dot-type.md) + [`SIZE` (size of type or variable)](operator-size.md)\ + [`SIZEOF` (size of type or variable)](operator-sizeof.md)\ + [`THIS` (current location)](operator-this.md)\ + [`TYPE` (get expression type)](operator-type.md)\ + [`.TYPE` (get argument type info)](operator-dot-type.md) :::column-end::: :::row-end::: 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 7ed4aa9a07..fd6b674619 100644 --- a/docs/assembler/masm/option-masm.md +++ b/docs/assembler/masm/option-masm.md @@ -1,11 +1,11 @@ --- +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. @@ -19,20 +19,45 @@ Available options include: :::row::: :::column span=""::: - **`CASEMAP`**
**`DOTNAME`**
**`NODOTNAME`**
**`EMULATOR`**
**`NOEMULATOR`**
**`EPILOGUE`**
**`EXPR16`** + [`AVXENCODING`](option-avxencoding-masm.md)\ + **`CASEMAP`**\ + **`DOTNAME`**\ + **`NODOTNAME`**\ + **`EMULATOR`**\ + **`NOEMULATOR`**\ + **`EPILOGUE`**\ + **`EXPR16`** :::column-end::: :::column span=""::: - **`EXPR32`**
**`LANGUAGE`**
**`LJMP`**
**`NOLJMP`**
**`M510`**
**`NOM510`**
**`NOKEYWORD`** + **`EXPR32`**\ + [`LANGUAGE`](option-language-masm.md)\ + **`LJMP`**\ + **`NOLJMP`**\ + **`M510`**\ + **`NOM510`**\ + **`NOKEYWORD`** :::column-end::: :::column span=""::: - **`NOSIGNEXTEND`**
**`OFFSET`**
**`OLDMACROS`**
**`NOOLDMACROS`**
**`OLDSTRUCTS`**
**`NOOLDSTRUCTS`**
**`PROC`** + **`NOSIGNEXTEND`**\ + **`OFFSET`**\ + **`OLDMACROS`**\ + **`NOOLDMACROS`**\ + **`OLDSTRUCTS`**\ + **`NOOLDSTRUCTS`**\ + **`PROC`** :::column-end::: :::column span=""::: - **`PROLOGUE`**
**`READONLY`**
**`NOREADONLY`**
**`SCOPED`**
**`NOSCOPED`**
**`SEGMENT`**
**`SETIF2`** + **`PROLOGUE`**\ + **`READONLY`**\ + **`NOREADONLY`**\ + **`SCOPED`**\ + **`NOSCOPED`**\ + **`SEGMENT`**\ + **`SETIF2`** :::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/org.md b/docs/assembler/masm/org.md index 7cc41c65ad..3822a97f3e 100644 --- a/docs/assembler/masm/org.md +++ b/docs/assembler/masm/org.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ORG" title: "ORG" ms.date: "12/17/2019" f1_keywords: ["ORG"] diff --git a/docs/assembler/masm/oword.md b/docs/assembler/masm/oword.md index 9579a52e56..9405c50d65 100644 --- a/docs/assembler/masm/oword.md +++ b/docs/assembler/masm/oword.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: OWORD" title: "OWORD" ms.date: "12/17/2019" f1_keywords: ["OWORD"] diff --git a/docs/assembler/masm/page.md b/docs/assembler/masm/page.md index 08855c25c9..44120a97fc 100644 --- a/docs/assembler/masm/page.md +++ b/docs/assembler/masm/page.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: PAGE" title: "PAGE" ms.date: "12/16/2019" f1_keywords: ["PAGE"] diff --git a/docs/assembler/masm/percent-out.md b/docs/assembler/masm/percent-out.md index db03e28197..8d49a2f884 100644 --- a/docs/assembler/masm/percent-out.md +++ b/docs/assembler/masm/percent-out.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: %OUT" title: "%OUT" ms.date: "12/17/2019" f1_keywords: ["%OUT"] diff --git a/docs/assembler/masm/popcontext.md b/docs/assembler/masm/popcontext.md index a7a6130105..011e299f8d 100644 --- a/docs/assembler/masm/popcontext.md +++ b/docs/assembler/masm/popcontext.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: POPCONTEXT" title: "POPCONTEXT" ms.date: "12/06/2019" f1_keywords: ["POPCONTEXT"] diff --git a/docs/assembler/masm/proc.md b/docs/assembler/masm/proc.md index fecefcb069..9eb65fc377 100644 --- a/docs/assembler/masm/proc.md +++ b/docs/assembler/masm/proc.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: PROC" title: "PROC" ms.date: "12/06/2019" f1_keywords: ["PROC"] diff --git a/docs/assembler/masm/processor-manufacturer-programming-manuals.md b/docs/assembler/masm/processor-manufacturer-programming-manuals.md index cc473d64e1..4774fdeeb7 100644 --- a/docs/assembler/masm/processor-manufacturer-programming-manuals.md +++ b/docs/assembler/masm/processor-manufacturer-programming-manuals.md @@ -1,21 +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/proto.md b/docs/assembler/masm/proto.md index 9aa7f70eb0..343bd9108c 100644 --- a/docs/assembler/masm/proto.md +++ b/docs/assembler/masm/proto.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: PROTO" title: "PROTO" ms.date: "12/06/2019" f1_keywords: ["PROTO"] diff --git a/docs/assembler/masm/public-masm.md b/docs/assembler/masm/public-masm.md index e1ed4d2c7c..e372aac24a 100644 --- a/docs/assembler/masm/public-masm.md +++ b/docs/assembler/masm/public-masm.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: PUBLIC" title: "PUBLIC (MASM)" ms.date: "12/16/2019" f1_keywords: ["public"] diff --git a/docs/assembler/masm/purge.md b/docs/assembler/masm/purge.md index 55662a457c..9051b7fae9 100644 --- a/docs/assembler/masm/purge.md +++ b/docs/assembler/masm/purge.md @@ -1,9 +1,9 @@ --- 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 @@ -15,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/pushcontext.md b/docs/assembler/masm/pushcontext.md index 2917f3aa1c..fb32914f92 100644 --- a/docs/assembler/masm/pushcontext.md +++ b/docs/assembler/masm/pushcontext.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: PUSHCONTEXT" title: "PUSHCONTEXT" ms.date: "12/06/2019" f1_keywords: ["PUSHCONTEXT"] diff --git a/docs/assembler/masm/q.md b/docs/assembler/masm/q.md index 829964dc0e..3819214c6d 100644 --- a/docs/assembler/masm/q.md +++ b/docs/assembler/masm/q.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ?" title: "? (MASM)" ms.date: "12/17/2019" f1_keywords: ["?"] diff --git a/docs/assembler/masm/qword.md b/docs/assembler/masm/qword.md index 19c970f61a..ecfd6fa626 100644 --- a/docs/assembler/masm/qword.md +++ b/docs/assembler/masm/qword.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: QWORD" title: "QWORD" ms.date: "12/17/2019" f1_keywords: ["QWORD"] diff --git a/docs/assembler/masm/real10.md b/docs/assembler/masm/real10.md index c8a6871ae5..c29c22c2db 100644 --- a/docs/assembler/masm/real10.md +++ b/docs/assembler/masm/real10.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: REAL10" title: "REAL10" ms.date: "12/17/2019" f1_keywords: ["REAL10"] diff --git a/docs/assembler/masm/real4.md b/docs/assembler/masm/real4.md index 7b44afe665..066317ab5b 100644 --- a/docs/assembler/masm/real4.md +++ b/docs/assembler/masm/real4.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: REAL4" title: "REAL4" ms.date: "12/17/2019" f1_keywords: ["REAL4"] diff --git a/docs/assembler/masm/real8.md b/docs/assembler/masm/real8.md index 1832b933a4..2d963ab3fb 100644 --- a/docs/assembler/masm/real8.md +++ b/docs/assembler/masm/real8.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: REAL8" title: "REAL8" ms.date: "12/17/2019" f1_keywords: ["REAL8"] diff --git a/docs/assembler/masm/record-masm.md b/docs/assembler/masm/record-masm.md index baa9e4bb88..96b3f0f3af 100644 --- a/docs/assembler/masm/record-masm.md +++ b/docs/assembler/masm/record-masm.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: RECORD" title: "RECORD (MASM)" ms.date: "12/16/2019" f1_keywords: ["RECORD"] diff --git a/docs/assembler/masm/repeat.md b/docs/assembler/masm/repeat.md index 9805df108f..4e95f1eae5 100644 --- a/docs/assembler/masm/repeat.md +++ b/docs/assembler/masm/repeat.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: REPEAT" title: "REPEAT" ms.date: "12/17/2019" f1_keywords: ["REPEAT"] diff --git a/docs/assembler/masm/rept.md b/docs/assembler/masm/rept.md index 3c152bbe4c..8adb58794f 100644 --- a/docs/assembler/masm/rept.md +++ b/docs/assembler/masm/rept.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: REPT" title: "REPT" ms.date: "12/17/2019" f1_keywords: ["REPT"] diff --git a/docs/assembler/masm/sbyte-masm.md b/docs/assembler/masm/sbyte-masm.md index 7f5193cf26..62c126f17e 100644 --- a/docs/assembler/masm/sbyte-masm.md +++ b/docs/assembler/masm/sbyte-masm.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: SBYTE" title: "SBYTE (MASM)" ms.date: "12/17/2019" f1_keywords: ["sbyte"] diff --git a/docs/assembler/masm/sdword.md b/docs/assembler/masm/sdword.md index bade6a5047..e3ddcc9bde 100644 --- a/docs/assembler/masm/sdword.md +++ b/docs/assembler/masm/sdword.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: SDWORD" title: "SDWORD" ms.date: "12/17/2019" f1_keywords: ["SDWORD"] diff --git a/docs/assembler/masm/segment.md b/docs/assembler/masm/segment.md index f72a883c0a..4e8debb2c6 100644 --- a/docs/assembler/masm/segment.md +++ b/docs/assembler/masm/segment.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: SEGMENT" title: "SEGMENT" ms.date: "12/16/2019" f1_keywords: ["SEGMENT"] diff --git a/docs/assembler/masm/sizestr.md b/docs/assembler/masm/sizestr.md index 096f1f3a44..f0ea923225 100644 --- a/docs/assembler/masm/sizestr.md +++ b/docs/assembler/masm/sizestr.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: SIZESTR" title: "SIZESTR" ms.date: "12/17/2019" f1_keywords: ["SIZESTR"] diff --git a/docs/assembler/masm/sqword.md b/docs/assembler/masm/sqword.md index d7f2c56d60..fe78b8f5a4 100644 --- a/docs/assembler/masm/sqword.md +++ b/docs/assembler/masm/sqword.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: SQWORD" title: "SQWORD" ms.date: "12/17/2019" f1_keywords: ["SQWORD"] diff --git a/docs/assembler/masm/struc.md b/docs/assembler/masm/struc.md index 55802b0232..8621795794 100644 --- a/docs/assembler/masm/struc.md +++ b/docs/assembler/masm/struc.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: STRUC" title: "STRUC" ms.date: "12/17/2019" f1_keywords: ["STRUC"] diff --git a/docs/assembler/masm/struct-masm.md b/docs/assembler/masm/struct-masm.md index 6abc46367c..c6200e58d2 100644 --- a/docs/assembler/masm/struct-masm.md +++ b/docs/assembler/masm/struct-masm.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: STRUCT" title: "STRUCT (MASM)" ms.date: "12/17/2019" f1_keywords: ["struct"] diff --git a/docs/assembler/masm/substr.md b/docs/assembler/masm/substr.md index cfa46eba58..b7e7a67d08 100644 --- a/docs/assembler/masm/substr.md +++ b/docs/assembler/masm/substr.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: SUBSTR" title: "SUBSTR" ms.date: "12/16/2019" f1_keywords: ["substr"] diff --git a/docs/assembler/masm/subtitle.md b/docs/assembler/masm/subtitle.md index dd98209b17..ce64380b7f 100644 --- a/docs/assembler/masm/subtitle.md +++ b/docs/assembler/masm/subtitle.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: SUBTITLE" title: "SUBTITLE" ms.date: "12/16/2019" f1_keywords: ["SUBTITLE"] diff --git a/docs/assembler/masm/subttl.md b/docs/assembler/masm/subttl.md index d464c2fc1d..a119b8eb14 100644 --- a/docs/assembler/masm/subttl.md +++ b/docs/assembler/masm/subttl.md @@ -1,9 +1,9 @@ --- 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 @@ -15,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/masm/sword.md b/docs/assembler/masm/sword.md index 4608b250a9..a68a65c883 100644 --- a/docs/assembler/masm/sword.md +++ b/docs/assembler/masm/sword.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: SWORD" title: "SWORD" ms.date: "12/17/2019" f1_keywords: ["SWORD"] diff --git a/docs/assembler/masm/symbols-reference.md b/docs/assembler/masm/symbols-reference.md index 5e2049581b..c7fd4af9f8 100644 --- a/docs/assembler/masm/symbols-reference.md +++ b/docs/assembler/masm/symbols-reference.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Symbols reference" title: "Symbols reference" ms.date: 07/15/2020 helpviewer_keywords: ["MASM (Microsoft Macro Assembler), symbols reference"] @@ -69,7 +70,8 @@ ms.assetid: 96ed59cc-dafa-4299-bb2e-9c7c3f496491 :::row::: :::column span=""::: - [`$`](dollar.md)
[`?`](q.md) + [`$`](dollar.md)\ + [`?`](q.md) :::column-end::: :::column span=""::: [`@@:`](at-at.md) @@ -86,16 +88,22 @@ ms.assetid: 96ed59cc-dafa-4299-bb2e-9c7c3f496491 :::row::: :::column span=""::: - [`@code`](at-code.md)
[`@CodeSize`](at-codesize.md)
[`@CurSeg`](at-curseg.md) + [`@code`](at-code.md)\ + [`@CodeSize`](at-codesize.md)\ + [`@CurSeg`](at-curseg.md) :::column-end::: :::column span=""::: - [`@data`](at-data.md)
[`@DataSize`](at-datasize.md)
[`@fardata`](at-fardata.md) + [`@data`](at-data.md)\ + [`@DataSize`](at-datasize.md)\ + [`@fardata`](at-fardata.md) :::column-end::: :::column span=""::: - [`@fardata?`](at-fardata-q.md)
[`@Model`](at-model.md) + [`@fardata?`](at-fardata-q.md)\ + [`@Model`](at-model.md) :::column-end::: :::column span=""::: - [`@stack`](at-stack.md)
[`@WordSize`](at-wordsize.md) + [`@stack`](at-stack.md)\ + [`@WordSize`](at-wordsize.md) :::column-end::: :::row-end::: diff --git a/docs/assembler/masm/tbyte.md b/docs/assembler/masm/tbyte.md index 6659ba520e..8553fd5cd3 100644 --- a/docs/assembler/masm/tbyte.md +++ b/docs/assembler/masm/tbyte.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: TBYTE" title: "TBYTE" ms.date: "12/17/2019" f1_keywords: ["TBYTE"] diff --git a/docs/assembler/masm/textequ.md b/docs/assembler/masm/textequ.md index 5d7e77c330..e56588acef 100644 --- a/docs/assembler/masm/textequ.md +++ b/docs/assembler/masm/textequ.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: TEXTEQU" title: "TEXTEQU" ms.date: "12/17/2019" f1_keywords: ["TEXTEQU"] diff --git a/docs/assembler/masm/title.md b/docs/assembler/masm/title.md index e022fcd101..8bda31d7f8 100644 --- a/docs/assembler/masm/title.md +++ b/docs/assembler/masm/title.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: TITLE" title: "TITLE" ms.date: "12/16/2019" f1_keywords: ["title"] diff --git a/docs/assembler/masm/typedef-masm.md b/docs/assembler/masm/typedef-masm.md index 2735de98a5..93e5a43db6 100644 --- a/docs/assembler/masm/typedef-masm.md +++ b/docs/assembler/masm/typedef-masm.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: TYPEDEF" title: "TYPEDEF (MASM)" ms.date: "12/16/2019" f1_keywords: ["typedef"] diff --git a/docs/assembler/masm/union.md b/docs/assembler/masm/union.md index 236107c1f2..507db9afdf 100644 --- a/docs/assembler/masm/union.md +++ b/docs/assembler/masm/union.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: UNION" title: "UNION" ms.date: "12/17/2019" f1_keywords: ["union"] diff --git a/docs/assembler/masm/while-masm.md b/docs/assembler/masm/while-masm.md index 94c0556ba9..fc693f6061 100644 --- a/docs/assembler/masm/while-masm.md +++ b/docs/assembler/masm/while-masm.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: WHILE" title: "WHILE (MASM)" ms.date: "12/16/2019" helpviewer_keywords: ["WHILE directive"] diff --git a/docs/assembler/masm/word.md b/docs/assembler/masm/word.md index 8304c1dc8f..3345165dfd 100644 --- a/docs/assembler/masm/word.md +++ b/docs/assembler/masm/word.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: WORD" title: "WORD" ms.date: "12/17/2019" f1_keywords: ["WORD"] diff --git a/docs/assembler/masm/xmmword.md b/docs/assembler/masm/xmmword.md index 1324fde5a5..9e4ef7c064 100644 --- a/docs/assembler/masm/xmmword.md +++ b/docs/assembler/masm/xmmword.md @@ -1,9 +1,9 @@ --- title: "XMMWORD" -ms.date: "12/17/2019" +description: "Learn more about: XMMWORD" +ms.date: 12/17/2019 f1_keywords: ["XMMWORD"] helpviewer_keywords: ["XMMWORD directive"] -ms.assetid: 18026d32-5cab-403e-ad7e-382fb41aa9b8 --- # XMMWORD @@ -23,6 +23,6 @@ Used for 128-bit multimedia operands with MMX and SSE (XMM) instructions. movdqa xmm0, xmmword ptr [ebx] ``` -## See Also +## See also [MASM BNF Grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/ymmword.md b/docs/assembler/masm/ymmword.md index 7e2f2030dc..993f51251e 100644 --- a/docs/assembler/masm/ymmword.md +++ b/docs/assembler/masm/ymmword.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: YMMWORD" title: "YMMWORD" ms.date: "12/17/2019" f1_keywords: ["YMMWORD"] 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 00a548c77c..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 @@ -1,11 +1,12 @@ --- +description: "Learn more about: Allocating and Releasing Memory for a BSTR" title: "Allocating and Releasing Memory for a BSTR" ms.date: "11/04/2016" f1_keywords: ["bstr"] helpviewer_keywords: ["BSTRs, memory allocation", "memory deallocation, string memory", "memory [C++], releasing", "memory allocation, BSTRs", "memory deallocation, BSTR memory", "strings [C++], releasing"] ms.assetid: 98041e29-3442-4a02-b425-7a4a13e9cc84 --- -# Allocating and Releasing Memory for a BSTR +# Allocating and Releasing Memory for a `BSTR` When you create `BSTR`s and pass them between COM objects, you must take care in treating the memory they use in order to avoid memory leaks. When a `BSTR` stays within an interface, you must free its memory when you are done with it. However, when a `BSTR` passes out of an interface, the receiving object takes responsibility for its memory management. @@ -14,22 +15,22 @@ 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)] ## See also [Strings (ATL/MFC)](../atl-mfc-shared/strings-atl-mfc.md)
-[CStringT::AllocSysString](../atl-mfc-shared/reference/cstringt-class.md#allocsysstring)
-[SysAllocString](/windows/win32/api/oleauto/nf-oleauto-sysallocstring)
-[SysFreeString](/windows/win32/api/oleauto/nf-oleauto-sysfreestring) +[`CStringT::AllocSysString`](../atl-mfc-shared/reference/cstringt-class.md#allocsysstring)
+[`SysAllocString`](/windows/win32/api/oleauto/nf-oleauto-sysallocstring)
+[`SysFreeString`](/windows/win32/api/oleauto/nf-oleauto-sysfreestring) diff --git a/docs/atl-mfc-shared/atl-mfc-concepts.md b/docs/atl-mfc-shared/atl-mfc-concepts.md index 754186ee0c..6227696c2b 100644 --- a/docs/atl-mfc-shared/atl-mfc-concepts.md +++ b/docs/atl-mfc-shared/atl-mfc-concepts.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL/MFC Concepts" title: "ATL-MFC Concepts" ms.date: "11/04/2016" helpviewer_keywords: ["MFC", "ATL"] diff --git a/docs/atl-mfc-shared/atl-mfc-shared-classes.md b/docs/atl-mfc-shared/atl-mfc-shared-classes.md index 81047ae47b..564d03df38 100644 --- a/docs/atl-mfc-shared/atl-mfc-shared-classes.md +++ b/docs/atl-mfc-shared/atl-mfc-shared-classes.md @@ -1,8 +1,9 @@ --- +description: "Learn more about: ATL/MFC Shared Classes" title: "ATL-MFC Shared Classes" ms.custom: "index-page" ms.date: "11/04/2016" -ms.topic: "conceptual" +ms.topic: "concept-article" f1_keywords: ["vc.classes.shared"] helpviewer_keywords: ["CPoint class, shared class", "CFileTimeSpan class, shared class", "COleDateTime class, shared class", "CFixedStringT class, shared class", "CStrBufT class, shared class", "CFileTime class, shared class", "CRect class, shared class", "CSimpleStringT class, shared class", "CStringT class, shared class", "CSize class, shared class", "CStringData class, shared class", "IAtlStringMgr class, shared class", "shared classes, MFC and ATL", "COleDateTimeSpan class, shared class", "CString objects, shared class", "shared classes"] ms.assetid: e13aaac3-21ec-4f4d-8834-432b40fde544 diff --git a/docs/atl-mfc-shared/avoidance-of-heap-contention.md b/docs/atl-mfc-shared/avoidance-of-heap-contention.md index eb5ed0f104..6639bbbe49 100644 --- a/docs/atl-mfc-shared/avoidance-of-heap-contention.md +++ b/docs/atl-mfc-shared/avoidance-of-heap-contention.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Avoidance of Heap Contention" title: "Avoidance of Heap Contention" ms.date: "11/04/2016" helpviewer_keywords: ["heap contention"] diff --git a/docs/atl-mfc-shared/basic-cstring-operations.md b/docs/atl-mfc-shared/basic-cstring-operations.md index d6c4f3625b..047bd978b2 100644 --- a/docs/atl-mfc-shared/basic-cstring-operations.md +++ b/docs/atl-mfc-shared/basic-cstring-operations.md @@ -1,8 +1,8 @@ --- 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 @@ -18,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/cfixedstringt-example-of-a-custom-string-manager.md b/docs/atl-mfc-shared/cfixedstringt-example-of-a-custom-string-manager.md index 5e1ac5b6b2..11094716d1 100644 --- a/docs/atl-mfc-shared/cfixedstringt-example-of-a-custom-string-manager.md +++ b/docs/atl-mfc-shared/cfixedstringt-example-of-a-custom-string-manager.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CFixedStringT: Example of a Custom String Manager" title: "CFixedStringT: Example of a Custom String Manager" ms.date: "11/04/2016" helpviewer_keywords: ["CFixedStringT class, using a custom string manager"] diff --git a/docs/atl-mfc-shared/codesnippet/CPP/afx-extension-module-structure_1.cpp b/docs/atl-mfc-shared/codesnippet/CPP/afx-extension-module-structure_1.cpp index 597a279a89..ddc30f08be 100644 --- a/docs/atl-mfc-shared/codesnippet/CPP/afx-extension-module-structure_1.cpp +++ b/docs/atl-mfc-shared/codesnippet/CPP/afx-extension-module-structure_1.cpp @@ -1,4 +1,4 @@ -static AFX_EXTENSION_MODULE NVC_MFC_DLLDLL = { NULL, NULL }; +static AFX_EXTENSION_MODULE NVC_MFC_DLLDLL; extern "C" int APIENTRY DllMain(HINSTANCE hInstance, DWORD dwReason, LPVOID lpReserved) { @@ -11,4 +11,4 @@ DllMain(HINSTANCE hInstance, DWORD dwReason, LPVOID lpReserved) // MFC extension DLL one-time initialization if (!AfxInitExtensionModule(NVC_MFC_DLLDLL, hInstance)) - return 0; \ No newline at end of file + return 0; 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/codesnippet/CPP/cstringt-class_39.cpp b/docs/atl-mfc-shared/codesnippet/CPP/cstringt-class_39.cpp index d2b2eb6cf3..8886e69d9f 100644 --- a/docs/atl-mfc-shared/codesnippet/CPP/cstringt-class_39.cpp +++ b/docs/atl-mfc-shared/codesnippet/CPP/cstringt-class_39.cpp @@ -8,4 +8,4 @@ { _tprintf_s(_T("Resulting token: %s\n"), resToken); resToken = str.Tokenize(_T("% #"), curPos); - }; \ No newline at end of file + } \ 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 7bedbe266e..68ff5addc6 100644 --- a/docs/atl-mfc-shared/cstring-argument-passing.md +++ b/docs/atl-mfc-shared/cstring-argument-passing.md @@ -1,22 +1,22 @@ --- +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&`). @@ -25,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-exception-cleanup.md b/docs/atl-mfc-shared/cstring-exception-cleanup.md index e0c6833d51..f9571eb699 100644 --- a/docs/atl-mfc-shared/cstring-exception-cleanup.md +++ b/docs/atl-mfc-shared/cstring-exception-cleanup.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CString Exception Cleanup" title: "CString Exception Cleanup" ms.date: "11/04/2016" helpviewer_keywords: ["CString objects, exceptions", "exception handling, cleanup code"] 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 552f8a996d..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 @@ -1,12 +1,13 @@ --- +description: "Learn more about: CString Operations Relating to C-Style Strings" title: "CString Operations Relating to C-Style Strings" 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. @@ -16,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"; @@ -32,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. @@ -45,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. @@ -55,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. @@ -63,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: @@ -84,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/cstring-semantics.md b/docs/atl-mfc-shared/cstring-semantics.md index a61de26071..a8b283511b 100644 --- a/docs/atl-mfc-shared/cstring-semantics.md +++ b/docs/atl-mfc-shared/cstring-semantics.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CString Semantics" title: "CString Semantics" ms.date: "11/04/2016" helpviewer_keywords: ["semantics in Cstring", "CString objects, assignment semantics", "assignment statements, assigning CString objects"] diff --git a/docs/atl-mfc-shared/date-and-time.md b/docs/atl-mfc-shared/date-and-time.md index 88e82534c9..6285d86cb2 100644 --- a/docs/atl-mfc-shared/date-and-time.md +++ b/docs/atl-mfc-shared/date-and-time.md @@ -1,34 +1,34 @@ --- +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. @@ -68,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/date-type.md b/docs/atl-mfc-shared/date-type.md index 3bd88a5be5..51909869c5 100644 --- a/docs/atl-mfc-shared/date-type.md +++ b/docs/atl-mfc-shared/date-type.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: DATE Type" title: "DATE Type" ms.date: "11/04/2016" f1_keywords: ["DATE"] @@ -49,7 +50,7 @@ The following points should be noted when working with these date and time forma > [!CAUTION] > Note that because 6:00 AM is always represented by a fractional value 0.25 regardless of whether the integer representing the day is positive (after December 30, 1899) or negative (before December 30, 1899), a simple floating point comparison would erroneously sort any DATE representing 6:00 AM on a day earlier than 12/30/1899 as *later* than a DATE representing 7:00 AM on that same day. -More information on issues related to the DATE and `COleDateTime` types can be found under [COleDateTime Class](../atl-mfc-shared/reference/coledatetime-class.md) and [Date and Time: Automation Support](../atl-mfc-shared/date-and-time-automation-support.md). +More information on issues related to the DATE and `COleDateTime` types can be found under [COleDateTime Class](../atl-mfc-shared/reference/coledatetime-class.md) and [Date and Time: Automation Support](./date-and-time.md). ## 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 8c4959aa0e..3e5b794a88 100644 --- a/docs/atl-mfc-shared/exporting-string-classes-using-cstringt.md +++ b/docs/atl-mfc-shared/exporting-string-classes-using-cstringt.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Exporting String Classes Using CStringT" title: "Exporting String Classes Using CStringT" ms.date: "11/04/2016" helpviewer_keywords: ["CStringT class, exporting strings"] @@ -26,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/implementation-of-a-custom-string-manager-advanced-method.md b/docs/atl-mfc-shared/implementation-of-a-custom-string-manager-advanced-method.md index cd9845f74a..55fe40e157 100644 --- a/docs/atl-mfc-shared/implementation-of-a-custom-string-manager-advanced-method.md +++ b/docs/atl-mfc-shared/implementation-of-a-custom-string-manager-advanced-method.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Implementation of a Custom String Manager (Advanced Method)" title: "Implementation of a Custom String Manager (Advanced Method)" ms.date: "11/04/2016" helpviewer_keywords: ["IAtlStringMgr class, using"] diff --git a/docs/atl-mfc-shared/implementation-of-a-custom-string-manager-basic-method.md b/docs/atl-mfc-shared/implementation-of-a-custom-string-manager-basic-method.md index 898169ad67..2e91251aaa 100644 --- a/docs/atl-mfc-shared/implementation-of-a-custom-string-manager-basic-method.md +++ b/docs/atl-mfc-shared/implementation-of-a-custom-string-manager-basic-method.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Implementation of a Custom String Manager (Basic Method)" title: "Implementation of a Custom String Manager (Basic Method)" ms.date: "11/04/2016" helpviewer_keywords: ["IAtlStringMgr class, using"] diff --git a/docs/atl-mfc-shared/memory-management-with-cstringt.md b/docs/atl-mfc-shared/memory-management-with-cstringt.md index 4ae642651b..c0df6f2ceb 100644 --- a/docs/atl-mfc-shared/memory-management-with-cstringt.md +++ b/docs/atl-mfc-shared/memory-management-with-cstringt.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Memory Management with CStringT" title: "Memory Management with CStringT" ms.date: "11/04/2016" helpviewer_keywords: ["CString objects, memory management", "memory [C++], usage", "IAtlStringMgr class, using", "strings [C++], custom memory management", "CFixedStringT class, description of", "strings [C++], memory management", "CStringT class, memory management"] diff --git a/docs/atl-mfc-shared/reference/cfiletime-class.md b/docs/atl-mfc-shared/reference/cfiletime-class.md index e3b94df1ff..35d7d8dc48 100644 --- a/docs/atl-mfc-shared/reference/cfiletime-class.md +++ b/docs/atl-mfc-shared/reference/cfiletime-class.md @@ -1,99 +1,100 @@ --- -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(); @@ -101,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. @@ -139,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; ``` @@ -191,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. @@ -420,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. @@ -439,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 5ddf71a9c3..c236dcb8d4 100644 --- a/docs/atl-mfc-shared/reference/cfixedstringt-class.md +++ b/docs/atl-mfc-shared/reference/cfixedstringt-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CFixedStringT Class" title: "CFixedStringT Class" ms.date: "03/27/2019" f1_keywords: ["CFixedStringT", "CSTRINGT/ATL::CFixedStringT", "CSTRINGT/ATL::CFixedStringT::CFixedStringT"] @@ -11,7 +12,7 @@ This class represents a string object with a fixed character buffer. ## Syntax -``` +```cpp template class CFixedStringT : private CFixedStringMgr, public StringType ``` @@ -68,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); @@ -97,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 a641f06038..d355d0f27a 100644 --- a/docs/atl-mfc-shared/reference/cimage-class.md +++ b/docs/atl-mfc-shared/reference/cimage-class.md @@ -1,11 +1,11 @@ --- title: "CImage Class" -ms.date: "08/19/2019" +description: "Learn more about: CImage Class" +ms.date: 08/19/2019 f1_keywords: ["CImage", "ATLIMAGE/ATL::CImage", "ATLIMAGE/ATL::CImage::CImage", "ATLIMAGE/ATL::CImage::AlphaBlend", "ATLIMAGE/ATL::CImage::Attach", "ATLIMAGE/ATL::CImage::BitBlt", "ATLIMAGE/ATL::CImage::Create", "ATLIMAGE/ATL::CImage::CreateEx", "ATLIMAGE/ATL::CImage::Destroy", "ATLIMAGE/ATL::CImage::Detach", "ATLIMAGE/ATL::CImage::Draw", "ATLIMAGE/ATL::CImage::GetBits", "ATLIMAGE/ATL::CImage::GetBPP", "ATLIMAGE/ATL::CImage::GetColorTable", "ATLIMAGE/ATL::CImage::GetDC", "ATLIMAGE/ATL::CImage::GetExporterFilterString", "ATLIMAGE/ATL::CImage::GetHeight", "ATLIMAGE/ATL::CImage::GetImporterFilterString", "ATLIMAGE/ATL::CImage::GetMaxColorTableEntries", "ATLIMAGE/ATL::CImage::GetPitch", "ATLIMAGE/ATL::CImage::GetPixel", "ATLIMAGE/ATL::CImage::GetPixelAddress", "ATLIMAGE/ATL::CImage::GetTransparentColor", "ATLIMAGE/ATL::CImage::GetWidth", "ATLIMAGE/ATL::CImage::IsDIBSection", "ATLIMAGE/ATL::CImage::IsIndexed", "ATLIMAGE/ATL::CImage::IsNull", "ATLIMAGE/ATL::CImage::IsTransparencySupported", "ATLIMAGE/ATL::CImage::Load", "ATLIMAGE/ATL::CImage::LoadFromResource", "ATLIMAGE/ATL::CImage::MaskBlt", "ATLIMAGE/ATL::CImage::PlgBlt", "ATLIMAGE/ATL::CImage::ReleaseDC", "ATLIMAGE/ATL::CImage::ReleaseGDIPlus", "ATLIMAGE/ATL::CImage::Save", "ATLIMAGE/ATL::CImage::SetColorTable", "ATLIMAGE/ATL::CImage::SetPixel", "ATLIMAGE/ATL::CImage::SetPixelIndexed", "ATLIMAGE/ATL::CImage::SetPixelRGB", "ATLIMAGE/ATL::CImage::SetTransparentColor", "ATLIMAGE/ATL::CImage::StretchBlt", "ATLIMAGE/ATL::CImage::TransparentBlt"] 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. @@ -14,7 +14,7 @@ ms.assetid: 52861e3d-bf7e-481f-a240-90e88f76c490 ## Syntax -``` +```cpp class CImage ``` @@ -24,87 +24,87 @@ 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). -## Example +## Examples ```cpp // Get a CDC for the image @@ -115,9 +115,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*`. - -## Example +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) @@ -132,24 +130,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, @@ -186,46 +184,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 @@ -236,11 +234,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(); @@ -248,27 +246,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, @@ -299,37 +297,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 @@ -338,29 +336,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, @@ -370,32 +368,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, @@ -407,36 +405,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 @@ -447,7 +445,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. @@ -455,23 +453,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, @@ -511,41 +509,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 @@ -553,11 +551,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. @@ -571,16 +569,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(); ``` @@ -592,9 +590,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. @@ -607,20 +605,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(); ``` @@ -630,13 +628,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, @@ -647,17 +645,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: @@ -669,7 +667,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. @@ -692,34 +690,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(); ``` @@ -727,11 +725,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, @@ -742,17 +740,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: @@ -764,7 +762,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. @@ -787,30 +785,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(); ``` @@ -822,11 +820,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(); ``` @@ -838,32 +836,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. @@ -873,10 +871,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 @@ -888,11 +886,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(); ``` @@ -900,11 +898,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(); ``` @@ -912,72 +910,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(); ``` @@ -987,38 +985,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( @@ -1032,24 +1030,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, @@ -1087,49 +1085,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 @@ -1140,15 +1138,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, @@ -1175,38 +1173,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 @@ -1214,11 +1212,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. @@ -1228,9 +1226,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+. @@ -1240,13 +1238,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(); @@ -1258,13 +1256,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. @@ -1280,13 +1278,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. @@ -1299,20 +1297,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. @@ -1322,22 +1320,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(); @@ -1345,18 +1343,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( @@ -1369,47 +1367,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, @@ -1444,40 +1442,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 @@ -1486,13 +1484,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, @@ -1527,49 +1525,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 @@ -1602,10 +1600,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 7f341a1595..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 @@ -1,4 +1,5 @@ --- +description: "Learn more about: Classes Shared by MFC and ATL" title: "Classes Shared by MFC and ATL" ms.date: "11/04/2016" helpviewer_keywords: ["shared classes, classes"] @@ -20,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 d2718a2ac1..5da193d9b9 100644 --- a/docs/atl-mfc-shared/reference/coledatetime-class.md +++ b/docs/atl-mfc-shared/reference/coledatetime-class.md @@ -1,9 +1,9 @@ --- title: "COleDateTime Class" -ms.date: "03/27/2019" +description: "API reference for the MFC COleDateTime class which Encapsulates the `DATE` data type used in OLE automation." +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 @@ -11,7 +11,7 @@ Encapsulates the `DATE` data type that is used in OLE automation. ## Syntax -``` +```cpp class COleDateTime ``` @@ -83,7 +83,7 @@ The `DATE` type is implemented as a floating-point value. Days are measured from > [!CAUTION] > In the table above, although day values become negative before midnight on December 30, 1899, time-of-day values do not. For example, 6:00 AM is always represented by a fractional value 0.25 regardless of whether the integer representing the day is positive (after December 30, 1899) or negative (before December 30, 1899). This means that a simple floating point comparison would erroneously sort a `COleDateTime` representing 6:00 AM on 12/29/1899 as **later** than one representing 7:00 AM on the same day. -The `COleDateTime` class handles dates from January 1, 100, through December 31, 9999. The `COleDateTime` class uses the Gregorian calendar; it does not support Julian dates. `COleDateTime` ignores Daylight Saving Time. (See [Date and Time: Automation Support](../../atl-mfc-shared/date-and-time-automation-support.md).) +The `COleDateTime` class handles dates from January 1, 100, through December 31, 9999. The `COleDateTime` class uses the Gregorian calendar; it does not support Julian dates. `COleDateTime` ignores Daylight Saving Time. (See [Date and Time: Automation Support](../date-and-time.md).) > [!NOTE] > You can use the `%y` format to retrieve a two-digit year only for dates starting at 1900. If you use the `%y` format on a date before 1900, the code generates an ASSERT failure. @@ -98,7 +98,7 @@ To avoid problems, specify a four-digit date. For example: Basic arithmetic operations for the `COleDateTime` values use the companion class [COleDateTimeSpan](../../atl-mfc-shared/reference/coledatetimespan-class.md). `COleDateTimeSpan` values define a time interval. The relationship between these classes is similar to the one between [CTime](../../atl-mfc-shared/reference/ctime-class.md) and [CTimeSpan](../../atl-mfc-shared/reference/ctimespan-class.md). -For more information about the `COleDateTime` and `COleDateTimeSpan` classes, see the article [Date and Time: Automation Support](../../atl-mfc-shared/date-and-time-automation-support.md). +For more information about the `COleDateTime` and `COleDateTimeSpan` classes, see the article [Date and Time: Automation Support](../date-and-time.md). ## Requirements @@ -108,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(); @@ -127,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)] @@ -141,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(); @@ -212,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. @@ -230,7 +228,7 @@ For more information on the `time_t` data type, see the [time](../../c-runtime-l For more information, see the [SYSTEMTIME](/windows/win32/api/minwinbase/ns-minwinbase-systemtime) and [FILETIME](/windows/win32/api/minwinbase/ns-minwinbase-filetime) structures in the Windows SDK. -For more information about the bounds for `COleDateTime` values, see the article [Date and Time: Automation Support](../../atl-mfc-shared/date-and-time-automation-support.md). +For more information about the bounds for `COleDateTime` values, see the article [Date and Time: Automation Support](../date-and-time.md). > [!NOTE] > The constructor using `DBTIMESTAMP` parameter is only available when OLEDB.h is included. @@ -243,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; @@ -264,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 @@ -304,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(); ``` @@ -329,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(); ``` @@ -352,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(); ``` @@ -373,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(); ``` @@ -385,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(); ``` @@ -419,9 +417,9 @@ For information on other member functions that query the value of this `COleDate ## COleDateTime::GetDayOfWeek -Gets the day of the month represented by this date/time value. +Gets the day of the week represented by this date/time value. -``` +```cpp int GetDayOfWeek() const throw(); ``` @@ -457,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(); ``` @@ -493,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(); ``` @@ -529,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(); ``` @@ -565,7 +563,7 @@ See the example for [GetHour](#gethour). Gets the month represented by this date/time value. -``` +```cpp int GetMonth() const throw(); ``` @@ -601,7 +599,7 @@ See the example for [GetDay](#getday). Gets the second represented by this date/time value. -``` +```cpp int GetSecond() const throw(); ``` @@ -616,7 +614,7 @@ Valid return values range between 0 and 59. > [!NOTE] > The `COleDateTime` class does not support leap seconds. -For more information about the implementation for `COleDateTime`, see the article [Date and Time: Automation Support](../../atl-mfc-shared/date-and-time-automation-support.md). +For more information about the implementation for `COleDateTime`, see the article [Date and Time: Automation Support](../date-and-time.md). For information on other member functions that query the value of this `COleDateTime` object, see the following member functions: @@ -642,7 +640,7 @@ See the example for [GetHour](#gethour). Gets the status (validity) of a given `COleDateTime` object. -``` +```cpp DateTimeStatus GetStatus() const throw(); ``` @@ -654,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, @@ -698,7 +696,7 @@ For more information about the operations that may set the status to invalid, se - [operator +=, -=](#operator_add_eq_-_eq) -For more information about the bounds for `COleDateTime` values, see the article [Date and Time: Automation Support](../../atl-mfc-shared/date-and-time-automation-support.md). +For more information about the bounds for `COleDateTime` values, see the article [Date and Time: Automation Support](../date-and-time.md). ### Example @@ -708,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(); ``` @@ -736,7 +734,7 @@ For information on other member functions that query the value of this `COleDate - [GetDayOfYear](#getdayofyear) -For more information about the bounds for `COleDateTime` values, see the article [Date and Time: Automation Support](../../atl-mfc-shared/date-and-time-automation-support.md). +For more information about the bounds for `COleDateTime` values, see the article [Date and Time: Automation Support](../date-and-time.md). ### Example @@ -746,7 +744,7 @@ See the example for [GetDay](#getday). The underlying `DATE` structure for this `COleDateTime` object. -``` +```cpp DATE m_dt; ``` @@ -755,13 +753,13 @@ DATE m_dt; > [!CAUTION] > Changing the value in the `DATE` object accessed by the pointer returned by this function will change the value of this `COleDateTime` object. It does not change the status of this `COleDateTime` object. -For more information about the implementation of the `DATE` object, see the article [Date and Time: Automation Support](../../atl-mfc-shared/date-and-time-automation-support.md). +For more information about the implementation of the `DATE` object, see the article [Date and Time: Automation Support](../date-and-time.md). ## COleDateTime::m_status Contains the status of this `COleDateTime` object. -``` +```cpp DateTimeStatus m_status; ``` @@ -776,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(); @@ -810,13 +808,13 @@ For more information on the `time_t` data type, see the [time](../../c-runtime-l For more information, see the [SYSTEMTIME](/windows/win32/api/minwinbase/ns-minwinbase-systemtime) and [FILETIME](/windows/win32/api/minwinbase/ns-minwinbase-filetime) structures in the Windows SDK. -For more information about the bounds for `COleDateTime` values, see the article [Date and Time: Automation Support](../../atl-mfc-shared/date-and-time-automation-support.md). +For more information about the bounds for `COleDateTime` values, see the article [Date and Time: Automation Support](../date-and-time.md). ## COleDateTime::operator +, - 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(); @@ -836,7 +834,7 @@ The **+** and **-** operators will assert if the `COleDateTime` object is set to For more information on the valid, invalid, and null status values, see the [m_status](#m_status) member variable. -For more information about the bounds for `COleDateTime` values, see the article [Date and Time: Automation Support](../../atl-mfc-shared/date-and-time-automation-support.md). +For more information about the bounds for `COleDateTime` values, see the article [Date and Time: Automation Support](../date-and-time.md). ### Example @@ -846,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(); ``` @@ -863,19 +861,19 @@ For more information on the valid, invalid, and null status values, see the [m_s The **+=** and **-=** operators will assert if the `COleDateTime` object is set to null. See [COleDateTime Relational Operators](#coledatetime_relational_operators) for an example. -For more information about the bounds for `COleDateTime` values, see the article [Date and Time: Automation Support](../../atl-mfc-shared/date-and-time-automation-support.md). +For more information about the bounds for `COleDateTime` values, see the article [Date and Time: Automation Support](../date-and-time.md). ## COleDateTime::operator DATE Converts a `ColeDateTime` value into a `DATE`. -``` +```cpp operator DATE() const throw(); ``` ### Remarks -This operator returns a `DATE` object whose value is copied from this `COleDateTime` object. For more information about the implementation of the `DATE` object, see the article [Date and Time: Automation Support](../../atl-mfc-shared/date-and-time-automation-support.md). +This operator returns a `DATE` object whose value is copied from this `COleDateTime` object. For more information about the implementation of the `DATE` object, see the article [Date and Time: Automation Support](../date-and-time.md). The `DATE` operator will assert if the `COleDateTime` object is set to null. See [COleDateTime Relational Operators](#coledatetime_relational_operators) for an example. @@ -883,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, @@ -938,13 +936,13 @@ In the case of VAR_DATEVALUEONLY, the time value is set to time 0, or midnight. If the string could not be converted to a date/time value or if there was a numerical overflow, the status of this `COleDateTime` object is invalid. -For more information about the bounds and implementation for `COleDateTime` values, see the article [Date and Time: Automation Support](../../atl-mfc-shared/date-and-time-automation-support.md). +For more information about the bounds and implementation for `COleDateTime` values, see the article [Date and Time: Automation Support](../date-and-time.md). ## COleDateTime::SetDate Sets the date of this `COleDateTime` object. -``` +```cpp int SetDate( int nYear, int nMonth, @@ -1011,7 +1009,7 @@ For information on member functions that query the value of this `COleDateTime` - [GetDayOfYear](#getdayofyear) -For more information about the bounds for `COleDateTime` values, see the article [Date and Time: Automation Support](../../atl-mfc-shared/date-and-time-automation-support.md). +For more information about the bounds for `COleDateTime` values, see the article [Date and Time: Automation Support](../date-and-time.md). ### Example @@ -1021,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, @@ -1095,7 +1093,7 @@ For information on member functions that query the value of this `COleDateTime` - [GetDayOfYear](#getdayofyear) -For more information about the bounds for `COleDateTime` values, see the article [Date and Time: Automation Support](../../atl-mfc-shared/date-and-time-automation-support.md). +For more information about the bounds for `COleDateTime` values, see the article [Date and Time: Automation Support](../date-and-time.md). ### Example @@ -1129,7 +1127,7 @@ See the example for [GetStatus](#getstatus). Sets the time of this `COleDateTime` object. -``` +```cpp int SetTime( int nHour, int nMin, @@ -1188,7 +1186,7 @@ For information on member functions that query the value of this `COleDateTime` - [GetDayOfYear](#getdayofyear) -For more information about the bounds for `COleDateTime` values, see the article [Date and Time: Automation Support](../../atl-mfc-shared/date-and-time-automation-support.md). +For more information about the bounds for `COleDateTime` values, see the article [Date and Time: Automation Support](../date-and-time.md). ### Example diff --git a/docs/atl-mfc-shared/reference/coledatetimespan-class.md b/docs/atl-mfc-shared/reference/coledatetimespan-class.md index 1696713780..491074bbae 100644 --- a/docs/atl-mfc-shared/reference/coledatetimespan-class.md +++ b/docs/atl-mfc-shared/reference/coledatetimespan-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: COleDateTimeSpan Class" title: "COleDateTimeSpan Class" ms.date: "03/27/2019" f1_keywords: ["COleDateTimeSpan", "ATLCOMTIME/ATL::COleDateTimeSpan", "ATLCOMTIME/ATL::COleDateTimeSpan::COleDateTimeSpan", "ATLCOMTIME/ATL::COleDateTimeSpan::Format", "ATLCOMTIME/ATL::COleDateTimeSpan::GetDays", "ATLCOMTIME/ATL::COleDateTimeSpan::GetHours", "ATLCOMTIME/ATL::COleDateTimeSpan::GetMinutes", "ATLCOMTIME/ATL::COleDateTimeSpan::GetSeconds", "ATLCOMTIME/ATL::COleDateTimeSpan::GetStatus", "ATLCOMTIME/ATL::COleDateTimeSpan::GetTotalDays", "ATLCOMTIME/ATL::COleDateTimeSpan::GetTotalHours", "ATLCOMTIME/ATL::COleDateTimeSpan::GetTotalMinutes", "ATLCOMTIME/ATL::COleDateTimeSpan::GetTotalSeconds", "ATLCOMTIME/ATL::COleDateTimeSpan::SetDateTimeSpan", "ATLCOMTIME/ATL::COleDateTimeSpan::SetStatus", "ATLCOMTIME/ATL::COleDateTimeSpan::m_span", "ATLCOMTIME/ATL::COleDateTimeSpan::m_status"] @@ -11,7 +12,7 @@ Represents a relative time, a time span. ## Syntax -``` +```cpp class COleDateTimeSpan ``` @@ -42,7 +43,7 @@ class COleDateTimeSpan ### Public Operators -||| +|Name|Description| |-|-| |[operator +, -](#operator_add_-)|Add, subtract, and change sign for `COleDateTimeSpan` values.| |[operator +=, -=](#operator_add_eq_-_eq)|Add and subtract a `COleDateTimeSpan` value from this `COleDateTimeSpan` value.| @@ -65,7 +66,7 @@ A `COleDateTimeSpan` keeps time in days. `COleDateTimeSpan` is used with its companion class [COleDateTime](../../atl-mfc-shared/reference/coledatetime-class.md). `COleDateTime` encapsulates the `DATE` data type of OLE automation. `COleDateTime` represents absolute time values. All `COleDateTime` calculations involve `COleDateTimeSpan` values. The relation between these classes is analogous to the one between [CTime](../../atl-mfc-shared/reference/ctime-class.md) and [CTimeSpan](../../atl-mfc-shared/reference/ctimespan-class.md). -For more information on the `COleDateTime` and `COleDateTimeSpan` classes, see the article [Date and Time: Automation Support](../../atl-mfc-shared/date-and-time-automation-support.md). +For more information on the `COleDateTime` and `COleDateTimeSpan` classes, see the article [Date and Time: Automation Support](../date-and-time.md). ## Requirements @@ -75,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(); @@ -101,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(); @@ -134,7 +135,7 @@ All of these constructors create new `COleDateTimeSpan` objects initialized to t The status of the new `COleDateTimeSpan` object is set to valid. -For more information about the bounds for `COleDateTimeSpan` values, see the article [Date and Time: Automation Support](../../atl-mfc-shared/date-and-time-automation-support.md). +For more information about the bounds for `COleDateTimeSpan` values, see the article [Date and Time: Automation Support](../date-and-time.md). ### Example @@ -144,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; ``` @@ -193,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(); ``` @@ -229,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(); ``` @@ -265,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(); ``` @@ -301,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(); ``` @@ -337,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(); ``` @@ -349,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, @@ -375,13 +376,13 @@ The status of a `COleDateTimeSpan` object is invalid in the following cases: For more information about the operations that may set the status to invalid, see [COleDateTimeSpan::operator +, -](../../atl-mfc-shared/reference/coledatetime-class.md#operator_add_-) and [COleDateTimeSpan::operator +=, -=](../../atl-mfc-shared/reference/coledatetime-class.md#operator_add_eq_-_eq). -For more information about the bounds for `COleDateTimeSpan` values, see the article [Date and Time: Automation Support](../../atl-mfc-shared/date-and-time-automation-support.md). +For more information about the bounds for `COleDateTimeSpan` values, see the article [Date and Time: Automation Support](../date-and-time.md). ## COleDateTimeSpan::GetTotalDays Retrieves this date/time-span value expressed in days. -``` +```cpp double GetTotalDays() const throw(); ``` @@ -417,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(); ``` @@ -453,7 +454,7 @@ See the example for [GetTotalDays](#gettotaldays). Retrieves this date/time-span value expressed in minutes. -``` +```cpp double GetTotalMinutes() const throw(); ``` @@ -489,7 +490,7 @@ See the example for [GetTotalDays](#gettotaldays). Retrieves this date/time-span value expressed in seconds. -``` +```cpp double GetTotalSeconds() const throw(); ``` @@ -525,7 +526,7 @@ See the example for [GetTotalDays](#gettotaldays). The underlying **`double`** value for this `COleDateTime` object. -``` +```cpp double m_span; ``` @@ -540,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, @@ -575,13 +576,13 @@ For more information about the operations that may set the status to invalid, se > [!CAUTION] > This data member is for advanced programming situations. You should use the inline member functions [GetStatus](#getstatus) and [SetStatus](#setstatus). See `SetStatus` for further cautions regarding explicitly setting this data member. -For more information about the bounds for `COleDateTimeSpan` values, see the article [Date and Time: Automation Support](../../atl-mfc-shared/date-and-time-automation-support.md). +For more information about the bounds for `COleDateTimeSpan` values, see the article [Date and Time: Automation Support](../date-and-time.md). ## COleDateTimeSpan::operator = Copies a `COleDateTimeSpan` value. -``` +```cpp COleDateTimeSpan& operator=(double dblSpanSrc) throw(); ``` @@ -593,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(); @@ -617,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(); ``` @@ -638,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(); ``` @@ -700,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 bfc0a63839..1636a18f6d 100644 --- a/docs/atl-mfc-shared/reference/cpoint-class.md +++ b/docs/atl-mfc-shared/reference/cpoint-class.md @@ -1,17 +1,17 @@ --- +description: "Learn more about: CPoint Class" 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 ``` @@ -21,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`. @@ -60,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(); @@ -76,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 @@ -122,7 +122,7 @@ CPoint ptFromDouble(dwSize); ASSERT(ptFromDouble == ptMFCHere); ``` -## CPoint::Offset +## `CPoint::Offset` Adds values to the `x` and `y` members of the `CPoint`. @@ -134,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(); @@ -181,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(); @@ -203,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(); @@ -232,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(); @@ -262,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(); @@ -298,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 @@ -319,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 @@ -329,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 fdf150d45e..a213a9fcb6 100644 --- a/docs/atl-mfc-shared/reference/crect-class.md +++ b/docs/atl-mfc-shared/reference/crect-class.md @@ -1,17 +1,17 @@ --- title: "CRect Class" -ms.date: "11/06/2018" +description: "Learn more about: CRect Class" +ms.date: 11/06/2018 f1_keywords: ["CRect", "ATLTYPES/ATL::CRect", "ATLTYPES/ATL::CRect::CRect", "ATLTYPES/ATL::CRect::BottomRight", "ATLTYPES/ATL::CRect::CenterPoint", "ATLTYPES/ATL::CRect::CopyRect", "ATLTYPES/ATL::CRect::DeflateRect", "ATLTYPES/ATL::CRect::EqualRect", "ATLTYPES/ATL::CRect::Height", "ATLTYPES/ATL::CRect::InflateRect", "ATLTYPES/ATL::CRect::IntersectRect", "ATLTYPES/ATL::CRect::IsRectEmpty", "ATLTYPES/ATL::CRect::IsRectNull", "ATLTYPES/ATL::CRect::MoveToX", "ATLTYPES/ATL::CRect::MoveToXY", "ATLTYPES/ATL::CRect::MoveToY", "ATLTYPES/ATL::CRect::NormalizeRect", "ATLTYPES/ATL::CRect::OffsetRect", "ATLTYPES/ATL::CRect::PtInRect", "ATLTYPES/ATL::CRect::SetRect", "ATLTYPES/ATL::CRect::SetRectEmpty", "ATLTYPES/ATL::CRect::Size", "ATLTYPES/ATL::CRect::SubtractRect", "ATLTYPES/ATL::CRect::TopLeft", "ATLTYPES/ATL::CRect::UnionRect", "ATLTYPES/ATL::CRect::Width"] 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 ``` @@ -21,53 +21,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 @@ -80,11 +80,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 @@ -94,11 +94,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(); @@ -139,7 +139,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. @@ -202,7 +202,7 @@ void CMyDlg::OnPaint() } ``` -## CRect::CopyRect +## `CRect::CopyRect` Copies the `lpSrcRect` rectangle into `CRect`. @@ -212,8 +212,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 @@ -237,7 +237,7 @@ rectDest.CopyRect(&rectSource2); // rectDest is now set to (0, 0, 640, 480) ``` -## CRect::CRect +## `CRect::CRect` Constructs a `CRect` object. @@ -252,47 +252,47 @@ 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 not initialized. +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 ```cpp -// default constructor doesn't initialize! -CRect rectUnknown; +// default constructor is equivalent to CRect(0, 0, 0, 0) +CRect emptyRect; // four-integers are left, top, right, and bottom CRect rect(0, 0, 100, 50); @@ -326,7 +326,7 @@ CRect rect5(pt, ptBottomRight); ASSERT(rect5 == rect4); ``` -## CRect::DeflateRect +## `CRect::DeflateRect` `DeflateRect` deflates `CRect` by moving its sides toward its center. @@ -339,35 +339,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 @@ -384,7 +384,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. @@ -394,15 +394,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 @@ -423,11 +423,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(); ``` @@ -440,7 +440,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 @@ -452,7 +452,7 @@ int nHt = rect.Height(); ASSERT(nHt == 40); ``` -## CRect::InflateRect +## `CRect::InflateRect` `InflateRect` inflates `CRect` by moving its sides away from its center. @@ -465,35 +465,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 @@ -505,20 +505,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 @@ -530,7 +530,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 @@ -548,11 +548,11 @@ rectInter2 &= rectTwo; ASSERT(rectInter2 == CRect(125, 75, 150, 95)); ``` -## CRect::IsRectEmpty +## `CRect::IsRectEmpty` Determines whether `CRect` is empty. -``` +```cpp BOOL IsRectEmpty() const throw(); ``` @@ -565,7 +565,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 @@ -578,11 +578,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(); ``` @@ -607,9 +607,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(); @@ -617,7 +617,7 @@ void MoveToX(int x) throw(); ### Parameters -*x*
+*`x`*
The absolute x-coordinate for the upper-left corner of the rectangle. ### Example @@ -630,7 +630,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. @@ -641,13 +641,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 @@ -659,9 +659,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(); @@ -669,7 +669,7 @@ void MoveToY(int y) throw(); ### Parameters -*y*
+*`y`*
The absolute y-coordinate for the upper-left corner of the rectangle. ### Example @@ -681,7 +681,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. @@ -694,7 +694,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 @@ -706,7 +706,7 @@ rect2.NormalizeRect(); ASSERT(rect1 == rect2); ``` -## CRect::OffsetRect +## `CRect::OffsetRect` Moves `CRect` by the specified offsets. @@ -718,21 +718,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 @@ -744,35 +744,37 @@ 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(); @@ -780,8 +782,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 @@ -793,18 +795,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 @@ -813,7 +815,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 @@ -833,18 +835,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 @@ -853,7 +855,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 @@ -873,7 +875,7 @@ test.bottom = 25; ASSERT(rect3 != test); ``` -## CRect::operator += +## `CRect::operator +=` The first two overloads move `CRect` by the specified offsets. @@ -885,18 +887,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. @@ -911,7 +913,7 @@ rect1 += pt; ASSERT(rect1 == rect2); ``` -## CRect::operator -= +## `CRect::operator -=` The first two overloads move `CRect` by the specified offsets. @@ -923,20 +925,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 @@ -949,7 +951,7 @@ CRect rectResult(65, 170, 165, 270); ASSERT(rect1 == rectResult); ``` -## CRect::operator &= +## `CRect::operator &=` Sets `CRect` equal to the intersection of `CRect` and `rect`. @@ -959,21 +961,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`. @@ -983,15 +985,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 @@ -1004,11 +1006,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(); @@ -1016,14 +1018,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 @@ -1031,7 +1033,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. @@ -1047,11 +1049,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(); @@ -1059,14 +1061,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 @@ -1074,9 +1076,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 @@ -1090,29 +1092,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 @@ -1126,30 +1128,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 @@ -1163,18 +1165,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 @@ -1185,7 +1187,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 @@ -1215,7 +1217,7 @@ pt.y = 50; ASSERT(rect.PtInRect(pt)); ``` -## CRect::SetRect +## `CRect::SetRect` Sets the dimensions of `CRect` to the specified coordinates. @@ -1225,16 +1227,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 @@ -1245,7 +1247,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. @@ -1263,7 +1265,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`. @@ -1273,14 +1275,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 @@ -1290,21 +1292,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 @@ -1312,16 +1314,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 @@ -1357,11 +1359,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(); ``` @@ -1376,22 +1378,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 @@ -1405,7 +1407,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 @@ -1419,11 +1421,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(); ``` @@ -1436,7 +1438,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 @@ -1449,6 +1451,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 29bb94899a..b62a850efa 100644 --- a/docs/atl-mfc-shared/reference/csimplestringt-class.md +++ b/docs/atl-mfc-shared/reference/csimplestringt-class.md @@ -1,31 +1,31 @@ --- 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 @@ -33,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. @@ -103,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 @@ -121,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")); @@ -128,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. @@ -140,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, @@ -202,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); @@ -234,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 @@ -258,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); @@ -272,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. @@ -284,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. @@ -307,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 @@ -336,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 @@ -346,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(); ``` @@ -362,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 @@ -385,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 @@ -396,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 @@ -422,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`. @@ -430,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 @@ -445,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 @@ -468,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`. @@ -479,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 @@ -494,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(); ``` @@ -520,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(); ``` @@ -538,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(); ``` @@ -566,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 @@ -598,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(); ``` @@ -622,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: @@ -640,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; @@ -649,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 @@ -680,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 @@ -720,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 @@ -742,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 @@ -789,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(); ``` @@ -841,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. @@ -863,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 @@ -905,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 @@ -934,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 @@ -946,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. @@ -965,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 @@ -985,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. @@ -997,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 @@ -1013,7 +1037,7 @@ CSimpleString s(pMgr); s.SetManager(pCustomMgr); ``` -## CSimpleStringT::SetString +## `CSimpleStringT::SetString` Sets the string of a `CSimpleStringT` object. @@ -1026,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 @@ -1055,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 @@ -1086,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. @@ -1098,7 +1122,7 @@ void Truncate(int nNewLength); #### Parameters -*nNewLength*
+*`nNewLength`*
The new length of the string. ### Remarks @@ -1106,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. @@ -1135,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(); ``` @@ -1153,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 179cb83856..f398b5055d 100644 --- a/docs/atl-mfc-shared/reference/csize-class.md +++ b/docs/atl-mfc-shared/reference/csize-class.md @@ -1,9 +1,9 @@ --- 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 @@ -11,7 +11,7 @@ Similar to the Windows [SIZE](/windows/win32/api/windef/ns-windef-size) structur ## Syntax -``` +```cpp class CSize : public tagSIZE ``` @@ -57,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(); @@ -94,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 @@ -110,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(); ``` @@ -150,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(); @@ -180,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 0498aaed9c..4cc53bfee5 100644 --- a/docs/atl-mfc-shared/reference/cstrbuft-class.md +++ b/docs/atl-mfc-shared/reference/cstrbuft-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CStrBufT Class" title: "CStrBufT Class" ms.date: "10/18/2018" f1_keywords: ["CStrBufT", "ATLSIMPSTR/ATL::CStrBufT", "ATLSIMPSTR/ATL::CStrBufT::CStrBufT", "ATLSIMPSTR/ATL::CStrBufT::SetLength", "ATLSIMPSTR/ATL::CStrBufT::AUTO_LENGTH", "ATLSIMPSTR/ATL::CStrBufT::SET_LENGTH"] @@ -11,7 +12,7 @@ This class provides automatic resource cleanup for `GetBuffer` and `ReleaseBuffe ## Syntax -``` +```cpp template class CStrBufT ``` @@ -25,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 @@ -33,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 @@ -77,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; ``` @@ -89,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(...); ``` @@ -119,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(); ``` @@ -135,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(); ``` @@ -151,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; ``` @@ -159,7 +160,7 @@ typedef CSimpleStringT::PCXSTR PCXSTR; A pointer to a string. -``` +```cpp typedef CSimpleStringT::PXSTR PXSTR; ``` @@ -167,7 +168,7 @@ typedef CSimpleStringT::PXSTR PXSTR; Set the length of the string object at `GetBuffer` time. -``` +```cpp static const DWORD SET_LENGTH = 0x02; ``` @@ -201,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 2aea7d71a2..2755f5e8ab 100644 --- a/docs/atl-mfc-shared/reference/cstringdata-class.md +++ b/docs/atl-mfc-shared/reference/cstringdata-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CStringData Class" title: "CStringData Class" ms.date: "11/04/2016" f1_keywords: ["CStringData", "ATLSIMPSTR/ATL::CStringData", "ATLSIMPSTR/ATL::AddRef", "ATLSIMPSTR/ATL::data", "ATLSIMPSTR/ATL::IsLocked", "ATLSIMPSTR/ATL::IsShared", "ATLSIMPSTR/ATL::Lock", "ATLSIMPSTR/ATL::Release", "ATLSIMPSTR/ATL::Unlock", "ATLSIMPSTR/ATL::nAllocLength", "ATLSIMPSTR/ATL::nDataLength", "ATLSIMPSTR/ATL::nRefs", "ATLSIMPSTR/ATL::pStringMgr"] @@ -11,7 +12,7 @@ This class represents the data of a string object. ## Syntax -``` +```cpp struct CStringData ``` @@ -19,7 +20,7 @@ struct CStringData ### Methods -||| +|Name|Description| |-|-| |[AddRef](#addref)|Increments the reference count of the string data object.| |[data](#data)|Retrieves the character data of a string object.| @@ -31,7 +32,7 @@ struct CStringData ### Data Members -||| +|Name|Description| |-|-| |[nAllocLength](#nalloclength)|Length of allocated data in `XCHAR`s (not including terminating null)| |[nDataLength](#ndatalength)|Length of currently used data in `XCHAR`s (not including terminating null)| @@ -104,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(); ``` @@ -120,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(); ``` @@ -151,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; ``` @@ -163,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; ``` @@ -175,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; ``` @@ -187,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 0965d5a993..a47c9ad9a6 100644 --- a/docs/atl-mfc-shared/reference/cstringt-class.md +++ b/docs/atl-mfc-shared/reference/cstringt-class.md @@ -1,17 +1,17 @@ --- -title: "CStringT Class" -ms.date: "03/27/2019" -f1_keywords: ["CStringT", "ATLSTR/ATL::CStringT", "ATLSTR/ATL::CStringT::CStringT", "ATLSTR/ATL::CStringT::AllocSysString", "ATLSTR/ATL::CStringT::AnsiToOem", "ATLSTR/ATL::CStringT::AppendFormat", "ATLSTR/ATL::CStringT::Collate", "ATLSTR/ATL::CStringT::CollateNoCase", "ATLSTR/ATL::CStringT::Compare", "ATLSTR/ATL::CStringT::CompareNoCase", "ATLSTR/ATL::CStringT::Delete", "ATLSTR/ATL::CStringT::Find", "ATLSTR/ATL::CStringT::FindOneOf", "ATLSTR/ATL::CStringT::Format", "ATLSTR/ATL::CStringT::FormatMessage", "ATLSTR/ATL::CStringT::FormatMessageV", "ATLSTR/ATL::CStringT::FormatV", "ATLSTR/ATL::CStringT::GetEnvironmentVariable", "ATLSTR/ATL::CStringT::Insert", "ATLSTR/ATL::CStringT::Left", "ATLSTR/ATL::CStringT::LoadString", "ATLSTR/ATL::CStringT::MakeLower", "ATLSTR/ATL::CStringT::MakeReverse", "ATLSTR/ATL::CStringT::MakeUpper", "ATLSTR/ATL::CStringT::Mid", "ATLSTR/ATL::CStringT::OemToAnsi", "ATLSTR/ATL::CStringT::Remove", "ATLSTR/ATL::CStringT::Replace", "ATLSTR/ATL::CStringT::ReverseFind", "ATLSTR/ATL::CStringT::Right", "ATLSTR/ATL::CStringT::SetSysString", "ATLSTR/ATL::CStringT::SpanExcluding", "ATLSTR/ATL::CStringT::SpanIncluding", "ATLSTR/ATL::CStringT::Tokenize", "ATLSTR/ATL::CStringT::Trim", "ATLSTR/ATL::CStringT::TrimLeft", "ATLSTR/ATL::CStringT::TrimRight", "CSTRINGT/CStringT", "CSTRINGT/CStringT::CStringT", "CSTRINGT/CStringT::AllocSysString", "CSTRINGT/CStringT::AnsiToOem", "CSTRINGT/CStringT::AppendFormat", "CSTRINGT/CStringT::Collate", "CSTRINGT/CStringT::CollateNoCase", "CSTRINGT/CStringT::Compare", "CSTRINGT/CStringT::CompareNoCase", "CSTRINGT/CStringT::Delete", "CSTRINGT/CStringT::Find", "CSTRINGT/CStringT::FindOneOf", "CSTRINGT/CStringT::Format", "CSTRINGT/CStringT::FormatMessage", "CSTRINGT/CStringT::FormatMessageV", "CSTRINGT/CStringT::FormatV", "CSTRINGT/CStringT::GetEnvironmentVariable", "CSTRINGT/CStringT::Insert", "CSTRINGT/CStringT::Left", "CSTRINGT/CStringT::LoadString", "CSTRINGT/CStringT::MakeLower", "CSTRINGT/CStringT::MakeReverse", "CSTRINGT/CStringT::MakeUpper", "CSTRINGT/CStringT::Mid", "CSTRINGT/CStringT::OemToAnsi", "CSTRINGT/CStringT::Remove", "CSTRINGT/CStringT::Replace", "CSTRINGT/CStringT::ReverseFind", "CSTRINGT/CStringT::Right", "CSTRINGT/CStringT::SetSysString", "CSTRINGT/CStringT::SpanExcluding", "CSTRINGT/CStringT::SpanIncluding", "CSTRINGT/CStringT::Tokenize", "CSTRINGT/CStringT::Trim", "CSTRINGT/CStringT::TrimLeft", "CSTRINGT/CStringT::TrimRight"] +title: "**`CStringT`** Class" +description: "API reference for the Microsoft ATL **`CStringT`** class" +ms.date: 12/06/2020 +f1_keywords: ["CStringT", "CSTRINGT/ATL::CStringT", "CSTRINGT/ATL::CStringT::CStringT", "CSTRINGT/ATL::CStringT::AllocSysString", "CSTRINGT/ATL::CStringT::AnsiToOem", "CSTRINGT/ATL::CStringT::AppendFormat", "CSTRINGT/ATL::CStringT::Collate", "CSTRINGT/ATL::CStringT::CollateNoCase", "CSTRINGT/ATL::CStringT::Compare", "CSTRINGT/ATL::CStringT::CompareNoCase", "CSTRINGT/ATL::CStringT::Delete", "CSTRINGT/ATL::CStringT::Find", "CSTRINGT/ATL::CStringT::FindOneOf", "CSTRINGT/ATL::CStringT::Format", "CSTRINGT/ATL::CStringT::FormatMessage", "CSTRINGT/ATL::CStringT::FormatMessageV", "CSTRINGT/ATL::CStringT::FormatV", "CSTRINGT/ATL::CStringT::GetEnvironmentVariable", "CSTRINGT/ATL::CStringT::Insert", "CSTRINGT/ATL::CStringT::Left", "CSTRINGT/ATL::CStringT::LoadString", "CSTRINGT/ATL::CStringT::MakeLower", "CSTRINGT/ATL::CStringT::MakeReverse", "CSTRINGT/ATL::CStringT::MakeUpper", "CSTRINGT/ATL::CStringT::Mid", "CSTRINGT/ATL::CStringT::OemToAnsi", "CSTRINGT/ATL::CStringT::Remove", "CSTRINGT/ATL::CStringT::Replace", "CSTRINGT/ATL::CStringT::ReverseFind", "CSTRINGT/ATL::CStringT::Right", "CSTRINGT/ATL::CStringT::SetSysString", "CSTRINGT/ATL::CStringT::SpanExcluding", "CSTRINGT/ATL::CStringT::SpanIncluding", "CSTRINGT/ATL::CStringT::Tokenize", "CSTRINGT/ATL::CStringT::Trim", "CSTRINGT/ATL::CStringT::TrimLeft", "CSTRINGT/ATL::CStringT::TrimRight"] helpviewer_keywords: ["strings [C++], in ATL", "shared classes, CStringT", "CStringT class"] -ms.assetid: 7cacc59c-425f-40f1-8f5b-6db921318ec9 --- -# CStringT Class +# `CStringT` Class -This class represents a `CStringT` object. +This class represents a **`CStringT`** object. ## Syntax -``` +```cpp template class CStringT : public CSimpleStringT +*`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). -*StringTraits*
+*`StringTraits`*\ Determines if the string class needs C Run-Time (CRT) Library support and where string resources are located. Can be one of the following: -- **StrTraitATL< wchar_t** | **`char`** | **TCHAR, ChTraitsCRT< wchar_t** | **`char`** | **TCHAR > >** +- **`StrTraitATL>`** The class requires CRT support and searches for resource strings in the module specified by `m_hInstResource` (a member of the application's module class). -- **StrTraitATL< wchar_t** | **`char`** | **TCHAR, ChTraitsOS< wchar_t** | **`char`** | **TCHAR > >** +- **`StrTraitATL>`** - The class does not require CRT support and searches for resource strings in the module specified by `m_hInstResource` (a member of the application's module class). + The class doesn't require CRT support and searches for resource strings in the module specified by `m_hInstResource` (a member of the application's module class). -- **StrTraitMFC< wchar_t** | **`char`** | **TCHAR, ChTraitsCRT< wchar_t** | **`char`** | **TCHAR > >** +- **`StrTraitMFC>`** The class requires CRT support and searches for resource strings using the standard MFC search algorithm. -- **StrTraitMFC< wchar_t** | **`char`** | **TCHAR, ChTraitsOS< wchar_t** | **`char`** | **TCHAR > >** +- **`StrTraitMFC>`** - The class does not require CRT support and searches for resource strings using the standard MFC search algorithm. + The class doesn't require CRT support and searches for resource strings using the standard MFC search algorithm. ## Members @@ -54,79 +54,79 @@ Determines if the string class needs C Run-Time (CRT) Library support and where |Name|Description| |----------|-----------------| -|[CStringT::CStringT](#cstringt)|Constructs a `CStringT` object in various ways.| -|[CStringT::~CStringT](#_dtorcstringt)|Destroys a `CStringT` object.| +|[`CStringT::CStringT`](#cstringt)|Constructs a **`CStringT`** object in various ways.| +|[`CStringT::~CStringT`](#_dtorcstringt)|Destroys a **`CStringT`** object.| ### Public Methods |Name|Description| |----------|-----------------| -|[CStringT::AllocSysString](#allocsysstring)|Allocates a BSTR from `CStringT` data.| -|[CStringT::AnsiToOem](#ansitooem)|Makes an in-place conversion from the ANSI character set to the OEM character set.| -|[CStringT::AppendFormat](#appendformat)|Appends formatted data to an existing `CStringT` object.| -|[CStringT::Collate](#collate)|Compares two strings (case sensitive, uses locale-specific information).| -|[CStringT::CollateNoCase](#collatenocase)|Compares two strings (case insensitive, uses locale-specific information).| -|[CStringT::Compare](#compare)|Compares two strings (case sensitive).| -|[CStringT::CompareNoCase](#comparenocase)|Compares two strings (case insensitive).| -|[CStringT::Delete](#delete)|Deletes a character or characters from a string.| -|[CStringT::Find](#find)|Finds a character or substring inside a larger string.| -|[CStringT::FindOneOf](#findoneof)|Finds the first matching character from a set.| -|[CStringT::Format](#format)|Formats the string as `sprintf` does.| -|[CStringT::FormatMessage](#formatmessage)|Formats a message string.| -|[CStringT::FormatMessageV](#formatmessagev)|Formats a message string using a variable argument list.| -|[CStringT::FormatV](#formatv)|Formats the string using a variable list of arguments.| -|[CStringT::GetEnvironmentVariable](#getenvironmentvariable)|Sets the string to the value of the specified environment variable.| -|[CStringT::Insert](#insert)|Inserts a single character or a substring at the given index within the string.| -|[CStringT::Left](#left)|Extracts the left part of a string.| -|[CStringT::LoadString](#loadstring)|Loads an existing `CStringT` object from a Windows resource.| -|[CStringT::MakeLower](#makelower)|Converts all the characters in this string to lowercase characters.| -|[CStringT::MakeReverse](#makereverse)|Reverses the string.| -|[CStringT::MakeUpper](#makeupper)|Converts all the characters in this string to uppercase characters.| -|[CStringT::Mid](#mid)|Extracts the middle part of a string.| -|[CStringT::OemToAnsi](#oemtoansi)|Makes an in-place conversion from the OEM character set to the ANSI character set.| -|[CStringT::Remove](#remove)|Removes indicated characters from a string.| -|[CStringT::Replace](#replace)|Replaces indicated characters with other characters.| -|[CStringT::ReverseFind](#reversefind)|Finds a character inside a larger string; starts from the end.| -|[CStringT::Right](#right)|Extracts the right part of a string.| -|[CStringT::SetSysString](#setsysstring)|Sets an existing BSTR object with data from a `CStringT` object.| -|[CStringT::SpanExcluding](#spanexcluding)|Extracts characters from the string, starting with the first character, that are not in the set of characters identified by `pszCharSet`.| -|[CStringT::SpanIncluding](#spanincluding)|Extracts a substring that contains only the characters in a set.| -|[CStringT::Tokenize](#tokenize)|Extracts specified tokens in a target string.| -|[CStringT::Trim](#trim)|Trims all leading and trailing whitespace characters from the string.| -|[CStringT::TrimLeft](#trimleft)|Trims leading whitespace characters from the string.| -|[CStringT::TrimRight](#trimright)|Trims trailing whitespace characters from the string.| +|[`CStringT::AllocSysString`](#allocsysstring)|Allocates a `BSTR` from **`CStringT`** data.| +|[`CStringT::AnsiToOem`](#ansitooem)|Makes an in-place conversion from the ANSI character set to the OEM character set.| +|[`CStringT::AppendFormat`](#appendformat)|Appends formatted data to an existing **`CStringT`** object.| +|[`CStringT::Collate`](#collate)|Compares two strings (case-sensitive, uses locale-specific information).| +|[`CStringT::CollateNoCase`](#collatenocase)|Compares two strings (case-insensitive, uses locale-specific information).| +|[`CStringT::Compare`](#compare)|Compares two strings (case-sensitive).| +|[`CStringT::CompareNoCase`](#comparenocase)|Compares two strings (case-insensitive).| +|[`CStringT::Delete`](#delete)|Deletes a character or characters from a string.| +|[`CStringT::Find`](#find)|Finds a character or substring inside a larger string.| +|[`CStringT::FindOneOf`](#findoneof)|Finds the first matching character from a set.| +|[`CStringT::Format`](#format)|Formats the string as `sprintf` does.| +|[`CStringT::FormatMessage`](#formatmessage)|Formats a message string.| +|[`CStringT::FormatMessageV`](#formatmessagev)|Formats a message string using a variable argument list.| +|[`CStringT::FormatV`](#formatv)|Formats the string using a variable list of arguments.| +|[`CStringT::GetEnvironmentVariable`](#getenvironmentvariable)|Sets the string to the value of the specified environment variable.| +|[`CStringT::Insert`](#insert)|Inserts a single character or a substring at the given index within the string.| +|[`CStringT::Left`](#left)|Extracts the left part of a string.| +|[`CStringT::LoadString`](#loadstring)|Loads an existing **`CStringT`** object from a Windows resource.| +|[`CStringT::MakeLower`](#makelower)|Converts all the characters in this string to lowercase characters.| +|[`CStringT::MakeReverse`](#makereverse)|Reverses the string.| +|[`CStringT::MakeUpper`](#makeupper)|Converts all the characters in this string to uppercase characters.| +|[`CStringT::Mid`](#mid)|Extracts the middle part of a string.| +|[`CStringT::OemToAnsi`](#oemtoansi)|Makes an in-place conversion from the OEM character set to the ANSI character set.| +|[`CStringT::Remove`](#remove)|Removes indicated characters from a string.| +|[`CStringT::Replace`](#replace)|Replaces indicated characters with other characters.| +|[`CStringT::ReverseFind`](#reversefind)|Finds a character inside a larger string; starts from the end.| +|[`CStringT::Right`](#right)|Extracts the right part of a string.| +|[`CStringT::SetSysString`](#setsysstring)|Sets an existing `BSTR` object with data from a **`CStringT`** object.| +|[`CStringT::SpanExcluding`](#spanexcluding)|Extracts characters from the string, starting with the first character, that aren't in the set of characters identified by `pszCharSet`.| +|[`CStringT::SpanIncluding`](#spanincluding)|Extracts a substring that contains only the characters in a set.| +|[`CStringT::Tokenize`](#tokenize)|Extracts specified tokens in a target string.| +|[`CStringT::Trim`](#trim)|Trims all leading and trailing whitespace characters from the string.| +|[`CStringT::TrimLeft`](#trimleft)|Trims leading whitespace characters from the string.| +|[`CStringT::TrimRight`](#trimright)|Trims trailing whitespace characters from the string.| ### Operators -||| +|Name|Description| |-|-| -|[CStringT::operator =](#operator_eq)|Assigns a new value to a `CStringT` object.| -|[CStringT::operator +](#operator_add)|Concatenates two strings or a character and a string.| -|[CStringT::operator +=](#operator_add_eq)|Concatenates a new string to the end of an existing string.| -|[CStringT::operator ==](#operator_eq_eq)|Determines if two strings are logically equal.| -|[CStringT::operator !=](#operator_neq)|Determines if two strings are logically not equal.| -|[CStringT::operator <](#operator_lt)|Determines if the string on the left side of the operator is less than to the string on the right side.| -|[CStringT::operator >](#operator_gt)|Determines if the string on the left side of the operator is greater than to the string on the right side.| -|[CStringT::operator <=](#operator_lt_eq)|Determines if the string on the left side of the operator is less than or equal to the string on the right side.| -|[CStringT::operator >=](#operator_gt_eq)|Determines if the string on the left side of the operator is greater than or equal to the string on the right side.| +|[`CStringT::operator =`](#operator_eq)|Assigns a new value to a **`CStringT`** object.| +|[`CStringT::operator +`](#operator_add)|Concatenates two strings, or a character and a string.| +|[`CStringT::operator +=`](#operator_add_eq)|Concatenates a new string to the end of an existing string.| +|[`CStringT::operator ==`](#operator_eq_eq)|Determines if two strings are logically equal.| +|[`CStringT::operator !=`](#operator_neq)|Determines if two strings aren't logically equal.| +|[`CStringT::operator <`](#operator_lt)|Determines if the string on the left side of the operator is less than to the string on the right side.| +|[`CStringT::operator >`](#operator_gt)|Determines if the string on the left side of the operator is greater than to the string on the right side.| +|[`CStringT::operator <=`](#operator_lt_eq)|Determines if the string on the left side of the operator is less than or equal to the string on the right side.| +|[`CStringT::operator >=`](#operator_gt_eq)|Determines if the string on the left side of the operator is greater than or equal to the string on the right side.| ## 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. +> **`CStringT`** objects are capable of throwing exceptions. This occurs when a **`CStringT`** object runs out of memory for any reason. -A `CStringT` object consists of a variable-length sequence of characters. `CStringT` provides functions and operators using syntax similar to that of Basic. Concatenation and comparison operators, together with simplified memory management, make `CStringT` objects easier to use than ordinary character arrays. +A **`CStringT`** object consists of a variable-length sequence of characters. **`CStringT`** provides functions and operators using syntax similar to that of Basic. Concatenation and comparison operators, together with simplified memory management, make **`CStringT`** objects easier to use than ordinary character arrays. > [!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. +> 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. -By using different combinations of the `BaseType` and `StringTraits` parameters, `CStringT` objects can come in the following types, which are have been predefined by the ATL libraries. +By using different combinations of the `BaseType` and `StringTraits` parameters, **`CStringT`** objects can come in the following types, which have been predefined by the ATL libraries. If using in an ATL application: -`CString`, `CStringA`, and `CStringW` are exported from the MFC DLL (MFC90.DLL), never from user DLLs. This is done to prevent `CStringT` from being multiply defined. +`CString`, `CStringA`, and `CStringW` are exported from the MFC DLL (MFC90.DLL), never from user DLLs. This is done to prevent **`CStringT`** from being defined multiple times. > [!NOTE] > If your code contains the workaround for linker errors that is described in [Exporting String Classes Using CStringT](../../atl-mfc-shared/exporting-string-classes-using-cstringt.md), you should remove that code. It is no longer needed. @@ -139,7 +139,7 @@ The following string types are available within MFC-based applications: |`CStringW`|A Unicode character type string with CRT support.| |`CString`|Both ANSI and Unicode character types with CRT support.| -The following string types are available in projects where ATL_CSTRING_NO_CRT is defined: +The following string types are available in projects where `ATL_CSTRING_NO_CRT` is defined: |CStringT type|Declaration| |-------------------|-----------------| @@ -147,7 +147,7 @@ The following string types are available in projects where ATL_CSTRING_NO_CRT is |`CAtlStringW`|A Unicode character type string without CRT support.| |`CAtlString`|Both ANSI and Unicode character types without CRT support.| -The following string types are available in projects where ATL_CSTRING_NO_CRT is not defined: +The following string types are available in projects where `ATL_CSTRING_NO_CRT` isn't defined: |CStringT type|Declaration| |-------------------|-----------------| @@ -157,48 +157,48 @@ The following string types are available in projects where ATL_CSTRING_NO_CRT is `CString` objects also have the following characteristics: -- `CStringT` objects can grow as a result of concatenation operations. +- **`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. +- 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| |----------|-----------------| -|`XCHAR`|A single character (either **`wchar_t`** or **`char`**) with the same character type as the `CStringT` object.| -|`YCHAR`|A single character (either **`wchar_t`** or **`char`**) with the opposite character type as the `CStringT` object.| -|`PXSTR`|A pointer to a character string (either **`wchar_t`** or **`char`**) with the same character type as the `CStringT` object.| -|`PYSTR`|A pointer to a character string (either **`wchar_t`** or **`char`**) with the opposite character type as the `CStringT` object.| -|`PCXSTR`|A pointer to a **`const`** character string (either **`wchar_t`** or **`char`**) with the same character type as the `CStringT` object.| -|`PCYSTR`|A pointer to a **`const`** character string (either **`wchar_t`** or **`char`**) with the opposite character type as the `CStringT` object.| +|`XCHAR`|A single character (either **`wchar_t`** or **`char`**) with the same character type as the **`CStringT`** object.| +|`YCHAR`|A single character (either **`wchar_t`** or **`char`**) with the opposite character type as the **`CStringT`** object.| +|`PXSTR`|A pointer to a character string (either **`wchar_t`** or **`char`**) with the same character type as the ****`CStringT`**** object.| +|`PYSTR`|A pointer to a character string (either **`wchar_t`** or **`char`**) with the opposite character type as the **`CStringT`** object.| +|`PCXSTR`|A pointer to a **`const`** character string (either **`wchar_t`** or **`char`**) with the same character type as the **`CStringT`** object.| +|`PCYSTR`|A pointer to a **`const`** character string (either **`wchar_t`** or **`char`**) with the opposite character type as the **`CStringT`** object.| > [!NOTE] -> Code that previously used undocumented methods of `CString` (such as `AssignCopy`) must be replaced with code that uses the following documented methods of `CStringT` (such as `GetBuffer` or `ReleaseBuffer`). These methods are inherited from `CSimpleStringT`. +> Code that previously used undocumented methods of `CString` (such as `AssignCopy`) must be replaced with code that uses the following documented methods of **`CStringT`** (such as `GetBuffer` or `ReleaseBuffer`). These methods are inherited from `CSimpleStringT`. ## Inheritance Hierarchy -[CSimpleStringT](../../atl-mfc-shared/reference/csimplestringt-class.md) +[`CSimpleStringT`](../../atl-mfc-shared/reference/csimplestringt-class.md) -`CStringT` +**`CStringT`** ## Requirements |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 +## `CStringT::AllocSysString` -Allocates an Automation-compatible string of the type BSTR and copies the contents of the `CStringT` object into it, including the terminating null character. +Allocates an Automation-compatible string of the type `BSTR` and copies the contents of the **`CStringT`** object into it, including the terminating null character. -``` +```cpp BSTR AllocSysString() const; ``` @@ -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 @@ -220,9 +220,9 @@ The following example demonstrates the use of `CStringT::AllocSysString`. [!code-cpp[NVC_ATLMFC_Utilities#105](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_1.cpp)] -## CStringT::AnsiToOem +## `CStringT::AnsiToOem` -Converts all the characters in this `CStringT` object from the ANSI character set to the OEM character set. +Converts all the characters in this **`CStringT`** object from the ANSI character set to the OEM character set. ```cpp void AnsiToOem(); @@ -230,15 +230,15 @@ void AnsiToOem(); ### Remarks -The function is not available if _UNICODE is defined. +The function isn't available if `_UNICODE` is defined. ### Example [!code-cpp[NVC_ATLMFC_Utilities#106](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_2.cpp)] -## CStringT::AppendFormat +## `CStringT::AppendFormat` -Appends formatted data to an existing `CStringT` object. +Appends formatted data to an existing **`CStringT`** object. ```cpp void __cdecl AppendFormat(PCXSTR pszFormat, [, argument] ...); @@ -247,89 +247,89 @@ void __cdecl AppendFormat(UINT nFormatID, [, argument] ...); ### Parameters -*pszFormat*
+*`pszFormat`*\ A format-control string. -*nFormatID*
+*`nFormatID`*\ The string resource identifier that contains the format-control string. -*argument*
+*`argument`*\ Optional arguments. ### Remarks -This function formats and appends a series of characters and values in the `CStringT`. Each optional argument (if any) is converted and appended according to the corresponding format specification in *pszFormat* or from the string resource identified by *nFormatID*. +This function formats and appends a series of characters and values in the **`CStringT`**. Each optional argument (if any) is converted and appended according to the corresponding format specification in *`pszFormat`* or from the string resource identified by *`nFormatID`*. ### Example [!code-cpp[NVC_ATLMFC_Utilities#107](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_3.cpp)] -## CStringT::Collate +## `CStringT::Collate` Compares two strings using the generic-text function `_tcscoll`. -``` +```cpp int Collate(PCXSTR psz) const throw(); ``` ### Parameters -*psz*
+*`psz`*\ The other string used for comparison. ### Return Value -Zero if the strings are identical, < 0 if this `CStringT` object is less than *psz*, or > 0 if this `CStringT` object is greater than *psz*. +Zero if the strings are identical, < 0 if this **`CStringT`** object is less than *`psz`*, or > 0 if this **`CStringT`** object is greater than *`psz`*. ### 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 performs 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 +## `CStringT::CollateNoCase` Compares two strings using the generic-text function `_tcscoll`. -``` +```cpp int CollateNoCase(PCXSTR psz) const throw(); ``` ### Parameters -*psz*
+*`psz`*\ The other string used for comparison. ### Return Value -Zero if the strings are identical (ignoring case), < 0 if this `CStringT` object is less than *psz* (ignoring case), or > 0 if this `CStringT` object is greater than *psz* (ignoring case). +Zero if the strings are identical (ignoring case), < 0 if this **`CStringT`** object is less than *`psz`* (ignoring case), or > 0 if this **`CStringT`** object is greater than *`psz`* (ignoring case). ### 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 performs 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 [!code-cpp[NVC_ATLMFC_Utilities#109](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_4.cpp)] -## CStringT::Compare +## `CStringT::Compare` -Compares two strings (case sensitive). +Compares two strings (case-sensitive). -``` +```cpp int Compare(PCXSTR psz) const; ``` ### Parameters -*psz*
+*`psz`*\ The other string used for comparison. ### Return Value -Zero if the strings are identical, < 0 if this `CStringT` object is less than *psz*, or > 0 if this `CStringT` object is greater than *psz*. +Zero if the strings are identical, < 0 if this **`CStringT`** object is less than *`psz`*, or > 0 if this **`CStringT`** object is greater than *`psz`*. ### 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 performs a case-sensitive comparison of the strings and is not 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. @@ -339,36 +339,36 @@ The following example demonstrates the use of `CStringT::Compare`. [!code-cpp[NVC_ATLMFC_Utilities#110](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_5.cpp)] -## CStringT::CompareNoCase +## `CStringT::CompareNoCase` -Compares two strings (case insensitive). +Compares two strings (case-insensitive). -``` +```cpp int CompareNoCase(PCXSTR psz) const throw(); ``` ### Parameters -*psz*
+*`psz`*\ The other string used for comparison. ### Return Value -Zero if the strings are identical (ignoring case), <0 if this `CStringT` object is less than *psz* (ignoring case), or >0 if this `CStringT` object is greater than *psz* (ignoring case). +Zero if the strings are identical (ignoring case), <0 if this **`CStringT`** object is less than *`psz`* (ignoring case), or >0 if this **`CStringT`** object is greater than *`psz`* (ignoring case). ### 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 performs 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 [!code-cpp[NVC_ATLMFC_Utilities#111](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_6.cpp)] -## CStringT::CStringT +## `CStringT::CStringT` -Constructs a `CStringT` object. +Constructs a **`CStringT`** object. -``` +```cpp CStringT() throw() : CThisSimpleString(StringTraits::GetDefaultManager()); @@ -443,95 +443,95 @@ CStringT(const YCHAR* pch, int nLength, IAtlStringMgr* pStringMgr) : ### Parameters -*pch*
-A pointer to an array of characters of length *nLength*, not null-terminated. +*`pch`*\ +A pointer to an array of characters of length *`nLength`*, not null-terminated. -*nLength*
-A count of the number of characters in *pch*. +*`nLength`*\ +A count of the number of characters in *`pch`*. -*ch*
+*`ch`*\ A single character. -*pszSrc*
-A null-terminated string to be copied into this `CStringT` object. +*`pszSrc`*\ +A null-terminated string to be copied into this **`CStringT`** object. -*pStringMgr*
-A pointer to the memory manager for the `CStringT` object. For more information on `IAtlStringMgr` and memory management for `CStringT`, see [Memory Management with CStringT](../../atl-mfc-shared/memory-management-with-cstringt.md). +*`pStringMgr`*\ +A pointer to the memory manager for the **`CStringT`** object. For more information on `IAtlStringMgr` and memory management for **`CStringT`**, see [Memory Management with CStringT](../../atl-mfc-shared/memory-management-with-cstringt.md). -*strSrc*
-An existing `CStringT` object to be copied into this `CStringT` object. For more information on `CThisString` and `CThisSimpleString`, see the Remarks section. +*`strSrc`*\ +An existing **`CStringT`** object to be copied into this **`CStringT`** object. For more information on `CThisString` and `CThisSimpleString`, see the Remarks section. -*varSrc*
-A variant object to be copied into this `CStringT` object. +*`varSrc`*\ +A variant object to be copied into this **`CStringT`** object. -*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). -*bMFCDLL*
-Boolean that specifies whether the project is an MFC DLL (TRUE) or not (FALSE). +*`bMFCDLL`*\ +Boolean that specifies whether the project is an MFC DLL (`TRUE`) or not (`FALSE`). -*SystemString*
-Must be `System::String`, and the project must be compiled with /clr. +*`SystemString`*\ +Must be `System::String`, and the project must be compiled with `/clr`. -*pString*
-A handle for a `CStringT` object. +*`pString`*\ +A handle for a **`CStringT`** object. ### Remarks -Because the constructors copy the input data into new allocated storage, you should be aware that memory exceptions may result. Note that some of these constructors act as conversion functions. This allows you to substitute, for example, an LPTSTR where a `CStringT` object is expected. +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. +> 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. -Note that 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. +The overload operator `CSimpleStringT<>&()` constructs a **`CStringT`** object from a `CSimpleStringT` declaration. > [!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. +> 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. ### Example [!code-cpp[NVC_ATLMFC_Utilities#112](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_7.cpp)] -## CStringT::~CStringT +## `CStringT::~CStringT` -Destroys the `CStringT` object. +Destroys the **`CStringT`** object. -``` +```cpp ~CStringT() throw(); ``` ### Remarks -Destroys the `CStringT` object. +Destroys the **`CStringT`** object. -## CStringT::Delete +## `CStringT::Delete` Deletes a character or characters from a string starting with the character at the given index. -``` +```cpp int Delete(int iIndex, int nCount = 1); ``` ### Parameters -*iIndex*
-The zero-based index of the first character in the `CStringT` object to delete. +*`iIndex`*\ +The zero-based index of the first character in the **`CStringT`** object to delete. -*nCount*
+*`nCount`*\ The number of characters to be removed. ### Return Value @@ -540,7 +540,7 @@ The length of the changed string. ### Remarks -If *nCount* is longer than the string, the rest of the string will be removed. +If *`nCount`* is longer than the string, the rest of the string will be removed. ### Example @@ -553,29 +553,29 @@ After: Soccer best, but hockey is quicker! ``` -## CStringT::Find +## `CStringT::Find` Searches this string for the first match of a character or substring. -``` +```cpp int Find(PCXSTR pszSub, int iStart=0) const throw(); int Find(XCHAR ch, int iStart=0) const throw(); ``` ### Parameters -*pszSub*
+*`pszSub`*\ A substring to search for. -*iStart*
+*`iStart`*\ The index of the character in the string to begin the search with, or 0 to start from the beginning. -*ch*
+*`ch`*\ A single character to search for. ### Return Value -The zero-based index of the first character in this `CStringT` object that matches the requested substring or characters; -1 if the substring or character is not found. +The zero-based index of the first character in this **`CStringT`** object that matches the requested substring or characters; -1 if the substring or character isn't found. ### Remarks @@ -585,34 +585,34 @@ The function is overloaded to accept both single characters (similar to the run- [!code-cpp[NVC_ATLMFC_Utilities#114](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_9.cpp)] -## CStringT::FindOneOf +## `CStringT::FindOneOf` -Searches this string for the first character that matches any character contained in *pszCharSet*. +Searches this string for the first character that matches any character contained in *`pszCharSet`*. -``` +```cpp int FindOneOf(PCXSTR pszCharSet) const throw(); ``` ### Parameters -*pszCharSet*
+*`pszCharSet`*\ String containing characters for matching. ### Return Value -The zero-based index of the first character in this string that is also in *pszCharSet*; -1 if there is no match. +The zero-based index of the first character in this string that is also in *`pszCharSet`*; -1 if there is no match. ### Remarks -Finds the first occurrence of any of the characters in *pszCharSet*. +Finds the first occurrence of any of the characters in *`pszCharSet`*. ### Example [!code-cpp[NVC_ATLMFC_Utilities#115](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_10.cpp)] -## CStringT::Format +## `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]...); @@ -621,30 +621,30 @@ void __cdecl Format(PCXSTR pszFormat, [, argument] ...); ### Parameters -*nFormatID*
+*`nFormatID`*\ The string resource identifier that contains the format-control string. -*pszFormat*
+*`pszFormat`*\ A format-control string. -*argument*
+*`argument`*\ Optional arguments. ### Remarks -This function formats and stores a series of characters and values in the `CStringT`. Each optional argument (if any) is converted and output according to the corresponding format specification in *pszFormat* or from the string resource identified by *nFormatID*. +This function formats and stores a series of characters and values in the **`CStringT`**. Each optional argument (if any) is converted and output according to the corresponding format specification in *`pszFormat`* or from the string resource identified by *`nFormatID`*. The call will fail if the string object itself is offered as a parameter to `Format`. For example, the following code will cause unpredictable results: [!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 [!code-cpp[NVC_ATLMFC_Utilities#117](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_12.cpp)] -## CStringT::FormatMessage +## `CStringT::FormatMessage` Formats a message string. @@ -655,29 +655,29 @@ void __cdecl FormatMessage(PCXSTR pszFormat, [, argument]...); ### Parameters -*nFormatID*
+*`nFormatID`*\ 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. +*`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. -*argument*
+*`argument`*\ Optional arguments. ### Remarks -The function requires a message definition as input. The message definition is determined by *pszFormat* or from the string resource identified by *nFormatID*. The function copies the formatted message text to the `CStringT` object, processing any embedded insert sequences if requested. +The function requires a message definition as input. The message definition is determined by *`pszFormat`* or from the string resource identified by *`nFormatID`*. The function copies the formatted message text to the **`CStringT`** object, processing any embedded insert sequences if requested. > [!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 [!code-cpp[NVC_ATLMFC_Utilities#118](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_13.cpp)] -## CStringT::FormatMessageV +## `CStringT::FormatMessageV` Formats a message string using a variable argument list. @@ -687,22 +687,22 @@ void FormatMessageV(PCXSTR pszFormat, va_list* pArgList); ### Parameters -*pszFormat*
+*`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. -*pArgList*
+*`pArgList`*\ Pointer to a list of arguments. ### Remarks -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. +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 +## `CStringT::FormatV` Formats a message string using a variable argument list. @@ -712,33 +712,33 @@ void FormatV(PCXSTR pszFormat, va_list args); ### Parameters -*pszFormat*
+*`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. -*args*
+*`args`*\ Pointer to a list of arguments. ### Remarks -Writes a formatted string and a variable list of arguments to a `CStringT` string in the same way that `vsprintf_s` formats data into a C-style character array. +Writes a formatted string and a variable list of arguments to a **`CStringT`** string in the same way that `vsprintf_s` formats data into a C-style character array. ### 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 +## `CStringT::GetEnvironmentVariable` Sets the string to the value of the specified environment variable. -``` +```cpp BOOL GetEnvironmentVariable(PCXSTR pszVar); ``` ### Parameters -*pszVar*
+*`pszVar`*\ Pointer to a null-terminated string that specifies the environment variable. ### Return Value @@ -753,24 +753,24 @@ Retrieves the value of the specified variable from the environment block of the [!code-cpp[NVC_ATLMFC_Utilities#121](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_16.cpp)] -## CStringT::Insert +## `CStringT::Insert` Inserts a single character or a substring at the given index within the string. -``` +```cpp int Insert(int iIndex, PCXSTR psz); int Insert(int iIndex, XCHAR ch); ``` ### Parameters -*iIndex*
+*`iIndex`*\ The index of the character before which the insertion will take place. -*psz*
+*`psz`*\ A pointer to the substring to be inserted. -*ch*
+*`ch`*\ The character to be inserted. ### Return Value @@ -779,44 +779,44 @@ 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 [!code-cpp[NVC_ATLMFC_Utilities#122](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_17.cpp)] -## CStringT::Left +## `CStringT::Left` -Extracts the leftmost *nCount* characters from this `CStringT` object and returns a copy of the extracted substring. +Extracts the leftmost *`nCount`* characters from this **`CStringT`** object and returns a copy of the extracted substring. -``` +```cpp CStringT Left(int nCount) const; ``` ### Parameters -*nCount*
-The number of characters to extract from this `CStringT` object. +*`nCount`*\ +The number of characters to extract from this **`CStringT`** object. ### Return Value -A `CStringT` object that contains a copy of the specified range of characters. The returned `CStringT` object may be empty. +A **`CStringT`** object that contains a copy of the specified range of characters. The returned **`CStringT`** object may be empty. ### Remarks -If *nCount* exceeds the string length, then the entire string is extracted. `Left` is similar to the Basic `Left` function. +If *`nCount`* exceeds the string length, then the entire string is extracted. `Left` is similar to the Basic `Left` function. -For multi-byte character sets (MBCS), *nCount* treats each 8-bit sequence as a character, so that *nCount* returns the number of multi-byte characters multiplied by two. +For multi-byte character sets (MBCS), *`nCount`* treats each 8-bit sequence as a character, so that *`nCount`* returns the number of multi-byte characters multiplied by two. ### Example [!code-cpp[NVC_ATLMFC_Utilities#123](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_18.cpp)] -## CStringT::LoadString +## `CStringT::LoadString` -Reads a Windows string resource, identified by *nID*, into an existing `CStringT` object. +Reads a Windows string resource, identified by *nID*, into an existing **`CStringT`** object. -``` +```cpp BOOL LoadString(HINSTANCE hInstance, UINT nID, WORD wLanguageID); BOOL LoadString(HINSTANCE hInstance, UINT nID); BOOL LoadString(UINT nID); @@ -824,13 +824,13 @@ BOOL LoadString(UINT nID); ### Parameters -*hInstance*
+*`hInstance`*\ A handle to the instance of the module. -*nID*
+*`nID`*\ A Windows string resource ID. -*wLanguageID*
+*`wLanguageID`*\ The language of the string resource. ### Return Value @@ -839,17 +839,17 @@ 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 [!code-cpp[NVC_ATLMFC_Utilities#124](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_19.cpp)] -## CStringT::MakeLower +## `CStringT::MakeLower` -Converts the `CStringT` object to a lowercase string. +Converts the **`CStringT`** object to a lowercase string. -``` +```cpp CStringT& MakeLower(); ``` @@ -861,11 +861,11 @@ The resulting lowercase string. [!code-cpp[NVC_ATLMFC_Utilities#125](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_20.cpp)] -## CStringT::MakeReverse +## `CStringT::MakeReverse` -Reverses the order of the characters in the `CStringT` object. +Reverses the order of the characters in the **`CStringT`** object. -``` +```cpp CStringT& MakeReverse(); ``` @@ -877,11 +877,11 @@ The resulting reversed string. [!code-cpp[NVC_ATLMFC_Utilities#126](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_21.cpp)] -## CStringT::MakeUpper +## `CStringT::MakeUpper` -Converts the `CStringT` object to an uppercase string. +Converts the **`CStringT`** object to an uppercase string. -``` +```cpp CStringT& MakeUpper(); ``` @@ -895,63 +895,62 @@ The resulting uppercase string. [!code-cpp[NVC_ATLMFC_Utilities#127](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_22.cpp)] -## CStringT::Mid +## `CStringT::Mid` -Extracts a substring of length *nCount* characters from this `CStringT` object, starting at position *iFirst* (zero-based). +Extracts a substring of length *`nCount`* characters from this **`CStringT`** object, starting at position *`iFirst`* (zero-based). -``` +```cpp CStringT Mid(int iFirst, int nCount) const; CStringT Mid(int iFirst) const; ``` ### Parameters -*iFirst*
-The zero-based index of the first character in this `CStringT` object that is to be included in the extracted substring. +*`iFirst`*\ +The zero-based index of the first character in this **`CStringT`** object that is to be included in the extracted substring. -*nCount*
-The number of characters to extract from this `CStringT` object. If this parameter is not supplied, then the remainder of the string is extracted. +*`nCount`*\ +The number of characters to extract from this **`CStringT`** object. If this parameter isn't supplied, then the rest of the string is extracted. ### Return Value -A `CStringT` object that contains a copy of the specified range of characters. Note that the returned `CStringT` object may be empty. +A **`CStringT`** object that contains a copy of the specified range of characters. The returned **`CStringT`** object may be empty. ### Remarks The function returns a copy of the extracted substring. `Mid` is similar to the Basic Mid function (except that indexes in Basic are one-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 [!code-cpp[NVC_ATLMFC_Utilities#128](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_23.cpp)] -## CStringT::OemToAnsi +## `CStringT::OemToAnsi` -Converts all the characters in this `CStringT` object from the OEM character set to the ANSI character set. +Converts all the characters in this **`CStringT`** object from the OEM character set to the ANSI character set. -```cpp +```cppcpp void OemToAnsi(); ``` ### Remarks -This function is not available if _UNICODE is defined. +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 = +## `CStringT::operator =` Assigns a new value to the string. -``` +```cpp CStringT& operator=(const CStringT& strSrc); template CStringT& operator=(const CSimpleStringT& str); - CStringT& operator=(PCXSTR pszSrc); CStringT& operator=(PCYSTR pszSrc); CStringT& operator=(const unsigned char* pszSrc); @@ -962,86 +961,86 @@ CStringT& operator=(const VARIANT& var); ### Parameters -*strSrc*
-A `CStringT` to assign to this string. +*`strSrc`*\ +A **`CStringT`** to assign to this string. -*str*
+*`str`*\ A reference to a `CThisSimpleString` object. -*bMFCDLL*
+*`bMFCDLL`*\ A boolean specifying whether the project is an MFC DLL or not. -*BaseType*
+*`BaseType`*\ The string base type. -*var*
+*`var`*\ A variant object to assign to this string. -*ch*
+*`ch`*\ An ANSI or Unicode character to assign to the string. -*pszSrc*
+*`pszSrc`*\ A pointer to the original string being assigned. ### Remarks -The assignment operator accepts another `CStringT` object, a character pointer, or a single character. You should be aware that memory exceptions can occur whenever you use this operator because new storage can be allocated. +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. +> 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. -## CStringT::operator + +## `CStringT::operator +` 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 -*ch1*
+*`ch1`*\ An ANSI or Unicode character to concatenate with a string. -*ch2*
+*`ch2`*\ An ANSI or Unicode character to concatenate with a string. -*str1*
-A `CStringT` to concatenate with a string or character. +*`str1`*\ +A **`CStringT`** to concatenate with a string or character. -*str2*
-A `CStringT` to concatenate with a string or character. +*`str2`*\ +A **`CStringT`** to concatenate with a string or character. -*psz1*
+*`psz1`*\ A pointer to a null-terminated string to concatenate with a string or character. -*psz2*
+*`psz2`*\ A pointer to a string to concatenate with a string or character. ### Remarks -There are seven overload forms of the `CStringT::operator+` function. The first version concatenates two existing `CStringT` objects. The next two concatenate a `CStringT` object and a null-terminated string. The next two concatenate a `CStringT` object and an ANSI character. The last two concatenate a `CStringT` object and a Unicode character. +There are seven overload forms of the `CStringT::operator+` function. The first version concatenates two existing **`CStringT`** objects. The next two concatenate a **`CStringT`** object and a null-terminated string. The next two concatenate a **`CStringT`** object and an ANSI character. The last two concatenate a **`CStringT`** object and a Unicode character. > [!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. +> 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. ### Example [!code-cpp[NVC_ATLMFC_Utilities#140](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_24.cpp)] -## CStringT::operator += +## `CStringT::operator +=` Concatenates characters to the end of the string. -``` +```cpp CStringT& operator+=(const CThisSimpleString& str); template @@ -1059,129 +1058,129 @@ CStringT& operator+=(const VARIANT& var); ### Parameters -*str*
+*`str`*\ A reference to a `CThisSimpleString` object. -*bMFCDLL*
+*`bMFCDLL`*\ A boolean specifying whether the project is an MFC DLL or not. -*BaseType*
+*`BaseType`*\ The string base type. -*var*
+*`var`*\ A variant object to concatenate to this string. -*ch*
+*`ch`*\ An ANSI or Unicode character to concatenate with a string. -*pszSrc*
+*`pszSrc`*\ A pointer to the original string being concatenated. -*strSrc*
-A `CStringT` to concatenate to this string. +*`strSrc`*\ +A **`CStringT`** to concatenate to this string. ### Remarks -The operator accepts another `CStringT` object, a character pointer, or a single character. You should be aware that memory exceptions can occur whenever you use this concatenation operator because new storage can be allocated for characters added to this `CStringT` object. +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. +> 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. ### Example [!code-cpp[NVC_ATLMFC_Utilities#141](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_25.cpp)] -## CStringT::operator == +## `CStringT::operator ==` Determines whether two strings are logically equal. -``` +```cpp friend bool operator==(const CStringT& str1, const CStringT& str2) throw(); 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 -*ch1*
+*`ch1`*\ An ANSI or Unicode character for comparison. -*ch2*
+*`ch2`*\ An ANSI or Unicode character for comparison. -*str1*
-A `CStringT` for comparison. +*`str1`*\ +A **`CStringT`** for comparison. -*str2*
-A `CStringT` for comparison. +*`str2`*\ +A **`CStringT`** for comparison. -*psz1*
+*`psz1`*\ A pointer to a null-terminated string for comparison. -*psz2*
+*`psz2`*\ A pointer to a null-terminated string for comparison. ### Remarks -Tests whether a string or character on the left side is equal to a string or character on the right side, and returns TRUE or FALSE accordingly. +Tests whether a string or character on the left side is equal to a string or character on the right side, and returns `TRUE` or `FALSE` accordingly. ### Example [!code-cpp[NVC_ATLMFC_Utilities#142](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_26.cpp)] -## CStringT::operator != +## `CStringT::operator !=` Determines whether two strings are logically not equal. -``` +```cpp friend bool operator!=(const CStringT& str1, const CStringT& str2) throw(); 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 -*ch1*
+*`ch1`*\ An ANSI or Unicode character to concatenate with a string. -*ch2*
+*`ch2`*\ An ANSI or Unicode character to concatenate with a string. -*str1*
-A `CStringT` for comparison. +*`str1`*\ +A **`CStringT`** for comparison. -*str2*
-A `CStringT` for comparison. +*`str2`*\ +A **`CStringT`** for comparison. -*psz1*
+*`psz1`*\ A pointer to a null-terminated string for comparison. -*psz2*
+*`psz2`*\ A pointer to a null-terminated string for comparison. ### Remarks -Tests if a string or character on the left side is not equal to a string or character on the right side. +Tests if a string or character on the left side isn't equal to a string or character on the right side. ### Example [!code-cpp[NVC_ATLMFC_Utilities#143](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_27.cpp)] -## CStringT::operator < +## `CStringT::operator <` Determines whether the string on the left side of the operator is less than the string on the right side. -``` +```cpp friend bool operator<(const CStringT& str1, const CStringT& str2) throw(); friend bool operator<(const CStringT& str1, PCXSTR psz2) throw(); friend bool operator<(PCXSTR psz1, const CStringT& str2) throw(); @@ -1189,16 +1188,16 @@ friend bool operator<(PCXSTR psz1, const CStringT& str2) throw(); ### Parameters -*str1*
-A `CStringT` for comparison. +*`str1`*\ +A **`CStringT`** for comparison. -*str2*
-A `CStringT` for comparison. +*`str2`*\ +A **`CStringT`** for comparison. -*psz1*
+*`psz1`*\ A pointer to a null-terminated string for comparison. -*psz2*
+*`psz2`*\ A pointer to a null-terminated string for comparison. ### Remarks @@ -1215,11 +1214,11 @@ A lexicographical comparison between strings, character by character until: [!code-cpp[NVC_ATLMFC_Utilities#144](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_28.cpp)] -## CStringT::operator > +## `CStringT::operator >` Determines whether the string on the left side of the operator is greater than the string on the right side. -``` +```cpp friend bool operator>(const CStringT& str1, const CStringT& str2) throw(); friend bool operator>(const CStringT& str1, PCXSTR psz2) throw(); friend bool operator>(PCXSTR psz1, const CStringT& str2) throw(); @@ -1227,16 +1226,16 @@ friend bool operator>(PCXSTR psz1, const CStringT& str2) throw(); ### Parameters -*str1*
-A `CStringT` for comparison. +*`str1`*\ +A **`CStringT`** for comparison. -*str2*
-A `CStringT` for comparison. +*`str2`*\ +A **`CStringT`** for comparison. -*psz1*
+*`psz1`*\ A pointer to a null-terminated string for comparison. -*psz2*
+*`psz2`*\ A pointer to a null-terminated string for comparison. ### Remarks @@ -1253,11 +1252,11 @@ A lexicographical comparison between strings, character by character until: [!code-cpp[NVC_ATLMFC_Utilities#145](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_29.cpp)] -## CStringT::operator <= +## `CStringT::operator <=` Determines whether the string on the left side of the operator is less than or equal to the string on the right side. -``` +```cpp friend bool operator<=(const CStringT& str1, const CStringT& str2) throw(); friend bool operator<=(const CStringT& str1, PCXSTR psz2) throw(); friend bool operator<=(PCXSTR psz1, const CStringT& str2) throw(); @@ -1265,16 +1264,16 @@ friend bool operator<=(PCXSTR psz1, const CStringT& str2) throw(); ### Parameters -*str1*
-A `CStringT` for comparison. +*`str1`*\ +A **`CStringT`** for comparison. -*str2*
-A `CStringT` for comparison. +*`str2`*\ +A **`CStringT`** for comparison. -*psz1*
+*`psz1`*\ A pointer to a null-terminated string for comparison. -*psz2*
+*`psz2`*\ A pointer to a null-terminated string for comparison. ### Remarks @@ -1291,11 +1290,11 @@ A lexicographical comparison between strings, character by character until: [!code-cpp[NVC_ATLMFC_Utilities#146](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_30.cpp)] -## CStringT::operator >= +## `CStringT::operator >=` Determines whether the string on the left side of the operator is greater than or equal to the string on the right side. -``` +```cpp friend bool operator>=(const CStringT& str1, const CStringT& str2) throw(); friend bool operator>=(const CStringT& str1, PCXSTR psz2) throw(); friend bool operator>=(PCXSTR psz1, const CStringT& str2) throw(); @@ -1303,16 +1302,16 @@ friend bool operator>=(PCXSTR psz1, const CStringT& str2) throw(); ### Parameters -*str1*
-A `CStringT` for comparison. +*`str1`*\ +A **`CStringT`** for comparison. -*str2*
-A `CStringT` for comparison. +*`str2`*\ +A **`CStringT`** for comparison. -*psz1*
+*`psz1`*\ A pointer to a string for comparison. -*psz2*
+*`psz2`*\ A pointer to a string for comparison. ### Remarks @@ -1329,63 +1328,63 @@ A lexicographical comparison between strings, character by character until: [!code-cpp[NVC_ATLMFC_Utilities#147](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_31.cpp)] -## CStringT::Remove +## `CStringT::Remove` Removes all instances of the specified character from the string. -``` +```cpp int Remove(XCHAR chRemove); ``` ### Parameters -*chRemove*
+*`chRemove`*\ The character to be removed from a string. ### Return Value -The count of characters removed from the string. Zero if the string is not changed. +The count of characters removed from the string. Zero if the string isn't changed. ### Remarks -Comparisons for the character are case sensitive. +Comparisons for the character are case-sensitive. ### Example [!code-cpp[NVC_ATLMFC_Utilities#129](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_32.cpp)] -## CStringT::Replace +## `CStringT::Replace` -There are two versions of `Replace`.The first version replaces one or more copies of a substring by using another substring. Both substrings are null-terminated. The second version replaces one or more copies of a character by using another character. Both versions operate on the character data stored in `CStringT`. +There are two versions of `Replace`. The first version replaces one or more copies of a substring by using another substring. Both substrings are null-terminated. The second version replaces one or more copies of a character by using another character. Both versions operate on the character data stored in **`CStringT`**. -``` +```cpp int Replace(PCXSTR pszOld, PCXSTR pszNew); int Replace(XCHAR chOld, XCHAR chNew); ``` ### Parameters -*pszOld*
-A pointer to a null-terminated string to be replaced by *pszNew*. +*`pszOld`*\ +A pointer to a null-terminated string to be replaced by *`pszNew`*. -*pszNew*
-A pointer to a null-terminated string that replaces *pszOld*. +*`pszNew`*\ +A pointer to a null-terminated string that replaces *`pszOld`*. -*chOld*
-The character to be replaced by *chNew*. +*`chOld`*\ +The character to be replaced by *`chNew`*. -*chNew*
-The character replacing *chOld*. +*`chNew`*\ +The character replacing *`chOld`*. ### Return Value -Returns the number of replaced instances of the character or substring, or zero if the string is not changed. +Returns the number of replaced instances of the character or substring, or zero if the string isn't changed. ### Remarks -`Replace` can change the string length because *pszNew* and *pszOld* do not have to be the same length, and several copies of the old substring can be changed to the new one. The function performs a case-sensitive match. +`Replace` can change the string length because *`pszNew`* and *`pszOld`* don't have to be the same length, and several copies of the old substring can be changed to the new one. The function does a case-sensitive match. -Examples of `CStringT` instances are `CString`, `CStringA`, and `CStringW`. +Examples of **`CStringT`** instances are `CString`, `CStringA`, and `CStringW`. For `CStringA`, `Replace` works with ANSI or multibyte (MBCS) characters. For `CStringW`, `Replace` works with wide characters. @@ -1393,8 +1392,8 @@ For `CString`, the character data type is selected at compile time, based on whe |Defined Constant|Character Data Type| |----------------------|-------------------------| -|_UNICODE|Wide characters| -|_MBCS|Multi-byte characters| +|`_UNICODE`|Wide characters| +|`_MBCS`|Multi-byte characters| |Neither|Single-byte characters| |Both|Undefined| @@ -1402,22 +1401,22 @@ For `CString`, the character data type is selected at compile time, based on whe [!code-cpp[NVC_ATLMFC_Utilities#200](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_33.cpp)] -## CStringT::ReverseFind +## `CStringT::ReverseFind` -Searches this `CStringT` object for the last match of a character. +Searches this **`CStringT`** object for the last match of a character. -``` +```cpp int ReverseFind(XCHAR ch) const throw(); ``` ### Parameters -*ch*
+*`ch`*\ The character to search for. ### Return Value -The zero-based index of the last character in this `CStringT` object that matches the requested character, or -1 if the character is not found. +The zero-based index of the last character in this **`CStringT`** object that matches the requested character, or -1 if the character isn't found. ### Remarks @@ -1427,44 +1426,44 @@ The function is similar to the run-time function `strrchr`. [!code-cpp[NVC_ATLMFC_Utilities#130](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_34.cpp)] -## CStringT::Right +## `CStringT::Right` -Extracts the last (that is, rightmost) *nCount* characters from this `CStringT` object and returns a copy of the extracted substring. +Extracts the last (that is, rightmost) *`nCount`* characters from this **`CStringT`** object and returns a copy of the extracted substring. -``` +```cpp CStringT Right(int nCount) const; ``` ### Parameters -*nCount*
-The number of characters to extract from this `CStringT` object. +*`nCount`*\ +The number of characters to extract from this **`CStringT`** object. ### Return Value -A `CStringT` object that contains a copy of the specified range of characters. Note that the returned `CStringT` object can be empty. +A **`CStringT`** object that contains a copy of the specified range of characters. The returned **`CStringT`** object can be empty. ### Remarks -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). +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 [!code-cpp[NVC_ATLMFC_Utilities#131](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_35.cpp)] -## CStringT::SetSysString +## `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; ``` ### Parameters -*pbstr*
+*`pbstr`*\ A pointer to a character string. ### Return Value @@ -1473,7 +1472,7 @@ The new string. ### Remarks -Depending on the contents of the `CStringT` object, the value of the BSTR referenced by *pbstr* can change. The function throws a `CMemoryException` if insufficient memory exists. +Depending on the contents of the **`CStringT`** object, the value of the **`BSTR`** referenced by *`pbstr`* can change. The function throws a `CMemoryException` if insufficient memory exists. This function is normally used to change the value of strings passed by reference for Automation. @@ -1481,88 +1480,86 @@ This function is normally used to change the value of strings passed by referenc [!code-cpp[NVC_ATLMFC_Utilities#132](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_36.cpp)] -## CStringT::SpanExcluding +## `CStringT::SpanExcluding` -Extracts characters from the string, starting with the first character, that are not in the set of characters identified by *pszCharSet*. +Extracts characters from the string, starting with the first character, that aren't in the set of characters identified by *`pszCharSet`*. -``` +```cpp CStringT SpanExcluding(PCXSTR pszCharSet) const; ``` ### Parameters -*pszCharSet*
+*`pszCharSet`*\ A string interpreted as a set of characters. ### Return Value -A substring that contains characters in the string that are not in *pszCharSet*, beginning with the first character in the string and ending with the first character found in the string that is also in *pszCharSet* (that is, starting with the first character in the string and up to but excluding the first character in the string that is found *pszCharSet*). It returns the entire string if no character in *pszCharSet* is found in the string. +A substring that contains characters in the string that aren't in *`pszCharSet`*, beginning with the first character in the string and ending with the first character found in the string that is also in *`pszCharSet`* (that is, starting with the first character in the string and up to but excluding the first character in the string that is found *`pszCharSet`*). It returns the entire string if no character in *`pszCharSet`* is found in the string. ### Remarks -`SpanExcluding` extracts and returns all characters preceding the first occurrence of a character from *pszCharSet* (in other words, the character from *pszCharSet* and all characters following it in the string, are not returned). If no character from *pszCharSet* is found in the string, then `SpanExcluding` returns the entire string. +`SpanExcluding` extracts and returns all characters preceding the first occurrence of a character from *`pszCharSet`* (in other words, the character from *`pszCharSet`* and all characters following it in the string, aren't returned). If no character from *`pszCharSet`* is found in the string, then `SpanExcluding` returns the entire string. ### Example [!code-cpp[NVC_ATLMFC_Utilities#133](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_37.cpp)] -## CStringT::SpanIncluding +## `CStringT::SpanIncluding` -Extracts characters from the string, starting with the first character, that are in the set of characters identified by *pszCharSet*. +Extracts characters from the string, starting with the first character, that are in the set of characters identified by *`pszCharSet`*. -``` +```cpp CStringT SpanIncluding(PCXSTR pszCharSet) const; ``` ### Parameters -*pszCharSet*
+*`pszCharSet`*\ A string interpreted as a set of characters. ### Return Value -A substring that contains characters in the string that are in *pszCharSet*, beginning with the first character in the string and ending when a character is found in the string that is not in *pszCharSet*. `SpanIncluding` returns an empty substring if the first character in the string is not in the specified set. +A substring that contains characters in the string that are in *`pszCharSet`*, beginning with the first character in the string and ending when a character is found in the string that isn't in *`pszCharSet`*. `SpanIncluding` returns an empty substring if the first character in the string isn't in the specified set. ### Remarks -If the first character of the string is not in the character set, then `SpanIncluding` returns an empty string. Otherwise, it returns a sequence of consecutive characters that are in the set. +If the first character of the string isn't in the character set, then `SpanIncluding` returns an empty string. Otherwise, it returns a sequence of consecutive characters that are in the set. ### Example [!code-cpp[NVC_ATLMFC_Utilities#134](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_38.cpp)] -## CStringT::Tokenize +## `CStringT::Tokenize` Finds the next token in a target string -``` +```cpp CStringT Tokenize(PCXSTR pszTokens, int& iStart) const; ``` ### Parameters -*pszTokens*
-A string containing token delimiters. The order of these delimiters is not important. +*`pszTokens`*\ +A string containing token delimiters. The order of these delimiters isn't important. -*iStart*
+*`iStart`*\ The zero-based index to begin the search. ### Return Value -A `CStringT` object containing the current token value. +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 remainder 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` does not 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 [!code-cpp[NVC_ATLMFC_Utilities#135](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_39.cpp)] -### Remarks - The output from this example is as follows: ```Output @@ -1571,11 +1568,11 @@ Resulting Token: Second Resulting Token: Third ``` -## CStringT::Trim +## `CStringT::Trim` Trims leading and trailing characters from the string. -``` +```cpp CStringT& Trim(XCHAR chTarget); CStringT& Trim(PCXSTR pszTargets); CStringT& Trim(); @@ -1583,11 +1580,11 @@ CStringT& Trim(); ### Parameters -*chTarget*
+*`chTarget`*\ The target character to be trimmed. -*pszTargets*
-A pointer to a string containing the target characters to be trimmed. All leading and trailing occurrences of characters in *pszTarget* will be trimmed from the `CStringT` object. +*`pszTargets`*\ +A pointer to a string containing the target characters to be trimmed. All leading and trailing occurrences of characters in *`pszTargets`* will be trimmed from the **`CStringT`** object. ### Return Value @@ -1597,9 +1594,9 @@ Returns the trimmed string. Removes all leading and trailing occurrences of one of the following: -- The character specified by *chTarget*. +- The character specified by *`chTarget`*. -- All characters found in the string specified by *pszTargets*. +- All characters found in the string specified by *`pszTargets`*. - Whitespace. @@ -1607,8 +1604,6 @@ Removes all leading and trailing occurrences of one of the following: [!code-cpp[NVC_ATLMFC_Utilities#136](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_40.cpp)] -### Remarks - The output from this example is as follows: ```Output @@ -1616,11 +1611,11 @@ Before: "******Soccer is best, but liquor is quicker!!!!!" After : "Soccer is best, but liquor is quicker" ``` -## CStringT::TrimLeft +## `CStringT::TrimLeft` Trims leading characters from the string. -``` +```cpp CStringT& TrimLeft(XCHAR chTarget); CStringT& TrimLeft(PCXSTR pszTargets); CStringT& TrimLeft(); @@ -1628,11 +1623,11 @@ CStringT& TrimLeft(); ### Parameters -*chTarget*
+*`chTarget`*\ The target character to be trimmed. -*pszTargets*
-A pointer to a string containing the target characters to be trimmed. All leading occurrences of characters in *pszTarget* will be trimmed from the `CStringT` object. +*`pszTargets`*\ +A pointer to a string containing the target characters to be trimmed. All leading occurrences of characters in *`pszTargets`* will be trimmed from the **`CStringT`** object. ### Return Value @@ -1642,9 +1637,9 @@ The resulting trimmed string. Removes all leading and trailing occurrences of one of the following: -- The character specified by *chTarget*. +- The character specified by *`chTarget`*. -- All characters found in the string specified by *pszTargets*. +- All characters found in the string specified by *`pszTargets`*. - Whitespace. @@ -1652,11 +1647,11 @@ Removes all leading and trailing occurrences of one of the following: [!code-cpp[NVC_ATLMFC_Utilities#137](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_41.cpp)] -## CStringT::TrimRight +## `CStringT::TrimRight` Trims trailing characters from the string. -``` +```cpp CStringT& TrimRight(XCHAR chTarget); CStringT& TrimRight(PCXSTR pszTargets); CStringT& TrimRight(); @@ -1664,33 +1659,31 @@ CStringT& TrimRight(); ### Parameters -*chTarget*
+*`chTarget`*\ The target character to be trimmed. -*pszTargets*
-A pointer to a string containing the target characters to be trimmed. All trailing occurrences of characters in *pszTarget* will be trimmed from the `CStringT` object. +*`pszTargets`*\ +A pointer to a string containing the target characters to be trimmed. All trailing occurrences of characters in *`pszTargets`* will be trimmed from the **`CStringT`** object. ### Return Value -Returns the `CStringT` object that contains the trimmed string. +Returns the **`CStringT`** object that contains the trimmed string. ### Remarks Removes trailing occurrences of one of the following: -- The character specified by *chTarget*. +- The character specified by *`chTarget`*. -- All characters found in the string specified by *pszTargets*. +- All characters found in the string specified by *`pszTargets`*. - Whitespace. -The `CStringT& TrimRight(XCHAR chTarget)` version accepts one character parameter and removes all copies of that character from the end of `CStringT` string data. It starts from the end of the string and works toward the front. It stops when it finds a different character or when `CSTringT` runs out of character data. - -The `CStringT& TrimRight(PCXSTR pszTargets)` version accepts a null-terminated string that contains all the different characters to search for. It removes all copies of those characters in the `CStringT` object. It starts at the end of the string and works toward the front. It stops when it finds a character that is not in the target string, or when `CStringT` runs out of character data. It does not try to match the whole target string to a substring at the end of `CStringT`. +The `CStringT& TrimRight(XCHAR chTarget)` version accepts one character parameter and removes all copies of that character from the end of **`CStringT`** string data. It starts from the end of the string and works toward the front. It stops when it finds a different character or when **`CStringT`** runs out of character data. -The `CStringT& TrimRight()` version requires no parameters. It trims any trailing whitespace characters from the end of the `CStringT` string. Whitespace characters can be line breaks, spaces, or tabs. +The `CStringT& TrimRight(PCXSTR pszTargets)` version accepts a null-terminated string that contains all the different characters to search for. It removes all copies of those characters in the **`CStringT`** object. It starts at the end of the string and works toward the front. It stops when it finds a character that isn't in the target string, or when **`CStringT`** runs out of character data. It doesn't try to match the whole target string to a substring at the end of **`CStringT`**. -- +The `CStringT& TrimRight()` version requires no parameters. It trims any trailing whitespace characters from the end of the **`CStringT`** string. Whitespace characters can be line breaks, spaces, or tabs. ### Example @@ -1698,6 +1691,6 @@ The `CStringT& TrimRight()` version requires no parameters. It trims any trailin ## See also -[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) +[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) diff --git a/docs/atl-mfc-shared/reference/ctime-class.md b/docs/atl-mfc-shared/reference/ctime-class.md index 7703f13a37..067db91b52 100644 --- a/docs/atl-mfc-shared/reference/ctime-class.md +++ b/docs/atl-mfc-shared/reference/ctime-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CTime Class" title: "CTime Class" ms.date: "10/18/2018" f1_keywords: ["ATLTIME/ATL::CTime", "ATLTIME/ATL::CTime::CTime", "ATLTIME/ATL::CTime::Format", "ATLTIME/ATL::CTime::FormatGmt", "ATLTIME/ATL::CTime::GetAsDBTIMESTAMP", "ATLTIME/ATL::CTime::GetAsSystemTime", "ATLTIME/ATL::CTime::GetCurrentTime", "ATLTIME/ATL::CTime::GetDay", "ATLTIME/ATL::CTime::GetDayOfWeek", "ATLTIME/ATL::CTime::GetGmtTm", "ATLTIME/ATL::CTime::GetHour", "ATLTIME/ATL::CTime::GetLocalTm", "ATLTIME/ATL::CTime::GetMinute", "ATLTIME/ATL::CTime::GetMonth", "ATLTIME/ATL::CTime::GetSecond", "ATLTIME/ATL::CTime::GetTime", "ATLTIME/ATL::CTime::GetYear", "ATLTIME/ATL::CTime::Serialize64"] @@ -11,7 +12,7 @@ Represents an absolute time and date. ## Syntax -``` +```cpp class CTime ``` @@ -46,7 +47,7 @@ class CTime ### Operators -||| +|Name|Description| |-|-| |[operator + -](#operator_add_-)|These operators add and subtract `CTimeSpan` and `CTime` objects.| |[operator +=, -=](#operator_add_eq_-_eq)|These operators add and subtract a `CTimeSpan` object to and from this `CTime` object.| @@ -81,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(); @@ -107,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, @@ -192,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; ``` @@ -223,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; ``` @@ -254,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(); ``` @@ -279,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(); ``` @@ -304,7 +305,7 @@ TRUE if successful; otherwise FALSE. Returns a `CTime` object that represents the current time. -``` +```cpp static CTime WINAPI GetCurrentTime() throw(); ``` @@ -320,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(); ``` @@ -340,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(); ``` @@ -360,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; ``` @@ -387,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(); ``` @@ -407,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; ``` @@ -434,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(); ``` @@ -454,7 +455,7 @@ See the example for [GetHour](#gethour). Returns the month represented by the `CTime` object. -``` +```cpp int GetMonth() const throw(); ``` @@ -474,7 +475,7 @@ See the example for [GetDay](#getday). Returns the second represented by the `CTime` object. -``` +```cpp int GetSecond() const throw(); ``` @@ -494,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(); ``` @@ -510,7 +511,7 @@ __time64_t GetTime() const throw(); Returns the year represented by the `CTime` object. -``` +```cpp int GetYear(); ``` @@ -530,7 +531,7 @@ See the example for [GetDay](#getday). The assignment operator. -``` +```cpp CTime& operator=(__time64_t time) throw(); ``` @@ -551,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(); @@ -581,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(); ``` @@ -610,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 abebccea3e..ae10bdba1c 100644 --- a/docs/atl-mfc-shared/reference/ctimespan-class.md +++ b/docs/atl-mfc-shared/reference/ctimespan-class.md @@ -1,17 +1,17 @@ --- +description: "Learn more about: CTimeSpan Class" 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 ``` @@ -21,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(); @@ -79,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(); @@ -107,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 @@ -124,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: @@ -141,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; @@ -153,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 @@ -175,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(); ``` @@ -195,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(); ``` @@ -217,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(); ``` @@ -231,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(); ``` @@ -247,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(); ``` @@ -261,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(); ``` @@ -277,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(); ``` @@ -291,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(); ``` @@ -307,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 @@ -335,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 @@ -361,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 @@ -383,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 ddf9bc330e..9eb991ca28 100644 --- a/docs/atl-mfc-shared/reference/iatlstringmgr-class.md +++ b/docs/atl-mfc-shared/reference/iatlstringmgr-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IAtlStringMgr Class" title: "IAtlStringMgr Class" ms.date: "10/18/2018" f1_keywords: ["IAtlStringMgr", "ATLSIMPSTR/ATL::IAtlStringMgr", "ATLSIMPSTR/ATL::Allocate", "ATLSIMPSTR/ATL::Clone", "ATLSIMPSTR/ATL::Free", "ATLSIMPSTR/ATL::GetNilString", "ATLSIMPSTR/ATL::Reallocate"] @@ -11,7 +12,7 @@ This class represents the interface to a `CStringT` memory manager. ## Syntax -``` +```cpp __interface IAtlStringMgr ``` @@ -19,7 +20,7 @@ __interface IAtlStringMgr ### Methods -||| +|Name|Description| |-|-| |[Allocate](#allocate)|Call this method to allocate a new string data structure.| |[Clone](#clone)|Call this method to return a pointer to a new string manager for use with another instance of `CSimpleStringT`.| @@ -41,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(); ``` @@ -71,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(); ``` @@ -112,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(); ``` @@ -134,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 6869f6c88e..b48c6a636d 100644 --- a/docs/atl-mfc-shared/string-data-management.md +++ b/docs/atl-mfc-shared/string-data-management.md @@ -1,20 +1,20 @@ --- +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. @@ -22,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. @@ -34,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"` @@ -47,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 9ca8653328..1c0b4515fa 100644 --- a/docs/atl-mfc-shared/strings-atl-mfc.md +++ b/docs/atl-mfc-shared/strings-atl-mfc.md @@ -1,8 +1,8 @@ --- +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) @@ -10,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 849f8d788f..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 @@ -1,4 +1,5 @@ --- +description: "Learn more about: Unicode and Multibyte Character Set (MBCS) Support" title: "Unicode and Multibyte Character Set (MBCS) Support" ms.date: "01/09/2017" helpviewer_keywords: ["MFC [C++], character set support", "MBCS [C++], strings and MFC support", "strings [C++], MBCS support in MFC", "character sets [C++], multibyte", "Unicode [C++], MFC strings", "Unicode [C++], string objects", "strings [C++], Unicode", "strings [C++], character set support"] @@ -7,45 +8,69 @@ 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 -The entire MFC class library is conditionally enabled for Unicode characters and strings stored in wide characters as UTF-16. In particular, class [CString](../atl-mfc-shared/reference/cstringt-class.md) is Unicode-enabled. +The entire MFC class library is conditionally enabled for Unicode characters and strings stored in wide characters as UTF-16. In particular, class [`CString`](../atl-mfc-shared/reference/cstringt-class.md) is Unicode-enabled. These library, debugger, and DLL files are used to support Unicode in MFC: -||||| -|-|-|-|-| -|UAFXCW.LIB|UAFXCW.PDB|UAFXCWD.LIB|UAFXCWD.PDB| -|MFC*version*U.LIB|MFC*version*U.PDB|MFC*version*U.DLL|MFC*version*UD.LIB| -|MFC*version*UD.PDB|MFC*version*UD.DLL|MFCS*version*U.LIB|MFCS*version*U.PDB| -|MFCS*version*UD.LIB|MFCS*version*UD.PDB|MFCM*version*U.LIB|MFCM*version*U.PDB| -|MFCM*version*U.DLL|MFCM*version*UD.LIB|MFCM*version*UD.PDB|MFCM*version*UD.DLL| +:::row::: + :::column span=""::: + MFC*version*U.LIB\ + MFC*version*UD.LIB\ + MFCM*version*U.LIB\ + MFCM*version*UD.LIB\ + MFCS*version*U.LIB\ + MFCS*version*UD.LIB\ + UAFXCW.LIB\ + UAFXCWD.LIB + :::column-end::: + :::column span=""::: + MFC*version*U.PDB\ + MFC*version*UD.PDB\ + MFCM*version*U.PDB\ + MFCM*version*UD.PDB\ + MFCS*version*U.PDB\ + MFCS*version*UD.PDB\ + UAFXCW.PDB\ + UAFXCWD.PDB + :::column-end::: + :::column span=""::: + MFC*version*U.DLL\ + MFC*version*UD.DLL\ + MFCM*version*U.DLL\ + MFCM*version*UD.DLL + :::column-end::: +:::row-end::: (*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. +- 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. - Use the following data types for characters and character pointers: - - Use TCHAR where you would use **`char`**. + - Use `TCHAR` where you would use **`char`**. - - Use LPTSTR where you would use **`char`**\*. + - Use `LPTSTR` where you would use **`char`**\*. - - Use LPCTSTR where you would use **const char**\*. `CString` provides the operator LPCTSTR to convert between `CString` and LPCTSTR. + - Use `LPCTSTR` where you would use **`const char`**\*. `CString` provides the operator `LPCTSTR` to convert between `CString` and `LPCTSTR`. `CString` also supplies Unicode-aware constructors, assignment operators, and comparison operators. @@ -55,29 +80,29 @@ 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. > [!NOTE] > Unicode string serialization in MFC can read both Unicode and MBCS strings regardless of which version of the application that you are running. Your data files are portable between Unicode and MBCS versions of your program. -`CString` member functions use special "generic text" versions of the C run-time functions they call, or they use Unicode-aware functions. Therefore, for example, if a `CString` function would typically call `strcmp`, it calls the corresponding generic-text function `_tcscmp` instead. Depending on how the symbols _MBCS and _UNICODE are defined, `_tcscmp` maps as follows: +`CString` member functions use special "generic text" versions of the C run-time functions they call, or they use Unicode-aware functions. Therefore, for example, if a `CString` function would typically call `strcmp`, it calls the corresponding generic-text function `_tcscmp` instead. Depending on how the symbols `_MBCS` and `_UNICODE` are defined, `_tcscmp` maps as follows: -||| +|Symbols|Function| |-|-| -|_MBCS defined|`_mbscmp`| -|_UNICODE defined|`wcscmp`| +|`_MBCS` defined|`_mbscmp`| +|`_UNICODE` defined|`wcscmp`| |Neither symbol defined|`strcmp`| > [!NOTE] -> The symbols _MBCS and _UNICODE are mutually exclusive. +> The symbols `_MBCS` and `_UNICODE` are mutually exclusive. Generic-text function mappings for all of the run-time string-handling routines are discussed in [C Run-Time Library Reference](../c-runtime-library/c-run-time-library-reference.md). For a list, see [Internationalization](../c-runtime-library/internationalization.md). -Similarly, `CString` methods are implemented by using generic data type mappings. To enable both MBCS and Unicode, MFC uses TCHAR for **`char`** or **`wchar_t`**, LPTSTR for **`char`**\* or `wchar_t*`, and LPCTSTR for **const char**\* or `const wchar_t*`. These ensure the correct mappings for either MBCS or Unicode. +Similarly, `CString` methods are implemented by using generic data type mappings. To enable both MBCS and Unicode, MFC uses `TCHAR` for **`char`** or **`wchar_t`**, `LPTSTR` for **`char`**\* or `wchar_t*`, and `LPCTSTR` for **`const char`**\* or `const wchar_t*`. These ensure the correct mappings for either MBCS or Unicode. ## See also diff --git a/docs/atl-mfc-shared/using-cstring.md b/docs/atl-mfc-shared/using-cstring.md index bd2f1df95e..f6a99466fc 100644 --- a/docs/atl-mfc-shared/using-cstring.md +++ b/docs/atl-mfc-shared/using-cstring.md @@ -1,20 +1,21 @@ --- +description: "Learn more about: Using CString" title: "Using CString" 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`. @@ -35,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)
@@ -47,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-mfc-shared/using-cstringt.md b/docs/atl-mfc-shared/using-cstringt.md index d864be8de8..e7232579f8 100644 --- a/docs/atl-mfc-shared/using-cstringt.md +++ b/docs/atl-mfc-shared/using-cstringt.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Using CStringT" title: "Using CStringT" ms.date: "11/04/2016" helpviewer_keywords: ["CStringT class, using"] diff --git a/docs/atl/active-template-library-atl-concepts.md b/docs/atl/active-template-library-atl-concepts.md index cbdf4011ce..cda405159a 100644 --- a/docs/atl/active-template-library-atl-concepts.md +++ b/docs/atl/active-template-library-atl-concepts.md @@ -1,14 +1,16 @@ --- +description: "Learn more about: Active Template Library (ATL) Concepts" title: "Active Template Library (ATL) Concepts" ms.date: "05/06/2019" helpviewer_keywords: ["ATL, about ATL"] ms.assetid: a3960991-4d76-4da5-9568-3fa7fde53ff4 +ms.topic: concept-article --- # Active Template Library (ATL) Concepts The Active Template Library (ATL) is a set of template-based C++ classes that let you create small, fast Component Object Model (COM) objects. It has special support for key COM features, including stock implementations, dual interfaces, standard COM enumerator interfaces, connection points, tear-off interfaces, and ActiveX controls. -If you do a lot of ATL programming, you will want to learn more about COM and .NET attributes, which is designed to simplify COM programming. For more information, see [Attributed Programming](../windows/attributed-programming-concepts.md). (COM and .NET attributes are not to be confused with the \[\[attribute]] feature in the C++ standard.) +If you do a lot of ATL programming, you will want to learn more about COM and .NET attributes, which is designed to simplify COM programming. For more information, see [Attributed Programming](../windows/attributes/cpp-attributes-com-net.md). (COM and .NET attributes are not to be confused with the \[\[attribute]] feature in the C++ standard.) ## In This Section @@ -27,7 +29,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)
@@ -89,7 +91,7 @@ Contains information on the ATL Project Wizard. [ATL Control Wizard](reference/atl-control-wizard.md)
Discusses how to add classes. -[Attributed Programming](../windows/attributed-programming-concepts.md)
+[Attributed Programming](../windows/attributes/cpp-attributes-com-net.md)
Provides an overview on using attributes to simplify COM programming plus a list of links to more detailed topics. [ATL Class Overview](atl-class-overview.md)
diff --git a/docs/atl/active-template-library-atl-tutorial.md b/docs/atl/active-template-library-atl-tutorial.md index 52c536ff96..2a9841ea00 100644 --- a/docs/atl/active-template-library-atl-tutorial.md +++ b/docs/atl/active-template-library-atl-tutorial.md @@ -5,6 +5,7 @@ ms.custom: "get-started-article" ms.date: "05/03/2019" helpviewer_keywords: ["ATL projects, tutorials", "controls [ATL], tutorials", "ATL tutorial", "tutorials [ATL]", "ATL, tutorials"] ms.assetid: f921a121-09c8-4812-9317-e15b2f1471fa +ms.topic: tutorial --- # Active Template Library (ATL) Tutorial 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 79d232829e..668cb2039f 100644 --- a/docs/atl/adding-a-control-atl-tutorial-part-2.md +++ b/docs/atl/adding-a-control-atl-tutorial-part-2.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Adding a Control (ATL Tutorial, Part 2)" title: "Adding a Control (ATL Tutorial, Part 2)" ms.custom: "get-started-article" ms.date: "08/19/2019" ms.assetid: c9575a75-1064-41f1-9697-7aada560c669 +ms.topic: tutorial --- # Adding a Control (ATL Tutorial, Part 2) @@ -108,7 +110,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 33d3bb8244..394d9aff8d 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 @@ -1,8 +1,10 @@ --- +description: "Learn more about: Adding a Property Page (ATL Tutorial, Part 6)" title: "Adding a Property Page (ATL Tutorial, Part 6)" ms.custom: "get-started-article" ms.date: "09/27/2018" ms.assetid: df80d255-e7ea-49d9-b940-3f012e90cf9b +ms.topic: tutorial --- # Adding a Property Page (ATL Tutorial, Part 6) @@ -141,7 +143,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 26adb48cad..839a2653ed 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 @@ -1,8 +1,10 @@ --- +description: "Learn more about: Adding a Property to the Control (ATL Tutorial, Part 3)" title: "Adding a Property to the Control (ATL Tutorial, Part 3)" ms.custom: "get-started-article" ms.date: "09/26/2018" ms.assetid: f775fe34-103b-4f07-9999-400e987ee030 +ms.topic: tutorial --- # Adding a Property to the Control (ATL Tutorial, Part 3) @@ -56,7 +58,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-atl-message-handler.md b/docs/atl/adding-an-atl-message-handler.md index f19399bf29..ee2243126a 100644 --- a/docs/atl/adding-an-atl-message-handler.md +++ b/docs/atl/adding-an-atl-message-handler.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Adding an ATL Message Handler" title: "Adding an ATL Message Handler" ms.date: "11/04/2016" helpviewer_keywords: ["message handlers [C++]", "ATL, windows", "message handling [C++], ATL message handler", "windows [C++], ATL", "ATL, message handlers"] ms.assetid: cdea38a1-0d9b-4f8d-bbd5-b4f063fb3eeb +ms.topic: concept-article --- # Adding an ATL Message Handler 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 68cfe2c834..48d9ef8f01 100644 --- a/docs/atl/adding-an-event-atl-tutorial-part-5.md +++ b/docs/atl/adding-an-event-atl-tutorial-part-5.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Adding an Event (ATL Tutorial, Part 5)" title: "Adding an Event (ATL Tutorial, Part 5)" ms.custom: "get-started-article" ms.date: "09/27/2018" ms.assetid: 2de12022-3148-4ce3-8606-8a9d4274f0e9 +ms.topic: tutorial --- # Adding an Event (ATL Tutorial, Part 5) @@ -148,7 +150,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/adding-connection-points-to-an-object.md b/docs/atl/adding-connection-points-to-an-object.md index c54bfb9d14..d2564c44cd 100644 --- a/docs/atl/adding-connection-points-to-an-object.md +++ b/docs/atl/adding-connection-points-to-an-object.md @@ -1,57 +1,55 @@ --- title: "Adding Connection Points to an Object" -ms.date: "11/04/2016" +description: "Learn more about: Adding Connection Points to an Object" +ms.date: 11/04/2016 helpviewer_keywords: ["connection points [C++], adding to ATL objects", "Implement Connection Point ATL wizard"] -ms.assetid: 843531be-4a36-4db0-9d54-e029b1a72a8b +ms.topic: how-to --- # Adding Connection Points to an Object -The [ATL Tutorial](../atl/active-template-library-atl-tutorial.md) demonstrates how to create a control with support for connection points, how to add events, and then how to implement the connection point. ATL implements connection points with the [IConnectionPointImpl](../atl/reference/iconnectionpointimpl-class.md) class. +The [ATL Tutorial](active-template-library-atl-tutorial.md) demonstrates how to create a control with support for connection points, how to add events, and then how to implement the connection point. ATL implements connection points with the [`IConnectionPointImpl`](reference/iconnectionpointimpl-class.md) class. To implement a connection point, you have two choices: - Implement your own outgoing event source, by adding a connection point to the control or object. - - Reuse a connection point interface defined in another type library. -In either case, the Implement Connection Point Wizard uses a type library to do its work. +In either case, the **Implement Connection Point Wizard** uses a type library to do its work. -### To add a connection point to a control or object +### Add a connection point to a control or object -1. Define a dispinterface in the library block of the .idl file. If you enabled support for connection points when you created the control with the ATL Control Wizard, the dispinterface will already be created. If you did not enable support for connection points when you created the control, you must manually add a dispinterface to the .idl file. The following is an example of a dispinterface. Outgoing interfaces are not required to be dispatch interfaces but many scripting languages such as VBScript and JScript require this, so this example uses two dispinterfaces: +1. Define a dispinterface in the library block of the `.idl` file. If you enabled support for connection points when you created the control with the **ATL Control Wizard**, the dispinterface will already be created. If you did not enable support for connection points when you created the control, you must manually add a dispinterface to the `.idl` file. The following is an example of a dispinterface. Outgoing interfaces are not required to be dispatch interfaces but many scripting languages such as VBScript and JScript require this, so this example uses two dispinterfaces: - [!code-cpp[NVC_ATL_Windowing#81](../atl/codesnippet/cpp/adding-connection-points-to-an-object_1.idl)] + [!code-cpp[NVC_ATL_Windowing#81](codesnippet/cpp/adding-connection-points-to-an-object_1.idl)] - Use either the uuidgen.exe or guidgen.exe utility to generate a GUID. + Use either the `uuidgen.exe` or `guidgen.exe` utility to generate a GUID. -2. Add the dispinterface as the `[default,source]` interface in the coclass for the object in the project's .idl file. Again, if you enabled support for connection points when you created the control, the ATL Control Wizard will create the `[default,source`] entry. To manually add this entry, add the line in bold: +2. Add the dispinterface as the `[default,source]` interface in the coclass for the object in the project's `.idl` file. Again, if you enabled support for connection points when you created the control, the ATL Control Wizard will create the `[default,source]` entry. To manually add this entry, add the line in bold: - [!code-cpp[NVC_ATL_Windowing#82](../atl/codesnippet/cpp/adding-connection-points-to-an-object_2.idl)] + [!code-cpp[NVC_ATL_Windowing#82](codesnippet/cpp/adding-connection-points-to-an-object_2.idl)] - See the .idl file in the [Circ](../overview/visual-cpp-samples.md) ATL sample for an example. + See the `.idl` file in the [Circ](../overview/visual-cpp-samples.md) ATL sample for an example. -3. Use Class View to add methods and properties to the event interface. Right-click the class in Class View, point to **Add** on the shortcut menu, and click **Add Connection Point**. +3. Use **Class View** to add methods and properties to the event interface. Right-click the class in **Class View**, point to **Add** on the shortcut menu, and select **Add Connection Point**. -4. In the **Source Interfaces** list box of the Implement Connection Point Wizard, select **Project's interfaces**. If you choose an interface for your control and press **OK**, you will: +4. In the **Source Interfaces** list box of the **Implement Connection Point Wizard**, select **Project's interfaces**. If you choose an interface for your control and select **OK**, you: - Generate a header file with an event proxy class that implements the code that will make the outgoing calls for the event. - - Add an entry to the connection point map. - You will also see a list of all of the type libraries on your computer. You should only use one of these other type libraries to define your connection point if you want to implement the exact same outgoing interface found in another type library. - -### To reuse a connection point interface defined in another type library + You also see a list of all of the type libraries on your computer. Only use one of these other type libraries to define your connection point if you want to implement the exact same outgoing interface found in another type library. -1. In Class View, right-click a class that implements a **BEGIN_COM_MAP** macro, point to **Add** on the shortcut menu, and click **Add Connection Point**. +### Reuse a connection point interface defined in another type library -2. In the Implement Connection Point Wizard, select a type library and an interface in the type library and click **Add**. +1. In **Class View**, right-click a class that implements a `BEGIN_COM_MAP` macro, point at **Add** on the shortcut menu, and select **Add Connection Point**. -3. Edit the .idl file to either: +2. In the **Implement Connection Point Wizard**, select a type library and an interface in the type library and select **Add**. - - Copy the dispinterface from the .idl file for the object whose event-source is being used. +3. Edit the `.idl` file to either: + - Copy the dispinterface from the `.idl` file for the object whose event-source is being used. - Use the **importlib** instruction on that type library. ## See also -[Connection Point](../atl/atl-connection-points.md) +[Connection Point](atl-connection-points.md) diff --git a/docs/atl/adding-functionality-to-the-composite-control.md b/docs/atl/adding-functionality-to-the-composite-control.md index 465323db85..3576620945 100644 --- a/docs/atl/adding-functionality-to-the-composite-control.md +++ b/docs/atl/adding-functionality-to-the-composite-control.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Adding Functionality to the Composite Control" title: "Adding Functionality to the Composite Control" ms.date: "11/04/2016" helpviewer_keywords: ["event handlers [C++], ActiveX controls", "composite controls, handling events", "ActiveX controls [C++], events"] ms.assetid: 98f85681-9564-480d-af38-03f9733fe58b +ms.topic: concept-article --- # Adding Functionality to the Composite Control diff --git a/docs/atl/aggregation.md b/docs/atl/aggregation.md index d6491b1b4e..36c510daf3 100644 --- a/docs/atl/aggregation.md +++ b/docs/atl/aggregation.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Aggregation" title: "Aggregation" ms.date: "11/04/2016" helpviewer_keywords: ["aggregation [C++]", "aggregate objects [C++]"] diff --git a/docs/atl/atl-and-the-free-threaded-marshaler.md b/docs/atl/atl-and-the-free-threaded-marshaler.md index c3bb490621..5d5e78c8a6 100644 --- a/docs/atl/atl-and-the-free-threaded-marshaler.md +++ b/docs/atl/atl-and-the-free-threaded-marshaler.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL and the Free Threaded Marshaler" title: "ATL and the Free Threaded Marshaler" ms.date: "11/04/2016" helpviewer_keywords: ["ATL, free threaded marshaler", "free threaded marshaler", "threading [C++], marshaler in ATL", "threading [ATL], free threaded marshaler", "FTM in ATL"] diff --git a/docs/atl/atl-class-overview.md b/docs/atl/atl-class-overview.md index fffa86786c..98846a0de5 100644 --- a/docs/atl/atl-class-overview.md +++ b/docs/atl/atl-class-overview.md @@ -1,40 +1,57 @@ --- -title: "ATL Class Overview" +description: "Learn more about: ATL class overview" +title: "ATL class overview" ms.date: "11/04/2016" helpviewer_keywords: ["classes [C++], ATL", "ATL, class reference"] ms.assetid: c38ac93d-c3a2-4ce7-8153-f1d34c0f0fa6 +ms.topic: concept-article --- -# ATL Class Overview +# ATL class overview Classes in the Active Template Library (ATL) can be categorized as follows: -||| -|-|-| -|[Class Factories](../atl/class-factories-classes.md)|[Memory Management](../atl/memory-management-classes.md)| -|[Class Information](../atl/class-information-classes.md)|[MMC Snap-In](../atl/mmc-snap-in-classes.md)| -|[Collection](../atl/collection-classes.md)|[Object Safety](../atl/object-safety-classes.md)| -|[COM Modules](../atl/com-modules-classes.md)|[Persistence](../atl/persistence-classes.md)| -|[Composite Controls](../atl/composite-controls-classes.md)|[Properties and Property Pages](../atl/properties-and-property-pages-classes.md)| -|[Connection Points](../atl/connection-points-classes.md)|[Registry Support](../atl/registry-support-classes.md)| -|[Control Containment](../atl/control-containment-classes.md)|[Running Objects](../atl/running-objects-classes.md)| -|[Controls: General Support](../atl/controls-general-support-classes.md)|[Security](../atl/security-classes.md)| -|[Data Transfer](../atl/data-transfer-classes.md)|[Service Provider Support](../atl/service-provider-support-classes.md)| -|[Data Types](../atl/data-types-classes.md)|[Site Information](../atl/site-information-classes.md)| -|[Debugging and Exception](../atl/debugging-and-exceptions-classes.md)|[String and Text](../atl/string-and-text-classes.md)| -|[Dual Interfaces](../atl/dual-interfaces-classes.md)|[Tear-Off Interfaces](../atl/tear-off-interfaces-classes.md)| -|[Enumerators and Collections](../atl/enumerators-and-collections-classes.md)|[Thread Pooling](../atl/thread-pooling-classes.md)| -|[Error Information](../atl/error-information-classes.md)|[Threading Models and Critical Sections](../atl/threading-models-and-critical-sections-classes.md)| -|[File Handling](../atl/file-handling-classes.md)|[UI Support](../atl/ui-support-classes.md)| -|[Interface Pointers](../atl/interface-pointers-classes.md)|[Windows Support](../atl/windows-support-classes.md)| -|[IUnknown Implementation](../atl/iunknown-implementation-classes.md)|[Utility](../atl/utility-classes.md)| +[Class factories](../atl/class-factories-classes.md)\ +[Class information](../atl/class-information-classes.md)\ +[Collection](../atl/collection-classes.md)\ +[COM modules](../atl/com-modules-classes.md)\ +[Composite controls](../atl/composite-controls-classes.md)\ +[Connection points](../atl/connection-points-classes.md)\ +[Control containment](../atl/control-containment-classes.md)\ +[Controls: General support](../atl/controls-general-support-classes.md)\ +[Data transfer](../atl/data-transfer-classes.md)\ +[Data types](../atl/data-types-classes.md)\ +[Debugging and exception](../atl/debugging-and-exceptions-classes.md)\ +[Dual interfaces](../atl/dual-interfaces-classes.md)\ +[Enumerators and collections](../atl/enumerators-and-collections-classes.md)\ +[Error information](../atl/error-information-classes.md)\ +[File handling](../atl/file-handling-classes.md)\ +[Interface pointers](../atl/interface-pointers-classes.md)\ +[IUnknown implementation](../atl/iunknown-implementation-classes.md)\ +[Memory management](../atl/memory-management-classes.md)\ +[MMC snap-in](../atl/mmc-snap-in-classes.md)\ +[Object safety](../atl/object-safety-classes.md)\ +[Persistence](../atl/persistence-classes.md)\ +[Properties and property pages](../atl/properties-and-property-pages-classes.md)\ +[Registry support](../atl/registry-support-classes.md)\ +[Running objects](../atl/running-objects-classes.md)\ +[Security](../atl/security-classes.md)\ +[Service provider support](../atl/service-provider-support-classes.md)\ +[Site information](../atl/site-information-classes.md)\ +[String and text](../atl/string-and-text-classes.md)\ +[Tear-off interfaces](../atl/tear-off-interfaces-classes.md)\ +[Thread pooling](../atl/thread-pooling-classes.md)\ +[Threading models and critical sections](../atl/threading-models-and-critical-sections-classes.md)\ +[UI support](../atl/ui-support-classes.md)\ +[Windows support](../atl/windows-support-classes.md)\ +[Utility](../atl/utility-classes.md) -For additional classes that can be used in ATL projects, see [Shared Classes](../atl-mfc-shared/atl-mfc-shared-classes.md). +For additional classes that can be used in ATL projects, see [Shared classes](../atl-mfc-shared/atl-mfc-shared-classes.md). ## See also [Classes and structs](../atl/reference/atl-classes.md)
-[ATL COM Desktop Components](../atl/atl-com-desktop-components.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)
+[Global variables](../atl/reference/atl-global-variables.md)
[Macros](../atl/reference/atl-macros.md)
[Typedefs](../atl/reference/atl-typedefs.md) diff --git a/docs/atl/atl-collection-and-enumerator-classes.md b/docs/atl/atl-collection-and-enumerator-classes.md index f790d7b6e1..d96c74e570 100644 --- a/docs/atl/atl-collection-and-enumerator-classes.md +++ b/docs/atl/atl-collection-and-enumerator-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL Collection and Enumerator Classes" title: "ATL Collection and Enumerator Classes" ms.date: "11/04/2016" helpviewer_keywords: ["enumerators, ATL classes", "collection classes, ATL"] diff --git a/docs/atl/atl-collection-classes.md b/docs/atl/atl-collection-classes.md index 9cd13f25e2..db96014d6f 100644 --- a/docs/atl/atl-collection-classes.md +++ b/docs/atl/atl-collection-classes.md @@ -1,8 +1,10 @@ --- -title: "ATL Collection Classes" +description: "Learn more about: ATL Collection Classes" +title: "ATL collection class overview" ms.date: "11/19/2018" helpviewer_keywords: ["DestructElements function", "collection classes, choosing", "ConstructElements function", "SerializeElements function", "traits classes", "collection classes, about collection classes", "CTraits classes", "collection classes"] ms.assetid: 4d619d46-5b4e-41dd-b9fd-e86b1fbc00b5 +ms.topic: concept-article --- # ATL Collection Classes @@ -96,7 +98,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-collections-and-enumerators.md b/docs/atl/atl-collections-and-enumerators.md index 12b46f4cef..68eea6e6f8 100644 --- a/docs/atl/atl-collections-and-enumerators.md +++ b/docs/atl/atl-collections-and-enumerators.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL Collections and Enumerators" title: "ATL Collections and Enumerators" ms.date: "11/04/2016" helpviewer_keywords: ["enumerator interfaces", "collections, ATL classes", "enumerators, ATL classes", "collection interfaces"] diff --git a/docs/atl/atl-com-desktop-components.md b/docs/atl/atl-com-desktop-components.md index 13ac73af8b..3d5d2ad0c9 100644 --- a/docs/atl/atl-com-desktop-components.md +++ b/docs/atl/atl-com-desktop-components.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL COM Desktop Components" title: "ATL COM Desktop Components" ms.date: "10/19/2018" helpviewer_keywords: ["ATL, reference", "ATL, about ATL"] diff --git a/docs/atl/atl-com-property-pages.md b/docs/atl/atl-com-property-pages.md index fb11543bdd..109d83b95c 100644 --- a/docs/atl/atl-com-property-pages.md +++ b/docs/atl/atl-com-property-pages.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL COM Property Pages" title: "ATL COM Property Pages" ms.date: "11/04/2016" helpviewer_keywords: ["property pages, COM", "ATL COM objects", "COM property pages", "property pages, ATL", "COM objects, ATL", "ATL property pages"] diff --git a/docs/atl/atl-composite-control-fundamentals.md b/docs/atl/atl-composite-control-fundamentals.md index caed897fcb..99d5bc76e0 100644 --- a/docs/atl/atl-composite-control-fundamentals.md +++ b/docs/atl/atl-composite-control-fundamentals.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL Composite Control Fundamentals" title: "ATL Composite Control Fundamentals" ms.date: "11/04/2016" helpviewer_keywords: ["composite controls, about composite controls"] diff --git a/docs/atl/atl-connection-point-classes.md b/docs/atl/atl-connection-point-classes.md index b752077849..9de4d1eaf4 100644 --- a/docs/atl/atl-connection-point-classes.md +++ b/docs/atl/atl-connection-point-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL Connection Point Classes" title: "ATL Connection Point Classes" ms.date: "11/04/2016" helpviewer_keywords: ["CFirePropNotifyEvent class, connection point classes", "connection points [C++], ATL classes", "ATL, connection points", "CComDynamicUnkArray class, connection point classes", "CFirePropNotifyEvent class", "CComUnkArray class, connection point classes"] diff --git a/docs/atl/atl-connection-point-example.md b/docs/atl/atl-connection-point-example.md index 6eb291ed6a..0a7cf22ac7 100644 --- a/docs/atl/atl-connection-point-example.md +++ b/docs/atl/atl-connection-point-example.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL Connection Point Example" title: "ATL Connection Point Example" ms.date: "11/04/2016" helpviewer_keywords: ["connection points [C++], examples", "examples [ATL]"] diff --git a/docs/atl/atl-connection-points.md b/docs/atl/atl-connection-points.md index 06448765d6..9bad34db0b 100644 --- a/docs/atl/atl-connection-points.md +++ b/docs/atl/atl-connection-points.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL Connection Points" title: "ATL Connection Points" ms.date: "11/04/2016" helpviewer_keywords: ["connections, connection points", "ATL, connection points", "connection points [C++], about connection points"] @@ -8,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 695f7f873a..0000000000 --- a/docs/atl/atl-control-containment-faq.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -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-q.md). - -## 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-copy-policy-classes.md b/docs/atl/atl-copy-policy-classes.md index 2499a35b31..08787e3fe9 100644 --- a/docs/atl/atl-copy-policy-classes.md +++ b/docs/atl/atl-copy-policy-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL Copy Policy Classes" title: "ATL Copy Policy Classes" ms.date: "11/04/2016" helpviewer_keywords: ["data [C++], ATL", "classes [C++], copy policy", "copy policy classes [C++]", "_Copy class", "_CopyInterface class"] diff --git a/docs/atl/atl-encoding-reference.md b/docs/atl/atl-encoding-reference.md index a5e899b391..e7153b0520 100644 --- a/docs/atl/atl-encoding-reference.md +++ b/docs/atl/atl-encoding-reference.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL Encoding Reference" title: "ATL Encoding Reference" ms.date: "11/04/2016" helpviewer_keywords: ["encoding", "encoding, functions"] @@ -6,35 +7,35 @@ ms.assetid: 82d4fdf3-3c4a-4fe2-b297-8ffb4714406f --- # ATL Encoding Reference -Encoding in a range of common Internet standards such as uuencode, hexadecimal, and UTF8 is supported by the code found in atlenc.h. +Encoding in a range of common Internet standards such as uuencode, hexadecimal, and UTF8 is supported by the code found in *`atlenc.h`*. ### Functions -||| -|-|-| -|[AtlGetHexValue](reference/atl-text-encoding-functions.md#atlgethexvalue)|Call this function to get the numeric value of a hexadecimal digit.| -|[AtlHexDecode](reference/atl-text-encoding-functions.md#atlhexdecode)|Decodes a string of data that has been encoded as hexadecimal text such as by a previous call to [AtlHexEncode](reference/atl-text-encoding-functions.md#atlhexencode).| -|[AtlHexDecodeGetRequiredLength](reference/atl-text-encoding-functions.md#atlhexdecodegetrequiredlength)|Call this function to get the size in bytes of a buffer that could contain data decoded from a hex-encoded string of the specified length.| -|[AtlHexEncode](reference/atl-text-encoding-functions.md#atlhexencode)|Call this function to encode some data as a string of hexadecimal text.| -|[AtlHexEncodeGetRequiredLength](reference/atl-text-encoding-functions.md#atlhexencodegetrequiredlength)|Call this function to get the size in characters of a buffer that could contain a string encoded from data of the specified size.| -|[AtlUnicodeToUTF8](reference/atl-text-encoding-functions.md#atlunicodetoutf8)|Call this function to convert a Unicode string to UTF-8.| -|[BEncode](reference/atl-text-encoding-functions.md#bencode)|Call this function to convert some data using the "B" encoding.| -|[BEncodeGetRequiredLength](reference/atl-text-encoding-functions.md#bencodegetrequiredlength)|Call this function to get the size in characters of a buffer that could contain a string encoded from data of the specified size.| -|[EscapeXML](reference/atl-text-encoding-functions.md#escapexml)|Call this function to convert characters that are unsafe for use in XML to their safe equivalents.| -|[GetExtendedChars](reference/atl-text-encoding-functions.md#getextendedchars)|Call this function to get the number of extended characters in a string.| -|[IsExtendedChar](reference/atl-text-encoding-functions.md#isextendedchar)|Call this function to find out if a given character is an extended character (less than 32, greater than 126, and not a tab, line feed or carriage return)| -|[QEncode](reference/atl-text-encoding-functions.md#qencode)|Call this function to convert some data using the "Q" encoding.| -|[QEncodeGetRequiredLength](reference/atl-text-encoding-functions.md#qencodegetrequiredlength)|Call this function to get the size in characters of a buffer that could contain a string encoded from data of the specified size.| -|[QPDecode](reference/atl-text-encoding-functions.md#qpdecode)|Decodes a string of data that has been encoded in quoted-printable format such as by a previous call to [QPEncode](reference/atl-text-encoding-functions.md#qpencode).| -|[QPDecodeGetRequiredLength](reference/atl-text-encoding-functions.md#qpdecodegetrequiredlength)|Call this function to get the size in bytes of a buffer that could contain data decoded from quoted-printable-encoded string of the specified length.| -|[QPEncode](reference/atl-text-encoding-functions.md#qpencode)|Call this function to encode some data in quoted-printable format.| -|[QPEncodeGetRequiredLength](reference/atl-text-encoding-functions.md#qpencodegetrequiredlength)|Call this function to get the size in characters of a buffer that could contain a string encoded from data of the specified size.| -|[UUDecode](reference/atl-text-encoding-functions.md#uudecode)|Decodes a string of data that has been uuencoded such as by a previous call to [UUEncode](reference/atl-text-encoding-functions.md#uuencode).| -|[UUDecodeGetRequiredLength](reference/atl-text-encoding-functions.md#uudecodegetrequiredlength)|Call this function to get the size in bytes of a buffer that could contain data decoded from a uuencoded string of the specified length.| -|[UUEncode](reference/atl-text-encoding-functions.md#uuencode)|Call this function to uuencode some data.| -|[UUEncodeGetRequiredLength](reference/atl-text-encoding-functions.md#uuencodegetrequiredlength)|Call this function to get the size in characters of a buffer that could contain a string encoded from data of the specified size.| +| Function | Use case | +|--|--| +| [AtlGetHexValue](reference/atl-text-encoding-functions.md#atlgethexvalue) | Call this function to get the numeric value of a hexadecimal digit. | +| [AtlHexDecode](reference/atl-text-encoding-functions.md#atlhexdecode) | Decodes a string of data that has been encoded as hexadecimal text such as by a previous call to [AtlHexEncode](reference/atl-text-encoding-functions.md#atlhexencode). | +| [AtlHexDecodeGetRequiredLength](reference/atl-text-encoding-functions.md#atlhexdecodegetrequiredlength) | Call this function to get the size in bytes of a buffer that could contain data decoded from a hex-encoded string of the specified length. | +| [AtlHexEncode](reference/atl-text-encoding-functions.md#atlhexencode) | Call this function to encode some data as a string of hexadecimal text. | +| [AtlHexEncodeGetRequiredLength](reference/atl-text-encoding-functions.md#atlhexencodegetrequiredlength) | Call this function to get the size in characters of a buffer that could contain a string encoded from data of the specified size. | +| [AtlUnicodeToUTF8](reference/atl-text-encoding-functions.md#atlunicodetoutf8) | Call this function to convert a Unicode string to UTF-8. | +| [BEncode](reference/atl-text-encoding-functions.md#bencode) | Call this function to convert some data using the "B" encoding. | +| [BEncodeGetRequiredLength](reference/atl-text-encoding-functions.md#bencodegetrequiredlength) | Call this function to get the size in characters of a buffer that could contain a string encoded from data of the specified size. | +| [EscapeXML](reference/atl-text-encoding-functions.md#escapexml) | Call this function to convert characters that are unsafe for use in XML to their safe equivalents. | +| [GetExtendedChars](reference/atl-text-encoding-functions.md#getextendedchars) | Call this function to get the number of extended characters in a string. | +| [IsExtendedChar](reference/atl-text-encoding-functions.md#isextendedchar) | Call this function to find out if a given character is an extended character (less than 32, greater than 126, and not a tab, line feed or carriage return) | +| [QEncode](reference/atl-text-encoding-functions.md#qencode) | Call this function to convert some data using the "Q" encoding. | +| [QEncodeGetRequiredLength](reference/atl-text-encoding-functions.md#qencodegetrequiredlength) | Call this function to get the size in characters of a buffer that could contain a string encoded from data of the specified size. | +| [QPDecode](reference/atl-text-encoding-functions.md#qpdecode) | Decodes a string of data that has been encoded in quoted-printable format such as by a previous call to [QPEncode](reference/atl-text-encoding-functions.md#qpencode). | +| [QPDecodeGetRequiredLength](reference/atl-text-encoding-functions.md#qpdecodegetrequiredlength) | Call this function to get the size in bytes of a buffer that could contain data decoded from quoted-printable-encoded string of the specified length. | +| [QPEncode](reference/atl-text-encoding-functions.md#qpencode) | Call this function to encode some data in quoted-printable format. | +| [QPEncodeGetRequiredLength](reference/atl-text-encoding-functions.md#qpencodegetrequiredlength) | Call this function to get the size in characters of a buffer that could contain a string encoded from data of the specified size. | +| [UUDecode](reference/atl-text-encoding-functions.md#uudecode) | Decodes a string of data that has been uuencoded such as by a previous call to [UUEncode](reference/atl-text-encoding-functions.md#uuencode). | +| [UUDecodeGetRequiredLength](reference/atl-text-encoding-functions.md#uudecodegetrequiredlength) | Call this function to get the size in bytes of a buffer that could contain data decoded from a uuencoded string of the specified length. | +| [UUEncode](reference/atl-text-encoding-functions.md#uuencode) | Call this function to uuencode some data. | +| [UUEncodeGetRequiredLength](reference/atl-text-encoding-functions.md#uuencodegetrequiredlength) | Call this function to get the size in characters of a buffer that could contain a string encoded from data of the specified size. | ## See also [Concepts](../atl/active-template-library-atl-concepts.md)
-[ATL COM Desktop Components](../atl/atl-com-desktop-components.md) +[ATL COM desktop components](../atl/atl-com-desktop-components.md) diff --git a/docs/atl/atl-event-handling-summary.md b/docs/atl/atl-event-handling-summary.md index 57cc50379a..166f1d4028 100644 --- a/docs/atl/atl-event-handling-summary.md +++ b/docs/atl/atl-event-handling-summary.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL Event Handling Summary" title: "ATL Event Handling Summary" ms.date: "11/04/2016" helpviewer_keywords: ["event handling, implementing"] diff --git a/docs/atl/atl-module-classes.md b/docs/atl/atl-module-classes.md index 662309606c..4613d5af00 100644 --- a/docs/atl/atl-module-classes.md +++ b/docs/atl/atl-module-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL Module Classes" title: "ATL Module Classes" ms.date: "11/04/2016" helpviewer_keywords: ["CComModule class, what's changed", "ATL, module classes", "module classes"] diff --git a/docs/atl/atl-registry-component-registrar.md b/docs/atl/atl-registry-component-registrar.md index fc8dd475b3..6fc68ca1fc 100644 --- a/docs/atl/atl-registry-component-registrar.md +++ b/docs/atl/atl-registry-component-registrar.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL Registry Component (Registrar)" title: "ATL Registry Component (Registrar)" ms.date: "11/04/2016" helpviewer_keywords: ["scripting, registry scripting", "ATL, registry", "registrar scripts [ATL]", "registry, accessing", "ATL Registrar", "scripts, Registrar scripts", "registry, Registrar"] diff --git a/docs/atl/atl-services.md b/docs/atl/atl-services.md index 35b7105972..4acde07ca7 100644 --- a/docs/atl/atl-services.md +++ b/docs/atl/atl-services.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL Services" title: "ATL Services" ms.date: "11/04/2016" helpviewer_keywords: ["CServiceModule class", "COM objects, ATL", "services, ATL", "ATL services"] diff --git a/docs/atl/atl-support-for-dhtml-controls.md b/docs/atl/atl-support-for-dhtml-controls.md index 612ee901f9..eca0e2fe0b 100644 --- a/docs/atl/atl-support-for-dhtml-controls.md +++ b/docs/atl/atl-support-for-dhtml-controls.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL Support for DHTML Controls" title: "ATL Support for DHTML Controls" ms.date: "11/04/2016" helpviewer_keywords: ["HTML controls, ATL support", "DHTML controls, ATL support", "DHTML controls"] diff --git a/docs/atl/atl-utilities-reference.md b/docs/atl/atl-utilities-reference.md index ea0f7d0e1a..d903e4dbab 100644 --- a/docs/atl/atl-utilities-reference.md +++ b/docs/atl/atl-utilities-reference.md @@ -1,91 +1,89 @@ --- -title: "ATL Utilities Reference" -ms.date: "11/04/2016" -ms.assetid: dd8a2888-34f4-461e-9bf4-834218f9b95b +title: "ATL utilities reference" +description: "Learn more about: ATL utilities reference" +ms.date: 11/04/2016 --- -# ATL Utilities Reference +# ATL utilities reference ATL provides code for manipulating paths and URLs in the form of [CPathT](../atl/reference/cpatht-class.md) and [CUrl](../atl/reference/curl-class.md). A thread pool, [CThreadPool](../atl/reference/cthreadpool-class.md), can be used in your applications. This code can be found in atlpath.h and atlutil.h. -### Classes +## Classes -||| -|-|-| -|[CPathT Class](../atl/reference/cpatht-class.md)|This class represents a path.| -|[CDebugReportHook Class](../atl/reference/cdebugreporthook-class.md)|Use this class to send debug reports to a named pipe.| -|[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.| -|[CNoWorkerThread Class](../atl/reference/cnoworkerthread-class.md)|Use this class as the argument for the `MonitorClass` template parameter to cache classes if you want to disable dynamic cache maintenance.| -|[CThreadPool Class](../atl/reference/cthreadpool-class.md)|This class provides a pool of worker threads that process a queue of work items.| -|[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.| -|[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.| +| Name | Description | +|--|--| +| [CPathT class](../atl/reference/cpatht-class.md) | This class represents a path. | +| [CDebugReportHook class](../atl/reference/cdebugreporthook-class.md) | Use this class to send debug reports to a named pipe. | +| [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. | +| [CNoWorkerThread class](../atl/reference/cnoworkerthread-class.md) | Use this class as the argument for the `MonitorClass` template parameter to cache classes if you want to disable dynamic cache maintenance. | +| [CThreadPool class](../atl/reference/cthreadpool-class.md) | This class provides a pool of worker threads that process a queue of work items. | +| [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. | +| [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. | -### Typedefs +## Typedefs -||| -|-|-| -|[CPath](../atl/reference/atl-typedefs.md#cpath)|A specialization of [CPathT](../atl/reference/cpatht-class.md) using `CString`.| -|[CPathA](../atl/reference/atl-typedefs.md#cpatha)|A specialization of [CPathT](../atl/reference/cpatht-class.md) using `CStringA`.| -|[CPathW](../atl/reference/atl-typedefs.md#cpathw)|A specialization of [CPathT](../atl/reference/cpatht-class.md) using `CStringW`.| -|[ATL_URL_PORT](../atl/reference/atl-typedefs.md#atl_url_port)|The type used by [CUrl](../atl/reference/curl-class.md) for specifying a port number.| +| Name | Description | +|--|--| +| [CPath](../atl/reference/atl-typedefs.md#cpath) | A specialization of [CPathT](../atl/reference/cpatht-class.md) using `CString`. | +| [CPathA](../atl/reference/atl-typedefs.md#cpatha) | A specialization of [CPathT](../atl/reference/cpatht-class.md) using `CStringA`. | +| [CPathW](../atl/reference/atl-typedefs.md#cpathw) | A specialization of [CPathT](../atl/reference/cpatht-class.md) using `CStringW`. | +| [ATL_URL_PORT](../atl/reference/atl-typedefs.md#atl_url_port) | The type used by [CUrl](../atl/reference/curl-class.md) for specifying a port number. | -### Enums +## Enums -||| -|-|-| -|[ATL_URL_SCHEME](../atl/reference/atl-url-scheme-enum.md)|The members of this enumeration provide constants for the schemes understood by [CUrl](../atl/reference/curl-class.md).| +| Name | Description | +|--|--| +| [ATL_URL_SCHEME](../atl/reference/atl-url-scheme-enum.md) | The members of this enumeration provide constants for the schemes understood by [CUrl](../atl/reference/curl-class.md). | -### Functions +## Functions -||| -|-|-| -|[AtlCanonicalizeUrl](../atl/reference/atl-http-utility-functions.md#atlcanonicalizeurl)|Call this function to canonicalize a URL, which includes converting unsafe characters and spaces into escape sequences.| -|[AtlCombineUrl](../atl/reference/atl-http-utility-functions.md#atlcombineurl)|Call this function to combine a base URL and a relative URL into a single, canonical URL.| -|[AtlEscapeUrl](../atl/reference/atl-http-utility-functions.md#atlescapeurl)|Call this function to convert all unsafe characters to escape sequences.| -|[AtlGetDefaultUrlPort](../atl/reference/atl-http-utility-functions.md#atlgetdefaulturlport)|Call this function to get the default port number associated with a particular internet protocol or scheme.| -|[AtlHexValue](../atl/reference/atl-text-encoding-functions.md#atlhexvalue)|Call this function to get the numeric value of a hexadecimal digit.| -|[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::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).| -|[ATLPath::Canonicalize](../atl/reference/atl-path-functions.md#canonicalize)|This function is an overloaded wrapper for [PathCanonicalize](/windows/win32/api/shlwapi/nf-shlwapi-pathcanonicalizew).| -|[ATLPath::Combine](../atl/reference/atl-path-functions.md#combine)|This function is an overloaded wrapper for [PathCombine](/windows/win32/api/shlwapi/nf-shlwapi-pathcombinew).| -|[ATLPath::CommonPrefix](../atl/reference/atl-path-functions.md#commonprefix)|This function is an overloaded wrapper for [PathCommonPrefix](/windows/win32/api/shlwapi/nf-shlwapi-pathcommonprefixw).| -|[ATLPath::CompactPath](../atl/reference/atl-path-functions.md#compactpath)|This function is an overloaded wrapper for [PathCompactPath](/windows/win32/api/shlwapi/nf-shlwapi-pathcompactpathw).| -|[ATLPath::CompactPathEx](../atl/reference/atl-path-functions.md#compactpathex)|This function is an overloaded wrapper for [PathCompactPathEx](/windows/win32/api/shlwapi/nf-shlwapi-pathcompactpathexw).| -|[ATLPath::FileExists](../atl/reference/atl-path-functions.md#fileexists)|This function is an overloaded wrapper for [PathFileExists](/windows/win32/api/shlwapi/nf-shlwapi-pathfileexistsw).| -|[ATLPath::FindExtension](../atl/reference/atl-path-functions.md#findextension)|This function is an overloaded wrapper for [PathFindExtension](/windows/win32/api/shlwapi/nf-shlwapi-pathfindextensionw).| -|[ATLPath::FindFileName](../atl/reference/atl-path-functions.md#findfilename)|This function is an overloaded wrapper for [PathFindFileName](/windows/win32/api/shlwapi/nf-shlwapi-pathfindfilenamew).| -|[ATLPath::GetDriveNumber](../atl/reference/atl-path-functions.md#getdrivenumber)|This function is an overloaded wrapper for [PathGetDriveNumber](/windows/win32/api/shlwapi/nf-shlwapi-pathgetdrivenumberw).| -|[ATLPath::IsDirectory](../atl/reference/atl-path-functions.md#isdirectory)|This function is an overloaded wrapper for [PathIsDirectory](/windows/win32/api/shlwapi/nf-shlwapi-pathisdirectoryw).| -|[ATLPath::IsFileSpec](../atl/reference/atl-path-functions.md#isfilespec)|This function is an overloaded wrapper for [PathIsFileSpec](/windows/win32/api/shlwapi/nf-shlwapi-pathisfilespecw).| -|[ATLPath::IsPrefix](../atl/reference/atl-path-functions.md#isprefix)|This function is an overloaded wrapper for [PathIsPrefix](/windows/win32/api/shlwapi/nf-shlwapi-pathisprefixw).| -|[ATLPath::IsRelative](../atl/reference/atl-path-functions.md#isrelative)|This function is an overloaded wrapper for [PathIsRelative](/windows/win32/api/shlwapi/nf-shlwapi-pathisrelativew).| -|[ATLPath::IsRoot](../atl/reference/atl-path-functions.md#isroot)|This function is an overloaded wrapper for [PathIsRoot](/windows/win32/api/shlwapi/nf-shlwapi-pathisrootw).| -|[ATLPath::IsSameRoot](../atl/reference/atl-path-functions.md#issameroot)|This function is an overloaded wrapper for [PathIsSameRoot](/windows/win32/api/shlwapi/nf-shlwapi-pathissamerootw).| -|[ATLPath::IsUNC](../atl/reference/atl-path-functions.md#isunc)|This function is an overloaded wrapper for [PathIsUNC](/windows/win32/api/shlwapi/nf-shlwapi-pathisuncw).| -|[ATLPath::IsUNCServer](../atl/reference/atl-path-functions.md#isuncserver)|This function is an overloaded wrapper for [PathIsUNCServer](/windows/win32/api/shlwapi/nf-shlwapi-pathisuncserverw).| -|[ATLPath::IsUNCServerShare](../atl/reference/atl-path-functions.md#isuncservershare)|This function is an overloaded wrapper for [PathIsUNCServerShare](/windows/win32/api/shlwapi/nf-shlwapi-pathisuncserversharew).| -|[ATLPath::MakePretty](../atl/reference/atl-path-functions.md#makepretty)|This function is an overloaded wrapper for [PathMakePretty](/windows/win32/api/shlwapi/nf-shlwapi-pathmakeprettyw).| -|[ATLPath::MatchSpec](../atl/reference/atl-path-functions.md#matchspec)|This function is an overloaded wrapper for [PathMatchSpec](/windows/win32/api/shlwapi/nf-shlwapi-pathmatchspecw).| -|[ATLPath::QuoteSpaces](../atl/reference/atl-path-functions.md#quotespaces)|This function is an overloaded wrapper for [PathQuoteSpaces](/windows/win32/api/shlwapi/nf-shlwapi-pathquotespacesw).| -|[ATLPath::RelativePathTo](../atl/reference/atl-path-functions.md#relativepathto)|This function is an overloaded wrapper for [PathRelativePathTo](/windows/win32/api/shlwapi/nf-shlwapi-pathrelativepathtow).| -|[ATLPath::RemoveArgs](../atl/reference/atl-path-functions.md#removeargs)|This function is an overloaded wrapper for [PathRemoveArgs](/windows/win32/api/shlwapi/nf-shlwapi-pathremoveargsw).| -|[ATLPath::RemoveBackslash](../atl/reference/atl-path-functions.md#removebackslash)|This function is an overloaded wrapper for [PathRemoveBackslash](/windows/win32/api/shlwapi/nf-shlwapi-pathremovebackslashw).| -|[ATLPath::RemoveBlanks](../atl/reference/atl-path-functions.md#removeblanks)|This function is an overloaded wrapper for [PathRemoveBlanks](/windows/win32/api/shlwapi/nf-shlwapi-pathremoveblanksw).| -|[ATLPath::RemoveExtension](../atl/reference/atl-path-functions.md#removeextension)|This function is an overloaded wrapper for [PathRemoveExtension](/windows/win32/api/shlwapi/nf-shlwapi-pathremoveextensionw).| -|[ATLPath::RemoveFileSpec](../atl/reference/atl-path-functions.md#removefilespec)|This function is an overloaded wrapper for [PathRemoveFileSpec](/windows/win32/api/shlwapi/nf-shlwapi-pathremovefilespecw).| -|[ATLPath::RenameExtension](../atl/reference/atl-path-functions.md#renameextension)|This function is an overloaded wrapper for [PathRenameExtension](/windows/win32/api/shlwapi/nf-shlwapi-pathrenameextensionw).| -|[ATLPath::SkipRoot](../atl/reference/atl-path-functions.md#skiproot)|This function is an overloaded wrapper for [PathSkipRoot](/windows/win32/api/shlwapi/nf-shlwapi-pathskiprootw).| -|[ATLPath::StripPath](../atl/reference/atl-path-functions.md#strippath)|This function is an overloaded wrapper for [PathStripPath](/windows/win32/api/shlwapi/nf-shlwapi-pathstrippathw).| -|[ATLPath::StripToRoot](../atl/reference/atl-path-functions.md#striptoroot)|This function is an overloaded wrapper for [PathStripToRoot](/windows/win32/api/shlwapi/nf-shlwapi-pathstriptorootw).| -|[ATLPath::UnquoteSpaces](../atl/reference/atl-path-functions.md#unquotespaces)|This function is an overloaded wrapper for [PathUnquoteSpaces](/windows/win32/api/shlwapi/nf-shlwapi-pathunquotespacesw).| +| Name | Description | +|--|--| +| [AtlCanonicalizeUrl](../atl/reference/atl-http-utility-functions.md#atlcanonicalizeurl) | Call this function to canonicalize a URL, which includes converting unsafe characters and spaces into escape sequences. | +| [AtlCombineUrl](../atl/reference/atl-http-utility-functions.md#atlcombineurl) | Call this function to combine a base URL and a relative URL into a single, canonical URL. | +| [AtlEscapeUrl](../atl/reference/atl-http-utility-functions.md#atlescapeurl) | Call this function to convert all unsafe characters to escape sequences. | +| [AtlGetDefaultUrlPort](../atl/reference/atl-http-utility-functions.md#atlgetdefaulturlport) | Call this function to get the default port number associated with a particular internet protocol or scheme. | +| [AtlHexValue](../atl/reference/atl-text-encoding-functions.md#atlhexvalue) | Call this function to get the numeric value of a hexadecimal digit. | +| [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/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). | +| [ATLPath::Canonicalize](../atl/reference/atl-path-functions.md#canonicalize) | This function is an overloaded wrapper for [PathCanonicalize](/windows/win32/api/shlwapi/nf-shlwapi-pathcanonicalizew). | +| [ATLPath::Combine](../atl/reference/atl-path-functions.md#combine) | This function is an overloaded wrapper for [PathCombine](/windows/win32/api/shlwapi/nf-shlwapi-pathcombinew). | +| [ATLPath::CommonPrefix](../atl/reference/atl-path-functions.md#commonprefix) | This function is an overloaded wrapper for [PathCommonPrefix](/windows/win32/api/shlwapi/nf-shlwapi-pathcommonprefixw). | +| [ATLPath::CompactPath](../atl/reference/atl-path-functions.md#compactpath) | This function is an overloaded wrapper for [PathCompactPath](/windows/win32/api/shlwapi/nf-shlwapi-pathcompactpathw). | +| [ATLPath::CompactPathEx](../atl/reference/atl-path-functions.md#compactpathex) | This function is an overloaded wrapper for [PathCompactPathEx](/windows/win32/api/shlwapi/nf-shlwapi-pathcompactpathexw). | +| [ATLPath::FileExists](../atl/reference/atl-path-functions.md#fileexists) | This function is an overloaded wrapper for [PathFileExists](/windows/win32/api/shlwapi/nf-shlwapi-pathfileexistsw). | +| [ATLPath::FindExtension](../atl/reference/atl-path-functions.md#findextension) | This function is an overloaded wrapper for [PathFindExtension](/windows/win32/api/shlwapi/nf-shlwapi-pathfindextensionw). | +| [ATLPath::FindFileName](../atl/reference/atl-path-functions.md#findfilename) | This function is an overloaded wrapper for [PathFindFileName](/windows/win32/api/shlwapi/nf-shlwapi-pathfindfilenamew). | +| [ATLPath::GetDriveNumber](../atl/reference/atl-path-functions.md#getdrivenumber) | This function is an overloaded wrapper for [PathGetDriveNumber](/windows/win32/api/shlwapi/nf-shlwapi-pathgetdrivenumberw). | +| [ATLPath::IsDirectory](../atl/reference/atl-path-functions.md#isdirectory) | This function is an overloaded wrapper for [PathIsDirectory](/windows/win32/api/shlwapi/nf-shlwapi-pathisdirectoryw). | +| [ATLPath::IsFileSpec](../atl/reference/atl-path-functions.md#isfilespec) | This function is an overloaded wrapper for [PathIsFileSpec](/windows/win32/api/shlwapi/nf-shlwapi-pathisfilespecw). | +| [ATLPath::IsPrefix](../atl/reference/atl-path-functions.md#isprefix) | This function is an overloaded wrapper for [PathIsPrefix](/windows/win32/api/shlwapi/nf-shlwapi-pathisprefixw). | +| [ATLPath::IsRelative](../atl/reference/atl-path-functions.md#isrelative) | This function is an overloaded wrapper for [PathIsRelative](/windows/win32/api/shlwapi/nf-shlwapi-pathisrelativew). | +| [ATLPath::IsRoot](../atl/reference/atl-path-functions.md#isroot) | This function is an overloaded wrapper for [PathIsRoot](/windows/win32/api/shlwapi/nf-shlwapi-pathisrootw). | +| [ATLPath::IsSameRoot](../atl/reference/atl-path-functions.md#issameroot) | This function is an overloaded wrapper for [PathIsSameRoot](/windows/win32/api/shlwapi/nf-shlwapi-pathissamerootw). | +| [ATLPath::IsUNC](../atl/reference/atl-path-functions.md#isunc) | This function is an overloaded wrapper for [PathIsUNC](/windows/win32/api/shlwapi/nf-shlwapi-pathisuncw). | +| [ATLPath::IsUNCServer](../atl/reference/atl-path-functions.md#isuncserver) | This function is an overloaded wrapper for [PathIsUNCServer](/windows/win32/api/shlwapi/nf-shlwapi-pathisuncserverw). | +| [ATLPath::IsUNCServerShare](../atl/reference/atl-path-functions.md#isuncservershare) | This function is an overloaded wrapper for [PathIsUNCServerShare](/windows/win32/api/shlwapi/nf-shlwapi-pathisuncserversharew). | +| [ATLPath::MakePretty](../atl/reference/atl-path-functions.md#makepretty) | This function is an overloaded wrapper for [PathMakePretty](/windows/win32/api/shlwapi/nf-shlwapi-pathmakeprettyw). | +| [ATLPath::MatchSpec](../atl/reference/atl-path-functions.md#matchspec) | This function is an overloaded wrapper for [PathMatchSpec](/windows/win32/api/shlwapi/nf-shlwapi-pathmatchspecw). | +| [ATLPath::QuoteSpaces](../atl/reference/atl-path-functions.md#quotespaces) | This function is an overloaded wrapper for [PathQuoteSpaces](/windows/win32/api/shlwapi/nf-shlwapi-pathquotespacesw). | +| [ATLPath::RelativePathTo](../atl/reference/atl-path-functions.md#relativepathto) | This function is an overloaded wrapper for [PathRelativePathTo](/windows/win32/api/shlwapi/nf-shlwapi-pathrelativepathtow). | +| [ATLPath::RemoveArgs](../atl/reference/atl-path-functions.md#removeargs) | This function is an overloaded wrapper for [PathRemoveArgs](/windows/win32/api/shlwapi/nf-shlwapi-pathremoveargsw). | +| [ATLPath::RemoveBackslash](../atl/reference/atl-path-functions.md#removebackslash) | This function is an overloaded wrapper for [PathRemoveBackslash](/windows/win32/api/shlwapi/nf-shlwapi-pathremovebackslashw). | +| [ATLPath::RemoveBlanks](../atl/reference/atl-path-functions.md#removeblanks) | This function is an overloaded wrapper for [PathRemoveBlanks](/windows/win32/api/shlwapi/nf-shlwapi-pathremoveblanksw). | +| [ATLPath::RemoveExtension](../atl/reference/atl-path-functions.md#removeextension) | This function is an overloaded wrapper for [PathRemoveExtension](/windows/win32/api/shlwapi/nf-shlwapi-pathremoveextensionw). | +| [ATLPath::RemoveFileSpec](../atl/reference/atl-path-functions.md#removefilespec) | This function is an overloaded wrapper for [PathRemoveFileSpec](/windows/win32/api/shlwapi/nf-shlwapi-pathremovefilespecw). | +| [ATLPath::RenameExtension](../atl/reference/atl-path-functions.md#renameextension) | This function is an overloaded wrapper for [PathRenameExtension](/windows/win32/api/shlwapi/nf-shlwapi-pathrenameextensionw). | +| [ATLPath::SkipRoot](../atl/reference/atl-path-functions.md#skiproot) | This function is an overloaded wrapper for [PathSkipRoot](/windows/win32/api/shlwapi/nf-shlwapi-pathskiprootw). | +| [ATLPath::StripPath](../atl/reference/atl-path-functions.md#strippath) | This function is an overloaded wrapper for [PathStripPath](/windows/win32/api/shlwapi/nf-shlwapi-pathstrippathw). | +| [ATLPath::StripToRoot](../atl/reference/atl-path-functions.md#striptoroot) | This function is an overloaded wrapper for [PathStripToRoot](/windows/win32/api/shlwapi/nf-shlwapi-pathstriptorootw). | +| [ATLPath::UnquoteSpaces](../atl/reference/atl-path-functions.md#unquotespaces) | This function is an overloaded wrapper for [PathUnquoteSpaces](/windows/win32/api/shlwapi/nf-shlwapi-pathunquotespacesw). | ## See also -[Concepts](../atl/active-template-library-atl-concepts.md)
-[ATL COM Desktop Components](../atl/atl-com-desktop-components.md) +[Concepts](../atl/active-template-library-atl-concepts.md)\ +[ATL COM desktop components](../atl/atl-com-desktop-components.md) diff --git a/docs/atl/atl-window-classes.md b/docs/atl/atl-window-classes.md index ba9f1581bc..bf9968a031 100644 --- a/docs/atl/atl-window-classes.md +++ b/docs/atl/atl-window-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL Window Classes" title: "ATL Window Classes" ms.date: "11/04/2016" helpviewer_keywords: ["ATL, windows", "windows [C++], subclassing", "windows [C++], superclassing", "windows [C++], ATL", "subclassing ATL window classes", "superclassing", "superclassing, ATL"] diff --git a/docs/atl/benefits-and-tradeoffs-of-the-method-used-to-link-to-the-crt.md b/docs/atl/benefits-and-tradeoffs-of-the-method-used-to-link-to-the-crt.md index 74f7c7ba94..d84c7e8e63 100644 --- a/docs/atl/benefits-and-tradeoffs-of-the-method-used-to-link-to-the-crt.md +++ b/docs/atl/benefits-and-tradeoffs-of-the-method-used-to-link-to-the-crt.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Benefits and Tradeoffs of the Method Used to Link to the CRT" title: "Benefits and Tradeoffs of the Method Used to Link to the CRT" ms.date: "05/06/2019" helpviewer_keywords: ["_ATL_MIN_CRT macro"] diff --git a/docs/atl/building-and-testing-the-atl-project.md b/docs/atl/building-and-testing-the-atl-project.md index d3339460f5..d5920c6e59 100644 --- a/docs/atl/building-and-testing-the-atl-project.md +++ b/docs/atl/building-and-testing-the-atl-project.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Building and Testing the ATL Project" title: "Building and Testing the ATL Project" ms.date: "11/04/2016" helpviewer_keywords: ["composite controls, building and testing the project", "composite controls, containers for"] ms.assetid: 5c1541f8-f6cb-4c22-bd22-c66bcfbaa077 +ms.topic: concept-article --- # Building and Testing the ATL Project diff --git a/docs/atl/calling-cpp-code-from-dhtml.md b/docs/atl/calling-cpp-code-from-dhtml.md index 6076a5b4cc..a5d05fe09e 100644 --- a/docs/atl/calling-cpp-code-from-dhtml.md +++ b/docs/atl/calling-cpp-code-from-dhtml.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Calling C++ Code from DHTML" title: "Calling C++ Code from DHTML" ms.date: "11/04/2016" helpviewer_keywords: ["DHTML, calling C++ code from"] ms.assetid: 37329acd-4c22-40ca-a85a-b7480748f75f +ms.topic: concept-article --- # Calling C++ Code from DHTML diff --git a/docs/atl/catlservicemodulet-handler-function.md b/docs/atl/catlservicemodulet-handler-function.md index 57221734e1..a2da13bec8 100644 --- a/docs/atl/catlservicemodulet-handler-function.md +++ b/docs/atl/catlservicemodulet-handler-function.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAtlServiceModuleT::Handler Function" title: "CAtlServiceModuleT::Handler Function" ms.date: "11/04/2016" helpviewer_keywords: ["Handler method"] diff --git a/docs/atl/catlservicemodulet-run-function.md b/docs/atl/catlservicemodulet-run-function.md index 874515b205..9471ee390a 100644 --- a/docs/atl/catlservicemodulet-run-function.md +++ b/docs/atl/catlservicemodulet-run-function.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAtlServiceModuleT::Run Function" title: "CAtlServiceModuleT::Run Function" ms.date: "11/04/2016" helpviewer_keywords: ["ATL services, security"] diff --git a/docs/atl/catlservicemodulet-servicemain-function.md b/docs/atl/catlservicemodulet-servicemain-function.md index df9815a77d..f3cfffa7fd 100644 --- a/docs/atl/catlservicemodulet-servicemain-function.md +++ b/docs/atl/catlservicemodulet-servicemain-function.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAtlServiceModuleT::ServiceMain Function" title: "CAtlServiceModuleT::ServiceMain Function" ms.date: "11/04/2016" helpviewer_keywords: ["ServiceMain method"] diff --git a/docs/atl/catlservicemodulet-start-function.md b/docs/atl/catlservicemodulet-start-function.md index e097dd6df0..920857413d 100644 --- a/docs/atl/catlservicemodulet-start-function.md +++ b/docs/atl/catlservicemodulet-start-function.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAtlServiceModuleT::Start Function" title: "CAtlServiceModuleT::Start Function" ms.date: "11/04/2016" helpviewer_keywords: ["Start method"] diff --git a/docs/atl/changing-the-default-class-factory-and-aggregation-model.md b/docs/atl/changing-the-default-class-factory-and-aggregation-model.md index 2beb7ceea4..78b9ca1c8a 100644 --- a/docs/atl/changing-the-default-class-factory-and-aggregation-model.md +++ b/docs/atl/changing-the-default-class-factory-and-aggregation-model.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Changing the Default Class Factory and Aggregation Model" title: "Changing the Default Class Factory and Aggregation Model" ms.date: "11/04/2016" helpviewer_keywords: ["CComClassFactory class, making the default", "aggregation [C++], using ATL", "aggregation [C++], aggregation models", "defaults [C++], aggregation model in ATL", "default class factory", "class factories, changing default", "CComCoClass class, default class factory and aggregation model", "default class factory, ATL", "defaults [C++], class factory"] ms.assetid: 6e040e95-0f38-4839-8a8b-c9800dd47e8c +ms.topic: concept-article --- # Changing the Default Class Factory and Aggregation Model 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 2a82dd5ee0..2ed4a960e6 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 @@ -1,9 +1,11 @@ --- +description: "Learn more about: Changing the Drawing Code (ATL Tutorial, Part 4)" title: "Changing the Drawing Code (ATL Tutorial, Part 4)" ms.custom: "get-started-article" ms.date: "09/26/2018" helpviewer_keywords: ["_ATL_MIN_CRT macro"] ms.assetid: 08ff14e8-aa49-4139-a110-5d071939cf1e +ms.topic: tutorial --- # Changing the Drawing Code (ATL Tutorial, Part 4) @@ -150,7 +152,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/class-factories-classes.md b/docs/atl/class-factories-classes.md index 3ece2e4af1..15bda12d38 100644 --- a/docs/atl/class-factories-classes.md +++ b/docs/atl/class-factories-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Class Factories Classes" title: " ATL Class Factories Classes" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/class-information-classes.md b/docs/atl/class-information-classes.md index f14f672583..4f4b3f3158 100644 --- a/docs/atl/class-information-classes.md +++ b/docs/atl/class-information-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Class Information Classes" title: "Class Information Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/codesnippet/CPP/atl-collection-classes_1.cpp b/docs/atl/codesnippet/CPP/atl-collection-classes_1.cpp index 876ad2f58c..baa1deb220 100644 --- a/docs/atl/codesnippet/CPP/atl-collection-classes_1.cpp +++ b/docs/atl/codesnippet/CPP/atl-collection-classes_1.cpp @@ -29,7 +29,7 @@ class MyTraits : public CElementTraits< MyData > return true; else return false; - }; + } }; void DoAtlCustomTraitsList() diff --git a/docs/atl/collection-classes.md b/docs/atl/collection-classes.md index 376ec684e2..0545b6d29b 100644 --- a/docs/atl/collection-classes.md +++ b/docs/atl/collection-classes.md @@ -1,5 +1,6 @@ --- -title: "ATL Collection Classes" +description: "Learn more about: Collection Classes" +title: "Collection classes in ATL" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["collection classes"] @@ -79,7 +80,7 @@ The following classes provide support for arrays, lists, maps, and also traits m ## Related Articles -[ATL Collection Classes](../atl/atl-collection-classes.md) +[ATL collection class overview](../atl/atl-collection-classes.md) ## See also diff --git a/docs/atl/com-modules-classes.md b/docs/atl/com-modules-classes.md index 2cbad8fb7e..4c4671f123 100644 --- a/docs/atl/com-modules-classes.md +++ b/docs/atl/com-modules-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: COM Modules Classes" title: "COM Modules Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/commandhandler.md b/docs/atl/commandhandler.md index cf7a2fcd68..6ad29accfb 100644 --- a/docs/atl/commandhandler.md +++ b/docs/atl/commandhandler.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CommandHandler" title: "CommandHandler" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/composite-controls-classes.md b/docs/atl/composite-controls-classes.md index 4b612e947d..0e45651cc8 100644 --- a/docs/atl/composite-controls-classes.md +++ b/docs/atl/composite-controls-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Composite Controls Classes" title: "Composite Controls Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/connection-points-classes.md b/docs/atl/connection-points-classes.md index f510c8eae9..52b73a0103 100644 --- a/docs/atl/connection-points-classes.md +++ b/docs/atl/connection-points-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Connection Points Classes" title: "Connection Points Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/control-containment-classes.md b/docs/atl/control-containment-classes.md index 169acafc7f..1446101b69 100644 --- a/docs/atl/control-containment-classes.md +++ b/docs/atl/control-containment-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Control Containment Classes" title: "Control Containment Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" @@ -19,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/controls-general-support-classes.md b/docs/atl/controls-general-support-classes.md index 8172840341..fdb016140e 100644 --- a/docs/atl/controls-general-support-classes.md +++ b/docs/atl/controls-general-support-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Controls: General Support Classes" title: "ATL Controls: General Support Classes" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/creating-an-aggregated-object.md b/docs/atl/creating-an-aggregated-object.md index bad5079b3a..f0bc8d88b2 100644 --- a/docs/atl/creating-an-aggregated-object.md +++ b/docs/atl/creating-an-aggregated-object.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Creating an Aggregated Object" title: "Creating an Aggregated Object" ms.date: "11/04/2016" helpviewer_keywords: ["aggregation [C++], creating aggregated objects", "aggregate objects [C++], creating"] ms.assetid: fc29d7aa-fd53-4276-9c2f-37379f71b179 +ms.topic: how-to --- # Creating an Aggregated Object diff --git a/docs/atl/creating-an-atl-dhtml-control.md b/docs/atl/creating-an-atl-dhtml-control.md index fa81467ac6..1831d58d0b 100644 --- a/docs/atl/creating-an-atl-dhtml-control.md +++ b/docs/atl/creating-an-atl-dhtml-control.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Creating an ATL DHTML Control" title: "Creating an ATL DHTML Control" ms.date: "11/04/2016" helpviewer_keywords: ["HTML controls, creating", "DHTML controls", "DHTML controls, creating"] ms.assetid: 1d8f0ede-7d8b-4959-976e-b4d0e2a87f5a +ms.topic: how-to --- # Creating an ATL DHTML Control diff --git a/docs/atl/creating-registrar-scripts.md b/docs/atl/creating-registrar-scripts.md index 2ee26a8fbc..d9d281b53a 100644 --- a/docs/atl/creating-registrar-scripts.md +++ b/docs/atl/creating-registrar-scripts.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Creating Registrar scripts" title: "Creating scripts for ATL Registrar" ms.date: "05/14/2014" helpviewer_keywords: ["scripting, registry scripting", "ATL, registry", "registrar scripts [ATL]", "scripts, Registrar scripts", "scripts, creating"] ms.assetid: cbd5024b-8061-4a71-be65-7fee90374a35 +ms.topic: concept-article --- # Creating Registrar scripts diff --git a/docs/atl/creating-the-project-atl-tutorial-part-1.md b/docs/atl/creating-the-project-atl-tutorial-part-1.md index 273f619ece..b8a01fd225 100644 --- a/docs/atl/creating-the-project-atl-tutorial-part-1.md +++ b/docs/atl/creating-the-project-atl-tutorial-part-1.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Creating the Project (ATL Tutorial, Part 1)" title: "Creating the Project (ATL Tutorial, Part 1)" ms.custom: "get-started-article" ms.date: "08/19/2019" ms.assetid: f6b727d1-390a-4b27-b82f-daadcd9fc059 +ms.topic: tutorial --- # Creating the Project (ATL Tutorial, Part 1) @@ -44,7 +46,7 @@ This tutorial walks you step-by-step through a non-attributed ATL project that c Visual Studio will create the project by generating several files. You can view these files in **Solution Explorer** by expanding the `Polygon` object. The files are listed below. -::: moniker range="<=vs-2017" +::: moniker range="<=msvc-150" |File|Description| |----------|-----------------| @@ -60,7 +62,7 @@ Visual Studio will create the project by generating several files. You can view ::: moniker-end -::: moniker range=">=vs-2019" +::: moniker range=">=msvc-160" |File|Description| |----------|-----------------| diff --git a/docs/atl/data-transfer-classes.md b/docs/atl/data-transfer-classes.md index a6bcf766ad..67709a809c 100644 --- a/docs/atl/data-transfer-classes.md +++ b/docs/atl/data-transfer-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Data Transfer Classes" title: "Data Transfer Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/data-types-classes.md b/docs/atl/data-types-classes.md index a89b474781..85d986bad8 100644 --- a/docs/atl/data-types-classes.md +++ b/docs/atl/data-types-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Data Types Classes" title: "Data Types Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/dcomcnfg.md b/docs/atl/dcomcnfg.md index 4ebd1c3d8d..0a0468d6a5 100644 --- a/docs/atl/dcomcnfg.md +++ b/docs/atl/dcomcnfg.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: DCOMCNFG" title: "DCOMCNFG" ms.date: "11/04/2016" helpviewer_keywords: ["DCOMCNFG utility", "DCOM, configuring in ATL"] diff --git a/docs/atl/debugging-and-exceptions-classes.md b/docs/atl/debugging-and-exceptions-classes.md index e32ebc13f9..703972808b 100644 --- a/docs/atl/debugging-and-exceptions-classes.md +++ b/docs/atl/debugging-and-exceptions-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Debugging and Exceptions Classes" title: "Debugging and Exceptions Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/debugging-tips.md b/docs/atl/debugging-tips.md index 8f33d4d9ff..5fcdee636d 100644 --- a/docs/atl/debugging-tips.md +++ b/docs/atl/debugging-tips.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Debugging Tips" title: "Debugging Tips (ATL)" ms.date: "11/04/2016" helpviewer_keywords: ["ATL, debugging", "services, debugging"] ms.assetid: 48c60244-d0ce-4466-85fa-6fa65fcfe86c +ms.topic: concept-article --- # Debugging Tips diff --git a/docs/atl/design-principles-for-collection-and-enumerator-interfaces.md b/docs/atl/design-principles-for-collection-and-enumerator-interfaces.md index 609edc37cc..e75179b64e 100644 --- a/docs/atl/design-principles-for-collection-and-enumerator-interfaces.md +++ b/docs/atl/design-principles-for-collection-and-enumerator-interfaces.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Design Principles for Collection and Enumerator Interfaces" title: "Designing Collection and Enumerator Interfaces (ATL)" ms.date: "11/04/2016" helpviewer_keywords: ["enumerator interfaces", "collection interfaces"] ms.assetid: ea19a39e-6333-41a1-be62-5435c236640e +ms.topic: concept-article --- # Design Principles for Collection and Enumerator Interfaces diff --git a/docs/atl/displaying-assertions.md b/docs/atl/displaying-assertions.md index c051bef184..8587c3eb40 100644 --- a/docs/atl/displaying-assertions.md +++ b/docs/atl/displaying-assertions.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Displaying Assertions" title: "Displaying Assertions" ms.date: "05/05/2019" helpviewer_keywords: ["debugging [ATL], displaying assertions", "assertions, displaying", "debugging assertions", "assertions, debugging"] ms.assetid: fa353fe8-4656-4384-a5d2-8866bc977f06 +ms.topic: concept-article --- # Displaying Assertions diff --git a/docs/atl/dual-interfaces-and-atl.md b/docs/atl/dual-interfaces-and-atl.md index 579b4eb081..2039cb3e12 100644 --- a/docs/atl/dual-interfaces-and-atl.md +++ b/docs/atl/dual-interfaces-and-atl.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Dual Interfaces and ATL" title: "Dual Interfaces and ATL" ms.date: "11/04/2016" helpviewer_keywords: ["COM, and ATL", "ATL, dual interfaces", "dual interfaces, about dual interfaces"] diff --git a/docs/atl/dual-interfaces-and-events.md b/docs/atl/dual-interfaces-and-events.md index e6f9af8b2a..a0a520b396 100644 --- a/docs/atl/dual-interfaces-and-events.md +++ b/docs/atl/dual-interfaces-and-events.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Dual Interfaces and Events" title: "Dual Interfaces and Events" ms.date: "11/04/2016" helpviewer_keywords: ["events [C++], dual interfaces", "dual interfaces, events"] diff --git a/docs/atl/dual-interfaces-classes.md b/docs/atl/dual-interfaces-classes.md index 08c1e543c5..b675565549 100644 --- a/docs/atl/dual-interfaces-classes.md +++ b/docs/atl/dual-interfaces-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Dual Interfaces Classes" title: "Dual Interfaces Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/enumerators-and-collections-classes.md b/docs/atl/enumerators-and-collections-classes.md index 2a383e12a1..6ccef203df 100644 --- a/docs/atl/enumerators-and-collections-classes.md +++ b/docs/atl/enumerators-and-collections-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Enumerators and Collections Classes" title: "Enumerators and Collections Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/error-information-classes.md b/docs/atl/error-information-classes.md index 45367457f8..5a2a987385 100644 --- a/docs/atl/error-information-classes.md +++ b/docs/atl/error-information-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Error Information Classes" title: "Error Information Classe (ATL)" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/event-handling-and-atl.md b/docs/atl/event-handling-and-atl.md index eca0b20a5c..649b68042c 100644 --- a/docs/atl/event-handling-and-atl.md +++ b/docs/atl/event-handling-and-atl.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Event Handling and ATL" title: "Event Handling and ATL" ms.date: "11/04/2016" helpviewer_keywords: ["event handling, about event handling"] diff --git a/docs/atl/event-handling-principles.md b/docs/atl/event-handling-principles.md index e6eb057965..41c766a5e7 100644 --- a/docs/atl/event-handling-principles.md +++ b/docs/atl/event-handling-principles.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Event Handling Principles" title: "Event Handling Principles (ATL)" ms.date: "11/04/2016" helpviewer_keywords: ["event handling, implementing", "event handling, advising event sources", "interfaces, event and event sink", "dual interfaces, event interfaces", "event handling, dual event interfaces"] diff --git a/docs/atl/example-implementing-a-property-page.md b/docs/atl/example-implementing-a-property-page.md index 4943243c88..6e7ee66751 100644 --- a/docs/atl/example-implementing-a-property-page.md +++ b/docs/atl/example-implementing-a-property-page.md @@ -1,18 +1,20 @@ --- +description: "Learn more about: Example: Implementing a Property Page" title: "Implementing a Property Page (ATL)" ms.date: "05/09/2019" helpviewer_keywords: ["property pages, implementing"] ms.assetid: c30b67fe-ce08-4249-ae29-f3060fa8d61e +ms.topic: how-to --- # Example: Implementing a Property Page -::: moniker range="vs-2019" +::: moniker range=">=msvc-160" The ATL Property Page wizard is not available in Visual Studio 2019 and later. ::: moniker-end -::: moniker range="<=vs-2017" +::: moniker range="<=msvc-150" This example shows how to build a property page that displays (and allows you to change) properties of the [Document Classes](../mfc/document-classes.md) interface. @@ -59,7 +61,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. @@ -126,7 +128,7 @@ When users want to apply their changes to the objects, the property page site wi To display this page, you need to create a simple helper object. The helper object will provide a method that simplifies the `OleCreatePropertyFrame` API for displaying a single page connected to a single object. This helper will be designed so that it can be used from Visual Basic. -Use the [Add Class dialog box](../ide/add-class-dialog-box.md) and the [ATL Simple Object Wizard](../atl/reference/atl-simple-object-wizard.md) to generate a new class and use `Helper` as its short name. Once created, add a method as shown in the table below. +Use the [Add Class dialog box](../ide/adding-a-class-visual-cpp.md#add-class-dialog-box) and the [ATL Simple Object Wizard](../atl/reference/atl-simple-object-wizard.md) to generate a new class and use `Helper` as its short name. Once created, add a method as shown in the table below. |Item|Value| |----------|-----------| diff --git a/docs/atl/file-handling-classes.md b/docs/atl/file-handling-classes.md index e885c8ed64..22602083ec 100644 --- a/docs/atl/file-handling-classes.md +++ b/docs/atl/file-handling-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: File Handling Classes" title: "File Handling Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/fundamentals-of-atl-com-objects.md b/docs/atl/fundamentals-of-atl-com-objects.md index 9e1f771156..afc7adb434 100644 --- a/docs/atl/fundamentals-of-atl-com-objects.md +++ b/docs/atl/fundamentals-of-atl-com-objects.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Fundamentals of ATL COM Objects" title: "Fundamentals of ATL COM Objects" ms.date: "11/19/2018" helpviewer_keywords: ["COM, and ATL", "ATL, COM", "ATL COM objects", "COM objects, ATL"] @@ -8,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 34a2306c55..7ac825b837 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 @@ -1,8 +1,10 @@ --- +description: "Learn more about: Identifying the Elements of the DHTML Control Project" title: "Identifying the Elements of the DHTML Control Project" ms.date: "11/19/2018" helpviewer_keywords: ["HTML controls, ATL support", "DHTML controls, ATL support"] ms.assetid: b627547a-3768-4346-9900-4b7a21fb8e27 +ms.topic: concept-article --- # Identifying the Elements of the DHTML Control Project @@ -18,7 +20,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. @@ -39,7 +41,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-a-dialog-box.md b/docs/atl/implementing-a-dialog-box.md index 3891be279b..c84428bea5 100644 --- a/docs/atl/implementing-a-dialog-box.md +++ b/docs/atl/implementing-a-dialog-box.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Implementing a Dialog Box" title: "Implementing a Dialog Box" ms.date: "11/04/2016" helpviewer_keywords: ["CSimpleDialog class, implementing dialog boxes in ATL", "dialog boxes, ATL", "CAxDialogImpl class, implementing dialog boxes in ATL", "ATL, dialog boxes"] ms.assetid: 478525f2-aa6a-435a-b162-68fc8aa98a8e +ms.topic: how-to --- # Implementing a Dialog Box @@ -10,7 +12,7 @@ There are two ways to add a dialog box to your ATL project: use the ATL Dialog W ## Adding a Dialog Box with the ATL Dialog Wizard -In the [Add Class dialog box](../ide/add-class-dialog-box.md), select the ATL Dialog object to add a dialog box to your ATL project. Fill in the ATL Dialog Wizard as appropriate and click **Finish**. The wizard adds a class derived from [CAxDialogImpl](../atl/reference/caxdialogimpl-class.md) to your project. Open **Resource View** from the **View** menu, locate your dialog, and double-click it to open it in the resource editor. +In the [Add Class dialog box](../ide/adding-a-class-visual-cpp.md#add-class-dialog-box), select the ATL Dialog object to add a dialog box to your ATL project. Fill in the ATL Dialog Wizard as appropriate and click **Finish**. The wizard adds a class derived from [CAxDialogImpl](../atl/reference/caxdialogimpl-class.md) to your project. Open **Resource View** from the **View** menu, locate your dialog, and double-click it to open it in the resource editor. > [!NOTE] > If your dialog box is derived from `CAxDialogImpl`, it can host both ActiveX and Windows controls. If you don't want the overhead of ActiveX control support in your dialog box class, use [CSimpleDialog](../atl/reference/csimpledialog-class.md) or [CDialogImpl](../atl/reference/cdialogimpl-class.md) instead. diff --git a/docs/atl/implementing-a-dual-interface.md b/docs/atl/implementing-a-dual-interface.md index ca04fc66bd..6abd84d51b 100644 --- a/docs/atl/implementing-a-dual-interface.md +++ b/docs/atl/implementing-a-dual-interface.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Implementing a Dual Interface" title: "Implementing a Dual Interface (ATL)" ms.date: "11/04/2016" helpviewer_keywords: ["IDispatchImpl class, implementing dual interfaces", "dual interfaces, implementing"] ms.assetid: d1da3633-b445-4dcd-8a0a-3efdafada3ea +ms.topic: concept-article --- # Implementing a Dual Interface @@ -22,7 +24,7 @@ To use this class: ## ATL Simple Object Wizard -If you want to create a new interface and a new class to implement it, you can use the [ATL Add Class dialog box](../ide/add-class-dialog-box.md), and then the [ATL Simple Object Wizard](../atl/reference/atl-simple-object-wizard.md). +If you want to create a new interface and a new class to implement it, you can use the [ATL Add Class dialog box](../ide/adding-a-class-visual-cpp.md#add-class-dialog-box), and then the [ATL Simple Object Wizard](../atl/reference/atl-simple-object-wizard.md). ## Implement Interface Wizard diff --git a/docs/atl/implementing-a-window-with-cwindowimpl.md b/docs/atl/implementing-a-window-with-cwindowimpl.md index 5cbe34ac7a..be0f590b83 100644 --- a/docs/atl/implementing-a-window-with-cwindowimpl.md +++ b/docs/atl/implementing-a-window-with-cwindowimpl.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Implementing a Window with CWindowImpl" title: "Implementing a Window with CWindowImpl" ms.date: "11/04/2016" helpviewer_keywords: ["ATL, windows", "windows [C++], subclassing", "windows [C++], superclassing", "windows [C++], ATL", "subclassing ATL window classes", "superclassing, ATL"] ms.assetid: 3fc40550-f1d6-4702-8b7c-4cf682b6a855 +ms.topic: how-to --- # Implementing a Window with CWindowImpl @@ -21,7 +23,7 @@ To implement a window, derive a class from `CWindowImpl`. In your derived class, > [!NOTE] > `CWindowImpl` passes NULL to the `DECLARE_WND_CLASS` macro, which means ATL will generate a Windows class name. To specify your own name, pass a string to DECLARE_WND_CLASS in your `CWindowImpl`-derived class. -## Example +## Example: Implement a window Following is an example of a class that implements a window based on a new Windows class: @@ -38,7 +40,7 @@ The [DECLARE_WND_SUPERCLASS](reference/window-class-macros.md#declare_wnd_superc When you use DECLARE_WND_SUPERCLASS, a new Windows class will be registered. This new class will be the same as the existing class you specify, but will replace the window procedure with `CWindowImpl::WindowProc` (or with your function that overrides this method). -## Example +## Example: Superclass the Edit class Following is an example of a class that superclasses the standard Edit class: diff --git a/docs/atl/implementing-a-window.md b/docs/atl/implementing-a-window.md index 4c17826598..dbe42c3fbc 100644 --- a/docs/atl/implementing-a-window.md +++ b/docs/atl/implementing-a-window.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Implementing a Window" title: "Implementing a Window (ATL)" ms.date: "11/04/2016" helpviewer_keywords: ["ATL, windows", "CWindowImpl class, using", "windows [C++], implementing in ATL"] ms.assetid: eb1ce8d6-72f9-4894-aae7-e60a61665628 +ms.topic: concept-article --- # Implementing a Window diff --git a/docs/atl/implementing-an-stl-based-collection.md b/docs/atl/implementing-an-stl-based-collection.md index f686100a78..761ef740d1 100644 --- a/docs/atl/implementing-an-stl-based-collection.md +++ b/docs/atl/implementing-an-stl-based-collection.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Implementing a C++ Standard Library-Based Collection" title: "Implementing a C++ Standard Library-Based Collection" ms.date: "11/04/2016" helpviewer_keywords: ["ICollectionOnSTLImpl interface"] ms.assetid: 6d49f819-1957-4813-b074-3f12c494d8ca +ms.topic: how-to --- # Implementing a C++ Standard Library-Based Collection diff --git a/docs/atl/implementing-ccomobject-ccomaggobject-and-ccompolyobject.md b/docs/atl/implementing-ccomobject-ccomaggobject-and-ccompolyobject.md index 562e357eb9..e7a6428fba 100644 --- a/docs/atl/implementing-ccomobject-ccomaggobject-and-ccompolyobject.md +++ b/docs/atl/implementing-ccomobject-ccomaggobject-and-ccompolyobject.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Implementing CComObject, CComAggObject, and CComPolyObject" title: "Implementing CComObject, CComAggObject, and CComPolyObject" ms.date: "11/04/2016" helpviewer_keywords: ["CComPolyObject class, implementing", "CreateInstance method", "CComAggObject class", "CComObject class, implementing"] ms.assetid: 5aabe938-104d-492e-9c41-9f7fb1c62098 +ms.topic: concept-article --- # Implementing CComObject, CComAggObject, and CComPolyObject diff --git a/docs/atl/implementing-ccomobjectrootex.md b/docs/atl/implementing-ccomobjectrootex.md index 2d85e51114..5dc0fc19ca 100644 --- a/docs/atl/implementing-ccomobjectrootex.md +++ b/docs/atl/implementing-ccomobjectrootex.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Implementing CComObjectRootEx" title: "Implementing CComObjectRootEx" ms.date: "11/04/2016" helpviewer_keywords: ["CComObjectRoot class, implementing", "CComObjectRootEx class"] ms.assetid: 79630c44-f2df-4e9e-b730-400a0ebfbd2b +ms.topic: concept-article --- # Implementing CComObjectRootEx diff --git a/docs/atl/implementing-property-pages.md b/docs/atl/implementing-property-pages.md index eae6114c64..d9e3b0942c 100644 --- a/docs/atl/implementing-property-pages.md +++ b/docs/atl/implementing-property-pages.md @@ -1,26 +1,28 @@ --- +description: "Learn more about: Implementing Property Pages" title: "Implementing Property Pages" ms.date: "11/04/2016" helpviewer_keywords: ["IPropertyPage2 class", "IPropertyPage class", "property pages, implementing"] ms.assetid: 62f29440-33a7-40eb-a1ef-3634c95f640c +ms.topic: how-to --- # Implementing Property Pages -::: moniker range="vs-2019" +::: moniker range=">=msvc-160" The ATL Property Page wizard is not available in Visual Studio 2019 and later. ::: moniker-end -::: moniker range="<=vs-2017" +::: moniker range="<=msvc-150" -Property pages are COM objects that implement the `IPropertyPage` or `IPropertyPage2` interface. ATL provides support for implementing property pages through the [ATL Property Page Wizard](../atl/reference/atl-property-page-wizard.md) in the [Add Class dialog box](../ide/add-class-dialog-box.md). +Property pages are COM objects that implement the `IPropertyPage` or `IPropertyPage2` interface. ATL provides support for implementing property pages through the [ATL Property Page Wizard](../atl/reference/atl-property-page-wizard.md) in the [Add Class dialog box](../ide/adding-a-class-visual-cpp.md#add-class-dialog-box). To create a property page using ATL: - Create or open an ATL Dynamic-link library (DLL) server project. -- Open the [Add Class dialog box](../ide/add-class-dialog-box.md) and select **ATL Property Page**. +- Open the [Add Class dialog box](../ide/adding-a-class-visual-cpp.md#add-class-dialog-box) and select **ATL Property Page**. - Make sure your property page is apartment threaded (since it has a user interface). diff --git a/docs/atl/implementing-the-event-handling-interface.md b/docs/atl/implementing-the-event-handling-interface.md index a03b89112e..3442039a73 100644 --- a/docs/atl/implementing-the-event-handling-interface.md +++ b/docs/atl/implementing-the-event-handling-interface.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Implementing the Event Handling Interface" title: "Implementing the Event Handling Interface" ms.date: "11/04/2016" helpviewer_keywords: ["ATL, event handling", "event handling, ATL", "interfaces, event and event sink"] ms.assetid: eb2a5b33-88dc-4ce3-bee0-c5c38ea050d7 +ms.topic: concept-article --- # Implementing the Event Handling Interface diff --git a/docs/atl/inserting-a-composite-control.md b/docs/atl/inserting-a-composite-control.md index f3a858cd59..ad1f4f6dc2 100644 --- a/docs/atl/inserting-a-composite-control.md +++ b/docs/atl/inserting-a-composite-control.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Inserting a Composite Control" title: "Inserting a Composite Control" ms.date: "11/04/2016" helpviewer_keywords: ["composite controls, inserting with ATL Object Wizard", "composite controls", "ATL Control Wizard"] ms.assetid: f10b1927-9fc6-40a7-ac29-efdac70584fe +ms.topic: how-to --- # Inserting a Composite Control diff --git a/docs/atl/interface-pointers-classes.md b/docs/atl/interface-pointers-classes.md index 8b42ea1f04..d54f0ad4aa 100644 --- a/docs/atl/interface-pointers-classes.md +++ b/docs/atl/interface-pointers-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Interface Pointers Classes" title: "Interface Pointers Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/interfaces-atl.md b/docs/atl/interfaces-atl.md index 348538be30..93422d3cd2 100644 --- a/docs/atl/interfaces-atl.md +++ b/docs/atl/interfaces-atl.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Interfaces (ATL)" title: "Interfaces (ATL)" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/introduction-to-atl-window-classes.md b/docs/atl/introduction-to-atl-window-classes.md index c67170245b..5ae3fc8c8a 100644 --- a/docs/atl/introduction-to-atl-window-classes.md +++ b/docs/atl/introduction-to-atl-window-classes.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Introduction to ATL Window Classes" title: "Introduction to ATL Window Classes" ms.date: "11/04/2016" helpviewer_keywords: ["window classes"] ms.assetid: 503efc2c-a269-495d-97cf-3fb300d52f3d +ms.topic: concept-article --- # Introduction to ATL Window Classes diff --git a/docs/atl/introduction-to-atl.md b/docs/atl/introduction-to-atl.md index 293759d724..cccfc97391 100644 --- a/docs/atl/introduction-to-atl.md +++ b/docs/atl/introduction-to-atl.md @@ -1,9 +1,11 @@ --- +description: "Learn more about: Introduction to ATL" title: "Introduction to ATL" ms.custom: "index-page" ms.date: "11/04/2016" helpviewer_keywords: ["COM objects, creating in ATL", "ATL"] ms.assetid: 77f565e8-c4ec-4a80-af4b-7278fcfe5c98 +ms.topic: concept-article --- # Introduction to ATL diff --git a/docs/atl/introduction-to-com-and-atl.md b/docs/atl/introduction-to-com-and-atl.md index 6dceae0574..57e25904bc 100644 --- a/docs/atl/introduction-to-com-and-atl.md +++ b/docs/atl/introduction-to-com-and-atl.md @@ -1,9 +1,11 @@ --- +description: "Learn more about: Introduction to COM and ATL" title: "Introduction to COM and ATL" ms.custom: "index-page" ms.date: "11/04/2016" helpviewer_keywords: ["COM, and ATL", "ATL, COM", "COM objects, ATL"] ms.assetid: 35d6ae9c-abbb-42f0-9344-33f3c19ac3ce +ms.topic: concept-article --- # Introduction to COM and ATL diff --git a/docs/atl/introduction-to-com.md b/docs/atl/introduction-to-com.md index f219e8f343..c44fc4f065 100644 --- a/docs/atl/introduction-to-com.md +++ b/docs/atl/introduction-to-com.md @@ -1,9 +1,11 @@ --- +description: "Learn more about: Introduction to COM" title: "Introduction to COM" ms.custom: "index-page" ms.date: "11/04/2016" helpviewer_keywords: ["COM"] ms.assetid: 120735d9-db71-4ad3-a730-ce576ea2354e +ms.topic: concept-article --- # Introduction to COM diff --git a/docs/atl/invoking-scripts.md b/docs/atl/invoking-scripts.md index 3bd6109da3..2d33947181 100644 --- a/docs/atl/invoking-scripts.md +++ b/docs/atl/invoking-scripts.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Invoking Scripts" title: "Invoking Scripts (ATL)" ms.date: "11/04/2016" helpviewer_keywords: ["StringRegister method", "scripts, invoking registry in ATL"] ms.assetid: eabd41ee-586b-4266-9e92-5aaad04b73a4 +ms.topic: concept-article --- # Invoking Scripts diff --git a/docs/atl/iunknown-implementation-classes.md b/docs/atl/iunknown-implementation-classes.md index 27fbd9e48a..7721fad35c 100644 --- a/docs/atl/iunknown-implementation-classes.md +++ b/docs/atl/iunknown-implementation-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IUnknown Implementation Classes" title: "IUnknown Implementation Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/iunknown.md b/docs/atl/iunknown.md index 19cbfe61eb..ee1578aa31 100644 --- a/docs/atl/iunknown.md +++ b/docs/atl/iunknown.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IUnknown" title: "IUnknown" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/linking-to-the-crt-in-your-atl-project.md b/docs/atl/linking-to-the-crt-in-your-atl-project.md index 7d4c3ad3d9..430134baa4 100644 --- a/docs/atl/linking-to-the-crt-in-your-atl-project.md +++ b/docs/atl/linking-to-the-crt-in-your-atl-project.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Linking to the CRT in Your ATL Project" title: "Linking to the CRT in Your ATL Project" ms.date: "11/04/2016" helpviewer_keywords: ["CRT, linking with ATL", "WinMainCRTStartup method", "DllMainCRTStartup method", "wWinMainCRTStartup method", "ATL, C Run-Time library (CRT)"] ms.assetid: 650957ae-362c-4ecf-8b03-5d49138e8b5b +ms.topic: concept-article --- # Linking to the CRT in Your ATL Project diff --git a/docs/atl/marshaling.md b/docs/atl/marshaling.md index 4eef2ca8b6..1f5c52b2be 100644 --- a/docs/atl/marshaling.md +++ b/docs/atl/marshaling.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Marshaling" title: "Marshaling" ms.date: "11/04/2016" helpviewer_keywords: ["marshaling, COM interop", "marshaling", "COM interfaces, marshaling"] ms.assetid: 40644b0a-1106-4fc8-9dfb-9bee9915d825 +ms.topic: concept-article --- # Marshaling diff --git a/docs/atl/memory-management-classes.md b/docs/atl/memory-management-classes.md index ac60898602..680e61f19d 100644 --- a/docs/atl/memory-management-classes.md +++ b/docs/atl/memory-management-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Memory Management Classes" title: "Memory Management Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/message-handler-functions.md b/docs/atl/message-handler-functions.md index ff00f7ba27..a37dc85d18 100644 --- a/docs/atl/message-handler-functions.md +++ b/docs/atl/message-handler-functions.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Message Handler Functions" title: "Message Handler Functions" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/message-maps-atl.md b/docs/atl/message-maps-atl.md index 3e50f39c4b..0ab8a690a8 100644 --- a/docs/atl/message-maps-atl.md +++ b/docs/atl/message-maps-atl.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Message Maps (ATL)" title: "Message Maps (ATL)" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/messagehandler.md b/docs/atl/messagehandler.md index 9614f5af80..4fcdaad53b 100644 --- a/docs/atl/messagehandler.md +++ b/docs/atl/messagehandler.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: MessageHandler" title: "MessageHandler" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/mmc-snap-in-classes.md b/docs/atl/mmc-snap-in-classes.md index ae959fa479..140e10dc5e 100644 --- a/docs/atl/mmc-snap-in-classes.md +++ b/docs/atl/mmc-snap-in-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: MMC Snap-In Classes" title: "MMC Snap-In Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/modifying-the-atl-dhtml-control.md b/docs/atl/modifying-the-atl-dhtml-control.md index 1d7f40ca6a..3e77a536a1 100644 --- a/docs/atl/modifying-the-atl-dhtml-control.md +++ b/docs/atl/modifying-the-atl-dhtml-control.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Modifying the ATL DHTML Control" title: "Modifying the ATL DHTML Control" ms.date: "11/04/2016" helpviewer_keywords: ["HTML controls, modifying", "DHTML controls", "DHTML controls, modifying"] ms.assetid: c053f35f-8629-4600-9595-721f5956777a +ms.topic: how-to --- # Modifying the ATL DHTML Control diff --git a/docs/atl/modifying-the-atl-project.md b/docs/atl/modifying-the-atl-project.md index 3539311296..d9211d9776 100644 --- a/docs/atl/modifying-the-atl-project.md +++ b/docs/atl/modifying-the-atl-project.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Modifying the ATL Project" title: "Modifying the ATL Project" ms.date: "11/04/2016" helpviewer_keywords: ["controls [ATL], adding to composite controls", "Dialog editor, working with composite controls", "composite controls, adding controls"] ms.assetid: 59984518-748f-4b8b-875f-3e97d22d0b0f +ms.topic: concept-article --- # Modifying the ATL Project diff --git a/docs/atl/multiple-dual-interfaces.md b/docs/atl/multiple-dual-interfaces.md index e18301d513..99c4302524 100644 --- a/docs/atl/multiple-dual-interfaces.md +++ b/docs/atl/multiple-dual-interfaces.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Multiple Dual Interfaces" title: "Multiple Dual Interfaces" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/nonextensible-attribute.md b/docs/atl/nonextensible-attribute.md index cfd1a67af3..08a854a487 100644 --- a/docs/atl/nonextensible-attribute.md +++ b/docs/atl/nonextensible-attribute.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: nonextensible Attribute" title: "nonextensible Attribute" ms.date: "11/04/2016" helpviewer_keywords: ["nonextensible attribute", "dual interfaces, nonextensible attribute"] @@ -8,7 +9,7 @@ ms.assetid: 02a4a18b-ffd3-4d53-8fd1-feb1c05ad5ac If a dual interface will not be extended at run time (that is, you won't provide methods or properties via `IDispatch::Invoke` that are not available via the vtable), you should apply the **nonextensible** attribute to your interface definition. This attribute provides information to client languages (such as Visual Basic) that can be used to enable full code verification at compile time. If this attribute is not supplied, bugs may remain hidden in the client code until run time. -For more information on the **nonextensible** attribute and an example, see [nonextensible](../windows/nonextensible.md). +For more information on the **nonextensible** attribute and an example, see [nonextensible](../windows/attributes/nonextensible.md). ## See also diff --git a/docs/atl/notifyhandler.md b/docs/atl/notifyhandler.md index 7201748b84..adb1d4a0db 100644 --- a/docs/atl/notifyhandler.md +++ b/docs/atl/notifyhandler.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: NotifyHandler" title: "NotifyHandler" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/object-safety-classes.md b/docs/atl/object-safety-classes.md index cbab7caee1..8021fd778b 100644 --- a/docs/atl/object-safety-classes.md +++ b/docs/atl/object-safety-classes.md @@ -1,5 +1,6 @@ --- -title: "Object Safety Classes (ATL)| Microsoft Docs" +description: "Learn more about: Object Safety Classes" +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/persistence-classes.md b/docs/atl/persistence-classes.md index 137648b4d7..bce7966eb7 100644 --- a/docs/atl/persistence-classes.md +++ b/docs/atl/persistence-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Persistence Classes" title: "Persistence Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/programming-with-atl-and-c-run-time-code.md b/docs/atl/programming-with-atl-and-c-run-time-code.md index 3910c92a76..66c4ade4f2 100644 --- a/docs/atl/programming-with-atl-and-c-run-time-code.md +++ b/docs/atl/programming-with-atl-and-c-run-time-code.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Programming with ATL and C Run-Time Code" title: "Programming with ATL and C Run-Time Code" ms.date: "11/04/2016" helpviewer_keywords: ["ATL_MIN_CRT macro", "CRT, using with ATL", "_ATL_MIN_CRT macro", "ATL, C Run-Time library (CRT)"] ms.assetid: 20f03b66-1eb7-4add-84a2-6047db0911eb +ms.topic: concept-article --- # Programming with ATL and C Run-Time Code diff --git a/docs/atl/programming-with-ccombstr-atl.md b/docs/atl/programming-with-ccombstr-atl.md index 2def91a492..31f7ee2d37 100644 --- a/docs/atl/programming-with-ccombstr-atl.md +++ b/docs/atl/programming-with-ccombstr-atl.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Programming with CComBSTR (ATL)" title: "Programming with CComBSTR (ATL)" ms.date: "11/04/2016" helpviewer_keywords: ["CComBSTR class, programming with", "Unicode, using CComBSTR [ATL]"] ms.assetid: d3bd0851-d132-4be9-9c4c-6ccba17acb2b +ms.topic: concept-article --- # Programming with CComBSTR (ATL) @@ -26,9 +28,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/properties-and-property-pages-classes.md b/docs/atl/properties-and-property-pages-classes.md index 95021de1ae..17e8307bb0 100644 --- a/docs/atl/properties-and-property-pages-classes.md +++ b/docs/atl/properties-and-property-pages-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Properties and Property Pages Classes" title: "Properties and Property Pages Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" 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 64752423e7..faf66529f1 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 @@ -1,8 +1,10 @@ --- +description: "Learn more about: Putting the Control on a Web Page (ATL Tutorial, Part 7)" title: "Putting the Control on a Web Page (ATL Tutorial, Part 7)" ms.custom: "get-started-article" ms.date: "05/06/2019" ms.assetid: 50dc4c95-c95b-4006-b88a-9826f7bdb222 +ms.topic: tutorial --- # Putting the Control on a Web Page (ATL Tutorial, Part 7) @@ -14,30 +16,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 1a9387bfd7..3d982e0e93 100644 --- a/docs/atl/queryinterface.md +++ b/docs/atl/queryinterface.md @@ -1,19 +1,20 @@ --- +description: "Learn more about: QueryInterface" title: "QueryInterface" ms.date: "11/04/2016" 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/recommendations-for-choosing-between-atl-and-mfc.md b/docs/atl/recommendations-for-choosing-between-atl-and-mfc.md index 38dac128db..2fc4145a2b 100644 --- a/docs/atl/recommendations-for-choosing-between-atl-and-mfc.md +++ b/docs/atl/recommendations-for-choosing-between-atl-and-mfc.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Recommendations for Choosing Between ATL and MFC" title: "Recommendations for Choosing Between ATL and MFC" ms.date: "11/04/2016" helpviewer_keywords: ["MFC, ATL support", "ATL, vs. MFC"] diff --git a/docs/atl/reference-counting.md b/docs/atl/reference-counting.md index 8103d2557c..db71a9ca66 100644 --- a/docs/atl/reference-counting.md +++ b/docs/atl/reference-counting.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Reference Counting" title: "Reference Counting (ATL)" ms.date: "11/04/2016" helpviewer_keywords: ["AddRef method [C++], reference counting", "reference counting", "AddRef method [C++]", "reference counts", "references, counting"] diff --git a/docs/atl/reference/adding-a-new-interface-in-an-atl-project.md b/docs/atl/reference/adding-a-new-interface-in-an-atl-project.md index 5f44e2cf41..f9b927b58c 100644 --- a/docs/atl/reference/adding-a-new-interface-in-an-atl-project.md +++ b/docs/atl/reference/adding-a-new-interface-in-an-atl-project.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Adding a New Interface in an ATL Project" title: "Adding a New Interface in an ATL Project" ms.date: "11/04/2016" f1_keywords: ["vc.appwiz.ATL.interface"] @@ -17,7 +18,7 @@ You can add a new interface to your control in one of two ways: manually or usin 1. On the shortcut menu, click **Add**, and then click **Implement Interface**. -1. Select the interfaces to implement in the [Implement Interface Wizard](../../ide/implement-interface-wizard.md). If the interface does not exist in any available typelib, then you must add it manually to the .idl file. +1. Select the interfaces to implement in the [Implement Interface Wizard](../../ide/implementing-an-interface-visual-cpp.md#implement-interface-wizard). If the interface does not exist in any available typelib, then you must add it manually to the .idl file. ## To add a new interface manually 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 26450d4049..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 @@ -1,19 +1,20 @@ --- +description: "Learn more about: Adding an ATL Active Server Page Component" title: "Adding an ATL Active Server Page Component" ms.date: "05/09/2019" ms.assetid: 7be2204c-6e58-4099-8892-001b848c8987 --- # Adding an ATL Active Server Page Component -::: moniker range="vs-2019" +::: moniker range=">=msvc-160" The ATL Active Server Pages component wizard is not available in Visual Studio 2019 and later. ::: moniker-end -::: moniker range="<=vs-2017" +::: moniker range="<=msvc-150" -To add an Active Template Library (ATL) object to your project, your project must have been created as an ATL COM application or as an MFC application that contains ATL support. You can use the [ATL Project Wizard](../../atl/reference/atl-project-wizard.md) to create an ATL application, you can select **Add ATL Support to MFC** from the [Add Class Dialog Box](../../ide/add-class-dialog-box.md) dialog box, or you can [add an ATL object to your MFC application](../../mfc/reference/adding-atl-support-to-your-mfc-project.md) to implement ATL support for an MFC application. +To add an Active Template Library (ATL) object to your project, your project must have been created as an ATL COM application or as an MFC application that contains ATL support. You can use the [ATL Project Wizard](../../atl/reference/atl-project-wizard.md) to create an ATL application, you can select **Add ATL Support to MFC** from the [Add Class Dialog Box](../../ide/adding-a-class-visual-cpp.md#add-class-dialog-box) dialog box, or you can [add an ATL object to your MFC application](../../mfc/reference/adding-atl-support-to-your-mfc-project.md) to implement ATL support for an MFC application. Active Server Pages components are part of the Internet Information Services architecture, which provides the following advanced Web development features: @@ -29,7 +30,7 @@ Active Server Pages components are part of the Internet Information Services arc 1. From the shortcut menu, click **Add**, and then click **Add Class**. -1. In the [Add Class](../../ide/add-class-dialog-box.md) dialog box, in the **Templates** pane, click **ATL Active Server Page Component**, and then click **Open** to display the [ATL Active Server Page Component Wizard](../../atl/reference/atl-active-server-page-component-wizard.md). +1. In the [Add Class](../../ide/adding-a-class-visual-cpp.md#add-class-dialog-box) dialog box, in the **Templates** pane, click **ATL Active Server Page Component**, and then click **Open** to display the [ATL Active Server Page Component Wizard](../../atl/reference/atl-active-server-page-component-wizard.md). ::: moniker-end 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 fa1ddf9744..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 @@ -1,17 +1,18 @@ --- +description: "Learn more about: Adding an ATL COM+ 1.0 Component" title: "Adding an ATL COM+ 1.0 Component" ms.date: "05/09/2019" ms.assetid: c6c95e64-9ee4-4a6e-8804-5930202ce1b9 --- # Adding an ATL COM+ 1.0 Component -::: moniker range="vs-2019" +::: moniker range=">=msvc-160" The ATL COM+ 1.0 Component wizard is not available in Visual Studio 2019 and later. ::: moniker-end -::: moniker range="<=vs-2017" +::: moniker range="<=msvc-150" This wizard adds an object to your project that supports COM+ 1.0 services, including transactions. @@ -21,7 +22,7 @@ This wizard adds an object to your project that supports COM+ 1.0 services, incl 1. On the shortcut menu, click **Add**, and then click **Add Class**. -1. In the [Add Class](../../ide/add-class-dialog-box.md) dialog box, in the **Templates** pane, click **ATL COM+ 1.0 Component**, and then click **Open** to display the [ATL COM+ 1.0 Component Wizard](../../atl/reference/atl-com-plus-1-0-component-wizard.md). +1. In the [Add Class](../../ide/adding-a-class-visual-cpp.md#add-class-dialog-box) dialog box, in the **Templates** pane, click **ATL COM+ 1.0 Component**, and then click **Open** to display the [ATL COM+ 1.0 Component Wizard](../../atl/reference/atl-com-plus-1-0-component-wizard.md). ## See also diff --git a/docs/atl/reference/adding-an-atl-control.md b/docs/atl/reference/adding-an-atl-control.md index 3fe29b55dd..c9a0174533 100644 --- a/docs/atl/reference/adding-an-atl-control.md +++ b/docs/atl/reference/adding-an-atl-control.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Adding an ATL Control" title: "Adding an ATL Control" ms.date: "11/04/2016" helpviewer_keywords: ["ATL projects, adding controls", "controls [ATL], adding to projects"] @@ -14,7 +15,7 @@ Use this wizard to add a user interface object to a project that supports interf 1. Click **Add** from the shortcut menu, and then click **Add Class**. -1. In the [Add Class](../../ide/add-class-dialog-box.md) dialog box, in the templates pane, click **ATL Control**, and then click **Add** to display the [ATL Control Wizard](../../atl/reference/atl-control-wizard.md). +1. In the [Add Class](../../ide/adding-a-class-visual-cpp.md#add-class-dialog-box) dialog box, in the templates pane, click **ATL Control**, and then click **Add** to display the [ATL Control Wizard](../../atl/reference/atl-control-wizard.md). Using the **ATL Control Wizard**, you can create one of three types of controls: diff --git a/docs/atl/reference/adding-an-atl-dialog-box.md b/docs/atl/reference/adding-an-atl-dialog-box.md index daebc2a397..928fd20430 100644 --- a/docs/atl/reference/adding-an-atl-dialog-box.md +++ b/docs/atl/reference/adding-an-atl-dialog-box.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Adding an ATL Dialog Box" title: "Adding an ATL Dialog Box" ms.date: "11/04/2016" helpviewer_keywords: ["ATL projects, adding dialog resources", "MFC dialog boxes, ATL dialogs", "dialog boxes, ATL"] @@ -19,7 +20,7 @@ By default, the ATL Dialog Wizard implements a dialog box derived from [CAxDialo 1. From [Class View](/visualstudio/ide/viewing-the-structure-of-code), right-click the project name and click **Add** from the shortcut menu. Click **Add Class**. -1. In the **Templates** pane of the [Add Class](../../ide/add-class-dialog-box.md) dialog box, click **ATL Dialog**. Click **Open** to display the [ATL Dialog Wizard](../../atl/reference/atl-dialog-wizard.md). +1. In the **Templates** pane of the [Add Class](../../ide/adding-a-class-visual-cpp.md#add-class-dialog-box) dialog box, click **ATL Dialog**. Click **Open** to display the [ATL Dialog Wizard](../../atl/reference/atl-dialog-wizard.md). For more information, see [Implementing a Dialog Box](../../atl/implementing-a-dialog-box.md). 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 762cdb75ea..52b1acc39a 100644 --- a/docs/atl/reference/adding-an-atl-ole-db-consumer.md +++ b/docs/atl/reference/adding-an-atl-ole-db-consumer.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Adding an ATL OLE DB Consumer" title: "Adding an ATL OLE DB Consumer" ms.date: "05/09/2019" helpviewer_keywords: ["ATL OLE DB consumers"] @@ -6,13 +7,13 @@ ms.assetid: f940a513-4e42-4148-b521-dd0d7dc89fa2 --- # Adding an ATL OLE DB Consumer -::: moniker range="vs-2019" +::: 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). ::: moniker-end -::: moniker range="<=vs-2017" +::: moniker range="<=msvc-150" Use this wizard to add an ATL OLE DB consumer to a project. An ATL OLE DB consumer consists of an OLE DB accessor class and data bindings necessary to access a data source. The project must have been created as an ATL COM application, or as an MFC or Win32 application that contains ATL support (which the ATL OLE DB Consumer Wizard adds automatically). 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 639998fa80..3aba76e606 100644 --- a/docs/atl/reference/adding-an-atl-ole-db-provider.md +++ b/docs/atl/reference/adding-an-atl-ole-db-provider.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Adding an ATL OLE DB Provider" title: "Adding an ATL OLE DB Provider" ms.date: "05/09/2019" helpviewer_keywords: ["OLE DB, adding ATL OLE DB provider to projects", "ATL projects, adding ATL OLE DB providers", "ATL OLE DB providers"] @@ -6,13 +7,13 @@ ms.assetid: 26fba1e3-880f-4bc6-90e5-2096a48a3a6c --- # Adding an ATL OLE DB Provider -::: moniker range="vs-2019" +::: moniker range=">=msvc-160" The ATL OLE DB Provider wizard is not available in Visual Studio 2019 and later. ::: moniker-end -::: moniker range="<=vs-2017" +::: moniker range="<=msvc-150" Use this wizard to add an ATL OLE DB provider to a project. An ATL OLE DB provider consists of a data source, session, command, and rowset classes. The project must have been created as an ATL COM application. diff --git a/docs/atl/reference/adding-an-atl-property-page.md b/docs/atl/reference/adding-an-atl-property-page.md index 088f895525..376b4875a7 100644 --- a/docs/atl/reference/adding-an-atl-property-page.md +++ b/docs/atl/reference/adding-an-atl-property-page.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Adding an ATL Property Page" title: "Adding an ATL Property Page" ms.date: "05/09/2019" helpviewer_keywords: ["property pages, adding", "ATL projects, adding property pages", "controls [ATL], property pages"] @@ -22,7 +23,7 @@ If you are adding a property page for a control, your control must support the [ 1. From the shortcut menu, click **Add** and then click **Add Class**. -1. In the [Add Class](../../ide/add-class-dialog-box.md) dialog box, in the **Templates** pane, click **ATL Property Page** and then click **Open** to display the [ATL Property Page Wizard](../../atl/reference/atl-property-page-wizard.md). +1. In the [Add Class](../../ide/adding-a-class-visual-cpp.md#add-class-dialog-box) dialog box, in the **Templates** pane, click **ATL Property Page** and then click **Open** to display the [ATL Property Page Wizard](../../atl/reference/atl-property-page-wizard.md). Once you create a property page for a control, you must provide the [PROP_PAGE](property-map-macros.md#prop_page) entry in the property map for the control. diff --git a/docs/atl/reference/adding-an-atl-simple-object.md b/docs/atl/reference/adding-an-atl-simple-object.md index 310606ba03..91e8e2ddac 100644 --- a/docs/atl/reference/adding-an-atl-simple-object.md +++ b/docs/atl/reference/adding-an-atl-simple-object.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Adding an ATL Simple Object" title: "Adding an ATL Simple Object" ms.date: "11/04/2016" f1_keywords: ["vc.codewiz.classes.adding.atl"] @@ -9,7 +10,7 @@ ms.assetid: 9c57d2ef-0447-4c84-8982-3304b8e49847 To add an ATL (Active Template Library) object to your project, your project must have been created as an ATL application or as an MFC application that contains ATL support. You can use the [ATL Project Wizard](../../atl/reference/atl-project-wizard.md) to create an ATL application, or [add an ATL object to your MFC application](../../mfc/reference/adding-atl-support-to-your-mfc-project.md) to implement ATL support for an MFC application. -You can define COM interfaces for your new ATL object when you first create it, or add them later by using the [Implement Interface](../../ide/implement-interface-wizard.md) command from the **Class View** shortcut menu. +You can define COM interfaces for your new ATL object when you first create it, or add them later by using the [Implement Interface](../../ide/implementing-an-interface-visual-cpp.md#implement-interface-wizard) command from the **Class View** shortcut menu. ## To add an ATL simple object to your ATL COM project @@ -17,7 +18,7 @@ You can define COM interfaces for your new ATL object when you first create it, 1. From the shortcut menu, click **Add**, and then click **Add Class**. -1. In the [Add Class](../../ide/add-class-dialog-box.md) dialog box, in the **Templates** pane, click **ATL Simple Object**, and then click **Open** to display the [ATL Simple Object Wizard](../../atl/reference/atl-simple-object-wizard.md). +1. In the [Add Class](../../ide/adding-a-class-visual-cpp.md#add-class-dialog-box) dialog box, in the **Templates** pane, click **ATL Simple Object**, and then click **Open** to display the [ATL Simple Object Wizard](../../atl/reference/atl-simple-object-wizard.md). 1. Set additional options for your project on the [Options](../../atl/reference/options-atl-simple-object-wizard.md) page of the **ATL Simple Object** wizard. diff --git a/docs/atl/reference/adding-objects-and-controls-to-an-atl-project.md b/docs/atl/reference/adding-objects-and-controls-to-an-atl-project.md index 79dcf0eb69..036b72dc54 100644 --- a/docs/atl/reference/adding-objects-and-controls-to-an-atl-project.md +++ b/docs/atl/reference/adding-objects-and-controls-to-an-atl-project.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Adding Objects and Controls to an ATL Project" title: "Adding Objects and Controls to an ATL Project" ms.date: "05/09/2019" f1_keywords: ["vc.appwiz.ATL.controls"] @@ -12,11 +13,15 @@ ms.assetid: c0adcbd0-07fe-4c55-a8fd-8c2c65ecdaad You can use one of the ATL code wizards to add an object or a control to your ATL- or MFC-based projects. For each COM object or control you add, the wizard generates .cpp and .h files, as well as an .rgs file for script-based registry support. The following ATL code wizards are available in Visual Studio: -|||| -|-|-|-| -|[ATL Simple Object](../../atl/reference/atl-simple-object-wizard.md)|[ATL Dialog](../../atl/reference/atl-dialog-wizard.md)|[ATL Control](../../atl/reference/atl-control-wizard.md)| -|[ATL Property Page](../../atl/reference/atl-property-page-wizard.md)|[ATL Active Server Page Component](../../atl/reference/atl-active-server-page-component-wizard.md)|[ATL OLE DB Consumer](../../atl/reference/atl-ole-db-consumer-wizard.md)| -|[Add ATL Support to MFC](../../mfc/reference/adding-atl-support-to-your-mfc-project.md)|[ATL COM+ 1.0 Component Wizard](../../atl/reference/atl-com-plus-1-0-component-wizard.md)|[ATL OLE DB Provider](../../atl/reference/atl-ole-db-provider-wizard.md)| +- [ATL Simple Object](../../atl/reference/atl-simple-object-wizard.md) +- [ATL Dialog](../../atl/reference/atl-dialog-wizard.md) +- [ATL Control](../../atl/reference/atl-control-wizard.md) +- [ATL Property Page](../../atl/reference/atl-property-page-wizard.md) +- [ATL Active Server Page Component](../../atl/reference/atl-active-server-page-component-wizard.md) +- [ATL OLE DB Consumer](../../atl/reference/atl-ole-db-consumer-wizard.md) +- [Add ATL Support to MFC](../../mfc/reference/adding-atl-support-to-your-mfc-project.md) +- [ATL COM+ 1.0 Component Wizard](../../atl/reference/atl-com-plus-1-0-component-wizard.md) +- [ATL OLE DB Provider](../../atl/reference/atl-ole-db-provider-wizard.md) > [!NOTE] > Before adding an ATL object to your project, you should review the details and requirements for the object in its related Help topics. @@ -25,7 +30,7 @@ You can use one of the ATL code wizards to add an object or a control to your AT 1. In **Solution Explorer**, right-click the project node and click **Add** from the shortcut menu. Click **Add Class**. - The [Add Class](../../ide/add-class-dialog-box.md) dialog box appears. + The [Add Class](../../ide/adding-a-class-visual-cpp.md#add-class-dialog-box) dialog box appears. 1. With the **ATL** folder selected in the **Categories** pane, select an object to insert from the **Templates** pane. Click **Open**. The code wizard for the selected object appears. diff --git a/docs/atl/reference/aggregation-and-class-factory-macros.md b/docs/atl/reference/aggregation-and-class-factory-macros.md index 93521129a0..b6dacd4282 100644 --- a/docs/atl/reference/aggregation-and-class-factory-macros.md +++ b/docs/atl/reference/aggregation-and-class-factory-macros.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Aggregation and Class Factory Macros" title: "Aggregation and Class Factory Macros" ms.date: 08/12/2020 f1_keywords: ["ATLCOM/ATL::DECLARE_AGGREGATABLE", "ATLCOM/ATL::DECLARE_CLASSFACTORY", "ATLCOM/ATL::DECLARE_CLASSFACTORY_EX", "ATLCOM/ATL::DECLARE_CLASSFACTORY_AUTO_THREAD", "ATLCOM/ATL::DECLARE_CLASSFACTORY_SINGLETON", "ATLCOM/ATL::DECLARE_GET_CONTROLLING_UNKNOWN", "ATLCOM/ATL::DECLARE_NOT_AGGREGATABLE", "ATLCOM/ATL::DECLARE_ONLY_AGGREGATABLE", "ATLCOM/ATL::DECLARE_POLY_AGGREGATABLE", "ATLCOM/ATL::DECLARE_PROTECT_FINAL_CONSTRUCT", "ATLCOM/ATL::DECLARE_VIEW_STATUS", "ATLDEF/ATL::DECLARE_AGGREGATABLE", "ATLDEF/ATL::DECLARE_CLASSFACTORY", "ATLDEF/ATL::DECLARE_CLASSFACTORY_EX", "ATLDEF/ATL::DECLARE_CLASSFACTORY_AUTO_THREAD", "ATLDEF/ATL::DECLARE_CLASSFACTORY_SINGLETON", "ATLDEF/ATL::DECLARE_GET_CONTROLLING_UNKNOWN", "ATLDEF/ATL::DECLARE_NOT_AGGREGATABLE", "ATLDEF/ATL::DECLARE_ONLY_AGGREGATABLE", "ATLDEF/ATL::DECLARE_POLY_AGGREGATABLE", "ATLDEF/ATL::DECLARE_PROTECT_FINAL_CONSTRUCT", "ATLDEF/ATL::DECLARE_VIEW_STATUS", "ATLCOM/DECLARE_AGGREGATABLE", "ATLCOM/DECLARE_CLASSFACTORY", "ATLCOM/DECLARE_CLASSFACTORY_EX", "ATLCOM/DECLARE_CLASSFACTORY_AUTO_THREAD", "ATLCOM/DECLARE_CLASSFACTORY_SINGLETON", "ATLCOM/DECLARE_GET_CONTROLLING_UNKNOWN", "ATLCOM/DECLARE_NOT_AGGREGATABLE", "ATLCOM/DECLARE_ONLY_AGGREGATABLE", "ATLCOM/DECLARE_POLY_AGGREGATABLE", "ATLCOM/DECLARE_PROTECT_FINAL_CONSTRUCT", "ATLCOM/DECLARE_VIEW_STATUS", "ATL::DECLARE_AGGREGATABLE", "ATL::DECLARE_CLASSFACTORY", "ATL::DECLARE_CLASSFACTORY_EX", "ATL::DECLARE_CLASSFACTORY_AUTO_THREAD", "ATL::DECLARE_CLASSFACTORY_SINGLETON", "ATL::DECLARE_GET_CONTROLLING_UNKNOWN", "ATL::DECLARE_NOT_AGGREGATABLE", "ATL::DECLARE_ONLY_AGGREGATABLE", "ATL::DECLARE_POLY_AGGREGATABLE", "ATL::DECLARE_PROTECT_FINAL_CONSTRUCT", "ATL::DECLARE_VIEW_STATUS", "DECLARE_AGGREGATABLE", "DECLARE_CLASSFACTORY", "DECLARE_CLASSFACTORY_EX", "DECLARE_CLASSFACTORY_AUTO_THREAD", "DECLARE_CLASSFACTORY_SINGLETON", "DECLARE_GET_CONTROLLING_UNKNOWN", "DECLARE_NOT_AGGREGATABLE", "DECLARE_ONLY_AGGREGATABLE", "DECLARE_POLY_AGGREGATABLE", "DECLARE_PROTECT_FINAL_CONSTRUCT", "DECLARE_VIEW_STATUS"] diff --git a/docs/atl/reference/appearance-atl-control-wizard.md b/docs/atl/reference/appearance-atl-control-wizard.md index 9bade2038d..5a28f5a572 100644 --- a/docs/atl/reference/appearance-atl-control-wizard.md +++ b/docs/atl/reference/appearance-atl-control-wizard.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Appearance, ATL Control Wizard" title: "Appearance, ATL Control Wizard" ms.date: "08/31/2018" f1_keywords: ["vc.codewiz.class.atl.control.misc"] diff --git a/docs/atl/reference/application-settings-atl-project-wizard.md b/docs/atl/reference/application-settings-atl-project-wizard.md index e22ac23913..03b0fade12 100644 --- a/docs/atl/reference/application-settings-atl-project-wizard.md +++ b/docs/atl/reference/application-settings-atl-project-wizard.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Application Settings, ATL Project Wizard" title: "Application Settings, ATL Project Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.appwiz.atl.com.appset"] diff --git a/docs/atl/reference/asp-atl-active-server-page-component-wizard.md b/docs/atl/reference/asp-atl-active-server-page-component-wizard.md index e2a93af9f1..efb54c5bbf 100644 --- a/docs/atl/reference/asp-atl-active-server-page-component-wizard.md +++ b/docs/atl/reference/asp-atl-active-server-page-component-wizard.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ASP, ATL Active Server Page Component Wizard" title: "ASP, ATL Active Server Page Component Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.codewiz.class.atl.asp.asp"] 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 dfcb2d2374..ceab8c73f9 100644 --- a/docs/atl/reference/atl-active-server-page-component-wizard.md +++ b/docs/atl/reference/atl-active-server-page-component-wizard.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL Active Server Page Component Wizard" title: "ATL Active Server Page Component Wizard" ms.date: "05/09/2019" helpviewer_keywords: ["ASP components, creating in ATL"] @@ -6,13 +7,13 @@ ms.assetid: 5a5cb904-dbbf-44ea-ad3d-2ddd14c1d3c5 --- # ATL Active Server Page Component Wizard -::: moniker range="vs-2019" +::: moniker range=">=msvc-160" This wizard is not available in Visual Studio 2019 and later. ::: moniker-end -::: moniker range="<=vs-2017" +::: moniker range="<=msvc-150" This wizard inserts into the project an Active Server Pages (ASP) component. The Microsoft Internet Information Services (IIS) uses ASP components as part of its enhanced Web page development architecture. @@ -60,7 +61,7 @@ Provides information for the C++ class created for the object. By default for nonattributed projects, any objects you add after you set this option are designated as attributed (the check box is selected). You can clear this box to add an object that does not use attributes. - See [Application Settings, ATL Project Wizard](../../atl/reference/application-settings-atl-project-wizard.md) and [Basic Mechanics of Attributes](../../windows/basic-mechanics-of-attributes.md) for more information. + See [Application Settings, ATL Project Wizard](../../atl/reference/application-settings-atl-project-wizard.md) and [Basic mechanics of attributes](../../windows/attributes/cpp-attributes-com-net.md#basic-mechanics-of-attributes) for more information. ### COM diff --git a/docs/atl/reference/atl-base-module70-structure.md b/docs/atl/reference/atl-base-module70-structure.md index 882799cae4..78cbd73876 100644 --- a/docs/atl/reference/atl-base-module70-structure.md +++ b/docs/atl/reference/atl-base-module70-structure.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: _ATL_BASE_MODULE70 Structure" title: "_ATL_BASE_MODULE70 Structure" ms.date: "11/04/2016" f1_keywords: ["ATL::_ATL_BASE_MODULE70", "ATL._ATL_BASE_MODULE70", "_ATL_BASE_MODULE70"] diff --git a/docs/atl/reference/atl-classes.md b/docs/atl/reference/atl-classes.md index c2609d4318..36a3ed3f0d 100644 --- a/docs/atl/reference/atl-classes.md +++ b/docs/atl/reference/atl-classes.md @@ -1,8 +1,8 @@ --- -title: "ATL classes and structs| Microsoft Docs" +description: "Learn more about: ATL classes and structs" +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 @@ -10,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-module70-structure.md b/docs/atl/reference/atl-com-module70-structure.md index 1bed0efc1d..3f37add4ec 100644 --- a/docs/atl/reference/atl-com-module70-structure.md +++ b/docs/atl/reference/atl-com-module70-structure.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: _ATL_COM_MODULE70 Structure" title: "_ATL_COM_MODULE70 Structure" ms.date: "11/04/2016" f1_keywords: ["ATL::_ATL_COM_MODULE70", "ATL._ATL_COM_MODULE70", "_ATL_COM_MODULE70"] 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 e5e5e3bafb..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 @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL COM+ 1.0 Component Wizard" title: "ATL COM+ 1.0 Component Wizard" ms.date: "05/08/2019" helpviewer_keywords: ["ATL projects, adding components"] @@ -6,13 +7,13 @@ ms.assetid: 11670681-8671-4122-96a4-2e52f8dadce0 --- # ATL COM+ 1.0 Component Wizard -::: moniker range="vs-2019" +::: moniker range=">=msvc-160" This wizard is not available in Visual Studio 2019 and later. ::: moniker-end -::: moniker range="<=vs-2017" +::: moniker range="<=msvc-150" Use this wizard to add an object to your project that supports COM+ 1.0 services, including transactions. @@ -54,7 +55,7 @@ Specify the names for the object, interface, and classes to be added to your pro Any objects you add following setting this option are designated as attributed by default (the check box is selected). You can clear this box to add an object that does not use attributes. - See [Application Settings, ATL Project Wizard](../../atl/reference/application-settings-atl-project-wizard.md) and [Basic Mechanics of Attributes](../../windows/basic-mechanics-of-attributes.md) for more information. + See [Application Settings, ATL Project Wizard](../../atl/reference/application-settings-atl-project-wizard.md) and [Basic mechanics of attributes](../../windows/attributes/cpp-attributes-com-net.md#basic-mechanics-of-attributes) for more information. ### COM diff --git a/docs/atl/reference/atl-control-wizard.md b/docs/atl/reference/atl-control-wizard.md index f30fedc78d..f1ba09a54d 100644 --- a/docs/atl/reference/atl-control-wizard.md +++ b/docs/atl/reference/atl-control-wizard.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL Control Wizard" title: "ATL Control Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.codewiz.class.atl.control.overview"] @@ -60,7 +61,7 @@ Provides information for the C++ class created to implement the object. By default, any objects you add after you set this option are designated as attributed (the check box is selected). You can clear this box to add an object that does not use attributes. - See [Application Settings, ATL Project Wizard](../../atl/reference/application-settings-atl-project-wizard.md) and [Basic Mechanics of Attributes](../../windows/basic-mechanics-of-attributes.md) for more information. + See [Application Settings, ATL Project Wizard](../../atl/reference/application-settings-atl-project-wizard.md) and [Basic mechanics of attributes](../../windows/attributes/cpp-attributes-com-net.md#basic-mechanics-of-attributes) for more information. ### COM @@ -83,7 +84,7 @@ Provides information about the COM functionality for the object. - **ProgID** - Sets the name that containers can use instead of the CLSID of the object. This field is not automatically populated. If you do not manually populate this field, the control may not be available to other tools. For example, ActiveX controls that are generated without a `ProgID` are not available in the **Insert ActiveX Control** dialog box. For more information about the dialog box, see [Insert ActiveX Control Dialog Box](../../windows/insert-activex-control-dialog-box.md). + Sets the name that containers can use instead of the CLSID of the object. This field is not automatically populated. If you do not manually populate this field, the control may not be available to other tools. For example, ActiveX controls that are generated without a `ProgID` are not available in the **Insert ActiveX Control** dialog box. For more information about the dialog box, see [Insert ActiveX controls](../../windows/adding-editing-or-deleting-controls.md#insert-activex-controls). ## See also diff --git a/docs/atl/reference/atl-dialog-wizard.md b/docs/atl/reference/atl-dialog-wizard.md index f5fc0dde7b..c2908571e3 100644 --- a/docs/atl/reference/atl-dialog-wizard.md +++ b/docs/atl/reference/atl-dialog-wizard.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL Dialog Wizard" title: "ATL Dialog Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.codewiz.class.atl.dlg.overview"] diff --git a/docs/atl/reference/atl-drawinfo-structure.md b/docs/atl/reference/atl-drawinfo-structure.md index 2bc47678d4..8c44e5e231 100644 --- a/docs/atl/reference/atl-drawinfo-structure.md +++ b/docs/atl/reference/atl-drawinfo-structure.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL_DRAWINFO Structure" title: "ATL_DRAWINFO Structure" ms.date: "11/04/2016" f1_keywords: ["ATL::ATL_DRAWINFO", "ATL_DRAWINFO", "ATL.ATL_DRAWINFO"] diff --git a/docs/atl/reference/atl-func-info-structure.md b/docs/atl/reference/atl-func-info-structure.md index eab7648030..2be432a32d 100644 --- a/docs/atl/reference/atl-func-info-structure.md +++ b/docs/atl/reference/atl-func-info-structure.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: _ATL_FUNC_INFO Structure" title: "_ATL_FUNC_INFO Structure" ms.date: "11/04/2016" f1_keywords: ["_ATL_FUNC_INFO", "ATL::_ATL_FUNC_INFO", "ATL._ATL_FUNC_INFO"] diff --git a/docs/atl/reference/atl-functions.md b/docs/atl/reference/atl-functions.md index 2dddc1985c..f32f42b204 100644 --- a/docs/atl/reference/atl-functions.md +++ b/docs/atl/reference/atl-functions.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL Functions" title: "ATL Functions" ms.date: "11/04/2016" helpviewer_keywords: ["functions [ATL]", "ATL, global functions"] diff --git a/docs/atl/reference/atl-global-variables.md b/docs/atl/reference/atl-global-variables.md index 2fbfd36a26..68a23951c1 100644 --- a/docs/atl/reference/atl-global-variables.md +++ b/docs/atl/reference/atl-global-variables.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL Global Variables" title: "ATL Global Variables" ms.date: "12/06/2017" f1_keywords: ["ATLBASE/_pAtlModule"] diff --git a/docs/atl/reference/atl-http-utility-functions.md b/docs/atl/reference/atl-http-utility-functions.md index 2ac450a0ea..47f78813f0 100644 --- a/docs/atl/reference/atl-http-utility-functions.md +++ b/docs/atl/reference/atl-http-utility-functions.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL HTTP Utility Functions" title: "ATL HTTP Utility Functions" ms.date: "11/04/2016" ms.assetid: 4db57ef2-31fa-4696-bbeb-79a9035033ed @@ -7,7 +8,7 @@ ms.assetid: 4db57ef2-31fa-4696-bbeb-79a9035033ed These functions support manipulation of URLs. -||| +|Function|Description| |-|-| |[AtlCanonicalizeUrl](#atlcanonicalizeurl)|Canonicalizes a URL, which includes converting unsafe characters and spaces into escape sequences.| |[AtlCombineUrl](#atlcombineurl)|Combines a base URL and a relative URL into a single, canonical URL.| diff --git a/docs/atl/reference/atl-macros.md b/docs/atl/reference/atl-macros.md index 7ac52771b5..28f62b3011 100644 --- a/docs/atl/reference/atl-macros.md +++ b/docs/atl/reference/atl-macros.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL Macros" title: "ATL Macros" ms.date: "11/04/2016" helpviewer_keywords: ["ATL, macros", "macros, ATL"] diff --git a/docs/atl/reference/atl-module70-structure.md b/docs/atl/reference/atl-module70-structure.md index f9d7274d81..eeee426327 100644 --- a/docs/atl/reference/atl-module70-structure.md +++ b/docs/atl/reference/atl-module70-structure.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: _ATL_MODULE70 Structure" title: "_ATL_MODULE70 Structure" ms.date: "11/04/2016" f1_keywords: ["_ATL_MODULE70", "ATL::_ATL_MODULE70", "ATL._ATL_MODULE70"] diff --git a/docs/atl/reference/atl-ole-db-consumer-wizard.md b/docs/atl/reference/atl-ole-db-consumer-wizard.md index 94510665a1..da09ffeebb 100644 --- a/docs/atl/reference/atl-ole-db-consumer-wizard.md +++ b/docs/atl/reference/atl-ole-db-consumer-wizard.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL OLE DB Consumer Wizard" title: "ATL OLE DB Consumer Wizard" ms.date: "07/02/2019" helpviewer_keywords: ["ATL projects, adding ATL OLE DB consumers"] @@ -6,13 +7,13 @@ ms.assetid: dcb68ed1-2224-422f-9f7b-108a74864204 --- # ATL OLE DB Consumer Wizard -::: moniker range="vs-2019" +::: moniker range=">=msvc-160" This wizard is not available in Visual Studio 2019 and later. ::: moniker-end -::: moniker range="<=vs-2017" +::: moniker range="<=msvc-150" This wizard sets up an OLE DB consumer class with the data bindings necessary to access the specified data source through the specified OLE DB provider. @@ -148,7 +149,7 @@ This wizard sets up an OLE DB consumer class with the data bindings necessary to // for consumer type of 'table' ``` - See [Basic Mechanics of Attributes](../../windows/basic-mechanics-of-attributes.md) for more information. + See [Basic mechanics of attributes](../../windows/attributes/cpp-attributes-com-net.md#basic-mechanics-of-attributes) for more information. - **Type** diff --git a/docs/atl/reference/atl-ole-db-provider-wizard.md b/docs/atl/reference/atl-ole-db-provider-wizard.md index d4e6cee054..29417f6f85 100644 --- a/docs/atl/reference/atl-ole-db-provider-wizard.md +++ b/docs/atl/reference/atl-ole-db-provider-wizard.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL OLE DB Provider Wizard" title: "ATL OLE DB Provider Wizard" ms.date: "05/09/2019" helpviewer_keywords: ["ATL projects, adding ATL OLE DB providers"] @@ -6,13 +7,13 @@ ms.assetid: cf91ba78-01d1-4d12-b673-e95d96bfbebe --- # ATL OLE DB Provider Wizard -::: moniker range="vs-2019" +::: moniker range=">=msvc-160" This wizard is not available in Visual Studio 2019 and later. ::: moniker-end -::: moniker range="<=vs-2017" +::: moniker range="<=msvc-150" ## Remarks diff --git a/docs/atl/reference/atl-operators.md b/docs/atl/reference/atl-operators.md index 18dffb6593..85beb951ab 100644 --- a/docs/atl/reference/atl-operators.md +++ b/docs/atl/reference/atl-operators.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL Operators" title: "ATL Operators" ms.date: "11/04/2016" helpviewer_keywords: ["operators [ATL]"] diff --git a/docs/atl/reference/atl-path-functions.md b/docs/atl/reference/atl-path-functions.md index a704907c84..33562d071a 100644 --- a/docs/atl/reference/atl-path-functions.md +++ b/docs/atl/reference/atl-path-functions.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL Path functions" title: "ATL Path functions" ms.date: "11/04/2016" helpviewer_keywords: ["ATL, path"] @@ -11,13 +12,13 @@ ATL provides the ATLPath class for manipulating paths in the form of [CPathT](cp ## Related Classes -||| +|Class|Description| |-|-| |[CPathT Class](cpatht-class.md)|This class represents a path.| ## Related Typedefs -||| +|Typedef|Description| |-|-| |`CPath`|A specialization of [CPathT](cpatht-class.md) using `CString`.| |`CPathA`|A specialization of [CPathT](cpatht-class.md) using `CStringA`.| @@ -25,7 +26,7 @@ ATL provides the ATLPath class for manipulating paths in the form of [CPathT](cp ## Functions -||| +|Function|Description| |-|-| |[ATLPath::AddBackslash](#addbackslash)|This function is an overloaded wrapper for [PathAddBackslash](/windows/win32/api/shlwapi/nf-shlwapi-pathaddbackslashw).| |[ATLPath::AddExtension](#addextension)|This function is an overloaded wrapper for [PathAddExtension](/windows/win32/api/shlwapi/nf-shlwapi-pathaddextensionw).| diff --git a/docs/atl/reference/atl-project-wizard.md b/docs/atl/reference/atl-project-wizard.md index 45ef199443..54180ade5d 100644 --- a/docs/atl/reference/atl-project-wizard.md +++ b/docs/atl/reference/atl-project-wizard.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL Project Wizard" title: "ATL Project Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.appwiz.atl.com.overview"] diff --git a/docs/atl/reference/atl-property-page-wizard.md b/docs/atl/reference/atl-property-page-wizard.md index e11300a445..16c0045690 100644 --- a/docs/atl/reference/atl-property-page-wizard.md +++ b/docs/atl/reference/atl-property-page-wizard.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL Property Page Wizard" title: "ATL Property Page Wizard" ms.date: "05/09/2019" f1_keywords: ["vc.codewiz.class.atl.ppg.overview"] @@ -7,13 +8,13 @@ ms.assetid: 6113e325-facd-4f68-b491-144d75209922 --- # ATL Property Page Wizard -::: moniker range="vs-2019" +::: moniker range=">=msvc-160" This wizard is not available in Visual Studio 2019 and later. ::: moniker-end -::: moniker range="<=vs-2017" +::: moniker range="<=msvc-150" This wizard [adds a property page into an ATL project](../../atl/reference/adding-an-atl-property-page.md) or to an MFC project with ATL support. An ATL property page provides a user interface for setting the properties (or calling the methods) of one or more COM objects. @@ -32,14 +33,13 @@ Specify the names for the object, interface, and classes to be added to your pro Provides information for the C++ class created to implement the object. -||| -|-|-| |Term|Definition| +|-|-| |**Short name**|Sets the abbreviated name for the object. The name that you provide determines the class and **Coclass** names, the file (**.cpp** and **.h**) names, the **Type** name, and the **ProgID**, unless you change those fields individually.| |**.h file**|Sets the name of the header file for the new object's class. By default, this name is based on the name that you provide in **Short name**. Click the ellipsis button to save the file name to the location of your choice, or to append the class declaration to an existing file. If you select an existing file, the wizard will not save it to the selected location until you click **Finish** in the wizard.

The wizard does not overwrite a file. If you select the name of an existing file, when you click **Finish**, the wizard prompts you to indicate whether the class declaration should be appended to the contents of the file. Click **Yes** to append the file; click **No** to return to the wizard and specify another file name.| |**Class**|Sets the name of the class that implements the object. This name is based on the name that you provide in **Short name**, preceded by 'C', the typical prefix for a class name.| |**.cpp file**|Sets the name of the implementation file for the new object's class. By default, this name is based on the name that you provide in **Short name**. Click the ellipsis button to save the file name to the location of your choice. The file is not saved to the selected location until you click **Finish** in the wizard.

The wizard does not overwrite a file. If you select the name of an existing file, when you click **Finish**, the wizard prompts you to indicate whether the class implementation should be appended to the contents of the file. Click **Yes** to append the file; click **No** to return to the wizard and specify another file name.| -|**Attributed**|Indicates whether the object uses attributes. If you are adding an object to an attributed ATL project, this option is selected and not available to change, that is, you can add only attributed objects to a project created with attribute support.

You can add an attributed object only to an ATL project that uses attributes. If you select this option for an ATL project that does not have attribute support, the wizard prompts you to specify whether you want to add attribute support to the project.

By default, any objects you add after you set this option are designated as attributed (the check box is selected). You can clear this box to add an object that does not use attributes.

See [Application Settings, ATL Project Wizard](../../atl/reference/application-settings-atl-project-wizard.md) and [Basic Mechanics of Attributes](../../windows/basic-mechanics-of-attributes.md) for more information.| +|**Attributed**|Indicates whether the object uses attributes. If you are adding an object to an attributed ATL project, this option is selected and not available to change, that is, you can add only attributed objects to a project created with attribute support.

You can add an attributed object only to an ATL project that uses attributes. If you select this option for an ATL project that does not have attribute support, the wizard prompts you to specify whether you want to add attribute support to the project.

By default, any objects you add after you set this option are designated as attributed (the check box is selected). You can clear this box to add an object that does not use attributes.

See [Application Settings, ATL Project Wizard](../../atl/reference/application-settings-atl-project-wizard.md) and [Basic mechanics of attributes](../../windows/attributes/cpp-attributes-com-net.md#basic-mechanics-of-attributes) for more information.| ### COM diff --git a/docs/atl/reference/atl-simple-object-wizard.md b/docs/atl/reference/atl-simple-object-wizard.md index 9c31c4b6f9..23a819b1bf 100644 --- a/docs/atl/reference/atl-simple-object-wizard.md +++ b/docs/atl/reference/atl-simple-object-wizard.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL Simple Object Wizard" title: "ATL Simple Object Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.codewiz.class.atl.simple.overview"] @@ -54,7 +55,7 @@ Provides information for the C++ class created for the object. By default, any objects you add after you set this option are designated as attributed (the check box is selected). You can clear this box to add an object that does not use attributes. - See [Application Settings, ATL Project Wizard](../../atl/reference/application-settings-atl-project-wizard.md) and [Basic Mechanics of Attributes](../../windows/basic-mechanics-of-attributes.md) for more information. + See [Application Settings, ATL Project Wizard](../../atl/reference/application-settings-atl-project-wizard.md) and [Basic mechanics of attributes](../../windows/attributes/cpp-attributes-com-net.md#basic-mechanics-of-attributes) for more information. ## COM diff --git a/docs/atl/reference/atl-text-encoding-functions.md b/docs/atl/reference/atl-text-encoding-functions.md index 76ff1156b0..aa50e31f2e 100644 --- a/docs/atl/reference/atl-text-encoding-functions.md +++ b/docs/atl/reference/atl-text-encoding-functions.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL Text Encoding Functions" title: "ATL Text Encoding Functions" ms.date: "11/04/2016" f1_keywords: ["atlbase/ATL::AtlGetHexValue", "atlbase/ATL::AtlGetVersion", "atlenc/ATL::AtlHexDecode", "atlenc/ATL::AtlHexDecodeGetRequiredLength", "atlenc/ATL::AtlHexEncode", "atlenc/ATL::AtlHexEncodeGetRequiredLength", "atlenc/ATL::AtlHexValue", "atlenc/ATL::BEncode", "atlenc/ATL::BEncodeGetRequiredLength", "atlenc/ATL::EscapeXML", "atlenc/ATL::GetExtendedChars", "atlenc/ATL::IsExtendedChar", "atlenc/ATL::QEncode", "atlenc/ATL::QEncodeGetRequiredLength", "atlenc/ATL::QPDecode", "atlenc/ATL::QPDecodeGetRequiredLength", "atlenc/ATL::QPEncode", "atlenc/ATL::QPEncodeGetRequiredLength", "atlenc/ATL::UUDecode", "atlenc/ATL::UUDecodeGetRequiredLength", "atlenc/ATL::UUEncode", "atlenc/ATL::UUEncodeGetRequiredLength"] @@ -8,7 +9,7 @@ ms.assetid: 2ae1648b-2b87-4112-92aa-0069fcfd23da These functions support text encoding and decoding. -||| +|Function|Description| |-|-| |[AtlGetHexValue](#atlgethexvalue)|Call this function to get the numeric value of a hexadecimal digit.| |[AtlGetVersion](#atlgetversion)|Call this function to get the version of the ATL library that you are using. | @@ -334,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/atl-typedefs.md b/docs/atl/reference/atl-typedefs.md index b027344273..471587e327 100644 --- a/docs/atl/reference/atl-typedefs.md +++ b/docs/atl/reference/atl-typedefs.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL Typedefs" title: "ATL Typedefs" ms.date: "11/04/2016" f1_keywords: ["atlcore/ATL::_ATL_BASE_MODULE", "atlbase/ATL::_ATL_COM_MODULE", "atlbase/ATL::_ATL_MODULE", "atlbase/ATL::_ATL_WIN_MODULE", "atlutil/ATL::ATL_URL_PORT", "atlbase/ATL::CComDispatchDriver", "atlbase/ATL::CComGlobalsThreadModel", "atlbase/ATL::CComObjectThreadModel", "atlwin/ATL::CContainedWindow", "atlpath/ATL::CPath", "atlpath/ATL::CPathA", "atlpath/ATL::CPathW", " atlsimpcoll/ATL::CSimpleValArray", " atlutil/ATL::LPCURL", "atlbase/ATL::DefaultThreadTraits", "atlutil/ATL::LPURL"] @@ -9,7 +10,7 @@ ms.assetid: 7dd05baa-3efb-4e3b-af23-793c610f4560 The Active Template Library includes the following typedefs. -||| +|Typedef|Description| |-|-| |[_ATL_BASE_MODULE](#_atl_base_module)|Defined as a typedef based on [_ATL_BASE_MODULE70](../../atl/reference/atl-base-module70-structure.md).| |[_ATL_COM_MODULE](#_atl_com_module)|Defined as a typedef based on [_ATL_COM_MODULE70](../../atl/reference/atl-com-module70-structure.md).| diff --git a/docs/atl/reference/atl-url-scheme-enum.md b/docs/atl/reference/atl-url-scheme-enum.md index ccab260de1..fbed95cb01 100644 --- a/docs/atl/reference/atl-url-scheme-enum.md +++ b/docs/atl/reference/atl-url-scheme-enum.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL_URL_SCHEME" title: "ATL_URL_SCHEME enumeration" ms.date: "11/04/2016" helpviewer_keywords: ["ATLUTIL/ATL::ATL_URL_SCHEME"] diff --git a/docs/atl/reference/atl-win-module70-structure.md b/docs/atl/reference/atl-win-module70-structure.md index 58f8691a93..4a053f0aec 100644 --- a/docs/atl/reference/atl-win-module70-structure.md +++ b/docs/atl/reference/atl-win-module70-structure.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: _ATL_WIN_MODULE70 Structure" title: "_ATL_WIN_MODULE70 Structure" ms.date: "11/04/2016" f1_keywords: ["_ATL_WIN_MODULE70", "ATL::_ATL_WIN_MODULE70", "ATL._ATL_WIN_MODULE70"] diff --git a/docs/atl/reference/atl-wizards-and-dialog-boxes.md b/docs/atl/reference/atl-wizards-and-dialog-boxes.md index 1ce169938d..0632227a11 100644 --- a/docs/atl/reference/atl-wizards-and-dialog-boxes.md +++ b/docs/atl/reference/atl-wizards-and-dialog-boxes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ATL Wizards and Dialog Boxes" title: "ATL Wizards and Dialog Boxes" ms.date: "06/26/2020" helpviewer_keywords: ["ATL, class wizards"] diff --git a/docs/atl/reference/atlcreatewnddata-structure.md b/docs/atl/reference/atlcreatewnddata-structure.md index a8486f78d4..ab5f1b3cf6 100644 --- a/docs/atl/reference/atlcreatewnddata-structure.md +++ b/docs/atl/reference/atlcreatewnddata-structure.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: _AtlCreateWndData Structure" title: "_AtlCreateWndData Structure" ms.date: "11/04/2016" f1_keywords: ["ATL::_AtlCreateWndData", "ATL._AtlCreateWndData", "_AtlCreateWndData"] diff --git a/docs/atl/reference/ca2aex-class.md b/docs/atl/reference/ca2aex-class.md index 1c39e72eb6..17184ac1d4 100644 --- a/docs/atl/reference/ca2aex-class.md +++ b/docs/atl/reference/ca2aex-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CA2AEX Class" title: "CA2AEX Class" ms.date: "11/04/2016" f1_keywords: ["CA2AEX", "ATLCONV/ATL::CA2AEX", "ATLCONV/ATL::CA2AEX::CA2AEX", "ATLCONV/ATL::CA2AEX::m_psz", "ATLCONV/ATL::CA2AEX::m_szBuffer"] diff --git a/docs/atl/reference/ca2caex-class.md b/docs/atl/reference/ca2caex-class.md index 92a0ff95f0..384efbd5ea 100644 --- a/docs/atl/reference/ca2caex-class.md +++ b/docs/atl/reference/ca2caex-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CA2CAEX Class" title: "CA2CAEX Class" ms.date: "11/04/2016" f1_keywords: ["CA2CAEX", "ATLCONV/ATL::CA2CAEX", "ATLCONV/ATL::CA2CAEX::CA2CAEX", "ATLCONV/ATL::CA2CAEX::m_psz"] diff --git a/docs/atl/reference/ca2wex-class.md b/docs/atl/reference/ca2wex-class.md index 965ee1edc3..6b350dc68c 100644 --- a/docs/atl/reference/ca2wex-class.md +++ b/docs/atl/reference/ca2wex-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CA2WEX Class" title: "CA2WEX Class" ms.date: "11/04/2016" f1_keywords: ["CA2WEX", "ATLCONV/ATL::CA2WEX", "ATLCONV/ATL::CA2WEX::CA2WEX", "ATLCONV/ATL::CA2WEX::m_psz", "ATLCONV/ATL::CA2WEX::m_szBuffer"] diff --git a/docs/atl/reference/caccesstoken-class.md b/docs/atl/reference/caccesstoken-class.md index 7bc57a281b..49272bfcd4 100644 --- a/docs/atl/reference/caccesstoken-class.md +++ b/docs/atl/reference/caccesstoken-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAccessToken Class" title: "CAccessToken Class" ms.date: "07/02/2019" f1_keywords: ["CAccessToken", "ATLSECURITY/ATL::CAccessToken", "ATLSECURITY/ATL::CAccessToken::Attach", "ATLSECURITY/ATL::CAccessToken::CheckTokenMembership", "ATLSECURITY/ATL::CAccessToken::CreateImpersonationToken", "ATLSECURITY/ATL::CAccessToken::CreatePrimaryToken", "ATLSECURITY/ATL::CAccessToken::CreateProcessAsUser", "ATLSECURITY/ATL::CAccessToken::CreateRestrictedToken", "ATLSECURITY/ATL::CAccessToken::Detach", "ATLSECURITY/ATL::CAccessToken::DisablePrivilege", "ATLSECURITY/ATL::CAccessToken::DisablePrivileges", "ATLSECURITY/ATL::CAccessToken::EnablePrivilege", "ATLSECURITY/ATL::CAccessToken::EnablePrivileges", "ATLSECURITY/ATL::CAccessToken::GetDefaultDacl", "ATLSECURITY/ATL::CAccessToken::GetEffectiveToken", "ATLSECURITY/ATL::CAccessToken::GetGroups", "ATLSECURITY/ATL::CAccessToken::GetHandle", "ATLSECURITY/ATL::CAccessToken::GetImpersonationLevel", "ATLSECURITY/ATL::CAccessToken::GetLogonSessionId", "ATLSECURITY/ATL::CAccessToken::GetLogonSid", "ATLSECURITY/ATL::CAccessToken::GetOwner", "ATLSECURITY/ATL::CAccessToken::GetPrimaryGroup", "ATLSECURITY/ATL::CAccessToken::GetPrivileges", "ATLSECURITY/ATL::CAccessToken::GetProcessToken", "ATLSECURITY/ATL::CAccessToken::GetProfile", "ATLSECURITY/ATL::CAccessToken::GetSource", "ATLSECURITY/ATL::CAccessToken::GetStatistics", "ATLSECURITY/ATL::CAccessToken::GetTerminalServicesSessionId", "ATLSECURITY/ATL::CAccessToken::GetThreadToken", "ATLSECURITY/ATL::CAccessToken::GetTokenId", "ATLSECURITY/ATL::CAccessToken::GetType", "ATLSECURITY/ATL::CAccessToken::GetUser", "ATLSECURITY/ATL::CAccessToken::HKeyCurrentUser", "ATLSECURITY/ATL::CAccessToken::Impersonate", "ATLSECURITY/ATL::CAccessToken::ImpersonateLoggedOnUser", "ATLSECURITY/ATL::CAccessToken::IsTokenRestricted", "ATLSECURITY/ATL::CAccessToken::LoadUserProfile", "ATLSECURITY/ATL::CAccessToken::LogonUser", "ATLSECURITY/ATL::CAccessToken::OpenCOMClientToken", "ATLSECURITY/ATL::CAccessToken::OpenNamedPipeClientToken", "ATLSECURITY/ATL::CAccessToken::OpenRPCClientToken", "ATLSECURITY/ATL::CAccessToken::OpenThreadToken", "ATLSECURITY/ATL::CAccessToken::PrivilegeCheck", "ATLSECURITY/ATL::CAccessToken::Revert", "ATLSECURITY/ATL::CAccessToken::SetDefaultDacl", "ATLSECURITY/ATL::CAccessToken::SetOwner", "ATLSECURITY/ATL::CAccessToken::SetPrimaryGroup"] diff --git a/docs/atl/reference/cacl-class.md b/docs/atl/reference/cacl-class.md index f579a74e28..1521ad15fe 100644 --- a/docs/atl/reference/cacl-class.md +++ b/docs/atl/reference/cacl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAcl Class" title: "CAcl Class" ms.date: "11/04/2016" f1_keywords: ["CAcl", "ATLSECURITY/ATL::CAcl", "ATLSECURITY/ATL::CAcl::CAccessMaskArray", "ATLSECURITY/ATL::CAcl::CAceFlagArray", "ATLSECURITY/ATL::CAcl::CAceTypeArray", "ATLSECURITY/ATL::CAcl::CAcl", "ATLSECURITY/ATL::CAcl::GetAceCount", "ATLSECURITY/ATL::CAcl::GetAclEntries", "ATLSECURITY/ATL::CAcl::GetAclEntry", "ATLSECURITY/ATL::CAcl::GetLength", "ATLSECURITY/ATL::CAcl::GetPACL", "ATLSECURITY/ATL::CAcl::IsEmpty", "ATLSECURITY/ATL::CAcl::IsNull", "ATLSECURITY/ATL::CAcl::RemoveAce", "ATLSECURITY/ATL::CAcl::RemoveAces", "ATLSECURITY/ATL::CAcl::SetEmpty", "ATLSECURITY/ATL::CAcl::SetNull"] diff --git a/docs/atl/reference/cadapt-class.md b/docs/atl/reference/cadapt-class.md index 52fbb6d534..e3596e34f0 100644 --- a/docs/atl/reference/cadapt-class.md +++ b/docs/atl/reference/cadapt-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAdapt Class" title: "CAdapt Class" ms.date: "11/04/2016" f1_keywords: ["CAdapt", "ATLCOMCLI/ATL::CAdapt", "ATLCOMCLI/ATL::CAdapt::CAdapt", "ATLCOMCLI/ATL::CAdapt::m_T"] @@ -91,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*. @@ -103,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*. @@ -115,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 0baf8d0cd8..2520af5960 100644 --- a/docs/atl/reference/category-macros.md +++ b/docs/atl/reference/category-macros.md @@ -1,14 +1,15 @@ --- +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 These macros define category maps. -||| +|Macro|Description| |-|-| |[BEGIN_CATEGORY_MAP](#begin_category_map)|Marks the beginning of the category map.| |[END_CATEGORY_MAP](#end_category_map)|Marks the end of the category map.| diff --git a/docs/atl/reference/catlarray-class.md b/docs/atl/reference/catlarray-class.md index 669da3a6a9..e2ff7b40f5 100644 --- a/docs/atl/reference/catlarray-class.md +++ b/docs/atl/reference/catlarray-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAtlArray Class" title: "CAtlArray Class" ms.date: "11/04/2016" f1_keywords: ["CAtlArray", "ATLCOLL/ATL::CAtlArray", "ATLCOLL/ATL::Add", "ATLCOLL/ATL::Append", "ATLCOLL/ATL::AssertValid", "ATLCOLL/ATL::Copy", "ATLCOLL/ATL::FreeExtra", "ATLCOLL/ATL::GetAt", "ATLCOLL/ATL::GetCount", "ATLCOLL/ATL::GetData", "ATLCOLL/ATL::InsertArrayAt", "ATLCOLL/ATL::InsertAt", "ATLCOLL/ATL::IsEmpty", "ATLCOLL/ATL::RemoveAll", "ATLCOLL/ATL::RemoveAt", "ATLCOLL/ATL::SetAt", "ATLCOLL/ATL::SetAtGrow", "ATLCOLL/ATL::SetCount", "ATLCOLL/ATL::INARGTYPE", "ATLCOLL/ATL::OUTARGTYPE"] @@ -28,7 +29,7 @@ The code used to copy or move elements. ### Methods -||| +|Function|Description| |-|-| |[Add](#add)|Call this method to add an element to the array object.| |[Append](#append)|Call this method to add the contents of one array to the end of another.| @@ -51,13 +52,13 @@ The code used to copy or move elements. ### Operators -||| +|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 -||| +|Typedef|Description| |-|-| |[INARGTYPE](#inargtype)|The data type to use for adding elements to the array.| |[OUTARGTYPE](#outargtype)|The data type to use for retrieving elements from the array.| diff --git a/docs/atl/reference/catlautothreadmodule-class.md b/docs/atl/reference/catlautothreadmodule-class.md index 7ab2eb95de..ad171cbf11 100644 --- a/docs/atl/reference/catlautothreadmodule-class.md +++ b/docs/atl/reference/catlautothreadmodule-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAtlAutoThreadModule Class" title: "CAtlAutoThreadModule Class" ms.date: "11/04/2016" f1_keywords: ["CAtlAutoThreadModule", "atlbase/ATL::CAtlAutoThreadModule"] diff --git a/docs/atl/reference/catlautothreadmodulet-class.md b/docs/atl/reference/catlautothreadmodulet-class.md index 194fba7e78..b3551f67c2 100644 --- a/docs/atl/reference/catlautothreadmodulet-class.md +++ b/docs/atl/reference/catlautothreadmodulet-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAtlAutoThreadModuleT Class" title: "CAtlAutoThreadModuleT Class" ms.date: "11/04/2016" f1_keywords: ["CAtlAutoThreadModuleT", "ATLBASE/ATL::CAtlAutoThreadModuleT", "ATLBASE/ATL::CAtlAutoThreadModuleT::GetDefaultThreads"] diff --git a/docs/atl/reference/catlbasemodule-class.md b/docs/atl/reference/catlbasemodule-class.md index 2745c5a87d..ca75cf7b50 100644 --- a/docs/atl/reference/catlbasemodule-class.md +++ b/docs/atl/reference/catlbasemodule-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAtlBaseModule Class" title: "CAtlBaseModule Class" ms.date: "11/04/2016" f1_keywords: ["CAtlBaseModule", "ATLCORE/ATL::CAtlBaseModule", "ATLCORE/ATL::CAtlBaseModule::CAtlBaseModule", "ATLCORE/ATL::CAtlBaseModule::AddResourceInstance", "ATLCORE/ATL::CAtlBaseModule::GetHInstanceAt", "ATLCORE/ATL::CAtlBaseModule::GetModuleInstance", "ATLCORE/ATL::CAtlBaseModule::GetResourceInstance", "ATLCORE/ATL::CAtlBaseModule::RemoveResourceInstance", "ATLCORE/ATL::CAtlBaseModule::SetResourceInstance", "ATLCORE/ATL::CAtlBaseModule::m_bInitFailed"] diff --git a/docs/atl/reference/catlcommodule-class.md b/docs/atl/reference/catlcommodule-class.md index aa453f662c..ec1824a976 100644 --- a/docs/atl/reference/catlcommodule-class.md +++ b/docs/atl/reference/catlcommodule-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAtlComModule Class" title: "CAtlComModule Class" ms.date: "11/04/2016" f1_keywords: ["CAtlComModule", "ATLBASE/ATL::CAtlComModule", "ATLBASE/ATL::CAtlComModule::CAtlComModule", "ATLBASE/ATL::CAtlComModule::RegisterServer", "ATLBASE/ATL::CAtlComModule::RegisterTypeLib", "ATLBASE/ATL::CAtlComModule::UnregisterServer", "ATLBASE/ATL::CAtlComModule::UnRegisterTypeLib"] diff --git a/docs/atl/reference/catldebuginterfacesmodule-class.md b/docs/atl/reference/catldebuginterfacesmodule-class.md index 9130fb259a..38a674b3e7 100644 --- a/docs/atl/reference/catldebuginterfacesmodule-class.md +++ b/docs/atl/reference/catldebuginterfacesmodule-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAtlDebugInterfacesModule Class" title: "CAtlDebugInterfacesModule Class" ms.date: "11/04/2016" f1_keywords: ["CAtlDebugInterfacesModule", "atlbase/ATL::CAtlDebugInterfacesModule"] diff --git a/docs/atl/reference/catldllmodulet-class.md b/docs/atl/reference/catldllmodulet-class.md index 2d0c861f98..af960db0ee 100644 --- a/docs/atl/reference/catldllmodulet-class.md +++ b/docs/atl/reference/catldllmodulet-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAtlDllModuleT Class" title: "CAtlDllModuleT Class" ms.date: "11/04/2016" f1_keywords: ["CAtlDllModuleT", "ATLBASE/ATL::CAtlDllModuleT", "ATLBASE/ATL::CAtlDllModuleT::CAtlDllModuleT", "ATLBASE/ATL::CAtlDllModuleT::DllCanUnloadNow", "ATLBASE/ATL::CAtlDllModuleT::DllGetClassObject", "ATLBASE/ATL::CAtlDllModuleT::DllMain", "ATLBASE/ATL::CAtlDllModuleT::DllRegisterServer", "ATLBASE/ATL::CAtlDllModuleT::DllUnregisterServer", "ATLBASE/ATL::CAtlDllModuleT::GetClassObject"] diff --git a/docs/atl/reference/catlexception-class.md b/docs/atl/reference/catlexception-class.md index 032169e6dc..5549aa2ab7 100644 --- a/docs/atl/reference/catlexception-class.md +++ b/docs/atl/reference/catlexception-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAtlException Class" title: "CAtlException Class" ms.date: "11/04/2016" f1_keywords: ["CAtlException", "ATLEXCEPT/ATL::CAtlException", "ATLEXCEPT/ATL::CAtlException::CAtlException", "ATLEXCEPT/ATL::CAtlException::m_hr"] diff --git a/docs/atl/reference/catlexemodulet-class.md b/docs/atl/reference/catlexemodulet-class.md index f825bd22be..9d191306d9 100644 --- a/docs/atl/reference/catlexemodulet-class.md +++ b/docs/atl/reference/catlexemodulet-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAtlExeModuleT Class" title: "CAtlExeModuleT Class" ms.date: "11/04/2016" f1_keywords: ["CAtlExeModuleT", "ATLBASE/ATL::CAtlExeModuleT", "ATLBASE/ATL::CAtlExeModuleT::CAtlExeModuleT", "ATLBASE/ATL::CAtlExeModuleT::InitializeCom", "ATLBASE/ATL::CAtlExeModuleT::ParseCommandLine", "ATLBASE/ATL::CAtlExeModuleT::PostMessageLoop", "ATLBASE/ATL::CAtlExeModuleT::PreMessageLoop", "ATLBASE/ATL::CAtlExeModuleT::RegisterClassObjects", "ATLBASE/ATL::CAtlExeModuleT::RevokeClassObjects", "ATLBASE/ATL::CAtlExeModuleT::Run", "ATLBASE/ATL::CAtlExeModuleT::RunMessageLoop", "ATLBASE/ATL::CAtlExeModuleT::UninitializeCom", "ATLBASE/ATL::CAtlExeModuleT::Unlock", "ATLBASE/ATL::CAtlExeModuleT::WinMain", "ATLBASE/ATL::CAtlExeModuleT::m_bDelayShutdown", "ATLBASE/ATL::CAtlExeModuleT::m_dwPause", "ATLBASE/ATL::CAtlExeModuleT::m_dwTimeOut"] diff --git a/docs/atl/reference/catlfile-class.md b/docs/atl/reference/catlfile-class.md index 10b54bd10d..bbc448b979 100644 --- a/docs/atl/reference/catlfile-class.md +++ b/docs/atl/reference/catlfile-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAtlFile Class" title: "CAtlFile Class" ms.date: "11/04/2016" f1_keywords: ["CAtlFile", "ATLFILE/ATL::CAtlFile", "ATLFILE/ATL::CAtlFile::CAtlFile", "ATLFILE/ATL::CAtlFile::Create", "ATLFILE/ATL::CAtlFile::Flush", "ATLFILE/ATL::CAtlFile::GetOverlappedResult", "ATLFILE/ATL::CAtlFile::GetPosition", "ATLFILE/ATL::CAtlFile::GetSize", "ATLFILE/ATL::CAtlFile::LockRange", "ATLFILE/ATL::CAtlFile::Read", "ATLFILE/ATL::CAtlFile::Seek", "ATLFILE/ATL::CAtlFile::SetSize", "ATLFILE/ATL::CAtlFile::UnlockRange", "ATLFILE/ATL::CAtlFile::Write", "ATLFILE/ATL::CAtlFile::m_pTM"] diff --git a/docs/atl/reference/catlfilemapping-class.md b/docs/atl/reference/catlfilemapping-class.md index 47ff5b0148..8eebfc290c 100644 --- a/docs/atl/reference/catlfilemapping-class.md +++ b/docs/atl/reference/catlfilemapping-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAtlFileMapping Class" title: "CAtlFileMapping Class" ms.date: "11/04/2016" f1_keywords: ["CAtlFileMapping", "atlfile/ATL::CAtlFileMapping"] diff --git a/docs/atl/reference/catlfilemappingbase-class.md b/docs/atl/reference/catlfilemappingbase-class.md index 2487ac77e0..f7084aa957 100644 --- a/docs/atl/reference/catlfilemappingbase-class.md +++ b/docs/atl/reference/catlfilemappingbase-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAtlFileMappingBase Class" title: "CAtlFileMappingBase Class" ms.date: "11/04/2016" f1_keywords: ["CAtlFileMappingBase", "ATLFILE/ATL::CAtlFileMappingBase", "ATLFILE/ATL::CAtlFileMappingBase::CAtlFileMappingBase", "ATLFILE/ATL::CAtlFileMappingBase::CopyFrom", "ATLFILE/ATL::CAtlFileMappingBase::GetData", "ATLFILE/ATL::CAtlFileMappingBase::GetHandle", "ATLFILE/ATL::CAtlFileMappingBase::GetMappingSize", "ATLFILE/ATL::CAtlFileMappingBase::MapFile", "ATLFILE/ATL::CAtlFileMappingBase::MapSharedMem", "ATLFILE/ATL::CAtlFileMappingBase::OpenMapping", "ATLFILE/ATL::CAtlFileMappingBase::Unmap"] diff --git a/docs/atl/reference/catllist-class.md b/docs/atl/reference/catllist-class.md index c76645de14..6b1fc2ce91 100644 --- a/docs/atl/reference/catllist-class.md +++ b/docs/atl/reference/catllist-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAtlList Class" title: "CAtlList Class" ms.date: "11/04/2016" f1_keywords: ["CAtlList", "ATLCOLL/ATL::CAtlList", "ATLCOLL/ATL::CAtlList::INARGTYPE", "ATLCOLL/ATL::CAtlList::CAtlList", "ATLCOLL/ATL::CAtlList::AddHead", "ATLCOLL/ATL::CAtlList::AddHeadList", "ATLCOLL/ATL::CAtlList::AddTail", "ATLCOLL/ATL::CAtlList::AddTailList", "ATLCOLL/ATL::CAtlList::AssertValid", "ATLCOLL/ATL::CAtlList::Find", "ATLCOLL/ATL::CAtlList::FindIndex", "ATLCOLL/ATL::CAtlList::GetAt", "ATLCOLL/ATL::CAtlList::GetCount", "ATLCOLL/ATL::CAtlList::GetHead", "ATLCOLL/ATL::CAtlList::GetHeadPosition", "ATLCOLL/ATL::CAtlList::GetNext", "ATLCOLL/ATL::CAtlList::GetPrev", "ATLCOLL/ATL::CAtlList::GetTail", "ATLCOLL/ATL::CAtlList::GetTailPosition", "ATLCOLL/ATL::CAtlList::InsertAfter", "ATLCOLL/ATL::CAtlList::InsertBefore", "ATLCOLL/ATL::CAtlList::IsEmpty", "ATLCOLL/ATL::CAtlList::MoveToHead", "ATLCOLL/ATL::CAtlList::MoveToTail", "ATLCOLL/ATL::CAtlList::RemoveAll", "ATLCOLL/ATL::CAtlList::RemoveAt", "ATLCOLL/ATL::CAtlList::RemoveHead", "ATLCOLL/ATL::CAtlList::RemoveHeadNoReturn", "ATLCOLL/ATL::CAtlList::RemoveTail", "ATLCOLL/ATL::CAtlList::RemoveTailNoReturn", "ATLCOLL/ATL::CAtlList::SetAt", "ATLCOLL/ATL::CAtlList::SwapElements"] diff --git a/docs/atl/reference/catlmap-class.md b/docs/atl/reference/catlmap-class.md index 38c16d8841..b9273b02c8 100644 --- a/docs/atl/reference/catlmap-class.md +++ b/docs/atl/reference/catlmap-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAtlMap Class" title: "CAtlMap Class" ms.date: "11/04/2016" f1_keywords: ["CAtlMap", "ATLCOLL/ATL::CAtlMap", "ATLCOLL/ATL::CAtlMap::KINARGTYPE", "ATLCOLL/ATL::CAtlMap::KOUTARGTYPE", "ATLCOLL/ATL::CAtlMap::VINARGTYPE", "ATLCOLL/ATL::CAtlMap::VOUTARGTYPE", "ATLCOLL/ATL::CPair::m_key", "ATLCOLL/ATL::CPair::m_value", "ATLCOLL/ATL::CAtlMap::CAtlMap", "ATLCOLL/ATL::CAtlMap::AssertValid", "ATLCOLL/ATL::CAtlMap::DisableAutoRehash", "ATLCOLL/ATL::CAtlMap::EnableAutoRehash", "ATLCOLL/ATL::CAtlMap::GetAt", "ATLCOLL/ATL::CAtlMap::GetCount", "ATLCOLL/ATL::CAtlMap::GetHashTableSize", "ATLCOLL/ATL::CAtlMap::GetKeyAt", "ATLCOLL/ATL::CAtlMap::GetNext", "ATLCOLL/ATL::CAtlMap::GetNextAssoc", "ATLCOLL/ATL::CAtlMap::GetNextKey", "ATLCOLL/ATL::CAtlMap::GetNextValue", "ATLCOLL/ATL::CAtlMap::GetStartPosition", "ATLCOLL/ATL::CAtlMap::GetValueAt", "ATLCOLL/ATL::CAtlMap::InitHashTable", "ATLCOLL/ATL::CAtlMap::IsEmpty", "ATLCOLL/ATL::CAtlMap::Lookup", "ATLCOLL/ATL::CAtlMap::Rehash", "ATLCOLL/ATL::CAtlMap::RemoveAll", "ATLCOLL/ATL::CAtlMap::RemoveAtPos", "ATLCOLL/ATL::CAtlMap::RemoveKey", "ATLCOLL/ATL::CAtlMap::SetAt", "ATLCOLL/ATL::CAtlMap::SetOptimalLoad", "ATLCOLL/ATL::CAtlMap::SetValueAt"] diff --git a/docs/atl/reference/catlmodule-class.md b/docs/atl/reference/catlmodule-class.md index 3bb7a0ed6a..637193f3c8 100644 --- a/docs/atl/reference/catlmodule-class.md +++ b/docs/atl/reference/catlmodule-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAtlModule Class" title: "CAtlModule Class" ms.date: "11/04/2016" f1_keywords: ["CAtlModule", "ATLBASE/ATL::CAtlModule", "ATLBASE/ATL::CAtlModule::CAtlModule", "ATLBASE/ATL::CAtlModule::AddCommonRGSReplacements", "ATLBASE/ATL::CAtlModule::AddTermFunc", "ATLBASE/ATL::CAtlModule::GetGITPtr", "ATLBASE/ATL::CAtlModule::GetLockCount", "ATLBASE/ATL::CAtlModule::Lock", "ATLBASE/ATL::CAtlModule::Term", "ATLBASE/ATL::CAtlModule::Unlock", "ATLBASE/ATL::CAtlModule::UpdateRegistryFromResourceD", "ATLBASE/ATL::CAtlModule::UpdateRegistryFromResourceDHelper", "ATLBASE/ATL::CAtlModule::UpdateRegistryFromResourceS", "ATLBASE/ATL::CAtlModule::m_libid", "ATLBASE/ATL::CAtlModule::m_pGIT"] diff --git a/docs/atl/reference/catlmodulet-class.md b/docs/atl/reference/catlmodulet-class.md index e550880c22..aeddee3c88 100644 --- a/docs/atl/reference/catlmodulet-class.md +++ b/docs/atl/reference/catlmodulet-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAtlModuleT Class" title: "CAtlModuleT Class" ms.date: "11/04/2016" f1_keywords: ["CAtlModuleT", "ATLBASE/ATL::CAtlModuleT", "ATLBASE/ATL::CAtlModuleT::CAtlModuleT", "ATLBASE/ATL::CAtlModuleT::InitLibId", "ATLBASE/ATL::CAtlModuleT::RegisterAppId", "ATLBASE/ATL::CAtlModuleT::RegisterServer", "ATLBASE/ATL::CAtlModuleT::UnregisterAppId", "ATLBASE/ATL::CAtlModuleT::UnregisterServer", "ATLBASE/ATL::CAtlModuleT::UpdateRegistryAppId"] diff --git a/docs/atl/reference/catlpreviewctrlimpl-class.md b/docs/atl/reference/catlpreviewctrlimpl-class.md index ef082551ac..2f2fc09617 100644 --- a/docs/atl/reference/catlpreviewctrlimpl-class.md +++ b/docs/atl/reference/catlpreviewctrlimpl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAtlPreviewCtrlImpl Class" title: "CAtlPreviewCtrlImpl Class" ms.date: "11/04/2016" f1_keywords: ["CAtlPreviewCtrlImpl", "ATLPREVIEWCTRLIMPL/ATL::CAtlPreviewCtrlImpl", "ATLPREVIEWCTRLIMPL/ATL::CAtlPreviewCtrlImpl::CAtlPreviewCtrlImpl", "ATLPREVIEWCTRLIMPL/ATL::CAtlPreviewCtrlImpl::Create", "ATLPREVIEWCTRLIMPL/ATL::CAtlPreviewCtrlImpl::Destroy", "ATLPREVIEWCTRLIMPL/ATL::CAtlPreviewCtrlImpl::Focus", "ATLPREVIEWCTRLIMPL/ATL::CAtlPreviewCtrlImpl::OnPaint", "ATLPREVIEWCTRLIMPL/ATL::CAtlPreviewCtrlImpl::Redraw", "ATLPREVIEWCTRLIMPL/ATL::CAtlPreviewCtrlImpl::SetHost", "ATLPREVIEWCTRLIMPL/ATL::CAtlPreviewCtrlImpl::SetPreviewVisuals", "ATLPREVIEWCTRLIMPL/ATL::CAtlPreviewCtrlImpl::SetRect", "ATLPREVIEWCTRLIMPL/ATL::CAtlPreviewCtrlImpl::DoPaint", "ATLPREVIEWCTRLIMPL/ATL::CAtlPreviewCtrlImpl::m_plf", "ATLPREVIEWCTRLIMPL/ATL::CAtlPreviewCtrlImpl::m_clrBack", "ATLPREVIEWCTRLIMPL/ATL::CAtlPreviewCtrlImpl::m_clrText"] diff --git a/docs/atl/reference/catlservicemodulet-class.md b/docs/atl/reference/catlservicemodulet-class.md index 20f4280c90..8931b81512 100644 --- a/docs/atl/reference/catlservicemodulet-class.md +++ b/docs/atl/reference/catlservicemodulet-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAtlServiceModuleT Class" title: "CAtlServiceModuleT Class" ms.date: "05/06/2019" f1_keywords: ["CAtlServiceModuleT", "ATLBASE/ATL::CAtlServiceModuleT", "ATLBASE/ATL::CAtlServiceModuleT::CAtlServiceModuleT", "ATLBASE/ATL::CAtlServiceModuleT::Handler", "ATLBASE/ATL::CAtlServiceModuleT::InitializeSecurity", "ATLBASE/ATL::CAtlServiceModuleT::Install", "ATLBASE/ATL::CAtlServiceModuleT::IsInstalled", "ATLBASE/ATL::CAtlServiceModuleT::LogEvent", "ATLBASE/ATL::CAtlServiceModuleT::OnContinue", "ATLBASE/ATL::CAtlServiceModuleT::OnInterrogate", "ATLBASE/ATL::CAtlServiceModuleT::OnPause", "ATLBASE/ATL::CAtlServiceModuleT::OnShutdown", "ATLBASE/ATL::CAtlServiceModuleT::OnStop", "ATLBASE/ATL::CAtlServiceModuleT::OnUnknownRequest", "ATLBASE/ATL::CAtlServiceModuleT::ParseCommandLine", "ATLBASE/ATL::CAtlServiceModuleT::PreMessageLoop", "ATLBASE/ATL::CAtlServiceModuleT::RegisterAppId", "ATLBASE/ATL::CAtlServiceModuleT::Run", "ATLBASE/ATL::CAtlServiceModuleT::ServiceMain", "ATLBASE/ATL::CAtlServiceModuleT::SetServiceStatus", "ATLBASE/ATL::CAtlServiceModuleT::Start", "ATLBASE/ATL::CAtlServiceModuleT::Uninstall", "ATLBASE/ATL::CAtlServiceModuleT::Unlock", "ATLBASE/ATL::CAtlServiceModuleT::UnregisterAppId", "ATLBASE/ATL::CAtlServiceModuleT::WinMain", "ATLBASE/ATL::CAtlServiceModuleT::m_bService", "ATLBASE/ATL::CAtlServiceModuleT::m_dwThreadID", "ATLBASE/ATL::CAtlServiceModuleT::m_hServiceStatus", "ATLBASE/ATL::CAtlServiceModuleT::m_status", "ATLBASE/ATL::CAtlServiceModuleT::m_szServiceName"] diff --git a/docs/atl/reference/catltemporaryfile-class.md b/docs/atl/reference/catltemporaryfile-class.md index 30b12eedcf..9878d4a0d9 100644 --- a/docs/atl/reference/catltemporaryfile-class.md +++ b/docs/atl/reference/catltemporaryfile-class.md @@ -1,9 +1,9 @@ --- 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 @@ -356,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 83645c2a65..4c4430bf45 100644 --- a/docs/atl/reference/catltransactionmanager-class.md +++ b/docs/atl/reference/catltransactionmanager-class.md @@ -1,9 +1,9 @@ --- title: "CAtlTransactionManager Class" -ms.date: "11/04/2016" +description: "Learn more about: CAtlTransactionManager Class" +ms.date: 11/04/2016 f1_keywords: ["CAtlTransactionManager", "ATLTRANSACTIONMANAGER/ATL::CAtlTransactionManager", "ATLTRANSACTIONMANAGER/ATL::Close", "ATLTRANSACTIONMANAGER/ATL::Commit", "ATLTRANSACTIONMANAGER/ATL::Create", "ATLTRANSACTIONMANAGER/ATL::CreateFile", "ATLTRANSACTIONMANAGER/ATL::DeleteFile", "ATLTRANSACTIONMANAGER/ATL::FindFirstFile", "ATLTRANSACTIONMANAGER/ATL::GetFileAttributes", "ATLTRANSACTIONMANAGER/ATL::GetFileAttributesEx", "ATLTRANSACTIONMANAGER/ATL::GetHandle", "ATLTRANSACTIONMANAGER/ATL::IsFallback", "ATLTRANSACTIONMANAGER/ATL::MoveFile", "ATLTRANSACTIONMANAGER/ATL::RegCreateKeyEx", "ATLTRANSACTIONMANAGER/ATL::RegDeleteKey", "ATLTRANSACTIONMANAGER/ATL::RegOpenKeyEx", "ATLTRANSACTIONMANAGER/ATL::Rollback", "ATLTRANSACTIONMANAGER/ATL::SetFileAttributes", "ATLTRANSACTIONMANAGER/ATL::m_bFallback", "ATLTRANSACTIONMANAGER/ATL::m_hTransaction"] helpviewer_keywords: ["CAtlTransactionManager class"] -ms.assetid: b01732dc-1d16-4b42-bfac-b137fca2b740 --- # CAtlTransactionManager Class @@ -65,7 +65,7 @@ class CAtlTransactionManager; **Header:** atltransactionmanager.h -## ~CAtlTransactionManager +## ~CAtlTransactionManager CAtlTransactionManager destructor. @@ -164,7 +164,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/catlwinmodule-class.md b/docs/atl/reference/catlwinmodule-class.md index cc0ad3af5c..fe46bab7a8 100644 --- a/docs/atl/reference/catlwinmodule-class.md +++ b/docs/atl/reference/catlwinmodule-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAtlWinModule Class" title: "CAtlWinModule Class" ms.date: "11/04/2016" f1_keywords: ["CAtlWinModule", "ATLBASE/ATL::CAtlWinModule", "ATLBASE/ATL::CAtlWinModule::CAtlWinModule", "ATLBASE/ATL::CAtlWinModule::AddCreateWndData", "ATLBASE/ATL::CAtlWinModule::ExtractCreateWndData"] diff --git a/docs/atl/reference/cautoptr-class.md b/docs/atl/reference/cautoptr-class.md index e3c2269de9..ec51839b4b 100644 --- a/docs/atl/reference/cautoptr-class.md +++ b/docs/atl/reference/cautoptr-class.md @@ -1,11 +1,12 @@ --- -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. @@ -21,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 @@ -75,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. @@ -85,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. @@ -115,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 @@ -127,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. @@ -139,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. @@ -149,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`. @@ -171,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. @@ -185,7 +186,7 @@ T* m_p; This member variable holds the pointer information. -## CAutoPtr::operator = +## `CAutoPtr::operator =` The assignment operator. @@ -199,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. @@ -225,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 @@ -235,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. @@ -245,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/cautoptrarray-class.md b/docs/atl/reference/cautoptrarray-class.md index 880b8bab26..cadb53e14a 100644 --- a/docs/atl/reference/cautoptrarray-class.md +++ b/docs/atl/reference/cautoptrarray-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAutoPtrArray Class" title: "CAutoPtrArray Class" ms.date: "11/04/2016" f1_keywords: ["CAutoPtrArray", "ATLCOLL/ATL::CAutoPtrArray", "ATLCOLL/ATL::CAutoPtrArray::CAutoPtrArray"] diff --git a/docs/atl/reference/cautoptrelementtraits-class.md b/docs/atl/reference/cautoptrelementtraits-class.md index 5f58b4a2be..90b8dbbea8 100644 --- a/docs/atl/reference/cautoptrelementtraits-class.md +++ b/docs/atl/reference/cautoptrelementtraits-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAutoPtrElementTraits Class" title: "CAutoPtrElementTraits Class" ms.date: "11/04/2016" f1_keywords: ["CAutoPtrElementTraits", "ATLCOLL/ATL::CAutoPtrElementTraits", "ATLCOLL/ATL::CAutoPtrElementTraits::INARGTYPE", "ATLCOLL/ATL::CAutoPtrElementTraits::OUTARGTYPE"] diff --git a/docs/atl/reference/cautoptrlist-class.md b/docs/atl/reference/cautoptrlist-class.md index ac317408f1..c2b8e2a7d2 100644 --- a/docs/atl/reference/cautoptrlist-class.md +++ b/docs/atl/reference/cautoptrlist-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAutoPtrList Class" title: "CAutoPtrList Class" ms.date: "11/04/2016" f1_keywords: ["CAutoPtrList", "ATLCOLL/ATL::CAutoPtrList", "ATLCOLL/ATL::CAutoPtrList::CAutoPtrList"] diff --git a/docs/atl/reference/cautorevertimpersonation-class.md b/docs/atl/reference/cautorevertimpersonation-class.md index e438153196..6f63d12451 100644 --- a/docs/atl/reference/cautorevertimpersonation-class.md +++ b/docs/atl/reference/cautorevertimpersonation-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAutoRevertImpersonation Class" title: "CAutoRevertImpersonation Class" ms.date: "11/04/2016" f1_keywords: ["CAutoRevertImpersonation", "ATLSECURITY/ATL::CAutoRevertImpersonation", "ATLSECURITY/ATL::CAutoRevertImpersonation::CAutoRevertImpersonation", "ATLSECURITY/ATL::CAutoRevertImpersonation::Attach", "ATLSECURITY/ATL::CAutoRevertImpersonation::Detach", "ATLSECURITY/ATL::CAutoRevertImpersonation::GetAccessToken"] diff --git a/docs/atl/reference/cautovectorptr-class.md b/docs/atl/reference/cautovectorptr-class.md index 35de635a4f..be4c474bcc 100644 --- a/docs/atl/reference/cautovectorptr-class.md +++ b/docs/atl/reference/cautovectorptr-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAutoVectorPtr Class" title: "CAutoVectorPtr Class" ms.date: "11/04/2016" f1_keywords: ["CAutoVectorPtr", "ATLBASE/ATL::CAutoVectorPtr", "ATLBASE/ATL::CAutoVectorPtr::CAutoVectorPtr", "ATLBASE/ATL::CAutoVectorPtr::Allocate", "ATLBASE/ATL::CAutoVectorPtr::Attach", "ATLBASE/ATL::CAutoVectorPtr::Detach", "ATLBASE/ATL::CAutoVectorPtr::Free", "ATLBASE/ATL::CAutoVectorPtr::m_p"] @@ -57,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/cautovectorptrelementtraits-class.md b/docs/atl/reference/cautovectorptrelementtraits-class.md index 44342da5f9..86e766db0b 100644 --- a/docs/atl/reference/cautovectorptrelementtraits-class.md +++ b/docs/atl/reference/cautovectorptrelementtraits-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAutoVectorPtrElementTraits Class" title: "CAutoVectorPtrElementTraits Class" ms.date: "11/04/2016" f1_keywords: ["CAutoVectorPtrElementTraits", "ATLCOLL/ATL::CAutoVectorPtrElementTraits", "ATLCOLL/ATL::CAutoVectorPtrElementTraits::INARGTYPE", "ATLCOLL/ATL::CAutoVectorPtrElementTraits::OUTARGTYPE"] diff --git a/docs/atl/reference/caxdialogimpl-class.md b/docs/atl/reference/caxdialogimpl-class.md index 264dd77b8c..76937ed12b 100644 --- a/docs/atl/reference/caxdialogimpl-class.md +++ b/docs/atl/reference/caxdialogimpl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAxDialogImpl Class" title: "CAxDialogImpl Class" ms.date: "11/04/2016" f1_keywords: ["CAxDialogImpl", "ATLWIN/ATL::CAxDialogImpl", "ATLWIN/ATL::CAxDialogImpl::AdviseSinkMap", "ATLWIN/ATL::CAxDialogImpl::Create", "ATLWIN/ATL::CAxDialogImpl::DestroyWindow", "ATLWIN/ATL::CAxDialogImpl::DoModal", "ATLWIN/ATL::CAxDialogImpl::EndDialog", "ATLWIN/ATL::CAxDialogImpl::GetDialogProc", "ATLWIN/ATL::CAxDialogImpl::GetIDD", "ATLWIN/ATL::CAxDialogImpl::IsDialogMessage", "ATLWIN/ATL::CAxDialogImpl::m_bModal"] @@ -64,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 e1d0ff1892..1817a66fc3 100644 --- a/docs/atl/reference/caxwindow-class.md +++ b/docs/atl/reference/caxwindow-class.md @@ -1,9 +1,16 @@ --- +description: "Learn more about: CAxWindow Class" title: "CAxWindow Class" 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 @@ -22,7 +29,7 @@ class CAxWindow : public CWindow ### Methods -||| +|Function|Description| |-|-| |[AttachControl](#attachcontrol)|Attaches an existing ActiveX control to the `CAxWindow` object.| |[CAxWindow](#caxwindow)|Constructs a `CAxWindow` object.| @@ -36,7 +43,7 @@ class CAxWindow : public CWindow ### Operators -||| +|Operator|Description| |-|-| |[operator =](#operator_eq)|Assigns an HWND to an existing `CAxWindow` object.| @@ -152,7 +159,7 @@ See [CAxWindow2T::CreateControlLic](../../atl/reference/caxwindow2t-class.md#cre ### Example -See [Hosting ActiveX Controls Using ATL AXHost](../../atl/hosting-activex-controls-using-atl-axhost.md) 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 @@ -224,7 +231,7 @@ See [CAxWindow2T::CreateControlLicEx](../../atl/reference/caxwindow2t-class.md#c ### Example -See [Hosting ActiveX Controls Using ATL AXHost](../../atl/hosting-activex-controls-using-atl-axhost.md) 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 @@ -353,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 85ae94b8cc..866f52ad95 100644 --- a/docs/atl/reference/caxwindow2t-class.md +++ b/docs/atl/reference/caxwindow2t-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CAxWindow2T Class" title: "CAxWindow2T Class" ms.date: "11/04/2016" f1_keywords: ["CAxWindow2T", "ATLWIN/ATL::CAxWindow2T", "ATLWIN/ATL::CAxWindow2T::CAxWindow2T", "ATLWIN/ATL::CAxWindow2T::Create", "ATLWIN/ATL::CAxWindow2T::CreateControlLic", "ATLWIN/ATL::CAxWindow2T::CreateControlLicEx", "ATLWIN/ATL::CAxWindow2T::GetWndClassName"] @@ -59,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/hosting-activex-controls-using-atl-axhost.md) 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 @@ -111,7 +112,7 @@ See `CWindow::Create` for a description of the parameters and return value. ### Example -See [Hosting ActiveX Controls Using ATL AXHost](../../atl/hosting-activex-controls-using-atl-axhost.md) 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 @@ -142,7 +143,7 @@ See [CAxWindow::CreateControl](../../atl/reference/caxwindow-class.md#createcont ### Example -See [Hosting ActiveX Controls Using ATL AXHost](../../atl/hosting-activex-controls-using-atl-axhost.md) 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 @@ -179,7 +180,7 @@ See [CAxWindow::CreateControlEx](../../atl/reference/caxwindow-class.md#createco ### Example -See [Hosting ActiveX Controls Using ATL AXHost](../../atl/hosting-activex-controls-using-atl-axhost.md) 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 @@ -209,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/cbindstatuscallback-class.md b/docs/atl/reference/cbindstatuscallback-class.md index ade19ae4da..1de6349c0c 100644 --- a/docs/atl/reference/cbindstatuscallback-class.md +++ b/docs/atl/reference/cbindstatuscallback-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CBindStatusCallback Class" title: "CBindStatusCallback Class" ms.date: "11/04/2016" f1_keywords: ["CBindStatusCallback", "ATLCTL/ATL::CBindStatusCallback", "ATLCTL/ATL::CBindStatusCallback::CBindStatusCallback", "ATLCTL/ATL::CBindStatusCallback::Download", "ATLCTL/ATL::CBindStatusCallback::GetBindInfo", "ATLCTL/ATL::CBindStatusCallback::GetPriority", "ATLCTL/ATL::CBindStatusCallback::OnDataAvailable", "ATLCTL/ATL::CBindStatusCallback::OnLowResource", "ATLCTL/ATL::CBindStatusCallback::OnObjectAvailable", "ATLCTL/ATL::CBindStatusCallback::OnProgress", "ATLCTL/ATL::CBindStatusCallback::OnStartBinding", "ATLCTL/ATL::CBindStatusCallback::OnStopBinding", "ATLCTL/ATL::CBindStatusCallback::StartAsyncDownload", "ATLCTL/ATL::CBindStatusCallback::m_dwAvailableToRead", "ATLCTL/ATL::CBindStatusCallback::m_dwTotalRead", "ATLCTL/ATL::CBindStatusCallback::m_pFunc", "ATLCTL/ATL::CBindStatusCallback::m_pT", "ATLCTL/ATL::CBindStatusCallback::m_spBindCtx", "ATLCTL/ATL::CBindStatusCallback::m_spBinding", "ATLCTL/ATL::CBindStatusCallback::m_spMoniker", "ATLCTL/ATL::CBindStatusCallback::m_spStream"] diff --git a/docs/atl/reference/ccomaggobject-class.md b/docs/atl/reference/ccomaggobject-class.md index ebc212701e..b6eefe7233 100644 --- a/docs/atl/reference/ccomaggobject-class.md +++ b/docs/atl/reference/ccomaggobject-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComAggObject Class" title: "CComAggObject Class" ms.date: "11/04/2016" f1_keywords: ["CComAggObject", "ATLCOM/ATL::CComAggObject", "ATLCOM/ATL::CComAggObject::CComAggObject", "ATLCOM/ATL::CComAggObject::AddRef", "ATLCOM/ATL::CComAggObject::CreateInstance", "ATLCOM/ATL::CComAggObject::FinalConstruct", "ATLCOM/ATL::CComAggObject::FinalRelease", "ATLCOM/ATL::CComAggObject::QueryInterface", "ATLCOM/ATL::CComAggObject::Release", "ATLCOM/ATL::CComAggObject::m_contained"] diff --git a/docs/atl/reference/ccomallocator-class.md b/docs/atl/reference/ccomallocator-class.md index fd94c2885b..c29ebdbe01 100644 --- a/docs/atl/reference/ccomallocator-class.md +++ b/docs/atl/reference/ccomallocator-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComAllocator Class" title: "CComAllocator Class" ms.date: "11/04/2016" f1_keywords: ["CComAllocator", "ATLBASE/ATL::CComAllocator", "ATLBASE/ATL::CComAllocator::Allocate", "ATLBASE/ATL::CComAllocator::Free", "ATLBASE/ATL::CComAllocator::Reallocate"] diff --git a/docs/atl/reference/ccomapartment-class.md b/docs/atl/reference/ccomapartment-class.md index a510ef6ee6..b49417cff8 100644 --- a/docs/atl/reference/ccomapartment-class.md +++ b/docs/atl/reference/ccomapartment-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComApartment Class" title: "CComApartment Class" ms.date: "11/04/2016" f1_keywords: ["CComApartment", "ATLBASE/ATL::CComApartment", "ATLBASE/ATL::CComApartment::CComApartment", "ATLBASE/ATL::CComApartment::Apartment", "ATLBASE/ATL::CComApartment::GetLockCount", "ATLBASE/ATL::CComApartment::Lock", "ATLBASE/ATL::CComApartment::Unlock", "ATLBASE/ATL::CComApartment::m_dwThreadID", "ATLBASE/ATL::CComApartment::m_hThread", "ATLBASE/ATL::CComApartment::m_nLockCnt"] diff --git a/docs/atl/reference/ccomautocriticalsection-class.md b/docs/atl/reference/ccomautocriticalsection-class.md index cf88a1c757..1307f3e999 100644 --- a/docs/atl/reference/ccomautocriticalsection-class.md +++ b/docs/atl/reference/ccomautocriticalsection-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComAutoCriticalSection Class" title: "CComAutoCriticalSection Class" ms.date: "11/04/2016" f1_keywords: ["CComAutoCriticalSection", "ATLCORE/ATL::CComAutoCriticalSection", "ATLCORE/ATL::CComAutoCriticalSection::CComAutoCriticalSection"] diff --git a/docs/atl/reference/ccomautodeletecriticalsection-class.md b/docs/atl/reference/ccomautodeletecriticalsection-class.md index 2095a3ba54..b7ab596a45 100644 --- a/docs/atl/reference/ccomautodeletecriticalsection-class.md +++ b/docs/atl/reference/ccomautodeletecriticalsection-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComAutoDeleteCriticalSection Class" title: "CComAutoDeleteCriticalSection Class" ms.date: "11/04/2016" f1_keywords: ["CComAutoDeleteCriticalSection", "atlcore/ATL::CComAutoDeleteCriticalSection"] diff --git a/docs/atl/reference/ccomautothreadmodule-class.md b/docs/atl/reference/ccomautothreadmodule-class.md index 689dcd9caf..4cff4d76b9 100644 --- a/docs/atl/reference/ccomautothreadmodule-class.md +++ b/docs/atl/reference/ccomautothreadmodule-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComAutoThreadModule Class" title: "CComAutoThreadModule Class" ms.date: "11/04/2016" f1_keywords: ["CComAutoThreadModule", "ATLBASE/ATL::CComAutoThreadModule", "ATLBASE/ATL::CreateInstance", "ATLBASE/ATL::GetDefaultThreads", "ATLBASE/ATL::Init", "ATLBASE/ATL::Lock", "ATLBASE/ATL::Unlock", "ATLBASE/ATL::dwThreadID", "ATLBASE/ATL::m_Allocator", "ATLBASE/ATL::m_nThreads", "ATLBASE/ATL::m_pApartments"] @@ -28,7 +29,7 @@ class CComAutoThreadModule : public CComModule ### Methods -||| +|Function|Description| |-|-| |[CreateInstance](#createinstance)|Selects a thread and then creates an object in the associated apartment.| |[GetDefaultThreads](#getdefaultthreads)|(Static) Dynamically calculates the number of threads for the module based on the number of processors.| @@ -38,9 +39,7 @@ class CComAutoThreadModule : public CComModule ### Data Members -### Data Members - -||| +|Data member|Description| |-|-| |[dwThreadID](#dwthreadid)|Contains the identifier of the current thread.| |[m_Allocator](#m_allocator)|Manages thread selection.| diff --git a/docs/atl/reference/ccombstr-class.md b/docs/atl/reference/ccombstr-class.md index 1d4191aa01..14c7a7e8d8 100644 --- a/docs/atl/reference/ccombstr-class.md +++ b/docs/atl/reference/ccombstr-class.md @@ -1,13 +1,14 @@ --- +description: "Learn more about: CComBSTR Class" title: "CComBSTR Class" ms.date: "11/04/2016" f1_keywords: ["CComBSTR", "ATLBASE/ATL::CComBSTR", "ATLBASE/ATL::CComBSTR::CComBSTR", "ATLBASE/ATL::CComBSTR::Append", "ATLBASE/ATL::CComBSTR::AppendBSTR", "ATLBASE/ATL::CComBSTR::AppendBytes", "ATLBASE/ATL::CComBSTR::ArrayToBSTR", "ATLBASE/ATL::CComBSTR::AssignBSTR", "ATLBASE/ATL::CComBSTR::Attach", "ATLBASE/ATL::CComBSTR::BSTRToArray", "ATLBASE/ATL::CComBSTR::ByteLength", "ATLBASE/ATL::CComBSTR::Copy", "ATLBASE/ATL::CComBSTR::CopyTo", "ATLBASE/ATL::CComBSTR::Detach", "ATLBASE/ATL::CComBSTR::Empty", "ATLBASE/ATL::CComBSTR::Length", "ATLBASE/ATL::CComBSTR::LoadString", "ATLBASE/ATL::CComBSTR::ReadFromStream", "ATLBASE/ATL::CComBSTR::ToLower", "ATLBASE/ATL::CComBSTR::ToUpper", "ATLBASE/ATL::CComBSTR::WriteToStream", "ATLBASE/ATL::CComBSTR::m_str"] 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 @@ -21,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. @@ -79,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(); @@ -100,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 @@ -124,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(); @@ -134,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 @@ -149,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(); @@ -159,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(); @@ -183,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(); @@ -200,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(); @@ -217,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 @@ -231,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. @@ -241,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. @@ -258,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(); @@ -286,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. @@ -315,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. @@ -327,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`. @@ -337,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(); @@ -355,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(); @@ -383,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(); @@ -401,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. @@ -411,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(); @@ -428,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; @@ -454,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(); @@ -464,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(); @@ -480,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(); @@ -503,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(); @@ -530,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 @@ -540,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. @@ -551,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. @@ -577,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); @@ -596,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. @@ -615,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. @@ -642,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(); @@ -658,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. @@ -683,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. @@ -699,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(); @@ -715,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/ccomcachedtearoffobject-class.md b/docs/atl/reference/ccomcachedtearoffobject-class.md index 9bd762b1ff..26e8f9526d 100644 --- a/docs/atl/reference/ccomcachedtearoffobject-class.md +++ b/docs/atl/reference/ccomcachedtearoffobject-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComCachedTearOffObject Class" title: "CComCachedTearOffObject Class" ms.date: "11/04/2016" f1_keywords: ["CComCachedTearOffObject", "ATLCOM/ATL::CComCachedTearOffObject", "ATLCOM/ATL::CComCachedTearOffObject::CComCachedTearOffObject", "ATLCOM/ATL::CComCachedTearOffObject::AddRef", "ATLCOM/ATL::CComCachedTearOffObject::FinalConstruct", "ATLCOM/ATL::CComCachedTearOffObject::FinalRelease", "ATLCOM/ATL::CComCachedTearOffObject::QueryInterface", "ATLCOM/ATL::CComCachedTearOffObject::Release", "ATLCOM/ATL::CComCachedTearOffObject::m_contained"] diff --git a/docs/atl/reference/ccomclassfactory-class.md b/docs/atl/reference/ccomclassfactory-class.md index bd54bb607c..02636d54b1 100644 --- a/docs/atl/reference/ccomclassfactory-class.md +++ b/docs/atl/reference/ccomclassfactory-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComClassFactory Class" title: "CComClassFactory Class" ms.date: "11/04/2016" f1_keywords: ["CComClassFactory", "ATLCOM/ATL::CComClassFactory", "ATLCOM/ATL::CComClassFactory::CreateInstance", "ATLCOM/ATL::CComClassFactory::LockServer"] diff --git a/docs/atl/reference/ccomclassfactory2-class.md b/docs/atl/reference/ccomclassfactory2-class.md index ce3062c6e4..6a40fbd71e 100644 --- a/docs/atl/reference/ccomclassfactory2-class.md +++ b/docs/atl/reference/ccomclassfactory2-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComClassFactory2 Class" title: "CComClassFactory2 Class" ms.date: "11/04/2016" f1_keywords: ["CComClassFactory2", "ATLCOM/ATL::CComClassFactory2", "ATLCOM/ATL::CComClassFactory2::CreateInstance", "ATLCOM/ATL::CComClassFactory2::CreateInstanceLic", "ATLCOM/ATL::CComClassFactory2::GetLicInfo", "ATLCOM/ATL::CComClassFactory2::LockServer", "ATLCOM/ATL::CComClassFactory2::RequestLicKey"] diff --git a/docs/atl/reference/ccomclassfactoryautothread-class.md b/docs/atl/reference/ccomclassfactoryautothread-class.md index d785208336..af076db252 100644 --- a/docs/atl/reference/ccomclassfactoryautothread-class.md +++ b/docs/atl/reference/ccomclassfactoryautothread-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComClassFactoryAutoThread Class" title: "CComClassFactoryAutoThread Class" ms.date: "11/04/2016" f1_keywords: ["CComClassFactoryAutoThread", "ATLCOM/ATL::CComClassFactoryAutoThread", "ATLCOM/ATL::CComClassFactoryAutoThread::CreateInstance", "ATLCOM/ATL::CComClassFactoryAutoThread::LockServer"] diff --git a/docs/atl/reference/ccomclassfactorysingleton-class.md b/docs/atl/reference/ccomclassfactorysingleton-class.md index a46f70d061..7559d27a59 100644 --- a/docs/atl/reference/ccomclassfactorysingleton-class.md +++ b/docs/atl/reference/ccomclassfactorysingleton-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComClassFactorySingleton Class" title: "CComClassFactorySingleton Class" ms.date: "11/04/2016" f1_keywords: ["CComClassFactorySingleton", "ATLCOM/ATL::CComClassFactorySingleton", "ATLCOM/ATL::CComClassFactorySingleton::CreateInstance", "ATLCOM/ATL::CComClassFactorySingleton::m_spObj"] diff --git a/docs/atl/reference/ccomcoclass-class.md b/docs/atl/reference/ccomcoclass-class.md index fd521ea7b0..2101a31f89 100644 --- a/docs/atl/reference/ccomcoclass-class.md +++ b/docs/atl/reference/ccomcoclass-class.md @@ -1,9 +1,9 @@ --- 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 @@ -11,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 @@ -57,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 @@ -100,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, @@ -129,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, @@ -142,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 @@ -169,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* **)**. @@ -177,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(); ``` @@ -189,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/ccomcompositecontrol-class.md b/docs/atl/reference/ccomcompositecontrol-class.md index 482eafac89..d2899ea4af 100644 --- a/docs/atl/reference/ccomcompositecontrol-class.md +++ b/docs/atl/reference/ccomcompositecontrol-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComCompositeControl Class" title: "CComCompositeControl Class" ms.date: "11/04/2016" f1_keywords: ["CComCompositeControl", "ATLCTL/ATL::CComCompositeControl", "ATLCTL/ATL::CComCompositeControl::CComCompositeControl", "ATLCTL/ATL::CComCompositeControl::AdviseSinkMap", "ATLCTL/ATL::CComCompositeControl::CalcExtent", "ATLCTL/ATL::CComCompositeControl::Create", "ATLCTL/ATL::CComCompositeControl::CreateControlWindow", "ATLCTL/ATL::CComCompositeControl::SetBackgroundColorFromAmbient", "ATLCTL/ATL::CComCompositeControl::m_hbrBackground", "ATLCTL/ATL::CComCompositeControl::m_hWndFocus"] @@ -99,14 +100,14 @@ True if all controls are to be advised; otherwise false. ### Return Value -||| -|-|-| -|S_OK |All controls in the event sink map were connected or disconnected from their event source successfully.| -|E_FAIL |Not all controls in the event sink map could be connected or disconnected from their event source successfully.| -|E_POINTER |This error usually indicates a problem with an entry in the control's event sink map or a problem with a template argument used in an `IDispEventImpl` or `IDispEventSimpleImpl` base class.| -|CONNECT_E_ADVISELIMIT |The connection point has already reached its limit of connections and cannot accept any more.| -|CONNECT_E_CANNOTCONNECT |The sink does not support the interface required by this connection point.| -|CONNECT_E_NOCONNECTION |The cookie value does not represent a valid connection. This error usually indicates a problem with an entry in the control's event sink map or a problem with a template argument used in an `IDispEventImpl` or `IDispEventSimpleImpl` base class.| +| Value | Description | +|--|--| +| `S_OK` | All controls in the event sink map were connected or disconnected from their event source successfully. | +| `E_FAIL` | Not all controls in the event sink map could be connected or disconnected from their event source successfully. | +| `E_POINTER` | This error usually indicates a problem with an entry in the control's event sink map or a problem with a template argument used in an `IDispEventImpl` or `IDispEventSimpleImpl` base class. | +| `CONNECT_E_ADVISELIMIT` | The connection point has already reached its limit of connections and cannot accept any more. | +| `CONNECT_E_CANNOTCONNECT` | The sink does not support the interface required by this connection point. | +| `CONNECT_E_NOCONNECTION` | The cookie value does not represent a valid connection. This error usually indicates a problem with an entry in the control's event sink map or a problem with a template argument used in an `IDispEventImpl` or `IDispEventSimpleImpl` base class. | ### Remarks diff --git a/docs/atl/reference/ccomcontainedobject-class.md b/docs/atl/reference/ccomcontainedobject-class.md index d2ea040eb6..1f6f7008ce 100644 --- a/docs/atl/reference/ccomcontainedobject-class.md +++ b/docs/atl/reference/ccomcontainedobject-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComContainedObject Class" title: "CComContainedObject Class" ms.date: "11/04/2016" f1_keywords: ["CComContainedObject", "ATLCOM/ATL::CComContainedObject", "ATLCOM/ATL::CComContainedObject::CComContainedObject", "ATLCOM/ATL::CComContainedObject::AddRef", "ATLCOM/ATL::CComContainedObject::GetControllingUnknown", "ATLCOM/ATL::CComContainedObject::QueryInterface", "ATLCOM/ATL::CComContainedObject::Release"] diff --git a/docs/atl/reference/ccomcontrol-class.md b/docs/atl/reference/ccomcontrol-class.md index 4af4e3f7f9..4c3cba00c3 100644 --- a/docs/atl/reference/ccomcontrol-class.md +++ b/docs/atl/reference/ccomcontrol-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComControl Class" title: "CComControl Class" ms.date: "11/04/2016" f1_keywords: ["CComControl", "ATLCTL/ATL::CComControl", "ATLCTL/ATL::CComControl::CComControl", "ATLCTL/ATL::CComControl::ControlQueryInterface", "ATLCTL/ATL::CComControl::CreateControlWindow", "ATLCTL/ATL::CComControl::FireOnChanged", "ATLCTL/ATL::CComControl::FireOnRequestEdit", "ATLCTL/ATL::CComControl::MessageBox"] diff --git a/docs/atl/reference/ccomcontrolbase-class.md b/docs/atl/reference/ccomcontrolbase-class.md index edc35120c0..f65f6c90ee 100644 --- a/docs/atl/reference/ccomcontrolbase-class.md +++ b/docs/atl/reference/ccomcontrolbase-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComControlBase Class" title: "CComControlBase Class" ms.date: "11/04/2016" f1_keywords: ["CComControlBase", "ATLCTL/ATL::CComControlBase", "ATLCTL/ATL::CComControlBase::AppearanceType", "ATLCTL/ATL::CComControlBase::CComControlBase", "ATLCTL/ATL::CComControlBase::ControlQueryInterface", "ATLCTL/ATL::CComControlBase::DoesVerbActivate", "ATLCTL/ATL::CComControlBase::DoesVerbUIActivate", "ATLCTL/ATL::CComControlBase::DoVerbProperties", "ATLCTL/ATL::CComControlBase::FireViewChange", "ATLCTL/ATL::CComControlBase::GetAmbientAppearance", "ATLCTL/ATL::CComControlBase::GetAmbientAutoClip", "ATLCTL/ATL::CComControlBase::GetAmbientBackColor", "ATLCTL/ATL::CComControlBase::GetAmbientCharSet", "ATLCTL/ATL::CComControlBase::GetAmbientCodePage", "ATLCTL/ATL::CComControlBase::GetAmbientDisplayAsDefault", "ATLCTL/ATL::CComControlBase::GetAmbientDisplayName", "ATLCTL/ATL::CComControlBase::GetAmbientFont", "ATLCTL/ATL::CComControlBase::GetAmbientFontDisp", "ATLCTL/ATL::CComControlBase::GetAmbientForeColor", "ATLCTL/ATL::CComControlBase::GetAmbientLocaleID", "ATLCTL/ATL::CComControlBase::GetAmbientMessageReflect", "ATLCTL/ATL::CComControlBase::GetAmbientPalette", "ATLCTL/ATL::CComControlBase::GetAmbientProperty", "ATLCTL/ATL::CComControlBase::GetAmbientRightToLeft", "ATLCTL/ATL::CComControlBase::GetAmbientScaleUnits", "ATLCTL/ATL::CComControlBase::GetAmbientShowGrabHandles", "ATLCTL/ATL::CComControlBase::GetAmbientShowHatching", "ATLCTL/ATL::CComControlBase::GetAmbientSupportsMnemonics", "ATLCTL/ATL::CComControlBase::GetAmbientTextAlign", "ATLCTL/ATL::CComControlBase::GetAmbientTopToBottom", "ATLCTL/ATL::CComControlBase::GetAmbientUIDead", "ATLCTL/ATL::CComControlBase::GetAmbientUserMode", "ATLCTL/ATL::CComControlBase::GetDirty", "ATLCTL/ATL::CComControlBase::GetZoomInfo", "ATLCTL/ATL::CComControlBase::InPlaceActivate", "ATLCTL/ATL::CComControlBase::InternalGetSite", "ATLCTL/ATL::CComControlBase::OnDraw", "ATLCTL/ATL::CComControlBase::OnDrawAdvanced", "ATLCTL/ATL::CComControlBase::OnKillFocus", "ATLCTL/ATL::CComControlBase::OnMouseActivate", "ATLCTL/ATL::CComControlBase::OnPaint", "ATLCTL/ATL::CComControlBase::OnSetFocus", "ATLCTL/ATL::CComControlBase::PreTranslateAccelerator", "ATLCTL/ATL::CComControlBase::SendOnClose", "ATLCTL/ATL::CComControlBase::SendOnDataChange", "ATLCTL/ATL::CComControlBase::SendOnRename", "ATLCTL/ATL::CComControlBase::SendOnSave", "ATLCTL/ATL::CComControlBase::SendOnViewChange", "ATLCTL/ATL::CComControlBase::SetControlFocus", "ATLCTL/ATL::CComControlBase::SetDirty", "ATLCTL/ATL::CComControlBase::m_bAutoSize", "ATLCTL/ATL::CComControlBase::m_bDrawFromNatural", "ATLCTL/ATL::CComControlBase::m_bDrawGetDataInHimetric", "ATLCTL/ATL::CComControlBase::m_bInPlaceActive", "ATLCTL/ATL::CComControlBase::m_bInPlaceSiteEx", "ATLCTL/ATL::CComControlBase::m_bNegotiatedWnd", "ATLCTL/ATL::CComControlBase::m_bRecomposeOnResize", "ATLCTL/ATL::CComControlBase::m_bRequiresSave", "ATLCTL/ATL::CComControlBase::m_bResizeNatural", "ATLCTL/ATL::CComControlBase::m_bUIActive", "ATLCTL/ATL::CComControlBase::m_bUsingWindowRgn", "ATLCTL/ATL::CComControlBase::m_bWasOnceWindowless", "ATLCTL/ATL::CComControlBase::m_bWindowOnly", "ATLCTL/ATL::CComControlBase::m_bWndLess", "ATLCTL/ATL::CComControlBase::m_hWndCD", "ATLCTL/ATL::CComControlBase::m_nFreezeEvents", "ATLCTL/ATL::CComControlBase::m_rcPos", "ATLCTL/ATL::CComControlBase::m_sizeExtent", "ATLCTL/ATL::CComControlBase::m_sizeNatural", "ATLCTL/ATL::CComControlBase::m_spAdviseSink", "ATLCTL/ATL::CComControlBase::m_spAmbientDispatch", "ATLCTL/ATL::CComControlBase::m_spClientSite", "ATLCTL/ATL::CComControlBase::m_spDataAdviseHolder", "ATLCTL/ATL::CComControlBase::m_spInPlaceSite", "ATLCTL/ATL::CComControlBase::m_spOleAdviseHolder"] @@ -251,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/ccomcriticalsection-class.md b/docs/atl/reference/ccomcriticalsection-class.md index 39822f74d3..7ee8d73ac5 100644 --- a/docs/atl/reference/ccomcriticalsection-class.md +++ b/docs/atl/reference/ccomcriticalsection-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComCriticalSection Class" title: "CComCriticalSection Class" ms.date: "11/04/2016" f1_keywords: ["CComCriticalSection", "ATLCORE/ATL::CComCriticalSection", "ATLCORE/ATL::CComCriticalSection::CComCriticalSection", "ATLCORE/ATL::CComCriticalSection::Init", "ATLCORE/ATL::CComCriticalSection::Lock", "ATLCORE/ATL::CComCriticalSection::Term", "ATLCORE/ATL::CComCriticalSection::Unlock", "ATLCORE/ATL::CComCriticalSection::m_sec"] diff --git a/docs/atl/reference/ccomcritseclock-class.md b/docs/atl/reference/ccomcritseclock-class.md index 0b75b14467..726f3bc79c 100644 --- a/docs/atl/reference/ccomcritseclock-class.md +++ b/docs/atl/reference/ccomcritseclock-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComCritSecLock Class" title: "CComCritSecLock Class" ms.date: "11/04/2016" f1_keywords: ["CComCritSecLock", "ATLBASE/ATL::CComCritSecLock", "ATLBASE/ATL::CComCritSecLock::CComCritSecLock", "ATLBASE/ATL::CComCritSecLock::Lock", "ATLBASE/ATL::CComCritSecLock::Unlock"] diff --git a/docs/atl/reference/ccomcurrency-class.md b/docs/atl/reference/ccomcurrency-class.md index 61526c0191..cee7bfd016 100644 --- a/docs/atl/reference/ccomcurrency-class.md +++ b/docs/atl/reference/ccomcurrency-class.md @@ -1,92 +1,92 @@ --- 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(); @@ -108,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. @@ -188,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; ``` @@ -200,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. @@ -314,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. @@ -335,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); @@ -439,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 @@ -624,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 3746b309ff..682edba816 100644 --- a/docs/atl/reference/ccomdynamicunkarray-class.md +++ b/docs/atl/reference/ccomdynamicunkarray-class.md @@ -1,9 +1,9 @@ --- title: "CComDynamicUnkArray Class" -ms.date: "11/04/2016" +description: "Learn more about: CComDynamicUnkArray Class" +ms.date: 11/04/2016 f1_keywords: ["CComDynamicUnkArray", "ATLCOM/ATL::CComDynamicUnkArray", "ATLCOM/ATL::CComDynamicUnkArray::CComDynamicUnkArray", "ATLCOM/ATL::CComDynamicUnkArray::Add", "ATLCOM/ATL::CComDynamicUnkArray::begin", "ATLCOM/ATL::CComDynamicUnkArray::clear", "ATLCOM/ATL::CComDynamicUnkArray::end", "ATLCOM/ATL::CComDynamicUnkArray::GetAt", "ATLCOM/ATL::CComDynamicUnkArray::GetCookie", "ATLCOM/ATL::CComDynamicUnkArray::GetSize", "ATLCOM/ATL::CComDynamicUnkArray::GetUnknown", "ATLCOM/ATL::CComDynamicUnkArray::Remove"] helpviewer_keywords: ["connection points [C++], managing", "CComDynamicUnkArray class"] -ms.assetid: 202470d7-9a1b-498f-b96d-659d681acd65 --- # CComDynamicUnkArray Class @@ -34,7 +34,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.| @@ -68,7 +68,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 @@ -91,7 +96,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(); @@ -123,7 +128,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** @@ -149,7 +156,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 @@ -174,7 +181,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; @@ -182,7 +191,7 @@ int GetSize() const; ### Return Value -The length of the array. +The number of elements the array can store. `GetSize() == end() - begin()`. ## CComDynamicUnkArray::GetUnknown @@ -205,6 +214,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 c54aec616c..874c02b84c 100644 --- a/docs/atl/reference/ccomenum-class.md +++ b/docs/atl/reference/ccomenum-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComEnum Class" title: "CComEnum Class" ms.date: "11/04/2016" f1_keywords: ["CComEnum", "atlcom/ATL::CComEnum"] @@ -75,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/ccomenumimpl-class.md b/docs/atl/reference/ccomenumimpl-class.md index 211b29fe21..904acfd49b 100644 --- a/docs/atl/reference/ccomenumimpl-class.md +++ b/docs/atl/reference/ccomenumimpl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComEnumImpl Class" title: "CComEnumImpl Class" ms.date: "11/04/2016" f1_keywords: ["CComEnumImpl", "ATLCOM/ATL::CComEnumImpl", "ATLCOM/ATL::CComEnumImpl::CComEnumImpl", "ATLCOM/ATL::CComEnumImpl::Clone", "ATLCOM/ATL::CComEnumImpl::Init", "ATLCOM/ATL::CComEnumImpl::Next", "ATLCOM/ATL::CComEnumImpl::Reset", "ATLCOM/ATL::CComEnumImpl::Skip", "ATLCOM/ATL::CComEnumImpl::m_begin", "ATLCOM/ATL::CComEnumImpl::m_dwFlags", "ATLCOM/ATL::CComEnumImpl::m_end", "ATLCOM/ATL::CComEnumImpl::m_iter", "ATLCOM/ATL::CComEnumImpl::m_spUnk"] diff --git a/docs/atl/reference/ccomenumonstl-class.md b/docs/atl/reference/ccomenumonstl-class.md index c6019606f3..7ab682b506 100644 --- a/docs/atl/reference/ccomenumonstl-class.md +++ b/docs/atl/reference/ccomenumonstl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComEnumOnSTL Class" title: "CComEnumOnSTL Class" ms.date: "11/04/2016" f1_keywords: ["CComEnumOnSTL", "atlcom/ATL::CComEnumOnSTL"] @@ -84,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/ccomfakecriticalsection-class.md b/docs/atl/reference/ccomfakecriticalsection-class.md index d793a688e3..087bc175ff 100644 --- a/docs/atl/reference/ccomfakecriticalsection-class.md +++ b/docs/atl/reference/ccomfakecriticalsection-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComFakeCriticalSection Class" title: "CComFakeCriticalSection Class" ms.date: "11/04/2016" f1_keywords: ["CComFakeCriticalSection", "ATLCORE/ATL::CComFakeCriticalSection", "ATLCORE/ATL::CComFakeCriticalSection::Init", "ATLCORE/ATL::CComFakeCriticalSection::Lock", "ATLCORE/ATL::CComFakeCriticalSection::Term", "ATLCORE/ATL::CComFakeCriticalSection::Unlock"] diff --git a/docs/atl/reference/ccomgitptr-class.md b/docs/atl/reference/ccomgitptr-class.md index 347c86c9eb..1cc42d0b16 100644 --- a/docs/atl/reference/ccomgitptr-class.md +++ b/docs/atl/reference/ccomgitptr-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComGITPtr Class" title: "CComGITPtr Class" ms.date: "11/04/2016" f1_keywords: ["CComGITPtr", "ATLBASE/ATL::CComGITPtr", "ATLBASE/ATL::CComGITPtr::CComGITPtr", "ATLBASE/ATL::CComGITPtr::Attach", "ATLBASE/ATL::CComGITPtr::CopyTo", "ATLBASE/ATL::CComGITPtr::Detach", "ATLBASE/ATL::CComGITPtr::GetCookie", "ATLBASE/ATL::CComGITPtr::Revoke", "ATLBASE/ATL::CComGITPtr::m_dwCookie"] diff --git a/docs/atl/reference/ccomheap-class.md b/docs/atl/reference/ccomheap-class.md index fe3a815080..f561ecf30d 100644 --- a/docs/atl/reference/ccomheap-class.md +++ b/docs/atl/reference/ccomheap-class.md @@ -1,43 +1,44 @@ --- +description: "Learn more about: CComHeap Class" title: "CComHeap Class" ms.date: "11/04/2016" f1_keywords: ["CComHeap", "ATLCOMMEM/ATL::CComHeap", "ATLCOMMEM/ATL::CComHeap::Allocate", "ATLCOMMEM/ATL::CComHeap::Free", "ATLCOMMEM/ATL::CComHeap::GetSize", "ATLCOMMEM/ATL::CComHeap::Reallocate"] 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` @@ -51,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/ccomheapptr-class.md b/docs/atl/reference/ccomheapptr-class.md index 0439fc2866..0edb83160e 100644 --- a/docs/atl/reference/ccomheapptr-class.md +++ b/docs/atl/reference/ccomheapptr-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComHeapPtr Class" title: "CComHeapPtr Class" ms.date: "11/04/2016" f1_keywords: ["CComHeapPtr", "ATLBASE/ATL::CComHeapPtr", "ATLBASE/ATL::CComHeapPtr::CComHeapPtr"] diff --git a/docs/atl/reference/ccommodule-class.md b/docs/atl/reference/ccommodule-class.md index e4c60b031e..eb17faf3c4 100644 --- a/docs/atl/reference/ccommodule-class.md +++ b/docs/atl/reference/ccommodule-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComModule Class" title: "CComModule Class" ms.date: "08/19/2019" f1_keywords: ["CComModule", "ATLBASE/ATL::CComModule", "ATLBASE/ATL::CComModule::GetClassObject", "ATLBASE/ATL::CComModule::GetModuleInstance", "ATLBASE/ATL::CComModule::GetResourceInstance", "ATLBASE/ATL::CComModule::GetTypeLibInstance", "ATLBASE/ATL::CComModule::Init", "ATLBASE/ATL::CComModule::RegisterClassHelper", "ATLBASE/ATL::CComModule::RegisterClassObjects", "ATLBASE/ATL::CComModule::RegisterServer", "ATLBASE/ATL::CComModule::RegisterTypeLib", "ATLBASE/ATL::CComModule::RevokeClassObjects", "ATLBASE/ATL::CComModule::Term", "ATLBASE/ATL::CComModule::UnregisterClassHelper", "ATLBASE/ATL::CComModule::UnregisterServer", "ATLBASE/ATL::CComModule::UpdateRegistryClass", "ATLBASE/ATL::CComModule::UpdateRegistryFromResourceD", "ATLBASE/ATL::CComModule::UpdateRegistryFromResourceS", "ATLBASE/ATL::CComModule::m_csObjMap", "ATLBASE/ATL::CComModule::m_csTypeInfoHolder", "ATLBASE/ATL::CComModule::m_csWindowCreate", "ATLBASE/ATL::CComModule::m_hInst", "ATLBASE/ATL::CComModule::m_hInstResource", "ATLBASE/ATL::CComModule::m_hInstTypeLib", "ATLBASE/ATL::CComModule::m_pObjMap"] diff --git a/docs/atl/reference/ccommultithreadmodel-class.md b/docs/atl/reference/ccommultithreadmodel-class.md index ff912da21f..651aa91f66 100644 --- a/docs/atl/reference/ccommultithreadmodel-class.md +++ b/docs/atl/reference/ccommultithreadmodel-class.md @@ -1,9 +1,9 @@ --- 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 @@ -11,7 +11,7 @@ ms.assetid: db8f1662-2f7a-44b3-b341-ffbfb6e422a3 ## Syntax -``` +```cpp class CComMultiThreadModel ``` @@ -34,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| |-------------|----------------------|-------------------------|--------------------| @@ -53,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; ``` @@ -119,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; ``` @@ -143,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 @@ -164,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 @@ -185,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; ``` @@ -207,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/ccommultithreadmodelnocs-class.md b/docs/atl/reference/ccommultithreadmodelnocs-class.md index 4db352ab15..9a116848ea 100644 --- a/docs/atl/reference/ccommultithreadmodelnocs-class.md +++ b/docs/atl/reference/ccommultithreadmodelnocs-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComMultiThreadModelNoCS Class" title: "CComMultiThreadModelNoCS Class" ms.date: "11/04/2016" f1_keywords: ["CComMultiThreadModelNoCS", "ATLBASE/ATL::CComMultiThreadModelNoCS", "ATLBASE/ATL::CComMultiThreadModelNoCS::AutoCriticalSection", "ATLBASE/ATL::CComMultiThreadModelNoCS::CriticalSection", "ATLBASE/ATL::CComMultiThreadModelNoCS::ThreadModelNoCS", "ATLBASE/ATL::CComMultiThreadModelNoCS::Decrement", "ATLBASE/ATL::CComMultiThreadModelNoCS::Increment"] diff --git a/docs/atl/reference/ccomobject-class.md b/docs/atl/reference/ccomobject-class.md index 145e28b3fa..940285715a 100644 --- a/docs/atl/reference/ccomobject-class.md +++ b/docs/atl/reference/ccomobject-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComObject Class" title: "CComObject Class" ms.date: "11/04/2016" f1_keywords: ["CComObject", "ATLCOM/ATL::CComObject", "ATLCOM/ATL::CComObject::CComObject", "ATLCOM/ATL::CComObject::AddRef", "ATLCOM/ATL::CComObject::CreateInstance", "ATLCOM/ATL::CComObject::QueryInterface", "ATLCOM/ATL::CComObject::Release"] @@ -124,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/ccomobjectglobal-class.md b/docs/atl/reference/ccomobjectglobal-class.md index ba40912189..14afcb2e9d 100644 --- a/docs/atl/reference/ccomobjectglobal-class.md +++ b/docs/atl/reference/ccomobjectglobal-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComObjectGlobal Class" title: "CComObjectGlobal Class" ms.date: "11/04/2016" f1_keywords: ["CComObjectGlobal", "ATLCOM/ATL::CComObjectGlobal", "ATLCOM/ATL::CComObjectGlobal::CComObjectGlobal", "ATLCOM/ATL::CComObjectGlobal::AddRef", "ATLCOM/ATL::CComObjectGlobal::QueryInterface", "ATLCOM/ATL::CComObjectGlobal::Release", "ATLCOM/ATL::CComObjectGlobal::m_hResFinalConstruct"] diff --git a/docs/atl/reference/ccomobjectnolock-class.md b/docs/atl/reference/ccomobjectnolock-class.md index c56974cb25..e98933f364 100644 --- a/docs/atl/reference/ccomobjectnolock-class.md +++ b/docs/atl/reference/ccomobjectnolock-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComObjectNoLock Class" title: "CComObjectNoLock Class" ms.date: "11/04/2016" f1_keywords: ["CComObjectNoLock", "ATLCOM/ATL::CComObjectNoLock", "ATLCOM/ATL::CComObjectNoLock::CComObjectNoLock", "ATLCOM/ATL::CComObjectNoLock::AddRef", "ATLCOM/ATL::CComObjectNoLock::QueryInterface", "ATLCOM/ATL::CComObjectNoLock::Release"] diff --git a/docs/atl/reference/ccomobjectroot-class.md b/docs/atl/reference/ccomobjectroot-class.md index 8b0775b314..5a34267e8d 100644 --- a/docs/atl/reference/ccomobjectroot-class.md +++ b/docs/atl/reference/ccomobjectroot-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComObjectRoot Class" title: "CComObjectRoot Class" ms.date: "11/04/2016" f1_keywords: ["CComObjectRoot", "atlcom/ATL::CComObjectRoot"] diff --git a/docs/atl/reference/ccomobjectrootex-class.md b/docs/atl/reference/ccomobjectrootex-class.md index a63950388c..d28e79d490 100644 --- a/docs/atl/reference/ccomobjectrootex-class.md +++ b/docs/atl/reference/ccomobjectrootex-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComObjectRootEx Class" title: "CComObjectRootEx Class" ms.date: "11/04/2016" f1_keywords: ["CComObjectRootEx", "ATLCOM/ATL::CComObjectRootEx", "ATLCOM/ATL::InternalAddRef", "ATLCOM/ATL::InternalRelease", "ATLCOM/ATL::Lock", "ATLCOM/ATL::Unlock", "ATLCOM/ATL::FinalConstruct", "ATLCOM/ATL::FinalRelease", "ATLCOM/ATL::OuterAddRef", "ATLCOM/ATL::OuterQueryInterface", "ATLCOM/ATL::OuterRelease", "ATLCOM/ATL::InternalQueryInterface", "ATLCOM/ATL::ObjectMain", "ATLCOM/ATL::m_dwRef", "ATLCOM/ATL::m_pOuterUnknown"] @@ -25,7 +26,7 @@ The class whose methods implement the desired threading model. You can explicitl ### Methods -||| +|Function|Description| |-|-| |[CComObjectRootEx](#ccomobjectrootex)|Constructor.| |[InternalAddRef](#internaladdref)|Increments the reference count for a nonaggregated object.| @@ -35,7 +36,7 @@ The class whose methods implement the desired threading model. You can explicitl ### CComObjectRootBase Methods -||| +|Function|Description| |-|-| |[FinalConstruct](#finalconstruct)|Override in your class to perform any initialization required by your object.| |[FinalRelease](#finalrelease)|Override in your class to perform any cleanup required by your object.| @@ -45,14 +46,14 @@ The class whose methods implement the desired threading model. You can explicitl ### Static Functions -||| +|Function|Description| |-|-| |[InternalQueryInterface](#internalqueryinterface)|Delegates to the `IUnknown` of a nonaggregated object.| |[ObjectMain](#objectmain)|Called during module initialization and termination for derived classes listed in the object map.| ### Data Members -||| +|Data member|Description| |-|-| |[m_dwRef](#m_dwref)|With `m_pOuterUnknown`, part of a union. Used when the object is not aggregated to hold the reference count of `AddRef` and `Release`.| |[m_pOuterUnknown](#m_pouterunknown)|With `m_dwRef`, part of a union. Used when the object is aggregated to hold a pointer to the outer unknown.| diff --git a/docs/atl/reference/ccomobjectstack-class.md b/docs/atl/reference/ccomobjectstack-class.md index cde88aa669..946beb5b66 100644 --- a/docs/atl/reference/ccomobjectstack-class.md +++ b/docs/atl/reference/ccomobjectstack-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComObjectStack Class" title: "CComObjectStack Class" ms.date: "11/04/2016" f1_keywords: ["CComObjectStack", "ATLCOM/ATL::CComObjectStack", "ATLCOM/ATL::CComObjectStack::CComObjectStack", "ATLCOM/ATL::CComObjectStack::AddRef", "ATLCOM/ATL::CComObjectStack::QueryInterface", "ATLCOM/ATL::CComObjectStack::Release", "ATLCOM/ATL::CComObjectStack::m_hResFinalConstruct"] diff --git a/docs/atl/reference/ccompolyobject-class.md b/docs/atl/reference/ccompolyobject-class.md index b581c7315b..d3632a5283 100644 --- a/docs/atl/reference/ccompolyobject-class.md +++ b/docs/atl/reference/ccompolyobject-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComPolyObject Class" title: "CComPolyObject Class" ms.date: "11/04/2016" f1_keywords: ["CComPolyObject", "ATLCOM/ATL::CComPolyObject", "ATLCOM/ATL::CComPolyObject::CComPolyObject", "ATLCOM/ATL::CComPolyObject::AddRef", "ATLCOM/ATL::CComPolyObject::CreateInstance", "ATLCOM/ATL::CComPolyObject::FinalConstruct", "ATLCOM/ATL::CComPolyObject::FinalRelease", "ATLCOM/ATL::CComPolyObject::QueryInterface", "ATLCOM/ATL::CComPolyObject::Release", "ATLCOM/ATL::CComPolyObject::m_contained"] 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 b4ffe7ca19..c2363d848e 100644 --- a/docs/atl/reference/ccomptrbase-class.md +++ b/docs/atl/reference/ccomptrbase-class.md @@ -1,79 +1,80 @@ --- +description: "Learn more about: CComPtrBase Class" title: "CComPtrBase Class" ms.date: "11/04/2016" f1_keywords: ["CComPtrBase", "ATLCOMCLI/ATL::CComPtrBase", "ATLCOMCLI/ATL::CComPtrBase::Advise", "ATLCOMCLI/ATL::CComPtrBase::Attach", "ATLCOMCLI/ATL::CComPtrBase::CoCreateInstance", "ATLCOMCLI/ATL::CComPtrBase::CopyTo", "ATLCOMCLI/ATL::CComPtrBase::Detach", "ATLCOMCLI/ATL::CComPtrBase::IsEqualObject", "ATLCOMCLI/ATL::CComPtrBase::QueryInterface", "ATLCOMCLI/ATL::CComPtrBase::Release", "ATLCOMCLI/ATL::CComPtrBase::SetSite", "ATLCOMCLI/ATL::CComPtrBase::p"] 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, @@ -82,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. @@ -109,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(); ``` @@ -128,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, @@ -146,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(); ``` @@ -324,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; ``` @@ -336,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. @@ -373,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/ccomqiptr-class.md b/docs/atl/reference/ccomqiptr-class.md index 59a5c34ad9..03490efe16 100644 --- a/docs/atl/reference/ccomqiptr-class.md +++ b/docs/atl/reference/ccomqiptr-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComQIPtr Class" title: "CComQIPtr Class" ms.date: "11/04/2016" f1_keywords: ["CComQIPtr", "ATLCOMCLI/ATL::CComQIPtr", "ATLCOMCLI/ATL::CComQIPtr::CComQIPtr"] diff --git a/docs/atl/reference/ccomqiptrelementtraits-class.md b/docs/atl/reference/ccomqiptrelementtraits-class.md index 6bb9530907..c81c56e55e 100644 --- a/docs/atl/reference/ccomqiptrelementtraits-class.md +++ b/docs/atl/reference/ccomqiptrelementtraits-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComQIPtrElementTraits Class" title: "CComQIPtrElementTraits Class" ms.date: "11/04/2016" f1_keywords: ["CComQIPtrElementTraits", "ATLCOLL/ATL::CComQIPtrElementTraits", "ATLCOLL/ATL::CComQIPtrElementTraits::INARGTYPE"] diff --git a/docs/atl/reference/ccomsafearray-class.md b/docs/atl/reference/ccomsafearray-class.md index 102699cc92..d9c6729e91 100644 --- a/docs/atl/reference/ccomsafearray-class.md +++ b/docs/atl/reference/ccomsafearray-class.md @@ -1,24 +1,24 @@ --- +description: "Learn more about: CComSafeArray Class" 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 @@ -27,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); @@ -118,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); @@ -180,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() ``` @@ -217,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. @@ -322,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. @@ -360,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/ccomsafearraybound-class.md b/docs/atl/reference/ccomsafearraybound-class.md index f9447c01c3..fa65d7b399 100644 --- a/docs/atl/reference/ccomsafearraybound-class.md +++ b/docs/atl/reference/ccomsafearraybound-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComSafeArrayBound Class" title: "CComSafeArrayBound Class" ms.date: "05/06/2019" f1_keywords: ["CComSafeArrayBound", "ATLSAFE/ATL::CComSafeArrayBound", "ATLSAFE/ATL::GetCount", "ATLSAFE/ATL::GetLowerBound", "ATLSAFE/ATL::GetUpperBound", "ATLSAFE/ATL::SetCount", "ATLSAFE/ATL::SetLowerBound"] @@ -19,7 +20,7 @@ class CComSafeArrayBound : public SAFEARRAYBOUND ### Methods -||| +|Function|Description| |-|-| |[CComSafeArrayBound](#ccomsafearraybound)|The constructor.| |[GetCount](#getcount)|Call this method to return the number of elements.| @@ -30,7 +31,7 @@ class CComSafeArrayBound : public SAFEARRAYBOUND ### Operators -||| +|Operator|Description| |-|-| |[operator =](#operator_eq)|Sets the `CComSafeArrayBound` to a new value.| diff --git a/docs/atl/reference/ccomsafedeletecriticalsection-class.md b/docs/atl/reference/ccomsafedeletecriticalsection-class.md index 9264fb7d33..1ece1377c3 100644 --- a/docs/atl/reference/ccomsafedeletecriticalsection-class.md +++ b/docs/atl/reference/ccomsafedeletecriticalsection-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComSafeDeleteCriticalSection Class" title: "CComSafeDeleteCriticalSection Class" ms.date: "11/04/2016" f1_keywords: ["CComSafeDeleteCriticalSection", "ATLCORE/ATL::CComSafeDeleteCriticalSection", "ATLCORE/ATL::CComSafeDeleteCriticalSection::CComSafeDeleteCriticalSection", "ATLCORE/ATL::CComSafeDeleteCriticalSection::Init", "ATLCORE/ATL::CComSafeDeleteCriticalSection::Lock", "ATLCORE/ATL::CComSafeDeleteCriticalSection::Term", "ATLCORE/ATL::m_bInitialized"] @@ -34,7 +35,7 @@ class CComSafeDeleteCriticalSection : public CComCriticalSection ### Data Members -||| +|Data member|Description| |-|-| |[m_bInitialized](#m_binitialized)|Flags whether the internal `CRITICAL_SECTION` object has been initialized.| diff --git a/docs/atl/reference/ccomsimplethreadallocator-class.md b/docs/atl/reference/ccomsimplethreadallocator-class.md index 64ed616eed..3ba04a9ad2 100644 --- a/docs/atl/reference/ccomsimplethreadallocator-class.md +++ b/docs/atl/reference/ccomsimplethreadallocator-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComSimpleThreadAllocator Class" title: "CComSimpleThreadAllocator Class" ms.date: "11/04/2016" f1_keywords: ["CComSimpleThreadAllocator", "ATLBASE/ATL::CComSimpleThreadAllocator", "ATLBASE/ATL::CComSimpleThreadAllocator::GetThread"] diff --git a/docs/atl/reference/ccomsinglethreadmodel-class.md b/docs/atl/reference/ccomsinglethreadmodel-class.md index 5f0104a517..1fdb2f95db 100644 --- a/docs/atl/reference/ccomsinglethreadmodel-class.md +++ b/docs/atl/reference/ccomsinglethreadmodel-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComSingleThreadModel Class" title: "CComSingleThreadModel Class" ms.date: "2/29/2020" f1_keywords: ["CComSingleThreadModel", "ATLBASE/ATL::CComSingleThreadModel", "ATLBASE/ATL::CComSingleThreadModel::AutoCriticalSection", "ATLBASE/ATL::CComSingleThreadModel::CriticalSection", "ATLBASE/ATL::CComSingleThreadModel::ThreadModelNoCS", "ATLBASE/ATL::CComSingleThreadModel::Decrement", "ATLBASE/ATL::CComSingleThreadModel::Increment"] diff --git a/docs/atl/reference/ccomtearoffobject-class.md b/docs/atl/reference/ccomtearoffobject-class.md index 7db32f7d8a..42f6daf517 100644 --- a/docs/atl/reference/ccomtearoffobject-class.md +++ b/docs/atl/reference/ccomtearoffobject-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComTearOffObject Class" title: "CComTearOffObject Class" ms.date: "11/04/2016" f1_keywords: ["CComTearOffObject", "ATLCOM/ATL::CComTearOffObject", "ATLCOM/ATL::CComTearOffObject::CComTearOffObject", "ATLCOM/ATL::CComTearOffObject::AddRef", "ATLCOM/ATL::CComTearOffObject::QueryInterface", "ATLCOM/ATL::CComTearOffObject::Release", "ATLCOM/ATL::CComTearOffObjectBase", "ATLCOM/ATL::m_pOwner"] @@ -42,13 +43,13 @@ ATL implements its tear-off interfaces in two phases — the `CComTearOffObjectB ### CComTearOffObjectBase Methods -||| +|Function|Description| |-|-| |[CComTearOffObjectBase](#ccomtearoffobjectbase)|Constructor.| ### CComTearOffObjectBase Data Members -||| +|Data member|Description| |-|-| |[m_pOwner](#m_powner)|A pointer to a `CComObject` derived from the owner class.| diff --git a/docs/atl/reference/ccomunkarray-class.md b/docs/atl/reference/ccomunkarray-class.md index 3cda3831b3..dcdc5ecd76 100644 --- a/docs/atl/reference/ccomunkarray-class.md +++ b/docs/atl/reference/ccomunkarray-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CComUnkArray Class" title: "CComUnkArray Class" ms.date: "11/04/2016" f1_keywords: ["CComUnkArray", "ATLCOM/ATL::CComUnkArray", "ATLCOM/ATL::CComUnkArray::CComUnkArray", "ATLCOM/ATL::CComUnkArray::Add", "ATLCOM/ATL::CComUnkArray::begin", "ATLCOM/ATL::CComUnkArray::end", "ATLCOM/ATL::CComUnkArray::GetCookie", "ATLCOM/ATL::CComUnkArray::GetUnknown", "ATLCOM/ATL::CComUnkArray::Remove"] diff --git a/docs/atl/reference/ccomvariant-class.md b/docs/atl/reference/ccomvariant-class.md index ba18ff739f..e3b806e113 100644 --- a/docs/atl/reference/ccomvariant-class.md +++ b/docs/atl/reference/ccomvariant-class.md @@ -1,13 +1,13 @@ --- -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 @@ -17,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 - -||| -|-|-| -|[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); @@ -118,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); @@ -319,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 0a22ddb5ec..92e55f8f39 100644 --- a/docs/atl/reference/ccontainedwindowt-class.md +++ b/docs/atl/reference/ccontainedwindowt-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CContainedWindowT Class" title: "CContainedWindowT Class" ms.date: "11/04/2016" f1_keywords: ["CContainedWindowT", "ATLWIN/ATL::CContainedWindowT", "ATLWIN/ATL::CContainedWindowT::CContainedWindowT", "ATLWIN/ATL::CContainedWindowT::Create", "ATLWIN/ATL::CContainedWindowT::DefWindowProc", "ATLWIN/ATL::CContainedWindowT::GetCurrentMessage", "ATLWIN/ATL::CContainedWindowT::RegisterWndSuperclass", "ATLWIN/ATL::CContainedWindowT::SubclassWindow", "ATLWIN/ATL::CContainedWindowT::SwitchMessageMap", "ATLWIN/ATL::CContainedWindowT::UnsubclassWindow", "ATLWIN/ATL::CContainedWindowT::WindowProc", "ATLWIN/ATL::CContainedWindowT::m_dwMsgMapID", "ATLWIN/ATL::CContainedWindowT::m_lpszClassName", "ATLWIN/ATL::CContainedWindowT::m_pfnSuperWindowProc", "ATLWIN/ATL::CContainedWindowT::m_pObject"] @@ -74,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| @@ -196,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/ccrtallocator-class.md b/docs/atl/reference/ccrtallocator-class.md index 290e451804..782c70f47f 100644 --- a/docs/atl/reference/ccrtallocator-class.md +++ b/docs/atl/reference/ccrtallocator-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CCRTAllocator Class" title: "CCRTAllocator Class" ms.date: "11/04/2016" f1_keywords: ["CCRTAllocator", "ATLCORE/ATL::CCRTAllocator", "ATLCORE/ATL::CCRTAllocator::Allocate", "ATLCORE/ATL::CCRTAllocator::Free", "ATLCORE/ATL::CCRTAllocator::Reallocate"] diff --git a/docs/atl/reference/ccrtheap-class.md b/docs/atl/reference/ccrtheap-class.md index 8caa4973cf..2c032d979d 100644 --- a/docs/atl/reference/ccrtheap-class.md +++ b/docs/atl/reference/ccrtheap-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CCRTHeap Class" title: "CCRTHeap Class" ms.date: "11/04/2016" f1_keywords: ["CCRTHeap", "ATLMEM/ATL::CCRTHeap", "ATLMEM/ATL::CCRTHeap::Allocate", "ATLMEM/ATL::CCRTHeap::Free", "ATLMEM/ATL::CCRTHeap::GetSize", "ATLMEM/ATL::CCRTHeap::Reallocate"] diff --git a/docs/atl/reference/cdacl-class.md b/docs/atl/reference/cdacl-class.md index b07c8a0299..dcd93c40d5 100644 --- a/docs/atl/reference/cdacl-class.md +++ b/docs/atl/reference/cdacl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CDacl Class" title: "CDacl Class" ms.date: "11/04/2016" f1_keywords: ["CDacl", "ATLSECURITY/ATL::CDacl", "ATLSECURITY/ATL::CDacl::CDacl", "ATLSECURITY/ATL::CDacl::AddAllowedAce", "ATLSECURITY/ATL::CDacl::AddDeniedAce", "ATLSECURITY/ATL::CDacl::GetAceCount", "ATLSECURITY/ATL::CDacl::RemoveAce", "ATLSECURITY/ATL::CDacl::RemoveAllAces"] diff --git a/docs/atl/reference/cdebugreporthook-class.md b/docs/atl/reference/cdebugreporthook-class.md index c7532787ef..a525a35257 100644 --- a/docs/atl/reference/cdebugreporthook-class.md +++ b/docs/atl/reference/cdebugreporthook-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CDebugReportHook Class" title: "CDebugReportHook Class" ms.date: "11/04/2016" f1_keywords: ["CDebugReportHook", "ATLUTIL/ATL::CDebugReportHook", "ATLUTIL/ATL::CDebugReportHook::CDebugReportHook", "ATLUTIL/ATL::CDebugReportHook::CDebugReportHookProc", "ATLUTIL/ATL::CDebugReportHook::RemoveHook", "ATLUTIL/ATL::CDebugReportHook::SetHook", "ATLUTIL/ATL::CDebugReportHook::SetPipeName", "ATLUTIL/ATL::CDebugReportHook::SetTimeout"] diff --git a/docs/atl/reference/cdefaultchartraits-class.md b/docs/atl/reference/cdefaultchartraits-class.md index a142fadcc0..6d941499c6 100644 --- a/docs/atl/reference/cdefaultchartraits-class.md +++ b/docs/atl/reference/cdefaultchartraits-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CDefaultCharTraits Class" title: "CDefaultCharTraits Class" ms.date: "11/04/2016" f1_keywords: ["CDefaultCharTraits", "ATLCOLL/ATL::CDefaultCharTraits", "ATLCOLL/ATL::CDefaultCharTraits::CharToLower", "ATLCOLL/ATL::CDefaultCharTraits::CharToUpper"] diff --git a/docs/atl/reference/cdefaultcomparetraits-class.md b/docs/atl/reference/cdefaultcomparetraits-class.md index 26e1f20666..ba680d5061 100644 --- a/docs/atl/reference/cdefaultcomparetraits-class.md +++ b/docs/atl/reference/cdefaultcomparetraits-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CDefaultCompareTraits Class" title: "CDefaultCompareTraits Class" ms.date: "11/04/2016" f1_keywords: ["CDefaultCompareTraits", "ATLCOLL/ATL::CDefaultCompareTraits", "ATLCOLL/ATL::CDefaultCompareTraits::CompareElements", "ATLCOLL/ATL::CDefaultCompareTraits::CompareElementsOrdered"] diff --git a/docs/atl/reference/cdefaultelementtraits-class.md b/docs/atl/reference/cdefaultelementtraits-class.md index dd3f9bf896..ee35bca2b3 100644 --- a/docs/atl/reference/cdefaultelementtraits-class.md +++ b/docs/atl/reference/cdefaultelementtraits-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CDefaultElementTraits Class" title: "CDefaultElementTraits Class" ms.date: "11/04/2016" f1_keywords: ["CDefaultElementTraits", "atlcoll/ATL::CDefaultElementTraits"] diff --git a/docs/atl/reference/cdefaulthashtraits-class.md b/docs/atl/reference/cdefaulthashtraits-class.md index c6602452a7..8c626840a9 100644 --- a/docs/atl/reference/cdefaulthashtraits-class.md +++ b/docs/atl/reference/cdefaulthashtraits-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CDefaultHashTraits Class" title: "CDefaultHashTraits Class" ms.date: "11/04/2016" f1_keywords: ["CDefaultHashTraits", "ATLCOLL/ATL::CDefaultHashTraits", "ATLCOLL/ATL::CDefaultHashTraits::Hash"] diff --git a/docs/atl/reference/cdialogimpl-class.md b/docs/atl/reference/cdialogimpl-class.md index a1590b22c0..56a1d4713c 100644 --- a/docs/atl/reference/cdialogimpl-class.md +++ b/docs/atl/reference/cdialogimpl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CDialogImpl Class" title: "CDialogImpl Class" ms.date: "11/04/2016" f1_keywords: ["CDialogImpl", "ATLWIN/ATL::CDialogImpl", "ATLWIN/ATL::Create", "ATLWIN/ATL::DestroyWindow", "ATLWIN/ATL::DoModal", "ATLWIN/ATL::EndDialog", "ATLWIN/ATL::GetDialogProc", "ATLWIN/ATL::MapDialogRect", "ATLWIN/ATL::OnFinalMessage", "ATLWIN/ATL::DialogProc", "ATLWIN/ATL::StartDialogProc"] @@ -32,7 +33,7 @@ The base class of your new class. The default base class is [CWindow](../../atl/ ### Methods -||| +|Function|Description| |-|-| |[Create](#create)|Creates a modeless dialog box.| |[DestroyWindow](#destroywindow)|Destroys a modeless dialog box.| @@ -41,7 +42,7 @@ The base class of your new class. The default base class is [CWindow](../../atl/ ### CDialogImplBaseT Methods -||| +|Function|Description| |-|-| |[GetDialogProc](#getdialogproc)|Returns the current dialog box procedure.| |[MapDialogRect](#mapdialogrect)|Maps the dialog-box units of the specified rectangle to screen units (pixels).| @@ -49,7 +50,7 @@ The base class of your new class. The default base class is [CWindow](../../atl/ ### Static Functions -||| +|Function|Description| |-|-| |[DialogProc](#dialogproc)|Processes messages sent to the dialog box.| |[StartDialogProc](#startdialogproc)|Called when the first message is received to process messages sent to the dialog box.| diff --git a/docs/atl/reference/cdynamicchain-class.md b/docs/atl/reference/cdynamicchain-class.md index 7e47151415..27e0374b8f 100644 --- a/docs/atl/reference/cdynamicchain-class.md +++ b/docs/atl/reference/cdynamicchain-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CDynamicChain Class" title: "CDynamicChain Class" ms.date: "11/04/2016" f1_keywords: ["CDynamicChain", "ATLWIN/ATL::CDynamicChain", "ATLWIN/ATL::CDynamicChain::CDynamicChain", "ATLWIN/ATL::CDynamicChain::CallChain", "ATLWIN/ATL::CDynamicChain::RemoveChainEntry", "ATLWIN/ATL::CDynamicChain::SetChainEntry"] diff --git a/docs/atl/reference/celementtraits-class.md b/docs/atl/reference/celementtraits-class.md index 47b9f2eece..067c69927e 100644 --- a/docs/atl/reference/celementtraits-class.md +++ b/docs/atl/reference/celementtraits-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CElementTraits Class" title: "CElementTraits Class" ms.date: "11/04/2016" f1_keywords: ["CElementTraits", "atlcoll/ATL::CElementTraits"] diff --git a/docs/atl/reference/celementtraitsbase-class.md b/docs/atl/reference/celementtraitsbase-class.md index 1f24adce4f..8bf122174c 100644 --- a/docs/atl/reference/celementtraitsbase-class.md +++ b/docs/atl/reference/celementtraitsbase-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CElementTraitsBase Class" title: "CElementTraitsBase Class" ms.date: "11/04/2016" f1_keywords: ["CElementTraitsBase", "ATLCOLL/ATL::CElementTraitsBase", "ATLCOLL/ATL::CElementTraitsBase::INARGTYPE", "ATLCOLL/ATL::CElementTraitsBase::OUTARGTYPE", "ATLCOLL/ATL::CElementTraitsBase::CopyElements", "ATLCOLL/ATL::CElementTraitsBase::RelocateElements"] diff --git a/docs/atl/reference/cfirepropnotifyevent-class.md b/docs/atl/reference/cfirepropnotifyevent-class.md index 6a79f525a9..76834b9a5e 100644 --- a/docs/atl/reference/cfirepropnotifyevent-class.md +++ b/docs/atl/reference/cfirepropnotifyevent-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CFirePropNotifyEvent Class" title: "CFirePropNotifyEvent Class" ms.date: "11/04/2016" f1_keywords: ["CFirePropNotifyEvent", "ATLCTL/ATL::CFirePropNotifyEvent", "ATLCTL/ATL::CFirePropNotifyEvent::FireOnChanged", "ATLCTL/ATL::CFirePropNotifyEvent::FireOnRequestEdit"] diff --git a/docs/atl/reference/cglobalheap-class.md b/docs/atl/reference/cglobalheap-class.md index bc1dc3bca8..426101159d 100644 --- a/docs/atl/reference/cglobalheap-class.md +++ b/docs/atl/reference/cglobalheap-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CGlobalHeap Class" title: "CGlobalHeap Class" ms.date: "11/04/2016" f1_keywords: ["CGlobalHeap", "ATLMEM/ATL::CGlobalHeap", "ATLMEM/ATL::CGlobalHeap::Allocate", "ATLMEM/ATL::CGlobalHeap::Free", "ATLMEM/ATL::CGlobalHeap::GetSize", "ATLMEM/ATL::CGlobalHeap::Reallocate"] diff --git a/docs/atl/reference/chandle-class.md b/docs/atl/reference/chandle-class.md index 313bc2c17a..237fa0cd88 100644 --- a/docs/atl/reference/chandle-class.md +++ b/docs/atl/reference/chandle-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CHandle Class" title: "CHandle Class" ms.date: "07/09/2019" f1_keywords: ["CHandle", "ATLBASE/ATL::CHandle", "ATLBASE/ATL::CHandle::CHandle", "ATLBASE/ATL::CHandle::Attach", "ATLBASE/ATL::CHandle::Close", "ATLBASE/ATL::CHandle::Detach", "ATLBASE/ATL::CHandle::m_h"] diff --git a/docs/atl/reference/cheapptr-class.md b/docs/atl/reference/cheapptr-class.md index 7643038e95..c7888bfbcc 100644 --- a/docs/atl/reference/cheapptr-class.md +++ b/docs/atl/reference/cheapptr-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CHeapPtr Class" title: "CHeapPtr Class" ms.date: "11/04/2016" f1_keywords: ["CHeapPtr", "ATLCORE/ATL::CHeapPtr", "ATLCORE/ATL::CHeapPtr::CHeapPtr", "ATLCORE/ATL::CHeapPtr::Allocate", "ATLCORE/ATL::CHeapPtr::Reallocate"] diff --git a/docs/atl/reference/cheapptrbase-class.md b/docs/atl/reference/cheapptrbase-class.md index b484cf9fb7..8ba15f0fb6 100644 --- a/docs/atl/reference/cheapptrbase-class.md +++ b/docs/atl/reference/cheapptrbase-class.md @@ -1,11 +1,12 @@ --- -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. @@ -14,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. @@ -98,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(); ``` @@ -119,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`. @@ -145,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; ``` @@ -159,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/cheapptrelementtraits-class.md b/docs/atl/reference/cheapptrelementtraits-class.md index 231d83cb0c..3ff0b3f44d 100644 --- a/docs/atl/reference/cheapptrelementtraits-class.md +++ b/docs/atl/reference/cheapptrelementtraits-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CHeapPtrElementTraits Class" title: "CHeapPtrElementTraits Class" ms.date: "11/04/2016" f1_keywords: ["CHeapPtrElementTraits", "ATLCOLL/ATL::CHeapPtrElementTraits", "ATLCOLL/ATL::CHeapPtrElementTraits::INARGTYPE", "ATLCOLL/ATL::CHeapPtrElementTraits::OUTARGTYPE"] diff --git a/docs/atl/reference/cheapptrlist-class.md b/docs/atl/reference/cheapptrlist-class.md index 835c2635d9..591c578772 100644 --- a/docs/atl/reference/cheapptrlist-class.md +++ b/docs/atl/reference/cheapptrlist-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CHeapPtrList Class" title: "CHeapPtrList Class" ms.date: "11/04/2016" f1_keywords: ["CHeapPtrList", "ATLCOLL/ATL::CHeapPtrList", "ATLCOLL/ATL::CHeapPtrList::CHeapPtrList"] diff --git a/docs/atl/reference/cinterfacearray-class.md b/docs/atl/reference/cinterfacearray-class.md index 5b5753ea80..3a6ec0bc1d 100644 --- a/docs/atl/reference/cinterfacearray-class.md +++ b/docs/atl/reference/cinterfacearray-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CInterfaceArray Class" title: "CInterfaceArray Class" ms.date: "11/04/2016" f1_keywords: ["CInterfaceArray", "ATLCOLL/ATL::CInterfaceArray", "ATLCOLL/ATL::CInterfaceArray::CInterfaceArray"] diff --git a/docs/atl/reference/cinterfacelist-class.md b/docs/atl/reference/cinterfacelist-class.md index d31c32ecf9..e5aae7bdce 100644 --- a/docs/atl/reference/cinterfacelist-class.md +++ b/docs/atl/reference/cinterfacelist-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CInterfaceList Class" title: "CInterfaceList Class" ms.date: "11/04/2016" f1_keywords: ["CInterfaceList", "ATLCOLL/ATL::CInterfaceList", "ATLCOLL/ATL::CInterfaceList::CInterfaceList"] diff --git a/docs/atl/reference/clocalheap-class.md b/docs/atl/reference/clocalheap-class.md index 642c75e20b..32ff5c199e 100644 --- a/docs/atl/reference/clocalheap-class.md +++ b/docs/atl/reference/clocalheap-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CLocalHeap Class" title: "CLocalHeap Class" ms.date: "11/04/2016" f1_keywords: ["CLocalHeap", "ATLMEM/ATL::CLocalHeap", "ATLMEM/ATL::CLocalHeap::Allocate", "ATLMEM/ATL::CLocalHeap::Free", "ATLMEM/ATL::CLocalHeap::GetSize", "ATLMEM/ATL::CLocalHeap::Reallocate"] diff --git a/docs/atl/reference/cmessagemap-class.md b/docs/atl/reference/cmessagemap-class.md index 900e6fd6ab..1f8f30e742 100644 --- a/docs/atl/reference/cmessagemap-class.md +++ b/docs/atl/reference/cmessagemap-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CMessageMap Class" title: "CMessageMap Class" ms.date: "11/04/2016" f1_keywords: ["CMessageMap", "ATLWIN/ATL::CMessageMap", "ATLWIN/ATL::CMessageMap::ProcessWindowMessage"] diff --git a/docs/atl/reference/cnonstatelessworker-class.md b/docs/atl/reference/cnonstatelessworker-class.md index 8a2f8045fb..014cd170ab 100644 --- a/docs/atl/reference/cnonstatelessworker-class.md +++ b/docs/atl/reference/cnonstatelessworker-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CNonStatelessWorker Class" title: "CNonStatelessWorker Class" ms.date: "11/04/2016" f1_keywords: ["CNonStatelessWorker", "ATLUTIL/ATL::CNonStatelessWorker", "ATLUTIL/ATL::CNonStatelessWorker::RequestType", "ATLUTIL/ATL::CNonStatelessWorker::Execute", "ATLUTIL/ATL::CNonStatelessWorker::Initialize", "ATLUTIL/ATL::CNonStatelessWorker::Terminate"] diff --git a/docs/atl/reference/cnoworkerthread-class.md b/docs/atl/reference/cnoworkerthread-class.md index bba941dd46..69c725ddc5 100644 --- a/docs/atl/reference/cnoworkerthread-class.md +++ b/docs/atl/reference/cnoworkerthread-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CNoWorkerThread Class" title: "CNoWorkerThread Class" ms.date: "11/04/2016" f1_keywords: ["CNoWorkerThread", "ATLUTIL/ATL::CNoWorkerThread", "ATLUTIL/ATL::CNoWorkerThread::AddHandle", "ATLUTIL/ATL::CNoWorkerThread::AddTimer", "ATLUTIL/ATL::CNoWorkerThread::GetThreadHandle", "ATLUTIL/ATL::CNoWorkerThread::GetThreadId", "ATLUTIL/ATL::CNoWorkerThread::Initialize", "ATLUTIL/ATL::CNoWorkerThread::RemoveHandle", "ATLUTIL/ATL::CNoWorkerThread::Shutdown"] diff --git a/docs/atl/reference/com-interface-entry-macros.md b/docs/atl/reference/com-interface-entry-macros.md index 4c3f04dec1..83a187ec49 100644 --- a/docs/atl/reference/com-interface-entry-macros.md +++ b/docs/atl/reference/com-interface-entry-macros.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: COM_INTERFACE_ENTRY Macros" title: "COM Interface Entry Macros" ms.date: "03/28/2017" f1_keywords: ["atlcom/ATL::COM_INTERFACE_ENTRY", "atlcom/ATL::COM_INTERFACE_ENTRY_IID", "atlcom/ATL::COM_INTERFACE_ENTRY_AGGREGATE", "atlcom/ATL::COM_INTERFACE_ENTRY_AGGREGATE_BLIND", "atlcom/ATL::COM_INTERFACE_ENTRY_AUTOAGGREGATE", "atlcom/ATL::COM_INTERFACE_ENTRY_AUTOAGGREGATE_BLIND", "atlcom/ATL::COM_INTERFACE_ENTRY_BREAK", "atlcom/ATL::COM_INTERFACE_ENTRY_CACHED_TEAR_OFF", "atlcom/ATL::COM_INTERFACE_ENTRY_TEAR_OFF", "atlcom/ATL::COM_INTERFACE_ENTRY_CHAIN", "atlcom/ATL::COM_INTERFACE_ENTRY_FUNC", "atlcom/ATL::COM_INTERFACE_ENTRY_FUNC_BLIND", "atlcom/ATL::COM_INTERFACE_ENTRY_NOINTERFACE"] @@ -9,7 +10,7 @@ ms.assetid: 19dcb768-2e1f-4b8d-a618-453a01a4bd00 These macros enter an object's interfaces into its COM map so that they can be accessed by `QueryInterface`. The order of entries in the COM map is the order interfaces will be checked for a matching IID during `QueryInterface`. -||| +|Macro|Description| |-|-| |[COM_INTERFACE_ENTRY](#com_interface_entry)|Enters interfaces into the COM interface map.| |[COM_INTERFACE_ENTRY2](#com_interface_entry2)|Use this macro to disambiguate two branches of inheritance.| diff --git a/docs/atl/reference/com-map-global-functions.md b/docs/atl/reference/com-map-global-functions.md index a661c2e62b..97e1980264 100644 --- a/docs/atl/reference/com-map-global-functions.md +++ b/docs/atl/reference/com-map-global-functions.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: COM Map Global Functions" title: "COM Map Global Functions" ms.date: "11/04/2016" f1_keywords: ["atlbase/ATL::AtlInternalQueryInterface", "atlbase/ATL::InlineIsEqualIUnknown"] @@ -9,7 +10,7 @@ ms.assetid: b9612d30-eb23-46ef-8093-d56f237d3cf1 These functions provide support for COM Map `IUnknown` implementations. -||| +|Function|Description| |-|-| |[AtlInternalQueryInterface](#atlinternalqueryinterface)|Delegates to the `IUnknown` of a nonaggregated object.| |[InlineIsEqualIUnknown](#inlineisequaliunknown)|Generates efficient code for comparing interfaces against `IUnknown`.| diff --git a/docs/atl/reference/com-map-macros.md b/docs/atl/reference/com-map-macros.md index f68ae030c5..6734604721 100644 --- a/docs/atl/reference/com-map-macros.md +++ b/docs/atl/reference/com-map-macros.md @@ -1,7 +1,8 @@ --- +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 --- @@ -9,7 +10,7 @@ ms.assetid: 0f33656d-321f-4996-90cc-9a7f21ab73c3 These macros define COM interface maps. -||| +|Macro|Description| |-|-| |[BEGIN_COM_MAP](#begin_com_map)|Marks the beginning of the COM interface map entries.| |[END_COM_MAP](#end_com_map)|Marks the end of the COM interface map entries.| 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 f1110386b1..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 @@ -1,4 +1,5 @@ --- +description: "Learn more about: COM+ 1.0, ATL COM+ 1.0 Component Wizard" title: "COM+ 1.0, ATL COM+ 1.0 Component Wizard" ms.date: "05/09/2019" f1_keywords: ["vc.codewiz.class.atl.mts.options"] @@ -6,13 +7,13 @@ ms.assetid: 2fbe259c-6be1-4d0e-9cfe-721c75c97cb1 --- # COM+ 1.0, ATL COM+ 1.0 Component Wizard -::: moniker range="vs-2019" +::: moniker range=">=msvc-160" This wizard is not available in Visual Studio 2019 and later. ::: moniker-end -::: moniker range="<=vs-2017" +::: moniker range="<=msvc-150" Use this page of the ATL COM+ 1.0 Component Wizard to specify interface type and additional interfaces to be supported. diff --git a/docs/atl/reference/com-plus-1-0-support-in-atl-projects.md b/docs/atl/reference/com-plus-1-0-support-in-atl-projects.md index 326f3bb809..ae0f296311 100644 --- a/docs/atl/reference/com-plus-1-0-support-in-atl-projects.md +++ b/docs/atl/reference/com-plus-1-0-support-in-atl-projects.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: COM+ 1.0 Support in ATL Projects" title: "COM+ 1.0 Support in ATL Projects" ms.date: "11/04/2016" f1_keywords: ["vc.appwiz.ATL.MTS"] diff --git a/docs/atl/reference/compiler-options-macros.md b/docs/atl/reference/compiler-options-macros.md index 81d590b390..4c80bb5d9b 100644 --- a/docs/atl/reference/compiler-options-macros.md +++ b/docs/atl/reference/compiler-options-macros.md @@ -1,33 +1,34 @@ --- +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 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 ``` @@ -51,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. @@ -81,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)] @@ -109,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. @@ -121,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 @@ -131,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. @@ -143,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. @@ -153,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. @@ -163,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. @@ -183,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 3b0d13b506..b55042bb27 100644 --- a/docs/atl/reference/composite-control-global-functions.md +++ b/docs/atl/reference/composite-control-global-functions.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Composite Control Global Functions" title: "Composite Control Global Functions" ms.date: "11/04/2016" f1_keywords: ["atlhost/ATL::AtlAxDialogBox", "atlhost/ATL::AtlAxCreateDialog", "atlhost/ATL::AtlAxCreateControl", "atlhost/ATL::AtlAxCreateControlEx", "atlhost/ATL::AtlAxCreateControlLic", "atlhost/ATL::AtlAxCreateControlLicEx", "atlhost/ATL::AtlAxAttachControl", "atlhost/ATL::AtlAxGetHost", "atlhost/ATL::AtlAxGetControl", "atlhost/ATL::AtlSetChildSite", "atlhost/ATL::AtlAxWinInit", "atlhost/ATL::AtlAxWinTerm", "atlhost/ATL::AtlGetObjectSourceInterface"] @@ -12,7 +13,7 @@ These functions provide support for creating dialog boxes, and for creating, hos > [!IMPORTANT] > The functions listed in the following table cannot be used in applications that execute in the Windows Runtime. -||| +|Function|Description| |-|-| |[AtlAxDialogBox](#atlaxdialogbox)|Creates a modal dialog box from a dialog template provided by the user. The resulting dialog box can contain ActiveX controls.| |[AtlAxCreateDialog](#atlaxcreatedialog)|Creates a modeless dialog box from a dialog template provided by the user. The resulting dialog box can contain ActiveX controls.| @@ -75,7 +76,7 @@ CONTROL "{04FE35E9-ADBC-4f1d-83FE-8FA4D1F71C7F}", IDC_TEST, "AtlAxWin80", WS_GROUP | WS_TABSTOP, 0, 0, 100, 100 ``` -For more information on editing resource scripts, see [How to: Open a Resource Script File in Text Format](../../windows/how-to-open-a-resource-script-file-in-text-format.md). For more information on control resource-definition statements, see [Common Control Parameters](/windows/win32/menurc/common-control-parameters) under Windows SDK: SDK Tools. +For more information on editing resource scripts, see [How to: Create Resources](../../windows/how-to-create-a-resource-script-file.md). For more information on control resource-definition statements, see [Common Control Parameters](/windows/win32/menurc/common-control-parameters) under Windows SDK: SDK Tools. For more information on dialog boxes in general, refer to [DialogBox](/windows/win32/api/winuser/nf-winuser-dialogboxw) and [CreateDialogParam](/windows/win32/api/winuser/nf-winuser-createdialogparamw) in the Windows SDK. @@ -278,7 +279,7 @@ One of the standard HRESULT values. ### Example -See [Hosting ActiveX Controls Using ATL AXHost](../../atl/hosting-activex-controls-using-atl-axhost.md) 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 @@ -345,7 +346,7 @@ One of the standard HRESULT values. ### Example -See [Hosting ActiveX Controls Using ATL AXHost](../../atl/hosting-activex-controls-using-atl-axhost.md) 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 4578e12c45..9721f16031 100644 --- a/docs/atl/reference/composite-control-macros.md +++ b/docs/atl/reference/composite-control-macros.md @@ -1,7 +1,8 @@ --- +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 --- @@ -9,12 +10,12 @@ ms.assetid: 17f2dd5e-07e6-4aa6-b965-7a361c78c45e These macros define event sink maps and entries. -||| +|Macro|Description| |-|-| |[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.| @@ -42,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 @@ -58,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 @@ -85,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 @@ -119,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 @@ -152,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-global-functions.md b/docs/atl/reference/connection-point-global-functions.md index 995af33e61..be49a8643a 100644 --- a/docs/atl/reference/connection-point-global-functions.md +++ b/docs/atl/reference/connection-point-global-functions.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Connection Point Global Functions" title: "Connection Point Global Functions" ms.date: "11/04/2016" f1_keywords: ["atlbase/ATL::AtlAdvise", "atlbase/ATL::AtlUnadvise", "atlbase/ATL::AtlAdviseSinkMap"] @@ -12,7 +13,7 @@ These functions provide support for connection points and sink maps. > [!IMPORTANT] > The functions listed in the following table cannot be used in applications that execute in the Windows Runtime. -||| +|Function|Description| |-|-| |[AtlAdvise](#atladvise)|Creates a connection between an object's connection point and a client's sink.| |[AtlUnadvise](#atlunadvise)|Terminates the connection established through `AtlAdvise`.| diff --git a/docs/atl/reference/connection-point-macros.md b/docs/atl/reference/connection-point-macros.md index b9be9eac5d..490abb2c38 100644 --- a/docs/atl/reference/connection-point-macros.md +++ b/docs/atl/reference/connection-point-macros.md @@ -1,7 +1,8 @@ --- +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 --- @@ -9,7 +10,7 @@ ms.assetid: cc3a6dd3-5538-45df-b027-1f34963c31e5 These macros define connection point maps and entries. -||| +|Macro|Description| |-|-| |[BEGIN_CONNECTION_POINT_MAP](#begin_connection_point_map)|Marks the beginning of the connection point map entries.| |[CONNECTION_POINT_ENTRY](#connection_point_entry)|Enters connection points into the map.| diff --git a/docs/atl/reference/cpatht-class.md b/docs/atl/reference/cpatht-class.md index 1042819d05..32b31a3db1 100644 --- a/docs/atl/reference/cpatht-class.md +++ b/docs/atl/reference/cpatht-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CPathT Class" title: "CPathT Class" ms.date: "03/27/2019" f1_keywords: ["CPathT", "ATLPATH/ATL::CPathT", "ATLPATH/ATL::CPathT::PCXSTR", "ATLPATH/ATL::CPathT::PXSTR", "ATLPATH/ATL::CPathT::XCHAR", "ATLPATH/ATL::CPathT::CPathT", "ATLPATH/ATL::CPathT::AddBackslash", "ATLPATH/ATL::CPathT::AddExtension", "ATLPATH/ATL::CPathT::Append", "ATLPATH/ATL::CPathT::BuildRoot", "ATLPATH/ATL::CPathT::Canonicalize", "ATLPATH/ATL::CPathT::Combine", "ATLPATH/ATL::CPathT::CommonPrefix", "ATLPATH/ATL::CPathT::CompactPath", "ATLPATH/ATL::CPathT::CompactPathEx", "ATLPATH/ATL::CPathT::FileExists", "ATLPATH/ATL::CPathT::FindExtension", "ATLPATH/ATL::CPathT::FindFileName", "ATLPATH/ATL::CPathT::GetDriveNumber", "ATLPATH/ATL::CPathT::GetExtension", "ATLPATH/ATL::CPathT::IsDirectory", "ATLPATH/ATL::CPathT::IsFileSpec", "ATLPATH/ATL::CPathT::IsPrefix", "ATLPATH/ATL::CPathT::IsRelative", "ATLPATH/ATL::CPathT::IsRoot", "ATLPATH/ATL::CPathT::IsSameRoot", "ATLPATH/ATL::CPathT::IsUNC", "ATLPATH/ATL::CPathT::IsUNCServer", "ATLPATH/ATL::CPathT::IsUNCServerShare", "ATLPATH/ATL::CPathT::MakePretty", "ATLPATH/ATL::CPathT::MatchSpec", "ATLPATH/ATL::CPathT::QuoteSpaces", "ATLPATH/ATL::CPathT::RelativePathTo", "ATLPATH/ATL::CPathT::RemoveArgs", "ATLPATH/ATL::CPathT::RemoveBackslash", "ATLPATH/ATL::CPathT::RemoveBlanks", "ATLPATH/ATL::CPathT::RemoveExtension", "ATLPATH/ATL::CPathT::RemoveFileSpec", "ATLPATH/ATL::CPathT::RenameExtension", "ATLPATH/ATL::CPathT::SkipRoot", "ATLPATH/ATL::CPathT::StripPath", "ATLPATH/ATL::CPathT::StripToRoot", "ATLPATH/ATL::CPathT::UnquoteSpaces", "ATLPATH/ATL::CPathT::m_strPath"] @@ -59,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.| @@ -176,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 @@ -395,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; @@ -597,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. @@ -621,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/cprimitiveelementtraits-class.md b/docs/atl/reference/cprimitiveelementtraits-class.md index 03ec8da38f..7a0da283d4 100644 --- a/docs/atl/reference/cprimitiveelementtraits-class.md +++ b/docs/atl/reference/cprimitiveelementtraits-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CPrimitiveElementTraits Class" title: "CPrimitiveElementTraits Class" ms.date: "11/04/2016" f1_keywords: ["CPrimitiveElementTraits", "ATLCOLL/ATL::CPrimitiveElementTraits", "ATLCOLL/ATL::CPrimitiveElementTraits::INARGTYPE", "ATLCOLL/ATL::CPrimitiveElementTraits::OUTARGTYPE"] diff --git a/docs/atl/reference/cprivateobjectsecuritydesc-class.md b/docs/atl/reference/cprivateobjectsecuritydesc-class.md index db915df3b7..8d18a4cef8 100644 --- a/docs/atl/reference/cprivateobjectsecuritydesc-class.md +++ b/docs/atl/reference/cprivateobjectsecuritydesc-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CPrivateObjectSecurityDesc Class" title: "CPrivateObjectSecurityDesc Class" ms.date: "11/04/2016" f1_keywords: ["CPrivateObjectSecurityDesc", "ATLSECURITY/ATL::CPrivateObjectSecurityDesc", "ATLSECURITY/ATL::CPrivateObjectSecurityDesc::CPrivateObjectSecurityDesc", "ATLSECURITY/ATL::CPrivateObjectSecurityDesc::ConvertToAutoInherit", "ATLSECURITY/ATL::CPrivateObjectSecurityDesc::Create", "ATLSECURITY/ATL::CPrivateObjectSecurityDesc::Get", "ATLSECURITY/ATL::CPrivateObjectSecurityDesc::Set"] @@ -35,7 +36,7 @@ class CPrivateObjectSecurityDesc : public CSecurityDesc ### Operators -||| +|Operator|Description| |-|-| |[operator =](#operator_eq)|Assignment operator.| diff --git a/docs/atl/reference/crbmap-class.md b/docs/atl/reference/crbmap-class.md index eb33aa175f..4617fc49e3 100644 --- a/docs/atl/reference/crbmap-class.md +++ b/docs/atl/reference/crbmap-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CRBMap Class" title: "CRBMap Class" ms.date: "11/04/2016" f1_keywords: ["CRBMap", "ATLCOLL/ATL::CRBMap", "ATLCOLL/ATL::CRBMap::CRBMap", "ATLCOLL/ATL::CRBMap::Lookup", "ATLCOLL/ATL::CRBMap::RemoveKey", "ATLCOLL/ATL::CRBMap::SetAt"] diff --git a/docs/atl/reference/crbmultimap-class.md b/docs/atl/reference/crbmultimap-class.md index c4f52f3787..3788491f6d 100644 --- a/docs/atl/reference/crbmultimap-class.md +++ b/docs/atl/reference/crbmultimap-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CRBMultiMap Class" title: "CRBMultiMap Class" ms.date: "11/04/2016" f1_keywords: ["CRBMultiMap", "ATLCOLL/ATL::CRBMultiMap", "ATLCOLL/ATL::CRBMultiMap::CRBMultiMap", "ATLCOLL/ATL::CRBMultiMap::FindFirstWithKey", "ATLCOLL/ATL::CRBMultiMap::GetNextValueWithKey", "ATLCOLL/ATL::CRBMultiMap::GetNextWithKey", "ATLCOLL/ATL::CRBMultiMap::Insert", "ATLCOLL/ATL::CRBMultiMap::RemoveKey"] diff --git a/docs/atl/reference/crbtree-class.md b/docs/atl/reference/crbtree-class.md index b6b0fadc37..1b37d5c41e 100644 --- a/docs/atl/reference/crbtree-class.md +++ b/docs/atl/reference/crbtree-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CRBTree Class" title: "CRBTree Class" ms.date: "11/04/2016" f1_keywords: ["CRBTree", "ATLCOLL/ATL::CRBTree", "ATLCOLL/ATL::CRBTree::KINARGTYPE", "ATLCOLL/ATL::CRBTree::KOUTARGTYPE", "ATLCOLL/ATL::CRBTree::VINARGTYPE", "ATLCOLL/ATL::CRBTree::VOUTARGTYPE", "ATLCOLL/ATL::CRBTree::FindFirstKeyAfter", "ATLCOLL/ATL::CRBTree::GetAt", "ATLCOLL/ATL::CRBTree::GetCount", "ATLCOLL/ATL::CRBTree::GetHeadPosition", "ATLCOLL/ATL::CRBTree::GetKeyAt", "ATLCOLL/ATL::CRBTree::GetNext", "ATLCOLL/ATL::CRBTree::GetNextAssoc", "ATLCOLL/ATL::CRBTree::GetNextKey", "ATLCOLL/ATL::CRBTree::GetNextValue", "ATLCOLL/ATL::CRBTree::GetPrev", "ATLCOLL/ATL::CRBTree::GetTailPosition", "ATLCOLL/ATL::CRBTree::GetValueAt", "ATLCOLL/ATL::CRBTree::IsEmpty", "ATLCOLL/ATL::CRBTree::RemoveAll", "ATLCOLL/ATL::CRBTree::RemoveAt", "ATLCOLL/ATL::CRBTree::SetValueAt"] @@ -103,7 +104,7 @@ This class is used by the methods [CRBTree::GetAt](#getat), [CRBTree::GetNext](# The members are as follows: -||| +|Data member|Description| |-|-| |`m_key`|The data member storing the key element.| |`m_value`|The data member storing the value element.| diff --git a/docs/atl/reference/creating-an-atl-project.md b/docs/atl/reference/creating-an-atl-project.md index 88126c0028..0e82550faf 100644 --- a/docs/atl/reference/creating-an-atl-project.md +++ b/docs/atl/reference/creating-an-atl-project.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Creating an ATL Project" title: "Creating an ATL Project" ms.date: "05/06/2019" f1_keywords: ["vc.appwiz.ATL.project"] diff --git a/docs/atl/reference/cregkey-class.md b/docs/atl/reference/cregkey-class.md index a2c11e55cf..175495ad2e 100644 --- a/docs/atl/reference/cregkey-class.md +++ b/docs/atl/reference/cregkey-class.md @@ -1,11 +1,11 @@ --- +description: "Learn more about: CRegKey Class" 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. @@ -24,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 @@ -80,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(); @@ -99,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(); @@ -116,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( @@ -135,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. @@ -177,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. @@ -202,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. @@ -212,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(); @@ -233,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(); @@ -252,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. @@ -266,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. @@ -296,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. @@ -315,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. @@ -340,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. @@ -350,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. @@ -364,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( @@ -407,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. @@ -444,7 +444,7 @@ CRegKey& operator= (CRegKey& key) throw(); ### Parameters -*key*
+*`key`*\ The key to copy. ### Return Value @@ -453,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. @@ -468,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( @@ -500,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. @@ -529,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. @@ -559,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( @@ -591,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. @@ -621,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( @@ -664,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. @@ -711,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. @@ -735,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(); @@ -762,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. @@ -786,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. @@ -813,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. @@ -840,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. @@ -871,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(); @@ -895,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. @@ -922,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( @@ -969,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/crtthreadtraits-class.md b/docs/atl/reference/crtthreadtraits-class.md index b2dc26db6c..de1edbf63f 100644 --- a/docs/atl/reference/crtthreadtraits-class.md +++ b/docs/atl/reference/crtthreadtraits-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CRTThreadTraits Class" title: "CRTThreadTraits Class" ms.date: "11/04/2016" f1_keywords: ["CRTThreadTraits", "ATLBASE/ATL::CRTThreadTraits", "ATLBASE/ATL::CRTThreadTraits::CreateThread"] diff --git a/docs/atl/reference/csacl-class.md b/docs/atl/reference/csacl-class.md index a835a7066a..47717cec06 100644 --- a/docs/atl/reference/csacl-class.md +++ b/docs/atl/reference/csacl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CSacl Class" title: "CSacl Class" ms.date: "11/04/2016" f1_keywords: ["CSacl", "ATLSECURITY/ATL::CSacl", "ATLSECURITY/ATL::CSacl::CSacl", "ATLSECURITY/ATL::CSacl::AddAuditAce", "ATLSECURITY/ATL::CSacl::GetAceCount", "ATLSECURITY/ATL::CSacl::RemoveAce", "ATLSECURITY/ATL::CSacl::RemoveAllAces"] diff --git a/docs/atl/reference/csecurityattributes-class.md b/docs/atl/reference/csecurityattributes-class.md index bcf0fc4e10..7ba2de9bec 100644 --- a/docs/atl/reference/csecurityattributes-class.md +++ b/docs/atl/reference/csecurityattributes-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CSecurityAttributes Class" title: "CSecurityAttributes Class" ms.date: "11/04/2016" f1_keywords: ["CSecurityAttributes", "ATLSECURITY/ATL::CSecurityAttributes", "ATLSECURITY/ATL::CSecurityAttributes::CSecurityAttributes", "ATLSECURITY/ATL::CSecurityAttributes::Set"] diff --git a/docs/atl/reference/csecuritydesc-class.md b/docs/atl/reference/csecuritydesc-class.md index 86e069d97c..d504290768 100644 --- a/docs/atl/reference/csecuritydesc-class.md +++ b/docs/atl/reference/csecuritydesc-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CSecurityDesc Class" title: "CSecurityDesc Class" ms.date: "11/04/2016" f1_keywords: ["CSecurityDesc", "ATLSECURITY/ATL::CSecurityDesc", "ATLSECURITY/ATL::CSecurityDesc::CSecurityDesc", "ATLSECURITY/ATL::CSecurityDesc::FromString", "ATLSECURITY/ATL::CSecurityDesc::GetControl", "ATLSECURITY/ATL::CSecurityDesc::GetDacl", "ATLSECURITY/ATL::CSecurityDesc::GetGroup", "ATLSECURITY/ATL::CSecurityDesc::GetOwner", "ATLSECURITY/ATL::CSecurityDesc::GetPSECURITY_DESCRIPTOR", "ATLSECURITY/ATL::CSecurityDesc::GetSacl", "ATLSECURITY/ATL::CSecurityDesc::IsDaclAutoInherited", "ATLSECURITY/ATL::CSecurityDesc::IsDaclDefaulted", "ATLSECURITY/ATL::CSecurityDesc::IsDaclPresent", "ATLSECURITY/ATL::CSecurityDesc::IsDaclProtected", "ATLSECURITY/ATL::CSecurityDesc::IsGroupDefaulted", "ATLSECURITY/ATL::CSecurityDesc::IsOwnerDefaulted", "ATLSECURITY/ATL::CSecurityDesc::IsSaclAutoInherited", "ATLSECURITY/ATL::CSecurityDesc::IsSaclDefaulted", "ATLSECURITY/ATL::CSecurityDesc::IsSaclPresent", "ATLSECURITY/ATL::CSecurityDesc::IsSaclProtected", "ATLSECURITY/ATL::CSecurityDesc::IsSelfRelative", "ATLSECURITY/ATL::CSecurityDesc::MakeAbsolute", "ATLSECURITY/ATL::CSecurityDesc::MakeSelfRelative", "ATLSECURITY/ATL::CSecurityDesc::SetControl", "ATLSECURITY/ATL::CSecurityDesc::SetDacl", "ATLSECURITY/ATL::CSecurityDesc::SetGroup", "ATLSECURITY/ATL::CSecurityDesc::SetOwner", "ATLSECURITY/ATL::CSecurityDesc::SetSacl", "ATLSECURITY/ATL::CSecurityDesc::ToString"] diff --git a/docs/atl/reference/csid-class.md b/docs/atl/reference/csid-class.md index b66256092b..49be86aa61 100644 --- a/docs/atl/reference/csid-class.md +++ b/docs/atl/reference/csid-class.md @@ -1,78 +1,79 @@ --- -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 -||| -|-|-| -|[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 -||| -|-|-| -|[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. @@ -80,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(...); @@ -123,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(); ``` @@ -159,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(...); @@ -330,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(); @@ -377,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(); @@ -399,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(); @@ -421,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(); @@ -443,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(); @@ -465,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()); @@ -487,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 5d45021ef3..12a7cd1332 100644 --- a/docs/atl/reference/csimplearray-class.md +++ b/docs/atl/reference/csimplearray-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CSimpleArray Class" title: "CSimpleArray Class" ms.date: "11/04/2016" f1_keywords: ["CSimpleArray", "ATLSIMPCOLL/ATL::CSimpleArray", "ATLSIMPCOLL/ATL::CSimpleArray::CSimpleArray", "ATLSIMPCOLL/ATL::CSimpleArray::Add", "ATLSIMPCOLL/ATL::CSimpleArray::Find", "ATLSIMPCOLL/ATL::CSimpleArray::GetData", "ATLSIMPCOLL/ATL::CSimpleArray::GetSize", "ATLSIMPCOLL/ATL::CSimpleArray::Remove", "ATLSIMPCOLL/ATL::CSimpleArray::RemoveAll", "ATLSIMPCOLL/ATL::CSimpleArray::RemoveAt", "ATLSIMPCOLL/ATL::CSimpleArray::SetAtIndex"] @@ -251,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/csimplearrayequalhelper-class.md b/docs/atl/reference/csimplearrayequalhelper-class.md index d134ccb4b6..e88c64cd44 100644 --- a/docs/atl/reference/csimplearrayequalhelper-class.md +++ b/docs/atl/reference/csimplearrayequalhelper-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CSimpleArrayEqualHelper Class" title: "CSimpleArrayEqualHelper Class" ms.date: "11/04/2016" f1_keywords: ["CSimpleArrayEqualHelper", "ATLSIMPCOLL/ATL::CSimpleArrayEqualHelper", "ATLSIMPCOLL/ATL::CSimpleArrayEqualHelper::IsEqual"] diff --git a/docs/atl/reference/csimplearrayequalhelperfalse-class.md b/docs/atl/reference/csimplearrayequalhelperfalse-class.md index efcd79f8c1..9b66910ec4 100644 --- a/docs/atl/reference/csimplearrayequalhelperfalse-class.md +++ b/docs/atl/reference/csimplearrayequalhelperfalse-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CSimpleArrayEqualHelperFalse Class" title: "CSimpleArrayEqualHelperFalse Class" ms.date: "11/04/2016" f1_keywords: ["CSimpleArrayEqualHelperFalse", "ATLSIMPCOLL/ATL::CSimpleArrayEqualHelperFalse", "ATLSIMPCOLL/ATL::CSimpleArrayEqualHelperFalse::IsEqual"] diff --git a/docs/atl/reference/csimpledialog-class.md b/docs/atl/reference/csimpledialog-class.md index 04baef4219..9650d3ce7c 100644 --- a/docs/atl/reference/csimpledialog-class.md +++ b/docs/atl/reference/csimpledialog-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CSimpleDialog Class" title: "CSimpleDialog Class" ms.date: "11/04/2016" f1_keywords: ["CSimpleDialog", "ATLWIN/ATL::CSimpleDialog", "ATLWIN/ATL::CSimpleDialog::DoModal"] diff --git a/docs/atl/reference/csimplemap-class.md b/docs/atl/reference/csimplemap-class.md index d54cb75cc3..50f2040375 100644 --- a/docs/atl/reference/csimplemap-class.md +++ b/docs/atl/reference/csimplemap-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CSimpleMap Class" title: "CSimpleMap Class" ms.date: "11/04/2016" f1_keywords: ["CSimpleMap", "ATLSIMPCOLL/ATL::CSimpleMap", "ATLSIMPCOLL/ATL::CSimpleMap::_ArrayElementType", "ATLSIMPCOLL/ATL::CSimpleMap::_ArrayKeyType", "ATLSIMPCOLL/ATL::CSimpleMap::CSimpleMap", "ATLSIMPCOLL/ATL::CSimpleMap::Add", "ATLSIMPCOLL/ATL::CSimpleMap::FindKey", "ATLSIMPCOLL/ATL::CSimpleMap::FindVal", "ATLSIMPCOLL/ATL::CSimpleMap::GetKeyAt", "ATLSIMPCOLL/ATL::CSimpleMap::GetSize", "ATLSIMPCOLL/ATL::CSimpleMap::GetValueAt", "ATLSIMPCOLL/ATL::CSimpleMap::Lookup", "ATLSIMPCOLL/ATL::CSimpleMap::Remove", "ATLSIMPCOLL/ATL::CSimpleMap::RemoveAll", "ATLSIMPCOLL/ATL::CSimpleMap::RemoveAt", "ATLSIMPCOLL/ATL::CSimpleMap::ReverseLookup", "ATLSIMPCOLL/ATL::CSimpleMap::SetAt", "ATLSIMPCOLL/ATL::CSimpleMap::SetAtIndex"] diff --git a/docs/atl/reference/csimplemapequalhelper-class.md b/docs/atl/reference/csimplemapequalhelper-class.md index 10a4addcd8..05c3178fda 100644 --- a/docs/atl/reference/csimplemapequalhelper-class.md +++ b/docs/atl/reference/csimplemapequalhelper-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CSimpleMapEqualHelper Class" title: "CSimpleMapEqualHelper Class" ms.date: "11/04/2016" f1_keywords: ["CSimpleMapEqualHelper", "ATLSIMPCOLL/ATL::CSimpleMapEqualHelper", "ATLSIMPCOLL/ATL::CSimpleMapEqualHelper::IsEqualKey", "ATLSIMPCOLL/ATL::CSimpleMapEqualHelper::IsEqualValue"] diff --git a/docs/atl/reference/csimplemapequalhelperfalse-class.md b/docs/atl/reference/csimplemapequalhelperfalse-class.md index 5e0a1001e2..97e43c2e59 100644 --- a/docs/atl/reference/csimplemapequalhelperfalse-class.md +++ b/docs/atl/reference/csimplemapequalhelperfalse-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CSimpleMapEqualHelperFalse Class" title: "CSimpleMapEqualHelperFalse Class" ms.date: "11/04/2016" f1_keywords: ["CSimpleMapEqualHelperFalse", "ATLSIMPCOLL/ATL::CSimpleMapEqualHelperFalse", "ATLSIMPCOLL/ATL::CSimpleMapEqualHelperFalse::IsEqualKey", "ATLSIMPCOLL/ATL::CSimpleMapEqualHelperFalse::IsEqualValue"] diff --git a/docs/atl/reference/csnapinitemimpl-class.md b/docs/atl/reference/csnapinitemimpl-class.md index 5573e20a71..b302a376c2 100644 --- a/docs/atl/reference/csnapinitemimpl-class.md +++ b/docs/atl/reference/csnapinitemimpl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CSnapInItemImpl Class" title: "CSnapInItemImpl Class" ms.date: "11/04/2016" f1_keywords: ["CSnapInItemImpl", "ATLSNAP/ATL::CSnapInItemImpl", "ATLSNAP/ATL::CSnapInItemImpl::CSnapInItemImpl", "ATLSNAP/ATL::CSnapInItemImpl::AddMenuItems", "ATLSNAP/ATL::CSnapInItemImpl::Command", "ATLSNAP/ATL::CSnapInItemImpl::CreatePropertyPages", "ATLSNAP/ATL::CSnapInItemImpl::FillData", "ATLSNAP/ATL::CSnapInItemImpl::GetResultPaneInfo", "ATLSNAP/ATL::CSnapInItemImpl::GetResultViewType", "ATLSNAP/ATL::CSnapInItemImpl::GetScopePaneInfo", "ATLSNAP/ATL::CSnapInItemImpl::Notify", "ATLSNAP/ATL::CSnapInItemImpl::QueryPagesFor", "ATLSNAP/ATL::CSnapInItemImpl::SetMenuInsertionFlags", "ATLSNAP/ATL::CSnapInItemImpl::SetToolbarButtonInfo", "ATLSNAP/ATL::CSnapInItemImpl::UpdateMenuState", "ATLSNAP/ATL::CSnapInItemImpl::UpdateToolbarButton", "ATLSNAP/ATL::CSnapInItemImpl::m_bstrDisplayName", "ATLSNAP/ATL::CSnapInItemImpl::m_resultDataItem", "ATLSNAP/ATL::CSnapInItemImpl::m_scopeDataItem"] diff --git a/docs/atl/reference/csnapinpropertypageimpl-class.md b/docs/atl/reference/csnapinpropertypageimpl-class.md index 062479ed44..5bbd52fce6 100644 --- a/docs/atl/reference/csnapinpropertypageimpl-class.md +++ b/docs/atl/reference/csnapinpropertypageimpl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CSnapInPropertyPageImpl Class" title: "CSnapInPropertyPageImpl Class" ms.date: "11/04/2016" f1_keywords: ["CSnapInPropertyPageImpl", "ATLSNAP/ATL::CSnapInPropertyPageImpl", "ATLSNAP/ATL::CSnapInPropertyPageImpl::CSnapInPropertyPageImpl", "ATLSNAP/ATL::CSnapInPropertyPageImpl::CancelToClose", "ATLSNAP/ATL::CSnapInPropertyPageImpl::Create", "ATLSNAP/ATL::CSnapInPropertyPageImpl::OnApply", "ATLSNAP/ATL::CSnapInPropertyPageImpl::OnHelp", "ATLSNAP/ATL::CSnapInPropertyPageImpl::OnKillActive", "ATLSNAP/ATL::CSnapInPropertyPageImpl::OnQueryCancel", "ATLSNAP/ATL::CSnapInPropertyPageImpl::OnReset", "ATLSNAP/ATL::CSnapInPropertyPageImpl::OnSetActive", "ATLSNAP/ATL::CSnapInPropertyPageImpl::OnWizardBack", "ATLSNAP/ATL::CSnapInPropertyPageImpl::OnWizardFinish", "ATLSNAP/ATL::CSnapInPropertyPageImpl::OnWizardNext", "ATLSNAP/ATL::CSnapInPropertyPageImpl::QuerySiblings", "ATLSNAP/ATL::CSnapInPropertyPageImpl::SetModified", "ATLSNAP/ATL::CSnapInPropertyPageImpl::m_psp"] diff --git a/docs/atl/reference/csocketaddr-class.md b/docs/atl/reference/csocketaddr-class.md index c2f0659ab4..de051c6ae6 100644 --- a/docs/atl/reference/csocketaddr-class.md +++ b/docs/atl/reference/csocketaddr-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CSocketAddr Class" title: "CSocketAddr Class" ms.date: "10/22/2018" f1_keywords: ["CSocketAddr", "ATLSOCKET/ATL::CSocketAddr", "ATLSOCKET/ATL::CSocketAddr::CSocketAddr", "ATLSOCKET/ATL::CSocketAddr::FindAddr", "ATLSOCKET/ATL::CSocketAddr::FindINET4Addr", "ATLSOCKET/ATL::CSocketAddr::FindINET6Addr", "ATLSOCKET/ATL::CSocketAddr::GetAddrInfo", "ATLSOCKET/ATL::CSocketAddr::GetAddrInfoList"] diff --git a/docs/atl/reference/cstockpropimpl-class.md b/docs/atl/reference/cstockpropimpl-class.md index 9d70ac0f67..1f4959941f 100644 --- a/docs/atl/reference/cstockpropimpl-class.md +++ b/docs/atl/reference/cstockpropimpl-class.md @@ -1,9 +1,9 @@ --- 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 @@ -54,7 +54,7 @@ The class used to manage the type information for *T*. The default value is `CCo ### Public Methods -||| +|Name|Description| |-|-| |[get_Appearance](#get_appearance)|Call this method to get the paint style used by the control, for example, flat or 3D.| |[get_AutoSize](#get_autosize)|Call this method to get the status of the flag that indicates if the control cannot be any other size.| @@ -606,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 @@ -1099,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/cstringelementtraits-class.md b/docs/atl/reference/cstringelementtraits-class.md index f289392fe4..d314865a59 100644 --- a/docs/atl/reference/cstringelementtraits-class.md +++ b/docs/atl/reference/cstringelementtraits-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CStringElementTraits Class" title: "CStringElementTraits Class" ms.date: "11/04/2016" f1_keywords: ["CStringElementTraits", "CSTRINGT/ATL::CStringElementTraits", "CSTRINGT/ATL::CStringElementTraits::INARGTYPE", "CSTRINGT/ATL::CStringElementTraits::OUTARGTYPE", "CSTRINGT/ATL::CStringElementTraits::CompareElements", "CSTRINGT/ATL::CStringElementTraits::CompareElementsOrdered", "CSTRINGT/ATL::CStringElementTraits::CopyElements", "CSTRINGT/ATL::CStringElementTraits::Hash", "CSTRINGT/ATL::CStringElementTraits::RelocateElements"] diff --git a/docs/atl/reference/cstringelementtraitsi-class.md b/docs/atl/reference/cstringelementtraitsi-class.md index e9253a211d..089e89ec28 100644 --- a/docs/atl/reference/cstringelementtraitsi-class.md +++ b/docs/atl/reference/cstringelementtraitsi-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CStringElementTraitsI Class" title: "CStringElementTraitsI Class" ms.date: "11/04/2016" f1_keywords: ["CStringElementTraitsI", "ATLCOLL/ATL::CStringElementTraitsI", "ATLCOLL/ATL::CStringElementTraitsI::INARGTYPE", "ATLCOLL/ATL::CStringElementTraitsI::OUTARGTYPE", "ATLCOLL/ATL::CStringElementTraitsI::CompareElements", "ATLCOLL/ATL::CStringElementTraitsI::CompareElementsOrdered", "ATLCOLL/ATL::CStringElementTraitsI::Hash"] diff --git a/docs/atl/reference/cstringrefelementtraits-class.md b/docs/atl/reference/cstringrefelementtraits-class.md index 6668d3de02..ed14c61490 100644 --- a/docs/atl/reference/cstringrefelementtraits-class.md +++ b/docs/atl/reference/cstringrefelementtraits-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CStringRefElementTraits Class" title: "CStringRefElementTraits Class" ms.date: "11/04/2016" f1_keywords: ["CStringRefElementTraits", "ATLCOLL/ATL::CStringRefElementTraits", "ATLCOLL/ATL::CStringRefElementTraits::CompareElements", "ATLCOLL/ATL::CStringRefElementTraits::CompareElementsOrdered", "ATLCOLL/ATL::CStringRefElementTraits::Hash"] diff --git a/docs/atl/reference/cthreadpool-class.md b/docs/atl/reference/cthreadpool-class.md index 6679b379b6..0cca6b473f 100644 --- a/docs/atl/reference/cthreadpool-class.md +++ b/docs/atl/reference/cthreadpool-class.md @@ -1,9 +1,9 @@ --- 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 @@ -264,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/ctokengroups-class.md b/docs/atl/reference/ctokengroups-class.md index 4959849669..50ca0053c9 100644 --- a/docs/atl/reference/ctokengroups-class.md +++ b/docs/atl/reference/ctokengroups-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CTokenGroups Class" title: "CTokenGroups Class" ms.date: "11/04/2016" f1_keywords: ["CTokenGroups", "ATLSECURITY/ATL::CTokenGroups", "ATLSECURITY/ATL::CTokenGroups::CTokenGroups", "ATLSECURITY/ATL::CTokenGroups::Add", "ATLSECURITY/ATL::CTokenGroups::Delete", "ATLSECURITY/ATL::CTokenGroups::DeleteAll", "ATLSECURITY/ATL::CTokenGroups::GetCount", "ATLSECURITY/ATL::CTokenGroups::GetLength", "ATLSECURITY/ATL::CTokenGroups::GetPTOKEN_GROUPS", "ATLSECURITY/ATL::CTokenGroups::GetSidsAndAttributes", "ATLSECURITY/ATL::CTokenGroups::LookupSid"] diff --git a/docs/atl/reference/ctokenprivileges-class.md b/docs/atl/reference/ctokenprivileges-class.md index 8144718ff7..df23437d13 100644 --- a/docs/atl/reference/ctokenprivileges-class.md +++ b/docs/atl/reference/ctokenprivileges-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CTokenPrivileges Class" title: "CTokenPrivileges Class" ms.date: "11/04/2016" f1_keywords: ["CTokenPrivileges", "ATLSECURITY/ATL::CTokenPrivileges", "ATLSECURITY/ATL::CTokenPrivileges::CTokenPrivileges", "ATLSECURITY/ATL::CTokenPrivileges::Add", "ATLSECURITY/ATL::CTokenPrivileges::Delete", "ATLSECURITY/ATL::CTokenPrivileges::DeleteAll", "ATLSECURITY/ATL::CTokenPrivileges::GetCount", "ATLSECURITY/ATL::CTokenPrivileges::GetDisplayNames", "ATLSECURITY/ATL::CTokenPrivileges::GetLength", "ATLSECURITY/ATL::CTokenPrivileges::GetLuidsAndAttributes", "ATLSECURITY/ATL::CTokenPrivileges::GetNamesAndAttributes", "ATLSECURITY/ATL::CTokenPrivileges::GetPTOKEN_PRIVILEGES", "ATLSECURITY/ATL::CTokenPrivileges::LookupPrivilege"] diff --git a/docs/atl/reference/curl-class.md b/docs/atl/reference/curl-class.md index b496d20244..ff1a201f3f 100644 --- a/docs/atl/reference/curl-class.md +++ b/docs/atl/reference/curl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CUrl Class" title: "CUrl Class" ms.date: "05/06/2019" f1_keywords: ["CUrl", "ATLUTIL/ATL::CUrl", "ATLUTIL/ATL::CUrl::CUrl", "ATLUTIL/ATL::CUrl::Canonicalize", "ATLUTIL/ATL::CUrl::Clear", "ATLUTIL/ATL::CUrl::CrackUrl", "ATLUTIL/ATL::CUrl::CreateUrl", "ATLUTIL/ATL::CUrl::GetExtraInfo", "ATLUTIL/ATL::CUrl::GetExtraInfoLength", "ATLUTIL/ATL::CUrl::GetHostName", "ATLUTIL/ATL::CUrl::GetHostNameLength", "ATLUTIL/ATL::CUrl::GetPassword", "ATLUTIL/ATL::CUrl::GetPasswordLength", "ATLUTIL/ATL::CUrl::GetPortNumber", "ATLUTIL/ATL::CUrl::GetScheme", "ATLUTIL/ATL::CUrl::GetSchemeName", "ATLUTIL/ATL::CUrl::GetSchemeNameLength", "ATLUTIL/ATL::CUrl::GetUrlLength", "ATLUTIL/ATL::CUrl::GetUrlPath", "ATLUTIL/ATL::CUrl::GetUrlPathLength", "ATLUTIL/ATL::CUrl::GetUserName", "ATLUTIL/ATL::CUrl::GetUserNameLength", "ATLUTIL/ATL::CUrl::SetExtraInfo", "ATLUTIL/ATL::CUrl::SetHostName", "ATLUTIL/ATL::CUrl::SetPassword", "ATLUTIL/ATL::CUrl::SetPortNumber", "ATLUTIL/ATL::CUrl::SetScheme", "ATLUTIL/ATL::CUrl::SetSchemeName", "ATLUTIL/ATL::CUrl::SetUrlPath", "ATLUTIL/ATL::CUrl::SetUserName"] diff --git a/docs/atl/reference/cw2aex-class.md b/docs/atl/reference/cw2aex-class.md index 04d01385f6..9029cccbe7 100644 --- a/docs/atl/reference/cw2aex-class.md +++ b/docs/atl/reference/cw2aex-class.md @@ -1,13 +1,13 @@ --- +description: "Learn more about: CW2AEX Class" 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. @@ -21,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 @@ -30,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 @@ -43,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). @@ -78,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. @@ -91,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. @@ -113,7 +113,7 @@ The destructor. Frees the allocated buffer. -## CW2AEX::m_psz +## `CW2AEX::m_psz` The data member that stores the source string. @@ -121,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. @@ -129,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. @@ -139,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/cw2cwex-class.md b/docs/atl/reference/cw2cwex-class.md index c533e73ec7..58df28f8f6 100644 --- a/docs/atl/reference/cw2cwex-class.md +++ b/docs/atl/reference/cw2cwex-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CW2CWEX Class" title: "CW2CWEX Class" ms.date: "11/04/2016" f1_keywords: ["CW2CWEX", "ATLCONV/ATL::CW2CWEX", "ATLCONV/ATL::CW2CWEX::CW2CWEX", "ATLCONV/ATL::CW2CWEX::m_psz"] diff --git a/docs/atl/reference/cw2wex-class.md b/docs/atl/reference/cw2wex-class.md index a64b9ac1e6..d5c15f69f2 100644 --- a/docs/atl/reference/cw2wex-class.md +++ b/docs/atl/reference/cw2wex-class.md @@ -1,9 +1,9 @@ --- 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 @@ -99,7 +99,7 @@ Creates the buffer required for the translation. ## CW2WEX::~CW2WEX -The destructor.. +The destructor. ``` ~CW2WEX() throw(); @@ -139,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/cwin32heap-class.md b/docs/atl/reference/cwin32heap-class.md index 0e37f54e9a..8c69f91f15 100644 --- a/docs/atl/reference/cwin32heap-class.md +++ b/docs/atl/reference/cwin32heap-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CWin32Heap Class" title: "CWin32Heap Class" ms.date: "11/04/2016" f1_keywords: ["CWin32Heap", "ATLMEM/ATL::CWin32Heap", "ATLMEM/ATL::CWin32Heap::CWin32Heap", "ATLMEM/ATL::CWin32Heap::Allocate", "ATLMEM/ATL::CWin32Heap::Attach", "ATLMEM/ATL::CWin32Heap::Detach", "ATLMEM/ATL::CWin32Heap::Free", "ATLMEM/ATL::CWin32Heap::GetSize", "ATLMEM/ATL::CWin32Heap::Reallocate", "ATLMEM/ATL::CWin32Heap::m_bOwnHeap", "ATLMEM/ATL::CWin32Heap::m_hHeap"] diff --git a/docs/atl/reference/cwindow-class.md b/docs/atl/reference/cwindow-class.md index a2910f2779..c91fae3db6 100644 --- a/docs/atl/reference/cwindow-class.md +++ b/docs/atl/reference/cwindow-class.md @@ -1,11 +1,11 @@ --- +description: "Learn more about: CWindow Class" 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. @@ -24,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. @@ -233,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(); @@ -245,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. @@ -262,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. @@ -278,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. @@ -294,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. @@ -315,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. @@ -327,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. @@ -342,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. @@ -354,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. @@ -366,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. @@ -379,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. @@ -401,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. @@ -447,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. @@ -459,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. @@ -473,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. @@ -487,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. @@ -514,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(); @@ -526,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(); @@ -544,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. @@ -564,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. @@ -580,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. @@ -595,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. @@ -610,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. @@ -622,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. @@ -634,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. @@ -646,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. @@ -658,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. @@ -674,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. @@ -690,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. @@ -702,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. @@ -718,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. @@ -734,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. @@ -746,7 +746,7 @@ HWND GetDescendantWindow(int nID) const throw(); ### Parameters -*nID*
+*`nID`*\ [in] The identifier of the descendant window to be retrieved. ### Return Value @@ -757,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. @@ -770,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). @@ -797,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. @@ -812,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. @@ -841,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. @@ -854,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. @@ -873,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. @@ -893,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(); @@ -911,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(); @@ -921,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. @@ -933,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 @@ -942,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. @@ -954,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. @@ -966,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. @@ -978,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(); @@ -990,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. @@ -1002,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. @@ -1018,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. @@ -1030,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. @@ -1045,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. @@ -1061,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. @@ -1077,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. @@ -1091,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. @@ -1103,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. @@ -1113,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. @@ -1129,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. @@ -1141,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. @@ -1155,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. @@ -1165,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. @@ -1177,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. @@ -1193,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. @@ -1208,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. @@ -1229,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. @@ -1241,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. @@ -1257,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. @@ -1269,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. @@ -1283,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. @@ -1315,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. @@ -1327,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. @@ -1343,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. @@ -1355,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. @@ -1367,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. @@ -1386,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. @@ -1398,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. @@ -1416,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. @@ -1428,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. @@ -1444,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. @@ -1456,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. @@ -1468,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. @@ -1480,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. @@ -1496,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. @@ -1508,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. @@ -1524,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. @@ -1540,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. @@ -1556,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. @@ -1572,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`. @@ -1584,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(); @@ -1596,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. @@ -1615,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. @@ -1632,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. @@ -1649,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. @@ -1668,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. @@ -1714,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. @@ -1766,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. @@ -1780,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. @@ -1792,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. @@ -1823,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. @@ -1831,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. @@ -1841,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(); @@ -1853,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(); @@ -1881,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. @@ -1907,7 +1901,7 @@ Contains default window dimensions. static RECT rcDefault; ``` -## CWindow::RedrawWindow +## `CWindow::RedrawWindow` Updates a specified rectangle or region in the client area. @@ -1922,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. @@ -1938,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. @@ -1957,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. @@ -1977,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. @@ -1995,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. @@ -2014,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. @@ -2030,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( @@ -2051,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. @@ -2071,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. @@ -2100,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. @@ -2114,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. @@ -2130,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. @@ -2142,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. @@ -2154,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. @@ -2174,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. @@ -2186,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. @@ -2198,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(); @@ -2214,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(); @@ -2230,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(); @@ -2250,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 @@ -2262,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. @@ -2274,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. @@ -2286,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(); @@ -2302,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 @@ -2313,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. @@ -2326,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. @@ -2341,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. @@ -2357,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. @@ -2372,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. @@ -2384,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. @@ -2396,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. @@ -2411,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. @@ -2425,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. @@ -2448,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. @@ -2462,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. @@ -2474,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. @@ -2490,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. @@ -2502,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. @@ -2518,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. @@ -2530,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. @@ -2542,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. @@ -2558,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. @@ -2570,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. @@ -2586,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. @@ -2598,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. @@ -2613,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 009802be41..d2041bc669 100644 --- a/docs/atl/reference/cwindowimpl-class.md +++ b/docs/atl/reference/cwindowimpl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CWindowImpl Class" title: "CWindowImpl Class" ms.date: "11/04/2016" f1_keywords: ["CWindowImpl", "ATLWIN/ATL::CWindowImpl", "ATLWIN/ATL::CWindowImpl::Create", "ATLWIN/ATL::CWindowImpl::DefWindowProc", "ATLWIN/ATL::CWindowImpl::GetCurrentMessage", "ATLWIN/ATL::CWindowImpl::GetWindowProc", "ATLWIN/ATL::CWindowImpl::OnFinalMessage", "ATLWIN/ATL::CWindowImpl::SubclassWindow", "ATLWIN/ATL::CWindowImpl::UnsubclassWindow", "ATLWIN/ATL::CWindowImpl::GetWndClassInfo", "ATLWIN/ATL::CWindowImpl::WindowProc", "ATLWIN/ATL::CWindowImpl::m_pfnSuperWindowProc"] @@ -40,7 +41,7 @@ A [traits class](../../atl/understanding-window-traits.md) that defines styles f ### CWindowImplBaseT Methods -||| +|Name|Description| |-|-| |[DefWindowProc](#defwindowproc)|Provides default message processing.| |[GetCurrentMessage](#getcurrentmessage)|Returns the current message.| @@ -51,14 +52,14 @@ A [traits class](../../atl/understanding-window-traits.md) that defines styles f ### Static Methods -||| +|Name|Description| |-|-| |[GetWndClassInfo](#getwndclassinfo)|Returns a static instance of [CWndClassInfo](../../atl/reference/cwndclassinfo-class.md), which manages the window class information.| |[WindowProc](#windowproc)|Processes messages sent to the window.| ### Data Members -||| +|Name|Description| |-|-| |[m_pfnSuperWindowProc](#m_pfnsuperwindowproc)|Points to the window class's original window procedure.| @@ -275,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/cwintraits-class.md b/docs/atl/reference/cwintraits-class.md index edf9eab9a4..e7d7b65eab 100644 --- a/docs/atl/reference/cwintraits-class.md +++ b/docs/atl/reference/cwintraits-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CWinTraits Class" title: "CWinTraits Class" ms.date: "11/04/2016" f1_keywords: ["CWinTraits", "ATLWIN/ATL::CWinTraits", "ATLWIN/ATL::CWinTraits::GetWndExStyle", "ATLWIN/ATL::CWinTraits::GetWndStyle"] diff --git a/docs/atl/reference/cwintraitsor-class.md b/docs/atl/reference/cwintraitsor-class.md index a705b20e6e..fbc54c0034 100644 --- a/docs/atl/reference/cwintraitsor-class.md +++ b/docs/atl/reference/cwintraitsor-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CWinTraitsOR Class" title: "CWinTraitsOR Class" ms.date: "11/04/2016" f1_keywords: ["CWinTraitsOR", "ATLWIN/ATL::CWinTraitsOR", "ATLWIN/ATL::CWinTraitsOR::GetWndExStyle", "ATLWIN/ATL::CWinTraitsOR::GetWndStyle"] diff --git a/docs/atl/reference/cwndclassinfo-class.md b/docs/atl/reference/cwndclassinfo-class.md index ad78e3059c..0ac4762455 100644 --- a/docs/atl/reference/cwndclassinfo-class.md +++ b/docs/atl/reference/cwndclassinfo-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CWndClassInfo Class" title: "CWndClassInfo Class" ms.date: "11/04/2016" f1_keywords: ["CWndClassInfo", "ATLWIN/ATL::CWndClassInfo", "ATLWIN/ATL::Register", "ATLWIN/ATL::m_atom", "ATLWIN/ATL::m_bSystemCursor", "ATLWIN/ATL::m_lpszCursorID", "ATLWIN/ATL::m_lpszOrigName", "ATLWIN/ATL::m_szAutoName", "ATLWIN/ATL::m_wc", "ATLWIN/ATL::pWndProc"] @@ -22,13 +23,13 @@ class CWndClassInfo ### Public Methods -||| +|Name|Description| |-|-| |[Register](#register)|Registers the window class.| ### Data Members -||| +|Name|Description| |-|-| |[m_atom](#m_atom)|Uniquely identifies the registered window class.| |[m_bSystemCursor](#m_bsystemcursor)|Specifies whether the cursor resource refers to a system cursor or to a cursor contained in a module resource.| diff --git a/docs/atl/reference/cworkerthread-class.md b/docs/atl/reference/cworkerthread-class.md index bcda16799c..a0171833ba 100644 --- a/docs/atl/reference/cworkerthread-class.md +++ b/docs/atl/reference/cworkerthread-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CWorkerThread Class" title: "CWorkerThread Class" ms.date: "11/04/2016" f1_keywords: ["CWorkerThread", "ATLUTIL/ATL::CWorkerThread", "ATLUTIL/ATL::CWorkerThread::CWorkerThread", "ATLUTIL/ATL::CWorkerThread::AddHandle", "ATLUTIL/ATL::CWorkerThread::AddTimer", "ATLUTIL/ATL::CWorkerThread::GetThreadHandle", "ATLUTIL/ATL::CWorkerThread::GetThreadId", "ATLUTIL/ATL::CWorkerThread::Initialize", "ATLUTIL/ATL::CWorkerThread::RemoveHandle", "ATLUTIL/ATL::CWorkerThread::Shutdown"] diff --git a/docs/atl/reference/debugging-and-error-reporting-global-functions.md b/docs/atl/reference/debugging-and-error-reporting-global-functions.md index 1ef7f2aa0a..defba9ea3c 100644 --- a/docs/atl/reference/debugging-and-error-reporting-global-functions.md +++ b/docs/atl/reference/debugging-and-error-reporting-global-functions.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Debugging and Error Reporting Global Functions" title: "Debugging and Error Reporting Global Functions" ms.date: "11/04/2016" f1_keywords: ["atlcomcli/ATL::AtlHresultFromLastError", "atlcom/ATL::AtlReportError", "atldef/ATL::AtlThrow"] @@ -9,7 +10,7 @@ ms.assetid: 11339c02-98cd-428d-b3b9-7deeb155a6a3 These functions provide useful debugging and trace facilities. -||| +|Name|Description| |-|-| |[AtlHresultFromLastError](debugging-and-error-reporting-global-functions.md#atlhresultfromlasterror)|Returns a `GetLastError` error code in the form of an HRESULT.| |[AtlHresultFromWin32](debugging-and-error-reporting-global-functions.md#atlhresultfromwin32)|Converts a Win32 error code into an HRESULT.| @@ -185,7 +186,7 @@ For ATL projects, it is possible to provide your own implementation of this func [!code-cpp[NVC_ATL_Windowing#95](../../atl/codesnippet/cpp/debugging-and-error-reporting-global-functions_2.h)] -## Requirements +### Requirements **Header:** atldef.h @@ -207,7 +208,7 @@ If _ATL_NO_EXCEPTIONS is not defined in an ATL project, the function throws a [C If _ATL_NO_EXCEPTIONS is defined, the function causes an assertion failure instead of throwing an exception. -## Requirements +### Requirements **Header:** atldef.h diff --git a/docs/atl/reference/debugging-and-error-reporting-macros.md b/docs/atl/reference/debugging-and-error-reporting-macros.md index a117a291ae..463ef4c007 100644 --- a/docs/atl/reference/debugging-and-error-reporting-macros.md +++ b/docs/atl/reference/debugging-and-error-reporting-macros.md @@ -1,7 +1,8 @@ --- +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 --- @@ -9,7 +10,7 @@ ms.assetid: 4da9b87f-ec5c-4a32-ab93-637780909b9d These macros provide useful debugging and trace facilities. -||| +|Name|Description| |-|-| |[_ATL_DEBUG_INTERFACES](#_atl_debug_interfaces)|Writes, to the output window, any interface leaks that are detected when `_Module.Term` is called.| |[_ATL_DEBUG_QI](#_atl_debug_qi)|Writes all calls to `QueryInterface` to the output window.| @@ -81,7 +82,7 @@ Expression (including pointers) that evaluates to nonzero or 0. In debug builds, ATLASSERT evaluates *booleanExpression* and generates a debug report when the result is false. -## Requirements +### Requirements **Header:** atldef.h @@ -118,7 +119,7 @@ The difference between ATLENSURE and ATLASSERT is that ATLENSURE throws an excep [!code-cpp[NVC_ATL_Utilities#108](../../atl/codesnippet/cpp/debugging-and-error-reporting-macros_1.cpp)] -## Requirements +### Requirements **Header:** afx.h @@ -143,7 +144,7 @@ In release builds, simply returns E_NOTIMPL. [!code-cpp[NVC_ATL_Utilities#127](../../atl/codesnippet/cpp/debugging-and-error-reporting-macros_2.cpp)] -## Requirements +### Requirements **Header:** atltrace.h diff --git a/docs/atl/reference/default-atl-project-configurations.md b/docs/atl/reference/default-atl-project-configurations.md index 64322e635f..0b8caec7af 100644 --- a/docs/atl/reference/default-atl-project-configurations.md +++ b/docs/atl/reference/default-atl-project-configurations.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Default ATL Project Configurations" title: "Default ATL Project Configurations" ms.date: "10/20/2017" helpviewer_keywords: ["ATL projects, default configurations"] diff --git a/docs/atl/reference/device-context-global-functions.md b/docs/atl/reference/device-context-global-functions.md index eccdceccbe..7ef43f0431 100644 --- a/docs/atl/reference/device-context-global-functions.md +++ b/docs/atl/reference/device-context-global-functions.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Device Context Global Functions" title: "Device Context Global Functions" ms.date: "11/04/2016" f1_keywords: ["atlwin/ATL::AtlCreateTargetDC"] @@ -8,7 +9,7 @@ ms.assetid: 08ec28f6-daff-4882-9544-e8a4639d05c4 This function creates a device context for a given device. -||| +|Name|Description| |-|-| |[AtlCreateTargetDC](#atlcreatetargetdc)|Creates a device context.| diff --git a/docs/atl/reference/event-handling-global-functions.md b/docs/atl/reference/event-handling-global-functions.md index 45dbc01812..69c6f619b6 100644 --- a/docs/atl/reference/event-handling-global-functions.md +++ b/docs/atl/reference/event-handling-global-functions.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Event Handling Global Functions" title: "Event Handling Global Functions" ms.date: "11/04/2016" f1_keywords: ["atlbase/ATL::AtlWaitWithMessageLoop"] @@ -12,7 +13,7 @@ This function provides an event handler. > [!IMPORTANT] > The function listed in the following table cannot be used in applications that execute in the Windows Runtime. -||| +|Name|Description| |-|-| |[AtlWaitWithMessageLoop](#atlwaitwithmessageloop)|Waits for an object to be signaled, meanwhile dispatching window messages as needed.| diff --git a/docs/atl/reference/exception-handling-macros.md b/docs/atl/reference/exception-handling-macros.md index 83bda37e74..44f9993452 100644 --- a/docs/atl/reference/exception-handling-macros.md +++ b/docs/atl/reference/exception-handling-macros.md @@ -1,7 +1,8 @@ --- +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 --- @@ -9,7 +10,7 @@ ms.assetid: a8385d34-3fb0-4006-a42a-de045cacf0f4 These macros provide support for exception handling. -||| +|Name|Description| |-|-| |[_ATLCATCH](#_atlcatch)|Statement(s) to handle errors occurring in the associated `_ATLTRY`.| |[_ATLCATCHALL](#_atlcatchall)|Statement(s) to handle errors occurring in the associated `_ATLTRY`.| diff --git a/docs/atl/reference/iatlautothreadmodule-class.md b/docs/atl/reference/iatlautothreadmodule-class.md index 37ebd8f254..42df620330 100644 --- a/docs/atl/reference/iatlautothreadmodule-class.md +++ b/docs/atl/reference/iatlautothreadmodule-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IAtlAutoThreadModule Class" title: "IAtlAutoThreadModule Class" ms.date: "11/04/2016" f1_keywords: ["IAtlAutoThreadModule", "atlbase/ATL::IAtlAutoThreadModule"] diff --git a/docs/atl/reference/iatlmemmgr-class.md b/docs/atl/reference/iatlmemmgr-class.md index 7dac87c9fa..46acd30174 100644 --- a/docs/atl/reference/iatlmemmgr-class.md +++ b/docs/atl/reference/iatlmemmgr-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IAtlMemMgr Class" title: "IAtlMemMgr Class" ms.date: "11/04/2016" f1_keywords: ["IAtlMemMgr", "ATLMEM/ATL::IAtlMemMgr", "ATLMEM/ATL::Allocate", "ATLMEM/ATL::Free", "ATLMEM/ATL::GetSize", "ATLMEM/ATL::Reallocate"] @@ -19,7 +20,7 @@ __interface __declspec(uuid("654F7EF5-CFDF-4df9-A450-6C6A13C622C0")) IAtlMemMgr ### Methods -||| +|Name|Description| |-|-| |[Allocate](#allocate)|Call this method to allocate a block of memory.| |[Free](#free)|Call this method to free a block of memory.| @@ -922,7 +923,7 @@ Calling this method is equivalent to calling [IAxWinHostWindowLic::CreateControl ### Example -See [Hosting ActiveX Controls Using ATL AXHost](../../atl/hosting-activex-controls-using-atl-axhost.md) 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 @@ -950,7 +951,7 @@ See [IAxWinHostWindow::CreateControlEx](#createcontrolex) for a description of t ### Example -See [Hosting ActiveX Controls Using ATL AXHost](../../atl/hosting-activex-controls-using-atl-axhost.md) 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 675d1e3905..f1799cf5b2 100644 --- a/docs/atl/reference/iaxwinambientdispatch-interface.md +++ b/docs/atl/reference/iaxwinambientdispatch-interface.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IAxWinAmbientDispatch Interface" title: "IAxWinAmbientDispatch Interface" ms.date: "11/04/2016" f1_keywords: ["IAxWinAmbientDispatch", "ATLIFACE/ATL::IAxWinAmbientDispatch", "ATLIFACE/ATL::get_AllowContextMenu", "ATLIFACE/ATL::get_AllowShowUI", "ATLIFACE/ATL::get_AllowWindowlessActivation", "ATLIFACE/ATL::get_BackColor", "ATLIFACE/ATL::get_DisplayAsDefault", "ATLIFACE/ATL::get_DocHostDoubleClickFlags", "ATLIFACE/ATL::get_DocHostFlags", "ATLIFACE/ATL::get_Font", "ATLIFACE/ATL::get_ForeColor", "ATLIFACE/ATL::get_LocaleID", "ATLIFACE/ATL::get_MessageReflect", "ATLIFACE/ATL::get_OptionKeyPath", "ATLIFACE/ATL::get_ShowGrabHandles", "ATLIFACE/ATL::get_ShowHatching", "ATLIFACE/ATL::get_UserMode", "ATLIFACE/ATL::put_AllowContextMenu", "ATLIFACE/ATL::put_AllowShowUI", "ATLIFACE/ATL::put_AllowWindowlessActivation", "ATLIFACE/ATL::put_BackColor", "ATLIFACE/ATL::put_DisplayAsDefault", "ATLIFACE/ATL::put_DocHostDoubleClickFlags", "ATLIFACE/ATL::put_DocHostFlags", "ATLIFACE/ATL::put_Font", "ATLIFACE/ATL::put_ForeColor", "ATLIFACE/ATL::put_LocaleID", "ATLIFACE/ATL::put_MessageReflect", "ATLIFACE/ATL::put_OptionKeyPath", "ATLIFACE/ATL::put_UserMode"] @@ -22,7 +23,7 @@ interface IAxWinAmbientDispatch : IDispatch ### Methods -||| +|Name|Description| |-|-| |[get_AllowContextMenu](#get_allowcontextmenu)|The `AllowContextMenu` property specifies whether the hosted control is allowed to display its own context menu.| |[get_AllowShowUI](#get_allowshowui)|The `AllowShowUI` property specifies whether the hosted control is allowed to display its own user interface.| @@ -61,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/hosting-activex-controls-using-atl-axhost.md) 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 245a0dbf34..4df19f4e98 100644 --- a/docs/atl/reference/iaxwinambientdispatchex-interface.md +++ b/docs/atl/reference/iaxwinambientdispatchex-interface.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IAxWinAmbientDispatchEx Interface" title: "IAxWinAmbientDispatchEx Interface" ms.date: "11/04/2016" f1_keywords: ["IAxWinAmbientDispatchEx", "ATLIFACE/ATL::IAxWinAmbientDispatchEx", "ATLIFACE/ATL::SetAmbientDispatch"] @@ -22,7 +23,7 @@ MIDL_INTERFACE("B2D0778B - AC99 - 4c58 - A5C8 - E7724E5316B5") IAxWinAmbientDisp ### Methods -||| +|Name|Description| |-|-| |[SetAmbientDispatch](#setambientdispatch)|This method is called to supplement the default ambient property interface with a user-defined interface.| @@ -36,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/hosting-activex-controls-using-atl-axhost.md) 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/iaxwinhostwindow-interface.md b/docs/atl/reference/iaxwinhostwindow-interface.md index 9268326bc4..38ea65043d 100644 --- a/docs/atl/reference/iaxwinhostwindow-interface.md +++ b/docs/atl/reference/iaxwinhostwindow-interface.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IAxWinHostWindow Interface" title: "IAxWinHostWindow Interface" ms.date: "11/04/2016" f1_keywords: ["IAxWinHostWindow", "ATLIFACE/ATL::IAxWinHostWindow", "ATLIFACE/ATL::AttachControl", "ATLIFACE/ATL::CreateControl", "ATLIFACE/ATL::CreateControlEx", "ATLIFACE/ATL::QueryControl", "ATLIFACE/ATL::SetExternalDispatch", "ATLIFACE/ATL::SetExternalUIHandler"] @@ -22,7 +23,7 @@ interface IAxWinHostWindow : IUnknown ### Methods -||| +|Name|Description| |-|-| |[AttachControl](#attachcontrol)|Attaches an existing control to the host object.| |[CreateControl](#createcontrol)|Creates a control and attaches it to the host object.| diff --git a/docs/atl/reference/iaxwinhostwindowlic-interface.md b/docs/atl/reference/iaxwinhostwindowlic-interface.md index 0424951ff6..e2d65671f2 100644 --- a/docs/atl/reference/iaxwinhostwindowlic-interface.md +++ b/docs/atl/reference/iaxwinhostwindowlic-interface.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IAxWinHostWindowLic Interface" title: "IAxWinHostWindowLic Interface" ms.date: "11/04/2016" f1_keywords: ["IAxWinHostWindowLic", "ATLIFACE/ATL::IAxWinHostWindowLic", "ATLIFACE/ATL::CreateControlLic", "ATLIFACE/ATL::CreateControlLicEx"] @@ -19,7 +20,7 @@ interface IAxWinHostWindowLic : IAxWinHostWindow ### Methods -||| +|Name|Description| |-|-| |[CreateControlLic](#createcontrollic)|Creates a licensed control and attaches it to the host object.| |[CreateControlLicEx](#createcontrollicex)|Creates a licensed control, attaches it to the host object, and optionally sets up an event handler.| @@ -28,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/hosting-activex-controls-using-atl-axhost.md) 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 @@ -64,7 +65,7 @@ Calling this method is equivalent to calling [IAxWinHostWindowLic::CreateControl ### Example -See [Hosting ActiveX Controls Using ATL AXHost](../../atl/hosting-activex-controls-using-atl-axhost.md) 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 @@ -92,4 +93,4 @@ See [IAxWinHostWindow::CreateControlEx](../../atl/reference/iaxwinhostwindow-int ### Example -See [Hosting ActiveX Controls Using ATL AXHost](../../atl/hosting-activex-controls-using-atl-axhost.md) 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/icollectiononstlimpl-class.md b/docs/atl/reference/icollectiononstlimpl-class.md index 8bca109cb6..58c7584c39 100644 --- a/docs/atl/reference/icollectiononstlimpl-class.md +++ b/docs/atl/reference/icollectiononstlimpl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ICollectionOnSTLImpl Class" title: "ICollectionOnSTLImpl Class" ms.date: "11/04/2016" f1_keywords: ["ICollectionOnSTLImpl", "ATLCOM/ATL::ICollectionOnSTLImpl", "ATLCOM/ATL::ICollectionOnSTLImpl::get__NewEnum", "ATLCOM/ATL::ICollectionOnSTLImpl::getcount", "ATLCOM/ATL::ICollectionOnSTLImpl::get_Item", "ATLCOM/ATL::ICollectionOnSTLImpl::m_coll"] diff --git a/docs/atl/reference/iconnectionpointcontainerimpl-class.md b/docs/atl/reference/iconnectionpointcontainerimpl-class.md index c52fe4e64e..fd6e2362ee 100644 --- a/docs/atl/reference/iconnectionpointcontainerimpl-class.md +++ b/docs/atl/reference/iconnectionpointcontainerimpl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IConnectionPointContainerImpl Class" title: "IConnectionPointContainerImpl Class" ms.date: "11/04/2016" f1_keywords: ["IConnectionPointContainerImpl", "ATLCOM/ATL::IConnectionPointContainerImpl", "ATLCOM/ATL::IConnectionPointContainerImpl::EnumConnectionPoints", "ATLCOM/ATL::IConnectionPointContainerImpl::FindConnectionPoint"] diff --git a/docs/atl/reference/iconnectionpointimpl-class.md b/docs/atl/reference/iconnectionpointimpl-class.md index 59b68171d9..2b51b7bc46 100644 --- a/docs/atl/reference/iconnectionpointimpl-class.md +++ b/docs/atl/reference/iconnectionpointimpl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IConnectionPointImpl Class" title: "IConnectionPointImpl Class" ms.date: "11/04/2016" f1_keywords: ["IConnectionPointImpl", "ATLCOM/ATL::IConnectionPointImpl", "ATLCOM/ATL::IConnectionPointImpl::Advise", "ATLCOM/ATL::IConnectionPointImpl::EnumConnections", "ATLCOM/ATL::IConnectionPointImpl::GetConnectionInterface", "ATLCOM/ATL::IConnectionPointImpl::GetConnectionPointContainer", "ATLCOM/ATL::IConnectionPointImpl::Unadvise", "ATLCOM/ATL::IConnectionPointImpl::m_vec"] diff --git a/docs/atl/reference/idataobjectimpl-class.md b/docs/atl/reference/idataobjectimpl-class.md index a3b57a3d14..3ebc3c4402 100644 --- a/docs/atl/reference/idataobjectimpl-class.md +++ b/docs/atl/reference/idataobjectimpl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IDataObjectImpl Class" title: "IDataObjectImpl Class" ms.date: "11/04/2016" f1_keywords: ["IDataObjectImpl", "ATLCTL/ATL::IDataObjectImpl", "ATLCTL/ATL::IDataObjectImpl::DAdvise", "ATLCTL/ATL::IDataObjectImpl::DUnadvise", "ATLCTL/ATL::IDataObjectImpl::EnumDAdvise", "ATLCTL/ATL::IDataObjectImpl::EnumFormatEtc", "ATLCTL/ATL::IDataObjectImpl::FireDataChange", "ATLCTL/ATL::IDataObjectImpl::GetCanonicalFormatEtc", "ATLCTL/ATL::IDataObjectImpl::GetData", "ATLCTL/ATL::IDataObjectImpl::GetDataHere", "ATLCTL/ATL::IDataObjectImpl::QueryGetData", "ATLCTL/ATL::IDataObjectImpl::SetData"] diff --git a/docs/atl/reference/idispatchimpl-class.md b/docs/atl/reference/idispatchimpl-class.md index 5fd65880b4..e44623c762 100644 --- a/docs/atl/reference/idispatchimpl-class.md +++ b/docs/atl/reference/idispatchimpl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IDispatchImpl Class" title: "IDispatchImpl Class" ms.date: "11/04/2016" f1_keywords: ["IDispatchImpl", "ATLCOM/ATL::IDispatchImpl", "ATLCOM/ATL::IDispatchImpl::IDispatchImpl", "ATLCOM/ATL::IDispatchImpl::GetIDsOfNames", "ATLCOM/ATL::IDispatchImpl::GetTypeInfo", "ATLCOM/ATL::IDispatchImpl::GetTypeInfoCount", "ATLCOM/ATL::IDispatchImpl::Invoke"] diff --git a/docs/atl/reference/idispeventimpl-class.md b/docs/atl/reference/idispeventimpl-class.md index 2e30973f95..ef54c3c7b5 100644 --- a/docs/atl/reference/idispeventimpl-class.md +++ b/docs/atl/reference/idispeventimpl-class.md @@ -1,11 +1,11 @@ --- 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. @@ -14,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 @@ -53,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 @@ -77,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 @@ -96,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, @@ -118,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, @@ -149,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); @@ -188,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 @@ -200,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; ``` @@ -224,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/idispeventsimpleimpl-class.md b/docs/atl/reference/idispeventsimpleimpl-class.md index 22386ac001..c76ceee129 100644 --- a/docs/atl/reference/idispeventsimpleimpl-class.md +++ b/docs/atl/reference/idispeventsimpleimpl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IDispEventSimpleImpl Class" title: "IDispEventSimpleImpl Class" ms.date: "11/04/2016" f1_keywords: ["IDispEventSimpleImpl", "ATLCOM/ATL::IDispEventSimpleImpl", "ATLCOM/ATL::IDispEventSimpleImpl::Advise", "ATLCOM/ATL::IDispEventSimpleImpl::DispEventAdvise", "ATLCOM/ATL::IDispEventSimpleImpl::DispEventUnadvise", "ATLCOM/ATL::IDispEventSimpleImpl::GetIDsOfNames", "ATLCOM/ATL::IDispEventSimpleImpl::GetTypeInfo", "ATLCOM/ATL::IDispEventSimpleImpl::GetTypeInfoCount", "ATLCOM/ATL::IDispEventSimpleImpl::Invoke", "ATLCOM/ATL::IDispEventSimpleImpl::Unadvise"] diff --git a/docs/atl/reference/idochostuihandlerdispatch-interface.md b/docs/atl/reference/idochostuihandlerdispatch-interface.md index d644040fc1..d748d3e3df 100644 --- a/docs/atl/reference/idochostuihandlerdispatch-interface.md +++ b/docs/atl/reference/idochostuihandlerdispatch-interface.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IDocHostUIHandlerDispatch Interface" title: "IDocHostUIHandlerDispatch Interface" ms.date: "07/02/2019" f1_keywords: ["IDocHostUIHandlerDispatch", "atlbase/ATL::IDocHostUIHandlerDispatch"] @@ -25,7 +26,7 @@ interface IDocHostUIHandlerDispatch : IDispatch > [!NOTE] > The links in the following table are to the INet SDK reference topics for the members of the [IDocUIHostHandler](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753260\(v=vs.85\)) interface. `IDocHostUIHandlerDispatch` has the same functionality as `IDocUIHostHandler`, with the difference being that `IDocHostUIHandlerDispatch` is a dispinterface whereas `IDocUIHostHandler` is a custom interface. -||| +|Name|Description| |-|-| |[EnableModeless](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753253\(v=vs.85\))|Called from MSHTML implementation of [IOleInPlaceActiveObject::EnableModeless](/windows/win32/api/oleidl/nf-oleidl-ioleinplaceactiveobject-enablemodeless). Also called when MSHTML displays modal UI.| |[FilterDataObject](/previous-versions/windows/internet-explorer/ie-developer/platform-apis/aa753254\(v=vs.85\))|Called on the host by MSHTML to allow the host to replace MSHTML's data object.| diff --git a/docs/atl/reference/ienumonstlimpl-class.md b/docs/atl/reference/ienumonstlimpl-class.md index 7dd99ea06b..c8c694372a 100644 --- a/docs/atl/reference/ienumonstlimpl-class.md +++ b/docs/atl/reference/ienumonstlimpl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IEnumOnSTLImpl Class" title: "IEnumOnSTLImpl Class" ms.date: "11/04/2016" f1_keywords: ["IEnumOnSTLImpl", "ATLCOM/ATL::IEnumOnSTLImpl", "ATLCOM/ATL::IEnumOnSTLImpl::Clone", "ATLCOM/ATL::IEnumOnSTLImpl::Init", "ATLCOM/ATL::IEnumOnSTLImpl::Next", "ATLCOM/ATL::IEnumOnSTLImpl::Reset", "ATLCOM/ATL::IEnumOnSTLImpl::Skip", "ATLCOM/ATL::IEnumOnSTLImpl::m_iter", "ATLCOM/ATL::IEnumOnSTLImpl::m_pcollection", "ATLCOM/ATL::IEnumOnSTLImpl::m_spUnk"] diff --git a/docs/atl/reference/interfaces-atl-control-wizard.md b/docs/atl/reference/interfaces-atl-control-wizard.md index e7e4a350cf..97794e03f9 100644 --- a/docs/atl/reference/interfaces-atl-control-wizard.md +++ b/docs/atl/reference/interfaces-atl-control-wizard.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Interfaces, ATL Control Wizard" title: "Interfaces, ATL Control Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.codewiz.class.atl.control.interfaces"] diff --git a/docs/atl/reference/iobjectsafetyimpl-class.md b/docs/atl/reference/iobjectsafetyimpl-class.md index 8d42815b40..dee092995f 100644 --- a/docs/atl/reference/iobjectsafetyimpl-class.md +++ b/docs/atl/reference/iobjectsafetyimpl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IObjectSafetyImpl Class" title: "IObjectSafetyImpl Class" ms.date: "11/04/2016" f1_keywords: ["IObjectSafetyImpl", "ATLCTL/ATL::IObjectSafetyImpl", "ATLCTL/ATL::IObjectSafetyImpl::GetInterfaceSafetyOptions", "ATLCTL/ATL::IObjectSafetyImpl::SetInterfaceSafetyOptions", "ATLCTL/ATL::IObjectSafetyImpl::m_dwCurrentSafety"] diff --git a/docs/atl/reference/iobjectwithsiteimpl-class.md b/docs/atl/reference/iobjectwithsiteimpl-class.md index eac5b95656..5ae9a4b8d7 100644 --- a/docs/atl/reference/iobjectwithsiteimpl-class.md +++ b/docs/atl/reference/iobjectwithsiteimpl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IObjectWithSiteImpl Class" title: "IObjectWithSiteImpl Class" ms.date: "11/04/2016" f1_keywords: ["IObjectWithSiteImpl", "ATLCOM/ATL::IObjectWithSiteImpl", "ATLCOM/ATL::IObjectWithSiteImpl::GetSite", "ATLCOM/ATL::IObjectWithSiteImpl::SetChildSite", "ATLCOM/ATL::IObjectWithSiteImpl::SetSite", "ATLCOM/ATL::IObjectWithSiteImpl::m_spUnkSite"] diff --git a/docs/atl/reference/iolecontrolimpl-class.md b/docs/atl/reference/iolecontrolimpl-class.md index a9fe4c7585..6c3430e9ce 100644 --- a/docs/atl/reference/iolecontrolimpl-class.md +++ b/docs/atl/reference/iolecontrolimpl-class.md @@ -1,9 +1,9 @@ --- 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 @@ -21,7 +21,7 @@ class IOleControlImpl #### Parameters -*T*
+*T*\ Your class, derived from `IOleControlImpl`. ## Members @@ -75,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 @@ -115,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/ioleinplaceactiveobjectimpl-class.md b/docs/atl/reference/ioleinplaceactiveobjectimpl-class.md index 136cf6f050..64fcdcd25b 100644 --- a/docs/atl/reference/ioleinplaceactiveobjectimpl-class.md +++ b/docs/atl/reference/ioleinplaceactiveobjectimpl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IOleInPlaceActiveObjectImpl Class" title: "IOleInPlaceActiveObjectImpl Class" ms.date: "11/04/2016" f1_keywords: ["IOleInPlaceActiveObjectImpl", "ATLCTL/ATL::IOleInPlaceActiveObjectImpl", "ATLCTL/ATL::IOleInPlaceActiveObjectImpl::ContextSensitiveHelp", "ATLCTL/ATL::IOleInPlaceActiveObjectImpl::EnableModeless", "ATLCTL/ATL::IOleInPlaceActiveObjectImpl::GetWindow", "ATLCTL/ATL::IOleInPlaceActiveObjectImpl::OnDocWindowActivate", "ATLCTL/ATL::IOleInPlaceActiveObjectImpl::OnFrameWindowActivate", "ATLCTL/ATL::IOleInPlaceActiveObjectImpl::ResizeBorder", "ATLCTL/ATL::IOleInPlaceActiveObjectImpl::TranslateAccelerator"] diff --git a/docs/atl/reference/ioleinplaceobjectwindowlessimpl-class.md b/docs/atl/reference/ioleinplaceobjectwindowlessimpl-class.md index b265d237ea..d34f0d80b9 100644 --- a/docs/atl/reference/ioleinplaceobjectwindowlessimpl-class.md +++ b/docs/atl/reference/ioleinplaceobjectwindowlessimpl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IOleInPlaceObjectWindowlessImpl Class" title: "IOleInPlaceObjectWindowlessImpl Class" ms.date: "11/04/2016" f1_keywords: ["IOleInPlaceObjectWindowlessImpl", "ATLCTL/ATL::IOleInPlaceObjectWindowlessImpl", "ATLCTL/ATL::IOleInPlaceObjectWindowlessImpl::ContextSensitiveHelp", "ATLCTL/ATL::IOleInPlaceObjectWindowlessImpl::GetDropTarget", "ATLCTL/ATL::IOleInPlaceObjectWindowlessImpl::GetWindow", "ATLCTL/ATL::IOleInPlaceObjectWindowlessImpl::InPlaceDeactivate", "ATLCTL/ATL::IOleInPlaceObjectWindowlessImpl::OnWindowMessage", "ATLCTL/ATL::IOleInPlaceObjectWindowlessImpl::ReactivateAndUndo", "ATLCTL/ATL::IOleInPlaceObjectWindowlessImpl::SetObjectRects", "ATLCTL/ATL::IOleInPlaceObjectWindowlessImpl::UIDeactivate"] diff --git a/docs/atl/reference/ioleobjectimpl-class.md b/docs/atl/reference/ioleobjectimpl-class.md index f8c25ab5c3..888f9c0db9 100644 --- a/docs/atl/reference/ioleobjectimpl-class.md +++ b/docs/atl/reference/ioleobjectimpl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IOleObjectImpl Class" title: "IOleObjectImpl Class" ms.date: "11/04/2016" f1_keywords: ["IOleObjectImpl", "ATLCTL/ATL::IOleObjectImpl", "ATLCTL/ATL::IOleObjectImpl::Advise", "ATLCTL/ATL::IOleObjectImpl::Close", "ATLCTL/ATL::IOleObjectImpl::DoVerb", "ATLCTL/ATL::IOleObjectImpl::DoVerbDiscardUndo", "ATLCTL/ATL::IOleObjectImpl::DoVerbHide", "ATLCTL/ATL::IOleObjectImpl::DoVerbInPlaceActivate", "ATLCTL/ATL::IOleObjectImpl::DoVerbOpen", "ATLCTL/ATL::IOleObjectImpl::DoVerbPrimary", "ATLCTL/ATL::IOleObjectImpl::DoVerbShow", "ATLCTL/ATL::IOleObjectImpl::DoVerbUIActivate", "ATLCTL/ATL::IOleObjectImpl::EnumAdvise", "ATLCTL/ATL::IOleObjectImpl::EnumVerbs", "ATLCTL/ATL::IOleObjectImpl::GetClientSite", "ATLCTL/ATL::IOleObjectImpl::GetClipboardData", "ATLCTL/ATL::IOleObjectImpl::GetExtent", "ATLCTL/ATL::IOleObjectImpl::GetMiscStatus", "ATLCTL/ATL::IOleObjectImpl::GetMoniker", "ATLCTL/ATL::IOleObjectImpl::GetUserClassID", "ATLCTL/ATL::IOleObjectImpl::GetUserType", "ATLCTL/ATL::IOleObjectImpl::InitFromData", "ATLCTL/ATL::IOleObjectImpl::IsUpToDate", "ATLCTL/ATL::IOleObjectImpl::OnPostVerbDiscardUndo", "ATLCTL/ATL::IOleObjectImpl::OnPostVerbHide", "ATLCTL/ATL::IOleObjectImpl::OnPostVerbInPlaceActivate", "ATLCTL/ATL::IOleObjectImpl::OnPostVerbOpen", "ATLCTL/ATL::IOleObjectImpl::OnPostVerbShow", "ATLCTL/ATL::IOleObjectImpl::OnPostVerbUIActivate", "ATLCTL/ATL::IOleObjectImpl::OnPreVerbDiscardUndo", "ATLCTL/ATL::IOleObjectImpl::OnPreVerbHide", "ATLCTL/ATL::IOleObjectImpl::OnPreVerbInPlaceActivate", "ATLCTL/ATL::IOleObjectImpl::OnPreVerbOpen", "ATLCTL/ATL::IOleObjectImpl::OnPreVerbShow", "ATLCTL/ATL::IOleObjectImpl::OnPreVerbUIActivate", "ATLCTL/ATL::IOleObjectImpl::SetClientSite", "ATLCTL/ATL::IOleObjectImpl::SetColorScheme", "ATLCTL/ATL::IOleObjectImpl::SetExtent", "ATLCTL/ATL::IOleObjectImpl::SetHostNames", "ATLCTL/ATL::IOleObjectImpl::SetMoniker", "ATLCTL/ATL::IOleObjectImpl::Unadvise", "ATLCTL/ATL::IOleObjectImpl::Update"] diff --git a/docs/atl/reference/iperpropertybrowsingimpl-class.md b/docs/atl/reference/iperpropertybrowsingimpl-class.md index d2a0ca55e2..c5f0e2678e 100644 --- a/docs/atl/reference/iperpropertybrowsingimpl-class.md +++ b/docs/atl/reference/iperpropertybrowsingimpl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IPerPropertyBrowsingImpl Class" title: "IPerPropertyBrowsingImpl Class" ms.date: "11/04/2016" f1_keywords: ["IPerPropertyBrowsingImpl", "ATLCTL/ATL::IPerPropertyBrowsingImpl", "ATLCTL/ATL::IPerPropertyBrowsingImpl::GetDisplayString", "ATLCTL/ATL::IPerPropertyBrowsingImpl::GetPredefinedStrings", "ATLCTL/ATL::IPerPropertyBrowsingImpl::GetPredefinedValue", "ATLCTL/ATL::IPerPropertyBrowsingImpl::MapPropertyToPage"] @@ -15,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/ipersistpropertybagimpl-class.md b/docs/atl/reference/ipersistpropertybagimpl-class.md index 38f496cc68..b9029c339d 100644 --- a/docs/atl/reference/ipersistpropertybagimpl-class.md +++ b/docs/atl/reference/ipersistpropertybagimpl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IPersistPropertyBagImpl Class" title: "IPersistPropertyBagImpl Class" ms.date: "11/04/2016" f1_keywords: ["IPersistPropertyBagImpl", "ATLCOM/ATL::IPersistPropertyBagImpl", "ATLCOM/ATL::IPersistPropertyBagImpl::GetClassID", "ATLCOM/ATL::IPersistPropertyBagImpl::InitNew", "ATLCOM/ATL::IPersistPropertyBagImpl::Load", "ATLCOM/ATL::IPersistPropertyBagImpl::Save"] diff --git a/docs/atl/reference/ipersiststorageimpl-class.md b/docs/atl/reference/ipersiststorageimpl-class.md index 33b8a69e34..a5396bee53 100644 --- a/docs/atl/reference/ipersiststorageimpl-class.md +++ b/docs/atl/reference/ipersiststorageimpl-class.md @@ -1,9 +1,9 @@ --- 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 @@ -21,7 +21,7 @@ class ATL_NO_VTABLE IPersistStorageImpl : public IPersistStorage #### Parameters -*T*
+*T*\ Your class, derived from `IPersistStorageImpl`. ## Members @@ -96,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 @@ -110,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 @@ -124,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 @@ -138,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 @@ -154,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/ipersiststreaminitimpl-class.md b/docs/atl/reference/ipersiststreaminitimpl-class.md index 2dc0fb2983..3eab5ba63c 100644 --- a/docs/atl/reference/ipersiststreaminitimpl-class.md +++ b/docs/atl/reference/ipersiststreaminitimpl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IPersistStreamInitImpl Class" title: "IPersistStreamInitImpl Class" ms.date: "11/04/2016" f1_keywords: ["IPersistStreamInitImpl", "ATLCOM/ATL::IPersistStreamInitImpl", "ATLCOM/ATL::IPersistStreamInitImpl::GetClassID", "ATLCOM/ATL::IPersistStreamInitImpl::GetSizeMax", "ATLCOM/ATL::IPersistStreamInitImpl::InitNew", "ATLCOM/ATL::IPersistStreamInitImpl::IsDirty", "ATLCOM/ATL::IPersistStreamInitImpl::Load", "ATLCOM/ATL::IPersistStreamInitImpl::Save"] diff --git a/docs/atl/reference/ipointerinactiveimpl-class.md b/docs/atl/reference/ipointerinactiveimpl-class.md index e3e0e0d70a..7118949124 100644 --- a/docs/atl/reference/ipointerinactiveimpl-class.md +++ b/docs/atl/reference/ipointerinactiveimpl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IPointerInactiveImpl Class" title: "IPointerInactiveImpl Class" ms.date: "11/04/2016" f1_keywords: ["IPointerInactiveImpl", "ATLCTL/ATL::IPointerInactiveImpl", "ATLCTL/ATL::IPointerInactiveImpl::GetActivationPolicy", "ATLCTL/ATL::IPointerInactiveImpl::OnInactiveMouseMove", "ATLCTL/ATL::IPointerInactiveImpl::OnInactiveSetCursor"] diff --git a/docs/atl/reference/ipropertynotifysinkcp-class.md b/docs/atl/reference/ipropertynotifysinkcp-class.md index fca5d29f3c..b02d41d33b 100644 --- a/docs/atl/reference/ipropertynotifysinkcp-class.md +++ b/docs/atl/reference/ipropertynotifysinkcp-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IPropertyNotifySinkCP Class" title: "IPropertyNotifySinkCP Class" ms.date: "11/04/2016" f1_keywords: ["IPropertyNotifySinkCP", "atlctl/ATL::IPropertyNotifySinkCP"] diff --git a/docs/atl/reference/ipropertypage2impl-class.md b/docs/atl/reference/ipropertypage2impl-class.md index c2d124dea4..f39eac4e87 100644 --- a/docs/atl/reference/ipropertypage2impl-class.md +++ b/docs/atl/reference/ipropertypage2impl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IPropertyPage2Impl Class" title: "IPropertyPage2Impl Class" ms.date: "11/04/2016" f1_keywords: ["IPropertyPage2Impl", "ATLCTL/ATL::IPropertyPage2Impl", "ATLCTL/ATL::IPropertyPage2Impl::EditProperty"] diff --git a/docs/atl/reference/ipropertypageimpl-class.md b/docs/atl/reference/ipropertypageimpl-class.md index 2d14ddcbf4..8b217ed0d0 100644 --- a/docs/atl/reference/ipropertypageimpl-class.md +++ b/docs/atl/reference/ipropertypageimpl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IPropertyPageImpl Class" title: "IPropertyPageImpl Class" ms.date: "11/04/2016" f1_keywords: ["IPropertyPageImpl", "ATLCTL/ATL::IPropertyPageImpl", "ATLCTL/ATL::IPropertyPageImpl::IPropertyPageImpl", "ATLCTL/ATL::IPropertyPageImpl::Activate", "ATLCTL/ATL::IPropertyPageImpl::Apply", "ATLCTL/ATL::IPropertyPageImpl::Deactivate", "ATLCTL/ATL::IPropertyPageImpl::GetPageInfo", "ATLCTL/ATL::IPropertyPageImpl::Help", "ATLCTL/ATL::IPropertyPageImpl::IsPageDirty", "ATLCTL/ATL::IPropertyPageImpl::Move", "ATLCTL/ATL::IPropertyPageImpl::SetDirty", "ATLCTL/ATL::IPropertyPageImpl::SetObjects", "ATLCTL/ATL::IPropertyPageImpl::SetPageSite", "ATLCTL/ATL::IPropertyPageImpl::Show", "ATLCTL/ATL::IPropertyPageImpl::TranslateAccelerator", "ATLCTL/ATL::IPropertyPageImpl::m_bDirty", "ATLCTL/ATL::IPropertyPageImpl::m_dwDocString", "ATLCTL/ATL::IPropertyPageImpl::m_dwHelpContext", "ATLCTL/ATL::IPropertyPageImpl::m_dwHelpFile", "ATLCTL/ATL::IPropertyPageImpl::m_dwTitle", "ATLCTL/ATL::IPropertyPageImpl::m_nObjects", "ATLCTL/ATL::IPropertyPageImpl::m_pPageSite", "ATLCTL/ATL::IPropertyPageImpl::m_ppUnk", "ATLCTL/ATL::IPropertyPageImpl::m_size"] diff --git a/docs/atl/reference/iprovideclassinfo2impl-class.md b/docs/atl/reference/iprovideclassinfo2impl-class.md index 7122229b23..c700c6a280 100644 --- a/docs/atl/reference/iprovideclassinfo2impl-class.md +++ b/docs/atl/reference/iprovideclassinfo2impl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IProvideClassInfo2Impl Class" title: "IProvideClassInfo2Impl Class" ms.date: "11/04/2016" f1_keywords: ["IProvideClassInfo2Impl", "ATLCOM/ATL::IProvideClassInfo2Impl", "ATLCOM/ATL::IProvideClassInfo2Impl::IProvideClassInfo2Impl", "ATLCOM/ATL::IProvideClassInfo2Impl::GetClassInfo", "ATLCOM/ATL::IProvideClassInfo2Impl::GetGUID", "ATLCOM/ATL::IProvideClassInfo2Impl::_tih"] diff --git a/docs/atl/reference/iquickactivateimpl-class.md b/docs/atl/reference/iquickactivateimpl-class.md index 115c36eff0..55d408fead 100644 --- a/docs/atl/reference/iquickactivateimpl-class.md +++ b/docs/atl/reference/iquickactivateimpl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IQuickActivateImpl Class" title: "IQuickActivateImpl Class" ms.date: "11/04/2016" f1_keywords: ["IQuickActivateImpl", "ATLCTL/ATL::IQuickActivateImpl", "ATLCTL/ATL::IQuickActivateImpl::GetContentExtent", "ATLCTL/ATL::IQuickActivateImpl::QuickActivate", "ATLCTL/ATL::IQuickActivateImpl::SetContentExtent"] diff --git a/docs/atl/reference/iregistrar-class.md b/docs/atl/reference/iregistrar-class.md index 83f3b4b91f..9c3ca2a980 100644 --- a/docs/atl/reference/iregistrar-class.md +++ b/docs/atl/reference/iregistrar-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IRegistrar Interface" title: "IRegistrar Interface" ms.date: "02/01/2017" f1_keywords: ["IRegistrar", "ATLIFASE/ATL::IRegistrar", "ATLIFASE/ATL::IRegistrar::ResourceRegisterSz", "ATLIFASE/ATL::IRegistrar::ResourceUnregisterSz", "ATLIFASE/ATL::IRegistrar::FileRegister", "ATLIFASE/ATL::IRegistrar::FileUnregister", "ATLIFASE/ATL::IRegistrar::StringRegister", "ATLIFASE/ATL::IRegistrar::StringUnregister", "ATLIFASE/ATL::IRegistrar::ResourceRegister", "ATLIFASE/ATL::IRegistrar::ResourceUnregister"] diff --git a/docs/atl/reference/irunnableobjectimpl-class.md b/docs/atl/reference/irunnableobjectimpl-class.md index ca64379666..77b26a5072 100644 --- a/docs/atl/reference/irunnableobjectimpl-class.md +++ b/docs/atl/reference/irunnableobjectimpl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IRunnableObjectImpl Class" title: "IRunnableObjectImpl Class" ms.date: "11/04/2016" f1_keywords: ["IRunnableObjectImpl", "ATLCTL/ATL::IRunnableObjectImpl", "ATLCTL/ATL::IRunnableObjectImpl::GetRunningClass", "ATLCTL/ATL::IRunnableObjectImpl::IsRunning", "ATLCTL/ATL::IRunnableObjectImpl::LockRunning", "ATLCTL/ATL::IRunnableObjectImpl::Run", "ATLCTL/ATL::IRunnableObjectImpl::SetContainedObject"] diff --git a/docs/atl/reference/iserviceproviderimpl-class.md b/docs/atl/reference/iserviceproviderimpl-class.md index 15de7e9570..6cd8822fdd 100644 --- a/docs/atl/reference/iserviceproviderimpl-class.md +++ b/docs/atl/reference/iserviceproviderimpl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IServiceProviderImpl Class" title: "IServiceProviderImpl Class" ms.date: "11/04/2016" f1_keywords: ["IServiceProviderImpl", "ATLCOM/ATL::IServiceProviderImpl", "ATLCOM/ATL::IServiceProviderImpl::QueryService"] diff --git a/docs/atl/reference/ispecifypropertypagesimpl-class.md b/docs/atl/reference/ispecifypropertypagesimpl-class.md index fbfe5e168b..ae7b448193 100644 --- a/docs/atl/reference/ispecifypropertypagesimpl-class.md +++ b/docs/atl/reference/ispecifypropertypagesimpl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ISpecifyPropertyPagesImpl Class" title: "ISpecifyPropertyPagesImpl Class" ms.date: "11/04/2016" f1_keywords: ["ISpecifyPropertyPagesImpl", "ATLCOM/ATL::ISpecifyPropertyPagesImpl", "ATLCOM/ATL::ISpecifyPropertyPagesImpl::GetPages"] diff --git a/docs/atl/reference/isupporterrorinfoimpl-class.md b/docs/atl/reference/isupporterrorinfoimpl-class.md index c3be5df313..b9146cc6cf 100644 --- a/docs/atl/reference/isupporterrorinfoimpl-class.md +++ b/docs/atl/reference/isupporterrorinfoimpl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ISupportErrorInfoImpl Class" title: "ISupportErrorInfoImpl Class" ms.date: "06/13/2019" f1_keywords: ["ISupportErrorInfoImpl", "ATLCOM/ATL::ISupportErrorInfoImpl", "ATLCOM/ATL::ISupportErrorInfoImpl::InterfaceSupportsErrorInfo"] diff --git a/docs/atl/reference/ithreadpoolconfig-interface.md b/docs/atl/reference/ithreadpoolconfig-interface.md index 4a7fbb4fed..3a3411e136 100644 --- a/docs/atl/reference/ithreadpoolconfig-interface.md +++ b/docs/atl/reference/ithreadpoolconfig-interface.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IThreadPoolConfig Interface" title: "IThreadPoolConfig Interface" ms.date: "11/04/2016" f1_keywords: ["IThreadPoolConfig", "ATLUTIL/ATL::IThreadPoolConfig", "ATLUTIL/ATL::GetSize", "ATLUTIL/ATL::GetTimeout", "ATLUTIL/ATL::SetSize", "ATLUTIL/ATL::SetTimeout"] @@ -23,7 +24,7 @@ __interface ### Methods -||| +|Name|Description| |-|-| |[GetSize](#getsize)|Call this method to get the number of threads in the pool.| |[GetTimeout](#gettimeout)|Call this method to get the maximum time in milliseconds that the thread pool will wait for a thread to shut down.| diff --git a/docs/atl/reference/iviewobjecteximpl-class.md b/docs/atl/reference/iviewobjecteximpl-class.md index 03c0489e4f..ad03e3ac10 100644 --- a/docs/atl/reference/iviewobjecteximpl-class.md +++ b/docs/atl/reference/iviewobjecteximpl-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IViewObjectExImpl Class" title: "IViewObjectExImpl Class" ms.date: "11/04/2016" f1_keywords: ["IViewObjectExImpl", "ATLCTL/ATL::IViewObjectExImpl", "ATLCTL/ATL::IViewObjectExImpl::Draw", "ATLCTL/ATL::IViewObjectExImpl::Freeze", "ATLCTL/ATL::IViewObjectExImpl::GetAdvise", "ATLCTL/ATL::IViewObjectExImpl::GetColorSet", "ATLCTL/ATL::IViewObjectExImpl::GetExtent", "ATLCTL/ATL::IViewObjectExImpl::GetNaturalExtent", "ATLCTL/ATL::IViewObjectExImpl::GetRect", "ATLCTL/ATL::IViewObjectExImpl::GetViewStatus", "ATLCTL/ATL::IViewObjectExImpl::QueryHitPoint", "ATLCTL/ATL::IViewObjectExImpl::QueryHitRect", "ATLCTL/ATL::IViewObjectExImpl::SetAdvise", "ATLCTL/ATL::IViewObjectExImpl::Unfreeze"] diff --git a/docs/atl/reference/iworkerthreadclient-interface.md b/docs/atl/reference/iworkerthreadclient-interface.md index 0f62e3e588..c962eb0cdf 100644 --- a/docs/atl/reference/iworkerthreadclient-interface.md +++ b/docs/atl/reference/iworkerthreadclient-interface.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IWorkerThreadClient Interface" title: "IWorkerThreadClient Interface" ms.date: "11/04/2016" f1_keywords: ["IWorkerThreadClient", "ATLUTIL/ATL::IWorkerThreadClient", "ATLUTIL/ATL::CloseHandle", "ATLUTIL/ATL::Execute"] @@ -22,7 +23,7 @@ __interface IWorkerThreadClient ### Methods -||| +|Name|Description| |-|-| |[CloseHandle](#closehandle)|Implement this method to close the handle associated with this object.| |[Execute](#execute)|Implement this method to execute code when the handle associated with this object becomes signaled.| diff --git a/docs/atl/reference/making-an-atl-object-noncreatable.md b/docs/atl/reference/making-an-atl-object-noncreatable.md index 9a9ed6e890..6a14432332 100644 --- a/docs/atl/reference/making-an-atl-object-noncreatable.md +++ b/docs/atl/reference/making-an-atl-object-noncreatable.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Making an ATL Object Noncreatable" title: "Making an ATL Object Noncreatable" ms.date: "11/04/2016" f1_keywords: ["vc.appwiz.ATL.objects"] @@ -13,7 +14,7 @@ You can change the attributes of an ATL-based COM object so that a client cannot 1. Remove the [OBJECT_ENTRY_AUTO](object-map-macros.md#object_entry_auto) for the object. If you want the object to be noncreatable but the control to be registered, replace OBJECT_ENTRY_AUTO with [OBJECT_ENTRY_NON_CREATEABLE_EX_AUTO](object-map-macros.md#object_entry_non_createable_ex_auto). -1. Add the [noncreatable](../../windows/noncreatable.md) attribute to the coclass in the .idl file. For example: +1. Add the [noncreatable](../../windows/attributes/noncreatable.md) attribute to the coclass in the .idl file. For example: ``` [uuid(A1992E3D-3CF0-11D0-826F-00A0C90F2851), diff --git a/docs/atl/reference/marshaling-global-functions.md b/docs/atl/reference/marshaling-global-functions.md index a17e79d3c5..74ec8bf714 100644 --- a/docs/atl/reference/marshaling-global-functions.md +++ b/docs/atl/reference/marshaling-global-functions.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Marshaling Global Functions" title: "Marshaling Global Functions" ms.date: "11/04/2016" f1_keywords: ["atlbase/ATL::AtlFreeMarshalStream", "atlbase/ATL::AtlMarshalPtrInProc", "atlbase/ATL::AtlUnmarshalPtr"] @@ -11,7 +12,7 @@ These functions provide support for marshaling and converting marshaling data in > [!IMPORTANT] > The functions listed in the following table cannot be used in applications that execute in the Windows Runtime. -||| +|Name|Description| |-|-| |[AtlFreeMarshalStream](#atlfreemarshalstream)|Releases the marshal data and the `IStream` pointer.| |[AtlMarshalPtrInProc](#atlmarshalptrinproc)|Creates a new stream object and marshals the specified interface pointer.| diff --git a/docs/atl/reference/message-map-macros-atl.md b/docs/atl/reference/message-map-macros-atl.md index e4f7107677..99775caee5 100644 --- a/docs/atl/reference/message-map-macros-atl.md +++ b/docs/atl/reference/message-map-macros-atl.md @@ -1,14 +1,15 @@ --- +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) These macros define message maps and entries. -||| +|Name|Description| |-|-| |[ALT_MSG_MAP](#alt_msg_map)|Marks the beginning of an alternate message map.| |[BEGIN_MSG_MAP](#begin_msg_map)|Marks the beginning of the default message map.| diff --git a/docs/atl/reference/mfc-support-in-atl-projects.md b/docs/atl/reference/mfc-support-in-atl-projects.md index 0decb093af..c02e7ad566 100644 --- a/docs/atl/reference/mfc-support-in-atl-projects.md +++ b/docs/atl/reference/mfc-support-in-atl-projects.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: MFC Support in ATL Projects" title: "MFC Support in ATL Projects" ms.date: "11/04/2016" f1_keywords: ["vc.atl.addmfc"] diff --git a/docs/atl/reference/object-map-macros.md b/docs/atl/reference/object-map-macros.md index 2b38419a08..e0d53e8236 100644 --- a/docs/atl/reference/object-map-macros.md +++ b/docs/atl/reference/object-map-macros.md @@ -1,14 +1,15 @@ --- +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 These macros define object maps and entries. -||| +|Name|Description| |-|-| |[DECLARE_OBJECT_DESCRIPTION](#declare_object_description)|Allows you to specify a class object's text description, which will be entered into the object map.| |[OBJECT_ENTRY_AUTO](#object_entry_auto)|Enters an ATL object into the object map, updates the registry, and creates an instance of the object.| diff --git a/docs/atl/reference/object-status-macros.md b/docs/atl/reference/object-status-macros.md index 747fc8c5e7..06a9bdb39f 100644 --- a/docs/atl/reference/object-status-macros.md +++ b/docs/atl/reference/object-status-macros.md @@ -1,14 +1,15 @@ --- +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 This macro sets flags belonging to ActiveX controls. -||| +|Name|Description| |-|-| |[DECLARE_OLEMISC_STATUS](#declare_olemisc_status)|Used in ATL ActiveX controls to set the OLEMISC flags.| diff --git a/docs/atl/reference/options-atl-active-server-page-component-wizard.md b/docs/atl/reference/options-atl-active-server-page-component-wizard.md index 8c07553336..ee4d74799f 100644 --- a/docs/atl/reference/options-atl-active-server-page-component-wizard.md +++ b/docs/atl/reference/options-atl-active-server-page-component-wizard.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Options, ATL Active Server Page Component Wizard" title: "Options, ATL Active Server Page Component Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.codewiz.class.atl.asp.options"] diff --git a/docs/atl/reference/options-atl-control-wizard.md b/docs/atl/reference/options-atl-control-wizard.md index 0bd2bf052c..b6ec7ec9d0 100644 --- a/docs/atl/reference/options-atl-control-wizard.md +++ b/docs/atl/reference/options-atl-control-wizard.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Options, ATL Control Wizard" title: "Options, ATL Control Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.codewiz.class.atl.control.options"] @@ -65,7 +66,7 @@ The type of interface this control exposes to the container. - **Custom**: Creates an interface that exposes methods directly through a VTBL. - If you select **Custom**, then you can specify that the control is **Automation compatible**. If you select **Automation compatible**, then the wizard adds the [oleautomation](../../windows/oleautomation.md) attribute to the interface in the IDL, and the interface can be marshaled by the universal marshaler in oleaut32.dll. See [Marshaling Details](/windows/win32/com/marshaling-details) in the Windows SDK for more information. + If you select **Custom**, then you can specify that the control is **Automation compatible**. If you select **Automation compatible**, then the wizard adds the [oleautomation](../../windows/attributes/oleautomation.md) attribute to the interface in the IDL, and the interface can be marshaled by the universal marshaler in oleaut32.dll. See [Marshaling Details](/windows/win32/com/marshaling-details) in the Windows SDK for more information. Additionally, if you select **Automation compatible**, then all parameters for all methods in the control must be VARIANT compatible. diff --git a/docs/atl/reference/options-atl-property-page-wizard.md b/docs/atl/reference/options-atl-property-page-wizard.md index b7e6b78888..a49caf9d07 100644 --- a/docs/atl/reference/options-atl-property-page-wizard.md +++ b/docs/atl/reference/options-atl-property-page-wizard.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Options, ATL Property Page Wizard" title: "Options, ATL Property Page Wizard" ms.date: "05/09/2019" f1_keywords: ["vc.codewiz.class.atl.ppg.options"] @@ -7,13 +8,13 @@ ms.assetid: a7107779-b2ea-4f99-b84b-7f3e0c504bc8 --- # Options, ATL Property Page Wizard -::: moniker range="vs-2019" +::: moniker range=">=msvc-160" The ATL Property Page wizard is not available in Visual Studio 2019 and later. ::: moniker-end -::: moniker range="<=vs-2017" +::: moniker range="<=msvc-150" Use this page of the wizard to define the threading model and aggregation level of property page you are creating. diff --git a/docs/atl/reference/options-atl-simple-object-wizard.md b/docs/atl/reference/options-atl-simple-object-wizard.md index 3222728a0a..a15ab0eccc 100644 --- a/docs/atl/reference/options-atl-simple-object-wizard.md +++ b/docs/atl/reference/options-atl-simple-object-wizard.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Options, ATL Simple Object Wizard" title: "Options, ATL Simple Object Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.codewiz.class.atl.simple.options"] diff --git a/docs/atl/reference/pixel-himetric-conversion-global-functions.md b/docs/atl/reference/pixel-himetric-conversion-global-functions.md index ceb40d325c..3e1c7e9264 100644 --- a/docs/atl/reference/pixel-himetric-conversion-global-functions.md +++ b/docs/atl/reference/pixel-himetric-conversion-global-functions.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Pixel/HIMETRIC Conversion Global Functions" title: "Pixel-HIMETRIC Conversion Global Functions" ms.date: "11/04/2016" f1_keywords: ["atlwin/ATL::AtlHiMetricToPixel", "atlwin/ATL::AtlPixelToHiMetric"] @@ -11,7 +12,7 @@ These functions provide support for converting to and from pixel and HIMETRIC un > [!IMPORTANT] > The functions listed in the following table cannot be used in applications that execute in the Windows Runtime. -||| +|Name|Description| |-|-| |[AtlHiMetricToPixel](#atlhimetrictopixel)|Converts HIMETRIC units (each unit is 0.01 millimeter) to pixels.| |[AtlPixelToHiMetric](#atlpixeltohimetric)|Converts pixels to HIMETRIC units (each unit is 0.01 millimeter).| diff --git a/docs/atl/reference/property-map-macros.md b/docs/atl/reference/property-map-macros.md index 14c4ca020a..c0e785543d 100644 --- a/docs/atl/reference/property-map-macros.md +++ b/docs/atl/reference/property-map-macros.md @@ -1,7 +1,8 @@ --- +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 --- @@ -9,7 +10,7 @@ ms.assetid: 128bc742-2b98-4b97-a243-684dbb83db77 These macros define property maps and entries. -||| +|Name|Description| |-|-| |[BEGIN_PROP_MAP](#begin_prop_map)|Marks the beginning of the ATL property map.| |[PROP_DATA_ENTRY](#prop_data_entry)|Indicates the extent, or dimensions, of an ActiveX control.| @@ -77,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-and-typelib-global-functions.md b/docs/atl/reference/registry-and-typelib-global-functions.md index 027528f43a..c97812f48d 100644 --- a/docs/atl/reference/registry-and-typelib-global-functions.md +++ b/docs/atl/reference/registry-and-typelib-global-functions.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Registry and TypeLib Global Functions" title: "Registry and TypeLib Global Functions" ms.date: "03/27/2019" f1_keywords: ["atlbase/ATL::AtlGetPerUserRegistration", "afxpriv/ATL::AfxRegCreateKey", "afxpriv/ATL::AfxRegDeleteKey", "atlbase/ATL::AtlRegisterTypeLib", "afxpriv/ATL::AfxRegOpenKey", "afxpriv/ATL::AfxRegOpenKeyEx", "afxdisp/ATL::AfxUnregisterPreviewHandler", "atlbase/ATL::AtlSetPerUserRegistration", "atlbase/ATL::AtlUnRegisterTypeLib", "atlbase/ATL::AtlLoadTypeLib", "atlbase/ATL::AtlUpdateRegistryFromResourceD", "atlbase/ATL::RegistryDataExchange"] @@ -12,7 +13,7 @@ These functions provide support for loading and registering a type library. > [!IMPORTANT] > The functions listed in the following tables cannot be used in applications that execute in the Windows Runtime. -||| +|Name|Description| |-|-| |[AfxRegCreateKey](#afxregcreatekey)|Creates the specified registry key.| |[AfxRegDeleteKey](#afxregdeletekey)|Deletes the specified registry key.| @@ -28,7 +29,7 @@ These functions provide support for loading and registering a type library. These functions control which node in the registry the program uses to store information. -||| +|Name|Description| |-|-| |[AtlGetPerUserRegistration](#atlgetperuserregistration)|Retrieves whether the application redirects registry access to the **HKEY_CURRENT_USER** ( **HKCU**) node.| |[AtlSetPerUserRegistration](#atlsetperuserregistration)|Sets whether the application redirects registry access to the **HKEY_CURRENT_USER** ( **HKCU**) node.| diff --git a/docs/atl/reference/registry-data-exchange-macros.md b/docs/atl/reference/registry-data-exchange-macros.md index 0feb314576..98857707a3 100644 --- a/docs/atl/reference/registry-data-exchange-macros.md +++ b/docs/atl/reference/registry-data-exchange-macros.md @@ -1,7 +1,8 @@ --- +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 --- @@ -9,7 +10,7 @@ ms.assetid: c1bc5e79-2307-43d2-9d10-3a62ffadf473 These macros perform Registry Data Exchange operations. -||| +|Name|Description| |-|-| |[BEGIN_RDX_MAP](#begin_rdx_map)|Marks the beginning of the Registry Data Exchange map.| |[END_RDX_MAP](#end_rdx_map)|Marks the end of the Registry Data Exchange map.| diff --git a/docs/atl/reference/registry-macros.md b/docs/atl/reference/registry-macros.md index bd7e75e03f..f18617f0fe 100644 --- a/docs/atl/reference/registry-macros.md +++ b/docs/atl/reference/registry-macros.md @@ -1,7 +1,8 @@ --- +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 --- @@ -9,7 +10,7 @@ ms.assetid: 3ee041da-c63b-42a4-89cf-2a4b2a6f81ae These macros define useful type library and registry facilities. -||| +|Name|Description| |-|-| |[_ATL_STATIC_REGISTRY](#_atl_static_registry)|Indicates that you want the registration code for your object to be in the object to avoid a dependency on ATL.DLL.| |[DECLARE_LIBID](#declare_libid)|Provides a way for ATL to obtain the *libid* of the type library.| diff --git a/docs/atl/reference/security-global-functions.md b/docs/atl/reference/security-global-functions.md index 224a2ea150..e42bcb30f7 100644 --- a/docs/atl/reference/security-global-functions.md +++ b/docs/atl/reference/security-global-functions.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Security Global Functions" title: "Security Global Functions" ms.date: "11/04/2016" f1_keywords: ["atlsecurity/ATL::AtlGetDacl", "atlsecurity/ATL::AtlSetDacl", "atlsecurity/ATL::AtlGetGroupSid", "atlsecurity/ATL::AtlSetGroupSid", "atlsecurity/ATL::AtlGetOwnerSid", "atlsecurity/ATL::AtlSetOwnerSid", "atlsecurity/ATL::AtlGetSacl", "atlsecurity/ATL::AtlSetSacl", "atlsecurity/ATL::AtlGetSecurityDescriptor"] @@ -12,7 +13,7 @@ These functions provide support for modifying SID and ACL objects. > [!IMPORTANT] > The functions listed in the following table cannot be used in applications that execute in the Windows Runtime. -||| +|Name|Description| |-|-| |[AtlGetDacl](#atlgetdacl)|Call this function to retrieve the discretionary access-control list (DACL) information of a specified object.| |[AtlSetDacl](#atlsetdacl)|Call this function to set the discretionary access-control list (DACL) information of a specified object.| diff --git a/docs/atl/reference/security-identifier-global-functions.md b/docs/atl/reference/security-identifier-global-functions.md index d7b26e8c56..d429e27b2a 100644 --- a/docs/atl/reference/security-identifier-global-functions.md +++ b/docs/atl/reference/security-identifier-global-functions.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Security Identifier Global Functions" title: "Security Identifier Global Functions" ms.date: "11/04/2016" f1_keywords: ["atlsecurity/ATL::Sids::AccountOps", "atlsecurity/ATL::Sids::Admins", "atlsecurity/ATL::Sids::AnonymousLogon", "atlsecurity/ATL::Sids::AuthenticatedUser", "atlsecurity/ATL::Sids::BackupOps", "atlsecurity/ATL::Sids::Batch", "atlsecurity/ATL::Sids::CreatorGroup", "atlsecurity/ATL::Sids::CreatorGroupServer", "atlsecurity/ATL::Sids::CreatorOwner", "atlsecurity/ATL::Sids::CreatorOwnerServer", "atlsecurity/ATL::Sids::Dialup", "atlsecurity/ATL::Sids::Guests", "atlsecurity/ATL::Sids::Interactive", "atlsecurity/ATL::Sids::Local", "atlsecurity/ATL::Sids::Network", "atlsecurity/ATL::Sids::NetworkService", "atlsecurity/ATL::Sids::Null", "atlsecurity/ATL::Sids::PowerUsers", "atlsecurity/ATL::Sids::PrintOps", "atlsecurity/ATL::Sids::Proxy", "atlsecurity/ATL::Sids::RasServers", "atlsecurity/ATL::Sids::Replicator", "atlsecurity/ATL::Sids::RestrictedCode", "atlsecurity/ATL::Sids::Self", "atlsecurity/ATL::Sids::ServerLogon", "atlsecurity/ATL::Sids::Service", "atlsecurity/ATL::Sids::System", "atlsecurity/ATL::Sids::SystemOps", "atlsecurity/ATL::Sids::TerminalServer", "atlsecurity/ATL::Sids::Users", "atlsecurity/ATL::Sids::World"] @@ -12,7 +13,7 @@ These functions return common well-known SID objects. > [!IMPORTANT] > The functions listed in the following table cannot be used in applications that execute in the Windows Runtime. -||| +|Name|Description| |-|-| |[Sids::AccountOps](#accountops)|Returns the DOMAIN_ALIAS_RID_ACCOUNT_OPS SID.| |[Sids::Admins](#admins)|Returns the DOMAIN_ALIAS_RID_ADMINS SID.| diff --git a/docs/atl/reference/server-registration-global-functions.md b/docs/atl/reference/server-registration-global-functions.md index c2c4f4f7cb..4277c7c13a 100644 --- a/docs/atl/reference/server-registration-global-functions.md +++ b/docs/atl/reference/server-registration-global-functions.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Server Registration Global Functions" title: "Server Registration Global Functions" ms.date: "11/04/2016" f1_keywords: ["atlbase/ATL::AtlComModuleRegisterServer", "atlbase/ATL::AtlComModuleUnregisterServer", "atlbase/ATL::AtlComModuleRegisterClassObjects", "atlbase/ATL::AtlComModuleRevokeClassObjects", "atlbase/ATL::AtlComModuleGetClassObject"] @@ -11,7 +12,7 @@ These functions provide support for registering and unregistering server objects > [!IMPORTANT] > The functions listed in the following table cannot be used in applications that execute in the Windows Runtime. -||| +|Name|Description| |-|-| |[AtlComModuleRegisterServer](#atlcommoduleregisterserver)|This function is called to register every object in the object map.| |[AtlComModuleUnregisterServer](#atlcommoduleunregisterserver)|This function is called to unregister every object in the object map.| diff --git a/docs/atl/reference/service-map-macros.md b/docs/atl/reference/service-map-macros.md index ff1a1b275b..b42010306a 100644 --- a/docs/atl/reference/service-map-macros.md +++ b/docs/atl/reference/service-map-macros.md @@ -1,14 +1,15 @@ --- +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 These macros define service maps and entries. -||| +|Name|Description| |-|-| |[BEGIN_SERVICE_MAP](#begin_service_map)|Marks the beginning of an ATL service map.| |[END_SERVICE_MAP](#end_service_map)|Marks the end of an ATL service map.| @@ -114,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| |------------------|-------------| @@ -122,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 da4c402131..380f4cf116 100644 --- a/docs/atl/reference/snap-in-object-macros.md +++ b/docs/atl/reference/snap-in-object-macros.md @@ -1,14 +1,15 @@ --- +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 These macros provide support for snap-in extensions. -||| +|Name|Description| |-|-| |[BEGIN_EXTENSION_SNAPIN_NODEINFO_MAP](#begin_extension_snapin_nodeinfo_map)|Marks the beginning of the snap-in extension data class map for a Snap-In object.| |[BEGIN_SNAPINTOOLBARID_MAP](#begin_snapintoolbarid_map)|Marks the beginning of the toolbar map for a Snap-In object.| diff --git a/docs/atl/reference/specifying-compiler-optimization-for-an-atl-project.md b/docs/atl/reference/specifying-compiler-optimization-for-an-atl-project.md index df89855534..c59923486a 100644 --- a/docs/atl/reference/specifying-compiler-optimization-for-an-atl-project.md +++ b/docs/atl/reference/specifying-compiler-optimization-for-an-atl-project.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Specifying Compiler Optimization for an ATL Project" title: "Specifying Compiler Optimization for an ATL Project" ms.date: "08/19/2019" f1_keywords: ["vc.appwiz.ATL.optimization", "vc.appwiz.ATL.vtable"] diff --git a/docs/atl/reference/stock-properties-atl-control-wizard.md b/docs/atl/reference/stock-properties-atl-control-wizard.md index 1235f787e2..d71b29f1d2 100644 --- a/docs/atl/reference/stock-properties-atl-control-wizard.md +++ b/docs/atl/reference/stock-properties-atl-control-wizard.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Stock Properties, ATL Control Wizard" title: "Stock Properties, ATL Control Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.codewiz.class.atl.control.stockprops"] diff --git a/docs/atl/reference/string-conversion-macros.md b/docs/atl/reference/string-conversion-macros.md index 40eaf4e9fa..9b67e45e5f 100644 --- a/docs/atl/reference/string-conversion-macros.md +++ b/docs/atl/reference/string-conversion-macros.md @@ -1,7 +1,8 @@ --- +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 @@ -49,7 +50,7 @@ The behavior of the `DEVMODE` and `TEXTMETRIC` string conversion macros depends The following table lists the `DEVMODE` and `TEXTMETRIC` string conversion macros. -||| +|`DEVMODE` macro|`TEXTMETRIC` macro| |-|-| |DEVMODEA2W|TEXTMETRICA2W| |DEVMODEOLE2T|TEXTMETRICOLE2T| diff --git a/docs/atl/reference/strings-atl-property-page-wizard.md b/docs/atl/reference/strings-atl-property-page-wizard.md index e07a54bf07..af7682dd9f 100644 --- a/docs/atl/reference/strings-atl-property-page-wizard.md +++ b/docs/atl/reference/strings-atl-property-page-wizard.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Strings, ATL Property Page Wizard" title: "Strings, ATL Property Page Wizard" ms.date: "05/09/2019" f1_keywords: ["vc.codewiz.class.atl.ppg.strings"] @@ -7,13 +8,13 @@ ms.assetid: 00547db6-911f-49eb-92e1-2ba67079d4df --- # Strings, ATL Property Page Wizard -::: moniker range="vs-2019" +::: moniker range=">=msvc-160" The ATL Property Page wizard is not available in Visual Studio 2019 and later. ::: moniker-end -::: moniker range="<=vs-2017" +::: moniker range="<=msvc-150" Provides the text associated with the property page. diff --git a/docs/atl/reference/u-menuorid-class.md b/docs/atl/reference/u-menuorid-class.md index 51872d7499..cd2b60ec3e 100644 --- a/docs/atl/reference/u-menuorid-class.md +++ b/docs/atl/reference/u-menuorid-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: _U_MENUorID Class" title: "_U_MENUorID Class" ms.date: "11/04/2016" f1_keywords: ["ATL._U_MENUorID", "ATL::_U_MENUorID", "_U_MENUorID"] diff --git a/docs/atl/reference/u-rect-class.md b/docs/atl/reference/u-rect-class.md index e0e7d19ae1..515c8add35 100644 --- a/docs/atl/reference/u-rect-class.md +++ b/docs/atl/reference/u-rect-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: _U_RECT Class" title: "_U_RECT Class" ms.date: "11/04/2016" f1_keywords: ["ATL::_U_RECT", "_U_RECT", "ATL._U_RECT"] diff --git a/docs/atl/reference/u-stringorid-class.md b/docs/atl/reference/u-stringorid-class.md index c8d49c7fea..d7148ff89c 100644 --- a/docs/atl/reference/u-stringorid-class.md +++ b/docs/atl/reference/u-stringorid-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: _U_STRINGorID Class" title: "_U_STRINGorID Class" ms.date: "11/04/2016" f1_keywords: ["ATL._U_STRINGorID", "ATL::_U_STRINGorID", "_U_STRINGorID"] diff --git a/docs/atl/reference/win32threadtraits-class.md b/docs/atl/reference/win32threadtraits-class.md index 6fc1b8e7e5..2d4f1fa008 100644 --- a/docs/atl/reference/win32threadtraits-class.md +++ b/docs/atl/reference/win32threadtraits-class.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Win32ThreadTraits Class" title: "Win32ThreadTraits Class" ms.date: "11/04/2016" f1_keywords: ["Win32ThreadTraits", "ATLBASE/ATL::Win32ThreadTraits", "ATLBASE/ATL::Win32ThreadTraits::CreateThread"] diff --git a/docs/atl/reference/window-class-macros.md b/docs/atl/reference/window-class-macros.md index ae41f9c880..4804e4b723 100644 --- a/docs/atl/reference/window-class-macros.md +++ b/docs/atl/reference/window-class-macros.md @@ -1,14 +1,15 @@ --- +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 These macros define window class utilities. -||| +|Name|Description| |-|-| |[DECLARE_WND_CLASS](#declare_wnd_class)|Allows you to specify the name of a new window class.| |[DECLARE_WND_CLASS2](#declare_wnd_class2)|(Visual Studio 2017) Allows you to specify the name of a new window class and the enclosing class whose window procedure the new class will use.| diff --git a/docs/atl/reference/windows-messages-macros.md b/docs/atl/reference/windows-messages-macros.md index fba9a9e238..0675305320 100644 --- a/docs/atl/reference/windows-messages-macros.md +++ b/docs/atl/reference/windows-messages-macros.md @@ -1,14 +1,15 @@ --- +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 This macro forwards window messages. -||| +|Name|Description| |-|-| |[WM_FORWARDMSG](#wm_forwardmsg)|Use to forward a message received by a window to another window for processing.| diff --git a/docs/atl/reference/winmodule-global-functions.md b/docs/atl/reference/winmodule-global-functions.md index 486b2c4956..c0708a6a56 100644 --- a/docs/atl/reference/winmodule-global-functions.md +++ b/docs/atl/reference/winmodule-global-functions.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: WinModule Global Functions" title: "WinModule Global Functions" ms.date: "11/04/2016" f1_keywords: ["atlbase/ATL::AtlWinModuleAddCreateWndData", "atlbase/ATL::AtlWinModuleExtractCreateWndData"] @@ -11,7 +12,7 @@ These functions provide support for `_AtlCreateWndData` structure operations. > [!IMPORTANT] > The functions listed in the following table cannot be used in applications that execute in the Windows Runtime. -||| +|Name|Description| |-|-| |[AtlWinModuleAddCreateWndData](#atlwinmoduleaddcreatewnddata)|This function is used to initialize and add an `_AtlCreateWndData` structure.| |[AtlWinModuleExtractCreateWndData](#atlwinmoduleextractcreatewnddata)|Call this function to extract an existing `_AtlCreateWndData` structure.| diff --git a/docs/atl/reference/worker-archetype.md b/docs/atl/reference/worker-archetype.md index 1816a938bb..e4a36e9702 100644 --- a/docs/atl/reference/worker-archetype.md +++ b/docs/atl/reference/worker-archetype.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Worker Archetype" title: "Worker Archetype" ms.date: "11/04/2016" helpviewer_keywords: ["Worker archetype"] diff --git a/docs/atl/registry-entries.md b/docs/atl/registry-entries.md index 4e3acd7bd7..30fd629939 100644 --- a/docs/atl/registry-entries.md +++ b/docs/atl/registry-entries.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Registry Entries" title: "Registry Entries (ATL)" ms.date: "11/04/2016" helpviewer_keywords: ["registry, ATL services entries", "registry, application IDs"] diff --git a/docs/atl/registry-scripting-examples.md b/docs/atl/registry-scripting-examples.md index 45df174dd8..605b92f0df 100644 --- a/docs/atl/registry-scripting-examples.md +++ b/docs/atl/registry-scripting-examples.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Registry Scripting Examples" title: "Registry Scripting Examples" ms.date: "11/04/2016" helpviewer_keywords: ["scripting, examples", "registrar scripts [ATL]", "scripts, Registrar scripts", "registry, Registrar"] diff --git a/docs/atl/registry-support-classes.md b/docs/atl/registry-support-classes.md index 01cd2b9871..1aafad7ccf 100644 --- a/docs/atl/registry-support-classes.md +++ b/docs/atl/registry-support-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Registry Support Classes" title: "Registry Support Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/running-objects-classes.md b/docs/atl/running-objects-classes.md index b1f477ba07..8d7c92b99f 100644 --- a/docs/atl/running-objects-classes.md +++ b/docs/atl/running-objects-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Running Objects Classes" title: "Running Objects Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/running-the-program-as-a-local-server.md b/docs/atl/running-the-program-as-a-local-server.md index 602d0fec3f..647555b455 100644 --- a/docs/atl/running-the-program-as-a-local-server.md +++ b/docs/atl/running-the-program-as-a-local-server.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Running the Program as a Local Server" title: "Running the Program as a Local Server" ms.date: "11/04/2016" helpviewer_keywords: ["debugging [ATL], running services as local server", "ATL services, running as local servers"] ms.assetid: eb9701e6-e2a8-4666-897f-0c893aec8ac7 +ms.topic: concept-article --- # Running the Program as a Local Server diff --git a/docs/atl/scope-of-atl.md b/docs/atl/scope-of-atl.md index d85c1b650b..bf84207f3b 100644 --- a/docs/atl/scope-of-atl.md +++ b/docs/atl/scope-of-atl.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Scope of ATL" title: "Scope of ATL" ms.date: "11/04/2016" helpviewer_keywords: ["ATL, scope"] diff --git a/docs/atl/security-classes.md b/docs/atl/security-classes.md index 84f3579dbe..c4d3e1acab 100644 --- a/docs/atl/security-classes.md +++ b/docs/atl/security-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Security Classes" title: "Security Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/service-provider-support-classes.md b/docs/atl/service-provider-support-classes.md index 9037a30d31..9cce29b4cd 100644 --- a/docs/atl/service-provider-support-classes.md +++ b/docs/atl/service-provider-support-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Service Provider Support Classes" title: "Service Provider Support Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/setting-up-a-static-link-to-the-registrar-code-cpp-only.md b/docs/atl/setting-up-a-static-link-to-the-registrar-code-cpp-only.md index 35f9eddb4c..e5797ef152 100644 --- a/docs/atl/setting-up-a-static-link-to-the-registrar-code-cpp-only.md +++ b/docs/atl/setting-up-a-static-link-to-the-registrar-code-cpp-only.md @@ -1,21 +1,23 @@ --- -title: "Setting Up a Static Link to the Registrar Code (C++ Only)" -ms.date: "11/04/2016" +title: "Setting up a static link to the Registrar code (C++ only)" +description: "How to statically link C++ code to the ATL Registrar code." +ms.date: 09/03/2020 helpviewer_keywords: ["statically linking to ATL Registrar code", "linking [C++], to ATL Registrar code"] ms.assetid: 835f5885-87a6-48fa-91e6-60988ee65538 +ms.topic: how-to --- -# Setting Up a Static Link to the Registrar Code (C++ Only) +# Setting up a static link to the Registrar code (C++ Only) C++ clients can create a static link to the Registrar's code. Static linking of the Registrar's parser adds approximately 5K to a release build. -The simplest way to set up static linking assumes you have specified [DECLARE_REGISTRY_RESOURCEID](reference/registry-macros.md#declare_registry_resourceid) in your object's declaration. (This is the default specification used by the ATL.) +The simplest way to set up static linking assumes you have specified [`DECLARE_REGISTRY_RESOURCEID`](reference/registry-macros.md#declare_registry_resourceid) in your object's declaration. (It's the default specification used by the ATL.) -## To create a static link using DECLARE_REGISTRY_RESOURCEID +## To create a static link using `DECLARE_REGISTRY_RESOURCEID` -1. Specify [/D](../build/reference/d-preprocessor-definitions.md) **\_ATL\_STATIC\_REGISTRY** instead of **/D \_ATL\_DLL**. +1. Specify **`/D _ATL_STATIC_REGISTRY`** instead of **`/D _ATL_DLL`** on the CL command line. For more information, see [`/D`](../build/reference/d-preprocessor-definitions.md). 1. Recompile. ## See also -[Registry Component (Registrar)](../atl/atl-registry-component-registrar.md) +[Registry component (Registrar)](../atl/atl-registry-component-registrar.md) diff --git a/docs/atl/site-information-classes.md b/docs/atl/site-information-classes.md index fa7840d93f..4ece835b06 100644 --- a/docs/atl/site-information-classes.md +++ b/docs/atl/site-information-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Site Information Classes" title: "Site Information Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/specifying-property-pages.md b/docs/atl/specifying-property-pages.md index 3df3001f5b..0213211d07 100644 --- a/docs/atl/specifying-property-pages.md +++ b/docs/atl/specifying-property-pages.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Specifying Property Pages" title: "Specifying Property Pages (ATL)" ms.date: "11/04/2016" helpviewer_keywords: ["ISpecifyPropertyPages method", "property pages, specifying"] ms.assetid: ee8678cf-c708-49ab-b0ad-fc2db31f1ac3 +ms.topic: how-to --- # Specifying Property Pages diff --git a/docs/atl/specifying-the-threading-model-for-a-project-atl.md b/docs/atl/specifying-the-threading-model-for-a-project-atl.md index bdb9317d5f..f9d9ebeb3a 100644 --- a/docs/atl/specifying-the-threading-model-for-a-project-atl.md +++ b/docs/atl/specifying-the-threading-model-for-a-project-atl.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Specifying the Threading Model for a Project (ATL)" title: "Specifying the Threading Model for a Project (ATL)" ms.date: "11/04/2016" helpviewer_keywords: ["_ATL_FREE_THREADED macro", "_ATL_APARTMENT_THREADED macro", "ATL, multithreading", "threading [ATL], models", "_ATL_SINGLE_THREADED macro"] ms.assetid: 6b571078-521c-4f3e-9f08-482aa235a822 +ms.topic: concept-article --- # Specifying the Threading Model for a Project (ATL) diff --git a/docs/atl/string-and-text-classes.md b/docs/atl/string-and-text-classes.md index af4b89ae1a..3810a64d0d 100644 --- a/docs/atl/string-and-text-classes.md +++ b/docs/atl/string-and-text-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: String and Text Classes" title: "ATL String and Text Classes" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/supporting-idispatch-and-ierrorinfo.md b/docs/atl/supporting-idispatch-and-ierrorinfo.md index cdfa14334c..97c4908435 100644 --- a/docs/atl/supporting-idispatch-and-ierrorinfo.md +++ b/docs/atl/supporting-idispatch-and-ierrorinfo.md @@ -1,14 +1,16 @@ --- +description: "Learn more about: Supporting IDispatch and IErrorInfo" title: "Supporting IDispatch and IErrorInfo" ms.date: "11/04/2016" helpviewer_keywords: ["ISupportErrorInfoImpl method", "IErrorInfo class suppor in ATL", "IDispatchImpl class", "IDispatch class support in ATL"] ms.assetid: 7db2220f-319d-4ce9-9382-d340019f14f7 +ms.topic: concept-article --- # Supporting IDispatch and IErrorInfo 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/supporting-idispeventimpl.md b/docs/atl/supporting-idispeventimpl.md index 9cfd0be136..261ffa445c 100644 --- a/docs/atl/supporting-idispeventimpl.md +++ b/docs/atl/supporting-idispeventimpl.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Supporting IDispEventImpl" title: "Supporting IDispEventImpl" ms.date: "11/04/2016" helpviewer_keywords: ["event sink maps, declaring", "IDispEventImpl class, advising and unadvising", "SINK_ENTRY macro", "type libraries, importing", "ATL, IDispEventImpl support in COM objects", "BEGIN_SINK_MAP macro", "IDispEventImpl class, declaring"] ms.assetid: b957f930-6a5b-4598-8e4d-8027759957e7 +ms.topic: concept-article --- # Supporting IDispEventImpl diff --git a/docs/atl/tear-off-interfaces-classes.md b/docs/atl/tear-off-interfaces-classes.md index e0adec34a6..0f6c3667bd 100644 --- a/docs/atl/tear-off-interfaces-classes.md +++ b/docs/atl/tear-off-interfaces-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Tear-Off Interfaces Classes" title: "Tear-Off Interfaces Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/testing-the-atl-dhtml-control.md b/docs/atl/testing-the-atl-dhtml-control.md index d741733813..1d223e24d1 100644 --- a/docs/atl/testing-the-atl-dhtml-control.md +++ b/docs/atl/testing-the-atl-dhtml-control.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Testing the ATL DHTML Control" title: "Testing the ATL DHTML Control" ms.date: "11/04/2016" helpviewer_keywords: ["HTML controls, testing", "testing controls", "DHTML controls", "DHTML controls, testing"] ms.assetid: 0e4b4358-80ce-4505-8b06-ef4f30b1d1f0 +ms.topic: how-to --- # Testing the ATL DHTML Control diff --git a/docs/atl/testing-the-modified-atl-dhtml-control.md b/docs/atl/testing-the-modified-atl-dhtml-control.md index 9d07ec8af8..fe0809b88b 100644 --- a/docs/atl/testing-the-modified-atl-dhtml-control.md +++ b/docs/atl/testing-the-modified-atl-dhtml-control.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Testing the Modified ATL DHTML Control" title: "Testing the Modified ATL DHTML Control" ms.date: "11/06/2018" helpviewer_keywords: ["HTML controls, testing", "testing controls", "DHTML controls, testing"] ms.assetid: 42316118-9433-410f-9d8a-0efcc1eff824 +ms.topic: how-to --- # Testing the Modified ATL DHTML Control diff --git a/docs/atl/thread-pooling-classes.md b/docs/atl/thread-pooling-classes.md index 6c5e2a0e5c..ff62fdc9f8 100644 --- a/docs/atl/thread-pooling-classes.md +++ b/docs/atl/thread-pooling-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Thread Pooling Classes" title: "Thread Pooling Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/threading-models-and-critical-sections-classes.md b/docs/atl/threading-models-and-critical-sections-classes.md index 0fd1793ad8..1bc26034ca 100644 --- a/docs/atl/threading-models-and-critical-sections-classes.md +++ b/docs/atl/threading-models-and-critical-sections-classes.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Threading Models and Critical Sections Classes" title: "Threading Models and Critical Sections Classes (ATL)" ms.date: "11/04/2016" helpviewer_keywords: ["ATL, critical sections", "ATL, multithreading", "threading [ATL], models", "critical sections"] ms.assetid: 759f05ef-6285-4be6-a2cc-78572dd75146 +ms.topic: concept-article --- # Threading Models and Critical Sections Classes 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/ui-support-classes.md b/docs/atl/ui-support-classes.md index 1b3fe37840..8e5f56f4c4 100644 --- a/docs/atl/ui-support-classes.md +++ b/docs/atl/ui-support-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: UI Support Classes" title: "UI Support Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/understanding-backus-naur-form-bnf-syntax.md b/docs/atl/understanding-backus-naur-form-bnf-syntax.md index 83542d927e..7e5295bf9e 100644 --- a/docs/atl/understanding-backus-naur-form-bnf-syntax.md +++ b/docs/atl/understanding-backus-naur-form-bnf-syntax.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Understanding Backus-Naur form (BNF) syntax" title: "ATL Registrar and Backus-Naur form (BNF) syntax" ms.date: "05/14/2019" helpviewer_keywords: ["BNF notation", "Backus-Naur form (BNF) syntax"] ms.assetid: 994bbef0-9077-4aa8-bdfe-b7e830af9acc +ms.topic: concept-article --- # Understanding Backus-Naur form (BNF) syntax diff --git a/docs/atl/understanding-parse-trees.md b/docs/atl/understanding-parse-trees.md index 72eb3d3756..a0eea7d823 100644 --- a/docs/atl/understanding-parse-trees.md +++ b/docs/atl/understanding-parse-trees.md @@ -1,43 +1,50 @@ --- +description: "Learn more about: Understanding parse trees" title: "ATL Registrar and Parse Trees" -ms.date: "11/04/2016" +ms.date: 04/15/2021 helpviewer_keywords: ["parse trees"] -ms.assetid: 668ce2dd-a1c3-4ca0-8135-b25267cb6a85 +ms.topic: concept-article --- -# Understanding Parse Trees +# Understanding parse trees You can define one or more parse trees in your registrar script, where each parse tree has the following form: -> \{\}+ +> \{\}+ where: -> \ ::= HKEY_CLASSES_ROOT | HKEY_CURRENT_USER |\ ->     HKEY_LOCAL_MACHINE | HKEY_USERS |\ ->     HKEY_PERFORMANCE_DATA | HKEY_DYN_DATA |\ ->     HKEY_CURRENT_CONFIG | HKCR | HKCU |\ ->     HKLM | HKU | HKPD | HKDD | HKCC - -> \ ::= \ | \ - -> \ ::= [**ForceRemove** | **NoRemove** | **val**]\ [\][{\}] - -> \ ::= **Delete**\ - -> \ ::= **'**\+**'** - -> \ ::= *any character not NULL, i.e. ASCII 0* - -> \ ::= \\ - -> \ ::= **s** | **d** - -> \ ::= **'**\**'** +> *\* ::=\ +>  **`HKEY_CLASSES_ROOT`** | **`HKEY_CURRENT_USER`** |\ +>  **`HKEY_LOCAL_MACHINE`** | **`HKEY_USERS`** |\ +>  **`HKEY_PERFORMANCE_DATA`** | **`HKEY_DYN_DATA`** |\ +>  **`HKEY_CURRENT_CONFIG`** | **`HKCR`** | **`HKCU`** |\ +>  **`HKLM`** | **`HKU`** | **`HKPD`** | **`HKDD`** | **`HKCC`** +> +> *\* ::=\ +>   *\* | *\* +> +> *\* ::=\ +>   \[**`ForceRemove`** | **`NoRemove`** | **`val`**] *\* \[*\*] \[ **`{`** *\* **`}`** ] +> +> *\* ::=\ +>   **`Delete`** *\* +> +> *\* ::=\ +>   **`'`***\*+**`'`** +> +> *\* ::=\ +>   any non-null character. +> +> *\* ::=\ +>   *\* *\* +> +> *\* ::=\ +>   **`s`** | **`d`** > [!NOTE] -> `HKEY_CLASSES_ROOT` and `HKCR` are equivalent; `HKEY_CURRENT_USER` and `HKCU` are equivalent; and so on. +> **`HKEY_CLASSES_ROOT`** and **`HKCR`** are equivalent; **`HKEY_CURRENT_USER`** and **`HKCU`** are equivalent; and so on. -A parse tree can add multiple keys and subkeys to the \. In doing so, it keeps a subkey's handle open until the parser has completed parsing all of its subkeys. This approach is more efficient than operating on a single key at a time, as seen in the following example: +A parse tree can add multiple keys and subkeys to the \. The Registrar keeps each subkey handle open until the parser has completed parsing all of its subkeys. It's more efficient than operating on a single key at a time. Here's an example: ```rgs HKEY_CLASSES_ROOT @@ -52,8 +59,8 @@ HKEY_CLASSES_ROOT } ``` -Here, the Registrar initially opens (creates) `HKEY_CLASSES_ROOT\MyVeryOwnKey`. It then sees that `MyVeryOwnKey` has a subkey. Rather than close the key to `MyVeryOwnKey`, the Registrar retains the handle and opens (creates) `HasASubKey` using this parent handle. (The system registry can be slower when no parent handle is open.) Thus, opening `HKEY_CLASSES_ROOT\MyVeryOwnKey` and then opening `HasASubKey` with `MyVeryOwnKey` as the parent is faster than opening `MyVeryOwnKey`, closing `MyVeryOwnKey`, and then opening `MyVeryOwnKey\HasASubKey`. +Here, the Registrar initially opens (creates) `HKEY_CLASSES_ROOT\MyVeryOwnKey`. It then sees that `MyVeryOwnKey` has a subkey. Rather than close the key to `MyVeryOwnKey`, the Registrar keeps the handle and opens (creates) `HasASubKey` using this parent handle. (The system registry can be slower when no parent handle is open.) So, opening `HKEY_CLASSES_ROOT\MyVeryOwnKey` and then opening `HasASubKey` with `MyVeryOwnKey` as the parent is faster than opening `MyVeryOwnKey`, closing `MyVeryOwnKey`, and then opening `MyVeryOwnKey\HasASubKey`. ## See also -[Creating Registrar Scripts](../atl/creating-registrar-scripts.md) +[Creating registrar scripts](../atl/creating-registrar-scripts.md) diff --git a/docs/atl/understanding-window-traits.md b/docs/atl/understanding-window-traits.md index b8f66b059f..df7884f862 100644 --- a/docs/atl/understanding-window-traits.md +++ b/docs/atl/understanding-window-traits.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Understanding Window Traits" title: "ATL Window Traits" ms.date: "11/04/2016" helpviewer_keywords: ["window traits"] ms.assetid: c90cf850-9e91-49da-9cf3-ad4efb30347d +ms.topic: concept-article --- # Understanding Window Traits diff --git a/docs/atl/using-a-template-library.md b/docs/atl/using-a-template-library.md index 130105f647..11bd456ff9 100644 --- a/docs/atl/using-a-template-library.md +++ b/docs/atl/using-a-template-library.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Using a Template Library" title: "Using a Template Library (ATL)" ms.date: "11/04/2016" helpviewer_keywords: ["template libraries"] ms.assetid: 5e80ec6e-a61c-41ce-b34b-9a6252c46265 +ms.topic: concept-article --- # Using a Template Library diff --git a/docs/atl/using-a-window.md b/docs/atl/using-a-window.md index d8bb3d149a..69488133ae 100644 --- a/docs/atl/using-a-window.md +++ b/docs/atl/using-a-window.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Using a Window" title: "Using a Window (ATL)" ms.date: "11/04/2016" helpviewer_keywords: ["ATL, windows", "CWindow class, about CWindow class", "windows [C++], ATL"] ms.assetid: b3b9cc8e-4287-486b-b080-38852bc2943a +ms.topic: concept-article --- # Using a Window diff --git a/docs/atl/using-contained-windows.md b/docs/atl/using-contained-windows.md index a6aea75c7c..82894f8eea 100644 --- a/docs/atl/using-contained-windows.md +++ b/docs/atl/using-contained-windows.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Using Contained Windows" title: "Using Contained Windows" ms.date: "11/04/2016" helpviewer_keywords: ["ATL, windows", "windows [C++], ATL", "contained windows in ATL"] ms.assetid: 7b3d79e5-b569-413f-9b98-df4f14efbe2b +ms.topic: concept-article --- # Using Contained Windows diff --git a/docs/atl/using-idispeventimpl.md b/docs/atl/using-idispeventimpl.md index 54874f2ce6..9e9c1537f2 100644 --- a/docs/atl/using-idispeventimpl.md +++ b/docs/atl/using-idispeventimpl.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Using IDispEventImpl" title: "Using IDispEventImpl (ATL)" ms.date: "08/19/2019" helpviewer_keywords: ["IDispEventImpl class, using"] ms.assetid: 82d53b61-9d0d-45c5-aff9-2fafa468a9ca +ms.topic: how-to --- # Using IDispEventImpl diff --git a/docs/atl/using-idispeventsimpleimpl.md b/docs/atl/using-idispeventsimpleimpl.md index 6f3da59f91..3f50230f72 100644 --- a/docs/atl/using-idispeventsimpleimpl.md +++ b/docs/atl/using-idispeventsimpleimpl.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Using IDispEventSimpleImpl" title: "Using IDispEventSimpleImpl (ATL)" ms.date: "08/19/2019" helpviewer_keywords: ["IDispEventSimpleImpl class, using"] ms.assetid: 8640ad1a-4bd0-40a5-b5e4-7322685d7aab +ms.topic: concept-article --- # Using IDispEventSimpleImpl 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 ee17e71728..5541235e12 100644 --- a/docs/atl/using-replaceable-parameters-the-registrar-s-preprocessor.md +++ b/docs/atl/using-replaceable-parameters-the-registrar-s-preprocessor.md @@ -1,10 +1,12 @@ --- +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 +ms.topic: concept-article --- -# 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/atl/using-task-manager.md b/docs/atl/using-task-manager.md index b906d19341..31747f6282 100644 --- a/docs/atl/using-task-manager.md +++ b/docs/atl/using-task-manager.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Using Task Manager" title: "Using Task Manager" ms.date: "11/04/2016" helpviewer_keywords: ["Task Manager", "breakpoints, Task Manager", "debugging [ATL], using Task Manager"] ms.assetid: 773fccd5-308d-42c2-a17f-60ae94989062 +ms.topic: how-to --- # Using Task Manager diff --git a/docs/atl/utility-classes.md b/docs/atl/utility-classes.md index e8669292ec..df1f437594 100644 --- a/docs/atl/utility-classes.md +++ b/docs/atl/utility-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Utility Classes" title: "Utility Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" diff --git a/docs/atl/windows-support-classes.md b/docs/atl/windows-support-classes.md index 95965da43e..caa906a9fb 100644 --- a/docs/atl/windows-support-classes.md +++ b/docs/atl/windows-support-classes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Windows Support Classes" title: "Windows Support Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" 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 38959ff564..fccaa5d7f9 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,19 @@ 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 +ms.topic: how-to --- # Get started with C++ Build Insights -::: moniker range="<=vs-2017" +::: 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="vs-2019" +::: 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 +23,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 +42,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 d81e9ae3b9..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "CL_PASS_D --- # CL_PASS_DATA structure -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `CL_PASS_DATA` structure describes a compilation pass. @@ -29,7 +29,7 @@ typedef struct CL_PASS_DATA_TAG ## Members -| | | +| Name | Description | |--|--| | `TranslationUnitPassCode` | A code identifying the compilation pass being executed. For more information, see [TRANSLATION_UNIT_PASS_CODE](translation-unit-pass-code-enum.md). | | `InputSourcePath` | The C or C++ source file on which this compilation pass is being executed. | 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 99bc684daf..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "EVENT_COL --- # EVENT_COLLECTION_DATA structure -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `EVENT_COLLECTION_DATA` structure describes an array of [EVENT_DATA](event-data-struct.md) elements. @@ -28,7 +28,7 @@ typedef struct EVENT_COLLECTION_DATA_TAG ## Members -| | | +| Name | Description | |--|--| | `Count` | The number of `EVENT_DATA` elements in the array. | | `Elements` | Pointer to the first `EVENT_DATA` element in the array. | 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 0b1dd4ac48..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="<=vs-2015" +::: 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=">=vs-2017" +::: 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 @@ -46,19 +48,19 @@ typedef struct EVENT_DATA_TAG ## Members -| | | +| Name | Description | |--|--| | `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 859e6b7f2c..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "EVENT_ID" --- # EVENT_ID enum -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `EVENT_ID` enum. 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 caca2391e6..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "FILE_DATA --- # FILE_DATA structure -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `FILE_DATA` structure describes a file input or output. @@ -28,7 +28,7 @@ typedef struct FILE_DATA_TAG ## Members -| | | +| Name | Description | |--|--| | `Path` | The file's absolute path | | `TypeCode` | A code describing the type of the file. For more information, see [FILE_TYPE_CODE](file-type-code-enum.md). | 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 5e7bc2fbda..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "FILE_TYPE --- # FILE_TYPE_CODE enum -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `FILE_TYPE_CODE` enum describes the type of a file. 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 c119f5c41b..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "FRONT_END --- # FRONT_END_FILE_DATA structure -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `FRONT_END_FILE_DATA` structure describes the processing of a file by the compiler front end. @@ -27,7 +27,7 @@ typedef struct FRONT_END_FILE_DATA_TAG ## Members -| | | +| Name | Description | |--|--| | `Path` | The file's absolute path, encoded in UTF-8. | 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 df13ee2769..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "FUNCTION_ --- # FUNCTION_DATA structure -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `FUNCTION_DATA` structure describes a function. @@ -27,7 +27,7 @@ typedef struct FUNCTION_DATA_TAG ## Members -| | | +| Name | Description | |--|--| | `Name` | The function's name, encoded in UTF-8. | 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 839a8de000..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "FUNCTION_ --- # FUNCTION_FORCE_INLINEE_DATA structure -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `FUNCTION_FORCE_INLINEE_DATA` structure describes a force-inlined function. @@ -28,7 +28,7 @@ typedef struct FUNCTION_FORCE_INLINEE_DATA_TAG ## Members -| | | +| Name | Description | |--|--| | `Name` | The function's name, encoded in UTF-8. | | `Size` | The function's size, as a number of intermediate instructions. | 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 b45846849e..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "INVOCATIO --- # INVOCATION_DATA structure -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `INVOCATION_DATA` structure describes a compiler or linker invocation. @@ -33,7 +33,7 @@ typedef struct INVOCATION_DATA_TAG ## Members -| | | +| Name | Description | |--|--| | `MSVCToolCode` | A code that identifies the invocation's type. For more information, see [MSVC_TOOL_CODE](msvc-tool-code-enum.md). | | `ToolVersion` | An object that stores the invoked tool's version as a group of integral values. | 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 2b6cfbfe5d..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "INVOCATIO --- # INVOCATION_VERSION_DATA structure -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `INVOCATION_VERSION_DATA` structure describes a version number as a group of integral values. @@ -30,7 +30,7 @@ typedef struct INVOCATION_VERSION_DATA_TAG ## Members -| | | +| Name | Description | |--|--| | `VersionMajor` | The version's major number. | | `VersionMinor` | The version's minor number. | 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 16d502e42e..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "MSVC_TOOL --- # MSVC_TOOL_CODE enum -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `MSVC_TOOL_CODE` enum. 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 de13d49ca3..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "NAME_VALU --- # NAME_VALUE_PAIR_DATA structure -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `NAME_VALUE_PAIR_DATA` structure describes a name and value pair. @@ -27,7 +27,7 @@ typedef struct NAME_VALUE_PAIR_DATA_TAG ## Members -| | | +| Name | Description | |--|--| | `Name` | The name. | | `Value` | The value. | 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 4a1c3b99cf..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "SYMBOL_NA --- # SYMBOL_NAME_DATA structure -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `SYMBOL_NAME_DATA` structure describes a compiler front-end symbol. @@ -28,7 +28,7 @@ typedef struct SYMBOL_NAME_DATA_TAG ## Members -| | | +| Name | Description | |--|--| | `Key` | The symbol's key. This value is unique within the trace being analyzed. | | `Name` | The symbol's name. | 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 e8d89a8ec5..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TEMPLATE_ --- # TEMPLATE_INSTANTIATION_DATA structure -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `TEMPLATE_INSTANTIATION_DATA` structure describes a template instantiation. @@ -29,7 +29,7 @@ typedef struct TEMPLATE_INSTANTIATION_DATA_TAG ## Members -| | | +| Name | Description | |--|--| | `SpecializationSymbolKey` | The key for the template specialization's type. This value is unique within the trace being analyzed. | | `PrimaryTemplateSymbolKey` | The key for the primary template type that was specialized. This value is unique within the trace being analyzed. | 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 b1aaa00ad6..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TEMPLATE_ --- # TEMPLATE_INSTANTIATION_KIND_CODE enum -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `TEMPLATE_INSTANTIATION_KIND_CODE` enum. 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 4092ed2331..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TRACE_INF --- # TRACE_INFO_DATA structure -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `TRACE_INFO_DATA` structure describes a trace being analyzed or relogged. @@ -30,7 +30,7 @@ typedef struct TRACE_INFO_DATA_TAG ## Members -| | | +| Name | Description | |--|--| | `LogicalProcessorCount` | The number of logical processors on the machine where the trace was collected. | | `TickFrequency` | The number of ticks per second to use when evaluating a duration measured in ticks. | 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 ce4e09ab1f..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TRANSLATI --- # TRANSLATION_UNIT_PASS_CODE enum -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `TRANSLATION_UNIT_PASS_CODE` enum. 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 2228c58ab1..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,17 +1,20 @@ --- -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="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `Activity` 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 any activity event. Refer to [event table](../event-table.md) to see all events that can be matched by the `Activity` class. 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 48cc2703f5..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,17 +1,20 @@ --- -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="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `BackEndPass` 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 [BACK_END_PASS](../event-table.md#back-end-pass) event. 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 254f514049..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "BottomUp" --- # BottomUp class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `BottomUp` 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 [BOTTOM_UP](../event-table.md#bottom-up) event. 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 26af4ff995..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,17 +1,20 @@ --- -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="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `C1DLL` 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 [C1_DLL](../event-table.md#c1-dll) event. 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 f3621085f6..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "C2DLL", " --- # C2DLL class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `C2DLL` 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 [C2_DLL](../event-table.md#c2-dll) event. 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 6865a89684..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "CodeGener --- # CodeGeneration class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `CodeGeneration` 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 [CODE_GENERATION](../event-table.md#code-generation) event. 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 697ac070ab..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "CommandLi --- # CommandLine class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `CommandLine` 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 [COMMAND_LINE](../event-table.md#command-line) event. 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 4b8a3dccb9..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "CompilerP --- # CompilerPass class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `CompilerPass` 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 [BACK_END_PASS](../event-table.md#back-end-pass) or [FRONT_END_PASS](../event-table.md#front-end-pass) event. @@ -47,7 +47,7 @@ Along with the inherited members from its [Activity](activity.md) base class, th #### PassCode -||| +|Value|Description| |-|-| |FRONT_END|The front-end pass.| |BACK_END|The back-end pass.| @@ -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 b8ccf34851..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Compiler" --- # Compiler class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `Compiler` 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 [COMPILER](../event-table.md#compiler) event. 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 bd49c48810..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Environme --- # EnvironmentVariable class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `EnvironmentVariable` 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 an [ENVIRONMENT_VARIABLE](../event-table.md#environment-variable) event. @@ -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 ce82594208..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "EventGrou --- # EventGroup class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `EventGroup` class template is the base class for all group capture classes. @@ -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 fee4a549ba..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "EventStac --- # EventStack class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `EventStack` class is a collection of [Event](event.md) objects. All events received from the C++ Build Insights SDK come in the form of an `EventStack` object. The last entry in this stack is the event currently being processed. The entries that precede the last entry are the parent hierarchy of the current event. For more information on the event model used in C++ Build Insights, see [event table](../event-table.md). @@ -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 e885746d9f..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Event", " --- # Event class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `Event` 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 any event. @@ -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 04e76fbba9..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Executabl --- # ExecutableImageOutput class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `ExecutableImageOutput` 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 an [EXECUTABLE_IMAGE_OUTPUT](../event-table.md#executable-image-output) event. 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 3232656a5f..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "ExpOutput --- # ExpOutput class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `ExpOutput` 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 an [EXP_OUTPUT](../event-table.md#exp-output) event. 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 e4acd598a6..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "FileInput --- # FileInput class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `FileInput` 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 [FILE_INPUT](../event-table.md#file-input) event. @@ -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 a22f2896db..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "FileOutpu --- # FileOutput class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `FileOutput` 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 an [EXECUTABLE_IMAGE_OUTPUT](../event-table.md#executable-image-output), [EXP_OUTPUT](../event-table.md#exp-output), [IMP_LIB_OUTPUT](../event-table.md#imp-lib-output), [LIB_OUTPUT](../event-table.md#lib-output), or [OBJ_OUTPUT](../event-table.md#obj-output) event. @@ -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 ceaa8e2df3..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "ForceInli --- # ForceInlinee class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `ForceInlinee` 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 [FORCE_INLINEE](../event-table.md#force-inlinee) event. @@ -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 6cc5dfbdc9..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "FrontEndF --- # FrontEndFileGroup class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `FrontEndFileGroup` class is used with the [MatchEventStack](../functions/match-event-stack.md) and [MatchEventStackInMemberFunction](../functions/match-event-stack-in-member-function.md) functions. Use it to match groups of [FRONT_END_FILE](../event-table.md#front-end-file) events. 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 ff67d7c8ba..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "FrontEndF --- # FrontEndFile class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `FrontEndFile` 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 [FRONT_END_FILE](../event-table.md#front-end-file) event. 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 8589cd4af0..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "FrontEndP --- # FrontEndPass class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `FrontEndPass` 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 [FRONT_END_PASS](../event-table.md#front-end-pass) event. 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 ee77403a8e..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,17 +1,19 @@ --- -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="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `Function` 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 [FUNCTION](../event-table.md#function) event. @@ -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 6425648dfd..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "ImpLibOut --- # ImpLibOutput class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `ImpLibOutput` 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 an [IMP_LIB_OUTPUT](../event-table.md#imp-lib-output) event. 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 9d9160d2ab..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Invocatio --- # InvocationGroup class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `InvocationGroup` class is used with the [MatchEventStack](../functions/match-event-stack.md) and [MatchEventStackInMemberFunction](../functions/match-event-stack-in-member-function.md) functions. Use it to match groups containing a mix of [COMPILER](../event-table.md#compiler) and [LINKER](../event-table.md#linker) events. 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 3ffe65241d..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Invocatio --- # Invocation class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `Invocation` 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 [COMPILER](../event-table.md#compiler) or [LINKER](../event-table.md#linker) event. @@ -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 91be1b3136..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "LibOutput --- # LibOutput class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `LibOutput` 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 [LIB_OUTPUT](../event-table.md#lib-output) event. 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 7277f6fc05..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "LinkerGro --- # LinkerGroup class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `LinkerGroup` class is used with the [MatchEventStack](../functions/match-event-stack.md) and [MatchEventStackInMemberFunction](../functions/match-event-stack-in-member-function.md) functions. Use it to match groups of [LINKER](../event-table.md#linker) events. 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 611d3a6cc8..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "LinkerPas --- # LinkerPass class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `LinkerPass` 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 [PASS1](../event-table.md#pass1) or [PASS2](../event-table.md#pass2) event. 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 d543294763..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Linker", --- # Linker class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `Linker` 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 [LINKER](../event-table.md#linker) event. 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 29a78797bc..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "LTCG", "t --- # LTCG class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `LTCG` 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 [LTCG](../event-table.md#ltcg) event. 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 81290caa45..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "ObjOutput --- # ObjOutput class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `ObjOutput` 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 an [OBJ_OUTPUT](../event-table.md#obj-output) event. 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 15c719eca9..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "OptICF", --- # OptICF class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `OptICF` 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 an [OPT_ICF](../event-table.md#opt-icf) event. 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 9605cfee53..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "OptLBR", --- # OptLBR class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `OptLBR` 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 an [OPT_LBR](../event-table.md#opt-lbr) event. 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 82466c9e50..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "OptRef", --- # OptRef class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `OptRef` 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 an [OPT_REF](../event-table.md#opt-ref) event. 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 c0ee2832d1..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,17 +1,19 @@ --- -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="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `Pass1` 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 [PASS1](../event-table.md#pass1) event. @@ -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 b4ebda5ad3..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Pass2", " --- # Pass2 class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `Pass2` 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 [PASS2](../event-table.md#pass2) event. 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 343a7173e0..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "PreLTCGOp --- # PreLTCGOptRef class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `PreLTCGOptRef` 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 [PRE_LTCG_OPT_REF](../event-table.md#pre-ltcg-opt-ref) event. 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 bea4ac1ce0..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "RawEvent" --- # RawEvent class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `RawEvent` class is used to represent a general event in an [EventStack](event-stack.md). @@ -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 d899c134d7..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "SimpleEve --- # SimpleEvent class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `SimpleEvent` 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 any simple event. Refer to the [event table](../event-table.md) to see all events that can be matched by the `SimpleEvent` class. 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 c34a07fb2d..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "SymbolNam --- # SymbolName class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `SymbolName` 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 [SYMBOL_NAME](../event-table.md#symbol-name) event. @@ -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 c798819e6d..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TemplateI --- # TemplateInstantiationGroup class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `TemplateInstantiationGroup` class is used with the [MatchEventStack](../functions/match-event-stack.md) and [MatchEventStackInMemberFunction](../functions/match-event-stack-in-member-function.md) functions. Use it to match groups of [TEMPLATE_INSTANTIATION](../event-table.md#template-instantiation) events. 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 127789c274..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TemplateI --- # TemplateInstantiation class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `TemplateInstantiation` 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 [TEMPLATE_INSTANTIATION](../event-table.md#template-instantiation) event. @@ -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 c361ed90f7..1e850cafb6 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 @@ -3,15 +3,16 @@ title: "Thread class" description: "The C++ Build Insights SDK Thread class reference." ms.date: "02/12/2020" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Thread", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference --- # Thread class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `Thread` 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 [THREAD](../event-table.md#thread) event. 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 6d74855a9d..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TopDown", --- # TopDown class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `TopDown` 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 [TOP_DOWN](../event-table.md#top-down) event. 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 a318fe02d2..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TraceInfo --- # TraceInfo class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `TraceInfo` class is used to access useful properties about a trace being analyzed or relogged. @@ -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 ce51f2fd3f..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "WholeProg --- # WholeProgramAnalysis class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `WholeProgramAnalysis` 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 [WHOLE_PROGRAM_ANALYSIS](../event-table.md#whole-program-analysis) event. diff --git a/docs/build-insights/reference/sdk/event-table.md b/docs/build-insights/reference/sdk/event-table.md index 0b1f7110db..2a2993364f 100644 --- a/docs/build-insights/reference/sdk/event-table.md +++ b/docs/build-insights/reference/sdk/event-table.md @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Events", --- # C++ Build Insights SDK: event table -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" ## Compiler events @@ -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 48792d7a97..2f690eaa29 100644 --- a/docs/build-insights/reference/sdk/functions/analyze-a.md +++ b/docs/build-insights/reference/sdk/functions/analyze-a.md @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "AnalyzeA" --- # AnalyzeA -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `AnalyzeA` function is used to analyze MSVC events read from an input Event Tracing for Windows (ETW) trace. diff --git a/docs/build-insights/reference/sdk/functions/analyze-w.md b/docs/build-insights/reference/sdk/functions/analyze-w.md index 538a227021..f7dc804272 100644 --- a/docs/build-insights/reference/sdk/functions/analyze-w.md +++ b/docs/build-insights/reference/sdk/functions/analyze-w.md @@ -1,17 +1,20 @@ --- -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 -::: moniker range="<=vs-2015" +# AnalyzeW function -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. +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `AnalyzeW` function is used to analyze MSVC events read from an input Event Tracing for Windows (ETW) trace. diff --git a/docs/build-insights/reference/sdk/functions/analyze.md b/docs/build-insights/reference/sdk/functions/analyze.md index 2332b75847..32e5bd369c 100644 --- a/docs/build-insights/reference/sdk/functions/analyze.md +++ b/docs/build-insights/reference/sdk/functions/analyze.md @@ -1,17 +1,20 @@ --- -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 -::: moniker range="<=vs-2015" +# Analyze function -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. +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `Analyze` function is used to analyze an Event Tracing for Windows (ETW) trace obtained from MSVC while tracing a C++ build. The events in the ETW trace are forwarded sequentially to an analyzer group provided by the caller. This function supports multi-pass analyses that allow forwarding the event stream to the analyzer group multiple times in a row. diff --git a/docs/build-insights/reference/sdk/functions/inject-event.md b/docs/build-insights/reference/sdk/functions/inject-event.md index 1d2476b888..e642578856 100644 --- a/docs/build-insights/reference/sdk/functions/inject-event.md +++ b/docs/build-insights/reference/sdk/functions/inject-event.md @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "InjectEve --- # InjectEvent -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `InjectEvent` function is called within a relogger implementing the [IRelogger](../other-types/irelogger-class.md) interface. It's used to write an Event Tracing for Windows (ETW) event in the output trace file of a relogging session. 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 4fae4da0ec..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "MakeDynam --- # MakeDynamicAnalyzerGroup -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `MakeDynamicAnalyzerGroup` function is used to create a dynamic analyzer group. Members of an analyzer group receive events one by one from left to right, until all events in a trace get analyzed. 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 4844d75956..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "MakeDynam --- # MakeDynamicReloggerGroup -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `MakeDynamicReloggerGroup` function is used to create a dynamic relogger group. Members of a relogger group receive events one by one from left to right until all events in a trace have been processed. 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 7eaf918c02..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="<=vs-2015" +::: 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=">=vs-2017" +::: 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 708d174f07..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "MakeStati --- # MakeStaticReloggerGroup -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `MakeStaticReloggerGroup` function is used to create a static relogger group that can be passed to functions such as [Relog](relog.md). Members of a relogger group receive events one by one from left to right until all events in a trace have been processed. 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 bf035b126d..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "MatchEven --- # MatchEventInMemberFunction -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `MatchEventInMemberFunction` function is used to match an event against the type described by the first parameter of a member function. The matched event is forwarded to the member function for further processing. 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 519f15322c..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "MatchEven --- # MatchEventStackInMemberFunction -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `MatchEventStackInMemberFunction` function is used to match an event stack against a specific event hierarchy, described by the parameter list of a member function. Matched hierarchies are forwarded to the member function for further processing. To learn more about events, event stacks, and hierarchies, see [event table](../event-table.md). 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 681528e2b8..55a15df0fa 100644 --- a/docs/build-insights/reference/sdk/functions/match-event-stack.md +++ b/docs/build-insights/reference/sdk/functions/match-event-stack.md @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "MatchEven --- # MatchEventStack -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `MatchEventStack` function is used to match an event stack against a specific event hierarchy. Matched hierarchies are forwarded to a handler for further processing. To learn more about events, event stacks, and hierarchies, see [event table](../event-table.md). diff --git a/docs/build-insights/reference/sdk/functions/match-event.md b/docs/build-insights/reference/sdk/functions/match-event.md index 284cc332f0..e392c3184d 100644 --- a/docs/build-insights/reference/sdk/functions/match-event.md +++ b/docs/build-insights/reference/sdk/functions/match-event.md @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "MatchEven --- # MatchEvent -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `MatchEvent` function is used to match an event against a list of event types. If the event matches a type in the list, it's forwarded to a handler for further processing. diff --git a/docs/build-insights/reference/sdk/functions/relog-a.md b/docs/build-insights/reference/sdk/functions/relog-a.md index a3b9ed1b4f..36ec0048ec 100644 --- a/docs/build-insights/reference/sdk/functions/relog-a.md +++ b/docs/build-insights/reference/sdk/functions/relog-a.md @@ -1,17 +1,17 @@ --- title: "RelogA" description: "The C++ Build Insights SDK RelogA function reference." -ms.date: "02/12/2020" +ms.date: 02/12/2020 helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "RelogA", "throughput analysis", "build time analysis", "vcperf.exe"] --- -# RelogA +# `RelogA` -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `RelogA` function is used to read MSVC events from an Event Tracing for Windows (ETW) trace and write them into a new, modified ETW trace. @@ -26,17 +26,17 @@ enum RESULT_CODE RelogA( ### Parameters -*inputLogFile*\ +*`inputLogFile`*\ The input ETW trace that you wish to read events from. -*outputLogFile*\ +*`outputLogFile`*\ The file in which to write the new events. -*relogDescriptor*\ -Pointer to a [RELOG_DESCRIPTOR](../other-types/relog-descriptor-struct.md) object. Use this object to configure the relogging session. +*`relogDescriptor`*\ +Pointer to a [`RELOG_DESCRIPTOR`](../other-types/relog-descriptor-struct.md) object. Use this object to configure the relogging session. ### Return Value -A result code from the [RESULT_CODE](../other-types/result-code-enum.md) enum. +A result code from the [`RESULT_CODE`](../other-types/result-code-enum.md) enum. ::: moniker-end diff --git a/docs/build-insights/reference/sdk/functions/relog-w.md b/docs/build-insights/reference/sdk/functions/relog-w.md index afb54b5054..d042d6ce85 100644 --- a/docs/build-insights/reference/sdk/functions/relog-w.md +++ b/docs/build-insights/reference/sdk/functions/relog-w.md @@ -1,17 +1,17 @@ --- title: "RelogW" description: "The C++ Build Insights SDK RelogW function reference." -ms.date: "02/12/2020" +ms.date: 02/12/2020 helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "RelogW", "throughput analysis", "build time analysis", "vcperf.exe"] --- -# RelogW +# `RelogW` -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `RelogW` function is used to read MSVC events from an input Event Tracing for Windows (ETW) trace and write them into a new, modified ETW trace. @@ -26,17 +26,17 @@ enum RESULT_CODE RelogW( ### Parameters -*inputLogFile*\ +*`inputLogFile`*\ The input ETW trace that you wish to read events from. -*outputLogFile*\ +*`outputLogFile`*\ The file in which to write the new events. -*relogDescriptor*\ -Pointer to a [RELOG_DESCRIPTOR](../other-types/relog-descriptor-struct.md) object. Use this object to configure the relogging session. +*`relogDescriptor`*\ +Pointer to a [`RELOG_DESCRIPTOR`](../other-types/relog-descriptor-struct.md) object. Use this object to configure the relogging session. ### Return Value -A result code from the [RESULT_CODE](../other-types/result-code-enum.md) enum. +A result code from the [`RESULT_CODE`](../other-types/result-code-enum.md) enum. ::: moniker-end diff --git a/docs/build-insights/reference/sdk/functions/relog.md b/docs/build-insights/reference/sdk/functions/relog.md index 2b5f0883de..4bf0bb1dce 100644 --- a/docs/build-insights/reference/sdk/functions/relog.md +++ b/docs/build-insights/reference/sdk/functions/relog.md @@ -1,17 +1,17 @@ --- title: "Relog" description: "The C++ Build Insights SDK Relog function reference." -ms.date: "02/12/2020" +ms.date: 02/12/2020 helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Relog", "throughput analysis", "build time analysis", "vcperf.exe"] --- -# Relog +# `Relog` -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `Relog` function is used to read MSVC events from an Event Tracing for Windows (ETW) trace and write them into a new, modified ETW trace. @@ -41,40 +41,44 @@ RESULT_CODE Relog( StaticReloggerGroup reloggerGroup); ``` -### Parameters +### Template parameters + +*`TAnalyzerGroupMembers`*\ +This template parameter pack is always deduced. -*TAnalyzerGroupMembers*\ -This parameter is always deduced. +*`TReloggerGroupMembers`*\ +This template parameter pack is always deduced. -*TReloggerGroupMembers*\ -This parameter is always deduced. +### Parameters -*inputLogFile*\ +*`inputLogFile`*\ The input ETW trace that you wish to read events from. -*outputLogFile*\ +*`outputLogFile`*\ The file in which to write the new events. -*numberOfAnalysisPasses*\ +*`numberOfAnalysisPasses`*\ The number of analysis passes to run on the input trace. The trace gets passed through the provided analyzer group once per analysis pass. -*systemEventsRetentionFlags*\ -A bitmask that specifies which system ETW events to keep in the relogged trace. For more information, see [RELOG_RETENTION_SYSTEM_EVENT_FLAGS](../other-types/relog-retention-system-event-flags-constants.md). +*`systemEventsRetentionFlags`*\ +A bitmask that specifies which system ETW events to keep in the relogged trace. For more information, see [`RELOG_RETENTION_SYSTEM_EVENT_FLAGS`](../other-types/relog-retention-system-event-flags-constants.md). -*analyzerGroup*\ -The analyzer group used for the analysis phase of the relogging session. Call [MakeStaticAnalyzerGroup](make-static-analyzer-group.md) to create an analyzer group. To use a dynamic analyzer group obtained from [MakeDynamicAnalyzerGroup](make-dynamic-analyzer-group.md), first encapsulate it inside a static analyzer group by passing its address to `MakeStaticAnalyzerGroup`. +*`analyzerGroup`*\ +The analyzer group used for the analysis phase of the relogging session. Call [`MakeStaticAnalyzerGroup`](make-static-analyzer-group.md) to create an analyzer group. To use a dynamic analyzer group obtained from [`MakeDynamicAnalyzerGroup`](make-dynamic-analyzer-group.md), first encapsulate it inside a static analyzer group by passing its address to `MakeStaticAnalyzerGroup`. -*reloggerGroup*\ -The relogger group that relogs events into the trace file specified in *outputLogFile*. Call [MakeStaticReloggerGroup](make-static-relogger-group.md) to create a relogger group. To use a dynamic relogger group obtained from [MakeDynamicReloggerGroup](make-dynamic-relogger-group.md), first encapsulate it inside a static relogger group by passing its address to `MakeStaticReloggerGroup`. +*`reloggerGroup`*\ +The relogger group that relogs events into the trace file specified in *`outputLogFile`*. Call [`MakeStaticReloggerGroup`](make-static-relogger-group.md) to create a relogger group. To use a dynamic relogger group obtained from [`MakeDynamicReloggerGroup`](make-dynamic-relogger-group.md), first encapsulate it inside a static relogger group by passing its address to `MakeStaticReloggerGroup`. ### Return Value -A result code from the [RESULT_CODE](../other-types/result-code-enum.md) enum. +A result code from the [`RESULT_CODE`](../other-types/result-code-enum.md) enum. + +### Remarks -### Remark +The input trace is passed through the analyzer group *`numberOfAnalysisPasses`* times. There's no similar option for relogging passes. The trace is passed trough the relogger group only once, after all analysis passes are complete. -The input trace is passed through the analyzer group *numberOfAnalysisPasses* times. There's no similar option for relogging passes. The trace is passed trough the relogger group only once, after all analysis passes are complete. +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 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`](/windows/win32/api/objbase/nf-objbase-coinitialize) before you call `relog`. Call [`CoUninitialize`](/windows/win32/api/combaseapi/nf-combaseapi-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 cb781563dc..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "StartTrac --- # StartTracingSessionA -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `StartTracingSessionA` function starts a tracing session. Executables calling this function must have administrator privileges. 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 5af29356fe..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "StartTrac --- # StartTracingSessionW -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `StartTracingSessionW` function starts a tracing session. Executables calling this function must have administrator privileges. 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 cf0a0e627a..78270e8aa0 100644 --- a/docs/build-insights/reference/sdk/functions/start-tracing-session.md +++ b/docs/build-insights/reference/sdk/functions/start-tracing-session.md @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "StartTrac --- # StartTracingSession -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `StartTracingSession` function starts a tracing session. Executables calling this function must have administrator privileges. 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 e1b5d7df4e..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "StopAndAn --- # StopAndAnalyzeTracingSessionA -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `StopAndAnalyzeTracingSessionA` function stops an ongoing tracing session and saves the resulting trace in a temporary file. An analysis session is then immediately started using the temporary file as an input. Executables calling this function must have administrator privileges. 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 3ec51b605d..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "StopAndAn --- # StopAndAnalyzeTracingSessionW -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `StopAndAnalyzeTracingSessionW` function stops an ongoing tracing session and saves the resulting trace in a temporary file. An analysis session is then immediately started using the temporary file as an input. Executables calling this function must have administrator privileges. 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 ea1a0f2a4a..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "StopAndAn --- # StopAndAnalyzeTracingSession -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `StopAndAnalyzeTracingSession` function stops an ongoing tracing session and saves the resulting trace in a temporary file. An analysis session is then immediately started using the temporary file as an input. Executables calling this function must have administrator privileges. 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 819dbaaf5b..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "StopAndRe --- # StopAndRelogTracingSessionA -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `StopAndRelogTracingSessionA` function stops an ongoing tracing session and saves the resulting trace in a temporary file. A relogging session is then immediately started using the temporary file as an input. The final relogged trace produced by the relogging session is saved in a file specified by the caller. Executables calling this function must have administrator privileges. 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 5159ed8685..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "StopAndRe --- # StopAndRelogTracingSessionW -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `StopAndRelogTracingSessionW` function stops an ongoing tracing session and saves the resulting trace in a temporary file. A relogging session is then immediately started using the temporary file as an input. The final relogged trace produced by the relogging session is saved in a file specified by the caller. Executables calling this function must have administrator privileges. 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 fac4cef9c0..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "StopAndRe --- # StopAndRelogTracingSession -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `StopAndRelogTracingSession` function stops an ongoing tracing session and saves the resulting trace in a temporary file. A relogging session is then immediately started using the temporary file as an input. The final relogged trace produced by the relogging session is saved in a file specified by the caller. Executables calling this function must have administrator privileges. 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 181fa7d358..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 @@ -6,14 +6,14 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "StopTraci --- # StopTracingSessionA -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: 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 75cbb4407f..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 @@ -6,14 +6,14 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "StopTraci --- # StopTracingSessionW -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: 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 0fa48098c5..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="<=vs-2015" +::: 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=">=vs-2017" +::: 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 580787ba55..348969f6fd 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 @@ -3,15 +3,16 @@ title: "ANALYSIS_CALLBACKS structure" description: "The C++ Build Insights SDK ANALYSIS_CALLBACKS structure reference." ms.date: "02/12/2020" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "ANALYSIS_CALLBACKS", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference --- # ANALYSIS_CALLBACKS structure -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `ANALYSIS_CALLBACKS` structure is used when initializing an [ANALYSIS_DESCRIPTOR](analysis-descriptor-struct.md) or [RELOG_DESCRIPTOR](relog-descriptor-struct.md) object. It specifies which functions to call during the analysis or relogging of an Event Tracing for Windows (ETW) trace. @@ -33,7 +34,7 @@ typedef struct ANALYSIS_CALLBACKS_TAG ## Members -| | | +| Name | Description | |--|--| | `OnStartActivity` | Called to process an activity start event. | | `OnStopActivity` | Called to process an activity stop event. | 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 ab76cc0912..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 @@ -6,18 +6,18 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "AnalysisC --- # AnalysisControl enum class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `AnalysisControl` enum class is used control the flow of an analysis or relogging session. Return an `AnalysisControl` code from an [IAnalyzer](ianalyzer-class.md) or [IRelogger](irelogger-class.md) member function to control what should happen next. ## Members -| | | +| Name | Description | |--|--| | `BLOCK` | Prevents the current event from propagating further in the analyzer or relogger group. | | `CANCEL` | Cancel the current analysis or relogging session. | 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 d19ec5e7ea..d18e384ca2 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 @@ -3,15 +3,16 @@ title: "ANALYSIS_DESCRIPTOR structure" description: "The C++ Build Insights SDK ANALYSIS_DESCRIPTOR structure reference." ms.date: "02/12/2020" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "ANALYSIS_DESCRIPTOR", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference --- # ANALYSIS_DESCRIPTOR structure -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `ANALYSIS_DESCRIPTOR` structure is used with the [AnalyzeA](../functions/analyze-a.md) and [AnalyzeW](../functions/analyze-w.md) functions. It describes how an Event Tracing for Windows (ETW) trace should be analyzed. @@ -28,7 +29,7 @@ typedef struct ANALYSIS_DESCRIPTOR_TAG ## Members -| | | +| Name | Description | |--|--| | `NumberOfPasses` | The number of analysis passes that should be done over the ETW trace. | | `Callbacks` | An [ANALYSIS_CALLBACKS](analysis-callbacks-struct.md) object that specifies which functions to call during the analysis session. | 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 e90da86ef6..85cbc687ae 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 @@ -3,15 +3,16 @@ title: "CALLBACK_CODE enum" description: "The C++ Build Insights SDK CALLBACK_CODE enum reference." ms.date: "02/12/2020" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "CALLBACK_CODE", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference --- # CALLBACK_CODE enum -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `CALLBACK_CODE` enum is used control the flow of an analysis or relogging session. Return a CALLBACK_CODE value from the functions in [ANALYSIS_CALLBACKS](analysis-callbacks-struct.md) or [RELOG_CALLBACKS](relog-callbacks-struct.md) to control what should happen next. 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 5cd7188323..b08d6a4ab3 100644 --- a/docs/build-insights/reference/sdk/other-types/ianalyzer-class.md +++ b/docs/build-insights/reference/sdk/other-types/ianalyzer-class.md @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "IAnalyzer --- # IAnalyzer class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `IAnalyzer` class provides an interface for analyzing an Event Tracing for Windows (ETW) trace. It's used with the [MakeDynamicAnalyzerGroup](../functions/make-dynamic-analyzer-group.md), [MakeDynamicReloggerGroup](../functions/make-dynamic-relogger-group.md), [MakeStaticAnalyzerGroup](../functions/make-dynamic-analyzer-group.md), and [MakeStaticReloggerGroup](../functions/make-static-analyzer-group.md) functions. Use `IAnalyzer` as a base class to create your own analyzer that can be part of an analyzer or relogger group. 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 e0c5ef81ac..8fedb9fc5b 100644 --- a/docs/build-insights/reference/sdk/other-types/irelogger-class.md +++ b/docs/build-insights/reference/sdk/other-types/irelogger-class.md @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "IRelogger --- # IRelogger class -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `IRelogger` class provides an interface for relogging an Event Tracing for Windows (ETW) trace. It's used with the [MakeDynamicReloggerGroup](../functions/make-dynamic-relogger-group.md) and [MakeStaticReloggerGroup](../functions/make-static-analyzer-group.md) functions. Use `IRelogger` as a base class to create your own relogger that can be part of a relogger group. 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 c3708135ec..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "OnAnalysi --- # OnAnalysisEventFunc typedef -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `OnAnalysisEventFunc` typedef is one of the function signatures used in the [ANALYSIS_CALLBACKS](analysis-callbacks-struct.md) structure. 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 404c6b463c..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "OnBeginEn --- # OnBeginEndPassFunc typedef -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `OnBeginEndPassFunc` typedef is one of the function signatures used in the [ANALYSIS_CALLBACKS](analysis-callbacks-struct.md) and [RELOG_CALLBACKS](relog-callbacks-struct.md) structures. @@ -24,7 +24,7 @@ typedef enum CALLBACK_CODE (BUILD_INSIGHTS_API *OnBeginEndPassFunc)( ## Members -| | | +| Name | Description | |--|--| | `callbackContext` | | 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 8a92188365..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "OnRelogEv --- # OnRelogEventFunc typedef -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `OnRelogEventFunc` typedef is one of the function signatures used in the [RELOG_CALLBACKS](relog-callbacks-struct.md) structure. 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 cdf30ba897..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 @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "OnTraceIn --- # OnTraceInfoFunc typedef -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `OnTraceInfoFunc` typedef is one of the function signatures used in the [ANALYSIS_CALLBACKS](analysis-callbacks-struct.md) and [RELOG_CALLBACKS](relog-callbacks-struct.md) structures. 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 0c7af68bde..d3173d03ac 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 @@ -3,15 +3,16 @@ title: "RELOG_CALLBACKS structure" description: "The C++ Build Insights SDK RELOG_CALLBACKS structure reference." ms.date: "02/12/2020" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "RELOG_CALLBACKS", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference --- # RELOG_CALLBACKS structure -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `RELOG_CALLBACKS` structure is used when initializing a [RELOG_DESCRIPTOR](relog-descriptor-struct.md) object. It specifies which functions to call during the relogging of an Event Tracing for Windows (ETW) trace. @@ -33,7 +34,7 @@ typedef struct RELOG_CALLBACKS_TAG ## Members -| | | +| Name | Description | |--|--| | `OnStartActivity` | Called to process an activity start event. | | `OnStopActivity` | Called to process an activity stop event. | 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 f86ffb6544..36fa65c767 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 @@ -3,15 +3,16 @@ title: "RELOG_DESCRIPTOR structure" description: "The C++ Build Insights SDK RELOG_DESCRIPTOR structure reference." ms.date: "02/12/2020" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "RELOG_DESCRIPTOR", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference --- # RELOG_DESCRIPTOR structure -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `RELOG_DESCRIPTOR` structure is used with the [RelogA](../functions/relog-a.md) and [RelogW](../functions/relog-w.md) functions. It describes how an Event Tracing for Windows (ETW) trace should be relogged. @@ -31,7 +32,7 @@ typedef struct RELOG_DESCRIPTOR_TAG ## Members -| | | +| Name | Description | |--|--| | `NumberOfAnalysisPasses` | The number of analysis passes that should be done over the ETW trace during the relogging session's analysis phase. | | `AnalysisCallbacks` | An [ANALYSIS_CALLBACKS](analysis-callbacks-struct.md) object that specifies which functions to call during the relogging session's analysis phase. | 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 d82fbe7c8c..c82f194f46 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 @@ -3,15 +3,16 @@ title: "RELOG_RETENTION_SYSTEM_EVENT_FLAGS constants" description: "The C++ Build Insights SDK RELOG_RETENTION_SYSTEM_EVENT_FLAGS constants reference." ms.date: "02/12/2020" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "RELOG_RETENTION_SYSTEM_EVENT_FLAGS", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference --- # RELOG_RETENTION_SYSTEM_EVENT_FLAGS constants -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `RELOG_RETENTION_SYSTEM_EVENT_FLAGS` constants are used to describe which system events to keep in a relogged trace. Use them to initialize the [RELOG_DESCRIPTOR](relog-descriptor-struct.md) structure's `SystemEventsRetentionFlags` field. @@ -27,7 +28,7 @@ static const unsigned long long ## Members -| | | +| Name | Description | |--|--| | `RELOG_RETENTION_SYSTEM_EVENT_FLAGS_CPU_SAMPLES` | Keep CPU sample system events in a relogged trace. | | `RELOG_RETENTION_SYSTEM_EVENT_FLAGS_ALL` | Keep all system events in a relogged trace. | 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 2d3669397e..d6ac44cca2 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 @@ -3,15 +3,16 @@ title: "RESULT_CODE enum" description: "The C++ Build Insights SDK RESULT_CODE enum reference." ms.date: "02/12/2020" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "RESULT_CODE", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference --- # RESULT_CODE enum -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `RESULT_CODE` enum describes success and failure conditions. 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 4a3902fb57..5bc47f3b43 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 @@ -3,15 +3,16 @@ title: "TRACING_SESSION_MSVC_EVENT_FLAGS constants" description: "The C++ Build Insights SDK TRACING_SESSION_MSVC_EVENT_FLAGS constants reference." ms.date: "02/12/2020" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TRACING_SESSION_MSVC_EVENT_FLAGS", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference --- # TRACING_SESSION_MSVC_EVENT_FLAGS constants -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `TRACING_SESSION_MSVC_EVENT_FLAGS` constants are used to describe which MSVC events to collect during a trace. Use them to initialize the [TRACING_SESSION_OPTIONS](tracing-session-options-struct.md) structure's `MsvcEventFlags` field. 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 db299cb318..f087e51bf3 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 @@ -1,17 +1,18 @@ --- title: "TRACING_SESSION_OPTIONS structure" -description: "The C++ Build Insights SDK TRACING_SESSION_OPTIONS structure reference." +description: "Learn about the C++ Build Insights SDK TRACING_SESSION_OPTIONS structure reference." ms.date: "02/12/2020" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TRACING_SESSION_OPTIONS", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference --- # TRACING_SESSION_OPTIONS structure -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `TRACING_SESSION_OPTIONS` structure is used when initializing an [ANALYSIS_DESCRIPTOR](analysis-descriptor-struct.md) or [RELOG_DESCRIPTOR](relog-descriptor-struct.md) structure. It describes which events to capture during the collection of a trace. @@ -28,7 +29,7 @@ typedef struct TRACING_SESSION_OPTIONS_TAG ## Members -| | | +| Name | Description | |--|--| | `SystemEventFlags` | A bitmask describing the system events to capture. For more information, see [TRACING_SESSION_SYSTEM_EVENT_FLAGS](tracing-session-system-event-flags-constants.md). | | `MsvcEventFlags` | A bitmask describing the MSVC events to capture. For more information, see [TRACING_SESSION_MSVC_EVENT_FLAGS](tracing-session-msvc-event-flags-constants.md). | 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 03e1ca20cb..80b32daa9d 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 @@ -1,17 +1,18 @@ --- title: "TRACING_SESSION_STATISTICS structure" -description: "The C++ Build Insights SDK TRACING_SESSION_OPTIONS structure reference." +description: "Learn about the C++ Build Insights SDK TRACING_SESSION_STATISTICS structure reference." ms.date: "02/12/2020" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TRACING_SESSION_STATISTICS", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference --- # TRACING_SESSION_STATISTICS structure -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `TRACING_SESSION_STATISTICS` structure describes statistics on a trace that was collected. Its fields are set when stopping a tracing session. @@ -30,7 +31,7 @@ typedef struct TRACING_SESSION_STATISTICS_TAG ## Members -| | | +| Name | Description | |--|--| | `MSVCEventsLost` | The number of MSVC events that were dropped. | | `MSVCBuffersLost` | The number of MSVC event buffers that were dropped. | 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 a8f2f78265..129d27038f 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 @@ -3,15 +3,16 @@ title: "TRACING_SESSION_SYSTEM_EVENT_FLAGS constants" description: "The C++ Build Insights SDK TRACING_SESSION_SYSTEM_EVENT_FLAGS constants reference." ms.date: "02/12/2020" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TRACING_SESSION_SYSTEM_EVENT_FLAGS", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference --- # TRACING_SESSION_SYSTEM_EVENT_FLAGS constants -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The `TRACING_SESSION_SYSTEM_EVENT_FLAGS` constants are used to describe which system events to collect during a trace. Use them to initialize the [TRACING_SESSION_OPTIONS](tracing-session-options-struct.md) structure's `SystemEventFlags` field. diff --git a/docs/build-insights/reference/sdk/overview.md b/docs/build-insights/reference/sdk/overview.md index bb9f1f7f00..483b547d4f 100644 --- a/docs/build-insights/reference/sdk/overview.md +++ b/docs/build-insights/reference/sdk/overview.md @@ -6,12 +6,12 @@ helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Analyzing --- # C++ Build Insights SDK -::: moniker range="<=vs-2015" +::: 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=">=vs-2017" +::: moniker range=">=msvc-150" The C++ Build Insights SDK is a collection of APIs that allow you to create personalized tools on top of the C++ Build Insights platform. This page provides a high-level overview to help you get started. @@ -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 @@ -186,7 +186,7 @@ Whenever the C++ Build Insights SDK gives you an event, it comes in the form of The C++ Build Insights SDK gives you every event in a trace, but most of the time you only care about a subset of them. In some cases, you may only care about a subset of *event stacks*. The SDK provides facilities to help you quickly extract the events or event stack you need, and reject the ones you don't. It's done through these matching functions: -| | | +| Function | Description | |--|--| | [MatchEvent](functions/match-event.md) | Keep an event if it matches one of the specified types. Forward matched events to a lambda or other callable type. The event's parent hierarchy isn't considered by this function. | | [MatchEventInMemberFunction](functions/match-event-in-member-function.md) | Keep an event if it matches the type specified in a member function's parameter. Forward matched events to the member function. The event's parent hierarchy isn't considered by this function. | diff --git a/docs/build-insights/reference/vcperf-commands.md b/docs/build-insights/reference/vcperf-commands.md index 8fdce294f5..ed8342bf1b 100644 --- a/docs/build-insights/reference/vcperf-commands.md +++ b/docs/build-insights/reference/vcperf-commands.md @@ -6,39 +6,40 @@ helpviewer_keywords: ["C++ Build Insights", "throughput analysis", "build time a --- # Reference: vcperf commands -::: moniker range="<=vs-2017" +::: 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="vs-2019" +::: 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](/cpp/build-insights/get-started-with-cpp-build-insights). 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](/cpp/build-insights/get-started-with-cpp-build-insights). | +| `/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 -[Get started with C++ Build Insights](/cpp/build-insights/get-started-with-cpp-build-insights)\ -[Tutorial: Windows Performance Analyzer basics](/cpp/build-insights/tutorials/wpa-basics)\ +[Get started with C++ Build Insights](../get-started-with-cpp-build-insights.md)\ +[Tutorial: Windows Performance Analyzer basics](../tutorials/wpa-basics.md)\ [Reference: Windows Performance Analyzer views](wpa-views.md)\ [Windows Performance Analyzer](/windows-hardware/test/wpt/windows-performance-analyzer) diff --git a/docs/build-insights/reference/wpa-views.md b/docs/build-insights/reference/wpa-views.md index bc30bb4ae5..a7c5391f5c 100644 --- a/docs/build-insights/reference/wpa-views.md +++ b/docs/build-insights/reference/wpa-views.md @@ -6,19 +6,19 @@ helpviewer_keywords: ["C++ Build Insights", "throughput analysis", "build time a --- # Reference: Windows Performance Analyzer views -::: moniker range="<=vs-2017" +::: 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="vs-2019" +::: 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: - data column descriptions; and - available presets for each view, including their intended use and preferred viewing mode. -If you're new to WPA, we recommend that you first familiarize yourself with the [basics of WPA for C++ Build Insights](/cpp/build-insights/tutorials/wpa-basics). +If you're new to WPA, we recommend that you first familiarize yourself with the [basics of WPA for C++ Build Insights](../tutorials/wpa-basics.md). ## Build Explorer @@ -120,9 +120,9 @@ The Functions view is used to identify functions with an excessively long code g ## See also -[Get started with C++ Build Insights](/cpp/build-insights/get-started-with-cpp-build-insights)\ +[Get started with C++ Build Insights](../get-started-with-cpp-build-insights.md)\ [Reference: vcperf commands](vcperf-commands.md)\ -[Tutorial: Windows Performance Analyzer basics](/cpp/build-insights/tutorials/wpa-basics)\ +[Tutorial: Windows Performance Analyzer basics](../tutorials/wpa-basics.md)\ [Windows Performance Analyzer](/windows-hardware/test/wpt/windows-performance-analyzer) ::: moniker-end diff --git a/docs/build-insights/toc.yml b/docs/build-insights/toc.yml index f571b06818..d5f07030b9 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,14 @@ - name: "Tutorials" expanded: true items: + - name: "Troubleshoot function inlining impact on build time" + href: ../build-insights/tutorials/build-insights-function-view.md + - name: "Troubleshoot template instantiation impact on build time" + href: ../build-insights/tutorials/build-insights-template-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 +132,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 +150,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 +164,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 +184,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 +226,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..bd0ccd9e31 --- /dev/null +++ b/docs/build-insights/tutorials/build-insights-function-view.md @@ -0,0 +1,152 @@ +--- +title: "Troubleshoot function inlining impact 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"] +ms.topic: troubleshooting-general +--- +# Troubleshoot function inlining impact 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 doesn'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::: + +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 executes 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 + +- Use **File** > **Save As** to save the ETL file to a more permanent location to keep a record of the build time information. You can then compare it to future builds to see how your changes are improving things. +- If you 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..0b68665351 --- /dev/null +++ b/docs/build-insights/tutorials/build-insights-included-files-view.md @@ -0,0 +1,189 @@ +--- +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"] +ms.topic: how-to +--- +# 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) diff --git a/docs/build-insights/tutorials/build-insights-template-view.md b/docs/build-insights/tutorials/build-insights-template-view.md new file mode 100644 index 0000000000..47382cff0b --- /dev/null +++ b/docs/build-insights/tutorials/build-insights-template-view.md @@ -0,0 +1,235 @@ +--- +title: "Troubleshoot template instantiation impact on build time" +description: "Tutorial for how to use Build Insights template view to analyze and optimize the impact of template instantiations on build time in your C++ projects." +ms.date: 07/17/2025 +helpviewer_keywords: ["C++ Build Insights", "template instantiation analysis", "build time analysis"] +ms.topic: troubleshooting-general +ai-usage: ai-assisted +--- + +# Troubleshoot template instantiation impact on build time + +Use the Build Insights **Templates** view to see how template instantiation affects C++ build time. It's especially helpful for projects that use lots of templates, like those with template metaprogramming or large generic libraries. + +The **Templates** view works like the Build Insights [Functions view](build-insights-function-view.md). + +## Prerequisites + +- Visual Studio 2022 version 17.10 or later. +- The **C++ Build Insights** component must be installed. Either the Desktop development with C++ workload or the Game development with C++ workload includes it. To check if it's installed, follow these steps: + 1. Open the Visual Studio Installer. + 1. Select **Modify** to change your Visual Studio installation. + 1. On the **Individual components** tab, search for and select **C++ Build Insights**, then select **Close** to finish installing the component. + :::image type="content" source="./media/installer-build-insights.png" alt-text="Screenshot of the Visual Studio Installer. The search box contains C++ Build Insights. The item C++ Build Insights is visible and selected."::: + +## Overview + +Build Insights, integrated into Visual Studio, helps you optimize your build times--especially for large projects like AAA games. Build Insights provides analytics such as the **Templates** view, which shows the time it takes to instantiate each template and which template instantiations add the most to your build time. + +In general, C++ template instantiation happens quickly. In rare cases, some template instantiations can noticeably slow down your build. + +In this article, you create a project that shows how template instantiation affects build time, run Build Insights to analyze the impact, and use those insights to make the build faster. + +## Create a test project + +1. Open Visual Studio and create a new **C++ Console App** project. Name it `TemplateAnalysis`. +1. Create a header file named `Templates.h`, then replace its contents with the following code: + + ```cpp + #pragma once + + #include + #include + + template struct S1 {}; + template using type = std::vector>; + + template struct S2 {}; + + template struct S3 {}; + + template + struct S3> + { + using type = S2)...>; + }; + + inline size_t LargeValue() + { + return sizeof(S3>); + } + + inline size_t SmallValue() + { + return sizeof(S1<5>); + } + ``` + +1. Create a source file named `LargeValue.cpp`, then replace its contents with the following code: + + ```cpp + #include "Templates.h" + + size_t GetLargeValue() + { + return LargeValue(); + } + ``` + +1. Replace the contents of the `TemplateAnalysis.cpp` file with the following code: + + ```cpp + #include "Templates.h" + + extern size_t GetLargeValue(); + + size_t GetSmallValue() + { + return SmallValue(); + } + + int main() + { + size_t largeValue = GetLargeValue(); + size_t smallValue = GetSmallValue(); + return 0; + } + ``` + +## Enable build time data collection + +Template instantiation time collection is off by default to minimize build overhead. To turn it on: + +1. In Visual Studio, go to **Tools** > **Options**. +1. In the **Options** dialog, expand **Build Insights** in the left navigation. +1. Select **Collect Template Instantiation**. +1. To choose where to save the report, select **Store Build Insights reports in this directory** and enter a directory. By default, it's saved in the folder pointed to by the Windows `TEMP` environment variable. +1. Select **OK**. + +:::image type="content" source="./media/tools-options-build-insights.png" alt-text="Screenshot of the project property pages dialog. The settings are open to Build Insights > Trace Collection. The Collect Template Instantiation checkbox is selected."::: + +> [!NOTE] +> Collecting template instantiation times increases build time due to the extra data collected. Only enable it when you want to analyze template instantiation bottlenecks. + +## Run Build Insights to get template instantiation data + +From the main menu, select **Build** > **Run Build Insights on Solution** > **Rebuild**. You can also right-click a project in Solution Explorer and select **Run Build Insights** > **Rebuild**. Choose **Rebuild** instead of **Build** to measure the build time for the entire project. + +:::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. The file name is based on the collection time. + +## Use Templates view to optimize build time + +The **Templates** view lists the template instantiations that contributed significantly to build time. The columns provide information about: + +- **Time [sec, %]** shows how long it takes to instantiate each template 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 template instantiations based on their use of parallel compiler threads. +- **Specialization Name** shows each template instantiation, including the template arguments used. This helps you find which template specializations are most expensive. +- **Translation Unit** shows the source files where each template instantiation happens. Different files can cause the same template instantiation if they include the same header with the template definition. +- **Instantiation File Name** shows where the template is defined. + +:::image type="complex" source="./media/templates-view-before-fix.png" alt-text="Screenshot of the Build Insights Templates view showing expensive template instantiations." lightbox="./media/templates-view-before-fix.png"::: +The Templates view shows two template instantiations of struct S3 taking most (79.448 percent) of the build time. The Translation Unit column shows that both LargeValue.cpp and TemplateAnalysis.cpp are affected. The build time is 4.966 seconds. +:::image-end::: + +- Sort by **Time** to find the templates that take the longest to instantiate. +- Expand a template to see its instantiations and where they happened. +- Use the search box to focus on specific templates. + +### Understanding Templates view results + +To interpret the **Templates** view results: + +- **Empty view**: If nothing shows up in the **Templates** view, template instantiations don't dominate your build time. That's good news because your templates aren't a build bottleneck. +- **Duplicate instantiations**: If the same template instantiation appears multiple times across different translation units, different source files are causing the same expensive instantiation. This is often the biggest optimization opportunity. +- **Threshold filtering**: The view only shows instantiations whose contribution exceeds a certain threshold, so you can focus on the most impactful ones and avoid noise from trivial instantiations. +- **Time aggregation**: The time shown is the total time spent on that specific template instantiation, including any nested instantiations. + +## Improve build time by optimizing template instantiations + +In the example, two template instantiations of `S3` take 79 percent of the build time. The **Translation Unit** column shows that both `LargeValue.cpp` and `TemplateAnalysis.cpp` cause this template instantiation. + +The **Instantiation File Name** and the **Specialization Name** are the same for both entries, which means one expensive template instantiation that affects both source files. That's why the time for each of the two template instantiations is roughly equal. Including `Templates.h` in both source files causes one template instantiation to add significant time to the build. + +From the **Specialization Name** column, the expensive instantiation is `S3>`, which is instantiated in this code in `Templates.h`: + +```cpp +inline size_t LargeValue() +{ + return sizeof(S3>); +} +``` + +There are three main ways to decrease the cost of template instantiations. + +### Remove unused templates + +Check if the expensive template is used. If it isn't, the easiest solution is to remove the function or template. In the example, `LargeValue()` is used in `LargeValue.cpp`, so you can't remove it. + +Consider removing include directives that bring in unnecessary template instantiations. It's easy to forget to remove header files when you aren't using them, and unused includes can significantly affect build time. + +### Move template instantiations to source files + +In this example, rely on the third approach: move the definition that causes the expensive template instantiation to a source file. + +Because `LargeValue.cpp` is the only source file that calls `LargeValue()`, move the definition to `LargeValue.cpp`. This change prevents the template instantiation from happening in every file that includes `Templates.h`. Remove the current definition of `LargeValue()` from `Templates.h` and replace it with a declaration: + +```cpp +size_t LargeValue(); +``` + +Inside `LargeValue.cpp` add the definition: + +```cpp +size_t LargeValue() +{ + return sizeof(S3>); +} +``` + +Rebuild the project and run Build Insights again from the main menu. Select **Build** > **Run Build Insights on Selection** > **Rebuild**. + +The build time decreases. While the template instantiation of `S3` still contributes to the build time, including only necessary template instantiations cuts the build time nearly in half. The count of `S3` instantiations is now one instead of two. + +:::image type="complex" source="./media/templates-view-after-fix.png" alt-text="Screenshot of the Build Insights Templates view after optimization. The view shows reduced template instantiation time." lightbox="./media/templates-view-after-fix.png"::: +The Templates view now shows only one instantiation of S3 instead of two, and the total build time is significantly less at 3.152 seconds. +:::image-end::: + +This technique works well for larger projects. If multiple files include `Templates.h`, each file adds the instantiation time of `LargeValue()` to the total build time. By moving the definition of `LargeValue()` to a dedicated source file, you minimize build time. + +### Optimize the template implementation + +Other optimization techniques include: + +- Use simpler template patterns +- Use `if constexpr` instead of Substitution Failure Is Not An Error (SFINAE) when possible +- Avoid recursive template instantiation patterns that lead to exponential growth + +For more advanced template optimization techniques, see [Build Throughput Series: More Efficient Template Metaprogramming](https://devblogs.microsoft.com/cppblog/build-throughput-series-more-efficient-template-metaprogramming/), which provides detailed examples of reducing template instantiation overhead. + +## Tips + +- Use **File** > **Save As** to save the ETL file to a more permanent location to keep a record of the build time information. You can then compare it to future builds to see how your changes are improving things. +- If you close the Build Insights window, reopen it by finding the *dateandtime*.etl file either where you specified it should be saved, or in your temporary folder. The `TEMP` Windows environment variable provides the path of your temporary files folder. +- Drag columns to change the order of the columns. For example, you might want to move the **Wall Time Responsibility** column to the first column. You can add or hide columns by right-clicking the column header and selecting or deselecting the columns you want. +- The **Templates** view has a filter box to help you find a specific template instantiation. It does partial matches on the name you provide. + +## Troubleshooting + +**Templates view is empty**: This can mean: + +- Your build time isn't dominated by template instantiations. +- Template data collection isn't enabled. To turn it on, see [Enable build time data collection](#enable-build-time-data-collection). +- Do a rebuild instead of a build. The Build Insights window doesn't appear if nothing builds, which can be the case if no files changed since the last build. +- Make sure you're using Visual Studio 2022 17.10 or later, and that the C++ Build Insights component is installed. + +**Build is much slower with Templates view enabled:** This is expected because of the extra data collection. Turn off template instantiation collection when you don't need it. For more information, see [Enable build time data collection](#enable-build-time-data-collection). + +## See also + +- [Build Insights tips and tricks](build-insights-tips.md) +- [#include cleanup in Visual Studio](https://devblogs.microsoft.com/cppblog/include-cleanup-in-visual-studio) +- [Troubleshoot header file impact on build time](build-insights-included-files-view.md) +- [Troubleshoot function inlining on build time](build-insights-function-view.md) +- [Build Insights now available in Visual Studio 2022](https://devblogs.microsoft.com/cppblog/build-insights-now-available-in-visual-studio-2022) +- [Build throughput series: More efficient template metaprogramming](https://devblogs.microsoft.com/cppblog/build-throughput-series-more-efficient-template-metaprogramming) 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..fcd96f050e 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-build-insights.png b/docs/build-insights/tutorials/media/installer-build-insights.png new file mode 100644 index 0000000000..55e1ec52cf Binary files /dev/null and b/docs/build-insights/tutorials/media/installer-build-insights.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/media/templates-view-after-fix.png b/docs/build-insights/tutorials/media/templates-view-after-fix.png new file mode 100644 index 0000000000..7acc1cf276 Binary files /dev/null and b/docs/build-insights/tutorials/media/templates-view-after-fix.png differ diff --git a/docs/build-insights/tutorials/media/templates-view-before-fix.png b/docs/build-insights/tutorials/media/templates-view-before-fix.png new file mode 100644 index 0000000000..22bd3ba5fd Binary files /dev/null and b/docs/build-insights/tutorials/media/templates-view-before-fix.png differ diff --git a/docs/build-insights/tutorials/media/tools-options-build-insights.png b/docs/build-insights/tutorials/media/tools-options-build-insights.png new file mode 100644 index 0000000000..b0317d247d Binary files /dev/null and b/docs/build-insights/tutorials/media/tools-options-build-insights.png differ diff --git a/docs/build-insights/tutorials/vcperf-and-wpa.md b/docs/build-insights/tutorials/vcperf-and-wpa.md index e70895a2ff..0b8b278a8a 100644 --- a/docs/build-insights/tutorials/vcperf-and-wpa.md +++ b/docs/build-insights/tutorials/vcperf-and-wpa.md @@ -3,49 +3,51 @@ title: "Tutorial: vcperf and Windows Performance Analyzer" description: "Tutorial on how to use vcperf and WPA for analyzing C++ build traces." ms.date: "11/03/2019" helpviewer_keywords: ["C++ Build Insights", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: tutorial --- # Tutorial: vcperf and Windows Performance Analyzer -::: moniker range="<=vs-2017" +::: 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="vs-2019" +::: 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 NOTE: Windows 8 or above is required for installing the Windows Performance Analyzer. -1. Browse to the Windows ADK [download page](https://docs.microsoft.com/windows-hardware/get-started/adk-install). +1. Browse to the Windows ADK [download page](/windows-hardware/get-started/adk-install). 1. Download and install the latest version of the Windows ADK. 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 +58,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 +77,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 +106,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. @@ -113,10 +115,10 @@ Other views are available in the Graph Explorer panel. Drag them into the Analys [Tutorial: Windows Performance Analyzer basics](wpa-basics.md)\ Learn about common WPA operations that can help you analyze your build traces. -[Reference: vcperf commands](/cpp/build-insights/reference/vcperf-commands)\ +[Reference: vcperf commands](../reference/vcperf-commands.md)\ The *vcperf.exe* command reference lists all the available command options. -[Reference: Windows Performance Analyzer views](/cpp/build-insights/reference/wpa-views)\ +[Reference: Windows Performance Analyzer views](../reference/wpa-views.md)\ Refer to this article for details about the C++ Build Insights views in WPA. [Windows Performance Analyzer](/windows-hardware/test/wpt/windows-performance-analyzer)\ diff --git a/docs/build-insights/tutorials/wpa-basics.md b/docs/build-insights/tutorials/wpa-basics.md index ad7bf03e37..35ad6fe727 100644 --- a/docs/build-insights/tutorials/wpa-basics.md +++ b/docs/build-insights/tutorials/wpa-basics.md @@ -3,15 +3,16 @@ title: "Tutorial: Windows Performance Analyzer basics" description: "Tutorial on how to complete basic operations in Windows Performance Analyzer." ms.date: "11/03/2019" helpviewer_keywords: ["C++ Build Insights", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: tutorial --- # Tutorial: Windows Performance Analyzer basics -::: moniker range="<=vs-2017" +::: 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="vs-2019" +::: 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. @@ -36,7 +37,7 @@ Most C++ Build Insights WPA views have multiple presets for you to choose from. Some build traces are so large it's hard to make out the details. To zoom in on an area that interests you, right-click on the graph and select **Zoom**. You can always go back to the previous setting by choosing **Undo Zoom**. This image shows an example of using a selection and the **Zoom** command to zoom in on a section of the graph: -![Zooming in on a graph.](media/wpa-zooming.gif) +![Short video showing zooming in on a graph.](media/wpa-zooming.gif) ## Group by different columns @@ -44,13 +45,13 @@ You can customize the way your trace is displayed. Click on the gear icon at the This image shows an example bar graph of a link invocation. We use the gear icon to open the Build Explorer View Editor dialog. Then we drag the Component and Name column entries above the yellow line. The configuration is changed to increase the level of detail, and to see what actually happened inside the linker: -![Zooming in on a graph.](media/wpa-grouping.gif) +![Short video showing showing how you can group by different columns.](media/wpa-grouping.gif) ## See also [Tutorial: vcperf and Windows Performance Analyzer](vcperf-and-wpa.md)\ -[Reference: vcperf commands](/cpp/build-insights/reference/vcperf-commands)\ -[Reference: Windows Performance Analyzer views](/cpp/build-insights/reference/wpa-views)\ +[Reference: vcperf commands](../reference/vcperf-commands.md)\ +[Reference: Windows Performance Analyzer views](../reference/wpa-views.md)\ [Windows Performance Analyzer](/windows-hardware/test/wpt/windows-performance-analyzer) ::: moniker-end diff --git a/docs/build/active-technology-and-dlls.md b/docs/build/active-technology-and-dlls.md index 7d40107beb..9361cb0c6d 100644 --- a/docs/build/active-technology-and-dlls.md +++ b/docs/build/active-technology-and-dlls.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Active Technology and DLLs" title: "Active Technology and DLLs" ms.date: "11/04/2016" helpviewer_keywords: ["in-process server DLLs", "Automation [C++], DLLs", "DLLs [C++], Active Technology", "Active technology [C++]", "MFC DLLs [C++], Active Technology"] diff --git a/docs/build/adding-references-in-visual-cpp-projects.md b/docs/build/adding-references-in-visual-cpp-projects.md index 45d42bae87..41de401156 100644 --- a/docs/build/adding-references-in-visual-cpp-projects.md +++ b/docs/build/adding-references-in-visual-cpp-projects.md @@ -1,55 +1,60 @@ --- +description: "Learn more about: Consuming libraries and components" title: "Consuming libraries and components in C++ projects" -ms.date: "12/10/2018" +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 +ms.topic: how-to --- # Consuming libraries and components -Often, a C++ project needs to call functions or access data in a binary file such as static library (.lib files), DLL, Windows Runtime component, COM component, or .NET assembly. In these cases, you have to configure the project so that it can find that binary at build time. The specific steps depend on the type of your project, the type of the binary, and whether the binary is being built in the same solution as your project. +C++ projects often need to call functions or access data in a binary file such as static library (LIB files), DLL, Windows Runtime component, COM component, or .NET assembly. In these cases, you have to configure the project so that it can find that binary at build time. The specific steps depend on the type of your project, the type of the binary, and whether the binary gets built in the same solution as your project. ## 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: A C++ package manager for Windows, Linux and MacOS](vcpkg.md#integrate-with-visual-studio-windows) 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 is being built in the same solution: +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 will start 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 is not part of the solution: +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 where the .lib file is located in **Library Paths** and add the path to the library header file(s) in **Include Directories**. -3. In the **Linker > Input** property page, add the name of the .lib file to **Additional Dependencies**. +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 -If the DLL is being built as part of the same solution as the application, follow the same steps as for a static library. +If the DLL gets built as part of the same solution as the application, follow the same steps as for a static library. -If the DLL is not 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. +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). -2. Follow steps 1-3 for static libraries to provide the paths to the headers and .lib file. +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 -If your native C++ application needs to consume a COM object, and that object is *registered*, then all you have to do is call CoCreateInstance and pass in the CLSID of the object. The system will find it in the Windows Registry and load it. A C++/CLI project can consume a COM object in the same way, or by adding a reference to it from the **Add References > COM** list and consuming it through its [Runtime callable wrapper](/dotnet/framework/interop/runtime-callable-wrapper). +If your native C++ application needs to consume a COM object, and that object is *registered*, then all you have to do is call CoCreateInstance and pass in the CLSID of the object. The system will find it in the Windows Registry and load it. A C++/CLI project can consume a COM object in the same way. Or, it can consume it by adding a reference to it from the **Add References > COM** list and consuming it through its [Runtime callable wrapper](/dotnet/framework/interop/runtime-callable-wrapper). ## .NET assemblies and Windows Runtime Components -In UWP or C++/CLI projects, you consume .NET assemblies or Windows Runtime Components by adding a *reference* to the assembly or component. Under the **References** node in a UWP or C++/CLI project, you see references to commonly-used components. Right-click on the **References** node in **Solution Explorer** to bring up the **Reference Manager** and browse through additional components that are known to the system. Click the **Browse** button to navigate to any folder where a custom component is located. Because .NET assemblies and Windows Runtime components contain built-in type information, you can view their methods and classes by right-clicking and choosing **View in Object Browser**. +In UWP or C++/CLI projects, you consume .NET assemblies or Windows Runtime Components by adding a *reference* to the assembly or component. Under the **References** node in a UWP or C++/CLI project, you see references to commonly used components. Right-click on the **References** node in **Solution Explorer** to bring up the **Reference Manager** and browse through the components available on the system. Choose the **Browse** button to navigate to any folder that contains a custom component. Because .NET assemblies and Windows Runtime components contain built-in type information, you can view their methods and classes by right-clicking and choosing **View in Object Browser**. ## Reference properties -Each kind of reference has properties. You can view the properties by selecting the reference in Solution Explorer and pressing **Alt + Enter**, or else right-clicking and choosing **Properties**. Some properties are read-only and some can be modified. However, typically you don't have to manually modify these properties. +Each kind of reference has properties. You can view the properties by selecting the reference in Solution Explorer and pressing **Alt + Enter**, or else right-clicking and choosing **Properties**. Some properties are read-only and some are modifiable. However, typically you don't have to manually modify these properties. ### ActiveX reference properties -ActiveX reference properties are available only for references to COM components. These properties are displayed only when a COM component is selected in the **References** pane. The properties cannot be modified. +ActiveX reference properties are available only for references to COM components. These properties get displayed only when you select a COM component in the **References** pane. The properties aren't modifiable. - **Control Full Path** @@ -69,11 +74,11 @@ ActiveX reference properties are available only for references to COM components - **Wrapper Tool** - Displays the tool that is used to build the interop assembly from the referenced COM library or ActiveX control. + Displays the tool that's used to build the interop assembly from the referenced COM library or ActiveX control. ### Assembly reference properties (C++/CLI) -Assembly reference properties are available only for references to .NET Framework assemblies in C++/CLI projects. These properties are displayed only when a .NET Framework assembly is selected in the **References** pane. The properties cannot be modified. +Assembly reference properties are available only for references to .NET Framework assemblies in C++/CLI projects. These properties get displayed only when you select a .NET Framework assembly in the **References** pane. The properties aren't modifiable. - **Relative Path** @@ -93,27 +98,27 @@ The following properties are available on various kinds of references. They enab - **Reference Assembly Output** - Specifies that this assembly is used in the build process. If **`true`**, the assembly is used on the compiler command line during the build. + Specifies that this assembly gets used in the build process. If **`true`**, the assembly gets used on the compiler command line during the build. ### Project-to-project reference properties -The following properties define a *project-to-project reference* from the project that is selected in the **References** pane to another project in the same solution. For more information, see [Managing references in a project](/visualstudio/ide/managing-references-in-a-project). +The following properties define a *project-to-project reference* from the project that's selected in the **References** pane to another project in the same solution. For more information, see [Managing references in a project](/visualstudio/ide/managing-references-in-a-project). - **Link Library Dependencies** - When this property is **True**, the project system links into the dependent project the .lib files that are produced by the independent project. Typically, you will specify **True**. + When this property is **True**, the project system links the LIB files that the independent project produces into the dependent project. Typically, you'll specify **True**. - **Project Identifier** - Uniquely identifies the independent project. The property value is an internal system GUID that cannot be modified. + Uniquely identifies the independent project. The property value is an internal system GUID that isn't modifiable. - **Use Library Dependency Inputs** - When this property is **False**, the project system will not link into the dependent project the .obj files for the library produced by the independent project. Consequently, this value disables incremental linking. Typically, you will specify **False** because building the application can take a long time if there are many independent projects. + When this property is **False**, the project system won't link the OBJ files for the library that the independent project produces into the dependent project. That's why this value disables incremental linking. Typically, you'll specify **False** because building the application can take a long time if there are many independent projects. ### Read-only reference properties (COM & .NET) -The following properties are found on COM and .NET assembly references, and cannot be modified. +The following properties exist on COM and .NET assembly references, and aren't modifiable. - **Assembly Name** @@ -133,7 +138,7 @@ The following properties are found on COM and .NET assembly references, and cann - **Identity** - For the .NET Frameworkassemblies, displays the full path. For COM components, displays the GUID. + For the .NET Framework assemblies, displays the full path. For COM components, displays the GUID. - **Label** @@ -145,11 +150,11 @@ The following properties are found on COM and .NET assembly references, and cann - **Public Key Token** - Displays the public key token that is used to identify the referenced assembly. + Displays the public key token used to identify the referenced assembly. - **Strong Name** - **`true`** if the referenced assembly has a strong name. A strong named assembly is uniquely versioned. + **`true`** if the referenced assembly has a strong name. A strong named assembly has a unique version. - **Version** @@ -157,5 +162,5 @@ The following properties are found on COM and .NET assembly references, and cann ## 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 04bfb762ac..b7cc353313 100644 --- a/docs/build/arm-exception-handling.md +++ b/docs/build/arm-exception-handling.md @@ -1,33 +1,34 @@ --- title: "ARM Exception Handling" -ms.date: "07/11/2018" -ms.assetid: fe0e615f-c033-4ad5-97f4-ff96af45b201 +description: "Learn more about: ARM Exception Handling" +ms.date: 12/15/2021 +ms.topic: concept-article --- # 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 -Executable images for Windows on ARM use the Portable Executable (PE) format. For more information, see [Microsoft PE and COFF Specification](https://go.microsoft.com/fwlink/p/?linkid=84140). Exception handling information is stored in the .pdata and .xdata sections of the image. +Executable images for Windows on ARM use the Portable Executable (PE) format. For more information, see [PE Format](/windows/win32/debug/pe-format). Exception handling information is stored in the `.pdata` and `.xdata` sections of the image. 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. @@ -45,133 +46,133 @@ The exception handling mechanism makes certain assumptions about code that follo - Parse one of a few well-defined frame types. -### .pdata Records +### `.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: +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: |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 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 low two bits implicitly 0). If *Flag* is non-zero, then the remaining bits form a *Packed Unwind Data* structure.| -|1|2-31|*Exception Information RVA* or *Packed Unwind Data*.

*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 required to unwind from a function, assuming a canonical form. In this case, no .xdata record is required.| +|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 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 low two bits implicitly 0). If *`Flag`* is non-zero, then the remaining bits form a *Packed Unwind Data* structure.| +|1|2-31|*Exception Information RVA* or *Packed Unwind Data*.

*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 required to unwind from a function, assuming a canonical form. In this case, no `.xdata` record is required.| ### 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: +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: +- 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. + - 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. -- If the *Ret* field is set to 0, the *L* flag must be set to 1. +- If the *`Ret`* field is set to 0, the *`L`* flag must be set to 1. Violating these restrictions causes an unsupported sequence. -For purposes of the discussion below, two pseudo-flags are derived from *Stack Adjust*: +For purposes of the discussion below, two pseudo-flags are derived from *`Stack Adjust`*: -- *PF* or "prologue folding" indicates that *Stack Adjust* is 0x3F4 or larger and bit 2 is set. +- *`PF`* or "prologue folding" indicates that *`Stack Adjust`* is 0x3F4 or larger and bit 2 is set. -- *EF* or "epilogue folding" indicates that *Stack Adjust* is 0x3F4 or larger and bit 3 is set. +- *`EF`* or "epilogue folding" indicates that *`Stack Adjust`* is 0x3F4 or larger and bit 3 is set. 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. +Instruction 1 is always present if the *`H`* bit is set to 1. -To set up the frame chaining, either instruction 3a or 3b is present if the *C* bit is set. It is a 16-bit `mov` if no registers other than r11 and LR are pushed; otherwise, it is a 32-bit `add`. +To set up the frame chaining, either instruction 3a or 3b is present if the *`C`* bit is set. It is a 16-bit `mov` if no registers other than r11 and LR are pushed; otherwise, it is a 32-bit `add`. If a non-folded adjustment is specified, instruction 5 is the explicit stack adjustment. -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*| +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 | (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. +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 +### `.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 that has four sections: +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 that has four sections: -1. A 1 or 2-word header that describes the overall size of the .xdata structure and provides key function data. The second word is only present if the *Epilogue Count* and *Code Words* fields are both set to 0. The fields are broken out in this table: +1. A 1 or 2-word header that describes the overall size of the `.xdata` structure and provides key function data. The second word is only present if the *Epilogue Count* and *Code Words* fields are both set to 0. The fields are broken out in this table: |Word|Bits|Purpose| |----------|----------|-------------| - |0|0-17|*Function Length* is an 18-bit field that indicates the total length of the function in bytes, divided by 2. If a function is larger than 512 KB, then multiple .pdata and .xdata records must be used to describe the function. For details, see the Large Functions section in this document.| - |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|0-17|*`Function Length`* is an 18-bit field that indicates the total length of the function in bytes, divided by 2. If a function is larger than 512 KB, then multiple `.pdata` and `.xdata` records must be used to describe the function. For details, see the Large Functions section in this document.| + |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|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'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.| |1|24-31|Reserved| -1. After the exception data (if the *E* bit in the header was set to 0) is a list of information about epilogue scopes, which are packed one to a word and stored in order of increasing starting offset. Each scope contains these fields: +1. After the exception data (if the *`E`* bit in the header was set to 0) is a list of information about epilogue scopes, which are packed one to a word and stored in order of increasing starting offset. Each scope contains these fields: |Bits|Purpose| |----------|-------------| @@ -184,13 +185,13 @@ When the packed unwind format is insufficient to describe the unwinding of a fun 1. If the *X* field in the header is 1, the unwind code bytes are followed by the exception handler information. This consists of one *Exception Handler RVA* that contains the address of the exception handler, followed immediately by the (variable-length) amount of data required by the exception handler. -The .xdata record is designed so that it is possible to fetch the first 8 bytes and compute the full size of the record, not including the length of the variable-sized exception data that follows. This code snippet computes the record size: +The `.xdata` record is designed so that it is possible to fetch the first 8 bytes and compute the full size of the record, not including the length of the variable-sized exception data that follows. This code snippet computes the record size: ```cpp -ULONG ComputeXdataSize(PULONG *Xdata) +ULONG ComputeXdataSize(PULONG Xdata) { - ULONG EpilogueScopes; ULONG Size; + ULONG EpilogueScopes; ULONG UnwindWords; if ((Xdata[0] >> 23) != 0) { @@ -206,15 +207,18 @@ ULONG ComputeXdataSize(PULONG *Xdata) if (!(Xdata[0] & (1 << 21))) { Size += 4 * EpilogueScopes; } + Size += 4 * UnwindWords; + if (Xdata[0] & (1 << 20)) { - Size += 4; + Size += 4; // Exception handler RVA } + return Size; } ``` -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 @@ -230,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. @@ -296,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. @@ -304,41 +308,41 @@ 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 -For code optimization, it may be useful to split a function into discontiguous parts. When this is done, each function fragment requires its own separate .pdata—and possibly .xdata—record. +For code optimization, it may be useful to split a function into discontiguous parts. When this is done, each function fragment requires its own separate `.pdata`—and possibly `.xdata`—record. Assuming that the function prologue is at the beginning of the function and can't be split, there are four function fragment cases: - 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. +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 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. +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. +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 @@ -354,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 @@ -380,25 +384,25 @@ 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 -Due to 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 quite minimal. +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 is data—for example, a literal pool—that follows an epilogue in a function, it should not be included as part of the function length. By shrinking the function to just the code that is 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 is 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 do not 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 do not 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, and 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 do not 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 re-use 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 and use any perfect match as a starting point for re-use. +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. -If, after single-instruction epilogues are ignored, there are no remaining epilogues, consider using a compact .pdata form; it becomes much more likely in the absence of an epilogue. +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. ## Examples @@ -414,29 +418,29 @@ Epilogue: 00453658: 4770 bx lr ``` -.pdata (fixed, 2 words): +`.pdata` (fixed, 2 words): - Word 0 - - *Function Start RVA* = 0x000535F8 (= 0x004535F8-0x00400000) + - *`Function Start RVA`* = 0x000535F8 (= 0x004535F8-0x00400000) - Word 1 - - *Flag* = 1, indicating canonical prologue and epilogue formats + - *`Flag`* = 1, indicating canonical prologue and epilogue formats - - *Function Length* = 0x31 (= 0x62/2) + - *`Function Length`* = 0x31 (= 0x62/2) - - *Ret* = 1, indicating a 16-bit branch return + - *`Ret`* = 1, indicating a 16-bit branch return - - *H* = 0, indicating the parameters were not homed + - *`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 + - *`L`* = 0, indicating no LR save/restore - - *C* = 0, indicating no frame chaining + - *`C`* = 0, indicating no frame chaining - - *Stack Adjust* = 0, indicating no stack adjustment + - *`Stack Adjust`* = 0, indicating no stack adjustment ### Example 2: Nested Function with Local Allocation @@ -449,29 +453,29 @@ Epilogue: 00453414: BDF0 pop {r4-r7, pc} ``` -.pdata (fixed, 2 words): +`.pdata` (fixed, 2 words): - Word 0 - - *Function Start RVA* = 0x000533AC (= 0x004533AC -0x00400000) + - *`Function Start RVA`* = 0x000533AC (= 0x004533AC -0x00400000) - Word 1 - - *Flag* = 1, indicating canonical prologue and epilogue formats + - *`Flag`* = 1, indicating canonical prologue and epilogue formats - - *Function Length* = 0x35 (= 0x6A/2) + - *`Function Length`* = 0x35 (= 0x6A/2) - - *Ret* = 0, indicating a pop {pc} return + - *`Ret`* = 0, indicating a pop {pc} return - - *H* = 0, indicating the parameters were not homed + - *`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 + - *`L`* = 1, indicating LR was saved/restored - - *C* = 0, indicating no frame chaining + - *`C`* = 0, indicating no frame chaining - - *Stack Adjust* = 3 (= 0x0C/4) + - *`Stack Adjust`* = 3 (= 0x0C/4) ### Example 3: Nested Variadic Function @@ -484,29 +488,29 @@ Epilogue: 004539D8: F85D FB14 ldr pc, [sp], #0x14 ``` -.pdata (fixed, 2 words): +`.pdata` (fixed, 2 words): - Word 0 - - *Function Start RVA* = 0x00053988 (= 0x00453988-0x00400000) + - *`Function Start RVA`* = 0x00053988 (= 0x00453988-0x00400000) - Word 1 - - *Flag* = 1, indicating canonical prologue and epilogue formats + - *`Flag`* = 1, indicating canonical prologue and epilogue formats - - *Function Length* = 0x2A (= 0x54/2) + - *`Function Length`* = 0x2A (= 0x54/2) - - *Ret* = 0, indicating a pop {pc}-style return (in this case an ldr pc,[sp],#0x14 return) + - *`Ret`* = 0, indicating a pop {pc}-style return (in this case an `ldr pc,[sp],#0x14` return) - - *H* = 1, indicating the parameters were homed + - *`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 + - *`L`* = 1, indicating LR was saved/restored - - *C* = 0, indicating no frame chaining + - *`C`* = 0, indicating no frame chaining - - *Stack Adjust* = 0, indicating no stack adjustment + - *`Stack Adjust`* = 0, indicating no stack adjustment ### Example 4: Function with Multiple Epilogues @@ -530,35 +534,35 @@ Epilogues: 00459636: F028 FF0F bl KeBugCheckEx ; end of function ``` -.pdata (fixed, 2 words): +`.pdata` (fixed, 2 words): - Word 0 - - *Function Start RVA* = 0x000592F4 (= 0x004592F4-0x00400000) + - *`Function Start RVA`* = 0x000592F4 (= 0x004592F4-0x00400000) - Word 1 - - *Flag* = 0, indicating .xdata record present (required due to multiple epilogues) + - *`Flag`* = 0, indicating `.xdata` record present (required for multiple epilogues) - - *.xdata address* - 0x00400000 + - *`.xdata` address* - 0x00400000 -.xdata (variable, 6 words): +`.xdata` (variable, 6 words): - Word 0 - - *Function Length* = 0x0001A3 (= 0x000346/2) + - *`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 + - *`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). @@ -590,35 +594,35 @@ Epilogue: 00485E2A: F7FF BE7D b #0x485B28 ; end of function ``` -.pdata (fixed, 2 words): +`.pdata` (fixed, 2 words): - Word 0 - - *Function Start RVA* = 0x00085A20 (= 0x00485A20-0x00400000) + - *`Function Start RVA`* = 0x00085A20 (= 0x00485A20-0x00400000) - Word 1 - - *Flag* = 0, indicating .xdata record present (needed due to multiple epilogues) + - *`Flag`* = 0, indicating `.xdata` record present (needed for multiple epilogues) - - *.xdata address* - 0x00400000 + - *`.xdata` address* - 0x00400000 -.xdata (variable, 3 words): +`.xdata` (variable, 3 words): - Word 0 - - *Function Length* = 0x0001A3 (= 0x000346/2) + - *`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 + - *`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) @@ -648,35 +652,35 @@ Epilogue: 00488C70: BD90 pop {r4, r7, pc} ``` -.pdata (fixed, 2 words): +`.pdata` (fixed, 2 words): - Word 0 - - *Function Start RVA* = 0x00088C24 (= 0x00488C24-0x00400000) + - *`Function Start RVA`* = 0x00088C24 (= 0x00488C24-0x00400000) - Word 1 - - *Flag* = 0, indicating .xdata record present (needed due to multiple epilogues) + - *`Flag`* = 0, indicating `.xdata` record present (needed for multiple epilogues) - - *.xdata address* - 0x00400000 + - *`.xdata` address* - 0x00400000 -.xdata (variable, 5 words): +`.xdata` (variable, 5 words): - Word 0 - - *Function Length* =0x000027 (= 0x00004E/2) + - *`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 + - *`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: @@ -688,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 @@ -707,29 +711,29 @@ Function: 00488C86: BD00 pop {pc} ``` -.pdata (fixed, 2 words): +`.pdata` (fixed, 2 words): - Word 0 - - *Function Start RVA* = 0x00088C72 (= 0x00488C72-0x00400000) + - *`Function Start RVA`* = 0x00088C72 (= 0x00488C72-0x00400000) - Word 1 - - *Flag* = 1, indicating canonical prologue and epilogue formats + - *`Flag`* = 1, indicating canonical prologue and epilogue formats - - *Function Length* = 0x0B (= 0x16/2) + - *`Function Length`* = 0x0B (= 0x16/2) - - *Ret* = 0, indicating a pop {pc} return + - *`Ret`* = 0, indicating a pop {pc} return - - *H* = 0, indicating the parameters were not homed + - *`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 + - *`L`* = 1, indicating LR was saved/restored - - *C* = 0, indicating no frame chaining + - *`C`* = 0, indicating no frame chaining - - *Stack Adjust* = 1, indicating a 1 × 4 byte stack adjustment + - *`Stack Adjust`* = 1, indicating a 1 × 4 byte stack adjustment ## See also diff --git a/docs/build/arm64-exception-handling.md b/docs/build/arm64-exception-handling.md index eb2a10798b..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,158 +230,184 @@ 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) +ULONG ComputeXdataSize(PULONG Xdata) { - ULONG EpilogScopes; ULONG Size; + ULONG EpilogScopes; ULONG UnwindWords; - if ((Xdata[0] >> 27) != 0) { + if ((Xdata[0] >> 22) != 0) { Size = 4; EpilogScopes = (Xdata[0] >> 22) & 0x1f; - UnwindWords = (Xdata[0] >> 27) & 0x0f; + UnwindWords = (Xdata[0] >> 27) & 0x1f; } else { Size = 8; EpilogScopes = Xdata[1] & 0xffff; UnwindWords = (Xdata[1] >> 16) & 0xff; } - Size += 4 * EpilogScopes; + if (!(Xdata[0] & (1 << 21))) { + Size += 4 * EpilogScopes; + } + Size += 4 * UnwindWords; + if (Xdata[0] & (1 << 20)) { - Size += 4; // exception handler RVA + Size += 4; // Exception handler RVA } + return Size; } ``` -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. @@ -400,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. @@ -422,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 @@ -463,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. @@ -510,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 @@ -533,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| @@ -619,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 e94a4bdb12..db01bfefe2 100644 --- a/docs/build/arm64-windows-abi-conventions.md +++ b/docs/build/arm64-windows-abi-conventions.md @@ -1,14 +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. @@ -18,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: @@ -29,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. @@ -65,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. @@ -86,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. | @@ -119,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 @@ -149,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. @@ -159,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. @@ -197,19 +201,26 @@ Integral values are returned in x0. Floating-point values are returned in s0, d0, or v0, as appropriate. -HFA and HVA values are returned in s0-s3, d0-d3, or v0-v3, 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 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. + +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. Types which have all of these properties, +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, - they're *aggregate* by the C++14 standard definition, that is, they have no user-provided constructors, no private or protected non-static data members, no base classes, and no virtual functions, and - they have a trivial copy-assignment operator, and - they have a trivial destructor, -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: @@ -217,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 @@ -235,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. @@ -245,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/automation-in-a-dll.md b/docs/build/automation-in-a-dll.md index 4fa660617f..14bfcd95d7 100644 --- a/docs/build/automation-in-a-dll.md +++ b/docs/build/automation-in-a-dll.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Automation in a DLL" title: "Automation in a DLL" ms.date: "11/04/2016" helpviewer_keywords: ["DLLs [C++], Automation", "Automation [C++], DLLs"] diff --git a/docs/build/building-c-cpp-isolated-applications-and-side-by-side-assemblies.md b/docs/build/building-c-cpp-isolated-applications-and-side-by-side-assemblies.md index e51803d42c..01183ef989 100644 --- a/docs/build/building-c-cpp-isolated-applications-and-side-by-side-assemblies.md +++ b/docs/build/building-c-cpp-isolated-applications-and-side-by-side-assemblies.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Building C/C++ Isolated Applications and Side-by-side Assemblies" title: "Building C/C++ Isolated Applications and Side-by-side Assemblies" ms.date: "05/06/2019" helpviewer_keywords: ["isolated applications [C++]", "WinSxS [C++]", "native assembly cache [C++]", "builds [C++], isolated applications", "side-by-side applications [C++]", "builds [C++], side-by-side assemblies"] ms.assetid: 9465904e-76f7-48bd-bb3f-c55d8f1699b6 +ms.topic: concept-article --- # Building C/C++ Isolated Applications and Side-by-side Assemblies diff --git a/docs/build/building-c-cpp-isolated-applications.md b/docs/build/building-c-cpp-isolated-applications.md index 40d2243d86..8724e842f8 100644 --- a/docs/build/building-c-cpp-isolated-applications.md +++ b/docs/build/building-c-cpp-isolated-applications.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Building C/C++ Isolated Applications" title: "Building C/C++ Isolated Applications" ms.date: "05/06/2019" helpviewer_keywords: ["isolated applications [C++]"] ms.assetid: 8a2fe4fa-0489-433e-bfc6-495844d8d73a +ms.topic: concept-article --- # Building C/C++ Isolated Applications diff --git a/docs/build/building-c-cpp-side-by-side-assemblies.md b/docs/build/building-c-cpp-side-by-side-assemblies.md index 3febae312d..29478d8b6e 100644 --- a/docs/build/building-c-cpp-side-by-side-assemblies.md +++ b/docs/build/building-c-cpp-side-by-side-assemblies.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Building C/C++ Side-by-side Assemblies" title: "Building C/C++ Side-by-side Assemblies" ms.date: "11/04/2016" helpviewer_keywords: ["side-by-side applications [C++]"] ms.assetid: 7fa20b16-3737-4f76-a0b5-1dacea19a1e8 +ms.topic: concept-article --- # Building C/C++ Side-by-side Assemblies diff --git a/docs/build/building-on-the-command-line.md b/docs/build/building-on-the-command-line.md index 66b0224dd1..7b4a452f29 100644 --- a/docs/build/building-on-the-command-line.md +++ b/docs/build/building-on-the-command-line.md @@ -2,34 +2,50 @@ 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 +ms.topic: how-to --- # Use the Microsoft C++ toolset from the command line 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 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. +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. -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 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 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. +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. + +## 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. @@ -37,121 +53,134 @@ The command prompt shortcuts are installed in a version-specific Visual Studio f - **x86_x64 Cross Tools Command Prompt** - Sets the environment to use 32-bit, x86-native tools to build 64-bit, x64-native code. - **x64_x86 Cross Tools Command Prompt** - Sets the environment to use 64-bit, x64-native tools to build 32-bit, x86-native code. -::: moniker range=">= vs-2019" +::: 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="= vs-2017" +::: 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**. ::: moniker-end -::: moniker range="< vs-2017" +::: moniker range="< msvc-150" The Start menu folder and shortcut names vary depending on the installed version of Visual Studio. For example, suppose you installed Visual Studio 2015. The developer command prompt shortcut is named **Developer Command Prompt for VS 2015**. ::: 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=">= vs-2019" +::: moniker range=">= msvc-170" + +The command file location depends on the version of Visual Studio you installed, and on choices you made during installation. For Visual Studio 2019, the typical installation location on a 64-bit system is in *`\Program Files\Microsoft Visual Studio\2022\`*. 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\\*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 (x86)\Microsoft Visual Studio\2019\`*. The *``* may be Community, Professional, Enterprise, BuildTools, or another nickname you supplied. ::: moniker-end -::: moniker range="= vs-2017" +::: 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="< vs-2017" +::: 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=">= vs-2017" +::: moniker range=">= msvc-150" More command files are available to set up specific build architectures. The command files available depend on the Visual Studio workloads and options you've installed. In Visual Studio 2017 and Visual Studio 2019, you'll find them in the VC\\Auxiliary\\Build subdirectory. ::: moniker-end -::: moniker range="< vs-2017" +::: moniker range="< msvc-150" More command files are available to set up specific build architectures. The command files available depend on the Visual Studio workloads and options you've installed. In Visual Studio 2015, they're located in the VC, VC\\bin, or VC\\bin\\*architecture* subdirectories, where *architecture* is one of the native or cross-compiler options. ::: 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=">= vs-2019" +::: 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="= vs-2017" +::: moniker range="= msvc-150" Use **-vcvars_ver=14.16** to specify the latest version of the Visual Studio 2017 compiler toolset. @@ -161,6 +190,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. @@ -171,21 +203,21 @@ Use **-vcvars_ver=14.0** to specify the Visual Studio 2015 compiler toolset. ## Create your own command prompt shortcut -::: moniker range=">= vs-2019" +::: moniker range=">= msvc-160" Open the Properties dialog for a developer command prompt shortcut to see the command target used. For example, the target for the **x64 Native Tools Command Prompt for VS 2019** shortcut is something similar to: `%comspec% /k "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat"` ::: moniker-end -::: moniker range="= vs-2017" +::: moniker range="= msvc-150" Open the Properties dialog for a developer command prompt shortcut to see the command target used. For example, the target for the **x64 Native Tools Command Prompt for VS 2017** shortcut is something similar to: `%comspec% /k "C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvars64.bat"` ::: moniker-end -::: moniker range="< vs-2017" +::: moniker range="< msvc-150" Open the Properties dialog for a developer command prompt shortcut to see the command target used. For example, the target for the **VS2015 x64 Native Tools Command Prompt** shortcut is something similar to: @@ -193,21 +225,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=">= vs-2019" +::: 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="= vs-2017" +::: 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="< vs-2017" +::: 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 +249,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](https://docs.microsoft.com/cpp/), 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 +292,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/calling-dll-functions-from-visual-basic-applications.md b/docs/build/calling-dll-functions-from-visual-basic-applications.md index baaf170905..38bcce3a90 100644 --- a/docs/build/calling-dll-functions-from-visual-basic-applications.md +++ b/docs/build/calling-dll-functions-from-visual-basic-applications.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Calling DLL Functions from Visual Basic Applications" title: "Calling DLL Functions from Visual Basic Applications" ms.date: "11/04/2016" helpviewer_keywords: ["functions [C++], calling DLL functions from Visual Basic", "DLL functions [C++]", "function calls [C++], DLL functions", "DLLs [C++], calling", "calling DLL functions from VB applications [C++]", "__stdcall keyword [C++]", "DLL functions [C++], calling"] ms.assetid: 282f7fbf-a0f2-4b9f-b277-1982710be56c +ms.topic: concept-article --- # Calling DLL Functions from Visual Basic Applications diff --git a/docs/build/checking-for-memory-overwrites.md b/docs/build/checking-for-memory-overwrites.md index 62799a88a5..5c8869aca1 100644 --- a/docs/build/checking-for-memory-overwrites.md +++ b/docs/build/checking-for-memory-overwrites.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Checking for Memory Overwrites" title: "Checking for Memory Overwrites" ms.date: "11/04/2016" helpviewer_keywords: ["memory, overwrites"] ms.assetid: da7c5d77-a267-415f-a8ab-ee5ce5bfc286 +ms.topic: concept-article --- # Checking for Memory Overwrites diff --git a/docs/build/clang-support-cmake.md b/docs/build/clang-support-cmake.md index 84069fcb8b..157c3259d9 100644 --- a/docs/build/clang-support-cmake.md +++ b/docs/build/clang-support-cmake.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Clang/LLVM support in Visual Studio CMake projects" title: "Clang/LLVM support in Visual Studio CMake projects" ms.date: "07/01/2019" ms.description: "Configure a CMake project in Visual Studio to use the Clang/LLVM toolchain." @@ -6,25 +7,37 @@ helpviewer_keywords: ["Clang support for C++ CMake projects"] --- # Clang/LLVM support in Visual Studio CMake projects -::: moniker range="<=vs-2017" +::: 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="vs-2019" +::: 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. -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. +![Screenshot of the Visual Studio Installer Individual Components page that shows Clang components available for installation.](media/clang-install-vs2019.png) + +::: 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 @@ -34,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). @@ -50,7 +63,7 @@ To modify an existing configuration to use Clang, follow these steps: 1. Under **General** select the **Toolset** dropdown and choose the desired Clang toolset: - ![CMake Clang toolset](media/cmake-clang-toolset.png) + ![Screenshot of the General dialog box showing that the Toolset is selected and clang cl x 86 is highlighted.](media/cmake-clang-toolset.png) ## Custom Clang locations @@ -61,7 +74,7 @@ By default, Visual Studio looks for Clang in two places: You can specify another location by setting the **CMAKE_C_COMPILER** and **CMAKE_CXX_COMPILER** CMake variables in **CMake Settings**: -![CMake Clang toolset](media/clang-location-cmake.png) +![Screenshot of the C Make Settings dialog box with the C Make C X X Compiler highlighted.](media/clang-location-cmake.png) ## Clang compatibility modes @@ -71,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 1a36c26d99..6e44fbb42a 100644 --- a/docs/build/clang-support-msbuild.md +++ b/docs/build/clang-support-msbuild.md @@ -1,36 +1,65 @@ --- -title: "Clang/LLVM support in Visual Studio Visual Studio projects" -ms.date: "06/02/2020" +title: "Clang/LLVM support in Visual Studio projects" +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"] --- # Clang/LLVM support in Visual Studio projects -::: moniker range="<=vs-2017" +::: 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="vs-2019" +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. -You can use Visual Studio 2019 version 16.2 with Clang to edit, build, and debug C++ Visual Studio projects (MSBuild) that target Windows or Linux. +::: moniker-end + +::: 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 those, you can install them by opening the Visual Studio Installer and choosing **C++ Clang tools for Windows** under **Desktop development with C++** optional components. If you prefer to use an existing Clang installation on your machine, choose the **C++ Clang-cl for v142 build tools.** optional component. The Microsoft C++ Standard Library currently requires at least Clang 8.0.0; the bundled version of Clang will automatically be updated to stay current with updates in the Microsoft implementation of the Standard Library. +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 -![Clang component installation](media/clang-install-vs2019.png) +::: moniker range=">=msvc-160" +The Microsoft C++ Standard Library requires at least Clang 8.0.0. +::: moniker-end + +::: 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::: + +::: 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**. -![Clang component installation](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 are using the Clang tools that are bundled with Visual Studio, no additional 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 and 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 are 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. See [Set a custom LLVM location](#custom_llvm_location) for more information. +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 @@ -40,31 +69,54 @@ 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 are using Windows Subsystem for Linux, or **Remote_Clang_1_0** if you are 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**. -![Clang component installation](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 encounters in the PATH environment property. If you are using a custom Clang installation, then you must change the value of the `LLVMInstallDir` property or else substitute a path under **Project** > **Properties** > **VC++ DIrectories** > **Configuration Properties** > **Executable Directories**. See [Set a custom LLVM location](#custom_llvm_location) for more information. +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 for LLVM for one or more projects by creating a *Directory.build.props* file and adding 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 substitute your actual 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 + C:\MyLLVMRootDir + 15.0.0 ``` -## Set additional properties, edit, build, and debug +## Set a custom LLVM toolset version in the IDE + +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: + +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. Choose **Apply** to save your changes. + +1. Select the **Configuration Properties** > **Advanced** property page. + +1. Modify the **LLVM Toolset Version** property to your preferred version, and then choose **OK** to save your changes. + +The **LLVM Toolset Version** property only appears when the LLVM platform toolset is selected. + +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 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 are 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 very similar to those for MSVC, although some compiler-dependent features such as Edit and Continue are not available for Clang configurations. To set a Clang compiler or linker option that is not available in the property pages, you can add it manually in the property pages under **Configuration Properties** > **C/C++ (or Linker)** > **Command Line** > **Additional Options**. +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 ffa7bd878c..d9597573d8 100644 --- a/docs/build/cmake-predefined-configuration-reference.md +++ b/docs/build/cmake-predefined-configuration-reference.md @@ -1,20 +1,21 @@ --- +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 -::: moniker range="vs-2015" +::: moniker range="msvc-140" CMake projects are supported in Visual Studio 2017 and later. ::: moniker-end -::: moniker range=">=vs-2017" +::: 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 @@ -27,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: @@ -59,7 +60,7 @@ When you choose a configuration, it is added to the *CMakeSettings.json* file in "inheritEnvironments": [ "linux_x64" ] - } +} { "name": "Linux-Release", @@ -88,9 +89,8 @@ When you choose a configuration, it is added to the *CMakeSettings.json* file in "inheritEnvironments": [ "linux_x64" ] - }, - ``` - +}, +``` You can use these optional settings for more control: @@ -347,9 +347,9 @@ These options allow you to run commands on the remote system before and after bu ::: moniker-end -::: moniker range="vs-2019" +::: 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 @@ -373,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 new file mode 100644 index 0000000000..07b08b79e8 --- /dev/null +++ b/docs/build/cmake-presets-json-reference.md @@ -0,0 +1,118 @@ +--- +description: "Schema reference for `CMakePresets.json` and `CMakeUserPresets.json` Microsoft vendor maps" +title: "CMakeUserPresets.json" +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. + +*`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`* 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 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`*. + +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 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`. | +| `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. 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 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. + +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`*. + +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. 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 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`*. + +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](./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: + +```json +{ + "taskLabel": "mkdir", + "appliesTo": "CMakeLists.txt", + "type": "remote", + "command": "mkdir test", + "remoteMachineName": "localhost" + } +``` + +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. 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. + +|Macro |Description | +|---------|---------| +|`$ms{projectDirName}`| Evaluates to the name of the open folder in Visual Studio. This macro is used to set the default value of `sourceDir` in remote copy scenarios. This macro is not supported by Visual Studio Code. Use `${sourceDirName}` instead. | + +## Environment variables + +|Macro |Description | +|---------|---------| +| `$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`*. + +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` | + +## Accepted shell syntax + +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 new file mode 100644 index 0000000000..87d3fd7146 --- /dev/null +++ b/docs/build/cmake-presets-vs.md @@ -0,0 +1,493 @@ +--- +title: Configure and build with CMake Presets +description: "Reference for using CMake Presets to configure and build CMake projects." +ms.date: 06/09/2023 +ms.topic: reference +ms.custom: sfi-image-nochange +--- + +# 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. + +*`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: + +- 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/blob/main/docs/cmake-presets.md). + +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 + +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. + +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). + +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. + +We recommend using at least CMake version 3.14 or later. + +## Enable *`CMakePresets.json`* integration in Visual Studio + +*`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. + +In some older versions of Visual Studio, **Tools** > **Options** > **CMake** > **General** only has a single option to enable *`CMakePresets.json`* integration: + +:::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`* | + +## Modify automatic configuration and cache notifications + +By default, Visual Studio automatically invokes `configure` each time the active Target System or Configure Preset changes. You can modify this behavior by selecting **Never run configure step automatically** in **Tools** > **Options** > **CMake** > **General**. You can also disable all CMake cache notifications (gold bars) by clearing **Show CMake cache notifications**. + +## 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 + +```json +{ + "name": "windows-default", + "displayName": "Windows x64 Debug", + "description": "Sets Ninja generator, compilers, x64 architecture, build and install directory, debug build type", + "generator": "Ninja", + "binaryDir": "${sourceDir}/out/build/${presetName}", + "architecture": { + "value": "x64", + "strategy": "external" + }, + "cacheVariables": { + "CMAKE_BUILD_TYPE": "Debug", + "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}" + }, + "vendor": { + "microsoft.com/VisualStudioSettings/CMake/1.0": { + "hostOS": [ "Windows" ] + } + } +}, +``` + +### Linux example + +```json +{ + "name": "linux-default", + "displayName": "Linux Debug", + "description": "Sets Ninja generator, compilers, build and install directory, debug build type", + "generator": "Ninja", + "binaryDir": "${sourceDir}/out/build/${presetName}", + "cacheVariables": { + "CMAKE_BUILD_TYPE": "Debug", + "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}" + }, + "vendor": { + "microsoft.com/VisualStudioSettings/CMake/1.0": { + "hostOS": [ "Linux" ] + }, + "microsoft.com/VisualStudioRemoteSettings/CMake/1.0": { + "sourceDir": "$env{HOME}/.vs/$ms{projectDirName}" + } + } +} +``` + +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 + +On the Visual Studio toolbar, there are dropdowns for the Target Systems, Configure Presets, and Build Presets when *`CMakePresets.json`* integration is enabled: + +:::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: + +:::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: + +- **192.168.0.5** is a remote Linux system that was added to Connection Manager. +- **ubuntu2004** and **debian** are WSL installations. + +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`*. + +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 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`*. + +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 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. + +To disable automatic cache generation, see [Automatic configuration and cache notifications](#modify-automatic-configuration-and-cache-notifications). + +### Build + +To build the entire project, select **Build** > **Build All** from the main menu. It's the same as running `cmake --build --preset ` from the command line, where `` is the name of the active Build Preset. + +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`*. + +## Run CTest + +*`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`*. + +## 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`*. + +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 Configuration** from the shortcut menu. The dialog to select a Configure Preset template appears: + +:::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). + +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). + +## Edit presets + +The official [CMake documentation](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#id1) is the best resource for editing Configure Presets, Build Presets, and Test Presets. The following information is a subset of the CMake documentation that's especially relevant to Visual Studio developers. + +### Select your compilers + +You can set C and C++ compilers by using `cacheVariables.CMAKE_C_COMPILER` and `cacheVariables.CMAKE_CXX_COMPILER` in a Configure Preset. It's equivalent to passing `-D CMAKE_C_COMPILER=` and `-D CMAKE_CXX_COMPILER=` to CMake from the command line. For more information, see [`CMAKE__COMPILER`](https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_COMPILER.html#cmake-lang-compiler). + +Use the following examples to build with `cl.exe` and `clang-cl.exe` from Visual Studio. The C++ Clang tools for Windows components must be installed for you to build with `clang-cl`. + +Build with `cl.exe`: + +```json +"cacheVariables": { + "CMAKE_BUILD_TYPE": "Debug", + "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}", + "CMAKE_C_COMPILER": "cl", + "CMAKE_CXX_COMPILER": "cl" +}, +``` + +Build with `clang`: + +```json +"cacheVariables": { + "CMAKE_BUILD_TYPE": "Debug", + "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}", + "CMAKE_C_COMPILER": "clang-cl", + "CMAKE_CXX_COMPILER": "clang-cl" +}, + +"vendor": { + "microsoft.com/VisualStudioSettings/CMake/1.0": { + "intelliSenseMode": "windows-clang-x64" + } +} +``` + +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`. + +To reproduce these builds outside Visual Studio, see [Run CMake from the command line or a CI pipeline](#run-cmake-from-the-command-line-or-a-ci-pipeline). + +To build on Linux or without the Visual C++ toolset, specify the name of a compiler on your `PATH` instance, or an environment variable that evaluates to the full path of a compiler. Full paths are discouraged so that the file can remain shareable. A preset that builds with GCC version 8 might look like this: + +```json +"cacheVariables": { + "CMAKE_BUILD_TYPE": "Debug", + "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}", + "CMAKE_C_COMPILER": "gcc-8", + "CMAKE_CXX_COMPILER": "g++-8" +}, +``` + +You can also set compilers with a CMake toolchain file. Toolchain files can be set with `cacheVariables.CMAKE_TOOLCHAIN_FILE`, which is equivalent to passing `-D CMAKE_TOOLCHAIN_FILE=` to CMake from the command line. A CMake toolchain file is most often used for cross-compilation. For more information about authoring CMake toolchain files, see [CMake toolchains](https://cmake.org/cmake/help/latest/manual/cmake-toolchains.7.html). + +### Select your generator + +The Windows and Linux Configure Preset templates both specify Ninja as the default generator. Other common generators are the [Visual Studio Generators](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html?highlight=visual%20studio%20generators#visual-studio-generators) on Windows and Unix Makefiles on Linux and macOS. You can specify a new generator with the `generator` option in a Configure Preset. It's equivalent to passing `-G` to CMake from the command line. + +Set `architecture.strategy` and `toolset.strategy` to `set` when you're building with a Visual Studio Generator. For more information, see [CMake generators](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#:~:text=A%20CMake%20Generator%20is%20responsible%20for%20writing%20the,what%20native%20build%20system%20is%20to%20be%20used). + +### Select your configuration type + +You can set the configuration type (`Debug` or `Release`) for single configuration generators by using `cacheVariables.CMAKE_BUILD_TYPE`. It's equivalent to passing `-D CMAKE_BUILD_TYPE=` to CMake from the command line. For more information, see [`CMAKE_BUILD_TYPE`](https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html). + +### Select your target and host architecture when building with the Visual C++ toolset + +You can set the target architecture (x64, Win32, ARM64, or ARM) by using `architecture.value`. It's equivalent to passing `-A` to CMake from the command line. For more information, see [Platform Selection](https://cmake.org/cmake/help/latest/generator/Visual%20Studio%2016%202019.html#platform-selection). + +> [!NOTE] +> Currently, Visual Studio Generators expect the Win32 syntax and command-line generators (like Ninja) expect the x86 syntax when you're building for x86. + +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 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). + +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). + +Use the following examples to target ARM64 with the Ninja generator, or to target Win32 (x86) with the Visual Studio 16 2019 generator: + +```json +"generator": "Ninja", +"architecture": { + "strategy": "external", + "value": "arm64" +}, + +"generator": "Visual Studio 16 2019", +"architecture": { + "strategy": "set", + "value": "Win32" +}, +``` + +### 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. + +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). + +You can reference environment variables by using the `$env{}` and `$penv{}` syntax. For more information, see [Macro Expansion](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#macro-expansion). + +### Configure IntelliSense for a cross-compiler + +By default, Visual Studio uses the IntelliSense mode that matches your specified toolset and target architecture. If you're cross-compiling, you might need to manually specify the correct IntelliSense mode by using the `intelliSenseMode` option in the Visual Studio Settings vendor map. For more information, see the entry for `intelliSenseMode` in the table under [Visual Studio Settings vendor map](cmake-presets-json-reference.md#visual-studio-settings-vendor-map). + +## 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. + +### `${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. + +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). + +### Local folder for remote output + +Remote copy scenarios require a local directory to copy some remote files like CMake File API response files or build files if `copyBuildOutput` in the Visual Studio Remote Settings vendor map is set to `true`. These files are automatically copied to `/out//build/${presetName}`. + +### 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. + +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: + +```json +{ + "name": "windows-preset", + "inherits": "base-preset", + "binaryDir": "${sourceDir}/out/build/${presetName}", + "vendor": { + "microsoft.com/VisualStudioSettings/CMake/1.0": { + "hostOS": "Windows" + } + } +} +``` + +> [!NOTE] +> In Visual Studio 2019, only the WSL1 toolset is supported. You'll see this behavior any time you invoke `configure` on both Windows and WSL. + +## Enable vcpkg integration + +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. + +Instead, set the path to `vcpkg.cmake` by using the `VCPKG_ROOT` environment variable in *`CMakePresets.json`*: + +```json +"cacheVariables": { + "CMAKE_TOOLCHAIN_FILE": { + "value": "$env{VCPKG_ROOT}/scripts/buildsystems/vcpkg.cmake", + "type": "FILEPATH" + } + }, +``` + +`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](/vcpkg/users/buildsystems/cmake-integration#using-multiple-toolchain-files). Follow those instructions to use an external toolchain file with a project by using vcpkg. + +## 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: + +- 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. + +- 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. + +## 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. + +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: + +```cmd +CMake Error: Could not read presets from +C:/Users//source/repos/: JSON parse error +``` + +Other troubleshooting steps include: + +- Delete the cache and reconfigure the project (**CMake: Delete Cache** and **Project** > **Configure \**). +- Close and reopen the folder in Visual Studio (**File** > **Close Folder**). +- Delete the `.vs` folder at the root your project. + +If you've identified a problem, the best way to report it is by selecting the **Send Feedback** button in the upper-right corner of Visual Studio. + +## 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](../linux/connect-to-your-remote-linux-computer.md#logging-for-remote-connections). + +## Enable AddressSanitizer for Windows and Linux + +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. + +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) + +if(ASAN_ENABLED) + if(MSVC) + target_compile_options( PUBLIC /fsanitize=address) + else() + target_compile_options( PUBLIC -fsanitize=address ) + target_link_options( PUBLIC -fsanitize=address) + endif() +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 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. + +## 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. + +### 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](./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. + +*`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: + +```cmd +/path/to/vcvarsall.bat x64_arm64 +cmake --list-presets=all . +cmake --preset +cmake --build --preset +``` + +## Example *`CMakePresets.json`* file + +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 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 c763a87c1d..b56efcce7e 100644 --- a/docs/build/cmake-projects-in-visual-studio.md +++ b/docs/build/cmake-projects-in-visual-studio.md @@ -1,266 +1,403 @@ --- 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"] +ms.custom: sfi-image-nochange --- # CMake projects in Visual Studio -CMake is a cross-platform, open-source tool for defining build processes that run on multiple platforms. This article assumes you're familiar with CMake. You can learn more about it at [Build, Test and Package Your Software With CMake](https://cmake.org/). +[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="vs-2019" +::: 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. -![CMake component in C++ Desktop workload](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](vcpkg.md), 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="vs-2017" +::: 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. -![CMake component in C++ Desktop workload](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,33 +411,35 @@ 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 -::: moniker range="vs-2015" +::: moniker range="msvc-140" In Visual Studio 2015, Visual Studio users can use a [CMake generator](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html) to generate MSBuild project files, which the IDE then consumes for IntelliSense, browsing, and compilation. ::: 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 new file mode 100644 index 0000000000..41645840b3 --- /dev/null +++ b/docs/build/cmake-remote-debugging.md @@ -0,0 +1,186 @@ +--- +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 +--- + +# 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. 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. 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: + +> [!div class="checklist"] +> +> * create a CMake project +> * configure a CMake project to build for ARM64 +> * configure a CMake project to run on a remote ARM64 Windows machine +> * debug a CMake project running on a remote ARM64 Windows machine + +## Prerequisites + +### 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 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**. +1. From the choices at the top, choose **Individual components**. +1. Scroll down to the **Compilers, build tools, and runtimes** section. +1. Ensure that the following are selected: + - **C++ CMake tools for Windows** + - **MSVC v142 - VS 2019 C++ ARM64 build tools (Latest)** It's important that you choose the `ARM64` build tools and not the `ARM` build tools (look for the 64) and that you choose the version that goes with `VS 2019`. +1. Select **Modify** to install the tools. + +### On the remote machine + +1. Install the remote tools on the remote machine. For this tutorial, install the ARM64 tools by following the instructions in [Download and Install the remote tools](/visualstudio/debugger/remote-debugging-cpp#download-and-install-the-remote-tools). +1. Start and configure the remote debugger on the remote machine. For this tutorial, do so by following the directions in [set up the remote debugger](/visualstudio/debugger/remote-debugging-cpp#BKMK_setup) on the remote Windows machine. + +## 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** +1. Give the project a name and choose a location. Then select **Create**. + +Give Visual Studio a few moments to create the project and populate the **Solution Explorer**. + +## Configure for ARM64 + +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) + +Add a new configuration by selecting **Add a new configuration** (the green **+** button).\ +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) + +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 is set to **msvc_arm64_x64**. Your settings should now look like this: + +![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'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): + +![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 + +Next, add configuration information that tells Visual Studio where to find your remote machine, along with other configuration details. + +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) + +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) + +This command creates a *`launch.vs.json`* file in your project. Open it and change the following entries to enable remote debugging: + +- `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). + +> [!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: +> +> - 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`*'. + +## Start the remote debugger monitor on the remote Windows machine + +Before you run your CMake project, ensure that the Visual Studio 2019 remote debugger is running on the remote Windows machine. You may need to change the remote debugger options depending on your authentication situation. + +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) + +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 +{ + "version": "0.2.1", + "defaults": {}, + "configurations": [ + { + "type": "remoteWindows", + "authenticationType": "none" + "name": "CMakeLists.txt", + "project": "CMakeLists.txt", + "projectTarget": "CMakeProject3.exe", + "remoteMachineName": "", + "cwd": "${debugInfo.defaultWorkingDirectory}", + "program": "${debugInfo.fullTargetPath}", + "deploy": [], + "args": [], + "env": {} + }, + { + "type": "default", + "project": "CMakeLists.txt", + "projectTarget": "CMakeProject3.exe", + "name": "CMakeProject3.exe" + } + ] +} +``` + +## Debug the app + +On the host machine, in the Visual Studio **Solution Explorer**, open the CPP file for your CMake project. If you're still in **CMake Targets View**, you'll need to open the **(executable)** node to see it. + +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: + +![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: + +- `"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'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) + +Visual Studio on the host machine should be stopped at the breakpoint for `return 0;`. + +## What you learned + +In this tutorial, you created a CMake project, configured it to build for Windows on ARM64, and debugged it on a remote ARM64 Windows machine. + +## 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 predefined configuration reference](cmake-predefined-configuration-reference.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 7b0a50f01e..e9a6acdb8f 100644 --- a/docs/build/cmakesettings-reference.md +++ b/docs/build/cmakesettings-reference.md @@ -1,127 +1,128 @@ --- +description: "Learn more about: CMakeSettings.json schema reference" title: "CMakeSettings.json schema reference" 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="vs-2015" +::: moniker range="msvc-140" CMake projects are supported in Visual Studio 2017 and later. ::: moniker-end -::: moniker range=">=vs-2017" +::: 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 Address Sanitizer (Experimental on Windows). On Linux, compile with -fno-omit-frame-pointer and compiler optimization level -Os or -Oo for best results. -- `addressSanitizerRuntimeFlags`: runtime flags passed to AddressSanitizer 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": [ @@ -138,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": [ { @@ -224,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}". } ], @@ -251,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 -? @@ -273,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-problems-when-creating-a-release-build.md b/docs/build/common-problems-when-creating-a-release-build.md index 0329179c05..b0c6111231 100644 --- a/docs/build/common-problems-when-creating-a-release-build.md +++ b/docs/build/common-problems-when-creating-a-release-build.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Common Problems When Creating a Release Build" title: "Common Problems When Creating a Release Build" ms.date: "11/04/2016" helpviewer_keywords: ["unexpected code generation", "debugging [MFC], release builds", "release builds, troubleshooting", "stray pointers", "debug builds, difference from release builds", "MFC [C++], release builds", "heap layout problems", "pointers, stray", "release builds, building applications", "debug memory allocator", "optimization [C++], compiler", "projects [C++], debug configuration", "troubleshooting release builds", "memory [C++], overwrites"] diff --git a/docs/build/common-visual-cpp-64-bit-migration-issues.md b/docs/build/common-visual-cpp-64-bit-migration-issues.md index b14cd0b55f..531a59ee62 100644 --- a/docs/build/common-visual-cpp-64-bit-migration-issues.md +++ b/docs/build/common-visual-cpp-64-bit-migration-issues.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Common Visual C++ 64-bit Migration Issues" title: "Common Visual C++ 64-bit Migration Issues" ms.date: "05/06/2019" helpviewer_keywords: ["64-bit programming [C++], migration", "64-bit compiler [C++], migration", "porting 32-bit code to 64-bit code", "migration [C++], 64-bit code issues", "32-bit code porting [C++]", "64-bit applications [C++]", "64-bit compiler [C++], porting 32-bit code", "Win64 [C++]"] diff --git a/docs/build/common-visual-cpp-arm-migration-issues.md b/docs/build/common-visual-cpp-arm-migration-issues.md index c5bca9c4b0..36035c044b 100644 --- a/docs/build/common-visual-cpp-arm-migration-issues.md +++ b/docs/build/common-visual-cpp-arm-migration-issues.md @@ -1,28 +1,31 @@ --- +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 @@ -40,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. @@ -68,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; @@ -82,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/concepts-of-isolated-applications-and-side-by-side-assemblies.md b/docs/build/concepts-of-isolated-applications-and-side-by-side-assemblies.md index e82cd390a4..ef50625ae8 100644 --- a/docs/build/concepts-of-isolated-applications-and-side-by-side-assemblies.md +++ b/docs/build/concepts-of-isolated-applications-and-side-by-side-assemblies.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Concepts of Isolated Applications and Side-by-side Assemblies" title: "Concepts of Isolated Applications and Side-by-side Assemblies" ms.date: "05/06/2019" helpviewer_keywords: ["side-by-side assemblies [C++]", "isolated assemblies [C++]"] ms.assetid: 945a885f-cb3e-4c8a-a0b9-2c2e3e02cc50 +ms.topic: concept-article --- # Concepts of Isolated Applications and Side-by-side Assemblies diff --git a/docs/build/configure-cmake-debugging-sessions.md b/docs/build/configure-cmake-debugging-sessions.md index 309ae2bf46..a16c9e0f9b 100644 --- a/docs/build/configure-cmake-debugging-sessions.md +++ b/docs/build/configure-cmake-debugging-sessions.md @@ -1,44 +1,59 @@ --- title: "Configure CMake debugging sessions in Visual Studio" description: "Describes how to use Visual Studio to configure CMake debugger settings." -ms.date: "04/02/2020" +ms.date: 10/26/2023 helpviewer_keywords: ["CMake debugging"] +ms.topic: how-to --- # Configure CMake debugging sessions -::: moniker range="vs-2015" +::: 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 -::: moniker range=">=vs-2017" +::: moniker range=">=msvc-150" -All executable CMake targets are shown in the **Startup Item** dropdown in the **General** toolbar. Select one to start a debugging session and launch the debugger. +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. @@ -49,7 +64,6 @@ To reference any key in a *CMakeSettings.json* file, prepend `cmake.` to it in * ```json { "version": "0.2.1", - "defaults": {}, "configurations": [ { "type": "default", @@ -106,9 +120,14 @@ In Visual Studio 2019 version 16.6, we added a new debug configuration of `type: #### Additional options allowed with the `gdbserver` configuration (16.7 or later) - `program`: Defaults to `"${debugInfo.fullTargetPath}"`. The Unix path to the application to debug. Only required if different than the target executable in the build or deploy location. + + > [!TIP] + > Deploy is not yet supported for local cross-compilation scenarios. If you are cross-compiling on Windows (for example, using a cross-compiler on Windows to build a Linux ARM executable) then you'll need to manually copy the binary to the location specified by `program` on the remote ARM machine before debugging. + - `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. @@ -218,7 +237,7 @@ You can configure the `cppdbg` configuration to debug using `gdbserver`. You can ::: moniker-end -::: moniker range=">=vs-2017" +::: moniker range=">=msvc-150" ## See also diff --git a/docs/build/configuring-programs-for-64-bit-visual-cpp.md b/docs/build/configuring-programs-for-64-bit-visual-cpp.md index 3513524fc3..e922af4027 100644 --- a/docs/build/configuring-programs-for-64-bit-visual-cpp.md +++ b/docs/build/configuring-programs-for-64-bit-visual-cpp.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Configure C++ projects for 64-bit, x64 targets" title: "Configure C++ projects for 64-bit, x64 targets" ms.date: "11/04/2016" helpviewer_keywords: ["64-bit compiler [C++], options", "64-bit compiler [C++]", "64-bit programming [C++], about 64-bit programming", "programming [C++], 64-bit"] 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 037276498c..fc99baa1b2 100644 --- a/docs/build/configuring-programs-for-arm-processors-visual-cpp.md +++ b/docs/build/configuring-programs-for-arm-processors-visual-cpp.md @@ -1,7 +1,7 @@ --- +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 @@ -16,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. @@ -26,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 f05d4cb56d..629e6b7230 100644 --- a/docs/build/configuring-programs-for-windows-xp.md +++ b/docs/build/configuring-programs-for-windows-xp.md @@ -1,28 +1,29 @@ --- 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 +ms.topic: how-to --- # 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="vs-2019" +::: 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 ## Install the Windows XP platform toolset -::: moniker range="<=vs-2017" +::: moniker range="<=msvc-150" To get the Visual Studio 2017 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 list of optional components for this workload, choose **Windows XP support for C++**, and then choose **Install** or **Modify**. ::: moniker-end -::: moniker range="vs-2019" +::: 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 +37,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 +62,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 +71,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://www.microsoft.com/download/details.aspx?displaylang=en&id=6812). + 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 6923b4d97e..cafd37a1e7 100644 --- a/docs/build/cppproperties-schema-reference.md +++ b/docs/build/cppproperties-schema-reference.md @@ -1,86 +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: -||| -|-|-| -|`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. @@ -112,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`*: -||| -|-|-| -|`${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 { @@ -135,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 e446aec45e..52af28e0f4 100644 --- a/docs/build/create-reusable-property-configurations.md +++ b/docs/build/create-reusable-property-configurations.md @@ -1,44 +1,46 @@ --- +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"] +ms.topic: how-to --- # 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-a-resource-only-dll.md b/docs/build/creating-a-resource-only-dll.md index 9d5f601d3b..664e45250d 100644 --- a/docs/build/creating-a-resource-only-dll.md +++ b/docs/build/creating-a-resource-only-dll.md @@ -5,6 +5,7 @@ ms.date: "01/27/2020" helpviewer_keywords: ["resource-only DLLs [C++], creating", "DLLs [C++], creating"] ms.assetid: e6b1d4da-7275-467f-a58c-a0a8a5835199 no-loc: [noentry] +ms.topic: how-to --- # Creating a resource-only DLL @@ -14,7 +15,7 @@ A resource-only DLL is a DLL that contains nothing but resources, such as icons, To create a resource-only DLL, you create a new Windows DLL (non-MFC) project, and add your resources to the project: -::: moniker range="vs-2015" +::: moniker range="msvc-140" 1. Select **Win32 Project** in the **New Project** dialog box. Enter the project and solution names, and choose **OK**. @@ -29,7 +30,7 @@ To create a resource-only DLL, you create a new Windows DLL (non-MFC) project, a 1. Build the DLL. ::: moniker-end -::: moniker range=">=vs-2017" +::: moniker range=">=msvc-150" 1. Select **Windows Desktop Wizard** in the **New Project** dialog box and choose **Next**. In the **Configure your new project** page, enter the project and solution names, and choose **Create**. diff --git a/docs/build/creating-and-managing-visual-cpp-projects.md b/docs/build/creating-and-managing-visual-cpp-projects.md index c07f3c6709..2441a8b327 100644 --- a/docs/build/creating-and-managing-visual-cpp-projects.md +++ b/docs/build/creating-and-managing-visual-cpp-projects.md @@ -1,79 +1,92 @@ --- -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="vs-2019" +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**. + +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. -::: moniker range="vs-2017" + :::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**. - ![Solution Explorer](media/mathlibrary-solution-explorer-153.png) +1. Choose **Visual C++** in the left pane. In the center pane, a list of project templates appears: -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. + :::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."::: -## Add items +::: moniker-end -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**. +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 third party libraries +You can create your own project templates. For more information, see [Create project templates](/visualstudio/ide/how-to-create-project-templates). -To add third-party libraries, use the [vcpkg](vcpkg.md) 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. +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."::: + +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**. -## Set compiler options and other build properties +The solution file coordinates build dependencies when you have multiple related projects. Compiler options are set at the project level. -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 code, icons, and other assets to a project + +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 909c2ecb47..2b0f1f5ebe 100644 --- a/docs/build/creating-precompiled-header-files.md +++ b/docs/build/creating-precompiled-header-files.md @@ -1,154 +1,189 @@ --- 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: -|||| -|-|-|-| -|`comment`|`page`|`subtitle`| -|`linesize`|`pagesize`|`title`| -|`message`|`skip`|| +:::row::: + :::column span=""::: + `comment`\ + `linesize` + :::column-end::: + :::column span=""::: + `message`\ + `page` + :::column-end::: + :::column span=""::: + `pagesize`\ + `skip` + :::column-end::: + :::column span=""::: + `subtitle`\ + `title` + :::column-end::: +:::row-end::: These pragmas are retained as part of a precompiled header, and affect the remainder of a compilation that uses the precompiled header: -|||| -|-|-|-| -|`alloc_text`|`include_alias`|`pack`| -|`auto_inline`|`init_seg`|`pointers_to_members`| -|`check_stack`|`inline_depth`|`setlocale`| -|`code_seg`|`inline_recursion`|`vtordisp`| -|`data_seg`|`intrinsic`|`warning`| -|`function`|`optimize`|| - -## 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. - -### Compiler Option Consistency +:::row::: + :::column span=""::: + `alloc_text`\ + `auto_inline`\ + `check_stack`\ + `code_seg`\ + `data_seg` + :::column-end::: + :::column span=""::: + `function`\ + `include_alias`\ + `init_seg`\ + `inline_depth` + :::column-end::: + :::column span=""::: + `inline_recursion`\ + `intrinsic`\ + `optimize`\ + `pack` + :::column-end::: + :::column span=""::: + `pointers_to_members`\ + `setlocale`\ + `vtordisp`\ + `warning` + :::column-end::: +:::row-end::: + +## 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. + +### 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 @@ -194,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 @@ -221,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 @@ -233,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 @@ -247,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 @@ -277,6 +320,8 @@ void notstable( void ) } ``` +Source file `MYAPP.CPP`: + ```cpp // MYAPP.CPP : Sample application // All precompiled code other than the file listed @@ -285,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(); @@ -298,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 e64b3efb06..6b56804360 100644 --- a/docs/build/customize-cmake-settings.md +++ b/docs/build/customize-cmake-settings.md @@ -1,25 +1,31 @@ --- +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"] +ms.topic: how-to --- # Customize CMake build settings -::: moniker range="vs-2019" +::: 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 @@ -31,19 +37,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 @@ -51,35 +57,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" @@ -93,15 +99,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 @@ -111,11 +117,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 @@ -123,7 +129,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: @@ -141,9 +147,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. @@ -151,25 +157,25 @@ For more information about each of the properties in the file, see [CMakeSetting ::: moniker-end -::: moniker range="<=vs-2017" +::: 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 { @@ -185,11 +191,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/determining-which-exporting-method-to-use.md b/docs/build/determining-which-exporting-method-to-use.md index 304fcd5946..58d6c4432c 100644 --- a/docs/build/determining-which-exporting-method-to-use.md +++ b/docs/build/determining-which-exporting-method-to-use.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Determine Which Exporting Method to Use" title: "Determine Which Exporting Method to Use" ms.date: "11/04/2016" helpviewer_keywords: ["__declspec(dllexport) keyword [C++]", "exporting DLLs [C++], method comparison", "def files [C++], exporting from DLLs", ".def files [C++], exporting from DLLs"] diff --git a/docs/build/dll-frequently-asked-questions.md b/docs/build/dll-frequently-asked-questions.md deleted file mode 100644 index ba40fe2699..0000000000 --- a/docs/build/dll-frequently-asked-questions.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -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/environment-variables-for-profile-guided-optimizations.md b/docs/build/environment-variables-for-profile-guided-optimizations.md index 65e83d9b80..9677b3b138 100644 --- a/docs/build/environment-variables-for-profile-guided-optimizations.md +++ b/docs/build/environment-variables-for-profile-guided-optimizations.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Environment Variables for Profile-Guided Optimizations" title: "Environment Variables for Profile-Guided Optimizations" ms.date: "03/14/2018" helpviewer_keywords: ["profile-guided optimizations, environment variables"] diff --git a/docs/build/exception-handling-x64.md b/docs/build/exception-handling-x64.md index 237921aee2..41a6e29b6e 100644 --- a/docs/build/exception-handling-x64.md +++ b/docs/build/exception-handling-x64.md @@ -1,5 +1,6 @@ --- title: "x64 exception handling" +description: "Overview of Microsoft C++ exception handling conventions on x64." ms.date: "10/14/2019" helpviewer_keywords: ["C++ exception handling, x64", "exception handling, x64"] ms.assetid: 41fecd2d-3717-4643-b21c-65dcd2f18c93 @@ -16,7 +17,7 @@ Several data structures are required for exception handling and debugging suppor Table-based exception handling requires a table entry for all functions that allocate stack space or call another function (for example, nonleaf functions). Function table entries have the format: -||| +|Size|Value| |-|-| |ULONG|Function start address| |ULONG|Function end address| @@ -28,7 +29,7 @@ The RUNTIME_FUNCTION structure must be DWORD aligned in memory. All addresses ar The unwind data info structure is used to record the effects a function has on the stack pointer, and where the nonvolatile registers are saved on the stack: -||| +|Size|Value| |-|-| |UBYTE: 3|Version| |UBYTE: 5|Flags| @@ -41,14 +42,14 @@ The unwind data info structure is used to record the effects a function has on t (1) Exception Handler -||| +|Size|Value| |-|-| |ULONG|Address of exception handler| |variable|Language-specific handler data (optional)| (2) Chained Unwind Info -||| +|Size|Value| |-|-| |ULONG|Function start address| |ULONG|Function end address| @@ -106,7 +107,7 @@ The UNWIND_INFO structure must be DWORD aligned in memory. Here's what each fiel The unwind code array is used to record the sequence of operations in the prolog that affect the nonvolatile registers and RSP. Each code item has this format: -||| +|Size|Value| |-|-| |UBYTE|Offset in prolog| |UBYTE: 4|Unwind operation code| @@ -172,7 +173,7 @@ The unwind operation code is one of these values: Push a machine frame. This unwind code is used to record the effect of a hardware interrupt or exception. There are two forms. If the operation info equals 0, one of these frames has been pushed on the stack: - ||| + |Location|Value| |-|-| |RSP+32|SS| |RSP+24|Old RSP| @@ -182,7 +183,7 @@ The unwind operation code is one of these values: If the operation info equals 1, then one of these frames has been pushed: - ||| + |Location|Value| |-|-| |RSP+40|SS| |RSP+32|Old RSP| @@ -213,7 +214,7 @@ The unwind operation code is one of these values: The meaning of the operation info bits depends upon the operation code. To encode a general-purpose (integer) register, this mapping is used: -||| +|Bit|Register| |-|-| |0|RAX| |1|RCX| @@ -297,7 +298,7 @@ typedef struct _DISPATCHER_CONTEXT { } DISPATCHER_CONTEXT, *PDISPATCHER_CONTEXT; ``` -**ControlPc** is the value of RIP within this function. This value is either an exception address or the address at which control left the establishing function. The RIP is used to determine if control is within some guarded construct inside this function, for example, a `__try` block for `__try`/**`__except`** or `__try`/**`__finally`**. +**ControlPc** is the value of RIP within this function. This value is either an exception address or the address at which control left the establishing function. The RIP is used to determine if control is within some guarded construct inside this function, for example, a **`__try`** block for **`__try`**/**`__except`** or **`__try`**/**`__finally`**. **ImageBase** is the image base (load address) of the module containing this function, to be added to the 32-bit offsets used in the function entry and unwind info to record relative addresses. @@ -439,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; @@ -487,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-and-importing-using-afx-ext-class.md b/docs/build/exporting-and-importing-using-afx-ext-class.md index ef7af0afc1..e47b06663e 100644 --- a/docs/build/exporting-and-importing-using-afx-ext-class.md +++ b/docs/build/exporting-and-importing-using-afx-ext-class.md @@ -1,9 +1,11 @@ --- +description: "Learn more about: Exporting and Importing Using AFX_EXT_CLASS" title: "Exporting and Importing Using AFX_EXT_CLASS" ms.date: "11/04/2016" f1_keywords: ["afx_ext_class"] helpviewer_keywords: ["AFX_EXT_CLASS macro", "exporting classes [C++]", "importing DLLs [C++]", "extension DLLs [C++], exporting classes", "executable files [C++], importing classes", "exporting DLLs [C++], AFX_EXT_CLASS macro"] ms.assetid: 6b72cb2b-e92e-4ecd-bcab-c335e1d1cfde +ms.topic: concept-article --- # Exporting and Importing Using AFX_EXT_CLASS 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 bd167aaf9d..4096be3e6e 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,14 +1,16 @@ --- -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 +ms.topic: how-to --- -# 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 @@ -25,7 +27,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" { @@ -35,15 +37,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) @@ -51,7 +53,7 @@ extern "C" { - [Decorated names](reference/decorated-names.md) -- [Using extern to Specify Linkage](../cpp/using-extern-to-specify-linkage.md) +- [Using `extern` to specify linkage](../cpp/extern-cpp.md) ## See also diff --git a/docs/build/exporting-cpp-functions-for-use-in-c-language-executables.md b/docs/build/exporting-cpp-functions-for-use-in-c-language-executables.md index 66f9f646d3..d44fe579a3 100644 --- a/docs/build/exporting-cpp-functions-for-use-in-c-language-executables.md +++ b/docs/build/exporting-cpp-functions-for-use-in-c-language-executables.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Exporting C++ Functions for Use in C-Language Executables" title: "Exporting C++ Functions for Use in C-Language Executables" ms.date: "11/04/2016" helpviewer_keywords: ["functions [C++], C++ functions in C executables", "exporting DLLs [C++], C++ functions in C executables", "exporting functions [C++], C++ functions in C executables", "functions [C++], exporting"] ms.assetid: 80b9e982-f52d-4312-a891-f73cc69f3c2b +ms.topic: concept-article --- # Exporting C++ Functions for Use in C-Language Executables @@ -34,7 +36,7 @@ extern "C" __declspec( dllexport ) int MyFunc(long parm1); - [Decorated names](reference/decorated-names.md) -- [Using extern to Specify Linkage](../cpp/using-extern-to-specify-linkage.md) +- [Using extern to Specify Linkage](../cpp/extern-cpp.md) ## See also diff --git a/docs/build/exporting-from-a-dll-using-declspec-dllexport.md b/docs/build/exporting-from-a-dll-using-declspec-dllexport.md index 888d9aeaaa..674c52fb8d 100644 --- a/docs/build/exporting-from-a-dll-using-declspec-dllexport.md +++ b/docs/build/exporting-from-a-dll-using-declspec-dllexport.md @@ -1,9 +1,11 @@ --- +description: "Learn more about: Exporting from a DLL Using __declspec(dllexport)" title: "Exporting from a DLL Using __declspec(dllexport)" ms.date: "05/06/2019" f1_keywords: ["dllexport"] helpviewer_keywords: ["__declspec(dllexport) keyword [C++]", "names [C++], DLL exports by", "export directives [C++]", "exporting DLLs [C++], __declspec(dllexport) keyword"] ms.assetid: a35e25e8-7263-4a04-bad4-00b284458679 +ms.topic: how-to --- # Exporting from a DLL Using __declspec(dllexport) diff --git a/docs/build/exporting-from-a-dll-using-def-files.md b/docs/build/exporting-from-a-dll-using-def-files.md index ebcdd72554..ce1b224eed 100644 --- a/docs/build/exporting-from-a-dll-using-def-files.md +++ b/docs/build/exporting-from-a-dll-using-def-files.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Exporting from a DLL Using DEF Files" title: "Exporting from a DLL Using DEF Files" ms.date: "05/06/2019" helpviewer_keywords: ["def files [C++], exporting from DLLs", ".def files [C++], exporting from DLLs", "exporting DLLs [C++], DEF files"] ms.assetid: 9d31eda2-184e-47de-a2ee-a93ebd603f8e +ms.topic: concept-article --- # Exporting from a DLL Using DEF Files diff --git a/docs/build/exporting-from-a-dll.md b/docs/build/exporting-from-a-dll.md index 7c5f3db3c6..d7513fc477 100644 --- a/docs/build/exporting-from-a-dll.md +++ b/docs/build/exporting-from-a-dll.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Exporting from a DLL" title: "Exporting from a DLL" ms.date: "11/04/2016" helpviewer_keywords: ["exporting DLLs [C++], about exporting from DLLs", "exporting functions [C++], DLLs (exporting from)", "exporting DLLs [C++]", "DLLs [C++], exporting from", "DLL exports [C++]", "functions [C++], exporting", "exports table [C++]"] ms.assetid: a08f86c4-5996-460b-ae54-da2b764045f0 +ms.topic: concept-article --- # Exporting from a DLL diff --git a/docs/build/exporting-functions-from-a-dll-by-ordinal-rather-than-by-name.md b/docs/build/exporting-functions-from-a-dll-by-ordinal-rather-than-by-name.md index b053bbf1b6..d5911954fb 100644 --- a/docs/build/exporting-functions-from-a-dll-by-ordinal-rather-than-by-name.md +++ b/docs/build/exporting-functions-from-a-dll-by-ordinal-rather-than-by-name.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Exporting Functions from a DLL by Ordinal Rather Than by Name" title: "Exporting Functions from a DLL by Ordinal Rather Than by Name" ms.date: "11/04/2016" helpviewer_keywords: ["exporting functions [C++], ordinal values", "ordinal exports [C++]", "exporting DLLs [C++], ordinal values", "NONAME attribute"] ms.assetid: 679719fd-d965-4df3-9f7a-7d86ad831702 +ms.topic: concept-article --- # Exporting Functions from a DLL by Ordinal Rather Than by Name diff --git a/docs/build/extension-dlls-overview.md b/docs/build/extension-dlls-overview.md index d17f10888f..b43f909510 100644 --- a/docs/build/extension-dlls-overview.md +++ b/docs/build/extension-dlls-overview.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: MFC extension DLLs: Overview" title: "Extension DLLs: Overview" ms.date: "05/06/2019" helpviewer_keywords: ["AFXDLL library", "MFC DLLs [C++], MFC extension DLLs", "DLLs [C++], extension", "shared DLL versions [C++]", "extension DLLs [C++], about MFC extension DLLs"] ms.assetid: eb5e10b7-d615-4bc7-908d-e3e99b7b1d5f +ms.topic: concept-article --- # MFC extension DLLs: Overview diff --git a/docs/build/extension-dlls.md b/docs/build/extension-dlls.md index 25192d47ba..c9c4df3763 100644 --- a/docs/build/extension-dlls.md +++ b/docs/build/extension-dlls.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: MFC extension DLLs" title: "Extension DLLs" ms.date: "05/06/2019" helpviewer_keywords: ["memory [C++], DLLs", "MFC extension DLLs [C++]", "AFXDLL library", "shared resources [C++]", "MFC DLLs [C++], MFC extension DLLs", "DLLs [C++], extension", "shared DLL versions [C++]", "resource sharing [C++]", "extension DLLs [C++]", "extension DLLs [C++], about MFC extension DLLs"] diff --git a/docs/build/fixing-release-build-problems.md b/docs/build/fixing-release-build-problems.md index f379c8a98c..f10be40f3e 100644 --- a/docs/build/fixing-release-build-problems.md +++ b/docs/build/fixing-release-build-problems.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Fixing Release Build Problems" title: "Fixing Release Build Problems" ms.date: "11/04/2016" helpviewer_keywords: ["release builds, troubleshooting", "debug builds, memory overwrites", "memory, overwrites", "troubleshooting Visual C++, release builds", "troubleshooting release builds"] ms.assetid: a0c0818e-4c47-4fe0-a611-50d61a41bd88 +ms.topic: concept-article --- # Fixing Release Build Problems 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 58846ff51b..b8c2ff6f18 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,10 +1,12 @@ --- -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 +ms.topic: concept-article --- -# 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: @@ -12,28 +14,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/freelibrary-and-afxfreelibrary.md b/docs/build/freelibrary-and-afxfreelibrary.md index c205e2e991..28afe4945a 100644 --- a/docs/build/freelibrary-and-afxfreelibrary.md +++ b/docs/build/freelibrary-and-afxfreelibrary.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: FreeLibrary and AfxFreeLibrary" title: "FreeLibrary and AfxFreeLibrary" ms.date: "11/04/2016" f1_keywords: ["FreeLibrary", "AfxFreeLibrary"] diff --git a/docs/build/get-started-linux-cmake.md b/docs/build/get-started-linux-cmake.md index 19c16e3c98..b2f59a7381 100644 --- a/docs/build/get-started-linux-cmake.md +++ b/docs/build/get-started-linux-cmake.md @@ -2,7 +2,8 @@ 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 +ms.custom: sfi-image-nochange --- # Tutorial: Create C++ cross-platform projects in Visual Studio @@ -21,14 +22,16 @@ 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, ninja, 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 ninja-build zip + sudo apt install -y openssh-server build-essential gdb rsync make zip ``` * Visual Studio requires a recent version of CMake on the Linux machine that has server mode enabled (at least 3.8). Microsoft produces a universal build of CMake that you can install on any Linux distro. We recommend you use this build to ensure that you have the latest features. You can get the CMake binaries from [the Microsoft fork of the CMake repo](https://github.com/Microsoft/CMake/releases) on GitHub. Go to that page and download the version that matches the system architecture on your Linux machine, then mark it as an executable: @@ -38,7 +41,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 +52,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 +100,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 +124,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. @@ -139,21 +142,25 @@ In this step, we'll debug an example program that demonstrates the Bullet Physic 1. Add a Linux configuration. Right-click the CMakeSettings.json file in the **Solution Explorer** view and select **Add Configuration**. You see the same Add Configuration to CMakeSettings dialog as before. Select **Linux-Debug** this time, then save the CMakeSettings.json file (ctrl + s). +1. **Visual Studio 2019 version 16.6 or later** Scroll down to the bottom of the CMake Settings Editor and select **Show advanced settings**. Select **Unix Makefiles** as the **CMake generator**, then save the CMakeSettings.json file (ctrl + s). + 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](/cpp/linux/connect-to-your-remote-linux-computer) 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](/cpp/linux/configure-a-linux-project?view=vs-2019#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. @@ -163,7 +170,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}", @@ -173,13 +180,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 @@ -197,4 +208,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/getprocaddress.md b/docs/build/getprocaddress.md index 908859a320..6e538053bb 100644 --- a/docs/build/getprocaddress.md +++ b/docs/build/getprocaddress.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: GetProcAddress" title: "GetProcAddress" ms.date: "11/04/2016" f1_keywords: ["GetProcAddress"] diff --git a/docs/build/how-to-add-a-custom-build-step-to-msbuild-projects.md b/docs/build/how-to-add-a-custom-build-step-to-msbuild-projects.md index 96f281575a..5fe3724876 100644 --- a/docs/build/how-to-add-a-custom-build-step-to-msbuild-projects.md +++ b/docs/build/how-to-add-a-custom-build-step-to-msbuild-projects.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: How to: Add a Custom Build Step to MSBuild Projects" title: "How to: Add a Custom Build Step to MSBuild Projects" ms.date: "10/16/2019" helpviewer_keywords: ["msbuild (c++), howto: add a custom build step"] 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 75e651069c..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,24 +1,27 @@ --- -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... @@ -28,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 @@ -41,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-build-isolated-applications-to-consume-com-components.md b/docs/build/how-to-build-isolated-applications-to-consume-com-components.md index d02de0361a..3c84ebd01d 100644 --- a/docs/build/how-to-build-isolated-applications-to-consume-com-components.md +++ b/docs/build/how-to-build-isolated-applications-to-consume-com-components.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: How to: Build Isolated Applications to Consume COM Components" title: "How to: Build Isolated Applications to Consume COM Components" ms.date: "11/04/2016" helpviewer_keywords: ["isolated applications [C++]"] diff --git a/docs/build/how-to-build-registration-free-com-components.md b/docs/build/how-to-build-registration-free-com-components.md index adb29a4277..2497be473a 100644 --- a/docs/build/how-to-build-registration-free-com-components.md +++ b/docs/build/how-to-build-registration-free-com-components.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: How to: Build Registration-Free COM Components" title: "How to: Build Registration-Free COM Components" ms.date: "11/04/2016" helpviewer_keywords: ["COM components, registration-free"] diff --git a/docs/build/how-to-configure-visual-cpp-projects-to-target-64-bit-platforms.md b/docs/build/how-to-configure-visual-cpp-projects-to-target-64-bit-platforms.md index a2dd80e7ee..4656970d0a 100644 --- a/docs/build/how-to-configure-visual-cpp-projects-to-target-64-bit-platforms.md +++ b/docs/build/how-to-configure-visual-cpp-projects-to-target-64-bit-platforms.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: How to: Configure Visual Studio C++ projects to Target 64-Bit, x64 Platforms" title: "How to: Configure Visual Studio C++ projects to Target 64-Bit, x64 Platforms" ms.date: "11/04/2016" helpviewer_keywords: ["platforms [C++], 64-bit", "64-bit programming [C++], configuring projects", "project configurations [C++]"] 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 ba3c388181..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,20 +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 | @@ -24,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. @@ -33,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. @@ -52,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-create-a-release-build.md b/docs/build/how-to-create-a-release-build.md index f6d98f2a27..be26a6e5da 100644 --- a/docs/build/how-to-create-a-release-build.md +++ b/docs/build/how-to-create-a-release-build.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: How to: Create a Release Build" title: "How to: Create a Release Build" ms.date: "11/04/2016" helpviewer_keywords: ["Win32, release build", "release builds, creating"] diff --git a/docs/build/how-to-debug-a-release-build.md b/docs/build/how-to-debug-a-release-build.md index 3811863d05..3063cfc32b 100644 --- a/docs/build/how-to-debug-a-release-build.md +++ b/docs/build/how-to-debug-a-release-build.md @@ -1,30 +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 4299174f28..0000000000 --- a/docs/build/how-to-embed-a-manifest-inside-a-c-cpp-application.md +++ /dev/null @@ -1,253 +0,0 @@ ---- -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 b22fb196eb..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 @@ -1,8 +1,8 @@ --- +description: "Learn more about: How to: Enable a 64-Bit, x64 hosted MSVC toolset on the command line" 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 @@ -10,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-integrate-custom-tools-into-the-project-properties.md b/docs/build/how-to-integrate-custom-tools-into-the-project-properties.md index a1f5fb8184..8dda41dbe2 100644 --- a/docs/build/how-to-integrate-custom-tools-into-the-project-properties.md +++ b/docs/build/how-to-integrate-custom-tools-into-the-project-properties.md @@ -1,32 +1,50 @@ --- title: "How to: Integrate Custom Tools into the Project Properties" -ms.date: "05/16/2019" -helpviewer_keywords: ["msbuild (c++), howto: integrate custom tools"] -ms.assetid: f32d91a4-44e9-4de3-aa9a-1c7f709ad2ee +description: "How to integrate custom tools into the Project Properties in Visual Studio C++ projects." +ms.date: 10/08/2020 +helpviewer_keywords: ["MSBuild (C++), howto: integrate custom tools"] --- # How to: Integrate Custom Tools into the Project Properties -You can add custom tool options to the Visual Studio **Property Pages** window by creating an underlying XML schema file. +You can add custom tool options to the Visual Studio **Property Pages** window by creating an XML file. -The **Configuration Properties** section of the **Property Pages** window displays setting groups that are known as *rules*. Every rule contains the settings for a tool or a group of features. For example, the **Linker** rule contains the settings for the linker tool. The settings in a rule can be subdivided into *categories*. +The **Configuration Properties** section of the **Property Pages** window displays setting groups known as *rules*. Every rule contains the settings for a tool or a group of features. For example, the **Linker** rule contains the settings for the linker tool. The settings in a rule can be subdivided into *categories*. -This document explains how to create a file in a set directory that contains properties for your custom tool so that the properties are loaded when Visual Studio starts. For information about how to modify the file, see [Platform Extensibilty Part 2](https://docs.microsoft.com/archive/blogs/vsproject/platform-extensibility-part-2) on the Visual Studio Project Team blog. +You can create a rule file that contains properties for your custom tool so that the properties are loaded when Visual Studio starts. For information about how to modify the file, see [Platform Extensibility Part 2](/archive/blogs/vsproject/platform-extensibility-part-2) on the Visual Studio Project Team blog. + +::: moniker range="msvc-140" + +The folder to place your rule file in depends on the locale and the version of Visual Studio in use. In a Visual Studio 2015 or earlier developer command prompt, the rules folder is *`%ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\\`*. The `` value is *`v140`* in Visual Studio 2015. The `` is an LCID, for example, `1033` for English. You'll use a different path for each edition of Visual Studio that's installed, and for each language. For example, the default rules folder path for Visual Studio 2015 Community edition in English could be *`C:\Program Files (x86)\MSBuild\Microsoft.Cpp\v4.0\v140\1033\`*. + +::: moniker-end + +::: moniker range="msvc-150" + +The folder to place your rule file in depends on the locale and the version of Visual Studio in use. In a Visual Studio 2017 developer command prompt, the rules folder is *`%VSINSTALLDIR%Common7\IDE\VC\VCTargets\\`*. The `` is an LCID, for example, `1033` for English. In a Visual Studio 2015 or earlier developer command prompt, the rules folder is *`%ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\\\`*, where the `` value is *`v140`* in Visual Studio 2015. You'll use a different path for each edition of Visual Studio that's installed, and for each language. For example, the default rules folder path for Visual Studio 2017 Community edition in English could be *`C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\Common7\IDE\VC\VCTargets\1033\`*. + +::: moniker-end + +::: moniker range=">=msvc-160" + +The folder to place your rule file in depends on the locale and the version of Visual Studio in use. In a Visual Studio 2019 or later developer command prompt, the rules folder is *`%VSINSTALLDIR%MSBuild\Microsoft\VC\\\`*, where the `` value is *`v160`* in Visual Studio 2019. The `` is an LCID, for example, `1033` for English. In Visual Studio 2017, the rules folder is *`%VSINSTALLDIR%Common7\IDE\VC\VCTargets\\`*. In a Visual Studio 2015 or earlier developer command prompt, the rules folder is *`%ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\\\`*. You'll use a different path for each edition of Visual Studio that's installed, and for each language. For example, the default rules folder path for Visual Studio 2019 Community edition in English could be *`C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\MSBuild\Microsoft\VC\v160\1033\`*. + +::: moniker-end ### To add or change project properties 1. In the XML editor, create an XML file. -1. Save the file in the Visual Studio `VCTargets\1033` folder. You will have a different path for each edition of Visual Studio that is installed and each language. For example, the default folder path for Visual Studio 2019 Community edition in English is `C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\Common7\IDE\VC\VCTargets`. Adjust the path for your language and Visual Studio edition. Every rule in the **Property Pages** window is represented by an XML file in this folder. Make sure that the file is uniquely named in the folder. +1. Save the file in the default rules folder. Adjust the path for your language and Visual Studio edition. Every rule in the **Property Pages** window is represented by an XML file in this folder. Make sure that the file is uniquely named in the folder. -1. Copy the content of `%ProgramFiles%\Microsoft Visual Studio\2019\\Common7\IDE\VC\VCTargets\\cl.xml` (or whatever your path is), close it without saving changes, and then paste the content in your new XML file. You can use any XML schema file - this is just one that can be used so you start with a template. +1. Copy the content of an existing rules file, such as *`rc.xml`*, close it without saving changes, and then paste the content in your new XML file. You can copy any XML schema file to use as a template. Choose one that's similar to your tool. 1. In the new XML file, modify the content according to your requirements. Make sure to change the **Rule Name** and **Rule.DisplayName** at the top of the file. -1. Save the changes and close the file. +1. Save your changes and close the file. -1. The XML files in `%ProgramFiles%\Microsoft Visual Studio\2019\\Common7\IDE\VC\VCTargets\` (or wherever you saved them) are loaded when Visual Studio starts. Therefore, to test the new file, restart Visual Studio. +1. The XML files in the rules folder are loaded when Visual Studio starts. To test the new file, restart Visual Studio. -1. In **Solution Explorer**, right-click a project and then click **Properties**. In the **Property Pages** window, in the left pane, verify that there is a new node with the name of your Rule. +1. In **Solution Explorer**, right-click a project and then choose **Properties**. In the **Property Pages** window, verify that there's a new node with the name of your rule. ## See also diff --git a/docs/build/how-to-merge-multiple-pgo-profiles-into-a-single-profile.md b/docs/build/how-to-merge-multiple-pgo-profiles-into-a-single-profile.md index 77acb0392e..13784aa448 100644 --- a/docs/build/how-to-merge-multiple-pgo-profiles-into-a-single-profile.md +++ b/docs/build/how-to-merge-multiple-pgo-profiles-into-a-single-profile.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: How to: Merge Multiple PGO Profiles into a Single Profile" title: "How to: Merge Multiple PGO Profiles into a Single Profile" ms.date: "03/14/2018" helpviewer_keywords: ["merging profiles", "profile-guided optimizations, merging profiles"] 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 d2ec9815a0..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,38 +1,38 @@ --- +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: "conceptual" -ms.date: "07/24/2019" +ms.date: 03/31/2021 helpviewer_keywords: ["msbuild (c++), howto: modify target framework and platform toolset"] -ms.assetid: 031b1d54-e6e1-4da7-9868-3e75a87d9ffe --- # How to: Modify the Target Framework and Platform Toolset -You can edit a Visual Studio C++ project file to target different versions of the C++ platform toolset, the Windows SDK and the .NET Framework (C++/CLI projects only). By default, the project system uses the .NET Framework version and the toolset version that correspond to the version of Visual Studio that you use to create the project. You can modify all these values in the .vcxproj file so that you can use the same code base for every compilation target. +You can edit a Visual Studio C++ project file to target different versions of the C++ platform toolset. The Windows SDK and the .NET Framework used are also editable. (The .NET Framework applies to C++/CLI projects only). A new project uses the default .NET Framework and toolset of the Visual Studio version that you use to create the project. If you modify these values in the .vcxproj file, you can use the same code base for every compilation target. ## Platform toolset -The platform toolset consists of the C++ compiler (cl.exe) and linker (link.exe), along with the C/C++ standard libraries. Since Visual Studio 2015, the major version of the toolset has remained at 14, which means that projects compiled with Visual Studio 2019 or Visual Studio 2017 are ABI-backwards-compatible with projects compiled with Visual Studio 2015. The minor version has updated by 1 for each version since Visual Studio 2015: +The platform toolset consists of the C++ compiler (cl.exe) and linker (link.exe), along with the C/C++ standard libraries. Visual Studio 2015, Visual Studio 2017, and Visual Studio 2019 are binary-compatible. It's shown by the major version of the toolset, which has remained at 14. Projects compiled in Visual Studio 2019 or Visual Studio 2017 are ABI-backwards-compatible with 2017 and 2015 projects. The minor version has updated by 1 for each version since Visual Studio 2015: - Visual Studio 2015: v140 - Visual Studio 2017: v141 - Visual Studio 2019: v142 +- Visual Studio 2022: v143 -These toolsets support .NET Framework 4.5 and later. +These toolsets support the .NET Framework 4.5 and later. -Visual Studio also supports multitargeting for C++ projects. You can use the Visual Studio IDE to edit and build projects that were created with older versions of Visual Studio, without upgrading them to use a new version of the toolset. You do need to have the older toolsets installed on your computer. For more information, see [How to use native multi-targeting in Visual Studio](../porting/use-native-multi-targeting.md). For example, in Visual Studio 2015, you can *target* .NET Framework 2.0 but you must use an earlier toolset that supports it. +Visual Studio also supports multitargeting for C++ projects. You can use the latest Visual Studio IDE to edit and build projects created by older versions of Visual Studio. It doesn't require a project upgrade the projects to use a new version of the toolset. It does require the older toolset is installed on your computer. For more information, see [How to use native multi-targeting in Visual Studio](../porting/use-native-multi-targeting.md). For example, in Visual Studio 2015, you can *target* .NET Framework 2.0, but you must use an earlier toolset that supports it. ## 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 such as 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) platform toolset to target the .NET Framework 2.0, 3.0, 3.5, and 4, and the x86/x64 platforms. +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. ### To change the target Framework -1. In Visual Studio, in **Solution Explorer**, select your project. On the menu bar, open the **Project** menu and choose **Unload project**. This unloads the project (.vcxproj) file for your project. +1. In Visual Studio, in **Solution Explorer**, select your project. On the menu bar, open the **Project** menu and choose **Unload project**. This command unloads the project (.vcxproj) file for your project. > [!NOTE] - > A C++ project cannot be loaded while the project file is being modified in Visual Studio. However, you can use another editor such as Notepad to modify the project file while the project is loaded in Visual Studio. Visual Studio will detect that the project file has changed and prompt you to reload the project. + > A C++ project can't be loaded while you edit the project file in Visual Studio. However, you can use another editor such as Notepad to modify the project file while the project is loaded in Visual Studio. Visual Studio will detect that the project file has changed and prompt you to reload the project. 1. On the menu bar, select **File**, **Open**, **File**. In the **Open File** dialog box, navigate to your project folder, and then open the project (.vcxproj) file. @@ -44,19 +44,23 @@ You can extend the target platform further by creating a custom platform toolset 1. In **Solution Explorer**, open the shortcut menu for your project and then choose **Reload Project**. -1. To verify the change, in **Solution Explorer**, right-click to open the shortcut menu for your project (not for your solution) and then choose **Properties** to open your project **Property Pages** dialog box. In the left pane of the dialog box, expand **Configuration Properties** and then select **General**. Verify that **.NET Target Framework Version** shows the new Framework version. +1. To verify the change, on the menu bar, select **Project** > **Properties** to open your project **Property Pages** dialog box. In the dialog box, select the **Configuration Properties** > **General** property page. Verify that **.NET Target Framework Version** shows the new Framework version. ### To change the platform toolset -1. In Visual Studio, in **Solution Explorer**, open the shortcut menu for your project (not for your solution) and then choose **Properties** to open your project **Property Pages** dialog box. +1. In Visual Studio, on the menu bar, select **Project** > **Properties** to open your project **Property Pages** dialog box. -1. In the **Property Pages** dialog box, open the **Configuration** drop-down list and then select **All Configurations**. +1. In the top of the **Property Pages** dialog box, open the **Configuration** drop-down list and then select **All Configurations**. -1. In the left pane of the dialog box, expand **Configuration Properties** and then select **General**. +1. In the dialog box, select the **Configuration Properties** > **General** property page. -1. In the right pane, select **Platform Toolset** and then select the toolset you want from the drop-down list. For example, if you have installed the Visual Studio 2010 toolset, select **Visual Studio 2010 (v100)** to use it for your project. +1. In the properties page, select **Platform Toolset** and then select the toolset you want from the drop-down list. For example, if you've installed the Visual Studio 2010 toolset, select **Visual Studio 2010 (v100)** to use it for your project. -1. Choose the **OK** button. +1. Choose the **OK** button to save your changes. + +## Next Steps + +[Walkthrough: Working with Projects and Solutions (C++)](../ide/walkthrough-working-with-projects-and-solutions-cpp.md) ## See also diff --git a/docs/build/how-to-organize-project-output-files-for-builds.md b/docs/build/how-to-organize-project-output-files-for-builds.md index 896f336529..6de6a60f87 100644 --- a/docs/build/how-to-organize-project-output-files-for-builds.md +++ b/docs/build/how-to-organize-project-output-files-for-builds.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: How to: Organize Project Output Files for Builds" title: "How to: Organize Project Output Files for Builds" ms.date: "05/06/2019" helpviewer_keywords: ["C++, output files", "output files, organizing"] 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 df1869af03..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,8 +1,8 @@ --- 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 @@ -32,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 @@ -63,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/ieee-floating-point-representation.md b/docs/build/ieee-floating-point-representation.md index 265ba6479c..b2f6f290cc 100644 --- a/docs/build/ieee-floating-point-representation.md +++ b/docs/build/ieee-floating-point-representation.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: IEEE Floating-Point Representation" title: "IEEE Floating-Point Representation" ms.date: "05/06/2019" helpviewer_keywords: ["float keyword", "real*8 value", "floating-point numbers, IEEE representation", "double data type, floating-point representation", "IEEE floating point representation", "real*10 value", "long double", "real*4 value"] diff --git a/docs/build/importing-and-exporting-inline-functions.md b/docs/build/importing-and-exporting-inline-functions.md index 4650ba689e..c34b0859a1 100644 --- a/docs/build/importing-and-exporting-inline-functions.md +++ b/docs/build/importing-and-exporting-inline-functions.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Importing and exporting inline functions" title: "Importing and exporting inline functions" ms.date: "11/04/2016" helpviewer_keywords: ["exporting functions [C++], inline functions", "inline functions [C++], importing", "DLLs [C++], importing", "importing functions [C++]", "DLLs [C++], exporting from", "importing inline functions [C++]", "inline functions [C++], exporting", "functions [C++], importing", "functions [C++], exporting"] ms.assetid: 89f488f8-b078-40fe-afd7-80bd7840057b +ms.topic: concept-article --- # Importing and exporting inline functions diff --git a/docs/build/importing-and-exporting.md b/docs/build/importing-and-exporting.md index dc13aa8986..87ecffe020 100644 --- a/docs/build/importing-and-exporting.md +++ b/docs/build/importing-and-exporting.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Importing and Exporting" title: "Importing and Exporting" ms.date: "05/06/2019" helpviewer_keywords: ["DLLs [C++], importing", "exporting DLLs [C++]", "importing DLLs [C++]", "DLLs [C++], exporting from", "__declspec(dllimport) keyword [C++]"] ms.assetid: 7c44c2aa-2117-4cec-9615-a65bfd3f8f7b +ms.topic: concept-article --- # Importing and Exporting diff --git a/docs/build/importing-data-using-declspec-dllimport.md b/docs/build/importing-data-using-declspec-dllimport.md index 1f5338e7fb..eeec7bf2ff 100644 --- a/docs/build/importing-data-using-declspec-dllimport.md +++ b/docs/build/importing-data-using-declspec-dllimport.md @@ -1,16 +1,19 @@ --- -title: "Importing Data Using __declspec(dllimport)" -ms.date: "11/04/2016" +title: "Importing data using __declspec(dllimport)" +description: "How to use __declspec(dllimport) to import DLL data." +ms.date: 09/03/2020 helpviewer_keywords: ["importing data [C++]", "dllimport attribute [C++], data imports", "__declspec(dllimport) keyword [C++]", "importing DLLs [C++], __declspec(dllimport)"] ms.assetid: 0ae70b39-87c7-4181-8be9-e786e0db60b0 +ms.topic: concept-article --- -# Importing Data Using __declspec(dllimport) +# Importing data using `__declspec(dllimport)` In the case of data, using **`__declspec(dllimport)`** is a convenience item that removes a layer of indirection. When you import data from a DLL, you still have to go through the import address table. Before **`__declspec(dllimport)`**, this meant you had to remember to do an extra level of indirection when accessing data exported from the DLL: -``` +```C // project.h -#ifdef _DLL // If accessing the data from inside the DLL +// Define PROJECT_EXPORTS when building your DLL +#ifdef PROJECT_EXPORTS // If accessing the data from inside the DLL ULONG ulDataInDll; #else // If accessing the data from outside the DLL @@ -20,7 +23,7 @@ In the case of data, using **`__declspec(dllimport)`** is a convenience item tha You would then export the data in your .DEF file: -``` +```DEF // project.def LIBRARY project EXPORTS @@ -29,7 +32,7 @@ EXPORTS and access it outside the DLL: -``` +```C if (*ulDataInDll == 0L) { // Do stuff here @@ -40,8 +43,15 @@ When you mark the data as **`__declspec(dllimport)`**, the compiler automaticall To export the data automatically from the DLL, use this declaration: -``` -__declspec(dllexport) ULONG ulDataInDLL; +```C +// project.h +// Define PROJECT_EXPORTS when building your DLL +#ifdef PROJECT_EXPORTS // If accessing the data from inside the DLL + __declspec(dllexport) ULONG ulDataInDLL; + +#else // If accessing the data from outside the DLL + __declspec(dllimport) ULONG ulDataInDLL; +#endif ``` ## See also diff --git a/docs/build/importing-function-calls-using-declspec-dllimport.md b/docs/build/importing-function-calls-using-declspec-dllimport.md index e275b0ec86..4d4472780a 100644 --- a/docs/build/importing-function-calls-using-declspec-dllimport.md +++ b/docs/build/importing-function-calls-using-declspec-dllimport.md @@ -4,6 +4,7 @@ description: "How and why to use __declspec(dllimport) when calling DLL data and ms.date: "05/03/2020" helpviewer_keywords: ["importing function calls [C++]", "dllimport attribute [C++], function call imports", "__declspec(dllimport) keyword [C++]", "function calls [C++], importing"] ms.assetid: 6b53c616-0c6d-419a-8e2a-d2fff20510b3 +ms.topic: concept-article --- # Importing function calls using `__declspec(dllimport)` diff --git a/docs/build/importing-into-an-application-using-declspec-dllimport.md b/docs/build/importing-into-an-application-using-declspec-dllimport.md index 7181a6fbdd..c50718d79d 100644 --- a/docs/build/importing-into-an-application-using-declspec-dllimport.md +++ b/docs/build/importing-into-an-application-using-declspec-dllimport.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Import into an application using __declspec(dllimport)" title: "Import into an application using __declspec(dllimport)" ms.date: "11/04/2016" helpviewer_keywords: ["__declspec(dllimport) keyword [C++]", "importing DLLs [C++], __declspec(dllimport)"] ms.assetid: edb4da4e-f83a-44cf-a668-9239d49dbe42 +ms.topic: how-to --- # Import into an application using __declspec(dllimport) diff --git a/docs/build/importing-into-an-application.md b/docs/build/importing-into-an-application.md index 36f78a3542..c944f53c12 100644 --- a/docs/build/importing-into-an-application.md +++ b/docs/build/importing-into-an-application.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Importing into an Application" title: "Importing into an Application" ms.date: "11/04/2016" helpviewer_keywords: ["DLLs [C++], importing", "importing DLLs [C++], applications", "applications [C++], importing into"] ms.assetid: 9d646466-e12e-4710-8ad9-c819c0375fcc +ms.topic: concept-article --- # Importing into an Application diff --git a/docs/build/importing-using-def-files.md b/docs/build/importing-using-def-files.md index 962604ddbd..877708fe77 100644 --- a/docs/build/importing-using-def-files.md +++ b/docs/build/importing-using-def-files.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Importing Using DEF Files" title: "Importing Using DEF Files" ms.date: "11/04/2016" helpviewer_keywords: ["importing DLLs [C++], DEF files", "def files [C++], importing with", ".def files [C++], importing with", "dllimport attribute [C++], DEF files", "DLLs [C++], DEF files"] ms.assetid: aefdbf50-f603-488a-b0d7-ed737bae311d +ms.topic: concept-article --- # Importing Using DEF Files diff --git a/docs/build/improving-compiler-throughput.md b/docs/build/improving-compiler-throughput.md index 486837f862..3da2de62fc 100644 --- a/docs/build/improving-compiler-throughput.md +++ b/docs/build/improving-compiler-throughput.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Improving Compiler Throughput" title: "Improving Compiler Throughput" ms.date: "11/04/2016" helpviewer_keywords: ["throughput, C++ compiler", "cl.exe compiler, performance", "performance, compiler", "cl.exe compiler, throughput"] ms.assetid: ba5f884e-9037-4a92-b10e-fc2a3836c5bf +ms.topic: concept-article --- # Improving Compiler Throughput diff --git a/docs/build/kinds-of-dlls.md b/docs/build/kinds-of-dlls.md index 4d16fbadd8..425b98c17c 100644 --- a/docs/build/kinds-of-dlls.md +++ b/docs/build/kinds-of-dlls.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Kinds of DLLs" title: "Kinds of DLLs" ms.date: "05/06/2019" helpviewer_keywords: ["MFC DLLs [C++], types", "DLLs [C++], types", "DLLs [C++], MFC"] diff --git a/docs/build/launch-vs-schema-reference-cpp.md b/docs/build/launch-vs-schema-reference-cpp.md index 6b44bc0655..290cc1a1ce 100644 --- a/docs/build/launch-vs-schema-reference-cpp.md +++ b/docs/build/launch-vs-schema-reference-cpp.md @@ -1,89 +1,149 @@ --- title: "launch.vs.json schema reference (C++)" -ms.date: "08/20/2019" +description: "Describes the schema elements for the `launch.vs.json` file" +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](/cpp/build/configure-cmake-debugging-sessions). +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**| -|`name`|string|Specifies the name of the entry in the Debug target dropdown.| -|`type`|string|Specifies whether the project is a dll or .exe (Defaults to .exe)| -|`project`|string|Specifies the relative path to the project file.| -|`projectTarget`|string|Specifies the optional target invoked when building `project`. This `projectTarget` must exist already and match the name in the **Debug Target** dropdown.| -|`debugType`|string|Specifies the debugging mode according to the type of code (native, managed, or mixed). This will automatically be detected unless this parameter is set. Allowed values: "native", "managed", "mixed".| -|`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".| -|`args`|array|Specifies the command-line arguments passed to the launched program.| -|`currentDir`|string|Specifies the full directory path to the Build Target. This will automatically be detected unless this parameter is set.| -|`noDebug`|boolean|Specifies whether to debug the launched program. The default value for this parameter is **`false`** if not specified.| -|`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.| -|`env`|array| Specifies a key-value list of custom environment variables. env:{"myEnv":"myVal"}.| -|`portName`|string|Specifies the name of port when attaching to a running process.| -|`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. +| 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|.natvis file to be used when debugging this process. This option is not compatible with GDB pretty printing. See "showDisplayString" if using this setting.| -|`showDisplayString`|boolean|When a visualizerFile is specified, showDisplayString will enable the display string. Turning on this option can cause slower 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.| -|`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. Default value is the remote workspace root, unless overridden in the *CMakeLists.txt* file.| -|`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 in order 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" in order 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. Defaults to **`false`**. NOTE: 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 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: -|||| -|-|-|-| -|`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: -|||| -|-|-|-| -|`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: -|||| -|-|-|-| -|`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/linking-an-executable-to-a-dll.md b/docs/build/linking-an-executable-to-a-dll.md index bdc0bfddfb..05f822e898 100644 --- a/docs/build/linking-an-executable-to-a-dll.md +++ b/docs/build/linking-an-executable-to-a-dll.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Link an executable to a DLL" title: "Link an executable to a DLL" ms.date: "08/22/2019" helpviewer_keywords: ["run time [C++], linking", "dynamic load linking [C++]", "linking [C++], DLLs", "DLLs [C++], linking", "implicit linking [C++]", "explicit linking [C++]", "executable files [C++], linking to DLLs", "loading DLLs [C++]"] diff --git a/docs/build/localized-resources-in-mfc-applications-satellite-dlls.md b/docs/build/localized-resources-in-mfc-applications-satellite-dlls.md index 60a16be865..007d519f7f 100644 --- a/docs/build/localized-resources-in-mfc-applications-satellite-dlls.md +++ b/docs/build/localized-resources-in-mfc-applications-satellite-dlls.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Localized Resources in MFC Applications: Satellite DLLs" title: "Localized Resources in MFC Applications: Satellite DLLs" ms.date: "11/04/2016" helpviewer_keywords: ["multiple language support [C++]", "localization [C++], MFC resources", "localized resources [C++]", "MFC DLLs [C++], localizing", "DLLs [C++], localizing MFC", "resources [MFC], localizing", "resource-only DLLs [C++]", "resource-only DLLs [C++], MFC applications", "satellite DLLs [C++]"] 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 e0c77246e7..0000000000 --- a/docs/build/manifest-generation-at-the-command-line.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -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 2e002efb84..0000000000 --- a/docs/build/manifest-generation-in-visual-studio.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -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 new file mode 100644 index 0000000000..47d963209c Binary files /dev/null and b/docs/build/media/add-configure-preset-to-cmakepresets.png differ diff --git a/docs/build/media/add-reference-to-walkthrough.png b/docs/build/media/add-reference-to-walkthrough.png new file mode 100644 index 0000000000..e158d40b48 Binary files /dev/null and b/docs/build/media/add-reference-to-walkthrough.png differ diff --git a/docs/build/media/additional-header-unit-dependencies-setting.png b/docs/build/media/additional-header-unit-dependencies-setting.png new file mode 100644 index 0000000000..d2834ce2fa Binary files /dev/null and b/docs/build/media/additional-header-unit-dependencies-setting.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/change-compile-as.png b/docs/build/media/change-compile-as.png new file mode 100644 index 0000000000..8d92a9d7d0 Binary files /dev/null and b/docs/build/media/change-compile-as.png differ diff --git a/docs/build/media/change-item-type.png b/docs/build/media/change-item-type.png new file mode 100644 index 0000000000..3255f44d4e Binary files /dev/null and b/docs/build/media/change-item-type.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-add-config-icon-with-target-dialog.png b/docs/build/media/cmake-add-config-icon-with-target-dialog.png new file mode 100644 index 0000000000..c0ea187cb8 Binary files /dev/null and b/docs/build/media/cmake-add-config-icon-with-target-dialog.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-settings-editor2.png b/docs/build/media/cmake-settings-editor2.png new file mode 100644 index 0000000000..2e4a3230c2 Binary files /dev/null and b/docs/build/media/cmake-settings-editor2.png differ diff --git a/docs/build/media/cmake-targets-add-debug-configuration.png b/docs/build/media/cmake-targets-add-debug-configuration.png index 38762cfc42..c8156ac165 100644 Binary files a/docs/build/media/cmake-targets-add-debug-configuration.png and b/docs/build/media/cmake-targets-add-debug-configuration.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 new file mode 100644 index 0000000000..673ddd555b Binary files /dev/null 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/empty-project-option.png b/docs/build/media/empty-project-option.png new file mode 100644 index 0000000000..4232654540 Binary files /dev/null and b/docs/build/media/empty-project-option.png 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/enable-cmakepresets.png b/docs/build/media/enable-cmakepresets.png new file mode 100644 index 0000000000..f2b46318ff Binary files /dev/null and b/docs/build/media/enable-cmakepresets.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/public-include-module-directories-setting.png b/docs/build/media/public-include-module-directories-setting.png new file mode 100644 index 0000000000..a6539264b4 Binary files /dev/null and b/docs/build/media/public-include-module-directories-setting.png differ diff --git a/docs/build/media/remote-cmake-app.png b/docs/build/media/remote-cmake-app.png new file mode 100644 index 0000000000..f44190c240 Binary files /dev/null and b/docs/build/media/remote-cmake-app.png differ diff --git a/docs/build/media/remote-debugger-options.png b/docs/build/media/remote-debugger-options.png new file mode 100644 index 0000000000..4f7cc1eaec Binary files /dev/null and b/docs/build/media/remote-debugger-options.png differ diff --git a/docs/build/media/set-cpp-language-latest.png b/docs/build/media/set-cpp-language-latest.png new file mode 100644 index 0000000000..ea67b165be Binary files /dev/null and b/docs/build/media/set-cpp-language-latest.png differ diff --git a/docs/build/media/set-header-unit-library-settings.png b/docs/build/media/set-header-unit-library-settings.png new file mode 100644 index 0000000000..2a2c423fcd Binary files /dev/null and b/docs/build/media/set-header-unit-library-settings.png differ diff --git a/docs/build/media/solution-explorer-switch-view.png b/docs/build/media/solution-explorer-switch-view.png new file mode 100644 index 0000000000..a8723d7474 Binary files /dev/null and b/docs/build/media/solution-explorer-switch-view.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/startup-item.png b/docs/build/media/startup-item.png new file mode 100644 index 0000000000..f16d403fb4 Binary files /dev/null and b/docs/build/media/startup-item.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/target-system-dropdown.png b/docs/build/media/target-system-dropdown.png new file mode 100644 index 0000000000..a09eead210 Binary files /dev/null and b/docs/build/media/target-system-dropdown.png differ diff --git a/docs/build/media/target-system-selections.png b/docs/build/media/target-system-selections.png new file mode 100644 index 0000000000..6947285cdd Binary files /dev/null and b/docs/build/media/target-system-selections.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-additional-module-dependencies.png b/docs/build/media/vs2019-additional-module-dependencies.png new file mode 100644 index 0000000000..73dff3c604 Binary files /dev/null and b/docs/build/media/vs2019-additional-module-dependencies.png differ diff --git a/docs/build/media/vs2019-cmake-manage-configurations-arm.png b/docs/build/media/vs2019-cmake-manage-configurations-arm.png new file mode 100644 index 0000000000..0b2abb81c7 Binary files /dev/null and b/docs/build/media/vs2019-cmake-manage-configurations-arm.png differ diff --git a/docs/build/media/vs2019-cmake-manage-configurations.png b/docs/build/media/vs2019-cmake-manage-configurations.png index 057dcefd8c..07a29fdf3b 100644 Binary files a/docs/build/media/vs2019-cmake-manage-configurations.png and b/docs/build/media/vs2019-cmake-manage-configurations.png differ diff --git a/docs/build/media/vs2019-scan-module-dependencies.png b/docs/build/media/vs2019-scan-module-dependencies.png new file mode 100644 index 0000000000..8541eff487 Binary files /dev/null and b/docs/build/media/vs2019-scan-module-dependencies.png differ diff --git a/docs/build/media/vs2019-translate-includes-option.png b/docs/build/media/vs2019-translate-includes-option.png new file mode 100644 index 0000000000..782975cd08 Binary files /dev/null and b/docs/build/media/vs2019-translate-includes-option.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 85250f0937..3cba0d0efa 100644 --- a/docs/build/modify-project-properties-without-changing-project-file.md +++ b/docs/build/modify-project-properties-without-changing-project-file.md @@ -1,38 +1,40 @@ --- +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"] +ms.topic: how-to --- # How to: Modify C++ project properties and targets without changing the project file -You can override project properties and targets from the MSBuild command prompt without changing the project file. This is useful when you want to apply some properties temporarily or occasionally. It assumes some knowledge of MSBuild. For more information, see [MSBUild](https://docs.microsoft.com/visualstudio/msbuild/msbuild). +You can override project properties and targets from the MSBuild command prompt without changing the project file. This is useful when you want to apply some properties temporarily or occasionally. It assumes some knowledge of MSBuild. For more information, see [MSBuild](/visualstudio/msbuild/msbuild). > [!IMPORTANT] > You can use the XML Editor in Visual Studio, or any text editor, to create the .props or .targets file. Don't use the **Property Manager** in this scenario because it adds the properties to the project file. *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/module-states-of-a-regular-dll-dynamically-linked-to-mfc.md b/docs/build/module-states-of-a-regular-dll-dynamically-linked-to-mfc.md index b3fc59022f..de98e84705 100644 --- a/docs/build/module-states-of-a-regular-dll-dynamically-linked-to-mfc.md +++ b/docs/build/module-states-of-a-regular-dll-dynamically-linked-to-mfc.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Module States of a Regular MFC DLL Dynamically Linked to MFC" title: "Module States of a Regular MFC DLL Dynamically Linked to MFC" ms.date: "11/04/2016" helpviewer_keywords: ["regular MFC DLLs [C++], dynamically linked to MFC", "module states [C++]", "MFC DLLs [C++], regular MFC DLLs", "module states [C++], regular MFC DLLs dynamically linked to", "DLLs [C++], module states"] diff --git a/docs/build/msbuild-visual-cpp.md b/docs/build/msbuild-visual-cpp.md index 5e1eb6f780..0066c81f6d 100644 --- a/docs/build/msbuild-visual-cpp.md +++ b/docs/build/msbuild-visual-cpp.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: MSBuild on the command line - C++" title: "MSBuild on the command line - C++" ms.date: "12/12/2018" helpviewer_keywords: ["MSBuild"] diff --git a/docs/build/mutual-imports.md b/docs/build/mutual-imports.md index 79fa1a9a2c..47743d4ff1 100644 --- a/docs/build/mutual-imports.md +++ b/docs/build/mutual-imports.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Mutual Imports" title: "Mutual Imports" ms.date: "11/04/2016" helpviewer_keywords: ["mutual DLL imports [C++]", "AFX_DATA", "importing DLLs [C++], mutual imports", "mutually importing executable files [C++]", "AFX_EXT_CLASS macro", "circular imports", "_AFXEXT preprocessor symbol", "DLLs [C++], importing", "executable files [C++], importing", "extension DLLs [C++], mutual imports", "exporting DLLs [C++], mutual imports"] @@ -24,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/non-mfc-dlls-overview.md b/docs/build/non-mfc-dlls-overview.md index f780e12500..ff377f90b1 100644 --- a/docs/build/non-mfc-dlls-overview.md +++ b/docs/build/non-mfc-dlls-overview.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Non-MFC DLLs: Overview" title: "Non-MFC DLLs: Overview" ms.date: "11/04/2016" helpviewer_keywords: ["non-MFC DLLs [C++]", "DLLs [C++], non-MFC"] ms.assetid: 1ed5d1ee-e20c-47d7-801d-87ea26a73842 +ms.topic: concept-article --- # Non-MFC DLLs: Overview diff --git a/docs/build/open-folder-projects-cpp.md b/docs/build/open-folder-projects-cpp.md index 4664d99484..006635d28b 100644 --- a/docs/build/open-folder-projects-cpp.md +++ b/docs/build/open-folder-projects-cpp.md @@ -1,18 +1,19 @@ --- title: "Open Folder support for C++ build systems in Visual Studio" -ms.date: "12/02/2019" +description: "Learn more about: Open Folder support for C++ build systems in Visual Studio" +ms.date: 12/02/2019 helpviewer_keywords: ["Open Folder Projects in Visual Studio"] -ms.assetid: abd1985e-3717-4338-9e80-869db5435175 +ms.topic: how-to --- # Open Folder support for C++ build systems in Visual Studio -::: moniker range="vs-2015" +::: moniker range="msvc-140" The Open Folder feature is available in Visual Studio 2017 and later. ::: moniker-end -::: moniker range=">=vs-2017" +::: moniker range=">=msvc-150" In Visual Studio 2017 and later, the "Open Folder" feature enables you to open a folder of source files and immediately start coding with support for IntelliSense, browsing, refactoring, debugging, and so on. As you edit, create, move, or delete files, Visual Studio tracks the changes automatically and continuously updates its IntelliSense index. No .sln or .vcxproj files are loaded; if needed, you can specify custom tasks as well as build and launch parameters through simple .json files. This feature enables you to integrate any third-party build system into Visual Studio. For general information about Open Folder, see [Develop code in Visual Studio without projects or solutions](/visualstudio/ide/develop-code-in-visual-studio-without-projects-or-solutions). @@ -24,7 +25,7 @@ CMake is integrated in the Visual Studio IDE as a component of the C++ desktop w To use the Visual Studio IDE with a build system or compiler toolset that is not directly supported from the main menu select **File | Open | Folder** or press **Ctrl + Shift + Alt + O**. Navigate to the folder that contains your source code files. To build the project, configure IntelliSense and set debugging parameters, you add three JSON files: -| | | +| File | Description | |-|-| |CppProperties.json|Specify custom configuration information for browsing. Create this file, if needed, in your root project folder. (Not used in CMake projects.)| |tasks.vs.json|Specify custom build commands. Accessed via the **Solution Explorer** context menu item **Configure Tasks**.| @@ -34,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: @@ -73,11 +74,12 @@ 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 { - { + "configurations": [ + { "inheritEnvironments": [ "mingw_64" ], @@ -99,22 +101,23 @@ If you add the MinGW-W64 configuration, the JSON looks this this: } ] } + ] } ``` -Note the `environments` block. It defines properties that behave like environment variables and are available not only in the *CppProperties.json* file, but also in the other configuration files *task.vs.json* and *launch.vs.json*. The `Mingw64` configuration inherits the `mingw_w64` environment, and uses its `INCLUDE` property to specify the value for `includePath`. You can add other paths to this array property as needed.` +Note the `environments` block. It defines properties that behave like environment variables and are available not only in the *CppProperties.json* file, but also in the other configuration files *task.vs.json* and *launch.vs.json*. The `Mingw64` configuration inherits the `mingw_w64` environment, and uses its `INCLUDE` property to specify the value for `includePath`. You can add other paths to this array property as needed. The `intelliSenseMode` property is set to a value appropriate for GCC. For more information on all these properties, see [CppProperties schema reference](cppproperties-schema-reference.md). 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. @@ -122,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*. @@ -144,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**. @@ -191,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 76902cd882..b0530ca07e 100644 --- a/docs/build/optimization-best-practices.md +++ b/docs/build/optimization-best-practices.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Optimization best practices" title: "Optimization best practices" ms.date: "05/06/2019" helpviewer_keywords: ["C++, optimization", "optimization, best practices"] ms.assetid: f3433148-7255-4ca6-8a4f-7c31aac88508 +ms.topic: best-practice --- # Optimization best practices @@ -32,7 +34,7 @@ It is also strongly recommended to generate debug symbols, even with optimized r The **`/Op`** compiler option has been removed, and the following four compiler options dealing with floating point optimizations have been added: -||| +|Option|Description| |-|-| |**`/fp:precise`**|This is the default recommendation and should be used in most cases.| |**`/fp:fast`**|Recommended if performance is of the utmost importance, for example in games. This will result in the fastest performance.| @@ -93,8 +95,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/optimization-pragmas-and-keywords.md b/docs/build/optimization-pragmas-and-keywords.md index 591ec9a911..41f664791b 100644 --- a/docs/build/optimization-pragmas-and-keywords.md +++ b/docs/build/optimization-pragmas-and-keywords.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Optimization Pragmas and Keywords" title: "Optimization Pragmas and Keywords" ms.date: "11/04/2016" helpviewer_keywords: ["keywords [C++], for optimization", "pragmas, for optimization", "optimization, keywords and pragmas"] diff --git a/docs/build/optimizing-your-code.md b/docs/build/optimizing-your-code.md index 2bd278d810..590f7b8fae 100644 --- a/docs/build/optimizing-your-code.md +++ b/docs/build/optimizing-your-code.md @@ -1,7 +1,9 @@ --- +description: "Learn more about: Optimizing your code" title: "Optimizing Your Code" ms.date: "05/06/2019" helpviewer_keywords: ["performance, optimizing code", "optimization", "cl.exe compiler, performance", "optimization, C++ code", "code, optimizing", "performance, compiler"] +ms.topic: concept-article --- # Optimizing your code @@ -68,7 +70,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 7bd91b1f5b..3e61981e84 100644 --- a/docs/build/overview-of-arm-abi-conventions.md +++ b/docs/build/overview-of-arm-abi-conventions.md @@ -1,29 +1,30 @@ --- +description: "Learn more about: Overview of ARM32 ABI Conventions" title: "Overview of ARM ABI Conventions" ms.date: "07/11/2018" 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. @@ -33,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 @@ -90,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| |-------------|-------------|-----------|---------------|----------| @@ -120,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 @@ -165,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 @@ -205,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/pgoautosweep.md b/docs/build/pgoautosweep.md index d9db2769c5..8988529bcb 100644 --- a/docs/build/pgoautosweep.md +++ b/docs/build/pgoautosweep.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: PgoAutoSweep" title: "PgoAutoSweep" ms.date: "07/02/2019" f1_keywords: ["PgoAutoSweep", "PogoAutoSweepA", "PogoAutoSweepW"] diff --git a/docs/build/pgomgr.md b/docs/build/pgomgr.md index 4edf46ba34..42f0859a1f 100644 --- a/docs/build/pgomgr.md +++ b/docs/build/pgomgr.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: pgomgr" title: "pgomgr" ms.date: "03/14/2018" helpviewer_keywords: ["pgomgr program", "profile-guided optimizations, pgomgr"] diff --git a/docs/build/pgosweep.md b/docs/build/pgosweep.md index 8377a86ca9..af007f40dd 100644 --- a/docs/build/pgosweep.md +++ b/docs/build/pgosweep.md @@ -1,52 +1,64 @@ --- title: "pgosweep" -ms.date: "03/14/2018" +description: "Use the pgosweep command to write profile data to a PGC file for use in profile-guided optimization." +ms.date: 10/23/2020 helpviewer_keywords: ["pgosweep program", "profile-guided optimizations, pgosweep"] -ms.assetid: f39dd3b7-1cd9-4c3b-8e8b-fb794744b757 --- # pgosweep -Used in profile-guided optimization to write all profile data from a running program to the .pgc file. +Used in profile-guided optimization to write all profile data from a running program to the PGC file. ## Syntax -> **pgosweep** [*options*] *image* *pgcfile* +> **`pgosweep`** [*options*] *image* *pgcfile* ### Parameters -*options*
+*options*\ (Optional) The valid values for *options* are: -- **/?** or **/help** displays the help message. +- **`/?`** or **`/help`** displays the help message. -- **/noreset** preserves the count in the runtime data structures. +- **`/reset`** resets counts to zero after sweep. This behavior is the default. -*image*
-The full path of an .exe or .dll file that was created by using the [/GENPROFILE](reference/genprofile-fastgenprofile-generate-profiling-instrumented-build.md), [/FASTGENPROFILE](reference/genprofile-fastgenprofile-generate-profiling-instrumented-build.md), or [/LTCG:PGINSTRUMENT](reference/ltcg-link-time-code-generation.md) option. +- **`/pid:n`** only sweeps the specified PID, where *n* is the PID number. -*pgcfile*
-The .pgc file where this command writes out the data counts. +- **`/wait`** waits for the specified PID to terminate before collecting counts. + +- **`/onlyzero`** doesn't save a PGC file, only zero counts. + +- **`/pause`** pauses count collection on the system. + +- **`/resume`** resumes count collection on the system. + +- **`/noreset`** preserves the count in the runtime data structures. + +*image*\ +The full path of an EXE or DLL file that was created by using the [`/GENPROFILE`](reference/genprofile-fastgenprofile-generate-profiling-instrumented-build.md), [`/FASTGENPROFILE`](reference/genprofile-fastgenprofile-generate-profiling-instrumented-build.md), or [`/LTCG:PGINSTRUMENT`](reference/ltcg-link-time-code-generation.md) option. + +*pgcfile*\ +The PGC file where this command writes out the data counts. ## Remarks -The **pgosweep** command works on programs that were built by using the [/GENPROFILE or /FASTGENPROFILE](reference/genprofile-fastgenprofile-generate-profiling-instrumented-build.md) option, or the deprecated [/LTCG:PGINSTRUMENT](reference/ltcg-link-time-code-generation.md) option. It interrupts a running program and writes the profile data to a new .pgc file. By default, the command resets counts after each write operation. If you specify the **/noreset** option, the command will record the values, but not reset them in the running program. This option gives you duplicate data if you retrieve the profile data later. +The **`pgosweep`** command works on programs that were built by using the [`/GENPROFILE` or `/FASTGENPROFILE`](reference/genprofile-fastgenprofile-generate-profiling-instrumented-build.md) option, or the deprecated [`/LTCG:PGINSTRUMENT`](reference/ltcg-link-time-code-generation.md) option. It interrupts a running program and writes the profile data to a new PGC file. By default, the command resets counts after each write operation. If you specify the **`/noreset`** option, the command will record the values, but not reset them in the running program. This option gives you duplicate data if you retrieve the profile data later. -An alternative use for **pgosweep** is to retrieve profile information just for the normal operation of the application. For example, you could run **pgosweep** shortly after you start the application and discard that file. This would remove profile data associated with startup costs. Then, you can run **pgosweep** before ending the application. Now the collected data has profile information only from the time the user could interact with the program. +An alternative use for **`pgosweep`** is to retrieve profile information just for the normal operation of the application. For example, you could run **`pgosweep`** shortly after you start the application and discard that file. This command would remove profile data associated with startup costs. Then, you can run **`pgosweep`** before ending the application. Now the collected data has profile information only from the time the user could interact with the program. -When you name a .pgc file (by using the *pgcfile* parameter) you can use the standard format, which is *appname!n*.pgc. If you use this format, the compiler automatically finds this data in the **/LTCG /USEPROFILE** or **/LTCG:PGO** phase. If you do not use the standard format, you must use [pgomgr](pgomgr.md) to merge the .pgc files. +When you name a PGC file (by using the *pgcfile* parameter) you can use the standard format, which is *`appname!n.pgc`*. The *n* represents an increasing numeric value for each file. If you use this format, the compiler automatically finds this data in the **`/LTCG /USEPROFILE`** or **`/LTCG:PGO`** phase. If you don't use the standard format, you must use [`pgomgr`](pgomgr.md) to merge the PGC files. > [!NOTE] -> You can start this tool only from a Visual Studio developer command prompt. You cannot start it from a system command prompt or from File Explorer. +> You can start this tool only from a Visual Studio developer command prompt. You can't start it from a system command prompt or from File Explorer. -For information on how to capture the profile data from within your executable, see [PgoAutoSweep](pgoautosweep.md). +For information on how to capture the profile data from within your executable, see [`PgoAutoSweep`](pgoautosweep.md). ## Example -In this example command, **pgosweep** writes the current profile information for myapp.exe to myapp!1.pgc. +In this example command, **`pgosweep`** writes the current profile information for *`myapp.exe`* to *`myapp!1.pgc`*. `pgosweep myapp.exe myapp!1.pgc` ## See also -[Profile-Guided Optimizations](profile-guided-optimizations.md)
-[PgoAutoSweep](pgoautosweep.md)
+[Profile-Guided Optimizations](profile-guided-optimizations.md)\ +[PgoAutoSweep](pgoautosweep.md) diff --git a/docs/build/profile-guided-optimizations.md b/docs/build/profile-guided-optimizations.md index 0889597649..065565ef0d 100644 --- a/docs/build/profile-guided-optimizations.md +++ b/docs/build/profile-guided-optimizations.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Profile-guided optimizations" title: "Profile-guided optimizations" ms.date: "04/23/2019" helpviewer_keywords: ["profile-guided optimizations", "optimization, profile-guided [C++]"] @@ -8,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 99f5f569b1..3456a29290 100644 --- a/docs/build/project-property-inheritance.md +++ b/docs/build/project-property-inheritance.md @@ -10,17 +10,35 @@ The Visual Studio native project system is based on MSBuild. MSBuild defines fil ## The .vcxproj file, .props files and .targets files -Project properties are stored either directly in the project file (*`.vcxproj`*) or in other *`.targets`* or *`.props`* files that the project file imports and which supply default values. For Visual Studio 2015, these files are located in *`\Program Files (x86)\MSBuild\Microsoft.Cpp\v4.0\V140`*. For Visual Studio 2017, these files are located in *`\Program Files (x86)\Microsoft Visual Studio\2017\\Common7\IDE\VC\VCTargets`*, where *``* is the Visual Studio edition installed. In Visual Studio 2019, these files are located in *`\Program Files (x86)\Microsoft Visual Studio\2019\\MSBuild\Microsoft\VC\v160`*. Properties are also stored in any custom *`.props`* files that you might add to your own project. We highly recommend that you NOT edit those files manually. Instead, use the property pages in the IDE to modify all properties, especially the ones that participate in inheritance, unless you have a deep understanding of MSBuild. +::: moniker range="msvc-140" -As shown earlier, the same property for the same configuration may be assigned a different value in these different files. When you build a project, the MSBuild engine evaluates the project file and all the imported files in a well-defined order (described below). As each file is evaluated, any property values defined in that file will override the existing values. Any values that aren't specified are inherited from files that were evaluated earlier. When you set a property with property pages, it's also important to pay attention to where you set it. If you set a property to "X" in a *`.props`* file, but the property is set to "Y" in the project file, then the project will build with the property set to "Y". If the same property is set to "Z" on a project item, such as a *`.cpp`* file, then the MSBuild engine will use the "Z" value. +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 2015 project files in a locale-specific folder under the base directory, *`%ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\v140`*. + +::: moniker-end + +::: moniker range="msvc-150" + +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 2017 project files in a locale-specific folder under the base directory, *`%VSINSTALLDIR%Common7\IDE\VC\VCTargets\`*. + +::: moniker-end + +::: 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. + +::: moniker-end + +Properties are also stored in any custom *`.props`* files that you might add to your own project. We highly recommend that you *NOT* edit those files manually. Instead, use the property pages in the IDE to modify all properties, especially the ones that participate in inheritance, unless you have a deep understanding of MSBuild and *`.vcxproj`* files. + +As shown earlier, the same property for the same configuration may be assigned a different value in these different files. When you build a project, the MSBuild engine evaluates the project file and all the imported files in a well-defined order that's described later. As each file is evaluated, any property values defined in that file will override the existing values. Any values that aren't specified are inherited from files that were evaluated earlier. When you set a property with property pages, it's also important to pay attention to where you set it. If you set a property to "X" in a *`.props`* file, but the property is set to "Y" in the project file, then the project will build with the property set to "Y". If the same property is set to "Z" on a project item, such as a *`.cpp`* file, then the MSBuild engine will use the "Z" value. Here's the basic inheritance tree: -1. Default settings from the MSBuild CPP Toolset (..\Program Files\MSBuild\Microsoft.Cpp\v4.0\Microsoft.Cpp.Default.props, which is imported by the *`.vcxproj`* file.) +1. Default settings from the MSBuild CPP Toolset (the *`Microsoft.Cpp.Default.props`* file in the base directory, which is imported by the *`.vcxproj`* file.) 1. Property sheets -1. *`.vcxproj`* file. (Can override the default and property sheet settings.) +1. *`.vcxproj`* file. (This file can override the default and property sheet settings.) 1. Items metadata @@ -57,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 df65acbe10..156cd4acfd 100644 --- a/docs/build/projects-and-build-systems-cpp.md +++ b/docs/build/projects-and-build-systems-cpp.md @@ -1,14 +1,15 @@ --- title: "C/C++ projects and build systems in Visual Studio" -ms.description: "Use Visual Studio to compile and build C++ projects for Windows, ARM or Linux based on any project system." +description: "Use Visual Studio to compile and build C++ projects for Windows, ARM, or Linux based on any project system." 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 -You can use Visual Studio to edit, compile and build any C++ code base with full IntelliSense support without having to convert that code into a Visual Studio project or compile with the MSVC toolset. For example, you can edit a cross-platform CMake project in Visual Studio on a Windows machine, then compile it for Linux using g++ on a remote Linux machine. +You can use Visual Studio to edit, compile, and build any C++ code base with full IntelliSense support without having to convert that code into a Visual Studio project or compile with the MSVC toolset. For example, you can edit a cross-platform CMake project in Visual Studio on a Windows machine, then compile it for Linux using g++ on a remote Linux machine. ## C++ compilation @@ -22,7 +23,7 @@ Basic C++ compilation involves three main steps: ## The MSVC toolset -The Microsoft C++ compiler, linker, standard libraries, and related utilities comprise 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 standalone package for free from the [Build Tools for Visual Studio 2019 download location](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*: @@ -30,17 +31,17 @@ You can build simple programs by invoking the MSVC compiler (cl.exe) directly fr cl /EHsc hello.cpp ``` -Note that here the compiler (cl.exe) automatically invokes the C++ preprocessor and the linker to produce the final output file. For more information, see [Building on the command line](building-on-the-command-line.md). +Here the compiler (cl.exe) automatically invokes the C++ preprocessor and the linker to produce the final output file. For more information, see [Building on the command line](building-on-the-command-line.md). ## Build systems and projects -Most real-world programs use some kind of *build system* to manage complexities of compiling multiple source files for multiple configurations (i.e. debug vs. release), multiple platforms (x86, x64, ARM, and so on), custom build steps, and even multiple executables that must be compiled in a certain order. You make settings in a build configuration file(s), and the build system accepts that file as input before it invoke the compiler. The set of source code files and build configuration files needed to build an executable file is called a *project*. +Most real-world programs use some kind of *build system* to manage complexities of compiling multiple source files for multiple configurations (debug vs. release), multiple platforms (x86, x64, ARM, and so on), custom build steps, and even multiple executables that must be compiled in a certain order. You make settings in a build configuration file(s), and the build system accepts that file as input before it invokes the compiler. The set of source code files and build configuration files needed to build an executable file is called a *project*. The following list shows various options for Visual Studio Projects - C++: - create a Visual Studio project by using the Visual Studio IDE and configure it by using property pages. Visual Studio projects produce programs that run on Windows. For an overview, see [Compiling and Building](/visualstudio/ide/compiling-and-building-in-visual-studio) in the Visual Studio documentation. -- open a folder that contains a CMakeLists.txt file. CMake support is integrated into Visual Studio. You can use the IDE to edit, test and debug without modifying the CMake files in any way. This enables you to work in the same CMake project as others who might be using different editors. CMake is the recommended approach for cross-platform development. For more information, see [CMake projects](cmake-projects-in-visual-studio.md). +- open a folder that contains a CMakeLists.txt file. CMake support is integrated into Visual Studio. You can use the IDE to edit, test, and debug without modifying the CMake files in any way. This enables you to work in the same CMake project as others who might be using different editors. CMake is the recommended approach for cross-platform development. For more information, see [CMake projects](cmake-projects-in-visual-studio.md). - open a loose folder of source files with no project file. Visual Studio will use heuristics to build the files. This is an easy way to compile and run small console applications. For more information, see [Open Folder projects](open-folder-projects-cpp.md). @@ -50,45 +51,45 @@ The following list shows various options for Visual Studio Projects - C++: ## MSBuild from the command line -You can invoke MSBuild from the command line by passing it a .vcxproj file along with command-line options. This approach requires a good understanding of MSBuild, and is recommended only when absolutely necessary. For more information, see [MSBuild](msbuild-visual-cpp.md). +You can invoke MSBuild from the command line by passing it a .vcxproj file along with command-line options. This approach requires a good understanding of MSBuild, and is recommended only when necessary. For more information, see [MSBuild](msbuild-visual-cpp.md). ## In This Section -[Visual Studio projects](creating-and-managing-visual-cpp-projects.md) +[Visual Studio projects](creating-and-managing-visual-cpp-projects.md)\ How to create, configure, and build C++ projects in Visual Studio using its native build system (MSBuild). -[CMake projects](cmake-projects-in-visual-studio.md) +[CMake projects](cmake-projects-in-visual-studio.md)\ How to code, build, and deploy CMake projects in Visual Studio. -[Open Folder projects](open-folder-projects-cpp.md) -How to use Visual Studio to code, build and deploy C++ projects based on any arbitrary build system, or no build system. at all. +[Open Folder projects](open-folder-projects-cpp.md)\ +How to use Visual Studio to code, build, and deploy C++ projects based on any arbitrary build system, or no build system at all. -[Release builds](release-builds.md) +[Release builds](release-builds.md)\ How to create and troubleshoot optimized release builds for deployment to end users. -[Use the MSVC toolset from the command line](building-on-the-command-line.md)
+[Use the MSVC toolset from the command line](building-on-the-command-line.md)\ Discusses how to use the C/C++ compiler and build tools directly from the command line rather than using the Visual Studio IDE. -[Building DLLs in Visual Studio](dlls-in-visual-cpp.md) -How to create, debug and deploy C/C++ DLLs (shared libraries) in Visual Studio. +[Building DLLs in Visual Studio](dlls-in-visual-cpp.md)\ +How to create, debug, and deploy C/C++ DLLs (shared libraries) in Visual Studio. -[Walkthrough: Creating and Using a Static Library](walkthrough-creating-and-using-a-static-library-cpp.md) -How to create a .lib binary file. +[Walkthrough: Creating and Using a Static Library](walkthrough-creating-and-using-a-static-library-cpp.md)\ +How to create a **.lib** binary file. -[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)\ Describes the deployment model for Windows Desktop applications, based on the idea of isolated applications and side-by-side assemblies. -[Configure C++ projects for 64-bit, x64 targets](configuring-programs-for-64-bit-visual-cpp.md) +[Configure C++ projects for 64-bit, x64 targets](configuring-programs-for-64-bit-visual-cpp.md)\ How to target 64-bit x64 hardware with the MSVC build tools. -[Configure C++ projects for ARM processors](configuring-programs-for-arm-processors-visual-cpp.md) +[Configure C++ projects for ARM processors](configuring-programs-for-arm-processors-visual-cpp.md)\ How to use the MSVC build tools to target ARM hardware. -[Optimizing Your Code](optimizing-your-code.md) +[Optimizing Your Code](optimizing-your-code.md)\ How to optimize your code in various ways including program guided optimizations. -[Configuring Programs for Windows XP](configuring-programs-for-windows-xp.md) +[Configuring Programs for Windows XP](configuring-programs-for-windows-xp.md)\ How to target Windows XP with the MSVC build tools. -[C/C++ Building Reference](reference/c-cpp-building-reference.md)
+[C/C++ Building Reference](reference/c-cpp-building-reference.md)\ Provides links to reference articles about program building in C++, compiler and linker options, and various build tools. diff --git a/docs/build/prolog-and-epilog.md b/docs/build/prolog-and-epilog.md index c6300fb705..eb6f1ad972 100644 --- a/docs/build/prolog-and-epilog.md +++ b/docs/build/prolog-and-epilog.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: x64 prolog and epilog" title: "x64 prolog and epilog" ms.date: "12/17/2018" ms.assetid: 0453ed1a-3ff1-4bee-9cc2-d6d3d6384984 diff --git a/docs/build/reference/advanced-property-page.md b/docs/build/reference/advanced-property-page.md index ecc2c5d02c..f119173610 100644 --- a/docs/build/reference/advanced-property-page.md +++ b/docs/build/reference/advanced-property-page.md @@ -1,101 +1,137 @@ --- +description: "Use the Advanced property page in Visual Studio 2019 to set various properties for C++ projects." title: "Advanced Property Page (Project)" -ms.date: 08/10/2020 -f1_keywords: ["VC.Project.VCConfiguration.VCToolsVersion"] -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="<=vs-2017" +::: 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 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): -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. +- [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="vs-2019" +::: 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). + +### Enable MSVC Structured Output + +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 . - Causes the [`/clr`](clr-common-language-runtime-compilation.md) compiler option to be used. +### .NET Target Framework Version - To programmatically access this property, see . +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. -- **.NET Target Framework Version** +### .NET Target Framework - In managed projects, specifies the .NET framework version to target. +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). -- **Enable Managed Incremental Build** +This property specifies the .NET 5+ Target Framework Moniker this project targets, for example `net6.0-windows` or `net7.0-windows8.0`. - 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 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. + +### 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/ai-specify-metadata-directories.md b/docs/build/reference/ai-specify-metadata-directories.md index cfd734fc69..279ba49645 100644 --- a/docs/build/reference/ai-specify-metadata-directories.md +++ b/docs/build/reference/ai-specify-metadata-directories.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /AI (Specify Metadata Directories)" title: "/AI (Specify Metadata Directories)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCCLCompilerTool.AdditionalUsingDirectories", "VC.Project.VCNMakeTool.AssemblySearchPath", "/AI", "VC.Project.VCCLWCECompilerTool.AdditionalUsingDirectories"] diff --git a/docs/build/reference/align-section-alignment.md b/docs/build/reference/align-section-alignment.md index 313a6e506b..083eacba6b 100644 --- a/docs/build/reference/align-section-alignment.md +++ b/docs/build/reference/align-section-alignment.md @@ -1,29 +1,31 @@ --- -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 @@ -39,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/all.md b/docs/build/reference/all.md index 78e18bf3af..063b789b6e 100644 --- a/docs/build/reference/all.md +++ b/docs/build/reference/all.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /ALL" title: "/ALL" ms.date: "11/04/2016" f1_keywords: ["/all"] diff --git a/docs/build/reference/allowbind-prevent-dll-binding.md b/docs/build/reference/allowbind-prevent-dll-binding.md index a8fba7393b..583b85e26a 100644 --- a/docs/build/reference/allowbind-prevent-dll-binding.md +++ b/docs/build/reference/allowbind-prevent-dll-binding.md @@ -1,29 +1,32 @@ --- -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 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. Expand **Configuration Properties**, **Linker**, and select **Command Line**. +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 @@ -31,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 89a7efb68d..b7404db175 100644 --- a/docs/build/reference/allowbind.md +++ b/docs/build/reference/allowbind.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /ALLOWBIND" title: "/ALLOWBIND" ms.date: "11/04/2016" f1_keywords: ["/allowbind_bind"] @@ -10,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 519abac866..4d178ade64 100644 --- a/docs/build/reference/allowisolation-manifest-lookup.md +++ b/docs/build/reference/allowisolation-manifest-lookup.md @@ -1,31 +1,30 @@ --- -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 @@ -37,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 449b117191..579f9900b3 100644 --- a/docs/build/reference/allowisolation.md +++ b/docs/build/reference/allowisolation.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /ALLOWISOLATION" title: "/ALLOWISOLATION" ms.date: "11/04/2016" f1_keywords: ["/ALLOWISOLATION_EDITBIN"] @@ -12,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 9437373f46..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: 07/27/2020 -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) @@ -12,103 +11,232 @@ Enables code analysis and control options. ## Syntax -::: moniker range=">=vs-2017" - -> **`/analyze`**\ -> **`/analyze-`**\ -> **`/analyze:autolog`**\ -> **`/analyze:autolog-`**\ -> **`/analyze:autolog:ext`** *extension*\ -> **`/analyze:log`** *filename*\ -> **`/analyze:max_paths`** *number*\ +General analysis options: +> **`/analyze`**\[**`-`**]\ > **`/analyze:only`**\ -> **`/analyze:plugin`** *plugin-dll*\ > **`/analyze:quiet`**\ -> **`/analyze:ruleset`** *ruleset*\ -> **`/analyze:stacksize`** *number*\ +> **`/analyze:max_paths`** *`number`*\ +> **`/analyze:stacksize`** *`number`*\ > **`/analyze:WX-`** +Analysis plugin options: +> **`/analyze:plugin`** *`plugin_dll`* + +::: moniker range=">=msvc-160" + +External file analysis options: +> **`/analyze:external-`**\ +> **`/analyze:external:ruleset`** *`ruleset_files`* + ::: moniker-end -::: moniker range="vs-2015" -> **`/analyze`**\ -> **`/analyze-`**\ -> **`/analyze:autolog`**\ -> **`/analyze:autolog-`**\ -> **`/analyze:autolog:ext`** *extension*\ -> **`/analyze:log`** *filename*\ -> **`/analyze:max_paths`** *number*\ -> **`/analyze:only`**\ -> **`/analyze:plugin`** *plugin-dll*\ -> **`/analyze:quiet`**\ -> **`/analyze:stacksize`** *number*\ -> **`/analyze:WX-`** +Analysis log options: +> **`/analyze:autolog`**\[**`-`**]\ +> **`/analyze:autolog:ext`** *`extension`*\ +> **`/analyze:log`** *`log_path`* + +::: moniker range=">=msvc-160" + +Log file format options: +> **`/analyze:log:format:sarif`**\ +> **`/analyze:log:format:xml`** + +Log file content options: +> **`/analyze:sarif:analyzedfiles`**\[**`-`**]\ +> **`/analyze:sarif:configuration`**\[**`-`**]\ +> **`/analyze:log:compilerwarnings`**\ +> **`/analyze:log:includesuppressed`** + +::: moniker-end + +::: moniker range="msvc-150" + +Ruleset options: +> **`/analyze:ruleset`** *ruleset_file* ::: moniker-end -## Arguments +::: moniker range=">=msvc-160" + +Ruleset options: +> **`/analyze:projectdirectory`** *`project_directory`*\ +> **`/analyze:rulesetdirectory`** *`ruleset_directories`*\ +> **`/analyze:ruleset`** *`ruleset_files`* -**`/analyze`**\ -Turns on analysis in the default mode. Analysis output goes to the console or the Visual Studio **Output** window like other error messages. Use **`/analyze-`** to explicitly turn off analysis. +::: moniker-end -**`/analyze:autolog`**\ -Detailed analyzer results are written as XML to a file with the same base name as the source file and an extension of *`.pftlog`*. **`/analyze:autolog-`** disables this log file. +### Arguments -**`/analyze:autolog:ext`** *extension*\ -Detailed analyzer results are written as XML to a file with the same base name as the source file and an extension of *extension*. +#### General analysis options -**`/analyze:log`** *filename*\ -Detailed analyzer results are written as XML to the file that is specified by *filename*. +**`/analyze`**\[**`-`**]\ +Turns on code analysis. Use **`/analyze-`** to explicitly turn off analysis. **`/analyze-`** is the default behavior. -**`/analyze:max_paths`** *number*\ -The *number* parameter that is used with this option specifies the maximum number of code paths to be analyzed. If this parameter isn't specified, the number is 256 by default. Larger values cause more thorough checking, but the analysis might take longer. +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`**\ -Typically, the compiler generates code and does more syntax checking after it runs the analyzer. The **`/analyze:only`** option turns off this code generation pass. It makes analysis faster, but doesn't emit compiler errors and warnings that the code generation pass of the compiler might find. If the program isn't free of code-generation errors, analysis results might be unreliable. We recommend you use this option only if the code already passes code-generation syntax checking without errors. +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. + +**`/analyze:quiet`**\ +Turns off analysis output to the console or Visual Studio Output window. + +**`/analyze:max_paths`** *`number`*\ +The *`number`* parameter specifies the maximum number of code paths to analyze. Analysis defaults to 256 paths. Larger values cause more thorough checking, but the analysis might take longer. + +**`/analyze:stacksize`** *`number`*\ +The *`number`* parameter specifies the size in bytes of the stack frame that generates warning [C6262](../../code-quality/c6262.md). The default stack frame size is 16KB. + +**`/analyze:WX-`**\ +Tells the compiler not to treat code analysis warnings as errors even when the **`/WX`** option is used. For more information, see [`/WX` (Warning level)](compiler-option-warning-level.md). + +#### Analysis plugin options + +**`/analyze:plugin`** *`plugin_dll`*\ +Enables the specified code analysis plug-in DLL for code analysis. -**`/analyze:plugin`** *plugin-dll*\ -Enables the specified PREfast plugin as part of code analysis runs. +Space between **`/analyze:plugin`** and the *`plugin_dll`* file path is optional if the path doesn't require double-quotes (**`"`**). For example, you can write `/analyze:plugin EspxEngine.dll`. However, if the path is enclosed in double-quotes, you can't have a space between **`/analyze:plugin`** and the file path. Here's an example: `/analyze:plugin"c:\path\to\EspxEngine.dll"`. -::: moniker range="<=vs-2017" +The code analysis engine uses plug-ins to help find specific categories of defects. The code analysis engine comes with some built-in plug-ins that detect various defects. To use another plug-in with the code analysis engine, specify it by using the **`/analyze:plugin`** option. -LocalEspC.dll is the plugin that implements concurrency-related code analysis checks in the range of C261XX warnings. For example, [C26100](/cpp/code-quality/c26100), [C26101](/cpp/code-quality/c26101), ..., [C26167](/cpp/code-quality/c26167). +::: moniker range="<=msvc-150" -To run LocalEspC.dll, use this compiler option: **`/analyze:plugin LocalEspC.dll`** +The plug-in `LocalEspC.dll` implements concurrency-related analysis checks. These checks raise warnings in the C261XX range, such as [C26100](../../code-quality/c26100.md) through [C26167](../../code-quality/c26167.md). + +To load `LocalEspC.dll`, use compiler option `/analyze:plugin LocalEspC.dll`. ::: moniker-end -::: moniker range=">=vs-2019" -ConcurrencyCheck.dll implements concurrency-related code analysis checks in the range of C261XX warnings. For example, [C26100](/cpp/code-quality/c26100), [C26101](/cpp/code-quality/c26101), ..., [C26167](/cpp/code-quality/c26167). +::: moniker range=">=msvc-160" + +Some plug-ins, like `EspXEngine.dll`, which ships with Visual Studio, employ extensions that can do further analysis. Visual Studio includes these extensions for EspXEngine: `ConcurrencyCheck.dll`, `CppCoreCheck.dll`, `EnumIndex.dll`, `HResultCheck.dll`, and `VariantClear.dll`. They check for defects for concurrency issues, CppCoreGuidelines violations, inappropriate uses of `enum` values as indexes, `HRESULT` values, or `VARIANT` values, respectively. -To run ConcurrencyCheck.dll, first run this command from a developer command prompt: +When you build on the command line, you can use the `Esp.Extensions` environment variable to specify EspXEngine extensions. For example: ```cmd -set Esp.Extensions=ConcurrencyCheck.dll +set Esp.Extensions=ConcurrencyCheck.dll;CppCoreCheck.dll; ``` -Then use this compiler option: **`/analyze:plugin EspXEngine.dll`**. +Use a semicolon (**`;`**) to delimit the extensions, as shown in the example. A trailing semicolon isn't needed. You can use an absolute file path for an extension, or specify a relative path from the directory that contains `EspXEngine.dll`. -To run CppCoreCheck.dll, first run this command from a developer command prompt: +The `EspXEngine.dll` plug-in uses `ConcurrencyCheck.dll` to implement concurrency-related code analysis checks. These checks raise warnings in the C261XX range, such as [C26100](../../code-quality/c26100.md) through [C26167](../../code-quality/c26167.md). + +If you're building in a developer command prompt window, first set the `Esp.Extensions` environment variable to specify the `ConcurrencyCheck.dll` extension: ```cmd -set Esp.Extensions=CppCoreCheck.dll +set Esp.Extensions=ConcurrencyCheck.dll ``` -Then use this compiler option: **`/analyze:plugin EspXEngine.dll`**. +Then, use compiler option `/analyze:plugin EspXEngine.dll` to use the EspXEngine plug-in. ::: moniker-end -**`/analyze:quiet`**\ -Turns off analyzer output to the console or Visual Studio **Output** window. +::: moniker range=">=msvc-160" + +#### External file analysis options + +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: + +**`/analyze:external-`**\ +Skips analysis of external header files. By default, code analysis analyzes external header files just like other files. When the **`/analyze:external-`** option is set, code analysis skips any files specified as external, except templates from external files. Templates defined in external headers are treated as non-external by using the **`/external:templates-`** option. The **`/external:Wn`** option doesn't affect code analysis. For example, code analysis analyzes external files and reports defects even when `/external:W0` is specified. + +**`/analyze:external:ruleset`** *`ruleset_files`*\ +The *`ruleset_files`* parameter specifies one or more semicolon-delimited ruleset files to use for analysis of external files. For information on rulesets, refer to "Options for rulesets" section. + +There's an environment variable (`CAExcludePath`) that provides similar but simpler capability to skip analysis of files under the directories specified in the environment variable. If a directory is specified in both **`/external:*`** option and in the `CAExcludePath` environment variable, it's considered as excluded, and **`/analyze:external*`** options won't apply to that directory. + +::: moniker-end + +#### Analysis log options + +**`/analyze:autolog`**\[**`-`**]\ +This flag used to be required to enable creation of analysis log file for each of the source files being analyzed. Log files are now created by default, so this flag is mostly redundant. +When used, it changes the default log extension to *`*.pftlog`* instead of *`.xml`*. Use **`/analyze:autolog-`** to disable logging to files. + +**`/analyze:autolog:ext`** *`extension`*\ +Overrides the default extension of the analysis log files, and uses *`extension`* instead. If you use the *`.sarif`* extension, the log file uses the SARIF format instead of the default XML format. + +**`/analyze:log`** *`log_path`*\ +Specifies a log file path *`log_path`* instead of the automatically generated log file path. When the *`log_path`* path has a trailing backslash and refers to an existing directory, code analysis creates all log files in the specified directory. Otherwise, *`log_path`* specifies a file path. A file path instructs the compiler to combine logs for all analyzed source files into the specified log file. If the file path has a *`.sarif`* extension, the log file uses the SARIF format instead of the default XML format. You can override this behavior by using the **`/analyze:log:format:*`** option. + +::: moniker range=">=msvc-160" + +#### Log file format options + +Starting in Visual Studio 2019 version 16.9, you can specify different log format options for code analysis. + +**`/analyze:log:format:xml`**\ +Forces the use of XML log format irrelevant of the file extension used. + +**`/analyze:log:format:sarif`**\ +Forces the use of SARIF log format irrelevant of the file extension used. -::: moniker range=">=vs-2017" +#### Log file content options -**`/analyze:ruleset`** *file_path.ruleset*\ -Lets you specify which rule sets to analyze, including custom rule sets that you can create yourself. When this switch is set, the rules engine is more efficient, because it excludes non-members of the specified rule set before running. Otherwise, the engine checks all rules. +Starting in Visual Studio 2019 version 16.9, you can specify different log content options for code analysis. -The rulesets that ship with Visual Studio are found in *`%VSINSTALLDIR%\Team Tools\Static Analysis Tools\Rule Sets`*. +**`/analyze:sarif:analyzedfiles`**\[**`-`**]\ +Adds file artifacts entries to the SARIF log file for analyzed files that don't issue warnings. This option is disabled by default. Artifacts for the source file and for files that emitted results are always included. -The following sample custom rule set tells the rules engine to check for C6001 and C26494. You can place this file anywhere as long as it has a *`.ruleset`* extension and you provide the full path in the argument. +**`/analyze:sarif:configuration`**\[**`-`**]\ +Adds rule configuration entries to determine how the user overrode the default rule configuration (disabled by default). + +**`/analyze:log:compilerwarnings`**\ +Adds both any defects the analysis engine finds, and all compiler warnings, to the analysis log file. By default, compiler warnings aren't included in the analysis log file. For more information on compiler warnings during code analysis, see the **`/analyze:only`** option. + +**`/analyze:log:includesuppressed`**\ +Adds both suppressed warnings and unsuppressed warnings to the analysis log file. By default, suppressed warnings aren't included in the analysis log file. If ruleset files are specified for analysis, the warnings disabled by the ruleset files aren't included in the log even when **`/analyze:log:includesuppressed`** is specified. + +::: moniker-end + +::: moniker range=">=msvc-150" + +#### Ruleset options + +::: moniker-end + +::: moniker range=">=msvc-160" + +**`/analyze:projectdirectory`** *`project_directory`*\ +Specifies the current project directory. If the ruleset (or an item it includes) is a file name, the compiler first looks for the file under the specified *`project_directory`*. If not found, it next searches the *`ruleset_directories`* specified by **`/analyze:rulesetdirectory`**, if any. If the ruleset (or an item it includes) is a relative path, the compiler first looks for the file under the project directory. If the ruleset isn't found, then it looks in the current working directory. This option is available starting in Visual Studio 2019 version 16.9. + +**`/analyze:rulesetdirectory`** *`ruleset_directories`*\ +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; 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; 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 + +::: moniker range=">=msvc-150" + +The ruleset files that ship with Visual Studio are found in *`%VSINSTALLDIR%\Team Tools\Static Analysis Tools\Rule Sets`*. + +The following example custom ruleset tells the analysis engine to check for C6001 and C26494, and report them as warnings. + +::: moniker-end + +::: moniker range="msvc-150" + +You can place this file anywhere as long as you specify the full path in the argument. + +::: moniker-end + +::: moniker range=">=msvc-160" + +You can place this file anywhere as long as you specify the full path in the argument, or under the directories specified in the **`/analyze:projectdirectory`** or **`/analyze:rulesetdirectory`** options. + +::: moniker-end + +::: moniker range=">=msvc-150" ```xml @@ -120,17 +248,15 @@ The following sample custom rule set tells the rules engine to check for C6001 a ``` -::: moniker-end +By default, the file extension for ruleset files is *`*.ruleset`*. Visual Studio uses the default extension when browsing for ruleset files. However, you can use any extension. -**`/analyze:stacksize`** *number*\ -The *number* parameter that is used with this option specifies the size, in bytes, of the stack frame for which warning [C6262](/cpp/code-quality/c6262) is generated. The space before *number* is optional. If this parameter isn't specified, the stack frame size is 16KB by default. +For more information about rulesets, see [Use rule sets to specify the C++ rules to run](../../code-quality/using-rule-sets-to-specify-the-cpp-rules-to-run.md). -**`/analyze:WX-`**\ -Code analysis warnings aren't treated as errors when you compile by using **`/WX`**. For more information, see [`/WX` (Warning level)](compiler-option-warning-level.md). +::: moniker-end ## Remarks -For more information, see [Code analysis for C/C++ overview](/cpp/code-quality/code-analysis-for-c-cpp-overview) and [Code analysis for C/C++ warnings](/cpp/code-quality/code-analysis-for-c-cpp-warnings). +For more information, see [Code analysis for C/C++ overview](../../code-quality/code-analysis-for-c-cpp-overview.md) and [Code analysis for C/C++ warnings](../../code-quality/code-analysis-for-c-cpp-warnings.md). ### To set this compiler option in the Visual Studio development environment @@ -140,11 +266,31 @@ For more information, see [Code analysis for C/C++ overview](/cpp/code-quality/c 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 . ## 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/appcontainer-windows-store-app.md b/docs/build/reference/appcontainer-windows-store-app.md index 0b380d5bf6..4c0e6f856c 100644 --- a/docs/build/reference/appcontainer-windows-store-app.md +++ b/docs/build/reference/appcontainer-windows-store-app.md @@ -1,39 +1,32 @@ --- -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 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. Expand the **Configuration Properties** node. - -1. Expand the **Linker** node. - -1. Select the **Command Line** property page. +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 c2ba98365a..7cf45709d1 100644 --- a/docs/build/reference/appcontainer.md +++ b/docs/build/reference/appcontainer.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /APPCONTAINER" title: "/APPCONTAINER" ms.date: "11/04/2016" f1_keywords: ["/APPCONTAINER"] @@ -10,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 739cef8ee0..8d7ebd3293 100644 --- a/docs/build/reference/arch-arm.md +++ b/docs/build/reference/arch-arm.md @@ -1,39 +1,35 @@ --- +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). -1. Select the **C/C++** folder. - -1. Select the **Command Line** property page. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. 1. In the **Additional options** box, add `/arch:ARMv7VE` or `/arch:VFPv4`. @@ -43,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 8e0e1b7ee6..3c17866868 100644 --- a/docs/build/reference/arch-minimum-cpu-architecture.md +++ b/docs/build/reference/arch-minimum-cpu-architecture.md @@ -1,21 +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 d4c8aedd81..0bcf4ff202 100644 --- a/docs/build/reference/arch-x64.md +++ b/docs/build/reference/arch-x64.md @@ -1,58 +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. -- **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. +- **`SSE4.2`** uses the full set of SSE instructions for floating-point scalar, vector, and integer vector calculations. -- **AVX2** extends most integer operations to 256-bit vectors and enables use of Fused Multiply-Add (FMA) instructions. +- **`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-512** introduced another instruction encoding form that allows 512-bit vectors, plus certain other optional features. Instructions for additional operations were also added. +- **`AVX2`** extends most integer operations to 256-bit vectors and enables use of Fused Multiply-Add (FMA) instructions. -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. +- **`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. -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. +- **`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. -### To set the /arch:AVX, /arch:AVX2 or /arch:AVX512 compiler option in Visual Studio +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. -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). +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` compiler option in Visual Studio -1. Select the **Configuration Properties**, **C/C++** folder. +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 **Code Generation** property page. +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 @@ -60,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 bb27f7d588..cb71ce0716 100644 --- a/docs/build/reference/arch-x86.md +++ b/docs/build/reference/arch-x86.md @@ -1,63 +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 Intel Streaming SIMD Extensions 2. The default instruction set is SSE2 if no **`/arch`** option is specified. -**/arch:SSE2**
-Enables the use of SSE2 instructions. This is the default instruction on x86 platforms if no **/arch** option is specified. +**`/arch:AVX`**\ +Enables Intel Advanced Vector Extensions. -**/arch:AVX**
-Enables the use of Intel Advanced Vector Extensions instructions. +**`/arch:AVX2`**\ +Enables Intel Advanced Vector Extensions 2. -**/arch:AVX2**
-Enables the use of Intel Advanced Vector Extensions 2 instructions. +**`/arch:AVX512`**\ +Enables Intel Advanced Vector Extensions 512. -**/arch:AVX512**
-Enables the use of Intel Advanced Vector Extensions 512 instructions. +**`/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 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. +- **`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. -- **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, plus certain other optional features. Instructions for additional operations were also added. +- **`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. -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. +- **`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. -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. +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. -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: +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'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. @@ -71,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) { @@ -83,15 +88,13 @@ 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). -1. Select the **Configuration Properties**, **C/C++** folder. - -1. Select the **Code Generation** property page. +1. Select the **Configuration Properties** > **C/C++** > **Code Generation** property page. 1. Modify the **Enable Enhanced Instruction Set** property. @@ -101,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/archivemembers.md b/docs/build/reference/archivemembers.md index 0a42eb8025..e020461603 100644 --- a/docs/build/reference/archivemembers.md +++ b/docs/build/reference/archivemembers.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /ARCHIVEMEMBERS" title: "/ARCHIVEMEMBERS" ms.date: "11/04/2016" f1_keywords: ["/archivemembers"] 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 5f6580b1d5..fb77f5d492 100644 --- a/docs/build/reference/assemblydebug-add-debuggableattribute.md +++ b/docs/build/reference/assemblydebug-add-debuggableattribute.md @@ -1,63 +1,64 @@ --- +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 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 **Debug** property page. +1. Select the **Configuration Properties** > **Linker** > **Debug** property page. 1. Modify the **Debuggable Assembly** property. @@ -67,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 acbbfe9121..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,58 +1,59 @@ --- -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 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 **Command Line** property page. +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 @@ -60,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 3d496aa491..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,60 +1,59 @@ --- -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 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 **Input** property page. +1. Select the **Configuration Properties** > **Linker** > **Input** property page. 1. Modify the **Add Module to Assembly** property. @@ -64,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 2ee5ed8fa7..c21d423109 100644 --- a/docs/build/reference/assemblyresource-embed-a-managed-resource.md +++ b/docs/build/reference/assemblyresource-embed-a-managed-resource.md @@ -1,57 +1,58 @@ --- -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 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 **Input** property page. +1. Select the **Configuration Properties** > **Linker** > **Input** property page. 1. Modify the **Embed Managed Resource File** property. @@ -61,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-compiler-response-file.md b/docs/build/reference/at-specify-a-compiler-response-file.md index 1b71306de0..be0a32692e 100644 --- a/docs/build/reference/at-specify-a-compiler-response-file.md +++ b/docs/build/reference/at-specify-a-compiler-response-file.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: @ (Specify a Compiler Response File)" title: "@ (Specify a Compiler Response File)" ms.date: "11/04/2016" f1_keywords: ["@"] 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 776671086c..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,36 +1,37 @@ --- -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 1abbfb4fa5..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,25 +1,60 @@ --- -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 2160678e52..9595a434ff 100644 --- a/docs/build/reference/await-enable-coroutine-support.md +++ b/docs/build/reference/await-enable-coroutine-support.md @@ -1,31 +1,40 @@ --- +description: "Learn more about: /await (Enable coroutine support)" title: "/await (Enable coroutine support)" ms.date: "08/15/2017" 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 1. Open your project's **Property Pages** dialog box. -1. Under **Configuration Properties**, expand the **C/C++** folder and choose the **Command Line** property page. +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 1ab1c6c2d3..1728032bac 100644 --- a/docs/build/reference/base-base-address.md +++ b/docs/build/reference/base-base-address.md @@ -1,53 +1,51 @@ --- -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 @@ -56,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 ad9c0eade7..0000000000 --- a/docs/build/reference/batch-mode-rules.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -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/bigobj-increase-number-of-sections-in-dot-obj-file.md b/docs/build/reference/bigobj-increase-number-of-sections-in-dot-obj-file.md index bd38641892..50fd03c24d 100644 --- a/docs/build/reference/bigobj-increase-number-of-sections-in-dot-obj-file.md +++ b/docs/build/reference/bigobj-increase-number-of-sections-in-dot-obj-file.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /bigobj (Increase Number of Sections in .Obj file)" title: "/bigobj (Increase Number of Sections in .Obj file)" ms.date: "03/26/2019" f1_keywords: ["/bigobj"] diff --git a/docs/build/reference/bind.md b/docs/build/reference/bind.md index 94347bbc1f..d766c07cb5 100644 --- a/docs/build/reference/bind.md +++ b/docs/build/reference/bind.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /BIND" title: "/BIND" ms.date: "11/04/2016" f1_keywords: ["/bind"] diff --git a/docs/build/reference/binding-imports.md b/docs/build/reference/binding-imports.md deleted file mode 100644 index a4174bf720..0000000000 --- a/docs/build/reference/binding-imports.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: "Binding Imports" -ms.date: "11/04/2016" -helpviewer_keywords: ["/DELAY:NOBIND linker option", "DELAY:NOBIND linker option"] -ms.assetid: bb766038-deb1-41b1-bcbc-29a30e8c1e2a ---- -# Binding Imports - -The default linker behavior is to create a bindable import address table for the delay-loaded DLL. If the DLL is bound, the helper function will attempt to use the bound information instead of calling **GetProcAddress** on each of the referenced imports. If either the timestamp or the preferred address do not match those of the loaded DLL, the helper function will assume the bound import address table is out of date and will proceed as if it does not exist. - -If you never intend to bind the DLL's delay-loaded imports, specifying [/delay](delay-delay-load-import-settings.md):nobind on the linker's command line will prevent the bound import address table from being generated and consuming space in the image file. - -## See also - -[Linker Support for Delay-Loaded DLLs](linker-support-for-delay-loaded-dlls.md) diff --git a/docs/build/reference/bscmake-command-file-response-file.md b/docs/build/reference/bscmake-command-file-response-file.md index 20e1145aa9..ee25e12599 100644 --- a/docs/build/reference/bscmake-command-file-response-file.md +++ b/docs/build/reference/bscmake-command-file-response-file.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: BSCMAKE Command File (Response File)" title: "BSCMAKE Command File (Response File)" ms.date: "11/04/2016" helpviewer_keywords: ["BSCMAKE, response file", "BSCMAKE, command file", "response files, BSCMAKE", "command files, BSCMAKE", "response files", "command files"] diff --git a/docs/build/reference/bscmake-command-line.md b/docs/build/reference/bscmake-command-line.md index e41fcf62b9..24ebc146d5 100644 --- a/docs/build/reference/bscmake-command-line.md +++ b/docs/build/reference/bscmake-command-line.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: BSCMAKE Command Line" title: "BSCMAKE Command Line" ms.date: "11/04/2016" helpviewer_keywords: ["BSCMAKE, command line"] diff --git a/docs/build/reference/bscmake-exit-codes.md b/docs/build/reference/bscmake-exit-codes.md index d84294ea4d..6c42e84738 100644 --- a/docs/build/reference/bscmake-exit-codes.md +++ b/docs/build/reference/bscmake-exit-codes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: BSCMAKE Exit Codes" title: "BSCMAKE Exit Codes" ms.date: "11/04/2016" helpviewer_keywords: ["exit codes", "BSCMAKE, exit codes"] 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/bscmake-reference.md b/docs/build/reference/bscmake-reference.md index 057ad43868..8009cf7e85 100644 --- a/docs/build/reference/bscmake-reference.md +++ b/docs/build/reference/bscmake-reference.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: BSCMAKE Reference" title: "BSCMAKE Reference" ms.date: "05/06/2019" helpviewer_keywords: ["BSCMAKE, reference", "Microsoft Browse Information Maintenance Utility", "browse windows", "browse information files (.bsc), building", ".bsc files, building", "bsc files, building", "BSCMAKE"] diff --git a/docs/build/reference/building-a-dot-bsc-file.md b/docs/build/reference/building-a-dot-bsc-file.md index 9a8331db74..3f4860e08c 100644 --- a/docs/build/reference/building-a-dot-bsc-file.md +++ b/docs/build/reference/building-a-dot-bsc-file.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Building a .Bsc File" title: "Building a .Bsc File" ms.date: "11/04/2016" helpviewer_keywords: [".bsc files, building", "bsc files, building"] diff --git a/docs/build/reference/building-an-import-library-and-export-file.md b/docs/build/reference/building-an-import-library-and-export-file.md index 4566778998..b816aece36 100644 --- a/docs/build/reference/building-an-import-library-and-export-file.md +++ b/docs/build/reference/building-an-import-library-and-export-file.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Building an Import Library and Export File" title: "Building an Import Library and Export File" ms.date: "09/05/2018" f1_keywords: ["VC.Project.VCLibrarianTool.ModuleDefinitionFile", "VC.Project.VCLibrarianTool.ExportNamedFunctions", "VC.Project.VCLibrarianTool.GenerateDebug", "VC.Project.VCLibrarianTool.ForceSymbolReferences"] diff --git a/docs/build/reference/building-browse-information-files-overview.md b/docs/build/reference/building-browse-information-files-overview.md index 799b3eb2ff..c7217d48af 100644 --- a/docs/build/reference/building-browse-information-files-overview.md +++ b/docs/build/reference/building-browse-information-files-overview.md @@ -1,42 +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 4d0d582d6d..e1d0795232 100644 --- a/docs/build/reference/c-compile-without-linking.md +++ b/docs/build/reference/c-compile-without-linking.md @@ -1,9 +1,9 @@ --- title: "/c (Compile Without Linking)" -ms.date: "11/04/2016" +description: "Learn more about: /c (Compile Without Linking)" +ms.date: 11/04/2016 f1_keywords: ["/c"] helpviewer_keywords: ["suppress link", "cl.exe compiler, compiling without linking", "-c compiler option [C++]", "c compiler option [C++]", "/c compiler option [C++]"] -ms.assetid: 8017fc3d-e5dd-4668-a1f7-3120daa95d20 --- # /c (Compile Without Linking) @@ -33,14 +33,14 @@ Any internal project created in the development environment uses the **/c** opti The following command line creates the object files FIRST.obj and SECOND.obj. THIRD.obj is ignored. -``` +```cmd 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 +```cmd +LINK first.obj second.obj third.obj /OUT:filename.exe ``` ## See also diff --git a/docs/build/reference/c-cpp-build-tools.md b/docs/build/reference/c-cpp-build-tools.md index 8f8206e462..65f2e602a6 100644 --- a/docs/build/reference/c-cpp-build-tools.md +++ b/docs/build/reference/c-cpp-build-tools.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Additional MSVC Build Tools" title: "Additional MSVC Build Tools" ms.date: "08/28/2019" f1_keywords: ["c.build"] diff --git a/docs/build/reference/c-cpp-prop-page.md b/docs/build/reference/c-cpp-prop-page.md index 410bd24930..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: 07/08/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 @@ -72,7 +94,7 @@ Treats compiler warnings as errors. For a new project, it may be best to use [`/ ### Warning Version -Hide warnings introduced after a specific version of the compiler. Sets [`/Wv:xx`\[`.yy`\[`.zzzzz`\]\]](wx-treat-linker-warnings-as-errors.md). +Hide warnings introduced after a specific version of the compiler. Sets [`/Wv:xx[.yy[.zzzzz]]`](wx-treat-linker-warnings-as-errors.md). ### Diagnostics Format @@ -90,13 +112,17 @@ 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 ### Optimization -Select option for code optimization; choose Custom to use specific optimization options. Sets [/Od](od-disable-debug.md), [/O1, /O2](o-options-optimize-code.md). +Select option for code optimization; choose Custom to use specific optimization options. Sets [`/Od`](od-disable-debug.md), [`/O1`, `/O2`](o-options-optimize-code.md). #### Choices @@ -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 @@ -127,8 +153,8 @@ Whether to favor code size or code speed; 'Global Optimization' must be turned o #### Choices -- **Favor small code** - Favor Small Code. Minimizes the size of EXEs and DLLs by instructing the compiler to favor size over speed. -- **Favor fast code** - Favor Fast Code. Maximizes the speed of EXEs and DLLs by instructing the compiler to favor speed over size. (This value is the default.) +- **Favor small code** - Minimizes the size of EXEs and DLLs by instructing the compiler to favor size over speed. +- **Favor fast code** - Maximizes the speed of EXEs and DLLs by instructing the compiler to favor speed over size. (This value is the default.) - **Neither** - No size and speed optimization. ### Omit Frame Pointers @@ -141,7 +167,7 @@ Enables memory space optimization when using fibers and thread local storage acc ### Whole Program Optimization -Enables cross-module optimizations by delaying code generation to link time. Requires the linker option 'Link Time Code Generation'. Sets [`/GL`](gl-whole-program-optimization.md). +Enables cross-module optimizations by delaying code generation to link time. Requires the linker option **Link Time Code Generation**. Sets [`/GL`](gl-whole-program-optimization.md). ## C/C++ Preprocessor Properties @@ -171,7 +197,7 @@ Preprocess without #line directives. ### Keep Comments -Suppresses comment strip from source code; requires that one of the 'Preprocessing' options be set. Sets [`/C`](c-preserve-comments-during-preprocessing.md). +Suppresses comment strip from source code; requires setting at least one of the **Preprocessing** options. Sets [`/C`](c-preserve-comments-during-preprocessing.md). ## C/C++ Code Generation Properties @@ -206,7 +232,7 @@ Enable basic runtime error checks, incompatible with any optimization type other - **Stack Frames** - Enables stack frame run-time error checking. - **Uninitialized variables** - Reports when a variable is used without having been initialized. -- **Both (/RTC1, equiv. to /RTCsu)** - Equivalent of /RTCsu. +- **Both (/RTC1, equiv. to /RTCsu)** - Equivalent of **`/RTCsu`**. - **Default** - Default runtime checks. ### Runtime Library @@ -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 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** - 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. ### 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 @@ -253,7 +279,7 @@ Guard security check helps detect attempts to dispatch to illegal block of code. ### Enable Function-Level Linking -Allows the compiler to package individual functions in the form of packaged functions (COMDATs). Required for edit and continue to work. Sets [/Gy](gy-enable-function-level-linking.md). +Allows the compiler to package individual functions in the form of packaged functions (COMDATs). Required for edit and continue to work. Sets [`/Gy`](gy-enable-function-level-linking.md). ### Enable Parallel Code Generation @@ -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,15 +306,15 @@ 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 -Reliable floating-point exception model. Exceptions will be raised immediately after they're triggered. Sets [/fp:except](fp-specify-floating-point-behavior.md). +Reliable floating-point exception model. Exceptions will be raised immediately after they're triggered. Sets [`/fp:except`](fp-specify-floating-point-behavior.md). ### Create Hotpatchable Image -When hotpatching is on, the compiler ensures that first instruction of each function is two bytes, as required for hot patching. Sets [/hotpatch](hotpatch-create-hotpatchable-image.md). +When hotpatching is on, the compiler ensures that first instruction of each function is two bytes, as required for hot patching. Sets [`/hotpatch`](hotpatch-create-hotpatchable-image.md). ### Spectre Mitigation @@ -305,49 +331,64 @@ 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. ### Force Conformance in For Loop Scope -Used to implement standard C++ behavior for the for statement loops with Microsoft extensions. Sets [`/Za`, `/Ze` (Disable language extensions](za-ze-disable-language-extensions.md). [`/Zc:forScope`](zc-forscope-force-conformance-in-for-loop-scope.md) is on by default. +Implements standard C++ behavior for the `for` statement loops with Microsoft extensions. Sets [`/Za`, `/Ze` (Disable language extensions](za-ze-disable-language-extensions.md). [`/Zc:forScope`](zc-forscope-force-conformance-in-for-loop-scope.md) is on by default. ### Remove unreferenced code and data -When specified, compiler no longer generates symbol information for unreferenced code and data. +When specified, the compiler no longer generates symbol information for unreferenced code and data. ### Enforce type conversion rules -Used to identify an rvalue reference type as the result of a cast operation per the C++11 standard. +Used to identify an rvalue reference type as the result of a cast operation according to the C++11 standard. ### Enable Run-Time Type Information -Adds code for checking C++ object types at run time (runtime type information). Sets [`/GR`, `/GR-`](gr-enable-run-time-type-information.md). +Adds code for checking C++ object types at run time (*runtime type information*, or RTTI). Sets [`/GR`, `/GR-`](gr-enable-run-time-type-information.md). ### Open MP Support 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 @@ -356,8 +397,8 @@ Enables creation or use of a precompiled header during the build. Sets [`/Yc`](y #### Choices -- **Create** - Instructs the compiler to create a precompiled header (.pch) file that represents the state of compilation at a certain point. -- **Use** - Instructs the compiler to use an existing precompiled header (.pch) file in the current compilation. +- **Create** - Instructs the compiler to create a precompiled header (*`.pch`*) file that represents the state of compilation at a certain point. +- **Use** - Instructs the compiler to use an existing precompiled header (*`.pch`*) file in the current compilation. - **Not Using Precompiled Headers** - Not using precompiled headers. ### Precompiled Header File @@ -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-preserve-comments-during-preprocessing.md b/docs/build/reference/c-preserve-comments-during-preprocessing.md index 3ddc5debd6..242f1eabc6 100644 --- a/docs/build/reference/c-preserve-comments-during-preprocessing.md +++ b/docs/build/reference/c-preserve-comments-during-preprocessing.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /C (Preserve Comments During Preprocessing)" title: "/C (Preserve Comments During Preprocessing)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCCLCompilerTool.KeepComments", "VC.Project.VCCLWCECompilerTool.KeepComments"] @@ -38,9 +39,7 @@ int i; // a variable 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 **C/C++** folder. - -1. Click the **Preprocessor** property page. +1. Select the **Configuration Properties** > **C/C++** > **Preprocessor** property page. 1. Modify the **Keep Comments** property. diff --git a/docs/build/reference/c-visual-cpp.md b/docs/build/reference/c-visual-cpp.md index 4109e62179..ebfab859c0 100644 --- a/docs/build/reference/c-visual-cpp.md +++ b/docs/build/reference/c-visual-cpp.md @@ -1,28 +1,29 @@ --- -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 @@ -47,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/calculating-necessary-values.md b/docs/build/reference/calculating-necessary-values.md deleted file mode 100644 index 78a9b18999..0000000000 --- a/docs/build/reference/calculating-necessary-values.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: "Calculating Necessary Values" -ms.date: "11/04/2016" -helpviewer_keywords: ["helper functions, calculating necessary values"] -ms.assetid: 4f037d0f-881a-4a48-a9d2-9f8872dfccb7 ---- -# Calculating Necessary Values - -Two critical pieces of information need to be calculated by the delay helper routine. To that end, there are two inline functions in delayhlp.cpp for calculating this information. - -- The first calculates the index of the current import into the three different tables (import address table (IAT), bound import address table (BIAT), and unbound import address table (UIAT)). - -- The second counts the number of imports in a valid IAT. - -```cpp -// utility function for calculating the index of the current import -// for all the tables (INT, BIAT, UIAT, and IAT). -__inline unsigned -IndexFromPImgThunkData(PCImgThunkData pitdCur, PCImgThunkData pitdBase) { - return pitdCur - pitdBase; - } - -// utility function for calculating the count of imports given the base -// of the IAT. NB: this only works on a valid IAT! -__inline unsigned -CountOfImports(PCImgThunkData pitdBase) { - unsigned cRet = 0; - PCImgThunkData pitd = pitdBase; - while (pitd->u1.Function) { - pitd++; - cRet++; - } - return cRet; - } -``` - -## See also - -[Understanding the Helper Function](understanding-the-helper-function.md) diff --git a/docs/build/reference/calling-conventions-parameters-and-return-type.md b/docs/build/reference/calling-conventions-parameters-and-return-type.md deleted file mode 100644 index 1951bd62a6..0000000000 --- a/docs/build/reference/calling-conventions-parameters-and-return-type.md +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: "Calling Conventions, Parameters, and Return Type" -ms.date: "02/13/2019" -helpviewer_keywords: ["calling conventions, helper functions", "helper functions, calling conventions", "helper functions, return types"] -ms.assetid: 0ffa4558-6005-4803-be95-7a8ec8837660 ---- -# Calling Conventions, Parameters, and Return Type - -The helper routine's prototype is: - -``` -FARPROC WINAPI __delayLoadHelper2( - PCImgDelayDescr pidd, - FARPROC * ppfnIATEntry -); -``` - -### Parameters - -*pidd*
-A **`const`** pointer to a `ImgDelayDescr` that contains the offsets of various import-related data, a timestamp for binding information, and a set of attributes that provide further information about the descriptor content. Currently there's only one attribute, `dlattrRva`, which indicates that the addresses in the descriptor are relative virtual addresses. For more information, see the declarations in *delayimp.h*. - -For the definition of the `PCImgDelayDescr` structure, see [Structure and Constant Definitions](structure-and-constant-definitions.md). - -*ppfnIATEntry*
-A pointer to the slot in the delay load import address table (IAT) that's updated with the address of the imported function. The helper routine needs to store the same value that it returns into this location. - -## Expected Return Values - -If the function is successful, it returns the address of the imported function. - -If the function fails, it raises an exception and returns 0. Three types of exceptions can be raised: - -- Invalid parameter, which happens if the attributes in `pidd` aren't specified correctly. - -- `LoadLibrary` failed on the specified DLL. - -- Failure of `GetProcAddress`. - -It's your responsibility to handle these exceptions. - -## Remarks - -The calling convention for the helper function is **`__stdcall`**. The type of the return value isn't relevant, so FARPROC is used. This function has C linkage. - -The return value of the delay load helper needs to be stored in the passed-in function pointer location, unless you want your helper routine to be used as a notification hook. In that case, your code is responsible for finding the appropriate function pointer to return. The thunk code the linker generates then takes that return value as the real target of the import and jumps directly to it. - -## Sample - -The following code shows how to implement a simple hook function. - -```C -FARPROC WINAPI delayHook(unsigned dliNotify, PDelayLoadInfo pdli) -{ - switch (dliNotify) { - case dliStartProcessing : - - // If you want to return control to the helper, return 0. - // Otherwise, return a pointer to a FARPROC helper function - // that will be used instead, thereby bypassing the rest - // of the helper. - - break; - - case dliNotePreLoadLibrary : - - // If you want to return control to the helper, return 0. - // Otherwise, return your own HMODULE to be used by the - // helper instead of having it call LoadLibrary itself. - - break; - - case dliNotePreGetProcAddress : - - // If you want to return control to the helper, return 0. - // If you choose you may supply your own FARPROC function - // address and bypass the helper's call to GetProcAddress. - - break; - - case dliFailLoadLib : - - // LoadLibrary failed. - // If you don't want to handle this failure yourself, return 0. - // In this case the helper will raise an exception - // (ERROR_MOD_NOT_FOUND) and exit. - // If you want to handle the failure by loading an alternate - // DLL (for example), then return the HMODULE for - // the alternate DLL. The helper will continue execution with - // this alternate DLL and attempt to find the - // requested entrypoint via GetProcAddress. - - break; - - case dliFailGetProc : - - // GetProcAddress failed. - // If you don't want to handle this failure yourself, return 0. - // In this case the helper will raise an exception - // (ERROR_PROC_NOT_FOUND) and exit. - // If you choose you may handle the failure by returning - // an alternate FARPROC function address. - - break; - - case dliNoteEndProcessing : - - // This notification is called after all processing is done. - // There is no opportunity for modifying the helper's behavior - // at this point except by longjmp()/throw()/RaiseException. - // No return value is processed. - - break; - - default : - - return NULL; - } - - return NULL; -} - -/* -and then at global scope somewhere -const PfnDliHook __pfnDliNotifyHook2 = delayHook; -*/ -``` - -## See also - -[Understanding the Helper Function](understanding-the-helper-function.md) diff --git a/docs/build/reference/cetcompat.md b/docs/build/reference/cetcompat.md index 39b345f3ef..d5c8870b4c 100644 --- a/docs/build/reference/cetcompat.md +++ b/docs/build/reference/cetcompat.md @@ -1,12 +1,13 @@ --- +description: "Learn more about: /CETCOMPAT (CET Shadow Stack compatible)" title: "/CETCOMPAT (CET Shadow Stack compatible)" -ms.date: "06/30/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 @@ -20,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. @@ -30,21 +31,21 @@ 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 enable EH continuation metadata, or **`No (/CETCOMPAT:NO)`** to disable it. +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. -1. In the **Additional Options** edit control, add *`/CETCOMPAT`* to enable EH continuation metadata, or *`/CETCOMPAT:NO`* to explicitly disable it. +1. In the **Additional Options** edit control, add *`/CETCOMPAT`* to mark the binary as CET Shadow Stack compatible, or *`/CETCOMPAT:NO`* to explicitly mark it as non-compatible. ### To set this linker option programmatically diff --git a/docs/build/reference/cgthreads-code-generation-threads.md b/docs/build/reference/cgthreads-code-generation-threads.md index ec370c592b..d169b1d341 100644 --- a/docs/build/reference/cgthreads-code-generation-threads.md +++ b/docs/build/reference/cgthreads-code-generation-threads.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: `/cgthreads` (Code generation threads)" title: "/cgthreads (Code generation threads)" ms.date: 07/31/2020 f1_keywords: ["/cgthreads"] diff --git a/docs/build/reference/cgthreads-compiler-threads.md b/docs/build/reference/cgthreads-compiler-threads.md index a614214a6c..0dc7611402 100644 --- a/docs/build/reference/cgthreads-compiler-threads.md +++ b/docs/build/reference/cgthreads-compiler-threads.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /CGTHREADS (Compiler Threads)" title: "/CGTHREADS (Compiler Threads)" ms.date: "11/04/2016" helpviewer_keywords: ["/CGTHREADS linker option", "-CGTHREADS linker option", "CGTHREADS linker option"] @@ -29,9 +30,7 @@ Multiple levels of parallelism can be specified for a build. The msbuild.exe swi 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** folder. - -1. Select the **Command Line** property page. +1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. 1. Modify the **Additional Options** property to include **/CGTHREADS:**`number`, where `number` is a value from 1 to 8, and then choose **OK**. diff --git a/docs/build/reference/changes-in-the-dll-delayed-loading-helper-function-since-visual-cpp-6-0.md b/docs/build/reference/changes-in-the-dll-delayed-loading-helper-function-since-visual-cpp-6-0.md deleted file mode 100644 index 17bbbb2840..0000000000 --- a/docs/build/reference/changes-in-the-dll-delayed-loading-helper-function-since-visual-cpp-6-0.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: "Changes in the DLL Delayed Loading Helper Function Since Visual C++ 6.0" -ms.date: "11/04/2016" -helpviewer_keywords: ["delayed loading of DLLs, what's changed", "PFromRva method", "__delayLoadHelper2 function", "helper functions, what's changed"] -ms.assetid: 99f0be69-105d-49ba-8dd5-3be7939c0c72 ---- -# Changes in the DLL Delayed Loading Helper Function Since Visual C++ 6.0 - -If you have multiple versions of Visual C++ on your computer or if you defined your own helper function, you may be affected by changes made to the DLL delayed loading helper function. For example: - -- **__delayLoadHelper** is now **__delayLoadHelper2** - -- **__pfnDliNotifyHook** is now **__pfnDliNotifyHook2** - -- **__pfnDliFailureHook** is now **__pfnDliFailureHook2** - -- **__FUnloadDelayLoadedDLL** is now **__FUnloadDelayLoadedDLL2** - -> [!NOTE] -> If you are using the default helper function, these changes will not affect you. There are no changes regarding how you invoke the linker. - -## Multiple Versions of Visual C++ - -If you have multiple versions of Visual C++ on your computer, make sure the linker matches delayimp.lib. If there is a mismatch, you will get a linker error reporting either `___delayLoadHelper2@8` or `___delayLoadHelper@8` as an unresolved external symbol. The former implies a new linker with an old delayimp.lib, and the latter implies an old linker with a new delayimp.lib. - -If you get an unresolved linker error, run [dumpbin /linkermember](linkermember.md):1 on the delayimp.lib that you expect to contain the helper function to see which helper function is defined instead. The helper function could also be defined in an object file; run [dumpbin /symbols](symbols.md) and look for `delayLoadHelper(2)`. - -If you know you have the Visual C++ 6.0 linker, then: - -- Run dumpbin on the delay load helper's .lib or .obj file to determine whether it defines **__delayLoadHelper2**. If not, the link will fail. - -- Define **__delayLoadHelper** in the delay load helper's .lib or .obj file. - -## User-Defined Helper Function - -If you defined your own helper function and are using the current version of Visual C++, do the following: - -- Rename the helper function to **__delayLoadHelper2**. - -- Since the pointers in the delay descriptor (ImgDelayDescr in delayimp.h) have been changed from absolute addresses (VAs) to relative addresses (RVAs) to work as expected in both 32- and 64-bit programs, you need to convert these back to pointers. A new function has been introduced: PFromRva, found in delayhlp.cpp. You can use this function on each of the fields in the descriptor to convert them back to either 32- or 64-bit pointers. The default delay load helper function continues to be a good template to use as an example. - -## Load All Imports for a Delay-Loaded DLL - -The linker can load all imports from a DLL that you specified to be delay loaded. See [Loading All Imports for a Delay-Loaded DLL](loading-all-imports-for-a-delay-loaded-dll.md) for more information. - -## See also - -[Understanding the Helper Function](understanding-the-helper-function.md) diff --git a/docs/build/reference/choosing-the-format-of-netmodule-input-files.md b/docs/build/reference/choosing-the-format-of-netmodule-input-files.md index 96def7e10e..86c167a0fb 100644 --- a/docs/build/reference/choosing-the-format-of-netmodule-input-files.md +++ b/docs/build/reference/choosing-the-format-of-netmodule-input-files.md @@ -1,32 +1,32 @@ --- +description: "Learn more about: Choosing the Format of .netmodule Input Files" title: "Choosing the Format of .netmodule Input Files" ms.date: "11/04/2016" -ms.assetid: 4653d1bd-300f-4083-86f5-d1a06f44e61c --- -# Choosing the Format of .netmodule Input Files +# Choosing the format of .netmodule input files -An MSIL .obj file (compiled with [/clr](clr-common-language-runtime-compilation.md)) can also be used as a .netmodule file. .obj files contain metadata and native symbols. .netmodules only contain metadata. +You can use an MSIL `.obj` file (compiled with [`/clr`](clr-common-language-runtime-compilation.md)) as a `.netmodule` file. `.obj` files contain metadata and native symbols. `.netmodules` only contain metadata. -You can pass an MSIL .obj file to any other Visual Studio compiler via the /addmodule compiler option (but be aware that the .obj file becomes part of the resulting assembly and must be shipped with the assembly). For example, Visual C# and Visual Basic have the /addmodule compiler option. +Pass an MSIL `.obj` file to any other Visual Studio compiler with the `/addmodule` compiler option. The `.obj` file becomes part of the resulting assembly and must be shipped with the assembly. For example, Visual C# and Visual Basic have the `/addmodule` compiler option. > [!NOTE] -> In most cases, you will need to pass to the linker the .obj file from the compilation that created the .net module. Passing a .dll or .netmodule MSIL module file to the linker may result in LNK1107. +> In most cases, you need to pass to the linker the `.obj` file from the compilation that created the .net module. Passing a `.dll` or `.netmodule` MSIL module file to the linker might result in LNK1107. -.obj files, along with their associated .h files, which you reference via #include in source, allow C++ applications to consume the native types in the module, whereas in a .netmodule file, only the managed types can be consumed by a C++ application. If you attempt to pass a .obj file to #using, information about native types will not be available; #include the .obj file's .h file instead. +`.obj` files, along with their associated `.h` files, which you reference via #include in source, allow C++ applications to consume the native types in the module. In a `.netmodule` file, only the managed types can be consumed by a C++ application. If you attempt to pass a `.obj` file to #using, information about native types isn't available. Instead, #include the `.obj` file's `.h` file. Other Visual Studio compilers can only consume managed types from a module. -Use the following to determine whether you need to use a .netmodule or a .obj file as module input to the MSVC linker: +Use the following guidance to determine whether you need to use a `.netmodule` or a `.obj` file as module input to the MSVC linker: -- If you are building with a Visual Studio compiler other than Visual C++, produce a .netmodule and use the .netmodule as input to the linker. +- If you're building with a Visual Studio compiler other than Visual C++, produce a `.netmodule` and use the `.netmodule` as input to the linker. -- If you are using the MSVC compiler to produce modules and if the module(s) will be used to build something other than a library, use the .obj files produced by the compiler as module input to the linker; do not use the .netmodule file as input. +- If you're using the MSVC compiler to produce modules and if the modules are used to build something other than a library, use the `.obj` files produced by the compiler as module input to the linker. Don't use the `.netmodule` file as input. -- If your modules will be used to build a native (not a managed) library, use .obj files as module input to the linker and generate a .lib library file. +- If your modules are used to build a native (not a managed) library, use `.obj` files as module input to the linker and generate a `.lib` library file. -- If your modules will be used to build a managed library, and if all module input to the linker will be verifiable (produced with /clr:safe), use .obj files as module input to the linker and generate a .dll (assembly) or .netmodule (module) library file. +- If your modules are used to build a managed library, and if all module input to the linker is verifiable (produced with `/clr:safe`), use `.obj` files as module input to the linker and generate a `.dll` (assembly) or `.netmodule` (module) library file. -- If your modules will be used to build a managed library, and if one or more modules input to the linker will be produced with just /clr, use .obj files as module input to the linker and generate a .dll (assembly). If you want to expose managed types from the library and if you also want C++ applications to consume the native types in the library, your library will consist of the .obj files for the libraries component modules (you will also want to ship the .h files for each module, so they can be referenced with #include from source code). +- If your modules are used to build a managed library, and if one or more modules input to the linker are produced with just `/clr`, use `.obj` files as module input to the linker and generate a `.dll` (assembly). If you want to expose managed types from the library and if you also want C++ applications to consume the native types in the library, your library consists of the `.obj` files for the libraries component modules. You also want to ship the `.h` files for each module, so they can be referenced with #include from source code. ## See also diff --git a/docs/build/reference/cl-environment-variables.md b/docs/build/reference/cl-environment-variables.md index e100e3f3e4..4be22b5fbe 100644 --- a/docs/build/reference/cl-environment-variables.md +++ b/docs/build/reference/cl-environment-variables.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CL environment variables" title: "CL environment variables" ms.date: "06/06/2019" helpviewer_keywords: ["INCLUDE environment variable", "cl.exe compiler, environment variables", "LIBPATH environment variable", "environment variables, CL compiler"] @@ -25,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/cl-filename-syntax.md b/docs/build/reference/cl-filename-syntax.md index 88c46e90ec..7471fdc63e 100644 --- a/docs/build/reference/cl-filename-syntax.md +++ b/docs/build/reference/cl-filename-syntax.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: CL Filename Syntax" title: "CL Filename Syntax" ms.date: "11/04/2016" helpviewer_keywords: ["syntax, compiler filename", "paths, CL compiler filename syntax", "cl.exe compiler, filename syntax", "extensions, specifying to compiler", "file names [C++], CL compiler", "file names [C++]"] diff --git a/docs/build/reference/cl-invokes-the-linker.md b/docs/build/reference/cl-invokes-the-linker.md index 993f6baaab..df402a7015 100644 --- a/docs/build/reference/cl-invokes-the-linker.md +++ b/docs/build/reference/cl-invokes-the-linker.md @@ -1,8 +1,8 @@ --- title: "CL Invokes the Linker" -ms.date: "11/04/2016" +description: "Learn more about: CL Invokes the Linker" +ms.date: 11/04/2016 helpviewer_keywords: ["compiling source code [C++], without linking", "invoking linker from the compiler", "LINK tool [C++], invoking from CL compiler", "cl.exe compiler [C++], compiling without linking", "cl.exe compiler [C++], controlling linker"] -ms.assetid: eae47ef7-09eb-40c9-b318-7c714cd452fc --- # CL Invokes the Linker @@ -29,7 +29,7 @@ Assume that you are compiling three C source files: MAIN.c, MOD1.c, and MOD2.c. To build this program, compile with the following command line: -``` +```cmd CL MAIN.c MOD1.C MOD2.C MYGRAPH.lib ``` diff --git a/docs/build/reference/clr-common-language-runtime-compilation.md b/docs/build/reference/clr-common-language-runtime-compilation.md index 837f4aa177..d8189c75f6 100644 --- a/docs/build/reference/clr-common-language-runtime-compilation.md +++ b/docs/build/reference/clr-common-language-runtime-compilation.md @@ -1,84 +1,93 @@ --- -title: "/clr (Common Language Runtime Compilation)" -ms.date: "05/16/2019" +title: "/clr (Common Language Runtime compilation)" +description: "Use the Microsoft C++ compiler option /clr to compile C++/CLI and C++ code as managed code." +ms.date: 10/27/2020 f1_keywords: ["/CLR", "VC.Project.VCNMakeTool.CompileAsManaged", "VC.Project.VCCLCompilerTool.CompileAsManaged"] helpviewer_keywords: ["cl.exe compiler, common language runtime option", "-clr compiler option [C++]", "clr compiler option [C++]", "/clr compiler option [C++]", "Managed Extensions for C++, compiling", "common language runtime, /clr compiler option"] ms.assetid: fec5a8c0-40ec-484c-a213-8dec918c1d6c --- -# /clr (Common Language Runtime Compilation) +# `/clr` (Common Language Runtime Compilation) -Enables applications and components to use features from the common language runtime (CLR). +Enables applications and components to use features from the common language runtime (CLR) and enables C++/CLI compilation. ## Syntax -> **/clr**[**:**_options_] +> **`/clr`**\[**`:`**_options_] ## Arguments -*options*
-One or more of the following switches, comma-separated. +*options*\ +One or more of the following comma-separated arguments. - none - With no options, **/clr** creates metadata for the application. The metadata can be consumed by other CLR applications, and enables the application 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). + 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). -- **pure** +::: moniker range=">=msvc-160" - **/clr:pure is deprecated**. The option is removed in Visual Studio 2017 and later. We recommend that you port code that must be pure MSIL to C#. +- **`netcore`** -- **safe** + Available starting in Visual Studio 2019 version 16.4, **`/clr:netcore`** creates metadata and code for the component using the latest cross-platform .NET framework, also known as .NET Core. The metadata can be consumed by other .NET Core applications. And, the option enables the component to consume types and data in the metadata of other .NET Core components. - **/clr:safe is deprecated**. The option is removed in Visual Studio 2017 and later. We recommend that you port code that must be safe MSIL to C#. +::: moniker-end -- **noAssembly** +- **`nostdlib`** - **/clr:noAssembly is deprecated**. Use [/LN (Create MSIL Module)](ln-create-msil-module.md) instead. + Instructs the compiler to ignore the default *`\clr`* directory. The compiler produces errors if you include multiple versions of a DLL, such as System.dll. This option lets you specify the specific framework to use during compilation. - Specifies that an assembly manifest should not be inserted into the output file. By default, the **noAssembly** option is not in effect. +- **`pure`** - A managed program that does not have assembly metadata in the manifest is known as a *module*. The **noAssembly** option can be used only to produce a module. If you compile by using [/c](c-compile-without-linking.md) and **/clr:noAssembly**, then specify the [/NOASSEMBLY](noassembly-create-a-msil-module.md) option in the linker phase to create a module. + **`/clr:pure` is deprecated**. The option is removed in Visual Studio 2017 and later. We recommend that you port code that must be pure MSIL to C#. - Before Visual Studio 2005, **/clr:noAssembly** required **/LD**. **/LD** is now implied when you specify **/clr:noAssembly**. +- **`safe`** -- **initialAppDomain** + **`/clr:safe` is deprecated**. The option is removed in Visual Studio 2017 and later. We recommend that you port code that must be safe MSIL to C#. - Enables a Visual C++ application to run on version 1 of the CLR. An application that is compiled by using **initialAppDomain** should not be used by an application that uses ASP.NET because it is not supported in version 1 of the CLR. +- **`noAssembly`** -- **nostdlib** + **`/clr:noAssembly` is deprecated**. Use [`/LN` (Create MSIL Module)](ln-create-msil-module.md) instead. - Instructs the compiler to ignore the default \clr directory. The compiler produces errors if you are including multiple versions of a DLL such as System.dll. Using this option lets you specify the specific framework to use during compilation. + Tells the compiler not to insert an assembly manifest into the output file. By default, the **`noAssembly`** option isn't in effect. + + A managed program that doesn't have assembly metadata in the manifest is known as a *module*. The **`noAssembly`** option can be used only to produce a module. If you compile by using [`/c`](c-compile-without-linking.md) and **`/clr:noAssembly`**, then specify the [`/NOASSEMBLY`](noassembly-create-a-msil-module.md) option in the linker phase to create a module. + + Before Visual Studio 2005, **`/clr:noAssembly`** required **`/LD`**. **`/LD`** is now implied when you specify **`/clr:noAssembly`**. + +- **`initialAppDomain`** + + **`initialAppDomain` is obsolete**. Enables a C++/CLI application to run on version 1 of the CLR. An application that's compiled by using **`initialAppDomain`** shouldn't be used by an application that uses ASP.NET because it's not supported in version 1 of the CLR. ## Remarks -Managed code is code that can be inspected and managed by the CLR. Managed code can access managed objects. For more information, see [/clr Restrictions](clr-restrictions.md). +*Managed code* is code that can be inspected and managed by the CLR. Managed code can access managed objects. For more information, see [`/clr` Restrictions](clr-restrictions.md). -For information about how to develop applications that define and consume managed types, see [Component Extensions for Runtime Platforms](../../extensions/component-extensions-for-runtime-platforms.md). +For information about how to develop applications that define and consume managed types in C++, see [Component Extensions for Runtime Platforms](../../extensions/component-extensions-for-runtime-platforms.md). -An application compiled by using **/clr** may or may not contain managed data. +An application compiled by using **`/clr`** may or may not contain managed data. -To enable debugging on a managed application, see [/ASSEMBLYDEBUG (Add DebuggableAttribute)](assemblydebug-add-debuggableattribute.md). +To enable debugging on a managed application, see [`/ASSEMBLYDEBUG` (Add DebuggableAttribute)](assemblydebug-add-debuggableattribute.md). -Only CLR types will be instantiated on the garbage-collected heap. For more information, see [Classes and Structs](../../extensions/classes-and-structs-cpp-component-extensions.md). To compile a function to native code, use the `unmanaged` pragma. For more information, see [managed, unmanaged](../../preprocessor/managed-unmanaged.md). +Only CLR types are instantiated on the garbage-collected heap. For more information, see [Classes and Structs](../../extensions/classes-and-structs-cpp-component-extensions.md). To compile a function to native code, use the `unmanaged` pragma. For more information, see [`managed`, `unmanaged`](../../preprocessor/managed-unmanaged.md). -By default, **/clr** is not in effect. When **/clr** is in effect, **/MD** is also in effect. For more information, see [/MD, /MT, /LD (Use Run-Time Library)](md-mt-ld-use-run-time-library.md). **/MD** ensures that the dynamically linked, multithreaded versions of the runtime routines are selected from the standard header (.h) files. Multithreading is required for managed programming because the CLR garbage collector runs finalizers in an auxiliary thread. +By default, **`/clr`** isn't in effect. When **`/clr`** is in effect, **`/MD`** is also in effect. For more information, see [`/MD`, `/MT`, `/LD` (Use Run-Time Library)](md-mt-ld-use-run-time-library.md). **`/MD`** ensures that the dynamically linked, multithreaded versions of the runtime routines are selected from the standard header files. Multithreading is required for managed programming because the CLR garbage collector runs finalizers in an auxiliary thread. -If you compile by using **/c**, you can specify the CLR type of the resulting output file with [/CLRIMAGETYPE](clrimagetype-specify-type-of-clr-image.md). +If you compile by using **`/c`**, you can specify the CLR type of the resulting output file by using the [`/CLRIMAGETYPE`](clrimagetype-specify-type-of-clr-image.md) linker option. -**/clr** implies **/EHa**, and no other **/EH** options are supported for **/clr**. For more information, see [/EH (Exception Handling Model)](eh-exception-handling-model.md). +**`/clr`** implies **`/EHa`**, and no other **`/EH`** options are supported for **`/clr`**. For more information, see [`/EH` (Exception Handling Model)](eh-exception-handling-model.md). -For information about how to determine the CLR image type of a file, see [/CLRHEADER](clrheader.md). +For information about how to determine the CLR image type of a file, see [`/CLRHEADER`](clrheader.md). -All modules passed to a given invocation of the linker must be compiled by using the same run-time library compiler option (**/MD** or **/LD**). +All modules passed to a given invocation of the linker must be compiled by using the same run-time library compiler option (**`/MD`** or **`/LD`**). -Use the [/ASSEMBLYRESOURCE](assemblyresource-embed-a-managed-resource.md) linker option to embed a resource in an assembly. [/DELAYSIGN](delaysign-partially-sign-an-assembly.md), [/KEYCONTAINER](keycontainer-specify-a-key-container-to-sign-an-assembly.md), and [/KEYFILE](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md) linker options also let you customize how an assembly is created. +Use the [`/ASSEMBLYRESOURCE`](assemblyresource-embed-a-managed-resource.md) linker option to embed a resource in an assembly. [`/DELAYSIGN`](delaysign-partially-sign-an-assembly.md), [`/KEYCONTAINER`](keycontainer-specify-a-key-container-to-sign-an-assembly.md), and [`/KEYFILE`](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md) linker options also let you customize how an assembly is created. -When **/clr** is used, the `_MANAGED` symbol is defined to be 1. For more information, see [Predefined Macros](../../preprocessor/predefined-macros.md). +When **`/clr`** is used, the `_MANAGED` symbol is defined to be 1. For more information, see [Predefined macros](../../preprocessor/predefined-macros.md). -The global variables in a native object file are initialized first (during DllMain if the executable is a DLL), and then the global variables in the managed section are initialized (before any managed code is run). `#pragma` [init_seg](../../preprocessor/init-seg.md) only affects the order of initialization in the managed and unmanaged categories. +The global variables in a native object file are initialized first (during `DllMain` if the executable is a DLL), and then the global variables in the managed section are initialized (before any managed code is run). [`#pragma init_seg`](../../preprocessor/init-seg.md) only affects the order of initialization in the managed and unmanaged categories. -## Metadata and Unnamed Classes +### Metadata and Unnamed Classes -Unnamed classes will appear in metadata named as follows: `$UnnamedClass$`*crc-of-current-file-name*`$`*index*`$`, where *index* is a sequential count of the unnamed classes in the compilation. For example, the following code sample generates an unnamed class in metadata. +Unnamed classes appear in metadata under names such as `$UnnamedClass$$$`, where `` is a sequential count of the unnamed classes in the compilation. For example, the following code sample generates an unnamed class in metadata. ```cpp // clr_unnamed_class.cpp @@ -88,7 +97,24 @@ class {} x; Use ildasm.exe to view metadata. +### 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** dropdown to **All configurations**, and set the **Platform** dropdown to **All Platforms**. + +1. Select the **Configuration Properties** > **C/C++** > **General** page. + +1. Modify the **Common Language Runtime Support** property. Choose **OK** to save your changes. + +> [!NOTE] +> In the Visual Studio IDE, the **`/clr`** compiler option can be individually set on the **Configuration Properties** > **C/C++** > **General** page of the Property Pages dialog. However, we recommend you use a CLR template to create your project. It sets all of the properties required for successful creation of a CLR component. Another way to set these properties is to use the **Common Language Runtime Support** property on the **Configuration Properties** > **Advanced** page of the Property Pages dialog. This property sets all the other CLR-related tool options at once. + +### To set this compiler option programmatically + +- See . + ## 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/clr-restrictions.md b/docs/build/reference/clr-restrictions.md index a7ac282d92..7f929098e7 100644 --- a/docs/build/reference/clr-restrictions.md +++ b/docs/build/reference/clr-restrictions.md @@ -1,73 +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. @@ -75,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/clrheader.md b/docs/build/reference/clrheader.md index 6a724de539..a44f270ddf 100644 --- a/docs/build/reference/clrheader.md +++ b/docs/build/reference/clrheader.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /CLRHEADER" title: "/CLRHEADER" ms.date: "05/16/2019" f1_keywords: ["/CLRHEADER"] diff --git a/docs/build/reference/clrimagetype-specify-type-of-clr-image.md b/docs/build/reference/clrimagetype-specify-type-of-clr-image.md index 5dbbd26c01..cbaa592502 100644 --- a/docs/build/reference/clrimagetype-specify-type-of-clr-image.md +++ b/docs/build/reference/clrimagetype-specify-type-of-clr-image.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /CLRIMAGETYPE (Specify Type of CLR Image)" title: "/CLRIMAGETYPE (Specify Type of CLR Image)" ms.date: "05/16/2019" f1_keywords: ["/CLRIMAGETYPE", "VC.Project.VCLinkerTool.CLRImageType"] @@ -25,11 +26,7 @@ For information about how to determine the CLR image type of a file, see [/CLRHE 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. Expand the **Configuration Properties** node. - -1. Expand the **Linker** node. - -1. Select the **Advanced** property page. +1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. 1. Modify the **CLR Image Type** property. 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 2d5e734182..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,77 +1,45 @@ --- +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**. - -You can minimize the performance impact by linking with **/CLRSUPPORTLASTERROR:SYSTEMDLL**, which only preserves the last error code for functions in system DLLs. A system DLL is defined as one of the following: - -||||| -|-|-|-|-| -|ACLUI.DLL|ACTIVEDS.DLL|ADPTIF.DLL|ADVAPI32.DLL| -|ASYCFILT.DLL|AUTHZ.DLL|AVICAP32.DLL|AVIFIL32.DLL| -|CABINET.DLL|CLUSAPI.DLL|COMCTL32.DLL|COMDLG32.DLL| -|COMSVCS.DLL|CREDUI.DLL|CRYPT32.DLL|CRYPTNET.DLL| -|CRYPTUI.DLL|D3D8THK.DLL|DBGENG.DLL|DBGHELP.DLL| -|DCIMAN32.DLL|DNSAPI.DLL|DSPROP.DLL|DSUIEXT.DLL| -|GDI32.DLL|GLU32.DLL|HLINK.DLL|ICM32.DLL| -|IMAGEHLP.DLL|IMM32.DLL|IPHLPAPI.DLL|IPROP.DLL| -|KERNEL32.DLL|KSUSER.DLL|LOADPERF.DLL|LZ32.DLL| -|MAPI32.DLL|MGMTAPI.DLL|MOBSYNC.DLL|MPR.DLL| -|MPRAPI.DLL|MQRT.DLL|MSACM32.DLL|MSCMS.DLL| -|MSI.DLL|MSIMG32.DLL|MSRATING.DLL|MSTASK.DLL| -|MSVFW32.DLL|MSWSOCK.DLL|MTXEX.DLL|NDDEAPI.DLL| -|NETAPI32.DLL|NPPTOOLS.DLL|NTDSAPI.DLL|NTDSBCLI.DLL| -|NTMSAPI.DLL|ODBC32.DLL|ODBCBCP.DLL|OLE32.DLL| -|OLEACC.DLL|OLEAUT32.DLL|OLEDLG.DLL|OPENGL32.DLL| -|PDH.DLL|POWRPROF.DLL|QOSNAME.DLL|QUERY.DLL| -|RASAPI32.DLL|RASDLG.DLL|RASSAPI.DLL|RESUTILS.DLL| -|RICHED20.DLL|RPCNS4.DLL|RPCRT4.DLL|RTM.DLL| -|RTUTILS.DLL|SCARDDLG.DLL|SECUR32.DLL|SENSAPI.DLL| -|SETUPAPI.DLL|SFC.DLL|SHELL32.DLL|SHFOLDER.DLL| -|SHLWAPI.DLL|SISBKUP.DLL|SNMPAPI.DLL|SRCLIENT.DLL| -|STI.DLL|TAPI32.DLL|TRAFFIC.DLL|URL.DLL| -|URLMON.DLL|USER32.DLL|USERENV.DLL|USP10.DLL| -|UXTHEME.DLL|VDMDBG.DLL|VERSION.DLL|WINFAX.DLL| -|WINHTTP.DLL|WININET.DLL|WINMM.DLL|WINSCARD.DLL| -|WINTRUST.DLL|WLDAP32.DLL|WOW32.DLL|WS2_32.DLL| -|WSNMP32.DLL|WSOCK32.DLL|WTSAPI32.DLL|XOLEHLP.DLL| +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 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. Click the **Linker** folder. +1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. -1. Click the **Command Line** property page. - -1. Type 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 - See . -## Example +## Examples The following sample defines a native DLL with one exported function that modifies last error. @@ -88,9 +56,7 @@ __declspec(dllexport) double MySqrt(__int64 n) { } ``` -## Example - -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 @@ -143,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/clrthreadattribute-set-clr-thread-attribute.md b/docs/build/reference/clrthreadattribute-set-clr-thread-attribute.md index 1d7f7e9ffc..f7fbc0e382 100644 --- a/docs/build/reference/clrthreadattribute-set-clr-thread-attribute.md +++ b/docs/build/reference/clrthreadattribute-set-clr-thread-attribute.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /CLRTHREADATTRIBUTE (Set CLR Thread Attribute)" title: "/CLRTHREADATTRIBUTE (Set CLR Thread Attribute)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCLinkerTool.CLRThreadAttribute"] @@ -42,11 +43,7 @@ It will be necessary for you to use single-threading, for example, if your CLR p 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. Expand the **Configuration Properties** node. - -1. Expand the **Linker** node. - -1. Select the **Advanced** property page. +1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. 1. Modify the **CLR Thread Attribute** property. diff --git a/docs/build/reference/clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md b/docs/build/reference/clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md index 5fbea4e8d1..ffc60a41e9 100644 --- a/docs/build/reference/clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md +++ b/docs/build/reference/clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md @@ -1,42 +1,40 @@ --- +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. Expand the **Configuration Properties** node. - -1. Expand the **Linker** node. - -1. Select the **Advanced** property page. +1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. 1. Modify the **CLR Unmanaged Code Check** property. @@ -46,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 15591815cd..2ae857a3e2 100644 --- a/docs/build/reference/code-visual-cpp.md +++ b/docs/build/reference/code-visual-cpp.md @@ -1,35 +1,41 @@ --- -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 34896807da..3e5ab9a2c5 100644 --- a/docs/build/reference/command-line-property-pages.md +++ b/docs/build/reference/command-line-property-pages.md @@ -1,19 +1,33 @@ --- -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 fe439fac10..0000000000 --- a/docs/build/reference/command-modifiers.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -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 c41297f640..9929e2f05b 100644 --- a/docs/build/reference/commands-in-a-makefile.md +++ b/docs/build/reference/commands-in-a-makefile.md @@ -1,28 +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 260edea22f..0000000000 --- a/docs/build/reference/comments-in-a-makefile.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -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 4641af59f1..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,76 +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 bef1e1eb08..e34ddaab59 100644 --- a/docs/build/reference/compiler-command-line-syntax.md +++ b/docs/build/reference/compiler-command-line-syntax.md @@ -1,14 +1,14 @@ --- title: "MSVC Compiler Command-Line Syntax" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Command-Line Syntax" +ms.date: 11/04/2016 helpviewer_keywords: ["syntax, CL compiler command line", "cl.exe compiler, command-line syntax"] -ms.assetid: acba2c1c-0803-4a3a-af25-63e849b930a2 --- # Compiler Command-Line Syntax The CL command line uses the following syntax: -``` +```cmd CL [option...] file... [option | file]... [lib...] [@command-file] [/link link-opt...] ``` @@ -16,10 +16,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-controlled-link-options.md b/docs/build/reference/compiler-controlled-link-options.md index 3030069f73..28bcdbdcc5 100644 --- a/docs/build/reference/compiler-controlled-link-options.md +++ b/docs/build/reference/compiler-controlled-link-options.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Compiler-Controlled LINK Options" title: "Compiler-Controlled LINK Options" ms.date: "11/04/2016" helpviewer_keywords: ["LINK tool [C++], compiler-controlled options", "linker [C++], CL compiler control", "linking [C++], affected by CL features", "cl.exe compiler [C++], features that affect linking", "cl.exe compiler [C++], controlling linker"] 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 3d5adf2636..193a21544b 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: 07/29/2020 +ms.date: 2/5/2025 helpviewer_keywords: ["compiler options, C++"] --- # Compiler options listed alphabetically @@ -14,160 +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. | +| [`/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) | Enables experimental conforming preprocessor support. | +| [`/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. | -| [`/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). | +| [`/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. | +| [`/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. | -| [`/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. | +| [`/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. | +| [`/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 headers, modules, and other source 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`](sourcedependencies.md) | List all source-level dependencies. | +| [`/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++. | -| [`/U`](u-u-undefine-symbols.md) | Removes a predefined macro. | +| [`/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 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 faea07b379..5b2a78c030 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,48 +111,111 @@ 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/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. | +| [`/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`. | + ## Language | 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 by 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. | @@ -136,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*. | @@ -152,48 +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. | +| [`/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*. | | [`/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. | -| [`/sourceDependencies`](sourcedependencies.md) | List headers, modules, and other source dependencies. | +| [`/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 @@ -201,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) | Enables experimental conforming preprocessor support. | ## Deprecated and removed compiler options @@ -210,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) instead. | | [`/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. | @@ -225,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/compiler-options.md b/docs/build/reference/compiler-options.md index 7a0470dee0..3cd8681a83 100644 --- a/docs/build/reference/compiler-options.md +++ b/docs/build/reference/compiler-options.md @@ -1,8 +1,8 @@ --- +description: "Learn more about: Compiler Options" title: "MSVC Compiler Options" -ms.date: "05/06/2019" +ms.date: "12/14/2020" helpviewer_keywords: ["cl.exe compiler", "x86 MSVC compiler", "ARM MSVC compiler", "compiler options, C++", "x64 MSVC compiler"] -ms.assetid: ed3376c8-bef4-4c9a-80e9-3b5da232644c --- # Compiler Options @@ -13,7 +13,7 @@ cl.exe is a tool that controls the Microsoft C++ (MSVC) C and C++ compilers and The compilers produce Common Object File Format (COFF) object (.obj) files. The linker produces executable (.exe) files or dynamic-link libraries (DLLs). -Note that all compiler options are case sensitive. You may use either a forward slash (`/`) or a dash (`-`) to specify a compiler option. +All compiler options are case-sensitive. You may use either a forward slash (`/`) or a dash (`-`) to specify a compiler option. To compile without linking, use the [/c](c-compile-without-linking.md) option. 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 5cd071338e..9052345e64 100644 --- a/docs/build/reference/constexpr-control-constexpr-evaluation.md +++ b/docs/build/reference/constexpr-control-constexpr-evaluation.md @@ -1,44 +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. - -2. Under **Configuration Properties**, expand the **C/C++** folder and choose the **Command Line** property page. - -3. Enter any **/constexpr** compiler options in the **Additional Options** box. Choose **OK** or **Apply** to save your changes. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. +1. Enter **/constexpr** compiler options in the **Additional Options** box. Choose **OK** to save your changes. ### To set this compiler option programmatically @@ -46,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/constraints-of-delay-loading-dlls.md b/docs/build/reference/constraints-of-delay-loading-dlls.md deleted file mode 100644 index d47cbc48b6..0000000000 --- a/docs/build/reference/constraints-of-delay-loading-dlls.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: "Constraints of Delay Loading DLLs" -ms.date: "11/04/2016" -helpviewer_keywords: ["constraints [C++], delayed loading of DLLs", "delayed loading of DLLs, constraints", "DLLs [C++], constraints"] -ms.assetid: 0097ff65-550f-4a4e-8ac3-39bf6404f926 ---- -# Constraints of Delay Loading DLLs - -There are constraints regarding the delay loading of imports. - -- Imports of data cannot be supported. A workaround is to explicitly handle the data import yourself using `LoadLibrary` (or `GetModuleHandle` after you know the delay-load helper has loaded the DLL) and `GetProcAddress`. - -- Delay loading Kernel32.dll is not supported. This DLL is necessary for the delay-load helper routines to perform the delay loading. - -- [Binding](binding-imports.md) of entry points that are forwarded is not supported. - -- Delay loading of a DLL may not result in the same behavior of the process if there are per-process initializations that occur in the entry point of the delay-loaded DLL. Other cases include static TLS (thread local storage), declared using [__declspec(thread)](../../cpp/thread.md), which is not handled when the DLL is loaded via `LoadLibrary`. Dynamic TLS, using `TlsAlloc`, `TlsFree`, `TlsGetValue`, and `TlsSetValue`, is still available for use in either static or delay-loaded DLLs. - -- Static (global) function pointers should be reinitialized to imported functions after the first call to the function. This is because the first use of the function pointer will point to the thunk. - -- There is no way currently to delay the loading of only specific procedures from a DLL while using the normal import mechanism. - -- Custom calling conventions (such as using condition codes on x86 architectures) are not supported. Also, the floating-point registers are not saved on any platform. If your custom helper routine or hook routines use floating-point types, they need to completely save and restore the floating-point state on machines with register calling conventions with floating-point parameters. Be careful about delay loading the CRT DLL if you call CRT functions that take floating-point parameters on a numeric data processor (NDP) stack in the help function. - -## See also - -[Linker Support for Delay-Loaded DLLs](linker-support-for-delay-loaded-dlls.md)
-[LoadLibrary function](/windows/win32/api/libloaderapi/nf-libloaderapi-loadlibraryw)
-[GetModuleHandle function](/windows/win32/api/libloaderapi/nf-libloaderapi-getmodulehandlew)
-[GetProcAddress function](/windows/win32/api/libloaderapi/nf-libloaderapi-getprocaddress)
-[TlsAlloc function](/windows/win32/api/processthreadsapi/nf-processthreadsapi-tlsalloc)
-[TlsFree function](/windows/win32/api/processthreadsapi/nf-processthreadsapi-tlsfree)
-[TlsGetValue function](/windows/win32/api/processthreadsapi/nf-processthreadsapi-tlsgetvalue)
-[TlsSetValue function](/windows/win32/api/processthreadsapi/nf-processthreadsapi-tlssetvalue) diff --git a/docs/build/reference/contents-of-a-makefile.md b/docs/build/reference/contents-of-a-makefile.md index 884e11b04a..8883cd8cc7 100644 --- a/docs/build/reference/contents-of-a-makefile.md +++ b/docs/build/reference/contents-of-a-makefile.md @@ -1,10 +1,10 @@ --- -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: @@ -20,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 133adcbda0..1f88156dfd 100644 --- a/docs/build/reference/creating-a-makefile-project.md +++ b/docs/build/reference/creating-a-makefile-project.md @@ -1,22 +1,22 @@ --- 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. @@ -24,21 +24,21 @@ 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="vs-2019" +::: 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 -::: moniker range="<=vs-2017" +::: moniker range="<=msvc-150" ### To create a makefile project in Visual Studio 2015 or Visual Studio 2017 @@ -46,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 @@ -68,27 +68,27 @@ 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. Expand the **Configuration Properties** node. +1. Select the **Configuration Properties** > **NMake** property page. -1. Select the **NMake** property page, and then modify properties under **IntelliSense** as appropriate. +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. Click **OK** to close the property pages. +1. Choose **OK** to close the property pages. 1. Use the **Save All** command to save the modified project settings. @@ -96,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 ed40f7eb74..37096da3b1 100644 --- a/docs/build/reference/creating-an-dot-sbr-file.md +++ b/docs/build/reference/creating-an-dot-sbr-file.md @@ -1,8 +1,8 @@ --- 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 @@ -13,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 33bc7edcfb..0000000000 --- a/docs/build/reference/creating-inline-file-text.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -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/custom-build-step-property-page-general.md b/docs/build/reference/custom-build-step-property-page-general.md index 8b2e7b6b88..02b28be5a7 100644 --- a/docs/build/reference/custom-build-step-property-page-general.md +++ b/docs/build/reference/custom-build-step-property-page-general.md @@ -1,17 +1,18 @@ --- title: "Custom Build Step Property Page: General" -ms.date: "11/04/2016" +description: "This article describes the properties available on the Custom Build Step page in the Property Pages dialog." +ms.date: 10/27/2020 f1_keywords: ["VC.Project.VCCustomBuildStep.AdditionalInputs", "VC.Project.VCCustomBuildStep.CustomBuildAfterTargets", "VC.Project.VCCustomBuildStep.CustomBuildBeforeTargets", "VC.Project.VCCustomBuildStep.Outputs", "VC.Project.VCCustomBuildStep.Message", "VC.Project.VCCustomBuildStep.Command"] helpviewer_keywords: ["project properties, custom build step", "custom build step (general)"] ms.assetid: bd319741-0491-46c4-a428-7c61b4b46a02 --- # Custom Build Step Property Page: General -For each combination of project configuration and target platform in your project, you can specify a custom step to be performed when the project is built. +For each project configuration and target platform combination in your project, you can specify a custom step to execute when the project is built. For the Linux version of this page, see [Custom Build Step Properties (Linux C++)](../../linux/prop-pages/custom-build-step-linux.md). -## UIElement List +## General page - **Command Line** @@ -31,17 +32,17 @@ For the Linux version of this page, see [Custom Build Step Properties (Linux C++ - **Execute After and Execute Before** - These options define when the custom build step is run in the build process, relative to the listed targets. The most commonly listed targets are BuildGenerateSources, BuildCompile, and BuildLink, because they represent the major steps in the build process. Other often-listed targets are Midl, CLCompile, and Link. + These options define when the custom build step is run in the build process, relative to the listed targets. The most commonly listed targets are `BuildGenerateSources`, `BuildCompile`, and `BuildLink`, because they represent the major steps in the build process. Other often-listed targets are `Midl`, `CLCompile`, and `Link`. - **Treat Output As Content** - This option is only meaningful for Universal Windows Platform or Windows Phone apps, which include all content files in the .appx package. + This option is only meaningful for Universal Windows Platform or Windows Phone apps, which include all content files in the *`.appx`* package. ### To specify a custom build step -1. On the menu bar, choose **Project**, **Properties**. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. On the menu bar, choose **Project** > **Properties** to 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. In the **Property Pages** dialog box, navigate to the **Configuration Properties**, **Custom Build Step**, **General** page. +1. Select the **Configuration Properties** > **Custom Build Step** > **General** page. 1. Modify the settings. diff --git a/docs/build/reference/d-preprocessor-definitions.md b/docs/build/reference/d-preprocessor-definitions.md index fd999a97a5..4b23b2a738 100644 --- a/docs/build/reference/d-preprocessor-definitions.md +++ b/docs/build/reference/d-preprocessor-definitions.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /D (Preprocessor Definitions)" title: "/D (Preprocessor Definitions)" ms.date: "09/18/2019" f1_keywords: ["VC.Project.VCNMakeTool.PreprocessorDefinitions", "VC.Project.VCCLCompilerTool.PreprocessorDefinitions", "/d"] @@ -11,22 +12,22 @@ Defines a preprocessing symbol for a source file. ## Syntax -> **/D**\[ ]_name_[`=` | `#` [{ *string* | *number* }] ]\ -> **/D**\[ ]`"`_name_[`=` | `#` [{ *string* | *number* }] ]`"` +> **`/D`**\[ ]_name_\[`=` | `#` \[{ *string* | *number* }] ]\ +> **`/D`**\[ ]`"`_name_\[`=` | `#` \[{ *string* | *number* }] ]`"` ## Remarks You can use this symbol together with `#if` or `#ifdef` to compile source code conditionally. The symbol definition remains in effect until it's redefined in the code, or is undefined in the code by an `#undef` directive. -**/D** has the same effect as a `#define` directive at the beginning of a source code file. The difference is that **/D** strips quotation marks on the command line, and a `#define` directive keeps them. You can have whitespace between the **/D** and the symbol. There can't be whitespace between the symbol and the equals sign, or between the equals sign and any value assigned. +**`/D`** has the same effect as a `#define` directive at the beginning of a source code file. The difference is that **`/D`** strips quotation marks on the command line, and a `#define` directive keeps them. You can have whitespace between the **`/D`** and the symbol. There can't be whitespace between the symbol and the equals sign, or between the equals sign and any value assigned. By default, the value associated with a symbol is 1. For example, `/D name` is equivalent to `/D name=1`. In the example at the end of this article, the definition of `TEST` is shown to print `1`. Compiling by using `/D name=` causes the symbol *name* to have no associated value. Although the symbol can still be used to conditionally compile code, it otherwise evaluates to nothing. In the example, if you compile by using `/DTEST=`, an error occurs. This behavior resembles the use of `#define` with or without a value. -The **/D** option doesn't support function-like macro definitions. To insert definitions that can't be defined on the command line, consider the [/FI (Name forced include file)](fi-name-forced-include-file.md) compiler option. +The **`/D`** option doesn't support function-like macro definitions. To insert definitions that can't be defined on the command line, consider the [`/FI` (Name forced include file)](fi-name-forced-include-file.md) compiler option. -You can use **/D** multiple times on the command line to define additional symbols. If the same symbol is defined more than once, the last definition is used. +You can use **`/D`** multiple times on the command line to define more symbols. If the same symbol is defined more than once, the last definition is used. This command defines the symbol DEBUG in TEST.c: @@ -34,13 +35,13 @@ This command defines the symbol DEBUG in TEST.c: CL /DDEBUG TEST.C ``` -This command removes all occurrences of the keyword `__far` in TEST.c: +This command removes all occurrences of the keyword **`__far`** in TEST.c: ```cmd CL /D __far= TEST.C ``` -The **CL** environment variable can't be set to a string that contains the equal sign. To use **/D** together with the **CL** environment variable, you must specify the number sign (`#`) instead of the equal sign: +The **CL** environment variable can't be set to a string that contains the equal sign. To use **`/D`** together with the **`CL`** environment variable, you must specify the number sign (`#`) instead of the equal sign: ```cmd SET CL=/DTEST#0 @@ -56,11 +57,11 @@ CL /DTEST=%% TEST.C 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. In the left pane, select **Configuration Properties**, **C/C++**, **Preprocessor**. +1. Select the **Configuration Properties** > **C/C++** > **Preprocessor** property page. -1. In the right pane, in the right-hand column of the **Preprocessor Definitions** property, open the drop-down menu and choose **Edit**. +1. Open the drop-down menu of the **Preprocessor Definitions** property and choose **Edit**. -1. In the **Preprocessor Definitions** dialog box, add (one per line), modify, or delete one or more definitions. Choose **OK** to save your changes. +1. In the **Preprocessor Definitions** dialog box, add, modify, or delete one or more definitions, one per line. Choose **OK** to save your changes. You don't need to include the '/D' option prefix on the definitions you specify here. In the property page, definitions are separated by semicolons (`;`). @@ -91,9 +92,9 @@ TEST defined 1 ## See also -[MSVC Compiler Options](compiler-options.md)\ -[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md)\ -[/FI (Name forced include file)](fi-name-forced-include-file.md)\ -[/U, /u (Undefine Symbols)](u-u-undefine-symbols.md)\ -[#undef Directive (C/C++)](../../preprocessor/hash-undef-directive-c-cpp.md)\ -[#define Directive (C/C++)](../../preprocessor/hash-define-directive-c-cpp.md) +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md)\ +[`/FI` (Name forced include file)](fi-name-forced-include-file.md)\ +[`/U`, `/u` (Undefine Symbols)](u-u-undefine-symbols.md)\ +[`#undef` Directive (C/C++)](../../preprocessor/hash-undef-directive-c-cpp.md)\ +[`#define` Directive (C/C++)](../../preprocessor/hash-define-directive-c-cpp.md) diff --git a/docs/build/reference/dash-exports.md b/docs/build/reference/dash-exports.md index e1e186ca49..edc81ed026 100644 --- a/docs/build/reference/dash-exports.md +++ b/docs/build/reference/dash-exports.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /EXPORTS" title: "/EXPORTS" ms.date: "11/04/2016" f1_keywords: ["/exports"] 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 2a7497a353..85a515deba --- a/docs/build/reference/debug-generate-debug-info.md +++ b/docs/build/reference/debug-generate-debug-info.md @@ -1,51 +1,52 @@ --- +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 @@ -53,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/debugging-prop-pages.md b/docs/build/reference/debugging-prop-pages.md index bfc4bd3f41..c738655f99 100644 --- a/docs/build/reference/debugging-prop-pages.md +++ b/docs/build/reference/debugging-prop-pages.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: C++ Debugging Property Pages" title: "C++ Debugging Property Pages" ms.date: "07/24/2019" ms.topic: "article" diff --git a/docs/build/reference/debugtype-debug-info-options.md b/docs/build/reference/debugtype-debug-info-options.md index 55df480cf0..3805199d6b 100644 --- a/docs/build/reference/debugtype-debug-info-options.md +++ b/docs/build/reference/debugtype-debug-info-options.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /DEBUGTYPE (Debug Info Options)" title: "/DEBUGTYPE (Debug Info Options)" ms.date: "11/04/2016" f1_keywords: ["/debugtype"] diff --git a/docs/build/reference/decorated-names.md b/docs/build/reference/decorated-names.md index 3917011240..6370302c0d 100644 --- a/docs/build/reference/decorated-names.md +++ b/docs/build/reference/decorated-names.md @@ -1,21 +1,22 @@ --- -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. @@ -27,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. @@ -37,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 /symbols` `objfile` 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, after a pipe (|) character and 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. @@ -88,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/using-extern-to-specify-linkage.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 e70d685995..42e938c3ff 100644 --- a/docs/build/reference/def-specify-module-definition-file.md +++ b/docs/build/reference/def-specify-module-definition-file.md @@ -1,36 +1,34 @@ --- -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 @@ -38,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/defaultlib-specify-default-library.md b/docs/build/reference/defaultlib-specify-default-library.md index c5de59934a..6e860e72b2 100644 --- a/docs/build/reference/defaultlib-specify-default-library.md +++ b/docs/build/reference/defaultlib-specify-default-library.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /DEFAULTLIB (Specify Default Library)" title: "/DEFAULTLIB (Specify Default Library)" ms.date: "05/29/2018" f1_keywords: ["VC.Project.VCLinkerTool.DefaultLibraries", "/defaultlib"] diff --git a/docs/build/reference/defining-a-rule.md b/docs/build/reference/defining-a-rule.md deleted file mode 100644 index 7dbce885fe..0000000000 --- a/docs/build/reference/defining-a-rule.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -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 3d4f76383f..dd09538893 100644 --- a/docs/build/reference/defining-an-nmake-macro.md +++ b/docs/build/reference/defining-an-nmake-macro.md @@ -1,33 +1,63 @@ --- -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 +title: "Define an NMAKE Macro" +description: "Learn more about: Defining an NMAKE Macro" +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 bcf938b5c0..a1054d65b8 100644 --- a/docs/build/reference/delay-delay-load-import-settings.md +++ b/docs/build/reference/delay-delay-load-import-settings.md @@ -1,46 +1,48 @@ --- -title: "/DELAY (Delay Load Import Settings)" -ms.date: "11/04/2016" -f1_keywords: ["/delay", "VC.Project.VCLinkerTool.DelayNoBind", "VC.Project.VCLinkerTool.SupportUnloadOfDelayLoadedDLL", "VC.Project.VCLinkerTool.DelayUnload"] +description: "Learn more about: /DELAY (Delay load import settings)" +title: "/DELAY (Delay load import settings)" +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"] -ms.assetid: 9334b332-cc58-4dae-b10f-a4c75972d50c --- -# /DELAY (Delay Load Import Settings) +# `/DELAY` (Delay load import settings) -``` -/DELAY:UNLOAD -/DELAY:NOBIND -``` +Linker options to control delayed loading of DLLs at runtime. + +## Syntax + +> **`/DELAY:UNLOAD`**\ +> **`/DELAY:NOBIND`** ## Remarks -The /DELAY option controls [delayed loading](linker-support-for-delay-loaded-dlls.md) of DLLs: +The **`/DELAY`** option controls [delayed loading](linker-support-for-delay-loaded-dlls.md) of DLLs: -- The UNLOAD qualifier tells the delay-load helper function to support explicit unloading of the DLL. The Import Address Table (IAT) is reset to its original form, invalidating IAT pointers and causing them to be overwritten. +- The **`/DELAY:UNLOAD`** qualifier tells the delay-load helper function to support explicit unloading of the DLL. The Import Address Table (IAT) is reset to its original form, invalidating IAT pointers and causing them to be overwritten. - If you do not select UNLOAD, any call to [FUnloadDelayLoadedDLL](explicitly-unloading-a-delay-loaded-dll.md) will fail. + If you don't select **`/DELAY:UNLOAD`**, any call to [`__FUnloadDelayLoadedDLL`](linker-support-for-delay-loaded-dlls.md#explicitly-unload-a-delay-loaded-dll) will fail. -- 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. The resulting image cannot be statically bound. (Images with bindable IATs may be statically bound prior to execution.) See [/BIND](bind.md). +- The **`/DELAY: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. The resulting image can't be statically bound. (Images with bindable IATs may be statically bound before execution.) For more information, see [`/BIND`](bind.md). - If the DLL is bound, the helper function will attempt to use the bound information instead of calling [GetProcAddress](/windows/win32/api/libloaderapi/nf-libloaderapi-getprocaddress) on each of the referenced imports. If either the timestamp or the preferred address does not match those of the loaded DLL, the helper function will assume the bound IAT is out of date and will proceed as if the bound IAT does not exist. + If the DLL is bound, the helper function attempts to use the bound information instead of calling [`GetProcAddress`](/windows/win32/api/libloaderapi/nf-libloaderapi-getprocaddress) on each of the referenced imports. If either the timestamp or the preferred address doesn't match the ones in the loaded DLL, the helper function assumes the bound IAT is out of date. It continues as if the bound IAT doesn't exist. - NOBIND causes your program image to be larger but can speed load time of the DLL. If you never intend to bind the DLL, NOBIND will prevent the bound IAT from being generated. + **`/DELAY:NOBIND`** causes your program image to be larger, but can speed load time of the DLL. If you never intend to bind the DLL, **`/DELAY:NOBIND`** prevents the bound IAT from being generated. -To specify DLLs to delay load, use the [/DELAYLOAD](delayload-delay-load-import.md) option. +To specify DLLs to delay load, use the [`/DELAYLOAD`](delayload-delay-load-import.md) option. ### 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. Expand **Configuration Properties**, **Linker**, and then select **Advanced**. +1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. -1. Modify the **Delay Loaded DLL** property. +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 -[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/delayload-delay-load-import.md b/docs/build/reference/delayload-delay-load-import.md index 34f65c31e9..680051a455 100644 --- a/docs/build/reference/delayload-delay-load-import.md +++ b/docs/build/reference/delayload-delay-load-import.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /DELAYLOAD (Delay Load Import)" title: "/DELAYLOAD (Delay Load Import)" ms.date: "11/04/2016" f1_keywords: ["/delayload", "VC.Project.VCLinkerTool.DelayLoadDLLS"] diff --git a/docs/build/reference/delaysign-partially-sign-an-assembly.md b/docs/build/reference/delaysign-partially-sign-an-assembly.md index 6ef5a08f92..c4920ce4ea 100644 --- a/docs/build/reference/delaysign-partially-sign-an-assembly.md +++ b/docs/build/reference/delaysign-partially-sign-an-assembly.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /DELAYSIGN (Partially Sign an Assembly)" title: "/DELAYSIGN (Partially Sign an Assembly)" ms.date: "11/04/2016" f1_keywords: ["/delaysign", "VC.Project.VCLinkerTool.DelaySign"] 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 ec7b5e5d4f..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,29 +1,30 @@ --- -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: -| | | -|-|-| -| `///` | This is the form that is shown in documentation examples and used by the Visual Studio C++ project templates. | -| `/** */` | These are multiline delimiters. | +| Delimiter | Description | +|--|--| +| `///` | 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: @@ -42,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 /** @@ -50,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 /** @@ -63,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 c485c6c3e1..f44b4223a0 100644 --- a/docs/build/reference/dependentloadflag.md +++ b/docs/build/reference/dependentloadflag.md @@ -7,13 +7,13 @@ helpviewer_keywords: ["LINK tool [C++], dependent load flags", "-DEPENDENTLOADFL --- # /DEPENDENTLOADFLAG (Set default dependent load flags) -::: moniker range="vs-2015" +::: moniker range="msvc-140" The **/DEPENDENTLOADFLAG** option requires Visual Studio 2017 or later. ::: moniker-end -::: moniker range=">=vs-2017" +::: moniker range=">=msvc-150" Sets the default load flags used when the operating system resolves the statically linked imports of a module. @@ -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/dependents.md b/docs/build/reference/dependents.md index e56c0fae47..d0a66c44aa 100644 --- a/docs/build/reference/dependents.md +++ b/docs/build/reference/dependents.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /DEPENDENTS" title: "/DEPENDENTS" ms.date: "07/15/2019" f1_keywords: ["/dependents"] diff --git a/docs/build/reference/description-blocks.md b/docs/build/reference/description-blocks.md index 15c3684c8b..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 @@ -16,7 +15,7 @@ targets... : dependents... ## Dependency lines -A *dependency line* specifies one or more targets, and zero or more dependents. If a target doesn't exist, or has an earlier timestamp than a dependent, NMAKE executes the commands in the command block. NMAKE also executes the command block if the target is a [pseudotarget](pseudotargets.md). Here's an example dependency line: +A *dependency line* specifies one or more targets, and zero or more dependents. If a target doesn't exist, or has an earlier timestamp than a dependent, NMAKE executes the commands in the command block. NMAKE also executes the command block if the target is a [pseudotarget](#pseudotargets). Here's an example dependency line: ```makefile hi_bye.exe : hello.obj goodbye.obj helper.lib @@ -30,7 +29,7 @@ Before it executes command blocks, NMAKE scans all the dependencies and any appl ## Targets -The targets section of a dependency line specifies one or more targets. A target can be any valid filename, directory name, or [pseudotarget](pseudotargets.md). Separate multiple targets by using one or more spaces or tabs. Targets aren't case-sensitive. Paths are permitted with filenames. A target and its path can't exceed 256 characters. If the target preceding the colon is a single character, use a separating space. Otherwise, NMAKE interprets the letter-colon combination as a drive specifier. +The targets section of a dependency line specifies one or more targets. A target can be any valid filename, directory name, or [pseudotarget](#pseudotargets). Separate multiple targets by using one or more spaces or tabs. Targets aren't case-sensitive. Paths are permitted with filenames. A target and its path can't exceed 256 characters. If the target preceding the colon is a single character, use a separating space. Otherwise, NMAKE interprets the letter-colon combination as a drive specifier. ### Multiple targets @@ -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. @@ -179,7 +178,7 @@ setenv : ## Dependents -In a dependency line, specify zero or more dependents after the colon (`:`) or double colon (`::`), using any valid filename or [pseudotarget](pseudotargets.md). Separate multiple dependents by using one or more spaces or tabs. Dependents aren't case-sensitive. Paths are permitted with filenames. +In a dependency line, specify zero or more dependents after the colon (`:`) or double colon (`::`), using any valid filename or [pseudotarget](#pseudotargets). Separate multiple dependents by using one or more spaces or tabs. Dependents aren't case-sensitive. Paths are permitted with filenames. ### Inferred dependents diff --git a/docs/build/reference/developing-your-own-helper-function.md b/docs/build/reference/developing-your-own-helper-function.md deleted file mode 100644 index a8a1b97ee4..0000000000 --- a/docs/build/reference/developing-your-own-helper-function.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: "Developing Your Own Helper Function" -ms.date: "11/04/2016" -helpviewer_keywords: ["helper functions"] -ms.assetid: a845429d-68b1-4e14-aa88-f3f5343bd490 ---- -# Developing Your Own Helper Function - -You may want to provide your own version of the routine to do specific processing based on the names of the DLL or imports. There are two methods of doing this: coding your own, possibly based on the supplied code, or merely hooking the supplied version using the notification hooks detailed previously. - -## Code Your Own - -This is fairly simple since you can essentially use the supplied code as a guideline for the new one. Of course, it must adhere to the calling conventions and if it returns to the linker-generated thunks, it must return a proper function pointer. Once in your code, you can do pretty much whatever you want in order to satisfy the call or get out of the call. - -## Use the Start Processing Notification Hook - -It will probably be easiest to simply provide a new pointer to a user-supplied notification hook function that receives the same values as the default helper on the notification dliStartProcessing. At that point, the hook function can essentially become the new helper function, as a successful return to the default helper will bypass all further processing in the default helper. - -## See also - -[Linker Support for Delay-Loaded DLLs](linker-support-for-delay-loaded-dlls.md) diff --git a/docs/build/reference/diagnostics-compiler-diagnostic-options.md b/docs/build/reference/diagnostics-compiler-diagnostic-options.md index d6a8f55d5c..da294868c4 100644 --- a/docs/build/reference/diagnostics-compiler-diagnostic-options.md +++ b/docs/build/reference/diagnostics-compiler-diagnostic-options.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /diagnostics (Compiler diagnostic options)" title: "/diagnostics (Compiler diagnostic options)" ms.date: "11/11/2016" f1_keywords: ["/diagnostics", "VC.Project.VCCLCompilerTool.DiagnosticsFormat"] diff --git a/docs/build/reference/directives.md b/docs/build/reference/directives.md index a2a4d057c3..94c1814fb2 100644 --- a/docs/build/reference/directives.md +++ b/docs/build/reference/directives.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /DIRECTIVES" title: "/DIRECTIVES" ms.date: "11/04/2016" f1_keywords: ["/directives"] @@ -13,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/disasm.md b/docs/build/reference/disasm.md index caa4c31297..ab7366f884 100644 --- a/docs/build/reference/disasm.md +++ b/docs/build/reference/disasm.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /DISASM" title: "/DISASM" ms.date: "01/17/2018" f1_keywords: ["/disasm"] diff --git a/docs/build/reference/dll-build-a-dll.md b/docs/build/reference/dll-build-a-dll.md index bdfb9320b6..cc53dbe0f9 100644 --- a/docs/build/reference/dll-build-a-dll.md +++ b/docs/build/reference/dll-build-a-dll.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /DLL (Build a DLL)" title: "/DLL (Build a DLL)" ms.date: "11/04/2016" f1_keywords: ["/dll"] diff --git a/docs/build/reference/doc-process-documentation-comments-c-cpp.md b/docs/build/reference/doc-process-documentation-comments-c-cpp.md index 34bb86af24..2e29931fa9 100644 --- a/docs/build/reference/doc-process-documentation-comments-c-cpp.md +++ b/docs/build/reference/doc-process-documentation-comments-c-cpp.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /doc (Process Documentation Comments) (C/C++)" title: "/doc (Process Documentation Comments) (C/C++)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCCLCompilerTool.GenerateXMLDocumentationFiles", "/doc", "VC.Project.VCCLCompilerTool.XMLDocumentationFileName"] diff --git a/docs/build/reference/dot-def-files-as-linker-input.md b/docs/build/reference/dot-def-files-as-linker-input.md index e4b3510863..02845caca1 100644 --- a/docs/build/reference/dot-def-files-as-linker-input.md +++ b/docs/build/reference/dot-def-files-as-linker-input.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .Def Files as Linker Input" title: ".Def Files as Linker Input" ms.date: "11/04/2016" helpviewer_keywords: [".def files, as linker input", "def files, as linker input"] diff --git a/docs/build/reference/dot-directives.md b/docs/build/reference/dot-directives.md index 2fe7cf9306..951b71d2e0 100644 --- a/docs/build/reference/dot-directives.md +++ b/docs/build/reference/dot-directives.md @@ -1,33 +1,33 @@ --- -title: "Dot Directives" -ms.date: "11/04/2016" +description: "Learn more about: Dot Directives" +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-exe-files-as-linker-input.md b/docs/build/reference/dot-exe-files-as-linker-input.md index be29c2ea88..95de0a4e48 100644 --- a/docs/build/reference/dot-exe-files-as-linker-input.md +++ b/docs/build/reference/dot-exe-files-as-linker-input.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .Exe Files as Linker Input" title: ".Exe Files as Linker Input" ms.date: "11/04/2016" helpviewer_keywords: ["executable files, as linker output", ".exe files"] diff --git a/docs/build/reference/dot-exp-files-as-linker-input.md b/docs/build/reference/dot-exp-files-as-linker-input.md index 6cbcd344fd..08fd493bfd 100644 --- a/docs/build/reference/dot-exp-files-as-linker-input.md +++ b/docs/build/reference/dot-exp-files-as-linker-input.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .Exp Files as Linker Input" title: ".Exp Files as Linker Input" ms.date: "11/04/2016" helpviewer_keywords: ["exporting functions", "import libraries, linker files", "linking [C++], exports", "exporting functions, information about exported functions", "exporting data, export (.exp) files", "functions [C++], exporting", ".exp files [C++]", "EXP files"] 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 f17a974be7..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,14 +1,19 @@ --- -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 ea59fa533b..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,31 +1,36 @@ --- -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 @@ -35,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 @@ -53,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-obj-files-as-linker-input.md b/docs/build/reference/dot-obj-files-as-linker-input.md index 2434549c27..ece43bd251 100644 --- a/docs/build/reference/dot-obj-files-as-linker-input.md +++ b/docs/build/reference/dot-obj-files-as-linker-input.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .Obj Files as Linker Input" title: ".Obj Files as Linker Input" ms.date: "12/29/2017" helpviewer_keywords: ["linker [C++], OBJ files as input", "object files, linker output", "OMF object files", "LINK tool [C++], .obj files", "COFF files", "OBJ files as linker input", ".obj files as linker input"] diff --git a/docs/build/reference/dot-pdb-files-as-linker-input.md b/docs/build/reference/dot-pdb-files-as-linker-input.md index 64d0cd8ba3..4ca0b92504 100644 --- a/docs/build/reference/dot-pdb-files-as-linker-input.md +++ b/docs/build/reference/dot-pdb-files-as-linker-input.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .Pdb Files as Linker Input" title: ".Pdb Files as Linker Input" ms.date: "11/04/2016" helpviewer_keywords: [".pdb files, as linker input", "PDB files, as linker input"] diff --git a/docs/build/reference/dot-res-files-as-linker-input.md b/docs/build/reference/dot-res-files-as-linker-input.md index 1b7a572d4d..a1eed4f228 100644 --- a/docs/build/reference/dot-res-files-as-linker-input.md +++ b/docs/build/reference/dot-res-files-as-linker-input.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .Res Files as Linker Input" title: ".Res Files as Linker Input" ms.date: "11/04/2016" helpviewer_keywords: ["RES files as linker input", ".res files as linker input", "linking [C++], resource files", "resource files, linking"] diff --git a/docs/build/reference/dot-txt-files-as-linker-input.md b/docs/build/reference/dot-txt-files-as-linker-input.md index 4d8a56d453..19bf78f3fd 100644 --- a/docs/build/reference/dot-txt-files-as-linker-input.md +++ b/docs/build/reference/dot-txt-files-as-linker-input.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: .Txt Files as Linker Input" title: ".Txt Files as Linker Input" ms.date: "11/04/2016" helpviewer_keywords: [".txt files, linker input", "text files, linker input", "txt files, linker input"] diff --git a/docs/build/reference/dot-xml-file-processing.md b/docs/build/reference/dot-xml-file-processing.md index ae8af5c634..eb1f67631c 100644 --- a/docs/build/reference/dot-xml-file-processing.md +++ b/docs/build/reference/dot-xml-file-processing.md @@ -1,14 +1,15 @@ --- -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: @@ -18,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, @@ -69,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 @@ -173,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/driver-windows-nt-kernel-mode-driver.md b/docs/build/reference/driver-windows-nt-kernel-mode-driver.md index ffefb7195d..bf94b28702 100644 --- a/docs/build/reference/driver-windows-nt-kernel-mode-driver.md +++ b/docs/build/reference/driver-windows-nt-kernel-mode-driver.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /DRIVER (Windows NT Kernel Mode Driver)" title: "/DRIVER (Windows NT Kernel Mode Driver)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCLinkerTool.driver", "/driver"] @@ -37,7 +38,7 @@ If **/DRIVER** is specified: ### To set this linker option programmatically -- See [VCLinkerTool.driver Property](https://docs.microsoft.com/dotnet/api/microsoft.visualstudio.vcprojectengine.vclinkertool.driver?view=visualstudiosdk-2017#Microsoft_VisualStudio_VCProjectEngine_VCLinkerTool_driver). +- See [VCLinkerTool.driver Property](/dotnet/api/microsoft.visualstudio.vcprojectengine.vclinkertool.driver). ## See also diff --git a/docs/build/reference/dumpbin-command-line.md b/docs/build/reference/dumpbin-command-line.md index e56f410ee5..07068b6dda 100644 --- a/docs/build/reference/dumpbin-command-line.md +++ b/docs/build/reference/dumpbin-command-line.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: DUMPBIN Command Line" title: "DUMPBIN Command Line" ms.date: "11/04/2016" helpviewer_keywords: ["DUMPBIN program, command line"] 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 bbd9c055cd..fd5a44b32a 100644 --- a/docs/build/reference/dumpbin-reference.md +++ b/docs/build/reference/dumpbin-reference.md @@ -1,6 +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 @@ -10,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/dumping-delay-loaded-imports.md b/docs/build/reference/dumping-delay-loaded-imports.md deleted file mode 100644 index 7f662683f9..0000000000 --- a/docs/build/reference/dumping-delay-loaded-imports.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: "Dumping Delay-Loaded Imports" -ms.date: "11/04/2016" -helpviewer_keywords: ["delay-loaded imports, dumping", "imports (delay-loaded)", "delay-loaded imports"] -ms.assetid: f766acf4-9df8-4b85-8cf6-0be3ffc4c124 ---- -# Dumping Delay-Loaded Imports - -Delay-loaded imports can be dumped using [dumpbin /imports](imports-dumpbin.md) and show up with slightly different information than standard imports. They are segregated into their own section of the /imports dumping and are explicitly labeled as delay-loaded imports. If there is unload information present in the image, that is noted. If there is bind information present, the time/date stamp of the target DLL is noted along with the bound addresses of the imports. - -## See also - -[Linker Support for Delay-Loaded DLLs](linker-support-for-delay-loaded-dlls.md) 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 73e2919271..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,23 +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 @@ -34,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) -- [Windows ISV Software Security Defenses](https://docs.microsoft.com/previous-versions/bb430720(v=msdn.10)) +- [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 d171159d0b..9ccddd3219 100644 --- a/docs/build/reference/dynamicbase.md +++ b/docs/build/reference/dynamicbase.md @@ -1,25 +1,28 @@ --- +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 - [EDITBIN Options](editbin-options.md) -- [Windows ISV Software Security Defenses](https://docs.microsoft.com/previous-versions/bb430720(v=msdn.10)) +- [Windows ISV Software Security Defenses](/previous-versions/bb430720(v=msdn.10)) diff --git a/docs/build/reference/e-preprocess-to-stdout.md b/docs/build/reference/e-preprocess-to-stdout.md index 1fba3538c0..7426af0346 100644 --- a/docs/build/reference/e-preprocess-to-stdout.md +++ b/docs/build/reference/e-preprocess-to-stdout.md @@ -1,9 +1,9 @@ --- title: "/E (Preprocess to stdout)" -ms.date: "11/04/2016" +description: "Learn more about: /E (Preprocess to stdout)" +ms.date: 11/04/2016 f1_keywords: ["/e"] helpviewer_keywords: ["-E compiler option [C++]", "/E compiler option [C++]", "preprocessor output, copy to stdout", "preprocessor output"] -ms.assetid: ddbb1725-d950-4978-ab2f-30a5cd7b778c --- # /E (Preprocess to stdout) @@ -43,7 +43,7 @@ m(int)main( ) However, if you compile with: -``` +```cmd cl -E test.cpp > test2.cpp ``` @@ -53,11 +53,9 @@ cl -E test.cpp > test2.cpp 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 **C/C++** folder. - -1. Click the **Command Line** property page. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Type the compiler option in the **Additional Options**box. +1. Enter the compiler option in the **Additional Options** box. ### To set this compiler option programmatically @@ -67,7 +65,7 @@ cl -E test.cpp > test2.cpp The following command line preprocesses `ADD.C`, preserves comments, adds `#line` directives, and displays the result on the standard output device: -``` +```cmd CL /E /C ADD.C ``` diff --git a/docs/build/reference/editbin-command-line.md b/docs/build/reference/editbin-command-line.md index 099112ac07..8895da5e50 100644 --- a/docs/build/reference/editbin-command-line.md +++ b/docs/build/reference/editbin-command-line.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: EDITBIN Command Line" title: "EDITBIN Command Line" ms.date: "11/04/2016" helpviewer_keywords: ["EDITBIN program, command line"] diff --git a/docs/build/reference/editbin-reference.md b/docs/build/reference/editbin-reference.md index 0c557bf836..bd60d095e0 100644 --- a/docs/build/reference/editbin-reference.md +++ b/docs/build/reference/editbin-reference.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: EDITBIN Reference" title: "EDITBIN Reference" ms.date: "11/04/2016" f1_keywords: ["editbin"] diff --git a/docs/build/reference/eh-exception-handling-model.md b/docs/build/reference/eh-exception-handling-model.md index 4cc1b5619f..7262d762d7 100644 --- a/docs/build/reference/eh-exception-handling-model.md +++ b/docs/build/reference/eh-exception-handling-model.md @@ -1,13 +1,13 @@ --- title: "/EH (Exception handling model)" description: "Reference guide to the Microsoft C++ /EH (Exception handling model) compiler options in Visual Studio." -ms.date: "04/14/2020" +ms.date: 08/25/2020 f1_keywords: ["VC.Project.VCCLWCECompilerTool.ExceptionHandling", "/eh", "VC.Project.VCCLCompilerTool.ExceptionHandling"] helpviewer_keywords: ["exception handling, compiler model", "cl.exe compiler, exception handling", "EH compiler option [C++]", "-EH compiler option [C++]", "/EH compiler option [C++]"] no-loc: [SEH, try, catch, throw, extern, finally, noexcept] ms.assetid: 754b916f-d206-4472-b55a-b6f1b0f2cb4d --- -# /EH (Exception handling model) +# `/EH` (Exception handling model) Specifies the exception handling model support generated by the compiler. Arguments specify whether to apply `catch(...)` syntax to both structured and standard C++ exceptions, whether **extern "C"** code is assumed to throw exceptions, and whether to optimize away certain **`noexcept`** checks. @@ -41,7 +41,7 @@ Clears the previous option argument. For example, **`/EHsc-`** is interpreted as ### Default exception handling behavior -The compiler always generates code that supports asynchronous structured exception handling (SEH). By default (that is, if no **`/EHsc`**, **`/EHs`**, or **`/EHa`** option is specified), the compiler supports SEH handlers in the native C++ `catch(...)` clause. However, it also generates code that only partially supports C++ exceptions. The default exception unwinding code doesn't destroy automatic C++ objects outside of [try](../../cpp/try-throw-and-catch-statements-cpp.md) blocks that go out of scope because of an exception. Resource leaks and undefined behavior may result when a C++ exception is thrown. +The compiler always generates code that supports asynchronous structured exception handling (SEH). By default (that is, if no **`/EHsc`**, **`/EHs`**, or **`/EHa`** option is specified), the compiler supports SEH handlers in the native C++ `catch(...)` clause. However, it also generates code that only partially supports C++ exceptions. The default exception unwinding code doesn't destroy automatic C++ objects outside of [`try`](../../cpp/try-throw-and-catch-statements-cpp.md) blocks that go out of scope because of an exception. Resource leaks and undefined behavior may result when a C++ exception is thrown. ### Standard C++ exception handling @@ -53,12 +53,12 @@ When you use **`/EHs`** or **`/EHsc`**, the compiler assumes that exceptions can ### Structured and standard C++ exception handling -The **`/EHa`** compiler option enables safe stack unwinding for both asynchronous exceptions and C++ exceptions. It supports handling of both standard C++ and structured exceptions by using the native C++ `catch(...)` clause. To implement SEH without specifying **`/EHa`**, you may use the **__try**, **`__except`**, and **`__finally`** syntax. For more information, see [Structured exception handling](../../cpp/structured-exception-handling-c-cpp.md). +The **`/EHa`** compiler option enables safe stack unwinding for both asynchronous exceptions and C++ exceptions. It supports handling of both standard C++ and structured exceptions by using the native C++ `catch(...)` clause. To implement SEH without specifying **`/EHa`**, you may use the **`__try`**, **`__except`**, and **`__finally`** syntax. For more information, see [Structured exception handling](../../cpp/structured-exception-handling-c-cpp.md). > [!IMPORTANT] > Specifying **`/EHa`** and trying to handle all exceptions by using `catch(...)` can be dangerous. In most cases, asynchronous exceptions are unrecoverable and should be considered fatal. Catching them and proceeding can cause process corruption and lead to bugs that are hard to find and fix. > -> Even though Windows and Visual C++ support SEH, we strongly recommend that you use ISO-standard C++ exception handling (**`/EHsc`** or **`/EHs`**). It makes your code more portable and flexible. There may still be times you have to use SEH in legacy code or for particular kinds of programs. It's required in code compiled to support the common language runtime ([/clr](clr-common-language-runtime-compilation.md)), for example. For more information, see [Structured exception handling](../../cpp/structured-exception-handling-c-cpp.md). +> Even though Windows and Visual C++ support SEH, we strongly recommend that you use ISO-standard C++ exception handling (**`/EHsc`** or **`/EHs`**). It makes your code more portable and flexible. There may still be times you have to use SEH in legacy code or for particular kinds of programs. It's required in code compiled to support the common language runtime ([`/clr`](clr-common-language-runtime-compilation.md)), for example. For more information, see [Structured exception handling](../../cpp/structured-exception-handling-c-cpp.md). > > We recommend that you never link object files compiled using **`/EHa`** to ones compiled using **`/EHs`** or **`/EHsc`** in the same executable module. If you have to handle an asynchronous exception by using **`/EHa`** anywhere in your module, use **`/EHa`** to compile all the code in the module. You can use structured exception handling syntax in the same module as code that's compiled by using **`/EHs`**. However, you can't mix the SEH syntax with C++ **`try`**, **`throw`**, and **`catch`** in the same function. @@ -111,9 +111,9 @@ For information about exception handling restrictions under **`/clr`**, see [_se ### Runtime exception checks -The **`/EHr`** option forces runtime termination checks in all functions that have a **`noexcept`** attribute. By default, runtime checks may be optimized away if the compiler back-end determines that a function only calls *non-throwing* functions. Non-throwing functions are any functions that have an attribute that specifies no exceptions may be thrown. They include functions marked **`noexcept`**, `throw()`, `__declspec(nothrow)`, and, when **`/EHc`** is specified, **extern "C"** functions. Non-throwing functions also include any that the compiler has determined are non-throwing by inspection. You can explicitly set the default behavior by using **`/EHr-`**. +The **`/EHr`** option forces runtime termination checks in all functions that have a **`noexcept`** attribute. By default, runtime checks may be optimized away if the compiler back-end determines that a function only calls *non-throwing* functions. Non-throwing functions are any functions that have an attribute that specifies no exceptions may be thrown. They include functions marked **`noexcept`**, `throw()`, `__declspec(nothrow)`, and, when **`/EHc`** is specified, **`extern "C"`** functions. Non-throwing functions also include any that the compiler has determined are non-throwing by inspection. You can explicitly set the default behavior by using **`/EHr-`**. -A non-throwing attribute isn't a guarantee that exceptions can't be thrown by a function. Unlike the behavior of a **`noexcept`** function, the MSVC compiler considers an exception thrown by a function declared using `throw()`, `__declspec(nothrow)`, or **extern "C"** as undefined behavior. Functions that use these three declaration attributes don't enforce runtime termination checks for exceptions. You can use the **`/EHr`** option to help you identify this undefined behavior, by forcing the compiler to generate runtime checks for unhandled exceptions that escape a **`noexcept`** function. +A non-throwing attribute isn't a guarantee that exceptions can't be thrown by a function. Unlike the behavior of a **`noexcept`** function, the MSVC compiler considers an exception thrown by a function declared using `throw()`, `__declspec(nothrow)`, or **`extern "C"`** as undefined behavior. Functions that use these three declaration attributes don't enforce runtime termination checks for exceptions. You can use the **`/EHr`** option to help you identify this undefined behavior, by forcing the compiler to generate runtime checks for unhandled exceptions that escape a **`noexcept`** function. ## Set the option in Visual Studio or programmatically @@ -133,8 +133,8 @@ A non-throwing attribute isn't a guarantee that exceptions can't be thrown by a ## See also -[MSVC Compiler Options](compiler-options.md)\ -[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md)\ -[Errors and Exception Handling](../../cpp/errors-and-exception-handling-modern-cpp.md)\ -[Exception Specifications (throw)](../../cpp/exception-specifications-throw-cpp.md)\ +[MSVC Compiler options](compiler-options.md)\ +[MSVC Compiler command-line syntax](compiler-command-line-syntax.md)\ +[Errors and exception handling](../../cpp/errors-and-exception-handling-modern-cpp.md)\ +[Exception specifications (throw)](../../cpp/exception-specifications-throw-cpp.md)\ [Structured Exception Handling (C/C++)](../../cpp/structured-exception-handling-c-cpp.md) diff --git a/docs/build/reference/entry-entry-point-symbol.md b/docs/build/reference/entry-entry-point-symbol.md index 60e6067ad9..25d9dbdf63 100644 --- a/docs/build/reference/entry-entry-point-symbol.md +++ b/docs/build/reference/entry-entry-point-symbol.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /ENTRY (Entry-Point Symbol)" title: "/ENTRY (Entry-Point Symbol)" ms.date: "11/04/2016" f1_keywords: ["/entry", "VC.Project.VCLinkerTool.EntryPointSymbol"] @@ -42,9 +43,7 @@ For information on how to define your own `DllMain` entry point, see [DLLs and V 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 **Advanced** property page. +1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. 1. Modify the **Entry Point** property. diff --git a/docs/build/reference/environment-variable-macros.md b/docs/build/reference/environment-variable-macros.md deleted file mode 100644 index 810f1fa08a..0000000000 --- a/docs/build/reference/environment-variable-macros.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -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/ep-preprocess-to-stdout-without-hash-line-directives.md b/docs/build/reference/ep-preprocess-to-stdout-without-hash-line-directives.md index 1e6c5ced7d..61d030c081 100644 --- a/docs/build/reference/ep-preprocess-to-stdout-without-hash-line-directives.md +++ b/docs/build/reference/ep-preprocess-to-stdout-without-hash-line-directives.md @@ -1,9 +1,9 @@ --- title: "/EP (Preprocess to stdout Without #line Directives)" -ms.date: "11/04/2016" +description: "Learn more about: /EP (Preprocess to stdout Without #line Directives)" +ms.date: 11/04/2016 f1_keywords: ["/ep", "VC.Project.VCCLCompilerTool.GeneratePreprocessedFileNoLines"] helpviewer_keywords: ["copy preprocessor output to stdout", "preprocessor output, copy to stdout", "-EP compiler option [C++]", "EP compiler option [C++]", "/EP compiler option [C++]"] -ms.assetid: 6ec411ae-e33d-4ef5-956e-0054635eabea --- # /EP (Preprocess to stdout Without #line Directives) @@ -33,9 +33,7 @@ You cannot use precompiled headers with the **/EP** option. 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 **C/C++** folder. - -1. Click the **Preprocessor** property page. +1. Select the **Configuration Properties** > **C/C++** > **Preprocessor** property page. 1. Modify the **Generate Preprocessed File** property. @@ -47,7 +45,7 @@ You cannot use precompiled headers with the **/EP** option. The following command line preprocesses file `ADD.C`, preserves comments, and displays the result on the standard output device: -``` +```cmd CL /EP /C ADD.C ``` diff --git a/docs/build/reference/errlook-reference.md b/docs/build/reference/errlook-reference.md index 2aac37f3b9..47ed1c2c9d 100644 --- a/docs/build/reference/errlook-reference.md +++ b/docs/build/reference/errlook-reference.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: ERRLOOK Reference" title: "ERRLOOK Reference" ms.date: "11/04/2016" helpviewer_keywords: ["ErrLook tool", "Error lookup tool"] diff --git a/docs/build/reference/error-handling-and-notification.md b/docs/build/reference/error-handling-and-notification.md index 4eead222c7..f56b2d4f4d 100644 --- a/docs/build/reference/error-handling-and-notification.md +++ b/docs/build/reference/error-handling-and-notification.md @@ -1,31 +1,137 @@ --- -title: "Error Handling and Notification" -ms.date: "11/04/2016" +title: "Error handling and notification" +description: "Learn more about: DLL delay load error handling and notification" +ms.date: "01/19/2021" helpviewer_keywords: ["error handling, and notification"] -ms.assetid: b621cf60-d869-451a-b05e-dc86d78addaa --- -# Error Handling and Notification +# Error handling and notification -For more information on error handling and notification, see [Understanding the Helper Function](understanding-the-helper-function.md). +If your program uses delay-loaded DLLs, it must handle errors robustly, since failures that occur while the program is running will result in unhandled exceptions. Failure handling is composed of two portions: Recovery through a hook, and reporting via an exception. -For more information on hook functions, see [Structure and Constant Definitions](structure-and-constant-definitions.md). +For more information on DLL delay load error handling and notification, see [Understand the helper function](understanding-the-helper-function.md). -If your program uses delay-loaded DLLs, it must handle errors robustly since failures that occur while the program is running will result in unhandled exceptions. Failure handling is comprised of two portions: +For more information on hook functions, see [Structure and constant definitions](understanding-the-helper-function.md#structure-and-constant-definitions). -Recovery through a hook. -If your code needs to recover or provide an alternate library and/or routine on failure, a hook can be provided to the helper function that can supply or remedy the situation. The hook routine needs to return a suitable value, so that processing can continue (an HINSTANCE or FARPROC) or 0 to indicate that an exception should be thrown. It could also throw its own exception or **longjmp** out of the hook. There are notification hooks and failure hooks. +## Recovery through a hook -Reporting via an exception. -If all that is necessary for handling the error is to abort the procedure, no hook is necessary as long as the user code can handle the exception. +Your code may need to recover on a failure, or to provide an alternate library or routine. You can provide a hook to the helper function that can supply the alternative code, or remedy the situation. The hook routine needs to return a suitable value, so that processing can continue (an `HINSTANCE` or `FARPROC`). Or, it can return 0 to indicate that an exception should be thrown. It could also throw its own exception or `longjmp` out of the hook. There are notification hooks and failure hooks. The same routine may be used for both. -The following topics discuss error handling and notification: +## Notification hooks -- [Notification Hooks](notification-hooks.md) +The delay load notification hooks are called just before the following actions are taken in the helper routine: -- [Failure Hooks](failure-hooks.md) +- The stored handle to the library is checked to see if it has already been loaded. -- [Exceptions](exceptions-c-cpp.md) +- `LoadLibrary` is called to attempt the load of the DLL. + +- `GetProcAddress` is called to attempt to get the address of the procedure. + +- Return to the delay import load thunk. + +The notification hook is enabled: + +- By supplying a new definition of the pointer `__pfnDliNotifyHook2` that's initialized to point to your own function that receives the notifications. + + \-or- + +- By setting the pointer `__pfnDliNotifyHook2` to your hook function before any calls to the DLL that the program is delay loading. + +If the notification is `dliStartProcessing`, the hook function can return: + +- `NULL` + + The default helper handles the loading of the DLL. It's useful to call just for informational purposes. + +- a function pointer + + Bypass the default delay-load handling. It lets you supply your own load handler. + +If the notification is `dliNotePreLoadLibrary`, the hook function can return: + +- 0, if it just wants informational notifications. + +- The `HMODULE` for the loaded DLL, if it loaded the DLL itself. + +If the notification is `dliNotePreGetProcAddress`, the hook function can return: + +- 0, if it just wants informational notifications. + +- The imported function's address, if the hook function gets the address itself. + +If the notification is `dliNoteEndProcessing`, the hook function's return value is ignored. + +If this pointer is initialized (nonzero), the delay load helper invokes the function at certain notification points throughout its execution. The function pointer has the following definition: + +```C +// The "notify hook" gets called for every call to the +// delay load helper. This allows a user to hook every call and +// skip the delay load helper entirely. +// +// dliNotify == { +// dliStartProcessing | +// dliNotePreLoadLibrary | +// dliNotePreGetProc | +// dliNoteEndProcessing} +// on this call. +// +ExternC +PfnDliHook __pfnDliNotifyHook2; + +// This is the failure hook, dliNotify = {dliFailLoadLib|dliFailGetProc} +ExternC +PfnDliHook __pfnDliFailureHook2; +``` + +The notifications pass in a `DelayLoadInfo` structure to the hook function along with the notification value. This data is identical to the data used by the delay load helper routine. The notification value will be one of the values defined in [Structure and constant definitions](understanding-the-helper-function.md#structure-and-constant-definitions). + +## Failure hooks + +The failure hook is enabled in the same manner as the [notification hook](#notification-hooks). The hook routine needs to return a suitable value so that processing can continue (an `HINSTANCE` or `FARPROC`), or 0 to indicate that an exception should be thrown. + +The pointer variable that refers to the user-defined function is: + +```C +// This is the failure hook, dliNotify = {dliFailLoadLib|dliFailGetProc} +ExternC +PfnDliHook __pfnDliFailureHook2; +``` + +The **`DelayLoadInfo`** structure contains all the pertinent data necessary for detailed reporting of the error, including the value from `GetLastError`. + +If the notification is **`dliFailLoadLib`**, the hook function can return: + +- 0, if it can't handle the failure. + +- An `HMODULE`, if the failure hook fixed the problem and loaded the library itself. + +If the notification is **`dliFailGetProc`**, the hook function can return: + +- 0, if it can't handle the failure. + +- A valid proc address (import function address), if the failure hook succeeded in getting the address itself. + +## Report by using an exception + +If all that's required to handle the error is to abort the procedure, no hook is necessary, as long as the user code can handle the exception. + +## Delay load exception codes + +Structured exception codes can be raised when failures occur during a delayed load. The exception values are specified by using a `VcppException` macro: + +```C +// +// Exception information +// +#define FACILITY_VISUALCPP ((LONG)0x6d) +#define VcppException(sev,err) ((sev) | (FACILITY_VISUALCPP<<16) | err) +``` + +For a `LoadLibrary` failure, the standard `VcppException(ERROR_SEVERITY_ERROR, ERROR_MOD_NOT_FOUND)` is thrown. For a `GetProcAddress` failure, the error thrown is `VcppException(ERROR_SEVERITY_ERROR, ERROR_PROC_NOT_FOUND)`. The exception passes a pointer to a `DelayLoadInfo` structure. It's in the `LPDWORD` value retrieved by `GetExceptionInformation` from the [`EXCEPTION_RECORD`](/windows/win32/api/winnt/ns-winnt-exception_record) structure, in the `ExceptionInformation[0]` field. + +If the incorrect bits are set in the `grAttrs` field, the exception `ERROR_INVALID_PARAMETER` is thrown. This exception is, for all intents and purposes, fatal. + +For more information, see [Structure and constant definitions](understanding-the-helper-function.md#structure-and-constant-definitions). ## See also -[Linker Support for Delay-Loaded DLLs](linker-support-for-delay-loaded-dlls.md) +[Linker support for delay-loaded DLLs](linker-support-for-delay-loaded-dlls.md) diff --git a/docs/build/reference/error-message-edit-control.md b/docs/build/reference/error-message-edit-control.md index 40312e369b..98098486e4 100644 --- a/docs/build/reference/error-message-edit-control.md +++ b/docs/build/reference/error-message-edit-control.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Error Message Edit Control" title: "Error Message Edit Control" ms.date: "11/04/2016" helpviewer_keywords: ["Error Message edit control"] diff --git a/docs/build/reference/errorreport-report-internal-compiler-errors.md b/docs/build/reference/errorreport-report-internal-compiler-errors.md index e50ae09abd..95625bc2bc 100644 --- a/docs/build/reference/errorreport-report-internal-compiler-errors.md +++ b/docs/build/reference/errorreport-report-internal-compiler-errors.md @@ -25,7 +25,7 @@ The **/errorReport** arguments are overridden by the Windows Error Reporting ser 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 **Configuration Properties** > **C/C++** > **Advanced** property page. +1. Select the **Configuration Properties** > **C/C++** > **Advanced** property page. 1. Modify the **Error Reporting** property. diff --git a/docs/build/reference/errorreport-report-internal-linker-errors.md b/docs/build/reference/errorreport-report-internal-linker-errors.md index e6343fb35a..47d1eb0661 100644 --- a/docs/build/reference/errorreport-report-internal-linker-errors.md +++ b/docs/build/reference/errorreport-report-internal-linker-errors.md @@ -1,6 +1,6 @@ --- title: "/ERRORREPORT (Report internal linker errors)" -description: "Reference guide to the Microsoft NMAKE command-line options." +description: "Learn how to use /ERRORREPORT." ms.date: "02/09/2020" f1_keywords: ["/ERRORREPORT", "VC.Project.VCLinkerTool.ErrorReporting"] helpviewer_keywords: ["/ERRORREPORT linker option", "ERRORREPORT linker option", "-ERRORREPORT linker option"] @@ -22,7 +22,7 @@ The **/ERRORREPORT** arguments are overridden by the Windows Error Reporting ser 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 **Configuration Properties** > **Linker** > **Advanced** property page. +1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. 1. Modify the **Error Reporting** property. diff --git a/docs/build/reference/example-visual-cpp.md b/docs/build/reference/example-visual-cpp.md index c5ec5adaa1..95e9710e46 100644 --- a/docs/build/reference/example-visual-cpp.md +++ b/docs/build/reference/example-visual-cpp.md @@ -1,28 +1,29 @@ --- -title: "<example> (C++ documentation comments)" -ms.date: "11/04/2016" -f1_keywords: ["", "example"] +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 @@ -53,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 f418e663f3..0e047d8a41 100644 --- a/docs/build/reference/exception-visual-cpp.md +++ b/docs/build/reference/exception-visual-cpp.md @@ -1,36 +1,37 @@ --- -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> +# `` 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 @@ -58,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/exceptions-c-cpp.md b/docs/build/reference/exceptions-c-cpp.md deleted file mode 100644 index 32201b977c..0000000000 --- a/docs/build/reference/exceptions-c-cpp.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: "DLL loading exception codes (C/C++)" -ms.date: "11/19/2019" -f1_keywords: ["ERROR_MOD_NOT_FOUND", "vcppException", "ERROR_SEVERITY_ERROR"] -helpviewer_keywords: ["vcppException", "C++ exception handling, delayed loading of DLLs", "delayed loading of DLLs, exceptions", "ERROR_SEVERITY_ERROR exception", "ERROR_MOD_NOT_FOUND exception"] -ms.assetid: c03be05d-1c39-4f35-84cf-00c9af3bae9a ---- -# Exceptions (C/C++) - -Two exception codes can be raised when failures are encountered: - -- For a **LoadLibrary** failure - -- For a **GetProcAddress** failure - -Here is the exception information: - -``` -// -// Exception information -// -#define FACILITY_VISUALCPP ((LONG)0x6d) -#define VcppException(sev,err) ((sev) | (FACILITY_VISUALCPP<<16) | err) -``` - -The exception codes thrown are the standard VcppException(ERROR_SEVERITY_ERROR, ERROR_MOD_NOT_FOUND) and VcppException(ERROR_SEVERITY_ERROR, ERROR_PROC_NOT_FOUND) values. The exception passes a pointer to a **DelayLoadInfo** structure in the LPDWORD value that can be retrieved by **GetExceptionInformation** in the [EXCEPTION_RECORD](/windows/win32/api/winnt/ns-winnt-exception_record) structure, ExceptionInformation[0] field. - -Additionally, if the incorrect bits are set in the grAttrs field, the exception ERROR_INVALID_PARAMETER is thrown. This exception is, for all intents and purposes, fatal. - -See [Structure and Constant Definitions](structure-and-constant-definitions.md) for more information. - -## See also - -[Error Handling and Notification](error-handling-and-notification.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 5094d32b1d..0000000000 --- a/docs/build/reference/executing-a-program-in-preprocessing.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -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 c1ac7988ba..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,50 +1,49 @@ --- -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. Expand the **Configuration Properties**, **C/C++**, **Command Line** folder. +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 a6c3e240ce..bfbcec74a8 100644 --- a/docs/build/reference/experimental-module.md +++ b/docs/build/reference/experimental-module.md @@ -1,42 +1,62 @@ --- title: "/experimental:module (Enable module support)" -description: "Use the /experimental:module compiler option to enable experimental compiler support for modules." -ms.date: "09/03/2019" +description: "Use the /experimental:module compiler option to enable experimental compiler support for named modules." +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 modules, as specified by the draft C++20 standard. +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. You can 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 are not 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. | -Here's an example of the compiler command-line options used to create an export module from source file *ModuleName.ixx*: +The experimental library consists of the following named modules: -```cmd -cl /EHsc /MD /experimental:module /module:export /module:name ModuleName /module:wrapper C:\Output\path\ModuleName.h /module:output C:\Output\path\ModuleName.ifc -c ModuleName.ixx +- `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 -[/Zc (Conformance)](zc-conformance.md) +[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)\ +[`/translateInclude` (Translate include directives into import directives)](translateinclude.md)\ +[`/Zc` (Conformance)](zc-conformance.md) diff --git a/docs/build/reference/experimental-preprocessor.md b/docs/build/reference/experimental-preprocessor.md index 5ab98659a6..f9b88a5726 100644 --- a/docs/build/reference/experimental-preprocessor.md +++ b/docs/build/reference/experimental-preprocessor.md @@ -1,23 +1,23 @@ --- title: "/experimental:preprocessor (Enable preprocessor conformance mode)" description: "Use the /experimental:preprocessor compiler option to enable experimental compiler support for a standard conforming preprocessor." -ms.date: "10/31/2019" +ms.date: 09/10/2020 f1_keywords: ["preprocessor", "/experimental:preprocessor"] helpviewer_keywords: ["preprocessor conformance", "/experimental:preprocessor", "Enable preprocessor conformance mode"] --- -# /experimental:preprocessor (Enable preprocessor conformance mode) +# `/experimental:preprocessor` (Enable preprocessor conformance mode) -This option enables an experimental, token-based preprocessor that more closely conforms to C++11 standards, including C99 preprocessor features. For more information, see [MSVC experimental preprocessor overview](../../preprocessor/preprocessor-experimental-overview.md). +This option is obsolete starting in Visual Studio 2019 version 16.5, replaced by the [`/Zc:preprocessor`](zc-preprocessor.md) compiler option. **`/experimental:preprocessor`** enables an experimental, token-based preprocessor that more closely conforms to C++11 standards, including C99 preprocessor features. For more information, see [MSVC new preprocessor overview](../../preprocessor/preprocessor-experimental-overview.md). ## Syntax -> **/experimental:preprocessor**[**-**] +> **`/experimental:preprocessor`**\[**`-`**] ## Remarks -Use the **/experimental:preprocessor** compiler option to enable the experimental conforming preprocessor. You can use **/experimental:preprocessor-** option to explicitly specify the traditional preprocessor. +Use the **`/experimental:preprocessor`** compiler option to enable the experimental conforming preprocessor. You can use **`/experimental:preprocessor-`** option to explicitly specify the traditional preprocessor. -The **/experimental:preprocessor** option is available starting in Visual Studio 2017 version 15.8. +The **`/experimental:preprocessor`** option is available starting in Visual Studio 2017 version 15.8. Starting in Visual Studio 2019 version 16.5, the new preprocessor is complete, and available under the [`/Zc:preprocessor`](zc-preprocessor.md) compiler option. ### To set this compiler option in the Visual Studio development environment @@ -25,7 +25,7 @@ The **/experimental:preprocessor** option is available starting in Visual Studio 1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Modify the **Additional Options** property to include **/experimental:preprocessor** and then choose **OK**. +1. Modify the **Additional Options** property to include *`/experimental:preprocessor`* and then choose **OK**. ## See also diff --git a/docs/build/reference/explicitly-unloading-a-delay-loaded-dll.md b/docs/build/reference/explicitly-unloading-a-delay-loaded-dll.md deleted file mode 100644 index b422b3b82e..0000000000 --- a/docs/build/reference/explicitly-unloading-a-delay-loaded-dll.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: "Explicitly Unloading a Delay-Loaded DLL" -ms.date: "11/04/2016" -helpviewer_keywords: ["/DELAY:UNLOAD linker option", "DELAY:UNLOAD linker option", "__FUnloadDelayLoadedDLL2", "delayed loading of DLLs, unloading"] -ms.assetid: 1c4c5172-fd06-45d3-9e4f-f12343176b3c ---- -# Explicitly Unloading a Delay-Loaded DLL - -The [/delay](delay-delay-load-import-settings.md):unload linker option allows you to unload a DLL that was delay loaded. By default, when your code unloads the DLL (using /delay:unload and **__FUnloadDelayLoadedDLL2**), the delay-loaded imports remain in the import address table (IAT). However, if you use /delay:unload on the linker command line, the helper function will support the explicit unloading of the DLL, resetting the IAT to its original form; the now-invalid pointers will be overwritten. The IAT is a field in the [ImgDelayDescr](calling-conventions-parameters-and-return-type.md) that contains the address of a copy of the original IAT (if it exists). - -## Example - -### Code - -``` -// link with /link /DELAYLOAD:MyDLL.dll /DELAY:UNLOAD -#include -#include -#include "MyDll.h" -#include - -#pragma comment(lib, "delayimp") -#pragma comment(lib, "MyDll") -int main() -{ - BOOL TestReturn; - // MyDLL.DLL will load at this point - fnMyDll(); - - //MyDLL.dll will unload at this point - TestReturn = __FUnloadDelayLoadedDLL2("MyDll.dll"); - - if (TestReturn) - printf_s("\nDLL was unloaded"); - else - printf_s("\nDLL was not unloaded"); -} -``` - -### Comments - -Important notes on unloading a delay-loaded DLL: - -- You can find the implementation of the **__FUnloadDelayLoadedDLL2** function in the file \VC7\INCLUDE\DELAYHLP.CPP. - -- The name parameter of the **__FUnloadDelayLoadedDLL2** function must exactly match (including case) what the import library contains (that string is also in the import table in the image). You can view the contents of the import library with [DUMPBIN /DEPENDENTS](dependents.md). If a case-insensitive string match is desired, you can update **__FUnloadDelayLoadedDLL2** to use one of the CRT string functions or a Windows API call. - -See [Unloading a Delay-Loaded DLL](unloading-a-delay-loaded-dll.md) for more information. - -## See also - -[Linker Support for Delay-Loaded DLLs](linker-support-for-delay-loaded-dlls.md) diff --git a/docs/build/reference/export-exports-a-function.md b/docs/build/reference/export-exports-a-function.md index 321be5c951..4cdb2520bc 100644 --- a/docs/build/reference/export-exports-a-function.md +++ b/docs/build/reference/export-exports-a-function.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /EXPORT (Exports a Function)" title: "/EXPORT (Exports a Function)" ms.date: "09/05/2018" f1_keywords: ["VC.Project.VCLinkerTool.ExportFunctions", "/export"] diff --git a/docs/build/reference/exports.md b/docs/build/reference/exports.md index 317abc7949..a535ba1d83 100644 --- a/docs/build/reference/exports.md +++ b/docs/build/reference/exports.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: EXPORTS" title: "EXPORTS" ms.date: "09/07/2018" f1_keywords: ["EXPORTS"] 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 8461f9788b..0000000000 --- a/docs/build/reference/expressions-in-makefile-preprocessing.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -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 new file mode 100644 index 0000000000..30134f5f93 --- /dev/null +++ b/docs/build/reference/external-external-headers-diagnostics.md @@ -0,0 +1,213 @@ +--- +title: "/external (External headers diagnostics)" +description: "The Microsoft C++ compiler /external headers diagnostic options syntax and usage." +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 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 (Not required in 16.10 and later): +> **`/experimental:external`** + +Specify external headers: +> **`/external:anglebrackets`**\ +> **`/external:env:`***`var`*\ +> **`/external:I`** *`path`* + +Specify diagnostics behavior: +> **`/external:W0`**\ +> **`/external:W1`**\ +> **`/external:W2`**\ +> **`/external:W3`**\ +> **`/external:W4`**\ +> **`/external:templates-`** + +### Arguments + +**`/experimental:external`**\ +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. + +**`/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`*\ +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. 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) +// the global warning level is now 0 here +#include +#pragma warning (pop) +``` + +**`/external:templates-`**\ +Allows warnings from external headers when they occur in a template that's instantiated in your code. + +## Remarks + +By default, the **`/Wn`** warning level you specify for your build applies to all files. The options to specify external headers only define a set of files to which you can apply a different default warning level. So, if you specify external headers, also use **`/external:Wn`** to specify an external warning level to change compiler behavior. + +All the existing mechanisms to enable, disable, and suppress warnings still work in both external and non-external files. For example, a [`warning` pragma](../../preprocessor/warning.md) can still override the default warning level you set for external headers. + +### Example: Set external warning level + +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 + +template +struct sample_struct +{ + static const T value = -7; // W4: warning C4245: 'initializing': + // conversion from 'int' to 'unsigned int', signed/unsigned mismatch +}; +``` + +Source file `program.cpp`: + +```cpp +// User code: program.cpp +#include + +int main() +{ + return sample_struct().value; +} +``` + +You can build the sample by using this command line: + +```cmd +cl /EHsc /I include_dir /W4 program.cpp +``` + +As expected, this sample generates a warning: + +```Output +program.cpp +include_dir\header_file.h(6): warning C4245: 'initializing': conversion from 'int' to 'const T', signed/unsigned mismatch + with + [ + T=unsigned int + ] +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[\*](#note_experimental): + +```cmd +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[\*](#note_experimental): + +```cmd +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. + +### Enable, disable, or suppress warnings + +All the existing mechanisms to enable, disable, and suppress warnings still work in external headers. When a warning appears because you use the **`/external:templates-`** option, you can still suppress the warning at the point of instantiation. For example, to explicitly suppress the warning in the sample that reappears because of **`/external:templates-`**, use a `warning` pragma directive: + +```cpp +int main() +{ + #pragma warning( suppress : 4245) + return sample_struct().value; +} +``` + +Library writers can use the same mechanisms to enforce certain warnings, or all the warnings at certain level, if they feel those warnings should never be silenced by **`/external:Wn`**. For example, this version of the header file forces warning C4245 to report an error: + +```cpp +// External header: include_dir/header_file.h + +#pragma warning( push, 4 ) +#pragma warning( error : 4245 ) + +template +struct sample_struct +{ + static const T value = -7; // W4: warning C4245: 'initializing': conversion from 'int' + // to 'unsigned int', signed/unsigned mismatch +}; + +#pragma warning( pop ) +``` + +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. + +### `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 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 **`/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)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/extracting-a-library-member.md b/docs/build/reference/extracting-a-library-member.md index d4de937815..7533c0ca2d 100644 --- a/docs/build/reference/extracting-a-library-member.md +++ b/docs/build/reference/extracting-a-library-member.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Extracting a Library Member" title: "Extracting a Library Member" ms.date: "11/04/2016" helpviewer_keywords: ["LIB [C++], extracting library members", "EXTRACT library manager option", "libraries, extracting members", "-EXTRACT library manager option", "extracting library members", "/EXTRACT library manager option"] diff --git a/docs/build/reference/f-set-stack-size.md b/docs/build/reference/f-set-stack-size.md index ad2c9efecb..9d489f868e 100644 --- a/docs/build/reference/f-set-stack-size.md +++ b/docs/build/reference/f-set-stack-size.md @@ -1,34 +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 @@ -36,7 +37,7 @@ You can also set the stack size by: 1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Type the compiler option in the **Additional Options** box. +1. Enter the compiler option in the **Additional Options** box. ### To set this compiler option programmatically @@ -44,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/fa-fa-listing-file.md b/docs/build/reference/fa-fa-listing-file.md index 6c79af3728..c39f694b11 100644 --- a/docs/build/reference/fa-fa-listing-file.md +++ b/docs/build/reference/fa-fa-listing-file.md @@ -1,60 +1,60 @@ --- -title: "/FA, /Fa (Listing File)" -ms.date: "11/04/2016" +title: "/FA, /Fa (Listing file)" +description: "Reference guide to the Microsoft C++ /FA and /Fa (Listing file) compiler option." +ms.date: 11/21/2020 f1_keywords: ["VC.Project.VCCLWCECompilerTool.AssemblerListingLocation", "VC.Project.VCCLCompilerTool.ConfigureASMListing", "VC.Project.VCCLWCECompilerTool.AssemblerOutput", "VC.Project.VCCLCompilerTool.AssemblerListingLocation", "/fa", "VC.Project.VCCLCompilerTool.AssemblerOutput", "VC.Project.VCCLCompilerTool.UseUnicodeForAssemblerListing"] helpviewer_keywords: ["FA compiler option [C++]", "/FA compiler option [C++]", "-FA compiler option [C++]", "listing file type", "assembly-only listing"] -ms.assetid: c7507d0e-c69d-44f9-b8e2-d2c398697402 --- -# /FA, /Fa (Listing File) +# `/FA`, `/Fa` (Listing file) Creates a listing file containing assembler code. ## Syntax -> **/FA**[**c**\][**s**\][**u**] -> **/Fa**_pathname_ +> **`/FA`**[**`c`**\][**`s`**\][**`u`**]\ +> **`/Fa`**_pathname_ ## Remarks -The **/FA** compiler option generates an assembler listing file for each translation unit in the compilation, which generally corresponds to a C or C++ source file. By default, only assembler is included in the listing file, which is encoded as ANSI. The optional **c**, **s**, and **u** arguments to **/FA** control whether machine code or source code are output together with the assembler listing, and whether the listing is encoded as UTF-8. +The **`/FA`** compiler option generates an assembler listing file for each translation unit in the compilation, which generally corresponds to a C or C++ source file. By default, only assembler is included in the listing file, which is encoded as ANSI. The optional **`c`**, **`s`**, and **`u`** arguments to **`/FA`** control whether machine code or source code are output together with the assembler listing, and whether the listing is encoded as UTF-8. -By default, each listing file gets the same base name as the source file, and has a .asm extension. When machine code is included by using the **c** option, the listing file has a .cod extension. You can change the name and extension of the listing file and the directory where it is created by using the **/Fa** option. +By default, each listing file gets the same base name as the source file, and has an *`.asm`* extension. When machine code is included by using the **`c`** option, the listing file has a *`.cod`* extension. You can change the name and extension of the listing file and the directory where it's created by using the **`/Fa`** option. -### /FA arguments +### `/FA` arguments -none
+none\ Only assembler language is included in the listing. -**c**
+**`c`**\ Optional. Includes machine code in the listing. -**s**
+**`s`**\ Optional. Includes source code in the listing. -**u**
-Optional. Encodes the listing file in UTF-8 format, and includes a byte order marker. By default, the file is encoded as ANSI. Use `u` to create a listing file that displays correctly on any system, or if you are using Unicode source code files as input to the compiler. +**`u`**\ +Optional. Encodes the listing file in UTF-8 format, and includes a byte order marker. By default, the file is encoded as ANSI. Use **`u`** to create a listing file that displays correctly on any system, or if you're using Unicode source code files as input to the compiler. -If both **s** and **u** are specified, and if a source code file uses a Unicode encoding other than UTF-8, then the code lines in the .asm file may not display correctly. +If both **`s`** and **`u`** are specified, and if a source code file uses a Unicode encoding other than UTF-8, then the code lines in the *`.asm`* file may not display correctly. -### /Fa argument +### `/Fa` argument -none
-One *source*.asm file is created for each source code file in the compilation. +none\ +One *source.asm* file is created for each source code file in the compilation. -*filename*
-A listing file named *filename*.asm is placed in the current directory. This is only valid when compiling a single source code file. +*filename*\ +The compiler places a listing file named *filename*.asm in the current directory. This argument form is only valid when compiling a single source code file. -*filename.extension*
-A listing file named *filename.extension* is placed in the current directory. This is only valid when compiling a single source code file. +*filename.extension*\ +The compiler places a listing file named *filename.extension* in the current directory. This argument form is only valid when compiling a single source code file. -*directory*__\\__
-One *source_file*.asm file is created and placed in the specified *directory* for each source code file in the compilation. Note the required trailing backslash. Only paths on the current disk are allowed. +*directory*__\\__\ +The compiler creates one *source_file.asm* file for each source code file in the compilation. It's placed in the specified *directory*. The trailing backslash is required. Only paths on the current disk are allowed. -*directory*__\\__*filename*
-A listing file named *filename*.asm is placed in the specified *directory*. This is only valid when compiling a single source code file. +*directory*__\\__*filename*\ +A listing file named *filename.asm* is placed in the specified *directory*. This argument form is only valid when compiling a single source code file. -*directory*__\\__*filename.extension*
-A listing file named *filename.extension* is placed in the specified *directory*. This is only valid when compiling a single source code file. +*directory*__\\__*filename.extension*\ +A listing file named *filename.extension* is placed in the specified *directory*. This argument form is only valid when compiling a single source code file. ### To set this compiler option in the Visual Studio development environment @@ -62,9 +62,9 @@ A listing file named *filename.extension* is placed in the specified *directory* 1. Select the **Configuration Properties** > **C/C++** > **Output Files** property page. -1. Modify the **Assembler Output** property to set the **/FAc** and **/FAs** options for assembler, machine, and source code. Modify the **Use Unicode For Assembler Listing** property to set the **/FAu** option for ANSI or UTF-8 output. Modify the **ASM List Location** to set the **/Fa** option for listing file name and location. +1. Modify the **Assembler Output** property to set the **/FAc** and **/FAs** options for assembler, machine, and source code. Modify the **Use Unicode For Assembler Listing** property to set the **`/FAu`** option for ANSI or UTF-8 output. Modify the **ASM List Location** to set the **`/Fa`** option for listing file name and location. -Note that setting both **Assembler Output** and **Use Unicode For Assembler Listing** properties can cause [Command-Line Warning D9025](../../error-messages/tool-errors/command-line-warning-d9025.md). To combine these options in the IDE, use the **Additional Options** field in the **Command Line** property page instead. +Setting both **Assembler Output** and **Use Unicode For Assembler Listing** properties can cause [Command-Line Warning D9025](../../error-messages/tool-errors/command-line-warning-d9025.md). To combine these options in the IDE, use the **Additional Options** field in the **Command Line** property page instead. ### To set this compiler option programmatically @@ -72,7 +72,7 @@ Note that setting both **Assembler Output** and **Use Unicode For Assembler List ## Example -The following command line produces a combined source and machine-code listing called HELLO.cod: +The following command line produces a combined source and machine-code listing called *`HELLO.cod`*: ```cmd CL /FAcs HELLO.CPP @@ -80,7 +80,7 @@ CL /FAcs HELLO.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)
+[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/failure-hooks.md b/docs/build/reference/failure-hooks.md deleted file mode 100644 index e54f979036..0000000000 --- a/docs/build/reference/failure-hooks.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: "Failure Hooks" -ms.date: "11/04/2016" -helpviewer_keywords: ["delayed loading of DLLs, failure hooks"] -ms.assetid: 12bb303b-ffe6-4471-bffe-9ef4f8bb2d30 ---- -# Failure Hooks - -The failure hook is enabled in the same manner as the [notification hook](notification-hooks.md). The hook routine needs to return a suitable value so that processing can continue (an HINSTANCE or FARPROC) or 0 to indicate that an exception should be thrown. - -The pointer variable that refers to the user-defined function is: - -``` -// This is the failure hook, dliNotify = {dliFailLoadLib|dliFailGetProc} -ExternC -PfnDliHook __pfnDliFailureHook2; -``` - -The **DelayLoadInfo** structure contains all the pertinent data necessary for accurate reporting of the error, including the value from `GetLastError`. - -If the notification is **dliFailLoadLib**, the hook function can return: - -- 0, if it cannot handle the failure. - -- An HMODULE, if the failure hook fixed the problem and loaded the library itself. - -If the notification is **dliFailGetProc**, the hook function can return: - -- 0, if it cannot handle the failure. - -- A valid proc address (import function address), if the failure hook succeeded in getting the address itself. - -## See also - -[Error Handling and Notification](error-handling-and-notification.md) diff --git a/docs/build/reference/favor-optimize-for-architecture-specifics.md b/docs/build/reference/favor-optimize-for-architecture-specifics.md index 007d7b27cd..57dd5b9016 100644 --- a/docs/build/reference/favor-optimize-for-architecture-specifics.md +++ b/docs/build/reference/favor-optimize-for-architecture-specifics.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /favor (Optimize for Architecture Specifics)" title: "/favor (Optimize for Architecture Specifics)" ms.date: "11/04/2016" f1_keywords: ["/favor"] @@ -36,9 +37,7 @@ For information about how to program for the x64 architecture, see [x64 Software 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 **C/C++** folder. - -1. Select the **Command Line** property page. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. 1. Enter the compiler option in the **Additional Options** box. 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 d5ba42c213..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 @@ -1,42 +1,53 @@ --- -title: "/FC (Full Path of Source Code File in Diagnostics)" -ms.date: "11/04/2016" -f1_keywords: ["VC.Project.VCCLCompilerTool.UseFullPaths", "/FC"] +description: "Learn more about: /FC (Full path of source code file in diagnostics)" +title: "/FC (Full path of source code file in diagnostics)" +ms.date: 04/26/2021 +f1_keywords: ["VC.Project.VCCLCompilerTool.UseFullPaths", "/FC", "-FC"] helpviewer_keywords: ["/FC compiler option [C++]", "-FC compiler option [C++]"] ms.assetid: 1f11414e-cb42-421b-be68-9d369aab036b --- -# /FC (Full Path of Source Code File in Diagnostics) +# `/FC` (Full path of source code file in diagnostics) Causes the compiler to display the full path of source code files passed to the compiler in diagnostics. ## Syntax -> /FC +> **`/FC`** ## Remarks -Consider the following code sample: +Consider the following code sample, where the source file is located in *`C:\test\compiler_option_FC.cpp`*: ```cpp // compiler_option_FC.cpp + int main( ) { int i // C2143 } ``` -Without **/FC**, the diagnostic text would look similar to this diagnostic text: +Without **`/FC`**, the compiler output looks similar to this diagnostic text: + +- compiler_option_FC.cpp(5): error C2143: syntax error: missing ';' before '}' + +With **`/FC`**, the compiler output looks similar to this diagnostic text: + +::: moniker range="<=msvc-150" + +- c:\test\compiler_option_fc.cpp(5): error C2143: syntax error: missing ';' before '}' -- compiler_option_FC.cpp(5) : error C2143: syntax error : missing ';' before '}' +::: moniker-end +::: moniker range=">=msvc-160" -With **/FC**, the diagnostic text would look similar to this diagnostic text: +- C:\test\compiler_option_FC.cpp(5): error C2143: syntax error: missing ';' before '}' -- c:\test\compiler_option_fc.cpp(5) : error C2143: syntax error : missing ';' before '}' +::: moniker-end -**/FC** is also needed if you want to see the full path of a file name when using the __FILE__ macro. See [Predefined Macros](../../preprocessor/predefined-macros.md) for more information on __FILE__. +**`/FC`** is also needed if you want to see the full path of a file name when using the `__FILE__` macro. For more information about `__FILE__`, see [Predefined macros](../../preprocessor/predefined-macros.md). -The **/FC** option is implied by **/ZI**. For more information about **/ZI**, see [/Z7, /Zi, /ZI (Debug Information Format)](z7-zi-zi-debug-information-format.md). +The **`/FC`** option is implied by **`/ZI`**. For more information about **`/ZI`**, see [`/Z7, /Zi, /ZI` (Debug information format)](z7-zi-zi-debug-information-format.md). -**/FC** outputs full paths in lower case. +In Visual Studio 2017 and earlier versions, **`/FC`** outputs full paths in lower case. Starting in Visual Studio 2019, **`/FC`** uses the same casing as the file system for full paths. ### To set this compiler option in the Visual Studio development environment @@ -46,11 +57,11 @@ The **/FC** option is implied by **/ZI**. For more information about **/ZI**, se 1. Modify the **Use Full Paths** property. -### To set this linker option programmatically +### 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) +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/fd-ide-minimal-rebuild.md b/docs/build/reference/fd-ide-minimal-rebuild.md index 6c687f1d64..c8c608806a 100644 --- a/docs/build/reference/fd-ide-minimal-rebuild.md +++ b/docs/build/reference/fd-ide-minimal-rebuild.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /FD (IDE Minimal Rebuild)" title: "/FD (IDE Minimal Rebuild)" ms.date: "04/08/2019" helpviewer_keywords: ["/FD compiler option [C++]", "-FD compiler option [C++]", "FD compiler option [C++]"] diff --git a/docs/build/reference/fd-program-database-file-name.md b/docs/build/reference/fd-program-database-file-name.md index 8caa8afe17..c9027012f2 100644 --- a/docs/build/reference/fd-program-database-file-name.md +++ b/docs/build/reference/fd-program-database-file-name.md @@ -1,9 +1,9 @@ --- title: "/Fd (Program Database File Name)" -ms.date: "11/04/2016" +description: "Learn more about: /Fd (Program Database File Name)" +ms.date: 11/04/2016 f1_keywords: ["/FD", "VC.Project.VCCLWCECompilerTool.ProgramDataBaseFileName", "VC.Project.VCCLCompilerTool.ProgramDataBaseFileName"] helpviewer_keywords: ["/FD compiler option [C++]", "program database file name [C++]", "-FD compiler option [C++]", "PDB files, creating", "program database compiler option [C++]", ".pdb files, creating", "FD compiler option [C++]"] -ms.assetid: 3977a9ed-f0ac-45df-bf06-01cedd2ba85a --- # /Fd (Program Database File Name) @@ -29,9 +29,7 @@ This option also names the state (.idb) file used for minimal rebuild and increm 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 **C/C++** folder. - -1. Click the **Output Files** property page. +1. Select the **Configuration Properties** > **C/C++** > **Output Files** property page. 1. Modify the **Program Database File Name** property. @@ -43,7 +41,7 @@ This option also names the state (.idb) file used for minimal rebuild and increm This command line creates a .pdb file named PROG.pdb and an .idb file named PROG.idb: -``` +```cmd CL /DDEBUG /Zi /FdPROG.PDB PROG.CPP ``` diff --git a/docs/build/reference/fe-name-exe-file.md b/docs/build/reference/fe-name-exe-file.md index fc36b374d4..02c71317a5 100644 --- a/docs/build/reference/fe-name-exe-file.md +++ b/docs/build/reference/fe-name-exe-file.md @@ -1,9 +1,9 @@ --- title: "/Fe (Name EXE File)" -ms.date: "11/04/2016" +description: "Learn more about: /Fe (Name EXE File)" +ms.date: 11/04/2016 f1_keywords: ["/fe"] helpviewer_keywords: ["-Fe compiler option [C++]", "executable files, renaming", "rename file compiler option [C++]", "/Fe compiler option [C++]", "Fe compiler option [C++]"] -ms.assetid: 49f594fd-5e94-45fe-a1bf-7c9f2abb6437 --- # /Fe (Name EXE File) @@ -21,7 +21,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. @@ -31,7 +31,7 @@ If you specify the [/c (Compile Without Linking)](c-compile-without-linking.md) 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 **Configuration Properties** > **Linker** > **General** property page. +1. Select the **Configuration Properties** > **Linker** > **General** property page. 1. Modify the **Output File** property. Choose **OK** to save your changes. @@ -39,19 +39,17 @@ If you specify the [/c (Compile Without Linking)](c-compile-without-linking.md) - See . -## Example +## Examples The following command line compiles and links all C source files in the current directory. The resulting executable file is named PROCESS.exe and is created in the directory "C:\Users\User Name\repos\My Project\bin". -``` +```cmd CL /Fe"C:\Users\User Name\repos\My Project\bin\PROCESS" *.C ``` -## Example - The following command line creates an executable file in `C:\BIN` with the same base name as the first source file in the current directory: -``` +```cmd CL /FeC:\BIN\ *.C ``` 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/fi-name-forced-include-file.md b/docs/build/reference/fi-name-forced-include-file.md index 86cee90fbd..48184defa9 100644 --- a/docs/build/reference/fi-name-forced-include-file.md +++ b/docs/build/reference/fi-name-forced-include-file.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /FI (Name Forced Include File)" title: "/FI (Name Forced Include File)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCNMakeTool.ForcedIncludes", "VC.Project.VCCLCompilerTool.ForcedIncludeFiles", "VC.Project.VCCLWCECompilerTool.ForcedIncludeFiles"] @@ -23,9 +24,7 @@ This option has the same effect as specifying the file with double quotation mar 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 **C/C++** folder. - -1. Click the **Advanced** property page. +1. Select the **Configuration Properties** > **C/C++** > **Advanced** property page. 1. Modify the **Forced Include File** property. diff --git a/docs/build/reference/fi-preprocess-output-file-name.md b/docs/build/reference/fi-preprocess-output-file-name.md index ac7587a29c..a13d7f5cb3 100644 --- a/docs/build/reference/fi-preprocess-output-file-name.md +++ b/docs/build/reference/fi-preprocess-output-file-name.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: `/Fi` (Preprocess output file name)" title: "/Fi (Preprocess Output File Name)" ms.date: 08/12/2020 f1_keywords: ["/Fi"] diff --git a/docs/build/reference/file-types-created-for-visual-cpp-projects.md b/docs/build/reference/file-types-created-for-visual-cpp-projects.md index 6dc321c6b6..b26bf12c98 100644 --- a/docs/build/reference/file-types-created-for-visual-cpp-projects.md +++ b/docs/build/reference/file-types-created-for-visual-cpp-projects.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: File Types Created for Visual Studio C++ Projects" title: "File Types Created for Visual Studio C++ projects" ms.date: "04/08/2019" helpviewer_keywords: ["header files [C++], Visual Studio projects", "ActiveX controls [C++], Help files", "def files", "project items [C++], files", "Visual Studio C++ projects, files and directories", "resource files, created by wizard", "files [C++], extensions", "Help files, for ActiveX controls", "Web projects [C++], adding items", ".def files", "licensing ActiveX controls"] diff --git a/docs/build/reference/filealign.md b/docs/build/reference/filealign.md index 05189e96d7..1e794ab0e1 100644 --- a/docs/build/reference/filealign.md +++ b/docs/build/reference/filealign.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /FILEALIGN (Align sections in files)" title: "/FILEALIGN (Align sections in files)" ms.date: "10/23/2017" f1_keywords: ["/filealign"] @@ -7,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 @@ -30,9 +31,9 @@ Use [DUMPBIN](dumpbin-reference.md) to see information about sections in your ou 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 **Command Line** property page in the **Linker** folder. +1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. -1. Type the option name **/FILEALIGN:** and the size in the **Additional Options** box. +1. Enter the option name **/FILEALIGN:** and the size in the **Additional Options** box. ### To set this linker option programmatically diff --git a/docs/build/reference/filename-macros.md b/docs/build/reference/filename-macros.md deleted file mode 100644 index 5c7b12276f..0000000000 --- a/docs/build/reference/filename-macros.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -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 e460dc33e5..0000000000 --- a/docs/build/reference/filename-parts-syntax.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -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/files-created-for-clr-projects.md b/docs/build/reference/files-created-for-clr-projects.md index 9a3327708a..1aa648278b 100644 --- a/docs/build/reference/files-created-for-clr-projects.md +++ b/docs/build/reference/files-created-for-clr-projects.md @@ -1,8 +1,8 @@ --- title: "Files Created for CLR Projects" -ms.date: "11/04/2016" +description: "Learn more about: Files Created for CLR Projects" +ms.date: 11/04/2016 helpviewer_keywords: ["Visual Studio C++ projects, CLR programming", ".NET applications, C++"] -ms.assetid: 59ae9020-5f26-4ad0-bbdd-97c2e2023a20 --- # Files Created for CLR Projects @@ -10,7 +10,7 @@ When you use Visual C++ templates to create your projects, several files are cre |File name|File description| |---------------|----------------------| -|AssemblyInfo.cpp|The file that contains information (that is, attributes, files, resources, types, versioning information, signing information, and so on) for modifying the project's assembly metadata. For more information see [Assembly Concepts](/dotnet/framework/app-domains/assembly-contents).| +|AssemblyInfo.cpp|The file that contains information (that is, attributes, files, resources, types, versioning information, signing information, and so on) for modifying the project's assembly metadata. For more information, see [Assembly Concepts](/dotnet/framework/app-domains/assembly-contents).| |*projname*.asmx|A text file that references managed classes that encapsulate the functionality of the XML Web service.| |*projname*.cpp|The main source file and entry point into the application that Visual Studio created for you. Identifies the project .dll file and the project namespace. Provide your own code in this file.| |*projname*.vsdisco|An XML deployment file containing links to other resources that describe the XML Web service.| diff --git a/docs/build/reference/fixed-fixed-base-address.md b/docs/build/reference/fixed-fixed-base-address.md index 2ceb7fdf3e..eb98ccae97 100644 --- a/docs/build/reference/fixed-fixed-base-address.md +++ b/docs/build/reference/fixed-fixed-base-address.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /FIXED (Fixed Base Address)" title: "/FIXED (Fixed Base Address)" ms.date: "11/04/2016" f1_keywords: ["/fixed", "VC.Project.VCLinkerTool.FixedBaseAddress"] @@ -25,11 +26,9 @@ Specify /FIXED:NO to generate a relocation section in the program. 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. Select the **Configuration Properties** > **Linker** > **Command Line** property page. -1. Select the **Command Line** property page. - -1. Type the option name and setting in the **Additional Options** box. +1. Enter the option name and setting in the **Additional Options** box. ### To set this linker option programmatically diff --git a/docs/build/reference/fm-name-mapfile.md b/docs/build/reference/fm-name-mapfile.md index c89297620a..14a4869427 100644 --- a/docs/build/reference/fm-name-mapfile.md +++ b/docs/build/reference/fm-name-mapfile.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Fm (Name Mapfile)" title: "/Fm (Name Mapfile)" ms.date: "11/04/2016" f1_keywords: ["/fm"] @@ -17,23 +18,21 @@ Tells the linker to produce a mapfile containing a list of segments in the order ## Remarks -By default, the mapfile is given the base name of the corresponding C or C++ source file with a .MAP extension. +By default, the map file is given the base name of the corresponding C or C++ source file with a *`.MAP`* extension. Specifying **/Fm** has the same effect as if you had specified the [/MAP (Generate Mapfile)](map-generate-mapfile.md) linker option. If you specify [/c (Compile Without Linking)](c-compile-without-linking.md) to suppress linking, **/Fm** has no effect. -Global symbols in a mapfile usually have one or more leading underscores because the compiler adds a leading underscore to variable names. Many global symbols that appear in the mapfile are used internally by the compiler and the standard libraries. +Global symbols in a map file usually have one or more leading underscores. It's because the compiler adds a leading underscore to variable names. Many global symbols that appear in the map file are used internally by the compiler and the standard libraries. ### 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. Click the **C/C++** folder. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Click the **Command Line** property page. - -1. Type the compiler option in the **Additional Options** box. +1. Enter the compiler option in the **Additional Options** box. ### To set this compiler option programmatically 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 8c53219fa8..0df90153e1 100644 --- a/docs/build/reference/force-force-file-output.md +++ b/docs/build/reference/force-force-file-output.md @@ -1,43 +1,45 @@ --- -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 @@ -45,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 46696740aa..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. @@ -24,7 +24,7 @@ If you don't specify an extension as part of the *pathname*, an extension of *pc 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 **Configuration Properties** > **C/C++** > **Precompiled Headers** property page. +1. Select the **Configuration Properties** > **C/C++** > **Precompiled Headers** property page. 1. Modify the **Precompiled Header Output File** property. diff --git a/docs/build/reference/fp-specify-floating-point-behavior.md b/docs/build/reference/fp-specify-floating-point-behavior.md index 79c24f177c..47f650de28 100644 --- a/docs/build/reference/fp-specify-floating-point-behavior.md +++ b/docs/build/reference/fp-specify-floating-point-behavior.md @@ -1,70 +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` | -||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 @@ -72,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 @@ -133,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 @@ -149,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 @@ -171,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 @@ -204,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) @@ -215,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) @@ -224,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 @@ -234,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 @@ -256,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/fpo.md b/docs/build/reference/fpo.md index 0d3cedc870..58d6575c40 100644 --- a/docs/build/reference/fpo.md +++ b/docs/build/reference/fpo.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /FPO" title: "/FPO" ms.date: "11/04/2016" f1_keywords: ["/fpo"] 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 aec5143cfc..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,44 +1,46 @@ --- -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 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. In the navigation pane, choose the **C/C++**, **Browse Information** property page. +1. Select the **Configuration Properties** > **C/C++** > **Browse Information** property page. 1. Modify the **Browse Information File** or **Enable Browse Information** property. @@ -48,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/fs-force-synchronous-pdb-writes.md b/docs/build/reference/fs-force-synchronous-pdb-writes.md index 3106597ffb..c4b2b6d51d 100644 --- a/docs/build/reference/fs-force-synchronous-pdb-writes.md +++ b/docs/build/reference/fs-force-synchronous-pdb-writes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /FS (Force Synchronous PDB Writes)" title: "/FS (Force Synchronous PDB Writes)" ms.date: "11/04/2016" f1_keywords: ["/FS"] @@ -25,9 +26,7 @@ The [/MP](mp-build-with-multiple-processes.md) option enables **/FS** by default 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 **C/C++** folder. - -1. Select the **Command Line** property page. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. 1. Modify the **Additional Options** property to include `/FS` and then choose **OK**. 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 new file mode 100644 index 0000000000..6e9e8c9439 --- /dev/null +++ b/docs/build/reference/fsanitize.md @@ -0,0 +1,76 @@ +--- +description: "Learn more about the /fsanitize (enable sanitizers) compiler option" +title: "/fsanitize (Enable sanitizers)" +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. + +## 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 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=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=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 + +1. Open your project's **Property Pages** dialog box. + +1. Select the **Configuration Properties** > **C/C++** > **General** property page. + +1. Modify the **Enable Address Sanitizer** property. To enable it, choose **Yes (/fsanitize=address)**. + +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. + +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. + +1. Modify the **Additional Options** property to set **/fsanitize-address-use-after-return** or **/fno-sanitize-address-vcasan-lib**. + +1. Choose **OK** or **Apply** 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)\ +[`/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/fu-name-forced-hash-using-file.md b/docs/build/reference/fu-name-forced-hash-using-file.md index dcf43ef4c4..9c43dc267b 100644 --- a/docs/build/reference/fu-name-forced-hash-using-file.md +++ b/docs/build/reference/fu-name-forced-hash-using-file.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /FU (Name Forced #using File)" title: "/FU (Name Forced #using File)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCCLCompilerTool.ForcedUsingFiles", "/FU", "VC.Project.VCNMakeTool.ForcedUsingAssemblies"] diff --git a/docs/build/reference/functionpadmin-create-hotpatchable-image.md b/docs/build/reference/functionpadmin-create-hotpatchable-image.md index 46f1da302c..98057d1ebd 100644 --- a/docs/build/reference/functionpadmin-create-hotpatchable-image.md +++ b/docs/build/reference/functionpadmin-create-hotpatchable-image.md @@ -1,36 +1,37 @@ --- -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 @@ -38,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/fx-merge-injected-code.md b/docs/build/reference/fx-merge-injected-code.md index b98bb521e9..2cfbde93dd 100644 --- a/docs/build/reference/fx-merge-injected-code.md +++ b/docs/build/reference/fx-merge-injected-code.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Fx (Merge Injected Code)" title: "/Fx (Merge Injected Code)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCCLWCECompilerTool.ExpandAttributedSource", "/Fx", "VC.Project.VCCLCompilerTool.ExpandAttributedSource"] @@ -38,7 +39,7 @@ In an .mrg file, code that was injected because of an attribute will be delimite //--- End Injected Code ``` -The [no_injected_text](../../windows/no-injected-text.md) attribute is embedded in an .mrg file, which allows for the compilation of the .mrg file without text being reinjected. +The [no_injected_text](../../windows/attributes/no-injected-text.md) attribute is embedded in an .mrg file, which allows for the compilation of the .mrg file without text being reinjected. You should be aware that the .mrg source file is intended to be a representation of the source code injected by the compiler. The .mrg file may not compile or run exactly as the original source file. @@ -50,9 +51,7 @@ If your program includes a header file that uses injected code, **/Fx** generate 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 **C/C++** folder. - -1. Click the **Output Files** property page. +1. Select the **Configuration Properties** > **C/C++** > **Output Files** property page. 1. Modify the **Expand Attributed Source** property. diff --git a/docs/build/reference/ga-optimize-for-windows-application.md b/docs/build/reference/ga-optimize-for-windows-application.md index 1c867fb94f..c0f0de2ae0 100644 --- a/docs/build/reference/ga-optimize-for-windows-application.md +++ b/docs/build/reference/ga-optimize-for-windows-application.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /GA (Optimize for Windows Application)" title: "/GA (Optimize for Windows Application)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCCLCompilerTool.OptimizeForWindowsApplication", "/ga"] @@ -25,11 +26,9 @@ Using **/GA** for a DLL can result in bad code generation. 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 **C/C++** folder. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Click the **Command Line** property page. - -1. Type the compiler option in the **Additional Options** box. +1. Enter the compiler option in the **Additional Options** box. ### To set this compiler option programmatically 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 1014088145..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,9 +1,9 @@ --- 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) @@ -43,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 @@ -78,7 +78,7 @@ For C, the **`__vectorcall`** naming convention uses the function name followed 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 **C/C++** > **Advanced** property page. +1. Select the **Configuration Properties** > **C/C++** > **Advanced** property page. 1. Modify the **Calling Convention** property. diff --git a/docs/build/reference/ge-enable-stack-probes.md b/docs/build/reference/ge-enable-stack-probes.md index a1dd5d9d4e..e7d1d6c044 100644 --- a/docs/build/reference/ge-enable-stack-probes.md +++ b/docs/build/reference/ge-enable-stack-probes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Ge (Enable Stack Probes)" title: "/Ge (Enable Stack Probes)" ms.date: "11/04/2016" f1_keywords: ["/ge"] @@ -27,11 +28,9 @@ This mechanism is useful if you rewrite the functionality of the stack probe. It 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 **C/C++** folder. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Click the **Command Line** property page. - -1. Type the compiler option in the **Additional Options** box. +1. Enter the compiler option in the **Additional Options** box. ### To set this compiler option programmatically diff --git a/docs/build/reference/general-property-page-file.md b/docs/build/reference/general-property-page-file.md index d38641cff3..f4dc2206c6 100644 --- a/docs/build/reference/general-property-page-file.md +++ b/docs/build/reference/general-property-page-file.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: General Property Page (File)" title: "General Property Page (File)" ms.date: "08/30/2019" f1_keywords: ["VC.Project.VCFileConfiguration.ExcludedFromBuild", "VC.Project.VCFileConfiguration.Tool"] @@ -20,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?view=vs-2019#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 bf58189cf8..5fd0640279 100644 --- a/docs/build/reference/general-property-page-project.md +++ b/docs/build/reference/general-property-page-project.md @@ -1,204 +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=">=vs-2019" +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). -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++)](/cpp/cross-platform/general-android-prop-page). For Android Makefile projects, see [General Project Properties (Android C++ Makefile)](/cpp/cross-platform/general-makefile-android-prop-page) +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. -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: +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: -- **Output Directory** +- General - 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)\. +- Project Defaults - To programmatically access this property, see . +## General -- **Intermediate Directory** +The General property heading includes some combination of these properties: - 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)\. +### Target Platform - To programmatically access this property, see . +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. -- **Target Name** +### Target Platform Version - Specifies the file name this project generates. By default, this property is the filename specified by the macro $(ProjectName). +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. -- **Configuration Type** +### Target Platform Min. Version - There are several configuration types from which to choose: +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. - - **Application (.exe)** +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 linker toolset (C/C++ Compiler, MIDL, Resource Compiler, Linker, BSCMake, XML Web Service Proxy Generator, custom build, prebuild, prelink, postbuild events). +### Windows SDK Version - - **Dynamic Library (.dll)** +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 linker toolset, specifies /DLL linker option, and adds the _WINDLL define to CL. +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). - - **Makefile** +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). - Displays makefile toolset (NMake). +### Output Directory - - **Static Library (.lib)** +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)\`. - Displays librarian toolset (same as linker toolset except substitute librarian for linker and omit XML Web Service Proxy Generator). +To programmatically access this property, see . - - **Utility** +### Intermediate Directory - Displays utility toolset (MIDL, custom build, prebuild, postbuild events). +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)\`. - To programmatically access this property, see . +To programmatically access this property, see . -- **Windows SDK Version** +### Target Name - 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 file name this project generates. By default, this property is the filename specified by the macro `$(ProjectName)`. - 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). +### Target Extension - 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 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). -- **Platform Toolset** +### Extensions to Delete on Clean - 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). +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. -- **C++ Language Standard** +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). - 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) +### Build Log File -::: moniker-end +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). -::: moniker range="<=vs-2017" +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). -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: +### Platform Toolset -- General - -- Project Defaults - -## General +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). -- **Target Platform** +### Enable Managed Incremental Build - 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. +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). -- **Target Platform Version (Visual Studio 2015)** +::: moniker range=">=msvc-160" - 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. +### Configuration Type - 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. +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: -- **Windows SDK Version (Visual Studio 2017)** +#### Application (.exe) - 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. +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 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). +#### Dynamic Library (.dll) - 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). +Displays the linker toolset, specifies the **`/DLL`** linker option, and adds the `_WINDLL` preprocessor definition to the CL command line. -- **Output Directory** +#### Makefile - 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 makefile toolset (NMake). - To programmatically access this property, see . +#### Static Library (.lib) -- **Intermediate Directory** +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. - 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)\. +#### Utility - To programmatically access this property, see . +Displays the utility toolset (MIDL, custom build, prebuild, and postbuild events). -- **Target Name** +To programmatically access this property, see . - Specifies the file name this project generates. By default, this property is the filename specified by the macro $(ProjectName). +### C++ Language Standard -- **Target Extension** +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). - Specifies the file name extension this project generates; for example, .exe or .dll. +### C Language Standard -- **Extensions to Delete on Clean** +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) - 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. - - To programmatically access this property, see . - -- **Build Log File** - - 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. - - 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 163d9a44a6..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,48 +1,57 @@ --- title: "/GENPROFILE, /FASTGENPROFILE (Generate Profiling Instrumented Build)" -ms.date: "03/14/2018" +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"] -ms.assetid: deff5ce7-46f5-448a-b9cd-a7a83a6864c6 --- -# /GENPROFILE, /FASTGENPROFILE (Generate Profiling Instrumented Build) +# `/GENPROFILE`, `/FASTGENPROFILE` (Generate Profiling Instrumented Build) -Specifies generation of a .pgd file by the linker to support profile-guided optimization (PGO). **/GENPROFILE** and **/FASTGENPROFILE** use different default parameters. Use **/GENPROFILE** to favor precision over speed and memory usage during profiling. Use **/FASTGENPROFILE** to favor smaller memory usage and speed over precision. +Specifies generation of a *`.pgd`* file by the linker to support profile-guided optimization (PGO). **`/GENPROFILE`** and **`/FASTGENPROFILE`** use different default parameters. Use **`/GENPROFILE`** to favor precision over speed and memory usage during profiling. Use **`/FASTGENPROFILE`** to favor smaller memory usage and speed over precision. ## Syntax -> **/GENPROFILE**[**:**{[**COUNTER32**|**COUNTER64**]|[**EXACT**|**NOEXACT**]|**MEMMAX=**_#_|**MEMMIN=**_#_|[**PATH**|**NOPATH** ]|[**TRACKEH** |**NOTRACKEH** ]|**PGD=**_filename_}]\ -> **/FASTGENPROFILE**[**:**{[**COUNTER32**|**COUNTER64**]|[**EXACT**|**NOEXACT**]|**MEMMAX=**_#_|**MEMMIN=**_#_|[**PATH**|**NOPATH** ]|[**TRACKEH** |**NOTRACKEH** ]|**PGD=**_filename_}] +> **`/GENPROFILE`**\[**`:`**_`profile-argument`_\[**`,`**_`profile-argument`_ ...]]\ +> **`/FASTGENPROFILE`**\[**`:`**_`profile-argument`_\[**`,`**_`profile-argument`_ ...]] + +> *`profile-argument`*\ +>  { **`COUNTER32`** | **`COUNTER64`** }\ +>  { **`EXACT`** | **`NOEXACT`** }\ +>  **`MEMMAX=`**_value_\ +>  **`MEMMIN=`**_value_\ +>  { **`PATH`** | **`NOPATH`** }\ +>  { **`TRACKEH`** | **`NOTRACKEH`** }\ +>  **`PGD=`**_filename_ ### Arguments -Any of the following arguments may be specified to **/GENPROFILE** or **/FASTGENPROFILE**. Arguments listed here separated by a pipe (**|**) character are mutually exclusive. Use a comma (**,**) character to separate options. +Any of the *`profile-argument`* arguments may be specified to **`/GENPROFILE`** or **`/FASTGENPROFILE`**. Arguments listed here separated by a pipe character (**`|`**) are mutually exclusive. Use a comma character (**`,`**) to separate arguments. Don't put spaces between arguments, commas, or after the colon (**`:`**). -**COUNTER32** | **COUNTER64**
-Use **COUNTER32** to specify the use of 32-bit probe counters, and **COUNTER64** to specify 64-bit probe counters. When you specify **/GENPROFILE**, the default is **COUNTER64**. When you specify **/FASTGENPROFILE**, the default is **COUNTER32**. +**`COUNTER32`** | **`COUNTER64`**\ +Use **`COUNTER32`** to specify the use of 32-bit probe counters, and **`COUNTER64`** to specify 64-bit probe counters. When you specify **`/GENPROFILE`**, the default is **`COUNTER64`**. When you specify **`/FASTGENPROFILE`**, the default is **`COUNTER32`**. -**EXACT** | **NOEXACT**
-Use **EXACT** to specify thread-safe interlocked increments for probes. **NOEXACT** specifies unprotected increment operations for probes. The default is **NOEXACT**. +**`EXACT`** | **`NOEXACT`**\ +Use **`EXACT`** to specify thread-safe interlocked increments for probes. **`NOEXACT`** specifies unprotected increment operations for probes. The default is **`NOEXACT`**. -**MEMMAX**=*value*, **MEMMIN**=*value*
-Use **MEMMAX** and **MEMMIN** to specify the maximum and minimum reservation sizes for training data in memory. The value is the amount of memory to reserve in bytes. By default, these values are determined by an internal heuristic. +**`MEMMAX`**=*value*, **`MEMMIN`**=*value*\ +Use **`MEMMAX`** and **`MEMMIN`** to specify the maximum and minimum reservation sizes for training data in memory. The value is the amount of memory to reserve in bytes. By default, these values are determined by an internal heuristic. -**PATH** | **NOPATH**
-Use **PATH** to specify a separate set of PGO counters for each unique path to a function. Use **NOPATH** to specify only one set of counters for each function. When you specify **/GENPROFILE**, the default is **PATH** . When you specify **/FASTGENPROFILE**, the default is **NOPATH** . +**`PATH`** | **`NOPATH`**\ +Use **`PATH`** to specify a separate set of PGO counters for each unique path to a function. Use **`NOPATH`** to specify only one set of counters for each function. When you specify **`/GENPROFILE`**, the default is **`PATH`** . When you specify **`/FASTGENPROFILE`**, the default is **`NOPATH`** . -**TRACKEH** | **NOTRACKEH**
-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 does not use exception handling or that does not encounter exceptions in your training scenarios. When you specify **/GENPROFILE**, the default is **TRACKEH** . When you specify **/FASTGENPROFILE**, the default is **NOTRACKEH** . +**`TRACKEH`** | **`NOTRACKEH`**\ +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. +**`PGD`**=*filename*\ +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 -The **/GENPROFILE** and **/FASTGENPROFILE** options tell the linker to generate the profiling instrumentation file needed to support application training for profile-guided optimization (PGO). These options are new in Visual Studio 2015. Prefer these options to the deprecated **/LTCG:PGINSTRUMENT**, **/PGD** and **/POGOSAFEMODE** options and the **PogoSafeMode**, **VCPROFILE_ALLOC_SCALE** and **VCPROFILE_PATH** environment variables. The profiling information generated by application training is used as input to perform targeted whole-program optimizations during builds. You can set additional options to control various profiling features for performance during app training and builds. The default options specified by **/GENPROFILE** give most accurate results, especially for large, complex multi-threaded apps. The **/FASTGENPROFILE** option uses different defaults for a lower memory footprint and faster performance during training, at the expense of accuracy. +The **`/GENPROFILE`** and **`/FASTGENPROFILE`** options tell the linker to generate the profiling instrumentation file needed to support application training for profile-guided optimization (PGO). These options are new in Visual Studio 2015. Prefer these options to the deprecated **`/LTCG:PGINSTRUMENT`**, **`/PGD`**, and **`/POGOSAFEMODE`** options, and to the **`PogoSafeMode`**, **`VCPROFILE_ALLOC_SCALE`**, and **`VCPROFILE_PATH`** environment variables. The profiling information generated by application training is used as input for targeted whole-program optimizations during builds. You can also set other options to control various profiling features for performance during app training and builds. The default options specified by **`/GENPROFILE`** give the most accurate results, especially for large, complex multi-threaded apps. The **`/FASTGENPROFILE`** option uses different defaults for a lower memory footprint and faster performance during training, at the expense of accuracy. -Profiling information is captured when you run the instrumented app after you build by using **/GENPROFILE** of **/FASTGENPROFILE**. This information is captured when you specify the [/USEPROFILE](useprofile.md) linker option to perform the profiling step and then used to guide the optimized build step. For more information on how to train your app and details on the collected data, see [Profile-Guided Optimizations](../profile-guided-optimizations.md). +Profiling information is captured when you run the instrumented app after you build by using **`/GENPROFILE`** of **`/FASTGENPROFILE`**. This information is captured when you specify the [`/USEPROFILE`](useprofile.md) linker option to do the profiling step and then used to guide the optimized build step. For more information on how to train your app and details on the collected data, see [Profile-guided optimizations](../profile-guided-optimizations.md). -You must also specify **/LTCG** when you specify **/GENPROFILE** or **/FASTGENPROFILE**. +Always specify **`/LTCG`** when you specify **`/GENPROFILE`** or **`/FASTGENPROFILE`**. ### To set this linker option in the Visual Studio development environment @@ -50,7 +59,7 @@ You must also specify **/LTCG** when you specify **/GENPROFILE** or **/FASTGENPR 1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. -1. Enter the **/GENPROFILE** or **/FASTGENPROFILE** options and arguments into the **Additional Options** box. Choose **OK** to save your changes. +1. Enter the **`/GENPROFILE`** or **`/FASTGENPROFILE`** options and arguments into the **Additional Options** box. Choose **`OK`** to save your changes. ### To set this linker option programmatically @@ -58,6 +67,6 @@ You must also specify **/LTCG** when you specify **/GENPROFILE** or **/FASTGENPR ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md)
-[/LTCG (Link-time Code Generation)](ltcg-link-time-code-generation.md)
+[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md)\ +[`/LTCG` (Link-time code generation)](ltcg-link-time-code-generation.md) diff --git a/docs/build/reference/gf-eliminate-duplicate-strings.md b/docs/build/reference/gf-eliminate-duplicate-strings.md index a6a4b0b572..840adad9b6 100644 --- a/docs/build/reference/gf-eliminate-duplicate-strings.md +++ b/docs/build/reference/gf-eliminate-duplicate-strings.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /GF (Eliminate Duplicate Strings)" title: "/GF (Eliminate Duplicate Strings)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCCLCompilerTool.StringPooling", "VC.Project.VCCLWCECompilerTool.StringPooling", "/gf"] @@ -40,9 +41,7 @@ char *t = "This is a character buffer"; 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 **C/C++** folder. - -1. Click the **Code Generation** property page. +1. Select the **Configuration Properties** > **C/C++** > **Code Generation** property page. 1. Modify the **Enable String Pooling** property. diff --git a/docs/build/reference/gh-enable-penter-hook-function.md b/docs/build/reference/gh-enable-penter-hook-function.md index 1045fdd670..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 @@ -30,7 +30,7 @@ This declaration isn't available for 64-bit projects. 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 **Configuration Properties** > **C/C++** > **Command Line** property page. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. 1. Enter the compiler option in the **Additional Options** box. @@ -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/gh-enable-pexit-hook-function.md b/docs/build/reference/gh-enable-pexit-hook-function.md index b09a621f2b..0b8ceeb8a7 100644 --- a/docs/build/reference/gh-enable-pexit-hook-function.md +++ b/docs/build/reference/gh-enable-pexit-hook-function.md @@ -32,7 +32,7 @@ This declaration isn't available for 64-bit projects. 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 **Configuration Properties** > **C/C++** > **Command Line** property page. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. 1. Enter the compiler option in the **Additional Options** box. diff --git a/docs/build/reference/gl-whole-program-optimization.md b/docs/build/reference/gl-whole-program-optimization.md index c18bdf8afa..30e5b20b61 100644 --- a/docs/build/reference/gl-whole-program-optimization.md +++ b/docs/build/reference/gl-whole-program-optimization.md @@ -1,25 +1,23 @@ --- -title: "/GL (Whole Program Optimization)" -ms.date: "11/04/2016" -f1_keywords: ["/gl"] +description: "Learn more about: /GL (Whole program optimization)" +title: "/GL (Whole program optimization)" +ms.date: 03/05/2021 +f1_keywords: ["/GL"] helpviewer_keywords: ["/GL compiler option [C++]", "whole program optimizations and C++ compiler", "-GL compiler option [C++]", "GL compiler option [C++]"] -ms.assetid: 09d51e2d-9728-4bd0-b5dc-3b8284aca1d1 --- -# /GL (Whole Program Optimization) +# `/GL` (Whole program optimization) Enables whole program optimization. ## Syntax -``` -/GL[-] -``` +> **`/GL`**[**`-`**] ## Remarks -Whole program optimization allows the compiler to perform optimizations with information on all modules in the program. Without whole program optimization, optimizations are performed on a per module (compiland) basis. +Whole program optimization allows the compiler to perform optimizations with information on all modules in the program. Without whole program optimization, optimizations are performed on a per-module (compiland) basis. -Whole program optimization is off by default and must be explicitly enabled. However, it is also possible to explicitly disable it with **/GL-**. +Whole program optimization is off by default and must be explicitly enabled. However, it's also possible to explicitly disable it with **`/GL-`**. With information on all modules, the compiler can: @@ -27,31 +25,31 @@ With information on all modules, the compiler can: - Do a better job of tracking modifications to global data, allowing a reduction in the number of loads and stores. -- Do a better job of tracking the possible set of items modified by a pointer dereference, reducing the numbers of loads and stores. +- Track the possible set of items modified by a pointer dereference, reducing the required loads and stores. - Inline a function in a module even when the function is defined in another module. -.obj files produced with **/GL** will not be available to such linker utilities as [EDITBIN](editbin-reference.md) and [DUMPBIN](dumpbin-reference.md). +*`.obj`* files produced with **`/GL`** aren't usable by linker utilities such as [`EDITBIN`](editbin-reference.md) and [`DUMPBIN`](dumpbin-reference.md). -If you compile your program with **/GL** and [/c](c-compile-without-linking.md), you should use the /LTCG linker option to create the output file. +If you compile your program with **`/GL`** and [`/c`](c-compile-without-linking.md), you should use the /LTCG linker option to create the output file. -[/ZI](z7-zi-zi-debug-information-format.md) cannot be used with **/GL** +[`/ZI`](z7-zi-zi-debug-information-format.md) can't be used with **`/GL`** -The format of files produced with **/GL** in the current version may not be readable by subsequent versions of Visual C++. You should not ship a .lib file comprised of .obj files that were produced with **/GL** unless you are willing to ship copies of the .lib file for all versions of Visual C++ you expect your users to use, now and in the future. +The format of files produced with **`/GL`** in the current version often isn't readable by later versions of Visual Studio and the MSVC toolset. Unless you're willing to ship copies of the *`.lib`* file for all versions of Visual Studio you expect your users to use, now and in the future, don't ship a *`.lib`* file made up of *`.obj`* files produced by **`/GL`** . For more information, see [Restrictions on binary compatibility](../../porting/binary-compat-2015-2017.md#restrictions). -.obj files produced with **/GL** and precompiled header files should not be used to build a .lib file unless the .lib file will be linked on the same machine that produced the **/GL** .obj file. Information from the .obj file's precompiled header file will be needed at link time. +*`.obj`* files produced by **`/GL`** and precompiled header files shouldn't be used to build a *`.lib`* file unless the *`.lib`* file is linked on the same machine that produced the **`/GL`** *`.obj`* file. Information from the *`.obj`* file's precompiled header file is needed at link time. -For more information on the optimizations available with and the limitations of whole program optimization, see [/LTCG](ltcg-link-time-code-generation.md). **/GL** also makes profile guided optimization available; see /LTCG. When compiling for profile guided optimizations and if you want function ordering from your profile guided optimizations, you must compile with [/Gy](gy-enable-function-level-linking.md) or a compiler option that implies /Gy. +For more information on the optimizations available with and the limitations of whole program optimization, see [`/LTCG`](ltcg-link-time-code-generation.md). **`/GL`** also makes profile guided optimization available. When compiling for profile guided optimizations and if you want function ordering from your profile guided optimizations, you must compile with [`/Gy`](gy-enable-function-level-linking.md) or a compiler option that implies /Gy. ### To set this linker option in the Visual Studio development environment -1. See [/LTCG (Link-time Code Generation)](ltcg-link-time-code-generation.md) for information on how to specify **/GL** in the development environment. +For more information on how to specify **`/GL`** in the development environment, see [`/LTCG` (Link-time code generation)](ltcg-link-time-code-generation.md) . ### To set this linker option programmatically -1. See . +- 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/gm-enable-minimal-rebuild.md b/docs/build/reference/gm-enable-minimal-rebuild.md index d218df82dd..f0ec29080d 100644 --- a/docs/build/reference/gm-enable-minimal-rebuild.md +++ b/docs/build/reference/gm-enable-minimal-rebuild.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Gm (Enable Minimal Rebuild)" title: "/Gm (Enable Minimal Rebuild)" ms.date: "11/12/2018" f1_keywords: ["VC.Project.VCCLCompilerTool.MinimalRebuild", "/Gm", "VC.Project.VCCLWCECompilerTool.MinimalRebuild"] diff --git a/docs/build/reference/gr-enable-run-time-type-information.md b/docs/build/reference/gr-enable-run-time-type-information.md index d535cefb72..ebdbb8f62f 100644 --- a/docs/build/reference/gr-enable-run-time-type-information.md +++ b/docs/build/reference/gr-enable-run-time-type-information.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /GR (Enable Run-Time Type Information)" title: "/GR (Enable Run-Time Type Information)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCCLWCECompilerTool.RuntimeTypeInfo", "VC.Project.VCCLCompilerTool.RuntimeTypeInfo"] @@ -27,9 +28,7 @@ For more information about run-time type checking, see [Run-Time Type Informatio 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 **C/C++** folder. - -1. Click the **Language** property page. +1. Select the **Configuration Properties** > **C/C++** > **Language** property page. 1. Modify the **Enable Run-Time Type Info** property. diff --git a/docs/build/reference/gs-buffer-security-check.md b/docs/build/reference/gs-buffer-security-check.md index 0aea552920..41fe1b082c 100644 --- a/docs/build/reference/gs-buffer-security-check.md +++ b/docs/build/reference/gs-buffer-security-check.md @@ -1,9 +1,9 @@ --- 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) @@ -28,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. @@ -56,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. @@ -79,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 @@ -98,14 +88,8 @@ 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. In **Solution Explorer**, right-click the project and then click **Properties**. - - For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). - -1. In the **Property Pages** dialog box, click the **C/C++** folder. - -1. Click the **Code Generation** property page. - +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 @@ -141,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 58817bb437..4e1ff0eb87 100644 --- a/docs/build/reference/gs-control-stack-checking-calls.md +++ b/docs/build/reference/gs-control-stack-checking-calls.md @@ -1,43 +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 @@ -53,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 1738481bac..61a24b9f5a 100644 --- a/docs/build/reference/guard-enable-control-flow-guard.md +++ b/docs/build/reference/guard-enable-control-flow-guard.md @@ -1,46 +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 **Configuration Properties**, **C/C++**, **Code Generation**. +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-eh-continuation-metadata.md b/docs/build/reference/guard-enable-eh-continuation-metadata.md index 01090ed5c9..e5fa4b11bc 100644 --- a/docs/build/reference/guard-enable-eh-continuation-metadata.md +++ b/docs/build/reference/guard-enable-eh-continuation-metadata.md @@ -5,7 +5,7 @@ ms.date: "06/03/2020" f1_keywords: ["/guard:ehcont", "VC.Project.VCCLCompilerTool.GuardEHContMetadata"] helpviewer_keywords: ["/guard:ehcont", "/guard:ehcont compiler option"] --- -# /guard:ehcont (Enable EH Continuation Metadata) +# `/guard:ehcont` (Enable EH Continuation Metadata) Enables generation of EH Continuation (EHCONT) metadata by the compiler. @@ -25,7 +25,7 @@ When shadow stacks are available to prevent ROP attacks, attackers move on to us `RtlRestoreContext` and `NtContinue` are used during Structured Exception Handling (SEH) exception unwinding to unwind to the target frame that contains the **`__except`** block. The instruction pointer of the **`__except`** block isn't expected to be on the shadow stack, because it would fail instruction pointer validation. The **`/guard:ehcont`** compiler switch generates an "EH Continuation Table". It contains a sorted list of the RVAs of all valid exception handling continuation targets in the binary. `NtContinue` first checks the shadow stack for the user-supplied instruction pointer, and if the instruction pointer isn't found there, it proceeds to check the EH Continuation Table from the binary that contains the instruction pointer. If the containing binary wasn't compiled with the table, then for compatibility with legacy binaries, `NtContinue` is allowed to continue. It's important to distinguish between legacy binaries that have no EHCONT data, and binaries containing EHCONT data but no table entries. The former allow all addresses inside the binary as valid continuation targets. The latter don't allow any address inside the binary as a valid continuation target. -The **`/guard:ehcont`** option must be passed to both the compiler and linker to generate EH continuation target RVAs for a binary. If your binary is built by using a single `cl` command, the compiler passes the option to the linker. The compiler also passes the [**`/guard:cf`**](guard-enable-control-flow-guard.md) option to the linker. If you compile and link separately, these options must be set on both the compiler and linker commands. +The **`/guard:ehcont`** option must be passed to both the compiler and linker to generate EH continuation target RVAs for a binary. If your binary is built by using a single `cl` command, the compiler passes the option to the linker. The compiler also passes the [`/guard:cf`](guard-enable-control-flow-guard.md) option to the linker. If you compile and link separately, these options must be set on both the compiler and linker commands. You can link code compiled by using **`/guard:ehcont`** to libraries and object files compiled without it. The linker returns a fatal error in any of these scenarios: diff --git a/docs/build/reference/guard-enable-guard-checks.md b/docs/build/reference/guard-enable-guard-checks.md index 586433dcfb..3df932fa31 100644 --- a/docs/build/reference/guard-enable-guard-checks.md +++ b/docs/build/reference/guard-enable-guard-checks.md @@ -1,36 +1,41 @@ --- +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. Expand **Configuration Properties**, **Linker**, **Command Line**. +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/gw-optimize-global-data.md b/docs/build/reference/gw-optimize-global-data.md index 049035843a..678495d166 100644 --- a/docs/build/reference/gw-optimize-global-data.md +++ b/docs/build/reference/gw-optimize-global-data.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Gw (Optimize Global Data)" title: "/Gw (Optimize Global Data)" ms.date: "11/04/2016" f1_keywords: ["/Gw"] @@ -29,9 +30,7 @@ For more information, see [Introducing /Gw Compiler Switch](https://devblogs.mic 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 **C/C++** folder. - -1. Select the **Command Line** property page. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. 1. Modify the **Additional Options** property to include **/Gw** and then choose **OK**. diff --git a/docs/build/reference/gx-enable-exception-handling.md b/docs/build/reference/gx-enable-exception-handling.md index e03161b50a..14400a4d0e 100644 --- a/docs/build/reference/gx-enable-exception-handling.md +++ b/docs/build/reference/gx-enable-exception-handling.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /GX (Enable Exception Handling)" title: "/GX (Enable Exception Handling)" ms.date: "11/19/2019" f1_keywords: ["/gx"] @@ -25,9 +26,9 @@ By default, **/EHsc**, the equivalent of **/GX**, is in effect when you compile 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. In the navigation pane, choose **Configuration Properties**, **C/C++**, **Command Line**. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Type the compiler option in the **Additional Options** box. +1. Enter the compiler option in the **Additional Options** box. ### To set this compiler option programmatically diff --git a/docs/build/reference/gy-enable-function-level-linking.md b/docs/build/reference/gy-enable-function-level-linking.md index f179ed5e0f..7dfd2998f0 100644 --- a/docs/build/reference/gy-enable-function-level-linking.md +++ b/docs/build/reference/gy-enable-function-level-linking.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Gy (Enable Function-Level Linking)" title: "/Gy (Enable Function-Level Linking)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCCLCompilerTool.EnableFunctionLevelLinking", "/gy", "VC.Project.VCCLWCECompilerTool.EnableFunctionLevelLinking"] @@ -32,9 +33,7 @@ Inline functions are always packaged if they are instantiated as calls (which oc 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 **C/C++** folder. - -1. Click the **Code Generation** property page. +1. Select the **Configuration Properties** > **C/C++** > **Code Generation** property page. 1. Modify the **Enable Function-Level Linking** property. diff --git a/docs/build/reference/gz-enable-stack-frame-run-time-error-checking.md b/docs/build/reference/gz-enable-stack-frame-run-time-error-checking.md index 6170fc6f2c..7bef045a1f 100644 --- a/docs/build/reference/gz-enable-stack-frame-run-time-error-checking.md +++ b/docs/build/reference/gz-enable-stack-frame-run-time-error-checking.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /GZ (Enable Stack Frame Run-Time Error Checking)" title: "/GZ (Enable Stack Frame Run-Time Error Checking)" ms.date: "11/04/2016" f1_keywords: ["/gz"] @@ -25,11 +26,9 @@ Performs the same operations as the [/RTC (Run-Time Error Checks)](rtc-run-time- 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 **C/C++** folder. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Click the **Command Line** property page. - -1. Type the compiler option in the **Additional Options** box. +1. Enter the compiler option in the **Additional Options** box. ### To set this compiler option programmatically diff --git a/docs/build/reference/h-restrict-length-of-external-names.md b/docs/build/reference/h-restrict-length-of-external-names.md index 4b1e022471..742d2a1f5c 100644 --- a/docs/build/reference/h-restrict-length-of-external-names.md +++ b/docs/build/reference/h-restrict-length-of-external-names.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /H (Restrict Length of External Names)" title: "/H (Restrict Length of External Names)" ms.date: "09/05/2018" f1_keywords: ["/h"] 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 new file mode 100644 index 0000000000..2f7824ddfb --- /dev/null +++ b/docs/build/reference/headername.md @@ -0,0 +1,75 @@ +--- +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: 11/16/2022 +author: "tylermsft" +ms.author: "twhitney" +f1_keywords: ["/headerName"] +helpviewer_keywords: ["/headerName", "Use header unit IFC"] +--- +# `/headerName` (Build a header unit from the specified header) + +Build the specified header file into a header unit (*`.ifc`* file). + +## Syntax + +> **`/headerName:quote`** `header-filename`\ +> **`/headerName:angle`** `header-filename` + +### Arguments + +*`header-filename`*\ +The name of a header file that the compiler should compile into a header unit (*`.ifc`* file). + +## Remarks + +The **`/headerName:quote`** and **`/headerName:angle`** compiler options are available starting in Visual Studio 2019 version 16.10. + +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-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 example: + +```bash +cl /std:c++latest /exportHeader /headerName:quote m.h /Fom.h.obj +``` + +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 +``` + +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 +``` + +### To set this compiler option in the Visual Studio development environment + +> [!NOTE] +> 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**. 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: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` (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/headers.md b/docs/build/reference/headers.md index 4169fccd2f..edb91ce521 100644 --- a/docs/build/reference/headers.md +++ b/docs/build/reference/headers.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /HEADERS" title: "/HEADERS" ms.date: "11/04/2016" f1_keywords: ["/headers"] diff --git a/docs/build/reference/headerunit.md b/docs/build/reference/headerunit.md new file mode 100644 index 0000000000..6ee2d63554 --- /dev/null +++ b/docs/build/reference/headerunit.md @@ -0,0 +1,72 @@ +--- +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: 5/28/2024 +f1_keywords: ["/headerUnit"] +helpviewer_keywords: ["/headerUnit", "Use header unit IFC"] +author: "tylermsft" +ms.author: "twhitney" +--- +# `/headerUnit` (Use header unit IFC) + +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`* + +### Arguments + +*`header-filename`*\ +During `import header-name;` the compiler resolves `header-name` to a file on disk. Use *`header-filename`* to specify that file. Once matched, the compiler opens the corresponding IFC named by *`ifc-filename`* for import. + +*`ifc-filename`*\ +The name of a file that contains compiled header unit information. To import more than one header unit, add a separate **`/headerUnit`** option for each file. + +## Remarks + +The **`/headerUnit`** compiler option requires [`/std:c++20`](std-specify-language-standard-version.md) or later. + +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 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 by *`ifc-filename`*. + +- **`/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 `. + +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 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 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 like this: + +```CMD +cl ... /std:c++latest /headerUnit C:\utils\util.h=C:\util.h.ifc /headerUnit:quote app.h=app.h.ifc +``` + +### To set this compiler option in the Visual Studio development environment + +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)\ +[`/translateInclude` (Translate include directives into import directives)](translateinclude.md) diff --git a/docs/build/reference/heap-set-heap-size.md b/docs/build/reference/heap-set-heap-size.md index aee0786840..ef1b94e30f 100644 --- a/docs/build/reference/heap-set-heap-size.md +++ b/docs/build/reference/heap-set-heap-size.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /HEAP (Set Heap Size)" title: "/HEAP (Set Heap Size)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCLinkerTool.HeapCommitSize", "VC.Project.VCLinkerTool.HeapReserveSize"] @@ -27,9 +28,7 @@ This functionality is also available via a module definition file with [HEAPSIZE 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 **System** property page. +1. Select the **Configuration Properties** > **Linker** > **System** property page. 1. Modify the **Heap Commit Size** property. diff --git a/docs/build/reference/heapsize.md b/docs/build/reference/heapsize.md index f5944e6568..44a1464afc 100644 --- a/docs/build/reference/heapsize.md +++ b/docs/build/reference/heapsize.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: HEAPSIZE" title: "HEAPSIZE" ms.date: "11/04/2016" f1_keywords: ["HEAPSIZE"] diff --git a/docs/build/reference/help-compiler-command-line-help.md b/docs/build/reference/help-compiler-command-line-help.md index e422165f26..8b03e638c8 100644 --- a/docs/build/reference/help-compiler-command-line-help.md +++ b/docs/build/reference/help-compiler-command-line-help.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /HELP (Compiler Command-Line Help)" title: "/HELP (Compiler Command-Line Help)" ms.date: "11/04/2016" f1_keywords: ["/help"] diff --git a/docs/build/reference/help-files-html-help.md b/docs/build/reference/help-files-html-help.md index 4ae4efe114..e97ee5a668 100644 --- a/docs/build/reference/help-files-html-help.md +++ b/docs/build/reference/help-files-html-help.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Help Files (HTML Help)" title: "Help Files (HTML Help)" ms.date: "11/04/2016" helpviewer_keywords: ["file types [C++], HTML Help files"] diff --git a/docs/build/reference/help-files-winhelp.md b/docs/build/reference/help-files-winhelp.md index 7a8f74e48b..facccac560 100644 --- a/docs/build/reference/help-files-winhelp.md +++ b/docs/build/reference/help-files-winhelp.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Help Files (WinHelp)" title: "Help Files (WinHelp)" ms.date: "11/04/2016" helpviewer_keywords: ["file types [C++], WinHelp files"] diff --git a/docs/build/reference/highentropyva-support-64-bit-aslr.md b/docs/build/reference/highentropyva-support-64-bit-aslr.md index 477573e519..2948f7251e 100644 --- a/docs/build/reference/highentropyva-support-64-bit-aslr.md +++ b/docs/build/reference/highentropyva-support-64-bit-aslr.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /HIGHENTROPYVA (Support 64-Bit ASLR)" title: "/HIGHENTROPYVA (Support 64-Bit ASLR)" ms.date: "06/12/2018" ms.assetid: fe35f9f7-d28e-4694-9aeb-a79db06168e0 @@ -33,4 +34,4 @@ For **`/HIGHENTROPYVA`** to have an effect at load time, [`/DYNAMICBASE`](dynami - [MSVC linker options](linker-options.md) - [`/DYNAMICBASE`](dynamicbase-use-address-space-layout-randomization.md) - [`/LARGEADDRESSAWARE`](largeaddressaware-handle-large-addresses.md) -- [Windows ISV Software Security Defenses](https://docs.microsoft.com/previous-versions/bb430720(v=msdn.10)) +- [Windows ISV Software Security Defenses](/previous-versions/bb430720(v=msdn.10)) diff --git a/docs/build/reference/highentropyva.md b/docs/build/reference/highentropyva.md index 4c4e97ec79..d7156aed21 100644 --- a/docs/build/reference/highentropyva.md +++ b/docs/build/reference/highentropyva.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /HIGHENTROPYVA" title: "/HIGHENTROPYVA" ms.date: "06/12/2018" f1_keywords: ["/HIGHENTROPYVA"] @@ -24,4 +25,4 @@ By default, the linker enables **`/HIGHENTROPYVA`** for 64-bit executable images [EDITBIN Options](editbin-options.md)\ [`/DYNAMICBASE`](dynamicbase.md)\ [`/LARGEADDRESSAWARE`](largeaddressaware.md)\ -[Windows ISV Software Security Defenses](https://docs.microsoft.com/previous-versions/bb430720(v=msdn.10)) +[Windows ISV Software Security Defenses](/previous-versions/bb430720(v=msdn.10)) diff --git a/docs/build/reference/hint-files.md b/docs/build/reference/hint-files.md index 784dd225ce..b292dfffa3 100644 --- a/docs/build/reference/hint-files.md +++ b/docs/build/reference/hint-files.md @@ -1,9 +1,9 @@ --- title: "Hint Files" -ms.date: "02/26/2019" +description: "Learn more about: Hint Files" +ms.date: 02/26/2019 f1_keywords: ["cpp.hint", "vc.hint.file"] helpviewer_keywords: ["stop file", "cpp.hint", "hint file", "cpp.stop", "Class View, hint file"] -ms.assetid: 17194f66-cf62-4523-abec-77db0675ab65 --- # Hint Files @@ -132,7 +132,7 @@ For a depiction of how hints are gathered, see the [Example](#example) section. You create and delete hints by using the same syntax as the preprocessor directives to create and delete macros. In fact, the parsing system uses the C/C++ preprocessor to evaluate the hints. For more information about the preprocessor directives, see [#define Directive (C/C++)](../../preprocessor/hash-define-directive-c-cpp.md) and [#undef Directive (C/C++)](../../preprocessor/hash-undef-directive-c-cpp.md). -The only unusual syntax elements are the `@<`, `@=`, and `@>` replacement strings. These hint-file specific replacement strings are only used in *map* macros. A map is a set of macros that relate data, functions, or events to other data, functions, or event handlers. For example, `MFC` uses maps to create [message maps](../../mfc/reference/message-maps-mfc.md), and `ATL` uses maps to create [object maps](../../atl/reference/object-map-macros.md). The hint-file specific replacement strings mark the starting, intermediate, and ending elements of a map. Only the name of a map macro is significant. Therefore, each replacement string intentionally hides the implementation of the macro. +The only unusual syntax elements are the `@<`, `@=`, and `@>` replacement strings. These hint-file specific replacement strings are only used in *map* macros. A map is a set of macros that relate data, functions, or events to other data, functions, or event handlers. For example, MFC uses maps to create [message maps](../../mfc/reference/message-maps-mfc.md), and ATL uses maps to create [object maps](../../atl/reference/object-map-macros.md). The hint-file specific replacement strings mark the starting, intermediate, and ending elements of a map. Only the name of a map macro is significant. Therefore, each replacement string intentionally hides the implementation of the macro. Hints use this syntax: @@ -154,7 +154,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/hlsl-property-pages.md b/docs/build/reference/hlsl-property-pages.md index 5b9aa56ba4..ab667c3e2e 100644 --- a/docs/build/reference/hlsl-property-pages.md +++ b/docs/build/reference/hlsl-property-pages.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: HLSL Compiler Property Pages" title: "HLSL Property Pages" ms.date: "07/24/2019" ms.assetid: 0c65f5ec-a2a5-4f5b-8d4c-fa57113a5a1d @@ -26,7 +27,7 @@ f1_keywords: --- # HLSL Compiler Property Pages -You can use the HLSL compiler (fxc.exe) property pages to configure how individual HLSL shader files are built. You can also specify command-line arguments to the HLSL compiler by using the **Additional Options** property of the **Command Line** property page; this includes arguments that can't be configured by using other properties of the HLSL property pages. For information about the HLSL compiler, see [Effect-Compiler Tool](https://go.microsoft.com/fwlink/p/?LinkID=258285&clcid=0x409) +You can use the HLSL compiler (fxc.exe) property pages to configure how individual HLSL shader files are built. You can also specify command-line arguments to the HLSL compiler by using the **Additional Options** property of the **Command Line** property page; this includes arguments that can't be configured by using other properties of the HLSL property pages. For information about the HLSL compiler, see [Effect-Compiler Tool](/windows/win32/direct3dtools/fxc) ## HLSL General Property Page @@ -140,4 +141,4 @@ Specifies file name for assembly code listing file [C++ project property page reference](property-pages-visual-cpp.md)
[Command Line Property Pages](command-line-property-pages.md)
-[Compiling Shaders](https://go.microsoft.com/fwlink/p/?LinkID=258284&clcid=0x409) +[Compiling Shaders](/windows/win32/direct3dhlsl/dx-graphics-hlsl-part1) diff --git a/docs/build/reference/homeparams-copy-register-parameters-to-stack.md b/docs/build/reference/homeparams-copy-register-parameters-to-stack.md index accf32a54d..bb498d1bfe 100644 --- a/docs/build/reference/homeparams-copy-register-parameters-to-stack.md +++ b/docs/build/reference/homeparams-copy-register-parameters-to-stack.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /homeparams (Copy Register Parameters to Stack)" title: "/homeparams (Copy Register Parameters to Stack)" ms.date: "12/17/2018" f1_keywords: ["/homeparams"] @@ -27,7 +28,7 @@ In debug builds, the stack is always populated with parameters passed in registe 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 **Configuration Properties** > **C/C++** > **Command Line** property page. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. 1. Enter the compiler option in the **Additional Options** box. diff --git a/docs/build/reference/hotpatch-create-hotpatchable-image.md b/docs/build/reference/hotpatch-create-hotpatchable-image.md index 572af8065e..ecd2b6467e 100644 --- a/docs/build/reference/hotpatch-create-hotpatchable-image.md +++ b/docs/build/reference/hotpatch-create-hotpatchable-image.md @@ -1,6 +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 @@ -17,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**. @@ -27,9 +28,7 @@ Because instructions are always two bytes or larger on the ARM architecture, and 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 **C/C++** folder. - -1. Select the **Command Line** property page. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. 1. Add the compiler option to the **Additional Options** box. diff --git a/docs/build/reference/how-bscmake-builds-a-dot-bsc-file.md b/docs/build/reference/how-bscmake-builds-a-dot-bsc-file.md index 66d610c1e2..df888c90e3 100644 --- a/docs/build/reference/how-bscmake-builds-a-dot-bsc-file.md +++ b/docs/build/reference/how-bscmake-builds-a-dot-bsc-file.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: How BSCMAKE Builds a .Bsc File" title: "How BSCMAKE Builds a .Bsc File" ms.date: "11/04/2016" helpviewer_keywords: ["browse information files (.bsc), building"] diff --git a/docs/build/reference/how-to-set-lib-exe-options-in-the-visual-studio-development-environment.md b/docs/build/reference/how-to-set-lib-exe-options-in-the-visual-studio-development-environment.md index be1c0f0e2d..c5d378b776 100644 --- a/docs/build/reference/how-to-set-lib-exe-options-in-the-visual-studio-development-environment.md +++ b/docs/build/reference/how-to-set-lib-exe-options-in-the-visual-studio-development-environment.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: How to: Set LIB.EXE Options in the Visual Studio Development Environment" title: "How to: Set LIB.EXE Options in the Visual Studio Development Environment" ms.date: "11/04/2016" helpviewer_keywords: ["lib.exe options, setting in the Visual Studio Development Environment"] diff --git a/docs/build/reference/i-additional-include-directories.md b/docs/build/reference/i-additional-include-directories.md index a6a8c4ff67..c885e46247 100644 --- a/docs/build/reference/i-additional-include-directories.md +++ b/docs/build/reference/i-additional-include-directories.md @@ -1,36 +1,39 @@ --- +description: "Learn more about: /I (Additional include directories)" title: "/I (Additional include directories)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCCLWCECompilerTool.AdditionalIncludeDirectories", "VC.Project.VCCLCompilerTool.AdditionalIncludeDirectories", "/I", "VC.Project.VCNMakeTool.IncludeSearchPath"] helpviewer_keywords: ["/I compiler option [C++]", "Additional Include Directories compiler option", "I compiler option [C++]", "-I compiler option [C++]", "set include directories", "include directories, compiler option [C++]"] ms.assetid: 3e9add2a-5ed8-4d15-ad79-5b411e313a49 --- -# /I (Additional include directories) +# `/I` (Additional include directories) Adds a directory to the list of directories searched for include files. ## Syntax -> **/I**[ ]*directory* +> **`/I`** *directory* ### Arguments -*directory*
-The directory to be added to the list of directories searched for include files. +*directory*\ +The directory to add to the list of directories searched for include files. The space between `/I` and *directory* is optional. Directories that include spaces must be enclosed in double quotes. A directory may be an absolute path or a relative path. ## Remarks To add more than one directory, use this option more than once. Directories are searched only until the specified include file is found. -You can use this option with the ([/X (Ignore Standard Include Paths)](x-ignore-standard-include-paths.md)) option. +You can use this option on the same command line as the ([`/X` (Ignore standard include paths)](x-ignore-standard-include-paths.md)) option. + +A [`#include` directive](../../preprocessor/hash-include-directive-c-cpp.md) can be specified in double-quote (or local-first) form, for example, `#include "local.h"`. Or, it can be specified in angle-bracket (or include-path-first) form, for example, `#include `. The compiler searches directories in the following order: -1. If specified using a [#include directive](../../preprocessor/hash-include-directive-c-cpp.md) in double-quote form, it first searches local directories. The search begins in the same directory as the file that contains the **#include** statement. If this fails to find the file, it searches in the directories of the currently opened include files, in the reverse order in which they were opened. The search begins in the directory of the parent include file and continues upward through the directories of any grandparent include files. +1. If the **`#include`** directive is specified using double-quote form, it first searches local directories. The search begins in the same directory as the file that contains the **`#include`** directive. If it fails to find the file, it searches next in the directories of the currently opened include files, in the reverse order in which they were opened. The search begins in the directory of the parent include file and continues upward through the directories of any grandparent include files. -1. If specified using a **#include** directive in angle bracket form, or if the local directory search has failed, it searches directories specified by using the **/I** option, in the order that CL encounters them on the command line. +1. If the **`#include`** directive is specified in angle-bracket form, or if the local directory search has failed, it searches directories specified by using the **`/I`** option, in the order they're specified on the command line. -1. Directories specified in the **INCLUDE** environment variable. +1. Directories specified in the **`INCLUDE`** environment variable. ### To set this compiler option in the Visual Studio development environment @@ -38,7 +41,7 @@ The compiler searches directories in the following order: 1. Select the **Configuration Properties** > **C/C++** > **General** property page. -1. Modify the **Additional Include Directories** property. +1. Modify the **Additional Include Directories** property. You can specify more than one directory at a time in this property. Directories must be separated by a semicolon (**`;`**). ### To set this compiler option programmatically @@ -46,10 +49,10 @@ The compiler searches directories in the following order: ## Example -The following command looks for the include files requested by MAIN.c in the following order: First, if specified by using double-quotes, local files are searched. Next, search continues in the \INCLUDE directory, then in the \MY\INCLUDE directory, and finally in the directories assigned to the INCLUDE environment variable. +The following command looks for the include files requested by *`main.c`* in the following order: First, if specified by using double-quotes, local files are searched. Next, search continues in the *`\include`* directory, then in the *`\my\include`* directory, and finally in the directories assigned to the **`INCLUDE`** environment variable, in left to right order. -``` -CL /I \INCLUDE /I\MY\INCLUDE MAIN.C +```cmd +CL /I \include /I\my\include main.c ``` ## See also diff --git a/docs/build/reference/idlout-name-midl-output-files.md b/docs/build/reference/idlout-name-midl-output-files.md index 8409f59f13..3c18293306 100644 --- a/docs/build/reference/idlout-name-midl-output-files.md +++ b/docs/build/reference/idlout-name-midl-output-files.md @@ -1,52 +1,45 @@ --- 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/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. Click the **Linker** folder. - -1. Click the **Embedded IDL** property page. - +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 @@ -55,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)
-[Building an Attributed Program](../../windows/building-an-attributed-program.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/ignore-ignore-specific-warnings.md b/docs/build/reference/ignore-ignore-specific-warnings.md index 362658aaea..e7439cde9f 100644 --- a/docs/build/reference/ignore-ignore-specific-warnings.md +++ b/docs/build/reference/ignore-ignore-specific-warnings.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /IGNORE (Ignore Specific Warnings)" title: "/IGNORE (Ignore Specific Warnings)" ms.date: "11/04/2016" f1_keywords: ["/OVERWRITE"] @@ -22,7 +23,7 @@ By default, LINK reports all warnings. Specify **/IGNORE:**`warning` to tell the The linker does not allow some warnings to be ignored. This table lists the warnings that are not suppressed by **/IGNORE**: -|Linker Warning|| +| Linker Warning | Message | |--------------------|-| |LNK4017|`keyword` statement not supported for the target platform; ignored| |[LNK4044](../../error-messages/tool-errors/linker-tools-warning-lnk4044.md)|unrecognized option '`option`'; ignored| @@ -48,7 +49,7 @@ In general, linker warnings that can't be ignored represent build failures, comm 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. In the **Linker** folder, select the **Command Line** property page. +1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. 1. Modify the **Additional Options** property. 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 40bda9c8b8..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,11 +1,12 @@ --- -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 @@ -13,15 +14,13 @@ ms.assetid: 29514098-6a1c-4317-af2f-1dc268972780 ## Remarks -The /IGNOREIDL option specifies that any [IDL attributes](../../windows/idl-attributes.md) in source code should not be processed into an .idl file. +The /IGNOREIDL option specifies that any [IDL attributes](../../windows/attributes/idl-attributes.md) in source code should not be processed into an .idl 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 **Embedded IDL** property page. +1. Select the **Configuration Properties** > **Linker** > **Embedded IDL** property page. 1. Modify the **Ignore Embedded IDL** property. @@ -36,4 +35,4 @@ The /IGNOREIDL option specifies that any [IDL attributes](../../windows/idl-attr [/IDLOUT (Name MIDL Output Files)](idlout-name-midl-output-files.md)
[/TLBOUT (Name .TLB File)](tlbout-name-dot-tlb-file.md)
[/MIDL (Specify MIDL Command Line Options)](midl-specify-midl-command-line-options.md)
-[Building an Attributed Program](../../windows/building-an-attributed-program.md) +[Building an Attributed Program](../../windows/attributes/cpp-attributes-com-net.md) 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 71af50f070..93ad9b6efb 100644 --- a/docs/build/reference/implib-name-import-library.md +++ b/docs/build/reference/implib-name-import-library.md @@ -1,39 +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. Click the **Linker** folder. - -1. Click the **Advanced** property page. - +1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. 1. Modify the **Import Library** property. ### To set this linker option programmatically @@ -42,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/imports-dumpbin.md b/docs/build/reference/imports-dumpbin.md index 2e7b106156..5dd39ae8e6 100644 --- a/docs/build/reference/imports-dumpbin.md +++ b/docs/build/reference/imports-dumpbin.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /IMPORTS (DUMPBIN)" title: "/IMPORTS (DUMPBIN)" ms.date: "11/04/2016" f1_keywords: ["/imports"] diff --git a/docs/build/reference/include-force-symbol-references.md b/docs/build/reference/include-force-symbol-references.md index 233a930cbb..701c6726b1 100644 --- a/docs/build/reference/include-force-symbol-references.md +++ b/docs/build/reference/include-force-symbol-references.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /INCLUDE (Force Symbol References)" title: "/INCLUDE (Force Symbol References)" ms.date: "11/04/2016" f1_keywords: ["/include", "VC.Project.VCLinkerTool.ForceSymbolReferences"] @@ -30,9 +31,7 @@ Specifying a symbol with this option overrides the removal of that symbol by [/O 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 **Input** property page. +1. Select the **Configuration Properties** > **Linker** > **Input** property page. 1. Modify the **Force Symbol References** property. diff --git a/docs/build/reference/include-visual-cpp.md b/docs/build/reference/include-visual-cpp.md index dfe504945a..532ad182b6 100644 --- a/docs/build/reference/include-visual-cpp.md +++ b/docs/build/reference/include-visual-cpp.md @@ -1,43 +1,44 @@ --- -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 @@ -57,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 @@ -102,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 9513f55631..581ba2ccd8 100644 --- a/docs/build/reference/incremental-link-incrementally.md +++ b/docs/build/reference/incremental-link-incrementally.md @@ -1,23 +1,26 @@ --- -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. @@ -26,43 +29,43 @@ 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 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. Select the **General** property page. +1. Select the **Configuration Properties** > **Linker** > **General** property page. 1. Modify the **Enable Incremental Linking** property. @@ -72,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/inferasanlibs.md b/docs/build/reference/inferasanlibs.md new file mode 100644 index 0000000000..5c952da5ee --- /dev/null +++ b/docs/build/reference/inferasanlibs.md @@ -0,0 +1,45 @@ +--- +description: "Learn more about the /INFERASANLIBS (Use inferred sanitizer libs) linker option" +title: "/INFERASANLIBS (Use inferred sanitizer libs)" +ms.date: 03/01/2021 +f1_keywords: ["/INFERASANLIBS", "/INFERASANLIBS:NO"] +helpviewer_keywords: ["/INFERASANLIBS [C++]", "address sanitizer [C++] linker option"] +--- +# `/INFERASANLIBS` (Use inferred sanitizer libs) + +Use the **`/INFERASANLIBS`** linker option to enable or disable linking to the default AddressSanitizer libraries. As of Visual Studio 2019 16.9, the only supported sanitizer is [AddressSanitizer](../../sanitizers/asan.md). + +## Syntax + +> **`/INFERASANLIBS`**\[**`:NO`**] + +## Remarks + +The **`/INFERASANLIBS`** linker option enables the default [AddressSanitizer](../../sanitizers/asan.md) libraries. This option is enabled by default. + +The **`/INFERASANLIBS`** and **`/INFERASANLIBS:NO`** linker options offer support for advanced users. For more information, see [AddressSanitizer build and language reference](../../sanitizers/asan-building.md). + +The **`/INFERASANLIBS`** option is available beginning in Visual Studio 2019 version 16.9. + +### To set the **`/INFERASANLIBS`** linker option in the Visual Studio development environment + +1. Open your 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 enable default libraries, enter **/INFERASANLIBS** in the edit box. To disable default libraries, enter **/INFERASANLIBS:NO** instead. + +1. 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)\ +[`/fsanitize` (Enable sanitizers)](./fsanitize.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/inference-rules.md b/docs/build/reference/inference-rules.md index e011843dd1..ebb37cb557 100644 --- a/docs/build/reference/inference-rules.md +++ b/docs/build/reference/inference-rules.md @@ -1,27 +1,184 @@ --- -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 68df1eeb20..0000000000 --- a/docs/build/reference/inferred-dependents-and-rules.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -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 f2c698436b..b18211ffdc 100644 --- a/docs/build/reference/inline-files-in-a-makefile.md +++ b/docs/build/reference/inline-files-in-a-makefile.md @@ -1,22 +1,58 @@ --- -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 2e4bce4fe4..2e154fe960 100644 --- a/docs/build/reference/integritycheck-require-signature-check.md +++ b/docs/build/reference/integritycheck-require-signature-check.md @@ -1,38 +1,38 @@ --- -title: "/INTEGRITYCHECK (Require Signature Check)" -ms.date: "11/04/2016" -ms.assetid: 9e738825-2c98-40cd-8ad2-5d0d9c14893e +description: "Learn more about: /INTEGRITYCHECK (Require signature check)" +title: "/INTEGRITYCHECK (Require signature check)" +ms.date: 08/29/2023 --- -# /INTEGRITYCHECK (Require Signature Check) +# `/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. +By default, **`/INTEGRITYCHECK`** is off. -The **/INTEGRITYCHECK** option sets—in the PE header of the DLL file or executable file—a flag for 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, and is recommended for all device drivers on Windows Vista, Windows 7, Windows 8, Windows Server 2008, and Windows Server 2012. 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). 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 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. Expand the **Configuration Properties** node. - -1. Expand the **Linker** node. +1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. -1. Select the **Command Line** property page. +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. In **Additional Options**, enter `/INTEGRITYCHECK` or `/INTEGRITYCHECK:NO`. +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/integritycheck.md b/docs/build/reference/integritycheck.md index 0b26420eed..6abe974378 100644 --- a/docs/build/reference/integritycheck.md +++ b/docs/build/reference/integritycheck.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /INTEGRITYCHECK" title: "/INTEGRITYCHECK" ms.date: "12/28/2017" f1_keywords: ["/INTEGRITYCHECK"] 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/j-default-char-type-is-unsigned.md b/docs/build/reference/j-default-char-type-is-unsigned.md index 9231cf0f06..71b378fba7 100644 --- a/docs/build/reference/j-default-char-type-is-unsigned.md +++ b/docs/build/reference/j-default-char-type-is-unsigned.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /J (Default char Type Is unsigned)" title: "/J (Default char Type Is unsigned)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCCLCompilerTool.DefaultCharIsUnsigned", "VC.Project.VCCLWCECompilerTool.DefaultCharIsUnsigned", "/j"] @@ -28,11 +29,11 @@ ANSI C and C++ do not require a specific implementation of the **`char`** type. ### To set this compiler option in the Visual Studio development environment -1. In **Solution Explorer**, open the shortcut menu for the project and then choose **Properties**. +1. Open your project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). -1. In the project **Property Pages** dialog box, in the left pane under **Configuration Properties**, expand **C/C++** and then select **Command Line**. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. In the **Additional Options** pane, specify the **/J** compiler option. +1. In **Additional Options**, enter the **/J** compiler option. ### To set this compiler option programmatically diff --git a/docs/build/reference/jmc.md b/docs/build/reference/jmc.md index a519ebc89c..c78e3b3eb1 100644 --- a/docs/build/reference/jmc.md +++ b/docs/build/reference/jmc.md @@ -1,24 +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/). @@ -36,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/kernel-create-kernel-mode-binary.md b/docs/build/reference/kernel-create-kernel-mode-binary.md index a7ae266c8d..9427cc443c 100644 --- a/docs/build/reference/kernel-create-kernel-mode-binary.md +++ b/docs/build/reference/kernel-create-kernel-mode-binary.md @@ -1,46 +1,37 @@ --- -title: "/kernel (Create Kernel Mode Binary)" -ms.date: "11/04/2016" +title: "/kernel (Create kernel mode binary)" +description: "The Microsoft C/C++ compiler /kernel option builds and links projects for kernel-mode execution." +ms.date: 09/28/2020 f1_keywords: ["/kernel", "/kernel-"] ms.assetid: 6d7fdff0-c3d1-4b78-9367-4da588ce8b05 --- -# /kernel (Create Kernel Mode Binary) +# /kernel (Create kernel mode binary) -Creates a binary that can be executed in the Windows kernel. +Creates a binary that can be executed in the Windows kernel. The code in the current project gets compiled and linked by using a simplified set of C++ language features that are specific to code that runs in kernel mode. ## Syntax -``` -/kernel[-] -``` - -## Arguments - -**/kernel**
-The code in the current project is compiled and linked by using a set of C++ language rules that are specific to code that will run in kernel mode. - -**/kernel-**
-The code in the current project is compiled and linked without using the C++ language rules that are specific to code that will run in kernel mode. +> **`/kernel`** ## Remarks -There is no `#pragma` equivalent to control this option. +Specifying the **`/kernel`** option tells the compiler and linker to arbitrate which language features are permissible in kernel mode and to make sure that you have sufficient expressive power to avoid runtime instability that is unique to kernel mode C++. It's done by prohibiting the use of C++ language features that are disruptive in kernel mode. The compiler produces warnings for C++ language features that are potentially disruptive but can't be disabled. -Specifying the **/kernel** option tells the compiler and linker to arbitrate which language features are permissible in kernel mode and to make sure that you have sufficient expressive power to avoid runtime instability that is unique to kernel mode C++. This is accomplished by prohibiting the use of C++ language features that are disruptive in kernel mode and by providing warnings for C++ language features that are potentially disruptive but cannot be disabled. +The **`/kernel`** option applies to both the compiler and linker phases of a build and is set at the project level. Pass the **`/kernel`** switch to indicate to the compiler that the resulting binary, after linking, should be loaded into the Windows kernel. The compiler will narrow the spectrum of C++ language features to a subset that is compatible with the kernel. -The **/kernel** option applies to both the compiler and linker phases of a build and is set at the project level. Pass the **/kernel** switch to indicate to the compiler that the resulting binary, after linking, should be loaded into the Windows kernel. The compiler will narrow the spectrum of C++ language features to a subset that is compatible with the kernel. +The following table lists changes in compiler behavior when **`/kernel`** is specified. -The following table lists changes in compiler behavior when **/kernel** is specified. +| Behavior type | **`/kernel`** behavior | +|--|--| +| C++ exception handling | Disabled. All instances of the **`throw`** and **`try`** keywords emit a compiler error (except for the exception specification `throw()`). No **`/EH`** options are compatible with **`/kernel`**, except for **`/EH-`**. | +| RTTI | Disabled. All instances of the **`dynamic_cast`** and **`typeid`** keywords emit a compiler error, unless **`dynamic_cast`** is used statically. | +| `new` and `delete` | You must explicitly define the `new()` or `delete()` operator. The compiler and runtime don't supply a default definition. | -|Behavior Type|**/kernel** Behavior| -|-------------------|---------------------------| -|C++ Exception Handling|Disabled. All instances of the **`throw`** and **`try`** keywords emit a compiler error (except for the exception specification `throw()`). No **/EH** options are compatible with **/kernel**, except for **/EH-**.| -|RTTI|Disabled. All instances of the **`dynamic_cast`** and **`typeid`** keywords emit a compiler error, unless **`dynamic_cast`** is used statically.| -|`new` and `delete`|You must explicitly define the `new()` or `delete()` operator; neither the compiler nor the runtime will supply a default definition.| +Custom calling conventions, the [`/GS`](gs-buffer-security-check.md) build option, and all optimizations are permitted when you use the **`/kernel`** option. Inlining is largely not affected by **`/kernel`**, with the same semantics honored by the compiler. If you want to make sure that the **`__forceinline`** inlining qualifier is honored, you must make sure that warning [C4714](../../error-messages/compiler-warnings/compiler-warning-level-4-c4714.md) is enabled so that you know when a particular **`__forceinline`** function isn't inlined. -Custom calling conventions, the [/GS](gs-buffer-security-check.md) build option, and all optimizations are permitted when you use the **/kernel** option. Inlining is largely not affected by **/kernel**, with the same semantics honored by the compiler. If you want to make sure that the **`__forceinline`** inlining qualifier is honored, you must make sure that warning [C4714](../../error-messages/compiler-warnings/compiler-warning-level-4-c4714.md) is enabled so that you know when a particular **`__forceinline`** function is not inlined. +There's no `#pragma` equivalent to control this option. -When the compiler is passed the **/kernel** switch, it predefines a preprocessor macro that's named `_KERNEL_MODE` and has the value **1**. You can use this to conditionally compile code based on whether the execution environment is in user mode or kernel mode. For example, the following code specifies that the class should be in a non-pageable memory segment when it is compiled for kernel mode execution. +When the compiler is passed the **`/kernel`** switch, it predefines a preprocessor macro that's named `_KERNEL_MODE` and has the value **1**. You can use this macro to conditionally compile code based on whether the execution environment is in user mode or kernel mode. For example, the following code specifies that the `MyNonPagedClass` class should be in a non-pageable memory segment when it's compiled for kernel mode execution. ```cpp #ifdef _KERNEL_MODE @@ -55,40 +46,38 @@ class NONPAGESECTION MyNonPagedClass }; ``` -Some the following combinations of target architecture and the **/arch** option produce an error when they are used with **/kernel**: +Some of the following combinations of target architecture and the **`/arch`** option produce an error when they're used with **`/kernel`**: -- **/arch:{SSE|SSE2|AVX}** are not supported on x86. Only **/arch:IA32** is supported with **/kernel** on x86. +- **`/arch:SSE`**, **`/arch:SSE2`**, **`/arch:AVX`**, **`/arch:AVX2`**, and **`/arch:AVX512`** aren't supported on x86. Only **`/arch:IA32`** is supported with **`/kernel`** on x86. -- **/arch:AVX** is not supported with **/kernel** on x64. +- **`/arch:AVX`**, **`/arch:AVX2`**, and **`/arch:AVX512`** aren't supported with **`/kernel`** on x64. -Building with **/kernel** also passes **/kernel** to the linker. Her's how this affects linker behavior: +Building with **`/kernel`** also passes **`/kernel`** to the linker. Here's how the option affects linker behavior: -- Incremental linking is disabled. If you add **/incremental** to the command line, the linker emits this fatal error: +- Incremental linking is disabled. If you add **`/incremental`** to the command line, the linker emits this fatal error: - **LINK : fatal error LNK1295: '/INCREMENTAL' not compatible with '/KERNEL' specification; link without '/INCREMENTAL'** + **fatal error LNK1295: '/INCREMENTAL' not compatible with '/KERNEL' specification; link without '/INCREMENTAL'** -- The linker inspects each object file (or any included archive member from static libraries) to see whether it could have been compiled by using the **/kernel** option but was not. If any instances meet this criterion, the linker still successfully links but might issue a warning, as shown in the following table. +- The linker inspects each object file (or any included archive member from static libraries) to see whether it could have been compiled by using the **`/kernel`** option but wasn't. If any instances meet this criterion, the linker still successfully links but might issue a warning, as shown in the following table. - ||**/kernel** obj|**/kernel-** obj, MASM obj, or cvtresed|Mix of **/kernel** and **/kernel-** objs| - |-|----------------------|-----------------------------------------------|-------------------------------------------------| - |**link /kernel**|Yes|Yes|Yes with warning LNK4257| - |**link**|Yes|Yes|Yes| + | Command | **`/kernel`** obj | non-**`/kernel`** obj, MASM obj, or cvtres obj | Mix of **`/kernel`** and non-**`/kernel`** objs | + |--|--|--|--| + | **`link /kernel`** | Yes | Yes | Yes with warning LNK4257 | + | **`link`** | Yes | Yes | Yes | - **LNK4257 linking object not compiled with /KERNEL ; image may not run** + **LNK4257 linking object not compiled with /KERNEL; image may not run** -The **/kernel** option and the **/driver** option operate independently and neither affects the other. +The **`/kernel`** option and the **`/driver`** option operate independently. They have no effect on each other. ### To set the /kernel 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 **C/C++** folder. - -1. Select the **Command Line** property page. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. In the **Additional options** box, add `/kernel` or `/kernel-`. +1. In the **Additional options** box, add *`/kernel`*. Choose **OK** or **Apply** to save your changes. ## 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/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 8737931083..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 @@ -1,4 +1,5 @@ --- +description: "Learn more about: /KEYCONTAINER (Specify a Key Container to Sign an Assembly)" title: "/KEYCONTAINER (Specify a Key Container to Sign an Assembly)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCLinkerTool.KeyContainer", "/keycontainer"] @@ -22,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: @@ -40,11 +41,9 @@ Other linker options that affect assembly generation are: 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. Select the **Configuration Properties** > **Linker** > **Command Line** property page. -1. Click the **Command Line** property page. - -1. Type the option into the **Additional Options** box. +1. Enter the option into the **Additional Options** box. ### To set this linker option programmatically 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 a063d0ea63..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,11 +1,11 @@ --- 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 @@ -13,44 +13,34 @@ 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. 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 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 does not 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. -Note that a key file might contain only the public key. - -See [Creating and Using Strong-Named Assemblies](/dotnet/framework/app-domains/create-and-use-strong-named-assemblies) for more information on signing an assembly. +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. Click the **Linker** folder. - -1. Click the **Command Line** property page. - -1. Type the option into the **Additional Options** box. +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 @@ -58,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 56a45991d0..4d3910054e 100644 --- a/docs/build/reference/largeaddressaware-handle-large-addresses.md +++ b/docs/build/reference/largeaddressaware-handle-large-addresses.md @@ -1,9 +1,9 @@ --- 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) @@ -13,17 +13,17 @@ 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 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 **System** property page. +1. Select the **Configuration Properties** > **Linker** > **System** property page. 1. Modify the **Enable Large Addresses** property. @@ -33,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/largeaddressaware.md b/docs/build/reference/largeaddressaware.md index 9bfa03e144..9cbe6ea6a8 100644 --- a/docs/build/reference/largeaddressaware.md +++ b/docs/build/reference/largeaddressaware.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /LARGEADDRESSAWARE" title: "/LARGEADDRESSAWARE" ms.date: "11/04/2016" f1_keywords: ["/largeaddressaware_editbin"] diff --git a/docs/build/reference/lib-input-files.md b/docs/build/reference/lib-input-files.md index 605d2cb6a6..7d710aba08 100644 --- a/docs/build/reference/lib-input-files.md +++ b/docs/build/reference/lib-input-files.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: LIB Input Files" title: "LIB Input Files" ms.date: "11/04/2016" helpviewer_keywords: ["input files, LIB"] diff --git a/docs/build/reference/lib-output-files.md b/docs/build/reference/lib-output-files.md index c4e4a536fd..b17e7201bc 100644 --- a/docs/build/reference/lib-output-files.md +++ b/docs/build/reference/lib-output-files.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: LIB Output Files" title: "LIB Output Files" ms.date: "11/04/2016" helpviewer_keywords: ["output files, LIB"] diff --git a/docs/build/reference/lib-reference.md b/docs/build/reference/lib-reference.md index cfa58dad61..7310ee1235 100644 --- a/docs/build/reference/lib-reference.md +++ b/docs/build/reference/lib-reference.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: LIB Reference" title: "LIB Reference" ms.date: "11/04/2016" f1_keywords: ["Lib"] diff --git a/docs/build/reference/libpath-additional-libpath.md b/docs/build/reference/libpath-additional-libpath.md index 8c43cec687..64cfdd3f94 100644 --- a/docs/build/reference/libpath-additional-libpath.md +++ b/docs/build/reference/libpath-additional-libpath.md @@ -1,33 +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. Click the **Linker** folder. - -1. Click the **General** property page. - +1. Select the **Configuration Properties** > **Linker** > **General** property page. 1. Modify the **Additional Library Directories** property. ### To set this linker option programmatically @@ -36,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/library.md b/docs/build/reference/library.md index 7b139fb69f..449d8a1795 100644 --- a/docs/build/reference/library.md +++ b/docs/build/reference/library.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: LIBRARY" title: "LIBRARY" ms.date: "11/04/2016" f1_keywords: ["LIBRARY"] diff --git a/docs/build/reference/linenumbers.md b/docs/build/reference/linenumbers.md index b50a4a4262..24ac0dc6c6 100644 --- a/docs/build/reference/linenumbers.md +++ b/docs/build/reference/linenumbers.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /LINENUMBERS" title: "/LINENUMBERS" ms.date: "11/04/2016" f1_keywords: ["/linenumbers"] 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 e68d115fd8..80664636c6 100644 --- a/docs/build/reference/link-input-files.md +++ b/docs/build/reference/link-input-files.md @@ -1,41 +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-output.md b/docs/build/reference/link-output.md index 48287c6c11..da8f24adf5 100644 --- a/docs/build/reference/link-output.md +++ b/docs/build/reference/link-output.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: LINK Output" title: "LINK Output" ms.date: "11/04/2016" helpviewer_keywords: ["mapfiles [C++]", "ILK files", "output files [C++], linker", "files [C++], LINK", ".ilk files", "LINK tool [C++], output", "import libraries [C++], creating", "executable files [C++], as linker output", "mapfiles [C++], LINK output", "linker [C++], output files", "DLLs [C++], as linker output", "LINK tool [C++], mapfile"] diff --git a/docs/build/reference/link-pass-options-to-linker.md b/docs/build/reference/link-pass-options-to-linker.md index 3a20d92055..c8824f2f5b 100644 --- a/docs/build/reference/link-pass-options-to-linker.md +++ b/docs/build/reference/link-pass-options-to-linker.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /link (Pass Options to Linker)" title: "/link (Pass Options to Linker)" ms.date: "03/25/2019" f1_keywords: ["/link"] 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 062699b0a4..5749d0c236 100644 --- a/docs/build/reference/linker-options.md +++ b/docs/build/reference/linker-options.md @@ -1,134 +1,140 @@ --- title: "MSVC Linker options" description: "A list of the options supported by the Microsoft LINK linker." -ms.date: "02/09/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.| -|[/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.| -|[/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 409e638102..27a8a52d11 100644 --- a/docs/build/reference/linker-property-pages.md +++ b/docs/build/reference/linker-property-pages.md @@ -1,8 +1,9 @@ --- 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 @@ -12,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 @@ -30,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** @@ -183,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 @@ -216,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. @@ -242,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** @@ -353,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** @@ -439,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 @@ -449,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 @@ -464,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/linker-support-for-delay-loaded-dlls.md b/docs/build/reference/linker-support-for-delay-loaded-dlls.md index 86453c3bb9..cf73ac44b4 100644 --- a/docs/build/reference/linker-support-for-delay-loaded-dlls.md +++ b/docs/build/reference/linker-support-for-delay-loaded-dlls.md @@ -1,46 +1,170 @@ --- -title: "Linker Support for Delay-Loaded DLLs" -ms.date: "11/04/2016" +description: "Learn more about: Linker support for delay-loaded DLLs" +title: "Linker support for delay-loaded DLLs" +ms.date: "01/19/2021" helpviewer_keywords: ["delayed loading of DLLs, linker support"] -ms.assetid: b2d7e449-2809-42b1-9c90-2c0ca5e31a14 --- -# Linker Support for Delay-Loaded DLLs +# Linker support for delay-loaded DLLs -The MSVC linker now supports the delayed loading of DLLs. This relieves you of the need to use the Windows SDK functions **LoadLibrary** and **GetProcAddress** to implement DLL delayed loading. +The MSVC linker supports the delayed loading of DLLs. This feature relieves you of the need to use the Windows SDK functions [`LoadLibrary`](/windows/win32/api/libloaderapi/nf-libloaderapi-loadlibraryw) and [`GetProcAddress`](/windows/win32/api/libloaderapi/nf-libloaderapi-getprocaddress) to implement DLL delayed loading. -Before Visual C++ 6.0, the only way to load a DLL at run time was by using **LoadLibrary** and **GetProcAddress**; the operating system would load the DLL when the executable or DLL using it was loaded. +Without delayed load, the only way to load a DLL at run time is by using `LoadLibrary` and `GetProcAddress`; the operating system loads the DLL when the executable or DLL using it gets loaded. -Beginning with Visual C++ 6.0, when implicitly linking with a DLL, the linker provides options to delay load the DLL until the program calls a function in that DLL. +With delayed load, when you implicitly link a DLL, the linker provides options to delay the DLL load until the program calls a function in that DLL. -An application can delay load a DLL using the [/DELAYLOAD (Delay Load Import)](delayload-delay-load-import.md) linker option with a helper function (default implementation provided by Visual C++). The helper function will load the DLL at run time by calling **LoadLibrary** and **GetProcAddress** for you. +An application can delay load a DLL using the [`/DELAYLOAD` (Delay load import)](delayload-delay-load-import.md) linker option with a helper function. (A default helper function implementation is provided by Microsoft.) The helper function loads the DLL on demand at runtime by calling `LoadLibrary` and `GetProcAddress` for you. -You should consider delay loading a DLL if: +Consider delay loading a DLL if: -- Your program may not call a function in the DLL. +- Your program might not call a function in the DLL. -- A function in the DLL may not get called until late in your program's execution. +- A function in the DLL might not get called until late in your program's execution. -The delayed loading of a DLL can be specified during the build of either a .EXE or .DLL project. A .DLL project that delays the loading of one or more DLLs should not itself call a delay-loaded entry point in Dllmain. +The delayed loading of a DLL can be specified during the build of either an EXE or DLL project. A DLL project that delays the loading of one or more DLLs itself shouldn't call a delay-loaded entry point in `DllMain`. -The following topics describe delay loading DLLs: +## Specify DLLs to delay load -- [Specifying DLLs to Delay Load](specifying-dlls-to-delay-load.md) +You can specify which DLLs to delay load by using the [`/delayload:`*`dllname`*](delayload-delay-load-import.md) linker option. If you don't plan to use your own version of a helper function, you must also link your program with *`delayimp.lib`* (for desktop applications) or *`dloadhelper.lib`* (for UWP apps). -- [Explicitly Unloading a Delay-Loaded DLL](explicitly-unloading-a-delay-loaded-dll.md) +Here's a simple example of delay loading a DLL: -- [Loading All Imports for a Delay-Loaded DLL](loading-all-imports-for-a-delay-loaded-dll.md) +```cpp +// cl t.cpp user32.lib delayimp.lib /link /DELAYLOAD:user32.dll +#include +// uncomment these lines to remove .libs from command line +// #pragma comment(lib, "delayimp") +// #pragma comment(lib, "user32") -- [Binding Imports](binding-imports.md) +int main() { + // user32.dll will load at this point + MessageBox(NULL, "Hello", "Hello", MB_OK); +} +``` -- [Error Handling and Notification](error-handling-and-notification.md) +Build the DEBUG version of the project. Step through the code using the debugger and you'll notice that *`user32.dll`* is loaded only when you make the call to `MessageBox`. -- [Dumping Delay-Loaded Imports](dumping-delay-loaded-imports.md) +## Explicitly unload a delay-loaded DLL -- [Constraints of Delay Loading DLLs](constraints-of-delay-loading-dlls.md) +The [`/delay:unload`](delay-delay-load-import-settings.md) linker option allows your code to explicitly unload a DLL that was delay loaded. By default, the delay-loaded imports remain in the import address table (IAT). However, if you use **`/delay:unload`** on the linker command line, the helper function supports the explicit unloading of the DLL by a `__FUnloadDelayLoadedDLL2` call, and resets the IAT to its original form. The now-invalid pointers get overwritten. The IAT is a field in the [`ImgDelayDescr`](understanding-the-helper-function.md#calling-conventions-parameters-and-return-type) structure that contains the address of a copy of the original IAT, if one exists. -- [Understanding the Helper Function](understanding-the-helper-function.md) +### Example of unloading a delay-loaded DLL -- [Developing Your Own Helper Function](developing-your-own-helper-function.md) +This example shows how to explicitly unload a DLL, *`MyDll.dll`*, which contains a function `fnMyDll`: + +```C +// link with /link /DELAYLOAD:MyDLL.dll /DELAY:UNLOAD +#include +#include +#include "MyDll.h" +#include + +#pragma comment(lib, "delayimp") +#pragma comment(lib, "MyDll") +int main() +{ + BOOL TestReturn; + // MyDLL.DLL will load at this point + fnMyDll(); + + //MyDLL.dll will unload at this point + TestReturn = __FUnloadDelayLoadedDLL2("MyDll.dll"); + + if (TestReturn) + printf_s("\nDLL was unloaded"); + else + printf_s("\nDLL was not unloaded"); +} +``` + +Important notes on unloading a delay-loaded DLL: + +- You can find the implementation of the `__FUnloadDelayLoadedDLL2` function in the file *`delayhlp.cpp`*, in the MSVC *`include`* directory. For more information, see [Understand the delay load helper function](understanding-the-helper-function.md). + +- The *`name`* parameter of the `__FUnloadDelayLoadedDLL2` function must exactly match (including case) what the import library contains. (That string is also in the import table in the image.) You can view the contents of the import library by using [`DUMPBIN /DEPENDENTS`](dependents.md). If you prefer a case-insensitive string match, you can update `__FUnloadDelayLoadedDLL2` to use one of the case-insensitive CRT string functions, or a Windows API call. + +## Bind delay-loaded imports + +The default linker behavior is to create a bindable import address table (IAT) for the delay-loaded DLL. If the DLL is bound, the helper function attempts to use the bound information instead of calling `GetProcAddress` on each of the referenced imports. If either the timestamp or the preferred address doesn't match the one in the loaded DLL, the helper function assumes the bound import address table is out of date. It proceeds as if the IAT doesn't exist. + +If you never intend to bind the delay-loaded imports of a DLL, specify [`/delay:nobind`](delay-delay-load-import-settings.md) on the linker command line. The linker won't generate the bound import address table, which saves space in the image file. + +## Load all imports for a delay-loaded DLL + +The `__HrLoadAllImportsForDll` function, which is defined in *`delayhlp.cpp`*, tells the linker to load all imports from a DLL that was specified with the [`/delayload`](delayload-delay-load-import.md) linker option. + +When you load all imports at once, you can centralize error handling in one place. You can avoid structured exception handling around all the actual calls to the imports. It also avoids a situation where your application fails part way through a process: For example, if the helper code fails to load an import, after successfully loading others. + +Calling `__HrLoadAllImportsForDll` doesn't change the behavior of hooks and error handling. For more information, see [Error handling and notification](error-handling-and-notification.md). + +`__HrLoadAllImportsForDll` makes a case-sensitive comparison to the name stored inside the DLL itself. + +Here's an example that uses `__HrLoadAllImportsForDll` in a function called `TryDelayLoadAllImports` to attempt to load a named DLL. It uses a function, `CheckDelayException`, to determine exception behavior. + +```C +int CheckDelayException(int exception_value) +{ + if (exception_value == VcppException(ERROR_SEVERITY_ERROR, ERROR_MOD_NOT_FOUND) || + exception_value == VcppException(ERROR_SEVERITY_ERROR, ERROR_PROC_NOT_FOUND)) + { + // This example just executes the handler. + return EXCEPTION_EXECUTE_HANDLER; + } + // Don't attempt to handle other errors + return EXCEPTION_CONTINUE_SEARCH; +} + +bool TryDelayLoadAllImports(LPCSTR szDll) +{ + __try + { + HRESULT hr = __HrLoadAllImportsForDll(szDll); + if (FAILED(hr)) + { + // printf_s("Failed to delay load functions from %s\n", szDll); + return false; + } + } + __except (CheckDelayException(GetExceptionCode())) + { + // printf_s("Delay load exception for %s\n", szDll); + return false; + } + // printf_s("Delay load completed for %s\n", szDll); + return true; +} +``` + +You can use the result of `TryDelayLoadAllImports` to control whether you call the import functions or not. + +## Error handling and notification + +If your program uses delay-loaded DLLs, it must handle errors robustly. Failures that occur while the program is running will result in unhandled exceptions. For more information on DLL delay load error handling and notification, see [Error handling and notification](error-handling-and-notification.md). + +## Dump delay-loaded imports + +Delay-loaded imports can be dumped by using [`DUMPBIN /IMPORTS`](imports-dumpbin.md). These imports show up with slightly different information than standard imports. They're segregated into their own section of the `/imports` list, and are explicitly labeled as delay-loaded imports. If there's unload information present in the image, that is noted. If there's bind information present, the time and date stamp of the target DLL is noted along with the bound addresses of the imports. + +## Constraints on delay-load DLLs + +There are several constraints on the delay loading of DLL imports. + +- Imports of data can't be supported. A workaround is to explicitly handle the data import yourself by using `LoadLibrary` (or by using [`GetModuleHandle`](/windows/win32/api/libloaderapi/nf-libloaderapi-getmodulehandlew) after you know the delay-load helper has loaded the DLL) and `GetProcAddress`. + +- Delay loading *`Kernel32.dll`* isn't supported. This DLL must be loaded for the delay-load helper routines to work. + +- [Binding](#bind-delay-loaded-imports) of forwarded entry points isn't supported. + +- A process may have different behavior if a DLL is delay-loaded, instead of loaded on start-up. It can be seen if there are per-process initializations that occur in the entry point of the delay-loaded DLL. Other cases include static TLS (thread local storage), declared using [`__declspec(thread)`](../../cpp/thread.md), which isn't handled when the DLL is loaded via `LoadLibrary`. Dynamic TLS, using [`TlsAlloc`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-tlsalloc), [`TlsFree`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-tlsfree), [`TlsGetValue`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-tlsgetvalue), and [`TlsSetValue`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-tlssetvalue), is still available for use in either static or delay-loaded DLLs. + +- Reinitialize static global function pointers to imported functions after the first call of each function. That's required because the first use of a function pointer points to the thunk, not the loaded function. + +- There's currently no way to delay the loading of only specific procedures from a DLL while using the normal import mechanism. + +- Custom calling conventions (such as using condition codes on x86 architectures) aren't supported. Also, the floating-point registers aren't saved on any platform. Take care if your custom helper routine or hook routines use floating-point types: The routines must save and restore the complete floating-point state on machines that use register calling conventions with floating-point parameters. Be careful about delay-loading the CRT DLL, particularly if you call CRT functions that take floating-point parameters on a numeric data processor (NDP) stack in the help function. + +## Understand the delay load helper function + +The helper function for linker-supported delayed loading is what actually loads the DLL at runtime. You can modify the helper function to customize its behavior. Instead of using the supplied helper function in *`delayimp.lib`*, write your own function and link it to your program. One helper function serves all delay loaded DLLs. For more information, see [Understand the delay load helper function](understanding-the-helper-function.md) and [Develop your own helper function](understanding-the-helper-function.md#develop-your-own-helper-function). ## See also diff --git a/docs/build/reference/linkermember.md b/docs/build/reference/linkermember.md index a036bf456d..c71480e49c 100644 --- a/docs/build/reference/linkermember.md +++ b/docs/build/reference/linkermember.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /LINKERMEMBER" title: "/LINKERMEMBER" ms.date: "11/04/2016" f1_keywords: ["/linkermember"] diff --git a/docs/build/reference/linking.md b/docs/build/reference/linking.md index 4dbe6f32e4..8891ebf554 100644 --- a/docs/build/reference/linking.md +++ b/docs/build/reference/linking.md @@ -1,82 +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 c02ac3fcc5..56154a07e8 100644 --- a/docs/build/reference/list-visual-cpp.md +++ b/docs/build/reference/list-visual-cpp.md @@ -1,17 +1,18 @@ --- -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 `` 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 -``` +```xml term @@ -24,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 @@ -61,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/ln-create-msil-module.md b/docs/build/reference/ln-create-msil-module.md index ee11436e28..b5cd351176 100644 --- a/docs/build/reference/ln-create-msil-module.md +++ b/docs/build/reference/ln-create-msil-module.md @@ -1,13 +1,13 @@ --- +description: "Learn more about: /LN (Create MSIL Module)" title: "/LN (Create MSIL Module)" ms.date: "11/04/2016" f1_keywords: ["/LN"] helpviewer_keywords: ["-LN compiler option [C++]", "/LN compiler option [C++]"] -ms.assetid: 4f38f4f4-3176-4caf-8200-5c7585dc1ed3 --- # /LN (Create MSIL Module) -Specifies that an assembly manifest should not be inserted into the output file. +Specifies that the compiler shouldn't insert an assembly manifest into the output file. ## Syntax @@ -17,27 +17,27 @@ Specifies that an assembly manifest should not be inserted into the output file. ## Remarks -By default, **/LN** is not in effect (an assembly manifest is inserted into the output file). +By default, `/LN` isn't in effect, and the compiler inserts an assembly manifest into the output file. -When **/LN** is used, one of the [/clr (Common Language Runtime Compilation)](clr-common-language-runtime-compilation.md) options must also be used. +When you use `/LN`, you must also use one of the [/clr (Common Language Runtime Compilation)](clr-common-language-runtime-compilation.md) options. -A managed program that does not have an assembly metadata in the manifest is called a module. If you compile with [/c (Compile Without Linking)](c-compile-without-linking.md) and **/LN**, specify [/NOASSEMBLY (Create a MSIL Module)](noassembly-create-a-msil-module.md) in the linker phase to create the output file. +A managed program that doesn't have assembly metadata in the manifest is called a module. If you compile with [/c (Compile Without Linking)](c-compile-without-linking.md) and `/LN`, specify [`/NOASSEMBLY `(Create a MSIL Module)](noassembly-create-a-msil-module.md) in the linker phase to create the output file. -You may want to create modules if you want to take a component-based approach to building assemblies. That is, you can author types and compile them into modules. Then, you can generate an assembly from one or more modules. For more information on creating assemblies from modules, see [.netmodule Files as Linker Input](netmodule-files-as-linker-input.md) or [Al.exe (Assembly Linker)](/dotnet/framework/tools/al-exe-assembly-linker). +Create modules if you want to take a component-based approach to building assemblies. You can author types and compile them into modules. Then, you can generate an assembly from one or more modules. For more information on creating assemblies from modules, see [`.netmodule` Files as Linker Input](netmodule-files-as-linker-input.md) or [`Al.exe `(Assembly Linker)](/dotnet/framework/tools/al-exe-assembly-linker). -The default file extension for a module is .netmodule. +The default file extension for a module is `.netmodule`. -In releases before Visual Studio 2005, a module was created with **/clr:noAssembly**. +In releases before Visual Studio 2005, you created a module with `/clr:noAssembly`. -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. The output file produced by the linker is an assembly or `.netmodule` with no run-time dependence on any of the `.netmodule`s that you input to the linker. For more information, see [`.netmodule `Files as Linker Input](netmodule-files-as-linker-input.md). ### To set this compiler option in the Visual Studio development environment -- Specify [/NOASSEMBLY (Create a MSIL Module)](noassembly-create-a-msil-module.md) in the linker phase to create the output file. +- Specify [`/NOASSEMBLY` (Create a MSIL Module)](noassembly-create-a-msil-module.md) in the linker phase to create the output file. ### To set this compiler option programmatically -- This compiler option cannot be changed programmatically. +- You can't change this compiler option programmatically. ## See also diff --git a/docs/build/reference/loadconfig.md b/docs/build/reference/loadconfig.md index 63384e0af1..0e2b89cd44 100644 --- a/docs/build/reference/loadconfig.md +++ b/docs/build/reference/loadconfig.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /LOADCONFIG" title: "/LOADCONFIG" ms.date: "11/04/2016" f1_keywords: ["/loadconfig"] diff --git a/docs/build/reference/loading-all-imports-for-a-delay-loaded-dll.md b/docs/build/reference/loading-all-imports-for-a-delay-loaded-dll.md deleted file mode 100644 index 78a7c1f914..0000000000 --- a/docs/build/reference/loading-all-imports-for-a-delay-loaded-dll.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: "Loading All Imports for a Delay-Loaded DLL" -ms.date: "11/04/2016" -helpviewer_keywords: ["__HrLoadAllImportsForDll linker option"] -ms.assetid: 975fcd97-1a56-4a16-9698-e1a249d2d592 ---- -# Loading All Imports for a Delay-Loaded DLL - -The **__HrLoadAllImportsForDll** function, which is defined in delayhlp.cpp, tells the linker to load all imports from a DLL that was specified with the [/delayload](delayload-delay-load-import.md) linker option. - -Loading all imports allows you to put error handling in one place in your code and not have to use exception handling around the actual calls to the imports. It also avoids a situation where your application fails partially through a process as a result of the helper code failing to load an import. - -Calling **__HrLoadAllImportsForDll** does not change the behavior of hooks and error handling; see [Error Handling and Notification](error-handling-and-notification.md) for more information. - -The DLL name passed to **__HrLoadAllImportsForDll** is compared to the name stored inside the DLL itself and is case sensitive. - -The following example shows how to call **__HrLoadAllImportsForDll**: - -``` -if (FAILED(__HrLoadAllImportsForDll("delay1.dll"))) { - printf ( "failed on snap load, exiting\n" ); - exit(2); -} -``` - -## See also - -[Linker Support for Delay-Loaded DLLs](linker-support-for-delay-loaded-dlls.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 a4109118e5..0000000000 --- a/docs/build/reference/long-filenames-in-a-makefile.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -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/look-up-button.md b/docs/build/reference/look-up-button.md index f46cc9d583..ad47b7bd5f 100644 --- a/docs/build/reference/look-up-button.md +++ b/docs/build/reference/look-up-button.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Look Up Button" title: "Look Up Button" ms.date: "11/04/2016" helpviewer_keywords: ["Look Up button"] diff --git a/docs/build/reference/ltcg-link-time-code-generation.md b/docs/build/reference/ltcg-link-time-code-generation.md index 169bb1a355..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,25 +12,25 @@ 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`**. +(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`**. **`PGOPTIMIZE`**
(Optional) This option is deprecated starting in Visual Studio 2015. Instead, use **`/LTCG`** and [`/USEPROFILE`](useprofile.md) to build an optimized image. For more information, see [Profile-Guided Optimizations](../profile-guided-optimizations.md). The short form of this option is **`/LTCG:PGO`**. @@ -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 be69f6ee65..203ac3a325 100644 --- a/docs/build/reference/machine-specify-target-platform.md +++ b/docs/build/reference/machine-specify-target-platform.md @@ -1,29 +1,26 @@ --- +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 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 **Advanced** property page. +1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. 1. Modify the **Target Machine** property. @@ -33,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 b1f17ff14c..0000000000 --- a/docs/build/reference/macro-substitution.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -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/macros-and-nmake.md b/docs/build/reference/macros-and-nmake.md index d4f9b87926..df09c388eb 100644 --- a/docs/build/reference/macros-and-nmake.md +++ b/docs/build/reference/macros-and-nmake.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Macros and NMAKE" title: "Macros and NMAKE" ms.date: "11/04/2016" helpviewer_keywords: ["NMAKE macros", "macros, NMAKE"] diff --git a/docs/build/reference/makefile-preprocessing-directives.md b/docs/build/reference/makefile-preprocessing-directives.md deleted file mode 100644 index 7be0d0cd0c..0000000000 --- a/docs/build/reference/makefile-preprocessing-directives.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -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 ca48b93c5a..0000000000 --- a/docs/build/reference/makefile-preprocessing-operators.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -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 04f07473d7..7092de7a26 100644 --- a/docs/build/reference/makefile-preprocessing.md +++ b/docs/build/reference/makefile-preprocessing.md @@ -1,18 +1,141 @@ --- -title: "Makefile Preprocessing" -ms.date: "11/04/2016" -helpviewer_keywords: ["preprocessing makefiles", "makefiles, preprocessing"] -ms.assetid: a9185139-97c9-4adb-b4a9-1ec395cce9f8 +title: "Makefile preprocessing" +description: "Learn more about: Makefile Preprocessing" +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/managed-resources-property-page.md b/docs/build/reference/managed-resources-property-page.md index 5a4f8e7f9e..492d86ac45 100644 --- a/docs/build/reference/managed-resources-property-page.md +++ b/docs/build/reference/managed-resources-property-page.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Managed Resources Property Page" title: "Managed Resources Property Page" ms.date: "08/28/2019" f1_keywords: ["VC.Project.VCManagedResourceCompilerTool.ResourceFileName", "VC.Project.VCManagedResourceCompilerTool.OutputFileName", "VC.Project.VCManagedResourceCompilerTool.DefaultLocalizedResources"] diff --git a/docs/build/reference/managing-a-library.md b/docs/build/reference/managing-a-library.md index 812fd04650..5ea56fcb14 100644 --- a/docs/build/reference/managing-a-library.md +++ b/docs/build/reference/managing-a-library.md @@ -1,48 +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: @@ -55,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 72ae7aa480..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,47 +1,46 @@ --- -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. -## Remarks +## Syntax -/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). +> **`/MANIFEST`**\[**`:`**{**`EMBED`**\[**`,ID=`***`resource_id`*]\|**`NO`**}] -The default is /MANIFEST. +## Remarks -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`** 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). -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). +The default is **`/MANIFEST`**. -To change the default behavior for UAC, do one of these: +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. -- Specify the /MANIFESTUAC option and set the UAC level to the desired value. +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). -- Or specify the /MANIFESTUAC:NO option if you do not want to generate a UAC fragment in the manifest. +To change the default behavior for UAC, set one of these options: -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. +- Specify the **`/MANIFESTUAC`** option and set the UAC level to the desired value. -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*. +- Or, specify the **`/MANIFESTUAC:NO`** option if you don't want to generate a UAC fragment in the manifest. -### To set this linker option in the Visual Studio development environment +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`**. -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). +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`*. -1. Expand the **Configuration Properties** node. +### To set this linker option in the Visual Studio development environment -1. Expand the **Linker** node. +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 **Manifest File** property page. +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 @@ -49,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 3a726d0d89..cdf705d3d8 100644 --- a/docs/build/reference/manifest-tool-property-pages.md +++ b/docs/build/reference/manifest-tool-property-pages.md @@ -1,7 +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 @@ -22,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` @@ -65,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 @@ -73,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** @@ -99,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 @@ -129,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/manifestdependency-specify-manifest-dependencies.md b/docs/build/reference/manifestdependency-specify-manifest-dependencies.md index 4979805a0d..a08dddac2a 100644 --- a/docs/build/reference/manifestdependency-specify-manifest-dependencies.md +++ b/docs/build/reference/manifestdependency-specify-manifest-dependencies.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /MANIFESTDEPENDENCY (Specify Manifest Dependencies)" title: "/MANIFESTDEPENDENCY (Specify Manifest Dependencies)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCLinkerTool.AdditionalManifestDependencies"] diff --git a/docs/build/reference/manifestfile-name-manifest-file.md b/docs/build/reference/manifestfile-name-manifest-file.md index de62f1ede7..32a06f368e 100644 --- a/docs/build/reference/manifestfile-name-manifest-file.md +++ b/docs/build/reference/manifestfile-name-manifest-file.md @@ -1,32 +1,31 @@ --- +description: "Learn more about: /MANIFESTFILE (Name Manifest File)" 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 - -/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. +## Syntax -/MANIFESTFILE will have no effect if you do not also link with [/MANIFEST](manifest-create-side-by-side-assembly-manifest.md). +> `/MANIFESTFILE:`**filename** -### To set this linker option in the Visual Studio development environment +## Arguments -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). +**filename**\ +The default name of the manifest file is *filename* with `.manifest` appended. -1. Expand the **Configuration Properties** node. +## Remarks -1. Expand the **Linker** node. +`/MANIFESTFILE` has no effect if you do not also link with [/MANIFEST](manifest-create-side-by-side-assembly-manifest.md). -1. Select the **Manifest File** property page. +### 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 @@ -35,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 6b7296fc19..df8b326f7d 100644 --- a/docs/build/reference/manifestinput-specify-manifest-input.md +++ b/docs/build/reference/manifestinput-specify-manifest-input.md @@ -1,7 +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) @@ -9,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/manifestuac-embeds-uac-information-in-manifest.md b/docs/build/reference/manifestuac-embeds-uac-information-in-manifest.md index 7769f78a6a..fe3af69ca1 100644 --- a/docs/build/reference/manifestuac-embeds-uac-information-in-manifest.md +++ b/docs/build/reference/manifestuac-embeds-uac-information-in-manifest.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /MANIFESTUAC (Embeds UAC information in manifest)" title: "/MANIFESTUAC (Embeds UAC information in manifest)" ms.date: "06/12/2020" f1_keywords: ["VC.Project.VCLinkerTool.UACUIAccess", "VC.Project.VCLinkerTool.UACExecutionLevel", "VC.Project.VCLinkerTool.EnableUAC"] diff --git a/docs/build/reference/map-generate-mapfile.md b/docs/build/reference/map-generate-mapfile.md index 60fc6c2fed..fe7b049ca4 100644 --- a/docs/build/reference/map-generate-mapfile.md +++ b/docs/build/reference/map-generate-mapfile.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /MAP (Generate Mapfile)" title: "/MAP (Generate Mapfile)" ms.date: "11/04/2016" f1_keywords: ["/map", "VC.Project.VCLinkerTool.MapFileName", "VC.Project.VCLinkerTool.GenerateMapFile"] @@ -40,9 +41,7 @@ The [/MAPINFO](mapinfo-include-information-in-mapfile.md) option specifies addit 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 **Debug** property page. +1. Select the **Configuration Properties** > **Linker** > **Debug** property page. 1. Modify the **Generate Map File** property. diff --git a/docs/build/reference/mapinfo-include-information-in-mapfile.md b/docs/build/reference/mapinfo-include-information-in-mapfile.md index 1cc4e6badf..7c4c3aced3 100644 --- a/docs/build/reference/mapinfo-include-information-in-mapfile.md +++ b/docs/build/reference/mapinfo-include-information-in-mapfile.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /MAPINFO (Include Information in Mapfile)" title: "/MAPINFO (Include Information in Mapfile)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCLinkerTool.MapLines", "VC.Project.VCLinkerTool.MapInfoFixups", "VC.Project.VCLinkerTool.MapExports", "/mapinfo"] @@ -19,9 +20,7 @@ The /MAPINFO option tells the linker to include the specified information in a m 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 **Debug** property page. +1. Select the **Configuration Properties** > **Linker** > **Debug** property page. 1. Modify of the **Map Exports** properties: 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 0e9b8eaeae..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,13 +1,13 @@ --- -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 @@ -21,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 @@ -50,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/merge-combine-sections.md b/docs/build/reference/merge-combine-sections.md index 7c3e9ea552..0cef6fa371 100644 --- a/docs/build/reference/merge-combine-sections.md +++ b/docs/build/reference/merge-combine-sections.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /MERGE (Combine Sections)" title: "/MERGE (Combine Sections)" ms.date: "11/04/2016" f1_keywords: ["/merge", "VC.Project.VCLinkerTool.MergeSections"] @@ -23,9 +24,7 @@ The /MERGE option is useful for creating VxDs and overriding the compiler-genera 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 **Advanced** property page. +1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. 1. Modify the **Merge Sections** property. diff --git a/docs/build/reference/mfc-program-or-control-source-and-header-files.md b/docs/build/reference/mfc-program-or-control-source-and-header-files.md index ba0fee10b5..283a500c46 100644 --- a/docs/build/reference/mfc-program-or-control-source-and-header-files.md +++ b/docs/build/reference/mfc-program-or-control-source-and-header-files.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: MFC Program or Control Source and Header Files" title: "MFC Program or Control Source and Header Files" ms.date: "11/04/2016" helpviewer_keywords: ["file types [C++], MFC source and header"] 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 a9e9beab5b..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,107 +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: @@ -109,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 ) { @@ -117,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 ); @@ -143,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`**. @@ -152,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; @@ -165,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 }; ``` @@ -176,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: @@ -186,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 5288079010..66c3955c39 100644 --- a/docs/build/reference/midl-property-pages.md +++ b/docs/build/reference/midl-property-pages.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: MIDL Property Pages" title: "MIDL Compiler Property Pages" ms.date: "07/24/2019" ms.topic: "article" @@ -46,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/midl-specify-midl-command-line-options.md b/docs/build/reference/midl-specify-midl-command-line-options.md index 427e908b56..1af7a41b5b 100644 --- a/docs/build/reference/midl-specify-midl-command-line-options.md +++ b/docs/build/reference/midl-specify-midl-command-line-options.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /MIDL (Specify MIDL Command Line Options)" title: "/MIDL (Specify MIDL Command Line Options)" ms.date: "09/05/2018" f1_keywords: ["/midl", "VC.Project.VCLinkerTool.MidlCommandFile"] @@ -43,4 +44,4 @@ The file should contain one MIDL command-line option per line. [/IDLOUT (Name MIDL Output Files)](idlout-name-midl-output-files.md)
[/IGNOREIDL (Don't Process Attributes into MIDL)](ignoreidl-don-t-process-attributes-into-midl.md)
[/TLBOUT (Name .TLB File)](tlbout-name-dot-tlb-file.md)
-[Building an Attributed Program](../../windows/building-an-attributed-program.md) +[Building an Attributed Program](../../windows/attributes/cpp-attributes-com-net.md) diff --git a/docs/build/reference/module-definition-dot-def-files.md b/docs/build/reference/module-definition-dot-def-files.md index ff4e0cf93c..2153611a97 100644 --- a/docs/build/reference/module-definition-dot-def-files.md +++ b/docs/build/reference/module-definition-dot-def-files.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Module-Definition (.Def) Files" title: "Module-Definition (.Def) Files" ms.date: "11/04/2016" helpviewer_keywords: ["def files", "module definition files", ".def files"] diff --git a/docs/build/reference/module-exportheader.md b/docs/build/reference/module-exportheader.md new file mode 100644 index 0000000000..5c1b8a839c --- /dev/null +++ b/docs/build/reference/module-exportheader.md @@ -0,0 +1,71 @@ +--- +title: "/exportHeader (Create header units)" +description: "Use the /exportHeader compiler option to create module header units for the header-name or include files specified." +ms.date: 05/18/2020 +author: "tylermsft" +ms.author: "twhitney" +f1_keywords: ["/exportHeader"] +helpviewer_keywords: ["/exportHeader", "Create header units"] +--- +# `/exportHeader` (Create header units) + +Tells the compiler to create the header units specified by the input arguments. The compiler generates header units as IFC (*`.ifc`*) files. + +## Syntax + +> **`/exportHeader /headerName:angle`** *`header-name`*\ +> **`/exportHeader /headerName:quote`** *`header-name`*\ +> **`/exportHeader`** *`full path to header file`* + +### Arguments + +The argument to `/exportHeader` is a `/headerName` command-line option that specifies the name, *`header-name`*, of the header file to export. + +## Remarks + +**`/exportHeader`** is available starting in Visual Studio 2019 version 16.10. + +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 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). + +You may find it helpful to use the complementary option **`/showResolvedHeader`**. The **`/showResolvedHeader`** option prints an absolute path to the file the *`header-name`* argument resolves to. + +**`/exportHeader`** can handle multiple inputs at once, even under **`/MP`**. We recommended you use **`/ifcOutput `** to create a separate *`.ifc`* file for each compilation. + +### Examples + +To build a header unit such as `` might look like: + +```cmd +cl . . . /std:c++latest /exportHeader /headerName:angle vector +``` + +Building a local project header such as `"utils/util.h"` might look like: + +```cmd +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 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)\ +[`/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 new file mode 100644 index 0000000000..10f51331a9 --- /dev/null +++ b/docs/build/reference/module-reference.md @@ -0,0 +1,82 @@ +--- +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: 02/17/2022 +f1_keywords: ["/reference", "VC.Project.VCCLCompilerTool.AdditionalModuleDependencies"] +helpviewer_keywords: ["/reference", "Use named module IFC"] +--- +# `/reference` (Use named module IFC) + +Tells the compiler to use an existing IFC (*`.ifc`*) for the current compilation. + +## Syntax + +> **`/reference`** *`module-name=filename`*\ +> **`/reference`** *`filename`* + +### Arguments + +*`filename`*\ +The name of a file that contains *IFC data*, which is prebuilt module information. To import more than one module, include a separate **`/reference`** option for each file. + +*`module-name`*\ +A valid name of an exported primary module interface unit name or full module partition name. + +## Remarks + +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++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. + +The *`module-name`* must be a valid primary module interface unit name or full module partition name. Examples of primary module interface names include: + +- `M` +- `M.N.O` +- `MyModule` +- `my_module` + +Examples of full module partition names include: + +- `M:P` +- `M.N.O:P.Q` +- `MyModule:Algorithms` +- `my_module:algorithms` + +If a module reference is created using a *`module-name`*, other modules on the command line don't get searched if the compiler encounters an import of that name. For example, given this command line: + +```cmd +cl ... /std:c++latest /reference m.ifc /reference m=n.ifc +``` + +In the case above, if the compiler sees `import m;` then *`m.ifc`* doesn't get searched. + +### Examples + +Given three modules as listed in this table: + +| Module | IFC file | +|--|--| +| *`M`* | *`m.ifc`* | +| *`M:Part1`* | *`m-part1.ifc`* | +| *`Core.Networking`* | *`Networking.ifc`* | + +The reference options using a *`filename`* argument would be like this: + +```cmd +cl ... /std:c++latest /reference m.ifc /reference m-part.ifc /reference Networking.ifc +``` + +The reference options using *`module-name=filename`* would be like this: + +```cmd +cl ... /std:c++latest /reference m=m.ifc /reference M:Part1=m-part.ifc /reference Core.Networking=Networking.ifc +``` + +## 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/modules-button.md b/docs/build/reference/modules-button.md index 1ddb985208..99581bf6ae 100644 --- a/docs/build/reference/modules-button.md +++ b/docs/build/reference/modules-button.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Modules Button" title: "Modules Button" ms.date: "11/04/2016" helpviewer_keywords: ["Modules button"] diff --git a/docs/build/reference/mp-build-with-multiple-processes.md b/docs/build/reference/mp-build-with-multiple-processes.md index f710bf6517..de05d5234b 100644 --- a/docs/build/reference/mp-build-with-multiple-processes.md +++ b/docs/build/reference/mp-build-with-multiple-processes.md @@ -1,121 +1,122 @@ --- -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 688e3e3a60..bbc889a922 100644 --- a/docs/build/reference/msbuild-reference-cpp.md +++ b/docs/build/reference/msbuild-reference-cpp.md @@ -1,6 +1,7 @@ --- 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 @@ -11,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 29c39501d5..e614f2f98a 100644 --- a/docs/build/reference/msbuild-visual-cpp-overview.md +++ b/docs/build/reference/msbuild-visual-cpp-overview.md @@ -1,8 +1,8 @@ --- title: "MSBuild internals for C++ projects in Visual Studio" -ms.date: "02/26/2020" +description: "The support files, properties, and targets used by MSBuild for Visual Studio C++ projects." +ms.date: 02/10/2022 helpviewer_keywords: ["MSBuild overview"] -ms.assetid: dd258f6f-ab51-48d9-b274-f7ba911d05ca --- # MSBuild internals for C++ projects @@ -14,51 +14,59 @@ Most targets and properties in the support files exist solely to implement the b By default, the primary Visual Studio support files are located in the following directories. This information is version-specific. -### Visual Studio 2019 +::: moniker range=">=msvc-160" -- %VSINSTALLDIR%MSBuild\\Microsoft\\VC\\*version*\\ +### Visual Studio 2022 and 2019 - 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 *version* placeholder refers to the Visual Studio version: v160 for Visual Studio 2019, v150 for Visual Studio 2017. +- *`%VSINSTALLDIR%MSBuild\Microsoft\VC\\`* -- %VSINSTALLDIR%MSBuild\\Microsoft\\VC\\*version*\\Platforms\\*platform*\\ + 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. - 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 *platform* placeholder represents the ARM, Win32, or x64 subdirectory. +- *`%VSINSTALLDIR%MSBuild\Microsoft\VC\\Platforms\\`* -- %VSINSTALLDIR%MSBuild\\Microsoft\\VC\\*version*\\Platforms\\*platform*\\PlatformToolsets\\*toolset*\\ + 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, ARM64, Win32, or x64 subdirectory. - Contains the directories that enable the build to generate C++ applications by using the specified *toolset*. The *platform* placeholder represents the ARM, Win32, or x64 subdirectory. The *toolset* placeholder represents the toolset subdirectory. +- *`%VSINSTALLDIR%MSBuild\Microsoft\VC\\Platforms\\PlatformToolsets\\`* + + Contains the directories that enable the build to generate C++ applications by using the specified *``*. The *``* placeholder represents the ARM, ARM64, Win32, or x64 subdirectory. The *``* placeholder represents the toolset subdirectory. + +::: moniker-end + +::: moniker range=">=msvc-150" ### Visual Studio 2017 -- %VSINSTALLDIR%Common7\\IDE\\VC\\VCTargets\\ +- *`%VSINSTALLDIR%Common7\IDE\VC\VCTargets\`* + + 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. +- *`%VSINSTALLDIR%Common7\IDE\VC\VCTargets\Platforms\\`* -- %VSINSTALLDIR%Common7\\IDE\\VC\\VCTargets\\Platforms\\*platform*\\ + 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, ARM64, Win32, or x64 subdirectory. - 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 *platform* placeholder represents the ARM, Win32, or x64 subdirectory. +- *`%VSINSTALLDIR%Common7\IDE\VC\VCTargets\Platforms\\PlatformToolsets\\`* -- %VSINSTALLDIR%Common7\\IDE\\VC\\VCTargets\\Platforms\\*platform*\\PlatformToolsets\\*toolset*\\ + Contains the directories that enable the build to generate C++ applications by using the specified *``*. The *``* placeholder represents the ARM, Win32, or x64 subdirectory. The *``* placeholder represents the toolset subdirectory. - Contains the directories that enable the build to generate C++ applications by using the specified *toolset*. The *platform* placeholder represents the ARM, Win32, or x64 subdirectory. The *toolset* placeholder represents the toolset subdirectory. +::: moniker-end ### Visual Studio 2015 and earlier -- *drive*:\\Program Files *(x86)*\\MSBuild\\Microsoft.Cpp (x86)\\v4.0\\*version*\\ +- *`:\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. -- *drive*:\\Program Files *(x86)*\\MSBuild\\Microsoft.Cpp\\v4.0\\*version*\\Platforms\\*platform*\\ +- *`:\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 *platform* placeholder represents the ARM, Win32, or x64 subdirectory. + 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. -- *drive*:\\Program Files *(x86)*\\MSBuild\\Microsoft.Cpp\\v4.0\\*version*\\Platforms\\*platform*\\PlatformToolsets\\*toolset*\\ +- *`:\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 *toolset*. The *version* placeholder is V110 for Visual Studio 2012, V120 for Visual Studio 2013, and V140 for Visual Studio 2015. The *platform* placeholder represents the ARM, Win32, or x64 subdirectory. The *toolset* 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. + 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. -- *drive*:\\Program Files *(x86)*\\MSBuild\\Microsoft.Cpp\\v4.0\\Platforms\\*platform*\\PlatformToolsets\\*toolset*\\ +- *`:\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 *version*. In those versions, the *platform* placeholder represents the Itanium, Win32, or x64 subdirectory. The *toolset* placeholder represents the v90 or v100 toolset subdirectory. + 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. ## Support Files @@ -66,15 +74,15 @@ 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). | -| .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\\. | +| *`.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 +### `PlatformToolset` property The `PlatformToolset` property determines which MSVC toolset is used in the build. By default, the current toolset is used. When this property is set, its value gets concatenated with literal strings to form the path. It's the directory that contains the property and target files required to build a project for a particular platform. The platform toolset must be installed to build by using that platform toolset version. @@ -82,7 +90,7 @@ For example, set the `PlatformToolset` property to `v140` to use Visual Studio 2 `msbuild myProject.vcxproj /p:PlatformToolset=v140` -### PreferredToolArchitecture property +### `PreferredToolArchitecture` property The `PreferredToolArchitecture` property determines whether the 32-bit or 64-bit compiler and tools are used in the build. This property doesn't affect the output platform architecture or configuration. By default, MSBuild uses the x86 version of the compiler and tools if this property isn't set. @@ -90,47 +98,47 @@ For example, set the `PreferredToolArchitecture` property to `x64` to use the 64 `msbuild myProject.vcxproj /p:PreferredToolArchitecture=x64` -### UseEnv property +### `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` +> `msbuild myProject.vcxproj /p:UseEnv=true` ### Targets -There are hundreds of targets in the Visual Studio support files. However, most are system-oriented targets that the user can ignore. Most system targets are prefixed by an underscore (`_`), or have a name that starts with "PrepareFor", "Compute", "Before", "After", "Pre", or "Post". +There are hundreds of targets in the Visual Studio support files. However, most are system-oriented targets that the user can ignore. Most system targets are prefixed by an underscore (`_`), or have a name that starts with `PrepareFor`, `Compute`, `Before`, `After`, `Pre`, or `Post`. 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 below.* | +| `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 f36cc78211..0000000000 --- a/docs/build/reference/multiple-inline-files.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -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/name-c-cpp.md b/docs/build/reference/name-c-cpp.md index 9b880db05a..32aa228501 100644 --- a/docs/build/reference/name-c-cpp.md +++ b/docs/build/reference/name-c-cpp.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: NAME (C/C++)" title: "NAME (C/C++)" ms.date: "11/04/2016" f1_keywords: ["name"] diff --git a/docs/build/reference/natvis-add-natvis-to-pdb.md b/docs/build/reference/natvis-add-natvis-to-pdb.md index bba231886e..dbc59b4eb0 100644 --- a/docs/build/reference/natvis-add-natvis-to-pdb.md +++ b/docs/build/reference/natvis-add-natvis-to-pdb.md @@ -1,38 +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 **Command Line** property page in the **Linker** folder. +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 cea2b79ca0..d726226b5a 100644 --- a/docs/build/reference/nmake-property-page.md +++ b/docs/build/reference/nmake-property-page.md @@ -1,5 +1,6 @@ --- -title: "NMake Property Page (Windows C++)| Microsoft Docs" +description: "Learn more about: NMake Property Page" +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"] @@ -7,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** @@ -31,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. @@ -41,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** @@ -53,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 05849391e5..18d37d08a5 100644 --- a/docs/build/reference/nmake-reference.md +++ b/docs/build/reference/nmake-reference.md @@ -1,20 +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/noassembly-create-a-msil-module.md b/docs/build/reference/noassembly-create-a-msil-module.md index a4bd213677..c101b214b0 100644 --- a/docs/build/reference/noassembly-create-a-msil-module.md +++ b/docs/build/reference/noassembly-create-a-msil-module.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /NOASSEMBLY (Create a MSIL Module)" title: "/NOASSEMBLY (Create a MSIL Module)" ms.date: "11/04/2016" f1_keywords: ["/NOASSEMBLY", "VC.Project.VCLinkerTool.TurnOffAssemblyGeneration"] @@ -37,9 +38,7 @@ Other linker options that affect assembly generation are: 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 **Advanced** property page. +1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. 1. Modify the **Turn Off Assembly Generation** property. diff --git a/docs/build/reference/nodefaultlib-ignore-libraries.md b/docs/build/reference/nodefaultlib-ignore-libraries.md index 082cb1288e..646e515a1e 100644 --- a/docs/build/reference/nodefaultlib-ignore-libraries.md +++ b/docs/build/reference/nodefaultlib-ignore-libraries.md @@ -1,40 +1,41 @@ --- -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 @@ -42,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/noentry-no-entry-point.md b/docs/build/reference/noentry-no-entry-point.md index dc2e9932c2..8c5afccd3d 100644 --- a/docs/build/reference/noentry-no-entry-point.md +++ b/docs/build/reference/noentry-no-entry-point.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /NOENTRY (No Entry Point)" title: "/NOENTRY (No Entry Point)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCLinkerTool.ResourceOnlyDLL", "/noentry"] @@ -21,9 +22,7 @@ Use this option to prevent LINK from linking a reference to `_main` into the DLL 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. Select the **Advanced** property page. +1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. 1. Modify the **No Entry Point** property. diff --git a/docs/build/reference/nologo-editbin.md b/docs/build/reference/nologo-editbin.md index d0b46e42e4..4ac9a8eff1 100644 --- a/docs/build/reference/nologo-editbin.md +++ b/docs/build/reference/nologo-editbin.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /NOLOGO (EDITBIN)" title: "/NOLOGO (EDITBIN)" ms.date: "11/04/2016" f1_keywords: ["/nologo_editbin"] diff --git a/docs/build/reference/nologo-suppress-startup-banner-c-cpp.md b/docs/build/reference/nologo-suppress-startup-banner-c-cpp.md index 62a3bb4654..df6bf58967 100644 --- a/docs/build/reference/nologo-suppress-startup-banner-c-cpp.md +++ b/docs/build/reference/nologo-suppress-startup-banner-c-cpp.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /nologo (Suppress Startup Banner) (C/C++)" title: "/nologo (Suppress Startup Banner) (C/C++)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCCLWCECompilerTool.SuppressStartupBanner", "VC.Project.VCCLCompilerTool.SuppressStartupBanner"] @@ -21,9 +22,7 @@ Suppresses the display of the copyright banner when the compiler starts up and d 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 **C/C++** folder. - -1. Click the **General** property page. +1. Select the **Configuration Properties** > **C/C++** > **General** property page. 1. Modify the **Suppress Startup Banner** property. diff --git a/docs/build/reference/nologo-suppress-startup-banner-linker.md b/docs/build/reference/nologo-suppress-startup-banner-linker.md index 47b4abbbf1..0076881020 100644 --- a/docs/build/reference/nologo-suppress-startup-banner-linker.md +++ b/docs/build/reference/nologo-suppress-startup-banner-linker.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /NOLOGO (Suppress Startup Banner) (Linker)" title: "/NOLOGO (Suppress Startup Banner) (Linker)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCLinkerTool.SuppressStartupBanner", "/nologo"] diff --git a/docs/build/reference/notification-hooks.md b/docs/build/reference/notification-hooks.md deleted file mode 100644 index d979d9fb71..0000000000 --- a/docs/build/reference/notification-hooks.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: "Notification Hooks" -ms.date: "11/04/2016" -helpviewer_keywords: ["delayed loading of DLLs, notification hooks"] -ms.assetid: e9c291ed-2f2d-4319-a171-09800625256f ---- -# Notification Hooks - -The notification hooks are called just before the following actions are taken in the helper routine: - -- The stored handle to the library is checked to see if it has already been loaded. - -- **LoadLibrary** is called to attempt the load of the DLL. - -- **GetProcAddress** is called to attempt to get the address of the procedure. - -- Return to the delay import load thunk. - -The notification hook is enabled: - -- By supplying a new definition of the pointer **__pfnDliNotifyHook2** that is initialized to point to your own function that receives the notifications. - - \-or- - -- By setting the pointer **__pfnDliNotifyHook2** to your hook function before any calls to the DLL that the program is delay loading. - -If the notification is **dliStartProcessing**, the hook function can return: - -- NULL - - The default helper handles the loading of the DLL. This is useful to be called just for informational purposes. - -- function pointer - - Bypass the default delay-load handling. This lets you supply your own load handler. - -If the notification is **dliNotePreLoadLibrary**, the hook function can return: - -- 0, if it just wants informational notifications. - -- The HMODULE for the loaded DLL, if it loaded the DLL itself. - -If the notification is **dliNotePreGetProcAddress**, the hook function can return: - -- 0, if it just wants informational notifications. - -- The imported function's address, if the hook function gets the address itself. - -If the notification is **dliNoteEndProcessing**, the hook function's return value is ignored. - -If this pointer is initialized (nonzero), the delay load helper will invoke the function at certain notification points throughout its execution. The function pointer has the following definition: - -```C -// The "notify hook" gets called for every call to the -// delay load helper. This allows a user to hook every call and -// skip the delay load helper entirely. -// -// dliNotify == { -// dliStartProcessing | -// dliNotePreLoadLibrary | -// dliNotePreGetProc | -// dliNoteEndProcessing} -// on this call. -// -ExternC -PfnDliHook __pfnDliNotifyHook2; - -// This is the failure hook, dliNotify = {dliFailLoadLib|dliFailGetProc} -ExternC -PfnDliHook __pfnDliFailureHook2; -``` - -The notifications pass in a **DelayLoadInfo** structure to the hook function along with the notification value. This data is identical to that used by the delay load helper routine. The notification value will be one of the values defined in [Structure and Constant Definitions](structure-and-constant-definitions.md). - -## See also - -[Error Handling and Notification](error-handling-and-notification.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 7c58f1d0b0..0000000000 --- a/docs/build/reference/null-and-undefined-macros.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -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/nxcompat.md b/docs/build/reference/nxcompat.md index 685199a4b2..a2c976a255 100644 --- a/docs/build/reference/nxcompat.md +++ b/docs/build/reference/nxcompat.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /NXCOMPAT" title: "/NXCOMPAT" ms.date: "11/04/2016" f1_keywords: ["/NXCOMPAT_editbin"] diff --git a/docs/build/reference/ob-inline-function-expansion.md b/docs/build/reference/ob-inline-function-expansion.md index 3109693abd..6d0e76142f 100644 --- a/docs/build/reference/ob-inline-function-expansion.md +++ b/docs/build/reference/ob-inline-function-expansion.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Ob (Inline Function Expansion)" title: "/Ob (Inline Function Expansion)" ms.date: "08/08/2019" f1_keywords: ["VC.Project.VCCLWCECompilerTool.InlineFunctionExpansion", "VC.Project.VCCLCompilerTool.InlineFunctionExpansion", "/ob"] @@ -11,13 +12,13 @@ Controls inline expansion of functions. By default, when optimizing, expansion o ## Syntax -::: moniker range=">=vs-2019" +::: moniker range=">=msvc-160" > **/Ob**{**0**|**1**|**2**|**3**} ::: moniker-end -::: moniker range="<=vs-2017" +::: moniker range="<=msvc-150" > **/Ob**{**0**|**1**|**2**} @@ -34,7 +35,7 @@ Allows expansion only of functions marked [inline](../../cpp/inline-functions-cp **2**\ The default value under [/O1](o1-o2-minimize-size-maximize-speed.md) and [/O2](o1-o2-minimize-size-maximize-speed.md). Allows the compiler to expand any function not explicitly marked for no inlining. -::: moniker range=">=vs-2019" +::: moniker range=">=msvc-160" **3**\ This option specifies more aggressive inlining than **/Ob2**, but has the same restrictions. The **/Ob3** option is available starting in Visual Studio 2019. @@ -58,7 +59,7 @@ To exclude functions from consideration as candidates for inline expansion, you 1. Modify the **Inline Function Expansion** property. -::: moniker range=">=vs-2019" +::: moniker range=">=msvc-160" The **/Ob3** option isn't available in the **Inline Function Expansion** property. To set **/Ob3**: diff --git a/docs/build/reference/od-disable-debug.md b/docs/build/reference/od-disable-debug.md index 3d08cc627c..d7da05e69c 100644 --- a/docs/build/reference/od-disable-debug.md +++ b/docs/build/reference/od-disable-debug.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Od (Disable (Debug))" title: "/Od (Disable (Debug))" ms.date: "11/04/2016" f1_keywords: ["/od"] @@ -23,9 +24,7 @@ This option is the default. Because **/Od** suppresses code movement, it simplif 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 **C/C++** folder. - -1. Click the **Optimization** property page. +1. Select the **Configuration Properties** > **C/C++** > **Optimization** property page. 1. Modify the **Optimization** property. diff --git a/docs/build/reference/og-global-optimizations.md b/docs/build/reference/og-global-optimizations.md index ca2aa06046..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 7dd167fadf..6903538cac 100644 --- a/docs/build/reference/oi-generate-intrinsic-functions.md +++ b/docs/build/reference/oi-generate-intrinsic-functions.md @@ -1,9 +1,9 @@ --- +description: "Learn more about: /Oi (Generate Intrinsic Functions)" 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) @@ -17,39 +17,34 @@ 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** +You can use [intrinsic](../../preprocessor/intrinsic.md) to create intrinsic functions, or [function (C/C++)](../../preprocessor/function-c-cpp.md) to explicitly force a function call. -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. +### x86-specific remarks -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. +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. -**END x86 Specific** +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 also use [intrinsic](../../preprocessor/intrinsic.md) to create intrinsic functions, or [function (C/C++)](../../preprocessor/function-c-cpp.md) to explicitly force a function call. - -### To set this compiler option in the Visual Studio development environment +## 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. Click the **C/C++** folder. - -1. Click the **Optimization** property page. - +1. Select the **Configuration Properties** > **C/C++** > **Optimization** property page. 1. Modify the **Enable Intrinsic Functions** property. -### To set this compiler option programmatically +## To set this compiler option programmatically - See . ## 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 d1ce9c8d2b..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,51 +1,57 @@ --- +description: "Learn more about: /openmp (Enable OpenMP Support)" title: "/openmp (Enable OpenMP Support)" -ms.date: "04/15/2019" -f1_keywords: ["/openmp", "VC.Project.VCCLCompilerTool.OpenMP"] -helpviewer_keywords: ["/openmp compiler option [C++]", "-openmp compiler option [C++]"] -ms.assetid: 9082b175-18d3-4378-86a7-c0eb95664e13 +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++]"] --- -# /openmp (Enable OpenMP Support) +# `/openmp` (Enable OpenMP Support) Causes the compiler to process [`#pragma omp`](../../preprocessor/omp.md) directives in support of OpenMP. ## Syntax -::: moniker range=">= vs-2019" +::: moniker range=">= msvc-160" -> **/openmp**\[**:**__experimental__] +> **`/openmp`**\ +> **`/openmp:experimental`**\ +> **`/openmp:llvm`** ::: moniker-end -::: moniker range="<= vs-2017" +::: moniker range="<= msvc-150" -> **/openmp** +> **`/openmp`** ::: moniker-end ## Remarks -`#pragma omp` is used to specify [Directives](../../parallel/openmp/reference/openmp-directives.md) and [Clauses](../../parallel/openmp/reference/openmp-clauses.md). If **/openmp** isn't specified in a compilation, the compiler ignores OpenMP clauses and directives. [OpenMP Function](../../parallel/openmp/reference/openmp-functions.md) calls are processed by the compiler even if **/openmp** isn't specified. +`#pragma omp` is used to specify [Directives](../../parallel/openmp/reference/openmp-directives.md) and [Clauses](../../parallel/openmp/reference/openmp-clauses.md). If **`/openmp`** isn't specified in a compilation, the compiler ignores OpenMP clauses and directives. [OpenMP Function](../../parallel/openmp/reference/openmp-functions.md) calls are processed by the compiler even if **`/openmp`** isn't specified. -::: moniker range=">= vs-2019" +::: 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 additional 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/). + +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 -Applications compiled by using both **/openmp** and **/clr** can only be run in a single application domain process. Multiple application domains aren't supported. That is, when the module constructor (`.cctor`) is run, it detects if the process is compiled using **/openmp**, and if the app is loaded into a non-default runtime. For more information, see [appdomain](../../cpp/appdomain.md), [/clr (Common Language Runtime Compilation)](clr-common-language-runtime-compilation.md), and [Initialization of Mixed Assemblies](../../dotnet/initialization-of-mixed-assemblies.md). +Applications compiled by using both **`/openmp`** and **`/clr`** can only be run in a single application domain process. Multiple application domains aren't supported. That is, when the module constructor (`.cctor`) is run, it detects if the process is compiled using **`/openmp`**, and if the app is loaded into a non-default runtime. For more information, see [`appdomain`](../../cpp/appdomain.md), [`/clr` (Common Language Runtime Compilation)](clr-common-language-runtime-compilation.md), and [Initialization of Mixed Assemblies](../../dotnet/initialization-of-mixed-assemblies.md). -If you attempt to load an app compiled using both **/openmp** and **/clr** into a non-default application domain, a exception is thrown outside the debugger, and a `OpenMPWithMultipleAppdomainsException` exception is thrown in the debugger. +If you attempt to load an app compiled using both **`/openmp`** and **`/clr`** into a non-default application domain, a exception is thrown outside the debugger, and a `OpenMPWithMultipleAppdomainsException` exception is thrown in the debugger. These exceptions can also be raised in the following situations: -- If your application is compiled using **/clr** but not **/openmp**, and is loaded into a non-default application domain, where the process includes an app compiled using **/openmp**. +- If your application is compiled using **`/clr`** but not **`/openmp`**, and is loaded into a non-default application domain, where the process includes an app compiled using **`/openmp`**. -- If you pass your **/clr** app to a utility, such as [regasm.exe](/dotnet/framework/tools/regasm-exe-assembly-registration-tool), which loads its target assemblies into a non-default application domain. +- If you pass your **`/clr`** app to a utility, such as [regasm.exe](/dotnet/framework/tools/regasm-exe-assembly-registration-tool), which loads its target assemblies into a non-default application domain. The common language runtime's code access security doesn't work in OpenMP regions. If you apply a CLR code access security attribute outside a parallel region, it won't be in effect in the parallel region. -Microsoft doesn't recommend that you write **/openmp** apps that allow partially trusted callers. Don't use , or any CLR code access security attributes. +Microsoft doesn't recommend that you write **`/openmp`** apps that allow partially trusted callers. Don't use , or any CLR code access security attributes. ### To set this compiler option in the Visual Studio development environment @@ -63,9 +69,9 @@ Microsoft doesn't recommend that you write **/openmp** apps that allow partially The following sample shows some of the effects of thread pool startup versus using the thread pool after it has started. Assuming an x64, single core, dual processor, the thread pool takes about 16 ms to start up. After that, there's little extra cost for the thread pool. -When you compile using **/openmp**, the second call to test2 never runs any longer than if you compile using **/openmp-**, as there's no thread pool startup. At a million iterations, the **/openmp** version is faster than the **/openmp-** version for the second call to test2. At 25 iterations, both **/openmp-** and **/openmp** versions register less than the clock granularity. +When you compile using **`/openmp`**, the second call to test2 never runs any longer than if you compile using **`/openmp-`**, as there's no thread pool startup. At a million iterations, the **`/openmp`** version is faster than the **`/openmp-`** version for the second call to test2. At 25 iterations, both **`/openmp-`** and **`/openmp`** versions register less than the clock granularity. -If you have only one loop in your application and it runs in less than 15 ms (adjusted for the approximate overhead on your machine), **/openmp** may not be appropriate. If it's higher, you may want to consider using **/openmp**. +If you have only one loop in your application and it runs in less than 15 ms (adjusted for the approximate overhead on your machine), **`/openmp`** may not be appropriate. If it's higher, you may want to consider using **`/openmp`**. ```cpp // cpp_compiler_options_openmp.cpp @@ -113,6 +119,6 @@ int main(int argc, char* argv[]) { ## 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) \ [OpenMP in MSVC](../../parallel/openmp/openmp-in-visual-cpp.md) diff --git a/docs/build/reference/opt-optimizations.md b/docs/build/reference/opt-optimizations.md index fdbf048808..e02850e624 100644 --- a/docs/build/reference/opt-optimizations.md +++ b/docs/build/reference/opt-optimizations.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /OPT (Optimizations)" title: "/OPT (Optimizations)" ms.date: "05/18/2018" f1_keywords: ["VC.Project.VCLinkerTool.OptimizeReferences", "/opt", "VC.Project.VCLinkerTool.OptimizeForWindows98", "VC.Project.VCLinkerTool.EnableCOMDATFolding", "VC.Project.VCLinkerTool.OptimizeFolding", "VC.Project.VCLinkerTool.FoldingIterations", "VC.Project.VCLinkerTool.OptimizeFoldingIterations"] @@ -11,13 +12,13 @@ Controls the optimizations that LINK performs during a build. ## Syntax -> **/OPT:**{**REF** | **NOREF**}\ -> **/OPT:**{**ICF**[**=**_iterations_] | **NOICF**}\ -> **/OPT:**{**LBR** | **NOLBR**} +> **/OPT:**{**REF** \| **NOREF**}\ +> **/OPT:**{**ICF**\[**=**_iterations_] \| **NOICF**}\ +> **/OPT:**{**LBR** \| **NOLBR**} ## 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. @@ -29,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. @@ -40,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/order-of-cl-options.md b/docs/build/reference/order-of-cl-options.md index 96ca2fd4e1..de662be868 100644 --- a/docs/build/reference/order-of-cl-options.md +++ b/docs/build/reference/order-of-cl-options.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Order of CL Options" title: "Order of CL Options (C++) - Visual Studio" ms.date: "12/14/2018" helpviewer_keywords: ["cl.exe compiler, setting options"] diff --git a/docs/build/reference/order-put-functions-in-order.md b/docs/build/reference/order-put-functions-in-order.md index 3598c1a372..de6ac64e77 100644 --- a/docs/build/reference/order-put-functions-in-order.md +++ b/docs/build/reference/order-put-functions-in-order.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /ORDER (Put Functions in Order)" title: "/ORDER (Put Functions in Order)" ms.date: "09/05/2018" f1_keywords: ["VC.Project.VCLinkerTool.FunctionOrder", "/order"] 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/other-lib-output.md b/docs/build/reference/other-lib-output.md index 51487dd297..a95bc83aab 100644 --- a/docs/build/reference/other-lib-output.md +++ b/docs/build/reference/other-lib-output.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Other LIB Output" title: "Other LIB Output" ms.date: "11/04/2016" helpviewer_keywords: ["output files, LIB"] diff --git a/docs/build/reference/out-dumpbin.md b/docs/build/reference/out-dumpbin.md index 062c4b66d9..6e25352a73 100644 --- a/docs/build/reference/out-dumpbin.md +++ b/docs/build/reference/out-dumpbin.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /OUT (DUMPBIN)" title: "/OUT (DUMPBIN)" ms.date: "11/04/2016" f1_keywords: ["/out_dumpbin"] diff --git a/docs/build/reference/out-output-file-name.md b/docs/build/reference/out-output-file-name.md index 36d9290d37..f671586c63 100644 --- a/docs/build/reference/out-output-file-name.md +++ b/docs/build/reference/out-output-file-name.md @@ -1,36 +1,32 @@ --- +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 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 **General** property page. +1. Select the **Configuration Properties** > **Linker** > **General** property page. 1. Modify the **Output File** property. @@ -40,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/output-file-f-options.md b/docs/build/reference/output-file-f-options.md index f3b985808a..601eba50f4 100644 --- a/docs/build/reference/output-file-f-options.md +++ b/docs/build/reference/output-file-f-options.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Output-File (/F) Options" title: "Output-File (-F) Options" ms.date: "11/04/2016" helpviewer_keywords: ["output files", "output files, compiler options [C++]", "cl.exe compiler, output files"] diff --git a/docs/build/reference/oy-frame-pointer-omission.md b/docs/build/reference/oy-frame-pointer-omission.md index 53cf381a51..17094ba141 100644 --- a/docs/build/reference/oy-frame-pointer-omission.md +++ b/docs/build/reference/oy-frame-pointer-omission.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Oy (Frame-Pointer Omission)" title: "/Oy (Frame-Pointer Omission)" ms.date: "11/19/2018" f1_keywords: ["VC.Project.VCCLCompilerTool.OmitFramePointers", "/oy"] diff --git a/docs/build/reference/p-preprocess-to-a-file.md b/docs/build/reference/p-preprocess-to-a-file.md index f1829f9a14..3f8c51279b 100644 --- a/docs/build/reference/p-preprocess-to-a-file.md +++ b/docs/build/reference/p-preprocess-to-a-file.md @@ -1,9 +1,9 @@ --- title: "/P (Preprocess to a File)" -ms.date: "11/04/2016" +description: "Learn more about: /P (Preprocess to a File)" +ms.date: 11/04/2016 f1_keywords: ["VC.Project.VCCLCompilerTool.GeneratePreprocessedFile", "/p", "VC.Project.VCCLWCECompilerTool.GeneratePreprocessedFile"] helpviewer_keywords: ["/P compiler option [C++]", "-P compiler option [C++]", "P compiler option [C++]", "output files, preprocessor", "preprocessing output files"] -ms.assetid: 123ee54f-8219-4a6f-9876-4227023d83fc --- # /P (Preprocess to a File) @@ -27,9 +27,7 @@ The **/P** option suppresses compilation. It does not produce an .obj file, even 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 **C/C++** folder. - -1. Click the **Preprocessor** property page. +1. Select the **Configuration Properties** > **C/C++** > **Preprocessor** property page. 1. Modify the **Generate Preprocessed File** property. @@ -41,7 +39,7 @@ The **/P** option suppresses compilation. It does not produce an .obj file, even The following command line preprocesses `ADD.C`, preserves comments, adds `#line` directives, and writes the result to a file, `ADD.I`: -``` +```cmd CL /P /C ADD.C ``` diff --git a/docs/build/reference/para-visual-cpp.md b/docs/build/reference/para-visual-cpp.md index 90b4940c47..e9b4e2dbcb 100644 --- a/docs/build/reference/para-visual-cpp.md +++ b/docs/build/reference/para-visual-cpp.md @@ -1,33 +1,34 @@ --- -title: "<para>" -ms.date: "11/04/2016" -f1_keywords: ["", "para"] +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 72dd59972d..3f11c6ab64 100644 --- a/docs/build/reference/param-visual-cpp.md +++ b/docs/build/reference/param-visual-cpp.md @@ -1,33 +1,34 @@ --- -title: "<param> (C++ documentation comments)" -ms.date: "11/04/2016" -f1_keywords: ["param", ""] +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 @@ -45,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 ac3171b942..1ff58d4850 100644 --- a/docs/build/reference/paramref-visual-cpp.md +++ b/docs/build/reference/paramref-visual-cpp.md @@ -1,28 +1,29 @@ --- -title: "<paramref> (C++ documentation comments)" -ms.date: "11/04/2016" -f1_keywords: ["paramref", ""] +title: " (C++ documentation comments)" +description: "Learn more about the paramref C++ XML documentation tag." +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 @@ -41,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/pdata.md b/docs/build/reference/pdata.md index 8c37b6b38d..085b0f48a3 100644 --- a/docs/build/reference/pdata.md +++ b/docs/build/reference/pdata.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /PDATA" title: "/PDATA" ms.date: "11/04/2016" f1_keywords: ["/pdata"] diff --git a/docs/build/reference/pdb-use-program-database.md b/docs/build/reference/pdb-use-program-database.md index efde10c681..9d61dad7b1 100644 --- a/docs/build/reference/pdb-use-program-database.md +++ b/docs/build/reference/pdb-use-program-database.md @@ -1,39 +1,37 @@ --- 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. Click the **Linker** folder. - -1. Click the **Debug** property page. - +1. Select the **Configuration Properties** > **Linker** > **Debug** property page. 1. Modify the **Generate Program Database File** property. ### To set this linker option programmatically @@ -42,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 8e45bb5e9e..6c198f7815 100644 --- a/docs/build/reference/pdbaltpath-use-alternate-pdb-path.md +++ b/docs/build/reference/pdbaltpath-use-alternate-pdb-path.md @@ -1,28 +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 48a667c970..b88420f081 100644 --- a/docs/build/reference/pdbpath.md +++ b/docs/build/reference/pdbpath.md @@ -1,11 +1,11 @@ --- +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 @@ -13,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/pdbstripped-strip-private-symbols.md b/docs/build/reference/pdbstripped-strip-private-symbols.md index d8a2eaf229..fd93071a85 100644 --- a/docs/build/reference/pdbstripped-strip-private-symbols.md +++ b/docs/build/reference/pdbstripped-strip-private-symbols.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /PDBSTRIPPED (Strip Private Symbols)" title: "/PDBSTRIPPED (Strip Private Symbols)" ms.date: "11/04/2016" f1_keywords: ["/pdbstripped", "VC.Project.VCLinkerTool.StripPrivateSymbols"] @@ -42,9 +43,7 @@ If you do not create a PDB file, /PDBSTRIPPED is ignored. 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 **Debug** property page. +1. Select the **Configuration Properties** > **Linker** > **Debug** property page. 1. Modify the **Strip Private Symbols** property. diff --git a/docs/build/reference/permission-visual-cpp.md b/docs/build/reference/permission-visual-cpp.md index 676ec9f95c..007e807a83 100644 --- a/docs/build/reference/permission-visual-cpp.md +++ b/docs/build/reference/permission-visual-cpp.md @@ -1,37 +1,38 @@ --- -title: "<permission> (C++ documentation comments)" -ms.date: "11/04/2016" -f1_keywords: ["permission", ""] +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 @@ -49,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 6a486c10bc..3a182cb84d 100644 --- a/docs/build/reference/permissive-standards-conformance.md +++ b/docs/build/reference/permissive-standards-conformance.md @@ -1,44 +1,48 @@ --- title: "/permissive- (Standards conformance)" description: "Reference guide to the Microsoft C++ /permissive- (Standards conformance) compiler option." -ms.date: "06/04/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. ## Syntax -> **`/permissive-`** +> **`/permissive-`**\ +> **`/permissive`** ## Remarks -This option is supported in Visual Studio 2017 and later. +The **`/permissive-`** option is supported in Visual Studio 2017 and later. **`/permissive`** is supported in Visual Studio 2019 version 16.8 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. +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++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. + +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. The **`/permissive-`** option is compatible with almost all of the header files from the latest Windows Kits, such as the Software Development Kit (SDK) or Windows Driver Kit (WDK), starting in the Windows Fall Creators SDK (10.0.16299.0). Older versions of the SDK may fail to compile under **`/permissive-`** for various source code conformance reasons. The compiler and SDKs ship on different release timelines, so there are some remaining issues. For specific header file issues, see [Windows header issues](#windows-header-issues) below. -The **`/permissive-`** option sets the [**`/Zc:referenceBinding`**](zc-referencebinding-enforce-reference-binding-rules.md), [**`/Zc:strictStrings`**](zc-strictstrings-disable-string-literal-type-conversion.md), and [**`/Zc:rvalueCast`**](zc-rvaluecast-enforce-type-conversion-rules.md) options to conforming behavior. These options defaults to non-conforming behavior. You can pass specific **`/Zc`** options after **`/permissive-`** on the command line to override this behavior. +The **`/permissive-`** option sets the [`/Zc:referenceBinding`](zc-referencebinding-enforce-reference-binding-rules.md), [`/Zc:strictStrings`](zc-strictstrings-disable-string-literal-type-conversion.md), and [`/Zc:rvalueCast`](zc-rvaluecast-enforce-type-conversion-rules.md) options to conforming behavior. These options default to non-conforming behavior. You can pass specific **`/Zc`** options after **`/permissive-`** on the command line to override this behavior. -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. +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. -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. +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. -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. +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 @@ -49,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(); } ``` @@ -100,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 { @@ -112,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 { @@ -126,6 +152,8 @@ void g() { } ``` +You can enable the hidden friend name lookup rules independently of **`/permissive`** by using [`/Zc:hiddenFriend`](./zc-hiddenfriend.md). If you want legacy behavior for hidden friend name lookup, but otherwise want **`/permissive-`** behavior, use the **`/Zc:hiddenFriend-`** option. + #### Use scoped enums in array bounds ```cpp @@ -153,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 @@ -161,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]; @@ -182,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 @@ -236,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 @@ -256,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 @@ -277,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 @@ -338,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 @@ -347,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' @@ -355,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 @@ -364,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' @@ -380,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 @@ -404,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 7b6b333200..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,13 +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 @@ -15,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). @@ -40,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/pogosafemode-linker-option.md b/docs/build/reference/pogosafemode-linker-option.md index da45b2bd66..2019c0b736 100644 --- a/docs/build/reference/pogosafemode-linker-option.md +++ b/docs/build/reference/pogosafemode-linker-option.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /POGOSAFEMODE (Run PGO in thread safe mode)" title: "/POGOSAFEMODE (Run PGO in thread safe mode)" ms.date: "03/14/2018" f1_keywords: ["POGOSAFEMODE"] 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 c18d579120..0000000000 --- a/docs/build/reference/precedence-in-inference-rules.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -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 9abb1b5545..0000000000 --- a/docs/build/reference/precedence-in-macro-definitions.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -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 631d405443..0000000000 --- a/docs/build/reference/predefined-rules.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -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 9c6cca772f..bff93bcfd7 100644 --- a/docs/build/reference/profile-performance-tools-profiler.md +++ b/docs/build/reference/profile-performance-tools-profiler.md @@ -1,45 +1,41 @@ --- title: "/PROFILE (Performance Tools Profiler)" -ms.date: "11/04/2016" +description: "Learn more about: /PROFILE (Performance Tools Profiler)" +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](/cpp/code-quality/code-analysis-for-c-cpp-overview). +- [`/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 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. Expand the **Configuration Properties** node. - -1. Expand the **Linker** node. - -1. Select the **Advanced** property page. +1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. 1. Modify the **Profile** property. @@ -47,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 +## 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/project-and-solution-files.md b/docs/build/reference/project-and-solution-files.md index 4b8794a887..2b281ac46b 100644 --- a/docs/build/reference/project-and-solution-files.md +++ b/docs/build/reference/project-and-solution-files.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Project and Solution Files" title: "Project and Solution Files" ms.date: "05/06/2019" helpviewer_keywords: ["project files [C++]", "file types [C++], makefiles", ".sdf, browsing database file", "Makefile projects", "browsing database file, .sdf", "file types [C++], project files"] diff --git a/docs/build/reference/project-files.md b/docs/build/reference/project-files.md index 5be74af37f..6f2317c51b 100644 --- a/docs/build/reference/project-files.md +++ b/docs/build/reference/project-files.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Project Files" title: "Example Project File" ms.date: "08/19/2019" helpviewer_keywords: [".vcxproj files", "C++ projects, project file format"] @@ -10,13 +11,13 @@ A C++ project file in Visual Studio is an XML-based file that has the .vcxproj f ## Example -::: moniker range=">=vs-2019" +::: moniker range=">=msvc-160" The following sample .vcxproj file was produced by choosing **Windows Desktop Wizard** in the **New Project** dialog box. To process a project file use either the msbuild.exe tool at the command line, or the **Build** command in the IDE. (This sample cannot be processed because the required source and header files are not provided.) For more information about the XML elements in a project file, see [Project File Schema Reference](/visualstudio/msbuild/msbuild-project-file-schema-reference). ::: moniker-end -::: moniker range="<=vs-2017" +::: moniker range="<=msvc-150" The following sample .vcxproj file was produced by specifying a **Win32 Console Application** in the **New Project** dialog box. To process a project file use either the msbuild.exe tool at the command line, or the **Build** command in the IDE. (This sample cannot be processed because the required source and header files are not provided.) For more information about the XML elements in a project file, see [Project File Schema Reference](/visualstudio/msbuild/msbuild-project-file-schema-reference). diff --git a/docs/build/reference/property-page-xml-files.md b/docs/build/reference/property-page-xml-files.md index a2b0a27766..b7d32df9fb 100644 --- a/docs/build/reference/property-page-xml-files.md +++ b/docs/build/reference/property-page-xml-files.md @@ -1,24 +1,47 @@ --- title: "Property Page XML rule files" -ms.date: "05/06/2019" +description: "Description of the Visual Studio IDE C++ property page XML rule files and contents." +ms.date: 10/14/2020 helpviewer_keywords: ["property page XML files"] -ms.assetid: dd9d9734-4387-4098-8ba6-85b93507731d --- # Property Page XML rule files -The project property pages in the IDE are configured by XML files in the VCTargets folder. The exact path depends on which edition(s) of Visual Studio are installed, and the product language. For Visual Studio 2019 Enterprise Edition, in English, the path is `%ProgramFiles%\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\VC\VCTargets\1033`. The XML files describe the names of the rules, the categories, and the individual properties, their data type, default values, and how they are to be displayed. When you set a property in the IDE, the new value is stored in the project file. +The project property pages in the IDE are configured by XML files in the default rules folder. The XML files describe the names of the rules, the categories, and the individual properties, their data type, default values, and how to display them. When you set a property in the IDE, the new value is stored in the project file. -The only scenarios in which you need to understand the internal workings of these files and the Visual Studio IDE are (a) you want to create a custom property page, or (b) you want to customize your project properties by some means other than through the Visual Studio IDE. +::: moniker range="msvc-140" -First, let's open the property pages for a project (right click on the project node in **Solution Explorer** and choose Properties): +The path to the default rules folder depends on the locale and the version of Visual Studio in use. In a Visual Studio 2015 or earlier developer command prompt, the rules folder is *`%ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\\`*. The `` value is *`v140`* in Visual Studio 2015. The `` is an LCID, for example, `1033` for English. You'll use a different path for each edition of Visual Studio that's installed, and for each language. For example, the default rules folder path for Visual Studio 2015 Community edition in English could be *`C:\Program Files (x86)\MSBuild\Microsoft.Cpp\v4.0\v140\1033\`*. -![Visual Studio C++ Project Properties](../media/cpp-property-page-2017.png) +::: moniker-end -Each node under **Configuration Properties** is called a Rule. A Rule sometimes represents a single tool like the compiler, but 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 VCTargets folder. For example, the C/C++ rule that is shown above is populated by `cl.xml'. +::: moniker range="msvc-150" -As shown above, 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 themselves are rendered in a grid format on the right pane. +The path to the default rules folder depends on the locale and the version of Visual Studio in use. In a Visual Studio 2017 developer command prompt, the rules folder is *`%VSINSTALLDIR%Common7\IDE\VC\VCTargets\\`*. The `` is an LCID, for example, `1033` for English. In a Visual Studio 2015 or earlier developer command prompt, the rules folder is *`%ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\\\`*, where the `` value is *`v140`* in Visual Studio 2015. You'll use a different path for each edition of Visual Studio that's installed, and for each language. For example, the default rules folder path for Visual Studio 2017 Community edition in English could be *`C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\Common7\IDE\VC\VCTargets\1033\`*. -You can open cl.xml in notepad or any XML editor (see snapshot below). You will see a root node called Rule that has the same list of properties defined under it as is displayed in the UI, along with additional metadata. +::: moniker-end + +::: moniker range=">=msvc-160" + +The path to the default rules folder depends on the locale and the version of Visual Studio in use. In a Visual Studio 2019 or later developer command prompt, the rules folder is *`%VSINSTALLDIR%MSBuild\Microsoft\VC\\\`*, where the `` value is *`v160`* in Visual Studio 2019. The `` is an LCID, for example, `1033` for English. In Visual Studio 2017, the rules folder is *`%VSINSTALLDIR%Common7\IDE\VC\VCTargets\\`*. In a Visual Studio 2015 or earlier developer command prompt, the rules folder is *`%ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\\\`*. You'll use a different path for each edition of Visual Studio that's installed, and for each language. For example, the default rules folder path for Visual Studio 2019 Community edition in English could be *`C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\MSBuild\Microsoft\VC\v160\1033\`*. + +::: moniker-end + +You only need to understand the internal workings of these files and the Visual Studio IDE in a couple of scenarios: + +- You want to create a custom property page, or +- You want to customize your project properties without use of the Visual Studio IDE. + +## Contents of rule files + +First, let's open the property pages for a project. Right-click on the project node in **Solution Explorer** and choose **Properties**: + +![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 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. + +You can open *`cl.xml`* in notepad or any XML editor. You'll see a root node called `Rule`. It defines the same list of properties that get displayed in the UI, along with additional metadata. ```xml @@ -37,16 +60,17 @@ You can open cl.xml in notepad or any XML editor (see snapshot below). You will -... + + ``` -There is one XML file corresponding to every node under Configuration Properties in the property pages UI. You can add or remove rules in the UI by including or removing locations to corresponding XML files in the project. For example, this is how Microsoft.CppBuild.targets (one level up from the 1033 folder) includes cl.xml: +There's one XML file for every node under **Configuration Properties** in the property pages UI. You can add or remove rules in the UI: it's done by including or removing locations to corresponding XML files in the project. For example, it's how *`Microsoft.CppBuild.targets`* (found one level higher than the 1033 folder) includes *`cl.xml`*: ```xml ``` -If you strip cl.xml of all data, you will end up with the following skeleton: +If you strip *`cl.xml`* of all data, you have this basic framework: ```xml @@ -54,7 +78,7 @@ If you strip cl.xml of all data, you will end up with the following skeleton: - ... + @@ -64,109 +88,115 @@ If you strip cl.xml of all data, you will end up with the following skeleton: ``` -The following section describes each major elements and some of the metadata that can be attached to them. +The next section describes each major element and some of the metadata that you can attach. -1. **Rule:** Rule is generally the root node in the xml file; it can have many attributes: +### Rule attributes - ```xml - - - C/C++ - - ``` +A **``** element is the root node in the XML file. It can have many attributes: - a. **Name:** The Name attribute is an id for the Rule. It needs to be unique among all the property page xml files for a project. +```xml + + + C/C++ + +``` - b. **PageTemplate:** The value of this attribute is used by the UI to choose from a collection of UI templates. The "tool" template renders the properties in a standard grid format. Other in-built values for this attribute are "debugger" and "generic". See the Debugging node and General node, respectively, to see the UI format resulting from specifying these values. The UI for "debugger" page template uses a drop-down box to switch between the properties of different debuggers whereas the "generic" template displays different property categories all in one page as opposed to having multiple category sub-nodes under the Rule node. This attribute is just a suggestion to the UI; the xml file is designed to be UI independent. A different UI might use this attribute for different purposes. +- **`Name`**: The Name attribute is an ID for the `Rule`. It needs to be unique among all the property page XML files for a project. - c. **SwitchPrefix:** This is the prefix used in the command line for the switches. A value of "/" would result in switches that look like /ZI, /nologo, /W3, etc. +- **`PageTemplate`**: The value of this attribute is used by the UI to choose from a collection of UI templates. The "tool" template renders the properties in a standard grid format. Other in-built values for this attribute are "debugger" and "generic". See the Debugging node and General node, respectively, to see the UI format resulting from specifying these values. The UI for "debugger" page template uses a drop-down box to switch between the properties of different debuggers. The "generic" template displays different property categories all in one page, as opposed to having multiple category sub-nodes under the `Rule` node. This attribute is just a suggestion to the UI. The XML file is designed to be UI independent. A different UI might use this attribute for different purposes. - d. **Order:** This is a suggestion to a prospective UI client on the relative location of this Rule compared to all other Rules in the system. +- **`SwitchPrefix`**: The prefix used in the command line for the switches. A value of `"/"` would result in switches that look like **`/ZI`**, **`/nologo`**, **`/W3`**, and so on. - e. **xmlns:** This is a standard XAML element. You can see three namespaces listed. These correspond to the namespaces for the XAML deserialization classes, XAML schema and system namespace, respectively. +- **`Order`**: A suggestion to a prospective UI client on the relative location of this `Rule` compared to all other rules in the system. - f. **DisplayName:** This is the name that is shown on the property page UI for the Rule node. This value is localized. We created DisplayName as a child element of Rule rather than as an attribute (like Name or SwitchPrefix) because of internal localization tool requirements. From XAML's perspective, both are equivalent. So, you can just make it an attribute to reduce clutter or leave it as it is. +- **`xmlns`**: A standard XML element. You can see three namespaces listed. These attributes correspond to the namespaces for the XML deserialization classes, XML schema, and system namespace, respectively. - g. **DataSource:** This is a very important property that tells the project system the location from which the property value should read from and written to, and its grouping (explained below). For cl.xml, these values are: +- **`DisplayName`**: The name that's shown on the property page UI for the `Rule` node. This value is localized. We created `DisplayName` as a child element of `Rule` rather than as an attribute (like `Name` or `SwitchPrefix`) because of internal localization tool requirements. From an XML perspective, both are equivalent. So, you can just make it an attribute to reduce clutter or leave it as it is. - ```xml - - ``` +- **`DataSource`**: This important property tells the project system the location to read and write the property value, and its grouping (explained later). For *`cl.xml`*, these values are: - - `Persistence="ProjectFile` tells the project system that all properties for the Rule should be written to the project file or the property sheet file (depending on which node was used to spawn the property pages). The other possible value is "UserFile" which will write the value to the .user file. + ```xml + + ``` + + - `Persistence="ProjectFile"` tells the project system that all properties for the `Rule` should be written to the project file or the property sheet file (depending on which node was used to spawn the property pages). The other possible value is `"UserFile"`, which will write the value to the *`.user`* file. - - `ItemType="ClCompile"` says that the properties will be stored as ItemDefinition metadata or item metadata (the latter only if the property pages were spawned from a file node in solution explorer) of this item type. If this field is not set, then the property is written as a common property in a PropertyGroup. + - `ItemType="ClCompile"` says that the properties will be stored as ItemDefinition metadata or item metadata (the latter only if the property pages were spawned from a file node in solution explorer) of this item type. If this field isn't set, then the property is written as a common property in a PropertyGroup. - - `Label=""` indicates that when the properties are written as `ItemDefinition` metadata, the label of the parent ItemDefinitionGroup will be empty (every MSBuild element can have a Label). Visual Studio 2017 and later use labeled groups to navigate the .vcxproj project file. Note that the groups that contain most Rule properties have an empty string as a label. + - `Label=""` indicates that when the properties are written as `ItemDefinition` metadata, the label of the parent ItemDefinitionGroup will be empty (every MSBuild element can have a Label). Visual Studio 2017 and later use labeled groups to navigate the .vcxproj project file. The groups that contain most `Rule` properties have an empty string as a label. - - `HasConfigurationCondition="true"` tells the project system to affix a configuration condition to the value so that it takes effect only for the current project configuration (the condition could be affixed to the parent group or the value itself). For example, open the property pages off the project node and set the value of the property **Treat Warnings As Error** under **Configuration Properties > C/C++ General** to "Yes". The following value is written to the project file. Notice the configuration condition attached to the parent ItemDefinitionGroup. + - `HasConfigurationCondition="true"` tells the project system to affix a configuration condition to the value so that it takes effect only for the current project configuration (the condition could be affixed to the parent group or the value itself). For example, open the property pages off the project node and set the value of the property **Treat Warnings As Error** under **Configuration Properties > C/C++ General** to "Yes". The following value is written to the project file. Notice the configuration condition attached to the parent ItemDefinitionGroup. - ```xml - - - true - - - ``` + ```xml + + + true + + + ``` - If this value were set in the property page for a specific file, such as stdafx.cpp, then the property value would be written under the *stdafx.cpp* item in the project file as shown below. Notice how the configuration condition is directly attached to the metadata itself. + If this value is set in the property page for a specific file, such as *`stdafx.cpp`*, then the property value should be written under the `stdafx.cpp` item in the project file as shown Here. Notice how the configuration condition is directly attached to the metadata itself: - ```xml - - - true - - - ``` + ```xml + + + true + + + ``` - Another attribute of **DataSource** not listed above is **PersistedName**. You can use this attribute to represent a property in the project file using a different name. By default this attribute is set to the property's **Name**. + Another attribute of `DataSource` not listed here is `PersistedName`. You can use this attribute to represent a property in the project file using a different name. By default, this attribute is set to the property's `Name`. - An individual property can override its parent Rule's DataSource. In that case, the location for that property's value will be different from other properties in the Rule. + An individual property can override the `DataSource` of its parent `Rule`. In that case, the location for that property's value will be different from other properties in the `Rule`. - h. There are other attributes of a Rule, including Description and SupportsFileBatching, that are not shown here. The full set of attributes applicable to a Rule or on any other element can be obtained by browsing the documentation for these types. Alternately, you can examine the public properties on the types in the `Microsoft.Build.Framework.XamlTypes` namespace in the `Microsoft.Build.Framework .dll` assembly. +- There are other attributes of a `Rule`, including `Description` and `SupportsFileBatching`, that aren't shown here. The full set of attributes applicable to a `Rule` or on any other element can be obtained by browsing the documentation for these types. Alternately, you can examine the public properties on the types in the `Microsoft.Build.Framework.XamlTypes` namespace in the `Microsoft.Build.Framework.dll` assembly. - i. **DisplayName**, **PageTemplate**, and **Order** are UI-related properties that are present in this otherwise UI-independent data model. These properties are almost certain to be used by any UI that is used to display the property pages. **DisplayName** and **Description** are two properties that are present on almost all elements in the xml file. And these are the only two properties that are localized (localization of these strings will be explained in a later post). +- **`DisplayName`**, **`PageTemplate`**, and **`Order`** are UI-related properties that are present in this otherwise UI-independent data model. These properties are almost certain to be used by any UI that is used to display the property pages. `DisplayName` and `Description` are two properties that are present on almost all elements in the XML file. And, these two properties are the only ones that are localized. -1. **Category:** A Rule can have multiple Categories. The order in which the categories are listed in the xml file is a suggestion to the UI to display the categories in the same order. For example, the order of the categories under the C/C++ node as seen in the UI –General, Optimization, Preprocessor, … – is the same as that in cl.xml. A sample category looks like this: +### Category elements - ```xml - - - Optimization - - - ``` +A `Rule` can have multiple `Category` elements. The order in which the categories are listed in the XML file is a suggestion to the UI to display the categories in the same order. For example, the order of the categories under the **C/C++** node you see in the UI is the same as the order in *`cl.xml`*. A sample category looks like this: - The above snippet shows the **Name** and **DisplayName** attributes that have been described before. Once again, there are other attributes a **Category** can have that are not used above. You can know about them by reading the documentation or by examining the assemblies using ildasm.exe. +```xml + + + Optimization + + +``` -1. **Properties:** This is the meat of the xml file and contains the list of all properties in this Rule. Each property can be one of five possible types shown in the XAML skeleton above. Of course, you could have only a few of those types in your file. A property has a number of attributes that allow it to be described richly. I'll explain only the **StringProperty** here. The rest are very similar. +This snippet shows the `Name` and `DisplayName` attributes that have been described before. Once again, there are other attributes a `Category` can have that aren't shown in the example. You can learn about them by reading the documentation or by examining the assemblies using *`ildasm.exe`*. - ```xml - - - Object File Name - - - Specifies a name to override the default object file name; can be file or directory name.(/Fo[name]) - - - ``` +### Property elements + +Most of the rule file consists of `Property` elements. They contain the list of all properties in a `Rule`. Each property can be one of the five possible types shown in the basic framework: `BoolProperty`, `EnumProperty`, `IntProperty`, `StringProperty`, and `StringListProperty`. You might have only a few of those types in your file. A property has a number of attributes that allow it to be described in detail. The `StringProperty` is described here. The rest are similar. + +```xml + + + Object File Name + + + Specifies a name to override the default object file name; can be file or directory name.(/Fo[name]) + + +``` - Most of the attributes in the snippet have been described before. The new ones are Subtype, Category and Switch. +Most of the attributes in the snippet have been described before. The new ones are `Subtype`, `Category`, and `Switch`. - a. **Subtype** is an attribute available only for **StringProperty** and **StringListProperty**; it gives contextual information. For example, the value of "file" indicates that the property represents a file path. Such contextual information is used to enhance the editing experience by providing a Windows Explorer as the property's editor that allows the user to choose the file visually. +- **`Subtype`** is an attribute available only for `StringProperty` and `StringListProperty` elements. It gives contextual information. For example, the value `file` indicates that the property represents a file path. Visual Studio uses such contextual information to enhance the editing experience. For instance, it may provide a Windows Explorer window that allows the user to choose the file visually as the property's editor. - b. **Category:** This declares the category under which this property falls. Try to find this property under the **Output Files** category in the UI. +- **`Category`**: The category under which this property falls. Try to find this property under the **Output Files** category in the UI. - c. **Switch:** When a Rule represents a tool – such as the compiler tool in this case – most properties of the Rule are passed as switches to the tool executable during build time. The value of this attribute indicates the switch literal to be used. The property above specifies that its switch should be **Fo**. Combined with the **SwitchPrefix** attribute on the parent Rule, this property is passed to the executable as **/Fo"Debug\"** (visible in the command line for C/C++ in the property page UI). +- **`Switch`**: When a rule represents a tool such as the compiler tool, most `Rule` properties get passed as switches to the tool executable at build time. The value of this attribute indicates which switch literal to use. The `` example specifies that its switch should be **`Fo`**. Combined with the `SwitchPrefix` attribute on the parent `Rule`, this property is passed to the executable as **`/Fo"Debug\"`**. It's visible in the command line for C/C++ in the property page UI. Other property attributes include: - d. **Visible:** If for some reason, you don't want your property to show up in the property pages (but probably still available during build time), set this attribute to false. +- **`Visible`**: If you don't want your property to appear in the property pages, but want it available at build time, set this attribute to `false`. - e. **ReadOnly:** If you want to provide a read-only view of this property's value in the property pages, set this attribute to true. +- **`ReadOnly`**: If you want to provide a read-only view of this property's value in the property pages, set this attribute to `true`. - f. **IncludeInCommandLine:** Some properties may not need to be passed to a tool during build time. Setting this attribute to false will prevent it from being passed. +- **`IncludeInCommandLine`**: At build time, a tool might not need some of its properties. Set this attribute to `false` to prevent a particular property from being passed. diff --git a/docs/build/reference/property-pages-visual-cpp.md b/docs/build/reference/property-pages-visual-cpp.md index 7df73d41ec..a265d2aaf9 100644 --- a/docs/build/reference/property-pages-visual-cpp.md +++ b/docs/build/reference/property-pages-visual-cpp.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Windows C++ project property page reference" title: "Windows C++ project property page reference - Visual Studio" ms.date: "08/28/2019" helpviewer_keywords: ["project-file macro", "project properties [C++], default values", "user-defined values", "project properties [C++], setting", "macros, project-file", "property pages, project settings", "C++ projects, properties", "build macro", "user-defined macros"] @@ -8,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/q-options-low-level-operations.md b/docs/build/reference/q-options-low-level-operations.md index 364a3ebb74..e0d11fdbbf 100644 --- a/docs/build/reference/q-options-low-level-operations.md +++ b/docs/build/reference/q-options-low-level-operations.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Q Options (Low-Level Operations)" title: "/Q Options (Low-Level Operations)" ms.date: "01/08/2020" f1_keywords: ["/q"] diff --git a/docs/build/reference/qfast-transcendentals-force-fast-transcendentals.md b/docs/build/reference/qfast-transcendentals-force-fast-transcendentals.md index 9ca0ec2c4c..4cff2b6e29 100644 --- a/docs/build/reference/qfast-transcendentals-force-fast-transcendentals.md +++ b/docs/build/reference/qfast-transcendentals-force-fast-transcendentals.md @@ -1,33 +1,30 @@ --- -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 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 **C/C++** folder. - -1. Click the **Command Line** property page. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. 1. Type the compiler option in the **Additional Options** box. @@ -37,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/qifist-suppress-ftol.md b/docs/build/reference/qifist-suppress-ftol.md index d716bf9e60..d6194caced 100644 --- a/docs/build/reference/qifist-suppress-ftol.md +++ b/docs/build/reference/qifist-suppress-ftol.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /QIfist (Suppress _ftol)" title: "/QIfist (Suppress _ftol)" ms.date: "11/04/2016" f1_keywords: ["/qifist"] @@ -43,9 +44,7 @@ The **/QIfist** option is deprecated starting in Visual Studio 2005. The compile 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 **C/C++** folder. - -1. Click the **Command Line** property page. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. 1. Type the compiler option in the **Additional Options** box. diff --git a/docs/build/reference/qimprecise-fwaits-remove-fwaits-inside-try-blocks.md b/docs/build/reference/qimprecise-fwaits-remove-fwaits-inside-try-blocks.md index a10e5dd521..35674c106f 100644 --- a/docs/build/reference/qimprecise-fwaits-remove-fwaits-inside-try-blocks.md +++ b/docs/build/reference/qimprecise-fwaits-remove-fwaits-inside-try-blocks.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Qimprecise_fwaits (Remove fwaits Inside Try Blocks)" title: "/Qimprecise_fwaits (Remove fwaits Inside Try Blocks)" ms.date: "11/04/2016" f1_keywords: ["/Qimprecise_fwaits"] @@ -17,17 +18,15 @@ Removes the `fwait` commands internal to **`try`** blocks when you use the [/fp: ## Remarks -This option has no effect if **/fp:except** is not also specified. If you specify the **/fp:except** option, the compiler will insert a `fwait` command around each line of code in a **`try`** block. In this way, the compiler can identify the specific line of code that produces an exception. **/Qimprecise_fwaits** removes internal `fwait` instructions, leaving only the waits around the **`try`** block. This improves performance, but the compiler will only be able to say which **`try`** block causes an exception, not which line. +This option has no effect if **`/fp:except`** isn't also specified. If you specify the **`/fp:except`** option, the compiler will insert a `fwait` instruction around each line of code in a **`try`** block. In this way, the compiler can identify the specific line of code that produces an exception. **`/Qimprecise_fwaits`** removes internal `fwait` instructions, leaving only the waits around the **`try`** block. It improves performance, but the compiler can only show which **`try`** block causes an exception, not which line. ### 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. Click the **C/C++** folder. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Click the **Command Line** property page. - -1. Type the compiler option in the **Additional Options** box. +1. Enter the compiler option in the **Additional Options** box. ### To set this compiler option programmatically diff --git a/docs/build/reference/qintel-jcc-erratum.md b/docs/build/reference/qintel-jcc-erratum.md index 97b364fcf6..ca538af7a6 100644 --- a/docs/build/reference/qintel-jcc-erratum.md +++ b/docs/build/reference/qintel-jcc-erratum.md @@ -7,13 +7,13 @@ helpviewer_keywords: ["/QIntel-jcc-erratum", "-QIntel-jcc-erratum"] --- # /QIntel-jcc-erratum -::: moniker range="<=vs-2017" +::: moniker range="<=msvc-150" The **/QIntel-jcc-erratum** option is available in Visual Studio 2019 version 16.5 and later. ::: moniker-end -::: moniker range=">=vs-2019" +::: moniker range=">=msvc-160" Specifies that the compiler generates instructions to mitigate the performance impact caused by the Intel Jump Conditional Code (JCC) erratum microcode update in certain Intel processors. diff --git a/docs/build/reference/qpar-auto-parallelizer.md b/docs/build/reference/qpar-auto-parallelizer.md index e3f60c05f1..37cedc2517 100644 --- a/docs/build/reference/qpar-auto-parallelizer.md +++ b/docs/build/reference/qpar-auto-parallelizer.md @@ -1,44 +1,43 @@ --- -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. In **Solution Explorer**, open the shortcut menu for the project and then choose **Properties**. +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. In the **Property Pages** dialog box, under **C/C++**, select **Command Line**. +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)
-[Native code vectorization in Visual Studio](https://docs.microsoft.com/archive/blogs/nativeconcurrency/auto-vectorizer-in-visual-studio-2012-overview) +[`/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/qpar-report-auto-parallelizer-reporting-level.md b/docs/build/reference/qpar-report-auto-parallelizer-reporting-level.md index 21e37f5d7d..fe1b300d9d 100644 --- a/docs/build/reference/qpar-report-auto-parallelizer-reporting-level.md +++ b/docs/build/reference/qpar-report-auto-parallelizer-reporting-level.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Qpar-report (Auto-Parallelizer Reporting Level)" title: "/Qpar-report (Auto-Parallelizer Reporting Level)" ms.date: "11/04/2016" ms.assetid: 562673b9-02da-4bf8-bb64-70bc25ef4651 @@ -27,9 +28,9 @@ Messages are reported to stdout. If no informational messages are reported, then 1. In **Solution Explorer**, open the shortcut menu for the project and then choose **Properties**. -1. In the **Property Pages** dialog box, under **C/C++**, select **Command Line**. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. In the **Additional Options** box, enter `/Qpar-report:1` or `/Qpar-report:2`. +1. In the **Additional Options** box, enter *`/Qpar-report:1`* or *`/Qpar-report:2`*. ### To set the /Qpar-report compiler option programmatically @@ -40,4 +41,4 @@ Messages are reported to stdout. If no informational messages are reported, then [/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)
-[Native code vectorization in Visual Studio](https://docs.microsoft.com/archive/blogs/nativeconcurrency/auto-vectorizer-in-visual-studio-2012-overview) +[Native code vectorization in Visual Studio](/archive/blogs/nativeconcurrency/auto-vectorizer-in-visual-studio-2012-overview) diff --git a/docs/build/reference/qsafe-fp-loads.md b/docs/build/reference/qsafe-fp-loads.md index f56fd1346c..367010aa09 100644 --- a/docs/build/reference/qsafe-fp-loads.md +++ b/docs/build/reference/qsafe-fp-loads.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Qsafe_fp_loads" title: "/Qsafe_fp_loads" ms.date: "01/24/2018" --- 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 1418658974..2eace5222a 100644 --- a/docs/build/reference/qspectre.md +++ b/docs/build/reference/qspectre.md @@ -1,26 +1,29 @@ --- 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**. @@ -29,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="vs-2019" +::: 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). @@ -73,13 +114,17 @@ For more information, see the official [Microsoft Security Advisory ADV180002, G ::: moniker-end -::: moniker range="<=vs-2017" +::: 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 @@ -89,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/qvec-report-auto-vectorizer-reporting-level.md b/docs/build/reference/qvec-report-auto-vectorizer-reporting-level.md index e44f796e8e..860d52ec1e 100644 --- a/docs/build/reference/qvec-report-auto-vectorizer-reporting-level.md +++ b/docs/build/reference/qvec-report-auto-vectorizer-reporting-level.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Qvec-report (Auto-Vectorizer Reporting Level)" title: "/Qvec-report (Auto-Vectorizer Reporting Level)" ms.date: "11/04/2016" ms.assetid: 4778c9a3-0692-4085-9b05-1bfeadf4c74a @@ -25,11 +26,11 @@ For information about reason codes and messages, see [Vectorizer and Parallelize ### To set the /Qvec-report compiler option in Visual Studio -1. In **Solution Explorer**, open the shortcut menu for the project and then choose **Properties**. +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. In the **Property Pages** dialog box, under **C/C++**, select **Command Line**. +1. Select the **Configuration Properties** > **C/C++** > **Code Generation** property page. -1. In the **Additional Options** box, enter `/Qvec-report:1` or `/Qvec-report:2`. +1. In the **Additional Options** box, enter *`/Qvec-report:1`* or *`/Qvec-report:2`*. ### To set the /Qvec-report compiler option programmatically @@ -40,4 +41,4 @@ For information about reason codes and messages, see [Vectorizer and Parallelize [/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)
-[Native code vectorization in Visual Studio](https://docs.microsoft.com/archive/blogs/nativeconcurrency/auto-vectorizer-in-visual-studio-2012-overview) +[Native code vectorization in Visual Studio](/archive/blogs/nativeconcurrency/auto-vectorizer-in-visual-studio-2012-overview) diff --git a/docs/build/reference/range.md b/docs/build/reference/range.md index f95a885f86..298b3d9a42 100644 --- a/docs/build/reference/range.md +++ b/docs/build/reference/range.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /RANGE" title: "/RANGE" ms.date: "11/04/2016" f1_keywords: ["/RANGE"] diff --git a/docs/build/reference/rawdata.md b/docs/build/reference/rawdata.md index f30d3704dc..1ce3fbbdec 100644 --- a/docs/build/reference/rawdata.md +++ b/docs/build/reference/rawdata.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /RAWDATA" title: "/RAWDATA" ms.date: "11/04/2016" f1_keywords: ["/rawdata"] diff --git a/docs/build/reference/rebase.md b/docs/build/reference/rebase.md index 5ce6ab7263..c5f64e2a85 100644 --- a/docs/build/reference/rebase.md +++ b/docs/build/reference/rebase.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /REBASE" title: "/REBASE" ms.date: "11/04/2016" f1_keywords: ["/rebase"] 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 6679b6399c..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,34 +1,43 @@ --- -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)| -|[\](value-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/release-set-the-checksum.md b/docs/build/reference/release-set-the-checksum.md index 8fe28f25e7..ce0b560413 100644 --- a/docs/build/reference/release-set-the-checksum.md +++ b/docs/build/reference/release-set-the-checksum.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /RELEASE (Set the Checksum)" title: "/RELEASE (Set the Checksum)" ms.date: "11/04/2016" f1_keywords: ["/release", "VC.Project.VCLinkerTool.SetChecksum"] diff --git a/docs/build/reference/release.md b/docs/build/reference/release.md index 3a9f99f60a..1e5213c4ae 100644 --- a/docs/build/reference/release.md +++ b/docs/build/reference/release.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /RELEASE" title: "/RELEASE" ms.date: "11/04/2016" f1_keywords: ["/release_editbin"] diff --git a/docs/build/reference/relocations.md b/docs/build/reference/relocations.md index abb5efc561..d68f671b26 100644 --- a/docs/build/reference/relocations.md +++ b/docs/build/reference/relocations.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /RELOCATIONS" title: "/RELOCATIONS" ms.date: "11/04/2016" f1_keywords: ["/relocations"] diff --git a/docs/build/reference/remarks-visual-cpp.md b/docs/build/reference/remarks-visual-cpp.md index 462d9730c8..0c455a623e 100644 --- a/docs/build/reference/remarks-visual-cpp.md +++ b/docs/build/reference/remarks-visual-cpp.md @@ -1,28 +1,29 @@ --- -title: "<remarks> (C++ documentation comments)" -ms.date: "11/04/2016" -f1_keywords: ["remarks", ""] +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 @@ -44,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/reserved-words.md b/docs/build/reference/reserved-words.md index 6509cb5962..eeae921831 100644 --- a/docs/build/reference/reserved-words.md +++ b/docs/build/reference/reserved-words.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Reserved words" title: "Reserved words" ms.date: "11/04/2016" f1_keywords: ["code", "CONFORMING", "DISCARDABLE", "Description", "base", "APPLOADER", "Data", "DYNAMIC", "DEV386"] @@ -9,28 +10,75 @@ ms.assetid: 9b9f49e5-0739-45ab-a37e-81e3915ceb25 The following words are reserved by the linker. These names can be used as arguments in [module-definition statements](module-definition-dot-def-files.md) only if the name is enclosed in double quotation marks (""). -|||| -|-|-|-| -|**APPLOADER**1|**INITINSTANCE**2|**PRELOAD**| -|**BASE**|**IOPL**|**PRIVATE**| -|**CODE**|**LIBRARY**1|**PROTMODE**2| -|**CONFORMING**|**LOADONCALL**1|**PURE**1| -|**DATA**|**LONGNAMES**2|**READONLY**| -|**DESCRIPTION**|**MOVABLE**1|**READWRITE**| -|**DEV386**|**MOVEABLE**1|**REALMODE**1| -|**DISCARDABLE**|**MULTIPLE**|**RESIDENT**| -|**DYNAMIC**|**NAME**|**RESIDENTNAME**1| -|**EXECUTE-ONLY**|**NEWFILES**2|**SECTIONS**| -|**EXECUTEONLY**|**NODATA**1|**SEGMENTS**| -|**EXECUTEREAD**|**NOIOPL**1|**SHARED**| -|**EXETYPE**|**NONAME**|**SINGLE**| -|**EXPORTS**|**NONCONFORMING**1|**STACKSIZE**| -|**FIXED**1|**NONDISCARDABLE**|**STUB**| -|**FUNCTIONS**2|**NONE**|**VERSION**| -|**HEAPSIZE**|**NONSHARED**|**WINDOWAPI**| -|**IMPORTS**|**NOTWINDOWCOMPAT**1|**WINDOWCOMPAT**| -|**IMPURE**1|**OBJECTS**|**WINDOWS**| -|**INCLUDE**2|**OLD**1|| +:::row::: + :::column span=""::: + **`APPLOADER`**1\ + **`BASE`**\ + **`CODE`**\ + **`CONFORMING`**\ + **`DATA`**\ + **`DESCRIPTION`**\ + **`DEV386`**\ + **`DISCARDABLE`**\ + **`DYNAMIC`**\ + **`EXECUTE-ONLY`**\ + **`EXECUTEONLY`**\ + **`EXECUTEREAD`**\ + **`EXETYPE`**\ + **`EXPORTS`**\ + **`FIXED`**1 + :::column-end::: + :::column span=""::: + **`FUNCTIONS`**2\ + **`HEAPSIZE`**\ + **`IMPORTS`**\ + **`IMPURE`**1\ + **`INCLUDE`**2\ + **`INITINSTANCE`**2\ + **`IOPL`**\ + **`LIBRARY`**1\ + **`LOADONCALL`**1\ + **`LONGNAMES`**2\ + **`MOVABLE`**1\ + **`MOVEABLE`**1\ + **`MULTIPLE`**\ + **`NAME`**\ + **`NEWFILES`**2 + :::column-end::: + :::column span=""::: + **`NODATA`**1\ + **`NOIOPL`**1\ + **`NONAME`**\ + **`NONCONFORMING`**1\ + **`NONDISCARDABLE`**\ + **`NONE`**\ + **`NONSHARED`**\ + **`NOTWINDOWCOMPAT`**1\ + **`OBJECTS`**\ + **`OLD`**1\ + **`PRELOAD`**\ + **`PRIVATE`**\ + **`PROTMODE`**2\ + **`PURE`**1\ + **`READONLY`** + :::column-end::: + :::column span=""::: + **`READWRITE`**\ + **`REALMODE`**1\ + **`RESIDENT`**\ + **`RESIDENTNAME`**1\ + **`SECTIONS`**\ + **`SEGMENTS`**\ + **`SHARED`**\ + **`SINGLE`**\ + **`STACKSIZE`**\ + **`STUB`**\ + **`VERSION`**\ + **`WINDOWAPI`**\ + **`WINDOWCOMPAT`**\ + **`WINDOWS`** + :::column-end::: +:::row-end::: 1 The linker emits a warning ("ignored") when it encounters this term. However, the word is still reserved. diff --git a/docs/build/reference/resource-files-cpp.md b/docs/build/reference/resource-files-cpp.md index 5a9ecd0297..c93d831a45 100644 --- a/docs/build/reference/resource-files-cpp.md +++ b/docs/build/reference/resource-files-cpp.md @@ -1,10 +1,11 @@ --- -title: "Resource Files (C++)" +description: "Learn more about: Project Resource Files (C++)" +title: "Project Resource Files (C++)" ms.date: "05/14/2019" helpviewer_keywords: ["resource files", "resources [C++]"] ms.assetid: 338a4a0f-0c62-4ef1-a34f-5d86262d93a4 --- -# Resource Files (C++) +# Project Resource Files (C++) Resources are interface elements that provide information to the user. Bitmaps, icons, toolbars, and cursors are all resources. Some resources can perform an action such as selecting from a menu or entering data in dialog box. diff --git a/docs/build/reference/resources-property-pages.md b/docs/build/reference/resources-property-pages.md index 7931818c40..cea6e5ba33 100644 --- a/docs/build/reference/resources-property-pages.md +++ b/docs/build/reference/resources-property-pages.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Resources property page" title: "Resources" ms.date: "08/28/2019" ms.topic: "article" @@ -13,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 89822031e0..26806b0ec0 100644 --- a/docs/build/reference/return-value-of-cl-exe.md +++ b/docs/build/reference/return-value-of-cl-exe.md @@ -1,8 +1,8 @@ --- title: "Return Value of cl.exe" -ms.date: "09/05/2018" +description: "Learn more about: Return Value of cl.exe" +ms.date: 09/05/2018 helpviewer_keywords: ["cl.exe compiler, return value"] -ms.assetid: 7c2d7f33-ee0d-4199-8ef4-75fe2b007670 --- # Return Value of cl.exe @@ -10,9 +10,9 @@ 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](https://docs.microsoft.com/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). +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). ## Remarks diff --git a/docs/build/reference/returns-visual-cpp.md b/docs/build/reference/returns-visual-cpp.md index 51691ee65a..9ed2a4ee6d 100644 --- a/docs/build/reference/returns-visual-cpp.md +++ b/docs/build/reference/returns-visual-cpp.md @@ -1,28 +1,29 @@ --- -title: "<returns> (C++ Documentation Comments)" -ms.date: "11/04/2016" -f1_keywords: ["returns", ""] +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 @@ -41,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 9def77e6d8..0000000000 --- a/docs/build/reference/reusing-inline-files.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -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/rtc-run-time-error-checks.md b/docs/build/reference/rtc-run-time-error-checks.md index 8dbe37ed61..265e61d945 100644 --- a/docs/build/reference/rtc-run-time-error-checks.md +++ b/docs/build/reference/rtc-run-time-error-checks.md @@ -1,5 +1,6 @@ --- title: "/RTC (Run-time error checks)" +description: "The Microsoft C/C++ compiler /RTC options for run-time error checks." ms.date: 07/31/2020 f1_keywords: ["/rtc", "VC.Project.VCCLCompilerTool.SmallerTypeCheck", "VC.Project.VCCLCompilerTool.UninitializedVariableCheck", "VC.Project.VCCLCompilerTool.StackFrameCheck", "VC.Project.VCCLCompilerTool.BasicRuntimeChecks"] helpviewer_keywords: ["/RTCs compiler option [C++]", "-RTC1 compiler option [C++]", "run-time errors, error checks", "-RTCu compiler option [C++]", "/RTC1 compiler option [C++]", "/RTCc compiler option [C++]", "/RTCu compiler option [C++]", "__MSVC_RUNTIME_CHECKS macro", "-RTCs compiler option [C++]", "RTCs compiler option", "RTC1 compiler option", "run-time errors, run-time checks", "run-time checks, /RTC option", "RTCu compiler option", "RTCc compiler option", "-RTCc compiler option [C++]"] @@ -82,7 +83,7 @@ The `__MSVC_RUNTIME_CHECKS` preprocessor directive will be defined when you use 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. Select the **Configuration Properties** > **C/C++** > **Code Generation** property page. 1. Modify one or both of the following properties: **Basic Runtime Checks** or **Smaller Type Check**. diff --git a/docs/build/reference/rules-for-module-definition-statements.md b/docs/build/reference/rules-for-module-definition-statements.md index 267660ed51..5b8cf86931 100644 --- a/docs/build/reference/rules-for-module-definition-statements.md +++ b/docs/build/reference/rules-for-module-definition-statements.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Rules for Module-Definition Statements" title: "Rules for Module-Definition Statements" ms.date: "11/04/2016" f1_keywords: [".def"] 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 31509f529a..e9633b59a9 100644 --- a/docs/build/reference/running-nmake.md +++ b/docs/build/reference/running-nmake.md @@ -1,65 +1,66 @@ --- title: "Running NMAKE" -description: "Reference guide to the Microsoft NMAKE command-line options." -ms.date: "02/09/2020" +description: "Learn about running NMAKE." +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 08230f2d05..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,33 +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 */ @@ -88,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 @@ -102,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 6511a32ed3..911eecd6cb 100644 --- a/docs/build/reference/sample-makefile.md +++ b/docs/build/reference/sample-makefile.md @@ -1,7 +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 @@ -11,7 +11,7 @@ This topic contains a sample makefile. ### Code -``` +```makefile # Sample makefile !include @@ -30,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/sdl-enable-additional-security-checks.md b/docs/build/reference/sdl-enable-additional-security-checks.md index e176a0bc20..63e7af5fa4 100644 --- a/docs/build/reference/sdl-enable-additional-security-checks.md +++ b/docs/build/reference/sdl-enable-additional-security-checks.md @@ -1,12 +1,13 @@ --- title: "/sdl (Enable Additional Security Checks)" -ms.date: "11/26/2018" +description: "The Microsoft C/C++ compiler /sdl option enables recommended Security Development Lifecycle (SDL) checks and warnings." +ms.date: 10/02/2020 f1_keywords: ["VC.Project.VCCLCompilerTool.SDLCheck"] ms.assetid: 3dcf86a0-3169-4240-9f29-e04a9f535826 --- # /sdl (Enable Additional Security Checks) -Adds recommended Security Development Lifecycle (SDL) checks. These checks include extra security-relevant warnings as errors, and additional secure code-generation features. +Enables recommended Security Development Lifecycle (SDL) checks. These checks change security-relevant warnings into errors, and set additional secure code-generation features. ## Syntax @@ -16,53 +17,51 @@ Adds recommended Security Development Lifecycle (SDL) checks. These checks inclu **/sdl** enables a superset of the baseline security checks provided by [`/GS`](gs-buffer-security-check.md) and overrides **`/GS-`**. By default, **`/sdl`** is off. **`/sdl-`** disables the additional security checks. -## Compile-time Checks +### Compile-time Checks **`/sdl`** enables these warnings as errors: -|Warning enabled by /sdl|Equivalent command-line switch|Description| -|------------------------------|-------------------------------------|-----------------| -|[C4146](../../error-messages/compiler-warnings/compiler-warning-level-2-c4146.md)|/we4146|A unary minus operator was applied to an unsigned type, resulting in an unsigned result.| -|[C4308](../../error-messages/compiler-warnings/compiler-warning-level-2-c4308.md)|/we4308|A negative integral constant converted to unsigned type, resulting in a possibly meaningless result.| -|[C4532](../../error-messages/compiler-warnings/compiler-warning-level-1-c4532.md)|/we4532|Use of `continue`, `break` or `goto` keywords in a `__finally`/`finally` block has undefined behavior during abnormal termination.| -|[C4533](../../error-messages/compiler-warnings/compiler-warning-level-1-c4533.md)|/we4533|Code initializing a variable will not be executed.| -|[C4700](../../error-messages/compiler-warnings/compiler-warning-level-1-and-level-4-c4700.md)|/we4700|Use of an uninitialized local variable.| -|[C4703](../../error-messages/compiler-warnings/compiler-warning-level-4-c4703.md)|/we4703|Use of a potentially uninitialized local pointer variable.| -|[C4789](../../error-messages/compiler-warnings/compiler-warning-level-1-c4789.md)|/we4789|Buffer overrun when specific C run-time (CRT) functions are used.| -|[C4995](../../error-messages/compiler-warnings/compiler-warning-level-3-c4995.md)|/we4995|Use of a function marked with pragma [`deprecated`](../../preprocessor/deprecated-c-cpp.md).| -|[C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md)|/we4996|Use of a function marked as [`deprecated`](../../cpp/deprecated-cpp.md).| +| Warning enabled by /sdl | Equivalent command-line switch | Description | +|--|--|--| +| [C4146](../../error-messages/compiler-warnings/compiler-warning-level-2-c4146.md) | /we4146 | A unary minus operator was applied to an unsigned type, resulting in an unsigned result. | +| [C4308](../../error-messages/compiler-warnings/compiler-warning-level-2-c4308.md) | /we4308 | A negative integral constant converted to unsigned type, resulting in a possibly meaningless result. | +| [C4532](../../error-messages/compiler-warnings/compiler-warning-level-1-c4532.md) | /we4532 | Use of `continue`, `break`, or `goto` keywords in a `__finally`/`finally` block has undefined behavior during abnormal termination. | +| [C4533](../../error-messages/compiler-warnings/compiler-warning-level-1-c4533.md) | /we4533 | Code initializing a variable will not be executed. | +| [C4700](../../error-messages/compiler-warnings/compiler-warning-level-1-and-level-4-c4700.md) | /we4700 | Use of an uninitialized local variable. | +| [C4703](../../error-messages/compiler-warnings/compiler-warning-level-4-c4703.md) | /we4703 | Use of a potentially uninitialized local pointer variable. | +| [C4789](../../error-messages/compiler-warnings/compiler-warning-level-1-c4789.md) | /we4789 | Buffer overrun when specific C run-time (CRT) functions are used. | +| [C4995](../../error-messages/compiler-warnings/compiler-warning-level-3-c4995.md) | /we4995 | Use of a function marked with pragma [`deprecated`](../../preprocessor/deprecated-c-cpp.md). | +| [C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md) | /we4996 | Use of a function marked as [`deprecated`](../../cpp/deprecated-cpp.md). | -## Runtime checks +### Runtime checks -When **`/sdl`** is enabled, the compiler generates code to perform these checks at run time: +When **`/sdl`** is enabled, the compiler generates code that does these checks at run time: - Enables the strict mode of **`/GS`** run-time buffer overrun detection, equivalent to compiling with `#pragma strict_gs_check(push, on)`. -- Performs limited pointer sanitization. In expressions that do not involve dereferences and in types that have no user-defined destructor, pointer references are set to a non-valid address after a call to **`delete`**. This helps to prevent the reuse of stale pointer references. +- Does limited pointer sanitization. In expressions that don't involve dereferences and in types that have no user-defined destructor, pointer references are set to a non-valid address after a call to **`delete`**. This sanitization helps to prevent the reuse of stale pointer references. -- Performs class member pointer initialization. Automatically initializes class members of pointer type to **`nullptr`** on object instantiation (before the constructor runs). This helps prevent the use of uninitialized pointers that the constructor does not explicitly initialize. The compiler-generated member pointer initialization is called as long as: +- Initializes class member pointers. Automatically initializes class members of pointer type to **`nullptr`** on object instantiation (before the constructor runs). It helps prevent the use of uninitialized pointers that the constructor doesn't explicitly initialize. The compiler-generated member pointer initialization is called as long as: - - The object is not allocated using a custom (user defined) `operator new` + - The object isn't allocated using a custom (user defined) `operator new` - - The object is not allocated as part of an array (for example `new A[x]`) + - The object isn't allocated as part of an array (for example `new A[x]`) - - The class is not managed or imported + - The class isn't managed or imported - The class has a user-defined default constructor. To be initialized by the compiler-generated class initialization function, a member must be a pointer, and not a property or constant. -## Remarks - -For more information, see [Warnings, /sdl, and improving uninitialized variable detection](https://cloudblogs.microsoft.com/microsoftsecure/2012/06/06/warnings-sdl-and-improving-uninitialized-variable-detection/). +For more information, see [Warnings, /sdl, and improving uninitialized variable detection](https://www.microsoft.com/security/blog/2012/06/06/warnings-sdl-and-improving-uninitialized-variable-detection/). -#### To set this compiler option in the Visual Studio development environment +### 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 **C/C++** folder. +1. Select the **Configuration Properties** > **C/C++** > **General** property page. -1. On the **General** page, select the option from the **SDL checks** drop-down list. +1. Set the **SDL checks** property by using the property drop-down control. Choose **OK** or **Apply** to save your changes. ## See also 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 fa9ae100d3..0000000000 --- a/docs/build/reference/search-paths-in-rules.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -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-dumpbin.md b/docs/build/reference/section-dumpbin.md index 130443e207..16fb9cbc25 100644 --- a/docs/build/reference/section-dumpbin.md +++ b/docs/build/reference/section-dumpbin.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /SECTION (DUMPBIN)" title: "/SECTION (DUMPBIN)" ms.date: "11/04/2016" f1_keywords: ["/section_dumpbin"] diff --git a/docs/build/reference/section-editbin.md b/docs/build/reference/section-editbin.md index b956f2973e..e476fed5d0 100644 --- a/docs/build/reference/section-editbin.md +++ b/docs/build/reference/section-editbin.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /SECTION (EDITBIN)" title: "/SECTION (EDITBIN)" ms.date: "11/04/2016" f1_keywords: ["/section_editbin"] diff --git a/docs/build/reference/section-specify-section-attributes.md b/docs/build/reference/section-specify-section-attributes.md index 9e53c30aa6..c994dd4799 100644 --- a/docs/build/reference/section-specify-section-attributes.md +++ b/docs/build/reference/section-specify-section-attributes.md @@ -1,78 +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 @@ -80,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/sections-c-cpp.md b/docs/build/reference/sections-c-cpp.md index 15e3d1ef9b..42f7ecf1c8 100644 --- a/docs/build/reference/sections-c-cpp.md +++ b/docs/build/reference/sections-c-cpp.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: SECTIONS (C/C++)" title: "SECTIONS (C/C++)" ms.date: "11/04/2016" f1_keywords: ["SECTIONS"] diff --git a/docs/build/reference/see-visual-cpp.md b/docs/build/reference/see-visual-cpp.md index 9b1ceab5e1..1118029155 100644 --- a/docs/build/reference/see-visual-cpp.md +++ b/docs/build/reference/see-visual-cpp.md @@ -1,38 +1,39 @@ --- -title: "<see> (C++ Documentation Comments)" -ms.date: "11/04/2016" -f1_keywords: ["", "see"] +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 @@ -61,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 1f93520e46..317e154d8b 100644 --- a/docs/build/reference/seealso-visual-cpp.md +++ b/docs/build/reference/seealso-visual-cpp.md @@ -1,40 +1,41 @@ --- -title: "<seealso> (C++ Documentation Comments)" -ms.date: "11/04/2016" -f1_keywords: ["", "seealso"] +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 @@ -60,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 a146a89699..ced65322f7 100644 --- a/docs/build/reference/showincludes-list-include-files.md +++ b/docs/build/reference/showincludes-list-include-files.md @@ -1,46 +1,40 @@ --- -title: "/showIncludes (List Include Files)" -ms.date: "11/04/2016" +description: "Learn more about: /showIncludes (List include files)" +title: "/showIncludes (List include files)" +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++]"] -ms.assetid: 0b74b052-f594-45a6-a7c7-09e1a319547d --- -# /showIncludes (List Include Files) +# `/showIncludes` (List include files) -Causes the compiler to output a list of the include files. Nested include files are also displayed (files that are included from the files that you include). +Causes the compiler to output a list of the include files. The option also displays nested include files, that is, the files included by the files that you include. ## Syntax -``` -/showIncludes -``` +> **`/showIncludes`** ## Remarks -When an include file is encountered during compilation, a message is output, for example: +When the compiler comes to an include file during compilation, a message is output, as in this example: -``` +```cmd Note: including file: d:\MyDir\include\stdio.h ``` -Nested include files are indicated by an indentation, one space for each level of nesting, for example: +Nested include files are indicated by an indentation, one space for each level of nesting, as in this example: -``` +```cmd Note: including file: d:\temp\1.h Note: including file: d:\temp\2.h ``` -In this case, `2.h` was included from within `1.h`, hence the indentation. - -The **/showIncludes** option emits to `stderr`, not `stdout`. +In this case, *`2.h`* was included from within *`1.h`*, causing the indentation. ### 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. Click the **C/C++** folder. - -1. Click the **Advanced** property page. +1. Select the **Configuration Properties** > **C/C++** > **Advanced** property page. 1. Modify the **Show Includes** property. @@ -50,5 +44,5 @@ The **/showIncludes** option emits to `stderr`, not `stdout`. ## 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/source-charset-set-source-character-set.md b/docs/build/reference/source-charset-set-source-character-set.md index 09e6e110fe..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,52 +1,51 @@ --- -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 **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 details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). -1. Expand the **Configuration Properties**, **C/C++**, **Command Line** folder. +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 new file mode 100644 index 0000000000..25cfd5f192 --- /dev/null +++ b/docs/build/reference/sourcedependencies-directives.md @@ -0,0 +1,112 @@ +--- +title: "/sourceDependencies:directives (List module and header unit dependencies)" +description: "Reference guide to the /sourceDependencies:directives compiler option in Microsoft C++." +ms.date: 05/19/2022 +author: "tylermsft" +ms.author: "twhitney" +f1_keywords: ["/sourceDependencies:directives"] +helpviewer_keywords: ["/sourceDependencies:directives compiler option", "/sourceDependencies:directives"] +--- +# `/sourceDependencies:directives` (List 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. + +This option differs from [`/sourceDependencies`](sourcedependencies.md) in the following ways: + +- 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 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`** *filename*\ +> **`/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. + +*`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 *`.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. + +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: + +```cpp +//main.cpp: +#include + +import m; +import std; +import ; +import "t.h"; + +int main() {} +``` + +This following command line: + +`cl /std:c++latest /translateInclude /sourceDependencies:directives output.json main.cpp` + +produces a JSON file *`output.json`* similar to: + +```JSON +{ + "Version":"1.1", + "Data":{ + "Source":"C:\\test\\main.cpp", + "ProvidedModule":"", + "ImportedModules":[ + "m", + "std" + ], + "ImportedHeaderUnits":[ + "C:\\...\\utility", + "C:\\...\\vector", + "C:\\test\\t.h" + ] + } +} +``` + +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 set this compiler option in Visual Studio + +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)\ +[`/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 e2ef5e4a3f..e789466f8b 100644 --- a/docs/build/reference/sourcedependencies.md +++ b/docs/build/reference/sourcedependencies.md @@ -1,37 +1,45 @@ --- title: "/sourceDependencies (Report source-level dependencies)" -description: "Reference guide to the /sourceDependencies compiler option in Microsoft C++." -ms.date: 07/29/2020 +description: "Describes the /sourceDependencies compiler option in Microsoft C++." +ms.date: 02/23/2024 +author: "tylermsft" +ms.author: "twhitney" f1_keywords: ["/sourceDependencies"] helpviewer_keywords: ["/sourceDependencies compiler option", "/sourceDependencies"] --- -# `/sourceDependencies` (Report source-level dependencies) +# `/sourceDependencies` (List all source-level dependencies) -Instructs the compiler to generate a JSON file that details the source-level dependencies consumed during compilation. +This command-line switch generates a JSON file that details the source-level dependencies consumed during compilation. The JSON file contains a list of the source dependencies, which include: -The JSON file contains a list of the source dependencies, which include: -- Header files (both transitive and directly included headers). +- Header files. Both directly included and the list of headers included by those headers. - The PCH used (if **`/Yu`** is specified). -- Imported modules and imported header units (both transitive and directly imported modules/header units). +- Names of imported modules +- File paths and names of both directly imported header units and of the modules and header units they import in turn. + +This option provides information necessary to build modules and header units in the proper dependency order. ## Syntax +> **`/sourceDependencies-`**\ > **`/sourceDependencies`** *filename*\ > **`/sourceDependencies`** *directory* ## Arguments -*filename*\ -The compiler writes the source dependency output to the specified filename, which may include a relative or absolute path. +*`-`*\ +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 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`*. +*`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 *`.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. @@ -42,52 +50,61 @@ All file paths appear as absolute paths in the output. Given the following sample code: ```cpp -// main.cpp -#include "header.h" -import m; -import "other.h"; - -int main() { } +// ModuleE.ixx: +export module ModuleE; +import ModuleC; +import ModuleD; +import ; ``` -You can use **`/sourceDependencies`** along with the rest of your compiler options: +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 something like: +where `...` represents your other compiler options. This command line produces a JSON file *`output.json`* with content like: ```JSON { - "Version": "1.0", + "Version": "1.2", "Data": { - "Source": "C:\\...\\main.cpp", - "PCH": "C:\\...\\pch.pch", - "Includes": [ - "C:\\...\\header.h" + "Source": "F:\\Sample\\myproject\\modulee.ixx", + "ProvidedModule": "ModuleE", + "Includes": [], + "ImportedModules": [ + { + "Name": "ModuleC", + "BMI": "F:\\Sample\\Outputs\\Intermediate\\MyProject\\x64\\Debug\\ModuleC.ixx.ifc" + }, + { + "Name": "ModuleB", + "BMI": "F:\\Sample\\Outputs\\Intermediate\\ModuleB\\x64\\Debug\\ModuleB.ixx.ifc" + }, + { + "Name": "ModuleD", + "BMI": "F:\\Sample\\Outputs\\Intermediate\\MyProject\\x64\\Debug\\ModuleD.cppm.ifc" + } ], - "Modules": [ - "C:\\...\\m.ifc", - "C:\\...\\other.h.ifc" + "ImportedHeaderUnits": [ + { + "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" + } ] } } ``` -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. - -### To set the /sourceDependencies 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. +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. -1. In the **Additional options** box, add *`/sourceDependencies: `* and then choose **OK** or **Apply** to save your changes. +`ProvidedModule` lists exported module or module partition names. -### To set this compiler option programmatically +### To set this compiler option in the Visual Studio development environment -- This option doesn't have a programmatic equivalent. +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 1eb20e06d9..0000000000 --- a/docs/build/reference/special-characters-in-a-makefile.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -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 a9f58e2294..0000000000 --- a/docs/build/reference/special-characters-in-macros.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -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 ef17a8cb38..93dcf23449 100644 --- a/docs/build/reference/special-nmake-macros.md +++ b/docs/build/reference/special-nmake-macros.md @@ -1,20 +1,80 @@ --- -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 12164b8b87..0000000000 --- a/docs/build/reference/specifying-an-inline-file.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -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/specifying-dlls-to-delay-load.md b/docs/build/reference/specifying-dlls-to-delay-load.md deleted file mode 100644 index b93a7c101f..0000000000 --- a/docs/build/reference/specifying-dlls-to-delay-load.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: "Specifying DLLs to Delay Load" -ms.date: "11/04/2016" -helpviewer_keywords: ["DELAYLOAD linker option", "delayed loading of DLLs", "delayed loading of DLLs, specifying", "/DELAYLOAD linker option"] -ms.assetid: 94cbecfe-7a42-40d1-a618-9f2786bac0d8 ---- -# Specifying DLLs to Delay Load - -You can specify which DLLs to delay load with the [/delayload](delayload-delay-load-import.md):`dllname` linker option. If you do not plan to use your own version of a helper function, you must also link your program with delayimp.lib (for desktop applications) or dloadhelper.lib (for store apps). - -The following is a simple example of delay loading a DLL: - -``` -// cl t.cpp user32.lib delayimp.lib /link /DELAYLOAD:user32.dll -#include -// uncomment these lines to remove .libs from command line -// #pragma comment(lib, "delayimp") -// #pragma comment(lib, "user32") - -int main() { - // user32.dll will load at this point - MessageBox(NULL, "Hello", "Hello", MB_OK); -} -``` - -Build the DEBUG version of the project. Step through the code using the debugger and you will notice that user32.dll is loaded only when you make the call to `MessageBox`. - -## See also - -[Linker Support for Delay-Loaded DLLs](linker-support-for-delay-loaded-dlls.md) diff --git a/docs/build/reference/specifying-the-pathname.md b/docs/build/reference/specifying-the-pathname.md index fae23cb270..55be6dfec9 100644 --- a/docs/build/reference/specifying-the-pathname.md +++ b/docs/build/reference/specifying-the-pathname.md @@ -1,8 +1,8 @@ --- title: "Specifying the Pathname" -ms.date: "11/04/2016" +description: "Learn more about: Specifying the Pathname" +ms.date: 11/04/2016 helpviewer_keywords: ["names [C++], compiler output files", "cl.exe compiler, output files", "output files, specifying pathnames"] -ms.assetid: 7a6595ce-3383-44ae-957a-466bfa29c343 --- # Specifying the Pathname @@ -23,7 +23,7 @@ Alternatively, the *pathname* argument can be a device name (AUX, CON, PRN, or N The following command line sends a mapfile to the printer: -``` +```cmd CL /FmPRN HELLO.CPP ``` diff --git a/docs/build/reference/stack-stack-allocations.md b/docs/build/reference/stack-stack-allocations.md index af3da09139..5bd9529826 100644 --- a/docs/build/reference/stack-stack-allocations.md +++ b/docs/build/reference/stack-stack-allocations.md @@ -1,35 +1,32 @@ --- -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 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. Select the **System** property page. +1. Select the **Configuration Properties** > **Linker** > **System** property page. 1. Modify one of the following properties: @@ -43,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/stack.md b/docs/build/reference/stack.md index ae10a564b5..bcb4472f91 100644 --- a/docs/build/reference/stack.md +++ b/docs/build/reference/stack.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /STACK" title: "/STACK" ms.date: "11/04/2016" f1_keywords: ["/stack_editbin"] diff --git a/docs/build/reference/stacksize.md b/docs/build/reference/stacksize.md index 9d2f27d04b..933e9f89ae 100644 --- a/docs/build/reference/stacksize.md +++ b/docs/build/reference/stacksize.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: STACKSIZE" title: "STACKSIZE" ms.date: "11/04/2016" f1_keywords: ["STACKSIZE"] diff --git a/docs/build/reference/std-specify-language-standard-version.md b/docs/build/reference/std-specify-language-standard-version.md index 1871409ac7..c9eeb3f544 100644 --- a/docs/build/reference/std-specify-language-standard-version.md +++ b/docs/build/reference/std-specify-language-standard-version.md @@ -1,60 +1,140 @@ --- title: "/std (Specify Language Standard Version)" -ms.date: "06/04/2020" -f1_keywords: ["/std", "-std", "VC.Project.VCCLCompilerTool.CppLanguageStandard"] -ms.assetid: 0acb74ba-1aa8-4c05-b96c-682988dc19bd +description: "The MSVC compiler option /std specifies the C or C++ language standard supported by the compiler." +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) -Enable supported C++ language features from the specified version of the C++ language standard. +Enable supported C and C++ language features from the specified version of the C or C++ language standard. ## Syntax > **`/std:c++14`**\ > **`/std:c++17`**\ -> **`/std:c++latest`** +> **`/std:c++20`**\ +> **`/std:c++23preview`**\ +> **`/std:c++latest`**\ +> **`/std:c11`**\ +> **`/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++ 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. 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. +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. -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: +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). -- [Rules for `auto` with braced-init-lists](https://wg21.link/n3922) +## C++ standards support -- [`typename` in template template-parameters](https://wg21.link/n4051) +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). -- [Removing trigraphs](https://wg21.link/n4086) +> [!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. -- [Attributes for namespaces and enumerators](https://wg21.link/n4266) +### `/std:c++14` + +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. +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` + +Enables C++20 standard-specific features and behavior. + +Enables the standard conformance mode provided by [**`/permissive-`**](./permissive-standards-conformance.md) unless explicitly overridden with **`/permissive`**. + +### `/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. + +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. + +### `/std:c++latest` + +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). -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). +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`**. -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. +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] -> 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). +> 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. -### To set this compiler option in the Visual Studio development environment +## C standards support + +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. + +### `/std:c11` + +Enables ISO C11 conformance. It's available starting in Visual Studio 2019 version 16.8. + +### `/std:c17` + +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). + +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: -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). +- [`_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) -1. Select **Configuration Properties**, **C/C++**, **Language**. +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`. + +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. + +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). + +- [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. VLAs provide attack vectors comparable to [`gets`](../../c-runtime-library/gets-getws.md), which is deprecated and planned for removal. + +### `/std:clatest` + +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. + +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. In **C++ Language Standard**, choose the language standard to support from the dropdown control, then choose **OK** or **Apply** to save your changes. +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/structure-and-constant-definitions.md b/docs/build/reference/structure-and-constant-definitions.md deleted file mode 100644 index a7e730c8d8..0000000000 --- a/docs/build/reference/structure-and-constant-definitions.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: "Structure and Constant Definitions" -ms.date: "11/04/2016" -ms.assetid: 1df7cf46-b853-4788-a257-100d5c37997f ---- -# Structure and Constant Definitions - -The default helper routine uses several structures to communicate with the hook functions and during any exceptions. Here are the notification and failure values, information structures, and the pointer-to-hook-function type passed to the hooks: - -``` -// -// Delay load import hook notifications -// -enum { - dliStartProcessing, // used to bypass or note helper only - dliNotePreLoadLibrary, // called just before LoadLibrary, can - // override w/ new HMODULE return val - dliNotePreGetProcAddress, // called just before GetProcAddress, can - // override w/ new FARPROC return value - dliFailLoadLib, // failed to load library, fix it by - // returning a valid HMODULE - dliFailGetProc, // failed to get proc address, fix it by - // returning a valid FARPROC - dliNoteEndProcessing, // called after all processing is done, no - // bypass possible at this point except - // by longjmp()/throw()/RaiseException. - }; - -typedef struct DelayLoadProc { - BOOL fImportByName; - union { - LPCSTR szProcName; - DWORD dwOrdinal; - }; - } DelayLoadProc; - -typedef struct DelayLoadInfo { - DWORD cb; // size of structure - PCImgDelayDescr pidd; // raw form of data (everything is there) - FARPROC * ppfn; // points to address of function to load - LPCSTR szDll; // name of dll - DelayLoadProc dlp; // name or ordinal of procedure - HMODULE hmodCur; // the hInstance of the library we have loaded - FARPROC pfnCur; // the actual function that will be called - DWORD dwLastError;// error received (if an error notification) - } DelayLoadInfo, * PDelayLoadInfo; - -typedef FARPROC (WINAPI *PfnDliHook)( - unsigned dliNotify, - PDelayLoadInfo pdli - ); - -typedef struct ImgDelayDescr { - DWORD grAttrs; // attributes - RVA rvaDLLName; // RVA to dll name - RVA rvaHmod; // RVA of module handle - RVA rvaIAT; // RVA of the IAT - RVA rvaINT; // RVA of the INT - RVA rvaBoundIAT; // RVA of the optional bound IAT - RVA rvaUnloadIAT; // RVA of optional copy of original IAT - DWORD dwTimeStamp; // 0 if not bound, - // O.W. date/time stamp of DLL bound to (Old BIND) - } ImgDelayDescr, * PImgDelayDescr; -``` - -## See also - -[Understanding the Helper Function](understanding-the-helper-function.md) diff --git a/docs/build/reference/structure-of-a-library.md b/docs/build/reference/structure-of-a-library.md index ab9248d8fb..a66a5b789f 100644 --- a/docs/build/reference/structure-of-a-library.md +++ b/docs/build/reference/structure-of-a-library.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Structure of a Library" title: "Structure of a Library" ms.date: "11/04/2016" helpviewer_keywords: ["libraries, structure"] diff --git a/docs/build/reference/stub-ms-dos-stub-file-name.md b/docs/build/reference/stub-ms-dos-stub-file-name.md index 61fda59ced..a05a231e1b 100644 --- a/docs/build/reference/stub-ms-dos-stub-file-name.md +++ b/docs/build/reference/stub-ms-dos-stub-file-name.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /STUB (MS-DOS Stub File Name)" title: "/STUB (MS-DOS Stub File Name)" ms.date: "11/04/2016" f1_keywords: ["/stub", "VC.Project.VCLinkerTool.DosStub"] @@ -36,11 +37,9 @@ When building a virtual device driver, *filename* allows the user to specify a f 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. Select the **Configuration Properties** > **Linker** > **Command Line** property page. -1. Click the **Command Line** property page. - -1. Type the option into the **Additional Options** box. +1. Enter the option into the **Additional Options** box. ### To set this linker option programmatically diff --git a/docs/build/reference/stub.md b/docs/build/reference/stub.md index f4fb112999..7ab5e7c3c3 100644 --- a/docs/build/reference/stub.md +++ b/docs/build/reference/stub.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: STUB" title: "STUB" ms.date: "11/04/2016" f1_keywords: ["STUB"] diff --git a/docs/build/reference/subsystem-specify-subsystem.md b/docs/build/reference/subsystem-specify-subsystem.md index b9c2c3e2f9..5669fa0e8b 100644 --- a/docs/build/reference/subsystem-specify-subsystem.md +++ b/docs/build/reference/subsystem-specify-subsystem.md @@ -1,72 +1,73 @@ --- +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 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. Select the **System** property page. +1. Select the **Configuration Properties** > **Linker** > **System** property page. -1. Modify the `SubSystem` property. +1. Modify the **SubSystem** property. ### To set this linker option programmatically @@ -74,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/subsystem.md b/docs/build/reference/subsystem.md index 8e238f2db2..a2c774d8a4 100644 --- a/docs/build/reference/subsystem.md +++ b/docs/build/reference/subsystem.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /SUBSYSTEM" title: "/SUBSYSTEM" ms.date: "11/04/2016" f1_keywords: ["/subsystem_editbin"] diff --git a/docs/build/reference/summary-visual-cpp.md b/docs/build/reference/summary-visual-cpp.md index 279c5e7dcb..7651f7a4bf 100644 --- a/docs/build/reference/summary-visual-cpp.md +++ b/docs/build/reference/summary-visual-cpp.md @@ -1,30 +1,31 @@ --- -title: "<summary> (C++ Documentation Comments)" -ms.date: "11/04/2016" -f1_keywords: ["", "summary"] +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 @@ -49,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/summary.md b/docs/build/reference/summary.md index dedd4b6ca7..56f2ad896b 100644 --- a/docs/build/reference/summary.md +++ b/docs/build/reference/summary.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /SUMMARY" title: "/SUMMARY" ms.date: "11/04/2016" f1_keywords: ["/summary"] diff --git a/docs/build/reference/swaprun-load-linker-output-to-swap-file.md b/docs/build/reference/swaprun-load-linker-output-to-swap-file.md index 2b19c86550..45bedc73fd 100644 --- a/docs/build/reference/swaprun-load-linker-output-to-swap-file.md +++ b/docs/build/reference/swaprun-load-linker-output-to-swap-file.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /SWAPRUN (Load Linker Output to Swap File)" title: "/SWAPRUN (Load Linker Output to Swap File)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCLinkerTool.SwapRunFromNet", "/swaprun", "VC.Project.VCLinkerTool.SwapRunFromCD"] @@ -21,9 +22,7 @@ If NET is specified, the operating system will first copy the binary image from 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 **System** property page. +1. Select the **Configuration Properties** > **Linker** > **System** property page. 1. Modify one of the following properties: diff --git a/docs/build/reference/swaprun.md b/docs/build/reference/swaprun.md index 769c412066..64f3a9fecc 100644 --- a/docs/build/reference/swaprun.md +++ b/docs/build/reference/swaprun.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /SWAPRUN" title: "/SWAPRUN" ms.date: "11/04/2016" f1_keywords: ["/swaprun_editbin"] diff --git a/docs/build/reference/symbols.md b/docs/build/reference/symbols.md index 8946f61b36..fd65581938 100644 --- a/docs/build/reference/symbols.md +++ b/docs/build/reference/symbols.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /SYMBOLS" title: "/SYMBOLS" ms.date: "09/05/2018" f1_keywords: ["/symbols"] diff --git a/docs/build/reference/tc-tp-tc-tp-specify-source-file-type.md b/docs/build/reference/tc-tp-tc-tp-specify-source-file-type.md index 985cf6e975..2920195ac1 100644 --- a/docs/build/reference/tc-tp-tc-tp-specify-source-file-type.md +++ b/docs/build/reference/tc-tp-tc-tp-specify-source-file-type.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Tc, /Tp, /TC, /TP (Specify Source File Type)" title: "/Tc, /Tp, /TC, /TP (Specify Source File Type)" ms.date: "01/11/2018" f1_keywords: ["VC.Project.VCCLWCECompilerTool.CompileAs", "VC.Project.VCCLCompilerTool.CompileAs", "/Tp", "/tc"] 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/tlbid-specify-resource-id-for-typelib.md b/docs/build/reference/tlbid-specify-resource-id-for-typelib.md index e894d8ba08..d799af702e 100644 --- a/docs/build/reference/tlbid-specify-resource-id-for-typelib.md +++ b/docs/build/reference/tlbid-specify-resource-id-for-typelib.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /TLBID (Specify Resource ID for TypeLib)" title: "/TLBID (Specify Resource ID for TypeLib)" ms.date: "11/04/2016" f1_keywords: ["/tlbid", "VC.Project.VCLinkerTool.TypeLibraryResourceID"] @@ -26,9 +27,7 @@ If this resource ID conflicts with one of your existing resources, you can speci 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 **Embedded IDL** property page. +1. Select the **Configuration Properties** > **Linker** > **Embedded IDL** property page. 1. Modify the **TypeLib Resource ID** property. diff --git a/docs/build/reference/tlbout-name-dot-tlb-file.md b/docs/build/reference/tlbout-name-dot-tlb-file.md index 1ee154c554..3daba01380 100644 --- a/docs/build/reference/tlbout-name-dot-tlb-file.md +++ b/docs/build/reference/tlbout-name-dot-tlb-file.md @@ -1,39 +1,37 @@ --- +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/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. -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 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 **Embedded IDL** property page. +1. Select the **Configuration Properties** > **Linker** > **Embedded IDL** property page. 1. Modify the **Type Library** property. @@ -43,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)
-[Building an Attributed Program](../../windows/building-an-attributed-program.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/tls.md b/docs/build/reference/tls.md index d9736ccbbe..b87e6fdf0d 100644 --- a/docs/build/reference/tls.md +++ b/docs/build/reference/tls.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /TLS" title: "/TLS" ms.date: "11/04/2016" f1_keywords: ["/TLS"] diff --git a/docs/build/reference/translateinclude.md b/docs/build/reference/translateinclude.md new file mode 100644 index 0000000000..fa5cadac9e --- /dev/null +++ b/docs/build/reference/translateinclude.md @@ -0,0 +1,50 @@ +--- +title: "/translateInclude" +description: "Use the /translateInclude compiler option to treat #include directives as import statements when an importable header unit is available." +ms.date: 02/17/2022 +author: "tylermsft" +ms.author: "twhitney" +f1_keywords: ["/translateInclude", "VC.Project.VCCLCompilerTool.TranslateIncludes"] +helpviewer_keywords: ["/translateInclude", "Translate include directives into import directives"] +--- +# `/translateInclude` + +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). + +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`. + +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). + +If an `#include` file isn't listed in the `header-units.json` file, it's treated as a normal `#include`. + +For an example of how this switch is used, see [Walkthrough: Build and import header units in Microsoft Visual C++](../walkthrough-header-units.md). + +## Syntax + +> **`/translateInclude`** + +## Remarks + +**`/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. + +## To set this compiler option in Visual Studio + +To enable `/translateInclude`, in the project properties dialog, set **Translate Includes to Imports**: + +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**. + + ![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)\ +[`/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 58be09321b..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,39 +1,36 @@ --- -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 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 **System** property page. +1. Select the **Configuration Properties** > **Linker** > **System** property page. 1. Modify the **Terminal Server** property. @@ -46,4 +43,4 @@ If an application was linked with /TSAWARE, DUMPBIN [/HEADERS](headers.md) will [MSVC linker reference](linking.md)
[MSVC Linker Options](linker-options.md)
[Storing User-Specific Information](/windows/win32/TermServ/storing-user-specific-information)
-[Legacy Applications in a Terminal Services Environment](https://docs.microsoft.com/previous-versions//aa382957(v=vs.85)) +[Legacy Applications in a Terminal Services Environment](/previous-versions/aa382957(v=vs.85)) diff --git a/docs/build/reference/tsaware.md b/docs/build/reference/tsaware.md index 2fed81686a..b82b7566fc 100644 --- a/docs/build/reference/tsaware.md +++ b/docs/build/reference/tsaware.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /TSAWARE" title: "/TSAWARE" ms.date: "11/04/2016" f1_keywords: ["/tsaware_editbin"] diff --git a/docs/build/reference/u-u-undefine-symbols.md b/docs/build/reference/u-u-undefine-symbols.md index faaef8b167..cdc3cdd3ba 100644 --- a/docs/build/reference/u-u-undefine-symbols.md +++ b/docs/build/reference/u-u-undefine-symbols.md @@ -1,11 +1,11 @@ --- title: "/U, /u (Undefine symbols)" -ms.date: "06/08/2020" +description: "Use the Microsoft C/C++ compiler /U and /u options to undefine preprocessor symbols." +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. @@ -16,7 +16,7 @@ The **`/U`** compiler option undefines the specified preprocessor symbol. The ** ## Arguments -*symbol*
+*`symbol`*\ The preprocessor symbol to undefine. ## Remarks @@ -29,23 +29,21 @@ By default, the compiler may define a large number of Microsoft-specific symbols | Symbol | Function | |--|--| -| `_CHAR_UNSIGNED` | Default char type is unsigned. Defined when the [**`/J`**](j-default-char-type-is-unsigned.md) option is specified. | -| `_CPPRTTI` | Defined for code compiled with the [**`/GR`**](gr-enable-run-time-type-information.md) option. | -| `_CPPUNWIND` | Defined for code compiled with the [**`/EHsc`**](eh-exception-handling-model.md) option. | -| `_DLL` | Defined when the [**`/MD`**](md-mt-ld-use-run-time-library.md) option is specified. | +| `_CHAR_UNSIGNED` | Default char type is unsigned. Defined when the [`/J`](j-default-char-type-is-unsigned.md) option is specified. | +| `_CPPRTTI` | Defined for code compiled with the [`/GR`](gr-enable-run-time-type-information.md) option. | +| `_CPPUNWIND` | Defined for code compiled with the [`/EHsc`](eh-exception-handling-model.md) option. | +| `_DLL` | Defined when the [`/MD`](md-mt-ld-use-run-time-library.md) option is specified. | | `_M_IX86` | By default, defined to 600 for x86 targets. | | `_MSC_VER` | Defined as a unique integer value for each compiler version. For more information, see [Predefined macros](../../preprocessor/predefined-macros.md). | | `_WIN32` | Defined for WIN32 applications. Always defined. | -| `_MT` | Defined when the [**`/MD`** or **`/MT`**](md-mt-ld-use-run-time-library.md) option is specified. | +| `_MT` | Defined when the [`/MD`](md-mt-ld-use-run-time-library.md) or [`/MT`](md-mt-ld-use-run-time-library.md) option is specified. | For a complete list of Microsoft-specific predefined macros, see [Predefined macros](../../preprocessor/predefined-macros.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++** > **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 @@ -54,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/understanding-the-helper-function.md b/docs/build/reference/understanding-the-helper-function.md index 53ac2b875e..e9a759e616 100644 --- a/docs/build/reference/understanding-the-helper-function.md +++ b/docs/build/reference/understanding-the-helper-function.md @@ -1,22 +1,22 @@ --- -title: "Understanding the Helper Function" -ms.date: "11/04/2016" +description: "Learn more about the delay load helper function" +title: "Understand the delay load helper function" +ms.date: "01/19/2021" helpviewer_keywords: ["delayed loading of DLLs, helper function", "__delayLoadHelper2 function", "delayimp.lib", "__delayLoadHelper function", "delayhlp.cpp", "delayimp.h", "helper functions"] -ms.assetid: 6279c12c-d908-4967-b0b3-cabfc3e91d3d --- -# Understanding the Helper Function +# Understand the delay load helper function -The helper function for linker-supported delayed loading is what actually loads the DLL at run time. You can modify the helper function to customize its behavior by writing your own function and linking it to your program instead of using the supplied helper function in Delayimp.lib. One helper function serves all delay loaded DLLs. +The helper function for linker-supported delayed loading is what actually loads the DLL at runtime. You can modify the helper function to customize its behavior. Instead of using the supplied helper function in *`delayimp.lib`*, write your own function and link it to your program. One helper function serves all delay loaded DLLs. You can provide your own version of the helper function if you want to do specific processing based on the names of the DLL or imports. -The helper function performs the following actions: +The helper function takes these actions: - Checks the stored handle to the library to see if it has already been loaded -- Calls **LoadLibrary** to attempt loading of the DLL +- Calls `LoadLibrary` to attempt to load the DLL -- Calls **GetProcAddress** to attempt getting the address of the procedure +- Calls `GetProcAddress` to attempt getting the address of the procedure - Returns to the delay import load thunk to call the now-loaded entry point @@ -24,32 +24,319 @@ The helper function can call back to a notification hook in your program after e - When the helper function starts up -- Just before **LoadLibrary** is called in the helper function +- Just before `LoadLibrary` is called in the helper function -- Just before **GetProcAddress** is called in the helper function +- Just before `GetProcAddress` is called in the helper function -- If the call to **LoadLibrary** in the helper function failed +- If the call to `LoadLibrary` in the helper function fails -- If the call to **GetProcAddress** in the helper function failed +- If the call to `GetProcAddress` in the helper function fails - After the helper function is done processing -Each of these hook points can return a value that will alter normal processing of the helper routine in some manner except the return to the delay import load thunk. +Each of these hook points can return a value that alters normal processing of the helper routine in some manner, except the return to the delay import load thunk. -The default helper code can be found in Delayhlp.cpp and Delayimp.h (in vc\include) and is compiled in Delayimp.lib (in vc\lib). You will need to include this library in your compilations unless you write your own helper function. +The default helper code can be found in *`delayhlp.cpp`* and *`delayimp.h`* in the MSVC *`include`* directory. It's compiled into *`delayimp.lib`* in the MSVC *`lib`* directory for your target architecture. You'll need to include this library in your compilations unless you write your own helper function. -The following topics describe the helper function: +## Delay load helper calling conventions, parameters, and return type -- [Changes in the DLL Delayed Loading Helper Function Since Visual C++ 6.0](changes-in-the-dll-delayed-loading-helper-function-since-visual-cpp-6-0.md) +The prototype for the delay load helper routine is: -- [Calling Conventions, Parameters, and Return Type](calling-conventions-parameters-and-return-type.md) +```C +FARPROC WINAPI __delayLoadHelper2( + PCImgDelayDescr pidd, + FARPROC * ppfnIATEntry +); +``` -- [Structure and Constant Definitions](structure-and-constant-definitions.md) +### Parameters -- [Calculating Necessary Values](calculating-necessary-values.md) +*`pidd`*\ +A **`const`** pointer to a `ImgDelayDescr` that contains the offsets of various import-related data, a timestamp for binding information, and a set of attributes that provide further information about the descriptor content. Currently there's only one attribute, `dlattrRva`, which indicates that the addresses in the descriptor are relative virtual addresses. For more information, see the declarations in *`delayimp.h`*. -- [Unloading a Delay-Loaded DLL](explicitly-unloading-a-delay-loaded-dll.md) +The pointers in the delay descriptor (`ImgDelayDescr` in *`delayimp.h`*) use relative virtual addresses (RVAs) to work as expected in both 32-bit and 64-bit programs. To use them, convert these RVAs back to pointers by using the function `PFromRva`, found in *`delayhlp.cpp`*. You can use this function on each of the fields in the descriptor to convert them back to either 32-bit or 64-bit pointers. The default delay load helper function is a good template to use as an example. + +For the definition of the `PCImgDelayDescr` structure, see [Structure and constant definitions](#structure-and-constant-definitions). + +*`ppfnIATEntry`*\ +A pointer to a slot in the delay load import address table (IAT). It's the slot that's updated with the address of the imported function. The helper routine needs to store the same value that it returns into this location. + +### Expected return values + +If the helper function is successful, it returns the address of the imported function. + +If the function fails, it raises a structured exception and returns 0. Three types of exceptions can be raised: + +- Invalid parameter, which happens if the attributes in *`pidd`* aren't specified correctly. Treat this as an unrecoverable error. + +- `LoadLibrary` failed on the specified DLL. + +- Failure of `GetProcAddress`. + +It's your responsibility to handle these exceptions. For more information, see [Error handling and notification](error-handling-and-notification.md). + +### Remarks + +The calling convention for the helper function is **`__stdcall`**. The type of the return value isn't relevant, so `FARPROC` is used. This function has C linkage, which means it needs to be wrapped by `extern "C"` when declared in C++ code. The `ExternC` macro takes care of this wrapper for you. + +To use your helper routine as a notification hook, your code must specify the appropriate function pointer to return. The thunk code the linker generates then takes that return value as the real target of the import and jumps directly to it. If you don't want to use your helper routine as a notification hook, store the return value of the helper function in `ppfnIATEntry`, the passed-in function pointer location. + +## Sample hook function + +The following code shows how to implement a basic hook function. + +```C +FARPROC WINAPI delayHook(unsigned dliNotify, PDelayLoadInfo pdli) +{ + switch (dliNotify) { + case dliStartProcessing : + + // If you want to return control to the helper, return 0. + // Otherwise, return a pointer to a FARPROC helper function + // that will be used instead, thereby bypassing the rest + // of the helper. + + break; + + case dliNotePreLoadLibrary : + + // If you want to return control to the helper, return 0. + // Otherwise, return your own HMODULE to be used by the + // helper instead of having it call LoadLibrary itself. + + break; + + case dliNotePreGetProcAddress : + + // If you want to return control to the helper, return 0. + // If you choose you may supply your own FARPROC function + // address and bypass the helper's call to GetProcAddress. + + break; + + case dliFailLoadLib : + + // LoadLibrary failed. + // If you don't want to handle this failure yourself, return 0. + // In this case the helper will raise an exception + // (ERROR_MOD_NOT_FOUND) and exit. + // If you want to handle the failure by loading an alternate + // DLL (for example), then return the HMODULE for + // the alternate DLL. The helper will continue execution with + // this alternate DLL and attempt to find the + // requested entrypoint via GetProcAddress. + + break; + + case dliFailGetProc : + + // GetProcAddress failed. + // If you don't want to handle this failure yourself, return 0. + // In this case the helper will raise an exception + // (ERROR_PROC_NOT_FOUND) and exit. + // If you choose, you may handle the failure by returning + // an alternate FARPROC function address. + + break; + + case dliNoteEndProcessing : + + // This notification is called after all processing is done. + // There is no opportunity for modifying the helper's behavior + // at this point except by longjmp()/throw()/RaiseException. + // No return value is processed. + + break; + + default : + + return NULL; + } + + return NULL; +} + +/* +and then at global scope somewhere: + +ExternC const PfnDliHook __pfnDliNotifyHook2 = delayHook; +ExternC const PfnDliHook __pfnDliFailureHook2 = delayHook; +*/ +``` + +## Delay load structure and constant definitions + +The default delay load helper routine uses several structures to communicate with the hook functions and during any exceptions. These structures are defined in *`delayimp.h`*. Here are the macros, typedefs, notification and failure values, information structures, and the pointer-to-hook-function type passed to the hooks: + +```C +#define _DELAY_IMP_VER 2 + +#if defined(__cplusplus) +#define ExternC extern "C" +#else +#define ExternC extern +#endif + +typedef IMAGE_THUNK_DATA * PImgThunkData; +typedef const IMAGE_THUNK_DATA * PCImgThunkData; +typedef DWORD RVA; + +typedef struct ImgDelayDescr { + DWORD grAttrs; // attributes + RVA rvaDLLName; // RVA to dll name + RVA rvaHmod; // RVA of module handle + RVA rvaIAT; // RVA of the IAT + RVA rvaINT; // RVA of the INT + RVA rvaBoundIAT; // RVA of the optional bound IAT + RVA rvaUnloadIAT; // RVA of optional copy of original IAT + DWORD dwTimeStamp; // 0 if not bound, + // O.W. date/time stamp of DLL bound to (Old BIND) + } ImgDelayDescr, * PImgDelayDescr; + +typedef const ImgDelayDescr * PCImgDelayDescr; + +enum DLAttr { // Delay Load Attributes + dlattrRva = 0x1, // RVAs are used instead of pointers + // Having this set indicates a VC7.0 + // and above delay load descriptor. + }; + +// +// Delay load import hook notifications +// +enum { + dliStartProcessing, // used to bypass or note helper only + dliNoteStartProcessing = dliStartProcessing, + + dliNotePreLoadLibrary, // called just before LoadLibrary, can + // override w/ new HMODULE return val + dliNotePreGetProcAddress, // called just before GetProcAddress, can + // override w/ new FARPROC return value + dliFailLoadLib, // failed to load library, fix it by + // returning a valid HMODULE + dliFailGetProc, // failed to get proc address, fix it by + // returning a valid FARPROC + dliNoteEndProcessing, // called after all processing is done, no + // bypass possible at this point except + // by longjmp()/throw()/RaiseException. + }; + +typedef struct DelayLoadProc { + BOOL fImportByName; + union { + LPCSTR szProcName; + DWORD dwOrdinal; + }; + } DelayLoadProc; + +typedef struct DelayLoadInfo { + DWORD cb; // size of structure + PCImgDelayDescr pidd; // raw form of data (everything is there) + FARPROC * ppfn; // points to address of function to load + LPCSTR szDll; // name of dll + DelayLoadProc dlp; // name or ordinal of procedure + HMODULE hmodCur; // the hInstance of the library we have loaded + FARPROC pfnCur; // the actual function that will be called + DWORD dwLastError;// error received (if an error notification) + } DelayLoadInfo, * PDelayLoadInfo; + +typedef FARPROC (WINAPI *PfnDliHook)( + unsigned dliNotify, + PDelayLoadInfo pdli + ); +``` + +## Calculate necessary values for delay loading + +The delay load helper routine needs to calculate two critical pieces of information. To help, there are two inline functions in *`delayhlp.cpp`* to calculate this information. + +- The first, `IndexFromPImgThunkData`, calculates the index of the current import into the three different tables (import address table (IAT), bound import address table (BIAT), and unbound import address table (UIAT)). + +- The second, `CountOfImports`, counts the number of imports in a valid IAT. + +```C +// utility function for calculating the index of the current import +// for all the tables (INT, BIAT, UIAT, and IAT). +__inline unsigned +IndexFromPImgThunkData(PCImgThunkData pitdCur, PCImgThunkData pitdBase) { + return pitdCur - pitdBase; + } + +// utility function for calculating the count of imports given the base +// of the IAT. NB: this only works on a valid IAT! +__inline unsigned +CountOfImports(PCImgThunkData pitdBase) { + unsigned cRet = 0; + PCImgThunkData pitd = pitdBase; + while (pitd->u1.Function) { + pitd++; + cRet++; + } + return cRet; + } +``` + +## Support unload of a delay-loaded DLL + +When a delay-loaded DLL gets loaded, the default delay-load helper checks to see if the delay-load descriptors have a pointer and a copy of the original import address table (IAT) in the `pUnloadIAT` field. If so, the helper saves a pointer in a list to the import delay descriptor. This entry lets the helper function find the DLL by name, to support unloading that DLL explicitly. + +Here are the associated structures and functions for explicitly unloading a delay-loaded DLL: + +```cpp +// +// Unload support from delayimp.h +// + +// routine definition; takes a pointer to a name to unload + +ExternC +BOOL WINAPI +__FUnloadDelayLoadedDLL2(LPCSTR szDll); + +// structure definitions for the list of unload records +typedef struct UnloadInfo * PUnloadInfo; +typedef struct UnloadInfo { + PUnloadInfo puiNext; + PCImgDelayDescr pidd; + } UnloadInfo; + +// from delayhlp.cpp +// the default delay load helper places the unloadinfo records in the +// list headed by the following pointer. +ExternC +PUnloadInfo __puiHead; +``` + +The `UnloadInfo` structure is implemented using a C++ class that uses `LocalAlloc` and `LocalFree` implementations as its `operator new` and `operator delete`, respectively. These options are kept in a standard linked list that uses `__puiHead` as the head of the list. + +When you call `__FUnloadDelayLoadedDLL`, it attempts to find the name you provide in the list of loaded DLLs. (An exact match is required.) If found, the copy of the IAT in `pUnloadIAT` is copied over the top of the running IAT to restore the thunk pointers. Then, the library is freed by using `FreeLibrary`, the matching `UnloadInfo` record is unlinked from the list and deleted, and `TRUE` is returned. + +The argument to the function `__FUnloadDelayLoadedDLL2` is case-sensitive. For example, you would specify: + +```cpp +__FUnloadDelayLoadedDLL2("user32.dll"); +``` + +and not: + +```cpp +__FUnloadDelayLoadedDLL2("User32.DLL"); +``` + +For an example of unloading a delay-loaded DLL, see [Explicitly unload a delay-loaded DLL](linker-support-for-delay-loaded-dlls.md). + +## Develop your own delay load helper function + +You may want to provide your own version of the delay load helper routine. In your own routine, you can do specific processing based on the names of the DLL or imports. There are two ways to insert your own code: Code your own helper function, possibly based on the supplied code. Or, hook the supplied helper to call your own function by using the [notification hooks](error-handling-and-notification.md#notification-hooks). + +### Code your own helper + +Creating your own helper routine is straightforward. You can use the existing code as a guide for your new function. Your function must use the same calling conventions as the existing helper. And, if it returns to the linker-generated thunks, it must return a proper function pointer. Once you've created your code, you may either satisfy the call or get out of the call, however you like. + +### Use the start processing notification hook + +It's probably easiest to provide a new pointer to a user-supplied notification hook function that takes the same values as the default helper for the `dliStartProcessing` notification. At that point, the hook function can essentially become the new helper function, because a successful return to the default helper bypasses all further processing in the default helper. ## See also -[Linker Support for Delay-Loaded DLLs](linker-support-for-delay-loaded-dlls.md) +[Linker support for delay-loaded DLLs](linker-support-for-delay-loaded-dlls.md#explicitly-unload-a-delay-loaded-dll) diff --git a/docs/build/reference/unicode-support-in-the-compiler-and-linker.md b/docs/build/reference/unicode-support-in-the-compiler-and-linker.md index 5a1954ea0a..3723ac9bf1 100644 --- a/docs/build/reference/unicode-support-in-the-compiler-and-linker.md +++ b/docs/build/reference/unicode-support-in-the-compiler-and-linker.md @@ -1,12 +1,13 @@ --- +description: "Learn more about: Unicode support in the compiler and linker" title: "Unicode Support in the Compiler and Linker" -ms.date: "12/15/2017" +ms.date: 03/07/2021 f1_keywords: ["VC.Project.VCLinkerTool.UseUnicodeResponseFiles", "VC.Project.VCLibrarianTool.UseUnicodeResponseFiles", "VC.Project.VCCLCompilerTool.UseUnicodeResponseFiles", "VC.Project.VCXDCMakeTool.UseUnicodeResponseFiles"] helpviewer_keywords: ["Unicode, Visual C++"] --- -# Unicode Support in the Compiler and Linker +# Unicode support in the compiler and linker -Most Visual C++ build tools support Unicode inputs and outputs. +Most Microsoft C/C++ (MSVC) build tools support Unicode inputs and outputs. ## Filenames @@ -24,17 +25,21 @@ Unicode can be input into a source code file in the following encodings: - UTF-8 with BOM +In the Visual Studio IDE, you can save files in several encoding formats, including Unicode ones. Save them in the **Save File As** dialog by using the dropdown on the **Save** button. Select **Save with Encoding** in the dropdown. Then, in the **Advanced Save Options** dialog, select an encoding from the dropdown list. Choose **OK** to save the file. + ## Output During compilation, the compiler outputs diagnostics to the console in UTF-16. The characters that can be displayed at your console depend on the console window properties. Compiler output redirected to a file is in the current ANSI console codepage. -## Linker response files and .DEF files +## Linker response files and `.DEF` files + +Response files and *`.DEF`* files can be either UTF-16 or UTF-8 with a BOM, or ANSI. -Response files and DEF files can be either UTF-16 with a BOM, or ANSI. +## `.asm` and `.cod` dumps -## .asm and .cod dumps +*`.asm`* and *`.cod`* dumps are in ANSI by default for compatibility with MASM. Use [`/FAu`](fa-fa-listing-file.md) to output UTF-8. -.asm and .cod dumps are in ANSI by default for compatibility with MASM. Use [/FAu](fa-fa-listing-file.md) to output UTF-8. Note that if you specify **/FAs**, the intermingled source will just be directly printed and may look garbled, for example if source code is UTF-8 and you didn't specify **/FAsu**. +If you specify **`/FAs`**, the intermingled source gets printed directly. It may look garbled, for example, when the source code is UTF-8 and you didn't specify **`/FAsu`**. ## See also diff --git a/docs/build/reference/unloading-a-delay-loaded-dll.md b/docs/build/reference/unloading-a-delay-loaded-dll.md deleted file mode 100644 index 72dec7851a..0000000000 --- a/docs/build/reference/unloading-a-delay-loaded-dll.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: "Unloading a Delay-Loaded DLL" -ms.date: "11/04/2016" -helpviewer_keywords: ["__FUnloadDelayLoadedDLL2", "delayed loading of DLLs, unloading"] -ms.assetid: 6463bc71-020e-4aff-a4ca-90360411c54e ---- -# Unloading a Delay-Loaded DLL - -The default-supplied delay-load helper checks to see if the delay-load descriptors have a pointer and a copy of the original import address table (IAT) in the pUnloadIAT field. If so, it will save a pointer in a list to the import delay descriptor. This enables the helper function to find the DLL by name to support unloading that DLL explicitly. - -Here are the associated structures and functions for explicitly unloading a delay-loaded DLL: - -```cpp -// -// Unload support from delayimp.h -// - -// routine definition; takes a pointer to a name to unload - -ExternC -BOOL WINAPI -__FUnloadDelayLoadedDLL2(LPCSTR szDll); - -// structure definitions for the list of unload records -typedef struct UnloadInfo * PUnloadInfo; -typedef struct UnloadInfo { - PUnloadInfo puiNext; - PCImgDelayDescr pidd; - } UnloadInfo; - -// from delayhlp.cpp -// the default delay load helper places the unloadinfo records in the -// list headed by the following pointer. -ExternC -PUnloadInfo __puiHead; -``` - -The UnloadInfo structure is implemented using a C++ class that uses **LocalAlloc** and **LocalFree** implementations as its operator **`new`** and operator **`delete`** respectively. These options are kept in a standard linked list using __puiHead as the head of the list. - -Calling __FUnloadDelayLoadedDLL will attempt to find the name you provide in the list of loaded DLLs (an exact match is required). If found, the copy of the IAT in pUnloadIAT is copied over the top of the running IAT to restore the thunk pointers, the library is freed with **FreeLibrary**, the matching **UnloadInfo** record is unlinked from the list and deleted, and TRUE is returned. - -The argument to the function __FUnloadDelayLoadedDLL2 is case sensitive. For example, you would specify: - -```cpp -__FUnloadDelayLoadedDLL2("user32.DLL"); -``` - -and not: - -```cpp -__FUnloadDelayLoadedDLL2("User32.DLL");. -``` - -## See also - -[Understanding the Helper Function](understanding-the-helper-function.md) diff --git a/docs/build/reference/useprofile.md b/docs/build/reference/useprofile.md index e504c9177b..9a9fde9e72 100644 --- a/docs/build/reference/useprofile.md +++ b/docs/build/reference/useprofile.md @@ -1,11 +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 @@ -13,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 @@ -47,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-import-library-and-export-file.md b/docs/build/reference/using-an-import-library-and-export-file.md index ddbccfbfd9..6ba6f1a699 100644 --- a/docs/build/reference/using-an-import-library-and-export-file.md +++ b/docs/build/reference/using-an-import-library-and-export-file.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Using an Import Library and Export File" title: "Using an Import Library and Export File" ms.date: "11/04/2016" helpviewer_keywords: ["circular exports", "import libraries, using", "export files"] diff --git a/docs/build/reference/using-an-nmake-macro.md b/docs/build/reference/using-an-nmake-macro.md index 0f2ba6c0c5..f4b418744b 100644 --- a/docs/build/reference/using-an-nmake-macro.md +++ b/docs/build/reference/using-an-nmake-macro.md @@ -1,26 +1,110 @@ --- -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/using-visual-cpp-add-new-item-templates.md b/docs/build/reference/using-visual-cpp-add-new-item-templates.md index 85e617bed1..3395c565be 100644 --- a/docs/build/reference/using-visual-cpp-add-new-item-templates.md +++ b/docs/build/reference/using-visual-cpp-add-new-item-templates.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Using Visual C++ Add New Item Templates" title: "Using Visual C++ Add New Item Templates" ms.date: "05/06/2019" helpviewer_keywords: ["Add New Item", "Add New Item templates", "Add New Item command", "templates, Add New Item"] 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 788e3af226..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,12 +1,13 @@ --- -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. @@ -18,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 @@ -38,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/v-version-number.md b/docs/build/reference/v-version-number.md index 8880f685ea..1ca90f5449 100644 --- a/docs/build/reference/v-version-number.md +++ b/docs/build/reference/v-version-number.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /V (Version Number)" title: "/V (Version Number)" ms.date: "11/04/2016" f1_keywords: ["/v"] @@ -32,11 +33,9 @@ The **/V** option is deprecated beginning in Visual Studio 2005; **/V** was prim 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 **C/C++** folder. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Click the **Command Line** property page. - -1. Type the compiler option in the **Additional Options** box. +1. Enter the compiler option in the **Additional Options** box. ### To set this compiler option programmatically 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 68eb322e49..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,42 +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 **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. Expand the **Configuration Properties**, **C/C++**, **Command Line** folder. +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-edit-control.md b/docs/build/reference/value-edit-control.md index 3a45a06b83..2d4fa684d7 100644 --- a/docs/build/reference/value-edit-control.md +++ b/docs/build/reference/value-edit-control.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Value Edit Control" title: "Value Edit Control" ms.date: "11/04/2016" helpviewer_keywords: ["Value edit control"] diff --git a/docs/build/reference/value-visual-cpp.md b/docs/build/reference/value-visual-cpp.md index 13feab67d2..86aaa58d08 100644 --- a/docs/build/reference/value-visual-cpp.md +++ b/docs/build/reference/value-visual-cpp.md @@ -1,28 +1,29 @@ --- -title: "<value> (C++ Documentation Comments)" -ms.date: "11/04/2016" -f1_keywords: ["value", ""] +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 @@ -50,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 1b9a5c59f6..4b5daa513b 100644 --- a/docs/build/reference/vcpp-directories-property-page.md +++ b/docs/build/reference/vcpp-directories-property-page.md @@ -1,31 +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. Right-click on a project node (not the top-level solution) and choose **Properties**. -1. In the left pane of the **Property Pages** dialog box, select **Configuration Properties** > **VC++ Directories**. +1. If the **Solution Explorer** window isn't visible, choose **View** > **Solution Explorer** on the main menu. -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: +1. Right-click on a project node (not the top-level solution) and choose **Properties** to open the **Property Pages** dialog box. -![Select the project node](../media/vcppdir.png "Select the project node to see the VC++ Directories properties") +1. Select the **Configuration Properties** > **VC++ Directories** property page. -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). +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: -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). +:::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::: -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 **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'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. To view the values for any of the directories: @@ -33,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 these blog posts: [VC++ Directories](https://docs.microsoft.com/archive/blogs/vsproject/vc-directories), [Inherited Properties and Property Sheets](https://docs.microsoft.com/cpp/build/project-property-inheritance), and [Visual Studio 2010 C++ Project Upgrade Guide](https://devblogs.microsoft.com/cppblog/visual-studio-2010-c-project-upgrade-guide/). +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 e0023dd122..0ce1e28fb5 100644 --- a/docs/build/reference/vcxproj-file-structure.md +++ b/docs/build/reference/vcxproj-file-structure.md @@ -1,44 +1,60 @@ --- title: ".vcxproj and .props file structure" -ms.date: "05/16/2019" +description: "How the C++ native MSBuild project system .vcxproj and .props files store project information." +ms.date: 11/14/2022 helpviewer_keywords: [".vcxproj file structure"] ms.assetid: 14d0c552-29db-480e-80c1-7ea89d6d8e9c --- -# .vcxproj and .props file structure +# `.vcxproj` and `.props` file structure -[MSBuild](../msbuild-visual-cpp.md) is the default project system in Visual Studio; when you choose **File** > **New Project** in Visual C++ you are 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. In most cases, you never need to manually edit the project file, and in fact you should not edit it manually unless you have a good understanding of MSBuild. Whenever possible you should use the Visual Studio property pages to modify project settings (see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). However, in some cases you may need to modify a project file or property sheet manually. For those scenarios, this article contains basic information about the structure of the file. +[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. -**Important:** +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 choose to manually edit a .vcxproj file, be aware of these facts: +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. -1. The structure of the file must follow a prescribed form, which is described in this article. +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. -1. The Visual Studio C++ project system currently does not support wildcards in project items. For example, this is not supported: +For manual editing scenarios, this article contains basic information about the structure of *`.vcxproj`* and related files. + +## Important considerations + +If you choose to manually edit a *`.vcxproj`* file, be aware of these facts: + +- The structure of the file must follow a prescribed form, which is described in this article. + +- The Visual Studio C++ project system currently doesn't support wildcards or lists directly in project items. For example, these forms aren't supported: ```xml - + + + + ``` -1. The Visual Studio C++ project system currently does not support macros in project item paths. For example, this is not supported: + For more information on wildcard support in projects and possible workarounds, see [`.vcxproj` files and wildcards](vcxproj-files-and-wildcards.md). + +- The Visual Studio C++ project system currently doesn't support macros in project item paths. For example, this form isn't supported: ```xml - + + + ``` - "Not supported" means that macros are not guaranteed to work for all operations in the IDE. Macros which 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 which change their value for different configurations will cause problems 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. -1. In order to have project properties correctly added, removed, or modified when edited in the **Project Properties** dialog, the file must contain separate groups for each project configuration, and the conditions must be in this form: +- 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: ```xml Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'" ``` -1. Each property must be specified in the group with correct label, as specified in the property rule file. For more information, see [Property page xml rule files](property-page-xml-files.md). +- Each property must be specified in the group with its correct label, as specified in the property rule file. For more information, see [Property page xml rule files](property-page-xml-files.md). -## .vcxproj file elements +## `.vcxproj` file elements -You can inspect the contents of a .vcxproj file by using any text or XML editor. You can view it in Visual Studio by right-clicking on the project in Solution Explorer, choosing **Unload project** and then choosing **Edit Foo.vcxproj**. +You can inspect the contents of a *`.vcxproj`* file by using any text or XML editor. You can view it in Visual Studio by right-clicking on the project in Solution Explorer, choosing **Unload project** and then choosing **Edit Foo.vcxproj**. The first thing to notice is that the top-level elements appear in a particular order. For example: @@ -48,14 +64,14 @@ The first thing to notice is that the top-level elements appear in a particular - There are multiple property groups, each with a unique label, and they occur in a particular order. -The order of elements in the project file is very important, because MSBuild is based on a sequential evaluation model. If your project file, including all the imported .props and .targets files, consists of multiple definitions of a property, the last definition overrides the preceding ones. In the following example, the value "xyz" will be set during compilation because the MSBUild engine encounters it last during its evaluation. +The order of elements in the project file is vitally important, because MSBuild is based on a sequential evaluation model. If your project file, including all the imported *`.props`* and *`.targets`* files, consists of multiple definitions of a property, the last definition overrides the preceding ones. In the following example, the value "xyz" will be set during compilation because the MSBUild engine encounters it last during its evaluation. ```xml abc xyz ``` -The following snippet shows a minimal .vcxproj file. Any .vcxproj file generated by Visual Studio will contain these top-level MSBuild elements and they will appear in this order (although they may contain multiple copies of each such top-level element). Note that `Label` attributes are arbitrary tags that are only used by Visual Studio as signposts for editing; they have no other function. +The following snippet shows a minimal *`.vcxproj`* file. Any *`.vcxproj`* file generated by Visual Studio will contain these top-level MSBuild elements. And, they'll appear in this order, although they may contain multiple copies of each such top-level element. Any `Label` attributes are arbitrary tags that are only used by Visual Studio as signposts for editing; they have no other function. ```xml @@ -75,7 +91,7 @@ The following snippet shows a minimal .vcxproj file. Any .vcxproj file generated ``` -The following sections describe the purpose of each of these elements and why they are ordered this way: +The following sections describe the purpose of each of these elements and why they're ordered this way: ### Project element @@ -83,7 +99,7 @@ The following sections describe the purpose of each of these elements and why th ``` -`Project` is the root node. It specifies the MSBuild version to use and also the default target to be executed when this file is passed to MSBuild.exe. +`Project` is the root node. It specifies the MSBuild version to use and also the default target to execute when this file gets passed to MSBuild.exe. ### ProjectConfigurations ItemGroup element @@ -91,13 +107,13 @@ The following sections describe the purpose of each of these elements and why th ``` -`ProjectConfigurations` contains the project configuration description. Examples are Debug|Win32, Release|Win32, Debug|ARM and so on. Many project settings are specific to a given configuration. For example, you will probably want to set optimization properties for a release build but not a debug build. +`ProjectConfigurations` contains the project configuration description. Examples are Debug|Win32, Release|Win32, Debug|ARM and so on. Many project settings are specific to a given configuration. For example, you'll probably want to set optimization properties for a release build but not a debug build. -The `ProjectConfigurations` item group is not used at build time. The Visual Studio IDE requires it in order to load the project. This item group can be moved to a .props file and imported into the .vcxproj file. However, in that case, if you need to add or remove configurations, you must manually edit the .props file; you can't use the IDE. +The `ProjectConfigurations` item group isn't used at build time. The Visual Studio IDE requires it to load the project. This item group can be moved to a *`.props`* file and imported into the *`.vcxproj`* file. However, in that case, if you need to add or remove configurations, you must manually edit the *`.props`* file; you can't use the IDE. ### ProjectConfiguration elements -The following snippet shows a project configuration. In this example 'Debug|x64' is the configuration name. The project configuration name must be in the format $(Configuration)|$(Platform). A Project Configuration node can have two properties: Configuration and Platform. Those properties will be automatically set with the values specified here when the configuration is active. +The following snippet shows a project configuration. In this example, 'Debug|x64' is the configuration name. The project configuration name must be in the format `$(Configuration)|$(Platform)`. A `ProjectConfiguration` node can have two properties: `Configuration` and `Platform`. Those properties get set automatically with the values specified here when the configuration is active. ```xml @@ -106,7 +122,7 @@ The following snippet shows a project configuration. In this example 'Debug|x64' ``` -The IDE expects to find a project configuration for any combination of Configuration and Platform values used in all ProjectConfiguration items. This often means that a project might have meaningless project configurations to fulfill this requirement. For instance, if a project has these configurations: +The IDE expects to find a project configuration for any combination of `Configuration` and `Platform` values used in all `ProjectConfiguration` items. Often, it means that a project might have meaningless project configurations to fulfill this requirement. For instance, if a project has these configurations: - Debug|Win32 @@ -130,7 +146,7 @@ You can disable the build and deploy commands for any configuration in the **Sol ``` -`Globals` contains project level settings such as ProjectGuid, RootNamespace, and ApplicationType/ ApplicationTypeRevision. The last two often define the target OS. A project can only target a single OS due to the fact that references and project items cannot have conditions currently. These properties are typically not overridden elsewhere in the project file. This group is not configuration-dependent and therefore typically only one Globals group exists in the project file. +`Globals` contains project level settings such as `ProjectGuid`, `RootNamespace`, and `ApplicationType` or `ApplicationTypeRevision`. The last two often define the target OS. A project can only target a single OS because currently, references and project items can't have conditions. These properties are typically not overridden elsewhere in the project file. This group isn't configuration-dependent, and typically only one `Globals` group exists in the project file. ### Microsoft.Cpp.default.props Import element @@ -138,7 +154,7 @@ You can disable the build and deploy commands for any configuration in the **Sol ``` -The **Microsoft.Cpp.default.props** property sheet comes with Visual Studio and cannot be modified. It contains the default settings for the project. The defaults might vary depending on the ApplicationType. +The **Microsoft.Cpp.default.props** property sheet comes with Visual Studio and can't be modified. It contains the default settings for the project. The defaults might vary depending on the ApplicationType. ### Configuration PropertyGroup elements @@ -146,7 +162,7 @@ The **Microsoft.Cpp.default.props** property sheet comes with Visual Studio and ``` -A `Configuration` property group has an attached configuration condition (such as `Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'"`) and comes in multiple copies, one per configuration. This property group hosts the properties that are set for a specific configuration. Configuration properties include PlatformToolset and also control the inclusion of system property sheets in **Microsoft.Cpp.props**. For example, if you define the property `Unicode`, then the system property sheet **microsoft.Cpp.unicodesupport.props** will be included. If you inspect **Microsoft.Cpp.props**, you will see the line: +A `Configuration` property group has an attached configuration condition (such as `Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'"`) and comes in multiple copies, one per configuration. This property group hosts the properties that are set for a specific configuration. Configuration properties include PlatformToolset and also control the inclusion of system property sheets in **Microsoft.Cpp.props**. For example, if you define the property `Unicode`, then the system property sheet **microsoft.Cpp.unicodesupport.props** will be included. If you inspect **Microsoft.Cpp.props**, you'll see the line: ``. ### Microsoft.Cpp.props Import element @@ -155,7 +171,7 @@ A `Configuration` property group has an attached configuration condition (such a ``` -The **Microsoft.Cpp.props** property sheet (directly or via imports) defines the default values for many tool-specific properties such as the compiler's Optimization and Warning Level properties, the MIDL tool's TypeLibraryName property, and so on. It also imports various system property sheets based on which configuration properties are defined in the property group immediately above. +The **Microsoft.Cpp.props** property sheet (directly or via imports) defines the default values for many tool-specific properties. Examples include the compiler's Optimization and Warning Level properties, the MIDL tool's TypeLibraryName property, and so on. It also imports various system property sheets based on which configuration properties are defined in the property group immediately before it. ### ExtensionSettings ImportGroup element @@ -163,7 +179,7 @@ The **Microsoft.Cpp.props** property sheet (directly or via imports) defines the ``` -The `ExtensionSettings` group contains imports for the property sheets that are part of Build Customizations. A Build Customization is defined by up to three files: a .targets file, a .props file and an .xml file. This import group contains the imports for the .props file. +The `ExtensionSettings` group contains imports for the property sheets that are part of Build Customizations. A Build Customization is defined by up to three files: a *`.targets`* file, a *`.props`* file, and an *`.xml`* file. This import group contains the imports for the *`.props`* file. ### PropertySheets ImportGroup elements @@ -171,7 +187,7 @@ The `ExtensionSettings` group contains imports for the property sheets that are ``` -The `PropertySheets` group contains the imports for user property sheets. These are the property sheets that you add through the Property Manager view in Visual Studio. The order in which these imports are listed is important and is reflected in the Property Manager. The project file normally contains multiple instances of this kind of import group, one for each project configuration. +The `PropertySheets` group contains the imports for user property sheets. These imports are the property sheets that you add through the Property Manager view in Visual Studio. The order in which these imports are listed is important and is reflected in the Property Manager. The project file normally contains multiple instances of this kind of import group, one for each project configuration. ### UserMacros PropertyGroup element @@ -179,7 +195,7 @@ The `PropertySheets` group contains the imports for user property sheets. These ``` -`UserMacros` contains properties you create as variables that are used to customize your build process. For example, you can define a user macro to define your custom output path as $(CustomOutputPath) and use it to define other variables. This property group houses such properties. Note that in Visual Studio, this group is not populated in the project file because Visual C++ does not support user macros for configurations. User macros are supported in property sheets. +`UserMacros` contains properties you create as variables that are used to customize your build process. For example, you can define a user macro to define your custom output path as $(CustomOutputPath) and use it to define other variables. This property group houses such properties. In Visual Studio, this group isn't populated in the project file because Visual C++ doesn't support user macros for configurations. User macros are supported in property sheets. ### Per-configuration PropertyGroup elements @@ -187,7 +203,7 @@ The `PropertySheets` group contains the imports for user property sheets. These ``` -There are multiple instances of this property group, one per configuration for all project configurations. Each property group must have one configuration condition attached. If any configurations are missing, the **Project Properties** dialog won't work correctly. Unlike the property groups above, this one does not have a label. This group contains project configuration-level settings. These settings apply to all files that are part of the specified item group. Build customization item definition metadata is initialized here. +There are multiple instances of this property group, one per configuration for all project configurations. Each property group must have one configuration condition attached. If any configurations are missing, the **Project Properties** dialog won't work correctly. Unlike the property groups listed before, this one doesn't have a label. This group contains project configuration-level settings. These settings apply to all files that are part of the specified item group. Build customization item definition metadata is initialized here. This PropertyGroup must come after `` and there must be no other PropertyGroup without a Label before it (otherwise Project Properties editing won't work correctly). @@ -197,7 +213,7 @@ This PropertyGroup must come after ` ``` -Defines (directly or via imports) Visual C++ targets such as build, clean, etc. +Defines (directly or through imports) C++ targets such as build, clean, and so on. ### ExtensionTargets ImportGroup element @@ -256,21 +272,21 @@ Defines (directly or via imports) Visual C++ targets such as build, clean, etc. 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 above. 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 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 above and since they generally do not define properties themselves. Likewise, user property sheets are imported after the system property sheets (included via **Microsoft.Cpp.props**). This ensures that the user can override any defaults brought in by the system property sheets. +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. -If a .vcxproj file does not follow this layout, the build results may not be what you expect. For example, if you mistakenly import a system property sheet after the property sheets defined by the user, the user settings will be overridden by the system property sheets. +If a *`.vcxproj`* file doesn't follow this layout, the build results may not be what you expect. For example, if you mistakenly import a system property sheet after the property sheets defined by the user, the user settings get overridden by the system property sheets. -Even the IDE design time experience depends to some extent on correct ordering of elements. For example, if your .vcxproj file does not have the `PropertySheets` import group, the IDE might not be able to determine where to place a new property sheet that the user has created in **Property Manager**. This could result in a user sheet being overridden by a system sheet. Although the heuristic used by IDE can tolerate minor inconsistencies in the .vcxproj file layout, it is strongly recommended not to deviate from the structure shown earlier in this article. +Even the IDE design time experience depends on some extent on correct ordering of elements. For example, if your *`.vcxproj`* file doesn't have the `PropertySheets` import group, the IDE might be unable to determine where to place a new property sheet that the user has created in **Property Manager**. It could result in a user sheet being overridden by a system sheet. Although the heuristic used by IDE can tolerate minor inconsistencies in the *`.vcxproj`* file layout, we strongly recommend you don't deviate from the structure shown earlier in this article. ## How the IDE uses element labels -In the IDE, when you set the **UseOfAtl** property in the general property page, it is written to the Configuration property group in the project file, while the **TargetName** property in the same property page is written to the label-less per-configuration property group. Visual Studio looks at the property page's xml file for the information on where to write each property. For the **General** property page (assuming you have an English version of Visual Studio 2019 Enterprise Edition), that file is `%ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\VC\VCTargets\1033\general.xml`. The property page XML rule file defines the static information about a Rule and all its properties. One such piece of information is the preferred position of a Rule property in the destination file (the file where its value will be written). The preferred position is specified by the Label attribute on the project file elements. +In the IDE, when you set the **UseOfAtl** property in the general property page, it's written to the Configuration property group in the project file. The **TargetName** property in the same property page is written to the label-less per-configuration property group. Visual Studio looks at the property page's xml file for the information on where to write each property. For the **General** property page, assuming you have an English version of Visual Studio 2019 Enterprise Edition, that file is `%ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\VC\VCTargets\1033\general.xml`. The property page XML rule file defines the static information about a Rule and all its properties. One such piece of information is the preferred position of a Rule property in the destination file (the file where its value will be written). The preferred position is specified by the Label attribute on the project file elements. ## Property Sheet layout -The following XML snippet is a minimal layout of a property sheet (.props) file. It is similar to a .vcxproj file, and the functionality of the .props elements can be inferred from the earlier discussion. +The following XML snippet is a minimal layout of a property sheet (.props) file. It's similar to a *`.vcxproj`* file, and the functionality of the *`.props`* elements can be inferred from the earlier discussion. ```xml @@ -282,9 +298,10 @@ The following XML snippet is a minimal layout of a property sheet (.props) file. ``` -To make your own property sheet, copy one of the .props files in the VCTargets folder and modify it for your purposes. For Visual Studio 2019 Enterprise edition, the default VCTargets path is `%ProgramFiles%\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\VC\VCTargets`. +To make your own property sheet, copy one of the *`.props`* files in the *`VCTargets`* folder and modify it for your purposes. For Visual Studio 2019 Enterprise edition, the default *`VCTargets`* path is `%ProgramFiles%\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\VC\VCTargets`. ## See also -[Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md)
-[Property Page XML Files](property-page-xml-files.md) +[Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md)\ +[Property Page XML Files](property-page-xml-files.md)\ +[`.vcxproj` files and wildcards](vcxproj-files-and-wildcards.md) diff --git a/docs/build/reference/vcxproj-files-and-wildcards.md b/docs/build/reference/vcxproj-files-and-wildcards.md new file mode 100644 index 0000000000..385ca604d8 --- /dev/null +++ b/docs/build/reference/vcxproj-files-and-wildcards.md @@ -0,0 +1,113 @@ +--- +title: ".vcxproj files and wildcards" +description: "How the C++ native MSBuild project system .vcxproj files handle wildcards." +ms.date: 09/30/2020 +helpviewer_keywords: [".vcxproj file structure"] +ms.assetid: 14d0c552-29db-480e-80c1-7ea89d6d8e9c +--- +# `.vcxproj` files and wildcards + +The Visual Studio IDE doesn't support certain constructs in project items in *`.vcxproj`* files. These unsupported constructs include wildcards, semi-colon delimited lists, or MSBuild macros that expand to multiple files. The `.vcxproj` project system for C++ builds is more restrictive than MSBuild. Each project item is required to have its own MSBuild item. For more information on the `.vcxproj` file format, see [`.vcxproj` and `.props` file structure](vcxproj-file-structure.md). + +These construct examples aren't supported by the IDE: + +```xml + + + + + +``` + +If a `.vcxproj` project file that includes these constructs gets loaded in the IDE, the project may seem to work at first. However, issues are likely as soon as the project is modified by Visual Studio and then saved on disk. You may experience random crashes and undefined behavior. + +In Visual Studio 2019 version 16.7, when Visual Studio loads a `.vcxproj` project file, it automatically detects unsupported entries in project items. You'll see warnings in the Output window during solution load. + +Visual Studio 2019 version 16.7 also adds read-only project support. Read-only support allows the IDE to use manually authored projects that don't have the additional limitations of IDE-editable projects. + +If you have a `.vcxproj` file that uses one or more of the unsupported constructs, you can make it load without warnings in the IDE by using one of these options: + +- List all items explicitly +- Mark your project as read-only +- Move wildcard items to a target body + +## List all items explicitly + +Currently, there's no way to make wildcard expansion items visible in the Solution Explorer window in a non-read-only project. Solution Explorer expects projects to list all items explicitly. + +To make `.vcxproj` projects automatically expand wildcards in Visual Studio 2019 version 16.7 or later, set the `ReplaceWildcardsInProjectItems` property to `true`. We recommend you create a *`Directory.Build.props`* file in a root directory, and use this content: + +```xml + + + true + + +``` + +## Mark your project as read-only + +In Visual Studio 2019 version 16.7 and later, you can mark projects as *read-only*. To mark your project read-only, add the following property to your *`.vcxproj`* file, or to any of the files it imports: + +```xml + + true + +``` + +The `` setting prevents Visual Studio from editing and saving the project, so you can use any MSBuild constructs in it, including wildcards. + +It's important to know that the project cache isn't available if Visual Studio detects wildcards in project items in the *`.vcxproj`* file or any of its imports. Solution load times in the IDE are much longer if you have lots of projects that use wildcards. + +## Move wildcard items to a target body + +You may want to use wildcards to gather resources, add generated sources, and so on. If you don't need them listed in the Solution Explorer window, you can use this procedure instead: + +1. Change the name of the item group to add wildcards. For instance, instead of: + + ```xml + + + ``` + + change it to: + + ```xml + <_WildCardImage Include="*.bmp" /> + <_WildCardClCompile Include="*.cpp" /> + ``` + +1. Add this content to your *`.vcxproj`* file. Or, add it to a *`Directory.Build.targets`* file in a root directory, to affect all projects under that root: + + ```xml + + + + + + + ``` + + This change makes the build see the items as they're defined in the *`.vcxproj`* file. However, now they aren't visible in the Solution Explorer window, and they won't cause problems in the IDE. + +1. To show correct IntelliSense for `_WildCardClCompile` items when you open those files in the editor, add the following content: + + ```xml + + + AddWildCardItems + $(ComputeCompileInputsTargets) + + + ``` + +Effectively, you can use wildcards for any items inside a target body. You can also use wildcards in an `ItemGroup` that isn't defined as a project item by a [`ProjectSchemaDefinition`](https://devblogs.microsoft.com/cppblog/vc-MSBuild-extensibility-example/). + +> [!NOTE] +> If you move wildcard includes from a *`.vcxproj`* file to an imported file, they won't be visible in the Solution Explorer window. This change also allows your project to load in the IDE without modification. However, we don't recommend this approach, because it disables the project cache. + +## See also + +[Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md)
+[Property Page XML Files](property-page-xml-files.md) 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/vd-disable-construction-displacements.md b/docs/build/reference/vd-disable-construction-displacements.md index 4cb0e61a10..e0a92f10ab 100644 --- a/docs/build/reference/vd-disable-construction-displacements.md +++ b/docs/build/reference/vd-disable-construction-displacements.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /vd (Disable Construction Displacements)" title: "/vd (Disable Construction Displacements)" ms.date: "11/04/2016" f1_keywords: ["/vd"] @@ -42,11 +43,9 @@ These options affect entire source files. Use [vtordisp](../../preprocessor/vtor 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 **C/C++** folder. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Click the **Command Line** property page. - -1. Type the compiler option in the **Additional Options** box. +1. Enter the compiler option in the **Additional Options** box. ### To set this compiler option programmatically diff --git a/docs/build/reference/verbose-print-progress-messages.md b/docs/build/reference/verbose-print-progress-messages.md index 3329843cb2..ee5e034c60 100644 --- a/docs/build/reference/verbose-print-progress-messages.md +++ b/docs/build/reference/verbose-print-progress-messages.md @@ -1,17 +1,17 @@ --- +description: "Learn more about: /VERBOSE (Print progress messages)" title: "/VERBOSE (Print progress messages)" -ms.date: "06/13/2019" +ms.date: 02/03/2021 f1_keywords: ["/verbose", "VC.Project.VCLinkerTool.ShowProgress"] helpviewer_keywords: ["-VERBOSE linker option", "linking [C++], session progress information", "Print Progress Messages linker option", "linker [C++], output dependency information", "/VERBOSE linker option", "dependencies [C++], dependency information in linker output", "VERBOSE linker option"] -ms.assetid: 9c347d98-4c37-4724-a39e-0983934693ab --- -# /VERBOSE (Print progress messages) +# `/VERBOSE` (Print progress messages) Outputs progress messages during the link process. ## Syntax -> **/VERBOSE**\[**:**{**CLR**|**ICF**|**INCR**|**LIB**|**REF**|**SAFESEH**|**UNUSEDDELAYLOAD**|**UNUSEDLIBS**}\] +> **`/VERBOSE`**\[**`:`**{**`CLR`**|**`ICF`**|**`INCR`**|**`LIB`**|**`REF`**|**`SAFESEH`**|**`UNUSEDDELAYLOAD`**|**`UNUSEDLIBS`**}\] ## Remarks @@ -19,15 +19,15 @@ The linker sends information about the progress of the linking session to the ** | Option | Description | | ------------ | ----------------- | -| /VERBOSE | Displays details about the linking process. | -| /VERBOSE:CLR | Displays information about linker activity specific to objects and metadata compiled by using [/clr](clr-common-language-runtime-compilation.md). | -| /VERBOSE:ICF | Displays information about linker activity that results from the use of [/OPT:ICF](opt-optimizations.md). | -| /VERBOSE:INCR | Displays information about the incremental link process. | -| /VERBOSE:LIB | Displays progress messages that indicate just the libraries searched.
The displayed information includes the library search process. It lists each library and object name (with full path), the symbol being resolved from the library, and a list of objects that reference the symbol. | -| /VERBOSE:REF | Displays information about linker activity that results from the use of [/OPT:REF](opt-optimizations.md). | -| /VERBOSE:SAFESEH | Displays information about modules that are incompatible with safe structured exception handling when [/SAFESEH](safeseh-image-has-safe-exception-handlers.md) isn't specified. | -| /VERBOSE:UNUSEDDELAYLOAD | Displays information about any delay loaded DLLs that have no symbols used when the image is created. | -| /VERBOSE:UNUSEDLIBS | Displays information about any library files that are unused when the image is created. | +| **`/VERBOSE`** | Displays details about the linking process. | +| **`/VERBOSE:CLR`** | Displays information about linker activity specific to objects and metadata compiled by using [`/clr`](clr-common-language-runtime-compilation.md). | +| **`/VERBOSE:ICF`** | Displays information about linker activity that results from the use of [`/OPT:ICF`](opt-optimizations.md). | +| **`/VERBOSE:INCR`** | Displays information about the incremental link process. | +| **`/VERBOSE:LIB`** | Displays progress messages that indicate just the libraries searched.
The displayed information includes the library search process. It lists each library and object name (with full path), the symbol being resolved from the library, and a list of objects that reference the symbol. | +| **`/VERBOSE:REF`** | Displays information about linker activity that results from the use of [`/OPT:REF`](opt-optimizations.md). | +| **`/VERBOSE:SAFESEH`** | Displays information about modules that are incompatible with safe structured exception handling when [`/SAFESEH`](safeseh-image-has-safe-exception-handlers.md) isn't specified. | +| **`/VERBOSE:UNUSEDDELAYLOAD`** | Displays information about any delay loaded DLLs that have no symbols used when the image is created. | +| **`/VERBOSE:UNUSEDLIBS`** | Displays information about any library files that are unused when the image is created. | ### To set this linker option in the Visual Studio development environment diff --git a/docs/build/reference/version-c-cpp.md b/docs/build/reference/version-c-cpp.md index 588a4e02d0..7218157640 100644 --- a/docs/build/reference/version-c-cpp.md +++ b/docs/build/reference/version-c-cpp.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: VERSION (C/C++)" title: "VERSION (C/C++)" ms.date: "11/04/2016" f1_keywords: ["VERSION"] diff --git a/docs/build/reference/version-version-information.md b/docs/build/reference/version-version-information.md index a7ba10017e..d4ab8a430e 100644 --- a/docs/build/reference/version-version-information.md +++ b/docs/build/reference/version-version-information.md @@ -1,38 +1,35 @@ --- -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 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 **General** property page. +1. Select the **Configuration Properties** > **Linker** > **General** property page. 1. Modify the **Version** property. @@ -42,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/version.md b/docs/build/reference/version.md index 8bd929dd24..0e7ca713a9 100644 --- a/docs/build/reference/version.md +++ b/docs/build/reference/version.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /VERSION" title: "/VERSION" ms.date: "11/04/2016" f1_keywords: ["/version_editbin"] diff --git a/docs/build/reference/visual-cpp-project-types.md b/docs/build/reference/visual-cpp-project-types.md index 2db0b545b2..41e998d56e 100644 --- a/docs/build/reference/visual-cpp-project-types.md +++ b/docs/build/reference/visual-cpp-project-types.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: C++ project templates" title: "Visual C++ Project Types" ms.date: "08/13/2019" helpviewer_keywords: ["programs [C++], projects", "project templates [Visual Studio], C++", "TODO comments [C++]", "projects [C++], types", "templates [C++], projects", "applications [C++], projects", "C++ projects, types"] @@ -19,10 +20,10 @@ The project templates included in Visual Studio depend on the product version an |Project template|Description| |----------------------|-----------------------------| -|[Windows Console Application](../../windows/creating-a-console-application.md)|A project for creating a Windows console application.| +|[Windows Console Application](../../windows/overview-of-windows-programming-in-cpp.md)|A project for creating a Windows console application.| |[Windows Desktop Application](../../windows/walkthrough-creating-windows-desktop-applications-cpp.md)|A project for creating a Windows desktop (Win32) application.| |[Dynamic-Link Library](../walkthrough-creating-and-using-a-dynamic-link-library-cpp.md)|A project for creating a dynamic-link library (DLL).| -|[Static Library](../../windows/walkthrough-creating-and-using-a-static-library-cpp.md)|A project for creating a static library (LIB).| +|[Static Library](../walkthrough-creating-and-using-a-static-library-cpp.md)|A project for creating a static library (LIB).| |[Windows Desktop Wizard](../../windows/windows-desktop-wizard.md)|A wizard for creating Windows desktop applications and libraries with additional options.| ### General 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/vmb-vmg-representation-method.md b/docs/build/reference/vmb-vmg-representation-method.md index 3e0c56a35b..cf11b63443 100644 --- a/docs/build/reference/vmb-vmg-representation-method.md +++ b/docs/build/reference/vmb-vmg-representation-method.md @@ -1,38 +1,36 @@ --- +description: "Learn more about: /vmb, /vmg (Representation method)" title: "/vmb, /vmg (Representation Method)" -ms.date: "11/04/2016" +ms.date: 04/12/2021 f1_keywords: ["/vmb", "/vmg"] helpviewer_keywords: ["vmb compiler option [C++]", "-vmg compiler option [C++]", "vmg compiler option [C++]", "-vmb compiler option [C++]", "/vmb compiler option [C++]", "representation method compiler options [C++]", "/vmg compiler option [C++]"] -ms.assetid: ecdb391c-7dab-40b1-916b-673d10889fd4 --- -# /vmb, /vmg (Representation Method) +# `/vmb`, `/vmg` (Representation method) Select the method that the compiler uses to represent pointers to class members. -Use **/vmb** if you always define a class before you declare a pointer to a member of the class. +## Syntax -Use **/vmg** to declare a pointer to a member of a class before defining the class. This need can arise if you define members in two different classes that reference each other. For such mutually referencing classes, one class must be referenced before it is defined. +> **`/vmb`**\ +> **`/vmg`** -## Syntax +### Options -``` -/vmb -/vmg -``` +**`/vmb`** is the compiler's default behavior. Its behavior is the same as `#pragma pointers_to_members(best_case)`. It doesn't require or ensure complete types. For complete types, it uses the best representation among single, multiple, or virtual inheritance based the inheritance of the class type. For incomplete types, it uses the largest, most general representation. + +**`/vmg`** lets you specify compiler behavior in combination with [`/vmm`, `/vms`, `/vmv` (General purpose representation)](./vmm-vms-vmv-general-purpose-representation.md) to declare a pointer to a member of a class before defining the class. This need can arise if you define members in two different classes that reference each other. For such mutually referencing classes, one class must be referenced before it's defined. ## Remarks -You can also use [pointers_to_members](../../preprocessor/pointers-to-members.md) or [Inheritance Keywords](../../cpp/inheritance-keywords.md) in your code to specify a pointer representation. +You can also use [`#pragma pointers_to_members`](../../preprocessor/pointers-to-members.md) or [Inheritance keywords](../../cpp/inheritance-keywords.md) in your code to specify a pointer representation. ### 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. Click the **C/C++** folder. - -1. Click the **Command Line** property page. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Type the compiler option in the **Additional Options** box. +1. Enter the compiler option in the **Additional Options** box. ### To set this compiler option programmatically @@ -40,5 +38,5 @@ You can also use [pointers_to_members](../../preprocessor/pointers-to-members.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/vmm-vms-vmv-general-purpose-representation.md b/docs/build/reference/vmm-vms-vmv-general-purpose-representation.md index d4572b1d4b..eb33799c9c 100644 --- a/docs/build/reference/vmm-vms-vmv-general-purpose-representation.md +++ b/docs/build/reference/vmm-vms-vmv-general-purpose-representation.md @@ -1,43 +1,58 @@ --- -title: "/vmm, -vms, -vmv (General Purpose Representation)" -ms.date: "11/04/2016" +description: "Learn more about: /vmm, /vms, /vmv (General Purpose Representation)" +title: "/vmm, /vms, /vmv (General Purpose Representation)" +ms.date: 04/12/2021 f1_keywords: ["/vms", "/vmm", "/vmv"] helpviewer_keywords: ["Virtual Inheritance compiler option", "general purpose representation compiler options", "vms compiler option [C++]", "vmm compiler option [C++]", "/vmm compiler option [C++]", "-vmm compiler option [C++]", "-vms compiler option [C++]", "/vms compiler option [C++]", "vmv compiler option [C++]", "/vmv compiler option [C++]", "Single Inheritance compiler option", "-vmv compiler option [C++]"] -ms.assetid: 0fcd7ae0-3031-4c62-a2a8-e154c8685dae --- -# /vmm, /vms, /vmv (General Purpose Representation) +# `/vmm`, `/vms`, `/vmv` (General Purpose Representation) -Used when [/vmb, /vmg (Representation Method)](vmb-vmg-representation-method.md) is selected as the [representation method](vmb-vmg-representation-method.md). These options indicate the inheritance model of the not-yet-encountered class definition. +Used when [`/vmg`](vmb-vmg-representation-method.md) is selected as the [representation method](vmb-vmg-representation-method.md). These options indicate the inheritance model of the not-yet-encountered class definition. ## Syntax -``` -/vmm -/vms -/vmv -``` +> **`/vmm`**\ +> **`/vms`**\ +> **`/vmv`** -## Remarks +### Options + +**`/vmm`**\ +Specifies the most general representation of a pointer to a member of a class as one that uses multiple inheritance. + +The corresponding [inheritance keyword](../../cpp/inheritance-keywords.md) and argument to [`#pragma pointers_to_members`](../../preprocessor/pointers-to-members.md) is **`multiple_inheritance`**. + +This representation is larger than the one required for single inheritance. + +If you use **`/vmm`** and declare a pointer to member of a class that has a virtual inheritance model, the compiler generates an error. + +**`/vms`**\ +Specifies the most general representation of a pointer to a member of a class as one that uses either no inheritance or single inheritance.The corresponding [inheritance keyword](../../cpp/inheritance-keywords.md) and argument to [`#pragma pointers_to_members`](../../preprocessor/pointers-to-members.md) is **`single_inheritance`**. + +This option generates the smallest possible representation of a pointer to a member of a class. -The options are described in the following table. +If you use **`/vms`** and declare a pointer to member of a class that has a multiple or virtual inheritance model, the compiler generates an error. -|Option|Description| -|------------|-----------------| -|**/vmm**|Specifies the most general representation of a pointer to a member of a class to be one that uses multiple inheritance.

The corresponding [inheritance keyword](../../cpp/inheritance-keywords.md) and argument to [#pragma pointers_to_members](../../preprocessor/pointers-to-members.md) is **multiple_inheritance**.

This representation is larger than that required for single inheritance.

If the inheritance model of a class definition for which a pointer to a member is declared is virtual, the compiler generates an error.| -|**/vms**|Specifies the most general representation of a pointer to a member of a class to be one that uses either no inheritance or single inheritance.

The corresponding [inheritance keyword](../../cpp/inheritance-keywords.md) and argument to [#pragma pointers_to_members](../../preprocessor/pointers-to-members.md) is **single_inheritance**.

This is the smallest possible representation of a pointer to a member of a class.

If the inheritance model of a class definition for which a pointer to a member is declared is multiple or virtual, the compiler generates an error.| -|**/vmv**|Specifies the most general representation of a pointer to a member of a class to be one that uses virtual inheritance. It never causes an error and is the default.

The corresponding [inheritance keyword](../../cpp/inheritance-keywords.md) and argument to [#pragma pointers_to_members](../../preprocessor/pointers-to-members.md) is **virtual_inheritance**.

This option requires a larger pointer and additional code to interpret the pointer than the other options.| +**`/vmv`**\ +Specifies the most general representation of a pointer to a member of a class as one that uses virtual inheritance. This pointer representation never causes an error and is the default. -When you specify one of these inheritance-model options, that model is used for all pointers to class members, regardless of their inheritance type or whether the pointer is declared before or after the class. Therefore, if you always use single-inheritance classes, you can reduce code size by compiling with **/vms**; however, if you want to use the most general case (at the expense of the largest data representation), compile with **/vmv**. +The corresponding [inheritance keyword](../../cpp/inheritance-keywords.md) and argument to [`#pragma pointers_to_members`](../../preprocessor/pointers-to-members.md) is **`virtual_inheritance`**. + +This option requires a larger pointer and more code to interpret the pointer than the other options. + +## Remarks + +In Visual Studio 2019 and earlier versions, Microsoft uses different representations (of different sizes) for pointer-to-member types. Pointers to members of classes that have no inheritance or single inheritance have the smallest representation. Pointers to members of classes that have multiple inheritance are larger. Pointers to members of classes that have virtual inheritance are the largest. When no representation model is specified to the compiler, it defaults to using the largest, most general representation. + +When you specify one of these inheritance-model options, that model gets used for all pointers to class members, no matter their inheritance type or whether you declare the pointer before or after the class. If you always use single-inheritance classes, you can reduce code size by compiling with **`/vms`**. However, if you want to use the most general case (at the expense of the largest data representation), compile with **`/vmv`**. ### 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. Click the **C/C++** folder. - -1. Click the **Command Line** property page. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Type the compiler option in the **Additional Options** box. +1. Enter the compiler option in the **Additional Options** box. ### To set this compiler option programmatically @@ -45,6 +60,6 @@ When you specify one of these inheritance-model options, that model is used for ## See also -[/vmb, /vmg (Representation Method)](vmb-vmg-representation-method.md)
-[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) +[`/vmb`, `/vmg` (Representation method)](vmb-vmg-representation-method.md)
+[MSVC compiler options](compiler-options.md)
+[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/volatile-volatile-keyword-interpretation.md b/docs/build/reference/volatile-volatile-keyword-interpretation.md index a8e4df57ca..8e54521e89 100644 --- a/docs/build/reference/volatile-volatile-keyword-interpretation.md +++ b/docs/build/reference/volatile-volatile-keyword-interpretation.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /volatile (volatile Keyword Interpretation)" title: "/volatile (volatile Keyword Interpretation)" ms.date: "11/04/2016" f1_keywords: ["/volatile:iso", "/volatile:ms", "/volatile"] @@ -16,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/web-references-property-page.md b/docs/build/reference/web-references-property-page.md index 7d3c758951..c2f4a05af6 100644 --- a/docs/build/reference/web-references-property-page.md +++ b/docs/build/reference/web-references-property-page.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Web References Property Page" title: "Web References Property Page" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCSDLTool.Output", "VC.Project.VCWebServiceProxyGeneratorTool.SuppressStartupBanner", "VC.Project.VCWebServiceProxyGeneratorTool.Output", "VC.Project.VCWebServiceProxyGeneratorTool.GeneratedProxyLanguage"] 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 cab79d016d..0000000000 --- a/docs/build/reference/where-to-define-macros.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -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 28896f86ba..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,7 +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) @@ -14,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 **Command Line** property page under **Configuration Properties**, **Linker**. - -1. Add the /WHOLEARCHIVE option to the **Additional Options** text box. +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 d6aef3eb4f..0000000000 --- a/docs/build/reference/wildcards-and-nmake.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -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 344638f5e7..4694f1f317 100644 --- a/docs/build/reference/winmd-generate-windows-metadata.md +++ b/docs/build/reference/winmd-generate-windows-metadata.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /WINMD (Generate Windows Metadata)" title: "/WINMD (Generate Windows Metadata)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCLinkerTool.GenerateWindowsMetadata"] @@ -23,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/winmddelaysign-partially-sign-a-winmd.md b/docs/build/reference/winmddelaysign-partially-sign-a-winmd.md index e711d9ce04..5a7b418502 100644 --- a/docs/build/reference/winmddelaysign-partially-sign-a-winmd.md +++ b/docs/build/reference/winmddelaysign-partially-sign-a-winmd.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /WINMDDELAYSIGN (Partially Sign a winmd)" title: "/WINMDDELAYSIGN (Partially Sign a winmd)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCLinkerTool.WINMDDelaySign"] @@ -20,9 +21,7 @@ Resembles the [/DELAYSIGN](delaysign-partially-sign-an-assembly.md) linker optio 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. Select the **Windows Metadata** property page. +1. Select the **Configuration Properties** > **Linker** > **Windows Metadata** property page. 1. In the **Windows Metadata Delay Sign** drop-down list box, select the option you want. diff --git a/docs/build/reference/winmdfile-specify-winmd-file.md b/docs/build/reference/winmdfile-specify-winmd-file.md index cfa861ff0a..69f135c446 100644 --- a/docs/build/reference/winmdfile-specify-winmd-file.md +++ b/docs/build/reference/winmdfile-specify-winmd-file.md @@ -1,33 +1,36 @@ --- 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 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. Select the **Windows Metadata** property page. +1. Select the **Configuration Properties** > **Linker** > **Windows Metadata** property page. 1. In the **Windows Metadata File** box, enter the file location. ## 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/winmdkeycontainer-specify-key-container.md b/docs/build/reference/winmdkeycontainer-specify-key-container.md index d6bb2f4f45..f6d8d3fa7d 100644 --- a/docs/build/reference/winmdkeycontainer-specify-key-container.md +++ b/docs/build/reference/winmdkeycontainer-specify-key-container.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /WINMDKEYCONTAINER (Specify Key Container)" title: "/WINMDKEYCONTAINER (Specify Key Container)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCLinkerTool.WINMDKEYCONTAINER"] @@ -20,9 +21,7 @@ Resembles the [/KEYCONTAINER](keycontainer-specify-a-key-container-to-sign-an-as 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. Select the **Windows Metadata** property page. +1. Select the **Configuration Properties** > **Linker** > **Windows Metadata** property page. 1. In the **Windows Metadata Key Container** box, enter the location. diff --git a/docs/build/reference/winmdkeyfile-specify-winmd-key-file.md b/docs/build/reference/winmdkeyfile-specify-winmd-key-file.md index 1a3d2f3bfe..e007127f70 100644 --- a/docs/build/reference/winmdkeyfile-specify-winmd-key-file.md +++ b/docs/build/reference/winmdkeyfile-specify-winmd-key-file.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /WINMDKEYFILE (Specify winmd Key File)" title: "/WINMDKEYFILE (Specify winmd Key File)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCLinkerTool.WINMDKeyFile"] @@ -20,9 +21,7 @@ Resembles the [/KEYFILE](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md) 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. Select the **Windows Metadata** property page. +1. Select the **Configuration Properties** > **Linker** > **Windows Metadata** property page. 1. In the **Windows Metadata Key File** box, enter the file location. diff --git a/docs/build/reference/wl-enable-one-line-diagnostics.md b/docs/build/reference/wl-enable-one-line-diagnostics.md index 619bd83eb0..ce71a6db76 100644 --- a/docs/build/reference/wl-enable-one-line-diagnostics.md +++ b/docs/build/reference/wl-enable-one-line-diagnostics.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /WL (Enable One-Line Diagnostics)" title: "/WL (Enable One-Line Diagnostics)" ms.date: "11/04/2016" f1_keywords: ["/wl"] @@ -17,9 +18,9 @@ Appends additional information to an error or warning message. ## Remarks -Error and warning messages from the C++ compiler can be followed by additional information that appears, by default, on a new line. When you compile from the command line, the additional line of information can be appended to the error or warning message. This might be desirable if you capture your build output to a log file and then process that log to find all errors and warnings. A semicolon will separate the error or warning message from the additional line. +Error and warning messages from the C++ compiler can be followed by additional information that appears, by default, on a new line. When you compile from the command line, the extra line of information can be appended to the error or warning message. It's useful if you capture your build output to a log file and then process that log to find all errors and warnings. A semicolon will separate the error or warning message from the additional line. -Not all error and warning messages have an additional line of information. The following code will generate an error that has an additional line of information; it will let you test the effect when you use **/WL**. +Not all error and warning messages have an extra line of information. The following code will generate an error that has another line of information. It lets you test the effect when you use **/WL**. ```cpp // compiler_option_WL.cpp @@ -35,11 +36,9 @@ int main() { 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 **C/C++** folder. +1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. -1. Click the **Command Line** property page. - -1. Type the compiler option in the **Additional Options** box. +1. Enter the compiler option in the **Additional Options** box. ### To set this compiler option programmatically diff --git a/docs/build/reference/working-with-import-libraries-and-export-files.md b/docs/build/reference/working-with-import-libraries-and-export-files.md index 1f66797227..975c1dd783 100644 --- a/docs/build/reference/working-with-import-libraries-and-export-files.md +++ b/docs/build/reference/working-with-import-libraries-and-export-files.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Working with Import Libraries and Export Files" title: "Working with Import Libraries and Export Files" ms.date: "11/04/2016" helpviewer_keywords: ["LIB [C++], /DEF option", "import libraries", "LIB [C++], import libraries and export files", "export files", "import libraries, creating"] diff --git a/docs/build/reference/wp64-detect-64-bit-portability-issues.md b/docs/build/reference/wp64-detect-64-bit-portability-issues.md index a4e67a8bb3..f4d3b6b8a1 100644 --- a/docs/build/reference/wp64-detect-64-bit-portability-issues.md +++ b/docs/build/reference/wp64-detect-64-bit-portability-issues.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Wp64 (Detect 64-Bit Portability Issues)" title: "/Wp64 (Detect 64-Bit Portability Issues)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCCLWCECompilerTool.Detect64BitPortabilityProblems", "VC.Project.VCCLCompilerTool.Detect64BitPortabilityProblems", "/wp64"] @@ -34,13 +35,9 @@ If you regularly compile your application by using a compiler that builds 64-bit ### To set this compiler option in the Visual Studio development environment -1. Open the project **Property Pages** dialog box. +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). - For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). - -1. Click the **C/C++** folder. - -1. Click the **Command Line** property page. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. 1. Modify the **Additional Options** box to include **/Wp64**. 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 a4541cd571..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,39 +1,50 @@ --- -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 is similar to **/WX** for the compiler (see [/w, /W0, /W1, /W2, /W3, /W4, /w1, /w2, /w3, /w4, /Wall, /wd, /we, /wo, /Wv, /WX (Warning Level)](compiler-option-warning-level.md) for more information). However, specifying **/WX** for the compilation does not 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. Click the **Linker** folder. +1. To set specific warnings as errors, select the **Configuration Properties** > **Linker** > **Command Line** property page. -1. Click the **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. Type 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/x-ignore-standard-include-paths.md b/docs/build/reference/x-ignore-standard-include-paths.md index bf8c2c21c2..3fc6311e0d 100644 --- a/docs/build/reference/x-ignore-standard-include-paths.md +++ b/docs/build/reference/x-ignore-standard-include-paths.md @@ -1,13 +1,14 @@ --- +description: "Learn more about: `/X` (Ignore standard include paths)" title: "/X (Ignore standard include paths)" -ms.date: 07/31/2020 +ms.date: 01/21/2021 f1_keywords: ["/x", "VC.Project.VCCLCompilerTool.OVERWRITEStandardIncludePath", "VC.Project.VCCLWCECompilerTool.OVERWRITEStandardIncludePath", "VC.Project.VCCLCompilerTool.IgnoreStandardIncludePath"] helpviewer_keywords: ["/X compiler option [C++]", "include files, ignore standard path", "-X compiler option [C++]", "include directories, ignore standard", "X compiler option", "Ignore Standard Include Paths compiler option"] ms.assetid: 16bdf2cc-c8dc-46e4-bdcc-f3caeba5e1ef --- # `/X` (Ignore standard include paths) -Prevents the compiler from searching for include files in directories specified in the PATH and INCLUDE environment variables. +Prevents the compiler from searching for include files in directories specified in the `PATH` and `INCLUDE` environment variables. ## Syntax @@ -31,7 +32,7 @@ You can use this option with the [`/I` (Additional include directories)](i-addit ## Example -In the following command, **`/X`** tells the compiler to ignore locations specified by the PATH and INCLUDE environment variables, and **`/I`** specifies the directory to look in for include files: +In the following command, **`/X`** tells the compiler to ignore locations specified by the `PATH` and `INCLUDE` environment variables, and **`/I`** specifies the directory to look in for include files: ```cmd CL /X /I \ALT\INCLUDE MAIN.C diff --git a/docs/build/reference/xdcmake-reference.md b/docs/build/reference/xdcmake-reference.md index 5a55b0fa1f..64bb96cb6d 100644 --- a/docs/build/reference/xdcmake-reference.md +++ b/docs/build/reference/xdcmake-reference.md @@ -1,50 +1,51 @@ --- +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). -1. Open the **Configuration Properties** folder. +1. Select the **Configuration Properties** > **XML Document Comments** property page. -1. Click the **XML Document Comments** property page. +1. Enter options in the property page. > [!NOTE] > xdcmake.exe options at the command line differ from the options when xdcmake.exe is used in the development environment (property pages). For information on using xdcmake.exe in the development environment, see [XML Document Generator Tool Property Pages](xml-document-generator-tool-property-pages.md). ## 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-data-generator-tool-property-page.md b/docs/build/reference/xml-data-generator-tool-property-page.md index cda862dd7a..02e4a3d3b5 100644 --- a/docs/build/reference/xml-data-generator-tool-property-page.md +++ b/docs/build/reference/xml-data-generator-tool-property-page.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: XML Data Generator Tool Property Page" title: "XML Data Generator Tool Property Page" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCXMLDataGeneratorTool.GeneratedProxyLanguage", "VC.Project.VCXMLDataGeneratorTool.Output", "VC.Project.VCXMLDataGeneratorTool.SuppressStartupBanner"] 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 2d8204632b..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,15 +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 @@ -19,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 f061dae0d3..8bb4f674c0 100644 --- a/docs/build/reference/xml-documentation-visual-cpp.md +++ b/docs/build/reference/xml-documentation-visual-cpp.md @@ -1,37 +1,38 @@ --- -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/y-ignore-precompiled-header-options.md b/docs/build/reference/y-ignore-precompiled-header-options.md index 8a92b876dc..58eb9c6d7e 100644 --- a/docs/build/reference/y-ignore-precompiled-header-options.md +++ b/docs/build/reference/y-ignore-precompiled-header-options.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Y- (Ignore Precompiled Header Options)" title: "/Y- (Ignore Precompiled Header Options)" ms.date: "11/04/2016" f1_keywords: ["/y-"] @@ -27,11 +28,9 @@ For more information on precompiled headers, see: 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 **C/C++** folder. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Click the **Command Line** property page. - -1. Type the compiler option in the **Additional Options** box. +1. Enter the compiler option in the **Additional Options** box. ### To set this compiler option programmatically diff --git a/docs/build/reference/y-precompiled-headers.md b/docs/build/reference/y-precompiled-headers.md index d747d6cefd..1dd5938fb8 100644 --- a/docs/build/reference/y-precompiled-headers.md +++ b/docs/build/reference/y-precompiled-headers.md @@ -1,27 +1,27 @@ --- -title: "/Y (Precompiled Headers)" +description: "Learn more about: /Y (precompiled headers)" +title: "/Y (precompiled headers)" ms.date: "11/04/2016" f1_keywords: ["/Y"] helpviewer_keywords: ["/Y compiler options [C++]"] -ms.assetid: 1df5726a-8ebe-42c3-b618-d2f5e1ce8673 --- -# /Y (Precompiled Headers) +# /Y (precompiled headers) The following compiler options affect the generation and use of precompiled headers: -- [/Y- (Ignore Precompiled Header Options)](y-ignore-precompiled-header-options.md) +- [/Y- (Ignore precompiled header options)](y-ignore-precompiled-header-options.md) -- [/Yc (Create Precompiled Header File)](yc-create-precompiled-header-file.md) +- [/Yc (Create precompiled header file)](yc-create-precompiled-header-file.md) -- [/Yd (Place Debug Information in Object File)](yd-place-debug-information-in-object-file.md) +- [/Yd (Place Debug Information in Object file)](yd-place-debug-information-in-object-file.md) -- [/Yl (Inject PCH Reference for Debug Library)](yl-inject-pch-reference-for-debug-library.md) +- [/Yl (Inject PCH reference for debug library)](yl-inject-pch-reference-for-debug-library.md) -- [/Yu (Use Precompiled Header File)](yu-use-precompiled-header-file.md) +- [/Yu (Use precompiled header file)](yu-use-precompiled-header-file.md) -For details on working with precompiled headers, see [Precompiled Header Files](../creating-precompiled-header-files.md). +For details on working with precompiled headers, see [precompiled header files](../creating-precompiled-header-files.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/yc-create-precompiled-header-file.md b/docs/build/reference/yc-create-precompiled-header-file.md index a9021b5596..8ea84374c5 100644 --- a/docs/build/reference/yc-create-precompiled-header-file.md +++ b/docs/build/reference/yc-create-precompiled-header-file.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Yc (Create Precompiled Header File)" title: "/Yc (Create Precompiled Header File)" ms.date: "11/04/2016" f1_keywords: ["VC.Project.VCCLCompilerTool.UsePrecompiledHeader", "/yc", "VC.Project.VCCLWCECompilerTool.PrecompiledHeaderThrough", "VC.Project.VCCLWCECompilerTool.UsePrecompiledHeader", "VC.Project.VCCLCompilerTool.PrecompiledHeaderThrough"] diff --git a/docs/build/reference/yd-place-debug-information-in-object-file.md b/docs/build/reference/yd-place-debug-information-in-object-file.md index fa105d176a..ced560abe3 100644 --- a/docs/build/reference/yd-place-debug-information-in-object-file.md +++ b/docs/build/reference/yd-place-debug-information-in-object-file.md @@ -1,9 +1,9 @@ --- title: "/Yd (Place Debug Information in Object File)" -ms.date: "11/04/2016" +description: "Learn more about: /Yd (Place Debug Information in Object File)" +ms.date: 11/04/2016 f1_keywords: ["/yd"] helpviewer_keywords: ["/Yd compiler option [C++]", "-Yd compiler option [C++]", "debugging [C++], debug information files", "Yd compiler option [C++]"] -ms.assetid: c5a699fe-65ce-461e-964c-7f5eb2a8320a --- # /Yd (Place Debug Information in Object File) @@ -35,11 +35,9 @@ For more information on precompiled headers, see: 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 **C/C++** folder. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Click the **Command Line** property page. - -1. Type the compiler option in the **Additional Options** box. +1. Enter the compiler option in the **Additional Options** box. ### To set this compiler option programmatically @@ -56,13 +54,13 @@ Suppose you have two base files, F.cpp and G.cpp, each containing these **#inclu The following command creates the precompiled header file ETC.pch and the object file F.obj: -``` +```cmd CL /YcETC.H /Z7 F.CPP ``` The object file F.obj includes type and symbol information for WINDOWS.h and ETC.h (and any other header files they include). Now you can use the precompiled header ETC.pch to compile the source file G.cpp: -``` +```cmd CL /YuETC.H /Z7 G.CPP ``` diff --git a/docs/build/reference/yl-inject-pch-reference-for-debug-library.md b/docs/build/reference/yl-inject-pch-reference-for-debug-library.md index 770d714d82..10b39b74a4 100644 --- a/docs/build/reference/yl-inject-pch-reference-for-debug-library.md +++ b/docs/build/reference/yl-inject-pch-reference-for-debug-library.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Yl (Inject PCH Reference for Debug Library)" title: "/Yl (Inject PCH Reference for Debug Library)" ms.date: "01/29/2018" f1_keywords: ["/yl"] diff --git a/docs/build/reference/yu-use-precompiled-header-file.md b/docs/build/reference/yu-use-precompiled-header-file.md index ca3993ad0b..dfdce8d69d 100644 --- a/docs/build/reference/yu-use-precompiled-header-file.md +++ b/docs/build/reference/yu-use-precompiled-header-file.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: `/Yu` (Use precompiled header file)" title: "/Yu (Use precompiled header file)" ms.date: 07/31/2020 f1_keywords: ["/Yu"] 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 a43e189b29..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,10 +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. @@ -22,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. @@ -30,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. @@ -42,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. @@ -57,7 +58,7 @@ The **`/ZI`** option forces both the [`/Gy` (Enable Function-Level Linking)](gy- 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 **Configuration Properties** > **C/C++** > **General** property page. +1. Select the **Configuration Properties** > **C/C++** > **General** property page. 1. Modify the **Debug Information Format** property. Choose **OK** to save your changes. diff --git a/docs/build/reference/za-ze-disable-language-extensions.md b/docs/build/reference/za-ze-disable-language-extensions.md index c744316bf8..9d1e2a35ef 100644 --- a/docs/build/reference/za-ze-disable-language-extensions.md +++ b/docs/build/reference/za-ze-disable-language-extensions.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Za, /Ze (Disable Language Extensions)" title: "/Za, /Ze (Disable Language Extensions)" ms.date: "02/19/2019" f1_keywords: ["VC.Project.VCCLWCECompilerTool.DisableLanguageExtensions", "/za", "/ze", "VC.Project.VCCLCompilerTool.DisableLanguageExtensions"] @@ -33,7 +34,7 @@ For more information about conformance issues with Visual C++, see [Nonstandard 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. In the navigation pane, choose **Configuration Properties** > **C/C++** > **Language**. +1. Select the **Configuration Properties** > **C/C++** > **Language** property page. 1. Modify the **Disable Language Extensions** property. diff --git a/docs/build/reference/zc-alignednew.md b/docs/build/reference/zc-alignednew.md index a596c98fe0..c591923268 100644 --- a/docs/build/reference/zc-alignednew.md +++ b/docs/build/reference/zc-alignednew.md @@ -1,28 +1,29 @@ --- 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 @@ -93,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-auto-deduce-variable-type.md b/docs/build/reference/zc-auto-deduce-variable-type.md index 04c9aa9b6b..ea2a667d29 100644 --- a/docs/build/reference/zc-auto-deduce-variable-type.md +++ b/docs/build/reference/zc-auto-deduce-variable-type.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: `/Zc:auto` (Deduce Variable Type)" title: "/Zc:auto (Deduce Variable Type)" ms.date: "02/28/2018" f1_keywords: ["/Zc:auto"] @@ -7,7 +8,7 @@ ms.assetid: 5f5bc102-44c3-4688-bbe1-080594dcee5c --- # `/Zc:auto` (Deduce Variable Type) -The **`/Zc:auto`** compiler option tells the compiler how to use the [`auto` keyword](../../cpp/auto-keyword.md) to declare variables. If you specify the default option, **`/Zc:auto`**, the compiler deduces the type of the declared variable from its initialization expression. If you specify **`/Zc:auto-`**, the compiler allocates the variable to the automatic storage class. +The **`/Zc:auto`** compiler option tells the compiler how to use the [`auto` keyword](../../cpp/auto-cpp.md) to declare variables. If you specify the default option, **`/Zc:auto`**, the compiler deduces the type of the declared variable from its initialization expression. If you specify **`/Zc:auto-`**, the compiler allocates the variable to the automatic storage class. ## Syntax @@ -17,7 +18,7 @@ The **`/Zc:auto`** compiler option tells the compiler how to use the [`auto` key The C++ standard defines an original and a revised meaning for the **`auto`** keyword. Before Visual Studio 2010, the keyword declares a variable in the automatic storage class; that is, a variable that has a local lifetime. Starting with Visual Studio 2010, the keyword deduces the type of a variable from the declaration's initialization expression. Use the **`/Zc:auto`** compiler option to tell the compiler to use the revised meaning of the **`auto`** keyword. The **`/Zc:auto`** option is on by default. The [`/permissive-`](permissive-standards-conformance.md) option does not change the default setting of **`/Zc:auto`**. -The compiler issues an appropriate diagnostic message if your use of the **`auto`** keyword contradicts the current **`/Zc:auto`** compiler option. For more information, see [`auto` Keyword](../../cpp/auto-keyword.md). For more information about conformance issues with Visual C++, see [Nonstandard Behavior](../../cpp/nonstandard-behavior.md). +The compiler issues an appropriate diagnostic message if your use of the **`auto`** keyword contradicts the current **`/Zc:auto`** compiler option. For more information, see [`auto` Keyword](../../cpp/auto-cpp.md). For more information about conformance issues with Visual C++, see [Nonstandard Behavior](../../cpp/nonstandard-behavior.md). ### To set this compiler option in Visual Studio @@ -30,4 +31,4 @@ The compiler issues an appropriate diagnostic message if your use of the **`auto ## See also [`/Zc` (Conformance)](zc-conformance.md)
-[`auto` Keyword](../../cpp/auto-keyword.md) +[`auto` Keyword](../../cpp/auto-cpp.md) 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 d8172a7beb..efa980dbb7 100644 --- a/docs/build/reference/zc-conformance.md +++ b/docs/build/reference/zc-conformance.md @@ -1,47 +1,63 @@ --- title: "/Zc (Conformance)" -ms.date: "03/06/2018" +description: "The /Zc conformance compiler options enable or disable support for conforming or backward-compatible behavior." +ms.date: 08/31/2023 helpviewer_keywords: ["/Zc compiler options [C++]", "-Zc compiler options [C++]", "Conformance compiler options", "Zc compiler options [C++]"] -ms.assetid: db1cc175-6e93-4a2e-9396-c3725d2d8f71 --- # `/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 -> **`/Zc:`**_option_{,_option_} +> **`/Zc:`**_option_{,_option_ ...} + +You may set multiple **`/Zc`** options separated by commas in a single **`/Zc`** compiler option. If a **`/Zc`** option is enabled and disabled in the same command, the option that appears last is used. ## Remarks -When Visual Studio has implemented an extension to C or C++ that is not compatible with the standard, you can use a **`/Zc`** conformance option to specify standard-conforming or Microsoft-specific behavior. For some options, the Microsoft-specific behavior is the default, to prevent large-scale breaking changes to existing code. In other cases, the default is the standard behavior, where improvements in security, performance, or compatibility outweigh the costs of breaking changes. The default setting of each conformance option may change in newer versions of Visual Studio. For more information about each conformance option, see the topic for the specific option. The [`/permissive-`](permissive-standards-conformance.md) compiler option implicitly sets the conformance options that are not set by default to their conformant setting. +When Visual Studio has implemented an extension to C or C++ that is incompatible with the standard, you can use a **`/Zc`** conformance option to specify standard-conforming or Microsoft-specific behavior. For some options, the Microsoft-specific behavior is the default, to prevent large-scale breaking changes to existing code. In other cases, the default is the standard behavior, where improvements in security, performance, or compatibility outweigh the costs of breaking changes. The default setting of each conformance option may change in newer versions of Visual Studio. For more information about each conformance option, see the article for the specific option. The [`/permissive-`](permissive-standards-conformance.md) compiler option implicitly sets the conformance options that aren't set by default to their conforming settings. -These are the **`/Zc`** compiler options: +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). | -| [`/ZcimplicitNoexcept`](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 function or data if it is COMDAT or has 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:referenceBinding`](zc-referencebinding-enforce-reference-binding-rules.md) | A UDT temporary will not bind to an 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). | - -For more information about conformance issues in Visual C++, see [Nonstandard Behavior](../../cpp/nonstandard-behavior.md). +| [`/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 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/zc-cplusplus.md b/docs/build/reference/zc-cplusplus.md index 4f49777c25..ef73099605 100644 --- a/docs/build/reference/zc-cplusplus.md +++ b/docs/build/reference/zc-cplusplus.md @@ -1,34 +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 @@ -36,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 25f3384831..ee9c10b502 100644 --- a/docs/build/reference/zc-externconstexpr.md +++ b/docs/build/reference/zc-externconstexpr.md @@ -1,9 +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) @@ -15,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 @@ -29,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-keyword.md) +[`auto` Keyword](../../cpp/auto-cpp.md)\ +[`permissive`](permissive-standards-conformance.md)\ +[`/Zc` (Conformance)](zc-conformance.md) diff --git a/docs/build/reference/zc-forscope-force-conformance-in-for-loop-scope.md b/docs/build/reference/zc-forscope-force-conformance-in-for-loop-scope.md index f3ee427f1d..8ef06d5327 100644 --- a/docs/build/reference/zc-forscope-force-conformance-in-for-loop-scope.md +++ b/docs/build/reference/zc-forscope-force-conformance-in-for-loop-scope.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Zc:forScope (Force Conformance in for Loop Scope)" title: "/Zc:forScope (Force Conformance in for Loop Scope)" ms.date: "03/06/2018" f1_keywords: ["VC.Project.VCCLCompilerTool.ForceConformanceInForLoopScope", "VC.Project.VCCLWCECompilerTool.ForceConformanceInForLoopScope", "/zc:forScope"] 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-hiddenfriend.md b/docs/build/reference/zc-hiddenfriend.md new file mode 100644 index 0000000000..cda8ab530e --- /dev/null +++ b/docs/build/reference/zc-hiddenfriend.md @@ -0,0 +1,39 @@ +--- +title: "/Zc:hiddenFriend (Enforce Standard C++ hidden friend rules)" +description: "Learn about the Microsoft C++ /Zc:hiddenFriend compiler option for conforming or relaxed hidden friend compatibility." +ms.date: 01/23/2021 +f1_keywords: ["/Zc:hiddenFriend"] +helpviewer_keywords: ["/Zc:hiddenFriend", "Zc:hiddenFriend", "-Zc:hiddenFriend"] +--- +# `/Zc:hiddenFriend` (Enforce Standard C++ hidden friend rules) + +Specifies the compiler conforms to the C++ standard treatment of hidden friend functions or function templates. + +## Syntax + +> **`/Zc:hiddenFriend`**\[**`-`**] + +## Remarks + +The **`/Zc:hiddenFriend`** option enables a subset of the [`/permissive-`](permissive-standards-conformance.md) option behavior. It tells the compiler to conform to the standard for hidden friends. The compiler only includes hidden friends in [argument-dependent lookup](../../cpp/argument-dependent-name-koenig-lookup-on-functions.md) (ADL) for explicit instances or template parameters of the enclosing class type. The restriction allows you to use hidden friends to keep operations on a type from applying to implicit conversions. This option can improve build speed in code that can't otherwise use [`/permissive-`](permissive-standards-conformance.md). + +A *hidden friend* is a **`friend`** function or function template declared only within a class or class template definition. By default, the Microsoft C++ compiler doesn't remove hidden friend declarations as candidates for overload resolution everywhere it should. This legacy behavior can slow the compiler down by including the hidden friend functions as possible candidates in more contexts. + +Standard C++ hidden friend behavior is enabled by default under **`/permissive-`**. To specify legacy hidden friend behavior when the **`/permissive-`** option is specified, use **`/Zc:hiddenFriend-`**. Use of C++20 Modules requires standard hidden friend behavior. + +The **`/Zc:hiddenFriend`** option is available starting in Visual Studio 2019 version 16.4. + +For examples of compiler behavior when you specify **`/Zc:hiddenFriend`**, see [Hidden friend name lookup rules](./permissive-standards-conformance.md#hidden-friend-name-lookup-rules). + +### 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:hiddenFriend`* or *`/Zc:hiddenFriend-`* and then choose **OK**. + +## See also + +[`/Zc` (Conformance)](zc-conformance.md)\ +[`/permissive-`](permissive-standards-conformance.md) diff --git a/docs/build/reference/zc-implicitnoexcept-implicit-exception-specifiers.md b/docs/build/reference/zc-implicitnoexcept-implicit-exception-specifiers.md index d5bec72d21..9f63fb0da9 100644 --- a/docs/build/reference/zc-implicitnoexcept-implicit-exception-specifiers.md +++ b/docs/build/reference/zc-implicitnoexcept-implicit-exception-specifiers.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Zc:implicitNoexcept (Implicit Exception Specifiers)" title: "/Zc:implicitNoexcept (Implicit Exception Specifiers)" ms.date: "03/06/2018" f1_keywords: ["/Zc:implicitNoexcept"] diff --git a/docs/build/reference/zc-inline-remove-unreferenced-comdat.md b/docs/build/reference/zc-inline-remove-unreferenced-comdat.md index 64d04824d0..37f4265cea 100644 --- a/docs/build/reference/zc-inline-remove-unreferenced-comdat.md +++ b/docs/build/reference/zc-inline-remove-unreferenced-comdat.md @@ -1,29 +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 @@ -38,6 +41,8 @@ public: }; ``` +Source file `example.cpp`: + ```cpp // example.cpp // Compile by using: cl /W4 /EHsc /O2 zcinline.cpp example.cpp @@ -54,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 @@ -65,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 @@ -85,6 +94,8 @@ public: }; ``` +Source file `example2.cpp`: + ```cpp // example2.cpp // Compile by using: cl /W4 /EHsc /O2 zcinline2.cpp example2.cpp @@ -96,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 @@ -107,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 @@ -119,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 994ccf37b5..db977cceeb 100644 --- a/docs/build/reference/zc-noexcepttypes.md +++ b/docs/build/reference/zc-noexcepttypes.md @@ -1,11 +1,12 @@ --- title: "/Zc:noexceptTypes (C++17 noexcept rules)" +description: "Learn about the Microsoft C++ /Zc:noexceptTypes compiler option for conforming or relaxed C++17 noexcept source code compatibility." ms.date: "06/04/2020" 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. @@ -15,9 +16,9 @@ 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. +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. This sample shows how declarations with an exception specifier behave when the **`/Zc:noexceptTypes`** option is set or disabled. To show the behavior when set, compile by using `cl /EHsc /W4 noexceptTypes.cpp`. To show the behavior when disabled, compile by using `cl /EHsc /W4 /Zc:noexceptTypes- noexceptTypes.cpp`. @@ -67,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)\ +[`/Zc` (Conformance)](zc-conformance.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 new file mode 100644 index 0000000000..fd8708017a --- /dev/null +++ b/docs/build/reference/zc-preprocessor.md @@ -0,0 +1,32 @@ +--- +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: 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) + +This option enables a token-based preprocessor that conforms to C99 and C++11 and later standards. For more information, see [MSVC new preprocessor overview](../../preprocessor/preprocessor-experimental-overview.md). + +## Syntax + +> **`/Zc:preprocessor`**[**`-`**] + +## Remarks + +Use the **`/Zc:preprocessor`** compiler option to enable the conforming preprocessor. You can use **`/Zc:preprocessor-`** option to explicitly specify the traditional (non-conforming) preprocessor. + +The **`/Zc:preprocessor`** option is available starting in Visual Studio 2019 version 16.5. An earlier, incomplete version of the new preprocessor option is available in versions of Visual Studio starting in Visual Studio 2017 version 15.8. For more information, see [`/experimental:preprocessor`](experimental-preprocessor.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++** > **Preprocessor** property page. + +1. Modify the **Use Standard Conforming Preprocessor** property and then choose **OK**. + +## See also + +[/Zc (Conformance)](zc-conformance.md) diff --git a/docs/build/reference/zc-referencebinding-enforce-reference-binding-rules.md b/docs/build/reference/zc-referencebinding-enforce-reference-binding-rules.md index f012bbf457..e6842c88e4 100644 --- a/docs/build/reference/zc-referencebinding-enforce-reference-binding-rules.md +++ b/docs/build/reference/zc-referencebinding-enforce-reference-binding-rules.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Zc:referenceBinding (Enforce reference binding rules)" title: "/Zc:referenceBinding (Enforce reference binding rules)" ms.date: "03/06/2018" f1_keywords: ["referenceBinding", "/Zc:referenceBinding"] diff --git a/docs/build/reference/zc-rvaluecast-enforce-type-conversion-rules.md b/docs/build/reference/zc-rvaluecast-enforce-type-conversion-rules.md index cfc1438638..3a9b1bdb1e 100644 --- a/docs/build/reference/zc-rvaluecast-enforce-type-conversion-rules.md +++ b/docs/build/reference/zc-rvaluecast-enforce-type-conversion-rules.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Zc:rvalueCast (Enforce type conversion rules)" title: "/Zc:rvalueCast (Enforce type conversion rules)" ms.date: "02/18/2020" f1_keywords: ["rvaluecast", "/Zc:rvalueCast", "VC.Project.VCCLCompilerTool.EnforceTypeConversionRules"] diff --git a/docs/build/reference/zc-sizeddealloc-enable-global-sized-dealloc-functions.md b/docs/build/reference/zc-sizeddealloc-enable-global-sized-dealloc-functions.md index 6f9e68485c..4aa9be51fa 100644 --- a/docs/build/reference/zc-sizeddealloc-enable-global-sized-dealloc-functions.md +++ b/docs/build/reference/zc-sizeddealloc-enable-global-sized-dealloc-functions.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Zc:sizedDealloc (Enable Global Sized Deallocation Functions)" title: "/Zc:sizedDealloc (Enable Global Sized Deallocation Functions)" ms.date: "03/06/2018" f1_keywords: ["sizedDealloc", "/Zc:sizedDealloc"] 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-strictstrings-disable-string-literal-type-conversion.md b/docs/build/reference/zc-strictstrings-disable-string-literal-type-conversion.md index 1cb47e0323..a50da44df3 100644 --- a/docs/build/reference/zc-strictstrings-disable-string-literal-type-conversion.md +++ b/docs/build/reference/zc-strictstrings-disable-string-literal-type-conversion.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: `/Zc:strictStrings` (Disable string literal type conversion)" title: "/Zc:strictStrings (Disable string literal type conversion)" ms.date: "03/06/2018" f1_keywords: ["/Zc:strictStrings", "strictStrings"] 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 5010d9c3fa..b77f0d7739 100644 --- a/docs/build/reference/zc-ternary.md +++ b/docs/build/reference/zc-ternary.md @@ -1,6 +1,7 @@ --- 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"] --- @@ -22,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 @@ -48,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-threadsafeinit-thread-safe-local-static-initialization.md b/docs/build/reference/zc-threadsafeinit-thread-safe-local-static-initialization.md index 6b5b2fae33..227a6aec5e 100644 --- a/docs/build/reference/zc-threadsafeinit-thread-safe-local-static-initialization.md +++ b/docs/build/reference/zc-threadsafeinit-thread-safe-local-static-initialization.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Zc:threadSafeInit (Thread-safe Local Static Initialization)" title: "/Zc:threadSafeInit (Thread-safe Local Static Initialization)" ms.date: "03/14/2018" f1_keywords: ["threadSafeInit", "/Zc:threadSafeInit"] diff --git a/docs/build/reference/zc-throwingnew-assume-operator-new-throws.md b/docs/build/reference/zc-throwingnew-assume-operator-new-throws.md index b748d3ec1a..df70e23f0c 100644 --- a/docs/build/reference/zc-throwingnew-assume-operator-new-throws.md +++ b/docs/build/reference/zc-throwingnew-assume-operator-new-throws.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Zc:throwingNew (Assume operator new throws)" title: "/Zc:throwingNew (Assume operator new throws)" ms.date: "03/01/2018" f1_keywords: ["throwingNew", "/Zc:throwingNew"] 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-wchar-t-wchar-t-is-native-type.md b/docs/build/reference/zc-wchar-t-wchar-t-is-native-type.md index 90114e08c0..0fdfce196d 100644 --- a/docs/build/reference/zc-wchar-t-wchar-t-is-native-type.md +++ b/docs/build/reference/zc-wchar-t-wchar-t-is-native-type.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Zc:wchar_t (wchar_t Is Native Type)" title: "/Zc:wchar_t (wchar_t Is Native Type)" ms.date: "03/01/2018" f1_keywords: ["VC.Project.VCCLWCECompilerTool.TreatWChar_tAsBuiltInType", "VC.Project.VCCLCompilerTool.TreatWChar_tAsBuiltInType", "/Zc:wchar_t"] 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 7080091f28..d15547b2e8 100644 --- a/docs/build/reference/zf.md +++ b/docs/build/reference/zf.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Zf (Faster PDB generation)" title: "/Zf (Faster PDB generation)" ms.date: "03/29/2018" f1_keywords: ["/Zf"] @@ -18,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/zg-generate-function-prototypes.md b/docs/build/reference/zg-generate-function-prototypes.md index 2aaaea7d41..1a3a71911c 100644 --- a/docs/build/reference/zg-generate-function-prototypes.md +++ b/docs/build/reference/zg-generate-function-prototypes.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Zg (Generate Function Prototypes)" title: "/Zg (Generate Function Prototypes)" ms.date: "11/04/2016" f1_keywords: ["/zg"] @@ -38,11 +39,9 @@ The **/Zg** option was deprecated in Visual Studio 2005 and has been removed in 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 **C/C++** folder. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Click the **Command Line** property page. - -1. Type the compiler option in the **Additional Options** box. +1. Enter the compiler option in the **Additional Options** box. ### To set this compiler option programmatically 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/zl-omit-default-library-name.md b/docs/build/reference/zl-omit-default-library-name.md index bfba6ae7e9..15fd5cc98d 100644 --- a/docs/build/reference/zl-omit-default-library-name.md +++ b/docs/build/reference/zl-omit-default-library-name.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Zl (Omit Default Library Name)" title: "/Zl (Omit Default Library Name)" ms.date: "11/04/2016" f1_keywords: ["/zl", "VC.Project.VCCLCompilerTool.OmitDefaultLibName"] @@ -45,9 +46,7 @@ void Test() { 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 **C/C++** folder. - -1. Click the **Advanced** property page. +1. Select the **Configuration Properties** > **C/C++** > **Advanced** property page. 1. Modify the **Omit Default Library Names** property. 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 104a39d449..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,60 +1,59 @@ --- -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). -1. In the navigation pane, select **Configuration Properties** > **C/C++** > **Command Line**. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. 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 be2ff9ba36..c4ff8c18fa 100644 --- a/docs/build/reference/zo-enhance-optimized-debugging.md +++ b/docs/build/reference/zo-enhance-optimized-debugging.md @@ -1,6 +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 @@ -11,23 +12,21 @@ 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. -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). +### To set the `/Zo` compiler option in Visual Studio -1. Select the **Configuration Properties**, **C/C++** folder. +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 **Command Line** property page. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. 1. Modify the **Additional Options** property to include `/Zo` and then choose **OK**. @@ -37,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 2791e13bb2..cfb89975b2 100644 --- a/docs/build/reference/zp-struct-member-alignment.md +++ b/docs/build/reference/zp-struct-member-alignment.md @@ -1,6 +1,7 @@ --- +description: "Learn more about: /Zp (Struct Member Alignment)" title: "/Zp (Struct Member Alignment)" -ms.date: "04/04/2019" +ms.date: "01/08/2021" f1_keywords: ["/zp", "VC.Project.VCCLCompilerTool.StructMemberAlignment", "VC.Project.VCCLWCECompilerTool.StructMemberAlignment"] helpviewer_keywords: ["Struct Member Alignment compiler option", "Zp compiler option", "/Zp compiler option [C++]", "-Zp compiler option [C++]"] ms.assetid: 5242f656-ed9b-48a3-bc73-cfcf3ed2520f @@ -25,14 +26,14 @@ 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] -> C++ headers in the Windows SDK set and assume **`/Zp8`** packing internally. Memory corruption may occur if the **`/Zp`** setting is changed inside the Windows SDK headers. The headers aren't affected by any **`/Zp`** option you set on the command line. +> 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 [`pack`](../../preprocessor/pack.md) to control structure packing. For more information about alignment, see: +You can also use the [`pack` pragma](../../preprocessor/pack.md) to control structure packing. For more information about alignment, see: - [`align`](../../cpp/align-cpp.md) diff --git a/docs/build/reference/zs-syntax-check-only.md b/docs/build/reference/zs-syntax-check-only.md index fcdc119435..2cf2237e5e 100644 --- a/docs/build/reference/zs-syntax-check-only.md +++ b/docs/build/reference/zs-syntax-check-only.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: /Zs (Syntax Check Only)" title: "/Zs (Syntax Check Only)" ms.date: "11/04/2016" f1_keywords: ["/zs"] @@ -25,11 +26,9 @@ The **/Zs** option provides a quick way to find and correct syntax errors before 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 **C/C++** folder. +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Click the **Command Line** property page. - -1. Type the compiler option in the **Additional Options** box. +1. Enter the compiler option in the **Additional Options** box. ### To set this compiler option programmatically diff --git a/docs/build/reference/zw-windows-runtime-compilation.md b/docs/build/reference/zw-windows-runtime-compilation.md index 98fad0f66d..6bba2c712c 100644 --- a/docs/build/reference/zw-windows-runtime-compilation.md +++ b/docs/build/reference/zw-windows-runtime-compilation.md @@ -1,15 +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 @@ -20,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). @@ -39,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/regular-dlls-dynamically-linked-to-mfc.md b/docs/build/regular-dlls-dynamically-linked-to-mfc.md index 44e44562d0..355c7bda04 100644 --- a/docs/build/regular-dlls-dynamically-linked-to-mfc.md +++ b/docs/build/regular-dlls-dynamically-linked-to-mfc.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Regular MFC DLLs Dynamically Linked to MFC" title: "Regular MFC DLLs Dynamically Linked to MFC" ms.date: "11/04/2016" helpviewer_keywords: ["regular MFC DLLs [C++], dynamically linked to MFC", "AFX_MANAGE_STATE macro", "DLLs [C++], regular", "shared DLL versions [C++]", "dynamically linked DLLs [C++]"] diff --git a/docs/build/regular-dlls-statically-linked-to-mfc.md b/docs/build/regular-dlls-statically-linked-to-mfc.md index 07634f670f..d3d90f0518 100644 --- a/docs/build/regular-dlls-statically-linked-to-mfc.md +++ b/docs/build/regular-dlls-statically-linked-to-mfc.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Regular MFC DLLs Statically Linked to MFC" title: "Regular MFC DLLs Statically Linked to MFC" ms.date: "11/04/2016" helpviewer_keywords: ["regular MFC DLLs [C++]", "DLLs [C++], regular", "USRDLLs", "USRDLLs, statically linked to MFC", "statically linked DLLs [C++]", "regular MFC DLLs [C++], statically linked to MFC"] diff --git a/docs/build/release-builds.md b/docs/build/release-builds.md index 86911856c8..ed9821fb8a 100644 --- a/docs/build/release-builds.md +++ b/docs/build/release-builds.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Release Builds" title: "C++ release builds - Visual Studio" ms.date: "12/10/2018" helpviewer_keywords: ["debugging [C++], release builds", "release builds", "debug builds, converting to release build"] diff --git a/docs/build/run-time-library-behavior.md b/docs/build/run-time-library-behavior.md index c44f7e4dad..1a85ae8d84 100644 --- a/docs/build/run-time-library-behavior.md +++ b/docs/build/run-time-library-behavior.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: DLLs and Visual C++ run-time library behavior" title: "DLLs and Visual C++ run-time library behavior" ms.date: "08/19/2019" f1_keywords: ["_DllMainCRTStartup", "CRT_INIT"] @@ -40,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. @@ -116,7 +117,7 @@ The wizard provides the following code for MFC extension DLLs. In the code, `PRO #undef THIS_FILE static char THIS_FILE[] = __FILE__; #endif -static AFX_EXTENSION_MODULE PROJNAMEDLL = { NULL, NULL }; +static AFX_EXTENSION_MODULE PROJNAMEDLL; extern "C" int APIENTRY DllMain(HINSTANCE hInstance, DWORD dwReason, LPVOID lpReserved) 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 24d1f66d75..0000000000 --- a/docs/build/setting-the-path-and-environment-variables-for-command-line-builds.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -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/specifying-build-events.md b/docs/build/specifying-build-events.md index 9736418603..25f79a1076 100644 --- a/docs/build/specifying-build-events.md +++ b/docs/build/specifying-build-events.md @@ -1,9 +1,11 @@ --- +description: "Learn more about: Specifying build events" title: "Specifying Build Events" ms.date: "12/28/2017" f1_keywords: ["VC.Project.IVCEventTool.CommandLine", "VC.Project.IVCEventTool.ExcludedFromBuild", "VC.Project.IVCEventTool.Description"] helpviewer_keywords: ["Pre-Link event", "build events [C++], specifying", "custom build steps [C++], build events", "builds [C++], events", "events [C++], build", "builds [C++], customizing C++", "build events [C++]", "post-build events"] ms.assetid: 788a6c18-2dbe-4a49-8cd6-86c1ad7a95cc +ms.topic: how-to --- # Specifying build events diff --git a/docs/build/specifying-custom-build-tools.md b/docs/build/specifying-custom-build-tools.md index 50e84a1d65..251433fada 100644 --- a/docs/build/specifying-custom-build-tools.md +++ b/docs/build/specifying-custom-build-tools.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Specify custom build tools" title: "Specifying Custom Build Tools" ms.date: "06/05/2018" f1_keywords: ["VC.Project.VCCustomBuildTool.CustomBuildToolBeforeTargets", "VC.Project.VCCustomBuildTool.Outputs", "VC.Project.VCCustomBuildTool.Command", "VC.Project.VCCustomBuildTool.CommandLine", "VC.Project.VCCustomBuildTool.AdditionalDependencies", "VC.Project.VCCustomBuildTool.Message", "VC.Project.VCCustomBuildTool.CustomBuildToolAfterTargets", "VC.Project.VCCustomBuildTool.Description", "VC.Project.VCCustomBuildTool.AdditionalInputs"] helpviewer_keywords: ["build tools (C++), specifying", "custom build tools (C++), specifying", "builds (C++), custom build tools"] +ms.topic: how-to --- # Specify custom build tools diff --git a/docs/build/stack-usage.md b/docs/build/stack-usage.md index 29aa0695f8..8bbec4908e 100644 --- a/docs/build/stack-usage.md +++ b/docs/build/stack-usage.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: x64 stack usage" title: "x64 stack usage" ms.date: "12/17/2018" ms.assetid: 383f0072-0438-489f-8829-cca89582408c @@ -21,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/tasks-vs-json-schema-reference-cpp.md b/docs/build/tasks-vs-json-schema-reference-cpp.md index 6cfa30afe9..4dc27c3886 100644 --- a/docs/build/tasks-vs-json-schema-reference-cpp.md +++ b/docs/build/tasks-vs-json-schema-reference-cpp.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: tasks.vs.json schema reference (C++)" title: "tasks.vs.json schema reference (C++)" ms.date: "08/20/2019" helpviewer_keywords: ["tasks.vs.json file [C++]"] @@ -14,9 +15,8 @@ A task has a `type` property which may have one of four values: `default`, `laun The default properties are available on all types of tasks: -|||| +|Property|Type|Description| |-|-|-| -|**Property**|**Type**|**Description**| |`taskLabel`|string| (Required.) Specifies the task label used in the user interface.| |`appliesTo`|string| (Required.) Specifies which files the command can be performed on. The use of wildcards is supported, for example: "*", "*.cpp", "/*.txt"| |`contextType`|string| Allowed values: "custom", "build", "clean", "rebuild". Determines where in the context menu the task will appear. Defaults to "custom".| @@ -28,9 +28,8 @@ The default properties are available on all types of tasks: When the task type is `launch`, these properties are available: -|||| +|Property|Type|Description| |-|-|-| -|**Property**|**Type**|**Description**| |`command`|string| Specifies the full path of the process or script to launch.| |`args`|array| Specifies a comma-separated list of arguments passed to the command.| |`launchOption`|string| Allowed values: "None", "ContinueOnError","IgnoreError". Specifies how to proceed with the command when there are errors.| @@ -81,9 +80,8 @@ Remote tasks are enabled when you install the Linux development with C++ workloa When the task type is `remote`, these properties are available: -|||| +|Property|Type|Description| |-|-|-| -|**Property**|**Type**|**Description**| |`remoteMachineName`|string|The name of the remote machine. Must match a machine name in **Connection Manager**.| |`command`|string|The command to send to the remote machine. By default commands are executed in the $HOME directory on the remote system.| |`remoteWorkingDirectory`|string|The current working directory on the remote machine.| @@ -122,9 +120,8 @@ The following task will appear in the context menu when you right-click on *main When the task type is `msbuild`, these properties are available: -|||| +|Property|Type|Description| |-|-|-| -|**Property**|**Type**|**Description**| |`verbosity`|string| Specifies the MSBuild project build output verbosityAllowed values: "Quiet", "Minimal", "Normal", "Detailed", "Diagnostic".| |`toolsVersion`|string| Specifies the toolset version to build the project, for example "2.0", "3.5", "4.0", "Current". Defaults to "Current".| |`globalProperties`|object|Specifies a key-value list of the global properties to pass into the project, for example, "Configuration":"Release"| diff --git a/docs/build/tips-for-improving-time-critical-code.md b/docs/build/tips-for-improving-time-critical-code.md index 0b70307552..aa3481e9e2 100644 --- a/docs/build/tips-for-improving-time-critical-code.md +++ b/docs/build/tips-for-improving-time-critical-code.md @@ -1,4 +1,5 @@ --- +description: "Learn more about: Tips for Improving Time-Critical Code" title: "Tips for Improving Time-Critical Code" ms.date: "11/04/2016" helpviewer_keywords: ["_lsearch function", "qsort function", "background tasks", "standard sort routines", "clock cycle losses", "code, time-critical", "memory [C++], monitoring usage", "execution, speed improvements", "local heap performance", "optimization [C++], time-critical code", "performance [C++], time-critical code", "threading [C++], performance", "cache [C++], hits and misses", "linear search performance", "page faults", "best practices, time-critical code", "searching [C++], improving performance", "sorting data, improving performance", "threading [C++], best practices", "threading [C++], background tasks", "lists, sorting", "bsearch function", "MFC [C++], performance", "sort routines", "programs [C++], performance", "_lfind function", "heap allocation, time-critical code performance"] @@ -6,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: @@ -40,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 @@ -58,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. @@ -108,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. @@ -118,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 6b917f67b3..b5614f10a7 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,10 +56,18 @@ 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 href: ../build/clang-support-cmake.md - name: Configure a Linux CMake project href: ../build/../linux/cmake-linux-project.md + - name: Configure and build with CMake Presets + href: ../build/cmake-presets-vs.md + - name: CMakePresets.json reference + href: ../build/cmake-presets-json-reference.md - name: Customize CMake build settings href: ../build/customize-cmake-settings.md - name: Configure CMake debugging sessions @@ -67,10 +76,19 @@ href: ../build/cmakesettings-reference.md - name: CMake predefined configuration schema reference href: ../build/cmake-predefined-configuration-reference.md -- name: "vcpkg: A package manager for C++" - href: ../build/vcpkg.md - name: "C++ Build Insights" href: ../build-insights/get-started-with-cpp-build-insights.md +- 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 @@ -142,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: @@ -184,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 @@ -271,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 @@ -294,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 @@ -318,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 @@ -326,6 +335,8 @@ href: ../build/configuring-programs-for-windows-xp.md - name: Code analysis for C/C++ href: ../code-quality/ +- name: "Code sanitizers for C/C++" + href: ../sanitizers/ - name: Compiler and build tools reference expanded: false items: @@ -363,12 +374,14 @@ 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 - name: .vcxproj and .props file structure href: ../build/reference/vcxproj-file-structure.md + - name: .vcxproj files and wildcards + href: ../build/reference/vcxproj-files-and-wildcards.md - name: Example project file href: ../build/reference/project-files.md - name: .vcxproj.filters file structure @@ -395,7 +408,7 @@ - name: Command line property pages href: ../build/reference/command-line-property-pages.md - name: NMake property page - href: ../build/reference/nmake-property-page.md + href: ../build/reference/nmake-property-page.md - name: Manifest Tool property pages href: ../build/reference/manifest-tool-property-pages.md - name: Resources property pages @@ -465,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) @@ -498,12 +513,16 @@ href: ../build/reference/ep-preprocess-to-stdout-without-hash-line-directives.md - name: /errorReport (Report internal compiler errors) href: ../build/reference/errorreport-report-internal-compiler-errors.md - - name: /execution/charset (Set execution character set) + - 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 href: ../build/reference/experimental-preprocessor.md + - name: /external (External headers diagnostics) + href: ../build/reference/external-external-headers-diagnostics.md - name: /F (Set stack size) href: ../build/reference/f-set-stack-size.md - name: Output-file (/F) options @@ -533,7 +552,7 @@ href: ../build/reference/fp-name-dot-pch-file.md - name: /FR, /Fr (Create .Sbr file) href: ../build/reference/fr-fr-create-dot-sbr-file.md - - name: /FU (Name forced + - name: "/FU (Name forced #using file)" href: ../build/reference/fu-name-forced-hash-using-file.md - name: /Fx (Merge injected code) href: ../build/reference/fx-merge-injected-code.md @@ -541,10 +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) @@ -583,6 +613,10 @@ href: ../build/reference/gz-enable-stack-frame-run-time-error-checking.md - name: /H (Restrict length of external names) href: ../build/reference/h-restrict-length-of-external-names.md + - name: /headerName (Build a header unit from the specified header) + href: ../build/reference/headername.md + - name: /headerUnit (Use header unit IFC) + href: ../build/reference/headerunit.md - name: /HELP (Compiler command-line help) href: ../build/reference/help-compiler-command-line-help.md - name: /homeparams (Copy register parameters to stack) @@ -591,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) @@ -603,6 +647,10 @@ href: ../build/reference/ln-create-msil-module.md - name: /MD, /MT, /LD (Use Run-time library) href: ../build/reference/md-mt-ld-use-run-time-library.md + - name: /exportHeader (Create header units) + href: ../build/reference/module-exportheader.md + - name: /reference (Use named module IFC) + href: ../build/reference/module-reference.md - name: /MP (Build with multiple processes) href: ../build/reference/mp-build-with-multiple-processes.md - name: /nologo (Suppress startup banner) (C/C++) @@ -630,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) @@ -655,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 @@ -663,21 +715,27 @@ 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 - name: /source-charset (Set source character set) href: ../build/reference/source-charset-set-source-character-set.md - - name: /sourceDependencies (Report source-level dependencies) + - name: /sourceDependencies (List all source-level dependencies) href: ../build/reference/sourcedependencies.md + - name: /sourceDependencies:directives (List module and header unit dependencies) + href: ../build/reference/sourcedependencies-directives.md - name: /std (Specify language standard version) href: ../build/reference/std-specify-language-standard-version.md - name: /Tc, /Tp, /TC, /TP (Specify source file type) href: ../build/reference/tc-tp-tc-tp-specify-source-file-type.md + - name: /translateInclude (Translate include directives into import directives) + 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 @@ -685,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) @@ -726,44 +788,72 @@ - 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)" href: ../build/reference/zc-referencebinding-enforce-reference-binding-rules.md - name: "/Zc:rvalueCast (Enforce type conversion rules)" 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) @@ -782,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 @@ -840,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) @@ -912,14 +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: /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) @@ -930,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) @@ -962,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) @@ -1059,50 +1165,14 @@ items: - name: Linker support for delay-loaded DLLs href: ../build/reference/linker-support-for-delay-loaded-dlls.md - - name: Specifying DLLs to delay load - href: ../build/reference/specifying-dlls-to-delay-load.md - - name: Explicitly unloading a delay-loaded DLL - href: ../build/reference/explicitly-unloading-a-delay-loaded-dll.md - - name: Binding imports - href: ../build/reference/binding-imports.md - - name: Loading all imports for a delay-loaded DLL - href: ../build/reference/loading-all-imports-for-a-delay-loaded-dll.md - name: Error handling and notification - expanded: false - items: - - name: Error handling and notification - href: ../build/reference/error-handling-and-notification.md - - name: Notification hooks - href: ../build/reference/notification-hooks.md - - name: Failure hooks - href: ../build/reference/failure-hooks.md - - name: DLL load exception codes (C/C++) - href: ../build/reference/exceptions-c-cpp.md - - name: Dumping delay-loaded imports - href: ../build/reference/dumping-delay-loaded-imports.md - - name: Constraints of delay loading DLLs - href: ../build/reference/constraints-of-delay-loading-dlls.md - - name: Understanding the helper function - expanded: false - items: - - name: Understanding the helper function - href: ../build/reference/understanding-the-helper-function.md - - name: Changes in the DLL delayed loading helper function since Visual C++ 6.0 - href: ../build/reference/changes-in-the-dll-delayed-loading-helper-function-since-visual-cpp-6-0.md - - name: Calling conventions, parameters, and return type - href: ../build/reference/calling-conventions-parameters-and-return-type.md - - name: Structure and constant definitions - href: ../build/reference/structure-and-constant-definitions.md - - name: Calculating necessary values - href: ../build/reference/calculating-necessary-values.md - - name: Unloading a delay-loaded DLL - href: ../build/reference/unloading-a-delay-loaded-dll.md - - name: Developing your own helper function - href: ../build/reference/developing-your-own-helper-function.md - - name: Additional MSVC build tools + href: ../build/reference/error-handling-and-notification.md + - name: Understand the delay load helper function + href: ../build/reference/understanding-the-helper-function.md + - 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 @@ -1111,23 +1181,12 @@ href: ../build/reference/nmake-reference.md - name: NMAKE projects in Visual Studio href: ../build/reference/creating-a-makefile-project.md - - name: Running NMAKE + - 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 @@ -1135,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/troubleshooting-build-customizations.md b/docs/build/troubleshooting-build-customizations.md index 45f751dc22..f97a61e9d3 100644 --- a/docs/build/troubleshooting-build-customizations.md +++ b/docs/build/troubleshooting-build-customizations.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Troubleshooting Build Customizations" title: "Troubleshooting Build Customizations" ms.date: "11/04/2016" helpviewer_keywords: ["build events [C++], troubleshooting", "builds [C++], build events", "troubleshooting [C++], builds", "build steps [C++], troubleshooting", "events [C++], build", "builds [C++], troubleshooting", "custom build steps [C++], troubleshooting"] ms.assetid: e4ceb177-fbee-4ed3-a7d7-80f0d78c1d07 +ms.topic: troubleshooting-general --- # Troubleshooting Build Customizations diff --git a/docs/build/troubleshooting-c-cpp-isolated-applications-and-side-by-side-assemblies.md b/docs/build/troubleshooting-c-cpp-isolated-applications-and-side-by-side-assemblies.md index 0e1301a06b..e6b026bfba 100644 --- a/docs/build/troubleshooting-c-cpp-isolated-applications-and-side-by-side-assemblies.md +++ b/docs/build/troubleshooting-c-cpp-isolated-applications-and-side-by-side-assemblies.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Troubleshooting C/C++ Isolated Applications and Side-by-side Assemblies" title: "Troubleshooting C/C++ Isolated Applications and Side-by-side Assemblies" ms.date: "11/04/2016" helpviewer_keywords: ["troubleshooting side-by-side assemblies", "troubleshooting isolated applications", "troubleshooting Visual C++"] ms.assetid: 3257257a-1f0b-4ede-8564-9277a7113a35 +ms.topic: troubleshooting-general --- # Troubleshooting C/C++ Isolated Applications and Side-by-side Assemblies diff --git a/docs/build/understanding-custom-build-steps-and-build-events.md b/docs/build/understanding-custom-build-steps-and-build-events.md index 41282988d5..7827264c81 100644 --- a/docs/build/understanding-custom-build-steps-and-build-events.md +++ b/docs/build/understanding-custom-build-steps-and-build-events.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Understanding Custom Build Steps and Build Events" title: "Understanding Custom Build Steps and Build Events" ms.date: "08/29/2019" helpviewer_keywords: ["builds [C++], events", "custom build steps [C++], customizing builds", "events [C++], build", "custom build steps [C++]", "build steps [C++]", "build events [C++], order of events and build steps", "build steps [C++], build events", "builds [C++], custom build steps"] ms.assetid: beb2f017-3e9f-4b2c-9b57-2572fd2628e4 +ms.topic: how-to --- # Understanding Custom Build Steps and Build Events 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 2166435a39..c0bc39deb7 100644 --- a/docs/build/understanding-manifest-generation-for-c-cpp-programs.md +++ b/docs/build/understanding-manifest-generation-for-c-cpp-programs.md @@ -1,18 +1,292 @@ --- -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 +ms.topic: how-to --- -# 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/using-database-ole-and-sockets-extension-dlls-in-regular-dlls.md b/docs/build/using-database-ole-and-sockets-extension-dlls-in-regular-dlls.md index b88658db26..08d3cbd88f 100644 --- a/docs/build/using-database-ole-and-sockets-extension-dlls-in-regular-dlls.md +++ b/docs/build/using-database-ole-and-sockets-extension-dlls-in-regular-dlls.md @@ -1,64 +1,65 @@ --- title: "Using Database, OLE, and Sockets MFC extension DLLs in regular MFC DLLs" -ms.date: "11/04/2016" +description: "Shows how to use the Database, OLE, and Sockets MFC extension DLLs in regular MFC DLLs." +ms.date: 11/30/2020 helpviewer_keywords: ["DLLs [C++], initializing", "DLLs [C++], extension", "DLLs [C++], regular"] -ms.assetid: 9f1d14a7-9e2a-4760-b3b6-db014fcdb7ff +ms.topic: concept-article --- # Using Database, OLE, and Sockets MFC extension DLLs in regular MFC DLLs -When using an MFC extension DLL from a regular MFC DLL, if the MFC extension DLL is not wired into the **CDynLinkLibrary** object chain of the regular MFC DLL, you might run into one or more of a set of related problems. Because the debug versions of the MFC Database, OLE, and Sockets support DLLs are implemented as MFC extension DLLs, you might see similar problems if you are using these MFC features, even if you are not explicitly using any of your own MFC extension DLLs. Some symptoms are: +When using an MFC extension DLL from a regular MFC DLL, if the MFC extension DLL isn't wired into the `CDynLinkLibrary` object chain of the regular MFC DLL, you might run into one or more related problems. Because the debug versions of the MFC Database, OLE, and Sockets support DLLs are implemented as MFC extension DLLs, you might see similar problems if you're using these MFC features, even if you're not explicitly using any of your own MFC extension DLLs. Some symptoms are: - When attempting to deserialize an object of a type of class defined in the MFC extension DLL, the message "Warning: Cannot load CYourClass from archive. Class not defined." appears in the TRACE debug window and the object fails to serialize. - An exception indicating bad class might be thrown. -- Resources stored in the MFC extension DLL fail to load because `AfxFindResourceHandle` returns **NULL** or an incorrect resource handle. +- Resources stored in the MFC extension DLL fail to load because `AfxFindResourceHandle` returns `NULL` or an incorrect resource handle. - `DllGetClassObject`, `DllCanUnloadNow`, and the `UpdateRegistry`, `Revoke`, `RevokeAll`, and `RegisterAll` member functions of `COleObjectFactory` fail to locate a class factory defined in the MFC extension DLL. -- `AfxDoForAllClasses` does not work for any classes in the MFC extension DLL. +- `AfxDoForAllClasses` doesn't work for any classes in the MFC extension DLL. -- Standard MFC database, sockets, or OLE resources fail to load. For example, **AfxLoadString**(**AFX_IDP_SQL_CONNECT_FAIL**) returns an empty string, even when the regular MFC DLL is properly using the MFC Database classes. +- Standard MFC database, sockets, or OLE resources fail to load. For example, `AfxLoadString(AFX_IDP_SQL_CONNECT_FAIL)` returns an empty string, even when the regular MFC DLL is properly using the MFC Database classes. -The solution to these problems is to create and export an initialization function in the MFC extension DLL that creates a **CDynLinkLibrary** object. Call this initialization function exactly once from each regular MFC DLL that uses the MFC extension DLL. +The solution to these problems is to create and export an initialization function in the MFC extension DLL that creates a `CDynLinkLibrary` object. Call this initialization function exactly once from each regular MFC DLL that uses the MFC extension DLL. ## MFC OLE, MFC Database (or DAO), or MFC Sockets Support -If you are using any MFC OLE, MFC Database (or DAO), or MFC Sockets support in your regular MFC DLL, respectively, the MFC debug MFC extension DLLs MFCOxxD.dll, MFCDxxD.dll, and MFCNxxD.dll (where xx is the version number) are linked automatically. You must call a predefined initialization function for each of these DLLs that you are using. +If you're using any MFC OLE, MFC Database (or DAO), or MFC Sockets support in your regular MFC DLL, respectively, the MFC debug MFC extension DLLs *`MFCOxxD.dll`*, *`MFCDxxD.dll`*, and *`MFCNxxD.dll`* (where *xx* is the version number) are linked automatically. Call a predefined initialization function for each of the DLLs that you're using: -For database support, add a call to `AfxDbInitModule` to your regular MFC DLL's `CWinApp::InitInstance` function. Make sure this call occurs before any base-class call or any added code which accesses the MFCDxxD.dll. This function takes no parameters and returns void. +- For database support, add a call to `AfxDbInitModule` to your regular MFC DLL in its `CWinApp::InitInstance` function. Make sure this call occurs before any base-class call or any added code that accesses the *`MFCDxxD.dll`*. This function takes no parameters and returns `void`. -For OLE support, add a call to `AfxOleInitModule` to your regular MFC DLL's `CWinApp::InitInstance`. Note that the **COleControlModule InitInstance** function calls `AfxOleInitModule` already, so if you are building an OLE control and are using `COleControlModule`, you should not add this call to `AfxOleInitModule`. +- For OLE support, add a call to `AfxOleInitModule` to your regular MFC DLL it its `CWinApp::InitInstance` function. The `COleControlModule::InitInstance` function calls `AfxOleInitModule` already, so if you're building an OLE control and use `COleControlModule`, you shouldn't add this call to `AfxOleInitModule`. -For Sockets support, add a call to `AfxNetInitModule` to your regular MFC DLL's `CWinApp::InitInstance`. +- For Sockets support, add a call to `AfxNetInitModule` to your regular MFC DLL in `CWinApp::InitInstance`. -Note that release builds of MFC DLLs and applications do not use separate DLLs for database, sockets, or OLE support. However, it is safe to call these initialization functions in release mode. +Release builds of MFC DLLs and applications don't use separate DLLs for database, sockets, or OLE support. However, it's safe to call these initialization functions in release mode. ## CDynLinkLibrary Objects -During each of the operations mentioned at the beginning of this topic, MFC needs to search for a desired value or object. For example, during deserialization, MFC needs to search through all the currently available run-time classes to match objects in the archive with their proper run-time class. +During each operation mentioned at the beginning of this article, MFC needs to search for a particular value or object. For example, during deserialization, MFC needs to search through all the currently available run-time classes to match objects in the archive with their proper run-time class. -As a part of these searches, MFC scans through all the MFC extension DLLs in use by walking a chain of **CDynLinkLibrary** objects. **CDynLinkLibrary** objects attach automatically to a chain during their construction and are created by each MFC extension DLL in turn during initialization. In addition, every module (application or regular MFC DLL) has its own chain of **CDynLinkLibrary** objects. +As a part of these searches, MFC scans through all the MFC extension DLLs in use by walking a chain of `CDynLinkLibrary` objects. `CDynLinkLibrary` objects attach automatically to a chain during their construction and are created by each MFC extension DLL in turn during initialization. Every module (application or regular MFC DLL) has its own chain of `CDynLinkLibrary` objects. -For an MFC extension DLL to get wired into a **CDynLinkLibrary** chain, it must create a **CDynLinkLibrary** object in the context of every module that uses the MFC extension DLL. Therefore, if an MFC extension DLL is going to be used from regular MFC DLLs, it must provide an exported initialization function that creates a **CDynLinkLibrary** object. Every regular MFC DLL that uses the MFC extension DLL must call the exported initialization function. +For an MFC extension DLL to get wired into a `CDynLinkLibrary` chain, it must create a `CDynLinkLibrary` object in the context of every module that uses the MFC extension DLL. To use an MFC extension DLL in regular MFC DLLs, the extension DLL must provide an exported initialization function that creates a `CDynLinkLibrary` object. Every regular MFC DLL that uses the MFC extension DLL must call the exported initialization function. -If an MFC extension DLL is only going to be used from an MFC application (.exe) and never from a regular MFC DLL, then it is sufficient to create the **CDynLinkLibrary** object in the MFC extension DLL's `DllMain`. This is what the MFC DLL Wizard MFC extension DLL code does. When loading an MFC extension DLL implicitly, `DllMain` loads and executes before the application ever starts. Any **CDynLinkLibrary** creations are wired into a default chain that the MFC DLL reserves for an MFC application. +If you'll only use an MFC extension DLL from an MFC application, and never from a regular MFC DLL, then it's sufficient to create the `CDynLinkLibrary` object in the MFC extension DLL `DllMain` function. It's what the MFC DLL Wizard MFC extension DLL code does. When loading an MFC extension DLL implicitly, `DllMain` loads and executes before the application ever starts. Any `CDynLinkLibrary` creations are wired into a default chain that the MFC DLL reserves for an MFC application. -Note that it is a bad idea to have multiple **CDynLinkLibrary** objects from one MFC extension DLL in any one chain, especially if the MFC extension DLL will be dynamically unloaded from memory. Do not call the initialization function more than once from any one module. +It's a bad idea to have multiple `CDynLinkLibrary` objects from one MFC extension DLL in any one chain. It's especially true if the MFC extension DLL may be dynamically unloaded from memory. Don't call the initialization function more than once from any one module. ## Sample Code -This sample code assumes that the regular MFC DLL is implicitly linking to the MFC extension DLL. This is accomplished by linking to the import library (.lib) of the MFC extension DLL when building the regular MFC DLL. +This sample code assumes that the regular MFC DLL implicitly links to the MFC extension DLL. To link implicitly, link to the import library (LIB file) of the MFC extension DLL when you build the regular MFC DLL. The following lines should be in the source of the MFC extension DLL: -``` +```cpp // YourExtDLL.cpp: // standard MFC extension DLL routines #include "afxdllx.h" -static AFX_EXTENSION_MODULE NEAR extensionDLL = { NULL, NULL }; +static AFX_EXTENSION_MODULE extensionDLL; extern "C" int APIENTRY DllMain(HINSTANCE hInstance, DWORD dwReason, LPVOID lpReserved) @@ -83,9 +84,9 @@ extern "C" void WINAPI InitYourExtDLL() } ``` -Be sure to export the **InitYourExtDLL** function. This could be done using **`__declspec(dllexport)`** or in your DLL's .def file as follows: +Be sure to export the **InitYourExtDLL** function. You can use **`__declspec(dllexport)`**, or export it in the DEF file for your DLL, as shown here: -``` +```def // YourExtDLL.Def: LIBRARY YOUREXTDLL CODE PRELOAD MOVEABLE DISCARDABLE @@ -96,7 +97,7 @@ EXPORTS Add a call to the `InitInstance` member of the `CWinApp`-derived object in each regular MFC DLL using the MFC extension DLL: -``` +```cpp // YourRegularDLL.cpp: class CYourRegularDLL : public CWinApp diff --git a/docs/build/using-function-name-without-parens-produces-no-code.md b/docs/build/using-function-name-without-parens-produces-no-code.md index 1a01287707..8b08e80798 100644 --- a/docs/build/using-function-name-without-parens-produces-no-code.md +++ b/docs/build/using-function-name-without-parens-produces-no-code.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Using Function Name Without () Produces No Code" title: "Using Function Name Without () Produces No Code" ms.date: "11/04/2016" helpviewer_keywords: ["functions [C++], without parentheses"] ms.assetid: edf4a177-a160-44aa-8436-e077b5b27809 +ms.topic: concept-article --- # Using Function Name Without () Produces No Code diff --git a/docs/build/using-the-debug-build-to-check-for-memory-overwrite.md b/docs/build/using-the-debug-build-to-check-for-memory-overwrite.md index 8c743f49d7..36aae3bdec 100644 --- a/docs/build/using-the-debug-build-to-check-for-memory-overwrite.md +++ b/docs/build/using-the-debug-build-to-check-for-memory-overwrite.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Using the Debug Build to Check for Memory Overwrite" title: "Using the Debug Build to Check for Memory Overwrite" ms.date: "11/04/2016" helpviewer_keywords: ["memory, overwrites"] ms.assetid: 1345eb4d-24ba-4595-b1cc-2da66986311e +ms.topic: how-to --- # Using the Debug Build to Check for Memory Overwrite diff --git a/docs/build/using-verify-instead-of-assert.md b/docs/build/using-verify-instead-of-assert.md index 0d40aa2172..f9e9350bc0 100644 --- a/docs/build/using-verify-instead-of-assert.md +++ b/docs/build/using-verify-instead-of-assert.md @@ -1,8 +1,10 @@ --- +description: "Learn more about: Using VERIFY Instead of ASSERT" title: "Using VERIFY Instead of ASSERT" ms.date: "05/06/2019" helpviewer_keywords: ["ASSERT statements", "debugging [MFC], ASSERT statements", "VERIFY macro", "assertions, troubleshooting ASSERT statements", "debugging assertions", "assertions, debugging"] ms.assetid: 4c46397b-3fb1-49c1-a09b-41a72fae3797 +ms.topic: concept-article --- # Using VERIFY Instead of ASSERT diff --git a/docs/build/vcpkg.md b/docs/build/vcpkg.md deleted file mode 100644 index 226305fd1a..0000000000 --- a/docs/build/vcpkg.md +++ /dev/null @@ -1,271 +0,0 @@ ---- -title: "vcpkg: a C++ package manager for Windows, Linux, and macOS" -description: "vcpkg is a command-line package manager that greatly simplifies the acquisition and installation of open-source C++ libraries on Windows, macOS, and Linux." -ms.date: "07/06/2020" -ms.technology: "cpp-ide" -ms.assetid: f50d459a-e18f-4b4e-814b-913e444cedd6 ---- -# vcpkg: a C++ package manager for Windows, Linux, and macOS - -vcpkg is a command-line package manager for C++. It greatly simplifies the acquisition and installation of third-party libraries on Windows, Linux, and macOS. If your project uses third-party libraries, we recommend that you use vcpkg to install them. vcpkg supports both open-source and proprietary libraries. All libraries in the vcpkg Windows catalog have been tested for compatibility with Visual Studio 2015, Visual Studio 2017, and Visual Studio 2019. Between the Windows and Linux/macOS catalogs, vcpkg now supports over 1900 libraries. The C++ community is adding more libraries to both catalogs on an ongoing basis. - -## Simple yet flexible - -With a single command, you can download sources and build a library. vcpkg is itself an open-source project, available on GitHub. It's possible to customize your private vcpkg clones in any way you like. For example, specify different libraries, or different versions of libraries than the ones found in the public catalog. You can have multiple clones of vcpkg on a single machine. Each one may be set to produce a custom collection of libraries, with your preferred compilation switches. Each clone is a self-contained environment with its own copy of vcpkg.exe that operates only on its own hierarchy. vcpkg isn't added to any environment variables, and has no dependency on the Windows Registry or Visual Studio. - -## Sources, not binaries - -For libraries in the Windows catalog, vcpkg downloads sources instead of binaries1. It compiles those sources using the most recent version of Visual Studio that it can find. In C++, it's important that both your application code and any libraries you use are compiled by the same compiler, and compiler version. By using vcpkg, you eliminate or at least greatly reduce the potential for mismatched binaries and the problems they can cause. In teams that are standardized on a specific version of a compiler, one team member can use vcpkg to download sources and compile a set of binaries. Then they can use the export command to zip up the binaries and headers for other team members. For more information, see [Export compiled binaries and headers](#export_binaries_per_project) below. - -You can also create a vcpkg clone that has private libraries in the ports collection. Add a port that downloads your prebuilt binaries and headers. Then, write a *portfile.cmake* file that simply copies those files to the preferred location. - -1 *Note: sources are unavailable for some proprietary libraries. In these cases, vcpkg downloads compatible prebuilt binaries.* - -## Installation - -Clone the vcpkg repo from GitHub: [https://github.com/Microsoft/vcpkg](https://github.com/Microsoft/vcpkg). You can download to any folder location you prefer. This location is the vcpkg *root*. Once the download is complete, change to that directory in your command shell. - -In the vcpkg root directory, run the vcpkg bootstrapper: - -- **`bootstrap-vcpkg.bat`** (Windows) -- **`./bootstrap-vcpkg.sh`** (Linux, macOS) - -On Linux or macOS, you may need to prefix vcpkg commands by using **`./`** in the examples that follow. Remember to run these commands from the vcpkg root directory. - -## Search the list of available libraries - -To see what packages are available, type **`vcpkg search`** at the command prompt. - -This command enumerates the control files in the *vcpkg/ports* subfolders. You'll see a listing like this: - -```cmd -ace 6.4.3 The ADAPTIVE Communication Environment -anax 2.1.0-1 An open source C++ entity system. \ vcpkg install boost:x86-windows - -The following packages will be built and installed: - boost:x86-windows - * bzip2:x86-windows - * zlib:x86-windows -Additional packages (*) will be installed to complete this operation. -``` - -For CMake projects, use `CMAKE_TOOLCHAIN_FILE` to make libraries available with `find_package()`. For example, on Linux or macOS: - -```cmd -cmake .. -DCMAKE_TOOLCHAIN_FILE=vcpkg/scripts/buildsystems/vcpkg.cmake -``` - -On Windows: - -```cmd -cmake .. -DCMAKE_TOOLCHAIN_FILE=vcpkg\scripts\buildsystems\vcpkg.cmake -``` - -Some libraries include installable options. For example, when you search for the curl library, you'll also see a list of supported options in square brackets: - -```cmd -> vcpkg search curl -curl 7.68.0-3 A library for transferring data with URLs -curl[tool] Builds curl executable -curl[non-http] Enables protocols beyond HTTP/HTTPS/HTTP2 -curl[http2] HTTP2 support -curl[ssl] Default SSL backend -curl[ssh] SSH support via libssh2 -curl[openssl] SSL support (OpenSSL) -curl[winssl] SSL support (Secure Channel / "WinSSL") -curl[mbedtls] SSL support (mbedTLS) -curl[sectransp] SSL support (sectransp) -curl[c-ares] c-ares support -curl[sspi] SSPI support -curl[brotli] brotli support (brotli) -curlpp 2018-06-15-3 C++ wrapper around libcURL -``` - -In this case, the square brackets **`[`** and **`]`** are literals, not metacharacters. - -You can specify a specific option to install on the command line. For example, to install libraries for curl using the default SSL backend for Windows, use the **`vcpkg install curl[ssl]:x86-windows`** command. The command installs any required prerequisites, including the core library, if needed: - -```cmd -> vcpkg list -curl:x86-windows 7.68.0-3 A library for transferring data with URLs -curl[non-http]:x86-windows Enables protocols beyond HTTP/HTTPS/HTTP2 -curl[ssl]:x86-windows Default SSL backend -curl[sspi]:x86-windows SSPI support -curl[winssl]:x86-windows SSL support (Secure Channel / "WinSSL") -zlib:x86-windows 1.2.11-6 A compression library -``` - -## List the libraries already installed - -After you've installed some libraries, you can use **`vcpkg list`** to see what you have: - -```cmd -> vcpkg list - -boost:x86-windows 1.64-3 Peer-reviewed portable C++ source libraries -bzip2:x86-windows 1.0.6-1 High-quality data compressor. -cpprestsdk:x86-windows 2.9.0-2 C++11 JSON, REST, and OAuth library The C++ REST ... -openssl:x86-windows 1.0.2k-2 OpenSSL is an open source project that provides a... -websocketpp:x86-windows 0.7.0 Library that implements RFC6455 The WebSocket Pro... -zlib:x86-windows 1.2.11 A compression library -``` - -## Integrate with Visual Studio (Windows) - -### Per-user - -Run **`vcpkg integrate install`** to configure Visual Studio to locate all vcpkg header files and binaries on a per-user basis. There's no need for manual editing of VC++ Directories paths. If you have multiple clones of vcpkg, the clone you run this command from becomes the new default location. - -Now you can #include headers simply by typing the folder/header, and autocomplete assists you. No additional steps are required for linking to libs or adding project references. The following illustration shows how Visual Studio finds the azure-storage-cpp headers. vcpkg places its headers in the */installed* subfolder, partitioned by target platform. The following diagram shows the list of include files in the */was* subfolder for the library: - -![vcpkg and IntelliSense](media/vcpkg-intellisense.png "vcpkg and IntelliSense") - -### Per project - -If you need to use a specific version of a library that's different from the version in your active vcpkg instance, follow these steps: - -1. Make a new clone of vcpkg -1. Modify the portfile for the library to obtain the version you need -1. Run **`vcpkg install `**. -1. Use **`vcpkg integrate project`** to create a NuGet package that references that library on a per-project basis. - -## Integrate with Visual Studio Code (Linux/macOS) - -Run **`vcpkg integrate install`** to configure Visual Studio Code on Linux/macOS. This command sets the location of the vcpkg enlistment and enables IntelliSense on source files. - -## Target Linux from Windows via WSL - -You can produce Linux binaries on a Windows machine by using the Windows Subsystem for Linux, or WSL. Follow the instructions to [Set up WSL on Windows 10](/windows/wsl/install-win10). Then, configure it with the [Visual Studio extension for Linux](https://devblogs.microsoft.com/cppblog/targeting-windows-subsystem-for-linux-from-visual-studio/). It's okay to put all your built libraries for Windows and Linux into the same folder. They're accessible from both Windows and WSL. - -## Export compiled binaries and headers - -It's inefficient to make everyone on a team download and build common libraries. A single team member can use the **`vcpkg export`** command to create a common zip file of the binaries and headers, or a NuGet package. Then, it's easy to share it with other team members. - -## Update/upgrade installed libraries - -The public catalog is kept up to date with the latest versions of the libraries. To determine which of your local libraries are out-of-date, use **`vcpkg update`**. When you're ready to update your ports collection to the latest version of the public catalog, run the **`vcpkg upgrade`** command. It automatically downloads and rebuilds any or all of your installed libraries that are out of date. - -By default, the **`vcpkg upgrade`** command only lists the libraries that are out of date; it doesn't upgrade them. To actually upgrade the libraries, use the **`--no-dry-run`** option. - -```cmd -> vcpkg upgrade --no-dry-run -``` - -### Upgrade Options - -- **`--no-dry-run`** Perform the upgrade; when not specified, the command only lists the out-of-date packages. -- **`--keep-going`** Continue installing packages even if one fails. -- **`--triplet `** Set the default triplet for unqualified packages. -- **`--vcpkg-root `** Specify the vcpkg directory to use instead of current directory or tool directory. - -### Upgrade example - -The following example shows how to upgrade only specified libraries. vcpkg automatically pulls in dependencies as necessary. - -```cmd -c:\users\satyan\vcpkg> vcpkg upgrade tiny-dnn:x86-windows zlib -The following packages are up-to-date: - tiny-dnn:x86-windows - -The following packages will be rebuilt: - * libpng[core]:x86-windows - * tiff[core]:x86-windows - zlib[core]:x86-windows -Additional packages (*) will be modified to complete this operation. -If you are sure you want to rebuild the above packages, run this command with the --no-dry-run option. -``` - -## Contribute new libraries - -You can include any libraries you like in your private ports collection. To suggest a new library for the public catalog, open an issue on the [GitHub vcpkg issue page](https://github.com/Microsoft/vcpkg/issues). - -## Remove a library - -Type **`vcpkg remove`** to remove an installed library. If any other libraries depend on it, you're asked to rerun the command with **`--recurse`**, which causes all downstream libraries to be removed. - -## Customize vcpkg - -You can modify your clone of vcpkg in any way you like. You can even create multiple vcpkg clones, then modify the portfiles in each one. That's a simple way to obtain specific library versions, or to specify particular command-line parameters. For example, individual groups of developers in an enterprise might work on software that has dependencies specific to their group. The solution is to set up a clone of vcpkg for each team. Then, modify the clones to download the library versions and set the compilation switches that each team needs. - -## Update vcpkg - -The vcpkg package manager is updated regularly on GitHub. To update your clone of vcpkg to the latest version, from the vcpkg root directory, run **`git pull`**. This command syncs your copy of vcpkg with the version on GitHub. After download is complete, run the bootstrapper again. The bootstrapper rebuilds the vcpkg program, but leaves your installed libraries in place. - -## Uninstall vcpkg - -To uninstall vcpkg, just delete the vcpkg directory. Deleting this directory uninstalls the vcpkg distribution, and all the libraries that vcpkg has installed. - -## Send feedback about vcpkg - -Use the **`vcpkg contact --survey`** command to send feedback to Microsoft about vcpkg, including bug reports and suggestions for features. - -## The vcpkg folder hierarchy - -All vcpkg functionality and data is self-contained in a single directory hierarchy, called an "instance". There are no registry settings or environment variables. You can have any number of instances of vcpkg on a machine, and they won't interfere with each other. - -The contents of a vcpkg instance are: - -- buildtrees - contains subfolders of sources from which each library is built -- docs - documentation and examples -- downloads - cached copies of any downloaded tools or sources. vcpkg searches here first when you run the install command. -- installed - Contains the headers and binaries for each installed library. When you integrate with Visual Studio, you're essentially telling it add this folder to its search paths. -- packages - Internal folder for staging between installs. -- ports - Files that describe each library in the catalog, its version, and where to download it. You can add your own ports if needed. -- scripts - Scripts (CMake, PowerShell) used by vcpkg. -- toolsrc - C++ source code for vcpkg and related components -- triplets - Contains the settings for each supported target platform (for example, x86-windows or x64-uwp). - -## Command-line reference - -|Command|Description| -|---------|---------| -|**`vcpkg search [pat]`**|Search for packages available to install| -|**`vcpkg install ...`**|Install a package| -|**`vcpkg remove ...`**|Uninstall a package| -|**`vcpkg remove --outdated`**|Uninstall all out-of-date packages| -|**`vcpkg list`**|List installed packages| -|**`vcpkg update`**|Display list of packages for updating| -|**`vcpkg upgrade`**|Rebuild all outdated packages| -|**`vcpkg hash [alg]`**|Hash a file by specific algorithm, default SHA512| -|**`vcpkg integrate install`**|Make installed packages available user-wide. Requires admin privileges on first use| -|**`vcpkg integrate remove`**|Remove user-wide integration| -|**`vcpkg integrate project`**|Generate a referencing NuGet package for individual VS project use| -|**`vcpkg export ... [opt]...`**|Export a package| -|**`vcpkg edit `**|Open up a port for editing (uses %EDITOR%, default 'code')| -|**`vcpkg create [archivename]`**|Create a new package| -|**`vcpkg cache`**|List cached compiled packages| -|**`vcpkg version`**|Display version information| -|**`vcpkg contact --survey`**|Display contact information to send feedback.| - -### Options - -|Option|Description| -|---------|---------| -|**`--triplet `**|Specify the target architecture triplet. (default: `%VCPKG_DEFAULT_TRIPLET%`, see also **`vcpkg help triplet`**)| -|**`--vcpkg-root `**|Specify the vcpkg root directory (default: `%VCPKG_ROOT%`)| diff --git a/docs/build/vscpp-step-0-installation.md b/docs/build/vscpp-step-0-installation.md index 6c4642f8f8..5ce61195dc 100644 --- a/docs/build/vscpp-step-0-installation.md +++ b/docs/build/vscpp-step-0-installation.md @@ -1,30 +1,135 @@ --- title: Install C and C++ support in Visual Studio -description: "Install Visual Studio support for Visual C++" -ms.custom: "mvc" -ms.date: "04/02/2019" -ms.topic: "tutorial" +description: "Learn how to install Visual Studio with support for Microsoft C and C++ and related workloads." +ms.date: 03/18/2025 +ms.topic: tutorial ms.devlang: "cpp" -ms.assetid: 45138d70-719d-42dc-90d7-1d0ca31a2f54 +ms.custom: + - vs-acquisition + - intro-installation + - sfi-image-nochange --- # 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="vs-2019" +::: moniker range="msvc-170" -## Visual Studio 2019 Installation +## Visual Studio 2022 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 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 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/2022/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: + +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 + +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 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/2019/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: @@ -32,75 +137,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, choose the edition of Visual Studio that you want, choose **Save**, and then choose **Open folder**. +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 to install the Visual Studio Installer. This new lightweight installer includes everything you need to both install and customize Visual Studio. +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: +1. From your *Downloads* folder, double-click the bootstrapper file. - - **vs_community.exe** for Visual Studio Community - - **vs_professional.exe** for Visual Studio Professional - - **vs_enterprise.exe** for Visual Studio Enterprise + If you receive a User Account Control notice, choose **Yes** to allow the bootstrapper to run. - If you receive a User Account Control notice, choose **Yes**. - -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,25 +212,23 @@ 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! ::: moniker-end -::: moniker range="vs-2017" +::: 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,49 +236,39 @@ For details on the disk space and operating system requirements, see [Visual Stu ### Download and install -1. Download the latest Visual Studio 2017 installer for Windows. +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. - > [!div class="nextstepaction"] - > [Install Visual Studio 2017 Community](https://visualstudio.microsoft.com/downloads/?utm_medium=microsoft&utm_source=docs.microsoft.com&utm_campaign=button+cta&utm_content=download+vs2017) +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. - >[!Tip] - > The Community edition is for individual developers, classroom learning, academic research, and open source development. For other uses, install [Visual Studio 2017 Professional](https://visualstudio.microsoft.com/downloads/?utm_medium=microsoft&utm_source=docs.microsoft.com&utm_campaign=button+cta&utm_content=download+vs2017) or [Visual Studio 2017 Enterprise](https://visualstudio.microsoft.com/downloads/?utm_medium=microsoft&utm_source=docs.microsoft.com&utm_campaign=button+cta&utm_content=download+vs2017). - -1. Find the installer file you downloaded and run it. It 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. - - ![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. ::: moniker-end -::: moniker range=" [!div class="nextstepaction"] -> [Create a C++ project](vscpp-step-1-create.md) - -