Add precompiled binary gem support and modernize build system by wesleyjellis · Pull Request #2 · OpsLevel/ruby-jq

wesleyjellis · 2026-07-07T14:10:24Z

Summary

This PR modernizes the ruby-jq gem's build and release infrastructure by adding support for precompiled platform-specific binaries, updating to use OpsLevel's jq fork, and migrating from Travis CI to GitHub Actions with cibuildgem.

Key Changes

Precompiled binaries: Added GitHub Actions workflow (.github/workflows/cibuildgem.yaml) to build and release platform-specific gems for x86_64-linux and arm64-darwin across multiple Ruby versions (3.3, 3.4, 4.0)
Updated jq source: Switched from upstream jq 1.6 to OpsLevel's fork where env/$ENV always return an empty object
Onigmo integration: Added static compilation of Onigmo 6.2.0 for regex support instead of relying on system libraries
Build system updates:
- Updated Rakefile to output compiled extensions to lib/jq/ and exclude mini_portile2 from platform gem dependencies
- Modified lib/jq.rb to load precompiled binaries matching the Ruby version, with fallback to source-compiled extension
- Updated extconf.rb to compile both Onigmo and jq statically with proper configuration options
CI/CD migration: Removed .travis.yml in favor of GitHub Actions workflow
Documentation: Updated README.md to document precompiled binary availability and build requirements
Modernization:
- Bumped minimum Ruby version to 3.3 in gemspec
- Updated RuboCop configuration (target Ruby 3.3, renamed Metrics/LineLength to Layout/LineLength)
- Version bump to 0.3.0
- Minor code style improvements (string interpolation, typo fixes)

Notable Implementation Details

The gem now supports two installation modes: precompiled binaries on supported platforms (no build tools needed) and source compilation on others (requires autoconf, automake, libtool)
Precompiled binaries are loaded via version-specific require paths (e.g., jq/3.3/jq_core) with graceful fallback
The build process uses cibuildgem for cross-platform compilation and automated RubyGems release
Added test coverage for regex support and the OpsLevel jq fork's env behavior

https://claude.ai/code/session_01PpxfE1fTm5fFQYBqWTzg4y

- Build a static, self-contained extension: vendor OpsLevel's jq fork (env/$ENV always return {}) plus Onigmo 6.2.0 for regex support, compiled with --disable-shared --enable-static --with-pic - Move the binary to lib/jq/jq_core.so and load a per-Ruby-minor precompiled binary when present, falling back to the source build - Add .github/workflows/cibuildgem.yaml to compile, test, verify, and release fat platform gems (x86_64-linux, arm64-darwin) for Ruby 3.3/3.4/4.0 via Shopify's cibuildgem - Declare required_ruby_version >= 3.3; drop mini_portile2 from platform gems - Add specs guarding regex support and the fork's empty env behavior - Bump version to 0.3.0; update README; remove stale .travis.yml Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PpxfE1fTm5fFQYBqWTzg4y

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

libruby exports its own onig_* functions and ELF's flat namespace lets calls bind across copies of Onigmo; today both are 6.2.0 so it works by coincidence, but a version skew would cause crashes. Keep the vendored jq/Onigmo symbols local to the extension. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

wesleyjellis

https://github.com/flavorjones/mini_portile mentions that "gem "mini_portile2", "~> 2.0.0" # NECESSARY if used in extconf.rb. see below." which seems missing

wesleyjellis · 2026-07-17T19:27:38Z

-  recipe = MiniPortile.new('jq', '1.6')
-  recipe.files = ['https://github.com/stedolan/jq/archive/jq-1.6.tar.gz']
+  onigmo = MiniPortile.new('onigmo', '6.2.0')
+  onigmo.files = ['https://github.com/k-takata/Onigmo/releases/download/Onigmo-6.2.0/onigmo-6.2.0.tar.gz']


We should add the expected sha256

wesleyjellis · 2026-07-17T19:31:07Z

 require 'mkmf'

 def using_system_libraries?
  arg_config('--use-system-libraries', ENV.key?('RUBYJQ_USE_SYSTEM_LIBRARIES'))


we set this in Opslevel, might have to remove it

wesleyjellis · 2026-07-17T19:42:28Z

+begin
+  # Load the precompiled binary matching the current Ruby, if this is a
+  # platform-specific gem packaged by cibuildgem.
+  require "jq/#{RUBY_VERSION[/\d+\.\d+/]}/jq_core"


I don't understand how this magic works

but it is the suggested path here: https://github.com/Shopify/cibuildgem/wiki/1.-Setup-cibuildgem-on-your-project#prepare-your-gem-to-load-the-right-binary

Ok, so the cibuildgem has to actually make a gem with the ruby version in it (eg: require "jq/3.3/jq.core") since the gem's compiled code references a specific ruby version.

There's also a change here from jq_core as the output of the compiled library via ext.lib_dir = 'lib/jq' change below. Apparently it's common and it should Just Work

wesleyjellis · 2026-07-17T19:44:14Z

+
+  # OpsLevel fork of jq: `env`/`$ENV` always return an empty object.
+  recipe = MiniPortile.new('jq', '1.6.opslevel')
+  recipe.files = ['https://github.com/OpsLevel/jq/archive/845f4206dd8a82355325bafffbb54a5155cf67ec.tar.gz']


here as well

…le2 version 2, and tighten dependency to avoid version 3

wesleyjellis · 2026-07-22T21:02:27Z

-    '--disable-maintainer-mode'
+    '--disable-maintainer-mode',
+    '--disable-docs',
+    '--disable-shared',


why the switch from --enabled-shared to disabled?

wesleyjellis · 2026-07-22T21:03:37Z

+# extension's dynamic symbol table: libruby exports its own onig_* functions,
+# and the flat ELF namespace would let calls bind across copies. (Mach-O uses
+# two-level namespaces, and its linker lacks this flag.)
+$LDFLAGS << ' -Wl,--exclude-libs,ALL' unless RUBY_PLATFORM.include?('darwin') # rubocop:disable Style/GlobalVars


What does -Wl actually do?

claude and others added 4 commits July 7, 2026 14:05

make compile on mac

c26a27c

Temporarily run CI on pushes to this branch for pre-merge testing

994102d

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

wesleyjellis commented Jul 20, 2026

View reviewed changes

wesleyjellis added 2 commits July 22, 2026 16:57

follow mini_portile recommendations for enforcing at least mini_porti…

f05a8c8

…le2 version 2, and tighten dependency to avoid version 3

pin archives by sha256

69ebc96

wesleyjellis commented Jul 22, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add precompiled binary gem support and modernize build system#2

Add precompiled binary gem support and modernize build system#2
wesleyjellis wants to merge 6 commits into
masterfrom
claude/precompile-jq-gem-0g9x67

wesleyjellis commented Jul 7, 2026

Uh oh!

wesleyjellis left a comment

Uh oh!

wesleyjellis Jul 17, 2026

Uh oh!

wesleyjellis Jul 17, 2026

Uh oh!

wesleyjellis Jul 17, 2026

Uh oh!

wesleyjellis Jul 17, 2026

Uh oh!

wesleyjellis Jul 22, 2026

Uh oh!

Uh oh!

wesleyjellis Jul 17, 2026

Uh oh!

wesleyjellis Jul 22, 2026

Uh oh!

wesleyjellis Jul 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

wesleyjellis commented Jul 7, 2026

Summary

Key Changes

Notable Implementation Details

Uh oh!

wesleyjellis left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants