Mograsim Development Documentation Version 0.2 — 2019-09-18
A short guide to the Mograsim Maven Tycho configuration and Maven Tycho in general, as well as some information on Eclipse Plugin Development and OSGi.
Maven Tycho is a plugin for Maven that allows building Eclipse and OSGi Projects comfortably and automatically using Maven.
Useful links:
OSGi is a module system for Java (completely unrelated to the Java 9 Jigsaw module system) that allows detailed control over modules, dependencies, versions and more. The file associated with OSGi here is a specific MANIFEST.MF in the META-INF directory of each project.
Roughly, an OSGi bundle has:
qualifier
is replaced during the build process with a timestamp of the format YYYYMMDDhhmmss
.
The version itself can be set using the maven tycho version plugin, which replaces
not only the maven versions, but all (equivalent) versions in the MANIFEST as well.The tree of Mograsim projects:
plugins
- This contains all bundles/plugins that provide functionality to MograsimTimeline
), using VHDL-like logic defined in Bit
and BitVector
. More complex ciruits are build out of Wire
s connecting Component
s.SubmodelComponent
by arranging existing ones to a
new component. Note that editing and simulation are entirely different processes
in Mograsim, the editor cannot simulate and a running simulation cannot be
edited. (At least in the current state)features
- This contains all Mograsim feature pluginsproducts
- This contains standalone Mograsim product(s)releng
- Abbreviation for Release Engineering, contains important configurationpom.xml
, that is the super-parent of all others,
including the generated ones.target/repository/
is the part of the whole
Mograsim project that actually gets deployed. By using Help -> Install New
Software -> Add -> Local, the repository
-folder can be selected and features
can be installed offline, e.g. to test them.tests
- This contains (integration-like) tests in form of plugin fragmentsSWTHelper
- This contains the SWTHelper
git submodule.bundles
- This submodule folder needs to be named like that for Tycho pom-less
build to work.Use the main aggregator pom.xml
next to this markdown file to build mograsim, take
care to use the correct JDK to run it (see Run Configuration).
A short guide to the Maven goals (Maven Lifecycle):
clean
goal will remove all target
-folders and other generated files like
flattened poms and polyglot build artifacts (all are listed in .gitignore
).validate
goal is useful to simply check if the setup itself (Maven Tycho)
is ok and everything needed is available.integration-test
goal will run the test plugins, the test
goal beforehand
will not.clean verify
or verify
, this will do everything up to and
including the testing.Please note that Tycho 1.5.0 is not released yet, and thus requires a workaround. More information can be found under Maven Core Extension Problems.
Not everything is as simple as it seems at first glance.
The Tycho extra tycho-pomless
is a Maven core extension allows for simpler structure
and less redundancy. Maven core extensions must be available at the central maven repository
(or already in the local repository), you cannot specify an alternative remote repository
in .mvn/extensions.xml
. If a core extension cannot be resolved, you will get currently
(Maven 3.6.2) only a warning like
[WARNING] The POM for org.eclipse.tycho.extras:tycho-pomless:jar:1.5.0-SNAPSHOT is missing, no dependency information available
This means that the extension was not found, and it cannot be used, which leads to a failure later on. To get around that, create a dummy pom that only serves the purpose to “request” and resolve the extension:
<project .. bla .. bla ..>
<modelVersion>4.0.0</modelVersion>
<groupId>net.mograsim</groupId>
<artifactId>net.mograsim.tycho-download</artifactId>
<version>1.0.0</version>
<packaging>pom</packaging>
<pluginRepositories>
<!-- currently necessary because we are using a SNAPSHOT build of tycho -->
<pluginRepository>
<id>tycho-snapshots</id>
<url>https://repo.eclipse.org/content/repositories/tycho-snapshots/</url>
<releases>
<enabled>true</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
<updatePolicy>always</updatePolicy>
</snapshots>
</pluginRepository>
</pluginRepositories>
<build>
<extensions>
<extension>
<groupId>org.eclipse.tycho.extras</groupId>
<artifactId>tycho-pomless</artifactId>
<version>1.5.0-SNAPSHOT</version>
</extension>
</extensions>
</build>
</project>
While that this is not the most compact way, it can be run by the developer and build
server equally easy and does not require special CLI knowledge. As developer, you
need to run that only once (in Eclipse: right click on pom.xml -> Run As -> Maven
clean). For continuous integration, you can insert one more line in the YAML (or
equivalent), like in our case - mvn $MAVEN_CLI_OPTS clean
.
Git submodules are a challenge with a tycho build, because the projects that reside in it need to be build, too. But not only that, they need to use the same configuration for the build, which is problematic if you do not have control over them. The solution only exists with Tycho 1.5.0 (currently only as snapshot), where deep folder structures are automatically scanned and poms get gnereated; not every folder requires an aggregator pom. This however requires (at the moment) certain naming conventions (see section on Tycho itself).
In our case, SWTHelper is a git submodule
containing several plain Java Eclipse projects with OSGi configuration (MANIFEST.MF),
which is the reason this works at all. Due to the naming conventions, the submodule
folder is named bundles
.
Maven 3.6.2 is currently incompatible with Tycho <= 1.5.0.
If you encounter
[FATAL] Non-readable POM “somepath”\tests.polyglot.pom.tycho: input contained no data @
or
[FATAL] Non-readable POM “somepath”\bundles\net.mograsim.logic.core.polyglot..META-INF_MANIFEST.MF: input contained no data @
make sure to use Maven 3.6.1 to fix that (this is the default Eclipse embedded Maven at the moment).