buildEnv

buildEnv یک derivation حاوی پوشه‌ها و پیوندهای نمادین (symlinks) می‌سازد که شباهت به چیدمان پروفایل دارد، جایی که فهرستی از درایویشن‌ها یا مسیرهای انبار نصب می‌شوند.

برخلاف symlinkJoin، buildEnv توجه ویژه‌ای به خروجی‌ها برای پیوند دادن دارد و به طور پیش‌فرض تداخل‌های محتوایی را در سراسر مسیرها بررسی می‌کند. یک مورد استفاده معمول برای buildEnv ساخت غلاف‌های محیطی است، مانند یک مفسر به همراه ماژول‌ها یا یک برنامه به همراه افزونه‌ها. برای مثال، python.withPackage بر پایه buildEnv است.

آرگومان‌ها

buildEnv علاوه بر یک مجموعه ویژگی ساده، آرگومان‌های نقطه-ثابت (buildEnv (finalAttrs: {'{'}'{'{'}'{'}'} {'{'}'{'}'}'{'}'})) را نیز می‌پذیرد.

مگر در مواردی که خلاف آن ذکر شده باشد، آرگومان‌ها را می‌توان مستقیماً با استفاده از <pkg>.overrideAttrs بازنشانی کرد.

buildEnv استفاده از ویژگی‌های ساختاریافته ({'{'}'{'{'}'{'}'} __structuredAttrs = true; {'{'}'{'}'}'{'}'}) را الزام می‌کند.

• name یا pname و version (الزامی): نام محیط.

• paths (الزامی): درایویشن‌ها یا مسیرهای انبار جهت ایجاد پیوند نمادین ("نصب").

  عناصر می‌توانند هر شیء مسیرمانندی باشند که طی درون‌گذاری رشته به یک مسیر انبار تبدیل می‌شوند. اولویت هر مسیر از <path>.meta.priority گرفته می‌شود و در صورت عدم تنظیم، به lib.meta.defaultPriority بازمی‌گردد.

  آرگومان paths به عنوان صفت passthru.paths منتقل می‌شود تا از آلودگی پیش‌بینی‌نشده‌ی زمینه جلوگیری کند. passthru.paths را می‌توان با <pkg>.overrideAttrs بازنشانی کرد.

• extraOutputsToInstall (پیش‌فرض: [ ]): خروجی‌های بسته که علاوه بر آنچه meta.outputsToInstall مشخص می‌کند، شامل می‌شوند.

• includeClosures (پیش‌فرض: false): اینکه آیا بستارها (closures) مربوط به تمامی مسیرهای ورودی شامل شوند یا خیر. فهرست مسیرهای بستار با writeClosure ساخته می‌شود. آن‌ها با اولویت پایین‌تر و بدون نمایش استثناهای زمان ساخت نصب می‌شوند.

• extraPrefix (پیش‌فرض: ""): نتیجه را در پوشه‌ی "$out${'{'}'{'{'}'{'}'}extraPrefix{'{'}'{'}'}'{'}'}" ریشه می‌دهد، مانند "/share".

• ignoreCollisions (پیش‌فرض: false): در صورت بروز تداخل‌های محتوایی، فرآیند ساخت شکست نخورد.

• checkCollisionContents (پیش‌فرض: true): اگر تداخلی وجود داشت، بررسی می‌کند که آیا محتوا و دسترسی‌ها تطابق دارند یا خیر؛ و تنها در صورت عدم تطابق، خطای تداخل ایجاد می‌کند.

• ignoreSingleFileOutputs (پیش‌فرض: false): در صورت وجود خروجی‌های تک‌فایلی، فرآیند ساخت شکست نخورد.

• manifest (پیش‌فرض: ""): فایل مانیفست (در صورت وجود). یک پیوند نمادین به صورت $out/manifest به آن ایجاد خواهد شد.

• pathsToLink (پیش‌فرض: [ "/" ]): مسیرهایی (نسبت به هر عنصر از paths) که می‌خواهیم پیوند نمادین داشته باشند (مثلاً ["/bin"]). هر فایلی خارج از پوشه‌های این فهرست، در محیط تولیدشده پیوند نمادین نخواهد شد.

• postBuild (پیش‌فرض: ""): دستورات Bash که پس از ساخت درخت پیوند نمادین اجرا می‌شوند.

• passthru و meta (پیش‌فرض: {'{'}'{'{'}'{'}'} {'{'}'{'}'}'{'}'}): صفات پشتیبانی‌شده توسط stdenv.mkDerivation که به builtins.derivation منتقل نمی‌شوند.

• derivationArgs (پیش‌فرض: {'{'}'{'{'}'{'}'} {'{'}'{'}'}'{'}'}): آرگومان‌های اضافی stdenv.mkDerivation مانند nativeBuildInputs/buildInputs برای وابستگی‌های postBuild و قلاب‌های راه‌اندازی (setup hooks).

  derivationArgs به stdenv.mkDerivation منتقل نمی‌شود. صفات آن را مستقیماً از طریق <pkg>.overrideAttrs بازنشانی کنید و مستقیماً از طریق finalAttrs به آن‌ها ارجاع دهید.

استثناهای زمان ساخت

شرایطی وجود دارد که در آن‌ها paths مشخص‌شده ممکن است چیدمان پروفایل معقولی ایجاد نکند. به طور پیش‌فرض، سازنده به محض تشخیص این استثناها با خطا مواجه می‌شود. buildEnv آرگومان‌هایی را برای تنظیم دقیق یا نادیده گرفتن برخی استثناها ارائه می‌دهد.

برخورد مسیرها

برخورد مسیرها زمانی رخ می‌دهد که فایل‌های ارائه‌شده توسط دو یا چند مسیر خروجی با اولویت یکسان با یکدیگر هم‌پوشانی داشته باشند، به‌طوری‌که چیدمان پروفایل حاصل، بالقوه تحت تأثیر ترتیب عناصر paths قرار گیرد. این امر در چندین مورد استفاده نامطلوب است، مانند زمانی که paths با ادغام ماژول‌های Nix تعیین می‌شود.

اگر آرگومان checkCollisionContents برابر true باشد، سازنده بررسی می‌کند که آیا مسیرهای دارای هم‌پوشانی محتوا و حالت (mode) یکسانی دارند یا خیر، و تنها در غیر این صورت با خطا مواجه می‌شود.

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

علاوه بر نادیده گرفتن این استثنا با ignoreCollisions، می‌توان اولویت بسته‌ها و مسیرهای انبار متداخل را نیز تنظیم کرد. مسیرهای انبار می‌توانند اولویت را به این صورت مشخص کنند

{
  outPath = <path>;
  meta.priority = <priority>;
}

همچنین توابع کتابخانه Nixpkgs مرتبط با lib.meta.setPrio روی یک مجموعه ویژگی رشته‌مانند ({'{'}'{'{'}'{'}'} outPath = <path>; {'{'}'{'}'}'{'}'}) نیز اعمال می‌شوند.

خروجی‌های تک‌فایلی

وقتی یک مسیر خروجی به جای یک پوشه، یک تک‌فایل ارائه می‌دهد، به طور ذاتی نمی‌تواند در چیدمان نتیجه ادغام شود. تمام بسته‌های قابل کشف باید meta.outputsToInstall خود را به درستی پیکربندی کنند، تا خروجی‌های تک‌فایلی در یک پروفایل نصب نشوند.

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