...
The BMI branch is soon to be merged with the trunk. Therefore it becomes relevant for all XBeach developers to understand the differences between the "makeincludes" program and the Python script. These differences are listed on this page.
Components
The "makeincludes" program is replaced by the following components:
- Python script that parses Fortran code and generates include files based on templates (stored in scripts/generate.py)
- Templates for include files (stored in src/xbeachlibrary/templates/)
- Input parameter definition (stored in src/xbeachlibrary/params.F90)
- Output variables definition (stored in src/xbeachlibrary/variables.F90, so not spaceparams.tmpl anymore!)
Python script
The "makeincludes" program used to parse src/xbeachlibrary/params.F90 and src/xbeachlibrary/spaceparams.tmpl to find all input parameters and output variables respectively. The new templating system uses a Python script located in scripts/generate.py to parse the Fortran code. Also, the spaceparams.tmpl file is replaced by the src/xbeachlibrary/variables.F90 file. The main reason is that the Python script then only needs to parse Fortran code and not also a custom template format as used in the original spaceparams.tmpl file.
After parsing the relevant Fortran code the Python script defines two dictionaries: "parameters" and "variables" that hold all the input parameters and output variables respectively, including their properties like rank, size, type and description. These dictionaries are used to parse the templates stored in src/xbeachlibrary/templates/ and generate the include files necessary to compile XBeach.
Templates
Templates are written in Fortran and therefore have the F90 file extension. Each template file will result in a single include file that has the INC file extension and will be written in the src/xbeachlibrary/ directory. To add an include file simply add a template file to the src/xbeachlibrary/templates/ directory and it will be picked up by the Python script. Templates define the Fortran code that is repeated in include files. Additional template markers define how the code is repeated using snippets of Python code. The Mako template engine is used to do so (see http://www.makotemplates.org).
...
A few other things changed in the XBeach code structure along with the new templating system as explained in the following subsections.
Template for writelog functions
The writelog functions are also considered repetitive and therefore generated using a template as well. You can add writelog functions by adding a format code to the "formats" variable in the src/xbeachlibrary/templates/writelog.f90 and src/xbeachlibrary/templates/writeloginterface.f90 templates (e.g. "aiaiafai"). The necessary functions and interfaces are generated accordingly.
Python dependency
Compiling XBeach now depends on Python to generate the include files. Python is shipped with all popular Unix distributions, therefore this is no problem for Unix users. For Windows users there Python is not always available. Therefore the scripts/generate.py is compiled as Windows executable so Windows users do not need Python to compile XBeach. Only when the scripts/generate.py script is modified the executable needs to be recompiled on a Windows machine with Python and the "distutils" and "py2exe" packages installed. Compiling the executable is done from the command-line as follows:
...