"Fossies" - the Fresh Open Source Software Archive

Member "ruby-2.6.5/man/gemfile.5.ronn" (1 Oct 2019, 20147 Bytes) of package /linux/misc/ruby-2.6.5.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 Gemfile(5) -- A format for describing gem dependencies for Ruby programs
    2 ========================================================================
    3 
    4 ## SYNOPSIS
    5 
    6 A `Gemfile` describes the gem dependencies required to execute associated
    7 Ruby code.
    8 
    9 Place the `Gemfile` in the root of the directory containing the associated
   10 code. For instance, in a Rails application, place the `Gemfile` in the same
   11 directory as the `Rakefile`.
   12 
   13 ## SYNTAX
   14 
   15 A `Gemfile` is evaluated as Ruby code, in a context which makes available
   16 a number of methods used to describe the gem requirements.
   17 
   18 ## GLOBAL SOURCES
   19 
   20 At the top of the `Gemfile`, add a line for the `Rubygems` source that contains
   21 the gems listed in the `Gemfile`.
   22 
   23     source "https://rubygems.org"
   24 
   25 It is possible, but not recommended as of Bundler 1.7, to add multiple global
   26 `source` lines. Each of these `source`s `MUST` be a valid Rubygems repository.
   27 
   28 Sources are checked for gems following the heuristics described in
   29 [SOURCE PRIORITY][]. If a gem is found in more than one global source, Bundler
   30 will print a warning after installing the gem indicating which source was used,
   31 and listing the other sources where the gem is available. A specific source can
   32 be selected for gems that need to use a non-standard repository, suppressing
   33 this warning, by using the [`:source` option](#SOURCE) or a
   34 [`source` block](#BLOCK-FORM-OF-SOURCE-GIT-PATH-GROUP-and-PLATFORMS).
   35 
   36 ### CREDENTIALS
   37 
   38 Some gem sources require a username and password. Use [bundle config(1)](bundle-config.1.html) to set
   39 the username and password for any of the sources that need it. The command must
   40 be run once on each computer that will install the Gemfile, but this keeps the
   41 credentials from being stored in plain text in version control.
   42 
   43     bundle config gems.example.com user:password
   44 
   45 For some sources, like a company Gemfury account, it may be easier to
   46 include the credentials in the Gemfile as part of the source URL.
   47 
   48     source "https://user:password@gems.example.com"
   49 
   50 Credentials in the source URL will take precedence over credentials set using
   51 `config`.
   52 
   53 ## RUBY
   54 
   55 If your application requires a specific Ruby version or engine, specify your
   56 requirements using the `ruby` method, with the following arguments.
   57 All parameters are `OPTIONAL` unless otherwise specified.
   58 
   59 ### VERSION (required)
   60 
   61 The version of Ruby that your application requires. If your application
   62 requires an alternate Ruby engine, such as JRuby, Rubinius or TruffleRuby, this
   63 should be the Ruby version that the engine is compatible with.
   64 
   65     ruby "1.9.3"
   66 
   67 ### ENGINE
   68 
   69 Each application _may_ specify a Ruby engine. If an engine is specified, an
   70 engine version _must_ also be specified.
   71 
   72 What exactly is an Engine?
   73   - A Ruby engine is an implementation of the Ruby language.
   74 
   75   - For background: the reference or original implementation of the Ruby
   76     programming language is called
   77     [Matz's Ruby Interpreter](https://en.wikipedia.org/wiki/Ruby_MRI), or  MRI
   78     for short. This is named after Ruby creator Yukihiro Matsumoto,
   79     also known as Matz. MRI is also known as CRuby, because it is written in C.
   80     MRI is the most widely used Ruby engine.
   81 
   82   - [Other implementations](https://www.ruby-lang.org/en/about/) of Ruby exist.
   83     Some of the more well-known implementations include
   84     [Rubinius](https://rubinius.com/), and [JRuby](http://jruby.org/).
   85     Rubinius is an alternative implementation of Ruby written in Ruby.
   86     JRuby is an implementation of Ruby on the JVM, short for Java Virtual Machine.
   87 
   88 ### ENGINE VERSION
   89 
   90 Each application _may_ specify a Ruby engine version. If an engine version is
   91 specified, an engine _must_ also be specified. If the engine is "ruby" the
   92 engine version specified _must_ match the Ruby version.
   93 
   94     ruby "1.8.7", :engine => "jruby", :engine_version => "1.6.7"
   95 
   96 ### PATCHLEVEL
   97 
   98 Each application _may_ specify a Ruby patchlevel.
   99 
  100     ruby "2.0.0", :patchlevel => "247"
  101 
  102 ## GEMS
  103 
  104 Specify gem requirements using the `gem` method, with the following arguments.
  105 All parameters are `OPTIONAL` unless otherwise specified.
  106 
  107 ### NAME (required)
  108 
  109 For each gem requirement, list a single _gem_ line.
  110 
  111     gem "nokogiri"
  112 
  113 ### VERSION
  114 
  115 Each _gem_ `MAY` have one or more version specifiers.
  116 
  117     gem "nokogiri", ">= 1.4.2"
  118     gem "RedCloth", ">= 4.1.0", "< 4.2.0"
  119 
  120 ### REQUIRE AS
  121 
  122 Each _gem_ `MAY` specify files that should be used when autorequiring via
  123 `Bundler.require`. You may pass an array with multiple files or `true` if file
  124 you want `required` has same name as _gem_ or `false` to
  125 prevent any file from being autorequired.
  126 
  127     gem "redis", :require => ["redis/connection/hiredis", "redis"]
  128     gem "webmock", :require => false
  129     gem "debugger", :require => true
  130 
  131 The argument defaults to the name of the gem. For example, these are identical:
  132 
  133     gem "nokogiri"
  134     gem "nokogiri", :require => "nokogiri"
  135     gem "nokogiri", :require => true
  136 
  137 ### GROUPS
  138 
  139 Each _gem_ `MAY` specify membership in one or more groups. Any _gem_ that does
  140 not specify membership in any group is placed in the `default` group.
  141 
  142     gem "rspec", :group => :test
  143     gem "wirble", :groups => [:development, :test]
  144 
  145 The Bundler runtime allows its two main methods, `Bundler.setup` and
  146 `Bundler.require`, to limit their impact to particular groups.
  147 
  148     # setup adds gems to Ruby's load path
  149     Bundler.setup                    # defaults to all groups
  150     require "bundler/setup"          # same as Bundler.setup
  151     Bundler.setup(:default)          # only set up the _default_ group
  152     Bundler.setup(:test)             # only set up the _test_ group (but `not` _default_)
  153     Bundler.setup(:default, :test)   # set up the _default_ and _test_ groups, but no others
  154 
  155     # require requires all of the gems in the specified groups
  156     Bundler.require                  # defaults to the _default_ group
  157     Bundler.require(:default)        # identical
  158     Bundler.require(:default, :test) # requires the _default_ and _test_ groups
  159     Bundler.require(:test)           # requires the _test_ group
  160 
  161 The Bundler CLI allows you to specify a list of groups whose gems `bundle install` should
  162 not install with the `--without` option. To specify multiple groups to ignore, specify a
  163 list of groups separated by spaces.
  164 
  165     bundle install --without test
  166     bundle install --without development test
  167 
  168 After running `bundle install --without test`, bundler will remember that you excluded
  169 the test group in the last installation. The next time you run `bundle install`,
  170 without any `--without option`, bundler will recall it.
  171 
  172 Also, calling `Bundler.setup` with no parameters, or calling `require "bundler/setup"`
  173 will setup all groups except for the ones you excluded via `--without` (since they
  174 are not available).
  175 
  176 Note that on `bundle install`, bundler downloads and evaluates all gems, in order to
  177 create a single canonical list of all of the required gems and their dependencies.
  178 This means that you cannot list different versions of the same gems in different
  179 groups. For more details, see [Understanding Bundler](http://bundler.io/rationale.html).
  180 
  181 ### PLATFORMS
  182 
  183 If a gem should only be used in a particular platform or set of platforms, you can
  184 specify them. Platforms are essentially identical to groups, except that you do not
  185 need to use the `--without` install-time flag to exclude groups of gems for other
  186 platforms.
  187 
  188 There are a number of `Gemfile` platforms:
  189 
  190   * `ruby`:
  191     C Ruby (MRI), Rubinius or TruffleRuby, but `NOT` Windows
  192   * `mri`:
  193     Same as _ruby_, but only C Ruby (MRI)
  194   * `mingw`:
  195     Windows 32 bit 'mingw32' platform (aka RubyInstaller)
  196   * `x64_mingw`:
  197     Windows 64 bit 'mingw32' platform (aka RubyInstaller x64)
  198   * `rbx`:
  199     Rubinius
  200   * `jruby`:
  201     JRuby
  202   * `truffleruby`:
  203     TruffleRuby
  204   * `mswin`:
  205     Windows
  206 
  207 You can restrict further by platform and version for all platforms *except* for
  208 `rbx`, `jruby`, `truffleruby` and `mswin`.
  209 
  210 To specify a version in addition to a platform, append the version number without
  211 the delimiter to the platform. For example, to specify that a gem should only be
  212 used on platforms with Ruby 2.3, use:
  213 
  214     ruby_23
  215 
  216 The full list of platforms and supported versions includes:
  217 
  218   * `ruby`:
  219     1.8, 1.9, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5
  220   * `mri`:
  221     1.8, 1.9, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5
  222   * `mingw`:
  223     1.8, 1.9, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5
  224   * `x64_mingw`:
  225     2.0, 2.1, 2.2, 2.3, 2.4, 2.5
  226 
  227 As with groups, you can specify one or more platforms:
  228 
  229     gem "weakling",   :platforms => :jruby
  230     gem "ruby-debug", :platforms => :mri_18
  231     gem "nokogiri",   :platforms => [:mri_18, :jruby]
  232 
  233 All operations involving groups ([`bundle install`](bundle-install.1.html), `Bundler.setup`,
  234 `Bundler.require`) behave exactly the same as if any groups not
  235 matching the current platform were explicitly excluded.
  236 
  237 ### SOURCE
  238 
  239 You can select an alternate Rubygems repository for a gem using the ':source'
  240 option.
  241 
  242     gem "some_internal_gem", :source => "https://gems.example.com"
  243 
  244 This forces the gem to be loaded from this source and ignores any global sources
  245 declared at the top level of the file. If the gem does not exist in this source,
  246 it will not be installed.
  247 
  248 Bundler will search for child dependencies of this gem by first looking in the
  249 source selected for the parent, but if they are not found there, it will fall
  250 back on global sources using the ordering described in [SOURCE PRIORITY][].
  251 
  252 Selecting a specific source repository this way also suppresses the ambiguous
  253 gem warning described above in
  254 [GLOBAL SOURCES (#source)](#GLOBAL-SOURCES).
  255 
  256 Using the `:source` option for an individual gem will also make that source
  257 available as a possible global source for any other gems which do not specify
  258 explicit sources. Thus, when adding gems with explicit sources, it is
  259 recommended that you also ensure all other gems in the Gemfile are using
  260 explicit sources.
  261 
  262 ### GIT
  263 
  264 If necessary, you can specify that a gem is located at a particular
  265 git repository using the `:git` parameter. The repository can be accessed via
  266 several protocols:
  267 
  268   * `HTTP(S)`:
  269     gem "rails", :git => "https://github.com/rails/rails.git"
  270   * `SSH`:
  271     gem "rails", :git => "git@github.com:rails/rails.git"
  272   * `git`:
  273     gem "rails", :git => "git://github.com/rails/rails.git"
  274 
  275 If using SSH, the user that you use to run `bundle install` `MUST` have the
  276 appropriate keys available in their `$HOME/.ssh`.
  277 
  278 `NOTE`: `http://` and `git://` URLs should be avoided if at all possible. These
  279 protocols are unauthenticated, so a man-in-the-middle attacker can deliver
  280 malicious code and compromise your system. HTTPS and SSH are strongly
  281 preferred.
  282 
  283 The `group`, `platforms`, and `require` options are available and behave
  284 exactly the same as they would for a normal gem.
  285 
  286 A git repository `SHOULD` have at least one file, at the root of the
  287 directory containing the gem, with the extension `.gemspec`. This file
  288 `MUST` contain a valid gem specification, as expected by the `gem build`
  289 command.
  290 
  291 If a git repository does not have a `.gemspec`, bundler will attempt to
  292 create one, but it will not contain any dependencies, executables, or
  293 C extension compilation instructions. As a result, it may fail to properly
  294 integrate into your application.
  295 
  296 If a git repository does have a `.gemspec` for the gem you attached it
  297 to, a version specifier, if provided, means that the git repository is
  298 only valid if the `.gemspec` specifies a version matching the version
  299 specifier. If not, bundler will print a warning.
  300 
  301     gem "rails", "2.3.8", :git => "https://github.com/rails/rails.git"
  302     # bundle install will fail, because the .gemspec in the rails
  303     # repository's master branch specifies version 3.0.0
  304 
  305 If a git repository does `not` have a `.gemspec` for the gem you attached
  306 it to, a version specifier `MUST` be provided. Bundler will use this
  307 version in the simple `.gemspec` it creates.
  308 
  309 Git repositories support a number of additional options.
  310 
  311   * `branch`, `tag`, and `ref`:
  312     You `MUST` only specify at most one of these options. The default
  313     is `:branch => "master"`
  314   * For example:
  315 
  316       git "https://github.com/rails/rails.git", :branch => "5-0-stable" do
  317 
  318       git "https://github.com/rails/rails.git", :tag => "v5.0.0" do
  319 
  320       git "https://github.com/rails/rails.git", :ref => "4aded" do
  321 
  322   * `submodules`:
  323     For reference, a [git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
  324     lets you have another git repository within a subfolder of your repository.
  325     Specify `:submodules => true` to cause bundler to expand any
  326     submodules included in the git repository
  327 
  328 If a git repository contains multiple `.gemspecs`, each `.gemspec`
  329 represents a gem located at the same place in the file system as
  330 the `.gemspec`.
  331 
  332     |~rails                   [git root]
  333     | |-rails.gemspec         [rails gem located here]
  334     |~actionpack
  335     | |-actionpack.gemspec    [actionpack gem located here]
  336     |~activesupport
  337     | |-activesupport.gemspec [activesupport gem located here]
  338     |...
  339 
  340 To install a gem located in a git repository, bundler changes to
  341 the directory containing the gemspec, runs `gem build name.gemspec`
  342 and then installs the resulting gem. The `gem build` command,
  343 which comes standard with Rubygems, evaluates the `.gemspec` in
  344 the context of the directory in which it is located.
  345 
  346 ### GIT SOURCE
  347 
  348 A custom git source can be defined via the `git_source` method. Provide the source's name
  349 as an argument, and a block which receives a single argument and interpolates it into a
  350 string to return the full repo address:
  351 
  352     git_source(:stash){ |repo_name| "https://stash.corp.acme.pl/#{repo_name}.git" }
  353     gem 'rails', :stash => 'forks/rails'
  354 
  355 In addition, if you wish to choose a specific branch:
  356 
  357     gem "rails", :stash => "forks/rails", :branch => "branch_name"
  358 
  359 ### GITHUB
  360 
  361 `NOTE`: This shorthand should be avoided until Bundler 2.0, since it
  362 currently expands to an insecure `git://` URL. This allows a
  363 man-in-the-middle attacker to compromise your system.
  364 
  365 If the git repository you want to use is hosted on GitHub and is public, you can use the
  366 :github shorthand to specify the github username and repository name (without the
  367 trailing ".git"), separated by a slash. If both the username and repository name are the
  368 same, you can omit one.
  369 
  370     gem "rails", :github => "rails/rails"
  371     gem "rails", :github => "rails"
  372 
  373 Are both equivalent to
  374 
  375     gem "rails", :git => "git://github.com/rails/rails.git"
  376 
  377 Since the `github` method is a specialization of `git_source`, it accepts a `:branch` named argument.
  378 
  379 ### GIST
  380 
  381 If the git repository you want to use is hosted as a Github Gist and is public, you can use
  382 the :gist shorthand to specify the gist identifier (without the trailing ".git").
  383 
  384     gem "the_hatch", :gist => "4815162342"
  385 
  386 Is equivalent to:
  387 
  388     gem "the_hatch", :git => "https://gist.github.com/4815162342.git"
  389 
  390 Since the `gist` method is a specialization of `git_source`, it accepts a `:branch` named argument.
  391 
  392 ### BITBUCKET
  393 
  394 If the git repository you want to use is hosted on Bitbucket and is public, you can use the
  395 :bitbucket shorthand to specify the bitbucket username and repository name (without the
  396 trailing ".git"), separated by a slash. If both the username and repository name are the
  397 same, you can omit one.
  398 
  399     gem "rails", :bitbucket => "rails/rails"
  400     gem "rails", :bitbucket => "rails"
  401 
  402 Are both equivalent to
  403 
  404     gem "rails", :git => "https://rails@bitbucket.org/rails/rails.git"
  405 
  406 Since the `bitbucket` method is a specialization of `git_source`, it accepts a `:branch` named argument.
  407 
  408 ### PATH
  409 
  410 You can specify that a gem is located in a particular location
  411 on the file system. Relative paths are resolved relative to the
  412 directory containing the `Gemfile`.
  413 
  414 Similar to the semantics of the `:git` option, the `:path`
  415 option requires that the directory in question either contains
  416 a `.gemspec` for the gem, or that you specify an explicit
  417 version that bundler should use.
  418 
  419 Unlike `:git`, bundler does not compile C extensions for
  420 gems specified as paths.
  421 
  422     gem "rails", :path => "vendor/rails"
  423 
  424 If you would like to use multiple local gems directly from the filesystem, you can set a global `path` option to the path containing the gem's files. This will automatically load gemspec files from subdirectories.
  425 
  426     path 'components' do
  427       gem 'admin_ui'
  428       gem 'public_ui'
  429     end
  430 
  431 ## BLOCK FORM OF SOURCE, GIT, PATH, GROUP and PLATFORMS
  432 
  433 The `:source`, `:git`, `:path`, `:group`, and `:platforms` options may be
  434 applied to a group of gems by using block form.
  435 
  436     source "https://gems.example.com" do
  437       gem "some_internal_gem"
  438       gem "another_internal_gem"
  439     end
  440 
  441     git "https://github.com/rails/rails.git" do
  442       gem "activesupport"
  443       gem "actionpack"
  444     end
  445 
  446     platforms :ruby do
  447       gem "ruby-debug"
  448       gem "sqlite3"
  449     end
  450 
  451     group :development, :optional => true do
  452       gem "wirble"
  453       gem "faker"
  454     end
  455 
  456 In the case of the group block form the :optional option can be given
  457 to prevent a group from being installed unless listed in the `--with`
  458 option given to the `bundle install` command.
  459 
  460 In the case of the `git` block form, the `:ref`, `:branch`, `:tag`,
  461 and `:submodules` options may be passed to the `git` method, and
  462 all gems in the block will inherit those options.
  463 
  464 The presence of a `source` block in a Gemfile also makes that source
  465 available as a possible global source for any other gems which do not specify
  466 explicit sources. Thus, when defining source blocks, it is
  467 recommended that you also ensure all other gems in the Gemfile are using
  468 explicit sources, either via source blocks or `:source` directives on
  469 individual gems.
  470 
  471 ## INSTALL_IF
  472 
  473 The `install_if` method allows gems to be installed based on a proc or lambda.
  474 This is especially useful for optional gems that can only be used if certain
  475 software is installed or some other conditions are met.
  476 
  477     install_if -> { RUBY_PLATFORM =~ /darwin/ } do
  478       gem "pasteboard"
  479     end
  480 
  481 ## GEMSPEC
  482 
  483 The [`.gemspec`](http://guides.rubygems.org/specification-reference/) file is where
  484  you provide metadata about your gem to Rubygems. Some required Gemspec
  485  attributes include the name, description, and homepage of your gem. This is
  486  also where you specify the dependencies your gem needs to run.
  487 
  488 If you wish to use Bundler to help install dependencies for a gem while it is
  489 being developed, use the `gemspec` method to pull in the dependencies listed in
  490 the `.gemspec` file.
  491 
  492 The `gemspec` method adds any runtime dependencies as gem requirements in the
  493 default group. It also adds development dependencies as gem requirements in the
  494 `development` group. Finally, it adds a gem requirement on your project (`:path
  495 => '.'`). In conjunction with `Bundler.setup`, this allows you to require project
  496 files in your test code as you would if the project were installed as a gem; you
  497 need not manipulate the load path manually or require project files via relative
  498 paths.
  499 
  500 The `gemspec` method supports optional `:path`, `:glob`, `:name`, and `:development_group`
  501 options, which control where bundler looks for the `.gemspec`, the glob it uses to look
  502 for the gemspec (defaults to: "{,*,*/*}.gemspec"), what named `.gemspec` it uses
  503 (if more than one is present), and which group development dependencies are included in.
  504 
  505 When a `gemspec` dependency encounters version conflicts during resolution, the
  506 local version under development will always be selected -- even if there are
  507 remote versions that better match other requirements for the `gemspec` gem.
  508 
  509 ## SOURCE PRIORITY
  510 
  511 When attempting to locate a gem to satisfy a gem requirement,
  512 bundler uses the following priority order:
  513 
  514   1. The source explicitly attached to the gem (using `:source`, `:path`, or
  515      `:git`)
  516   2. For implicit gems (dependencies of explicit gems), any source, git, or path
  517      repository declared on the parent. This results in bundler prioritizing the
  518      ActiveSupport gem from the Rails git repository over ones from
  519      `rubygems.org`
  520   3. The sources specified via global `source` lines, searching each source in
  521      your `Gemfile` from last added to first added.