Export SWIG interface files for downstream usage

This allows *other* C++/Fortran codes to integrate their standard library
usage with Flibcpp's Fortran proxy types.

Author: sethrj

CMakeLists.txt

@@ -103,18 +103,21 @@ configure_file("${CMAKE_CURRENT_SOURCE_DIR}/cmake/flibcpp_version.cpp.in"
 include(GNUInstallDirs)
 
 set(CMAKE_Fortran_MODULE_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/module")
-set(FLIBCPP_GENERATE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/src/generated")
+set(FLIBCPP_INTERFACE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/include")
+set(FLIBCPP_GENERATE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/src")
 set(FLIBCPP_INSTALL_CONFIGDIR "${CMAKE_INSTALL_LIBDIR}/cmake/Flibcpp")
 set(FLIBCPP_INSTALL_MODULEDIR "${CMAKE_INSTALL_INCLUDEDIR}")
 set(FLIBCPP_NAMESPACE Flibcpp::)
 
+# List of libraries exported by cmake/FlibcppConfig.cmake.in
 set(FLIBCPP_LIBRARIES)
 
 function(swig_fortran_add_module name)
+  set(src_file "${FLIBCPP_INTERFACE_DIR}/${name}.i")
   # We're using C++
-  set_property(SOURCE src/${name}.i PROPERTY CPLUSPLUS ON)
+  set_property(SOURCE "${src_file}" PROPERTY CPLUSPLUS ON)
   # We need to include the source directory
-  set_property(SOURCE src/${name}.i PROPERTY USE_TARGET_INCLUDE_DIRECTORIES ON)
+  set_property(SOURCE "${src_file}" PROPERTY USE_TARGET_INCLUDE_DIRECTORIES ON)
 
   if (FLIBCPP_USE_SWIG)
     # SWIG is available; actually generate the library dynamically.
@@ -123,8 +126,22 @@ function(swig_fortran_add_module name)
       LANGUAGE Fortran
       TYPE USE_BUILD_SHARED_LIBS
       OUTPUT_DIR "${FLIBCPP_GENERATE_DIR}"
-      SOURCES src/${name}.i ${ARGN}
+      SOURCES "${src_file}" ${ARGN}
     )
+
+    # Add SWIG headers
+    target_include_directories(${name}
+      PUBLIC
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+        $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
+    )
+
+    # Install the interface file for downstream libraries to use
+    install(FILES
+      "${src_file}"
+      DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
+    )
+
   else()
     # SWIG is *not* being used: compile the code committed in the repository,
     # generated by the developer with SWIG.
@@ -142,30 +159,36 @@ function(swig_fortran_add_module name)
   )
 
   target_include_directories(${name}
-    PRIVATE
-      # Internal C++ headers
-      $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/src>
     PUBLIC
       # Fortran modules
       $<BUILD_INTERFACE:${CMAKE_Fortran_MODULE_DIRECTORY}>
       $<INSTALL_INTERFACE:${FLIBCPP_INSTALL_MODULEDIR}>
   )
 
   # Set up installation
-  install(TARGETS ${name}
+  install(TARGETS
+    ${name}
     EXPORT Flibcpp-targets
     LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
     ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
   )
   # Add to list of targets to export
   set(FLIBCPP_LIBRARIES ${FLIBCPP_LIBRARIES} ${FLIBCPP_NAMESPACE}${name}
-      PARENT_SCOPE
+    PARENT_SCOPE
   )
 endfunction()
 
-# Four SWIG libraries
+# Install primary flc module, compiling version info as well
 swig_fortran_add_module(flc "${FLIBCPP_VERSION_CPP}")
 
+# Also install 'import_flc' if using SWIG
+if (FLIBCPP_USE_SWIG)
+  install(FILES
+    "${CMAKE_CURRENT_SOURCE_DIR}/include/import_flc.i"
+    DESTINATION "${CMAKE_INSTALL_INCLUDEDIR}"
+  )
+endif()
+
 swig_fortran_add_module(flc_algorithm)
 target_link_libraries(flc_algorithm flc_random flc)
 
@@ -183,7 +206,8 @@ target_link_libraries(flc_vector flc flc_string)
 #---------------------------------------------------------------------------#
 
 # Install module files
-install(DIRECTORY "${CMAKE_Fortran_MODULE_DIRECTORY}/"
+install(DIRECTORY
+  "${CMAKE_Fortran_MODULE_DIRECTORY}/"
   DESTINATION "${FLIBCPP_INSTALL_MODULEDIR}"
 )
 
@@ -197,20 +221,20 @@ install(EXPORT Flibcpp-targets
 include(CMakePackageConfigHelpers)
 
 configure_package_config_file(
-  ${CMAKE_CURRENT_LIST_DIR}/cmake/FlibcppConfig.cmake.in
-  ${CMAKE_CURRENT_BINARY_DIR}/FlibcppConfig.cmake
+  "${CMAKE_CURRENT_SOURCE_DIR}/cmake/FlibcppConfig.cmake.in"
+  "${CMAKE_CURRENT_BINARY_DIR}/FlibcppConfig.cmake"
   INSTALL_DESTINATION ${FLIBCPP_INSTALL_CONFIGDIR}
 )
 
 write_basic_package_version_file(
-  ${CMAKE_CURRENT_BINARY_DIR}/FlibcppConfigVersion.cmake
+  "${CMAKE_CURRENT_BINARY_DIR}/FlibcppConfigVersion.cmake"
   VERSION ${PROJECT_VERSION}
   COMPATIBILITY SameMajorVersion
 )
 
-install(
-  FILES ${CMAKE_CURRENT_BINARY_DIR}/FlibcppConfig.cmake
-        ${CMAKE_CURRENT_BINARY_DIR}/FlibcppConfigVersion.cmake
+install(FILES
+  "${CMAKE_CURRENT_BINARY_DIR}/FlibcppConfig.cmake"
+  "${CMAKE_CURRENT_BINARY_DIR}/FlibcppConfigVersion.cmake"
   DESTINATION ${FLIBCPP_INSTALL_CONFIGDIR}
 )
 

doc/interface.rst

@@ -15,37 +15,37 @@ flc
 
 The primary file defines typemaps.
 
-.. literalinclude:: ../src/flc.i
+.. literalinclude:: ../include/flc.i
    :linenos:
 
 flc_algorithm
 =============
 
-.. literalinclude:: ../src/flc_algorithm.i
+.. literalinclude:: ../include/flc_algorithm.i
    :linenos:
 
 flc_chrono
 =============
 
-.. literalinclude:: ../src/flc_chrono.i
+.. literalinclude:: ../include/flc_chrono.i
    :linenos:
 
 flc_random
 =============
 
-.. literalinclude:: ../src/flc_random.i
+.. literalinclude:: ../include/flc_random.i
    :linenos:
 
 flc_string
 =============
 
-.. literalinclude:: ../src/flc_string.i
+.. literalinclude:: ../include/flc_string.i
    :linenos:
 
 flc_vector
 =============
 
-.. literalinclude:: ../src/flc_vector.i
+.. literalinclude:: ../include/flc_vector.i
    :linenos:
 
 .. ############################################################################

doc/introduction.rst

@@ -34,8 +34,8 @@ By default, Flibcpp builds shared libraries. Add the CMake argument
 .. _YUM: https://access.redhat.com/solutions/9934
 .. _Flibcpp source code: https://github.com/swig-fortran/flibcpp/releases
 
-Downstream usage
-================
+Downstream usage as a library
+=============================
 
 The Flibcpp library is most easily used when your downstream app is built with
 CMake. It should require a single line to initialize::
@@ -63,6 +63,32 @@ library names. Depending on your system configuration, you might have to
 also explicitly link your app against the compiler's C++ standard libraries
 using ``-lstdc++``.
 
+Downstream usage as a component
+===============================
+
+Flibcpp's SWIG interface files can be used with your Fortran-accessible
+C++ project to seamlessly integrate the Flibcpp Fortran wrapper code with
+yours. To start, you must have the latest version of the `SWIG+Fortran`_ tool
+installed on your machine: the version of SWIG used by your installation of
+Flibcpp *must* match the version used by your downstream library/app. When you
+build Flibcpp for downstream SWIG usage, you must configure using ``cmake
+-DFLIBCPP_USE_SWIG=ON ..``. This will cause the SWIG interface files to be
+installed to ``${CMAKE_PREFIX_PATH}/include`` to make them available
+downstream. Finally, in your downstream SWIG interface code, instead of calling
+``%import <flc.i>`` you must use ``%include <import_flc.i>``. This is necessary
+to inject function declarations and other internal macros into your wrapper
+code.
+
+At that point, all you have to do is (for example) ``%import <flc_vector>`` to
+allow ``std::vector<double>`` in your library headers to be wrapped by
+Flibcpp's ``VectorReal8`` Fortran proxy derived type.
+
+An `example C++/Fortran library`_ that integrates with Flibcpp will be made
+available on Github.
+
+.. _SWIG+Fortran: https://github.com/swig-fortran
+.. _example C++/Fortran library: https://github.com/swig-fortran/flibcpp-example-lib).
+
 Developing
 ==========
 
@@ -74,8 +100,6 @@ examples, and documentation can be independently enabled using the
 ``FLIBCPP_BUILD_TESTS``, ``FLIBCPP_BUILD_EXAMPLES``, and ``FLIBCPP_BUILD_DOCS``
 options.
 
-.. _SWIG+Fortran: https://github.com/swig-fortran
-
 .. ############################################################################
 .. end of doc/introduction.rst
 .. ############################################################################