aprilasr-sys

Low-level FFI bindings for the april-asr C api (libaprilasr).

Overview

Compiles libaprilasr from source to OUT_DIR using CMake and generates bindings for April API, made available via vendored upstream source pointing at a specific commit sha as defined by the git submodule.

Requirements

Building requires the following system libraries:

• libonnxruntime
• libclang

Use locate to search for installed libraries. For example, on Linux run command locate libonnxruntime.so to determine if the ONNX Runtime is available.

Installation

To get the latest unyanked release published to crates.io:

cargo add aprilasr-sys

Or get the tip of the development branch via cargo using git:

cargo add --git https://codeberg.org/vhs/aprilasr-sys.git

It's also possible to vendor this crate:

mkdir crates && \
    (cd crates; git submodule add https://codeberg.org/vhs/aprilasr-sys)

And once cloned updating dependent's Cargo.toml manifest like:

[dependencies]
aprilasr-sys = { path = "crates/aprilasr-sys" }

Examples

For a basic usage example see examples/init.rs and run command:

cargo run --example init

You should see output like:

April ASR api v1 initialized and ready for model.

Development

First clone vendored source:

git submodule update --init --recursive

To generate bindings run command:

cargo build [--release]

To specify include directory set env APRIL_INCLUDE_DIR before running build.

To inspect bindings generated:

bat $(echo $(exa target/*/build/*/out/bindings.rs) | head -1)

Command requires bat and exa rust binaries and displays output with syntax highlighting.

Versioning

Consider using chrono to parse the date format unless april-asr adopts semantic versioning:

let date_str = "2023.05.12";
let native_date = chrono::NaiveDate::parse_from_str(date_str, "%Y.%m.%d");
p!("{:?}", native_date);

Here p! is a debug helper in build.rs and date_str represents the VERSION in vendor/april-asr/CMakeLists.txt file. With some additional work cmake-parser looks well-suited for parsing the file to get the version.

Date-based versioning is not currently implemented in the build.rs build script. Once versioning is implemented it would also ideal to use it as an input to pkg-config to scan the system for the library.

See Making a *-sys crate for other possible enhancements.

Vendoring

Because we are vendoring April ASR source using a git submodule we have the ability to update the submodule to generate new bindings when the upstream source code changes.

To view the current commit of the april-asr submodule:

git submodule status | awk '{print substr($1, 1, 7)}'

To update the submodule to the latest commit in the main branch of the submodule:

git submodule update --remote --recursive --merge

This command fetches the latest commits from the submodule's remote repository, checks out the commit referenced by the main branch, and updates the submodule in the main repository.

Releasing

Steps to package a release of this crate for crates.io:

1. Update git submodule as described in Vendoring.
2. Run cargo clean to remove existing build artifacts.
3. Run cargo build --release to update generated bindings.
4. Inspect bindings as described in Development.
5. Run cargo test to execute unit tests including bindgen.
6. Run cargo run --example init to check example.
7. Run cargo doc to generate crate docs and review them.
8. Bump the package version in Cargo.toml manifest.
9. Run cargo publish --dry-run to review your work.
10. Then cargo login and cargo publish to publish crate.

Once published visit docs.rs to review crate documentation.

Rights

Your rights to this work are hereby granted under 0BSD insofar as you agree to abide by Section 5 Paragraph 2 of the GPLv3 which defines the term "aggregate":

A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an “aggregate” if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation's users beyond what the individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate.

In other words do whatever you want with this crate but, if a larger program is created, such as when these bindings are used to create a high-level wrapper, the terms of the GPL will apply to that larger work.