Scarb: The Cairo Package Manager

The scarb-ui crate provides terminal user interface (TUI) primitives used by Scarb and its extensions. It serves two primary purposes:

1. User Communication: It provides a unified interface for interacting with users. Depending on the runtime configuration, it can either:
   • Render human-readable messages and interactive widgets for terminal users.
   • Print machine-parseable JSON-NL (JSON Newline) messages for automated tools.
2. CLI Argument Reuse: It provides reusable clap arguments for common tasks to ensure consistency across Scarb extensions.

The scarb-stable-hash crate provides a single function designed to implement a hasher that produces identical values across different Scarb releases. This ensures that hashes remain stable even when the Scarb tool itself is updated.

Important Considerations:

• Performance: The hasher is optimized to be fast.
• Collision Resistance: It is designed to have a low probability of collisions.
• Security: This hasher is not intended for cryptographic purposes and should not be used for security-sensitive operations.

The scarb-metadata crate provides structured access to the output generated by the scarb metadata command. This is useful for tools that need to programmatically inspect Scarb packages, dependencies, and project structures.

By default, the command feature is enabled, which provides an ergonomic interface to collect this metadata directly from the Scarb CLI.

The scarb-manifest-schema crate provides a dynamic JSON Schema representing Scarb's Scarb.toml manifest (mapping to scarb::core::TomlManifest). It is designed for developers building tools that need to interact with Scarb project configuration.

Use this crate when you need to:

• Build tooling that requires field descriptions, types, or examples of Scarb manifest keys.
• Create documentation generators that render the Scarb manifest reference.
• Implement validation logic based on the official Scarb manifest structure.

It also includes a helper utility to traverse the manifest using TOML paths.

The scarb-oracle-hint-service crate provides oracle functionality for Cairo programs executed via Scarb. It manages oracle hints and handles connections to external oracle services using various protocols.

Integrating this crate into a custom executor allows that executor to achieve feature parity with standard Scarb tools like scarb execute, cairo-test, and snforge regarding oracle support.

A workspace is a collection of one or more packages (called workspace members) managed together.

Key characteristics:

• Common Commands: You can run commands across all members using flags like scarb build --workspace.
• Shared Output: All packages share a single common output directory, which defaults to target in the workspace root.
• Metadata Sharing: Members can inherit metadata (like version or authors) from the workspace root.
• Compiler Configuration: When using a workspace, the [profile] and [cairo] sections in member manifests are ignored; only the configurations defined in the workspace root manifest are applied.

Procedural macros introduce significant overhead and complexity compared to declarative inline macros in Cairo. Before using them, consider the following:

• Compilation overhead: They require a full Rust compilation step (via Cargo) on top of the Cairo build, which significantly increases build times.
• Toolchain dependency: Users of your macro must have the Rust toolchain (Cargo) installed.
• Debugging difficulty: Errors occurring during macro expansion often surface as confusing Cairo compiler diagnostics.
• Maintenance burden: Developers must maintain knowledge of both Rust and Cairo, and manage the FFI boundary between them.

Recommendation: Prefer declarative inline macros written directly in Cairo unless you have a specific requirement that only procedural macros can fulfill.