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
25 single 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
39 variables to define when building the module. "groups" is the
40 optional list of groups to which the module belongs. "dir" is the
41 directory in which the module was checked out, if different from
42 "name". The "controlfile" parameter is the name of the build
43 control file to 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
58 $newsources 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
71 "newvalue" 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
77 reasonably description option key names, preferrably at least 2
78 words 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
97 relative 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
102 relative 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
106 execution. If no test called $name has been run yet, an error will
107 be 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
122 module's build was skipped due to a dependant module failing, the
123 status 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
133 relative 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
141 execution. 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
149 changesets.
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
158 execution. If the checkout has not run yet, an undefined value will
159 be 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
169 module 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
175 repository $repository. If there are no paths associated with that
176 repository, 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
194 command $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
201 invoking 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
205 single 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,
214 provided 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
218 difference between "cachable_run_task" and "run_task", with the
219 exception that the former will be alot faster if the archive is
220 used.
221 $module->unarchive_result($runtime, $cache, $taskname)
223 This method restores the result of the task $taskname from an old
224 archive $cache. $cache will be a subclass of the
225 "Test::AutoBuild::Archive" module. If the taskname is "build", then
226 the log files, build results, intalled files, generated packages,
227 and source changelogs will all be restored. If the taskname is
228 prefixed by "test-", then the log files and test results will be
229 restored.
230 my $bool = $module->archive_usable($runtime, $archive, $taskname)
232 Returns a true value, if the archive $archive contains a usable
233 saved entry for the task $taskname. An archive for a module's task
234 is defined to be usable if all dependant modules are also usable;
235 if the archive contains a bucket with the name $taskname; if the
236 status of the save task is "success" or "cached"; and if no source
237 code changes have been made.
238 $module->archive_result($runtime, $archive, $taskname)
240 This method saves the result of the task $taskname to a new archive
241 $archive. $archive will be a subclass of the
242 "Test::AutoBuild::Archive" module. If the taskname is "build", then
243 the log files, build results, intalled files, generated packages,
244 and source changelogs will all be saved. If the taskname is
245 prefixed by "test-", then the log files and test results will be
246 saved.
247 $module->build($runtime, $controlfile);
249 Runs the build task, by invoking the shell command $controlfile in
250 the source directory of this module. Refer to the "run_task" and
251 "invoke_shell" methods for further details of the context of
252 execution. Results and information about the task can later be
253 invoking the various "build_XXX" methods.
254 $module->test($runtime, $testname, $controlfile);
256 Runs a test task with the name $testname, by invoking the shell
257 command $controlfile in the source directory of this module. Refer
258 to the "run_task" and "invoke_shell" methods for further details of
259 the context of execution. Results and information about the task
260 can later be retrieved passing the $testname to the various
261 "test_XXX" methods.
262 my $bool = $module->should_skip($runtime);
264 Determines if execution of tasks for this module should be skipped.
265 A module should be skipped, if any of its dependant modules have a
266 value returned by their "build_status" methods of 'failed',
267 'pending' or 'skipped'.
268
270 Daniel Berrange <dan@berrange.com>
271
273 Copyright (C) 2002-2004 Daniel Berrange <dan@berrange.com>
274
276 perl(1), Test::AutoBuild::Runtime, Test::AutoBuild::Repository,
277 Test::AutoBuild::Stage
278perl v5.12.1 2007-12-10 Test::AutoBuild::Module(3)