Skip to content

Commit

Permalink
Document various parts of compiletest's lib.rs
Browse files Browse the repository at this point in the history
  • Loading branch information
@Zalathar
Zalathar committed Oct 14, 2024
1 parent f6648f2 commit cec5986
Showing 1 changed file with 114 additions and 13 deletions.
127 changes: 114 additions & 13 deletions src/tools/compiletest/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,11 @@ use crate::common::{
use crate::header::HeadersCache;
use crate::util::logv;

/// Creates the `Config` instance for this invocation of compiletest.
///
/// The config mostly reflects command-line arguments, but there might also be
/// some code here that inspects environment variables or even runs executables
/// (e.g. when discovering debugger versions).
pub fn parse_config(args: Vec<String>) -> Config {
let mut opts = Options::new();
opts.reqopt("", "compile-lib-path", "path to host shared libraries", "PATH")
Expand Down Expand Up @@ -413,6 +418,7 @@ pub fn opt_str2(maybestr: Option<String>) -> String {
}
}

/// Called by `main` after the config has been parsed.
pub fn run_tests(config: Arc<Config>) {
// If we want to collect rustfix coverage information,
// we first make sure that the coverage file does not exist.
Expand Down Expand Up @@ -454,6 +460,8 @@ pub fn run_tests(config: Arc<Config>) {
configs.push(config.clone());
};

// Discover all of the tests in the test suite directory, and build a libtest
// structure for each test (or each revision of a multi-revision test).
let mut tests = Vec::new();
for c in configs {
let mut found_paths = HashSet::new();
Expand All @@ -463,7 +471,12 @@ pub fn run_tests(config: Arc<Config>) {

tests.sort_by(|a, b| a.desc.name.as_slice().cmp(&b.desc.name.as_slice()));

// Delegate to libtest to filter and run the big list of structures created
// during test discovery. When libtest decides to run a test, it will invoke
// the corresponding closure created by `make_test_closure`.
let res = test::run_tests_console(&opts, tests);

// Check the outcome reported by libtest.
match res {
Ok(true) => {}
Ok(false) => {
Expand Down Expand Up @@ -532,6 +545,11 @@ pub fn test_opts(config: &Config) -> test::TestOpts {
}
}

/// Creates libtest structures for every test/revision in the test suite directory.
///
/// This always inspects _all_ test files in the suite (e.g. all 17k+ ui tests),
/// regardless of whether any filters/tests were specified on the command-line,
/// because filtering is handled later by libtest.
pub fn make_tests(
config: Arc<Config>,
tests: &mut Vec<test::TestDescAndFn>,
Expand Down Expand Up @@ -610,10 +628,17 @@ fn common_inputs_stamp(config: &Config) -> Stamp {
stamp
}

/// Returns a list of modified/untracked test files that should be run when
/// the `--only-modified` flag is in use.
///
/// (Might be inaccurate in some cases.)
fn modified_tests(config: &Config, dir: &Path) -> Result<Vec<PathBuf>, String> {
// If `--only-modified` wasn't passed, the list of modified tests won't be
// used for anything, so avoid some work and just return an empty list.
if !config.only_modified {
return Ok(vec![]);
}

let files =
get_git_modified_files(&config.git_config(), Some(dir), &vec!["rs", "stderr", "fixed"])?
.unwrap_or(vec![]);
Expand All @@ -634,6 +659,8 @@ fn modified_tests(config: &Config, dir: &Path) -> Result<Vec<PathBuf>, String> {
Ok(full_paths)
}

/// Recursively scans a directory to find test files and create test structures
/// that will be handed over to libtest.
fn collect_tests_from_dir(
config: Arc<Config>,
cache: &HeadersCache,
Expand All @@ -650,6 +677,8 @@ fn collect_tests_from_dir(
return Ok(());
}

// For run-make tests, a "test file" is actually a directory that contains
// an `rmake.rs` or `Makefile`"
if config.mode == Mode::RunMake {
if dir.join("Makefile").exists() && dir.join("rmake.rs").exists() {
return Err(io::Error::other(
Expand All @@ -663,6 +692,7 @@ fn collect_tests_from_dir(
relative_dir: relative_dir_path.parent().unwrap().to_path_buf(),
};
tests.extend(make_test(config, cache, &paths, inputs, poisoned));
// This directory is a test, so don't try to find other tests inside it.
return Ok(());
}
}
Expand All @@ -677,22 +707,27 @@ fn collect_tests_from_dir(
fs::create_dir_all(&build_dir).unwrap();

// Add each `.rs` file as a test, and recurse further on any
// subdirectories we find, except for `aux` directories.
// subdirectories we find, except for `auxiliary` directories.
// FIXME: this walks full tests tree, even if we have something to ignore
// use walkdir/ignore like in tidy?
for file in fs::read_dir(dir)? {
let file = file?;
let file_path = file.path();
let file_name = file.file_name();

if is_test(&file_name) && (!config.only_modified || modified_tests.contains(&file_path)) {
// We found a test file, so create the corresponding libtest structures.
debug!("found test file: {:?}", file_path.display());

// Record the stem of the test file, to check for overlaps later.
let rel_test_path = relative_dir_path.join(file_path.file_stem().unwrap());
found_paths.insert(rel_test_path);

let paths =
TestPaths { file: file_path, relative_dir: relative_dir_path.to_path_buf() };

tests.extend(make_test(config.clone(), cache, &paths, inputs, poisoned))
} else if file_path.is_dir() {
// Recurse to find more tests in a subdirectory.
let relative_file_path = relative_dir_path.join(file.file_name());
if &file_name != "auxiliary" {
debug!("found directory: {:?}", file_path.display());
Expand Down Expand Up @@ -728,13 +763,18 @@ pub fn is_test(file_name: &OsString) -> bool {
!invalid_prefixes.iter().any(|p| file_name.starts_with(p))
}

/// For a single test file, creates one or more test structures (one per revision)
/// that can be handed over to libtest to run, possibly in parallel.
fn make_test(
config: Arc<Config>,
cache: &HeadersCache,
testpaths: &TestPaths,
inputs: &Stamp,
poisoned: &mut bool,
) -> Vec<test::TestDescAndFn> {
// For run-make tests, each "test file" is actually a _directory_ containing
// an `rmake.rs` or `Makefile`. But for the purposes of directive parsing,
// we want to look at that recipe file, not the directory itself.
let test_path = if config.mode == Mode::RunMake {
if testpaths.file.join("rmake.rs").exists() && testpaths.file.join("Makefile").exists() {
panic!("run-make tests cannot have both `rmake.rs` and `Makefile`");
Expand All @@ -750,45 +790,66 @@ fn make_test(
} else {
PathBuf::from(&testpaths.file)
};

// Scan the test file to discover its revisions, if any.
let early_props = EarlyProps::from_file(&config, &test_path);

// Incremental tests are special, they inherently cannot be run in parallel.
// `runtest::run` will be responsible for iterating over revisions.
// Normally we create one libtest structure per revision, with two exceptions:
// - If a test doesn't use revisions, create a dummy revision (None) so that
// the test can still run.
// - Incremental tests inherently can't run their revisions in parallel, so
// we treat them like non-revisioned tests here. Incremental revisions are
// handled internally by `runtest::run` instead.
let revisions = if early_props.revisions.is_empty() || config.mode == Mode::Incremental {
vec![None]
} else {
early_props.revisions.iter().map(|r| Some(r.as_str())).collect()
};

// For each revision (or the sole dummy revision), create and return a
// `test::TestDescAndFn` that can be handed over to libtest.
revisions
.into_iter()
.map(|revision| {
// Create a test name and description to hand over to libtest.
let src_file =
std::fs::File::open(&test_path).expect("open test file to parse ignores");
let test_name = crate::make_test_name(&config, testpaths, revision);
// Create a libtest description for the test/revision.
// This is where `ignore-*`/`only-*`/`needs-*` directives are handled,
// because they need to set the libtest ignored flag.
let mut desc = make_test_description(
&config, cache, test_name, &test_path, src_file, revision, poisoned,
);
// Ignore tests that already run and are up to date with respect to inputs.

// If a test's inputs haven't changed since the last time it ran,
// mark it as ignored so that libtest will skip it.
if !config.force_rerun
&& is_up_to_date(&config, testpaths, &early_props, revision, inputs)
{
desc.ignore = true;
// Keep this in sync with the "up-to-date" message detected by bootstrap.
desc.ignore_message = Some("up-to-date");
}
test::TestDescAndFn {
desc,
testfn: make_test_closure(config.clone(), testpaths, revision),
}

// Create the callback that will run this test/revision when libtest calls it.
let testfn = make_test_closure(config.clone(), testpaths, revision);

test::TestDescAndFn { desc, testfn }
})
.collect()
}

/// The path of the `stamp` file that gets created or updated whenever a
/// particular test completes successfully.
fn stamp(config: &Config, testpaths: &TestPaths, revision: Option<&str>) -> PathBuf {
output_base_dir(config, testpaths, revision).join("stamp")
}

/// Returns a list of files that, if modified, would cause this test to no
/// longer be up-to-date.
///
/// (Might be inaccurate in some cases.)
fn files_related_to_test(
config: &Config,
testpaths: &TestPaths,
Expand Down Expand Up @@ -824,53 +885,71 @@ fn files_related_to_test(
related
}

/// Checks whether a particular test/revision is "up-to-date", meaning that no
/// relevant files/settings have changed since the last time the test succeeded.
///
/// (This is not very reliable in some circumstances, so the `--force-rerun`
/// flag can be used to ignore up-to-date checking and always re-run tests.)
fn is_up_to_date(
config: &Config,
testpaths: &TestPaths,
props: &EarlyProps,
revision: Option<&str>,
inputs: &Stamp,
inputs: &Stamp, // Last-modified timestamp of the compiler, compiletest etc
) -> bool {
let stamp_name = stamp(config, testpaths, revision);
// Check hash.
// Check the config hash inside the stamp file.
let contents = match fs::read_to_string(&stamp_name) {
Ok(f) => f,
Err(ref e) if e.kind() == ErrorKind::InvalidData => panic!("Can't read stamp contents"),
// The test hasn't succeeded yet, so it is not up-to-date.
Err(_) => return false,
};
let expected_hash = runtest::compute_stamp_hash(config);
if contents != expected_hash {
// Some part of compiletest configuration has changed since the test
// last succeeded, so it is not up-to-date.
return false;
}

// Check timestamps.
// Check the timestamp of the stamp file against the last modified time
// of all files known to be relevant to the test.
let mut inputs = inputs.clone();
for path in files_related_to_test(config, testpaths, props, revision) {
inputs.add_path(&path);
}

// If no relevant files have been modified since the stamp file was last
// written, the test is up-to-date.
inputs < Stamp::from_path(&stamp_name)
}

/// The maximum of a set of file-modified timestamps.
#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
struct Stamp {
time: SystemTime,
}

impl Stamp {
/// Creates a timestamp holding the last-modified time of the specified file.
fn from_path(path: &Path) -> Self {
let mut stamp = Stamp { time: SystemTime::UNIX_EPOCH };
stamp.add_path(path);
stamp
}

/// Updates this timestamp to the last-modified time of the specified file,
/// if it is later than the currently-stored timestamp.
fn add_path(&mut self, path: &Path) {
let modified = fs::metadata(path)
.and_then(|metadata| metadata.modified())
.unwrap_or(SystemTime::UNIX_EPOCH);
self.time = self.time.max(modified);
}

/// Updates this timestamp to the most recent last-modified time of all files
/// recursively contained in the given directory, if it is later than the
/// currently-stored timestamp.
fn add_dir(&mut self, path: &Path) {
for entry in WalkDir::new(path) {
let entry = entry.unwrap();
Expand All @@ -886,6 +965,7 @@ impl Stamp {
}
}

/// Creates a name for this test/revision that can be handed over to libtest.
fn make_test_name(
config: &Config,
testpaths: &TestPaths,
Expand Down Expand Up @@ -914,20 +994,41 @@ fn make_test_name(
))
}

/// Creates a callback for this test/revision that libtest will call when it
/// decides to actually run the underlying test.
fn make_test_closure(
config: Arc<Config>,
testpaths: &TestPaths,
revision: Option<&str>,
) -> test::TestFn {
let config = config.clone();
let testpaths = testpaths.clone();
let revision = revision.map(str::to_owned);

// This callback is the link between compiletest's test discovery code,
// and the parts of compiletest that know how to run an individual test.
test::DynTestFn(Box::new(move || {
runtest::run(config, &testpaths, revision.as_deref());
Ok(())
}))
}

/// Checks that test discovery didn't find any tests whose name stem is a prefix
/// of some other tests's name.
///
/// For example, suppose the test suite contains these two test files:
/// - `tests/rustdoc/primitive.rs`
/// - `tests/rustdoc/primitive/no_std.rs`
///
/// The test runner might put the output from those tests in these directories:
/// - `$build/test/rustdoc/primitive/`
/// - `$build/test/rustdoc/primitive/no_std/`
///
/// Because one output path is a subdirectory of the other, the two tests might
/// interfere with each other in unwanted ways, especially if the test runner
/// decides to delete test output directories to clean them between runs.
/// To avoid problems, we forbid test names from overlapping in this way.
///
/// See <https://github.com/rust-lang/rust/pull/109509> for more context.
fn check_overlapping_tests(found_paths: &HashSet<PathBuf>) {
let mut collisions = Vec::new();
for path in found_paths {
Expand Down

0 comments on commit cec5986

Please sign in to comment.