RUBY-MODULE(5)

💖 NAME 💖

Okay bestie, meet ruby-module(5) — the lang/ruby port module. This page is chillin' in the File Formats Manual, and it's all about what happens when you set MODULES=lang/ruby in the ports(7) tree. 💅

---

✨ DESCRIPTION ✨

The big main-character use of the lang/ruby module is letting one single Ruby gem-based port build packages for multiple versions of Ruby. It also makes ports that depend on Ruby way easier, because it automatically sets up the correct dependencies and defines the commonly needed variables. No cap. 🫶

🎀 CONFIGURE_STYLE and the multi-Ruby glow-up 🎀

To let a single Ruby gem-based port build packages for multiple versions of Ruby, set a specific CONFIGURE_STYLE, which modifies some additional parameters:

• CONFIGURE_STYLE="ruby gem" — for pure Ruby gems without C extensions. This adds PKG_ARCH = * to the port. 🧚
• CONFIGURE_STYLE="ruby gem ext" — for Ruby gems with C extensions. Wanna pass additional arguments to gem install when building the port? Set those via CONFIGURE_ARGS. ✨

Both CONFIGURE_STYLE="ruby gem" and CONFIGURE_STYLE="ruby gem ext" add ruby33, ruby34, and ruby40 FLAVORs to the port. They also make FULLPKGNAME use FLAVOR- instead of ruby- as the package prefix. Iconic. 👑

The ports system defaults to using Ruby 3.4 if the version of Ruby is not specified. To specify a version for a gem port, use a specific FLAVOR, such as ruby33 to use Ruby 3.3. To specify the Ruby version to use for a non Ruby-gem port, set MODRUBY_REV to 3.3, 3.4, or 4.0. Easy. 🌸

To ensure that dependencies use the same Ruby implementation as the current port, all Ruby gem dependencies specified in the port should use this format:

category/ruby-foo,${MODRUBY_FLAVOR}

To prevent the ports system from automatically setting up FLAVORs in a gem port, set MODRUBY_HANDLE_FLAVORS to No. Similarly, to let the ports system automatically set up FLAVORs in a non-gem port, set MODRUBY_HANDLE_FLAVORS to Yes. When MODRUBY_HANDLE_FLAVORS is Yes, the ports system automatically adds the appropriate prefix to the FULLPKGNAME (e.g. ruby40- for ruby 4.0, ruby34- for ruby 3.4). 🦋

For Ruby gem ports that can work on multiple Ruby versions, append GEM_BIN_SUFFIX to every binary file entry in the PLIST. This is because the gem binaries for multiple Ruby versions are all installed to ${LOCALBASE}/bin, and the binaries all use a version-specific suffix. Any man pages and other files that would be installed to locations not specific to a Ruby implementation (such as under ${LOCALBASE}/share), should use GEM_MAN_SUFFIX before the extension so the different FLAVORs do not conflict. 🌈

Careful, bestie! make update-plist may remove GEM_BIN_SUFFIX and GEM_MAN_SUFFIX from the PLIST, or use them in inappropriate places, so be careful when updating gem ports with binaries or man pages. Additionally, for gem ports with C extensions, make update-plist will add back files used by the specific FLAVOR (such as files under the extension source directory), which may not exist for other FLAVORs, so always manually check the result of make update-plist and manually test that all supported FLAVORs are buildable before committing. Additionally, for gems with C extensions, make update-plist may add back the extension source files, which shouldn't be included in the files, so make sure to double check that all files added by make update-plist should be included in the package. 😭

The lang/ruby module creates a do-test target if MODRUBY_TEST is used and one is not already defined.

🫶 Variables it appends to (the glow-up list) 🫶

The lang/ruby module appends to the following variables:

• BUILD_DEPENDS — adds a dependency on the version of Ruby in use unless MODRUBY_BUILDDEP is set to No, or NO_BUILD is set to Yes.
• CATEGORIES — adds the lang/ruby category.
• RUN_DEPENDS — adds a dependency on the version of Ruby in use unless MODRUBY_RUNDEP is set to No.
• TEST_DEPENDS — adds the rspec dependency if MODRUBY_TEST is set to rspec3.
• SUBST_VARS — adds GEM_EXTENSIONS_DIR, MODRUBY_RELEXAMPLEDIR, MODRUBY_SITEARCHDIR, MODRUBY_SITEDIR, MODRUBY_LIBREV, MODRUBY_ARCH, GEM_LIB, GEM_BIN, and DISTNAME.
• UPDATE_PLIST_ARGS — adds options so that MODRUBY_RELEXAMPLEDIR, MODRUBY_SITEARCHDIR, MODRUBY_SITEDIR, GEM_LIB, and GEM_BIN are only substituted at the start of paths.

If using CONFIGURE_STYLE="ruby gem" or CONFIGURE_STYLE="ruby gem ext", it also appends to the following variables:

• EXTRACT_CASES — adds support for extracting .gem files.

If using CONFIGURE_STYLE="ruby gem ext", it also appends to the following variables:

