1.\" $OpenBSD: ruby-module.5,v 1.26 2019/04/29 00:44:53 jeremy 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: April 29 2019 $ 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 ruby24, ruby25, ruby26, 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 ruby24, ruby25, and ruby26 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.El 178.Pp 179To ensure that dependencies use the same ruby implementation as the 180current port, all ruby gem dependencies specified in the port 181should use this format: 182.Pp 183.Dl category/ruby-foo,${MODRUBY_FLAVOR} 184.Pp 185The "ruby gem" and "ruby gem ext" 186.Ev CONFIGURE_STYLE Ns s 187cause the 188.Ev FULLPKGNAME 189to use the 190.Ev FLAVOR 191instead of ruby as the package prefix. 192Specifying 193.Ev MODRUBY_FLAVOR 194is necessary so that if a ruby x.y package is being built for the current 195port, it depends on the ruby x.y package of the 196dependencies. 197.Pp 198The ports system defaults to using ruby 2.6 if the version of ruby is not 199specified. 200If you want to specify a version for a gem port, use a specific 201.Ev FLAVOR , 202such as ruby25 to use ruby 2.5. 203If you want to specify a version for a non-gem port, set 204.Ev MODRUBY_REV 205for the version of ruby you want to use (2.4, 2.5, 2.6, jruby). 206.Pp 207If you do not want the ports system to automatically set up 208.Ev FLAVOR Ns s 209when using a gem port, set 210.Ev MODRUBY_HANDLE_FLAVORS 211to No. 212Similarly, if you want the ports system to automatically set up 213.Ev FLAVOR Ns s 214when using a non-gem port, set 215.Ev MODRUBY_HANDLE_FLAVORS 216to Yes. 217When 218.Ev MODRUBY_HANDLE_FLAVORS 219is Yes, the ports system automatically adds the appropriate prefix to the 220.Ev FULLPKGNAME 221(e.g. jruby- for jruby, ruby26- for ruby 2.6). 222Additionally, it adds 223.Ev GEM_BIN_SUFFIX 224and 225.Ev GEM_MAN_SUFFIX 226to 227.Ev SUBST_VARS 228so that the PLISTs will work on multiple ruby versions. 229.Pp 230For ruby gem ports that can work on multiple ruby versions or implementations, 231any binary file entries in the PLIST should be appended with 232.Ev GEM_BIN_SUFFIX . 233This is because the gem binaries for multiple ruby versions are all 234installed to 235.Pa ${LOCALBASE}/bin , 236and the binaries all use a version-specific suffix. 237Any man pages and other files that would be installed to locations not 238specific to a ruby implementation (such as under 239.Pa ${LOCALBASE}/share ) , 240should use 241.Ev GEM_MAN_SUFFIX 242before the extension so the different 243.Ev FLAVOR Ns s 244do not conflict. 245.Pp 246make update-plist may remove 247.Ev GEM_BIN_SUFFIX 248and 249.Ev GEM_MAN_SUFFIX 250from the PLIST, or use them in inappropriate places where they shouldn't be 251used, so be careful when updating gem ports with binaries or man pages. 252Additionally, for gem ports with C extensions, make update-plist will add back 253files used by the specific 254.Ev FLAVOR 255you are using (such as files under the extension source directory), which may 256not exist for other 257.Ev FLAVOR Ns s , 258so always manually check the result of make update-plist and manually test that 259you can build the other 260.Ev FLAVOR Ns s 261before committing. 262Additionally, for gems with C extensions, make update-plist may add back the 263extension source files, which shouldn't be included in the files, so make sure 264to double check that all files added by make update-plist should be included 265in the package. 266.Sh SEE ALSO 267.Xr port-modules 5 268