deb-src-control(5) dpkg suite deb-src-control(5)

deb-src-control - فرمت فایل کنترلی قالب بسته‌های سورس دبیان

debian/control

هر بسته سورس دبیان شامل فایل کنترلی قالب سورس «debian/control» است، و فرمت deb822(5) آن ابرمجموعه‌ای از فایل control ارائه‌شده در بسته‌های باینری دبیان محسوب می‌شود؛ به deb-control(5) مراجعه کنید.

این فایل دست‌کم شامل ۲ بند (stanza) است که با یک خط خالی از هم جدا شده‌اند. بند نخست، بند بسته سورس نامیده می‌شود و تمامی اطلاعات درباره بسته سورس را به صورت کلی فهرست می‌کند، در حالی که هر یک از بندهای بعدی، بندهای بسته باینری نامیده می‌شوند و دقیقاً یک بسته باینری را در هر بند توصیف می‌کنند. هر بند حداقل از یک فیلد تشکیل شده است. یک فیلد با نام فیلد آغاز می‌شود، مانند Package یا Section (غیرحساس به بزرگی و کوچکی حروف)، به دنبال آن یک دونقطه، بدنه فیلد (حساس به بزرگی و کوچکی حروف مگر آنکه خلافش ذکر شود) و یک خط جدید قرار می‌گیرد. فیلدهای چندخطی نیز مجاز هستند، اما هر خط تکمیلی، بدون نام فیلد، باید حداقل با یک فاصله (space) شروع شود. محتوای فیلدهای چندخطی معمولاً توسط ابزارها به یک خط متصل می‌گردد (به جز در مورد فیلد Description، به شرح زیر مراجعه کنید). برای درج خطوط خالی درون یک فیلد چندخطی، یک نقطه بعد از فاصله درج کنید. خطوطی که با یک ‘#’ شروع می‌شوند، به عنوان کامنت در نظر گرفته می‌شوند.

مقدار این فیلد، نام بسته سورس است، و باید با نام بسته سورس در فایل debian/changelog مطابقت داشته باشد. نام بسته باید تنها شامل حروف کوچک انگلیسی (a-z)، ارقام (0-9)، علامت‌های مثبت (+) و خط تیره (-) و نقطه (.) باشد. نام بسته‌ها باید حداقل دو کاراکتر طول داشته باشند و با یک کاراکتر الفبایی-عددی کوچک (a-z0-9) آغاز شوند.
باید در قالب «Joe Bloggs <jbloggs@foo.com>» باشد، و به شخصی اشاره دارد که در حال حاضر از بسته نگهداری می‌کند، برعکس پدیدآورنده نرم‌افزار یا بسته‌بند اصلی.
تمامی نام‌ها و نشانی‌های ایمیل همکاران نگه‌دارنده بسته را در همان قالب فیلد Maintainer فهرست می‌کند. چندین همکار نگه‌دارنده باید با یک کاما از یکدیگر جدا شوند.
این فیلد جدیدترین نسخه از استانداردهای سیاست توزیع را که این بسته با آن سازگار است، مستند می‌کند.
 long-description
قالب توصیف بسته سورس به صورت یک چکیده کوتاه در خط اول است (پس از فیلد Description). خطوط بعدی باید برای یک توصیف طولانی‌تر و با جزئیات بیشتر به کار روند. هر خط از توصیف طولانی باید با یک فاصله شروع شود، و خطوط خالی در توصیف طولانی باید شامل یک ‘.’ تنها پس از فاصله ابتدایی باشند.
نشانی URL صفحه خانگی پروژه بالادستی (upstream).
نشانی url سامانه پیگیری اشکالات برای این بسته. قالب مورد استفاده فعلی به صورت bts-type://bts-address است، مانند debbugs://bugs.debian.org. این فیلد معمولاً مورد نیاز نیست.
این فیلد آزمایشی، نام راه‌انداز ساخت مورد استفاده برای ساخت این بسته را مشخص می‌کند. در صورت عدم درج، مقدار driver-name به صورت پیش‌فرض debian-rules خواهد بود.

