اطلاعات احراز هویت (CREDENTIALS)

برخی از منابع جم به نام کاربری و گذرواژه نیاز دارند. از دستور bundle config(1) bundle-config.1.html برای تنظیم نام کاربری و گذرواژه برای هر منبعی که به آن نیاز دارد استفاده کنید. این دستور باید یک بار روی هر رایانه‌ای که Gemfile را نصب می‌کند اجرا شود، اما مانع از ذخیره اطلاعات احراز هویت به صورت متن خام در سیستم کنترل نسخه می‌شود.

bundle config gems.example.com user:password

برای برخی منابع، مانند حساب شرکتی Gemfury، ممکن است قرار دادن اطلاعات ورود در Gemfile به عنوان بخشی از نشانی اینترنتی منبع ساده‌تر باشد.

source "https://user:password@gems.example.com"

اطلاعات احراز هویت موجود در نشانی URL منبع نسبت به موارد تنظیم‌شده از طریق config اولویت خواهند داشت.

نگارش (VERSION - الزامی)

نگارش روبی که برنامه شما نیاز دارد. اگر برنامه شما به یک موتور جایگزین روبی مانند JRuby، TruffleRuby یا غیره نیاز دارد، این باید نگارش روبی باشد که موتور با آن سازگار است.

ruby "3.1.2"

اگر مایلید نگارش روبی خود را از یک فایل نگارش (مانند .ruby-version) استخراج کنید، می‌توانید به جای آن از گزینه file استفاده کنید.

ruby file: ".ruby-version"

فایل نگارش باید با هر یک از قالب‌های زیر مطابقت داشته باشد:

