asdf/docs/pt-br/guide/getting-started.md

Começando

Hi, we've recently migrated our docs and added some new pages. If you would like to help translate this page, see the "Edit this page" link at the bottom of the page.

A instalação do asdf envolve:

1. Instalar as dependências
2. Instalar o núcleo do asdf
3. Adicionar o asdf ao seu shell
4. Instalar um plugin para cada ferramenta que você gostaria de gerenciar
5. Instalar uma versão desta ferramenta
6. Definir uma versão global e uma versão local através do arquivo de configuração .tool-versions

Você pode também acompanhar o passo a passo da instalação através deste vídeo.

1. Instalando as dependências

asdf primarily requires git & curl. Here is a non-exhaustive list of commands to run for your package manager (some might automatically install these tools in later steps).

OS	Package Manager	Command
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 Note

sudo may be required depending on your system configuration.

:::

2. Download asdf

Official Download

git clone https://github.com/asdf-vm/asdf.git ~/.asdf --branch v0.14.1

Community Supported Download Methods

We highly recommend using the official git method.

Method	Command
Homebrew	brew install asdf
Pacman	git clone https://aur.archlinux.org/asdf-vm.git && cd asdf-vm && makepkg -si or use your preferred AUR helper

3. Adicionando ao seu shell

Existem diversas combinações de shells, sistemas operacionais e métodos de instalação que podem impactar a configuração. Abaixo, expanda a seção que se adeque mais com o seu sistema:

::: details Bash & Git

Adicione esta linha ao seu ~/.bashrc:

. "$HOME/.asdf/asdf.sh"

O auto completar deve ser configurado manualmente a partir da adição da seguinte linha ao .bashrc:

. "$HOME/.asdf/completions/asdf.bash"

:::

::: details Bash & Git (macOS)

Se você estiver usando o macOS Catalina ou mais recente, o shell padrão mudou para o ZSH. A não ser que você tenha voltado para o bash, siga as instruções de instalação para o ZSH.

Adicione esta linha ao seu ~/.bash_profile:

. "$HOME/.asdf/asdf.sh"

O auto completar deve ser configurado manualmente a partir da adição da seguinte linha ao .bash_profile:

. "$HOME/.asdf/completions/asdf.bash"

:::

::: details Bash & Homebrew

Adicione asdf.sh ao ~/.bashrc através do comando:

echo -e "\n. $(brew --prefix asdf)/asdf.sh" >> ~/.bashrc

O auto completar deve ser configurado seguindo as instruções da Homebrew, ou as seguintes:

echo -e "\n. \"$(brew --prefix asdf)/etc/bash_completion.d/asdf.bash\"" >> ~/.bashrc

:::

::: details Bash & Homebrew (macOS)

Se você estiver usando o macOS Catalina ou mais recente, o shell padrão mudou para o ZSH. A não ser que você tenha voltado para o bash, siga as instruções de instalação para o ZSH.

Adicione asdf.sh ao ~/.bash_profile através do comando:

echo -e "\n. $(brew --prefix asdf)/asdf.sh" >> ~/.bash_profile

O auto completar deve ser configurado seguindo as instruções da Homebrew, ou as seguintes:

echo -e "\n. \"$(brew --prefix asdf)/etc/bash_completion.d/asdf.bash\"" >> ~/.bash_profile

:::

::: details Bash & Pacman

Adicione a seguinte linha ao seu ~/.bashrc:

. /opt/asdf-vm/asdf.sh

O pacote bash-completion precisa ser instalado para o auto completar funcionar. :::

::: details Fish & Git

Adicione a seguinte linha ao seu ~/.config/fish/config.fish:

source ~/.asdf/asdf.fish

O auto completar deve ser configurado manualmente através do seguinte comando:

mkdir -p ~/.config/fish/completions; and ln -s ~/.asdf/completions/asdf.fish ~/.config/fish/completions

:::

::: details Fish & Homebrew

Adicione asdf.fish ao seu ~/.config/fish/config.fish através do comando:

echo -e "\nsource "(brew --prefix asdf)"/asdf.fish" >> ~/.config/fish/config.fish

