From ded88bffbb9eadfcec17be716654e5cb7b74d907 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Felix=20Sp=C3=B6ttel?= <1682504+fspoettel@users.noreply.github.com> Date: Sat, 21 Oct 2023 18:40:32 +0200 Subject: [PATCH] docs: update documentation --- Cargo.toml | 6 +++ README.md | 62 ++++++++++++++----------------- src/template/commands/all.rs | 4 +- src/template/readme_benchmarks.rs | 2 +- src/template/runner.rs | 2 +- 5 files changed, 37 insertions(+), 39 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 3ec21e9..a871f8d 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -7,5 +7,11 @@ default-run = "advent_of_code" publish = false # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html +[lib] +doctest = false + +[features] +test_lib = [] + [dependencies] pico-args = "0.5.0" diff --git a/README.md b/README.md index e025563..804a017 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ This template supports all major OS (macOS, Linux, Windows). 1. Open [the template repository](https://github.com/fspoettel/advent-of-code-rust) on Github. 2. Click [Use this template](https://github.com/fspoettel/advent-of-code-rust/generate) and create your repository. 3. Clone your repository to your computer. -4. If you are solving a previous year's aoc and want to use the `aoc-cli` integration, change the `AOC_YEAR` variable in `.cargo/config.toml` to reflect that. +4. If you are solving a previous year's advent of code, change the `AOC_YEAR` variable in `.cargo/config.toml` to reflect the year you are solving. ### Setup rust ๐Ÿ’ป @@ -40,16 +40,16 @@ This template supports all major OS (macOS, Linux, Windows). cargo scaffold # output: -# Created module "src/bin/01.rs" -# Created empty input file "src/inputs/01.txt" -# Created empty example file "src/examples/01.txt" +# Created module file "src/bin/01.rs" +# Created empty input file "data/inputs/01.txt" +# Created empty example file "data/examples/01.txt" # --- # ๐ŸŽ„ Type `cargo solve 01` to run your solution. ``` -Individual solutions live in the `./src/bin/` directory as separate binaries. +Individual solutions live in the `./src/bin/` directory as separate binaries. _Inputs_ and _examples_ live in the the `./data` directory. -Every [solution](https://github.com/fspoettel/advent-of-code-rust/blob/main/src/bin/scaffold.rs#L11-L41) has _unit tests_ referencing its _example_ file. Use these unit tests to develop and debug your solution against the example input. For some puzzles, it might be easier to forgo the example file and hardcode inputs into the tests. +Every [solution](https://github.com/fspoettel/advent-of-code-rust/blob/main/src/bin/scaffold.rs#L11-L41) has _unit tests_ referencing its _example_ file. Use these unit tests to develop and debug your solution against the example input. When editing a solution, `rust-analyzer` will display buttons for running / debugging unit tests above the unit test blocks. @@ -63,19 +63,14 @@ When editing a solution, `rust-analyzer` will display buttons for running / debu cargo download # output: -# Loaded session cookie from "/Users//.adventofcode.session". -# Fetching puzzle for day 1, 2022... -# Saving puzzle description to "src/puzzles/01.md"... -# Downloading input for day 1, 2022... -# Saving puzzle input to "src/inputs/01.txt"... -# Done! +# [INFO aoc] ๐ŸŽ„ aoc-cli - Advent of Code command-line tool +# [INFO aoc_client] ๐ŸŽ… Saved puzzle to 'data/puzzles/01.md' +# [INFO aoc_client] ๐ŸŽ… Saved input to 'data/inputs/01.txt' # --- -# ๐ŸŽ„ Successfully wrote input to "src/inputs/01.txt". -# ๐ŸŽ„ Successfully wrote puzzle to "src/puzzles/01.md". +# ๐ŸŽ„ Successfully wrote input to "data/inputs/01.txt". +# ๐ŸŽ„ Successfully wrote puzzle to "data/puzzles/01.md". ``` -Puzzle descriptions are stored in `src/puzzles` as markdown files. Puzzle inputs are not checked into git. [Reasoning](https://old.reddit.com/r/adventofcode/comments/k99rod/sharing_input_data_were_we_requested_not_to/gf2ukkf/?context=3). - ### Run solutions for a day ```sh @@ -83,19 +78,17 @@ Puzzle descriptions are stored in `src/puzzles` as markdown files. Puzzle inputs cargo solve # output: +# Finished dev [unoptimized + debuginfo] target(s) in 0.13s # Running `target/debug/01` -# ๐ŸŽ„ Part 1 ๐ŸŽ„ -# -# 6 (elapsed: 37.03ยตs) -# -# ๐ŸŽ„ Part 2 ๐ŸŽ„ -# -# 9 (elapsed: 33.18ยตs) +# Part 1: 42 (166.0ns) +# Part 2: 42 (41.0ns) ``` -`solve` is an alias for `cargo run --bin`. To run an optimized version for benchmarking, append the `--release` flag. +The `solve` command runs your solution. If you set the `--release` flag, real puzzle _inputs_ will be passed to your solution, otherwise the _example_ inputs will be used. -Displayed _timings_ show the raw execution time of your solution without overhead (e.g. file reads). +If you append the `--time` flag to the command, the runner will run your code between `10` and `10.000` times - depending on execution time of first execution - and print the average execution time. + +For example, a benchmarked execution against real inputs of day 1 would look like `cargo solve 1 --release --time`. Displayed _timings_ show the raw execution time of your solution without overhead like file reads. #### Submitting solutions @@ -114,22 +107,21 @@ cargo all # ---------- # | Day 01 | # ---------- -# ๐ŸŽ„ Part 1 ๐ŸŽ„ -# -# 0 (elapsed: 170.00ยตs) -# -# ๐ŸŽ„ Part 2 ๐ŸŽ„ -# -# 0 (elapsed: 30.00ยตs) +# Part 1: 42 (19.0ns) +# Part 2: 42 (19.0ns) # <...other days...> # Total: 0.20ms ``` -`all` is an alias for `cargo run`. To run an optimized version for benchmarking, use the `--release` flag. +This runs all solutions sequentially and prints output to the command-line. Same as for the `solve` command, `--release` controls whether real inputs will be used. -_Total timing_ is computed from individual solution _timings_ and excludes as much overhead as possible. +#### Update readme benchmarks -### Run all solutions against the example input +The template can output a table with solution times to your readme. Please note that these are not "scientific" benchmarks, understand them as a fun approximation. ๐Ÿ˜‰ + +In order to generate a benchmarking table, run `cargo all --release --time`. If everything goes well, the command will output _Successfully updated README with benchmarks._ after the execution finishes. + +### Run all tests ```sh cargo test diff --git a/src/template/commands/all.rs b/src/template/commands/all.rs index 7a36929..87fc2c9 100644 --- a/src/template/commands/all.rs +++ b/src/template/commands/all.rs @@ -196,7 +196,7 @@ mod child_commands { } /// copied from: https://github.com/rust-lang/rust/blob/1.64.0/library/std/src/macros.rs#L328-L333 - #[cfg(test)] + #[cfg(feature = "test_lib")] macro_rules! assert_approx_eq { ($a:expr, $b:expr) => {{ let (a, b) = (&$a, &$b); @@ -209,7 +209,7 @@ mod child_commands { }}; } - #[cfg(test)] + #[cfg(feature = "test_lib")] mod tests { use super::parse_exec_time; diff --git a/src/template/readme_benchmarks.rs b/src/template/readme_benchmarks.rs index d5e9eb4..49750c4 100644 --- a/src/template/readme_benchmarks.rs +++ b/src/template/readme_benchmarks.rs @@ -100,7 +100,7 @@ pub fn update(timings: Vec, total_millis: f64) -> Result<(), Error> { Ok(()) } -#[cfg(test)] +#[cfg(feature = "test_lib")] mod tests { use super::{update_content, Timings, MARKER}; diff --git a/src/template/runner.rs b/src/template/runner.rs index 18cba2a..5e407eb 100644 --- a/src/template/runner.rs +++ b/src/template/runner.rs @@ -50,7 +50,7 @@ fn bench(func: impl Fn(I) -> T, input: I, base_time: &Duration) -> let _ = stdout.flush(); let bench_iterations = cmp::min( - 100000, + 10000, cmp::max( Duration::from_secs(1).as_nanos() / cmp::max(base_time.as_nanos(), 10), 10,