این فیلد از نسخه dpkg 1.22.7 پشتیبانی می‌شود.

این فیلد برای مشخص کردن این به کار می‌رود که آیا فایل debian/rules برای اجرای برخی از تارگت‌های خود به دسترسی‌های (fake)root نیاز دارد یا خیر، و اگر نیاز دارد در چه زمانی.
تارگت‌های باینری اصلاً به (fake)root نیازی نخواهند داشت. این مقدار در سطح dpkg-build-api بزرگتر یا مساوی ۱، یا از نسخه dpkg 1.22.13 حالت پیش‌فرض است.
تارگت‌های باینری باید همیشه تحت (fake)root اجرا شوند. این مقدار در سطح ۰ dpkg-build-api تا نسخه dpkg 1.22.13، در صورت عدم درج فیلد، پیش‌فرض است؛ افزودن این فیلد با مقدار صریح binary-targets، اگرچه کاملاً ضروری نیست، اما نشان می‌دهد که این بسته برای این نیازمندی مورد تحلیل قرار گرفته است.
این یک فهرست جدا شده با فاصله از کلیدواژه‌ها است که مشخص می‌کنند چه زمانی (fake)root مورد نیاز است.

کلیدواژه‌ها شامل namespace/cases هستند. بخش namespace نمی‌تواند شامل «/» یا فاصله باشد. بخش cases نمی‌تواند شامل فاصله باشد. علاوه بر این، هر دو بخش باید کاملاً از کاراکترهای اسکی (ASCII) قابل چاپ تشکیل شده باشند.

هر ابزار/بسته یک فضای‌نام با نام خودش تعریف می‌کند و تعدادی از مواردی را که در آن به (fake)root نیاز است، ارائه می‌دهد. (به «Implementation provided keywords» در rootless-builds.txt مراجعه کنید).

هنگامی که این فیلد روی یکی از impl-keywords تنظیم شود، ابزار سازنده رابطی را ارائه می‌دهد که برای اجرای یک دستور تحت (fake)root استفاده می‌شود. (به «Gain Root API» در rootless-builds.txt مراجعه کنید).

این فیلدها در صفحه راهنمای dsc(5) توصیف شده‌اند، زیرا از اطلاعات استنتاج‌شده از debian/tests/control تولید شده یا به طور مستقیم در فایل کنترل سورس کپی می‌شوند.
نشانی url مخزن سیستم کنترل نسخه مورد استفاده برای نگهداری این بسته. در حال حاضر موارد پشتیبانی‌شده عبارتند از Arch، Bzr (مخفف Bazaar)، Cvs، Darcs، Git، Hg (مخفف Mercurial)، Mtn (مخفف Monotone) و Svn (مخفف Subversion). معمولاً این فیلد به جدیدترین نسخه بسته اشاره می‌کند، مانند شاخه اصلی (main) یا trunk.
نشانی url یک رابط وب برای مرور مخزن سیستم کنترل نسخه.
نام توزیعی که این بسته از آن سرچشمه می‌گیرد. این فیلد معمولاً مورد نیاز نیست.
این یک فیلد عمومی است که دسته‌ای را بر اساس نرم‌افزاری که نصب می‌کند به بسته اختصاص می‌دهد. برخی از بخش‌های متداول عبارتند از utils، net، mail، text، x11 و غیره.

در صورت عدم درج، مقدار section به صورت پیش‌فرض unknown خواهد بود (از نسخه dpkg 1.22.13).

مقادیر پذیرفته‌شده بر اساس سیاست‌های خاص توزیع تعیین می‌شوند.

اهمیت این بسته را در ارتباط با کل سیستم تعیین می‌کند. اولویت‌های شناخته‌شده عبارتند از required، important، standard، optional، extra و unknown، اما مقادیر دیگر را نیز می‌توان به کار برد.

