From e3bfc28d71632ba63ae7419f7653be0060c7c095 Mon Sep 17 00:00:00 2001 From: Andy Dixon Date: Thu, 8 Oct 2026 20:12:37 +0100 Subject: [PATCH] Docs and metadata: per-OS platform notes, package description --- ARCHITECTURE.md | 28 +++++++++++++++++++--------- Cargo.toml | 2 +- PERFORMANCE.md | 2 +- 3 files changed, 21 insertions(+), 11 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 644bbf4..0e96607 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -285,17 +285,27 @@ it receives all keys; `Esc` always closes it. ## OS abstraction -`internal/platform` exposes `ReadDir(path, func(chunk []Entry) error)` and -`Meta` structs. Implementations: +`platform` exposes `read_dir(path, chunk, |entries| …)`, `stat`/`lstat`, +`Meta`, trash, delete, reveal and name lookups. `platform/unix.rs` and +`platform/windows.rs` hold the implementations: -* `readdir_linux.go` — `getdents` via `os.File.ReadDir` + `statx` relative to - the directory fd (one syscall per entry, gives birth time). -* `readdir_unix.go` — darwin/BSD: `fstatat` relative to the directory fd. -* `readdir_windows.go` — `os.File.ReadDir` + `Lstat`; reparse points - (junctions, symlinks) are never descended by default. -* `fs_*.go` — virtual-filesystem detection, owner name lookup. +* Linux — `readdir` on an `O_DIRECTORY` descriptor + `statx` (via the raw + system call, so static musl builds work) relative to that descriptor: one + system call per entry, birth time included; `fstatat` if the kernel lacks + `statx`. Virtual filesystems are detected with `statfs`. freedesktop.org + trash; `xdg-open` reveals. +* macOS, FreeBSD, NetBSD — the same descriptor-relative walk with + `fstatat`. macOS moves items to `~/.Trash` (or the volume's `.Trashes`) + and reveals with `open -R`; the BSDs have no trash or reveal, so `d` is + only offered as a permanent delete when headless. +* Windows — `std::fs::read_dir` and metadata. Allocated size is reported as + unknown and there is no inode identity, so hard links are not + deduplicated and symlinks and junctions are never followed. The Recycle + Bin (`SHFileOperationW`) and `explorer /select,` reveal; permanent delete + is not offered. -No other package switches on `runtime.GOOS`. +The terminal code has the only other `cfg` blocks (signals and writing the +restore sequence). ## Security handling for hostile filenames diff --git a/Cargo.toml b/Cargo.toml index 8db12b0..ba49adc 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,7 +3,7 @@ name = "mapsize" version = "1.2.0" edition = "2021" license = "GPL-3.0-or-later" -description = "Interactive terminal disk usage analyser (Rust port)" +description = "Interactive terminal disk usage analyser with a live, navigable treemap" [dependencies] libc = "0.2" diff --git a/PERFORMANCE.md b/PERFORMANCE.md index 796ec44..28c512b 100644 --- a/PERFORMANCE.md +++ b/PERFORMANCE.md @@ -17,7 +17,7 @@ is the median (and best) of 7 runs. ## Scanner -Dataset: `~/go/pkg/mod`, a large module cache: 388,307 files + 65,518 +Dataset: a source-package cache directory: 388,307 files + 65,518 directories (458,510 inventory nodes), 10.5 GiB allocated. **Warm cache only**: dropping the page cache needs root, so these measure CPU and syscall cost, not disk seeks. Cold-cache behaviour on HDDs will be dominated by seek