DUNE-UPGRADE(1) Dune Manual DUNE-UPGRADE(1)

dune-upgrade - ارتقای پروژه‌ها بین نسخه‌های اصلی Dune

dune upgrade [OPTION]…

دستور dune upgrade تمام پروژه‌های موجود در فضای کاری را به آخرین نسخه اصلی Dune ارتقا می‌دهد.

--action-stderr-on-success=VAL
مشابه --action-stdout-on-success است، اما به‌جای خروجی استاندارد برای خطای استاندارد اعمال می‌شود. یک مقدار پیش‌فرض مناسب برای مخازن بزرگ یکپارچه (mono-repositories) استفاده از --action-stdout-on-success=swallow --action-stderr-on-success=must-be-empty است. این کار تضمین می‌کند که یک ساخت موفق، خروجی خالی و «تمیز» داشته باشد.
--action-stdout-on-success=VAL
تعیین نحوه برخورد با خروجی استاندارد اقدامات (actions) در صورت موفقیت‌آمیز بودن آن‌ها. مقادیر ممکن عبارتند از: print برای چاپ ساده آن در خروجی Dune، swallow برای نادیده گرفتن کامل آن، و must-be-empty برای الزام به این‌که اقدام هیچ چیزی چاپ نکرده باشد. با انتخاب must-be-empty، اگر اقدام چیزی در خروجی استاندارد چاپ کرده باشد، Dune آن را ناموفق تلقی خواهد کرد. مقدار پیش‌فرض print است.
--build-info
نمایش اطلاعات ساخت.
--display-separate-messages
جداسازی پیام‌های خطا با یک خط خالی.
--error-reporting=VAL (پیش‌فرض=deterministic)
زمان گزارش خطاهای ساخت را کنترل می‌کند. مقدار early خطاها را به محض شناسایی گزارش می‌دهد. مقدار deterministic خطاها را در پایان فرایند ساخت با ترتیبی معین گزارش می‌کند. مقدار twice هر خطا را دو بار گزارش می‌دهد: یک‌بار به محض شناسایی خطا و بار دیگر در پایان فرایند ساخت با ترتیبی معین.
-f، --force
اجبار اقدامات مرتبط با نام‌های مستعار (aliases) به اجرای مجدد، حتی اگر وابستگی‌های آن‌ها تغییری نکرده باشد.
--file-watcher=VAL (پیش‌فرض=automatic)
سازوکار تشخیص تغییرات در سورس‌کد. مقدار Automatic باعث می‌شود Dune برنامه‌ای خارجی را برای تشخیص تغییرات اجرا کند. مقدار Manual برای مطلع‌سازی دستی Dune از تغییر فایل‌ها به کار می‌رود.
--passive-watch-mode
مشابه [--watch]، اما فرایند ساخت را تنها زمانی آغاز می‌کند که از طریق یک فراخوانی RPC خارجی به آن دستور داده شود.
--sandbox=VAL (در صورت عدم وجود از متغیر DUNE_SANDBOX استفاده می‌شود)
تنظیم حالت ایزوله‌سازی (sandboxing). برخی اقدامات نیازمند حالت خاصی از ایزوله‌سازی هستند و این تنظیم را نادیده می‌گیرند. مقادیر مجاز عبارتند از: none، symlink، copy، hardlink.
--stop-on-first-error
توقف فرایند ساخت به محض مواجهه با نخستین خطا.
-w، --watch
به‌جای پایان دادن به فرایند ساخت پس از اتمام، به‌طور مداوم منتظر تغییرات فایل بماند.
--wait-for-filesystem-clock
برنامه Dune برای بهبود کارایی افزایشی (incremental)، محتوای فایل‌ها را خلاصه‌سازی (digest) می‌کند. این خلاصه‌ها خودشان کش می‌شوند. در برخی موارد، Dune برای قابل اطمینان بودن فرایندها نیاز دارد برخی از مدخل‌های کش خلاصه را دور بریزد. این گزینه باعث می‌شود Dune منتظر جلو رفتن ساعت سیستم‌فایل بماند تا نیازی به دور ریختن هیچ داده‌ای نباشد. احتمالاً نیازی به توجه به این گزینه نخواهید داشت؛ این گزینه بیشتر برای توسعه‌دهندگان Dune جهت افزایش تکرارپذیری آزمایش‌های مربوط به کش خلاصه مفید است.

این گزینه‌ها میان همه دستورها مشترک هستند.

