From 09fef78f9a6b732cfa03c36087fc8f7961e480b6 Mon Sep 17 00:00:00 2001
From: Niklas Kapelle <niklas@kapelle.org>
Date: Mon, 5 Aug 2024 14:39:16 +0200
Subject: [PATCH] added doc for applications

---
 doc/Concepts.md | 33 ++++++++++++++++++++++++++++++---
 1 file changed, 30 insertions(+), 3 deletions(-)

diff --git a/doc/Concepts.md b/doc/Concepts.md
index f6633f1..49c54b2 100644
--- a/doc/Concepts.md
+++ b/doc/Concepts.md
@@ -111,10 +111,9 @@ A collection of `Pixel` is called a `Canvas` which is nothing more than a 2D arr
 The concept of processes tryes to encapsulate programs. A process is basically an interface with the `run(handle: ProcessHandle)` method.
 The idea is that you can register all you disposable resources in the handle and they will be disposed when the process is killed or crashes.
 
-A process can be used as a command on the terminal or as a service. See [bin/HelloWorld.hx](../src/bin/HelloWorld.hx) for an example.
-Basically everything that runs and is not part of the kernel is a process.
+A process can be used as a command on the terminal or as a service. Basically everything that runs and is not part of the kernel is a process.
 
-~~In order for you program to be used it needs to be registered in the `BinStore` and the `DCEHack` manually. ~~
+More on that at [Applications](#applications). 
 
 # EndOfLoop
 
@@ -224,3 +223,31 @@ The follwing haxe flags can be used in the code or can be set in the makefile.
 
 - `debug`: Is set when debug
 - `kv_use_native`: If set use the native CC serialize and unserialize functions instead of the Haxe ones. See [KVStore.hx](../src/lib/KVStore.hx) for more.
+
+# Applications
+
+If you want to make an application you just need to create a class that implements IProcess and and has no arguments in the constructor. 
+In order to have the programm available from the terminal you need to add the `Binstore.includeBin` macro for the class. Here is an example:
+
+```haxe
+@:build(macros.Binstore.includeBin("HelloWorld", ["hello", "helloworld"]))
+class HelloWorld implements IProcess {
+	public function new() {}
+
+	public function run(handle:ProcessHandle) {
+        handle.writeLine("Hello World");
+        handle.close(true);
+    }
+}
+```
+
+Let's break this down:
+
+- The `includeBin` macro is required to automaticly inlcude the app and to defeat the DCE optimisation. In early versions refections were used but DCE did not like that
+- The first argument on `includeBin` is the name of the app. Only ever used in displaying.
+- The second argument are the aliases. These are used to call the app from the terminal and other places
+- The constructor can't have any arguments. It's also recommended to not do any major setup stuff in there. 
+- The `run` method is the entry point in the app.
+- The handle is used to interact with the outside world. (theoretically at least)
+- The `handle.close(true)` call is required to end a process. The app does not end when the run function is finished. The first arguments represents if the app was successfull. 
+