1.\" $OpenBSD: ruby-module.5,v 1.47 2024/06/20 22:43:16 jeremy Exp $ 2.\" 3.\" Copyright (c) 2011-2015, 2023 Jeremy Evans <jeremy@openbsd.org> 4.\" Copyright (c) 2008, 2011 Marc Espie <espie@openbsd.org> 5.\" 6.\" All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 18.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 19.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 20.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 21.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 22.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 23.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 24.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 25.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 26.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27.\" 28.Dd $Mdocdate: June 20 2024 $ 29.Dt RUBY-MODULE 5 30.Os 31.Sh NAME 32.Nm ruby-module 33.Nd lang/ruby port module 34.Sh DESCRIPTION 35This manual page documents the behavior of setting 36.Ev MODULES Ns Li =lang/ruby 37in the 38.Xr ports 7 39tree. 40.Pp 41The main usage of the lang/ruby module is to allow a single Ruby gem-based 42port to build packages for multiple versions of Ruby. 43The lang/ruby module also simplifies ports that depend on Ruby by 44automatically setting up the correct dependencies and defining commonly 45needed variables. 46.Pp 47To allow a single Ruby gem-based port to build packages for multiple versions 48of Ruby, set a specific 49.Ev CONFIGURE_STYLE , 50which modifies some additional parameters: 51.Bl -tag -width Ds 52.It Ev CONFIGURE_STYLE Ns = Ns Qq ruby gem 53For pure Ruby gems without C extensions. 54This adds 55.Ev PKG_ARCH 56= * to the port. 57.It Ev CONFIGURE_STYLE Ns = Ns Qq ruby gem ext 58For Ruby gems with C extensions. 59To pass additional arguments to 60.Sy gem Cm install 61when building the port, set 62those via 63.Ev CONFIGURE_ARGS . 64.El 65.Pp 66.Ev CONFIGURE_STYLE Ns = Ns Qq ruby gem 67and 68.Ev CONFIGURE_STYLE Ns = Ns Qq ruby gem ext 69both add ruby31, ruby32, and ruby33 70.Ev FLAVOR Ns s 71to the port. 72They also cause the 73.Ev FULLPKGNAME 74to use the 75.Ev FLAVOR Ns \- 76instead of ruby\- as the package prefix. 77.Pp 78The ports system defaults to using Ruby 3.3 if the version of Ruby is not 79specified. 80To specify a version for a gem port, use a specific 81.Ev FLAVOR , 82such as ruby32 to use Ruby 3.2. 83To specify the Ruby version to use for a non Ruby-gem port, set 84.Ev MODRUBY_REV 85to 3.1, 3.2, or 3.3. 86.Pp 87To ensure that dependencies use the same Ruby implementation as the 88current port, all Ruby gem dependencies specified in the port 89should use this format: 90.Pp 91.Dl category/ruby\-foo,${MODRUBY_FLAVOR} 92.Pp 93To prevent the ports system from automatically setting up 94.Ev FLAVOR Ns s 95in a gem port, set 96.Ev MODRUBY_HANDLE_FLAVORS 97to 98.Cm \&No . 99Similarly, to let the ports system automatically set up 100.Ev FLAVOR Ns s 101in a non-gem port, set 102.Ev MODRUBY_HANDLE_FLAVORS 103to 104.Cm Yes . 105When 106.Ev MODRUBY_HANDLE_FLAVORS 107is 108.Cm Yes , 109the ports system automatically adds the appropriate prefix to the 110.Ev FULLPKGNAME 111(e.g. ruby32\- for ruby 3.2, ruby33\- for ruby 3.3). 112.Pp 113For Ruby gem ports that can work on multiple Ruby versions, append 114.Ev GEM_BIN_SUFFIX 115to every binary file entry in the PLIST. 116This is because the gem binaries for multiple Ruby versions are all 117installed to 118.Pa ${LOCALBASE}/bin , 119and the binaries all use a version-specific suffix. 120Any man pages and other files that would be installed to locations not 121specific to a Ruby implementation (such as under 122.Pa ${LOCALBASE}/share ) , 123should use 124.Ev GEM_MAN_SUFFIX 125before the extension so the different 126.Ev FLAVOR Ns s 127do not conflict. 128.Pp 129make update\-plist may remove 130.Ev GEM_BIN_SUFFIX 131and 132.Ev GEM_MAN_SUFFIX 133from the PLIST, or use them in inappropriate places, so be careful when 134updating gem ports with binaries or man pages. 135Additionally, for gem ports with C extensions, make update\-plist will add back 136files used by the specific 137.Ev FLAVOR 138(such as files under the extension source directory), which may 139not exist for other 140.Ev FLAVOR Ns s , 141so always manually check the result of make update\-plist and manually test that 142all supported 143.Ev FLAVOR Ns s 144are buildable before committing. 145Additionally, for gems with C extensions, make update\-plist may add back the 146extension source files, which shouldn't be included in the files, so make sure 147to double check that all files added by make update\-plist should be included 148in the package. 149.Pp 150The lang/ruby module creates a do\-test target if 151.Ev MODRUBY_TEST 152is used and one is not already defined. 153.Pp 154The lang/ruby module appends to the following variables: 155.Bl -tag -width Ds 156.It Ev BUILD_DEPENDS 157Adds dependency on version of Ruby in use unless 158.Ev MODRUBY_BUILDDEP 159is set to 160.Cm \&No , 161or 162.Ev NO_BUILD 163is set to 164.Cm Yes . 165.It Ev CATEGORIES 166Adds the lang/ruby category. 167.It Ev RUN_DEPENDS 168Adds dependency on version of Ruby in use unless 169.Ev MODRUBY_RUNDEP 170is set to 171.Cm \&No . 172.It Ev TEST_DEPENDS 173Adds the rspec dependency if 174.Ev MODRUBY_TEST 175is set to rspec3. 176.It Ev SUBST_VARS 177Adds 178.Ev GEM_EXTENSIONS_DIR , 179.Ev MODRUBY_RELEXAMPLEDIR , 180.Ev MODRUBY_SITEARCHDIR , 181.Ev MODRUBY_SITEDIR , 182.Ev MODRUBY_LIBREV , 183.Ev MODRUBY_ARCH , 184.Ev GEM_LIB , 185.Ev GEM_BIN , 186and 187.Ev DISTNAME . 188.It Ev UPDATE_PLIST_ARGS 189Adds options so that 190.Ev MODRUBY_RELEXAMPLEDIR , 191.Ev MODRUBY_SITEARCHDIR , 192.Ev MODRUBY_SITEDIR , 193.Ev GEM_LIB , 194and 195.Ev GEM_BIN 196are only substituted at the start of paths. 197.El 198.Pp 199If using 200.Ev CONFIGURE_STYLE Ns = Ns Qq ruby gem 201or 202.Ev CONFIGURE_STYLE Ns = Ns Qq ruby gem ext , 203it also appends to the following variables: 204.Bl -tag -width Ds 205.It Ev EXTRACT_CASES 206Adds support for extracting .gem files. 207.El 208.Pp 209If using 210.Ev CONFIGURE_STYLE Ns = Ns Qq ruby gem ext , 211it also appends to the following variables: 212.Bl -tag -width Ds 213.It Ev WANTLIB 214Adds libraries used by Ruby. 215.It Ev LIB_DEPENDS 216Adds 217.Ev MODRUBY_LIB_DEPENDS . 218.It Ev PKG_ARGS 219Adds additional PLIST so that loading native extensions will not attempt to 220rebuild them at runtime. 221.It Ev SUBST_VARS 222Adds 223.Ev GEM_EXTENSIONS_DIR . 224.El 225.Pp 226If using 227.Ev MODRUBY_HANDLE_FLAVORS Ns = Ns Yes , 228it also appends to the following variables: 229.Bl -tag -width Ds 230.It Ev SUBST_VARS 231Adds 232.Ev GEM_BIN_SUFFIX 233and 234.Ev GEM_MAN_SUFFIX 235to 236.Ev SUBST_VARS 237so that the PLISTs work on multiple Ruby versions. 238.El 239.Pp 240The lang/ruby module sets the following variables: 241.Bl -tag -width Ds 242.It Ev GEM 243The path to the appropriate 244.Sy gem 245binary for the current Ruby version (/usr/local/bin/gem${MODRUBY_BINREV}). 246.It Ev GEM_BASE_BIN 247The absolute path where the 248.Sy gem 249program will install the executable 250files provided by the gem (if any) during the fake target. 251.It Ev GEM_BASE_LIB 252The absolute path where the 253.Sy gem 254program will install library files 255provided by the gem during the fake target. 256.It Ev GEM_BIN 257The relative path under 258.Ev PREFIX 259where the package installs the gem's executable files. 260.It Ev GEM_BIN_SUFFIX 261The suffix to use for the gem's executable files, so that separate 262.Ev FLAVOR Ns s 263of the port do not conflict. 264.It Ev GEM_EXTENSIONS_DIR 265The relative path under 266.Ev PREFIX 267where the package installs Ruby-version specific files for Ruby gems 268with C extensions. 269.It Ev GEM_FLAGS 270Option flags for 271.Sy gem Cm install 272when building the port. 273.It Ev GEM_LIB 274The relative path under 275.Ev PREFIX 276where Ruby gem files are stored for the Ruby version in use. 277.It Ev GEM_MAN_SUFFIX 278The suffix to use for the gem's manual pages, so that separate 279.Ev FLAVOR Ns s 280of the port do not conflict. 281.It Ev MODRUBY_ADJ_FILES 282A list of filename patterns that will automatically have 283.Ev MODRUBY_RUBY_ADJ 284called on them during pre\-configure. 285.It Ev MODRUBY_ARCH 286The platform-specific string used by Ruby for files installed 287into platform-specific directories. 288.It Ev MODRUBY_BINREV 289The same as 290.Ev MODRUBY_REV 291except without the dot 292.Pq Ql \&. , 293reflecting the suffix used by the 294programs for the Ruby version in use. 295.It Ev MODRUBY_BIN_RSPEC 296The path to the rspec (rspec 3) binaries for the Ruby 297version in use. 298.It Ev MODRUBY_BUILD_DEPENDS 299The same as 300.Ev MODRUBY_RUN_DEPENDS . 301It is designed to be used in 302.Ev BUILD_DEPENDS 303values for other ports depending on Ruby. 304.It Ev MODRUBY_BUILDDEP 305If Ruby does not need to be installed 306while building the package(s), set to 307.Cm \&No . 308The default is 309.Cm Yes . 310.It Ev MODRUBY_FLAVOR 311The FLAVOR to use for Ruby dependencies to ensure that 312they use the same version of Ruby as the current port. 313.It Ev MODRUBY_HANDLE_FLAVORS 314Determines whether the port allows building with multiple 315.Ev FLAVOR Ns s, 316with each 317.Ev FLAVOR 318supporting a separate Ruby version. 319.It Ev MODRUBY_LIBREV 320The same as 321.Ev MODRUBY_REV . 322.It Ev MODRUBY_LIB_DEPENDS 323The same as 324.Ev MODRUBY_RUN_DEPENDS . 325It is designed to be used in 326.Ev LIB_DEPENDS 327values for other ports depending on Ruby. 328.It Ev MODRUBY_PKG_PREFIX 329The prefix to use for packages built using the lang/ruby module, 330if the port support building with multiple Ruby versions. 331.It Ev MODRUBY_RELEXAMPLEDIR 332The relative path under 333.Ev PREFIX 334where the package installs example files for non-Ruby gem ports. 335.It Ev MODRUBY_REV 336Includes the major and minor versions of the version of Ruby in use, 337separated by a dot 338.Pq Ql \&. . 339The port can override the value to specify which Ruby version to use, 340if the port sets or defaults to 341.Ev MODRUBY_HANDLE_FLAVORS Ns =Yes . 342.It Ev MODRUBY_RUBY_ADJ 343A command that takes filename arguments and replaces 344the 345.Pa /usr/bin/env 346ruby shebang lines with 347.Ev RUBY . 348.It Ev MODRUBY_RUN_DEPENDS 349The port path for the Ruby version in use. 350It is designed to be used in 351.Ev RUN_DEPENDS 352values for other ports depending on Ruby. 353.It Ev MODRUBY_RUNDEP 354If the packages do not depend on Ruby at runtime, set to 355.Cm \&No . 356The default is 357.Cm Yes . 358.It Ev MODRUBY_SITEARCHDIR 359The relative path under 360.Ev PREFIX 361where the package installs platform-specific library files for non-Ruby gem 362ports. 363.It Ev MODRUBY_SITEDIR 364The relative path under 365.Ev PREFIX 366where the package installs non-platform-specific library files for non-Ruby 367gem ports. 368.It Ev MODRUBY_TEST 369Set to 370.Cm ruby , 371.Cm rake , 372.Cm rspec3 , 373or 374.Cm testrb 375to choose the appropriate program to run the regress tests, if the port 376includes tests. 377.It Ev MODRUBY_TEST_ENV 378Sets environment variables for the regress tests. 379.It Ev MODRUBY_TEST_TARGET 380Sets the argument to the regress test program. 381.It Ev MODRUBY_WANTLIB 382Includes the library-specs for the Ruby version in use. 383.It Ev RAKE 384The path to the 385.Sy rake 386program for the Ruby version in use (/usr/local/bin/rake${MODRUBY_BINREV}). 387.It Ev RUBY 388The path to the 389.Xr ruby 1 390program for the Ruby version in use (/usr/local/bin/ruby${MODRUBY_BINREV}). 391.El 392.Sh SEE ALSO 393.Xr bsd.port.mk 5 , 394.Xr port-modules 5 395