xbuild(1) General Commands Manual xbuild(1)

xbuild - ابزار Mono برای ساخت فایل‌های پروژهٔ MSBuild

xbuild [option] [project-file]

دستور xbuild می‌تواند برای ساخت (build) فایل‌های پروژهٔ MSBuild به کار رود. محیط‌های یکپارچهٔ توسعه (IDE) مانند MonoDevelop و "Microsoft Visual Studio .NET" از قالب فایل پروژهٔ msbuild استفاده می‌کنند.

دستور xbuild مسیر فایل پروژه یا solution مورد نظر برای ساخت را به عنوان آرگومان اصلی دریافت می‌کند. در صورتی که هیچ فایلی مشخص نشود، برای ساخت هر فایل solution یا فایل پروژه‌ای در پوشهٔ جاری که پسوند proj.* داشته باشد تلاش می‌کند.

/target:T1[,TN]
فهرست هدف‌ها (targets) برای ساخت
/property:Name=Value
تنظیم یا بازنویسی مشخصه‌های (properties) پروژه
/logger:<logger>
ثبت‌کنندهٔ وقایع (logger) سفارشی برای ثبت رویدادهای ساخت
/toolsversion:version , /tv:version
نسخهٔ مجموعه‌ابزار (toolset) مورد استفاده را مشخص می‌کند.

به عنوان مثال: /tv:4.0
باعث می‌شود نسخهٔ 4.0 از Microsoft.Common.targets (در میان موارد دیگر) استفاده شود. این مقدار مشخص‌شده در فایل پروژه را بازنویسی می‌کند.

مقدارهای معتبر: 2.0، 3.0، 3.5 و 4.0

/verbosity:<level>
سطح پرگویی لاگر: quiet، minimal، normal، detailed، diagnostic
/validate
اعتبارسنجی فایل پروژه در برابر شِما (schema)
/validate:<schema>
اعتبارسنجی فایل پروژه در برابر شِمای مشخص‌شده
/consoleloggerparameters:<params> , /clp:<params>
پارامترهای ثبت‌کنندهٔ وقایع کنسول: PerfomanceSummary، Summary، NoSummary، NoItemAndPropertyList، Verbosity
/filelogger[n] , /fl[n]
خروجی را در فایلی ثبت می‌کند که به‌طور پیش‌فرض 'msbuild.log' نام دارد. اگر عدد اختیاری 'n' مشخص شود، در 'msbuild[n].log' ثبت خواهد شد. پارامترهای این ثبت‌کننده، از جمله نام فایل لاگ، را می‌توان با گزینهٔ متناظر /flp[n] تعیین کرد. سطح پرگویی پیش‌فرض برای لاگرهای فایل 'detailed' است. مقدار 'n' می‌تواند بین 1 تا 9 باشد.
/fileloggerparameters[n]:<params> , /flp[n]:<params>
پارامترهای ثبت‌کنندهٔ فایل. این گزینه متضمن یک گزینهٔ متناظر /fl[n] است. مقدار 'n' می‌تواند بین 1 تا 9 باشد و برای افزودن حداکثر 10 ثبت‌کنندهٔ فایل استفاده می‌شود. پارامترها علاوه بر موارد موجود برای لاگر کنسول، می‌توانند شامل موارد زیر باشند:
فایلی که لاگ ساخت در آن نوشته خواهد شد.
اگر از این مورد استفاده شود، لاگ به انتهای فایل افزوده می‌شود، در غیر این صورت فایلی جدید ایجاد خواهد شد.
کدگذاری مورد استفاده برای فایل لاگ، مانند UTF-8، ASCII.
مثال: xbuild foo.csproj /flp:Verbosity=normal "/flp1:LogFile=build.log;Append;Encoding=ASCII"
/nologo
عدم نمایش بنر اولیهٔ xbuild
/help
نمایش نحوهٔ استفاده از xbuild
/version
نمایش نسخهٔ xbuild

اگر این متغیر تنظیم شود، فایل پروژه‌ای که از روی فایل solution تولید شده است، خروجی داده می‌شود.
ارجاعات با بررسی فهرستی از مسیرهای جستجوی اسمبلی ($(AssemblySearchPaths)) حل‌وفصل (resolve) می‌شوند. اگر xbuild نتواند ارجاعی را حل کند، جزئیات دلیل ناموفق بودن مسیرهای مختلف جستجو را ثبت می‌کند. اگر این متغیر تنظیم شود، همین اطلاعات را حتی برای ارجاعاتی که با موفقیت حل شده‌اند نیز ثبت می‌کند. این لاگ‌ها در صورتی نمایش داده می‌شوند که سطح پرگویی روی detailed یا بالاتر تنظیم شده باشد.
افزونه‌های MSBuild معمولاً در $(MSBuildExtensionsPath) نصب می‌شوند، که xbuild آن را به $prefix/lib/mono/xbuild نگاشت می‌کند. هنگامی که در Import استفاده شود، مانند:


<Import Project="$(MSBuildExtensionsPath)\TestTargets.targets"/>

دستور xbuild مقادیر مختلف را برای مشخصهٔ msbuild یعنی $(MSBuildExtensionsPath) به ترتیب زیر می‌آزماید:


