Merge pull request #186 from LLNL/develop

Version 0.12.2

CHANGELOG.md

@@ -6,7 +6,21 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
-
+
+## v0.12.2 - 2020-08-04
+### Added
+- Added std::string scalar arguments.
+
+### Fixed
+- Mangle names of Fortran helper functions with *C_prefix*.  This
+  fixes a conflict when two Shroud generated wrappers are used in the
+  same subprogram.  Ideally these helpers would be `PRIVATE`, but
+  gfortran does not allow `PRIVATE` and `BIND(C)` together.
+- Mangle names of Fortran derived types for capsules with *C_prefix* to avoid
+  name conflicts.
+- Correctly count Python arguments when there are default arguments.
+  Do not include *intent(out)* arguments.
+
 ## v0.12.0 - 2020-06-29
 ### Added
 - Option `C_force_wrapper` to create a C wrapper.
@@ -23,7 +37,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
   are a lot of classes which may create lots of duplicate helpers.
 - Parse array syntax for variables and struct members.
 - Change Python setter and getter functions to be driven by py_statements.
-- Parse `(void)` C prototype to indicate no parameters.	
+- Parse `(void)` C prototype to indicate no parameters.
 
 ### Changed
 - *intent(in)* pointer arguments now use the *rank* attribute instead of

Makefile

@@ -52,6 +52,7 @@ include $(top)/regression/run/Makefile
 virtualenv : $(venv.dir)
 $(venv.dir) :
 	$(PYTHON) -m venv --system-site-packages $(venv.dir)
+	$(python.dir)/pip install --upgrade pip
 virtualenv2 :
 	$(venv) --system-site-packages $(venv.dir)
 
@@ -111,10 +112,33 @@ pypi:
 
 .PHONY : install-twine sdist testpypi pypi
 
+########################################################################
+# Creating pex executable
+# This puts all of shroud into a single file.
+# https://github.com/pantsbuild/pex
+
+install-pex :
+	$(python.dir)/pip install pex
+
+# Use version in output file name.
+pex-file : vernum = $(shell grep __version__ shroud/metadata.py | awk -F '"' '{print $$2}')
+pex-file : dist-pex/..
+	$(python.dir)/pex . -r requirements.txt --python-shebang="/usr/bin/env python3" \
+          -e shroud.main:main -o dist-pex/shroud-$(vernum).pex
+	cd dist-pex && ln --force --symbolic shroud-$(vernum).pex shroud.pex
+
+# Test pex created executable
+do-test-pex :
+	@export TEST_OUTPUT_DIR=$(top)/$(tempdir)/regression; \
+	export TEST_INPUT_DIR=$(top)/regression; \
+	export EXECUTABLE_DIR=$(top)/dist-pex/shroud.pex; \
+	$(PYTHON) regression/do-test.py $(do-test-args)
+
 ########################################################################
 # Creating shiv executable
 # This puts all of shroud into a single file.
 # https://github.com/linkedin/shiv
+# Note: Python 3.6+
 
 install-shiv :
 	$(python.dir)/pip install shiv
