fix: add includeMsgpack flag and per-module CHANGELOGs

- Add includeMsgpack to VenvConfig (defaults to true) so users who
  don't need python-embed-runtime can opt out of msgpack installation
- Add includeBuild 'python-embed-build-common' to root settings.gradle
  so publish-build-common.yml resolves correctly
- Create python-embed-build-common/CHANGELOG.md (1.0.2)
- Create python-embed-maven-plugin/CHANGELOG.md (1.0.2)
- Update root CHANGELOG.md with 1.0.4 entry for new modules
- Update VenvManagerTest and VenvTaskTest for includeMsgpack changes

Author: white

python-embed-build-common/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## [1.0.2] - 2026-06-26
+
+### Added
+- `VenvManager` — shared venv setup logic extracted from Gradle plugin
+- `VenvConfig` — configuration record for venv setup
+- `PythonDownloader` — downloads python-build-standalone releases from GitHub
+- `PythonResolver` — detects system Python and resolves python executable paths
+- `FingerprintManager` — incremental rebuild via package hash fingerprinting
+- `TarGzExtractor` — custom tar.gz extractor with path traversal protection
+- `RequirementsParser` — parses pip requirements.txt files
+
+[build-common-v1.0.2]: https://github.com/howtis/python-embed/releases/tag/build-common-v1.0.2

python-embed-build-common/src/main/java/io/github/howtis/pythonembed/build/VenvConfig.java

