# Build Tools and Dependencies for Macro: A Complete Developer Guide

> Explore macro build tools and dependencies including Nix, Cargo, Docker Compose, axum, and tokio. This guide details the microservices workspace setup for reproducible builds.

- Repository: [Macro/macro](https://github.com/macro-inc/macro)
- Tags: how-to-guide
- Published: 2026-08-20

---

**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`](https://github.com/macro-inc/macro/blob/main/docs/RUNNING_LOCALLY.md) and the crate manifest declared in the workspace [`Cargo.toml`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/docs/RUNNING_LOCALLY.md) and configured in [`services/sync-service/wrangler.toml`](https://github.com/macro-inc/macro/blob/main/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:

```bash
nix develop

just run_local --no-doppler

```

## Core Dependencies in the Macro Workspace

The workspace [`Cargo.toml`](https://github.com/macro-inc/macro/blob/main/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

```bash

# 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`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/services/authentication_service/src/main.rs):

```rust
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:

```rust
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`](https://github.com/macro-inc/macro/blob/main/Cargo.toml)** (workspace root) — Lists every crate, version pin, dependency feature flag, and build profile.
- **[`docs/RUNNING_LOCALLY.md`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/services/sync-service/wrangler.toml)** — Configures the Cloudflare Worker build using `cargo-zigbuild`.
- **[`packages/loro-mirror/README.md`](https://github.com/macro-inc/macro/blob/main/packages/loro-mirror/README.md)** — Documents the CRDT library used for collaborative editing.
- **[`infra/stacks/web-app/README.md`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/services/sync-service/wrangler.toml).
- The workspace [`Cargo.toml`](https://github.com/macro-inc/macro/blob/main/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`](https://github.com/macro-inc/macro/blob/main/services/authentication_service/src/main.rs).

### How many crates are defined in the Macro workspace?

The workspace [`Cargo.toml`](https://github.com/macro-inc/macro/blob/main/Cargo.toml) enumerates **more than 140** crates, covering async runtimes, cloud SDKs, serialization, image processing, payment integrations, and developer tooling.