مساحات الاسم المُدارة

ملخّص

مقدمة

تُستخدَم مساحات الاسم المُدارة في حزمة تطوير البرامج Weave لتزويد كل من مطوّري Weave SDK والمتكاملين على حد سواء بالإرشادات أو النصوص الفرعية المُعلَن عنها عند تحديد مجموعات معيّنة من واجهات برمجة التطبيقات ضمن حزمة SDK، ما يتيح لهم تخطيط مسار نقل البيانات وتوقُّعه من خلال إصدارات Weave SDK، وربما إدارة واجهات برمجة تطبيقات Weave متعددة والمتزامنة لوحدة معيّنة.

التصنيف

يمكن إدارة مساحات الاسم المُدارة باعتبارها أحد التصنيفات الأربعة:

تطوير

أي مساحة اسم تتم إدارتها من خلال تصنيف "التطوير" هي إشارة للمطورين والمدمجين إلى أن واجهات برمجة التطبيقات المضمَّنة في المنصة قيد التطوير النشط، وقد تكون عرضة للتغيير، وليست معتمدة رسميًا. بشكل عام، لا ننصح الشركات المتكاملة باستخدام واجهات برمجة التطبيقات هذه ما لم يتم توجيهها على وجه التحديد.

التالي

إنّ أي مساحة اسم تتم إدارتها من خلال تصنيف "التالي" هي إشارة للمطورين والمدمجين إلى أنّ واجهات برمجة التطبيقات المضمَّنة فيها قد تكون عرضة للتغيير، على الرغم من اكتمال عمليات التطوير النشطة إلى حد كبير، ويتم دعمها لأغراض التقييم المبكر. تمثّل واجهات برمجة التطبيقات المصممة على النحو المطلوب واجهة برمجة التطبيقات التطوّعية التالية في واجهة برمجة تطبيقات Weave SDK، وستصبح واجهات برمجة التطبيقات التلقائية الحالية في دورة المصادر الرئيسية في المستقبل القريب.

قد يتوفّر توافق مع الأنظمة القديمة، سواء من منظور واجهة برمجة التطبيقات أو بروتوكول الاتصال السلكي، ولكنّه غير مضمون في واجهات برمجة التطبيقات المحدّدة لذلك.

إنّ تحديد مساحة الاسم المُدارة من خلال Next يتيح للمطوّرين والمتكاملين إمكانية الاطّلاع على مسار حزمة تطوير البرامج Weave من خلال الإشارة إلى الميزات التي ستصبح واجهة برمجة التطبيقات التلقائية الحالية في أي إصدار مستقبلي.

إنّ تحديد مساحة الاسم المُدارة التالية اختياري، إذ قد تنتقل مساحة الاسم المُدارة خلال دورة حياة بدون استخدامها (يُرجى الاطّلاع على دورة حياة مساحة الاسم المُدارة).

ملف

تمثّل أي مساحة اسم مُدارة باستخدام التصنيف الحالي أو أي مساحة اسم غير مُدارة (أي عدم تحديد مساحة الاسم المُدارة) واجهة برمجة التطبيقات الحالية والتلقائية والرسمية المتوافقة لذلك الجزء أو الوحدة من حزمة تطوير البرامج Weave. على الرغم من احتمال توفُّر تحسينات مستمرة على واجهات برمجة التطبيقات هذه، إلا أنّ التغييرات ستكون على مستوى كبير من التوافق مع الأنظمة القديمة والتوافق مع الأنظمة القديمة، ويجب الحفاظ على كل من واجهة برمجة التطبيقات وعبر الأسلاك.

إنّ التصنيف الحالي لمساحة الاسم المُدارة اختياري، وبالتالي قد تنتقل مساحة الاسم المُدارة خلال دورة حياة بدون استخدامها (يُرجى الاطّلاع على دورة حياة مساحة الاسم المُدارة). في الواقع، أي مساحة اسم غير مُدارة هي مساحة اسم حديثة ضمنيًا.

قديمة

أي مساحة اسم تتم إدارتها من خلال التصنيف "قديم" هي إشارة للمطوّرين وجهات الدمج بأنّ واجهات برمجة التطبيقات المضمّنة تم إيقافها نهائيًا واستبدلتها بواجهة برمجة تطبيقات حالية جديدة. تمثّل واجهات برمجة التطبيقات هذه ما كان يُعرف سابقًا باسم واجهة برمجة التطبيقات الحالية.

