ptex-bind

High-level cxx-based bindings for Ptex

Introduction

The src directory contains the ptex crate. The ptex crate provides a high-level safe API over the low-level ptex-sys crate.

The ptex-sys directory contains the ptex-sys crate. ptex-sys uses cxx to wrap the C++ Ptex API.

The ptex-sys crate should not be used directly.

Usage

Building the ptex-sys crates requires you to install the C++ Ptex library in order to build the ptex crate.

Add ptex to your Cargo.toml:

[dependencies]
ptex = "0.2.0"

The ptex crate is built using cargo build but you must ensure that pkg-config is able to find your Ptex installation.

If the C++ Ptex library is installed to a non-system directory then you must configure the PKG_CONFIG_PATH environment variable to point to the share/pkgconfig directory inside the Ptex installtion.

pkg-config is used by ptex-sys/build.rs in order to locate the Ptex libraries and C++ headers. If Ptex is installed to a global system location such as /usr/local then PKG_CONFIG_PATH does not need to be configured. pkg-config searches in the system locations by default.

Development

This repository provides a garden.yaml Garden recipe to automate the process of installing Ptex and building the ptex Rust crate.

Garden can be used to clone Ptex to the ptex subdirectory and install the C++ Ptex library to ptex/dist.

Garden configures the PKG_CONFIG_PATH environment variable to contain $PWD/ptex/dist/share/pkgconfig when running commands.

Run the following Garden commands to bootstrap a development environment containing Ptex so that the the ptex crate can be built.

garden grow ptex
garden build all

These commands perform the following steps:

• garden grow clones Ptex into the ptex directory using the URL configured in the garden.yaml.

• garden build all builds the C++ Ptex library, installs it to ptex/dist, configures PKG_CONFIG_PATH and LD_LIBRARY_PATH to point into ptex/dist, and builds the ptex crate using cargo build.

Testing

The test suite in the tests directory is used to validate the ptex crate. The Garden recipe contains test and check commands that are used to run the test suite and run checks over the source code.

# Run tests
garden test

# Run checks and linters
garden check

Workflow

A typical development workflow loop in this repository contains the following steps:

• Build the Ptex C++ library. (garden build ptex)

• Buid the ptex-sys low-level Ptex bindings. (garden build ptex-sys)

• Build the high-level ptex bindings. (garden build or garden build ptex))

• Run tests across all crates. (garden test)

• Run checks across all crates. (garden check)

The garden.yaml recipe provides a command to perform all of the above steps in a single shot:

# Build, test and check everything.
garden dev

Versions

The ptex crate currently tracks the latest stable Ptex version.

Branches will be created for older versions in the future when newer major or minor Ptex releases are available.

The tags in this repository correspond to the ptex crate versions. The ptex crate version will be tagged and released with a non-v0 version number that matches the underlying C++ Ptex library once the ptex crate is feature-complete.

Links

• source repository
• ptex on crates.io
• ptex-sys on crates.io
• ptex documentation
• ptex-sys documentation
• ptex C++ documentation