گزینه‌های عمومی ساخت (Generic build options)

-ccontrol-file

فایل اصلی کنترل منبع را برای خواندن اطلاعات مشخص می‌کند. مقدار پیش‌فرض debian/control است. اگر به صورت نام مسیر نسبی داده شود، به عنوان مسیری شروع‌شده از دایرکتوری سطح بالای درخت منبع تفسیر می‌شود.

-lchangelog-file

فایل گزارش تغییرات (changelog) را برای خواندن اطلاعات مشخص می‌کند. مقدار پیش‌فرض debian/changelog است. اگر به صورت نام مسیر نسبی داده شود، به عنوان مسیری شروع‌شده از دایرکتوری سطح بالای درخت منبع تفسیر می‌شود.

-Fchangelog-format

قالب فایل changelog را مشخص می‌کند. برای اطلاعات درباره قالب‌های جایگزین، dpkg-parsechangelog(1) را ببینید.

--format=value

استفاده از قالب ارائه‌شده برای ساخت بسته منبع (از نسخه 1.14.17 dpkg). این گزینه بر هر قالبی که در debian/source/format مشخص شده باشد برتری دارد.

-Vname=value

تنظیم یک متغیر جایگزینی خروجی. برای بررسی متغیرهای جایگزینی خروجی، deb-substvars(5) را ببینید.

-Tsubstvars-file

خواندن متغیرهای جایگزینی در substvars-file؛ حالت پیش‌فرض عدم خواندن هیچ فایلی است. این گزینه می‌تواند چند بار برای خواندن متغیرهای جایگزینی از چندین فایل استفاده شود (از نسخه 1.15.6 dpkg).

-Dfield=value

جایگزینی یا افزودن یک فیلد در فایل کنترل خروجی.

-Ufield

حذف یک فیلد از فایل کنترل خروجی.

-Zcompression, --compression=compression

مشخص کردن فشرده‌سازی مورد استفاده برای بایگانی‌های tarball و فایل‌های diff ایجادشده (--compression از نسخه 1.15.5 dpkg). توجه داشته باشید که این گزینه باعث فشرده‌سازی مجدد tarballهای موجود نمی‌شود، بلکه تنها بر فایل‌های جدید اثر می‌گذارد. مقادیر پشتیبانی‌شده عبارتند از: gzip، bzip2، lzma و xz. مقدار پیش‌فرض برای قالب‌های 2.0 و جدیدتر xz، و برای قالب 1.0 gzip است. قالب xz تنها از نسخه 1.15.5 dpkg پشتیبانی می‌شود.

-zlevel, --compression-level=level

سطح فشرده‌سازی مورد استفاده (--compression-level از نسخه 1.15.5 dpkg). همانند -Z تنها بر فایل‌های تازه ساخته‌شده اثر می‌گذارد. مقادیر پشتیبانی‌شده عبارتند از: 1 تا 9، best و fast. مقدار پیش‌فرض برای gzip و bzip2 برابر 9، و برای xz و lzma برابر 6 است.

-i[regex], --diff-ignore[=regex]

می‌توانید یک عبارت باقاعده پرل (perl regex) برای تطبیق با فایل‌هایی که می‌خواهید از فهرست فایل‌های diff فیلتر شوند، مشخص کنید (--diff-ignore از نسخه 1.15.6 dpkg). (این فهرست توسط دستور find ایجاد می‌شود.) (اگر بسته منبع به عنوان بسته منبع نسخه 3 با استفاده از VCS ساخته می‌شود، می‌توان از این گزینه برای نادیده گرفتن تغییرات کامیت‌نشده روی فایل‌های خاص استفاده کرد. استفاده از -i.* همه آن‌ها را نادیده می‌گیرد.)

گزینه -i به تنهایی این تنظیم را با یک regex پیش‌فرض فعال می‌کند (و هر تغییری که قبلاً با --extend-diff-ignore روی regex پیش‌فرض اعمال شده را حفظ می‌کند) که فایل‌ها و دایرکتوری‌های کنترلی رایج‌ترین سامانه‌های کنترل نسخه، فایل‌های پشتیبان، swap و دایرکتوری‌های خروجی ساخت Libtool را فیلتر می‌کند. تنها یک regex فعال می‌تواند وجود داشته باشد؛ در میان چندین گزینه -i، تنها آخرین مورد اعمال خواهد شد.

این گزینه در حذف فایل‌های اضافی که ممکن است در diff قرار گیرند بسیار مفید است، برای مثال اگر منبع خود را در یک سامانه کنترل نسخه نگهداری می‌کنید و می‌خواهید از یک checkout برای ساخت بسته منبع استفاده کنید بدون اینکه فایل‌ها و دایرکتوری‌های اضافی معمول (مانند CVS/، .cvsignore، .svn/) در آن گنجانده شوند. عبارت باقاعده پیش‌فرض از قبل بسیار جامع است، اما اگر نیاز به جایگزینی آن دارید، لطفاً توجه داشته باشید که به طور پیش‌فرض می‌تواند با هر بخشی از مسیر تطبیق یابد؛ بنابراین اگر می‌خواهید با ابتدای نام فایل یا تنها با کل نام فایل تطبیق یابد، باید لنگرهای لازم (مانند ‘(^|/)’، ‘($|/)’) را خودتان ارائه دهید.

--extend-diff-ignore=regex

