Perceptual Color

importexport.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: Lukas Sommer <sommerluk@gmail.com>
2// SPDX-License-Identifier: BSD-2-Clause OR MIT
3
4/** @file importexport.h
5 *
6 * This file provides support for C++ symbol import and export. */
7
8#ifndef IMPORTEXPORT_H
9#define IMPORTEXPORT_H
10
11#include <qglobal.h>
12
13/** @def PERCEPTUALCOLOR_IMPORTEXPORT
14 *
15 * @brief A macro that either exports dynamic library symbols or imports
16 * dynamic library symbols or does nothing.
17 *
18 * This approach is proposed in Qt’s documentation (chapter “Creating
19 * Shared Libraries”) – see there for more details. In short:
20 *
21 * @section buildappdynamic Build an application using the dynamic library
22 *
23 * When your application is build <em>using</em> the dynamic
24 * library and includes the header files of the library, the
25 * macro <em>imports</em> the corresponding symbols of the library
26 * for you by expanding to Qt’s <tt>Q_DECL_IMPORT</tt> macro. This
27 * is the default behaviour of this macro.
28 *
29 * @section buildlibdynamic Build the dynamic library
30 *
31 * When the dynamic library <em>itself</em> is build, the macro
32 * <em>exports</em> the corresponding symbol by expanding to Qt’s
33 * <tt>Q_DECL_EXPORT</tt> macro. Exported symbols will be visible
34 * symbols in the dynamic library. To get this behaviour, it is
35 * necessary to define <tt>PERCEPTUALCOLORLIB_BUILD_DYNAMIC_LIBRARY</tt>
36 * always when this library itself is build.
37 *
38 * @section buildstatic Build either the static library itself or an application using it
39 *
40 * When either
41 *
42 * - building the static library itself
43 *
44 * or
45 *
46 * - your application is build <em>using</em> the static
47 * library and includes the header files of the library,
48 *
49 * the macro expands to <em>nothing</em>, because for static libraries
50 * no import nor export must happen. To get this behaviour, it is
51 * necessary to define <tt>PERCEPTUALCOLORLIB_STATIC</tt>.
52 *
53 * @section cmakeimportexport CMake code
54 *
55 * The definition can be made within CMake:
56 *
57 * @code{.unparsed}
58 * if(BUILD_SHARED_LIBS)
59 * target_compile_definitions(
60 * my_target_name
61 * PRIVATE PERCEPTUALCOLORLIB_BUILD_DYNAMIC_LIBRARY)
62 * else()
63 * target_compile_definitions(
64 * my_target_name
65 * PUBLIC PERCEPTUALCOLORLIB_STATIC)
66 * endif()
67 * @endcode
68 *
69 * <tt>PERCEPTUALCOLORLIB_BUILD_DYNAMIC_LIBRARY</tt> is defined
70 * <tt>PRIVATE</tt>, so it only becomes available when building
71 * the library <em>itself</em> dynamically, and not when building
72 * an application <em>using</em> the dynamic library.
73 *
74 * <tt>PERCEPTUALCOLORLIB_STATIC</tt> however is defined
75 * <tt>PUBLIC</tt>, so it only becomes available both, when building
76 * the library <em>itself</em> statically, and also when building
77 * an application <em>using</em> the static library.
78 *
79 * And you also have to make sure that all symbols that are <em>not</em>
80 * explicitly exported will be actually hidden on all platforms:
81 *
82 * @code{.unparsed}
83 * set_target_properties(
84 * my_target_name PROPERTIES
85 * # By default, on Windows all symbols are hidden except those that are
86 * # explicitly marked for export using the "__declspec(dllexport)"
87 * # or "__declspec(dllimport)" keywords in the code. On Unix-based systems,
88 * # however, all symbols are exported by default unless they are explicitly
89 * # marked as hidden. To achieve the same behavior as on Windows, set
90 * # the "CXX_VISIBILITY_PRESET" property to "hidden" in CMake to hide all
91 * # symbols by default, unless they are explicitly marked for export using
92 * # compiler-specific attributes.
93 * CXX_VISIBILITY_PRESET "hidden"
94 * VISIBILITY_INLINES_HIDDEN TRUE)
95 * @endcode
96 *
97 * For your information: The opposite would look like this:
98 *
99 * @code{.unparsed}
100 * set_target_properties(
101 * my_target_name PROPERTIES
102 * # We want all symbols to be publicly available. On Unix-based systems, this
103 * # is the default behavior, and no additional configuration is required.
104 * CXX_VISIBILITY_PRESET "default"
105 * # However, on Windows, all symbols are hidden by default except for those
106 * # that are explicitly marked for export using "__declspec(dllexport)" or
107 * # "__declspec(dllimport)" keywords. To achieve the same behavior on Windows
108 * # as on Unix-based systems, CMake provides the "WINDOWS_EXPORT_ALL_SYMBOLS"
109 * # property, which can be set to "TRUE" to automatically generate the
110 * # necessary export symbols for all classes and functions on Windows.
111 * # However, please note that this option does not work for global variables.
112 * WINDOWS_EXPORT_ALL_SYMBOLS TRUE
113 * VISIBILITY_INLINES_HIDDEN FALSE)
114 * @endcode
115 *
116 * @section importexportlinks Further reading
117 *
118 * @note CMake also offers support for symbol import and export.
119 * It can generate a corresponding header by using the <tt><a
120 * href="https://cmake.org/cmake/help/latest/module/GenerateExportHeader.html">
121 * generate_export_header()</a></tt> command. However, this is always
122 * an additional step and makes the build and install configuration
123 * more complex. Furthermore, we produce a second internal library
124 * target out of the same source code, which has a different symbol
125 * visibility for unit tests. As CMake-generated import-export headers
126 * use the name of the target as part of the macro names it defines, this
127 * would get complicated. Having our own macro is easier.
128 *
129 * @note CMake’s <a
130 * href="https://cmake.org/cmake/help/latest/module/GenerateExportHeader.html">
131 * <tt>generate_export_header()</tt></a> command also has portable
132 * support for deprecating symbols. However, since C++14 there is
133 * <a href="https://en.cppreference.com/w/cpp/language/attributes/deprecated">
134 * <tt>[[deprecated(string-literal)]]</tt></a> part of the standard.
135 * As we require even C++17 anyway, we can use this as a portable standard
136 * instead of CMake’s macros.
137 *
138 * @sa https://doc.qt.io/qt-5/sharedlibrary.html#using-symbols-from-shared-libraries
139 * @sa http://anadoxin.org/blog/control-over-symbol-exports-in-gcc.html
140 * @sa https://labjack.com/news/simple-cpp-symbol-visibility-demo */
141
142#ifdef PERCEPTUALCOLORLIB_STATIC
143
144#ifndef PERCEPTUALCOLOR_IMPORTEXPORT
145#define PERCEPTUALCOLOR_IMPORTEXPORT
146#endif
147
148#else
149
150#ifndef PERCEPTUALCOLOR_IMPORTEXPORT
151#ifdef PERCEPTUALCOLORLIB_BUILD_DYNAMIC_LIBRARY
152#define PERCEPTUALCOLOR_IMPORTEXPORT Q_DECL_EXPORT
153#else
154#define PERCEPTUALCOLOR_IMPORTEXPORT Q_DECL_IMPORT
155#endif
156#endif
157
158#endif
159
160#endif // IMPORTEXPORT_H
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri May 24 2024 11:48:43 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.