Jmix Dependencies Tool

Overview

is a command-line utility that helps to prepare custom Nexus repository for developing projects based on Jmix in an isolated environment (without internet access).

provides the following functionality:

• resolve all dependencies for Jmix framework
• resolve dependencies for any custom library
• export resolved dependencies in Maven repository format (for java) or tgz archives (for npm)
• upload exported dependencies into custom Nexus repository

Installation

In order to run the tool Java 11+ must be installed on the machine.

The tool distribution (zip archive) may be downloaded from the Releases page.

After extracting the archive use

or

bin/deptool.bat

files for executing CLI commands.

Distribution directories structure:

deptool
  -  bin (contains CLI executables)
  -  lib (required Java libraries)
  -  resolver (Gradle project used by the tool to resolve dependencies)
  -  npm-resolver (Gradle project used by the tool to resolve npm dependencies)

NOTE: to be able to export npm dependencies you need to install Node.js with npm package manager.

Usage Scenarios

The general usage scenario is the following:

• Resolve all Jmix dependencies for the specific version of the framework and its add-ons. If commercial add-ons are needed, this step requires the Enterprise subscription key. Resolve also additional libraries required for the project, if any. On this step, the resolved Java artifacts will be downloaded to the local Gradle cache. Npm dependencies are resolved as package-lock.json file.
• Export the resolved Java artifacts to the local Maven repository in the portable format.
• Export the resolved npm artifacts as a folder with packages as a tgz archives.
• Upload exported artifacts to a custom Nexus repository.
• Configure the project for using the custom Nexus repository.

Dependencies Resolution

The tool delegates dependencies resolution to a special Gradle project. The flow for getting required dependencies for Jmix framework of specific version or for any other library is the following:

• We pass dependency coordinates or Jmix version number to the
  deptool
  command.
• The
  deptool
  invokes Gradle task of the special resolver project that is shipped with in the tool distribution.
• Gradle downloads dependencies artifacts to its artifacts cache.
• Using the
  deptool
  utility we copy resolved artifacts from Gradle cache into output directory.

Resolve Jmix Dependencies (resolve-jmix)

The tool can resolve all dependencies required for specific Jmix version.

./deptool resolve-jmix --jmix-version 2.1.0

The command resolves and downloads dependencies required for Jmix starters to the Gradle cache.

Command options:

• --jmix-version
  (required) - the Jmix framework version.
• --jmix-plugin-version
  - Jmix plugin version. If not defined the value from the
  --jmix-version
  will be used.
• --resolve-commercial-addons
  - whether to resolve Jmix commercial add-ons. The
  --jmix-license-key
  option must be provided in this case. By default, only open-source modules dependencies are resolved.
• --jmix-license-key
  - your Jmix license key. This option is required if you resolve Jmix commercial add-ons.
• --gradle-user-home
  - gradle user home directory. It is the directory where dependencies will be downloaded to by Gradle. This directory must distinct from the user home of the gradle installed on your machine in order to contain only dependencies required for Jmix. The default value is
  ../gradle-home
  .
• --resolver-project
  - a path to a special gradle project used for dependencies resolution. This project is delivered within the distribution bundle. The default value is
  ../resolver
  .
• --gradle-version
  - version of Gradle installation that will be used.

If you run the command from within the

directory then the only required option is the

--jmix-version

. Other options have default values that work for that case. If you run the command from some other place then you need to configure a location of gradle home and a location of the resolver project.

Keep in mind that multiple invocations of the

command for resolving dependencies for different Jmix versions will accumulate dependencies for all resolved versions in the gradle user home (

../gradle-home

). If you need to export dependencies for specific version only and do not need dependencies of previous resolving operations then you have to clean the

gradle-home

directory.

Resolve a Single Library (resolve-lib)

The command transitively resolves artifacts used by any single dependency.

./deptool resolve-lib javax.validation:validation-api:1.0.0.GA

Command options:

• --jmix-version
  - see
  resolve-jmix
  command documentation. The option is not required for the resolve-lib command.
• --jmix-plugin-version
  - see
  resolve-jmix
  command documentation.
• --gradle-user-home
  - see
  resolve-jmix
  command documentation.
• --resolver-project
  - see
  resolve-jmix
  command documentation.
• --jmix-license-key
  - your Jmix license key. This option is required if you resolve dependencies that use Jmix commercial add-ons.
