GenerateExportHeader¶
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 <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.
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([<output_variable>])
Deprecated since version 3.0: Set the target properties
CXX_VISIBILITY_PRESETandVISIBILITY_INLINES_HIDDENinstead.
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.