Imported from love4taylor/linux-ntfs-dkms (AGENTS.md). Install upstream with npx skills add love4taylor/linux-ntfs-dkms. Copyright stays with the author.

AGENTS.md

Project Overview

This repository packages the upstream namjaejeon/linux-ntfs read-write NTFS filesystem driver as an out-of-tree DKMS module.

• The root repository owns the DKMS packaging, lifecycle scripts, and documentation.
• src/ is an upstream Git submodule and builds the ntfs.ko kernel module.
• dkms.conf is the source of truth for the package name, package version, module name, build command, destination, supported kernel bounds, and autoinstall behavior.
• The current package is linux-ntfs/20260806.ca149db, based on upstream commit ca149db6b901a0d44cdd88e54047e0cd422ca70d.
• The module registers the ntfs filesystem. It does not replace the separate in-kernel ntfs3 driver.

Repository Map

Core Invariants

• Keep src/ as a clean submodule. Do not edit upstream driver files for packaging-only work.
• Do not use make -C src install or make -C src uninstall. Those targets bypass DKMS, and the upstream uninstall target removes the whole kernel module directory.
• Keep BUILT_MODULE_NAME[0]="ntfs", BUILT_MODULE_LOCATION[0]="src", and DEST_MODULE_LOCATION[0]="/kernel/fs/ntfs" aligned with the upstream build output.
• Keep BUILD_EXCLUSIVE_KERNEL_MIN="6.1". Linux 7.1 and newer may build only when CONFIG_NTFS_FS is unset; if that option is y or m, the pre-build hook must exit 77 so DKMS records an intentional skip and uses the in-tree driver instead.
• Do not add a DKMS CLEAN directive. DKMS builds from a prepared source tree, and modern DKMS treats that directive as deprecated.
• Never unload ntfs while an NTFS filesystem is mounted. Use findmnt -t ntfs before any modprobe -r ntfs command.
• Preserve the file-level SPDX identifiers and copyright notices in src/. The root license does not override or narrow upstream declarations.

Package Versioning

PACKAGE_VERSION uses YYYYMMDD.<seven-character-src-commit>; the current value is 20260806.ca149db.

Update the package version when changing any content staged into /usr/src, including:

• the src submodule commit;
• dkms.conf; or
• scripts/dkms-pre-build.sh.

The suffix must match git -C src rev-parse --short=7 HEAD, and src/ must have no tracked modifications. A packaging-only revision can advance the date while retaining the same source suffix. Do not reuse a package version for different staged source: the installer deliberately rejects a registered /usr/src tree that differs from the checkout.

When changing PACKAGE_VERSION, update any hard-coded package version or /usr/src/linux-ntfs-<version> examples in both README files.

Setup

Initialize the upstream source before running checks or builds:

git submodule update --init --recursive
git submodule status

A Linux build host needs DKMS, Bash, GNU Make, a C toolchain, and headers or development files matching the target kernel. The target kernel must:

• be Linux 6.1 or newer;
• enable loadable modules, NLS, and FS_IOMAP; and
• leave CONFIG_NTFS_FS unset, except that Linux 6.1 through 7.0.x may build it as a module.

CONFIG_NTFS_FS=y is unsupported because a built-in filesystem driver cannot be replaced by DKMS. On Linux 7.1 and newer, CONFIG_NTFS_FS=m also selects the in-tree driver and suppresses this DKMS build.

Development Commands

Run from the repository root:

make check                         # Validate metadata, scripts, submodule state, and version suffix
make                               # Build src/ntfs.ko for the running kernel
make KERNEL_VERSION=<version>      # Build for another installed kernel
make KDIR=/path/to/kernel/build    # Build against an explicit prepared kernel tree
make clean                         # Remove upstream kernel build artifacts
make help                          # List public targets

The build targets require Linux and a prepared kernel tree. make check is the minimum repository-level static validation and can run without compiling the module.

DKMS Lifecycle

Install for the running kernel:

sudo make install

Install for another installed kernel:

sudo make install KERNEL_VERSION=<version>

The installer validates the checkout, stages clean source at /usr/src/linux-ntfs-<version>, runs dkms add, dkms build, and dkms install, and rolls back source and registration created by a failed first install. An existing matching registration is reused for additional kernels.

