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