@@ -124,7 +148,7 @@ shiv-file : vernum = $(shell grep __version__ shroud/metadata.py | awk -F '"' '{
 shiv-file : dist-shiv/..
 	$(python.dir)/shiv --python '/usr/bin/env python3' -c shroud \
           -o dist-shiv/shroud-$(vernum).pyz .
-	cd dist-shiv && ln -s shroud-$(vernum).pyz shroud.pyz
+	cd dist-shiv && ln --force --symbolic shroud-$(vernum).pyz shroud.pyz
 
 # Test shiv created executable
 do-test-shiv :

README.md

@@ -98,9 +98,10 @@ In addition, a file created by
 is available from the github release.
 Shroud and PyYAML are bundled into a single executable which uses
 the Python3 on your path.
+Shiv requires Python 3.6+.
 
 ```
-wget https://github.com/LLNL/shroud/archive/shroud-0.12.1.pyz
+wget https://github.com/LLNL/shroud/archive/shroud-0.12.2.pyz
 ```
 
 

docs/conf.py

@@ -53,7 +53,7 @@
 # The short X.Y version.
 version = '0.12'
 # The full version, including alpha/beta/rc tags.
-release = '0.12.1'
+release = '0.12.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/cstatements.rst

@@ -48,7 +48,7 @@ arg
 
 arg_decl
     The explicit declarations will be provided in the fields
-    c_arg_decl and f_arg_decl.
+    *c_arg_decl* and *f_arg_decl*.
 
 capsule
 
@@ -181,6 +181,8 @@ f_arg_decl
 ^^^^^^^^^^
 
 A list of declarations in the Fortran interface when buf_arg includes "arg_decl".
+The variable to be declared is *c_var*.
+*f_module* can be used to add ``USE`` statements.
 
 .. c_var
 

docs/fstatements.rst

@@ -67,6 +67,8 @@ If true, the Fortran wrapper will always be created.
 This is used when an assignment is needed to do a type coercion;
 for example, with logical types.
 
+.. XXX tends to call bufferify version
+
 arg_name
 ^^^^^^^^
 
@@ -93,6 +95,12 @@ Added before splicer.
 arg_c_call
 ^^^^^^^^^^
 
+List of arguments to pass to C wrapper.
+This can include an expression or additional arguments if required. 
+
+.. code-block:: text
+
+        arg_c_call=["C_LOC({f_var})"],
 
 declare
 ^^^^^^^
@@ -113,6 +121,18 @@ call
 
 Code used to call the function.
 Defaults to ``{F_result} = {F_C_call}({F_arg_c_call})``
+
+For example, to assign to an intermediate variable:
+
+.. code-block:: text
+
+        declare=[
+            "type(C_PTR) :: {F_pointer}",
+        ],
+        call=[
+            "{F_pointer} = {F_C_call}({F_arg_c_call})",
+        ],
+                
    
 post_call
 ^^^^^^^^^

docs/python.rst

@@ -111,6 +111,53 @@ PY_from_object
 PyArg_Parse - ``status = converter(object, address)``.
 Defaults to *None*.
 
+py_ctype
+^^^^^^^^
+
+The type returned by *PY_get* function.
+Defaults to ``None`` which implies it is the same as the typemap.
+i.e. ``PyInt_AsLong`` returns a ``long``.
+
+Defined for complex types because ``PyComplex_AsCComplex`` returns
+type ``Py_complex``.
+See also *pytype_to_pyctor* and *pytype_to_cxx*.
+
+pytype_to_pyctor
+^^^^^^^^^^^^^^^^
+
+Expression to use with *PY_ctor*.
+Defaults to ``None`` which indicates no additional processing of the argument
+is required.
+Only needs to be defined when *py_ctype* is defined.
+
+With complex types, it is used to extract the real and imaginary parts from
+``Py_complex`` (defined with *py_ctype*)
+with ``creal({ctor_expr}), cimag({ctor_expr})``.
+*ctor_expr* is the expression used with *Py_ctor*.
+
+pytype_to_cxx
+^^^^^^^^^^^^^
+
+Expression to convert *py_ctype* into a C++ value.
+Only needs to be defined when *py_ctype* is defined.
+
+Used with complex to convert ``Py_complex``  (defined with *py_ctype*)
+to C using ``{work_var}.real + {work_var}.imag * I``
+or C++ with ``std::complex(\tcvalue.real, cvalue.imag)``.
+
+cxx_to_pytype
+^^^^^^^^^^^^^
+
+Statements to convert *cxx_var* to *py_ctype*/
+Only needs to be defined when *py_ctype* is defined.
+
+.. code-block:: yaml
+
+    cxx_to_pytype: |
+        {ctype_var}.real = creal({cxx_var});
+        {ctype_var}.imag = cimag({cxx_var});
+
+
 PYN_descr
 ^^^^^^^^^
 
@@ -269,6 +316,7 @@ Assign a blank list will not add any declarations.
 This is used when only an output ``std::string`` or ``std::vector``
 is created after parsing arguments.
 
+This variables is used with ``PyArg_ParseTupleAndKeywords``.
 
 The argument will be non-const to allow it to be assigned later.
 

docs/reference.rst

@@ -54,6 +54,12 @@ write-helpers BASE
        Write files which contain the available helper functions
        into the files BASE.c and BASE.f.
 
+write-version
+       Write Shroud version into generated files.
+       ``--nowrite-version`` will not write the version and is used
+       by the testsuite to avoid changing every reference file when
+       the version changes.
+
 yaml-types FILE
        Write a YAML file with the default types.
 
@@ -452,11 +458,21 @@ F_abstract_interface_subprogram_template
    Defaults to ``arg{index}`` where *index* is the 0-based argument index.
    see :ref:`DeclAnchor_Function_Pointers`.
 
+F_array_type_template
+   ``{C_prefix}SHROUD_array``
+
+F_capsule_data_type_template
+   ``{C_prefix}SHROUD_capsule_data``
+
 F_capsule_data_type_class_template
     Name of the derived type which is the ``BIND(C)`` equivalent of the
     struct used to implement a shadow class.
     Each class must have a unique name.
-    Defaults to ``SHROUD_{F_name_scope}capsule``.
+    Defaults to ``{C_prefix}SHROUD_{F_name_scope}capsule``.
+
+F_capsule_type_template
+    ``{C_prefix}SHROUD_capsule``
+
 
 F_enum_member_template
     Name of enumeration member in Fortran wrapper.
@@ -711,15 +727,21 @@ CXX_this
 F_array_type
     Name of derived type used to store information about an array
     such as its address and size.
-    Defaults to *SHROUD_array*.
+    Default value from option *F_array_type_template* which 
+    defaults to *{C_prefix}SHROUD_array*.
 
 F_C_prefix
     Prefix added to name of generated Fortran interface for C routines.
     Defaults to **c_**.
 
 F_capsule_data_type
     Name of derived type used to share memory information with C or C++.
-    Defaults to *SHROUD_capsule_data*.
+    Member of *F_array_type*.
+    Default value from option *F_capsule_data_type_template* which 
+    defaults to *{C_prefix}SHROUD_capsule_data*.
+
+    Each class has a similar derived type, but with a different name
+    to enforce type safety.
 
 F_capsule_delete_function
     Name of type-bound function of *F_capsule_type* which will
@@ -733,7 +755,8 @@ F_capsule_final_function
 
 F_capsule_type
     Name of derived type used to release memory allocated by C or C++.
-    Defaults to *SHROUD_capsule*.
+    Default value from option *F_capsule_type_template* which 
+    defaults to *{C_prefix}SHROUD_capsule*.
     Contains a *F_capsule_data_type*.
 
 F_derived_member

docs/typemaps.rst

@@ -66,6 +66,11 @@ And template arguments are converted to underscores with the trailing
 ``>`` being replaced
 i.e. ``std::vector<int>`` becomes ``std_vector_int``.
 
+Complex types set this explicitly since C and C++ have much different
+type names. The *flat_name* is always ``double_complex`` while
+*c_type* is ``double complex`` and *cxx_type* is ``complex<double>``.
+
+
 One use of this name is as the **function_suffix** for templated functions.
 
 idtor

regression/do-test.py

@@ -187,6 +187,8 @@ def do_test(self):
             # Avoid printing things which may vary (path, date, time).
             "--option",
             "debug_testsuite=true",
+            # Avoid printing version number in reference files
+            "--nowrite-version",
         ]
 
         # test specific flags
