From ce130c7a6bce84a9af3859c6f58a8d6c9f16afc7 Mon Sep 17 00:00:00 2001 From: Brad King Date: Wed, 31 Jan 2018 13:55:22 -0500 Subject: UseSWIG: Convert docs to a bracket comment --- Modules/UseSWIG.cmake | 105 +++++++++++++++++++++++++------------------------- 1 file changed, 53 insertions(+), 52 deletions(-) diff --git a/Modules/UseSWIG.cmake b/Modules/UseSWIG.cmake index b8bcd92..91f9cf7 100644 --- a/Modules/UseSWIG.cmake +++ b/Modules/UseSWIG.cmake @@ -1,58 +1,59 @@ # Distributed under the OSI-approved BSD 3-Clause License. See accompanying # file Copyright.txt or https://cmake.org/licensing for details. -#.rst: -# UseSWIG -# ------- -# -# Defines the following macros for use with SWIG: -# -# :: -# -# SWIG_ADD_LIBRARY( -# [TYPE ] -# LANGUAGE -# SOURCES ... -# ) -# - Define swig module with given name and specified language -# SWIG_LINK_LIBRARIES(name [ libraries ]) -# - Link libraries to swig module -# -# Source files properties on module files can be set before the invocation -# of the SWIG_ADD_LIBRARY macro to specify special behavior of SWIG. -# -# The source file property CPLUSPLUS calls SWIG in c++ mode, e.g.:: -# -# set_property(SOURCE mymod.i PROPERTY CPLUSPLUS ON) -# swig_add_library(mymod LANGUAGE python SOURCES mymod.i) -# -# The source file property SWIG_FLAGS adds custom flags to the SWIG executable. -# -# The source-file property SWIG_MODULE_NAME have to be provided to specify the actual -# import name of the module in the target language if it cannot be scanned automatically -# from source or different from the module file basename.:: -# -# set_property(SOURCE mymod.i PROPERTY SWIG_MODULE_NAME mymod_realname) -# -# To get the name of the swig module target library, use: ${SWIG_MODULE_${name}_REAL_NAME}. -# -# Also some variables can be set to specify special behavior of SWIG. -# -# CMAKE_SWIG_FLAGS can be used to add special flags to all swig calls. -# -# CMAKE_SWIG_OUTDIR allows one to specify where to write -# the language specific files (swig -outdir option). -# -# SWIG_OUTFILE_DIR allows one to specify where to write the output file -# (swig -o option). If not specified, CMAKE_SWIG_OUTDIR is used. -# -# The name-specific variable SWIG_MODULE__EXTRA_DEPS may be used to specify extra -# dependencies for the generated modules. -# -# If the source file generated by swig need some special flag you can use:: -# -# set_source_files_properties( ${swig_generated_file_fullname} -# PROPERTIES COMPILE_FLAGS "-bla") +#[=======================================================================[.rst: +UseSWIG +------- + +Defines the following macros for use with SWIG: + +:: + + SWIG_ADD_LIBRARY( + [TYPE ] + LANGUAGE + SOURCES ... + ) + - Define swig module with given name and specified language + SWIG_LINK_LIBRARIES(name [ libraries ]) + - Link libraries to swig module + +Source files properties on module files can be set before the invocation +of the SWIG_ADD_LIBRARY macro to specify special behavior of SWIG. + +The source file property CPLUSPLUS calls SWIG in c++ mode, e.g.:: + + set_property(SOURCE mymod.i PROPERTY CPLUSPLUS ON) + swig_add_library(mymod LANGUAGE python SOURCES mymod.i) + +The source file property SWIG_FLAGS adds custom flags to the SWIG executable. + +The source-file property SWIG_MODULE_NAME have to be provided to specify the actual +import name of the module in the target language if it cannot be scanned automatically +from source or different from the module file basename.:: + + set_property(SOURCE mymod.i PROPERTY SWIG_MODULE_NAME mymod_realname) + +To get the name of the swig module target library, use: ${SWIG_MODULE_${name}_REAL_NAME}. + +Also some variables can be set to specify special behavior of SWIG. + +CMAKE_SWIG_FLAGS can be used to add special flags to all swig calls. + +CMAKE_SWIG_OUTDIR allows one to specify where to write +the language specific files (swig -outdir option). + +SWIG_OUTFILE_DIR allows one to specify where to write the output file +(swig -o option). If not specified, CMAKE_SWIG_OUTDIR is used. + +The name-specific variable SWIG_MODULE__EXTRA_DEPS may be used to specify extra +dependencies for the generated modules. + +If the source file generated by swig need some special flag you can use:: + + set_source_files_properties( ${swig_generated_file_fullname} + PROPERTIES COMPILE_FLAGS "-bla") +#]=======================================================================] set(SWIG_CXX_EXTENSION "cxx") set(SWIG_EXTRA_LIBRARIES "") -- cgit v0.12 From 315b0927e951019b43714f654f7b039b32ae14a9 Mon Sep 17 00:00:00 2001 From: Brad King Date: Wed, 31 Jan 2018 14:09:19 -0500 Subject: UseSWIG: Improve documentation markup --- Modules/UseSWIG.cmake | 73 +++++++++++++++++++++++++++++---------------------- 1 file changed, 42 insertions(+), 31 deletions(-) diff --git a/Modules/UseSWIG.cmake b/Modules/UseSWIG.cmake index 91f9cf7..9a6d046 100644 --- a/Modules/UseSWIG.cmake +++ b/Modules/UseSWIG.cmake @@ -7,52 +7,63 @@ UseSWIG Defines the following macros for use with SWIG: -:: +.. command:: swig_add_library - SWIG_ADD_LIBRARY( - [TYPE ] - LANGUAGE - SOURCES ... - ) - - Define swig module with given name and specified language - SWIG_LINK_LIBRARIES(name [ libraries ]) - - Link libraries to swig module + Define swig module with given name and specified language:: -Source files properties on module files can be set before the invocation -of the SWIG_ADD_LIBRARY macro to specify special behavior of SWIG. + swig_add_library( + [TYPE ] + LANGUAGE + SOURCES ... + ) -The source file property CPLUSPLUS calls SWIG in c++ mode, e.g.:: + The variable ``SWIG_MODULE__REAL_NAME`` will be set to the name + of the swig module target library. - set_property(SOURCE mymod.i PROPERTY CPLUSPLUS ON) - swig_add_library(mymod LANGUAGE python SOURCES mymod.i) +.. command:: swig_link_libraries -The source file property SWIG_FLAGS adds custom flags to the SWIG executable. + Link libraries to swig module:: -The source-file property SWIG_MODULE_NAME have to be provided to specify the actual -import name of the module in the target language if it cannot be scanned automatically -from source or different from the module file basename.:: + swig_link_libraries( [ libraries ]) - set_property(SOURCE mymod.i PROPERTY SWIG_MODULE_NAME mymod_realname) +Source file properties on module files can be set before the invocation +of the ``swig_add_library`` macro to specify special behavior of SWIG: -To get the name of the swig module target library, use: ${SWIG_MODULE_${name}_REAL_NAME}. +``CPLUSPLUS`` + Call SWIG in c++ mode. For example: -Also some variables can be set to specify special behavior of SWIG. + .. code-block:: cmake -CMAKE_SWIG_FLAGS can be used to add special flags to all swig calls. + set_property(SOURCE mymod.i PROPERTY CPLUSPLUS ON) + swig_add_library(mymod LANGUAGE python SOURCES mymod.i) -CMAKE_SWIG_OUTDIR allows one to specify where to write -the language specific files (swig -outdir option). +``SWIG_FLAGS`` + Add custom flags to the SWIG executable. -SWIG_OUTFILE_DIR allows one to specify where to write the output file -(swig -o option). If not specified, CMAKE_SWIG_OUTDIR is used. -The name-specific variable SWIG_MODULE__EXTRA_DEPS may be used to specify extra -dependencies for the generated modules. +``SWIG_MODULE_NAME`` + Specify the actual import name of the module in the target language. + This is required if it cannot be scanned automatically from source + or different from the module file basename. For example: -If the source file generated by swig need some special flag you can use:: + .. code-block:: cmake - set_source_files_properties( ${swig_generated_file_fullname} - PROPERTIES COMPILE_FLAGS "-bla") + set_property(SOURCE mymod.i PROPERTY SWIG_MODULE_NAME mymod_realname) + +Some variables can be set to specify special behavior of SWIG: + +``CMAKE_SWIG_FLAGS`` + Add flags to all swig calls. + +``CMAKE_SWIG_OUTDIR`` + Specify where to write the language specific files (swig ``-outdir`` option). + +``SWIG_OUTFILE_DIR`` + Specify where to write the output file (swig ``-o`` option). + If not specified, ``CMAKE_SWIG_OUTDIR`` is used. + +``SWIG_MODULE__EXTRA_DEPS`` + Specify extra dependencies for the generated module for ````. #]=======================================================================] set(SWIG_CXX_EXTENSION "cxx") -- cgit v0.12 From b844a414c7c0e7b32a43e14b71f30088ec473f46 Mon Sep 17 00:00:00 2001 From: Noel Eck Date: Wed, 31 Jan 2018 10:49:32 -0800 Subject: UseSWIG: Clarify documentation of SWIG_OUTFILE_DIR The `SWIG_OUTFILE_DIR` variable provides the option to specify an output directory location. This commit removes portion stating that this is equal to the `swig -o` option since it does not set the output filename. Fixes: #17703 Signed-off-by: Noel Eck --- Modules/UseSWIG.cmake | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Modules/UseSWIG.cmake b/Modules/UseSWIG.cmake index 9a6d046..b38e2b7 100644 --- a/Modules/UseSWIG.cmake +++ b/Modules/UseSWIG.cmake @@ -59,8 +59,8 @@ Some variables can be set to specify special behavior of SWIG: Specify where to write the language specific files (swig ``-outdir`` option). ``SWIG_OUTFILE_DIR`` - Specify where to write the output file (swig ``-o`` option). - If not specified, ``CMAKE_SWIG_OUTDIR`` is used. + Specify an output directory name where the generated source file will be + placed. If not specified, ``CMAKE_SWIG_OUTDIR`` is used. ``SWIG_MODULE__EXTRA_DEPS`` Specify extra dependencies for the generated module for ````. -- cgit v0.12