op-ct / rubygem-simp-rake-helpers

Rake Helpers for the SIMP Rake tasks

simp-rake-helpers

Table of Contents

• Overview
  • This gem is part of SIMP
  • Features
• Setup
  • Gemfile
• Usage
  • In a Puppet module
  • Environment Variables
  • In a Ruby Gem
  • Generating RPMs
    • RPM Changelog
    • RPM Dependencies
• Reference
  • simp/rake/rpm
    • rake pkg:rpm
    • rake pkg:tar
• Limitations
• Development
  • License
  • History

Overview

The simp-rake-helpers gem provides common Rake tasks to support the SIMP build process.

This gem is part of SIMP

This gem is part of (the build tooling for) the System Integrity Management Platform, a compliance-management framework built on Puppet.

Features

• Customizable RPM packaging based on a Puppet module's metadata.json
• RPM signing
• Rubygem packaging

Setup

Gemfile

# Variables:
#
# SIMP_GEM_SERVERS | a space/comma delimited list of rubygem servers
# PUPPET_VERSION   | specifies the version of the puppet gem to load
puppetversion = ENV.key?('PUPPET_VERSION') ? "#{ENV['PUPPET_VERSION']}" : '~>3'
gem_sources   = ENV.key?('SIMP_GEM_SERVERS') ? ENV['SIMP_GEM_SERVERS'].split(/[, ]+/) : ['https://rubygems.org']

gem_sources.each { |gem_source| source gem_source }

group :test do
  gem 'puppet', puppetversion
  gem 'beaker-rspec'
  gem 'vagrant-wrapper'
end

Usage

In a Puppet module

Within the project's Rakefile:

require 'simp/rake/pupmod/helpers'

Simp::Rake::Pupmod::Helpers.new(File.dirname(__FILE__))

Environment Variables

Some environment variables have been added to help you work with different types of testing scenarios and are documented below.

By default, only the modules found in the local .fixtures.yml file will be included.

• SIMP_RSPEC_PUPPETFILE

  • Ignore the local .fixtures.yml and use the modules listed in the specified Puppetfile
  • Downloaded items that are not Puppet modules will be removed from the downloaded fixtures prior to testing
  • Set this to a valid URL to download a remote Puppetfile for use

• SIMP_RSPEC_MODULEPATH

  • Will ignore the local .fixtures.yml file and create one entirely of symlinks that point to the modules present at the specified path.
  • If specified with SIMP_RSPEC_PUPPETFILE then will use the matching modules from the target directory instead of downloading them. Modules not present in the target directory will still be downloaded.

• SIMP_RSPEC_FIXTURES_OVERRIDE

  • Set to yes to ignore the local .fixtures.yml file
  • This will cause the generated file to include all modules from the Puppetfile or Module Path

In a Ruby Gem

Within the project's Rakefile:

require 'simp/rake/rubygem'

# e.g., "simp-rake-helpers"
package = 'name-of-rubygem'
Simp::Rake::Rubygem.new(package, File.dirname(__FILE__)

To see the extra rake tasks:

bunde exec rake -T

Generating RPMs

The task rake pkg:rpm) provides the ability to package an RPM from any Puppet module (regardless of whether it is a SIMP module or not). The only requirement is that the Puppet module MUST include a valid metadata.json file with entries for name, version, license, summary, and source.

The RPM package may be configured by other (optional) files under the project directory . The full list of files considered are:

./
├── metadata.json     # REQUIRED keys: name, version, license, summary, source
├── CHANGELOG         # OPTIONAL written in RPM's CHANGELOG format
└── build/            # OPTIONAL
    └── rpm_metadata/ # OPTIONAL
        ├── release   # OPTIONAL defines the RPM's "-<qualifier>" release qualifier
        ├── requires  # OPTIONAL supplementary 'Requires','Provides','Obsoletes'
        └── custom/   # OPTIONAL
          └── *       # OPTIONAL custom snippets in RPM .spec format

NOTE: The dependencies in metadata.json are not used to generate RPM dependencies!

RPM Changelog

The RPM Changelog will be derived from a CHANGELOG file at the top level of the project, if it exists.

• The file is expected to conform to the RPM Changelog format described in the Fedora packaging guidelines

• The file MUST start with a well-formatted RPM changelog string, or it will be ignored.

  Example:

  * Mon Nov 06 2017 Tom Smith <[e-mail]> - 3.8.0
  - Add feature x
  

  Important: Note the leading zero in "Nov 05". It is a convention

  that is required by our CHANGELOG validation tasks.

• The format is not fully checked before attempting to build the RPM―the RPM build will fail if the Changelog entries are not valid.

RPM Dependencies

It is likely that you will want to declare your dependencies in your RPM. To do this, create a build/rpm_metadata directory at the root of the project. A requires file in the build/rpm_metadata directory will be used to declare the dependencies of the RPM. A file named release in the build/rpm_metadata directory will be used to declare the RPM release number.

The following directives may be declared in the requires file:

• Provides:
• Requires:
• Obsoletes:

Reference

simp/rake/rpm

rake pkg:rpm

Packages the current SIMP project as an RPM

rake pkg:tar

Build the tar package for the current SIMP project

Limitations

Development

Please see the SIMP Contribution Guidelines.

License

See LICENSE

History

See CHANGELOG.md