Commit 442d504f authored by Joe Snyder's avatar Joe Snyder
Browse files

Redo RST Documentation

Talk about CMake process and add requirements.txt information.
parent 8d22987a
......@@ -13,89 +13,208 @@ See Copyright.txt_ for details.
Program execution
+++++++++++++++++
Prereq Install
Prerequisites
---------------
On Ubuntu::
All instructions below assume that a Python3 environment is available.
CMake
#####
The CMake-based portion of the tool requires CMake 3.12 or greater.
Download or build CMake: https://cmake.org/
CastXML
#######
A version of the CastXML tool is required for this program to run. It, likely, can
be downloaded from your Linux package management system. For Ubuntu, the command looks
like this::
sudo apt install castxml
which will install CastXML, a prerequsite for PyGCCXML.
Then::
If it is not available, a selection of binary distributions can be found on the
`data.kitware.com`_ website.
Python Libraries
################
The repository contains a requirements.txt file which can be provided to the
PIP program to install all required Python Libraries. Execute::
pip install -r requirements.txt
to install the other required programs.
Preparing C++ code
------------------
The setup for the C++ code to be wrapped is simple. Each C++ directory with content
to be wrapped should contain a file named ``wrapper_input.yml``.
This content should describe the classes, "free" functions
(functions that are not a part of a class), and non-typed enumerations.
This information follows a certain structure. This structure has three reserved key
tags: ``classes``, ``functions``, and ``enums``. Any tag not found within one of these
structures, is considered a namespace for the code to be found under::
<namespace>:
classes:
<class_name>:
<class_data>,
<class_2_name>:
<class_2_data>
functions:
<function_name>:
<function_data>
<namespace_2>:
enums:
Each type of object within the reserved tags requires different pieces of information:
+-----------------------------+---------------------------------+
| C++ Object | Required YAML pieces |
+=============================+=================================+
| Class | file: <str> |
| | Path to file with class |
| +---------------------------------+
| | inst: [] |
| | List of instantiation types |
| | for class. |
| | Leave blank for non-templated |
+-----------------------------+---------------------------------+
| Function | file: <str> |
| | Path to file with function |
| +---------------------------------+
| | is_template: <bool> |
| | "true" if function is template |
| | "false" otherwise |
| +---------------------------------+
| | inst: [] |
| | List of instantiation types |
| | for function, if is_template |
| | is true |
+-----------------------------+---------------------------------+
| Enumeration | file: <str> |
| | Path to file with enumeration |
+-----------------------------+---------------------------------+
For an example of a correctly written object, see `wrapper_input.yml`_ in the ``example`` directory.
Execution
---------
pip install pygccxml
via CMake
##########
to install PyGCCXML.
The recommended path for the usage of this tool is via CMake.
Setup
%%%%%
By utilizing the ``find_package`` utility, the created macros and functions can be
introduced into the environment. This repository contains the
``AutoPyBind11Config.cmake`` file which is the targe of the following command::
Both could be build from source as well. At this point, there is no
reason to require a build from source.
find_package(AutoPyBind11)
C++ Setup
---------
After this command is found, one additional command will be used to acquire PyBind11 via the
``FetchContent`` module::
autopybind11_fetch_build_pybind11()
Each directory with content to wrap should contain a file named
``wrapper_input.yml``. This content should describe <filler>
Add Library
%%%%%%%%%%%
Running the Generator
---------------------
To add a library for the written PyBind11 code, we use the ``autopybind11_add_module``
function. This function does the work of setting custom commands to generate
the PyBind11 code and adds a library to CMake which contains the PyBind11 code., and then
This command should be written once for each ``wrapper_input.yml`` file in the repository.
The command has the following structure::
autopybind11_add_module(<name> YAML_INPUT <path_to>/wrapper_input.yml
DESTINATION <path_to_output>
LINK_LIBRARIES <library_1> <library_2>
[CONFIG_INPUT <path_to>/config.yml])
Only the ``CONFIG_INPUT`` flag is optional. The file given to that argument can be used
to customize the templates used to create the PyBind11 CPP code. The default templates
can be found in `text_blocks.py`_
An example of the function invocation is here::
autopybind11_add_module("example" YAML_INPUT ${CMAKE_CURRENT_SOURCE_DIR}/wrapper_input.yml
DESTINATION ${CMAKE_CURRENT_BINARY_DIR}
LINK_LIBRARIES wrapper_example)
via Python
##########
This script assumes that Python 3.* is used.
The Python script has help for the arguments::
$ python3 autopybind11.py -h
usage: autopybind11.py [-h] [-s SOURCE_DIR] [-y YAML_PATH] -g CASTXML_PATH
[--includes INCLUDES] [--no-generation] [-cg CONFIG_DIR]
usage: autopybind11.py [-h] [-o OUTPUT_DIR] -y YAML_PATH --module_name
MODULE_NAME [-g CASTXML_PATH] [-cg CONFIG_DIR]
[--no-generation] [-rs RSP_PATH] [-pm]
[--common_cpp_body_fmt COMMON_CPP_BODY_FMT]
[--class_info_body_fmt CLASS_INFO_BODY_FMT]
[--init_fun_signature_fmt INIT_FUN_SIGNATURE_FMT]
[--init_fun_forward_fmt INIT_FUN_FORWARD_FMT]
[--cppbody_fmt CPPBODY_FMT]
[--module_cpp_fmt MODULE_CPP_FMT]
[--member_func_fmt MEMBER_FUNC_FMT]
[--constructor_fmt CONSTRUCTOR_FMT]
[--member_func_arg_fmt MEMBER_FUNC_ARG_FMT]
[--public_member_var_fmt PUBLIC_MEMBER_VAR_FMT]
[--private_member_var_fmt PRIVATE_MEMBER_VAR_FMT]
[--member_reference_fmt MEMBER_REFERENCE_FMT]
[--overload_template_fmt OVERLOAD_TEMPLATE_FMT]
[--wrap_header_fmt WRAP_HEADER_FMT]
[--operator_fmt OPERATOR_FMT]
[--call_operator_fmt CALL_OPERATOR_FMT]
[--enum_header_fmt ENUM_HEADER_FMT]
[--enum_val_fmt ENUM_VAL_FMT]
Args that start with '--' (eg. -o) can also be set in a config file (specified
via -cg). The config file uses YAML syntax and must represent a YAML 'mapping'
(for details, see http://learn.getgrav.org/advanced/yaml). If an arg is
specified in more than one place, then commandline values override config file
values which override defaults.
optional arguments:
-h, --help show this help message and exit
-s SOURCE_DIR, --source SOURCE_DIR
-o OUTPUT_DIR, --output OUTPUT_DIR
-y YAML_PATH, --input_yaml YAML_PATH
Path to input YAML file of namespaces
Path to input YAML file of objects to process
--module_name MODULE_NAME
Desired name of the output PyBind11 module
-g CASTXML_PATH, --castxml-path CASTXML_PATH
Path to castxml
-d DEFAULT_NAMESPACE, --default_namespace DEFAULT_NAMESPACE
value to use as the default namespace
--includes INCLUDES, -i INCLUDES
Path to the includes directory.
--no-generation, -n Only print name of files to be generated
-cg CONFIG_DIR, --config-path CONFIG_DIR
config file path
To run over the entirety of the local example, we use a command like this::
$ python3 autopybind11.py -g ~/Work/TRI/CastXML/build/bin/castxml -s ~/Work/TRI/wrapper_generator/example/
which would output a single C++ files of wrapper code called ``test_py.cpp``
Development Tools
+++++++++++++++++
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::
$ cmake -DDEFINE_TEST_PARAM=ON .... <path/to>/wrapper_generator
The ``autopybind11.py`` script will be run as a part of the ``Configure`` step in
of CMake.
--no-generation, -n Only print name of files to be generated
-rs RSP_PATH, --input_response RSP_PATH
-pm, --private_members
--common_cpp_body_fmt COMMON_CPP_BODY_FMT
--class_info_body_fmt CLASS_INFO_BODY_FMT
--init_fun_signature_fmt INIT_FUN_SIGNATURE_FMT
--init_fun_forward_fmt INIT_FUN_FORWARD_FMT
--cppbody_fmt CPPBODY_FMT
--module_cpp_fmt MODULE_CPP_FMT
--member_func_fmt MEMBER_FUNC_FMT
--constructor_fmt CONSTRUCTOR_FMT
--member_func_arg_fmt MEMBER_FUNC_ARG_FMT
--public_member_var_fmt PUBLIC_MEMBER_VAR_FMT
--private_member_var_fmt PRIVATE_MEMBER_VAR_FMT
--member_reference_fmt MEMBER_REFERENCE_FMT
--overload_template_fmt OVERLOAD_TEMPLATE_FMT
--wrap_header_fmt WRAP_HEADER_FMT
--operator_fmt OPERATOR_FMT
--call_operator_fmt CALL_OPERATOR_FMT
--enum_header_fmt ENUM_HEADER_FMT
--enum_val_fmt ENUM_VAL_FMT
This is useful for some small testing. But since a Python call would be needed to wrap each input file, we recommend
using the CMake system above.
Style Checking / Linting
-------------------------
......@@ -113,3 +232,6 @@ or setup a CMake build system and execute the ``WG_Linter`` test::
.. _pycodestyle: https://pypi.org/project/pycodestyle/
.. _Copyright.txt: Copyright.txt
.. _`data.kitware.com`: https://data.kitware.com/#folder/57b5de948d777f10f2696370
.. _`text_blocks.py`: text_blocks.py
.. _`wrapper_input.yml`: example/wrapper_input.yml
\ No newline at end of file
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment