Skip to content

Latest commit

 

History

History
223 lines (169 loc) · 7.85 KB

README.md

File metadata and controls

223 lines (169 loc) · 7.85 KB
Raw

ACAP for Rust

Easy and safe ACAP apps using Rust

Important

This project is an experiment provided "as is". While we strive to maintain it, there's no guarantee of ongoing support, and it may become unmaintained in the future. Your contributions are appreciated, and feel free to fork and continue the journey if needed.

This repository provides the developer tools, libraries, and documentation that form ACAP for Rust platform. To quickly start a new app, see acap-rs-app-template.

Table of Contents

Getting started

There are multiple ways to set up a development environment, but the recommended way is using a dev container.

Dev container

The quickest way to build the hello_world example is to launch the dev container and run make build AXIS_PACKAGE=hello_world. Once it completes there should be an .eap file in target/acap:

$ ls -1 target/acap
hello_world_1_0_0_aarch64.eap

This works with any of the example applications.

Important workflows are documented in the Makefile and can now be listed with make help.

Non-dev container

If you prefer to not use dev containers, or the implementation in your favorite IDE is buggy, the app can be built using only docker:

docker build --file .devcontainer/Dockerfile --tag acap-rs .
docker run \
  --interactive \
  --rm \
  --tty \
  --user $(id -u):$(id -g) \
  --volume $(pwd):$(pwd) \
  --workdir $(pwd) \
  acap-rs \
  make build AXIS_PACKAGE=hello_world

Without container

Development environments outside containers are more difficult to reproduce and maintain. Should it nonetheless be of interest, one procedure is documented in this workflow.

Developer tools

Tools for developing ACAP apps are provided primarily as binary crates. The tools can be roughly divided into low level plumbing and high level porcelain.

All of these tools are installed in the dev container of this project. To install them in another project before they are released, use the --git option e.g. like:

cargo install --locked --git https://github.com/AxisCommunications/acap-rs.git cargo-acap-sdk

Porcelain programs

The focus of these tools are to make common things easy.

  • cargo-acap-sdk - Automation of common development workflows.
    • Status: ⚠️ Alpha
    • Documentation: README

Plumbing programs

The focus of these tools are to make less common things possible.

  • acap-ssh-utils - Utilities for interacting with Axis devices over SSH.
    • Status: ⚠️ Alpha
    • Documentation: README
  • cargo-acap-build: Build utilities for ACAP apps and other executables deployed to Axis devices.
    • Status: ⚠️ Alpha
    • Documentation: README
  • device-manager: Utilities for manipulating a single Axis device.
    • Status: ⚠️ Alpha
    • Documentation: README
  • fleet-manager: Utilities for manipulating multiple Axis devices.
    • Status: ⚠️ Alpha
    • Documentation: README

These can be installed independently and are provided as library crates too for developers who want to write their own, tailored tools.

Libraries

To make it easier to relate the Rust offering to the official offering, the library crates are grouped in a similar way as in the ACAP Native SDK APIs documentation.

Note

If an API that is important to you is missing, create or upvote the feature request for it.

ACAP Native API bindings

These are idiomatic and safe bindings for the C APIs. Each crate has a corresponding *-sys, which is omitted for brevity.

  • axevent: Bindings for the Event API.
  • axstorage: Bindings for the Edge Storage API.
  • bbox: Bindings for the Bounding Box API.
  • licensekey: Bindings for the License Key API.
  • mdb: Bindings for the Message Broker API.

VAPIX API bindings

All the VAPIX APIs are provided by a single crate:

  • acap-vapix: Bindings for various VAPIX APIs + credentials lookup.
    • Status: ⚠️ Alpha
    • Documentation: README

Other library crates

These are not closely related to any official APIs but may nonetheless be helpful in their own way:

  • acap-logging: Logging utilities for ACAP applications
    • Status: 🚧 Beta
    • Documentation: Docs.rs

Documentation

Ideally information is provided when and where the reader needs it, such as:

  • Tab completions and help texts for binaries.
  • Docstrings and doctests for libraries.

This is however not always suitable, and this section lists other sources of documentation provided by this project.

Example applications

  • axstorage_example: Writes data to files on all connected storages.
  • bounding_box_example: Draws simple overlays in video streams.
  • consume_analytics_metadata: Subscribes to analytics scene description data using mdb.
  • embedded_web_page: Bundles an embedded web page.
  • hello_world:Sets up and uses logging using common functions and acap-logging.
  • licensekey_handler:Checks if an app is licensed using licensekey.
  • reverse_proxy: Exposes HTTP and WebSocket APIs using a axum and reverse proxy configuration.
  • send_event: Sends events using axevent.
  • using_a_build_script: Generates html, lib and app manifest files using a build script.
  • vapix_access: Accesses VAPIX APIs using acap-vapix.

Troubleshooting

The docker image may fail to build with the following included in the output: /usr/bin/env: 'sh\r': No such file or directory This is likely caused by git replacing POSIX newlines with Windows newlines in which case it can be resolved by either

  • cloning the code in Windows Subsystem for Linux (WSL), or
  • reconfiguring git.

License

MIT