From 71b843a433b4e67b5f59aa96faea56422dac8c19 Mon Sep 17 00:00:00 2001 From: Daniel Burgener Date: Tue, 22 Oct 2024 13:58:31 -0400 Subject: [PATCH] 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. --- 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