We converted the project into a Maven project. This has the following consequences:
- the structure of the source code changed, it now follows the standard structure for Maven projects, in particular:
- code formerly found in /src was split into code and resources
- the code is now in /src/main/java
- the resources are now in /src/main/resources, these are images, icons, i18n translation files and similar non-code resources needed at runtime
- unit tests previously under /test are now in /src/test/java
- some resources that were only needed for tests used to reside under /src, they were now moved to /src/test/resources
- the package structure and the classes/types are still the exact same that they were before, you can use ctrl+shift+t in Eclipse or ctrl+n in IntelliJ to find packages and classes/types, nothing changed here
- dependency management is now completely managed by Maven, the /lib and /lib-nondist subdirectories are gone, Maven will download the required libraries and add them to the build path, they will show up below the project in the package/project explorer of your IDE, just like before
- since Maven knows where to find the sources and Javadocs for (most of the) dependency libraries, it is now possible to open classes/types from these libraries and Maven will get their proper source code instead of decompiled versions, the Javadocs for these libraries should also be available either automatically or after having opened the source code of any one class of a library
- those interested in the configuration of Maven, look at the file pom.xml in the project root
Important: Eclipse IDE users should preferably reimport the project, a guide for this should be available shortly under vassalengine.org/wiki/Eclipse_maven_setup
- one of the side effects of this change is that the need for manual compiler arguments is gone, it is not not necessary to add “–add-exports” anymore in the build path settings of the IDE
Important: it is now not necessary anymore to manually change anything in the projects build settings, Maven will take care of that, any manual settings will be overwritten by Maven, i.e. do not touch the build configuration of the IDE anymore, instead change Maven’s settings in pom.xml and import these settings into the IDE by doing the steps described below
Important: before reporting any build configuration problem, make sure the IDE build configuration is properly set by Maven by doing one of the following:
- in Eclipse do a “alt+f5” or right-click on the project, select Maven → Update Project…
- in IntelliJ in the Maven tab click on button with the two arrows circling each other, or press shift+shift and enter some characters that lead to “Reload all Maven Projects” e.g. “re al ma pr”
Have I forgotten something?
Of course I have:
Currently open PRs most likely have conflicts now and cannot be merged, please update them by merging the current master into your PR branches, like this:
git checkout my-branch-name
git merge master
git push -u origin my-branch-name
Excellent! Thank you so much!
Vassal is building just fine for me with maven, and I believe I have successfully updated all my active PR’s. Whee!
One quick question – I assume there’s no longer anything Eclipse’y that I need to “.gitignore” inside my repository tree?
There shouldn’t be, I added these entries to .gitignore, they should cover Eclipse:
If any Eclipse files other than these ever show up in commits, feel free to propose a PR that adds them to .gitignore.
I still think the Wiki page on git needs more work.
- You should link to some git tutorials.
- You don’t actually explain how to “fork”. I know there is a button in the top-right of the github webpage but that’s not obvious.
- When I click on that I am told I have not set any keys. It’s a very long time since I used git fluently and I’ve probably forgotten how to fix that.
- I think one could build from the repository without intending ever to contribute actual code and saving a few steps that way. Is that something you want to document or discourage?
I’ve done some of 1, explained 2 in detail, nr. 3 no idea would have to find a guide for this myself, and added an info on top of the wiki page linking to the github clone guide for whoever intends to just do nr. 4.
Thank you for the feedback! (Note, this thread is about Maven, this and the previous posts were about the Gid guide on the Vassal wiki)
And it does not stop at switching over to Maven, this is only the beginning.
Next up, a CI pipeline, linux/windows/macosx packages built by maven, nightly builds, developers who break things getting notified automatically and have to fix it on their own instead of Joel having to clean up after them
I guess I am going to help with Vassal C++ after all, help it by relieving our C++ developers of tedious Vassal 3 duties and allowing them to spend time on their new project.
Wow, sounds downright professional! I was surprised how “clunky” Maven was to install on windows (no installer, manual unzipping, manual editing of environment variables like it’s 1993), so the guide could probably use a little note “yes this requires clunky hand-installation” but once it was installed the whole build literally compiled completely the very first time, which is SO worth it.
If there’s going to be active ongoing Vassal 3 maintenance then I’m very happy to hear it, and happy to continue to contribute the occasional fix and/or “UI nicety”.
Yes this is a developer tool, many of us don’t like installers, much easier to unzip things yourself and place them in a directory of choice, and also allows having several versions of maven on the same computer.
There is also a thing called “maven wrapper”, I am thinking of adding it, this will remove the need to install and configure maven. Now that you mention that Maven was a bit tedious to install, I think it makes sense to add this wrapper. It brings .bat-like files that run on all modern OSes and only has a JDK as a requirement, and it handles everything related to a Maven installation automatically.
Cool - meanwhile see other thread that “master” branch suddenly no longer builds today
This should solve this: github.com/vassalengine/vassal/pull/41
What’s the reason for doing a separate Maven install rather than using the inbuilt Eclipse maven plugin? Is that just to get Maven as a command line tool? I got the maven version of the repo compiling fine without an external maven install.
Travis CI question
Is this something we would setup so that it runs when we commit to our individual github forks? Or just setup to test the PR’s when we submit them?
To get Maven as a command line tool, yes. Also stability, today Eclipse has Maven version X builtin, tomorrow version Y, and next week they will switch to a custom Maven version that was extended by them and is broken (has been known to happen).
Although if we use this “Maven Wrapper” that I proposed in a PR we won’t even need a manual Maven installation anymore.
The primary use for this is testing the PRs and the branches of the central repo, the travis-ci.com/github/vassalengine.
There are more use cases e.g. automatic reports of various kinds, automatic build of a nightly release once a day, deployment of releases to a location where users can download them, but that’s for later.
In addition, each contributor is free to use this individually on his own Travis CI account. The project will contain the configuration for travis and the contributors can go to Travis, setup an account there and use it as they wish. This will be beyond our control and support, and will not help us ensure the quality of the central repo in any way.
I for instance have set this up to build the branches of my individual repository, but if/once it runs for the central repo on the central repo’s Travis account, I will deactivate my individual Travis setup, the central Travis build will be the one that counts.
Thanks, that’s what I thought.
Is there are simple way to run all of the tests locally that Travis will do? The Unit tests and maven plugin tests? I don’t want to have to submit a PR just to run tests that I should be running locally.
Yes, on the command line a
mvn clean test
If the Maven Wrapper gets added to master,
mvnw.cmd clean test
In Eclipse you can create a run configuration: right click on the project, “Run As” → “Maven test”. Or right-click on the project, “Run As” → “Maven build…” and enter “clean test” or just “test” as the goals.
In IntelliJ, press ctrl+ctrl and enter “mvn test” or “mvn clean test”.