Build Tools and Dependencies for Macro: A Complete Developer Guide

Macro is a Rust-based micro-services workspace that relies on Nix, just, Cargo, and Docker Compose for reproducible builds, while pulling in more than 140 workspace crates including axum, tokio, sqlx, and AWS SDKs.

Understanding the build tools and dependencies for Macro is essential for anyone contributing to the macro-inc/macro repository. This Rust-based workspace uses a modern, fully containerized dev-stack to compile micro-services, run local infrastructure, and deploy serverless components. Below is a comprehensive breakdown of the tooling defined in docs/RUNNING_LOCALLY.md and the crate manifest declared in the workspace Cargo.toml.

Build Tools for the Macro Repository

The Macro project automates its entire developer workflow through a Nix-driven shell and a set of tightly integrated CLI tools.

Nix Development Environment

Nix provides the reproducible development environment for Macro. Entering the Nix shell (nix develop) automatically installs just, Cargo, the Rust toolchain, Bun, sqlx, Zig, and cargo-zigbuild so contributors do not need to install components manually. This setup is documented in the "Enter the Nix Shell" section of docs/RUNNING_LOCALLY.md.

just Task Runner

just is the task runner that orchestrates building services, launching Docker stacks, seeding data, and running workflow commands. Common invocations include just run_local, just stack up, and just seed-scenario. According to the Macro source code, these commands abstract the underlying cargo and docker compose calls into a single interface.

Cargo and cargo-zigbuild

Cargo is the standard Rust package manager that compiles all crates in the workspace. For cross-compilation, Macro uses cargo-zigbuild to produce binaries for the Cloudflare Workers target, which is required by the sync-service worker. This requirement is noted in the "What the Stack Rebuilds" section of docs/RUNNING_LOCALLY.md and configured in services/sync-service/wrangler.toml.

Docker Compose, Bun, and Zig

Docker Compose spins up the full local stack including PostgreSQL, Redis, LocalStack, OpenSearch, Kafka, and FusionAuth. Bun serves as the JavaScript runtime for the web front-end and auxiliary scripts. Zig is required by cargo-zigbuild for producing Wasm and Worker binaries.

To start everything after entering the Nix shell, run:

nix develop

just run_local --no-doppler

Core Dependencies in the Macro Workspace

The workspace Cargo.toml enumerates more than 140 crates. The most critical runtime and platform-level dependencies are grouped below.

Web Framework, Runtime, and Networking

• axum 0.8 — HTTP server framework used by nearly every service.
• tokio 1.43.0 — Asynchronous multi-thread runtime for I/O and background tasks.
• tower-http 0.6.1 — Middleware utilities including compression, CORS, and tracing.
• tokio-tungstenite 0.28 — WebSocket support with rustls-tls-webpki-roots.
• reqwest 0.13 — HTTP client for external APIs such as Google, GitHub, and Stripe.
• worker 0.8.1 — Cloudflare Workers SDK used by the sync-service worker.
• aws-lambda-events 0.16.0 — Typed Lambda event definitions for serverless handlers.

Data, Storage, and Serialization

• sqlx 0.8.6 — Async Postgres client with compile-time query checking.
• redis 1.0.3 — Caching and pub/sub layer.
• serde 1.0.214 and serde_json 1.0.132 — Configuration, API payload, and database row (de)serialization.
• uuid 1.15.1 — Unique identifier generation.
• chrono 0.4.39 and chrono-tz 0.10.4 — Date-time handling with timezone support.
• zip =2.4.2 — Archive handling for DOCX processing.
• bzip2 0.5.1 — Compression and decompression.

Cloud, Observability, and External APIs

• aws-sdk-* — Various 1.x versions for S3, DynamoDB, Lambda, SNS, and other AWS services.
• opentelemetry 0.31.0 and tracing 0.1.44 — Distributed tracing and observability.
• async-stripe 0.41 — Stripe billing integration, feature-gated with runtime-tokio-hyper-rustls-webpki.

Document Processing and Specialized Utilities

• pdfium-render 0.8.37 — PDF rendering for the document-text-extractor service.
• image 0.25 — Image processing such as thumbnail generation.
• loro-mirror — Local package in packages/loro-mirror providing CRDT-based data synchronization for collaborative editing.
• scraper 0.18 — HTML parsing for the unfurl-service.
• ammonia 4.1.4 and html-escape 0.2 — Sanitizing user-generated HTML.

Developer and Build Utilities

