1AUTO-BUILD.CONF(5) User Contributed Perl Documentation AUTO-BUILD.CONF(5)
2
6 auto-build.conf - Test-AutoBuild configuration file
7
9 The "auto-build.conf" file contains the configuration information for a
10 build instance. It is used to define general metadata such as the host
11 name of build machine, the administrator / developer email addresses,
12 email alerts; the parameters for accessing source control repositories;
13 the modules to be checked out from source control and built.
14 The configuration file is processed by the Config::Record(3pm) module,
16 so refer to that manual page for formal syntax rules. Prior to loading
17 it is also run through the Template(3pm) module - the
18 Template::Manual::Syntax(3pm) manual page details the syntax for the
19 pre-processor. The pre-processor is most useful if there are a large
20 number of modules to be defined, each with pretty much identical
21 configuration parameters.
22
24 The example configuration file contains inline comments summarizing
25 important points, however, the full details are as follows:
26 HOST DETAILS
28 engine = /etc/auto-build.d/engine/host-build.conf
29 The fully qualified path to the build engine definition. There is
30 only one build engine setup currently provided, so this can be left
31 on its default setting of "/etc/auto-build.d/engine/host-main.conf"
32 At a later date extra engines will be provided for doing builds
33 with chroot, or virtual machines.
34 templateDir = /etc/auto-build.d/templates
36 The fully qualified path to the directory containing template files
37 for the HTML status pages, RSS feed and email alerts. The template
38 files are all processed using the "Template(3pm)" module, so refer
39 to the "Template::Manual::Syntax(3pm)" manual page for details on
40 the syntax.
41 buildRoot = /var/lib/builder
43 The path to the directory within which the build instance will
44 operate. This directory should previously have been populated with
45 pre-requisite sub-dirs by running the "auto-build-make-root(1)"
46 script. The RPM install "perl-Test-AutoBuild-account" installs the
47 correct directory structure under "/var/lib/builder", so if the
48 build host only needs to run a sigle instance of the builder, this
49 parameter can be left unchanged.
50 label = Continous Automatic Builder
52 A short descriptive name for this build configuration. This label
53 is used as the page title for HTML status pages, the subject in the
54 email alerts, and the title of the RSS feed.
55 adminEmail = admin@example.com
57 The email address for the person responsible for administering the
58 build instance.
59 adminName = Build Administrator
61 The name of the person responsible for administering the build
62 instance.
63 groupEmail = dev@example.com
65 The email address for the development team whose software is being
66 built. This would typically be the address of the main developers
67 mailing list.
68 groupName = Build Developers
70 The name of the development team whose software is being built, or
71 alternatively the name of the developers mailing list.
72 hostname = example.com
74 When the build host has multiple hostname aliases configured (for
75 virtual hosting), specifies the preferred hostname for accessing
76 the FTP / HTTP sites. This is used for generating links within the
77 email alerts and RSS feeds.
78 httpPrefix = /~builder
80 The URL path prefix under which the HTML status pages are
81 accessible. If using the "/etc/auto-build.d/http/aliased.conf" HTTP
82 config file, then this would be set to "/builder". If the user.conf
83 HTTP config file is used, then this would be set to "/~builder".
84 Finally, if the vhost.conf HTTP config file is used, then this is
85 simply set to the empty string.
86 lockMethod = fcntl
88 The method used for acquiring a lock file to prevent multiple build
89 instances running at the same time against the same buildRoot
90 directory.
91 fcntl
93 This is the best option, but is only implemented for Linux,
94 SunOS and FreeBSD. It correctly protects from multiple build
95 instances running against a single build root, even if the
96 build root is on NFS and accessed from multiple hosts.
97 flock
99 This is more portable than "fcntl", working on any UNIX
100 platform, but it does not protect a NFS hosted build root from
101 being accessed by multiple hosts.
102 file
104 This uses a simple file creation/deletion test. The downside is
105 that if the build engine or host machine crashes, it will be
106 neccessary to manually delete the lock file
107 ($buildRoot/.build.mutex) before the builder will run again.
108 FEATURES
110 There are various features available in the build engine workflow which
111 can be turned on/off as desired. They are all contained within a nested
112 "features" block.
113 cache = 1
115 If the cache is enabled, then modules will only be built if their
116 sources have changed since the previous build cycle. This provides
117 much faster cycle times if there are many modules in the build
118 config, only a few of which ever change
119 checkout = 1
121 Whether to try and checkout the latest sources from version control
122 If checkout is disabled, the build will run with whatever sources
123 #were checked out on the previous cycle.
124 createrepo_index = 1
126 Whether to run the 'createrepo' tool against the RPMs on the HTTP
127 distribution site. The XML metadata files created are used by
128 package update tools such as Yum for resolving dependancies between
129 RPMs.
130 yum_index = 1
132 Whether to run the 'yum-arch' tool against the RPMs on the HTTP
133 distribution site. This tool is now deprecated in favour of the
134 'createrepo' tool, so this module is only provided for backwards
135 compatability with old YUM versions.
136 apt_index = 1
138 Whether to generate an APT index of RPMs / Debian packages on the
139 HTTP distribution site.
140 email_alerts = 1
142 Whether to send email alerts at the end of each build cycle. The
143 alerts contain details of which modules successfully built, or
144 failed to build.
145 EMAIL ALERTS
147 The parameters for email alerts are grouped within a nested
148 configuration block with the name "alert". For example
149 alert = {
151 ...parameters..
152 }
153 scope = builder
155 The scope can be either "builder" in which case a single email is
156 sent containing details of all modules, or it can be "module" in
157 which case a separate email is sent for each module. This latter
158 option is useful in the case where a single builder instance is
159 building modules maintained by a number of distinct development
160 teams.
161 trigger = first-fail
163 The trigger defines the conditions under which an alert will be
164 generated. If the trigger is "always", alerts will be sent on
165 every build cycle. If the trigger is "fail", alerts will be sent
166 whenever the a module fails to build. If the trigger is
167 "first-fail", alerts will be sent the first time a module fails,
168 but no further alerts will be sent until the module has been fixed.
169 This latter option prevents a single coding error, generating a
170 long series of duplicated build alerts.
171 to = group
173 This specifies the recipient of the email alerts. It can either be
174 an explicit email address, or one of two "magic" addresses. The
175 first magic address is "admin" which is substituted by the value of
176 the "adminEmail" configuration parameter. The second magic address
177 is "group" which is substituted by the value of the "groupEmail"
178 configuration parameter.
179 from = builder@example.com
181 This specifies the address to use in the "From:" field of the
182 email.
183 smtpServer = mail.example.com
185 If the build host machine is not running an SMTP relay process on
186 port 25, then this parameter is required to specify the hostname of
187 the STMP sever to relay alerts via.
188 CACHE LIMITS
190 If the "cCache" feature is set to 1, then various files and pieces of
191 metadata are cached across build cycles. Since disk space is a finite
192 resource it is neccessary to limit the size of the cache. The suitable
193 size will depend on the size of particular modules being built. The
194 cache should be sized such that the output of at least 1 complete cycle
195 be saved.
196 maxCacheSize = 100M
198 The maximum size of the cache, can be specified in megabytes by
199 postfixing the letter "M", or in gigabytes by postfixing the letter
200 "G".
201 maxCacheAge = 7d
203 The maximum age sets a limit on how long a cache will be considered
204 valid, before a module is forced to be re-built from scratch.
205 GLOBAL ENVIRONMENT
207 The nested "env" configuration block provides the ability to specify
208 arbitrary environment variables which will be set whenever the build
209 engine executes a command.
210 env = {
212 ENV-NAME = ENV-VALUE
213 ...
214 }
215 SOURCE REPOSITORIES
217 For large development projects, multiple projects will be checked out
218 for building from a single source repository. Thus, the parameters
219 required to access particular source repositories are defined
220 separately to the modules themselves. The definition is within the
221 nested "repositories" block.
222 repositories = {
224 repo-name = {
225 ...repository params...
226 }
227 }
228 The available repository configuration parameters are:
230 label = Repository Name
232 The arbitrary descriptive name for the repository, used to identify
233 repositories in the HTML status pages.
234 type = cvs
236 Specifies the source control tool used to access files within the
237 repository. There are many source control tools supported
238 cvs The CVS repository type requires that the command "cvs" be
240 present in the $PATH. The "CVSROOT" environment variable should
241 be set in the "env" configuration block to identify the
242 location of the repository. For remote repositories it may also
243 be neccessary to specify the "CVS_RSH" environment variable.
244 For example
245 env = {
247 CVSROOT = :pserver:anonymous@cvs.gna.org:/cvs/testautobuild
248 }
249 p4 The Perforce repository type requires that the command "p4" be
251 present in the $PATH. The "P4CONFIG" environment variable
252 should to set to point to a client view. The paths in the view
253 spec will be filled in automatically by the build engine. For
254 example
255 env = {
257 P4CONFIG = /var/lib/builder/.p4config
258 }
259 tla The GNU Arch repository type requires that the command "tla" be
261 present in the $PATH. The 'archive-name' and 'archive-uri'
262 options should be set to identify the remote repository. For
263 example
264 options = {
266 archive-name = lord@emf.net--2004
267 archive-uri = http://arch.quackerhead.com/~lord/archives/lord@emf.net--2004
268 }
269 hg The Mercurial repository type requires that the command "hg" be
271 present in the $PATH. Additionally, it must be at least version
272 0.7 or later. The 'base-url' option should be set to identify
273 the base URL under which the repositories are located. For
274 example
275 options = {
277 base-url = http://www.selenic.com/
278 }
279 git The GIT repository type requires that the command "git" be
281 present in the $PATH. Additionally, it must be at least version
282 1.5.0.0 or later. The 'base-url' option should be set to
283 identify the base URL under which the repositories are located.
284 For example
285 options = {
287 base-url = git://anongit.freedesktop.org/git/
288 }
289 bzr The Bazaar repository type requires that the command "gbzr" be
291 present in the $PATH. Additionally, it must be at least version
292 0.91 or later. The 'base-url' option should be set to identify
293 the base URL under which the repositories are located. For
294 example
295 options = {
297 base-url = http://www.darcs.net/repos/
298 }
299 mtn The Monotone repository type requires that the command "mtn" be
301 present in the $PATH. Additionally, it must be at least version
302 0.37 or later. The 'server' option should be set to identify
303 the hostname & port number at which the repository is located.
304 For example
305 options = {
307 server = guitone.thomaskeller.biz
308 }
309 The module path will simply be the name of the branch to
311 checkout
312 darcs
314 The Darcs repository type requires that the command "darcs" be
315 present in the $PATH. Additionally, it must be at least version
316 1.0.0 or later. The 'base-url' option should be set to identify
317 the base URL under which the repositories are located. For
318 example
319 options = {
321 base-url = http://www.darcs.net/repos/
322 }
323 svn The Subversion repository type requires that the command "svn"
325 be present in the $PATH. The 'url' option should be set to
326 identify the base URL at which the repository is accessed.
327 options = {
329 url = http://aplaws.redhat.com/svn/aplaws/
330 }
331 svk The SVK repository type requires that the command "svk" be
333 present in the $PATH. It (currently) requires no special
334 options to be set, rather expecting the modules to specify
335 their full checkout URL. This will, however, likely change in
336 the future.
337 disk
339 The local disk repository type bypasses all version control,
340 allowing source files to be simply copied straight from another
341 directory. The 'directory' otion to refer to the base directory
342 containing the source files.
343 options = {
345 directory = /var/lib/builder/local-files
346 }
347 options
349 The nested "options" configuration block is used to set parameters
350 which are specific to each repository type. Refer to the
351 description of the "type" parameter for details of what options are
352 valid for a particular type.
353 env The nested "env" configuration block is used to set environment
355 variables which are specific to each repository type. Refer to the
356 description of the "type" parameter for details of what variables
357 are relevant for a particular type.
358 MODULES
360 The modules block is where the applications / tools / libraries to be
361 built are defined. The definitions for each module are within the
362 nested "modules" block:
363 modules = {
365 module-name = {
366 ...module params...
367 }
368 }
369 label = Module name
371 This defines a free text display name for the module, and will be
372 used in email alerts, web status pages & related areas.
373 admin-email = admin@example.com
375 Define the email address of a module-specific build administrator.
376 If this is omitted, it defaults to the global administrator email
377 address.
378 admin-name = Module Administrator
380 Define a name for the module-specific administrator. As with the
381 "admin-email", if this is omitted, the global administrator name is
382 used as a default.
383 group-email = developers@example.com
385 Define the email address of a mailing list for the module specific
386 development team. If this is omitted, it defaults to the global
387 developers email address.
388 group-name = Module developers
390 Define a name for the module-specific development team. If this is
391 omitted it defaults to the global development team name.
392 source
394 The nested "source" block defines the location from which the
395 source code for the module will be checked out.
396 source = {
398 ... source location options ...
399 }
400 There are two entries required to be presented in the "source"
402 block:
403 repository = gna-cvs
405 This defines the name of the repository from which the source
406 will be checked out. This repository must be defined earlier in
407 the configuration file.
408 path = /testautobuild
410 This defines the path from which to check out the module. The
411 syntax for the path varies depending on the type of repository,
412 and will typically be specified relative to the root of the
413 repository.
414 env The nested "env" configuration block provides the ability to
416 specify arbitrary environment variables which will be set whenever
417 the build engine executes a command for this module.
418 env = {
420 ENV-NAME = ENV-VALUE
421 ...
422 }
423 links
425 The nested "links" configuration block defines a list of
426 'interesting' hyperlinks pertaining to this module. No functional
427 interpretation is placed on the links, they are simply passed
428 through to the HTML template engine when generating the status
429 pages. It is common to provide links to the project's homepage, and
430 a URL for browsing the source code online.
431 links = (
433 {
434 ...first link...
435 }
436 {
437 ... second link...
438 }
439 )
440 Within the block for each link, there are two required entries:
442 href
444 The fully-qualified URL for the link, which will typically be
445 used in the "href" tag of an HTML hyperlink.
446 label
448 The free-text string to use as the title of the link - the text
449 a user will click on to follow the link.
450 groups
452 The nested "groups" configuration block defines the list of groups
453 of which the module is a member. The entries in the list are simply
454 names of groups defined earlier in the configuration block. The
455 group membership is primarily used to control generation of the
456 HTML pages.
457 groups = (
459 group-name-a
460 group-name-b
461 ...
462 )
463 artifacts
465 The nested "artifacts" configuration block defines a list of build
466 artifacts to publish to the distribution servers. A build artifact
467 can be anything which is generated during the course of a build,
468 test logs, documentation files, code coverage reports. Each entry
469 in the artifacts list is a block with the following keys
470 src = blib/html/*
472 The path to the source files for the artifact, relative to the
473 module's build root. The source can be a file, a directory, or
474 a BSD glob.
475 dst = apidocs/
477 The destination path at which to publish the artifacts, if the
478 source is a file, this parameter will be treated as a filename.
479 If the source is a glob, or directory, this parameter will be
480 treated as the base directory.
481 path = apidocs/Test/AutoBuild.html
483 An optional parameter providing an alternate link to the
484 published artifacts. This is useful if the web server does not
485 allow directory browsing, and there is no index.html file.
486 label = API Documentation
488 The label to use when displaying a link to the artifacts.
489 CD ISO IMAGES
491 XXX
492
494 engine = /etc/auto-build.d/engine/main.conf
495 templateDir = /etc/auto-build.d/templates
496 buildRoot = /var/lib/builder
498 label = Continous Automatic Builder
500 adminEmail = admin@example.com
502 adminName = Build Administrator
503 groupEmail = dev@example.com
505 groupName = Build Developers
506 hostname = example.com
508 httpPrefix = /~builder
509 lockMethod = fcntl
511 features = {
513 cache = 1
514 checkout = 1
515 createrepo_index = 1
516 yum_index = 1
517 apt_index = 1
518 email_alerts = 1
519 }
520 alert = {
522 scope = builder
523 trigger = first-fail
524 to = group
525 from = builder@example.com
526 smtpServer = mail.example.com
527 }
528 maxCacheSize = 100M
530 maxCacheAge = 7d
531 groups = {
533 software = {
534 label = Software
535 }
536 autobuild = {
537 label = Test-AutoBuild
538 }
539 docs = {
540 label = Documentation
541 }
542 }
543 env = {
545 USER = builder
546 }
547 repositories = {
549 gna-cvs = {
550 label = GNA Anonymous CVS Server
551 type = cvs
552 env = {
553 CVSROOT = :pserver:anonymous@cvs.gna.org:/cvs/testautobuild
554 }
555 }
556 }
557 modules = {
559 autobuild-dev = {
560 label = Test AutoBuild Unstable
561 admin-email = autobuild-admin@example.com
563 admin-name = Module Administrator
564 group-email = autobuild-dev@example.com
565 group-name = Module Developers
566 source = {
568 repository = gna-cvs
569 path = testautobuild
570 }
571 env = {
573 HTMLURLPREFIX = /~builder/artifacts/autobuild-dev/apidocs
574 }
575 groups = (
577 autobuild
578 software
579 )
580 links = (
582 {
583 href = http://www.autobuild.org/
584 label = Homepage
585 }
586 {
587 href = http://cvs.gna.org/viewcvs/testautobuild/testautobuild/
588 label = Browse CVS Repository
589 }
590 )
591 artifacts = (
593 {
594 src = README
595 dst = README
596 label = Readme
597 }
598 {
599 src = blib/coverage/*
600 dst = coverage/
601 label = Code Test & POD coverage Reports
602 }
603 {
604 src = blib/html/*
605 dst = apidocs/
606 path = apidocs/Test/AutoBuild.html
607 label = Module API documentation
608 }
609 )
610 }
611 }
612 isos = {
614 autobuild-unstable = {
615 name = autobuild-unstable.iso
616 label = Test-AutoBuild Unstable
617 packageTypes = (
619 rpm
620 zip
621 )
622 modules = (
624 autobuild-dev
625 )
626 }
627 }
628
630 /etc/auto-build.d/templates/* - templates for HTML status pages & email alerts
631 /etc/auto-build.d/engine/*.conf - definitions for build engine runtime setup
632 /etc/auto-build.d/httpd/*.conf - example apache configuration files
633 /etc/auto-build.d/cron/*.conf - example crontab entries for automating builder
634 /var/lib/builder - default build working directory
635
637 auto-build(1), Config::Record(3pm), Template(3pm)
638
640 Daniel P. Berrange <dan@berrange.com>
641perl v5.12.1 2007-12-17 AUTO-BUILD.CONF(5)