Class: Puppet::Module

Inherits:
Object show all
Includes:
Util::Logging
Defined in:
lib/puppet/module.rb

Overview

Support for modules

Defined Under Namespace

Classes: Error, IncompatibleModule, IncompatiblePlatform, InvalidFilePattern, InvalidName, MissingMetadata, MissingModule, UnsupportedPlatform

Constant Summary collapse

FILETYPES = 
{
  "manifests" => "manifests",
  "files" => "files",
  "templates" => "templates",
  "plugins" => "lib",
  "pluginfacts" => "facts.d",
}

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Util::Logging

#clear_deprecation_warnings, #deprecation_warning, #format_exception, #get_deprecation_offender, #log_and_raise, #log_deprecations_to_file, #log_exception, #puppet_deprecation_warning, #send_log

Constructor Details

#initialize(name, path, environment) ⇒ Module

Returns a new instance of Module.



42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/puppet/module.rb', line 42

def initialize(name, path, environment)
  @name = name
  @path = path
  @environment = environment

  assert_validity

  load_metadata if has_metadata?

  validate_puppet_version

  @absolute_path_to_manifests = Puppet::FileSystem::PathPattern.absolute(manifests)
end

Instance Attribute Details

#author ⇒ Object 



40
41
42
 
# File 'lib/puppet/module.rb', line 40

def author
  @author
end

#dependencies ⇒ Object 



39
40
41
 
# File 'lib/puppet/module.rb', line 39

def dependencies
  @dependencies
end

#description ⇒ Object 



40
41
42
 
# File 'lib/puppet/module.rb', line 40

def description
  @description
end

#environment ⇒ Object 



36
37
38
 
# File 'lib/puppet/module.rb', line 36

def environment
  @environment
end

#forge_name ⇒ Object 



39
40
41
 
# File 'lib/puppet/module.rb', line 39

def forge_name
  @forge_name
end

#license ⇒ Object 



40
41
42
 
# File 'lib/puppet/module.rb', line 40

def license
  @license
end

#metadata ⇒ Object (readonly) 



36
37
38
 
# File 'lib/puppet/module.rb', line 36

def metadata
  @metadata
end

#name ⇒ Object (readonly) 



36
37
38
 
# File 'lib/puppet/module.rb', line 36

def name
  @name
end

#path ⇒ Object (readonly) 



36
37
38
 
# File 'lib/puppet/module.rb', line 36

def path
  @path
end

#project_page ⇒ Object 



40
41
42
 
# File 'lib/puppet/module.rb', line 40

def project_page
  @project_page
end

#puppetversion ⇒ Object 



40
41
42
 
# File 'lib/puppet/module.rb', line 40

def puppetversion
  @puppetversion
end

#source ⇒ Object 



40
41
42
 
# File 'lib/puppet/module.rb', line 40

def source
  @source
end

#summary ⇒ Object 



40
41
42
 
# File 'lib/puppet/module.rb', line 40

def summary
  @summary
end

#version ⇒ Object 



40
41
42
 
# File 'lib/puppet/module.rb', line 40

def version
  @version
end

Class Method Details

.find(modname, environment = nil) ⇒ Object

Find and return the module that path belongs to. If path is absolute, or if there is no module whose name is the first component of path, return nil



29
30
31
32
33
34
 
# File 'lib/puppet/module.rb', line 29

def self.find(modname, environment = nil)
  return nil unless modname
  # Unless a specific environment is given, use the current environment
  env = environment ? Puppet.lookup(:environments).get!(environment) : Puppet.lookup(:current_environment)
  env.module(modname)
end

Instance Method Details

#all_manifests ⇒ Object 



157
158
159
160
161
 
# File 'lib/puppet/module.rb', line 157

def all_manifests
  return [] unless Puppet::FileSystem.exist?(manifests)

  Dir.glob(File.join(manifests, '**', '*.{rb,pp}'))
end

#dependencies_as_modules ⇒ Object 



198
199
200
201
202
203
204
205
206
207
 
# File 'lib/puppet/module.rb', line 198

def dependencies_as_modules
  dependent_modules = []
  dependencies and dependencies.each do |dep|
    author, dep_name = dep["name"].split('/')
    found_module = environment.module(dep_name)
    dependent_modules << found_module if found_module
  end

  dependent_modules
end

#has_external_facts? ⇒ Boolean

Returns:

  • (Boolean) 


183
184
185
 
# File 'lib/puppet/module.rb', line 183

def has_external_facts?
  File.directory?(plugin_fact_directory)
end

#has_local_changes? ⇒ Boolean

Returns:

  • (Boolean) 


213
214
215
216
217
218
 
# File 'lib/puppet/module.rb', line 213

def has_local_changes?
  Puppet.deprecation_warning("This method is being removed.")
  require 'puppet/module_tool/applications'
  changes = Puppet::ModuleTool::Applications::Checksummer.run(path)
  !changes.empty?
end

#has_metadata? ⇒ Boolean

Returns:

  • (Boolean) 


56
57
58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/puppet/module.rb', line 56

def has_metadata?
  return false unless metadata_file

  return false unless Puppet::FileSystem.exist?(metadata_file)

  begin
    metadata =  JSON.parse(File.read(metadata_file))
  rescue JSON::JSONError => e
    Puppet.debug("#{name} has an invalid and unparsable metadata.json file.  The parse error: #{e.message}")
    return false
  end

  return metadata.is_a?(Hash) && !metadata.keys.empty?
end

#license_file ⇒ Object 



109
110
111
112
113
114
 
# File 'lib/puppet/module.rb', line 109

