Repository files navigation

The Windows Implementation Libraries (WIL) is a header-only C++ library created to make life easierfor 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 WindowsAPI HANDLEs, HWNDs, and other resources and resource handles withRAII semantics.
• include/wil/win32_helpers.h(documentation): Wrappers for API functionsthat save you the work of manually specifying buffer sizes, calling a function twiceto 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 (documentation): Type-safe functions to read from, write to,and watch the registry. Also, registry watchers that can call a lambda function or a callback functionyou provide whenever a certain tree within the Windows registry changes.
• include/wil/network.h: Supports Winsock and network APIsby providing a header-include list which addresses the inter-header include dependendies;provides RAII objects for WSAStartup refcounts as well as the various addrinfo* typesreturned from the family of getaddrinfo* functions; provides a type-safe class for managingthe entire family of sockaddr-related structures.
• 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 aserror codes or C++ exceptions in your code.
• include/wil/Tracelogging.h: This file contains the convenience macrosthat enable developers define and log telemetry. These macros useTraceLogging APIto 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 returnederror 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 inits 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 nameMicrosoft.Windows.ImplementationLibrary. This package includes the header files under theinclude directory as well as a.targets file.

WIL is also available usingvcpkg under the namewil. Instructions for installing packages can be found in thevcpkg GitHub docs. In general, once vcpkg is set up on the system, you can run:

C:\vcpkg> vcpkg install wil:x86-windowsC:\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. Executevcpkg help triplet for a list of available options.

To get started contributing to WIL, first make sure that you have:

• The latest version ofVisual Studio or Build Tools for Visual Studio with the latest MSVC C++build tools and Address Sanitizer components included. In Visual Studio Installer's Import Configuration tool, pick.vsconfigto the necessary workloads installed.
• The most recentWindows SDK
• Nuget downloaded and added toPATH - seeInstall NuGet client tools
• vcpkg available on your system. Follow theirgetting started guide to get set up. Make sure theVCKPKG_ROOT environment variable is set, and the path tovcpkg.exe is in your%PATH%.
• A recent version ofClang

You can install these with WinGet in a console command line:

winget install Microsoft.VisualStudio.2022.Communitywinget install Microsoft.WindowsSDK.10.0.22621winget install Microsoft.NuGet-ewinget install Kitware.CMake-ewinget install Ninja-build.Ninja-e# Select "Add LLVM to the system path for all users"winget install-i llvm.llvm

By default,init.cmd andcmake attempt to find vcpkg's cmake integration toolchain file on their own, bylooking in theVCPKG_ROOT environment variable. After bootstrapping, you can usesetx to have this variableacross shell sessions. Make sure the directory containingvcpkg.exe is in yourPATH.

IfVCPKG_ROOT is not set you can pass its location to CMake or theinit.cmd script with one of these:

• cmake [...] --toolchain [path to vcpkg]/scripts/buildsystems/vcpkg.cmake
• scripts\init.cmd [...] --vcpkg <path to vcpkg>

Note that if you use theinit.cmd script (mentioned below), this path can be specified or auto-detected if you:

1. Have theVCPKG_ROOT environment variable set to the root of your vcpkg clone.You can use thesetx command to have this variable persist across shell sessions,
2. Have the path to the root of your vcpkg clone added to yourPATH (i.e. the path tovcpkg.exe), or
3. If your vcpkg clone is located at the root of the same drive as your WIL clone (e.g.C:\vcpkg if your WIL clone is on theC: drive)

Visual Studio 2022 hasfully integrated CMake support. Openingthis directory in Visual Studio 2022 uses the default "clang Debug" configurations. Other configurations for "clang Release," "msvc Debug,"and "msvc Release" are available in the Configuration drop-down.

Use "Build > Build All" to compile all targets.

Microsoft'sCMake Tools for Visual Studio Code make workingin VSCode easy.

1. Start a "Native Tools Command Prompt" (see below)
2. Launch VS Code from the prompt, giving it the path to this repo (likecode c:\wil)
3. Use "CMake: Select Configure Preset" to pickclang, then "CMake: Select Build Preset" to pickclang Debug, then "CMake: Select Build Target" and pickall
4. Use "CMake: Build" to compile all targets

Once everything is installed (you'll need to restart Terminal if you updatedPATH and don't havethis 2023 fix),open a VS native command window (e.g.x64 Native Tools Command Prompt for VS 2022 [notDeveloper Command Prompt for VS2022]).

You can use aCMake preset to configure the environment:

# Configure for clang compiler, then build clang-debugC:\wil> cmake--preset"clang"C:\wil> cmake--build--preset"clang-debug"

You can also usescripts/init.cmd to pick the configuration:

C:\wil> scripts\init.cmd -c clang -g ninja -b debug

