Overview
Gemsmith allows you to easily craft new gems via the command line with custom settings (if desired). If you are a fan of Bundler, then you'll appreciate the additional capabilities of this gem. Gemsmith is essentially an enhanced version of Bundler's gem building capabilities.
Features
- Builds a gem skeleton with Bundler functionality in mind.
- Supports common settings that can be applied to new gem creations.
- Supports Thor command line functionality.
- Supports Ruby on Rails.
- Supports RSpec.
- Supports Pry.
- Supports Guard.
- Supports Code Climate.
- Supports Gemnasium.
- Supports Travis CI.
- Supports Coveralls.
- Provides the ability to open the source code of any gem within your favorite editor.
- Provides the ability to read the documentation of any gem within your default browser.
- Adds commonly needed README, CHANGELOG, CONTRIBUTING, LICENSE, etc. template files.
Requirements
Setup
For a secure install, type the following from the command line (recommended):
gem cert --add <(curl -Ls http://www.redalchemist.com/gem-public.pem)
gem install gemsmith --trust-policy MediumSecurity
NOTE: A HighSecurity trust policy would be best but MediumSecurity enables signed gem verification while allowing the installation of unsigned dependencies since they are beyond the scope of this gem.
For an insecure install, type the following (not recommended):
gem install gemsmith
You can configure common settings for future gem builds by creating the following file:
~/.gemsmith/settings.yml
...using the following settings (for example):
---
:author_name: Brooke Kuhlmann
:author_email: [email protected]
:author_url: http://www.redalchemist.com
:company_name: Red Alchemist
If no options are configured, then the defaults are as follows:
gem_platform: Gem::Platform::RUBY
gem_private_key: ~/.ssh/gem-private.pem
gem_public_key: ~/.ssh/gem-public.pem
author_name: <git name>
author_email: <git email>
author_url: https://www.unknown.com
gem_url: <author URL>
company_name: <author name>
company_url: <author URL>
github_user: <github user>
year: <current year>
ruby_version: 2.0.0
ruby_patch: p0
rails_version: 4.0
Usage
From the command line, type: gemsmith help
gemsmith -c, [create=CREATE] # Create new gem.
gemsmith -e, [edit] # Edit gem in default editor (assumes $EDITOR environment variable).
gemsmith -h, [--help=HELP] # Show this message or get help for a command.
gemsmith -o, [open=OPEN] # Open gem in default editor (assumes $EDITOR environment variable).
gemsmith -r, [read=READ] # Open gem in default browser.
gemsmith -v, [--version] # Show version.
For more gem creation options, type: gemsmith help create
-b, [--bin], [--no-bin] # Add binary support.
-r, [--rails], [--no-rails] # Add Rails support.
-p, [--pry], [--no-pry] # Add Pry support.
# Default: true
-g, [--guard], [--no-guard] # Add Guard support.
# Default: true
-s, [--rspec], [--no-rspec] # Add RSpec support.
# Default: true
-c, [--code-climate], [--no-code-climate] # Add Code Climate support.
# Default: true
-G, [--gemnasium], [--no-gemnasium] # Add Gemnasium support.
# Default: true
-t, [--travis], [--no-travis] # Add Travis CI support.
# Default: true
-C, [--coveralls], [--no-coveralls] # Add Coveralls support.
# Default: true
Once a gem skeleton has been created, the following tasks are available within the project via Bundler (i.e. rake -T):
rake build # Build example-0.1.0.gem into the pkg directory
rake install # Build and install example-0.1.0.gem into system gems
rake release # Create tag v2.3.0 and build and push example-0.1.0.gem to Rubygems
Tests
To test, do the following:
- cd to the gem root.
- bundle install
- bundle exec rspec spec
Security
To create a certificate for your gems, run the following:
cd ~/.ssh
gem cert --build [email protected]
chmod 600 gem-*.pem
The resulting .pem keys can be referenced via the *gem_private_key and gem_public_key settings mentioned in the Setup documentation.
To learn more about gem certificates, read the following:
- Ruby Gems
- A Practical Guide to Using Signed Ruby Gems - Part 1: Bundler
- A Practical Guide to Using Signed Ruby Gems - Part 2: Heroku
Best Practices
- Semantic Versioning
- Best Practices While Cutting Gems.
- Ruby on Rails Gem Packaging.
- Gem Activation and You: Part I
- Gem Activation and You: Part II
- Why You Should Use a BSD Style License.
- Add -w to the RUBYOPT environment variable when testing. Details.
When To Include a Railtie (Crafting Rails Applications - Page 93 by José Valim)
- "Your gem needs to perform a given task while or after the Rails application is initialized."
- "Your gem needs to change a configuration value, such as setting a generator."
- "Your gem must provide Rake tasks and generators in nondefault locations (the default location for the former is lib/tasks and lib/gen- erators or lib/rails/generators for the latter)."
- "You want your gem to provide configuration options to the appli- cation, such as config.my_gem.key # :value."
Documentation
In order to make your gem easier to use and adopt by others, good documentation is always a plus. Consider submitting your gem to RubyDocs[http://rubydoc.info] once your gem is released and available for use. RubyDocs supports both RDoc and YARD formats.
Promotion
Once your gem is released, you might like to let the world know about the new awesomeness. Here are several resources:
Versioning
Read Semantic Versioning for details. Briefly, it means:
- Patch (x.y.Z) - Incremented for small, backwards compatible bug fixes.
- Minor (x.Y.z) - Incremented for new, backwards compatible public API enhancements and/or bug fixes.
- Major (X.y.z) - Incremented for any backwards incompatible public API changes.
Contributions
Read CONTRIBUTING for details.
Credits
Developed by Brooke Kuhlmann at Red Alchemist.
License
Copyright (c) 2011 Red Alchemist. Read the LICENSE for details.
History
Read the CHANGELOG for details.