dpkg-maintscript-helper(1) dpkg suite dpkg-maintscript-helper(1)

dpkg-maintscript-helper - تسهیل‌کننده عملیات اسکریپت‌های نگهدارنده بسته

dpkg-maintscript-helper command [parameter...] -- maint-script-parameter...

این برنامه برای اجرا در اسکریپت‌های نگهدارنده بسته (maintainer scripts) طراحی شده است تا وظایفی را انجام دهد که dpkg به دلیل تصمیمات طراحی یا محدودیت‌های فعلی، هنوز نمی‌تواند آن‌ها را به طور پیش‌فرض مدیریت کند.

بسیاری از این وظایف نیازمند اقدامات هماهنگ از سوی چندین اسکریپت نگهدارنده (preinst، postinst، prerm و postrm) هستند. برای جلوگیری از بروز خطا، کافی است همان فراخوانی در تمام اسکریپت‌ها قرار داده شود؛ برنامه رفتار خود را به طور خودکار بر اساس متغیر محیطی DPKG_MAINTSCRIPT_NAME و آرگومان‌های اسکریپت‌های نگهدارنده که باید بعد از خط تیره دوگانه (--) ارسال شوند، تطبیق خواهد داد.

این برنامه در dpkg نسخه 1.15.7 معرفی شد.

آخرین نسخه‌ای از بسته را مشخص می‌کند که ارتقا از آن باید این عملیات را فعال سازد. محاسبه دقیق prior-version بسیار حائز اهمیت است تا حتی اگر کاربر بسته را با یک نسخه محلی بازسازی (rebuild) کرده باشد، عملیات به درستی انجام گیرد. اگر prior-version خالی باشد یا حذف شود، عملیات در هر ارتقا امتحان خواهد شد (توجه: ایمن‌تر است که نسخه مشخص شود تا عملیات تنها یک بار انجام گیرد).

اگر فایل پیکربندی (conffile) در چندین نسخه ارائه نشده باشد و شما اکنون در حال اصلاح اسکریپت‌های نگهدارنده برای پاکسازی فایل منسوخ‌شده هستید، prior-version باید بر اساس نسخه بسته‌ای باشد که هم‌اکنون در حال آماده‌سازی آن هستید، نه اولین نسخه‌ای از بسته که فاقد فایل پیکربندی بوده است. این موضوع به همین ترتیب برای تمامی اقدامات دیگر نیز صدق می‌کند.

به عنوان مثال، برای یک فایل پیکربندی که در نسخه 2.0-1 یک بسته حذف شده است، prior-version باید روی 2.0-1~ تنظیم شود. این کار باعث می‌شود حتی اگر کاربر نسخه قبلی 1.0-1 را به عنوان 1.0-1local1 بازسازی کرده باشد، فایل پیکربندی حذف گردد. یا اگر بسته‌ای مسیری را از یک پیوند نمادین (ارائه‌شده در نسخه 1.0-1) به یک دایرکتوری (ارائه‌شده در نسخه 2.0-1) تغییر دهد، اما تبدیل واقعی را در اسکریپت‌های نگهدارنده نسخه 3.0-1 انجام دهد، باید prior-version را روی 3.0-1~ تنظیم کند.

نام بسته‌ای که مالک مسیر(ها) است. هنگامی که بسته دارای مشخصه «Multi-Arch: same» باشد، این پارامتر باید شامل شناسه معماری باشد، در غیر این صورت معمولاً نباید شامل شناسه معماری باشد (زیرا از ارتقای متقابل [cross-grades] یا تغییر از حالت وابسته به معماری به معماری all یا برعکس جلوگیری می‌کند). اگر این پارامتر خالی باشد یا درج نشود، از متغیرهای محیطی DPKG_MAINTSCRIPT_PACKAGE و DPKG_MAINTSCRIPT_ARCH (تنظیم‌شده توسط dpkg هنگام اجرای اسکریپت‌های نگهدارنده) برای تولید نام بسته مشخص‌شده با معماری استفاده خواهد شد.
--
تمام پارامترهای اسکریپت‌های نگهدارنده باید پس از -- به این برنامه ارسال شوند.

