importexport.h File Reference

#include <qglobal.h>

Include dependency graph for importexport.h:

Go to the source code of this file.

Macros
#define	PERCEPTUALCOLOR_IMPORTEXPORT   Q_DECL_IMPORT

Detailed Description

This file provides support for C++ symbol import and export.

Definition in file importexport.h.

Macro Definition Documentation

PERCEPTUALCOLOR_IMPORTEXPORT

#define PERCEPTUALCOLOR_IMPORTEXPORT   Q_DECL_IMPORT

A macro that either exports dynamic library symbols or imports dynamic library symbols or does nothing.

This approach is proposed in Qt’s documentation (chapter “Creating Shared Libraries”) – see there for more details. In short:

Build an application using the dynamic library

When your application is build using the dynamic library and includes the header files of the library, the macro imports the corresponding symbols of the library for you by expanding to Qt’s Q_DECL_IMPORT macro. This is the default behaviour of this macro.

Build the dynamic library

When the dynamic library itself is build, the macro exports the corresponding symbol by expanding to Qt’s Q_DECL_EXPORT macro. Exported symbols will be visible symbols in the dynamic library. To get this behaviour, it is necessary to define PERCEPTUALCOLORLIB_BUILD_DYNAMIC_LIBRARY always when this library itself is build.

Build either the static library itself or an application using it

When either

• building the static library itself

or

• your application is build using the static library and includes the header files of the library,

the macro expands to nothing, because for static libraries no import nor export must happen. To get this behaviour, it is necessary to define PERCEPTUALCOLORLIB_STATIC.

CMake code

The definition can be made within CMake:

if(BUILD_SHARED_LIBS)
    target_compile_definitions(
        my_target_name
        PRIVATE PERCEPTUALCOLORLIB_BUILD_DYNAMIC_LIBRARY)
else()
    target_compile_definitions(
        my_target_name
        PUBLIC PERCEPTUALCOLORLIB_STATIC)
endif()

PERCEPTUALCOLORLIB_BUILD_DYNAMIC_LIBRARY is defined PRIVATE, so it only becomes available when building the library itself dynamically, and not when building an application using the dynamic library.

PERCEPTUALCOLORLIB_STATIC however is defined PUBLIC, so it only becomes available both, when building the library itself statically, and also when building an application using the static library.

And you also have to make sure that all symbols that are not explicitly exported will be actually hidden on all platforms:

set_target_properties(
    my_target_name PROPERTIES
    # By default, on Windows all symbols are hidden except those that are
    # explicitly marked for export using the "__declspec(dllexport)"
    # or "__declspec(dllimport)" keywords in the code. On Unix-based systems,
    # however, all symbols are exported by default unless they are explicitly
    # marked as hidden. To achieve the same behavior as on Windows, set
    # the "CXX_VISIBILITY_PRESET" property to "hidden" in CMake to hide all
    # symbols by default, unless they are explicitly marked for export using
    # compiler-specific attributes.
    CXX_VISIBILITY_PRESET "hidden"
    VISIBILITY_INLINES_HIDDEN TRUE)

For your information: The opposite would look like this:

set_target_properties(
    my_target_name PROPERTIES
    # We want all symbols to be publicly available. On Unix-based systems, this
    # is the default behavior, and no additional configuration is required.
    CXX_VISIBILITY_PRESET "default"
    # However, on Windows, all symbols are hidden by default except for those
    # that are explicitly marked for export using "__declspec(dllexport)" or
    # "__declspec(dllimport)" keywords. To achieve the same behavior on Windows
    # as on Unix-based systems, CMake provides the "WINDOWS_EXPORT_ALL_SYMBOLS"
    # property, which can be set to "TRUE" to automatically generate the
    # necessary export symbols for all classes and functions on Windows.
    # However, please note that this option does not work for global variables.
    WINDOWS_EXPORT_ALL_SYMBOLS TRUE
    VISIBILITY_INLINES_HIDDEN FALSE)

Further reading

Note

CMake also offers support for symbol import and export. It can generate a corresponding header by using the generate_export_header() command. However, this is always an additional step and makes the build and install configuration more complex. Furthermore, we produce a second internal library target out of the same source code, which has a different symbol visibility for unit tests. As CMake-generated import-export headers use the name of the target as part of the macro names it defines, this would get complicated. Having our own macro is easier.

CMake’s generate_export_header() command also has portable support for deprecating symbols. However, since C++14 there is [[deprecated(string-literal)]] part of the standard. As we require even C++17 anyway, we can use this as a portable standard instead of CMake’s macros.

See also

https://doc.qt.io/qt-5/sharedlibrary.html#using-symbols-from-shared-libraries

http://anadoxin.org/blog/control-over-symbol-exports-in-gcc.html

https://labjack.com/news/simple-cpp-symbol-visibility-demo

Definition at line 154 of file importexport.h.