Skip to content

Commit 65666d9

Browse files
ktosoktoso
committed
Update the USER_GUIDE to reflect new commands
1 parent 88ccc11 commit 65666d9

File tree

1 file changed

+51
-44
lines changed

1 file changed

+51
-44
lines changed

‎USER_GUIDE.md

Lines changed: 51 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,8 @@ Before using this package, set the `JAVA_HOME` environment variable to point at
88

99
### Using Java libraries from Swift
1010

11-
Existing Java libraries can be wrapped for use in Swift with the `Java2Swift`
12-
tool. In a Swift program, the most direct way to access a Java API is to use the SwiftPM plugin to provide Swift wrappers for the Java classes. To do so, add a configuration file `Java2Swift.config` into the source directory for the Swift target. This is a JSON file that specifies Java classes and the Swift type name that should be generated to wrap them. For example, the following file maps `java.math.BigInteger` to a Swift type named `BigInteger`:
11+
Existing Java libraries can be wrapped for use in Swift with the `swift-java`
12+
tool. In a Swift program, the most direct way to access a Java API is to use the SwiftPM plugin to provide Swift wrappers for the Java classes. To do so, add a configuration file `swift-java.config` into the source directory for the Swift target. This is a JSON file that specifies Java classes and the Swift type name that should be generated to wrap them. For example, the following file maps `java.math.BigInteger` to a Swift type named `BigInteger`:
1313

1414
```json
1515
{
@@ -31,11 +31,11 @@ or, equivalently, adding the following to the package dependencies:
3131
.package(url: "https://github.com/swiftlang/swift-java", branch: "main"),
3232
```
3333

34-
Finally, update `Package.swift` so that the `Java2SwiftPlugin` plugin runs on the target in which you want to generate Swift wrappers. The plugin looks like this:
34+
Finally, update `Package.swift` so that the `SwiftJavaPlugin` plugin runs on the target in which you want to generate Swift wrappers. The plugin looks like this:
3535

3636
```swift
3737
plugins: [
38-
.plugin(name: "Java2SwiftPlugin", package: "swift-java"),
38+
.plugin(name: "SwiftJavaPlugin", package: "swift-java"),
3939
]
4040
```
4141

@@ -101,10 +101,10 @@ let bigInt = BigInteger(veryBigNumber, environment: jniEnvironment)
101101

102102
### Importing a Jar file into Swift
103103

