141 lines
4.3 KiB
ReStructuredText
141 lines
4.3 KiB
ReStructuredText
Getting started
|
|
====================
|
|
|
|
.. _installation:
|
|
|
|
Installation
|
|
----------------
|
|
|
|
You can use the python installer and type the install command 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
|
|
|
|
|
|
What is a consistency handling system ?
|
|
------------------------------------------------
|
|
|
|
.. questions:: Question
|
|
|
|
**Question**: OK, I have understood that the Rougail library enables me to take advantage of the :xref:`tiramisu` library. 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 documentation <tiramisu>`.
|
|
|
|
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 <structure file>`.
|
|
|
|
The structure files
|
|
---------------------
|
|
|
|
.. glossary::
|
|
|
|
structure file
|
|
|
|
A structure file in the Rougail meaning is a YAML file that describes variables
|
|
and their dependencies / consistencies.
|
|
There can be a lot of structure 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 variables
|
|
-----------------
|
|
|
|
Here is a :term:`structure file` example with only a variable **variable** named `proxy_mode`
|
|
A variable can be defined with no default value at all.
|
|
|
|
.. 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/ore some subfamilies.
|
|
|
|
Here how a YAML structure file with a family looks like:
|
|
|
|
.. code-block:: yaml
|
|
:caption: A :file:`hello.yml` structure sample file
|
|
|
|
---
|
|
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`
|
|
|