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

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

관리형 네임스페이스

요약

소개

Weave SDK에서 관리형 네임스페이스는 Weave SDK 개발자와 통합자 모두에게 SDK 내 특정 API 세트 지정에 대한 공지된 안내 및 하위 텍스트를 제공하여 Weave SDK 릴리스 전반에 걸친 이전 경로를 계획하고 예측할 수 있게 하고 잠재적으로 특정 모듈에 대해 여러 개의 동시 Weave API를 관리할 수 있도록 합니다.

직위

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

개발

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

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

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

Next 관리형 네임스페이스 지정은 향후 릴리스에서 현재 기본 API가 될 API를 힌트로 표시하여 Weave SDK가 향하는 방향을 개발자와 통합자에게 효과적으로 제공합니다.

Next 관리형 네임스페이스 지정은 선택사항입니다. 관리형 네임스페이스를 사용하지 않고 수명 주기 동안 전환할 수 있습니다 (관리형 네임스페이스 수명 주기 참조).

현재

현재 지정 또는 관리되지 않는 네임스페이스로 관리되는 네임스페이스 (즉, 관리되는 네임스페이스 지정이 없음)는 Weave SDK의 해당 부분 또는 모듈에 대해 지원되는 현재 기본 공식 API를 나타냅니다. 이러한 API가 계속해서 개선되고 있을 수 있지만, 변경사항은 대부분 점진적이고 이전 버전과의 호환성이 유지되므로 API와 유선 모두 유지되어야 합니다.

현재 관리형 네임스페이스 지정은 선택사항입니다. 관리형 네임스페이스를 사용하지 않고 수명 주기 동안 전환할 수 있습니다 (관리형 네임스페이스 수명 주기 참조). 실제로 관리되지 않는 네임스페이스는 암시적으로 최신 네임스페이스입니다.

기존

레거시로 관리되는 모든 네임스페이스는 개발자와 통합자에게 포함된 API가 지원 중단되었으며 새로운 최신 API로 대체되었음을 나타냅니다. 이러한 API는 이전의 현재 API를 나타냅니다.

이렇게 지정된 API는 다음 주요 Weave SDK 출시에서 완전히 사라질 것입니다. 따라서 개발자와 통합자는 Weave SDK의 최첨단 버전을 유지하려면 이러한 API로부터의 이전 계획을 수립해야 합니다.

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

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

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

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

개발이 완료되고 코드를 평가 및 통합할 준비가 되면 지정이 Next 또는 Current로 이전됩니다. 또는 지정이 완전히 취소되고 관리형 네임스페이스가 더 이상 사용되지 않아 지정이 사실상 최신 상태가 될 수 있습니다.

코드가 함께 게시되어야 하지만 아직 현재 코드를 대체하지 않는 경우 지정은 Next로 이전되어야 합니다. 코드가 현재 코드를 대체하는 경우 지정을 최신으로 이전해야 합니다.

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 

#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

개발 또는 다음으로 지정된 관리형 네임스페이스를 만들지 않고 현재 지정된 관리형 네임스페이스만 생성되는 경우 이러한 파일의 콘텐츠는 헤더 include 가드와 동일한 이름의 새로 이동된 헤더를 지정하는 include 지시어로 구성될 수 있습니다.

#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 

#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

구성이 정의되지 않은 경우 원하는 경우 관리형 네임스페이스 지정이 '현재'로 기본 설정됩니다.

이 헤더가 있으면 이제 다음을 포함하도록 호환성 래퍼 헤더를 수정할 수 있습니다.

#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 통합업체는 적절한 Weave SDK 공개 API 헤더를 포함하고 이를 토대로 애플리케이션을 통합 및 개발하는 데 중점을 둡니다.

작업 예시로, 다시 한번 Weave 프로필인 Mercury에 대해 Next, Current-, Legacy에서 지정된 관리형 네임스페이스가 있고, 공개 헤더가 다음과 같이 구성되어 있다고 가정해 보겠습니다.

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/Profiles/Mercury/Mercury.hpp)로 Weave 모듈 공개 헤더를 참조하는 것이 가장 좋습니다. 이렇게 하면 프로젝트의 include 지시어를 지속적으로 변경하지 않고도 API가 관리형 lifecycle를 통해 흐를 때 API 개발을 진행할 수 있습니다.

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

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Current

비관리형 / 정규화되지 않은 include 경로를 사용합니다.

#include

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

#define WEAVE_CONFIG_MERCURY_NAMESPACE kWeaveManagedNamespace_Legacy