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)

To suppress removal of a single include, add a comment to its line containin_g_ $include-toolbox-preserve$

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.

To suppress removal of a single include, add a comment to its line containin_g_ $include-toolbox-preserve$

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.4.1

  • Fixed crash when opening context menu on some non-project files

• 2.4.0

  • Added support for Visual Studio 2019
  • Dropped support for Visual Studio 2015
  • Made some operations asynchronous under the hood, related bugfixing/checks driven by VS2019's static analysis warnings

• 2.3.0

  • Include Formatter contributions by Dakota Hawkins * has now a remove duplicates option which is enabled by default * Fixed not adding newlines before the last line of a batch
  • Fixed TrialAndErrorRemoval stopping when encountering an unsupported document, changed operation timeout to a couple of minutes (PR by bytefactory73)
  • Fixed IWYU failing for long command line argument (PR by codingdave)
  • Trying now to query NMake settings for include paths if there is no VCCLCompilerTool present (happens if vcxproj is not a standard C++ project)

• 2.2.0

  • IWYU Integration/Trial and Error Include Removal
    • Introduced comment-tag to avoid removing include (thx to ergins23 for suggesting)
  • IWYU Integration
    • Passes now arch parameter for x64 projects on (thx to Fei for reporting)
    • Added option for custom parameters (thx to Fei for suggesting)

• 2.1.5

  • Fixed random timeouts in Trial and Error Include Removal
  • Updated internal library references & used VS Extension toolkit

• 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

  • Include-what-you-use (iwyu):
    • Iwyu.exe is no longer part of the package. Instead there is a automatic download and update from a different repository on first use.
    • iwyu.exe path can be configured by user
    • In case of automatic download, mapping files in iwyu path will be added to configuration
    • Fixed hardcoded defines being passed to iwyu
    • MSVC version is correctly passed to iwyu
    • Fixed issues with applying removal/addition of declarations
    • Changes can now optionally run through IncludeFormatter (on by default)
  • Formatter:
    • Include parser recognizes all whitespace-only lines as empty
    • No longer resolves includes via file local path if "Ignore File Relative" option is active
    • Formatting applied to includes inside preprocessor conditionals again. (Still ignored for include removal though)
    • Fixed incorrect include parse behavior for preceding /* */ comment.
    • Fixed potential crashes in internal path resolve
  • Other:
    • New Icons!
    • Safer against crashes in commands
    • Codebase has now a handful of unit tests

• 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