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.chef.io".freeze
EXCLUDED_VCS_FILES_WHEN_VENDORING =

Don’t vendor VCS files. Reference GNU tar –exclude-vcs: www.gnu.org/software/tar/manual/html_section/tar_49.html

[".arch-ids", "{arch}", ".bzr", ".bzrignore", ".bzrtags", "CVS", ".cvsignore", "_darcs", ".git", ".hg", ".hgignore", ".hgrags", "RCS", "SCCS", ".svn", "**/.git", "**/.svn"].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.

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



67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/berkshelf/berksfile.rb', line 67

def initialize(path, options = {})
  @filepath         = File.expand_path(path)
  @dependencies     = {}
  @sources          = {}
  @delete           = options[:delete]

  # defaults for what solvers to use
  @required_solver  = nil
  @preferred_solver = :gecode

  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) 



46
47
48
 
# File 'lib/berkshelf/berksfile.rb', line 46

def filepath
  @filepath
end

#preferred_solver ⇒ Symbol (readonly) 



54
55
56
 
# File 'lib/berkshelf/berksfile.rb', line 54

def preferred_solver
  @preferred_solver
end

#required_solver ⇒ Symbol (readonly) 



50
51
52
 
# File 'lib/berkshelf/berksfile.rb', line 50

def required_solver
  @required_solver
end

Class Method Details

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

Raises:



23
24
25
26
27
28
29
30
31
 
# File 'lib/berkshelf/berksfile.rb', line 23

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.



13
14
15
16
17
 
# File 'lib/berkshelf/berksfile.rb', line 13

def from_options(options = {})
  options[:berksfile] ||= File.join(Dir.pwd, Berkshelf::DEFAULT_FILENAME)
  symbolized = Hash[options.map { |k, v| [k.to_sym, v] }]
  from_file(options[:berksfile], symbolized.select { |k,| i{except only delete}.include? k })
end

Instance Method Details

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



373
374
375
 
# File 'lib/berkshelf/berksfile.rb', line 373

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.

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

Raises:



281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
 
# File 'lib/berkshelf/berksfile.rb', line 281

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]
    unless (@dependencies[name].groups & groups).empty?
      raise DuplicateDependencyDefined.new(name)
    end
  end

  # this appears to be dead code
  # if options[:path]
  #  metadata_file = File.join(options[:path], "metadata.rb")
  # end

  options[:constraint] = constraint

  @dependencies[name] = Dependency.new(self, name, options)
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

    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

    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:



148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/berkshelf/berksfile.rb', line 148

def cookbook(*args)
  options = args.last.is_a?(Hash) ? args.pop : {}
  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.

See Also:

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


330
331
332
 
# File 'lib/berkshelf/berksfile.rb', line 330

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

#dependencies ⇒ Array<Dependency> 



313
314
315
 
# File 'lib/berkshelf/berksfile.rb', line 313

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

#extension(name) ⇒ true

Activate a Berkshelf extension at runtime.

Examples:

Activate the Mercurial extension

extension 'hg'

Raises:

  • (LoadError) —

    if the extension cannot be loaded



102
103
104
105
106
107
108
 
# File 'lib/berkshelf/berksfile.rb', line 102

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.



340
341
342
 
# File 'lib/berkshelf/berksfile.rb', line 340

def find(name)
  @dependencies[name]
end

#find_chefignore(path) ⇒ Object

backcompat with ridley lookup of chefignore



608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
 
# File 'lib/berkshelf/berksfile.rb', line 608

def find_chefignore(path)
  filename = "chefignore"

  Pathname.new(path).ascend do |dir|
    next unless dir.directory?

    [
      dir.join(filename),
      dir.join("cookbooks", filename),
      dir.join(".chef",     filename),
    ].each do |possible|
      return possible.expand_path.to_s if possible.exist?
    end
  end

  nil
end

#group(*args) ⇒ Object 



163
164
165
166
167
 
# File 'lib/berkshelf/berksfile.rb', line 163

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

#groups ⇒ Hash 



358
359
360
361
362
363
364
365
366
367
 
# File 'lib/berkshelf/berksfile.rb', line 358

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.



307
308
309
310
 
# File 'lib/berkshelf/berksfile.rb', line 307

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.

Raises:

  • (OutdatedDependency) —

    if the lockfile constraints do not satisfy the Berksfile constraints



404
405
406
 
# File 'lib/berkshelf/berksfile.rb', line 404

def install
  Installer.new(self).run
end

#list ⇒ Hash<Dependency, CachedCookbook>

The cached cookbooks installed by this Berksfile.

Raises:



460
461
462
463
464
465
466
 
# File 'lib/berkshelf/berksfile.rb', line 460

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.



737
738
739
 
# File 'lib/berkshelf/berksfile.rb', line 737

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.

Options Hash (options):

  • :path (String) —

    path to the metadata file