عبارت باقاعده پرل مشخص‌شده، مقدار پیش‌فرض مورد استفاده توسط --diff-ignore و مقدار فعلی آن (در صورت تنظیم) را گسترش می‌دهد (از نسخه 1.15.6 dpkg). این کار با افزودن رشته “|regex” به مقدار موجود انجام می‌شود. استفاده از این گزینه در debian/source/options برای مستثنی کردن برخی فایل‌های خودکار تولیدشده از تولید خودکار وصله بسیار مناسب است.

-I[file-pattern], --tar-ignore[=file-pattern]

اگر این گزینه مشخص شود، این الگو هنگام فراخوانی دستور tar(1) برای تولید فایل .orig.tar یا .tar به گزینه --exclude آن پاس داده می‌شود (--tar-ignore از نسخه 1.15.6 dpkg). برای نمونه، -ICVS باعث می‌شود tar هنگام تولید فایل .tar.gz دایرکتوری‌های CVS را نادیده بگیرد. این گزینه می‌تواند چندین بار تکرار شود تا الگوهای متعددی برای مستثنی شدن فهرست شوند.

گزینه -I به خودی خود گزینه‌های --exclude پیش‌فرضی اضافه می‌کند که فایل‌ها و دایرکتوری‌های کنترلی رایج‌ترین سامانه‌های کنترل نسخه، فایل‌های پشتیبان، swap و دایرکتوری‌های خروجی ساخت Libtool را فیلتر می‌کنند.

توجه: اگرچه -i و -I اهداف مشابهی دارند، اما ساختار و معنای بسیار متفاوتی دارند. گزینه -i تنها می‌تواند یک‌بار مشخص شود و یک عبارت باقاعده سازگار با پرل دریافت می‌کند که با مسیر نسبی کامل هر فایل سنجیده می‌شود. گزینه -I می‌تواند چندین بار مشخص شود و یک الگوی نام فایل با وایلدکاردهای شل دریافت می‌کند. الگو هم بر مسیر نسبی کامل و هم بر هر بخش از مسیر به صورت جداگانه اعمال می‌شود. معنای دقیق گزینه --exclude در tar تا حدی پیچیده است؛ برای مستندات کامل پیوند https://www.gnu.org/software/tar/manual/tar.html#wildcards را ببینید.

عبارت باقاعده و الگوهای پیش‌فرض برای هر دو گزینه در خروجی دستور --help قابل مشاهده است.

گزینه‌های عمومی استخراج (Generic extract options)

--no-copy

عدم کپی کردن tarballهای اصلی در کنار بسته منبع استخراج‌شده (از نسخه 1.14.17 dpkg).

--no-check

عدم بررسی امضاها و چکسام‌ها قبل از باز کردن بسته (از نسخه 1.14.17 dpkg).

--no-overwrite-dir

عدم بازنویسی دایرکتوری استخراج در صورتی که از قبل وجود داشته باشد (از نسخه 1.18.8 dpkg).

--no-vendor-certs

عدم استفاده از دسته‌کلیدهای گواهی مختص توزیع‌کننده (vendor).

پشتیبانی‌شده از نسخه 1.23.0 dpkg.

--signer-certs=keyring

استفاده از این keyring حاوی گواهی‌های امضاکننده هنگام اعتبارسنجی امضای بسته‌های منبع.

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

پشتیبانی‌شده از نسخه 1.23.0 dpkg.

--require-valid-signature

امتناع از باز کردن بسته منبع اگر حاوی امضای OpenPGP قابل اعتبارسنجی نباشد (از نسخه 1.15.0 dpkg)، چه با دسته‌کلیدهای عرضه‌شده توسط کاربر با --signer-certs و چه با یکی از دسته‌کلیدهای مختص توزیع‌کننده (شامل هرگونه دسته‌کلید توزیع‌کننده والد در صورت مرتبط بودن).

--require-strong-checksums

امتناع از باز کردن بسته منبع اگر حاوی هیچ چکسام قدرتمندی نباشد (از نسخه 1.18.7 dpkg). در حال حاضر تنها چکسامی که قدرتمند تلقی می‌شود SHA-256 است.

--ignore-bad-version

تبدیل بررسی نادرست بودن نسخه بسته منبع به یک هشدار غیرمهلک (از نسخه 1.17.7 dpkg). این گزینه تنها باید هنگام استخراج بسته‌های منبع قدیمی با نسخه‌های مخدوش، صرفاً برای سازگاری با گذشته استفاده شود.

گزینه‌های عمومی کلی (Generic general options)

--threads-max=threads

تنظیم حداکثر تعداد رشته‌ها (threads) مجاز برای برنامه‌های فشرده‌سازی که از عملیات چندرشته‌ای پشتیبانی می‌کنند (از نسخه 1.21.14 dpkg).

-q

فعال کردن حالت بی‌صدا (quiet) برای سرکوب هشدارها.

قالب: 1.0 (Format: 1.0)

یک بسته منبع در این قالب شامل یک فایل .orig.tar.gz مرتبط با یک .diff.gz، یا یک فایل منفرد .tar.gz است (که در حالت دوم گفته می‌شود بسته بومی یا native است). به صورت اختیاری، tarball اصلی ممکن است با یک امضای بالادستی جداگانه .orig.tar.gz.asc همراه باشد که استخراج آن از نسخه 1.18.5 dpkg پشتیبانی می‌شود.

