mirror of
https://github.com/asdf-vm/asdf.git
synced 2024-12-19 18:05:02 -07:00
36 lines
74 KiB
JavaScript
36 lines
74 KiB
JavaScript
import{_ as n,c as o,a2 as l,j as s,a as e,G as a,B as p,o as d}from"./chunks/framework.BQmytedh.js";const T=JSON.parse('{"title":"Create a Plugin","description":"","frontmatter":{},"headers":[],"relativePath":"plugins/create.md","filePath":"plugins/create.md","lastUpdated":1704804447000}'),r={name:"plugins/create.md"},h={tabindex:"0"},c={style:{"text-align":"left"}},g={style:{"text-align":"left"}},u={style:{"text-align":"left"}},k={style:{"text-align":"left"}},b={id:"bin-list-all",tabindex:"-1"},m={id:"bin-download",tabindex:"-1"},f={id:"bin-install",tabindex:"-1"},y={id:"bin-latest-stable",tabindex:"-1"},F={id:"extension-commands-for-asdf-cli",tabindex:"-1"},v={id:"custom-shim-templates",tabindex:"-1"};function E(A,i,C,x,_,S){const t=p("Badge");return d(),o("div",null,[i[48]||(i[48]=l('<h1 id="create-a-plugin" tabindex="-1">Create a Plugin <a class="header-anchor" href="#create-a-plugin" aria-label="Permalink to "Create a Plugin""></a></h1><p>A plugin is a Git repo with some executable scripts to support versioning a language / tool. These scripts are run by asdf using specific commands to support features such as <code>asdf list-all <name></code>, <code>asdf install <name> <version></code> etc.</p><h2 id="quickstart" tabindex="-1">Quickstart <a class="header-anchor" href="#quickstart" aria-label="Permalink to "Quickstart""></a></h2><p>There are two options to get started with creating your own plugin:</p><ol><li>use the <a href="https://github.com/asdf-vm/asdf-plugin-template" target="_blank" rel="noreferrer">asdf-vm/asdf-plugin-template</a> repository to <a href="https://github.com/asdf-vm/asdf-plugin-template/generate" target="_blank" rel="noreferrer">generate</a> a plugin repo (named <code>asdf-<tool_name></code>) with default scripts implemented. Once generated, clone the repo and run the <code>setup.bash</code> script to interactively update the template.</li><li>start your own repo called <code>asdf-<tool_name></code> and implement the required scripts as listed in the documentation below.</li></ol><h3 id="golden-rules-for-plugin-scripts" tabindex="-1">Golden Rules for Plugin Scripts <a class="header-anchor" href="#golden-rules-for-plugin-scripts" aria-label="Permalink to "Golden Rules for Plugin Scripts""></a></h3><ul><li>scripts should <strong>NOT</strong> call other <code>asdf</code> commands</li><li>keep your dependency list of Shell tools/commands small</li><li>avoid non-portable tools or command flags. For example, <code>sort -V</code>. See our asdf core <a href="https://github.com/asdf-vm/asdf/blob/master/test/banned_commands.bats" target="_blank" rel="noreferrer">list of banned commands</a></li></ul><h2 id="scripts-overview" tabindex="-1">Scripts Overview <a class="header-anchor" href="#scripts-overview" aria-label="Permalink to "Scripts Overview""></a></h2><p>The full list of scripts callable from asdf.</p>',9)),s("table",h,[i[25]||(i[25]=s("thead",null,[s("tr",null,[s("th",{style:{"text-align":"left"}},"Script"),s("th",{style:{"text-align":"left"}},"Description")])],-1)),s("tbody",null,[s("tr",null,[s("td",c,[i[0]||(i[0]=s("a",{href:"#bin-list-all"},"bin/list-all",-1)),i[1]||(i[1]=e()),a(t,{type:"tip",text:"required",vertical:"middle"})]),i[2]||(i[2]=s("td",{style:{"text-align":"left"}},"List all installable versions",-1))]),s("tr",null,[s("td",g,[i[3]||(i[3]=s("a",{href:"#bin-download"},"bin/download",-1)),i[4]||(i[4]=e()),a(t,{type:"tip",text:"required",vertical:"middle"})]),i[5]||(i[5]=s("td",{style:{"text-align":"left"}},"Download source code or binary for the specified version",-1))]),s("tr",null,[s("td",u,[i[6]||(i[6]=s("a",{href:"#bin-install"},"bin/install",-1)),i[7]||(i[7]=e()),a(t,{type:"tip",text:"required",vertical:"middle"})]),i[8]||(i[8]=s("td",{style:{"text-align":"left"}},"Installs the specified version",-1))]),s("tr",null,[s("td",k,[i[9]||(i[9]=s("a",{href:"#bin-latest-stable"},"bin/latest-stable",-1)),i[10]||(i[10]=e()),a(t,{type:"warning",text:"recommended",vertical:"middle"})]),i[11]||(i[11]=s("td",{style:{"text-align":"left"}},"List the latest stable version of the specified tool",-1))]),i[12]||(i[12]=s("tr",null,[s("td",{style:{"text-align":"left"}},[s("a",{href:"#bin-help.overview"},"bin/help.overview")]),s("td",{style:{"text-align":"left"}},"Output a general description about the plugin & tool")],-1)),i[13]||(i[13]=s("tr",null,[s("td",{style:{"text-align":"left"}},[s("a",{href:"#bin-help.deps"},"bin/help.deps")]),s("td",{style:{"text-align":"left"}},"Output a list of dependencies per Operating System")],-1)),i[14]||(i[14]=s("tr",null,[s("td",{style:{"text-align":"left"}},[s("a",{href:"#bin-help.config"},"bin/help.config")]),s("td",{style:{"text-align":"left"}},"Output plugin or tool configuration information")],-1)),i[15]||(i[15]=s("tr",null,[s("td",{style:{"text-align":"left"}},[s("a",{href:"#bin-help.links"},"bin/help.links")]),s("td",{style:{"text-align":"left"}},"Output a list of links for the plugin or tool")],-1)),i[16]||(i[16]=s("tr",null,[s("td",{style:{"text-align":"left"}},[s("a",{href:"#bin-list-bin-paths"},"bin/list-bin-paths")]),s("td",{style:{"text-align":"left"}},"List relative paths to directories with binaries to create shims")],-1)),i[17]||(i[17]=s("tr",null,[s("td",{style:{"text-align":"left"}},[s("a",{href:"#bin-exec-env"},"bin/exec-env")]),s("td",{style:{"text-align":"left"}},"Prepare the environment for running the binaries")],-1)),i[18]||(i[18]=s("tr",null,[s("td",{style:{"text-align":"left"}},[s("a",{href:"#bin-exec-path"},"bin/exec-path")]),s("td",{style:{"text-align":"left"}},"Output the executable path for a version of a tool")],-1)),i[19]||(i[19]=s("tr",null,[s("td",{style:{"text-align":"left"}},[s("a",{href:"#bin-uninstall"},"bin/uninstall")]),s("td",{style:{"text-align":"left"}},"Uninstall a specific version of a tool")],-1)),i[20]||(i[20]=s("tr",null,[s("td",{style:{"text-align":"left"}},[s("a",{href:"#bin-list-legacy-filenames"},"bin/list-legacy-filenames")]),s("td",{style:{"text-align":"left"}},[e("Output filenames of legacy version files: "),s("code",null,".ruby-version")])],-1)),i[21]||(i[21]=s("tr",null,[s("td",{style:{"text-align":"left"}},[s("a",{href:"#bin-parse-legacy-file"},"bin/parse-legacy-file")]),s("td",{style:{"text-align":"left"}},"Custom parser for legacy version files")],-1)),i[22]||(i[22]=s("tr",null,[s("td",{style:{"text-align":"left"}},[s("a",{href:"#bin-post-plugin-add"},"bin/post-plugin-add")]),s("td",{style:{"text-align":"left"}},"Hook to execute after a plugin has been added")],-1)),i[23]||(i[23]=s("tr",null,[s("td",{style:{"text-align":"left"}},[s("a",{href:"#bin-post-plugin-update"},"bin/post-plugin-update")]),s("td",{style:{"text-align":"left"}},"Hook to execute after a plugin has been updated")],-1)),i[24]||(i[24]=s("tr",null,[s("td",{style:{"text-align":"left"}},[s("a",{href:"#bin-pre-plugin-remove"},"bin/pre-plugin-remove")]),s("td",{style:{"text-align":"left"}},"Hook to execute before a plugin is removed")],-1))])]),i[49]||(i[49]=l('<p>To see which commands invoke which scripts, see the detailed documentation for each script.</p><h2 id="environment-variables-overview" tabindex="-1">Environment Variables Overview <a class="header-anchor" href="#environment-variables-overview" aria-label="Permalink to "Environment Variables Overview""></a></h2><p>The full list of Environment Variables used throughout all scripts.</p><table tabindex="0"><thead><tr><th style="text-align:left;">Environment Variables</th><th style="text-align:left;">Description</th></tr></thead><tbody><tr><td style="text-align:left;"><code>ASDF_INSTALL_TYPE</code></td><td style="text-align:left;"><code>version</code> or <code>ref</code></td></tr><tr><td style="text-align:left;"><code>ASDF_INSTALL_VERSION</code></td><td style="text-align:left;">full version number or Git Ref depending on <code>ASDF_INSTALL_TYPE</code></td></tr><tr><td style="text-align:left;"><code>ASDF_INSTALL_PATH</code></td><td style="text-align:left;">the path to where the tool <em>should</em>, or <em>has been</em> installed</td></tr><tr><td style="text-align:left;"><code>ASDF_CONCURRENCY</code></td><td style="text-align:left;">the number of cores to use when compiling the source code. Useful for setting <code>make -j</code></td></tr><tr><td style="text-align:left;"><code>ASDF_DOWNLOAD_PATH</code></td><td style="text-align:left;">the path to where the source code or binary was downloaded to by <code>bin/download</code></td></tr><tr><td style="text-align:left;"><code>ASDF_PLUGIN_PATH</code></td><td style="text-align:left;">the path the plugin was installed</td></tr><tr><td style="text-align:left;"><code>ASDF_PLUGIN_SOURCE_URL</code></td><td style="text-align:left;">the source URL of the plugin</td></tr><tr><td style="text-align:left;"><code>ASDF_PLUGIN_PREV_REF</code></td><td style="text-align:left;">prevous <code>git-ref</code> of the plugin repo</td></tr><tr><td style="text-align:left;"><code>ASDF_PLUGIN_POST_REF</code></td><td style="text-align:left;">updated <code>git-ref</code> of the plugin repo</td></tr><tr><td style="text-align:left;"><code>ASDF_CMD_FILE</code></td><td style="text-align:left;">resolves to the full path of the file being sourced</td></tr></tbody></table><div class="tip custom-block"><p class="custom-block-title">NOTE</p><p><strong>Not all environment variables are available in all scripts.</strong> Check the documentation for each script below to see which env vars are available to it.</p></div><h2 id="required-scripts" tabindex="-1">Required Scripts <a class="header-anchor" href="#required-scripts" aria-label="Permalink to "Required Scripts""></a></h2>',6)),s("h3",b,[i[26]||(i[26]=s("code",null,"bin/list-all",-1)),i[27]||(i[27]=e()),a(t,{type:"tip",text:"required",vertical:"middle"}),i[28]||(i[28]=e()),i[29]||(i[29]=s("a",{class:"header-anchor",href:"#bin-list-all","aria-label":'Permalink to "`bin/list-all` <Badge type="tip" text="required" vertical="middle" />"'},"",-1))]),i[50]||(i[50]=l('<p><strong>Description</strong></p><p>List all installable versions.</p><p><strong>Output Format</strong></p><p>Must print a string with a <strong>space-separated</strong> list of versions. For example:</p><div class="language-txt vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">txt</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>1.0.1 1.0.2 1.3.0 1.4</span></span></code></pre></div><p>Newest version should be last.</p><p>asdf core will print each version on its own line, potentially pushing some versions offscreen.</p><p><strong>Sorting</strong></p><p>If versions are being pulled from releases page on a website it's recommended to leave the versions in the provided order as they are often already in the correct order. If they are in reverse order piping them through <code>tac</code> should suffice.</p><p>If sorting is unavoidable, <code>sort -V</code> is not portable, so we suggest either:</p><ul><li><a href="https://github.com/asdf-vm/asdf-plugin-template/blob/main/template/lib/utils.bash" target="_blank" rel="noreferrer">using the Git sort capability</a> (requires Git >= <code>v2.18.0</code>)</li><li><a href="https://github.com/vic/asdf-idris/blob/master/bin/list-all#L6" target="_blank" rel="noreferrer">writing a custom sort method</a> (requires <code>sed</code>, <code>sort</code> & <code>awk</code>)</li></ul><p><strong>Environment Variables available to script</strong></p><p>No environment variables are provided to this script.</p><p><strong>Commands that invoke this script</strong></p><ul><li><code>asdf list all <name> [version]</code></li><li><code>asdf list all nodejs</code>: lists all versions as returned by this script, one on each line.</li><li><code>asdf list all nodejs 18</code>: lists all versions as returned by this script, one on each line, with a filter matching any version beginning with <code>18</code> applied.</li></ul><p><strong>Call signature from asdf core</strong></p><p>No parameters provided.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">"${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">plugin_path</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">}/bin/list-all"</span></span></code></pre></div><hr>',19)),s("h3",m,[i[30]||(i[30]=s("code",null,"bin/download",-1)),i[31]||(i[31]=e()),a(t,{type:"tip",text:"required",vertical:"middle"}),i[32]||(i[32]=e()),i[33]||(i[33]=s("a",{class:"header-anchor",href:"#bin-download","aria-label":'Permalink to "`bin/download` <Badge type="tip" text="required" vertical="middle" />"'},"",-1))]),i[51]||(i[51]=l('<p><strong>Description</strong></p><p>Download the source code or binary for a specific version of a tool to a specified location.</p><p><strong>Implementation Details</strong></p><ul><li>The script must download the source or binary to the directory specified by <code>ASDF_DOWNLOAD_PATH</code>.</li><li>Only the decompressed source code or binary should be placed in the <code>ASDF_DOWNLOAD_PATH</code> directory.</li><li>On failure, no files should be placed in <code>ASDF_DOWNLOAD_PATH</code>.</li><li>Success should exit with <code>0</code>.</li><li>Failure should exit with a non-zero status.</li></ul><p><strong>Legacy Plugins</strong></p><p>Though this script is marked as <em>required</em> for all plugins, it is <em>optional</em> for "legacy" plugins which predate its introduction.</p><p>If this script is absent, asdf will assume that the <code>bin/install</code> script is present and will download <strong>and</strong> install the version.</p><p>All plugins must include this script as support for legacy plugins will eventually be removed.</p><p><strong>Environment Variables available to script</strong></p><ul><li><code>ASDF_INSTALL_TYPE</code>: <code>version</code> or <code>ref</code></li><li><code>ASDF_INSTALL_VERSION</code>: <ul><li>Full version number if <code>ASDF_INSTALL_TYPE=version</code>.</li><li>Git ref (tag/commit/branch) if <code>ASDF_INSTALL_TYPE=ref</code>.</li></ul></li><li><code>ASDF_INSTALL_PATH</code>: The path to where the tool <em>has been</em>, or <em>should be</em> installed.</li><li><code>ASDF_DOWNLOAD_PATH</code>: The path to where the source code or binary was downloaded to.</li></ul><p><strong>Commands that invoke this script</strong></p><ul><li><code>asdf install <tool> [version]</code></li><li><code>asdf install <tool> latest[:version]</code></li><li><code>asdf install nodejs 18.0.0</code>: downloads the source code or binary for Node.js version <code>18.0.0</code> and places it in the <code>ASDF_DOWNLOAD_PATH</code> directory. Then runs the <code>bin/install</code> script.</li></ul><p><strong>Call signature from asdf core</strong></p><p>No parameters provided.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">"${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">plugin_path</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">}"</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">/bin/download</span></span></code></pre></div><hr>',16)),s("h3",f,[i[34]||(i[34]=s("code",null,"bin/install",-1)),i[35]||(i[35]=e()),a(t,{type:"tip",text:"required",vertical:"middle"}),i[36]||(i[36]=e()),i[37]||(i[37]=s("a",{class:"header-anchor",href:"#bin-install","aria-label":'Permalink to "`bin/install` <Badge type="tip" text="required" vertical="middle" />"'},"",-1))]),i[52]||(i[52]=l('<p><strong>Description</strong></p><p>Install a specific version of a tool to a specified location.</p><p><strong>Implementation Details</strong></p><ul><li>The script should install the specified version in the path <code>ASDF_INSTALL_PATH</code>.</li><li>Shims will be created by default for any files in <code>$ASDF_INSTALL_PATH/bin</code>. This behaviour can be customised with the optional <a href="#binlist-bin-paths">bin/list-bin-paths</a> script.</li><li>Success should exit with <code>0</code>.</li><li>Failure should exit with a non-zero status.</li><li>To avoid TOCTOU (Time-of-Check-to-Time-of-Use) issues, ensure the script only places files in <code>ASDF_INSTALL_PATH</code> once the build and installation of the tool is deemed a success.</li></ul><p><strong>Legacy Plugins</strong></p><p>If the <code>bin/download</code> script is absent, this script should download <strong>and</strong> install the specified version.</p><p>For compatibility with versions of the asdf core earlier than <code>0.7._</code> and newer than <code>0.8._</code>, check for the presence of the <code>ASDF_DOWNLOAD_PATH</code> environment variable. If set, assume the <code>bin/download</code> script already downloaded the version, else download the source code in the <code>bin/install</code> script.</p><p><strong>Environment Variables available to script</strong></p><ul><li><code>ASDF_INSTALL_TYPE</code>: <code>version</code> or <code>ref</code></li><li><code>ASDF_INSTALL_VERSION</code>: <ul><li>Full version number if <code>ASDF_INSTALL_TYPE=version</code>.</li><li>Git ref (tag/commit/branch) if <code>ASDF_INSTALL_TYPE=ref</code>.</li></ul></li><li><code>ASDF_INSTALL_PATH</code>: The path to where the tool <em>has been</em>, or <em>should be</em> installed.</li><li><code>ASDF_CONCURRENCY</code>: The number of cores to use when compiling source code. Useful for setting flags like <code>make -j</code>.</li><li><code>ASDF_DOWNLOAD_PATH</code>: The path where the source code or binary was downloaded to.</li></ul><p><strong>Commands that invoke this script</strong></p><ul><li><code>asdf install</code></li><li><code>asdf install <tool></code></li><li><code>asdf install <tool> [version]</code></li><li><code>asdf install <tool> latest[:version]</code></li><li><code>asdf install nodejs 18.0.0</code>: installs Node.js version <code>18.0.0</code> in the <code>ASDF_INSTALL_PATH</code> directory.</li></ul><p><strong>Call signature from asdf core</strong></p><p>No parameters provided.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">"${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">plugin_path</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">}"</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">/bin/install</span></span></code></pre></div><h2 id="optional-scripts" tabindex="-1">Optional Scripts <a class="header-anchor" href="#optional-scripts" aria-label="Permalink to "Optional Scripts""></a></h2>',15)),s("h3",y,[i[38]||(i[38]=s("code",null,"bin/latest-stable",-1)),i[39]||(i[39]=e()),a(t,{type:"warning",text:"recommended",vertical:"middle"}),i[40]||(i[40]=e()),i[41]||(i[41]=s("a",{class:"header-anchor",href:"#bin-latest-stable","aria-label":'Permalink to "`bin/latest-stable` <Badge type="warning" text="recommended" vertical="middle" />"'},"",-1))]),i[53]||(i[53]=l('<p><strong>Description</strong></p><p>Determine the latest stable version of a tool. If absent, the asdf core will <code>tail</code> the <code>bin/list-all</code> output which may be undesirable.</p><p><strong>Implementation Details</strong></p><ul><li>The script should print the latest stable version of the tool to stdout.</li><li>Non-stable or release candidate versions should be omitted.</li><li>A filter query is provided as the first argument to the script. This should be used to filter the output by version number or tool provider. <ul><li>For instance, the output of <code>asdf list all ruby</code> from the <a href="https://github.com/asdf-vm/asdf-ruby" target="_blank" rel="noreferrer">ruby plugin</a> lists versions of Ruby from many providers: <code>jruby</code>, <code>rbx</code> & <code>truffleruby</code> amongst others. The user provided filter could be used by the plugin to filter the semver versions and/or provider.<div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>> asdf latest ruby</span></span>\n<span class="line"><span>3.2.2</span></span>\n<span class="line"><span>> asdf latest ruby 2</span></span>\n<span class="line"><span>2.7.8</span></span>\n<span class="line"><span>> asdf latest ruby truffleruby</span></span>\n<span class="line"><span>truffleruby+graalvm-22.3.1</span></span></code></pre></div></li></ul></li><li>Success should exit with <code>0</code>.</li><li>Failure should exit with a non-zero status.</li></ul><p><strong>Environment Variables available to script</strong></p><ul><li><code>ASDF_INSTALL_TYPE</code>: <code>version</code> or <code>ref</code></li><li><code>ASDF_INSTALL_VERSION</code>: <ul><li>Full version number if <code>ASDF_INSTALL_TYPE=version</code>.</li><li>Git ref (tag/commit/branch) if <code>ASDF_INSTALL_TYPE=ref</code>.</li></ul></li><li><code>ASDF_INSTALL_PATH</code>: The path to where the tool <em>has been</em>, or <em>should be</em> installed.</li></ul><p><strong>Commands that invoke this script</strong></p><ul><li><code>asdf global <tool> latest</code>: set the global version of a tool to the latest stable version for that tool.</li><li><code>asdf local <name> latest</code>: set the local version of a tool to the latest stable version for that tool.</li><li><code>asdf install <tool> latest</code>: installs the latest version of a tool.</li><li><code>asdf latest <tool> [<version>]</code>: outputs the latest version of a tool based on the optional filter.</li><li><code>asdf latest --all</code>: outputs the latest version of all tools managed by asdf and whether they are installed.</li></ul><p><strong>Call signature from asdf core</strong></p><p>The script should accept a single argument, the filter query.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">"${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">plugin_path</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">}"</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">/bin/latest-stable</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$query</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"</span></span></code></pre></div><hr><h3 id="bin-help-overview" tabindex="-1"><code>bin/help.overview</code> <a class="header-anchor" href="#bin-help-overview" aria-label="Permalink to "`bin/help.overview`""></a></h3><p><strong>Description</strong></p><p>Output a general description about the plugin and the tool being managed.</p><p><strong>Implementation Details</strong></p><ul><li>This script is required for any help output to be displayed for the plugin.</li><li>No heading should be printed as asdf core will print headings.</li><li>Output may be free-form text but ideally only one short paragraph.</li><li>Must not output any information that is already covered in the core asdf-vm documentation.</li><li>Should be tailored to the Operating System and version of the tool being installed (using optionally set Environment Variables <code>ASDF_INSTALL_VERSION</code> and <code>ASDF_INSTALL_TYPE</code>).</li><li>Success should exit with <code>0</code>.</li><li>Failure should exit with a non-zero status.</li></ul><p><strong>Environment Variables available to script</strong></p><ul><li><code>ASDF_INSTALL_TYPE</code>: <code>version</code> or <code>ref</code></li><li><code>ASDF_INSTALL_VERSION</code>: <ul><li>Full version number if <code>ASDF_INSTALL_TYPE=version</code>.</li><li>Git ref (tag/commit/branch) if <code>ASDF_INSTALL_TYPE=ref</code>.</li></ul></li><li><code>ASDF_INSTALL_PATH</code>: The path to where the tool <em>has been</em>, or <em>should be</em> installed.</li></ul><p><strong>Commands that invoke this script</strong></p><ul><li><code>asdf help <name> [<version>]</code>: Output documentation for plugin and tool</li></ul><p><strong>Call signature from asdf core</strong></p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">"${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">plugin_path</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">}"</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">/bin/help.overview</span></span></code></pre></div><hr><h3 id="bin-help-deps" tabindex="-1"><code>bin/help.deps</code> <a class="header-anchor" href="#bin-help-deps" aria-label="Permalink to "`bin/help.deps`""></a></h3><p><strong>Description</strong></p><p>Output the list of dependencies tailored to the operating system. One dependency per line.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">git</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">sed</span></span></code></pre></div><p><strong>Implementation Details</strong></p><ul><li>This script requires <code>bin/help.overview</code> for its output to be considered.</li><li>Should be tailored to the Operating System and version of the tool being installed (using optionally set Environment Variables <code>ASDF_INSTALL_VERSION</code> and <code>ASDF_INSTALL_TYPE</code>).</li><li>Success should exit with <code>0</code>.</li><li>Failure should exit with a non-zero status.</li></ul><p><strong>Environment Variables available to script</strong></p><ul><li><code>ASDF_INSTALL_TYPE</code>: <code>version</code> or <code>ref</code></li><li><code>ASDF_INSTALL_VERSION</code>: <ul><li>Full version number if <code>ASDF_INSTALL_TYPE=version</code>.</li><li>Git ref (tag/commit/branch) if <code>ASDF_INSTALL_TYPE=ref</code>.</li></ul></li><li><code>ASDF_INSTALL_PATH</code>: The path to where the tool <em>has been</em>, or <em>should be</em> installed.</li></ul><p><strong>Commands that invoke this script</strong></p><ul><li><code>asdf help <name> [<version>]</code>: Output documentation for plugin and tool</li></ul><p><strong>Call signature from asdf core</strong></p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">"${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">plugin_path</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">}"</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">/bin/help.deps</span></span></code></pre></div><hr><h3 id="bin-help-config" tabindex="-1"><code>bin/help.config</code> <a class="header-anchor" href="#bin-help-config" aria-label="Permalink to "`bin/help.config`""></a></h3><p><strong>Description</strong></p><p>Output any required or optional configuration for the plugin and tool. For example, describe any environment variables or other flags needed to install or compile the tool.</p><p><strong>Implementation Details</strong></p><ul><li>This script requires <code>bin/help.overview</code> for its output to be considered.</li><li>Output can be free-form text.</li><li>Should be tailored to the Operating System and version of the tool being installed (using optionally set Environment Variables <code>ASDF_INSTALL_VERSION</code> and <code>ASDF_INSTALL_TYPE</code>).</li><li>Success should exit with <code>0</code>.</li><li>Failure should exit with a non-zero status.</li></ul><p><strong>Environment Variables available to script</strong></p><ul><li><code>ASDF_INSTALL_TYPE</code>: <code>version</code> or <code>ref</code></li><li><code>ASDF_INSTALL_VERSION</code>: <ul><li>Full version number if <code>ASDF_INSTALL_TYPE=version</code>.</li><li>Git ref (tag/commit/branch) if <code>ASDF_INSTALL_TYPE=ref</code>.</li></ul></li><li><code>ASDF_INSTALL_PATH</code>: The path to where the tool <em>has been</em>, or <em>should be</em> installed.</li></ul><p><strong>Commands that invoke this script</strong></p><ul><li><code>asdf help <name> [<version>]</code>: Output documentation for plugin and tool</li></ul><p><strong>Call signature from asdf core</strong></p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">"${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">plugin_path</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">}"</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">/bin/help.config</span></span></code></pre></div><hr><h3 id="bin-help-links" tabindex="-1"><code>bin/help.links</code> <a class="header-anchor" href="#bin-help-links" aria-label="Permalink to "`bin/help.links`""></a></h3><p><strong>Description</strong></p><p>Output a list of links relevant to the plugin and tool. One link per line.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> Repository:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://github.com/vlang/v</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Documentation:</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://vlang.io</span></span></code></pre></div><p><strong>Implementation Details</strong></p><ul><li>This script requires <code>bin/help.overview</code> for its output to be considered.</li><li>One link per line.</li><li>Format must be either: <ul><li><code><title>: <link></code></li><li>or just <code><link></code></li></ul></li><li>Should be tailored to the Operating System and version of the tool being installed (using optionally set Environment Variables <code>ASDF_INSTALL_VERSION</code> and <code>ASDF_INSTALL_TYPE</code>).</li><li>Success should exit with <code>0</code>.</li><li>Failure should exit with a non-zero status.</li></ul><p><strong>Environment Variables available to script</strong></p><ul><li><code>ASDF_INSTALL_TYPE</code>: <code>version</code> or <code>ref</code></li><li><code>ASDF_INSTALL_VERSION</code>: <ul><li>Full version number if <code>ASDF_INSTALL_TYPE=version</code>.</li><li>Git ref (tag/commit/branch) if <code>ASDF_INSTALL_TYPE=ref</code>.</li></ul></li><li><code>ASDF_INSTALL_PATH</code>: The path to where the tool <em>has been</em>, or <em>should be</em> installed.</li></ul><p><strong>Commands that invoke this script</strong></p><ul><li><code>asdf help <name> [<version>]</code>: Output documentation for plugin and tool</li></ul><p><strong>Call signature from asdf core</strong></p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">"${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">plugin_path</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">}"</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">/bin/help.links</span></span></code></pre></div><hr><h3 id="bin-list-bin-paths" tabindex="-1"><code>bin/list-bin-paths</code> <a class="header-anchor" href="#bin-list-bin-paths" aria-label="Permalink to "`bin/list-bin-paths`""></a></h3><p><strong>Description</strong></p><p>List directories containing executables for the specified version of the tool.</p><p><strong>Implementation Details</strong></p><ul><li>If this script is not present, asdf will look for binaries in the <code>"${ASDF_INSTALL_PATH}"/bin</code> directory & create shims for those.</li><li>Output a space-separated list of paths containing executables.</li><li>Paths must be relative to <code>ASDF_INSTALL_PATH</code>. Example output would be:</li></ul><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">bin</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> tools</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> veggies</span></span></code></pre></div><p>This will instruct asdf to create shims for the files in:</p><ul><li><code>"${ASDF_INSTALL_PATH}"/bin</code></li><li><code>"${ASDF_INSTALL_PATH}"/tools</code></li><li><code>"${ASDF_INSTALL_PATH}"/veggies</code></li></ul><p><strong>Environment Variables available to script</strong></p><ul><li><code>ASDF_INSTALL_TYPE</code>: <code>version</code> or <code>ref</code></li><li><code>ASDF_INSTALL_VERSION</code>: <ul><li>Full version number if <code>ASDF_INSTALL_TYPE=version</code>.</li><li>Git ref (tag/commit/branch) if <code>ASDF_INSTALL_TYPE=ref</code>.</li></ul></li><li><code>ASDF_INSTALL_PATH</code>: The path to where the tool <em>has been</em>, or <em>should be</em> installed.</li></ul><p><strong>Commands that invoke this script</strong></p><ul><li><code>asdf install <tool> [version]</code>: initially create shims for binaries.</li><li><code>asdf reshim <tool> <version></code>: recreate shims for binaries.</li></ul><p><strong>Call signature from asdf core</strong></p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">"${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">plugin_path</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">}/bin/list-bin-paths"</span></span></code></pre></div><hr><h3 id="bin-exec-env" tabindex="-1"><code>bin/exec-env</code> <a class="header-anchor" href="#bin-exec-env" aria-label="Permalink to "`bin/exec-env`""></a></h3><p><strong>Description</strong></p><p>Prepare the environment before executing the shims for the binaries for the tool.</p><p><strong>Environment Variables available to script</strong></p><ul><li><code>ASDF_INSTALL_TYPE</code>: <code>version</code> or <code>ref</code></li><li><code>ASDF_INSTALL_VERSION</code>: <ul><li>Full version number if <code>ASDF_INSTALL_TYPE=version</code>.</li><li>Git ref (tag/commit/branch) if <code>ASDF_INSTALL_TYPE=ref</code>.</li></ul></li><li><code>ASDF_INSTALL_PATH</code>: The path to where the tool <em>has been</em>, or <em>should be</em> installed.</li></ul><p><strong>Commands that invoke this script</strong></p><ul><li><code>asdf which <command></code>: Display the path to an executable</li><li><code>asdf exec <command> [args...]</code>: Executes the command shim for current version</li><li><code>asdf env <command> [util]</code>: Runs util (default: <code>env</code>) inside the environment used for command shim execution.</li></ul><p><strong>Call signature from asdf core</strong></p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">"${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">plugin_path</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">}/bin/exec-env"</span></span></code></pre></div><hr><h3 id="bin-exec-path" tabindex="-1"><code>bin/exec-path</code> <a class="header-anchor" href="#bin-exec-path" aria-label="Permalink to "`bin/exec-path`""></a></h3><p>Get the executable path for the specified version of the tool. Must print a string with the relative executable path. This allows the plugin to conditionally override the shim's specified executable path, otherwise return the default path specified by the shim.</p><p><strong>Description</strong></p><p>Get the executable path for the specified version of the tool.</p><p><strong>Implementation Details</strong></p><ul><li>Must print a string with the relative executable path.</li><li>Conditionally override the shim's specified executable path, otherwise return the default path specified by the shim.</li></ul><div class="language-shell vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">shell</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Usage:</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> plugin/bin/exec-path</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">install-pat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">h</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">comman</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">executable-pat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">h</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span></span>\n<span class="line"></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Example</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> Call:</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> ~/.asdf/plugins/foo/bin/exec-path</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "~/.asdf/installs/foo/1.0"</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "foo"</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "bin/foo"</span></span>\n<span class="line"></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">Output:</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> bin/foox</span></span></code></pre></div><p><strong>Environment Variables available to script</strong></p><ul><li><code>ASDF_INSTALL_TYPE</code>: <code>version</code> or <code>ref</code></li><li><code>ASDF_INSTALL_VERSION</code>: <ul><li>Full version number if <code>ASDF_INSTALL_TYPE=version</code>.</li><li>Git ref (tag/commit/branch) if <code>ASDF_INSTALL_TYPE=ref</code>.</li></ul></li><li><code>ASDF_INSTALL_PATH</code>: The path to where the tool <em>has been</em>, or <em>should be</em> installed.</li></ul><p><strong>Commands that invoke this script</strong></p><ul><li><code>asdf which <command></code>: Display the path to an executable</li><li><code>asdf exec <command> [args...]</code>: Executes the command shim for current version</li><li><code>asdf env <command> [util]</code>: Runs util (default: <code>env</code>) inside the environment used for command shim execution.</li></ul><p><strong>Call signature from asdf core</strong></p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">"${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">plugin_path</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">}/bin/exec-path"</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$install_path</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$cmd</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$relative_path</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"</span></span></code></pre></div><hr><h3 id="bin-uninstall" tabindex="-1"><code>bin/uninstall</code> <a class="header-anchor" href="#bin-uninstall" aria-label="Permalink to "`bin/uninstall`""></a></h3><p><strong>Description</strong></p><p>Uninstall the provided version of a tool.</p><p><strong>Output Format</strong></p><p>Output should be sent to <code>stdout</code> or <code>stderr</code> as appropriate for the user. No output is read by subsequent execution in the core.</p><p><strong>Environment Variables available to script</strong></p><p>No environment variables are provided to this script.</p><p><strong>Commands that invoke this script</strong></p><ul><li><code>asdf list all <name> <version></code></li><li><code>asdf uninstall nodejs 18.15.0</code>: Uninstalls the version <code>18.15.0</code> of nodejs, removing all shims including those installed global with <code>npm i -g</code></li></ul><p><strong>Call signature from asdf core</strong></p><p>No parameters provided.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">"${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">plugin_path</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">}/bin/uninstall"</span></span></code></pre></div><hr><h3 id="bin-list-legacy-filenames" tabindex="-1"><code>bin/list-legacy-filenames</code> <a class="header-anchor" href="#bin-list-legacy-filenames" aria-label="Permalink to "`bin/list-legacy-filenames`""></a></h3><p><strong>Description</strong></p><p>List legacy configuration filenames for determining the specified version of the tool.</p><p><strong>Implementation Details</strong></p><ul><li>Output a space-separated list of filenames.<div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">.ruby-version</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .rvmrc</span></span></code></pre></div></li><li>Only applies for users who have enabled the <code>legacy_version_file</code> option in their <code>"${HOME}"/.asdfrc</code>.</li></ul><p><strong>Environment Variables available to script</strong></p><ul><li><code>ASDF_INSTALL_TYPE</code>: <code>version</code> or <code>ref</code></li><li><code>ASDF_INSTALL_VERSION</code>: <ul><li>Full version number if <code>ASDF_INSTALL_TYPE=version</code>.</li><li>Git ref (tag/commit/branch) if <code>ASDF_INSTALL_TYPE=ref</code>.</li></ul></li><li><code>ASDF_INSTALL_PATH</code>: The path to where the tool <em>has been</em>, or <em>should be</em> installed.</li></ul><p><strong>Commands that invoke this script</strong></p><p>Any command which reads a tool version.</p><p><strong>Call signature from asdf core</strong></p><p>No parameters provided.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">"${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">plugin_path</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">}/bin/list-legacy-filenames"</span></span></code></pre></div><hr><h3 id="bin-parse-legacy-file" tabindex="-1"><code>bin/parse-legacy-file</code> <a class="header-anchor" href="#bin-parse-legacy-file" aria-label="Permalink to "`bin/parse-legacy-file`""></a></h3><p><strong>Description</strong></p><p>Parse the legacy file found by asdf to determine the version of the tool. Useful to extract version numbers from files like JavaScript's <code>package.json</code> or Golangs <code>go.mod</code>.</p><p><strong>Implementation Details</strong></p><ul><li>If not present, asdf will simply <code>cat</code> the legacy file to determine the version.</li><li>Should be <strong>deterministic</strong> and always return the same exact version: <ul><li>when parsing the same legacy file.</li><li>regardless of what is installed on the machine or whether the legacy version is valid or complete. Some legacy file formats may not be suitable.</li></ul></li><li>Output a single line with the version:<div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">1.2.3</span></span></code></pre></div></li></ul><p><strong>Environment Variables available to script</strong></p><p>No environment variables specifically set before this script is called.</p><p><strong>Commands that invoke this script</strong></p><p>Any command which reads a tool version.</p><p><strong>Call signature from asdf core</strong></p><p>The script should accept a single argument, the path to the legacy file for reading its contents.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">"${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">plugin_path</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">}/bin/parse-legacy-file"</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$file_path</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"</span></span></code></pre></div><hr><h3 id="bin-post-plugin-add" tabindex="-1"><code>bin/post-plugin-add</code> <a class="header-anchor" href="#bin-post-plugin-add" aria-label="Permalink to "`bin/post-plugin-add`""></a></h3><p><strong>Description</strong></p><p>Execute this callback script <strong>after</strong> the plugin has been <em>added</em> to asdf with <code>asdf plugin add <tool></code>.</p><p>See also the related command hooks:</p><ul><li><code>pre_asdf_plugin_add</code></li><li><code>pre_asdf_plugin_add_${plugin_name}</code></li><li><code>post_asdf_plugin_add</code></li><li><code>post_asdf_plugin_add_${plugin_name}</code></li></ul><p><strong>Environment Variables available to script</strong></p><ul><li><code>ASDF_PLUGIN_PATH</code>: path where the plugin was installed.</li><li><code>ASDF_PLUGIN_SOURCE_URL</code>: URL of the plugin source. Can be a local directory path.</li></ul><p><strong>Call signature from asdf core</strong></p><p>No parameters provided.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">"${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">plugin_path</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">}/bin/post-plugin-add"</span></span></code></pre></div><hr><h3 id="bin-post-plugin-update" tabindex="-1"><code>bin/post-plugin-update</code> <a class="header-anchor" href="#bin-post-plugin-update" aria-label="Permalink to "`bin/post-plugin-update`""></a></h3><p><strong>Description</strong></p><p>Execute this callback script <strong>after</strong> asdf has downloaded the <em>update</em> plugin with <code>asdf plugin update <tool> [<git-ref>]</code>.</p><p>See also the related command hooks:</p><ul><li><code>pre_asdf_plugin_update</code></li><li><code>pre_asdf_plugin_update_${plugin_name}</code></li><li><code>post_asdf_plugin_update</code></li><li><code>post_asdf_plugin_update_${plugin_name}</code></li></ul><p><strong>Environment Variables available to script</strong></p><ul><li><code>ASDF_PLUGIN_PATH</code>: path where the plugin was installed.</li><li><code>ASDF_PLUGIN_PREV_REF</code>: the plugin's previous git-ref</li><li><code>ASDF_PLUGIN_POST_REF</code>: the plugin's updated git-ref</li></ul><p><strong>Call signature from asdf core</strong></p><p>No parameters provided.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">"${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">plugin_path</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">}/bin/post-plugin-update"</span></span></code></pre></div><hr><h3 id="bin-pre-plugin-remove" tabindex="-1"><code>bin/pre-plugin-remove</code> <a class="header-anchor" href="#bin-pre-plugin-remove" aria-label="Permalink to "`bin/pre-plugin-remove`""></a></h3><p><strong>Description</strong></p><p>Execute this callback script <strong>before</strong> asdf has removed the plugin with <code>asdf plugin remove <tool></code>.</p><p>See also the related command hooks:</p><ul><li><code>pre_asdf_plugin_remove</code></li><li><code>pre_asdf_plugin_remove_${plugin_name}</code></li><li><code>post_asdf_plugin_remove</code></li><li><code>post_asdf_plugin_remove_${plugin_name}</code></li></ul><p><strong>Environment Variables available to script</strong></p><ul><li><code>ASDF_PLUGIN_PATH</code>: path where the plugin was installed.</li></ul><p><strong>Call signature from asdf core</strong></p><p>No parameters provided.</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">"${</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">plugin_path</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">}/bin/pre-plugin-remove"</span></span></code></pre></div>',172)),s("h2",F,[i[42]||(i[42]=e("Extension Commands for asdf CLI ")),a(t,{type:"danger",text:"advanced",vertical:"middle"}),i[43]||(i[43]=e()),i[44]||(i[44]=s("a",{class:"header-anchor",href:"#extension-commands-for-asdf-cli","aria-label":'Permalink to "Extension Commands for asdf CLI <Badge type="danger" text="advanced" vertical="middle" />"'},"",-1))]),i[54]||(i[54]=l('<p>It's possible for plugins to define new asdf commands by providing <code>lib/commands/command*.bash</code> scripts or executables that will be callable using the asdf command line interface by using the plugin name as a subcommand.</p><p>For example, suppose a <code>foo</code> plugin has:</p><div class="language-shell vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">shell</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">foo/</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> lib/commands/</span></span>\n<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> command</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.bash</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> command-bat.bash</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> command-bat-man.bash</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> command-help.bash</span></span></code></pre></div><p>Users can now execute:</p><div class="language-shell vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">shell</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">$</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> asdf</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> foo</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # same as running `$ASDF_DATA_DIR/plugins/foo/lib/commands/command.bash`</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">$</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> asdf</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> foo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> bar</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # same as running `$ASDF_DATA_DIR/plugins/foo/lib/commands/command.bash bar`</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">$</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> asdf</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> foo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> help</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # same as running `$ASDF_DATA_DIR/plugins/foo/lib/commands/command-help.bash`</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">$</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> asdf</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> foo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> bat</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> man</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # same as running `$ASDF_DATA_DIR/plugins/foo/lib/commands/command-bat-man.bash`</span></span>\n<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">$</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> asdf</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> foo</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> bat</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> baz</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # same as running `$ASDF_DATA_DIR/plugins/foo/lib/commands/command-bat.bash baz`</span></span></code></pre></div><p>Plugin authors can use this feature to provide utilities related to their tools, or even create plugins that are just new command extensions of asdf itself.</p><p>If the executable bit is set, the script is executed, replacing the asdf execution.</p><p>If the executable bit is not set, asdf will source the scripts as Bash scripts.</p><p><code>$ASDF_CMD_FILE</code> resolves to the full path of the file being sourced.</p><p><a href="https://github.com/asdf-community/asdf-haxe" target="_blank" rel="noreferrer"><code>haxe</code></a> is a great example of a plugin which uses this feature. It provides the <code>asdf haxe neko-dylibs-link</code> to fix an issue where Haxe executables expect to find dynamic libraries relative to the executable directory.</p><p>Be sure to list your asdf Extension Commands in your plugins README.</p>',11)),s("h2",v,[i[45]||(i[45]=e("Custom Shim Templates ")),a(t,{type:"danger",text:"advanced",vertical:"middle"}),i[46]||(i[46]=e()),i[47]||(i[47]=s("a",{class:"header-anchor",href:"#custom-shim-templates","aria-label":'Permalink to "Custom Shim Templates <Badge type="danger" text="advanced" vertical="middle" />"'},"",-1))]),i[55]||(i[55]=l(`<div class="warning custom-block"><p class="custom-block-title">WARNING</p><p>Please only use if <strong>absolutely</strong> required</p></div><p>asdf allows custom shim templates. For an executable called <code>foo</code>, if there's a <code>shims/foo</code> file in the plugin, then asdf will copy that file instead of using its standard shim template.</p><p><strong>This must be used wisely.</strong></p><p>As far as the asdf core team is aware, this feature is only in use in the first-party <a href="https://github.com/asdf-vm/asdf-elixir" target="_blank" rel="noreferrer">Elixir plugin</a>. This is because an executable is also read as an Elixir file in addition to being an executable. This makes it not possible to use the standard Bash shim.</p><h2 id="testing" tabindex="-1">Testing <a class="header-anchor" href="#testing" aria-label="Permalink to "Testing""></a></h2><p><code>asdf</code> contains the <code>plugin-test</code> command to test your plugin:</p><div class="language-shell vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">shell</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">asdf</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> plugin</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> test</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">plugin_nam</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">plugin_ur</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">l</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--asdf-tool-version </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"><</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">versio</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">n</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--asdf-plugin-gitref </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"><</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">git_re</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">f</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [test_command...]</span></span></code></pre></div><ul><li><code><plugin_name></code> & <code><plugin_url></code> are required</li><li>If optional <code>[--asdf-tool-version <version>]</code> is specified, the tool will be installed with that specific version. Defaults to <code>asdf latest <plugin-name></code></li><li>If optional <code>[--asdf-plugin-gitref <git_ref>]</code> 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. Defaults to the default branch of the plugin's repository.</li><li>Optional parameter <code>[test_command...]</code> is the command to execute to validate the installed tool works correctly. Typically <code><tool> --version</code> or <code><tool> --help</code>. For example, to test the NodeJS plugin, we could run<div class="language-shell vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">shell</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># asdf plugin test <plugin_name> <plugin_url> [test_command]</span></span>
|
||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> asdf</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> plugin</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> test</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> nodejs</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://github.com/asdf-vm/asdf-nodejs.git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> node</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --version</span></span></code></pre></div></li></ul><div class="tip custom-block"><p class="custom-block-title">Note</p><p>We recommend testing in both Linux & macOS CI environments</p></div><h3 id="github-action" tabindex="-1">GitHub Action <a class="header-anchor" href="#github-action" aria-label="Permalink to "GitHub Action""></a></h3><p>The <a href="https://github.com/asdf-vm/actions" target="_blank" rel="noreferrer">asdf-vm/actions</a> repo provides a GitHub Action for testing your plugins hosted on GitHub. A sample <code>.github/workflows/test.yaml</code> Actions Workflow:</p><div class="language-yaml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">Test</span></span>
|
||
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">on</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
|
||
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> push</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
|
||
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> branches</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
|
||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">main</span></span>
|
||
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> pull_request</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
|
||
<span class="line"></span>
|
||
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">jobs</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
|
||
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> plugin_test</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
|
||
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">asdf plugin test</span></span>
|
||
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> strategy</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
|
||
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> matrix</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
|
||
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> os</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
|
||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">ubuntu-latest</span></span>
|
||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">macos-latest</span></span>
|
||
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> runs-on</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">\${{ matrix.os }}</span></span>
|
||
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> steps</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
|
||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">name</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">asdf_plugin_test</span></span>
|
||
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> uses</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">asdf-vm/actions/plugin-test@v2</span></span>
|
||
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> with</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
|
||
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;"> command</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"<MY_TOOL> --version"</span></span></code></pre></div><h3 id="travisci-config" tabindex="-1">TravisCI Config <a class="header-anchor" href="#travisci-config" aria-label="Permalink to "TravisCI Config""></a></h3><p>A sample <code>.travis.yml</code> file, customize it to your needs</p><div class="language-yaml vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">yaml</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">language</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">c</span></span>
|
||
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">script</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">asdf plugin test <MY_TOOL> $TRAVIS_BUILD_DIR '<MY_TOOL> --version'</span></span>
|
||
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">before_script</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
|
||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">git clone https://github.com/asdf-vm/asdf.git asdf</span></span>
|
||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">. asdf/asdf.sh</span></span>
|
||
<span class="line"><span style="--shiki-light:#22863A;--shiki-dark:#85E89D;">os</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">:</span></span>
|
||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">linux</span></span>
|
||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> - </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">osx</span></span></code></pre></div><div class="tip custom-block"><p class="custom-block-title">NOTE</p><p>When using another CI you may need to pass a relative path to the plugin location:</p><div class="language-shell vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">shell</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">asdf</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> plugin</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> test</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">tool_nam</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pat</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">h</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> '<tool_command> --version'</span></span></code></pre></div></div><h2 id="api-rate-limiting" tabindex="-1">API Rate Limiting <a class="header-anchor" href="#api-rate-limiting" aria-label="Permalink to "API Rate Limiting""></a></h2><p>If a command depends on accessing an external API, like <code>bin/list-all</code> or <code>bin/latest-stable</code>, it may experience rate limiting during automated testing. To mitigate this, ensure there is a code-path which provides an authentication token via an environment variable. For example:</p><div class="language-shell vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">shell</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">cmd</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"curl --silent"</span></span>
|
||
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">if</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [ </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">-n</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$GITHUB_API_TOKEN</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ]; </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">then</span></span>
|
||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> cmd</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$cmd</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> -H 'Authorization: token </span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$GITHUB_API_TOKEN</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">'"</span></span>
|
||
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">fi</span></span>
|
||
<span class="line"></span>
|
||
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">cmd</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$cmd</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> $releases_path</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"</span></span></code></pre></div><h3 id="github-api-token" tabindex="-1"><code>GITHUB_API_TOKEN</code> <a class="header-anchor" href="#github-api-token" aria-label="Permalink to "\`GITHUB_API_TOKEN\`""></a></h3><p>To utilise the <code>GITHUB_API_TOKEN</code>, create a <a href="https://github.com/settings/tokens/new" target="_blank" rel="noreferrer">new personal token</a> with only <code>public_repo</code> access.</p><p>Then add this to your CI pipeline environment variables.</p><div class="warning custom-block"><p class="custom-block-title">WARNING</p><p>NEVER publish your authentication tokens in your code repository</p></div><h2 id="plugin-shortname-index" tabindex="-1">Plugin Shortname Index <a class="header-anchor" href="#plugin-shortname-index" aria-label="Permalink to "Plugin Shortname Index""></a></h2><div class="tip custom-block"><p class="custom-block-title">TIP</p><p>The recommended installation method for a plugin is via direct URL installation:</p><div class="language-shell vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">shell</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># asdf plugin add <name> <git_url></span></span>
|
||
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> asdf</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> plugin</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> add</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> nodejs</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> https://github.com/asdf-vm/asdf-nodejs</span></span></code></pre></div></div><p>If the <code>git_url</code> is not provided, asdf will use the <a href="https://github.com/asdf-vm/asdf-plugins" target="_blank" rel="noreferrer">Shortname Index repository</a> to determine the exact <code>git_url</code> to use.</p><p>You can add your plugin to the <a href="https://github.com/asdf-vm/asdf-plugins" target="_blank" rel="noreferrer">Shortname Index</a> by following the instructions in that repo.</p>`,27))])}const L=n(r,[["render",E]]);export{T as __pageData,L as default};
|