This script supports using msbuild as the generator/build-tool (pass-g msbuild) and the otherCMAKE_BUILD_TYPE values(pass-b minsizerel). You can executeinit.cmd --help for a summary of available options.

Thescripts/init_all.cmd script will run theinit.cmd script for all combinations of Clang/MSVC and Debug/RelWithDebInfo.

Note: For either script, projects will only be generated for the architecture of the current VS command window.

In Visual Studio 2022, select a startup item (e.g.witest.exe) and use "Debug > Start Debugging". Targets will berebuilt as needed. Use "Build > Rebuild All" to rebuild all tests. Use the Visual Studio Test Explorer to run thetests.

In VS Code, use "CMake: Set Launch/Debug Target" and select a target (e.g.witest.exe). Use "CMake: Debug" (default keybindShift-F5)to run the selected testin VS Code's debugger environment..Switch toVS Code's "testing" tab, and click the "Run Tests"option.

For command-line CMake (configured withcmake --preset ...) build use, some examples:

# Build for MSVC release, all targetsC:\wil> cmake--build--preset"msvc-release"# Build only one test (e.g. for improved compile times)C:\wil> cmake--build--preset"msvc-release"--target"witest.noexcept"# Clean outputs, then build one targetC:\wil> cmake--build--preset"msvc-release"--clean-first--target"witest"# Run testsC:\wil> ctest--preset"msvc-release"

For command-line Ninja (configured withinit.cmd -c clang -b debug) build use, some examples:

# Build all testsC:\wil> ninja-C build\clang64debug# Build only one testC:\wil> ninja-C build\clang64debug witest# Clean outputs, then build one targetC:\wil> ninja-C build\clang64debug-j0clean witest.app# Run the tests (PowerShell)C:\wil>Get-ChildItem-Recurse-File build\clang64debug\witest*.exe|%{Write-Host$_ ;&$_ }# Run the tests (cmd)C:\wil>for/F%fIN ('dir /s /b build\clang\tests\witest*.exe')do%f

The output is a number of test executables. If you used the initialization script(s) mentioned above, or if you followedthe same directory naming convention of those scripts, you can use theruntests.cmd script,which will execute any test executables that have been built, erroring out - and preserving the exit code - if any testfails. Note that MSBuild will modify the output directory names, so this script is only compatible with using Ninja as thegenerator.

Note: Thewitest.app test is significantly slower than the other tests. You can use Test Explorer or the Testingtab to hide it while doing quick validation.

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.cmdC:\wil> scripts\build_all.cmdC:\wil> scripts\runtests.cmd

Note that this will only test for the architecture that corresponds to the command window you opened. You will want torepeat this process for the other architecture (e.g. by using thex86 Native Tools Command Prompt for VS 2022 in addition tox64).

This project has adoptedclang-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 ofclang-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 runclang-format on your changes.There is a CI check in place that will fail the build for your PR if you have not runclang-format.There are a few different ways to format your code:

Important! Git integration withclang-format is only available through the LLVM distribution.You can install LLVM through theirGibHub releases page, viawinget install llvm.llvm, or through the package manager of your choice.

Important! The use ofgit clang-format additionally requires Python to be installed and available on yourPATH.

The simplest way to format just your changes is to useclang-format'sgit 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 rungit 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 ofclang-format is configured to run with this command.You can pass--binary <path> to specify the path toclang-format.exe you would like the command to use.

If you'd like to format changes at the end of development, you can rungit clang-format against a specific commit/label.The simplest is to run againstupstream/master ororigin/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 theformat-changes.cmd script we provide, which will use the version ofclang-format that ships with Visual Studio:

C:\wil> git fetch upstreamC:\wil> git merge upstream/masterC:\wil> scripts\format-changes.cmd upstream/master

Important! The path toclang-format.exe is not added toPATH automatically, even when using a Visual Studio command window.The LLVM installer has the option to add itself to the system or userPATH if you'd like.If you would like the path to the version ofclang-format that ships with Visual Studio added to your path, you will need to do so manually.Otherwise, therun-clang-format.cmd script mentioned below (or, equivalently, building theformat target) will manually invoke theclang-format.exe under your Visual Studio install path.

An alternative, and generally easier option, is to runclang-format either on all source files or on all source files you've modified.Note, however, that depending on howclang-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 ofclang-format that you wish to use when formatting code, however this is not always the case.Therun-clang-format.cmd script we provide will ensure that the version ofclang-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, namedformat:

C:\wil\build\clang64debug> ninjaformat

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 aContributor License Agreement (CLA) declaring that you have the right to, and actually do, grant usthe rights to use your contribution. For details, visithttps://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to providea CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructionsprovided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted theMicrosoft Open Source Code of Conduct.For more information see theCode of Conduct FAQ orcontactopencode@microsoft.com with any additional questions or comments.