-.\" $OpenBSD: ruby-module.5,v 1.42 2023/09/12 17:21:05 schwarze Exp $
+.\" $OpenBSD: ruby-module.5,v 1.43 2023/09/27 21:46:17 jeremy Exp $
.\"
-.\" Copyright (c) 2008 Marc Espie, Jeremy Evans
+.\" Copyright (c) 2011-2015, 2023 Jeremy Evans <jeremy@openbsd.org>
+.\" Copyright (c) 2008, 2011 Marc Espie <espie@openbsd.org>
.\"
.\" All rights reserved.
.\"
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd $Mdocdate: September 12 2023 $
+.Dd $Mdocdate: September 27 2023 $
.Dt RUBY-MODULE 5
.Os
.Sh NAME
.Nd lang/ruby port module
.Sh DESCRIPTION
This manual page documents the behavior of setting
-.Li MODULES=lang/ruby
+.Ev MODULES Ns Li =lang/ruby
in the
.Xr ports 7
tree.
.Pp
-Sets
-.Ev GEM ,
-.Ev GEM_BASE_BIN ,
-.Ev GEM_BASE_LIB ,
-.Ev GEM_BIN ,
-.Ev GEM_BIN_SUFFIX ,
-.Ev GEM_EXTENSIONS_DIR ,
-.Ev GEM_FLAGS ,
-.Ev GEM_LIB ,
-.Ev GEM_MAN_SUFFIX ,
-.Ev MODRUBY_ADJ_FILES ,
-.Ev MODRUBY_ARCH ,
-.Ev MODRUBY_BINREV ,
-.Ev MODRUBY_BIN_RSPEC ,
-.Ev MODRUBY_BUILD_DEPENDS ,
-.Ev MODRUBY_BUILDDEP ,
-.Ev MODRUBY_FLAVOR ,
-.Ev MODRUBY_HANDLE_FLAVORS ,
-.Ev MODRUBY_LIBREV ,
-.Ev MODRUBY_LIB_DEPENDS ,
-.Ev MODRUBY_PKG_PREFIX ,
-.Ev MODRUBY_RELEXAMPLEDIR ,
-.Ev MODRUBY_REV ,
-.Ev MODRUBY_RUBY_ADJ ,
-.Ev MODRUBY_RUN_DEPENDS ,
-.Ev MODRUBY_RUNDEP ,
-.Ev MODRUBY_SITEARCHDIR ,
-.Ev MODRUBY_SITEDIR ,
-.Ev MODRUBY_TEST ,
-.Ev MODRUBY_TEST_ENV ,
-.Ev MODRUBY_TEST_TARGET ,
-.Ev MODRUBY_WANTLIB ,
-.Ev RAKE ,
-and
-.Ev RUBY .
+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.
.Pp
-Appends to
-.Ev CATEGORIES
-and
-.Ev SUBST_VARS .
-Appends to
-.Ev BUILD_DEPENDS
-unless
-.Ev MODRUBY_BUILDDEP
-is set to No or
-.Ev NO_BUILD
-is set to Yes.
-Appends to
-.Ev RUN_DEPENDS
-unless
-.Ev MODRUBY_RUNDEP
-is set to No.
-.Pp
-.Ev MODRUBY_RSPEC3_DEPENDS
-is set to the dependency line for the rspec 3 port for the version of ruby in
-use.
-.Ev RUBY ,
-and
-.Ev RAKE
-are the path to the ruby and rake
-binaries for the related ruby implementation.
-.Ev MODRUBY_BIN_RSPEC
-is the path to the rspec (rspec 3) binaries for the related ruby
-implementation.
-.Pp
-.Ev MODRUBY_RUBY_ADJ
-is a command that takes filename arguments and replaces
-the /usr/bin/env ruby shebang lines with
-.Ev RUBY .
-.Ev MODRUBY_ADJ_FILES
-is a list of filename patterns that will automatically have
-.Ev MODRUBY_RUBY_ADJ
-called on them during pre-configure.
-.Pp
-Creates a do-test target if
-.Ev MODRUBY_TEST
-is used and one is not already defined.
-.Ev MODRUBY_TEST
-can be set to ruby, rake, rspec3, or testrb to
-choose the appropriate binary to run the regress tests.
-.Ev MODRUBY_TEST_ENV
-can be used to set environment variables for the regress tests.
-.Ev MODRUBY_TEST_TARGET
-sets the argument to the regress test program.
-.Pp
-Supports additional
-.Ev CONFIGURE_STYLE Ns s ,
-and setting specific
-.Ev CONFIGURE_STYLE Ns s
-modifies some additional parameters:
-.Bl -bullet
-.It
-The "ruby gem"
-.Ev CONFIGURE_STYLE
-should be used for pure ruby gems without C extensions.
+To allow a single Ruby gem-based port to build packages for multiple versions
+of Ruby, set a specific
+.Ev CONFIGURE_STYLE ,
+which modifies some additional parameters:
+.Bl -tag -width Ds
+.It Ev CONFIGURE_STYLE Ns = Ns Qq ruby gem
+For pure Ruby gems without C extensions.
This adds
.Ev PKG_ARCH
-= * and adds ruby30, ruby31, and ruby32
-.Ev FLAVOR Ns s
-to the port, so the same port can build packages for multiple versions of ruby.
-.It
-The "ruby gem ext"
-.Ev CONFIGURE_STYLE
-should be used for ruby gems with C extensions.
-This adds
-.Ev MODRUBY_LIB_DEPENDS
-to
-.Ev LIB_DEPENDS
-and
-the appropriate libraries and
-.Ev MODRUBY_WANTLIB
-to
-.Ev WANTLIB .
-It also adds ruby30, ruby31, and ruby32
-.Ev FLAVOR Ns s
-to the port.
-If the C extension in the gem requires specific arguments to extconf.rb,
-set those via
+= * to the port.
+.It Ev CONFIGURE_STYLE Ns = Ns Qq ruby gem ext
+For Ruby gems with C extensions.
+To pass additional arguments to
+.Sy gem Cm install
+when building the port, set
+those via
.Ev CONFIGURE_ARGS .
.El
.Pp
-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:
-.Pp
-.Dl category/ruby-foo,${MODRUBY_FLAVOR}
-.Pp
-The "ruby gem" and "ruby gem ext"
-.Ev CONFIGURE_STYLE Ns s
-cause the
+.Ev CONFIGURE_STYLE Ns = Ns Qq ruby gem
+and
+.Ev CONFIGURE_STYLE Ns = Ns Qq ruby gem ext
+both add ruby30, ruby31, and ruby32
+.Ev FLAVOR Ns s
+to the port.
+They also cause the
.Ev FULLPKGNAME
to use the
-.Ev FLAVOR
-instead of ruby as the package prefix.
-Specifying
-.Ev MODRUBY_FLAVOR
-is necessary so that if a ruby x.y package is being built for the current
-port, it depends on the ruby x.y package of the dependencies.
+.Ev FLAVOR Ns \-
+instead of ruby\- as the package prefix.
.Pp
-The ports system defaults to using ruby 3.2 if the version of ruby is not
+The ports system defaults to using Ruby 3.2 if the version of Ruby is not
specified.
-If you want to specify a version for a gem port, use a specific
+To specify a version for a gem port, use a specific
.Ev FLAVOR ,
-such as ruby31 to use ruby 3.1.
-If you want to specify a version for a non-gem port, set
+such as ruby31 to use Ruby 3.1.
+To specify the Ruby version to use for a non Ruby-gem port, set
.Ev MODRUBY_REV
-for the version of ruby you want to use (3.0, 3.1, 3.2).
+to 3.0, 3.1, or 3.2.
+.Pp
+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:
+.Pp
+.Dl category/ruby\-foo,${MODRUBY_FLAVOR}
.Pp
-If you do not want the ports system to automatically set up
+To prevent the ports system from automatically setting up
.Ev FLAVOR Ns s
-when using a gem port, set
+in a gem port, set
.Ev MODRUBY_HANDLE_FLAVORS
-to No.
-Similarly, if you want the ports system to automatically set up
+to
+.Cm \&No .
+Similarly, to let the ports system automatically set up
.Ev FLAVOR Ns s
-when using a non-gem port, set
+in a non-gem port, set
.Ev MODRUBY_HANDLE_FLAVORS
-to Yes.
+to
+.Cm Yes .
When
.Ev MODRUBY_HANDLE_FLAVORS
-is Yes, the ports system automatically adds the appropriate prefix to the
+is
+.Cm Yes ,
+the ports system automatically adds the appropriate prefix to the
.Ev FULLPKGNAME
-(e.g. ruby31- for ruby 3.1, ruby32- for ruby 3.2).
-Additionally, it adds
-.Ev GEM_BIN_SUFFIX
-and
-.Ev GEM_MAN_SUFFIX
-to
-.Ev SUBST_VARS
-so that the PLISTs will work on multiple ruby versions.
+(e.g. ruby31\- for ruby 3.1, ruby32\- for ruby 3.2).
.Pp
-For ruby gem ports that can work on multiple ruby versions or implementations,
-any binary file entries in the PLIST should be appended with
-.Ev GEM_BIN_SUFFIX .
-This is because the gem binaries for multiple ruby versions are all
+For Ruby gem ports that can work on multiple Ruby versions, append
+.Ev 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
.Pa ${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
+specific to a Ruby implementation (such as under
.Pa ${LOCALBASE}/share ) ,
should use
.Ev GEM_MAN_SUFFIX
.Ev FLAVOR Ns s
do not conflict.
.Pp
-make update-plist may remove
+make update\-plist may remove
.Ev GEM_BIN_SUFFIX
and
.Ev GEM_MAN_SUFFIX
-from the PLIST, or use them in inappropriate places where they shouldn't be
-used, 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
+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
.Ev FLAVOR
-you are using (such as files under the extension source directory), which may
+(such as files under the extension source directory), which may
not exist for other
.Ev FLAVOR Ns s ,
-so always manually check the result of make update-plist and manually test that
-you can build the other
+so always manually check the result of make update\-plist and manually test that
+all supported
.Ev FLAVOR Ns s
-before committing.
-Additionally, for gems with C extensions, make update-plist may add back the
+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
+to double check that all files added by make update\-plist should be included
in the package.
+.Pp
+The lang/ruby module creates a do\-test target if
+.Ev MODRUBY_TEST
+is used and one is not already defined.
+.Pp
+The lang/ruby module appends to the following variables:
+.Bl -tag -width Ds
+.It Ev BUILD_DEPENDS
+Adds dependency on version of Ruby in use unless
+.Ev MODRUBY_BUILDDEP
+is set to
+.Cm \&No ,
+or
+.Ev NO_BUILD
+is set to
+.Cm Yes .
+.It Ev CATEGORIES
+Adds the lang/ruby category.
+.It Ev RUN_DEPENDS
+Adds dependency on version of Ruby in use unless
+.Ev MODRUBY_RUNDEP
+is set to
+.Cm \&No .
+.It Ev TEST_DEPENDS
+Adds the rspec dependency if
+.Ev MODRUBY_TEST
+is set to rspec3.
+.It Ev SUBST_VARS
+Adds
+.Ev GEM_EXTENSIONS_DIR ,
+.Ev MODRUBY_RELEXAMPLEDIR ,
+.Ev MODRUBY_SITEARCHDIR ,
+.Ev MODRUBY_SITEDIR ,
+.Ev MODRUBY_LIBREV ,
+.Ev MODRUBY_ARCH ,
+.Ev GEM_LIB ,
+.Ev GEM_BIN ,
+and
+.Ev DISTNAME .
+.It Ev UPDATE_PLIST_ARGS
+Adds options so that
+.Ev MODRUBY_RELEXAMPLEDIR ,
+.Ev MODRUBY_SITEARCHDIR ,
+.Ev MODRUBY_SITEDIR ,
+.Ev GEM_LIB ,
+and
+.Ev GEM_BIN
+are only substituted at the start of paths.
+.El
+.Pp
+If using
+.Ev CONFIGURE_STYLE Ns = Ns Qq ruby gem
+or
+.Ev CONFIGURE_STYLE Ns = Ns Qq ruby gem ext ,
+it also appends to the following variables:
+.Bl -tag -width Ds
+.It Ev EXTRACT_CASES
+Adds support for extracting .gem files.
+.El
+.Pp
+If using
+.Ev CONFIGURE_STYLE Ns = Ns Qq ruby gem ext ,
+it also appends to the following variables:
+.Bl -tag -width Ds
+.It Ev WANTLIB
+Adds libraries used by Ruby.
+.It Ev LIB_DEPENDS
+Adds
+.Ev MODRUBY_LIB_DEPENDS .
+.It Ev PKG_ARGS
+Adds additional PLIST so that loading native extensions will not attempt to
+rebuild them at runtime.
+.It Ev SUBST_VARS
+Adds
+.Ev GEM_EXTENSIONS_DIR .
+.El
+.Pp
+If using
+.Ev MODRUBY_HANDLE_FLAVORS Ns = Ns Yes ,
+it also appends to the following variables:
+.Bl -tag -width Ds
+.It Ev SUBST_VARS
+Adds
+.Ev GEM_BIN_SUFFIX
+and
+.Ev GEM_MAN_SUFFIX
+to
+.Ev SUBST_VARS
+so that the PLISTs work on multiple Ruby versions.
+.El
+.Pp
+The lang/ruby module sets the following variables:
+.Bl -tag -width Ds
+.It Ev GEM
+The path to the appropriate
+.Sy gem
+binary for the current Ruby version (/usr/local/bin/gem${MODRUBY_BINREV}).
+.It Ev GEM_BASE_BIN
+The absolute path where the
+.Sy gem
+program will install the executable
+files provided by the gem (if any) during the fake target.
+.It Ev GEM_BASE_LIB
+The absolute path where the
+.Sy gem
+program will install library files
+provided by the gem during the fake target.
+.It Ev GEM_BIN
+The relative path under
+.Ev PREFIX
+where the package installs the gem's executable files.
+.It Ev GEM_BIN_SUFFIX
+The suffix to use for the gem's executable files, so that separate
+.Ev FLAVOR Ns s
+of the port do not conflict.
+.It Ev GEM_EXTENSIONS_DIR
+The relative path under
+.Ev PREFIX
+where the package installs Ruby-version specific files for Ruby gems
+with C extensions.
+.It Ev GEM_FLAGS
+Option flags for
+.Sy gem Cm install
+when building the port.
+.It Ev GEM_LIB
+The relative path under
+.Ev PREFIX
+where Ruby gem files are stored for the Ruby version in use.
+.It Ev GEM_MAN_SUFFIX
+The suffix to use for the gem's manual pages, so that separate
+.Ev FLAVOR Ns s
+of the port do not conflict.
+.It Ev MODRUBY_ADJ_FILES
+A list of filename patterns that will automatically have
+.Ev MODRUBY_RUBY_ADJ
+called on them during pre\-configure.
+.It Ev MODRUBY_ARCH
+The plaform-specific string used by Ruby for files installed
+into platform-specific directories.
+.It Ev MODRUBY_BINREV
+The same as
+.Ev MODRUBY_REV
+except without the dot
+.Pq Ql \&. ,
+reflecting the suffix used by the
+programs for the Ruby version in use.
+.It Ev MODRUBY_BIN_RSPEC
+The path to the rspec (rspec 3) binaries for the Ruby
+version in use.
+.It Ev MODRUBY_BUILD_DEPENDS
+The same as
+.Ev MODRUBY_RUN_DEPENDS .
+It is designed to be used in
+.Ev BUILD_DEPENDS
+values for other ports depending on Ruby.
+.It Ev MODRUBY_BUILDDEP
+If Ruby does not need to be installed
+while building the package(s), set to
+.Cm \&No .
+The default is
+.Cm Yes .
+.It Ev MODRUBY_FLAVOR
+The FLAVOR to use for Ruby dependencies to ensure that
+they use the same version of Ruby as the current port.
+.It Ev MODRUBY_HANDLE_FLAVORS
+Determines whether the port allows building with multiple
+.Ev FLAVOR Ns s,
+with each
+.Ev FLAVOR
+supporting a separate Ruby version.
+.It Ev MODRUBY_LIBREV
+The same as
+.Ev MODRUBY_REV .
+.It Ev MODRUBY_LIB_DEPENDS
+The same as
+.Ev MODRUBY_RUN_DEPENDS .
+It is designed to be used in
+.Ev LIB_DEPENDS
+values for other ports depending on Ruby.
+.It Ev MODRUBY_PKG_PREFIX
+The prefix to use for packages built using the lang/ruby module,
+if the port support building with multiple Ruby versions.
+.It Ev MODRUBY_RELEXAMPLEDIR
+The relative path under
+.Ev PREFIX
+where the package installs example files for non-Ruby gem ports.
+.It Ev MODRUBY_REV
+Includes the major and minor versions of the version of Ruby in use,
+separated by a dot
+.Pq Ql \&. .
+The port can override the value to specify which Ruby version to use,
+if the port sets or defaults to
+.Ev MODRUBY_HANDLE_FLAVORS Ns =Yes .
+.It Ev MODRUBY_RUBY_ADJ
+A command that takes filename arguments and replaces
+the
+.Pa /usr/bin/env
+ruby shebang lines with
+.Ev RUBY .
+.It Ev MODRUBY_RUN_DEPENDS
+The port path for the Ruby version in use.
+It is designed to be used in
+.Ev RUN_DEPENDS
+values for other ports depending on Ruby.
+.It Ev MODRUBY_RUNDEP
+If the packages do not depend on Ruby at runtime, set to
+.Cm \&No .
+The default is
+.Cm Yes .
+.It Ev MODRUBY_SITEARCHDIR
+The relative path under
+.Ev PREFIX
+where the package installs platform-specific library files for non-Ruby gem
+ports.
+.It Ev MODRUBY_SITEDIR
+The relative path under
+.Ev PREFIX
+where the package installs non-platform-specific library files for non-Ruby
+gem ports.
+.It Ev MODRUBY_TEST
+Set to
+.Cm ruby ,
+.Cm rake ,
+.Cm rspec3 ,
+or
+.Cm testrb
+to choose the appropriate program to run the regress tests, if the port
+includes tests.
+.It Ev MODRUBY_TEST_ENV
+Sets environment variables for the regress tests.
+.It Ev MODRUBY_TEST_TARGET
+Sets the argument to the regress test program.
+.It Ev MODRUBY_WANTLIB
+Includes the library-specs for the Ruby version in use.
+.It Ev RAKE
+The path to the
+.Sy rake
+program for the Ruby version in use (/usr/local/bin/rake${MODRUBY_BINREV}).
+.It Ev RUBY
+The path to the
+.Xr ruby 1
+program for the Ruby version in use (/usr/local/bin/ruby${MODRUBY_BINREV}).
+.El
.Sh SEE ALSO
+.Xr bsd.port.mk 5 ,
.Xr port-modules 5
projects / openbsd / commitdiff