1.\" $OpenBSD: ruby-module.5,v 1.42 2023/09/12 17:21:05 schwarze 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: September 12 2023 $ 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 MODULES=lang/ruby 36in the 37.Xr ports 7 38tree. 39.Pp 40Sets 41.Ev GEM , 42.Ev GEM_BASE_BIN , 43.Ev GEM_BASE_LIB , 44.Ev GEM_BIN , 45.Ev GEM_BIN_SUFFIX , 46.Ev GEM_EXTENSIONS_DIR , 47.Ev GEM_FLAGS , 48.Ev GEM_LIB , 49.Ev GEM_MAN_SUFFIX , 50.Ev MODRUBY_ADJ_FILES , 51.Ev MODRUBY_ARCH , 52.Ev MODRUBY_BINREV , 53.Ev MODRUBY_BIN_RSPEC , 54.Ev MODRUBY_BUILD_DEPENDS , 55.Ev MODRUBY_BUILDDEP , 56.Ev MODRUBY_FLAVOR , 57.Ev MODRUBY_HANDLE_FLAVORS , 58.Ev MODRUBY_LIBREV , 59.Ev MODRUBY_LIB_DEPENDS , 60.Ev MODRUBY_PKG_PREFIX , 61.Ev MODRUBY_RELEXAMPLEDIR , 62.Ev MODRUBY_REV , 63.Ev MODRUBY_RUBY_ADJ , 64.Ev MODRUBY_RUN_DEPENDS , 65.Ev MODRUBY_RUNDEP , 66.Ev MODRUBY_SITEARCHDIR , 67.Ev MODRUBY_SITEDIR , 68.Ev MODRUBY_TEST , 69.Ev MODRUBY_TEST_ENV , 70.Ev MODRUBY_TEST_TARGET , 71.Ev MODRUBY_WANTLIB , 72.Ev RAKE , 73and 74.Ev RUBY . 75.Pp 76Appends to 77.Ev CATEGORIES 78and 79.Ev SUBST_VARS . 80Appends to 81.Ev BUILD_DEPENDS 82unless 83.Ev MODRUBY_BUILDDEP 84is set to No or 85.Ev NO_BUILD 86is set to Yes. 87Appends to 88.Ev RUN_DEPENDS 89unless 90.Ev MODRUBY_RUNDEP 91is set to No. 92.Pp 93.Ev MODRUBY_RSPEC3_DEPENDS 94is set to the dependency line for the rspec 3 port for the version of ruby in 95use. 96.Ev RUBY , 97and 98.Ev RAKE 99are the path to the ruby and rake 100binaries for the related ruby implementation. 101.Ev MODRUBY_BIN_RSPEC 102is the path to the rspec (rspec 3) binaries for the related ruby 103implementation. 104.Pp 105.Ev MODRUBY_RUBY_ADJ 106is a command that takes filename arguments and replaces 107the /usr/bin/env ruby shebang lines with 108.Ev RUBY . 109.Ev MODRUBY_ADJ_FILES 110is a list of filename patterns that will automatically have 111.Ev MODRUBY_RUBY_ADJ 112called on them during pre-configure. 113.Pp 114Creates a do-test target if 115.Ev MODRUBY_TEST 116is used and one is not already defined. 117.Ev MODRUBY_TEST 118can be set to ruby, rake, rspec3, or testrb to 119choose the appropriate binary to run the regress tests. 120.Ev MODRUBY_TEST_ENV 121can be used to set environment variables for the regress tests. 122.Ev MODRUBY_TEST_TARGET 123sets the argument to the regress test program. 124.Pp 125Supports additional 126.Ev CONFIGURE_STYLE Ns s , 127and setting specific 128.Ev CONFIGURE_STYLE Ns s 129modifies some additional parameters: 130.Bl -bullet 131.It 132The "ruby gem" 133.Ev CONFIGURE_STYLE 134should be used for pure ruby gems without C extensions. 135This adds 136.Ev PKG_ARCH 137= * and adds ruby30, ruby31, and ruby32 138.Ev FLAVOR Ns s 139to the port, so the same port can build packages for multiple versions of ruby. 140.It 141The "ruby gem ext" 142.Ev CONFIGURE_STYLE 143should be used for ruby gems with C extensions. 144This adds 145.Ev MODRUBY_LIB_DEPENDS 146to 147.Ev LIB_DEPENDS 148and 149the appropriate libraries and 150.Ev MODRUBY_WANTLIB 151to 152.Ev WANTLIB . 153It also adds ruby30, ruby31, and ruby32 154.Ev FLAVOR Ns s 155to the port. 156If the C extension in the gem requires specific arguments to extconf.rb, 157set those via 158.Ev CONFIGURE_ARGS . 159.El 160.Pp 161To ensure that dependencies use the same ruby implementation as the 162current port, all ruby gem dependencies specified in the port 163should use this format: 164.Pp 165.Dl category/ruby-foo,${MODRUBY_FLAVOR} 166.Pp 167The "ruby gem" and "ruby gem ext" 168.Ev CONFIGURE_STYLE Ns s 169cause the 170.Ev FULLPKGNAME 171to use the 172.Ev FLAVOR 173instead of ruby as the package prefix. 174Specifying 175.Ev MODRUBY_FLAVOR 176is necessary so that if a ruby x.y package is being built for the current 177port, it depends on the ruby x.y package of the dependencies. 178.Pp 179The ports system defaults to using ruby 3.2 if the version of ruby is not 180specified. 181If you want to specify a version for a gem port, use a specific 182.Ev FLAVOR , 183such as ruby31 to use ruby 3.1. 184If you want to specify a version for a non-gem port, set 185.Ev MODRUBY_REV 186for the version of ruby you want to use (3.0, 3.1, 3.2). 187.Pp 188If you do not want the ports system to automatically set up 189.Ev FLAVOR Ns s 190when using a gem port, set 191.Ev MODRUBY_HANDLE_FLAVORS 192to No. 193Similarly, if you want the ports system to automatically set up 194.Ev FLAVOR Ns s 195when using a non-gem port, set 196.Ev MODRUBY_HANDLE_FLAVORS 197to Yes. 198When 199.Ev MODRUBY_HANDLE_FLAVORS 200is Yes, the ports system automatically adds the appropriate prefix to the 201.Ev FULLPKGNAME 202(e.g. ruby31- for ruby 3.1, ruby32- for ruby 3.2). 203Additionally, it adds 204.Ev GEM_BIN_SUFFIX 205and 206.Ev GEM_MAN_SUFFIX 207to 208.Ev SUBST_VARS 209so that the PLISTs will work on multiple ruby versions. 210.Pp 211For ruby gem ports that can work on multiple ruby versions or implementations, 212any binary file entries in the PLIST should be appended with 213.Ev GEM_BIN_SUFFIX . 214This is because the gem binaries for multiple ruby versions are all 215installed to 216.Pa ${LOCALBASE}/bin , 217and the binaries all use a version-specific suffix. 218Any man pages and other files that would be installed to locations not 219specific to a ruby implementation (such as under 220.Pa ${LOCALBASE}/share ) , 221should use 222.Ev GEM_MAN_SUFFIX 223before the extension so the different 224.Ev FLAVOR Ns s 225do not conflict. 226.Pp 227make update-plist may remove 228.Ev GEM_BIN_SUFFIX 229and 230.Ev GEM_MAN_SUFFIX 231from the PLIST, or use them in inappropriate places where they shouldn't be 232used, so be careful when updating gem ports with binaries or man pages. 233Additionally, for gem ports with C extensions, make update-plist will add back 234files used by the specific 235.Ev FLAVOR 236you are using (such as files under the extension source directory), which may 237not exist for other 238.Ev FLAVOR Ns s , 239so always manually check the result of make update-plist and manually test that 240you can build the other 241.Ev FLAVOR Ns s 242before committing. 243Additionally, for gems with C extensions, make update-plist may add back the 244extension source files, which shouldn't be included in the files, so make sure 245to double check that all files added by make update-plist should be included 246in the package. 247.Sh SEE ALSO 248.Xr port-modules 5 249