cinch
Release 1.0
Cinch هي مجموعة من الأدوات المساعدة وخيارات التكوين المصممة لجعل Cmake يبني سهلة الاستخدام والإدارة.
يستخدم Cinch ميزات تثبيت Cmake القياسية. ومع ذلك ، نظرًا لأن Cinch يعتمد على أداة سطر الأوامر الخاصة بها (Cinch-Utils) لبناء وثائقها ، يجب تثبيتها في المراحل الموثقة في هذا القسم.
الاتجاهات لتثبيت Cinch-estils موجودة هنا.
لتثبيت وثائق Cinch ، يجب عليك تشغيل Cmake في دليل إنشاء Cinch مع تمكين الوثائق:
% cmake -DCMAKE_INSTALL_PREFIX=/path/to/install -DENABLE_DOCUMENTATION=ON ..
% make install
تم تصميم نظام بناء Cinch لجعل تطوير التعليمات البرمجية المعيارية أمرًا سهلاً. حسب المعيار ، نعني أنه يمكن دمج المشروعات الفرعية في مشروع من المستوى الأعلى القائم على Cinch ، وسيتم إضافتها تلقائيًا إلى أهداف بناء المشروع الأعلى. هذا يجعل من السهل إنشاء مشاريع جديدة تجمع بين قدرات مجموعة من المشاريع الفرعية. يتيح ذلك للمستخدمين بناء الوظائف والتحكم في وظائف المشروع الأعلى.
يمنع Cinch المستخدمين من إنشاء تصميمات في مكانها ، على سبيل المثال ، تم تصميمها في دليل المشروع على المستوى الأعلى لمشروع Cinch. إذا حاول المستخدم تكوين مثل هذا الإنشاء ، فسوف يخرج Cmake بخطأ وتعليمات حول كيفية تنظيف وإنشاء بناء خارج المصدر.
Cinch يخفف من صياغة نظام البناء عن طريق فرض بنية محددة على تخطيط مصدر المشروع.
project/
app/ (optional application subdirectory)
cinch/
CMakeLists.txt -> cinch/cmake/ProjectLists.txt
config/
documentation.cmake
packages.cmake
project.cmake
doc/
src/ (optional library source subdirectory)
CMakeLists.txt -> cinch/cmake/SourceLists.txt
قد يكون لديك أيضًا أي عدد من العروض الفرعية تحت دليل المشروع.
دليل المستوى الأعلى.
دليل التطبيق الفرعي المستهدف. يمكن إضافة أهداف التطبيق باستخدام cinch_add_application_directory الموثقة أدناه. يجب أن يحتوي هذا الدليل الفرعي على ملف cmakelists.txt الذي يضيف أي أهداف CMake مطلوبة للتطبيق المحدد.
دليل سينش الفرعي. يجب التحقق من ذلك من خادم cinch git: 'git [email protected]: losalamos/cinch.git'.
قم بإنشاء ملف ، والذي يعين cmake_minimum_required () ويتضمن ملف cinch projectlists.txt.
دليل تكوين المشروع. هذا الدليل مغطى بالتفصيل أدناه.
وثائق الدليل الفرعي. يجب أن يحتوي هذا الدليل الفرعي على ملفات تكوين لوثائق الدليل المولدة من Cinch ، وتوثيق واجهة Doxygen.
دليل مصدر مستهدف المكتبة. يمكن إضافة أهداف المكتبة باستخدام cinch_add_library_target الموثق أدناه.
يجب أن يحتوي دليل التكوين الفرعي على الملفات التالية التي توفر تخصص المشروع. على الرغم من أن جميع الملفات يجب أن تكون موجودة ، فإن الملف الوحيد المطلوب للحصول على محتوى هو ملف project.cmake .
لا يمكن أن يكون هذا الملف فارغًا. على الأقل ، يجب أن تحدد اسم المشروع الأعلى من خلال استدعاء وظيفة مشروع CMAKE لتعيين الاسم والإصدار واللغات الممكّنة للمشروع بأكمله. لمزيد من الوثائق ، في مطالبة على جهاز مع تثبيت cmake صالح ، اكتب:
٪ Cmake -Help Project
بالإضافة إلى ذلك ، قد يتصل هذا الملف بوظيفة cinch التالية (قد تترك أيضًا خالية):
cinch_add_application_directory (موثق هنا)
أضف دليل بناء خاص بالمشروع يجب تضمينه بواسطة CMake عند البحث عن ملفات قائمة. يجب أن يحتوي هذا الدليل على ملف cmakelists.txt صالح يقوم بتكوين أهداف بناء إضافية.
cinch_add_library_target (موثق هنا)
أضف هدف المكتبة للبناء لهذا المشروع.
cinch_add_subproject (موثق هنا)
إضافة مشروع فرعي لهذا المشروع.
يتم استخدام هذا الملف لتحديد متطلبات Cmake Find_Package لتحديد موقع حزم الجهات الخارجية المثبتة. يمكن أن يكون محتوى هذا الملف أي مجموعة من أوامر cmake صالحة. ستكون القيم التي يتم تعيينها في هذا الملف متاحة لملفات cmakelists.txt ذات المستوى المنخفض لتكوين خيارات الإنشاء على مستوى المصدر.
يتم استخدام هذا الملف لإضافة أهداف الوثائق مع واجهة Cinch_add_doc (يتم التعامل مع وثائق doxygen بشكل منفصل).
يوفر Cinch العديد من خيارات سطر الأوامر التي قد يتم تمريرها على خط تكوين CMAKE للتأثير على سلوكه.
خيار Cmake: enable_cinch_development (افتراضي)
ضع cinch في وضع التطوير. يؤثر هذا الخيار على بعض المعلومات التي يتم إنشاؤها بواسطة Cinch والتي هي مفيدة للمرشحين غير النشر. إذا تم تمكين هذا الخيار ، فسيتم تشغيل الميزات التالية:
خيار Cmake: enable_cinch_verbose (افتراضي)
تمكين المزيد من الإخراج التفصيلي.
خيار Cmake: enable_documentation (افتراضي)
لدى Cinch منشأة توثيق قوية تم تنفيذها باستخدام أداة سطر الأوامر Cinch و Pandoc. لإنشاء الوثائق ، حدد ملف التكوين لكل مستند يجب إنشاؤه في دليل "Doc" الفرعي. بعد ذلك ، أضف ملفات Markdown (.md) أو LaTex (.tex) إلى شجرة المصدر التي توثق أي جوانب المشروع يجب تضمينها. التحذير هو أن شظايا الوثائق هذه يجب أن يكون لها رأس تعليق خاص في بداية كل ، من النموذج:
<!-- CINCHDOC DOCUMENT(Name of Document) SECTION(Name of Section) -->
يشير هذا الرأس الخاص إلى الوثيقة المقصود من الشظية والقسم الذي يجب أن يظهر فيه. قد تمتد الرؤوس على خطوط متعددة شريطة أن يكون <!-- CINCHDOC يبدأ التعليق. إذا لم يتم تحديد أي سمات (المستند ، القسم ، إلخ) ، فستستخدم الأداة المساعدة مستندًا وقسمًا افتراضيًا ("افتراضي" و "افتراضي"). قد يتم تضمين شظايا متعددة مخصصة لمستندات وأقسام مختلفة داخل ملف إدخال واحد. بالنسبة لشظايا اللاتكس ، استخدم رأس النموذج:
% CINCHDOC DOCUMENT(Name of Document) SECTION(Name of Section)
يجب أن تكون رؤوس Cinchdoc على الطراز اللاتكس على خط واحد.
يمكن إضافة أهداف الإنشاء إلى ملف documentation.cmake في دليل التكوين. يجب إنشاء كل هدف عن طريق الاتصال:
cinch_add_doc (إخراج config.py top-level-search-directory)
الاسم الهدف ، سيتم إنشاء تسمية Target Target ، أي ، هدفًا بحيث يمكن استدعاء "جعل الاسم الهدف" لإنشاء هدف الوثائق.
config.py ملف التكوين الذي يجب أن يعيش في دليل "Doc" الفرعي للدليل على مستوى أعلى لمشروعك. يجب أن يحتوي هذا الملف على قاموس Python واحد اختيار يضبط خيارات واجهة خط الأوامر Cinch لاستمرار المستندات الخاصة بك.
من أعلى مستوى البحث ، فإن المسار النسبي لرئيس شجرة الدليل والذي يتم من خلاله البحث عن ملفات الوثائق المميزة.
إخراج اسم ملف الإخراج الذي يجب إنتاجه بواسطة Pandoc.
خيار Cmake: Enable_doxygen (افتراضي) خيار Cmake: enable_doxygen_warn (افتراضي)
يدعم Cinch وثائق الواجهة باستخدام Doxygen. يجب أن يسمى ملف تكوين doxygen "doxygen.conf.in" ويجب أن يقيم في الدليل الفرعي "Doc". للحصول على وثائق حول استخدام Doxygen ، يرجى إلقاء نظرة على صفحة Doxygen الرئيسية.
إذا تم تعيين enable_doxygen_warn على التشغيل ، فلن يتم قمع التشخيصات والتحذيرات doxygen العادية.
خيار Cmake: enable_unit_tests (افتراضي)
يتمتع Cinch بدعم لاختبار الوحدة باستخدام مجموعة من CTEST (مرفق اختبار CMAKE الأصلي) و googletest (لدعم C ++). إذا تم تمكين اختبارات الوحدة ، فسيقوم Cinch بإنشاء هدف "اختبار". يمكن إضافة اختبارات الوحدة في أي دليل فرعي للمشروع ببساطة إنشاء رمز مصدر الاختبار وإضافة هدف باستخدام وظيفة "cinch_add_unit (قائمة المصدر]).
سيقوم Cinch بالتحقق من الحصول على غوغليت محلي على النظام أثناء خطوة تكوين CMAKE. إذا لم يتم العثور على googletest ، فسيتم بناؤه بواسطة Cinch (يتم تضمين Googletest Source Code مع Cinch).
خيار Cmake: clog_enable_stdlog (إيقاف افتراضي)
خيار CMake: Clog_strip_level (افتراضي "0")
Cmake Option: Clog_tag_bits (افتراضي "16")
خيار Cmake: Clog_Color_output (إيقاف افتراضي)
يحظى Cinch بدعم Trace و Info و Warn والخطأ والإبلاغ عن السجل المميت (على غرار Google Log). هناك نوعان من أنماط واجهة لتسجيل المعلومات باستخدام السد: نمط الإدراج ، على سبيل المثال ،
clog (info) << "This is some information" << std::endl;وواجهة طريقة ، على سبيل المثال ،
clog_info ( " This is some information " );كلا أنماط الواجهة متوفرة لجميع مستويات الشدة (تمت مناقشتها أدناه).
ملاحظة: يتوفر CLOG تلقائيًا لاختبارات وحدة Cinch.
clog_init ( " group1,group2,group3 " ); clog (error) << "This is an error level severity message" << std::endl; clog_info ( " The number is " << number); clog_every_n (شدة ، رسالة ، ن)
إخراج كل تكرار ناتج باستخدام الشدة والرسالة . لا يتم تعريف هذه الطريقة لمستوى الشدة المميت أو التأكيدات.
clog_assert (اختبار ، رسالة)
تأكيد أن الاختبار صحيح. إذا كان الاختبار خطأ ، فسيتم تنفيذ هذه المكالمة clog_fatal (رسالة) .
clog_add_buffer (الاسم ، ostream ، ملونة)
أضف المخزن المؤقت المحدد بواسطة وسيطة Ostream في RDBUF (). اسم المعلمة الثاني هو اسم السلسلة لربطه بالمخزن المؤقت ، ويمكن استخدامه في المكالمات اللاحقة إلى واجهة Clog Buffer. تشير المعلمة الأخيرة إلى ما إذا كان المخزن المؤقت يدعم إخراج اللون أم لا.
clog_enable_buffer (اسم)
تمكين المخزن المؤقت المحدد بالاسم .
clog_disable_buffer (اسم)
تعطيل المخزن المؤقت المحدد بالاسم .
يمكن أن تكتب السد الإخراج إلى تدفقات الإخراج المتعددة في وقت واحد. يمكن للمستخدمين التحكم في ملفات السجل والإخراج التي يتم إنشاؤها عن طريق إضافة وتمكين/تعطيل تدفقات الإخراج المختلفة. بشكل افتراضي ، يقوم CLOG بتوجيه الإخراج إلى STD :: CLOG (هذا هو IoStream الافتراضي C ++ وليس جزءًا من السد) عند تحديد متغير بيئة Clog_enable_stdlog . يجب إضافة تدفقات الإخراج الأخرى بواسطة تطبيق المستخدم. على سبيل المثال ، إذا كان تطبيق المستخدم يريد أن ينتقل إخراج السد إلى ملف يسمى Output.log ، يمكن للمرء القيام بما يلي:
# include < ofstream >
# include " cinchlog.h "
int main ( int argc, char ** argv) {
// Initialize CLOG with output for all tag groups (discussed below)
clog_init ( " all " );
// Open an output stream for "output.log"
std::ofstream output ( " output.log " );
// Add the stream to CLOG:
// param 1 ("output") The string name of the buffer.
// param 2 (output) The stream (CLOG will call stream.rdbuf() on this).
// param 3 (false) A boolean denoting whether or not the buffer
// supports colorization.
//
// Note that output is automatically enabled for buffers when they
// are added. Buffers can be disable with clog_disable_buffer(string name),
// and re-enabled with clog_enable_buffer(string name).
clog_add_buffer ( " output " , output, false );
// Write some information to the output file (and to std::clog if enabled)
clog (info) << " This will go to output.log " << std::endl;
return 0 ;
} // mainيمكن التحكم في إخراج السد في وقت الترجمة عن طريق تحديد مستوى شدة معين. سيتم تعطيل أي رسائل تسجيل مع مستوى شدة أقل من تلك المحددة بواسطة CLOG_STRIP_LEVEL . لاحظ أن هذا يعني أن السد لن ينتج أي إخراج لـ clog_strip_level> = 5 .
مستويات الشدة المختلفة لها السلوك التالي:
يتعقب
ممكّن فقط لمستوى الشدة 0 (أقل من 1)
ناتج التتبع مناسب لمعلومات التسجيل الدقيقة.
معلومات
تمكين لمستويات الشدة أقل من 2
إخراج المعلومات مناسب لمعلومات التسجيل العادية.
تحذير
تمكين لمستويات الشدة أقل من 3
تحذير الإخراج مفيد لإصدار التحذيرات. عند تمكين clog_color_output ، سيتم عرض الرسائل تحذير باللون الأصفر.
خطأ
تمكين لمستويات الشدة أقل من 4
إخراج الخطأ مفيد لإصدار الأخطاء غير المميتة. عند تمكين clog_color_output ، سيتم عرض رسائل الخطأ باللون الأحمر.
مميت
تمكين لمستويات الشدة أقل من 5
إخراج الخطأ المميت مفيد لإصدار أخطاء مميتة. أخطاء قاتلة طباعة رسالة ، وتفريغ تتبع المكدس الحالي ، واتصل std :: exit (1). عند تمكين clog_color_output ، سيتم عرض الرسائل القاتلة باللون الأحمر.
التحكم في وقت التشغيل لإخراج السد من خلال إضافة أقسام النطاق في الكود المصدر. يشار إلى هذه مجموعات العلامات لأن القسم الناطق المسمى بعلامة. يتم التحكم في عدد مجموعات العلامات الممكنة بواسطة CLOG_TAG_BITS (الافتراضي 16). يمكن تمكين مجموعات العلامات أو تعطيلها في وقت التشغيل من خلال تحديد قائمة مجموعات العلامات على وظيفة CLOG_INIT . بشكل عام ، يتم التحكم في هذه العلم خط أوامر يتم تفسيرها بواسطة تطبيق المستخدم. فيما يلي رمز مثال باستخدام GFLAGs للتحكم في الإخراج:
# include < gflags/gflags.h >
// Create a command-line flag "--groups" with default value "all"
DEFINE_string (groups, " all " , " Specify the active tag groups " );
# include " cinchlog.h "
int main ( int argc, char ** argv) {
// Parse the command-line arguments
gflags::ParseCommandLineFlags (&argc, &argv, true );
// If the user has specified tag groups with --groups=group1, ...
// these groups will be enabled. Recall that the default is "all".
clog_init (FLAGS_groups);
{
// Create a new tag scope. Log messages within this scope will
// only be output if tag group "tag1" or tag group "all" is enabled.
clog_tag_scope (tag1);
clog (info) << " Enabled for tag group tag1 " << std::endl;
clog (warn) << " This is a warning in group tag1 " << std::endl;
} // scope
{
// Create a new tag scope. Log messages within this scope will
// only be output if tag group "tag2" or tag group "all" is enabled.
clog_tag_scope (tag2);
clog (info) << " Enabled for tag group tag2 " << std::endl;
clog (error) << " This is an error in group tag2 " << std::endl;
} // scope
clog (info) << " This output is not scoped " << std::endl;
return 0 ;
} // mainيعمل رمز المثال:
% ./example --groups=tag1
% [I1225 11:59:59 example.cc:22] Enabled for tag group tag1
% [W1225 11:59:59 example.cc:24] This is a warning in group tag1
% [I1225 11:59:59 example.cc:37] This output is not scoped
% ./example --groups=tag2
% [I1225 11:59:59 example.cc:32] Enabled for tag group tag1
% [E1225 11:59:59 example.cc:34] This is an error in group tag2
% [I1225 11:59:59 example.cc:37] This output is not scoped
% ./example
% [I1225 11:59:59 example.cc:22] Enabled for tag group tag1
% [W1225 11:59:59 example.cc:24] This is a warning in group tag1
% [I1225 11:59:59 example.cc:32] Enabled for tag group tag1
% [E1225 11:59:59 example.cc:34] This is an error in group tag2
% [I1225 11:59:59 example.cc:37] This output is not scoped
يتم تنفيذ واجهة السد العادية من خلال مجموعة من وحدات الماكرو. يمكن للمستخدمين المتقدمين ، الذين يحتاجون إلى تحكم أكبر على السداد ، إنشاء واجهاتهم الخاصة (الماكرو أو غير ذلك) للوصول مباشرة إلى واجهة السد ذات المستوى المنخفض. تسجل رسائل في السد مشتق من نوع Cinch :: log_message_t ، والذي يوفر مُنشئًا ومدمرة افتراضية وطريقة دفق افتراضي:
template < typename P>
struct log_message_t
{
// Constructor:
// param 1 (file) The originating file of the message (__FILE__)
// param 2 (line) The originating line of the mesasge (__LINE__)
// param 3 (predicate) A predicate function that can be used to
// control output.
log_message_t (
const char * file,
int line,
P && predicate
)
{
// See cinchlog.h for implementation.
} // log_message_t
// Destructor.
virtual
~log_message_t ()
{
// See cinchlog.h for implementation.
} // ~log_message_t
// Stream method.
virtual
std::ostream &
stream ()
{
// See cinchlog.h for implementation.
} // stream
}; // struct log_message_tيمكن للمستخدمين الذين يرغبون في تخصيص تسد القبعة تغيير السلوك الافتراضي من خلال تجاوز الأساليب الافتراضية لهذا النوع ، وتوفير مستحضرات مخصصة. يتم تنفيذ جزء كبير من وظائف السد الأساسية بهذه الطريقة ، على سبيل المثال ، الرمز التالي ينفذ إخراج شدة مستوى التتبع:
# define severity_message_t ( severity, P, format )
struct severity ## _log_message_t
: public log_message_t <P>
{
severity ## _log_message_t (
const char * file,
int line,
P && predicate = true_state)
: log_message_t <P>(file, line, predicate) {}
~severity ## _log_message_t ()
{
/* Clean colors from the stream */
clog_t::instance (). stream () << COLOR_PLAIN;
}
std::ostream &
stream () override
/* This is replaced by the scoped logic */
format
};
// ----------------------------------------------------------------------------//
// Define the insertion style severity levels.
// ----------------------------------------------------------------------------//
# define message_stamp
timestamp () << " " << rstrip<'/'>(file_) << ":" << line_
severity_message_t(trace, decltype(cinch::true_state),
{
# if CLOG_STRIP_LEVEL < 1
if ( clog_t::instance (). tag_enabled () && predicate_ ()) {
std::ostream & stream = clog_t::instance (). stream ();
stream << OUTPUT_CYAN ( " [T " ) << OUTPUT_LTGRAY (message_stamp);
stream << OUTPUT_CYAN ( " ] " );
return stream;
}
else {
return clog_t::instance (). null_stream ();
} // if
# else
return clog_t::instance (). null_stream ();
# endif
});يجب على المستخدمين المهتمين النظر في الكود المصدر لمزيد من الأمثلة.
Cmake Option: version_creation (الافتراضي "GIT الوصف")
يمكن لـ Cinch إنشاء معلومات الإصدار تلقائيًا للمشاريع التي تستخدم GIT. تستخدم هذه الميزة وظيفة "GIT الوصف" ، والتي تنشئ إصدارًا من أحدث علامة شرحية مع مستوى التصحيح بناءً على عدد الالتزامات منذ تلك العلامة ومفتاح التجزئة الجزئي. على سبيل المثال ، إذا كانت أحدث علامة شرحية هي "1.0" وكان هناك 35 عملاً منذ ذلك الحين ، فستكون النسخة التي تم إنشاؤها من Cinch مشابهة لـ: 1.0-35-G2F657A
للإصدارات الفعلية ، قد لا يكون هذا النهج الأمثل. في هذه الحالة ، يسمح لك Cinch بتجاوز الإصدار التلقائي عن طريق تحديد إصدار ثابت إلى CMake عبر خيار الإصدار _creation. ما عليك سوى تعيين هذا على الإصدار المطلوب وسيتم استخدامه.
تمت الموافقة على هذا البرنامج لإصدار مفتوح المصدر وتم تعيينه LA-CC-15-070 .
حقوق الطبع والنشر (C) 2016 ، Los Alamos National Security ، LLC جميع الحقوق محفوظة.
حقوق الطبع والنشر 2016. لوس ألاموس الأمن القومي ، LLC. تم إنتاج هذا البرنامج بموجب عقد الحكومة الأمريكية DE-AC52-06NA25396 لمختبر لوس ألاموس الوطني (LANL) ، الذي تديره LOS Alamos National Security ، LLC لوزارة الطاقة الأمريكية. حكومة الولايات المتحدة لديها حقوق في استخدام هذا البرنامج وإعادة إنتاجه وتوزيعه. لا تقوم الحكومة أو Los Alamos National Security ، LLC بأي ضمان أو صريح أو ضمني ، أو تتحمل أي مسؤولية عن استخدام هذا البرنامج. إذا تم تعديل البرنامج لإنتاج أعمال مشتقة ، فيجب وضع علامة على هذا البرامج المعدلة بوضوح ، حتى لا تخلط بينها مع الإصدار المتاح من LANL.
بالإضافة إلى ذلك ، يُسمح بإعادة التوزيع والاستخدام في النماذج المصدر والثنائية ، مع أو بدون تعديل ، شريطة استيفاء الشروط التالية:
يجب أن تحتفظ إعادة توزيع رمز المصدر بإشعار حقوق الطبع والنشر أعلاه ، وقائمة الشروط هذه وإخلاء المسؤولية التالية.
يجب أن تقوم إعادة التوزيع في النموذج الثنائي بإعادة إنتاج إشعار حقوق الطبع والنشر أعلاه ، وقائمة الشروط هذه وإخلاء المسؤولية التالية في الوثائق و/أو المواد الأخرى المتوفرة مع التوزيع.
لا يجوز استخدام اسم Los Alamos National Security ، LLC ، Los Alamos National Laboratory ، Lanl ، حكومة الولايات المتحدة ، ولا أسماء مساهميها لتأييد أو الترويج للمنتجات المستمدة من هذا البرنامج دون إذن كتابي مسبق محدد.
يتم توفير هذا البرنامج من قبل Los Alamos National Security ، LLC والمساهمين "كما هو" وأي ضمانات صريحة أو ضمنية ، بما في ذلك ، على سبيل المثال لا الحصر ، الضمانات الضمنية للتسويق والملاءمة لغرض معين. لا يجوز بأي حال من الأحوال أن يتحمل Los Alamos National Security أو LLC أو المساهمين أي أضرار مباشرة أو غير مباشرة أو عرضية أو خاصة أو مثالية أو تبعية (بما في ذلك ، على سبيل المثال لا الحصر ، شراء السلع أو الخدمات البديلة ؛ فقدان الاستخدام ، البيانات ، البيانات ، أو الأرباح ؛ أو انقطاع الأعمال) ومع ذلك ، وعلى أي نظرية للمسؤولية ، سواء في العقد ، أو المسؤولية الصارمة أو الضرر (بما في ذلك الإهمال مثل هذا الضرر.
