RUBY-MODULE(5) | File Formats Manual | RUBY-MODULE(5)

# NAME

`ruby-module` — lang/ruby port module

# DESCRIPTION

This manual page documents the behavior of setting `MODULES``=lang/ruby` in the ports(7) tree.

The main usage of the lang/ruby module is to allow a single Ruby gem-based port to build packages for multiple versions of Ruby. The lang/ruby module also simplifies ports that depend on Ruby by automatically setting up the correct dependencies and defining commonly needed variables.

To allow a single Ruby gem-based port to 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. To pass additional arguments to gem `install` when building the port, set those via `CONFIGURE_ARGS`.

`CONFIGURE_STYLE`="ruby gem" and `CONFIGURE_STYLE`="ruby gem ext" both add ruby32, ruby33, and ruby34 `FLAVOR`s to the port. They also cause the `FULLPKGNAME` to use the `FLAVOR`- instead of ruby- as the package prefix.

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.2, 3.3, or 3.4.

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 `FLAVOR`s in a gem port, set `MODRUBY_HANDLE_FLAVORS` to `No`. Similarly, to let the ports system automatically set up `FLAVOR`s 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. ruby33- for ruby 3.3, 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 `FLAVOR`s do not conflict.

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 `FLAVOR`s, so always manually check the result of make update-plist and manually test that all supported `FLAVOR`s 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.

The lang/ruby module appends to the following variables:

`BUILD_DEPENDS`
  Adds dependency on 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 dependency on 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.

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 `FLAVOR`s 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 `FLAVOR`s 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 `FLAVOR`s, 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)

June 28, 2025 | Debian