ستختفي واجهات برمجة التطبيقات المحددة تمامًا في الإصدار الرئيسي التالي من حزمة تطوير البرامج Weave. وبالتالي، على المطوّرين والمعنيين بالتكامل وضع خطط بشأن الانتقال من واجهات برمجة التطبيقات هذه إذا كانوا ينوون استخدام أحدث إصدارات Weave SDK.

مراحل نشاط مساحة الاسم المُدارة

يوضِّح الشكل التالي دورة حياة مساحة الاسم المُدارة أثناء انتقالها من مساحة التطوير، وربما إلى النطاق القديم:

.-------------.      .- - - .      .- - - - -.      .--------.
| Development | -.->   Next   -.->   Current   ---> | Legacy |
'-------------'  |   '- - - '  |   ' - - - - '      '--------'
                 |             |
                 '-------------'

وإذا تم استخدامه، تبدأ دورة حياة مساحة الاسم المُدارة بتعيين التطوير.

عندما تكتمل عملية التطوير وتكون التعليمة البرمجية جاهزة للتقييم والتكامل، يتم نقل التصنيف إلى التالي أو الحالي. وبدلاً من ذلك، يمكن أن يتم إسقاط التصنيف تمامًا وإيقاف مساحة الاسم المُدارة مرة أخرى، ما يؤدي فعليًا إلى أن يكون التصنيف محدثًا بشكل ضمني.

إذا كانت التعليمة البرمجية يجب أن تتواجد إلى جانب التعليمة البرمجية الحالية ولم تحل محل الرمز الحالي بعد، فسيتم نقل التصنيف إلى "التالي". إذا كانت التعليمة البرمجية ستحل محل التعليمة البرمجية الحالية، فيجب ترحيل التصنيف إلى الوضع الحالي.

باستخدام التصنيف التالي، بعد أن يخضع الرمز البرمجي لعدد دورات الإصدار والتقييم المطلوب، يتم نقل التصنيف إلى الوضع الحالي، أو مرة أخرى، قد يتم إسقاط التصنيف تمامًا.

عند استخدام التصنيف الحالي، إذا كان الرمز الجديد سيحل محله الرمز البرمجي الجديد ولكن لا يزال يتطلّب الاحتفاظ به لعدد من دورات الإصدار، سيتم نقل التصنيف إلى "قديم".

من التصنيف Legacy، تتم إزالة التعليمة البرمجية في النهاية من Weave SDK تمامًا.

استخدام مساحات الأسماء المُدارة

يمكن لمستخدمي Weave SDK التفاعل مع مساحات الاسم المُدارة إما بصفتك مطوّرًا أو توسيعًا للرمز البرمجي الحالي أو صيانته أو كشركة دمج تعمل على دمج Weave في التطبيق والنظام الأساسي ورمز النظام. يوضح القسمان التاليان بالتفصيل توصيات للتعامل مع مساحات الاسم المُدارة في Weave من هذين المنظورين.

استخدام "مساحات الأسماء المُدارة" بصفتك مطوِّرًا

يركّز مطوّر حزمة Weave SDK بشكل رئيسي على تحسين وتطوير واجهات برمجة تطبيقات Weave SDK ووظائفها الجديدة، بالإضافة إلى دعم عمليات نشر الوظائف وواجهة برمجة التطبيقات الحالية في الوقت نفسه.

وفي حال تعذّر تلبية هذَين الموضوعَين بطريقة متوافقة مع الأنظمة القديمة ضمن واجهة برمجة التطبيقات نفسها، توفّر مساحات الاسم المُدارة آلية لإدارة واجهات برمجة التطبيقات هذه بالتوازي، بطريقة لا تؤدي إلى إيقاف عمليات نشر الوظائف وواجهة برمجة التطبيقات الحالية.

كمثال عملي، افترض أن ملف Weave الشخصي، Mercury، الذي يوجد حاليًا ضمن التسلسل الهرمي التالي وغير المُدار لمساحة الاسم:

namespace nl {
namespace Weave {
namespace Profiles {
namespace Mercury {

// ...

}; // namespace Mercury
}; // namespace Profiles
}; // namespace Weave
}; // namespace nl

