{"id":13598553,"url":"https://github.com/microsoft/STL","last_synced_at":"2025-04-10T09:31:36.413Z","repository":{"id":37269994,"uuid":"204593825","full_name":"microsoft/STL","owner":"microsoft","description":"MSVC's implementation of the C++ Standard Library.","archived":false,"fork":false,"pushed_at":"2025-04-08T07:04:37.000Z","size":31776,"stargazers_count":10508,"open_issues_count":545,"forks_count":1540,"subscribers_count":250,"default_branch":"main","last_synced_at":"2025-04-08T10:12:21.025Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/microsoft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-08-27T01:31:18.000Z","updated_at":"2025-04-08T09:05:11.000Z","dependencies_parsed_at":"2024-02-12T08:57:48.508Z","dependency_job_id":"f4a049cb-bc3c-4602-8779-a6eb09ca79a5","html_url":"https://github.com/microsoft/STL","commit_stats":{"total_commits":2276,"total_committers":230,"mean_commits":9.895652173913044,"dds":0.7921792618629174,"last_synced_commit":"90820002693fe6eaaec2e55884472c654186207e"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2FSTL","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2FSTL/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2FSTL/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/microsoft%2FSTL/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/microsoft","download_url":"https://codeload.github.com/microsoft/STL/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248191728,"owners_count":21062560,"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-01T17:00:53.593Z","updated_at":"2025-04-10T09:31:31.381Z","avatar_url":"https://github.com/microsoft.png","language":"C++","readme":"# Microsoft's C++ Standard Library\r\n\r\nThis is the official repository for Microsoft's implementation of the C++ Standard Library (also known as the STL),\r\nwhich ships as part of the MSVC toolset and the Visual Studio IDE.\r\n\r\n* Our [Changelog][] tracks which updates to this repository appear in each VS release.\r\n* Our [Status Chart][] displays our overall progress over time.\r\n* Join our [Discord server][].\r\n* [![CI Status Badge][STL-CI-badge]][STL-CI-link] (STL-CI build status)\r\n* [![ASan CI Status Badge][STL-ASan-CI-badge]][STL-ASan-CI-link] (STL-ASan-CI build status)\r\n\r\n# What This Repo Is Useful For\r\n\r\nIf you're a programmer who just wants to use the STL, you **don't** need this repo. Simply install the Visual Studio IDE\r\nand select the \"Desktop development with C++\" workload.\r\n\r\nIf you want to participate in the STL's development, welcome! You can report issues, comment on pull requests, and learn\r\nabout what we're working on. You can also submit pull requests to fix bugs or add features: see [CONTRIBUTING.md][] for\r\nmore information.\r\n\r\nFinally, you can take our code and use it in other apps and libraries (according to the terms of our license, like\r\neverything else).\r\n\r\n# GitHub Migration Status\r\n\r\nWe're in the process of moving all of our work on the STL to GitHub. Current status:\r\n\r\n* Code: **Done.** Our source code is available under the Apache License v2.0 with LLVM Exception. (See\r\n[LICENSE.txt][] and [NOTICE.txt][] for more information.)\r\n\r\n* Build System: **In progress.** We're working on a CMake build system, which is currently capable of building one\r\nflavor of the STL (native desktop). We need to extend this to build all of the flavors required for the MSVC toolset\r\n(e.g. `/clr`, `/clr:pure`, OneCore, Spectre). Until that's done, we're keeping our legacy build system around in the\r\n`stl/msbuild` subdirectory. (We're keeping those files in this repo, even though they're unusable outside of Microsoft,\r\nbecause they need to be updated whenever source files are added/renamed/deleted. We'll delete the legacy machinery as\r\nsoon as possible.)\r\n\r\n* Tests: **In progress.** We rely on three test suites: std, tr1, and [libcxx][]. We've partially ported std and tr1,\r\nand fully ported libcxx to run under [lit][] using the various configurations/compilers we test internally.\r\n\r\n* Continuous Integration: **In progress.** We've set up Azure Pipelines to validate changes to the repository.\r\nCurrently, it builds the STL (native desktop for x86, x64, ARM, and ARM64). Also, it strictly verifies that all of our\r\nfiles have been formatted with [clang-format][] and follow our other whitespace conventions.\r\n\r\n* Contribution Guidelines: **Coming soon.** Working on the STL's code involves following many rules. We have codebase\r\nconventions, Standard requirements, Microsoft-specific requirements, binary compatibility (ABI) requirements, and more.\r\nWe're eager to begin accepting features and fixes from the community, but in addition to setting up a CI system, we need\r\nto write down all of the rules that are currently stored in our brains. (The ABI rules may be useful to other C++\r\nlibraries.)\r\n\r\n* Issues: **In progress.** We're going to use GitHub issues to track all of the things that we need to work on. This\r\nincludes C++20 features, [LWG issues][], conformance bugs, performance improvements, and other todos. There are\r\napproximately 200 active bugs in the STL's Microsoft-internal database; we need to manually replicate all of them to\r\nGitHub issues. Currently, the [cxx20 tag][] and [LWG tag][] are done; every remaining work item is tracked by a GitHub\r\nissue. The [bug tag][] and [enhancement tag][] are being populated.\r\n\r\n* Plans: **In progress.** We're writing up our [Roadmap][].\r\n\r\n# Goals\r\n\r\nWe're implementing the latest C++ Working Draft, currently [N4981][], which will eventually become the next C++\r\nInternational Standard. The terms Working Draft (WD) and Working Paper (WP) are interchangeable; we often\r\ninformally refer to these drafts as \"the Standard\" while being aware of the difference. (There are other relevant\r\nStandards; for example, supporting `/std:c++14` and `/std:c++17` involves understanding how the C++14 and C++17\r\nStandards differ from the Working Paper, and we often need to refer to the C Standard Library and ECMAScript regular\r\nexpression specifications.)\r\n\r\nOur primary goals are conformance, performance, usability, and compatibility.\r\n\r\n* Conformance: The Working Paper is a moving target; as features and LWG issue resolutions are added, we need to\r\nimplement them. That can involve a lot of work because the STL is required to behave in very specific ways and to\r\nhandle users doing very unusual things.\r\n\r\n* Performance: The STL needs to be extremely fast at runtime; speed is one of C++'s core strengths and most C++\r\nprograms use the STL extensively. As a result, we spend more time on optimization than most general-purpose libraries.\r\n(However, we're wary of changes that improve some scenarios at the expense of others, or changes that make code\r\nsignificantly more complicated and fragile. That is, there's a \"complexity budget\" that must be spent carefully.)\r\n\r\n* Usability: This includes parts of the programming experience like compiler throughput, diagnostic messages, and\r\ndebugging checks. For example, we've extensively marked the STL with `[[nodiscard]]` attributes because this helps\r\nprogrammers avoid bugs.\r\n\r\n* Compatibility: This includes binary compatibility and source compatibility. We're keeping VS 2022 binary-compatible\r\nwith VS 2015/2017/2019, which restricts what we can change in VS 2022 updates. (We've found that significant changes\r\nare possible even though other changes are impossible, which we'll be documenting in our Contribution Guidelines soon.)\r\nWhile there are a few exceptions to this rule (e.g. if a feature is added to the Working Paper, we implement it, and\r\nthen the feature is significantly changed before the International Standard is finalized, we reserve the right to break\r\nbinary compatibility because `/std:c++latest` offers an experimental preview of such features), binary compatibility\r\ngenerally overrides all other considerations, even conformance. Source compatibility refers to being able to\r\nsuccessfully recompile user code without changes. We consider source compatibility to be important, but not\r\nall-important; breaking source compatibility can be an acceptable cost if done for the right reasons in the right way\r\n(e.g. in a controlled manner with escape hatches).\r\n\r\n# Non-Goals\r\n\r\nThere are things that we aren't interested in doing with this project, for various reasons (most importantly, we need to\r\nfocus development effort on our goals). Some examples:\r\n\r\n* Non-goal: Porting to other platforms.\r\n\r\n* Non-goal: Adding non-Standard extensions.\r\n\r\n* Non-goal: Implementing Technical Specifications. (We're prioritizing features in the Working Paper. Occasionally, we\r\nmight implement some or all of a TS, often when we're working on the specification itself.)\r\n\r\nIf you're proposing a feature to WG21 (the C++ Standardization Committee), you're welcome (and encouraged!) to use our\r\ncode as a base for a proof-of-concept implementation. These non-goals simply mean that we're unable to consider pull\r\nrequests for a proposed feature until it has been voted into a Working Paper. After that happens, we'll be delighted to\r\nreview a production-ready pull request.\r\n\r\n# Reporting Issues\r\n\r\nYou can report STL bugs here, where they'll be directly reviewed by maintainers. You can also report STL bugs through\r\n[Developer Community][], or the VS IDE (Help \u003e Send Feedback \u003e Report a Problem...).\r\n\r\n**Please help us** efficiently process bug reports by following these rules:\r\n\r\n* Only STL bugs should be reported here. If it's a bug in the compiler, CRT, or IDE, please report it through Developer\r\nCommunity or Report A Problem. If it's a bug in the Windows SDK, please report it through the [Feedback Hub][hub] app.\r\nIf you aren't sure, try to reduce your test case and see if you can eliminate the STL's involvement while still\r\nreproducing the bug.\r\n\r\n* You should be reasonably confident that you're looking at an actual implementation bug, instead of undefined behavior\r\nor surprising-yet-Standard behavior. Comparing against other implementations can help (but remember that implementations\r\ncan differ while conforming to the Standard); try [Compiler Explorer][]. If you still aren't\r\nsure, ask the nearest C++ expert.\r\n\r\n* You should prepare a self-contained command-line test case, ideally as small as possible. We need a source file, a\r\ncommand line, what happened (e.g. a compiler error, runtime misbehavior), and what you expected to happen. By\r\n\"self-contained\", we mean that your source file has to avoid including code that we don't have. Ideally, only CRT and\r\nSTL headers should be included. If you have to include other MSVC libraries, or the Windows SDK, to trigger an STL bug,\r\nthat's okay. But if you need parts of your own source code to trigger the STL bug, you need to extract that for us. (On\r\nDeveloper Community, we'll accept zipped IDE projects if you have no other way to reproduce a bug, but this is very\r\ntime-consuming for us to reduce.)\r\n\r\n* A good title is helpful. We prefer \"`\u003cheader_name\u003e`: Short description of your issue\". You don't usually need to\r\nmention `std::` or C++. For example, \"`\u003ctype_traits\u003e`: `is_cute` should be true for `enum class FluffyKittens`\".\r\n\r\nIt's okay if you report an apparent STL bug that turns out to be a compiler bug or surprising-yet-Standard behavior.\r\nJust try to follow these rules, so we can spend more time fixing bugs and implementing features.\r\n\r\n# How To Build With The Visual Studio IDE\r\n\r\n1. Install Visual Studio 2022 17.11 Preview 3 or later.\r\n    * Select \"Windows 11 SDK (10.0.22621.0)\" in the VS Installer.\r\n    * We recommend selecting \"C++ CMake tools for Windows\" in the VS Installer.\r\n    This will ensure that you're using supported versions of CMake and Ninja.\r\n    * Otherwise, install [CMake][] 3.29.0 or later, and [Ninja][] 1.11.0 or later.\r\n    * Make sure [Python][] 3.12 or later is available to CMake.\r\n2. Open Visual Studio, and choose the \"Clone or check out code\" option. Enter the URL of this repository,\r\n   `https://github.com/microsoft/STL`.\r\n3. Open a terminal in the IDE with `` Ctrl + ` `` (by default) or press on \"View\" in the top bar, and then \"Terminal\".\r\n4. In the terminal, invoke `git submodule update --init --progress`\r\n5. Choose the architecture you wish to build in the IDE, and build as you would any other project. All necessary CMake\r\n   settings are set by `CMakePresets.json`.\r\n\r\n# How To Build With A Native Tools Command Prompt\r\n\r\n1. Install Visual Studio 2022 17.11 Preview 3 or later.\r\n    * Select \"Windows 11 SDK (10.0.22621.0)\" in the VS Installer.\r\n    * We recommend selecting \"C++ CMake tools for Windows\" in the VS Installer.\r\n    This will ensure that you're using supported versions of CMake and Ninja.\r\n    * Otherwise, install [CMake][] 3.29.0 or later, and [Ninja][] 1.11.0 or later.\r\n    * Make sure [Python][] 3.12 or later is available to CMake.\r\n2. Open a command prompt.\r\n3. Change directories to a location where you'd like a clone of this STL repository.\r\n4. `git clone https://github.com/microsoft/STL.git --recurse-submodules`\r\n\r\nTo build the x86 target:\r\n\r\n1. Open an \"x86 Native Tools Command Prompt for VS 2022 Preview\".\r\n2. Change directories to the previously cloned `STL` directory.\r\n3. `cmake --preset x86`\r\n4. `cmake --build --preset x86`\r\n\r\nTo build the x64 target (recommended):\r\n\r\n1. Open an \"x64 Native Tools Command Prompt for VS 2022 Preview\".\r\n2. Change directories to the previously cloned `STL` directory.\r\n3. `cmake --preset x64`\r\n4. `cmake --build --preset x64`\r\n\r\n# How To Consume\r\n\r\nConsumption of the built library is largely based on the build system you're using. There are at least 2 directories\r\nyou need to hook up. Assuming you built the x64 target with the Visual Studio IDE, with the STL repository cloned to\r\n`C:\\Dev\\STL`, build outputs will end up at `C:\\Dev\\STL\\out\\x64\\out`. Ensure that the `inc` directory is searched\r\nfor headers, and that `lib\\{architecture}` is searched for link libraries, before any defaults supplied by MSVC. The\r\nnames of the import and static libraries are the same as those that ship with MSVC. As a result, the compiler `/MD`,\r\n`/MDd`, `/MT`, or `/MTd` switches will work without modification of your build scripts or command-line muscle memory.\r\n\r\nShould you choose to use the DLL flavors, the DLLs to deploy are built to `bin\\{architecture}`. Note that the DLLs\r\ngenerated by the CMake build system here have a suffix, defaulting to `_oss`, which distinguishes them from the binaries\r\nthat ship with MSVC. That avoids any conflict with the DLLs installed by the [redistributables][] into System32 and\r\nensures that other components wanting to be a \"guest in your process\", like print drivers and shell extensions, see the\r\nexport surface of the STL they were built with. Otherwise, the \"`msvcp140.dll`\" you deployed in the same directory as\r\nyour .exe would \"win\" over the versions in System32.\r\n\r\nThe compiler looks for include directories according to the `INCLUDE` environment variable, and the linker looks for\r\nimport library directories according to the `LIB` environment variable, and the Windows loader will (eventually) look\r\nfor DLL dependencies according to directories in the `PATH` environment variable.\r\nThe build generates a batch script named `set_environment.bat` in the output directory. If you run this script in a VS\r\nDeveloper Command Prompt, it will insert the proper directories into the `INCLUDE`, `LIB`, and `PATH` environment\r\nvariables to ensure that the built headers and libraries are used.\r\n\r\n## Complete Example Using x64 DLL Flavor\r\n\r\nFrom an \"x64 Native Tools Command Prompt for VS 2022 Preview\":\r\n\r\n```\r\nC:\\Users\\username\\Desktop\u003eC:\\Dev\\STL\\out\\x64\\set_environment.bat\r\n\r\nC:\\Users\\username\\Desktop\u003etype example.cpp\r\n#include \u003ciostream\u003e\r\n\r\nint main() {\r\n    std::cout \u003c\u003c \"Hello STL OSS world!\\n\";\r\n}\r\n\r\nC:\\Users\\username\\Desktop\u003ecl /nologo /EHsc /W4 /WX /MDd /std:c++latest .\\example.cpp\r\nexample.cpp\r\n\r\nC:\\Users\\username\\Desktop\u003e.\\example.exe\r\nHello STL OSS world!\r\n\r\nC:\\Users\\username\\Desktop\u003edumpbin /DEPENDENTS .\\example.exe | findstr msvcp\r\n    msvcp140d_oss.dll\r\n```\r\n\r\n# How To Run The Tests With A Native Tools Command Prompt\r\n\r\n1. Follow either [How To Build With A Native Tools Command Prompt][] or [How To Build With The Visual Studio IDE][].\r\n2. Acquire [Python][] 3.12 or newer and have it on the `PATH` (or run it directly using its absolute or relative path).\r\n3. Have LLVM's `bin` directory on the `PATH` (so `clang-cl.exe` is available).\r\n    * We recommend selecting \"C++ Clang tools for Windows\" in the VS Installer. This will automatically add LLVM to the\r\n    `PATH` of the x86 and x64 Native Tools Command Prompts, and will ensure that you're using a supported version.\r\n    * Otherwise, use [LLVM's installer][] and choose to add LLVM to your `PATH` during installation.\r\n4. Follow the instructions below.\r\n\r\n## Running All The Tests\r\n\r\nAfter configuring and building the project, running `ctest` from the build output directory will run all the tests.\r\nCTest will only display the standard error output of tests that failed. In order to get more details from CTest's\r\n`lit` invocations, run the tests with `ctest -V`.\r\n\r\n## Running A Subset Of The Tests\r\n\r\n`${PROJECT_BINARY_DIR}\\tests\\utils\\stl-lit\\stl-lit.py` can be invoked on a subdirectory of a test suite and will execute\r\nall the tests under that subdirectory. This can mean executing the entirety of a single test suite, running all tests\r\nunder a category in libcxx, or running a single test in `std` and `tr1`.\r\n\r\n## Examples\r\n\r\nThese examples assume that your current directory is `C:\\Dev\\STL\\out\\x64`.\r\n\r\n* This command will run all of the test suites with verbose output.\r\n  + `ctest -V`\r\n* This command will also run all of the test suites.\r\n  + `python tests\\utils\\stl-lit\\stl-lit.py ..\\..\\llvm-project\\libcxx\\test ..\\..\\tests\\std ..\\..\\tests\\tr1`\r\n* This command will run all of the std test suite.\r\n  + `python tests\\utils\\stl-lit\\stl-lit.py ..\\..\\tests\\std`\r\n* If you want to run a subset of a test suite, you need to point it to the right place in the sources. The following\r\nwill run the single test found under VSO_0000000_any_calling_conventions.\r\n  + `python tests\\utils\\stl-lit\\stl-lit.py ..\\..\\tests\\std\\tests\\VSO_0000000_any_calling_conventions`\r\n* You can invoke `stl-lit` with any arbitrary subdirectory of a test suite. In libcxx this allows you to have finer\r\ncontrol over what category of tests you would like to run. The following will run all the libcxx map tests.\r\n  + `python tests\\utils\\stl-lit\\stl-lit.py ..\\..\\llvm-project\\libcxx\\test\\std\\containers\\associative\\map`\r\n* You can also use the `--filter` option to include tests whose names match a regular expression. The following\r\n  command will run tests with \"atomic_wait\" in their names in both the std and libcxx test suites.\r\n  + `python tests\\utils\\stl-lit\\stl-lit.py ..\\..\\llvm-project\\libcxx\\test ..\\..\\tests\\std --filter=atomic_wait`\r\n* There's also a `--filter-out` option to exclude tests matching a regular expression;\r\n  `--filter=iota --filter-out=view` would run tests with names matching \"iota\" but not \"view\".\r\n\r\n## Interpreting The Results Of Tests\r\n\r\n### CTest\r\n\r\nWhen running the tests via CTest, all of the test suites are considered to be a single test. If any single test in a\r\ntest suite fails, CTest will simply report that the `stl` test failed.\r\n\r\nExample:\r\n```\r\n0% tests passed, 1 tests failed out of 1\r\n\r\nTotal Test time (real) = 2441.55 sec\r\n\r\nThe following tests FAILED:\r\n      1 - stl (Failed)\r\n```\r\n\r\nThe primary utility of CTest in this case is to conveniently invoke `stl-lit.py` with the correct set of arguments.\r\n\r\nCTest will output everything that was sent to stderr for each of the failed test suites, which can be used to identify\r\nwhich individual test within the test suite failed. It can sometimes be helpful to run CTest with the `-V` option in\r\norder to see the stdout of the tests.\r\n\r\n### stl-lit\r\n\r\nWhen running the tests directly via the generated `stl-lit.py` script the result of each test will be printed. The\r\nformat of each result is `{Result Code}: {Test Suite Name} :: {Test Name}:{Configuration Number}`.\r\n\r\nExample:\r\n```\r\n-- Testing: 28 tests, 12 workers --\r\nPASS: tr1 :: tests/cwchar1:01 (1 of 28)\r\nPASS: tr1 :: tests/cwchar1:11 (2 of 28)\r\nPASS: tr1 :: tests/cwchar1:02 (3 of 28)\r\nPASS: tr1 :: tests/cwchar1:03 (4 of 28)\r\nPASS: tr1 :: tests/cwchar1:00 (5 of 28)\r\nPASS: tr1 :: tests/cwchar1:04 (6 of 28)\r\nPASS: tr1 :: tests/cwchar1:05 (7 of 28)\r\nPASS: tr1 :: tests/cwchar1:09 (8 of 28)\r\nPASS: tr1 :: tests/cwchar1:06 (9 of 28)\r\nUNSUPPORTED: tr1 :: tests/cwchar1:20 (10 of 28)\r\nUNSUPPORTED: tr1 :: tests/cwchar1:21 (11 of 28)\r\nUNSUPPORTED: tr1 :: tests/cwchar1:22 (12 of 28)\r\nUNSUPPORTED: tr1 :: tests/cwchar1:23 (13 of 28)\r\nUNSUPPORTED: tr1 :: tests/cwchar1:24 (14 of 28)\r\nPASS: tr1 :: tests/cwchar1:07 (15 of 28)\r\nPASS: tr1 :: tests/cwchar1:08 (16 of 28)\r\nPASS: tr1 :: tests/cwchar1:10 (17 of 28)\r\nPASS: tr1 :: tests/cwchar1:16 (18 of 28)\r\nPASS: tr1 :: tests/cwchar1:17 (19 of 28)\r\nPASS: tr1 :: tests/cwchar1:14 (20 of 28)\r\nPASS: tr1 :: tests/cwchar1:12 (21 of 28)\r\nPASS: tr1 :: tests/cwchar1:13 (22 of 28)\r\nPASS: tr1 :: tests/cwchar1:19 (23 of 28)\r\nPASS: tr1 :: tests/cwchar1:18 (24 of 28)\r\nPASS: tr1 :: tests/cwchar1:15 (25 of 28)\r\nPASS: tr1 :: tests/cwchar1:25 (26 of 28)\r\nPASS: tr1 :: tests/cwchar1:26 (27 of 28)\r\nPASS: tr1 :: tests/cwchar1:27 (28 of 28)\r\n\r\nTesting Time: 3.96s\r\n  Expected Passes    : 23\r\n  Unsupported Tests  : 5\r\n```\r\n\r\nIn the above example, we see that 23 tests succeeded and 5 were unsupported.\r\n\r\n### Result Code Values\r\n\r\nOur tests use the standard [lit result codes][], and an undocumented result code: `SKIPPED`. For our tests, only the\r\n`PASS`, `XFAIL`, `XPASS`, `FAIL`, `UNSUPPORTED`, and `SKIPPED` result codes are relevant.\r\n\r\nThe `PASS` and `FAIL` result codes are self-explanatory. We want our tests to `PASS` and not `FAIL`.\r\n\r\nThe `XPASS` and `XFAIL` result codes are less obvious. `XPASS` is actually a failure result and indicates that we\r\nexpected a test to fail but it passed. `XFAIL` is a successful result and indicates that we expected the test to fail\r\nand it did. Typically an `XPASS` result means that the `expected_results.txt` file for the test suite needs to be\r\nmodified. If the `XPASS` result is a test legitimately passing, the usual course of action would be to remove a `FAIL`\r\nentry from the `expected_results.txt`. However, some tests from `libcxx` mark themselves as `XFAIL` (meaning they\r\nexpect to fail) for features they have added tests for but have yet to implement in `libcxx`. If the STL implements\r\nthose features first the tests will begin passing unexpectedly for us and return `XPASS` results. In order to resolve\r\nthis it is necessary to add a `PASS` entry to the `expected_results.txt` of the test suite in question.\r\n\r\nThe `UNSUPPORTED` result code means that the requirements for a test are not met and so it will not be run. Currently,\r\nall tests which use the `/clr` or `/clr:pure` options are unsupported. Also, the `/BE` option is unsupported for x86.\r\n\r\nThe `SKIPPED` result code indicates that a given test was explicitly skipped by adding a `SKIPPED` entry to the\r\n`expected_results.txt`. A test may be skipped for a number of reasons, which include, but are not limited to:\r\n* being an incorrect test\r\n* taking a very long time to run\r\n* failing or passing for the incorrect reason\r\n\r\n### Debugging Individual Tests\r\n\r\nWhile `stl-lit` is super awesome in finding out that *something* is wrong or not even compiling, it is not really\r\nhelpful in debugging *what* is going wrong. However, debugging individual tests is rather simple given some additional\r\nsteps. Let's assume we want to debug a new feature with tests located in `tests\\std\\tests\\GH_XXXX_meow`.\r\n\r\nAs always, build the STL from your branch and run the tests:\r\n```\r\nC:\\STL\\out\\x64\u003e ninja\r\nC:\\STL\\out\\x64\u003e python tests\\utils\\stl-lit\\stl-lit.py -v C:\\STL\\tests\\std\\tests\\GH_XXXX_meow\r\n```\r\n\r\nLet's assume one of the tests fails an assert and we want to debug that configuration. `stl-lit` will conveniently print\r\nthe build command, which is far too long to provide here in full. The important part is to add the following options to\r\nprovide debug symbols: `/Zi /Fdbark.pdb`.\r\n\r\nYou can replace `bark` with any descriptive name you like. Add these before the `\"-link\"` option in the command line\r\nand recompile. Example:\r\n```\r\nC:\\STL\\out\\x64\u003ecl \"C:\\STL\\tests\\std\\tests\\GH_XXXX_meow\\test.cpp\" [... more arguments ...]\r\n\"-FeC:\\STL\\out\\x64\\tests\\std\\tests\\GH_XXXX_meow\\Output\\02\\GH_XXXX_meow.exe\" /Zi /Fdbark.pdb \"-link\"\r\n[... more arguments ...]\r\n```\r\n\r\nYou can now start debugging the test via:\r\n```\r\ndevenv \"C:\\STL\\out\\x64\\tests\\std\\tests\\GH_XXXX_meow\\Output\\02\\GH_XXXX_meow.exe\"\r\n       \"C:\\STL\\tests\\std\\tests\\GH_XXXX_meow\\test.cpp\"\r\n```\r\n\r\nHowever, this might not work right away, as Visual Studio may complain about a missing `msvcp140_oss.dll`. The reason\r\nis that the STL builds those and other DLLs itself and we should under no circumstances overwrite the installed ones.\r\nIf you are testing one of the configurations with dynamic linkage (`/MD` or `/MDd`) the easiest solution is to add the\r\nbuild folder to your path:\r\n```\r\nset PATH=C:\\STL\\out\\x64\\out\\bin\\amd64;%PATH%\r\n```\r\n\r\n# Benchmarking\r\n\r\nFor performance-sensitive code \u0026ndash; containers, algorithms, and the like \u0026ndash;\r\nyou may wish to write and/or run benchmarks, and the STL team will likely\r\nrun any benchmarks we do have in our PR process. Additionally,\r\nif you are writing a \"performance improvement\" PR, please add and run benchmarks\r\nto show that the PR does, in fact, improve performance.\r\n\r\nThe benchmarking code is located in `benchmarks`. Adding a new benchmark is as easy as adding a new file\r\nto `benchmarks/src`, and then adding `add_benchmark(\u003cname\u003e \u003csource_file\u003e)`\r\nto `benchmarks/CMakeLists.txt`.\r\nYou may also modify an existing benchmark file. We use Google's [Benchmark][gbenchmark] library,\r\nso you may find [their documentation][gbenchmark:docs] helpful, and you can also read the existing code\r\nfor how _we_ use it.\r\n\r\nTo run benchmarks, you'll need to first build the STL, then build the benchmarks:\r\n\r\n```cmd\r\ncmake --preset x64\r\ncmake --build --preset x64\r\ncmake -B out\\bench -S benchmarks -G Ninja -DSTL_BINARY_DIR=out\\x64\r\ncmake --build out\\bench\r\n```\r\n\r\nYou can then run your benchmark with:\r\n\r\n```cmd\r\nout\\bench\\benchmark-\u003cbenchmark-name\u003e --benchmark_out=\u003cfile\u003e --benchmark_out_format=csv\r\n```\r\n\r\nAnd then you can copy this CSV file into Excel, or another spreadsheet program. For example:\r\n\r\n```cmd\r\nout\\bench\\benchmark-std_copy --benchmark_out=benchmark-std_copy-results.csv --benchmark_out_format=csv\r\n```\r\n\r\nIf you want to see all the other flags you can pass, run:\r\n\r\n```cmd\r\nout\\bench\\benchmark-\u003cbenchmark-name\u003e --help\r\n```\r\n\r\n# Editing And Testing The Debugger Visualizer\r\n\r\n### Modify The Visualizer\r\n\r\nTo modify how components are visualized in the debugger, edit the file `stl\\debugger\\STL.natvis`. For more information\r\non how to modify this file, check the [natvis documentation][].\r\n\r\n### Test Your Changes\r\n\r\nYou can add the natvis file to any Visual Studio C++ project if you right-click your project \u003e Add \u003e Existing Item and\r\nselect the STL.natvis file. After doing this you should be able to see your changes in a Visual Studio debugging\r\nsession.\r\n\r\n# Block Diagram\r\n\r\nThe STL is built atop other compiler support libraries that ship with Windows and Visual Studio, like the UCRT,\r\nVCRuntime, and VCStartup. The following diagram describes the dependencies between those components and their ship\r\nvehicles.\r\n\r\n```mermaid\r\nflowchart TB\r\n%%{ init: {\"flowchart\": {\"htmlLabels\": true}} }%%\r\n    classDef default text-align:left\r\n    subgraph VisualStudioSubgraph[Visual Studio]\r\n        direction TB\r\n        STLNode(\"\u003cb\u003eSTL\u003c/b\u003e\r\n        This repo; provides C++ Standard Library headers, separately\r\n        compiled implementations of most of the iostreams functionality,\r\n        and a few runtime support components like std::exception_ptr.\")\r\n        subgraph VCRuntimeSubgraph[VCRuntime]\r\n            direction TB\r\n            VCStartupNode(\"\u003cb\u003eVCStartup\u003c/b\u003e\r\n            Provides compiler support mechanisms that\r\n            live in each binary; such as machinery to\r\n            call constructors and destructors for global\r\n            variables, the entry point, and the /GS cookie.\r\n\r\n            Merged into static and import libraries of VCRuntime.\")\r\n            VCRuntimeNode(\"\u003cb\u003eVCRuntime\u003c/b\u003e\r\n            Provides compiler support mechanisms that can be\r\n            shared between binaries; code that the compiler calls\r\n            on your behalf, such as the C++ exception handling\r\n            runtime, string.h intrinsics, math intrinsics, and\r\n            declarations for CPU-vendor-specific intrinsics.\")\r\n        end\r\n    end\r\n    subgraph WindowsSDKSubgraph[Windows SDK]\r\n        UniversalCRTNode(\"\u003cb\u003eUniversal CRT\u003c/b\u003e\r\n        Windows component that provides C library support, such as printf,\r\n        C locales, and some POSIX-like shims for the Windows API, like _stat.\")\r\n    end\r\n    STLNode ==\u003e VCRuntimeSubgraph \u0026 UniversalCRTNode\r\n    VCStartupNode ==\u003e VCRuntimeNode ==\u003e UniversalCRTNode\r\n```\r\n\r\n# Contributing\r\n\r\nThis project welcomes contributions and suggestions. Most contributions require you to agree to a\r\nContributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us\r\nthe rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.\r\n\r\nWhen you submit a pull request, a CLA bot will automatically determine whether you need to provide\r\na CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions\r\nprovided by the bot. You will only need to do this once across all repos using our CLA.\r\n\r\nSee [CONTRIBUTING.md][] for more information.\r\n\r\n# Code Of Conduct\r\n\r\nThis project has adopted the [Microsoft Open Source Code of Conduct][].\r\n\r\nSee [CODE_OF_CONDUCT.md][] for more information.\r\n\r\n# License\r\n\r\nCopyright (c) Microsoft Corporation.\r\n\r\nSPDX-License-Identifier: Apache-2.0 WITH LLVM-exception\r\n\r\n[Changelog]: https://github.com/microsoft/STL/wiki/Changelog\r\n[clang-format]: https://clang.llvm.org/docs/ClangFormat.html\r\n[CMake]: https://cmake.org/download\r\n[CODE_OF_CONDUCT.md]: CODE_OF_CONDUCT.md\r\n[Compiler Explorer]: https://godbolt.org\r\n[CONTRIBUTING.md]: CONTRIBUTING.md\r\n[Developer Community]: https://aka.ms/feedback/report?space=62\r\n[Discord server]: https://discord.gg/XWanNww\r\n[How To Build With A Native Tools Command Prompt]: #how-to-build-with-a-native-tools-command-prompt\r\n[How To Build With The Visual Studio IDE]: #how-to-build-with-the-visual-studio-ide\r\n[LICENSE.txt]: LICENSE.txt\r\n[LLVM's installer]: https://releases.llvm.org/download.html\r\n[LWG issues]: https://cplusplus.github.io/LWG/lwg-toc.html\r\n[LWG tag]: https://github.com/microsoft/STL/issues?q=is%3Aopen+is%3Aissue+label%3ALWG\r\n[Microsoft Open Source Code of Conduct]: https://opensource.microsoft.com/codeofconduct/\r\n[N4981]: https://wg21.link/N4981\r\n[NOTICE.txt]: NOTICE.txt\r\n[Ninja]: https://ninja-build.org\r\n[STL-CI-badge]: https://dev.azure.com/vclibs/STL/_apis/build/status%2FSTL-CI?branchName=main \"STL-CI\"\r\n[STL-CI-link]: https://dev.azure.com/vclibs/STL/_build/latest?definitionId=4\u0026branchName=main\r\n[STL-ASan-CI-badge]: https://dev.azure.com/vclibs/STL/_apis/build/status%2FSTL-ASan-CI?branchName=main \"STL-ASan-CI\"\r\n[STL-ASan-CI-link]: https://dev.azure.com/vclibs/STL/_build/latest?definitionId=5\u0026branchName=main\r\n[Python]: https://www.python.org/downloads/windows/\r\n[Roadmap]: https://github.com/microsoft/STL/wiki/Roadmap\r\n[Status Chart]: https://microsoft.github.io/STL/\r\n[bug tag]: https://github.com/microsoft/STL/issues?q=is%3Aopen+is%3Aissue+label%3Abug\r\n[cxx20 tag]: https://github.com/microsoft/STL/issues?q=is%3Aopen+is%3Aissue+label%3Acxx20\r\n[enhancement tag]: https://github.com/microsoft/STL/issues?q=is%3Aopen+is%3Aissue+label%3Aenhancement\r\n[gbenchmark]: https://github.com/google/benchmark\r\n[gbenchmark:docs]: https://github.com/google/benchmark/blob/main/docs/user_guide.md\r\n[hub]: https://support.microsoft.com/en-us/help/4021566/windows-10-send-feedback-to-microsoft-with-feedback-hub-app\r\n[libcxx]: https://libcxx.llvm.org\r\n[lit]: https://llvm.org/docs/CommandGuide/lit.html\r\n[lit result codes]: https://llvm.org/docs/CommandGuide/lit.html#test-status-results\r\n[redistributables]: https://learn.microsoft.com/en-US/cpp/windows/latest-supported-vc-redist\r\n[natvis documentation]: https://learn.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects\r\n","funding_links":[],"categories":["C++","TODO"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrosoft%2FSTL","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmicrosoft%2FSTL","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmicrosoft%2FSTL/lists"}