GenerateExportHeader — CMake 4.0.2 Documentation (original) (raw)

This module provides the generate_export_header() function to generate export macros for libraries.

Added in version 3.12: Added support for C projects. Previous versions supported C++ project only.

generate_export_header¶

The generate_export_header() function can be used to generate a file suitable for preprocessor inclusion which contains EXPORT macros to be used in library classes:

generate_export_header(LIBRARY_TARGET [BASE_NAME ] [EXPORT_MACRO_NAME ] [EXPORT_FILE_NAME ] [DEPRECATED_MACRO_NAME ] [NO_EXPORT_MACRO_NAME ] [INCLUDE_GUARD_NAME ] [STATIC_DEFINE ] [NO_DEPRECATED_MACRO_NAME ] [DEFINE_NO_DEPRECATED] [PREFIX_NAME ] [CUSTOM_CONTENT_FROM_VARIABLE ] )

The target properties CXX_VISIBILITY_PRESETand VISIBILITY_INLINES_HIDDEN can be used to add the appropriate compile flags for targets. See the documentation of those target properties, and the convenience variablesCMAKE_CXX_VISIBILITY_PRESET andCMAKE_VISIBILITY_INLINES_HIDDEN.

By default generate_export_header() generates macro names in a file name determined by the name of the library. This means that in the simplest case, users of GenerateExportHeader will be equivalent to:

set(CMAKE_CXX_VISIBILITY_PRESET hidden) set(CMAKE_VISIBILITY_INLINES_HIDDEN 1) add_library(somelib someclass.cpp) generate_export_header(somelib) install(TARGETS somelib DESTINATION ${LIBRARY_INSTALL_DIR}) install(FILES someclass.h PROJECTBINARYDIR/somelibexport.hDESTINATION{PROJECT_BINARY_DIR}/somelib_export.h DESTINATION PROJECTB​INARYD​IR/somelibe​xport.hDESTINATION{INCLUDE_INSTALL_DIR} )

And in the ABI header files:

#include "somelib_export.h" class SOMELIB_EXPORT SomeClass { ... };

The CMake fragment will generate a file in the${CMAKE_CURRENT_BINARY_DIR} called somelib_export.h containing the macros SOMELIB_EXPORT, SOMELIB_NO_EXPORT, SOMELIB_DEPRECATED,SOMELIB_DEPRECATED_EXPORT and SOMELIB_DEPRECATED_NO_EXPORT. They will be followed by content taken from the variable specified by the CUSTOM_CONTENT_FROM_VARIABLE option, if any. The resulting file should be installed with other headers in the library.

The BASE_NAME argument can be used to override the file name and the names used for the macros:

add_library(somelib someclass.cpp) generate_export_header(somelib BASE_NAME other_name )

Generates a file called other_name_export.h containing the macrosOTHER_NAME_EXPORT, OTHER_NAME_NO_EXPORT and OTHER_NAME_DEPRECATEDetc.

The BASE_NAME may be overridden by specifying other options in the function. For example:

add_library(somelib someclass.cpp) generate_export_header(somelib EXPORT_MACRO_NAME OTHER_NAME_EXPORT )

creates the macro OTHER_NAME_EXPORT instead of SOMELIB_EXPORT, but other macros and the generated file name is as default:

add_library(somelib someclass.cpp) generate_export_header(somelib DEPRECATED_MACRO_NAME KDE_DEPRECATED )

creates the macro KDE_DEPRECATED instead of SOMELIB_DEPRECATED.

If LIBRARY_TARGET is a static library, macros are defined without values.

If the same sources are used to create both a shared and a static library, the uppercased symbol ${BASE_NAME}_STATIC_DEFINE should be used when building the static library:

add_library(shared_variant SHARED ${lib_SRCS}) add_library(static_variant ${lib_SRCS}) generate_export_header(shared_variant BASE_NAME libshared_and_static) set_target_properties(static_variant PROPERTIES COMPILE_FLAGS -DLIBSHARED_AND_STATIC_STATIC_DEFINE)

This will cause the export macros to expand to nothing when building the static library.

If DEFINE_NO_DEPRECATED is specified, then a macro${BASE_NAME}_NO_DEPRECATED will be defined This macro can be used to remove deprecated code from preprocessor output:

option(EXCLUDE_DEPRECATED "Exclude deprecated parts of the library" FALSE) if (EXCLUDE_DEPRECATED) set(NO_BUILD_DEPRECATED DEFINE_NO_DEPRECATED) endif() generate_export_header(somelib ${NO_BUILD_DEPRECATED})

And then in somelib:

class SOMELIB_EXPORT SomeClass { public: #ifndef SOMELIB_NO_DEPRECATED SOMELIB_DEPRECATED void oldMethod(); #endif };

#ifndef SOMELIB_NO_DEPRECATED void SomeClass::oldMethod() { } #endif

If PREFIX_NAME is specified, the argument will be used as a prefix to all generated macros.

For example:

generate_export_header(somelib PREFIX_NAME VTK_)

Generates the macros VTK_SOMELIB_EXPORT etc.

Added in version 3.1: Library target can be an OBJECT library.

Added in version 3.7: Added the CUSTOM_CONTENT_FROM_VARIABLE option.

Added in version 3.11: Added the INCLUDE_GUARD_NAME option.

add_compiler_export_flags¶

add_compiler_export_flags([])

The add_compiler_export_flags() function adds -fvisibility=hidden toCMAKE_CXX_FLAGS if supported, and is a no-op on Windows which does not need extra compiler flags for exporting support. You may optionally pass a single argument to add_compiler_export_flags()that will be populated with the CXX_FLAGS required to enable visibility support for the compiler/architecture in use.