StoneChecksums née GemChecksums

---

A ruby shell script, and rake task, to generate SHA-256 and SHA-512 checksums of RubyGem libraries, shipped as a RubyGem.

You may be familiar with the standard rake task build:checksum from RubyGems. This gem ships an improved version as build:generate_checksums, based on the RubyGems pull request I started in October 2022.

rake build:generate_checksums

Or giving the same result...

The script accomplishes the same thing if you prefer that:

gem_checksums

Info you can shake a stick at

Tokens to Remember
Works with JRuby
Works with Truffle Ruby
Works with MRI Ruby 3
Works with MRI Ruby 2
Source
Documentation
Compliance
Expert 1:1 Support	or
Enterprise Support	💡Subscribe for support guarantees covering all FLOSS dependencies! 💡Tidelift is part of Sonar! 💡Tidelift pays maintainers to maintain the software you depend on! 📊@Pointy Haired Boss: An enterprise support subscription is "never gonna let you down", and supports open source maintainers!
Comrade BDFL 🎖️
... 💖

Installation

Install the gem and add to your library's Gemfile by executing:

bundle add stone_checksums

Or add it as a development dependency to the gemspec:

Gem::Specification.new do |spec|
  # ...
  spec.add_development_dependency("stone_checksums", "~> 1.0")
end

If bundler is not being used to manage dependencies, install the gem by executing:

gem install stone_checksums

Usage

Once installed you can use the shell script without any changes to your code.

# prepend with `bundle exec` if gem was added to Gemfile instead of installed globally
gem_checksums

However, if you want to use the bundled rake task you'll need to add it to your Rakefile first.

begin
  require "stone_checksums"
  GemChecksums.install_tasks
rescue LoadError
  task("build:generate_checksums") do
    warn("stone_checksums gem is not available")
  end
end

Then you can do:

# prepend with `bundle exec` if gem was added to Gemfile instead of installed globally
rake build:generate_checksums

It is different from, and improves on, the standard rake task in that it:

• does various checks to ensure the generated checksums will be valid
• does git commit the generated checksums

ENV variables

Behavior can be controlled by ENV variables!

• GEM_CHECKSUMS_GIT_DRY_RUN default value is false
  • when true the git commit command will run with --dry-run flag
  • when true the checksum files will be unstaged and deleted
• GEM_CHECKSUMS_CHECKSUMS_DIR default value is checksums (relative path)
  • this directory will be created, relative to current working directory, if not present
• GEM_CHECKSUMS_PACKAGE_DIR default value is pkg (relative path)
  • this directory will be searched for the latest gem package to generate checksums for

ARGV

If an argument is provided to the rake task it should be the path to a specific .gem package you want to generate checksums for.

The script version does not accept arguments, and should be controlled by the ENV variables if needed.

How To: Release gem with checksums generated by stone_checksums

Generating checksums makes sense when you are building and releasing a gem, so how does it fit into that process?

NOTE: This is an example process which assumes your project has bundler binstubs, and a version.rb file, with notes for zsh and bash shells.

1. Run bin/setup && bin/rake as a tests, coverage, & linting sanity check
2. Update the version number in version.rb
3. Run bin/setup && bin/rake again as a secondary check, and to update Gemfile.lock
4. Run git commit -am "🔖 Prepare release v<VERSION>" to commit the changes
5. Run git push to trigger the final CI pipeline before release, & merge PRs
   • NOTE: Remember to check your project's CI!
6. Run export GIT_TRUNK_BRANCH_NAME="$(git remote show origin | grep 'HEAD branch' | cut -d ' ' -f5)" && echo $GIT_TRUNK_BRANCH_NAME
7. Run git checkout $GIT_TRUNK_BRANCH_NAME
8. Run git pull origin $GIT_TRUNK_BRANCH_NAME to ensure you will release the latest trunk code
9. Set SOURCE_DATE_EPOCH so rake build and rake release use same timestamp, and generate same checksums
   • Run export SOURCE_DATE_EPOCH=$EPOCHSECONDS && echo $SOURCE_DATE_EPOCH
   • If the echo above has no output, then it didn't work.
   • Note that you'll need the zsh/datetime module, if running zsh.
   • In bash you can use date +%s instead, i.e. export SOURCE_DATE_EPOCH=$(date +%s) && echo $SOURCE_DATE_EPOCH
