Consolidate builder exceptions to BuildException

Pros:
- Simpler API: Callers only need to handle one exception type.
- Semantic clarity: "Building failed" vs. generic "I/O error"
  or "interrupted".
- Flexibility: Wraps both IOException and InterruptedException
  with proper cause chain.
- Industry standard: Gradle uses BuildException, Maven uses
  MojoExecutionException, etc.

Cleaner than throws IOException, InterruptedException and follows the
principle of "throw exceptions at the right level of abstraction."

Author: ctrueden

src/main/java/org/apposed/appose/Appose.java

@@ -29,6 +29,7 @@
 
 package org.apposed.appose;
 
+import org.apposed.appose.builder.BuildException;
 import org.apposed.appose.builder.Builders;
 import org.apposed.appose.builder.DynamicBuilder;
 import org.apposed.appose.builder.MambaBuilder;
@@ -38,7 +39,6 @@
 import org.apposed.appose.util.Versions;
 
 import java.io.File;
-import java.io.IOException;
 
 /**
  * Appose is a library for interprocess cooperation with shared memory. The
@@ -267,7 +267,7 @@ public static PixiBuilder pixi() {
 	 * @param source Path to pixi.toml or environment.yml file.
 	 * @return A new PixiBuilder instance.
 	 */
-	public static PixiBuilder pixi(String source) throws IOException {
+	public static PixiBuilder pixi(String source) throws BuildException {
 		return new PixiBuilder(source);
 	}
 
@@ -286,8 +286,9 @@ public static MambaBuilder mamba() {
 	 *
 	 * @param source Path to environment.yml file.
 	 * @return A new MambaBuilder instance.
+	 * @throws BuildException If the source is incompatible with the mamba builder.
 	 */
-	public static MambaBuilder mamba(String source) throws IOException {
+	public static MambaBuilder mamba(String source) throws BuildException {
 		return new MambaBuilder(source);
 	}
 
@@ -306,8 +307,9 @@ public static UvBuilder uv() {
 	 *
 	 * @param source Path to requirements.txt file.
 	 * @return A new UvBuilder instance.
+	 * @throws BuildException If the source is incompatible with the uv builder.
 	 */
-	public static UvBuilder uv(String source) throws IOException {
+	public static UvBuilder uv(String source) throws BuildException {
 		return new UvBuilder(source);
 	}
 
@@ -344,11 +346,11 @@ public static DynamicBuilder content(String content) {
 	 *
 	 * @param envDir The directory containing the environment.
 	 * @return An Environment configured for the detected type.
-	 * @throws IOException If the directory doesn't exist or type cannot be determined.
+	 * @throws BuildException If the directory doesn't exist or type cannot be determined.
 	 */
-	public static Environment wrap(File envDir) throws IOException {
+	public static Environment wrap(File envDir) throws BuildException {
 		if (!envDir.exists()) {
-			throw new IOException("Environment directory does not exist: " + envDir);
+			throw new BuildException(null, "Environment directory does not exist: " + envDir);
 		}
 
 		// Find a builder factory that can wrap this directory.
@@ -367,9 +369,9 @@ public static Environment wrap(File envDir) throws IOException {
 	 *
 	 * @param envDir The path to the directory containing the environment.
 	 * @return An Environment configured for the detected type.
-	 * @throws IOException If the directory doesn't exist or type cannot be determined.
+	 * @throws BuildException If the directory doesn't exist or type cannot be determined.
 	 */
-	public static Environment wrap(String envDir) throws IOException {
+	public static Environment wrap(String envDir) throws BuildException {
 		return wrap(new File(envDir));
 	}
 
@@ -388,9 +390,9 @@ public static Environment wrap(String envDir) throws IOException {
 	 * </ul>
 	 *
 	 * @return A system environment ready to use.
-	 * @throws IOException If the environment cannot be created.
+	 * @throws BuildException If the environment cannot be created.
 	 */
-	public static Environment system() throws IOException {
+	public static Environment system() throws BuildException {
 		return new SimpleBuilder()
 			.inheritRunningJava()
 			.appendSystemPath()

src/main/java/org/apposed/appose/Builder.java

@@ -29,6 +29,8 @@
 
 package org.apposed.appose;
 
+import org.apposed.appose.builder.BuildException;
+
 import java.io.File;
 import java.io.IOException;
 import java.net.URL;
@@ -67,9 +69,11 @@ public interface Builder<T extends Builder<T>> {
 	 * Builds the environment. This is the terminator method for any fluid building chain.
 	 *
 	 * @return The newly constructed Appose {@link Environment}.
-	 * @throws IOException If something goes wrong building the environment.
+	 * @throws BuildException if the build fails due to I/O errors,
+	 *         interruption, or other build-related issues.
+	 *         Check {@link BuildException#getCause()} for the underlying cause.
 	 */
-	Environment build() throws IOException;
+	Environment build() throws BuildException;
 
 	/**
 	 * Rebuilds the environment from scratch.
@@ -83,10 +87,17 @@ public interface Builder<T extends Builder<T>> {
 	 * </p>
 	 *
 	 * @return The newly rebuilt {@link Environment}.
-	 * @throws IOException If something goes wrong during rebuild.
+	 * @throws BuildException if the build fails due to I/O errors,
+	 *         interruption, or other build-related issues.
+	 *         Check {@link BuildException#getCause()} for the underlying cause.
 	 */
-	default Environment rebuild() throws IOException {
-		delete();
+	default Environment rebuild() throws BuildException {
+		try {
+			delete();
+		}
+		catch (IOException e) {
+			throw new BuildException(this, e);
+		}
 		return build();
 	}
 
@@ -107,11 +118,11 @@ default Environment rebuild() throws IOException {
 	 * found, it will be used when rebuild() is called later.
 	 * </p>
 	 *
-	 * @param envDir The existing environment directory to wrap
-	 * @return The wrapped {@link Environment}
-	 * @throws IOException If the directory doesn't exist or can't be wrapped
+	 * @param envDir The existing environment directory to wrap.
+	 * @return The wrapped {@link Environment}.
+	 * @throws BuildException If the directory doesn't exist or can't be wrapped.
 	 */
-	Environment wrap(File envDir) throws IOException;
+	Environment wrap(File envDir) throws BuildException;
 
 	/**
 	 * Sets an environment variable to be passed to worker processes.
@@ -193,15 +204,20 @@ default T channels(String... channels) {
 	 *
 	 * @param path Path to configuration file (e.g., "pixi.toml", "environment.yml")
 	 * @return This builder instance, for fluent-style programming.
-	 * @throws IOException If the file cannot be read
+	 * @throws BuildException If the file cannot be read
 	 */
-	default T file(String path) throws IOException {
-		java.nio.file.Path filePath = java.nio.file.Paths.get(path);
-		String fileContent = new String(
-			java.nio.file.Files.readAllBytes(filePath),
-			java.nio.charset.StandardCharsets.UTF_8
-		);
-		return content(fileContent);
+	default T file(String path) throws BuildException {
+		try {
+			java.nio.file.Path filePath = java.nio.file.Paths.get(path);
+			String fileContent = new String(
+					java.nio.file.Files.readAllBytes(filePath),
+					java.nio.charset.StandardCharsets.UTF_8
+			);
+			return content(fileContent);
+		}
+		catch (IOException e) {
+			throw new BuildException(this, e);
+		}
 	}
 
 	/**
@@ -219,9 +235,9 @@ default T file(String path) throws IOException {
 	 *
 	 * @param url URL to configuration file
 	 * @return This builder instance, for fluent-style programming.
-	 * @throws IOException If the URL cannot be read
+	 * @throws BuildException If the URL cannot be read
 	 */
-	default T url(URL url) throws IOException {
+	default T url(URL url) throws BuildException {
 		try (java.io.InputStream stream = url.openStream()) {
 			java.io.ByteArrayOutputStream result = new java.io.ByteArrayOutputStream();
 			byte[] buffer = new byte[8192];
@@ -232,6 +248,9 @@ default T url(URL url) throws IOException {
 			String urlContent = result.toString(java.nio.charset.StandardCharsets.UTF_8.name());
 			return content(urlContent);
 		}
+		catch (IOException e) {
+			throw new BuildException(this, e);
+		}
 	}
 
 	/**

src/main/java/org/apposed/appose/BuilderFactory.java

@@ -29,10 +29,10 @@
 
 package org.apposed.appose;
 
+import org.apposed.appose.builder.BuildException;
 import org.apposed.appose.builder.Builders;
 
 import java.io.File;
-import java.io.IOException;
 
 /**
  * Factory interface for creating builder instances.
@@ -57,7 +57,7 @@ public interface BuilderFactory {
 	 * @param source The source file path
 	 * @return A new configured builder instance
 	 */
-	Builder<?> createBuilder(String source) throws IOException;
+	Builder<?> createBuilder(String source) throws BuildException;
 
 	/**
 	 * Creates a new builder instance configured with a source file and scheme.
@@ -66,7 +66,7 @@ public interface BuilderFactory {
 	 * @param scheme The scheme (e.g., "environment.yml", "pixi.toml")
 	 * @return A new configured builder instance
 	 */
-	Builder<?> createBuilder(String source, String scheme) throws IOException;
+	Builder<?> createBuilder(String source, String scheme) throws BuildException;
 
 	/**
 	 * Returns the name of this builder (e.g., "pixi", "mamba", "system").

src/main/java/org/apposed/appose/Environment.java

@@ -29,6 +29,7 @@
 
 package org.apposed.appose;
 
+import org.apposed.appose.builder.BuildException;
 import org.apposed.appose.util.FilePaths;
 
 import java.io.File;
@@ -81,20 +82,25 @@ default String type() {
 	 * current builder configuration.
 	 *
 	 * @return The newly rebuilt environment.
-	 * @throws IOException If something goes wrong during rebuild.
+	 * @throws BuildException If something goes wrong during rebuild.
 	 */
-	default Environment rebuild() throws IOException {
+	default Environment rebuild() throws BuildException {
 		return builder().rebuild();
 	}
 
 	/**
 	 * Deletes the existing environment directory, if any.
 	 *
 	 * @return This environment, for fluid chaining.
-	 * @throws IOException If something goes wrong during deletion.
+	 * @throws BuildException If something goes wrong during deletion.
 	 */
-	default Environment delete() throws IOException {
-		builder().delete();
+	default Environment delete() throws BuildException {
+		try {
+			builder().delete();
+		}
+		catch (IOException e) {
+			throw new BuildException(builder(), e);
+		}
 		return this;
 	}
 

src/main/java/org/apposed/appose/builder/BaseBuilder.java

@@ -78,8 +78,13 @@ public void delete() throws IOException {
 	}
 
 	@Override
-	public Environment wrap(File envDir) throws IOException {
-		FilePaths.ensureDirectory(envDir);
+	public Environment wrap(File envDir) throws BuildException {
+		try {
+			FilePaths.ensureDirectory(envDir);
+		}
+		catch (IOException e) {
+			throw new BuildException(this, e);
+		}
 		// Set the base directory and build (which will detect existing env).
 		base(envDir);
 		return build();

src/main/java/org/apposed/appose/builder/BuildException.java

@@ -0,0 +1,73 @@
+/*-
+ * #%L
+ * Appose: multi-language interprocess cooperation with shared memory.
+ * %%
+ * Copyright (C) 2023 - 2025 Appose developers.
+ * %%
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ *    this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright notice,
+ *    this list of conditions and the following disclaimer in the documentation
+ *    and/or other materials provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ * #L%
+ */
+
+package org.apposed.appose.builder;
+
+import org.apposed.appose.Builder;
+import org.apposed.appose.Nullable;
+
+/**
+ * Exception thrown when a {@link Builder} fails to build an environment.
+ *
+ * @author Curtis Rueden
+ */
+public class BuildException extends Exception {
+
+	/** The builder associated with this exception. */
+	@Nullable
+	public final Builder<?> builder;
+
+	public BuildException(String message) {
+		this(null, message);
+	}
+
+	public BuildException(Throwable cause) {
+		this(null, cause);
+	}
+
+	public BuildException(@Nullable Builder<?> builder, String message) {
+		super(message);
+		this.builder = builder;
+	}
+
+	public BuildException(@Nullable Builder<?> builder, Throwable cause) {
+		this(builder, makeMessage(builder, cause), cause);
+	}
+
+	public BuildException(@Nullable Builder<?> builder, String message, Throwable cause) {
+		super(message, cause);
+		this.builder = builder;
+	}
+
+	private static String makeMessage(Builder<?> builder, Throwable cause) {
+		String noun = builder == null ? "build" : builder.name() + " build";
+		String verb = cause instanceof InterruptedException ? "interrupted" : "failed";
+		return noun + " " + verb;
+	}
+}

src/main/java/org/apposed/appose/builder/DynamicBuilder.java

@@ -33,8 +33,6 @@
 import org.apposed.appose.BuilderFactory;
 import org.apposed.appose.Environment;
 
-import java.io.IOException;
-
 /**
  * Dynamic builder that auto-detects the appropriate specific builder
  * based on source file and scheme.
@@ -75,14 +73,14 @@ public String name() {
 	}
 
 	@Override
-	public Environment build() throws IOException {
+	public Environment build() throws BuildException {
 		Builder<?> delegate = createBuilder(builderName, source, scheme);
 		copyConfigToDelegate(delegate);
 		return delegate.build();
 	}
 
 	@Override
-	public Environment rebuild() throws IOException {
+	public Environment rebuild() throws BuildException {
 		Builder<?> delegate = createBuilder(builderName, source, scheme);
 		copyConfigToDelegate(delegate);
 		return delegate.rebuild();
@@ -103,7 +101,7 @@ private void copyConfigToDelegate(Builder<?> delegate) {
 		errorSubscribers.forEach(delegate::subscribeError);
 	}
 
-	private Builder<?> createBuilder(String name, String source, String scheme) throws IOException {
+	private Builder<?> createBuilder(String name, String source, String scheme) throws BuildException {
 		// Find the builder matching the specified name, if any.
 		if (name != null) {
 			BuilderFactory factory = Builders.findFactoryByName(name);