توجه: در برخی توزیع‌ها (vendors)، dpkg طوری دستکاری شده که منابع بومی با نسخه‌های غیربومی را مجاز بداند که این امر باعث ناهمگونی و سردرگمی بیشتر در این مفهوم شده و علاوه بر این معمولاً تله‌ای برای خطاهای تصادفی است.

استخراج

استخراج یک بسته بومی، صرفاً استخراج ساده یک tarball واحد در دایرکتوری مقصد است. استخراج یک بسته غیربومی ابتدا با باز کردن .orig.tar.gz و سپس اعمال وصله (patch) موجود در فایل .diff.gz انجام می‌شود. مهر زمانی (timestamp) تمام فایل‌های وصله‌شده به زمان استخراج بسته منبع بازنشانی می‌شود (این کار از ناهماهنگی مهر زمانی که هنگام وصله شدن فایل‌های خودکار تولیدشده رخ می‌دهد جلوگیری می‌کند). فایل diff می‌تواند فایل‌های جدید بسازد (کل دایرکتوری debian از این طریق ساخته می‌شود) اما نمی‌تواند فایل‌ها را حذف کند (فایل‌های خالی باقی خواهند ماند) و نمی‌تواند پیوندهای نمادین ایجاد یا ویرایش کند.

ساخت

ساخت یک بسته بومی صرفاً ایجاد یک tarball واحد از دایرکتوری منبع است. ساخت یک بسته غیربومی شامل استخراج tarball اصلی در یک دایرکتوری مجزای “.orig” و تولید مجدد .diff.gz با مقایسه دایرکتوری directory بسته منبع با دایرکتوری .orig است.

گزینه‌های ساخت (با --build):

اگر دومین آرگومان غیرگزینه‌ای عرضه شود، باید نام دایرکتوری منبع اصلی یا فایل tar باشد یا در صورتی که بسته مختص دبیان باشد و بنابراین فاقد diffهای دبیانی‌سازی باشد، یک رشته خالی باشد. اگر آرگومان دومی عرضه نشود، dpkg-source بسته به آرگومان‌های -sX به دنبال فایل tar منبع اصلی package_upstream-version.orig.tar.gz یا دایرکتوری منبع اصلی directory.orig خواهد گشت.

گزینه‌های -sa، -sp، -sk، -su و -sr فایل‌های tar یا دایرکتوری‌های موجود را بازنویسی نخواهند کرد. اگر بازنویسی مد نظر باشد، باید به جای آن‌ها از -sA، -sP، -sK، -sU و -sR استفاده شود.

-sk

مشخص می‌کند که منبع اصلی به عنوان یک فایل tar انتظار می‌رود، که به طور پیش‌فرض package_upstream-version.orig.tar.extension است. این گزینه این منبع اصلی را به عنوان یک فایل tar در جای خود باقی می‌گذارد، یا اگر قبلاً در دایرکتوری جاری نباشد آن را در دایرکتوری جاری کپی می‌کند. این بایگانی tarball برای تولید diff در دایرکتوری directory.orig باز خواهد شد.

-sp

همانند -sk، اما پس از اتمام کار دایرکتوری را دوباره حذف می‌کند.

-su

مشخص می‌کند که منبع اصلی به عنوان یک دایرکتوری انتظار می‌رود، که به طور پیش‌فرض package-upstream-version.orig است، و dpkg-source یک بایگانی منبع اصلی جدید از روی آن خواهد ساخت.

-sr

همانند -su، اما آن دایرکتوری را پس از استفاده حذف خواهد کرد.

-ss

مشخص می‌کند که منبع اصلی هم به عنوان دایرکتوری و هم به عنوان فایل tar در دسترس است. دستور dpkg-source از دایرکتوری برای ایجاد diff و از فایل tar برای ساخت .dsc استفاده خواهد کرد. این گزینه باید با احتیاط استفاده شود - اگر دایرکتوری و فایل tar مطابقت نداشته باشند، یک بایگانی منبع معیوب تولید خواهد شد.

-sn

مشخص می‌کند که به دنبال هیچ منبع اصلی نگردد و فایل diff تولید نکند. دومین آرگومان، در صورت ارائه، باید یک رشته خالی باشد. این گزینه برای بسته‌های مختص دبیان استفاده می‌شود که منبع بالادستی جداگانه‌ای ندارند و در نتیجه فاقد diffهای دبیانی‌سازی هستند.

-sa یا -sA

مشخص می‌کند که به دنبال بایگانی منبع اصلی به عنوان یک فایل tar یا یک دایرکتوری بگردد - آرگومان دوم، در صورت وجود، می‌تواند هر یک از این دو یا رشته خالی باشد (که معادل استفاده از -sn است). اگر یک فایل tar یافت شود، آن را برای ایجاد diff باز کرده و سپس حذف می‌کند (معادل -sp)؛ اگر یک دایرکتوری یافت شود، آن را برای ایجاد منبع اصلی بسته‌بندی کرده و سپس حذف می‌کند (معادل -sr)؛ اگر هیچ‌کدام یافت نشود، فرض می‌کند که بسته فاقد diffهای دبیانی‌سازی است و تنها یک بایگانی منبع سرراست دارد (معادل -sn). اگر هر دو یافت شوند، در صورتی که -sA مشخص شده باشد dpkg-source دایرکتوری را نادیده گرفته و آن را بازنویسی می‌کند (معادل -sP) یا در صورتی که -sa مشخص شده باشد خطایی صادر می‌کند. گزینه -sa حالت پیش‌فرض است.

