{"id":13681084,"url":"https://github.com/microsoft/wil","last_synced_at":"2025-05-14T23:01:46.602Z","repository":{"id":39033204,"uuid":"156614409","full_name":"microsoft/wil","owner":"microsoft","description":"Windows Implementation Library","archived":false,"fork":false,"pushed_at":"2025-05-05T21:24:01.000Z","size":2301,"stargazers_count":2691,"open_issues_count":114,"forks_count":250,"subscribers_count":68,"default_branch":"master","last_synced_at":"2025-05-07T22:02:05.882Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/microsoft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-11-07T22:05:06.000Z","updated_at":"2025-05-07T07:16:28.000Z","dependencies_parsed_at":"2023-11-29T19:43:33.202Z","dependency_job_id":"ff033a16-9cc8-4812-9796-58d98da01231","html_url":"https://github.com/microsoft/wil","commit_stats":{"total_commits":256,"total_committers":74,"mean_commits":"3.4594594594594597","dds":0.765625,"last_synced_commit":"27d66a24b55a2f7baf91c06c196ba1a2d256c2db"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fwil","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fwil/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fwil/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2Fwil/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/microsoft","download_url":"https://codeload.github.com/microsoft/wil/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254243353,"owners_count":22038044,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T13:01:25.992Z","updated_at":"2025-05-14T23:01:46.532Z","avatar_url":"https://github.com/microsoft.png","language":"C++","readme":"# Windows Implementation Libraries (WIL)\n\n[![Build Status](https://dev.azure.com/msft-wil/Windows%20Implementation%20Library/_apis/build/status/Microsoft.wil?branchName=master)](https://dev.azure.com/msft-wil/Windows%20Implementation%20Library/_build/latest?definitionId=1\u0026branchName=master)\n\nThe Windows Implementation Libraries (WIL) is a header-only C++ library created to make life easier\nfor developers on Windows through readable type-safe C++ interfaces for common Windows coding patterns.\n\nSome things that WIL includes to whet your appetite:\n\n- [`include/wil/resource.h`](include/wil/resource.h)\n  ([documentation](https://github.com/Microsoft/wil/wiki/RAII-resource-wrappers)):\n  Smart pointers and auto-releasing resource wrappers to let you manage Windows\n  API HANDLEs, HWNDs, and other resources and resource handles with\n  [RAII](https://en.cppreference.com/w/cpp/language/raii) semantics.\n- [`include/wil/win32_helpers.h`](include/wil/win32_helpers.h)\n  ([documentation](https://github.com/microsoft/wil/wiki/Win32-helpers)): Wrappers for API functions\n  that save you the work of manually specifying buffer sizes, calling a function twice\n  to get the needed buffer size and then allocate and pass the right-size buffer,\n  casting or converting between types, and so on.\n- [`include/wil/registry.h`](include/wil/registry.h) ([documentation](https://github.com/microsoft/wil/wiki/Registry-Helpers)): Type-safe functions to read from, write to,\n  and watch the registry. Also, registry watchers that can call a lambda function or a callback function\n  you provide whenever a certain tree within the Windows registry changes.\n- [`include/wil/result.h`](include/wil/result.h)\n  ([documentation](https://github.com/Microsoft/wil/wiki/Error-handling-helpers)):\n  Preprocessor macros to help you check for errors from Windows API functions,\n  in many of the myriad ways those errors are reported, and surface them as\n  error codes or C++ exceptions in your code.\n- [`include/wil/Tracelogging.h`](include/wil/Tracelogging.h): This file contains the convenience macros\n  that enable developers define and log telemetry. These macros use\n  [`TraceLogging API`](https://docs.microsoft.com/en-us/windows/win32/tracelogging/trace-logging-portal)\n  to log data. This data can be viewed in tools such as\n  [`Windows Performance Analyzer`](https://docs.microsoft.com/en-us/windows-hardware/test/wpt/windows-performance-analyzer).\n\nWIL can be used by C++ code that uses C++ exceptions as well as code that uses returned\nerror codes to report errors. All of WIL can be used from user-space Windows code,\nand some (such as the RAII resource wrappers) can even be used in kernel mode.\n\n# Documentation\n\nThis project is documented in [its GitHub wiki](https://github.com/Microsoft/wil/wiki). Feel free to contribute to it!\n\n# Consuming WIL\nWIL 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.\n\n## Consuming WIL via NuGet\nWIL is available on nuget.org under the name [Microsoft.Windows.ImplementationLibrary](https://www.nuget.org/packages/Microsoft.Windows.ImplementationLibrary/). This package includes the header files under the [include](include) directory as well as a [.targets](packaging/nuget/Microsoft.Windows.ImplementationLibrary.targets) file.\n\n## Consuming WIL via vcpkg\nWIL is also available using [vcpkg](https://github.com/microsoft/vcpkg) under the name [wil](https://github.com/microsoft/vcpkg/blob/master/ports/wil/portfile.cmake). Instructions for installing packages can be found in the [vcpkg GitHub docs](https://github.com/microsoft/vcpkg/blob/master/docs/examples/installing-and-using-packages.md). In general, once vcpkg is set up on the system, you can run:\n```cmd\nC:\\vcpkg\u003e vcpkg install wil:x86-windows\nC:\\vcpkg\u003e vcpkg install wil:x64-windows\n```\nNote 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.\n\n# Building/Testing\n\n## Prerequisites\n\nTo get started contributing to WIL, first make sure that you have:\n\n* The latest version of [Visual Studio](https://visualstudio.microsoft.com/downloads/) or Build Tools for Visual Studio with the latest MSVC C++ build tools and Address Sanitizer components included.\n* The most recent [Windows SDK](https://developer.microsoft.com/windows/downloads/windows-sdk)\n* [Nuget](https://www.nuget.org/downloads) downloaded and added to `PATH`\n  * (`winget install nuget`; see [Install NuGet client tools](https://learn.microsoft.com/nuget/install-nuget-client-tools))\n* [vcpkg](https://vcpkg.io) available on your system.\nFollow their [getting started](https://vcpkg.io/en/getting-started) guide to get set up.\nYou'll need to provide the path to vcpkg when initializing with CMake by passing `-DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]/scripts/buildsystems/vcpkg.cmake`.\nNote that if you use the `init.cmd` script (mentioned below), this path can be specified or auto-detected if you:\n  1. Manually specify the path to the root of your vcpkg clone via the `-p` or `--vcpkg` argument,\n  1. Have the `VCPKG_ROOT` environment variable set to the root of your vcpkg clone.\n  You can use the `setx` command to have this variable persist across shell sessions,\n  1. Have the path to the root of your vcpkg clone added to your `PATH` (i.e. the path to `vcpkg.exe`), or\n  1. 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 the `C:` drive)\n\nIf you are doing any non-trivial work, also be sure to have:\n\n* A recent version of [Clang](http://releases.llvm.org/download.html)\n  * (`winget install -i llvm.llvm` and select `Add LLVM to the system path for all users`)\n\n## Initial configuration\n\nOnce everything is installed (you'll need to restart Terminal if you updated `PATH` and don't have [this 2023 fix](https://github.com/microsoft/terminal/pull/14999)), open a VS native command window (e.g. `x64 Native Tools Command Prompt for VS 2022` \\[_not_ `Developer Command Prompt for VS2022`]).\n\n* If you are familiar with CMake you can get started building normally.\n* Otherwise, or if you prefer to skip all of the boilerplate, you can use the `init.cmd` script in the [scripts](scripts) directory.\nFor example:\n  ```cmd\n  C:\\wil\u003e scripts\\init.cmd -c clang -g ninja -b debug\n  ```\n  You can execute `init.cmd --help` for a summary of available options.\n  The `scripts/init_all.cmd` script will run the `init.cmd` script for all combinations of Clang/MSVC and Debug/RelWithDebInfo.\n  Note that for either script, projects will only be generated for the architecture of the current VS command window.\n\nTo set up Visual Studio with IntelliSense, see below.\nIf you used the `init.cmd` script, the corresponding build output directory should contain a `compile_commands.json` file that describes the commands used to compile each input file.\nSome editors such as Visual Studio Code can be configured to use this file to provide better auto-complete, tooltips, etc.\nVisual Studio Code, in particular should auto-detect the presence of this file and prompt you to use it for better IntelliSense.\nIf you are not auto-prompted, this can be manually configured in the workspace's C/C++ properties under the property name `compileCommands`.\n\n### Visual Studio setup\n\nTo generate a Visual Studio solution with IntelliSense:\n```cmd\nC:\\wil\u003e scripts\\init.cmd -c msvc -g msbuild\n```\n\nThat will create a `.sln` file in the corresponding `build/` subdirectory (e.g. `build/msvc64debug`).\nYou can open this solution in Visual Studio to develop and build, or you can invoke MSBuild directly.\n\n\u003e **Important!** When using MSVC as the generator, the build type (`-b` argument to `init.cmd`) is mostly ignored by Visual Studio (since you can change the build type in the IDE), however this selection may still have an impact on project generation due to logic in the CMake files.\n\nYou 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.\n\n## Inner loop\n\nThe 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.\n\nFor example, if you initialized using the command above (`scripts\\init.cmd -c clang -g ninja -b debug`), you can build the tests like so:\n```cmd\nC:\\wil\\build\\clang64debug\u003e ninja\n```\nOr, if you want to only build a single test (e.g. for improved compile times):\n```cmd\nC:\\wil\\build\\clang64debug\u003e ninja witest.noexcept\n```\n\nThe output is a number of test executables. If you used the initialization script(s) mentioned above, or if you followed\nthe same directory naming convention of those scripts, you can use the [runtests.cmd](scripts/runtests.cmd) script,\nwhich will execute any test executables that have been built, erroring out - and preserving the exit code - if any test\nfails. Note that MSBuild will modify the output directory names, so this script is only compatible with using Ninja as the\ngenerator.\n\n## Build everything\n\nIf you are at the tail end of of a change, you can execute the following to get a wide range of coverage:\n```cmd\nC:\\wil\u003e scripts\\init_all.cmd\nC:\\wil\u003e scripts\\build_all.cmd\nC:\\wil\u003e scripts\\runtests.cmd\n```\nNote that this will only test for the architecture that corresponds to the command window you opened. You will want to\nrepeat this process for the other architecture (e.g. by using the `x86 Native Tools Command Prompt for VS 2022` in addition to `x64`).\n\n## Formatting\n\nThis project has adopted `clang-format` as the tool for formatting our code.\nPlease note that the `.clang-format` at the root of the repo is a copy from the internal Windows repo with few additions.\nIn general, please do not modify it.\nIf 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.\n\n\u003e _NOTE: Different versions of `clang-format` may format the same code differently.\nIn an attempt to maintain consistency between changes, we've standardized on using the version of `clang-format` that ships with the latest version of Visual Studio.\nIf you have LLVM installed and added to your `PATH`, the version of `clang-format` that gets picked up by default may not be the one we expect.\nIf you leverage the formatting scripts we have provided in the `scripts` directory, these should automatically pick up the proper version provided you are using a Visual Studio command window._\n\nBefore submitting a PR to the WIL repo we ask that you first run `clang-format` on your changes.\nThere is a CI check in place that will fail the build for your PR if you have not run `clang-format`.\nThere are a few different ways to format your code:\n\n### 1. Formatting with `git clang-format`\n\n\u003e **Important!** Git integration with `clang-format` is only available through the LLVM distribution.\nYou can install LLVM through their [GibHub releases page](https://github.com/llvm/llvm-project/releases), via `winget install llvm.llvm`, or through the package manager of your choice.\n\n\u003e **Important!** The use of `git clang-format` additionally requires Python to be installed and available on your `PATH`.\n\nThe simplest way to format just your changes is to use `clang-format`'s `git` integration.\nYou have the option to do this continuously as you make changes, or at the very end when you're ready to submit a PR.\nTo format code continuously as you make changes, you run `git clang-format` after staging your changes.\nFor example:\n```cmd\nC:\\wil\u003e git add *\nC:\\wil\u003e git clang-format --style file\n```\nAt this point, the formatted changes will be unstaged.\nYou can review them, stage them, and then commit.\nPlease note that this will use whichever version of `clang-format` is configured to run with this command.\nYou can pass `--binary \u003cpath\u003e` to specify the path to `clang-format.exe` you would like the command to use.\n\nIf you'd like to format changes at the end of development, you can run `git clang-format` against a specific commit/label.\nThe simplest is to run against `upstream/master` or `origin/master` depending on whether or not you are developing in a fork.\nPlease note that you likely want to sync/merge with the master branch prior to doing this step.\nYou can leverage the `format-changes.cmd` script we provide, which will use the version of `clang-format` that ships with Visual Studio:\n```cmd\nC:\\wil\u003e git fetch upstream\nC:\\wil\u003e git merge upstream/master\nC:\\wil\u003e scripts\\format-changes.cmd upstream/master\n```\n\n### 2. Formatting with `clang-format`\n\n\u003e **Important!** The path to `clang-format.exe` is not added to `PATH` automatically, even when using a Visual Studio command window.\nThe LLVM installer has the option to add itself to the system or user `PATH` if you'd like.\nIf you would like the path to the version of `clang-format` that ships with Visual Studio added to your path, you will need to do so manually.\nOtherwise, the `run-clang-format.cmd` script mentioned below (or, equivalently, building the `format` target) will manually invoke the `clang-format.exe` under your Visual Studio install path.\n\nAn alternative, and generally easier option, is to run `clang-format` either on all source files or on all source files you've modified.\nNote, however, that depending on how `clang-format` is invoked, the version used may not be the one that ships with Visual Studio.\nSome 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.\nThe `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:\n```cmd\nC:\\wil\u003e scripts\\run-clang-format.cmd\n```\nAdditionally, we've added a build target that will invoke this script, named `format`:\n```cmd\nC:\\wil\\build\\clang64debug\u003e ninja format\n```\nPlease note that this all assumes that your Visual Studio installation is up to date.\nIf it's out of date, code unrelated to your changes may get formatted unexpectedly.\nIf that's the case, you may need to manually revert some modifications that are unrelated to your changes.\n\n\u003e _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._\n\n# Contributing\n\nThis project welcomes contributions and suggestions.  Most contributions require you to agree to a\nContributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us\nthe rights to use your contribution. For details, visit https://cla.microsoft.com.\n\nWhen you submit a pull request, a CLA-bot will automatically determine whether you need to provide\na CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions\nprovided by the bot. You will only need to do this once across all repos using our CLA.\n\nThis project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).\nFor more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or\ncontact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.\n","funding_links":[],"categories":["C++","Standard/Support Libraries"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrosoft%2Fwil","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicrosoft%2Fwil","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrosoft%2Fwil/lists"}