Namespace Terkelola

Ringkasan

Pengantar

Namespace terkelola digunakan di Weave SDK untuk menyediakan developer dan integrator Weave SDK yang sama dengan panduan dan subteks yang diiklankan tentang penetapan set API tertentu dalam SDK sehingga mereka dapat merencanakan dan memprediksi jalur migrasi di seluruh rilis Weave SDK dan, berpotensi, mengelola beberapa Weave API serentak untuk modul tertentu.

Jabatan

Namespace terkelola dapat dikelola sebagai salah satu dari empat penetapan:

Pengembangan

Setiap namespace yang dikelola dengan penetapan Pengembangan merupakan indikasi bagi developer dan integrator bahwa API yang ada di dalamnya sedang dalam pengembangan aktif, mungkin dapat berubah, dan tidak didukung secara resmi. Integrator umumnya tidak disarankan untuk menggunakan API ini kecuali diarahkan secara khusus untuk melakukannya.

Berikutnya

Setiap namespace yang dikelola dengan penetapan Next merupakan indikasi bagi developer dan integrator bahwa API yang ada di dalamnya, meskipun sebagian besar telah menyelesaikan pengembangan aktif, mungkin masih dapat berubah dan didukung untuk tujuan evaluasi awal. API yang ditetapkan mewakili front evolusi berikutnya dalam Weave SDK API dan akan menjadi API default saat ini pada siklus rel utama dalam waktu dekat hingga di masa mendatang.

Kompatibilitas mundur, baik dari perspektif API maupun protokol over-the-wire, mungkin ada, tetapi tidak dijamin dalam API yang ditentukan.

Penetapan namespace terkelola Next secara efektif memberi developer dan integrator kemampuan untuk mengarahkan Weave SDK dengan menunjukkan apa yang akan menjadi API default saat ini dalam rilis mendatang.

Penetapan namespace terkelola Next bersifat opsional sehingga namespace terkelola dapat bertransisi melalui siklus proses tanpa menggunakannya (lihat Siklus Proses Namespace Terkelola).

Saat ini

Setiap namespace yang dikelola dengan penetapan Saat ini atau namespace yang tidak dikelola (yaitu yang tidak memiliki penetapan namespace terkelola) mewakili API resmi yang didukung saat ini untuk bagian atau modul Weave SDK tersebut. Meskipun mungkin masih ada peningkatan berkelanjutan pada API tersebut, perubahan sebagian besar akan berupa kompatibilitas inkremental dan mundur, baik API maupun over the wire, harus dipertahankan.

Penetapan namespace terkelola saat ini bersifat opsional sehingga namespace terkelola dapat bertransisi melalui siklus proses tanpa menggunakannya (lihat Siklus Proses Namespace Terkelola). Bahkan, namespace yang tidak dikelola memiliki status Terkini secara implisit.

Lama

Setiap namespace yang dikelola dengan penetapan Lama merupakan indikasi bagi developer dan integrator bahwa API yang ada di dalamnya sudah tidak digunakan lagi dan diganti dengan API baru yang sudah ada. API ini mewakili API yang sebelumnya disebut API saat ini.

API yang ditentukan akan dihapus sama sekali pada rilis utama Weave SDK berikutnya; akibatnya, developer dan integrator harus membuat rencana migrasi dari API ini jika mereka ingin tetap menggunakan rilis terdepan Weave SDK.

Siklus Proses Namespace Terkelola

Gambar berikut mengilustrasikan siklus proses namespace terkelola saat bertransisi dari Pengembangan dan, mungkin, ke Legacy:

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

Jika digunakan, siklus proses namespace terkelola akan dimulai dengan penetapan Pengembangan.

Setelah pengembangan selesai dan kode siap untuk evaluasi dan integrasi, penetapan akan dimigrasikan ke Berikutnya atau Saat Ini. Atau, penetapan tersebut dapat dihapus sepenuhnya dan namespace terkelola tidak lagi digunakan, yang secara efektif membuat penetapan menjadi Sekarang secara implisit.

