stow(8) User Contributed Perl Documentation stow(8)

stow - مدیریت مزارع پیوندهای نمادین

stow [ گزینهhar32ها ] بسته ...

این صفحه راهنما GNU Stow نسخه 2.4.1 را شرح می‌دهد. این مستندات قطعی برای Stow نیست؛ برای آن، راهنمای info همراه را برای مثال با تایپ "info stow" مشاهده فرمایید.

نرم‌افزار Stow یک مدیر مزرعه پیوندهای نمادین (symlink farm) است که مجموعه‌های متمایزی از نرم‌افزار و/یا داده‌های واقع در دایرکتوری‌های مجزا در فایل‌سیستم را دریافت کرده و کاری می‌کند که همگی آن‌ها در یک درخت دایرکتوری واحد نصب‌شده به نظر برسند.

در اصل Stow برای پاسخ به نیاز مدیریت، ارتقا، نصب و حذف پرونده‌ها در بسته‌های نرم‌افزاری مستقل بدون اشتباه گرفتن آن‌ها با سایر پرونده‌های مشترک در همان فضای فایل‌سیستم متولد شد. به عنوان مثال، سال‌ها پیش کامپایل کردن برنامه‌هایی مانند Perl و Emacs از منبع امری متداول بود. با استفاده از Stow، پوشه /usr/local/bin می‌توانست حاوی پیوندهای نمادین به پرونده‌های موجود در /usr/local/stow/emacs/bin، /usr/local/stow/perl/bin و غیره باشد، و به همین ترتیب به صورت بازگشتی برای هر زیردایرکتوری دیگر مانند .../share، .../man و غیره.

اگرچه این روش برای پیگیری نصب‌های سرتاسری سیستم و نصب‌های خاص هر کاربر از نرم‌افزارهای ساخته‌شده از کد منبع مفید است، اما در زمان‌های اخیر بسته‌های نرم‌افزاری اغلب توسط نرم‌افزارهای مدیریت بسته پیچیده‌تری مانند rpm، dpkg و Nix / GNU Guix، یا مدیران بسته بومی زبان‌های برنامه‌نویسی مانند gem در Ruby، pip در Python، npm در Javascript و غیره مدیریت می‌شوند.

با این حال Stow هنوز نه تنها برای مدیریت بسته‌های نرم‌افزاری، بلکه برای اهداف دیگری مانند تسهیل رویکرد کنترل‌شده‌تر در مدیریت پرونده‌های پیکربندی در دایرکتوری خانگی کاربر، به‌ویژه در ترکیب با سیستم‌های کنترل نسخه استفاده می‌شود.

نرم‌افزار Stow از برنامه Depot در دانشگاه کارنگی ملون الهام گرفته شده است، اما اساساً بسیار ساده‌تر و ایمن‌تر است. در حالی که Depot برای همگام نگه داشتن موارد نیاز به فایل‌های پایگاه‌داده داشت، Stow هیچ وضعیت اضافی بین اجراها ذخیره نمی‌کند، بنابراین هیچ خطری (همانند آنچه در Depot بود) مبنی بر به هم ریختن دایرکتوری‌ها هنگام عدم تطابق سلسله‌مراتب پرونده‌ها با پایگاه‌داده وجود ندارد. همچنین بر خلاف Depot، نرم‌افزار Stow هرگز پرونده‌ها، دایرکتوری‌ها یا پیوندهایی را که در یک دایرکتوری Stow (مثلاً /usr/local/stow/emacs) ظاهر می‌شوند حذف نخواهد کرد، بنابراین بازسازی درخت مقصد (مثلاً /usr/local) همیشه امکان‌پذیر است.

نرم‌افزار Stow به عنوان ترکیبی از یک اسکریپت Perl که یک رابط خط فرمان (CLI) ارائه می‌دهد و یک ماژول بک‌اند Perl که بیشتر کارها را انجام می‌دهد، پیاده‌سازی شده است.