• WANTLIB — adds libraries used by Ruby.
• LIB_DEPENDS — adds MODRUBY_LIB_DEPENDS.
• PKG_ARGS — adds additional PLIST so that loading native extensions will not attempt to rebuild them at runtime.
• SUBST_VARS — adds GEM_EXTENSIONS_DIR.

If using MODRUBY_HANDLE_FLAVORS=Yes, it also appends to the following variables:

• SUBST_VARS — adds GEM_BIN_SUFFIX and GEM_MAN_SUFFIX to SUBST_VARS so that the PLISTs work on multiple Ruby versions.

🌟 Variables it sets (main character list) 🌟

The lang/ruby module sets the following variables:

• GEM — the path to the appropriate gem binary for the current Ruby version (/usr/local/bin/gem${MODRUBY_BINREV}).
• GEM_BASE_BIN — the absolute path where the gem program will install the executable files provided by the gem (if any) during the fake target.
• GEM_BASE_LIB — the absolute path where the gem program will install library files provided by the gem during the fake target.
• GEM_BIN — the relative path under PREFIX where the package installs the gem's executable files.
• GEM_BIN_SUFFIX — the suffix to use for the gem's executable files, so that separate FLAVORs of the port do not conflict.
• GEM_EXTENSIONS_DIR — the relative path under PREFIX where the package installs Ruby-version specific files for Ruby gems with C extensions.
• GEM_FLAGS — option flags for gem install when building the port.
• GEM_LIB — the relative path under PREFIX where Ruby gem files are stored for the Ruby version in use.
• GEM_MAN_SUFFIX — the suffix to use for the gem's manual pages, so that separate FLAVORs of the port do not conflict.
• MODRUBY_ADJ_FILES — a list of filename patterns that will automatically have MODRUBY_RUBY_ADJ called on them during pre-configure.
• MODRUBY_ARCH — the platform-specific string used by Ruby for files installed into platform-specific directories.
• MODRUBY_BINREV — the same as MODRUBY_REV except without the dot (.), reflecting the suffix used by the programs for the Ruby version in use.
• MODRUBY_BIN_RSPEC — the path to the rspec (rspec 3) binaries for the Ruby version in use.
• MODRUBY_BUILD_DEPENDS — the same as MODRUBY_RUN_DEPENDS. It is designed to be used in BUILD_DEPENDS values for other ports depending on Ruby.
• MODRUBY_BUILDDEP — if Ruby does not need to be installed while building the package(s), set to No. The default is Yes.
• MODRUBY_FLAVOR — the FLAVOR to use for Ruby dependencies to ensure that they use the same version of Ruby as the current port.
• MODRUBY_HANDLE_FLAVORS — determines whether the port allows building with multiple FLAVORs, with each FLAVOR supporting a separate Ruby version.
• MODRUBY_LIBREV — the same as MODRUBY_REV.
• MODRUBY_LIB_DEPENDS — the same as MODRUBY_RUN_DEPENDS. It is designed to be used in LIB_DEPENDS values for other ports depending on Ruby.
• MODRUBY_PKG_PREFIX — the prefix to use for packages built using the lang/ruby module, if the port support building with multiple Ruby versions.
• MODRUBY_RELEXAMPLEDIR — the relative path under PREFIX where the package installs example files for non-Ruby gem ports.
• MODRUBY_REV — includes the major and minor versions of the version of Ruby in use, separated by a dot (.). The port can override the value to specify which Ruby version to use, if the port sets or defaults to MODRUBY_HANDLE_FLAVORS=Yes.
• MODRUBY_RUBY_ADJ — a command that takes filename arguments and replaces the /usr/bin/env ruby shebang lines with RUBY.
• MODRUBY_RUN_DEPENDS — the port path for the Ruby version in use. It is designed to be used in RUN_DEPENDS values for other ports depending on Ruby.
• MODRUBY_RUNDEP — if the packages do not depend on Ruby at runtime, set to No. The default is Yes.
• MODRUBY_SITEARCHDIR — the relative path under PREFIX where the package installs platform-specific library files for non-Ruby gem ports.
• MODRUBY_SITEDIR — the relative path under PREFIX where the package installs non-platform-specific library files for non-Ruby gem ports.
• MODRUBY_TEST — set to ruby, rake, rspec3, or testrb to choose the appropriate program to run the regress tests, if the port includes tests.
• MODRUBY_TEST_ENV — sets environment variables for the regress tests.
• MODRUBY_TEST_TARGET — sets the argument to the regress test program.
• MODRUBY_WANTLIB — includes the library-specs for the Ruby version in use.
• RAKE — the path to the rake program for the Ruby version in use (/usr/local/bin/rake${MODRUBY_BINREV}).
• RUBY — the path to the ruby(1) program for the Ruby version in use (/usr/local/bin/ruby${MODRUBY_BINREV}).

---

🦋 SEE ALSO 🦋

• bsd.port.mk(5)
• port-modules(5)

---

That's the whole vibe, bestie. This page is marked RUBY-MODULE(5), and the footer says Debian / December 27, 2025 — mwah. 💋