cuper/README.md

# Cuper (DRAFT)
## RIZ file header
```plain
                         32 bits
    <---------------------------------------------->
              16 bits                       8 bits
    <---------------------->            <---------->
    +----------------------------------------------+  <----------------------+
  0 |                IDENTIFICATOR                 |                         |
    +----------------------------------------------+                         |
  1 |          ARCH        |          OS           |                         |
    +----------------------------------------------+                         |
  2 |                     TIME                     |                         |
    +----------------------------------------------+                         |
  3 |          TYPE        |   PROT.   |    VER    |    Base informations.   |
    +----------------------------------------------+       Frame 0-9         |
  4 |           HL         |          MDL          |       + OPTIONS.        |
    +----------------------------------------------+                         |
5-9 |                   RESERVED                   |                         |
    +----------------------------------------------+                         |
    |                   OPTIONS                    |  <----------------------+
    +----------------------------------------------+  <----------------------+
    |                   METADATA                   |                         |
    +----------------------------------------------+         Contents.       |
    |                   PAYLOAD                    |   Frame post-OPTIONS-n. |
    +----------------------------------------------+  <----------------------+
```

**Description**

| Nom du champ | Position | Longeur (bits) | Valeur(s) |
|:-------------|:--------:|:--------------:|:----------|
| **Identificator** | 0 | 32 | `0x7f 0x52 0x49 0x5a` |
| **Arch** | 4 | 16 | `0x0000` = no arch |
|||| `0x0001` = i386 |
|||| `0x0002` = x86_64 |
| **OS** | 6 | 16 | `0x0000` = no OS |
|||| `0x0001` = Linux |
| **Time** | 8 | 32 | *current timestamp* |
| **Type** | 12 | 16 | `0x0000` = container |
|||| `0x0001` = meta container |
| **Protected** | 14 | 8 | `0x00` = unprotected |
|||| `0x01` = AES-128 |
|||| `0x02` = AES-192 |
|||| `0x04` = AES-256 |
| **Version** | 15 | 8 | `0x00` = first (current) |
| **HL** | 16 | 16 | `0x000a` = no options |
| **MDL** | 18 | 16 | `0x0000` = no metadata |
| **RESERVED** | 20 | 120 | `0x0000` = not used |

* **ARCH**: l'identifiant de la machine cible (architecture du processeur).
* **OS**: l'identifiant de la machine cible (environnement d'execution).
* **TIME**: le timestamp de compilation.
* **TYPE**: le type de conteneur, ex: conteneur, méta-conteneur, etc...
* **VER**: la version de l'entête.
* **HL**: la taille de l'entête en **mot de 32 bits**.
* **MDL**: la taille des méta-données en **mot de 32 bits**.
* **RESERVED**: 20 octets réservés.
* **OPTIONS**: des données optionnels.
* **METADATA**: les informations du contenu (see Cupfile).
* **PAYLOAD**: le contenu.

> **NOTE**:
* Si `TYPE` égale `1d` (`0001h`), alors il n'y à pas de contenu.
* Si `HL` égale `10d` (`000ah`), alors il n'y à pas d'options.
* Si `MDL` égale `0d` (`0000h`), alors il n'y à pas de méta-données.

## Cupfile
Le fichier **Cupfile** permet de **rassembler des informations** qui seront utilisés lors de la compilation.

Voici la structure d'un Cupfile:
```plain
+-------------------->
|                      VAR1 = value1
|   User variables.    VAR2 = value2
|                      VAR3 = value3
+-------------------->
|                      ([add:] | set:)X-CONST1 = value1
|     Constantes.      ([add:] | set:)X-CONST2 = value2
|                      ([add:] | set:)X-CONST3 = value3
+-------------------->
+--------------------> (2x LF: `0x0a 0x0a` or 2x CRLF: `0x0d 0x0a 0x0d 0x0a`)
+--------------------> `exec` executable_file [arguments]
```

Le Cupfile doit se situer à la raçine de votre projet, exemple:
```plain
reader:
    |-- .git/
	|-- test/
		`-- text.txt
	|-- python-windows-x86_64/
		|-- libraries.dll
		`-- python.exe
    |-- python-linux-x86_64/
        |-- libraries.so
        `-- python
    |-- Cupfile
    `-- main.py
```

Voici un exemple de Cupfile, ce conteneur permet l'execution d'un script Python, en incluant toutes les dépendances:
```bash
AUTOR = Maiuri Gaëtan <maiuri.gaetan@lessonsharing.fr>
DATE = 2017-09-22
DESCRIPTION = A simple Cuper container with a text reader.
X-ENV = ["set:VERBOSE=1", "LD_LIBRARY_PATH=$_CWD/python-linux-x86_64/"] # LD_LIBRARY_PATH=... => is equivalent of add:LD_LIBRARY_PATH=...
X-INCLUDES = ["python-linux-x86_64/", "main.py"]

exec ./python-linux-x86_64/python main.py -v -i myfile.txt
```

### Exemple avec des dépendances
Vous pouvez gérer **une liste de dépendances** avec l'attribut `X-DEPLIST`, exemple:

```plain
reader:
    |-- .git/
	|-- test/
		`-- text.txt
    |-- Cupfile
    `-- main.py
```

```bash
AUTOR = Maiuri Gaëtan <maiuri.gaetan@lessonsharing.fr>
DATE = 2017-09-22
DESCRIPTION = A simple Cuper container with a text reader.
X-DEPLIST = ["https://riz.example.com/download/python-linux-x86_64.riz"]
X-ENV = ["set:VERBOSE=1", "LD_LIBRARY_PATH=$_CWD/python-linux-x86_64/"] # LD_LIBRARY_PATH=... => is equivalent of add:LD_LIBRARY_PATH=...
X-INCLUDES = ["main.py"]

exec ./python-linux-x86_64/python main.py -v -i myfile.txt
```

## Constantes internes
Des constantes internes sont utilisable dans le Cupfile, afin de formater dynamiquement votre environnement d'execution.

> **NOTE**: Ces constantes ne sont pas modifiable.

| Non | Type | Description | Exemple |
|-----|:----:|-------------|---------|
| `$_CWD` | string | Le chemin du dossier courant post-extraction | `/path/to/riz/contents` |
| `$_HOME` | string | Le chemin du dossier utilisateur (de la machine cible) | `/home/batman` or `C:\Users\batman` |

## Attributs d'extension
Les attributs d'extension permettent d'injecter des intructions à la compilation.

| Non | Type | Description | Exemple |
|-----|:----:|-------------|---------|
| `X-DEPLIST` | array | Inject des dépendances a télécharger avant extraction (sur la machine cible) | `["http://example.com/riz/my-scripts.riz", "http://example.com/riz/my-libs.riz"]` |
| `X-ENV` | array | Inject des variables d'environnement dans le contexte d'execution (sur la machine cible) | `["VERBOSE=1", "LD_LIBRARY_PATH=libs/"]` |
| `X-INCLUDES` | array | Inclure seulement ces fichiers/dossiers dans le conteneur | `["myfile", "mydir/"]` |

L'attribut `X-DEPLIST` peut être grandement utile lors de la création d'un méta-conteneur.