From 51d5648cc32fc0ae6289fba64e052d6b19dbe081 Mon Sep 17 00:00:00 2001
From: niamtokik <niamtokik@localhost>
Date: Thu, 18 Jun 2020 06:31:08 +0000
Subject: [PATCH] update documentation

---
 README.md     | 81 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 c_src/erluv.c |  2 --
 2 files changed, 80 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 61cde34..d2a5a2d 100644
--- a/README.md
+++ b/README.md
@@ -2,8 +2,87 @@
 
 erluv library implementation based on c-node.
 
-# build
+## build
+
+to build the erlang code:
 
 ```sh
 rebar3 compile
 ```
+
+to build the C code:
+
+```sh
+# on OpenBSD
+cd c_src
+alias make="make -f Makefile.openbsd"
+make
+```
+
+## test
+
+```sh
+rebar3 eunit
+rebar3 ct
+```
+
+## goal
+
+ - fully implement libuv on erlang
+
+ - create a portable interface
+ 
+ - create strong abstraction
+ 
+ - use specific functions/lib based on different systems
+ 
+## design
+
+erluv supports 3 implementations, the default one is with c-node, and
+permits to create a really strong isolation between different
+context. The c-node is a slave and will receive the action to execute
+on the underlying system.
+
+```txt
+  ___________     _________________________
+ |           |   |                         |
+ | main node |   | different user context  |
+ |___________|   |   ________ __________   |
+ |           |   |  |        |          |  |
+ | erluv_app |<-----| c-node | liberluv |  |
+ |___________|   |  |________|__________|  |
+                 |           |          |  |
+                 |           | system   |  |
+                 |           |__________|  | 
+                 |               _| |_     |
+                 |               \   /     |
+                 |            ____\ /___   |
+                 |           |          |  |
+                 |           | process  |  |
+                 |           |__________|  |
+                 |_________________________|
+```
+
+The two other implementation are using `liberluv` as erlang nif and
+ports. Those two are not recommanded due to the lack of isolation. In
+case of nif and ports implementation, you can't use privilege
+separation even with `sudo` or `doas`.
+
+## Issues
+
+ * OpenBSD: both erlang package (erlang-19 and erlang-21) present in
+   the ports tree don't export `ei.h` headers. 
+   
+ * OpenBSD: support on OpenBSD can, at this time, only be made for
+   erlang-19 and erlang-21. Ports erlang-22 and erlang-23 are in
+   progress state.
+   
+ * libuv: is not thread safe. That means we need to isolate the
+   communication between the different subprocesses managed by c-node,
+   nif and ports.
+
+## Resources
+
+ * http://docs.libuv.org/en/v1.x
+ 
+ * https://erlang.org/doc/apps/erl_interface/ei_users_guide.html
diff --git a/c_src/erluv.c b/c_src/erluv.c
index b4c48ee..5438139 100644
--- a/c_src/erluv.c
+++ b/c_src/erluv.c
@@ -1,7 +1,5 @@
 /* copyright (c) 2020 Mathieu Kerjouan <contact@steepath.eu>
  *
- * http://docs.libuv.org/en/v1.x
- * https://erlang.org/doc/apps/erl_interface/ei_users_guide.html
  */
 #include <stdio.h>
 #include <stdlib.h>