diff --git a/docs/Writerside/hi.tree b/docs/Writerside/hi.tree index cc9ca61..7cff566 100644 --- a/docs/Writerside/hi.tree +++ b/docs/Writerside/hi.tree @@ -9,4 +9,6 @@ + + \ No newline at end of file diff --git a/docs/Writerside/topics/Manual-setup.md b/docs/Writerside/topics/Manual-setup.md index 86b9ee5..6c66f74 100644 --- a/docs/Writerside/topics/Manual-setup.md +++ b/docs/Writerside/topics/Manual-setup.md @@ -22,23 +22,12 @@ Make sure that: cargo install cargo-difftests ``` -- `cargo-difftests` supports 2 modes of collecting profiling data: For all crates, or for workspace crates only. In - practice, both of those work, but big projects that tend to have a lot of dependencies would generate substantially - larger profiles, which in turn makes their analysis much slower. So in general it is recommended to - only `-C instrument-coverage` workspace crates. +## First, a bit on the rustc wrappers {id="rustc-wrapper-difftests"} - - - - -In the case of workspace-only coverage, there is an additional package to install: - -```Bash -cargo install rustc-wrapper-difftests -``` - - - +`cargo-difftests` supports 2 modes of collecting profiling data: For all crates, or for workspace crates only. In +practice, both of those work, but big projects that tend to have a lot of dependencies would generate substantially +larger profiles, which in turn makes their analysis much slower. So in general it is recommended to +only `-C instrument-coverage` workspace crates. ## Creating the `difftests` profile @@ -135,6 +124,8 @@ The value it returns is quite important, here's what you have to keep in mind wh > let mut cmd = Command::new("..."); > cmd.envs(difftests_env.env_for_children()); > ``` +> +> More on this can be found in the [spawning subprocesses](spawning-subprocesses.md) article. {style="note"} ### `init` function parameters diff --git a/docs/Writerside/topics/multithreading.md b/docs/Writerside/topics/multithreading.md new file mode 100644 index 0000000..3eeb96a --- /dev/null +++ b/docs/Writerside/topics/multithreading.md @@ -0,0 +1,17 @@ +# On multithreading + +The way LLVM instrumentation works doesn't really lend itself well to the +multi-threading of tests, so multiple tests cannot run at the same time. +But a single test can spawn multiple threads, and the runtime will keep +track of those threads as well. + +However, those extra threads *must* finish running before the test itself +finishes. If they do not, and they are still going while the next test is +executing, they *will* interfere with that test's coverage. + +This is not a problem if all the test code is single-threaded; however, +special caution should be taken for multi-threaded tests. + +This however is different from spawning different processes, which is +supported; see the article on spawning subprocesses that should be tracked +[here](spawning-subprocesses.md). diff --git a/docs/Writerside/topics/spawning-subprocesses.md b/docs/Writerside/topics/spawning-subprocesses.md new file mode 100644 index 0000000..d169a1c --- /dev/null +++ b/docs/Writerside/topics/spawning-subprocesses.md @@ -0,0 +1,30 @@ +# Spawning subprocesses + +You can go ahead and spawn subprocesses normally; if their +coverage information should be ignored. If you however want them +to be tracked, you should pass them some environment variables. + +## Environment variables + +You can pass the required environment variables to the subprocess +like this: + +```Rust +#[test] +fn test_f() { + let env: DifftestsEnv = setup_difftests("test_f"); + let mut cmd = std::process::Command::new("exe"); + // the DifftestsEnv::env_for_children() + // method gives us the required environment variables + #[cfg(cargo_difftests)] + cmd.envs(env.env_for_children()); + cmd.spawn().unwrap().wait().unwrap(); +} +``` + +The instrumented binaries must have had coverage enabled for this to work. + +Unlike with [multithreading](multithreading.md), the subprocesses can run +even after the test has finished, and they will still be tracked. They +only have to finish before the analysis. However, leaky tests are still +a problem, and should be avoided.