Jika kode tersebut berfungsi bersama dan belum menggantikan kode saat ini, penetapan harus dimigrasikan ke Berikutnya. Jika kode tersebut menggantikan kode saat ini, penetapan harus dimigrasikan ke Current.

Dengan menggunakan penetapan Next, setelah kode melewati jumlah siklus rilis dan evaluasi yang diinginkan, penetapan tersebut beralih ke Current atau, sekali lagi, Penetapan dapat dihapus sepenuhnya.

Dengan menggunakan penetapan Saat ini, jika kode akan digantikan dengan kode baru tetapi masih perlu dipertahankan untuk sejumlah siklus rilis, penetapan tersebut akan dimigrasikan ke Versi Lama.

Berdasarkan penetapan Versi Lama, kode tersebut pada akhirnya dihapus dari Weave SDK sepenuhnya.

Menggunakan Namespace Terkelola

Pengguna Weave SDK dapat berinteraksi dengan namespace terkelola sebagai developer, memperluas dan mempertahankan kode yang ada, atau sebagai integrator, yang mengintegrasikan Weave ke dalam aplikasi, platform, dan kode sistem mereka sendiri. Dua bagian berikut merinci rekomendasi untuk menangani namespace yang dikelola Weave dari kedua perspektif tersebut.

Menggunakan Namespace Terkelola sebagai Developer

Fokus utama developer Weave SDK adalah meningkatkan dan mengembangkan API dan fungsi Weave SDK baru sekaligus, dalam banyak kasus, secara bersamaan mendukung deployment API dan fungsionalitas yang sudah ada.

Jika tidak mungkin memenuhi kedua area fokus ini dengan cara yang kompatibel dengan versi lama dalam API yang sama, namespace terkelola akan menyediakan mekanisme untuk mengelola API ini secara paralel, tanpa mengganggu deployment fungsi dan API yang ada.

Sebagai contoh praktis, asumsikan profil Weave, Mercury, yang saat ini ada di hierarki namespace berikut yang tidak dikelola:

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

// ...

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

dan beberapa {i>header<i} publik berikut:

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

di mana Mercury.hpp adalah {i>header<i} modul "{i>umbrella<i}". Sebagian besar integrator cukup menyertakan header modul "umbrella" seperti yang ditunjukkan berikut:

#include

Namun, developer Mercury kini telah mencapai titik di mana diperlukan pengembangan API generasi berikutnya dan, kemungkinan, protokol over-the-wire yang tidak kompatibel dengan deployment yang ada. Penggunaan namespace terkelola dapat membantu mencapai hal ini tanpa merusak deployment yang ada.

Memindahkan Namespace yang Ada ke Saat Ini

Dengan tujuan untuk terus mendukung rilis API saat ini dan fungsionalitas untuk integrasi yang telah di-deploy, tugas pertama adalah memindahkan kode saat ini:

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

Catatan, selain memindahkan file, header yang menyertakan pelindung untuk file yang dipindahkan juga harus diganti namanya, berpotensi mendekorasinya dengan '_CURRENT', karena file baru yang bernama serupa akan dibuat tempatnya di bawah ini.

Setelah kode dipindahkan, langkah berikutnya adalah mengelola namespace dengan penetapan yang sesuai, di sini 'Current'. Pertama, buat header yang menentukan namespace terkelola, sebagai 'Current/MercuryManagedNamespace.hpp'. Membuat header seperti itu lebih baik untuk mengulangi dan menduplikasi konten ini di setiap file header saat ada beberapa file header.

% 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

Selanjutnya, sertakan {i>header<i} ini sebelum perintah penyertaan khusus modul lainnya di {i>header<i} yang ada. Contoh:

#include 

#include

Membuat Header Kompatibilitas

Namun, memindahkan header yang ada ke lokasi baru dan mengelola namespace-nya saja tidak cukup untuk memastikan deployment yang ada akan berfungsi tanpa perubahan karena semuanya menggunakan perintah include yang menentukan header yang baru saja dipindahkan ke atas.

