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 необходимым для включения поддержки видимости для используемого компилятора/архитектуры.