Module: Dpl::Provider::Dsl

Includes:
Squiggle
Included in:
Dpl::Provider
Defined in:
lib/dpl/provider/dsl.rb

Overview

DSL available on the provider’s class body.

Use this to declare various features, requirements, and attributes that apply to your provider.

Instance Method Summary collapse

Methods included from Squiggle

#sq

Instance Method Details

#apt(package = nil, cmd = nil) ⇒ Object

Declare APT packages the provider depends on. These will be installed during the ‘before_install` stage using `apt-get install`, unless the given cmd is already available according to `which [cmd]`.

Parameters:

  • package (String) (defaults to: nil) —

    Package name (required).

  • cmd (String) (defaults to: nil) —

    Executable command installed by that package (optional, defaults to the package name).

Returns:

  • Previously declared apt packages if no arguments were given.



122
123
124
125
 
# File 'lib/dpl/provider/dsl.rb', line 122

def apt(package = nil, cmd = nil)
  return apt << [package, cmd].compact if package
  @apt ||= self == Provider ? [] : superclass.apt.dup
end

#apt? ⇒ Boolean

Whether or not the provider depends on any apt packages.

Returns:

  • (Boolean) 


128
129
130
 
# File 'lib/dpl/provider/dsl.rb', line 128

def apt?
  apt.any?
end

#cmds(cmds = nil) ⇒ Object

Declare shell commands used by the provider.

This exists so shell commands used can be separated from the implementation that runs them. This is useful in order to easily get an overview of all shell commands used by a provider on one hand, and in order to keep the implementation code focussed on the logic and functionality it provides, rather than the details of (potentially long winded) shell commands.

For example, a shell command declared on the class body like so:

```ruby
cmds git_push: 'git push -f %{target}'
```

can be used in the deploy stage like so:

```ruby
def deploy
  shell :git_push
end
```

The variable ‘%target` will be interpolated by calling the method `target` on the provider instance, so it will expect that method to exist.

commands.

Parameters:

  • cmds (Hash) (defaults to: nil) —

    Commands to declare.

Returns:

  • Previously declared cmds if no argument is given.

See Also:



224
225
226
227
 
# File 'lib/dpl/provider/dsl.rb', line 224

def cmds(cmds = nil)
  return self.cmds.update(cmds) if cmds
  @cmds ||= self == Provider ? {} : superclass.cmds.dup
end

#description(str = nil) ⇒ Object

Summary of the provider’s functionality.



38
39
40
41
 
# File 'lib/dpl/provider/dsl.rb', line 38

def description(str = nil)
  str = str.strip if str
  super
end

#env ⇒ Object

Declare an environment variable prefix to accept env vars as options

This method is defined in ‘Env::ClassMethods`.

Declares an environment variable prefix that imports environment variables into ‘opts` if they match declared options.

For example, with the following declaration on the class body:

```ruby
env :aws
opt '--access_key_id ID'
```

if the environment variable ‘AWS_ACCESS_KEY_ID` is set then the option `opts` will default to the value given on that variable (i.e. it could still be overwritten by the user by passing the `–access_key_id` option).




# File 'lib/dpl/provider/dsl.rb', line 64

#errs(errs = nil) ⇒ Object

Declare error messages that are raised if a shell command fails.

This exists so error messages can be separated from the implementation that uses them. This is useful in order to easily get an overview of all error messages used by a provider on one hand, and in order to keep the implementation code focussed on the logic and functionality it provides, rather than the details of (potentially long winded) error message strings.

The method ‘shell` will raise an error if the given shell command fails (returns a non-zero exit code) unless it is called with the option `assert: false`. The error message declared using `errs` will be used to raise with the eror.

For example, an error message declared on the class body like so:

```ruby
errs git_push: 'Failed to push to %{target}'
```

will be included to the raised error if the given command has failed:

```ruby
def deploy
  shell :git_push
end
```