یک "بسته" (package) مجموعه‌ای مرتبط از پرونده‌ها و دایرکتوری‌ها است که مایلید به عنوان یک واحد مدیریت کنید -- مانند Perl یا Emacs -- و باید در یک ساختار دایرکتوری خاص نصب شود -- مثلاً با زیردایرکتوری‌های bin، lib و man.

یک "دایرکتوری مقصد" (target directory) ریشه درختی است که یک یا چند بسته مایلند در آن نصب‌شده به نظر برسند. یک مکان رایج، اما نه تنها مکان ممکن، /usr/local است. مثال‌های این صفحه راهنما از /usr/local به عنوان دایرکتوری مقصد استفاده خواهند کرد.

یک "دایرکتوری stow" ریشه درختی است که شامل بسته‌های مجزا در زیردرخت‌های اختصاصی است. هنگامی که Stow اجرا می‌شود، از دایرکتوری جاری به عنوان دایرکتوری پیش‌فرض stow استفاده می‌کند. مثال‌های این صفحه راهنما از /usr/local/stow به عنوان دایرکتوری stow استفاده می‌کنند، به طوری که بسته‌های مجزا برای مثال /usr/local/stow/perl و /usr/local/stow/emacs خواهند بود.

یک "تصویر نصب" (installation image) چیدمان پرونده‌ها و دایرکتوری‌های مورد نیاز یک بسته نسبت به دایرکتوری مقصد است. بنابراین، تصویر نصب برای Perl شامل موارد زیر است: دایرکتوری bin حاوی perl و a2p (در میان سایرین)؛ دایرکتوری info حاوی مستندات Texinfo؛ دایرکتوری lib/perl حاوی کتابخانه‌های Perl؛ و دایرکتوری man/man1 حاوی صفحات راهنما.

یک "دایرکتوری بسته" (package directory) ریشه درختی است که تصویر نصب یک بسته خاص را در بر دارد. هر دایرکتوری بسته باید در یک دایرکتوری stow قرار گیرد -- برای مثال، دایرکتوری بسته /usr/local/stow/perl باید در دایرکتوری stow به نشانی /usr/local/stow قرار داشته باشد. "نام" یک بسته، نام دایرکتوری آن در دایرکتوری stow است -- مثلاً perl.

بنابراین، فایل اجرایی Perl ممکن است در /usr/local/stow/perl/bin/perl قرار گیرد، جایی که /usr/local دایرکتوری مقصد، /usr/local/stow دایرکتوری stow، /usr/local/stow/perl دایرکتوری بسته، و bin/perl در داخل آن بخشی از تصویر نصب است.

یک "پیوند نمادین" یا symlink یک ارجاع نمادین است. پیوند نمادین می‌تواند "نسبی" یا "مطلق" باشد. پیوند نمادین مطلق یک مسیر کامل را نام می‌برد؛ یعنی مسیری که از / شروع می‌شود. پیوند نمادین نسبی یک مسیر نسبی را مشخص می‌کند؛ یعنی مسیری که از / شروع نمی‌شود. مقصد یک پیوند نمادین نسبی با شروع از دایرکتوری خود پیوند نمادین محاسبه می‌شود. نرم‌افزار Stow تنها پیوندهای نمادین نسبی ایجاد می‌کند.

فرض می‌شود که دایرکتوری stow مقدار متغیر محیطی "STOW_DIR" باشد یا در صورت عدم تنظیم، دایرکتوری جاری در نظر گرفته می‌شود، و فرض می‌شود دایرکتوری مقصد والد دایرکتوری جاری باشد (بنابراین اجرای معمول stow از دایرکتوری /usr/local/stow است). هر بسته داده‌شده در خط فرمان، نام بسته‌ای در دایرکتوری stow است (مثلاً perl). به طور پیش‌فرض، آن‌ها در دایرکتوری مقصد نصب می‌شوند (اما با استفاده از "-D" می‌توان آن‌ها را حذف کرد).

