diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index b46bba53..4754baf6 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -29,7 +29,7 @@ jobs: node-version: "20" - name: Cache dependencies - uses: actions/cache@v3 + uses: actions/cache@v4 id: npm-cache with: path: | diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index eee61a53..960ace9d 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -10,17 +10,38 @@ env: PYTHON_MIN_VERSION: "3.7.13" jobs: - asdf: + asdf-bash: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: asdf-vm/actions/install@v3 - - uses: actions/setup-python@v4 + - uses: actions/setup-python@v5 with: python-version: ${{ env.PYTHON_MIN_VERSION }} - run: scripts/install_dependencies.bash - run: scripts/lint.bash --check + asdf-golang: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Setup Go + uses: actions/setup-go@v5 + with: + go-version: '1.21.5' + - name: Install dependencies + run: go get . + - name: Check format + run: '[ -z "$(gofmt -l ./...)" ]' + - name: Vet + run: go vet + - name: Install staticcheck for linting + run: go install honnef.co/go/tools/cmd/staticcheck@latest + - name: Lint + run: staticcheck -tests -show-ignored ./... + - name: Build + run: go build -v ./... + actions: runs-on: ubuntu-latest steps: diff --git a/.github/workflows/release-build.yml b/.github/workflows/release-build.yml new file mode 100644 index 00000000..8978d137 --- /dev/null +++ b/.github/workflows/release-build.yml @@ -0,0 +1,101 @@ +name: Release (and build Golang binaries) +# This workflow should eventually replace the one in release.yml completely. + +permissions: + contents: "write" + +# Eventually this workflow will only be run when a +#on: +# push: +# tags: +# - 'v[0-9]+.*' +# Typically we'd only want to build binaries and a release when a new tag is +# pushed. But since this is a new projectu I'm doing it on every new commit to +# the master branch. This will make it easy to download and test binaries for +# each new version. +on: + push: + branches: + - master + +# TODO: Uncomment once this is merged and we're ready to prepare the first +# public tagged version of the Golang implementation. +#jobs: +# release: +# runs-on: ubuntu-latest +# steps: +# - uses: GoogleCloudPlatform/release-please-action@v4 +# name: create release +# with: +# release-type: simple +# bump-minor-pre-major: true # remove this to enable breaking changes causing 1.0.0 tag +# changelog-types: | +# [ +# { "type": "feat", "section": "Features", "hidden": false }, +# { "type": "fix", "section": "Patches", "hidden": false }, +# { "type": "docs", "section": "Documentation", "hidden": false } +# ] +# extra-files: | +# SECURITY.md +# docs/guide/getting-started.md +# docs/pt-br/guide/getting-started.md +# docs/zh-hans/guide/getting-started.md + +jobs: + + create-release: + name: create-release + runs-on: ubuntu-22.04 + # env: + # Set to force version number, e.g., when no tag exists. + # ASDF_VERSION: TEST-0.1.0 + outputs: + upload_url: ${{ steps.release.outputs.upload_url }} + asdf_version: ${{ env.ASDF_VERSION }} + steps: + - name: Get the release version from the tag + shell: bash + if: env.ASDF_VERSION == '' + run: | + # Apparently, this is the right way to get a tag name. Really? + # + # See: https://github.community/t5/GitHub-Actions/How-to-get-just-the-tag-name/m-p/32167/highlight/true#M1027 + #echo "ASDF_VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_ENV + # Once we're using this for real releases we'll want to change this + # line below to contain the actual tag name + echo "ASDF_VERSION=0.0.0" >> "$GITHUB_ENV" + echo "version is: ${{ env.ASDF_VERSION }}" + - uses: actions/checkout@v3 + - name: Create GitHub release + id: release + uses: ncipollo/release-action@v1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + tag: ${{ env.ASDF_VERSION }} + name: ${{ env.ASDF_VERSION }} + + build: + needs: create-release + runs-on: ubuntu-latest + steps: + - + name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + - + name: Set up Go + uses: actions/setup-go@v5 + with: + go-version: '1.21.5' + cache: true + - + name: Run GoReleaser + # Downgraded to version 4 to get snapshot feature working + uses: goreleaser/goreleaser-action@v4 + with: + version: latest + args: release --clean --snapshot + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index e3fc771f..ce819ad3 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -9,7 +9,7 @@ jobs: release: runs-on: ubuntu-latest steps: - - uses: GoogleCloudPlatform/release-please-action@v3 + - uses: GoogleCloudPlatform/release-please-action@v4 name: create release with: release-type: simple diff --git a/.github/workflows/semantic-pr.yml b/.github/workflows/semantic-pr.yml index a95230be..566cb8a9 100644 --- a/.github/workflows/semantic-pr.yml +++ b/.github/workflows/semantic-pr.yml @@ -14,3 +14,17 @@ jobs: - uses: amannn/action-semantic-pull-request@v5.4.0 env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + scopes: | + # The scope for all the Golang rewrite commits + golang-rewrite + # A list of all used scopes can be computed by running this command: + # + # git log --pretty=format:%s | rg '^[^: ]*\(([^):]*)\).*' -r '$1' | sort | uniq + # + # We only want to allow a limited set of scopes going forward, so + # the list of valid scopes has been pared down here. + docs + website + plugin + completions diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index b3e9301e..cc4362d5 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -9,8 +9,6 @@ on: jobs: detect-changes: runs-on: ubuntu-latest - permissions: - pull-requests: read # Set job outputs to values from filter step outputs: documentation: ${{ steps.filter.outputs.documentation }} @@ -37,6 +35,22 @@ jobs: - 'defaults' - 'help.txt' + test-golang: + needs: detect-changes + if: ${{ needs.detect-changes.outputs.cli == 'true' }} + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Setup Go + uses: actions/setup-go@v5 + with: + go-version: '1.21.5' + - run: scripts/install_dependencies.bash + - name: Install dependencies + run: go get . + - name: Run Go tests + run: go test + ubuntu: needs: detect-changes # only run if @@ -85,7 +99,7 @@ jobs: with: node-version: "18" - - uses: actions/cache@v3 + - uses: actions/cache@v4 id: npm-cache with: path: | diff --git a/.gitignore b/.gitignore index 69ca2959..2e1e0325 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,5 @@ repository .vagrant keyrings /tmp + +dist/ diff --git a/.goreleaser.yaml b/.goreleaser.yaml new file mode 100644 index 00000000..9f2ee078 --- /dev/null +++ b/.goreleaser.yaml @@ -0,0 +1,51 @@ +# This is an example .goreleaser.yml file with some sensible defaults. +# Make sure to check the documentation at https://goreleaser.com + +# The lines below are called `modelines`. See `:help modeline` +# Feel free to remove those if you don't want/need to use them. +# yaml-language-server: $schema=https://goreleaser.com/static/schema.json +# vim: set ts=2 sw=2 tw=0 fo=cnqoj + +version: 1 + +before: + hooks: + # You may remove this if you don't use go modules. + - go mod tidy + # you may remove this if you don't need go generate + - go generate ./... + +builds: + - env: + - CGO_ENABLED=0 + goos: + - linux + - windows + - darwin + +archives: + - format: tar.gz + # this name template makes the OS and Arch compatible with the results of `uname`. + name_template: >- + {{ .ProjectName }}_ + {{- title .Os }}_ + {{- if eq .Arch "amd64" }}x86_64 + {{- else if eq .Arch "386" }}i386 + {{- else }}{{ .Arch }}{{ end }} + {{- if .Arm }}v{{ .Arm }}{{ end }} + # use zip for windows archives + format_overrides: + - goos: windows + format: zip + +changelog: + sort: asc + filters: + exclude: + - "^docs:" + - "^test:" + +snapshot: + # Dev prefix for snapshot builds as theses aren't intended for anything other + # than testing. + name_template: 'dev-{{ .Version }}-{{ .ShortCommit }}' diff --git a/.tool-versions b/.tool-versions index 43c2e079..f0ce08ce 100644 --- a/.tool-versions +++ b/.tool-versions @@ -1,3 +1,4 @@ +golang 1.21.5 bats 1.8.2 shellcheck 0.9.0 shfmt 3.6.0 diff --git a/CHANGELOG.md b/CHANGELOG.md index b6473f3d..d68a0f06 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,33 @@ # Changelog +## [0.14.0](https://github.com/asdf-vm/asdf/compare/v0.13.1...v0.14.0) (2024-01-19) + + +### ⚠ BREAKING CHANGES + +* Enable `pipefail` ([#1608](https://github.com/asdf-vm/asdf/issues/1608)) + +### Patches + +* `plugin test` git-ref to use plugin repo default branch ([#1694](https://github.com/asdf-vm/asdf/issues/1694)) ([6d8cf9d](https://github.com/asdf-vm/asdf/commit/6d8cf9d44b3d985ac59f1eac827c5275392f90fd)) +* avoid mention of `ASDF_NU_DIR` ([#1660](https://github.com/asdf-vm/asdf/issues/1660)) ([dfea89c](https://github.com/asdf-vm/asdf/commit/dfea89ccc703f3ef5a87c4b85726456d70167d89)) +* Enable `pipefail` ([#1608](https://github.com/asdf-vm/asdf/issues/1608)) ([4085e55](https://github.com/asdf-vm/asdf/commit/4085e5542bac824ea124610ad247c2f90d1b8d93)) +* **fish:** use PATH instead of fish_user_paths ([#1709](https://github.com/asdf-vm/asdf/issues/1709)) ([5327697](https://github.com/asdf-vm/asdf/commit/53276973f7c99695cd9a28b04c010b006d7f60ca)) +* list `asdf version` command under help.txt UTILS section ([#1673](https://github.com/asdf-vm/asdf/issues/1673)) ([240a5fb](https://github.com/asdf-vm/asdf/commit/240a5fbdea1de055672d02f83db1de990ea2bf83)) +* **nushell:** Use `def --env` instead of `def-env` ([#1681](https://github.com/asdf-vm/asdf/issues/1681)) ([3b8f400](https://github.com/asdf-vm/asdf/commit/3b8f400c3e628851286bfebd8da5bc7ab45cd676)) +* plugin extension commands to not require `bin/` directory ([#1643](https://github.com/asdf-vm/asdf/issues/1643)) ([61420ad](https://github.com/asdf-vm/asdf/commit/61420ad90829b2c9bf1ca16681a2eb652adcc755)) +* use universal scope for fish_user_paths ([#1699](https://github.com/asdf-vm/asdf/issues/1699)) ([0ffee72](https://github.com/asdf-vm/asdf/commit/0ffee7224bc00a917ceaea689c6268fd1f03bd62)) +* warn if plugin does not support keeping downloads if configured ([#1644](https://github.com/asdf-vm/asdf/issues/1644)) ([19515ed](https://github.com/asdf-vm/asdf/commit/19515eda3b91167b0d76c35ffc4402de688007e0)) + + +### Documentation + +* add Japanese translation ([#1667](https://github.com/asdf-vm/asdf/issues/1667)) ([2b9bec7](https://github.com/asdf-vm/asdf/commit/2b9bec7710cd18e51a01652e1f58cc309baf2fd7)) +* fix some pt-br spelling ([#1640](https://github.com/asdf-vm/asdf/issues/1640)) ([0c7c41a](https://github.com/asdf-vm/asdf/commit/0c7c41ab44d3a42a9e57e3d20a646569c2eacfdc)) +* fix typo "node version" filename ([#1679](https://github.com/asdf-vm/asdf/issues/1679)) ([fad23bc](https://github.com/asdf-vm/asdf/commit/fad23bc9f4d38747f28d6708ab01689749030063)) +* fix typo ([#1670](https://github.com/asdf-vm/asdf/issues/1670)) ([5737fa3](https://github.com/asdf-vm/asdf/commit/5737fa316eab01c4033565eacf678222cd861f8d)) +* Improve `.asdfrc` plugin hook docuentation ([#1661](https://github.com/asdf-vm/asdf/issues/1661)) ([8fbf9a3](https://github.com/asdf-vm/asdf/commit/8fbf9a396bd4a5b71ec7cf215d12040fb5365d6a)) + ## [0.13.1](https://github.com/asdf-vm/asdf/compare/v0.13.0...v0.13.1) (2023-09-12) diff --git a/SECURITY.md b/SECURITY.md index f831592f..79502c55 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -9,7 +9,7 @@ not covered under this security policy.** ``` -0.13.1 +0.14.0 ``` diff --git a/asdf.fish b/asdf.fish index 6f7a3050..20024eff 100644 --- a/asdf.fish +++ b/asdf.fish @@ -11,12 +11,12 @@ else end # Do not use fish_add_path (added in Fish 3.2) because it -# potentially changes the order of items in fish_user_paths -if not contains $_asdf_bin $fish_user_paths - set --global --prepend fish_user_paths $_asdf_bin +# potentially changes the order of items in PATH +if not contains $_asdf_bin $PATH + set -gx --prepend PATH $_asdf_bin end -if not contains $_asdf_shims $fish_user_paths - set --global --prepend fish_user_paths $_asdf_shims +if not contains $_asdf_shims $PATH + set -gx --prepend PATH $_asdf_shims end set --erase _asdf_bin set --erase _asdf_shims diff --git a/asdf.nu b/asdf.nu index 90940201..244f6422 100644 --- a/asdf.nu +++ b/asdf.nu @@ -1,14 +1,27 @@ -def-env configure-asdf [] { - - $env.ASDF_DIR = ( if ( $env | get --ignore-errors ASDF_DIR | is-empty ) { $env.ASDF_NU_DIR } else { $env.ASDF_DIR } ) - - let shims_dir = ( if ( $env | get --ignore-errors ASDF_DATA_DIR | is-empty ) { $env.HOME | path join '.asdf' } else { $env.ASDF_DIR } | path join 'shims' ) - +def --env configure-asdf [] { + $env.ASDF_DIR = ( + if ($env | get --ignore-errors ASDF_NU_DIR | is-empty) == false { + $env.ASDF_NU_DIR + } + else if ($env | get --ignore-errors ASDF_DIR | is-empty) == false { + $env.ASDF_DIR + } else { + print --stderr "asdf: Either ASDF_NU_DIR or ASDF_DIR must not be empty" + return + } + ) + + let shims_dir = ( + if ( $env | get --ignore-errors ASDF_DATA_DIR | is-empty ) { + $env.HOME | path join '.asdf' + } else { + $env.ASDF_DIR + } | path join 'shims' + ) let asdf_bin_dir = ( $env.ASDF_DIR | path join 'bin' ) $env.PATH = ( $env.PATH | split row (char esep) | where { |p| $p != $shims_dir } | prepend $shims_dir ) $env.PATH = ( $env.PATH | split row (char esep) | where { |p| $p != $asdf_bin_dir } | prepend $asdf_bin_dir ) - } configure-asdf diff --git a/bin/asdf b/bin/asdf index 4a15f61f..439fd181 100755 --- a/bin/asdf +++ b/bin/asdf @@ -1,5 +1,9 @@ #!/usr/bin/env bash + set -o pipefail +if [[ "${ASDF_DEBUG}" == "1" ]]; then + set -x +fi # shellcheck source=lib/utils.bash . "$(dirname "$(dirname "$0")")/lib/utils.bash" diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index cc55d47f..48ef1bac 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -16,6 +16,14 @@ export default defineConfig({ sidebar: sidebars.en, }, }, + "ja-jp": { + label: "日本語", + lang: "ja-jp", + themeConfig: { + nav: navbars.ja_jp, + sidebar: sidebars.ja_jp, + }, + }, "pt-br": { label: "Brazilian Portuguese", lang: "pr-br", diff --git a/docs/.vitepress/navbars.ts b/docs/.vitepress/navbars.ts index 81393199..e2db0b88 100644 --- a/docs/.vitepress/navbars.ts +++ b/docs/.vitepress/navbars.ts @@ -32,6 +32,24 @@ const en = [ }, ]; +const ja_jp = [ + { text: "ガイド", link: "/ja-jp/guide/getting-started" }, + { + text: "リファレンス", + link: "/ja-jp/manage/configuration", + }, + { + text: getVersion(), + items: [ + { + text: "変更履歴", + link: "https://github.com/asdf-vm/asdf/blob/master/CHANGELOG.md", + }, + { text: "コントリビューション", link: "/ja-jp/contribute/core" }, + ], + }, +]; + const pt_br = [ { text: "Guia", link: "/pt-br/guide/getting-started" }, { @@ -68,4 +86,4 @@ const zh_hans = [ }, ]; -export { en, pt_br, zh_hans }; +export { en, ja_jp, pt_br, zh_hans }; diff --git a/docs/.vitepress/sidebars.ts b/docs/.vitepress/sidebars.ts index 4435673d..e9afe653 100644 --- a/docs/.vitepress/sidebars.ts +++ b/docs/.vitepress/sidebars.ts @@ -110,6 +110,118 @@ const en = [ { text: "Thanks", link: "/more/thanks" }, ]; +const ja_jp = [ + { + text: "ガイド", + collapsed: false, + items: [ + { text: "asdfってなに?", link: "/ja-jp/guide/introduction" }, + { text: "はじめよう", link: "/ja-jp/guide/getting-started" }, + ], + }, + { + text: "使い方", + collapsed: false, + items: [ + { text: "コア", link: "/ja-jp/manage/core" }, + { text: "プラグイン", link: "/ja-jp/manage/plugins" }, + { text: "バージョン", link: "/ja-jp/manage/versions" }, + ], + }, + { + text: "リファレンス", + collapsed: false, + items: [ + { text: "構成設定", link: "/ja-jp/manage/configuration" }, + { text: "すべてのコマンド", link: "/ja-jp/manage/commands" }, + { + text: "プラグインショートネームの一覧", + link: "https://github.com/asdf-vm/asdf-plugins", + }, + ], + }, + { + text: "プラグイン", + collapsed: true, + items: [ + { + text: "開発者向け", + items: [ + { text: "プラグインの作成", link: "/ja-jp/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: "FAQ", link: "/ja-jp/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: "/ja-jp/contribute/core" }, + { text: "ドキュメント", link: "/ja-jp/contribute/documentation" }, + { + text: "公式プラグイン", + link: "/ja-jp/contribute/first-party-plugins", + }, + { text: "GitHub Actions", link: "/ja-jp/contribute/github-actions" }, + ], + }, + { text: "コミュニティプロジェクト", link: "/ja-jp/more/community-projects" }, + { text: "謝辞", link: "/ja-jp/more/thanks" }, +]; + const pt_br = [ { text: "Guia", @@ -334,4 +446,4 @@ const zh_hans = [ { text: "致谢", link: "/zh-hans/more/thanks" }, ]; -export { en, pt_br, zh_hans }; +export { en, ja_jp, pt_br, zh_hans }; diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index de5326a5..9c80faf0 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -36,7 +36,7 @@ asdf primarily requires `git` & `curl`. Here is a _non-exhaustive_ list of comma ```shell -git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.13.1 +git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.0 ``` @@ -300,7 +300,7 @@ Add the following to `~/.config/powershell/profile.ps1`: Add `asdf.nu` to your `~/.config/nushell/config.nu` with: ```shell -"\n$env.ASDF_NU_DIR = ($env.HOME | path join '.asdf')\n source " + ($env.HOME | path join '.asdf/asdf.nu') | save --append $nu.config-path +"\n$env.ASDF_DIR = ($env.HOME | path join '.asdf')\n source " + ($env.HOME | path join '.asdf/asdf.nu') | save --append $nu.config-path ``` Completions are automatically configured @@ -311,7 +311,7 @@ Completions are automatically configured Add `asdf.nu` to your `~/.config/nushell/config.nu` with: ```shell -"\n$env.ASDF_NU_DIR = (brew --prefix asdf | str trim | into string | path join 'libexec')\n source " + (brew --prefix asdf | into string | path join 'libexec/asdf.nu') | save --append $nu.config-path +"\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 ``` Completions are automatically configured @@ -322,7 +322,7 @@ Completions are automatically configured Add `asdf.nu` to your `~/.config/nushell/config.nu` with: ```shell -"\n$env.ASDF_NU_DIR = '/opt/asdf-vm/'\n source /opt/asdf-vm/asdf.nu" | save --append $nu.config-path +"\n$env.ASDF_DIR = '/opt/asdf-vm/'\n source /opt/asdf-vm/asdf.nu" | save --append $nu.config-path ``` Completions are automatically configured. diff --git a/docs/ja-jp/contribute/core.md b/docs/ja-jp/contribute/core.md new file mode 100644 index 00000000..4176b238 --- /dev/null +++ b/docs/ja-jp/contribute/core.md @@ -0,0 +1,158 @@ +# asdf + +これは、`asdf`コアのコントリビューションガイドです。 + +## 初期セットアップ + +GitHubで`asdf`をフォークするか、デフォルトのブランチをGitクローンしてください: + +```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をサポートするシェルパーサ、フォーマッタ、インタプリタです。 + +## 開発 + +インストール済みの`asdf`に変更を加えずに、あなたが開発した変更内容を試したいときは、`$ASDF_DIR`変数に、クローンしたリポジトリのパスを設定し、そのディレクトリの`bin`と`shims`ディレクトリを一時的にパスの先頭へ追加します。 + +リモートにコミットまたはプッシュする前に、コードをローカルでフォーマット、Lint、およびテストすることを推奨します。その際は、次のスクリプト/コマンドを使用してください: + +```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`ファイルです。プロジェクト固有のファイルは無視をしています。使用しているOS、ツール、およびワークフロー固有のファイルは、グローバルな`.gitignore`構成で無視する必要があります。詳しくは[こちら](http://stratus3d.com/blog/2018/06/03/stop-excluding-editor-temp-files-in-gitignore/)をご覧ください。 + +@[Gitignoreコード](https://github.com/asdf-vm/asdf/blob/master/.gitignore) + +### `.git-blame-ignore-revs` + +`asdf`では、`.git-blame-ignore-revs`を使用して、Blameを実行する際のノイズを減らしています。詳しくは、[git blameのドキュメント](https://git-scm.com/docs/git-blame)をご覧ください。 + +`git blame`を実行するときは、下記のように、このファイルと共に使います: + +```sh +git blame --ignore-revs-file .git-blame-ignore-revs ./test/install_command.bats +``` + +毎回手動でファイルを指定しなくても、gitのオプションで、`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`フラグを指定してTAP出力を有効にすると、テスト実行中に特殊なファイルディスクリプタ`>&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)で説明されています。 + +## プルリクエスト、リリース、Conventional Commits + +`asdf`は、[Release Please](https://github.com/googleapis/release-please)という自動リリースツールを使用して、[セマンティックバージョン](https://semver.org/)を自動的に引き上げ、[Changelog](https://github.com/asdf-vm/asdf/blob/master/CHANGELOG.md)を生成しています。この情報は、前回のリリースからのコミット履歴を読み込むことで生成されます。 + +[Conventional Commit messages](https://www.conventionalcommits.org/ja/)では、デフォルトブランチでのコミットメッセージのフォーマットとなる、プルリクエストタイトルのフォーマットを定義しています。これは、GitHub Action[`amannn/action-semantic-pull-request`](https://github.com/amannn/action-semantic-pull-request)で強制されます。 + +Conventional Commitは、下記のフォーマットに従います: + +``` +[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`。 + +- `!`: 破壊的変更を示します +- `fix`: セマンティックバージョンの`patch`を新しく作成します +- `feat`: セマンティックバージョンの`minor`を新しく作成します +- `!`: セマンティックバージョンの`major`を新しく作成します + +プルリクエストのタイトルは、このフォーマットに従う必要があります。 + +::: tip ヒント + +プルリクエストのタイトルには、Conventional Commit messageのフォーマットを使用してください。 + +::: + +## Dockerイメージ + +[asdf-alpine](https://github.com/vic/asdf-alpine)および[asdf-ubuntu](https://github.com/vic/asdf-ubuntu)プロジェクトは、一部のasdfツールのDocker化されたイメージを提供する取り組みを継続的に行っています。これらのDockerイメージは、開発用サーバのベースとしたり、本番用アプリケーションの実行用途として使用することができます。 diff --git a/docs/ja-jp/contribute/documentation.md b/docs/ja-jp/contribute/documentation.md new file mode 100644 index 00000000..1be6f733 --- /dev/null +++ b/docs/ja-jp/contribute/documentation.md @@ -0,0 +1,132 @@ +# ドキュメント & サイト + +これは、ドキュメントおよびサイトのコントリビューションガイドです。 + +## 初期セットアップ + +GitHubで`asdf`をフォークするか、デフォルトのブランチをGitクローンしてください: + +```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の依存関係をインストールしてください: + +```shell +npm install +``` + +## 開発 + +[VitePress (v2)](https://vitepress.dev/)は、asdfドキュメントサイトを構築するために使用している静的サイトジェネレータ(SSG)です。類似ツールである[Docsify.js](https://docsify.js.org/)やVuePressに代わってVitePressが採用されたのは、ユーザがJavaScriptを使用できない、または有効にしていない場合に、HTMLのみのフォールバックをサポートしたいからでした。これは、DocsifyとVitePressがVuePressに急速に取って代わっていた場合には不可能でした。これ以外の機能セットはほとんど同じで、最小限の構成でMarkdownファイルを書くことに重点を置いています。 + +`package.json`には、開発に必要なスクリプトが含まれています: + +@[`package.json`のコード](https://github.com/asdf-vm/asdf/blob/master/docs/package.json#L3-L5) + +ローカルの開発サーバを起動するには、次のように実行します: + +```shell +npm run dev +``` + +コミットする前にコードをフォーマットするには、次のように実行します: + +```shell +npm run format +``` + +## プルリクエスト、リリース、Conventional Commits + +`asdf`は、プルリクエストタイトルのConventional Commitsに依存する自動リリースパイプラインを使用しています。詳しくは、[コアのコントリビューションガイド](./core.md)のドキュメントに記述されています。 + +ドキュメントの変更に関するプルリクエストを作成する場合、プルリクエストのタイトルは、Conventional Commit typeを`docs`として、`docs: `というフォーマットで作成するようにしてください。 + +## Vitepress + +サイトの構成設定は、構成を示すために使用されるJSオブジェクト含んだ、いくつかのTypeScriptファイルに記述されています。以下のとおりです: + +- `docs/.vitepress/config.js`: サイトのルート構成ファイルです。仕様については、[VitePressのドキュメント](https://vitepress.dev/reference/site-config)をご覧ください。 + +ルート構成ファイルを簡素化するために、 _Navバー_ と _サイドバー_ の構成を示す大きなJSオブジェクトについては、別ファイルに切り出されており、かつ、ロケールごとに分類されています。次の両方のファイルを参照してください: + +- `docs/.vitepress/navbars.js` +- `docs/.vitepress/sidebars.js` + +これらの構成設定に関する公式ドキュメントは、[Default Theme Reference](https://vitepress.dev/reference/default-theme-config)をご覧ください。 + +## I18n + +VitePressは、国際化対応に関して最高のサポートを備えています。 +ルート構成ファイルである`docs/.vitepress/config.js`では、サポートされているロケールとそのURL、ドロップメニューのタイトル、Navバー/サイドバーの構成への参照を定義しています。 + +Navバー/サイドバーの構成設定は前述の構成ファイルにキャプチャされ、ロケールごとに分類され、個別にエクスポートされます。 + +各ロケールのMarkdownコンテンツは、ルート構成ファイル内の`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/ja-jp/contribute/first-party-plugins.md b/docs/ja-jp/contribute/first-party-plugins.md new file mode 100644 index 00000000..7a0ce85c --- /dev/null +++ b/docs/ja-jp/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`ショートネームリポジトリ](https://github.com/asdf-vm/asdf-plugins): ポピュラーな`asdf`プラグインを検索するために`asdf`コアが使用する、ショートネームのリストです。 +- [GitHub `asdf-plugin`トピック検索](https://github.com/topics/asdf-plugin) diff --git a/docs/ja-jp/contribute/github-actions.md b/docs/ja-jp/contribute/github-actions.md new file mode 100644 index 00000000..d5e5e29f --- /dev/null +++ b/docs/ja-jp/contribute/github-actions.md @@ -0,0 +1,3 @@ +# GitHub Actions + +ご興味を持っていただきありがとうございます。既存のイシュー、議論、コントリビューションガイドについては、[asdf actions リポジトリ](https://github.com/asdf-vm/actions)をご覧ください。 diff --git a/docs/ja-jp/guide/getting-started.md b/docs/ja-jp/guide/getting-started.md new file mode 100644 index 00000000..7d87ff3b --- /dev/null +++ b/docs/ja-jp/guide/getting-started.md @@ -0,0 +1,473 @@ +# はじめよう + +`asdf`のインストールには次の手順が必要です: + +1. 依存関係のインストール +2. `asdf`コアのダウンロード +3. `asdf`のインストール +4. 管理したいツール/ランタイムごとにプラグインをインストール +5. ツール/ランタイムの特定バージョンをインストール +6. `.tool-versions`ファイルで、グローバルまたはプロジェクトのバージョンをセット + +## 1. 依存関係のインストール + +asdfの動作には`git`および`curl`が必要です。以下の表は、 _あなたが使用している_ パッケージマネージャで実行するコマンドの _一部例_ です(some might automatically install these tools in later steps)。 + +| OS | パッケージマネージャ | コマンド | +| ----- | -------------------- | ---------------------------------- | +| 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.13.1 + +``` + + + +### コミュニティがサポートするダウンロード方法 + +理由がない限り、`git`コマンドを使用した公式ダウンロードの手順を使用することを強く推奨します。 + +| 方法 | コマンド | +| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Homebrew | `brew install asdf` | +| Pacman | `git clone https://aur.archlinux.org/asdf-vm.git && cd asdf-vm && makepkg -si` または好みの[AURヘルパー](https://wiki.archlinux.jp/index.php/AUR_ヘルパー)を使用 | + +## 3. asdfのインストール + +あなたが使用しているシェル、OS、およびインストール方法によって、ここでの設定方法が変わります。最も適したものを選択してください。 + +**masOSユーザの方は、この節の最後にある`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.jp/index.php/Bash#プログラムとオプションを追加)をインストールします。 +::: + +::: 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.sh`を追加します: + +```shell +echo -e "\nsource "(brew --prefix asdf)"/libexec/asdf.fish" >> ~/.config/fish/config.fish +``` + +コマンド補完は、[Fish shellの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 + +下記コマンドで、`~/.config/elvish/rc.elv`に`asdf.elv`を追加します: + +```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 for oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/asdf)のようなZSHフレームワークプラグインを使用して、このスクリプトをsourceし、コマンド補完をセットアップします。 + +コマンド補完は、ZSHフレームワークの`asdf`プラグインで設定するか、`~/.zshrc`に下記の行を追記することで設定できます: + +```shell +# append completions to fpath +fpath=(${ASDF_DIR}/completions $fpath) +# initialise completions with ZSH's compinit +autoload -Uz compinit && compinit +``` + +- `compinit`のセットアップをカスタマイズしている場合は、`asdf.sh`ソース以下に`compinit`がくるようにしてください。 +- ZSHフレームワークで`compinit`のセットアップをカスタマイズしている場合は、フレームワークソース以下に`compinit`がくるようにしてください。 + +**警告** + +ZSHフレームワークを使用している場合、新しいZSHコマンド補完を使用するには、`fpath`経由で、関連する`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 +``` + +**OR** use a ZSH Framework plugin like [asdf for oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/asdf) which will source this script and setup completions. + +コマンド補完は、ZSHフレームワーク`asdf`によって設定されるか、[Homebrewの説明に従って設定](https://docs.brew.sh/Shell-Completion#configuring-completions-in-zsh)必要があります。ZSHフレームワークを使用している場合、新しいZSHコマンド補完を使用するには、`fpath`経由で、関連する`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.jp/index.php/Zsh#.E3.82.B3.E3.83.9E.E3.83.B3.E3.83.89.E8.A3.9C.E5.AE.8C)。 +::: + +::: 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_NU_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_NU_DIR = (brew --prefix asdf | str trim | into string | path join 'libexec')\n source " + (brew --prefix asdf | 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_NU_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 など)を呼び出した**あと**に記述する必要があります。 + +::: warning 警告 +macOSでは、BasgまたはZSHシェルを起動すると、自動的に`path_helper`というユーティリティが呼び出されます。`path_helper`は`PATH`(および`MANPATH`)内の項目の順番を並び替えることができるため、特定の順序を必要とするツールの動作に、一貫性が無くなってしまいます。これを回避するため、macOSで`asdf`を利用するときは、強制的に`PATH`エントリの先頭に追加する(優先度を一番高くする)ようにしてください。これは、`ASDF_FORCE_PREPEND`環境変数で制御できます。 +::: + +`PATH`の変更を反映するために、シェルを再起動してください。たいていの場合、ターミナルのタブを新たに開けばOKです。 + +## コアのインストールが完了! + +これで、`asdf`のコアのインストールは完了です:tada: + +しかし、`asdf`が役に立つようになるのは、**プラグイン**をインストールしてから**ツール**をインストールし、**バージョン**を管理するようになってからです。引き続き、ガイドを進めていきましょう。 + +## 4. プラグインのインストール + +ここではデモとして、[`asdf-nodejs`](https://github.com/asdf-vm/asdf-nodejs/)プラグインを使用して[Node.js](https://nodejs.org/)をインストール・設定してみましょう。 + +### プラグインの依存関係 + +各プラグインには依存関係があるため、プラグインのリポジトリを確認しておきましょう。`asdf-nodejs`の場合、必要なものは次のとおりです: + +| OS | 依存関係インストールコマンド | +| ------------------------------ | --------------------------------------- | +| Debian | `apt-get install dirmngr gpg curl gawk` | +| CentOS/ Rocky Linux/ AlmaLinux | `yum install gnupg2 curl gawk` | +| macOS | `brew install gpg gawk` | + +一部のプラグインではインストール後の事後処理でこれらの依存関係が必要となるため、あらかじめインストールしておきましょう。 + +### プラグインのインストール + +```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`コマンドで確認できます。 + +最新版をインストールするには、次のコマンドを実行します: + +```shell +asdf install nodejs latest +``` + +::: tip 備考 +`asdf`では正確なバージョン番号を指定してください。`latest`は、現時点での最新バージョンを指定できる`asdf`のヘルパーです。 +::: + +## 6. バージョンをセット + +`asdf`は、カレントディレクトリから上位の`$HOME`ディレクトリまでに存在するすべての`.tool-versions`ファイルをもとに、ツールのバージョンを照会します。照会は、`asdf`で管理するツールを実行した際に、ジャストインタイムで行われます。 + +::: warning 警告 +ツールで指定されたバージョンが見つからない場合、**エラー**が発生します。`asdf current`コマンドを実行すると、カレントディレクトリにおいてツールのバージョンを解決可能か確認できるため、どのツールが実行に失敗するか検証することができます。 +::: + +### グローバル + +グローバルのデフォルト設定は、`$HOME/.tool-versions`で管理されます。グローバルのバージョンをセットするには、次のコマンドを実行します: + +```shell +asdf global nodejs latest +``` + +すると、`$HOME/.tool-versions`内には次のように書き込まれます: + +``` +nodejs 16.5.0 +``` + +一部のOSでは、`python`のように、`asdf`ではなくシステムが管理するツールが既にインストールされていることがあります。それを使用する場合、`asdf`に対して、バージョン管理をシステムに委任するように指示する必要があります。詳しくは、[バージョンのリファレンス](/ja-jp/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 +``` + +構成設定でのその他のオプションについて詳しくは、[構成設定](/ja-jp/manage/configuration.md)のリファレンスをご覧ください。 + +## 入門完了! + +以上で、`asdf`の入門は完了です:tada: ここまでで、プロジェクトでの`nodejs`のバージョン管理ができるようになりました。プロジェクトで使用するツールごとに、同様の手順を実施してください! + +`asdf`には使いこなすと便利なコマンドが他にもいっぱいあり、`asdf --help`コマンドまたは単に`asdf`コマンドを実行すれば、すべてのコマンドの説明を見ることができます。コマンドは大きく分けて3つのカテゴリに分けられます: + +- [`asdf`のコア](/ja-jp/manage/core.md) +- [プラグイン](/ja-jp/manage/plugins.md) +- [ツールのバージョン](/ja-jp/manage/versions.md) diff --git a/docs/ja-jp/guide/introduction.md b/docs/ja-jp/guide/introduction.md new file mode 100644 index 00000000..8fef2570 --- /dev/null +++ b/docs/ja-jp/guide/introduction.md @@ -0,0 +1,57 @@ +# イントロダクション + +`asdf`は、ツールのためのバージョンマネージャです。すべてのツールのバージョンは単一のファイル(`.tool-versions`)内で定義されるため、プロジェクトのGitリポジトリにチェックインして共有することで、チーム全員に同じーバージョンのツールを使ってもらえるようになります。 + +従来は、複数のCLIのバージョンマネージャを用意する必要があり、それぞれが異なるAPI、構成ファイル、および実装(`$PATH`の操作、Shim、環境変数など)となっていました。`asdf`は、開発ワークフローを簡素化するための単一インターフェースと構成ファイルを提供しており、シンプルなプラグインインターフェースを使って、すべてのツール・ランタイムに拡張することができます。 + +## どうやって動いているの + +シェル上で`asdf`コアがセットアップすると、特定のツールを管理するためのプラグインをインストールすることができるようになります。プラグインによってツールがインストールされると、インストールされる実行ファイルごとに[Shim]()が作成されます。これらの実行ファイルを実行しようとすると、代わりにShimが実行され、`.tool-versions`で定義されているバージョンを`asdf`が認識して、当該バージョンが実行されます。 + +## 関連プロジェクト + +### nvm / n / rbenv etc + +[nvm](https://github.com/nvm-sh/nvm)、[n](https://github.com/tj/n)、および[rbenv](https://github.com/rbenv/rbenv)のようなツールはすべて、ツールによってインストールされる実行ファイルのShimを作成するシェルスクリプトです。 + +`asdf`はこれらのツールと非常に似ていて、ツール/ランタイムのバージョン管理という分野では競合しています。`asdf`はプラグインシステムを採用し、他のツールと差別化することで、ツール/ランタイムごとのマネージャ、マネージャごとの異なるコマンド、そしてリポジトリ内の様々な`*-version`ファイルといったものを排除しています。 + + + +### direnv + +> シェルに、ディレクトリごとに環境変数をロード/アンロードできる機能を付け加えます。 + +`asdf`は環境変数を管理することはしませんが、direnvの動作を`asdf`に統合する[`asdf-direnv`](https://github.com/asdf-community/asdf-direnv)プラグインが存在します。 + +詳しくは[direnvのドキュメント](https://direnv.net/)をご覧ください。 + +### Homebrew + +> macOS(またはLinux)のためのパッケージマネージャー + +Homebrewは、パッケージとその上位の依存関係を管理します。`asdf`は上位の依存関係を管理することはしませんし、パッケージマネージャでもありません。それらの管理はユーザが負担することとなりますが、`asdf`はなるべく依存関係のリストを小さく保つように努めています。 + +詳しくは[Homebrewのドキュメント](https://brew.sh/)をご覧ください。 + +### NixOS + +> Nixは、パッケージ管理とシステム構成に独自のアプローチを取り入れたツールです。 + +NixOSは、各ツールの依存関係ツリー全体でパッケージのバージョンを正確に管理することで、真に再現可能な環境を構築することを目指しています。`asdf`でそのようなことはできません。NixOSは、独自のプログラミング言語、たくさんのCLIツール、そして60,000を超えるパッケージコレクションによって、それらの機能を支えています。 + +繰り返しになりますが、`asdf`は上位の依存関係を管理することはしませんし、パッケージマネージャでもありません。 + +詳しくは[NixOSのドキュメント](https://nixos.org/guides/how-nix-works.html)をご覧ください。 + +## なぜasdfを使うの? + +`asdf`は、プラグインシステムによって**多くの**ツールをサポートしており、シェル構成にたった1行の**シェル**スクリプトを記述するだけで使えるというシンプルさ・親しみやすさによって、チームが**確実に**同じバージョンのツールを使用することを保証できます。 + +::: tip Note +`asdf`はシステムのパッケージマネージャになることを目指してはいません。あくまで、ツールのバージョンマネージャです。プラグインを作成することで、どのようなツールでも`asdf`で管理できるようになりますが、それがそのツールにとって最善の方法であるとは限りませんのでご注意ください。 +::: diff --git a/docs/ja-jp/index.md b/docs/ja-jp/index.md new file mode 100644 index 00000000..af14f8d8 --- /dev/null +++ b/docs/ja-jp/index.md @@ -0,0 +1,39 @@ +--- +# https://vitepress.dev/reference/default-theme-home-page +layout: home + +hero: + name: asdf + text: マルチランタイム
バージョンマネージャ + tagline: 1つのツールですべてのランタイムのバージョンを管理しましょう! + actions: + - theme: brand + text: はじめよう + link: /ja-jp/guide/getting-started + - theme: alt + text: asdfってなに? + link: /ja-jp/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: "CI/CDワークフローで、.tool-versionsをインストールし利用するためのGitHub Actionを提供しています。" + icon: 🤖 +--- diff --git a/docs/ja-jp/manage/commands.md b/docs/ja-jp/manage/commands.md new file mode 100644 index 00000000..7c4bad54 --- /dev/null +++ b/docs/ja-jp/manage/commands.md @@ -0,0 +1,5 @@ +# すべてのコマンド + +`asdf`で利用可能なすべてのコマンドの一覧です。この一覧は、`asdf help`コマンドで表示されるテキストです。 + +<<< @../../help.txt diff --git a/docs/ja-jp/manage/configuration.md b/docs/ja-jp/manage/configuration.md new file mode 100644 index 00000000..89c02976 --- /dev/null +++ b/docs/ja-jp/manage/configuration.md @@ -0,0 +1,236 @@ +# 構成設定 + +`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` or `ref:39cb398vb39` - 指定されたタグ/コミット/ブランチをgithubからダウンロードし、コンパイルされます。 +- `path:~/src/elixir` - 使用するツールをカスタムコンパイルしたバージョンへのパスです。言語開発者などが使用します。 +- `system` - このキーワードを指定した場合、asdfが管理していない、システム上のツールバージョンへパススルーします。 + +::: tip ヒント + +スペースで区切れば、複数のバージョンを指定できます。例えば、Python `3.7.2`を使用し、Python `2.7.15`にフォールバックし、最終的に`system`のPythonにフォールバックさせるには、`.tool-versions`に下記の行を追記します。 + +``` +python 3.7.2 2.7.15 system +``` + +::: + +`.tool-versions`ファイルで定義されているすべてのツールをインストールするには、`.tool-versions`ファイルを含むディレクトリで、`asdf install`コマンドを引数を指定せずに実行します。 + +`.tool-versions`ファイルで定義されている単一のツールをインストールするには、`.tool-versions`ファイルを含むディレクトリで、`asdf install `コマンドを実行します。ツールは、`.tool-versions`ファイルで指定されたバージョンでインストールされます。 + +ファイルは、直接編集するか、`asdf local`コマンド(または`asdf global`コマンド)を使用して更新してください。 + +## `.asdfrc` + +`.asdfrc`では、ユーザのマシン固有の構成を設定します。 + +asdfはデフォルトで`${HOME}/.asdfrc`に構成ファイルを配置します。ファイルの場所は、[`ASDF_CONFIG_FILE`環境変数](#asdf-config-file)で設定できます。 + +下記は、構成に必要な項目とそのデフォルト値を示しています: + +```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` + +**対応している**プラグインの場合、他のバージョンマネージャで使用されているバージョンファイルを読み込むことができます。例えば、Rubyの`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プラグインのショートネームリポジトリの同期を無効化します。ショートネームリポジトリが無効となっている場合、同期イベントはすぐに終了します。 + +| オプション | 説明 | +| :------------------------------------------------------------ | :----------------------------------------------------------------------------- | +| `no` | 同期イベントが発生した際に、asdfプラグインリポジトリをクローンまたは更新します | +| `yes` | プラグインショートネームリポジトリを無効化します | + +同期は、以下のコマンドが実行されたときに発生します: + +- `asdf plugin add ` +- `asdf plugin list all` + +`asdf plugin add `コマンドでは、プラグインの同期はトリガーされません。 + +::: warning 備考 + +プラグインショートネームリポジトリを無効化しても、すでに同期されたリポジトリは削除されません。プラグインリポジトリを削除するには、`rm --recursive --trash $ASDF_DATA_DIR/repository`コマンドを実行してください。 + +また、プラグインショートネームリポジトリを無効化しても、以前にこのソースからインストールされたプラグインは削除されません。プラグインを削除するには、`asdf plugin remove `コマンドを実行してください。プラグインを削除すると、そのプラグインでインストールされたすべてのツールバージョンが削除されます。 + +::: + +### `concurrency` + +コンパイル時に使用するデフォルトのコア数です。 + +| Options | Description | +| :------ | :---------------------------------------------------------------------------------- | +| 整数値 | ソースコードのコンパイル時に使用するコア数です | +| `auto` | `nproc`、`sysctl hw.ncpu`、`/proc/cpuinfo`、または`1`、の優先順でコア数を計算します | + +備考: `ASDF_CONCURRENCY`環境変数が設定されている場合はそちらが優先されます。 + +## 環境変数 + +環境変数の設定値は、お使いのシステムやシェルによって異なります。デフォルトロケーションは、インストールした場所や方法(Gitクローン、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-versions`ファイルを無視したい場合を除き、この値を変更するべきではありません。 + +- 未設定の場合: `.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` + +`asdf`のShimやパスのディレクトリを`PATH`の先頭(最高優先度)に追加するかどうかを設定します。 + +- 未設定の場合: macOSでのデフォルト値は`yes`、その他のシステムでのデフォルト値は`no`です。 +- `yes`の場合: `asdf`ディレクトリを強制的に`PATH`の先頭に配置します。 +- `yes`以外の文字列を設定した場合: `asdf`ディレクトリを強制的に`PATH`の先頭に配置することは _しません_ 。 +- Usage: `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`が存在するので、`$HOME/.asdf`が使用されます。 | +| 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/ja-jp/manage/core.md b/docs/ja-jp/manage/core.md new file mode 100644 index 00000000..0005b48f --- /dev/null +++ b/docs/ja-jp/manage/core.md @@ -0,0 +1,456 @@ +# コア + +コアとなる`asdf`のコマンドはかなり少量ですが、多くのワークフローを円滑に進めることができます。 + +## インストール & セットアップ + +[はじめよう](/ja-jp/guide/getting-started.md)のガイドで説明されています。 + +## 実行 + +```shell +asdf exec [args...] +``` + +現在のバージョンのShimでコマンドを実行します。 + + + +## 環境変数 + +```shell +asdf env [util] +``` + + + +## 情報 + +```shell +asdf info +``` + +OS、シェル、および`asdf`のデバッグ情報を表示するヘルパーコマンドです。バグレポート作成時に共有してください。 + +## Shimの再作成 + +```shell +asdf reshim +``` + +特定のパッケージ・バージョンのShimを再作成します。デフォルトでは、Shimはプラグインによってツールのインストール中に作成されます。[npm CLI](https://docs.npmjs.com/cli/)などのツールは、実行ファイルをグローバルインストールができます(例:`npm install -g yarn`コマンドで[Yarn](https://yarnpkg.com/)をインストール)が、これらの実行ファイルはプラグインのライフサイクルを通してインストールされないため、Shimはまだ存在しません。そのような時に、例えば`asdf reshim nodejs `を実行すると、`nodejs`の``に対して、`yarn`のような新しい実行ファイルのShimを強制的に再作成させることができます。 + +## 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 (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/ja-jp/manage/plugins.md b/docs/ja-jp/manage/plugins.md new file mode 100644 index 00000000..26825e1a --- /dev/null +++ b/docs/ja-jp/manage/plugins.md @@ -0,0 +1,86 @@ +# プラグイン + +プラグインは、`asdf`がNode.jsやRuby、Elixirなどの様々なツールを取り扱えるようにするためのものです。 + +様々なツールをサポートするために使用されるプラグインAPIについては、[プラグインの作成](/ja-jp/plugins/create.md)をご覧ください。 + +## 追加 + +下記コマンドでは、GitのURLからプラグインを追加します: + +```shell +asdf plugin add +# asdf plugin add elm https://github.com/vic/asdf-elm +``` + +または下記のコマンドで、プラグインリポジトリのショートネームを指定して追加します: + +```shell +asdf plugin add +# asdf plugin add erlang +``` + +::: tip 推奨 + +リポジトリのショートネームに依存しないために、`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 +``` + +## 全プラグインのショートネーム一覧 + +```shell +asdf plugin list all +``` + +全プラグインのショートネーム一覧については、[プラグインショートネームの一覧](https://github.com/asdf-vm/asdf-plugins)もご覧ください。 + +## 更新 + +```shell +asdf plugin update --all +``` + +特定のプラグインパッケージを更新したい場合は、下記のように指定してください。 + +```shell +asdf plugin update +# asdf plugin update erlang +``` + +この更新コマンドは、プラグインリポジトリの _origin_ の _デフォルトブランチ_ における _最新コミット_ を取得します。バージョニングされたプラグインの更新機能については、現在開発中です([#916](https://github.com/asdf-vm/asdf/pull/916))。 + +## 削除 + +```bash +asdf plugin remove +# asdf plugin remove erlang +``` + +プラグインを削除すると、当該プラグインでインストールされたすべてのツールが削除されます。これは、各ツールの未使用バージョンを手っ取り早くクリーンアップ/プルーニングするのに有用です。 + +## ショートネームリポジトリの同期 + +ショートネームリポジトリはローカルマシンに同期され、定期的に更新されます。同期のタイミングの条件は、次のとおりです: + +- 同期イベントは、下記コマンドによってトリガーされます: + - `asdf plugin add ` + - `asdf plugin list all` +- 構成設定の`disable_plugin_short_name_repository`オプションが`yes`の場合、同期は中止されます。詳しくは[asdfの構成設定](/ja-jp/manage/configuration.md)のリファレンスをご覧ください。 +- もし、過去`X`分の間に同期が行われていない場合、同期が開始されます。 + - `X`のデフォルト値は`60`ですが、`.asdfrc`ファイルの`plugin_repository_last_check_duration`オプションで変更することができます。詳しくは[asdfの構成設定](/ja-jp/manage/configuration.md)のリファレンスをご覧ください。 diff --git a/docs/ja-jp/manage/versions.md b/docs/ja-jp/manage/versions.md new file mode 100644 index 00000000..2735cea4 --- /dev/null +++ b/docs/ja-jp/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`ファイルについて詳しくは、[構成設定のリファレンス](/ja-jp/manage/configuration.md)をご覧ください。 + +:::warning 代替手段 +現在のシェルセッションでのみバージョンを設定したい場合、 +または、特定のツールバージョンでコマンドを実行するだけのためにバージョンを設定したい場合は、 +`ASDF_${TOOL}_VERSION`という環境変数で設定することができます。 +::: + +下記の例では、バージョン`1.4.0`のElixirプロジェクトに対して、テストを実行させています。 +バージョンの表記形式は、`.tool-versions`ファイルでサポートされているものと同じです。 + +```shell +ASDF_ELIXIR_VERSION=1.4.0 mix test +``` + +## システムバージョンへの委任 + +asdfで管理されているバージョンではなく、``で指定されたツールのシステムバージョンを使用するには、バージョンとして`system`を指定します。 + +[カレントバージョンのセット](#カレントバージョンのセット)と同様の方法で、`global`、`local`、または`shell`のいずれかに`system`をセットしてください。 + +```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`)に作成されます。このディレクトリが(`asdf.sh`や`asdf.fish`などによって)`$PATH`に設定されることで、インストールされているプログラムが当該環境で利用できるようになります。 + +Shim自体は非常に単純なラッパーであり、`asdf exec`というヘルパープログラムに、プラグイン名と、Shimがラップしているインストール済みパッケージの実行ファイルのパスを渡して、`exec`します。 + +`asdf exec`ヘルパーは、使用するパッケージのバージョン(`.tool-versions`ファイルで指定されたもの、または`asdf local ...`か`asdf global ...`で指定されたもの)、パッケージのインストールディレクトリにある実行ファイルの完全パス(プラグインの`exec-path`コールバックで操作可能)、および実行環境(プラグインの`exec-env`スクリプトで提供)を決定し、実行します。 + +::: warning 備考 +本システムは`exec`呼び出しを使用するため、シェルによってsourceされるパッケージ内のスクリプトは、Shimラッパーを経由させずに直接アクセスする必要があります。`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のShimのバイパス + +何らかの理由でasdfのShimをバイパスしたい場合や、プロジェクトのディレクトリに移動した際に自動的に環境変数を設定したい場合は、[asdf-direnv](https://github.com/asdf-community/asdf-direnv)プラグインが役に立ちます。詳細はREADMEをご確認ください。 diff --git a/docs/ja-jp/more/community-projects.md b/docs/ja-jp/more/community-projects.md new file mode 100644 index 00000000..89b48e79 --- /dev/null +++ b/docs/ja-jp/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 Codespacesでasdfによるツール管理をサポートする、 + [GitHub Dev Container](https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces/introduction-to-dev-containers) + です。 + +::: warning 備考 + +asdfコアチームは、これらのプロジェクトやコードを所有していません。 +asdfコアでは、ここに掲載されているものに関連する品質やセキュリティについては責任を負いません。 + +::: diff --git a/docs/ja-jp/more/faq.md b/docs/ja-jp/more/faq.md new file mode 100644 index 00000000..56473730 --- /dev/null +++ b/docs/ja-jp/more/faq.md @@ -0,0 +1,25 @@ +# FAQ + +ここでは、`asdf`に関するよくある質問を紹介します。 + +## WSL1をサポートしていますか? + +WSL1 ([Windows Subsystem for Linux](https://ja.wikipedia.org/wiki/Windows_Subsystem_for_Linux) 1)は公式にはサポートしていません。`asdf`は正常に動作しない可能性があります。WSL1を公式にサポートする予定はありません。 + +## WSL2をサポートしていますか? + +WSL2 ([Windows Subsystem for Linux](https://ja.wikipedia.org/wiki/Windows_Subsystem_for_Linux#WSL2) 2)では、あなたが選択したWSLディストリビューションに基づいて、セットアップと依存関係の解決を済ませれば、動作するはずです。 + +重要なのは、WSL2が正常に動作するのは、カレントワークディレクトリがWindowsドライブではなくUnixドライブである場合に _限られる_ ということです。 + +GitHub Actionsでホストランナーのサポートが可能になれば、WSL2でテストスイートを実行する予定ですが、現時点ではそうではないようです。 + +## 新しくインストールした実行ファイルが実行できないのですが? + +> `npm install -g yarn`を実行したにも関わらず、`yarn`が実行できません。どうなっているの? + +`asdf`は[Shim]()を使って実行ファイルを管理しています。プラグインによってインストールされるものは、自動的にShimが作成されますが、`asdf`が管理しているツールによって実行ファイルがインストールされた場合は、Shimを作成しなければならないということを`asdf`に通知する必要があります。上記の例では、[Yarn](https://yarnpkg.com/)のShimを作成しなければいけません。詳しくは、[`asdf reshim`コマンドのドキュメント](/ja-jp/manage/core.md#shimの再作成)をご覧ください。 + +## シェルが、新しくインストールされたShimを検知してくれないのですが? + +`asdf reshim`コマンドを実行しても問題が解決しない場合、`asdf.sh`や`asdf.fish`のsourceが、シェルの構成ファイル(`.bash_profile`、`.zshrc`、`config.fish`など)の**一番下**にないことが原因である可能性があります。`$PATH`を設定した**後**、そしてフレームワーク(oh-my-zshなど)を使用しているのれあればそれをsourceした**後**に、sourceする必要があります。 diff --git a/docs/ja-jp/more/thanks.md b/docs/ja-jp/more/thanks.md new file mode 100644 index 00000000..3e1edcd2 --- /dev/null +++ b/docs/ja-jp/more/thanks.md @@ -0,0 +1,21 @@ +# 謝辞 + +このページを借りて、asdfのオーサーおよびコントリビューターの皆様に感謝を申し上げます! + +## クレジット + +私 ([@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/ja-jp/plugins/create.md b/docs/ja-jp/plugins/create.md new file mode 100644 index 00000000..e0d4705c --- /dev/null +++ b/docs/ja-jp/plugins/create.md @@ -0,0 +1,937 @@ +# プラグインの作成 + +プラグインとは、 +言語/ツールのバージョン管理をサポートするための実行スクリプトを含めたGitリポジトリのことです。 +これらのスクリプトは、`asdf list-all `や`asdf install `などの機能をサポートするコマンドを使って、 +asdfによって実行されます。 + +## クイックスタート + +オリジナルのプラグインを作成するには、次の2つの方法があります: + +1. [asdf-vm/asdf-plugin-template](https://github.com/asdf-vm/asdf-plugin-template)リポジトリを使用し、 + デフォルトのスクリプトが実装されたプラグインリポジトリ(名前は`asdf-`)を + [生成](https://github.com/asdf-vm/asdf-plugin-template/generate) + します。 + 生成できたら、 + そのリポジトリをクローンして`setup.bash`のスクリプトを実行し、 + テンプレートを対話的に更新していきます。 +2. `asdf-`という名前のリポジトリを自分で立ち上げ、 + 以降に記載されている必要なスクリプトを実装します。 + +### プラグインスクリプトの鉄則 + +- スクリプト内で他の`asdf`コマンドを呼び出しては**いけません**。 +- シェルのツール/コマンドへの依存関係を小さく保つようにしてください。 +- 移植性のないツールやコマンドフラグの使用は避けてください。 + 例えば、`sort -V`などです。 + asdfコアの[禁止コマンド一覧](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) | オペレーティングシステムに合わせた依存関係のリストを出力します。 | +| [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) | ツールのバイナリのShimを実行する前に環境を準備します。 | +| [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) | レガシーバージョンファイルのカスタムパーサーです。 | +| [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` | ソースとなるファイルのフルパスに解決されます。 | + +::: tip 備考 + +**すべてのスクリプトですべての環境変数が使用できるわけではありません。** +以下の各スクリプトのドキュメントで、そのスクリプトで利用可能な環境変数を確認してください。 + +::: + +## 必須スクリプト + +### `bin/list-all` + +**説明** + +インストール可能なすべてのバージョンをリストします。 + +**出力フォーマット** + +**スペース区切り**のバージョンリストの文字列を出力する必要があります。例えば次のとおりです: + +```txt +1.0.1 1.0.2 1.3.0 1.4 +``` + +最新バージョンが末尾にくる必要があります。 + +asdfコアは各バージョンを1行ずつ表示するため、 +いくつかのバージョンは画面外にはみ出る場合があります。 + +**並べ替え** + +ウェブサイト上のリリースページからバージョンを取得する場合、 +提供されている順序は正しいリリース順となっていることが多いため、 +そのままの順序を使用することを推奨します。 +逆順にしたければ、`tsc`をパイプで通すだけで十分です。 + +どうしても並べ替えが避けられない場合、`sort -V`は移植性が無いため、次のいずれかの方法を使用することを推奨します: + +- [Git sort capabilityを使用する](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`: このスクリプトで返されるすべてのバージョンを、 + 1行ずつリストします。 +- `asdf list all nodejs 18`: このスクリプトで返されるすべてのバージョンから、 + `18`で始まるバージョンのみフィルタし、1行ずつリストします。 + +**asdfからの呼び出しシグネチャ** + +引数はありません。 + +```bash +"${plugin_path}/bin/list-all" +``` + +--- + +### `bin/download` + +**説明** + +ツールの特定バージョンのソースコードまたはバイナリを、指定された場所にダウンロードします。 + +**実装内容** + +- スクリプトは、`ASDF_DOWNLOAD_PATH`で指定されたディレクトリに、ソースコードまたはバイナリをダウンロードする必要があります。 +- 解凍されたソースコードまたはバイナリのみを、`ASDF_DOWNLOAD_PATH`ディレクトリに配置する必要があります。 +- 失敗した場合、`ASDF_DOWNLOAD_PATH`ディレクトリ内に何もファイルを配置しないようにしてください。 +- 成功した場合、終了コードは`0`としてください。 +- 失敗した場合、終了コードは非ゼロとしてください。 + +**レガシープラグイン** + +このスクリプトはすべてのプラグインで _必須_ とされていますが、このスクリプトが導入される以前の"レガシー"プラグインでは、 _オプション_ となっていました。 + +このスクリプトが存在しない場合、asdfは`bin/install`スクリプトがあると想定して、バージョンのダウンロード、**かつ**、インストールが実行されます。 + +レガシープラグインのサポートは最終的に削除される予定のため、今後作成するすべてのプラグインでこのスクリプトを含めるようにしてください。 + +**スクリプトで使用できる環境変数** + +- `ASDF_INSTALL_TYPE`: `version`または`ref`です。。 +- `ASDF_INSTALL_VERSION`: + - `ASDF_INSTALL_TYPE=version`の場合、バージョンのフルナンバーです。 + - `ASDF_INSTALL_TYPE=ref`の場合、Gitのref (tag/commit/branch)です。 +- `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_DOWNLOAD_PATH`ディレクトリに配置します。 + そして`bin/install`スクリプトを実行します。 + +**asdfからの呼び出しシグネチャ** + +引数はありません。 + +```bash +"${plugin_path}"/bin/download +``` + +--- + +### `bin/install` + +**説明** + +ツールの特定バージョンを指定された場所にインストールします。 + +**実装内容** + +- スクリプトは、指定されたバージョンを`ASDF_INSTALL_PATH`のパスのディレクトリにインストールする必要があります。 +- Shimはデフォルトで、`$ASDF_INSTALL_PATH/bin`内にあるファイルに対して作成されます。 + この動作は、オプションの[bin/list-bin-paths](#binlist-bin-paths)スクリプトでカスタマイズできます。 +- 成功した場合、終了コードは`0`としてください。 +- 失敗した場合、終了コードは非ゼロとしてください。 +- TOCTOU (Time-of-Check-to-Time-of-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 (tag/commit/branch)です。 +- `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`: `ASDF_INSTALL_PATH`ディレクトリに、 + Node.jsのバージョン`18.0.0`をインストールします。 + +**asdfからの呼び出しシグネチャ** + +引数はありません。 + +```bash +"${plugin_path}"/bin/install +``` + +## オプションスクリプト + +### `bin/latest-stable` + +**説明** + +ツールの最新安定バージョンを判定します。このスクリプトが存在しない場合、asdfコアは`bin/list-all`の出力を`tail`した結果をもとに判定しますが、ツールによってはこれが望ましくないことがあります。 + +**実装内容** + +- スクリプトは、ツールの最新安定バージョンを標準出力する必要があります。 +- 非安定版やリリース候補版は除外されるべきです。 +- フィルタクエリは、スクリプトの第1引数で提供されます。このクエリは、バージョン番号やツールプロバイダによる出力をフィルタするために使用されるべきです。 + - 例えば、[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`としてください。 +- 失敗した場合、終了コードは非ゼロとしてください。 + +**スクリプトで使用できる環境変数** + +- `ASDF_INSTALL_TYPE`: `version`または`ref`です。 +- `ASDF_INSTALL_VERSION`: + - `ASDF_INSTALL_TYPE=version`の場合、バージョンのフルナンバーです。 + - `ASDF_INSTALL_TYPE=ref`の場合、Gitのref (tag/commit/branch)です。 +- `ASDF_INSTALL_PATH`: ツールがインストール _されている_ 場所、またはインストール _されるべき_ 場所へのパスです。 + +**このスクリプトを呼び出すコマンド** + +- `asdf global latest`: ツールのグローバルバージョンとして、当該ツールの最新安定バージョンにセットします。 +- `asdf local latest`: ツールのローカルバージョンとして、当該ツールの最新安定バージョンにセットします。 +- `asdf install latest`: ツールの最新安定バージョンをインストールします。 +- `asdf latest []`: オプションのフィルタに基づいて、ツールの最新バージョンを出力します。 +- `asdf latest --all`: asdfによって管理されているすべてのツールの最新バージョンと、それらがインストールされているかどうかを出力します。 + +**asdfからの呼び出しシグネチャ** + +このスクリプトは、フィルタクエリという1つの引数を受け取ります。 + +```bash +"${plugin_path}"/bin/latest-stable "$query" +``` + +--- + +### `bin/help.overview` + +**説明** + +プラグインおよび管理されているツールに関する概要説明を出力します。 + +**実装内容** + +- このスクリプトは、プラグインのヘルプを表示するために必要です。 +- ヘッダはasdfコア側で表示するため、スクリプト内では表示しないでください。 +- 自由な形式のテキストで出力して構いませんが、短い1段落程度の説明が理想です。 +- コアとなるasdf-vmドキュメントですでに説明されている情報は出力しないでください。 +- オペレーティングシステムと、インストールされているツールのバージョンに合わせて出力を調整する必要があります(必要に応じて、`ASDF_INSTALL_VERSION`および`ASDF_INSTALL_TYPE`環境変数の値を使用してください)。 +- 成功した場合、終了コードは`0`としてください。 +- 失敗した場合、終了コードは非ゼロとしてください。 + +**スクリプトで使用できる環境変数** + +- `ASDF_INSTALL_TYPE`: `version`または`ref`です。 +- `ASDF_INSTALL_VERSION`: + - `ASDF_INSTALL_TYPE=version`の場合、バージョンのフルナンバーです。 + - `ASDF_INSTALL_TYPE=ref`の場合、Gitのref (tag/commit/branch)です。 +- `ASDF_INSTALL_PATH`: ツールがインストール _されている_ 場所、またはインストール _されるべき_ 場所へのパスです。 + +**このスクリプトを呼び出すコマンド** + +- `asdf help []`: プラグインおよびツールのドキュメントを出力します。 + +**asdfからの呼び出しシグネチャ** + +```bash +"${plugin_path}"/bin/help.overview +``` + +--- + +### `bin/help.deps` + +**説明** + +オペレーティングシステムに合わせた依存関係のリストを出力します。依存関係を1行ごとに出力します。 + +```bash +git +curl +sed +``` + +**実装内容** + +- このスクリプトの出力を考慮するために、`bin/help.overview`を用意する必要があります。 +- オペレーティングシステムと、インストールされているツールのバージョンに合わせて出力を調整する必要があります(必要に応じて、`ASDF_INSTALL_VERSION`および`ASDF_INSTALL_TYPE`環境変数の値を使用してください)。 +- 成功した場合、終了コードは`0`としてください。 +- 失敗した場合、終了コードは非ゼロとしてください。 + +**スクリプトで使用できる環境変数** + +- `ASDF_INSTALL_TYPE`: `version`または`ref`です。 +- `ASDF_INSTALL_VERSION`: + - `ASDF_INSTALL_TYPE=version`の場合、バージョンのフルナンバーです。 + - `ASDF_INSTALL_TYPE=ref`の場合、Gitのref (tag/commit/branch)です。 +- `ASDF_INSTALL_PATH`: ツールがインストール _されている_ 場所、またはインストール _されるべき_ 場所へのパスです。 + +**このスクリプトを呼び出すコマンド** + +- `asdf help []`: プラグインおよびツールのドキュメントを出力します。 + +**asdfからの呼び出しシグネチャ** + +```bash +"${plugin_path}"/bin/help.deps +``` + +--- + +### `bin/help.config` + +**説明** + +プラグインおよびツールで設定必須または任意設定可能な構成設定一覧を出力します。例えば、ツールのインストール・コンパイルに必要な環境変数やその他フラグについて説明します。 + +**実装内容** + +- このスクリプトの出力を考慮するために、`bin/help.overview`を用意する必要があります。 +- 自由な形式のテキストで出力できます。 +- オペレーティングシステムと、インストールされているツールのバージョンに合わせて出力を調整する必要があります(必要に応じて、`ASDF_INSTALL_VERSION`および`ASDF_INSTALL_TYPE`環境変数の値を使用してください)。 +- 成功した場合、終了コードは`0`としてください。 +- 失敗した場合、終了コードは非ゼロとしてください。 + +**スクリプトで使用できる環境変数** + +- `ASDF_INSTALL_TYPE`: `version`または`ref`です。 +- `ASDF_INSTALL_VERSION`: + - `ASDF_INSTALL_TYPE=version`の場合、バージョンのフルナンバーです。 + - `ASDF_INSTALL_TYPE=ref`の場合、Gitのref (tag/commit/branch)です。 +- `ASDF_INSTALL_PATH`: ツールがインストール _されている_ 場所、またはインストール _されるべき_ 場所へのパスです。 + +**このスクリプトを呼び出すコマンド** + +- `asdf help []`: プラグインおよびツールのドキュメントを出力します。 + +**asdfからの呼び出しシグネチャ** + +```bash +"${plugin_path}"/bin/help.config +``` + +--- + +### `bin/help.links` + +**説明** + +プラグインとツールに関連するリンクリストを出力します。リンクを1行ごとに出力します。 + +```bash +Git Repository: https://github.com/vlang/v +Documentation: https://vlang.io +``` + +**実装内容** + +- このスクリプトの出力を考慮するために、`bin/help.overview`を用意する必要があります。 +- リンクを1行ごとに出力してください。 +- 形式は以下のいずれかである必要があります: + - `: <link>` + - または`<link>`のみ +- オペレーティングシステムと、インストールされているツールのバージョンに合わせて出力を調整する必要があります(必要に応じて、`ASDF_INSTALL_VERSION`および`ASDF_INSTALL_TYPE`環境変数の値を使用してください)。 +- 成功した場合、終了コードは`0`としてください。 +- 失敗した場合、終了コードは非ゼロとしてください。 + +**スクリプトで使用できる環境変数** + +- `ASDF_INSTALL_TYPE`: `version`または`ref`です。 +- `ASDF_INSTALL_VERSION`: + - `ASDF_INSTALL_TYPE=version`の場合、バージョンのフルナンバーです。 + - `ASDF_INSTALL_TYPE=ref`の場合、Gitのref (tag/commit/branch)です。 +- `ASDF_INSTALL_PATH`: ツールがインストール _されている_ 場所、またはインストール _されるべき_ 場所へのパスです。 + +**このスクリプトを呼び出すコマンド** + +- `asdf help <name> [<version>]`: プラグインおよびツールのドキュメントを出力します。 + +**asdfからの呼び出しシグネチャ** + +```bash +"${plugin_path}"/bin/help.links +``` + +--- + +### `bin/list-bin-paths` + +**説明** + +ツールの特定バージョンにおける、実行ファイルが含まれるディレクトリの一覧を出力します。 + +**実装内容** + +- このスクリプトが存在しない場合、asdfは`"${ASDF_INSTALL_PATH}"/bin`ディレクトリ内にあるバイナリを探し、そのバイナリ向けのShimを作成します。 +- 実行ファイルが含まれるディレクトリのパスをスペース区切りで出力してください。 +- パスは`ASDF_INSTALL_PATH`からの相対パスである必要があります。例えば、次のような出力となります: + +```bash +bin tools veggies +``` + +以上の場合、下記ディレクトリ内のファイルへのShimを作成するよう、asdfへ指示されます: +- `"${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 (tag/commit/branch)です。 +- `ASDF_INSTALL_PATH`: ツールがインストール _されている_ 場所、またはインストール _されるべき_ 場所へのパスです。 + +**このスクリプトを呼び出すコマンド** + +- `asdf install <tool> [version]`: バイナリへのShimを初期作成します。 +- `asdf reshim <tool> <version>`: バイナリへのShimを再作成します。 + +**asdfからの呼び出しシグネチャ** + +```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 (tag/commit/branch)です。 +- `ASDF_INSTALL_PATH`: ツールがインストール _されている_ 場所、またはインストール _されるべき_ 場所へのパスです。 + +**このスクリプトを呼び出すコマンド** + +- `asdf which <command>`: 実行ファイルのパスを表示します。 +- `asdf exec <command> [args...]`: 現在のバージョンでShimコマンドを実行します。 +- `asdf env <command> [util]`: Shimコマンドの実行時に使用される環境において、util(デフォルト: `env`)を実行します。 + +**asdfからの呼び出しシグネチャ** + +```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 (tag/commit/branch)です。 +- `ASDF_INSTALL_PATH`: ツールがインストール _されている_ 場所、またはインストール _されるべき_ 場所へのパスです。 + +**このスクリプトを呼び出すコマンド** + +- `asdf which <command>`: 実行ファイルのパスを表示します。 +- `asdf exec <command> [args...]`: 現在のバージョンでShimコマンドを実行します。 +- `asdf env <command> [util]`: Shimコマンドの実行時に使用される環境において、util(デフォルト: `env`)を実行します。 + +**asdfからの呼び出しシグネチャ** + +```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からの呼び出しシグネチャ** + +引数はありません。 + +```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 (tag/commit/branch)です。 +- `ASDF_INSTALL_PATH`: ツールがインストール _されている_ 場所、またはインストール _されるべき_ 場所へのパスです。 + +**このスクリプトを呼び出すコマンド** + +ツールのバージョンを読み込むすべてのコマンドから呼び出されます。 + +**asdfからの呼び出しシグネチャ** + +引数はありません。 + +```bash +"${plugin_path}/bin/list-legacy-filenames" +``` + +--- + +### `bin/parse-legacy-file` + +**説明** + +asdfによって発見されたレガシーファイルをパースして、ツールのバージョンを決定します。JavaScriptの`package.json`や、Go言語の`go.mod`のようなファイルから、バージョン番号を抽出するのに役立ちます。 + +**実装内容** + +- このスクリプトが存在しない場合、asdfは単純にレガシーファイルを`cat`してバージョンを決定します。 +- **決定論的**で、常に正確で同じバージョンを返す必要があります: + - 同じレガシーファイルを解析したら、同じバージョンを返すようにしてください。 + - マシンに何がインストールされているか、また、レガシーバージョンが有効で完全かどうかは関係ありません。一部のレガシーファイルのフォーマットは適切でないときもあります。 +- 下記のように、バージョン番号を1行で出力してください: + ```bash + 1.2.3 + ``` + +**スクリプトで使用できる環境変数** + +このスクリプトが呼び出される前に、環境変数が設定されることはありません。 + +**このスクリプトを呼び出すコマンド** + +ツールのバージョンを読み込むすべてのコマンドから呼び出されます。 + +**asdfからの呼び出しシグネチャ** + +このスクリプトは、レガシーファイルの内容を読み込むために、レガシーファイルのパスという1つの引数を受け取ります。 + +```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からの呼び出しシグネチャ** + +引数はありません。 + +```bash +"${plugin_path}/bin/post-plugin-add" +``` + +--- + +### `bin/post-plugin-update` + +**説明** + +このスクリプトは、asdfの`asdf plugin update <tool> [<git-ref>]`コマンドで、 _更新_ されたプラグインがダウンロードされた **後に** 呼び出されます。 + +関連するコマンドフックについても参照してください: + +- `pre_asdf_plugin_updated` +- `pre_asdf_plugin_updated_${plugin_name}` +- `post_asdf_plugin_updated` +- `post_asdf_plugin_updated_${plugin_name}` + +**スクリプトで使用できる環境変数** + +- `ASDF_PLUGIN_PATH`: プラグインがインストールされている場所へのパスです。 +- `ASDF_PLUGIN_PREV_REF`: プラグインの以前のgit-refです。 +- `ASDF_PLUGIN_POST_REF`: 更新後のプラグインのgit-refです。 + +**asdfからの呼び出しシグネチャ** + +引数はありません。 + +```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からの呼び出しシグネチャ** + +引数はありません。 + +```bash +"${plugin_path}/bin/pre-plugin-remove" +``` + +<!-- TODO: document command hooks --> +<!-- ## Command Hooks --> + +## asdf CLIの拡張コマンド <Badge type="danger" text="高度" vertical="middle" /> + +プラグイン名をサブコマンドとして使用し、 +asdfコマンドラインインターフェースを通して呼び出すことのできる`lib/commands/command*.bash`スクリプトまたは実行ファイルを用意することで、 +新しい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`環境変数は、ソースとなるファイルのフルパスに解決されます。 + +[`haxe`](https://github.com/asdf-community/asdf-haxe)は、 +この機能使ったプラグインの素晴らしい例です。 +このプラグインは、`asdf haxe neko-dylibs-link`を提供しており、 +Haxeの実行ファイルが実行ディレクトリから相対的に動的ライブラリを見つけようとしてしまう問題を修正します。 + +プラグインの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 備考 + +LinuxとmacOSの両方のCI環境でテストすることを推奨します。 + +::: + +### GitHub Action + +[asdf-vm/actions](https://github.com/asdf-vm/actions)リポジトリでは、 +GitHub上でホストされているプラグインをテストするためのGitHub Actionを提供しています。 +`.github/workflows/test.yamlのActionsワークフローの例は以下のとおりです: + +```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パイプライン環境変数に追加してください。 + +::: warning 警告 + +認証トークンをコードリポジトリで公開してはいけません。 + +::: + +## プラグインショートネームインデックス + +::: tip ヒント + +推奨されるプラグインのインストール方法は、URLをもとに直接インストールする方法です: + +```shell +# asdf plugin add <name> <git_url> + asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs +``` + +::: + +asdfの各種コマンドで`git_url`が指定されなかった場合、 +asdfは正確な`git_url`を決定するために、 +[ショートネームインデックスリポジトリ](https://github.com/asdf-vm/asdf-plugins)を使用します。 + +このリポジトリの指示に従うことで、 +あなたが作成したプラグインを、 +[ショートネームインデックス](https://github.com/asdf-vm/asdf-plugins)に追加することができます。 diff --git a/docs/plugins/create.md b/docs/plugins/create.md index ae3b9701..4a9a4024 100644 --- a/docs/plugins/create.md +++ b/docs/plugins/create.md @@ -814,7 +814,7 @@ asdf plugin test <plugin_name> <plugin_url> [--asdf-tool-version <version>] [--a installed with that specific version. Defaults to `asdf latest <plugin-name>` - If optional `[--asdf-plugin-gitref <git_ref>]` is specified, the plugin itself is checked out at that commit/branch/tag. This is useful for testing a - pull-request on your plugin's CI. + pull-request on your plugin's CI. Defaults to the default branch of the plugin's repository. - Optional parameter `[test_command...]` is the command to execute to validate the installed tool works correctly. Typically `<tool> --version` or `<tool> --help`. For example, to test the NodeJS plugin, we could run diff --git a/docs/pt-br/guide/getting-started.md b/docs/pt-br/guide/getting-started.md index c1462fb3..12bf58de 100644 --- a/docs/pt-br/guide/getting-started.md +++ b/docs/pt-br/guide/getting-started.md @@ -39,7 +39,7 @@ asdf primarily requires `git` & `curl`. Here is a _non-exhaustive_ list of comma <!-- x-release-please-start-version --> ```shell -git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.13.1 +git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.0 ``` <!-- x-release-please-end --> @@ -297,7 +297,7 @@ Adicione a seguinte linha ao seu `~/.config/powershell/profile.ps1`: Adicione `asdf.nu` ao seu `~/.config/nushell/config.nu` através do comando: ```shell -"\n$env.ASDF_NU_DIR = ($env.HOME | path join '.asdf')\n source " + ($env.HOME | path join '.asdf/asdf.nu') | save --append $nu.config-path +"\n$env.ASDF_DIR = ($env.HOME | path join '.asdf')\n source " + ($env.HOME | path join '.asdf/asdf.nu') | save --append $nu.config-path ``` Ao concluir atualizará automaticamente @@ -308,7 +308,7 @@ Ao concluir atualizará automaticamente Adicione `asdf.nu` ao seu `~/.config/nushell/config.nu` através do comando: ```shell -"\n$env.ASDF_NU_DIR = (brew --prefix asdf | str trim | into string | path join 'libexec')\n source " + (brew --prefix asdf | into string | path join 'libexec/asdf.nu') | save --append $nu.config-path +"\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 ``` Ao concluir atualizará automaticamente @@ -319,7 +319,7 @@ Ao concluir atualizará automaticamente Adicione `asdf.nu` ao seu `~/.config/nushell/config.nu` através do comando: ```shell -"\n$env.ASDF_NU_DIR = '/opt/asdf-vm/'\n source /opt/asdf-vm/asdf.nu" | save --append $nu.config-path +"\n$env.ASDF_DIR = '/opt/asdf-vm/'\n source /opt/asdf-vm/asdf.nu" | save --append $nu.config-path ``` Ao concluir atualizará automaticamente diff --git a/docs/pt-br/plugins/create.md b/docs/pt-br/plugins/create.md index 928896e0..63b06bd8 100644 --- a/docs/pt-br/plugins/create.md +++ b/docs/pt-br/plugins/create.md @@ -209,8 +209,8 @@ asdf plugin test <plugin-name> <plugin-url> [--asdf-tool-version <version>] [--a ``` Apenas os dois primeiros argumentos são necessários. -Se \__version_ for especificado, a ferramenta será instalada com essa versão específica. O padrão é o que retorna `asdf mais recente <plugin-name>`. -Se _git-ref_ for especificado, o plug-in em si é verificado nesse commit/branch/tag, útil para testar um pull-request no CI do seu plug-in. +Se \__version_ for especificado, a ferramenta será instalada com essa versão específica. O padrão é o que retorna `asdf latest <plugin-name>`. +Se _git-ref_ for especificado, o plug-in em si é verificado nesse commit/branch/tag, útil para testar um pull-request no CI do seu plug-in. O padrão é o branch _default_ do repositório do plugin. Os argumentos Rest são considerados o comando a ser executado para garantir que a ferramenta instalada funcione corretamente. Normalmente seria algo que leva `--version` ou `--help`. diff --git a/docs/zh-hans/guide/getting-started.md b/docs/zh-hans/guide/getting-started.md index 7704db84..6a24cfff 100644 --- a/docs/zh-hans/guide/getting-started.md +++ b/docs/zh-hans/guide/getting-started.md @@ -35,7 +35,7 @@ asdf primarily requires `git` & `curl`. Here is a _non-exhaustive_ list of comma <!-- x-release-please-start-version --> ```shell -git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.13.1 +git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.0 ``` <!-- x-release-please-end --> @@ -298,7 +298,7 @@ echo -e "\n. \"$(brew --prefix asdf)/libexec/asdf.ps1\"" >> ~/.config/powershell 使用以下命令将 `asdf.nu` 加入到 `~/.config/nushell/config.nu` 文件中： ```shell -"\n$env.ASDF_NU_DIR = ($env.HOME | path join '.asdf')\n source " + ($env.HOME | path join '.asdf/asdf.nu') | save --append $nu.config-path +"\n$env.ASDF_DIR = ($env.HOME | path join '.asdf')\n source " + ($env.HOME | path join '.asdf/asdf.nu') | save --append $nu.config-path ``` 补全功能将会自动配置。 @@ -309,7 +309,7 @@ echo -e "\n. \"$(brew --prefix asdf)/libexec/asdf.ps1\"" >> ~/.config/powershell 使用以下命令将 `asdf.nu` 加入到 `~/.config/nushell/config.nu` 文件中: ```shell -"\n$env.ASDF_NU_DIR = (brew --prefix asdf | str trim | into string | path join 'libexec')\n source " + (brew --prefix asdf | into string | path join 'libexec/asdf.nu') | save --append $nu.config-path +"\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 ``` 补全功能将会自动配置。 @@ -320,7 +320,7 @@ echo -e "\n. \"$(brew --prefix asdf)/libexec/asdf.ps1\"" >> ~/.config/powershell 使用以下命令将 `asdf.nu` 加入到 `~/.config/nushell/config.nu` 文件中: ```shell -"\n$env.ASDF_NU_DIR = '/opt/asdf-vm/'\n source /opt/asdf-vm/asdf.nu" | save --append $nu.config-path +"\n$env.ASDF_DIR = '/opt/asdf-vm/'\n source /opt/asdf-vm/asdf.nu" | save --append $nu.config-path ``` 补全功能将会自动配置。 diff --git a/docs/zh-hans/plugins/create.md b/docs/zh-hans/plugins/create.md index 803b3a79..eab67d52 100644 --- a/docs/zh-hans/plugins/create.md +++ b/docs/zh-hans/plugins/create.md @@ -222,7 +222,7 @@ asdf plugin test <plugin-name> <plugin-url> [--asdf-tool-version <version>] [--a 只有前两个参数是必须的。 如果指定了 \__version_，则该工具将随指定版本一起安装。默认返回为 `asdf latest <plugin-name>`。 -如果指定了 _git-ref_，则插件将检查提交/分支/标签。这对于在该插件的 CI 上测试拉取请求非常有用。 +如果指定了 _git-ref_，则插件将检查提交/分支/标签。这对于在该插件的 CI 上测试拉取请求非常有用。默认值是插件仓库的默认分支。 剩下的参数被视为要执行的命令，以确保安装的工具正常工作。通常情况下，它需要带 `--version` 或者 `--help`。例如，要测试 NodeJS 插件，我们可以运行： diff --git a/go.mod b/go.mod new file mode 100644 index 00000000..4fae493e --- /dev/null +++ b/go.mod @@ -0,0 +1,3 @@ +module asdf + +go 1.21.5 diff --git a/help.txt b/help.txt index 611dd6ed..2435d158 100644 --- a/help.txt +++ b/help.txt @@ -54,6 +54,7 @@ asdf exec <command> [args...] Executes the command shim for current ve asdf env <command> [util] Runs util (default: `env`) inside the environment used for command shim execution. asdf info Print OS, Shell and ASDF debug information. +asdf version Print the currently installed version of ASDF asdf reshim <name> <version> Recreate shims for version of a package asdf shim-versions <command> List the plugins and versions that provide a command diff --git a/lib/commands/command-plugin-test.bash b/lib/commands/command-plugin-test.bash index 4341e7a2..0cfa680e 100644 --- a/lib/commands/command-plugin-test.bash +++ b/lib/commands/command-plugin-test.bash @@ -14,7 +14,20 @@ plugin_test_command() { local plugin_url="$2" shift 2 - local plugin_gitref="master" + local exit_code + local TEST_DIR + + fail_test() { + printf "FAILED: %s\n" "$1" + rm -rf "$TEST_DIR" + exit 1 + } + + if [ -z "$plugin_name" ] || [ -z "$plugin_url" ]; then + fail_test "please provide a plugin name and url" + fi + + local plugin_gitref local tool_version local interpret_args_literally local skip_next_arg @@ -45,21 +58,13 @@ plugin_test_command() { fi done - if [ "$#" -eq 1 ]; then - set -- "${SHELL:-sh}" -c "$1" + if [ -z "$plugin_gitref" ]; then + plugin_remote_default_branch=$(git ls-remote --symref "$plugin_url" HEAD | awk '{ sub(/refs\/heads\//, ""); print $2; exit }') + plugin_gitref=${3:-${plugin_remote_default_branch}} fi - local exit_code - local TEST_DIR - - fail_test() { - printf "FAILED: %s\n" "$1" - rm -rf "$TEST_DIR" - exit 1 - } - - if [ -z "$plugin_name" ] || [ -z "$plugin_url" ]; then - fail_test "please provide a plugin name and url" + if [ "$#" -eq 1 ]; then + set -- "${SHELL:-sh}" -c "$1" fi TEST_DIR=$(mktemp -dt asdf.XXXX) @@ -79,7 +84,7 @@ plugin_test_command() { fi # shellcheck disable=SC2119 - if ! (plugin_list_command | grep "^$plugin_name$" >/dev/null); then + if ! (plugin_list_command | grep -q "^$plugin_name$"); then fail_test "$plugin_name was not properly installed" fi @@ -90,8 +95,8 @@ plugin_test_command() { local plugin_path plugin_path=$(get_plugin_path "$plugin_name") local list_all="$plugin_path/bin/list-all" - if grep api.github.com "$list_all" >/dev/null; then - if ! grep Authorization "$list_all" >/dev/null; then + if grep -q api.github.com "$list_all"; then + if ! grep -q Authorization "$list_all"; then printf "\nLooks like %s/bin/list-all relies on GitHub releases\n" "$plugin_name" printf "but it does not properly sets an Authorization header to prevent\n" printf "GitHub API rate limiting.\n\n" diff --git a/lib/commands/reshim.bash b/lib/commands/reshim.bash index 82bed60f..2317973a 100644 --- a/lib/commands/reshim.bash +++ b/lib/commands/reshim.bash @@ -18,7 +18,7 @@ remove_shim_for_version() { sed -i.bak -e "/# asdf-plugin: $plugin_name $version"'$/d' "$shim_path" rm "$shim_path".bak - if ! grep "# asdf-plugin:" "$shim_path" >/dev/null || + if ! grep -q "# asdf-plugin:" "$shim_path" || [ "$count_installed" -eq 0 ]; then rm -f "$shim_path" fi diff --git a/lib/functions/installs.bash b/lib/functions/installs.bash index 721ae50c..036c1dab 100644 --- a/lib/functions/installs.bash +++ b/lib/functions/installs.bash @@ -236,8 +236,13 @@ install_tool_version() { if [ $install_exit_code -eq 0 ] && [ $download_exit_code -eq 0 ]; then # Remove download directory if --keep-download flag or always_keep_download config setting are not set always_keep_download=$(get_asdf_config_value "always_keep_download") - if [ ! "$keep_download" = "true" ] && [ ! "$always_keep_download" = "yes" ] && [ -d "$download_path" ]; then - rm -r "$download_path" + if [ ! "$keep_download" = "true" ] && [ ! "$always_keep_download" = "yes" ]; then + if [ -d "$download_path" ]; then + rm -r "$download_path" + else + printf '%s\n' "asdf: Warn: You have configured asdf to preserve downloaded files (with always_keep_download=yes or --keep-download). But" >&2 + printf '%s\n' "asdf: Warn: the current plugin ($plugin_name) does not support that. Downloaded files will not be preserved." >&2 + fi fi reshim_command "$plugin_name" "$full_version" diff --git a/lib/functions/plugins.bash b/lib/functions/plugins.bash index 3b36ddd9..6f7a9435 100644 --- a/lib/functions/plugins.bash +++ b/lib/functions/plugins.bash @@ -76,7 +76,7 @@ plugin_add_command() { local plugin_path plugin_path=$(get_plugin_path "$plugin_name") - mkdir -p "$(asdf_data_dir)/plugins" + [ -d "$(asdf_data_dir)/plugins" ] || mkdir -p "$(asdf_data_dir)/plugins" if [ -d "$plugin_path" ]; then printf '%s\n' "Plugin named $plugin_name already added" diff --git a/lib/functions/versions.bash b/lib/functions/versions.bash index 4b7cc34b..7d1d941d 100644 --- a/lib/functions/versions.bash +++ b/lib/functions/versions.bash @@ -60,7 +60,7 @@ version_command() { resolved_versions+=("$version") done - if [ -f "$file" ] && grep "^$plugin_name " "$file" >/dev/null; then + if [ -f "$file" ] && grep -q "^$plugin_name " "$file"; then local temp_dir temp_dir=${TMPDIR:-/tmp} diff --git a/lib/utils.bash b/lib/utils.bash index 8eae18fc..21978a92 100644 --- a/lib/utils.bash +++ b/lib/utils.bash @@ -62,7 +62,7 @@ get_install_path() { local install_dir install_dir="$(asdf_data_dir)/installs" - mkdir -p "${install_dir}/${plugin}" + [ -d "${install_dir}/${plugin}" ] || mkdir -p "${install_dir}/${plugin}" if [ "$install_type" = "version" ]; then printf "%s/%s/%s\n" "$install_dir" "$plugin" "$version" @@ -81,7 +81,7 @@ get_download_path() { local download_dir download_dir="$(asdf_data_dir)/downloads" - mkdir -p "${download_dir}/${plugin}" + [ -d "${download_dir}/${plugin}" ] || mkdir -p "${download_dir}/${plugin}" if [ "$install_type" = "version" ]; then printf "%s/%s/%s\n" "$download_dir" "$plugin" "$version" @@ -442,7 +442,7 @@ initialize_or_update_plugin_repository() { git -C "$repository_path" reset --hard origin/master fi - mkdir -p "$(asdf_data_dir)/tmp" + [ -d "$(asdf_data_dir)/tmp" ] || mkdir -p "$(asdf_data_dir)/tmp" touch "$(asdf_data_dir)/tmp/repo-updated" } diff --git a/main.go b/main.go new file mode 100644 index 00000000..db9d76ca --- /dev/null +++ b/main.go @@ -0,0 +1,8 @@ +package main + +import "fmt" + +// Placeholder for the real code +func main() { + fmt.Println("Late but latest -- Rajinikanth") +} diff --git a/main_test.go b/main_test.go new file mode 100644 index 00000000..7e6af5fc --- /dev/null +++ b/main_test.go @@ -0,0 +1,164 @@ +package main + +import ( + "fmt" + "os" + "os/exec" + "strings" + "testing" +) + +// Basic integration tests using the legacy BATS test scripts. This ensures the +// new Golang implementation matches the existing Bash implementation. + +func TestBatsTests(t *testing.T) { + // Create temp directory + dir, err := os.MkdirTemp("", "golang-bats-tests") + if err != nil { + t.Fatal("Failed to create temp dir") + } + defer os.RemoveAll(dir) + + // Build asdf and put in temp directory + build_asdf(t, dir) + + // Run tests with the asdf binary in the temp directory + + // Uncomment these as they are implemented + //t.Run("current_command", func(t *testing.T) { + // run_bats_file(t, dir, "current_command.bats") + //}) + + //t.Run("get_asdf_config_value", func(t *testing.T) { + // run_bats_file(t, dir, "get_asdf_config_value.bats") + //}) + + //t.Run("help_command", func(t *testing.T) { + // run_bats_file(t, dir, "help_command.bats") + //}) + + //t.Run("info_command", func(t *testing.T) { + // run_bats_file(t, dir, "info_command.bats") + //}) + + //t.Run("install_command", func(t *testing.T) { + // run_bats_file(t, dir, "install_command.bats") + //}) + + //t.Run("latest_command", func(t *testing.T) { + // run_bats_file(t, dir, "latest_command.bats") + //}) + + //t.Run("list_command", func(t *testing.T) { + // run_bats_file(t, dir, "list_command.bats") + //}) + + //t.Run("plugin_add_command", func(t *testing.T) { + // run_bats_file(t, dir, "plugin_add_command.bats") + //}) + + //t.Run("plugin_extension_command", func(t *testing.T) { + // run_bats_file(t, dir, "plugin_extension_command.bats") + //}) + + //t.Run("plugin_list_all_command", func(t *testing.T) { + // run_bats_file(t, dir, "plugin_list_all_command.bats") + //}) + + //t.Run("plugin_remove_command", func(t *testing.T) { + // run_bats_file(t, dir, "plugin_remove_command.bats") + //}) + + //t.Run("plugin_test_command", func(t *testing.T) { + // run_bats_file(t, dir, "plugin_test_command.bats") + //}) + + //t.Run("plugin_update_command", func(t *testing.T) { + // run_bats_file(t, dir, "plugin_update_command.bats") + //}) + + //t.Run("remove_command", func(t *testing.T) { + // run_bats_file(t, dir, "remove_command.bats") + //}) + + //t.Run("reshim_command", func(t *testing.T) { + // run_bats_file(t, dir, "reshim_command.bats") + //}) + + //t.Run("reshim_command", func(t *testing.T) { + // run_bats_file(t, dir, "reshim_command.bats") + //}) + + //t.Run("shim_env_command", func(t *testing.T) { + // run_bats_file(t, dir, "shim_env_command.bats") + //}) + + //t.Run("shim_exec", func(t *testing.T) { + // run_bats_file(t, dir, "shim_exec.bats") + //}) + + //t.Run("shim_versions_command", func(t *testing.T) { + // run_bats_file(t, dir, "shim_versions_command.bats") + //}) + + //t.Run("shim_versions_command", func(t *testing.T) { + // run_bats_file(t, dir, "shim_versions_command.bats") + //}) + + //t.Run("uninstall_command", func(t *testing.T) { + // run_bats_file(t, dir, "uninstall_command.bats") + //}) + + //t.Run("update_command", func(t *testing.T) { + // run_bats_file(t, dir, "update_command.bats") + //}) + + //t.Run("version_commands", func(t *testing.T) { + // run_bats_file(t, dir, "version_commands.bats") + //}) + + //t.Run("where_command", func(t *testing.T) { + // run_bats_file(t, dir, "where_command.bats") + //}) + + //t.Run("which_command", func(t *testing.T) { + // run_bats_file(t, dir, "which_command.bats") + //}) +} + +func run_bats_file(t *testing.T, dir, filename string) { + t.Helper() + + cmd := exec.Command("bats", "--verbose-run", fmt.Sprintf("test/%s", filename)) + + // Capture stdout and stderr + var stdout strings.Builder + var stderr strings.Builder + cmd.Stdout = &stdout + cmd.Stderr = &stderr + + // Add dir to asdf test variables + asdf_test_home := fmt.Sprintf("HOME=%s/.asdf/", dir) + asdf_bin_path := fmt.Sprintf("ASDF_BIN=%s", dir) + cmd.Env = append(cmd.Environ(), asdf_bin_path, asdf_test_home) + + err := cmd.Run() + if err != nil { + // If command fails print both stderr and stdout + fmt.Println("stdout:", stdout.String()) + fmt.Println("stderr:", stderr.String()) + t.Fatal("bats command failed to run test file successfully") + + return + } +} + +func build_asdf(t *testing.T, dir string) { + cmd := exec.Command("go", "build", "-o", dir) + + err := cmd.Run() + + if err != nil { + t.Fatal("Failed to build asdf") + } +} diff --git a/scripts/install_dependencies.bash b/scripts/install_dependencies.bash index 8965077d..65c40549 100755 --- a/scripts/install_dependencies.bash +++ b/scripts/install_dependencies.bash @@ -22,10 +22,10 @@ fi # Elvish elvish_semver="v0.19.2" # Fish -fish_semver="3.6.1" +fish_semver="3.7.0" fish_apt_semver="${fish_semver}-1~jammy" # Nushell -nushell_semver="0.84.0" +nushell_semver="0.86.0" # Powershell powershell_semver="7.3.3" powershell_apt_semver="${powershell_semver}-1.deb" @@ -38,7 +38,7 @@ if [ "$RUNNER_OS" = "Linux" ]; then sudo sh -c 'echo "deb [arch=amd64] https://packages.microsoft.com/repos/microsoft-debian-bullseye-prod bullseye main" > /etc/apt/sources.list.d/microsoft.list' sudo add-apt-repository -y ppa:fish-shell/release-3 sudo apt-get update - sudo apt-get -y install curl parallel \ + sudo apt-get --allow-downgrades -y install curl parallel \ fish="${fish_apt_semver}" \ powershell="${powershell_apt_semver}" diff --git a/test/asdf_fish.bats b/test/asdf_fish.bats index 8c15f7b4..9e89ecc6 100644 --- a/test/asdf_fish.bats +++ b/test/asdf_fish.bats @@ -16,7 +16,7 @@ cleaned_path() { } @test "exports ASDF_DIR" { - run fish -c " + run fish --no-config -c " set -e asdf set -e ASDF_DIR set -e ASDF_DATA_DIR @@ -30,7 +30,7 @@ cleaned_path() { } @test "adds asdf dirs to PATH" { - run fish -c " + run fish --no-config -c " set -e asdf set -e ASDF_DIR set -e ASDF_DATA_DIR @@ -46,7 +46,7 @@ cleaned_path() { } @test "does not add paths to PATH more than once" { - run fish -c " + run fish --no-config -c " set -e asdf set -e ASDF_DIR set -e ASDF_DATA_DIR @@ -63,7 +63,7 @@ cleaned_path() { } @test "defines the asdf function" { - run fish -c " + run fish --no-config -c " set -e asdf set -e ASDF_DIR set PATH $(cleaned_path) @@ -76,7 +76,7 @@ cleaned_path() { } @test "function calls asdf command" { - run fish -c " + run fish --no-config -c " set -e asdf set -x ASDF_DIR $(pwd) # checkstyle-ignore set PATH $(cleaned_path) diff --git a/test/asdf_nu.bats b/test/asdf_nu.bats index f46d6a66..729def50 100644 --- a/test/asdf_nu.bats +++ b/test/asdf_nu.bats @@ -26,7 +26,7 @@ run_nushell() { hide-env -i asdf hide-env -i ASDF_DIR \$env.PATH = ( '$(cleaned_path)' | split row ':' ) - \$env.ASDF_NU_DIR = '$PWD' + \$env.ASDF_DIR = '$PWD' source asdf.nu $1" @@ -60,7 +60,7 @@ run_nushell() { [ "$result" = "" ] } -@test "retains ASDF_DIR" { +@test "retains ASDF_DIR (from ASDF_NU_DIR)" { run nu -c " hide-env -i asdf \$env.ASDF_DIR = ( pwd ) @@ -75,6 +75,21 @@ run_nushell() { [ "$output" = "$PWD" ] } +@test "retains ASDF_DIR (from ASDF_DIR)" { + run nu -c " + hide-env -i asdf + \$env.ASDF_DIR = ( pwd ) + \$env.PATH = ( '$(cleaned_path)' | split row ':' ) + \$env.ASDF_DIR = '$PWD' + + source asdf.nu + + echo \$env.ASDF_DIR" + + [ "$status" -eq 0 ] + [ "$output" = "$PWD" ] +} + @test "defines the asdf or main function" { run_nushell "which asdf | get path | to text" diff --git a/test/fixtures/dummy_plugin_no_download/LICENSE b/test/fixtures/dummy_plugin_no_download/LICENSE new file mode 100644 index 00000000..d3084751 --- /dev/null +++ b/test/fixtures/dummy_plugin_no_download/LICENSE @@ -0,0 +1,20 @@ +The MIT License (MIT) + +Copyright (c) 2014 Akash Manohar J + +Permission is hereby granted, free of charge, to any person obtaining a copy of +this software and associated documentation files (the "Software"), to deal in +the Software without restriction, including without limitation the rights to +use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software is furnished to do so, +subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS +FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR +COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER +IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN +CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/test/fixtures/dummy_plugin_no_download/bin/install b/test/fixtures/dummy_plugin_no_download/bin/install new file mode 100755 index 00000000..4c5589ec --- /dev/null +++ b/test/fixtures/dummy_plugin_no_download/bin/install @@ -0,0 +1,3 @@ +#!/usr/bin/env bash + +printf '%s' 'install' diff --git a/test/install_command.bats b/test/install_command.bats index bd945cbe..9e70d544 100644 --- a/test/install_command.bats +++ b/test/install_command.bats @@ -242,9 +242,9 @@ EOM echo 'legacy_version_file = yes' >"$HOME/.asdfrc" echo '1.2.0' >>"$PROJECT_DIR/.dummy-version" cd "$PROJECT_DIR" + run asdf install [ "$status" -eq 0 ] - [ -z "$output" ] [ -f "$ASDF_DIR/installs/dummy/1.2.0/version" ] } @@ -257,7 +257,6 @@ EOM run asdf install [ "$status" -eq 0 ] - [ -z "$output" ] [ -f "$ASDF_DIR/installs/dummy/1.2.0/version" ] } @@ -302,3 +301,12 @@ EOM [ ! -d "$ASDF_DIR/installs/dummy-broken/1.1.0" ] [ "$output" = "Download failed!" ] } + +@test "install_command prints info message if plugin does not support preserving download data if configured" { + install_dummy_plugin_no_download + + run asdf install dummy-no-download 1.0.0 + [ "$status" -eq 0 ] + + [[ "$output" == *'asdf: Warn:'*'not be preserved'* ]] +} diff --git a/test/test_helpers.bash b/test/test_helpers.bash index 103da76c..e693e534 100644 --- a/test/test_helpers.bash +++ b/test/test_helpers.bash @@ -12,13 +12,15 @@ setup_asdf_dir() { BASE_DIR="$(mktemp -dt "asdf with spaces.XXXX")" fi - HOME="$BASE_DIR/home" + # HOME is now defined by the Golang test code in main_test.go + #HOME="$BASE_DIR/home" ASDF_DIR="$HOME/.asdf" mkdir -p "$ASDF_DIR/plugins" mkdir -p "$ASDF_DIR/installs" mkdir -p "$ASDF_DIR/shims" mkdir -p "$ASDF_DIR/tmp" - ASDF_BIN="$(dirname "$BATS_TEST_DIRNAME")/bin" + # ASDF_BIN is now defined by the Golang test code in main_test.go + #ASDF_BIN="$(dirname "$BATS_TEST_DIRNAME")/bin" # shellcheck disable=SC2031 PATH="$ASDF_BIN:$ASDF_DIR/shims:$PATH" @@ -30,6 +32,12 @@ install_mock_plugin() { cp -r "$BATS_TEST_DIRNAME/fixtures/dummy_plugin" "$location/plugins/$plugin_name" } +install_mock_plugin_no_download() { + local plugin_name=$1 + local location="${2:-$ASDF_DIR}" + cp -r "$BATS_TEST_DIRNAME/fixtures/dummy_plugin_no_download" "$location/plugins/$plugin_name" +} + install_mock_legacy_plugin() { local plugin_name=$1 local location="${2:-$ASDF_DIR}" @@ -64,6 +72,10 @@ install_dummy_plugin() { install_mock_plugin "dummy" } +install_dummy_plugin_no_download() { + install_mock_plugin_no_download "dummy-no-download" "$1" +} + install_dummy_legacy_plugin() { install_mock_legacy_plugin "legacy-dummy" } diff --git a/version.txt b/version.txt index c317a918..a803cc22 100644 --- a/version.txt +++ b/version.txt @@ -1 +1 @@ -0.13.1 +0.14.0