Build System and Build Tools in macro-inc/macro: A Complete Guide

The macro-inc/macro repository uses the Just command runner as its primary build orchestration tool alongside Cargo, with a root justfile defining recipes that compile, test, and package over 80 Rust crates across the workspace.

The macro-inc/macro codebase is a Rust-centric monorepo organized as a Cargo workspace containing more than 80 individual crates. Understanding the build system and build tools used in this project is essential for compiling microservices, running integration tests, or packaging Lambda functions for deployment. The repository leverages just—a modern command runner—as its primary task orchestrator, while relying on Cargo for the actual Rust compilation.

The Primary Build Orchestrator: Just

At the heart of the build system is just, a command runner that provides concise, script-like recipes for common development tasks. Unlike traditional build systems, just focuses on running commands rather than managing dependencies or compilation units, making it ideal for coordinating a complex Cargo workspace.

The repository contains a top-level justfile that defines high-level recipes for building, testing, and packaging all services. These recipes invoke standard Cargo commands (cargo build, cargo test, cargo fmt, etc.) to compile individual crates, while also handling auxiliary tasks like Docker container management and Lambda artifact packaging.

Rust Compilation with Cargo Workspaces

While just handles orchestration, Cargo performs the actual compilation work. The root Cargo.toml defines the workspace structure, enumerating all member crates across the services/, crates/, and infra/ directories. When you run a just recipe, it ultimately calls Cargo with appropriate flags for the entire workspace or specific subsets of crates.

This separation of concerns allows developers to use just for high-level workflows while retaining direct access to Cargo for low-level build control when needed.

Essential Build Commands and Workflows

The root justfile provides standardized recipes for common development tasks. Here are the primary build commands available:

• just build — Compiles every crate in the workspace in debug mode by running cargo build --workspace, producing binaries and libraries for the entire system.

• just build_lambdas — Builds only the Lambda functions using cargo build --release for each Lambda crate, then packages the artifacts for AWS deployment.

• just check — Performs static analysis with cargo check, providing fast type-checking without producing final binaries.

• just test — Starts required Docker containers (Postgres, OpenSearch, etc.) and executes cargo test --workspace to run the full test suite.

• just fmt — Invokes cargo fmt to automatically format all Rust source files according to the project style guidelines.

• just clippy — Runs cargo clippy with the repository’s recommended lint configuration to catch common mistakes and anti-patterns.

To execute any of these commands, run them from the repository root:

# Build everything in debug mode

just build

# Run static analysis without full compilation

just check

# Start dependencies and run all tests

just test

Service-Specific Build Configuration

For developers working on individual microservices, the repository provides granular control through service-specific justfiles located in each service directory.

For example, to build only the email service, navigate to its directory and invoke the local justfile:

cd services/email_service
just build

According to the macro-inc/macro source code, these service-specific configurations reside at paths like services/email_service/justfile and services/document_storage_service/justfile. Similarly, infrastructure components maintain their own build scripts, such as the justfile located at infra/stacks/macrodb/justfile for the MacroDB stack.

Key Build System Files

Several configuration files define the build behavior across the repository:

• justfile (root) — The central orchestration file defining main recipes for the entire workspace, including build, test, and deployment commands.

• Cargo.toml (root) — Declares the Cargo workspace and lists all member crates, establishing the dependency graph for the build system.

• services/*/justfile — Service-specific recipes for building, packaging, or running individual microservices like the email service or document storage service.

• crates/*/Cargo.toml — Individual crate manifest files (e.g., crates/email/Cargo.toml) that define dependencies, features, and build settings for each component.

• infra/stacks/*/justfile — Build and deployment scripts for infrastructure components, handling provisioning tasks alongside Rust compilation.

Summary

• The macro-inc/macro repository uses just as its primary task runner and Cargo as its Rust compiler, creating a hybrid build system optimized for a monorepo structure.
• The root justfile provides standardized recipes including just build, just test, and just build_lambdas for workspace-wide operations.
• Service-specific justfiles in directories like services/email_service/ allow targeted builds of individual microservices without compiling the entire workspace.
• The build system integrates Docker container management for integration testing and specialized packaging for AWS Lambda deployment.
• Key configuration files include the root justfile, root Cargo.toml, and individual manifests scattered throughout the crates/ and services/ directories.

Frequently Asked Questions

What build system does macro-inc/macro use?

The repository uses a combination of Just (a command runner) and Cargo (Rust's package manager and build tool). Just provides the high-level orchestration through recipes defined in justfiles, while Cargo handles the actual compilation of Rust code across the workspace's 80+ crates.

How do I build only one service instead of the entire workspace?

Navigate to the specific service directory and run just build from there. For example, execute cd services/email_service && just build to compile only the email service using that directory's local justfile, avoiding the overhead of building the entire workspace.

Are Make or CMake used in the macro-inc/macro build system?

No, the repository explicitly uses just instead of Make or CMake for task running. The justfile syntax is similar to Makefiles but designed specifically for running commands rather than tracking file dependencies, making it better suited for orchestrating Cargo builds and Docker workflows.

What command builds Lambda functions for deployment?

Run just build_lambdas from the repository root. This recipe executes cargo build --release for each Lambda-specific crate and handles the subsequent packaging of artifacts required for AWS deployment, streamlining the serverless release process.

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