هیچ عملیاتی که فایل‌سیستم را تغییر دهد انجام نده؛ صرفاً نشان بده که چه اتفاقی خواهد افتاد.
دایرکتوری stow را به جای دایرکتوری جاری، روی "DIR" تنظیم کن. این کار همچنین باعث می‌شود دایرکتوری مقصد پیش‌فرض والد "DIR" شود.
دایرکتوری مقصد را به جای والد دایرکتوری stow، روی "DIR" تنظیم کن.
خروجی مشروح توصیف‌کننده کارهایی که Stow انجام می‌دهد را به خروجی خطای استاندارد ارسال کن. سطوح پرگویی از 0 تا 5 است؛ 0 پیش‌فرض است. استفاده از "-v" یا "--verbose" پرگویی را یک واحد افزایش می‌دهد؛ استفاده از --verbose=N آن را روی N تنظیم می‌کند.
بسته‌های پس از این گزینه را در دایرکتوری مقصد مستقر (stow) کن. این عمل پیش‌فرض است و بنابراین اگر فقط در حال استقرار بسته‌ها هستید و ترکیبی از اقدامات stow/delete/restow را انجام نمی‌دهید، می‌توانید آن را نادیده بگیرید.
بسته‌های پس از این گزینه را به جای نصب کردن، از دایرکتوری مقصد حذف (unstow) کن.
استقرار مجدد بسته‌ها (ابتدا حذف پیوندها، سپس استقرار دوباره). این گزینه برای هرس کردن پیوندهای نمادین منسوخ از درخت مقصد پس از به‌روزرسانی نرم‌افزار در یک بسته مفید است.
هشدار! این رفتار به طور ویژه برای تغییر محتویات دایرکتوری stow شما در نظر گرفته شده است. اگر چنین چیزی نمی‌خواهید، این گزینه برای شما مناسب نیست.

هنگام استقرار، اگر مقصدی مشاهده شود که از قبل وجود دارد اما یک فایل معمولی است (و بنابراین متعلق به هیچ بسته stow موجودی نیست)، معمولاً Stow این را به عنوان یک تداخل ثبت کرده و از ادامه کار خودداری می‌کند. این گزینه این رفتار را تغییر می‌دهد به طوری که فایل به همان مکان نسبی در تصویر نصب بسته در دایرکتوری stow منتقل می‌شود، و سپس استقرار طبق روال قبل ادامه می‌یابد. بنابراین عملاً، فایل بدون اینکه محتوایش تغییر کند توسط بسته stow به فرزندی پذیرفته (adopt) می‌شود.

--no-folding
غیرفعال کردن تا کردن (folding) دایرکتوری‌های جدیداً مستقرشده هنگام stow، و تا کردن مجدد دایرکتوری‌های جدیداً قابل تا شدن هنگام unstow.
نادیده گرفتن پرونده‌هایی که به این عبارت باقاعده Perl ختم می‌شوند.
عدم استقرار پرونده‌هایی که با این عبارت باقاعده Perl شروع می‌شوند در صورتی که فایل از قبل در بسته دیگری مستقر شده باشد.
اجبار به استقرار پرونده‌هایی که با این عبارت باقاعده Perl شروع می‌شوند حتی اگر فایل از قبل در بسته دیگری مستقر شده باشد.
فعال کردن مدیریت ویژه برای "dotfileها" (پرونده‌ها یا پوشه‌هایی که نامشان با نقطه شروع می‌شود) در دایرکتوری بسته. اگر این گزینه فعال باشد، Stow یک مرحله پیش‌پردازش برای هر پرونده یا پوشه‌ای که نامش با "dot-" شروع می‌شود اضافه می‌کند و پیشوند "dot-" در نام را با یک نقطه (.) جایگزین می‌نماید. این گزینه زمانی مفید است که Stow برای مدیریت مجموعه‌هایی از dotfileها استفاده می‌شود، تا از پر شدن دایرکتوری بسته از پرونده‌های مخفی جلوگیری شود.

به عنوان مثال، فرض کنید بسته‌ای شامل دو پرونده داریم: stow/dot-bashrc و stow/dot-emacs.d/init.el. با این گزینه، Stow پیوندهای نمادینی از .bashrc به stow/dot-bashrc و از .emacs.d/init.el به stow/dot-emacs.d/init.el ایجاد می‌کند. هر پرونده دیگری که نامش با "dot-" شروع نشود طبق روال معمول پردازش خواهد شد.

