+++ /dev/null
-# Mograsim Development Environment
-
-<span style="color:grey">_Mograsim Development Documentation Version 0.3 --- 2019-09-27_</span>
-
-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
-
-[Maven Tycho](https://www.eclipse.org/tycho/sitedocs/index.html) is a plugin for
-[Maven](http://maven.apache.org) that allows building Eclipse and OSGi Projects comfortably
-and automatically using Maven.
-
-Useful links:
-- [eclipse.org/tycho](https://www.eclipse.org/tycho/)
-- [wiki.eclipse.org/Category:Tycho](https://wiki.eclipse.org/Category:Tycho)
-- [vogella.com/tutorials/EclipseTycho](https://www.vogella.com/tutorials/EclipseTycho/article.html)
-- [eclipse.org/tycho/sitedocs](https://www.eclipse.org/tycho/sitedocs/index.html)
-- [Tycho pomless sources](https://git.eclipse.org/c/tycho/org.eclipse.tycho.extras.git/tree/tycho-pomless/src/main/java/org/eclipse/tycho/pomless)
- (see *Mapping for naming and other conventions, TychoAggregatorMapping for folders)
-
-## OSGi
-
-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:
-- a **symbolic name** that acts as an identifier, therefore it should be unique and
- must not be changed, otherwise it a large portion of the configuration would break.
- Never change that field after distribution.
-- a **bundle name** and **bundle vendor**; this is only for the users and developers
- and is not constrained in any way. You can change that, but it should be consistent
- across all Mograsim modules. Both can be externalized to
-- a **bundle version** that denotes current the version of the bundle. The `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.
-- a **bundle required execution environment** (abbr. BREE) where the bundle's *minimal*
- JDK version is set. This is also the one eclipse uses and displays as JRE System
- Library in the Eclipse projects.<br> This should be the same as the one the target
- definition used for the build and the same that maven is run with ( -> check the
- Run Configuration)
-
-## Eclipse Plugins
-
-- Short explanation of the different names and terms used in Eclipse Plugin Dev,
- and short introduction to the different mechanisms used.
-
-## Mograsim Structure
-
-The tree of Mograsim projects:
-
-- `plugins` - _This contains all bundles/plugins that provide functionality to Mograsim_
- - **net.mograsim.logic.core** <br> The core logic for pure simulation. This contains
- the most important low-level logic circuits and gates and defines how that
- logic gets simulated. The underlying system for simulation in Mograsim is an
- event based approach (see `Timeline`), using VHDL-like logic defined in `Bit`
- and `BitVector`. More complex ciruits are build out of `Wire`s connecting `Component`s.
- - **net.mograsim.logic.model** <br>The model describes how that core logic is
- displayed and arranged, and allows (de-)serialization to JSON. The core logic
- model gets generated based on this. Every basic net.mograsim.logic.core Component
- has a model equivalent here that represents it in the GUI and persisted state
- (JSON).
- - **net.mograsim.logic.model.editor** <br> This bundle contains a standalone
- SWT-based editor to edit Mograsim JSON-models in a comfortable way. It can
- be used to create a new `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)
- - **net.mograsim.logic.model.am2900** <br> This plugin contains a model for the
- AMD Am2900 Family Microprocessors arranged into a microprogrammable model.
- This can be used in the microprogram editor of the Mograsim plugin and in the
- Mograsim assembler editor (by using a properly set up instruction set). We
- took care that the plugin is independent, meaning that it only provides an
- implementation for an extension point of the net.mograsim.machine plugin and
- no other Mograsim depends on it.<br> This is also the way to go if you want
- to add your own machine definitions to Mograsim and use them there.
- - **net.mograsim.machine** <br> The machine plugin defines an extension point
- that can be extended and implemented in other (your own) plugins to provide
- new machines to Mograsim. In addition to the extension point and the most important
- interfaces, it contains some commonly required or useful components to build/define
- another machine. net.mograsim.logic.model.am2900 for example is such an extension.
- The machine plugin itself scans for all available implementations of the interface
- given by the extension point, and other parts of the Mograsim plugin get access
- to them that way.
- - **net.mograsim.plugin.core** <br> This is - as the name says - the core plugin
- of mograsim. Here lie all the Eclipse Platform specific parts that make Mograsim
- as an Eclipse plugin work. This includes the different editors, view, settings
- and other functional extension to the Eclipse IDE.
- - **net.mograsim.plugin.core.nl_de** <br> This optional plugin provides a German
- localization for Mograsim.
- - **net.mograsim.plugin.branding** <br> This contains elements for branding the
- feature plugin, and additional resources and raw files (original logo and icon
- in SVG and Adobe Illustrator and similar).
- - **net.mograsim.plugin.docs** <br> The Plugin providing the user documentation.
- - **net.mograsim.preferences** <br> A plugin for managing and accessing preferences.
-- `features` - _This contains all Mograsim feature plugins_
- - **net.mograsim.feature** <br> The Mograsim feature plugin, containing all the
- plugins above and combining them into a feature. A feature is a plugin collection
- with additional properties that allows for easy installation by the end user.
- For this purpose, it also contains license information, authors, updatesite
- location (allows eclipse to automatically check if updates are available) and
- more.
-- `products` - _This contains standalone Mograsim product(s)_
- - **net.mograsim.product** <br> A product can be pretty much anything (see Eclipse
- RCP), in our case, this is simply a pre-configured Eclipse package, comparable
- to the packages located at [www.eclipse.org/downloads/packages](https://www.eclipse.org/downloads/packages/).
-- `releng` - _Abbreviation for **Rel**ease **Eng**ineering, contains important configuration_
- - **net.mograsim.configuration** <br> This contains the configuration for the
- Mograsim project and the build in particular. The central Maven configuration
- is located here in a single `pom.xml`, that is the super-parent of all others,
- including the generated ones.
- - **net.mograsim.updatesite** <br> This updatesite project collects features
- in form of an update site that can be accessed by Eclipse to install new features
- or update features. The features are grouped into categories which can come
- with further descriptions. The `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.
- - **net.mograsim.target** <br> The target definition for the build. This is a
- well-defined environment that we expect the plugins to work in/with. That includes
- all plugin dependencies (like all plugins the Eclipse Platform is comprised
- of) and the (minimum) JRE that is expected. Some plugins exclusively for testing
- are included here, too.
-- `tests` - _This contains (integration-like) tests in form of plugin fragments_
- - **net.mograsim.logic.core.tests**
- - **net.mograsim.logic.model.am2900.tests**
- - **net.mograsim.machine.tests**
-- `SWTHelper` - _This contains the [SWTHelper](https://github.com/Haspamelodica/SWTHelper)
- git submodule._
- - `bundles` - _This submodule folder needs to be named like that for Tycho pom-less
- build to work._
- - **SWTInput** - Contains type specific input fields for SWT.
- - **SWTObjectWrappers** - SWT object abstractions to enable zooming and optimizations.
- - <span style="color:grey">_SWTSystemInOutApplication_</span> - _unused_
- - <span style="color:grey">_SWTTiledZoomableCanvas_</span> - _unused_
- - **SWTZoomableCanvas** - The SWT canvas we draw the simulation in.
-
-## Build Mograsim
-
-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)](https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html):
-- The `clean` goal will remove all `target`-folders and other generated files like
- flattened poms and polyglot build artifacts (all are listed in `.gitignore`).
-- The `validate` goal is useful to simply check if the setup itself (Maven Tycho)
- is ok and everything needed is available.
-- The `integration-test` goal will run the test plugins, the `test` goal beforehand
- **will not.**
-- I recommend running `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](#mceps).
-
-## Challenges
-
-Not everything is as simple as it seems at first glance.
-
-### Maven Core Extension Problems <a name="mceps"></a>
-
-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](http://repo.maven.apache.org/maven2/)
-(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:
-
-```xml
-<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
-
-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](https://github.com/Haspamelodica/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 incompatibility
-
-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).
projects / Mograsim.git / blobdiff