Skip to content
BranchesTags
 
 

Repository files navigation

Gemsmith

Gemsmith is a command line interface for smithing Ruby gems. Perfect for when you need a professional and robust tool beyond Bundler's basic gem skeletons. While Bundler is great for creating your first gem, you’ll quickly outgrow Bundler when creating and maintaining multiple gems. This is where Gemsmith can increase your productivity by providing much of the tooling you need from the start with the ability to customize as desired.

Table of Contents

Features

  • Supports all features provided by Rubysmith which is used for smithing Ruby projects.

  • Supports basic gem skeletons or more advanced Command Line Interface (CLI) skeletons.

  • Supports gem building, installing for local development, and publishing.

  • Supports the editing and viewing of installed gems.

Requirements

  1. A UNIX-based system.

  2. Ruby.

  3. RubyGems.

Setup

To install, run:

gem install gemsmith

Upgrade

If upgrading from 16.0.0 to 17.0.0, you’ll need to make the following changes:

  • README badges are no longer injected so you can customize as desired.

  • The :rubocop: build configuration has been removed. Use :caliber: instead.

  • The --rubocop build option has been removed. Use --caliber instead.

  • You no longer have to Git ignore RuboCop cached configurations since this is handled by the Caliber gem now.

Usage

Command Line Interface (CLI)

From the command line, type: gemsmith --help

USAGE:
  -b, --build NAME [options]               Build new project.
  -c, --config ACTION                      Manage gem configuration: edit or view.
      --edit GEM                           Edit installed gem in default editor.
  -h, --help                               Show this message.
  -i, --install [NAME]                     Install gem for local development.
  -p, --publish [NAME]                     Publish gem to remote gem server.
  -v, --version                            Show gem version.
      --view GEM                           View installed gem in default browser.

BUILD OPTIONS:
      --[no-]amazing_print                 Add Amazing Print gem. Default: true.
      --[no-]bundler-leak                  Add Bundler Leak gem. Default: true.
      --[no-]caliber                       Add Caliber gem. Default: true.
      --[no-]circle_ci                     Add Circle CI configuration and badge. Default: false.
      --[no-]citation                      Add citation documentation. Default: true.
      --[no-]community                     Add community documentation. Default: false.
      --[no-]conduct                       Add code of conduct documentation. Default: true.
      --[no-]console                       Add console script. Default: true.
      --[no-]contributions                 Add contributions documentation. Default: true.
      --[no-]dead_end                      Add Dead End gem. Default: true.
      --[no-]debug                         Add Debug gem. Default: true.
      --[no-]git                           Add Git. Default: true.
      --[no-]git_hub                       Add GitHub templates. Default: false.
      --[no-]git-lint                      Add Git Lint gem. Default: true.
      --[no-]guard                         Add Guard gem. Default: true.
      --[no-]license                       Add license documentation. Default: true.
      --max                                Use maximum/enabled options. Default: false.
      --min                                Use minimum/disabled options. Default: false.
      --[no-]rake                          Add Rake gem. Default: true.
      --[no-]readme                        Add readme documentation. Default: true.
      --[no-]reek                          Add Reek gem. Default: true.
      --[no-]refinements                   Add Refinements gem. Default: true.
      --[no-]rspec                         Add RSpec gem. Default: true.
      --[no-]security                      Add security. Default: true.
      --[no-]setup                         Add setup script. Default: true.
      --[no-]simple_cov                    Add SimpleCov gem. Default: true.
      --[no-]versions                      Add version history. Default: true.
      --[no-]yard                          Add Yard gem. Default: false.
      --[no-]zeitwerk                      Add Zeitwerk gem. Default: true.
      --[no-]cli                           Add command line interface. Default: false.

Build

The core functionality of this gem centers around the --build command and associated flags. The build options allow you to further customize the kind of gem you want to build. Most build options are enabled by default. For detailed documentation on all supported flags, see the Rubysmith documentation.

The build option, which is unique to Gemsmith, is the --cli option. This allows you to build a gem which has a Command Line Interface (CLI). There are multiple ways a CLI can be built in Ruby but Gemsmith takes an approach which builds upon Ruby’s native OptionParser with help from Dry Container. All of this culminates in a design that is mix of Objected Oriented + Functional Programming design. Building a gem with CLI support is a simple as running:

gemsmith --build demo --cli

The above will give you a new gem with CLI support which includes working specs. It’s the same design used to build this Gemsmith gem. You’ll have both a configuration and CLI namespace for configuring your gem and adding additional CLI support. Out of the box, the CLI gem generated for you supports the following options:

  -c, --config ACTION                      Manage gem configuration: edit or view.
  -h, --help                               Show this message.
  -v, --version                            Show gem version.

From here you can add whatever you wish to make an awesome CLI gem for others to enjoy.

Install

After you’ve designed, implemented, and built your gem, you’ll want to test it out within your local environment by installing it. You can do this by running:

# Implicit
gemsmith --install

# Explicit
gemsmith --install demo

Gemsmith can be used to install any gem, in fact. Doesn’t matter if the gem was built by Gemsmith, Bundler, or some other tool. As long as your gem has a *.gemspec file, Gemsmith will be able to install it.

Publish