Untuk mengatasinya, header wrapper kompatibilitas dengan nama yang cocok dengan yang baru saja dipindahkan harus dibuat.

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

Jika hanya namespace terkelola yang ditunjuk saat ini yang dibuat tanpa membuat namespace terkelola yang ditetapkan Pengembangan atau Berikutnya untuk menyertainya, isi file ini dapat terdiri dari header include guard dan perintah include yang menentukan header yang baru dipindahkan dengan nama sama:

#ifndef _WEAVE_MERCURY_BAR_HPP
#define _WEAVE_MERCURY_BAR_HPP

#include 

#endif // _WEAVE_MERCURY_BAR_HPP

Namun, jika namespace terkelola yang ditunjuk Pengembangan atau Berikutnya juga dibuat untuk mengakomodasi pengembangan baru yang tidak kompatibel, harus dilakukan sesuatu yang sedikit lebih kompleks.

Seperti sebelumnya, header untuk konfigurasi namespace terkelola akan dibuat di sini dengan nama MercuryManagedNamespace.hpp. Sekali lagi, sebaiknya kita mengulang dan menduplikasi konten ini di setiap file header saat ada beberapa file header..

% 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

Perhatikan bahwa penetapan namespace terkelola ke 'Saat ini' jika tidak ada konfigurasi yang ditentukan, seperti yang diinginkan.

Dengan adanya header ini, header wrapper kompatibilitas sekarang dapat diedit untuk memuat:

#include 

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

atau apa pun yang sesuai untuk kasus penggunaan manajemen namespace yang sedang dihadapi.

Membuat Konten Pengembangan

Pada titik ini, infrastruktur kini siap untuk mulai membangun fungsi dan API baru bersama dengan yang sudah ada.

% 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

Tentu saja, jika modul jauh lebih sederhana daripada contoh yang disajikan di sini dan tidak memiliki banyak class, sumber, file, atau header, semua ini dapat dilakukan di file header yang sama tanpa memindahkan file dan membuat beberapa header kompatibilitas dan konfigurasi mandiri. Namun, dengan contoh kompleks ini, contoh ini akan menginspirasi solusi namespace terkelola dalam spektrum dari kompleks ke sederhana.

Menggunakan Namespace Terkelola sebagai Integrator

Fokus utama dari integrator Weave SDK adalah menyertakan header API publik Weave SDK yang sesuai dan mengintegrasikan serta mengembangkan aplikasi terhadap header tersebut.

Sebagai contoh, asumsikan lagi profil Weave, Mercury, yang memiliki namespace terkelola yang ditetapkan Next-, Current-, dan Legacy, yang header publiknya disusun sebagai berikut:

  • 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

di mana Mercury.hpp adalah {i>header<i} modul "{i>umbrella<i}".

Kecuali jika kasus penggunaan yang sedang dihadapi memotivasi penyertaan modul yang dikelola namespace dalam Weave secara eksplisit, misalnya:

#include

sebaiknya rujuk header publik modul Weave melalui jalur default yang tidak dikelola (misalnya Weave/Profiles/Mercury/Mercury.hpp). Dengan melakukannya, Anda dapat mengikuti perkembangan pengembangan API tanpa terus mengubah perintah include project saat API tersebut mengalir melalui lifecycle terkelola.

Dengan mengikuti strategi ini, deployment kemudian dapat menargetkan ulang kodenya pada penetapan namespace terkelola yang berbeda, penetapan Current misalnya, dengan menentukan konfigurasi yang diinginkan dalam preprocessor C/C++. Tindakan ini dapat dilakukan di command line, di kode sumber, atau di header konfigurasi atau awalan:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current

dan gunakan jalur include yang tidak dikelola / tidak memenuhi syarat:

#include

Jika, dan jika, penetapan namespace terkelola berubah untuk API yang ditargetkan, misalnya dari Current ke Legacy, cukup targetkan ulang dengan menyesuaikan definisi praprosesor:

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Legacy