Google은 흑인 공동체를 위한 인종적 평등을 추구하기 위해 노력하고 있습니다. 자세히 알아보기

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

관리형 네임스페이스

요약

소개

관리형 네임스페이스는 Weave SDK에서 SDK 내에서 특정 API 세트 지정에 대한 공지된 지침과 하위 텍스트를 제공하기 위해 Weave SDK에서 사용됩니다. 이를 통해 Weave SDK 릴리스 전체에서 마이그레이션 경로를 계획하고 예측할 수 있고, 잠재적으로는 특정 모듈에 대해 여러 개의 동시 Weave API를 관리할 수 있습니다.

칭호

관리형 네임스페이스는 다음 네 가지 지정 중 하나로 관리될 수 있습니다.

개발

개발 지정으로 관리되는 네임스페이스는 안에 포함된 API가 개발 중이며 변경될 수 있으며 공식적으로 지원되지 않음을 개발자와 통합자에게 나타냅니다. 일반적으로 통합자는 특별히 지시된 경우를 제외하고는 이러한 API를 사용하지 않는 것이 좋습니다.

Next 지정으로 관리되는 네임스페이스는 개발자와 통합자에게 이 API에 포함된 API는 대체로 적극적인 개발이 완료되었지만 여전히 변경될 수 있으며 조기 평가 목적으로 지원된다는 것을 나타냅니다. 이렇게 지정된 API는 Weave SDK API의 차세대 기능을 나타내며, 가까운 미래에 주요 출시 주기에서 현재의 기본 API가 될 것입니다.

API 및 유선 프로토콜 관점에서 이전 버전과의 호환성이 존재할 수 있지만 지정된 API에서 보장되지는 않습니다.

Next 관리 네임스페이스 지정을 통해 개발자와 통합자는 향후 릴리스에서 현재 기본 API가 될 항목을 암시하여 Weave SDK가 향하는 방향을 효과적으로 파악할 수 있습니다.

관리형 네임스페이스가 사용하지 않고 수명 주기를 거쳐 전환될 수 있도록 다음 관리형 네임스페이스 지정은 선택사항입니다 (관리형 네임스페이스 수명 주기 참조).

현재

현재 지정 또는 비관리 네임스페이스로 관리되는 모든 네임스페이스 (즉, 관리형 네임스페이스 지정이 없음)는 Weave SDK의 해당 부분 또는 모듈에 대해 현재 지원되는 기본 API를 나타냅니다. 이러한 API가 아직 지속적으로 개선될 수는 있지만 변경사항은 주로 점진적인 호환성과 이전 버전과의 호환성(API 및 유선을 통한 호환성 모두)을 유지해야 합니다.

관리형 네임스페이스가 이를 사용하지 않고 수명 주기를 거치도록 전환될 수 있도록, 현재 관리형 네임스페이스 지정은 선택사항입니다 (관리형 네임스페이스 수명 주기 참조). 실제로 비관리 네임스페이스는 암시적으로 현재 네임스페이스입니다.

기존

기존 지정으로 관리되는 네임스페이스는 개발자 및 통합자에게 여기에 포함된 API가 지원 중단되었으며 새로운 현재 API로 대체되었음을 나타냅니다. 이러한 API는 이전의 현재 API를 나타냅니다.

이렇게 지정된 API는 다음번 주요 Weave SDK 릴리스에서 완전히 사라질 것입니다. 따라서 개발자와 통합자는 Weave SDK 릴리스의 최첨단을 계속 사용하려면 이러한 API에서 마이그레이션할 계획을 세워야 합니다.

관리형 네임스페이스 수명 주기

다음 그림은 개발에서 레거시로 전환될 때 관리형 네임스페이스의 수명 주기를 보여줍니다.

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

이를 사용하는 경우 관리형 네임스페이스 수명 주기는 '개발'로 지정된 것으로 시작됩니다.

개발이 완료되고 코드를 평가 및 통합할 준비가 되면 지정이 Next 또는 Current로 이전됩니다. 또는 지정이 완전히 삭제되고 관리형 네임스페이스가 더 이상 사용되지 않아 사실상 암시적으로 '현재' 네임스페이스가 될 수 있습니다.

코드가 현재 코드를 대체하지 않고 함께 사용하려는 경우 그 지정을 Next로 이전해야 합니다. 코드가 현재 코드를 대체하는 경우 지정을 Current로 이전해야 합니다.

