Pular para o conteúdo principal
Versão: Próxima

Visão Geral de Dependências de Módulos

:::warning Alpha — Dependências de Módulos Podem Mudar Dependências de módulos ainda estão sendo refinadas. Embora nosso objetivo seja manter compatibilidade retroativa, mudanças incompatíveis podem ocorrer antes do release 1.0. Arquivos de lock mantêm builds reprodutíveis, mas o comportamento de resolução pode evoluir. :::

Dependências de módulos permitem que um módulo use comandos de outros módulos hospedados em repositórios Git. Dependências são declaradas em invowkmod.cue em requires e resolvidas em invowkmod.lock.cue.

O que são Dependências de Módulos?​

Dependências de módulos são módulos externos dos quais seu módulo depende. Elas são:

  • Hospedadas em repositórios Git (GitHub, GitLab, Bitbucket, etc.)
  • Versionadas com semver (tags como v1.2.3 ou 1.2.3)
  • Cacheadas localmente para uso offline e performance
  • Publicadas sob um ID de origem de comando derivado do ID do módulo de dependência ou alias para evitar colisões

Início Rápido​

1. (Opcional) Resolver uma Dependência​

invowk module add resolve uma dependência, atualiza invowkmod.lock.cue e autoedita invowkmod.cue para adicionar a entrada em requires quando o arquivo existir:

invowk module add https://github.com/example/common.git ^1.0.0

2. Declarar em invowkmod.cue​

module: "com.example.mytools"
version: "1.0.0"
description: "My tools"

requires: [
    {
        git_url: "https://github.com/example/common.git"
        version: "^1.0.0"
        alias: "common"
    },
]

3. Sincronizar Dependências​

invowk module sync

4. Verificar Dependências Resolvidas​

invowk module deps

Namespaces e Aliases​

Quando um módulo de dependência está instalado em um caminho de descoberta, seus comandos são publicados sob um ID de origem de comando. O ID padrão é o ID do módulo de dependência; alias o sobrescreve. Execute o nome simples quando ele for único, ou use @<source> / --ivk-from <source> para desambiguar:

# Default command source ID
invowk cmd common build

# Disambiguate when another source also defines "build"
invowk cmd @common build
invowk cmd --ivk-from common build

# With alias
invowk cmd tools build

Como Funciona​

  1. Declaração: Dependências são listadas em invowkmod.cue em requires
  2. Resolução: invowk module sync resolve restrições de versão para versões concretas
  3. Download: Módulos são clonados do Git e cacheados localmente
  4. Lock file: Versões resolvidas são gravadas em invowkmod.lock.cue
  5. Descoberta: Comandos ficam disponíveis pelo ID de origem de comando do módulo quando a dependência é instalada

:::note Dependências Explícitas (Estilo Go) O Invowk usa um modelo de dependências explícitas, similar ao Go modules: todo módulo na árvore de dependências deve ser declarado no invowkmod.cue raiz. Se o módulo A requer o módulo B, e B requer C, então C também deve ser declarado no seu invowkmod.cue.

  • invowk module sync falha com erros acionáveis se dependências transitivas estiverem faltando.
  • invowk module tidy adiciona automaticamente dependências transitivas faltantes ao seu invowkmod.cue.

Ao declarar depends_on.cmds, comandos em um módulo só podem referenciar comandos de:

  1. O mesmo módulo
  2. Módulos de comandos do usuário instalados globalmente em ~/.invowk/cmds/
  3. Módulos declarados diretamente na lista requires desse módulo

Este escopo é aplicado pela validação de depends_on.cmds antes da execução de comandos. Não intercepta chamadas de subprocesso em tempo de execução dentro de scripts. :::

Cache de Módulos​

Dependências de módulos são cacheadas em ~/.invowk/modules/ por padrão:

~/.invowk/modules/
├── sources/
│   └── github.com/
│       └── example/
│           └── common/
└── github.com/
    └── example/
        └── common/
            └── 1.2.3/
                └── io.example.common.invowkmod/
                    ├── invowkmod.cue
                    └── invowkfile.cue

Sobrescreva a localização do cache:

export INVOWK_MODULES_PATH=/custom/cache/path

Próximos Passos​