Class: Berkshelf::Berksfile

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Mixin::Logging, Cleanroom
Defined in:
lib/berkshelf/berksfile.rb

Constant Summary collapse

DEFAULT_API_URL = 
"https://supermarket.getchef.com".freeze

Instance Attribute Summary collapse

Attributes included from Mixin::Logging

#logger

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(path, options = {}) ⇒ Berksfile

Create a new Berksfile object.

Parameters:

  • path (String) —

    path on disk to the file containing the contents of this Berksfile

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

    a customizable set of options

Options Hash (options):

  • :except (Symbol, Array<String>) —

    Group(s) to exclude which will cause any dependencies marked as a member of the group to not be installed

  • :only (Symbol, Array<String>) —

    Group(s) to include which will cause any dependencies marked as a member of the group to be installed and all others to be ignored



51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/berkshelf/berksfile.rb', line 51

def initialize(path, options = {})
  @filepath         = File.expand_path(path)
  @dependencies     = Hash.new
  @sources          = Hash.new

  if options[:except] && options[:only]
    raise ArgumentError, 'Cannot specify both :except and :only!'
  elsif options[:except]
    except = Array(options[:except]).collect(&:to_sym)
    @filter = ->(dependency) { (except & dependency.groups).empty? }
  elsif options[:only]
    only = Array(options[:only]).collect(&:to_sym)
    @filter = ->(dependency) { !(only & dependency.groups).empty? }
  else
    @filter = ->(dependency) { true }
  end
end

Instance Attribute Details

#filepath ⇒ String (readonly)

Returns The path on disk to the file representing this instance of Berksfile.

Returns:

  • (String) —

    The path on disk to the file representing this instance of Berksfile



38
39
40
 
# File 'lib/berkshelf/berksfile.rb', line 38

def filepath
  @filepath
end

Class Method Details

.from_file(file, options = {}) ⇒ Berksfile

