|
| 1 | +# Guía de Build en Windows (Fork / Entorno Local) |
| 2 | + |
| 3 | +Esta guía documenta los pasos reproducibles para compilar y ejecutar el servidor en Windows usando Go + cgo con toolchain **llvm-mingw** (recomendado) y el script de conveniencia `Z_Iosu/scripts/dev-run.ps1`. |
| 4 | + |
| 5 | +## 1. Requisitos Previos |
| 6 | + |
| 7 | +1. **Go** >= 1.21 (detectado: probado con 1.24.x) |
| 8 | +2. **llvm-mingw** (recomendado) o toolchain MinGW que provea `clang`/`gcc` compatibles: |
| 9 | + - Descargar release: https://github.com/mstorsjo/llvm-mingw/releases |
| 10 | + - Extraer, por ejemplo en: `C:\llvm-mingw` |
| 11 | + - Añadir al PATH (inicio de sesión o sesión actual): |
| 12 | + ```powershell |
| 13 | + $env:PATH = 'C:\llvm-mingw\bin;' + $env:PATH |
| 14 | + ``` |
| 15 | +3. (Opcional) Visual Studio Build Tools – solo si se quiere probar `clang-cl` / `cl.exe` (NO recomendado para cgo aquí). |
| 16 | +4. PowerShell 5.1 o superior. |
| 17 | +
|
| 18 | +## 2. Verificación Inicial |
| 19 | +
|
| 20 | +```powershell |
| 21 | +where go |
| 22 | +where clang |
| 23 | +where x86_64-w64-mingw32-clang |
| 24 | +``` |
| 25 | +Debes ver rutas dentro de `C:\llvm-mingw\bin`. Si solo aparece `clang.exe` sin el prefijo triple, el script igualmente lo detecta. |
| 26 | + |
| 27 | +## 3. Script de Conveniencia |
| 28 | +El archivo: `Z_Iosu/scripts/dev-run.ps1` |
| 29 | + |
| 30 | +Parámetros principales: |
| 31 | +- `-ForceClangGnu` Fuerza clang (llvm-mingw) y si no existe intenta clang genérico o gcc (fallback). Ignora `cl.exe`. |
| 32 | +- `-ResetGoEnv` Elimina CC/CXX persistidos en `go env` (evita arrastre de toolchain viejo). |
| 33 | +- `-Clean` Limpia caché de compilación (`go clean -cache`) y borra `build/`. |
| 34 | +- `-ShowEnv` Imprime CC, CXX, flags cgo y host. |
| 35 | +- `-GoRelease` Compila binario optimizado (`-trimpath -ldflags '-s -w'`) y lo ejecuta. |
| 36 | +- `-UseCMake` / `-Release` Flujo CMake opcional (debug/release) si se necesita integración nativa. |
| 37 | +- `-PreferClangCL` Prioriza `clang-cl` si está, para pruebas (no recomendado con cgo puro). |
| 38 | +- `-DryRun` No ejecuta acciones, solo muestra. |
| 39 | + |
| 40 | +Orden de fallback con `-ForceClangGnu`: |
| 41 | +1. `x86_64-w64-mingw32-clang.exe` |
| 42 | +2. `clang.exe` |
| 43 | +3. `x86_64-w64-mingw32-gcc.exe` / `gcc` |
| 44 | +Si ninguno aparece: aborta indicando instalar llvm-mingw. |
| 45 | + |
| 46 | +## 4. Primer Arranque (Modo Desarrollo) |
| 47 | +```powershell |
| 48 | +powershell -ExecutionPolicy Bypass -File Z_Iosu\scripts\dev-run.ps1 -ForceClangGnu -ResetGoEnv -Clean -ShowEnv |
| 49 | +``` |
| 50 | +IosuUltimo |
| 51 | +powershell -ExecutionPolicy Bypass -File Z_Iosu\scripts\dev-run.ps1 -ForceClangGnu -ResetGoEnv -GoRelease -Clean -ShowEnv |
| 52 | + |
| 53 | +Esto: |
| 54 | +1. Limpia CC/CXX persistentes. |
| 55 | +2. Detecta `x86_64-w64-mingw32-clang.exe` (si existe) y lo asigna a `CC` y su par `clang++.exe` a `CXX`. |
| 56 | +3. Traduce flags MSVC si apareciesen (/std:c++17, /EHsc) a formato GCC. |
| 57 | +4. Inyecta: `--target=x86_64-w64-windows-gnu -fuse-ld=lld` y asegura `-std=c++17`. |
| 58 | +5. Ejecuta `go run . serve`. |
| 59 | +=================================================================================== |
| 60 | +=================================================================================== |
| 61 | +=================================================================================== |
| 62 | +Iosu FINAL |
| 63 | +powershell -ExecutionPolicy Bypass -File Z_Iosu\scripts\build-installer.ps1 -Version 0.11.102 -ForceClangGnu -InnoPath "C:\Program Files (x86)\Inno Setup 6\ISCC.exe" -AlsoPortable -Verbose |
| 64 | +=================================================================================== |
| 65 | +=================================================================================== |
| 66 | +=================================================================================== |
| 67 | + |
| 68 | + |
| 69 | +## 5. Build Optimizado (GoRelease) |
| 70 | +```powershell |
| 71 | +powershell -ExecutionPolicy Bypass -File Z_Iosu\scripts\dev-run.ps1 -ForceClangGnu -ResetGoEnv -GoRelease -Clean -ShowEnv |
| 72 | +``` |
| 73 | +Genera `ollama-dev.exe` y lo lanza con `serve`. |
| 74 | + |
| 75 | +## 6. Variables CGO Añadidas Automáticamente |
| 76 | +Cuando se usa `-ForceClangGnu` el script ajusta (pre-pend): |
| 77 | +- `CGO_CFLAGS`: `--target=x86_64-w64-windows-gnu -fuse-ld=lld -O3 -DNDEBUG ...` |
| 78 | +- `CGO_CXXFLAGS`: idem + `-std=c++17` (si faltaba) |
| 79 | +- `CGO_LDFLAGS`: `--target=x86_64-w64-windows-gnu -fuse-ld=lld ...` |
| 80 | + |
| 81 | +Esto evita el error de formato `_cgo_.o` y el rechazo de flags MSVC. |
| 82 | + |
| 83 | +## 7. Problemas Frecuentes |
| 84 | +| Síntoma | Causa | Solución | |
| 85 | +|---------|-------|----------| |
| 86 | +| `cl : Command line error D8021` | Se usó `cl.exe` con flags GCC (`-Werror`) | Añadir `-ForceClangGnu` y asegurar llvm-mingw primero en PATH | |
| 87 | +| `cgo: cannot parse _cgo_.o` | Mezcla de toolchain 32/64 o falta `--target` | Confirmar uso de `x86_64-w64-mingw32-clang.exe`; usar script actualizado | |
| 88 | +| No se encuentra `clang.exe` | PATH sin llvm-mingw | Añadir `C:\llvm-mingw\bin` al PATH | |
| 89 | +| Flags `/std:c++17` inválidos | Se ejecutó clang GNU con flags MSVC | Script ya traduce; re-ejecutar con `-ResetGoEnv` | |
| 90 | +| Código salida 1 tras servir | Cierre manual/context canceled | Ver logs y decidir si ignorar exit code (future improvement) | |
| 91 | + |
| 92 | +## 8. Limpieza Manual |
| 93 | +Para limpiar completamente (incluyendo módulos Go): |
| 94 | +```powershell |
| 95 | +go clean -cache -modcache |
| 96 | +Remove-Item -Recurse -Force build -ErrorAction SilentlyContinue |
| 97 | +``` |
| 98 | + |
| 99 | +## 9. Ejecución sin Script (Referencia) |
| 100 | +Si necesitas reproducir manualmente: |
| 101 | +```powershell |
| 102 | +$env:PATH = 'C:\llvm-mingw\bin;' + $env:PATH |
| 103 | +$env:CC='C:\llvm-mingw\bin\x86_64-w64-mingw32-clang.exe' |
| 104 | +$env:CXX='C:\llvm-mingw\bin\x86_64-w64-mingw32-clang++.exe' |
| 105 | +$env:CGO_ENABLED=1 |
| 106 | +$env:CGO_CFLAGS='--target=x86_64-w64-windows-gnu -fuse-ld=lld -O3 -DNDEBUG' |
| 107 | +$env:CGO_CXXFLAGS='--target=x86_64-w64-windows-gnu -fuse-ld=lld -O3 -DNDEBUG -std=c++17' |
| 108 | +$env:CGO_LDFLAGS='--target=x86_64-w64-windows-gnu -fuse-ld=lld' |
| 109 | +$env:OLLAMA_HOST='127.0.0.1:11434' |
| 110 | +# Desarrollo |
| 111 | +go run . serve |
| 112 | +# Release |
| 113 | +go build -trimpath -ldflags '-s -w' -o ollama-dev.exe . |
| 114 | +./ollama-dev.exe serve |
| 115 | +``` |
| 116 | + |
| 117 | +## 10. Próximas Mejoras (Opcionales) |
| 118 | +- Parámetro `-IgnoreExitCode` para no propagar código distinto de 0 al cerrar. |
| 119 | +- `-LogFile` para redirigir stdout/stderr. |
| 120 | +- `-Model <name>` para precarga controlada. |
| 121 | + |
| 122 | +## 11. Checklist Rápido |
| 123 | +``` |
| 124 | +[ ] Go instalado |
| 125 | +[ ] llvm-mingw en PATH (x86_64-w64-mingw32-clang.exe responde) |
| 126 | +[ ] go env CC/CXX no persistentes (usar -ResetGoEnv si dudas) |
| 127 | +[ ] Script ejecutado con -ForceClangGnu |
| 128 | +[ ] Puerto accesible: http://127.0.0.1:11434/api/ps |
| 129 | +``` |
| 130 | + |
| 131 | +## 12. Generar Instalador Windows |
| 132 | +Script: `Z_Iosu/scripts/build-installer.ps1` |
| 133 | + |
| 134 | +Ejemplos: |
| 135 | +```powershell |
| 136 | +# Versión automática (fecha+commit), compilando con clang gnu |
| 137 | +powershell -ExecutionPolicy Bypass -File Z_Iosu\scripts\build-installer.ps1 -ForceClangGnu -AutoVersion |
| 138 | +powershell -ExecutionPolicy Bypass -File Z_Iosu\scripts\build-installer.ps1 -AutoVersion -ForceClangGnu -Verbose |
| 139 | +
|
| 140 | +# Versión fija y reutilizando binarios existentes |
| 141 | +powershell -ExecutionPolicy Bypass -File Z_Iosu\scripts\build-installer.ps1 -Version 0.11.101 -ForceClangGnu -Verbose |
| 142 | +powershell -ExecutionPolicy Bypass -File Z_Iosu\scripts\build-installer.ps1 -Version 0.1.0 -SkipBuild |
| 143 | +
|
| 144 | +# Generar instalador y también ZIP portable |
| 145 | +powershell -ExecutionPolicy Bypass -File Z_Iosu\scripts\build-installer.ps1 -Version 0.11.101 -ForceClangGnu -AlsoPortable -Verbose |
| 146 | +
|
| 147 | +# Con salida verbosa |
| 148 | +powershell -ExecutionPolicy Bypass -File Z_Iosu\scripts\build-installer.ps1 -ForceClangGnu -AutoVersion -Verbose |
| 149 | +``` |
| 150 | +Salida: |
| 151 | +- Instalador base (cuando se usa Inno): `dist/OllamaSetup.exe` (o `%LOCALAPPDATA%\dist\OllamaSetup.exe` si el OutputDir relativo cae allí). |
| 152 | +- Copia versionada: `Z_Iosu/release/installer/OllamaSetup-<VERSION>.exe` |
| 153 | +- Paquete portable (sin Inno con `-Portable` o adicional con `-AlsoPortable`): `Z_Iosu/release/installer/Ollama-portable-<VERSION>.zip` |
| 154 | + |
| 155 | +Parámetros clave: |
| 156 | +- `-AutoVersion` Usa `YYYY.MM.DD+<shortCommit>`. |
| 157 | +- `-Version 1.2.3` Fija versión manual. |
| 158 | +- `-ForceClangGnu` Recompila usando clang gnu / fallback (dev-run). |
| 159 | +- `-SkipBuild` Empaqueta sin recompilar (usa binario existente). |
| 160 | +- `-InnoPath C:\ruta\ISCC.exe` Ruta directa a `ISCC.exe`. |
| 161 | +- `-SkipWrapper` No (re)crea `windows-amd64-app.exe`. |
| 162 | +- `-Portable` Genera zip portable en lugar de instalador. |
| 163 | +- `-AlsoPortable` Fuerza generar zip además del instalador. |
| 164 | +- `-NoAlsoPortable` No generar zip adicional (por defecto ahora se crea si hay instalador). |
| 165 | +- `-Verbose` Log extendido (muestra versión limpia, rutas, etc.). |
| 166 | + |
| 167 | +Requisitos para el instalador: |
| 168 | +1. Inno Setup 6 (ISCC.exe en PATH o usar `-InnoPath`). |
| 169 | +2. Binario `ollama-dev.exe` o `ollama.exe` listo (si `-SkipBuild`). |
| 170 | +3. `app/ollama.iss` presente (el script crea copia temporal para ajustar `VersionInfoVersion`). |
| 171 | + |
| 172 | +Requisitos para `-Portable`: |
| 173 | +1. Binario `ollama.exe` disponible (se toma `ollama-dev.exe` si existe y se renombra). |
| 174 | +2. Wrapper generado (`windows-amd64-app.exe`) salvo `-SkipWrapper`. |
| 175 | +3. LICENSE y README si se quieren empaquetar (se incluyen si existen). |
| 176 | + |
| 177 | +Troubleshooting: |
| 178 | +- "No se localizó ISCC.exe": Instala Inno Setup (o `choco install innosetup`) o pasa `-InnoPath`. |
| 179 | +- "No se encontró binario de servidor": Ejecuta build previo con `dev-run.ps1 -ForceClangGnu -GoRelease`. |
| 180 | +- Instalador sin versión correcta: Revisa `-Version` / `-AutoVersion` y que no haya quedado un valor previo en entorno. |
| 181 | +- No aparece `OllamaSetup.exe` en `dist/`: El script busca también en `%LOCALAPPDATA%\dist`; si no está, revisar logs de ISCC. |
| 182 | +- ZIP incompleto: Asegura que `dist/windows-amd64/ollama.exe` exista antes de usar `-Portable` (no omitir build si falta). |
| 183 | + |
| 184 | +--- |
| 185 | +Si algo falla, ejecuta con `-ShowEnv -DryRun` y comparte la salida para diagnóstico. |
0 commit comments