Mercurial > bitten > bitten-test

comparison doc/configure.txt @ 599:b76e6accad72

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
0.6dev: Added Configuration documentation. It contains all configuration information I've found in the wiki and source code.
author osimons
date Thu, 30 Jul 2009 09:47:48 +0000
parents
children 4dc38daaeca0
comparison
equal deleted inserted replaced
598:5f3e66e5b451 599:b76e6accad72
1 .. -*- mode: rst; encoding: utf-8 -*-
2
3 =============
4 Configuration
5 =============
6
7 While the `Recipe`_ contains the instructions for how to build,
8 configurations are used to determine what gets built and any runtime
9 parameters used when building.
10
11 .. _recipe: recipe.html
12
13 .. contents:: Contents
14 :depth: 2
15 .. sectnum::
16
17 Target platforms
18 ================
19
20 A target platform is something like 'NetBSD x86' or 'Win32 Java 1.4'.
21
22 Technically, a target platform is a named set of rules against which the
23 properties of build slaves are matched. Each rule is a regular expression
24 matching a particular slave property, such as the operating system
25 or the processor. When a slave connects to the build master, it sends a
26 registration message that includes information about the slave.
27
28 A build configuration must have at least one target platform assigned to
29 it before it becomes fully active.
30
31 Slave Properties
32 ================
33
34 By default, the following properties are included:
35
36 :`family`: The basic type of operating system, typically “posix” for
37 Unix-like systems and “nt” for Win32 systems.
38 :`os`: The name of the operating system (for example “Darwin”,
39 “Linux” or “Windows”).
40 :`version`: The operating system version.
41 :`machine`: The hardware platform (for example “i686” or “Power Macintosh”).
42 :`processor`: The processor architecture (for example “athlon” or “powerpc”).
43
44 Note that not all of these properties may be available for all platforms,
45 depending on OS and Python version.
46
47 Examples
48 --------
49
50 To set up a target platform, create rules that are checked against the
51 properties of the slave. For example, a target platform that matches slave
52 running Linux on x86 would look like this:
53
54 +------------+------------------------------------+
55 + Property | Expression |
56 +============+====================================+
57 | `os` | `^Linux` |
58 +------------+------------------------------------+
59 | `machine` | `^[xi]\d?86$` |
60 +------------+------------------------------------+
61
62 A target platform that matches any slaves running on Windows might look
63 like this:
64
65 +------------+------------------------------------+
66 + Property | Expression |
67 +============+====================================+
68 | `family` | `^nt$` |
69 +------------+------------------------------------+
70
71 The build master will request a build from at most one slave for every
72 target platform. So, for example, if there are three slaves connected that
73 are matching 'NetBSD x86', only one of them will perform the build of a
74 specific revision. Slaves that match a particular target platform are
75 treated as if they were completely interchangable.
76
77 If a slave connects that doesn't match any of the configured target platforms,
78 the build master will reject its registration.
79
80 Slave Configuration
81 ===================
82
83 When a build slave registers with a build master, it sends information about
84 the machine the slave is running on, and what software it has available.
85 While some of this information can be automatically discovered by the slave,
86 other information may need to be configured explicitly. Also, a slave instance
87 may want to override some of the automatically computed attributes,
88 for example to enable cross-compilation.
89
90 There are three categories of information that can be configured for a slave:
91
92 :`os`: Properties of the operating system
93 :`machine`: Properties of the underlying hardware
94 :`packages`: Various pieces of software, like a language runtime or a library
95
96 Configuration File Format
97 -------------------------
98
99 For simple manual editing, the slave configuration file will be based on
100 the ``'INI'`` file format known from Windows, which is also frequently used by
101 Python applications.
102
103 The file is included at runtime using a slave command-line option::
104
105 bitten-slave -f config.ini
106
107 A configuration file is partitioned into named sections. There are two
108 predefined sections named ``[machine]`` and ``[os]``. If you supply them in
109 your configuration file they should include the following sections.
110
111 .. code-block:: ini
112
113 [os]
114 name = Darwin
115 version = 8.1.0
116 family = posix
117
118 [machine]
119 name = levi
120 processor = Power Macintosh
121
122 There may be any number of additional sections, where each section corresponds
123 to a software package. For example:
124
125 .. code-block:: ini
126
127 [dbxml]
128 version = 2.1.8
129
130 [python]
131 version = 2.3.5
132 path = /usr/bin/python2.3
133
134 The build slave sends this package information as part of the build initiation,
135 which when using verbose logging (``bitten-slave -v``) will display a debug
136 message 'Sending slave configuration:' followed by:
137
138 .. code-block:: xml
139
140 <slave name="host.domain">
141 <platform processor="Power Macintosh">levi</platform>
142 <os version="8.1.0" family="posix">Darwin</os>
143 <package name="dbxml" version="2.1.8" />
144 <package name="python" version="2.3.5" path="/usr/bin/python23" />
145 </slave>
146
147 The name of the slave can only be set as command-line option::
148
149 bitten-slave --name=myhost
150
151 Commands using Properties
152 -------------------------
153
154 A number of commands_ support runtime settings using a slave configuration
155 file. The example of ``python.path`` above is one such example, where all
156 Python commands will use the specified executable for running commands.
157
158 The documentation for commands_ should include information about all
159 runtime settings.
160
161 .. _commands: commands.html
162
163 Properties in Build Configurations
164 ----------------------------------
165
166 Defined properties can be used in a build configuration to match slaves
167 against target platforms. For example, the following rule would match any slave
168 providing 'Berkeley DB XML' version 2.x::
169
170 dbxml.version ~= /^2\.\d\.\d.*/
171
172 The properties are accessible in dotted notation, where the part before the dot
173 is the package name, and the part after the dot is the name of the property.
174
175 Property Interpolation in Build Recipes
176 ---------------------------------------
177
178 Property values can be interpolated into build recipes_ as well, so individual
179 slaves can parameterize how their build is perfomed. For example, given the
180 following build recipe excerpt:
181
182 .. code-block:: xml
183
184 <svn:checkout url="http://svn.example.org/repos/myproject/"
185 path="${repository.branch}" revision="${revision}"/>
186
187 .. _recipes: recipes.html
188
189 Slaves may control which part of the repository is checked out and tested
190 with a configuration file excerpt like this one:
191
192 .. code-block:: ini
193
194 [repository]
195 branch = /branches/0.3-testing
196
197 Authentication
198 ==============
199
200 Authentication information can also be included in slave configuration file:
201
202 .. code-block:: ini
203
204 [authentication]
205 username = myusername
206 password = mypassword
207
208 The authentication information will be removed as soon as it is read
209 by the slave, and will not be passed to the master as active configuration.
Copyright (C) 2012-2017 Edgewall Software