Skip to content

Upgrade of presets to 1.5

HGuillemet edited this page Jan 11, 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/java/org/bytedeco. 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):
git rm `grep -l 'DO NOT EDIT THIS FILE' *.java`
  1. Create directory PS/src/java/org/bytedeco/LIB for each native library.
  2. Move the corresponding Java presets file from the presets directory to this new directory, changing its name from LIB.java to LIB_presets.java. Change the package name and the class name in the file accordingly. Using the refactoring feature of your favorite IDE may help. Be sure to use git mv or your IDE moving feature instead of your system mv to keep the version history.
  3. Similarly, if helper classes exist, move them to the same package and rename the classes LIB_helper. If an helper class contains static classes, move these classes out as standalone classes in the same package. Again, your IDE may help in such task by adapting the imports and changing references. Ensure these files are added to the repository.
  4. At this point, the presets (and helpers) directory should be empty and can be deleted.
  5. Back to the presets file PS/src/java/org/bytedeco/LIB/LIB_presets.java: change the helper property in the annotations, if any, to the new helper package and class name, also add the new property global, with value LIB. This is the name of the main class that will contain the global members of the library (not enclosed in a C++ class). This class, like the package, is given the same name as the library. Please keep this name lowercase even if it is against usual Java conventions. This choice minimizes the risk of name clash with normal Java class that would be also named after the library name but would use the C++/Java convention. If the presets contains an inherit property change the referenced class name(s) by adding the _presets suffix and add the corresponding import if your IDE didn't do it for you.
  6. Create a directory PS/src/main/java9/module-info.java containing:
    module org.bytedeco.javacpp.PS {
      requires transitive org.bytedeco.javacpp;
      exports org.bytedeco.javacpp.LIB;
    }
    Repeat the exports line for each native library included in the presets. 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 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.