Skip to content

GUIA_COMPILACION_EXE.md

Latest commit

 

History

History
421 lines (298 loc) · 11.3 KB

GUIA_COMPILACION_EXE.md

File metadata and controls

421 lines (298 loc) · 11.3 KB
Raw

🔨 Guía de Compilación - Ejecutable Portable

📋 Tabla de Contenidos

  1. Introducción
  2. Requisitos para Compilar
  3. Proceso de Compilación
  4. Contenido del Ejecutable
  5. Distribución
  6. Solución de Problemas

🎯 Introducción

Este documento explica cómo compilar ChequeoDigital Admin en un ejecutable portable (.exe) que:

  • ✅ No requiere instalación de Python
  • ✅ No requiere dependencias externas de Python
  • ✅ Se auto-configura en la primera ejecución
  • ✅ Incluye todos los scripts PowerShell necesarios
  • ✅ Es completamente standalone

El ejecutable funciona como un instalador/programa en uno:

  1. Primera ejecución → Instala archivos en C:\chequeo
  2. Ejecuciones posteriores → Lanza directamente la GUI

🔧 Requisitos para Compilar

En la Máquina de Compilación

Software Requerido

  1. Python 3.8 o superior

    python --version
# Debe mostrar: Python 3.8.x o superior

  2. PyInstaller

    pip install pyinstaller
# O se instalará automáticamente al ejecutar Compilar_Ejecutable.bat

  3. Módulos de Python

    • tkinter (incluido con Python en Windows)
    • Todos los demás módulos son estándar

Archivos del Proyecto

Asegúrate de tener la siguiente estructura en C:\chequeo:

C:\chequeo\
├── gui\
│   ├── chequeo_admin.py          (GUI principal)
│   └── chequeo_admin_launcher.py (Launcher portable)
├── scripts\
│   ├── export_to_bigquery.ps1
│   ├── compare_data_sync_simple.ps1
│   ├── sync_delta_tracking_to_bigquery_fixed.ps1
│   ├── tests\
│   │   └── test_export.ps1
│   └── ... (todos los demás scripts)
├── config\
│   └── delta_tracking_schema.json
├── build_portable.py             (Script de compilación)
└── Compilar_Ejecutable.bat       (Launcher de compilación)

🚀 Proceso de Compilación

Método 1: Usando el Batch (Recomendado)

  1. Abre PowerShell o CMD como Administrador

    • Clic derecho en el menú inicio → Windows PowerShell (Admin)

  2. Navega al directorio del proyecto

    cd C:\chequeo

  3. Ejecuta el compilador

    .\Compilar_Ejecutable.bat

  4. Espera a que termine

    • El proceso tarda 2-5 minutos
    • Verás el progreso en pantalla

  5. ¡Listo!

    • El ejecutable estará en C:\chequeo\dist\ChequeoDigitalAdmin.exe

Método 2: Usando Python Directamente

cd C:\chequeo
python build_portable.py

📦 Contenido del Ejecutable

¿Qué se Empaqueta?

El ejecutable ChequeoDigitalAdmin.exe contiene:

  1. Python Runtime

    • Intérprete de Python embebido
    • Todas las librerías necesarias

  2. GUI Principal

    • chequeo_admin.py (interfaz gráfica completa)
    • chequeo_admin_launcher.py (sistema de auto-instalación)

  3. Scripts PowerShell

    • Todos los scripts en scripts/ y subdirectorios
    • test_export.ps1, export_to_bigquery.ps1, etc.

  4. Archivos de Configuración

    • delta_tracking_schema.json
    • Plantillas de configuración

¿Qué NO se Empaqueta?

❌ PowerShell - Debe estar instalado en el sistema destino (viene con Windows) ❌ SQL Server Module - Debe instalarse en el sistema destino ❌ Google Cloud SDK - Debe instalarse en el sistema destino ❌ Service Account JSON - El usuario debe proporcionarlo

