search

cuba-platform / cuba-sdk

Software development kit for CUBA Platform
Apache License 2.0
4 stars 3 forks source link

readme

license

CUBA SDK

Overview

CUBA SDK is a command-line tool that provides an ability to resolve, export and upload to an external repository all dependencies for CUBA and Jmix frameworks, add-ons or any external library with a few simple commands. SDK can be used as an embedded repository. This tool has a built-in Nexus 3 repository.

CUBA SDK is a useful tool if it is required to develop applications with a limited network environment.

Main CUBA SDK features

Installation

Download and Install

Windows

  1. Download and run Windows installer. It will automatically register cuba-sdk in the PATH environment variable.
  2. Open a terminal and run the cuba-sdk command.

Linux

  1. Download and unpack the ZIP archive.
  2. Add location of cuba-sdk/bin directory to the PATH environment variable.
  3. Open a terminal and run the cuba-sdk command.

macOS

  1. Download and install DMG.

  2. Run CUBA SDK from Applications or add /Applications/CUBA SDK.app/Contents/bin to the PATH environment variable and run cuba-sdk in the terminal.

    The app is not signed at the moment, so macOS refuses to run it at the first attempt. You have to open Preferences -> Security and Privacy and click Open Anyway.

Initialization

On the first run, SDK is automatically initialized. You can also do it at any time by running init command.

Commands Reference

Common SDK Commands

Embedded Nexus Repository Commands

Manage Repositories

SDK tool has three repository scopes:

By default the following repositories are configured:

Commands:

Manage Components

Component Commands

List command prints a list of resolved and installed components:

Component coordinates for framework and add-on component commands can be configured as:

Example: push cuba 7.1.3

Resolve command finds and downloads all component dependencies to local Gradle cache. If an add-on depends on other add-ons, then SDK will ask to resolve additional add-ons too. This feature can be disabled with --nra or --not-resolve-addons additional parameters.

Push command uploads resolved components with dependencies to all target repositories. Specific target repository can be configured with --r or --repository additional parameters, for example, push cuba-addon dashboard --r sdk2.

Install command resolves and pushes components. Specific target repository can be configured with --r or --repository additional parameters, for example, install cuba-addon dashboard --r sdk2.

Remove command removes the component with dependencies from the local m2 repository and the embedded Nexus repository. If --local-only flag is provided, then the component will be removed only from the local m2 repository.

Component coordinates for bulk commands can be passed with ','. For example: install --c cuba>>7.2.1,cuba-addon>>dashboard:3.2.1.

Export command exports the component with dependencies as an archive to the sdkproperties[sdk.export.home] directory. If the component is not resolved yet, then SDK will ask to resolve the component.

Import command imports exported SDK archive to the current SDK and upload it to sdk repositories. Specific target repository can be configured with --r or --repository additional parameters, for example, import --r sdk2. If the --no-upload additional parameter is presented, then SDK archive will be imported only to the local m2 repository.

Additional Parameters which can be Applied to Components Commands:

SDK Settings

Configured SDK settings by default are located in the <User.home>/cli/sdk/sdk.properties file. Current configured settings can be printed with properties command.

Properties Reference:

Default SDK target repository which was configured in the setup command

SDK metadata

Local repo settings

Gradle settings

Apply Custom SDK Settings

Following parameters can be applied to all commands:

SDK Plugins

CUBA SDK supports external plugins. Plugins are similar to CUBA CLI plugins. Please check more info about plugin development in CUBA CLI documentation.

CUBA SDK plugins should be located in <user.home>/.haulmont/sdk/plugins/ directory.

To add new component provider it is required to implement com.haulmont.cuba.cli.plugin.sdk.templates.ComponentProvider interface methods and add implementation to ComponentRegistry in InitPluginEvent plugin handler.

Example:

