.TH include_server 1 "9 June 2008" .SH "نام (NAME)" include_server.py \- تخمین محافظه‌کارانه وابستگی‌های include برای C/C++ .SH "خلاصه دستور (SYNOPSIS)" .B include_server --port .I INCLUDE_SERVER_PORT [OPTIONS] .SH "توضیحات (DESCRIPTION)" .P اسکریپت include_server.py یک فرایند کارساز include را راه‌اندازی می‌کند. این فرایند به پرس‌وجوهای کلاینت‌های \fBdistcc\fR(1) درباره اینکه چه فایل‌هایی باید در کامپایل‌های C/C++ گنجانده (include) شوند، پاسخ می‌دهد. خود دستور include_server.py به محض ایجاد فرایند کارساز include خاتمه می‌یابد. .PP آرگومان INCLUDE_SERVER_PORT نام سوکتی است که برای تمامی ارتباطات میان کلاینت‌های distcc و کارساز include استفاده می‌شود. دستور \fBpump\fR(1) مسئول ایجاد محل سوکت، ارسال آن به این اسکریپت و فرستادن آن به تمامی کلاینت‌های distcc از طریق متغیر محیطی با نام INCLUDE_SERVER_PORT است. .PP پروتکل مورد استفاده کارساز include از پیاده‌سازی RPC در distcc بهره می‌برد. هر درخواست distcc شامل (۱) پوشه جاری و (۲) فهرست آرگومان‌های دستور کامپایل است. .PP اگر کارساز include قادر به پردازش درخواست باشد، با ارسال فهرستی از مسیرهای فایل به کلاینت distcc پاسخ می‌دهد. این مسیرها مربوط به فایل‌های سورس و سرآیند (header) فشرده‌شده‌ای هستند که از طریق تحلیل include برای کامپایل ضروری تشخیص داده شده‌اند. این فهرست همچنین شامل پیوندهای نمادین و حتی فایل‌های ساختگی (dummy) مورد نیاز کارساز کامپایل است تا نسخه‌ای دقیق از بخش‌های مورد نیاز سیستم‌فایل برای کامپایل ایجاد کند. بدین ترتیب، یک فایل سرآیند مورد نیاز مانند /path/foo.h فشرده شده، تغییر نام یافته و در یک مکان موقت مانند /dev/shm/tmpiAvfGv.include_server-9368-1/path/foo.h.lzo ذخیره می‌شود. کلاینت distcc این فایل‌ها را به کارساز کامپایل منتقل می‌کند، جایی که آن‌ها از حالت فشرده خارج شده و به‌طور موقت سوار (mount) می‌شوند. .PP اگر کارساز include قادر به پردازش درخواست نباشد، یک فهرست خالی به کلاینت distcc بازمی‌گرداند. .PP دو نوع شکست در رابطه با کارساز include وجود دارد. ممکن است کارساز include در محاسبه includeها ناموفق باشد یا به روش‌های دیگری با خطا مواجه شود، بخش \fBنشانه‌ها و مشکلات کارساز INCLUDE (INCLUDE SERVER SYMPTOMS AND ISSUES)\fR را ببینید. همچنین ممکن است کامپایل در کارساز دوردست به دلیل ناکافی بودن بستار include محاسبه‌شده با شکست مواجه شود، اما با تلاش مجدد محلی موفقیت‌آمیز باشد، بخش \fBنشانه‌های مغایرت DISTCC (DISTCC DISCREPANCY SYMPTOMS)\fR را ببینید. .SH "خلاصه گزینه‌ها (OPTION SUMMARY)" گزینه‌های زیر توسط include_server.py پشتیبانی می‌شوند. .TP .B -dPAT, --debug_pattern=PAT بردار بیتی برای فعال‌سازی هشدارها و اشکال‌زدایی 1 = هشدارها 2 = ردیابی برخی توابع سایر توان‌های ۲: به include_server/basics.py مراجعه کنید. .TP .B -e, --email ارسال ایمیل به 'distcc-pump-errors' یا در صورت تعریف، به مقدار متغیر محیطی DISTCC_EMAILLOG_WHOM_TO_BLAME، هنگامی که کارساز include با مشکل مواجه می‌شود. پیش‌فرض عدم ارسال ایمیل است. .TP .B --email_bound NUMBER حداکثر تعداد ایمیل‌های ارسالی (علاوه بر ایمیل نهایی). پیش‌فرض: ۳. .TP .B --no-email عدم ارسال ایمیل. این حالت پیش‌فرض است. .TP .B --path_observation_re=RE صادر کردن پیام هشدار هر زمان که نام یک فایل به یک realpath تطبیق‌یافته با RE (که یک عبارت منظم با نحو پایتون است) تحلیل شود. این گزینه برای پی بردن به اینکه فایل‌های include واقعاً از کجا آمده‌اند مفید است. برای یافتن همه آن‌ها از RE="" استفاده کنید. توجه: هشدارها باید حداقل با -d1 فعال شده باشند. .TP .B --pid_file FILEPATH شناسه فرایند (PID) کارساز include در فایل FILEPATH نوشته می‌شود. این امر به اسکریپتی مانند \fBpump\fR اجازه می‌دهد کارساز include را متوقف کند. .TP .B -s, --statistics چاپ اطلاعات مربوط به تحلیل include در خروجی استاندارد (stdout). .TP .B --stat_reset_triggers=LIST پاک‌سازی حافظه پنهان stat زمانی که برچسب زمانی (timestamp) هر مسیر فایل در LIST تغییر کند یا مسیر فایل ایجاد یا حذف شود. LIST رشته‌ای از مسیرهای فایل است که با دونقطه از هم جدا شده‌اند و احتمالاً شامل الگوهای تطبیق ساده (مطابق با ماژول glob پایتون) است. هر زمان که چنین تغییری رخ دهد، یک هشدار چاپ می‌شود (در صورت فعال بودن هشدارها). این گزینه امکان استثنائات محدودی را برای فرض معمول distcc_pump مبنی بر عدم تغییر فایل‌های سورس در طول ساخت فراهم می‌کند. .TP .B -t, --time چاپ زمان سپری‌شده، زمان کاربر و زمان سیستم در خروجی خطای استاندارد (stderr). .TP .B --unsafe_absolute_includes انجام پیش‌پردازش روی کارساز کامپایل، حتی اگر includeهایی با مسیرهای مطلق مشاهده شوند. به طور معمول کارساز include در صورت شناسایی هرگونه include مطلق، به پیش‌پردازش محلی بازمی‌گردد. بنابراین، این پرچم برای جلوگیری از چنین بازگشت‌هایی در مواردی که includeهای مطلق یک هشدار کاذب هستند، مفید است؛ چه به این دلیل که include مطلق در حین پیش‌پردازش کنار گذاشته می‌شود یا به این دلیل که فایل با مسیر مطلق روی کارسازهای کامپایل وجود دارد. .IP به بیان دقیق‌تر، با --unsafe_absolute_includes مسیرهای مطلق به منظور گردآوری بستار include نادیده گرفته می‌شوند. استفاده از این گزینه ممکن است به نتایج نادرست منجر شود زیرا (۱) ممکن است فایل سرآیند واقعاً در کارساز کامپایل include شود و با نسخه کلاینت متفاوت باشد، (۲) دستورات include آن سرآیند بیشتر تحلیل نمی‌شوند. .IP این گزینه برای کامپایل کدی مفید است که در آن چنین مکان‌های مطلق و ثابت‌شده‌ای از فایل‌های سرآیند درون دستورات شرطی (مانند "#ifdef") قرار دارند که includeها را بی‌اثر می‌کنند. به بیان دقیق‌تر، این includeها باید در طول پیش‌پردازش برای پیکربندی فعلی حذف شوند. در این حالت مسئله وجود فایل سرآیند منتفی است و کامپایل از راه دور معتبر خواهد بود. این وضعیت اغلب در مواردی رخ می‌دهد که چنین includeهایی برای پیکربندی‌های غیرمعمول و متفاوت از پیکربندی فعلی در نظر گرفته شده‌اند. .TP .B --no_force_dirs ایجاد تمامی پوشه‌های استفاده‌شده در یک مسیر include را اجباری نکن. ممکن است در برخی موارد کارایی را بهبود بخشد، اما ساخت‌هایی را که از ساختارهای include مانند "" بدون گنجاندن سایر فایل‌ها در foo/ استفاده می‌کنند، با شکست مواجه خواهد کرد. .TP .B -v, --verify بررسی اینکه آیا فایل‌های موجود در بستار CPP در بستار محاسبه‌شده توسط پردازشگر include گنجانده شده‌اند یا خیر. .TP .B -w, --write_include_closure نوشتن یک فایل .d_approx که تمام فایل‌های include محاسبه‌شده توسط کارساز include را فهرست می‌کند؛ با گزینه -x، علاوه بر آن فایل‌های include محاسبه‌شده توسط CPP را در یک فایل .d_exact می‌نویسد. .TP .B -x, --exact_analysis استفاده از CPP به جای آن، فایل‌های سرآیند سیستم را حذف نکن. .SH "نشانه‌ها و مشکلات کارساز INCLUDE (INCLUDE SERVER SYMPTOMS AND ISSUES)" محتمل‌ترین پیام‌ها و هشدارهایی که ممکن است از پردازشگر include صادر شوند در زیر آورده شده‌اند. .PP .TP .B "Preprocessing locally. Include server not covering: Couldn't determine default system include directories" برای تعیین پوشه‌های سرآیند پیش‌فرض سیستم، کارساز include برای هر زبان مورد نیاز در طول نشست خود یک بار کامپایلر را اجرا می‌کند. این پیام نشان می‌دهد که کامپایلر مشخص‌شده برای distcc روی کلاینت وجود ندارد. .PP .TP .B Preprocessing locally. Include server not covering: Bailing out because include server spent more than ...s user time handling request در شرایط غیرمعمول، کارساز include در تحلیل عبارت‌های ماکروی بسیار پیچیده ناموفق است. کلاینت distcc از حالت ساده distcc استفاده خواهد کرد. .PP .TP .B Warning: Filepath must be relative but isn't کارساز include مسیرهای مطلق مانند /usr/include/stdio.h را در دستورات include نمی‌پذیرد، زیرا هیچ تضمینی وجود ندارد که این فایل سرآیند روی رایانه کارساز کامپایل مشابه رایانه کلاینت باشد. کارساز include از تحلیل بستار include منصرف می‌شود. کلاینت distcc نمی‌تواند از حالت pump استفاده کند. .IP برای رفع این مشکل به روشی که البته همیشه قابل اعتماد نیست، هنگام فراخوانی اسکریپت pump متغیر محیطی INCLUDE_SERVER_ARGS='--unsafe_absolute_includes' را تنظیم کنید تا گزینه --unsafe_absolute_includes به کارساز include ارسال شود. .PP .TP .B Warning: Absolute filepath ... was IGNORED گزینه --unsafe_absolute_includes در حال استفاده است. این وضعیت تحت همان شرایطی رخ می‌دهد که پیام "Filepath must be relative but isn't" صادر می‌شود، اما در این حالت پردازشگر include پاسخی به کلاینت distcc ارائه خواهد داد. .PP .TP .B Warning: Path '/PATH/FILE' changed/came into existence/no longer exists این هشدارها هنگام استفاده از محرک‌های بازنشانی stat صادر می‌شوند. به دلیل تغییر /PATH/FILE، کارساز include حافظه پنهان خود را پاک می‌کند؛ نسخه جدید فایل (یا عدم وجود آن) تحلیل include را نامعتبر می‌سازد. این پیام معمولاً قابل چشم‌پوشی است؛ اما نشان‌دهنده استفاده تا حدی ناامن از فایل‌ها توسط سیستم ساخت است. توصیه می‌شود سیستم ساخت به گونه‌ای اصلاح شود که فایل‌ها بازنویسی نشوند. .PP .TP .B Warning: For translation unit ..., lookup of file ... resolved to ... whose realpath is ... این هشدار همراه با --path_observation_re زمانی رخ می‌دهد که یک realpath جدید منطبق با یک فایل سورس یا سرآیند مشاهده شود. .SH "نشانه‌های مغایرت DISTCC (DISTCC DISCREPANCY SYMPTOMS)" تعاملات بین سیستم ساخت، distcc و کارساز include تا حدودی پیچیده است. هنگامی که دستورات distcc یک خطای کامپایل از کارساز دوردست دریافت می‌کنند، کامپایل را به صورت محلی دوباره امتحان می‌کنند. این بخش دلایل مغایرت بین کامپایل از راه دور و محلی را مورد بحث قرار می‌دهد. این موارد با پیام تنزل رتبه مشخص می‌شوند: .PP .B __________Warning: ... pump-mode compilation(s) failed on server, .B but succeeded locally. .br .B __________Distcc-pump was demoted to plain mode. .B See the Distcc Discrepancy Symptoms section in the include_server(1) man .B page. .PP اسکریپت pump این پیام را در پایان فرایند ساخت صادر می‌کند. این بدان معناست که حداقل در یک مورد فراخوانی distcc، پس از شکست کامپایل از راه دور، کامپایل محلی با موفقیت انجام شده است. هر فراخوانی distcc که چنین مغایرتی برای آن رخ داده باشد نیز به نوبه خود پیامی شبیه به این صادر می‌کند: .PP .B Warning: remote compilation of '...' failed, .B retried locally and got a different result. .PP این تنزل درجه باعث می‌شود که فراخوانی‌های بعدی distcc از حالت ساده distcc استفاده کنند. بنابراین پیش‌پردازش برای ادامه ساخت روی رایانه محلی انجام خواهد شد. این روش از ساخت‌های بسیار کند که در آن‌ها تمامی کامپایل‌ها پس از شکست از راه دور در نهایت روی رایانه محلی انجام می‌شوند، جلوگیری می‌کند. .PP البته اگر کامپایل محلی نیز پس از شکست‌های از راه دور با خطا مواجه شود، فراخوانی distcc با وضعیت غیرصفر کامپایل محلی خارج می‌شود. پیام‌های خطای چاپ‌شده نیز همان پیام‌های کامپایل محلی هستند. .PP رفتار بازگشت به کامپایل محلی برای حالت distcc-pump را می‌توان با تنظیم متغیر محیطی DISTCC_FALLBACK بر روی ۰ غیرفعال کرد، که باعث می‌شود دستور distcc به محض شکست کامپایل از راه دور ناموفق شود. این تنظیم برای اشکال‌زدایی دلیل بروز خطا در کامپایل از راه دور بسیار مفید است، زیرا در این حالت خروجی کارساز چاپ خواهد شد. .PP در ادامه دلایل احتمالی بروز مغایرت‌ها را بررسی می‌کنیم. .PP .TP .B کاربر در حین ساخت، یک فایل سورس یا سرآیند را تغییر داده است. این کار مسلماً نتایج متناقضی به همراه خواهد داشت. .PP .TP .B یک فایل سورس یا سرآیند در طول ساخت تغییر کرده است. سیستم ساخت یک فایل را بازنویسی می‌کند. برای هسته لینوکس ۲.۶، این اتفاق برای 'include/linux/compile.h' و 'include/asm/asm-offsets.h' رخ می‌دهد. این وضعیت با آگاه کردن کارساز include از این موضوع که باید حافظه پنهان خود را هنگام تغییر stat هر یک از فایل‌ها پاک کند، برطرف می‌شود. از نظر عملی، این کار با گردآوری فایل‌ها در یک فهرست با جداکننده دونقطه و سپس تنظیم متغیر محیطی INCLUDE_SERVER_ARGS هنگام اجرای اسکریپت pump انجام می‌شود تا گزینه .B --stat_reset_triggers ارسال شود؛ برای مثال: .PP .nf INCLUDE_SERVER_ARGS="--stat_reset_triggers=include/linux/compile.h:include/asm/asm-offsets.h" .fi .PP .TP .B یک فایل سرآیند بالقوه include شده است، اما وجود ندارد و سپس بعداً include می‌شود. این حالت زمانی رخ می‌دهد که یک سرآیند foo.h فایل سرآیند دیگری به نام trick.h را شامل شود، اما فایل trick.h هنوز تولید نشده باشد و عمل include به دلیل دستورات پیش‌پردازنده عملاً نادیده گرفته شود. کارساز include وجود trick.h را بررسی می‌کند، زیرا تمام حالت‌های ممکن برای ارزیابی دستورات را بیش از حد تخمین می‌زند. مشخص می‌شود که فایل trick.h وجود ندارد. اگر بعداً این فایل تولید شود و واقعاً include گردد، کارساز include به اشتباه تصور می‌کند که فایل هنوز وجود ندارد. راه‌حل این مشکل این است که سیستم ساخت طوری تنظیم شود که trick.h را پیش از نخستین باری که هر فایل سرآیندی ارجاعی به trick.h دارد تولید کند. .PP .TP .B کارساز include با \fB--unsafe_absolute_includes\fR راه‌اندازی شده است. این مورد زمانی مشکل‌ساز است که فایل‌های سرآیندی به صورت محلی وجود داشته باشند که در کارساز دوردست وجود ندارند و در عمل مورد استفاده قرار می‌گیرند. چنین includeهایی اغلب توسط دستورات شرطی محافظت می‌شوند که طوری ارزیابی می‌شوند که فقط در پلتفرم‌های خاص و معمولاً غیرمعمول استفاده شوند. اگر برای چنین پلتفرمی کامپایل نمی‌کنید، استفاده از \fB--unsafe_absolute_includes\fR می‌تواند مناسب باشد. .PP .TP .B کارساز include فایل‌های include را اشتباه محاسبه کرده است. ما تاکنون از چنین وضعیتی مطلع نشده‌ایم. .SH "کدهای خروج (EXIT CODES)" کد خروج include_server.py معمولاً ۰ است. راه‌اندازی صحیح کارساز include از طریق وجود فایل pid_file اطلاع داده می‌شود. .SH "متغیرهای محیطی (ENVIRONMENT VARIABLES)" .TP .B DISTCC_EMAILLOG_WHOM_TO_BLAME نشانی ایمیل مورد استفاده برای ایمیل‌های خودکار کارساز include. پیش‌فرض 'distcc-pump-errors' است (که نشانی ایمیلی است که احتمالاً در دامنه شما وجود نخواهد داشت). .PP علاوه بر این، فراخوانی کامپایلر ممکن است از متغیرهای محیطی دیگری نیز استفاده کند. .SH "گزارش باگ‌ها (BUGS)" اگر فکر می‌کنید باگی در distcc یافته‌اید، لطفاً فایل .I reporting-bugs.txt در پوشه مستندات را برای اطلاعات در مورد نحوه گزارش آن بررسی کنید. .PP در حالت distcc-pump، کارساز include قادر به مدیریت برخی includeهای محاسباتی بسیار پیچیده مانند موارد موجود در بخش‌هایی از کتابخانه Boost نیست. مهلت زمانی کارساز include به پایان می‌رسد و distcc به حالت ساده بازمی‌گردد. .PP سایر باگ‌های شناخته‌شده ممکن است در .I http://code.google.com/p/distcc مستند شده باشند. .SH "نویسنده (AUTHOR)" کارساز include توسط Nils Klarlund با همکاری Fergus Henderson، Manos Renieris و Craig Silverstein نوشته شده است. لطفاً باگ‌ها را به گزارش دهید. .SH "مجوز (LICENCE)" استفاده از distcc برای شما آزاد است. distcc (شامل این راهنما) تنها تحت شرایط مجوز عمومی همگانی گنو (GNU GPL) نسخه ۲ یا بالاتر می‌تواند رونوشت، اصلاح یا توزیع شود. distcc مطلقاً بدون هیچ‌گونه ضمانتی ارائه می‌شود. یک نسخه از GPL در فایل COPYING گنجانده شده است. .SH "همچنین ببینید (SEE ALSO)" \fBdistcc\fR(1), \fBdistccd\fR(1), \fBinclude_server\fR(1), \fBgcc\fR(1) .PP http://code.google.com/p/distcc https://ccache.dev