Inspect or remove the exact package version:

make status
sudo make uninstall

Uninstall removes this package version from all kernels. It verifies package metadata before deleting the corresponding /usr/src directory.

Testing Instructions

Static Checks

Run these for every change:

make check
git diff --check
git status --short
git -C src status --short

For documentation changes, also verify that README.md and README.zh.md have matching heading levels and command sequences. Keep the English and Chinese documents structurally synchronized.

Build Check

On Linux with matching headers:

make clean
make
modinfo src/ntfs.ko

Do not claim build success from make check; it only validates shell syntax and packaging contracts.

DKMS Integration Check

On a disposable or recoverable Linux test host:

sudo make install
make status
modinfo -n ntfs
modinfo ntfs | grep -E '^(filename|vermagic|signer):'

The installed path should resolve through DKMS for the target kernel. Secure Boot systems also require the DKMS signing key to be trusted before the module can load.

Runtime Check

Prefer rebooting after installation. For a live switch, first prove the filesystem is unused:

findmnt -t ntfs
sudo modprobe -r ntfs
sudo modprobe ntfs
modinfo -n ntfs
grep -w ntfs /proc/filesystems

Do not run the unload command if findmnt -t ntfs prints any mount. Runtime validation should include a controlled mount, read/write exercise, clean unmount, and kernel-log inspection when the change affects driver behavior.

Code Style

• Use tabs for Make recipes and preserve the existing variable-driven target style.
• Write Bash scripts with set -euo pipefail or set -Eeuo pipefail, quote expansions, validate arguments, and emit actionable errors to stderr.
• Keep privileged filesystem changes inside the install and uninstall scripts. Validation targets must remain non-destructive.
• Use explicit paths under /usr/src and /lib/modules; validate ownership metadata before recursive removal.
• Keep comments concise and explain safety or compatibility decisions rather than restating the code.
• Default code and shell text to ASCII. Chinese is expected in README.zh.md.

Documentation Rules

• Keep README.md and README.zh.md one-to-one in section structure and command examples.
• Update both documents whenever commands, requirements, package versions, paths, safety checks, or lifecycle behavior changes.
• Keep user documentation focused on installation and operation. Put agent-specific invariants and maintenance details here.
• Do not duplicate the full license text in documentation; link to LICENSE when a license reference is needed.

Source Submodule Updates

When explicitly updating upstream source:

1. Fetch and select the intended commit inside src/.
2. Review the upstream diff and confirm its kernel compatibility independently.
3. Ensure git -C src status --short is empty.
4. Update the root gitlink and set PACKAGE_VERSION to a new date plus the new seven-character commit suffix.
5. Update both README files if their displayed commit, version, requirements, or behavior changed.
6. Run static checks, a Linux module build, DKMS installation, and runtime validation before publishing.

Do not hide uncommitted driver changes inside a DKMS package. Commit them in an appropriate source repository or restore the submodule to a clean commit first.

Safety and Troubleshooting

• Treat module installation and removal as host-level changes. Use a recoverable test machine and preserve SSH or console access.
• A successful DKMS build does not prove that the running kernel loaded the new module; verify modinfo -n ntfs after reboot or a safe reload.
• A module that builds but will not load on Secure Boot systems may be unsigned or signed by an untrusted key.
• If /usr/src/linux-ntfs-<version> exists without a DKMS registration, resolve the stale state deliberately; do not weaken the installer's consistency check.
• If the kernel has CONFIG_NTFS_FS=y, use another kernel configuration instead of trying to force installation.
• This repository currently has no automated unit test suite or CI workflow. State exactly which static, build, DKMS, and runtime checks were performed.

Commit and Review Guidelines

• Use Conventional Commits, for example docs: regenerate project guides or fix: reject incompatible kernel config.
• Keep submodule updates explicit in the commit description, including the old and new upstream commits.
• Do not stage, commit, push, or deploy unless the user explicitly requests it.
• Before handoff, report the validation boundary: local static checks, Linux compilation, DKMS installation, module activation, and filesystem I/O are distinct levels of evidence.