Skip to content

Conversation

@marktsuchida
Copy link
Member

@marktsuchida marktsuchida commented Jul 17, 2025

MMCoreJ is currently built with SWIG 2-3 (2 on Windows, 3 on macOS, but it makes little difference).

SWIG 4 replaced the std::vector and std::map wrappers with versions that fit better into Java by extending java.util.List and java.util.Map.

This results in the generated Java API from being incompatible with that generated by SWIG 2-3, in the following ways (based on japicmp output; see #37 for full details):

  • *Vector, with * = Boolean, Char, Double, Long, Str, Unsigned

    • The constructor taking Java long (and producing that many empty/zero elements) was removed
    • Parameter type for add() and set() was changed from primitive to boxed (for all but StrVector); these methods also newly have a return value
    • get() now returns boxed, rather than primitive, type
    • size() and capacity() now return int rather than long
    • reserve() now takes int rather than long
  • StrMap

    • get() takes Object instead of String (source-compatible but not binary-compatible)
    • set() is replaced by put()
    • del() is removed (in favor of remove())
    • has_key() is replaced by containsKey()
    • empty() is replaced by isEmpty()
    • size() now returns int rather than long

(I'm ignoring backward-compatible changes, and incompatible changes to generated classes that should not be considered part of the API, such as MMCoreJJNI.)

This PR explicitly adds back the *Vector constructors taking long. This was enough to get all of our Java modules in micro-manager to compile (as of this writing).

For the remaining incompatibilities, I suggest that we leave them alone:

  • The changes from unboxed to boxed types and from long to int may cause compile errors under certain usage, but they do not cause any silent change in semantics. And they are hopefully even less likely to cause errors in BeanShell scripts.

  • I'm inclined leave StrMap alone, since StrMap is not actually used as a parameter or return value to any API methods (currently, at least). Even if there is code that uses it, it will at most get a compile error that should be easy to fix.


Before merging:

  • Does swig-doc-converter (used by apidoc CI) work with SWIG 4 output?
  • Windows build machine image needs to have SWIG 4 available
  • macOS build machine image needs to have SWIG 4 available
  • apidoc CI job on micro-manager repo needs SWIG 4
  • Re-check that all of our Java modules build with the new code
  • Check that pycro-manager is not broken by this change
  • Update build instructions wherever we mention SWIG

Closes #37.

SWIG 4 replaced the `std::vector` and `std::map` wrappers with versions
that fit better into Java by extending `java.util.List` and
`java.util.Map`.

This results in the generated Java API from being incompatible with that
generated by SWIG 2-3, in the following ways (based on japicmp output):

- `*Vector`, with `*` = `Boolean`, `Char`, `Double`, `Long`, `Str`,
  `Unsigned`
  - The constructor taking Java `long` (and producing that many
    empty/zero elements) was removed
  - Parameter type for `add()` and `set()` was changed from primitive to
    boxed (for all but `StrVector`); these methods also newly have a
    return value
  - `get()` now returns boxed, rather than primitive, type
  - `size()` and `capacity()` now return `int` rather than `long`
  - `reserve()` now takes `int` rather than `long`

- `StrMap`
  - `get()` takes `Object` instead of `String` (source-compatible but
    not binary-compatible)
  - `set()` is replaced by `put()`
  - `del()` is removed (in favor of `remove()`)
  - `has_key()` is replaced by `containsKey()`
  - `empty()` is replaced by `isEmpty()`
  - `size()` now returns `int` rather than `long`

(I'm ignoring backward-compatible changes, and incompatible changes to
generated classes that should not be considered part of the API, such as
`MMCoreJJNI`.)

This PR explicitly adds back the `*Vector` constructors taking `long`.
This was enough to get all of our Java modules in `micro-manager` to
compile (as of this writing).

For the remaining incompatibilities, I suggest that we leave them alone:

- The changes from unboxed to boxed types and from `long` to `int` may
  cause compile errors under certain usage, but they do not cause any
  silent change in semantics. And they are hopefully even less likely to
  cause errors in BeanShell scripts.

- I'm inclined leave `StrMap` alone, since `StrMap` is not actually used
  as a parameter or return value to any API methods (currently, at
  least). Even if there is code that uses it, it will at most get a
  compile error that should be easy to fix.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Swig 4.0 makes incompatible changes to MMCoreJ API (and also fails build)

1 participant