+++ /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).
+++ /dev/null
-<html><head>
- <meta charset='utf-8'>
- <meta http-equiv='x-ua-compatible' content='IE=edge'/>
- <meta name="viewport" content="width=device-width,initial-scale=1.0">
- <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css">
- <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js"></script>
- <script>hljs.initHighlightingOnLoad();</script>
-<style media="screen" type="text/css">
-/*! normalize.css v8.0.0 | MIT License | github.com/necolas/normalize.css */html{line-height:1.15;-webkit-text-size-adjust:100%}body{margin:0}h1{font-size:2em;margin:.67em 0}hr{-webkit-box-sizing:content-box;box-sizing:content-box;height:0;overflow:visible}pre{font-family:monospace;font-size:1em}a{background-color:transparent}abbr[title]{border-bottom:none;text-decoration:underline;-webkit-text-decoration:underline dotted;text-decoration:underline dotted}b,strong{font-weight:bolder}code,kbd,samp{font-family:monospace,monospace;font-size:1em}small{font-size:80%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sub{bottom:-.25em}sup{top:-.5em}img{border-style:none}button,input,optgroup,select,textarea{font-family:inherit;font-size:100%;line-height:1.15;margin:0}button,input{overflow:visible}button,select{text-transform:none}[type=button],[type=reset],[type=submit],button{-webkit-appearance:button}[type=button]::-moz-focus-inner,[type=reset]::-moz-focus-inner,[type=submit]::-moz-focus-inner,button::-moz-focus-inner{border-style:none;padding:0}[type=button]:-moz-focusring,[type=reset]:-moz-focusring,[type=submit]:-moz-focusring,button:-moz-focusring{outline:1px dotted ButtonText}fieldset{padding:.35em .75em .625em}legend{-webkit-box-sizing:border-box;box-sizing:border-box;color:inherit;display:table;max-width:100%;padding:0;white-space:normal}progress{vertical-align:baseline}textarea{overflow:auto}[type=checkbox],[type=radio]{-webkit-box-sizing:border-box;box-sizing:border-box;padding:0}[type=number]::-webkit-inner-spin-button,[type=number]::-webkit-outer-spin-button{height:auto}[type=search]{-webkit-appearance:textfield;outline-offset:-2px}[type=search]::-webkit-search-decoration{-webkit-appearance:none}::-webkit-file-upload-button{-webkit-appearance:button;font:inherit}details{display:block}summary{display:list-item}[hidden],template{display:none}body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI","Helvetica Neue",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol";font-size:14px;line-height:1.5;padding-top:10px;padding-bottom:10px;background-color:#fff;padding:30px}body>:first-child{margin-top:0!important}body>:last-child{margin-bottom:0!important}body>h2:first-child{margin-top:0;padding-top:0}body>h1:first-child{margin-top:0;padding-top:0}body>h1:first-child+h2{margin-top:0;padding-top:0}body>h3:first-child{margin-top:0;padding-top:0}body>h4:first-child{margin-top:0;padding-top:0}body>h5:first-child{margin-top:0;padding-top:0}body>h6:first-child{margin-top:0;padding-top:0}a{color:#4183c4}a.absent{color:#c00}a.anchor{display:block;padding-left:30px;margin-left:-30px;cursor:pointer;position:absolute;top:0;left:0;bottom:0}a:first-child h1{margin-top:0;padding-top:0}a:first-child h2{margin-top:0;padding-top:0}a:first-child h3{margin-top:0;padding-top:0}a:first-child h4{margin-top:0;padding-top:0}a:first-child h5{margin-top:0;padding-top:0}a:first-child h6{margin-top:0;padding-top:0}h1,h2,h3,h4,h5,h6{margin:20px 0 10px;padding:0;font-weight:600;cursor:text;position:relative;border-bottom:1px solid #ccc;color:#000}h1 code,h1 tt,h2 code,h2 tt,h3 code,h3 tt,h4 code,h4 tt,h5 code,h5 tt,h6 code,h6 tt{font-size:inherit}h1 p,h2 p,h3 p,h4 p,h5 p,h6 p{margin-top:0}h1:hover a.anchor,h2:hover a.anchor,h3:hover a.anchor,h4:hover a.anchor,h5:hover a.anchor,h6:hover a.anchor{background:url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAA09pVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDUuMy1jMDExIDY2LjE0NTY2MSwgMjAxMi8wMi8wNi0xNDo1NjoyNyAgICAgICAgIj4gPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIgeG1sbnM6eG1wPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvIiB4bWxuczp4bXBNTT0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wL21tLyIgeG1sbnM6c3RSZWY9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9zVHlwZS9SZXNvdXJjZVJlZiMiIHhtcDpDcmVhdG9yVG9vbD0iQWRvYmUgUGhvdG9zaG9wIENTNiAoMTMuMCAyMDEyMDMwNS5tLjQxNSAyMDEyLzAzLzA1OjIxOjAwOjAwKSAgKE1hY2ludG9zaCkiIHhtcE1NOkluc3RhbmNlSUQ9InhtcC5paWQ6OUM2NjlDQjI4ODBGMTFFMTg1ODlEODNERDJBRjUwQTQiIHhtcE1NOkRvY3VtZW50SUQ9InhtcC5kaWQ6OUM2NjlDQjM4ODBGMTFFMTg1ODlEODNERDJBRjUwQTQiPiA8eG1wTU06RGVyaXZlZEZyb20gc3RSZWY6aW5zdGFuY2VJRD0ieG1wLmlpZDo5QzY2OUNCMDg4MEYxMUUxODU4OUQ4M0REMkFGNTBBNCIgc3RSZWY6ZG9jdW1lbnRJRD0ieG1wLmRpZDo5QzY2OUNCMTg4MEYxMUUxODU4OUQ4M0REMkFGNTBBNCIvPiA8L3JkZjpEZXNjcmlwdGlvbj4gPC9yZGY6UkRGPiA8L3g6eG1wbWV0YT4gPD94cGFja2V0IGVuZD0iciI/PsQhXeAAAABfSURBVHjaYvz//z8DJYCRUgMYQAbAMBQIAvEqkBQWXI6sHqwHiwG70TTBxGaiWwjCTGgOUgJiF1J8wMRAIUA34B4Q76HUBelAfJYSA0CuMIEaRP8wGIkGMA54bgQIMACAmkXJi0hKJQAAAABJRU5ErkJggg==) no-repeat 10px center;text-decoration:none}h1{font-size:2em}h2{font-size:24px}h3{font-size:18px}h4{font-size:16px}h5{font-size:14px}h6{font-size:14px;color:#777}p{margin:15px 0}blockquote{margin:15px 0;border-left:4px solid #ddd;padding:0 15px;color:#777}blockquote>:first-child{margin-top:0}blockquote>:last-child{margin-bottom:0}ol,ul{margin:5px 0;padding-left:30px}ol :first-child,ul :first-child{margin-top:0}ol :last-child,ul :last-child{margin-bottom:0}dl{margin:15px 0;padding:0}dl dt{font-size:14px;font-weight:600;font-style:italic;padding:0;margin:15px 0 5px}dl dt:first-child{padding:0}dl dt>:first-child{margin-top:0}dl dt>:last-child{margin-bottom:0}dl dd{margin:0 0 15px;padding:0 15px}dl dd>:first-child{margin-top:0}dl dd>:last-child{margin-bottom:0}li{margin:5px 0}li p.first{display:inline-block}table{margin:15px 0;padding:0}table tr{border-top:1px solid #ccc;background-color:#fff;margin:0;padding:0}table tr:nth-child(2n){background-color:#f8f8f8}table tr th{font-weight:600;border:1px solid #ccc;text-align:left;margin:0;padding:6px 13px}table tr th :first-child{margin-top:0}table tr th :last-child{margin-bottom:0}table tr td{border:1px solid #ccc;text-align:left;margin:0;padding:6px 13px}table tr td :first-child{margin-top:0}table tr td :last-child{margin-bottom:0}pre{margin:15px 0;background-color:#f8f8f8;border:1px solid #ccc;font-size:12px;line-height:18px;overflow:auto;padding:6px 8px;border-radius:3px}pre code{margin:0;padding:0;white-space:pre;border:none;background:0 0;background-color:transparent;border:none}pre tt{background-color:transparent;border:none}hr{background:transparent url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAYAAAAECAYAAACtBE5DAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAAyJpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDUuMC1jMDYwIDYxLjEzNDc3NywgMjAxMC8wMi8xMi0xNzozMjowMCAgICAgICAgIj4gPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIgeG1sbnM6eG1wPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvIiB4bWxuczp4bXBNTT0iaHR0cDovL25zLmFkb2JlLmNvbS94YXAvMS4wL21tLyIgeG1sbnM6c3RSZWY9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9zVHlwZS9SZXNvdXJjZVJlZiMiIHhtcDpDcmVhdG9yVG9vbD0iQWRvYmUgUGhvdG9zaG9wIENTNSBNYWNpbnRvc2giIHhtcE1NOkluc3RhbmNlSUQ9InhtcC5paWQ6OENDRjNBN0E2NTZBMTFFMEI3QjRBODM4NzJDMjlGNDgiIHhtcE1NOkRvY3VtZW50SUQ9InhtcC5kaWQ6OENDRjNBN0I2NTZBMTFFMEI3QjRBODM4NzJDMjlGNDgiPiA8eG1wTU06RGVyaXZlZEZyb20gc3RSZWY6aW5zdGFuY2VJRD0ieG1wLmlpZDo4Q0NGM0E3ODY1NkExMUUwQjdCNEE4Mzg3MkMyOUY0OCIgc3RSZWY6ZG9jdW1lbnRJRD0ieG1wLmRpZDo4Q0NGM0E3OTY1NkExMUUwQjdCNEE4Mzg3MkMyOUY0OCIvPiA8L3JkZjpEZXNjcmlwdGlvbj4gPC9yZGY6UkRGPiA8L3g6eG1wbWV0YT4gPD94cGFja2V0IGVuZD0iciI/PqqezsUAAAAfSURBVHjaYmRABcYwBiM2QSA4y4hNEKYDQxAEAAIMAHNGAzhkPOlYAAAAAElFTkSuQmCC) repeat-x 0 0;border:0 none;color:#ccc;height:3px;padding:0}img{max-width:100%}span.frame{display:block;overflow:hidden}span.frame>span{border:1px solid #ddd;display:block;float:left;overflow:hidden;margin:13px 0 0;padding:7px;width:auto}span.frame span img{display:block;float:left}span.frame span span{clear:both;color:#333;display:block;padding:5px 0 0}span.align-center{display:block;overflow:hidden;clear:both}span.align-center>span{display:block;overflow:hidden;margin:13px auto 0;text-align:center}span.align-center span img{margin:0 auto;text-align:center}span.align-right{display:block;overflow:hidden;clear:both}span.align-right>span{display:block;overflow:hidden;margin:13px 0 0;text-align:right}span.align-right span img{margin:0;text-align:right}span.float-left{display:block;margin-right:13px;overflow:hidden;float:left}span.float-left span{margin:13px 0 0}span.float-right{display:block;margin-left:13px;overflow:hidden;float:right}span.float-right>span{display:block;overflow:hidden;margin:13px auto 0;text-align:right}code,tt{margin:0 2px;padding:0 5px;white-space:nowrap;border:1px solid #eaeaea;background-color:#f8f8f8;border-radius:3px}@media (max-width:400px){body{font-size:12px;margin-left:10px;margin-right:10px;margin-top:10px;margin-bottom:15px}}@media (min-width:401px) and (max-width:600px){body{font-size:13px;margin-left:10px;margin-right:10px;margin-top:10px;margin-bottom:15px}}@media (min-width:601px) and (max-width:900px){body{font-size:14px;margin-left:20px;margin-right:20px;margin-top:20px;margin-bottom:25px}}@media (min-width:901px) and (max-width:1800px){body{font-size:15px;margin-left:50px;margin-right:50px;margin-top:30px;margin-bottom:25px;max-width:800px}}@media (min-width:1801px){body{font-size:16px;margin-left:20%;margin-right:20%;margin-top:30px;margin-bottom:25px;max-width:1000px}}
-</style>
-</head><body>
-<h1>Mograsim Development Environment</h1>
-<p><span style="color:grey"><em>Mograsim Development Documentation Version 0.3 — 2019-09-27</em></span></p>
-<p>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.</p>
-<h2>Maven Tycho</h2>
-<p><a href="https://www.eclipse.org/tycho/sitedocs/index.html">Maven Tycho</a> is a plugin for
-<a href="http://maven.apache.org">Maven</a> that allows building Eclipse and OSGi Projects comfortably
-and automatically using Maven.</p>
-<p>Useful links:</p>
-<ul>
-<li><a href="https://www.eclipse.org/tycho/">eclipse.org/tycho</a></li>
-<li><a href="https://wiki.eclipse.org/Category:Tycho">wiki.eclipse.org/Category:Tycho</a></li>
-<li><a href="https://www.vogella.com/tutorials/EclipseTycho/article.html">vogella.com/tutorials/EclipseTycho</a></li>
-<li><a href="https://www.eclipse.org/tycho/sitedocs/index.html">eclipse.org/tycho/sitedocs</a></li>
-<li><a href="https://git.eclipse.org/c/tycho/org.eclipse.tycho.extras.git/tree/tycho-pomless/src/main/java/org/eclipse/tycho/pomless">Tycho pomless sources</a>
-(see *Mapping for naming and other conventions, TychoAggregatorMapping for folders)</li>
-</ul>
-<h2>OSGi</h2>
-<p>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.</p>
-<p>Roughly, an OSGi bundle has:</p>
-<ul>
-<li>a <strong>symbolic name</strong> 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.</li>
-<li>a <strong>bundle name</strong> and <strong>bundle vendor</strong>; 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</li>
-<li>a <strong>bundle version</strong> that denotes current the version of the bundle. The <code>qualifier</code>
-is replaced during the build process with a timestamp of the format <code>YYYYMMDDhhmmss</code>.
-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.</li>
-<li>a <strong>bundle required execution environment</strong> (abbr. BREE) where the bundle's <em>minimal</em>
-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)</li>
-</ul>
-<h2>Eclipse Plugins</h2>
-<ul>
-<li>Short explanation of the different names and terms used in Eclipse Plugin Dev,
-and short introduction to the different mechanisms used.</li>
-</ul>
-<h2>Mograsim Structure</h2>
-<p>The tree of Mograsim projects:</p>
-<ul>
-<li><code>plugins</code> - <em>This contains all bundles/plugins that provide functionality to Mograsim</em><ul>
-<li><strong>net.mograsim.logic.core</strong> <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 <code>Timeline</code>), using VHDL-like logic defined in <code>Bit</code>
-and <code>BitVector</code>. More complex ciruits are build out of <code>Wire</code>s connecting <code>Component</code>s.</li>
-<li><strong>net.mograsim.logic.model</strong> <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).</li>
-<li><strong>net.mograsim.logic.model.editor</strong> <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 <code>SubmodelComponent</code> 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)</li>
-<li><strong>net.mograsim.logic.model.am2900</strong> <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.</li>
-<li><strong>net.mograsim.machine</strong> <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.</li>
-<li><strong>net.mograsim.plugin.core</strong> <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.</li>
-<li><strong>net.mograsim.plugin.core.nl_de</strong> <br> This optional plugin provides a German
-localization for Mograsim.</li>
-<li><strong>net.mograsim.plugin.branding</strong> <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).</li>
-<li><strong>net.mograsim.plugin.docs</strong> <br> The Plugin providing the user documentation.</li>
-<li><strong>net.mograsim.preferences</strong> <br> A plugin for managing and accessing preferences.</li>
-</ul>
-</li>
-<li><code>features</code> - <em>This contains all Mograsim feature plugins</em><ul>
-<li><strong>net.mograsim.feature</strong> <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.</li>
-</ul>
-</li>
-<li><code>products</code> - <em>This contains standalone Mograsim product(s)</em><ul>
-<li><strong>net.mograsim.product</strong> <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 <a href="https://www.eclipse.org/downloads/packages/">www.eclipse.org/downloads/packages</a>.</li>
-</ul>
-</li>
-<li><code>releng</code> - <em>Abbreviation for <strong>Rel</strong>ease <strong>Eng</strong>ineering, contains important configuration</em><ul>
-<li><strong>net.mograsim.configuration</strong> <br> This contains the configuration for the
-Mograsim project and the build in particular. The central Maven configuration
-is located here in a single <code>pom.xml</code>, that is the super-parent of all others,
-including the generated ones.</li>
-<li><strong>net.mograsim.updatesite</strong> <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 <code>target/repository/</code> is the part of the whole
-Mograsim project that actually gets deployed. By using Help -> Install New
-Software -> Add -> Local, the <code>repository</code>-folder can be selected and features
-can be installed offline, e.g. to test them.</li>
-<li><strong>net.mograsim.target</strong> <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.</li>
-</ul>
-</li>
-<li><code>tests</code> - <em>This contains (integration-like) tests in form of plugin fragments</em><ul>
-<li><strong>net.mograsim.logic.core.tests</strong></li>
-<li><strong>net.mograsim.logic.model.am2900.tests</strong></li>
-<li><strong>net.mograsim.machine.tests</strong></li>
-</ul>
-</li>
-<li><code>SWTHelper</code> - <em>This contains the <a href="https://github.com/Haspamelodica/SWTHelper">SWTHelper</a>
-git submodule.</em><ul>
-<li><code>bundles</code> - <em>This submodule folder needs to be named like that for Tycho pom-less
-build to work.</em><ul>
-<li><strong>SWTInput</strong> - Contains type specific input fields for SWT.</li>
-<li><strong>SWTObjectWrappers</strong> - SWT object abstractions to enable zooming and optimizations.</li>
-<li><span style="color:grey"><em>SWTSystemInOutApplication</em></span> - <em>unused</em></li>
-<li><span style="color:grey"><em>SWTTiledZoomableCanvas</em></span> - <em>unused</em></li>
-<li><strong>SWTZoomableCanvas</strong> - The SWT canvas we draw the simulation in.</li>
-</ul>
-</li>
-</ul>
-</li>
-</ul>
-<h2>Build Mograsim</h2>
-<p>Use the main aggregator <code>pom.xml</code> next to this markdown file to build mograsim, take
-care to use the correct JDK to run it (see Run Configuration).</p>
-<p>A short guide to the <a href="https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html">Maven goals (Maven Lifecycle)</a>:</p>
-<ul>
-<li>The <code>clean</code> goal will remove all <code>target</code>-folders and other generated files like
-flattened poms and polyglot build artifacts (all are listed in <code>.gitignore</code>).</li>
-<li>The <code>validate</code> goal is useful to simply check if the setup itself (Maven Tycho)
-is ok and everything needed is available.</li>
-<li>The <code>integration-test</code> goal will run the test plugins, the <code>test</code> goal beforehand
-<strong>will not.</strong></li>
-<li>I recommend running <code>clean verify</code> or <code>verify</code>, this will do everything up to and
-including the testing.</li>
-</ul>
-<p>Please note that Tycho 1.5.0 is not released yet, and thus requires a workaround.
-More information can be found under <a href="#mceps">Maven Core Extension Problems</a>.</p>
-<h2>Challenges</h2>
-<p>Not everything is as simple as it seems at first glance.</p>
-<h3>Maven Core Extension Problems <a name="mceps"></a></h3>
-<p>The Tycho extra <code>tycho-pomless</code> is a Maven core extension allows for simpler structure
-and less redundancy. Maven core extensions must be available at <a href="http://repo.maven.apache.org/maven2/">the central maven repository</a>
-(or already in the local repository), you cannot specify an alternative remote repository
-in <code>.mvn/extensions.xml</code>. If a core extension cannot be resolved, you will get currently
-(Maven 3.6.2) only a warning like</p>
-<blockquote><p>[WARNING] The POM for org.eclipse.tycho.extras:tycho-pomless:jar:1.5.0-SNAPSHOT is missing, no dependency information available</p>
-</blockquote>
-<p>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:</p>
-<pre><code><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>
-</code></pre>
-<p>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 <code>- mvn $MAVEN_CLI_OPTS clean</code>.</p>
-<h3>Git Submodules</h3>
-<p>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).</p>
-<p>In our case, <a href="https://github.com/Haspamelodica/SWTHelper">SWTHelper</a> 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 <code>bundles</code>.</p>
-<h3>Maven incompatibility</h3>
-<p>Maven 3.6.2 is currently incompatible with Tycho <= 1.5.0.</p>
-<p>If you encounter</p>
-<blockquote><p>[FATAL] Non-readable POM “somepath”\tests.polyglot.pom.tycho: input contained no data @</p>
-</blockquote>
-<p>or</p>
-<blockquote><p>[FATAL] Non-readable POM “somepath”\bundles\net.mograsim.logic.core.polyglot..META-INF_MANIFEST.MF: input contained no data @</p>
-</blockquote>
-<p>make sure to use Maven 3.6.1 to fix that (this is the default Eclipse embedded Maven
-at the moment).</p>
-
-</body></html>
\ No newline at end of file
Mograsim focuses especially on the AMD Am2900 Family microprocessors in a specific
16-bit arrangement used by the Technical University of Munich as an example.
-# Building Mograsim
-
-These are a very basic instructions for building Mograsim from source.
-
-It assumes you know nothing about Eclipse Plug-In development, Maven, or Git.
-
-## Prerequisites
-
-1. [Java 11 JDK](http://jdk.java.net/java-se-ri/11) [(or Oracle Implementation)](https://www.oracle.com/technetwork/java/javase/downloads/index.html)
-2. [Eclipse 2019-03 or later](https://www.eclipse.org/downloads/)
-3. _(optional)_ [Git](https://git-scm.com/downloads)
-
-## Install PDE (Plugin Development Environment)
-
-1. In Eclipse, click on "Help" -> "Install New Software..."
-2. Next to "Work With:", select "The Eclipse Project Updates"
-3. Tick "Eclipse PDE Plug-in Developer Resources" (expand "Eclipse Plugin Development
- Tools" or type "PDE" in the search bar to see it)
-4. Click on "Next >" two times, read and accept the license, and click on "Finish"
-5. Wait for the installation to complete (may take a while). When prompted, restart
- Eclipse.
-
-## Clone the Git repository and import the projects
-
-Can be done via Git or via EGit (Eclipse Git).
+# Getting Started
-### a) via EGit
+See [Getting Started](docs/getting_started.md)
-1. In Eclipse, click on "Window" -> "Show View" -> "Other..."
-2. Select "Git Repositories" (expand "Git" to see it); click on "Open"
-3. In the "Git Repositories" view, click on "Clone a Git repository"
-4. Enter the repository URL ("Host", "Repository path", and "Protocol" should fill
- automatically); click on "Next >"
-5. Select only "master"; click on "Next >"
-6. Enter the directory you want the Mograsim projects to be saved in
-7. Tick "Clone submodules" and "Import all existing Eclipse projects after clone
- finishes"; click on "Finish"
-
-### b) via Git (requires Git to be installed)
-
-1. In a command prompt (Terminal on Linux; git-bash on Windows), execute `git clone
- --recurse-submodules --single-branch -b master <repository URL> <target directory>`
-2. _(optional)_ Import the repository in Eclipse:
- 1. In Eclipse, open the "Git Repositories" view as described in the first two
- steps in **a)**
- 2. In the "Git Repositories" view, click on "Add an existing local Git repository"
- 3. Enter the directory of the repository and tick the repository you see in the
- list below; click on "Add". (If there is another repository ending with "SWTHelper",
- ignore it)
-3. Import the projects into the workspace
- 1. Click on "File" -> "Import..."
- 2. Select "Existing Projects into Workspace" (expand "General" to see it); click
- on "Next >"
- 3. Tick "Select root directory:" and "Search for nested projects"
- 4. Next to "Select root directory:", enter the directory of the repository; click
- on "Finish"
-
-Note: After importing the projects, probably an automatic workspace build will start.
-Wait for it to finish before continuing.
-
-## Do the Maven Tycho workaround:
-
-In the project explorer or package explorer, right-click on "net.mograsim.tycho-download",
-click on "Run As" -> "Maven clean" and wait for it to finish.
-
-## Build the Update Site
-
-1. In the project explorer or package explorer, right-click on "net.mograsim", click
- on "Run As" -> "Maven build..."
-2. Next to "Goals", enter "clean verify"; click on "Run" and wait for it to finish
- (this will take a while)
-3. Select all projects, right-click, and click on "Refresh"
-
-The update site now should be built and is located in net.mograsim.plugin.updatesite/target/repository.
-In there you should see, among other files, a folder named "features", a folder named
-"plugins" containing some jar files, and two jar files called "artifacts.jar" and
-"content.jar".
+# Building Mograsim
-More information about the build, structure and environment can be found in the [MAVEN-TYCHO-README.MD](MAVEN-TYCHO-README.MD).
+See [Building Mograsim](docs/building_mograsim.md)
\ No newline at end of file
--- /dev/null
+# Building Mograsim
+
+These is a very basic instruction set for building Mograsim from source.
+
+It assumes you know nothing about Eclipse Plug-In development, Maven, or Git.
+
+## Prerequisites
+
+- [Java JDK](http://jdk.java.net/) 11 or later (or [Oracle Implementation](https://www.oracle.com/technetwork/java/javase/downloads/index.html))
+- [Eclipse](https://www.eclipse.org/downloads/) 2019-03 or later (TODO: do earlier versions work?)
+- _(optional)_ [Git](https://git-scm.com/downloads)
+
+## Install PDE (Plugin Development Environment)
+
+1. In Eclipse, click on "Help" -> "Install New Software..."
+2. Next to "Work With:", select "The Eclipse Project Updates"
+3. Tick "Eclipse PDE Plug-in Developer Resources" (expand "Eclipse Plugin Development
+ Tools" or type "PDE" in the search bar to see it)
+4. Click on "Next >" two times, read and accept the license, and click on "Finish"
+5. Wait for the installation to complete (may take a while). When prompted, restart
+ Eclipse.
+
+## Clone the Git repository and import the projects
+
+Can be done via Git or via EGit (Eclipse Git).
+
+### a) via EGit
+
+1. In Eclipse, click on "Window" -> "Show View" -> "Other..."
+2. Select "Git Repositories" (expand "Git" to see it); click on "Open"
+3. In the "Git Repositories" view, click on "Clone a Git repository"
+4. Enter the repository URL ("Host", "Repository path", and "Protocol" should fill
+ automatically); click on "Next >"
+5. Select only "master"; click on "Next >"
+6. Enter the directory you want the Mograsim projects to be saved in
+7. Tick "Clone submodules" and "Import all existing Eclipse projects after clone
+ finishes"; click on "Finish"
+
+### b) via Git (requires Git to be installed)
+
+1. In a command prompt (Terminal on Linux; git-bash on Windows), execute `git clone
+ --recurse-submodules --single-branch -b master <repository URL> <target directory>`
+2. _(optional)_ Import the repository in Eclipse:
+ 1. In Eclipse, open the "Git Repositories" view as described in the first two
+ steps in **a)**
+ 2. In the "Git Repositories" view, click on "Add an existing local Git repository"
+ 3. Enter the directory of the repository and tick the repository you see in the
+ list below; click on "Add". (If there is another repository ending with "SWTHelper",
+ ignore it)
+3. Import the projects into the workspace
+ 1. Click on "File" -> "Import..."
+ 2. Select "Existing Projects into Workspace" (expand "General" to see it); click
+ on "Next >"
+ 3. Tick "Select root directory:" and "Search for nested projects"
+ 4. Next to "Select root directory:", enter the directory of the repository; click
+ on "Finish"
+
+Note: After importing the projects, probably an automatic workspace build will start.
+Wait for it to finish before continuing.
+
+## Do the Maven Tycho workaround:
+
+In the project explorer or package explorer, right-click on "net.mograsim.tycho-download",
+click on "Run As" -> "Maven clean" and wait for it to finish.
+
+## Build the Update Site
+
+1. In the project explorer or package explorer, right-click on "net.mograsim", click
+ on "Run As" -> "Maven build..."
+2. Next to "Goals", enter "clean verify"; click on "Run" and wait for it to finish
+ (this will take a while)
+3. Select all projects, right-click, and click on "Refresh"
+
+The update site now should be built and is located in net.mograsim.plugin.updatesite/target/repository.
+In there you should see, among other files, a folder named "features", a folder named
+"plugins" containing some jar files, and two jar files called "artifacts.jar" and
+"content.jar".
+
+More information about the build, structure and environment can be found in the [development environment description](development_environment.md).
\ No newline at end of file
--- /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).
+++ /dev/null
-## Getting started with Mograsim
-### Prerequisites
-- [Java](http://jdk.java.net/) 11 or later (or [Oracle Implementation](https://www.oracle.com/technetwork/java/javase/downloads/index.html))
-- [Eclipse](https://www.eclipse.org/downloads/) 2019-03 or later (TODO do earlier versions work?)
-### Install Mograsim
-1. Start Eclipse
-2. Go to "Help" -> "Install New Software..."
-3. Enter the Mograsim update site address
- 1. Click on "Add..."
- 2. Next to "Location:", enter the update site address
- 3. Click on "Add"
-1. Tick "Mograsim"
-2. Click on "Next >" two times, read and accept the license, and click on "Finish"
-3. Confirm that you want to install unsigned content
-4. Wait for the installation to complete (may take a while). When prompted, restart Eclipse.
-### Enable the Launch action set
-1. Go to "Window" -> "Perspective" -> "Customize Perspective..."
-2. Go to the tab "Action Set Availability"
-3. Under "Available action sets", enable "Launch" (if it is not already enabled); click on "Apply and Close"
-### Create a new Mograsim project
-1. Create a new Eclipse project ("File" -> "New" -> "Project...", select "General" -> "Project")
-2. Add the Mograsim nature to the new project and set it up.
- 1. Open the properties dialog of the new project (right-click on it, select Properties)
- 2. Go to the "Project Natures" page, click on "Add...". If a confirmation dialog pops up, confirm.
- 3. Select "Mograsim Project Nature"; click on "OK".
- 4. Click on "Apply and Close" and re-open the properties dialog.
- 5. Go to the new "Mograsim" page, select "Am2900Simple", click on "Apply and Close".
-### Write a MPM file (containing the microprogram)
-1. Create a new file with the extension ".mpm". (Right-click on the project -> "New" -> "File"; enter the filename; click on "Finish")
-2. The Mograsim instruction editor should open. If not, right-click on the MPM file -> "Open With" -> "Other..."; select "Instruction Editor"; click on "OK".
-3. Write a microprogram. (Note: The MPROM is hardcoded to be Opcode * 0x10)
-4. Every cell differing from the default value is highlighted with a cursive font and green background.
-### _(optional)_ Write a MEM file (containing the initial contents of the memory)
-1. Create a new file with the extension ".mem" (as described above)
-2. The Mograsim memory editor should open. If not, open it as described above.
-3. Write the memory contents.
-
-Each table row contains one (16 bit wide) memory cell.
-The two text fields labeled "Address" and "Number of cells" only refer to the cells displayed simultaneously in the editor. The editor internally retains all 65536 addressable cells.
-Don't use the "Set active" button. (TODO: remove it)
-### Open the views "Simulation", "Debug", "Memory" and "Registers"
-1. Go to "Window" -> "Show View" -> "Other...", select a view; click on "Open".
-The Simulation view is in the category "Mograsim" and the other views in "Debug".
-2. It is recommended to move the Simulation view to the Editor pane.
-### Create a machine launch configuration and run it
-1. Click on the little triangle next to the "Launch" symbol in the toolbar; click on "Run configurations..."
-2. Right-click on "Mograsim machine" -> "New Configuration".
-3. Enter the Mograsim project containing both the MPM and MEM file, as well as these files.
-4. If you don't have a MEM file, leave the according field blank. This causes the memory to be initialized with 0.
-5. Click "Run". The Simulation view now should contain a rectangle containing either the text "Am2900" in a very small font or a huge mess of smaller rectangles connected by colored lines.
-
-The machine doesn't start running yet since it starts paused. (TODO: make a checkbox for this)
-### Set up and get used to the views
-#### Simulation view (see also the [simulation model explanation](model.md))
-Move the view around by dragging with the left mouse button held.
-Zoom in and out by either scrolling up or down or by dragging down and up with the middle mouse button held.
-
-Using the slider or by directly entering a number in the text field, the machine can be slowed down or sped up.
-
-Also, a "step by step execution" mode can be enabled. (TODO use "Step over" instead)
-Step by step execution means that the machine is automatically paused on each rising edge of the clock.
-
-At the bottom of the Simulation view, a single instruction table row is displayed. This row contains the instruction currently being executed.
-The MPM can be modified by this line. This is not recommended, however, because changes done here are not reflected in the MPM file, and will be undone if the MPM file is hot-replaced (see below), even if the changed row didn't change in the hot replace. Also, as for a hot replace, these changes doesn't affect the currently active microinstruction.
-#### Memory view
-1. In the Memory view, click on the green +, enter 0 and click on "OK".
-2. Right-click on the table -> "Format...".
-3. Select 16 units per row and one unit per column. (8 units per row if 16 don't fit on the screen.)
-
-The table now displays the contents of the currently running machine. At this moment, this should be equal to the contents of the initial memory specified when creating the launch configuration. This table updates automatically if the machine writes a memory cell. In this case, for a short time, this cell is highlighted using a red font and with a small delta symbol in the cell's corner.
-#### Register view
-1. Expand the pseudo register group.
-It should contain the registers R0-R15 as well as the Q register.
-All of them should be 0, displayed as a bitstring (TODO view in hex).
-
-It is possible to change the register contents via this view by clicking on the old value and entering a new bitstring (TODO a hex integer). It is not recommended to use `Z` in these bitstrings.
-#### Debug view
-Lists all currently running machines. The Simulation, Memory, and Register view follow the selection done here.
-A Mograsim machine launch contains one debug target, which contains one thread labeled "pseudo thread".
-The pseudo thread contains one stack frame labeled "pseudo stack frame" as long as the machine is paused. Unfortunately, it is required by Eclipse that threads don't have stack frames as long as they are running.
-For the Memory view to work, the pseudo thread or pseudo stack frame of a machine launch needs to be selected; for the Register view, the stack frame needs to be selected.
-#### Toolbar
-The toolbar also contains some relevant buttons: "Resume", "Suspend", and "Terminate".
-Suspend not only causes the clock to stop, but freezes the other components and wires. Because of this, some components can seem to be in an incorrect state, for example the two inputs of a NAND gate could be 1, while the output also is 1.
-### Start the machine
-Set the simulation speed to the lowest setting.
-In the toolbar, click the "Resume" button.
-Slowly increase the simulation speed until the wires in the Simulation view start flickering. The machine is now running and starts executing the microprogram.
-### Notes
-1. If the MPM file used by a machine launch is opened in the Instruction editor, the row corresponding to the microinstruction currently being executed is highlighted there using a bold font and yellow background.
-2. If the MPM file changes, after confirmation, the changes are hot-replaced into the machine.
- Changes in the MPM file don't affect the currently active microinstruction, however.
-3. Some of the behaviour described here can be changed in the Eclipse Preferences (in the pages "Mograsim" and "General" -> "Appearance" -> "Colors and Fonts"). For these cases the default behaviour is described.
-### Troubleshooting
-- If nothing Mograsim-related seems to be installed after installing Mograsim, make sure Eclipse uses Java 11 or later.
-1. Go to "Help" -> "About Eclipse IDE", click on "Installation Details", go to the tab "Configuration"
-2. Search the line starting with "java.version=". (This line is in the "System properties" block, which usually occupies the first 200 lines)
-3. If this line specifies a version less than 11, configure your Eclipse installation to use a Java 11 JRE (or later). See https://wiki.eclipse.org/FAQ_How_do_I_run_Eclipse%3F#Find_the_JVM.
\ No newline at end of file
+++ /dev/null
-The simulation model consists of components connected by wires.
-
-Some components consist of other components and wires. The components contained in such a component are called the subcomponents of this component.
-
-Some wires carry one bit, and some carry multiple bits.
-
-Each bit carried by a wire is one of 1, 0, U, Z, or X. These values are IEEE 1164-compilant. (We don't use H, L, or W.)
-See https://en.wikipedia.org/wiki/IEEE_1164 for an explanation of these values.
-Note: We also use X to denote illegal states. For example, when two components try to put different values on the D bus, the conflicting bits on the D bus will become X.
-
-The simulation model can be viewed in the Simulation view:
-Each rectangle represents a component. Zooming in a component reveals its inner structure (if it has one).
-The colored lines connecting these rectangles represent wires.
-(Multiple-bit wires are displayed thicker than the single-bit wires, and always are black.
-For single-bit wires, the color represents their current value. These colors can be configured in the Eclipse preferences. The default values are:
-
-| Bit | Color |
-|:---:| ------ |
-| 1 | green |
-| 0 | grey |
-| U | cyan |
-| Z | yellow |
-| X | red |
\ No newline at end of file
--- /dev/null
+## Getting started with Mograsim
+### Prerequisites
+- [Java](http://jdk.java.net/) 11 or later (or [Oracle Implementation](https://www.oracle.com/technetwork/java/javase/downloads/index.html))
+- [Eclipse](https://www.eclipse.org/downloads/) 2019-03 or later (TODO: do earlier versions work?)
+### Install Mograsim
+1. Start Eclipse
+2. Go to "Help" -> "Install New Software..."
+3. Enter the Mograsim update site address
+ 1. Click on "Add..."
+ 2. Next to "Location:", enter the update site address
+ 3. Click on "Add"
+1. Tick "Mograsim"
+2. Click on "Next >" two times, read and accept the license, and click on "Finish"
+3. Confirm that you want to install unsigned content
+4. Wait for the installation to complete (may take a while). When prompted, restart Eclipse.
+### Enable the Launch action set
+1. Go to "Window" -> "Perspective" -> "Customize Perspective..."
+2. Go to the tab "Action Set Availability"
+3. Under "Available action sets", enable "Launch" (if it is not already enabled); click on "Apply and Close"
+### Create a new Mograsim project
+1. Create a new Eclipse project ("File" -> "New" -> "Project...", select "General" -> "Project")
+2. Add the Mograsim nature to the new project and set it up.
+ 1. Open the properties dialog of the new project (right-click on it, select Properties)
+ 2. Go to the "Project Natures" page, click on "Add...". If a confirmation dialog pops up, confirm.
+ 3. Select "Mograsim Project Nature"; click on "OK".
+ 4. Click on "Apply and Close" and re-open the properties dialog.
+ 5. Go to the new "Mograsim" page, select "Am2900Simple", click on "Apply and Close".
+### Write a MPM file (containing the microprogram)
+1. Create a new file with the extension ".mpm". (Right-click on the project -> "New" -> "File"; enter the filename; click on "Finish")
+2. The Mograsim instruction editor should open. If not, right-click on the MPM file -> "Open With" -> "Other..."; select "Instruction Editor"; click on "OK".
+3. Write a microprogram. (Note: The MPROM is hardcoded to be Opcode * 0x10)
+4. Every cell differing from the default value is highlighted with a cursive font and green background.
+### _(optional)_ Write a MEM file (containing the initial contents of the memory)
+1. Create a new file with the extension ".mem" (as described above)
+2. The Mograsim memory editor should open. If not, open it as described above.
+3. Write the memory contents.
+
+Each table row contains one (16 bit wide) memory cell.
+The two text fields labeled "Address" and "Number of cells" only refer to the cells displayed simultaneously in the editor. The editor internally retains all 65536 addressable cells.
+Don't use the "Set active" button. (TODO: remove it)
+### Open the views "Simulation", "Debug", "Memory" and "Registers"
+1. Go to "Window" -> "Show View" -> "Other...", select a view; click on "Open".
+The Simulation view is in the category "Mograsim" and the other views in "Debug".
+2. It is recommended to move the Simulation view to the Editor pane.
+### Create a machine launch configuration and run it
+1. Click on the little triangle next to the "Launch" symbol in the toolbar; click on "Run configurations..."
+2. Right-click on "Mograsim machine" -> "New Configuration".
+3. Enter the Mograsim project containing both the MPM and MEM file, as well as these files.
+4. If you don't have a MEM file, leave the according field blank. This causes the memory to be initialized with 0.
+5. Click "Run". The Simulation view now should contain a rectangle containing either the text "Am2900" in a very small font or a huge mess of smaller rectangles connected by colored lines.
+
+The machine doesn't start running yet since it starts paused. (TODO: make a checkbox for this)
+### Set up and get used to the views
+#### Simulation view (see also the [simulation model explanation](model.md))
+Move the view around by dragging with the left mouse button held.
+Zoom in and out by either scrolling up or down or by dragging down and up with the middle mouse button held.
+
+Using the slider or by directly entering a number in the text field, the machine can be slowed down or sped up.
+
+Also, a "step by step execution" mode can be enabled. (TODO: use "Step over" instead)
+Step by step execution means that the machine is automatically paused on each rising edge of the clock.
+
+At the bottom of the Simulation view, a single instruction table row is displayed. This row contains the instruction currently being executed.
+The MPM can be modified by this line. This is not recommended, however, because changes done here are not reflected in the MPM file, and will be undone if the MPM file is hot-replaced (see below), even if the changed row didn't change in the hot replace. Also, as for a hot replace, these changes doesn't affect the currently active microinstruction.
+#### Memory view
+1. In the Memory view, click on the green +, enter 0 and click on "OK".
+2. Right-click on the table -> "Format...".
+3. Select 16 units per row and one unit per column. (8 units per row if 16 don't fit on the screen.)
+
+The table now displays the contents of the currently running machine. At this moment, this should be equal to the contents of the initial memory specified when creating the launch configuration. This table updates automatically if the machine writes a memory cell. In this case, for a short time, this cell is highlighted using a red font and with a small delta symbol in the cell's corner.
+#### Register view
+1. Expand the pseudo register group.
+It should contain the registers R0-R15 as well as the Q register.
+All of them should be 0, displayed as a bitstring (TODO: view in hex).
+
+It is possible to change the register contents via this view by clicking on the old value and entering a new bitstring (TODO: a hex integer). It is not recommended to use `Z` in these bitstrings.
+#### Debug view
+Lists all currently running machines. The Simulation, Memory, and Register view follow the selection done here.
+A Mograsim machine launch contains one debug target, which contains one thread labeled "pseudo thread".
+The pseudo thread contains one stack frame labeled "pseudo stack frame" as long as the machine is paused. Unfortunately, it is required by Eclipse that threads don't have stack frames as long as they are running.
+For the Memory view to work, the pseudo thread or pseudo stack frame of a machine launch needs to be selected; for the Register view, the stack frame needs to be selected.
+#### Toolbar
+The toolbar also contains some relevant buttons: "Resume", "Suspend", and "Terminate".
+Suspend not only causes the clock to stop, but freezes the other components and wires. Because of this, some components can seem to be in an incorrect state, for example the two inputs of a NAND gate could be 1, while the output also is 1.
+### Start the machine
+Set the simulation speed to the lowest setting.
+In the toolbar, click the "Resume" button.
+Slowly increase the simulation speed until the wires in the Simulation view start flickering. The machine is now running and starts executing the microprogram.
+### Notes
+1. If the MPM file used by a machine launch is opened in the Instruction editor, the row corresponding to the microinstruction currently being executed is highlighted there using a bold font and yellow background.
+2. If the MPM file changes, after confirmation, the changes are hot-replaced into the machine.
+ Changes in the MPM file don't affect the currently active microinstruction, however.
+3. Some of the behaviour described here can be changed in the Eclipse Preferences (in the pages "Mograsim" and "General" -> "Appearance" -> "Colors and Fonts"). For these cases the default behaviour is described.
+### Troubleshooting
+- If nothing Mograsim-related seems to be installed after installing Mograsim, make sure Eclipse uses Java 11 or later.
+1. Go to "Help" -> "About Eclipse IDE", click on "Installation Details", go to the tab "Configuration"
+2. Search the line starting with "java.version=". (This line is in the "System properties" block, which usually occupies the first 200 lines)
+3. If this line specifies a version less than 11, configure your Eclipse installation to use a Java 11 JRE (or later). See https://wiki.eclipse.org/FAQ_How_do_I_run_Eclipse%3F#Find_the_JVM.
\ No newline at end of file
--- /dev/null
+The simulation model consists of components connected by wires.
+
+Some components consist of other components and wires. The components contained in such a component are called the subcomponents of this component.
+
+Some wires carry one bit, and some carry multiple bits.
+
+Each bit carried by a wire is one of 1, 0, U, Z, or X. These values are IEEE 1164-compilant. (We don't use H, L, or W.)
+See https://en.wikipedia.org/wiki/IEEE_1164 for an explanation of these values.
+Note: We also use X to denote illegal states. For example, when two components try to put different values on the D bus, the conflicting bits on the D bus will become X.
+
+The simulation model can be viewed in the Simulation view:
+Each rectangle represents a component. Zooming in a component reveals its inner structure (if it has one).
+The colored lines connecting these rectangles represent wires.
+(Multiple-bit wires are displayed thicker than the single-bit wires, and always are black.
+For single-bit wires, the color represents their current value. These colors can be configured in the Eclipse preferences. The default values are:
+
+| Bit | Color |
+|:---:| ------ |
+| 1 | green |
+| 0 | grey |
+| U | cyan |
+| Z | yellow |
+| X | red |
\ No newline at end of file
projects / Mograsim.git / commitdiff