fpm-cookery 0.32.0 → 0.33.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a8092cdd01badb7c7c69adc60983e1d8b220f878
-  data.tar.gz: b31722bf137e40a7201b1b8b00aaa6adc89ca165
+  metadata.gz: 1bf794a51fecd510948128ab67bb5c795ed3e4c6
+  data.tar.gz: 7020e143e7ba574171c2ace14831df9336e40182
 SHA512:
-  metadata.gz: cf005ab828be976ab4372ea4366155ac3e0c9b21d545d462a7000430ceebd4117c0cff927c7feb17a39873e6057b79d8a5f83e8bb30789f3ff216efc2a2674af
-  data.tar.gz: a3b7a495348df7a575f802f7f4881a4996791a7ae5a4fade00f62111c5da79196fa99c08ee4cfa2a95e339e0caa07511bafcdbad5b074647e6682ee3e335a894
+  metadata.gz: a711e293257e46fbb1b46601c96e4ee90152cb835604ab30e75fc10f204f54f2b5d19591ef9a6777ea2b085dc50097554611517a1601aa1a886e4008dbb193ff
+  data.tar.gz: 0625f2d75df8e1aaafdeedcf2796ffc4b65d57a8648cbdd655aa60ae09f353fa6eb60ee5bf8f5d6ae03207c3bdb61a12f601e611cdc62474efa32107c31d6746

data/.gitignore

@@ -12,6 +12,8 @@ tmp-dest/
 .vagrant
 Vagrantfile
 /vendor
+/coverage
+/doc
 
 # vim backups
 *~

data/.travis.yml

@@ -1,10 +1,13 @@
 sudo: false
+cache: bundler
 script: bundle exec rake spec
 rvm:
   - 1.9.3
   - 2.0.0
-  - 2.1.1
-  - 2.2.1
+  - 2.1.10
+  - 2.2.5
+  - 2.3.1
+  - 2.4.1
   - ruby-head
 
 matrix:

data/CHANGELOG.md

