Microsoft C++ Standard Library (STL)

The STL's import library (.lib) is unique because it does more than just define symbols imported from a DLL; it also defines certain functions and variables directly within the library. This allows for extending the STL (e.g., adding <filesystem> support) without changing the DLL export surface and improves throughput by compiling constant data (like <charconv> lookup tables) separately.

Critical Limitations

When working with or building against this library, be aware of these constraints:

• No Shared Global State: Because the import library embeds part of the implementation into every user binary that links to it, variables in the import library cannot represent shared global state. If your application requires shared global state across DLL boundaries, a satellite DLL must be used instead.
• Bypassing /MD and /MDd: This technique embeds part of the STL implementation into the user's binary, which partially defeats the purpose of using the /MD (Release) or /MDd (Debug) compiler options.
• Iterator Debug Level Constraints: Because there are only two flavors of the import library (Debug and Release), the library cannot use anything that depends on _ITERATOR_DEBUG_LEVEL.
• Implementation Restrictions: To avoid the issues above, the import library is restricted to core headers only. For example, basic_string must not be used within the import library.

You can influence how benchmarks are compiled using environment variables or CMake flags:

• Compiler Flags: Use the CXXFLAGS environment variable to pass additional options (e.g., /arch:AVX2) to the benchmark compilation. This must be set after building the STL but before configuring/building the benchmarks.
• Compiler Choice: To use Clang instead of MSVC, pass -DCMAKE_CXX_COMPILER=clang-cl during the benchmark configuration step.
• Execution Priority: To run a benchmark with high priority or on specific CPU cores, use the Windows start command with /high and /affinity.

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

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

# Run with high priority and affinity
start /b /wait /high /affinity 0F out\bench\benchmark-std_copy

To use the built STL in your own projects, you need to configure your build system to find the headers and libraries.

Key Directories:

• Headers: Search the inc directory.
• Libraries: Search the lib/{architecture} directory.
• DLLs (if using DLL flavor): Located in bin/{architecture}.

Important Notes:

• Library Naming: The names of the import and static libraries match those shipped with MSVC. Standard compiler switches like /MD, /MDd, /MT, or /MTd will work without modification.
• DLL Suffix: DLLs generated by this CMake build system have a default suffix of _oss (e.g., msvcp140d_oss.dll). This prevents conflicts with standard MSVC DLLs in System32 and ensures your application uses the specific version it was built with.
• Environment Setup: The build process generates a set_environment.bat script in the output directory. Running this script automatically updates your INCLUDE, LIB, and PATH environment variables to point to the correct built headers and libraries.

To debug a failing test, first build the STL and run the specific test directory using stl-lit.py -v.

To enable debugging with Visual Studio, identify the build command printed by stl-lit.py and add the /Zi and /Fdb<name>.pdb flags before the "-link" option. This generates debug symbols. You can then launch the resulting executable and the source .cpp file directly in devenv (Visual Studio).

Note on DLLs: If testing configurations with dynamic linkage (/MD or /MDd), you may encounter missing msvcp140_oss.dll errors. To fix this, add the STL build's out/bin directory to your PATH environment variable.

# 1. Build and run tests with verbosity
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

# 2. Add debug symbols to the build command (example)
cl "C:\Dev\STL\tests\std\tests\GH_XXXX_meow\test.cpp" [...] "-FeC:\Dev\STL\out\x64\tests\std\tests\GH_XXXX_meow\Output\02\GH_XXXX_meow.exe" /Zi /Fdbark.pdb "-link" [...]

# 3. Launch in Visual Studio
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"

# 4. Fix DLL path if using /MD or /MDd
set PATH=C:\Dev\STL\out\x64\out\bin\amd64;%PATH%

Bugs should be reported directly to the STL maintainers via GitHub issues.

Bug Reporting Rules

• Scope: Only report actual STL implementation bugs here.
  • For Compiler, CRT, or IDE bugs: Use Developer Community.
  • For Windows SDK bugs: Use the Feedback Hub app.
• Verification: Ensure the issue is an implementation bug and not just undefined behavior or surprising-yet-Standard behavior. Use Compiler Explorer to compare implementations.
• Test Case: Provide a self-contained command-line test case. This should ideally include only STL and CRT headers. If you must include other libraries to reproduce the bug, ensure you have extracted the minimal logic required to trigger it.
• Title Format: Use the pattern <header_name>: Short description of your issue.
  • Example: <type_traits>: is_cute should be true for enum class FluffyKittens

To build the Microsoft STL from source using the command line, follow these steps to clone the repository and use CMake presets for different architectures.

Prerequisites:

• Git installed.
• Visual Studio installed (ensure you know the installation path for vcvarsall.bat).
• CMake installed.

Initial Setup:

git clone https://github.com/microsoft/STL.git --recurse-submodules
pushd STL

Building for specific targets: Note: If Visual Studio is in a non-default location, adjust the path to vcvarsall.bat accordingly. The following examples use the default path for Visual Studio 18 Insiders.

# Example: Building x64 target
pushd "%ProgramFiles%\Microsoft Visual Studio\18\Insiders\VC\Auxiliary\Build"
vcvarsall.bat x64 -vcvars_ver=preview
popd
cmake --preset x64
cmake --build --preset x64