• guppy 0.17.24 — Dependency-graph analysis for the xtask tooling.
• clap 4.5.20 — Command-line parsing for CLI tools such as seed_cli and xtask.
• dotenvy 0.15.7 — Loading environment variables from .env files.
• log 0.4.26 — Logging facade used alongside tracing.
• utoipa 5.4.0 and utoipa-swagger-ui 9 — OpenAPI schema generation for Axum APIs.
• regex 1.11.1 and once_cell 1.21.3 — Pattern matching and lazy static values.
• rootcause 0.12 and rootcause-tracing 0.12.1 — Error-wrapping utilities.

How Macro Build Tools and Dependencies Work Together

The following snippets illustrate how the core tools and crates are combined in the codebase.

Starting the Full Local Stack

# Enter the reproducible Nix shell (installs just, Cargo, Docker, etc.)

nix develop

# Build all services and launch the Docker Compose stack

just run_local --no-doppler

This workflow is the primary entry point defined in docs/RUNNING_LOCALLY.md.

Axum Server with Tracing and OpenAPI

The server code pattern below appears across multiple services, such as services/authentication_service/src/main.rs:

use axum::{routing::get, Router};
use utoipa::OpenApi;
use tracing_subscriber::{layer::SubscriberExt, util::SubscriberInitExt};

#[derive(OpenApi)]
#[openapi(paths(get_health))]
struct ApiDoc;

async fn get_health() -> &'static str {
    "OK"
}

fn main() {
    tracing_subscriber::registry()
        .with(tracing_subscriber::fmt::layer())
        .init();

    let app = Router::new()
        .route("/health", get(get_health))
        .merge(utoipa_swagger_ui::swagger_ui(ApiDoc::openapi()));

    axum::Server::bind(&"0.0.0.0:8080".parse().unwrap())
        .serve(app.into_make_service())
        .await
        .unwrap();
}

Compile-Time SQL Validation with sqlx

The crates/macro_db_client crate uses sqlx for type-checked database access:

use sqlx::postgres::PgPool;
use uuid::Uuid;

#[derive(sqlx::FromRow)]
struct Document {
    id: Uuid,
    title: String,
    created_at: chrono::DateTime<chrono::Utc>,
}

async fn get_document(pool: &PgPool, doc_id: Uuid) -> Result<Document, sqlx::Error> {
    sqlx::query_as!(
        Document,
        r#"SELECT id, title, created_at FROM "Document" WHERE id = $1"#,
        doc_id
    )
    .fetch_one(pool)
    .await
}

Key Files That Define Macro Builds

• Cargo.toml (workspace root) — Lists every crate, version pin, dependency feature flag, and build profile.
• docs/RUNNING_LOCALLY.md — Central developer guide covering the Nix shell, just commands, and the Docker Compose stack.
• tooling/xtask — Custom just-driven build utilities that orchestrate dependency graphs and workspace preparation.
• services/sync-service/wrangler.toml — Configures the Cloudflare Worker build using cargo-zigbuild.
• packages/loro-mirror/README.md — Documents the CRDT library used for collaborative editing.
• infra/stacks/web-app/README.md — Describes the infrastructure stack used during local builds and tests.

Summary

• Macro is a Rust micro-services workspace whose build tools and dependencies for macro development are managed through a Nix shell, just task runner, Cargo, and Docker Compose.
• Cross-compilation for the sync-service worker relies on cargo-zigbuild and Zig, configured in services/sync-service/wrangler.toml.
• The workspace Cargo.toml declares more than 140 crates, with axum, tokio, sqlx, serde, and the AWS SDKs forming the core runtime stack.
• sqlx runs in offline mode to validate SQL queries at compile time, while opentelemetry and tracing provide observability.
• Key helper crates include utoipa for OpenAPI docs, loro-mirror for CRDT sync, and pdfium-render for PDF processing.

Frequently Asked Questions

What are the primary build tools for Macro?

Macro uses Nix for environment provisioning, just for task orchestration, Cargo for Rust compilation, and Docker Compose for local infrastructure. Cross-compilation is handled by cargo-zigbuild with Zig.

How does Macro ensure SQL queries are correct before runtime?

Macro uses sqlx 0.8.6 in offline mode. Queries are checked at compile time against the database schema, as demonstrated in crates/macro_db_client, preventing runtime SQL errors.

Which HTTP framework does Macro use for its micro-services?

Macro services are built on axum 0.8, often combined with tower-http 0.6.1 middleware and utoipa 5.4.0 for OpenAPI documentation. This pattern appears in services/authentication_service/src/main.rs.

How many crates are defined in the Macro workspace?

The workspace Cargo.toml enumerates more than 140 crates, covering async runtimes, cloud SDKs, serialization, image processing, payment integrations, and developer tooling.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}