--abort-on-upstream-changes

اگر diff تولیدشده شامل تغییراتی در فایل‌های خارج از زیردایرکتوری debian باشد، فرآیند ناموفق می‌شود (از نسخه 1.15.8 dpkg). این گزینه در debian/source/options مجاز نیست اما می‌تواند در debian/source/local-options استفاده شود.

گزینه‌های استخراج (با --extract):

در تمام موارد، هرگونه درخت منبع اصلی موجود حذف خواهد شد.

-sp

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

-su

درخت منبع اصلی را باز می‌کند.

-sn

اطمینان حاصل می‌کند که منبع اصلی نه در دایرکتوری جاری کپی شود و نه باز گردد. با این حال هر درخت منبع اصلی موجود در دایرکتوری جاری حذف می‌شود.

تمام گزینه‌های -sX مانعة‌الجمع هستند. اگر بیش از یکی را مشخص کنید، تنها آخرین مورد استفاده خواهد شد.

--skip-debianization

از اعمال diff دبیان بر روی منابع بالادستی صرف‌نظر می‌کند (از نسخه 1.15.1 dpkg).

قالب: 2.0 (Format: 2.0)

پشتیبانی از استخراج از نسخه 1.13.9 dpkg، و پشتیبانی از ساخت از نسخه 1.14.8 dpkg. همچنین با نام wig&pen شناخته می‌شود. این قالب برای استفاده گسترده توصیه نمی‌شود؛ قالب “3.0 (quilt)” جایگزین آن شده است. قالب Wig&pen نخستین مشخصات یک قالب بسته منبع نسل جدید بود.

رفتار این قالب مشابه قالب “3.0 (quilt)” است، جز اینکه از یک فهرست صریح وصله‌ها استفاده نمی‌کند. تمام فایل‌های موجود در debian/patches/ که با عبارت باقاعده پرل [\w-]+ تطبیق داشته باشند باید وصله‌های معتبری باشند: آن‌ها در زمان استخراج اعمال می‌شوند.

هنگام ساخت یک بسته منبع جدید، هرگونه تغییر در منبع بالادستی در وصله‌ای به نام zz_debian-diff-auto ذخیره می‌شود.

قالب: 3.0 (بومی) (Format: 3.0 (native))

پشتیبانی‌شده از نسخه 1.14.17 dpkg. این قالب گسترشی از قالب بسته بومی تعریف‌شده در قالب 1.0 است. این قالب از تمامی روش‌های فشرده‌سازی پشتیبانی کرده و به طور پیش‌فرض هرگونه فایل و دایرکتوری مختص سامانه‌های کنترل نسخه و همچنین بسیاری از فایل‌های موقت را نادیده می‌گیرد (مقدار پیش‌فرض مرتبط با گزینه -I در خروجی --help را ببینید).

توجه: در برخی توزیع‌ها، dpkg طوری دستکاری شده که منابع بومی با نسخه‌های غیربومی را مجاز بداند که این امر باعث ناهمگونی و سردرگمی بیشتر در این مفهوم شده و علاوه بر این معمولاً تله‌ای برای خطاهای تصادفی است.

قالب: 3.0 (quilt) (Format: 3.0 (quilt))

پشتیبانی‌شده از نسخه 1.14.17 dpkg. یک بسته منبع در این قالب دست‌کم شامل یک tarball اصلی (.orig.tar.ext که در آن ext می‌تواند gz، bz2، lzma و xz باشد) و یک tarball دبیان (.debian.tar.ext) است. همچنین می‌تواند شامل tarballهای اصلی اضافی باشد (.orig-addon.tar.ext). بخش addon تنها می‌تواند شامل نویسه‌های الفبایی-عددی (‘a-zA-Z0-9’) و خط تیره (‘-’) باشد. به صورت اختیاری هر tarball اصلی می‌تواند همراه با یک امضای بالادستی جداگانه باشد (.orig.tar.ext.asc و .orig-addon.tar.ext.asc)؛ استخراج از نسخه 1.17.20 dpkg و ساخت از نسخه 1.18.5 dpkg پشتیبانی می‌شود.

استخراج

ابتدا tarball اصلی استخراج می‌شود، سپس تمام tarballهای اصلی اضافی در زیردایرکتوری‌هایی با نام بخش addon از نام فایل آن‌ها استخراج می‌گردند (هر دایرکتوری از پیش موجود جایگزین می‌شود). سپس tarball دبیان، پس از حذف دایرکتوری debian از پیش موجود، در ریشه دایرکتوری منبع استخراج می‌شود. توجه داشته باشید که tarball دبیان باید حاوی یک زیردایرکتوری debian باشد، اما می‌تواند شامل فایل‌های باینری خارج از آن دایرکتوری نیز باشد (گزینه --include-binaries را ببینید).

