From b5b6331fcbff4fdade3b5efe7adb840f17fa5bdc Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Thu, 2 Jan 2025 23:41:12 +0700 Subject: [PATCH 1/7] fix(rust): make rust doc tests not run with nightly --- earthly/rust/scripts/std_build.py | 6 ++++-- earthly/rust/stdcfgs/cargo_config.toml | 6 +----- examples/rust/.cargo/config.toml | 6 +----- 3 files changed, 6 insertions(+), 12 deletions(-) diff --git a/earthly/rust/scripts/std_build.py b/earthly/rust/scripts/std_build.py index 070a22a1d..fbb17ca6b 100755 --- a/earthly/rust/scripts/std_build.py +++ b/earthly/rust/scripts/std_build.py @@ -36,7 +36,7 @@ def cargo_lint(flags: str, verbose: bool = False) -> exec_manager.Result: def cargo_doctest(flags: str, verbose: bool = False) -> exec_manager.Result: return exec_manager.cli_run( - "cargo +nightly testdocs " + f"{flags} ", + "cargo testdocs " + f"{flags} ", name="Documentation tests all pass check", verbose=verbose, ) @@ -95,7 +95,9 @@ def cargo_bench(flags: str, verbose: bool = False) -> exec_manager.Result: def cargo_doc(verbose: bool = False) -> exec_manager.Result: return exec_manager.cli_run( - "cargo +nightly docs ", name="Documentation build", verbose=verbose + "cargo +nightly docs --enable-index-page -Z unstable-options", + name="Documentation build", + verbose=verbose ) diff --git a/earthly/rust/stdcfgs/cargo_config.toml b/earthly/rust/stdcfgs/cargo_config.toml index 6641db1fa..cd8aa55e3 100644 --- a/earthly/rust/stdcfgs/cargo_config.toml +++ b/earthly/rust/stdcfgs/cargo_config.toml @@ -27,11 +27,7 @@ rustflags = [ [build] rustflags = [] -rustdocflags = [ - "--enable-index-page", - "-Z", - "unstable-options", -] +rustdocflags = [] [profile.dev] opt-level = 1 diff --git a/examples/rust/.cargo/config.toml b/examples/rust/.cargo/config.toml index 6641db1fa..cd8aa55e3 100644 --- a/examples/rust/.cargo/config.toml +++ b/examples/rust/.cargo/config.toml @@ -27,11 +27,7 @@ rustflags = [ [build] rustflags = [] -rustdocflags = [ - "--enable-index-page", - "-Z", - "unstable-options", -] +rustdocflags = [] [profile.dev] opt-level = 1 From 7e65b0042d5d9758e91882af631a0afe4ac1dd2c Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Thu, 2 Jan 2025 23:54:52 +0700 Subject: [PATCH 2/7] fix(docs): rust doc options --- earthly/rust/scripts/std_build.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/earthly/rust/scripts/std_build.py b/earthly/rust/scripts/std_build.py index fbb17ca6b..aad1bd043 100755 --- a/earthly/rust/scripts/std_build.py +++ b/earthly/rust/scripts/std_build.py @@ -95,7 +95,7 @@ def cargo_bench(flags: str, verbose: bool = False) -> exec_manager.Result: def cargo_doc(verbose: bool = False) -> exec_manager.Result: return exec_manager.cli_run( - "cargo +nightly docs --enable-index-page -Z unstable-options", + "cargo +nightly docs -Z unstable-options --enable-index-page", name="Documentation build", verbose=verbose ) From b6ba74362f85f265982b106b1229fa40b0b07edd Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Fri, 3 Jan 2025 09:29:44 +0700 Subject: [PATCH 3/7] fix(rust): Deny arithmetic side effects in the code (forces being thoughtful about overflow/underflow). --- earthly/rust/stdcfgs/cargo_manifest/project.toml | 3 ++- earthly/rust/stdcfgs/cargo_manifest/workspace.toml | 3 ++- examples/rust/Cargo.toml | 1 + 3 files changed, 5 insertions(+), 2 deletions(-) diff --git a/earthly/rust/stdcfgs/cargo_manifest/project.toml b/earthly/rust/stdcfgs/cargo_manifest/project.toml index 5278f2be3..14bba9158 100644 --- a/earthly/rust/stdcfgs/cargo_manifest/project.toml +++ b/earthly/rust/stdcfgs/cargo_manifest/project.toml @@ -35,4 +35,5 @@ panic = "deny" string_slice = "deny" unchecked_duration_subtraction = "deny" unreachable = "deny" -missing_docs_in_private_items = "deny" \ No newline at end of file +missing_docs_in_private_items = "deny" +arithmetic_side_effects = "deny" \ No newline at end of file diff --git a/earthly/rust/stdcfgs/cargo_manifest/workspace.toml b/earthly/rust/stdcfgs/cargo_manifest/workspace.toml index 86dfcc1be..acd007c00 100644 --- a/earthly/rust/stdcfgs/cargo_manifest/workspace.toml +++ b/earthly/rust/stdcfgs/cargo_manifest/workspace.toml @@ -35,4 +35,5 @@ panic = "deny" string_slice = "deny" unchecked_duration_subtraction = "deny" unreachable = "deny" -missing_docs_in_private_items = "deny" \ No newline at end of file +missing_docs_in_private_items = "deny" +arithmetic_side_effects = "deny" \ No newline at end of file diff --git a/examples/rust/Cargo.toml b/examples/rust/Cargo.toml index 1cfc0fc57..ffb3b2434 100644 --- a/examples/rust/Cargo.toml +++ b/examples/rust/Cargo.toml @@ -45,3 +45,4 @@ string_slice = "deny" unchecked_duration_subtraction = "deny" unreachable = "deny" missing_docs_in_private_items = "deny" +arithmetic_side_effects = "deny" \ No newline at end of file From dd4251998dc08770d0ed5875a703811e9c1bc279 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Fri, 3 Jan 2025 09:30:29 +0700 Subject: [PATCH 4/7] fix(rust): Add llvm-tools-preview to the +nightly toolchain in case we want to use doctests with code coverage one day --- earthly/rust/Earthfile | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/earthly/rust/Earthfile b/earthly/rust/Earthfile index 3ef00debb..5d7aa3212 100644 --- a/earthly/rust/Earthfile +++ b/earthly/rust/Earthfile @@ -407,7 +407,13 @@ INSTALL_RUST: RUN rustup component add llvm-tools-preview # Install a nightly toolchain which matches. - RUN rustup toolchain install nightly --component miri --component rust-src --component rustfmt --component clippy --component cargo + RUN rustup toolchain install nightly \ + --component miri \ + --component rust-src \ + --component rustfmt \ + --component clippy \ + --component cargo \ + --component llvm-tools-preview # Ensure we have all the necessary targets RUN rustup target add wasm32-unknown-unknown From 21127dda01f24a80f178438079ea03e9e39a101e Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Fri, 3 Jan 2025 09:34:17 +0700 Subject: [PATCH 5/7] fix(rust): Run doctests serially, to prevent flaky builds from failed doctest compiles --- earthly/rust/scripts/std_build.py | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/earthly/rust/scripts/std_build.py b/earthly/rust/scripts/std_build.py index aad1bd043..6912b87a2 100755 --- a/earthly/rust/scripts/std_build.py +++ b/earthly/rust/scripts/std_build.py @@ -330,9 +330,8 @@ def main(): runner.run(cargo_lint, args.lint_flags, args.verbose) # Check if all Self contained tests pass (Test that need no external resources). + # But NOT doc tests, as these are not replacements for unit tests. if not args.disable_tests: - # Check if all documentation tests pass. - runner.run(cargo_doctest, args.doctest_flags, args.verbose) if args.cov_report == "": # Without coverage report runner.run(cargo_nextest, args.test_flags, args.verbose) @@ -367,6 +366,15 @@ def main(): results = runner.get_results() + # Check if all Self contained doc tests pass (Test that need no external resources). + # Can not be run in parallel with the normal builds as it becomes flaky and randomly fails. + # NOTE: DocTests are ONLY run to prove they are valid, they are NOT unit tests, and never + # currently contribute to code coverage. + if not args.disable_tests: + # Check if all documentation tests pass. + results.add(cargo_doctest(args.doctest_flags, args.verbose)) + + results.print() if not results.ok(): exit(1) From 926f26ecf7f61759aef11e3f1ea6c74942bdd1df Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Fri, 3 Jan 2025 09:43:50 +0700 Subject: [PATCH 6/7] fix(rust): Don't enable arithmetic_side_effects = "deny" yet --- earthly/rust/stdcfgs/cargo_manifest/project.toml | 3 +-- earthly/rust/stdcfgs/cargo_manifest/workspace.toml | 3 +-- examples/rust/Cargo.toml | 3 +-- 3 files changed, 3 insertions(+), 6 deletions(-) diff --git a/earthly/rust/stdcfgs/cargo_manifest/project.toml b/earthly/rust/stdcfgs/cargo_manifest/project.toml index 14bba9158..5278f2be3 100644 --- a/earthly/rust/stdcfgs/cargo_manifest/project.toml +++ b/earthly/rust/stdcfgs/cargo_manifest/project.toml @@ -35,5 +35,4 @@ panic = "deny" string_slice = "deny" unchecked_duration_subtraction = "deny" unreachable = "deny" -missing_docs_in_private_items = "deny" -arithmetic_side_effects = "deny" \ No newline at end of file +missing_docs_in_private_items = "deny" \ No newline at end of file diff --git a/earthly/rust/stdcfgs/cargo_manifest/workspace.toml b/earthly/rust/stdcfgs/cargo_manifest/workspace.toml index acd007c00..86dfcc1be 100644 --- a/earthly/rust/stdcfgs/cargo_manifest/workspace.toml +++ b/earthly/rust/stdcfgs/cargo_manifest/workspace.toml @@ -35,5 +35,4 @@ panic = "deny" string_slice = "deny" unchecked_duration_subtraction = "deny" unreachable = "deny" -missing_docs_in_private_items = "deny" -arithmetic_side_effects = "deny" \ No newline at end of file +missing_docs_in_private_items = "deny" \ No newline at end of file diff --git a/examples/rust/Cargo.toml b/examples/rust/Cargo.toml index ffb3b2434..6627e2aa8 100644 --- a/examples/rust/Cargo.toml +++ b/examples/rust/Cargo.toml @@ -44,5 +44,4 @@ panic = "deny" string_slice = "deny" unchecked_duration_subtraction = "deny" unreachable = "deny" -missing_docs_in_private_items = "deny" -arithmetic_side_effects = "deny" \ No newline at end of file +missing_docs_in_private_items = "deny" \ No newline at end of file From ff49d524f35d3f8b269c915590c2c57278b816b9 Mon Sep 17 00:00:00 2001 From: Steven Johnson Date: Fri, 3 Jan 2025 10:01:17 +0700 Subject: [PATCH 7/7] fix(rust): Use an env var to control rustdoc selectively only when building docs, not running doc tests --- earthly/rust/scripts/std_build.py | 5 ++++- utilities/scripts/python/exec_manager.py | 2 ++ 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/earthly/rust/scripts/std_build.py b/earthly/rust/scripts/std_build.py index 6912b87a2..06e2b15cb 100755 --- a/earthly/rust/scripts/std_build.py +++ b/earthly/rust/scripts/std_build.py @@ -94,8 +94,11 @@ def cargo_bench(flags: str, verbose: bool = False) -> exec_manager.Result: def cargo_doc(verbose: bool = False) -> exec_manager.Result: + # Add RUSTDOCFLAGS to the inherited environment so we can build an index page with nightly. + env = os.environ + env["RUSTDOCFLAGS"] = "-Z unstable-options --enable-index-page" return exec_manager.cli_run( - "cargo +nightly docs -Z unstable-options --enable-index-page", + "cargo +nightly docs", name="Documentation build", verbose=verbose ) diff --git a/utilities/scripts/python/exec_manager.py b/utilities/scripts/python/exec_manager.py index e17b2a4a3..06cdb9660 100755 --- a/utilities/scripts/python/exec_manager.py +++ b/utilities/scripts/python/exec_manager.py @@ -150,6 +150,7 @@ def cli_run( log: bool = True, timeout=None, verbose=False, + env=None ) -> Result: def procedure() -> ProcedureResult: result = subprocess.run( @@ -159,6 +160,7 @@ def procedure() -> ProcedureResult: stderr=subprocess.STDOUT, text=True, timeout=timeout, + env=env ) return ProcedureResult(result.returncode, command, result.stdout)