Once you’ve built your gem; installed it locally; and thoroughly tested it, you’ll want to publish your gem so anyone in the world can make use of it. You can do this by running the following:

# Implicit
gemsmith --publish

# Explicit
gemsmith --publish demo

Security is important which requires a GPG key for signing your Git tags and RubyGems Multi-Factor Authentication for publishing to RubyGems. Both of which are enabled by default. You’ll want to read through the linked article which delves into how Gemsmith automatically makes use of your YubiKey to authenticate with RubyGems. Spending the time to set this up will allow Gemsmith to use of your YubiKey for effortless and secure publishing of new versions of your gems so I highly recommend doing this.

As with installing a gem, Gemsmith can be used to publish existing gems which were not built by Gemsmith too. As long as your gem has a *.gemspec file with a valid version, Gemsmith will be able to publish it.

Edit

Gemsmith can be used to edit existing gems on your local system. You can do this by running:

gemsmith --edit <name of gem>

If multiple versions of the same gem are detected, you’ll be prompted to pick which gem you want to edit. Otherwise, the gem will immediately be opened within your default editor (or whatever you have set in your EDITOR environment variable).

Editing a local gem is a great way to learn from others or quickly debug issues.

View

Gemsmith can be used to view existing gem documentation. You can do this by running:

gemsmith --view <name of gem>

If multiple versions of the same gem are detected, you’ll be prompted to pick which gem you want to view. Otherwise, the gem will immediately be opened within your default browser.

Viewing a gem is a great way to learn more about the gem and documentation in general.

Configuration

This gem can be configured via a global configuration:

$HOME/.config/gemsmith/configuration.yml

It can also be configured via XDG environment variables.

The default configuration is everything provided in the Rubysmith with the addition of the following:

:build:
  :cli: false

Feel free to take the combined Rubysmith + Gemsmith configuration, modify, and save as your own custom configuration.yml.

Workflows

When building/testing your gem locally, a typical workflow is:

# Build
gemsmith --build demo

# Design, Implement and Test.
cd demo
bundle exec rake

# Install
gemsmith --install

# Publish
gemsmith --publish

Security

Git Signing Key

To securely sign your Git tags, install and configure GPG:

brew install gpg
gpg --gen-key

When creating your GPG key, choose these settings:

  • Key kind: RSA and RSA (default)

  • Key size: 4096

  • Key validity: 0

  • Real Name: <your name>

  • Email: <your email>

  • Passphrase: <your passphrase>

To obtain your key, run the following and take the part after the forward slash:

gpg --list-keys | grep pub

Add your key to your global Git configuration in the [user] section. Example:

[user]
  signingkey = <your GPG key>

Now, when publishing your gems with Gemsmith (i.e. bundle exec rake publish), signing of your Git tag will happen automatically.

Gem Certificates

To create a certificate for your gems, run the following:

cd ~/.ssh
gem cert --build you@example.com
chmod 600 gem-*.pem

The resulting .pem key files can be referenced via the :private_key: and :public_key: keys within the $HOME/.gemsmithrc file.

To learn more about gem certificates, read about RubyGems Security.

Private Gem Servers

By default, the following Rake task will publish your gem to RubyGems:

gemsmith --publish

You can change this behavior by adding metadata to your gemspec that will allow Gemsmith to publish your gem to an alternate/private gem server instead. This can be done by updating your gem specification and RubyGems credentials.

Gem Specification Metadata

Add the following metadata to your gemspec:

Gem::Specification.new do |spec|
  spec.metadata = {
    "allowed_push_key" => "example_key",
    "allowed_push_host" => "https://gems.example.com"
  }
end

The gemspec metadata keys and values must be strings per the RubyGems Specification. Each key represents the following:

  • allowed_push_key: Provides a reference (look up) to the key defined the RubyGems credentials file so that sensitive credentials are not used within your gemspec.

  • allowed_push_host: Provides the URL of the private gem server to push your gem to.

Gem Credentials

With your gem specification metadata established, you are ready to publish your gem to a public or private server. If this is your first time publishing a gem and no gem credentials have been configured, you’ll be prompted for them. Gem credentials are stored in the RubyGems $HOME/.gem/credentials file. From this point forward, future gem publishing will use your stored credentials instead. Multiple credentials can be stored in the $HOME/.gem/credentials file. Example:

:rubygems_api_key: 2a0b460650e67d9b85a60e183defa376
:some_custom_key: "Basic dXNlcjpwYXNzd29yZA=="

Should you need to delete a credential (due to a bad login/password for example), you can open the $HOME/.gem/credentials in your default editor and remove the line(s) you don’t need. Upon next publish of your gem, you’ll be prompted for the missing credentials.

Promotion

Once your gem is released, let the world know about your accomplishment by posting an update to these sites:

Development

To contribute, run:

git clone https://github.com/bkuhlmann/gemsmith.git
cd gemsmith
bin/setup

You can also use the IRB console for direct access to all objects:

bin/console

Tests

To test, run:

bundle exec rake

Credits

Engineered by Brooke Kuhlmann.

About

A command line interface for smithing Ruby gems.

www.alchemists.io/projects/gemsmith

Resources

Readme
License

Code of conduct

Code of conduct
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages