STL README

The project's README from github.com/microsoft/STL. As one markdown file: README.md.

Microsoft's C++ Standard Library

This is the official repository for Microsoft's implementation of the C++ Standard Library (also known as the STL), which ships as part of the MSVC toolset and the Visual Studio IDE.

What This Repo Is Useful For

If you're a programmer who just wants to use the STL, you don't need this repo. Simply install the Visual Studio IDE and select the "Desktop development with C++" workload.

If you want to participate in the STL's development, welcome! You can report issues, comment on pull requests, and learn about what we're working on. You can also submit pull requests to fix bugs or add features: see CONTRIBUTING.md for more information.

Finally, you can take our code and use it in other apps and libraries (according to the terms of our license, like everything else).

GitHub Migration Status

We're in the process of moving all of our work on the STL to GitHub. Current status:

Goals

We're implementing the latest C++ Working Draft, currently N5054, which will eventually become the next C++ International Standard. The terms Working Draft (WD) and Working Paper (WP) are interchangeable; we often informally refer to these drafts as "the Standard" while being aware of the difference. (There are other relevant Standards; for example, supporting /std:c++14 and /std:c++17 involves understanding how the C++14 and C++17 Standards differ from the Working Paper, and we often need to refer to the C Standard Library and ECMAScript regular expression specifications.)

Our primary goals are conformance, performance, usability, and compatibility.

Non-Goals

There are things that we aren't interested in doing with this project, for various reasons (most importantly, we need to focus development effort on our goals). Some examples:

If you're proposing a feature to WG21 (the C++ Standardization Committee), you're welcome (and encouraged!) to use our code as a base for a proof-of-concept implementation. These non-goals simply mean that we're unable to consider pull requests for a proposed feature until it has been voted into a Working Paper. After that happens, we'll be delighted to review a production-ready pull request.

Reporting Issues

You can report STL bugs here, where they'll be directly reviewed by maintainers. You can also report STL bugs through Developer Community, or the VS IDE (Help > Send Feedback > Report a Problem...).

Please help us efficiently process bug reports by following these rules:

It's okay if you report an apparent STL bug that turns out to be a compiler bug or surprising-yet-Standard behavior. Just try to follow these rules, so we can spend more time fixing bugs and implementing features.

Visual Studio Installer Prerequisites

Note 1: The STL and the compiler ship together, and we frequently need recently implemented compiler fixes and features, so the Latest build tools (i.e. latest production) are too old. Because the Insiders IDE supports having the Latest and Preview build tools installed simultaneously, you need to ensure that you're using the Preview build tools. If you build with the IDE, we've arranged for this to happen automatically. If you build with the Command Prompt, you need to pass -vcvars_ver=preview as explained below. For more info, read the C++ Team Blog post that announced this release process.

Note 2: The x64/x86 build tools are usually sufficient. You'll need the ARM64/ARM64EC build tools if you're working with architecture-sensitive code. For example, <atomic> has conditionally compiled code for the _M_ARM64 and _M_ARM64EC predefined macros.

How To Build With The Visual Studio IDE

  1. Open Visual Studio and select "Clone a repository".
  2. Enter https://github.com/microsoft/STL.git as the repository location. Choose a local path. Click "Clone".
  3. File > Open > Folder... > Select the folder that you just cloned the repository into.
  4. Use the IDE's dropdown menu to choose the architecture you want to build. We recommend x64 for general development.
  5. Build > Build All.

How To Build With The Command Prompt

  1. Open a command prompt.
  2. Change directories to a location where you'd like a clone of this STL repository.
  3. git clone https://github.com/microsoft/STL.git --recurse-submodules
  4. pushd STL

The following instructions assume that you're starting in the previously cloned STL directory. If you installed VS to a non-default location, change the vcvarsall.bat paths below accordingly.

To build the x64 target (recommended):

  1. pushd "%ProgramFiles%\Microsoft Visual Studio\18\Insiders\VC\Auxiliary\Build"
  2. vcvarsall.bat x64 -vcvars_ver=preview
  3. popd
  4. cmake --preset x64
  5. cmake --build --preset x64

To build the x86 target:

  1. pushd "%ProgramFiles%\Microsoft Visual Studio\18\Insiders\VC\Auxiliary\Build"
  2. vcvarsall.bat x86 -vcvars_ver=preview
  3. popd
  4. cmake --preset x86
  5. cmake --build --preset x86

