Packaging and Use guide for Java To Distributable

This is a guide that explains how to obtain the .jar file and later, how use the Java to Distributable app.

Before starting

There are some requirements (tools and programs) that are needed for the success of this processes, which are:

• Have Maven installed.
• Have Java 11 SE installed and configured.
• Have access to the dpkg, rpm, rpmbuild, snapcraft and snap commands, as well as being on a GNU/Linux operating system.
• Recommended to have the latests version of the Java to Distributable project.

If you already meet this requirements, you are free to continue.

Packaging

This section is all about packaging process. It will provide some insights and guidelines on how to obtain the .jar executable file for the Java To Distributable app.

The steps are rather simple:

1. First, open a command prompt.
2. Now, navigate to the project's root folder.
3. Finally, execute the following command:

user@machine:~$ mvn clean package

After all the process is completed, you should be left with all the produced files on the “target” folder of the project.

This includes the .jar executables of the Java To Distributable app.

Use guide

This section provides a use guide for the Java To Distributable app.

As the previous section, the use of the app is very simple:

1. Open a command prompt.
2. Now, you can use the app as follows:

user@machine:~$ java -jar <path_to_your_desired_jar> COMMAND [ARGS…]

It is recommended that you use the “jar-with-dependencies-and-services” so you can use all the features of the application without problems.

You can see more about the Java To Distributable commands and options in the “Example_Java_To_Distributable_commands.md” file.

Choices.xml file

The choices.xml file is a user provided XML for package info overwrite. Its format is simple. All of its elements are optional, can be in any order, and all hang from the root <choice> element. But there are a few exceptions to the latter, such as the <jarPath>, <dependency>, <category>, and <javaRunArg> elements that hang from the <jarPaths>, <dependencies>, <categories>, and <javaRunArgs> tags respectively.

The tags that can be placed in the choices.xml file are:

• <targetCommandName> represents the name of the command with which the application is executed.
• <name> represents the full name of the application.
• <version> represents the current version of the application.
• <description> represents the description of the application.
• <className> represents the fully qualified main Java class of the application.
• <licence> represents the licence of the application.
• <documentation> represents the homepage URL of the application.
• <maintainer> represents the maintainer of the application.
• <icon> represents the application's icon path.
• <terminal> represents whether or not the application run on a terminal.
• <base> represents the pre-built runtime environment upon which the snap will run.
• <grade> represents whether the snap is considered a stable release or a development version.
• <confinement> represents the degree of confinement applied to the snap.
• <javaDependency> represents the Java package that the application needs to be executed.
• <manPage> represents the man page file path of the application.
• <categories> represents/contains a set of <category>
  • <category> represents a category for the distributable file to be tagged as such.
• <dependencies> represents/contains a set of <dependency>
  • <dependency> represents a package dependency for the distributable file.
• <jarPaths> represents/contains a set of <jarPath>
  • <jarPath> represents the path of a .jar file.
• <javaRunArgs> represents/contains a set of <javaRunArg>
  • <javaRunArg> represents a Java execution argument to run the application with. It must not have the initial hyphen.

Result

The execution of a command produces a distributable file.

Debian package (.deb)

In the case that you chose to generate a .deb distributable file, you can follow this steps to install the application on your Debian distribution:

1. Open a command prompt.
2. You can install the .deb file using the following command in your terminal:

user@machine:~$ sudo dpkg -i <path_to_the_distributable_file>

Note that you must have sudo privileges to execute the previous command.

If its required to install some additional packages, the tool will ask for your permission.

• Once the application is installed, you can use with the following command:

user@machine:~$ <package_name>

Where the package name is the one that is in the first part of the .deb package name, for instance:

seda_1.6.0-SNAPSHOT_all.deb -> <package_name>_<version>_<architecture>.deb

• If you want to uninstall the application, you can simply execute the next command:

user@machine:~$ sudo dpkg -r <package_name>

Snapcraft package (.snap)

In the case that you chose to generate a .snap distributable file, you can follow this steps to install the application on your Linux distribution:

1. Open a command prompt.
2. You can install the application by executing the following command in your terminal:

user@machine:~$ sudo snap install --dangerous <path_to_the_distributable_file>

The "dangerous" flag is necessary because the generated snapcraft package is not signed, so you need to indicate that you know about that fact.

Also, if the generated snapcraft package was created with a confinement other than strict, you should add another flag, for example:

user@machine:~$ sudo snap install --dangerous --devmode <path_to_the_distributable_file>

user@machine:~$ sudo snap install --dangerous --classic <path_to_the_distributable_file>

If the confinement is devmode or classic respectively.

Note that you must have sudo privileges to execute the previous command.

If its required to install some additional packages, the tool will ask for your permission.

• Once the application is installed, you can use with the following command:

user@machine:~$ <package_name>

Where the package name is the one that is in the first part of the .snap package name, for instance:

seda_1.6.0-SNAPSHOT_amd64.snap -> <package_name>_<version>_<architecture>.snap

• If you want to uninstall the application, you can simply execute the following command:

user@machine:~$ sudo snap remove <package_name>

Red Hat Package Manager (.rpm)

In the case that you chose to generate a .rpm distributable file, you can follow this steps to install the application on your Red Hat based distribution:

1. Open a command prompt.
2. Navigate to the root of the output folder that you choose when generating the distributable file.
3. Now, go to rpmbuild/RPMS/noarch, it is where the .rpm file is stored.
4. To install it, execute this command:

user@machine:~$ sudo rpm -i <package_name>

Note that you must have sudo privileges to execute the previous command.

If its required to install some additional packages, the tool will ask for your permission.

• Once the application is installed, you can use with the following command:

user@machine:~$ <package_name>

Where the package name is the one that is in the first part of the .rpm package name, for instance:

seda-1.6.0_SNAPSHOT-1.el7.noarch.rpm -> <package_name>-<version>-<package_version>.<linux_enterprise_version>.<architecture>.rpm

• If you want to uninstall the application, you can simply execute the following command:

user@machine:~$ sudo rpm -e <package_name>