# GoogleTest Build Options gtest_disable_pthreads and gtest_hide_internal_symbols Explained

> Understand GoogleTest build options gtest_disable_pthreads and gtest_hide_internal_symbols. Optimize for embedded environments and avoid linkage conflicts in shared libraries.

- Repository: [Google/googletest](https://github.com/google/googletest)
- Tags: deep-dive
- Published: 2026-08-29

---

**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`](https://github.com/google/googletest/blob/main/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`](https://github.com/google/googletest/blob/main/googletest/CMakeLists.txt) (lines 22-27), the option is declared as:

```cmake
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:

```cmake
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`](https://github.com/google/googletest/blob/main/googletest/CMakeLists.txt) (lines 75-78).

```cmake
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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/google/googletest/blob/main/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`](https://github.com/google/googletest/blob/main/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.