https://github.com/glotzerlab/hoomd-component-template
Template repository for HOOMD-blue C++ components.
https://github.com/glotzerlab/hoomd-component-template
Last synced: 5 months ago
JSON representation
Template repository for HOOMD-blue C++ components.
- Host: GitHub
- URL: https://github.com/glotzerlab/hoomd-component-template
- Owner: glotzerlab
- License: bsd-3-clause
- Created: 2023-11-28T15:24:42.000Z (over 2 years ago)
- Default Branch: trunk
- Last Pushed: 2025-02-21T15:24:37.000Z (over 1 year ago)
- Last Synced: 2025-02-21T16:29:46.762Z (over 1 year ago)
- Language: CMake
- Size: 39.1 KB
- Stars: 2
- Watchers: 9
- Forks: 11
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# HOOMD-blue component template
`hoomd-component-template` provides a framework to develop components that extend
[**HOOMD-blue**](https://glotzerlab.engin.umich.edu/hoomd-blue/). It includes template C++ and
Python modules, an example unit test, CMake scripts to build the component, and GitHub Actions
workflows.
## Building the component
To build this component:
1. Build and install **HOOMD-blue** from source.
2. Obtain the component's source.
```
$ git clone https://github.com/glotzerlab/hoomd-component-template
```
3. Configure.
```
$ cmake -B build/hoomd-component-template -S hoomd-component-template
```
4. Build the component.
```
$ cmake --build build/hoomd-component-template
```
5. Install the component.
```
$ cmake --install build/hoomd-component-template
```
Once installed, the template is available for import via:
```
import hoomd.template
```
(replace `template` with the `COMPONENT_NAME` you set in `src/CMakeLists.txt`).
## Creating a new component
To create a new component:
1. Fork [hoomd-component-template](https://github.com/glotzerlab/hoomd-component-template/).
2. Address all **TODO** comments (including those in `.github/`)
3. Add C++ and Python files to `src/`.
4. Add unit tests in `src/pytest`.
5. Format and check code style with [prek](https://prek.j178.dev/).
## Using the provided GitHub Actions configuration
When you push your changes to GitHub, the [unit test workflow](.github/workflows/unit-test.yaml)
compile your code on the CPU (with and without MPI) and on the GPU (with and without MPI). The
workflow also executes the unit tests on the CPU. You should run GPU unit tests locally, as GitHub
does not provide free GPU runners for GitHub Actions. As a one time step, you need to navigate to
the "Actions" tab of your repository and confirm that GitHub should execute actions for your fork.
When you push a new tag, the [release workflow](.github/workflows/release.yaml) will create a
new GitHub release with automatically generated release notes.
## Maintaining your component
The HOOMD-blue developers will periodically update
[hoomd-component-template](https://github.com/glotzerlab/hoomd-component-template/), including
updates to the GitHub Actions workflow, pre-commit configuration, and CMake scripts. Merge these
changes into your fork to support the latest version of HOOMD-blue.
## Documenting and releasing your component
TODO: Document your component in `README.md` (this file) and remove documentation relevant to the
template.
When appropriate:
* Add [Sphinx](https://www.sphinx-doc.org) documentation and publish it on
[readthedocs](https://www.readthedocs.org).
* Add a [conda-forge](https://conda-forge.org/) package.
* Announce your component on the [HOOMD-blue discussion board](https://github.com/glotzerlab/hoomd-blue/discussions).