The variable ‘%target` will be interpolated by calling the method `target` on the provider instance, so it will expect that method to exist.

See Dpl::Ctx::Bash#shell for more details on how to call shell commands.

Parameters:

  • errs (Hash) (defaults to: nil) —

    Error messages to declare.

Returns:

  • Previously declared errs if no argument is given.



266
267
268
269
 
# File 'lib/dpl/provider/dsl.rb', line 266

def errs(errs = nil)
  return self.errs.update(errs) if errs
  @errs ||= self == Provider ? {} : superclass.errs.dup
end

#full_name(name = nil) ⇒ Object

Declare the full name of the provider. Required if the proper provider name does not match the provider’s class name.

Parameters:

  • name (String) (defaults to: nil) —

    The provider’s full name

Returns:

  • The previously declared full name if no argument is given



28
29
30
 
# File 'lib/dpl/provider/dsl.rb', line 28

def full_name(name = nil)
  name ? @full_name = name : @full_name || self.name.split('::').last
end

#gem(name = nil, version = nil, opts = {}) ⇒ Object

Declare additional paths to Ruby gem source code that this provider requires.

These gems will be installed, and files required at runtime, during the ‘before_init` stage (not at install time, and/or load time), unless they are already installed.

Parameters:

  • name (String) (defaults to: nil) —

    Ruby gem name (required)

  • version (String) (defaults to: nil) —

    Ruby gem version (required)

  • opts (Hash) (defaults to: {}) —

    options

Options Hash (opts):

  • :require (Array<String>, String) —

    A single path or a list of paths to source files to require from this Ruby gem. If not given the name of the gem will be assumed to be the path to be required.

Returns:

  • Previously declared gems if no arguments were given



145
146
147
148
 
# File 'lib/dpl/provider/dsl.rb', line 145

def gem(name = nil, version = nil, opts = {})
  return gem << [name, version, opts] if name
  @gem ||= self == Provider ? [] : superclass.gem.dup
end

#gem? ⇒ Boolean

Returns:

  • (Boolean) 


150
151
152
 
# File 'lib/dpl/provider/dsl.rb', line 150

def gem?
  gem.any?
end

#keep(*paths) ⇒ Object

Declare artifacts, such as executables during the ‘install` stage that need to be kept during `cleanup`.

Parameters:

  • paths (String) —

    Paths to artifacts to keep during ‘cleanup`

Returns:

  • Previously declared artifacts to keep if no argument is given.



343
344
345
346
 
# File 'lib/dpl/provider/dsl.rb', line 343

def keep(*paths)
  return keep.concat(paths) if paths.any?
  @keep ||= self == Provider ? [] : superclass.keep.dup
end

#move(*paths) ⇒ Object 



97
98
99
 
# File 'lib/dpl/provider/dsl.rb', line 97

def move(*paths)
  paths.any? ? @move = paths : @move ||= []
end

#msgs(msgs = nil) ⇒ Object

Declare other messages, such as info level log output, warnings, or custom strings, such as commit messages or descriptions.

This exists so various messages can be separated from the implementation that uses them. This is useful in order to easily get an overview of all error messages used by a provider on one hand, and in order to keep the implementation code focussed on the logic and functionality it provides, rather than the details of (potentially long winded) message strings.

For example, a message declared on the class body like so:

```ruby
msgs login: 'Logging in to the service %{full_name}'
```

could be used by the implementation like so:

```ruby
def login
  info :login
end
```

The variable ‘%#full_name` will be interpolated by calling the method `full_name` on the provider instance, so it will expect that method to exist.

It is possible to use msgs in order to declare and use custom messages, e.g. for the commit message on a commit a provider needs to create, or a description that needs to be included to an API call.

For example, a message declared on the class body like so:

```ruby
cmds git_commit: 'git commit -am "%{commit_msg}"'
msgs commit_msg: 'Commit build artifacts on build %{build_number}'
```

could be used by the implementation like so:

```ruby
def create_commit
  shell :git_commit
end

def commit_msg
  interpolate(msg(:commit_msg))
end
```

