uutils · Its-Just-Nans · Apr 25, 2025 · Apr 25, 2025 · Apr 25, 2025 · Apr 25, 2025
diff --git a/.github/workflows/CICD.yml b/.github/workflows/CICD.yml
@@ -1160,8 +1160,8 @@ jobs:
      run: |
        for f in $(util/show-utils.sh)
        do
-          echo "Running tests with --features=$f and --no-default-features"
-          cargo test --features=$f --no-default-features
+          echo "Running tests with --features="$f coreutils" --no-default-features"
+          cargo test --features="$f coreutils" --no-default-features
        done

  test_selinux:

diff --git a/Cargo.toml b/Cargo.toml
@@ -23,7 +23,7 @@ edition.workspace = true
 all-features = true

 [features]
-default = ["feat_common_core"]
+default = ["feat_common_core", "coreutils"]
 ## OS feature shortcodes
 macos = ["feat_os_macos"]
 unix = ["feat_os_unix"]
@@ -35,7 +35,8 @@ expensive_tests = []
 # "test_risky_names" == enable tests that create problematic file names (would make a network share inaccessible to Windows, breaks SVN on Mac OS, etc.)
 test_risky_names = []
 # * only build `uudoc` when `--feature uudoc` is activated
-uudoc = ["zip", "dep:uuhelp_parser"]
+uudoc = ["dep:zip", "dep:uuhelp_parser"]
+coreutils = ["dep:zip"]
 ## features
 # "feat_acl" == enable support for ACLs (access control lists; by using`--features feat_acl`)
 # NOTE:
@@ -542,6 +543,7 @@ phf_codegen = { workspace = true }
 [[bin]]
 name = "coreutils"
 path = "src/bin/coreutils.rs"
+required-features = ["coreutils"]

 [[bin]]
 name = "uudoc"

diff --git a/GNUmakefile b/GNUmakefile
@@ -300,17 +300,17 @@ endif
 endif

 build-coreutils:
-	${CARGO} build ${CARGOFLAGS} --features "${EXES} $(BUILD_SPEC_FEATURE)" ${PROFILE_CMD} --no-default-features
+	${CARGO} build ${CARGOFLAGS} --features "${EXES} $(BUILD_SPEC_FEATURE) coreutils" ${PROFILE_CMD} --no-default-features

 build: build-coreutils build-pkgs

 $(foreach test,$(filter-out $(SKIP_UTILS),$(PROGS)),$(eval $(call TEST_BUSYBOX,$(test))))

 test:
-	${CARGO} test ${CARGOFLAGS} --features "$(TESTS) $(TEST_SPEC_FEATURE)" --no-default-features $(TEST_NO_FAIL_FAST)
+	${CARGO} test ${CARGOFLAGS} --features "$(TESTS) $(TEST_SPEC_FEATURE) coreutils" --no-default-features $(TEST_NO_FAIL_FAST)

 nextest:
-	${CARGO} nextest run ${CARGOFLAGS} --features "$(TESTS) $(TEST_SPEC_FEATURE)" --no-default-features $(TEST_NO_FAIL_FAST)
+	${CARGO} nextest run ${CARGOFLAGS} --features "$(TESTS) $(TEST_SPEC_FEATURE) coreutils" --no-default-features $(TEST_NO_FAIL_FAST)

 test_toybox:
 	-(cd $(TOYBOX_SRC)/ && make tests)

diff --git a/build.rs b/build.rs
@@ -36,8 +36,9 @@ pub fn main() {
                "nightly" | "test_unimplemented" | "expensive_tests" | "test_risky_names" => {
                    continue;
                } // crate-local custom features
-                "uudoc" => continue, // is not a utility
+                "uudoc" => continue,     // is not a utility
                "test" => continue, // over-ridden with 'uu_test' to avoid collision with rust core crate 'test'
+                "coreutils" => continue, // coreutils
                s if s.starts_with(FEATURE_PREFIX) => continue, // crate feature sets
                _ => {}             // util feature name
            }

diff --git a/src/bin/coreutils.rs b/src/bin/coreutils.rs
@@ -10,19 +10,34 @@ use clap_complete::Shell;
 use std::cmp;
 use std::ffi::OsStr;
 use std::ffi::OsString;
+use std::fs::File;
+use std::io::Read;
+use std::io::Seek;
 use std::io::{self, Write};
 use std::path::{Path, PathBuf};
 use std::process;
 use uucore::display::Quotable;