--always-show-command-line
همیشه خط فرمان کامل برنامه‌های اجرا شده توسط Dune نمایش داده شود.
--auto-promote
ارتقای خودکار فایل‌ها (promote). این عمل مشابه اجرای dune promote پس از ساخت است.
--build-dir=FILE (در صورت عدم وجود از متغیر DUNE_BUILD_DIR استفاده می‌شود)
دایرکتوری ساخت مشخص‌شده. در صورت مشخص نشدن، پیش‌فرض _build است
--cache=VAL (در صورت عدم وجود از متغیر DUNE_CACHE استفاده می‌شود)
فعال یا غیرفعال کردن کش Dune (یکی از مقادیر disabled، enabled-except-user-rules یا enabled). مقدار پیش‌فرض `enabled-except-user-rules' است.
--cache-check-probability=VAL (در صورت عدم وجود از متغیر DUNE_CACHE_CHECK_PROBABILITY استفاده می‌شود)
بررسی تکرارپذیری ساخت از طریق اجرای مجدد قواعد تصادفی انتخاب‌شده و مقایسه نتایج آن‌ها با مقادیر ذخیره‌شده در کش Dune. نکته: افزایش احتمال این بررسی‌ها فرایند ساخت را کند می‌کند. احتمال پیش‌فرض صفر است، یعنی هیچ قاعده‌ای بررسی نمی‌شود.
--cache-storage-mode=VAL (در صورت عدم وجود از متغیر DUNE_CACHE_STORAGE_MODE استفاده می‌شود)
حالت ذخیره‌سازی کش Dune (یکی از مقادیر auto، hardlink یا copy). پیش‌فرض `hardlink' است.
--config-file=FILE
بارگذاری این فایل پیکربندی به‌جای فایل پیش‌فرض.
--debug-backtraces
همیشه ردگیری بازگشتی (backtrace) استثناها چاپ شود.
--debug-dependency-path
در صورت بروز خطا، مسیر وابستگی از هدف‌های خط فرمان تا قاعده‌ای که شکست خورده چاپ شود.
--debug-package-logs (در صورت عدم وجود از متغیر DUNE_DEBUG_PACKAGE_LOGS استفاده می‌شود)
همیشه گزارش‌های استاندارد هنگام ساخت بسته‌ها چاپ شود
--default-target=TARGET (پیش‌فرض=@@default)
تنظیم هدف پیش‌فرضی که در صورت مشخص نشدن هیچ هدفی برای dune build استفاده می‌شود.
--diff-command=VAL (در صورت عدم وجود از متغیر DUNE_DIFF_COMMAND استفاده می‌شود)
دستور شل مورد استفاده برای مقایسه فایل‌ها. برای غیرفعال کردن چاپ تفاوت‌ها از - استفاده کنید.
--disable-promotion (در صورت عدم وجود از متغیر DUNE_DISABLE_PROMOTION استفاده می‌شود)
غیرفعال کردن تمام قواعد ارتقا (promotion)
--display=MODE
کنترل حالت نمایش Dune. برای جزئیات بیشتر dune-config(5) را ببینید. مقادیر مجاز برای این گزینه عبارتند از: progress، verbose، short، quiet یا tui.
--dump-gc-stats=FILE
تخلیه آمار زباله‌روب (garbage collector) در یک فایل پس از تکمیل ساخت.
--help[=FMT] (پیش‌فرض=auto)
نمایش این راهنما در قالب FMT. مقدار FMT باید یکی از مقادیر auto، pager، groff یا plain باشد. با انتخاب auto، در صورتی که متغیر محیطی TERM برابر با dumb یا تعریف‌نشده باشد، قالب به pager یا plain تغییر می‌کند.
--ignore-promoted-rules
نادیده گرفتن قواعد دارای (mode promote)، به‌جز موارد دارای (only ...). متغیر %{ignoring_promoted_rules} در فایل‌های dune نشان‌دهنده استفاده یا عدم استفاده از این گزینه است.
--instrument-with=BACKENDS (در صورت عدم وجود از متغیر DUNE_INSTRUMENT_WITH استفاده می‌شود)
فعال‌سازی ابزار دقیق (instrumentation) توسط BACKENDS. مقدار BACKENDS فهرستی از نام‌های کتابخانه‌ها است که با کاما از هم جدا شده‌اند و هر یک باید یک بک‌اند ابزار دقیق را تعریف کنند.
-j JOBS (در صورت عدم وجود از متغیر DUNE_JOBS استفاده می‌شود)
عدم اجرای هم‌زمان بیش از JOBS دستور. مقدار JOBS باید یک عدد صحیح مثبت یا auto برای تشخیص خودکار تعداد هسته‌ها (پیش‌فرض) باشد.
--no-buffer
بافر نکردن خروجی دستورهای اجرا شده توسط dune. به‌طور پیش‌فرض dune خروجی زیردستورها را بافر می‌کند تا از تداخل خروجی‌ها هنگام اجرای هم‌زمان دستورها جلوگیری شود. با این حال، این مسئله ممکن است هنگام اشکال‌زدایی تست‌های طولانی مشکل‌ساز شود. با گزینه --no-buffer، دستورها دسترسی مستقیم به ترمینال دارند. توجه داشته باشید که در نتیجه، خروجی آن‌ها در فایل لاگ ذخیره نخواهد شد. برای جلوگیری از تداخل، بهتر است از این گزینه همراه با -j 1 استفاده کنید. علاوه بر این، استفاده از --verbose نیز توصیه می‌شود تا اطمینان یابید دستورها پیش از اجرا چاپ می‌شوند.
--no-config
عدم بارگذاری فایل پیکربندی
--no-print-directory
حذف پیام‌های "Entering directory"
--only-packages=PACKAGES
نادیده گرفتن بخش‌هایی (stanzas) که به بسته‌ای خارج از PACKAGES اشاره دارند. مقدار PACKAGES فهرستی از نام‌های بسته‌ها است که با کاما از هم جدا شده‌اند. توجه داشته باشید که این کار اثری مشابه حذف بندهای مربوطه از فایل‌های dune دارد. این گزینه عمدتاً برای انتشار بسته‌ها (releases) کاربرد دارد. در حین فرایند توسعه، معمولاً هدف شما ساخت یک تارگت خاص مانند <package>.install است.
-p PACKAGES، --for-release-of-packages=PACKAGES (الزامی)
کوتاه‌نوشتی برای --release --pkg=disabled --only-packages PACKAGE. باید از این گزینه در فایل‌های <package>.opam خود استفاده کنید تا در صورتی که پروژه‌تان شامل چندین بسته است، تنها بخش‌های ضروری ساخته شده و ساخت‌هایی تکرارپذیر حاصل شود.
--pkg=VAL
فعال یا غیرفعال کردن مدیریت بسته. رفتار پیش‌فرض وابسته به وجود دایرکتوری قفل (lock directory) است.
--profile=VAL (در صورت عدم وجود از متغیر DUNE_PROFILE استفاده می‌شود)
انتخاب نمایه ساخت (build profile)، برای نمونه dev یا release. مقدار پیش‌فرض dev است.
--promote-install-files[=VAL] (پیش‌فرض=true)
ارتقای فایل‌های تولیدشده <package>.install به درخت سورس‌کد.
--release
قرار دادن dune در حالت تکرارپذیر release. کوتاه‌نوشتی برای --root . --ignore-promoted-rules --no-config --profile release --always-show-command-line --promote-install-files --require-dune-project-file --default-target @install. باید از این گزینه برای ساخت‌های نهایی انتشار استفاده کنید. برای مثال، استفاده از آن در فایل‌های <package>.opam ضروری است؛ مگر این‌که پیش‌تر از -p استفاده کرده باشید، زیرا -p متضمن این گزینه است.
--require-dune-project-file[=VAL] (پیش‌فرض=true)
ایجاد خطا در صورت مفقود بودن فایل dune-project.
--root=DIR (در صورت عدم وجود از متغیر DUNE_ROOT استفاده می‌شود)
استفاده از این دایرکتوری به‌عنوان ریشه فضای کاری به‌جای حدس زدن آن. توجه داشته باشید که این گزینه تفسیر اهداف مشخص‌شده در خط فرمان را تغییر نمی‌دهد. این گزینه صرفاً برای اسکریپت‌ها در نظر گرفته شده است.
--store-orig-source-dir (در صورت عدم وجود از متغیر DUNE_STORE_ORIG_SOURCE_DIR استفاده می‌شود)
ذخیره مکان اصلی سورس‌کد در فراداده‌های dune-package.
--target-exec=TOOLCHAIN=CMD (در صورت عدم وجود از متغیر DUNE_TARGET_EXEC استفاده می‌شود)
دستور واسط (wrapper) برای اجرای باینری‌های هدف هنگام کامپایل متقاطع (cross-compiling). قالب: TOOLCHAIN=CMD (برای نمونه: 'windows=wine').
--terminal-persistence=MODE
تغییر نحوه نمایش گزارش نتایج ساخت در کنسول بین ساخت‌های مجدد در حالت --watch. حالت‌های پشتیبانی‌شده: preserve، clear-on-rebuild، clear-on-rebuild-and-flush-history.
--trace-file=FILE
خروجی داده‌های ردگیری در قالب catapult (سازگار با chrome://tracing).
--verbose
مشابه --display verbose
--version
نمایش اطلاعات نسخه.
--watch-exclusions=REGEX
افزودن یک عبارت باقاعده POSIX برای مستثنی کردن دایرکتوری‌های منطبق از دستور `dune build --watch`. گزینه --watch-exclusions می‌تواند برای تعیین چندین استثنا تکرار شود. همچنین نقطه-ویرگول (;) می‌تواند به‌عنوان جداکننده به کار رود. اگر هیچ استثنایی تعیین نشود، یک مجموعه استثنای استاندارد اعمال می‌شود؛ اما اگر یک یا چند گزینه --watch-exclusions مشخص شود، هیچ‌یک از استثناهای پیش‌فرض استاندارد استفاده نخواهند شد. استثناهای استاندارد عبارتند از: ^_opam /_opam ^_esy /_esy ^\.#.* /\.#.* ~$ ^#[^#]*#$ /#[^#]*#$ ^4913$ /4913$ /.git /.hg :/windows
--workspace=FILE (در صورت عدم وجود از متغیر DUNE_WORKSPACE استفاده می‌شود)
استفاده از این فایل فضای کاری مشخص به‌جای جستجو برای آن.
-x VAL (در صورت عدم وجود از متغیر DUNE_CROSS_TARGET استفاده می‌شود)
کامپایل متقاطع با استفاده از این زنجیره ابزار (toolchain).

برای دریافت راهنما در مورد یک دستور خاص از `dune COMMAND --help' استفاده کنید.

دستور dune upgrade با مقادیر زیر خارج می‌شود:

0
در صورت موفقیت.
1
در صورت بروز خطا.
130
در صورتی که با یک سیگنال متوقف شود.

این متغیرهای محیطی بر اجرای upgrade تأثیر می‌گذارند:

دایرکتوری ساخت مشخص‌شده. در صورت مشخص نشدن، پیش‌فرض _build است
فعال یا غیرفعال کردن کش Dune (یکی از مقادیر disabled، enabled-except-user-rules یا enabled). مقدار پیش‌فرض `enabled-except-user-rules' است.
بررسی تکرارپذیری ساخت از طریق اجرای مجدد قواعد تصادفی انتخاب‌شده و مقایسه نتایج آن‌ها با مقادیر ذخیره‌شده در کش Dune. نکته: افزایش احتمال این بررسی‌ها فرایند ساخت را کند می‌کند. احتمال پیش‌فرض صفر است، یعنی هیچ قاعده‌ای بررسی نمی‌شود.
حالت ذخیره‌سازی کش Dune (یکی از مقادیر auto، hardlink یا copy). پیش‌فرض `hardlink' است.
کامپایل متقاطع با استفاده از این زنجیره ابزار.
همیشه لاگ‌های استاندارد هنگام ساخت بسته‌ها چاپ شود
دستور شل مورد استفاده برای مقایسه فایل‌ها. برای غیرفعال کردن چاپ تفاوت‌ها از - استفاده کنید.
غیرفعال کردن تمام قواعد ارتقا
فعال‌سازی ابزار دقیق توسط BACKENDS. مقدار BACKENDS فهرستی از نام‌های کتابخانه‌ها است که با کاما از هم جدا شده‌اند و هر یک باید یک بک‌اند ابزار دقیق را مشخص کنند.
عدم اجرای هم‌زمان بیش از JOBS دستور. مقدار JOBS باید یک عدد صحیح مثبت یا auto برای تشخیص خودکار تعداد هسته‌ها (پیش‌فرض) باشد.
نمایه ساخت. در صورت مشخص نشدن dev، یا در صورت تنظیم بودن -p برابر با release خواهد بود.
استفاده از این دایرکتوری به‌عنوان ریشه فضای کاری به‌جای حدس زدن آن. توجه داشته باشید که این گزینه تفسیر اهداف مشخص‌شده در خط فرمان را تغییر نمی‌دهد. این گزینه صرفاً برای اسکریپت‌ها در نظر گرفته شده است.
حالت ایزوله‌سازی پیش‌فرض مورد استفاده. (گزینه --sandbox را ببینید)
ذخیره مکان اصلی سورس‌کد در فراداده‌های dune-package.
دستور واسط برای اجرای باینری‌های هدف هنگام کامپایل متقاطع. قالب: TOOLCHAIN=CMD (برای نمونه: 'windows=wine').
استفاده از این فایل فضای کاری مشخص به‌جای جستجو برای آن.

گزارش‌های اشکال را در نشانی https://github.com/ocaml/dune/issues بررسی کنید.

dune(1)

Dune 3.24.2