DUNE-RULES(1) Dune Manual DUNE-RULES(1)

dune-rules - برون‌ریزی قوانین ساخت

dune rules [OPTION]… [TARGET]…

برون‌ریزی قوانین Dune برای هدف‌های مشخص‌شده. اگر هیچ هدفی مشخص نشود، تمامی قوانین برون‌ریزی می‌شوند.

با گزینهٔ --deps، تنها وابستگی‌های قوانین منطبق چاپ می‌شوند.

به‌طور پیش‌فرض، خروجی فهرستی از S-expressionها است، یک S-expression به ازای هر قانون. هر S-expression دارای ساختار زیر است:

((deps    (<dependencies>))
 (targets (<targets>))
 (context <context-name>)
 (action  <action>))

<context-name> بافتی (context) است که عمل در آن اجرا می‌شود. اگر عمل مستقل از بافت باشد، این مقدار حذف می‌شود.

<action> عملی است با همان ساختار نحویِ اعمال کاربری، همان‌طور که در راهنما شرح داده شده است.

از --format=json برای برون‌ریزی همین داده‌ها در قالب JSON استفاده کنید.

--action-stderr-on-success=VAL
مشابه --action-stdout-on-success اما به‌جای خروجی استاندارد، برای خطای استاندارد اعمال می‌شود. یک مقدار پیش‌فرض مناسب برای مخازن بزرگ تک‌مخزنی (monorepos) عبارت است از --action-stdout-on-success=swallow --action-stderr-on-success=must-be-empty. این کار تضمین می‌کند که یک ساخت موفق، خروجی «تمیز» و خالی داشته باشد.
--action-stdout-on-success=VAL
نحوهٔ برخورد با خروجی استاندارد اعمال را در صورت موفقیت مشخص می‌کند. مقادیر ممکن عبارتند از: print برای چاپ صرف آن در خروجی Dune، swallow برای نادیده گرفتن کامل آن و must-be-empty برای الزام به اینکه عمل هیچ چیزی چاپ نکرده باشد. با مقدار must-be-empty، اگر عمل چیزی در خروجی استاندارد خود چاپ کند، Dune آن عمل را شکست‌خورده تلقی می‌کند. مقدار پیش‌فرض print است.
--build-info
نمایش اطلاعات ساخت.
--deps
تنها چاپ وابستگی‌های قوانین منطبق.
--display-separate-messages
جدا کردن پیام‌های خطا با یک خط خالی.
--error-reporting=VAL (پیش‌فرض=deterministic)
زمان گزارش خطاهای ساخت را کنترل می‌کند. مقدار early خطاها را به محض کشف شدن گزارش می‌کند. مقدار deterministic خطاها را در پایان ساخت و با ترتیبی مشخص و تکرارپذیر گزارش می‌کند. مقدار twice هر خطا را دو بار گزارش می‌کند: یک بار به محض کشف خطا و بار دیگر در پایان ساخت، با ترتیبی مشخص.
-f, --force
اجبار به اجرای مجدد اعمال مرتبط با نام‌های مستعار (aliases)، حتی اگر وابستگی‌های آن‌ها تغییری نکرده باشد.
--file-watcher=VAL (پیش‌فرض=automatic)
سازوکار تشخیص تغییرات در کد منبع. مقدار automatic باعث می‌شود dune یک برنامهٔ خارجی را برای تشخیص تغییرات اجرا کند. مقدار manual برای اطلاع‌رسانی دستی تغییر فایل‌ها به dune استفاده می‌شود.
--format=FORMAT (پیش‌فرض=sexp)
مقدار FORMAT باید sexp یا json باشد.
-o FILE
هدایت خروجی به یک فایل به‌جای stdout.
--passive-watch-mode
مشابه [--watch]، اما ساخت تنها زمانی آغاز می‌شود که فرمانی از خارج از طریق یک RPC ارسال شود.
-r, --recursive
چاپ تمامی قوانین مورد نیاز برای ساخت وابستگی‌های تعدی‌پذیر (transitive dependencies) اهداف مشخص‌شده.
--sandbox=VAL (در صورت عدم وجود متغیر محیطی DUNE_SANDBOX)
تنظیم حالت محدودسازی (sandboxing). برخی اعمال نیازمند حالت خاصی از محیط ایزوله هستند و بنابراین این تنظیم را نادیده می‌گیرند. مقادیر مجاز عبارتند از: none، symlink، copy، hardlink.
--stop-on-first-error
توقف فرایند ساخت به محض مواجهه با اولین خطا.
-w, --watch
به‌جای پایان دادن به ساخت پس از اتمام، به طور مداوم منتظر تغییرات فایل‌ها می‌ماند.
--wait-for-filesystem-clock
برنامهٔ Dune برای بهبود کارایی ساخت افزایشی، چکیده‌هایی (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)
غیرفعال کردن تمامی قوانین ارتقا.
--display=MODE
کنترل حالت نمایش Dune. برای جزئیات بیشتر به dune-config(5) مراجعه کنید. مقادیر معتبر عبارتند از: progress، verbose، short، quiet یا tui.
--dump-gc-stats=FILE
برون‌ریزی آمار زباله‌روب (GC) در یک فایل پس از اتمام ساخت.
--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)
فعال‌سازی ابزاردقیق‌سازی توسط BACKENDS. مقدار BACKENDS فهرستی جداشده با کاما از نام کتابخانه‌هاست که هر یک باید یک پسانهٔ ابزاردقیق‌سازی تعریف کرده باشند.
-j JOBS (در صورت عدم وجود متغیر محیطی DUNE_JOBS)
عدم اجرای هم‌زمان بیش از JOBS دستور. مقدار JOBS باید یک عدد صحیح مثبت یا auto برای تشخیص خودکار تعداد هسته‌ها (پیش‌فرض) باشد.
--no-buffer
عدم بافر کردن خروجی دستورهای اجراشده توسط dune. به‌طور پیش‌فرض dune خروجی زیردستورها را بافر می‌کند تا از درهم‌آمیختگی خروجی‌ها هنگام اجرای موازی چندین دستور جلوگیری شود. با این حال، این مسئله ممکن است هنگام اشکال‌زدایی آزمون‌های طولانی مشکل‌ساز شود. با گزینهٔ --no-buffer، دستورها دسترسی مستقیم به ترمینال دارند. توجه داشته باشید که در نتیجه خروجی آن‌ها در فایل وقایع (log) ذخیره نخواهد شد. برای جلوگیری از تداخل خروجی‌ها، باید از این گزینه همراه با -j 1 استفاده کنید. علاوه بر این، باید از --verbose نیز استفاده شود تا اطمینان حاصل شود که دستورها پیش از اجرا چاپ می‌شوند.
--no-config
عدم بارگذاری فایل پیکربندی.
--no-print-directory
جلوگیری از نمایش پیام‌های «Entering directory».
--only-packages=PACKAGES
نادیده گرفتن بندهایی (stanzas) که به بسته‌ای ارجاع می‌دهند که در PACKAGES نیست. مقدار PACKAGES فهرستی جداشده با کاما از نام بسته‌هاست. توجه داشته باشید که این کار اثری مشابه حذف بندهای مربوطه از فایل‌های dune دارد. این گزینه عمدتاً برای انتشار نسخه‌ها کاربرد دارد. در طول توسعه، احتمالاً آنچه می‌خواهید ساخت یک هدف خاص <package>.install است.
-p PACKAGES, --for-release-of-packages=PACKAGES (الزامی)
کوتاه‌نوشتی برای --release --pkg=disabled --only-packages PACKAGE. زمانی که پروژه شامل چندین بسته است، باید از این گزینه در فایل‌های <package>.opam خود استفاده کنید تا تنها موارد ضروری ساخته شوند و ساخت‌های تکرارپذیر حاصل گردد.
--pkg=VAL
فعال یا غیرفعال کردن مدیریت بسته. رفتار پیش‌فرض به وجود یا عدم وجود یک دایرکتوری قفل (lock) بستگی دارد.
--profile=VAL (در صورت عدم وجود متغیر محیطی DUNE_PROFILE)
انتخاب نمایهٔ ساخت (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) برای اجرای دودویی‌های هدف هنگام کامپایل متقابل. قالب: TOOLCHAIN=CMD (برای نمونه، 'windows=wine').
--terminal-persistence=MODE
تغییر نحوهٔ نمایش گزارش نتایج ساخت در کنسول میان ساخت‌های متوالی در حالت --watch. حالت‌های پشتیبانی‌شده: preserve، clear-on-rebuild، clear-on-rebuild-and-flush-history.
--trace-file=FILE
خروجی داده‌های ردگیری (trace) در قالب 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 rules با این کدها خارج می‌شود:

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

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

دایرکتوری ساخت مشخص‌شده. در صورت مشخص نشدن، مقدار پیش‌فرض _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