Wil

Windows Implementation Libraries (WIL)

The Windows Implementation Libraries (WIL) is a header-merely C++ library created to make life easier for developers on Windows through readable type-prophylactic C++ interfaces for mutual 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 relieve you the work of manually specifying buffer sizes, calling a role twice to get the needed buffer size and so classify and pass the right-size buffer, casting or converting betwixt types, and so on.
• include/wil/registry.h: Registry watchers that can call a lambda role or callback yous provide whenever a certain tree within the Windows registry changes.
• include/wil/result.h (documentation): Preprocessor macros to assist you check for errors from Windows API functions, in many of the myriad means those errors are reported, and surface them as error codes or C++ exceptions in your lawmaking.
• include/wil/Tracelogging.h: This file contains the convenience macros that enable developers define and log telemetry. These macros apply TraceLogging API to log data. This data can be viewed in tools such every bit Windows Performance Analyzer.

WIL tin can be used by C++ code that uses C++ exceptions as well equally code that uses returned fault codes to report errors. All of WIL can be used from user-space Windows code, and some (such every bit the RAII resource wrappers) can even be used in kernel manner.

Documentation

This project is documented in its GitHub wiki. Experience free to contribute to information technology!

Consuming WIL

WIL follows the "live at head" philosophy, then yous should feel costless to swallow WIL directly from the GitHub repo nevertheless you lot delight: equally 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 exist updated periodically, likely to average around once or twice per month.

Consuming WIL via NuGet

WIL is available on nuget.org under the name Microsoft.Windows.ImplementationLibrary. This package includes the header files under the include directory too as a .targets file.

Consuming WIL via vcpkg

WIL is also bachelor using vcpkg under the name wil. Instructions for installing packages tin exist institute in the vcpkg GitHub docs. In full general, one time vcpkg is set up upward on the organisation, y'all tin can run:

C:\vcpkg>              vcpkg install wil:x86-windows C:\vcpkg>              vcpkg install wil:x64-windows

Note that even though WIL is a header-simply library, you still need to install the package for all architectures/platforms yous wish to utilize information technology 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.

Building/Testing

To get started testing WIL, first make certain that you have a contempo version of Visual Studio and the virtually contempo Windows SDK installed. If you are doing whatever not-trivial work, likewise exist sure to have a recent version of Clang installed. One time everything is installed, open a VS native command window (e.g. "x64 Native Tools Command Prompt for VS 2019"). If yous are familiar with CMake you lot tin go started edifice normally. Otherwise, or if you adopt to skip all of the boilerplate, you tin can use one of the scripts in the scripts directory:

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

You can execute init.cmd --assist for a summary of bachelor options. The scripts use a common directory pattern of build/$(compiler)$(arch)$(type) for the build output root. Eastward.yard. build/clang64debug when using Clang as the compiler, x64 as the architecture, and Debug equally the build type. It is this directory where yous volition desire to build from. For case, if you initialized using the command to a higher place, you tin can build the tests like so:

C:\wil\build\clang64debug>              ninja

Or, if y'all desire to merely build a single test (e.g. for improved compile times):

C:\wil\build\clang64debug>              ninja witest.noexcept

If you initialized using MSBuild equally the generator, there will be a .sln file in the root of the build directory. You can either open the solution in Visual Studio or invoke MSBuild directly to build.

The output is a number of exam executables. If you used the initialization script(s) mentioned above, or if y'all followed the aforementioned directory naming convention of those scripts, y'all can utilise the runtests.cmd script, which will execute whatever test executables that have been built, erroring out - and preserving the get out code - if whatever test fails. Annotation that MSBuild will modify the output directory names, then this script is just compatible with using Ninja as the generator. If you are at the tail end of of a change, you can execute the post-obit to become 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 volition but test for the compages that corresponds to the control window yous opened. You will want to repeat this procedure for the other architecture (e.g. by using the "x86 Native Tools Command Prompt for VS 2019")

Contributing

This project welcomes contributions and suggestions. Most contributions require you lot to agree to a Contributor License Agreement (CLA) declaring that y'all have the correct to, and really practice, grant united states of america the rights to utilise your contribution. For details, visit https://cla.microsoft.com.

When y'all submit a pull request, a CLA-bot will automatically determine whether you demand to provide a CLA and decorate the PR appropriately (east.1000., characterization, annotate). Simply follow the instructions provided past the bot. You will only need to practice this once across all repos using our CLA.

This projection has adopted the Microsoft Open Source Code of Conduct. For more information see the Lawmaking of Carry FAQ or contact opencode@microsoft.com with whatever boosted questions or comments.

siegeldeftern.blogspot.com

Source: https://github.com/Microsoft/wil

Share this post