سپس تمام وصله‌های فهرست‌شده در debian/patches/vendor.series یا debian/patches/series اعمال می‌شوند که در آن vendor نام با حروف کوچک توزیع‌کننده فعلی، یا در صورت عدم تعریف توزیع‌کننده برابر با debian خواهد بود. اگر فایل اول استفاده شود و فایل دوم وجود نداشته باشد (یا یک پیوند نمادین باشد)، فایل دوم با یک پیوند نمادین به فایل اول جایگزین می‌شود. این کار برای ساده‌سازی استفاده از quilt برای مدیریت مجموعه‌وصله‌ها در نظر گرفته شده است. فایل‌های series مختص توزیع‌کننده با این هدف طراحی شده‌اند که امکان مرتب‌سازی شاخه‌های توسعه متعدد بر اساس توزیع‌کننده را به روشی اعلانی فراهم کنند، به جای اینکه این مدیریت به صورت کدنویسی باز در debian/rules انجام شود. این به ویژه زمانی مفید است که منبع باید به صورت شرطی وصله شود، زیرا فایل‌های تحت تاثیر فاقد پشتیبانی داخلی انسداد شرطی هستند. با این حال توجه داشته باشید با اینکه dpkg-source فایل‌های series حاوی گزینه‌های صریح برای اعمال وصله (که روی هر خط پس از نام فایل وصله و با یک یا چند فاصله قرار دارند) را به درستی تجزیه می‌کند، اما آن گزینه‌ها را نادیده می‌گیرد و همیشه انتظار وصله‌هایی را دارد که بتوان با گزینه -p1 دستور patch آن‌ها را اعمال کرد. بنابراین هنگام مواجهه با چنین گزینه‌هایی هشداری صادر می‌کند و فرآیند ساخت به احتمال زیاد ناموفق خواهد بود.

توجه داشته باشید که lintian(1) هنگام استفاده از series توزیع‌کننده به دلیل یک تصمیم مناقشه‌برانگیز مختص دبیان هشدارهای بدون شرطی صادر می‌کند که نباید بر هیچ کاربرد خارجی اثر بگذارد؛ برای بی‌صدا کردن این هشدارها، می‌توان از نمایه lintian دبیان با پاس دادن «--profile dpkg» به lintian(1) استفاده کرد.

مهر زمانی تمام فایل‌های وصله‌شده به زمان استخراج بسته منبع بازنشانی می‌شود (این کار از ناهماهنگی مهر زمانی که هنگام وصله شدن فایل‌های خودکار تولیدشده رخ می‌دهد جلوگیری می‌کند).

بر خلاف رفتار پیش‌فرض quilt، انتظار می‌رود که وصله‌ها بدون هیچ‌گونه انحراف (fuzz) اعمال شوند. در صورتی که چنین نباشد، باید این وصله‌ها را با quilt بازسازی (refresh) کنید، در غیر این صورت dpkg-source هنگام تلاش برای اعمال آن‌ها با خطا مواجه خواهد شد.

مشابه رفتار پیش‌فرض quilt، وصله‌ها می‌توانند فایل‌ها را نیز حذف کنند.

اگر برخی وصله‌ها در حین استخراج اعمال شده باشند، فایل .pc/applied-patches ایجاد می‌شود.

ساخت

تمام tarballهای اصلی یافت‌شده در دایرکتوری جاری، با همان منطق باز کردن بسته، در یک دایرکتوری موقت استخراج می‌شوند، دایرکتوری debian در دایرکتوری موقت کپی می‌شود و تمام وصله‌ها به جز وصله خودکار (debian-changes-version یا debian-changes، بسته به --single-debian-patch) اعمال می‌شوند. دایرکتوری موقت با دایرکتوری بسته منبع مقایسه می‌شود. اگر diff خالی نباشد، فرآیند ساخت ناموفق می‌شود مگر اینکه از --single-debian-patch یا --auto-commit استفاده شده باشد، که در این صورت diff در وصله خودکار ذخیره می‌شود. اگر وصله خودکار ایجاد یا حذف شود، به فایل series و متادیتای quilt افزوده یا از آن‌ها حذف می‌شود.

هرگونه تغییر در یک فایل باینری در فایل diff قابل بازنمایی نیست و بنابراین منجر به شکست خواهد شد، مگر اینکه نگه‌دارنده عمداً تصمیم گرفته باشد آن فایل باینری تغییریافته را در tarball دبیان بگنجاند (با فهرست کردن آن در debian/source/include-binaries). همچنین اگر در زیردایرکتوری debian فایل‌های باینری پیدا شود ساخت بسته با شکست مواجه می‌شود، مگر اینکه از طریق debian/source/include-binaries مجاز شده باشند.

سپس از دایرکتوری به‌روزشده debian و فهرست باینری‌های اصلاح‌شده برای تولید tarball دبیان استفاده می‌شود.

فایل diff به طور خودکار تولیدشده تغییرات روی فایل‌های سامانه‌های کنترل نسخه و همچنین بسیاری از فایل‌های موقت را شامل نمی‌شود (مقدار پیش‌فرض مرتبط با گزینه -i در خروجی --help را ببینید). به ویژه، دایرکتوری .pc مورد استفاده توسط quilt در حین تولید وصله خودکار نادیده گرفته می‌شود.

