class Autobuild::Utility
Utilities are post-build things that can be executed on packages
Canonical examples are documentation generation and tests
Attributes
Allows to override the utility’s availability (i.e. whether this utility is available on the underlying package) regardless of whether {task} got called or not
This is mainly used to fine-tune packages whose base type enables the utility (e.g. testing) but the actual package does not have it
Allows to disable the utility regardless of the value of {available?}
This utility’s name
Controls whether this utility generates results or not
By default, Autobuild
assumes that utilities generate report or artifact files, that are saved in {#target_dir}. Set this flag to true to disable this behavior, in which case the only report will be the console output during run
@see no_results
?
@return [Package] the package on which this utility object acts
Directory in which the utility will generate some files The interpretation of relative directories is package-specific. The default implementation interpret them as relative to the source directory. Set {#source_ref_dir=}
@return [String,nil] the target directory, or nil if this utility does
not need any special source directory
@return [String,nil] the reference directory for {#source_dir=}. If
nil, will use the package's source directory
Directory in which the utility would install some files. If it is relative, it is interpreted as relative to the utility’s prefix directory (Autobuild
.#{name}_prefix)
@return [String,nil] the target directory, or nil if this utility does
not install anything
Public Class Methods
# File lib/autobuild/utility.rb, line 22 def initialize(name, package, install_on_error: false) @name = name @task = nil @package = package @available = true @enabled = true @source_ref_dir = nil @source_dir = nil @target_dir = nil @install_on_error = install_on_error @no_results = false @invoked = false @success = false @installed = false end
Public Instance Methods
True if this utility would do something, and false otherwise
This will return true only if a task has been by calling {task} and the utility has not been explicitly disabled by setting the {enabled} attribute to false
@return [Boolean]
# File lib/autobuild/utility.rb, line 158 def available? @available && @task && (no_results? || source_dir) end
# File lib/autobuild/utility.rb, line 122 def call_task_block @invoked = true begin yield if block_given? @success = true rescue StandardError => e install if install_on_error? && !@installed && !no_results? raise end # Allow the user to install manually in the task # block install if !@installed && !no_results? rescue StandardError => e @success = false if Autobuild.send("pass_#{name}_errors") raise else package.warn "%s: failed to call #{name}" if e.kind_of?(SubcommandFailed) package.warn "%s: see #{e.logfile} for more details" else package.warn "%s: #{e.message}" end end end
Can be called in the block given to {task} to announce that the utility is to be disabled for that package. This is mainly used when a runtime check is necessary to know if a package can run this utility or not.
# File lib/autobuild/utility.rb, line 220 def disabled throw :disabled end
True if this utility should be executed
@return [Boolean]
# File lib/autobuild/utility.rb, line 165 def enabled? @enabled && available? end
True if the underlying package already has a task generated by this utility
@return [Boolean]
# File lib/autobuild/utility.rb, line 235 def has_task? Rake.application.lookup(task_name) end
# File lib/autobuild/utility.rb, line 180 def install unless File.directory?(source_dir) raise "#{source_dir} was expected to be a directory, but it is not. "\ "Check the package's #{name} generation. "\ "The generated #{name} products should be in #{source_dir}" end target_dir = self.target_dir source_dir = self.source_dir FileUtils.rm_rf target_dir FileUtils.mkdir_p File.dirname(target_dir) FileUtils.cp_r source_dir, target_dir Autoproj.message " copied #{name} results for #{package.name} "\ "from #{source_dir} to #{target_dir}" @installed = true end
Whether install
should be called even if the task failed
The default is false. Set it to true for instance if the utility results are a report of the success/errors (e.g. test run results)
# File lib/autobuild/utility.rb, line 18 def install_on_error? @install_on_error end
True if the utility’s results have been installed
# File lib/autobuild/utility.rb, line 212 def installed? @installed end
True if the utility has been invoked
# File lib/autobuild/utility.rb, line 199 def invoked? @invoked end
Whether this utility generates results or not
@see no_results
=
# File lib/autobuild/utility.rb, line 75 def no_results? @no_results end
Absolute path to where this utulity should output its results. Returns nil if {source_dir} has not been set.
# File lib/autobuild/utility.rb, line 50 def source_dir File.expand_path(@source_dir, source_ref_dir || package.srcdir) if @source_dir end
True if the utility has been successful
Combine with {#invoked?} to determine whether ‘false’ means ‘not run’ or ‘failed’
# File lib/autobuild/utility.rb, line 207 def success? @success end
Absolute path to where the utility product files have to be installed. Returns nil if {target_dir} is not set.
@return [String,nil]
# File lib/autobuild/utility.rb, line 83 def target_dir if @target_dir utility_prefix = Autobuild.send("#{name}_prefix") || name File.expand_path(@target_dir, File.expand_path(utility_prefix, package.prefix)) else File.join(package.logdir, "#{name}-results", package.name) end end
Defines the task code for this utility. The given block is called and then the utility byproducts get installed (if any).
The block is invoked in the package’s source directory
In general, specific package types define a meaningful with_XXX method that call this method internally
@return [Rake::Task]
# File lib/autobuild/utility.rb, line 102 def task(&block) return if @task @task = package.task task_name do # This flag allows to disable this utility's task # once {task} has been called if enabled? @installed = false catch(:disabled) do package.isolate_errors do call_task_block(&block) end end end end package.task name => task_name @task end
The name of the Rake
task
@return [String]
# File lib/autobuild/utility.rb, line 227 def task_name "#{package.name}-#{name}" end