Merge pull request #29 from LabyMod/develop

Update 0.3.4

Author: Janrupf

.github/workflows/ci.yml

@@ -92,8 +92,8 @@ jobs:
         run: "chmod +x gradlew"
       - name: Build base with gradle
         run: "./gradlew -PCI=true -PnativeBinaryExternalDir=native-binaries ultralight-java-base:build"
-      - name: Build lwjgl3-opengl with gradle
-        run: "./gradlew -PCI=true -PnativeBinaryExternalDir=native-binaries ultralight-java-lwjgl3-opengl:build"
+      - name: Build lwjgl3-opengl example with gradle
+        run: "./gradlew -PCI=true -PnativeBinaryExternalDir=native-binaries example:lwjgl3-opengl:build"
       - name: Check license
         run: "./gradlew licenseCheck"
       - name: Deploy to OSSHR

README.md

@@ -26,13 +26,54 @@ based UI, while staying with the Java platform.
 Moreover, the databind API is capable of translating Java objects directly to JavaScript, allowing interop and Java 
 calls directly from within your JavaScript code, making integration with the UI even easier.
 
+# Using the library
+The library requires the Ultralight SDK, which can be downloaded 
+[here](https://github.com/ultralight-ux/Ultralight/blob/master/README.md#getting-the-latest-sdk). The native binaries of
+the SDK need to be available at runtime and can be loaded using the provided Java methods.
+
+### Maven
+Using the library with maven:
+```xml
+<dependency>
+  <groupId>com.labymedia</groupId>
+  <artifactId>ultralight-java-base</artifactId>
+  <!-- Replace with latest version from https://search.maven.org/artifact/com.labymedia/ultralight-java-base !-->
+  <version>0.3.4</version>
+</dependency>
+```
+
+If you need Javascript interop:
+```xml
+<dependency>
+  <groupId>com.labymedia</groupId>
+  <artifactId>ultralight-java-databind</artifactId>
+  <!-- Replace with latest version from https://search.maven.org/artifact/com.labymedia/ultralight-java-databind !-->
+  <version>0.3.4</version>
+</dependency>
+```
+
+### Gradle
+```kotlin
+dependencies {
+  // Replace with latest version from https://search.maven.org/artifact/com.labymedia/ultralight-java-base
+  implementation("com.labymedia", "ultralight-java-base", "0.3.4")
+
+  // // Replace with latest version from https://search.maven.org/artifact/com.labymedia/ultralight-java-databind
+  // Remove the comments if you need Javascript interop
+  // implementation("com.labymedia", "ultralight-java-databind", "0.3.4")
+}
+```
+
+The latest version can usually also be found in the 
+[VERSION file on the master branch](https://github.com/LabyMod/ultralight-java/blob/master/VERSION).
+
+**You will also need to download the Ultralight SDK and extract the `bin` folder into a directory given to
+the Library in order to provide the natives!**
+
+See [Examples](https://github.com/LabyMod/ultralight-java/tree/develop/example) for more info.
+
 # Licensing
 For Ultralight Java [LGPLv3](https://www.gnu.org/licenses/lgpl-3.0.en.html) is being used, however, Ultralight itself is
 licensed under a custom proprietary license. See
 [Ultralight licensing](https://github.com/ultralight-ux/Ultralight/blob/master/README.md#licensing) for further 
 information.
-
-# Using the library
-The library requires the Ultralight SDK, which can be downloaded 
-[here](https://github.com/ultralight-ux/Ultralight/blob/master/README.md#getting-the-latest-sdk). The native binaries of
-the SDK need to be available at runtime and can be loaded using the provided Java methods.

VERSION

@@ -1 +1 @@
-0.3.3
+0.3.4

ci.gradle

@@ -1,59 +1,77 @@
 import org.apache.tools.ant.taskdefs.condition.Os
 
+// This is the directory the library headers will be generated in
 ext.generatedHeadersDir = new File(buildDir, "generatedHeaders")
 if(!ext.generatedHeadersDir.exists() && !ext.generatedHeadersDir.mkdirs()) {
     throw new GradleException("Failed to create directory ${ext.generatedHeadersDir.absolutePath}")
 }
 
+// This is the directory where the native binaries can be found after compilation
 ext.nativeBinariesDir = new File(buildDir, "nativeBinaries")
 if(!ext.nativeBinariesDir.exists() && !ext.nativeBinariesDir.mkdirs()) {
     throw new GradleException("Failed to create directory ${ext.nativeBinariesDir.absolutePath}")
 }
 
+// Properties determining the build type
 def isExternalBuild = false
 def ciBuild = project.hasProperty("CI") && Boolean.parseBoolean(project.property("CI").toString())
 
 if(!project.hasProperty("nativeBinaryExternalDir")) {
-    if (Os.isFamily(Os.FAMILY_WINDOWS)) {
+    // The binaries will possibly be need to be built locally
+    if(Os.isFamily(Os.FAMILY_WINDOWS)) {
         // WARNING, this assumes CMake uses visual studio
         // For GCC or Clang the output should be $nativeBinariesDir/libultralight-java.dll
         ext.nativeBinaries = Arrays.asList(new File(nativeBinariesDir, "Debug/ultralight-java.dll"))
-    } else if (Os.isFamily(Os.FAMILY_MAC)) {
+    } else if(Os.isFamily(Os.FAMILY_MAC)) {
         ext.nativeBinaries = Arrays.asList(new File(nativeBinariesDir, "libultralight-java.dylib"))
-    } else if (Os.isFamily(Os.FAMILY_UNIX)) {
+    } else if(Os.isFamily(Os.FAMILY_UNIX)) {
         ext.nativeBinaries = Arrays.asList(new File(nativeBinariesDir, "libultralight-java.so"))
     } else {
-        if (!project.hasProperty("nativeBinaryLibrary")) {
+        if(!project.hasProperty("nativeBinaryLibrary")) {
+            // Unknown OS and missing binary, bail out
             throw new GradleException("Unable to determine native output library, " +
                     "pass -PnativeBinaryLibrary=/path/to/native/binary to gradle")
         } else {
+            // Unknown OS but the user specified the output binary
             ext.nativeBinaries = [new File(project.property("nativeBinaryLibrary").toString())]
         }
     }
 } else {
+    // The binaries have been built by an external process and can be used now
     def nativeBinaryExternalDir = file(project.property("nativeBinaryExternalDir").toString())
     if(!nativeBinaryExternalDir.exists()) {
+        // The directory where the binaries are supposed to be is missing, bail out
         throw new GradleException("nativeBinaryExternalDir ${nativeBinaryExternalDir.absolutePath} does not exist")
     }
 
     ext.nativeBinaries = new ArrayList<File>()
 
+    // Collect all native binaries built externally
     for(def file in nativeBinaryExternalDir.listFiles()) {
         println "Found native binary ${file.absolutePath}"
         ext.nativeBinaries.add(file)
     }
 
+    // Flag the build
     isExternalBuild = true
 }
 
 project(":ultralight-java-base").afterEvaluate { javaProject ->
     project(":ultralight-java-native").afterEvaluate { nativeProject ->
         if(!isExternalBuild) {
+            // If the binaries have not been built externally, building the java project requires
+            // building OS dependent binary locally
             javaProject.tasks["processResources"].dependsOn(nativeProject.tasks["build"])
         }
     }
 }
 
+/**
+ * Helper function to retrieve the file extensions from a file.
+ *
+ * @param file The file to retrieve the extension from
+ * @return The extension of the file, or an empty string, if the file does not have an extension
+ */
 static def getExtension(File file) {
     String fileName = file.getName()
 
@@ -64,16 +82,30 @@ static def getExtension(File file) {
     }
 }
 
+/**
+ * Helper function to retrieve the absolute path of a file without its extension.
+ *
+ * @param file The file to retrieve the path from
+ * @return The absolute path of the file without its extension, or the path itself,
+ *         if the file does not have an extension
+ */
 static def getPathWithoutExtension(File file) {
-    String fileName = file.getAbsolutePath()
+    String path = file.getAbsolutePath()
 
-    if(fileName.lastIndexOf(".") != -1 && fileName.lastIndexOf(".") != 0) {
-        return fileName.substring(0, fileName.lastIndexOf("."))
+    if(path.lastIndexOf(".") != -1 && path.lastIndexOf(".") != 0) {
+        return path.substring(0, path.lastIndexOf("."))
     } else {
-        return ""
+        return path
     }
 }
 
+/**
+ * Processes a binary file by calculating its new path and moving it if desired.
+ *
+ * @param binary The binary to process
+ * @param doMove If {@code true}, the file will be moved to the new path
+ * @return The new file of the binary
+ */
 def processBinary(File binary, boolean doMove) {
     String extension = getExtension(binary)
     String path = getPathWithoutExtension(binary)
@@ -89,12 +121,16 @@ def processBinary(File binary, boolean doMove) {
 }
 
 if(ciBuild) {
+    // We are running a CI build
     def ciDir = file("ci")
     if(!ciDir.exists() && !ciDir.mkdirs()) {
+        // Failed to create a necessary directory, bail out
         throw new GradleException("Failed to create directory ${ciDir.absolutePath}")
     }
 
     new File(ciDir, "binaries").withWriter {
+        // Write a file with paths to the native binaries, required by our script
+        // at .github/workflows/ci.yml to create an archive with natives
         for(File binary in ext.nativeBinaries) {
             it.write(processBinary(binary, false).absolutePath)
         }
@@ -104,13 +140,15 @@ if(ciBuild) {
 
     task moveNativeBinaries {
         doLast {
-            for (File binary in binaries) {
+            for(File binary in binaries) {
+                // Move the binaries to their new locations
                 processBinary(binary, true)
             }
         }
     }
 
     project(":ultralight-java-native").afterEvaluate { nativeProject ->
+        // Make sure the binaries are moved after the build
         nativeProject.tasks["build"].finalizedBy(moveNativeBinaries)
     }
 }