GenerateExportHeader

This module provides commands for generating a header file containing preprocessor macro definitions to control C/C++ symbol visibility.

Load this module in CMake project with:

include(GenerateExportHeader)

在 3.12 版被加入: Support for C projects. Previous versions supported C++ projects only.

When developing C or C++ projects, especially for cross-platform use, symbol visibility determines which functions, classes, global variables, templates, and other symbols are made visible to users of the library.

For example, on Windows, symbols must be explicitly marked with __declspec(dllexport) when building a shared library, and __declspec(dllimport) when using it. Other platforms may use attributes like __attribute__((visibility("default"))).

This module simplifies the creation and usage of preprocessor macros to manage these requirements, avoiding repetitive and error-prone #ifdef blocks in source code.

Some symbol visibility can also be controlled with compiler options. In CMake, target properties such as <LANG>_VISIBILITY_PRESET and VISIBILITY_INLINES_HIDDEN enable compiler visibility flags, where appropriate. See also related convenience variables CMAKE_<LANG>_VISIBILITY_PRESET and CMAKE_VISIBILITY_INLINES_HIDDEN to enable it for all targets in current scope. These are commonly used in combination with this module to further simplify C/C++ code, removing the need for some of the preprocessor macros in the source code.

Commands

This module provides the following commands:

Generating Export Header

generate_export_header

Generates a header file suitable for inclusion in source code, containing preprocessor export macros for controlling the visibility of symbols:

generate_export_header(
  <target>
  [BASE_NAME <base-name>]
  [EXPORT_FILE_NAME <export-file-name>]
  [EXPORT_MACRO_NAME <export-macro-name>]
  [NO_EXPORT_MACRO_NAME <no-export-macro-name>]
  [DEPRECATED_MACRO_NAME <deprecated-macro-name>]
  [DEFINE_NO_DEPRECATED]
  [NO_DEPRECATED_MACRO_NAME <no-deprecated-macro-name>]
  [STATIC_DEFINE <static-define>]
  [PREFIX_NAME <prefix>]
  [CUSTOM_CONTENT_FROM_VARIABLE <variable>]
  [INCLUDE_GUARD_NAME <include-guard-name>]
)

By default, this command generates a header file named <target-name-lowercase>_export.h in the current binary directory (CMAKE_CURRENT_BINARY_DIR). This header defines a set of preprocessor macros used to mark API symbols as exported, hidden, or deprecated across different platforms and build types (e.g., static or shared builds), and is intended to be installed along with the library's public headers, because it affects public API declarations:

• <MACRO>_EXPORT: Marks symbols for export or import, making them visible as part of the public API when building or consuming a shared library.

• <MACRO>_NO_EXPORT: Marks symbols that should not be exported. If the <LANG>_VISIBILITY_PRESET target property is set to hidden, using this macro in source code is typically redundant.

• <MACRO>_DEPRECATED: Marks symbols as deprecated. When such symbols are used, the compiler emits a warning at compile-time.

• <MACRO>_DEPRECATED_EXPORT: Combines export/import and deprecation markers for a symbol that is both part of the public API and deprecated.

• <MACRO>_DEPRECATED_NO_EXPORT: Marks a deprecated symbol that should not be exported (internal and deprecated).

• <MACRO>_NO_DEPRECATED: A macro that can be used in source code to conditionally exclude deprecated code parts from the build via preprocessor logic.

The <MACRO> part is derived by default from the uppercase name of the target or the explicitly provided <base-name>. All macro names can be customized using the optional arguments.

The arguments are:

<target>

Name of a target for which the export header will be generated. Supported target types:

• STATIC library (in this case, export-related macros are defined without values)

• SHARED library

• MODULE library

• 在 3.1 版被加入: OBJECT library

BASE_NAME <base-name>

If specified, it overrides the default file name and macro names.

EXPORT_FILE_NAME <export-file-name>

If specified, it overrides the full path and the name of the generated export header file (<base-name-lowercase>_export.h) to <export-file-name>. If given as a relative path, it will be interpreted relative to the current binary directory (CMAKE_CURRENT_BINARY_DIR).

EXPORT_MACRO_NAME <export-macro-name>

If specified, it overrides the default macro name for the export directive.

NO_EXPORT_MACRO_NAME <no-export-macro-name>

If specified, the <no-export-macro-name> will be used for the macro name that designates the attribute for items that shouldn't be exported.

DEPRECATED_MACRO_NAME <deprecated-macro-name>

If specified, the following names will be used:

