فضاهای نام مدیریت شده

خلاصه

مقدمه

فضاهای نام مدیریت شده در Weave SDK استفاده می‌شود تا هم به توسعه‌دهندگان Weave SDK و هم برای یکپارچه‌سازان، راهنمایی‌های تبلیغاتی و زیرمتن را در مورد تعیین مجموعه‌های API خاص در SDK ارائه دهند، به طوری که بتوانند مسیر مهاجرت خود را در نسخه‌های Weave SDK برنامه‌ریزی و پیش‌بینی کنند و به طور بالقوه، چندین API Weave همزمان را برای یک ماژول معین مدیریت کنید.

تعیین

فضاهای نام مدیریت شده ممکن است به عنوان یکی از چهار نام مدیریت شوند:

توسعه

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

بعدی

هر فضای نامی که با نام Next مدیریت می‌شود، نشانه‌ای برای توسعه‌دهندگان و یکپارچه‌کننده‌ها است که APIهای موجود در آن، در حالی که توسعه فعال را تا حد زیادی تکمیل کرده‌اند، ممکن است همچنان در معرض تغییر باشند و برای اهداف ارزیابی اولیه پشتیبانی شوند. APIهایی که به این صورت تعیین شده اند نشان دهنده جبهه تکاملی بعدی در API Weave SDK هستند و در آینده نزدیک تا نزدیک به APIهای فعلی و پیش فرض در یک چرخه انتشار اصلی تبدیل خواهند شد.

سازگاری به عقب، هم از منظر پروتکل API و هم از منظر پروتکل بدون سیم، ممکن است وجود داشته باشد اما در APIهایی که به این ترتیب تعیین شده تضمین نمی شود.

تعیین فضای نام مدیریت شده Next به طور مؤثری به توسعه‌دهندگان و ادغام‌کننده‌ها این منظر را ارائه می‌دهد که Weave SDK به کجا هدایت می‌شود، با اشاره به آنچه که در نسخه‌های آینده به API پیش‌فرض فعلی تبدیل می‌شود.

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

فعلی

هر فضای نامی که با تعیین Current یا هر فضای نام مدیریت‌نشده‌ای مدیریت می‌شود (یعنی فاقد تعیین فضای نام مدیریت‌شده) نشان‌دهنده API فعلی، پیش‌فرض و رسمی پشتیبانی‌شده برای آن بخش یا ماژول Weave SDK است. در حالی که هنوز ممکن است پیشرفت‌های مداومی برای چنین APIهایی وجود داشته باشد، تغییرات تا حد زیادی افزایشی خواهد بود و سازگاری با API باید حفظ شود.

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

میراث

هر فضای نامی که با نام Legacy مدیریت می‌شود، به توسعه‌دهندگان و ادغام‌کنندگان نشان می‌دهد که APIهای موجود در آن منسوخ شده‌اند و جایگزین API جدید و فعلی می‌شوند. این APIها همان چیزی است که قبلاً API فعلی بود.

APIهای تعیین شده در نسخه بعدی Weave SDK به طور کامل ناپدید می شوند. در نتیجه، توسعه‌دهندگان و ادغام‌کنندگان باید برنامه‌هایی را برای مهاجرت به دور از این APIها ایجاد کنند، اگر قصد دارند با لبه‌های برتر نسخه‌های Weave SDK باقی بمانند.

چرخه حیات فضای نام مدیریت شده

شکل زیر چرخه حیات یک فضای نام مدیریت شده را هنگام انتقال از توسعه و به طور بالقوه به Legacy نشان می دهد: 

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

اگر از آن استفاده شود، چرخه حیات فضای نام مدیریت شده با تعیین توسعه شروع می شود.

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

اگر قرار است کد در کنار کد فعلی قرار گیرد و هنوز جایگزین کد فعلی نشود، نامگذاری باید به Next منتقل شود. اگر قرار است کد جایگزین کد فعلی شود، نامگذاری باید به Current منتقل شود.

با استفاده از نام بعدی، پس از اینکه کد تعداد مورد نظر از چرخه های انتشار و ارزیابی را طی کرد، تعیین به Current منتقل می شود یا دوباره، تعیین ممکن است به طور کلی حذف شود.

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

از نام Legacy، کد در نهایت از Weave SDK به طور کلی حذف می شود.

استفاده از فضاهای نام مدیریت شده

کاربران Weave SDK ممکن است با فضاهای نام مدیریت شده به عنوان توسعه دهنده ، توسعه دهنده و حفظ کد موجود، یا به عنوان یکپارچه ساز ، با Weave در برنامه، پلتفرم و کد سیستم خود تعامل داشته باشند. دو بخش زیر به جزئیات توصیه هایی برای برخورد با فضاهای نام مدیریت شده Weave از این دو منظر می پردازد.

استفاده از فضاهای نام مدیریت شده به عنوان یک توسعه دهنده

تمرکز اصلی توسعه‌دهنده Weave SDK، بهبود و توسعه API‌ها و عملکرد جدید Weave SDK است، در حالی که در بسیاری از موارد، همزمان از توسعه‌های API و عملکرد موجود پشتیبانی می‌کند.

