Skip to content

README.md

Latest commit

 

History

History
120 lines (97 loc) · 5.17 KB

README.md

File metadata and controls

120 lines (97 loc) · 5.17 KB
Raw

Generating a New Copper Project from Templates

Kickstart your Copper development by generating a new project structure using our predefined templates. This approach sets up a basic or full project skeleton, allowing you to focus on building your application logic faster.

Prerequisites

Before you begin, ensure you have the following installed:

  1. Rust and Cargo: If you don't have them, install Rustup (which includes Rust and Cargo):

    curl --proto '=https' --tlsv1.2 -sSf [https://sh.rustup.rs](https://sh.rustup.rs) | sh
# Follow the on-screen instructions

  2. cargo-generate: This Cargo subcommand is used to scaffold projects from templates. Install it using Cargo:

    cargo install cargo-generate

Generating Your Project

You can generate a new Copper project using the cargo generate command along with specific template details.

Available templates:

  • cu_project: A single-crate project for quick experiments.
  • cu_full: A multi-crate workspace with apps/ and components/ (payloads, sources, tasks, sinks).

Example: Generating a Workspace or Single-Crate Project

  1. Navigate to the Templates Directory: The templates are located within a templates subdirectory relative to this README (adjust the path if necessary).

    cd templates

  2. Run cargo generate: Execute one of the following commands to generate a workspace named test_workspace or a single-crate project named test_project in the parent directory (./ relative to templates, which means the same directory where the templates folder resides).

    # Workspace template
cargo +stable generate \
    --path cu_full \
    --name test_workspace \
    --destination . \
    --define copper_source=local \
    --define copper_root_path=../..

# Single-crate project template
cargo +stable generate \
    --path cu_project \
    --name test_project \
    --destination . \
    --define copper_source=local \
    --define copper_root_path=../..

    Explanation of Options:

    • +stable: Ensures you use the stable Rust toolchain (recommended for consistency).
    • --path cu_full (or -p cu_full): Specifies the path to the workspace template to use. The path is relative to your current directory (templates).
    • --path cu_project (or -p cu_project): Specifies the path to the single-crate template to use. The path is relative to your current directory (templates).
    • --name test_workspace or --name test_project: Sets the name of the new project directory and often influences internal project names.
    • --destination . : Specifies where the generated project directory should be created. Here, . means the current directory.
    • --define <key>=<value> (or -d <key>=<value>): Sets template variables. These are used by the template during generation.
      • copper_source=local: Indicates using a local version of Copper.
      • copper_root_path=../..: Specifies the relative path from the generated project's location back to the root of the copper-rs repository. Adjust this path if your copper-rs location differs.

    Note: If you omit the --name or --define flags, cargo-generate will interactively prompt you for values like the project name and any required template variables (like copper_root_path). Using the flags provides these values directly.

    You can also use cunew as an alias for cargo generate:

    cargo cunew .

    Or use the templates/justfile for the standard names:

    just gen-workspace
just gen-project

  3. Change into the new workspace or project directory: For the workspace template:

    cd ../test_workspace
# Adjust path if you used a different destination

    For the single-crate template:

    cd ../test_project
# Adjust path if you used a different destination

    The workspace template includes apps/ and components/ (payloads, sources, tasks, sinks) so it scales beyond a single crate. The single-crate template keeps everything under src/.

  4. Run the project using Cargo: For the workspace template (main app):

    cargo run -p test-workspace

    Or run the demo app:

    cargo run -p test-workspace-demo

    Or run from the main app directory:

    cd ../test_workspace/apps/test_workspace
cargo run

    For the single-crate template:

    cargo run

Utility Commands

The generated project includes helper commands in its justfile:

  • just log: Extract and view structured logs generated by your Copper application.
  • just cl: Extract CopperLists (sequences of operations) from the application's log output.
  • just rcfg: Generate a .dot file representing the application's execution Directed Acyclic Graph (DAG). You can use tools like Graphviz to visualize this file (e.g., dot -Tpng graph.dot -o graph.png).

Set APP_NAME=test-workspace-demo APP_DIR=test_workspace-demo to target the demo app (for example, APP_NAME=test-workspace-demo APP_DIR=test_workspace-demo just log).