@@ -22,6 +22,7 @@ public final class VenvConfig {
     private final Path venvDir;
     private final String targetOs;
     private final Consumer<String> logger;
+    private final boolean includeMsgpack;
 
     private VenvConfig(Builder builder) {
         this.packages = Collections.unmodifiableList(new ArrayList<>(builder.packages));
@@ -33,6 +34,7 @@ private VenvConfig(Builder builder) {
         this.venvDir = Objects.requireNonNull(builder.venvDir, "venvDir must not be null");
         this.targetOs = builder.targetOs;
         this.logger = builder.logger;
+        this.includeMsgpack = builder.includeMsgpack;
     }
 
     public List<String> packages() { return packages; }
@@ -45,6 +47,15 @@ private VenvConfig(Builder builder) {
     public String targetOs() { return targetOs; }
     public Consumer<String> logger() { return logger; }
 
+    /**
+     * Whether to include {@code msgpack} in the installed packages.
+     * Defaults to {@code true} because {@code msgpack} is required by
+     * {@code python-embed-runtime}'s bridge protocol.
+     *
+     * @return true if msgpack should be included
+     */
+    public boolean includeMsgpack() { return includeMsgpack; }
+
     public static Builder builder() {
         return new Builder();
     }
@@ -59,6 +70,7 @@ public static final class Builder {
         private Path venvDir;
         private String targetOs;
         private Consumer<String> logger = s -> {};
+        private boolean includeMsgpack = true;
 
         private Builder() {}
 
@@ -107,6 +119,11 @@ public Builder logger(Consumer<String> logger) {
             return this;
         }
 
+        public Builder includeMsgpack(boolean includeMsgpack) {
+            this.includeMsgpack = includeMsgpack;
+            return this;
+        }
+
         public VenvConfig build() {
             return new VenvConfig(this);
         }

python-embed-build-common/src/main/java/io/github/howtis/pythonembed/build/VenvManager.java

@@ -36,7 +36,10 @@ public static PythonEnvironment setup(VenvConfig config) throws IOException {
 
         // Collect packages
         List<String> packages = new ArrayList<>(config.packages());
-        if (!packages.contains("msgpack")) {
+
+        // Include msgpack by default (required by python-embed-runtime bridge protocol).
+        // Users who do not need the runtime can opt out via VenvConfig.includeMsgpack(false).
+        if (config.includeMsgpack() && !packages.contains("msgpack")) {
             packages.add("msgpack");
         }
 

python-embed-build-common/src/test/java/io/github/howtis/pythonembed/build/VenvManagerTest.java

@@ -66,8 +66,7 @@ void setup_upToDate_skipsSetup(@TempDir Path tempDir) throws IOException {
         Files.createFile(pythonExe);
 
         // Write a fingerprint matching the expected configuration.
-        // VenvManager.setup() always adds "msgpack" to the packages list,
-        // so the fingerprint must include it.
+        // includeMsgpack defaults to true, so msgpack is added to the packages list.
         String pythonVersion = "3.12";
         String packageHash = FingerprintManager.computePackageHash(
                 List.of("msgpack"), null, List.of(), null);
@@ -83,4 +82,37 @@ void setup_upToDate_skipsSetup(@TempDir Path tempDir) throws IOException {
         assertEquals(venvDir, result.venvDir());
         assertEquals("system", result.source());
     }
+
+    @Test
+    void setup_upToDate_withoutMsgpack(@TempDir Path tempDir) throws IOException {
+        Path venvDir = tempDir.resolve("venv");
+        Files.createDirectories(venvDir);
+
+        // Create a mock Python executable
+        Path pythonExe;
+        if (PythonResolver.isWindows()) {
+            pythonExe = venvDir.resolve("python.exe");
+        } else {
+            pythonExe = venvDir.resolve("bin").resolve("python3");
+            Files.createDirectories(pythonExe.getParent());
+        }
+        Files.createFile(pythonExe);
+
+        // Write a fingerprint matching empty packages (msgpack excluded).
+        String pythonVersion = "3.12";
+        String packageHash = FingerprintManager.computePackageHash(
+                List.of(), null, List.of(), null);
+        FingerprintManager.write(venvDir, "system", pythonVersion, packageHash);
+
+        VenvConfig config = VenvConfig.builder()
+                .venvDir(venvDir)
+                .includeMsgpack(false)
+                .build();
+
+        PythonEnvironment result = VenvManager.setup(config);
+
+        assertNotNull(result);
+        assertEquals(venvDir, result.venvDir());
+        assertEquals("system", result.source());
+    }
 }

python-embed-gradle-plugin/src/test/java/io/github/howtis/pythonembed/gradle/VenvTaskTest.java

@@ -149,8 +149,8 @@ void createVenv_fingerprintMatchSkipsSetup(@TempDir Path tempDir) throws IOExcep
         // Create fake python executable in OS-appropriate location
         createPrimaryPythonExe(venvPath);
 
-        // Set packages and compute expected fingerprint
-        // msgpack is auto-added by VenvTask, so include it in the expected hash
+        // Set packages and compute expected fingerprint.
+        // includeMsgpack defaults to true in VenvConfig, so msgpack is auto-added.
         List<String> packages = List.of("numpy==1.26.4");
         task.getPackages().set(packages);
         String expectedHash = task.computePackageHash(List.of("numpy==1.26.4", "msgpack"), null, List.of(), null);
@@ -231,7 +231,8 @@ void createVenv_nullPythonSourceForcesFullSetup(@TempDir Path tempDir) throws IO
         // Create fake python executable in OS-appropriate location
         createPrimaryPythonExe(venvPath);
 
-        // Set packages matching the fingerprint
+        // Set packages matching the fingerprint.
+        // includeMsgpack defaults to true in VenvConfig, so msgpack is auto-added.
         List<String> packages = List.of("numpy==1.26.4");
         task.getPackages().set(packages);
         String expectedHash = task.computePackageHash(List.of("numpy==1.26.4", "msgpack"), null, List.of(), null);
@@ -278,7 +279,8 @@ void createVenv_pythonVersionMismatchForcesFullSetup(@TempDir Path tempDir) thro
         // Create fake python executable
         createPrimaryPythonExe(venvPath);
 
-        // Set packages matching the fingerprint
+        // Set packages matching the fingerprint.
+        // includeMsgpack defaults to true in VenvConfig, so msgpack is auto-added.
         List<String> packages = List.of("numpy==1.26.4");
         task.getPackages().set(packages);
         String expectedHash = task.computePackageHash(List.of("numpy==1.26.4", "msgpack"), null, List.of(), null);
@@ -314,7 +316,8 @@ void createVenv_pythonMissingForcesFullSetup(@TempDir Path tempDir) throws IOExc
         // Do NOT create python executable (simulates deleted venv)
         Files.createDirectories(venvPath);
 
-        // Set packages matching the fingerprint
+        // Set packages matching the fingerprint.
+        // includeMsgpack defaults to true in VenvConfig, so msgpack is auto-added.
         List<String> packages = List.of("numpy==1.26.4");
         task.getPackages().set(packages);
         String expectedHash = task.computePackageHash(List.of("numpy==1.26.4", "msgpack"), null, List.of(), null);

python-embed-maven-plugin/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## [1.0.2] - 2026-06-26
+
+### Added
+- `SetupMojo` — `python-embed:setup` goal for venv creation and package installation
+- `PropertiesMojo` — `python-embed:properties` goal to expose Python environment properties
+- `HelpMojo` — `python-embed:help` goal with plugin documentation
+- Maven plugin descriptor (`plugin.xml`) for `io.github.howtis:python-embed-maven-plugin`
+
+[maven-plugin-v1.0.2]: https://github.com/howtis/python-embed/releases/tag/maven-plugin-v1.0.2

settings.gradle

@@ -1,5 +1,6 @@
 rootProject.name = 'python-embed'
 
+includeBuild 'python-embed-build-common'
 includeBuild 'python-embed-gradle-plugin'
 includeBuild 'python-embed-maven-plugin'
 include 'python-embed-runtime'