def license_file
  return @license_file if defined?(@license_file)

  return @license_file = nil unless path
  @license_file = File.join(path, "License")
end

#load_metadata ⇒ Object 



116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/puppet/module.rb', line 116

def load_metadata
  @metadata = data = JSON.parse(File.read(metadata_file))
  @forge_name = data['name'].gsub('-', '/') if data['name']

  [:source, :author, :version, :license, :puppetversion, :dependencies].each do |attr|
    unless value = data[attr.to_s]
      unless attr == :puppetversion
        raise MissingMetadata, "No #{attr} module metadata provided for #{self.name}"
      end
    end

    # NOTICE: The fallback to `versionRequirement` is something we'd like to
    # not have to support, but we have a reasonable number of releases that
    # don't use `version_requirement`. When we can deprecate this, we should.
    if attr == :dependencies
      value.tap do |dependencies|
        dependencies.each do |dep|
          dep['version_requirement'] ||= dep['versionRequirement'] || '>= 0.0.0'
        end
      end
    end

    send(attr.to_s + "=", value)
  end
end

#local_changes ⇒ Object 



220
221
222
223
224
 
# File 'lib/puppet/module.rb', line 220

def local_changes
  Puppet.deprecation_warning("This method is being removed.")
  require 'puppet/module_tool/applications'
  Puppet::ModuleTool::Applications::Checksummer.run(path)
end

#match_manifests(rest) ⇒ Object

Return the list of manifests matching the given glob pattern, defaulting to ‘init.pp,rb’ for empty modules.



144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/puppet/module.rb', line 144

def match_manifests(rest)
  if rest
    wanted_manifests = wanted_manifests_from(rest)
    searched_manifests = wanted_manifests.glob.reject { |f| FileTest.directory?(f) }
  else
    searched_manifests = []
  end

  # (#4220) Always ensure init.pp in case class is defined there.
  init_manifests = [manifest("init.pp"), manifest("init.rb")].compact
  init_manifests + searched_manifests
end

#metadata_file ⇒ Object 



163
164
165
166
167
168
 
# File 'lib/puppet/module.rb', line 163

def metadata_file
  return @metadata_file if defined?(@metadata_file)

  return @metadata_file = nil unless path
  @metadata_file = File.join(path, "metadata.json")
end

#modulepath ⇒ Object 



170
171
172
 
# File 'lib/puppet/module.rb', line 170

def modulepath
  File.dirname(path) if path
end

#plugin_directory ⇒ Object

Find all plugin directories. This is used by the Plugins fileserving mount.



175
176
177
 
# File 'lib/puppet/module.rb', line 175

def plugin_directory
  subpath("lib")
end

#plugin_fact_directory ⇒ Object 



179
180
181
 
# File 'lib/puppet/module.rb', line 179

def plugin_fact_directory
  subpath("facts.d")
end

#required_by ⇒ Object 



209
210
211
 
# File 'lib/puppet/module.rb', line 209

def required_by
  environment.module_requirements[self.forge_name] || {}
end

#supports(name, version = nil) ⇒ Object 



187
188
189
190
 
# File 'lib/puppet/module.rb', line 187

def supports(name, version = nil)
  @supports ||= []
  @supports << [name, version]
end

#to_s ⇒ Object 



192
193
194
195
196
 
# File 'lib/puppet/module.rb', line 192

def to_s
  result = "Module #{name}"
  result += "(#{path})" if path
  result
end

#unmet_dependencies ⇒ Object

Identify and mark unmet dependencies. A dependency will be marked unmet for the following reasons:

* not installed and is thus considered missing
* installed and does not meet the version requirements for this module
* installed and doesn't use semantic versioning

Returns a list of hashes representing the details of an unmet dependency.

Example:

[
  {
    :reason => :missing,
    :name   => 'puppetlabs-mysql',
    :version_constraint => 'v0.0.1',
    :mod_details => {
      :installed_version => '0.0.1'
    }
    :parent => {
      :name    => 'puppetlabs-bacula',
      :version => 'v1.0.0'
    }
  }
]



252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
 
# File 'lib/puppet/module.rb', line 252

def unmet_dependencies
  unmet_dependencies = []
  return unmet_dependencies unless dependencies

  dependencies.each do |dependency|
    forge_name = dependency['name']
    version_string = dependency['version_requirement'] || '>= 0.0.0'

    dep_mod = begin
      environment.module_by_forge_name(forge_name)
    rescue
      nil
    end

    error_details = {
      :name => forge_name,
      :version_constraint => version_string.gsub(/^(?=\d)/, "v"),
      :parent => {
        :name => self.forge_name,
        :version => self.version.gsub(/^(?=\d)/, "v")
      },
      :mod_details => {
        :installed_version => dep_mod.nil? ? nil : dep_mod.version
      }
    }

    unless dep_mod
      error_details[:reason] = :missing
      unmet_dependencies << error_details
      next
    end

    if version_string
      begin
        required_version_semver_range = SemVer[version_string]
        actual_version_semver = SemVer.new(dep_mod.version)
      rescue ArgumentError
        error_details[:reason] = :non_semantic_version
        unmet_dependencies << error_details
        next
      end

      unless required_version_semver_range.include? actual_version_semver
        error_details[:reason] = :version_mismatch
        unmet_dependencies << error_details
        next
      end
    end
  end

  unmet_dependencies
end

#validate_puppet_version ⇒ Object

Raises:



305
306
307
308
 
# File 'lib/puppet/module.rb', line 305

def validate_puppet_version
  return unless puppetversion and puppetversion != Puppet.version
  raise IncompatibleModule, "Module #{self.name} is only compatible with Puppet version #{puppetversion}, not #{Puppet.version}"
end