Contributing Guide
Principles
See the core principles in the repository's README
Rust crates vs FFI libraries
The implementation of the rust crate should be completely seperate from the foreign interfaces. For example, algokit_transact does not depend on UniFFI or wasm-bindgen. Instead, there's a seperate crate algokit_transact_ffi that provides the foreign interfaces.
Development Tools and Commands
This repository provides several cargo binary commands to help with development and building packages for different languages.
Available Binary Commands
1. Package Building (build_pkgs
)
cargo pkg <package> [language]
Examples:
cargo pkg algokit_transact typescript
- Build TypeScript/WASM bindingscargo pkg algokit_transact python
- Build Python bindingscargo pkg algokit_transact swift
- Build Swift bindingscargo pkg algokit_transact
- Build all languages
2. API Tools (api_tools
)
cargo api <subcommand>
Available subcommands:
test-oas
- Test the OAS generatorformat-oas
- Format the OAS generator codelint-oas
- Lint and type-check the OAS generatorformat-algod
- Format generated Rust codegenerate-algod
- Generate algod API clientconvert-openapi
- Convert OpenAPI specification
3. Documentation Building
cargo run --bin build-docs --manifest-path docs/Cargo.toml
4. Cargo Binary Management
cargo bin <args>
5. UniFFI Bindings Generator
cargo run --bin uniffi-bindgen -- <args>
6. Pre-commit Hooks (Optional)
This repository includes pre-commit hooks that run the same checks as scripts/sanity.sh
.
Run hooks manually on all files:
pre-commit run --all-files
# or
pre-commit install # to auto run on each commit
The hooks will automatically run cargo fmt --check
, cargo clippy
, cargo check
, cargo test
, and cargo check --no-default-features --features ffi_wasm
on every commit.
Development Workflow
When Developing Core Rust Functionality
- Make changes to the core crates (e.g.,
algokit_transact
) - Run tests to ensure functionality works:
cargo test -p algokit_transact
- Test FFI layer if your changes affect the interface:
cargo test -p algokit_transact_ffi
When Developing Language Bindings
TypeScript/WASM Development
- Build the TypeScript bindings after making Rust changes:
cargo pkg algokit_transact typescript
- Run TypeScript tests:
cd packages/typescript/algokit_transact bun test
Python Development
- Build the Python bindings:
cargo pkg algokit_transact python
- Test Python bindings:
cd packages/python/algokit_transact poetry run pytest
Swift Development
- Build the Swift bindings:
cargo pkg algokit_transact swift
Testing Your Changes
-
Run Rust tests:
cargo test
-
Run specific crate tests:
cargo test -p algokit_transact cargo test -p algokit_transact_ffi
-
Run language-specific tests:
# TypeScript cd packages/typescript/algokit_transact && bun test # Python cd packages/python/algokit_transact && poetry run pytest
-
Run all tests (as done in CI):
./scripts/test-all.sh # Comprehensive test script
Or manually:
cargo test # Rust tests
cargo pkg algokit_transact typescript # Build TS
cd packages/typescript/algokit_transact && bun test # Test TS
cargo pkg algokit_transact python # Build Python
cd packages/python/algokit_transact && poetry run pytest # Test Python
Debugging Rust Code is VS Code
Prerequisites
Install the CodeLLDB extension for Visual Studio Code to debug Rust code.
Debug Configurations
The project includes pre-configured debug configurations in .vscode/launch.json
:
- Debug unit tests in algokit_transact: Debug tests for the core transaction functionality
- Debug unit tests in algokit_transact_ffi: Debug tests for the FFI bindings
How to Debug
- Set breakpoints by clicking in the gutter next to line numbers
- Go to the Debug view (
Ctrl+Shift+D
orCmd+Shift+D
) and select a configuration for the crate you want to debug - Press
F5
to start debugging - Use the debug toolbar to step through code (
F10
for step over,F11
for step into)