|
| 1 | +# Custom Directory Configuration |
| 2 | + |
| 3 | +## 🎯 **Problema Resolvido** |
| 4 | + |
| 5 | +Adicionada funcionalidade para customizar diretórios de instalação via arquivo `.llvmup-config`, resolvendo limitações do ambiente Docker onde apenas o working directory e seus subdiretorios são acessíveis. |
| 6 | + |
| 7 | +## ✅ **Nova Funcionalidade** |
| 8 | + |
| 9 | +### Seção `[paths]` no `.llvmup-config` |
| 10 | + |
| 11 | +```toml |
| 12 | +[paths] |
| 13 | +llvm_home = "./llvm" # Diretório base personalizado |
| 14 | +toolchains_dir = "./llvm/toolchains" # Diretório de instalações |
| 15 | +sources_dir = "./llvm/sources" # Diretório de código fonte |
| 16 | +``` |
| 17 | + |
| 18 | +# Custom Directory Configuration |
| 19 | + |
| 20 | +## 🎯 Problema resolvido |
| 21 | + |
| 22 | +É possível customizar diretórios de instalação via um arquivo de configuração `.llvmup-config`. Isso resolve limitações comuns em ambientes como Docker — onde apenas o diretório de trabalho e seus subdiretórios estão disponíveis — e facilita testes locais com estruturas personalizadas. |
| 23 | + |
| 24 | +## ✅ Nova funcionalidade |
| 25 | + |
| 26 | +Adicione a seção `[paths]` no `.llvmup-config` para sobrepor os diretórios padrão: |
| 27 | + |
| 28 | +```toml |
| 29 | +[paths] |
| 30 | +llvm_home = "./llvm" # Diretório base personalizado |
| 31 | +toolchains_dir = "./llvm/toolchains" # Diretório de instalações |
| 32 | +sources_dir = "./llvm/sources" # Diretório de código fonte |
| 33 | +``` |
| 34 | + |
| 35 | +### Exemplos |
| 36 | + |
| 37 | +1) Ambiente Docker (caminhos relativos) |
| 38 | + |
| 39 | +```toml |
| 40 | +[version] |
| 41 | +default = "llvmorg-21.1.0" |
| 42 | + |
| 43 | +[paths] |
| 44 | +llvm_home = "./docker-llvm" |
| 45 | +toolchains_dir = "./docker-llvm/toolchains" |
| 46 | +sources_dir = "./docker-llvm/sources" |
| 47 | +``` |
| 48 | + |
| 49 | +2) Instalação personalizada (caminhos absolutos) |
| 50 | + |
| 51 | +```toml |
| 52 | +[version] |
| 53 | +default = "llvmorg-21.1.0" |
| 54 | + |
| 55 | +[paths] |
| 56 | +llvm_home = "/opt/llvm" |
| 57 | +toolchains_dir = "/opt/llvm/toolchains" |
| 58 | +sources_dir = "/opt/llvm/sources" |
| 59 | +``` |
| 60 | + |
| 61 | +3) Instalação local do usuário (note a expansão de `~`) |
| 62 | + |
| 63 | +```toml |
| 64 | +[version] |
| 65 | +default = "llvmorg-21.1.0" |
| 66 | + |
| 67 | +[paths] |
| 68 | +llvm_home = "~/my-llvm" |
| 69 | +toolchains_dir = "~/my-llvm/toolchains" |
| 70 | +sources_dir = "~/my-llvm/sources" |
| 71 | +``` |
| 72 | + |
| 73 | +> Observação: o parser TOML pode retornar as chaves exatamente como escritas. O código que carrega a configuração converte e normaliza as chaves (ex.: `llvm_home`) antes de usar. Além disso, `~` não é automaticamente expandido pelo TOML; nossa implementação chama `Expand-Path` / `Resolve-Path` ao aplicar os diretórios. |
| 74 | +
|
| 75 | +## 🔧 Como funciona (resumo) |
| 76 | + |
| 77 | +1. Carregamento antecipado: as configurações de diretório são aplicadas antes da criação dos diretórios. |
| 78 | +2. Logs verbosos: quando executado com `-Verbose` ou `-VerboseMode`, o script informa quais caminhos personalizados estão sendo usados. |
| 79 | +3. Fallback inteligente: se apenas `llvm_home` for informado, os outros diretórios são derivados a partir dele. |
| 80 | + |
| 81 | +### Ordem de prioridade |
| 82 | + |
| 83 | +1. Configuração explícita: `toolchains_dir` e `sources_dir` definidos no `.llvmup-config` (ou variáveis de ambiente equivalentes, se aplicável). |
| 84 | +2. Configuração base: `llvm_home` + subdiretórios padrão. |
| 85 | +3. Padrão do sistema: `$HOME/.llvm` + subdiretórios. |
| 86 | + |
| 87 | +## 🧪 Exemplo de teste |
| 88 | + |
| 89 | +Crie um arquivo de configuração de teste e execute o instalador em modo verboso: |
| 90 | + |
| 91 | +```bash |
| 92 | +# Criar configuração de teste |
| 93 | +cat > .llvmup-config << 'EOF' |
| 94 | +[version] |
| 95 | +default = "llvmorg-21.1.0" |
| 96 | +
|
| 97 | +[paths] |
| 98 | +llvm_home = "./test-llvm" |
| 99 | +toolchains_dir = "./test-llvm/toolchains" |
| 100 | +sources_dir = "./test-llvm/sources" |
| 101 | +EOF |
| 102 | + |
| 103 | +# Testar com logs verbose (forma recomendada portátil) |
| 104 | +pwsh -NoProfile -Command '. ./Install-Llvm.ps1; # chame a função ou script conforme a API do projeto' |
| 105 | +``` |
| 106 | + |
| 107 | +Saída esperada (exemplo): |
| 108 | + |
| 109 | +``` |
| 110 | +[VERBOSE] Using custom LLVM_HOME: ./test-llvm |
| 111 | +[VERBOSE] Using custom TOOLCHAINS_DIR: ./test-llvm/toolchains |
| 112 | +[VERBOSE] Using custom SOURCES_DIR: ./test-llvm/sources |
| 113 | +``` |
| 114 | + |
| 115 | +## 🎉 Benefícios |
| 116 | + |
| 117 | +- Docker friendly: funciona em containers com volumes limitados. |
| 118 | +- Flexibilidade: permite qualquer estrutura de diretórios. |
| 119 | +- Backward compatible: configurações antigas continuam válidas. |
| 120 | +- Logs claros: modo verbose mostra exatamente os caminhos usados. |
| 121 | +- Fácil debug: diretórios customizados facilitam testes e desenvolvimento. |
| 122 | + |
| 123 | +## 🔍 Implementação técnica (exemplo portátil) |
| 124 | + |
| 125 | +O exemplo abaixo assume que o resultado do parser TOML é um hashtable com chaves em snake_case (ex.: `llvm_home`). Ajuste conforme a função `Read-LlvmConfig` do projeto. |
| 126 | + |
| 127 | +```powershell |
| 128 | +function Apply-DirectoryConfiguration { |
| 129 | + param([hashtable]$Config) |
| 130 | +
|
| 131 | + # Helper local para expandir ~ e caminhos relativos sem falhar |
| 132 | + function Expand-PathSafe($p) { |
| 133 | + if (-not $p) { return $null } |
| 134 | + try { return (Resolve-Path -LiteralPath (Expand-Path $p) -ErrorAction Stop).Path } catch { return (Expand-Path $p) } |
| 135 | + } |
| 136 | +
|
| 137 | + $llvmHomeRaw = $null |
| 138 | + if ($Config.ContainsKey('llvm_home')) { $llvmHomeRaw = $Config['llvm_home'] } |
| 139 | + elseif ($Config.ContainsKey('LlvmHome')) { $llvmHomeRaw = $Config['LlvmHome'] } |
| 140 | +
|
| 141 | + if ($llvmHomeRaw) { |
| 142 | + $script:LLVM_HOME = Expand-PathSafe $llvmHomeRaw |
| 143 | + Write-Verbose "Using custom LLVM_HOME: $script:LLVM_HOME" |
| 144 | + } else { |
| 145 | + $script:LLVM_HOME = Join-Path $HOME '.llvm' |
| 146 | + } |
| 147 | +
|
| 148 | + if ($Config.ContainsKey('toolchains_dir')) { |
| 149 | + $script:TOOLCHAINS_DIR = Expand-PathSafe $Config['toolchains_dir'] |
| 150 | + Write-Verbose "Using custom TOOLCHAINS_DIR: $script:TOOLCHAINS_DIR" |
| 151 | + } else { |
| 152 | + $script:TOOLCHAINS_DIR = Join-Path $script:LLVM_HOME 'toolchains' |
| 153 | + } |
| 154 | +
|
| 155 | + if ($Config.ContainsKey('sources_dir')) { |
| 156 | + $script:SOURCES_DIR = Expand-PathSafe $Config['sources_dir'] |
| 157 | + Write-Verbose "Using custom SOURCES_DIR: $script:SOURCES_DIR" |
| 158 | + } else { |
| 159 | + $script:SOURCES_DIR = Join-Path $script:LLVM_HOME 'sources' |
| 160 | + } |
| 161 | +
|
| 162 | + # Ensure directories exist |
| 163 | + foreach ($p in @($script:TOOLCHAINS_DIR, $script:SOURCES_DIR)) { |
| 164 | + if (-not (Test-Path -LiteralPath $p)) { |
| 165 | + New-Item -ItemType Directory -Path $p -Force | Out-Null |
| 166 | + } |
| 167 | + } |
| 168 | +} |
| 169 | +``` |
| 170 | + |
| 171 | +### Carregamento antecipado (exemplo) |
| 172 | + |
| 173 | +```powershell |
| 174 | +# Ler config e aplicar diretórios antes das operações que escrevem em disco |
| 175 | +$earlyConfig = Read-LlvmConfig |
| 176 | +if ($earlyConfig) { Apply-DirectoryConfiguration -Config $earlyConfig } |
| 177 | +``` |
| 178 | + |
| 179 | +## Resultado |
| 180 | + |
| 181 | +Agora o LLVM Manager pode ser usado em qualquer ambiente (incluindo Docker) apontando para diretórios customizados dentro do volume montado. Os testes e operações de instalação respeitam a configuração fornecida. |
| 182 | + |
| 183 | +--- |
| 184 | + |
| 185 | +Se quiser, eu aplico essas mudanças diretamente no arquivo e crio um commit com a mensagem: `docs: melhorar CUSTOM_DIRECTORIES.md — snippets e notas de portabilidade`. |
0 commit comments