1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263
#![forbid(unsafe_code)] #![forbid(missing_docs)] #![forbid(warnings)] //! Ultra-Lightweight Zero-Dependency Rust Cargo Task Runner. //! //! - Platform Agnostic - runs on any platform that cargo runs on. //! - Zero-Dependency - the task manager itself installs almost instantly. //! - Rust Task Logic - stop writing separate bash and powershell scripts. //! - Take a look at the ['.cargo-task' directory](./.cargo-task) in this repo for examples. //! //! ```shell //! cargo install -f cargo-task //! cargo help task //! ``` //! //! ## Creating `cargo-task` automation tasks. //! //! ```shell //! cargo task ct-init //! cd .cargo-task //! cargo new --bin my-task //! cd .. //! cargo task my-task //! ``` //! //! - `cargo task ct-init` - creates the `.cargo-task` directory and `.gitignore`. //! - `cargo task my-task` - runs the crate named `my-task` defined in the `.cargo-task` directory. //! //! It's that simple! //! //! ## Script-like single file tasks. //! //! If you don't want to commit a whole directory / Cargo.toml etc... you can //! specify cargo-task tasks as single files. //! //! Just create a file in your `.cargo-task` directory named something like //! `my-task.ct.rs` and write it as you would a `main.rs`. //! //! This will also create a `my-task` cargo task. You can even specify cargo //! crate dependencies via AtAt directive `@ct-cargo-deps@` (see below). //! //! ## Customizing how tasks are executed. //! //! `cargo-task` uses a metadata format called AtAt - because it uses `@` signs: //! //! ```ignore //! /* //! @ct-default@ true @@ //! @ct-task-deps@ //! one //! two //! @@ //! */ //! ``` //! //! Some things to know about AtAt: //! - protocol: `@key@ value @@`. //! - the first `@` for the key must be the first character on a line. //! - the value is terminated by a two ats, "`@@`". //! - the value can contain newlines or be on a single line. //! - you probably want it in a rust comment block : ) //! //! These directives will be read from your `main.rs` file when parsing the //! `.cargo-task` crates. //! //! ### Default tasks. //! //! ```ignore //! /* //! @ct-default@ true @@ //! */ //! ``` //! //! Default tasks will be executed if the task list is empty on `cargo task` //! invocations. //! //! ### Bootstrap tasks. //! //! ```ignore //! /* //! @ct-bootstrap@ true @@ //! */ //! ``` //! //! Bootstrap tasks will *always* be executed before any task-list tasks. //! Also, the cargo-task metadata will be reloaded after bootstrap tasks //! are executed. You can use this to download / install / configure //! additional tasks. //! //! ### Cargo dependencies. //! //! ```ignore //! /* //! @ct-cargo-deps@ //! num_cpus = "1" //! serde = { version = "1", features = [ "derive" ] } //! @@ //! */ //! ``` //! //! Write them just as you would in your Cargo.toml. //! //! ### Task dependencies. //! //! ```ignore //! /* //! @ct-task-deps@ //! my-first-dependency //! my-second-dependency //! @@ //! */ //! ``` //! //! A whitespace delimited list of tasks that must be run prior to the current //! task. Can be on a single line or multiple lines. //! //! ### Minimum cargo-task version. //! //! ```ignore //! /* //! @ct-min-version@ 0.0.7 @@ //! */ //! ``` //! //! Require at least a minimum version of cargo-task to prompt users //! to upgrade if you are depending on features. //! Note, this directive works well when combined with `@ct-bootstrap@` //! //! ## The magic `cargo_task_util` dependency. //! //! - [cargo_task_util on docs.rs](https://docs.rs/cargo-task/latest/cargo_task/_cargo_task_util/index.html) //! //! This module will be available at the root of your crate during build time. //! To include it, simply add a `mod` directive in your `main.rs` file. //! A crate dependency with the same pub contents of this module will be //! available to your crate a run-time. The dependency is automatically added //! to script-type tasks. //! //! To add it to crate-type tasks simply include the dependency in your //! Cargo.toml: //! //! ```ignore //! [dependencies] //! cargo_task_util = "*" //! ``` //! //! ```ignore //! /* //! @ct-default@ true @@ //! */ //! //! use cargo_task_util::*; //! //! fn main() { //! // cargo task metadata env helper //! let env = ct_env(); //! //! // print out some cool cargo-task metadata //! // (this does the same thing as `cargo task ct-meta`) //! println!("{:#?}", env); //! //! // also includes cargo-task special log helpers //! ct_warn!("ahh, a warning! {:?}", std::time::SystemTime::now()); //! } //! ``` //! //! ### Configuring tasks and the `cargo_task_util` crate for direct execution. //! //! So, you want to run your cargo tasks directly? The `cargo_task_util` crate //! is generated into your .cargo-task directory, but is ignored from git //! by a `.cargo-task/.gitignore` file. You can delete the .gitignore lines //! to check the crate into version control. //! //! Due to a windows pathing quirk, we need to use a workspace-level `[patch]` //! directive to make this dependency work. //! //! If you want a root workspace `Cargo.toml`, you can create one at the root //! of your project, and include all your crates, and your task crates. //! //! If, instead, you want to keep the task crates in a separate workspace, //! you can put a workspace `Cargo.toml` file in your `.cargo-task` directory. //! (You will also need to remove that line from your `.cargo-task/.gitignore`) //! //! This example is for a `.cargo-task/Cargo.toml` workspace. If your workspace //! root is a different directory, you'll have to adjust the paths. //! //! ```ignore //! [workspace] //! members = [ //! "cargo_task_util", //! "my_task_crate", //! ] //! //! [patch.crates-io] //! cargo_task_util = { path = "cargo_task_util" } //! ``` //! //! ## Exporting environment variables to configure other tasks. //! //! `cargo_task_util::CTEnv` also includes a utility for exporting environment //! variables. //! //! If you just use the rust `std::env::set_var` function, the variable will //! be set for the current task execution, but no other tasks will see it. //! //! Instead you can use `cargo_task_util::CTEnv::set_env` function. //! //! You probably want to do this in a "bootstrap" task so it is available //! to other tasks that are run later. //! //! ```ignore //! /* //! @ct-bootstrap@ true @@ //! */ //! //! mod cargo_task_util; //! use cargo_task_util::*; //! //! fn main() { //! // cargo task metadata env helper //! let env = ct_env(); //! //! // set a variable that will be available in other tasks. //! env.set_env("MY_VARIABLE", "MY_VALUE"); //! } //! ``` pub mod _cargo_task_util; pub mod at_at; mod env_loader; mod task; #[cfg(windows)] include!(concat!(env!("OUT_DIR"), "\\ver.rs")); #[cfg(not(windows))] include!(concat!(env!("OUT_DIR"), "/ver.rs")); /// The .cargo-task directory name const CARGO_TASK_DIR: &str = ".cargo-task"; /// The .cargo-task/.gitignore file #[cfg(windows)] const CT_DIR_GIT_IGNORE: &str = ".cargo-task\\.gitignore"; #[cfg(not(windows))] const CT_DIR_GIT_IGNORE: &str = ".cargo-task/.gitignore"; /// Source content of .cargo-task/.gitignore for 'ct-init' #[cfg(windows)] const CT_DIR_GIT_IGNORE_SRC: &[u8] = include_bytes!(concat!( env!("CARGO_MANIFEST_DIR"), "\\.cargo-task\\.gitignore" )); #[cfg(not(windows))] const CT_DIR_GIT_IGNORE_SRC: &[u8] = include_bytes!(concat!( env!("CARGO_MANIFEST_DIR"), "/.cargo-task/.gitignore" )); /// Source-code content of cargo_task_util.rs const CARGO_TASK_UTIL_SRC: &[u8] = include_bytes!("_cargo_task_util.rs"); mod exec; pub use exec::*;