다음 지정을 사용하면 코드가 원하는 횟수의 출시 및 평가 주기를 거친 후 현재 지정으로 이전되거나 지정이 완전히 삭제될 수 있습니다.

현재 지정을 사용하여 코드가 새 코드로 대체되어야 하지만 여러 출시 주기 동안 계속 유지되어야 하는 경우 지정이 기존 코드로 이전됩니다.

Legacy 지정으로 인해 코드가 Weave SDK에서 완전히 삭제됩니다.

관리형 네임스페이스 사용

Weave SDK 사용자는 개발자로서 기존 코드의 확장 및 유지관리로서, 또는 Weave를 자신의 애플리케이션, 플랫폼 및 시스템 코드에 통합하는 통합업체로서 관리형 네임스페이스와 상호작용할 수 있습니다. 다음 두 섹션에서는 이러한 두 가지 관점에서 Weave 관리 네임스페이스를 처리하기 위한 권장 사항을 자세히 설명합니다.

개발자로 관리 네임스페이스 사용

Weave SDK 개발자의 주안점은 새로운 Weave SDK API 및 기능을 향상 및 개발하는 동시에 기존 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.hpp는 'umbrella' 헤더를 클릭하세요. 대부분의 통합자는 'umbrella' 헤더를 다음과 같이 바꿉니다.

#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 

#include

호환성 헤더 생성

그러나 기존 헤더를 새 위치로 이동하고 네임스페이스만 관리하는 것만으로는 기존 배포가 변경 없이 작동한다고 보장할 수 없습니다. 위에서 이동한 헤더를 모두 지정한 include 지시문을 모두 사용하기 때문입니다.

이 문제를 해결하려면 방금 이동한 이름과 일치하는 이름이 있는 호환성 래퍼 헤더를 만들어야 합니다.

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

Development 또는 Next에서 지정된 관리형 네임스페이스를 수반하지 않고 현재 지정된 관리형 네임스페이스만 생성하는 경우 이러한 파일의 콘텐츠는 헤더 포함 가드와 동일한 이름의 새로 이동된 헤더를 지정하는 include 지시문으로 간단히 구성될 수 있습니다.

#ifndef _WEAVE_MERCURY_BAR_HPP
#define _WEAVE_MERCURY_BAR_HPP

#include 

#endif // _WEAVE_MERCURY_BAR_HPP

그러나 새로운 호환되지 않는 개발을 수용하기 위해 Development 또는 Next로 지정된 관리형 네임스페이스를 만드는 경우 약간 더 복잡한 조치가 필요합니다.

이전과 마찬가지로 관리형 네임스페이스 구성을 위한 헤더가 여기에서는 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 통합업체는 적절한 Weave SDK 공개 API 헤더를 포함하고 이 헤더로 애플리케이션을 통합 및 개발하는 데 중점을 두고 있습니다.

실제로 작동하는 예로, Next, Current- 및 Legacy로 지정된 관리 네임스페이스가 있는 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는 'umbrella' 헤더를 클릭하세요.

당면 사용 사례에서 Weave 내에 네임스페이스 관리 모듈을 포함할 것을 명시적으로 요구하지 않는 한, 예를 들면 다음과 같습니다.

#include

Weave 모듈 공개 헤더를 관리되지 않는 기본 경로 (예: Weave/Profiles/Mercury/Mercury.hpp)로 참조하는 것이 가장 좋습니다. 이렇게 하면 API가 관리형 수명 주기를 거치므로 프로젝트의 include 지시문을 지속적으로 변경하지 않고도 API 개발의 진행 상황을 따를 수 있습니다.

이 전략에 따라 배포는 C/C++ 전처리기에서 원하는 구성을 지정하는 등 다른 관리형 네임스페이스 지정(예: 현재 지정)에서 코드를 재타겟팅할 수 있습니다. 이 작업은 명령줄, 소스 코드, 구성 또는 접두사 헤더에서 수행할 수 있습니다.

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current

및 관리되지 않는 / 정규화되지 않은 포함 경로를 사용합니다.

#include

대상 API에 대해 관리형 네임스페이스 지정이 변경되는 경우(예: Current에서 Legacy로 변경) 전처리기 정의를 조정하여 재타겟팅하면 됩니다.

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Legacy