در مواردی که برآوردن هر دوی این حوزه‌های تمرکز به روشی سازگار با عقب در یک API یکسان امکان‌پذیر نیست، فضاهای نام مدیریت شده مکانیزمی را برای مدیریت موازی این APIها ارائه می‌کنند، به گونه‌ای که API موجود و استقرار عملکرد را مختل نمی‌کند.

به عنوان مثال کاری، یک نمایه Weave، Mercury را فرض کنید که در حال حاضر تحت سلسله مراتب فضای نام مدیریت نشده زیر وجود دارد: 

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

// ...

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

و سرصفحه های عمومی زیر:

  • بافت / پروفایل / مرکوری / مرکوری.hpp
  • بافت / پروفایل / مرکوری / Bar.hpp
  • بافت / پروفایل / مرکوری / Foo.hpp
  • بافت / پروفایل / مرکوری / Foobar.hpp

جایی که Mercury.hpp سربرگ ماژول "چتر" است. بیشتر ادغام کننده ها به سادگی هدر ماژول "چتر" را همانطور که نشان داده شده است شامل می شوند: 

#include

با این حال، توسعه دهنده Mercury اکنون به نقطه ای رسیده است که در آن نیاز به توسعه نسل بعدی APIها و به طور بالقوه، پروتکل بدون سیم است که با استقرارهای موجود سازگار نیست. استفاده از فضاهای نام مدیریت شده می تواند به انجام این کار بدون شکستن این استقرارهای موجود کمک کند.

فضای نام موجود را به فعلی منتقل کنید

با هدف ادامه پشتیبانی از نسخه فعلی API و عملکرد برای ادغام‌های مستقر شده موجود، اولین کار انتقال کد فعلی است: 

% 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

اگر فقط یک فضای نام مدیریت شده تعیین شده توسط Current بدون ایجاد فضای نام مدیریت شده با توسعه یا بعدی ایجاد شود، محتوای این فایل ها می تواند به سادگی شامل یک هدر شامل محافظ و یک دستورالعمل شامل باشد که هدر جدید منتقل شده را مشخص می کند. همین نام: 

#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

یا هر چیزی که برای استفاده مدیریت فضای نام مناسب است.

محتوای توسعه ایجاد کنید

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

% 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

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

استفاده از فضاهای نام مدیریت شده به عنوان یکپارچه ساز

تمرکز اصلی ادغام‌کننده Weave SDK شامل هدرهای API عمومی Weave SDK و یکپارچه‌سازی و توسعه برنامه‌های کاربردی علیه آنها است.

به عنوان مثال کاری، دوباره یک نمایه Weave، Mercury را فرض کنید که دارای فضاهای نام مدیریت شده بعدی، فعلی، و قدیمی است که سربرگ های عمومی آن به صورت زیر ساخته شده است:

  • بافت / پروفایل / مرکوری / مرکوری.hpp
  • بافت / پروفایل / مرکوری / Bar.hpp
  • بافت / پروفایل / مرکوری / Foo.hpp
  • بافت / پروفایل / مرکوری / 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
  • بافت / پروفایل / مرکوری / جاری / مرکوری.hpp
  • بافت / پروفایل / مرکوری / جاری / Bar.hpp
  • بافت / پروفایل / مرکوری / فعلی / Foo.hpp
  • بافت / پروفایل / مرکوری / فعلی / Foobar.hpp
  • Weave/Profiles/Mercury/Legacy/Mercury.hpp
  • بافت/پروفایل/مرکوری/میراث/Bar.hpp
  • Weave/Profiles/Mercury/Legacy/Foo.hpp
  • Weave/Profiles/Mercury/Legacy/Foobar.hpp

جایی که Mercury.hpp سربرگ ماژول "چتر" است.

مگر اینکه مورد استفاده در دست انگیزه گنجاندن یک ماژول مدیریت فضای نام در Weave را به طور واضح ایجاد کند، به عنوان مثال: 

#include

بهتر است سرصفحه‌های عمومی ماژول Weave را با مسیرهای مدیریت نشده و پیش‌فرض (مانند Weave/Profiles/Mercury/Mercury.hpp) ارجاع دهید. انجام این کار امکان پیگیری پیشرفت توسعه API را بدون تغییر مداوم دستورالعمل‌های شامل پروژه فراهم می‌کند، زیرا آن APIها در چرخه حیات مدیریت شده جریان دارند.

به دنبال این استراتژی، استقرارها می توانند کد خود را در یک نام فضای نام مدیریت شده متفاوت، برای مثال تعیین فعلی، با تعیین پیکربندی مورد نظر در پیش پردازشگر C/C++، دوباره هدف گیری کنند. این ممکن است در خط فرمان، در کد منبع، یا در یک پیکربندی یا سربرگ پیشوند انجام شود: 

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current

و از مسیر شامل مدیریت نشده / ناموفق استفاده کنید: 

#include

وقتی، و اگر، تعیین فضای نام مدیریت شده برای APIهای مورد نظر تغییر کرد، به عنوان مثال از Current به Legacy، به سادگی با تنظیم تعریف پیش پردازنده، دوباره هدف گذاری کنید: 

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Legacy