cr
1.0.0
/*
حل إعادة التحميل المباشر لرأس ملف واحد فقط للغة C، مكتوب بلغة C++:
ملحوظة: الملف الوحيد المهم في هذا المستودع هو cr.h .
يحتوي هذا الملف على وثائق تخفيض السعر والترخيص والتنفيذ وواجهة برمجة التطبيقات العامة. جميع الملفات الأخرى الموجودة في هذا المستودع هي ملفات داعمة ويمكن تجاهلها بأمان.
يمكنك تنزيل وتثبيت cr باستخدام مدير التبعيات vcpkg:
git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
./vcpkg install cr
يتم تحديث منفذ cr في vcpkg بواسطة أعضاء فريق Microsoft والمساهمين في المجتمع. إذا كان الإصدار قديمًا، فيرجى إنشاء مشكلة أو سحب طلب على مستودع vcpkg.
سيستفيد التطبيق المضيف (الرفيع) القابل للتنفيذ من cr لإدارة إعادة التحميل المباشر للتطبيق الحقيقي في شكل ثنائي ديناميكي قابل للتحميل، وسيكون المضيف شيئًا مثل:
#define CR_HOST // required in the host only and before including cr.h
#include "../cr.h"
int main ( int argc , char * argv []) {
// the host application should initalize a plugin with a context, a plugin
cr_plugin ctx ;
// the full path to the live-reloadable application
cr_plugin_open ( ctx , "c:/path/to/build/game.dll" );
// call the update function at any frequency matters to you, this will give
// the real application a chance to run
while (! cr_plugin_update ( ctx )) {
// do anything you need to do on host side (ie. windowing and input stuff?)
}
// at the end do not forget to cleanup the plugin context
cr_plugin_close ( ctx );
return 0 ;
}بينما الضيف (التطبيق الحقيقي) سيكون مثل:
CR_EXPORT int cr_main ( struct cr_plugin * ctx , enum cr_op operation ) {
assert ( ctx );
switch ( operation ) {
case CR_LOAD : return on_load (...); // loading back from a reload
case CR_UNLOAD : return on_unload (...); // preparing to a new reload
case CR_CLOSE : ...; // the plugin will close and not reload anymore
}
// CR_STEP
return on_update (...);
}CR_INITIAL_FAILURE . إذا تعطل المكون الإضافي الأولي، فيجب على المضيف تحديد المسار التالي، ولن نقوم بإعادة تحميل المكون الإضافي المعطل. cr_plugin_load لصالح cr_plugin_open للتوافق مع cr_plugin_close . راجع العدد رقم 49.CR_BAD_IMAGE في حالة ما إذا كان الملف الثنائي لا يزال غير جاهز حتى لو تغير الطابع الزمني الخاص به. قد يحدث هذا إذا كان إنشاء الملف (المترجم أو النسخ) بطيئًا.CR_BAD_IMAGE ). الآن يتم تقليل الإصدار مرة واحدة في معالج التعطل ثم مرة أخرى أثناء الاستعادة ثم يتم صدمه مرة أخرى. لن يؤدي التراجع بسبب صورة غير مكتملة إلى التراجع عن نسختين بشكل غير صحيح، وسيستمر في نفس الإصدار في إعادة محاولة التحميل حتى تصبح الصورة صالحة (انتهى النسخ أو المترجم من الكتابة إليها). قد يؤثر هذا على الاستخدامات الحالية لـ cr إذا تم استخدام معلومات version أثناء CR_UNLOAD حيث ستكون الآن قيمة مختلفة. يمكن العثور على عينتين بسيطتين في دليل samples .
الأول هو تطبيق وحدة تحكم بسيط يوضح بعض الحالات الثابتة الأساسية التي تعمل بين المثيلات واختبارات التعامل مع الأعطال الأساسية. يتم استخدام الطباعة للإخراج لإظهار ما يحدث.
يوضح الجزء الثاني كيفية إعادة التحميل المباشر لتطبيق opengl باستخدام Dear ImGui. تعيش بعض الولايات في الجانب المضيف بينما يكون معظم الكود في جانب الضيف.
تستخدم العينات والاختبارات نظام بناء fips. يتطلب بايثون وCMake.
$ ./fips build # will generate and build all artifacts
$ ./fips run crTest # To run tests
$ ./fips run imgui_host # To run imgui sample
# open a new console, then modify imgui_guest.cpp
$ ./fips make imgui_guest # to build and force imgui sample live reload
int (*cr_main)(struct cr_plugin *ctx, enum cr_op operation)هذا هو مؤشر الوظيفة لوظيفة نقطة الإدخال الثنائية القابلة للتحميل الديناميكية.
الحجج
ctx إلى سياق سيتم تمريره من host إلى guest ويحتوي على معلومات قيمة حول الإصدار الحالي الذي تم تحميله وسبب الفشل وبيانات المستخدم. لمزيد من المعلومات، راجع cr_plugin .operation التي يتم تنفيذها، راجع cr_op .يعود
CR_USER . 0 أو قيمة موجبة سيتم تمريرها إلى العملية host . bool cr_plugin_open(cr_plugin &ctx, const char *fullpath)تحميل وتهيئة البرنامج المساعد.
الحجج
ctx هو السياق الذي سيدير البيانات الداخلية للمكون الإضافي وبيانات المستخدم.fullpath مع اسم الملف إلى الملف الثنائي القابل للتحميل للمكون الإضافي أو NULL .يعود
true في حالة النجاح، false فيما عدا ذلك. void cr_set_temporary_path(cr_plugin& ctx, const std::string &path) يضبط المسار المؤقت الذي سيتم وضع النسخ المؤقتة من البرنامج المساعد فيه. يجب أن يتم استدعاؤه مباشرة بعد cr_plugin_open() . إذا لم يتم تعيين المسار temporary ، فسيتم نسخ نسخ مؤقتة من الملف إلى نفس الدليل الذي يوجد به الملف الأصلي.
الحجج
ctx هو السياق الذي سيدير البيانات الداخلية للمكون الإضافي وبيانات المستخدم.path المسار الكامل إلى دليل موجود والذي سيتم استخدامه لتخزين نسخ المكونات الإضافية المؤقتة. int cr_plugin_update(cr_plugin &ctx, bool reloadCheck = true) ستستدعي هذه الوظيفة وظيفة البرنامج المساعد cr_main . يجب أن يتم استدعاؤه بشكل متكرر حسب احتياجات المنطق/التطبيق الأساسية.
الحجج
ctx بيانات سياق البرنامج المساعد الحالي.reloadCheck اختياري: قم بفحص القرص (stat()) لمعرفة ما إذا كانت المكتبة الديناميكية تحتاج إلى إعادة تحميل.يعود
cr_main . void cr_plugin_close(cr_plugin &ctx)تنظيف الحالات الداخلية بمجرد عدم الحاجة إلى البرنامج المساعد بعد الآن.
الحجج
ctx بيانات سياق البرنامج المساعد الحالي. cr_op يشير التعداد إلى نوع الخطوة التي يتم تنفيذها بواسطة host :
CR_LOAD يتم تنفيذ التحميل الناتج عن إعادة التحميل، ويمكن استخدامه لاستعادة أي حالة داخلية محفوظة.CR_STEP تحديث التطبيق، وهذه هي العملية العادية والأكثر تكرارًا؛CR_UNLOAD سيتم تنفيذ عملية إلغاء التحميل لإعادة تحميل المكون الإضافي، مما يمنح التطبيق فرصة واحدة لتخزين أي بيانات مطلوبة؛CR_CLOSE يستخدم عند إغلاق البرنامج المساعد، ويعمل مثل CR_UNLOAD ولكن لا ينبغي توقع CR_LOAD بعد ذلك؛ cr_pluginبنية سياق مثيل البرنامج المساعد.
p غير شفاف لبيانات cr الداخلية؛userdata المستخدم لتمرير المعلومات بين عمليات إعادة التحميل؛version لكل عملية إعادة تحميل ناجحة، بدءًا من 1 للتحميل الأول. سيتم تغيير الإصدار أثناء عملية معالجة العطل ؛failure الذي يستخدمه نظام الحماية من الأعطال، سيحتوي على رمز خطأ الفشل الأخير الذي تسبب في التراجع. راجع cr_failure لمزيد من المعلومات حول القيم المحتملة؛ cr_failureفي حالة حدوث عطل في الملف الثنائي القابل للتحميل، سيشير معالج التعطل إلى سبب التعطل باستخدام أحد الأسباب التالية:
CR_NONE لا يوجد خطأ؛CR_SEGFAULT خطأ في التقسيم. SIGSEGV على Linux/OSX أو EXCEPTION_ACCESS_VIOLATION على Windows؛CR_ILLEGAL في حالة التعليمات غير القانونية. SIGILL على Linux/OSX أو EXCEPTION_ILLEGAL_INSTRUCTION على Windows؛CR_ABORT Abort، SIGBRT على Linux/OSX، غير مستخدم على Windows؛CR_MISALIGN ، SIGBUS على Linux/OSX أو EXCEPTION_DATATYPE_MISALIGNMENT على Windows؛CR_BOUNDS هو EXCEPTION_ARRAY_BOUNDS_EXCEEDED ، لنظام التشغيل Windows فقط؛CR_STACKOVERFLOW هو EXCEPTION_STACK_OVERFLOW ، لنظام التشغيل Windows فقط؛CR_STATE_INVALIDATED فشل إدارة CR_STATE الثابت؛CR_BAD_IMAGE البرنامج المساعد ليس صورة صالحة (على سبيل المثال، ربما لا يزال المترجم يكتبها)؛CR_OTHER إشارة أخرى، Linux فقط؛CR_USER (للقيم السالبة التي يتم إرجاعها من cr_main )؛ CR_HOST يجب استخدام هذا التعريف قبل تضمين cr.h في host ، إذا لم يتم تعريف CR_HOST ، فسيعمل cr.h كملف رأس API عام لاستخدامه في تنفيذ guest .
اختياريًا، يمكن أيضًا تعريف CR_HOST بإحدى القيم التالية كطريقة لتكوين وضع التشغيل safety لإدارة الحالة الثابتة التلقائية ( CR_STATE ):
CR_SAFEST سوف يتحقق من صحة عنوان وحجم أقسام بيانات الحالة أثناء عمليات إعادة التحميل، إذا تغير أي شيء، فسيتم التراجع عن التحميل؛CR_SAFE سيتحقق فقط من حجم قسم الحالة، وهذا يعني أن عنوان الإحصائيات قد يتغير (ومن الأفضل تجنب الضغط على أي مؤشر للأشياء الثابتة)؛CR_UNSAFE لن يتحقق من صحة أي شيء سوى أن حجم القسم مناسب، وقد لا يكون دقيقًا بالضرورة (النمو مقبول ولكن الانكماش ليس كذلك)، هذا هو السلوك الافتراضي؛CR_DISABLE تعطيل الإدارة التلقائية للحالة الثابتة تمامًا؛ CR_STATE ماكرويُستخدم لوضع علامة على متغير ثابت عام أو محلي ليتم حفظه واستعادته أثناء إعادة التحميل.
الاستخدام
static bool CR_STATE bInitialized = false;
يمكنك تحديد وحدات الماكرو هذه قبل تضمين cr.h في المضيف (CR_HOST) لتخصيص عمليات تخصيص ذاكرة cr.h والسلوكيات الأخرى:
CR_MAIN_FUNC : يغير الرمز "cr_main" إلى اسم الوظيفة المعرفة من قبل المستخدم. الافتراضي: #define CR_MAIN_FUNC "cr_main"CR_ASSERT : تجاوز التأكيد. الافتراضي: #define CA_ASSERT(e) يؤكد(e)CR_REALLOC : تجاوز إعادة تخصيص libc. الافتراضي: #define CR_REALLOC(ptr, size) ::realloc(ptr, size)CR_MALLOC : تجاوز malloc الخاص بـ libc. الافتراضي: #define CR_MALLOC(الحجم) ::malloc(الحجم)CR_FREE : تجاوز libc المجاني. الافتراضي: #define CR_FREE(ptr) ::free(ptr)CR_DEBUG : إخراج رسائل تصحيح الأخطاء في CR_ERROR وCR_LOG وCR_TRACECR_ERROR : يسجل رسائل التصحيح إلى stderr. الافتراضي (CR_DEBUG فقط): #define CR_ERROR(...) fprintf(stderr, VA_ARGS )CR_LOG : يسجل رسائل تصحيح الأخطاء. الافتراضي (CR_DEBUG فقط): #define CR_LOG(...) fprintf(stdout, VA_ARGS )CR_TRACE : طباعة استدعاءات الوظائف. الافتراضي (CR_DEBUG فقط): #define CR_TRACE(...) fprintf(stdout, "CR_TRACE: %sn, FUNCTION )ج: اقرأ عن سبب قيامي بهذا هنا.
ج: تأكد من أن كلاً من مضيف التطبيق الخاص بك وملف dll الخاص بك يستخدمان وقت التشغيل الديناميكي (/MD أو /MDd) حيث يجب تحرير أي بيانات مخصصة في الكومة باستخدام نفس مثيل المخصص، من خلال مشاركة وقت التشغيل بين الضيف و المضيف، ستضمن استخدام نفس المُخصص.
ج: نعم. يجب أن يعمل هذا دون مشاكل على نظام التشغيل Windows. في أنظمة التشغيل Linux وOSX، قد تكون هناك مشكلات تتعلق بمعالجة الأعطال
إذا كان عليك تحميل ملف dll قبل cr لأي سبب من الأسباب، فقد يستمر Visual Studio في الاحتفاظ بقفل PDB. ربما تواجهك هذه المشكلة والحل هنا.
أولاً، تأكد من أن نظام البناء الخاص بك لا يتدخل من خلال الارتباط إلى حد ما بمكتبتك المشتركة. هناك الكثير من الأشياء التي يمكن أن تسوء وتحتاج إلى التأكد من أن cr فقط هو الذي سيتعامل مع مكتبتك المشتركة. على نظام التشغيل Linux، لمزيد من المعلومات حول كيفية العثور على ما يحدث، تحقق من هذه المشكلة.
cr هو أداة إعادة تحميل C والتعامل مع C يفترض أن الأشياء البسيطة ستعمل في الغالب.
المشكلة هي كيف سيقرر الرابط إعادة ترتيب الأشياء وفقًا لمقدار التغييرات التي تجريها في الكود. بالنسبة للتغييرات المتزايدة والمحلية، لم أواجه أية مشكلات مطلقًا، بشكل عام، لم أواجه أي مشكلات على الإطلاق عند كتابة كود C العادي. الآن، عندما تبدأ الأمور في أن تصبح أكثر تعقيدًا وتقترب من لغة C++، يصبح الأمر أكثر خطورة. إذا كنت بحاجة إلى القيام بأشياء معقدة، أقترح عليك التحقق من RCCPP وقراءة ملف PDF ومنشور مدونتي الأصلي حول cr هنا.
مع كل هذه المعلومات، ستتمكن من تحديد أيهما أفضل لحالة الاستخدام الخاصة بك.
cr لرعاية منفذ cr إلى MacOSX.
داني جرين
روكاس كوبستيس
نوح رينهارت
نيكلاس لوندبرج
سبهر تغديسيان
روبرت غابرييل جاكابوسكي
@pixelherodev
الكسندر
نحن نرحب بجميع المساهمات، وليس هناك أشياء بسيطة للمساهمة بها، حتى إصلاح الأخطاء المطبعية بحرف واحد مرحب به.
الشيء الوحيد الذي نطلبه هو إجراء اختبار شامل والحفاظ على نمط التعليمات البرمجية وتحديث الوثائق.
وكذلك القبول والموافقة على إطلاق أي مساهمة بموجب نفس الترخيص.
رخصة معهد ماساتشوستس للتكنولوجيا (MIT)
حقوق الطبع والنشر (ج) 2017 داني أنجيلو كارميناتي جرين
يُمنح الإذن مجانًا لأي شخص يحصل على نسخة من هذا البرنامج وملفات الوثائق المرتبطة به ("البرنامج")، للتعامل في البرنامج دون قيود، بما في ذلك، على سبيل المثال لا الحصر، حقوق الاستخدام والنسخ والتعديل والدمج. ونشر و/أو توزيع وترخيص من الباطن و/أو بيع نسخ من البرنامج، والسماح للأشخاص الذين تم توفير البرنامج لهم بالقيام بذلك، وفقًا للشروط التالية:
يجب تضمين إشعار حقوق الطبع والنشر أعلاه وإشعار الإذن هذا في جميع النسخ أو الأجزاء الكبيرة من البرنامج.
يتم توفير البرنامج "كما هو"، دون أي ضمان من أي نوع، صريحًا أو ضمنيًا، بما في ذلك، على سبيل المثال لا الحصر، ضمانات القابلية للتسويق والملاءمة لغرض معين وعدم الانتهاك. لا يتحمل المؤلفون أو أصحاب حقوق الطبع والنشر بأي حال من الأحوال المسؤولية عن أي مطالبة أو أضرار أو مسؤولية أخرى، سواء في إجراء العقد أو الضرر أو غير ذلك، الناشئة عن أو خارج أو فيما يتعلق بالبرنامج أو الاستخدام أو المعاملات الأخرى في برمجة.
* /
#ifndef __CR_H__
#define __CR_H__
//
// Global OS specific defines/customizations
//
#if defined( _WIN32 )
#define CR_WINDOWS
#define CR_PLUGIN ( name ) "" name ".dll"
#elif defined( __linux__ )
#define CR_LINUX
#define CR_PLUGIN ( name ) "lib" name ".so"
#elif defined( __APPLE__ )
#define CR_OSX
#define CR_PLUGIN ( name ) "lib" name ".dylib"
#else
#error "Unknown/unsupported platform, please open an issue if you think this
platform should be supported."
#endif // CR_WINDOWS || CR_LINUX || CR_OSX
//
// Global compiler specific defines/customizations
//
#if defined( _MSC_VER )
#if defined( __cplusplus )
#define CR_EXPORT extern "C" __declspec(dllexport)
#define CR_IMPORT extern "C" __declspec(dllimport)
#else
#define CR_EXPORT __declspec(dllexport)
#define CR_IMPORT __declspec(dllimport)
#endif
#endif // defined(_MSC_VER)
#if defined( __GNUC__ ) // clang & gcc
#if defined( __cplusplus )
#define CR_EXPORT extern "C" __attribute__((visibility("default")))
#else
#define CR_EXPORT __attribute__((visibility("default")))
#endif
#define CR_IMPORT
#endif // defined(__GNUC__)
#if defined( __MINGW32__ )
#undef CR_EXPORT
#if defined( __cplusplus )
#define CR_EXPORT extern "C" __declspec(dllexport)
#else
#define CR_EXPORT __declspec(dllexport)
#endif
#endif
// cr_mode defines how much we validate global state transfer between
// instances. The default is CR_UNSAFE, you can choose another mode by
// defining CR_HOST, ie.: #define CR_HOST CR_SAFEST
enum cr_mode {
CR_SAFEST = 0 , // validate address and size of the state section, if
// anything changes the load will rollback
CR_SAFE = 1 , // validate only the size of the state section, this means
// that address is assumed to be safe if avoided keeping
// references to global/static states
CR_UNSAFE = 2 , // don't validate anything but that the size of the section
// fits, may not be identical though
CR_DISABLE = 3 // completely disable the auto state transfer
};
// cr_op is passed into the guest process to indicate the current operation
// happening so the process can manage its internal data if it needs.
enum cr_op {
CR_LOAD = 0 ,
CR_STEP = 1 ,
CR_UNLOAD = 2 ,
CR_CLOSE = 3 ,
};
enum cr_failure {
CR_NONE , // No error
CR_SEGFAULT , // SIGSEGV / EXCEPTION_ACCESS_VIOLATION
CR_ILLEGAL , // illegal instruction (SIGILL) / EXCEPTION_ILLEGAL_INSTRUCTION
CR_ABORT , // abort (SIGBRT)
CR_MISALIGN , // bus error (SIGBUS) / EXCEPTION_DATATYPE_MISALIGNMENT
CR_BOUNDS , // EXCEPTION_ARRAY_BOUNDS_EXCEEDED
CR_STACKOVERFLOW , // EXCEPTION_STACK_OVERFLOW
CR_STATE_INVALIDATED , // one or more global data section changed and does
// not safely match basically a failure of
// cr_plugin_validate_sections
CR_BAD_IMAGE , // The binary is not valid - compiler is still writing it
CR_INITIAL_FAILURE , // Plugin version 1 crashed, cannot rollback
CR_OTHER , // Unknown or other signal,
CR_USER = 0x100 ,
};
struct cr_plugin ;
typedef int ( * cr_plugin_main_func )( struct cr_plugin * ctx , enum cr_op operation );
// public interface for the plugin context, this has some user facing
// variables that may be used to manage reload feedback.
// - userdata may be used by the user to pass information between reloads
// - version is the reload counter (after loading the first instance it will
// be 1, not 0)
// - failure is the (platform specific) last error code for any crash that may
// happen to cause a rollback reload used by the crash protection system
struct cr_plugin {
void * p ;
void * userdata ;
unsigned int version ;
enum cr_failure failure ;
unsigned int next_version ;
unsigned int last_working_version ;
};
#ifndef CR_HOST
// Guest specific compiler defines/customizations
#if defined( _MSC_VER )
#pragma section(".state", read, write)
#define CR_STATE __declspec(allocate(".state"))
#endif // defined(_MSC_VER)
#if defined( CR_OSX )
#define CR_STATE __attribute__((used, section("__DATA,__state")))
#else
#if defined( __GNUC__ ) // clang & gcc
#define CR_STATE __attribute__((section(".state")))
#endif // defined(__GNUC__)
#endif
#else // #ifndef CR_HOST
// Overridable macros
#ifndef CR_LOG
# ifdef CR_DEBUG
# include 
