GenerateExportHeader

Функция для генерации макросов экспорта для библиотек

Этот модуль предоставляет функцию GENERATE_EXPORT_HEADER().

Функция GENERATE_EXPORT_HEADER может быть использована для генерации файла, подходящего для включения препроцессором, который содержит макросы EXPORT, которые будут использоваться в классах библиотек:

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>]
)

Целевые свойства CXX_VISIBILITY_PRESET и VISIBILITY_INLINES_HIDDEN могут быть использованы для добавления соответствующих флагов компиляции для целей. Смотрите документацию этих целевых свойств и удобные переменные CMAKE_CXX_VISIBILITY_PRESET и CMAKE_VISIBILITY_INLINES_HIDDEN.

По умолчанию GENERATE_EXPORT_HEADER() генерирует имена макросов в файле, имя которого определяется именем библиотеки. Это означает, что в простейшем случае, пользователи GenerateExportHeader будут эквивалентны:

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}
)

А в заголовочных файлах ABI:

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

Фрагмент CMake сгенерирует файл в ${CMAKE_CURRENT_BINARY_DIR} под названием somelib_export.h, содержащий макросы SOMELIB_EXPORT, SOMELIB_NO_EXPORT, SOMELIB_DEPRECATED, SOMELIB_DEPRECATED_EXPORT и SOMELIB_DEPRECATED_NO_EXPORT. За ними последуют данные, взятые из переменной, указанной опцией CUSTOM_CONTENT_FROM_VARIABLE , если таковая имеется. Результирующий файл должен быть установлен вместе с другими заголовками в библиотеке.

Аргумент BASE_NAME может быть использован для переопределения имени файла и имен, используемых для макросов:

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

Генерирует файл под названием other_name_export.h, содержащий макросы OTHER_NAME_EXPORT, OTHER_NAME_NO_EXPORT и OTHER_NAME_DEPRECATED и т. д.

BASE_NAME может быть переопределено путем указания других опций в функции. Например:

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

создает макрос OTHER_NAME_EXPORT вместо SOMELIB_EXPORT, но другие макросы и имя генерируемого файла остаются по умолчанию:

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

создает макрос KDE_DEPRECATED вместо SOMELIB_DEPRECATED.

Если LIBRARY_TARGET является статической библиотекой, макросы определяются без значений.

Если одни и те же исходные файлы используются для создания как динамической, так и статической библиотеки, при построении статической библиотеки следует использовать заглавную переменную ${BASE_NAME}_STATIC_DEFINE:

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)

Это приведет к тому, что макросы экспорта будут расширяться до ничего при построении статической библиотеки.

Если указано DEFINE_NO_DEPRECATED, то будет определён макрос ${BASE_NAME}_NO_DEPRECATED. Этот макрос может быть использован для удаления устаревшего кода из вывода препроцессора:

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})

А затем в somelib:

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

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

Если указано PREFIX_NAME, аргумент будет использован в качестве префикса ко всем сгенерированным макросам.

Например:

generate_export_header(somelib PREFIX_NAME VTK_)

Генерирует макросы VTK_SOMELIB_EXPORT и т. д.

ADD_COMPILER_EXPORT_FLAGS( [<output_variable>] )

Функция ADD_COMPILER_EXPORT_FLAGS добавляет -fvisibility=hidden в CMAKE_CXX_FLAGS, если это поддерживается, и является пустой операцией в Windows, которая не нуждается в дополнительных флагах компилятора для поддержки экспорта. Вы можете необязательно передать единственный аргумент функции ADD_COMPILER_EXPORT_FLAGS, который будет заполнен CXX_FLAGS необходимым для включения поддержки видимости для используемого компилятора/архитектуры.

Эта функция устарела. Вместо этого установите целевые свойства CXX_VISIBILITY_PRESET и VISIBILITY_INLINES_HIDDEN.