ccam 업데이트

ccam update는 GitHub에서 ccam 릴리스를 내려받아 릴리스의 checksums.txt로 확인한 뒤, 실행 중인 바이너리를 이름 바꾸기 한 번으로 교체합니다. 설치 스크립트나 압축 파일로 ccam을 설치했을 때 쓰면 됩니다. ccam은 스스로 업데이트를 확인하지 않습니다. GitHub에 접속하는 명령은 이것 하나뿐이므로, 다른 모든 명령은 오프라인에서도 똑같이 동작합니다.

사용법

ccam update                    # install the latest release
ccam update --check            # only say whether a newer release exists
ccam update --version v0.3.0   # install that release, also an older one
ccam --dry-run update          # show what would be downloaded and replaced

$ ccam update --check
ccam 0.5.0 is available (you have 0.4.0). Run `ccam update`.
$ ccam --dry-run update
Would update ccam 0.4.0 → 0.5.0:
  download  https://github.com/jhyunwoo/ccam/releases/download/v0.5.0/ccam_linux_amd64.tar.gz
  verify    with https://github.com/jhyunwoo/ccam/releases/download/v0.5.0/checksums.txt
  replace   /home/you/.local/bin/ccam
$ ccam update
→ downloading https://github.com/jhyunwoo/ccam/releases/download/v0.5.0/ccam_linux_amd64.tar.gz
✓ Updated ccam 0.4.0 → 0.5.0 (/home/you/.local/bin/ccam)

더 새로운 릴리스가 없으면 ccam은 ccam 0.4.0 is up to date.를 출력하고 아무것도 바꾸지 않습니다. --version에 지금 실행 중인 버전을 주면 ccam 0.4.0 is already installed.를 출력합니다.

옵션

--check와 --version은 함께 쓸 수 없습니다. 태그는 vMAJOR.MINOR.PATCH 형식이어야 하며, 프리릴리스나 빌드 접미사를 붙일 수 있습니다. 앞의 v는 생략해도 됩니다. 그 밖의 형식은 실패합니다(예: --version takes a release tag such as v0.3.0, not "1.2").

환경 변수 CCAM_RELEASES_URL은 미러나 테스트를 위해 https://github.com/jhyunwoo/ccam/releases를 대신합니다. 구조는 같아야 합니다. <url>/latest는 <url>/tag/<tag>로 리디렉션되고, 파일은 <url>/download/<tag>/<asset>에 있어야 합니다.

동작 방식

코드는 internal/update에 있으며, 이 패키지는 ccam update만 가져다 씁니다. 실행 경로에서는 절대 호출하지 않습니다.

1. cli.updateCmd는 os.Executable로 실행 중인 바이너리를 찾고 filepath.EvalSymlinks로 심볼릭 링크를 해석합니다. 교체되는 것은 이 실제 경로입니다.
2. --version이 없으면 Updater.Latest가 리디렉션을 따라가지 않고 <releases>/latest를 요청한 뒤, Location 헤더(…/tag/v0.5.0)에서 태그를 읽습니다. GitHub API 대신 릴리스 페이지를 쓰므로, 시간당 60회라는 API 요청 한도가 적용되지 않습니다. 조회 제한 시간은 10초입니다.
3. parseVersion이 엄격한 패턴으로 태그를 검사합니다. 태그는 다운로드 URL과 출력되는 셸 명령에 들어가므로, /, %, 공백, 셸 문자가 포함된 것은 통과하지 못합니다. compareVersions는 이 태그를 실행 중인 버전과 비교하며, 프리릴리스는 해당 정식 릴리스보다 앞선 버전으로 취급합니다.
4. managed()와 writable()이 ccam이 바이너리를 교체해도 되는지 판단합니다(아래 참고).
5. Updater.Fetch는 ccam_<os>_<arch>.tar.gz와 checksums.txt를 동시에 내려받으며, 두 파일을 합쳐 제한 시간은 2분입니다. 각 다운로드는 최대 256 MB입니다.
6. 다른 작업을 하기 전에 압축 파일의 SHA-256이 checksums.txt의 해당 줄과 일치해야 합니다. 줄이 없거나 체크섬이 다르면 nothing was changed를 출력하고 업데이트를 멈춥니다.
7. extract()는 tar를 읽어 ccam이라는 이름의 첫 번째 일반 파일을 꺼냅니다. 디렉터리, 링크 등 다른 항목은 무시하며, 바이너리도 최대 256 MB입니다.
8. Updater.Install은 fsutil.AtomicWrite로 새 바이너리를 기록합니다. 바이너리 옆에 이전 파일과 같은 권한 비트로 임시 파일 .ccam.tmp*를 만들고, 디스크에 기록한 뒤 이전 파일 위로 이름을 바꿉니다.

