Adoptable Cookbooks List

Supermarket Belongs to the Community

Supermarket belongs to the community. While Chef has the responsibility to keep it running and be stewards of its functionality, what it does and how it works is driven by the community. The chef/supermarket repository will continue to be where development of the Supermarket application takes place. Come be part of shaping the direction of Supermarket by opening issues and pull requests or by joining us on the Chef Mailing List.

<a name="title"></a> ruby_rbenv Chef Cookbook

<a name="description"></a> Description

Manages rbenv and its installed Rubies.
Several lightweight resources and providers (LWRPs) are also defined.

WARNING: As of version 1.0 this cookbook was renamed from rbenv to ruby_rbenv so it could be uploaded to the Supermarket. Attributes and resources (LWRPs) retain the rbenv namespace for compatibility, but if you wrap this cookbook you'll need to update the recipes you include. Use 0.9.0 if you need the existing name.

<a name="requirements"></a> Requirements

<a name="requirements-chef"></a> Chef

This cookbook requires Chef 12.1+.

<a name="requirements-platform"></a> Platform

The following platforms have been tested with this cookbook, meaning that
the recipes and LWRPs run on these platforms without error:

<a name="usage-user-rubies"></a> rbenv Installed For A Specific User with Rubies

If you want a per-user install (like on a Mac/Linux workstation for
development, CI, etc.), include recipe[ruby_rbenv::user] in your run_list and
add a user hash to the user_installs attribute list. For example:

If you want to manage your own rbenv environment with the provided
LWRPs, then include recipe[ruby_rbenv::system_install] in your run_list
to prevent a default rbenv Ruby being installed. See the
Resources and Providers section for more details.

If you want to manage your own rbenv environment for users with the provided
LWRPs, then include recipe[ruby_rbenv::user_install] in your run_list and add a
user hash to the user_installs attribute list. For example:

<a name="usage-minimal"></a> Ultra-Minimal Access To LWRPs

Simply include recipe[ruby_rbenv] in your run_list and the LWRPs will be
available to use in other cookbooks. See the Resources and Providers
section for more details.

<a name="recipes"></a> Recipes

<a name="recipes-default"></a> default

Installs the rbenv gem and initializes Chef to use the Lightweight Resources
and Providers (LWRPs).

Use this recipe explicitly if you only want access to the LWRPs provided.

<a name="recipes-system-install"></a> system_install

Installs the rbenv codebase system-wide (that is, into /usr/local/rbenv). This
recipe includes default.

Use this recipe by itself if you want rbenv installed system-wide but want
to handle installing Rubies, invoking LWRPs, etc..

<a name="recipes-system"></a> system

Installs the rbenv codebase system-wide (that is, into /usr/local/rbenv) and
installs rubies driven off attribute metadata. This recipe includes default
and system_install.

Use this recipe by itself if you want rbenv installed system-wide with rubies
installed.

<a name="recipes-user-install"></a> user_install

Installs the rbenv codebase for a list of users (selected from the
node['rbenv']['user_installs'] hash). This recipe includes default.

Use this recipe by itself if you want rbenv installed for specific users in
isolation but want each user to handle installing Rubies, invoking LWRPs, etc.

<a name="recipes-user"></a> user

Installs the rbenv codebase for a list of users (selected from the
node['rbenv']['user_installs'] hash) and installs rubies driven off attribte
metadata. This recipe includes default and user_install.

Use this recipe by itself if you want rbenv installed for specific users in
isolation with rubies installed.

<a name="attributes"></a> Attributes

<a name="attributes-git-url"></a> git_url

The Git URL which is used to install rbenv.

The default is "git://github.com/sstephenson/rbenv.git".

<a name="attributes-git-ref"></a> git_ref

A specific Git branch/tag/reference to use when installing rbenv. For
example, to pin rbenv to a specific release:

node.default['ruby_build']['git_ref'] = "v0.2.1"

The default is "v0.4.0".

<a name="attributes-upgrade"></a> upgrade

Determines how to handle installing updates to the rbenv. There are currently
2 valid values:

"none", false, or nil: will not update rbenv and leave it in its
current state.

"sync" or true: updates rbenv to the version specified by the
git_ref attribute or the head of the master branch by default.

The default is "none".

<a name="attributes-root-path"></a> root_path

