TL;DR

  • .cmd는 Linux·macOS·Windows에서 동일한 명령줄 인터페이스를 제공하고 저장소에 함께 체크인할 수 있어, 사전 설치 없이 빌드·테스트·실행을 가능하게 하는 크로스플랫폼 작업 실행기임.
  • 작은 다중 언어 셸 스크립트가 독립 실행형 Lua 실행 파일을 내려받고, 이를 프로그램 내려받기와 실행에 활용함.
  • SHA-256 해시로 의존성을 고정하고 다운로드를 검증하며, 캐시된 파일을 여러 실행과 프로젝트에서 재사용함.
  • zsh, bash, pwsh, cmd 등의 셸에서 동작하며, 초기화 명령으로 .cmd.lua 설정 파일을 만들고 셸 자동 완성과 Lua 언어 서버 주석을 설정할 수 있음.
  • 예시에서는 Go 1.27.1 도구 체인을 플랫폼별로 내려받아 빌드와 실행을 수행하며, 최초 실행 후에는 캐시된 도구 체인을 사용함.

존재 이유

  • .cmd는 Linux·macOS·Windows 프로젝트에서 개발 의존성과 빌드 스크립트를 설정할 때 동일한 명령줄 인터페이스를 제공함.
  • 저장소에 체크인하도록 설계되어 있어, 새로 체크아웃한 프로젝트만으로 빌드·테스트·실행이 가능함.
  • 기여자 온보딩과 지속적 통합(CI) 설정을 간소화하며, .cmd 사용에 필요한 사전 설치 항목이 없음.

.cmd의 구성

  • Linux·macOS·Windows에서 동작하는 작은 다중 언어 셸 스크립트이며, zsh, bash, pwsh, cmd 등의 셸을 지원함.
  • 독립 실행형 Lua 실행 파일을 내려받아 크로스플랫폼 프로그램 내려받기와 실행에 사용함.
  • 크기가 작고 성능이 뛰어나며 보안성이 높고, 내장 도구로 모든 의존성을 SHA-256 해시를 사용해 고정할 수 있음.

설치

  • 시스템 전체에 설치하는 절차 없이 파일 하나를 저장소에 내려받으면 됨.
  • Linux·macOS에서는 아래 명령으로 파일을 내려받고 실행 권한을 설정함.
  • curl -fsSL https://github.com/dotcmdhq/dotcmd/releases/latest/download/dotcmd.cmd -o .cmd && chmod +x .cmd
  • Windows PowerShell에서는 아래 명령으로 파일을 내려받음.
  • Invoke-WebRequest -UseBasicParsing https://github.com/dotcmdhq/dotcmd/releases/latest/download/dotcmd.cmd -OutFile .cmd
  • Windows cmd.exe에서는 아래 명령으로 파일을 내려받음.
  • curl.exe -fsSL https://github.com/dotcmdhq/dotcmd/releases/latest/download/dotcmd.cmd -o .cmd

시작하기

  • ./.cmd --init을 실행하면 빌드 설정 파일인 .cmd.lua가 생성됨.
  • 편의를 위해 ./.cmd --setup completions로 셸 자동 완성을 설치하고, ./.cmd --setup luals로 Lua 언어 서버용 주석을 설치할 수 있음.
  • 코딩 에이전트에 .cmd를 가리키면 필요한 문서가 내장되어 있어 사용법을 파악할 수 있음.
  • Go 프로그램 예시 설정은 build와 run 작업을 정의함.
  • build 작업은 Go 1.27.1 버전을 지정하고, 플랫폼별 운영체제 이름과 아키텍처 이름을 Go 배포 파일 형식에 맞게 대응시킴. Linux·macOS·Windows의 x64·arm64 조합별 SHA-256 해시를 고정하며, 해시 출처는 Go 다운로드 정보임.
  • 빌드 디렉터리를 만들고 운영체제에 따라 .zip 또는 .tar.gz 파일을 내려받아 압축을 풂. 내려받은 Go 도구 체인으로 hello.go를 빌드하며, GOROOT, GOTOOLCHAIN=local, CGO_ENABLED=0 환경 변수를 설정함.
  • run 작업은 build를 호출한 뒤 이름 인자를 받아 빌드된 프로그램에 전달함.
  • 저장소를 체크아웃한 사용자는 도구를 별도로 설치하지 않고 ./.cmd run으로 Go 프로그램을 실행할 수 있음. 첫 실행 때 Go 도구 체인을 내려받고, 이후에는 캐시된 버전을 사용함.

주요 개념

작업

  • .cmd.lua는 이름이 지정된 작업 테이블을 반환하며, ./.cmd build는 build 작업의 run 함수를 실행함.
  • 작업은 설명, 위치 인자, 옵션을 선언할 수 있으며, 이 정의가 인자 분석·도움말·셸 자동 완성에 사용됨.

fetch

  • fetch는 다운로드 URL과 고정된 SHA-256 해시를 받아 로컬 경로를 제공함.
  • 새 다운로드의 해시를 검증하고, 실행과 프로젝트를 넘나들며 캐시된 파일을 재사용함.
  • 선택적 prepare(input, output) 함수로 압축 파일을 푸는 등 준비된 파일이나 디렉터리를 만들 수 있음.
  • 예시에서는 시스템 전체 설치 없이 현재 플랫폼에 맞는 Go 도구 체인을 제공함.

exec

  • exec는 Lua 테이블로 전달된 인자를 사용해 프로그램을 실행함.
  • 프로그램을 직접 실행하므로 각 인자는 셸의 인용이나 확장 없이 전달됨. 기본 작업 디렉터리는 프로젝트 디렉터리이며, cwd와 env로 자식 프로세스의 작업 디렉터리와 환경을 설정할 수 있음.
  • 기본적으로 출력은 터미널에 직접 전달되고, 0이 아닌 종료 코드는 작업 실패로 처리됨. 예시에서는 내려받은 Go 컴파일러를 실행한 다음 생성된 프로그램을 실행함.