هنگام ارتقای یک بسته، اگر یک فایل پیکربندی (conffile - فایل پیکربندی‌ای که dpkg باید تغییرات کاربر در آن را حفظ کند) در نسخه جدیدتر وجود نداشته باشد، dpkg آن را به طور خودکار حذف نخواهد کرد. دو دلیل اصلی برای این کار وجود دارد؛ اول اینکه ممکن است فایل پیکربندی به صورت تصادفی حذف شده باشد و نسخه بعدی آن را بازگرداند، و کاربران نمی‌خواهند تغییراتشان از بین برود. دوم این است که به بسته‌ها اجازه داده شود فایل‌ها را از یک conffile تحت مدیریت dpkg به فایلی تحت مدیریت اسکریپت‌های نگهدارنده بسته (معمولاً با ابزاری مانند debconf یا ucf) منتقل کنند.

این بدان معناست که اگر قرار است بسته‌ای یک فایل پیکربندی را تغییر نام داده یا حذف کند، باید صراحتاً این کار را انجام دهد و می‌توان از dpkg-maintscript-helper برای پیاده‌سازی حذف و انتقال بی‌نقص و امن فایل‌های پیکربندی در اسکریپت‌های نگهدارنده استفاده کرد.

توجه: این کار در بیشتر موارد می‌تواند با پرچم "remove-on-upgrade" در DEBIAN/conffiles جایگزین شود (از dpkg نسخه 1.20.6 به بعد)؛ به deb-conffiles(5) مراجعه کنید.

اگر یک فایل پیکربندی به طور کامل حذف شود، باید از روی دیسک پاک گردد، مگر اینکه کاربر آن را تغییر داده باشد. اگر تغییرات محلی وجود داشته باشد، باید حفظ شوند. اگر ارتقای بسته لغو شود (abort)، فایل پیکربندی که به تازگی منسوخ شده است نباید ناپدید شود.

تمام این موارد با قرار دادن قطعه‌کد شل زیر در اسکریپت‌های نگهدارنده preinst، postinst و postrm پیاده‌سازی می‌شود:


dpkg-maintscript-helper rm_conffile \
conffile prior-version package -- "$@"

در اینجا conffile نام فایل پیکربندی مورد نظر برای حذف است.

پیاده‌سازی فعلی: در اسکریپت preinst، بررسی می‌شود که آیا فایل پیکربندی تغییر کرده است یا خیر، و اگر تغییر نکرده باشد نام آن به conffile.dpkg-remove و در صورت تغییر به conffile.dpkg-backup تغییر می‌یابد. در postinst، فایل دوم به conffile.dpkg-bak تغییر نام یافته و به عنوان مرجع نگهداری می‌شود زیرا شامل تغییرات کاربر است، اما فایل اول حذف خواهد شد. اگر ارتقای بسته با خطا متوقف شود، postrm فایل پیکربندی اصلی را بازگردانی می‌کند. هنگام پاکسازی کامل (purge)، اسکریپت postrm فایل .dpkg-bak نگهداری‌شده تا آن زمان را نیز حذف خواهد کرد.

اگر یک فایل پیکربندی از یک مکان به مکان دیگری منتقل شود، باید اطمینان حاصل کنید که هرگونه تغییری را که کاربر ایجاد کرده است نیز انتقال می‌دهید. این ممکن است در ابتدا یک تغییر ساده در اسکریپت preinst به نظر برسد، اما منجر به این خواهد شد که dpkg از کاربر بخواهد ویرایش‌های فایل پیکربندی را تأیید کند، حتی اگر خود کاربر مسئول آن ویرایش‌ها نبوده باشد.

تغییر نام امن را می‌توان با قرار دادن قطعه‌کد شل زیر در اسکریپت‌های نگهدارنده preinst، postinst و postrm پیاده‌سازی کرد:


dpkg-maintscript-helper mv_conffile \
old-conffile new-conffile prior-version package -- "$@"

پارامترهای old-conffile و new-conffile به ترتیب نام قدیم و جدید فایل پیکربندی برای تغییر نام هستند.