توجه: دستور dpkg-source --before-build (و --build) اطمینان حاصل می‌کند که تمام وصله‌های فهرست‌شده در فایل series اعمال شده‌اند تا ساخت بسته همیشه همراه با اعمال تمام وصله‌ها باشد. این کار با یافتن وصله‌های اعمال‌نشده انجام می‌شود (وصله‌هایی که در فایل series فهرست شده‌اند اما در .pc/applied-patches نیستند)، و اگر اولین وصله در آن مجموعه بدون خطا قابل اعمال باشد، همه آن‌ها را اعمال می‌کند. از گزینه --no-preparation می‌توان برای غیرفعال کردن این رفتار استفاده کرد.

ثبت تغییرات

--commit [directory] [patch-name] [patch-file]

وصله‌ای متناظر با تغییرات محلی که توسط سیستم وصله quilt مدیریت نمی‌شوند ایجاد کرده و آن را تحت نام patch-name در سیستم وصله ادغام می‌کند. اگر نام ارائه نشود، به صورت تعاملی درخواست خواهد شد. اگر patch-file داده شود، به عنوان وصله متناظر با تغییرات محلی جهت ادغام استفاده می‌شود. پس از ادغام، یک ویرایشگر (نخستین ویرایشگر یافت‌شده از میان sensible-editor، $VISUAL، $EDITOR، vi) اجرا می‌شود تا بتوانید متادیتای موجود در هدر وصله را ویرایش کنید.

ارائه patch-file عمدتاً پس از شکست در ساختی مفید است که این فایل را از قبل تولید کرده باشد، و بر این اساس فایل ارائه‌شده پس از ادغام حذف می‌شود. همچنین توجه داشته باشید که تغییرات موجود در فایل وصله باید از قبل روی درخت اعمال شده باشند و فایل‌های اصلاح‌شده توسط وصله نباید دارای تغییرات ثبت‌نشده تکمیلی باشند.

اگر فرآیند تولید وصله فایل‌های باینری اصلاح‌شده را شناسایی کند، آن‌ها به طور خودکار به debian/source/include-binaries اضافه می‌شوند تا در tarball دبیان قرار گیرند (دقیقاً همان کاری که dpkg-source --include-binaries --build انجام می‌دهد).

گزینه‌های ساخت

--allow-version-of-quilt-db=version

به dpkg-source اجازه می‌دهد در صورتی که نسخه متادیتای quilt نسخه مشخص‌شده باشد، بسته منبع را بسازد حتی اگر dpkg-source از آن مطلع نباشد (از نسخه 1.15.5.4 dpkg). در عمل این گزینه بیان می‌کند که نسخه داده‌شده از متادیتای quilt با نسخه 2 که dpkg-source در حال حاضر پشتیبانی می‌کند سازگار است. نسخه متادیتای quilt در .pc/.version ذخیره شده است.

--include-removal

فایل‌های حذف‌شده را نادیده نمی‌گیرد و آن‌ها را در وصله به طور خودکار تولیدشده می‌گنجاند.

--include-timestamp

مهر زمانی را در وصله به طور خودکار تولیدشده می‌گنجاند.

--include-binaries

افزودن تمام فایل‌های باینری تغییریافته به tarball دبیان. همچنین آن‌ها را به debian/source/include-binaries اضافه می‌کند: آن‌ها در ساخت‌های بعدی به طور پیش‌فرض اضافه خواهند شد و بنابراین دیگر نیازی به این گزینه نخواهد بود.

--no-preparation

تلاشی برای آماده‌سازی درخت ساخت با اعمال وصله‌هایی که ظاهراً اعمال نشده‌اند نمی‌کند (از نسخه 1.14.18 dpkg).

--single-debian-patch

استفاده از debian/patches/debian-changes به جای debian/patches/debian-changes-version برای نام وصله خودکار تولیدشده در طول ساخت (از نسخه 1.15.5.4 dpkg). این گزینه به ویژه زمانی مفید است که بسته در یک VCS نگهداری می‌شود و مجموعه‌وصله را نمی‌توان به طور مطمئن تولید کرد. در عوض، diff فعلی با بالادست باید در یک وصله واحد ذخیره شود. این گزینه در debian/source/local-options قرار می‌گیرد و همراه با یک فایل debian/source/local-patch-header خواهد بود که توضیح می‌دهد چگونه تغییرات دبیان به بهترین شکل بررسی شوند، برای نمونه در سامانه VCS مورد استفاده.

--create-empty-orig

در صورتی که tarball اصلی وجود نداشته باشد و tarballهای اصلی تکمیلی وجود داشته باشند، آن را به طور خودکار خالی می‌سازد (از نسخه 1.15.6 dpkg). این گزینه زمانی کاربرد دارد که بسته منبع صرفاً بسته‌ای از چندین نرم‌افزار بالادستی است و هیچ نرم‌افزار “اصلی” وجود ندارد.

--no-unapply-patches, --unapply-patches

به طور پیش‌فرض، dpkg-source در صورتی که وصله‌ها را در طول --before-build اعمال کرده باشد، در قلاب --after-build به طور خودکار وصله‌ها را لغو اعمال (unapply) می‌کند (--unapply-patches از نسخه 1.15.8 dpkg، و --no-unapply-patches از نسخه 1.16.5 dpkg). این گزینه‌ها به شما امکان می‌دهند فرآیند لغو اعمال وصله‌ها را به اجبار غیرفعال یا فعال کنید. این گزینه‌ها فقط در debian/source/local-options مجاز هستند تا تمام بسته‌های منبع تولیدشده به طور پیش‌فرض رفتار یکسانی داشته باشند.