10. Run bundle exec rake build
11. Run gem_checksums (from this gem, and added to path in .envrc, more context 1 and 2) to create SHA-256 and SHA-512 checksums
    • Checksums will be committed automatically by the script, but not pushed
12. Run bundle exec rake release which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org

Too many steps?

If you don't follow the steps above you'll end up seeing this error:

WARNING: Build time not provided via environment variable SOURCE_DATE_EPOCH.
         To ensure consistent SHA-256 & SHA-512 checksums,
         you must set this environment variable *before* building the gem.

IMPORTANT: After setting the build time, you *must re-build the gem*, i.e. bundle exec rake build, or gem build.

How to set the build time:

In zsh shell:
  - export SOURCE_DATE_EPOCH=$EPOCHSECONDS && echo $SOURCE_DATE_EPOCH
  - If the echo above has no output, then it didn't work.
  - Note that you'll need the `zsh/datetime` module enabled.

In fish shell:
  - set -x SOURCE_DATE_EPOCH (date +%s)
  - echo $SOURCE_DATE_EPOCH

In bash shell:
  - export SOURCE_DATE_EPOCH=$(date +%s) && echo $SOURCE_DATE_EPOCH`

Just do what it says!

🔐 Security

See SECURITY.md.

🤝 Contributing

If you need some ideas of where to help, you could work on adding more code coverage, or if it is already 💯 (see below) check TODOs (see below), or check issues, or PRs, or use the gem and think about how it could be better.

We so if you make changes, remember to update it.

See CONTRIBUTING.md for more detailed instructions.

TODOs

• Prepend rake build task with check for SOURCE_DATE_EPOCH environment variable, and raise error if not set.

Code Coverage

🪇 Code of Conduct

Everyone interacting in this project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the .

🌈 Contributors

Made with contributors-img.

Also see GitLab Contributors: https://gitlab.com/pboling/gem_checksums/-/graphs/main

⭐️ Star History

📌 Versioning

This Library adheres to . Violations of this scheme should be reported as bugs. Specifically, if a minor or patch version is released that breaks backward compatibility, a new version should be immediately released that restores compatibility. Breaking changes to the public API will only be introduced with new major versions.

📌 Is "Platform Support" part of the public API?

Yes. But I'm obligated to include notes...

SemVer should, but doesn't explicitly, say that dropping support for specific Platforms is a breaking change to an API. It is obvious to many, but not all, and since the spec is silent, the bike shedding is endless.

dropping support for a platform is both obviously and objectively a breaking change

• Jordan Harband (@ljharb) in SemVer issue 716

To get a better understanding of how SemVer is intended to work over a project's lifetime, read this article from the creator of SemVer:

• "Major Version Numbers are Not Sacred"

As a result of this policy, and the interpretive lens used by the maintainer, you can (and should) specify a dependency on these libraries using the Pessimistic Version Constraint with two digits of precision.

For example:

spec.add_dependency("gem_checksums", "~> 1.1")

See CHANGELOG.md for list of releases.

📄 License

The gem is available as open source under the terms of the MIT License . See LICENSE.txt for the official Copyright Notice.

© Copyright

Copyright (c) 2022 - 2025 Peter H. Boling, RailsBling.com

🤑 One more thing

You made it to the bottom of the page, so perhaps you'll indulge me for another 20 seconds. I maintain many dozens of gems, including this one, because I want Ruby to be a great place for people to solve problems, big and small. Please consider supporting my efforts via the giant yellow link below, or one of the others at the head of this README.