doc/getting-started.txt

   1 ==================================
   2 Getting started
   3 ==================================
   4
   5 What is options handling ?
   6 =================================
   7
   8 Due to more and more available options required to set up an operating system,
   9 compiler options or whatever, it became quite annoying to hand the necessary
  10 options to where they are actually used and even more annoying to add new
  11 options. To circumvent these problems the configuration control was
  12 introduced...
  13
  14 What is Tiramisu ?
  15 ===================
  16
  17 Tiramisu is an options handler and an options controller, which aims at
  18 producing flexible and fast options access. The main advantages are its access
  19 rules and the fact that the whole consistency is preserved at any time, see
  20 :doc:`consistency`. There is of course type and structure validations, but also
  21 validations towards the whole options. Furthermore, options can be reached and
  22 changed according to the access rules from nearly everywhere in your appliance.
  23
  24 Just the facts
  25 ==============
  26
  27 .. _gettingtiramisu:
  28
  29 Download
  30 ---------
  31
  32 To obtain a copy of the sources, check it out from the repository using `git`.
  33 We suggest using `git` if one wants to access to the current developments.
  34
  35 ::
  36
  37     git clone git://git.labs.libre-entreprise.org/tiramisu.git
  38
  39 This will get you a fresh checkout of the code repository in a local directory
  40 named ``tiramisu``.
  41
  42 Getting started
  43 -------------------
  44
  45 Option objects can be created in different ways. Let's perform very basic
  46 :class:`~tiramisu.option.Option` and :class:`~tiramisu.config.Config` object
  47 manipulations:
  48
  49 ::
  50
  51     >>> from tiramisu.config import Config
  52     >>> from tiramisu.option import OptionDescription, BoolOption
  53     >>> # let's create a group of options... with only one option inside
  54     >>> descr = OptionDescription("optgroup", "", [
  55     ...     BoolOption("bool", "", default=False)])
  56     >>> # c is a namespace as well as a container for the options
  57     >>> c = Config(descr)
  58     >>> c.bool
  59     False
  60     >>> c.bool = True
  61     >>> c.bool
  62     True
  63
  64 So by now, we have:
  65
  66 - a namespace (which is `c` here)
  67 - the access of an option's value by the
  68   attribute access way (here `bool`, which is a boolean option
  69   :class:`~tiramisu.option.BoolOption()`.
  70
  71 So, option objects are produced at the entry point `c` and then handed down to
  72 where they are actually used when `c.bool` is triggered. This keeps options
  73 local but available at any timer and consistent.
  74
  75 Once the namespace is created, we can set a
  76 :meth:`~config.CommonConfig.read_write()` access to the options::
  77
  78     >>> c.read_write()
  79
  80 which enables us to set a bunch of access rules that we wil explain later in
  81 :doc:`status`.