والعناوين العامة التالية:

  • Weave/Profiles/Mercury/Mercury.hpp
  • Weave/Profiles/Mercury/Bar.hpp
  • Weave/Profiles/Mercury/Foo.hpp
  • Weave/Profiles/Mercury/Foobar.hpp

الذي يمثل فيه Mercury.hpp وحدة "مظلة" . تضمّن معظم الشركات الناشئة وحدة "المظلة" ببساطة كما هو موضح:

#include

مع ذلك، وصل تطوّر عطارد إلى مرحلة أصبحت فيها الحاجة إلى تطوير جيل جديد من واجهات برمجة التطبيقات، وربما بروتوكول عبر الشبكة اللاسلكية غير متوافق مع الإصدارات القديمة مع عمليات النشر الحالية. ويمكن أن يساعد استخدام مساحات الاسم المُدارة في تحقيق ذلك بدون تعطيل عمليات النشر الحالية هذه.

نقل مساحة الاسم الحالية إلى المساحة الحالية

بهدف مواصلة دعم الإصدار الحالي من واجهة برمجة التطبيقات والوظائف الخاصة بعمليات الدمج المنشورة حاليًا، تتمثل المهمة الأولى في نقل الرمز الحالي:

% cd src/lib/profiles/mercury
% mkdir Current
% mv Mercury.hpp Bar.hpp Foo.hpp Foobar.hpp *.cpp Current/

ملاحظة: بالإضافة إلى نقل الملفات، يجب أيضًا إعادة تسمية العنوان الذي يتضمن عناصر حماية للملفات المنقولة، ما قد يؤدي إلى إضافة " _CURRENT" إلى الملفات، لأنّه سيتم إنشاء مكان للملفات الجديدة التي تحمل أسماء متشابهة أدناه.

بعد نقل الرمز، تكون الخطوة التالية هي إدارة مساحة الاسم ذات التصنيف المناسب، هنا 'Current' (الحالي). أولاً، أنشئ عنوانًا يحدد مساحة الاسم المُدارة، على النحو التالي: "Current/MercuryManagedNamespace.hpp". ومن تفضيل إنشاء مثل هذا العنوان تكرار هذا المحتوى وتكراره في كل ملف عنوان عند وجود ملفات عناوين متعددة.

% cat << EOF > Current/MercuryManagedNamespace.hpp
#ifndef _WEAVE_MERCURY_MANAGEDNAMESPACE_CURRENT_HPP
#define _WEAVE_MERCURY_MANAGEDNAMESPACE_CURRENT_HPP

#include <Weave/Support/ManagedNamespace.hpp>

#if defined(WEAVE_CONFIG_MERCURY_NAMESPACE) && WEAVE_CONFIG_MERCURY_NAMESPACE != kWeaveManagedNamespace_Current
#error Compiling Weave Mercury current-designation managed namespace file with WEAVE_CONFIG_MERCURY_NAMESPACE defined != kWeaveManagedNamespace_Current
#endif

#ifndef WEAVE_CONFIG_MERCURY_NAMESPACE
#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current
#endif

namespace nl {
namespace Weave {
namespace Profiles {

namespace WeaveMakeManagedNamespaceIdentifier(Mercury, kWeaveManagedNamespaceDesignation_Current) { };

namespace Mercury = WeaveMakeManagedNamespaceIdentifier(Mercury, kWeaveManagedNamespaceDesignation_Current);

}; // namespace Profiles
}; // namespace Weave
}; // namespace nl

#endif // _WEAVE_MERCURY_MANAGEDNAMESPACE_CURRENT_HPP
EOF

بعد ذلك، قم بتضمين هذا الرأس قبل توجيهات التضمين الأخرى الخاصة بالوحدة في الرؤوس الحالية. على سبيل المثال:

#include 

#include

إنشاء عناوين التوافق

ومع ذلك، لا يكفي نقل الرؤوس الحالية إلى موقع جديد وإدارة مساحة الاسم وحدها لضمان عمل عمليات النشر الحالية بدون أي تغيير، حيث إنها جميعًا تستخدم توجيهات تتضمن توجيهات تحدد العناوين التي تم نقلها للتو.

ولحل هذه المشكلة، يجب إنشاء رؤوس برامج تضمين التوافق مع الأسماء المطابقة لتلك التي تم نقلها للتو.

