97 lines
3.6 KiB
ReStructuredText
97 lines
3.6 KiB
ReStructuredText
|
The structure files
|
||
|
|
=====================
|
||
|
|
|
||
|
|
Definition
|
||
|
|
------------
|
||
|
|
|
||
|
|
.. 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`.
|
||
|
|
|
||
|
|
|
||
|
|
The header of a structure file
|
||
|
|
-----------------------------------
|
||
|
|
|
||
|
|
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_000/firefox/00-proxy.yml
|
||
|
|
:language: yaml
|
||
|
|
:caption: An empty Rougail structure file.
|
||
|
|
:name: RougailStructureFirstVariableDescription
|
||
|
|
|
||
|
|
..
|
||
|
|
%YAML 1.2
|
||
|
|
---
|
||
|
|
version: 1.1
|
||
|
|
...
|
||
|
|
|
||
|
|
The structure file processing
|
||
|
|
----------------------------------
|
||
|
|
|
||
|
|
The structured files contain information that will be used by the consistency
|
||
|
|
handling system for structure validation.
|
||
|
|
|
||
|
|
.. figure:: images/schema.png
|
||
|
|
:alt: The Rougail process
|
||
|
|
:align: center
|
||
|
|
|
||
|
|
The Rougail process from structure files to Tiramisu valition handler object
|
||
|
|
|
||
|
|
The structured data
|
||
|
|
---------------------
|
||
|
|
|
||
|
|
.. glossary::
|
||
|
|
|
||
|
|
structured data
|
||
|
|
|
||
|
|
We sometimes call "structured datas" the datas that are defined in the structure files,
|
||
|
|
as opposed to :term:`user datas <user datas>`\ .
|
||
|
|
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.
|
||
|
|
|
||
|
|
What contains exactly a :term:`structure file`?
|
||
|
|
-------------------------------------------------
|
||
|
|
|
||
|
|
A :term:`structure file` is a YAML file whose structure is described in this documentation page.
|
||
|
|
|
||
|
|
A structure file contains a set of variables loaded into :term:`Tiramisu`, usable in your application, for example in a :term:`template`
|
||
|
|
to generate configuration files.
|
||
|
|
|
||
|
|
:term:`Families` and :term:`variables` can be defined in several structure files. These structure files are then aggregated.
|
||
|
|
|
||
|
|
If you want to see the contents of a structure file, you can have a look at the :ref:`tutorial with a real world sample. <tutorial>`
|
||
|
|
|
||
|
|
The default namespace
|
||
|
|
-------------------------
|
||
|
|
|
||
|
|
The families and variables contained in these structure files are ordered, by default, in the `rougail` namespace. It is possible to change the name of this namespace with the :term:`variable namespace <variable_namespace>` parameter of the :doc:`configuration <configuration>`.
|
||
|
|
|
||
|
|
This namespace is a bit special, it can access variables in another namespace.
|
||
|
|
|
||
|
|
The extra structure files
|
||
|
|
---------------------------
|
||
|
|
|
||
|
|
An extra is a different namespace. The idea is to be able to classify the variables by theme.
|
||
|
|
|
||
|
|
Extra namespaces must be declared :doc:`when configuring Rougail <configuration>`.
|
||
|
|
|
||
|
|
In this namespace we cannot access variables from another `extra` namespace.
|
||
|
|
On the other hand, it is possible to access the variable of the default namespace.
|