نمایش شماره نسخه Stow و خروج.
نمایش نحو دستور Stow و خروج.

عمل پیش‌فرض Stow نصب یک بسته است. این به معنای ایجاد پیوندهای نمادین در درخت مقصد است که به درخت بسته اشاره می‌کنند. نرم‌افزار Stow تلاش می‌کند این کار را با کمترین تعداد پیوند نمادین ممکن انجام دهد؛ به عبارت دیگر، اگر Stow بتواند یک پیوند نمادین واحد ایجاد کند که به کل یک زیردرخت در داخل درخت بسته اشاره کند، آن کار را به جای ایجاد یک دایرکتوری در درخت مقصد و پر کردن آن با پیوندهای نمادین انتخاب خواهد کرد.

به عنوان مثال، فرض کنید هنوز هیچ بسته‌ای در /usr/local نصب نشده است؛ کاملاً خالی است (البته به جز زیردایرکتوری stow). اکنون فرض کنید بسته Perl نصب شده است. یادآوری می‌شود که این بسته شامل دایرکتوری‌های زیر در تصویر نصب خود است: bin؛ info؛ lib/perl؛ man/man1. به جای ایجاد دایرکتوری /usr/local/bin و پر کردن آن با پیوندهای نمادین به ../stow/perl/bin/perl و ../stow/perl/bin/a2p (و غیره)، Stow یک پیوند نمادین منفرد /usr/local/bin ایجاد می‌کند که به stow/perl/bin اشاره دارد. به این ترتیب، ارجاع به /usr/local/bin/perl و /usr/local/bin/a2p همچنان کار می‌کند و پیوندهای نمادین کمتری ایجاد شده است. این فرآیند "تا کردن درخت" (tree folding) نامیده می‌شود، زیرا کل یک زیردرخت درون یک پیوند نمادین واحد "تا" شده است.

برای تکمیل این مثال، Stow همچنین پیوند نمادین /usr/local/info با اشاره به stow/perl/info؛ پیوند نمادین /usr/local/lib با اشاره به stow/perl/lib؛ و پیوند نمادین /usr/local/man با اشاره به stow/perl/man را ایجاد خواهد کرد.

اکنون فرض کنید به جای نصب بسته Perl در یک درخت مقصد خالی، درخت مقصد از ابتدا خالی نیست. در عوض، شامل چندین پرونده و دایرکتوری است که تحت یک فلسفه مدیریت سیستم دیگر نصب شده‌اند. به طور خاص، /usr/local/bin از قبل وجود دارد و یک دایرکتوری است، همانند /usr/local/lib و /usr/local/man/man1. در این حالت، Stow به داخل /usr/local/bin رفته و پیوندهای نمادین به ../stow/perl/bin/perl و ../stow/perl/bin/a2p (غیره) ایجاد می‌کند، و وارد /usr/local/lib شده و پیوند نمادین تا کردن درخت perl را با اشاره به ../stow/perl/lib/perl ایجاد می‌نماید، و الی آخر. به عنوان یک قاعده، زمانی که Stow بتواند یک پیوند نمادین تا کردن درخت ایجاد کند، فقط تا جایی که لازم است در درخت مقصد پایین می‌رود.

