CTEST(1) CMake CTEST(1)

ctest - ابزار اجرای آزمون‌ها در سیستم ساخت CMake

•
ctest(1)
  • خلاصه دستور
  • توضیحات
  • اجرای آزمون‌ها
  • مشاهده راهنما
  • تطبیق برچسب‌ها
  • خلاصه برچسب‌ها و زیرپروژه‌ها
  • حالت ساخت و آزمون
  • کلاینت داشبورد
  • مراحل کلاینت داشبورد
  • حالت‌های کلاینت داشبورد
  • کلاینت داشبورد از طریق خط فرمان CTest
  • کلاینت داشبورد از طریق اسکریپت CTest
•
پیکربندی کلاینت داشبورد
  • مرحله آغاز CTest
  • مرحله به‌روزرسانی CTest
  • مرحله پیکربندی CTest
  • مرحله ساخت CTest
  • مرحله آزمون CTest
  • مرحله پوشش کد CTest
  • مرحله بررسی حافظه CTest
  • مرحله ارسال CTest
  • نمایش به عنوان مدل شیء JSON
  • تخصیص منابع
  • فایل مشخصات منابع
  • ویژگی RESOURCE_GROUPS
  • متغیرهای محیطی
  • فایل مشخصات منابع تولیدشده به‌صورت پویا
  • یکپارچه‌سازی با سرور کارها
  • همچنین ببینید

اجرای آزمون‌ها
 ctest [<options>...] [--test-dir <path-to-build>] [-- <test-args>...]
حالت ساخت و آزمون
 ctest --build-and-test <path-to-source> <path-to-build>
       --build-generator <generator> [<options>...]
      [--build-options <opts>...]
      [--test-command <command> [<args>...]]
کلاینت داشبورد
 ctest -D <dashboard>            [-- <dashboard-options>...]
 ctest -M <model> -T <action>    [-- <dashboard-options>...]
 ctest [-M <model>] -T Configure --source-dir <path-to-source>
                                 [--build-dir <path-to-build>]
                                 [-- <dashboard-options>...]
 ctest -S <script>               [-- <dashboard-options>...]
 ctest -SP <script>              [-- <dashboard-options>...]
مشاهده راهنما
 ctest --help[-<topic>]

برنامه اجرایی ctest ابزار گرداننده آزمون‌ها در سامانه ساخت CMake است. درخت‌های ساخت تولیدشده توسط CMake برای پروژه‌هایی که از دستورات enable_testing() <#command:enable_testing> و add_test() <#command:add_test> استفاده می‌کنند، دارای پشتیبانی از اجرای آزمون هستند. این برنامه آزمون‌ها را اجرا کرده و نتایج را گزارش می‌کند.

دستور ctest آزمون‌های تعریف‌شده توسط یک فایل CTestTestfile.cmake را اجرا می‌کند، که معمولاً در یک درخت ساخت تولیدشده توسط cmake(1) <#manual:cmake(1)> قرار دارد:

ctest [<options>...] [--test-dir <path-to-build>] [-- <test-args>...]

اگر تمام آزمون‌ها با موفقیت سپری شوند، کد خروج 0 خواهد بود. کد خروج در موارد زیر غیرصفر است:

  • خطایی رخ دهد، مانند شکست در پردازش آرگومان‌های نامعتبر.
  • افزوده‌شده در نسخه 4.4: هیچ آرگومانی داده نشده باشد و هیچ فایل CTestTestfile.cmake وجود نداشته باشد.
  • آرگومان --no-tests=error داده شده باشد و هیچ آزمونی اجرا نشود؛ برای مثال هنگامی که CTestTestfile.cmake هیچ آزمونی را تعریف نکرده باشد، یا زمانی که آرگومان‌های داده‌شده تمام آزمون‌ها را مستثنی کنند.
  • دست‌کم یک آزمون با شکست مواجه شود.

گزینه‌های اجرای آزمون‌ها عبارتند از:

استفاده از یک پیش‌تنظیم (preset) آزمون <#manual:cmake-presets(7)> برای مشخص کردن گزینه‌های آزمون. دایرکتوری باینری پروژه از کلید configurePreset <#cmakepresets-testpresets-configurepreset> استنباط می‌شود.

افزوده‌شده در نسخه 3.30: گزینه --test-dir می‌تواند با دایرکتوری باینری متفاوتی نسبت به آنچه توسط کلید configurePreset <#cmakepresets-testpresets-configurepreset> مشخص شده، تعیین گردد.

تغییریافته در نسخه 4.4: اگر --presets-file مشخص شده باشد، حضور هیچ‌یک از فایل‌های CMakePresets.json یا CMakeUserPresets.json الزامی نیست. در غیر این صورت، وجود آن‌ها در دایرکتوری منبع سطح بالا الزامی است. در نسخه‌های پیشین، این موضوع اکیداً الزامی بود.

افزوده‌شده در نسخه 4.4.