태그 조회부터 이름 바꾸기까지의 전체 과정은 다음과 같습니다.

압축 파일과 checksums.txt를 나란히 내려받고, 체크섬이 일치하기 전에는 아무것도 기록하지 않습니다. 이름 바꾸기는 원자적이므로, 도중에 비정상 종료되거나 디스크가 가득 차도 이전 바이너리나 새 바이너리 중 하나가 온전히 남습니다. 절반만 바뀐 파일은 생기지 않습니다. ~/.local/bin/ccwork 같은 단축 명령은 ccam 바이너리를 가리키는 심볼릭 링크이므로, 아무것도 바꾸지 않아도 새 버전을 실행합니다.

패키지로 설치한 경우

.deb로 설치한 ccam은 apt가 관리하므로, apt 모르게 교체하면 패키지 데이터베이스가 실제와 달라집니다. ccam은 내려받기 전에 바이너리를 누가 관리하는지 확인합니다.

1. /usr/bin, /bin, /usr/sbin, /sbin에 있는 바이너리는 패키지가 관리하는 것으로 봅니다.
2. 그 밖의 위치라도 dpkg가 설치되어 있고 dpkg -S <path>가 성공하면 패키지가 관리하는 것으로 봅니다.
3. 둘 다 아니면 ccam이 바이너리 옆에 임시 파일 .ccam-update-*를 만들었다 지워 보면서 그 폴더에 쓸 수 있는지 확인합니다.

패키지가 관리하는 바이너리라면 ccam은 멈추고 apt로 업데이트하는 방법을 출력합니다.

$ ccam update
ccam: /usr/bin/ccam was installed by a package, so `ccam update` leaves it alone.
To update the .deb, download ccam_0.5.0_linux_amd64.deb from https://github.com/jhyunwoo/ccam/releases/tag/v0.5.0 and run:
  sudo apt install ./ccam_0.5.0_linux_amd64.deb
Or install a copy in ~/.local/bin with the install script:
  curl -fsSL https://raw.githubusercontent.com/jhyunwoo/ccam/main/install.sh | sh

Linux가 아닌 시스템에서는 설치 스크립트 줄만 출력합니다. 폴더에 쓸 수 없으면 ccam은 설치 스크립트를 다시 실행하라고 안내합니다. 설치 스크립트는 ccam을 ~/.local/bin에 설치합니다.

안전장치와 예외 상황

• 개발 빌드는 버전을 dev로 표시하며 비교할 릴리스가 없으므로, ccam update와 ccam update --check가 거부합니다. ccam update --version vX.Y.Z로는 그 위에 릴리스를 설치할 수 있습니다.
• 다운로드가 실패하거나, 사용 중인 플랫폼용 파일이 없거나, 체크섬이 일치하지 않으면 설치된 바이너리는 그대로 남습니다.
• 없는 릴리스를 지정하면 there is no release <tag>로 실패합니다. GitHub가 HTTP 403이나 429로 거부하면, ccam은 요청 한도 때문일 가능성이 높다고 알리고 나중에 다시 시도하라고 안내합니다.
• --check는 읽기만 합니다. 바이너리가 패키지로 관리되는지, 쓸 수 있는지는 확인하지 않습니다.
• 이전 버전으로 되돌리려면 --version에 이전 태그를 주면 됩니다.

관련 문서

• 설치
• 명령어
• FAQ