Function for generation of export macros for libraries
This module provides the function 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 <base_name>] [EXPORT_MACRO_NAME <export_macro_name>] [EXPORT_FILE_NAME <export_file_name>] [DEPRECATED_MACRO_NAME <deprecated_macro_name>] [NO_EXPORT_MACRO_NAME <no_export_macro_name>] [INCLUDE_GUARD_NAME <include_guard_name>] [STATIC_DEFINE <static_define>] [NO_DEPRECATED_MACRO_NAME <no_deprecated_macro_name>] [DEFINE_NO_DEPRECATED] [PREFIX_NAME <prefix_name>] [CUSTOM_CONTENT_FROM_VARIABLE <variable>] )
The target properties CXX_VISIBILITY_PRESET
and VISIBILITY_INLINES_HIDDEN
can be used to add the appropriate compile flags for targets. See the documentation of those target properties, and the convenience variables CMAKE_CXX_VISIBILITY_PRESET
and CMAKE_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 ${PROJECT_BINARY_DIR}/somelib_export.h DESTINATION ${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 macros OTHER_NAME_EXPORT
, OTHER_NAME_NO_EXPORT
and OTHER_NAME_DEPRECATED
etc.
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.
ADD_COMPILER_EXPORT_FLAGS( [<output_variable>] )
The ADD_COMPILER_EXPORT_FLAGS
function adds -fvisibility=hidden
to CMAKE_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.
This function is deprecated. Set the target properties CXX_VISIBILITY_PRESET
and VISIBILITY_INLINES_HIDDEN
instead.
© 2000–2020 Kitware, Inc. and Contributors
Licensed under the BSD 3-clause License.
https://cmake.org/cmake/help/v3.19/module/GenerateExportHeader.html