cargo-new

Create a new Rust project with a binary target

$ cargo new [path/to/directory]

cargo new [OPTIONS] <PATH>

<PATH>
    The path to the new project directory. The last component of the path will be used as the project name, unless overridden by `--name`. For example, `cargo new my_app` creates `my_app/`, while `cargo new projects/my_app` creates `projects/my_app/`.

--bin
    Creates a binary application project (this is the default behavior). This sets up `src/main.rs`.

--lib
    Creates a library project instead of a binary. This sets up `src/lib.rs`.

--vcs <VCS>
    Initializes a new repository for the specified Version Control System. Common values are `git` (default), `hg` (Mercurial), or `none` to skip VCS initialization.

--edition <YEAR>
    Specifies the Rust edition to use for the new project (e.g., `2018`, `2021`). Defaults to the latest stable edition.

--name <NAME>
    Sets the package name in `Cargo.toml`, which can be different from the directory name. Useful if the new directory's name is not the desired package name.

--registry <REGISTRY>
    Specifies the registry to use when publishing this package.

--offline
    Run without accessing the network.

-h, --help
    Prints help information for the `cargo new` command.

-v, --verbose
    Use verbose output.

-q, --quiet
    Do not print Cargo log messages.

cargo new is a fundamental command within the Rust programming language's package manager and build system, Cargo. It is used to quickly scaffold a new Rust project, setting up the essential directory structure and initial files required for development. When executed, cargo new creates a new directory at the specified path, containing a Cargo.toml file (the project manifest) and a src directory. Inside src, it generates either a main.rs file (for a binary application, the default) or a lib.rs file (for a library). This command streamlines the initial setup process, allowing developers to immediately start writing Rust code without manually configuring the project layout or build system. It also initializes a Git repository by default, facilitating version control from the outset.

1. Rust Toolchain Required: `cargo new` relies on the Rust toolchain (including Cargo) being properly installed on your system, typically via Rustup.
2. Directory Creation: The command creates a new directory for the project. If a directory with the specified name already exists at the given path and is not empty, `cargo new` will typically fail to prevent accidental data loss.
3. Default Behaviors: By default, `cargo new` creates a binary application project and initializes a Git repository. To create a library or use a different VCS (or none), explicit options (`--lib`, `--vcs`) must be provided.

Upon execution, `cargo new my_project` typically creates the following directory and file structure:

`my_project/`
    `Cargo.toml`
    `src/`
        `main.rs` (for `--bin` or default)
        `lib.rs` (for `--lib`)
    `.git/` (if `--vcs git` or default VCS is active)

This file is the manifest for your Rust project. It contains essential metadata about the package (e.g., `name`, `version`, `authors`, `edition`) and specifies dependencies (e.g., `[dependencies]`). `cargo new` generates a basic `Cargo.toml` to get you started, which is crucial for Cargo to understand and build your project.

For a binary project (default), `main.rs` typically contains a simple "Hello, world!" program, making it runnable immediately (`cargo run`). For a library, `lib.rs` will contain a basic testable function, demonstrating how to define and use a library crate.

The `cargo new` command has been a core part of the Rust ecosystem since the early days of Cargo's development. Cargo itself was designed to manage Rust projects efficiently, and `cargo new` was fundamental to providing a standardized and easy way to bootstrap new projects. It has evolved alongside the Rust language, incorporating features like Rust Editions and improving project structure conventions, always aiming to simplify the developer's initial setup experience and streamline the development workflow.

cargo(1): The Rust package manager and build tool., cargo build(1): Compile the current package., cargo run(1): Build and execute the current package., cargo check(1): Check the current package for errors., cargo init(1): Create a new Cargo package in an existing directory.