tiramisu/doc/getting-started.txt

==================================
Getting started
==================================

What is options handling ?
=================================

Due to more and more available options required to set up an operating system,
compiler options or whatever, it became quite annoying to hand the necessary
options to where they are actually used and even more annoying to add new
options. To circumvent these problems the configuration control was
introduced...

What is Tiramisu ?
===================

Tiramisu is an options handler and an options controller, which aims at
producing flexible and fast options access. The main advantages are its access
rules and the fact that the whole consistency is preserved at any time, see
:doc:`consistency`. There is of course type and structure validations, but also
validations towards the whole options. Furthermore, options can be reached and
changed according to the access rules from nearly everywhere in your appliance.

Just the facts
==============

.. _gettingtiramisu:

`tiramisu`\ 's home page is here_

.. _here: https://forge.cadoles.com/Cadoles/tiramisu

Download
---------


To obtain a copy of the sources, check it out from the repository using `git`.
We suggest using `git` if one wants to access to the current developments.

::

    git clone https://forge.cadoles.com/Cadoles/tiramisu.git

This will get you a fresh checkout of the code repository in a local directory
named ``tiramisu``.

Getting started
-------------------

Option objects can be created in different ways. Let's perform very basic
:class:`~tiramisu.option.Option` and :class:`~tiramisu.config.Config` object
manipulations:

::

    >>> from tiramisu.config import Config
    >>> from tiramisu.option import OptionDescription, BoolOption
    >>> # let's create a group of options... with only one option inside
    >>> descr = OptionDescription("optgroup", "", [
    ...     BoolOption("bool", "", default=False)])
    >>> # c is a namespace as well as a container for the options
    >>> c = Config(descr)
    >>> c.bool
    False
    >>> c.bool = True
    >>> c.bool
    True

So by now, we have:

- a namespace (which is `c` here)
- the access of an option's value by the
  attribute access way (here `bool`, which is a boolean option
  :class:`~tiramisu.option.BoolOption()`.

So, option objects are produced at the entry point `c` and then handed down to
where they are actually used when `c.bool` is triggered. This keeps options
local but available at any timer and consistent.

Once the namespace is created, we can set a
:meth:`~config.CommonConfig.read_write()` access to the options::

    >>> c.read_write()

which enables us to set a bunch of access rules that we wil explain later in
:doc:`status`.