Namespace Terkelola

Ringkasan

Pengantar

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

Pengelompokan

Namespace terkelola dapat dikelola sebagai salah satu dari empat pengelompokan:

Pengembangan

Setiap namespace yang dikelola dengan penetapan Pengembangan merupakan indikasi bagi developer dan integrator bahwa API yang terdapat di dalamnya sedang dalam pengembangan aktif, dapat berubah sewaktu-waktu, dan tidak didukung secara resmi. Integrator umumnya tidak disarankan untuk menggunakan API ini kecuali jika 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 di Weave SDK API dan akan menjadi API default saat ini pada siklus releaes utama dalam waktu dekat atau dekat.

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

Penetapan namespace terkelola Berikutnya secara efektif memberikan gambaran kepada developer dan integrator terkait tujuan Weave SDK dengan menunjukkan API yang akan menjadi API default saat ini dalam rilis mendatang.

Penetapan namespace terkelola Berikutnya 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 tidak memiliki penetapan namespace terkelola) mewakili API resmi yang didukung saat ini, default, dan yang didukung untuk bagian atau modul Weave SDK tersebut. Meskipun mungkin masih ada peningkatan berkelanjutan pada API tersebut, perubahan sebagian besar akan memiliki kompatibilitas inkremental dan versi sebelumnya, baik API maupun melalui kabel, 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, setiap namespace yang tidak dikelola secara implisit adalah Current.

Lama

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

API yang ditetapkan akan hilang semuanya di rilis utama Weave SDK berikutnya; oleh karena itu, developer dan integrator harus membuat rencana migrasi dari API ini jika mereka ingin tetap menggunakan versi terdepan dalam rilis Weave SDK.

Siklus Proses Namespace Terkelola

Gambar berikut mengilustrasikan siklus proses namespace terkelola saat bertransisi dari Development dan, kemungkinan, 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 serta integrasi, penetapan akan bermigrasi ke Berikutnya atau Saat Ini. Atau, penetapan dapat dihentikan sepenuhnya dan namespace terkelola tidak lagi digunakan, yang secara efektif menjadikan penetapan sebagai Aktif secara implisit.

Jika kode tersebut akan ditampilkan 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 Berikutnya, setelah kode menjalani jumlah siklus rilis dan evaluasi yang diinginkan, penetapan akan bermigrasi ke Saat Ini atau, sekali lagi, Penetapan dapat dihapus sepenuhnya.

Menggunakan penetapan Saat Ini, jika kode akan digantikan oleh kode baru tetapi masih perlu dipertahankan selama sejumlah siklus rilis, penetapan akan dimigrasikan ke Lama.

Dari penetapan Lama, kode pada akhirnya akan 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. Berikut dua bagian rekomendasi detail untuk menangani namespace yang dikelola Weave dari kedua perspektif tersebut.

Menggunakan Namespace Terkelola sebagai Developer

Fokus utama developer Weave SDK adalah meningkatkan kualitas dan mengembangkan API dan fungsi Weave SDK yang baru, sekaligus mendukung deployment fungsi dan API yang sudah ada.

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

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

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

// ...

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

dan header publik berikut:

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

dengan Mercury.hpp adalah modul "umbrella" {i>header<i}. Kebanyakan integrator cukup menyertakan modul "umbrella" seperti yang ditunjukkan berikut:

#include

Namun, pengembangan Mercury kini telah mencapai titik di mana ada kebutuhan untuk mengembangkan API generasi berikutnya dan, kemungkinan, protokol over-the-wire yang tidak kompatibel dengan deployment yang ada. Menggunakan namespace terkelola dapat membantu menyelesaikannya tanpa merusak deployment yang sudah ada ini.

Memindahkan Namespace yang Ada ke Saat Ini

Dengan tujuan untuk terus mendukung rilis API saat ini dan fungsionalitas untuk integrasi yang sudah 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, {i>header<i} menyertakan guard untuk file yang dipindahkan juga harus diganti namanya, yang berpotensi mendekorasinya dengan '_CURRENT', karena file baru yang bernama sama akan dibuat di tempatnya di bawah.

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'. Lebih baik membuat header seperti itu daripada mengulang dan menduplikasi konten ini di setiap file header jika ada beberapa file header.

% 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

Selanjutnya, sertakan header ini sebelum perintah penyertaan khusus modul lainnya dalam header yang ada. Contoh:

#include 

#include

Membuat Header Kompatibilitas

Namun, memindahkan header yang ada ke lokasi baru dan mengelola namespace saja tidaklah cukup untuk memastikan bahwa deployment yang ada akan berfungsi tanpa perubahan karena semuanya menggunakan perintah include yang menentukan header yang baru saja dipindahkan di 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 ditetapkan saat ini yang dibuat tanpa membuat namespace terkelola yang ditetapkan untuk Pengembangan atau Berikutnya untuk menyertainya, konten file ini dapat hanya terdiri dari header termasuk guard dan direktif include yang menentukan header yang baru dipindahkan dengan nama yang sama:

#ifndef _WEAVE_MERCURY_BAR_HPP
#define _WEAVE_MERCURY_BAR_HPP

#include 

#endif // _WEAVE_MERCURY_BAR_HPP

Namun, jika namespace terkelola yang ditetapkan untuk Pengembangan atau Berikutnya sedang dibuat juga untuk mengakomodasi pengembangan baru yang tidak kompatibel, perlu ada sesuatu yang sedikit lebih kompleks.

Seperti sebelumnya, header untuk konfigurasi namespace terkelola akan dibuat di sini sebagai MercuryManagedNamespace.hpp. Sekali lagi, lebih disarankan untuk mengulang dan menduplikasi konten ini di setiap file header jika ada beberapa file header.

% 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

Perhatikan bahwa, sesuai keinginan, penetapan namespace terkelola ke nilai 'Current' secara default jika tidak ada konfigurasi yang ditentukan.

Dengan menerapkan header ini, header wrapper kompatibilitas kini dapat diedit untuk berisi:

#include 

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

atau apa pun yang sesuai dengan kasus penggunaan pengelolaan namespace yang sedang dihadapi.

Buat Konten Pengembangan

Pada tahap 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 <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

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 diselesaikan dalam file header yang sama tanpa memindahkan file dan membuat beberapa header kompatibilitas dan konfigurasi mandiri. Namun, dengan contoh yang kompleks ini, akan mengilhami solusi namespace terkelola di sepanjang spektrum dari yang kompleks hingga yang sederhana.

Menggunakan Namespace Terkelola sebagai Integrator

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

Sebagai contoh, gunakan kembali profil Weave, Mercury, yang memiliki namespace terkelola yang ditetapkan untuk Next, Current-, dan Legacy, yang header publiknya memiliki struktur 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

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

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

#include

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

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

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current

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

#include

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

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Legacy