26 releases
0.2.22 | Sep 22, 2024 |
---|---|
0.2.21 | Jun 1, 2024 |
0.2.20 | Apr 14, 2024 |
0.2.19 | Nov 2, 2023 |
0.2.1 | Jun 28, 2021 |
#30 in Cargo plugins
72KB
1.5K
SLoC
cargo-temp
A CLI tool that allows you to create a new rust project in a temporary directory with already installed dependencies.
Install
Requires Rust 1.51.
cargo install cargo-temp
If you want to use the generate
feature, Rust 1.61 is required.
cargo install --all-features cargo-temp
Or
cargo install --features generate cargo-temp
Usage
Create a new temporary project:
-
With no additional dependencies:
cargo-temp
-
With multiple dependencies:
cargo-temp rand tokio
-
When specifying a version:
cargo-temp anyhow=1.0
Using the cargo's comparison requirements:
-
Exact version:
cargo-temp anyhow==1.0.13
-
Maximal version:
cargo-temp anyhow=<1.0.2
Repositories
You can add repositories to your Cargo.toml
.
Examples:
-
HTTP:
cargo-temp anyhow=https://github.com/dtolnay/anyhow
-
SSH
cargo-temp anyhow=ssh://git@github.com/dtolnay/anyhow.git
If you have some problems to add a dependency over SSH, please refer to this: Support SSH Git URLs. If it doesn't help, please file an issue.
- Without package name
cargo-temp https://github.com/dtolnay/anyhow.git
To choose a branch or a revision:
-
Branch:
cargo-temp anyhow=https://github.com/dtolnay/anyhow.git#branch=master
-
Revision:
cargo-temp anyhow=https://github.com/dtolnay/anyhow.git#rev=7e0f77a38
Without a branch or a revision, cargo will use the default branch of the repository.
Dependencies features
You can add features to a dependency with +
.
Examples:
-
A dependency with feature
cargo-temp serde+derive
-
A dependency with version and feature
cargo-temp serde=1.0+derive
-
A repository with branch and feature
cargo-temp serde=https://github.com/serde-rs/serde#branch=master+derive
-
Without specifying package name
cargo-temp https://github.com/tokio-rs/tokio#branch=compat+io_std
If you want to add multiple features you can do it with +
, like this:
cargo-temp serde=1.0+derive+alloc
Features
The TO_DELETE file
If you change your mind and decide to keep the project, you can just delete the
TO_DELETE
file and the directory will not be deleted when the shell or the
editor exits.
Git Working Tree
You can create a git worktree from the current repository using:
cargo-temp --worktree
This will create a new working tree at the current HEAD. You can specify a branch like this:
cargo-temp --worktree <branch>
When exiting the shell (or your editor) the working tree will be cleaned up.
Equivalent to git worktree prune
.
Temporary Git Clone
If you want to create a temporary project from a Git repository, you can use the --git
option with
the repository's URL:
cargo-temp --git <url>
Cargo-temp truncates the history to the last commit by default. You can change this behavior in the config file:
- You can choose how many commits will stay in the history.
This will leave the 3 last commits of the history.git_repo_depth = 3
- If you do not want to truncate the history, you can set the
git_repo_depth
to false.git_repo_depth = false
git_repo_depth = true
is the same as the default behavior.
Benchmarking
If you want to create a temporary project with benchmarking using criterion-rs
, you
can use the --bench
option with an optional name for the benchmark file:
cargo-temp --bench my_benchmark
The resulting directory layout will look like this:
tmp-id/
├── benches
│ └── my_benchmark.rs
├── Cargo.toml
├── src
│ └── main.rs
└── TO_DELETE
This will also add these lines to the Cargo.toml
of the project:
[dev-dependencies]
criterion = "*"
[profile.release]
debug = true
[[bench]]
name = "my_benchmark"
harness = false
And finally, the benchmark file contains some imports and a Hello, world!
example:
use criterion::{black_box, criterion_group, criterion_main, Criterion};
fn criterion_benchmark(_c: &mut Criterion) {
println!("Hello, world!");
}
criterion_group!(
benches,
criterion_benchmark
);
criterion_main!(benches);
Edition
If you want to specify a specific edition for the temporary project, you can use the --edition
option:
cargo-temp --edition 2015
The available options are:
15
or2015
18
or2018
21
or2021
If the argument doesn't match these options, the default is the latest edition.
Project name
If you want to provide a specific project name, you can use the --name
option:
cargo-temp --name project
This name will be used as the suffix of the temporary project directory, like tmp-wXyZ-project
.
If you decide to preserve the project, the directory will be renamed to match the project's name.
Generate
Generate a temporary project from a template using cargo-generate
(current used version is v0.16)
For example, to create a temporary project using this template:
cargo temp generate --git https://github.com/ashleygwilliams/wasm-pack-template
Almost all the features of the cargo-generate
CLI are provided as it,
expections are:
--init
- This flag is used by cargo-temp to init the template as the temporary directory.--destination
- Since we already use--init
, this feature cannot be used with cargo-temp.--allow-commands
- Needs further investigation to avoid conflicts with cargo-temp's subprocesses.
Settings
The config file is located at {CONFIG_DIR}/cargo-temp/config.toml
.
When you run cargo-temp
for the first time it will be created automatically.
We use the XDG system for both Linux and OSX
and the Known Folder system on Windows.
Welcome message
Each time you create a temporary project, a welcome message explain how to exit the temporary project and how to preserve it when exiting.
This message is enabled by default and can be disabled using the welcome_message
setting:
welcome_message = false # You can also remove this line from the config file
Temporary project directory
The path where the temporary projects are created. Set on the cache directory by default.
temporary_project_dir = "/home/name/.cache/cargo-temp/"
If the directory doesn't exist, it will be created with all of its parent components if they are missing.
Cargo target directory
Cargo's target directory override.
This setting is unset by default and will be ignored if the CARGO_TARGET_DIR
environment variable is already set.
cargo_target_dir = "/home/name/repos/tmp"
Editor
You can use editor
to start an IDE instead of a shell
and editor_args
to provide its arguments. These settings are unset by default.
-
Example to run VS Code on Unix
editor = "/usr/bin/code" editor_args = [ "--wait", "--new-window" ]
-
Example to run VS Code on Windows
editor = "C:\\Program Files\\Microsoft VS Code\\Code.exe" editor_args = [ "--wait", "--new-window" ]
Use a VCS
By default, cargo-temp will use the default cargo VCS for your projects (which
is normally git), you can change that in the config file with the vcs
option.
vcs = "pijul"
The possible values are
- pijul
- fossil
- hg
- git
- none
The --vcs
value will be passed as is to cargo.
Confirmation prompt before deleting the project
cargo-temp will automatically delete the temporary project if the flag file TO_DELETE
exists
in the project when exiting the shell. If you prefer to enable a prompt that asks you if you want
to delete the project, you can add this to your config.toml
:
prompt = true
Subprocesses
You can spawn subprocess along your temporary shell like this:
[[subprocess]]
command = "alacritty -e cargo watch -x run"
foreground = false
The command
field is a shell command like echo Hello
.
The foreground
field allows to run the program in foreground instead of
background.
Additional settings
working_dir
overrides the default working directory. The default is to use the temporary directory that has been created.keep_on_exit
is used to keep the process alive after exiting the shell. The default is to kill the process when the shell exits. This setting doesn't work with foreground process.
Platform specific
Unix:
stdout
andstderr
settings allows enabling or disabling outputs. With a background process, the default will be false, with a foreground process, the default will be true. Thestdin
setting doesn't exist since it's always disabled.
Windows:
inherit_handles
allows handles inheritance - If this parameter is true, each inheritable handle in the calling process is inherited by the new process. If the parameter is false, the handles are not inherited (see CreateProcessW).
Examples
- Unix:
[[subprocess]] command = "cargo run" foreground = true [[subprocess]] command = "firefox" foreground = false
- Windows
[[subprocess]] command = "cargo.exe run" foreground = true [[subprocess]] command = "firefox.exe" foreground = false
Configuration file example
# Print a welcome message when creating a new temporary project. Enabled by default.
welcome-message = true
# Path where the temporary projects are created. Cache directory by default.
temporary_project_dir = "/home/me/repos/temp"
# Cargo's target directory override. Optional.
cargo_target_dir = "/home/me/repos/target"
# Open the temporary project with VS Code. Optional.
editor = "/usr/bin/code"
editor_args = ["--wait", "--new-window"]
# Specify the VCS you want to use within the project. Default is `git`.
vcs = "pijul"
# Specify the path to the directory where you want to preserve a saved project. Optional (default is `temporary_project_dir`).
preserved_project_dir = "/home/me/projects/"
# Use a confirmation prompt before deleting a project
prompt = true
# Watch over changes in the project using `cargo watch`
[[subprocess]]
command = "cargo watch"
foreground = true
Dependencies
~6–21MB
~321K SLoC