class Autobuild::Utility

Utilities are post-build things that can be executed on packages

Canonical examples are documentation generation and tests

Attributes

available[W]

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

enabled[W]

Allows to disable the utility regardless of the value of {available?}

name[R]

This utility's name

no_results[W]

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?

package[R]

@return [Package] the package on which this utility object acts

source_dir[W]

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
source_ref_dir[RW]

@return [String,nil] the reference directory for {#source_dir=}. If

nil, will use the package's source directory
target_dir[W]

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

new(name, package, install_on_error: false) click to toggle source
# 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

available?() click to toggle source

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
call_task_block() { || ... } click to toggle source
# 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
disabled() click to toggle source

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
enabled?() click to toggle source

True if this utility should be executed

@return [Boolean]

# File lib/autobuild/utility.rb, line 165
def enabled?
    @enabled && available?
end
has_task?() click to toggle source

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
install() click to toggle source
# 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
install_on_error?() click to toggle source

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
installed?() click to toggle source

True if the utility's results have been installed

# File lib/autobuild/utility.rb, line 212
def installed?
    @installed
end
invoked?() click to toggle source

True if the utility has been invoked

# File lib/autobuild/utility.rb, line 199
def invoked?
    @invoked
end
no_results?() click to toggle source

Whether this utility generates results or not

@see no_results=

# File lib/autobuild/utility.rb, line 75
def no_results?
    @no_results
end
source_dir() click to toggle source

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
success?() click to toggle source

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
target_dir() click to toggle source

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
task(&block) click to toggle source

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
task_name() click to toggle source

The name of the Rake task

@return [String]

# File lib/autobuild/utility.rb, line 227
def task_name
    "#{package.name}-#{name}"
end