O auto completar é configurado pela Homebrew para o fish shell. :::

::: details Fish & Pacman

Adicione a seguinte linha ao seu ~/.config/fish/config.fish:

source /opt/asdf-vm/asdf.fish

O auto completar é configurado automaticamente durante a instalação do pacote AUR. :::

::: details Elvish & Git

Adicione asdf.elv ao ~/.config/elvish/rc.elv através do comando:

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

Ao concluir atualizará automaticamente

:::

::: details Elvish & Homebrew

Adicione asdf.elv ao ~/.config/elvish/rc.elv através do comando:

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

Ao concluir atualizará automaticamente :::

::: details Elvish & Pacman

Adicione asdf.elv ao ~/.config/elvish/rc.elv através do comando:

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

Ao concluir atualizará automaticamente :::

::: details ZSH & Git

Adicione a seguinte linha ao seu ~/.zshrc:

. "$HOME/.asdf/asdf.sh"

OU utilize um framework para ZSH, como asdf para oh-my-zsh que irá adicionar o script e o auto completar.

O auto completar pode ser configurado ou pelo plugin do asdf para framework para ZSH, ou através da adição das seguintes linhas ao seu .zshrc:

# append completions to fpath
fpath=(${ASDF_DIR}/completions $fpath)
# initialise completions with ZSH's compinit
autoload -Uz compinit && compinit

• Se você está utilizando uma configuração compinit customizada, garanta que compinit esteja abaixo chamada asdf.sh
• Se você está utilizando uma configuração compinit customizada com um framework para ZSH, garanta que compinit esteja abaixo da chamada do framework.

Aviso

Se você está utilizando um framework para ZSH, o plugin do asdf pode precisar ser atualizado para utilização adequada do novo auto completar do ZSH através do fpath. O plugin do asdf para o oh-my-zsh ainda não foi atualizado, veja: ohmyzsh/ohmyzsh#8837. :::

::: details ZSH & Homebrew

Adicione asdf.sh ao seu ~/.zshrc através do comando:

echo -e "\n. $(brew --prefix asdf)/asdf.sh" >> ${ZDOTDIR:-~}/.zshrc

OU utilize um framework para ZSH, como asdf para oh-my-zsh que irá adicionar o script e o auto completar.

O auto completar pode ser configurado ou pelo framework para ZSH, ou de acordo com as instruções da Homebrew. Se você está usando um framework para ZSH, pode ser que seja necessário atualizar o plugin do asdf para que o novo auto completar funcione adequadamente através do fpath. O plugin do asdf para o Oh-My-ZSH ainda será atualizado, veja: ohmyzsh/ohmyzsh#8837. :::

::: details ZSH & Pacman

Adicione a seguinte linha ao seu ~/.zshrc:

. /opt/asdf-vm/asdf.sh

::: details PowerShell Core & Git

Adicione a seguinte linha ao seu ~/.config/powershell/profile.ps1:

. "$HOME/.asdf/asdf.ps1"

:::

::: details PowerShell Core & Homebrew

Adicione asdf.ps1 ao seu ~/.config/powershell/profile.ps1 através do comando:

echo -e "\n. \"$(brew --prefix asdf)/libexec/asdf.ps1\"" >> ~/.config/powershell/profile.ps1

:::

::: details PowerShell Core & Pacman

Adicione a seguinte linha ao seu ~/.config/powershell/profile.ps1:

. /opt/asdf-vm/asdf.ps1

:::

::: details Nushell & Git

Adicione asdf.nu ao seu ~/.config/nushell/config.nu através do comando:

"\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 :::

::: details Nushell & Homebrew

Adicione asdf.nu ao seu ~/.config/nushell/config.nu através do comando:

"\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 :::

::: details Nushell & Pacman

Adicione asdf.nu ao seu ~/.config/nushell/config.nu através do comando:

"\n$env.ASDF_DIR = '/opt/asdf-vm/'\n source /opt/asdf-vm/asdf.nu" | save --append $nu.config-path

Ao concluir atualizará automaticamente :::

::: details POSIX Shell & Git

Adicione a seguinte linha ao seu ~/.profile:

