153 lines
5.2 KiB
ReStructuredText
153 lines
5.2 KiB
ReStructuredText
Getting started
|
|
====================
|
|
|
|
.. _installation:
|
|
|
|
Installation
|
|
----------------
|
|
|
|
- Open a shell session
|
|
|
|
.. type-along:: Optional: install the Rougail library in a virtual environment
|
|
|
|
- install the virtual environment: `python -m"venv' .venv`
|
|
- activate it `./.venv/bin/activate` (or `.venv\Scripts\activate.exe` under windows)
|
|
|
|
.. type-along:: Rougail's library installation
|
|
|
|
You can use the `pip` python installer, here is the install command:
|
|
|
|
.. code-block:: text
|
|
|
|
pip install rougail
|
|
|
|
What is a consistency handling system ?
|
|
------------------------------------------------
|
|
|
|
.. questions:: Rougail, Tiramisu: What is it all about?
|
|
|
|
**Question**: OK, I have understood that the Rougail library allows me to take advantage of the :xref:`tiramisu` consistency handling library. But what is all this for? What is exactly a consistency handling system? And again, what is this :xref:`Tiramisu library <tiramisu library>` used for?
|
|
|
|
**Answer**: Well, we will explain in details what this :xref:`tiramisu` library is and what Rougail is.
|
|
|
|
In (very) short:
|
|
|
|
- Rougail is the YAML consistency description of a :term:`context`\ 's situation
|
|
- Tiramisu is the consistency engine linter
|
|
|
|
.. glossary::
|
|
|
|
Tiramisu
|
|
|
|
:xref:`tiramisu` is a consistency handling system that has initially been designed
|
|
in the configuration management scope. Until now,
|
|
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:`variables <variable>` and :term:`families <family>`.
|
|
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.
|
|
There can be a lot of structure files located in many different folders.
|
|
|
|
Rougail reads all the structure files and loads them into a single object
|
|
that represents the whole :term:`context`.
|
|
|
|
.. figure:: images/schema.png
|
|
:alt: The Rougail process
|
|
:align: center
|
|
|
|
The Rougail process from structure files to Tiramisu object
|
|
|
|
.. glossary::
|
|
|
|
structured data
|
|
|
|
We sometimes call 'structured datas' the datas that are in the structure files,
|
|
as opposed to :term:`user datas <user data>`\ .
|
|
For example when a value of a variable is defined in the structured datas, that is
|
|
in a structured file, the assigned value's status is that the variable's value is a default value.
|
|
If the assigned value of the variable is defined in a user data file,
|
|
it is an user assigned value.
|
|
|
|
We'll see later on some examples of default values and user assigned values.
|
|
|
|
The main advantage of all of this 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`
|
|
|