104-
Java libraries are often distributed as Jar files. The `Java2Swift` tool can inspect a Jar file to create a `Java2Swift.config` file that will wrap all of the public classes for use in Swift. Following the example in `swift-java/Samples/JavaSieve`, we will wrap a small [Java library for computing prime numbers](https://github.com/gazman-sdk/quadratic-sieve-Java) for use in Swift. Assuming we have a Jar file `QuadraticSieve-1.0.jar` in the package directory, run the following command:
104+
Java libraries are often distributed as Jar files. The `swift-java` tool can inspect a Jar file to create a `swift-java.config` file that will wrap all of the public classes for use in Swift. Following the example in `swift-java/Samples/JavaSieve`, we will wrap a small [Java library for computing prime numbers](https://github.com/gazman-sdk/quadratic-sieve-Java) for use in Swift. Assuming we have a Jar file `QuadraticSieve-1.0.jar` in the package directory, run the following command:
105105

106106
```swift
107-
swift run Java2Swift --module-name JavaSieve --jar QuadraticSieve-1.0.jar
107+
swift-java generate --module-name JavaSieve --jar QuadraticSieve-1.0.jar
108108
```
109109

110110
The resulting configuration file will look something like this:
@@ -142,7 +142,7 @@ The resulting configuration file will look something like this:
142142
}
143143
```
144144

145-
As with the previous `JavaProbablyPrime` sample, the `JavaSieve` target in `Package.swift` should depend on the `swift-java` package modules (`JavaKit`) and apply the `Java2Swift` plugin. This makes all of the Java classes found in the Jar file available to Swift within the `JavaSieve` target.
145+
As with the previous `JavaProbablyPrime` sample, the `JavaSieve` target in `Package.swift` should depend on the `swift-java` package modules (`JavaKit`) and apply the `swift-java` plugin. This makes all of the Java classes found in the Jar file available to Swift within the `JavaSieve` target.
146146

147147
If you inspect the build output, there are a number of warnings that look like this:
148148

@@ -159,12 +159,12 @@ These warnings mean that some of the APIs in the Java library aren't available i
159159
.product(name: "JavaKit", package: "swift-java"),
160160
],
161161
plugins: [
162-
.plugin(name: "Java2SwiftPlugin", package: "swift-java"),
162+
.plugin(name: "SwiftJavaPlugin", package: "swift-java"),
163163
]
164164
),
165165
```
166166

167-
Then define a a Java2Swift configuration file in `Sources/JavaMath/Java2Swift.config` to bring in the types we need:
167+
Then define a a swift-java configuration file in `Sources/JavaMath/swift-java.config` to bring in the types we need:
168168

169169
```json
170170
{
@@ -255,7 +255,7 @@ public class HelloSwift {
255255
}
256256
```
257257

258-
On the Swift side, the Java class needs to be exposed to Swift through `Java2Swift.config`, e.g.,:
258+
On the Swift side, the Java class needs to be exposed to Swift through `swift-java.config`, e.g.,:
259259

260260
```swift
261261
{
@@ -393,7 +393,7 @@ A number of JavaKit modules provide Swift projections of Java classes and interf
393393
| `java.lang.Throwable` | `Throwable` | `JavaKit` |
394394
| `java.net.URL` | `URL` | `JavaKitNetwork` |
395395

396-
The `Java2Swift` tool can translate any other Java classes into Swift projections. The easiest way to use `Java2Swift` is with the SwiftPM plugin described above. More information about using this tool directly are provided later in this document
396+
The `swift-java` tool can translate any other Java classes into Swift projections. The easiest way to use `swift-java` is with the SwiftPM plugin described above. More information about using this tool directly are provided later in this document
397397

398398
#### Improve parameter names of imported Java methods
399399
When building Java libraries you can pass the `-parameters` option to javac
@@ -438,65 +438,71 @@ public struct Enumeration<E: AnyJavaObject> {
438438
}
439439
```
440440

441-
## Translating Java classes with `Java2Swift`
441+
## Translating Java classes with `swift-java`
442442

443-
The `Java2Swift` is a Swift program that uses Java's runtime reflection facilities to translate the requested Java classes into their Swift projections. The output is a number of Swift source files, each of which corresponds to a
444-
single Java class. The `Java2Swift` can be executed like this:
443+
The `swift-java` is a Swift program that uses Java's runtime reflection facilities to translate the requested Java classes into their Swift projections. The output is a number of Swift source files, each of which corresponds to a
444+
single Java class. The `swift-java` can be executed like this:
445445

446446
```
447-
swift run Java2Swift
447+
swift-java
448448
```
449449

450450
to produce help output like the following:
451451

452452
```
453-
USAGE: Java2Swift --module-name <module-name> [--depends-on <depends-on> ...] [--jar] [--cp <cp> ...] [--output-directory <output-directory>] <input>
453+
OVERVIEW: Generate sources and configuration for Swift and Java interoperability.
454454
455-
ARGUMENTS:
456-
<input> The input file, which is either a Java2Swift
457-
configuration file or (if '-jar' was specified)
458-
a Jar file.
455+
USAGE: swift-java <options> <subcommand>
459456
460457
OPTIONS:
461-
--module-name <module-name>
462-
The name of the Swift module into which the resulting
463-
Swift types will be generated.
464458
--depends-on <depends-on>
465-
A Java2Swift configuration file for a given Swift
466-
module name on which this module depends, e.g.,
467-
JavaKitJar=Sources/JavaKitJar/Java2Swift.config.
468-
There should be one of these options for each Swift
469-
module that this module depends on (transitively)
470-
that contains wrapped Java sources.
471-
--jar Specifies that the input is a Jar file whose public
472-
classes will be loaded. The output of Java2Swift will
473-
be a configuration file (Java2Swift.config) that can
474-
be used as input to a subsequent Java2Swift
475-
invocation to generate wrappers for those public
476-
classes.
477-
--cp, --classpath <cp> Class search path of directories and zip/jar files
478-
from which Java classes can be loaded.
459+
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
460+
module depends on (transitively) that contains wrapped Java sources.
461+
--jar 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
462+
generate wrappers for those public classes.
463+
--fetch Fetch dependencies from given target (containing swift-java configuration) or dependency string
464+
--swift-native-implementation <swift-native-implementation>
465+
The names of Java classes whose declared native methods will be implemented in Swift.
466+
--output-swift <output-swift>
467+
The directory where generated Swift files should be written. Generally used with jextract mode.
468+
--output-java <output-java>
469+
The directory where generated Java files should be written. Generally used with jextract mode.
470+
--java-package <java-package>
471+
The Java package the generated Java code should be emitted into.
472+
-c, --cache-directory <cache-directory>
473+
Directory where to write cached values (e.g. swift-java.classpath files)
479474
-o, --output-directory <output-directory>
480-
The directory in which to output the generated Swift
481-
files or the Java2Swift configuration file. (default:
482-
.)
475+
The directory in which to output the generated Swift files or the SwiftJava configuration file.
476+
--input-swift <input-swift>
477+
Directory containing Swift files which should be extracted into Java bindings. Also known as 'jextract' mode. Must be paired with --output-java and --output-swift.
478+
-l, --log-level <log-level>
479+
Configure the level of logs that should be printed (values: trace, debug, info, notice, warning, error, critical; default: log level)
480+
--cp, --classpath <cp> Class search path of directories and zip/jar files from which Java classes can be loaded.
481+
-f, --filter-java-package <filter-java-package>
482+
While scanning a classpath, inspect only types included in this package
483483
-h, --help Show help information.
484+
485+
SUBCOMMANDS:
486+
configure Configure and emit a swift-java.config file based on an input dependency or jar file
487+
resolve Resolve dependencies and write the resulting swift-java.classpath file
488+
489+
See 'swift-java help <subcommand>' for detailed help.
484490
```
485491

486492
For example, the `JavaKitJar` library is generated with this command line:
487493

488494
```swift
489-
swift run Java2Swift --module-name JavaKitJar --depends-on JavaKit=Sources/JavaKit/Java2Swift.config -o Sources/JavaKitJar/generated Sources/JavaKitJar/Java2Swift.config
495+
swift run swift-java --module-name JavaKitJar --depends-on JavaKit=Sources/JavaKit/swift-java.config -o Sources/JavaKitJar/generated Sources/JavaKitJar/swift-java.config
490496
```
491497

492498
The `--module-name JavaKitJar` parameter describes the name of the Swift module in which the code will be generated.
493499

494-
The `--depends-on` option is followed by the Java2Swift configuration files for any library on which this Swift library depends. Each `--depends-on` option is of the form `<swift library name>=<Java2Swift.config path>`, and tells Java2Swift which other Java classes have already been translated to Swift. For example, if your Java class uses `java.net.URL`, then you should include
500+
The `--depends-on` option is followed by the swift-java configuration files for any library on which this Swift library depends. Each `--depends-on` option is of the form `<swift library name>=<swift-java.config path>`, and tells swift-java which other Java classes have already been translated to Swift. For example, if your Java class uses `java.net.URL`, then you should include
495501
`JavaKitNetwork`'s configuration file as a dependency here.
496502

497503
The `-o` option specifies the output directory. Typically, this will be `Sources/<module name>/generated` or similar to keep the generated Swift files separate from any hand-written ones. To see the output on the terminal rather than writing files to disk, pass `-` for this option.
498504

499-
Finally, the command line should contain the `Java2Swift.config` file containing the list of classes that should be translated into Swift and their corresponding Swift type names. The tool will output a single `.swift` file for each class, along with warnings for any public API that cannot be translated into Swift. The most common warnings are due to missing Swift projections for Java classes. For example, here we have not translated (or provided the translation manifests for) the Java classes
505+
Finally, the command line should contain the `swift-java.config` file containing the list of classes that should be translated into Swift and their corresponding Swift type names. The tool will output a single `.swift` file for each class, along with warnings for any public API that cannot be translated into Swift. The most common warnings are due to missing Swift projections for Java classes. For example, here we have not translated (or provided the translation manifests for) the Java classes
500506
`java.util.zip.ZipOutputStream` and `java.io.OutputStream`:
501507

502508
```
@@ -507,7 +513,7 @@ warning: Unable to translate 'java.util.jar.JarInputStream' method 'transferTo':
507513

508514
The result of such warnings is that certain information won't be statically available in Swift, e.g., the superclass won't be known (so we will assume it is `JavaObject`), or the specified constructors or methods won't be translated. If you don't need these APIs, the warnings can be safely ignored. The APIs can still be called dynamically via JNI.
509515

510-
The `--jar` option changes the operation of `Java2Swift`. Instead of wrapping Java classes in Swift, it scans the given input Jar file to find all public classes and outputs a configuration file `Java2Swift.config` mapping all of the Java classes in the Jar file to Swift types. The `--jar` mode is expected to be used to help import a Java library into Swift wholesale, after which Java2Swift should invoked again given the generated configuration file.
516+
The `--jar` option changes the operation of `swift-java`. Instead of wrapping Java classes in Swift, it scans the given input Jar file to find all public classes and outputs a configuration file `swift-java.config` mapping all of the Java classes in the Jar file to Swift types. The `--jar` mode is expected to be used to help import a Java library into Swift wholesale, after which swift-java should invoked again given the generated configuration file.
511517

512518
### Under construction: Create a Java class to wrap the Swift library
513519

@@ -651,6 +657,7 @@ A Swift function may accept a closure which is used as a callback:
651657
func callMe(maybe: () -> ()) {}
652658
```
653659

660+
Minimal support for c-compatible closures is implemented, more documentation soon.
654661

655662

656663
## `jextract-swift` importer behavior

0 commit comments

Comments
 (0)