[piercifani]

Builds on #950 (prefix and postfix operators); only the second commit is new here.

Depends on swiftlang/swift-binding-generator-core#4, which adds the ExtractDecider hooks this uses (mayExtractMembers(of:), isExported(_:), isFromKnownModuleSource). SwiftExtract moved there in #957, so this PR no longer edits it. Until that PR is merged, build this branch with SWIFT_BINDING_GENERATOR_CORE_PATH pointing at a checkout of it.

Problem

jextract exports every declaration that passes the access level. To leave something out, the only option is a file or type pattern in swift-java.config (swiftFilterExclude). You can't leave out a single member, and a module can't export only the few declarations it means to.

In a large codebase this gets in the way:

• Warnings on Swift-only API. Public API with no Java mapping, such as tuples, [String: Any], Combine publishers or Codable plumbing, is reported as skipped on every run.
• Build failures. A declaration that is translated incorrectly breaks the build of the whole module, even when nobody needs it in Java.
• Size. Every exported declaration costs a JNI entrypoint and generated Java.

Running jextract over every public declaration of a production codebase with about 2,900 skipped declarations showed the scale. About 2,000 of those skips, and three quarters of the declarations whose generated Java didn't compile, were in code the codebase doesn't need in Java.

Changes

• @JavaExport(false) keeps a declaration out of the bindings. On a type or an extension, it applies to all their members and nested types:

  import SwiftJavaAnnotations // or SwiftJava, which re-exports it
  
  public struct Session {
    public var token: String
    @JavaExport(false) public var debugDump: [String: Any]
  }
  
  @JavaExport(false)
  extension Session { ... }

  @JavaExport keeps working as before; the macro now takes an optional Bool.

• "exportMode": "annotated" in swift-java.config exports only declarations marked @JavaExport, and the members of a type or extension marked @JavaExport. An unmarked type is still exported, with only its marked members, when one of its members is marked. The default, all, keeps today's behavior.

• Both are decided in JavaExtractDecider. The nearest marked enclosing declaration is found by walking up the syntax tree, so extensions and nested types need nothing extra. Declarations that aren't exported never reach translation.

• ExtractDecider.mayExtractMembers(of:), defaulting to true. An extension of a type that doesn't resolve, such as a Foundation type, is no longer reported as skipped when none of its members can be exported. Without this, annotated mode still warned about every such extension.

• Unexported types. A declaration whose signature uses a type that isn't exported is skipped with "uses 'T', which is not exported", instead of generating Java that refers to a missing class. ExtractDecider.isExported(_:) answers this for types from the module and from its dependencies, using each dependency's exportMode from its swift-java.config.

• Foundation types in annotated mode. The Data, Date and URL types jextract extracts when a module uses them are never filtered out by export mode, since SwiftExtract describes them itself and they carry no markers.

• A new SwiftJavaAnnotations module and product holds the JavaExport macro, with no dependency on the JNI runtime. Code that is also built for platforms without Java can then carry the marker. SwiftJava re-exports it, so existing @JavaExport uses compile unchanged.

Docs: the new option is in SwiftJavaConfigFile.md (regenerated with generate-config-docs), and SwiftJavaJextract.md gains a "Choosing what to export" section.

Open to other spellings, for example @JavaExport(.never) or a separate @JavaIgnore, or a different name for exportMode.

Testing

• New JNIExportControlTests (7 tests):
  • opted-out members, types and extensions don't appear in the Java output;
  • annotated mode exports exactly the marked declarations;
  • in both modes, the diagnostics sink receives no skipped declaration for code that isn't exported, including an extension of an unresolved type. Without the markers, the same source reports 4;
  • annotated mode keeps the Date and URL types;
  • a declaration using an unexported type, from the module or from a dependency, is skipped with that reason, and kept when the dependency exports everything.
• swift test passes.

[ktoso]

I don't think this is quite right, I'll have to dive deeper here.

We definitely would not spell it like that with a random "false".

It's also not true that it's not possible to control importing per member level -- filterInclude and filterExclude can be combined to make that work.

[piercifani]

Thanks @ktoso, happy to change the spelling. @JavaExport(.never) or a separate @JavaIgnore are options, whichever you prefer.

The goal of this PR is to have an equivalent of Skip’s // SKIP @nobridge (docs): a way to keep individual APIs that can’t be expressed in Java or Kotlin out of the bindings.

As far as I can tell, swiftFilterInclude/swiftFilterExclude match files and type names but not members. And even with member patterns, I don’t see how a filter could express this:

public final class Foo {
  @JavaExport(.never)
  public init() async throws { ... }

  public static func create() async throws -> Foo { try await Foo() }
}

Am I missing a combination?