--abort-on-upstream-changes

اگر یک وصله خودکار ایجاد شده باشد، فرآیند ناموفق می‌شود (از نسخه 1.15.8 dpkg). این گزینه می‌تواند برای اطمینان از اینکه تمام تغییرات پیش از ساخت بسته منبع به درستی در وصله‌های مجزای quilt ثبت شده‌اند استفاده شود. این گزینه در debian/source/options مجاز نیست اما می‌تواند در debian/source/local-options استفاده شود.

--auto-commit

اگر یک وصله خودکار تولید شده باشد فرآیند ناموفق نمی‌شود، بلکه بلافاصله در series مربوط به quilt ثبت می‌گردد.

گزینه‌های استخراج

--skip-debianization

از استخراج tarball دبیان بر روی منابع بالادستی صرف‌نظر می‌کند (از نسخه 1.15.1 dpkg).

--skip-patches

در پایان استخراج، وصله‌ها را اعمال نمی‌کند (از نسخه 1.14.18 dpkg).

قالب: 3.0 (سفارشی) (Format: 3.0 (custom))

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

گزینه‌های ساخت

تمام آرگومان‌های غیرگزینه‌ای به عنوان فایل‌هایی برای ادغام در بسته منبع تولیدشده در نظر گرفته می‌شوند. آن‌ها باید وجود داشته باشند و ترجیحاً در دایرکتوری جاری باشند. حداقل یک فایل باید داده شود.

--target-format=value

الزامی. قالب واقعی بسته منبع تولیدشده را مشخص می‌کند. فایل .dsc تولیدشده حاوی این مقدار در فیلد Format خود خواهد بود و نه “3.0 (custom)”.

قالب: 3.0 (گیت) (Format: 3.0 (git))

پشتیبانی‌شده از نسخه 1.14.17 dpkg. این قالب آزمایشی است.

یک بسته منبع در این قالب شامل یک دسته (bundle) واحد از یک مخزن گیت .git برای نگهداری منبع یک بسته است. همچنین ممکن است یک فایل .gitshallow وجود داشته باشد که بازبینی‌ها را برای کلون کم‌عمق (shallow) گیت فهرست می‌کند.

استخراج

بسته bundle به عنوان یک مخزن گیت در دایرکتوری مقصد کلون می‌شود. اگر یک فایل gitshallow وجود داشته باشد، به صورت .git/shallow در داخل مخزن گیت کلون‌شده نصب می‌شود.

توجه داشته باشید که به طور پیش‌فرض در مخزن جدید همان شاخه‌ای checkout می‌شود که در منبع اصلی checkout شده بود. (معمولاً “main”، اما می‌تواند هر شاخه‌ای باشد.) هر شاخه دیگری تحت remotes/origin/ در دسترس خواهد بود.

ساخت

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

دستور git-bundle(1) برای تولید یک بسته bundle از مخزن گیت استفاده می‌شود. به طور پیش‌فرض، تمام شاخه‌ها و برچسب‌های موجود در مخزن در بسته گنجانده می‌شوند.

گزینه‌های ساخت

--git-ref=ref

امکان مشخص کردن یک ref گیت را برای گنجاندن در bundle گیت فراهم می‌کند. استفاده از این گزینه رفتار پیش‌فرض گنجاندن تمام شاخه‌ها و برچسب‌ها را غیرفعال می‌کند. می‌تواند چندین بار مشخص شود. مقدار ref می‌تواند نام یک شاخه یا برچسب برای گنجاندن باشد. همچنین می‌تواند هر پارامتری باشد که به git-rev-list(1) داده می‌شود. برای نمونه، جهت گنجاندن تنها شاخه اصلی، از --git-ref=main استفاده کنید. برای گنجاندن تمام برچسب‌ها و شاخه‌ها، به جز شاخه خصوصی، از --git-ref=--all --git-ref=^private استفاده کنید.

--git-depth=number

یک کلون کم‌عمق با تاریخچه‌ای کوتاه‌شده به تعداد مشخص‌شده از بازبینی‌ها ایجاد می‌کند.

قالب: 3.0 (bzr) (Format: 3.0 (bzr))

پشتیبانی‌شده از نسخه 1.14.17 dpkg. این قالب آزمایشی است. یک tarball واحد حاوی مخزن bzr تولید می‌کند.

استخراج

فایل tarball باز می‌شود و سپس از bzr برای checkout شاخه جاری استفاده می‌شود.

ساخت

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

سپس بخش مربوط به VCS از دایرکتوری منبع در یک دایرکتوری موقت کپی می‌شود. پیش از بسته‌بندی این دایرکتوری موقت در یک tarball، پاک‌سازی‌های مختلفی برای صرفه‌جویی در فضا انجام می‌شود.

عدم تعیین قالب منبع در debian/source/format

فایل debian/source/format همیشه باید وجود داشته باشد و قالب منبع مورد نظر را مشخص کند. برای سازگاری با نسخه‌های گذشته، در صورتی که فایل وجود نداشته باشد، قالب “1.0” فرض می‌شود، اما نباید به این موضوع اتکا کنید: در آینده dpkg-source طوری اصلاح خواهد شد که در صورت عدم وجود این فایل با خطا متوقف شود.