• --repository
  - additional Maven repository that must be used for dependencies resolution. If no authentication is required then pass repository URL as parameter value. If authentication is required, then pass URL, username and password separated by
  |
  , e.g.
  http://localhost:8081/jmix|admin|admin
• --gradle-version
  - version of Gradle installation that will be used.

If

option is defined then Jmix BOM will be used during dependency resolution. Jmix BOM is not used by default.

Resolve NPM Dependencies (resolve-npm)

The tool can resolve all npm dependencies required for specific Jmix version.

./deptool resolve-npm --jmix-version 2.1.0

The command resolves npm dependencies required for Jmix frontend as package-lock.json.

NOTE: save generated package-lock.json file - it's required for further project configuration

Command options:

• --jmix-version
  (required) - the Jmix framework version.
• --jmix-plugin-version
  - Jmix plugin version. If not defined the value from the
  --jmix-version
  will be used.
• --resolve-commercial-addons
  - whether to resolve Jmix commercial add-ons. The
  --jmix-license-key
  option must be provided in this case. By default, only open-source modules dependencies are resolved.
• --jmix-license-key
  - your Jmix license key. This option is required if you resolve Jmix commercial add-ons.
• --gradle-user-home
  - gradle user home directory. It is the directory where dependencies will be downloaded to by Gradle. This directory must distinct from the user home of the gradle installed on your machine in order to contain only dependencies required for Jmix. The default value is
  ../gradle-home
  .
• --resolver-project
  - a path to a special gradle project used for dependencies resolution. This project is delivered within the distribution bundle. The default value is
  ../npm-resolver
  .
• --gradle-version
  - version of Gradle installation that will be used.

If you run the command from within the

directory then the only required option is the

--jmix-version

. Other options have default values that work for that case. If you run the command from some other place then you need to configure a location of gradle home and a location of the resolver project.

Keep in mind that each invocation of the

command will override the result of the previous one.

Export Resolved Dependencies (export)

The command copies all resolved artifact from the gradle user home directory to the specific target directory. In the target directory files will be organized in a Maven repository format.

./deptool export

By default, if you run the

from the

deptool/bin

directory the command will export artifacts to the

deptool/export

directory. If you want to change the output directory location, use the

--target-dir

option.

Command options:

• --target-dir
  - a directory where dependencies artifacts will be exported to (
  ../export
  by default).
• --gradle-user-home
  - gradle home directory with resolved dependencies. See
  resolve-jmix
  command documentation.
• --report-file
  - a path to a file which will contain a list of all exported artifacts.

Export Resolved NPM Dependencies (export-npm)

The command download all npm packages declared in package-lock.json as a folders with tgz archives. The command copies all resolved artifact from the gradle user home directory to the specific target directory. In the target directory files will be organized in a Maven repository format.

./deptool export-npm

By default, if you run the

from the

deptool/bin

directory the command will export artifacts to the

deptool/export-npm

directory. If you want to change the output directory location, use the

--target-dir

option.

Command options:

• --package-lock-file
  - path to the package-lock.json file with declared dependencies (
  ../npm-resolver/package-lock.json
  by default).
• --target-dir
  - a directory where dependencies artifacts will be exported to (
  ../export-npm
  by default).
• --resolver-project
  - a path to a special gradle project used for dependencies resolution. This project is delivered within the distribution bundle. The default value is
  ../npm-resolver
  .

Upload Exported Dependencies to Nexus Repository (upload)

The command uploads artifacts exported by the

command to the Nexus repository.

./deptool upload --nexus-url http://localhost:8081 \
  --nexus-repository jmix \
  --nexus-username admin \
  --nexus-password adminpass \
  --artifacts-dir ../export

Command options:

• --nexus-url
  (required) - Nexus repository URL.
• --nexus-repository
  (required) - Nexus repository name.
• --nexus-username
  (required) - Nexus user username.
• --nexus-password
  (required) - Nexus user password.
• --artifacts-dir
  (required) - a directory with artifacts to be uploaded to Nexus.

Upload Exported NPM Dependencies to Nexus Repository (upload-npm)

The command uploads artifacts exported by the

command to the Nexus repository.

./deptool upload-npm --nexus-url http://localhost:8081 \
  --nexus-repository jmix-npm \
  --nexus-username admin \
  --nexus-password adminpass \
  --artifacts-dir ../export-npm

Command options:

• --nexus-url
  (required) - Nexus repository URL.
• --nexus-repository
  (required) - Nexus repository name.
• --nexus-username
  (required) - Nexus user username.
• --nexus-password
  (required) - Nexus user password.