در صورت عدم درج، مقدار priority به صورت پیش‌فرض optional خواهد بود (از نسخه dpkg 1.22.13).

نحوه اِعمال این مقادیر به سیاست‌های خاص توزیع بستگی دارد.

فهرستی از بسته‌ها که برای امکان ساخت از بسته سورس، باید نصب و پیکربندی شده باشند. این وابستگی‌ها باید هنگام ساخت بسته‌های وابسته به معماری یا مستقل از معماری باینری و بسته‌های سورس برآورده شوند. قرار دادن یک وابستگی در این فیلد اثر کاملاً یکسانی با قرار دادن آن در هر دو فیلد Build-Depends-Arch و Build-Depends-Indep ندارد، زیرا این وابستگی باید هنگام ساخت بسته سورس نیز برآورده شود.
مشابه Build-Depends است، اما آن‌ها تنها هنگام ساخت بسته‌های وابسته به معماری مورد نیاز هستند. در این حالت فیلدهای Build-Depends نیز نصب می‌شوند. این فیلد از نسخه dpkg 1.16.4 پشتیبانی می‌شود؛ جهت ساخت با نسخه‌های قدیمی‌تر dpkg، باید از Build-Depends به جای آن استفاده شود.
مشابه Build-Depends است، اما آن‌ها تنها هنگام ساخت بسته‌های مستقل از معماری مورد نیاز هستند. فیلدهای Build-Depends نیز در این حالت نصب می‌شوند.
فهرستی از بسته‌ها که هنگام ساخت بسته نباید نصب باشند، برای نمونه به این دلیل که با سیستم ساخت مورد استفاده تداخل دارند. قرار دادن یک وابستگی در این فهرست همان اثری را دارد که قرار دادن آن در هر دو فیلد Build-Conflicts-Arch و Build-Conflicts-Indep دارد، همراه با اثر افزوده که برای ساخت‌های منحصراً سورس نیز استفاده می‌شود.
مشابه Build-Conflicts است، اما تنها هنگام ساخت بسته‌های وابسته به معماری اعمال می‌شود. این فیلد از نسخه dpkg 1.16.4 پشتیبانی می‌شود؛ جهت ساخت با نسخه‌های قدیمی‌تر dpkg، باید از Build-Conflicts به جای آن استفاده شود.
مشابه Build-Conflicts است، اما تنها هنگام ساخت بسته‌های مستقل از معماری اعمال می‌شود.

سینتکس فیلدهای Build-Depends، Build-Depends-Arch و Build-Depends-Indep فهرستی از گروه‌هایی از بسته‌های جایگزین است. هر گروه فهرستی از بسته‌ها است که با نماد خط عمودی (یا «pipe»)، ‘|’، از هم جدا شده‌اند. گروه‌ها با کاما ‘,’ از یکدیگر تفکیک می‌شوند، و می‌توانند با یک کامای پایانی خاتمه یابند که هنگام تولید فیلدها برای deb-control(5) حذف خواهد شد (از نسخه dpkg 1.10.14). کاماها باید به عنوان «AND» و پایپ‌ها به عنوان «OR» خوانده شوند، که در این میان پایپ‌ها پیوند محکم‌تری دارند. هر نام بسته می‌تواند به صورت اختیاری با یک توصیف‌کننده معماری که پس از یک دونقطه ‘:’ افزوده می‌شود، سپس به صورت اختیاری با تعیین مشخصات شماره نسخه درون پرانتزهای ‘(’ و ‘)’، یک مشخصه معماری درون کروشه‌های ‘[’ و ‘]’، و یک فرمول محدودیت متشکل از یک یا چند فهرست از نام‌های پروفایل درون علامت‌های کوچکتر/بزرگتر ‘<’ و ‘>’ همراه شود.

