Best practice to set up a module custom code project

Development
1

Hi Yan,

What is the best way to setup a custom code project for a module?

I have managed to convert my existing project to a maven project. It references the vassal project in the build path, so it picks up any references to vassal classes, but is there a better ‘maven’ way to do this?

My code also uses some of the same libraries that vassal installs and I have got my code to compile by copying the appropriate dependencies from the vassal/pom.xml to my new pom.xml, but is there a better way to do that by somehow referencing the vassal dependencies?

Thanks,
Brent.

2

Yes I too am looking for the same best practice. Little groups of Packages I need to compile; they need to reference some version of Vassal on the buildpath - but note that in the future they really ought to reference a “stable” version, so for example some label like 3.3.2 when that comes out, as opposed to breaking whenever master changes – because these will be associated with a module that is built for some stable version of Vassal. And then of course it would be nice to have the “lib” and “noredist” kinds of things stay right rather than manually keeping them up to date for the custom class packages.

3

Very good question.

The best would be if we could add Vassal as a maven dependency, then maven would take care of all the other dependencies. It should be possible already, but only under certain conditions:

  • the Vassal jar is installed in the local maven repository, a “mvn install” does this
  • alternatively both Vassal and the module need to be open at the same time in the same Eclipse workspace and the Eclipse option “resolve workspace artifacts” needs to be enabled, it is enabled by default I think but better double-check, and this is not a very maven-y way since it depends on Eclipse

But at the moment this is only a crude workaround for what maven is really able to do, and only works on the computers of those that have maven installed and mess around with the Vassal code. For it to become a really neat feature for module developers, we still need to do the following:

  • decide a proper naming scheme for the groupId and artifactId, right now it’s more or less a placeholder which I have not given much thought, a proper one would be something like “org.vassalengine:vassal-app” (groupId:artifactId)
  • switch to the version number in maven as the leading version number of Vassal, at the moment the maven version number is parallel to the “real” version number that is set manually and/or by using this ‘git describe --tags’ command
  • split the one single-module project into a multi-module project, have the actual Vassal jar as one of the sub-modules, since this is the one that the modules will need, the rest has to do with building the release package and is irrelevant for the modules
  • set maven to build a source and/or a javadoc package in addition to the plain jar
  • start uploading our releases (the jar+src+javadoc, minus the rest) to mavencentral
  • at this point module designers will be able to simply add a maven dependency to their project, just like the dependencies that we have in our pom.xml, their maven will download the Vassal jar and all transitive dependencies, they IDEs will resolve the javadoc and the sourcecode if they want to jump into the Vassal code straight from their IDE, just like we can jump into the source code of our dependencies now
  • once we have this, we can setup a template/skeleton project and hand it out to module designers, where the pom.xml will already contain the main fields and run out of the box, with comments describing what fields they need to change, perhaps 1-2 example classes

I am working on this as I am writing this, I already converted it to a multi-module project and the jar that is needed for modules is singled out in it’s own maven artifact.

I would like to hear your feedback on some of these bullet points, mainly the switch to the maven version number, going “full opensource” by publishing the artifacts on mavencentral (never done this before but it shouldn’t be too complicated, here is an official guide maven.apache.org/repository/guid … pload.html), and what naming scheme would be appropriate, my suggestion is:

  • group id: “org.vassalengine”
  • artifact id: “vassal-app”

Reason for “vassal-app” is, if (big BIG if, I know :smiley:) we ever manage to split the application into something approaching MVC, we could keep “vassal-app” for the overall thing, and make new ones named “vassal-core” or “vassal-api” or something, then tell the module designers that they can switch to “vassal-core” in new versions of their modules.

Alternatively, we can split it in another way: split up the API that modules can use from the API that they can not / should not use, e.g. it makes no sense for modules to use/extend/overwrite classes like ModuleManager, Player and Editor, these could stay in “vassal-app” and the classes that modules can use as their API could go into “vassal-core”.

But this is very longterm, right now let’s decide whether we want to publish the artifacts on mavencentral, make up a nice naming scheme and make a neat skeleton module for module designers.

4

This approach makes a lot of sense.

There has always been a very steep entry cost for developers who just want to create a couple of basic custom classes.

On another note, lowering the entry cost is also going to open the floodgates for even more bug reports coming in as custom code fails. Is there some better way we can handle the bug reports being created from modules that have custom classes included? To at least make them easy to filter out and identify the generating module name?

5

If the previous post was too much, here is a minimal setup for a module:

Install Vassal jar into local maven repo (maven lifecycle quick reference):

cd /path/to/vassalcode
mvn install

Note how the .jar gets installed (copied) at the end of the build log:

[INFO] Installing /home/zorro/dev/vassal/target/lib/Vengine.jar to /home/zorro/.m2/repository/org/vassal/vassalengine/3.3.2-SNAPSHOT/vassalengine-3.3.2-SNAPSHOT.jar

Module project’s pom.xml:

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>org.example</groupId>
  <artifactId>testmodule</artifactId>
  <version>1.0-SNAPSHOT</version>

  <name>testmodule</name>

  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.source>11</maven.compiler.source>
    <maven.compiler.target>11</maven.compiler.target>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.vassal</groupId>
      <artifactId>vassalengine</artifactId>
      <version>3.3.2-SNAPSHOT</version>
    </dependency>
  </dependencies>

</project>

Module class in src/main/java/org.example:

package org.example;

import VASSAL.counters.Stack;

public class ExtendedStack extends Stack {

}
6

Thus spake Brent Easton:

On another note, lowering the entry cost is also going to open the
floodgates for even more bug reports coming in as custom code fails. Is
there some better way we can handle the bug reports being created from
modules that have custom classes included? To at least make them easy
to filter out and identify the generating module name?

I have thought about this before and have never come up with anything
which would work correctly.

You can’t reject stack traces on the basis of an exception occurring in
custom code, becuase a bug in our code can cause an exception in custom
code. You can’t accept stack traces on the basis of an exception occuring
in our code because custom code can causea an exception in our code.

–
J.

7

Is there no way we can get the modulename included somewhere in the bug report that is searchable? That would help speed up triage at least and let module maintainers find all reports relating to their module.