מרחבי שמות מנוהלים

סיכום

מבוא

מרחבי שמות מנוהלים משמשים ב-Weave SDK כדי לספק למפתחים ולמשלבים של Weave SDK גם הנחיות שפורסמו וגם טקסט משנה בנוגע להקצאה של קבוצות API מסוימות בתוך ה-SDK. כך הם יוכלו לתכנן ולחזות את נתיב ההעברה שלהם בגרסאות של Weave SDK, ואולי גם לנהל ממשקי API מרובים בו-זמנית ב-Weave SDK עבור מודול נתון.

ייעוד

ניתן לנהל מרחבי שמות מנוהלים אחת מארבע אפשרויות:

• Development
• הבא
• עכשיו
• דור קודם

פיתוח

כל מרחב שמות שמנוהל עם ייעוד 'פיתוח' מהווה אינדיקציה למפתחים ולמשלבים שממשקי ה-API שנכללים בהם נמצאים בפיתוח פעיל, עשויים להשתנות ואינם נתמכים באופן רשמי. בדרך כלל, למשלבים מומלץ לא להשתמש בממשקי ה-API האלה, אלא אם הם מחויבים לעשות זאת באופן ספציפי.

הבא

כל מרחב שמות שמנוהל עם הסיווג Next מהווה אינדיקציה למפתחים ולמשלבים שממשקי ה-API שכלולים בהם, למרות שברובם הם השלימו את הפיתוח הפעיל שלהם, הם עדיין עשויים להשתנות, ויש תמיכה בהם למטרות הערכה מוקדמת. ממשקי ה-API שייעדו לכך מייצגים את החזית האבולוציה הבאה ב-Weave SDK API, ויהפכו לממשקי ה-API הקיימים שמוגדרים כברירת מחדל במחזוריות משמעותיים בעתיד הקרוב.

יכול להיות שתהיה תאימות לאחור, גם בממשק ה-API וגם מנקודת המבט של פרוטוקול בחיבור אלחוטי, אבל היא לא מובטחת בממשקי ה-API שצוינו.

ההקצאה של מרחב שמות מנוהל Next מספקת למפתחים ולמשלבים יכולים לראות את היעדים הבאים של Weave SDK, על ידי רמז מה יהפוך ל-API הנוכחי המוגדר כברירת מחדל בגרסאות עתידיות.

ההקצאה של מרחב השמות המנוהל הבא היא אופציונלית, כך שמרחב שמות מנוהל עשוי לעבור במחזור החיים בלי להשתמש בו (מידע נוסף זמין במאמר מחזור חיים של מרחב שמות מנוהל).

היחס הנוכחי

כל מרחב שמות שמנוהל עם הסיווג הנוכחי או כל מרחב שמות לא מנוהל (כלומר, אם אין הקצאה של מרחב שמות מנוהל), מייצג את ה-API הרשמי הנתמך הנוכחי שמוגדר כברירת מחדל לחלק או למודול הזה של Weave SDK. ייתכן שיהיו שיפורים מתמשכים לממשקי API כאלה, אבל רובם יהיו שינויים מצטברים בתאימות לאחור, וצריך לשמר גם את ה-API וגם את השידור החי.

ההקצאה של מרחב השמות המנוהל הנוכחי היא אופציונלית, כך שמרחב שמות מנוהל עשוי לעבור במחזור החיים מבלי להשתמש בו (מידע נוסף זמין במאמר מחזור חיים של מרחב שמות מנוהל). למעשה, כל מרחב שמות לא מנוהל הוא 'נוכחי' באופן לא מפורש.

הדור הקודם

כל מרחב שמות שמנוהל עם הסיווג 'דור קודם' מהווה אינדיקציה למפתחים ולמשלבים שממשקי ה-API שנכללים בהם הוצאו משימוש ומוחלפים באמצעות ממשק API חדש ועדכני. ממשקי ה-API האלה מייצגים את מה שהיה בעבר ה-API הנוכחי.

ממשקי API שיושמו ייעלמו לגמרי בגרסה הגדולה הבאה של Weave SDK. כתוצאה מכך, מפתחים ומשלבים צריכים לתכנן מעבר מממשקי ה-API האלה אם הם מתכוונים להמשיך לפתח את מהדורות Weave SDK.

מחזור החיים של מרחב שמות מנוהל

האיור הבא ממחיש את מחזור החיים של מרחב שמות מנוהל במעבר מפיתוח, ואולי גם מדור קודם:

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

אם משתמשים במרחב השמות המנוהל, מחזור החיים של מרחב השמות המנוהל מתחיל בהגדרה של 'פיתוח'.

