.\" generated with Ronn-NG/v0.10.1
.\" http://github.com/apjanke/ronn-ng/tree/0.10.1
.TH "BUNDLE\-EXEC" "1" "September 2025" ""
.SH "نام (NAME)"
\fBbundle\-exec\fR \- اجرای یک دستور در بافت و زمینهٔ بسته (bundle)
.SH "خلاصه دستور (SYNOPSIS)"
\fBbundle exec\fR [\-\-gemfile=GEMFILE] \fIcommand\fR
.SH "توضیحات (DESCRIPTION)"
این دستور، دستور مشخص‌شده را طوری اجرا می‌کند که تمام gemهای تعیین‌شده در [\fBGemfile(5)\fR][Gemfile(5)] برای فراخوانی توسط \fBrequire\fR در برنامه‌های Ruby در دسترس قرار گیرند\.
.P
در اصل، اگر در حالت معمول دستوری مانند \fBrspec spec/my_spec\.rb\fR را اجرا می‌کردید و اکنون می‌خواهید از gemهای مشخص‌شده در [\fBGemfile(5)\fR][Gemfile(5)] که از طریق bundle install(1) \fIbundle\-install\.1\.html\fR نصب شده‌اند استفاده کنید، باید دستور \fBbundle exec rspec spec/my_spec\.rb\fR را اجرا نمایید\.
.P
توجه داشته باشید که \fBbundle exec\fR نیازی ندارد که فایل اجرایی مورد نظر حتماً در متغیر \fB$PATH\fR پوستهٔ شما موجود باشد\.
.SH "گزینه‌ها (OPTIONS)"
.TP
\fB\-\-gemfile=GEMFILE\fR
استفاده از gemfile مشخص‌شده به جای [\fBGemfile(5)\fR][Gemfile(5)]\.
.SH "دستور BUNDLE INSTALL \-\-BINSTUBS"
اگر از پرچم \fB\-\-binstubs\fR در bundle install(1) \fIbundle\-install\.1\.html\fR استفاده کنید، Bundler به‌طور خودکار دایرکتوری‌ای ایجاد می‌کند (که به‌طور پیش‌فرض \fBapp_root/bin\fR است) شامل تمام فایل‌های اجرایی که از طریق gemهای موجود در bundle در دسترس هستند\.
.P
پس از به‌کارگیری \fB\-\-binstubs\fR، اجرای \fBbin/rspec spec/my_spec\.rb\fR دقیقاً معادل با \fBbundle exec rspec spec/my_spec\.rb\fR خواهد بود\.
.SH "تغییرات محیطی (ENVIRONMENT MODIFICATIONS)"
دستور \fBbundle exec\fR تغییراتی در متغیرهای محیطی پوسته ایجاد کرده و سپس دستور مشخص‌شده توسط شما را به‌طور کامل اجرا می‌کند\.
.IP "\(bu" 4
اطمینان حاصل می‌کند که هنوز امکان اجرای دستور \fBbundle\fR از درون دستوری که توسط \fBbundle exec\fR فراخوانی شده است وجود دارد (با استفاده از \fB$BUNDLE_BIN_PATH\fR)
.IP "\(bu" 4
دایرکتوری حاوی فایل‌های اجرایی مربوط به bundle شما (مانند \fBrails\fR، \fBrspec\fR و \fBrackup\fR) را در متغیر \fB$PATH\fR قرار می‌دهد
.IP "\(bu" 4
اطمینان حاصل می‌کند که اگر bundler در زیرپوسته (subshell) فراخوانی شود، از همان \fBGemfile\fR استفاده کند (با تنظیم \fBBUNDLE_GEMFILE\fR)
.IP "\(bu" 4
افزودن \fB\-rbundler/setup\fR به متغیر \fB$RUBYOPT\fR، که تضمین می‌کند برنامه‌های Ruby فراخوانی‌شده در زیرپوسته می‌توانند gemهای موجود در bundle را شناسایی کنند
.IP "" 0
.P
این دستور همچنین Rubygems را به روش‌های زیر تغییر می‌دهد:
.IP "\(bu" 4
جلوگیری از بارگذاری gemهای اضافی که در bundle موجود نیستند
.IP "\(bu" 4
تغییر متد \fBgem\fR به‌گونه‌ای که اگر gem مطابق با نیازمندی‌ها در bundle موجود باشد، هیچ عملی انجام ندهد (no\-op)، و در صورتی که موجود نباشد، خطای \fBGem::LoadError\fR صادر کند
.IP "\(bu" 4
بی‌اثر کردن متد \fBGem\.refresh\fR (تنظیم به no\-op)، زیرا هنگام استفاده از bundler ایندکس منبع همیشه ثابت و مسدود (frozen) است و این کار از سرایت gemهای سیستمی به محیط جلوگیری می‌کند
.IP "\(bu" 4
بازنویسی متد \fBGem\.bin_path\fR برای استفاده از gemهای درون bundle، تا فایل‌های اجرایی سیستمی به درستی کار کنند
.IP "\(bu" 4
افزودن تمام gemهای موجود در bundle به Gem\.loaded_specs
.IP "" 0
.P
در نهایت، اگر فایل قفل و Gemfile با یکدیگر مطابقت نداشته باشند، \fBbundle exec\fR فایل \fBGemfile\.lock\fR را نیز به‌طور ضمنی اصلاح می‌کند\. ابزار Bundler برای تعیین مواردی از قبیل گروه‌های gem، \fBautorequire\fR و پلتفرم‌ها به Gemfile نیاز دارد و این اطلاعات در فایل قفل ذخیره نمی‌شوند\. برای اجرای موفقیت‌آمیز \fBbundle exec\fR باید Gemfile و فایل قفل با هم همگام باشند؛ بنابراین \fBbundle exec\fR پیش از اجرا، فایل قفل را به‌روزرسانی می‌کند\.
.SS "بارگذاری (Loading)"
به‌طور پیش‌فرض، هنگام تلاش برای اجرای \fBbundle exec\fR روی فایلی که دارای shebang زبان روبی است، Bundler به جای استفاده از \fBKernel\.exec\fR آن فایل را از طریق \fBKernel\.load\fR بارگذاری می‌کند\. در اکثر قریب به اتفاق موارد، این یک بهبود کارایی محسوب می‌شود\. در موارد معدودی، این رفتار ممکن است عوارض جانبی ظریفی ایجاد کند (مانند وابستگی به مقدار دقیق \fB$0\fR یا \fB__FILE__\fR)؛ این بهینه‌سازی را می‌توان با فعال‌سازی تنظیم \fBdisable_exec_load\fR غیرفعال کرد\.
.SS "اجرای دستور در پوسته (Shelling out)"
هر کد روبی که یک زیرپوسته باز کند (مانند متد \fBsystem\fR، بک‌تیک‌ها (\`\`) یا \fB%x{}\fR) به‌طور خودکار از محیط فعلی Bundler استفاده خواهد کرد\. اگر نیاز دارید دستوری در پوسته اجرا کنید که جزئی از bundle فعلی شما نیست، از متد \fBwith_unbundled_env\fR همراه با یک بلوک کد استفاده نمایید\. به تمام زیرپوسته‌هایی که درون این بلوک ایجاد می‌شوند، محیطی اختصاص می‌یابد که پیش از فعال شدن Bundler وجود داشته است\. برای نمونه، دستورات Homebrew کدهای Ruby را اجرا می‌کنند، اما در داخل یک bundle کارایی ندارند:
.IP "" 4
.nf
Bundler\.with_unbundled_env do
  `brew install wget`
end
.fi
.IP "" 0
.P
استفاده از \fBwith_unbundled_env\fR همچنین در حالتی که می‌خواهید دستوری را در یک bundle دیگر اجرا کنید ضروری است\. هر دستور Bundler که درون زیرپوسته اجرا شود Gemfile فعلی را به ارث می‌برد، بنابراین دستوراتی که باید در بافت یک bundle متفاوت اجرا شوند نیز نیاز به استفاده از \fBwith_unbundled_env\fR دارند\.
.IP "" 4
.nf
Bundler\.with_unbundled_env do
  Dir\.chdir "/other/bundler/project" do
    `bundle exec \./script`
  end
end
.fi
.IP "" 0
.P
ابزار Bundler توابع کمکی سودمندی فراهم می‌کند که متدهای \fBsystem\fR و \fBexec\fR را پوشش می‌دهند و می‌توان آن‌ها را به این صورت استفاده کرد:
.IP "" 4
.nf
Bundler\.unbundled_system('brew install wget')
Bundler\.unbundled_exec('brew install wget')
.fi
.IP "" 0
.SH "پلاگین‌های روبین‌جمز (RUBYGEMS PLUGINS)"
در حال حاضر، سیستم پلاگین Rubygems هنگامی که کدی \fBrubygems\.rb\fR را require می‌کند، نیازمند تمام فایل‌های با نام \fBrubygems_plugin\.rb\fR در مسیر بارگذاری \fIهر\fR gem نصب‌شده است\. این شامل فایل‌های اجرایی نصب‌شده در سیستم، نظیر \fBrails\fR، \fBrackup\fR و \fBrspec\fR نیز می‌شود\.
.P
از آنجا که پلاگین‌های Rubygems می‌توانند حاوی کدهای دلخواه Ruby باشند، معمولاً در نهایت باعث فعال‌سازی خود یا وابستگی‌هایشان می‌شوند\.
.P
برای نمونه، gem با نسخهٔ \fBgemcutter 0\.5\fR به \fBjson_pure\fR وابسته بود\. اگر آن نسخه از gemcutter را نصب داشتید (حتی اگر نسخهٔ جدیدتری بدون این مشکل را \fIنیز\fR نصب کرده بودید)، Rubygems نسخهٔ \fBgemcutter 0\.5\fR و آخرین نسخهٔ \fBjson_pure\fR را فعال می‌کرد\.
.P
اگر Gemfile(5) شما نیز شامل \fBjson_pure\fR بود (یا gem دیگری که به \fBjson_pure\fR وابسته بود)، آخرین نسخهٔ موجود در سیستم شما ممکن بود با نسخهٔ تعیین‌شده در Gemfile(5) یا نسخهٔ ثبت‌شده در \fBGemfile\.lock\fR تداخل پیدا کند\.
.P
در صورت بروز چنین رخدادی، bundler پیام زیر را اعلام خواهد کرد:
.IP "" 4
.nf
You have already activated json_pure 1\.4\.6 but your Gemfile
requires json_pure 1\.4\.3\. Consider using bundle exec\.
.fi
.IP "" 0
.P
در چنین شرایطی، تقریباً به‌طور قطع مایل خواهید بود gem پایه‌ای را که حاوی پلاگین مشکل‌ساز است حذف کنید\. به‌طور کلی، توسعه‌دهندگان این پلاگین‌ها (در این مورد، gem مربوط به \fBgemcutter\fR) نسخه‌های جدیدتری منتشر کرده‌اند که در پلاگین‌های خود احتیاط بیشتری اعمال می‌کنند\.
.P
شما می‌توانید با اجرای دستور زیر فهرستی از تمام gemهای حاوی پلاگین‌های gem را بیابید:
.IP "" 4
.nf
ruby \-e "puts Gem\.find_files('rubygems_plugin\.rb')"
.fi
.IP "" 0
.P
دست‌کم، باید همهٔ نسخه‌ها به جز جدیدترین نسخه از هر پلاگین gem را حذف کرده و همچنین تمام پلاگین‌های gem را که استفاده نمی‌کنید پاکسازی نمایید (\fBgem uninstall gem_name\fR)\.