From: Chris McGee <cmcgee1024@gmail.com>
Date: Wed, 12 Nov 2025 13:42:03 +0000 (-0500)
Subject: Provide a detailed description of the libarchive module map file
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=refs%2Fpull%2F2738%2Fhead;p=thirdparty%2Flibarchive.git

Provide a detailed description of the libarchive module map file
---

diff --git a/libarchive/module.modulemap b/libarchive/module.modulemap
index e570d01a4..70f70fc3a 100644
--- a/libarchive/module.modulemap
+++ b/libarchive/module.modulemap
@@ -1,3 +1,33 @@
+/*
+ * Clang Module Map for libarchive
+ *
+ * What this is:
+ * This file tells the Clang compiler how to treat libarchive as a "module" -
+ * a self-contained unit of code that can be imported all at once instead of
+ * including individual header files. Think of it like a package definition.
+ *
+ * How it works:
+ * - When you write `@import CArchive` (Objective-C) or `import CArchive` (Swift),
+ *   the compiler uses this file to know which headers belong to libarchive
+ * - Instead of processing each #include separately, the compiler can load a
+ *   pre-compiled version of the entire library, making builds faster
+ * - This also provides better dependency tracking and can catch issues like
+ *   conflicting macro definitions between libraries
+ *
+ * When to update:
+ * Update this file whenever:
+ * - New public header files are added to libarchive's libarchive/ directory
+ * - Public headers are removed or renamed
+ * - The library's API structure changes significantly
+ *
+ * You typically don't need to update this for:
+ * - Internal implementation changes
+ * - Private/internal header modifications
+ * - Documentation updates
+ *
+ * NOTE: This only affects projects using Clang with modules enabled. Traditional
+ * #include-based builds will continue to work normally with or without this file.
+ */
 module CArchive {
   header "archive.h"
   header "archive_entry.h"