• <deprecated-macro-name> (macro for marking deprecated symbols)

• <deprecated-macro-name>_EXPORT (macro for deprecated symbols with export markers)

• <deprecated-macro-name>_NO_EXPORT (macro for deprecated symbols with no-export markers)

instead of the default names in format of <MACRO>_DEPRECATED{,_EXPORT,_NO_EXPORT}.

DEFINE_NO_DEPRECATED

If specified, this will define a macro named <MACRO>_NO_DEPRECATED.

NO_DEPRECATED_MACRO_NAME <no-deprecated-macro-name>

Used in combination with DEFINE_NO_DEPRECATED option. If specified, then a macro named <no-deprecated-macro-name> is used instead of the default <MACRO>_NO_DEPRECATED.

STATIC_DEFINE <static-define>

If specified, the <static-define> macro name will be used instead of the default <MACRO>_STATIC_DEFINE. This macro controls the symbol export behavior in the generated header for static libraries. It is typically used when building both shared and static variants of a library from the same sources using a single generated export header. When this macro is defined for static library, the export-related macros will expand to nothing. This is important also on Windows, where symbol decoration is required only for shared libraries, not for static ones.

PREFIX_NAME <prefix>

If specified, the additional <prefix> is prepended to all generated macro names.

CUSTOM_CONTENT_FROM_VARIABLE <variable>

在 3.7 版被加入.

If specified, the content from the <variable> value is appended to the generated header file content after the preprocessor macros definitions.

INCLUDE_GUARD_NAME <include-guard-name>

在 3.11 版被加入.

If specified, the <include-guard-name> is used as the preprocessor macro name to guard multiple inclusions of the generated header instead of the default name <export-macro-name>_H.

<base-name-lowercase>_export.h

#ifndef <include-guard-name>
#define <include-guard-name>
// ...
#endif /* <include-guard-name> */

Deprecated Command

add_compiler_export_flags

在 3.0 版之後被棄用: Set the target properties CXX_VISIBILITY_PRESET and VISIBILITY_INLINES_HIDDEN instead.

Adds C++ compiler options -fvisibility=hidden (and -fvisibility-inlines-hidden, if supported) to hide all symbols by default to either CMAKE_CXX_FLAGS variable or to a specified variable:

add_compiler_export_flags([<output_variable>])

This command is a no-op on Windows which does not need extra compiler flags for exporting support.

<output-variable>

Optional variable name that will be populated with a string of space-separated C++ compile options required to enable visibility support for the compiler/architecture in use. If this argument is specified, the CMAKE_CXX_FLAGS variable will not be modified.

範例

Example: Generating Export Header

The following example demonstrates how to use this module to generate an export header in the current binary directory (example_export.h) and use it in a C++ library named example to control symbols visibility. The generated header defines the preprocessor macros EXAMPLE_EXPORT, EXAMPLE_NO_EXPORT, EXAMPLE_DEPRECATED, EXAMPLE_DEPRECATED_EXPORT, and EXAMPLE_DEPRECATED_NO_EXPORT, and is installed along with the library's other public headers:

CMakeLists.txt

cmake_minimum_required(VERSION 3.24)
project(GenerateExportHeaderExample)

# Set default visibility of all symbols to hidden
set(CMAKE_CXX_VISIBILITY_PRESET "hidden")
set(CMAKE_VISIBILITY_INLINES_HIDDEN TRUE)

add_library(example)

include(GenerateExportHeader)
generate_export_header(example)

target_sources(
  example
  PRIVATE example.cxx
  PUBLIC
    FILE_SET HEADERS
      FILES example.h
    FILE_SET generated_headers
      TYPE HEADERS
      BASE_DIRS $<TARGET_PROPERTY:example,BINARY_DIR>
      FILES ${CMAKE_CURRENT_BINARY_DIR}/example_export.h
)

target_include_directories(example PRIVATE ${CMAKE_CURRENT_BINARY_DIR})

install(
  TARGETS example
  FILE_SET HEADERS
  FILE_SET generated_headers
)

And in the ABI header files:

example.h

#include "example_export.h"

// This class is part of the public API and is exported
class EXAMPLE_EXPORT SomeClass
{
public:
  SomeClass();
  void doSomething();

  // This method is deprecated
  EXAMPLE_DEPRECATED void legacyMethod();
};

// This function is exported and deprecated
EXAMPLE_DEPRECATED_EXPORT void legacyPublicFunction();

// This function is deprecated but not exported
EXAMPLE_DEPRECATED void legacyInternalFunction();

example.cxx

