deptool
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).
deptool
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
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 bin/deptool
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.
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.
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.
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 deptool/bin
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 resolve
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.
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
- seeresolve-jmix
command documentation. The option is not required for the resolve-lib command.--jmix-plugin-version
- seeresolve-jmix
command documentation.--gradle-user-home
- seeresolve-jmix
command documentation.--resolver-project
- seeresolve-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 --jmix-version
option is defined then Jmix BOM will be used during dependency resolution. Jmix BOM is not used by default.
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 deptool/bin
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 resolve-npm
command will override the result of the previous one.
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 deptool
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. Seeresolve-jmix
command documentation.--report-file
- a path to a file which will contain a list of all exported artifacts.
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 deptool
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
.
The command uploads artifacts exported by the export
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.
The command uploads artifacts exported by the export-npm
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.
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 settings.gradle
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.
allowInsecureProtocol true
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 mavenCentral()
instruction from the repositories
section of the build.gradle
file.
Copy previously saved package-lock.json file at hte root of your project.
To use custom npm registry create file .npmrc
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
Download Sonatype Nexus OSS.
Unzip the archive.
Go to the bin
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 maven2 (hosted)
repository type.
Fill the Name field (e.g. jmix
) and select the Version policy: Mixed
.
Create NPM repository the same way - use npm (hosted)
repository type and fill the Name (e.g. jmix-npm).
The deptool
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 JmixDependenciesPlugin
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>
The deptool
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 JmixNpmDependenciesPlugin
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
To build the distribution locally run the following command to build the deptool
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 build/distributions/deplool-<version>.zip
archive.
After extracting the archive use bin/deptool.sh
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)