Add test for wrapping C++ library

.gitmodules

@@ -4,3 +4,6 @@
 [submodule "external/bmi-example-fortran"]
 	path = external/bmi-example-fortran
 	url = https://github.com/csdms/bmi-example-fortran
+[submodule "external/bmi-example-cxx"]
+	path = external/bmi-example-cxx
+	url = https://github.com/csdms/bmi-example-cxx

.travis.yml

@@ -45,7 +45,7 @@ before_install:
   fi
 - micromamba activate
 - micromamba install mamba --yes -c conda-forge
-- mamba create -n testing python=$PYTHON bmi-c bmi-fortran cmake pkg-config fortran-compiler c-compiler mamba --yes -c conda-forge
+- mamba create -n testing python=$PYTHON --file=requirements-testing.txt --yes -c conda-forge
 - source activate testing
 - |
   mkdir _build \
@@ -59,8 +59,13 @@ before_install:
   &&   cmake ../external/bmi-example-fortran -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX \
   &&   make install \
   &&   popd
+- |
+  mkdir _buildcxx \
+  && pushd _buildcxx \
+  &&   cmake ../external/bmi-example-cxx -DCMAKE_INSTALL_PREFIX=$CONDA_PREFIX \
+  &&   make install \
+  &&   popd
 install:
-- mamba install --file=requirements-testing.txt --yes -c conda-forge
 - pip install .
 script:
 - babelize --version

CHANGES.rst

@@ -4,7 +4,7 @@ Changelog for babelizer
 0.3.2 (unreleased)
 ------------------
 
-- Nothing changed yet.
+- No changes yet
 
 
 0.3.1 (2020-09-25)

Makefile

@@ -52,11 +52,11 @@ clean-test: ## remove test and coverage artifacts
 	rm -fr .pytest_cache
 
 lint: ## check style with flake8
-	flake8 babelizer
+	flake8 babelizer tests
 
 pretty: ## reformat files to make them look pretty
-	isort --apply --recursive babelizer
-	black setup.py babelizer --exclude=babelizer/data
+	isort babelizer tests
+	black setup.py babelizer tests --exclude=babelizer/data
 
 
 test: ## run tests quickly with the default Python

README.rst

@@ -87,14 +87,17 @@ Input file
 **********
 
 The *babelizer* requires a single, *toml*-formatted, input file that describes
-the library you would like to wrap. This file is typically called, *babel.toml*.
+the library you would like to wrap. This file is typically named *babel.toml*.
 An example of a blank *babel.toml* file,
 
 .. code:: toml
 
     [library]
+    [library."<name>"]
     language = "c"
-    entry_point = []
+    library = ""
+    header = ""
+    entry_point = ""
 
     [build]
     undef_macros = []
@@ -104,14 +107,15 @@ An example of a blank *babel.toml* file,
     include_dirs = []
     extra_compile_args = []
 
-    [plugin]
+    [package]
     name = ""
     requirements = []
 
     [info]
-    plugin_author = "csdms"
     github_username = "pymt-lab"
-    plugin_license = "MIT"
+    package_author = "csdms"
+    package_author_email = "csdms@colorado.edu"
+    package_license = "MIT"
     summary = ""
 
 You can generate *babel.toml* files using the *babelize generate* command.
@@ -121,107 +125,143 @@ For example, the above *babel.toml* was generated with,
 
   $ babelize generate --no-input -
 
+Library section
+===============
 
-Build section
-=============
-
-In the build section the user can specify flags to pass to the compiler
-when building the extension.
-
-Info section
-============
-
-Descriptive infomation about the package.
+The *library* section specifies information about the library being babelized.
 
-Github username
----------------
+Name
+----
 
-The GitHub username or organization where this package will be hosted. This
-is used in generating links to the CI, docs, etc.
+The name of the babelized class.
+This will be a Python class,
+so it should follow Python naming conventions such as camel-case typing.
 
-Author
-------
+Language
+--------
 
-Author of the wrapped package. Note that this is not the author of the
-library being wrapped, just the code generated by the *babelizer*.
+The programming language of the library (possible values are "c", "c++",
+"fortran", and "python").
 
-License
--------
+.. code:: toml
 
-Specify the Open Source license for the wrapped package. Note that this is not the
-license for the library being wrapped, just for the code generated by the *babelizer*.
+  [library]
+  language = "c"
 
-Summary
+Library
 -------
 
-A short description of the wrapped library.
+The name of the BMI library to wrap.
+This is the text passed to the linker through the `-l` option;
+for example, use "foo" for a library *libfoo.a*.
 
-Library section
-===============
+Header
+------
 
-The *library* section specifies information about the library being babelized.
+The name of the header file (*.h*, *.hxx*) declaring the BMI class.
+This option is only needed when wrapping C and C++ libraries.
 
-Entry point to the BMI
-----------------------
+Entry point
+-----------
 
-A list of one or more entry points into the library.
+The name of the BMI entry point into the library.
+For object-oriented languages,
+this is typically the name of a class that implements the BMI.
+For procedural languages,
+this is typically a function.
 