خواندن پیش‌تنظیم‌ها (presets <#manual:cmake-presets(7)>) از <file> داده‌شده. مسیر مشخص‌شده می‌تواند مطلق یا نسبت به دایرکتوری کاری جاری باشد. اگر --presets-file داده شود، پیش‌تنظیم‌های تعریف‌شده در CMakePresets.json و CMakeUserPresets.json نادیده گرفته خواهند شد.

فهرست کردن پیش‌تنظیم‌های آزمون موجود. دایرکتوری کاری جاری باید شامل CMakePresets.json و/یا CMakeUserPresets.json باشد.

تغییریافته در نسخه 4.4: اگر --presets-file مشخص شده باشد، وجود هیچ‌یک از فایل‌های CMakePresets.json یا CMakeUserPresets.json الزامی نیست، و تنها پیش‌تنظیم‌های تعریف‌شده در <file> مشخص‌شده فهرست خواهند شد. در غیر این صورت، حضور آن‌ها در دایرکتوری منبع سطح بالا الزامی است. در نسخه‌های پیشین، این موضوع اکیداً الزامی بود.

انتخاب پیکربندی برای آزمون.

برخی از درخت‌های ساخت تولیدشده توسط CMake می‌توانند چندین پیکربندی ساخت در همان درخت داشته باشند. این گزینه می‌تواند برای مشخص کردن اینکه کدام پیکربندی باید آزمایش شود به کار رود. پیکربندی‌های نمونه شامل Debug و Release هستند.

فعال‌سازی خروجی مختصر پیشرفت آزمون‌ها.

هنگامی که خروجی ctest مستقیماً به یک ترمینال ارسال می‌شود، پیشرفت مجموعه آزمون‌ها به‌جای چاپ پیام‌های شروع و پایان هر آزمون در سطرهای جدید، با به‌روزرسانی همان سطر گزارش می‌شود. این کار می‌تواند میزان پرگویی خروجی آزمون را به میزان چشمگیری کاهش دهد. پیام‌های اتمام آزمون برای آزمون‌های ناموفق همچنان در سطر اختصاصی خود چاپ می‌شوند و خلاصه نهایی آزمون نیز ثبت خواهد شد.

این گزینه همچنین می‌تواند با تنظیم متغیر محیطی CTEST_PROGRESS_OUTPUT <#envvar:CTEST_PROGRESS_OUTPUT> فعال شود.

فعال‌سازی خروجی پرجزئیات از آزمون‌ها.

خروجی آزمون‌ها معمولاً مخفی نگه داشته شده و فقط اطلاعات خلاصه نمایش داده می‌شود. این گزینه تمام خروجی‌های آزمون را نشان می‌دهد.

فعال‌سازی خروجی با جزئیات بیشتر از آزمون‌ها.

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

نمایش جزئیات داخلی دقیق‌تر CTest.

این ویژگی منجر به حجم بالایی از خروجی می‌شود که عمدتاً برای اشکال‌زدایی مشکلات داشبورد مفید است.

چاپ تمام خروجی‌های برنامه آزمون در صورت شکست آزمون. این گزینه همچنین با تنظیم متغیر محیطی CTEST_OUTPUT_ON_FAILURE <#envvar:CTEST_OUTPUT_ON_FAILURE> قابل فعال‌سازی است.
توقف اجرای آزمون‌ها به محض وقوع نخستین شکست.
فعال‌سازی بازیابی پس از شکست (failover).

این گزینه به CTest اجازه می‌دهد اجرای مجموعه آزمونی را که قبلاً قطع شده بود، از سر بگیرد. در صورتی که هیچ وقفه‌ای رخ نداده باشد، گزینه -F هیچ اثری نخواهد داشت.

اجرای موازی آزمون‌ها، به صورت اختیاری محدود به سطح مشخصی از موازی‌سازی.

افزوده‌شده در نسخه 3.29: مقدار <level> می‌تواند حذف شود، یا 0 باشد که در این حالت:

  • تحت یکپارچگی کارگزار کار (Job Server Integration)، موازی‌سازی با نشانه‌های کار (job tokens) موجود محدود می‌شود.
  • در غیر این صورت، اگر مقدار حذف شود، موازی‌سازی به تعداد پردازنده‌ها یا ۲ (هرکدام که بزرگ‌تر باشد) محدود خواهد شد.
  • در غیر این صورت، اگر مقدار 0 باشد، موازی‌سازی نامحدود خواهد بود.

این گزینه می‌تواند از طریق متغیر محیطی CTEST_PARALLEL_LEVEL <#envvar:CTEST_PARALLEL_LEVEL> نیز مشخص گردد.

این گزینه می‌تواند با ویژگی آزمون PROCESSORS <#prop_test:PROCESSORS> به کار رود. بخش خلاصه برچسب و زیرپروژه (Label and Subproject Summary) را ببینید.

اجرای CTest با تخصیص منابع فعال، با استفاده از فایل مشخصات منبع (resource specification file) تعیین‌شده در <file>.

هنگامی که ctest به عنوان یک کلاینت داشبورد اجرا می‌شود، این گزینه فیلد ResourceSpecFile مرحله آزمون CTest را تنظیم می‌کند.

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

هنگامی که ctest به عنوان کلاینت داشبورد اجرا می‌شود، این گزینه فیلد TestLoad مرحله آزمون CTest را تنظیم می‌نماید.

بی‌صدا کردن CTest.

این گزینه تمام خروجی‌ها را مسدود می‌کند. در صورتی که --output-log مشخص شده باشد، فایل لاگ خروجی همچنان ایجاد خواهد شد. در صورت مشخص شدن --quiet، گزینه‌هایی مانند --verbose، --extra-verbose و --debug نادیده گرفته می‌شوند.

ارسال خروجی به فایل گزارش (log).

این گزینه به CTest دستور می‌دهد تمام خروجی‌های خود را در فایل گزارش <file> بنویسد.

افزوده‌شده در نسخه 3.21.

نوشتن نتایج آزمون در قالب JUnit.

این گزینه به CTest دستور می‌دهد نتایج آزمون را در قالب XML جی‌یونیت (JUnit XML) در <file> بنویسد. اگر <file> از قبل وجود داشته باشد، رونویسی خواهد شد. در صورت استفاده از گزینه -S برای اجرای یک اسکریپت داشبورد، به جای آن از کلمه کلیدی OUTPUT_JUNIT همراه با دستور ctest_test() <#command:ctest_test> استفاده کنید.

غیرفعال کردن اجرای واقعی آزمون‌ها.

این گزینه به CTest دستور می‌دهد آزمون‌هایی را که قرار است اجرا شوند فهرست کند، اما عملاً آن‌ها را اجرا نکند. در ترکیب با گزینه‌های -R و -E مفید است.

افزوده‌شده در نسخه 3.14: گزینه --show-only یک مقدار <format> می‌پذیرد.

مقدار <format> می‌تواند یکی از مقادیر زیر باشد:

خروجی خوانا برای انسان. پایدار بودن این قالب تضمین نمی‌شود. این حالت پیش‌فرض است.
تخلیه اطلاعات آزمون در قالب JSON. بخش Show as JSON Object Model را ببینید.
اجرای آزمون‌هایی با برچسب‌های منطبق بر عبارت باقاعده، همان‌طور که در string(REGEX) <#regex-specification> توضیح داده شده است.

این گزینه به CTest دستور می‌دهد تنها آزمون‌هایی را اجرا کند که برچسب‌های آن‌ها با عبارت باقاعده داده‌شده مطابقت داشته باشد. هنگامی که بیش از یک گزینه -L داده شود، یک آزمون تنها در صورتی اجرا می‌شود که هر عبارت باقاعده دست‌کم با یکی از برچسب‌های آزمون مطابقت کند (یعنی برچسب‌های چندگانه -L یک رابطه AND تشکیل می‌دهند). بخش Label Matching را ببینید.

اجرای آزمون‌های منطبق با عبارت باقاعده.

این گزینه به CTest دستور می‌دهد فقط آزمون‌هایی را اجرا کند که نام آن‌ها با عبارت باقاعده داده‌شده مطابقت دارد.

مستثنی کردن آزمون‌های منطبق با عبارت باقاعده.

این گزینه به CTest دستور می‌دهد آزمون‌هایی را که نام آن‌ها با عبارت باقاعده داده‌شده مطابقت دارد اجرا نکند.

مستثنی کردن آزمون‌هایی با برچسب‌های منطبق با عبارت باقاعده.

این گزینه به CTest دستور می‌دهد آزمون‌هایی را که برچسب‌های آن‌ها با عبارت باقاعده داده‌شده مطابقت دارد اجرا نکند. هنگامی که بیش از یک گزینه -LE داده شود، یک آزمون تنها در صورتی مستثنی می‌شود که هر عبارت باقاعده دست‌کم با یکی از برچسب‌های آزمون مطابقت داشته باشد (یعنی برچسب‌های چندگانه -LE یک رابطه AND تشکیل می‌دهند). بخش Label Matching را ببینید.

افزوده‌شده در نسخه 3.29.

اجرای آزمون‌های فهرست‌شده در فایل مشخص‌شده.

این گزینه به CTest دستور می‌دهد آزمون‌هایی را که در فایل داده‌شده فهرست شده‌اند اجرا کند. فایل باید در هر سطر دقیقاً شامل نام یک آزمون باشد. سطرهایی که دقیقاً با هیچ نام آزمونی مطابقت ندارند نادیده گرفته می‌شوند. این گزینه می‌تواند با گزینه‌های دیگری مانند -R، -E، -L یا -LE ترکیب شود.

افزوده‌شده در نسخه 3.29.

مستثنی کردن آزمون‌های فهرست‌شده در فایل داده‌شده.

این گزینه به CTest اعلام می‌کند آزمون‌هایی را که در فایل داده‌شده فهرست شده‌اند اجرا نکند. فایل باید در هر سطر شامل نام دقیق یک آزمون باشد. سطرهایی که دقیقاً با هیچ نام آزمونی مطابقت ندارند نادیده گرفته می‌شوند. این گزینه می‌تواند با گزینه‌های دیگری مانند -R، -E، -L یا -LE ترکیب شود.

مستثنی کردن فیکسچرهای منطبق با <regex> از افزودن خودکار هرگونه آزمون به مجموعه آزمون‌ها.

اگر آزمونی در مجموعه آزمون‌های در حال اجرا نیازمند یک فیکسچر خاص باشد، آزمون‌های راه‌اندازی و پاک‌سازی آن فیکسچر به طور طبیعی و خودکار به مجموعه آزمون‌ها افزوده می‌شوند. این گزینه از افزودن آزمون‌های راه‌اندازی یا پاک‌سازی برای فیکسچرهای منطبق با <regex> جلوگیری می‌کند. توجه داشته باشید که تمام رفتارهای دیگر فیکسچر حفظ می‌شوند، از جمله وابستگی‌های آزمون و صرف‌نظر کردن از آزمون‌هایی که آزمون‌های راه‌اندازی فیکسچر آن‌ها با شکست مواجه شده است.

مشابه -FA، با این تفاوت که تنها آزمون‌های راه‌اندازی منطبق مستثنی می‌شوند.
مشابه -FA، با این تفاوت که تنها آزمون‌های پاک‌سازی منطبق مستثنی می‌شوند.
اجرای تعداد مشخصی از آزمون‌ها بر اساس شماره.

این گزینه باعث می‌شود CTest آزمون‌ها را با شروع از شماره Start، پایان در شماره End و با گام‌های افزایشی Stride اجرا کند. هرگونه شماره اضافی بعد از Stride به عنوان شماره آزمون جداگانه در نظر گرفته می‌شود. مقادیر Start، End یا Stride می‌توانند خالی باشند. همچنین می‌توان فایلی را مشخص کرد که شامل همان قواعد نگارشی خط فرمان باشد.

در نظر گرفتن اجتماع گزینه‌های -I و -R.

هنگامی که هر دو گزینه -R و -I مشخص شده باشند، به طور پیش‌فرض اشتراک آزمون‌ها اجرا می‌شود. با تعیین -U به جای آن اجتماع آزمون‌ها اجرا خواهد شد.

تنها اجرای آزمون‌هایی که قبلاً شکست خورده‌اند.

این گزینه به CTest اعلام می‌کند فقط آزمون‌هایی را انجام دهد که در اجرای قبلی شکست خورده‌اند. هنگامی که این گزینه مشخص شود، CTest تمام گزینه‌های دیگر را که برای تغییر فهرست آزمون‌های اجرایی در نظر گرفته شده‌اند (مانند -L، -R، -E، -LE، -I و غیره) نادیده می‌گیرد. در صورتی که CTest اجرا شود و هیچ آزمونی شکست نخورد، فراخوانی‌های بعدی CTest با گزینه --rerun-failed مجموعه آزمون‌هایی را اجرا خواهد کرد که اخیراً شکست خورده بودند (در صورت وجود).

اجرای مکرر آزمون‌ها بر اساس <mode> داده‌شده تا سقف <n> بار. حالت‌ها عبارتند از:
الزام به اجرای هر آزمون تا <n> بار بدون شکست برای قبولی. این حالت برای یافتن خطاهای متناوب و تصادفی در موارد آزمون مفید است.
امکان اجرای هر آزمون تا سقف <n> بار به منظور قبولی. در صورت شکست آزمون‌ها به هر دلیلی، آن‌ها را تکرار می‌کند. این حالت برای تحمل خطاهای تصادفی در موارد آزمون مفید است.
امکان اجرای هر آزمون تا سقف <n> بار به منظور قبولی. آزمون‌ها را تنها در صورت اتمام مهلت زمانی (timeout) تکرار می‌کند. این حالت برای تحمل پایان مهلت‌های زمانی تصادفی در موارد آزمون روی سیستم‌های شلوغ مفید است.
معادل --repeat until-fail:<n>.
تعیین حداکثر عرض نام آزمون در خروجی.

تنظیم حداکثر عرض برای نمایش نام هر آزمون در خروجی. این به کاربر امکان می‌دهد پهنای خروجی را افزایش دهد تا از بریده شدن نام آزمون که می‌تواند بسیار آزاردهنده باشد جلوگیری شود.

غیرفعال‌سازی (0) یا فعال‌سازی (1) حالت اشکال‌زدایی تعاملی.

این گزینه باعث می‌شود CTest آزمون‌ها را در حالت تعاملی یا غیرتعاملی اجرا کند. در حالت پیشخوان (Experimental، Nightly، Continuous)، حالت پیش‌فرض غیرتعاملی است. در حالت غیرتعاملی، متغیر محیطی DASHBOARD_TEST_FROM_CTEST <#envvar:DASHBOARD_TEST_FROM_CTEST> تنظیم می‌شود.

حالت تعاملی به گزارش خطای ویندوز (WER) اجازه می‌دهد پنجره‌های بالاپر اشکال‌زدایی را نشان داده و دامپ هسته ایجاد کند. برای فعال کردن دامپ‌های هسته در آزمون‌ها، از حالت تعاملی استفاده کرده و مستندات ویندوز درباره Collecting User-Mode Dumps https://learn.microsoft.com/en-us/windows/win32/wer/collecting-user-mode-dumps را دنبال کنید.

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

تغییریافته در نسخه 3.11: گزارش خطای ویندوز (WER) در هر دو حالت تعاملی و غیرتعاملی غیرفعال است، بنابراین فرآیندهای آزمون پنجره‌های بالاپر نشان نمی‌دهند یا دامپ هسته ایجاد نمی‌کنند. این موضوع به دلیل راه‌اندازی فرآیندهای آزمون با libuv است.

غیرفعال‌سازی اطلاعات خلاصه زمان‌بندی برای برچسب‌ها.

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

بخش Label and Subproject Summary را ببینید.

غیرفعال‌سازی اطلاعات خلاصه زمان‌بندی برای زیرپروژه‌ها.

این گزینه به CTest اعلام می‌کند اطلاعات خلاصه را برای هر زیرپروژه مرتبط با آزمون‌های اجراشده چاپ نکند. اگر هیچ زیرپروژه‌ای روی آزمون‌ها وجود نداشته باشد، هیچ چیز اضافی چاپ نمی‌شود.

بخش Label and Subproject Summary را ببینید.

افزوده‌شده در نسخه 3.20.

مشخص کردن دایرکتوری مورد جستجو برای آزمون‌ها، که معمولاً دایرکتوری ساخت یک پروژه CMake است. در صورت مشخص نشدن، از دایرکتوری جاری استفاده می‌شود. همچنین --build-dir را ببینید.

افزوده‌شده در نسخه 3.4.

محدود کردن اندازه خروجی آزمون‌های موفق به <size> بایت.

افزوده‌شده در نسخه 3.4.

محدود کردن اندازه خروجی آزمون‌های شکست‌خورده به <size> بایت.

افزوده‌شده در نسخه 3.24.

کوتاه‌سازی و برش بخش پایانی (tail، پیش‌فرض)، میانی (middle) یا ابتدایی (head) خروجی آزمون به محض رسیدن به حداکثر اندازه مجاز خروجی.

بازنویسی گزینه پیکربندی CTest.

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

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

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

افزوده‌شده در نسخه 4.1.

بازنویسی بذر (seed) مربوط به ترتیب تصادفی.

این گزینه برای امکان بازتولید شکست‌های ناشی از ترتیب تصادفی اجرا توسط --schedule-random استفاده می‌شود.

گزینه قدیمی برای قابلیت سرور پیشخوان قدیمی Dart2. استفاده نکنید.
تنظیم مهلت زمانی (timeout) پیش‌فرض آزمون‌ها.

این گزینه در عمل مهلت زمانی را برای تمام آزمون‌هایی که قبلاً از طریق ویژگی TIMEOUT <#prop_test:TIMEOUT> مهلت زمانی برای آن‌ها تعیین نشده است اعمال می‌کند.

تنظیم زمانی که در آن تمام آزمون‌ها باید متوقف شوند.

تعیین یک ساعت واقعی از شبانه‌روز که در آن زمان مهلت تمام آزمون‌ها به پایان برسد. مثال: 7:00:00 -0400. هر فرمت زمانی قابل فهم برای تجزیه‌کننده تاریخ curl پذیرفته می‌شود. در صورت عدم تعیین منطقه زمانی، زمان محلی فرض خواهد شد.

چاپ تمام برچسب‌های آزمون موجود.

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

تعیین رفتار سیستم در زمانی که هیچ آزمونی اجرا نمی‌شود؛ برای نمونه هنگامی که CTestTestfile.cmake هیچ آزمونی تعریف نکرده است، یا وقتی آرگومان‌های داده‌شده همه آزمون‌ها را مستثنی کرده‌اند. مقدار <action> می‌تواند یکی از موارد زیر باشد:
اجرا نشدن هیچ آزمونی را به عنوان یک خطا در نظر بگیرد.

این حالت در هنگام اجرای اسکریپت‌های ctest -S حالت پیش‌فرض است.

اجرا نشدن هیچ آزمونی را عادی تلقی کند.

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

افزوده‌شده در نسخه 3.26.

این گزینه می‌تواند با تنظیم متغیر محیطی CTEST_NO_TESTS_ACTION <#envvar:CTEST_NO_TESTS_ACTION> نیز تعیین شود.

افزوده‌شده در نسخه 4.0.

جمع‌آوری دستی داده‌های سنجش (instrumentation) از دایرکتوری ساخت مشخص‌شده. برای جزئیات بیشتر، بخش Indexing <#cmake-instrumentation-indexing> از سنجش CMake را ببینید.

-- <test-args>...
افزوده‌شده در نسخه 4.4.

ارسال آرگومان‌های اضافی به فایل‌های اجرایی آزمون.

تمام آرگومان‌های پس از -- به انتهای خط فرمان هر آزمون اجراشده الحاق می‌شوند. این ویژگی برای ارسال گزینه‌ها به چارچوب‌های آزمون مانند Google Test یا doctest مفید است. برای مثال:

ctest -R my_test -- --gtest_filter=SomeTest.Case
ctest --verbose -- --success

تمام آزمون‌های انتخاب‌شده آرگومان‌های اضافی یکسانی دریافت می‌کنند. از -R یا -L برای محدود کردن آزمون‌های اجرایی استفاده کنید.

یک -- به تنهایی و بدون آرگومان‌های پس از آن، بدون هشدار نادیده گرفته می‌شود.

هنگامی که هر دو مورد <test-args> و testPassthroughArguments <#cmakepresets-testpresets-execution-testpassthrougharguments> ارائه شوند، آرگومان‌های پیش‌تنظیم آزمون ابتدا قرار می‌گیرند و پس از آن‌ها <test-args> می‌آیند.

برای چاپ جزئیات نسخه یا صفحات برگزیده‌ای از مستندات CMake، از یکی از گزینه‌های زیر استفاده کنید:

بنر نام و نسخه برنامه را نمایش داده و خارج می‌شود. اگر json-v1 مشخص شده باشد، اطلاعات تفصیلی نسخه را در قالب JSON چاپ می‌کند. خروجی JSON حاوی نسخه‌های CMake و وابستگی‌های آن است. در صورت ارائه نام <file>، خروجی در آن نوشته می‌شود.

قالب خروجی JSON به شکل خوانا برای ماشین در this JSON schema توصیف شده است.

اطلاعات نحوه استفاده را چاپ کرده و خارج می‌شود.

نحوه استفاده، رابط خط فرمان پایه و گزینه‌های آن را شرح می‌دهد.

راهنما را برای یک کلیدواژه CMake چاپ می‌کند.

کلیدواژه <keyword> می‌تواند یک ویژگی (property)، متغیر، دستور، خط‌مشی (policy)، تولیدکننده (generator) یا ماژول باشد.

مدخل مربوطه در کتابچه راهنما برای <keyword> در یک قالب متنی خوانا برای انسان چاپ می‌شود. در صورت ارائه نام <file>، خروجی در آن نوشته می‌شود.

تغییریافته در نسخه 3.28: پیش از CMake 3.28، این گزینه تنها از نام دستورات پشتیبانی می‌کرد.

تمام کتابچه‌های راهنما را چاپ کرده و خارج می‌شود.

تمام کتابچه‌های راهنما در یک قالب متنی خوانا برای انسان چاپ می‌شوند. در صورت ارائه نام <file>، خروجی در آن نوشته می‌شود.

یک کتابچه راهنما را چاپ کرده و خارج می‌شود.

کتابچه راهنمای مشخص‌شده در یک قالب متنی خوانا برای انسان چاپ می‌شود. در صورت ارائه نام <file>، خروجی در آن نوشته می‌شود.

کتابچه‌های راهنمای موجود را فهرست کرده و خارج می‌شود.

این فهرست شامل تمام کتابچه‌های راهنمایی است که می‌توان با استفاده از گزینه --help-manual همراه با نام کتابچه به راهنمای آن‌ها دست یافت. در صورت ارائه نام <file>، خروجی در آن نوشته می‌شود.

راهنما را برای یک دستور چاپ کرده و خارج می‌شود.

مدخل کتابچه راهنمای cmake-commands(7) <#manual:cmake-commands(7)> برای <cmd> در یک قالب متنی خوانا برای انسان چاپ می‌شود. در صورت ارائه نام <file>، خروجی در آن نوشته می‌شود.

دستوراتی را که راهنمای آن‌ها موجود است فهرست کرده و خارج می‌شود.

این فهرست شامل تمام دستوراتی است که می‌توان با استفاده از گزینه --help-command همراه با نام دستور به راهنمای آن‌ها دست یافت. در صورت ارائه نام <file>، خروجی در آن نوشته می‌شود.

کتابچه راهنمای cmake-commands را چاپ کرده و خارج می‌شود.

کتابچه راهنمای cmake-commands(7) <#manual:cmake-commands(7)> در یک قالب متنی خوانا برای انسان چاپ می‌شود. در صورت ارائه نام <file>، خروجی در آن نوشته می‌شود.

راهنما را برای یک ماژول چاپ کرده و خارج می‌شود.

مدخل کتابچه راهنمای cmake-modules(7) <#manual:cmake-modules(7)> برای <mod> در یک قالب متنی خوانا برای انسان چاپ می‌شود. در صورت ارائه نام <file>، خروجی در آن نوشته می‌شود.

ماژول‌هایی را که راهنمای آن‌ها موجود است فهرست کرده و خارج می‌شود.

این فهرست شامل تمام ماژول‌هایی است که می‌توان با استفاده از گزینه --help-module همراه با نام ماژول به راهنمای آن‌ها دست یافت. در صورت ارائه نام <file>، خروجی در آن نوشته می‌شود.

کتابچه راهنمای cmake-modules را چاپ کرده و خارج می‌شود.

کتابچه راهنمای cmake-modules(7) <#manual:cmake-modules(7)> در یک قالب متنی خوانا برای انسان چاپ می‌شود. در صورت ارائه نام <file>، خروجی در آن نوشته می‌شود.

راهنما را برای یک خط‌مشی چاپ کرده و خارج می‌شود.

مدخل کتابچه راهنمای cmake-policies(7) <#manual:cmake-policies(7)> برای <cmp> در یک قالب متنی خوانا برای انسان چاپ می‌شود. در صورت ارائه نام <file>، خروجی در آن نوشته می‌شود.

خط‌مشی‌هایی را که راهنمای آن‌ها موجود است فهرست کرده و خارج می‌شود.

این فهرست شامل تمام خط‌مشی‌هایی است که می‌توان با استفاده از گزینه --help-policy همراه با نام خط‌مشی به راهنمای آن‌ها دست یافت. در صورت ارائه نام <file>، خروجی در آن نوشته می‌شود.

کتابچه راهنمای cmake-policies را چاپ کرده و خارج می‌شود.

کتابچه راهنمای cmake-policies(7) <#manual:cmake-policies(7)> در یک قالب متنی خوانا برای انسان چاپ می‌شود. در صورت ارائه نام <file>، خروجی در آن نوشته می‌شود.

راهنما را برای یک ویژگی چاپ کرده و خارج می‌شود.

مدخل‌های کتابچه راهنمای cmake-properties(7) <#manual:cmake-properties(7)> برای <prop> در یک قالب متنی خوانا برای انسان چاپ می‌شوند. در صورت ارائه نام <file>، خروجی در آن نوشته می‌شود.

ویژگی‌هایی را که راهنمای آن‌ها موجود است فهرست کرده و خارج می‌شود.

این فهرست شامل تمام ویژگی‌هایی است که می‌توان با استفاده از گزینه --help-property همراه با نام ویژگی به راهنمای آن‌ها دست یافت. در صورت ارائه نام <file>، خروجی در آن نوشته می‌شود.

کتابچه راهنمای cmake-properties را چاپ کرده و خارج می‌شود.

کتابچه راهنمای cmake-properties(7) <#manual:cmake-properties(7)> در یک قالب متنی خوانا برای انسان چاپ می‌شود. در صورت ارائه نام <file>، خروجی در آن نوشته می‌شود.

راهنما را برای یک متغیر چاپ کرده و خارج می‌شود.

مدخل کتابچه راهنمای cmake-variables(7) <#manual:cmake-variables(7)> برای <var> در یک قالب متنی خوانا برای انسان چاپ می‌شود. در صورت ارائه نام <file>، خروجی در آن نوشته می‌شود.

متغیرهایی را که راهنمای آن‌ها موجود است فهرست کرده و خارج می‌شود.

این فهرست شامل تمام متغیرهایی است که می‌توان با استفاده از گزینه --help-variable همراه با نام متغیر به راهنمای آن‌ها دست یافت. در صورت ارائه نام <file>، خروجی در آن نوشته می‌شود.

کتابچه راهنمای cmake-variables را چاپ کرده و خارج می‌شود.

کتابچه راهنمای cmake-variables(7) <#manual:cmake-variables(7)> در یک قالب متنی خوانا برای انسان چاپ می‌شود. در صورت ارائه نام <file>، خروجی در آن نوشته می‌شود.

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

هنگامی که -L استفاده می‌شود، برای اینکه یک آزمون در یک اجرای آزمون گنجانده شود، هر عبارت باقاعده باید حداقل با یک برچسب مطابقت داشته باشد. استفاده از بیش از یک گزینه -L به معنای "تطبیق با همه این موارد" است.

گزینه -LE دقیقاً مانند -L عمل می‌کند، اما آزمون‌ها را به جای گنجاندن، مستثنی می‌کند. یک آزمون در صورتی مستثنی می‌شود که هر عبارت باقاعده با حداقل یک برچسب مطابقت داشته باشد.

اگر آزمونی هیچ برچسبی متصل به خود نداشته باشد، آن‌گاه -L هرگز آن آزمون را شامل نخواهد شد، و -LE نیز هرگز آن آزمون را مستثنی نخواهد کرد. به عنوان مثالی از آزمون‌های دارای برچسب، پنج آزمون را با برچسب‌های زیر در نظر بگیرید:

  • آزمون test1 دارای برچسب‌های tuesday و production است
  • آزمون test2 دارای برچسب‌های tuesday و test است
  • آزمون test3 دارای برچسب‌های wednesday و production است
  • آزمون test4 دارای برچسب wednesday است
  • آزمون test5 دارای برچسب‌های friday و test است

اجرای ctest با -L tuesday -L test آزمون test2 را انتخاب خواهد کرد که هر دو برچسب را دارد. اجرای CTest با -L test آزمون‌های test2 و test5 را انتخاب می‌کند، زیرا هر دوی آن‌ها برچسبی دارند که با آن عبارت باقاعده مطابقت دارد.

از آنجا که تطبیق با عبارات باقاعده کار می‌کند، توجه داشته باشید که اجرای CTest با -L es با هر پنج آزمون تطابق خواهد داشت. برای انتخاب آزمون‌های tuesday و wednesday به همراه یکدیگر، از یک عبارت باقاعده منفرد استفاده کنید که با هر یک از آن‌ها تطابق داشته باشد، مانند -L "tue|wed".

ابزار CTest اطلاعات خلاصه زمان‌بندی را برای هر LABEL و زیرپروژه مرتبط با آزمون‌های اجراشده چاپ می‌کند. خلاصه زمان برچسب شامل برچسب‌هایی که به زیرپروژه‌ها نگاشت شده‌اند نخواهد بود.

افزوده‌شده در نسخه 3.22: برچسب‌هایی که به صورت پویا در طول اجرای آزمون اضافه می‌شوند نیز در خلاصه زمان‌بندی گزارش می‌شوند. بخش Additional Labels <#additional-labels> را ببینید.

هنگامی که ویژگی آزمون PROCESSORS <#prop_test:PROCESSORS> تنظیم شده باشد، CTest یک نتیجه زمان‌بندی وزنی آزمون را در خلاصه برچسب‌ها و زیرپروژه‌ها نمایش می‌دهد. زمان به جای تنها sec، با sec * proc گزارش می‌شود.

خلاصه زمان وزن‌دار گزارش‌شده برای هر برچسب یا زیرپروژه j به صورت زیر محاسبه می‌شود:

Weighted Time Summary for Label/Subproject j =
    sum(raw_test_time[j,i] * num_processors[j,i], i=1...num_tests[j])
for labels/subprojects j=1...total

که در آن:

  • raw_test_time[j,i]: زمان واقعی (Wall-clock time) برای آزمون i مربوط به برچسب یا زیرپروژه j
  • num_processors[j,i]: مقدار ویژگی PROCESSORS <#prop_test:PROCESSORS> در CTest برای آزمون i مربوط به برچسب یا زیرپروژه j
  • num_tests[j]: تعداد آزمون‌های مرتبط با برچسب یا زیرپروژه j
  • total: تعداد کل برچسب‌ها یا زیرپروژه‌هایی که حداقل یک آزمون اجراشده دارند

بنابراین، خلاصه زمان وزن‌دار برای هر برچسب یا زیرپروژه نشان‌دهنده مدت زمانی است که CTest به اجرای آزمون‌های هر برچسب یا زیرپروژه اختصاص داده است و نمایش مناسبی از هزینه کل آزمون‌ها برای هر برچسب یا زیرپروژه در مقایسه با سایر برچسب‌ها یا زیرپروژه‌ها ارائه می‌دهد.

به عنوان مثال، اگر SubprojectA مقدار 100 sec*proc و SubprojectB مقدار 10 sec*proc را نشان دهد، آن‌گاه CTest تقریباً ۱۰ برابر زمان پردازنده/هسته بیشتری را برای اجرای آزمون‌های SubprojectA نسبت به SubprojectB اختصاص داده است (مثلاً اگر قرار باشد تلاشی برای کاهش هزینه مجموعه آزمون برای کل پروژه صرف شود، کاهش هزینه مجموعه آزمون برای SubprojectA احتمالاً تأثیر بیشتری نسبت به تلاش برای کاهش هزینه مجموعه آزمون برای SubprojectB خواهد داشت).

ابزار CTest یک ساختار خط فرمانی برای پیکربندی (یعنی اجرای cmake روی آن)، ساخت و/یا اجرای یک آزمون ارائه می‌دهد:

ctest --build-and-test <path-to-source> <path-to-build>
      --build-generator <generator>
      [<options>...]
      [--build-options <opts>...]
      [--test-command <command> [<args>...]]

مراحل پیکربندی و آزمون اختیاری هستند. آرگومان‌های این خط فرمان دایرکتوری‌های سورس و باینری هستند. برای استفاده از --build-and-test گزینهٔ --build-generator باید مشخص شود. اگر --test-command مشخص شده باشد، پس از اتمام ساخت اجرا خواهد شد. سایر گزینه‌هایی که بر این حالت اثر می‌گذارند عبارتند از:

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

اگر هیچ --build-target مشخص نشود، تارگت all ساخته می‌شود.

اجرای فرآیند ساخت بدون اجرای اولیهٔ cmake.

صرف‌نظر کردن از مرحلهٔ cmake.

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

دایرکتوری که برنامه‌ها پس از کامپایل در آن قرار خواهند داشت.

اجرای دو بارهٔ CMake (دو بار اجرای متوالی).
مشخص کردن دایرکتوری فایل اجرایی.
مشخص کردن ژنراتور (تولیدکننده) مورد استفاده. راهنمای cmake-generators(7) <#manual:cmake-generators(7)> را ببینید.
مشخص کردن پلتفرم ویژهٔ ژنراتور.
مشخص کردن جعبه‌ابزار (toolset) ویژهٔ ژنراتور.
مشخص کردن نام پروژه‌ای که باید ساخته شود.
مشخص کردن برنامهٔ make صریح برای استفاده توسط CMake هنگام پیکربندی و ساخت پروژه. این گزینه تنها برای ژنراتورهای Makefile <#makefile-generators> و ژنراتورهای Ninja <#ninja-generators> کاربرد دارد.
صرف‌نظر کردن از مرحلهٔ make clean.
یک فایل اجرایی نمونه برای استفاده در تعیین پیکربندی مورد نظر (مانند Debug، Release و غیره).
گزینه‌های اضافی برای پیکربندی فرآیند ساخت (یعنی برای cmake(1) <#manual:cmake(1)>، نه برای ابزار ساخت). توجه داشته باشید که در صورت مشخص شدن، کلمهٔ کلیدی --build-options و آرگومان‌های آن باید آخرین گزینهٔ ارائه‌شده در خط فرمان باشند، به استثنای احتمالی --test-command.
دستوری که باید به عنوان مرحلهٔ آزمون همراه با گزینهٔ --build-and-test اجرا شود. تمامی آرگومان‌های بعد از این کلمهٔ کلیدی به عنوان بخشی از خط فرمان دستور آزمون در نظر گرفته خواهند شد، بنابراین باید آخرین گزینهٔ ارائه‌شده باشد.
محدودیت زمانی بر حسب ثانیه.

ابزار CTest می‌تواند به عنوان یک کلاینت برای برنامهٔ داشبورد کیفیت نرم‌افزار CDash https://www.cdash.org عمل کند. ابزار CTest در نقش کلاینت داشبورد، دنباله‌ای از مراحل را برای پیکربندی، ساخت و آزمون نرم‌افزار انجام می‌دهد و سپس نتایج را به یک سرور CDash https://www.cdash.org ارسال می‌کند. ساختار خط فرمانی مورد استفاده برای ارسال به CDash https://www.cdash.org عبارت است از:

ctest -D <dashboard>         [-- <dashboard-options>...]
ctest -M <model> -T <action> [-- <dashboard-options>...]
ctest -S <script>            [-- <dashboard-options>...]
ctest -SP <script>           [-- <dashboard-options>...]

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

اجرای آزمون داشبورد.

این گزینه به CTest اعلام می‌کند که به عنوان کلاینت CDash عمل کرده و یک آزمون داشبورد را انجام دهد. تمامی آزمون‌ها به صورت <Mode><Test> هستند، که در آن <Mode> می‌تواند Experimental، Nightly و Continuous باشد، و <Test> می‌تواند Start، Update، Configure، Build، Test، Coverage و Submit باشد.

اگر <dashboard> یکی از مقادیر شناخته‌شدهٔ <Mode><Test> نباشد، به جای آن به عنوان تعریف یک متغیر در نظر گرفته خواهد شد (بخش dashboard-options در ادامه را ببینید).

تنظیم مدل برای یک داشبورد.

این گزینه به CTest اعلام می‌کند که به عنوان کلاینت CDash عمل کند که در آن <model> می‌تواند Experimental، Nightly و Continuous باشد. ترکیب کردن -M و -T مشابه -D است.

تنظیم اقدام (action) داشبورد برای اجرا.

این گزینه به CTest اعلام می‌کند که به عنوان کلاینت CDash عمل کرده و اقدامی مانند start، build، test و غیره را انجام دهد. برای فهرست کامل اقدامات، بخش «مراحل کلاینت داشبورد» را ببینید. ترکیب کردن -M و -T مشابه -D است.

اجرای یک داشبورد برای یک پیکربندی.

این گزینه به CTest اعلام می‌کند که یک اسکریپت پیکربندی را بارگذاری کند که تعدادی از پارامترها مانند دایرکتوری‌های باینری و سورس را مقداردهی می‌کند. سپس CTest اقدامات لازم را برای ایجاد و اجرای یک داشبورد انجام خواهد داد. این گزینه اساساً یک داشبورد را برپا می‌کند و سپس ctest -D را با گزینه‌های مناسب اجرا می‌نماید.

اجرای یک داشبورد برای یک پیکربندی.

این گزینه همان عملیات -S را انجام می‌دهد اما آن را در یک پردازش جداگانه انجام خواهد داد. این گزینه در درجهٔ اول در مواردی مفید است که اسکریپت ممکن است متغیرهای محیطی را تغییر دهد و شما نمی‌خواهید این محیطِ تغییریافته بر سایر اسکریپت‌های -S تأثیر بگذارد.

گزینه‌های <dashboard-options> موجود شامل موارد زیر است:

تعریف یک متغیر برای حالت کلاینت داشبورد.

ارسال مقادیر متغیرها از طریق خط فرمان. در ترکیب با -S برای ارسال مقادیر متغیرها به یک اسکریپت داشبورد، یا با -T برای بازنویسی تنظیمات پیکربندی کلاینت داشبورد استفاده می‌شود. تجزیهٔ آرگومان‌های -D به عنوان مقادیر متغیر تنها در صورتی بررسی می‌شود که مقدارِ پس از -D با هیچ‌یک از انواع شناخته‌شدهٔ داشبورد مطابقت نداشته باشد.

قالب <var>:<type>=<value> هر نام متغیری را می‌پذیرد. قالب ساده‌ترِ <var>=<value> (بدون تعیین نوع) تنها برای متغیرهایی پذیرفته می‌شود که نام آن‌ها با CTEST_ آغاز شود. در هر دو حالت، هنگام استفاده از -T، این مقدار تنظیمات متناظر را از فایل پیکربندی کلاینت داشبورد (مانند DartConfiguration.tcl) بازنویسی می‌کند.

نکته:

این تعاریف، متغیرهای اسکریپت CTest را مقداردهی می‌کنند (مانند CTEST_BUILD_NAME <#variable:CTEST_BUILD_NAME>)، نه متغیرهای کش CMake را. برای ارسال متغیرهای کش CMake به مرحلهٔ پیکربندی، استفاده از یک اسکریپت CTest، یک configure preset <#manual:cmake-presets(7)>، یا تنظیم CTEST_CONFIGURE_COMMAND <#variable:CTEST_CONFIGURE_COMMAND> را در نظر بگیرید.
افزوده‌شده در نسخهٔ 4.4.

مشخص کردن دایرکتوری سورس پروژه. در صورت ترکیب با -T Configure، به CTest اجازه می‌دهد تا یک مرحلهٔ پیکربندی اولیه را برای یک دایرکتوری باینری خالی انجام دهد. دایرکتوری باینری به طور پیش‌فرض روی دایرکتوری کاری جاری تنظیم است؛ از --build-dir برای مشخص کردن مکانی دیگر استفاده کنید. اگر دایرکتوری باینری هنوز وجود نداشته باشد، به طور خودکار ایجاد می‌شود.

هنگامی که یک configure preset <#manual:cmake-presets(7)> مشخص شود که ویژگی binaryDir <#cmakepresets-configurepresets-binarydir> را تعریف کرده باشد، CTest به طور خودکار از آن مسیر به عنوان دایرکتوری باینری استفاده می‌کند (بدون نیاز به --build-dir). یک گزینهٔ صریح --build-dir بر مقدار binaryDir <#cmakepresets-configurepresets-binarydir> در پیش‌تنظیم اولویت دارد.

یک تولیدکنندهٔ CMake نیز باید مشخص شود. از -D CTEST_CMAKE_GENERATOR=<gen>; برای معرفی آن استفاده کنید، یا CTEST_CONFIGURE_PRESET <#variable:CTEST_CONFIGURE_PRESET> را برای تعیین یک configure preset <#manual:cmake-presets(7)> تنظیم نمایید که شامل یک generator <#cmakepresets-configurepresets-generator> باشد.

برای جزئیات بیشتر، تنظیمات مرحلهٔ CTest Configure را ببینید.

افزوده‌شده در نسخهٔ 4.4.

مشخص کردن دایرکتوری باینری (ساخت) پروژه. این یک نام مستعار برای --test-dir است که برای استفاده به همراه --source-dir هنگام راه‌اندازی اولیهٔ فرآیند ساخت با -T Configure در نظر گرفته شده است.

مشخص کردن گروهی که نتایج باید به آن ارسال شوند.

ارسال داشبورد به گروه مشخص‌شده به جای گروه پیش‌فرض. به طور پیش‌فرض، داشبورد به گروه Nightly، Experimental یا Continuous ارسال می‌شود، اما با تعیین این گزینه، گروه می‌تواند دلخواه باشد.

این گزینه جایگزین گزینهٔ منسوخ‌شدهٔ --track می‌شود. علیرغم تغییر نام، رفتار آن بدون تغییر باقی مانده است.

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

این گزینه به CTest اعلام می‌کند که هنگام ارسال داشبورد، یک فایل یادداشت را نیز ضمیمه کند.

شروع آزمون‌های Nightly یا Experimental با برچسب روز بعد.

این گزینه زمانی مفید است که فرآیند ساخت در یک روز به پایان نرسد.

ارسال فایل‌های پارت .xml اضافی به داشبورد. گزینهٔ PARTS ExtraFiles در دستور ctest_submit() <#command:ctest_submit> را ببینید.
افزوده‌شده در نسخهٔ 3.29.

پیوست کردن هدر HTTP هنگام ارسال به داشبورد.

این گزینه باعث می‌شود CTest هدر مشخص‌شده را هنگام ارسال به داشبورد پیوست کند. این گزینه می‌تواند بیش از یک بار مشخص شود.

ارسال با استفاده از HTTP 1.0.

این گزینه CTest را ملزم می‌کند تا به جای HTTP 1.1، از HTTP 1.0 برای ارسال فایل‌ها به داشبورد استفاده کند.

عدم فشرده‌سازی خروجی آزمون هنگام ارسال.

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

ابزار CTest یک فهرست ترتیبی از مراحل آزمون را تعریف می‌کند که ممکن است برخی یا همهٔ آن‌ها به عنوان کلاینت داشبورد اجرا شوند:

آغاز یک ارسال داشبورد جدید که از نتایج ثبت‌شده توسط مراحل بعدی تشکیل خواهد شد. بخش «مرحلهٔ CTest Start» در ادامه را ببینید.
به‌روزرسانی درخت سورس از مخزن سیستم کنترل نسخهٔ آن. ثبت نسخه‌های قدیمی و جدید و فهرست فایل‌های سورس به‌روزرسانی‌شده. بخش «مرحلهٔ CTest Update» در ادامه را ببینید.
پیکربندی نرم‌افزار با اجرای یک دستور در درخت ساخت. ثبت گزارش خروجی پیکربندی. بخش «مرحلهٔ CTest Configure» در ادامه را ببینید.
ساخت نرم‌افزار با اجرای یک دستور در درخت ساخت. ثبت گزارش خروجی ساخت و شناسایی هشدارها و خطاها. بخش «مرحلهٔ CTest Build» در ادامه را ببینید.
آزمون نرم‌افزار با بارگذاری یک فایل CTestTestfile.cmake از درخت ساخت و اجرای آزمون‌های تعریف‌شده. ثبت خروجی و نتیجهٔ هر آزمون. بخش «مرحلهٔ CTest Test» در ادامه را ببینید.
محاسبهٔ پوشش کد منبع با اجرای یک ابزار تحلیل پوشش و ثبت خروجی آن. بخش «مرحلهٔ CTest Coverage» در ادامه را ببینید.
اجرای مجموعه آزمون نرم‌افزار با استفاده از یک ابزار بررسی حافظه. ثبت خروجی آزمون، نتایج و اشکالات گزارش‌شده توسط ابزار. بخش «مرحلهٔ CTest MemCheck» در ادامه را ببینید.
ارسال نتایج ثبت‌شده از سایر مراحل آزمون به سرور داشبورد کیفیت نرم‌افزار. بخش «مرحلهٔ CTest Submit» در ادامه را ببینید.

ابزار CTest سه حالت عملکردی را به عنوان کلاینت داشبورد تعریف می‌کند:

این حالت برای فراخوانی یک بار در روز، معمولاً در طول شب، در نظر گرفته شده است. این حالت مراحل Start، Update، Configure، Build، Test، Coverage و Submit را به طور پیش‌فرض فعال می‌کند. مراحل انتخاب‌شده حتی اگر مرحلهٔ Update هیچ تغییری را در درخت سورس گزارش نکند، اجرا می‌شوند.
این حالت برای فراخوانی مکرر در طول روز در نظر گرفته شده است. این حالت مراحل Start، Update، Configure، Build، Test، Coverage و Submit را به طور پیش‌فرض فعال می‌کند، اما در صورتی که مرحلهٔ Update هیچ تغییری را در درخت سورس گزارش نکند، پس از آن مرحله پایان می‌یابد.
این حالت برای فراخوانی توسط توسعه‌دهنده جهت آزمودن تغییرات محلی در نظر گرفته شده است. این حالت مراحل Start، Configure، Build، Test، Coverage و Submit را به طور پیش‌فرض فعال می‌کند.

ابزار CTest می‌تواند فرآیند آزمون را روی یک درخت ساخت از قبل تولیدشده انجام دهد. دستور ctest را با تنظیم دایرکتوری کاری جاری بر روی درخت ساخت اجرا کنید و از یکی از این ساختارها استفاده نمایید:

ctest -D <mode>[<step>]
ctest -M <mode> [-T <step>]...

گزینهٔ --source-dir علاوه بر این اجازه می‌دهد تا مرحلهٔ Configure بر روی یک درخت ساخت که هنوز وجود ندارد انجام شود، که در این صورت گزینهٔ --build-dir مشخص می‌کند که در کجا ایجاد شود:

ctest [-M <mode>] -T Configure
    --source-dir <path-to-source> [--build-dir <path-to-build>]
ctest --build-and-test <path-to-source> <path-to-build>

مقدار <mode> باید یکی از «حالت‌های کلاینت داشبورد» بالا باشد، و هر <step> باید یکی از «مراحل کلاینت داشبورد» فوق باشد.

ابزار CTest تنظیمات پیکربندی کلاینت داشبورد را از یک فایل در درخت ساخت به نام CTestConfiguration.ini یا DartConfiguration.tcl می‌خواند (این نام‌ها جنبهٔ تاریخی دارند). قالب این فایل به این صورت است:

# Lines starting in '#' are comments.
# Other non-blank lines are key-value pairs.
<setting>: <value>

که در آن <setting> نام تنظیم و <value> مقدار تنظیم است.

در درخت‌های ساختی که توسط CMake تولید می‌شوند، این فایل پیکربندی توسط ماژول CTest <#module:CTest> در صورت گنجانده شدن در پروژه تولید می‌شود. این ماژول از متغیرها برای دریافت مقدار هر تنظیم مطابق با توضیحات ارائه‌شده در بخش تنظیمات در ادامه استفاده می‌کند.

ابزار CTest می‌تواند آزمون را با هدایت یک اسکریپت cmake-language(7) <#manual:cmake-language(7)> انجام دهد که علاوه بر اجرای مراحل آزمون، درخت‌های سورس و ساخت را ایجاد و نگهداری می‌کند. دستور ctest را با تنظیم دایرکتوری کاری جاری در خارج از هرگونه درخت ساخت اجرا کرده و از یکی از این ساختارها استفاده کنید:

ctest -S <script>
ctest -SP <script>

فایل <script> باید دستورات CTest Commands <#ctest-commands> را فراخوانی کند تا مراحل آزمون را به صورت صریح طبق توضیحات زیر اجرا نماید. این دستورات تنظیمات پیکربندی کلاینت داشبورد را از آرگومان‌های خود یا از متغیرهای تعیین‌شده در اسکریپت دریافت می‌کنند.

مراحل کلاینت داشبورد را می‌توان با تنظیمات نام‌گذاری‌شده همان‌طور که در بخش‌های زیر مستند شده است، پیکربندی کرد.

شروع یک ارسال جدید به داشبورد که متشکل از نتایج ثبت‌شده توسط مراحل زیر خواهد بود.

در یک اسکریپت CTest، دستور ctest_start() <#command:ctest_start> این مرحله را اجرا می‌کند. آرگومان‌های ارائه‌شده به این دستور ممکن است برخی از تنظیمات مرحله را مشخص کنند. این دستور ابتدا خط فرمان مشخص‌شده توسط متغیر CTEST_CHECKOUT_COMMAND را (در صورت تنظیم شدن) برای مقداردهی اولیه دایرکتوری سورس اجرا می‌کند.

تنظیمات پیکربندی شامل موارد زیر است:

مسیر کامل به درخت ساخت پروژه.
  • متغیر اسکریپت CTest: CTEST_BINARY_DIRECTORY <#variable:CTEST_BINARY_DIRECTORY>
  • متغیر ماژول CTest <#module:CTest>: PROJECT_BINARY_DIR <#variable:PROJECT_BINARY_DIR>
مسیر کامل به درخت سورس پروژه.
  • متغیر اسکریپت CTest: CTEST_SOURCE_DIRECTORY <#variable:CTEST_SOURCE_DIRECTORY>
  • متغیر ماژول CTest <#module:CTest>: PROJECT_SOURCE_DIR <#variable:PROJECT_SOURCE_DIR>
خط فرمانی که پیش از مرحله شروع برای مقداردهی اولیه دایرکتوری سورس اجرا می‌شود، مانند انجام یک دریافت اولیه (checkout) از سیستم کنترل نسخه.
  • متغیر اسکریپت CTest: CTEST_CHECKOUT_COMMAND <#variable:CTEST_CHECKOUT_COMMAND>
  • متغیر ماژول CTest <#module:CTest>: هیچ‌کدام (none)

در یک اسکریپت CTest، دستور ctest_update() <#command:ctest_update> این مرحله را اجرا می‌کند. آرگومان‌های ارائه‌شده به این دستور ممکن است برخی از تنظیمات مرحله را مشخص کنند.

تنظیمات پیکربندی برای تعیین ابزار کنترل نسخه شامل موارد زیر است:

ابزار خط فرمان bzr برای استفاده در صورتی که درخت سورس توسط Bazaar مدیریت می‌شود.
  • متغیر اسکریپت CTest: CTEST_BZR_COMMAND <#variable:CTEST_BZR_COMMAND>
  • متغیر ماژول CTest <#module:CTest>: هیچ‌کدام (none)
گزینه‌های خط فرمان برای BZRCommand هنگام به‌روزرسانی سورس.
  • متغیر اسکریپت CTest: CTEST_BZR_UPDATE_OPTIONS <#variable:CTEST_BZR_UPDATE_OPTIONS>
  • متغیر ماژول CTest <#module:CTest>: هیچ‌کدام (none)
ابزار خط فرمان cvs برای استفاده در صورتی که درخت سورس توسط CVS مدیریت می‌شود.
  • متغیر اسکریپت CTest: CTEST_CVS_COMMAND <#variable:CTEST_CVS_COMMAND>
  • متغیر ماژول CTest <#module:CTest>: CVSCOMMAND
گزینه‌های خط فرمان برای CVSCommand هنگام به‌روزرسانی سورس.
  • متغیر اسکریپت CTest: CTEST_CVS_UPDATE_OPTIONS <#variable:CTEST_CVS_UPDATE_OPTIONS>
  • متغیر ماژول CTest <#module:CTest>: CVS_UPDATE_OPTIONS
ابزار خط فرمان git برای استفاده در صورتی که درخت سورس توسط Git مدیریت می‌شود.
  • متغیر اسکریپت CTest: CTEST_GIT_COMMAND <#variable:CTEST_GIT_COMMAND>
  • متغیر ماژول CTest <#module:CTest>: GITCOMMAND

درخت سورس با اجرای git fetch و به دنبال آن git reset --hard روی FETCH_HEAD به‌روزرسانی می‌شود. نتیجه همانند git pull است، با این تفاوت که هرگونه تغییرات محلی بازنویسی می‌شود. از GITUpdateCustom برای تعیین یک رویکرد متفاوت استفاده کنید.

در صورت تنظیم، CTest زیرماژول‌های مخزن را پیش از به‌روزرسانی، به‌روز می‌کند.
  • متغیر اسکریپت CTest: CTEST_GIT_INIT_SUBMODULES <#variable:CTEST_GIT_INIT_SUBMODULES>
  • متغیر ماژول CTest <#module:CTest>: CTEST_GIT_INIT_SUBMODULES
یک خط فرمان سفارشی (به عنوان یک فهرست جداشده با نقطه-ویرگول) را برای اجرا در درخت سورس (درخت کاری Git) به جهت به‌روزرسانی آن، به جای اجرای GITCommand مشخص می‌کند.
  • متغیر اسکریپت CTest: CTEST_GIT_UPDATE_CUSTOM <#variable:CTEST_GIT_UPDATE_CUSTOM>
  • متغیر ماژول CTest <#module:CTest>: CTEST_GIT_UPDATE_CUSTOM
گزینه‌های خط فرمان برای GITCommand هنگام به‌روزرسانی سورس.
  • متغیر اسکریپت CTest: CTEST_GIT_UPDATE_OPTIONS <#variable:CTEST_GIT_UPDATE_OPTIONS>
  • متغیر ماژول CTest <#module:CTest>: GIT_UPDATE_OPTIONS
ابزار خط فرمان hg برای استفاده در صورتی که درخت سورس توسط Mercurial مدیریت می‌شود.
  • متغیر اسکریپت CTest: CTEST_HG_COMMAND <#variable:CTEST_HG_COMMAND>
  • متغیر ماژول CTest <#module:CTest>: هیچ‌کدام (none)
گزینه‌های خط فرمان برای HGCommand هنگام به‌روزرسانی سورس.
  • متغیر اسکریپت CTest: CTEST_HG_UPDATE_OPTIONS <#variable:CTEST_HG_UPDATE_OPTIONS>
  • متغیر ماژول CTest <#module:CTest>: هیچ‌کدام (none)
مقدار گزینه -c برای P4Command.
  • متغیر اسکریپت CTest: CTEST_P4_CLIENT <#variable:CTEST_P4_CLIENT>
  • متغیر ماژول CTest <#module:CTest>: CTEST_P4_CLIENT
ابزار خط فرمان p4 برای استفاده در صورتی که درخت سورس توسط Perforce مدیریت می‌شود.
  • متغیر اسکریپت CTest: CTEST_P4_COMMAND <#variable:CTEST_P4_COMMAND>
  • متغیر ماژول CTest <#module:CTest>: P4COMMAND
گزینه‌های خط فرمان برای P4Command برای تمام فراخوانی‌ها.
  • متغیر اسکریپت CTest: CTEST_P4_OPTIONS <#variable:CTEST_P4_OPTIONS>
  • متغیر ماژول CTest <#module:CTest>: CTEST_P4_OPTIONS
یک خط فرمان سفارشی (به عنوان یک فهرست جداشده با نقطه-ویرگول) را برای اجرا در درخت سورس (درخت Perforce) به جهت به‌روزرسانی آن، به جای اجرای P4Command مشخص می‌کند.
  • متغیر اسکریپت CTest: هیچ‌کدام (none)
  • متغیر ماژول CTest <#module:CTest>: CTEST_P4_UPDATE_CUSTOM
گزینه‌های خط فرمان برای P4Command هنگام به‌روزرسانی سورس.
  • متغیر اسکریپت CTest: CTEST_P4_UPDATE_OPTIONS <#variable:CTEST_P4_UPDATE_OPTIONS>
  • متغیر ماژول CTest <#module:CTest>: CTEST_P4_UPDATE_OPTIONS
ابزار خط فرمان svn برای استفاده در صورتی که درخت سورس توسط Subversion مدیریت می‌شود.
  • متغیر اسکریپت CTest: CTEST_SVN_COMMAND <#variable:CTEST_SVN_COMMAND>
  • متغیر ماژول CTest <#module:CTest>: SVNCOMMAND
گزینه‌های خط فرمان برای SVNCommand برای تمام فراخوانی‌ها.
  • متغیر اسکریپت CTest: CTEST_SVN_OPTIONS <#variable:CTEST_SVN_OPTIONS>
  • متغیر ماژول CTest <#module:CTest>: CTEST_SVN_OPTIONS
گزینه‌های خط فرمان برای SVNCommand هنگام به‌روزرسانی سورس.
  • متغیر اسکریپت CTest: CTEST_SVN_UPDATE_OPTIONS <#variable:CTEST_SVN_UPDATE_OPTIONS>
  • متغیر ماژول CTest <#module:CTest>: SVN_UPDATE_OPTIONS
ابزار خط فرمان کنترل نسخه را برای استفاده، بدون شناسایی خودکار VCS مدیریت‌کننده درخت سورس، مشخص می‌کند.
  • متغیر اسکریپت CTest: CTEST_UPDATE_COMMAND <#variable:CTEST_UPDATE_COMMAND>
  • متغیر ماژول CTest <#module:CTest>: هنگامی که UPDATE_TYPE برابر <vcs> باشد <VCS>COMMAND، وگرنه UPDATE_COMMAND
گزینه‌های خط فرمان برای UpdateCommand.
  • متغیر اسکریپت CTest: CTEST_UPDATE_OPTIONS <#variable:CTEST_UPDATE_OPTIONS>
  • متغیر ماژول CTest <#module:CTest>: هنگامی که UPDATE_TYPE برابر <vcs> باشد <VCS>_UPDATE_OPTIONS، وگرنه UPDATE_OPTIONS
سیستم کنترل نسخه‌ای را که درخت سورس را مدیریت می‌کند مشخص می‌کند، در صورتی که نتوان آن را به طور خودکار شناسایی کرد. مقدار می‌تواند bzr، cvs، git، hg، p4 یا svn باشد.
  • متغیر اسکریپت CTest: ندارد، از درخت سورس شناسایی می‌شود
  • متغیر ماژول CTest <#module:CTest>: UPDATE_TYPE در صورت تنظیم شدن، وگرنه CTEST_UPDATE_TYPE
مشخص می‌کند که می‌خواهید دستور به‌روزرسانی کنترل نسخه فقط نسخه فعلی دریافت‌شده (checkout شده) را شناسایی کند، و به نسخه متفاوتی به‌روزرسانی نکند.
  • متغیر اسکریپت CTest: CTEST_UPDATE_VERSION_ONLY <#variable:CTEST_UPDATE_VERSION_ONLY>
  • گزینه ctest_update() <#command:ctest_update>: VERSION_ONLY
نسخه فعلی درخت سورس شما را مشخص می‌کند.

هنگامی که این متغیر روی یک رشته غیرخالی تنظیم شود، CTest مقداری را که شما مشخص کرده‌اید گزارش می‌دهد، به جای این که از دستور به‌روزرسانی برای شناسایی نسخه فعلی دریافت‌شده استفاده کند. استفاده از این متغیر جایگزین UpdateVersionOnly می‌شود. مانند UpdateVersionOnly، استفاده از این متغیر به CTest اعلام می‌کند که درخت سورس را به نسخه متفاوتی به‌روز نکند.

  • متغیر اسکریپت CTest: CTEST_UPDATE_VERSION_OVERRIDE <#variable:CTEST_UPDATE_VERSION_OVERRIDE>
  • گزینه ctest_update() <#command:ctest_update>: VERSION_OVERRIDE <version>

تنظیمات پیکربندی اضافی شامل موارد زیر است:

در حالت داشبورد Nightly، "زمان شروع شبانه" را مشخص می‌کند. در سیستم‌های کنترل نسخه متمرکز (cvs و svn)، مرحله Update نسخه نرم‌افزار را تا این زمان دریافت می‌کند تا چندین کلاینت نسخه مشترکی را برای آزمون انتخاب نمایند. این مفهوم در سیستم‌های کنترل نسخه توزیع‌شده به خوبی تعریف نشده است، بنابراین این تنظیم نادیده گرفته می‌شود.
  • متغیر اسکریپت CTest: CTEST_NIGHTLY_START_TIME <#variable:CTEST_NIGHTLY_START_TIME>
  • متغیر ماژول CTest <#module:CTest>: NIGHTLY_START_TIME در صورت تنظیم شدن، وگرنه CTEST_NIGHTLY_START_TIME

در یک اسکریپت CTest، دستور ctest_configure() <#command:ctest_configure> این مرحله را اجرا می‌کند. آرگومان‌های ارائه‌شده به این دستور می‌توانند برخی از تنظیمات مرحله را مشخص کنند.

تنظیمات پیکربندی شامل موارد زیر است:

خط فرمانی برای راه‌اندازی فرآیند پیکربندی نرم‌افزار. این فرمان در مکان مشخص‌شده توسط تنظیم BuildDirectory اجرا خواهد شد.
  • متغیر اسکریپت CTest: CTEST_CONFIGURE_COMMAND <#variable:CTEST_CONFIGURE_COMMAND>
  • متغیر ماژول CTest <#module:CTest>: CMAKE_COMMAND <#variable:CMAKE_COMMAND> که پس از آن PROJECT_SOURCE_DIR <#variable:PROJECT_SOURCE_DIR> قرار می‌گیرد
فهرستی از برچسب‌ها که با نقطه-ویرگول از هم جدا شده‌اند و به عنوان زیرپروژه در نظر گرفته می‌شوند را مشخص می‌کند. این نگاشت هنگام ارسال نتایج پیکربندی، آزمون یا ساخت به CDash تحویل داده خواهد شد.
  • متغیر اسکریپت CTest: CTEST_LABELS_FOR_SUBPROJECTS <#variable:CTEST_LABELS_FOR_SUBPROJECTS>
  • متغیر ماژول CTest <#module:CTest>: CTEST_LABELS_FOR_SUBPROJECTS

بخش خلاصه برچسب و زیرپروژه (Label and Subproject Summary) را ببینید.

تولیدکننده CMake برای استفاده در مرحله پیکربندی هنگامی که ConfigureCommand تنظیم نشده است.
  • متغیر اسکریپت CTest: CTEST_CMAKE_GENERATOR
  • متغیر ماژول CTest <#module:CTest>: هیچ‌کدام (none)
سکوی تولیدکننده CMake برای استفاده در مرحله پیکربندی هنگامی که ConfigureCommand تنظیم نشده است.
  • متغیر اسکریپت CTest: CTEST_CMAKE_GENERATOR_PLATFORM
  • متغیر ماژول CTest <#module:CTest>: هیچ‌کدام (none)
مجموعه‌ابزار تولیدکننده CMake برای استفاده در مرحله پیکربندی هنگامی که ConfigureCommand تنظیم نشده است.
  • متغیر اسکریپت CTest: CTEST_CMAKE_GENERATOR_TOOLSET
  • متغیر ماژول CTest <#module:CTest>: هیچ‌کدام (none)

در یک اسکریپت CTest، دستور ctest_build() <#command:ctest_build> این مرحله را اجرا می‌کند. آرگومان‌های ارائه‌شده به این دستور می‌توانند برخی از تنظیمات مرحله را مشخص کنند.

تنظیمات پیکربندی شامل موارد زیر است:

هنگامی که سیستم ساختِ فراخوانی‌شده امکان انتخاب پیکربندی در زمان ساخت (مانند Debug یا Release) را می‌دهد، این گزینه پیکربندی پیش‌فرضی را مشخص می‌کند که در صورت عدم ارائه گزینه -C به دستور ctest ساخته خواهد شد. این مقدار در مقدار MakeCommand جایگزین رشته دقیق ${CTEST_CONFIGURATION_TYPE} (در صورت وجود) می‌شود.
  • متغیر اسکریپت CTest: CTEST_CONFIGURATION_TYPE <#variable:CTEST_CONFIGURATION_TYPE>
  • متغیر ماژول CTest <#module:CTest>: DEFAULT_CTEST_CONFIGURATION_TYPE، که با متغیر محیطی CMAKE_CONFIG_TYPE <#envvar:CMAKE_CONFIG_TYPE> مقداردهی اولیه می‌شود
فهرستی از برچسب‌ها که با نقطه-ویرگول از هم جدا شده‌اند و به عنوان زیرپروژه در نظر گرفته می‌شوند را مشخص می‌کند. این نگاشت هنگام ارسال نتایج پیکربندی، آزمون یا ساخت به CDash تحویل داده خواهد شد.
  • متغیر اسکریپت CTest: CTEST_LABELS_FOR_SUBPROJECTS <#variable:CTEST_LABELS_FOR_SUBPROJECTS>
  • متغیر ماژول CTest <#module:CTest>: CTEST_LABELS_FOR_SUBPROJECTS

بخش خلاصه برچسب و زیرپروژه (Label and Subproject Summary) را ببینید.

خط فرمانی برای راه‌اندازی فرآیند ساخت نرم‌افزار. این فرمان در مکان مشخص‌شده توسط تنظیم BuildDirectory اجرا خواهد شد.
  • متغیر اسکریپت CTest: CTEST_BUILD_COMMAND <#variable:CTEST_BUILD_COMMAND>
  • متغیر ماژول CTest <#module:CTest>: MAKECOMMAND، که با دستور build_command() <#command:build_command> مقداردهی اولیه می‌شود
برای درخت‌های ساخت ایجادشده توسط CMake با استفاده از یکی از تولیدکننده‌های Makefile <#makefile-generators> یا تولیدکننده Ninja <#generator:Ninja>، مشخص می‌کند که آیا ویژگی CTEST_USE_LAUNCHERS توسط ماژول CTestUseLaunchers <#module:CTestUseLaunchers> (که در ماژول CTest <#module:CTest> نیز گنجانده شده است) فعال است یا خیر. در صورت فعال بودن، سیستم ساخت تولیدشده هر بار فراخوانی کامپایلر، پیونددهنده یا خط فرمان سفارشی را درون یک «راه‌انداز» (launcher) قرار می‌دهد که از طریق متغیرهای محیطی و فایل‌ها با CTest ارتباط برقرار می‌کند تا هشدارهای ساخت و اطلاعات خطای جزئی و تفکیک‌شده را گزارش دهد. در غیر این صورت، CTest باید لاگ خروجی ساخت را برای تحلیل و تشخیص خطاها واکشی («scrape») کند.
  • متغیر اسکریپت CTest: CTEST_USE_LAUNCHERS <#variable:CTEST_USE_LAUNCHERS>
  • متغیر ماژول CTest <#module:CTest>: CTEST_USE_LAUNCHERS
فلگ‌های اضافی برای ارسال به ابزار ساخت هنگام ساخت پروژه. فقط زمانی استفاده می‌شود که MakeCommand به‌طور صریح تنظیم نشده باشد.
  • متغیر اسکریپت CTest: CTEST_BUILD_FLAGS
  • متغیر ماژول CTest <#module:CTest>: هیچ‌کدام (none)
یک هدف خاص را برای ساخت به جای هدف پیش‌فرض مشخص می‌کند. فقط زمانی استفاده می‌شود که MakeCommand به‌طور صریح تنظیم نشده باشد.
  • متغیر اسکریپت CTest: CTEST_BUILD_TARGET
  • متغیر ماژول CTest <#module:CTest>: هیچ‌کدام (none)

در یک اسکریپت CTest، دستور ctest_test() <#command:ctest_test> این مرحله را اجرا می‌کند. آرگومان‌های ارائه‌شده به این دستور می‌توانند برخی از تنظیمات مرحله را مشخص کنند.

تنظیمات پیکربندی شامل موارد زیر است:

یک فایل مشخصات منابع (resource specification file) را تعیین می‌کند.
  • متغیر اسکریپت CTest: CTEST_RESOURCE_SPEC_FILE <#variable:CTEST_RESOURCE_SPEC_FILE>
  • متغیر ماژول CTest <#module:CTest>: CTEST_RESOURCE_SPEC_FILE

برای اطلاعات بیشتر، بخش تخصیص منابع (Resource Allocation) را ببینید.

فهرستی از برچسب‌ها که با نقطه-ویرگول از هم جدا شده‌اند و به عنوان زیرپروژه در نظر گرفته می‌شوند را مشخص می‌کند. این نگاشت هنگام ارسال نتایج پیکربندی، آزمون یا ساخت به CDash تحویل داده خواهد شد.
  • متغیر اسکریپت CTest: CTEST_LABELS_FOR_SUBPROJECTS <#variable:CTEST_LABELS_FOR_SUBPROJECTS>
  • متغیر ماژول CTest <#module:CTest>: CTEST_LABELS_FOR_SUBPROJECTS

بخش خلاصه برچسب و زیرپروژه (Label and Subproject Summary) را ببینید.

هنگام اجرای موازی آزمون‌ها (برای مثال با -j)، تلاش می‌کند در صورتی که بار پردازنده (CPU load) ممکن است از یک آستانه مشخص فراتر رود، آزمون‌های جدیدی را شروع نکند.
  • متغیر اسکریپت CTest: CTEST_TEST_LOAD <#variable:CTEST_TEST_LOAD>
  • متغیر ماژول CTest <#module:CTest>: CTEST_TEST_LOAD
مدت زمان انقضای پیش‌فرض (timeout) برای هر آزمون در صورتی که توسط ویژگی آزمون TIMEOUT <#prop_test:TIMEOUT> یا فلگ --timeout مشخص نشده باشد.
  • متغیر اسکریپت CTest: CTEST_TEST_TIMEOUT <#variable:CTEST_TEST_TIMEOUT>
  • متغیر ماژول CTest <#module:CTest>: DART_TESTING_TIMEOUT
در نسخه 4.4 اضافه شد.

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

این مقدار نشان‌دهنده استفاده از پوشش کد مبتنی بر سورس‌کد Clang است که «مستقیماً روی اطلاعات پیش‌پردازنده و AST عمل می‌کند». برای اطلاعات بیشتر، به مستندات پوشش کد مبتنی بر سورس‌کد Clang (Clang Source-based Code Coverage) https://clang.llvm.org/docs/SourceBasedCodeCoverage.html مراجعه کنید.

دستور CTest هر آزمون را با متغیر محیطی LLVM_PROFILE_FILE تنظیم‌شده روی <directory>/<test-name>_<process-id>.profraw اجرا خواهد کرد، که در آن <directory> مسیر مطلق به پوشه‌ای است که CTestTestfile.cmake توصیف‌کننده آزمون در آن قرار دارد. این کار پوشش کد مبتنی بر سورس Clang را به گونه‌ای پیکربندی می‌کند که اطلاعات پوشش جمع‌آوری‌شده توسط هر آزمون را به‌طور منحصربه‌فرد و بدون هرگونه تداخل شناسایی کند.

هرگونه فایل موجود <directory>/<test-name>_*.profraw برای یک آزمون، پیش از اجرای آن آزمون حذف می‌شود. هر متغیر محیطی موجود LLVM_PROFILE_FILE نادیده گرفته می‌شود.

اگر مقداری مشخص نشود، هیچ کاری انجام نشده و چیزی به متغیرهای محیطی اضافه نمی‌شود.

  • متغیر اسکریپت CTest: CTEST_TEST_COVERAGE_TOOL <#variable:CTEST_TEST_COVERAGE_TOOL>
  • متغیر ماژول CTest <#module:CTest>: CTEST_TEST_COVERAGE_TOOL <#variable:CTEST_TEST_COVERAGE_TOOL>

برای گزارش مقادیر اضافی آزمون به CDash، بخش اندازه‌گیری‌های اضافی آزمون (Additional Test Measurements) <#additional-test-measurements> را ببینید.

در یک اسکریپت CTest، دستور ctest_coverage() <#command:ctest_coverage> این مرحله را اجرا می‌کند. آرگومان‌های ارائه‌شده به این دستور می‌توانند برخی از تنظیمات مرحله را مشخص کنند.

تنظیمات پیکربندی شامل موارد زیر است:

ابزار خط فرمانی برای انجام تحلیل پوشش کد نرم‌افزار. این فرمان در مکان مشخص‌شده توسط تنظیم BuildDirectory اجرا خواهد شد.
  • متغیر اسکریپت CTest: CTEST_COVERAGE_COMMAND <#variable:CTEST_COVERAGE_COMMAND>
  • متغیر ماژول CTest <#module:CTest>: COVERAGE_COMMAND
گزینه‌های خط فرمان ارسالی به ابزار CoverageCommand را مشخص می‌کند.
  • متغیر اسکریپت CTest: CTEST_COVERAGE_EXTRA_FLAGS <#variable:CTEST_COVERAGE_EXTRA_FLAGS>
  • متغیر ماژول CTest <#module:CTest>: COVERAGE_EXTRA_FLAGS

این گزینه‌ها نخستین آرگومان‌های ارسال‌شده به CoverageCommand هستند.

فهرستی از الگوهای گلوب (glob patterns) جداشده با نقطه-ویرگول برای فایل‌های منبع اضافی جهت گنجاندن در تحلیل پوشش کد.
  • متغیر اسکریپت CTest: CTEST_EXTRA_COVERAGE_GLOB <#variable:CTEST_EXTRA_COVERAGE_GLOB>
  • متغیر ماژول CTest <#module:CTest>: هیچ‌کدام (none)

در یک اسکریپت CTest، دستور ctest_memcheck() <#command:ctest_memcheck> این مرحله را اجرا می‌کند. آرگومان‌های ارائه‌شده به این دستور می‌توانند برخی از تنظیمات این مرحله را تعیین کنند.

تنظیمات پیکربندی شامل موارد زیر است:

ابزار خط فرمانی برای انجام تحلیل پویا (dynamic analysis). خطوط فرمان آزمون از طریق این ابزار اجرا خواهند شد.
  • متغیر اسکریپت CTest: CTEST_MEMORYCHECK_COMMAND <#variable:CTEST_MEMORYCHECK_COMMAND>
  • متغیر ماژول CTest <#module:CTest>: MEMORYCHECK_COMMAND
گزینه‌های خط فرمان را برای ابزار MemoryCheckCommand مشخص می‌کند. این گزینه‌ها پیش از خط فرمان آزمون قرار خواهند گرفت.
  • متغیر اسکریپت CTest: CTEST_MEMORYCHECK_COMMAND_OPTIONS <#variable:CTEST_MEMORYCHECK_COMMAND_OPTIONS>
  • متغیر ماژول CTest <#module:CTest>: MEMORYCHECK_COMMAND_OPTIONS
نوع بررسی حافظه را برای اجرا مشخص می‌کند.
  • متغیر اسکریپت CTest: CTEST_MEMORYCHECK_TYPE <#variable:CTEST_MEMORYCHECK_TYPE>
  • متغیر ماژول CTest <#module:CTest>: MEMORYCHECK_TYPE
گزینه‌های ابزارهای پالایش حافظه (sanitizers) را هنگام اجرا با ساختی که پالایش در آن فعال است (sanitize-enabled build) مشخص می‌کند.
  • متغیر اسکریپت CTest: CTEST_MEMORYCHECK_SANITIZER_OPTIONS <#variable:CTEST_MEMORYCHECK_SANITIZER_OPTIONS>
  • متغیر ماژول CTest <#module:CTest>: MEMORYCHECK_SANITIZER_OPTIONS
فایلی شامل قوانین نادیده‌گیری (suppression rules) را برای ابزار MemoryCheckCommand مشخص می‌کند. این فایل با گزینه‌های متناسب با آن ابزار ارسال خواهد شد.
  • متغیر اسکریپت CTest: CTEST_MEMORYCHECK_SUPPRESSIONS_FILE <#variable:CTEST_MEMORYCHECK_SUPPRESSIONS_FILE>
  • متغیر ماژول CTest <#module:CTest>: MEMORYCHECK_SUPPRESSIONS_FILE

تنظیمات پیکربندی اضافی شامل موارد زیر است:

یک MemoryCheckCommand را تعیین می‌کند که از نظر خط فرمان با Bounds Checker سازگار است.
  • متغیر اسکریپت CTest: ندارد
  • متغیر ماژول CTest <#module:CTest>: ندارد
یک MemoryCheckCommand را تعیین می‌کند که از نظر خط فرمان با Purify سازگار است.
  • متغیر اسکریپت CTest: ندارد
  • متغیر ماژول CTest <#module:CTest>: PURIFYCOMMAND
یک MemoryCheckCommand را تعیین می‌کند که از نظر خط فرمان با Valgrind سازگار است.
  • متغیر اسکریپت CTest: ندارد
  • متغیر ماژول CTest <#module:CTest>: VALGRIND_COMMAND
گزینه‌های خط فرمان را برای ابزار ValgrindCommand مشخص می‌کند. این گزینه‌ها پیش از خط فرمان آزمون قرار خواهند گرفت.
  • متغیر اسکریپت CTest: ندارد
  • متغیر ماژول CTest <#module:CTest>: VALGRIND_COMMAND_OPTIONS
یک MemoryCheckCommand را تعیین می‌کند که از نظر خط فرمان با DrMemory سازگار است.
  • متغیر اسکریپت CTest: ندارد
  • متغیر ماژول CTest <#module:CTest>: DRMEMORY_COMMAND
گزینه‌های خط فرمان را برای ابزار DrMemoryCommand مشخص می‌کند. این گزینه‌ها پیش از خط فرمان آزمون قرار خواهند گرفت.
  • متغیر اسکریپت CTest: ندارد
  • متغیر ماژول CTest <#module:CTest>: DRMEMORY_COMMAND_OPTIONS
یک MemoryCheckCommand را تعیین می‌کند که از نظر خط فرمان با cuda-memcheck یا compute-sanitizer سازگار است.
  • متغیر اسکریپت CTest: ندارد
  • متغیر ماژول CTest <#module:CTest>: CUDA_SANITIZER_COMMAND
گزینه‌های خط فرمان را برای ابزار CudaSanitizerCommand مشخص می‌کند. این گزینه‌ها پیش از خط فرمان آزمون قرار خواهند گرفت.
  • متغیر اسکریپت CTest: ندارد
  • متغیر ماژول CTest <#module:CTest>: CUDA_SANITIZER_COMMAND_OPTIONS

در یک اسکریپت CTest، دستور ctest_submit() <#command:ctest_submit> این مرحله را اجرا می‌کند. آرگومان‌های ارائه‌شده به این دستور می‌توانند برخی از تنظیمات این مرحله را تعیین کنند.

تنظیمات پیکربندی شامل موارد زیر است:

پلتفرم کلاینت داشبورد را با یک رشته کوتاه توصیف می‌کند. (سیستم‌عامل، کامپایلر و غیره)
  • متغیر اسکریپت CTest: CTEST_BUILD_NAME <#variable:CTEST_BUILD_NAME>
  • متغیر ماژول CTest <#module:CTest>: BUILDNAME
گزینه قدیمی (منسوخ). استفاده نمی‌شود.
  • متغیر اسکریپت CTest: ندارد، از سرور شناسایی می‌شود
  • متغیر ماژول CTest <#module:CTest>: CTEST_CDASH_VERSION
تعداد تلاش‌های مجدد برای ارسال در صورت بروز خطای شبکه را مشخص می‌کند.
  • متغیر اسکریپت CTest: ندارد، از گزینه RETRY_COUNT در دستور ctest_submit() <#command:ctest_submit> استفاده کنید.
  • متغیر ماژول CTest <#module:CTest>: CTEST_SUBMIT_RETRY_COUNT
میزان تاخیر پیش از تلاش مجدد برای ارسال در صورت بروز خطای شبکه را مشخص می‌کند.
  • متغیر اسکریپت CTest: ندارد، از گزینه RETRY_DELAY در دستور ctest_submit() <#command:ctest_submit> استفاده کنید.
  • متغیر ماژول CTest <#module:CTest>: CTEST_SUBMIT_RETRY_DELAY
منسوخ‌شده از نسخه 3.30: به جای آن از TLSVerify استفاده کنید.

فهرستی از گزینه‌های جداشده با نقطه‌ویرگول را جهت کنترل کتابخانه Curl که CTest در داخل برای اتصال به سرور از آن استفاده می‌کند، مشخص می‌نماید.

  • متغیر اسکریپت CTest: CTEST_CURL_OPTIONS <#variable:CTEST_CURL_OPTIONS>
  • متغیر ماژول CTest <#module:CTest>: CTEST_CURL_OPTIONS

گزینه‌های ممکن عبارتند از:

غیرفعال کردن گزینه CURLOPT_SSL_VERIFYPEER در curl.
غیرفعال کردن گزینه CURLOPT_SSL_VERIFYHOST در curl.
گزینه قدیمی (منسوخ). هنگامی که SubmitURL تنظیم نشده باشد، از DropMethod، DropSiteUser، DropSitePassword، DropSite و DropLocation ساخته می‌شود.
  • متغیر اسکریپت CTest: CTEST_DROP_LOCATION <#variable:CTEST_DROP_LOCATION>
  • متغیر ماژول CTest <#module:CTest>: DROP_LOCATION در صورت تنظیم، در غیر این صورت CTEST_DROP_LOCATION
گزینه قدیمی (منسوخ). هنگامی که SubmitURL تنظیم نشده باشد، از DropMethod، DropSiteUser، DropSitePassword، DropSite و DropLocation ساخته می‌شود.
  • متغیر اسکریپت CTest: CTEST_DROP_METHOD <#variable:CTEST_DROP_METHOD>
  • متغیر ماژول CTest <#module:CTest>: DROP_METHOD در صورت تنظیم، در غیر این صورت CTEST_DROP_METHOD
گزینه قدیمی (منسوخ). هنگامی که SubmitURL تنظیم نشده باشد، از DropMethod، DropSiteUser، DropSitePassword، DropSite و DropLocation ساخته می‌شود.
  • متغیر اسکریپت CTest: CTEST_DROP_SITE <#variable:CTEST_DROP_SITE>
  • متغیر ماژول CTest <#module:CTest>: DROP_SITE در صورت تنظیم، در غیر این صورت CTEST_DROP_SITE
گزینه قدیمی (منسوخ). هنگامی که SubmitURL تنظیم نشده باشد، از DropMethod، DropSiteUser، DropSitePassword، DropSite و DropLocation ساخته می‌شود.
  • متغیر اسکریپت CTest: CTEST_DROP_SITE_PASSWORD <#variable:CTEST_DROP_SITE_PASSWORD>
  • متغیر ماژول CTest <#module:CTest>: DROP_SITE_PASSWORD در صورت تنظیم، در غیر این صورت CTEST_DROP_SITE_PASSWORD
گزینه قدیمی (منسوخ). هنگامی که SubmitURL تنظیم نشده باشد، از DropMethod، DropSiteUser، DropSitePassword، DropSite و DropLocation ساخته می‌شود.
  • متغیر اسکریپت CTest: CTEST_DROP_SITE_USER <#variable:CTEST_DROP_SITE_USER>
  • متغیر ماژول CTest <#module:CTest>: DROP_SITE_USER در صورت تنظیم، در غیر این صورت CTEST_DROP_SITE_USER
گزینه قدیمی (منسوخ). استفاده نمی‌شود.
  • متغیر اسکریپت CTest: CTEST_DROP_SITE_CDASH <#variable:CTEST_DROP_SITE_CDASH>
  • متغیر ماژول CTest <#module:CTest>: CTEST_DROP_SITE_CDASH
گزینه قدیمی (منسوخ). استفاده نمی‌شود.
  • متغیر اسکریپت CTest: CTEST_SCP_COMMAND <#variable:CTEST_SCP_COMMAND>
  • متغیر ماژول CTest <#module:CTest>: SCPCOMMAND
سایت میزبان کلاینت داشبورد را با یک رشته کوتاه توصیف می‌کند. (نام میزبان، دامنه و غیره)
  • متغیر اسکریپت CTest: CTEST_SITE <#variable:CTEST_SITE>
  • متغیر ماژول CTest <#module:CTest>: SITE، مقداردهی‌شده توسط دستور site_name() <#command:site_name>
نشانی اینترنتی http یا https مربوط به سرور داشبورد برای ارسال گزارش به آن.
  • متغیر اسکریپت CTest: CTEST_SUBMIT_URL <#variable:CTEST_SUBMIT_URL>
  • متغیر ماژول CTest <#module:CTest>: SUBMIT_URL در صورت تنظیم، در غیر این صورت CTEST_SUBMIT_URL
مدت زمانی که باید منتظر تکمیل ارسال ماند و در صورت پایان نیافتن، عملیات لغو می‌شود. برای غیرفعال کردن مهلت زمانی (timeout)، مقدار صفر را مشخص کنید.
  • متغیر اسکریپت CTest: CTEST_SUBMIT_INACTIVITY_TIMEOUT <#variable:CTEST_SUBMIT_INACTIVITY_TIMEOUT>
  • متغیر ماژول CTest <#module:CTest>: CTEST_SUBMIT_INACTIVITY_TIMEOUT
فهرستی از فایل‌های یادداشت جداشده با نقطه‌ویرگول که همراه با ارسال آپلود می‌شوند.
  • متغیر اسکریپت CTest: CTEST_NOTES_FILES <#variable:CTEST_NOTES_FILES>
  • متغیر ماژول CTest <#module:CTest>: ندارد
فهرستی از فایل‌های .xml اضافی جداشده با نقطه‌ویرگول که همراه با ارسال آپلود می‌شوند.
  • متغیر اسکریپت CTest: CTEST_EXTRA_SUBMIT_FILES <#variable:CTEST_EXTRA_SUBMIT_FILES>
  • متغیر ماژول CTest <#module:CTest>: ندارد
فهرستی از نام بخش‌ها جداشده با نقطه‌ویرگول جهت ارسال. در صورت تنظیم، تنها بخش‌های نام‌برده ارسال می‌شوند و نه تمام بخش‌های موجود. نام‌های معتبر همان گزینه‌های موجود در گزینه PARTS دستور ctest_submit() <#command:ctest_submit> هستند.
  • متغیر اسکریپت CTest: CTEST_SUBMIT_PARTS <#variable:CTEST_SUBMIT_PARTS>
  • متغیر ماژول CTest <#module:CTest>: ندارد
حداکثر زمان کل (به ثانیه) مجاز برای کل اجرای داشبورد. زمانی که زمان باقی‌مانده به کمتر از دو دقیقه کاهش یابد، CTest مراحل اضافی را آغاز نخواهد کرد.
  • متغیر اسکریپت CTest: CTEST_TIME_LIMIT
  • متغیر ماژول CTest <#module:CTest>: ندارد
اضافه‌شده در نسخه 3.30.

تعیین حداقل نسخه مجاز TLS هنگام ارسال به داشبورد از طریق نشانی‌های اینترنتی https://.

  • متغیر اسکریپت CTest: CTEST_TLS_VERSION <#variable:CTEST_TLS_VERSION>
  • متغیر ماژول CTest <#module:CTest>: CTEST_TLS_VERSION

تغییریافته در نسخه 3.31: مقدار پیش‌فرض TLS 1.2 است. پیش از این، هیچ حداقل نسخه‌ای به‌طور پیش‌فرض اعمال نمی‌شد.

اضافه‌شده در نسخه 3.30.

یک مقدار بولی (boolean) را مشخص می‌کند که تعیین‌کننده اعتبارسنجی گواهی سرور هنگام ارسال به داشبورد از طریق نشانی‌های اینترنتی https:// است.

  • متغیر اسکریپت CTest: CTEST_TLS_VERIFY <#variable:CTEST_TLS_VERIFY>
  • متغیر ماژول CTest <#module:CTest>: CTEST_TLS_VERIFY

تغییریافته در نسخه 3.31: مقدار پیش‌فرض on (روشن) است. پیش از این، مقدار پیش‌فرض off (خاموش) بود. کاربران می‌توانند متغیر محیطی CMAKE_TLS_VERIFY <#envvar:CMAKE_TLS_VERIFY> را روی 0 تنظیم کنند تا مقدار پیش‌فرض قبلی بازیابی شود.

گزینه قدیمی (منسوخ). استفاده نمی‌شود.
  • متغیر اسکریپت CTest: CTEST_TRIGGER_SITE <#variable:CTEST_TRIGGER_SITE>
  • متغیر ماژول CTest <#module:CTest>: TRIGGER_SITE در صورت تنظیم، در غیر این صورت CTEST_TRIGGER_SITE

در نسخه 3.14 اضافه شد.

هنگامی که گزینه خط فرمان --show-only=json-v1 داده شود، اطلاعات آزمون در قالب JSON خروجی داده می‌شود. نسخه 1.0 از مدل شیء JSON به صورت زیر تعریف می‌شود:

رشته "ctestInfo".
یک شیء JSON که مولفه‌های نسخه را مشخص می‌کند. اعضای آن عبارتند از:
یک عدد صحیح مثبت که مولفه نسخه اصلی (major) مدل شیء JSON را مشخص می‌کند.
یک عدد صحیح غیرمنفی که مولفه نسخه فرعی (minor) مدل شیء JSON را مشخص می‌کند.
شیء JSON نمایانگر اطلاعات ردگیری فراخوانی (backtrace) با اعضای زیر:
فهرستی از نام دستورات.
فهرستی از نام فایل‌ها.
فهرستی از اشیاء JSON مربوط به گره‌ها با اعضای زیر:
یک عضو اختیاری که هنگام نمایش فراخوانی یک دستور درون فایل توسط گره، وجود دارد. مقدار آن یک شاخص (index) عدد صحیح بدون علامت بر پایه 0 در عضو commands مربوط به backtraceGraph است.
یک شاخص عدد صحیح بدون علامت بر پایه 0 در عضو files مربوط به backtraceGraph.
یک عضو اختیاری که هنگام نمایش یک خط درون فایل توسط گره، وجود دارد. مقدار آن یک شماره خط عدد صحیح بدون علامت بر پایه 1 در فایلی است که ردگیری فراخوانی در آن اضافه شده است.
یک عضو اختیاری که وقتی گره در پایین‌ترین بخش پشته فراخوانی نباشد، وجود دارد. مقدار آن یک شاخص عدد صحیح بدون علامت بر پایه 0 در عضو nodes مربوط به backtraceGraph است که والد را در گراف نشان می‌دهد.
یک آرایه JSON شامل فهرستی از اطلاعات مربوط به هر آزمون. هر ورودی یک شیء JSON با اعضای زیر است:
نام آزمون. این مقدار نمی‌تواند خالی باشد.
فیلد اختیاری مشخص‌کننده پیکربندی که آزمون تحت آن اجرا خواهد شد. این مقدار همیشه با گزینه -C مشخص‌شده در خط فرمان ctest تطابق خواهد داشت. اگر چنین گزینه‌ای داده نشده باشد، این فیلد وجود نخواهد داشت.
آرایه اختیاری که در آن عنصر نخست دستور آزمون و عناصر باقی‌مانده آرگومان‌های دستور هستند. معمولاً این فیلد باید وجود داشته و غیرخالی باشد، اما در موارد خاص مربوط به عبارات تولیدکننده (generator expressions)، این امکان وجود دارد که یک آزمون دستوری نداشته باشد و در نتیجه این فیلد وجود نداشته باشد.
شاخص در عضو nodes مربوط به backtraceGraph.
آرایه اختیاری از ویژگی‌های آزمون. هر آیتم آرایه یک شیء JSON با اعضای زیر خواهد بود:
نام ویژگی آزمون. این مقدار نمی‌تواند خالی باشد.
مقدار ویژگی، که می‌تواند یک رشته، یک عدد، یک مقدار بولی (boolean) یا آرایه‌ای از رشته‌ها باشد.

در نسخه 4.1 اضافه شد: قالب خروجی JSON در قالبی خوانا برای ماشین توسط این طرح‌واره JSON (JSON schema) توصیف شده است.

ابزار CTest مکانیزمی را برای آزمون‌ها فراهم می‌کند تا منابع مورد نیاز خود را به روشی دقیق و ریزدانه (fine-grained) مشخص کنند، و همچنین به کاربران اجازه می‌دهد منابع موجود در ماشین در حال اجرا را تعیین نمایند. این قابلیت به CTest امکان می‌دهد تا به طور داخلی ردیابی کند کدام منابع در حال استفاده و کدام آزاد هستند، و آزمون‌ها را به‌گونه‌ای زمان‌بندی کند که مانع از تلاش آن‌ها برای درخواست منابعی شود که در دسترس نیستند.

هنگامی که قابلیت تخصیص منابع استفاده می‌شود، CTest منابع را بیش از ظرفیت تخصیص نخواهد داد (oversubscribe نمی‌کند). برای مثال، اگر یک منبع دارای 8 اسلات (slot) باشد، CTest آزمون‌هایی را که در مجموع به طور همزمان بیش از 8 اسلات مصرف می‌کنند اجرا نخواهد کرد. این امر موجب محدود شدن تعداد آزمون‌های در حال اجرا در هر لحظه می‌شود، حتی اگر آرگومان بالای -j استفاده شده باشد، به شرطی که تمام آن آزمون‌ها از اسلات‌های همان منبع استفاده کنند. علاوه بر این، بدین معناست که یک آزمون منفرد که بیش از میزان موجود در ماشین از یک منبع استفاده می‌کند اصلاً اجرا نخواهد شد (و وضعیت آن به صورت Not Run گزارش می‌شود).

یک کاربرد رایج این قابلیت برای آزمون‌هایی است که نیاز به استفاده از یک GPU دارند. چندین آزمون می‌توانند به طور همزمان حافظه‌ای از یک GPU را تخصیص دهند، اما اگر آزمون‌های بیش از حدی همزمان برای این کار تلاش کنند، تخصیص حافظه در برخی از آن‌ها با شکست مواجه می‌شود که نتیجه آن یک آزمون مردود است؛ حتی در حالی که اگر آزمون حافظه مورد نیازش را داشت، با موفقیت سپری می‌شد. با استفاده از قابلیت تخصیص منابع، هر آزمون می‌تواند مشخص کند چه میزان حافظه از GPU نیاز دارد، و به CTest امکان می‌دهد آزمون‌ها را طوری زمان‌بندی کند که اجرای همزمان چند مورد از این آزمون‌ها استخر حافظه (memory pool) پردازنده گرافیکی را تمام نکند.

لطفاً توجه داشته باشید که CTest هیچ مفهومی از اینکه GPU چیست یا چه مقدار حافظه دارد ندارد. این ابزار هیچ روشی برای برقراری ارتباط با یک GPU جهت دریافت این اطلاعات یا انجام مدیریت حافظه ندارد، هرچند پروژه می‌تواند آزمونی تعریف کند که جزئیات مربوط به ماشین آزمون را ارائه دهد (به بخش «فایل مشخصات منابع تولیدشده پویا (Dynamically-Generated Resource Specification File)» مراجعه کنید).

ابزار CTest فهرستی از انواع منابع انتزاعی (abstract resource types) را ردیابی می‌کند که هر کدام تعداد معینی اسلات (slot) در دسترس برای استفاده آزمون‌ها دارند. هر آزمون تعداد اسلات‌های مورد نیاز خود از یک منبع خاص را مشخص می‌کند، و سپس CTest آن‌ها را طوری زمان‌بندی می‌کند که از فراتر رفتن تعداد کل اسلات‌های در حال استفاده از ظرفیت فهرست‌شده جلوگیری شود. هنگامی که یک آزمون اجرا می‌شود، و اسلات‌هایی از یک منبع به آن آزمون اختصاص می‌یابد، آزمون‌ها می‌توانند فرض کنند که در طول مدت فرایند آزمون، استفاده انحصاری از آن اسلات‌ها را در اختیار دارند.

قابلیت تخصیص منابع CTest حداقل از دو ورودی تشکیل شده است:

  • فایل مشخصات منابع (resource specification file) که در زیر شرح داده شده و منابع موجود در سیستم را توصیف می‌کند.
  • ویژگی RESOURCE_GROUPS <#prop_test:RESOURCE_GROUPS> آزمون‌ها، که منابع مورد نیاز آزمون را توصیف می‌کند.

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

ویژگی RESOURCE_GROUPS <#prop_test:RESOURCE_GROUPS> به CTest می‌گوید آزمون انتظار دارد از چه منابعی استفاده کند که به شیوه‌ای معنادار برای آزمون گروه‌بندی شده‌اند. خود آزمون باید متغیرهای محیطی را بخواند تا تعیین کند چه منابعی به هر گروه اختصاص یافته است. برای مثال، هر گروه ممکن است متناظر با فرایندی باشد که آزمون هنگام اجرا ایجاد (spawn) می‌کند.

توجه داشته باشید که حتی اگر یک آزمون ویژگی RESOURCE_GROUPS <#prop_test:RESOURCE_GROUPS> را مشخص کند، در صورتی که کاربر یک فایل مشخصات منابع را ارائه ندهد، همچنان این امکان وجود دارد که آن آزمون بدون هیچ‌گونه تخصیص منابع (و بدون متغیرهای محیطی متناظر) اجرا شود. ارائه این فایل، چه از طریق آرگومان خط فرمان --resource-spec-file یا آرگومان RESOURCE_SPEC_FILE در ctest_test() <#command:ctest_test>، چیزی است که قابلیت تخصیص منابع را فعال می‌کند. آزمون‌ها باید متغیر محیطی CTEST_RESOURCE_GROUP_COUNT را بررسی کنند تا دریابند که آیا تخصیص منابع فعال است یا خیر. این متغیر همیشه (و تنها) در صورتی تعریف خواهد شد که تخصیص منابع فعال باشد. اگر تخصیص منابع فعال نباشد، آنگاه متغیر CTEST_RESOURCE_GROUP_COUNT وجود نخواهد داشت، حتی اگر برای فرایند والد ctest وجود داشته باشد. اگر یک آزمون قطعاً باید دارای تخصیص منابع باشد، می‌تواند یک کد خروج شکست‌خورده برگرداند یا از ویژگی‌های SKIP_RETURN_CODE <#prop_test:SKIP_RETURN_CODE> یا SKIP_REGULAR_EXPRESSION <#prop_test:SKIP_REGULAR_EXPRESSION> برای نشان دادن رد شدن (skip) آزمون استفاده کند.

فایل مشخصات منابع یک فایل JSON است که به یکی از چندین روش به CTest ارسال می‌شود. این فایل می‌تواند در خط فرمان با گزینه --resource-spec-file مشخص شود، با استفاده از آرگومان RESOURCE_SPEC_FILE در ctest_test() <#command:ctest_test> تعیین گردد، یا می‌تواند به‌طور پویا به عنوان بخشی از اجرای آزمون تولید شود (به «فایل مشخصات منابع تولید شده پویا» مراجعه کنید).

اگر از یک اسکریپت داشبورد استفاده شود و RESOURCE_SPEC_FILE مشخص نشده باشد، مقدار CTEST_RESOURCE_SPEC_FILE <#variable:CTEST_RESOURCE_SPEC_FILE> در اسکریپت داشبورد به جای آن استفاده می‌شود. اگر --resource-spec-file، RESOURCE_SPEC_FILE و CTEST_RESOURCE_SPEC_FILE <#variable:CTEST_RESOURCE_SPEC_FILE> در اسکریپت داشبورد مشخص نشده باشند، مقدار CTEST_RESOURCE_SPEC_FILE <#variable:CTEST_RESOURCE_SPEC_FILE> در بیلد CMake به جای آن استفاده می‌شود. اگر هیچ‌یک از این موارد مشخص نشده باشند، هیچ فایل مشخصات منبعی استفاده نخواهد شد.

فایل مشخصات منابع باید یک شیء JSON باشد. تمامی مثال‌های این سند فایل مشخصات منابع زیر را فرض می‌کنند:

{
  "version": {
    "major": 1,
    "minor": 0
  },
  "local": [
    {
      "gpus": [
        {
          "id": "0",
          "slots": 2
        },
        {
          "id": "1",
          "slots": 4
        },
        {
          "id": "2",
          "slots": 2
        },
        {
          "id": "3"
        }
      ],
      "crypto_chips": [
        {
          "id": "card0",
          "slots": 4
        }
      ]
    }
  ]
}

اعضای این شیء عبارتند از:

یک شیء شامل یک فیلد عدد صحیح major و یک فیلد عدد صحیح minor. در حال حاضر، تنها نسخه پشتیبانی‌شده نسخه اصلی (major) 1 و نسخه فرعی (minor) 0 است. هر مقدار دیگری خطا محسوب می‌شود.
یک آرایه JSON از مجموعه‌های منابع موجود در سیستم. در حال حاضر، اندازه این آرایه به ۱ محدود شده است.

هر عنصر آرایه یک شیء JSON با اعضایی است که نام‌های آن‌ها برابر با انواع منابع مورد نظر، مانند gpus است. این نام‌ها باید با یک حرف کوچک انگلیسی یا زیرخط شروع شوند، و کاراکترهای بعدی می‌توانند یک حرف کوچک، یک رقم یا یک زیرخط باشند. حروف بزرگ مجاز نیستند، زیرا برخی از پلتفرم‌ها متغیرهای محیطی بدون حساسیت به حروف کوچک و بزرگ دارند. برای اطلاعات بیشتر، بخش «متغیرهای محیطی (Environment Variables)» در زیر را ببینید. توصیه می‌شود نام نوع منبع جمع یک اسم باشد، مانند gpus یا crypto_chips (و نه gpu یا crypto_chip).

لطفاً توجه داشته باشید که نام‌های gpus و crypto_chips صرفاً مثال هستند و CTest به هیچ وجه آن‌ها را تفسیر نمی‌کند. شما آزادید هر نوع منبعی را که می‌خواهید برای برآوردن نیازمندی‌های خود تعریف کنید.

مقدار مربوط به هر نوع منبع، یک آرایه JSON متشکل از اشیاء JSON است که هر یک از آن‌ها یک نمونه خاص از منبع مشخص‌شده را توصیف می‌کنند. این اشیاء دارای اعضای زیر هستند:

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

شناسه‌ها باید در یک نوع منبع یکتا باشند. با این حال، نیازی نیست که در بین انواع مختلف منابع یکتا باشند. به عنوان مثال، داشتن یک منبع gpus با نام 0 و یک منبع crypto_chips با نام 0 معتبر است، اما وجود دو منبع gpus که هر دو دارای نام 0 باشند مجاز نیست.

لطفاً توجه داشته باشید که شناسه‌های 0، 1، 2، 3 و card0 صرفاً مثال هستند و CTest به هیچ وجه آن‌ها را تفسیر نمی‌کند. شما آزادید هر شناسه‌ای را که برای برآوردن نیازمندی‌های خود می‌خواهید بسازید.

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

در فایل نمونه بالا، چهار GPU با شناسه‌های 0 تا 3 وجود دارند. پردازنده گرافیکی 0 دارای ۲ اسلات، GPU 1 دارای ۴ اسلات، GPU 2 دارای ۲ اسلات، و GPU 3 دارای مقدار پیش‌فرض ۱ اسلات است. همچنین یک تراشه رمزنگاری با ۴ اسلات وجود دارد.

برای شرح این ویژگی، به RESOURCE_GROUPS <#prop_test:RESOURCE_GROUPS> مراجعه کنید.

هنگامی که CTest تصمیم گرفت چه منابعی را به یک آزمون اختصاص دهد، این اطلاعات را به عنوان مجموعه‌ای از متغیرهای محیطی به فایل اجرایی آزمون ارسال می‌کند. برای هر مثال زیر، فرض می‌کنیم که آزمون مورد نظر دارای ویژگی RESOURCE_GROUPS <#prop_test:RESOURCE_GROUPS> با مقدار 2,gpus:2;gpus:4,gpus:1,crypto_chips:2 است.

متغیرهای زیر به فرآیند آزمون ارسال می‌شوند:

تعداد کل گروه‌های مشخص‌شده توسط ویژگی RESOURCE_GROUPS <#prop_test:RESOURCE_GROUPS>. برای مثال:
•
CTEST_RESOURCE_GROUP_COUNT=3

این متغیر تنها زمانی تعریف خواهد شد که به ctest(1) گزینه --resource-spec-file داده شده باشد، یا به ctest_test() <#command:ctest_test> آرگومان RESOURCE_SPEC_FILE ارائه شده باشد. اگر هیچ فایل مشخصات منبعی داده نشده باشد، این متغیر تعریف نخواهد شد.

فهرست انواع منابع تخصیص‌یافته به هر گروه، در حالی که هر مورد با کاما از دیگری جدا شده است. <num> عددی از صفر تا CTEST_RESOURCE_GROUP_COUNT منهای یک است. CTEST_RESOURCE_GROUP_<num> برای هر <num> در این محدوده تعریف می‌شود. برای مثال:
  • CTEST_RESOURCE_GROUP_0=gpus
  • CTEST_RESOURCE_GROUP_1=gpus
  • CTEST_RESOURCE_GROUP_2=crypto_chips,gpus
فهرست شناسه‌های منابع و تعداد اسلات‌های اختصاص‌یافته از هر شناسه به هر گروه برای یک نوع منبع مشخص. این متغیر شامل مجموعه‌ای از جفت‌ها است که هر جفت با یک نقطه ویرگول (سیکولن) جدا شده و دو مورد داخل هر جفت با کاما تفکیک شده‌اند. اولین مورد در هر جفت id: به دنبال شناسه منبعی از نوع <resource-type> است، و دومین مورد slots: به دنبال تعداد اسلات‌های تخصیص‌یافته از آن منبع به گروه داده‌شده است. برای مثال:
  • CTEST_RESOURCE_GROUP_0_GPUS=id:0,slots:2
  • CTEST_RESOURCE_GROUP_1_GPUS=id:2,slots:2
  • CTEST_RESOURCE_GROUP_2_GPUS=id:1,slots:4;id:3,slots:1
  • CTEST_RESOURCE_GROUP_2_CRYPTO_CHIPS=id:card0,slots:2

در این مثال، گروه 0 تعداد ۲ اسلات از پردازنده گرافیکی 0، گروه 1 تعداد ۲ اسلات از پردازنده گرافیکی 2، و گروه 2 تعداد ۴ اسلات از پردازنده گرافیکی 1، ۱ اسلات از پردازنده گرافیکی 3، و ۲ اسلات از تراشه رمزنگاری card0 دریافت می‌کند.

<num> عددی از صفر تا CTEST_RESOURCE_GROUP_COUNT منهای یک است. <resource-type> نام یک نوع منبع است که به حروف بزرگ تبدیل شده است. CTEST_RESOURCE_GROUP_<num>_<resource-type> برای حاصل‌ضرب هر <num> در محدوده ذکرشده در بالا و هر نوع منبع ذکرشده در CTEST_RESOURCE_GROUP_<num> تعریف می‌شود.

از آنجا که برخی پلتفرم‌ها برای متغیرهای محیطی نام‌های غیرحساس به حروف بزرگ و کوچک دارند، نام‌های انواع منابع نباید در یک محیط بدون حساسیت به حروف تداخل داشته باشند. به همین دلیل، برای سادگی، تمام انواع منابع باید در فایل مشخصات منابع و در ویژگی RESOURCE_GROUPS <#prop_test:RESOURCE_GROUPS> به صورت کاملاً با حروف کوچک ذکر شوند، و در متغیر محیطی CTEST_RESOURCE_GROUP_<num>_<resource-type> به حروف کاملاً بزرگ تبدیل می‌شوند.

افزوده‌شده در نسخه 3.28.

یک پروژه می‌تواند به صورت اختیاری یک آزمون واحد را مشخص کند که برای تولید پویای فایل مشخصات منابع استفاده می‌شود؛ فایلی که CTest از آن برای زمان‌بندی آزمون‌های مصرف‌کننده منابع استفاده خواهد کرد. آزمونی که فایل را تولید می‌کند باید ویژگی GENERATED_RESOURCE_SPEC_FILE <#prop_test:GENERATED_RESOURCE_SPEC_FILE> را تنظیم کرده باشد، و باید دقیقاً یک فیکسچر در ویژگی FIXTURES_SETUP <#prop_test:FIXTURES_SETUP> خود داشته باشد. این فیکسچر از نظر CTest معنای ویژه‌ای دارد: این فیکسچری است که فایل مشخصات منبع را تولید می‌کند. این فیکسچر می‌تواند هر نامی داشته باشد. در صورت وجود چنین فیکسچری، تمام آزمون‌هایی که ویژگی RESOURCE_GROUPS <#prop_test:RESOURCE_GROUPS> را تنظیم کرده‌اند باید این فیکسچر را در FIXTURES_REQUIRED <#prop_test:FIXTURES_REQUIRED> خود داشته باشند، و فایل مشخصات منبع نباید با آرگومان --resource-spec-file یا متغیر CTEST_RESOURCE_SPEC_FILE <#variable:CTEST_RESOURCE_SPEC_FILE> مشخص شده باشد.

افزوده‌شده در نسخه 3.29.

در سیستم‌های پازیکس (POSIX)، هنگام اجرا در زمینه یک سرور کارها (Job Server) https://www.gnu.org/software/make/manual/html_node/Job-Slots.html، برنامه CTest اسلات‌های کاری خود را به اشتراک می‌گذارد. این امر مستقل از ویژگی آزمون PROCESSORS <#prop_test:PROCESSORS> است که همچنان در سطح موازی‌سازی -j برنامه CTest محاسبه می‌شود. برنامه CTest پیش از اجرای هر آزمون دقیقاً یک توکن از سرور کارها دریافت می‌کند و پس از اتمام آزمون آن را بازمی‌گرداند.

برای مثال، این Makefile را در نظر بگیرید:

test:
	+ctest -j 8

هنگام فراخوانی از طریق make -j 2 test، برنامه CTest به سرور کارها متصل می‌شود، یک توکن برای هر آزمون دریافت می‌کند، و حداکثر ۲ آزمون را به طور همزمان اجرا می‌کند.

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

منابع زیر برای دریافت راهنما در استفاده از CMake در دسترس هستند:

https://cmake.org

نقطه شروع اصلی برای یادگیری درباره CMake.

https://cmake.org/documentation

پیوندهای مربوط به مستندات موجود و منابع انجمن را می‌توان در این صفحه وب یافت.

https://discourse.cmake.org

تالار گفتگوی Discourse میزبان گفتگوها و پرسش‌ها پیرامون CMake است.

2000-2026 Kitware, Inc. and Contributors

August 31, 2026 4.4.3