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
- simp/rake/rpm
- 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
- Ignore the local
-
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.
- Will ignore the local
-
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
- Set to
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 <tom.smith@simp.com> - 3.8.0 - Add feature x
Important: Note the leading zero in "
Nov 05
". It is a conventionthat 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