Skip to content

README.md

Latest commit

 

History

History
204 lines (142 loc) · 7.79 KB

README.md

File metadata and controls

204 lines (142 loc) · 7.79 KB
Raw

Local CI Scripts

This directory contains bash scripts that mirror the GitHub Actions workflow defined in .github/workflows/test.yml. These scripts allow you to run the same tests locally that run in CI, ensuring consistency between local development and the CI environment.

Quick Start

  1. Setup your environment (run once):

    ./scripts/setup.sh

  2. Run all tests (equivalent to the full CI pipeline):

    ./scripts/run-all.sh

Individual Scripts

You can also run individual test suites:

Core Development Scripts

  • setup.sh - Install dependencies and setup the development environment
  • run-all.sh - Run the complete test suite (all scripts below in sequence)

Main Scripts

  • build-and-test.sh - Build and test the native workspace, build WASM examples, and run craft
  • build.sh - Build all examples (accepts release argument for release builds), then shrink the release WASM via wasm-opt.sh

Helper Scripts

  • clippy.sh - Run Clippy linting on both native and WASM workspaces
  • fmt.sh - Check Rust code formatting
  • run-markdown.sh - Execute bash code blocks in Markdown files
  • run-tests.sh - Run integration tests for examples and end-to-end tests (reuses a running rippled, else starts one in Docker; see below)
  • docker-rippled.sh - Start/stop/check a local rippled node in Docker, pinned to the same image CI uses; also used by CI itself, so this is the only place the container's docker run/health-check/logs logic lives (start/stop/status/logs)
  • host-function-audit.sh - Audit host functions against XRPLd (requires Node.js)
  • cargo-deny.sh - Check RustSec advisories on the library workspace (requires cargo-deny)
  • wasm-opt.sh - Shrink the built release contracts in place with Binaryen's wasm-opt (run automatically at the end of build.sh; auto-installs a pinned wasm-opt via cargo if none is found, and fails the build if it can't; exits quietly when there's no release WASM to optimize). --ensure-tool resolves/installs the tool without optimizing anything.
  • benchmark-gas.sh - Measure and compare gas costs of optimized helper functions
  • generate-sfields.sh - Generate type-safe SField constants from rippled source (requires Node.js)

Usage Examples

# Setup environment (run once)
./scripts/setup.sh

# Run quick checks before committing
./scripts/fmt.sh

# Run comprehensive tests
./scripts/run-all.sh

# Build in release mode
./scripts/build.sh release

# Run only clippy checks
./scripts/clippy.sh

# Run only integration tests (reuses a running rippled, else auto-starts one in Docker)
./scripts/run-tests.sh

# Run integration tests against a rippled you're already running yourself
NO_DOCKER=true ./scripts/run-tests.sh

# Run integration tests against WASM Devnet instead
DEVNET=true ./scripts/run-tests.sh

# Manage the local Docker rippled directly
./scripts/docker-rippled.sh start   # no-op if rippled is already reachable on port 6006
./scripts/docker-rippled.sh status
./scripts/docker-rippled.sh logs
./scripts/docker-rippled.sh stop

# Run gas benchmarks (requires local rippled instance)
./scripts/benchmark-gas.sh

# Generate SField constants from rippled source
./scripts/generate-sfields.sh

# Check RustSec advisories (install cargo-deny first)
./scripts/cargo-deny.sh

Environment Variables

All scripts respect the RUSTFLAGS environment variable. By default, they set:

export RUSTFLAGS="-Dwarnings"

This matches the CI environment and ensures warnings are treated as errors.

run-tests.sh additionally respects:

  • DEVNET=true - test against WASM Devnet instead of a local node
  • NO_DOCKER=true - skip the automatic Docker rippled and test against a rippled you're already running yourself on ws://localhost:6006

Gas Benchmark Script

The benchmark-gas.sh script measures and compares gas costs of optimized helper functions:

# Run gas benchmarks (requires local rippled instance running on ws://127.0.0.1:6006)
./scripts/benchmark-gas.sh

This script:

  1. Builds the gas_benchmark contract
  2. Deploys it to a local rippled instance
  3. Executes it multiple times to measure gas consumption
  4. Generates a comparison report

Requirements for gas benchmarking:

  • Local rippled instance running on ws://127.0.0.1:6006
  • Node.js (for the benchmark runner scripts)

Output files:

  • gas_benchmark_results.json - Raw measurement data
  • GAS_BENCHMARK_REPORT.md - Formatted comparison report

Generate SFields Script

The generate-sfields.sh script generates type-safe SField constants from the rippled source code:

# Generate from default rippled repository (se/supported branch)
./scripts/generate-sfields.sh

# Generate from a specific rippled repository or branch
./scripts/generate-sfields.sh https://github.com/XRPLF/rippled/tree/develop

# Generate to a custom output file
./scripts/generate-sfields.sh https://github.com/XRPLF/rippled/tree/ripple/se/supported custom_output.rs

This script:

  1. Fetches SField definitions from rippled source (local path or GitHub URL)
  2. Generates type-safe Rust constants with proper type mappings
  3. Applies custom type overrides for special fields (TransactionType, Condition, Fulfillment)
  4. Outputs to xrpl-common-stdlib/src/sfield.rs by default

Custom type mappings:

The script automatically applies custom type mappings for fields that need specialized types:

  • TransactionType → TransactionType enum (not u16)
  • Condition → ConditionBlob (not StandardBlob)
  • Fulfillment → FulfillmentBlob (not StandardBlob)

To add more custom mappings, edit the customFieldTypes object in tools/generateSFields.js.

Requirements

  • Rust: Stable toolchain (installed automatically by setup.sh)
  • Pre-commit: For running pre-commit hooks (installed by setup.sh)
  • Node.js: Required for host function audit, gas benchmark, and integration test scripts
  • Docker: Required for run-tests.sh's default local rippled (skip with NO_DOCKER=true or DEVNET=true)

GitHub Actions Compatibility

These scripts are designed to work both locally and in GitHub Actions. The same scripts can be called from GitHub Actions workflows, ensuring perfect consistency between local and CI environments.

Troubleshooting

  • Permission denied: Run chmod +x scripts/*.sh to make scripts executable
  • Pre-commit not found: Run ./scripts/setup.sh to install dependencies
  • Node.js required: Install Node.js for the host function audit, or skip that script
  • WASM target missing: The scripts automatically install the wasm32v1-none target
  • Build pauses on "installing wasm-opt via cargo": expected on a machine with no wasm-opt; it compiles Binaryen from source once (a few minutes, needs a C++17 toolchain). Install a native Binaryen instead (brew install binaryen / apt-get install binaryen) to skip the compile, or set SKIP_WASM_OPT=true to build without the optimization step
  • Docker not found / daemon not reachable: Install/start Docker, or set NO_DOCKER=true (use your own local rippled) or DEVNET=true (use WASM Devnet)

Script Dependencies

setup.sh (run first)
├── build-and-test.sh
├── build.sh
    └── wasm-opt.sh (required; auto-installs a pinned wasm-opt via cargo)
├── check-wasm-exports.sh
├── clippy.sh
├── run-tests.sh
    └── ../build.sh (dependency)
├── fmt.sh
├── host-function-audit.sh (requires Node.js)
├── cargo-deny.sh (requires cargo-deny; library workspace only; not in run-all.sh while advisory-only)
└── run-markdown.sh

Note: Pre-commit checks are handled by the GitHub Actions workflow using pre-commit/action@v3.0.1 rather than a local script.

The run-all.sh script runs all individual scripts in the correct order.