echo/CMake
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Help: Enhance UseSWIG module documentation

Browse Source 
* Add section headings
* Add TOC (HTML only)
* Move `swig_link_libraries()` to "Deprecated commands"
  section at end of docs, document as deprecated in favor of
  `target_link_libraries()` in all cases.
This commit is contained in:
FeRD (Frank Dana) 2022-12-12 04:58:13 -05:00
parent aaf4367371
commit 87778d2da5
1 changed files with 47 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

62
Modules/UseSWIG.cmake
View File

@ -8,7 +8,14 @@ UseSWIG
This file provides support for ``SWIG``. It is assumed that :module:`FindSWIG`
module has already been loaded.
Defines the following command for use with ``SWIG``:
.. only:: html
.. contents::
CMake Commands
^^^^^^^^^^^^^^
The following command is defined for use with ``SWIG``:
.. command:: swig_add_library
@ -125,20 +132,8 @@ Defines the following command for use with ``SWIG``:
to prevent interference between targets or losing other important files,
each target should have its own dedicated output directory.
.. command:: swig_link_libraries
Link libraries to swig module::
swig_link_libraries(<name> <item>...)
This command has same capabilities as :command:`target_link_libraries`
command.
.. note::
If variable ``UseSWIG_TARGET_NAME_PREFERENCE`` is set to ``STANDARD``, this
command is deprecated and :command:`target_link_libraries` command must be
used instead.
Properties on Source Files
^^^^^^^^^^^^^^^^^^^^^^^^^^
Source file properties on module files **must** be set before the invocation
of the ``swig_add_library`` command to specify special behavior of SWIG and
@ -233,6 +228,9 @@ ensure generated files will receive the required settings.
other ways to define output file directory applies (see ``OUTFILE_DIR``
option of ``swig_add_library()`` command).
Properties on Targets
^^^^^^^^^^^^^^^^^^^^^
Target library properties can be set to apply same configuration to all SWIG
input files.
@ -271,6 +269,9 @@ input files.
Add dependencies to all SWIG input files.
Read-only Target Properties
"""""""""""""""""""""""""""
The following target properties are output properties and can be used to get
information about support files generated by ``SWIG`` interface compilation.
@ -303,6 +304,9 @@ information about support files generated by ``SWIG`` interface compilation.
When source property ``OUTPUT_DIR`` is defined, multiple directories can be
specified as part of ``SWIG_SUPPORT_FILES_DIRECTORY``.
CMake Variables
^^^^^^^^^^^^^^^
Some variables can be set to customize the behavior of ``swig_add_library``
as well as ``SWIG``:
@ -361,6 +365,34 @@ as well as ``SWIG``:
.. versionadded:: 3.22
Added the support of :ref:`Visual Studio Generators`.
Deprecated Commands
^^^^^^^^^^^^^^^^^^^
.. command:: swig_link_libraries
.. deprecated:: 3.13
Use :command:`target_link_libraries` with the standard target name,
or with ``${SWIG_MODULE_<name>_REAL_NAME}`` for legacy target naming.
Link libraries to swig module::
swig_link_libraries(<name> <item>...)
This command has same capabilities as :command:`target_link_libraries`
command.
.. note::
When policy :policy:`CMP0078` is set to ``NEW``,
:command:`swig_add_library` creates a standard target with the
specified ``<name>`` and :command:`target_link_libraries` must be used
instead of this command.
With the legacy behavior (when :policy:`CMP0078` is set to ``OLD`` and
the ``UseSWIG_TARGET_NAME_PREFERENCE`` variable is set to ``"LEGACY"``,
or in CMake versions prior to 3.12), it is preferable to use
``target_link_libraries(${SWIG_MODULE_<name>_REAL_NAME} ...)``
instead of this command.
#]=======================================================================]
cmake_policy(PUSH)