From f640750e378579af5a16af33d5cd417e48619fc3 Mon Sep 17 00:00:00 2001 From: junseo-yang Date: Thu, 16 May 2024 17:56:22 -0400 Subject: [PATCH] Translate to Korean --- docs/.vitepress/config.ts | 8 + docs/.vitepress/navbars.ts | 20 +- docs/.vitepress/sidebars.ts | 114 ++- docs/ko-kr/contribute/core.md | 158 ++++ docs/ko-kr/contribute/documentation.md | 132 +++ docs/ko-kr/contribute/first-party-plugins.md | 14 + docs/ko-kr/contribute/github-actions.md | 3 + docs/ko-kr/guide/getting-started.md | 475 ++++++++++ docs/ko-kr/guide/introduction.md | 57 ++ docs/ko-kr/index.md | 40 + docs/ko-kr/manage/commands.md | 5 + docs/ko-kr/manage/configuration.md | 261 ++++++ docs/ko-kr/manage/core.md | 456 +++++++++ docs/ko-kr/manage/plugins.md | 86 ++ docs/ko-kr/manage/versions.md | 155 +++ docs/ko-kr/more/community-projects.md | 16 + docs/ko-kr/more/faq.md | 25 + docs/ko-kr/more/thanks.md | 21 + docs/ko-kr/plugins/create.md | 937 +++++++++++++++++++ 19 files changed, 2981 insertions(+), 2 deletions(-) create mode 100644 docs/ko-kr/contribute/core.md create mode 100644 docs/ko-kr/contribute/documentation.md create mode 100644 docs/ko-kr/contribute/first-party-plugins.md create mode 100644 docs/ko-kr/contribute/github-actions.md create mode 100644 docs/ko-kr/guide/getting-started.md create mode 100644 docs/ko-kr/guide/introduction.md create mode 100644 docs/ko-kr/index.md create mode 100644 docs/ko-kr/manage/commands.md create mode 100644 docs/ko-kr/manage/configuration.md create mode 100644 docs/ko-kr/manage/core.md create mode 100644 docs/ko-kr/manage/plugins.md create mode 100644 docs/ko-kr/manage/versions.md create mode 100644 docs/ko-kr/more/community-projects.md create mode 100644 docs/ko-kr/more/faq.md create mode 100644 docs/ko-kr/more/thanks.md create mode 100644 docs/ko-kr/plugins/create.md diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 48ef1bac1..534e720e6 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -16,6 +16,14 @@ export default defineConfig({ sidebar: sidebars.en, }, }, + "ko-kr": { + label: "한국어", + lang: "ko-kr", + themeConfig: { + nav: navbars.ko_kr, + sidebar: sidebars.ko_kr, + }, + }, "ja-jp": { label: "日本語", lang: "ja-jp", diff --git a/docs/.vitepress/navbars.ts b/docs/.vitepress/navbars.ts index e2db0b881..5408c232c 100644 --- a/docs/.vitepress/navbars.ts +++ b/docs/.vitepress/navbars.ts @@ -50,6 +50,24 @@ const ja_jp = [ }, ]; +const ko_kr = [ + { text: "가이드", link: "/ko-kr/guide/getting-started" }, + { + text: "참고자료", + link: "/ko-kr/manage/configuration", + }, + { + text: getVersion(), + items: [ + { + text: "변동사항", + link: "https://github.com/asdf-vm/asdf/blob/master/CHANGELOG.md", + }, + { text: "기여하기", link: "/ko-kr/contribute/core" }, + ], + }, +]; + const pt_br = [ { text: "Guia", link: "/pt-br/guide/getting-started" }, { @@ -86,4 +104,4 @@ const zh_hans = [ }, ]; -export { en, ja_jp, pt_br, zh_hans }; +export { en, ko_kr, ja_jp, pt_br, zh_hans }; diff --git a/docs/.vitepress/sidebars.ts b/docs/.vitepress/sidebars.ts index e9afe6539..1366590e9 100644 --- a/docs/.vitepress/sidebars.ts +++ b/docs/.vitepress/sidebars.ts @@ -110,6 +110,118 @@ const en = [ { text: "Thanks", link: "/more/thanks" }, ]; +const ko_kr = [ + { + text: "가이드", + collapsed: false, + items: [ + { text: "asdf이란?", link: "/ko-kr/guide/introduction" }, + { text: "시작하기", link: "/ko-kr/guide/getting-started" }, + ], + }, + { + text: "사용방법", + collapsed: false, + items: [ + { text: "코어", link: "/ko-kr/manage/core" }, + { text: "플러그인", link: "/ko-kr/manage/plugins" }, + { text: "버전", link: "/ko-kr/manage/versions" }, + ], + }, + { + text: "참고자료", + collapsed: false, + items: [ + { text: "설정", link: "/ko-kr/manage/configuration" }, + { text: "모든 명령어", link: "/ko-kr/manage/commands" }, + { + text: "플러그인 Shortname 인덱스", + link: "https://github.com/asdf-vm/asdf-plugins", + }, + ], + }, + { + text: "플러그인", + collapsed: true, + items: [ + { + text: "저자", + items: [ + { text: "플러그인 만들기", link: "/ko-kr/plugins/create" }, + { + text: "GitHub 플러그인 템플릿", + link: "https://github.com/asdf-vm/asdf-plugin-template", + }, + ], + }, + { + text: "공식 플러그인", + items: [ + { + text: "Elixir", + link: "https://github.com/asdf-vm/asdf-elixir", + }, + { + text: "Erlang", + link: "https://github.com/asdf-vm/asdf-erlang", + }, + { + text: "Node.js", + link: "https://github.com/asdf-vm/asdf-nodejs", + }, + { + text: "Ruby", + link: "https://github.com/asdf-vm/asdf-ruby", + }, + ], + }, + { + text: "커뮤니티 플러그인", + items: [ + { + text: "asdf-community", + link: "https://github.com/asdf-community", + }, + { + text: "GitHub 토픽 검색", + link: "https://github.com/topics/asdf-plugin", + }, + ], + }, + ], + }, + { + text: "질문", + collapsed: true, + items: [ + { text: "자주 묻는 질문", link: "/ko-kr/more/faq" }, + { + text: "GitHub 이슈", + link: "https://github.com/asdf-vm/asdf/issues", + }, + { + text: "Stack Overflow 태그", + link: "https://stackoverflow.com/questions/tagged/asdf-vm", + }, + ], + }, + { + text: "기여하기", + collapsed: true, + items: [ + { text: "코어 asdf", link: "/ko-kr/contribute/core" }, + { text: "문서", link: "/ko-kr/contribute/documentation" }, + { + text: "공식 플러그인", + link: "/ko-kr/contribute/first-party-plugins", + }, + { text: "GitHub Actions", link: "/ko-kr/contribute/github-actions" }, + ], + }, + { text: "커뮤니티 프로젝트", link: "/ko-kr/more/community-projects" }, + { text: "감사인사", link: "/ko-kr/more/thanks" }, +]; + const ja_jp = [ { text: "ガイド", @@ -446,4 +558,4 @@ const zh_hans = [ { text: "致谢", link: "/zh-hans/more/thanks" }, ]; -export { en, ja_jp, pt_br, zh_hans }; +export { en, ko_kr, ja_jp, pt_br, zh_hans }; diff --git a/docs/ko-kr/contribute/core.md b/docs/ko-kr/contribute/core.md new file mode 100644 index 000000000..3708a4748 --- /dev/null +++ b/docs/ko-kr/contribute/core.md @@ -0,0 +1,158 @@ +# asdf + +`asdf` 코어 기여 가이드. + +## 초기 설정 + +Github의 `asdf`를 fork하거나 clone하세요: + +```shell +# clone your fork +git clone https://github.com//asdf.git +# or clone asdf +git clone https://github.com/asdf-vm/asdf.git +``` + +코어 개발을 위한 툴들은 이 리포지토리의 `.tool-versions`에 있습니다. 만약 `asdf`가 직접 관리하기를 바라신다면, 다음 플러그인들을 설치하세요: + +```shell +asdf plugin add bats https://github.com/timgluz/asdf-bats.git +asdf plugin add shellcheck https://github.com/luizm/asdf-shellcheck.git +asdf plugin add shfmt https://github.com/luizm/asdf-shfmt.git +``` + +`asdf`를 개발하기 위한 버전들을 설치하세요: + +```shell +asdf install +``` + +로컬 머신에서 개발 도구를 손상시킬 수 있는 기능을 개발 중일 경우 `asdf`를 사용하지 않는 것이 _좋을 수_ 있습니다. 개발 도구들의 원본 목록입니다: + +- [bats-core](https://github.com/bats-core/bats-core): Bash 또는 POSIX 준수 스크립트를 단위 테스트하기 위한 Bash 자동화 테스트 시스템. +- [shellcheck](https://github.com/koalaman/shellcheck): 셸 스크립트 정적 분석 도구. +- [shfmt](https://github.com/mvdan/sh): Bash를 지원하는 셸 parser, formatter, interpreter; shfmt 포함 + +## 개발 + +만약 설치된 `asdf`에 영향 없이 변화들을 테스트해보시고 싶으시다면, `$ASDF_DIR` 변수를 리포지토리를 clone한 경로에 지정하시고, 그 다음 임시로 `bin`와 `shims` 디렉토리들을 경로 앞에 추가하세요. + +원격 리포지토리에 커밋 혹은 push하기 전에, 당신의 코드를 format, lint, 그리고 locally test하세요. 다음 스크립트/명령어들을 사용하세요: + +```shell +# Lint +./scripts/lint.bash --check + +# Fix & Format +./scripts/lint.bash --fix + +# Test: all tests +./scripts/test.bash + +# Test: for specific command +bats test/list_commands.bash +``` + +::: tip + +**테스트 추가!** - 새로운 기능들과 버그 수정들의 리뷰 속도 향상을 위해 테스트들은 **필수적**입니다. 풀 리퀘스트 요청을 만드시기 전에 새로운 코드 경로들을 추가해주세요. [bats-core 문서](https://bats-core.readthedocs.io/en/stable/index.html) 참조 + +::: + +### Gitignore + +다음은 `asdf-vm/asdf` 리포지토리에 `.gitignore` 파일입니다. 우리는 프로젝트에 관련된 특정한 파일들을 무시합니다. 운영체제, 툴, workflows에 관련된 파일들은 글로벌 `.gitignore` 설정에서 무시되어야합니다, [더 보기](http://stratus3d.com/blog/2018/06/03/stop-excluding-editor-temp-files-in-gitignore/). + +@[코드](../../.gitignore) + +### `.git-blame-ignore-revs` + +`asdf`는 `.git-blame-ignore-revs` 사용해 blame 실행에서 잡음을 줄입니다. 더 많은 정보 [git blame 문서](https://git-scm.com/docs/git-blame). + +다음과 같이 `git blame`과 `.git-blame-ignore-revs`을 사용: + +```sh +git blame --ignore-revs-file .git-blame-ignore-revs ./test/install_command.bats +``` + +선택적으로, 수동적으로 파일을 제공하는 대신 모든 `blame`에서 해당 파일을 사용하도록 설정: + +```sh +git config blame.ignoreRevsFile .git-blame-ignore-revs +``` + +IDE들에서 이 파일을 사용하도록 설정할 수 있습니다. 예를 들어, VSCode를 사용하실 경우 ([GitLens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens)와 함께), 다음을 `.vscode/settings.json`에 추가하세요: + +```json +{ + "gitlens.advanced.blame.customArguments": [ + "--ignore-revs-file", + ".git-blame-ignore-revs" + ] +} +``` + +## Bats 테스팅 + +로컬 테스트 실행: + +```shell +./scripts/test.bash +``` + +테스트 작성 전 **반드시 읽기**: + +- `test/`에 존재하는 테스트들 +- [bats-core 문서](https://bats-core.readthedocs.io/en/stable/index.html) +- `scripts/test.bash`에 존재하는 Bats 설정들 + +### Bats 팁 + +Bats 디버깅은 때에 따라 어려울 수 있습니다. 디버깅 단순화를 위해, `-t` flag로 TAP output을 사용하여 테스트 실행 중 결과물 출력을 위한 특별한 파일 디스크립터 `>&3`를 사용할 수 있습니다. 예시: + +```shell +# test/some_tests.bats + +printf "%s\n" "Will not be printed during bats test/some_tests.bats" +printf "%s\n" "Will be printed during bats -t test/some_tests.bats" >&3 +``` + +bats-core의 더 자세한 문서 [Printing to the Terminal](https://bats-core.readthedocs.io/en/stable/writing-tests.html#printing-to-the-terminal). + +## 풀 리퀘스트, 릴리스 & 관습적 커밋 + +`asdf`는 자동화 배포 툴 [Release Please](https://github.com/googleapis/release-please)를 사용하여 자동으로 [SemVer](https://semver.org/) 버전을 올리고 [변동사항](https://github.com/asdf-vm/asdf/blob/master/CHANGELOG.md)을 작성합니다. 이 정보들은 지난 배포들로부터 커밋 history를 읽음으로써 결정됩니다. + +[유의적 커밋 메세지](https://www.conventionalcommits.org/)는 기본 브랜치의 커밋 메세지 형식이 되는 풀 리퀘스트 제목의 형식을 정의합니다. 이것은 GitHub Action에서 강제됩니다 [`amannn/action-semantic-pull-request`](https://github.com/amannn/action-semantic-pull-request). + +관습적인 커밋 다음 형식을 따릅니다: + +``` +[optional scope][optional !]: + + +fix: some fix +feat: a new feature +docs: some documentation update +docs(website): some change for the website +feat!: feature with breaking change +``` + +``의 모든 목록: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`. + +- `!`: 주요한(breaking) 변화들을 나타냅니다 +- `fix`: 새로운 SemVer `patch`을 만듭니다 +- `feat`: 새로운 SemVer `minor`을 만듭니다 +- `!`: 새로운 SemVer `major`을 만듭니다 + +풀 리퀘스트 제목은 반드시 이 형식을 따라야 합니다. + +::: tip + +풀 리퀘스트 제목을 관습적 커밋 메세지 형식을 사용하세요. + +::: + +## Docker 이미지 + +[asdf-alpine](https://github.com/vic/asdf-alpine)와 [asdf-ubuntu](https://github.com/vic/asdf-ubuntu) 프로젝트들은 asdf 툴들의 Dockerized 이미지들을 제공하기 위해 진행되고있습니다. 개발 서버의 베이스 혹은 프로덕션 앱들을 위해 docker 이미지들을 사용할 수 있습니다. diff --git a/docs/ko-kr/contribute/documentation.md b/docs/ko-kr/contribute/documentation.md new file mode 100644 index 000000000..88527a5e7 --- /dev/null +++ b/docs/ko-kr/contribute/documentation.md @@ -0,0 +1,132 @@ +# 문서 & 사이트 + +문서 & 사이트 기여 가이드. + +## 초기 세팅 + +Github의 `asdf` fork 그리고/혹은 기본 브랜치 Git clone: + +```shell +# clone your fork +git clone https://github.com//asdf.git +# or clone asdf +git clone https://github.com/asdf-vm/asdf.git +``` + +문서 사이트 개발을 위한 도구들은 `asdf`의 `docs/.tool-versions`에서 관리되고 있습니다. 플러그인들을 추가하기: + +```shell +asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs +``` + +툴 버전들을 설치하기: + +```shell +asdf install +``` + +- [Node.js](https://nodejs.org): Chrome의 V8 JavaScript 엔진을 기반으로 구축된 JavaScript 런타임. + +`docs/package.json`로부터 Node.js dependencies 설치하기: + +```shell +npm install +``` + +## 개발 + +[VitePress (v2)](https://vitepress.dev/)는 우리가 asdf 문서 사이트를 빌드하기 위해 사용하는 정적 사이트 생성기(SSG)입니다. 이는 사용자가 JavaScript를 사용중이지 않을때도 HTML 폴백을 지원하고, [Docsify.js](https://docsify.js.org/)와 결과적으로 VuePress를 대체하기 위해 선택되었습니다. 이는 VuePress로부터 대체된 Docsify & VitePress가 아니면 불가능했을 것입니다. 이것을 제외하면, 최소한의 설정과 함께 마크다운 작성에 집중하는 feature-set은 대부분 비슷합니다. + +`package.json`은 개발에 필요한 스크립트들을 포함합니다: + +@[code json{3-5}](../../package.json) + +로컬 개발 서버 시작하기: + +```shell +npm run dev +``` + +커밋 전 코드 형식 맞추기: + +```shell +npm run format +``` + +## 풀 리퀘스트, 릴리스 & 관습적 커밋 + +`asdf`는 PR 제목들의 관습적인 커밋들에 의존하는 자동화된 배포 pipeline을 사용하고 있습니다. 더 자세한 문서는 [코어 기여 가이드](./core.md)에서 찾을 수 있습니다. + +문서 업데이트를 위한 PR을 만드실때는, PR `docs: ` 형식인 관습적인 커밋 타입 `docs` 제목을 만들어주세요. + +## Vitepress + +사이트의 설정은 설정을 대표하는 JS 오브젝트의 TypeScript 파일들로 구성되어 있습니다. 그 파일들은 다음과 같습니다: + +- `docs/.vitepress/config.js`: 사이트를 위한 root 설정 파일. [VitePress 문서](https://vitepress.dev/reference/site-config) 참조. + +root 설정 단순화를 위해, _navbar_ 와 _sidebar_ 를 대표하는 더 큰 JS 객체가 추출되었고 로케일로 구분되었습니다. 다음을 참조하세요: + +- `docs/.vitepress/navbars.js` +- `docs/.vitepress/sidebars.js` + +[기본 테마 참고자료](https://vitepress.dev/reference/default-theme-config)에서 위 설정들의 공식 문서를 보실 수 있습니다. + +## I18n + +VitePress는 국제화를 공식적으로 지원합니다. +root 설정 `docs/.vitepress/config.js`는 선택 dropdown에서의 지원되는 로케일들의 URL, 제목과 navbar/sidebar의 설정 레퍼런스들을 정의합니다. + +navbar/sidebar 설정들은 앞서 언급한 로케일 별로 나누어지고 내보내기된 설정파일들에 의해 결정됩니다. + +각 로케일을 위한 Markdown 내용은 반드시 root 설정안에 `locales`의 키들과 같은 이름의 폴더에 위치해야합니다. 다시 말해서: + +```js +// docs/.vitepress/config.js +export default defineConfig({ + ... + locales: { + root: { + label: "English", + lang: "en-US", + themeConfig: { + nav: navbars.en, + sidebar: sidebars.en, + }, + }, + "pt-br": { + label: "Brazilian Portuguese", + lang: "pr-br", + themeConfig: { + nav: navbars.pt_br, + sidebar: sidebars.pt_br, + }, + }, + "zh-hans": { + label: "简体中文", + lang: "zh-hans", + themeConfig: { + nav: navbars.zh_hans, + sidebar: sidebars.zh_hans, + }, + }, + }, +}) +``` + +`/pt-BR/`는 `docs/pt-BR/`에 위치한 Markdown 파일들의 세트가 똑같이 필요합니다, 예를 들어: + +```shell +docs +├─ README.md +├─ foo.md +├─ nested +│ └─ README.md +└─ pt-BR + ├─ README.md + ├─ foo.md + └─ nested + └─ README.md +``` + +더 자세한 정보는 [공식 VitePress i18n 문서](https://vitepress.dev/guide/i18n)에서 확인 가능합니다. diff --git a/docs/ko-kr/contribute/first-party-plugins.md b/docs/ko-kr/contribute/first-party-plugins.md new file mode 100644 index 000000000..90eba879c --- /dev/null +++ b/docs/ko-kr/contribute/first-party-plugins.md @@ -0,0 +1,14 @@ +# 공식 플러그인 + +asdf 코어 팀은 일상 업무 환경에서 사용되는 플러그인들을 작성해왔습니다. 이 플러그인들을 관리하고 발전시키는 도움은 언제든 환영입니다. 아래 각 링크들에서 관련된 리포지토리들을 확인하세요: + +- [Elixir](https://github.com/asdf-vm/asdf-elixir) +- [Erlang](https://github.com/asdf-vm/asdf-erlang) +- [Node.js](https://github.com/asdf-vm/asdf-nodejs) +- [Ruby](https://github.com/asdf-vm/asdf-ruby) + +커뮤니티 플러그인 보기: + +- [`asdf-community` 공동체](https://github.com/asdf-community): `asdf` 플러그인의 장기 유지보수를 위한 공동체 주도의 프로젝트입니다. +- [`asdf-plugins` shortname 리포지토리](https://github.com/asdf-vm/asdf-plugins): 인기 있는 `asdf` 플러그인 검색을 위해 `asdf` 코어가 사용하는 Short-name 목록. +- [Github `asdf-plugin` 토픽 검색](https://github.com/topics/asdf-plugin) diff --git a/docs/ko-kr/contribute/github-actions.md b/docs/ko-kr/contribute/github-actions.md new file mode 100644 index 000000000..c43e0b212 --- /dev/null +++ b/docs/ko-kr/contribute/github-actions.md @@ -0,0 +1,3 @@ +# GitHub Actions + +당신의 관심에 감사드리며, 존재하는 이슈들, 대화들, 그리고 기여 가이드라인을 [asdf actions 리포지토리](https://github.com/asdf-vm/actions)에서 확인 해주세요. diff --git a/docs/ko-kr/guide/getting-started.md b/docs/ko-kr/guide/getting-started.md new file mode 100644 index 000000000..93b296708 --- /dev/null +++ b/docs/ko-kr/guide/getting-started.md @@ -0,0 +1,475 @@ +# 시작하기 + +`asdf` 설치는 다음과 같습니다: + +1. dependencies 설치 +2. `asdf` 코어 다운로드 +3. `asdf` 설치 +4. 관리하고 싶은 각각의 툴/런타임 플러그인 설치 +5. 툴/런타임 버전 설치 +6. `.tool-versions` 설정 파일들을 통해 글로벌 혹은 프로젝트 버전들 설정 + +## 1. Dependencies 설치 + +asdf는 `git` & `curl`이 필요합니다. _당신이_ 필요한 패키지 매니저를 구동하기 위한 _일부_ 명령어들의 목록입니다. (몇몇은 나중 단계에서 자동으로 설치될 수 있습니다). + +| 운영체제 | 패키지 매니저 | 명령어 | +| -------- | ------------- | ---------------------------------- | +| linux | Aptitude | `apt install curl git` | +| linux | DNF | `dnf install curl git` | +| linux | Pacman | `pacman -S curl git` | +| linux | Zypper | `zypper install curl git` | +| macOS | Homebrew | `brew install coreutils curl git` | +| macOS | Spack | `spack install coreutils curl git` | + +::: tip 노트 + +시스템 설정에 의해 `sudo`가 필요할 수 있습니다. + +::: + +## 2. asdf 다운로드 + +### 공식 다운로드 + + + + +```shell +git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.0 + +``` + + + +### 커뮤니티 지원 다운로드 방법 + +공식 `git` 방식을 사용할 것을 적극적으로 권장드립니다. + +| 방법 | 명령어 | +| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Homebrew | `brew install asdf` | +| Pacman | `git clone https://aur.archlinux.org/asdf-vm.git && cd asdf-vm && makepkg -si` 혹은 선호하시는 [AUR helper](https://wiki.archlinux.org/index.php/AUR_helpers) 사용 | + +## 3. asdf 설치 + +설정에 영향을 미치는 다양한 셸, 운영체제들 & 설치방법의 조합들이 있습니다. 아래 선택사항들 중 가장 적합한 것을 사용하세요. + +**macOS 사용자들은 이 섹션 마지막 부분에 `path_helper`에 경고를 반드시 읽어보세요.** + +::: details Bash & Git + +다음을 `~/.bashrc`에 추가하세요: + +```shell +. "$HOME/.asdf/asdf.sh" +``` + +자동완성 설정은 다음을 `.bashrc`에 추가하세요: + +```shell +. "$HOME/.asdf/completions/asdf.bash" +``` + +::: + +::: details Bash & Git (macOS) + +**macOS Catalina 혹은 그 이상**을 사용하신다면, 기본 셸이 **ZSH**로 변경되었습니다. Bash로 다시 변경하지 않으셨다면, ZSH의 설치방법을 따라주세요. + +다음을 `~/.bash_profile`에 추가하세요: + +```shell +. "$HOME/.asdf/asdf.sh" +``` + +자동완성 설정은 다음을 `.bash_profile`에 직접 추가하세요: + +```shell +. "$HOME/.asdf/completions/asdf.bash" +``` + +::: + +::: details Bash & Homebrew + +`~/.bashrc`에 `asdf.sh`를 추가하세요: + +```shell +echo -e "\n. \"$(brew --prefix asdf)/libexec/asdf.sh\"" >> ~/.bashrc +``` + +자동완성은 [Homebrew'의 방법에 따라 설정되어야 합니다](https://docs.brew.sh/Shell-Completion#configuring-completions-in-bash) 혹은 다음을 이용하세요: + +```shell +echo -e "\n. \"$(brew --prefix asdf)/etc/bash_completion.d/asdf.bash\"" >> ~/.bashrc +``` + +::: + +::: details Bash & Homebrew (macOS) + +**macOS Catalina 혹은 그 이상**을 사용하신다면, 기본 셸이 **ZSH**로 변경되었습니다. Bash로 다시 변경하지 않으셨다면, ZSH의 설치방법을 따라주세요. + +`~/.bash_profile`에 `asdf.sh` 추가하기: + +```shell +echo -e "\n. \"$(brew --prefix asdf)/libexec/asdf.sh\"" >> ~/.bash_profile +``` + +자동완성은 [Homebrew'의 방법에 따라 설정되어야 합니다](https://docs.brew.sh/Shell-Completion#configuring-completions-in-bash) 혹은 다음을 이용하세요: + +```shell +echo -e "\n. \"$(brew --prefix asdf)/etc/bash_completion.d/asdf.bash\"" >> ~/.bash_profile +``` + +::: + +::: details Bash & Pacman + +다음을 `~/.bashrc`에 추가하세요: + +```shell +. /opt/asdf-vm/asdf.sh +``` + +자동완성을 위해 [`bash-completion`](https://wiki.archlinux.org/title/bash#Common_programs_and_options)이 설치 되어야합니다. +::: + +::: details Fish & Git + +다음을 `~/.config/fish/config.fish`에 추가하세요: + +```shell +source ~/.asdf/asdf.fish +``` + +다음 명령어로 자동완성을 설정하세요: + +```shell +mkdir -p ~/.config/fish/completions; and ln -s ~/.asdf/completions/asdf.fish ~/.config/fish/completions +``` + +::: + +::: details Fish & Homebrew + +`~/.config/fish/config.fish`에 `asdf.fish`를 추가하세요: + +```shell +echo -e "\nsource "(brew --prefix asdf)"/libexec/asdf.fish" >> ~/.config/fish/config.fish +``` + +자동완성은 [Fish 셸 Homebrew에 의해 관리됩니다](https://docs.brew.sh/Shell-Completion#configuring-completions-in-fish). 편하죠! +::: + +::: details Fish & Pacman + +다음을 `~/.config/fish/config.fish`에 추가하세요: + +```shell +source /opt/asdf-vm/asdf.fish +``` + +자동완성은 AUR 패키지를 통한 설치로 자동적으로 설정됩니다. +::: + +::: details Elvish & Git + +`~/.config/elvish/rc.elv`에 `asdf.elv`를 추가하세요: + +```shell +mkdir -p ~/.config/elvish/lib; ln -s ~/.asdf/asdf.elv ~/.config/elvish/lib/asdf.elv +echo "\n"'use asdf _asdf; var asdf~ = $_asdf:asdf~' >> ~/.config/elvish/rc.elv +echo "\n"'set edit:completion:arg-completer[asdf] = $_asdf:arg-completer~' >> ~/.config/elvish/rc.elv +``` + +자동완성은 자동적으로 설정됩니다. + +::: + +::: details Elvish & Homebrew + +Add `asdf.elv` to your `~/.config/elvish/rc.elv` with: + +```shell +mkdir -p ~/.config/elvish/lib; ln -s (brew --prefix asdf)/libexec/asdf.elv ~/.config/elvish/lib/asdf.elv +echo "\n"'use asdf _asdf; var asdf~ = $_asdf:asdf~' >> ~/.config/elvish/rc.elv +echo "\n"'set edit:completion:arg-completer[asdf] = $_asdf:arg-completer~' >> ~/.config/elvish/rc.elv +``` + +자동완성은 자동적으로 설정됩니다. +::: + +::: details Elvish & Pacman + +`~/.config/elvish/rc.elv`에 `asdf.elv`를 추가하세요: + +```shell +mkdir -p ~/.config/elvish/lib; ln -s /opt/asdf-vm/asdf.elv ~/.config/elvish/lib/asdf.elv +echo "\n"'use asdf _asdf; var asdf~ = $_asdf:asdf~' >> ~/.config/elvish/rc.elv +echo "\n"'set edit:completion:arg-completer[asdf] = $_asdf:arg-completer~' >> ~/.config/elvish/rc.elv +``` + +자동완성은 자동적으로 설정됩니다. +::: + +::: details ZSH & Git + +다음을 `~/.zshrc`에 추가하세요: + +```shell +. "$HOME/.asdf/asdf.sh" +``` + +**혹은** 위 스크립트와 자동완성을 설정하는 [asdf를 위한 oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/asdf)와 같은 ZSH 프레임워크 플러그인을 사용하세요. + +자동완성은 ZSH 프레임워크 `asdf` 플러그인 혹은 다음을 `.zshrc`에 추가함으로써 설정됩니다: + +```shell +# append completions to fpath +fpath=(${ASDF_DIR}/completions $fpath) +# initialise completions with ZSH's compinit +autoload -Uz compinit && compinit +``` + +- 만약 custom `compinit` 설정을 사용중이라면, `asdf.sh`를 source하고 난 다음 `compinit`가 오도록 해주세요 +- 만약 ZSH 프레임워크를 통해 custom `compinit` 설정을 사용중이라면, 해당 프레임워크를 source하고 난 다음 `compinit`가 오도록 해주세요 + +**경고** + +만약 ZSH 프레임워크를 사용중이라면, `fpath`를 통해 새로운 ZSH 자동완성을 사용하려면 관련된 `asdf` 플러그인이 업데이트 되어야합니다. Oh-My-ZSH asdf 플로그인이 아직 업데이트 되지 않았습니다, [ohmyzsh/ohmyzsh#8837](https://github.com/ohmyzsh/ohmyzsh/pull/8837) 참고. +::: + +::: details ZSH & Homebrew + +`~/.zshrc`에 `asdf.sh`를 추가하세요: + +```shell +echo -e "\n. $(brew --prefix asdf)/libexec/asdf.sh" >> ${ZDOTDIR:-~}/.zshrc +``` + +**혹은** 위 스크립트와 자동완성을 설정하는 [asdf를 위한 oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/asdf)와 같은 ZSH 프레임워크 플러그인을 사용하세요. + +자동완성은 `asdf` ZSH 프레임워크 혹은 [Homebrew'의 방법](https://docs.brew.sh/Shell-Completion#configuring-completions-in-zsh)에 따라 설정되어야 합니다. 만약 ZSH 프레임워크를 사용중이라면, `fpath`를 통해 새로운 ZSH 자동완성을 사용하려면 관련된 asdf 플러그인이 업데이트 되어야합니다. Oh-My-ZSH asdf 플로그인이 아직 업데이트 되지 않았습니다, [ohmyzsh/ohmyzsh#8837](https://github.com/ohmyzsh/ohmyzsh/pull/8837) 참고. +::: + +::: details ZSH & Pacman + +다음을 `~/.zshrc`에 추가하세요: + +```shell +. /opt/asdf-vm/asdf.sh +``` + +자동완성은 ZSH 친화적인 위치에 있지만, [ZSH는 자동완성 사용을 위해 반드시 설정 되어야합니다](https://wiki.archlinux.org/index.php/zsh#Command_completion). +::: + +::: details PowerShell Core & Git + +다음을 `~/.config/powershell/profile.ps1`에 추가하세요: + +```shell +. "$HOME/.asdf/asdf.ps1" +``` + +::: + +::: details PowerShell Core & Homebrew + +`~/.config/powershell/profile.ps1`에 `asdf.sh`를 추가하세요: + +```shell +echo -e "\n. \"$(brew --prefix asdf)/libexec/asdf.ps1\"" >> ~/.config/powershell/profile.ps1 +``` + +::: + +::: details PowerShell Core & Pacman + +다음을 `~/.config/powershell/profile.ps1`에 추가하세요: + +```shell +. /opt/asdf-vm/asdf.ps1 +``` + +::: + +::: details Nushell & Git + +`~/.config/nushell/config.nu`에 `asdf.nu`를 추가하세요: + +```shell +"\n$env.ASDF_DIR = ($env.HOME | path join '.asdf')\n source " + ($env.HOME | path join '.asdf/asdf.nu') | save --append $nu.config-path +``` + +자동완성은 자동적으로 설정됩니다. +::: + +::: details Nushell & Homebrew + +`~/.config/nushell/config.nu`에 `asdf.nu`를 추가하세요: + +```shell +"\n$env.ASDF_DIR = (brew --prefix asdf | str trim | into string | path join 'libexec')\n source " + (brew --prefix asdf | str trim | into string | path join 'libexec/asdf.nu') | save --append $nu.config-path +``` + +자동완성은 자동적으로 설정됩니다. +::: + +::: details Nushell & Pacman + +`~/.config/nushell/config.nu`에 `asdf.nu`를 추가하세요: + +```shell +"\n$env.ASDF_DIR = '/opt/asdf-vm/'\n source /opt/asdf-vm/asdf.nu" | save --append $nu.config-path +``` + +자동완성은 자동적으로 설정됩니다. +::: + +::: details POSIX Shell & Git + +다음을 `~/.profile`에 추가하세요: + +```shell +export ASDF_DIR="$HOME/.asdf" +. "$HOME/.asdf/asdf.sh" +``` + +::: + +::: details POSIX Shell & Homebrew + +`~/.profile`에 `asdf.sh`를 추가하세요: + +```shell +echo -e "\nexport ASDF_DIR=\"$(brew --prefix asdf)/libexec/asdf.sh\"" >> ~/.profile +echo -e "\n. \"$(brew --prefix asdf)/libexec/asdf.sh\"" >> ~/.profile +``` + +::: + +::: details POSIX Shell & Pacman + +다음을 `~/.profile`에 추가하세요: + +```shell +export ASDF_DIR="/opt/asdf-vm" +. /opt/asdf-vm/asdf.sh +``` + +::: + +`asdf` 스크립트들은 `$PATH` 설정한 **이후에** 프레임워크 (oh-my-zsh 등) source **이후에** source 되어야 합니다. + +::: 경고 +macOS에서, Bash 혹은 Zsh 셸 시작시에 자동적으로 `path_helper` 유틸리티를 실행시킵니다. `path_helper`는 `PATH` (와 `MANPATH`)에 항목들을 재배열 시켜 특정 순서를 요구하는 툴들의 일관된 동작을 방해합니다. 이를 방지하기 위해, macOS에서 `asdf`는 `PATH` 앞부분에 (가장 높은 우선순위) 강제로 추가합니다. 이는 `ASDF_FORCE_PREPEND`를 통해 변경가능합니다. +::: + +`PATH` 업데이트를 위해 셸을 재시작하세요. 새로운 터미널을 여는 경우 대부분 해결됩니다. + +## 코어 설치 완료! + +`asdf` 코어 설치를 완료했습니다 :tada: + +`asdf`는 **플러그인**과 **툴**을 설치하고, **버전**들을 관리해야 유용합니다. 설치 및 관리방법을 이 가이드 아래에서 계속해서 배우세요. + +## 4. 플러그인 설치 + +데모 목적으로 우리는 [`asdf-nodejs`](https://github.com/asdf-vm/asdf-nodejs/) 플러그인을 통해 [Node.js](https://nodejs.org/) 설치 & 설정을 해보겠습니다. + +### 플러그인 Dependencies + +각 플러그인은 dependencies 갖고 있어 우리는 플러그인 리포지토리의 목록을 확인해야합니다. `asdf-nodejs`는 다음을 가지고 있습니다: + +| OS | Dependency 설치 | +| ------------------------------ | --------------------------------------- | +| Debian | `apt-get install dirmngr gpg curl gawk` | +| CentOS/ Rocky Linux/ AlmaLinux | `yum install gnupg2 curl gawk` | +| macOS | `brew install gpg gawk` | + +우리는 어떤 플러그인들은 설치-후 훅들을 갖고있어 dependencies 먼저 설치해야합니다. + +### 플러그인 설치 + +```shell +asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git +``` + +## 5. 버전 설치 + +이제 우리는 Node.js를 위한 플러그인을 갖고있어 툴 버전을 설치할 수 있습니다. + +우리는 `asdf list all nodejs`를 통해 어떤 버전들이 이용가능한지 혹은 `asdf list all nodejs 14`를 통해 하위 버전들을 확인가능합니다. + +우리는 이용가능한 `latest` 버전을 설치할 것입니다. + +```shell +asdf install nodejs latest +``` + +::: tip 노트 +`asdf`는 정확한 버전들을 강제합니다. `latest`는 `asdf`가 실행했을때 실제 버전을 찾는 헬퍼입니다. +::: + +## 6. 버전 설정 + +`asdf`는 현재 작업 디렉토리부터 `$HOME` 디렉토리까지 모든 `.tool-versions` 파일들에서 버전 검색을 수행합니다. 검색은 `asdf`가 관리하는 툴을 실행시킬때 맞춰서 실행됩니다. + +::: 경고 +툴 실행을 위한 툴 버전을 설정하지 않으면 **에러**가 발생합니다. `asdf current`는 현재 디렉토리로부터 툴 & 버전을 표시함으로써 어떤 툴들이 실행을 실패하는지 관찰할 수 있게합니다. +::: + +### 글로벌 + +글로벌 기본값들은 `$HOME/.tool-versions`에서 관리됩니다. 글로벌 버전을 다음을 이용해 설정하세요: + +```shell +asdf global nodejs latest +``` + + +`$HOME/.tool-versions`은 다음과 같습니다: + +``` +nodejs 16.5.0 +``` + +어떤 운영체제들은 `asdf`가 아닌 시스템에 의해 관리되는 툴들이 이미 설치되어 있습니다, `python`이 대표적인 예시입니다. 당신은 시스템에 의한 툴 관리를 위해 `asdf`를 설정해야합니다. [버전 참조 섹션](/ko-kr/manage/versions.md)를 참고하세요. + +### 로컬 + +로컬 버전들은 (현재 작업 디렉토리) `$PWD/.tool-versions` 파일에 정의 되어 있습니다. 보통, 이 디렉토리는 하나의 프로젝트의 Git 리포지토리입니다. 툴 버전을 설정하고 싶은 디렉토리에서 다음을 실행시키세요: + +```shell +asdf local nodejs latest +``` + +`$PWD/.tool-versions`은 다음과 같습니다: + +``` +nodejs 16.5.0 +``` + +### 기존의 툴 버전 파일들 사용하기 + +`asdf`는 기존의 다른 버전 매니저들의 버전 파일들 마이그레이션을 지원합니다. 예시: `rbenv`의 `.ruby-version`. 이는 각 플러그인 기준으로 지원됩니다. + +[`asdf-nodejs`](https://github.com/asdf-vm/asdf-nodejs/)는 `.nvmrc`와 `.node-version` 파일들을 지원합니다. 이를 활성화하기 위해, 다음을 `asdf` 설정 파일 `$HOME/.asdfrc`에 추가하세요: + +``` +legacy_version_file = yes +``` + +더 많은 설정 옵션들은 [configuration](/ko-kr/manage/configuration.md) 페이지를 참고하세요. + +## 가이드 끝! + +`asdf` 시작하기 가이드가 끝났습니다. :tada: 당신은 이제 당신의 프로젝트의 `nodejs` 버전들을 관리할 수 있습니다. 같은 방법으로 다른 각각의 툴들의 버전을 관리하세요! + +`asdf`는 우리가 익숙해져야하는 더 많은 명령어들을 가지고 있고, `asdf --help` 혹은 `asdf`를 통해 확인할 수 있습니다. 명령어들의 코어의 3가지 카테고리로 나눠질 수 있습니다: + +- [코어 `asdf`](/ko-kr/manage/core.md) +- [플러그인](/ko-kr/manage/plugins.md) +- [툴 버전](/ko-kr/manage/versions.md) diff --git a/docs/ko-kr/guide/introduction.md b/docs/ko-kr/guide/introduction.md new file mode 100644 index 000000000..e2e795c18 --- /dev/null +++ b/docs/ko-kr/guide/introduction.md @@ -0,0 +1,57 @@ +# 소개 + +`asdf`는 툴 버전 매니저입니다. 모든 툴 버전 정의들은 당신의 팀들과 공유되는 프로젝트의 Git 리포지토리에서 확인할 수 있는 하나의 (`.tool-versions`) 파일에 있으며, 모든 사람들이 **정확히** 같은 버전의 툴들을 사용하게 합니다. + +기존의 작업 방식은 여러 CLI 버전 매니저들, 각각의 고유한 API, 설정 파일들 그리고 구현이 필요했었습니다 (e.g. `$PATH` 조정, shims, 환경 변수 등...). `asdf`는 개발 워크플로우 단순화를 위해 단 하나의 인터페이스와 설정파일을 제공하고 단순한 플러그인 인터페이스를 통해 모든 툴과 런타임들 확장가능합니다. + +## 작동방식 + +`asdf` 코어가 셸 설정과 함께 설치되면, 플러그인들이 특정 툴들을 관리하기 위해 설치됩니다. 플러그인에 의해 한가지 툴이 설치되면, [shims]()들을 가진 실행파일들이 각각의 툴들을 위해 생성됩니다. 실행파일들을 실행하려 할 때, `.tool-versions`에 설정된 툴의 버전을 통해 `asdf`가 어떤 버전을 실행시킬 지 결정하고 해당 shim이 대신 실행됩니다. + +## 관련된 프로젝트 + +### nvm / n / rbenv 등 + +[nvm](https://github.com/nvm-sh/nvm), [n](https://github.com/tj/n) 그리고 [rbenv](https://github.com/rbenv/rbenv)과 같은 툴들은 설치된 실행파일을 위한 shim들을 만드는 셸 스크립트들로 작성되어 있습니다. + +`asdf`는 매우 비슷하고 툴/런타임 버전 관리의 영역에서 경쟁하기 위해 만들어졌습니다. `asdf`의 차별화 요소는 플러그인 시스템이 툴/런타임 별 매니저의 필요성, 각기 다른 명령어들, 그리고 리포지토리에 각각 `*-version` 파일들을 제거하였다는 것입니다. + + + +### direnv + +> 현재 디렉토리에 따라 환경 변수들을 load와 unload 할 수 있는 새로운 기능을 기존의 셸에 추가합니다. + +`asdf`는 환경 변수들을 관리하지 않습니다만, [`asdf-direnv`](https://github.com/asdf-community/asdf-direnv) 플러그인을 통해 direnv 동작를 `asdf`에 통합할 수 있습니다. + +[direnv 문서](https://direnv.net/)에서 더보기. + +### Homebrew + +> macOS (혹은 Linux)에서의 패키지 매니저 부재 + +Homebrew는 패키지들과 upstream dependencies들을 관리합니다. `asdf`는 upstream dependencies들을 관리하지 않고, 패키지 매니저가 아니고, 우리가 dependency 목록들을 작게 유지하므로, 사용자가 직접 관리해야합니다. + +[Homebrew 문서](https://brew.sh/)에서 더보기. + +### NixOS + +> Nix는 패키지 관리와 시스템 설정에 창의적으로 접근하는 툴입니다. + +NixOS는, `asdf`가 제공하지 않는, 각 툴의 전체 dependency tree를 통해 패키지들의 정확한 버전들을 관리함으로써 재현가능한 환경 구축을 목표로 합니다. NixOS는 자신만의 프로그래밍 언어, 많은 CLI 툴들, 그리고 6000개가 넘는 패키지 컬렉션을 통해 해당 기능을 제공합니다. + +다시 한번 말씀드리지만, `asdf`는 upstream dependencies들을 관리하지 않으며 패키지 매니저가 아닙니다. + +[NixOS 문서](https://nixos.org/guides/how-nix-works.html)에서 더보기. + +## 왜 asdf를 사용할까요? + +`asdf`는 팀들이 플러그인 시스템을 통해 **다양한** 툴들의 지원 그리고 셸 설정에 포함시킬 하나의 **셸** 스크립트의 _단순함_ 과 _친숙성_ 을 통해 **정확히** 같은 버전의 툴들을 사용하는 것을 보장합니다. + +::: tip 노트 +`asdf`는 시스템 패키지 매니저가 아닙니다. 이것은 툴 버전 매니저입니다. 단지 어떠한 툴을 위한 플러그인을 생성하고 그것의 버전을 `asdf`로 관리할 수 있다고 해서, 그 특정한 툴을 버전 관리를 위한 최선의 방법을 의미하는 것은 아닙니다. +::: diff --git a/docs/ko-kr/index.md b/docs/ko-kr/index.md new file mode 100644 index 000000000..6a28e6c7b --- /dev/null +++ b/docs/ko-kr/index.md @@ -0,0 +1,40 @@ +--- +# https://vitepress.dev/reference/default-theme-home-page +layout: home + +hero: + name: asdf + text: 다중 런타임 버전 매니저 + tagline: 한가지 툴로 모든 런타임 버전들을 관리하세요! + actions: + - theme: brand + text: 시작하기 + link: /ko-kr/guide/getting-started + - theme: alt + text: asdf이란? + link: /ko-kr/guide/introduction + - theme: alt + text: GitHub에서 보기 + link: https://github.com/asdf-vm/asdf + +features: + - title: "단 한가지 도구" + details: "각 프로젝트 런타임들을 단 한가지 CLI 툴과 커맨드 인터페이스로 관리." + icon: 🎉 + - title: "플러그인" + details: "런타임과 툴들의 거대한 생태계. 당신이 필요한 새로운 툴들을 더해주는 간단한 API!" + icon: 🔌 + - title: "구버전 호환" + details: "원활한 마이그레이션을 위해 이미 존재하던 .nvmrc, .node-version, .ruby-version 등의 설정 파일들 지원!" + icon: ⏮ + - title: "단 하나의 설정 파일" + details: "단 하나의 공유된 .tool-versions 파일로 모든 툴, 런타임, 그리고 버전들을 관리." + icon: 📄 + - title: "셸" + details: "Bash, ZSH, Fish & Elvish 자동완성 기능 지원." + icon: 🐚 + - title: "GitHub Actions" + details: "GitHub Action 설치 제공과 .tool-versions 파일을 CI/CD 워크플로우에서 활용." + icon: 🤖 + +--- diff --git a/docs/ko-kr/manage/commands.md b/docs/ko-kr/manage/commands.md new file mode 100644 index 000000000..33c23a85a --- /dev/null +++ b/docs/ko-kr/manage/commands.md @@ -0,0 +1,5 @@ +# 모든 명령어 + +다음 목록은 `asdf`에서 이용가능한 모든 명령어들입니다. 해당 목록은 `asdf help` 명령어를 통해 확인가능합니다. + +<<< @../../help.txt diff --git a/docs/ko-kr/manage/configuration.md b/docs/ko-kr/manage/configuration.md new file mode 100644 index 000000000..87e86ed0f --- /dev/null +++ b/docs/ko-kr/manage/configuration.md @@ -0,0 +1,261 @@ +# 설정 + +`asdf`의 설정은 공유가능한 `.tool-versions` 파일들 뿐만 아니라 `.asdfrc`를 통한 특정한 사용자 맞춤화 및 환경 변수들을 모두 포함합니다. + +## `.tool-versions` + +한 디렉토리에 `.tool-versions` 파일이 존재하면, 해당 파일에 정의된 툴 버전들은 해당 디렉토리와 모든 하위 디렉토리에서 사용됩니다. + +::: warning 노트 + +글로벌 기본값들은 `$HOME/.tool-versions` 파일에 설정 가능합니다 + +::: + +`.tool-versions` 파일의 형태는 다음과 같습니다: + +``` +ruby 2.5.3 +nodejs 10.15.0 +``` + +다음과 같이 주석을 넣을 수 있습니다: + +``` +ruby 2.5.3 # This is a comment +# This is another comment +nodejs 10.15.0 +``` + +버전들은 다음과 같은 형식일 수 있습니다: + +- `10.15.0` - 실제 버전. 바이너리 다운로드를 지원하는 플러그인은 바이너리를 다운로드합니다. +- `ref:v1.0.2-a` 혹은 `ref:39cb398vb39` - 지정된 태그/커밋/브랜치 Github로부터 다운로드하고 컴파일됩니다. +- `path:~/src/elixir` - 사용하려는 툴의 맞춤 컴파일 버전을 위한 경로. 언어 개발자들 등이 사용합니다. +- `system` - 이 키워드는 asdf가 asdf에 의해 관리되지 않는 시스템 버전 툴의 버전을 사용하게합니다. + +::: tip + +다양한 버전들은 공백으로 구분하여 설정될 수 있습니다. 예를 들어, 파이썬 `3.7.2`를 사용하고, 파이썬 `2.7.15`로 그리고 마지막으로 `system` 파이썬으로 폴백하려면, 다음을 `.tool-versions`에 추가해주세요. + +``` +python 3.7.2 2.7.15 system +``` + +::: + +`.tool-version` 파일에 정의된 모든 툴들을 설치하려면 `.tool-version` 파일이 포함된 디렉토리에서 다른 인수 없이 `asdf install`을 실행합니다. + +`.tool-versions` 파일에 정의된 하나의 툴을 설치하려면 `.tool-version` 파일이 포함된 디렉토리에서 `asdf install `를 실행합니다. 이 툴은 `.tool-versions` 파일에 정의된 버전으로 설치됩니다. + +해당 파일은 직접 편집하거나 `asdf local` 명령어(또는 `asdf global` 명령어)를 사용하여 업데이트해 주세요. + +## `.asdfrc` + +`.asdfrc` 파일은 사용자의 머신별 설정을 정의합니다. + +`${HOME}/.asdfrc`는 asdf가 사용하는 기본 위치입니다. 이는 [환경 변수 `ASDF_CONFIG_FILE`](#asdfconfigfile)로 설정 가능합니다. + +아래 파일은 필수적인 형식과 기본값들을 보여줍니다: + +```txt +legacy_version_file = no +use_release_candidates = no +always_keep_download = no +plugin_repository_last_check_duration = 60 +disable_plugin_short_name_repository = no +concurrency = auto +``` + +### `legacy_version_file` + +**지원되는** 플러그인들은 다른 버전 매니저에서 사용되는 버전 파일들을 읽을 수 있습니다, 예를 들어, 루비의 `rbenv`에서 `.ruby-version`. + +| 옵션 | 설명 | +| :------------------------------------------------------ | :------------------------------------------------------------------------------------------ | +| `no` | 버전을 불러오는 데는 `.tool-versions`를 사용합니다 | +| `yes` | 이용 가능한 레거시 버전 파일(`.ruby-version` 등)이 있는 경우 플러그인의 폴백으로 사용합니다 | + +### `use_release_candidates` + +`asdf update` 명령어로 asdf를 최신 유의적 버전이 아닌 최신 버전 후보판으로 업그레이드 되도록 설정합니다. + +| 옵션 | 설명 | +| :------------------------------------------------------ | :----------------- | +| `no` | 유의적 버전 사용 | +| `yes` | 릴리스 후보판 사용 | + +### `always_keep_download` + +`asdf install` 명령어로 다운로드하는 소스 코드 또는 바이너리를 유지 또는 제거하도록 설정합니다 + +| 옵션 | 설명 | +| :------------------------------------------------------ | :-------------------------------------------- | +| `no` | 성공적인 설치 후 소스 코드 또는 바이너리 제거 | +| `yes` | 설치 후 소스 코드 또는 바이너리 유지 | + +### `plugin_repository_last_check_duration` + +asdf 플러그인 리포지토리 동기화 간격(분)을 설정합니다. 트리거 이벤트는 지난 동기화 시간을 확인하게 합니다. 마지막 동기화 이후 지정된 동기화 간격보다 더 많은 시간이 경과하면, 새로운 동기화가 발생합니다. + +| 옵션 | 설명 | +| :-------------------------------------------------------------------------------------------- | :------------------------------------------------------------------ | +| `1`에서 `999999999` 사이의 정수
`60` | 마지막 동기화 이후 지속 시간(분)이 초과된 경우 트리거 이벤트 동기화 | +| `0` | 각 트리거 이벤트에서 동기화 | +| `never` | 동기화 하지 않음 | + +동기화 이벤트는 다음 명령어들을 실행할 때 발생합니다: + +- `asdf plugin add ` +- `asdf plugin list all` + +`asdf plugin add ` 플러그인 동기화를 트리거하지 않습니다. + +::: warning 노트 + +해당 값을 `never`로 설정하는 것은 플러그인 리포지토리의 초기 동기화를 막지 않고, 해당 기능을 위해 `disable_plugin_short_name_repository`를 참조하세요. + +::: + +### `disable_plugin_short_name_repository` + +asdf 플러그인 short-name 리포지토리의 동기화를 비활성화합니다. short-name 리포지토리가 비활성화 되어있으면 동기화 이벤트가 조기 종료됩니다. + +| 옵션 | 설명 | +| :------------------------------------------------------ | :------------------------------------------------------------- | +| `no` | 동기화 이벤트에서 asdf 플러그인 리포지토리 clone 또는 업데이트 | +| `yes` | short-name 플러그인 리포지토리 비활성화 | + +동기화 이벤트는 다음 명령어들을 실행할 때 발생합니다: + +- `asdf plugin add ` +- `asdf plugin list all` + +`asdf plugin add `는 플러그인 동기화를 트리거하지 않습니다. + +::: warning 노트 + +플러그인 short-name repository를 비활성화해도 리포지토리가 이미 동기화된 경우 제거되지 않습니다. `rm --recursive --trash $ASDF_DATA_DIR/repository`로 플러그인 리포지토리를 제거합니다. + +플러그인 short-name 리포지토리를 비활성화해도 그 리포지토리로부터 설치된 이전의 플러그인은 제거되지 않습니다. `asdf plugin remove `을 사용하여 플러그인을 제거할 수 있습니다. 플러그인을 제거하면 해당 툴의 모든 설치된 버전이 제거됩니다. + +::: + +### `concurrency` + +컴파일 중에 사용할 기본 코어 수입니다. + +| 옵션 | 설명 | +| :----- | :--------------------------------------------------------------------------------------------- | +| 정수 | 소스 코드를 컴파일할 때 사용할 코어 수 | +| `auto` | `nproc`, `sysctl hw.ncpu`, `/proc/cpuinfo` 또는 `1`을 순차적으로 사용하여 코어 수를 계산합니다 | + +노트: `ASDF_CONCURRENCY` 환경 변수가 존재하는 경우 우선 순위를 갖습니다. + +### 플러그인 훅 + +다음에서 사용자 맞춤 코드를 실행이 가능합니다: + +- 플러그인 설치, shim 재생성, 업데이트, 또는 제거 전 또는 후 +- 플러그인 명령어 실행 전 또는 후 + +예를 들어 `foo`라는 플러그인이 설치되어 있고 `bar`라는 실행파일이 제공된 경우, 다음 훅들을 사용하여 사용자 맞춤 코드를 먼저 실행할 수 있습니다: + +```text +pre_foo_bar = echo Executing with args: $@ +``` + +지원되는 패턴은 다음과 같습니다: + +- `pre__` +- `pre_asdf_download_` +- `{pre,post}_asdf_{install,reshim,uninstall}_` + - `$1`: 풀 버전 +- `{pre,post}_asdf_plugin_{add,update,remove,reshim}` + - `$1`: 플러그인 이름 +- `{pre,post}_asdf_plugin_{add,update,remove}_` + +어떤 명령어 훅들이 어떤 명령어 이전 또는 이후에 실행되는 지에 대한 자세한 내용은 [플러그인 생성하기](../plugins/create.md)를 참조하세요. + +## 환경 변수 + +환경 변수 설정은 시스템과 셸에 따라 다릅니다. 기본 위치는 설치 위치와 방식(Git clone, Homebrew, AUR)에 달려있습니다. + +환경 변수들은 일반적으로 `asdf.sh`/`asdf.fish` 등을 source하기 전에 설정됩니다. Elvish의 경우는, 상단에서 `use asdf`로 설정합니다. + +다음은 Bash 셸에서 사용법에 관한 설명입니다. + +### `ASDF_CONFIG_FILE` + +`.asdfrc` 설정 파일의 경로. 임의의 위치로 설정 가능합니다. 절대 경로여야 합니다. + +- 미설정 시: `$HOME/.asdfrc`가 사용됩니다. +- 사용법: `export ASDF_CONFIG_FILE=/home/john_doe/.config/asdf/.asdfrc` + +### `ASDF_DEFAULT_TOOL_VERSIONS_FILENAME` + +툴 이름과 버전을 저장하는 파일의 파일이름입니다. 임의의 유효한 파일 이름이면 됩니다. 일반적으로, `.tool-version` 파일들을 무시하고 싶을 때 해당 값을 설정하세요. + +- 미설정 시: `.tool-versions`가 사용됩니다. +- 사용법: `export ASDF_DEFAULT_TOOL_VERSIONS_FILENAME=tool_versions` + +### `ASDF_DIR` + +`asdf` 코어 스크립트의 위치. 임의의 위치로 설정할 수 있습니다. 절대 경로여야 합니다. + +- 미설정 시: `bin/asdf` 실행파일의 한 단계 상위 디렉토리가 사용됩니다. +- 사용법: `export ASDF_DIR=/home/john_doe/.config/asdf` + +### `ASDF_DATA_DIR` + +`asdf`가 플러그인, shim들, 툴 버전들을 설치하는 위치. 임의의 위치로 설정할 수 있습니다. 절대 경로여야 합니다. + +- 미설정 시: `$HOME/.asdf` 존재 시 사용, 존재하지 않는 경우 `ASDF_DIR` 사용 +- 사용법: `export ASDF_DATA_DIR=/home/john_doe/.asdf` + +### `ASDF_CONCURRENCY` + +소스 코드를 컴파일할 때 사용할 코어 수입니다. 설정하면 이 값이 asdf 설정 `concurrency` 값보다 우선 시 됩니다. + +- 미설정 시: asdf 설정 `concurrency` 값이 사용됩니다. +- 사용법: `export ASDF_CONCURRENCY=32` + +### `ASDF_FORCE_PREPEND` + +`PATH`의 맨 앞(최우선순위) 부분에 `asdf` shim과 경로 디렉토리를 추가할 것인지 여부. + +- 미설정 시: 맥 운영체제에서, `yes`가 기본값; 다른 시스템에서는 `no`가 기본값 +- `yes`: `PATH`의 앞 부분에 `asdf` 디렉토리 강제 추가 +- `yes` 이외의 _다른_ 문자열: `PATH`의 앞 부분에 `asdf` 디렉토리 강제로 추가하지 _않음_ +- 사용법: `ASDF_FORCE_PREPEND=no . "/asdf.sh"` + +## 전체 설정의 예시 + +다음을 이용한 간단한 asdf 설치는: + +- Bash 셸 +- `$HOME/.asdf` 설치 위치 +- Git을 통한 설치 +- 환경 변수 설정 없음 +- 맞춤 `.asdfrc` 파일 없음 + +다음의 결과가 나오게 됩니다: + +| 항목 | 값 | 값이 세팅되는 과정 | +| :------------------------------------ | :--------------- | :--------------------------------------------------------------------------------------------------------------------------- | +| config file location | `$HOME/.asdfrc` | `ASDF_CONFIG_FILE`가 비었으므로, `$HOME/.asdfrc`을 사용 | +| default tool versions filename | `.tool-versions` | `ASDF_DEFAULT_TOOL_VERSIONS_FILENAME`가 비었으므로, `.tool-versions`을 사용 | +| asdf dir | `$HOME/.asdf` | `ASDF_DIR`가 비었으므로, `bin/asdf`의 한 단계 상위 디렉토리 사용 | +| asdf data dir | `$HOME/.asdf` | `ASDF_DATA_DIR`가 비었으므로, `$HOME/.asdf`를 `$HOME`으로 사용. | +| concurrency | `auto` | `ASDF_CONCURRENCY`가 비었으므로, [기본 설정](https://github.com/asdf-vm/asdf/blob/master/defaults)의 `concurrency` 값에 의존 | +| legacy_version_file | `no` | 맞춤 `.asdfrc` 없음, [기본 설정](https://github.com/asdf-vm/asdf/blob/master/defaults) 사용 | +| use_release_candidates | `no` | 맞춤 `.asdfrc` 없음, [기본 설정](https://github.com/asdf-vm/asdf/blob/master/defaults) 사용 | +| always_keep_download | `no` | 맞춤 `.asdfrc` 없음, [기본 설정](https://github.com/asdf-vm/asdf/blob/master/defaults) 사용 | +| plugin_repository_last_check_duration | `60` | 맞춤 `.asdfrc` 없음, [기본 설정](https://github.com/asdf-vm/asdf/blob/master/defaults) 사용 | +| disable_plugin_short_name_repository | `no` | 맞춤 `.asdfrc` 없음, [기본 설정](https://github.com/asdf-vm/asdf/blob/master/defaults) 사용 | + +## 내부 설정 + +이 섹션은 패키지 관리자 및 통합자에게 유용한 `asdf` 내부 설정을 설명하므로 일반 사용자들은 이 섹션에 대해 걱정할 필요가 없습니다. + +- `$ASDF_DIR/asdf_updates_disabled`: 이 파일이 있으면 `asdf update` 명령어를 통한 업데이트가 (내용과 무관하게) 비활성화됩니다. 이는 Pacman이나 Homebrew와 같은 패키지 매니저들이 특정 설치에 올바른 업데이트 방법이 사용되었는지 확인하는 데 사용됩니다. diff --git a/docs/ko-kr/manage/core.md b/docs/ko-kr/manage/core.md new file mode 100644 index 000000000..619ba080d --- /dev/null +++ b/docs/ko-kr/manage/core.md @@ -0,0 +1,456 @@ +# 코어 + +코어 `asdf` 명령어는 소수지만, 많은 워크플로우를 원활하게 만들어줍니다. + +## 설치 & 설정 + +[시작하기](/ko-kr/guide/getting-started.md)의 가이드에 설명되어 있습니다. + +## 실행 + +```shell +asdf exec [args...] +``` + +현재 버전의 shim 명령어를 실행합니다. + + + +## 환경 변수 + +```shell +asdf env [util] +``` + + + +## 정보 + +```shell +asdf info +``` + +운영체제, 셸 및 `asdf` 디버깅 정보를 출력하는 헬퍼 명령어입니다. 버그 리포트 작성시 공유해주세요. + +## Shim 재생성 + +```shell +asdf reshim +``` + +패키지의 현재 버전 shim을 재생성합니다. 기본적으로, shim들은 플러그인을 통해 툴 설치 중에 생성됩니다. [npm CLI](https://docs.npmjs.com/cli/) 등과 같은 툴들은 실행파일을 글로벌 설치할 수 있습니다, 예를 들어, `npm install -g yarn`을 통한 [Yarn](https://yarnpkg.com/) 설치. 이러한 실행파일은 플러그인의 라이프사이클을 통해 설치되지 않았기 때문에, 해당 플러그인을 위한 shim이 아직 존재하지 않습니다. 이때, `nodejs`의 ``에 대해서, 예를 들면 `yarn`과 같은, 새로운 실행파일의 shim을 `asdf reshim nodejs `을 통해 강제적으로 재작성 할 수 있습니다. + +## Shim 버전 + +```shell +asdf shim-versions +``` + +shim을 제공하는 플러그인 및 버전들을 나열합니다. + +예를 들면, [Node.js](https://nodejs.org/)에는 `node`와 `npm`이라고 하는 2개의 실행파일이 제공되고 있습니다. [`asdf-nodejs`](https://github.com/asdf-vm/asdf-nodejs/)을 통해 여러 버전의 툴이 설치되어 있는 경우, `shim-versions`는 아래와 같은 내용을 출력할 수 있습니다: + +```shell +➜ asdf shim-versions node +nodejs 14.8.0 +nodejs 14.17.3 +nodejs 16.5.0 +``` + +```shell +➜ asdf shim-versions npm +nodejs 14.8.0 +nodejs 14.17.3 +nodejs 16.5.0 +``` + +## 업데이트 + +`asdf`는 (권장 설치 방법) Git에 의존하는 빌트인 업데이트 명령어가 있습니다. 다른 방법으로 설치한 경우, 그 방법을 위한 절차를 따라주세요: + +| 방법 | 최신 안정 릴리스 | `master`에 최신 커밋 | +| -------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | +| asdf (via Git) | `asdf update` | `asdf update --head` | +| Homebrew | `brew upgrade asdf` | `brew upgrade asdf --fetch-HEAD` | +| Pacman | 새로운 `PKGBUILD` 다운로드 & 재빌드
혹은 선호하는 [AUR 헬퍼](https://wiki.archlinux.org/index.php/AUR_helpers) 사용 | | + +## 제거 + +`asdf` 제거를 위해 다음 절차를 따르세요: + +::: details Bash & Git + +1. `~/.bashrc`에서, `asdf.sh` 및 자동완성을 source하고 있는 행들을 삭제: + +```shell +. "$HOME/.asdf/asdf.sh" +. "$HOME/.asdf/completions/asdf.bash" +``` + +2. `$HOME/.asdf` 디렉토리 제거: + +```shell +rm -rf "${ASDF_DATA_DIR:-$HOME/.asdf}" +``` + +3. 모든 `asdf` 설정 파일들 제거를 위해 아래 명령어 실행: + +```shell +rm -rf "$HOME/.tool-versions" "$HOME/.asdfrc" +``` + +::: + +::: details Bash & Git (macOS) + +1. `~/.bash_profile`에서, `asdf.sh` 및 자동완성을 source하고 있는 행들을 삭제: + +```shell +. "$HOME/.asdf/asdf.sh" +. "$HOME/.asdf/completions/asdf.bash" +``` + +2. `$HOME/.asdf` 디렉토리 제거: + +```shell +rm -rf "${ASDF_DATA_DIR:-$HOME/.asdf}" +``` + +3. 모든 `asdf` 설정 파일들 제거를 위해 아래 명령어 실행: + +```shell +rm -rf "$HOME/.tool-versions" "$HOME/.asdfrc" +``` + +::: + +::: details Bash & Homebrew + +1. `~/.bashrc`에서, `asdf.sh` 및 자동완성을 source하고 있는 행들을 삭제: + +```shell +. $(brew --prefix asdf)/libexec/asdf.sh +. $(brew --prefix asdf)/etc/bash_completion.d/asdf.bash +``` + +명령어 자동완성에 대해서는 [Homebrew에 설명되어 있는 방법으로 설정](https://docs.brew.sh/Shell-Completion#configuring-completions-in-bash) 되어 있을 가능성이 있으므로, 그 가이드에 따라 삭제할 행을 찾아주세요. + +2. 패키지 관리자를 사용하여 제거: + +```shell +brew uninstall asdf --force +``` + +3. 모든 `asdf` 설정 파일들 제거를 위해 아래 명령어 실행: + +```shell +rm -rf "$HOME/.tool-versions" "$HOME/.asdfrc" +``` + +::: + +::: details Bash & Homebrew (macOS) + +**macOS Catalina 혹은 그 이상**을 사용하신다면, 기본 셸이 **ZSH**로 변경되었습니다. 만약, `~/.bash_profile`에서 설정을 찾을 수 없는 경우는, `~/.zshrc`에 있을 가능성이 있는데 이 경우 ZSH의 설명을 봐 주세요. + +1. `~/.bash_profile`에서, `asdf.sh` 및 자동완성을 source하고 있는 행들을 삭제: + +```shell +. $(brew --prefix asdf)/libexec/asdf.sh +. $(brew --prefix asdf)/etc/bash_completion.d/asdf.bash +``` + +명령어 자동완성에 대해서는 [Homebrew에 설명되어 있는 방법으로 설정](https://docs.brew.sh/Shell-Completion#configuring-completions-in-bash) 되어 있을 가능성이 있으므로, 그 가이드에 따라 삭제할 행을 찾아주세요. + +2. 패키지 관리자를 사용하여 제거: + +```shell +brew uninstall asdf --force +``` + +3. 모든 `asdf` 설정 파일들 제거를 위해 아래 명령어 실행: + +```shell +rm -rf "$HOME/.tool-versions" "$HOME/.asdfrc" +``` + +::: + +::: details Bash & Pacman + +1. `~/.bashrc`에서, `asdf.sh` 및 자동완성을 source하고 있는 행들을 삭제: + +```shell +. /opt/asdf-vm/asdf.sh +``` + +2. 패키지 관리자를 사용하여 제거: + +```shell +pacman -Rs asdf-vm +``` + +3. `$HOME/.asdf` 디렉토리 제거: + +```shell +rm -rf "${ASDF_DATA_DIR:-$HOME/.asdf}" +``` + +4. 모든 `asdf` 설정 파일들 제거를 위해 아래 명령어 실행: + +```shell +rm -rf "$HOME/.tool-versions" "$HOME/.asdfrc" +``` + +::: + +::: details Fish & Git + +1. `~/.config/fish/config.fish`에서, `asdf.fish`를 source하고 있는 행들을 삭제: + +```shell +source ~/.asdf/asdf.fish +``` + +그리고 자동완성을 다음 명령어로 제거: + +```shell +rm -rf ~/.config/fish/completions/asdf.fish +``` + +2. `$HOME/.asdf` 디렉토리 제거: + +```shell +rm -rf (string join : -- $ASDF_DATA_DIR $HOME/.asdf) +``` + +3. 모든 `asdf` 설정 파일들 제거를 위해 아래 명령어 실행: + +```shell +rm -rf "$HOME/.tool-versions" "$HOME/.asdfrc" +``` + +::: + +::: details Fish & Homebrew + +1. `~/.config/fish/config.fish`에서, `asdf.fish`를 source하고 있는 행들을 삭제: + +```shell +source "(brew --prefix asdf)"/libexec/asdf.fish +``` + +2. 패키지 관리자를 사용하여 제거: + +```shell +brew uninstall asdf --force +``` + +3. 모든 `asdf` 설정 파일들 제거를 위해 아래 명령어 실행: + +```shell +rm -rf "$HOME/.tool-versions" "$HOME/.asdfrc" +``` + +::: + +::: details Fish & Pacman + +1. `~/.config/fish/config.fish`에서, `asdf.fish`를 source하고 있는 행들을 삭제: + +```shell +source /opt/asdf-vm/asdf.fish +``` + +2. 패키지 관리자를 사용하여 제거: + +```shell +pacman -Rs asdf-vm +``` + +3. `$HOME/.asdf` 디렉토리 제거: + +```shell +rm -rf (string join : -- $ASDF_DATA_DIR $HOME/.asdf) +``` + +4. 모든 `asdf` 설정 파일들 제거를 위해 아래 명령어 실행: + +```shell +rm -rf "$HOME/.tool-versions" "$HOME/.asdfrc" +``` + +::: + +::: details Elvish & Git + +1. `~/.config/elvish/rc.elv`에서, `asdf` 모듈을 사용하는 행들을 삭제: + +```shell +use asdf _asdf; var asdf~ = $_asdf:asdf~ +set edit:completion:arg-completer[asdf] = $_asdf:arg-completer~ +``` + +그리고 `asdf` 모듈을 다음 명령어로 제거: + +```shell +rm -f ~/.config/elvish/lib/asdf.elv +``` + +2. `$HOME/.asdf` 디렉토리 제거: + +```shell +if (!=s $E:ASDF_DATA_DIR "") { rm -rf $E:ASDF_DATA_DIR } else { rm -rf ~/.asdf } +``` + +3. 모든 `asdf` 설정 파일들 제거를 위해 아래 명령어 실행: + +```shell +rm -rf "$HOME/.tool-versions" "$HOME/.asdfrc" +``` + +::: + +::: details Elvish & Homebrew + +1. `~/.config/elvish/rc.elv`에서, `asdf` 모듈을 사용하는 행들을 삭제: + +```shell +use asdf _asdf; var asdf~ = $_asdf:asdf~ +set edit:completion:arg-completer[asdf] = $_asdf:arg-completer~ +``` + +그리고 `asdf` 모듈을 다음 명령어로 제거: + +```shell +rm -f ~/.config/elvish/lib/asdf.elv +``` + +2. 패키지 관리자를 사용하여 제거: + +```shell +brew uninstall asdf --force +``` + +3. 모든 `asdf` 설정 파일들 제거를 위해 아래 명령어 실행: + +```shell +rm -rf "$HOME/.tool-versions" "$HOME/.asdfrc" +``` + +::: + +::: details Elvish & Pacman + +1. `~/.config/elvish/rc.elv`에서, `asdf` 모듈을 사용하는 행들을 삭제: + +```shell +use asdf _asdf; var asdf~ = $_asdf:asdf~ +set edit:completion:arg-completer[asdf] = $_asdf:arg-completer~ +``` + +그리고 `asdf` 모듈을 다음 명령어로 제거: + +```shell +rm -f ~/.config/elvish/lib/asdf.elv +``` + +2. 패키지 관리자를 사용하여 제거: + +```shell +pacman -Rs asdf-vm +``` + +3. `$HOME/.asdf` 디렉토리 제거: + +```shell +if (!=s $E:ASDF_DATA_DIR "") { rm -rf $E:ASDF_DATA_DIR } else { rm -rf ~/.asdf } +``` + +4. 모든 `asdf` 설정 파일들 제거를 위해 아래 명령어 실행: + +```shell +rm -rf "$HOME/.tool-versions" "$HOME/.asdfrc" +``` + +::: + +::: details ZSH & Git + +1. `~/.zshrc`에서, `asdf.sh` 및 자동완성을 source하고 있는 행들을 삭제: + +```shell +. "$HOME/.asdf/asdf.sh" +# ... +fpath=(${ASDF_DIR}/completions $fpath) +autoload -Uz compinit +compinit +``` + +**혹은** 사용된 ZSH 프레임워크 플러그인 제거. + +2. `$HOME/.asdf` 디렉토리 제거: + +```shell +rm -rf "${ASDF_DATA_DIR:-$HOME/.asdf}" +``` + +3. 모든 `asdf` 설정 파일들 제거를 위해 아래 명령어 실행: + +```shell +rm -rf "$HOME/.tool-versions" "$HOME/.asdfrc" +``` + +::: + +::: details ZSH & Homebrew + +1. `~/.zshrc`에서, `asdf.sh`을 source하고 있는 행들을 삭제: + +```shell +. $(brew --prefix asdf)/libexec/asdf.sh +``` + +2. 패키지 관리자를 사용하여 제거: + +```shell +brew uninstall asdf --force && brew autoremove +``` + +3. 모든 `asdf` 설정 파일들 제거를 위해 아래 명령어 실행: + +```shell +rm -rf "$HOME/.tool-versions" "$HOME/.asdfrc" +``` + +::: + +::: details ZSH & Pacman + +1. `~/.zshrc`에서, `asdf.sh`을 source하고 있는 행들을 삭제: + +```shell +. /opt/asdf-vm/asdf.sh +``` + +2. 패키지 관리자를 사용하여 제거: + +```shell +pacman -Rs asdf-vm +``` + +3. `$HOME/.asdf` 디렉토리 제거: + +```shell +rm -rf "${ASDF_DATA_DIR:-$HOME/.asdf}" +``` + +4. 모든 `asdf` 설정 파일들 제거를 위해 아래 명령어 실행: + +```shell +rm -rf "$HOME/.tool-versions" "$HOME/.asdfrc" +``` + +::: + +끝! 🎉 diff --git a/docs/ko-kr/manage/plugins.md b/docs/ko-kr/manage/plugins.md new file mode 100644 index 000000000..c60554f5b --- /dev/null +++ b/docs/ko-kr/manage/plugins.md @@ -0,0 +1,86 @@ +# 플러그인 + +플로그인들은 `asdf`가 Node.js, Ruby, Elixir 등 여러가지 툴들을 취급하는 방법입니다. + +더 많은 툴들 지원을 위한 플러그인 API는 [플러그인 생성하기](/ko-kr/plugins/create.md) 참고하세요. + +## 추가하기 + +Git URL로 플러그인 추가하기: + +```shell +asdf plugin add +# asdf plugin add elm https://github.com/vic/asdf-elm +``` + +또는 플러그인 리포지토리에 short-name을 통해 추가하기: + +```shell +asdf plugin add +# asdf plugin add erlang +``` + +::: tip 추천 + +short-name 리포지토리에 독립적인 긴 `git-url` 방식이 선호됩니다. + +::: + +## 설치된 목록 + +```shell +asdf plugin list +# asdf plugin list +# java +# nodejs +``` + +```shell +asdf plugin list --urls +# asdf plugin list +# java https://github.com/halcyon/asdf-java.git +# nodejs https://github.com/asdf-vm/asdf-nodejs.git +``` + +## 모든 Short-name 리포지토리 목록 + +```shell +asdf plugin list all +``` + +플러그인들의 전체 short-name 목록을 [플러그인 Shortname 인덱스](https://github.com/asdf-vm/asdf-plugins)에서 확인하세요. + +## 업데이트 + +```shell +asdf plugin update --all +``` + +특정 패키지를 업데이트하고 싶다면, 다음 명령어를 사용하세요. + +```shell +asdf plugin update +# asdf plugin update erlang +``` + +이 명령어는 해당 플러그인 리포지토리의 _origin_ _기본 브랜치_ 의 _가장 최근 커밋_ 을 fetch합니다. 버전화된 플러그인들과 업데이트들은 현재 개발 진행중 입니다 ([#916](https://github.com/asdf-vm/asdf/pull/916)). + +## 제거 + +```bash +asdf plugin remove +# asdf plugin remove erlang +``` + +플러그인 제거는 해당 툴과 관련된 모든 것을 제거합니다. 이것은 한 툴의 미사용중인 많은 버전들의 cleaning/pruning에 유용합니다. + +## asdf Short-name 리포지토리 동기화 + +Short-name 리포지토리는 로컬 머신에 주기적으로 동기화됩니다. 동기화 방식들로 다음 방식들이 있습니다: + +- 명령어들에 의한 동기화 이벤트: + - `asdf plugin add ` + - `asdf plugin list all` +- 만약 `disable_plugin_short_name_repository` 설정 옵션이 `yes`로 설정되어 있다면, 동기화는 조기 종료됩니다. [asdf 설정 문서](/ko-kr/manage/configuration.md)에서 더보기. +- 만약 동기화가 지난 `X`분 동안 진행되지 않았다면, 동기화가 진행됩니다. + - `X`의 기본값은 `60`입니다만, `.asdfrc`의 `plugin_repository_last_check_duration` 옵션을 통해 설정될 수 있습니다. [asdf 설정 문서](/ko-kr/manage/configuration.md)에서 더보기. diff --git a/docs/ko-kr/manage/versions.md b/docs/ko-kr/manage/versions.md new file mode 100644 index 000000000..02489813f --- /dev/null +++ b/docs/ko-kr/manage/versions.md @@ -0,0 +1,155 @@ +# 버전 + +## 버전 설치 + +```shell +asdf install +# asdf install erlang 17.3 +``` + +플러그인이 소스에서 다운로드 & 컴파일을 지원하는 경우, `ref:foo`를 지정할 수 있으며 여기서 `foo`는 특정 브랜치, 태그 또는 커밋입니다. 제거할 때도 동일한 이름과 참조를 사용해야 합니다. + +## 최신 안정 버전 설치 + +```shell +asdf install latest +# asdf install erlang latest +``` + +주어진 문자열로 시작하는 최신 안정 버전을 설치합니다. + +```shell +asdf install latest: +# asdf install erlang latest:17 +``` + +## 설치된 버전 목록 + +```shell +asdf list +# asdf list erlang +``` + +주어진 문자열로 시작하는 버전으로 필터링합니다. + +```shell +asdf list +# asdf list erlang 17 +``` + +## 사용 가능한 모든 버전 목록 + +```shell +asdf list all +# asdf list all erlang +``` + +주어진 문자열로 시작하는 버전으로 필터링합니다. + +```shell +asdf list all +# asdf list all erlang 17 +``` + +## 최신 안정 버전 보기 + +```shell +asdf latest +# asdf latest erlang +``` + +주어진 문자열로 시작하는 최신 안정 버전을 보여줍니다. + +```shell +asdf latest +# asdf latest erlang 17 +``` + +## 현재 버전 설정 + +```shell +asdf global [...] +asdf shell [...] +asdf local [...] +# asdf global elixir 1.2.4 + +asdf global latest[:] +asdf local latest[:] +# asdf global elixir latest +``` + +`global`은 해당 버전을 `$HOME/.tool-versions`에 작성합니다. + +현재 셸 세션에 대해서만, `shell`은 `ASDF_${TOOL}_VERSION`이라는 이름의 환경 변수로 버전을 설정합니다. + +`local`은 해당 버전을 `$PWD/.tool-versions`에 작성합니다, 존재하지 않을 시에 새로 만듦. + +세부 내용은 `.tool-versions` [설정 섹션에 파일](/ko-kr/manage/configuration.md)을 참고하세요. + +:::warning 대체수단 +현재 셸 세션에 대해서만 버전을 설정하려는 경우 +또는 특정 툴 버전 하에 단순히 한개의 명령어만 실행하기 위해, 당신은 +`ASDF_${TOOL}_VERSION`과 같은 환경 변수를 설정할 수 있습니다. +::: + +다음 예시에서는 버전 `1.4.0`의 Elixir 프로젝트에서 테스트를 수행합니다. +버전 형식은 `.tool-versions` 파일에서 지원되는 것과 동일하게 지원됩니다. + +```shell +ASDF_ELIXIR_VERSION=1.4.0 mix test +``` + +## 시스템 버전으로의 폴백 + +asdf 관리 버전이 아닌 `` 도구의 시스템 버전을 사용하려면 도구의 버전을 `system`으로 설정할 수 있습니다. + +위에 [현재 버전 설정](#현재-버전-설정) 섹션에 나와있는대로, `system`을 `global`, `local` or `shell` 중에 하나로 설정하세요. + +```shell +asdf local system +# asdf local python system +``` + +## 현재 버전 보기 + +```shell +asdf current +# asdf current +# erlang 17.3 /Users/kim/.tool-versions +# nodejs 6.11.5 /Users/kim/cool-node-project/.tool-versions + +asdf current +# asdf current erlang +# erlang 17.3 /Users/kim/.tool-versions +``` + +## 버전 제거 + +```shell +asdf uninstall +# asdf uninstall erlang 17.3 +``` + +## Shims + +asdf는 패키지를 설치할 때 해당 패키지의 모든 실행 프로그램에 대한 shim들을 `$ASDF_DATA_DIR/shims` 디렉토리 (기본값은 `~/.asdf/shims`)에 생성합니다. 이 디렉토리는 설치된 프로그램들이 이용가능하도록 `$PATH` (`asdf.sh`, `asdf.fish` 등)에 존재합니다. + +Shim 자체는 플러그인 이름과 shim이 감싸고 있는 설치된 패키지의 실행파일의 경로를 넘겨주는 `asdf exec`라는 헬퍼 프로그램을 `exec`시키는 매우 단순한 wrapper입니다. + +`asdf exec` 헬퍼는 (`.tool-version` 파일에 지정된 대로, `asdf local...` 또는 `asdf global...`에서 선택된 대로) 사용할 패키지의 버전을 결정합니다, (플러그인의 `exec-path` 콜백에 의해 조정될 수 있음) 패키지 설치 디렉토리의 실행 파일에 대한 최종 경로 및 (플러그인에 의해 제공된 - `exec-env` 스크립트) 실행할 환경을 결정하고, 최종적으로 이를 실행합니다. + +::: warning 노트 +이 시스템은 `exec` 호출을 사용하기 때문에, 실행 대신 셸에 의해 source 되야하는 패키지의 스크립트는 shim wrapper를 통하지 않고 직접 액세스되야 합니다. 두 가지 `asdf` 명령어: `which`와 `where`는 설치된 패키지로의 경로를 반환할 수 있습니다: +::: + +```shell +# returns path to main executable in current version +source $(asdf which ${PLUGIN})/../script.sh + +# returns path to the package installation directory +source $(asdf where ${PLUGIN})/bin/script.sh +``` + +### asdf shims 우회 + +어떠한 이유로 asdf의 shim들을 우회하고 싶거나 프로젝트의 디렉토리로 이동했을 때 자동으로 환경 변수를 설정되게 하고 싶으시면 [asdf-direnv](https://github.com/asdf-community/asdf-direnv) 플러그인이 도움이 될 것입니다. 상세한 내용은 README를 확인해 주세요. diff --git a/docs/ko-kr/more/community-projects.md b/docs/ko-kr/more/community-projects.md new file mode 100644 index 000000000..ead02a5d9 --- /dev/null +++ b/docs/ko-kr/more/community-projects.md @@ -0,0 +1,16 @@ +# 커뮤니티 프로젝트 + +`asdf`와 관련된 커뮤니티 프로젝트들입니다: + +- [asdf-community](https://github.com/asdf-community): + asdf 플로그인들의 장기 관리를 위한 커뮤니티 주도의 프로젝트입니다. +- [asdf dev container](https://github.com/iloveitaly/asdf-devcontainer): + GitHub 코드스페이스에서 asdf가 관리하는 툴들을 지원하는 + [GitHub 개발 컨테이너](https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces/introduction-to-dev-containers) + +::: warning 노트 + +asdf 코어 팀은 이 프로젝트들 혹은 코드를 소유하지 않습니다. +asdf 코어는 위의 목록들에 품질과 보안을 책임지지 않습니다. + +::: diff --git a/docs/ko-kr/more/faq.md b/docs/ko-kr/more/faq.md new file mode 100644 index 000000000..bfe15c42d --- /dev/null +++ b/docs/ko-kr/more/faq.md @@ -0,0 +1,25 @@ +# 자주 묻는 질문 + +`asdf`에 관련된 공통된 질문들입니다. + +## WSL1을 지원하나요? + +WSL1 ([Windows Subsystem for Linux](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux) 1)는 공식적으로 지원되지 않습니다. 어떤 부분의 `asdf`의 제대로 동작하지 않을 수 있습니다. 우리는 WSL1의 공식 지원을 추가할 계획이 없습니다. + +## WSL2을 지원하나요? + +WSL2 ([Windows Subsystem for Linux](https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux#WSL_2) 2)는 당신이 선택한 WSL distro를 위한 설치 & dependency 설명서를 따르면 작동합니다. + +중요한 것은, WSL2는 _오직_ 현재 작업 디렉토리가 Unix 드라이브 그리고 Windows 드라이브에 종속되어 있지 않을때 정상적으로 동작합니다. + +우리는 호스트 runner support가 GitHub Actions에서 사용가능할 때 WSL2에서 테스트 suite를 진행할 계획입니다만, 현재는 아직 이용가능하지 않은 것 같습니다. + +## 새롭게 설치된 실행파일이 동작하지 않나요? + +> 방금 `npm install -g yarn`, 그러나 `yarn`을 실행시킬 수 없습니다. 어떻게 해야하나요? + +`asdf`는 [shims]()를 사용하여 실행파일들을 관리합니다. 플러그인에 의해서 설치되는 실행파일들은 자동적으로 shim이 생성되지만, `asdf`가 관리하고 있는 툴에 의해서 실행파일이 설치 된 경우는 shim을 생성해야 한다고 하는 것을 `asdf`에 알려줄 필요가 있습니다. 이러한 경우, [Yarn](https://yarnpkg.com/)의 shim을 생성하기 위해 [`asdf reshim` 명령어 문서](/ko-kr/manage/core.md#Shim-재생성)를 참고하세요. + +## 셸이 새롭게 설치된 shims들을 감지하지 못하나요? + +만약 `asdf reshim`가 문제를 해결하지 못한다면, 대부분의 경우 `asdf.sh` 혹은 `asdf.fish` sourcing이 당신의 셸 설정 파일 (`.bash_profile`, `.zshrc`, `config.fish` etc) **아래쪽에** 있지 _않을_ 가능성이 높습니다. 당신의 `$PATH`가 설정 된 **후에** 그리고 사용중인 프레임워크 (oh-my-zsh etc)가 source 된 **후에** source 되어야 합니다. diff --git a/docs/ko-kr/more/thanks.md b/docs/ko-kr/more/thanks.md new file mode 100644 index 000000000..07cb92932 --- /dev/null +++ b/docs/ko-kr/more/thanks.md @@ -0,0 +1,21 @@ +# 감사인사 + +asdf 저자들 & 기여자들을 위한 감사 페이지! + +## Credits + +나 ([@HashNuke](https://github.com/HashNuke)), 고열, 감기, 기침. + +2014년부터 종료까지의 저작권 ([MIT License](https://github.com/asdf-vm/asdf/blob/master/LICENSE)) + +## 관리자 + +- [@HashNuke](https://github.com/HashNuke) +- [@danhper](https://github.com/danhper) +- [@Stratus3D](https://github.com/Stratus3D) +- [@vic](https://github.com/vic) +- [@jthegedus](https://github.com/jthegedus) + +## 기여자 + +GitHub에서 [기여자들의 목록](https://github.com/asdf-vm/asdf/graphs/contributors)를 확인하세요 :pray: diff --git a/docs/ko-kr/plugins/create.md b/docs/ko-kr/plugins/create.md new file mode 100644 index 000000000..30c037a8d --- /dev/null +++ b/docs/ko-kr/plugins/create.md @@ -0,0 +1,937 @@ +# 플러그인 생성하기 + +플러그인은 언어 / 툴의 버전 관리를 지원하는 실행 가능한 스크립트들이 있는 +Git 리포지토리입니다. 이 스크립트들은 asdf에 의해 특정 명령어들을 받아 +`asdf list-all `, `asdf install ` +등의 지원을 위해 실행됩니다. + +## 빠른 시작 + +자체 플러그인을 만드는 것을 시작하는 두 가지 옵션이 있습니다: + +1. [asdf-vm/asdf-plugin-template](https://github.com/asdf-vm/asdf-plugin-template) + 리포지토리 사용해서 + 기본 스크립트가 구현된 (`asdf-` 이름으로) 플러그인 리포지토리 + [생성하기](https://github.com/asdf-vm/asdf-plugin-template/generate). 리포지토리가 생성되면, + 그 리포지토리를 clone하고 템플릿을 + 유기적으로 업데이트하여 + `setup.bash` 스크립트를 실행합니다. +2. `asdf-`로 이룸 붙인 리포지토리를 시작하고 + 아래 문서에 필수 스크립트들을 구현하세요. + +### 플리그인 스크립트들을 위한 황금률 + +- 스크립트는 다른 `asdf` 명령어를 호출하면 **안됩니다**. +- 셸 툴/명령어의 dependency를 최소로 유지하세요. +- non-portable 툴이나 명령어 플래그의 사용을 피하세요. 예를 들어, `sort -V`. + asdf core를 참고하세요 + [금지된 명령어 목록](https://github.com/asdf-vm/asdf/blob/master/test/banned_commands.bats) + +## 스크립트 개요 + +asdf에서 호출 가능한 스크립트의 전체 목록입니다. + +| 스크립트 | 설명 | +| :--------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------- | +| [bin/list-all](#bin-list-all) | 모든 설치 가능한 버전들을 나열 | +| [bin/download](#bin-download) | 지정한 버전에 대한 소스 코드 또는 바이너리 다운로드 | +| [bin/install](#bin-install) | 지정된 버전을 설치 | +| [bin/latest-stable](#bin-latest-stable) | 지정된 도구의 최신 안정 버전 나열 | +| [bin/help.overview](#bin-help.overview) | 플러그인 및 도구에 대한 일반적인 설명을 출력 | +| [bin/help.deps](#bin-help.deps) | 운영 체제별 dependencies 목록 출력 | +| [bin/help.config](#bin-help.config) | 플러그인 및 툴 설정 정보 출력 | +| [bin/help.links](#bin-help.links) | 플러그인 및 툴에 대한 링크 목록 출력 | +| [bin/list-bin-paths](#bin-list-bin-paths) | shim들을 생성하기 위해 바이너리 파일이 있는 디렉토리에 대한 상대 경로 나열 | +| [bin/exec-env](#bin-exec-env) | 바이너리 실행을 위한 환경 준비 | +| [bin/exec-path](#bin-exec-path) | 툴 버전의 실행파일 경로 출력 | +| [bin/uninstall](#bin-uninstall) | 툴의 특정 버전 제거 | +| [bin/list-legacy-filenames](#bin-list-legacy-filenames) | 레거시 버전 파일의 이름 출력: `.ruby-version` | +| [bin/parse-legacy-file](#bin-parse-legacy-file) | 레거시 버전 파일들을 위한 맞춤 parser | +| [bin/post-plugin-add](#bin-post-plugin-add) | 플러그인이 추가된 후 실행될 훅 | +| [bin/post-plugin-update](#bin-post-plugin-update) | 플러그인이 업데이트 된 후 실행될 훅 | +| [bin/pre-plugin-remove](#bin-pre-plugin-remove) | 플러그인이 제거되기 전 실행될 훅 | + +어떤 명령어가 어떤 스크립트를 호출하는지 확인하려면, 각 스크립트에 대한 자세한 문서를 +참조하세요. + +## 환경 변수 개요 + +모든 스크립트에서 사용되는 환경 변수의 전체 목록입니다. + +| 환경 변수 | 설명 | +| :----------------------- | :---------------------------------------------------------------- | +| `ASDF_INSTALL_TYPE` | `version` 또는 `ref` | +| `ASDF_INSTALL_VERSION` | `ASDF_INSTALL_TYPE`에 따른 풀 버전 번호 또는 Git Ref | +| `ASDF_INSTALL_PATH` | 툴이 설치 _되어야하는_ 혹은 _되어있는_ 경로 | +| `ASDF_CONCURRENCY` | 소스 코드를 컴파일할 때 사용할 코어 수. `make-j`를 설정할 때 유용 | +| `ASDF_DOWNLOAD_PATH` | `bin/download`에 의해 소스 코드 또는 바이너리가 다운로드 된 경로 | +| `ASDF_PLUGIN_PATH` | 플러그인이 설치된 경로 | +| `ASDF_PLUGIN_SOURCE_URL` | 플러그인의 소스 URL | +| `ASDF_PLUGIN_PREV_REF` | 플러그인 리포지토리의 이전 `git-ref` | +| `ASDF_PLUGIN_POST_REF` | 플러그인 리포지토리의 업데이트 된 `git-ref` | +| `ASDF_CMD_FILE` | source 되는 파일의 전체 경로를 해결 | + +::: tip 노트 + +**모든 스크립트에서 모든 환경 변수를 사용할 수 있는 것은 아닙니다.** 아래 각 스크립트에 대한 +문서를 확인하여 사용할 수 있는 환경 변수들을 확인하세요. + +::: + +## 필수적 스크립트 + +### `bin/list-all` + +**설명** + +설치 가능한 모든 버전 나열. + +**출력 형식** + +**공백으로 구분된** 문자열을 반드시 출력. 예를 들어: + +```txt +1.0.1 1.0.2 1.3.0 1.4 +``` + +최신 버전이 마지막에 와야 합니다. + +asdf core는 각 버전을 각각의 행에 출력하여, 일부 버전을 화면 밖으로 +밀어낼 가능성이 있습니다. + +**정렬** + +웹사이트의 릴리스 페이지에서 버전을 가져오는 경우에는 +이미 올바른 순서로 되어 있는 경우가 많기 때문에 제공된 순서대로 두는 것이 +좋습니다. 역순으로 되어 있는 경우 `tac`을 통해 해당 버전들을 바로 잡는것으로 +충분합니다. + +정렬이 불가피한 경우, `sort -V`는 사용이 불가능하므로, 다음 중 하나를 제안합니다: + +- [Git 정렬 기능 사용](https://github.com/asdf-vm/asdf-plugin-template/blob/main/template/lib/utils.bash) + (Git `v2.18.0` 이상 필요) +- [맞춤 정렬 함수 작성](https://github.com/vic/asdf-idris/blob/master/bin/list-all#L6) + (`sed`, `sort` & `awk` 필요) + +**스크립트에서 사용 가능한 환경 변수** + +이 스크립트에는 환경 변수가 제공되지 않습니다. + +**이 스크립트를 호출하는 명령어** + +- `asdf list all [version]` +- `asdf list all nodejs`: 이 스크립트에 의해 반환된 모든 버전을 나열합니다, + 한 행에 한개씩. +- `asdf list all nodejs 18`: 이 스크립트에 의해 반환된 모든 버전을 나열하며, + 각 행에 하나씩, `18`로 시작하는 모든 버전에 필터가 적용됩니다. + +**asdf core에서 호출 시그니처** + +제공되는 매개변수는 없습니다. + +```bash +"${plugin_path}/bin/list-all" +``` + +--- + +### `bin/download` + +**설명** + +지정된 장소에 지정된 버전에 대한 소스 코드 또는 바이너리 다운로드 + +**구현 세부사항** + +- 스크립트는 소스 또는 바이너리를 `ASDF_DOWNLOAD_PATH`에서 지정된 디렉토리에 다운로드해야합니다. +- 압축 해제된 소스 코드 또는 바이너리만 `ASDF_DOWNLOAD_PATH` 디렉토리에 위치해야합니다. +- 실패 시에는 `ASDF_DOLOAD_PATH`에 어떠한 파일도 남아서는 안 됩니다. +- 성공 시에는 `0`이 종료 코드입니다. +- 실패 시에는 0이 아닌 상태의 종료 코드입니다. + +**레거시 플러그인** + +비록 이 스크립트는 모든 플러그인에서 _필수_로 되어 있지만, 이 스크립트가 도입되기 이전의 "레거시" 플러그인에서는 _선택_ 입니다. + +이 스크립트가 없는 경우, asdf는 `bin/install` 스크립트가 있다고 가정하고 해당 버전을 다운로드 **그리고** 설치합니다. + +레거시 플러그인 지원은 최종적으로 제거될 예정이기 때문에 앞으로 작성할 모든 플러그인에서 이 스크립트를 포함해야합니다. + +**스크립트에서 사용 가능한 환경 변수** + +- `ASDF_INSTALL_TYPE`: `version` 또는 `ref` +- `ASDF_INSTALL_VERSION`: + - `ASDF_INSTALL_TYPE=version`의 경우, 풀 버전 번호. + - `ASDF_INSTALL_TYPE=ref`의 경우, Git ref (태그/커밋/브랜치). +- `ASDF_INSTALL_PATH`: 툴이 설치 _되어있는_, 또는 _되어야하는_ 경로. +- `ASDF_DOWNLOAD_PATH`: 소스 코드 또는 바이너리 파일이 다운로드 된 경로. + +**이 스크립트를 호출하는 명령어** + +- `asdf install [version]` +- `asdf install latest[:version]` +- `asdf install nodejs 18.0.0`: Node.js 버전 `18.0.0`의 소스 코드 또는 바이너리를 다운로드하고 + `ASDF_DOWLOAD_PATH` 디렉토리에 저장. 그 다음 `bin/install` 스크립트를 실행. + +**asdf core에서 호출 시그니처** + +제공되는 매개변수는 없습니다. + +```bash +"${plugin_path}"/bin/download +``` + +--- + +### `bin/install` + +**설명** + +특정 버전의 도구를 지정된 위치에 설치. + +**구현 세부사항** + +- 스크립트는 `ASDF_INSTALL_PATH` 경로에 지정된 버전을 설치해야합니다. +- Shim은 `$ASDF_INSTALL_PATH/bin`에 있는 어떠한 파일에 대해서든 기본적으로 생성됩니다. 이 동작은 +선택적 [bin/list-bin-paths](#binlist-bin-paths) 스크립트로 맞춤 설정 가능합니다. +- 성공 시에는 `0`이 종료 코드입니다. +- 실패 시에는 0이 아닌 상태의 종료 코드입니다. +- TOCTOU(Time-of-Check-to-Off-Use) 문제를 방지하려면, 툴의 빌드 및 설치가 성공적이라고 판단될때만 스크립트에서 파일을 `ASDF_INSTALL_PATH`에 배치합니다. + +**레거시 플러그인** + +`bin/download` 스크립트가 없는 경우, 이 스크립트는 지정된 버전을 다운로드 **그리고** 설치해야합니다. + +`0.7._`보다 이전 그리고 `0.8._`보다 이후 asdf 코어 버전들의 호환성을 확인하려면, `ASDF_DOWNLOAD_PATH` 환경 변수가 있는지 확인합니다. +그 환경 변수가 존재하는 경우, 이미 `bin/download` 스크립트가 그 버전을 다운로드했다고 가정하고, 존재하지 않으면 `bin/install` 스크립트에서 소스 코드를 다운로드합니다. + +**스크립트에서 사용 가능한 환경 변수** + +- `ASDF_INSTALL_TYPE`: `version` 또는 `ref` +- `ASDF_INSTALL_VERSION`: + - `ASDF_INSTALL_TYPE=version`의 경우, 풀 버전 번호. + - `ASDF_INSTALL_TYPE=ref`의 경우, Git ref (태그/커밋/브랜치). +- `ASDF_INSTALL_PATH`: 툴이 설치 _되어있는_, 또는 _되어야하는_ 경로. +- `ASDF_CONCURRENCY`: 소스 코드를 컴파일할 때 사용할 코어 수. `make-j`를 설정할 때 유용. +- `ASDF_DOWNLOAD_PATH`: 소스 코드 또는 바이너리 파일이 다운로드 된 경로. + +**이 스크립트를 호출하는 명령어** + +- `asdf install` +- `asdf install ` +- `asdf install [version]` +- `asdf install latest[:version]` +- `asdf install nodejs 18.0.0`: Node.js 버전 `18.0.0`을 + `ASDF_INSTALL_PATH` 디렉토리에 설치. + +**asdf core에서 호출 시그니처** + +제공되는 매개변수는 없습니다. + +```bash +"${plugin_path}"/bin/install +``` + +## 선택적 스크립트 + +### `bin/latest-stable` + +**설명** + +도구의 최신 안정 버전을 결정합니다. 이 스크립트가 존재하지 않는 경우, asdf 코어는 `bin/list-all`의 출력을 비의도적으로 `tail`합니다. + +**구현 세부사항** + +- 스크립트는 도구의 최신 안정 버전을 표준 출력에 출력해야합니다. +- 비안정판이나 릴리스 후보판은 제외되어야 합니다. +- 필터 쿼리는 스크립트의 첫 번째 인수로 제공됩니다 이 쿼리는 버전 번호나 툴 제공자에 의한 출력값을 필터하기 위해 사용되어야 합니다. + - 예를 들어 [ruby 플러그인](https://github.com/asdf-vm/asdf-ruby)에서의 `asdf list all ruby`는 `jruby`, `rbx`, `truffleruby` 등의 많은 제공자들의 Ruby 버전 목록을 출력합니다. 사용자가 제공한 필터는 플러그인이 유의적 버전 및/또는 공급자를 필터링하는 데 사용될 수 있습니다. + ``` + > asdf latest ruby + 3.2.2 + > asdf latest ruby 2 + 2.7.8 + > asdf latest ruby truffleruby + truffleruby+graalvm-22.3.1 + ``` +- 성공 시에는 `0`이 종료 코드입니다. +- 실패 시에는 0이 아닌 상태의 종료 코드입니다. + +**스크립트에서 사용 가능한 환경 변수** + +- `ASDF_INSTALL_TYPE`: `version` 또는 `ref` +- `ASDF_INSTALL_VERSION`: + - `ASDF_INSTALL_TYPE=version`의 경우, 풀 버전 번호. + - `ASDF_INSTALL_TYPE=ref`의 경우, Git ref (태그/커밋/브랜치). +- `ASDF_INSTALL_PATH`: 툴이 설치 _되어있는_, 또는 _되어야하는_ 경로. + +**이 스크립트를 호출하는 명령어** + +- `asdf global latest`: 툴의 글로벌 버전을 해당 툴의 최신 안정 버전으로 설정합니다. +- `asdf local latest`: 툴의 로컬 버전을 해당 툴의 최신 안정 버전으로 설정합니다. +- `asdf install latest`: 최신 버전의 툴을 설치합니다. +- `asdf latest []`: 선택적인 필터를 기반으로 도구의 최신 버전을 출력합니다. +- `asdf latest --all`: asdf에서 관리하는 모든 툴의 최신 버전과 설치 여부를 출력합니다. + +**asdf core에서 호출 시그니처** + +이 스크립트는 필터 쿼리라는 하나의 인수를 받습니다. + +```bash +"${plugin_path}"/bin/latest-stable "$query" +``` + +--- + +### `bin/help.overview` + +**설명** + +플러그인 및 관리 중인 툴에 대한 일반적인 설명을 출력. + +**구현 세부사항** + +- 플러그인에 대한 도움말 출력을 표시하려면 이 스크립트가 필요합니다. +- asdf 코어가 머리말를 인쇄하므로 머리말을 출력해서는 안 됩니다. +- 자유로운 형식의 텍스트로 출력해도 상관없지만 짧은 한 단락 정도의 설명이 이상적입니다. +- 핵심이 되는 asdf-vm 문서에서 이미 설명되어 있는 정보는 출력하지 않아야 합니다. +- 운영 체제와 설치된 툴의 버전에 맞게 출력해야합니다 (필요에 따라 `ASDF_INSTALL_VERSION` 및 `ASDF_INSTALL_TYPE` 환경 변수의 값을 사용하십시오). +- 성공 시에는 `0`이 종료 코드입니다. +- 실패 시에는 0이 아닌 상태의 종료 코드입니다. + +**스크립트에서 사용 가능한 환경 변수** + +- `ASDF_INSTALL_TYPE`: `version` 또는 `ref` +- `ASDF_INSTALL_VERSION`: + - `ASDF_INSTALL_TYPE=version`의 경우, 풀 버전 번호. + - `ASDF_INSTALL_TYPE=ref`의 경우, Git ref (태그/커밋/브랜치). +- `ASDF_INSTALL_PATH`: 툴이 설치 _되어있는_, 또는 _되어야하는_ 경로. + +**이 스크립트를 호출하는 명령어** + +- `asdf help []`: 플러그인 및 도구 문서를 출력 + +**asdf core에서 호출 시그니처** + +```bash +"${plugin_path}"/bin/help.overview +``` + +--- + +### `bin/help.deps` + +**설명** + +운영 체제에 맞는 dependencies 목록을 출합니다. 한 행마다 한 개의 dependency. + +```bash +git +curl +sed +``` + +**구현 세부사항** + +- 이 스크립트의 출력되기 위해서는 `bin/help.overview`가 필요합니다. +- 운영 체제와 설치된 툴의 버전에 맞게 출력해야합니다 (필요에 따라 `ASDF_INSTALL_VERSION` 및 `ASDF_INSTALL_TYPE` 환경 변수의 값을 사용하십시오). +- 성공 시에는 `0`이 종료 코드입니다. +- 실패 시에는 0이 아닌 상태의 종료 코드입니다. + +**스크립트에서 사용 가능한 환경 변수** + +- `ASDF_INSTALL_TYPE`: `version` 또는 `ref` +- `ASDF_INSTALL_VERSION`: + - `ASDF_INSTALL_TYPE=version`의 경우, 풀 버전 번호. + - `ASDF_INSTALL_TYPE=ref`의 경우, Git ref (태그/커밋/브랜치). +- `ASDF_INSTALL_PATH`: 툴이 설치 _되어있는_, 또는 _되어야하는_ 경로. + +**이 스크립트를 호출하는 명령어** + +- `asdf help []`: 플러그인 및 도구 문서를 출력 + +**asdf core에서 호출 시그니처** + +```bash +"${plugin_path}"/bin/help.deps +``` + +--- + +### `bin/help.config` + +**설명** + +플러그인 및 도구에 필수적 또는 선택적 설정 출력. 예를 들어, 도구를 설치하거나 컴파일하는 데 필요한 환경 변수나 기타 플래그를 설명. + +**구현 세부사항** + +- 이 스크립트의 출력되기 위해서는 `bin/help.overview`가 필요합니다. +- 자유로운 형식의 텍스트로 출력할 수 있습니다. +- 운영 체제와 설치된 툴의 버전에 맞게 출력해야합니다 (필요에 따라 `ASDF_INSTALL_VERSION` 및 `ASDF_INSTALL_TYPE` 환경 변수의 값을 사용하십시오). +- 성공 시에는 `0`이 종료 코드입니다. +- 실패 시에는 0이 아닌 상태의 종료 코드입니다. + +**스크립트에서 사용 가능한 환경 변수** + +- `ASDF_INSTALL_TYPE`: `version` 또는 `ref` +- `ASDF_INSTALL_VERSION`: + - `ASDF_INSTALL_TYPE=version`의 경우, 풀 버전 번호. + - `ASDF_INSTALL_TYPE=ref`의 경우, Git ref (태그/커밋/브랜치). +- `ASDF_INSTALL_PATH`: 툴이 설치 _되어있는_, 또는 _되어야하는_ 경로. + +**이 스크립트를 호출하는 명령어** + +- `asdf help []`: 플러그인 및 도구 문서를 출력 + +**asdf core에서 호출 시그니처** + +```bash +"${plugin_path}"/bin/help.config +``` + +--- + +### `bin/help.links` + +**설명** + +플러그인 및 툴과 관련된 링크 목록을 출력. 한 행마다 한 개의 링크. + +```bash +Git Repository: https://github.com/vlang/v +Documentation: https://vlang.io +``` + +**구현 세부사항** + +- 이 스크립트의 출력되기 위해서는 `bin/help.overview`가 필요합니다. +- 한행마다 한 개의 링크. +- 형식은 다음 중에 하나여야합니다: + - `: <link>` + - 또는 그냥 `<link>` +- 운영 체제와 설치된 툴의 버전에 맞게 출력해야합니다 (필요에 따라 `ASDF_INSTALL_VERSION` 및 `ASDF_INSTALL_TYPE` 환경 변수의 값을 사용하십시오). +- 성공 시에는 `0`이 종료 코드입니다. +- 실패 시에는 0이 아닌 상태의 종료 코드입니다. + +**스크립트에서 사용 가능한 환경 변수** + +- `ASDF_INSTALL_TYPE`: `version` 또는 `ref` +- `ASDF_INSTALL_VERSION`: + - `ASDF_INSTALL_TYPE=version`의 경우, 풀 버전 번호. + - `ASDF_INSTALL_TYPE=ref`의 경우, Git ref (태그/커밋/브랜치). +- `ASDF_INSTALL_PATH`: 툴이 설치 _되어있는_, 또는 _되어야하는_ 경로. + +**이 스크립트를 호출하는 명령어** + +- `asdf help <name> [<version>]`: 플러그인 및 도구 문서를 출력 + +**asdf core에서 호출 시그니처** + +```bash +"${plugin_path}"/bin/help.links +``` + +--- + +### `bin/list-bin-paths` + +**설명** + +툴의 특정 버전에서 실행파일이 포함된 디렉토리 목록을 출력. + +**구현 세부사항** + +- 이 스크립트가 존재하지 않는 경우, asdf는 `"${ASDF_INSTALL_PATH}"/bin` 디렉토리 내에 있는 바이너리들을 찾아 그 바이너리를 위한 shim들을 생성합니다. +- 실행파일이 포함된 디렉토리의 경로를 공백으로 구분하여 출력합니다. +- 경로는 `ASDF_INSTALL_PATH`로의 상대 경로이어야 합니다. 출력 예시는 다음과 같습니다: + +```bash +bin tools veggies +``` + +이는 asdf가 그 파일들을 위한 shim들을 다음 위치에 생성하게 지시합니다: +- `"${ASDF_INSTALL_PATH}"/bin` +- `"${ASDF_INSTALL_PATH}"/tools` +- `"${ASDF_INSTALL_PATH}"/veggies` + +**스크립트에서 사용 가능한 환경 변수** + +- `ASDF_INSTALL_TYPE`: `version` 또는 `ref` +- `ASDF_INSTALL_VERSION`: + - `ASDF_INSTALL_TYPE=version`의 경우, 풀 버전 번호. + - `ASDF_INSTALL_TYPE=ref`의 경우, Git ref (태그/커밋/브랜치). +- `ASDF_INSTALL_PATH`: 툴이 설치 _되어있는_, 또는 _되어야하는_ 경로. + +**이 스크립트를 호출하는 명령어** + +- `asdf install <tool> [version]`: 초기에 바이너리들을 위한 shim들 생성. +- `asdf reshim <tool> <version>`: 바이너리들을 위한 shim들 재생성. + +**asdf core에서 호출 시그니처** + +```bash +"${plugin_path}/bin/list-bin-paths" +``` + +--- + +### `bin/exec-env` + +**설명** + +툴 바이너리의 shim을 실행하기 전에 환경을 준비. + +**스크립트에서 사용 가능한 환경 변수** + +- `ASDF_INSTALL_TYPE`: `version` 또는 `ref` +- `ASDF_INSTALL_VERSION`: + - `ASDF_INSTALL_TYPE=version`의 경우, 풀 버전 번호. + - `ASDF_INSTALL_TYPE=ref`의 경우, Git ref (태그/커밋/브랜치). +- `ASDF_INSTALL_PATH`: 툴이 설치 _되어있는_, 또는 _되어야하는_ 경로. + +**이 스크립트를 호출하는 명령어** + +- `asdf which <command>`: 실행파일의 경로 표시 +- `asdf exec <command> [args...]`: 현재 버전에서 shim 명령을 실행 +- `asdf env <command> [util]`: shim 명령어 실행 시 사용되는 환경에서 유틸리티(기본값: `env`)를 실행. + +**asdf core에서 호출 시그니처** + +```bash +"${plugin_path}/bin/exec-env" +``` + +--- + +### `bin/exec-path` + +툴의 특정 버전의 실행파일 경로를 가져옵니다. +실행파일에 대한 상대 경로를 문자열로 출력해야합니다. +이는 플러그인이 shim에서 지정한 실행파일 경로를 조건부로 덮어쓰게 하거나, +그렇지 않으면 shim에서 지정한 기본 경로를 반환합니다. + +**설명** + +툴의 특정 버전의 실행파일 경로를 가져옵니다. + +**구현 세부사항** + +- 실행파일에 대한 상대 경로를 문자열로 출력. +- Shim에서 지정한 실행파일 경로를 조건부로 덮어쓰거나, 그렇지 않으면 shim에서 지정한 기본 경로를 반환. + +```shell +Usage: + plugin/bin/exec-path <install-path> <command> <executable-path> + +Example Call: + ~/.asdf/plugins/foo/bin/exec-path "~/.asdf/installs/foo/1.0" "foo" "bin/foo" + +Output: + bin/foox +``` + +**스크립트에서 사용 가능한 환경 변수** + +- `ASDF_INSTALL_TYPE`: `version` 또는 `ref` +- `ASDF_INSTALL_VERSION`: + - `ASDF_INSTALL_TYPE=version`의 경우, 풀 버전 번호. + - `ASDF_INSTALL_TYPE=ref`의 경우, Git ref (태그/커밋/브랜치). +- `ASDF_INSTALL_PATH`: 툴이 설치 _되어있는_, 또는 _되어야하는_ 경로. + +**이 스크립트를 호출하는 명령어** + +- `asdf which <command>`: 실행파일의 경로 표시 +- `asdf exec <command> [args...]`: 현재 버전에서 shim 명령을 실행 +- `asdf env <command> [util]`: shim 명령어 실행 시 사용되는 환경에서 유틸리티(기본값: `env`)를 실행. + +**asdf core에서 호출 시그니처** + +```bash +"${plugin_path}/bin/exec-path" "$install_path" "$cmd" "$relative_path" +``` + +--- + +### `bin/uninstall` + +**설명** + +툴의 지정된 버전을 제거합니다. + +**출력 형식** + +출력값은 `stdout` 또는 `stderr`에 적절히 송신 되어야 합니다. 어떠한 출력값도 후속 코어 실행에 의해 사용되지 않습니다. + +**스크립트에서 사용 가능한 환경 변수** + +이 스크립트에는 환경 변수가 제공되지 않습니다. + +**이 스크립트를 호출하는 명령어** + +- `asdf list all <name> <version>` +- `asdf uninstall nodejs 18.15.0`: nodejs의 `18.15.0` 버전을 제거, `npm i -g`로 설치된 모든 글로벌 shim들 또한 제거. + +**asdf core에서 호출 시그니처** + +제공되는 매개변수는 없습니다. + +```bash +"${plugin_path}/bin/uninstall" +``` + +--- + +### `bin/list-legacy-filenames` + +**설명** + +툴 버전을 결정하는 데 사용된 레거시 설정 파일 목록을 출력. + +**구현 세부사항** + +- 파일이름들의 목록을 공백으로 구분하여 출력. + ```bash + .ruby-version .rvmrc + ``` +- `"${HOME}"/.asdfrc`에서 `legacy_version_file` 옵션을 활성화한 사용자에게만 적용됩니다. + +**스크립트에서 사용 가능한 환경 변수** + +- `ASDF_INSTALL_TYPE`: `version` 또는 `ref` +- `ASDF_INSTALL_VERSION`: + - `ASDF_INSTALL_TYPE=version`의 경우, 풀 버전 번호. + - `ASDF_INSTALL_TYPE=ref`의 경우, Git ref (태그/커밋/브랜치). +- `ASDF_INSTALL_PATH`: 툴이 설치 _되어있는_, 또는 _되어야하는_ 경로. + +**이 스크립트를 호출하는 명령어** + +툴 버전을 가져오는 모든 명령에서 호출됩니다. + +**asdf core에서 호출 시그니처** + +제공되는 매개변수는 없습니다. + +```bash +"${plugin_path}/bin/list-legacy-filenames" +``` + +--- + +### `bin/parse-legacy-file` + +**설명** + +asdf에 의해 발견된 레거시 파일을 parse하여 툴의 버전을 결정. 자바스크립트의 `package.json`이나 Go 언어의 `go.mod`와 같은 파일에서 버전 번호를 추출하는 데 유용. + +**구현 세부사항** + +- 이 스크립트가 존재하지 않는 경우, asdf는 단순히 레거시 파일을 `cat`하여 버전을 결정합니다. +- 다음과 같은 상황에서도 **결정론적**이고 항상 동일하고 정확한 버전을 반환해야합니다: + - 동일한 레거시 파일을 구문 parsing할 때. + - 무엇이 설치되어 있는지 또는 레거시 버전이 유효하거나 완전한지는 관계 없이. 일부 레거시 파일 형식은 맞지 않을 수도 있습니다. +- 아래와 같이 버전 번호를 한 줄로 출력해 주세요: + ```bash + 1.2.3 + ``` + +**스크립트에서 사용 가능한 환경 변수** + +이 스크립트가 호출되기 전에 환경 변수가 설정되지 않습니다. + +**이 스크립트를 호출하는 명령어** + +툴 버전을 가져오는 모든 명령에서 호출됩니다. + +**asdf core에서 호출 시그니처** + +이 스크립트는 레거시 파일의 내용을 읽기 위해 레거시 파일의 경로라는 하나의 인수를 받습니다. + +```bash +"${plugin_path}/bin/parse-legacy-file" "$file_path" +``` + +--- + +### `bin/post-plugin-add` + +**설명** + +이 콜백 스크립트는 asdf의 `asdf plugin add <tool>` 명령어로 플러그인이 _추가된_ **후에** 실행됩니다. + +관련된 명령어 훅들을 참조하세요: + +- `pre_asdf_plugin_add` +- `pre_asdf_plugin_add_${plugin_name}` +- `post_asdf_plugin_add` +- `post_asdf_plugin_add_${plugin_name}` + +**스크립트에서 사용 가능한 환경 변수** + +- `ASDF_PLUGIN_PATH`: 플러그인이 설치된 경로. +- `ASDF_PLUGIN_SOURCE_URL`: 플러그인 소스의 URL. 로컬 디렉토리 경로일 수 있음. + +**asdf core에서 호출 시그니처** + +제공되는 매개변수는 없습니다. + +```bash +"${plugin_path}/bin/post-plugin-add" +``` + +--- + +### `bin/post-plugin-update` + +**설명** + +이 콜백 스크립트는 asdf가 `asdf plugin update <tool> [<git-ref>]` 커맨드로 플러그인 _업데이트_ 를 다운로드한 **후에** 실행됩니다. + +관련된 명령어 훅들을 참조하세요: + +- `pre_asdf_plugin_update` +- `pre_asdf_plugin_update_${plugin_name}` +- `post_asdf_plugin_update` +- `post_asdf_plugin_update_${plugin_name}` + +**스크립트에서 사용 가능한 환경 변수** + +- `ASDF_PLUGIN_PATH`: 플러그인이 설치된 경로. +- `ASDF_PLUGIN_PREV_REF`: 플러그인의 이전 git-ref +- `ASDF_PLUGIN_POST_REF`: 플러그인의 업데이트 된 git-ref + +**asdf core에서 호출 시그니처** + +제공되는 매개변수는 없습니다. + +```bash +"${plugin_path}/bin/post-plugin-update" +``` + +--- + +### `bin/pre-plugin-remove` + +**설명** + +asdf가 `asdf plugin remove <tool>` 커맨드로 플러그인을 제거하기 **전에** 이 콜백 스크립트를 실행시키세요. + +관련된 명령어 훅들을 참조하세요: + +- `pre_asdf_plugin_remove` +- `pre_asdf_plugin_remove_${plugin_name}` +- `post_asdf_plugin_remove` +- `post_asdf_plugin_remove_${plugin_name}` + +**스크립트에서 사용 가능한 환경 변수** + +- `ASDF_PLUGIN_PATH`: 플러그인이 설치된 경로. + +**asdf core에서 호출 시그니처** + +제공되는 매개변수는 없습니다. + +```bash +"${plugin_path}/bin/pre-plugin-remove" +``` + +<!-- TODO: document command hooks --> +<!-- ## Command Hooks --> + +## asdf CLI 확장 명령어 <Badge type="danger" text="고급" vertical="middle" /> + +`lib/commands/command*.bash` 스크립트 또는 플러그인 이름을 하위명령어로 사용하여 +asdf 명령줄 인터페이스를 통해 호출할 수 있는 실행파일을 제공함으로써 +새로운 asdf 명령어를 정의할 수 있습니다. + +예를 들면, `foo`라고 하는 플러그인이 있다고 하면: + +```shell +foo/ + lib/commands/ + command.bash + command-bat.bash + command-bat-man.bash + command-help.bash +``` + +사용자는 아래 명령을 실행할 수 있게 됩니다: + +```shell +$ asdf foo # same as running `$ASDF_DATA_DIR/plugins/foo/lib/commands/command.bash` +$ asdf foo bar # same as running `$ASDF_DATA_DIR/plugins/foo/lib/commands/command.bash bar` +$ asdf foo help # same as running `$ASDF_DATA_DIR/plugins/foo/lib/commands/command-help.bash` +$ asdf foo bat man # same as running `$ASDF_DATA_DIR/plugins/foo/lib/commands/command-bat-man.bash` +$ asdf foo bat baz # same as running `$ASDF_DATA_DIR/plugins/foo/lib/commands/command-bat.bash baz` +``` + +플러그인 개발자는 이 기능을 사용하여 툴과 관련된 유틸리티를 제공하거나, +asdf 자체의 명령어 확장 플러그인을 생성할 수 있습니다. + +실행 가능 비트(executable bit)가 부여되어 있는 경우, asdf 실행을 대신하여 +해당 스크립트가 실행됩니다. + +실행 가능 비트(executable bit)가 부여되지 않은 경우, asdf는 해당 스크립트를 Bash 스크립트로 source합니다. + +`$ASDF_CMD_FILE`는 source 되는 파일의 전체 경로를 해결합니다. + +[`haxe`](https://github.com/asdf-community/asdf-haxe)는 +이 기능을 사용하는 플러그인의 좋은 예시입니다. +이 플러그인은 Haxe 실행파일이 해당 디렉토리에서 상대적으로 동적 라이브러리를 찾으려하는 +문제해결을 위해 `asdf haxe neko-dylibs-link`를 제공합니다. + +플러그인 README에는 asdf 확장 명령어에 관한 것을 반드시 기재하도록 하십시오. + +## 맞춤 Shim 템플릿 <Badge type="danger" text="고급" vertical="middle" /> + +::: warning 경고 + +**반드시** 필요한 경우에만 사용하세요. + +::: + +asdf에서는 맞춤 shim 템플릿을 사용할 수 있습니다. `foo`라고 하는 실행파일에 대해, +플러그인 내에 `shims/foo` 파일이 존재하면, asdf는 표준 shim 템플릿을 +사용하는 대신 그 파일을 복사합니다. + +**이 기능은 현명하게 사용해야합니다.** + +asdf 코어팀이 파악하고 있는 것은, 이 기능은 오직 공식 플러그인 +[Elixir 플러그인](https://github.com/asdf-vm/asdf-elixir)에서만 사용되고 있습니다. +이는 실행파일은 실행파일일 뿐만 아니라 Elixir 파일로도 읽히기 때문입니다. +이 때문에 표준 Bash shim을 사용할 수 없습니다. + +## 테스팅 + +`asdf`에는 플러그인을 테스트하기 위한 `plugin-test` 명령어가 포함되어 있습니다: + +```shell +asdf plugin test <plugin_name> <plugin_url> [--asdf-tool-version <version>] [--asdf-plugin-gitref <git_ref>] [test_command...] +``` + +- `<plugin_name>` 및 `<plugin_url>`는 필수적입니다 +- 옵션에서 `[--asdf-tool-version <version>]`를 지정하면, 해당 지정된 버전의 툴이 설치됩니다. + 기본값은 `asdf latest <plugin-name>`입니다. +- 옵션에서 `[--asdf-plugin-gitref <git_ref>]`를 지정하면, + 그 커밋/브랜치/태그로 플러그인 자체를 체크아웃합니다. + 이것은 플러그인 CI에서 풀 요청을 테스트할 때 유용합니다. +- 선택적 매개변수 `[test_command...]`는 설치된 툴이 올바르게 동작하는지 확인하기위해 실행시키는 명령어입니다. + 일반적으로 `<tool> --version` 또는 + `<tool> --help`입니다. 예를 들어, NodeJS 플러그인을 테스트하기 위해, 다음을 실행시킬 수 있습니다 + ```shell + # asdf plugin test <plugin_name> <plugin_url> [test_command] + asdf plugin test nodejs https://github.com/asdf-vm/asdf-nodejs.git node --version + ``` + +::: tip 노트 + +리눅스와 맥 운영체제 양쪽 CI 환경에서 모두 테스트하는 것을 권장합니다. + +::: + +### GitHub Action + +[asdf-vm/actions](https://github.com/asdf-vm/actions) 리포지토리는 +GitHub에서 호스팅되는 플러그인을 테스트하기 위한 GitHub Action을 제공합니다. +`.github/workflows/test.yaml` 액션 워크플로우 예시: + +```yaml +name: Test +on: + push: + branches: + - main + pull_request: + +jobs: + plugin_test: + name: asdf plugin test + strategy: + matrix: + os: + - ubuntu-latest + - macos-latest + runs-on: ${{ matrix.os }} + steps: + - name: asdf_plugin_test + uses: asdf-vm/actions/plugin-test@v2 + with: + command: "<MY_TOOL> --version" +``` + +### TravisCI 설정 + +`.travis.yml` 예시 파일, 필요에 따라 바꿔 사용하세요: + +```yaml +language: c +script: asdf plugin test <MY_TOOL> $TRAVIS_BUILD_DIR '<MY_TOOL> --version' +before_script: + - git clone https://github.com/asdf-vm/asdf.git asdf + - . asdf/asdf.sh +os: + - linux + - osx +``` + +::: tip 노트 + +다른 CI를 사용하는 경우, +플러그인 위치에 대한 상대 경로를 전달할 필요가 있는 경우가 있습니다: + +```shell +asdf plugin test <tool_name> <path> '<tool_command> --version' +``` + +::: + +## API 속도 제한 + +`bin/list-all`이나 `bin/latest-stable`과 같이 명령어가 외부 API에 대한 접근에 의존하고 있는 경우, +자동화 테스트 중에 속도 제한이 발생할 수 있습니다. +이를 줄이기 위해, 환경 변수를 통해 인증 토큰을 제공하는 코드 경로가 있는지 확인하십시오. +예를 들어: + +```shell +cmd="curl --silent" +if [ -n "$GITHUB_API_TOKEN" ]; then + cmd="$cmd -H 'Authorization: token $GITHUB_API_TOKEN'" +fi + +cmd="$cmd $releases_path" +``` + +### `GITHUB_API_TOKEN` + +`GITHUB_API_TOKEN`를 사용할 때는, +오직 `public_repo` 액세스 권환으로 +[새로운 개인 토큰](https://github.com/settings/tokens/new)을 생성합니다. + +다음으로 이 토큰을 CI pipeline 환경 변수에 추가하십시오. + +::: warning 경고 + +절대 인증 토큰을 코드 리포지토리에 공개해서는 안됩니다. + +::: + +## 플러그인 Shortname 인덱스 + +::: tip + +권장되는 플러그인 설치 방법은 URL을 바탕으로 직접 설치입니다: + +```shell +# asdf plugin add <name> <git_url> + asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs +``` + +::: + +`git_url`이 지정되지 않은 경우, +asdf는 사용될 `git_url`을 정확히 결정하기 위해 +[Shortname 인덱스 리포지토리](https://github.com/asdf-vm/asdf-plugins)를 사용합니다. + +[Shortname 인덱스](https://github.com/asdf-vm/asdf-plugins)에 +설명서에 따라 플러그인을 +해당 리포지토리에 추가할 수 있습니다.