Merge branch 'master' of ssh://git.labs.libre-entreprise.org/gitroot/tiramisu
[tiramisu.git] / 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 to set up compiler options, and so on. it became quite annoying to hand the
10 necessary options to where they are actually used and even more annoying to add
11 new options. To circumvent these problems the configuration management was
12 introduced...
13
14 What is Tiramisu ?
15 ===================
16
17 Tiramisu is an options handler and an options controller, wich 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.
22
23 Last but not least, options can be reached and changed according to the access
24 rules from nearly everywhere in your appliance.
25
26 Just the facts
27 ==============
28
29 .. _gettingtiramisu:
30
31 Download
32 ---------
33
34 To obtain a copy of the sources, check it out from the repository using `git`.
35 We suggest using `git` if one wants to access the current developments.
36
37 ::
38
39     git clone git://git.labs.libre-entreprise.org/tiramisu.git
40
41 This will get you a fresh checkout of the code repository in a local directory
42 named ``tiramisu``.
43
44 Getting started
45 -------------------
46
47 Option objects can be created in different ways. Let's perform very basic
48 :class:`~tiramisu.option.Option` and :class:`~tiramisu.config.Config` object
49 manipulations:
50
51 ::
52
53     >>> from tiramisu.config import Config
54     >>> from tiramisu.option import OptionDescription, BoolOption
55     >>> descr = OptionDescription("optgroup", "", [
56     ...     BoolOption("bool", "", default=False)])
57     >>>
58     >>> c = Config(descr)
59     >>> #┬ánow we have a container, wich contains an option:
60     >>> c.bool
61     False
62     >>> c.bool = True
63     >>> c.bool
64     True
65
66
67 So by now, we have
68
69 - a namespace (which is `c` here)
70 - the access of an option's value by the
71   attribute access way (here `bool`, wich is a boolean option:
72   :class:`~tiramisu.option.BoolOption()`.
73
74 So, option objects are produced at the entry point and then handed down to
75 where they are actually used. This keeps options local but available everywhere
76 and consistent.
77
78 The namespace is created, we can set a `read_write` access to the options::
79
80     >>> c.read_write()