Tamaño del Ejecutable

  • Tamaño aproximado: 25-35 MB
  • Compresión: PyInstaller usa UPX para comprimir
  • Descompresión: Automática al ejecutar (no permanente)

📤 Distribución

Archivos para Distribuir

Después de la compilación, en C:\chequeo\dist\ encontrarás:

dist\
├── ChequeoDigitalAdmin.exe       (Ejecutable principal - 25-35 MB)
├── Instalar.bat                  (Instalador opcional)
└── README_PORTABLE.txt           (Instrucciones)

Opción 1: Distribución Simple

Archivo único: ChequeoDigitalAdmin.exe

Instrucciones para el usuario:

  1. Copia ChequeoDigitalAdmin.exe a cualquier ubicación
  2. Ejecuta como Administrador (clic derecho → Ejecutar como administrador)
  3. Sigue las instrucciones en pantalla
  4. El programa se instalará automáticamente en C:\chequeo

Opción 2: Distribución con Instalador

Archivos: Todo el contenido de dist\

Instrucciones para el usuario:

  1. Copia todos los archivos a una ubicación temporal
  2. Ejecuta Instalar.bat como Administrador
  3. El instalador:
    • Creará C:\chequeo
    • Copiará el ejecutable
    • Creará acceso directo en el escritorio
  4. Ejecuta desde el acceso directo o desde C:\chequeo\ChequeoDigitalAdmin.exe

Opción 3: Distribución en Red

Para instalaciones múltiples:

  1. Copia ChequeoDigitalAdmin.exe a una carpeta compartida de red
  2. Cada usuario ejecuta desde la red o copia local
  3. Primera ejecución en cada máquina instalará en C:\chequeo

🔍 Proceso de Primera Ejecución

En la Máquina del Usuario

  1. Usuario ejecuta ChequeoDigitalAdmin.exe

  2. El programa detecta que es primera ejecución

  3. Muestra diálogo de bienvenida:

    ╔════════════════════════════════════════════════╗
║  ChequeoDigital Admin - Primera Ejecución     ║
╚════════════════════════════════════════════════╝

Esta es la primera vez que ejecutas ChequeoDigital Admin.

El programa se instalará en: C:\chequeo

¿Deseas continuar con la instalación?

  4. Usuario hace clic en "OK"

  5. El programa verifica requisitos:

    • PowerShell 5.1+
    • Módulo SqlServer (opcional, pero advertencia si no está)
    • Google Cloud SDK (opcional, pero advertencia si no está)

  6. El programa extrae archivos:

    • Crea estructura de directorios en C:\chequeo
    • Extrae scripts PowerShell
    • Extrae archivos de configuración
    • Copia GUI principal

  7. Muestra diálogo de completado:

    ╔════════════════════════════════════════════════╗
║  Instalación Completada                       ║
╚════════════════════════════════════════════════╝

✅ ChequeoDigital Admin se instaló correctamente en:
   C:\chequeo

📋 Próximos pasos:
1. Configura SQL Server
2. Configura BigQuery
3. Prueba las conexiones
4. ¡Comienza a sincronizar!

La aplicación se abrirá automáticamente.

  8. La GUI se abre automáticamente

Ejecuciones Posteriores

  1. Usuario ejecuta ChequeoDigitalAdmin.exe
  2. El programa detecta instalación existente
  3. Actualiza scripts si es necesario
  4. Lanza GUI directamente (sin diálogos)

🔧 Solución de Problemas

Problemas de Compilación

Error: "Python no está instalado"

Solución:

# Descargar e instalar Python desde python.org
# Asegurarse de marcar "Add Python to PATH" durante la instalación

Error: "PyInstaller no encontrado"

Solución:

pip install pyinstaller

Error: "No se encontró chequeo_admin.py"

Solución:

  • Verifica que estés en C:\chequeo
  • Verifica que exista gui\chequeo_admin.py
  • Verifica que exista gui\chequeo_admin_launcher.py