% touch Mercury.hpp Bar.hpp Foo.hpp Foobar.hpp

إذا تم إنشاء مساحة اسم مُدارة محددة حاليًا بدون إنشاء مساحة اسم مُدارة منها "تطوير" أو "تم تعيين مساحة اسم مُدارة" مصاحبة لها، فيمكن أن تتكون محتويات هذه الملفات ببساطة من عنوان يتضمن حماية وتوجيه تضمين يحدد العنوان الذي تم نقله حديثًا والذي يحمل الاسم نفسه:

#ifndef _WEAVE_MERCURY_BAR_HPP
#define _WEAVE_MERCURY_BAR_HPP

#include 

#endif // _WEAVE_MERCURY_BAR_HPP

ومع ذلك، إذا كان يتم إنشاء مساحة الاسم المُدارة التي تم تحديدها من خلال "تطوير" أو "التالي" أيضًا لاستيعاب تطوير جديد وغير متوافق، سيكون هناك شيء أكثر تعقيدًا إلى حدٍ ما.

وكما في السابق، يتم إنشاء عنوان لتهيئة مساحة الاسم المُدارة، هنا باسم MercuryManagedNamespace.hpp. مرة أخرى، يُفضَّل تكرار هذا المحتوى وتكراره في كل ملف عنوان عند توفّر ملفات عناوين متعددة.

% cat << EOF > MercuryManagedNamespace.hpp
#ifndef _WEAVE_MERCURY_MANAGEDNAMESPACE_HPP
#define _WEAVE_MERCURY_MANAGEDNAMESPACE_HPP

#include <Weave/Support/ManagedNamespace.hpp>

#if defined(WEAVE_CONFIG_MERCURY_NAMESPACE)                             \
  && (WEAVE_CONFIG_MERCURY_NAMESPACE != kWeaveManagedNamespace_Current) \
  && (WEAVE_CONFIG_MERCURY_NAMESPACE != kWeaveManagedNamespace_Development)
#error "WEAVE_CONFIG_MERCURY_NAMESPACE defined, but not as namespace kWeaveManagedNamespace_Current or kWeaveManagedNamespace_Development"
#endif

#if !defined(WEAVE_CONFIG_MERCURY_NAMESPACE)
#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current
#endif

#endif // _WEAVE_MERCURY_MANAGEDNAMESPACE_HPP
EOF

لاحظ أن هذا الإعداد الافتراضي، كما هو مطلوب، هو تعيين مساحة الاسم المُدارة إلى 'Current' في حالة عدم تحديد أي تهيئة.

باستخدام هذا العنوان، يمكن الآن تعديل رؤوس برامج تضمين التوافق لتتضمّن ما يلي:

#include 

#if WEAVE_CONFIG_MERCURY_NAMESPACE == kWeaveManagedNamespace_Development
#include 
#else
#include 
#endif // WEAVE_CONFIG_MERCURY_NAMESPACE == kWeaveManagedNamespace_Development

أو أي شيء مناسب لحالة استخدام إدارة مساحة الاسم القائمة.

إنشاء محتوى التطوير

في هذه المرحلة، تتوفر البنية الأساسية الآن لبدء إنشاء وظائف وواجهات برمجة تطبيقات جديدة إلى جانب الوظائف الحالية.

% mkdir Development
% touch Development/Mercury.hpp Development/Bar.hpp Development/Foo.hpp Development/Foobar.hpp
% cat << EOF > Development/MercuryManagedNamespace.hpp
#ifndef _WEAVE_MERCURY_MANAGEDNAMESPACE_DEVELOPMENT_HPP
#define _WEAVE_MERCURY_MANAGEDNAMESPACE_DEVELOPMENT_HPP

#include <Weave/Support/ManagedNamespace.hpp>

#if defined(WEAVE_CONFIG_MERCURY_NAMESPACE) && WEAVE_CONFIG_MERCURY_NAMESPACE != kWeaveManagedNamespace_Development
#error Compiling Weave Mercury development-designated managed namespace file with WEAVE_CONFIG_MERCURY_NAMESPACE defined != kWeaveManagedNamespace_Development
#endif

#ifndef WEAVE_CONFIG_MERCURY_NAMESPACE
#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Development
#endif