اغلب زمانی فرا می‌رسد که یک پیوند نمادین تا کردن درخت باید باز شود (شکافته شود)، زیرا بسته دیگری از یک یا چند زیردایرکتوری تاشده در تصویر نصب خود استفاده می‌کند. این عملیات "شکافتن" (splitting open) یک درخت تاشده نامیده می‌شود. این کار شامل حذف پیوند نمادین اصلی از درخت مقصد، ایجاد یک دایرکتوری واقعی به جای آن، و سپس پر کردن دایرکتوری جدید با پیوندهای نمادین به بسته جدیداً نصب‌شده و به بسته قدیمی که از پیوند نمادین قدیمی استفاده می‌کرد، می‌باشد. به عنوان مثال، فرض کنید پس از نصب Perl در یک /usr/local خالی، می‌خواهیم Emacs را نصب کنیم. تصویر نصب Emacs شامل یک دایرکتوری bin حاوی فایل‌های اجرایی emacs و etags و موارد دیگر است. نرم‌افزار Stow باید کاری کند که این پرونده‌ها در /usr/local/bin نصب‌شده به نظر برسند، اما در حال حاضر /usr/local/bin یک پیوند نمادین به stow/perl/bin است. بنابراین Stow مراحل زیر را انجام می‌دهد: پیوند نمادین /usr/local/bin حذف می‌شود؛ دایرکتوری /usr/local/bin ایجاد می‌شود؛ پیوندهایی از /usr/local/bin به ../stow/emacs/bin/emacs و ../stow/emacs/bin/etags برقرار می‌شود؛ و پیوندهایی از /usr/local/bin به ../stow/perl/bin/perl و ../stow/perl/bin/a2p ایجاد می‌گردد.

هنگام شکافتن یک درخت تاشده، Stow مطمئن می‌شود پیوند نمادینی که در شرف حذف آن است، به داخل یک بسته معتبر در دایرکتوری stow جاری اشاره می‌کند.

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

اگر Stow نیاز به ایجاد یک دایرکتوری یا پیوند نمادین در درخت مقصد داشته باشد و نتواند این کار را انجام دهد چون آن نام در حال حاضر در حال استفاده است و در مالکیت Stow نیست، یک تداخل رخ داده است. بخش "Conflicts" را در راهنمای info ببینید.

هنگامی که گزینه "-D" داده می‌شود، اقدام Stow حذف یک بسته از درخت مقصد است. توجه داشته باشید که Stow چیزی را که "مالک" آن نیست حذف نخواهد کرد. حذف یک بسته به معنای حذف آن از دایرکتوری stow یا کنار گذاشتن درخت بسته نیست.

برای حذف یک بسته، Stow به صورت بازگشتی درخت مقصد را اسکن می‌کند، از دایرکتوری stow (از آنجا که معمولاً یک زیردایرکتوری از درخت مقصد است) و هر دایرکتوری stow دیگری که با آن روبرو می‌شود صرف‌نظر می‌کند (به "Multiple stow directories" در راهنمای info مراجعه فرمایید). هر پیوند نمادینی که بیابد و به بسته در حال حذف اشاره کند برداشته می‌شود. هر دایرکتوری که تنها شامل پیوندهای نمادین به بسته در حال حذف باشد برداشته می‌شود. هر دایرکتوری که پس از حذف پیوندهای نمادین و زیردایرکتوری‌های خالی، تنها شامل پیوندهای نمادین به یک بسته منفرد دیگر باشد، درختی در نظر گرفته می‌شود که قبلاً "تاشده" بوده و سپس "شکافته" شده است. نرم‌افزار Stow با حذف پیوندهای نمادین به بسته باقی‌مانده، حذف دایرکتوری، و سپس پیوند دادن مجدد دایرکتوری به بسته باقی‌مانده، درخت را مجدداً تا می‌کند.

نرم‌افزار Stow گزینه‌های پیش‌فرض خط فرمان را به ترتیب در .stowrc (دایرکتوری جاری) و ~/.stowrc (دایرکتوری خانگی) جستجو می‌کند. اگر هر دو مکان وجود داشته باشند، پرونده‌ها عملاً به یکدیگر الحاق می‌شوند.

اثر گزینه‌ها در پرونده منابع شبیه به افزودن ساده گزینه‌ها به ابتدای خط فرمان است. برای گزینه‌هایی که یک مقدار واحد ارائه می‌دهند، مانند --target یا --dir، گزینه خط فرمان هر گزینه‌ای در پرونده منابع را بازنویسی می‌کند. برای گزینه‌هایی که می‌توانند بیش از یک بار داده شوند، برای مثال --ignore، گزینه‌های خط فرمان و گزینه‌های منابع به یکدیگر الحاق می‌شوند.

متغیرهای محیطی و نویسه مدک (~) برای گزینه‌هایی که مسیر فایل را می‌گیرند بسط داده می‌شوند.

