نام (NAME)

castxml - خروجی XML از درخت نحو انتزاعی برای خانواده زبان‌های C

خلاصه دستور (SYNOPSIS)

castxml ( <castxml-opt> | <clang-opt> | <src> )...

توضیحات (DESCRIPTION)

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

فایل‌های منبع با استفاده از کامپایلر درونی Clang https://clang.llvm.org به عنوان واحدهای ترجمه کامل تجزیه می‌شوند. خروجی XML توسط گزینه --castxml-output=<v> یا --castxml-gccxml فعال می‌گردد.

گزینه‌ها (OPTIONS)

گزینه‌های خط فرمان زیر توسط castxml تفسیر می‌شوند. گزینه‌های باقی‌مانده به کامپایلر درونی Clang داده می‌شوند.

--castxml-cc-<id> <cc>, --castxml-cc-<id> "(" <cc> <cc-opt>... ")": پیش‌پردازنده درونی Clang و پلتفرم هدف را به‌گونه‌ای پیکربندی می‌کند که با دستور کامپایلر داده‌شده مطابقت داشته باشد. <id> نام کامپایلر مرجعی را مشخص می‌کند که دستور داده‌شده با آن سازگار است. این مقدار باید یکی از موارد زیر باشد:

gnu: کامپایلر GNU Compiler Collection C++ (g++)
gnu-c: کامپایلر GNU Compiler Collection C (gcc)
msvc: کامپایلر Microsoft Visual C++ (cl)
msvc-c: کامپایلر Microsoft Visual C (cl)

<cc> نام یک کامپایلر را مشخص می‌کند (مانند /usr/bin/gcc یا cl) و <cc-opt>... گزینه‌هایی را مشخص می‌کند که ممکن است بر هدف آن تأثیر بگذارند (مانند -m32). پلتفرم هدف تشخیص‌داده‌شده از کامپایلر مشخص‌شده را می‌توان با یک گزینه جداگانه -target در Clang بازنویسی و جایگزین کرد. سطح استاندارد زبان تشخیص‌داده‌شده از کامپایلر داده‌شده را می‌توان با یک گزینه جداگانه -std= در Clang بازنویسی کرد.

--castxml-output=<v>: خروجی XML را در <src>.xml یا فایلی که با -o مشخص شده می‌نویسد. <v> شماره نسخه قالب «epic» را برای تولید مشخص می‌کند، و باید مقدار آن 1 باشد.
--castxml-gccxml: خروجی XML را در قالبی نزدیک به gccxml http://gccxml.org تولید می‌کند. خروجی در <src>.xml یا فایل تعیین‌شده توسط -o نوشته می‌شود. قالب gccxml از حالت‌های زبان Clang غیر از -std=c++98 یا -std=c89 پشتیبانی نمی‌کند. این قالب خروجی ممکن است با حالت‌های زبان -std=c++11، -std=c++14، -std=c99، و -std=c11 استفاده شود اما خروجی شامل سازنده‌های انتقال ضمنی (implicit move constructors) یا عملگرهای انتساب انتقال نخواهد بود، و ممکن است در ساختارهای غیر c++98 شامل عناصر <Unimplemented/> باشد.
--castxml-start <name>[,<name>]...: پیمایش AST را از اعلان(ها) با نام(های) کامل داده‌شده آغاز می‌کند. چندین نام را می‌توان به‌صورت فهرستی جداشده با کاما یا با تکرار این گزینه مشخص کرد.
-help, --help: اطلاعات نحوه استفاده از castxml و کامپایلر درونی Clang را چاپ می‌کند.
-o <file>: در صورت تولید خروجی (مثلاً از طریق --castxml-output=<v>)، خروجی را در <file> می‌نویسد. حداکثر یک فایل <src> می‌تواند به‌عنوان ورودی مشخص شود.
--version: اطلاعات نسخه castxml و کامپایلر درونی Clang را چاپ می‌کند.
نسخه‌های رسمی CastXML از این قالب استفاده می‌کنند:

<major>.<minor>.<patch>[-rc<n>][-<id>]

که در آن بخش <patch> کمتر از 20000000 است، <n> یک شماره اختیاری کاندیدای انتشار (release candidate) است، و <id> ممکن است شامل متن دلخواه باشد (در صورت توسعه بین نسخه‌های وصله).

نسخه‌های توسعه CastXML از این قالب استفاده می‌کنند:

<major>.<minor>.<date>[-<id>]

که در آن بخش <date> به قالب CCYYMMDD است و <id> ممکن است شامل متن دلخواه باشد. این بخش نمایانگر توسعه تا یک تاریخ مشخص پس از انتشار نسخه قابلیت‌های <major>.<minor> است.

نسخه‌های قالب خروجی (OUTPUT FORMAT VERSIONS)

با --castxml-output=<v>

برچسب عنصر ریشه XML به شکل زیر خواهد بود:

<CastXML format="1.4.0">

