Merge branch 'main' into jni-optional

Author: madsodgaard

.github/actions/prepare_env/action.yml

@@ -10,7 +10,6 @@ runs:
         distribution: ${{ matrix.jdk_vendor }}
         java-version: |
           24
-          21
           17
         cache: 'gradle'
     - name: Set JAVA_HOME_{N}

.unacceptablelanguageignore

@@ -3,4 +3,5 @@ Sources/_Subprocess/Platforms/Subprocess+Darwin.swift
 Sources/_Subprocess/Platforms/Subprocess+Linux.swift
 Sources/_Subprocess/Platforms/Subprocess+Unix.swift
 Sources/_Subprocess/Teardown.swift
-Sources/_Subprocess/Subprocess.swift
+Sources/_Subprocess/Subprocess.swift
+NOTICE.txt

Package.swift

@@ -422,6 +422,7 @@ let package = Package(
       name: "JExtractSwiftLib",
       dependencies: [
         .product(name: "SwiftBasicFormat", package: "swift-syntax"),
+        .product(name: "SwiftLexicalLookup", package: "swift-syntax"),
         .product(name: "SwiftSyntax", package: "swift-syntax"),
         .product(name: "SwiftSyntaxBuilder", package: "swift-syntax"),
         .product(name: "ArgumentParser", package: "swift-argument-parser"),

README.md

@@ -62,22 +62,65 @@ Required language/runtime versions:
 
 This project contains multiple builds, living side by side together.
 
-Depending on which part you are developing, you may want to run just the swift tests:
+You will need to have:
+- Swift (6.1.x+)
+- Java (24+ for FFM, even though we support lower JDK targets)
+- Gradle (installed by "Gradle wrapper" automatically when you run gradle through `./gradlew`)
+
+### Preparing your environment
+
+Install **Swift**, the easiest way to do this is to use **Swiftly**: [swift.org/install/](https://www.swift.org/install/).
+This should automatically install a recent Swift, but you can always make sure by running:
+
+```bash
+swiftly install 6.1.2 --use
+```
+
+Install a recent enough Java distribution. We validate this project using Corretto so you can choose to use that as well,
+however any recent enough Java distribution should work correctly. You can use sdkman to install Java:
+
+```bash
+# Install sdkman from: https://sdkman.io
+curl -s "https://get.sdkman.io" | bash
+sdk install java 17.0.15-amzn
+sdk install java 24.0.1-amzn
+
+sdk use java 24.0.1-amzn
+```
+
+The use of JDK 24 is required to build the project, even though the libraries being published may target lower Java versions.
+
+❗️ Please make sure to `export JAVA_HOME` such that swift-java can find the necessary java libraries!
+When using sdkman the easiest way to export JAVA_HOME is to export the "current" used JDK's home, like this:
+
+```bash
+export JAVA_HOME="$(sdk home java current)
+```
+
+### Testing your changes 
+
+Many tests, including source generation tests, are written in Swift and you can execute them all by running the 
+swift package manager test command:
 
 ```bash
 > swift test
 ```
 
-or the Java tests through the Gradle build. The Gradle build may also trigger some Swift compilation because of 
-interlinked dependencies of the two parts of Swift-Java. To run the Java build and tests use the Gradle wrapper script:
+When adding tests in `Tests/...` targets, you can run these tests (or filter a specific test using `swift test --filter type-or-method-name`).
+
+Some tests are implemented in Java and therefore need to be executed using Gradle.
+Please always use the gradle wrapper (`./gradlew`) to make sure to use the appropriate Gradle version
 
 ```bash
 > ./gradlew test
 ```
 
-Currently it is suggested to use Swift 6.0 and a Java 24+.
+> Tip: A lot of the **runtime tests** for code relying on `jextract` are **located in sample apps**, 
+> so if you need to runtime test any code relying on source generation steps of jextract, consider adding the tests
+> to an appropriate Sample. These tests are also executed in CI (which you can check in the `ci-validate.sh` script 
+> contained in every sample repository).
 
-### Sample Apps
+### Sample apps & tests
 
 Sample apps are located in the `Samples/` directory, and they showcase full "roundtrip" usage of the library and/or tools.
 
@@ -101,19 +144,27 @@ To run a simple example app showcasing the jextract (Java calling Swift) approac
 This will also generate the necessary sources (by invoking jextract, extracting the `Sources/ExampleSwiftLibrary`) 
 and generating Java sources in `src/generated/java`.
 
+#### Other sample apps
+
+Please refer to the [Samples](Samples) directory for more sample apps which showcase the various usage modes of swift-java.
+
 ## Benchmarks
 
 You can run Swift [ordo-one/package-benchmark](https://github.com/ordo-one/package-benchmark) and OpenJDK [JMH](https://github.com/openjdk/jmh) benchmarks in this project.
 
 Swift benchmarks are located under `Benchmarks/` and JMH benchmarks are currently part of the SwiftKit sample project: `Samples/SwiftKitSampleApp/src/jmh` because they depend on generated sources from the sample.
 
+### Swift benchmarks
+
 To run **Swift benchmarks** you can:
 
 ```bash
 cd Benchmarks
 swift package benchmark
 ```
 
+### Java benchmarks
+
 In order to run JMH benchmarks you can:
 
 ```bash
@@ -125,4 +176,20 @@ Please read documentation of both performance testing tools and understand that
 
 ## User Guide
 
-More details about the project and how it can be used are available in [USER_GUIDE.md](USER_GUIDE.md)
+More details about the project can be found in [docc](https://www.swift.org/documentation/docc/) documentation.
+
+To view the rendered docc documentation you can use the docc preview command:
+
+```bash
+xcrun docc preview Sources/SwiftJavaDocumentation/Documentation.docc
+
+# OR JavaKit to view JavaKit documentation:
+# xcrun docc preview Sources/JavaKit/Documentation.docc
+
+# ========================================
+# Starting Local Preview Server
+#	 Address: http://localhost:8080/documentation/documentation
+# ========================================
+# Monitoring /Users/ktoso/code/swift-java/Sources/SwiftJavaDocumentation/Documentation.docc for changes...
+
+```

Samples/JExtractJNISampleApp/Sources/MySwiftLibrary/MySwiftLibrary.swift

@@ -45,6 +45,11 @@ public func globalTakeIntInt(i: Int64, j: Int64) {
   p("i:\(i), j:\(j)")
 }
 
+public func echoUnsignedInt(i: UInt32, j: UInt64) -> UInt64 {
+  p("i:\(i), j:\(j)")
+  return UInt64(i) + j
+}
+
 // ==== Internal helpers
 
 func p(_ msg: String, file: String = #fileID, line: UInt = #line, function: String = #function) {

Samples/JExtractJNISampleApp/src/test/java/com/example/swift/MySwiftLibraryTest.java

@@ -61,4 +61,11 @@ void globalVariable() {
         MySwiftLibrary.setGlobalVariable(100);
         assertEquals(100, MySwiftLibrary.getGlobalVariable());
     }
+
+    @Test
+    void globalUnsignedIntEcho() {
+        int i = 12;
+        long l = 1200;
+        assertEquals(1212, MySwiftLibrary.echoUnsignedInt(12, 1200));
+    }
 }

Samples/SwiftKitSampleApp/Sources/MySwiftLibrary/MySwiftClass.swift

@@ -60,4 +60,16 @@ public class MySwiftClass {
   public func makeRandomIntMethod() -> Int {
     return Int.random(in: 1..<256)
   }
+
+  public func takeUnsignedChar(arg: UInt16) {
+    p("\(UInt32.self) = \(arg)")
+  }
+
+  public func takeUnsignedInt(arg: UInt32) {
+    p("\(UInt32.self) = \(arg)")
+  }
+
+  public func takeUnsignedLong(arg: UInt64) {
+    p("\(UInt64.self) = \(arg)")
+  }
 }

Samples/SwiftKitSampleApp/src/test/java/com/example/swift/UnsignedNumbersTest.java

@@ -0,0 +1,36 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2025 Apple Inc. and the Swift.org project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of Swift.org project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+package com.example.swift;
+
+import org.junit.jupiter.api.Test;
+import org.swift.swiftkit.ffm.AllocatingSwiftArena;
+
+public class UnsignedNumbersTest {
+    @Test
+    void take_uint32() {
+        try (var arena = AllocatingSwiftArena.ofConfined()) {
+            var c = MySwiftClass.init(1, 2, arena);
+            c.takeUnsignedInt(128);
+        }
+    }
+
+    @Test
+    void take_uint64() {
+        try (var arena = AllocatingSwiftArena.ofConfined()) {
+            var c = MySwiftClass.init(1, 2, arena);
+            c.takeUnsignedLong(Long.MAX_VALUE);
+        }
+    }
+}

Sources/JExtractSwiftLib/Common/TypeAnnotations.swift

@@ -0,0 +1,26 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2025 Apple Inc. and the Swift.org project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of Swift.org project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import JavaTypes
+import JavaKitConfigurationShared
+
+/// Determine if the given type needs any extra annotations that should be included
+/// in Java sources when the corresponding Java type is rendered.
+func getTypeAnnotations(swiftType: SwiftType, config: Configuration) -> [JavaAnnotation] {
+  if swiftType.isUnsignedInteger, config.effectiveUnsignedNumbersMode == .annotate {
+    return [JavaAnnotation.unsigned]
+  }
+
+  return []
+}

Sources/JExtractSwiftLib/Configuration+Extensions.swift

@@ -0,0 +1,25 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2024 Apple Inc. and the Swift.org project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of Swift.org project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import JavaKitConfigurationShared // TODO: this should become SwiftJavaConfigurationShared
+import JavaTypes // TODO: this should become SwiftJavaConfigurationShared
+
+extension Configuration {
+  public var effectiveUnsignedNumericsMode: UnsignedNumericsMode {
+    switch effectiveUnsignedNumbersMode {
+    case .annotate: .ignoreSign
+    case .wrapGuava: .wrapUnsignedGuava
+    }
+  }
+}