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/07/26 15:25:47 UTC
[datasketches-memory] branch documentation-updates updated: Minor
updates to documentation
This is an automated email from the ASF dual-hosted git repository.
dcromberge pushed a commit to branch documentation-updates
in repository https://gitbox.apache.org/repos/asf/datasketches-memory.git
The following commit(s) were added to refs/heads/documentation-updates by this push:
new 7c1de65 Minor updates to documentation
7c1de65 is described below
commit 7c1de659f8d21f397aff817eb08070735c6b057f
Author: David Cromberge <dc...@apache.org>
AuthorDate: Mon Jul 26 16:25:33 2021 +0100
Minor updates to documentation
---
README.md | 7 ++-
docs/eclipse.md | 58 +++++++++++++++++--------
docs/img/eclipse-build-path-1.png | Bin 484430 -> 175296 bytes
docs/img/eclipse-build-path-2.png | Bin 457115 -> 164702 bytes
docs/img/eclipse-build-path-3.png | Bin 445207 -> 164750 bytes
docs/img/eclipse-compiler-level.png | Bin 109707 -> 168939 bytes
docs/img/eclipse-java-compiler-arguments-1.png | Bin 465610 -> 202204 bytes
docs/img/eclipse-java-compiler-arguments-2.png | Bin 308523 -> 158323 bytes
docs/img/eclipse-project-structure.png | Bin 162174 -> 222353 bytes
docs/img/intellij-java-compiler-arguments.png | Bin 599758 -> 275110 bytes
docs/img/intellij-project-structure.png | Bin 244742 -> 143458 bytes
docs/intellij.md | 6 ++-
docs/maven-toolchains.md | 6 +--
docs/module-system.md | 8 ++--
14 files changed, 57 insertions(+), 28 deletions(-)
diff --git a/README.md b/README.md
index fe80d9b..734e819 100644
--- a/README.md
+++ b/README.md
@@ -42,7 +42,7 @@ If you are interested in making contributions to this site please see our [Commu
Datasketches memory currently supports Java 8 up to and including Java 13.
-In order to use the library in Java 9 and above, you must provide the following runtime arguments to the JVM:
+In order to allocate off-heap memory using the library in Java 9 and above, you must provide the following runtime arguments to the JVM:
```shell
--add-opens java.base/java.nio=org.apache.datasketches.memory \
@@ -69,6 +69,7 @@ module datasketches.memory.multirelease.test {
}
```
+Note that the `add-opens` arguments are not required for cases where memory is allocated on the heap.
---
@@ -83,6 +84,8 @@ This DataSketches component is pure Java and requires the following JDKs to comp
- JDK9/Hotspot
- JDK11/Hotspot
+Ensure that your local environment has been configured according to the [Maven toolchain configuration](docs/maven-toolchains.md).
+
### Recommended Build Tool
This DataSketches component is structured as a Maven project and Maven is the recommended Build Tool.
@@ -119,7 +122,7 @@ This will create the following Jars:
### Toolchains
This project makes use of Maven toolchains to ensure that the correct Java compiler version is used when compiling source files.
-Ensure that your local environment has been configured according to the [Maven toolchain configuration](docs/maven-toolchains.md).
+See the [Maven toolchain configuration](docs/maven-toolchains.md) for more details.
### Dependencies
diff --git a/docs/eclipse.md b/docs/eclipse.md
index 661841e..e949060 100644
--- a/docs/eclipse.md
+++ b/docs/eclipse.md
@@ -1,12 +1,11 @@
# Eclipse IDE setup
-The use of Maven submodules to build a Multi Release JAR was motivated by its compatibility with popular IDEs.
+The use of Maven submodules to build a Multi Release JAR was motivated by its compatibility with popular IDEs. There are two configuration properties to be aware of when
+configuring your local development environment:
-There are two configuration properties to be aware of when configuring your local development environment:
+### Java compiler versions
-#### Java compiler versions
-
-Settings are usually synchronised with maven toolchain configuration, otherwise the Java version for a maven module
+Settings are usually synchronised with Maven Toolchain configuration, otherwise the Java version for a Maven module
should be set as follows:
| Maven submodule | JDK |
@@ -19,7 +18,7 @@ should be set as follows:
| datasketches-memory-java11 | 11 |
| datasketches-memory-resources | 8 |
-#### Compiler arguments for JPMS
+### Compiler arguments for JPMS
In order to compile Maven modules in Java versions 9 and above, it is necessary to provide the following arguments to the
compiler. These are usually synchronised with the `pom.xml` configuration:
@@ -33,11 +32,11 @@ compiler. These are usually synchronised with the `pom.xml` configuration:
---
-## Eclipse configuration
+## Running Datasketches-Memory in Eclipse
Note that the following configuration was verified using Eclipse Version: 2020-12 (4.18.0)
-#### The eclipse maven plugin
+### The eclipse maven plugin
The [Eclipse Maven plugin](https://maven.apache.org/plugins/maven-eclipse-plugin/) is used to generate Eclipse IDE files. In order to run the eclipse plugin use:
@@ -49,16 +48,31 @@ Please note that this plugin is retired and no longer maintained!
---
-#### Required - Compiler arguments for JPMS
+### Importing the project into eclipse
+
+From the **Package Explorer** View:
+
+- Right click on a blank space in the view
+- Select **Import/Maven/Existing Maven Projects**
+- Select **Next**, and browse to the project directory
+- Click **Open**
+
+---
+
+### Setting compiler arguments for JPMS
Although these should be set automatically, the Eclipse IDE does not currently configure these settings according to the `pom.xml` - see this [Eclipse Bug](https://github.com/eclipse-m2e/m2e-core/issues/129).
Ensure that the required JPMS arguments are set for the compiler (Java 9 only).
-First, open the project properties dialog for the `datasketches-memory-java9` project, and click on `Java Build Path`. Next, open the `Module Dependencies` tab and add an export for `java.base/jdk.internal.ref`:
+- First, right-click on the `datasketches-memory-java9` project, and select **Properties/Java Build Path**.
+- Next, open the **Module Dependencies** tab and select the `java.base` package.
+- Click on **Configured details**, followed by **Expose package**.
+- In the dialog box, enter package: ```jdk.internal.ref```, and `org.apache.datasketches.memory` as the target module.
+- Ensure that the **exports** checkbox is selected.
-Finally, click `Apply and Close`:
+- Finally, click **Apply and Close**:
@@ -66,11 +80,11 @@ Note: These arguments need only be supplied for `datasketches-memory-java9`.
---
-#### Verify - Java compiler settings
+### Setting Java compiler settings
This should be set automatically by the IDE. However, you may ensure that the correct Java compliance level is set for each module by using the Eclipse `Java Compiler` dialog.
-Open the `Java Compiler` dialog, and ensure `Enable project specific settings` is checked:
+- Open the **Java Compiler** dialog, and ensure **Enable project specific settings** is checked:
@@ -82,18 +96,26 @@ You might need to verify this for each module, making sure the correct complianc
---
-#### Verify - JRE library versions
+### Setting JRE library versions
-This should be set automatically by the IDE. However, you may ensure that the correct JRE is used for each module by using the Eclipse `Java Build Path` dialog.
+This should be set automatically by the IDE. However, you may ensure that the correct JRE is used for each module by using the Eclipse **Java Build Path** dialog.
-First, open the project properties dialog for the `datasketches-memory-java9` project, and click on `Java Build Path`. Next, open the `Libraries` tab and select the `JRE System Library` under `Modulepath`. Click `Edit` and ensure that the `Execution Environment` is selected and set to Java 9:
+- First, open the project properties dialog for the `datasketches-memory-java9` project, and click on **Java Build Path**.
+- Next, open the **Libraries** tab and select the **JRE System Library** under **Modulepath**.
+- Click **Edit** and ensure that the **Execution Environment** is selected and set to Java 9:
-Follow a similar process for `datasketches-memory-java11`, and verify that `Execution Environment` is selected and set to Java 11:
+- Follow a similar process for `datasketches-memory-java11`, and verify that **Execution Environment** is selected and set to Java 11:
-Lastly, for all other modules, verify that the `Execution Environment` is selected and set to the Java 8 JRE:
+- Lastly, for all other modules, verify that the **Execution Environment** is selected and set to the Java 8 JRE:
+
+### Running unit tests
+
+- Under the `datasketches-memory-java-8-tests` module, right-click on the `src/test/java` directory.
+- Select **Run-As** / **TestNG Test**
+- It should open a new window and run over 400 tests without error.
diff --git a/docs/img/eclipse-build-path-1.png b/docs/img/eclipse-build-path-1.png
index 18e71d2..17dd822 100644
Binary files a/docs/img/eclipse-build-path-1.png and b/docs/img/eclipse-build-path-1.png differ
diff --git a/docs/img/eclipse-build-path-2.png b/docs/img/eclipse-build-path-2.png
index 9ced94e..f815f86 100644
Binary files a/docs/img/eclipse-build-path-2.png and b/docs/img/eclipse-build-path-2.png differ
diff --git a/docs/img/eclipse-build-path-3.png b/docs/img/eclipse-build-path-3.png
index ab540e4..0a824d3 100644
Binary files a/docs/img/eclipse-build-path-3.png and b/docs/img/eclipse-build-path-3.png differ
diff --git a/docs/img/eclipse-compiler-level.png b/docs/img/eclipse-compiler-level.png
index 9ea4fe0..ff308c4 100644
Binary files a/docs/img/eclipse-compiler-level.png and b/docs/img/eclipse-compiler-level.png differ
diff --git a/docs/img/eclipse-java-compiler-arguments-1.png b/docs/img/eclipse-java-compiler-arguments-1.png
index 9f10d5e..0424fdc 100644
Binary files a/docs/img/eclipse-java-compiler-arguments-1.png and b/docs/img/eclipse-java-compiler-arguments-1.png differ
diff --git a/docs/img/eclipse-java-compiler-arguments-2.png b/docs/img/eclipse-java-compiler-arguments-2.png
index ab6c3a9..58c041c 100644
Binary files a/docs/img/eclipse-java-compiler-arguments-2.png and b/docs/img/eclipse-java-compiler-arguments-2.png differ
diff --git a/docs/img/eclipse-project-structure.png b/docs/img/eclipse-project-structure.png
index 9032cfd..9ed08ca 100644
Binary files a/docs/img/eclipse-project-structure.png and b/docs/img/eclipse-project-structure.png differ
diff --git a/docs/img/intellij-java-compiler-arguments.png b/docs/img/intellij-java-compiler-arguments.png
index 9d5eb88..e45421e 100644
Binary files a/docs/img/intellij-java-compiler-arguments.png and b/docs/img/intellij-java-compiler-arguments.png differ
diff --git a/docs/img/intellij-project-structure.png b/docs/img/intellij-project-structure.png
index de39156..aaa77f3 100644
Binary files a/docs/img/intellij-project-structure.png and b/docs/img/intellij-project-structure.png differ
diff --git a/docs/intellij.md b/docs/intellij.md
index cbedc31..c7425b0 100644
--- a/docs/intellij.md
+++ b/docs/intellij.md
@@ -33,9 +33,11 @@ compiler. These are usually synchronised with the `pom.xml` configuration:
---
+## Running Datasketches-Memory in IntelljJ-IDEA
+
Note that the following configuration was verified using IntelliJ IDEA 2021.1.2 (Community Edition).
-#### Java compiler versions
+### Java compiler versions
Ensure that the correct SDK is used for each module using the IntelliJ project structure dialog:
@@ -43,7 +45,7 @@ Ensure that the correct SDK is used for each module using the IntelliJ project s
---
-#### Compiler arguments for JPMS
+### Compiler arguments for JPMS
Ensure that the required JPMS arguments are set for the compiler (Java 9 only). These should be detected and set automatically based on the `pom.xml` configuration.
diff --git a/docs/maven-toolchains.md b/docs/maven-toolchains.md
index 5fdc460..a9e5148 100644
--- a/docs/maven-toolchains.md
+++ b/docs/maven-toolchains.md
@@ -42,15 +42,15 @@ For example, if you are using [SDKMAN!](https://sdkman.io/), your environment mi
- JAVA11_HOME: `/Users/me/.sdkman/candidates/java/11.0.10.hs-adpt`
#### For MacOS or Linux variants
-Users can discover what JDKs have been loaded into their enviornment by using the following command:
+Users can discover what JDKs have been loaded into their environment by using the following command:
- /usr/libexec/java_home -V
### Eclipse configuration
-If you are an Eclipse user, you may need further configuration for your IDE to use the appropriate JDK for each module - see the [eclipse IDE setup](eclipse.md).
+If you are an Eclipse user, you may need further configuration for your IDE to use the appropriate JDK for each module - see the [Eclipse IDE setup](eclipse.md).
### IntelliJ configuration
-Similarly, if you are an Eclipse user, you may need further configuration for your IDE to use the appropriate JDK for each module - see the [eclipse IDE setup](eclipse.md).
+Similarly, if you are an Eclipse user, you may need further configuration for your IDE to use the appropriate JDK for each module - see the [IntelliJ IDE setup](intellij.md).
diff --git a/docs/module-system.md b/docs/module-system.md
index bdf48d5..e479b75 100644
--- a/docs/module-system.md
+++ b/docs/module-system.md
@@ -72,19 +72,21 @@ to the Maven compiler plugin in the module's pom.xml file:
</compilerArgs>
```
-### Runtime arguments
+### Runtime arguments (off-heap memory only)
-Reflection is used by the datasketches memory library in cases where fields and methods that do not have `public` visibility
+When allocating off-heap memory, reflection is used by the datasketches memory library in cases where fields and methods that do not have `public` visibility
in a class. Reflective access requires additional arguments to be provided by the user at runtime, in order to use the
`datasketches-memory` JPMS module in Java versions 9 and above.
-The following runtime arguments should be provided when using the library:
+The following runtime arguments should be provided when allocating memory off-heap:
```shell
--add-opens java.base/java.nio=org.apache.datasketches.memory \
--add-opens java.base/jdk.internal.misc=org.apache.datasketches.memory \
--add-opens java.base/jdk.internal.ref=org.apache.datasketches.memory
```
+Note that these arguments are not required for cases where memory is allocated on the heap.
+
### JPMS and Java 8
Java 8 does not support module declarations and the JPMS module system.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@datasketches.apache.org
For additional commands, e-mail: commits-help@datasketches.apache.org