To build the ARM64 target:

  1. pushd "%ProgramFiles%\Microsoft Visual Studio\18\Insiders\VC\Auxiliary\Build"
  2. vcvarsall.bat x64_arm64 -vcvars_ver=preview
  3. popd
  4. cmake --preset ARM64
  5. cmake --build --preset ARM64

To build the ARM64EC target:

  1. pushd "%ProgramFiles%\Microsoft Visual Studio\18\Insiders\VC\Auxiliary\Build"
  2. vcvarsall.bat x64_arm64 -vcvars_ver=preview
  3. popd
  4. cmake --preset ARM64EC
  5. cmake --build --preset ARM64EC

Building ARM64 Natively

By default, the x64 and x86 presets are configured to both build and run the tests. The ARM64 and ARM64EC presets assume that you're cross-compiling, so they enable an option TESTS_BUILD_ONLY to build test executables without running them. If you have an ARM64 machine, you'll want to use the native compiler, and you'll want to disable TESTS_BUILD_ONLY:

  1. pushd "%ProgramFiles%\Microsoft Visual Studio\18\Insiders\VC\Auxiliary\Build"
  2. vcvarsall.bat arm64 -vcvars_ver=preview
  3. popd
  4. cmake --preset ARM64 -DTESTS_BUILD_ONLY=OFF
  5. cmake --build --preset ARM64

How To Consume

Consumption of the built library is largely based on the build system you're using. There are at least 2 directories you need to hook up. Assuming you built the x64 target with the Visual Studio IDE, with the STL repository cloned to C:\Dev\STL, build outputs will end up at C:\Dev\STL\out\x64\out. Ensure that the inc directory is searched for headers, and that lib\{architecture} is searched for link libraries, before any defaults supplied by MSVC. The names of the import and static libraries are the same as those that ship with MSVC. As a result, the compiler /MD, /MDd, /MT, or /MTd switches will work without modification of your build scripts or command-line muscle memory.

Should you choose to use the DLL flavors, the DLLs to deploy are built to bin\{architecture}. Note that the DLLs generated by the CMake build system here have a suffix, defaulting to _oss, which distinguishes them from the binaries that ship with MSVC. That avoids any conflict with the DLLs installed by the redistributables into System32 and ensures that other components wanting to be a "guest in your process", like print drivers and shell extensions, see the export surface of the STL they were built with. Otherwise, the "msvcp140.dll" you deployed in the same directory as your .exe would "win" over the versions in System32.

The compiler looks for include directories according to the INCLUDE environment variable, and the linker looks for import library directories according to the LIB environment variable, and the Windows loader will (eventually) look for DLL dependencies according to directories in the PATH environment variable. The build generates a batch script named set_environment.bat in the output directory. If you run this script, it will insert the proper directories into the INCLUDE, LIB, and PATH environment variables to ensure that the built headers and libraries are used.

Complete Example Using x64 DLL Flavor

C:\Temp>pushd D:\GitHub\STL

D:\GitHub\STL>pushd "%ProgramFiles%\Microsoft Visual Studio\18\Insiders\VC\Auxiliary\Build"

C:\Program Files\Microsoft Visual Studio\18\Insiders\VC\Auxiliary\Build>vcvarsall.bat x64 -vcvars_ver=preview
**********************************************************************
** Visual Studio 2026 Developer Command Prompt v18.4.0-insiders
** Copyright (c) 2026 Microsoft Corporation
**********************************************************************
[vcvarsall.bat] Environment initialized for: 'x64'

C:\Program Files\Microsoft Visual Studio\18\Insiders\VC\Auxiliary\Build>popd

D:\GitHub\STL>cmake --preset x64
[...]
-- Build files have been written to: D:/GitHub/STL/out/x64

D:\GitHub\STL>cmake --build --preset x64
[762/762] Linking CXX static library out\lib\amd64\libcpmtd0.lib

D:\GitHub\STL>out\x64\set_environment.bat

D:\GitHub\STL>popd

C:\Temp>type .\example.cpp

#include <print>

int main() {
    std::println("Hello STL OSS world!");
}

C:\Temp>cl /EHsc /nologo /W4 /WX /MDd /std:c++latest .\example.cpp
example.cpp

C:\Temp>.\example.exe
Hello STL OSS world!

C:\Temp>dumpbin /DEPENDENTS .\example.exe | findstr msvcp
    msvcp140d_oss.dll

How To Run The Tests