-The following will define a Python class *Hydrotrend* that wraps the function
-*register_bmi_hydrotrend* defined in the library *bmi_hydrotrend*.
+An example of a C++ library (*bmi_child*), exposing a class *BmiChild* (which
+implements a BMI) might look like the following:
 
 .. code:: toml
 
-  [library]
-  entry_point = [ "Hydrotrend=bmi_hydrotrend:register_bmi_hydrotrend",]
+   [library]
+   [library.Child]
+   language = "c++"
+   library = "bmi_child"
+   header = "bmi_child.hxx"
+   entry_point = "BmiChild"
 
-An example of a C++ library (*bmi_child*), exposing a class *Child* (which
-implemets a BMI) might look like the following,
+whereas a C library (*bmi_cem*), exposing a function *register_bmi_cem* (which
+implements a BMI) might look like:
 
 .. code:: toml
 
-  [library]
-  entry_point = [ "Child=bmi_child:Child",]
-
-Library language
-----------------
+   [library]
+   [library.Cem]
+   language = "c"
+   library = "bmi_cem"
+   header = "bmi_cem.h"
+   entry_point = "register_bmi_cem"
 
-The programming language of the library (possible values are "c", "c++",
-"fortran", and "python").
-
-.. code:: toml
+Build section
+=============
 
-  [library]
-  language = "c"
+In the build section the user can specify flags to pass to the compiler
+when building the extension.
 
-Plugin section
-==============
+Package section
+===============
 
 Name and extra requirements needed to build the babelized library.
 
 Name
 ----
 
-Name to use for the wrapped package. This is used when create the new
-package, *pymt_<plugin_name>*. For example, the following will create
+Name to use for the wrapped package. This is used when creating the new
+package *<package_name>*. For example, the following will create
 a new package, *pymt_foo*.
 
 .. code:: toml
 
-  [plugin]
-  name = "foo"
+  [package]
+  name = "pymt_foo"
 
 Requirements
 ------------
 
-List of packages required by the libaray being wrapped. For example, the
+List of packages required by the library being wrapped. For example, the
 following indicates that the packages *foo* and *bar* are dependencies
 for the package.
 
 .. code:: toml
 
-  [plugin]
+  [package]
   requirements = [ "foo", "bar",]
 
+Info section
+============
+
+Descriptive infomation about the package.
+
+Github username
+---------------
+
+The GitHub username or organization where this package will be hosted. This
+is used in generating links to the CI, docs, etc.
+
+Author
+------
+
+Author of the wrapped package. Note that this is not the author of the
+library being wrapped, just the code generated by the *babelizer*.
+
+Email
+-----
+
+Contact email to use for the wrapped package.
+
+License
+-------
+
+Specify the Open Source license for the wrapped package. Note that this is not the
+license for the library being wrapped, just for the code generated by the *babelizer*.
+
+Summary
+-------
+
+A short description of the wrapped library.
+
 
 Example babel.toml
 ==================
@@ -234,8 +274,11 @@ called *hydrotrend*.
 .. code:: toml
 
     [library]
+    [library.Hydrotrend]
     language = "c"
-    entry_point = [ "Hydrotrend=bmi_hydrotrend:register_bmi_hydrotrend",]
+    library = "bmi_hydrotrend"
+    header = "bmi_hydrotrend.h"
+    entry_point = "register_bmi_hydrotrend"
 
     [build]
     undef_macros = []
@@ -245,26 +288,31 @@ called *hydrotrend*.
     include_dirs = []
     extra_compile_args = []
 
-    [plugin]
-    name = "hydrotrend"
-    requirements = [ "hydrotrend",]
+    [package]
+    name = "pymt_hydrotrend"
+    requirements = ["hydrotrend"]
 
     [info]
-    plugin_author = "csdms"
     github_username = "pymt-lab"
-    plugin_license = "MIT"
+    package_author = "csdms"
+    package_author_email = "csdms@colorado.edu"
+    package_license = "MIT"
     summary = "PyMT plugin for hydrotrend"
 
-You can use the *babelize generate* command to generate *babel.toml* files.
+You can use the ``babelize generate`` command to generate *babel.toml* files.
 For example the above *babel.toml* can be generated with the following,
 
 .. code:: bash
 
-  $ babelize generate babel.toml \
-      --summary="PyMT plugin for hydrotrend" \
-      --entry-point=Hydrotrend=bmi_hydrotrend:register_bmi_hydrotrend \
-      --name=hydrotrend \
-      --requirement=hydrotrend
+    $ babelize generate babel.toml \
+	  --package=pymt_hydrotrend \
+	  --summary="PyMT plugin for hydrotrend" \
+	  --language=c \
+	  --library=bmi_hydrotrend \
+	  --header=bmi_hydrotrend.h \
+	  --entry-point=register_bmi_hydrotrend \
+	  --name=Hydrotrend \
+	  --requirement=hydrotrend
 
 ***
 Use

babelizer/__init__.py

@@ -1,4 +1,3 @@
 import pkg_resources
 
-
 __version__ = pkg_resources.get_distribution("babelizer").version