بخش اول شماره نسخه قالب epic است که به پرچم --castxml-output=<v> داده شده است، و در حال حاضر باید همیشه 1 باشد.
بخش دوم شماره نسخه اصلی (major) قالب است و با افزوده شدن یک عنصر جدید XML یا تغییرات عمده دیگر افزایش می‌یابد. کلاینت‌ها نیازمند به‌روزرسانی خواهند بود.
بخش سوم شماره نسخه فرعی (minor) قالب است و هر زمان که صفت (attribute) جدیدی از XML به یک عنصر موجود اضافه شود یا اشکال جزئی در خروجی XML مربوط به یک عنصر یا صفت موجود رفع گردد، افزایش می‌یابد (کلاینت‌ها بدون نیاز به تغییر به کار خود ادامه می‌دهند مگر اینکه اطلاعات جدید را بخواهند).

با --castxml-gccxml

برچسب عنصر ریشه XML به شکل زیر خواهد بود:

<GCC_XML version="0.9.0" cvs_revision="1.139">

شماره version با آخرین نسخه gccxml http://gccxml.org که تاکنون منتشر شده است مطابقت دارد (برای سازگاری رو به عقب). شماره cvs_revision یک شماره ترتیبی متوالی است که با هر تغییر جزئی در قالب XML افزایش می‌یابد.

طرحواره (SCHEMA)

طرحواره XML که هر دو قالب خروجی را توصیف می‌کند در دسترس است: castxml.xsd.

پیش‌پردازش (PREPROCESSING)

نرم‌افزار CastXML فایل‌های منبع را با استفاده از کامپایلر درونی Clang و به‌طور پیش‌فرض با بهره‌گیری از ماکروهای از پیش تعریف‌شده اختصاصی خود برای پلتفرم هدف، پیش‌پردازش می‌کند. گزینه --castxml-cc-<id> ماکروهای از پیش تعریف‌شده را تغییر می‌دهد تا با مواردی که از دستور کامپایلر داده‌شده شناسایی شده‌اند مطابقت پیدا کنند. در هر دو حالت، CastXML همواره ماکروهای از پیش تعریف‌شده زیر را اضافه می‌کند:

__castxml_major__: به شماره نسخه اصلی CastXML در مبنای ۱۰ تعریف شده است.
__castxml_minor__: به شماره نسخه فرعی CastXML در مبنای ۱۰ تعریف شده است.
__castxml_patch__: به شماره نسخه وصله CastXML در مبنای ۱۰ تعریف شده است.
__castxml_check(major,minor,patch): به یک عبارت ثابت تعریف شده است که سه بخش نسخه را برای مقایسه با __castxml__ کدگذاری می‌کند. روش کدگذاری دقیق مشخص نشده است.
__castxml__: به یک عبارت ثابت تعریف شده است که مؤلفه‌های نسخه CastXML را کدگذاری می‌کند:

__castxml_check(__castxml_major__,__castxml_minor__,__castxml_patch__)

__castxml_clang_major__: به مقدار __clang_major__ از کامپایلر درونی Clang تعریف شده است.
__castxml_clang_minor__: به مقدار __clang_minor__ از کامپایلر درونی Clang تعریف شده است.
__castxml_clang_patchlevel__: به مقدار __clang_patchlevel__ از کامپایلر درونی Clang تعریف شده است.

فایل‌های منبع می‌توانند از این ماکروها برای شناسایی ابزاری که در عمل در حال انجام پیش‌پردازش است استفاده کنند، حتی اگر --castxml-cc-<id> ماکروهای از پیش تعریف‌شده را تغییر دهد.

پرسش‌های متداول (FAQ)

چرا بدنه توابع C++ در خروجی XML قرار نمی‌گیرد؟

این ویژگی پیاده‌سازی نشده است زیرا پروژه اصلی که CastXML برای آن نوشته شده بود نیازی به بدنه توابع نداشت.

چرا الگوها (Templates) در خروجی دیده نمی‌شوند؟

این ویژگی پیاده‌سازی نشده است زیرا پروژه اصلی که CastXML برای آن نوشته شده بود نیازی به الگوهای نمونه‌سازی‌نشده نداشت. با این وجود، الگوهای نمونه‌سازی‌شده در خروجی درج خواهند شد. به عنوان مثال:

template <class T> struct foo {};
typedef foo<int>::foo foo_int;

موجب نمونه‌سازی foo<int> خواهد شد که در خروجی گنجانده می‌شود. با این حال، به غیر از درون نام، هیچ جایی وجود نخواهد داشت که مجموعه‌ای از انواع داده استفاده‌شده برای نمونه‌سازی را صراحتاً فهرست کند. دلیل این امر آن است که شیوه مناسب برای انجام این کار، درج خود الگوها و ارجاع به آن‌ها از نمونه‌سازی‌ها با ذکر آرگومان‌های الگو است. از آنجا که این ویژگی‌ها به یکدیگر وابسته‌اند، باید همراه با یکدیگر پیاده‌سازی شوند.

کپی‌رایت و تکثیر (COPYRIGHT)

2013-2022 Kitware, Inc.