Our tests are currently split across three test suites that are located at tests\std, tests\tr1, and llvm-project\libcxx\test\std. The test runner ${PROJECT_BINARY_DIR}\tests\utils\stl-lit\stl-lit.py accepts paths to directories in the test suites and runs all tests located in the subtree rooted at those paths. This can mean executing the entirety of a single test suite, running all tests under a category in libcxx, or running a single test in std and tr1.

Some useful stl-lit.py options:

Examples

These examples assume that your current directory is C:\Dev\STL\out\x64.

Interpreting The Results Of Tests

stl-lit.py prints the result of each test. The format of each result is {Result Code}: {Test Suite Name} :: {Test Name}:{Configuration Number}.

Example:

-- Testing: 28 tests, 12 workers --
PASS: tr1 :: tests/cwchar1:01 (1 of 28)
PASS: tr1 :: tests/cwchar1:11 (2 of 28)
PASS: tr1 :: tests/cwchar1:02 (3 of 28)
PASS: tr1 :: tests/cwchar1:03 (4 of 28)
PASS: tr1 :: tests/cwchar1:00 (5 of 28)
PASS: tr1 :: tests/cwchar1:04 (6 of 28)
PASS: tr1 :: tests/cwchar1:05 (7 of 28)
PASS: tr1 :: tests/cwchar1:09 (8 of 28)
PASS: tr1 :: tests/cwchar1:06 (9 of 28)
UNSUPPORTED: tr1 :: tests/cwchar1:20 (10 of 28)
UNSUPPORTED: tr1 :: tests/cwchar1:21 (11 of 28)
UNSUPPORTED: tr1 :: tests/cwchar1:22 (12 of 28)
UNSUPPORTED: tr1 :: tests/cwchar1:23 (13 of 28)
UNSUPPORTED: tr1 :: tests/cwchar1:24 (14 of 28)
PASS: tr1 :: tests/cwchar1:07 (15 of 28)
PASS: tr1 :: tests/cwchar1:08 (16 of 28)
PASS: tr1 :: tests/cwchar1:10 (17 of 28)
PASS: tr1 :: tests/cwchar1:16 (18 of 28)
PASS: tr1 :: tests/cwchar1:17 (19 of 28)
PASS: tr1 :: tests/cwchar1:14 (20 of 28)
PASS: tr1 :: tests/cwchar1:12 (21 of 28)
PASS: tr1 :: tests/cwchar1:13 (22 of 28)
PASS: tr1 :: tests/cwchar1:19 (23 of 28)
PASS: tr1 :: tests/cwchar1:18 (24 of 28)
PASS: tr1 :: tests/cwchar1:15 (25 of 28)
PASS: tr1 :: tests/cwchar1:25 (26 of 28)
PASS: tr1 :: tests/cwchar1:26 (27 of 28)
PASS: tr1 :: tests/cwchar1:27 (28 of 28)

Testing Time: 3.96s
  Expected Passes    : 23
  Unsupported Tests  : 5

In the above example, we see that 23 tests succeeded and 5 were unsupported.

Result Code Values

Our tests use the standard lit result codes, and an undocumented result code: SKIPPED. For our tests, only the PASS, XFAIL, XPASS, FAIL, UNSUPPORTED, and SKIPPED result codes are relevant.

The PASS and FAIL result codes are self-explanatory. We want our tests to PASS and not FAIL.

The XPASS and XFAIL result codes are less obvious. XPASS is actually a failure result and indicates that we expected a test to fail but it passed. XFAIL is a successful result and indicates that we expected the test to fail and it did. Typically an XPASS result means that the expected_results.txt file for the test suite needs to be modified. If the XPASS result is a test legitimately passing, the usual course of action would be to remove a FAIL entry from the expected_results.txt. However, some tests from libcxx mark themselves as XFAIL (meaning they expect to fail) for features they have added tests for but have yet to implement in libcxx. If the STL implements those features first the tests will begin passing unexpectedly for us and return XPASS results. In order to resolve this it is necessary to add a PASS entry to the expected_results.txt of the test suite in question.

The UNSUPPORTED result code means that the requirements for a test are not met and so it will not be run. Currently, all tests which use the /clr or /clr:pure options are unsupported. Also, the /BE option is unsupported for x86.

The SKIPPED result code indicates that a given test was explicitly skipped by adding a SKIPPED entry to the expected_results.txt. A test may be skipped for a number of reasons, which include, but are not limited to:

Debugging Individual Tests