The path prefix to rbenv in a system-wide installation.

The default is "/usr/local/rbenv".

<a name="attributes-patch_url"></a> patch_url

A url to a patch file for your ruby install.

The default is nil.

<a name="attributes-patch_file"></a> patch_file

A path to a patch file for your ruby install.

The default is nil.

<a name="attributes-rubies"></a> rubies

A list of additional system-wide rubies to be built and installed using the
ruby_build cookbook. You must include recipe[ruby_build]
in your run_list for the rbenv_ruby LWRP to work properly. For example:

node.default['rbenv']['rubies'] = [ "1.9.3-p0", "jruby-1.6.5" ]

The default is an empty array: [].

Additional environment variables can be passed to ruby_build via the environment variable.
For example:

<a name="attributes-gems"></a> gems

A hash of gems to be installed into arbitrary rbenv-managed rubies system wide.
See the rbenv_gem resource for more details about the options
for each gem hash and target Ruby environment. For example:

<a name="attributes-user-gems"></a> user_gems

A hash of gems to be installed into arbitrary rbenv-managed rubies for each user
when not explicitly set. See the rbenv_gem resource for more
details about the options for each gem hash and target Ruby environment. See
the gems attribute for an example.

The default is an empty hash: {}.

<a name="attributes-plugins"></a> plugins

A list of plugins to be installed system-wide. See the rbenv_plugin
resource for details about the options.

<a name="attributes-user-gems"></a> user_plugins

If using the vagrant recipe, this sets the path to the package-installed
chef-solo binary.

The default is "/opt/ruby/bin/chef-solo".

<a name="attributes-create-profiled"></a> create_profiled

The user's shell needs to know about rbenv's location and set up the
PATH environment variable. This is handled in the
system_install and
user_install recipes by dropping off
/etc/profile.d/rbenv.sh. However, this requires root privilege,
which means that a user cannot use a "user install" for only their
user.

Set this attribute to false to skip creation of the
/etc/profile.d/rbenv.sh template. For example:

node.default['rbenv']['create_profiled'] = false

The default is true.

<a name="lwrps"></a> Resources and Providers

<a name="lwrps-rg"></a> rbenv_global

This resource sets the global version of Ruby to be used in all shells, as per
the rbenv global docs.

<a name="lwrps-rg-actions"></a> Actions

<table>
<thead>
<tr>
<th>Action</th>
<th>Description</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td>create</td>
<td>
Sets the global version of Ruby to be used in all shells. See 3.1
rbenv global<sup>(1)</sup> for more details.
</td>
<td>Yes</td>
</tr>
</tbody>
</table>

Use action :nothing to set a command to only run if another resource
notifies it.

<a name="lwrps-rsc-attributes"></a> Attributes

<table>
<thead>
<tr>
<th>Attribute</th>
<th>Description</th>
<th>Default Value</th>
</tr>
</thead>
<tbody>
<tr>
<td>name</td>
<td>
<b>Name attribute:</b> Name of the command to execute.
</td>
<td>name</td>
</tr>
<tr>
<td>rbenv_version</td>
<td>
A version of Ruby being managed by rbenv.
</td>
<td><code>nil</code></td>
</tr>
<tr>
<td>root_path</td>
<td>
The path prefix to rbenv installation, for example:
<code>/opt/rbenv</code>.
</td>
<td><code>nil</code></td>
</tr>
<tr>
<td>code</td>
<td>
Quoted script of code to execute.
</td>
<td><code>nil</code></td>
</tr>
<tr>
<td>creates</td>
<td>
A file this command creates - if the file exists, the command will not
be run.
</td>
<td><code>nil</code></td>
</tr>
<tr>
<td>cwd</td>
<td>
Current working director to run the command from.
</td>
<td><code>nil</code></td>
</tr>
<tr>
<td>environment</td>
<td>
A has of environment variables to set before running this command.
</td>
<td><code>nil</code></td>
</tr>
<tr>
<td>group</td>
<td>
A group or group ID that we should change to before running this
command.
</td>
<td><code>nil</code></td>
</tr>
<tr>
<td>path</td>
<td>
An array of paths to use when searching for the command.
</td>
<td><code>nil</code>, uses system path</td>
</tr>
<tr>
<td>returns</td>
<td>
The return value of the command (may be an array of accepted values) -
this resource raises an exception if the return value(s) do not match.
</td>
<td><code>0</code></td>
</tr>
<tr>
<td>timeout</td>
<td>
How many seconds to let the command run before timing out.
</td>
<td><code>nil</code></td>
</tr>
<tr>
<td>user</td>
<td>
A users's isolated rbenv installation on which to apply an action. The
default value of <code>nil</code> denotes a system-wide rbenv
installation is being targeted. <b>Note:</b> if specified, the user
must already exist.
</td>
<td><code>nil</code></td>
</tr>
<tr>
<td>umask</td>
<td>
Umask for files created by the command.
</td>
<td><code>nil</code></td>
</tr>
</tbody>
</table>

