🦡 Vermilingua

Vermilingua is a Maven plugin for building WebObjects applications and frameworks.

It's close to a drop-in alternative to the WOLifecycle Maven Plugin (with some differences listed below), but unlike wolifecycle it's written from scratch instead of being a wrapper around the old WOProject Ant Tasks. This means it performs faster builds and it's easier to improve the plugin and the build process.

vermilingua has been used for years to build dozens of applications and frameworks (including a fork of Wonder) and is under active development.

Usage

Replace the wolifecycle-maven-plugin <plugin> element in your pom.xml with vermilingua-maven-plugin:

<plugin>
  <groupId>is.rebbi</groupId>
  <artifactId>vermilingua-maven-plugin</artifactId>
  <version>1.1.11</version>
  <extensions>true</extensions>
</plugin>

Optional <configuration> parameters

  • woresourcesPath
    Project-relative path to the WebObjects bundle resources folder. Defaults to dir.woresources in build.properties, then src/main/woresources.
  • componentsPath
    Project-relative path to the components folder. Defaults to dir.components in build.properties, then src/main/components.
  • webserverResourcesPath
    Project-relative path to the webserver resources folder. Defaults to dir.webserverResources in build.properties, then src/main/webserver-resources.
  • performSplit
    When set true, vermilingua will generate an additional "WebServerResources" bundle for "split deployments".
  • createArchives
    When set true, vermilingua will generate compressed archives of the build products (application bundle, and "WebServerResources" bundle if created) using tar and gzip.

Differences from wolifecycle-maven-plugin

Vermilingua does not support

  • Building of .war files (servlet deployment).
  • Building of old style .framework bundles. We only build Maven-style JAR frameworks.
  • flattenResources configuration parameter.
  • .patternset files. The build relies entirely on using a standard folder structure.

Other differences

  • flattenComponents is not required. Any folder structure in src/main/components is flattened since WO can't locate components in subfolders when deployed. Two components with the same name in different subfolders fail the build, and hidden files (.DS_Store, .svn etc.) in src/main/components are skipped.
  • The launch script no longer requires or reads the NEXT_ROOT environment variable and thus no longer passes the derived -DWORootDirectory or -DWOLocalRootDirectory parameters to the JVM. Since applications are now self-contained bundles, there's no need for a system-wide WebObjects installation.
  • Default location for WebObjects bundle resources is src/main/woresources instead of src/main/resources (which is now reserved for Java classpath resources As God Intended).
  • When building applications, ${build.finalName} (set in the POM) will only affect the name of the WOA folder. The insides of two WOAs made from the same project, but compiled with different finalNames, will look exactly the same.
  • The launch script no longer provides any specific provisions for running jdb. If you need to run your application using jdb you can use launch.jvm=jdb.
  • jvmOptions includes by default the --add-opens clauses required to run WO applications on modern JDKs.
  • Split webserver-resources archives and compressed artifacts are not generated by default. If you need those, check the performSplit and createArchives configuration parameters.

Simplified bundle structure

Vermilingua builds simpler bundles than wolifecycle. Platform-specific logic and files have been eliminated and the built bundle is simply:

📁 MyApp.woa
  📄 MyApp
  📄 config.txt
  📄 classpath.txt
  📁 Contents
    📄 Info.plist
    📁 WebServerResources
    📁 Frameworks
      📁 SomeFramework.framework
        📁 WebServerResources
    📁 Resources
      📁 Java
        📄 myapp.jar
        📄 ... [other jars/dependencies]

If deploying on Windows, you can use the standard launch script via WSL or Git Bash.

Modifying launch configuration at build- or runtime

config.txt contains the configuration parameters jvm and jvmOptions. By default, they contain the same values wolifecycle used, but can also be set:

  1. In the project's build.properties using launch.jvm=something
  2. At build time using a property: mvn package -Dlaunch.jvm=something
  3. At app launch time using a property: ./MyApp -launch.jvm=something

This is nice when:

  • you need to use a different java installation/version.
  • you need to add JVM arguments, in which case you use launch.jvmOptions.

Building a "Fluffy Bunny" project

While we prefer and encourage use of the standard maven project layout, vermilingua can build "Fluffy Bunny" layout projects with sources in Sources/, Resources/, Components/ and WebServerResources/. To do this, declare the location of your resource directories in build.properties:

dir.woresources=Resources
dir.components=Components
dir.webserverResources=WebServerResources

These are the same keys the application reads to find its resources when it runs from the project folder in development (ERProjectLayout, part of wonder-slim), so declaring them once covers both. Then set Maven's <sourceDirectory> to Sources:

<build>
  <sourceDirectory>Sources</sourceDirectory>
  ...
</build>

The folders can also be set in the plugin configuration, which takes precedence over build.properties:

<build>
  <sourceDirectory>Sources</sourceDirectory>
  <plugins>
    <plugin>
      <groupId>is.rebbi</groupId>
      <artifactId>vermilingua-maven-plugin</artifactId>
      <version>1.1.11</version>
      <extensions>true</extensions>
      <configuration>
        <woresourcesPath>Resources</woresourcesPath>
        <componentsPath>Components</componentsPath>
        <webserverResourcesPath>WebServerResources</webserverResourcesPath>
      </configuration>
    </plugin>
  </plugins>
</build>