You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@datasketches.apache.org by dc...@apache.org on 2021/09/07 21:05:13 UTC
[datasketches-memory] branch UpdateDocs updated: More documentation
updates
This is an automated email from the ASF dual-hosted git repository.
dcromberge pushed a commit to branch UpdateDocs
in repository https://gitbox.apache.org/repos/asf/datasketches-memory.git
The following commit(s) were added to refs/heads/UpdateDocs by this push:
new 49d187e More documentation updates
49d187e is described below
commit 49d187e5b04787df51be3adf1c59cf5c0a46d86c
Author: David Cromberge <dc...@apache.org>
AuthorDate: Tue Sep 7 22:02:25 2021 +0100
More documentation updates
---
README.md | 12 +++---
docs/usage-examples.md | 103 +++++++++++++++++++++++++------------------------
2 files changed, 58 insertions(+), 57 deletions(-)
diff --git a/README.md b/README.md
index 2ddfcc3..aac106d 100644
--- a/README.md
+++ b/README.md
@@ -163,12 +163,12 @@ A build script named **compile-package-jar.sh** has been provided to package a J
The build script performs the following steps:
-1) Sets up staging directories under **target/** for the package files
-2) Uses git commands to gather information about the current Git commit and branch
-3) Compiles java source tree and assembles javadocs
-4) Packages a JAR containing compiled sources together with the Manifest, Licence and Notice files
-5) Packages a javadoc JAR containing documentation files together with the Manifest, Licence and Notice files
-6) Checks and tests the assembled JAR by using the API to access four different resource types
+1. Sets up staging directories under **target/** for the package files
+2. Uses git commands to gather information about the current Git commit and branch
+3. Compiles java source tree and assembles javadocs
+4. Packages a JAR containing compiled sources together with the Manifest, Licence and Notice files
+5. Packages a javadoc JAR containing documentation files together with the Manifest, Licence and Notice files
+6. Checks and tests the assembled JAR by using the API to access four different resource types
The build script is located in the **tools/scripts/** directory and requires the following arguments:
diff --git a/docs/usage-examples.md b/docs/usage-examples.md
index 8968bea..2b1b933 100644
--- a/docs/usage-examples.md
+++ b/docs/usage-examples.md
@@ -20,7 +20,8 @@
# Usage Examples
You may need to supply additional runtime arguments to the JVM depending on how you are using the Datasketches Memory library.
-There are several applicable use cases that are considered:
+For more information regarding required JPMS arguments and when they are applicable, see the [README](../README.md).
+This document provides examples for the following scenarios:
1. Using the library from a Java 8 application
2. Using the library with on-heap memory only
@@ -34,10 +35,11 @@ No additional runtime arguments are required.
As an example, consider the following launch script that compiles and runs a simple Java 8 application:
```shell
- export JAVA_HOME=$JAVA8_HOME
- export JAVAC=$JAVA_HOME/bin/javac
- export JAR=$JAVA_HOME/bin/jar
- export JAVA=$JAVA_HOME/bin/java
+ JH=$JAVA8_HOME
+ JAVAC=$JH/bin/javac
+ JAVA=$JH/bin/java
+ JAR=$JH/bin/jar
+
patha=nomvn-jdk8
cd $patha
@@ -46,54 +48,52 @@ As an example, consider the following launch script that compiles and runs a sim
echo "--- CLEAN & COMPILE ---"
rm -rf target
- mkdir target
- mkdir target/classes
- mkdir target/test-classes
+ mkdir -p target/test-classes
- $JAVAC -d target/test-classes/ -cp "libs/*" $(find . -name '*.java')
+ $JAVAC\
+ -d target/test-classes/\
+ -cp libs/*\
+ $(find . -name '*.java')
echo "---- RUN ----"
- echo PWD:$(pwd)
$JAVA\
- -cp target/test-classes:libs/*:src/test/resources/\
- org.xyz.memory.CheckJava8
+ -cp libs/*:target/test-classes:src/test/resources/\
+ org.xyz.memory.RunMain
```
-### 2) Using the library with on-heap memory only, or with off-heap memory allocated via ByteBuffer by the user.
+### 2) Using the library with on-heap memory only
-No additional runtime arguments are required, regardless of whether the library is used from a Java 8 or Java 9+
-application.
+Similarly, no additional runtime arguments are required in this scenario - regardless of whether the library is used from a Java 8 or Java 9+ application.
As an example, consider the following launch script that compiles and runs a simple Java 9 application that only exclusively
uses on-heap memory:
```shell
- export JAVA_HOME=$JAVA9_HOME
- export JAVAC=$JAVA_HOME/bin/javac
- export JAR=$JAVA_HOME/bin/jar
- export JAVA=$JAVA_HOME/bin/java
+ JH=$JAVA9_HOME
+ JAVAC=$JH/bin/javac
+ JAVA=$JH/bin/java
+ JAR=$JH/bin/jar
+
patha=nomvn-nomod-heap-jdk9
cd $patha
- echo PWD:$(pwd)
- echo $JAVA_HOME
echo "--- CLEAN & COMPILE ---"
rm -rf target
- mkdir target
- mkdir target/classes
- mkdir target/test-classes
+ mkdir -p target/test-classes
- $JAVAC -d target/test-classes -cp "mods/*":"libs/*" -p mods $(find . -name '*.java')
+ $JAVAC\
+ -d target/test-classes/\
+ -cp "mods/*":"libs/*"
+ -p mods
+ $(find . -name '*.java')
echo "---- RUN ----"
- echo PWD:$(pwd)
-
$JAVA\
-cp target/test-classes:"mods/*":"libs/*":src/test/resources\
- org.xyz.memory.CheckJava9plus
+ org.xyz.memory.RunMain
```
### 3) Using off-heap memory in a non-modularized Java 9+ application
@@ -116,40 +116,38 @@ which runs as an UNNAMED module in a non-JPMS (non-modularized) application.
The following launch script compiles and runs a non-modularized Java 9 application:
```shell
+ JH=$JAVA9_HOME
+ JAVAC=$JH/bin/javac
+ JAVA=$JH/bin/java
+ JAR=$JH/bin/jar
- export JAVA_HOME=$JAVA9_HOME
- export JAVAC=$JAVA_HOME/bin/javac
- export JAR=$JAVA_HOME/bin/jar
- export JAVA=$JAVA_HOME/bin/java
patha=nomvn-nomod-jdk9
cd $patha
- echo PWD:$(pwd)
- echo $JAVA_HOME
echo "--- CLEAN & COMPILE ---"
rm -rf target
- mkdir target
- mkdir target/classes
- mkdir target/test-classes
+ mkdir -p target/test-classes
- $JAVAC -d target/test-classes -cp "mods/*":"libs/*" -p mods $(find . -name '*.java')
+ $JAVAC\
+ -d target/test-classes/\
+ -cp "mods/*":"libs/*"
+ -p mods
+ $(find . -name '*.java')
echo "---- RUN ----"
- echo PWD:$(pwd)
-
$JAVA\
--add-exports java.base/jdk.internal.misc=ALL-UNNAMED\
--add-exports java.base/jdk.internal.ref=ALL-UNNAMED\
--add-opens java.base/java.nio=ALL-UNNAMED\
--add-opens java.base/sun.nio.ch=ALL-UNNAMED\
-cp target/test-classes:"mods/*":"libs/*":src/test/resources\
- org.xyz.memory.CheckJava9plus
+ org.xyz.memory.RunMain
```
where the traditional classpath (`-cp`) argument contains all modules, libraries and resources.
-Note: `mods` is a local directory containing external modules, and `libs` is a localy directory for external library
+Note: `mods` is a local directory containing external modules, and `libs` is a local directory for external library
dependencies. No distinction is made between modules and libraries since they are both appended to the classpath.
### 4) Using off-heap memory in a modularized Java 9+ application
@@ -171,10 +169,11 @@ These arguments expose encapsulated packages in the `java.base` package to the `
The following launch script compiles and runs a modularized Java 9 application:
```shell
- export JAVA_HOME=$JAVA9_HOME
- export JAVAC=$JAVA_HOME/bin/javac
- export JAR=$JAVA_HOME/bin/jar
- export JAVA=$JAVA_HOME/bin/java
+ JH=$JAVA9_HOME
+ JAVAC=$JH/bin/javac
+ JAVA=$JH/bin/java
+ JAR=$JH/bin/jar
+
patha=nomvn-mod-jdk9
cd $patha
@@ -183,11 +182,13 @@ The following launch script compiles and runs a modularized Java 9 application:
echo "--- CLEAN & COMPILE ---"
rm -rf target
- mkdir target
- mkdir target/classes
- mkdir target/test-classes
+ mkdir -p target/test-classes
- $JAVAC -d target/test-classes -cp "libs/*" -p mods $(find . -name '*.java')
+ $JAVAC\
+ -d target/test-classes/\
+ -cp "mods/*":"libs/*"
+ -p mods
+ $(find . -name '*.java')
echo "---- RUN ----"
echo PWD:$(pwd)
@@ -197,7 +198,7 @@ The following launch script compiles and runs a modularized Java 9 application:
--add-opens java.base/sun.nio.ch=org.apache.datasketches.memory\
-cp "/libs/*":src/test/resources\
-p target/test-classes:mods\
- -m org.xyz.memory/org.xyz.memory.CheckJava9plus
+ -m org.xyz.memory/org.xyz.memory.RunMain
```
where the traditional classpath (`-cp`) argument contains libraries and resources, and the module-path argument (`-p`)
references all external modules and compiled classes for the current user application, which is itself a module.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datasketches.apache.org
For additional commands, e-mail: commits-help@datasketches.apache.org