# 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):
    ```bash
    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:
    ```bash
    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).
    ```bash
    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).

    ```bash
    # 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`:
    ```bash
    cargo cunew .
    ```
    Or use the `templates/justfile` for the standard names:
    ```bash
    just gen-workspace
    just gen-project
    ```
1.  **Change into the new workspace or project directory:**
    For the workspace template:
    ```bash
    cd ../test_workspace
    # Adjust path if you used a different destination
    ```
    For the single-crate template:
    ```bash
    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/`.

2.  **Run the project using Cargo:**
    For the workspace template (main app):
    ```bash
    cargo run -p test-workspace
    ```
    Or run the demo app:
    ```bash
    cargo run -p test-workspace-demo
    ```
    Or run from the main app directory:
    ```bash
    cd ../test_workspace/apps/test_workspace
    cargo run
    ```
    For the single-crate template:
    ```bash
    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`).