Java to Distritutable is a command-line application with several commands to generate different distributables (deb, rpm, snap) for Java applications.
This is a guide that explains how to obtain the executable .jar file of the Java to Distributable application and how to use it.
If you have any troubles, please see the Frequent issues section.
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, snap, snapcraft, lxd, gpg, curl, debuild, debsign and dput 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.
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:
- First, open a command prompt.
- Now, navigate to the project's root folder.
- 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.
This section provides a use guide for the Java To Distributable app.
As the previous section, the use of the app is very simple:
- Open a command prompt.
- 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 java-to-distributable-<VERSION>-jar-with-dependencies-and-services.jar 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.
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>, <javaRunArg>, <targetCommandName>, <className> and <numberJavaRunArg> elements that hang from the <jarPaths>, <dependencies>, <categories>, <javaRunArgs>, <targetCommandNames>, <classNames> and <numberJavaRunArgs> tags respectively.
The tags that can be placed in the choices.xml file are:
<mainName>represents the application's main name that is used for package baptism.<targetCommandNames>represents/contains a set of<targetCommandName><targetCommandName>represents the name of one of the commands that the application contains.
<name>represents the full name of the application.<version>represents the current version of the application.<description>represents the description of the application.<classNames>represents/contains a set of<className><className>represents the fully qualified main Java class names for execution.
<licence>represents the licence of the application.<documentation>represents the URL of the application home page.<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.<autocompletion>represents the bash completion script 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.jarfile.
<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.
<numberJavaRunArgs>represents/contains a set of<numberJavaRunArg><numberJavaRunArg>represents numbers that are the quantity of Java execution arguments for each command. Must be accumulative and match with the commands declaration order.
<nexusUsername>represents the Nexus repository username that is allowed to publish RPMs.<nexusRepoUrl>represents the Nexus repository URL were the RPM package will be published to.<releaseChannel>represents the Snapcraft store release channel were the snap package will be published to.<contactName>represents the name of the person responsible for contact.<contactEmail>represents the E-mail of the person responsible for contact.<ubuntuCodeName>represents the first word of the Ubuntu version code name.<key>represents the GPG secret key ID for PPA package signing.<ppaUsername>represents the Launchpad username of the PPA repository owner.<ppaName>represents the name of the PPA repository.
The execution of a command produces a distributable file. The commands available are:
generate-deb-distributablegenerate-snap-distributablegenerate-rpm-distributablegenerate-ppa-distributable
In the case that you chose to generate a .deb distributable file, you can follow these steps to install the application on your Debian distribution:
- Open a command prompt.
- You can install the
.debfile 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>
In the case that you chose to generate a .snap distributable file, you can follow these steps to install the application on your Linux distribution:
-
Open a command prompt.
-
Now, 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>
In the case that you chose to generate a .rpm distributable file, you can follow these steps to install the application on your Red Hat based distribution:
- Open a command prompt.
- Navigate to the root of the output folder that you choose when generating the distributable file.
- Now, go to
rpmbuild/RPMS/noarch, it is where the.rpmfile is stored. - 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>
This are some known issues when generating distributable files.
If the lxd daemon is not running, you can start it with this command:
user@machine:~$ lxd init --auto
The key message that appears for this error is Failed instance creation: no space left on device.
It means that the lxd default storage is too low, you can extend it with this command:
user@machine:~$ lxc storage edit default
This will open a text editor showing a YAML file corresponding configuration where you can manage it. Keep in mind that for any changes to take place, you need to restart the lxd service.
The key message that appears for this error is Cannot run program "rpmbuild", No such file or directory.
It means that you do not have rpm installed, so you must download it and install it with your package manager of
preference.