Keyboard shortcuts

Press or to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Stabilize cargo-script

Metadata
Point of contactEd Page
StatusProposed
FlagshipHigher-level Rust
Tracking issuerust-lang/rust-project-goals#119
Zulip channelN/A (an existing stream can be re-used or new streams can be created on request)
cargo championEd Page
lang championJosh Triplett
lang-docs championJosh Triplett
Teamscargo, compiler, lang, lang-docs
Task ownersEd Page

Summary

Stabilize support for "cargo script", the ability to have a single file that contains both Rust code and a Cargo.toml.

Motivation

Being able to have a Cargo package in a single file can reduce friction in development and communication, improving bug reports, educational material, prototyping, and development of small utilities.

The status quo

Today, at minimum a Cargo package is at least two files (Cargo.toml and either main.rs or lib.rs). The Cargo.toml has several required fields.

To share this in a bug report, people resort to

  • Creating a repo and sharing it
  • A shell script that cats out to multiple files
  • Manually specifying each file
  • Under-specifying the reproduction case (likely the most common due to being the eaisest)

To create a utility, a developer will need to run cargo new, update the Cargo.toml and main.rs, and decide on a strategy to run this (e.g. a shell script in the path that calls cargo run --manifest-path ...).

The next 6 months

Cargo and basic rustc support is already implemented on nightly. The goal is to finalize things within the rust repo and stabilize. With RFC #3502 and RFC #3503 approved, the next steps are being tracked in rust-lang/cargo#12207 and rust-lang/rust#136889(https://github.com/rust-lang/rust/issues/136889).

At a high-level, this is

  • rustfmt gracefully handling the presence of a frontmatter
  • r-a gracefully handling the presence of a frontmatter
  • Fix a known bug in rustc's lexer (rust-lang/rust#141367(https://github.com/rust-lang/rust/issues/141367)).
  • Improve error messages in Cargo

The "shiny future" we are working towards

Design axioms

  • In the trivial case, there should be no boilerplate. The boilerplate should scale with the application's complexity.
  • A script with a couple of dependencies should feel pleasant to develop without copy/pasting or scaffolding generators.
  • We don't need to support everything that exists today because we have multi-file packages.

Ownership and team asks

Tracking issue cargo#12207:

TaskOwner(s) or team(s)Notes
Discussion and moral supportTeam cargo, compiler
Ensure Cargo implementationEd Page

Implement language feature frontmatter

Tracking issue #136889(https://github.com/rust-lang/rust/issues/136889):

TaskOwner(s) or team(s)Notes
Rust-analyzer implementationEd Page
rustfmt implementationEd Page
Standard reviewsTeam compiler
Author call for testing blog postEd Page

Stabilize language feature frontmatter

TaskOwner(s) or team(s)Notes
Author Reference PREd Page
Review/revise Reference PRTeam lang-docsEric Huss
Author stabilization reportEd Page
Author stabilization PREd Page
Stabilization decisionTeam lang

Definitions

For definitions for terms used above, see the About > Team Asks page.

  • Discussion and moral support is the lowest level offering, basically committing the team to nothing but good vibes and general support for this endeavor.
  • Author RFC and Implementation means actually writing the code, document, whatever.
  • Design meeting means holding a synchronous meeting to review a proposal and provide feedback (no decision expected).
  • RFC decisions means reviewing an RFC and deciding whether to accept.
  • Org decisions means reaching a decision on an organizational or policy matter.
  • Secondary review of an RFC means that the team is "tangentially" involved in the RFC and should be expected to briefly review.
  • Stabilizations means reviewing a stabilization and report and deciding whether to stabilize.
  • Standard reviews refers to reviews for PRs against the repository; these PRs are not expected to be unduly large or complicated.
  • Prioritized nominations refers to prioritized lang-team response to nominated issues, with the expectation that there will be some response from the next weekly triage meeting.
  • Dedicated review means identifying an individual (or group of individuals) who will review the changes, as they're expected to require significant context.
  • Other kinds of decisions:
    • Lang team experiments are used to add nightly features that do not yet have an RFC. They are limited to trusted contributors and are used to resolve design details such that an RFC can be written.
    • Compiler Major Change Proposal (MCP) is used to propose a 'larger than average' change and get feedback from the compiler team.
    • Library API Change Proposal (ACP) describes a change to the standard library.

Frequently asked questions