From f72e7f0706149d0413e7c607b861022ea7480cc1 Mon Sep 17 00:00:00 2001 From: Daniel Kirschten Date: Sun, 6 Oct 2019 20:56:22 +0200 Subject: [PATCH] Restructured documentation files --- MAVEN-TYCHO-README.html | 250 ------------------ README.md | 80 +----- docs/building_mograsim.md | 79 ++++++ .../development_environment.md | 0 .../getstarted.md => getting_started.md} | 8 +- docs/{doc-snippets => }/model.md | 0 6 files changed, 87 insertions(+), 330 deletions(-) delete mode 100644 MAVEN-TYCHO-README.html create mode 100644 docs/building_mograsim.md rename MAVEN-TYCHO-README.MD => docs/development_environment.md (100%) rename docs/{doc-snippets/getstarted.md => getting_started.md} (95%) rename docs/{doc-snippets => }/model.md (100%) diff --git a/MAVEN-TYCHO-README.html b/MAVEN-TYCHO-README.html deleted file mode 100644 index bc19ca9e..00000000 --- a/MAVEN-TYCHO-README.html +++ /dev/null @@ -1,250 +0,0 @@ - - - - - - - - - -

Mograsim Development Environment

-

Mograsim Development Documentation Version 0.3 — 2019-09-27

-

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 is a plugin for -Maven that allows building Eclipse and OSGi Projects comfortably -and automatically using Maven.

-

Useful links:

- -

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:

- -

Eclipse Plugins

- -

Mograsim Structure

-

The tree of Mograsim projects:

- -

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):

- -

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.

-

Challenges

-

Not everything is as simple as it seems at first glance.

-

Maven Core Extension Problems

-

The Tycho extra tycho-pomless is a Maven core extension allows for simpler structure -and less redundancy. Maven core extensions must be available at the central maven repository -(or already in the local repository), you cannot specify an alternative remote repository -in .mvn/extensions.xml. If a core extension cannot be resolved, you will get currently -(Maven 3.6.2) only a warning like

-

[WARNING] The POM for org.eclipse.tycho.extras:tycho-pomless:jar:1.5.0-SNAPSHOT is missing, no dependency information available

-
-

This means that the extension was not found, and it cannot be used, which leads to -a failure later on. To get around that, create a dummy pom that only serves the purpose -to “request” and resolve the extension:

-
<project .. bla .. bla ..>
-    <modelVersion>4.0.0</modelVersion>
-    <groupId>net.mograsim</groupId>
-    <artifactId>net.mograsim.tycho-download</artifactId>
-    <version>1.0.0</version>
-    <packaging>pom</packaging>
-
-    <pluginRepositories>
-        <!-- currently necessary because we are using a SNAPSHOT build of tycho -->
-        <pluginRepository>
-            <id>tycho-snapshots</id>
-            <url>https://repo.eclipse.org/content/repositories/tycho-snapshots/</url>
-            <releases>
-                <enabled>true</enabled>
-            </releases>
-            <snapshots>
-                <enabled>true</enabled>
-                <updatePolicy>always</updatePolicy>
-            </snapshots>
-        </pluginRepository>
-    </pluginRepositories>
-
-    <build>
-        <extensions>
-            <extension>
-                <groupId>org.eclipse.tycho.extras</groupId>
-                <artifactId>tycho-pomless</artifactId>
-                <version>1.5.0-SNAPSHOT</version>
-            </extension>
-        </extensions>
-    </build>
-</project>
-
-

While that this is not the most compact way, it can be run by the developer and build -server equally easy and does not require special CLI knowledge. As developer, you -need to run that only once (in Eclipse: right click on pom.xml -> Run As -> Maven -clean). For continuous integration, you can insert one more line in the YAML (or -equivalent), like in our case - mvn $MAVEN_CLI_OPTS clean.

-

Git Submodules

-

Git submodules are a challenge with a tycho build, because the projects that reside -in it need to be build, too. But not only that, they need to use the same configuration -for the build, which is problematic if you do not have control over them. The solution -only exists with Tycho 1.5.0 (currently only as snapshot), where deep folder structures -are automatically scanned and poms get gnereated; not every folder requires an aggregator -pom. This however requires (at the moment) certain naming conventions (see section -on Tycho itself).

-

In our case, SWTHelper is a git submodule -containing several plain Java Eclipse projects with OSGi configuration (MANIFEST.MF), -which is the reason this works at all. Due to the naming conventions, the submodule -folder is named bundles.

-

Maven 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).

- - \ No newline at end of file diff --git a/README.md b/README.md index f7031a46..a20ad72b 100644 --- a/README.md +++ b/README.md @@ -14,82 +14,10 @@ and what the purpose of microprogramming is. In more detail, Mograsim allows: 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 ` -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 diff --git a/docs/building_mograsim.md b/docs/building_mograsim.md new file mode 100644 index 00000000..bfcf6240 --- /dev/null +++ b/docs/building_mograsim.md @@ -0,0 +1,79 @@ +# 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 ` +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 diff --git a/MAVEN-TYCHO-README.MD b/docs/development_environment.md similarity index 100% rename from MAVEN-TYCHO-README.MD rename to docs/development_environment.md diff --git a/docs/doc-snippets/getstarted.md b/docs/getting_started.md similarity index 95% rename from docs/doc-snippets/getstarted.md rename to docs/getting_started.md index e3c51461..d2210379 100644 --- a/docs/doc-snippets/getstarted.md +++ b/docs/getting_started.md @@ -1,7 +1,7 @@ ## 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?) +- [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..." @@ -57,7 +57,7 @@ Zoom in and out by either scrolling up or down or by dragging down and up with t 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) +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. @@ -71,9 +71,9 @@ The table now displays the contents of the currently running machine. At this mo #### 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). +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. +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". diff --git a/docs/doc-snippets/model.md b/docs/model.md similarity index 100% rename from docs/doc-snippets/model.md rename to docs/model.md -- 2.17.1