<a name="lwrps-rbr-attributes"></a> Attributes

<table>
<thead>
<tr>
<th>Attribute</th>
<th>Description</th>
<th>Default Value</th>
</tr>
</thead>
<tbody>
<tr>
<td>definition</td>
<td>
<b>Name attribute:</b> the name of a built-in definition<sup>(1)</sup>
or the name of the ruby installed by a ruby-build defintion file<sup>(2)</sup>
</td>
<td><code>nil</code></td>
</tr>
<tr>
<td>definition_file</td>
<td>
The path to a ruby-build definition file.
</td>
<td><code>nil</code></td>
</tr>
<tr>
<td>user</td>
<td>
A users's isolated rbenv installation on which to apply an action. The
default value of <code>nil</code> denotes a system-wide rbenv
installation is being targeted. <b>Note:</b> if specified, the user
must already exist.
</td>
<td><code>nil</code></td>
</tr>
<tr>
<td>root_path</td>
<td>
The path prefix to rbenv installation, for example:
<code>/opt/rbenv</code>.
</td>
<td><code>nil</code></td>
</tr>
<tr>
<td>rbenv_action</td>
<td>
The action that rbenv takes to install ruby via the command line. By default this is 'install' which results in a command such as <code>rbenv install ruby 2.2.0</code>. When using the rvm-download rbenv plugin use 'download' to have the provider execute a command such as <code>rbenv download 2.2.0</code>.
</td>
<td><code>install</code></td>
</tr>
</tbody>
</table>

<a name="lwrps-rbr-examples"></a> Examples

Install Ruby From ruby-build

Note: the install action is default, so the second example is a more common
usage.

Reinstall Ruby

rbenv_ruby "ree-1.8.7-2011.03" do
action :reinstall
end

Install a custom ruby

rbenv_ruby "2.0.0p116" do
definition_file "/usr/local/rbenv/custom/2.0.0p116"
end

<a name="mac-system-note"></a> System-Wide Mac Installation Note

This cookbook takes advantage of managing profile fragments in an
/etc/profile.d directory, common on most Unix-flavored platforms.
Unfortunately, Mac OS X does not support this idiom out of the box,
so you may need to modify your user profile.

<a name="license"></a> License and Author

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

1.0.1 (October 24, 2015)

Fixed failure with rehashing after the cookbook was renamed

1.0.0 (October 12, 2015)

WARNING: Cookbook has been renamed

Renamed to ruby_rbenv and uploaded to Supermarket (all attributes rename in the rbenv cookbook). If you wrap this cookbook you're going to need to update the recipes you include. All providers have been updated to keep their existing rbenv_xyz names for backwards compatibility and attributes still maintain the rbenv namespace.

Updated Travis config to run integration tests in Travis using kitchen-docker

0.9.0 (October 12, 2015)

Fixed base platform case statement in the cookbook that set install_pkgs and user_home_root attributes. This has been converted to a platform_family statement to better support derivitive operating systems and the attributes are set at default levels so they can be overwritten in wrapper cookbooks

Updated Travis to test using Chef DK vs. Gem installs

Fixed Chefspecs and Test Kitchen bats tests to all pass

Added the Apache 2.0 license file

Updated and added new development dependencies to the Gemfile

Use Chef 12.1+ multi-package installs for the dependency packages to speed up installs

Improvements

Pull request #46:
Add a definition_file attribute to the rbenv_ruby resource to prevent
continually trying to build a custom ruby when passed a build file name instead of a built-in definition
(@jf647)