private val componentRegistry: ComponentRegistry by sdkKodein.instance<ComponentRegistry>()

    @Subscribe
    fun onInit(event: InitPluginEvent) {
        componentRegistry.addProviders(YourProvider())

CUBA SDK provides additional events which can be used in external plugins:

Guides

How to Organize Local Repository

As an example let's use the case when we need to download and push to the local repository CUBA and Dashboards add-on artifacts.

  1. Install CUBA SDK according to the Installation section. After installation, you will see in the console:

    start

  2. If you use CUBA SDK for the first time, configure SDK by running the init command. This command creates the necessary initial environment settings, downloads Gradle, and initializes the standard repositories.

    init

    Enter a path to the home directory. Pay attention, that you need to use / instead of \ when entering a path.

    For the already configured SDK, the init command does not clean up current SDK metadata. To check the current SDK status, use the sdk command.

  3. Use the setup-nexus command to install and configure a local Nexus OSS repository. We assume that we have access to the internet. Otherwise, please download correct nexus repository version from https://www.sonatype.com/nexus-repository-oss and unzip the archive to the nexus3 and sonatype-work folders in the SDK home directory. Then run setup-nexus command again.

    nexus

    By default, the repository can be accessed at localhost:8085.

    nexus-ui

    To launch and stop the repository, use start and stop commands.

    The list of the repositories can be obtained by using the repository list command. In the example below, you can see the default repositories and the configured target repository.

    repo-list

    The repository manager supports local and remote repositories which are divided into two groups within SDK:

    • source - repositories used for searching artifacts;
    • target - repositories to which the artifacts will be loaded.

  4. To install CUBA to the local repository run the install cuba command. If the platform version is not specified, SDK provides available platform versions.

    cuba

    This command resolves and pushes components to all target repositories.

  5. To install an add-on, run the install cuba-addon dashboard command and select the version.

    dashboard

    Also, you can use the install command to select the necessary category.

    category

    If you need to install a premium add-on, set the license key by using the set-license command.

    key

  6. To grant access to the installed artifacts for your project, add the line with the repository into build.gradle file of your CUBA project.

buildscript {
    ext.cubaVersion = '7.2.10'
    repositories {
        maven {
            url 'http:/localhost:8085/repository/cuba-sdk'
            credentials {
            ...
            }
        }
        ...
    }
    dependencies {
        classpath "com.haulmont.gradle:cuba-plugin:$cubaVersion"
    }
}

The credentials section contains the username and password fields. Their values must be filled with the repository authentication data provided in the p. #3. By the way, CUBA Plugin detects the embedded repository and provides the necessary information to the CUBA project build.gradle file.

NB: as Jmix projects contain a newer Gradle Wrapper than CUBA projects do (by default), it is necessary to add allowInsecureProtocol(true) line to the local Nexus OSS repository declaration in build.gradle. Thus, the access to the repository artifacts via the HTTP protocol is granted. The other steps for organizing the local repository for work with Jmix projects and addons are the same as for CUBA except of replacing cuba with jmix in CLI commands.

How to Export Artifacts

Exporting artifacts can be useful when you are going to work in an isolated network or a network with weak internet access. Then you can export artifacts to the archive and transfer them to the computer in the isolated network.

  1. Open a console on the computer with the installed CUBA SDK. We assume, that the required artifacts are already installed (see How to Organize Local Repository).

  2. Run the export command. All resolved components will be exported as an archive to the home directory.

    export

In case you need to export only a particular component use commands export cuba-addon/export jmix-addon, export cuba/export jmix or export lib.

  1. Finally, find the archive in the <home>/export directory and transfer it to the required environment.

How to Import Artifacts

We assume that we have an exported archive with the required artifacts. A computer we need to import the archive on is in an isolated network and have no access to the internet. To install CUBA SDK you need to transfer an installation file to the computer.

First, you need to organize a local repository. Follow the instructions in the How to Organize Local Repository.

When CUBA SDK is installed and the local repository is configured run the import command and specify the path to the archive.

import

Build information

How to build, run, and debug CUBA SDK locally (in Intellij IDEA)

Below, ${platform} is referred to as the current Operating System (OS) name (windows, linux, macos for Windows, Linux, and macOS respectively).

The build directory of the CUBA SDK project contains a script file (.bat for Windows or .sh for Linux/macOS under bundle-${platform}/bin). Besides, there are two more directories inside: native-${platform} with a necessary Java runtime image created with the use of jlink and plugins with some .jar files (including archives corresponding to all the project modules). In order to generate a working build, one needs to run the Gradle task .\gradlew bundle (here, Gradle Wrapper is used from the project root location). It is possible (but not mandatory) to add -PtargetOsPlatform=${platform} as a command line parameter. It is worth noticing that this task (among other things) copies the content of one of the two files from etc directory (located in the same cuba-sdk module) to the script file created for a new build. Of course, the choice of the file is determined by the current OS (picked up as the rootProject.targetOsPlatform property value).

Once the task is completed, it is enough to execute cuba-sdk.bat or cuba-sdk.sh in Terminal to run the build. If debugging is required, one must set JLINK_VM_OPTIONS = -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005 and run the standard Remote JVM Debug configuration of Intellij IDEA to connect to the running JVM.