ci: add github actions for lint and format (#156)

Author: saidsay-so

.cirrus.yml

@@ -13,8 +13,7 @@ build: &BUILD
     - df -T /tmp
     - target/release/pjdfstest -c $CFG -p /tmp
     - su $SU_ARGS "target/release/pjdfstest -c $CFG -p /tmp"
-    - rustup component add clippy
-    - cargo clippy --all-targets
+
 
 task:
   name: FreeBSD

.github/workflows/book.yml

@@ -30,11 +30,12 @@ jobs:
         with:
           crate: mdbook-cmdrun
 
-      - uses: dtolnay/rust-toolchain@stable
       - name: Build the suite to retrieve its features
-        run: cd rust && cargo build
+        working-directory: rust
+        run: cargo build
 
-      - run: cd book && ./build.sh
+      - working-directory: book
+        run: ./build.sh
 
       - name: Deploy
         uses: peaceiris/actions-gh-pages@v4

.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+on:
+  push:
+
+jobs:
+  format_lint_check:
+    runs-on: ubuntu-latest
+    env:
+      RUSTFLAGS: -D warnings
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check formatting
+        working-directory: rust
+        run: cargo fmt --all --check
+
+      - name: Check clippy for Linux
+        working-directory: rust
+        run: cargo clippy --all-targets --all-features
+
+      - name: Install FreeBSD target
+        run: rustup target add x86_64-unknown-freebsd
+
+      - name: Check clippy for FreeBSD
+        working-directory: rust
+        run: cargo clippy --all-targets --all-features --target x86_64-unknown-freebsd
+
+      - name: Check doc
+        working-directory: rust
+        run: cargo doc --no-deps --all-features

README.md

@@ -1,9 +1,23 @@
-# pjdfstest - Rust rewrite
+# pjdfstest.rs - Rust rewrite
 
-pjdfstest is a test suite that helps exercise POSIX system calls.
+pjdfstest is a file system test suite to assess the correctness of file system implementations in terms of POSIX compliance.
+The test suite has been rewritten in Rust as part of the Google Summer of Code 2022 program.
 
 ## Build
 
+### Requirements
+
+The following dependencies are required to build the project:
+
+#### Common
+
+- Rust (1.72.1 or later)
+
+#### Linux
+
+- libacl1-dev (Debian/Ubuntu), libacl-devel (Fedora), acl (Arch)
+- acl
+
 ```bash
 cd rust
 cargo run
@@ -13,6 +27,51 @@ cargo run
 
 The documentation is available at <https://saidsay-so.github.io/pjdfstest/>.
 
+## Configuration file
+
+A TOML configuration file can be used to specify parameters for the test suite.
+A default configuration file is provided in the repository, which can be used as a template.
+
+```toml
+# Configuration for the pjdfstest runner
+
+# This section allows enabling file system specific features.
+# Please see the book for more details.
+# A list of these features is provided when executing the runner with `-l`.
+[features]
+# File flags can be specified for OS which supports them.
+# file_flags = ["UF_IMMUTABLE"]
+
+# Here is an example with the `posix_fallocate` syscall.
+posix_fallocate = {}
+
+# Might use the key notation as well.
+# [features.posix_fallocate]
+
+[settings]
+# naptime is the duration of various short sleeps.  It should be greater than
+# the timestamp granularity of the file system under test.
+naptime = 0.001
+# Allow to run the EROFS tests, which require to remount the file system on which
+# pjdsfstest is run as read-only.
+allow_remount = false
+
+# This section allows to modify the mechanism for switching users, which is required by some tests.
+# [dummy_auth]
+# An entry is the name of a user and its associated group.
+# For now, the array requires exactly 3 entries.
+# Please see the book for more details.
+# entries = [
+#   ["nobody", "nobody"],
+#   nogroup instead for some Linux distros
+#   ["nobody", "nogroup"],
+#   ["tests", "tests"],
+#   ["pjdfstest", "pjdfstest"],
+# ]
+```
+
+Please refer to the [documentation](https://saidsay-so.github.io/pjdfstest/configuration-file.html) for more details.
+
 ## Command-line interface
 
 _`pjdfstest [OPTIONS] [--] TEST_PATTERNS`_
@@ -70,3 +129,9 @@ tests:x:::Dummy User for pjdfstest:/:/usr/bin/nologin
 pjdfstest:x:::Dummy User for pjdfstest:/:/usr/bin/nologin
 EOF
 ```
+
+## Contributing
+
+Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on the process for submitting pull requests to us
+and the process for adding new tests.
+Also, read the [documentation](https://saidsay-so.github.io/pjdfstest/test-declaration.html) on how to declare tests.

book/src/introduction.md

@@ -5,7 +5,9 @@ primarily for FreeBSD file systems.
 It was originally written to validate the ZFS port to FreeBSD,
 but it now supports multiple operating systems and file systems.
 
-This is a complete rewrite of the original test suite in Rust.
+This is a complete rewrite of the original test suite in Rust,
+as part of the Google Summer of Code 2022 program
+(<https://summerofcode.withgoogle.com/archive/2022/projects/6XPYWLzJ>).
 
 **NOTE: The documentation is still a work-in-progress**
 

book/src/test-declaration.md

@@ -25,7 +25,7 @@ fn update_ctime(ctx: &mut TestContext, f_type: FileType) {
 
 All the structures and functions needed are documented in the `pjdfstest` crate,
 which you can obtain by running `cargo doc --open` in the `rust` directory
-or by visiting the [documentation](/doc/pjdfstest).
+or by visiting the [documentation](doc/pjdfstest/).
 
 ## Test context
 

rust/src/config/auth.rs

@@ -1,6 +1,6 @@
 use std::error::Error;
-use std::{borrow::Cow, fmt::Display};
 use std::process::exit;
+use std::{borrow::Cow, fmt::Display};
 
 use nix::unistd::{Group, User};
 use serde::{de::Visitor, ser::SerializeTuple, Deserialize, Serialize};
@@ -145,11 +145,11 @@ impl Default for DummyAuthConfig {
                 },
                 DummyAuthEntry {
                     user: upjdfstest,
-                    group: gpjdfstest
+                    group: gpjdfstest,
                 },
                 DummyAuthEntry {
                     user: utests,
-                    group: gtests
+                    group: gtests,
                 },
             ],
         }

rust/src/features.rs

@@ -21,7 +21,7 @@ use serde::{Deserialize, Serialize};
 #[serde(rename_all = "snake_case")]
 #[strum(serialize_all = "snake_case")]
 pub enum FileSystemFeature {
-    /// The [`chflags`](https://man.freebsd.org/cgi/man.cgi?chflags(1)) command is available
+    /// The [`chflags`](https://man.freebsd.org/cgi/man.cgi?chflags(1)) syscall is available
     Chflags,
     /// NFSv4 style Access Control Lists are available
     Nfsv4Acls,

rust/src/flags.rs

@@ -2,6 +2,7 @@
 
 use serde::{Deserialize, Serialize};
 
+/// Define a set of flags for a given enum and implement `From` for `nix::sys::stat::FileFlag`.
 macro_rules! flags {
     ( $( #[$enum_attrs: meta] )* pub enum $enum: ident { $(#[cfg($cfg: meta)] $(#[$attr: meta])* $flag: ident ),* $(,)?} ) => {
         $(#[$enum_attrs])*

rust/src/macros.rs

@@ -1,15 +1,15 @@
 //! Macros for defining test cases.
-//! 
-//! The `test_case` macro is used to define test cases for a test suite. 
+//!
+//! The `test_case` macro is used to define test cases for a test suite.
 
 /// Macro for defining test cases, which are automatically registered with the test suite.
-/// 
+///
 /// A test case can be serialized or non-serialized, require root privileges, and be run on specific file types.
 /// It can also require specific features to be enabled, and have guards which are run before the test case is executed to determine if conditions are met.
-/// 
+///
 /// The macro supports mutiple parameters which can be combined in a specific order,
 /// for example:
-/// 
+///
 /// ```rust
 /// // Non-serialized test case
 /// test_case! {
@@ -18,7 +18,7 @@
 /// }
 /// fn basic(_: &mut crate::test::TestContext) {}
 /// ```
-/// 
+///
 /// ```rust
 /// // Non-serialized test case with required features, guards, and root privileges
 /// test_case! {
@@ -27,7 +27,7 @@
 /// }
 /// fn features(_: &mut crate::test::TestContext) {}
 /// ```
-/// 
+///
 /// ```rust
 /// // Serialized test case with root privileges
 /// test_case! {
@@ -36,7 +36,7 @@
 /// }
 /// fn serialized(_: &mut crate::test::SerializedTestContext) {}
 /// ```
-/// 
+///
 /// ```rust
 /// // Serialized test case with required features
 /// test_case! {
@@ -45,12 +45,12 @@
 /// }
 /// fn serialized_features(_: &mut crate::test::SerializedTestContext) {}
 /// ```
-/// 
+///
 /// ```rust
 /// // Serialized test case with required features, guards, root privileges, and file types
 /// test_case! {
 /// /// description
-/// serialized_types, serialized, FileSystemFeature::Chflags, FileSystemFeature::PosixFallocate; guard_example, root => [Regular, Fifo]
+/// serialized_types, serialized, root, FileSystemFeature::Chflags, FileSystemFeature::PosixFallocate; guard_example, root => [Regular, Fifo]
 /// }
 /// fn serialized_types(_: &mut crate::test::SerializedTestContext, _: crate::context::FileType) {}
 /// ```

rust/src/tests/mod.rs

@@ -1,10 +1,10 @@
 //! Where the tests are defined.
-//! 
+//!
 //! This module contains the tests for the file system test suite. The tests are defined as functions
 //! which are then registered with the test suite.
-//! 
+//!
 //! The tests are defined using the `test_case!` macro, which is used to define a test case for the test suite.
-//! 
+//!
 //! It also contains some helper functions and macros which are used to define the tests.
 
 use std::fs::symlink_metadata;

rust/src/tests/rmdir.rs

@@ -105,8 +105,8 @@ fn has_mount_cap(_: &Config, _: &Path) -> anyhow::Result<()> {
     if !Uid::effective().is_root() && ctl.value()? == CtlValue::Int(0) {
         anyhow::bail!("process doesn't have the rights to mount the dummy file system")
     }
-    if !Uid::effective().is_root() &&
-        !OsStr::from_bytes(&Command::new("lsvfs").output().unwrap().stdout)
+    if !Uid::effective().is_root()
+        && !OsStr::from_bytes(&Command::new("lsvfs").output().unwrap().stdout)
             .to_string_lossy()
             .contains("nullfs")
     {

rust/src/utils.rs

@@ -1,5 +1,5 @@
 //! Utility functions for filesystem operations.
-//! 
+//!
 //! This module provides utility functions for filesystem operations which are not available in the standard library.
 
 use std::{
@@ -95,7 +95,7 @@ pub fn lchflags<P: ?Sized + nix::NixPath>(
 
 /// Wrapper for open which returns [`Ownedfd`] instead of [`RawFd`].
 pub fn open<P: ?Sized + nix::NixPath>(path: &P, oflag: OFlag, mode: Mode) -> nix::Result<OwnedFd> {
-    // SAFETY: The file descriptor was initialized only by open and isn't used anywhere else, 
+    // SAFETY: The file descriptor was initialized only by open and isn't used anywhere else,
     // leaving the ownership to the caller.
     nix::fcntl::open(path, oflag, mode).map(|fd| unsafe { OwnedFd::from_raw_fd(fd) })
 }