Note that in cases where builtin methods such as ‘shell`, `info`, `warn` etc. are not used the method `interpolate` needs to be used in order to interpolate variables used in a message (if any).

Parameters:

  • msgs (Hash) (defaults to: nil) —

    Messages to declare.

Returns:

  • Previously declared msgs if no argument is given.



328
329
330
331
 
# File 'lib/dpl/provider/dsl.rb', line 328

def msgs(msgs = nil)
  return self.msgs.update(msgs) if msgs
  @msgs ||= self == Provider ? {} : superclass.msgs.dup
end

#needs(*features) ⇒ Object

Declare features that the provider needs.

Known features currently are:

  • ‘ssh_key`: Generates a temporary, per-build SSH key, and calls the methods `add_key` and `remove_key` if the provider defines them. This gives providers the opportunity to install this key on their service, and remove it after the deployment has finished.

  • ‘git`: Populates the git config.user and config.email attributes, unless present.

  • ‘git_http_user_agent`: Changes the environment variable `GIT_HTTP_USER_AGENT` to the one generated by `user_agent`. This gives providers the opportunity to identify and track coming from Travis CI and/or dpl.

Parameters:

  • features (Symbol) —

    Features to activate for this provider

Returns:

  • Previously declared features needed if no argument is given.



365
366
367
368
 
# File 'lib/dpl/provider/dsl.rb', line 365

def needs(*features)
  return needs.concat(features) if features.any?
  @needs ||= self == Provider ? [] : superclass.needs.dup
end

#needs?(feature) ⇒ Boolean

Whether or not the provider has declared any features it needs.

Returns:

  • (Boolean) 


371
372
373
 
# File 'lib/dpl/provider/dsl.rb', line 371

def needs?(feature)
  needs.include?(feature)
end

#node_js(*requirements) ⇒ Object 



101
102
103
 
# File 'lib/dpl/provider/dsl.rb', line 101

def node_js(*requirements)
  runtimes(:node_js, requirements)
end

#npm(package = nil, cmd = nil) ⇒ Object

Declare NPM packages the provider depends on. These will be installed during the ‘before_install` stage using `npm install -g`, unless the given cmd is already available according to `which [cmd]`.

Parameters:

  • package (String) (defaults to: nil) —

    Package name (required).

  • cmd (String) (defaults to: nil) —

    Executable command installed by that package (optional, defaults to the package name).

Returns:

  • Previously declared NPM packages if no arguments are given.



162
163
164
165
 
# File 'lib/dpl/provider/dsl.rb', line 162

def npm(package = nil, cmd = nil)
  return npm << [package, cmd].compact if package
  @npm ||= self == Provider ? [] : superclass.npm.dup
end

#npm? ⇒ Boolean

Whether or not the provider depends on any NPM packages.

Returns:

  • (Boolean) 


168
169
170
 
# File 'lib/dpl/provider/dsl.rb', line 168

def npm?
  npm.any?
end

#opt ⇒ Object

Declare command line options that the provider supports.

This method is inherited from the base class ‘Cl::Cmd` which is defined in the Rubygem `Cl`. See the gem’s documentation for details on how to declare command line options.

See Also:



93
94
95
 
# File 'lib/dpl/provider/dsl.rb', line 93

def path(path)
  ENV['PATH'] = "#{File.expand_path(path)}:#{ENV['PATH']}"
end

#path(path) ⇒ Object

Declare command line options that the provider supports.

This method is inherited from the base class ‘Cl::Cmd` which is defined in the Rubygem `Cl`. See the gem’s documentation for details on how to declare command line options.

See Also:



93
94
95
 
# File 'lib/dpl/provider/dsl.rb', line 93

def path(path)
  ENV['PATH'] = "#{File.expand_path(path)}:#{ENV['PATH']}"
end

#pip(package = nil, cmd = nil, version = nil) ⇒ Object

Declare Python packages the provider depends on. These will be installed during the ‘before_install` stage using `pip install –user`. A previously installed package is uninstalled before that, but only if `version` was given.

Parameters:

  • package (String) (defaults to: nil) —

    Package name (required).

  • cmd (String) (defaults to: nil) —

    Executable command installed by that package (optional, defaults to the package name).

  • version (String) (defaults to: nil) —

    Package version (optional).