לאחר השלמת הפיתוח והקוד מוכן להערכה ולשילוב, הסיווג עובר לסטטוס 'הבא' או 'נוכחי'. לחלופין, ייתכן שההקצאה תוסר לחלוטין ולא ייעשה עוד שימוש במרחב השמות המנוהל, מה שהופך את הסיווג הנוכחי באופן מרומז באופן לא מפורש.

אם הקוד קיים לצד הקוד הנוכחי, ועדיין לא מחליף את הקוד הנוכחי, הסיווג צריך לעבור אל 'הבא'. אם הקוד הוא מחליף את הקוד הנוכחי, הסיווג צריך לעבור ל-Current (נוכחי).

באמצעות ההקצאה הבאה, לאחר שהקוד עבר את המספר הרצוי של מחזורי הפצה והערכה, ההקצאה תעבור לסטטוס 'נוכחי', או שוב, האישור עלול להישלל לחלוטין.

לפי הסיווג הנוכחי, אם הקוד יוחלף בקוד חדש אבל עדיין צריך לתחזק אותו במשך מספר מחזורי גרסאות, הסיווג עובר לגרסה הקודמת.

מההקצאה של הגרסה הקודמת, הקוד יוסר בסופו של דבר מ-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

ואת הכותרות הציבוריות הבאות:

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

כאשר Mercury.cpp הוא הכותרת "מטרייה" של המודול. רוב המשלבים פשוט כוללים את הכותרת "מטרייה" של המודול כפי שמוצג:

#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.cpp'. עדיף ליצור כותרת כזו ולחזור על התוכן הזה בכל קובץ כותרת כשיש בו מספר קובצי כותרת.

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

#include 

#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 

יצירת כותרות תאימות

עם זאת, העברת הכותרות הקיימות למיקום חדש וניהול מרחב השמות שלהן בלבד כדי להבטיח שהפריסות הקיימות יפעלו ללא שינוי, מפני שכולן משתמשות בהנחיות הכללה שציינו את הכותרות שהועברו למעלה.

כדי לפתור את הבעיה, צריך ליצור כותרות wrapper של תאימות עם שמות שתואמים לאלו שהועברו הרגע.

% 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

עם זאת, אם נוצר גם מרחב שמות מנוהל ייעודי לפיתוח או ל-Next כדי לתמוך בפיתוח חדש שאינו תואם, יש צורך לבצע פעולה קצת יותר מורכבת.

כמו בעבר, נוצרת כותרת לתצורה המנוהלת של מרחב השמות המנוהל, כאן בשם MercuryManagedNamespace.epp. שוב, עדיף לחזור על התוכן הזה ולשכפל אותו בכל קובץ כותרת כאשר יש מספר קובצי כותרת.

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

#include 

#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

הערה: אם לא הוגדרה תצורה, ברירת המחדל של מרחב השמות המנוהל היא 'נוכחי'.

עכשיו אפשר לערוך את כותרות wrapper של תאימות כך שיכללו את:

#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 

#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 נקרא 'מרקורי'. הפרופיל הזה מכיל מרחבי שמות מנוהלים שמיועדים 'הבא', 'נוכחי' ו'מדור קודם', שהכותרות הציבוריות שלהם בנויות כך:

• 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.cpp הוא הכותרת "מטרייה" של המודול.

אלא אם התרחיש לדוגמה מעודד את ההוספה של מודול מנוהל של מרחב שמות בתוך Weave באופן מפורש, לדוגמה:

#include 

מומלץ להפנות לכותרות ציבוריות של מודול Weave לפי נתיבי ברירת המחדל שאינם מנוהלים (למשל, Weave/Profiles/Mercury/Mercury.cpp). כך תוכלו לעקוב אחר ההתקדמות של פיתוח ה-API בלי לשנות כל הזמן את הוראות ההכללה של הפרויקט בזמן שממשקי ה-API האלה זורמים דרך lifecycle המנוהל.

בהמשך לאסטרטגיה הזו, יוכלו פריסות לטרגט מחדש את הקוד שלהן לפי הקצאה של מרחב שמות מנוהל שונה, הסיווג 'נוכח' (למשל, על ידי ציון ההגדרה הרצויה במעבד מראש של C/C++ ). ניתן לעשות זאת בשורת הפקודה, בקוד המקור או בכותרת תצורה או קידומת:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current

ומשתמשים בנתיב include [לא מנוהל'/'לא כשיר']:

#include 

אם, אם, אם הסיווג של מרחב השמות המנוהל משתנה לממשקי ה-API המטורגטים, למשל מ-Current קיים ל'דור קודם', צריך לבצע טירגוט מחדש על ידי שינוי ההגדרה של מעבד המידע מראש:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Legacy