export ASDF_DIR="$HOME/.asdf"
. "$HOME/.asdf/asdf.sh"

:::

::: details POSIX Shell & Homebrew

Adicione asdf.sh ao ~/.profile através do comando:

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

Adicione a seguinte linha ao seu ~/.profile:

export ASDF_DIR="/opt/asdf-vm"
. /opt/asdf-vm/asdf.sh

:::

O auto completar é colocado em um local familiar para o ZSH, mas o ZSH deve ser configurado para conseguir utilizá-lo. :::

Os scripts do asdf precisam ser chamados depois de ter configurado a sua variável $PATH e depois de ter chamado o seu framework para ZSH (oh-my-zsh etc).

Reinicie seu shell para que as mudanças na variável PATH tenham efeito. Abrir uma nova janela/sessão de terminal o fará.

4. Instalando um plugin

Para demonstração, vamos instalar e configurar o Node.js através do plugin asdf-nodejs.

Dependências dos plugins

Cada plugin possui algumas dependências, por isso precisamos checar no repositório onde elas estão listadas. Por exemplo, para o asdf-nodejs são:

SO	Instalação de dependencia
Linux (Debian)	apt-get install dirmngr gpg curl gawk
macOS	brew install gpg gawk

Devemos instalar instalar as dependências primeiro, pois alguns plugins exigem algumas ações após a instalação.

Instalando o plugin

asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git

5. Instalando uma versão

Agora temos o plugin para o Node.js, nós podemos instalar uma versão desta ferramenta.

Podemos ver quais versões tão disponíveis através do comando asdf list all nodejs, ou uma lista específica de versões com asdf list all nodejs 14

Vamos instalar somente a última versão disponível, utilizando a tag latest:

asdf install nodejs latest

::: tip Nota asdf exige versões exatas. A palavra latest resulta na instalação da versão atual na data da execução. :::

6. Definindo uma versão

asdf executa uma verificação das versões das ferramentas a serem utilizadas através do arquivo .tool-versions presente desde diretório atual, até o diretório $HOME. A varredura ocorre no momento em que você executa uma ferramenta que o asdf gerencia.

::: warning Se uma versão não for especificada para uma ferramenta, ao executá-la resultará em erro. asdf current mostrará a ferramenta e sua versão, ou então a falta dela no seu diretório atual para que você possa observar quais ferramentas falharão ao serem executadas. :::

Versões globais

Os padrões globais são gerenciados em $HOME/.tool-versions. Defina uma versão global através do comando:

asdf global nodejs latest

$HOME/.tool-versions ficará assim:

nodejs 16.5.0

Alguns sistemas operacionais vêm por padrão com ferramentas que são gerenciadas pelo próprio sistema e não pelo asdf, python é um exemplo. Você precisa indicar para o asdf para devolver o gerenciamento para o sistema. A seção de referência de versões irá guiá-lo.

Versões locais

Versões locais são definidas no arquivo $PWD/.tool-versions (seu diretório atual). Geralmente, será um repositório Git para um projeto. Quando estiver no diretório desejado, execute:

asdf local nodejs latest

$PWD/.tool-versions ficará assim:

nodejs 16.5.0

Usando arquivos de versão existentes

asdf suporta a migração de arquivos de versão provenientes de outros gerenciadores de versão. Por exemplo: .ruby-version para o rbenv. Essa funcionalidade é baseada no plugin de cada ferramenta.

O asdf-nodejs suporta tanto arquivos .nvmrc quanto .node-version. Para ativar essa funcionalidade, adicione a seguinte linha ao seu arquivo de configuração do asdf - $HOME/.asdfrc:

legacy_version_file = yes

Veja a página de refencia da configuração para mais opções de configuração.

Setup finalizado!

A configuração inicial do asdf foi finalizada 🎉. Agora, você pode gerenciar versões do nodejs para o seus projetos. Siga passos semelhantes para cada ferramenta do seu projeto.

O asdf possui diversos outros comandos para se acustomar ainda, você pode ver todos eles através do comando asdf --help ou simplesmente asdf. Eles estão divididos em três categorias:

• núcleo asdf
• plugins
• versões (de ferramentas)