403 lines
14 KiB
ReStructuredText
403 lines
14 KiB
ReStructuredText
Getting started
|
||
====================
|
||
|
||
.. objectives:: Objectives
|
||
|
||
We will learn how to:
|
||
|
||
- create a :term:`structure description file <structure file>`
|
||
- add a :term:`structure file <structure file>` format version in the structure file
|
||
- add a :term:`variable` in the structure file and set its default :term:`value`
|
||
|
||
.. prerequisites:: Prerequisites
|
||
|
||
- We assume that Rougail's library is :ref:`installed <installation>` on your computer.
|
||
- If you want to follow with this tutorial with the help of the corresponding :tutorial:`Rougail-tutorials git repository <>`,
|
||
this workshop page corresponds to the tags :tutorial:`v1.1_000 <src/tag/v1.1_000>` to :tutorial:`v1.1_011 <src/tag/v1.1_011>`
|
||
in the repository:
|
||
|
||
::
|
||
|
||
git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
|
||
git checkout v1.1_000
|
||
|
||
Creating a structure file
|
||
--------------------------
|
||
|
||
.. demo:: The folder structure
|
||
|
||
Here is the tree structure we want to have::
|
||
|
||
rougail-tutorials
|
||
└── firefox
|
||
└── 00-proxy.yml
|
||
|
||
- Let's make a :file:`rougail-tutorials` directory, with a :file:`firefox` subfolder.
|
||
- First, we will create a :term:`structure file <structure file>`, so let's create a :file:`00-proxy.yml` file
|
||
located in the :file:`firefox` subfolder.
|
||
|
||
This is an empty Rougail :term:`structure description file: <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 with only the YAML header and the version number
|
||
:name: RougailStructVersion
|
||
|
||
..
|
||
---
|
||
version: 1.1
|
||
|
||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_000/firefox/00-proxy.yml>`
|
||
|
||
This `version` specification is just the rougail YAML's format version specification.
|
||
By now, we have an empty structure file with the format specification in it.
|
||
|
||
Let's add our first variable
|
||
------------------------------
|
||
|
||
.. type-along:: For those who follow the tutorial with the help of the git repository
|
||
|
||
Now you need to checkout the `v1.1_001` version::
|
||
|
||
git checkout v1.1_001
|
||
|
||
|
||
- A variable is defined at a minimum by its name.
|
||
- A :term:`variable` lives in the :term:`structure description file <structure file>`.
|
||
|
||
Here we define a variable named `proxy_mode`:
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_001/firefox/00-proxy.yml
|
||
:language: yaml
|
||
:caption: A Rougail structure file with only one variable in it
|
||
:name: RougailDictionaryFirstVariableName
|
||
|
||
..
|
||
---
|
||
proxy_mode:
|
||
|
||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_001/firefox/00-proxy.yml>`
|
||
|
||
Let's run the Rougail CLI utility command in a terminal:
|
||
|
||
.. code-block:: text
|
||
:class: terminal
|
||
|
||
rougail -m firefox/
|
||
|
||
Well, we notice that we have an error:
|
||
|
||
.. raw:: html
|
||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_001/config/01/output_ro.html
|
||
:class: error-box
|
||
|
||
..
|
||
🛑 ERRORS
|
||
┣━━ The following variables are mandatory but have no value:
|
||
┗━━ - proxy_mode
|
||
|
||
It's because this first defined variable is :term:`mandatory` and needs to have a value set **but** there's no value yet.
|
||
|
||
We can therefore deduce the fact that:
|
||
|
||
.. admonition:: Fact
|
||
|
||
Once defined, an option configuration :term:`value` is :term:`mandatory`.
|
||
That is to say, it is absolutely necessary to assign a value to this variable.
|
||
|
||
Rougail waits for the `proxy_mode` configuration option's value to be set.
|
||
|
||
.. glossary::
|
||
|
||
mandatory
|
||
|
||
A variable is mandatory when a value is required, that is, `None` **is not** a possible value.
|
||
It **must** have a defined value.
|
||
|
||
.. seealso:: To go further, have a look at the :tiramisu:`mandatory option <glossary.html#term-mandatory-option>`
|
||
according to the :xref:`Tiramisu <tiramisu>` underlyning consistency system.
|
||
You will learn that it is actually possible to disable the mandatory property behavior,
|
||
but you need to declare it explicitely.
|
||
|
||
Describe the variable
|
||
-------------------------
|
||
|
||
Let's add a variable's description, which is not mandatory but which is usually a good practice.
|
||
|
||
.. type-along:: For those who follow the tutorial with the help of the git repository
|
||
|
||
Now you need to checkout the `v1.1_002` version::
|
||
|
||
git checkout v1.1_002
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_002/firefox/00-proxy.yml
|
||
:language: yaml
|
||
:caption: A Rougail structure file with a variable and a description
|
||
:name: RougailStructFirstVariableDescription
|
||
|
||
..
|
||
---
|
||
proxy_mode: # Configure Proxy Access to the Internet
|
||
|
||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_002/firefox/00-proxy.yml>`
|
||
|
||
You have two way to define a variable's description:
|
||
|
||
- the verbose way:
|
||
|
||
.. code-block:: yaml
|
||
|
||
proxy_mode:
|
||
description: Configure Proxy Access to the Internet
|
||
|
||
|
||
- or the compact way, using the "`#`" YAML notation:
|
||
|
||
.. code-block:: yaml
|
||
|
||
proxy_mode: # Configure Proxy Access to the Internet
|
||
|
||
Set a default value
|
||
---------------------
|
||
|
||
.. type-along:: For those who follow the tutorial with the help of the git repository
|
||
|
||
Now you need to checkout the `v1.1_003` version::
|
||
|
||
git checkout v1.1_003
|
||
|
||
We will learn different ways to set a value, the first way is setting a *default* value.
|
||
|
||
.. glossary::
|
||
|
||
default value
|
||
|
||
A default value is a variable value that is predefined, that's why this value is placed
|
||
right in the structure file.
|
||
|
||
Let's add a default value to this `proxy_mode` variable.
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/firefox/00-proxy.yml
|
||
:language: yaml
|
||
:caption: A rougail structure file with a default value for the variable
|
||
:name: RougailDictionaryVariableDefault
|
||
|
||
..
|
||
---
|
||
proxy_mode: No proxy # Configure Proxy Access to the Internet
|
||
|
||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_003/firefox/00-proxy.yml>`
|
||
|
||
.. admonition:: how to set a value -- the assignment
|
||
|
||
A default value has been set, great. This raises a question about what a normal value is.
|
||
|
||
Now then how can I assign a normal value to a variable?
|
||
|
||
.. type-along:: The different rougail roles and the default values
|
||
|
||
So far we have only talked about the one that writes the :term:`structure files <structure file>`\ . It's *role* is called the integrator's role.
|
||
|
||
.. glossary::
|
||
|
||
integrator
|
||
|
||
An integrator in the Rougail field is the person who writes the :term:`structure files <structure file>`\ .
|
||
He has the responsibilité of the integration process, that is,
|
||
defines the variables and the relationship between them, the variables that are allowed
|
||
(or not) to be set, and so on. His responsabilites are the **structuration** and the **consistency**
|
||
of the variables.
|
||
|
||
Now we will talk about the one that defines the values. It is called the operator.
|
||
|
||
.. glossary::
|
||
|
||
operator
|
||
|
||
An operator in the Rougail field is the person who assigns :term:`value`\ s to the pre-defined variables,
|
||
his responsabilities are to set variable values correctly.
|
||
|
||
The user :term:`value`\ s, that is the values that have been set by the operator, are of course type validated. The type validation is driven by the definitions in the :term:`structure file <structure file>`.
|
||
|
||
It is the operator's responsibility to set the user datas variables values.
|
||
The operator does not handle the structure files,
|
||
he is responsible of other files called the :term:`user data file`\ s.
|
||
|
||
.. glossary::
|
||
|
||
user datas
|
||
|
||
User datas, as opposed to structured datas, are datas that only concern the assignment of values
|
||
and not the consistency of the variables.
|
||
|
||
The variable's values are also called **user values**.
|
||
|
||
The consistency field is outside of the user datas scope.
|
||
The consistency is handled in the :term:`structured datas <structured data>`\ 's scope.
|
||
|
||
.. important:: If user datas are not set, default values are mandatory, otherwise Rougail will raise an error.
|
||
|
||
.. exercise:: Folder structure update
|
||
|
||
Now we add a :file:`config/config.yaml` file in our project::
|
||
|
||
rougail-tutorials
|
||
├── firefox
|
||
│ ├── 00-proxy.yml
|
||
└── config
|
||
└── config.yaml
|
||
|
||
.. type-along:: how to set a value in a user datas file
|
||
|
||
So for example if the integrator has not set any default value in his structure file,
|
||
it's up to the operator to do the job in the `config.yaml` file:
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/config/02/config.yml
|
||
:language: yaml
|
||
:caption: A Rougail user datas file :file:`config/config.yaml`, with a default value set.
|
||
:name: RougailConfigDefaultValue
|
||
|
||
..
|
||
---
|
||
proxy_mode: No proxy
|
||
|
||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_001/config/02/config.yaml>`
|
||
|
||
With the rougail CLI the operator has to add the `-u yaml -ff config/config.yaml` options:
|
||
|
||
.. code-block:: text
|
||
:class: terminal
|
||
:caption: A rougail Command Line Utility call with the :file:`config/config.yaml` Rougail user datas file
|
||
|
||
rougail -m firefox -u yaml -ff config/02/config.yaml
|
||
|
||
which gives us this output:
|
||
|
||
.. raw:: html
|
||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_001/config/02/output_ro.html
|
||
:class: output
|
||
|
||
..
|
||
<pre>╭──────── Caption ────────╮
|
||
│ Variable Modified value │
|
||
╰─────────────────────────╯
|
||
Variables:
|
||
<span style="color: #5c5cff">┗━━ </span>📓 proxy_mode: No proxy ◀ loaded from the YAML file "config/02/config.yaml"
|
||
</pre>
|
||
|
||
.. admonition:: Important fact
|
||
|
||
- the integrator works on structure files
|
||
- the operator works on user data files
|
||
|
||
Most of the time, the integrator and the operator are one and the same person, here we are talking about roles and not necessarily about people.
|
||
|
||
.. type-along:: Defining a choice type
|
||
|
||
In our firefox use case, the real type of the `proxy_mode` variable will be now set as a `choice` type:
|
||
|
||
.. seealso:: Have a look at the definition of the :term:`choice type variable <choice type>`
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/firefox/00-proxy.yml
|
||
:linenos:
|
||
:language: yaml
|
||
:caption: The real :file:`firefox/proxy.yml` Rougail structure file with a choice type
|
||
:name: RougailDictionaryChoiceType
|
||
|
||
..
|
||
---
|
||
proxy_mode:
|
||
description: Configure Proxy Access to the Internet
|
||
choices:
|
||
- No proxy
|
||
- Auto-detect proxy settings for this network
|
||
- Use system proxy settings
|
||
- Manual proxy configuration
|
||
- Automatic proxy configuration URL
|
||
default: No proxy
|
||
|
||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_004/firefox/00-proxy.yml>`
|
||
|
||
- Let's run the Rougail CLI
|
||
|
||
.. code-block:: text
|
||
:class: terminal
|
||
|
||
rougail -v 1.1 -m firefox/
|
||
|
||
We have an output like this one:
|
||
|
||
.. raw:: html
|
||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_004/config/01/output_ro.html
|
||
:class: output
|
||
|
||
..
|
||
<pre>╭────────────────────────── Caption ──────────────────────────╮
|
||
│ Variable <span style="color: #ffd700">Default value</span> │
|
||
│ <span style="color: #5c5cff">Undocumented variable</span> Modified value │
|
||
│ <span style="color: #ff0000">Undocumented but modified variable</span> (<span style="color: #00aa00">Original default value</span>) │
|
||
│ <span style="color: #ffaf00">Unmodifiable variable</span> │
|
||
╰─────────────────────────────────────────────────────────────╯
|
||
Variables:
|
||
<span style="color: #5c5cff">┗━━ </span>📓 proxy_mode: <span style="color: #ffd700">No proxy</span>
|
||
</pre>
|
||
|
||
The `proxy_mode` variable here, implicitely requires a value. It is a :term:`mandatory` variable.
|
||
|
||
As we set the `proxy_mode` variable as `No proxy` by default, we actually have specified a value, and the value appears in yellow, which means : "set by default".
|
||
|
||
The constraints that come with the `choice` type
|
||
----------------------------------------------------
|
||
|
||
We say that the `proxy_mode` variable is *constrained* (by the `choice` type).
|
||
|
||
We have the list of the possible (authorized) values:
|
||
|
||
- `No proxy`
|
||
- `Auto-detect proxy settings for this network`
|
||
- `Use system proxy settings`
|
||
- `Manual proxy configuration`
|
||
- `Automatic proxy configuration URL`
|
||
|
||
.. keypoints:: Key points progress
|
||
|
||
Indeed, in the Firefox configuration, it is possible to define several configuration modes, from no proxy at all (`no proxy`) to a kind of automatic configuration mode from a file (`set up proxy configuration from a file`).
|
||
|
||
|
||
**Keywords**
|
||
|
||
- :term:`structure file <structure file>`: structure description file
|
||
- :term:`variable`: an option's name which has a value
|
||
- a variable's description
|
||
- a variable's type
|
||
- a variable's default value
|
||
- the :term:`integrator` and :term:`operator` roles
|
||
- a mandatory value
|
||
- a choice type
|
||
|
||
**Progress**
|
||
|
||
To sum up, we have arrived at this point in writing a structure file like this:
|
||
|
||
**Structure description file**
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/firefox/00-proxy.yml
|
||
:linenos:
|
||
:language: yaml
|
||
:caption: A Rougail structure file with a variable named `proxy_mode`, with a default value.
|
||
|
||
..
|
||
|
||
.. raw:: text
|
||
|
||
---
|
||
proxy_mode:
|
||
description: Configure Proxy Access to the Internet
|
||
choices:
|
||
- No proxy
|
||
- Auto-detect proxy settings for this network
|
||
- Use system proxy settings
|
||
- Manual proxy configuration
|
||
- Automatic proxy configuration URL
|
||
default: No proxy
|
||
|