Merge pull request #392 from bci-oss/391-document-past-design-decisions

Describe important past design decisions

Author: atextor

documentation/decisions/0001-template-engine.md

@@ -0,0 +1,42 @@
+# Template Engine
+
+## Context and Problem Statement
+
+Various modules in the SDK generate code and other artifacts, such as documentation, from Aspect
+Models. For this, a suitable template engine is required that can be embedded in the generation
+APIs.
+
+## Decision Drivers
+
+* Sufficient expressiveness for the task at hand
+* Good Java integration, since the engine is to be embedded in the Java code base
+* Beneficial: Good tool support (editing from editors/IDEs, in particular Intellij IDEA)
+
+## Considered Options
+
+* [Xtend](https://eclipse.dev/Xtext/xtend/): Language development framework on the Eclipse Platform;
+  works like a cross between the Java language with smaller syntax and a template engine. Xtend
+  works by cross-compiling Xtend source code to Java source code.
+* [Apache Velocity](https://velocity.apache.org/): Java-based template engine. IntelliJ IDEA
+  integration exists (syntax highlighting, auto complete, etc.). Templates are defined in VTL
+  (Velocity Template Language).
+* [Apache Freemarker](https://freemarker.apache.org/): Template engine with Java API integration,
+  with an XML-like syntax. Templates are defined in FTL (Freemarker Template Language). No IntelliJ
+  IDEA plugin seems to exist.
+
+## Decision Outcome
+
+Chosen option: "Apache Velocity", because it is a mature project. In terms of features, Velocity and
+Freemarker are very similar; the only notable difference for our daily work seems to be the
+availability of an IntelliJ IDEA plugin to work with the templates. Xtend is difficult to use for
+multiple reasons: Firstly, IDE support only exists for the Eclipse IDE, secondly, errors in the
+template result in stack traces that refer to the lines of the Java source code that was generated
+from the template, which makes debugging very difficult. Lastly, the cross-compilation approach on
+top of regular Java compilation makes building notably slower and evaluation of template snippets
+from (e.g., in unit tests) impossible.
+
+### Consequences
+
+* Good, because Velocity is a robust library with good IDE support.
+* Bad, because there seems to be not much syntax support for FTL in other editors.
+

documentation/decisions/0002-native-binaries.md

@@ -0,0 +1,56 @@
+# Native Binaries
+
+## Context and Problem Statement
+
+The SDK's command line interface should be usable as convenient to use as possible, i.e., it should
+be usable without requiring a user to have a certain version of Java installed. It should also be
+directly launchable, i.e., by typing its name (without the `java -jar` incantation).
+
+## Decision Drivers
+
+* CLI should be runnable without having Java installed.
+* CLI should be directly executable (i.e., without calling `java -jar`).
+* Beneficial: CLI should respond quickly, in particluar when showing help texts.
+
+Note: A more detailed explanation of those points can be found in the blog post [Building a decent
+Java CLI](https://atextor.de/2020/07/27/building-a-decent-java-cli.html).
+
+## Considered Options
+
+* Regular executable .jar with custom launcher script and bundled JRE.
+  * Advantages
+    * .jar file can work as-is.
+    * Flexibility to adjust script.
+  * Disadvantages
+    * Binary can not be distributed on its own; it will always need a complete folder (containing
+      the JRE).
+    * Overall startup time: startup time of the .exe + startup time of the JVM.
+* [Launch4J](https://launch4j.sourceforge.net/index.html):
+  * Remarks
+    * Effectively provides a native binary that optionally extracts an executable .jar from itself,
+      then lauches the .jar using Java.
+  * Advantages
+    * .jar file can work as-is.
+    * Out-of-the-box solution including Maven plugin.
+  * Disadvantages
+    * Binary can not be distributed on its own; it will always need a complete folder (containing
+      the JRE).
+    * Overall startup time: startup time of the .exe + startup time of the JVM.
+* [GraalVM Native Image](https://www.graalvm.org/latest/reference-manual/native-image/basics/): 
+  * Remarks
+    * Project driven by Oracle to create native binaries from Java applications, including compiler,
+      custom runtime (that will be baked into the binary) and accompanying tooling such as source
+      annotations.
+  * Advantages
+    * "Official" project with support present or coming in major frameworks.
+    * Proper tooling available (Maven plugin, Github actions, etc.).
+    * Can produce standalone binaries.
+    * Startup time overhead is removed/reduced.
+  * Disadvantages
+    * Additional configuration effort for resources, reflection, JNI,...
+    
+## Decision Outcome
+
+Chosen option: "GraalVM Native Image", because only this option will provide a quickly starting,
+self-contained binary.
+