Class: Autobuild::Utility

Inherits:
Object
  • Object
show all
Defined in:
lib/autobuild/utility.rb

Overview

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

Canonical examples are documentation generation and tests

Direct Known Subclasses

TestUtility

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name, package, install_on_error: false) ⇒ Utility

Returns a new instance of Utility.



22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
 
# 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

Instance Attribute Details

#available=(value) ⇒ Object (writeonly)

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



175
176
177
 
# File 'lib/autobuild/utility.rb', line 175

def available=(value)
  @available = value
end

#enabled=(value) ⇒ Object (writeonly)

Allows to disable the utility regardless of the value of #available?



178
179
180
 
# File 'lib/autobuild/utility.rb', line 178

def enabled=(value)
  @enabled = value
end

#name ⇒ Object (readonly)

This utility’s name



7
8
9
 
# File 'lib/autobuild/utility.rb', line 7

def name
  @name
end

#no_results=(value) ⇒ Object (writeonly)

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 Also:



70
71
72
 
# File 'lib/autobuild/utility.rb', line 70

def no_results=(value)
  @no_results = value
end

#package ⇒ Package (readonly)

Returns the package on which this utility object acts.

Returns:

  • (Package) —

    the package on which this utility object acts



9
10
11
 
# File 'lib/autobuild/utility.rb', line 9

def package
  @package
end

#source_dir ⇒ Object

Absolute path to where this utulity should output its results. Returns nil if #source_dir has not been set.



50
51
52
 
# File 'lib/autobuild/utility.rb', line 50

def source_dir
    File.expand_path(@source_dir, source_ref_dir || package.srcdir) if @source_dir
end

#source_ref_dir ⇒ String?

Returns the reference directory for #source_dir=. If nil, will use the package’s source directory.

Returns:

  • (String, nil) —

    the reference directory for #source_dir=. If nil, will use the package’s source directory



12
13
14
 
# File 'lib/autobuild/utility.rb', line 12

def source_ref_dir
  @source_ref_dir
end

#target_dir ⇒ String?

Absolute path to where the utility product files have to be installed. Returns nil if #target_dir is not set.

Returns:

  • (String, nil) 


83
84
85
86
87
88
89
90
91
 
# 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

Instance Method Details

#available? ⇒ Boolean

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

Returns:

  • (Boolean) 


158
159
160
 
# File 'lib/autobuild/utility.rb', line 158

def available?
    @available && @task && (no_results? || source_dir)
end

#call_task_block ⇒ Object 



122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
 
# 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 ⇒ Object

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.



220
221
222
 
# File 'lib/autobuild/utility.rb', line 220

def disabled
    throw :disabled
end

#enabled? ⇒ Boolean

True if this utility should be executed

Returns:

  • (Boolean) 


165
166
167
 
# File 'lib/autobuild/utility.rb', line 165

def enabled?
    @enabled && available?
end

#has_task? ⇒ Boolean

True if the underlying package already has a task generated by this utility

Returns:

  • (Boolean) 


235
236
237
 
# File 'lib/autobuild/utility.rb', line 235

def has_task?
    Rake.application.lookup(task_name)
end

#install ⇒ Object 



180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
 
# 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? ⇒ Boolean

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)

Returns:

  • (Boolean) 


18
19
20
 
# File 'lib/autobuild/utility.rb', line 18

def install_on_error?
    @install_on_error
end

#installed? ⇒ Boolean

True if the utility’s results have been installed

Returns:

  • (Boolean) 


212
213
214
 
# File 'lib/autobuild/utility.rb', line 212

def installed?
    @installed
end

#invoked? ⇒ Boolean

True if the utility has been invoked

Returns:

  • (Boolean) 


199
200
201
 
# File 'lib/autobuild/utility.rb', line 199

def invoked?
    @invoked
end

#no_results? ⇒ Boolean

Whether this utility generates results or not

Returns:

  • (Boolean)

See Also:



75
76
77
 
# File 'lib/autobuild/utility.rb', line 75

def no_results?
    @no_results
end

#success? ⇒ Boolean

True if the utility has been successful

Combine with #invoked? to determine whether ‘false’ means ‘not run’ or ‘failed’

Returns:

  • (Boolean) 


207
208
209
 
# File 'lib/autobuild/utility.rb', line 207

def success?
    @success
end

#task(&block) ⇒ Rake::Task

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

Returns:



102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
 
# 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 ⇒ String

The name of the Rake task

Returns:

  • (String) 


227
228
229
 
# File 'lib/autobuild/utility.rb', line 227

def task_name
    "#{package.name}-#{name}"
end