MAVEN-TYCHO-README.html

   1 <html><head>
   2                 <meta charset='utf-8'>
   3                 <meta http-equiv='x-ua-compatible' content='IE=edge'/>
   4                 <meta name="viewport" content="width=device-width,initial-scale=1.0">
   5                 <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css">
   6                 <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js"></script>
   7                 <script>hljs.initHighlightingOnLoad();</script>
   8 <style media="screen" type="text/css">
   9 /*! 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}}
  10 </style>
  11 </head><body>
  12 <h1>Mograsim Development Environment</h1>
  13 <p><span style="color:grey"><em>Mograsim Development Documentation Version 0.2 &mdash; 2019-09-18</em></span></p>
  14 <p>A short guide to the Mograsim Maven Tycho configuration and Maven Tycho in general,
  15 as well as some information on Eclipse Plugin Development and OSGi.</p>
  16 <h2>Maven Tycho</h2>
  17 <p><a href="https://www.eclipse.org/tycho/sitedocs/index.html">Maven Tycho</a> is a plugin for
  18 <a href="http://maven.apache.org">Maven</a> that allows building Eclipse and OSGi Projects comfortably
  19 and automatically using Maven.</p>
  20 <p>Useful links:</p>
  21 <ul>
  22 <li><a href="https://www.eclipse.org/tycho/">eclipse.org/tycho</a></li>
  23 <li><a href="https://wiki.eclipse.org/Category:Tycho">wiki.eclipse.org/Category:Tycho</a></li>
  24 <li><a href="https://www.vogella.com/tutorials/EclipseTycho/article.html">vogella.com/tutorials/EclipseTycho</a></li>
  25 <li><a href="https://www.eclipse.org/tycho/sitedocs/index.html">eclipse.org/tycho/sitedocs</a></li>
  26 <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>
  27 (see *Mapping for naming and other conventions, TychoAggregatorMapping for folders)</li>
  28 </ul>
  29 <h2>OSGi</h2>
  30 <p>OSGi is a module system for Java (completely unrelated to the Java 9 Jigsaw module
  31 system) that allows detailed control over modules, dependencies, versions and more.
  32 The file associated with OSGi here is a specific MANIFEST.MF in the META-INF directory
  33 of each project.</p>
  34 <p>Roughly, an OSGi bundle has:</p>
  35 <ul>
  36 <li>a <strong>symbolic name</strong> that acts as an identifier, therefore it should be unique and
  37 must not be changed, otherwise it a large portion of the configuration would break.
  38 Never change that field after distribution.</li>
  39 <li>a <strong>bundle name</strong> and <strong>bundle vendor</strong>; this is only for the users and developers
  40 and is not constrained in any way. You can change that, but it should be consistent
  41 across all Mograsim modules. Both can be externalized to</li>
  42 <li>a <strong>bundle version</strong> that denotes current the version of the bundle. The <code>qualifier</code>
  43 is replaced during the build process with a timestamp of the format <code>YYYYMMDDhhmmss</code>.
  44 The version itself can be set using the maven tycho version plugin, which replaces
  45 not only the maven versions, but all (equivalent) versions in the MANIFEST as well.</li>
  46 <li>a <strong>bundle required execution environment</strong> (abbr. BREE) where the bundle's <em>minimal</em>
  47 JDK version is set. This is also the one eclipse uses and displays as JRE System
  48 Library in the Eclipse projects.<br> This should be the same as the one the target
  49 definition used for the build and the same that maven is run with ( -> check the
  50 Run Configuration)</li>
  51 </ul>
  52 <h2>Eclipse Plugins</h2>
  53 <ul>
  54 <li>Short explanation of the different names and terms used in Eclipse Plugin Dev,
  55 and short introduction to the different mechanisms used.</li>
  56 </ul>
  57 <h2>Mograsim Structure</h2>
  58 <p>The tree of Mograsim projects:</p>
  59 <ul>
  60 <li><code>plugins</code> - <em>This contains all bundles/plugins that provide functionality to Mograsim</em><ul>
  61 <li><strong>net.mograsim.logic.core</strong> <br> The core logic for pure simulation. This contains
  62 the most important low-level logic circuits and gates and defines how that
  63 logic gets simulated. The underlying system for simulation in Mograsim is an
  64 event based approach (see <code>Timeline</code>), using VHDL-like logic defined in <code>Bit</code>
  65 and <code>BitVector</code>. More complex ciruits are build out of <code>Wire</code>s connecting <code>Component</code>s.</li>
  66 <li><strong>net.mograsim.logic.model</strong> <br>The model describes how that core logic is
  67 displayed and arranged, and allows (de-)serialization to JSON. The core logic
  68 model gets generated based on this. Every basic net.mograsim.logic.core Component
  69 has a model equivalent here that represents it in the GUI and persisted state
  70 (JSON).</li>
  71 <li><strong>net.mograsim.logic.model.editor</strong> <br> This bundle contains a standalone
  72 SWT-based editor to edit Mograsim JSON-models in a comfortable way. It can
  73 be used to create a new <code>SubmodelComponent</code> by arranging existing ones to a
  74 new component. Note that editing and simulation are entirely different processes
  75 in Mograsim, the editor cannot simulate and a running simulation cannot be
  76 edited. (At least in the current state)</li>
  77 <li><strong>net.mograsim.logic.model.am2900</strong> <br> This plugin contains a model for the
  78 AMD Am2900 Family Microprocessors arranged into a microprogrammable model.
  79 This can be used in the microprogram editor of the Mograsim plugin and in the
  80 Mograsim assembler editor (by using a properly set up instruction set). We
  81 took care that the plugin is independent, meaning that it only provides an
  82 implementation for an extension point of the net.mograsim.machine plugin and
  83 no other Mograsim depends on it.<br> This is also the way to go if you want
  84 to add your own machine definitions to Mograsim and use them there.</li>
  85 <li><strong>net.mograsim.machine</strong> <br> The machine plugin defines an extension point
  86 that can be extended and implemented in other (your own) plugins to provide
  87 new machines to Mograsim. In addition to the extension point and the most important
  88 interfaces, it contains some commonly required or useful components to build/define
  89 another machine. net.mograsim.logic.model.am2900 for example is such an extension.
  90 The machine plugin itself scans for all available implementations of the interface
  91 given by the extension point, and other parts of the Mograsim plugin get access
  92 to them that way.</li>
  93 <li><strong>net.mograsim.plugin.core</strong> <br> This is - as the name says - the core plugin
  94 of mograsim. Here lie all the Eclipse Platform specific parts that make Mograsim
  95 as an Eclipse plugin work. This includes the different editors, view, settings
  96 and other functional extension to the Eclipse IDE.</li>
  97 <li><strong>net.mograsim.plugin.core.nl_de</strong> <br> This optional plugin provides a German
  98 localization for Mograsim.</li>
  99 <li><strong>net.mograsim.plugin.branding</strong> <br> This contains elements for branding the
 100 feature plugin, and additional resources and raw files (original logo and icon
 101 in SVG and Adobe Illustrator and similar).</li>
 102 <li><strong>net.mograsim.plugin.docs</strong> <br> The Plugin providing the user documentation.</li>
 103 <li><strong>net.mograsim.preferences</strong> <br> A plugin for managing and accessing preferences.</li>
 104 </ul>
 105 </li>
 106 <li><code>features</code> - <em>This contains all Mograsim feature plugins</em><ul>
 107 <li><strong>net.mograsim.feature</strong> <br> The Mograsim feature plugin, containing all the
 108 plugins above and combining them into a feature. A feature is a plugin collection
 109 with additional properties that allows for easy installation by the end user.
 110 For this purpose, it also contains license information, authors, updatesite
 111 location (allows eclipse to automatically check if updates are available) and
 112 more.</li>
 113 </ul>
 114 </li>
 115 <li><code>products</code> - <em>This contains standalone Mograsim product(s)</em><ul>
 116 <li><strong>net.mograsim.product</strong> <br> A product can be pretty much anything (see Eclipse
 117 RCP), in our case, this is simply a pre-configured Eclipse package, comparable
 118 to the packages located at <a href="https://www.eclipse.org/downloads/packages/">www.eclipse.org/downloads/packages</a>.</li>
 119 </ul>
 120 </li>
 121 <li><code>releng</code> - <em>Abbreviation for <strong>Rel</strong>ease <strong>Eng</strong>ineering, contains important configuration</em><ul>
 122 <li><strong>net.mograsim.configuration</strong> <br> This contains the configuration for the
 123 Mograsim project and the build in particular. The central Maven configuration
 124 is located here in a single <code>pom.xml</code>, that is the super-parent of all others,
 125 including the generated ones.</li>
 126 <li><strong>net.mograsim.updatesite</strong> <br> This updatesite project collects features
 127 in form of an update site that can be accessed by Eclipse to install new features
 128 or update features. The features are grouped into categories which can come
 129 with further descriptions. The <code>target/repository/</code> is the part of the whole
 130 Mograsim project that actually gets deployed. By using Help -> Install New
 131 Software -> Add -> Local, the <code>repository</code>-folder can be selected and features
 132 can be installed offline, e.g. to test them.</li>
 133 <li><strong>net.mograsim.target</strong> <br> The target definition for the build. This is a
 134 well-defined environment that we expect the plugins to work in/with. That includes
 135 all plugin dependencies (like all plugins the Eclipse Platform is comprised
 136 of) and the (minimum) JRE that is expected. Some plugins exclusively for testing
 137 are included here, too.</li>
 138 </ul>
 139 </li>
 140 <li><code>tests</code> - <em>This contains (integration-like) tests in form of plugin fragments</em><ul>
 141 <li><strong>net.mograsim.logic.core.tests</strong></li>
 142 <li><strong>net.mograsim.logic.model.am2900.tests</strong></li>
 143 <li><strong>net.mograsim.machine.tests</strong></li>
 144 </ul>
 145 </li>
 146 <li><code>SWTHelper</code> - <em>This contains the <a href="https://github.com/Haspamelodica/SWTHelper">SWTHelper</a>
 147 git submodule.</em><ul>
 148 <li><code>bundles</code> - <em>This submodule folder needs to be named like that for Tycho pom-less
 149 build to work.</em><ul>
 150 <li><span style="color:grey"><em>SWTInput</em></span> - <em>unused</em></li>
 151 <li><strong>SWTObjectWrappers</strong> - SWT object abstractions to enable zooming and optimizations.</li>
 152 <li><span style="color:grey"><em>SWTSystemInOutApplication</em></span> - <em>unused</em></li>
 153 <li><span style="color:grey"><em>SWTTiledZoomableCanvas</em></span> - <em>unused</em></li>
 154 <li><strong>SWTZoomableCanvas</strong> - The SWT canvas we draw the simulation in.</li>
 155 </ul>
 156 </li>
 157 </ul>
 158 </li>
 159 </ul>
 160 <h2>Build Mograsim</h2>
 161 <p>Use the main aggregator <code>pom.xml</code> next to this markdown file to build mograsim, take
 162 care to use the correct JDK to run it (see Run Configuration).</p>
 163 <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>
 164 <ul>
 165 <li>The <code>clean</code> goal will remove all <code>target</code>-folders and other generated files like
 166 flattened poms and polyglot build artifacts (all are listed in <code>.gitignore</code>).</li>
 167 <li>The <code>validate</code> goal is useful to simply check if the setup itself (Maven Tycho)
 168 is ok and everything needed is available.</li>
 169 <li>The <code>integration-test</code> goal will run the test plugins, the <code>test</code> goal beforehand
 170 <strong>will not.</strong></li>
 171 <li>I recommend running <code>clean verify</code> or <code>verify</code>, this will do everything up to and
 172 including the testing.</li>
 173 </ul>
 174 <p>Please note that Tycho 1.5.0 is not released yet, and thus requires a workaround.
 175 More information can be found under <a href="#mceps">Maven Core Extension Problems</a>.</p>
 176 <h2>Challenges</h2>
 177 <p>Not everything is as simple as it seems at first glance.</p>
 178 <h3>Maven Core Extension Problems <a name="mceps"></a></h3>
 179 <p>The Tycho extra <code>tycho-pomless</code> is a Maven core extension allows for simpler structure
 180 and less redundancy. Maven core extensions must be available at <a href="http://repo.maven.apache.org/maven2/">the central maven repository</a>
 181 (or already in the local repository), you cannot specify an alternative remote repository
 182 in <code>.mvn/extensions.xml</code>. If a core extension cannot be resolved, you will get currently
 183 (Maven 3.6.2) only a warning like</p>
 184 <blockquote><p>[WARNING] The POM for org.eclipse.tycho.extras:tycho-pomless:jar:1.5.0-SNAPSHOT is missing, no dependency information available</p>
 185 </blockquote>
 186 <p>This means that the extension was not found, and it cannot be used, which leads to
 187 a failure later on. To get around that, create a dummy pom that only serves the purpose
 188 to &ldquo;request&rdquo; and resolve the extension:</p>
 189 <pre><code>&lt;project .. bla .. bla ..&gt;
 190     &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
 191     &lt;groupId&gt;net.mograsim&lt;/groupId&gt;
 192     &lt;artifactId&gt;net.mograsim.tycho-download&lt;/artifactId&gt;
 193     &lt;version&gt;1.0.0&lt;/version&gt;
 194     &lt;packaging&gt;pom&lt;/packaging&gt;
 195
 196     &lt;pluginRepositories&gt;
 197         &lt;!-- currently necessary because we are using a SNAPSHOT build of tycho --&gt;
 198         &lt;pluginRepository&gt;
 199             &lt;id&gt;tycho-snapshots&lt;/id&gt;
 200             &lt;url&gt;https://repo.eclipse.org/content/repositories/tycho-snapshots/&lt;/url&gt;
 201             &lt;releases&gt;
 202                 &lt;enabled&gt;true&lt;/enabled&gt;
 203             &lt;/releases&gt;
 204             &lt;snapshots&gt;
 205                 &lt;enabled&gt;true&lt;/enabled&gt;
 206                 &lt;updatePolicy&gt;always&lt;/updatePolicy&gt;
 207             &lt;/snapshots&gt;
 208         &lt;/pluginRepository&gt;
 209     &lt;/pluginRepositories&gt;
 210
 211     &lt;build&gt;
 212         &lt;extensions&gt;
 213             &lt;extension&gt;
 214                 &lt;groupId&gt;org.eclipse.tycho.extras&lt;/groupId&gt;
 215                 &lt;artifactId&gt;tycho-pomless&lt;/artifactId&gt;
 216                 &lt;version&gt;1.5.0-SNAPSHOT&lt;/version&gt;
 217             &lt;/extension&gt;
 218         &lt;/extensions&gt;
 219     &lt;/build&gt;
 220 &lt;/project&gt;
 221 </code></pre>
 222 <p>While that this is not the most compact way, it can be run by the developer and build
 223 server equally easy and does not require special CLI knowledge. As developer, you
 224 need to run that only once (in Eclipse: right click on pom.xml -> Run As -> Maven
 225 clean). For continuous integration, you can insert one more line in the YAML (or
 226 equivalent), like in our case <code>- mvn  $MAVEN_CLI_OPTS clean</code>.</p>
 227 <h3>Git Submodules</h3>
 228 <p>Git submodules are a challenge with a tycho build, because the projects that reside
 229 in it need to be build, too. But not only that, they need to use the same configuration
 230 for the build, which is problematic if you do not have control over them. The solution
 231 only exists with Tycho 1.5.0 (currently only as snapshot), where deep folder structures
 232 are automatically scanned and poms get gnereated; not every folder requires an aggregator
 233 pom. This however requires (at the moment) certain naming conventions (see section
 234 on Tycho itself).</p>
 235 <p>In our case, <a href="https://github.com/Haspamelodica/SWTHelper">SWTHelper</a> is a git submodule
 236 containing several plain Java Eclipse projects with OSGi configuration (MANIFEST.MF),
 237 which is the reason this works at all. Due to the naming conventions, the submodule
 238 folder is named <code>bundles</code>.</p>
 239 <h3>Maven incompatibility</h3>
 240 <p>Maven 3.6.2 is currently incompatible with Tycho &lt;= 1.5.0.</p>
 241 <p>If you encounter</p>
 242 <blockquote><p>[FATAL] Non-readable POM &ldquo;somepath&rdquo;\tests.polyglot.pom.tycho: input contained no data @</p>
 243 </blockquote>
 244 <p>or</p>
 245 <blockquote><p>[FATAL] Non-readable POM &ldquo;somepath&rdquo;\bundles\net.mograsim.logic.core.polyglot..META-INF_MANIFEST.MF: input contained no data @</p>
 246 </blockquote>
 247 <p>make sure to use Maven 3.6.1 to fix that (this is the default Eclipse embedded Maven
 248 at the moment).</p>
 249
 250 </body></html>