Skip to content

Upgrade of presets to 1.5

HGuillemet edited this page Feb 1, 2019 · 14 revisions

This is the procedure to transform a pre-1.5 JavaCPP presets to a 1.5 presets, compatible with the Java Platform Module System. OpenCV and ffmpeg presets have already been upgraded to 1.5 and can be used as a model for upgrading other presets.

In the following <PS> is the name of the presets (e.g. ffmpeg) and <LIB> is the name of a native library (e.g. avcodec).

  1. Delete and remove from repository all generated Java files located in <PS>/src/main/java/org/bytedeco/javacpp. Beware not to remove not-generated source files that may have been created in this directory. This can be safely done with a command like (using a unix shell):
cd <PS>/src/main/java/org/bytedeco/javacpp
git rm `grep -l 'DO NOT EDIT THIS FILE' *.java`
  1. Rename the <PS>/src/main/java/org/bytedeco/javacpp directory to <PS>/src/main/java/org/bytedeco/<PS>, and adjust the packages and references in the helper and presets classes accordingly. A search&replace of org.bytedeco.javacpp.presets by org.bytedeco.<PS>.presets and org.bytedeco.javacpp.helper by org.bytedeco.<PS>.helper will do.
  2. Create directory <PS>/src/java/org/bytedeco/<PS>/<LIB> for each native library. For presets with a single native library, you can skip this step.
  3. Create directory <PS>/src/java/org/bytedeco/<PS>/global
  4. In the presets files <PS>/src/java/org/<PS>/presets/<LIB>.java: change the value of the target property to org.bytedeco.<PS>.<LIB>, or to org.bytedeco.<PS> if you skipped step 3. Add after the target property the new property global, with value org.bytedeco.<PS>.global.<LIB>. This is the name of the main class that will contain the global members of the library (not enclosed in a C++ class).
  5. If some helper classes <PS>/src/main/java/org/bytedeco/helper/<LIB>.java contain static classes, move these classes out as standalone classes in the directory <PS>/src/main/java/org/bytedeco/<PS>/<LIB> (or <PS>/src/main/java/org/bytedeco/<PS> if you skipped step 3). Again, your IDE may help in such task by adapting the packages and changing references. Ensure these files are added to the repository. If the class contains native methods (has a static { Loader.load(); } initializer), add the following annotation so that the generator knows to which library they must be linked:
    @Properties(inherit = org.bytedeco.<PS>.presets.<LIB>.class)
  6. Create <PS>/src/main/java9/module-info.java containing:
    module org.bytedeco.<PS> {
      requires transitive org.bytedeco.javacpp;
      exports org.bytedeco.<PS>.global;
      exports org.bytedeco.<PS>.<LIB>;
    }
    Repeat the exports line for each native library included in the presets (or omit <LIB> if you skipped step 3). Also add any exported package that doesn't map a library, if such package exists. Add this file to the repository.
  7. That's it. Give it a try with a mvn clean install -pl .,<PS>
  8. If the build is successful, uncomment the lines related to the preset in the Travis config file /.travis.yml and AppVeyor config file /.appveyor.yml.
  9. Add the generated sources to the repository: git add <PS>/src/gen.
  10. Publish a PR.