• --artifacts-dir
  (required) - a directory with artifacts to be uploaded to Nexus.

Configure Projects For Working with Custom Nexus Repository

While creating a new Jmix project in Jmix Studio, add custom Nexus repository.

After the project is created, add the following lines to the beginning of the

using correct Nexus repository URL:

pluginManagement {
    resolutionStrategy {
        eachPlugin {
            if (requested.id.id == 'io.jmix') {
                useModule("io.jmix.gradle:jmix-gradle-plugin:${requested.version}")
            }
        }
    }

    repositories {
        maven {
            allowInsecureProtocol true
            url 'http://localhost:8081/repository/jmix/'
            credentials {
                username(rootProject.hasProperty('repoUser') ? rootProject['repoUser'] : 'admin')
                password(rootProject.hasProperty('repoPass') ? rootProject['repoPass'] : 'admin')
            }
        }
    }
}

These lines are necessary for resolving Jmix gradle plugin.

instruction is required if your nexus repository uses http protocol. Add this instruction to the maven repository configuration in the

build.gradle

file as well.

Remove the

instruction from the

repositories

section of the

build.gradle

file.

Configure NPM

Copy previously saved package-lock.json file at hte root of your project.

To use custom npm registry create file

at the root of your project and add there the following line:

registry=http://localhost:8081/repository/jmix-npm/

Additional properties (like authentication, etc) can be found in documentation https://docs.npmjs.com/cli/v10/configuring-npm/npmrc

Install Custom Nexus Repository

Download Sonatype Nexus OSS.

Unzip the archive.

Go to the

directory and run Nexus using the command:

On Linux:

./nexus run

On Windows:

nexus.exe /run

Open the URL in the browser: http://localhost:8081

Click the Sign in button and change the default admin password.

Go to the Server administration and configuration section and click the Repositories button.

Click the Create repository button and select the

repository type.

Fill the Name field (e.g.

) and select the Version policy:

Mixed

.

Create NPM repository the same way - use

repository type and fill the Name (e.g. jmix-npm).

Implementation Details

Resolver Project

The

utility resolves dependencies by invocation of gradle tasks in the

resolver

project that is packed into the distribution. This project contains a simple predefined

build.gradle

file. In this file Jmix plugin and Jmix BOM are enabled if corresponding project properties are defined (

-PjmixVersion

and

-PjmixPluginVersion

). The

build.gradle

also applies a special gradle plugin that contains tasks that do the resolution.

The

adds the

resolveDependencies

task. This task is invoked by the

deptool

utility for dependencies resolution.

./gradlew resolveDependencies \
  --dependency javax.validation:validation-api:1.0.0.GA \
  --repository "http://some-external-repo.com:8081/repo|user|password" \
  -PjmixVersion=1.4.2 \
  -PjmixPluginVersion=1.4.2 \
  -PjmixLicenseKey=<your_key>

NPM Resolver Project

The

utility resolves dependencies by invocation of gradle tasks in the

npm-resolver

project that is packed into the distribution. This project contains a simple predefined

build.gradle

file. In this file Jmix plugin and Jmix BOM are enabled if corresponding project properties are defined (

-PjmixVersion

and

-PjmixPluginVersion

). The

build.gradle

also applies a special gradle plugin that contains tasks that do the resolution.

The

adds the

resolveNpmDependencies

task. This task is invoked by the

deptool

utility for dependencies resolution.

./gradlew resolveDependencies \
  --dependency io.jmix.flowui:jmix-flowui \
  --repository "http://some-external-repo.com:8081/repo|user|password" \
  -PjmixVersion=2.1.0 \
  -PjmixPluginVersion=2.1.0 \
  -PjmixLicenseKey=<your_key>

Task configure project using provided data, resolve java dependencies and use Vaadin plugin (vaadinBuildFrontend task) to generate package-lock.json

Building the Distribution

If you build the official release, use Java 11 for this.

To build the distribution locally run the following command to build the

tool distribution:

./gradlew zipDist

or pass the "version" parameter if you want to build the distribution with the specific version:

./gradlew zipDist -Pversion=1.2.3

The task produces the

archive.

After extracting the archive use

or

bin/deptool.bat

files for executing CLI commands.

Distribution directories structure:

deptool
  -  bin (contains CLI executables)
  -  lib (required Java libraries)
  -  resolver (Gradle project used by the tool to resolve dependencies)
  -  npm-resolver (Gradle project used by the tool to resolve npm dependencies)