3 - Estructura básica de un proyecto Gradle

Objetivo del tema

Analizarás los archivos y carpetas que Gradle utiliza para definir builds reproducibles, comprenderás cómo se organizan las fuentes y descubrirás las diferencias entre proyectos de aplicación y librería.

3.1 Archivos principales: build.gradle y settings.gradle

Todo proyecto Gradle se describe mediante scripts que pueden escribirse en Groovy DSL o Kotlin DSL. Los dos archivos esenciales son:

  • build.gradle: Contiene la configuración del módulo actual, es decir, plugins, dependencias y tareas personalizadas. La documentación oficial de Gradle resume las fases que ejecuta este script.
  • settings.gradle: Define el nombre del proyecto raíz e incluye módulos adicionales cuando se trata de un build multiproyecto. Su lectura es el primer paso del proceso de inicialización.

En builds sencillos ambos archivos residen en la carpeta raíz. Si utilizas Kotlin DSL, los nombres cambian a build.gradle.kts y settings.gradle.kts, pero cumplen la misma función.

3.2 Directorios convencionales de código y recursos

Gradle adopta la filosofía Convention over Configuration, por lo que espera encontrar código y recursos en ubicaciones predeterminadas. Para un proyecto Java o Kotlin el layout por defecto luce así:

mi-proyecto/
|-- build.gradle
|-- settings.gradle
`-- src
    |-- main
    |   |-- java
    |   |-- kotlin
    |   |-- resources
    |   `-- groovy
    `-- test
        |-- java
        |-- kotlin
        |-- resources
        `-- groovy
  • src/main/java o src/main/kotlin albergan el código fuente productivo. Si trabajas con Groovy, utiliza src/main/groovy.
  • src/main/resources almacena archivos de configuración, plantillas o recursos estáticos empaquetados junto a la aplicación.
  • src/test/<lenguaje> contiene las pruebas automatizadas, mientras que src/test/resources guarda datos de apoyo como archivos de prueba o datasets.

Puedes personalizar estas rutas mediante el bloque sourceSets, pero respetar las convenciones facilita el onboarding y reduce configuraciones adicionales.

3.3 Aplicación vs. librería: diferencias clave

Aunque comparten estructura, los proyectos de aplicación agregan configuraciones específicas para generar ejecutables, mientras que las librerías se enfocan en producir artefactos reutilizables.

Característica Proyecto de aplicación Proyecto de librería
Plugin principal application (define mainClass y tareas como run). java-library (expone API pública y separa dependencias api/implementation).
Artefacto generado JAR ejecutable o distribución empaquetada con scripts de arranque. JAR sin punto de entrada, pensado para ser consumido por otros proyectos.
Tareas habituales gradle run, gradle distZip, gradle installDist. gradle publishToMavenLocal, gradle publish, verificación de dependencias transitivas.
Configuración extra Bloque application con la clase principal y propiedades de arranque. Declaración de visibilidad (api vs implementation) para controlar el contrato expuesto.

Cuando un proyecto crece, es frecuente combinar ambos enfoques mediante un build multiproyecto: un módulo principal tipo aplicación y varios submódulos de librería compartidos.

Resumen didáctico

La estructura estándar de Gradle descansa en los scripts build.gradle y settings.gradle junto a directorios convencionales para código y pruebas. Comprender estas piezas permite adaptar builds a distintas necesidades, ya sea desplegar una aplicación ejecutable o distribuir librerías reutilizables.

Retornar