Updated README.md. Use more stable usrsctp version.

jitsi · Nov 1, 2019 · 922ab61 · 922ab61
1 parent 6385119
commit 922ab61
Show file tree

Hide file tree

Showing 6 changed files with 130 additions and 41 deletions.
diff --git a/README.md b/README.md
@@ -15,59 +15,137 @@ Because JNI has a complex build process multiplied by being platform dependent,
 
 * The `usrsctp` module handles the compilation of the [`usrsctp`](https://github.com/sctplab/usrsctp).
 This maven module produces platform specific artifact having pre-compiled `usrsctp` static library and corresponding `C` API-header.
-`mvn package -DbuildSctp -f pom.xml -pl org.jitsi:usrsctp -am` will create a jar that will include the native library and the necessary include headers for current platform.
-Resulting artifact has target platform set as [maven classifier](https://maven.apache.org/pom.html), e.g. `usrsctp-1.0-SNAPSHOT-windows.jar` or `usrsctp-1.0-SNAPSHOT-linux.jar`
+The module is build only when `-DbuildSctp` switch is passed to Maven.
+`mvn package -DbuildSctp -f pom.xml -pl org.jitsi:usrsctp` will create a jar that will include the native library and the necessary include headers for current platform.
+A resulting `jar` artifact has [maven classifier](https://maven.apache.org/pom.html) specified as a concatenation of `usrsctp` commit and target platform.
+For example, an artifact for `Linux` might be named as `usrsctp-1.0-SNAPSHOT-7a8bc9a-linux.jar` with an example content:
+```text
+$ tree usrsctp-1.0-SNAPSHOT-7a8bc9a-linux --noreport
+usrsctp-1.0-SNAPSHOT-7a8bc9a-linux
+|-- META-INF
+|   |-- MANIFEST.MF
+|   `-- maven
+|       `-- org.jitsi
+|           `-- usrsctp
+|               `-- pom.xml
+|-- git.properties
+|-- include
+|   `-- usrsctp.h
+`-- lib
+    `-- libusrsctp.a
+```
 
 * The `jniwrapper` module has 3 nested modules:
   * The `jniwrapper-java` module includes the Java portion of the JNI API and interacts with the native code.
+    The artifact produced by this module has Java classes to interact with native `usrsctp` wrapper, it also has
+    necessary `JNI` `C` headers, generated from Java classes. An example of artifact content:
+    ```text
+    $ tree jniwrapper-java-1.0-SNAPSHOT --noreport
+    jniwrapper-java-1.0-SNAPSHOT
+    |-- META-INF
+    |   |-- MANIFEST.MF
+    |   `-- maven
+    |       `-- org.jitsi
+    |           `-- jniwrapper-java
+    |               |-- pom.properties
+    |               `-- pom.xml
+    |-- cz
+    |   `-- adamh
+    |       `-- utils
+    |           `-- NativeUtils.class
+    |-- native
+    |   `-- headers
+    |       `-- org_jitsi_modified_sctp4j_SctpJni.h
+    `-- org
+        `-- jitsi_modified
+            `-- sctp4j
+                |-- EightArgumentVoidFunc.class
+                |-- FourArgumentIntFunc.class
+                |-- IncomingSctpDataHandler.class
+                |-- OutgoingSctpDataHandler.class
+                `-- SctpJni.class
+    ```
   * The `jniwrapper-native` module contains the `C` portion of the JNI API that bridges the Java and the [`usrsctp`](https://github.com/sctplab/usrsctp) native lib.
-  It depends on both the `usrsctp` module (because it needs the pre-built `usrsctp` static library and include headers) and the `jniwrapper-java` module (to generate the `JNI` header file to match the `C` implementation from the Java file).
-  The `compile` build phase will create a new jni lib in `target/jnisctp/install/lib`.
-  The `package` build phase will create a platform specific `jar` that includes the java code and the shared native library for current platform.
-  It is intended that the JNI libs are built for each platform ahead of time and published ahead of time to `Maven` repository as platform specific artifacts.
+  The module is build only when `-DbuildJniSctp` switch is passed to Maven.
+  It depends on two other modules:
+    * `usrsctp` module, because it needs the pre-built `usrsctp` static library and include headers;
+    * `jniwrapper-java` module, because it need `java -h` generated `JNI` header file to match the `C` implementation.
+
+    The `compile` build phase of `jniwrapper-native` module will create a new dynamic jni lib in `target/jnisctp/install/lib`. E.g. on `Linux` it produces dynamic library `target/jnisctp/install/lib/linux/libjnisctp.so`.
+
+    The `package` build phase of `jniwrapper-native` module will create a platform specific `jar` that includes the java code and the shared native library for current platform. It is assumed that `usrsctp` artifact for target platform is already available in `Maven`.
+    Below is an example of artifact produced by `mvn package -DbuildSctp -DbuildJniSctp -f pom.xml -pl org.jitsi:jniwrapper-native -am` is presented:
+      ```text
+      $ tree jniwrapper-native-1.0-SNAPSHOT-linux --noreport
+      jniwrapper-native-1.0-SNAPSHOT-linux
+      |-- META-INF
+      |   |-- MANIFEST.MF
+      |   `-- maven
+      |       `-- org.jitsi
+      |           `-- jniwrapper-native
+      |               `-- pom.xml
+      `-- lib
+          `-- linux
+              `-- libjnisctp.so
+
+      ```
+  **Note:** It is intended that platform specific `Maven` arficats produced by `usrsctp` and `jniwrapper-native` modules are built on each supported platform independently and published ahead of time to `Maven` repository 
+  before the rest of the artifacts can be built in way which allow them to be used on any of supported platform.
+
   * The `jnilib` maven module combines the `jniwrapper-java` and `jniwrapper-native` into a single `jar` which includes the Java API and the native JNI library that will be loaded at runtime.
-  By default `jnilib` only include `jnisctp` native library only for current platform.
-  To have universal (**fat jar**) `jnilib` suitable to run on any supported platform it necessary to build and publish platform-specific `jniwrapper-native` artifacts for all supported platforms in advance and then build `jnilib` with `mvn package -DbuildXPlatJar -f pom.xml -pl org.jitsi:jnilib -am`.
+  When built with `mvn package -f pom.xml -DbuildSctp -DbuildJniSctp -pl org.jitsi:jnilib -am` the `jnilib` artifact only include native `jnisctp` library for current platform.
+  To have universal (**fat jar**) `jnilib` suitable to run on any supported platform it necessary to build and publish platform-specific `jniwrapper-native` artifacts for all supported platforms in advance and then pass `-DbuildXPlatJar` switch into Maven. For example, fat `jnilib` jar could be built with `mvn package -DbuildXPlatJar -f pom.xml -pl org.jitsi:jnilib -am`, which will produce fat jar with example content:
+    ```
+    ```
+
 
 * The `sctp` module contains the Java library on top of the JNI code. 
 The jar built by this is what is intended to be used by other code.
 
 ### Building the jar files
 * Clone the project and initialize [`usrsctp`](https://github.com/sctplab/usrsctp) git submodule.
-* Run `mvn package` (and `mvn install` to install locally)
-
-This will install all the jars built by the project.  Depend on the `org.jitsi:sctp` artifact to use `jitsi-sctp` in your code.
+* Run `mvn package -f pom.xml` (and `mvn install -f pom.xml` to install locally). It assumes that platform specific artifacts like `usrsctp` and `jniwrapper-native` are already available in Maven. To compile and install all artifacts locally run `mvn install -DbuildSctp -DbuildJniSctp -f pom.xml`, this will build native and `Java` code for current platform and install resulting artifacts to local repository.
+* Depend on the `org.jitsi:sctp` artifact to use `jitsi-sctp` in your project.
 
 ### (Re)Building a new JNI lib
 The JNI lib will need to be rebuilt if there is a change in the [`usrsctp`](https://github.com/sctplab/usrsctp) version or a change in the JNI wrapper `C` file.
-Changes in [`usrsctp`](https://github.com/sctplab/usrsctp) handled by re-compiling `usrsctp` artifact from corresponding maven module.
+Changes in [`usrsctp`](https://github.com/sctplab/usrsctp) handled by re-compiling `usrsctp` artifact from corresponding Maven module.
 Changes in JNI wrapper `C` code are handled by recompiling `jniwrapper-native` artifact from corresponding maven module.
 To re-build native libraries cross-platform [`CMake`](https://cmake.org/) build tool, `C` compiler and linker and `JDK` must be installed on system used to build.
 
-On each supported native platform following commands must be executed to produce platform specific `usrsctp` and `jniwrapper-native` artifacts:
+The following steps can be done to produce an updated version of `jitsi-sctp` artifact with newver version of `usrsctp` or `jniwrapper-native`:
 
 1. Clone the project with `git clone --recurse-submodules <jitsi-sctp-git-url>`.
-```
-> git clone --recurse-submodules https://github.com/jitsi/jitsi-sctp.git jitsi-sctp
-```
+    ```
+    > git clone --recurse-submodules https://github.com/jitsi/jitsi-sctp.git jitsi-sctp
+    ```
 
-2. [Optional] initialize the [usrsctp](https://github.com/sctplab/usrsctp) submodule with `git submodule update --init --recursive`:
-```
-jitsi-sctp/usrsctp/usrsctp>
-(check out whatever hash/version you want in case it distinct from what is defined by git submodule)
-```
+2. \[Optional\] initialize the [usrsctp](https://github.com/sctplab/usrsctp) submodule with `git submodule update --init --recursive`:
+    ```
+    jitsi-sctp/usrsctp/usrsctp>
+    (check out whatever hash/version you want in case it distinct from what is defined by git submodule)
+    ```
 
-3. Produce and install new platform specific `usrsctp` and `jniwrapper-native` artifacts 
-```
-jitsi-sctp> mvn clean package install -DbuildSctp -DbuildJniSctp -f pom.xml --projects org.jitsi:usrsctp,org.jitsi:jniwrapper-native -am
-```
+3. Produce an updated platform specific `usrsctp` artifact 
+    ```
+    jitsi-sctp> mvn clean package install -DbuildSctp -f pom.xml -pl org.jitsi:usrsctp
+    ```
 
-4. Regular `jitsi-sctp` artifact with native `jnisctp` bundled only for current platform can be build and installed with:
-```
-jitsi-sctp>mvn clean package install -f pom.xml
-```
+4. \[Optional\] Update `<usrsctp_commit_id>` property in `jniwrapper/pom.xml` to specify desired version of `usrsctp` to use.
 
-5. Once `usrsctp` and `jniwrapper-native` artifacts rebuilt and published to [Maven repository](https://github.com/jitsi/jitsi-maven-repository/) for each supported platform (`Windows`, `Linux`, `Mac`) with steps `1-3`, an updated **fat jar** could be build and installed with following command:
-```
-jitsi-sctp>mvn clean package install -DbuildXPlatJar -f pom.xml
-```
+5. Produce an updated platform specific `jniwrapper-native` artifact and publish it to Maven.
+    ```
+    jitsi-sctp> mvn clean package install -DbuildJniSctp -f pom.xml -pl org.jitsi:jniwrapper-native 
+    ```
+
+6. \[Optional\] Repeat steps `1 - 5` on each of supported platforms: `Linux`, `Mac OSX`, `Windows`.
+
+7. Once `usrsctp` and `jniwrapper-native` artifacts built and published to [Maven repository](https://github.com/jitsi/jitsi-maven-repository/) for each supported platform (`Windows`, `Linux`, `Mac`) with steps `1 - 6`, an updated **fat jar** could be build and installed with following command:
+    ```
+    jitsi-sctp> mvn clean package install -DbuildXPlatJar -f pom.xml
+    ```
+
+8. To produce `jitsi-sctp` artifact usable only on current platform steps `3 - 7` can be skipped and following command could be used instead:
+    ```
+    jitsi-sctp> mvn clean package install -DbuildSctp -DbuildJniSctp -f pom.xml
+    ```
diff --git a/jniwrapper/native/pom.xml b/jniwrapper/native/pom.xml
@@ -30,7 +30,7 @@
     <profiles>
         <profile>
             <!-- This profile is activated when the system property 'buildJniSctp' is defined (i.e. via
-            passing -DbuildJniSctp to maven).  It adds a dependency on the usrsctp jar (since we'll need
+            passing -DbuildJniSctp to maven).It adds a dependency on the usrsctp jar (since we'll need
             the built libraries and include headers from it) and recompiles the native jniwrapper code -->
             <id>build-jni-sctp</id>
             <activation>
@@ -130,7 +130,7 @@
                                         <argument>-DJNISCTP_JNI_HEADERS_DIR=${jniwrapper_java_headers_dir}/native/headers</argument>
                                         <argument>-DJNISCTP_USRSCTP_DIR=${usrsctp_prebuilt_dir}</argument>
                                         <argument>-DCMAKE_INSTALL_PREFIX=${jnisctp_install_dir}</argument>
-                                        <argument>${cmake_c_flags}</argument>
+                                        <argument>-DCMAKE_C_FLAGS='${cmake_c_flags}'</argument>
                                         <argument>${cmake_generator_platform}</argument>
                                         <argument>${project.basedir}/src</argument>
                                     </arguments>

diff --git a/jniwrapper/pom.xml b/jniwrapper/pom.xml
@@ -12,7 +12,15 @@
     </parent>
 
     <properties>
-        <usrsctp_commit_id>7cd64a3</usrsctp_commit_id>
+        <!--
+          A specific commit of https://github.com/sctplab/usrsctp to use during compilation.
+          It is supposed that maven artifact produced by `usrsctp` maven module is built
+          in advance. The usrsctp version to use must be carefully chosen, due to various
+          issues inside intermediate versions of usrsctp. Currently the usrsctp version chosen
+          is used by Chromium 78. This version is proven to be stable enough to pass WebRTC's
+          stress test suite: https://webrtc.googlesource.com/src/+/2ebbff83eef7db5a3c70b8378aaabafa0a11099a/media/sctp/sctp_transport_reliability_unittest.cc
+        -->
+        <usrsctp_commit_id>7a8bc9a</usrsctp_commit_id>
     </properties>
 
     <artifactId>jniwrapper</artifactId>

diff --git a/pom.xml b/pom.xml
@@ -26,7 +26,7 @@
                 </os>
             </activation>
             <properties>
-                <cmake_c_flags>-DCMAKE_C_FLAGS='-fno-omit-frame-pointer -fno-optimize-sibling-calls'</cmake_c_flags>
+                <cmake_c_flags>-fno-omit-frame-pointer -fno-optimize-sibling-calls -Wno-format-truncation</cmake_c_flags>
                 <cmake_generator_platform/>
                 <maven_platform_classifier>darwin</maven_platform_classifier>
             </properties>
@@ -40,7 +40,7 @@
                 </os>
             </activation>
             <properties>
-                <cmake_c_flags>-DCMAKE_C_FLAGS='-fno-omit-frame-pointer -fno-optimize-sibling-calls -Wno-format-truncation -Wno-address-of-packed-member'</cmake_c_flags>
+                <cmake_c_flags>-fno-omit-frame-pointer -fno-optimize-sibling-calls -Wno-format-truncation -Wno-address-of-packed-member</cmake_c_flags>
                 <cmake_generator_platform/>
                 <maven_platform_classifier>linux</maven_platform_classifier>
             </properties>
@@ -54,7 +54,7 @@
             </activation>
             <properties>
                 <cmake_generator_platform>-DCMAKE_GENERATOR_PLATFORM=x64</cmake_generator_platform>
-                <cmake_c_flags/>
+                <cmake_c_flags></cmake_c_flags>
                 <maven_platform_classifier>windows</maven_platform_classifier>
             </properties>
         </profile>

diff --git a/usrsctp/pom.xml b/usrsctp/pom.xml
@@ -72,9 +72,12 @@
                                         <argument>-DCMAKE_BUILD_TYPE=RelWithDebInfo</argument>
                                         <argument>-DCMAKE_POSITION_INDEPENDENT_CODE=ON</argument>
                                         <argument>-Dsctp_invariants=ON</argument>
+                                        <argument>-Dsctp_inet=OFF</argument>
+                                        <argument>-Dsctp_inet6=OFF</argument>
                                         <argument>-Dsctp_debug=OFF</argument>
+                                        <argument>-Dsctp_build_programs=OFF</argument>
                                         <argument>${cmake_generator_platform}</argument>
-                                        <argument>${cmake_c_flags}</argument>
+                                        <argument>-DCMAKE_C_FLAGS='${cmake_c_flags} -D__FUNCTION__=__func__'</argument>
                                         <argument>-DCMAKE_INSTALL_PREFIX=${usrsctp_install_dir}</argument>
                                         <argument>${usrsctp_source_dir}</argument>
                                     </arguments>

diff --git a/usrsctp/usrsctp b/usrsctp/usrsctp