1.\" $OpenBSD: ruby-module.5,v 1.19 2016/03/22 16:02:02 naddy Exp $ 2.\" 3.\" Copyright (c) 2008 Marc Espie, Jeremy Evans 4.\" 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 17.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 20.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 21.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 22.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 23.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 25.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd $Mdocdate: March 22 2016 $ 28.Dt RUBY-MODULE 5 29.Os 30.Sh NAME 31.Nm ruby-module 32.Nd lang/ruby port module 33.Sh DESCRIPTION 34This manual page documents the behavior of setting 35.Li MODULE=lang/ruby 36in the 37.Xr ports 7 38tree. 39.Pp 40Sets 41.Ev MODRUBY_REV , 42.Ev RUBY , 43.Ev RAKE , 44.Ev RSPEC , 45.Ev MODRUBY_BIN_TESTRB , 46.Ev MODRUBY_BIN_RSPEC , 47.Ev MODRUBY_WANTLIB , 48.Ev MODRUBY_RUN_DEPENDS , 49.Ev MODRUBY_LIB_DEPENDS , 50.Ev MODRUBY_BUILD_DEPENDS , 51.Ev MODRUBY_RSPEC_DEPENDS , 52.Ev MODRUBY_RSPEC3_DEPENDS , 53.Ev MODRUBY_RUBY_ADJ , 54.Ev MODRUBY_ADJ_FILES , 55.Ev MODRUBY_LIBDIR , 56.Ev MODRUBY_DOCDIR , 57.Ev MODRUBY_SITEARCHDIR , 58.Ev MODRUBY_SITEDIR , 59.Ev MODRUBY_EXAMPLEDIR , 60.Ev MODRUBY_ARCH , 61.Ev MODRUBY_LIBREV , 62.Ev MODRUBY_BINREV , 63.Ev MODRUBY_HANDLE_FLAVORS , 64.Ev MODRUBY_PKG_PREFIX , 65.Ev MODRUBY_FLAVOR , 66.Ev MODRUBY_TEST , 67.Ev MODRUBY_TEST_TARGET , 68.Ev MODRUBY_TEST_DIR , 69.Ev MODRUBY_TEST_ENV , 70.Ev MODRUBY_BUILD_TARGET , 71.Ev MODRUBY_INSTALL_TARGET , 72.Ev MODRUBY_EXTRACT_TARGET , 73.Ev GEM , 74.Ev GEM_BIN , 75.Ev GEM_LIB , 76.Ev GEM_BASE_LIB , 77.Ev GEM_ABS_PATH , 78.Ev GEM_BASE_BIN , 79.Ev GEM_BIN_SUFFIX , 80.Ev GEM_MAN_SUFFIX , 81and 82.Ev GEM_FLAGS . 83.Pp 84Appends to 85.Ev CATEGORIES 86and 87.Ev SUBST_VARS . 88Appends to 89.Ev BUILD_DEPENDS 90unless 91.Ev MODRUBY_BUILDDEP 92is set to No or 93.Ev NO_BUILD 94is set to Yes. 95Appends to 96.Ev RUN_DEPENDS 97unless 98.Ev MODRUBY_RUNDEP 99is set to No. 100.Pp 101.Ev MODRUBY_RSPEC_DEPENDS 102is set to the dependency line for the rspec 1 port for the version of ruby in 103use. 104.Ev MODRUBY_RSPEC3_DEPENDS 105is set to the dependency line for the rspec 3 port for the version of ruby in 106use. 107.Ev RUBY , 108.Ev RAKE , 109and 110.Ev MODRUBY_BIN_TESTRB 111are the path to the ruby, rake, and 112testrb binaries for the related ruby implementation. 113.Ev RSPEC 114and 115.Ev MODRUBY_BIN_RSPEC 116are the path to the spec (rspec 1) and 117rspec (rspec 2 and 3) binaries for the related ruby implementation. 118.Pp 119.Ev MODRUBY_RUBY_ADJ 120is a command that takes filename arguments and replaces 121the /usr/bin/env ruby shebang lines with 122.Ev RUBY . 123.Ev MODRUBY_ADJ_FILES 124is a list of filename patterns that will automatically have 125.Ev MODRUBY_RUBY_ADJ 126called on them during pre-configure. 127.Pp 128Creates a do-test target if 129.Ev MODRUBY_TEST 130is used and one is not already defined. 131.Ev MODRUBY_TEST 132can be set to ruby, rake, rspec, rspec3, or testrb to 133choose the appropriate binary to run the regress tests. 134.Ev MODRUBY_TEST_ENV 135can be used to set environment variables for the regress tests. 136.Ev MODRUBY_TEST_DIR 137can be used to set the directory in which to execute 138the regress tests, it defaults to 139.Ev WRKSRC . 140.Ev MODRUBY_TEST_TARGET 141sets the argument to the regress test program. 142.Pp 143Supports additional 144.Ev CONFIGURE_STYLE Ns s , 145and setting specific 146.Ev CONFIGURE_STYLE Ns s 147modifies some additional parameters: 148.Bl -bullet 149.It 150The "ruby gem" 151.Ev CONFIGURE_STYLE 152should be used for pure ruby gems without C extensions. 153This adds 154.Ev PKG_ARCH 155= * and adds ruby18, ruby20, ruby21, ruby22, ruby23 and jruby 156.Ev FLAVOR Ns s 157to the port, so the same port can build packages for multiple versions of ruby. 158.It 159The "ruby gem ext" 160.Ev CONFIGURE_STYLE 161should be used for ruby gems with C extensions. 162This adds 163.Ev MODRUBY_LIB_DEPENDS 164to 165.Ev LIB_DEPENDS 166and 167the appropriate libraries and 168.Ev MODRUBY_WANTLIB 169to 170.Ev WANTLIB . 171It also adds ruby18, ruby20, ruby21, ruby22, and ruby23 172.Ev FLAVOR Ns s 173to the port. 174If the C extension in the gem requires specific arguments to extconf.rb, set those 175via 176.Ev CONFIGURE_ARGS . 177.It 178The "ruby extconf" 179.Ev CONFIGURE_STYLE 180is similar to the "ruby gem ext" 181.Ev CONFIGURE_STYLE , 182except that it is used when the package is distributed with an extconf.rb file 183and not as a ruby gem. 184.El 185.Pp 186To ensure that dependencies use the same ruby implementation as the 187current port, all ruby gem/extconf dependencies specified in the port 188should use this format: 189.Pp 190.Dl category/ruby-foo,${MODRUBY_FLAVOR} 191.Pp 192Use of a ruby20, ruby21, ruby22, ruby23, or jruby 193.Ev FLAVOR 194causes the 195.Ev FULLPKGNAME 196to use the 197.Ev FLAVOR 198instead of ruby as the package prefix. 199Specifying 200.Ev MODRUBY_FLAVOR 201is necessary so that if a ruby x.y package is being built for the current 202port, it depends on the ruby x.y package of the 203dependencies. 204.Pp 205The ports system defaults to using ruby 2.2 if the version of ruby is not 206specified. 207If you want to specify a version for a gem/extconf port, use a specific 208.Ev FLAVOR , 209such as ruby18 to use ruby 1.8. 210If you want to specify a version for a non-gem/extconf port, set 211.Ev MODRUBY_REV 212for the version of ruby you want to use (1.8, 2.0, 2.1, 2.2, jruby). 213.Pp 214If you do not want the ports system to automatically set up 215.Ev FLAVOR Ns s 216when using a gem/extconf port, set 217.Ev MODRUBY_HANDLE_FLAVORS 218to No. 219Similarly, if you want the ports system to automatically set up 220.Ev FLAVOR Ns s 221when using a non-gem/extconf port, set 222.Ev MODRUBY_HANDLE_FLAVORS 223to Yes. 224When 225.Ev MODRUBY_HANDLE_FLAVORS 226is Yes, the ports system automatically adds the appropriate prefix to the 227.Ev FULLPKGNAME 228(e.g. ruby- for ruby 1.8, ruby22- for ruby 2.2). 229Additionally, it adds 230.Ev GEM_BIN_SUFFIX 231and 232.Ev GEM_MAN_SUFFIX 233to 234.Ev SUBST_VARS 235so that the PLISTs will work on multiple ruby versions. 236.Pp 237For ruby gem ports that can work on multiple ruby versions or implementations, 238any binary file entries in the PLIST should be appended with 239.Ev GEM_BIN_SUFFIX . 240This is because the gem binaries for multiple ruby versions are all 241installed to 242.Pa ${LOCALBASE}/bin , 243and the binaries all use a version-specific suffix. 244Any man pages and other files that would be installed to locations not 245specific to a ruby implementation (such as under 246.Pa ${LOCALBASE}/share ) , 247should use 248.Ev GEM_MAN_SUFFIX 249before the extension so the different 250.Ev FLAVOR Ns s 251do not conflict. 252.Pp 253make update-plist may remove 254.Ev GEM_BIN_SUFFIX 255and 256.Ev GEM_MAN_SUFFIX 257from the PLIST, or use them in inappropriate places where they shouldn't be 258used, so be careful when updating gem ports with binaries or man pages. 259Additionally, for gem ports with C extensions, make update-plist will add back 260files used by the specific 261.Ev FLAVOR 262you are using (such as files under the extension source directory), which may 263not exist for other 264.Ev FLAVOR Ns s , 265so always manually check the result of make update-plist and manually test that 266you can build the other 267.Ev FLAVOR Ns s 268before committing. 269Additionally, for gems with C extensions, make update-plist may add back the 270extension source files, which shouldn't be included in the files, so make sure 271to double check that all files added by make update-plist should be included 272in the package. 273.Sh SEE ALSO 274.Xr port-modules 5 275