پیاده‌سازی فعلی: در preinst بررسی می‌شود که آیا فایل پیکربندی تغییر کرده است یا خیر؛ اگر بله در جای خود باقی می‌ماند وگرنه به old-conffile.dpkg-remove تغییر نام می‌یابد. در هنگام پیکربندی، postinst فایل old-conffile.dpkg-remove را حذف کرده و در صورت موجود بودن old-conffile، آن را به new-conffile تغییر نام می‌دهد. در صورت abort-upgrade یا abort-install، اسکریپت postrm در صورت نیاز old-conffile.dpkg-remove را دوباره به old-conffile بازمی‌گرداند.

هنگام ارتقای یک بسته، dpkg به طور خودکار یک پیوند نمادین را به یک دایرکتوری یا برعکس تبدیل نمی‌کند. تنزل نسخه (downgrade) پشتیبانی نمی‌شود و مسیر همان‌طور که هست رها خواهد شد.

توجه: پیوندهای نمادین و دایرکتوری‌های ایجاد شده در طول این تبدیل‌ها باید در بسته‌های جدید گنجانده شوند، در غیر این صورت dpkg نمی‌تواند آن‌ها را در زمان پاکسازی کامل (purge) حذف کند.

اگر یک پیوند نمادین به یک دایرکتوری واقعی تبدیل شود، باید قبل از باز کردن بسته (unpacking) مطمئن شوید که پیوند نمادین حذف شده است. این تغییر در ابتدا ممکن است یک تغییر ساده در اسکریپت preinst به نظر برسد، اما در صورت سفارشی‌سازی محلی پیوند نمادین توسط مدیر سیستم یا هنگام تنزل نسخه بسته، مشکلاتی ایجاد خواهد کرد.

تغییر نام امن را می‌توان با قرار دادن قطعه‌کد شل زیر در اسکریپت‌های نگهدارنده preinst، postinst و postrm پیاده‌سازی کرد:


dpkg-maintscript-helper symlink_to_dir \
pathname old-target prior-version package -- "$@"

در اینجا pathname نام مطلق پیوند نمادین قدیمی است (این مسیر در پایان نصب یک دایرکتوری خواهد بود) و old-target نام مقصد پیوند نمادین قبلی در pathname است. این مقدار می‌تواند یک مسیر مطلق باشد یا نسبی نسبت به دایرکتوری حاوی pathname.

پیاده‌سازی فعلی: در اسکریپت preinst، بررسی می‌شود که آیا پیوند نمادین وجود دارد و به old-target اشاره می‌کند یا خیر؛ اگر اشاره نکند در جای خود باقی می‌ماند، در غیر این صورت به pathname.dpkg-backup تغییر نام می‌یابد. در زمان پیکربندی، postinst فایل pathname.dpkg-backup را حذف می‌کند اگر هنوز یک پیوند نمادین باشد. در صورت abort-upgrade یا abort-install، اسکریپت postrm در صورت نیاز نام pathname.dpkg-backup را به pathname بازمی‌گرداند.

اگر یک دایرکتوری واقعی به یک پیوند نمادین تبدیل شود، باید قبل از باز کردن بسته مطمئن شوید که دایرکتوری حذف شده است. این ممکن است در ابتدا یک تغییر ساده در اسکریپت preinst به نظر برسد، اما در صورتی که دایرکتوری حاوی فایل‌های پیکربندی (conffiles)، مسیرهای متعلق به سایر بسته‌ها یا مسیرهای ایجاد شده به صورت محلی باشد، یا در هنگام تنزل نسخه بسته، مشکلاتی ایجاد خواهد کرد.

تبدیل امن را می‌توان با قرار دادن قطعه‌کد شل زیر در اسکریپت‌های نگهدارنده preinst، postinst و postrm پیاده‌سازی کرد:


dpkg-maintscript-helper dir_to_symlink \
pathname new-target prior-version package -- "$@"

در اینجا pathname نام مطلق دایرکتوری قدیمی است (این مسیر در پایان نصب یک پیوند نمادین خواهد بود) و new-target مقصد پیوند نمادین جدید در pathname است. این مقدار می‌تواند یک مسیر مطلق یا نسبی نسبت به دایرکتوری حاوی pathname باشد.