Parameters:

  • file (#to_s) —

    a path on disk to a Berksfile to instantiate from

Returns:

Raises:



19
20
21
22
23
24
25
26
27
 
# File 'lib/berkshelf/berksfile.rb', line 19

def from_file(file, options = {})
  raise BerksfileNotFound.new(file) unless File.exist?(file)

  begin
    new(file, options).evaluate_file(file)
  rescue => ex
    raise BerksfileReadError.new(ex)
  end
end

.from_options(options = {}) ⇒ Object

Instantiate a Berksfile from the given options. This method is used heavily by the CLI to reduce duplication.

Parameters:

  • path (String) —

    path on disk to the file containing the contents of this Berksfile

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

    a customizable set of options



10
11
12
13
 
# File 'lib/berkshelf/berksfile.rb', line 10

def from_options(options = {})
  options[:berksfile] ||= File.join(Dir.pwd, Berkshelf::DEFAULT_FILENAME)
  from_file(options[:berksfile], options.slice(:except, :only))
end

Instance Method Details

#[](name) ⇒ Dependency Also known as: get_dependency

Parameters:

  • name (String) —

    name of the dependency to return

Returns:



338
339
340
 
# File 'lib/berkshelf/berksfile.rb', line 338

def [](name)
  @dependencies[name]
end

#add_dependency(name, constraint = nil, options = {}) ⇒ Array<Dependency]

Add a dependency of the given name and constraint to the array of dependencies.

Parameters:

  • name (String) —

    the name of the dependency to add

  • constraint (String, Semverse::Constraint) (defaults to: nil) —

    the constraint to lock the dependency to

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

    a customizable set of options

Options Hash (options):

  • :group (Symbol, Array) —

    the group or groups that the cookbook belongs to

  • :path (String) —

    a filepath to the cookbook on your local disk

  • :git (String) —

    the Git URL to clone

Returns:

Raises:



247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
 
# File 'lib/berkshelf/berksfile.rb', line 247

def add_dependency(name, constraint = nil, options = {})
  if @dependencies[name]
    # Only raise an exception if the dependency is a true duplicate
    groups = (options[:group].nil? || options[:group].empty?) ? [:default] : options[:group]
    if !(@dependencies[name].groups & groups).empty?
      raise DuplicateDependencyDefined.new(name)
    end
  end

  if options[:path]
    metadata_file = File.join(options[:path], 'metadata.rb')
  end

  options[:constraint] = constraint

  @dependencies[name] = Dependency.new(self, name, options)
end

#chef_api(*args) ⇒ Object

TODO:

remove in Berkshelf 4.0

Raises:



222
223
224
225
226
 
# File 'lib/berkshelf/berksfile.rb', line 222

def chef_api(*args)
  raise DeprecatedError.new "Your Berksfile contains a chef_api location. Chef API locations have " +
    " been replaced by the source location. Please remove your site location and try again. For more " +
    " information visit https://github.com/berkshelf/berkshelf/wiki/deprecated-locations"
end

#cookbook(name, version_constraint, options = {}) ⇒ Object #cookbook(name, options = {}) ⇒ Object

Add a cookbook dependency to the Berksfile to be retrieved and have its dependencies recursively retrieved and resolved.

Examples:

a cookbook dependency that will be retrieved from one of the default locations

cookbook 'artifact'

a cookbook dependency that will be retrieved from a path on disk

cookbook 'artifact', path: '/Users/reset/code/artifact'

a cookbook dependency that will be retrieved from a Git server

cookbook 'artifact', git: 'git://github.com/RiotGames/artifact-cookbook.git'

Overloads:

  • #cookbook(name, version_constraint, options = {}) ⇒ Object

    Parameters:

    • name (#to_s)
    • version_constraint (#to_s)

    Options Hash (options):

    • :group (Symbol, Array) —

      the group or groups that the cookbook belongs to

    • :path (String) —

      a filepath to the cookbook on your local disk

    • :git (String) —

      the Git URL to clone

    See Also:

  • #cookbook(name, options = {}) ⇒ Object

    Parameters:

    • name (#to_s)

    Options Hash (options):

    • :group (Symbol, Array) —

      the group or groups that the cookbook belongs to

    • :path (String) —

      a filepath to the cookbook on your local disk

    • :git (String) —

      the Git URL to clone

    See Also:



127
128
129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/berkshelf/berksfile.rb', line 127

def cookbook(*args)
  options = args.last.is_a?(Hash) ? args.pop : Hash.new
  name, constraint = args

  options[:path] &&= File.expand_path(options[:path], File.dirname(filepath))
  options[:group] = Array(options[:group])

  if @active_group
    options[:group] += @active_group
  end

  add_dependency(name, constraint, options)
end

#cookbooks ⇒ Array<CachedCookbook>

Behaves the same as #dependencies, but this method returns an array of CachedCookbook objects instead of dependency objects. This method relies on the #retrieve_locked method to load the proper cached cookbook from the Berksfile + lockfile combination.

Returns:

See Also:

  • for a description of the +options+ hash
  • for a list of possible exceptions that might be raised and why


295
296
297
 
# File 'lib/berkshelf/berksfile.rb', line 295

def cookbooks
  dependencies.map { |dependency| retrieve_locked(dependency) }
end

#dependencies ⇒ Array<Dependency>

Returns:



278
279
280
 
# File 'lib/berkshelf/berksfile.rb', line 278

def dependencies
  @dependencies.values.sort.select(&@filter)
end

#extension(name) ⇒ true

Activate a Berkshelf extension at runtime.

Examples:

Activate the Mercurial extension

extension 'hg'

Parameters:

  • name (String) —

    the name of the extension to activate

Returns:

  • (true)

Raises:

  • (LoadError) —

    if the extension cannot be loaded



81
82
83
84
85
86
87
 
# File 'lib/berkshelf/berksfile.rb', line 81

def extension(name)
  require "berkshelf/#{name}"
  true
rescue LoadError
  raise LoadError, "Could not load an extension by the name `#{name}'. " \
    "Please make sure it is installed."
end

#find(name) ⇒ Dependency?

Find a dependency defined in this berksfile by name.

Parameters:

  • name (String) —

    the name of the cookbook dependency to search for

Returns:

  • (Dependency, nil) —

    the cookbook dependency, or nil if one does not exist



305
306
307
 
# File 'lib/berkshelf/berksfile.rb', line 305

def find(name)
  @dependencies[name]
end

#group(*args) ⇒ Object 



142
143
144
145
146
 
# File 'lib/berkshelf/berksfile.rb', line 142

def group(*args)
  @active_group = args
  yield
  @active_group = nil
end

#groups ⇒ Hash

Returns a hash containing group names as keys and an array of Dependencies that are a member of that group as values

Example:

{
  nautilus: [
    #<Dependency: nginx (~> 1.0.0)>,
    #<Dependency: mysql (~> 1.2.4)>
  ],
  skarner: [
    #<Dependency: nginx (~> 1.0.0)>
  ]
}.

Returns:

  • (Hash) —

    a hash containing group names as keys and an array of Dependencies that are a member of that group as values

    Example:

    {
  nautilus: [
    #<Dependency: nginx (~> 1.0.0)>,
    #<Dependency: mysql (~> 1.2.4)>
  ],
  skarner: [
    #<Dependency: nginx (~> 1.0.0)>
  ]
}



323
324
325
326
327
328
329
330
331
332
 
# File 'lib/berkshelf/berksfile.rb', line 323

def groups
  {}.tap do |groups|
    dependencies.each do |dependency|
      dependency.groups.each do |group|
        groups[group] ||= []
        groups[group] << dependency
      end
    end
  end
end

#has_dependency?(dependency) ⇒ Boolean

Check if the Berksfile has the given dependency, taking into account group and –only/–except flags.

Parameters:

  • dependency (String, Dependency) —

    the dependency or name of dependency to check presence of

Returns:

  • (Boolean) 


272
273
274
275
 
# File 'lib/berkshelf/berksfile.rb', line 272

def has_dependency?(dependency)
  name = Dependency.name(dependency)
  dependencies.map(&:name).include?(name)
end

#install ⇒ Array<CachedCookbook>

Install the dependencies listed in the Berksfile, respecting the locked versions in the Berksfile.lock.

  1. Check that a lockfile exists. If a lockfile does not exist, all dependencies are considered to be “unlocked”. If a lockfile is specified, a definition is created via the following algorithm:

    • For each source, see if there exists a locked version that still satisfies the version constraint in the Berksfile. If there exists such a source, remove it from the list of unlocked sources. If not, then either a version constraint has changed, or a new source has been added to the Berksfile. In the event that a locked_source exists, but it no longer satisfies the constraint, this method will raise a OutdatedCookbookSource, and inform the user to run berks update COOKBOOK to remedy the issue.

    • Remove any locked sources that no longer exist in the Berksfile (i.e. a cookbook source was removed from the Berksfile).

  2. Resolve the collection of locked and unlocked dependencies.

  3. Write out a new lockfile.

Returns:

Raises:

  • (OutdatedDependency) —

    if the lockfile constraints do not satisfy the Berksfile constraints



369
370
371
 
# File 'lib/berkshelf/berksfile.rb', line 369

def install
  Installer.new(self).run
end

#list ⇒ Hash<Dependency, CachedCookbook>

The cached cookbooks installed by this Berksfile.

Returns:

Raises:



425
426
427
428
429
430
431
 
# File 'lib/berkshelf/berksfile.rb', line 425

def list
  validate_lockfile_present!
  validate_lockfile_trusted!
  validate_dependencies_installed!

  lockfile.graph.locks.values
end

#lockfile ⇒ Lockfile

Get the lockfile corresponding to this Berksfile. This is necessary because the user can specify a different path to the Berksfile. So assuming the lockfile is named “Berksfile.lock” is a poor assumption.

Returns:

  • (Lockfile) —

    the lockfile corresponding to this berksfile, or a new Lockfile if one does not exist



656
657
658
 
# File 'lib/berkshelf/berksfile.rb', line 656

def lockfile
  @lockfile ||= Lockfile.from_berksfile(self)
end

#metadata(options = {}) ⇒ Object

Use a Cookbook metadata file to determine additional cookbook dependencies to retrieve. All dependencies found in the metadata will use the default locations set in the Berksfile (if any are set) or the default locations defined by Berkshelf.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :path (String) —

    path to the metadata file



157
158
159
160
161
162
163
 
# File 'lib/berkshelf/berksfile.rb', line 157

def metadata(options = {})
  path          = options[:path] || File.dirname(filepath)
  metadata_path = File.expand_path(File.join(path, 'metadata.rb'))
  metadata      = Ridley::Chef::Cookbook::Metadata.from_file(metadata_path)

  add_dependency(metadata.name, nil, path: path, metadata: true)
end

#outdated(*names) ⇒ Hash

List of all the cookbooks which have a newer version found at a source that satisfies the constraints of your dependencies.

Examples:

berksfile.outdated #=> {
  "nginx" => {
    "local" => #<Version 1.8.0>,
    "remote" => {
      #<Source uri: "https://supermarket.getchef.com"> #=> #<Version 2.6.2>
    }
  }
}

Returns:

  • (Hash) —

    a hash of cached cookbooks and their latest version grouped by their remote API source. The hash will be empty if there are no newer cookbooks for any of your dependencies (that still satisfy the given) constraints in the Berksfile.



451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
 
# File 'lib/berkshelf/berksfile.rb', line 451

def outdated(*names)
  validate_lockfile_present!
  validate_lockfile_trusted!
  validate_dependencies_installed!
  validate_cookbook_names!(names)

  lockfile.graph.locks.inject({}) do |hash, (name, dependency)|
    sources.each do |source|
      cookbooks = source.versions(name)

      latest = cookbooks.select do |cookbook|
        dependency.version_constraint.satisfies?(cookbook.version) &&
        Semverse::Version.coerce(cookbook.version) > dependency.locked_version
      end.sort_by { |cookbook| cookbook.version }.last

      unless latest.nil?
        hash[name] ||= {
          'local' => dependency.locked_version,
          'remote' => {
            source => Semverse::Version.coerce(latest.version)
          }
        }
      end
    end

    hash
  end
end

#package(path) ⇒ String

Package the given cookbook for distribution outside of berkshelf. If the name attribute is not given, all cookbooks in the Berksfile will be packaged.

Parameters:

  • path (String) —

    the path where the tarball will be created

Returns:

  • (String) —

    the path to the package

Raises:



555
556
557
558
559
560
561
562
563
564
565
566
 
# File 'lib/berkshelf/berksfile.rb', line 555

def package(path)
  packager = Packager.new(path)
  packager.validate!

  outdir = Dir.mktmpdir do |temp_dir|
    Berkshelf.ui.mute { vendor(File.join(temp_dir, 'cookbooks')) }
    packager.run(temp_dir)
  end

  Berkshelf.formatter.package(outdir)
  outdir
end

#retrieve_locked(dependency) ⇒ CachedCookbook

Retrieve information about a given cookbook that is installed by this Berksfile. Unlike #find, which returns a dependency, this method returns the corresponding CachedCookbook for the given name.

Parameters:

  • name (Dependency) —

    the name of the cookbook to find

Returns:

  • (CachedCookbook) —

    the CachedCookbook that corresponds to the given name parameter

Raises:

  • (LockfileNotFound) —

    if there is no lockfile containing that cookbook

  • (CookbookNotFound) —

    if there is a lockfile with a cookbook, but the cookbook is not downloaded



412
413
414
 
# File 'lib/berkshelf/berksfile.rb', line 412

def retrieve_locked(dependency)
  lockfile.retrieve(dependency)
end

#site(*args) ⇒ Object

TODO:

remove in Berkshelf 4.0

Raises:



203
204
205
206
207
208
209
210
211
212
213
214
215
216
 
# File 'lib/berkshelf/berksfile.rb', line 203

def site(*args)
  if args.first == :opscode
    Berkshelf.formatter.deprecation "Your Berksfile contains a site location pointing to the Opscode Community " +
      "Site (site :opscode). Site locations have been replaced by the source location. Change this to: " +
      "'source \"https://supermarket.getchef.com\"' to remove this warning. For more information visit " +
      "https://github.com/berkshelf/berkshelf/wiki/deprecated-locations"
    source(DEFAULT_API_URL)
    return
  end

  raise DeprecatedError.new "Your Berksfile contains a site location. Site locations have been " +
    " replaced by the source location. Please remove your site location and try again. For more information " +
    " visit https://github.com/berkshelf/berkshelf/wiki/deprecated-locations"
end

#source(api_url) ⇒ Array<Source>

Add a Berkshelf API source to use when building the index of known cookbooks. The indexes will be searched in the order they are added. If a cookbook is found in the first source then a cookbook in a second source would not be used.

Examples:

source "https://supermarket.getchef.com"
source "https://berks-api.riotgames.com"

Parameters:

  • api_url (String) —

    url for the api to add

Returns:

Raises:



180
181
182
 
# File 'lib/berkshelf/berksfile.rb', line 180

def source(api_url)
  @sources[api_url] = Source.new(api_url)
end

#source_for(name, version) ⇒ Object

Parameters:

  • dependency (Dependency) —

    the dependency to find the source for



196
197
198
 
# File 'lib/berkshelf/berksfile.rb', line 196

def source_for(name, version)
  sources.find { |source| source.cookbook(name, version) }
end

#sources ⇒ Array<Source>

Returns:



186
187
188
189
190
191
192
 
# File 'lib/berkshelf/berksfile.rb', line 186

def sources
  if @sources.empty?
    raise NoAPISourcesDefined
  else
    @sources.values
  end
end

#update(*names) ⇒ Object

Update the given set of dependencies (or all if no names are given).

Parameters:

  • options (Hash) —

    a customizable set of options



377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
 
# File 'lib/berkshelf/berksfile.rb', line 377

def update(*names)
  validate_lockfile_present!
  validate_cookbook_names!(names)

  Berkshelf.log.info "Updating cookbooks"

  # Calculate the list of cookbooks to unlock
  if names.empty?
    Berkshelf.log.debug "  Unlocking all the things!"
    lockfile.unlock_all
  else
    names.each do |name|
      Berkshelf.log.debug "  Unlocking #{name}"
      lockfile.unlock(name, true)
    end
  end

  # NOTE: We intentionally do NOT pass options to the installer
  self.install
end

#upload(names = []) ⇒ Array<CachedCookbook> #upload(names = [], options = {}) ⇒ Array<CachedCookbook>

Upload the cookbooks installed by this Berksfile

Examples:

Upload all cookbooks

berksfile.upload

Upload the ‘apache2’ and ‘mysql’ cookbooks

berksfile.upload('apache2', 'mysql')

Upload and freeze all cookbooks

berksfile.upload(freeze: true)

Upload and freeze the ‘chef-sugar` cookbook

berksfile.upload('chef-sugar', freeze: true)

Overloads:

  • #upload(names = []) ⇒ Array<CachedCookbook>

    Parameters:

    • names (Array<String>) (defaults to: []) —

      the list of cookbooks (by name) to upload to the remote Chef Server

  • #upload(names = [], options = {}) ⇒ Array<CachedCookbook>

    Parameters:

    • names (Array<String>) (defaults to: []) —

      the list of cookbooks (by name) to upload to the remote Chef Server

    • options (Hash<Symbol, Object>) (defaults to: {}) —

      the list of options to pass to the uploader

    Options Hash (options):

    • :force (Boolean) — default: false —

      upload the cookbooks even if the version already exists and is frozen on the remote Chef Server

    • :freeze (Boolean) — default: true —

      freeze the uploaded cookbooks on the remote Chef Server so that it cannot be overwritten on future uploads

    • :ssl_verify (Hash) — default: true —

      use SSL verification while connecting to the remote Chef Server

    • :halt_on_frozen (Boolean) — default: false —

      raise an exception (FrozenCookbook) if one of the cookbooks already exists on the remote Chef Server and is frozen

    • :server_url (String) —

      the URL (endpoint) to the remote Chef Server

    • :client_name (String) —

      the client name for the remote Chef Server

    • :client_key (String) —

      the client key (pem) for the remote Chef Server

Returns:

  • (Array<CachedCookbook>) —

    the list of cookbooks that were uploaded to the Chef Server

Raises:

  • (UploadFailure) —

    if you are uploading cookbooks with an invalid or not-specified client key

  • (DependencyNotFound) —

    if one of the given cookbooks is not a dependency defined in the Berksfile

  • (FrozenCookbook) —

    if the cookbook being uploaded is a #metadata cookbook and is already frozen on the remote Chef Server; indirect dependencies or non-metadata dependencies are just skipped



536
537
538
539
540
541
542
 
# File 'lib/berkshelf/berksfile.rb', line 536

def upload(*args)
  validate_lockfile_present!
  validate_lockfile_trusted!
  validate_dependencies_installed!

  Uploader.new(self, *args).run
end

#vendor(destination) ⇒ String?

Install the Berksfile or Berksfile.lock and then sync the cached cookbooks into directories within the given destination matching their name.

Parameters:

  • destination (String) —

    filepath to vendor cookbooks to

Returns:

  • (String, nil) —

    the expanded path cookbooks were vendored to or nil if nothing was vendored



576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
 
# File 'lib/berkshelf/berksfile.rb', line 576

def vendor(destination)
  scratch          = Berkshelf.mktmpdir
  chefignore       = nil
  cached_cookbooks = install

  return nil if cached_cookbooks.empty?

  cached_cookbooks.each do |cookbook|
    Berkshelf.formatter.vendor(cookbook, destination)
    cookbook_destination = File.join(scratch, cookbook.cookbook_name)
    FileUtils.mkdir_p(cookbook_destination)

    # Dir.glob does not support backslash as a File separator
    src   = cookbook.path.to_s.gsub('\\', '/')
    files = FileSyncer.glob(File.join(src, '*'))

    chefignore = Ridley::Chef::Chefignore.new(cookbook.path.to_s) rescue nil
    chefignore.apply!(files) if chefignore

    unless cookbook.compiled_metadata?
      cookbook.compile_metadata(cookbook_destination)
    end

    FileUtils.cp_r(files, cookbook_destination)
  end

  # Don't vendor the raw metadata (metadata.rb). The raw metadata is
  # unecessary for the client, and this is required until compiled metadata
  # (metadata.json) takes precedence over raw metadata in the Chef-Client.
  #
  # We can change back to including the raw metadata in the future after
  # this has been fixed or just remove these comments. There is no
  # circumstance that I can currently think of where raw metadata should
  # ever be read by the client.
  #
  # - Jamie
  #
  # See the following tickets for more information:
  #
  #   * https://tickets.opscode.com/browse/CHEF-4811
  #   * https://tickets.opscode.com/browse/CHEF-4810
  FileSyncer.sync(scratch, destination, exclude: ["**/*/metadata.rb"])

  destination
end

#verify ⇒ Object

Perform a validation with ‘Validator#validate` on each cached cookbook associated with the Lockfile of this Berksfile.

This function will return true or raise the first errors encountered.



626
627
628
629
630
631
632
 
# File 'lib/berkshelf/berksfile.rb', line 626

def verify
  validate_lockfile_present!
  validate_lockfile_trusted!
  Berkshelf.formatter.msg "Verifying (#{lockfile.cached.length}) cookbook(s)..."
  Validator.validate(lockfile.cached)
  true
end

#viz(outfile = nil) ⇒ String

Visualize the current Berksfile as a “graph” using DOT.

Parameters:

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

    the name/path to outfile the file

Returns:

  • (String) —

    path the path where the image was written



641
642
643
644
645
646
647
 
# File 'lib/berkshelf/berksfile.rb', line 641

def viz(outfile = nil)
  outfile = File.join(Dir.pwd, outfile || 'graph.png')

  validate_lockfile_present!
  validate_lockfile_trusted!
  Visualizer.from_lockfile(lockfile).to_png(outfile)
end