While stl-lit is super awesome in finding out that something is wrong or not even compiling, it is not really helpful in debugging what is going wrong. However, debugging individual tests is rather simple given some additional steps. Let's assume we want to debug a new feature with tests located in tests\std\tests\GH_XXXX_meow.

As always, build the STL from your branch and run the tests:

C:\Dev\STL\out\x64> ninja
C:\Dev\STL\out\x64> python tests\utils\stl-lit\stl-lit.py -v C:\Dev\STL\tests\std\tests\GH_XXXX_meow

Let's assume one of the tests fails an assert and we want to debug that configuration. stl-lit will conveniently print the build command, which is far too long to provide here in full. The important part is to add the following options to provide debug symbols: /Zi /Fdbark.pdb.

You can replace bark with any descriptive name you like. Add these before the "-link" option in the command line and recompile. Example:

C:\Dev\STL\out\x64>cl "C:\Dev\STL\tests\std\tests\GH_XXXX_meow\test.cpp" [... more arguments ...]
"-FeC:\Dev\STL\out\x64\tests\std\tests\GH_XXXX_meow\Output\02\GH_XXXX_meow.exe" /Zi /Fdbark.pdb "-link"
[... more arguments ...]

You can now start debugging the test via:

devenv "C:\Dev\STL\out\x64\tests\std\tests\GH_XXXX_meow\Output\02\GH_XXXX_meow.exe"
       "C:\Dev\STL\tests\std\tests\GH_XXXX_meow\test.cpp"

However, this might not work right away, as Visual Studio may complain about a missing msvcp140_oss.dll. The reason is that the STL builds those and other DLLs itself and we should under no circumstances overwrite the installed ones. If you are testing one of the configurations with dynamic linkage (/MD or /MDd) the easiest solution is to add the build folder to your path:

set PATH=C:\Dev\STL\out\x64\out\bin\amd64;%PATH%

Running Tests With Address Sanitizer (ASan)

You don't need any extra steps to run with test code and the code in STL headers instrumented with ASan. The test matrices include both ASan and non-ASan configurations if you don't pass -Dtags=ASAN or -Dnotags=ASAN to exclude one or the other.

