From f4e04748b51b12a2f1eeb6ad9e0cdde20c8d0463 Mon Sep 17 00:00:00 2001 From: Pranav Garg Date: Wed, 6 Jul 2022 11:04:37 +0530 Subject: [PATCH 1/5] Adding documentation about creation of uber-JARs Signed-off-by: Pranav Garg --- DEVELOPER_GUIDE.md | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md index 70abfda767353..da1ed5cb815f1 100644 --- a/DEVELOPER_GUIDE.md +++ b/DEVELOPER_GUIDE.md @@ -4,7 +4,8 @@ - [Install Prerequisites](#install-prerequisites) - [JDK 11](#jdk-11) - [JDK 14](#jdk-14) - - [Runtime JDK](#runtime-jdk) + - [JDK 17](#jdk-17) + - [Custom Runtime JDK](#custom-runtime-jdk) - [Windows](#windows) - [Docker](#docker) - [Build](#build) @@ -12,6 +13,7 @@ - [Run OpenSearch](#run-opensearch) - [Use an Editor](#use-an-editor) - [IntelliJ IDEA](#intellij-idea) + - [Remote development using JetBrains Gateway](#remote-development-using-jetbrains-gateway) - [Visual Studio Code](#visual-studio-code) - [Eclipse](#eclipse) - [Project Layout](#project-layout) @@ -49,7 +51,8 @@ - [Submitting Changes](#submitting-changes) - [Backports](#backports) - [LineLint](#linelint) - - [Lucene Snapshots](#lucene-snapshots) +- [Lucene Snapshots](#lucene-snapshots) +- [Creating uber-JAR/fat-JAR of a module](#creating-uber-jarfat-jar-of-a-module) # Developer Guide @@ -494,3 +497,16 @@ Pass a list of files or directories to limit your search. The Github workflow in [lucene-snapshots.yml](.github/workflows/lucene-snapshots.yml) is a Github worfklow executable by maintainers to build a top-down snapshot build of lucene. These snapshots are available to test compatibility with upcoming changes to Lucene by updating the version at [version.properties](buildsrc/version.properties) with the `version-snapshot-sha` version. Example: `lucene = 10.0.0-snapshot-2e941fc`. + +# Creating uber-JAR/fat-JAR of a module +An uber-JAR is the JAR, which contains classes from all the libraries, on which your project depends and, of course, the classes of current project. + +There might be cases where the developer would like to add some custom logic to the code of a module (like the rest client) and generate anuber-JAR that can be directly used by the dependency management tool. + +To do so you will be using [Gradle Shadow plugin](https://imperceptiblethoughts.com/shadow/). +Go to the `build.gradle` file of the module for which you want to create the uber-JAR. +Add the shadow plugin: +``` +apply plugin: 'com.github.johnrengelman.shadow' +``` + From 10f4309b977f5a4f5baa213213d849425e3f844b Mon Sep 17 00:00:00 2001 From: Pranav Garg Date: Wed, 6 Jul 2022 13:04:46 +0530 Subject: [PATCH 2/5] Fixing linelint error Signed-off-by: Pranav Garg --- DEVELOPER_GUIDE.md | 1 - 1 file changed, 1 deletion(-) diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md index da1ed5cb815f1..f89202228f76c 100644 --- a/DEVELOPER_GUIDE.md +++ b/DEVELOPER_GUIDE.md @@ -509,4 +509,3 @@ Add the shadow plugin: ``` apply plugin: 'com.github.johnrengelman.shadow' ``` - From ea0e54895c85004ffd0863cbac4a9f12891cfc1f Mon Sep 17 00:00:00 2001 From: Pranav Garg Date: Fri, 15 Jul 2022 11:58:08 +0530 Subject: [PATCH 3/5] Comprehensive changes Signed-off-by: Pranav Garg --- DEVELOPER_GUIDE.md | 36 +++++++++++++++++++++++------------- 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md index f89202228f76c..7049f23ef20c7 100644 --- a/DEVELOPER_GUIDE.md +++ b/DEVELOPER_GUIDE.md @@ -37,6 +37,7 @@ - [testImplementation](#testimplementation) - [Gradle Plugins](#gradle-plugins) - [Distribution Download Plugin](#distribution-download-plugin) + - [Creating fat-JAR of a module](#creating-fat-jar-of-a-module) - [Misc](#misc) - [git-secrets](#git-secrets) - [Installation](#installation) @@ -52,7 +53,6 @@ - [Backports](#backports) - [LineLint](#linelint) - [Lucene Snapshots](#lucene-snapshots) -- [Creating uber-JAR/fat-JAR of a module](#creating-uber-jarfat-jar-of-a-module) # Developer Guide @@ -377,6 +377,28 @@ The Distribution Download plugin downloads the latest version of OpenSearch by d ./gradlew integTest -PcustomDistributionUrl="https://ci.opensearch.org/ci/dbc/bundle-build/1.2.0/1127/linux/x64/dist/opensearch-1.2.0-linux-x64.tar.gz" ``` +### Creating fat-JAR of a module + +A fat-JAR (or an uber-JAR ) is the JAR, which contains classes from all the libraries, on which your project depends and, of course, the classes of current project. + +There might be cases where the developer would like to add some custom logic to the code of a module (or multiple modules) and generate a fat-JAR that can be directly used by the dependency management tool. For example in [#3665](https://github.com/opensearch-project/OpenSearch/pull/3665) the developer wanted to provide a tentative patch as a fat-JAR to a consumer for changes made in the high level rest client. + +To do so you will be using [Gradle Shadow plugin](https://imperceptiblethoughts.com/shadow/). +Go to the `build.gradle` file of the module for which you want to create the fat-JAR. + +Add the shadow plugin: +``` +apply plugin: 'com.github.johnrengelman.shadow' +``` +After applying the plugin you should see a new gradle command `shadowJar`. Run the command using: +``` +../../gradlew shadowJar +``` +Note: `gradlew` is at the root of OpenSearch project directory. You will have to change the path according to the module you are trying to build the shadowJar for. + +This will generate a fat-JAR in the `build/distributions` folder of the module. The default name of the fat-JAR will be `opensearch-[MODULE NAME]-[VERSION].jar`. You can inspect that it contains all the requirements using a decompiler. + +You can further customize your fat-JAR by customising the plugin, details for this can be found in the Shadow plugin [documentation](https://imperceptiblethoughts.com/shadow/). ## Misc @@ -497,15 +519,3 @@ Pass a list of files or directories to limit your search. The Github workflow in [lucene-snapshots.yml](.github/workflows/lucene-snapshots.yml) is a Github worfklow executable by maintainers to build a top-down snapshot build of lucene. These snapshots are available to test compatibility with upcoming changes to Lucene by updating the version at [version.properties](buildsrc/version.properties) with the `version-snapshot-sha` version. Example: `lucene = 10.0.0-snapshot-2e941fc`. - -# Creating uber-JAR/fat-JAR of a module -An uber-JAR is the JAR, which contains classes from all the libraries, on which your project depends and, of course, the classes of current project. - -There might be cases where the developer would like to add some custom logic to the code of a module (like the rest client) and generate anuber-JAR that can be directly used by the dependency management tool. - -To do so you will be using [Gradle Shadow plugin](https://imperceptiblethoughts.com/shadow/). -Go to the `build.gradle` file of the module for which you want to create the uber-JAR. -Add the shadow plugin: -``` -apply plugin: 'com.github.johnrengelman.shadow' -``` From 062ad7f3ef6b1aad2eea1ec7e42c80a4b735163d Mon Sep 17 00:00:00 2001 From: Pranav Garg Date: Mon, 1 Aug 2022 11:01:51 +0530 Subject: [PATCH 4/5] Adding PR changes Signed-off-by: Pranav Garg --- DEVELOPER_GUIDE.md | 32 ++++++++++++++++++++++++-------- 1 file changed, 24 insertions(+), 8 deletions(-) diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md index 7049f23ef20c7..8a9a011818773 100644 --- a/DEVELOPER_GUIDE.md +++ b/DEVELOPER_GUIDE.md @@ -379,26 +379,42 @@ The Distribution Download plugin downloads the latest version of OpenSearch by d ### Creating fat-JAR of a module -A fat-JAR (or an uber-JAR ) is the JAR, which contains classes from all the libraries, on which your project depends and, of course, the classes of current project. +A fat-JAR (or an uber-JAR) is the JAR, which contains classes from all the libraries, on which your project depends and, of course, the classes of current project. There might be cases where the developer would like to add some custom logic to the code of a module (or multiple modules) and generate a fat-JAR that can be directly used by the dependency management tool. For example in [#3665](https://github.com/opensearch-project/OpenSearch/pull/3665) the developer wanted to provide a tentative patch as a fat-JAR to a consumer for changes made in the high level rest client. To do so you will be using [Gradle Shadow plugin](https://imperceptiblethoughts.com/shadow/). -Go to the `build.gradle` file of the module for which you want to create the fat-JAR. +Add the following to the `build.gradle` file of the module for which you want to create the fat-JAR, e.g. `client/rest-high-level/build.gradle`: -Add the shadow plugin: ``` apply plugin: 'com.github.johnrengelman.shadow' ``` -After applying the plugin you should see a new gradle command `shadowJar`. Run the command using: + +Run the `shadowJar` command using: ``` -../../gradlew shadowJar +./gradlew :client:rest-high-level:shadowJar ``` -Note: `gradlew` is at the root of OpenSearch project directory. You will have to change the path according to the module you are trying to build the shadowJar for. -This will generate a fat-JAR in the `build/distributions` folder of the module. The default name of the fat-JAR will be `opensearch-[MODULE NAME]-[VERSION].jar`. You can inspect that it contains all the requirements using a decompiler. +This will generate a fat-JAR in the `build/distributions` folder of the module, e.g. .`/client/rest-high-level/build/distributions/opensearch-rest-high-level-client-1.4.0-SNAPSHOT.jar`. + +You can further customize your fat-JAR by customising the plugin, More information about shadow plugin can be found [here](https://imperceptiblethoughts.com/shadow/). + -You can further customize your fat-JAR by customising the plugin, details for this can be found in the Shadow plugin [documentation](https://imperceptiblethoughts.com/shadow/). +To use the generated JAR, install the JAR locally, +e.g. +``` +mvn install:install-file -Dfile=src/main/resources/opensearch-rest-high-level-client-1.4.0-SNAPSHOT.jar -DgroupId=org.opensearch.client -DartifactId=opensearch-rest-high-level-client -Dversion=1.4.0-SNAPSHOT -Dpackaging=jar -DgeneratePom=true +``` + +Refer the installed JAR as any other maven artifact, e.g. + +``` + + org.opensearch.client + opensearch-rest-high-level-client + 1.4.0-SNAPSHOT + +``` ## Misc From 2d2d6479ae74fd587a1386350fc3021df92293a8 Mon Sep 17 00:00:00 2001 From: Pranav Garg Date: Mon, 8 Aug 2022 18:23:44 +0530 Subject: [PATCH 5/5] PR changes Signed-off-by: Pranav Garg --- DEVELOPER_GUIDE.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md index 8a9a011818773..9172d91bccb78 100644 --- a/DEVELOPER_GUIDE.md +++ b/DEVELOPER_GUIDE.md @@ -37,7 +37,7 @@ - [testImplementation](#testimplementation) - [Gradle Plugins](#gradle-plugins) - [Distribution Download Plugin](#distribution-download-plugin) - - [Creating fat-JAR of a module](#creating-fat-jar-of-a-module) + - [Creating fat-JAR of a Module](#creating-fat-jar-of-a-module) - [Misc](#misc) - [git-secrets](#git-secrets) - [Installation](#installation) @@ -377,13 +377,13 @@ The Distribution Download plugin downloads the latest version of OpenSearch by d ./gradlew integTest -PcustomDistributionUrl="https://ci.opensearch.org/ci/dbc/bundle-build/1.2.0/1127/linux/x64/dist/opensearch-1.2.0-linux-x64.tar.gz" ``` -### Creating fat-JAR of a module +### Creating fat-JAR of a Module A fat-JAR (or an uber-JAR) is the JAR, which contains classes from all the libraries, on which your project depends and, of course, the classes of current project. -There might be cases where the developer would like to add some custom logic to the code of a module (or multiple modules) and generate a fat-JAR that can be directly used by the dependency management tool. For example in [#3665](https://github.com/opensearch-project/OpenSearch/pull/3665) the developer wanted to provide a tentative patch as a fat-JAR to a consumer for changes made in the high level rest client. +There might be cases where a developer would like to add some custom logic to the code of a module (or multiple modules) and generate a fat-JAR that can be directly used by the dependency management tool. For example, in [#3665](https://github.com/opensearch-project/OpenSearch/pull/3665) a developer wanted to provide a tentative patch as a fat-JAR to a consumer for changes made in the high level REST client. -To do so you will be using [Gradle Shadow plugin](https://imperceptiblethoughts.com/shadow/). +Use [Gradle Shadow plugin](https://imperceptiblethoughts.com/shadow/). Add the following to the `build.gradle` file of the module for which you want to create the fat-JAR, e.g. `client/rest-high-level/build.gradle`: ``` @@ -399,9 +399,7 @@ This will generate a fat-JAR in the `build/distributions` folder of the module, You can further customize your fat-JAR by customising the plugin, More information about shadow plugin can be found [here](https://imperceptiblethoughts.com/shadow/). - -To use the generated JAR, install the JAR locally, -e.g. +To use the generated JAR, install the JAR locally, e.g. ``` mvn install:install-file -Dfile=src/main/resources/opensearch-rest-high-level-client-1.4.0-SNAPSHOT.jar -DgroupId=org.opensearch.client -DartifactId=opensearch-rest-high-level-client -Dversion=1.4.0-SNAPSHOT -Dpackaging=jar -DgeneratePom=true ```