sync

[bitrig.git] / share / man / man5 / ruby-module.5

.\"     $OpenBSD: ruby-module.5,v 1.9 2013/03/21 10:53:13 jmc 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: March 21 2013 $
.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_WANTLIB ,
.Ev MODRUBY_RUN_DEPENDS ,
.Ev MODRUBY_LIB_DEPENDS ,
.Ev MODRUBY_BUILD_DEPENDS ,
.Ev MODRUBY_ICONV_DEPENDS ,
.Ev MODRUBY_RAKE_DEPENDS ,
.Ev MODRUBY_RSPEC_DEPENDS ,
.Ev MODRUBY_RSPEC2_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_ICONV_DEPENDS
is set to the dependency line for the iconv port for the version of ruby in
use.
.Ev MODRUBY_RAKE_DEPENDS
is set to the dependency line for the rake port for the version of ruby in
use.
.Ev MODRUBY_RSPEC_DEPENDS
is set to the dependency line for the rspec 1 port for the version of ruby in
use.
.Ev MODRUBY_RSPEC2_DEPENDS
is set to the dependency line for the rspec 2 port for the version of ruby in
use.
.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-test target if
.Ev MODRUBY_TEST
is used and one is not already defined.
.Ev MODRUBY_TEST
can be set to ruby, rake, rspec, rspec2, 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 ruby18, ruby19, ruby20, 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, ruby20, and rbx
.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 .
.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 distributed with an extconf.rb file
and not 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
Use of a ruby19, ruby20, 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
The ports system defaults to using ruby 1.9 if the version of ruby is not
specified.
If you want to specify a version for a gem/extconf port, use a specific
.Ev FLAVOR ,
such as ruby18 to use ruby 1.8.
If you want to specify a version for a non-gem/extconf port, set
.Ev MODRUBY_REV
for the version of ruby you want to use (1.8, 1.9, 2.0, jruby, rbx).
.Pp
If you do not want the ports system to automatically set up
.Ev FLAVOR Ns s
when using a gem/extconf 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/extconf 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. ruby- for ruby 1.8, ruby19- for ruby 1.9).
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 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