However, to instrument the separately-compiled code (the DLL, the satellites, the Import Library - everything that's in stl\src), you need to build the STL with ASan. Change the build steps to add -DSTL_ASAN_BUILD=ON:

cmake --preset x64 -DSTL_ASAN_BUILD=ON
cmake --build --preset x64

ASan-instrumented STL binaries require that the executable be instrumented as well, so you'll have to skip the non-ASan configurations by passing -Dtags=ASAN to stl-lit.py:

(This example assumes that your current directory is C:\Dev\STL\out\x64.)

python tests\utils\stl-lit\stl-lit.py ..\..\tests\std\tests\VSO_0000000_vector_algorithms -Dtags=ASAN -v

Benchmarking

For performance-sensitive code (e.g. containers and algorithms) you may wish to write and/or run benchmarks, and the STL team will likely run any benchmarks we do have in our PR process. Additionally, if you are writing a "performance improvement" PR, please add and run benchmarks to show that the PR does, in fact, improve performance.

The benchmarking code is located in benchmarks. Adding a new benchmark is as easy as adding a new file to benchmarks/src, and then adding add_benchmark(<name> <source_file>) to benchmarks/CMakeLists.txt. You may also modify an existing benchmark file. We use Google's Benchmark library, so you may find their documentation helpful, and you can also read the existing code for how we use it.

To run benchmarks, you'll need to first build the STL, then build the benchmarks:

cmake --preset x64
cmake --build --preset x64
cmake -B out\bench -S benchmarks -G Ninja -DSTL_BINARY_DIR=out\x64
cmake --build out\bench

You can then run your benchmark with:

out\bench\benchmark-<benchmark-name> --benchmark_out=<file> --benchmark_out_format=csv

And then you can copy this CSV file into Excel, or another spreadsheet program. For example:

out\bench\benchmark-std_copy --benchmark_out=benchmark-std_copy-results.csv --benchmark_out_format=csv

If you want to see all the other flags you can pass, run:

out\bench\benchmark-<benchmark-name> --help

Other Useful Incantations

To compile the benchmarks with additional compiler options, use the CXXFLAGS environment variable. Set it after configuring and building the STL, but before configuring and building the benchmarks. For example, to examine how the /arch:AVX2 option affects auto-vectorization and bit algorithm intrinsics:

set CXXFLAGS=/arch:AVX2
cmake -B out\bench -S benchmarks -G Ninja -DSTL_BINARY_DIR=out\x64
cmake --build out\bench

To compile the benchmarks with Clang, use -DCMAKE_CXX_COMPILER=clang-cl:

cmake -B out\bench -S benchmarks -G Ninja -DSTL_BINARY_DIR=out\x64 -DCMAKE_CXX_COMPILER=clang-cl
cmake --build out\bench

To run a benchmark on specific cores (e.g. P-cores vs. E-cores) and with higher priority (to avoid interference), use the start command:

start /b /wait /high /affinity 0F out\bench\benchmark-std_copy

Editing And Testing The Debugger Visualizer

Modify The Visualizer

To modify how components are visualized in the debugger, edit the file stl\debugger\STL.natvis. For more information on how to modify this file, check the natvis documentation.

Test Your Changes

You can add the natvis file to any Visual Studio C++ project if you right-click your project > Add > Existing Item and select the STL.natvis file. After doing this you should be able to see your changes in a Visual Studio debugging session.

Block Diagram

The STL is built atop other compiler support libraries that ship with Windows and Visual Studio, like the UCRT, VCRuntime, and VCStartup. The following diagram describes the dependencies between those components and their ship vehicles.

flowchart TB
%%{ init: {"flowchart": {"htmlLabels": true}} }%%
classDef default text-align:left
subgraph VisualStudioSubgraph[Visual Studio]
  direction TB
  STLNode("<b>STL</b>")
  subgraph VCRuntimeSubgraph[VCRuntime]
    direction TB
    VCRuntimeNode("<b>VCRuntime</b>")
    VCStartupNode("<b>VCStartup</b>")
  end
end
subgraph WindowsSDKSubgraph[Windows SDK]
  UniversalCRTNode("<b>Universal CRT</b>")
end
STLNode ==> VCRuntimeSubgraph & UniversalCRTNode
VCRuntimeNode ==> VCStartupNode ==> UniversalCRTNode

Contributing

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.opensource.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., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

See CONTRIBUTING.md for more information.

Code Of Conduct

This project has adopted the Microsoft Open Source Code of Conduct.

See CODE_OF_CONDUCT.md for more information.

License

Copyright (c) Microsoft Corporation.

SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception

STL (microsoft/STL)

Searching Database…

11.2K ·GitHub
STL
这是什么？微软官方的 C++ 标准库（STL）实现，随 MSVC 工具集和 Visual Studio IDE 一起发布。这个仓库托管它的源代码，也是它开发的地方。
我只是想在自己的程序里用 STL，需要这个仓库吗？不需要。只要安装带“使用 C++ 的桌面开发”工作负载的 Visual Studio IDE 就行。这个仓库是给想关注或参与 STL 开发、或者想按许可证复用其代码的人准备的。
构建之前需要先装好什么？需要 VS 2026 Insiders 及“使用 C++ 的桌面开发”工作负载——具体来说是预览版 MSVC 生成工具，因为 STL 和编译器是一起发布的，Latest 版工具太旧——另外还需要 Windows 11 SDK 10.0.28000+ 和 Python 3.14.7+。
能在 Linux 或 macOS 上用吗？不能。移植到其他平台是明确不做的事——它是 Windows 上 MSVC 工具集的标准库；其他平台用的是别的实现。
它目前实现的是哪个版本的 C++ 标准？最新的 C++ 工作草案，目前是 N5054，它最终会成为下一版国际标准。较早的语言模式（如 /std:c++14 和 /std:c++17）也会继续维护。
用旧版 Visual Studio 编译出来的程序还能链接吗？能。VS 2026 与 VS 2015-2022 保持二进制兼容，而且 ABI 兼容性的优先级高于其他一切考虑，连标准符合性也不例外。
团队平时主要优化什么？四个目标：符合工作草案、运行时性能（比大多数库投入的优化精力更多）、易用性（比如诊断信息和 [[nodiscard]] 检查），以及兼容性——所有这些都在刻意的“复杂度预算”之内。
What are similar projects?Jet, folly, libfyaml, mimalloc, googletest, ninja, ReBarUEFI, spdlog
Which topics is it in?cmake, arm64, optimization, microsoft, ci, c++, performance, apache-2.0, library, developer-tools, windows, open-source
Creator
microsoft
Size
34.7 MB
Stars
11.2K
Updated
CommitOct 06Releasemsvc-build-tools-14.51Jun 23
Age
7y
Commits · 90 Days