Skip to main content

HowTo: Create a new installable distribution of Openflexo softwares

Openflexo provides tools to package software distribution including:

  • a full set of Openflexo components,
  • required dependencies,
  • an installer (when relevant).

Those tools can be used to build packages for several platforms: MacOS, linux, Windows.

The packaging-tools maven project contains all the tooling that has been capitalized to do the job. It is possible to create either:

  • a pure distribution project that does not contain any additional resource or source file (e.g., look at the projects in /openflexo-packaging/packages),
  • to configure any standard project , containing some source code to be compiled and packaged as a jar, so that it can be distribute as a set of installable packages (one per platform).

Naming scheme of distribution packages​

Installable packages of Openflexo software use the following name scheme: ⟨product.name⟩⟨productSuffix⟩⟨flexo_version⟩ with following extension:

  • Linux: .tar.gz
  • MacOs: .dmg
  • Windows: Setup.exe

Naming elements come from the configuration files:

  • product.name is defined in pom.xml, and might be inherited from parent pom
  • productSuffix is defined in packaging.properties
  • flexo_____version is computed in build___packaging.xml using project.version from pom.xml in order to be compatible with file naming scheme of each platform (e.g. 1.8.0.18-SNAPHSOT will be translated to 1.8.0SNAPSHOT)

Requirements​

Before you start:​

  1. you must know the name and location of the Main class of the java application (e.g. org.openflexo.Flexo for a distribution containing only a set of standard modules)
  2. you must ensure that the mvn package command generates the jar file containing everything that you want to package as a part of the distribution (i.e. class files, property files, resources,... ), except dependencies
  3. if you want to make to distribution available on the download server, you must know the name and path of the directory where your files will be deployed, and ensure that it exists on the download server

Also, to be able to test your configuration, you will probably need to be able to use Maven on the command line. Required versions are:

  • Maven: 3.x
  • JdK: 1.7.xx

Files needed in the project​

All the files listed here must be present in your project before you start the customization of the distribution building process. Samples can be found in the packaging-tests project of the openflexo-production Github repository here.

You can copy any missing file from packaging-tests to your own project before customizing them.

Files that drive the build & packaging process​

Files not specific to a distribution project, that exist in any standard project:

  • pom.xml: the maven project configuration file that also contains information about the standard build process

Files specific to a distribution project:

  • build-packaging.xml: the Ant tooling used to generate software distribution (customization needed for each distribution project)
  • packaging.properties: contains the parameters for the tooling that builds installers, launchers and distribution assembly
  • packaging.xml: contains the parameters for the packaging of the current project, typically it is used to separate jars produced from Openflexo owned source code from external dependencies

Resources needed for the installers & splash screen​

Those directories and files need to be in the src/main/resources of the project. Locations and names of sub-directory may change but must be specified in build-packaging.xml.

  • Icons sub-directory should contain:
    • Icons/IconOpenflexo.icns: MacOS icon, name may change and must be identical in packaging.properties file
    • Icons/Openflexo.ico: Windows & Linux icon, name may change and must be identical in packaging.properties file
    • Icons/SplashPanel.bmp: (72x72 ppp en 128 couleurs indexs 580x300 pixels max)
  • License sub-directory:
    • must contain a rtf file containing License text that will be displayed during installation (Windows installer)
    • naming schema must be <license subdir name>&lt;version Type>\License.rtf, e.g. License/Tests/License.rtf
    • version type is specified in packaging.properties file

Step by step: configure a project to build a software distribution​

1. Ensure your project meets the requirements​

As documented earlier....

2. Add dependency to packaging tools​

Edit the pom.xml file to add a dependency:

		
		<!-- PACKAGING�DEPENDENCIES -->
		<dependency>
			<groupId>org.openflexo</groupId>
			<artifactId>packaging-tools</artifactId>
			<version>${packagingtools.version}</version>
			<scope>compile</scope>
		</dependency>

3. Update properties in pom.xml​

As in the following example, all the following properties need to be set in pom.xml file.

One of the most important is the main.class property as it is needed to build the programs and scripts that will enable users to use the application packaged in the distribution.


	<artifactId>packaging-tests</artifactId> <!-- name of the artifact to be packaged, will be also set in packaging.properties -->

	<name>Packaging :: Build Test Installers</name>
	<description>This project is a way to test packaging tools used to create software distribution for Openflexo.</description>
	<version>0.0.1-SNAPSHOT</version>

	<properties>
		<packagingtools.version>0.4-SNAPSHOT</packagingtools.version>
		<product.name>Your product name</product.name>
		<main.class>org.openflexo.TestApplication</main.class> <!-- main class of the application -->
	</properties>

4. Update parameters in build-packaging.xml​

Depending on your configuration, you might need to tweak some of the parameters in ant config file.

Most of the time, if you did not chose to put Icons and License files in another place than the default one, the only thing you'll have to change is the deployment directory: i.e., the place where the packages for the distribution will be uploaded if they have been successfully built.


	<!-- ./target/../Icons -->
	<property name="icons.dir" value="${resources.dir}/Icons" />
	<!-- ./target/../License -->
	<property name="license.dir" value="${resources.dir}/License" />
	<!-- deployment dir for packagings -->
		<property name="deployment.root.folder" value="~/downloads/somedirectory" />

5. Update packaging.properties​

Note: deprecated parameters are still needed as we need to do some cleaning in tooling to not rely on them anymore

  • versionType=Tests, MacOS specific parameter to name the directory where distribution is build (TODO: should be deprecated)
  • productSuffix=TestApplication, used to name the package (see naming scheme)
  • productDescription=A test application, description used by the installer
  • Copyright=Openflexo, Copyright specified on Installer screen
  • icon_mac_name=IconOpenflexo.icns, icon for MacOS distribution
  • logCount=0
  • keepLogTrace=false
  • default.logging.level=SEVERE, default log-level
  • maven.artifact.id=packaging-tests, maven artifact to be packaged, should be the same as the one specified in pom.xml
  • maven.group.id=org.openflexo, group_id of the maven artifact (jar) to be packaged in the distribution, with all its dependencies
  • wizard.setup.icon=Openflexo.ico, icon of the Windows installer without path
  • launcher.splash=SplashPanel.bmp, name of the image used for SplashPanel of the windows launcher (without path,see requirements)

6. Test and validate​

To test your configuration you can use the following maven target: mvn -Pbuild-installers package

To deploy the built package on the download server: mvn -Pbuild-installers deploy