diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst index 61413f1824..e9b90fb17c 100644 --- a/Help/manual/cmake-buildsystem.7.rst +++ b/Help/manual/cmake-buildsystem.7.rst @@ -404,9 +404,14 @@ for compiling a target. These are passed to the compiler with ``-D`` flags, or equivalent, in an unspecified order. - The :prop_tgt:`DEFINE_SYMBOL` target property is also used - as a compile definition as a special convenience case for - ``SHARED`` and ``MODULE`` library targets. + When compiling sources of a ``SHARED`` library, a ``MODULE`` library, + or an ``EXECUTABLE`` with :prop_tgt:`ENABLE_EXPORTS` enabled, CMake + automatically defines a target-specific preprocessor symbol. + By default the definition is of the form ``_EXPORTS``, but it + can be overridden by the :prop_tgt:`DEFINE_SYMBOL` target property. + This allows headers to detect whether they are included from inside + their implementation sources, and to correctly set up export/import + annotations or visibility of symbols. :prop_tgt:`COMPILE_OPTIONS` List of compile options for compiling sources in the target. diff --git a/Help/prop_tgt/DEFINE_SYMBOL.rst b/Help/prop_tgt/DEFINE_SYMBOL.rst index 775cf898cb..6cd6472859 100644 --- a/Help/prop_tgt/DEFINE_SYMBOL.rst +++ b/Help/prop_tgt/DEFINE_SYMBOL.rst @@ -1,17 +1,21 @@ DEFINE_SYMBOL ------------- -Define a symbol when compiling this target's sources. +Define a preprocessor symbol when compiling this target's sources. -``DEFINE_SYMBOL`` sets the name of the preprocessor symbol defined when -compiling sources in a shared library. If not set here then it is set -to ``target_EXPORTS`` by default (with some substitutions if the target is -not a valid C identifier). This is useful for headers to know whether -they are being included from inside their library or outside to -properly setup dllexport/dllimport decorations on Windows. +CMake adds this definition when compiling sources of a ``SHARED`` library, +a ``MODULE`` library, or an ``EXECUTABLE`` with :prop_tgt:`ENABLE_EXPORTS` +enabled. If ``DEFINE_SYMBOL`` is not set, the default definition is of +the form ``_EXPORTS`` (with some substitutions if the target is +not a valid C identifier). + +The symbol is only defined while compiling the target itself and is not +propagated to dependent targets. On POSIX platforms, this can optionally be used to control the visibility of symbols. CMake provides support for such decorations with the :module:`GenerateExportHeader` module. + +See also the ``COMPILE_DEFINITIONS`` under :ref:`Target Compile Properties`.