Tools for managing C/C++ #includes: Formatting, sorting, exploring, pruning.

Include Toolbox consists of 4 different tools. All of them are only applicable to VC++ projects.

[Command] Include Formatter
[Command] Trial and Error Include Removal
[Command] Include-What-You-Use Integration
[Tool Window] Include Graph

Tools in Detail

Include Formatter

Select a group of includes, right click, select "Format Selected Includes"

The behavior of this command is controlled by various options which can be configured in Tools>Options>Include Toolbox>Include Formatter:

Formatting
- Delimiter Mode
  Optionally change "" to <> or vice versa
- Slash Mode
  Optionally changes / to \ or vice versa
- Remove Empty Lines
  Optionally removes empty lines within the selection
Path Reformatting
- Ignore File Relative
  If true, the local file path will not be considered for reformatting the path
- Mode
  Configures the strategy that should be used to determine new include paths
Sorting
The tool will always sort all selected includes alphabeticaly, unless..
- Precedence Regex
  Every line gives a regex - if an include matches a regex, it has precedence over all other includes that do not match any, or a later regex. Multiple includes that match the same regex are still alphabetically sorted.
- Sort by Include Type
  Optionally puts all inclues with either quotes or angle brackets first.

All operations are performed in the order in which they occur on the option page.

Trial and Error Include Removal

The name says it all: This tool will try to remove an include, recompile, see if it works and proceed to the next one accordingly.
The tool can be started an all compilable files in a VC++ by right clicking on the code window. There is also a special version in the Project context menu which will run over every single file in the project (takes very long).

Obviously the results of this tool are far from optimal and the process can take a while.

The exact behavior of this command can be controlled in Tools>Options>Include Toolbox>Trial and Error Include Removal:

Ignore List
A list of regexes. If the content of an include matches any of these, it will never be removed.
Ignore First Include
If true the top most include will always be ignored
Removal Order
Wheater the tool should run from top to bottom or bottom to top (this can make a difference on the end result)

Include-What-You-Use Integration

Include Toolbox with an integration of the free Include-What-You-Use. By default (see Tools>Options>Include Toolbox>Include-What-You-Use) it is downloaded together with a VC++ specific mapping file from this github repository upon first use (and whenever there is a newer version available in this repository).

Again, it can be activated by right clicking on a C++ Code file in a VC++ document. The Option page exposes most of IWYU's command line options and provides the option to directly apply the results. The complete output will be displayed in the Include Toolbox output window.

IWYU often does not work as expected - for more information look at the official docs.

Include Graph

The Include Graph tool window shows you all (transitive) includes of a file either in a hierarchical view or grouped by folder. You can find it the View menu under View>Other Windows>Include Graph.

There are two modes of parsing to choose from:

Direct Parsing (default)
- Uses a simplistic handwritten parser!
  - Works on all files!
  - Does not further parse any file that is in one of the folder listed in Tools>Options>Include Toolbox>Include Graph>Graph Endpoint Directories
    - (To prevent meaningless drilling down in standard library files)
- Completely Ignores #pragma once and preprocessor!
  - If an
- Has information on exact line number an include was done and double click in the hierarchy jumps to the place
Compile /showIncludes
- Compiles the file with vc.exe /showIncludes and parses the output
  - Works only on compilable files
- Output depends on preprocessed file - sticks to currently active preprocessors and pragmas
- No information about #include line numbers, double click jumps to the including file

The "Grouped by Folder" view shows only unique included files in a minimal folder tree. This can be useful to get a feeling of the modules a file is dependent on.

FAQ:

Why don't you apply the formatting to all includes within a file?
This may sound desirable, but is very messy if there are optional includes (preprocessor) or specific exceptions where not all includes should be in the same place or in the default order.
XY didn't work, what is going on?
Look in the output window for Include Toolbox to get more information.

Version History

2.1
- DGML graph saving feature improvements
  - Each nodes has information about child count and unique transitive child counts
  - Option to color elements by transitive child count
  - Option to group by folders, expanded or collapsed
  - Messageprompt after graph is saved, allows to open in VS directly
- Other fixes and small improvements
  - Renamed "Try and Error Include Removal" to "Trial and Error Include Removal" (thx to steronydh for reporting)
  - Include sorting treats other preprocessor directives as barrier over which includes can't be moved (thx to etiennehebert for reporting)
  - Pressing enter on item in Include Graph jumps to include (previously only double click)
  - Fixed Include Graph not displaying graph when switching active file while graph is computed
2.0.1
- Fixed bug that BlankAfterRegexGroupMatch option would only work if RemoveEmptyLines was active as well.
- Fixed crash in formatter if delimiter mode not "Unchanged" + "Remove Empty Lines" was false. (thx to etiennehebert for reporting)
- Include Graph folder items end now in slashes.
2.0
- Rewrote Include Graph ("Include Viewer" previously)
  - New, improved UI
  - Allows to display includes grouped by folder
  - Much faster graph bulid up using by direct parsing (as alternative to compile with /showIncludes)
  - Double click can navigate to include site
  - Graph can be saved as DGML file
- Trial-and-Error-Include-Removal "Ignore List" option does now support "$(currentFilename)" macro
  - Default setting include "(\/|\\\\|^)$(currentFilename)\.(h|hpp|hxx|inl|c|cpp|cxx)$" to ignore corresponding header file in removal
1.8
1.7
- .inl and _inl.h are by default ignored for trial-and-error-include-removal (configurable)
- New option for trial-and-error-include-removal to keep line breaks (off by default)
- Contributed by Adam Skoglund: Another fix for folder handling in trial-and-error-include-removal
1.6 - Contributed by Adam Skoglund
- Basic support for #if/#endif - any include within an #if/#endif block will be ignored.
- Better support for subdirectories in trial-and-error-include-removal on projects.
1.5
- Fixed problems with VCProject runtimes in VS2015 introduced in previous version.
  Required suprisingly large internal restructuring to support both VS2015 and VS2017 equally.
1.4
- Support for VS2017
- "Format Selected Includes" action is now only visible if includes were actually selected.
- "Format Selected Includes" works partially now also on files that are not in the currently loaded project
- Fixed an error in IWYU include removal parsing
1.3 - Contributed by Dakota Hawkins
- Added option to put spaces between precedence regex matches.
- Improved regex sorting via "Schwartzian transform" (= grouping by regex order number before sorting).
1.2 - Contributed by Dakota Hawkins
- Added option to include delimiters in precedence regex to allow more advanced sorting (for a sample see original pull request).
1.1
- Remove dependency to ezEngine.
- IncludeViewer visualizes now the output of the /showIncludes command instead of trying to run the preprocessor manually.
1.01
- Have includes with quotes or angle brackets first
1.0
- First release.
- Merged two old projects "Include Viewer" and "Include Formatter" to new "Include Toolbox" bundle