README.rst 3.23 KB
Newer Older
Joe Snyder's avatar
Joe Snyder committed
1
2
3
4
5
6
Wrapper Generator
==================

This repository contains the first set of Python code which could be used to
automatically generate PyBin11 code from C++ files with proper annotation.

7
8
9
Program execution
+++++++++++++++++

Joe Snyder's avatar
Joe Snyder committed
10
11
12
13
14
Prereq Install
---------------

On Ubuntu::

15
16
17
18
  sudo apt install castxml

which will install CastXML, a prerequsite for PyGCCXML.
Then::
19

20
    pip install pygccxml
21

22
23
to install PyGCCXML.

Joe Snyder's avatar
Joe Snyder committed
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51


Both could be build from source as well.  At this point, there is no
reason to require a build from source.

C++ Setup
---------

Each directory with content to wrap should contain a file named
``wrapper_input.json``.  This content should describe <filler>

Running the Generator
---------------------

This script assumes that Python 3.* is used.
The Python script has help for the arguments::

    $ python3 generator.py -h
    usage: generator.py [-h] [-s SOURCE_DIR] [-j JSON_PATH] -g CASTXML_PATH
                        [--includes INCLUDES] [--no-generation]

    optional arguments:
      -h, --help            show this help message and exit
      -s SOURCE_DIR, --source SOURCE_DIR
      -j JSON_PATH, --input_json JSON_PATH
                            Path to input JSON file of namespaces
      -g CASTXML_PATH, --castxml-path CASTXML_PATH
                            Path to castxml
Joe Snyder's avatar
Joe Snyder committed
52
53
      -d DEFAULT_NAMESPACE, --default_namespace DEFAULT_NAMESPACE
                            value to use as the default namespace
Joe Snyder's avatar
Joe Snyder committed
54
55
56
57
      --includes INCLUDES, -i INCLUDES
                            Path to the includes directory.
      --no-generation, -n   Only print name of files to be generated

Joe Snyder's avatar
Joe Snyder committed
58

Joe Snyder's avatar
Joe Snyder committed
59
60
61
62
To run over the entirety of the local example, we use a command like this::

  $ python3 generator.py -g ~/Work/TRI/CastXML/build/bin/castxml -s ~/Work/TRI/wrapper_generator/example/

63
64
65
66
67
which would output a single C++ files of wrapper code called ``test_py.cpp``

Development Tools
+++++++++++++++++

Joe Snyder's avatar
Joe Snyder committed
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
Building with CMake
-------------------

The repository has a simple CMake system which can be used to compile both the
example code and the wrapped version of the code.
This repository requires a CMake version that is 3.12 or greater.

There are two CMake options which can be altered by the user.

+------------------------+--------------------------+
+    Option   Name       |      Effect              +
+------------------------+--------------------------+
+    DEFINE_TEST_PARAM   |   Adds a "-D" define to  +
+                        |   CXX flags: changes     +
+                        |   a function signature   +
+------------------------+--------------------------+

These options can be set either CMake GUIs or on the command line::

Joe Snyder's avatar
Joe Snyder committed
87
  $ cmake -DDEFINE_TEST_PARAM=ON  .... <path/to>/wrapper_generator
Joe Snyder's avatar
Joe Snyder committed
88
89
90
91

The ``generator.py`` script will be run as a part of the ``Configure`` step in
of CMake.

92
93
94
95
96
97
98
99
100
101
Style Checking / Linting
-------------------------

This repository uses the pycodestyle_ tool for linting and style checking which
can be installed via the ``pip`` program.
The program should be run at the top level so that the ``setup.cfg`` in the
repository is available. An example run is as follows::

  $ pycodestyle generator.py

Joe Snyder's avatar
Joe Snyder committed
102
103
104
105
106
or setup a CMake build system and execute the ``WG_Linter`` test::

  $ ctest -R WG_Linter -VV

.. _pycodestyle: https://pypi.org/project/pycodestyle/