پیاده‌سازی فعلی: در اسکریپت preinst، بررسی می‌شود که آیا دایرکتوری وجود دارد، فاقد فایل‌های پیکربندی (conffiles)، مسیرهای متعلق به سایر بسته‌ها، یا مسیرهای ایجاد شده به صورت محلی است یا خیر؛ اگر این‌طور نباشد در جای خود باقی می‌ماند، وگرنه به pathname.dpkg-backup تغییر نام یافته و یک دایرکتوری موقت (staging) خالی به نام pathname ایجاد شده و با یک فایل علامت‌گذاری می‌شود تا dpkg بتواند آن را ردیابی کند. در هنگام پیکربندی، اگر pathname.dpkg-backup هنوز یک دایرکتوری باشد و pathname همان دایرکتوری موقت باشد، postinst عملیات تبدیل را به پایان می‌رساند؛ فایل علامت دایرکتوری موقت را حذف کرده، فایل‌های تازه ایجاد شده درون دایرکتوری موقت را به مقصد پیوند نمادین یعنی new-target/ منتقل می‌کند، دایرکتوری موقت خالی‌شده pathname را با یک پیوند نمادین به new-target جایگزین نموده و pathname.dpkg-backup را حذف می‌کند. در صورت abort-upgrade یا abort-install، اسکریپت postrm در صورت نیاز نام pathname.dpkg-backup را مجدداً به pathname بازمی‌گرداند.

هنگام استفاده از یک ابزار کمکی بسته‌بندی، لطفاً بررسی کنید که آیا با dpkg-maintscript-helper یکپارچه‌سازی درونی دارد یا خیر، که ممکن است کار شما را بسیار آسان‌تر کند. برای مثال به dh_installdeb(1) مراجعه نمایید.

با توجه به اینکه dpkg-maintscript-helper در اسکریپت preinst استفاده می‌شود، استفاده بدون قید و شرط از آن نیازمند یک پیش‌نیاز نسخه‌دار (versioned pre-dependency) است تا اطمینان حاصل شود نسخه مورد نیاز از dpkg از قبل باز شده است، مگر اینکه بدانیم در حال ارتقا از انتشار (release) نگارشی هستیم که نسخه مورد نیاز dpkg در آن برآورده شده است. نسخه مورد نیاز به دستور مورد استفاده بستگی دارد: برای rm_conffile و mv_conffile نسخه 1.15.7.2 است، و برای symlink_to_dir و dir_to_symlink نسخه 1.17.14 است. به عنوان مثال، اگر برای ارتقا از نسخه‌ای که dpkg قدیمی‌تر از 1.17.14 داشت نیاز به پشتیبانی از symlink_to_dir داشته باشیم، باید این عبارت را اضافه کنیم:

Pre-Depends: dpkg (>= 1.17.14)

اما در بسیاری از موارد عملیات انجام‌شده توسط برنامه برای بسته حیاتی نیست، و به جای استفاده از یک پیش‌نیاز می‌توانیم برنامه را تنها در صورتی فراخوانی کنیم که بدانیم دستور مورد نیاز توسط dpkg فعلی نصب‌شده در سیستم پشتیبانی می‌شود:


if dpkg-maintscript-helper supports command; then
dpkg-maintscript-helper command ...
fi

دستور supports در صورت موفقیت مقدار 0 و در غیر این صورت مقدار 1 را برمی‌گرداند. دستور supports بررسی می‌کند که آیا متغیرهای محیطی که توسط dpkg تنظیم شده و برای اسکریپت مورد نیاز هستند وجود دارند یا خیر، و در صورتی که محیط ناکافی باشد آن را به عنوان شکست در نظر می‌گیرد.

در صورت تنظیم، به عنوان دایرکتوری ریشه سیستم فایل استفاده خواهد شد.
در صورت تنظیم، به عنوان دایرکتوری داده‌های dpkg استفاده خواهد شد.
حالت رنگی را تنظیم می‌کند (از dpkg نسخه 1.19.1 به بعد). مقادیر پذیرفته‌شده فعلی عبارتند از: auto (پیش‌فرض)، always و never.

dh_installdeb(1).

2026-03-06 1.23.7-dirty