add cpp_fort_and_py example and related docs (#735)

* add cpp_fort_and_py example and related docs

* add azure test for cpp fort and py ex

CHANGELOG.md

@@ -9,10 +9,13 @@ and this project aspires to adhere to [Semantic Versioning](https://semver.org/s
 ### Added
 
 #### General
+- Added the `cpp_fort_and_py` standalone example. It demos passing Conduit Nodes between C++, Fortran, and Python. See the related tutorial docs (https://llnl-conduit.readthedocs.io/en/latest/tutorial_cpp_fort_and_py.html) for more details.
 - Added  `conduit::utils::info_handler()`, `conduit::utils::warning_handler()`, and `conduit::utils::error_handler()`  methods, which provide access to the currently registered info, warning, and error handlers.
 - Added DataType::index_t method. Creates a DataType instance that describes an `index_t`, which is an alias to either `int32`, or `int 64` controlled by the `CONDUIT_INDEX_32` compile time option.
 - Added several more methods to Python DataType interface
 
+
+
 #### Relay
 - Added Relay HDF5 support for reading and writing to an HDF5 dataset with offset.
 - Added `conduit::relay::io::hdf5::read_info` which allows you to obtain metadata from an HDF5 file.

azure-pipelines.yml

@@ -547,6 +547,38 @@ stages:
           ./conduit_example
         displayName: 'Test vs Install (using-with-make)'
 
+      - script: |
+          ################################
+          # cpp fort and py example
+          ################################
+          # only run this when python is enabled
+          # (there might be a better way to do this with an azure `condition:` stmt)
+          if [ $ENABLE_PYTHON = 'OFF' ]; then exit 0; fi
+          pwd
+          ls -l
+          # find spack installed cmake
+          export ROOT_DIR=`pwd`
+          export CMAKE_BIN_DIR=`ls -d ${ROOT_DIR}/uberenv_libs/spack/opt/spack/*/*/cmake*/bin`
+          export PATH=${CMAKE_BIN_DIR}:$PATH
+          echo $PATH
+          # find spack installed python
+          export PYTHON_EXE=`ls -d ${ROOT_DIR}/uberenv_libs/spack/opt/spack/*/*/python*/bin/python`
+          # add conduit module to python path
+          export PYTHONPATH=${ROOT_DIR}/install/python-modules/
+          echo $PYTHONPATH
+          which cmake
+          # lets build
+          cd install/examples/conduit/cpp_fort_and_py
+          mkdir _test_build
+          cd _test_build
+          cmake -DCONDUIT_DIR=${ROOT_DIR}/install  -DPYTHON_EXECUTABLE=${PYTHON_EXE} ../
+          make VERBOSE=1
+          # lets run!
+          ./conduit_cpp_and_py_ex
+          ./conduit_fort_and_py_ex
+        displayName: 'Test vs Install (cpp_fort_and_py)'
+        
+
   ###############################################################################
   # Docker build and test case, that leverages our script that calls Docker Build
   ###############################################################################

src/docs/sphinx/conduit.rst

@@ -11,5 +11,6 @@ Conduit
 
    tutorial_cpp
    tutorial_python
+   tutorial_cpp_fort_and_py
 
 ..    conduit_api

src/examples/CMakeLists.txt

@@ -11,5 +11,8 @@
 add_subdirectory(staging)
 
 # install using and python examples
-install(DIRECTORY using-with-cmake using-with-make python
+install(DIRECTORY using-with-cmake
+                  using-with-make
+                  python
+                  cpp_fort_and_py
         DESTINATION examples/conduit)

src/examples/cpp_fort_and_py/CMakeLists.txt

@@ -0,0 +1,106 @@
+# Copyright (c) Lawrence Livermore National Security, LLC and other Conduit
+# Project developers. See top-level LICENSE AND COPYRIGHT files for dates and
+# other details. No copyright assignment is required to contribute to Conduit.
+###############################################################################
+#
+# Example that shows how to use Conduit across C++, Fortran, and an
+# embedded Python interpreter.
+#
+#
+# Building:
+#
+# Note: The python instance must have the conduit python module installed
+# or it must be in your PYTHONPATH.
+#
+# > mkdir build
+# > cd build
+# 
+# # if conduit python module is not installed in your python instance
+# # > export PYTHONPATH=/path/to/conduit-install/python-modules
+#
+# > cmake  \
+#    -DCONDUIT_DIR=/path/to/conduit/install
+#    -DPYTHON_EXECUTABLE=/path/to/python/bin/python
+#    ../
+# > make
+#
+#
+# Running:
+# > ./conduit_cpp_and_py_ex
+# > ./conduit_fort_and_py_ex
+#
+# # if conduit python module is not installed in your python instance
+# > env PYTHONPATH=/path/to/conduit-install/python-modules  ./conduit_cpp_and_py_ex
+# > env PYTHONPATH=/path/to/conduit-install/python-modules  ./conduit_fort_and_py_ex
+###############################################################################
+
+cmake_minimum_required(VERSION 3.0)
+
+project(conduit_cpp_fort_and_py C CXX Fortran)
+
+
+######
+# Setup Conduit
+######
+find_package(Conduit REQUIRED
+             NO_DEFAULT_PATH 
+             PATHS ${CONDUIT_DIR}/lib/cmake/conduit)
+
+######
+# Setup Python
+######
+include(SetupPython.cmake)
+
+######
+# If Conduit was built with c++11 support, make sure we enable it
+# for our project.
+######
+if(CONDUIT_USE_CXX11)
+    set(CMAKE_CXX_STANDARD 11)
+    set(CMAKE_CXX_STANDARD_REQUIRED ON)
+endif()
+
+
+##############################################################################
+# cpp to and from fortran example
+##############################################################################
+add_executable(conduit_cpp_and_py_ex
+               conduit_cpp_and_py_ex.cpp
+               python_interpreter.hpp
+               python_interpreter.cpp)
+
+target_link_libraries(conduit_cpp_and_py_ex
+                      conduit::conduit
+                      conduit::conduit_python)
+
+
+# extra includes and libs to support the embedded python interpreter
+target_include_directories(conduit_cpp_and_py_ex
+                           PUBLIC ${PYTHON_INCLUDE_DIR})
+
+target_link_libraries(conduit_cpp_and_py_ex
+                      ${PYTHON_LIBRARY})
+
+##############################################################################
+# fortran to and from python example
+##############################################################################
+
+add_executable(conduit_fort_and_py_ex
+               conduit_fort_and_py_ex.F90
+               conduit_fort_and_py_mod.cpp
+               conduit_fort_and_py_mod.F90
+               python_interpreter.hpp
+               python_interpreter.cpp)
+
+
+target_link_libraries(conduit_fort_and_py_ex
+                      conduit::conduit
+                      conduit::conduit_python)
+
+# extra includes and libs to support the embedded python interpreter
+target_include_directories(conduit_fort_and_py_ex
+                           PUBLIC ${PYTHON_INCLUDE_DIR})
+
+target_link_libraries(conduit_fort_and_py_ex
+                      ${PYTHON_LIBRARY})
+