@@ -320,6 +322,7 @@ def __init__(self, name, yaml=None, cmdline=None):
                  cmdline=[
                      "--write-helpers", "helpers",
                      "--yaml-types", "def_types.yaml",
+                     "--write-version",  # Test writing vesion
                  ]),
         TestDesc("tutorial"),
         TestDesc("debugfalse", yaml="tutorial",
@@ -477,6 +480,7 @@ def __init__(self, name, yaml=None, cmdline=None):
         TestDesc("namespace"),
         TestDesc("namespacedoc"),
         TestDesc("strings"),
+        TestDesc("ccomplex"),
         TestDesc("clibrary"),
         TestDesc("cxxlibrary"),
         TestDesc("interface"),

regression/input/ccomplex.yaml

@@ -0,0 +1,61 @@
+copyright:
+- Copyright (c) 2017-2020, Lawrence Livermore National Security, LLC and
+- other Shroud Project Developers.
+- See the top-level COPYRIGHT file for details.
+-
+- "SPDX-License-Identifier: (BSD-3-Clause)"
+-
+
+# Wrap complex in a C library
+# Many of the same function as Tutorial, but for C.
+
+# Several tests have a 'char *outbuf+intent(out)' argument
+# which will force a C bufferify wrapper to be created.
+# The size of this buffer is controlled by lenoutbuf.
+# This feature is helpful for the C tests since a C wrapper is not required
+# for each function since we do not need to deal with name mangling
+# like in C++.
+
+library: ccomplex
+cxx_header: ccomplex.h
+
+language: c
+
+options:
+  debug: True
+  wrap_python: True
+  wrap_lua: False
+  literalinclude2: True
+
+declarations:
+
+######################################################################
+- decl: void acceptFloatComplexInoutPtr(float complex *arg1)
+  options:
+    wrap_python: False
+- decl: void acceptDoubleComplexInoutPtr(double complex *arg1)
+- decl: void acceptDoubleComplexOutPtr(double complex *arg1 +intent(out))
+
+- decl: void acceptDoubleComplexInoutPtrFlag(double complex *arg1, int *flag +intent(out))
+  options:
+    wrap_c: False
+    wrap_fortran: False
+  doxygen:
+   description: |
+     Return two values so Py_BuildValue is used.
+
+- decl: void acceptDoubleComplexOutPtrFlag(
+            double complex *arg1 +intent(out),
+            int *flag +intent(out))
+  doxygen:
+   description: |
+     Return two values so Py_BuildValue is used.
+     Creates a Py_complex for intent(out)
+
+######################################################################
+
+#- decl: void acceptDoubleComplexInoutArrayList(
+#            double complex *arg1 +rank(1),
+#            int narg +implied(size(arg1)))
+#  options:
+#    PY_array_arg: list