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