[SE-0535] Add CLI for editing global mirrors configuration

안녕하세요. 그린입니다 🍏
이번 포스팅에서는 SE-0535 — 전역 mirrors 설정을 위한 CLI 추가에 대해 정리해보겠습니다 🙋🏻

Intro

Proposal: SE-0535

Author: Samuel Murray

Review Manager: Tim Condon

Status: Accepted

Implementation: swiftlang/swift-package-manager#9950

SPM은 로컬(프로젝트 단위)과 공유(사용자 단위) mirrors 설정을 둘 다 지원하지만, CLI로는 로컬 설정 파일만 편집할 수 있었어요.

 

이 제안은 기존 CLI에 전역 설정을 편집할 수 있는 --global 플래그를 옵션으로 추가합니다.

 

Motivation

원래 mirrors는 최초 제안에서 설명된 대로 프로젝트별 로컬 설정만 가능했어요.

이후 릴리스에서 전역 설정 파일 지원이 추가됐는데, 처음부터 로컬/전역 설정을 모두 지원해온 package registry의 디자인을 따른 거예요.

mirrors와 package registry의 전역 설정 파일은 특정 패키지를 항상 커스텀 URL에서 받아와야 하는 엔터프라이즈 환경에서 특히 유용해요.

게다가 곧 추가될 바이너리 타깃 미러링 지원으로 전역 설정의 유용함은 더 커질 예정입니다.

 

하지만 현재는 전역 mirrors 설정을 쉽게 편집하고 확인할 방법이 없어요.

유일한 방법은 설정 파일을 직접 만들고 손으로 편집하는 것뿐이죠.

이걸 위한 CLI를 제공하면 이미 있는 전역 package registry 기능과 결을 맞추면서, 전역 mirrors 설정의 발견 가능성도 높일 수 있습니다.

 

Proposed Solution

로컬 설정 파일을 다루는 기존 CLI는 다음과 같아요.

• swift package config set-mirror
• swift package config unset-mirror
• swift package config get-mirror

이 제안은 이 명령어들 각각에 선택적인 --global 플래그를 추가합니다.

 

예시

https://example.com/file.json의 mirror를 전역으로 추가하려면:

$ swift package config set-mirror --global --original https://example.com/file.json --mirror https://internal.com/file.json

 

그러면 ~/.swiftpm/configuration/mirrors.json에 아래 내용이 추가돼요. (파일이 없으면 새로 만듭니다)

{
  "object" : [
    {
      "mirror" : "https://internal.com/file.json",
      "original" : "https://example.com/file.json"
    }
    // ...
  ],
  "version" : 1
}

 

이 설정을 확인하려면:

$ swift package config get-mirror --global --original https://example.com/file.json
https://internal.com/file.json

 

설정을 해제하려면:

$ swift package config unset-mirror --global --original https://example.com/file.json

 

package registry용 CLI에서 아이디어를 얻어서, 이 명령어들 각각에 --global 플래그를 추가하자고 제안해요.

예를 들면 swift package config set-mirror --global [...] 이렇게요.

 

이 플래그와 함께 쓰면 명령어는 전역 설정 파일만 고려하게 됩니다.

이 플래그를 쓰면 명령어를 어느 디렉터리에서든 실행할 수 있어요.

반면 지금의 (플래그 없는) 명령어는 현재 디렉터리나 그 상위 디렉터리 어디에도 Package.swift가 없으면 실패하죠.

현재 swift package config get-mirror의 동작은, 로컬 설정 파일이 비어 있거나 없으면 전역 설정 파일을 읽는 방식이에요.
제안자는 이 동작을 그대로 두자고 제안합니다.
로컬 설정이 하나라도 있으면 전역 설정을 완전히 무시하는 것보다, 로컬을 더 높은 우선순위로 두고 로컬/전역을 병합하는 게 더 합리적이라고 생각하지만, 이건 이 제안과는 다소 별개의 주제라 후속 제안으로 다루는 게 좋겠다고 봤다고 합니다!

Detailed Design

--global 플래그와 함께 쓰는 모든 명령어는 어느 디렉터리에서든 사용할 수 있어요.

즉, 현재 디렉터리(또는 그 상위 디렉터리)에 Package.swift 파일이 있을 필요가 없습니다.

--global 플래그 없이 쓰면 모든 명령어의 동작은 기존과 동일합니다.

 

set-mirror

$ swift package config set-mirror --help
OVERVIEW: Set a mirror for a dependency.

USAGE: swift package config set-mirror [--global] [--original ] [--mirror ]

OPTIONS:
  --global                Apply settings to all projects for this user.
  --original    The original url or identity.
  --mirror        The mirror url or identity.
  --version               Show the version.
  -h, -help, --help       Show help information.

이 명령어를 실행하면 ~/.swiftpm/configuration/mirrors.json에 mirror 설정을 추가하거나, 파일이 없으면 새로 만듭니다.

 

unset-mirror

$ swift package config unset-mirror --help
OVERVIEW: Remove an existing mirror.

USAGE: swift package config unset-mirror [--original ] [--mirror ]

OPTIONS:
  --global                Apply settings to all projects for this user.
  --original    The original url or identity.
  --mirror        The mirror url or identity.
  --version               Show the version.
  -h, -help, --help       Show help information.

이 명령어를 실행하면 ~/.swiftpm/configuration/mirrors.json에서 일치하는 mirror 설정을 제거해요.

일치하는 항목이 없거나 파일이 없으면 에러 메시지를 표시합니다.

 

get-mirror

OVERVIEW: Print mirror configuration for the given package dependency.

USAGE: swift package config get-mirror [--original ]

OPTIONS:
  --global                Only read settings applied to all projects for this user.
  --original    The original url or identity.
  --version               Show the version.
  -h, -help, --help       Show help information.

이 명령어를 실행하면 ~/.swiftpm/configuration/mirrors.json에서 일치하는 mirror 설정을 가져와요.

일치하는 항목이 없거나 파일이 없으면 에러 메시지를 표시합니다.

 

Security

이 제안이 보안에 미치는 영향은 미미해요. 사용자 홈 디렉터리에 있는 파일을 수정하거나 읽는 정도입니다. mirrors의 최초 제안에서는 전역 설정이 "예상 못한 함정" 같은 순간을 만들 수 있다는 우려가 있었지만, SPM에 전역 mirrors 설정 지원이 이미 추가된 상태라 이 CLI를 추가한다고 해서 새로운 이슈가 생기진 않습니다.

 

Impact on Existing Packages

이 제안은 기존 패키지에 아무런 영향을 주지 않아요. 새 CLI 플래그를 추가할 뿐, 기존 동작은 전혀 바뀌지 않습니다.

 

Conclusion

작지만 실용적인 CLI 개선이에요. 그동안 전역 mirrors 설정을 편집하려면 ~/.swiftpm/configuration/mirrors.json을 직접 손으로 만지는 수밖에 없었는데, --global 플래그 하나로 set-mirror, unset-mirror, get-mirror를 어느 디렉터리에서든 쓸 수 있게 됐어요.

엔터프라이즈 환경에서 특정 패키지를 항상 내부 URL로 받아오게 설정해두고 싶을 때, 그리고 곧 추가될 바이너리 타깃 미러링과 함께 쓰기에도 훨씬 편리해질 것 같습니다 🙌

 

References

swift-evolution/proposals/0535-global-mirrors-configuration-cli.md at main · swiftlang/swift-evolution