Returns:

  • Previously declared Python packages if no arguments are given.



182
183
184
185
 
# File 'lib/dpl/provider/dsl.rb', line 182

def pip(package = nil, cmd = nil, version = nil)
  return pip << [package, cmd, version].compact if package
  @pip ||= self == Provider ? [] : superclass.pip.dup
end

#pip? ⇒ Boolean

Whether or not the provider depends on any Python packages.

Returns:

  • (Boolean) 


188
189
190
 
# File 'lib/dpl/provider/dsl.rb', line 188

def pip?
  pip.any?
end

#python(*requirements) ⇒ Object 



105
106
107
 
# File 'lib/dpl/provider/dsl.rb', line 105

def python(*requirements)
  runtimes(:python, requirements)
end

#ruby_pre?(version) ⇒ Boolean

Returns:

  • (Boolean) 


391
392
393
 
# File 'lib/dpl/provider/dsl.rb', line 391

def ruby_pre?(version)
  ruby_version < Gem::Version.new(version)
end

#ruby_version ⇒ Object 



387
388
389
 
# File 'lib/dpl/provider/dsl.rb', line 387

def ruby_version
  Gem::Version.new(RUBY_VERSION)
end

#runtimes(name = nil, requirements = nil) ⇒ Object 



109
110
111
112
 
# File 'lib/dpl/provider/dsl.rb', line 109

def runtimes(name = nil, requirements = nil)
  return @runtimes ||= [] unless name
  runtimes << [name, requirements]
end

#status(status = nil, msg = nil) ⇒ Object

Set or read the provider’s maturity status with an optional message



44
45
46
 
# File 'lib/dpl/provider/dsl.rb', line 44

def status(status = nil, msg = nil)
  status ? @status = Status.new(self, status, msg) : @status
end

#strs(strs = nil) ⇒ Object 



333
334
335
336
 
# File 'lib/dpl/provider/dsl.rb', line 333

def strs(strs = nil)
  return self.strs.update(strs) if strs
  @strs ||= self == Provider ? {} : superclass.strs.dup
end

#summary(summary = nil) ⇒ Object

Summary of the provider’s functionality.



33
34
35
 
# File 'lib/dpl/provider/dsl.rb', line 33

def summary(summary = nil)
  summary ? super : @summary || "#{full_name} deployment provider"
end

#user_agent(*strs) ⇒ String

Generates a useragent string that identifies the current dpl version, and whether it runs int he context of Travis CI. Can include arbitrary extra strings or key value pairs (passed as String or Hash arguments).

Parameters:

  • strs (String(s) or Hash(es)) —

    Additional strings or key value pairs to include to the useragent string.

Returns:

  • (String) —

    The useragent string



380
381
382
383
384
385
 
# File 'lib/dpl/provider/dsl.rb', line 380

def user_agent(*strs)
  strs.unshift "dpl/#{Dpl::VERSION}"
  strs.unshift 'travis/0.1.0' if ENV['TRAVIS']
  strs = strs.flat_map { |e| Hash === e ? e.map { |k, v| "#{k}/#{v}" } : e }
  strs.join(' ').gsub(/\s+/, ' ').strip
end

#vars(*vars) ⇒ Object

Declare additional variables available for interpolation.

Interpolating strings, when these exposed to the user, should safelist which variables are available. Options declared on a provider are always available, except if they are flags, arrays, internal, or secrets. This method can be used to allow additional variables, e.g. from the git context.



55
56
57
58
59
60
61
62
 
# File 'lib/dpl/provider/dsl.rb', line 55

def vars(*vars)
  return self.vars.concat(vars) if vars.any?
  return @vars if instance_variable_defined?(:@vars)
  vars = superclass.respond_to?(:vars) ? superclass.vars : []
  reject = %i(flag array internal interpolate secret)
  opts = reject.inject(self.opts) { |opts, attr| opts.reject(&:"#{attr}?") }
  @vars = vars.dup.concat(opts.map(&:name)).uniq.sort - [:strategy]
end