# Shroud: generate Fortran and Python wrappers for C and C++ libraries.
**Shroud** is a tool for creating a Fortran or Python interface to a C
or C++ library. It can also create a C API for a C++ library.
The user creates a YAML file with the C/C++ declarations to be wrapped
along with some annotations to provide semantic information and code
generation options. **Shroud** produces a wrapper for the library.
The generated code is highly-readable and intended to be similar to code
that would be hand-written to create the bindings.
verb
1. wrap or dress (a body) in a shroud for burial.
2. cover or envelop so as to conceal from view.
[](https://travis-ci.org/LLNL/shroud)
[](http://shroud.readthedocs.io/en/latest/?badge=develop)
## Goals
- Simplify the creating of wrapper for a C++ library.
- Preserves the object-oriented style of C++ classes.
- Create an idiomatic wrapper API from the C++ API.
- Generate code which is easy to understand.
- No dependent runtime library.
## Example
The user creates a YAML file which includes declarations from `zoo.hpp`.
```
library: zoo
cxx_header: zoo.hpp
declarations:
- decl: class Animal
declarations:
- decl: Animal()
- decl: void speak(const std::string &word)
```
This creates a Fortran interface which can be used as:
```
use zoo_mod
type(Animal) dog
dog = Animal()
dog%speak("woof")
```
And from Python
```
import zoo
dog = zoo.Animal()
dog.speak("woof")
```
## Documentation
To get started using Shroud, check out the full documentation:
http://shroud.readthedocs.io/en/develop
Presentation at FortranCon2020
https://www.youtube.com/watch?v=1mdI-M94vDc
[Slides](./pdf/Shroud-forcon.pdf)
## Mailing List
shroud-users@groups.io
https://groups.io/g/shroud-users
## Required Packages
* yaml - https://pypi.python.org/pypi/PyYAML
## C++ to C to Fortran
The generated Fortran requires a Fortran 2003 compiler.
## C++ or C to Python
The generated Python requires Python 2.7 or 3.4+.
Python features:
- Uses NumPy for arrays. Also able to use Python lists if NumPy is overkill.
- Uses extension type for classes.
- Creates readable source.
## Getting started
Shroud can be installed using pip
```
pip install llnl-shroud
```
This can be done in a virtual environment as
```
cd my_project_folder
virtualenv my_project
source my_project/bin/activate
pip install llnl-shroud
```
This assumes the bash shell. Source activate.csh for csh.
In addition, a file created by
[shiv](https://github.com/linkedin/shiv)
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.13.0.pyz
```
## License
Copyright (c) 2017-2023, Lawrence Livermore National Security, LLC.
Produced at the Lawrence Livermore National Laboratory.
SPDX-License-Identifier: (BSD-3-Clause)
See [LICENSE](./LICENSE) for details
Unlimited Open Source - BSD 3-clause Distribution
`LLNL-CODE-738041` `OCEC-17-143`
SPDX usage
------------
Individual files contain SPDX tags instead of the full license text.
This enables machine processing of license information based on the SPDX
License Identifiers that are available here: https://spdx.org/licenses/
Files that are licensed as BSD 3-Clause contain the following
text in the license header:
SPDX-License-Identifier: (BSD-3-Clause)
External Packages
-------------------
Shroud bundles some of its external dependencies in its repository. These
packages are covered by various permissive licenses. A summary listing
follows. See the license included with each package for full details.
[//]: # (Note: The spaces at the end of each line below add line breaks)
PackageName: fruit
PackageHomePage: https://sourceforge.net/projects/fortranxunit/
PackageLicenseDeclared: BSD-3-Clause
Raw data
{
"_id": null,
"home_page": "http://github.gov/llnl/shroud",
"name": "llnl-shroud",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "fortran development",
"author": "Lawrence Livermore National Laboratory",
"author_email": "shroud-users@groups.io",
"download_url": "https://files.pythonhosted.org/packages/90/aa/da7036e7ae1a1cb9bf0f0c9bbd19918f1d87b2f86bc10c86851ae242b586/llnl-shroud-0.13.0.tar.gz",
"platform": null,
"description": "# Shroud: generate Fortran and Python wrappers for C and C++ libraries.\n\n**Shroud** is a tool for creating a Fortran or Python interface to a C\nor C++ library. It can also create a C API for a C++ library.\n\nThe user creates a YAML file with the C/C++ declarations to be wrapped\nalong with some annotations to provide semantic information and code\ngeneration options. **Shroud** produces a wrapper for the library.\nThe generated code is highly-readable and intended to be similar to code\nthat would be hand-written to create the bindings.\n\nverb\n1. wrap or dress (a body) in a shroud for burial.\n2. cover or envelop so as to conceal from view.\n\n[](https://travis-ci.org/LLNL/shroud)\n[](http://shroud.readthedocs.io/en/latest/?badge=develop)\n\n## Goals\n\n- Simplify the creating of wrapper for a C++ library.\n- Preserves the object-oriented style of C++ classes.\n- Create an idiomatic wrapper API from the C++ API.\n- Generate code which is easy to understand.\n- No dependent runtime library.\n\n## Example\n\nThe user creates a YAML file which includes declarations from `zoo.hpp`.\n\n```\nlibrary: zoo\ncxx_header: zoo.hpp\n\ndeclarations:\n- decl: class Animal\n declarations:\n - decl: Animal()\n - decl: void speak(const std::string &word)\n```\nThis creates a Fortran interface which can be used as:\n\n```\nuse zoo_mod\ntype(Animal) dog\ndog = Animal()\ndog%speak(\"woof\")\n```\n\nAnd from Python\n\n```\nimport zoo\ndog = zoo.Animal()\ndog.speak(\"woof\")\n```\n\n## Documentation\n\nTo get started using Shroud, check out the full documentation:\n\nhttp://shroud.readthedocs.io/en/develop\n\nPresentation at FortranCon2020\n\nhttps://www.youtube.com/watch?v=1mdI-M94vDc\n[Slides](./pdf/Shroud-forcon.pdf)\n\n## Mailing List\n\nshroud-users@groups.io\n\nhttps://groups.io/g/shroud-users\n\n## Required Packages\n\n* yaml - https://pypi.python.org/pypi/PyYAML\n\n## C++ to C to Fortran\n\nThe generated Fortran requires a Fortran 2003 compiler.\n\n## C++ or C to Python\n\nThe generated Python requires Python 2.7 or 3.4+.\n\nPython features:\n\n- Uses NumPy for arrays. Also able to use Python lists if NumPy is overkill.\n- Uses extension type for classes.\n- Creates readable source.\n\n## Getting started\n\nShroud can be installed using pip\n\n```\npip install llnl-shroud\n```\n\nThis can be done in a virtual environment as\n\n```\ncd my_project_folder\nvirtualenv my_project\nsource my_project/bin/activate\npip install llnl-shroud\n```\n\nThis assumes the bash shell. Source activate.csh for csh.\n\nIn addition, a file created by\n[shiv](https://github.com/linkedin/shiv)\nis available from the github release.\nShroud and PyYAML are bundled into a single executable which uses\nthe Python3 on your path.\nShiv requires Python 3.6+.\n\n```\nwget https://github.com/LLNL/shroud/archive/shroud-0.13.0.pyz\n```\n\n\n## License\n\nCopyright (c) 2017-2023, Lawrence Livermore National Security, LLC.\nProduced at the Lawrence Livermore National Laboratory.\n\nSPDX-License-Identifier: (BSD-3-Clause)\n\nSee [LICENSE](./LICENSE) for details\n\nUnlimited Open Source - BSD 3-clause Distribution\n`LLNL-CODE-738041` `OCEC-17-143`\n\nSPDX usage\n------------\n\nIndividual files contain SPDX tags instead of the full license text.\nThis enables machine processing of license information based on the SPDX\nLicense Identifiers that are available here: https://spdx.org/licenses/\n\nFiles that are licensed as BSD 3-Clause contain the following\ntext in the license header:\n\nSPDX-License-Identifier: (BSD-3-Clause)\n\nExternal Packages\n-------------------\nShroud bundles some of its external dependencies in its repository. These\npackages are covered by various permissive licenses. A summary listing\nfollows. See the license included with each package for full details.\n\n[//]: # (Note: The spaces at the end of each line below add line breaks)\n\nPackageName: fruit \nPackageHomePage: https://sourceforge.net/projects/fortranxunit/ \nPackageLicenseDeclared: BSD-3-Clause \n\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Generate Fortran and Python wrappers for C and C++ Libraries",
"version": "0.13.0",
"project_urls": {
"Documentation": "http://shroud.readthedocs.io/en/develop",
"Download": "https://github.com/LLNL/shroud/archive/v0.13.0.tar.gz",
"Homepage": "http://github.gov/llnl/shroud",
"Source": "https://github.com/LLNL/shroud"
},
"split_keywords": [
"fortran",
"development"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "56478939813574785e09fe022ba3a7e417ae8536ca05467dfa3e82b70fbdc756",
"md5": "6715552dc82adcb46cbf11cee561c0c6",
"sha256": "12bd1a5f76eaa386724ed2494f9a25b784b8aa3c26fe9ca82d8423dd15aa5922"
},
"downloads": -1,
"filename": "llnl_shroud-0.13.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6715552dc82adcb46cbf11cee561c0c6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 201569,
"upload_time": "2023-10-04T21:08:23",
"upload_time_iso_8601": "2023-10-04T21:08:23.250266Z",
"url": "https://files.pythonhosted.org/packages/56/47/8939813574785e09fe022ba3a7e417ae8536ca05467dfa3e82b70fbdc756/llnl_shroud-0.13.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "90aada7036e7ae1a1cb9bf0f0c9bbd19918f1d87b2f86bc10c86851ae242b586",
"md5": "90aaa1b75175b1f083563da1043249ef",
"sha256": "1fc5dbafad86fd6137b3d739bad641beeffd60e8226f82906f5396b6cc6aeadd"
},
"downloads": -1,
"filename": "llnl-shroud-0.13.0.tar.gz",
"has_sig": false,
"md5_digest": "90aaa1b75175b1f083563da1043249ef",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 2901529,
"upload_time": "2023-10-04T21:08:29",
"upload_time_iso_8601": "2023-10-04T21:08:29.452017Z",
"url": "https://files.pythonhosted.org/packages/90/aa/da7036e7ae1a1cb9bf0f0c9bbd19918f1d87b2f86bc10c86851ae242b586/llnl-shroud-0.13.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-04 21:08:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "LLNL",
"github_project": "shroud",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "llnl-shroud"
}
JSON
