path: root/share/man/man5/ruby-module.5

.\"	$OpenBSD: ruby-module.5,v 1.35 2022/01/04 19:51:24 jeremy Exp $
.\"
.\" Copyright (c) 2008 Marc Espie, Jeremy Evans
.\"
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (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: January 4 2022 $
.Dt RUBY-MODULE 5
.Os
.Sh NAME
.Nm ruby-module
.Nd lang/ruby port module
.Sh DESCRIPTION
This manual page documents the behavior of setting
.Li MODULES=lang/ruby
in the
.Xr ports 7
tree.
.Pp
Sets
.Ev MODRUBY_REV ,
.Ev RUBY ,
.Ev RAKE ,
.Ev RSPEC ,
.Ev MODRUBY_BIN_TESTRB ,
.Ev MODRUBY_BIN_RSPEC ,
.Ev MODRUBY_WANTLIB ,
.Ev MODRUBY_RUN_DEPENDS ,
.Ev MODRUBY_LIB_DEPENDS ,
.Ev MODRUBY_BUILD_DEPENDS ,
.Ev MODRUBY_RSPEC_DEPENDS ,
.Ev MODRUBY_RSPEC3_DEPENDS ,
.Ev MODRUBY_RUBY_ADJ ,
.Ev MODRUBY_ADJ_FILES ,
.Ev MODRUBY_LIBDIR ,
.Ev MODRUBY_DOCDIR ,
.Ev MODRUBY_SITEARCHDIR ,
.Ev MODRUBY_SITEDIR ,
.Ev MODRUBY_EXAMPLEDIR ,
.Ev MODRUBY_ARCH ,
.Ev MODRUBY_LIBREV ,
.Ev MODRUBY_BINREV ,
.Ev MODRUBY_HANDLE_FLAVORS ,
.Ev MODRUBY_PKG_PREFIX ,
.Ev MODRUBY_FLAVOR ,
.Ev MODRUBY_TEST ,
.Ev MODRUBY_TEST_TARGET ,
.Ev MODRUBY_TEST_DIR ,
.Ev MODRUBY_TEST_ENV ,
.Ev MODRUBY_BUILD_TARGET ,
.Ev MODRUBY_INSTALL_TARGET ,
.Ev MODRUBY_EXTRACT_TARGET ,
.Ev GEM ,
.Ev GEM_BIN ,
.Ev GEM_LIB ,
.Ev GEM_BASE_LIB ,
.Ev GEM_ABS_PATH ,
.Ev GEM_BASE_BIN ,
.Ev GEM_BIN_SUFFIX ,
.Ev GEM_MAN_SUFFIX ,
and
.Ev GEM_FLAGS .
.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_RSPEC_DEPENDS
is set to the dependency line for the rspec 1 port for the version of ruby in
use.
.Ev MODRUBY_RSPEC3_DEPENDS
is set to the dependency line for the rspec 3 port for the version of ruby in
use.
.Ev RUBY ,
.Ev RAKE ,
and
.Ev MODRUBY_BIN_TESTRB
are the path to the ruby, rake, and
testrb binaries for the related ruby implementation.
.Ev RSPEC
and
.Ev MODRUBY_BIN_RSPEC
are the path to the spec (rspec 1) and
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, rspec, 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_DIR
can be used to set the directory in which to execute
the regress tests, it defaults to
.Ev WRKSRC .
.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.
This adds
.Ev PKG_ARCH
= * and adds ruby27, ruby30, ruby31, and jruby
.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 ruby27, ruby30, and ruby31
.Ev FLAVOR Ns s
to the port.
If the C extension in the gem requires specific arguments to extconf.rb, 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 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.
.Pp
The ports system defaults to using ruby 3.0 if the version of ruby is not
specified.
If you want to specify a version for a gem port, use a specific
.Ev FLAVOR ,
such as ruby27 to use ruby 2.7.
If you want to specify a version for a non-gem port, set
.Ev MODRUBY_REV
for the version of ruby you want to use (2.7, 3.0, jruby).
.Pp
If you do not want the ports system to automatically set up
.Ev FLAVOR Ns s
when using a gem port, set
.Ev MODRUBY_HANDLE_FLAVORS
to No.
Similarly, if you want the ports system to automatically set up
.Ev FLAVOR Ns s
when using a non-gem port, set
.Ev MODRUBY_HANDLE_FLAVORS
to Yes.
When
.Ev MODRUBY_HANDLE_FLAVORS
is Yes, the ports system automatically adds the appropriate prefix to the
.Ev FULLPKGNAME
(e.g. jruby- for jruby, ruby30- for ruby 3.0).
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.
.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
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
.Pa ${LOCALBASE}/share ) ,
should use
.Ev GEM_MAN_SUFFIX
before the extension so the different
.Ev FLAVOR Ns s
do not conflict.
.Pp
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
files used by the specific
.Ev FLAVOR
you are using (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
.Ev FLAVOR Ns s
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.
.Sh SEE ALSO
.Xr port-modules 5