• 3.1.2 (.ruby-version)
• ruby 3.1.2 (.tool-versions، خواندن: https://asdf-vm.com/manage/configuration.html#tool-versions)

موتور (ENGINE)

هر برنامه may (می‌تواند) یک موتور روبی را مشخص کند. اگر موتور مشخص شود، نگارش موتور نیز must (باید) تعیین گردد.

دقیقاً موتور چیست؟

• موتور روبی پیاده‌سازی از زبان روبی است.
• برای پیش‌زمینه: پیاده‌سازی مرجع یا اصلی زبان برنامه‌نویسی روبی با نام مفسر روبی ماتز https://en.wikipedia.org/wiki/Ruby_MRI یا به اختصار MRI شناخته می‌شود. این نام برگرفته از سازنده روبی یوکیهیرو ماتسوموتو، معروف به Matz است. MRI همچنین با عنوان CRuby شناخته می‌شود، زیرا به زبان C نوشته شده است. MRI پرکاربردترین موتور روبی است.
• پیاده‌سازی‌های دیگری https://www.ruby-lang.org/en/about از روبی وجود دارند. برخی از پیاده‌سازی‌های شناخته‌شده‌تر شامل JRuby https://www.jruby.org و TruffleRuby https://www.graalvm.org/ruby هستند. Rubinius پیاده‌سازی دیگری از روبی است که به خود زبان روبی نوشته شده است. JRuby پیاده‌سازی روبی روی JVM (سرنام Java Virtual Machine) است. TruffleRuby یک پیاده‌سازی روبی روی GraalVM است؛ جعبه‌ابزار زبانی که روی JVM ساخته شده است.

نگارش موتور (ENGINE VERSION)

هر برنامه may (می‌تواند) نگارش موتور روبی را مشخص کند. اگر نگارش موتور مشخص شود، نام موتور نیز must (باید) تعیین شود. اگر موتور "ruby" باشد، نگارش موتور مشخص‌شده must (باید) با نگارش روبی مطابقت داشته باشد.

ruby "2.6.8", engine: "jruby", engine_version: "9.3.8.0"

سطح پچ (PATCHLEVEL)

هر برنامه may (می‌تواند) سطح پچ روبی را مشخص کند. تعیین سطح پچ از زمان عرضه Ruby 2.1.0 بی‌معنی بوده است زیرا سطح پچ اکنون به طور یکتا با ترکیبی از شماره نگارش‌های اصلی (major)، فرعی (minor) و جزئی (teeny) تعیین می‌شود.

این گزینه در Bundler 1.4.0 برای Ruby 2.0 یا قدیمی‌تر پیاده‌سازی شده بود.

ruby "3.1.2", patchlevel: "20"

نام (NAME - الزامی)

برای هر نیازمندی جم، یک سطر منفرد gem بنویسید.

gem "nokogiri"

نگارش (VERSION)

هر gem MAY (می‌تواند) یک یا چند مشخص‌کننده نگارش داشته باشد.

gem "nokogiri", ">= 1.4.2"
gem "RedCloth", ">= 4.1.0", "< 4.2.0"

بارگذاری به عنوان (REQUIRE AS)

هر gem MAY (می‌تواند) فایل‌هایی را مشخص کند که باید هنگام بارگذاری خودکار از طریق Bundler.require استفاده شوند. می‌توانید آرایه‌ای از چند فایل، یا true را بفرستید اگر فایلی که می‌خواهید require شود همنام با gem است، یا false تا از بارگذاری خودکار هرگونه فایلی جلوگیری شود.

gem "redis", require: ["redis/connection/hiredis", "redis"]
gem "webmock", require: false
gem "byebug", require: true

مقدار پیش‌فرض این آرگومان نام جم است. برای نمونه، این سطرها یکسان هستند:

gem "nokogiri"
gem "nokogiri", require: "nokogiri"
gem "nokogiri", require: true

گروه‌ها (GROUPS)

هر gem MAY (می‌تواند) عضویت در یک یا چند گروه را مشخص کند. هر gem که عضویتی در هیچ گروهی مشخص نکند در گروه default قرار می‌گیرد.

gem "rspec", group: :test
gem "wirble", groups: [:development, :test]

محیط اجرای Bundler به دو متد اصلی خود، یعنی Bundler.setup و Bundler.require اجازه می‌دهد تأثیر خود را به گروه‌های خاصی محدود کنند.

# متد setup جم‌ها را به load path روبی اضافه می‌کند
Bundler.setup                    # پیش‌فرض برای همه گروه‌ها
require "bundler/setup"          # همانند Bundler.setup
Bundler.setup(:default)          # فقط برپاسازی گروه پیش‌فرض (_default_)
Bundler.setup(:test)             # فقط برپاسازی گروه آزمون (_test_) (و نه _default_)
Bundler.setup(:default, :test)   # برپاسازی گروه‌های _default_ و _test_، بدون موارد دیگر
# متد require تمام جم‌های گروه‌های مشخص‌شده را لود می‌کند
Bundler.require                  # پیش‌فرض روی گروه _default_
Bundler.require(:default)        # یکسان با قبلی
Bundler.require(:default, :test) # فراخوانی گروه‌های _default_ و _test_
Bundler.require(:test)           # فراخوانی گروه _test_

رابط خط فرمان Bundler به شما اجازه می‌دهد فهرستی از گروه‌هایی که bundle install نباید نصب کند را با پیکربندی without مشخص کنید.

برای تعیین چند گروه جهت نادیده گرفتن، فهرستی از گروه‌ها را با فاصله جدا کنید.

bundle config set --local without test
bundle config set --local without development test

همچنین فراخوانی Bundler.setup بدون پارامتر، یا فراخوانی require "bundler/setup" تمام گروه‌ها را به جز آن‌هایی که از طریق --without مستثنی کرده‌اید برپا می‌سازد (زیرا در دسترس نیستند).

توجه داشته باشید که هنگام اجرای bundle install، باندلر تمام جم‌ها را دانلود و ارزیابی می‌کند تا یک فهرست واحد و استاندارد از همه جم‌های مورد نیاز و وابستگی‌های آن‌ها ایجاد کند. این بدان معناست که شما نمی‌توانید نگارش‌های متفاوتی از همان جم‌ها را در گروه‌های مختلف فهرست کنید. برای جزئیات بیشتر، درک Bundler را در https://bundler.io/rationale.html ببینید.

سکscoreها (PLATFORMS)

اگر یک جم باید تنها در سکویی خاص یا مجموعه‌ای از سکوها استفاده شود، می‌توانید آن‌ها را مشخص کنید. سکوها اساساً مشابه گروه‌ها هستند، با این تفاوت که نیازی به استفاده از پرچم زمان نصب --without برای استثنا کردن گروه‌های جم برای سایر سکوها ندارید.

تعدادی سکو در Gemfile وجود دارد:

ruby

محیط C Ruby (MRI)، Rubinius، یا TruffleRuby، اما بدون Windows

mri

فقط C Ruby (MRI)، اما بدون Windows

windows

محیط Windows C Ruby (MRI)، شامل نگارش‌های ۳۲ بیتی و ۶۴ بیتی RubyInstaller

mswin

محیط Windows C Ruby (MRI)، شامل نگارش‌های ۳۲ بیتی RubyInstaller

mswin64

محیط Windows C Ruby (MRI)، شامل نگارش‌های ۶۴ بیتی RubyInstaller

rbx

محیط Rubinius

jruby

محیط JRuby

truffleruby

محیط TruffleRuby

در سکوهای ruby، mri، mswin، mswin64 و windows، علاوه بر این می‌توانید یک نگارش را با الحاق شماره‌های اصلی و فرعی نگارش بدون جداکننده مشخص کنید. برای نمونه، برای تعیین اینکه یک جم فقط باید در سکوی ruby نگارش 3.1 استفاده شود، از این الگو استفاده کنید:

ruby_31

همانند گروه‌ها (در بالا)، می‌توانید یک یا چند سکو را مشخص کنید:

gem "weakling",   platforms: :jruby
gem "ruby-debug", platforms: :mri_31
gem "nokogiri",   platforms: [:windows_31, :jruby]

تمام عملیات مرتبط با گروه‌ها (bundle install bundle-install.1.html، Bundler.setup، Bundler.require) دقیقاً همان‌گونه رفتار می‌کنند که گویی گروه‌هایی که با سکوی فعلی مطابقت ندارند صریحاً مستثنی شده‌اند.

مقادیر سکوی زیر منسوخ شده‌اند و باید با windows جایگزین شوند:

•

mswin، mswin64، mingw32، x64_mingw

توجه داشته باشید اگرچه متأسفانه از همان اصطلاحات استفاده می‌شود، اما مقادیر این گزینه با مقادیری که bundle lock --add-platform می‌پذیرد متفاوت است. مقادیر این گزینه به "پیاده‌سازی روبی" نزدیک‌تر است در حالی که مقادیری که دستور bundle lock --add-platform درک می‌کند بیشتر به سیستم‌عامل و معماری سیستم‌های مختلفی مربوط است که lockfile شما در آن‌ها استفاده خواهد شد.

گزینه FORCE_RUBY_PLATFORM

اگر همیشه می‌خواهید نسخه روبی خالص (pure ruby) یک جم به جای نسخه‌های وابسته به سکو انتخاب شود، می‌توانید از گزینه force_ruby_platform استفاده کنید:

gem "ffi", force_ruby_platform: true

این مورد می‌تواند در شرایط زیر کارآمد باشد (با این فرض که نسخه روبی خالص به خوبی کار می‌کند):

• هنگامی که با نسخه وابسته به سکوی خاص به مشکل برخورده‌اید.
• نسخه وابسته به سکو هنوز از روبی جدیدتر پشتیبانی نمی‌کند (و بنابراین دارای حد بالای required_ruby_version است)، اما همچنان می‌خواهید فایل‌های Gemfile{.lock} شما تحت آن روبی حل وابستگی شوند.

منبع (SOURCE)

می‌توانید با استفاده از گزینه ':source' یک مخزن RubyGems جایگزین را برای یک جم انتخاب کنید.

gem "some_internal_gem", source: "https://gems.example.com"

این کار بارگذاری جم را از این منبع اجباری می‌کند و منبع سراسری تعریف‌شده در سطح بالای فایل را نادیده می‌گیرد. اگر جم در این منبع وجود نداشته باشد، نصب نخواهد شد.

باندلر ابتدا با جستجو در منبع انتخاب‌شده برای جم والد، وابستگی‌های فرزند این جم را جستجو می‌کند، اما اگر آن‌ها در آنجا یافت نشوند، به منبع سراسری بازمی‌گردد.

نکته درباره رفتار ویژگی منسوخ‌شده در Bundler 1.13: انتخاب یک مخزن منبع مشخص به این شیوه، همچنین هشدار جم چندگانه تشریح‌شده در مخزن سراسری (GLOBAL SOURCE) را بی‌اثر می‌کند.

استفاده از گزینه :source برای یک جم منفرد، همچنین آن منبع را به عنوان یک منبع سراسری بالقوه برای سایر جم‌هایی که منابع صریح را مشخص نکرده‌اند در دسترس قرار می‌دهد. بنابراین، هنگام افزودن جم‌ها با منابع صریح، توصیه می‌شود مطمئن شوید که سایر جم‌ها در Gemfile نیز از منابع صریح استفاده می‌کنند.

گیت (GIT)

در صورت نیاز، می‌توانید مشخص کنید که یک جم در مخزن گیت خاصی با استفاده از پارامتر :git قرار دارد. دسترسی به مخزن از طریق چندین پروتکل امکان‌پذیر است:

HTTP(S)

gem "rails", git: "https://github.com/rails/rails.git"

SSH

gem "rails", git: "git@github.com:rails/rails.git"

git

gem "rails", git: "git://github.com/rails/rails.git"

در صورت استفاده از SSH، کاربری که از آن برای اجرای bundle install استفاده می‌کنید MUST (باید) کلیدهای مناسب را در $HOME/.ssh خود داشته باشد.

یادداشت: در صورت امکان باید از نشانی‌های اینترنتی http:// و git:// اجتناب کرد. این پروتکل‌ها احراز هویت نشده هستند، بنابراین یک مهاجم میانی (man-in-the-middle) می‌تواند کد مخرب تزریق کرده و سیستم شما را به خطر بیندازد. پروتکل‌های HTTPS و SSH به شدت ارجح هستند.

گزینه‌های group، platforms، و require در دسترس هستند و دقیقاً مشابه یک جم معمولی عمل می‌کنند.

یک مخزن گیت SHOULD (باید ترجیحاً) حداقل یک فایل در ریشه دایرکتوری حاوی جم با پسوند .gemspec داشته باشد. این فایل MUST (باید) حاوی یک مشخصات جم معتبر باشد، همان‌طور که دستور gem build انتظار دارد.

اگر یک مخزن گیت فایل .gemspec نداشته باشد، باندلر تلاش می‌کند تا یکی بسازد، اما این فایل فاقد هرگونه وابستگی، فایل اجرایی یا دستورالعمل‌های کامپایل افزونه C خواهد بود. در نتیجه، ممکن است نتواند به درستی با برنامه شما یکپارچه شود.

اگر یک مخزن گیت دارای یک .gemspec برای جمی باشد که به آن متصل کرده‌اید، تعیین نگارش (در صورت ارائه) بدین معناست که مخزن گیت تنها زمانی معتبر است که .gemspec نگارشی مطابق با مشخص‌کننده نگارش تعیین کند. در غیر این صورت، باندلر هشداری چاپ می‌کند.

gem "rails", "2.3.8", git: "https://github.com/rails/rails.git"
# دستور bundle install با شکست مواجه می‌شود، زیرا .gemspec در
# شاخه master مخزن rails نگارش 3.0.0 را مشخص می‌کند

اگر مخزن گیت فایل .gemspec برای جمی که به آن متصل کرده‌اید نداشته باشد، MUST (باید) یک مشخص‌کننده نگارش ارائه شود. باندلر از این نگارش در فایل ساده .gemspec که ایجاد می‌کند استفاده خواهد کرد.

مخازن گیت از تعدادی گزینه اضافی پشتیبانی می‌کنند.

branch، tag، و ref

شما MUST (باید) حداکثر یکی از این گزینه‌ها را مشخص کنید. مقدار پیش‌فرض branch: "master" است. برای نمونه:

gem "rails", git: "https://github.com/rails/rails.git", branch: "5-0-stable"

gem "rails", git: "https://github.com/rails/rails.git", tag: "v5.0.0"

gem "rails", git: "https://github.com/rails/rails.git", ref: "4aded"

submodules

برای مرجع، زیرماژول گیت https://git-scm.com/book/en/v2/Git-Tools-Submodules به شما اجازه می‌دهد مخزن گیت دیگری در زیرپوشه‌ای از مخزن خود داشته باشید. تعیین submodules: true باعث می‌شود باندلر هر زیرماژول موجود در مخزن گیت را باز کند.

اگر یک مخزن گیت حاوی چندین فایل .gemspec باشد، هر .gemspec نشان‌دهنده جمی است که در همان مکان در سیستم فایل قرار دارد که .gemspec قرار گرفته است.

|~rails                   [ریشه گیت]
| |-rails.gemspec         [جم rails اینجا قرار دارد]
|~actionpack
| |-actionpack.gemspec    [جم actionpack اینجا قرار دارد]
|~activesupport
| |-activesupport.gemspec [جم activesupport اینجا قرار دارد]
|...

برای نصب جمی که در مخزن گیت قرار دارد، باندلر به دایرکتوری حاوی gemspec می‌رود، دستور gem build name.gemspec را اجرا می‌کند و سپس جم حاصل را نصب می‌نماید. دستور gem build که به صورت استاندارد همراه با Rubygems ارائه می‌شود، فایل .gemspec را در چارچوب دایرکتوری که در آن قرار دارد ارزیابی می‌کند.

منبع گیت (GIT SOURCE)

یک منبع سفارشی گیت را می‌توان از طریق متد git_source تعریف کرد. نام منبع را به عنوان آرگومان، و بلوکی که یک آرگومان دریافت می‌کند و آن را در یک رشته برای بازگرداندن آدرس کامل مخزن درون‌یابی می‌کند، ارائه دهید:

git_source(:stash){ |repo_name| "https://stash.corp.acme.pl/#{repo_name}.git" }
gem 'rails', stash: 'forks/rails'

علاوه بر این، اگر مایل به انتخاب شاخه خاصی هستید:

gem "rails", stash: "forks/rails", branch: "branch_name"

گیت‌هاب (GITHUB)

یادداشت: تا قبل از Bundler 2.0 باید از این شکل مختصر اجتناب شود، زیرا در حال حاضر به یک نشانی ناامن git:// گسترش می‌یابد. این امر به مهاجم میانی اجازه می‌دهد سیستم شما را به خطر بیندازد.

اگر مخزن گیت مورد نظر شما روی GitHub میزبانی شده و عمومی است، می‌توانید از مختصرنویسی :github برای تعیین نام کاربری گیت‌هاب و نام مخزن (بدون پسوند ".git")، که با اسلش از هم جدا شده‌اند، استفاده کنید. اگر هر دو نام کاربری و نام مخزن یکسان باشند، می‌توانید یکی را حذف کنید.

gem "rails", github: "rails/rails"
gem "rails", github: "rails"

هر دو معادل هستند با

gem "rails", git: "https://github.com/rails/rails.git"

از آنجا که متد github نوعی تخصیص از git_source است، آرگومان نام‌دار :branch را می‌پذیرد.

همچنین می‌توانید مستقیماً نشانی یک Pull Request را ارسال کنید:

gem "rails", github: "https://github.com/rails/rails/pull/43753"

که معادل است با:

gem "rails", github: "rails/rails", branch: "refs/pull/43753/head"

گیست (GIST)

اگر مخزن گیت مد نظر به صورت GitHub Gist میزبانی شده و عمومی است، می‌توانید از مختصرنویسی :gist برای تعیین شناسه gist (بدون پسوند ".git") استفاده کنید.

gem "the_hatch", gist: "4815162342"

معادل است با:

gem "the_hatch", git: "https://gist.github.com/4815162342.git"

از آنجا که متد gist نوعی تخصیص از git_source است، آرگومان نام‌دار :branch را می‌پذیرد.

بیت‌باکت (BITBUCKET)

اگر مخزن گیت مد نظر روی Bitbucket میزبانی شده و عمومی است، می‌توانید از مختصرنویسی :bitbucket برای تعیین نام کاربری بیت‌باکت و نام مخزن (بدون پسوند ".git") که با اسلش از هم جدا شده‌اند استفاده کنید. اگر هم نام کاربری و هم نام مخزن یکسان باشند، می‌توانید یکی را حذف کنید.

gem "rails", bitbucket: "rails/rails"
gem "rails", bitbucket: "rails"

هر دو معادل هستند با

gem "rails", git: "https://rails@bitbucket.org/rails/rails.git"

از آنجا که متد bitbucket نوعی تخصیص از git_source است، آرگومان نام‌دار :branch را می‌پذیرد.

مسیر (PATH)

می‌توانید مشخص کنید که یک جم در مکان خاصی روی سیستم فایل قرار دارد. مسیرهای نسبی نسبت به دایرکتوری حاوی Gemfile حل می‌شوند.

همانند ساختار گزینه :git، گزینه :path نیز مستلزم آن است که دایرکتوری مورد نظر یا حاوی یک .gemspec برای جم باشد، یا اینکه نگارش صریحی را که باندلر باید استفاده کند مشخص نمایید.

برخلاف :git، باندلر افزونه‌های C را برای جم‌هایی که به عنوان مسیر مشخص شده‌اند کامپایل نمی‌کند.

gem "rails", path: "vendor/rails"

اگر می‌خواهید چندین جم محلی را مستقیماً از سیستم فایل استفاده کنید، می‌توانید یک گزینه سراسری path را به مسیری که حاوی فایل‌های جم است تنظیم کنید. این کار فایل‌های gemspec را به طور خودکار از زیردایرکتوری‌ها بارگذاری می‌کند.

path 'components' do
  gem 'admin_ui'
  gem 'public_ui'
end

اولویت فایل قفل (LOCKFILE PRECEDENCE)

هنگام تعیین مسیر فایل قفل یا تصمیم‌گیری درباره ایجاد فایل قفل، اولویت‌های زیر اعمال می‌شود:

1.

گزینه --no-lock در bundle install (که ایجاد lockfile را غیرفعال می‌کند).

2.

گزینه --lockfile در bundle install.

3.

متغیر محیطی BUNDLE_LOCKFILE.

4.

متد lockfile در Gemfile.

5.

رفتار پیش‌فرض اضافه کردن .lock به انتهای نام Gemfile.