|
| 1 | +--- |
| 2 | +title: "C++ Include Diagnostics" |
| 3 | +description: "Learn how to use #include Diagnostics in Visual Studio to analyze how often something from an include file is used and how an #include impacts build time." |
| 4 | +ms.date: 10/10/2023 |
| 5 | +ms.topic: "how-to" |
| 6 | +f1_keywords: ["include diagnostics"] |
| 7 | +helpviewer_keywords: ["include diagnostics"] |
| 8 | +--- |
| 9 | +# C++ Include Diagnostics in Visual Studio |
| 10 | + |
| 11 | +Starting with Visual Studio 17.8, Visual Studio helps you analyze your C++ `#include` files: |
| 12 | + |
| 13 | +- Displays how often, and where, something from each header file is used. |
| 14 | +- Displays the build time for each `#include` file--which helps you identify opportunities to optimize your build time. |
| 15 | + |
| 16 | +## Enable C++ Include Diagnostics and CodeLens |
| 17 | + |
| 18 | +The C++ Include Diagnostics feature is off by default. To turn it on, right-click in the code editor to bring up the context menu, and choose **Include Directives** > **Turn #include Diagnostics On**. |
| 19 | + |
| 20 | +:::image type="complex" source="media/vs2022-enable-include-diagnostics.png" alt-text="A screenshot of the context menu that appears when you right-click in the code editor area."::: |
| 21 | +The context menu shows the include directives option highlighted, which reveals two options: Sort # include directives and turn # include diagnostics on. |
| 22 | +:::image-end::: |
| 23 | + |
| 24 | +Information about your `#include` files is displayed via CodeLens, which is off by default. To turn on the relevant CodeLens settings, navigate to **Tools** > **Options** > **Text Editor** > **All Languages** > **CodeLens** and confirm both **Show C++ #include references** and **Show C++ compilation times** are enabled. |
| 25 | + |
| 26 | +:::image type="complex" source="media/vs2022-enable-code-lens-for-includes.png" alt-text="A screenshot of the options window."::: |
| 27 | +The options window is set to Text Editor > All Languages > CodeLens. The Show C++ # include references and Show C++ compilation times options are highlighted. |
| 28 | +:::image-end::: |
| 29 | + |
| 30 | +## View `#include` references |
| 31 | + |
| 32 | +To try out Include Diagnostics, create a new C++ console project. Replace the contents of the main `.cpp` file with the following code: |
| 33 | + |
| 34 | +```cpp |
| 35 | +#include <iostream> |
| 36 | +#include <vector> |
| 37 | + |
| 38 | +// a function that takes a vector of integers and prints them out |
| 39 | +void print(std::vector<int> &vec) |
| 40 | +{ |
| 41 | + for (int i : vec) |
| 42 | + { |
| 43 | + std::cout << i << std::endl; |
| 44 | + } |
| 45 | + std::cout << std::endl; |
| 46 | +} |
| 47 | + |
| 48 | +// a function that takes a vector of integers and adds 10 to each element of the vector and store the result in a new vector |
| 49 | +std::vector<int> add10(std::vector<int>& vec) |
| 50 | +{ |
| 51 | + std::vector<int> newVec; |
| 52 | + for (int i : vec) |
| 53 | + { |
| 54 | + newVec.push_back(i + 10); |
| 55 | + } |
| 56 | + return newVec; |
| 57 | +} |
| 58 | + |
| 59 | +int main() |
| 60 | +{ |
| 61 | + std::vector<int> vec = { 7, 5, 16, 8 }; |
| 62 | + |
| 63 | + print(vec); |
| 64 | + auto newVec = add10(vec); |
| 65 | + print(newVec); |
| 66 | +} |
| 67 | +``` |
| 68 | +
|
| 69 | +When C++ Include Diagnostics are turned on, the number of times code from a header file is referenced in the current code file is displayed above the header file. It looks like this for the previous code sample: |
| 70 | +
|
| 71 | +```cpp |
| 72 | +6 references |
| 73 | +#include <iostream> |
| 74 | +5 references |
| 75 | +#include <vector> |
| 76 | +``` |
| 77 | + |
| 78 | +In the code editor, select **5 references** above `#include <vector>` and a summary of locations where code from `<vector>` is used in this file is displayed: |
| 79 | + |
| 80 | +:::image type="complex" source="media/visual-studio-2022-codelens-include-references.png" alt-text="A screenshot of the C++ Include Diagnostics context window showing where code from the vector header file is used."::: |
| 81 | +The C++ Include Diagnostics context window shows that there are five places in the code where code from the vector header file is used in the current code file. For example, it's used twice on the definition of the add10 function, as a return value and parameter. It's used on line 17 in the declaration of newVec, and so on. |
| 82 | +:::image-end::: |
| 83 | + |
| 84 | +Select an item to go to its location in your code. |
| 85 | + |
| 86 | +## View `#include` build time |
| 87 | + |
| 88 | +To see the build time for each file you `#include`, first build using Build Insights. |
| 89 | + |
| 90 | +Turn on Build Insights from the main menu bar by selecting **Build** > **Run Build Insights on Solution** > **Build**. After the build completes, a window appears to list the build times for the various files that are compiled. Return to the source code window, and the build time for each `#include` file is displayed in CodeLens. It looks similar to this: |
| 91 | + |
| 92 | +```cpp |
| 93 | +6 references | Build: 0.3560s |
| 94 | +#include <iostream> |
| 95 | +5 references | Build 0.0360s |
| 96 | +#include <vector> |
| 97 | +``` |
| 98 | + |
| 99 | +If you have an `#include` directive that is used infrequently, but significantly impacts your compile time, this tool can help you identify it. |
| 100 | + |
| 101 | +In this article, you've seen how to turn on C++ Include Diagnostics and CodeLens, and how to use C++ Include Diagnostics to analyze how often something from an include file is used and how an `#include` impacts build time. |
| 102 | + |
| 103 | +## See also |
| 104 | + |
| 105 | +[C/C++ Include Cleanup overview](include-cleanup-overview.md)\ |
| 106 | +[Include Cleanup messages](include-cleanup-messages.md) |
![learn-build-service-prod[bot]](https://avatars.githubusercontent.com/in/237442?v=4&size=40){kind=avatar}
![prmerger-automator[bot]](https://avatars.githubusercontent.com/u/22479449?v=4&size=40){kind=avatar}
0 commit comments