سینتکس فیلدهای Build-Conflicts، Build-Conflicts-Arch و Build-Conflicts-Indep فهرستی از نام‌های بسته‌هاست که با کاما از هم جدا شده‌اند، که در آن کاما به عنوان یک «AND» خوانده می‌شود، و فهرست می‌تواند با یک کامای پایانی ختم شود که هنگام تولید فیلدها برای deb-control(5) حذف می‌گردد (از نسخه dpkg 1.10.14). تعیین بسته‌های جایگزین با استفاده از «pipe» پشتیبانی نمی‌شود. هر نام بسته می‌تواند به صورت اختیاری با مشخصات شماره نسخه درون پرانتز، یک مشخصه معماری درون کروشه، و یک فرمول محدودیت شامل یک یا چند فهرست از نام‌های پروفایل درون علامت‌های کوچکتر/بزرگتر همراه شود.

نام توصیف‌کننده معماری می‌تواند یک نام واقعی معماری دبیان (از نسخه dpkg 1.16.5)، any (از نسخه dpkg 1.16.2) یا native (از نسخه dpkg 1.16.5) باشد. در صورت حذف، مقدار پیش‌فرض برای فیلدهای Build-Depends معماری میزبان فعلی است، و مقدار پیش‌فرض برای فیلدهای Build-Conflicts مقدار any است. یک نام واقعی معماری دبیان دقیقاً با همان معماری برای آن نام بسته مطابقت خواهد داشت، مقدار any در صورتی که بسته با Multi-Arch: allowed علامت‌گذاری شده باشد با هر معماری برای آن نام بسته تطبیق می‌یابد، و native در صورتی که بسته با Multi-Arch: foreign علامت‌گذاری نشده باشد، با معماری ساخت جاری مطابقت خواهد داشت.

یک شماره نسخه ممکن است با ‘>>’ آغاز شود که در این صورت هر نسخه بعدی با آن تطبیق دارد، و ممکن است بازنگری بسته‌بندی دبیان (جدا شده با خط تیره) را مشخص کرده یا از آن صرف‌نظر کند. روابط مجاز برای نسخه عبارتند از ‘>>’ برای بزرگتر از، ‘<<’ برای کوچکتر از، ‘>=’ برای بزرگتر یا مساوی، ‘<=’ برای کوچکتر یا مساوی، و ‘=’ برای مساوی.

یک مشخصه معماری از یک یا چند نام معماری تشکیل می‌شود که با فاصله از هم جدا شده‌اند. علامت‌های تعجب (!) ممکن است در ابتدای هر یک از نام‌ها قرار گیرند، که به معنای «NOT» (نفی) است.

یک فرمول محدودیت از یک یا چند فهرست محدودیت تشکیل می‌شود که با فاصله از هم جدا شده‌اند. هر فهرست محدودیت درون علامت‌های کوچکتر/بزرگتر (< و >) قرار می‌گیرد. موارد موجود در فهرست محدودیت، نام‌های پروفایل ساخت هستند که با فاصله از هم جدا شده‌اند و می‌توانند با یک علامت تعجب (!) پیشوند شوند، که به معنای «NOT» است. یک فرمول محدودیت نشان‌دهنده یک عبارت فرم نرمال فصلی (disjunctive normal form) است، بدین معنی که فاصله درون علامت‌های کوچکتر/بزرگتر به عنوان «AND» خوانده می‌شود، و فاصله بین علامت‌های کوچکتر/بزرگتر به عنوان «OR» خوانده می‌شود، مانند «<foo AND bar> OR <quux AND baz>».

توجه داشته باشید که می‌توان از وابستگی به بسته‌های موجود در مجموعه build-essential صرف‌نظر کرد و اعلان تعارض ساخت در برابر آن‌ها غیرممکن است. فهرستی از این بسته‌ها در بسته build-essential موجود است.

