GoogleTest Build Options gtest_disable_pthreads and gtest_hide_internal_symbols Explained

The gtest_disable_pthreads option strips POSIX thread dependencies for embedded environments, while gtest_hide_internal_symbols masks internal API details in shared libraries to prevent linkage conflicts.

GoogleTest (google/googletest) exposes these CMake configuration flags in googletest/CMakeLists.txt to support specialized deployment scenarios. The GoogleTest build options gtest_disable_pthreads and gtest_hide_internal symbols allow developers to tailor the framework's threading model and binary interface for embedded systems or shared library distributions. Understanding these flags ensures you compile only the necessary functionality while maintaining strict control over exported symbols.

Disabling POSIX Threads with gtest_disable_pthreads

The gtest_disable_pthreads option defaults to OFF. When set to ON, the CMake configuration skips the Threads package detection and removes all pthread primitives from the compiled library. This is essential for platforms lacking POSIX thread support, including certain embedded environments or Windows toolchains that intentionally avoid threading.

In googletest/CMakeLists.txt (lines 22-27), the option is declared as:

option(gtest_disable_pthreads "Disable pthreads." OFF)

The actual enforcement occurs in googletest/cmake/internal_utils.cmake at line 55, where the build system checks the flag before linking:

if (NOT gtest_disable_pthreads AND NOT MINGW)
  find_package(Threads)
endif()

When this condition fails, GoogleTest compiles without thread-local storage or background test execution capabilities, producing a pure single-threaded library.

Restricting Symbol Visibility with gtest_hide_internal_symbols

The gtest_hide_internal_symbols option controls dynamic symbol exports in shared library builds. Defaulting to OFF, enabling this flag sets CMAKE_CXX_VISIBILITY_PRESET to hidden and CMAKE_VISIBILITY_INLINES_HIDDEN to 1 in googletest/CMakeLists.txt (lines 75-78).

if (gtest_hide_internal_symbols)
  set(CMAKE_CXX_VISIBILITY_PRESET hidden)
  set(CMAKE_VISIBILITY_INLINES_HIDDEN 1)
endif()

This configuration ensures only the public ::testing:: namespace symbols appear in the dynamic symbol table, reducing the ABI surface area and preventing collisions when linking multiple shared libraries. The resulting binaries load faster and avoid runtime conflicts with other components exporting similar internal utility symbols.

Configuring Your Build

Apply these options during the CMake configuration phase to customize your GoogleTest installation.

Building Without Pthread Support

For embedded targets or minimal environments, disable threading entirely:

cmake -S . -B build \
      -DBUILD_SHARED_LIBS=OFF \
      -Dgtest_disable_pthreads=ON
cmake --build build

This generates libgtest.a without any pthread_* symbol references, suitable for bare-metal or single-threaded applications.

Creating Shared Libraries with Hidden Symbols

When distributing GoogleTest as a shared object (.so or .dll), limit exports to the public API:

cmake -S . -B build \
      -DBUILD_SHARED_LIBS=ON \
      -Dgtest_hide_internal_symbols=ON
cmake --build build

Verify the restricted symbol table with nm -D libgtest.so, which should expose only testing::* entries rather than internal helper classes.

Combined Configuration for Constrained Environments

You may enable both options simultaneously for specialized shared library builds on threadless platforms:

cmake -S . -B build \
      -DBUILD_SHARED_LIBS=ON \
      -Dgtest_disable_pthreads=ON \
      -Dgtest_hide_internal_symbols=ON
cmake --build build

This configuration produces a shared library suitable for constrained environments requiring dynamic linking but lacking system thread support.

Summary

• gtest_disable_pthreads removes POSIX thread dependencies by skipping the Threads CMake package, defined in googletest/CMakeLists.txt and enforced in googletest/cmake/internal_utils.cmake.
• gtest_hide_internal_symbols sets compiler visibility presets to hidden, limiting exported symbols to the public API and reducing ABI conflicts in shared library builds.
• Both options default to OFF and should remain disabled for standard desktop development to retain full threading capabilities and debugging visibility.
• Configure these flags during the initial CMake generation phase using -D<option>=ON to tailor GoogleTest for embedded systems or controlled distribution scenarios.

Frequently Asked Questions

When should I enable gtest_disable_pthreads?

Enable this option when building for platforms without POSIX thread support, such as bare-metal embedded systems or specialized Windows environments where threading primitives are unavailable. The resulting library operates strictly in single-threaded mode without linking against libpthread.

Does gtest_hide_internal_symbols affect static library builds?

While the flag technically applies visibility attributes, static libraries (BUILD_SHARED_LIBS=OFF) do not export symbols dynamically, so the option provides no practical benefit for .a or .lib archives. It specifically optimizes shared object files (.so, .dll, .dylib) by shrinking their dynamic symbol tables.

Can I combine both build options in the same configuration?

Yes, you can enable both gtest_disable_pthreads=ON and gtest_hide_internal_symbols=ON simultaneously. This creates a single-threaded shared library with minimal exported symbols, ideal for embedded Linux systems requiring .so files but lacking pthread support.

Where are these options defined in the GoogleTest source?

Both options are declared in googletest/CMakeLists.txt (lines 22-27 for gtest_disable_pthreads and lines 75-78 for gtest_hide_internal_symbols). The pthread option is additionally referenced in googletest/cmake/internal_utils.cmake (line 55) to conditionally skip thread detection.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}