#include <iostream>
#include "example.h"

SomeClass::SomeClass() = default;

void SomeClass::doSomething()
{
  std::cout << "SomeClass::doSomething() called" << std::endl;
}

void SomeClass::legacyMethod()
{
  std::cout << "SomeClass::legacyMethod() is deprecated" << std::endl;
}

void legacyPublicFunction()
{
  std::cout << "legacyPublicFunction() is deprecated" << std::endl;
}

void internalLegacyFunction()
{
  std::cout << "legacyInternalFunction() is deprecated" << std::endl;
}

Examples: Customizing Generated Header

The BASE_NAME argument can be used to override the generated file name and the names used for the macros. The following will generate a file named other_name_export.h containing export-related macros such as OTHER_NAME_EXPORT, OTHER_NAME_NO_EXPORT, OTHER_NAME_DEPRECATED, etc.

add_library(example example.cxx)
include(GenerateExportHeader)
generate_export_header(example BASE_NAME "other_name")

The BASE_NAME may be overridden by specifying other command options. For example, the following creates a macro OTHER_NAME_EXPORT instead of EXAMPLE_EXPORT, but other macros and the generated header file name are set to their default values:

add_library(example example.cxx)
include(GenerateExportHeader)
generate_export_header(example EXPORT_MACRO_NAME "OTHER_NAME_EXPORT")

The following example creates KDE_DEPRECATED macro instead of default EXAMPLE_DEPRECATED:

add_library(example example.cxx)
include(GenerateExportHeader)
generate_export_header(example DEPRECATED_MACRO_NAME "KDE_DEPRECATED")

The DEFINE_NO_DEPRECATED option can be used to define a macro which can be used to remove deprecated code from preprocessor output:

option(EXCLUDE_DEPRECATED "Exclude deprecated parts of the library")
if(EXCLUDE_DEPRECATED)
  set(NO_BUILD_DEPRECATED DEFINE_NO_DEPRECATED)
endif()

include(GenerateExportHeader)
generate_export_header(example ${NO_BUILD_DEPRECATED})

example.h

class EXAMPLE_EXPORT SomeClass
{
public:
#ifndef EXAMPLE_NO_DEPRECATED
  EXAMPLE_DEPRECATED void legacyMethod();
#endif
};

example.cxx

#ifndef EXAMPLE_NO_DEPRECATED
void SomeClass::legacyMethod() {  }
#endif

The PREFIX_NAME argument can be used to prepend all generated macro names with some prefix. For example, the following will generate macros such as VTK_SOMELIB_EXPORT, etc.

include(GenerateExportHeader)
generate_export_header(somelib PREFIX_NAME "VTK_")

Appending additional content to generated header can be done with the CUSTOM_CONTENT_FROM_VARIABLE argument:

include(GenerateExportHeader)
set(content [[#include "project_api.h"]])
generate_export_header(example CUSTOM_CONTENT_FROM_VARIABLE content)

Example: Building Shared and Static Library

In the following example both a shared and a static library are built from the same sources, and the <MACRO>_STATIC_DEFINE macro compile definition is defined to ensure the same generated export header works for both:

add_library(example_shared SHARED example.cxx)
add_library(example_static STATIC example.cxx)

include(GenerateExportHeader)
generate_export_header(example_shared BASE_NAME "example")

# Define macro to disable export attributes for static build
target_compile_definitions(example_static PRIVATE EXAMPLE_STATIC_DEFINE)

Example: Upgrading Deprecated Command

In earlier versions of CMake, add_compiler_export_flags() command was used to add symbol visibility compile options:

CMakeLists.txt

add_library(example example.cxx)

include(GenerateExportHeader)

add_compiler_export_flags(flags)
string(REPLACE " " ";" flags "${flags}")
set_property(TARGET example APPEND PROPERTY COMPILE_OPTIONS "${flags}")

generate_export_header(example)

In new code, the following target properties are used to achieve the same functionality:

CMakeLists.txt

add_library(example example.cxx)

include(GenerateExportHeader)

set_target_properties(
  example
  PROPERTIES
    CXX_VISIBILITY_PRESET hidden
    VISIBILITY_INLINES_HIDDEN TRUE
)

generate_export_header(example)

另請參見

• The DEFINE_SYMBOL target property to customize the preprocessor macro name used by the generated header. This macro determines whether the library header is being included during the library's own compilation or when it is used by another project (e.g., after installation).

• The ENABLE_EXPORTS target property.

• The WINDOWS_EXPORT_ALL_SYMBOLS target property.