178
179
180
181
182
183
184
185
186
187
 
# File 'lib/berkshelf/berksfile.rb', line 178

def metadata(options = {})
  path = options[:path] || File.dirname(filepath)

  loader = Chef::Cookbook::CookbookVersionLoader.new(path)
  loader.load!
  cookbook_version = loader.cookbook_version
  metadata = cookbook_version.metadata

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

#outdated(*names, include_non_satisfying: false) ⇒ 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.chef.io"> #=> #<Version 2.6.2>
    }
  }
}



490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
 
# File 'lib/berkshelf/berksfile.rb', line 490

def outdated(*names, include_non_satisfying: false)
  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|
        (include_non_satisfying || dependency.version_constraint.satisfies?(cookbook.version)) &&
          Semverse::Version.coerce(cookbook.version) > dependency.locked_version
      end.sort_by(&: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.

Raises:



594
595
596
597
598
599
600
601
602
603
604
605
 
# File 'lib/berkshelf/berksfile.rb', line 594

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.

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



447
448
449
 
# File 'lib/berkshelf/berksfile.rb', line 447

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

#solver(name, precedence = :preferred) ⇒ Object

Configure a specific engine for the ‘solve’ gem to use when computing dependencies. You may optionally specify how strong a requirement this is. If omitted, the default precedence is :preferred.

If :required is specified and cannot be loaded, Resolver#resolve will raise an ArgumentError. If :preferred is specified and cannot be loaded, Resolver#resolve silently catch any errors and use whatever default method the ‘solve’ gem provides (as of 2.0.1, solve defaults to :ruby).

Examples:

solver :gecode
solver :gecode, :preferred
solver :gecode, :required
solver :ruby
solver :ruby, :preferred
solver :ruby, :required

Raises:



237
238
239
240
241
242
243
244
245
 
# File 'lib/berkshelf/berksfile.rb', line 237

def solver(name, precedence = :preferred)
  if name && precedence == :required
    @required_solver = name
  elsif name && precedence == :preferred
    @preferred_solver = name
  else
    raise ArgumentError, "Invalid solver precedence ':#{precedence}'"
  end
end

#source(api_url, **options) ⇒ 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.chef.io"
source "https://berks-api.riotgames.com"

Raises:



207
208
209
210
 
# File 'lib/berkshelf/berksfile.rb', line 207

def source(api_url, **options)
  source = Source.new(self, api_url, **options)
  @sources[source.uri.to_s] = source
end

#source_for(name, version) ⇒ Object 



259
260
261
 
# File 'lib/berkshelf/berksfile.rb', line 259

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

#sources ⇒ Array<Source> 



249
250
251
252
253
254
255
 
# File 'lib/berkshelf/berksfile.rb', line 249

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).



412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
 
# File 'lib/berkshelf/berksfile.rb', line 412

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
  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 = [], options = {}) ⇒ Array<CachedCookbook>

    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

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



575
576
577
578
579
580
581
 
# File 'lib/berkshelf/berksfile.rb', line 575

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.



634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
 
# File 'lib/berkshelf/berksfile.rb', line 634

def vendor(destination)
  Dir.mktmpdir("vendor") do |scratch|
    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.tr('\\', "/")
      files = FileSyncer.glob(File.join(src, "**/*"))

      # strip directories
      files.reject! { |file_path| File.directory?(file_path) }

      # convert to relative Pathname objects for chefignore
      files.map! { |file_path| Chef::Util::PathHelper.relative_path_from(cookbook.path.to_s, file_path) }

      chefignore = Chef::Cookbook::Chefignore.new(find_chefignore(cookbook.path.to_s) || cookbook.path.to_s)

      # apply chefignore
      files.reject! { |file_path| chefignore.ignored?(file_path) }

      # convert Pathname objects back to strings
      files.map!(&:to_s)

      # copy each file to destination
      files.each do |rpath|
        FileUtils.mkdir_p( File.join(cookbook_destination, File.dirname(rpath)) )
        FileUtils.cp( File.join(cookbook.path.to_s, rpath), File.join(cookbook_destination, rpath) )
      end

      cookbook.compile_metadata(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: EXCLUDED_VCS_FILES_WHEN_VENDORING, delete: @delete)
  end

  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.



698
699
700
701
702
703
704
 
# File 'lib/berkshelf/berksfile.rb', line 698

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, format = "png") ⇒ String

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



713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
 
# File 'lib/berkshelf/berksfile.rb', line 713

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

  validate_lockfile_present!
  validate_lockfile_trusted!
  vizualiser = Visualizer.from_lockfile(lockfile)

  case format
  when "dot"
    vizualiser.to_dot_file(outfile)
  when "png"
    vizualiser.to_png(outfile)
  else
    raise ConfigurationError, "Vizualiser format #{format} not recognised."
  end
end