Metadata-Version: 2.4
Name: ocpiupdate
Version: 0.4.1
Summary: An updater for OpenCPI Projects
Project-URL: Repository, https://gitlab.com/dawalters/ocpiupdate
Maintainer: Dom Walters
License-File: LICENSE
Keywords: ocpi,opencpi
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: lxml==5.3.0
Requires-Dist: tree-sitter-make==1.1.0
Requires-Dist: tree-sitter-xml==0.7.0
Requires-Dist: tree-sitter==0.23.2
Provides-Extra: dev
Requires-Dist: pre-commit==4.0.1; extra == 'dev'
Provides-Extra: lint-and-format
Requires-Dist: ruff==0.8.3; extra == 'lint-and-format'
Provides-Extra: static-analysis
Requires-Dist: lxml-stubs==0.5.1; extra == 'static-analysis'
Requires-Dist: mypy==1.13.0; extra == 'static-analysis'
Requires-Dist: types-tree-sitter==0.20.1.20240311; extra == 'static-analysis'
Description-Content-Type: text/markdown

# `ocpiupdate` - An updater for OpenCPI projects

[![pypi](https://img.shields.io/pypi/v/ocpiupdate)](https://pypi.org/project/ocpiupdate/)
[![release](https://gitlab.com/dawalters/ocpiupdate/-/badges/release.svg)](https://gitlab.com/dawalters/ocpiupdate/-/releases)
[![gitlab](https://gitlab.com/dawalters/ocpiupdate/badges/develop/pipeline.svg)](https://gitlab.com/dawalters/ocpiupdate/-/pipelines?page=1&scope=all&ref=develop)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)

`ocpiupdate` updates OpenCPI Projects to use style associated with newer
versions of OpenCPI.

For example:

- Using `<worker>-<model>.xml` for the Worker Description files, instead of
  `<worker>.xml`.
- Using `<component>.comp/<component>-comp.xml` for Component Specification
  files instead of `specs/<component>[-_]spec.xml`.
- Using `xml` files instead of `Makefile`s.

## Dependencies

This library requires Python 3.11 or newer. This means it doesn't support the
default system `python3` install on Ubuntu 20.04 or Ubuntu 22.04.

If you use a system with Python 3.10 or older, you need to either:

- Install a newer `python3` just for this library.
    - I'd recommend using a tool like [`uv`](https://docs.astral.sh/uv).
- Download and run the containerised version.

## Installation

### `pip`

You can install the latest release from [PyPi](https://pypi.org/project/ocpiupdate):

```bash
pip install ocpiupdate
```

Or, you can install this repository directly:

```bash
# Installs `develop` branch
pip install git+https://gitlab.com/dawalters/ocpiupdate

# Installs `v0.4.1` branch
pip install git+https://gitlab.com/dawalters/ocpiupdate@v0.4.1
```

#### Issues on Ubuntu 20.04 and 22.04

Ubuntu 20.04 and 22.04 experience segfaults when using the pre-compiled wheels
for `tree-sitter-make` that download from PyPi.

This problem is avoidable by instructing `pip` to install `tree-sitter-make`
from source. Unfortunately the source is
[missing some required include files](https://gitlab.com/dawalters/ocpiupdate/-/issues/23#note_2268462996).
This is fixable by coping the headers locally before installing:

```bash
git clone https://github.com/Freed-Wu/tree-sitter-make /tmp/tree-sitter-make
cp -rf /tmp/tree-sitter-make/src/tree_sitter /usr/local/include/.

# For `pip` when installing just `ocpiupdate
pip3 install --no-binary tree-sitter-make ocpiupdate

# Or for `uv` when developing for `ocpiupdate`
uv sync --no-binary-package tree-sitter-make
```

Note: these headers are specific to `tree-sitter-make` and could cause
conflicts when building other tree sitter bindings.

### `docker` or `podman`

The [`containers`](https://gitlab.com/dawalters/ocpiupdate/-/tree/develop/containers)
directory contains a variety of containers, relying only on a local
installation of `docker` or `podman`.

You can download built containers from the
[Gitlab Container Registry](https://gitlab.com/dawalters/ocpiupdate/container_registry).
This will happen automatically when a registry image is run:

```bash
project_directory=/path/to/project/root

container_name=registry.gitlab.com/dawalters/ocpiupdate:v0.4.1

additional_arguments="--dry-run --verbose"

# for `podman`, just replace `docker`
docker run \
    --volume "$project_directory":"$project_directory" \
    --workdir "$project_directory" \
    "$container_name" \
    "$additional_arguments"
```

See [`containers/scripts/ocpiupdate.sh`](https://gitlab.com/dawalters/ocpiupdate/-/tree/develop/containers/scripts/ocpiupdate.sh)
for a more complex example.

### Source tarball

You can download source releases from the
[Gitlab Releases page](https://gitlab.com/dawalters/ocpiupdate/-/releases).

## Configuration

Until documentation becomes available, you can follow the release posts
available on
[the OpenCPI forum](https://opencpi.dev/t/script-to-automate-updating-aspects-of-older-opencpi-projects).

This includes examples of usage, and discussion of how to write configuration
files.

## Disclaimer

This repository has no affiliation with OpenCPI.

The maintainer doesn't maintain OpenCPI.