namespace nl {
namespace Weave {
namespace Profiles {

namespace WeaveMakeManagedNamespaceIdentifier(Mercury, kWeaveManagedNamespaceDesignation_Development) { };

namespace Mercury = WeaveMakeManagedNamespaceIdentifier(Mercury, kWeaveManagedNamespaceDesignation_Development);

}; // namespace Profiles
}; // namespace Weave
}; // namespace nl

#endif // _WEAVE_MERCURY_MANAGEDNAMESPACE_DEVELOPMENT_HPP
EOF

وبالطبع، إذا كانت الوحدة أبسط بكثير من المثال الوارد هنا ولا تحتوي على العديد من الفئات أو المصادر أو الملفات أو الرؤوس، فيمكن تنفيذ ذلك كله في ملف الرأس نفسه بدون نقل الملفات وإنشاء عدة عناوين تهيئة مستقلة وتوافُق. مع ذلك، في هذا المثال المعقد، من المفترض أن تكون أفكارًا ملهمة بحلول مساحات الاسم المُدارة ضمن نطاق من المعقد إلى البسيط.

استخدام "مساحات الأسماء المُدارة" كعملية دمج

يتمثل التركيز الرئيسي في عملية دمج حزمة تطوير البرامج (SDK) في Weave في تضمين عناوين واجهة برمجة التطبيقات العامة لتطبيق Weave SDK المناسبة ودمج التطبيقات وتطويرها.

كمثال عملي، افترض مرة أخرى أن ملف Weave الشخصي، Mercury، الذي يحتوي على مساحات الاسم المُدارة التالية، والحالية، والقديمة، والتي يتم تنظيم عناوينها العامة على النحو التالي:

  • Weave/Profiles/Mercury/Mercury.hpp
  • Weave/Profiles/Mercury/Bar.hpp
  • Weave/Profiles/Mercury/Foo.hpp
  • Weave/Profiles/Mercury/Foobar.hpp
  • Weave/Profiles/Mercury/Next/Mercury.hpp
  • Weave/Profiles/Mercury/Next/Bar.hpp
  • Weave/Profiles/Mercury/Next/Foo.hpp
  • Weave/Profiles/Mercury/Next/Foobar.hpp
  • Weave/Profiles/Mercury/Current/Mercury.hpp
  • Weave/Profiles/Mercury/Current/Bar.hpp
  • Weave/Profiles/Mercury/Current/Foo.hpp
  • Weave/Profiles/Mercury/Current/Foobar.hpp
  • Weave/Profiles/Mercury/Legacy/Mercury.hpp
  • Weave/Profiles/Mercury/Legacy/Bar.hpp
  • Weave/Profiles/Mercury/Legacy/Foo.hpp
  • Weave/Profiles/Mercury/Legacy/Foobar.hpp

الذي يمثل فيه Mercury.hpp وحدة "مظلة" .

ما لم تحفز حالة الاستخدام المطروحة على تضمين وحدة مساحة اسم مُدارة داخل Weave بشكل صريح، على سبيل المثال:

#include

من الأفضل الإشارة إلى العناوين العامة لوحدة Weave من خلال مساراتها الافتراضية غير المُدارة (مثل Weave/Profiles/Mercury/Mercury.hpp). ويتيح ذلك متابعة عملية تطوير واجهة برمجة التطبيقات بدون تغيير توجيهات المشاريع باستمرار، بينما تتدفق واجهات برمجة التطبيقات خلال دورة الحياة المُدارة.

باتّباع هذه الاستراتيجية، يمكن لعمليات النشر بعد ذلك إعادة توجيه الرمز البرمجي الخاص بها إلى تخصيص مساحة اسم مُدارة مختلفة، وهو التصنيف الحالي، على سبيل المثال، من خلال تحديد الضبط المطلوب في المعالج المسبق C/C++. ويمكن إجراء ذلك في سطر الأوامر أو في رمز المصدر أو في إعدادات أو عنوان بادئة:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current

واستخدام مسار التضمين غير المُدار / غير المؤهل:

#include

متى وإذا تم تغيير تخصيص مساحة الاسم المُدارة لواجهات برمجة التطبيقات المستهدفة، على سبيل المثال من القائمة الحالية إلى القديمة، ما عليك سوى إعادة الاستهداف عن طريق ضبط تعريف المعالج المسبق:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Legacy