178 lines
5.4 KiB
ReStructuredText
178 lines
5.4 KiB
ReStructuredText
Getting started
|
|
====================
|
|
|
|
What is a consistency handling system ?
|
|
------------------------------------------------
|
|
|
|
.. questions:: Question
|
|
|
|
"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:`structure files <dictionaries>` (the term "dictionary" is also used as a synonym).
|
|
|
|
The structure files
|
|
---------------------
|
|
|
|
.. glossary::
|
|
|
|
structure file
|
|
dictionary
|
|
dictionaries
|
|
|
|
A dictionary or a a structure file 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 style (that is, in a YAML file).
|
|
|
|
Once the structure files are loaded by Rougail, the Tiramisu configuration management tool can check the consistency of the variables between them.
|
|
|
|
The YAML structure files format
|
|
------------------------------------
|
|
|
|
We need to learn first the specifics of the YAML dictionaries file format in Rougail, as well as some templating concepts.
|
|
|
|
Here is an empty Rougail dictionary YAML file
|
|
|
|
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_000/firefox/00-proxy.yml
|
|
:linenos:
|
|
:language: yaml
|
|
:caption: An empty Rougail dictionnary file. It's a YAML format.
|
|
:name: RougailDictionaryEmptyFile
|
|
|
|
..
|
|
---
|
|
version: 1.1
|
|
|
|
|
|
:download:`source file <https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_000/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
|
|
|
|
rougail -v 1.1
|
|
|
|
The variables
|
|
-----------------
|
|
|
|
Here is a :term:`structure file <dictionary>` example with a variable into it:
|
|
|
|
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml
|
|
:language: yaml
|
|
:caption: A Rougail dictionnary file with a variable named `proxy_mode`. It's the Rougail YAML dictionary format.
|
|
:name: RougailDictionaryFirstVariable
|
|
|
|
..
|
|
---
|
|
proxy_mode:
|
|
|
|
Here we declare a **variable** named `proxy_mode` without a 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_011/firefox/00-proxy.yml
|
|
:language: yaml
|
|
:caption: A Rougail dictionnary file with a variable named `proxy_mode`, with a description.
|
|
:name: RougailDictionaryFirstVariableDescription
|
|
|
|
..
|
|
---
|
|
proxy_mode:
|
|
description: Configure Proxy Access to the Internet
|
|
|
|
The same with a default value:
|
|
|
|
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_012/firefox/00-proxy.yml
|
|
:language: yaml
|
|
:caption: A Rougail dictionnary file with a variable named `proxy_mode`, with a default value.
|
|
:name: RougailDictionaryFirstVariableDefault
|
|
|
|
..
|
|
---
|
|
proxy_mode:
|
|
description: Configure Proxy Access to the Internet
|
|
default: No proxy
|
|
|
|
variable
|
|
|
|
A :term:`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.
|
|
|
|
Families of variables
|
|
--------------------------
|
|
|
|
family
|
|
|
|
A :term:`family` is simply a container of variables and subfamily.
|
|
|
|
.. _installation:
|
|
|
|
Installation
|
|
----------------
|
|
|
|
You just have to type this in your preferred terminal:
|
|
|
|
.. code-block:: text
|
|
|
|
pip install rougail
|
|
|
|
a better way to install the Rougail library in to do this in a virtual environment:
|
|
|
|
.. code-block:: text
|
|
|
|
python -m"venv' .venv
|
|
|
|
And, under linux or Mac:
|
|
|
|
.. code-block:: shell
|
|
|
|
./.venv/bin/activate
|
|
|
|
or, under windows:
|
|
|
|
.. code-block:: text
|
|
|
|
.venv\Scripts\activate.exe
|
|
|