Quick Start to Developing on Puppet
Before diving into the code, you should first take the time to make sure you have an environment where you can run puppet as a developer. In a nutshell you need: the puppet codebase, ruby versions, and dependencies. Once you've got all of that in place you can make sure that you have a working development system by running the puppet spec tests.
The Puppet Codebase
In order to contribute to puppet you'll need to have a github account. Once you have your account, fork the puppetlabs/puppet repo, and clone it onto your local machine. The github docs have a good explanation of how to do all of this.
Puppet needs to work across a variety of ruby versions, including ruby 1.9.3, 2.0.0 and 2.1.0.
Make sure you have bundler installed. This should be as simple as:
$ gem install bundler
Now you can get all of the dependencies using:
$ bundle install --path .bundle/gems/
Once this is done, you can interact with puppet through bundler using
exec <command> which will ensure that
<command> is executed in the context
of puppet's dependencies.
For example to run the specs:
$ bundle exec rake spec
To run puppet itself (for a resource lookup say):
$ bundle exec puppet resource host localhost
Running Spec Tests
Puppet Labs projects use a common convention of using Rake to run unit tests. The tests can be run with the following rake task:
bundle exec rake spec
To run a single file's worth of tests (much faster!), give the filename:
bundle exec rake spec TEST=spec/unit/ssl/host_spec.rb
When tests fail, it is often useful to capture Puppet's log of a test run. The test harness pays attention to two environment variables that can be used to send logs to a file, and to adjust the log level:
PUPPET_TEST_LOG: when set, must be an absolute path to a file. Puppet's log messages will be sent to that file. Note that the log file will contain lots of spurious warnings
Unable to set ownership of log file
- you can safely ignore them.
PUPPET_TEST_LOG_LEVEL: change the log level to adjust how much detail is captured. It defaults to
notice; useful values include