دلیل این امر آن است که قالب “1.0” دیگر قالب توصیه‌شده نیست، شما معمولاً باید یکی از قالب‌های جدیدتر (“3.0 (quilt)” یا “3.0 (native)”) را انتخاب کنید اما dpkg-source این کار را به طور خودکار برای شما انجام نخواهد داد. اگر می‌خواهید همچنان از قالب قدیمی استفاده کنید، باید صریحاً آن را مشخص کرده و عبارت “1.0” را در debian/source/format قرار دهید.

وصله (diff) فایل‌های بالادستی زیر را تغییر می‌دهد

هنگام استفاده از قالب منبع “1.0”، معمولاً تغییر مستقیم فایل‌های بالادستی ایده بدی است زیرا تغییرات در فایل .diff.gz پنهان و عمدتاً نامستند باقی می‌مانند. در عوض باید تغییرات خود را به عنوان وصله در دایرکتوری debian ذخیره کرده و در زمان ساخت آن‌ها را اعمال کنید. برای پرهیز از این پیچیدگی می‌توانید از قالب “3.0 (quilt)” نیز استفاده کنید که این قابلیت را به صورت بومی ارائه می‌دهد.

نمی‌توان تغییر اعمال‌شده در file را بازنمایی کرد

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

فایل خالی جدیداً ایجاد‌شده file در diff بازنمایی نخواهد شد

فایل‌های خالی را نمی‌توان با فایل‌های وصله ایجاد کرد. بنابراین این تغییر در بسته منبع ثبت نمی‌شود و به شما در این مورد هشدار داده می‌شود.

حالت اجرایی perms فایل file در diff بازنمایی نخواهد شد

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

حالت ویژه perms فایل file در diff بازنمایی نخواهد شد

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

debian/source/format

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

debian/source/include-binaries

این فایل شامل فهرستی از مسیرهای فایل‌های باینری (یک مورد در هر خط) نسبت به دایرکتوری ریشه منبع است که باید در tarball دبیان گنجانده شوند. فاصله‌های ابتدایی و انتهایی حذف می‌شوند. خطوطی که با ‘#’ آغاز می‌شوند کامنت بوده و نادیده گرفته می‌شوند. خطوط خالی نادیده گرفته می‌شوند.

debian/source/options

این فایل شامل فهرستی از گزینه‌های طولانی است که باید به طور خودکار به ابتدای مجموعه گزینه‌های خط فرمان در فراخوانی dpkg-source --build یا dpkg-source --print-format اضافه شوند. گزینه‌هایی مانند --compression و --compression-level برای این فایل بسیار مناسب هستند.

هر گزینه باید در یک خط جداگانه قرار گیرد. خطوط خالی و خطوطی که با ‘#’ شروع می‌شوند نادیده گرفته می‌شوند. پیشوند ‘--’ باید حذف شود و گزینه‌های کوتاه مجاز نیستند. فاصله‌های اختیاری در اطراف نماد ‘=’ و نقل‌قول‌های اختیاری در اطراف مقدار مجاز هستند. در اینجا نمونه‌ای از چنین فایلی آورده شده است:

# let dpkg-source create a debian.tar.bz2 with maximal compression
compression = "bzip2"
compression-level = 9
# use debian/patches/debian-changes as automatic patch
single-debian-patch
# ignore changes on config.{sub,guess}
extend-diff-ignore = "(^|/)(config.sub|config.guess)$"

توجه: گزینه‌های format در این فایل پذیرفته نمی‌شوند؛ باید به جای آن از debian/source/format استفاده کنید.

debian/source/local-options

دقیقاً مانند debian/source/options است با این تفاوت که این فایل در بسته منبع تولیدشده گنجانده نمی‌شود. می‌تواند برای ذخیره تنظیمات شخصی متصل به نگه‌دارنده یا به مخزن VCS که بسته منبع در آن نگهداری می‌شود مفید باشد.

debian/source/local-patch-header

debian/source/patch-header

متن آزاد که در بالای وصله خودکار تولیدشده در قالب‌های “2.0” یا “3.0 (quilt)” قرار می‌گیرد. فایل local-patch-header در بسته منبع تولیدشده گنجانده نمی‌شود در حالی که patch-header گنجانده می‌شود.

debian/patches/vendor.series

debian/patches/series

این فایل تمام وصله‌هایی را که باید (به ترتیب مشخص‌شده) بر روی بسته منبع بالادستی اعمال شوند فهرست می‌کند. فاصله‌های ابتدا و انتها حذف می‌شوند. مقدار vendor نام با حروف کوچک توزیع‌کننده فعلی خواهد بود، یا در صورتی که هیچ توزیع‌کننده‌ای تعریف نشده باشد برابر با debian است. اگر فایل series مختص توزیع‌کننده وجود نداشته باشد، از فایل series بدون توزیع‌کننده استفاده خواهد شد. خطوطی که با ‘#’ شروع می‌شوند کامنت بوده و نادیده گرفته می‌شوند. خطوط خالی نادیده گرفته می‌شوند. خطوط باقی‌مانده با یک نام فایل وصله (نسبت به دایرکتوری debian/patches/) تا اولین نویسه فاصله یا انتهای خط آغاز می‌شوند. گزینه‌های اختیاری quilt می‌توانند تا انتهای خط یا تا اولین ‘#’ که پیش از آن یک یا چند فاصله باشد (که شروع یک کامنت تا پایان خط را نشان می‌دهد) قرار گیرند.