Rework Java2Swift to operate entirely on Java2Swift.config files

Instead of having Java2Swift take in a list of classes on the command
line, which the plugin synthesizes by reading a configuration file,
and then emitting another almost-identical manifest file...
rework the command-line interface to Java2Swift to operate entirely on
the per-target Java2Swift.config files. This makes the plugin simpler,
because it never has to look at build products for its dependencies.

Change the `--jar-file` mode of Java2Swift to emit the configuration
file but not translate any classes. This should be used as a tool, not
a build step.

Update the user guide to introduce JavaKit through the build tool.

Author: DougGregor

Makefile

@@ -70,19 +70,19 @@ Java2Swift: $(BUILD_DIR)/debug/Java2Swift
 
 generate-JavaKit: Java2Swift
 	mkdir -p Sources/JavaKit/generated
-	$(BUILD_DIR)/debug/Java2Swift --module-name JavaKit -o Sources/JavaKit/generated java.lang.Object=JavaObject java.util.Enumeration java.lang.Throwable java.lang.Exception java.lang.RuntimeException java.lang.Error=JavaError
+	$(BUILD_DIR)/debug/Java2Swift --module-name JavaKit -o Sources/JavaKit/generated Sources/JavaKit/Java2Swift.config
 
 generate-JavaKitReflection: Java2Swift generate-JavaKit
 	mkdir -p Sources/JavaKitReflection/generated
-	$(BUILD_DIR)/debug/Java2Swift --module-name JavaKitReflection --manifests Sources/JavaKit/generated/JavaKit.swift2java -o Sources/JavaKitReflection/generated java.lang.reflect.Method java.lang.reflect.Type java.lang.reflect.Constructor java.lang.reflect.Parameter java.lang.reflect.ParameterizedType java.lang.reflect.Executable java.lang.reflect.AnnotatedType java.lang.reflect.TypeVariable java.lang.reflect.WildcardType java.lang.reflect.GenericArrayType java.lang.reflect.AccessibleObject java.lang.annotation.Annotation java.lang.reflect.GenericDeclaration java.lang.reflect.Field
+	$(BUILD_DIR)/debug/Java2Swift --module-name JavaKitReflection --depends-on JavaKit=Sources/JavaKit/Java2Swift.config -o Sources/JavaKitReflection/generated Sources/JavaKitReflection/Java2Swift.config
 
 generate-JavaKitJar: Java2Swift generate-JavaKit
 	mkdir -p Sources/JavaKitJar/generated
-	$(BUILD_DIR)/debug/Java2Swift --module-name JavaKitJar --manifests Sources/JavaKit/generated/JavaKit.swift2java -o Sources/JavaKitJar/generated java.util.jar.Attributes java.util.jar.JarEntry	java.util.jar.JarFile java.util.jar.JarInputStream java.util.jar.JarOutputStream java.util.jar.Manifest
+	$(BUILD_DIR)/debug/Java2Swift --module-name JavaKitJar --depends-on JavaKit=Sources/JavaKit/Java2Swift.config -o Sources/JavaKitJar/generated Sources/JavaKitJar/Java2Swift.config
 
 generate-JavaKitNetwork: Java2Swift generate-JavaKit
 	mkdir -p Sources/JavaKitNetwork/generated
-	$(BUILD_DIR)/debug/Java2Swift --module-name JavaKitNetwork --manifests Sources/JavaKit/generated/JavaKit.swift2java -o Sources/JavaKitNetwork/generated java.net.URI java.net.URL java.net.URLClassLoader
+	$(BUILD_DIR)/debug/Java2Swift --module-name JavaKitNetwork --depends-on JavaKit=Sources/JavaKit/Java2Swift.config -o Sources/JavaKitNetwork/generated Sources/JavaKitNetwork/Java2Swift.config
 
 javakit-generate: generate-JavaKit generate-JavaKitReflection generate-JavaKitJar generate-JavaKitNetwork
 

Plugins/Java2SwiftPlugin/Configuration.swift

@@ -14,6 +14,9 @@
 
 /// Configuration for the Java2Swift translation tool, provided on a per-target
 /// basis.