@@ -1,3 +1,22 @@
+# v0.33.0
+* Hiera lookups of recipe data from templated YAML files. (BaxterStockman / #150)
+* Travis-CI build matrix improvements. (thedrow / #155)
+* Expose `lsbcodename` fact. (thedrow / #158)
+* Improved build cookie generator. (BaxterStockman / #157)
+* Improved facter usage. (BaxterStockman / #167)
+* Alpine (apk) package support. (lloydpick / #162)
+* Fix typos and missing tests. (lloydpick / #163)
+* Add `inspect` command. (BaxterStockman / #165)
+* json dependency fix to work with older Rubies. (BaxterStockman / #166)
+* Bug fix when using local directory sources. (#164)
+* Make vendor delimiter configurable. (#169)
+* Ensure consistend extracted source value from all source handlers. (#170)
+* Add default package version and guard against nil/empty versions. (BaxterStockman / #176)
+* Documenting the use of Hiera in recipes. (BaxterStockman / #184)
+* Ruby pre-2.0 compatibility fix. (BaxterStockman / #183)
+* Add "safe\_yaml" dependency. (davewongillies / #186, #154)
+* Add `rpm_dist` method. (sfzylad / #190)
+
 # v0.32.0
 * Add `sourcedir` accessor that holds the path to the extracted source. (#132)
 * Add support for DirRecipe and Directory Handler. (cas-ei / #147)

data/Rakefile

@@ -5,3 +5,37 @@ desc 'Run all specs'
 RSpec::Core::RakeTask.new(:spec)
 
 task :default => :spec
+
+namespace :docs do |ns|
+  require 'systemu'
+
+  docs_dir = File.join(File.dirname(File.expand_path(__FILE__)), 'docs')
+
+  Dir.chdir docs_dir do
+    sphinxbuild = ENV['SPHINXBUILD'] || 'sphinx-build'
+
+    status, stdout, stderr = systemu "make SPHINXBUILD=#{sphinxbuild} help"
+    if status != 0 and Rake.verbose
+      $stderr.puts '# Unable to load tasks in the `docs` namespace:'
+      stderr.each_line { |l| $stderr.puts "# #{l}" }
+    end
+
+    desc 'clean up doc builds'
+    task 'clean' do
+      Dir.chdir docs_dir do
+        system "make SPHINXBUILD=#{sphinxbuild} clean"
+      end
+    end
+
+    stdout.each_line.grep(/^\s+(\w+?)\s+(.*)$/) do
+      t, d = $1, $2
+
+      desc d
+      task t do
+        Dir.chdir docs_dir do
+          system "make SPHINXBUILD=#{sphinxbuild} #{t}"
+        end
+      end
+    end
+  end
+end

data/docs/index.rst

@@ -26,6 +26,7 @@ Documentation Contents
    :maxdepth: 2
 
    pages/getting-started
+   pages/using-hiera
 
 
 Indices and tables

data/docs/pages/using-hiera.rst

@@ -0,0 +1,285 @@
+Using Hiera
+===========
+
+`Hiera <http://docs.puppetlabs.com/hiera>`_ is a hierarchical key-value lookup
+tool from Puppet Labs that, integrated with fpm-cookery, allows you to improve
+your package builds by:
+
+* Separating data from build logic,
+* Selectively overriding particular recipe attributes for different platforms,
+  software versions, etc., and
+* Staying DRY by reusing data via the ``hiera`` and ``scope``
+  :ref:`interpolation methods <hiera-interpolation-in-data-files>`.
+
+Configuring Hiera
+-----------------
+
+Controlling the Lookup Hierarchy
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, FPM-Cookery looks for Hiera data files under the ``config``
+subdirectory of the directory containing the target recipe. You can override
+this through the ``--data-dir`` option to ``fpm-cook``. You can also set the
+data file directory via the ``datadir=`` class method while defining the recipe
+class:
+
+.. code-block:: ruby
+
+    class FreshRecipe < FPM::Cookery::Recipe
+      datadir = "/somewhere/other/than/#{File.dirname(__FILE__)}/config"
+    end
+
+.. note::
+
+    Part of the recipe initialization process involves :ref:`automatically
+    applying data<hiera-automatic-application-of-hiera-data>` contained in the
+    files in the current ``datadir``.  If you change ``datadir`` after the
+    ``initialize`` method completes, you must call the ``apply`` method
+    manually to reconfigure the recipe according to the files in the the new
+    ``datadir``.
+
+When retrieving recipe data, fpm-cookery observes the following hierarchy of
+files under ``datadir``, ordered from highest to lowest precedence:
+
++--------------------------------+--------------------------------------------+
+| Path                           | Description                                |
++================================+============================================+
+| ``"#{recipe.platform}.yaml"``, | The platform for which the recipe is being |
+| ``"#{recipe.platform}.json"``  | built.  Corresponds to Facter's            |
+|                                | ``operatingsystem`` fact, except that all  |
+|                                | characters are lowercase. For instance, if |
+|                                | ``operatingsystem`` is ``ArchLinux``,      |
+|                                | ``recipe.platform`` will be ``archlinux``. |
++--------------------------------+--------------------------------------------+
+| ``"#{recipe.target}.yaml"``,   | The target package type.  Options span all |
+| ``"#{recipe.target}.json"``    | package types that FPM can build,          |
+|                                | including include ``rpm``, ``apk``,        |
+|                                | ``deb``, ``osxpkg``, and others.           |
++--------------------------------+--------------------------------------------+
+| ``"common.yaml"``,             | Intended for configuration data that is    |
+| ``"common.json"``              | common to all builds.                      |
++--------------------------------+--------------------------------------------+
+
+You can further influence the lookup hierarchy by setting the environment
+variable ``FPM_HIERARCHY``.  The value should be string containing a
+colon-separated list of filename stems.  For example::
+
+  $ FPM_HIERARCHY=centos:rhel:el fpm-cook package
+
+prepends ``centos``, ``rhel``, and ``el`` to the search hierarchy, causing
+fpm-cookery to attempt load data from ``centos.yaml``, ``rhel.yaml``,
+``el.yaml``, and their ``.json`` counterparts.  The final hierarchy is:
+
+* ``"centos.yaml"``
+* ``"rhel.yaml"``
+* ``"el.yaml"``
+* ``"#{recipe.platform}.yaml"``
+* ``"#{recipe.target}.yaml"``
+* ``"common.yaml"``
+
+Other Settings
+^^^^^^^^^^^^^^
+
+You can exercise more fine-grained control by providing the path to a Hiera
+configuration file via the ``--hiera-config`` option. See `the Hiera docs
+<http://docs.puppetlabs.com/hiera/3.0/configuring.html>`_ for available
+configuration file options.
+
+Hiera in Recipes
+----------------
+
+Lookups
+^^^^^^^
+
+fpm-cookery provides the ``lookup`` class method on all classes that inherit
+from ``FPM::Cookery::Recipe``, as well as an instance method of the same name.
+``lookup`` takes one mandatory argument: a key to be looked up in the Hiera
+data files.  If Hiera locates the key, ``lookup`` returns the corresponding
+value; otherwise ``lookup`` returns ``nil``.
+
+Writing Data Files
+^^^^^^^^^^^^^^^^^^
+
+See `the Hiera data sources documentation <http://docs.puppetlabs.com/hiera/3.0/data_sources.html>`_
+for an overview of Hiera data sources.
+
+.. note::
+
+    Please ensure that your data files use the extensions ``.yaml`` or
+    ``.json``, as appropriate -- Hiera ignores files with any other
+    extension.
+
+You'll probably find data files most useful for defining recipe attributes.
+However, key-value mappings in Hiera data sources need not correspond to recipe
+attributes -- you can store any data you like as long as it is valid YAML or
+JSON:
+
+.. code-block:: yaml
+
+    name: custom-package
+    version: '2.1.6'
+    some_arbitrary_data:
+      - thing one
+      - thing two
+      - thing: three
+        is_a: hash
+
+*(later on...)*
+
+.. code-block:: ruby
+
+    CustomPackageRecipe.lookup('some_arbitrary_data')
+      #=> ['thing one', 'thing two', {'thing' => 'three', 'is_a' => 'hash'}]
+
+.. _hiera-interpolation-in-data-files:
+
+Interpolation in Data Files
+'''''''''''''''''''''''''''
+
+Within a data file, the ``%{scope("...")}`` method interpolates values from the
+following sources:
+
+* The current recipe class
+* ``FPM::Cookery::Facts``
+* `Facter <https://puppetlabs.com/facter>`_ facts
+
+The ``%{hiera("...")}`` method interpolates values looked up in the data files
+themselves.
+
+Say you are on an ``x86_64`` system, and consider the following YAML data:
+
+.. code-block:: yaml
+
+    name: something-clever
+    version: '0.9.0'
+    source: 'https://www.sporkforge.net/archive/%{scope("arch")}/%{hiera("name")}-%{hiera("version")}.tar.gz'
+
+``source`` evaluates like so:
+
+.. code-block:: ruby
+
+    SomethingCleverRecipe.lookup('source')
+      #=> 'https://www.sporkforge.net/archive/x86_64/something-clever-0.9.0.tar.gz'
+
+.. _hiera-automatic-application-of-hiera-data:
+
+Symbolized Hash Keys
+''''''''''''''''''''
+
+Ruby's YAML library automatically converts hash keys prefixed with colons into
+symbols.  This is good to know when using Hiera to store data relevant to
+methods that expect symbols in their arguments -- for instance, ``source``.
+
+**BAD**:
+
+.. code-block:: yaml
+
+    source:
+      - 'git://gogs.myhostname.info/labyrinthm/bowie.git'
+      - with: git
+        tag: 'v1.1.3'
+
+**GOOD**:
+
+.. code-block:: yaml
+
+    source:
+      - 'git://gogs.myhostname.info/labyrinthm/bowie.git'
+      - :with: git
+        :tag: 'v1.1.3'
+
+Method Signatures and Unpacking Data Structures
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+fpm-cookery tries to Do What You Mean when dealing when loading data from
+Hiera, but there are some subtleties relating to method signatures that you
+should be aware of.
+
+Methods that expect a single argument are the simplest case -- just provide a
+single key-value pair:
+
+.. code-block:: yaml
+
+    name: 'myrecipe'
+
+Methods that expect multiple arguments should be given as a list:
+
+.. code-block:: yaml
+
+    depends:
+      - openssl-devel
+      - docker-compose
+
+fpm-cookery will automatically unpack the argument list with Ruby's splat
+(``*``) operator when invoking the method.
+
+Methods that expect a hash should be given as a series of key-value pairs:
+
+.. code-block:: yaml
+
+    environment:
+      LC_ALL: C
+      SHELLOPTS: xtrace
+      PAGER: cat
+
+fpm-cookery will *merge* these pairs into whatever data is already assigned as
+the value of the attribute, rather than replacing it.
+
+Some methods expect a heterogeneous list of arguments, ``source`` being the
+most important of these.  If you want to pass options to ``source`` or other
+such methods, use the following technique:
+
+.. code-block:: yaml
+
+    source:
+      - 'https://my.subversion-server.net/trunk'
+      - :revision: 92834
+        :externals: false
+
+This translates to a Ruby ``Array``:
+
+.. code-block:: ruby
+
+    ['https://my.subversion-server.net/trunk', {:revision => 92834, :externals => false}]
+
+For simple sources that consist only of a URL, you can do:
+
+.. code-block:: yaml
+
+    source: 'git://our.internal-git.com/foo/bar.git'
+
+Automatic Application of Hiera Data
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As part of the recipe initialization process, fpm-cookery calls ``lookup`` to
+retrieve any Hiera-defined values corresponding to recipe attribute names such
+as ``name``, ``version``, and ``source``.  If Hiera can locate the key,
+fpm-cookery automatically sets the relevant attribute to the retrieved value.
+
+Attributes defined in Hiera data files take precedence over
+attributes defined in ``recipe.rb``:
+
+.. code-block:: yaml
+
+    --- # common.yaml
+    source: https://www.repourl.org/source/neato-0.2.4-7.tar.bz2
+
+.. code-block:: ruby
+
+    # recipe.rb
+    class NeatoRecipe < FPM::Cookery::Recipe
+      source 'https://www.repourl.org/source/nightly/neato-nightly.tar.gz'
+    end
+
+This results in:
+
+.. code-block:: ruby
+
+    NeatoRecipe.source #=> https://www.repourl.org/source/neato-0.2.4-7.tar.bz2
+
+Examples
+--------
+
+See the `Redis recipe
+<https://github.com/bernd/fpm-cookery/tree/master/recipes/redis>`_ for an
+example of fpm-cookery and Hiera in action.

data/fpm-cookery.gemspec

@@ -18,11 +18,16 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
 
-  s.add_development_dependency "rspec", "~> 3.0"
+  s.add_development_dependency "rspec", "~> 3.3"
   s.add_development_dependency "rake"
+  s.add_development_dependency "pry"
+  s.add_development_dependency "simplecov", "~> 0.11"
   s.add_runtime_dependency "fpm", "~> 1.1"
   s.add_runtime_dependency "facter"
   s.add_runtime_dependency "puppet", "~> 3.4"
   s.add_runtime_dependency "addressable", "~> 2.3.8"
   s.add_runtime_dependency "systemu"
+  s.add_runtime_dependency "json", ">= 1.7.7", "< 2.0"
+  s.add_runtime_dependency "json_pure", ">= 1.7.7", "< 2.0"
+  s.add_runtime_dependency "safe_yaml", "~> 1.0.4"
 end

data/lib/fpm/cookery/book.rb

@@ -1,10 +1,13 @@
 require 'singleton'
+require 'fpm/cookery/path'
 
 module FPM
   module Cookery
     class Book
       include Singleton
 
+      attr_accessor :filename, :config
+
       def initialize
         @recipe = nil
       end
@@ -12,13 +15,37 @@ module FPM
       # Load the given file and instantiate an object. Wrap the class in an
       # anonymous module to avoid namespace cluttering. (see Kernel.load)
       def load_recipe(filename, config, &callback)
-        Kernel.load(filename, true)
-        callback.call(@recipe.new(filename, config))
+        @filename = FPM::Cookery::Path.new(filename).realpath
+        @config = config
+
+        Kernel.load(@filename.to_path, true)
+        callback.call(@recipe.new)
       end
 
       def add_recipe_class(klass)
         @recipe = klass
       end
+
+      # Hijack the recipe singleton to make the +filename+ and +config+ objects
+      # available when a descendent of BaseRecipe is declared.  This makes it
+      # possible to do Hiera lookups at class definition time.
+      def inject_class_methods!(klass)
+        # It's necessary to close over local variables because the receiver
+        # changes within the scope of +define_method+, so +self.filename+ would
+        # wrongly refer to +singleton_klass.filename+.
+        filename = self.filename
+        config = self.config
+
+        singleton_klass = (class << klass ; self ; end)
+
+        singleton_klass.send(:define_method, :filename) do
+          filename
+        end
+
+        singleton_klass.send(:define_method, :config) do
+          config
+        end
+      end
     end
   end
 end