The Windows Implementation Libraries (WIL) is a header-only C++ library created to make life easier for developers on Windows through readable type-safe C++ interfaces for common Windows coding patterns.
Some things that WIL includes to whet your appetite:
include/wil/resource.h
(documentation): Smart pointers and auto-releasing resource wrappers to let you manage Windows API HANDLEs, HWNDs, and other resources and resource handles with RAII semantics.include/wil/win32_helpers.h
(documentation): Wrappers for API functions that save you the work of manually specifying buffer sizes, calling a function twice to get the needed buffer size and then allocate and pass the right-size buffer, casting or converting between types, and so on.include/wil/registry.h
: Type-safe functions to read from, write to, and watch the registry. Also, registry watchers that can call a lambda function or a callback function you provide whenever a certain tree within the Windows registry changes.include/wil/result.h
(documentation): Preprocessor macros to help you check for errors from Windows API functions, in many of the myriad ways those errors are reported, and surface them as error codes or C++ exceptions in your code.include/wil/Tracelogging.h
: This file contains the convenience macros that enable developers define and log telemetry. These macros useTraceLogging API
to log data. This data can be viewed in tools such asWindows Performance Analyzer
.
WIL can be used by C++ code that uses C++ exceptions as well as code that uses returned error codes to report errors. All of WIL can be used from user-space Windows code, and some (such as the RAII resource wrappers) can even be used in kernel mode.
This project is documented in its GitHub wiki. Feel free to contribute to it!
WIL follows the "live at head" philosophy, so you should feel free to consume WIL directly from the GitHub repo however you please: as a GIT submodule, symbolic link, download and copy files, etc. and update to the latest version at your own cadence. Alternatively, WIL is available using a few package managers, mentioned below. These packages will be updated periodically, likely to average around once or twice per month.
WIL is available on nuget.org under the name Microsoft.Windows.ImplementationLibrary. This package includes the header files under the include directory as well as a .targets file.
WIL is also available using vcpkg under the name wil. Instructions for installing packages can be found in the vcpkg GitHub docs. In general, once vcpkg is set up on the system, you can run:
C:\vcpkg> vcpkg install wil:x86-windows
C:\vcpkg> vcpkg install wil:x64-windows
Note that even though WIL is a header-only library, you still need to install the package for all architectures/platforms you wish to use it with. Otherwise, WIL won't be added to the include path for the missing architectures/platforms. Execute vcpkg help triplet
for a list of available options.
To get started contributing to WIL, first make sure that you have:
- A recent version of Visual Studio
- The most recent Windows SDK
- Nuget downloaded and added to
PATH
- (
winget install nuget
; see Install NuGet client tools)
- (
If you are doing any non-trivial work, also be sure to have:
- A recent version of Clang
- (
winget install -i llvm.llvm
and selectAdd LLVM to the system path for all users
)
- (
Once everything is installed (you'll need to restart Terminal if you updated PATH
and don't have this 2023 fix), open a VS native command window (e.g. x64 Native Tools Command Prompt for VS 2022
[not Developer Command Prompt for VS2022
]).
- If you are familiar with CMake you can get started building normally.
- Otherwise, or if you prefer to skip all of the boilerplate, you can use one of the scripts in the scripts directory, like
scripts\init.cmd [optional arguments]
- For example:
C:\wil> scripts\init.cmd -c clang -g ninja -b debug
- For example:
To set up IDEs with IntelliSense, see below.
You can execute init.cmd --help
for a summary of available options.
To generate a Visual Studio solution with IntelliSense:
C:\wil> scripts\init.cmd -c msvc -g msbuild
That will create a .sln
file in the correspondingbuild/
subdirectory. You can also invoke MSBuild directly to build.
You can also get decent IntelliSense just by opening the repo directory in Visual Studio; VS should auto-detect CMake. You'll have to compile and run tests in a terminal window, though.
The scripts use a common directory pattern of build/$(compiler)$(arch)$(type)
for the build output root. E.g. build/clang64debug
when using Clang as the compiler, x64 as the architecture, and Debug as the build type. It is this directory where you will want to build from.
For example, if you initialized using the command above (scripts\init.cmd -c clang -g ninja -b debug
), you can build the tests like so:
C:\wil\build\clang64debug> ninja
Or, if you want to only build a single test (e.g. for improved compile times):
C:\wil\build\clang64debug> ninja witest.noexcept
The output is a number of test executables. If you used the initialization script(s) mentioned above, or if you followed the same directory naming convention of those scripts, you can use the runtests.cmd script, which will execute any test executables that have been built, erroring out - and preserving the exit code - if any test fails. Note that MSBuild will modify the output directory names, so this script is only compatible with using Ninja as the generator.
If you are at the tail end of of a change, you can execute the following to get a wide range of coverage:
C:\wil> scripts\init_all.cmd
C:\wil> scripts\build_all.cmd
C:\wil> scripts\runtests.cmd
Note that this will only test for the architecture that corresponds to the command window you opened. You will want to
repeat this process for the other architecture (e.g. by using the x86 Native Tools Command Prompt for VS 2022
in addition to x64
).
This project has adopted clang-format
as the tool for formatting our code.
Please note that the .clang-format
at the root of the repo is a copy from the internal Windows repo with few additions.
In general, please do not modify it.
If you find that a macro is causing bad formatting of code, you can add that macro to one of the corresponding arrays in the .clang-format
file (e.g. AttributeMacros
, etc.), format the code, and submit a PR.
NOTE: Different versions of
clang-format
may format the same code differently. In an attempt to maintain consistency between changes, we've standardized on using the version ofclang-format
that ships with the latest version of Visual Studio. If you have LLVM installed and added to yourPATH
, the version ofclang-format
that gets picked up by default may not be the one we expect. If you leverage the formatting scripts we have provided in thescripts
directory, these should automatically pick up the proper version provided you are using a Visual Studio command window.
Before submitting a PR to the WIL repo we ask that you first run clang-format
on your changes.
There is a CI check in place that will fail the build for your PR if you have not run clang-format
.
There are a few different ways to format your code:
The simplest way to format just your changes is to use clang-format
's git
integration.
You have the option to do this continuously as you make changes, or at the very end when you're ready to submit a PR.
To format code continuously as you make changes, you run git clang-format
after staging your changes.
For example:
C:\wil> git add *
C:\wil> git clang-format --style file
At this point, the formatted changes will be unstaged.
You can review them, stage them, and then commit.
Please note that this will use whichever version of clang-format
is configured to run with this command.
You can pass --binary <path>
to specify the path to clang-format.exe
you would like the command to use.
If you'd like to format changes at the end of developement, you can run git clang-format
against a specific commit/label.
The simplest is to run against upstream/master
or origin/master
depending on whether or not you are developing in a fork.
Please note that you likely want to sync/merge with the master branch prior to doing this step.
You can leverage the format-changes.cmd
script we provide, which will use the version of clang-format
that ships with Visual Studio:
C:\wil> git fetch upstream
C:\wil> git merge upstream/master
C:\wil> scripts\format-changes.cmd upstream/master
An alternative, and generally easier option, is to run clang-format
either on all source files or on all source files you've modified.
Note, however, that depending on how clang-format
is invoked, the version used may not be the one that ships with Visual Studio.
Some tools such as Visual Studio Code allow you to specify the path to the version of clang-format
that you wish to use when formatting code, however this is not always the case.
The run-clang-format.cmd
script we provide will ensure that the version of clang-format
used is the version that shipped with your Visual Studio install:
C:\wil> scripts\run-clang-format.cmd
Additionally, we've added a build target that will invoke this script, named format
:
C:\wil\build\clang64debug> ninja format
Please note that this all assumes that your Visual Studio installation is up to date. If it's out of date, code unrelated to your changes may get formatted unexpectedly. If that's the case, you may need to manually revert some modifications that are unrelated to your changes.
NOTE: Occasionally, Visual Studio will update without us knowing and the version installed for you may be newer than the version installed the last time we ran the format all script. If that's the case, please let us know so that we can re-format the code.
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.