3.6 KiB
Development Guide for fuse-archive
This document provides project-specific context, conventions, and workflows for building and contributing to the fuse-archive repository.
Project Overview
fuse-archive is a read-only FUSE filesystem that mounts various archive and compressed file formats (ZIP, TAR, 7Z, RAR, ISO, etc.) using the libarchive library. The project is structured as a core library in lib/ and a slim CLI wrapper in fuse-archive.cc.
C++ Standard
The project uses C++23. Ensure you are using a modern compiler (e.g., GCC 13+ or Clang 16+) that supports the C++23 standard.
Versioning Policy
The project follows a stable/development minor versioning scheme:
- Even minor versions (e.g., 1.20, 1.22) are stable releases.
- Odd minor versions (e.g., 1.19, 1.21) are development versions.
Current state: 1.25 (Development).
Build and Development
Makefile Variables
DEBUG=1: Enable debug symbols and disable optimizations.ASAN=1: Enable AddressSanitizer for memory safety checks.
Key Makefile Targets
make all: Build thefuse-archivebinary and the man page.make check-fast: Run the fast subset of tests (recommended for most dev work).make check: Run the full test suite (including large file tests).make doc: Regenerate thefuse-archive.1man page fromREADME.md.make release: Run the automated release workflow (see below).make clean-data: Remove large generated test archives fromtest/data.
Documentation Pipeline
The README.md file serves as both the user guide and the source for the man page.
- Generation:
pandocconvertsREADME.mdtoroffformat. - Formatting: The
Makefileusessedpost-processing on thepandocoutput to ensure bulleted lists are rendered compactly (using.PD 0) in the man page. - Markdown requirement: Bulleted lists in
README.mdmust be preceded by a blank line for correctpandocparsing.
Release Process
The release process is fully automated via release.py.
- Command:
make release [VERSION=X.Y] - Action: Bumps version, updates dates, regenerates docs, creates a stable release commit and git tag, then bumps to the next odd development version with another commit.
- Manual Step: Always
git push origin main --tagsafter a successfulmake release.
Technical Standards
Memory Safety
The project aims for full ASAN compliance. Always verify changes with ASAN=1 make check-fast.
Resource Management (RAII)
- Use RAII guards for resource cleanup.
- Specific Helpers:
FileDescriptor: Manages file descriptors.Cleanup: A generic helper that runs a provided lambda/function in its destructor, used for one-off cleanup tasks like removing temporary mount points (e.g.,mount_point_guard) or performing the global teardown (e.g.,global_cleanup_guard).
- Shutdown Performance: Global teardown (clearing the virtual node tree, disposing of children, emptying the reader recycle bin, and deleting the global string pool) is wrapped in a
Cleanupguard inside#ifdef __SANITIZE_ADDRESS__. This complex cleanup is only performed in ASAN builds to keep production shutdown nearly instant for archives with millions of files, while ensuring a perfectly clean exit for diagnostic builds.
Portability
- The project is 32-bit compatible.
- Year 2038: Always build with
-D_TIME_BITS=64(handled inMakefile) to ensure correct timestamp handling on 32-bit systems.
Testing
- Main Runner:
test/test.py - Data Generation: Large or complex test archives are generated by scripts in the
test/directory (e.g.,make_big_zip.py).