این فیلد برای تعیین نام بسته باینری به کار می‌رود. همان محدودیت‌های مربوط به نام بسته سورس در اینجا نیز اعمال می‌شوند.
این فیلد نوع بسته را تعریف می‌کند. udeb برای بسته‌های دارای محدودیت اندازه است که توسط نصاب دبیان (debian installer) استفاده می‌شوند. deb مقدار پیش‌فرض است، و در صورت عدم وجود فیلد فرض می‌شود. ممکن است انواع بیشتری در آینده اضافه شوند.
فهرست معماری مشخص می‌کند که این بسته بر روی چه نوع ماشینی اجرا می‌شود. مقدار باید فهرستی از نام‌های معماری و/یا الگوهای عام (wildcards) جدا شده با فاصله باشد.

مقدار ویژه all، به تنهایی، برای بسته‌هایی در نظر گرفته شده که مستقل از معماری هستند (مانند اسکریپت‌های شل و Perl یا مستندات)، و مقدار ویژه عام any، به تنهایی، برای بسته‌هایی است که وابسته به معماری هستند اما روی همه معماری‌ها اجرا می‌شوند (که با تمامی نام‌های معماری خاص، به جز all، مطابقت دارد). بیشتر بسته‌ها از all یا any استفاده خواهند کرد. برای محدود کردن بسته‌ها به مجموعه‌ای مشخص از معماری‌ها، یک یا چند نام معماری و/یا الگوهای عام معماری را، جدا شده با فاصله مشخص کنید.

یک نام یا الگوی عام معماری باید با یک کاراکتر الفبایی-عددی («0-9a-zA-Z») آغاز شود، و سپس کاراکترهای الفبایی-عددی و خط تیره («-») به دنبال آن بیایند.

برای اطلاعات بیشتر در مورد نام‌ها و الگوهای عام معماری، به dpkg-architecture(1) مراجعه کنید.

این فیلد شرایطی را مشخص می‌کند که بر اساس آن، این بسته باینری ساخته می‌شود یا ساخته نمی‌شود. برای بیان این شرط، از همان سینتکس فرمول محدودیت مربوط به فیلد Build-Depends استفاده می‌شود (شامل علامت‌های کوچکتر/بزرگتر).

اگر بند یک بسته باینری شامل این فیلد نباشد، به طور ضمنی بدین معناست که با تمام پروفایل‌های ساخت (شامل حالتی که هیچ پروفایلی تعریف نشده باشد) ساخته می‌شود.

به بیان دیگر، اگر بند یک بسته باینری با یک فیلد غیرخالی Build-Profiles نشانه‌گذاری شده باشد، این بسته باینری اگر و تنها اگر شرط بیان‌شده در عبارت فرم نرمال عطفی (conjunctive normal form) درست ارزیابی شود، تولید خواهد شد.

این فیلدها در صفحه راهنمای deb-control(5) توصیف شده‌اند، چرا که دقیقاً به فایل کنترل بسته باینری کپی می‌شوند.
مقدار فیلد مشابه در بند بسته سورس را رونویسی (override) می‌کند.

اگر هیچ فیلدی در بند باینری یا سورس وجود نداشته باشد، آنگاه مقدار پیش‌فرض آن unknown خواهد بود (از نسخه dpkg 1.22.13).

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

اگر هیچ فیلدی در بند باینری یا سورس وجود نداشته باشد، آنگاه مقدار پیش‌فرض آن optional خواهد بود (از نسخه dpkg 1.22.13).

مقدار فیلد مشابه در بند بسته سورس را رونویسی می‌کند.
این فیلدها روابط بین بسته‌ها را اعلام می‌کنند. آن‌ها در صفحه راهنمای deb-control(5) مورد بحث قرار گرفته‌اند. هنگامی که این فیلدها در debian/control یافت می‌شوند، می‌توانند به یک کامای پایانی نیز ختم شوند (از نسخه dpkg 1.10.14)، و دارای مشخصات معماری و فرمول‌های محدودیت باشند که همگی هنگام تولید فیلدها برای deb-control(5) ساده‌سازی و کاهش می‌یابند.
این فیلدها توسط debian-installer در بسته‌های udeb استفاده می‌شوند و معمولاً نیازی به آن‌ها نیست. برای جزئیات بیشتر درباره آن‌ها، به https://salsa.debian.org/installer-team/debian-installer/-/raw/master/doc/devel/modules.txt مراجعه کنید.