گزینه‌های -D، -R، -S، و هر بسته‌ای که در پرونده منابع فهرست شده باشد نادیده گرفته می‌شوند.

برای اطلاعات بیشتر در مورد نحوه مدیریت پرونده منابع توسط stow، راهنمای info را ببینید.

مستندات کامل stow به صورت یک راهنمای Texinfo نگهداری می‌شود. اگر برنامه‌های info و stow به درستی در سیستم شما نصب شده باشند، دستور

info stow

باید دسترسی به راهنمای کامل را برای شما فراهم کند.

لطفاً اشکالات موجود در Stow را با استفاده از سیستم ردیابی باگ دبیان گزارش دهید.

اشکالات شناخته‌شده در حال حاضر عبارتند از:

  • مشکل دایرکتوری خالی.

    اگر بسته foo شامل یک دایرکتوری خالی باشد -- مثلاً foo/bar -- در این صورت اگر هیچ بسته دیگری زیردایرکتوری bar نداشته باشد، همه چیز به خوبی کار می‌کند. اگر بسته دیگری به نام quux دارای زیردایرکتوری bar باشد، هنگام استقرار، targetdir/bar شکافته می‌شود و محتویات quux/bar به صورت جداگانه مستقر می‌شوند. تا اینجا مشکلی نیست. اما هنگام حذف استقرار (unstowing) بسته quux، پوشه targetdir/bar حذف می‌شود، هرچند foo/bar نیاز دارد که باقی بماند. یک راهکار موقت برای این مشکل، ایجاد یک پرونده به عنوان نگه‌دارنده مکان (placeholder) در foo/bar است. اگر نام آن پرونده را .placeholder بگذارید، پس از رفع این اشکال، یافتن و حذف چنین پرونده‌هایی آسان خواهد بود.

  • هنگام استفاده از چندین دایرکتوری stow (به "Multiple stow directories" در راهنمای info مراجعه فرمایید)، Stow در شکافتن پیوندهای نمادین تا کردن درخت (به "Installing packages" در راهنمای info مراجعه فرمایید) که به یک دایرکتوری stow اشاره دارند که توسط دستور فعلی Stow استفاده نمی‌شود، با شکست مواجه می‌شود. قبل از شکست، باید مقصد پیوند را جستجو کند تا ببیند آیا عنصری از مسیر شامل پرونده .stow است یا خیر. اگر یکی را بیابد، می‌تواند درباره دایرکتوری همکار stow اطلاعات کسب کند تا دفعه بعد که با یک پیوند نمادین تا کردن درخت روبرو شد، جستجوی .stow را کوتاه کند.

این صفحه راهنما در اصل توسط Charles Briscoe-Smith از بخش‌هایی از راهنمای info برنامه Stow ساخته شد و سپس توسط Adam Spiers به قالب POD تبدیل گردید. راهنمای info شامل اطلاعیه زیر است که همان‌طور که می‌گوید، برای این صفحه راهنما نیز صدق می‌کند. متن بخشی با عنوان "GNU General Public License" را می‌توان در پرونده /usr/share/common-licenses/GPL در هر سیستم دبیان یا گنو/لینوکس یافت. اگر به یک سیستم دبیان دسترسی ندارید، یا GPL در آنجا نیست، به بنیاد نرم‌افزار آزاد بنویسید: Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA, 02111-1307, USA.

حق نشر (C) 1993, 1994, 1995, 1996 متعلق به Bob Glickstein <bobg+stow@zanshin.com>؛ 2000, 2001 متعلق به Guillaume Morin؛ 2007 متعلق به Kahlil Hodgson؛ 2011 متعلق به Adam Spiers؛ و دیگران.

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

مجوز کپی و توزیع نسخه‌های تغییریافته این راهنما تحت شرایط تکثیر عین اصل داده شده است، به این شرط که بخش با عنوان "GNU General Public License" نیز همراه با راهنمای اصلاح‌شده گنجانده شود، و به شرطی که کل اثر مشتق‌شده حاصل تحت شرایط اعلامیه مجوزی دقیقاً مشابه با این منتشر شود.

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

2024-09-08 perl v5.38.2