more documentation

docs/extensions.md

@@ -6,14 +6,16 @@ permalink: /extensions
 usemathjax: true
 ---
 
-
 # Extensions
 
 This page contains two tutorials on how to construct extensions for IDeSyDe in two different manners:
 one for JVM languages, but using Java as the main example; and one for a Rust embedded module.
 
 ## Java module
 
+This tutorial assumes that you are *at least* familiar with Java syntax and minimally aware of how to structure Java projects.
+We will have brief mentions on how the
+
 To create a new java module, first make sure that JDK and `gradle` are installed in your computer.
 You can follow the steps from the [ForSyDe IO website](https://forsyde.github.io/forsyde-io/usage/#optional-downloading-sdk-gradle-and-jabba)
 using SDKMan and Jabba.
@@ -35,10 +37,169 @@ To fetch the framework parts of IDeSyDe, you need to first enable JitPack as a r
 
 ```
 repositories {
-    maven { url '<https://jitpack.io>' }
+    ...
+    maven { url 'https://jitpack.io' }
 }
 ```
 
 And then add to the modules to the dependencies section of your build.gradle:
 
+```
+dependencies {
+    ...
+    implementation "com.github.forsyde.IDeSyDe:build-java-core:0.8.4"
+    compileOnly "com.github.forsyde.IDeSyDe:build-java-core-generator:develop-SNAPSHOT"
+    annotationProcessor "com.github.forsyde.IDeSyDe:build-java-core-generator:develop-SNAPSHOT"
+    ...
+}
+```
+
+Or any version released after `0.8.4`. Check on [the GitHub release page to see the latest version](https://github.com/forsyde/IDeSyDe/releases).
+With this, it is now possible to create the Java module to be used by IDeSyDe!
+
+### Basic module
+
+Using your favourite Java IDE (we recommend either [Intellij IDEA](https://www.jetbrains.com/idea/) or [VS Code](https://code.visualstudio.com/)),
+create a new Java `interface` that will correspond to the new Module.
+Though you can choose any name you wish, in this tutorial we will go with `ExampleModule` in the package `tutorial`:
+
+```
+package tutorial;
+
+public interface ExampleModule {
+}
+```
+
+In case you are not experienced in Java development, your project should now look like this:
+
+```
+├───.gradle
+│   ├───8.2
+│   │   ├───checksums
+│   │   ├───dependencies-accessors
+│   │   ├───executionHistory
+│   │   ├───fileChanges
+│   │   ├───fileHashes
+│   │   └───vcsMetadata
+│   ├───buildOutputCleanup
+│   └───vcs-1
+├───.idea
+│   └───codeStyles
+├───gradle
+│   └───wrapper
+└───src
+    ├───main
+    │   ├───java
+    │   │   └───tutorial    <----- The new interface file exists inside this folder
+    │   └───resources
+    └───test
+        ├───java
+        └───resources
+```
+
+The interface created, we can now extend the created interface with the standard IDeSyDe interface `Module`:
+
+```
+package tutorial;
+
+import idesyde.core.Module;
+
+public interface ExampleModule extends Module {
+}
+```
+
+That is all there is to it. From now on, if there is anything (auto) registered to `ExampleModule`, it will be used later by IDeSyDe once a self-contained `jar` is produced.
+The self-contained `jar` can be achieved by adding the `shadowJar` plugin in the `build.gradle`:
+
+```
+plugins {
+    ...
+    id 'com.github.johnrengelman.shadow'
+    ...
+}
+```
+
+### Identification Rules
+
+An identification rule is realised in the Java world through a class that implements the interface `IdentificationRule`.
+For example, let's create a bare bones identification rule that does not identify anything;
+take special notive of the `@AutoRegister` annotation:
+
+```
+package tutorial;
+
+import idesyde.core.*;
+
+import java.util.Set;
+
+@AutoRegister(ExampleModule.class)
+public class ExampleIdentificationRule implements IdentificationRule {
+    @Override
+    public IdentificationResult apply(Set<? extends DesignModel> designModels, Set<? extends DecisionModel> decisionModels) {
+        return new IdentificationResult(Set.of(), Set.of());
+    }
+}
+```
+
+There three important items in this template:
+
+ 1. The `@AutoRegister(ExampleModule.class)` makes sure that the identification rule class `ExampleIdentificationRule` is auto-wired with the module in the final `jar`, so that IDeSyDe can use it in its runts.
+ 2. The `IdentificationResult` is a simple data container for a `Set` of new `DecisionModel`s and possible error/warning messages.
+ 3. You *must* implement the `IdentificationRule` interface for these function-wrapper classes; otherwise, the auto-wiring mechanism will generate uncompilable code.
+    In general, Java IDEs is quite good in telling you where the problem is even through you are generting code, but best to avoid these errors in a large codebase.
+
+The design models are the "models" that capture model-based or model-driven elements, e.g. a class wrapping [EMF models](https://eclipse.dev/modeling/emf/).
+The decision models are the ones which will contain any **non-decision** analysis results and extract information from design models.
+The non-decision part is not an enforced hard requirement: there is no hard checking from the programming side to ensure that you don't have decision-making being done
+during identification.
+However, if you do this breach of assumption, the identification process which is proven to be polynomial-bounded may suddenly become exponential;
+we would rather leave all the exponential decision-making to the exploration procedure.
+
+If you are following this tutorial without any prior IDeSyDe experience, likely you have no design or decision models to go ahead and fill the created
+identification rule, so we will address this first.
+
+### Design model
+
+For the sake of exemplification, we will assume that our design model of interest is [AMALTHEA](https://eclipse.dev/app4mc/).
+This means that we could create a design model wrapping the java files that already exist from AMALTHEA and simply use them directly.
+First, let our project consume the amalthea libraries from maven central:
+
+```
+dependencies {
+    ...
+    implementation 'org.eclipse.app4mc:org.eclipse.app4mc.amalthea.model:3.3.0' 
+    ...
+}
+```
+
+and then create the wrapper design model:
+
+```
+package tutorial;
+
+import idesyde.core.DesignModel;
+import org.eclipse.app4mc.amalthea.model.Amalthea;
+
+import java.util.Set;
+
+public record AmaltheaDesignModel(
+        Amalthea amaltheaModel
+) implements DesignModel {
+
+    @Override
+    public String category() {
+        return "AmaltheaDesignModel";
+    }
+
+    @Override
+    public String format() {
+        return "amxmi";
+    }
+}
+```
+
+where the `category` is an identifier so that other languages might be able to consume this design model (if necessary) from its "opaque" form.
+The opaqueness in this case is the DSI term for serialized in a standard format.
+Similarly, `format` describes the file format on disk for this design model, which is `amxmi` for XMI files exchanged in App4mc (AMALTHEA) applications.
+
 ## Rust embedded module