Lección 7. Publicación de un complemento: de la carpeta a GitHub y al Administrador de Complementos

📘 Curso: Creación de complementos para FreeCAD

Objetivo de la lección: preparar el complemento para su distribución, crear metadatos y publicarlo en GitHub, para que cualquier usuario de FreeCAD pueda instalarlo con un solo clic.

---

📦 Parte 1. ¿Qué es el Administrador de Complementos?

El Administrador de Complementos es una herramienta integrada en FreeCAD (Herramientas → Administrador de Complementos) que:

• Muestra un catálogo de más de 300 complementos oficiales
• Permite instalar, actualizar y eliminar complementos sin copiar archivos manualmente
• Funciona con repositorios en GitHub

Para que tu complemento aparezca allí, necesitas:

1. Subirlo a GitHub
2. Añadir el archivo package.xml
3. (Opcional) Enviar un PR a FreeCAD-addons

---

🗂 Parte 2. Preparación de la estructura del repositorio

Tu carpeta debe verse así:

BoxBuilderAddon/                ← raíz del repositorio
├── Resources/
│   └── icons/
│       ├── box_builder.svg
│       └── create_box.svg
├── InitGui.py
├── box_builder_workbench.py
├── package.xml                 ← ¡OBLIGATORIO!
├── README.md                   ← recomendado
└── LICENSE                     ← obligatorio para la publicación

💡 Importante: el nombre de la carpeta raíz debe coincidir con el nombre del complemento y ser el mismo que en InitGui.py.

---

📄 Parte 3. Creación de package.xml

Este archivo describe tu complemento para el Administrador de Complementos.

Crea el archivo package.xml en la raíz:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<package format="1" xmlns="https://wiki.freecad.org/Package_Metadata">
  <name>BoxBuilderAddon</name>
  <description>
    A simple tool to create parametric boxes with custom dimensions and GUI.
    Saves last used values between sessions.
  </description>
  <version>1.0.0</version>
  <date>2025-04-05</date>
  <maintainer email="your.email@example.com">Your Name</maintainer>
  <license file="LICENSE">LGPL-2.1-or-later</license>
  <url type="repository" branch="main">https://github.com/yourname/BoxBuilderAddon</url>
  <url type="bugtracker">https://github.com/yourname/BoxBuilderAddon/issues</url>
  <icon>Resources/icons/box_builder.svg</icon>
  <content>
    <workbench>BoxBuilderAddon</workbench>
  </content>
  <dependencies>
    <freecad>0.20</freecad>
  </dependencies>
</package>

🔍 Campos obligatorios:

• <name> — debe coincidir con la carpeta
• <version> — en formato X.Y.Z
• <license> — especifica el archivo LICENSE y el tipo de licencia
• <url type="repository"> — enlace a tu GitHub
• <icon> — ruta al icono (relativa a la raíz)
• <content><workbench>...</workbench></content> — indica que es un entorno de trabajo

💡 La licencia es obligatoria. Se recomienda LGPL-2.1-or-later (como la del propio FreeCAD).

---

📄 Parte 4. Archivo LICENSE

Crea el archivo LICENSE con el texto de la licencia.

Ejemplo para LGPL-2.1:

1. Ve a: https://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt
2. Copia todo el texto
3. Pégalo en el archivo LICENSE

O usa GitHub: al crear un repositorio, puedes elegir la licencia automáticamente.

---

📝 Parte 5. Archivo README.md

Crea un README.md simple:

# Complemento Box Builder para FreeCAD

Una herramienta simple para crear cajas paramétricas con dimensiones personalizadas.

## Características
- Diálogo GUI para introducir longitud, anchura, altura
- Guarda los últimos valores utilizados entre sesiones
- Nomenclatura de objetos única
- Centrado opcional en el origen

## Instalación
1. Abre FreeCAD
2. Ve a **Herramientas → Administrador de Complementos**
3. Busca "BoxBuilderAddon"
4. Haz clic en **Instalar**

O instala manualmente copiando la carpeta en tu directorio `Mod`.

## Requisitos
- FreeCAD 0.20 o más reciente

---

🌐 Parte 6. Publicación en GitHub

Pasos:

1. Regístrate en GitHub
2. Haz clic en New repository
3. Nombre: BoxBuilderAddon
4. Inicializa sin README (ya lo has creado)
5. Haz clic en Create repository
6. Sigue las instrucciones para subir la carpeta local:

git init
git add .
git commit -m "Initial release"
git branch -M main
git remote add origin https://github.com/yourname/BoxBuilderAddon.git
git push -u origin main

💡 Reemplaza yourname con tu nombre de usuario de GitHub.

---

🔍 Parte 7. Prueba de instalación

Ahora cualquier usuario puede:

1. Abrir FreeCAD
2. Ir a Herramientas → Administrador de Complementos
3. Hacer clic en Buscar actualizaciones
4. Encontrar BoxBuilderAddon y hacer clic en Instalar

⚠️ Para que el complemento aparezca en la lista oficial, debes enviar una Pull Request a:
🔗 https://github.com/FreeCAD/FreeCAD-addons

Pero incluso sin esto, los usuarios pueden instalarlo mediante un enlace directo:

• En el Administrador de Complementos: Herramientas → Administrador de Complementos → … → Instalar complemento personalizado
• Pegar la URL: https://github.com/yourname/BoxBuilderAddon

---

🧪 Tarea práctica

1. Crea una cuenta en GitHub (si no tienes una)
2. Prepara la estructura completa del complemento con package.xml, LICENSE, README.md
3. Sube el repositorio a GitHub
4. Instala tu complemento a través del Administrador de Complementos en una copia limpia de FreeCAD (o elimina la carpeta de Mod antes de la instalación)

---

✅ Resumen

Ahora sabes:

• Crear complementos completos con GUI y configuraciones
• Añadir iconos
• Preparar metadatos
• Publicar en GitHub
• Hacer que el complemento esté disponible para todo el mundo

---

🎓 ¿Qué sigue?

¡Has completado todo el curso! 🎉
Ahora eres un desarrollador de complementos de FreeCAD.

Posibles próximos pasos:

• Añade soporte para centrado (de la tarea de la Lección 5)
• Implementa entrada múltiple (creación de una cuadrícula de cajas)
• Integra con PartDesign para crear cuerpos de revolución
• Escribe un complemento para tu propia tarea: tornillos, marcos, cálculos, etc.

---

💬 Conclusión

FreeCAD no es solo un programa CAD.
Es una plataforma para la creatividad ingenieril, y ahora tienes la clave para expandirla.

Escribe complementos. Compártelos. Cambia el mundo, un objeto paramétrico a la vez. 🛠️

---

Si tienes una idea para un complemento real, descríbela y te ayudaré a implementarla.