+///
+/// Note: there is a copy of this struct in the Java2Swift library. They
+/// must be kept in sync.
 struct Configuration: Codable {
   /// The Java class path that should be passed along to the Java2Swift tool.
   var classPath: String? = nil

Plugins/Java2SwiftPlugin/Java2SwiftPlugin.swift

@@ -15,6 +15,8 @@
 import Foundation
 import PackagePlugin
 
+fileprivate let Java2SwiftConfigFileName = "Java2Swift.config"
+
 @main
 struct Java2SwiftBuildToolPlugin: BuildToolPlugin {
   func createBuildCommands(context: PluginContext, target: Target) throws -> [Command] {
@@ -24,42 +26,39 @@ struct Java2SwiftBuildToolPlugin: BuildToolPlugin {
     // so we cannot eliminate this deprecation warning.
     let sourceDir = target.directory.string
 
-    // Read a configuration file JavaKit.config from the target that provides
-    // information needed to call Java2Swift.
+    // The name of the configuration file JavaKit.config from the target for
+    // which we are generating Swift wrappers for Java classes.
     let configFile = URL(filePath: sourceDir)
       .appending(path: "Java2Swift.config")
     let configData = try Data(contentsOf: configFile)
     let config = try JSONDecoder().decode(Configuration.self, from: configData)
 
     /// Find the manifest files from other Java2Swift executions in any targets
     /// this target depends on.
-    var manifestFiles: [URL] = []
-    func searchForManifestFiles(in target: any Target) {
+    var dependentConfigFiles: [(String, URL)] = []
+    func searchForConfigFiles(in target: any Target) {
       let dependencyURL = URL(filePath: target.directory.string)
 
-      // Look for a checked-in manifest file.
-      let generatedManifestURL = dependencyURL
-        .appending(path: "generated")
-        .appending(path: "\(target.name).swift2java")
-      let generatedManifestString = generatedManifestURL
+      // Look for a config file within this target.
+      let dependencyConfigURL = dependencyURL
+        .appending(path: Java2SwiftConfigFileName)
+      let dependencyConfigString = dependencyConfigURL
         .path(percentEncoded: false)
 
-      if FileManager.default.fileExists(atPath: generatedManifestString) {
-        manifestFiles.append(generatedManifestURL)
+      if FileManager.default.fileExists(atPath: dependencyConfigString) {
+        dependentConfigFiles.append((target.name, dependencyConfigURL))
       }
-
-      // TODO: Look for a manifest file that was built by the plugin itself.
     }
 
     // Process direct dependencies of this target.
     for dependency in target.dependencies {
       switch dependency {
       case .target(let target):
-        searchForManifestFiles(in: target)
+        searchForConfigFiles(in: target)
 
       case .product(let product):
         for target in product.targets {
-          searchForManifestFiles(in: target)
+          searchForConfigFiles(in: target)
         }
 
       @unknown default:
@@ -69,14 +68,7 @@ struct Java2SwiftBuildToolPlugin: BuildToolPlugin {
 
     // Process indirect target dependencies.
     for dependency in target.recursiveTargetDependencies {
-      searchForManifestFiles(in: dependency)
-    }
-
-    /// Determine the list of Java classes that will be translated into Swift,
-    /// along with the names of the corresponding Swift types. This will be
-    /// passed along to the Java2Swift tool.
-    let classes = config.classes.sorted { (lhs, rhs) in
-      lhs.0 < rhs.0
+      searchForConfigFiles(in: dependency)
     }
 
     let outputDirectory = context.pluginWorkDirectoryURL
@@ -86,27 +78,26 @@ struct Java2SwiftBuildToolPlugin: BuildToolPlugin {
       "--module-name", sourceModule.name,
       "--output-directory", outputDirectory.path(percentEncoded: false),
     ]
-    if let classPath = config.classPath {
-      arguments += ["-cp", classPath]
-    }
-    arguments += manifestFiles.flatMap { manifestFile in
-      [ "--manifests", manifestFile.path(percentEncoded: false) ]
-    }
-    arguments += classes.map { (javaClassName, swiftName) in
-      "\(javaClassName)=\(swiftName)"
+    arguments += dependentConfigFiles.flatMap { moduleAndConfigFile in
+      let (moduleName, configFile) = moduleAndConfigFile
+      return [
+        "--depends-on",
+        "\(moduleName)=\(configFile.path(percentEncoded: false))"
+      ]
     }
+    arguments.append(configFile.path(percentEncoded: false))
 
     /// Determine the set of Swift files that will be emitted by the Java2Swift
     /// tool.
-    let outputSwiftFiles = classes.map { (javaClassName, swiftName) in
+    let outputSwiftFiles = config.classes.map { (javaClassName, swiftName) in
       outputDirectory.appending(path: "\(swiftName).swift")
     } + [
       outputDirectory.appending(path: "\(sourceModule.name).swift2java")
     ]
 
     return [
       .buildCommand(
-        displayName: "Wrapping \(classes.count) Java classes target \(sourceModule.name) in Swift",
+        displayName: "Wrapping \(config.classes.count) Java classes target \(sourceModule.name) in Swift",
         executable: try context.tool(named: "Java2Swift").url,
         arguments: arguments,
         inputFiles: [ configFile ],

Sources/Java2Swift/JavaToSwift.swift

@@ -31,33 +31,33 @@ struct JavaToSwift: ParsableCommand {
   @Option(help: "The name of the Swift module into which the resulting Swift types will be generated.")
   var moduleName: String
 
-  @Argument(
-    help:
-      "The Java classes to translate into Swift written with their canonical names (e.g., java.lang.Object). If the Swift name of the type should be different from simple name of the type, it can appended to the class name with '=<swift name>'."
-  )
-  var classes: [String] = []
-
   @Option(
     help:
-      "The Java-to-Swift module manifest files for any Swift module containing Swift types created to wrap Java classes."
+      "A Java2Swift configuration file for a given Swift module name on which this module depends, e.g., JavaKitJar=Sources/JavaKitJar/Java2Swift.config. There should be one of these options for each Swift module that this module depends on (transitively) that contains wrapped Java sources."
   )
-  var manifests: [String] = []
+  var dependsOn: [String] = []
 
-  @Option(
+  @Flag(
     help:
-      "The Jar file from which the set of class names should be loaded, if the classes weren't explicitly listed."
+      "Specifies that the input is a Jar file whose public classes will be loaded. The output of Java2Swift will be a configuration file (Java2Swift.config) that can be used as input to a subsequent Java2Swift invocation to generate wrappers for those public classes."
   )
-  var jarFile: String? = nil
+  var jarFile: Bool = false
 
   @Option(
     name: [.customLong("cp"), .customLong("classpath")],
     help: "Class search path of directories and zip/jar files from which Java classes can be loaded."
   )
   var classpath: [String] = []
 
-  @Option(name: .shortAndLong, help: "The directory in which to output the generated Swift files and manifest.")
+  @Option(name: .shortAndLong, help: "The directory in which to output the generated Swift files or the Java2Swift configuration file.")
   var outputDirectory: String = "."
 
+  @Argument(
+    help:
+      "The input file, which is either a Java2Swift configuration file or (if '-jar-file' was specified) a Jar file."
+  )
+  var input: String
+
   mutating func run() throws {
     var vmOptions: [String] = []
     let classpath = classPathWithJarFile
@@ -76,62 +76,39 @@ struct JavaToSwift: ParsableCommand {
       environment: environment
     )
 
-    // Load all of the translation manifests this depends on.
-    for manifest in manifests {
-      try translator.loadTranslationManifest(from: URL(filePath: manifest))
-    }
-
-    if jarFile == nil && classes.isEmpty {
-      throw JavaToSwiftError.noClasses
-    }
+    // Load all of the configurations this depends on.
+    for config in dependsOn {
+      guard let equalLoc = config.firstIndex(of: "=") else {
+        throw JavaToSwiftError.badConfigOption(config)
+      }
 
-    // If we have a Jar file but no classes were listed, find all of the
-    // classes in the Jar file.
-    if let jarFileName = jarFile, classes.isEmpty {
-      let jarFile = try JarFile(jarFileName, false, environment: environment)
-      classes = jarFile.entries()!.compactMap { (entry) -> String? in
-        guard entry.getName().hasSuffix(".class") else {
-          return nil
-        }
+      let afterEqual = config.index(after: equalLoc)
+      let swiftModuleName = String(config[..<equalLoc])
+      let configFileName = String(config[afterEqual...])
 
-        // If any of the segments of the Java name start with a number, it's a
-        // local class that cannot be mapped into Swift.
-        for segment in entry.getName().split(separator: "$") {
-          if segment.starts(with: /\d/) {
-            return nil
-          }
-        }
+      try translator.loadDependentConfiguration(
+        forSwiftModule: swiftModuleName,
+        from: URL(filePath: configFileName)
+      )
+    }
 
-        return String(entry.getName().replacing("/", with: ".")
-          .dropLast(".class".count))
-      }
+    // Jar file mode: read a Jar file and output a configuration.
+    if jarFile {
+      return try emitConfiguration(forJarFile: input, environment: environment)
     }
 
+    // Load the configuration file.
+    let config = try translator.readConfiguration(from: URL(filePath: input))
+
     // Load all of the requested classes.
     let classLoader = URLClassLoader(
-      try classPathWithJarFile.map { try URL("file://\($0)", environment: environment) },
+      try classPathWithJarFile.map {
+        try URL("file://\($0)", environment: environment)
+      },
       environment: environment
     )
     var javaClasses: [JavaClass<JavaObject>] = []
-    for javaClassNameOpt in self.classes {
-      // Determine the Java class name and its resulting Swift name.
-      let javaClassName: String
-      let swiftName: String
-      if let equalLoc = javaClassNameOpt.firstIndex(of: "=") {
-        let afterEqual = javaClassNameOpt.index(after: equalLoc)
-        javaClassName = String(javaClassNameOpt[..<equalLoc])
-        swiftName = String(javaClassNameOpt[afterEqual...])
-      } else {
-        if let dotLoc = javaClassNameOpt.lastIndex(of: ".") {
-          let afterDot = javaClassNameOpt.index(after: dotLoc)
-          swiftName = String(javaClassNameOpt[afterDot...])
-        } else {
-          swiftName = javaClassNameOpt
-        }
-
-        javaClassName = javaClassNameOpt
-      }
-
+    for (javaClassName, swiftName) in config.classes {
       guard let javaClass = try classLoader.loadClass(javaClassName) else {
         print("warning: could not find Java class '\(javaClassName)'")
         continue
@@ -167,18 +144,15 @@ struct JavaToSwift: ParsableCommand {
         description: "Java class '\(javaClass.getCanonicalName())' translation"
       )
     }
-
-    // Translation manifest.
-    let manifestFileName = "\(moduleName).swift2java"
-    let manifestContents = try translator.encodeTranslationManifest()
-    try writeContents(manifestContents, to: manifestFileName, description: "translation manifest")
   }
 
   /// Return the class path augmented with the Jar file, if there is one.
   var classPathWithJarFile: [String] {
-    guard let jarFile else { return classpath }
+    if jarFile {
+      return [input] + classpath
+    }
 
-    return [jarFile] + classpath
+    return classpath
   }
 
   func writeContents(_ contents: String, to filename: String, description: String) throws {
@@ -196,17 +170,71 @@ struct JavaToSwift: ParsableCommand {
     )
     print(" done.")
   }
+
+  func emitConfiguration(forJarFile jarFileName: String, environment: JNIEnvironment) throws {
+    var configuration = Configuration(
+      classPath: classPathWithJarFile.joined(separator: ":")
+    )
+    let jarFile = try JarFile(jarFileName, false, environment: environment)
+    for entry in jarFile.entries()! {
+      // We only look at class files in the Jar file.
+      guard entry.getName().hasSuffix(".class") else {
+        continue
+      }
+
+      // If any of the segments of the Java name start with a number, it's a
+      // local class that cannot be mapped into Swift.
+      for segment in entry.getName().split(separator: "$") {
+        if segment.starts(with: /\d/) {
+          continue
+        }
+      }
+
+      let javaCanonicalName = String(entry.getName().replacing("/", with: ".")
+        .dropLast(".class".count))
+      configuration.classes[javaCanonicalName] =
+        javaCanonicalName.defaultSwiftNameForJavaClass
+    }
+
+    // Encode the configuration.
+    let encoder = JSONEncoder()
+    encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+    var contents = String(data: try encoder.encode(configuration), encoding: .utf8)!
+    contents.append("\n")
+
+    // Write the file.
+    try writeContents(
+      contents,
+      to: URL(filePath: outputDirectory)
+        .appending(path: "Java2Swift.config")
+        .path(percentEncoded: false),
+      description: "Java2Swift configuration file"
+    )
+  }
 }
 
 enum JavaToSwiftError: Error {
-  case noClasses
+  case badConfigOption(String)
 }
 
 extension JavaToSwiftError: CustomStringConvertible {
   var description: String {
     switch self {
-    case .noClasses:
-      "no classes to translate: either list Java classes or provide a Jar file"
+    case .badConfigOption(_):
+      "configuration option must be of the form '<swift module name>=<path to config file>"
     }
   }
 }
+
+extension String {
+  /// For a String that's of the form java.util.Vector, return the "Vector"
+  /// part.
+  fileprivate var defaultSwiftNameForJavaClass: String {
+    if let dotLoc = lastIndex(of: ".") {
+      let afterDot = index(after: dotLoc)
+      return String(self[afterDot...])
+    }
+
+    return self
+  }
+}