افزودن فیلدهای اضافی تعریف‌شده توسط کاربر به فایل کنترل مجاز است. ابزارها از این فیلدها صرف‌نظر خواهند کرد. اگر می‌خواهید فیلدها به فایل‌های خروجی، مانند بسته‌های باینری، کپی شوند، باید از یک الگوی نام‌گذاری سفارشی استفاده کنید: فیلدها باید با یک X آغاز شوند، به دنبال آن صفر یا چند حرف از حروف SBC و سپس یک خط تیره قرار گیرد.

فیلد در فایل کنترل بسته سورس ظاهر خواهد شد؛ به dsc(5) مراجعه کنید.

تنها در بند بسته سورس مورد انتظار است.

فیلد در فایل کنترل موجود در بسته باینری ظاهر خواهد شد؛ به deb-control(5) مراجعه کنید.

در بند بسته سورس یا هر بند بسته باینری مجاز است.

فیلد در فایل کنترل بارگذاری (.changes) ظاهر خواهد شد؛ به deb-changes(5) مراجعه کنید.

تنها در بند بسته سورس مورد انتظار است.

توجه داشته باشید که پیشوندهای X[SBC]- هنگام کپی شدن فیلدها به فایل‌های خروجی حذف می‌شوند. یک فیلد XC-Approved-By به صورت Approved-By در فایل changes ظاهر می‌شود و در فایل‌های کنترل بسته باینری یا سورس نمایش داده نخواهد شد.

در نظر داشته باشید که این فیلدهای تعریف‌شده توسط کاربر از فضای‌نام سراسری استفاده خواهند کرد، که ممکن است در نقطه‌ای در آینده با فیلدهای رسمی شناخته‌شده تداخل پیدا کند. برای جلوگیری از چنین وضعیت احتمالی، می‌توانید این فیلدها را با Private- پیشوندگذاری کنید، مانند XB-Private-New-Field.

# Comment.
Source: dpkg
Section: admin
Priority: required
Maintainer: Dpkg Developers <debian-dpkg@lists.debian.org>
# This field is copied to the binary and source packages.
XBS-Upstream-Release-Status: stable
Homepage: https://wiki.debian.org/Teams/Dpkg
Vcs-Browser: https://git.dpkg.org/cgit/dpkg/dpkg.git
Vcs-Git: https://git.dpkg.org/git/dpkg/dpkg.git
Standards-Version: 4.7.3
Build-Depends:
 dpkg-build-api (= 1),
 debhelper-compat (= 13),
 debhelper (>= 13.10~),
 pkgconf,
 libselinux1-dev (>= 1.28-4) [!linux-any],
Package: dpkg-dev
Section: utils
Priority: optional
Architecture: all
# This is a custom field in the binary package.
XB-Mentoring-Contact: Raphael Hertzog <hertzog@debian.org>
Depends:
 libdpkg-perl (= ${source:Version}),
 dpkg (>= 1.14.6),
 binutils,
 bzip2,
 xz-utils,
# This is a comment in the middle of a field value.
 make,
 patch (>= 2.2-1),
 perl-modules,
 perl5,
Recommends:
 build-essential,
 gcc | c-compiler,
Suggests:
 debian-keyring,
Conflicts:
 devscripts (<< 2.10.26),
Replaces:
 manpages-pl (<= 20051117-1),
Provides:
 dpkg-build-api (= 0),
 dpkg-build-api (= 1),
Description: Debian package development tools
 This package provides the development tools (including dpkg-source)
 required to unpack, build and upload Debian source packages.
 .
 Most Debian source packages will require additional tools to build;
 for example, most packages need make and the C compiler gcc.

/usr/share/doc/dpkg/spec/rootless-builds.txt, deb822(5), deb-control(5), deb-version(7), dpkg-source(1)

2026-03-06 1.23.7-dirty