diff options
Diffstat (limited to 'man/gemfile.5.txt')
-rw-r--r-- | man/gemfile.5.txt | 653 |
1 files changed, 653 insertions, 0 deletions
diff --git a/man/gemfile.5.txt b/man/gemfile.5.txt new file mode 100644 index 0000000000..0ff77795ad --- /dev/null +++ b/man/gemfile.5.txt @@ -0,0 +1,653 @@ +GEMFILE(5) GEMFILE(5) + + + +1mNAME0m + 1mGemfile 22m- A format for describing gem dependencies for Ruby programs + +1mSYNOPSIS0m + A 1mGemfile 22mdescribes the gem dependencies required to execute associated + Ruby code. + + Place the 1mGemfile 22min the root of the directory containing the associ- + ated code. For instance, in a Rails application, place the 1mGemfile 22min + the same directory as the 1mRakefile22m. + +1mSYNTAX0m + A 1mGemfile 22mis evaluated as Ruby code, in a context which makes available + a number of methods used to describe the gem requirements. + +1mGLOBAL SOURCES0m + At the top of the 1mGemfile22m, add a line for the 1mRubygems 22msource that con- + tains the gems listed in the 1mGemfile22m. + + + + source "https://rubygems.org" + + + + It is possible, but not recommended as of Bundler 1.7, to add multiple + global 1msource 22mlines. Each of these 1msource22ms 1mMUST 22mbe a valid Rubygems + repository. + + Sources are checked for gems following the heuristics described in + 4mSOURCE24m 4mPRIORITY24m. If a gem is found in more than one global source, + Bundler will print a warning after installing the gem indicating which + source was used, and listing the other sources where the gem is avail- + able. A specific source can be selected for gems that need to use a + non-standard repository, suppressing this warning, by using the 1m:source0m + option or a 1msource 22mblock. + + 1mCREDENTIALS0m + Some gem sources require a username and password. Use bundle config(1) + 4mbundle-config.1.html24m to set the username and password for any of the + sources that need it. The command must be run once on each computer + that will install the Gemfile, but this keeps the credentials from + being stored in plain text in version control. + + + + bundle config gems.example.com user:password + + + + For some sources, like a company Gemfury account, it may be easier to + include the credentials in the Gemfile as part of the source URL. + + + + source "https://user:password@gems.example.com" + + + + Credentials in the source URL will take precedence over credentials set + using 1mconfig22m. + +1mRUBY0m + If your application requires a specific Ruby version or engine, specify + your requirements using the 1mruby 22mmethod, with the following arguments. + All parameters are 1mOPTIONAL 22munless otherwise specified. + + 1mVERSION (required)0m + The version of Ruby that your application requires. If your application + requires an alternate Ruby engine, such as JRuby, Rubinius or Truf- + fleRuby, this should be the Ruby version that the engine is compatible + with. + + + + ruby "1.9.3" + + + + 1mENGINE0m + Each application 4mmay24m specify a Ruby engine. If an engine is specified, + an engine version 4mmust24m also be specified. + + What exactly is an Engine? - A Ruby engine is an implementation of the + Ruby language. + + o For background: the reference or original implementation of the + Ruby programming language is called Matz's Ruby Interpreter + 4mhttps://en.wikipedia.org/wiki/Ruby_MRI24m, or MRI for short. This is + named after Ruby creator Yukihiro Matsumoto, also known as Matz. + MRI is also known as CRuby, because it is written in C. MRI is the + most widely used Ruby engine. + + o Other implementations 4mhttps://www.ruby-lang.org/en/about/24m of Ruby + exist. Some of the more well-known implementations include Rubinius + 4mhttps://rubinius.com/24m, and JRuby 4mhttp://jruby.org/24m. Rubinius is an + alternative implementation of Ruby written in Ruby. JRuby is an + implementation of Ruby on the JVM, short for Java Virtual Machine. + + + + 1mENGINE VERSION0m + Each application 4mmay24m specify a Ruby engine version. If an engine ver- + sion is specified, an engine 4mmust24m also be specified. If the engine is + "ruby" the engine version specified 4mmust24m match the Ruby version. + + + + ruby "1.8.7", :engine => "jruby", :engine_version => "1.6.7" + + + + 1mPATCHLEVEL0m + Each application 4mmay24m specify a Ruby patchlevel. + + + + ruby "2.0.0", :patchlevel => "247" + + + +1mGEMS0m + Specify gem requirements using the 1mgem 22mmethod, with the following argu- + ments. All parameters are 1mOPTIONAL 22munless otherwise specified. + + 1mNAME (required)0m + For each gem requirement, list a single 4mgem24m line. + + + + gem "nokogiri" + + + + 1mVERSION0m + Each 4mgem24m 1mMAY 22mhave one or more version specifiers. + + + + gem "nokogiri", ">= 1.4.2" + gem "RedCloth", ">= 4.1.0", "< 4.2.0" + + + + 1mREQUIRE AS0m + Each 4mgem24m 1mMAY 22mspecify files that should be used when autorequiring via + 1mBundler.require22m. You may pass an array with multiple files or 1mtrue 22mif + file you want 1mrequired 22mhas same name as 4mgem24m or 1mfalse 22mto prevent any + file from being autorequired. + + + + gem "redis", :require => ["redis/connection/hiredis", "redis"] + gem "webmock", :require => false + gem "debugger", :require => true + + + + The argument defaults to the name of the gem. For example, these are + identical: + + + + gem "nokogiri" + gem "nokogiri", :require => "nokogiri" + gem "nokogiri", :require => true + + + + 1mGROUPS0m + Each 4mgem24m 1mMAY 22mspecify membership in one or more groups. Any 4mgem24m that + does not specify membership in any group is placed in the 1mdefault0m + group. + + + + gem "rspec", :group => :test + gem "wirble", :groups => [:development, :test] + + + + The Bundler runtime allows its two main methods, 1mBundler.setup 22mand + 1mBundler.require22m, to limit their impact to particular groups. + + + + # setup adds gems to Ruby's load path + Bundler.setup # defaults to all groups + require "bundler/setup" # same as Bundler.setup + Bundler.setup(:default) # only set up the _default_ group + Bundler.setup(:test) # only set up the _test_ group (but `not` _default_) + Bundler.setup(:default, :test) # set up the _default_ and _test_ groups, but no others + + # require requires all of the gems in the specified groups + Bundler.require # defaults to the _default_ group + Bundler.require(:default) # identical + Bundler.require(:default, :test) # requires the _default_ and _test_ groups + Bundler.require(:test) # requires the _test_ group + + + + The Bundler CLI allows you to specify a list of groups whose gems 1mbun-0m + 1mdle install 22mshould not install with the 1m--without 22moption. To specify + multiple groups to ignore, specify a list of groups separated by spa- + ces. + + + + bundle install --without test + bundle install --without development test + + + + After running 1mbundle install --without test22m, bundler will remember that + you excluded the test group in the last installation. The next time you + run 1mbundle install22m, without any 1m--without option22m, bundler will recall + it. + + Also, calling 1mBundler.setup 22mwith no parameters, or calling 1mrequire0m + 1m"bundler/setup" 22mwill setup all groups except for the ones you excluded + via 1m--without 22m(since they are not available). + + Note that on 1mbundle install22m, bundler downloads and evaluates all gems, + in order to create a single canonical list of all of the required gems + and their dependencies. This means that you cannot list different ver- + sions of the same gems in different groups. For more details, see + Understanding Bundler 4mhttp://bundler.io/rationale.html24m. + + 1mPLATFORMS0m + If a gem should only be used in a particular platform or set of plat- + forms, you can specify them. Platforms are essentially identical to + groups, except that you do not need to use the 1m--without 22minstall-time + flag to exclude groups of gems for other platforms. + + There are a number of 1mGemfile 22mplatforms: + + 1mruby 22mC Ruby (MRI), Rubinius or TruffleRuby, but 1mNOT 22mWindows + + 1mmri 22mSame as 4mruby24m, but only C Ruby (MRI) + + 1mmingw 22mWindows 32 bit 'mingw32' platform (aka RubyInstaller) + + 1mx64_mingw0m + Windows 64 bit 'mingw32' platform (aka RubyInstaller x64) + + 1mrbx 22mRubinius + + 1mjruby 22mJRuby + + 1mtruffleruby0m + TruffleRuby + + 1mmswin 22mWindows + + You can restrict further by platform and version for all platforms + 4mexcept24m for 1mrbx22m, 1mjruby22m, 1mtruffleruby 22mand 1mmswin22m. + + To specify a version in addition to a platform, append the version num- + ber without the delimiter to the platform. For example, to specify that + a gem should only be used on platforms with Ruby 2.3, use: + + + + ruby_23 + + + + The full list of platforms and supported versions includes: + + 1mruby 22m1.8, 1.9, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5 + + 1mmri 22m1.8, 1.9, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5 + + 1mmingw 22m1.8, 1.9, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5 + + 1mx64_mingw0m + 2.0, 2.1, 2.2, 2.3, 2.4, 2.5 + + As with groups, you can specify one or more platforms: + + + + gem "weakling", :platforms => :jruby + gem "ruby-debug", :platforms => :mri_18 + gem "nokogiri", :platforms => [:mri_18, :jruby] + + + + All operations involving groups (1mbundle install 4m22mbundle-install.1.html24m, + 1mBundler.setup22m, 1mBundler.require22m) behave exactly the same as if any + groups not matching the current platform were explicitly excluded. + + 1mSOURCE0m + You can select an alternate Rubygems repository for a gem using the + ':source' option. + + + + gem "some_internal_gem", :source => "https://gems.example.com" + + + + This forces the gem to be loaded from this source and ignores any + global sources declared at the top level of the file. If the gem does + not exist in this source, it will not be installed. + + Bundler will search for child dependencies of this gem by first looking + in the source selected for the parent, but if they are not found there, + it will fall back on global sources using the ordering described in + 4mSOURCE24m 4mPRIORITY24m. + + Selecting a specific source repository this way also suppresses the + ambiguous gem warning described above in 4mGLOBAL24m 4mSOURCES24m 4m(#source)24m. + + Using the 1m:source 22moption for an individual gem will also make that + source available as a possible global source for any other gems which + do not specify explicit sources. Thus, when adding gems with explicit + sources, it is recommended that you also ensure all other gems in the + Gemfile are using explicit sources. + + 1mGIT0m + If necessary, you can specify that a gem is located at a particular git + repository using the 1m:git 22mparameter. The repository can be accessed via + several protocols: + + 1mHTTP(S)0m + gem "rails", :git => "https://github.com/rails/rails.git" + + 1mSSH 22mgem "rails", :git => "git@github.com:rails/rails.git" + + 1mgit 22mgem "rails", :git => "git://github.com/rails/rails.git" + + If using SSH, the user that you use to run 1mbundle install MUST 22mhave the + appropriate keys available in their 1m$HOME/.ssh22m. + + 1mNOTE22m: 1mhttp:// 22mand 1mgit:// 22mURLs should be avoided if at all possible. + These protocols are unauthenticated, so a man-in-the-middle attacker + can deliver malicious code and compromise your system. HTTPS and SSH + are strongly preferred. + + The 1mgroup22m, 1mplatforms22m, and 1mrequire 22moptions are available and behave + exactly the same as they would for a normal gem. + + A git repository 1mSHOULD 22mhave at least one file, at the root of the + directory containing the gem, with the extension 1m.gemspec22m. This file + 1mMUST 22mcontain a valid gem specification, as expected by the 1mgem build0m + command. + + If a git repository does not have a 1m.gemspec22m, bundler will attempt to + create one, but it will not contain any dependencies, executables, or C + extension compilation instructions. As a result, it may fail to prop- + erly integrate into your application. + + If a git repository does have a 1m.gemspec 22mfor the gem you attached it + to, a version specifier, if provided, means that the git repository is + only valid if the 1m.gemspec 22mspecifies a version matching the version + specifier. If not, bundler will print a warning. + + + + gem "rails", "2.3.8", :git => "https://github.com/rails/rails.git" + # bundle install will fail, because the .gemspec in the rails + # repository's master branch specifies version 3.0.0 + + + + If a git repository does 1mnot 22mhave a 1m.gemspec 22mfor the gem you attached + it to, a version specifier 1mMUST 22mbe provided. Bundler will use this ver- + sion in the simple 1m.gemspec 22mit creates. + + Git repositories support a number of additional options. + + 1mbranch22m, 1mtag22m, and 1mref0m + You 1mMUST 22monly specify at most one of these options. The default + is 1m:branch => "master"0m + + For example: + + git "https://github.com/rails/rails.git", :branch => "5-0-sta- + ble" do + + git "https://github.com/rails/rails.git", :tag => "v5.0.0" do + + git "https://github.com/rails/rails.git", :ref => "4aded" do + + 1msubmodules0m + For reference, a git submodule + 4mhttps://git-scm.com/book/en/v2/Git-Tools-Submodules24m lets you + have another git repository within a subfolder of your reposi- + tory. Specify 1m:submodules => true 22mto cause bundler to expand any + submodules included in the git repository + + If a git repository contains multiple 1m.gemspecs22m, each 1m.gemspec 22mrepre- + sents a gem located at the same place in the file system as the 1m.gem-0m + 1mspec22m. + + + + |~rails [git root] + | |-rails.gemspec [rails gem located here] + |~actionpack + | |-actionpack.gemspec [actionpack gem located here] + |~activesupport + | |-activesupport.gemspec [activesupport gem located here] + |... + + + + To install a gem located in a git repository, bundler changes to the + directory containing the gemspec, runs 1mgem build name.gemspec 22mand then + installs the resulting gem. The 1mgem build 22mcommand, which comes standard + with Rubygems, evaluates the 1m.gemspec 22min the context of the directory + in which it is located. + + 1mGIT SOURCE0m + A custom git source can be defined via the 1mgit_source 22mmethod. Provide + the source's name as an argument, and a block which receives a single + argument and interpolates it into a string to return the full repo + address: + + + + git_source(:stash){ |repo_name| "https://stash.corp.acme.pl/#{repo_name}.git" } + gem 'rails', :stash => 'forks/rails' + + + + In addition, if you wish to choose a specific branch: + + + + gem "rails", :stash => "forks/rails", :branch => "branch_name" + + + + 1mGITHUB0m + 1mNOTE22m: This shorthand should be avoided until Bundler 2.0, since it cur- + rently expands to an insecure 1mgit:// 22mURL. This allows a man-in-the-mid- + dle attacker to compromise your system. + + If the git repository you want to use is hosted on GitHub and is pub- + lic, you can use the :github shorthand to specify the github username + and repository name (without the trailing ".git"), separated by a + slash. If both the username and repository name are the same, you can + omit one. + + + + gem "rails", :github => "rails/rails" + gem "rails", :github => "rails" + + + + Are both equivalent to + + + + gem "rails", :git => "git://github.com/rails/rails.git" + + + + Since the 1mgithub 22mmethod is a specialization of 1mgit_source22m, it accepts a + 1m:branch 22mnamed argument. + + 1mGIST0m + If the git repository you want to use is hosted as a Github Gist and is + public, you can use the :gist shorthand to specify the gist identifier + (without the trailing ".git"). + + + + gem "the_hatch", :gist => "4815162342" + + + + Is equivalent to: + + + + gem "the_hatch", :git => "https://gist.github.com/4815162342.git" + + + + Since the 1mgist 22mmethod is a specialization of 1mgit_source22m, it accepts a + 1m:branch 22mnamed argument. + + 1mBITBUCKET0m + If the git repository you want to use is hosted on Bitbucket and is + public, you can use the :bitbucket shorthand to specify the bitbucket + username and repository name (without the trailing ".git"), separated + by a slash. If both the username and repository name are the same, you + can omit one. + + + + gem "rails", :bitbucket => "rails/rails" + gem "rails", :bitbucket => "rails" + + + + Are both equivalent to + + + + gem "rails", :git => "https://rails@bitbucket.org/rails/rails.git" + + + + Since the 1mbitbucket 22mmethod is a specialization of 1mgit_source22m, it + accepts a 1m:branch 22mnamed argument. + + 1mPATH0m + You can specify that a gem is located in a particular location on the + file system. Relative paths are resolved relative to the directory con- + taining the 1mGemfile22m. + + Similar to the semantics of the 1m:git 22moption, the 1m:path 22moption requires + that the directory in question either contains a 1m.gemspec 22mfor the gem, + or that you specify an explicit version that bundler should use. + + Unlike 1m:git22m, bundler does not compile C extensions for gems specified + as paths. + + + + gem "rails", :path => "vendor/rails" + + + + If you would like to use multiple local gems directly from the filesys- + tem, you can set a global 1mpath 22moption to the path containing the gem's + files. This will automatically load gemspec files from subdirectories. + + + + path 'components' do + gem 'admin_ui' + gem 'public_ui' + end + + + +1mBLOCK FORM OF SOURCE, GIT, PATH, GROUP and PLATFORMS0m + The 1m:source22m, 1m:git22m, 1m:path22m, 1m:group22m, and 1m:platforms 22moptions may be applied + to a group of gems by using block form. + + + + source "https://gems.example.com" do + gem "some_internal_gem" + gem "another_internal_gem" + end + + git "https://github.com/rails/rails.git" do + gem "activesupport" + gem "actionpack" + end + + platforms :ruby do + gem "ruby-debug" + gem "sqlite3" + end + + group :development, :optional => true do + gem "wirble" + gem "faker" + end + + + + In the case of the group block form the :optional option can be given + to prevent a group from being installed unless listed in the 1m--with0m + option given to the 1mbundle install 22mcommand. + + In the case of the 1mgit 22mblock form, the 1m:ref22m, 1m:branch22m, 1m:tag22m, and 1m:sub-0m + 1mmodules 22moptions may be passed to the 1mgit 22mmethod, and all gems in the + block will inherit those options. + + The presence of a 1msource 22mblock in a Gemfile also makes that source + available as a possible global source for any other gems which do not + specify explicit sources. Thus, when defining source blocks, it is rec- + ommended that you also ensure all other gems in the Gemfile are using + explicit sources, either via source blocks or 1m:source 22mdirectives on + individual gems. + +1mINSTALL_IF0m + The 1minstall_if 22mmethod allows gems to be installed based on a proc or + lambda. This is especially useful for optional gems that can only be + used if certain software is installed or some other conditions are met. + + + + install_if -> { RUBY_PLATFORM =~ /darwin/ } do + gem "pasteboard" + end + + + +1mGEMSPEC0m + The 1m.gemspec 4m22mhttp://guides.rubygems.org/specification-reference/24m file + is where you provide metadata about your gem to Rubygems. Some required + Gemspec attributes include the name, description, and homepage of your + gem. This is also where you specify the dependencies your gem needs to + run. + + If you wish to use Bundler to help install dependencies for a gem while + it is being developed, use the 1mgemspec 22mmethod to pull in the dependen- + cies listed in the 1m.gemspec 22mfile. + + The 1mgemspec 22mmethod adds any runtime dependencies as gem requirements in + the default group. It also adds development dependencies as gem + requirements in the 1mdevelopment 22mgroup. Finally, it adds a gem require- + ment on your project (1m:path => '.'22m). In conjunction with 1mBundler.setup22m, + this allows you to require project files in your test code as you would + if the project were installed as a gem; you need not manipulate the + load path manually or require project files via relative paths. + + The 1mgemspec 22mmethod supports optional 1m:path22m, 1m:glob22m, 1m:name22m, and 1m:develop-0m + 1mment_group 22moptions, which control where bundler looks for the 1m.gemspec22m, + the glob it uses to look for the gemspec (defaults to: "{,4m,24m/*}.gem- + spec"), what named 1m.gemspec 22mit uses (if more than one is present), and + which group development dependencies are included in. + + When a 1mgemspec 22mdependency encounters version conflicts during resolu- + tion, the local version under development will always be selected -- + even if there are remote versions that better match other requirements + for the 1mgemspec 22mgem. + +1mSOURCE PRIORITY0m + When attempting to locate a gem to satisfy a gem requirement, bundler + uses the following priority order: + + 1. The source explicitly attached to the gem (using 1m:source22m, 1m:path22m, or + 1m:git22m) + + 2. For implicit gems (dependencies of explicit gems), any source, git, + or path repository declared on the parent. This results in bundler + prioritizing the ActiveSupport gem from the Rails git repository + over ones from 1mrubygems.org0m + + 3. The sources specified via global 1msource 22mlines, searching each + source in your 1mGemfile 22mfrom last added to first added. + + + + + + + October 2018 GEMFILE(5) |