From a02e33b5244b885bcbb5406d887eb979c937b96d Mon Sep 17 00:00:00 2001 From: Daniel Burgener Date: Tue, 22 Oct 2024 13:58:31 -0400 Subject: [PATCH 1/3] Add CONTRIBUTING.md doc This is essentially to make the comment over current_kernel_abi() more visible and add some handholding for new developers. Coming in and running this crate on an older kernel results in multiple test failures, and finding the current_kernel_abi() comment takes a little investigation, so spelling this all out for new contributors may help save some time. Signed-off-by: Daniel Burgener --- CONTRIBUTING.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..26625462 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,28 @@ +# Contributing + +Thanks for your interest in contributing to rust-landlock! + +## Testing vs kernel ABI + +For `cargo test` to work, it needs to run only tests that target the Landlock +ABI supported on your currently running kernel. In order to set the tested ABI +use the LANDLOCK_CRATE_TEST_ABI environmental variable like: + +``` +LANDLOCK_CRATE_TEST_ABI=1 cargo test +``` + +The above example uses ABI version 1, supported by kernels 5.13 through 5.18. +You should use the ABI matching your actual kernel version. The test +`current_kernel_abi()` verifies that the ABI you set in the variable matches +your kernel version. + +If LANDLOCK_CRATE_TEST_ABI is unset, it defaults to the latest ABI supported by +rust-landlock. + +Note that if you are running with older kernels, you will be missing some +tests, which could cause a difference between your local testing and the +github actions CI. The github actions CI tests against all supported kernel +ABIs. + +For more information about Landlock ABIs see https://landlock.io/rust-landlock/landlock/enum.ABI.html From ed0ab798e5c8ef06db25066436af92ff06ea6649 Mon Sep 17 00:00:00 2001 From: Daniel Burgener Date: Thu, 19 Dec 2024 11:47:27 -0500 Subject: [PATCH 2/3] Change the default LANDLOCK_CRATE_TEST_ABI to the current kernel. If the user doesn't specify a version, run the tests applicable to their actual kernel rather than defaulting to the latest version available. This makes local smoke testing easier. Signed-off-by: Daniel Burgener --- src/compat.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/compat.rs b/src/compat.rs index 86f115e2..d9be8eae 100644 --- a/src/compat.rs +++ b/src/compat.rs @@ -146,7 +146,7 @@ lazy_static! { panic!("Unknown ABI: {n}"); } } - Err(std::env::VarError::NotPresent) => ABI::iter().last().unwrap(), + Err(std::env::VarError::NotPresent) => ABI::new_current(), Err(e) => panic!("Failed to read LANDLOCK_CRATE_TEST_ABI: {e}"), }; } From 0e5ca97ec859fd871d2d9abf05198bc7c319d1b5 Mon Sep 17 00:00:00 2001 From: Daniel Burgener Date: Thu, 19 Dec 2024 11:55:58 -0500 Subject: [PATCH 3/3] Simplify CONTRIBUTING doc Rewrite based on PR comments and change in LANDLOCK_CRATE_TEST_ABI default Signed-off-by: Daniel Burgener --- CONTRIBUTING.md | 33 +++++++++++++-------------------- 1 file changed, 13 insertions(+), 20 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 26625462..fdeb277f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,25 +4,18 @@ Thanks for your interest in contributing to rust-landlock! ## Testing vs kernel ABI -For `cargo test` to work, it needs to run only tests that target the Landlock -ABI supported on your currently running kernel. In order to set the tested ABI -use the LANDLOCK_CRATE_TEST_ABI environmental variable like: - -``` -LANDLOCK_CRATE_TEST_ABI=1 cargo test -``` - -The above example uses ABI version 1, supported by kernels 5.13 through 5.18. -You should use the ABI matching your actual kernel version. The test -`current_kernel_abi()` verifies that the ABI you set in the variable matches -your kernel version. - -If LANDLOCK_CRATE_TEST_ABI is unset, it defaults to the latest ABI supported by -rust-landlock. - -Note that if you are running with older kernels, you will be missing some -tests, which could cause a difference between your local testing and the -github actions CI. The github actions CI tests against all supported kernel -ABIs. +The Landlock functionality exposed differs between kernel versions. In order +to test all possible variations, the rust-landlock tests will run different +subsets of tests based on the landlock support in the current kernel. + +In order to fully test a change, it should be verified against a range of +kernel versions. This is done by the github actions CI, but is currently +challenging to do locally. For local development, running `cargo test` will +test against your currently running kernel version, which may result in some +tests being skipped. + +The kernel to test against can be overridden using the LANDLOCK_CRATE_TEST_ABI +environmental variable. For more details see the comment in +`compat.rs:current_kernel_abi()`. For more information about Landlock ABIs see https://landlock.io/rust-landlock/landlock/enum.ABI.html