+use zip::ZipArchive;

 const VERSION: &str = env!("CARGO_PKG_VERSION");

+const COMPLETION: &str = "completion";
+const MANPAGE: &str = "manpage";
+
 include!(concat!(env!("OUT_DIR"), "/uutils_map.rs"));

 fn usage<T>(utils: &UtilityMap<T>, name: &str) {
    println!("{name} {VERSION} (multi-call binary)\n");
    println!("Usage: {name} [function [arguments...]]");
-    println!("       {name} --list\n");
+    println!("       {name} --list");
+    println!();
+    println!("Functions:");
+    println!("      {COMPLETION}",);
+    println!("           {}", get_completion_args(utils).render_usage());
+    println!("      '{MANPAGE}'",);
+    println!("           {}", get_manpage_args(utils).render_usage());
+    println!("      '<uutils>' [arguments...]");
+    println!();
    println!("Options:");
    println!("      --list    lists all defined functions, one per row\n");
    println!("Currently defined functions:\n");
@@ -95,8 +110,14 @@ fn main() {
        };

        match util {
-            "completion" => gen_completions(args, &utils),
-            "manpage" => gen_manpage(args, &utils),
+            COMPLETION => {
+                gen_completions(args, &utils);
+                process::exit(0);
+            }
+            MANPAGE => {
+                gen_manpage(args, &utils);
+                process::exit(0);
+            }
            "--list" => {
                let mut utils: Vec<_> = utils.keys().collect();
                utils.sort();
@@ -148,18 +169,11 @@ fn main() {
    }
 }

-/// Prints completions for the utility in the first parameter for the shell in the second parameter to stdout
-/// # Panics
-/// Panics if the utility map is empty
-fn gen_completions<T: uucore::Args>(
-    args: impl Iterator<Item = OsString>,
-    util_map: &UtilityMap<T>,
-) -> ! {
+fn get_completion_args<T>(util_map: &UtilityMap<T>) -> clap::Command {
    let all_utilities: Vec<_> = std::iter::once("coreutils")
        .chain(util_map.keys().copied())
        .collect();
-
-    let matches = Command::new("completion")
+    Command::new(COMPLETION)
        .about("Prints completions to stdout")
        .arg(
            Arg::new("utility")
@@ -171,7 +185,17 @@ fn gen_completions<T: uucore::Args>(
                .value_parser(clap::builder::EnumValueParser::<Shell>::new())
                .required(true),
        )
-        .get_matches_from(std::iter::once(OsString::from("completion")).chain(args));
+}
+
+/// Prints completions for the utility in the first parameter for the shell in the second parameter to stdout
+/// # Panics
+/// Panics if the utility map is empty
+fn gen_completions<T: uucore::Args>(
+    args: impl Iterator<Item = OsString>,
+    util_map: &UtilityMap<T>,
+) {
+    let matches = get_completion_args(util_map)
+        .get_matches_from(std::iter::once(OsString::from(COMPLETION)).chain(args));

    let utility = matches.get_one::<String>("utility").unwrap();
    let shell = *matches.get_one::<Shell>("shell").unwrap();
@@ -185,42 +209,49 @@ fn gen_completions<T: uucore::Args>(

    clap_complete::generate(shell, &mut command, bin_name, &mut io::stdout());
    io::stdout().flush().unwrap();
-    process::exit(0);
 }

-/// Generate the manpage for the utility in the first parameter
-/// # Panics
-/// Panics if the utility map is empty
-fn gen_manpage<T: uucore::Args>(
-    args: impl Iterator<Item = OsString>,
-    util_map: &UtilityMap<T>,
-) -> ! {
+fn get_manpage_args<T>(util_map: &UtilityMap<T>) -> clap::Command {
    let all_utilities: Vec<_> = std::iter::once("coreutils")
        .chain(util_map.keys().copied())
        .collect();
+    Command::new(MANPAGE).about("Prints manpage to stdout").arg(
+        Arg::new("utility")
+            .value_parser(clap::builder::PossibleValuesParser::new(all_utilities))
+            .required(true),
+    )
+}

-    let matches = Command::new("manpage")
-        .about("Prints manpage to stdout")
-        .arg(
-            Arg::new("utility")
-                .value_parser(clap::builder::PossibleValuesParser::new(all_utilities))
-                .required(true),
-        )
-        .get_matches_from(std::iter::once(OsString::from("manpage")).chain(args));
+/// Generate the manpage for the utility in the first parameter
+/// # Panics
+/// Panics if the utility map is empty
+fn gen_manpage<T: uucore::Args>(args: impl Iterator<Item = OsString>, util_map: &UtilityMap<T>) {
+    let tldr_zip = File::open("docs/tldr.zip")
+        .ok()
+        .and_then(|f| ZipArchive::new(f).ok());
+
+    if tldr_zip.is_none() {
+        // Could not open tldr.zip
+    }
+    let matches = get_manpage_args(util_map)
+        .get_matches_from(std::iter::once(OsString::from(MANPAGE)).chain(args));

    let utility = matches.get_one::<String>("utility").unwrap();

    let command = if utility == "coreutils" {
        gen_coreutils_app(util_map)
    } else {
-        util_map.get(utility).unwrap().1()
+        let mut cmd = util_map.get(utility).unwrap().1();
+        if let Ok(examples) = get_zip_examples(utility) {
+            cmd = cmd.after_help(examples);
+        }
+        cmd
    };

    let man = clap_mangen::Man::new(command);
    man.render(&mut io::stdout())
        .expect("Man page generation failed");
    io::stdout().flush().unwrap();
-    process::exit(0);
 }

 /// # Panics
@@ -239,3 +270,64 @@ fn gen_coreutils_app<T: uucore::Args>(util_map: &UtilityMap<T>) -> Command {
    }
    command
 }
+
+/// # Errors
+/// Returns an error if the tldr.zip file cannot be opened or read
+fn get_zip_examples(name: &str) -> io::Result<String> {
+    fn get_zip_content(archive: &mut ZipArchive<impl Read + Seek>, name: &str) -> Option<String> {
+        let mut s = String::new();
+        archive.by_name(name).ok()?.read_to_string(&mut s).unwrap();
+        Some(s)
+    }
+
+    let mut w = io::BufWriter::new(Vec::new());
+    let file = File::open("docs/tldr.zip")?;
+    let mut tldr_zip = match ZipArchive::new(file) {
+        Ok(zip) => zip,
+        Err(e) => {
+            return Err(io::Error::new(
+                io::ErrorKind::NotFound,
+                format!("Error reading tldr.zip: {}", e),
+            ));
+        }
+    };
+
+    let content = if let Some(f) =
+        get_zip_content(&mut tldr_zip, &format!("pages/common/{}.md", name))
+    {
+        f
+    } else if let Some(f) = get_zip_content(&mut tldr_zip, &format!("pages/linux/{}.md", name)) {
+        f
+    } else {
+        return Err(io::Error::new(
+            io::ErrorKind::NotFound,
+            "Could not find tldr examples",
+        ));
+    };
+
+    writeln!(w, "Examples")?;
+    writeln!(w)?;
+    for line in content.lines().skip_while(|l| !l.starts_with('-')) {
+        if let Some(l) = line.strip_prefix("- ") {
+            writeln!(w, "{l}")?;
+        } else if line.starts_with('`') {
+            writeln!(w, "{}", line.trim_matches('`'))?;
+        } else if line.is_empty() {
+            writeln!(w)?;
+        } else {
+            // println!("Not sure what to do with this line:");
+            // println!("{line}");
+        }
+    }
+    writeln!(w)?;
+    writeln!(
+        w,
+        "> The examples are provided by the [tldr-pages project](https://tldr.sh) under the [CC BY 4.0 License](https://github.com/tldr-pages/tldr/blob/main/LICENSE.md)."
+    )?;
+    writeln!(w, "\n\n\n")?;
+    writeln!(
+        w,
+        "> Please note that, as uutils is a work in progress, some examples might fail."
+    )?;
+    Ok(String::from_utf8(w.into_inner().unwrap()).unwrap())
+}
diff --git a/src/uu/rm/benchmark.sh b/src/uu/rm/benchmark.sh
@@ -3,6 +3,6 @@
 # Exit on any failures
 set +x

-cargo build --no-default-features --features rm --release
+cargo build --no-default-features --features rm coreutils --release
 test_dir="$1"
-hyperfine --prepare "cp -r $test_dir tmp_d"  "rm -rf tmp_d" "target/release/coreutils rm -rf tmp_d"
+hyperfine --prepare "cp -r $test_dir tmp_d" "rm -rf tmp_d" "target/release/coreutils rm -rf tmp_d"