[ignite-3] branch main updated: IGNITE-17919 Added a developer documentation how to use Gradle build. Fixes #1229

[sk...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

sk0x50 pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/ignite-3.git


The following commit(s) were added to refs/heads/main by this push:
     new 7e92be9359 IGNITE-17919 Added a developer documentation how to use Gradle build. Fixes #1229
7e92be9359 is described below

commit 7e92be93598802c84bf7f97edc14b52efe0c9efa
Author: Aleksandr Pakhomov <ap...@gmail.com>
AuthorDate: Sun Oct 23 12:17:14 2022 +0300

    IGNITE-17919 Added a developer documentation how to use Gradle build. Fixes #1229
    
    Signed-off-by: Slava Koptilin <sl...@gmail.com>
---
 DEVNOTES.md | 256 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 256 insertions(+)

diff --git a/DEVNOTES.md b/DEVNOTES.md
index 62be82e684..3db7075a83 100644
--- a/DEVNOTES.md
+++ b/DEVNOTES.md
@@ -8,6 +8,10 @@
 * [Release candidate verification](#release-candidate-verification)
 ***
 
+# Deprecated Maven build
+
+The maven is depricated and will be removed soon. Gradle is a primary build tool, please follow instructions for that.
+
 ## Prerequisites
  * Java 11 SDK
  * Maven 3.6.0+ (for building)
@@ -207,3 +211,255 @@ High-level modules structure and detailed modules description can be found in th
     ```
     ./ignite node stop myFirstNode
     ```
+
+# Gradle build
+
+## Prerequisites
+* Java 11 SDK
+***
+
+
+## Building Ignite
+Ignite follows standard guidelines for multi-module gradle projects, so it can be easily built using the following command from the project 
+root directory (you can disable the tests when building using `-x test`):
+```shell
+./gradlew clean build -x test
+```
+***
+
+
+## Running sanity checks
+
+Run all checks:
+```shell
+./gradlew clean check
+```
+
+Skip all checks:
+```shell
+./gradlew clean build -x check
+```
+
+### Code style
+Code style is checked with [Gradle Checkstyle Plugin](https://docs.gradle.org/current/userguide/checkstyle_plugin.html).
+* [Checkstyle rules](check-rules/checkstyle-rules.xml)
+* [Checkstyle suppressions](check-rules/checkstyle-suppressions.xml)
+* [Checkstyle rules for javadocs](https://checkstyle.sourceforge.io/config_javadoc.html)
+
+It is enabled by default and is bound to `check` task.
+
+Build project without code style check:
+```shell
+./gradlew clean build -x checkstyleMain -x checkstyleIntegrationTest -x checkstyleTest -x checkstyleTestFixtures
+```
+
+Run code style checks only:
+```shell
+./gradlew checkstyleMain checkstyleIntegrationTest checkstyleTest checkstyleTestFixtures
+```
+
+Code style check results are generated at:
+* `<mudule-dir>/build/reports/checkstyle/`
+
+### Legacy API
+The project is checked for legacy APIs with [Modernizer Gradle Plugin](https://plugins.gradle.org/plugin/com.github.andygoossens.gradle-modernizer-plugin).
+* [Modernizer rules](check-rules/modernizer-rules.xml)
+
+Plugin is enabled by default and is bound to `build` task.
+
+Build project without legacy API check:
+```shell
+./gradlew clean build -x modernizer
+```
+
+Run legacy API checks only:
+```shell
+./gradlew clean modernizer
+```
+
+### PMD
+Static code analyzer is run with [Apache Gradle PMD Plugin](https://docs.gradle.org/current/userguide/pmd_plugin.html).
+* [PMD rules](check-rules/pmd-rules.xml)
+```shell
+./gradlew clean pmdMain pmdTest pmdTestFixtures pmdIntegrationTest
+```
+PMD check result (only if there are any violations) is generated at `<module-name>/build/reports/pmd/`.
+***
+
+
+## Running tests
+Run unit tests only:
+```shell
+./gradlew clean test
+```
+Run unit + integration tests:
+```shell
+./gradlew clean test integrationTest
+```
+Run integration tests only:
+```shell
+./gradlew clean integrationTest
+```
+***
+
+## Checking and generating Javadoc
+ [TBD](https://issues.apache.org/jira/browse/IGNITE-17930)
+***
+
+
+## Setting up IntelliJ Idea project
+You can quickly import Ignite project to your IDE using the root `build.gradle` file. In IntelliJ, choose `Open Project` from the `Quick Start` box or choose `Open...` from the `File` menu and select the root `build.gradle` file.
+
+After opening the project in IntelliJ, double check that the Java SDK is properly configured for the project:
+* Open the `File` menu and select `Project Structure...`
+* In the SDKs section, ensure that JDK 11 is selected (create one if none exist)
+* In the `Project` section, make sure the project language level is set to 11.0 as Ignite makes use of several Java 11
+  language features
+
+Ignite uses machine code generation for some of it's modules. To generate necessary production code, build the project using maven (see [Building Ignite](#building-ignite)).
+
+Configure Idea code style (for IntelliJ Idea >= 2019):
+* File -> Settings -> Editor -> Code Style -> Scheme -> gear (Show Scheme Actions) -> Import Scheme -> IntelliJ IDEA code style XML
+* Choose: ${igniteProject}/idea/intellij-java-google-style.xml
+* Import schema
+* Reboot IntelliJ Idea
+***
+
+## Code structure
+High-level modules structure and detailed modules description can be found in the [modules readme](modules/README.md).
+***
+
+## Packaging
+
+### Zip packaging
+```shell
+./gradlew clean allDistZip -x test -x check
+```
+Uber zip package will be located in `packaging/build/distributions`.
+
+If you wand to build CLI, you can do it with:
+```shell
+./gradlew clean packaging-cli:distZip -x test -x check
+```
+Zip package will be located in `packaging/cli/build/distributions`.
+
+For ignite-runner:
+```shell
+./gradlew clean packaging-db:distZip -x test -x check
+```
+Zip package will be located in `packaging/db/build/distributions`.
+
+You can build zip and run CLI with the following commands:
+```shell
+./gradlew clean packaging-cli:distZip -x test -x check
+cd packaging/cli/build/distributions
+unzip ignite3cli-3.<version>
+cd ignite3cli-3.<version>
+./bin/ignite3
+```
+
+To build a zip file with ignite-runner and run it:
+```shell
+./gradlew clean packaging-db:distZip -x test -x check
+cd packaging/db/build/distributions
+unzip ignite3db-3.<version>
+cd ignite3db-3.<version>
+./bin/ignite3db.sh start
+```
+
+To stop the started node run:
+```shell
+./bin/ignite3db.sh stop
+```
+
+### RPM/DEB packaging
+
+There is also RPM/DEB packaging for Ignite. To build those packages run:
+```shell
+./gradlew clean buildDeb buildRpm -x test -x check
+```
+`ignite3cli` packages are located in `packaging/cli/build/distributions/` and `ignite3db` packages in `packaging/db/build/distributions/`.
+***
+
+To install RPM packages run:
+```shell
+rpm -i ignite3cli_3.<version>.noarch.rpm
+rpm -i ignite3db_3.<version>.noarch.rpm
+```
+
+To install DEB packages run:
+```shell
+dpkg --install ignite3cli_3.<version>_all.deb
+dpkg --install ignite3db_3.<version>_all.deb
+```
+
+Run ignite3db service:
+```shell
+service ignite3db start
+```
+
+Stop ignite3db service:
+```shell
+service ignite3db stop
+```
+
+Use CLI:
+```shell
+ignite3
+```
+
+To uninstall RPM packages run:
+```shell
+rpm -e ignite3cli
+rpm -e ignite3db
+```
+
+To uninstall DEB packages run:
+```shell
+dpkg --remove ignite3cli
+dpkg --remove ignite3db
+```
+
+### Docker image
+
+Gradle build also provides the task that can build docker image. To run this task make sure you have docker installed.
+```shell
+./gradlew clean docker -x test -x check
+```
+
+Run docker container with ignite node:
+```shell
+docker run -it --rm -p 10300:10300 apacheignite/ignite3
+```
+
+
+## Release candidate verification
+1. Build all packages (this will also run unit tests and all checks)
+    ```shell
+    ./gradlew clean docker distZip allDistZip buildRpm buildDeb
+    ```
+1. Go to the `packaging/build/distributions` directory which now contains the packaged CLI tool and Ignite
+    ```shell
+   cd packaging/build/distributions
+   unzip ignite3-3.<version> 
+    ```
+1. Run the tool without parameters (full list of available commands should appear)
+    ```shell
+   cd ignite3cli-3.<version>
+   ./bin/ignite3
+    ```
+1. Start a node
+    ```shell
+   cd ../ignite3db-3.<version>
+   ./bin/ignite3db start
+    ```
+1. Check that the new node is up and running
+    ```shell
+    cd ../ignite3cli-3.<version>
+   ./bin/ignite3 node status
+    ```
+1. Stop the node
+    ```
+    cd ../ignite3db-3.<version>
+   ./bin/ignite3db stop
+    ```