234 lines
7.3 KiB
ReStructuredText
234 lines
7.3 KiB
ReStructuredText
Getting started
|
||
====================
|
||
|
||
What is a consistency handling system ?
|
||
------------------------------------------------
|
||
|
||
.. questions::
|
||
|
||
"OK, I have understood that the Rougail stuff enables me to take advantage of :xref:`tiramisu`.
|
||
|
||
But what is all this for?
|
||
|
||
What is exactly a consistency handling system?
|
||
|
||
And again, what is this :xref:`tiramisu` library used for?"
|
||
|
||
*Answer*: Well, now we explain what this :xref:`tiramisu` library is, and how we are using it.
|
||
|
||
.. glossary::
|
||
|
||
Tiramisu
|
||
|
||
:xref:`tiramisu` is a consistency handling system that has initially been designed
|
||
in the configuration management scope. To put it more simply,
|
||
this library is generally used to handle configuration options.
|
||
|
||
It manages variables and group of variables. In the Tiramisu scope we call
|
||
it *options* and *option descriptions*.
|
||
|
||
Here is the :xref:`tiramisu library`.
|
||
|
||
In the Rougail scope, we call it :term:`variable`\ s and :term:`families`.
|
||
In Rougail, the families and variables are located in the :term:`dictionaries`.
|
||
|
||
And this is what we are going to explain in this page.
|
||
|
||
The dictionaries
|
||
---------------------
|
||
|
||
.. glossary::
|
||
|
||
dictionary
|
||
dictionaries
|
||
|
||
A dictionary in the Rougail meaning is a YAML file that describes variables
|
||
and their dependencies / consistencies.
|
||
There can be a lot of dictionary files located in many different folders.
|
||
|
||
Rougail reads all the dictionaries and loads them into a single object
|
||
that handles the variables consistency.
|
||
|
||
.. image:: images/schema.png
|
||
|
||
The main advantage is that declaring variables and writing consistency is as simple
|
||
as writing YAML. With Rougail it is not necessary to write :term:`Tiramisu` code any more.
|
||
It simplifies a lot of things.
|
||
|
||
And rather than writing :term:`Tiramisu` code, we can declare variables and describe the relationships between variables in a declarative mode (that is, in a YAML file).
|
||
|
||
Once the dictionaries are loaded by Rougail, we find all the power of the :term:`Tiramisu` configuration management tool.
|
||
|
||
The YAML dictionaries format
|
||
-----------------------------
|
||
|
||
Before getting started with Rougail we need to learn the specifics of the YAML dictionaries file format (as well as some templating concepts).
|
||
|
||
.. todo:: parler de jinja https://jinja.palletsprojects.com
|
||
|
||
Here is an empty rougail dictionary YAML file
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_001/firefox/00-proxy.yml
|
||
:linenos:
|
||
:language: yaml
|
||
:caption: An empty rougail dictionnary file. It's a YAML format.
|
||
:name: RougailDictionaryEmptyFile
|
||
|
||
:download:`source file <https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml>`
|
||
|
||
You can see that there is just a `version` specification.
|
||
|
||
.. glossary::
|
||
|
||
version
|
||
|
||
The version is here a Rougail YAML dictionary version format.
|
||
It is set in the beginning of a YAML dictionary, or globaly in the Rougail settings
|
||
for example from the command line
|
||
|
||
.. note:: You can set the format in the Rougail command line tool like this:
|
||
|
||
.. code-block:: bash
|
||
|
||
foo@bar:~$ rougail -v 1.1
|
||
|
||
The variables
|
||
-----------------
|
||
|
||
Here is a :term:`dictionary` example with a variable into it:
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_003/firefox/00-proxy.yml
|
||
:linenos:
|
||
:language: yaml
|
||
:caption: A rougail dictionnary file with a variable named `proxy_mode`. It's the Rougail YAML dictionary format.
|
||
:name: RougailDictionaryFirstVariable
|
||
|
||
:download:`source file <https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_003/firefox/00-proxy.yml>`
|
||
|
||
Here we declare a **variable** named `proxy_mode` without a :term:`default value`.
|
||
A variable can be defined with no default value at all.
|
||
|
||
Here is the same variable with a description label:
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/firefox/00-proxy.yml
|
||
:linenos:
|
||
:language: yaml
|
||
:caption: A rougail dictionnary file with a variable named `proxy_mode`, with a description.
|
||
:name: RougailDictionaryFirstVariableDescription
|
||
|
||
The same with a default value:
|
||
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_005/firefox/00-proxy.yml
|
||
:linenos:
|
||
:language: yaml
|
||
:caption: A rougail dictionnary file with a variable named `proxy_mode`, with a default value.
|
||
:name: RougailDictionaryFirstVariableDefault
|
||
|
||
variable
|
||
|
||
A variable is a declaration unit that represents a business domain metaphor,
|
||
the most common example is that a variable that represents a configuration option
|
||
in a application, but a variable represents something more that a configuration option.
|
||
It provides a business domain specific representation unit.
|
||
|
||
.. todo:: définir une variable avec une description, un type, l'inférence de type,
|
||
les notations condensées,
|
||
une family sans variable doit avoir un type: family,
|
||
|
||
.. note:: Dictionaries can just define a list of variables, but we will see that
|
||
we can specify a lot more. We can define variables **and** their relations,
|
||
**and** the relations between them.
|
||
|
||
In the next step, we will explain through a tutorial how to construct a list of variables.
|
||
|
||
Families of variables
|
||
--------------------------
|
||
|
||
.. glossary::
|
||
|
||
family
|
||
families
|
||
|
||
A family of variables is simply a collection of variables that refer to
|
||
the same business model category. It's just a variables container.
|
||
Think of it as a container as well as a namespace.
|
||
|
||
A "hello world" with Rougail
|
||
------------------------------
|
||
|
||
We're gonna make the simplest possible example.
|
||
|
||
.. prerequisites:: Prerequisites
|
||
|
||
We assume that Rougail's library is installed on your computer (or in a virtual environment).
|
||
|
||
.. exercise:: Hello world's workshop
|
||
|
||
Here is the tree structure we want to have::
|
||
|
||
workplace
|
||
├── dict
|
||
│ ├── hello.yml
|
||
└── hello.py
|
||
|
||
- Let's make a :file:`workplace` directory, with a :file:`dict` subfolder.
|
||
- First, we need a :term:`dictionary`, so let's make the :file:`hello.yml` file
|
||
which is located in the :file:`dict` subfolder, with the following content:
|
||
|
||
.. code-block:: yaml
|
||
:caption: The `hello.yaml` file
|
||
|
||
---
|
||
version: '1.1'
|
||
hello:
|
||
default: world
|
||
|
||
.. todo:: mettre un appel à la CLI pour lancer le truc
|
||
|
||
We launch the script:
|
||
|
||
.. code-block:: bash
|
||
|
||
python hello.py
|
||
|
||
And we obtain the following result:
|
||
|
||
.. code-block:: python
|
||
|
||
{'rougail.hello': 'world'}
|
||
|
||
**Congratulations ! You have successfully completed your first Rougail script.**
|
||
|
||
A "Hello, <name> " sample with a family
|
||
------------------------------------------
|
||
|
||
Let's continuing on our "Hello world" theme and add a :term:`family` container.
|
||
|
||
.. code-block:: yaml
|
||
:caption: the :file:`hello.yml` file
|
||
:linenos:
|
||
|
||
---
|
||
version: '1.1'
|
||
world:
|
||
description: Hello world family container
|
||
name:
|
||
description: Somebody to say hello
|
||
default: rougail
|
||
|
||
Here, we have a family named `world`.
|
||
This family contains a variable named `name`
|
||
|
||
Again, let's validate this YAML file against Rougail's API:
|
||
|
||
.. code-block:: bash
|
||
|
||
python hello.py
|
||
|
||
We then have the output:
|
||
|
||
.. code-block:: python
|
||
|
||
{'rougail.world.name': 'rougail'}
|
||
|