.\"	$OpenBSD: ruby-module.5,v 1.4 2012/09/28 16:04:30 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: September 28 2012 $
.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 MODULE=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_RUN_DEPENDS ,
.Ev MODRUBY_LIB_DEPENDS ,
.Ev MODRUBY_BUILD_DEPENDS ,
.Ev MODRUBY_ICONV_DEPENDS ,
.Ev MODRUBY_LIBDIR ,
.Ev MODRUBY_DOCDIR ,
.Ev MODRUBY_SITEARCHDIR ,
.Ev MODRUBY_SITEDIR ,
.Ev MODRUBY_ARCH ,
.Ev MODRUBY_EXAMPLEDIR ,
.Ev MODRUBY_RUBY_ADJ ,
.Ev MODRUBY_ADJ_FILES ,
.Ev GEM_BIN_SUFFIX ,
.Ev GEM_MAN_SUFFIX ,
.Ev MODRUBY_LIBREV ,
.Ev MODRUBY_BINREV ,
.Ev MODRUBY_PKGSPEC ,
.Ev MODRUBY_PKG_PREFIX ,
.Ev MODRUBY_RAKE_DEPENDS ,
.Ev MODRUBY_RSPEC_DEPENDS ,
.Ev MODRUBY_WANTLIB ,
.Ev MODRUBY_FLAVOR ,
.Ev MODRUBY_REGRESS ,
.Ev MODRUBY_REGRESS_TARGET ,
.Ev MODRUBY_REGRESS_DIR ,
.Ev MODRUBY_REGRESS_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 ,
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 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 2) 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-regress target if
.Ev MODRUBY_REGRESS
is used and one is not already defined.
.Ev MODRUBY_REGRESS
can be set to ruby, rake, rspec, rspec2, or testrb to
choose the appropriate binary to run the regress tests.
.Ev MODRUBY_REGRESS_ENV
can be used to set environment variables for the regress tests.
.Ev MODRUBY_REGRESS_DIR
can be used to set the directory in which to execute
the regress tests, it defaults to
.Ev WRKSRC .
.Ev MODRUBY_REGRESS_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 ruby18, ruby19, rbx, 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 SHARED_ONLY Ns =Yes
and adds
.Ev MODRUBY_LIB_DEPENDS
to
.Ev LIB_DEPENDS
and
c, m, and
.Ev MODRUBY_WANTLIB
to
.Ev WANTLIB .
It also adds ruby18, ruby19, and rbx
.Ev FLAVOR Ns s
to the port.
.It
The "ruby extconf"
.Ev CONFIGURE_STYLE
is similar to the "ruby gem ext"
.Ev CONFIGURE_STYLE ,
except that it is used when the package is not distributed as a ruby gem.
.El
.Pp
To ensure that dependencies use the same ruby implementation as the
current port, all ruby gem/extconf dependencies specified in the port
should use this format:
.Pp
.Dl category/ruby-foo,${MODRUBY_FLAVOR}
.Pp
When building a gem/extconf port without a
.Ev FLAVOR ,
the ports system will automatically use the ruby19 FLAVOR by default.
Explicitly specify the ruby18
.Ev FLAVOR
to build a package for ruby 1.8.
.Pp
Use of a ruby19, rbx, or jruby
.Ev FLAVOR
causes 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 1.9 package is being built for the current
port, it depends on the ruby 1.9 package of the
dependencies.
.Pp
For ruby gem ports that can work on both ruby 1.8 and ruby 1.9, any binary
file entries in the PLIST should be appended with
.Ev GEM_BIN_SUFFIX .
This is because the ruby 1.8 and ruby 1.9 gem binaries are both installed to
.Pa ${LOCALBASE}/bin ,
and ruby 1.9 installs the binaries with a 19 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.
make update-plist currently removes
.Ev GEM_BIN_SUFFIX
and
.Ev GEM_MAN_SUFFIX ,
so be careful when updating gem ports with binaries or man pages.
.Sh SEE ALSO
.Xr port-modules 5