1. مسیرهای مشخص‌شده در متغیر محیطی $MSBuildExtensionsPath.
2. مسیر /Library/Frameworks/Mono.framework/External/xbuild در Mac OSX.
3. مسیر $XDG_CONFIG_HOME/xbuild/tasks (یا Environment.SpecialFolder.ApplicationData)
4. مسیر $prefix/lib/mono/xbuild (مکان پیش‌فرض)

در هر جای دیگری از فایل‌های پروژه، $(MSBuildExtensionsPath) همواره به مکان پیش‌فرض ارجاع داده خواهد شد. این قابلیت منحصراً متعلق به xbuild است. این قاعده برای مشخصه‌های $(MSBuildExtensionsPath32) و $(MSBuildExtensionsPath64) نیز صادق است و متغیرهای محیطی نام‌های متناظر MSBuildExtensionsPath32/64 را دارند.

در ToolsVersion 4.0، پروژه‌ها می‌توانند چارچوب‌های دلخواهی را هدف قرار دهند که توسط TargetFrameworkMoniker مشخص می‌شوند و ساختاری به این صورت دارند:


Identifier,Version=<version>[,Profile=<profile>]

مانند ".NETFramework,Version=v4.0"

این ۳ بخش moniker توسط مشخصه‌های msbuild زیر تعیین می‌شوند:


$(TargetFrameworkIdentifier)، $(TargetFrameworkVersion) و $(TargetFrameworkProfile)

این moniker به یک فایل توصیف چارچوب روی دیسک نگاشت می‌شود:


<framework_root>/Identifier/Version/[Profile]/RedistList/FrameworkList.xml

این فایل برای تعیین مسیری استفاده می‌شود که اسمبلی‌های مربوط به این چارچوب خاص در آن یافت می‌شوند.

پوشهٔ ریشهٔ چارچوب (Framework root) در اینجا قابل‌پیکربندی است و به ترتیب زیر ارزیابی می‌شود:

1. مسیرهای مشخص‌شده در متغیر محیطی $XBUILD_FRAMEWORK_FOLDERS_PATH
2. مسیر /Library/Frameworks/Mono.framework/External/xbuild-frameworks در Mac OSX.
3. مشخصهٔ MSBuild به نام $(TargetFrameworkRoot)
4. مسیر $prefix/lib/mono/xbuild-frameworks (مکان پیش‌فرض)

دستور XBuild مسیرهای ارائه‌شده در بالا را به ترتیب امتحان می‌کند تا به فایل FrameworkList.xml مربوط به moniker دست یابد. اجرا با گزینهٔ /v:detailed یا سطح پرگویی بالاتر، مسیرهای مختلفی را که امتحان می‌شوند نمایش می‌دهد.

خود فایل FrameworkList.xml صرفاً دارای یک عنصر ریشه است، مانند:


<FileList Name=".NET Framework 3.5" TargetFrameworkDirectory="..\..\..\..\3.5" IncludeFramework="v3.0">
</FileList>

در اینجا ویژگی TargetFrameworkDirectory پوشه‌ای را تعیین می‌کند که اسمبلی‌های این چارچوب خاص در آن قرار دارند. اگر این مقدار تنظیم نشده باشد، والد پوشهٔ حاوی فایل xml به عنوان پوشهٔ چارچوب در نظر گرفته می‌شود.

ویژگی IncludeFramework نسخهٔ یک چارچوب (تحت *همان* $(TargetFrameworkIdentifier)) را مشخص می‌کند که باید در فهرست نهایی پوشه‌های چارچوب هدف گنجانده شود.

اگر این متغیر تنظیم شود، شامل رشته‌ای به فرم "type=foreground,type=.." خواهد بود که مشخص می‌کند چه رنگی برای نمایش خطاها/هشدارها و غیره در برخی پایانه‌ها استفاده شود. مقدار Type در اینجا می‌تواند به صورت زیر باشد: 
errors, warnings, messages یا events
events: پیام‌های رویداد شروع و پایان project/target/task هستند.

رنگ‌های ممکن برای پیش‌زمینه (foreground) عبارتند از: black, red, brightred, green, brightgreen, yellow, brightyellow, blue, brightblue, magenta, brightmagenta, cyan, brightcyan, grey, white و brightwhite.

به عنوان مثال، می‌توانید این متغیر را در شل خود تنظیم کنید:

export XBUILD_COLORS
XBUILD_COLORS=errors=brightred,warnings=blue

می‌توانید طرح‌بندی رنگی درون‌ساخته را با تنظیم این متغیر روی "disable" غیرفعال کنید.

در Mac OSX، برای یافتن فایل‌های pkg-config (.pc)، ابزار xbuild به علاوه در مسیر "/Library/Frameworks/Mono.framework/External/pkgconfig" نیز جستجو می‌کند.

mono(1), mcs(1)

Copyright (C) 2011 Novell, Inc (http://www.novell.com)

برای جزئیات بیشتر به http://lists.ximian.com/mailman/listinfo/mono-devel-list مراجعه کنید.

برای جزئیات بیشتر به http://www.mono-project.com مراجعه کنید.