1Test::AutoBuild::ModuleU(s3e)r Contributed Perl DocumentaTteisotn::AutoBuild::Module(3)
2
6 Test::AutoBuild::Module - represents a code module to be built
7
9 use Test::AutoBuild::Module;
10 my $module = Test::AutoBuild::Module->new(name => $name,
12 label => $label,
13 sources => $sources,
14 [dependencies => \@modules,]
15 [env => \%env,]
16 [options => \%options,]
17 [groups => \@groups,]
18 [dir => $directory]);
19 $module->build();
21 $module->install();
22
24 The Test::AutoBuild::Module module provides a representation of a sin‐
25 gle code module to be built / tested.
26
28 The valid configuration options for the "modules" block are
29
31 my $module = Test::AutoBuild::Module->new(name => $name, label =>
32 $label, sources => $sources, [depends => \@modules,] [links =>
33 \%links,] [artifacts => \%artifacts,] [env => \%env,] [options =>
34 \%options,] [groups => \@groups,] [dir => $directory]);
35 Creates a new code module object. "name" is a alphanumeric token
36 for the name of the module. "label" is a short human friendly title
37 for the module. "depends" is an array ref containing a list of
38 dependant module names. "env" is a hash ref of environment vari‐
39 ables to define when building the module. "groups" is the optional
40 list of groups to which the module belongs. "dir" is the directory
41 in which the module was checked out, if different from "name". The
42 "controlfile" parameter is the name of the build control file to
43 run if different from the global default.
44 my $label = $module->label([$newlabel]);
46 Returns the label of this module, a short human friendly title. If
47 the "newlabel" parameter is supplied the label is also updated.
48 my $name = $module->name([$newname]);
50 Returns the name of this module, a short alphanumeric token. If the
51 "newname" parameter is supplied the name is also updated.
52 my $sources = $module->sources($newsources)
54 Returns an array references, where each element is as hash with two
55 keys. The value associated with the key "repository" is the name of
56 the soruce repository. The value associated with the key "path" is
57 the path within the source repository to checkout. If the $new‐
58 sources parameter is supplied, the list of sources is updated
59 my $path = $module->dir($newpath);
61 Returns the path for the directory checked out of source control.
62 Typically this is the same as the module name. If the "newpath"
63 parameter is supplied the dir is updated.
64 my \@modules = $module->depends([\@modules]);
66 Returns an array ref of dependant module names. If the "modules"
67 parameter is supplied then the list of dependants is updated.
68 my $value = $module->option($name[, $newvalue]);
70 Returns the value of the option referenced by "name". If the "new‐
71 value" parameter is supplied, then the option is also updated.
72 Options are arbitrary key + value pairs intended for stages to use
73 for configuring module specific options. For example the
74 Test::AutoBuild::Stage::Build module uses the "control-file" option
75 key to allow override of the shell script used to perform a build.
76 To avoid clashes between multiple different stages, try to use rea‐
77 sonably description option key names, preferrably at least 2 words
78 long.
79 my $bool = $module->is_installed($dir);
81 Returns a true value if this modules files are installed into the
82 directory $dir.
83 $module->install($runtime, $dir);
85 Installs all this module's files from a previously populated build
86 cache, into the directory $dir. If any dependant modules have not
87 yet been installed, they will be installed first.
88 $module->test_status($name);
90 Retrieves the status of the test called $name. The status will be
91 one of the "success", "failed", "cached". If there is no test
92 called $name, an error will be thrown.
93 $module->test_output_log_file($name);
95 Retrieves the name of the logfile into which console output for the
96 test called $name should be saved. The logfile name will be rela‐
97 tive to the runtime's log root directory.
98 $module->test_result_log_file($name);
100 Retrieves the name of the logfile into which formal results for the
101 test called $name should be saved. The logfile name will be rela‐
102 tive to the runtime's log root directory.
103 my $seconds = $module->test_start_date($name);
105 Retrieves the timestamp at which the test called $name began execu‐
106 tion. If no test called $name has been run yet, an error will be
107 thrown.
108 my $seconds = $module->test_end_date($name);
110 Retrieves the timestamp at which the test called $name completed
111 execution. If no test called $name has been run yet, an error will
112 be thrown.
113 my @names = $module->tests
115 Retrieves the list of all known test names which have been executed
116 for this module.
117 my $status = $module->build_status;
119 Retrieves the status of the module build. If the module has not yet
120 been built, it will return 'pending'; if the build has been run it
121 will return one of 'success', 'failed', or 'cached'; if the mod‐
122 ule's build was skipped due to a dependant module failing, the sta‐
123 tus will be 'skipped'.
124 $module->build_output_log_file();
126 Retrieves the name of the logfile into which console output for the
127 build process should be saved. The logfile name will be relative to
128 the runtime's log root directory.
129 $module->build_result_log_file();
131 Retrieves the name of the logfile into which results for the build
132 process unittests should be saved. The logfile name will be rela‐
133 tive to the runtime's log root directory.
134 my $seconds = $module->test_start_date();
136 Retrieves the timestamp at which the build process began execution.
137 If the build has not run yet, an undefined value will be returned.
138 my $seconds = $module->test_end_date();
140 Retrieves the timestamp at which the build process completed execu‐
141 tion. If the build has not run yet, an undefined value will be
142 returned.
143 my $status = $module->checkout_status;
145 Retrieves the status of the module SCM checkout. If the module has
146 not yet been checked out, it will return 'pending'; Ff the checkout
147 has been run it will return one of 'success', 'failed'. If it was
148 'success' then the "changes" method will return a list of change‐
149 sets.
150 $module->checkout_output_log_file();
152 Retrieves the name of the logfile into which console output for the
153 checkout process should be saved. The logfile name will be relative
154 to the runtime's log root directory.
155 my $seconds = $module->test_start_date();
157 Retrieves the timestamp at which the checkout process began execu‐
158 tion. If the checkout has not run yet, an undefined value will be
159 returned.
160 my $seconds = $module->test_end_date();
162 Retrieves the timestamp at which the checkout process completed
163 execution. If the checkout has not run yet, an undefined value will
164 be returned.
165 my $stauts = $module->status
167 Retrieves the overall status of this module. If the module failed
168 to checkout from SCM, then the SCM status is returned. If the mod‐
169 ule build failed, is pending, or was skipped, then this returns
170 'failed', 'pending', or 'skipped' respectively; If any test script
171 failed, this returns 'failed'; otherwise it returns 'success'.
172 my @paths = $module->paths($repository)
174 Returns the list of source paths to be checked out from the reposi‐
175 tory $repository. If there are no paths associated with that repos‐
176 itory, returns an empty list.
177 my $status = $module->invoke_shell($runtime, $controlfile, $logfile,
179 \@args);
180 This method spawns a shell, and executes the command $controlfile
181 saving its combined stdout/stderr output to the file $logfile. The
182 command will have @args passed as command line arguments, and will
183 be run in the context of the environment returned by the
184 "get_shell_env" method. The return value of this method will be
185 zero upon success, otherwise it will return the exit status of the
186 command. Before invoking the command $controlfile the current
187 directory will be changed to the directory returned by the "dir"
188 method beneath the runtime's source root. Any errors encountered
189 while trying to spawn the shell, or invoke the command will also be
190 logged in the file given by the $logfile parameter.
191 $module->run_task($runtime, $taskname, $controlfile);
193 This method runs a task named $taskname by invoking the shell com‐
194 mand $controlfile in the source directory for this module. The
195 taskname must either be "build" or be prefixed by the string
196 "test-". If the taskname is build then after execution any files
197 created in the install root will be recorded as installed files -
198 later available by invoking the "installed" method. Likewise any
199 files created in the package root, matching known package types
200 will be recorded as generated packages - later available by invok‐
201 ing the "packags" method. The start and end times of the task,
202 along with its success/failure status will be record and later
203 available from the corresponding "build_XXX" or "test_XXX" methods
204 matching the $taskname. The controfile will be invoked with a sin‐
205 gle command line argument, which is the full path to a file into
206 which formal test results should be saved. Regular, free format,
207 build / test output will automatically be captured to an alternate
208 log file.
209 $module->cachable_run_task
211 This is a wrapper around the "run_task" method which makes use of
212 the currently configured Test::AutoBuild::ArchiveManager to cache
213 successfull invocations of a task. On subsequent invocations, pro‐
214 vided there have been no source code checkout changes since the
215 previous archive, and no dependant modules have been re-built, the
216 archived result will be restored, rather than invoking the task
217 again. From the caller's POV, there should be no functional differ‐
218 ence between "cachable_run_task" and "run_task", with the exception
219 that the former will be alot faster if the archive is used.
220 $module->unarchive_result($runtime, $cache, $taskname)
222 This method restores the result of the task $taskname from an old
223 archive $cache. $cache will be a subclass of the "Test::Auto‐
224 Build::Archive" module. If the taskname is "build", then the log
225 files, build results, intalled files, generated packages, and
226 source changelogs will all be restored. If the taskname is prefixed
227 by "test-", then the log files and test results will be restored.
228 my $bool = $module->archive_usable($runtime, $archive, $taskname)
230 Returns a true value, if the archive $archive contains a usable
231 saved entry for the task $taskname. An archive for a module's task
232 is defined to be usable if all dependant modules are also usable;
233 if the archive contains a bucket with the name $taskname; if the
234 status of the save task is "success" or "cached"; and if no source
235 code changes have been made.
236 $module->archive_result($runtime, $archive, $taskname)
238 This method saves the result of the task $taskname to a new archive
239 $archive. $archive will be a subclass of the "Test::AutoBuild::Ar‐
240 chive" module. If the taskname is "build", then the log files,
241 build results, intalled files, generated packages, and source
242 changelogs will all be saved. If the taskname is prefixed by
243 "test-", then the log files and test results will be saved.
244 $module->build($runtime, $controlfile);
246 Runs the build task, by invoking the shell command $controlfile in
247 the source directory of this module. Refer to the "run_task" and
248 "invoke_shell" methods for further details of the context of execu‐
249 tion. Results and information about the task can later be invoking
250 the various "build_XXX" methods.
251 $module->test($runtime, $testname, $controlfile);
253 Runs a test task with the name $testname, by invoking the shell
254 command $controlfile in the source directory of this module. Refer
255 to the "run_task" and "invoke_shell" methods for further details of
256 the context of execution. Results and information about the task
257 can later be retrieved passing the $testname to the various
258 "test_XXX" methods.
259 my $bool = $module->should_skip($runtime);
261 Determines if execution of tasks for this module should be skipped.
262 A module should be skipped, if any of its dependant modules have a
263 value returned by their "build_status" methods of 'failed', 'pend‐
264 ing' or 'skipped'.
265
267 Daniel Berrange <dan@berrange.com>
268
270 Copyright (C) 2002-2004 Daniel Berrange <dan@berrange.com>
271
273 perl(1), Test::AutoBuild::Runtime, Test::AutoBuild::Repository,
274 Test::AutoBuild::Stage
275perl v5.8.8 2007-12-09 Test::AutoBuild::Module(3)