# thruput-native-exec
A native execution environment for testing Thruput contracts in-process. Tests
deploy contracts into an in-memory Thruput instance, run transactions against
them, and assert on events, return values, exceptions and faults, with no
guest build. Contract crates normally reach it through `thruput-sdk`'s `dev`
feature rather than depending on it directly:
```toml
[dev-dependencies]
my-contract = { path = ".", features = ["dev"] } # where `dev` enables thruput-sdk/dev
```
The executor itself is a native library, the Thruput test FFI, which the
`thruput-sys` crate binds and links. The rest of this page covers how
`thruput-sys` obtains that library. Its build script picks one of three ways,
selected by environment variables.
## Default Behavior
**On supported platforms** (x86_64 Linux, aarch64 Linux, aarch64 macOS), the
build script **automatically downloads** prebuilt libraries from
a public S3 bucket. No environment variables, extra features, or hogd checkout
are required.
**On unsupported platforms**, you must use the build-from-source or custom
library path described below.
## Build Methods
### 1. Download Prebuilt Library (Default on Supported Platforms)
```bash
# No environment variable needed
cargo build
```
This will automatically:
- Download the prebuilt tarball from public S3 using `curl`
- Verify the SHA256 checksum
- Assert the archive contains exactly the expected files, then extract and
link the library
- Copy the bundled `bindings.rs` from the tarball (no hogd checkout needed)
**Supported platforms:**
- Linux x86_64: `libtest_ffi-linux-x86_64.tar.gz`
- Linux ARM64: `libtest_ffi-linux-arm64.tar.gz`
- macOS ARM64: `libtest_ffi-macos-arm64.tar.gz`
Downloads are public and require no authentication or AWS credentials.
### 2. Build from Source (Maintainer Workflow)
This path is for working on the executor itself or for unsupported
platforms. It needs CMake, a C++ toolchain, libclang and ccache.
Building from source needs two things: the `source-build` cargo feature
(which makes the `cmake` and `bindgen` build-dependencies available — they
are not compiled on the default path) and the `HOGD_FFI_BUILD=1` environment
variable (which selects the source build for this invocation):
```bash
# Building thruput-sys / native-exec directly:
HOGD_FFI_BUILD=1 cargo build -p thruput-sys --features source-build
# From a contract crate that uses the SDK's dev/mock features for testing,
# the feature is forwarded through the SDK:
HOGD_FFI_BUILD=1 cargo test --features thruput-sdk/source-build
```
The feature is forwarded along the dependency chain
`thruput-sdk/source-build` → `thruput-native-exec/source-build` →
`thruput-sys/source-build`. If you build from source routinely, enable
`source-build` permanently in your manifest's feature forwarding and just
toggle `HOGD_FFI_BUILD=1` per invocation — with the feature on but the
environment variable unset, you still get the prebuilt download.
This will:
- Clone hogd at the matching `test-ffi-v{VERSION}` tag under the system
temporary directory, or use the checkout at `HOGD_SRC` if set, and verify
the tag. Keep a `HOGD_SRC` checkout outside this SDK tree, so the two
Cargo configurations stay separate
- Generate bindings using bindgen from the hogd header file
- Build the library using CMake (requires CMake, a C++ toolchain, and ccache)
Setting `HOGD_FFI_BUILD=1` without the `source-build` feature fails
immediately with instructions, rather than silently falling back to the
prebuilt download.
**Use this when:**
- You're on an unsupported platform
- You want to build with custom flags or modifications
- You're developing changes to the C++ code
### 3. Use Custom Library Path (Override)
```bash
export HOGD_FFI_LIB_DIR=/path/to/lib
cargo build
```
This will:
- Use a prebuilt library from the specified directory, which must contain
the appropriate library file for your platform and a matching
`bindings.rs`
- Override the default prebuilt download behavior
### 4. Documentation Builds (docs.rs)
docs.rs builds without network access. When `DOCS_RS` is set, the build
script copies the checked-in `crates/thruput-sys/docs-rs/bindings.rs` and skips
acquiring and linking the library; rustdoc needs neither. Every other build
method writes its own bindings. The `docs_rs_bindings` test in `thruput-sys`
fails when the checked-in copy differs from the linux-x86_64 archive's
`bindings.rs`.
## Additional Environment Variables
- `HOGD_SRC`: Path to a hogd checkout for source builds (cloned on demand
if unset)
- `HOGD_DOWNLOAD_CACHE_DIR`: Override the prebuilt download cache location
(default: under `OUT_DIR`)
- `NATIVE_EXEC_ALWAYS_CONFIGURE`: Force CMake reconfiguration when building
from source
## Version Management
The version is managed differently depending on the build path:
### Prebuilt Download Path (default)
Uses the `TEST_FFI_VERSION` constant in `crates/thruput-sys/build.rs` to
determine which release to download. The prebuilt tarball includes both the
library and a pre-generated `bindings.rs`, so no hogd checkout is needed.
Current version: **0.42.0** (tag: `test-ffi-v0.42.0`)
### Source / Custom-lib-dir Path
Parses the version from `hogd/test_ffi/test_bindings.h` by reading the
following constants:
- `TEST_FFI_VERSION_MAJOR`
- `TEST_FFI_VERSION_MINOR`
- `TEST_FFI_VERSION_PATCH`
These are combined to form the version string (e.g., `0.42.0`) and used to:
1. Cross-check against `TEST_FFI_VERSION` in build.rs (must match)
2. Verify the hogd checkout is at the correct git tag (`test-ffi-v{VERSION}`)
If the version doesn't match, the build will fail with instructions to check
out the correct tag.
### Updating the Version
When updating to a new test_ffi version:
1. Update `TEST_FFI_VERSION` in `crates/thruput-sys/build.rs`
2. Update the version in this README
## Error Handling
The build script will **fail with a clear error message** if:
- Multiple build methods are specified
- The platform is unsupported and no override is given
- `HOGD_FFI_BUILD=1` is set without the `source-build` feature
- The hogd version tag doesn't match
- A download fails, checksums don't match, or the archive contains anything
other than the expected files
- Required files are missing
This is intentional to prevent silent failures and ensure reproducible builds.
## Prebuilt Releases
Prebuilt libraries are published to:
`https://groundhog-public-release-artifacts-017820684264.s3.us-west-2.amazonaws.com/test-ffi/test-ffi-v{VERSION}/`
Each release includes, per platform:
- `libtest_ffi-<platform>.tar.gz` (+ `.sha256`)