https://github.com/simp/rubygem-simp-rake-helpers
Rake Helpers for the SIMP Rake tasks
https://github.com/simp/rubygem-simp-rake-helpers
gem helpers puppet rake ruby simp
Last synced: about 1 month ago
JSON representation
Rake Helpers for the SIMP Rake tasks
- Host: GitHub
- URL: https://github.com/simp/rubygem-simp-rake-helpers
- Owner: simp
- License: other
- Created: 2015-05-19T09:49:45.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2023-08-24T17:09:09.000Z (over 1 year ago)
- Last Synced: 2024-05-06T11:21:47.462Z (about 1 year ago)
- Topics: gem, helpers, puppet, rake, ruby, simp
- Language: Ruby
- Size: 958 KB
- Stars: 3
- Watchers: 16
- Forks: 10
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# simp-rake-helpers
[](http://www.apache.org/licenses/LICENSE-2.0.html)
[](https://travis-ci.org/simp/rubygem-simp-rake-helpers)
[](https://rubygems.org/gems/simp-rake-helpers)
[](https://rubygems.org/gems/simp-rake-helpers)
#### Table of Contents
* [Overview](#overview)
* [This gem is part of SIMP](#this-gem-is-part-of-simp)
* [Features](#features)
* [Setup](#setup)
* [Gemfile](#gemfile)
* [Usage](#usage)
* [In a Puppet module](#in-a-puppet-module)
* [Environment Variables](#environment-variables)
* [In a Ruby Gem](#in-a-ruby-gem)
* [Generating RPMs](#generating-rpms)
* [RPM Changelog](#rpm-changelog)
* [RPM Dependencies](#rpm-dependencies)
* [Reference](#reference)
* [simp/rake/rpm](#simprakerpm)
* [`rake pkg:rpm`](#rake-pkgrpm)
* [`rake pkg:tar`](#rake-pkgtar)
* [Limitations](#limitations)
* [Development](#development)
* [License](#license)
* [History](#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](https://simp-project.com), a compliance-management framework built on [Puppet](https://puppetlabs.com/).
### Features
* Customizable RPM packaging based on a Puppet module's [`metadata.json`][metadata.json]
* RPM signing
* Rubygem packaging
## Setup
### Gemfile
```ruby
# 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:
```ruby
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:
```ruby
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:
```sh
bunde exec rake -T
```
### Generating RPMs
The task [`rake pkg:rpm`](#simprakerpm)) 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`][metadata.json] file with entries for `name`,
`version`, `license`, `summary`, and `source`.
[metadata.json]: https://docs.puppet.com/puppet/latest/reference/modules_metadata.html
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 "-" 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][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 - 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 CHANGELOG]: https://fedoraproject.org/wiki/Packaging:Guidelines#Changelogs
#### 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](https://simp-project.atlassian.net/wiki/display/SD/Contributing+to+SIMP).
### License
See [LICENSE](LICENSE)
### History
See [CHANGELOG.md](CHANGELOG.md)