From 00e4e68d39187fbc3203926eb1a57d2f265598dc Mon Sep 17 00:00:00 2001
From: robojerk <rraines@gmail.com>
Date: Tue, 15 Jul 2025 11:22:13 -0700
Subject: [PATCH] Documentation: Add comprehensive Debian package structure and
 build information to ComposeFS docs

---
 docs/apt-layer/composefs.md | 98 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 97 insertions(+), 1 deletion(-)

diff --git a/docs/apt-layer/composefs.md b/docs/apt-layer/composefs.md
index 9475f5a..3889d30 100644
--- a/docs/apt-layer/composefs.md
+++ b/docs/apt-layer/composefs.md
@@ -56,6 +56,100 @@ apt-layer uses [ComposeFS](https://ostreedev.github.io/ostree/composefs/) as its
 
 ---
 
+## Package Structure
+
+### Debian/Ubuntu Packages
+
+ComposeFS is packaged in Debian/Ubuntu as three separate packages:
+
+#### 1. `composefs` (Main Tools Package)
+**Purpose:** Userspace tools for ComposeFS operations  
+**Contains:**
+- `/usr/bin/mkcomposefs` - Create ComposeFS images
+- `/usr/bin/composefs-info` - Inspect and manage images  
+- `/usr/bin/mount.composefs` - Mount helper for `mount -t composefs`
+- `/usr/share/man/man1/` - Manual pages for all tools
+- `/usr/share/doc/composefs/` - Documentation
+
+#### 2. `libcomposefs1` (Runtime Library)
+**Purpose:** Runtime shared library for ComposeFS  
+**Contains:**
+- `/usr/lib/x86_64-linux-gnu/libcomposefs.so.1` - Runtime library
+- `/usr/lib/x86_64-linux-gnu/libcomposefs.so.1.4.0` - Library version
+- **Dependencies:** `glibc`, `libgcc`, `openssl-libs`
+
+#### 3. `libcomposefs-dev` (Development Package)
+**Purpose:** Development headers and pkg-config files  
+**Contains:**
+- `/usr/include/libcomposefs/` - Header files
+- `/usr/lib/x86_64-linux-gnu/libcomposefs.so` - Development symlink
+- `/usr/lib/x86_64-linux-gnu/pkgconfig/composefs.pc` - pkg-config file
+- **Dependencies:** `libcomposefs1 (= ${binary:Version})`
+
+### Fedora/RHEL Packages
+
+ComposeFS is packaged in Fedora/RHEL as three separate packages:
+
+#### 1. `composefs` (Main Tools Package)
+**Purpose:** Userspace tools for ComposeFS operations  
+**Contains:** Same tools as Debian package
+
+#### 2. `composefs-libs` (Runtime Library)
+**Purpose:** Runtime shared library for ComposeFS  
+**Contains:** Same library as Debian `libcomposefs1`
+
+#### 3. `composefs-devel` (Development Package)
+**Purpose:** Development headers and pkg-config files  
+**Contains:** Same development files as Debian `libcomposefs-dev`
+
+### Installation Commands
+
+**Debian/Ubuntu:**
+```sh
+sudo apt install -y composefs libcomposefs1
+```
+
+**Fedora/RHEL:**
+```sh
+sudo dnf install -y composefs composefs-libs
+```
+
+**For development (optional):**
+```sh
+# Debian/Ubuntu
+sudo apt install -y libcomposefs-dev
+
+# Fedora/RHEL  
+sudo dnf install -y composefs-devel
+```
+
+### Build Dependencies
+
+The ComposeFS source package requires the following build dependencies:
+
+**Debian Build Dependencies:**
+- `debhelper-compat (= 13)`
+- `fsverity` - File system verity support
+- `fuse3` - FUSE filesystem support
+- `go-md2man` - Markdown to man page converter
+- `libcap2-bin` - Capability utilities
+- `libfuse3-dev` - FUSE development headers
+- `libssl-dev` - OpenSSL development headers
+- `meson` - Build system
+- `pkgconf` - Package configuration
+
+**Build System:** ComposeFS uses the Meson build system for compilation and packaging.
+
+### Source Package Information
+
+- **Repository:** [salsa.debian.org/debian/composefs](https://salsa.debian.org/debian/composefs)
+- **Maintainer:** Roland Hieber <rhi@pengutronix.de>
+- **Uploaders:** Dylan Aïssi <daissi@debian.org>
+- **Homepage:** [github.com/containers/composefs](https://github.com/containers/composefs)
+- **License:** BSD 2-Clause "Simplified" License
+
+---
+
 ## Commands
 
 The `composefs` package provides the following tools:
@@ -125,8 +219,10 @@ umount <mountpoint>
 
 ## Integration Notes
 
+- **Package Structure:** apt-layer supports the official ComposeFS packages from both Debian (`composefs`, `libcomposefs1`) and Fedora (`composefs`, `composefs-libs`) repositories
 - **Specific Tools:** While there isn't a single monolithic `composefs` CLI, specialized commands like `composefs-info` exist for introspection, and `mount.composefs` is the dedicated helper for mounting (callable directly or via `mount -t composefs`)
-- **Dependencies:** apt-layer requires `mkcomposefs`, `composefs-info`, `mount.composefs` (which might be part of the `composefs` package), `mksquashfs`, and `unsquashfs` for ComposeFS support
+- **Dependencies:** apt-layer requires `mkcomposefs`, `composefs-info`, `mount.composefs` (from the `composefs` package), `mksquashfs`, and `unsquashfs` for ComposeFS support
+- **Distribution Detection:** apt-layer automatically detects the distribution and provides appropriate installation commands for ComposeFS packages
 - **Fallback:** If `mkcomposefs` (and potentially `mount.composefs`) is not available, apt-layer can fall back to a shell script alternative (for development/testing only)
 - **Compatibility:** This approach matches rpm-ostree and Fedora Silverblue's use of ComposeFS for system layering