Error: "UPX no encontrado" (Warning)

Es seguro ignorarlo, pero si quieres instalarlo:

# Descargar UPX desde https://upx.github.io/
# Extraer a C:\Windows\System32\ o agregar al PATH

Problemas de Ejecución

Error: "Se requieren permisos de administrador"

Solución:

  • Clic derecho en ChequeoDigitalAdmin.exe
  • Selecciona "Ejecutar como administrador"

Error: "No se pudo crear C:\chequeo"

Solución:

  • Ejecuta como Administrador
  • Verifica permisos en el disco C:
  • Si persiste, cambia INSTALL_DIR en chequeo_admin_launcher.py antes de compilar

Error: "PowerShell no encontrado"

Solución:

  • PowerShell viene con Windows
  • Verifica que powershell.exe esté en el PATH
  • Ejecuta: where powershell

Advertencia: "Módulo SqlServer no encontrado"

Solución:

# Como Administrador
Install-Module SqlServer -Force -AllowClobber

Advertencia: "Google Cloud SDK no encontrado"

Solución:

# Descargar e instalar Google Cloud SDK
# https://cloud.google.com/sdk/docs/install

📊 Optimización

Reducir Tamaño del Ejecutable

Si necesitas un ejecutable más pequeño:

  1. Edita build_portable.py:

    # Cambia en el archivo .spec:
upx=True,              # Comprimir con UPX
upx_exclude=[],        # No excluir nada de la compresión

  2. Excluye módulos no usados:

    excludes=[
    'matplotlib',
    'numpy',
    'pandas',
    # Agrega otros que sepas que no usas
],

Acelerar Primera Ejecución

El tiempo de primera ejecución depende de:

  • Número de scripts PowerShell (más scripts = más tiempo)
  • Velocidad del disco

Típicamente: 10-30 segundos para la primera ejecución completa

📝 Notas Importantes

Dependencias Externas

El ejecutable NO incluye:

  • PowerShell (debe estar en el sistema)
  • SQL Server (el servidor debe estar accesible)
  • Google Cloud SDK (debe estar instalado)
  • Service Account JSON (el usuario debe proporcionarlo)

Requisitos en la Máquina Destino

Para que el ejecutable funcione, la máquina destino necesita:

  1. Windows Server 2012 o superior
  2. PowerShell 5.1+ (incluido con Windows)
  3. Módulo SqlServer (para conectar a SQL Server)
  4. Google Cloud SDK (para sincronizar con BigQuery)
  5. Acceso a red (para SQL Server y internet para BigQuery)
  6. Permisos de administrador (para crear tareas programadas)

Actualizaciones

Para actualizar el ejecutable:

  1. Modifica los archivos fuente en C:\chequeo
  2. Ejecuta Compilar_Ejecutable.bat nuevamente
  3. Distribuye el nuevo ChequeoDigitalAdmin.exe
  4. Los usuarios simplemente reemplazan el .exe antiguo
  5. Los archivos en C:\chequeo se actualizarán automáticamente

✅ Checklist de Compilación

Antes de distribuir, verifica:

  • El ejecutable se compila sin errores
  • El ejecutable se ejecuta en tu máquina
  • La primera ejecución funciona correctamente
  • Los scripts PowerShell se extraen correctamente
  • La GUI se abre y funciona
  • Las conexiones SQL y BigQuery se pueden configurar
  • Las exportaciones funcionan
  • Las tareas programadas se pueden crear
  • El archivo README_PORTABLE.txt está incluido
  • Tienes documentación para los usuarios

🎉 ¡Listo para Distribuir!

Una vez compilado y probado, tu ejecutable está listo para distribuirse a cualquier Windows Server 2012+.

¿Preguntas o problemas? Consulta los logs en C:\chequeo\logs\ o revisa la documentación completa en MANUAL_USUARIO_GUI.md.

Versión: 1.0
Fecha: Abril 2025