2. Configuración del entorno de desarrollo
El entorno de trabajo del desarrollador Kotlin consta de tres componentes independientes:
- el JDK (“Java Development Kit”): Kotlin, tal como lo usamos en este documento, se compila a bytecode y lo ejecuta la máquina virtual de Java (JVM), igual que un programa Java. El JDK proporciona esta máquina virtual, el comando [java] que ejecuta los programas, las bibliotecas estándar de Java SE (que Kotlin utiliza directamente: archivos, redes, fechas, hilos, etc.) y herramientas como [javap] o [jar];
- una herramienta de construcción de proyectos, en este caso Gradle: descarga el compilador de Kotlin y las bibliotecas que necesita un proyecto, compila el proyecto, ejecuta sus pruebas y lo empaqueta;
- un editor o un IDE (entorno de desarrollo integrado): [IntelliJ IDEA], diseñado por la empresa que creó Kotlin, es la opción natural; [VS Code] con la extensión de Kotlin es otra opción. El IDE se apoya en el JDK y puede leer proyectos Gradle.
El compilador de Kotlin en sí no figura en esta lista: Gradle lo descarga para cada proyecto e IntelliJ IDEA lo incluye. Sin embargo, puede instalarlo por separado con el comando [kotlinc] para compilar un solo archivo: lo haremos con nuestro primer programa, pero es opcional.
Este documento usa los comandos [java], [kotlinc] y [gradlew] para todas las operaciones: funcionan de la misma manera en Windows, Linux y macOS, sea cual sea el editor que elija.
2.1. JDK 25
2.1.1. Instalación
Existen varias distribuciones del JDK, todas construidas a partir del código fuente de OpenJDK y equivalentes para nuestros fines. Recomendamos Eclipse Temurin, una distribución gratuita y de código abierto de la Eclipse Foundation, que puede descargarse en https://adoptium.net: allí, seleccione la versión 25—LTS—, el sistema operativo y el tipo de paquete (en Windows, un instalador [.msi]). En Windows, también puede instalarlo desde una terminal (PowerShell o símbolo del sistema) con el administrador de paquetes [winget]:
Debe seleccionar el JDK (que contiene todo) y no solo el JRE (que únicamente permite ejecutar programas ya compilados). Al instalar en Windows, marque las opciones que agregan el JDK a [PATH] y definen la variable de entorno [JAVA_HOME]: Gradle, el compilador [kotlinc] y los IDE la usan para ubicar el JDK. En Linux, el JDK está disponible en los repositorios de las principales distribuciones (por ejemplo, [sudo apt install openjdk-25-jdk] en Ubuntu).
Después de la instalación, abra una nueva terminal para verificar que el comando [java] esté disponible y muestre la versión del JDK:
Estos resultados se obtuvieron con JDK Temurin 25.0.4, que se usó para escribir este documento. La versión exacta depende de la fecha de instalación: las actualizaciones de corrección de errores se publican trimestralmente. Todas las versiones 25.0.x del JDK son adecuadas para este documento. Pueden coexistir varias instancias del JDK en la misma computadora: la primera que se encuentre en el directorio de [PATH] responde al comando [java].
El JDK también contiene el compilador de Java [javac] ([javac --version] muestra [javac 25.0.4]). No lo necesitaremos: el compilador de Kotlin genera el bytecode por sí mismo. Pero está ahí, y un proyecto Gradle puede mezclar sin problemas archivos Kotlin y Java, que funcionan juntos.
2.1.2. Los comandos del JDK
Estos son los comandos del JDK que usaremos:
Comando | Función |
[java -jar program.jar] | Ejecuta el programa contenido en un archivo [.jar] cuyo manifiesto especifica la clase principal |
[java -cp classes MyClass] | ejecuta la función [main] de una clase compilada, buscada en la ruta de clases ([-cp], “class path”) |
[javap -cp classes MyClass] | muestra los miembros de una clase compilada: lo usaremos para ver lo que ha producido el compilador de Kotlin |
[jar] | crea o lee un archivo [.jar] (un archivo ZIP de clases compiladas) |
El JDK también proporciona el intérprete interactivo [jshell], pero solo acepta instrucciones Java. Para probar una expresión Kotlin sin escribir un programa, utilice en cambio las herramientas de IntelliJ IDEA descritas más adelante.
2.2. El compilador de Kotlin de línea de comandos
2.2.1. Instalación
Esta instalación es opcional: los proyectos Gradle no la requieren e IntelliJ IDEA incluye su propio compilador. Permite compilar y ejecutar un archivo Kotlin independiente desde una terminal sin crear un proyecto.
El compilador puede descargarse de la página de versiones publicadas del proyecto Kotlin, concretamente en GitHub (https://github.com/JetBrains/kotlin/releases): en la sección “Assets” de la versión 2.4.20, descargue el archivo [kotlin-compiler-2.4.20.zip]. Descomprímalo en una carpeta, por ejemplo [C:\Program Files\kotlinc], y agregue su subcarpeta [bin] a [PATH] (Windows: “Editar las variables de entorno del sistema”). También puede usar un administrador de paquetes: [scoop install kotlin] en Windows (con Scoop), o SDKMAN! en Linux y macOS ([sdk install kotlin 2.4.20]). El compilador requiere un JDK, que ubica mediante la variable [JAVA_HOME] o la variable [PATH] .
Verifique la instalación en una nueva terminal:
La versión del compilador (2.4.20) va seguida de la versión de la JVM que lo ejecuta (JDK 25).
2.2.2. Comandos del compilador
El directorio [bin] contiene dos comandos principales, [kotlinc] (el compilador) y [kotlinr] (el lanzador, “runner”):
Comando | Función |
[kotlinc File.kt -d classes] | compila uno o más archivos fuente y coloca los archivos [.class] resultantes en la carpeta [classes] |
[kotlinc File.kt -include-runtime -d prog.jar] | compila y produce un archivo ejecutable llamado [.jar], que contiene también la biblioteca estándar de Kotlin |
[kotlinr -cp classes MyClass] | como [java -cp classes MyClass], agregando la biblioteca estándar de Kotlin a la ruta de clases |
[kotlinr script.main.kts] | ejecuta un script de Kotlin (archivo [.main.kts]), sin un paso de compilación visible |
Un script de Kotlin es una secuencia de instrucciones que se ejecutan de arriba abajo, sin una función [main]. Por ejemplo, el siguiente script [essai.main.kts]:
se ejecuta así:
Antes de Kotlin 2.4.20, el lanzador se llamaba [kotlin]; en Kotlin 2.4.20 pasó a llamarse [kotlinr] para evitar un conflicto de nombres con otro comando, [kotlin], que pertenece a la herramienta “Kotlin Toolchain”. El nombre antiguo sigue funcionando en la versión 2.4.20 del compilador (no está oficialmente obsoleto), pero la documentación de Kotlin ahora recomienda [kotlinr].
Sin ningún argumento, el comando [kotlinc] solía iniciar un intérprete interactivo (un “REPL”, equivalente a [jshell]). Esta función ahora está obsoleta:
Para probar unas pocas líneas de Kotlin, conviene usar en cambio un archivo de prueba (scratch file) creado con IntelliJ IDEA (“File / New / Scratch File”, lenguaje Kotlin), que muestra los resultados junto a cada línea.
2.3. Gradle
2.3.1. La función de Gradle
Una aplicación real utiliza bibliotecas que no forman parte del JDK ni de la biblioteca estándar de Kotlin: un controlador de base de datos, un framework de pruebas, Hibernate, Spring, corrutinas… Se distribuyen como archivos [.jar] a través de un repositorio público, Maven Central (https://central.sonatype.com). Una herramienta de construcción lee la descripción del proyecto para determinar qué bibliotecas necesita, las descarga (junto con las bibliotecas de las que dependen) y luego compila, prueba y empaqueta el proyecto.
Las dos principales herramientas de construcción del mundo Java son Maven (usada por el curso de Java en el que se basa este documento) y Gradle. Kotlin puede usarse con ambas, pero Gradle es el estándar de facto en el ecosistema Kotlin: lo usa Android y los proyectos Kotlin creados por IntelliJ IDEA, y sus archivos de construcción están escritos... en Kotlin. Este documento usa Gradle 9.8.
2.3.2. El wrapper de Gradle: no requiere instalación
No es necesario instalar Gradle. Cada proyecto de este documento incluye el wrapper de Gradle: un pequeño lanzador formado por tres archivos ubicados en la raíz del proyecto:
- [gradlew]: el script de lanzamiento para Linux y macOS ([./gradlew]);
- [gradlew.bat]: el mismo script para Windows ([gradlew]);
- la [gradle/wrapper] carpeta, que contiene el programa lanzador ([gradle-wrapper.jar]) y su configuración ([gradle-wrapper.properties]).
El archivo [gradle-wrapper.properties] especifica la versión de Gradle que se debe usar:
La primera vez que se ejecuta, [gradlew] descarga esta versión de Gradle y la almacena en la computadora; en las ejecuciones posteriores, la usa directamente. Así, cada proyecto usa la versión de Gradle con la que fue escrito, sea cual sea la versión que pueda estar instalada en la computadora. Gradle solo necesita un JDK para ejecutarse, que encuentra mediante la variable [JAVA_HOME] o la variable [PATH] .
En este documento, los comandos se escriben en el formato de Windows ([gradlew build]); en Linux o macOS, se escriben como [./gradlew build]. En PowerShell, también debe escribirse [.\gradlew build].
Si aun así desea usar el comando [gradle] (para crear un proyecto con [gradle init], por ejemplo), descargue el archivo [gradle-9.8.0-bin.zip] desde https://gradle.org/releases, descomprímalo y agregue su subcarpeta [bin] a [PATH]; o use [scoop install gradle] o [sdk install gradle]. Luego verifique la instalación:
Estos resultados se obtuvieron en Linux. La línea [Kotlin:] indica la versión de Kotlin integrada en Gradle, que se usa para leer los archivos de construcción [.gradle.kts]: es independiente de la versión del compilador de Kotlin utilizada para compilar nuestros programas (2.4.20), que cada proyecto establece. La línea [Launcher JVM] indica el JDK que ejecuta Gradle.
2.3.3. Comandos de Gradle
El comando [gradlew] va seguido de una o más tareas; se ejecuta en el directorio raíz del proyecto, el que contiene el archivo [settings.gradle.kts]:
Comando | Función |
[gradlew build] | compila el código fuente de [src/main/kotlin], ejecuta las pruebas y crea el archivo del proyecto [.jar] en [build/libs] |
[gradlew run] | compila y luego ejecuta la clase principal del proyecto (plugin [application]) |
[gradlew test] | compila y luego ejecuta las pruebas unitarias de [src/test/kotlin] (capítulo 6) |
[gradlew clean] | elimina la carpeta [build] |
[gradlew tasks] | muestra la lista de tareas disponibles en el proyecto |
[gradlew installDist] | crea una versión instalable del programa en [build/install]: sus archivos y scripts de lanzamiento |
[gradlew bootRun] | ejecuta una aplicación Spring Boot (capítulo 13) |
Las tareas son interdependientes: ejecutar [run] también activa la compilación, y Gradle solo vuelve a ejecutar las partes que han cambiado desde la construcción anterior. La opción [-q] (“quiet”) suprime los mensajes de Gradle y muestra solo los del programa ejecutado; la opción [-Pname=value] define una propiedad que el archivo de construcción puede leer: la usaremos para elegir qué programa ejecutar. Los argumentos del programa iniciado por [run] se pasan mediante la opción [--args="a b"].
El primer comando que se ejecuta en un proyecto es lento: Gradle inicia un proceso en segundo plano (el “daemon” de Gradle), que permanece activo durante unas horas para acelerar los comandos posteriores, y descarga lo que el proyecto necesita.
2.3.4. Maven Central y el caché de Gradle
Las bibliotecas descargadas por Gradle se almacenan localmente en el caché de Gradle, en la carpeta [%USERPROFILE%\.gradle\caches] (Linux y macOS: [~/.gradle/caches]). Se descargan una sola vez y luego las reutilizan todos los proyectos. Por lo tanto, se requiere conexión a Internet al construir un proyecto por primera vez. La misma carpeta [.gradle] contiene, dentro de [wrapper/dists], las versiones de Gradle descargadas por el wrapper.
Una biblioteca se identifica por sus coordenadas: tres nombres separados por dos puntos: el grupo (a menudo un nombre de dominio invertido, como [org.hibernate.orm]), el nombre de la biblioteca y su versión, por ejemplo, [tools.jackson.core:jackson-databind:3.1.5]. Estas coordenadas son las que se escriben en el archivo de construcción de un proyecto, y pueden encontrarse buscando la biblioteca en el sitio web de Maven Central.
2.3.5. La sintaxis de Kotlin: DSL
El archivo de construcción del proyecto se llama [build.gradle.kts]. La extensión [.kts] indica que es un script de Kotlin: el archivo está escrito en un lenguaje específico (“DSL”, “Domain Specific Language”) construido con la sintaxis de Kotlin. Gradle también admite archivos [build.gradle] escritos en Groovy, que se encuentran en proyectos más antiguos; desde Gradle 8.2, el DSL de Kotlin es el formato predeterminado. Este es un extracto típico:
Aun sin conocer todavía Kotlin, puede leer este texto como una configuración:
- un nombre seguido de un bloque entre llaves ([plugins { ... }], [dependencies { ... }]) es una sección de la configuración. En Kotlin, es una llamada a una función que recibe un bloque de código como parámetro (una lambda, capítulo 7);
- [kotlin("jvm")] y [implementation("...")] son llamadas a funciones; las cadenas se escriben entre comillas dobles;
- [version = "1.0"] asigna un valor a una propiedad del proyecto.
Una ventaja de este formato es que IntelliJ IDEA lo reconoce como código Kotlin: ofrece autocompletado y señala los errores mientras se escribe.
2.4. El editor
2.4.1. IntelliJ IDEA
IntelliJ IDEA, de la empresa JetBrains, es el editor recomendado para este documento. JetBrains es también la empresa que desarrolló Kotlin (la primera versión estable del lenguaje se publicó en 2016) y que continúa desarrollándolo: el soporte de Kotlin está integrado en IntelliJ IDEA, sin necesidad de extensiones, y es el que sigue más de cerca la evolución del lenguaje. Sus funciones básicas, más que suficientes para este documento, son gratuitas.
IntelliJ IDEA reconoce los proyectos Gradle: seleccione “File / Open” y luego la carpeta que contiene el archivo [settings.gradle.kts]; IntelliJ inicia Gradle para leer el proyecto (puede seguir el proceso en la ventana “Build”), descarga las bibliotecas y luego muestra una vista “Gradle” que da acceso a todas las tareas del proyecto. Después puede ejecutar un programa haciendo clic en el triángulo verde del margen junto a su función [main] ([Ctrl-Shift-F10]), o ejecutar una prueba haciendo clic en el mismo triángulo junto a la función de prueba. El JDK que se usará se especifica en “File / Project Structure / SDK”; en un proyecto Gradle, generalmente es la declaración [jvmToolchain(25)] del proyecto (véase más adelante) la que especifica el JDK para la compilación.
IntelliJ IDEA también ofrece funciones específicas de Kotlin: conversión automática de un archivo Java a Kotlin (“Code / Convert Java File to Kotlin File”, o simplemente pegando código Java en un archivo Kotlin), visualización del bytecode generado por el compilador (“Tools / Kotlin / Show Kotlin Bytecode”) y los archivos de prueba mencionados anteriormente.
2.4.2. VS Code
VS Code es un editor gratuito y multiplataforma. Para programar en Kotlin, instale la extensión Kotlin publicada por JetBrains (vaya al menú “Extensions”, busque “Kotlin” y seleccione la que tenga como editor a JetBrains). Esta extensión oficial es nueva: usa el mismo motor de análisis de código que IntelliJ IDEA y puede importar proyectos Gradle, pero aún no ofrece todas las funciones del IDE de JetBrains, y su funcionalidad cambia de una versión a otra. Consulte la página de la extensión para ver qué admite en el momento de la instalación. Para los fines de este documento, es adecuada para leer y editar programas; siempre puede ejecutarlos desde la terminal integrada (“Terminal / New Terminal”) con los comandos [gradlew] que se indican en el texto.
En VS Code, abra la carpeta de un capítulo ("File / Open Folder"), por ejemplo, la carpeta [kotlin-oct-2026/03-basics].
2.4.3. Android Studio
Kotlin es también el lenguaje recomendado por Google para las aplicaciones Android. Android Studio, construido sobre IntelliJ IDEA, está dedicado a este tipo de aplicaciones, que no se tratan en este documento.
En el resto de este documento, las operaciones se describen con los comandos [java], [kotlinc] y [gradlew], que producen los mismos resultados sea cual sea el editor.
2.5. Un programa de ejemplo: el archivo Hello.kt
2.5.1. El programa
Un programa Kotlin puede ser un simple archivo que contiene una función llamada [main], sin declaración de clase. Creemos el siguiente archivo, [Hello.kt] (en la carpeta de ejemplos [02-installation] ):
Comentarios:
- línea 1: un comentario. Todo lo que sigue a [//] hasta el final de la línea es ignorado por el compilador;
- línea 2: la función [main], el punto de entrada del programa. La palabra clave [fun] introduce una función. Se declara a nivel de archivo (“top-level function”), fuera de cualquier clase; no es necesario declararla como [public] (esta es la visibilidad predeterminada en Kotlin) ni tiene que recibir argumentos del programa;
- línea 3: la única instrucción del programa: imprime una línea de texto en pantalla. La función [println] (y [print], que no salta a la línea siguiente) forma parte de la biblioteca estándar de Kotlin; es el equivalente de [System.out.println] en Java. Observe la ausencia de punto y coma al final de la instrucción: es opcional en Kotlin y no se escribe.
El programa es un poco más simple que su equivalente en el curso de Java ([void main() { IO.println(...); }]), pero la verdadera diferencia está en otra parte: la función de nivel superior [main] existe en Kotlin desde su primera versión, mientras que Java solo la admite desde Java 25.
2.5.2. Compilación y ejecución
Compilamos el programa con [kotlinc], especificando un archivo ejecutable llamado [.jar], y luego lo ejecutamos con el comando [java] del JDK:
- [-d hello.jar]: el destino de la compilación. Si termina en [.jar], el compilador produce un archivo; de lo contrario, es una carpeta en la que almacena los archivos [.class];
- [-include-runtime]: el archivo contiene además la biblioteca estándar de Kotlin ([kotlin-stdlib]), que los programas Kotlin necesitan en tiempo de ejecución, y un manifiesto que especifica la clase principal. Así, el programa puede ejecutarse con [java -jar] en cualquier máquina que tenga un JDK (o JRE), aunque Kotlin no esté instalado en ella. En cambio, el archivo pesa más de 5 MB, formado principalmente por la biblioteca estándar;
- la compilación tarda unos segundos: el compilador de Kotlin, que es a su vez un programa Java, debe iniciarse primero. Gradle e IntelliJ IDEA evitan este costo manteniendo un compilador activo entre compilaciones.
No existe en Kotlin un equivalente del comando de Java [java Hello.java], que compila y ejecuta un archivo fuente en un solo paso; lo más parecido es el script [.main.kts] presentado anteriormente.
2.5.3. Lo que produce el compilador
La máquina virtual de Java (JVM) solo reconoce clases: una función no puede existir fuera de una clase. Por eso el compilador de Kotlin envuelve las funciones de nivel superior de un archivo en una clase que genera él mismo, y la nombra a partir del archivo: el nombre del archivo seguido de [Kt]. Para [Hello.kt], la clase generada es [HelloKt]. El comando [javap] del JDK muestra sus miembros:
- La clase [HelloKt] es [public final];
- contiene nuestra función [main], que se ha convertido en un método estático sin parámetros;
- y un segundo método, [main(String[])], agregado por el compilador: es el método [public static void main(String[] args)] que la máquina virtual sabe invocar. Simplemente llama al primero. Volveremos sobre este mecanismo en el capítulo 3.
Este nombre de clase es el que identifica el programa que se ejecutará: el manifiesto de [hello.jar] contiene la línea [Main-Class: HelloKt], y también se puede escribir [java -cp hello.jar HelloKt].
A diferencia de Java, no hay restricciones sobre el nombre del archivo: no tiene que ser un identificador válido ni coincidir con el nombre de una clase que contenga. Se acepta un archivo llamado [first-try.kt] , y su clase generada se llama [First_tryKt] (el compilador pone en mayúscula la primera letra y reemplaza los caracteres no permitidos en un identificador por [_]). Sin embargo, por convención, los archivos reciben nombres que comienzan con mayúscula y no contienen guiones, como [Hello.kt] o [Basics01.kt].
En Windows, los caracteres acentuados escritos con [println] se muestran correctamente en la terminal: la máquina virtual convierte el texto a la codificación de la terminal. Los archivos fuente deben guardarse en UTF-8, la codificación predeterminada de VS Code e IntelliJ IDEA, y la que el compilador de Kotlin siempre supone. La situación es distinta cuando el programa lo inicia Gradle ([gradlew run], o el triángulo verde en un proyecto Gradle): su salida ya no es una consola sino una tubería hacia Gradle, y la máquina virtual la codifica entonces con la codificación histórica de Windows (windows-1252), de modo que IntelliJ IDEA, que espera UTF-8, muestra un carácter de reemplazo (un rombo con un signo de interrogación) en lugar de cada carácter acentuado. Los proyectos del curso resuelven este problema en su archivo [build.gradle.kts] (véase la sección siguiente). Para la terminal integrada de IntelliJ IDEA (PowerShell), también puede cambiar la consola a UTF-8 escribiendo [chcp 65001] al inicio de la sesión, o de una vez por todas especificando [powershell.exe -NoExit -Command "[Console]::OutputEncoding = [Text.Encoding]::UTF8"] como intérprete en “File / Settings / Tools / Terminal / Shell path”.
El comando [kotlinc] es adecuado para programas de un solo archivo que usan únicamente la biblioteca estándar. En cuanto un programa requiere una biblioteca externa, debe descargarla, junto con las bibliotecas de las que depende, y pasarla al compilador y luego a la máquina virtual: esto implica crear un proyecto Gradle. Es lo que haremos con todos los ejemplos de este documento.
2.6. Un proyecto Gradle
2.6.1. Estructura del proyecto
Un proyecto Gradle es una carpeta que contiene un archivo de construcción llamado [build.gradle.kts] y archivos fuente organizados según una estructura de directorios estándar. La raíz de una construcción Gradle contiene además un archivo llamado [settings.gradle.kts], que indica el nombre de la construcción y la lista de proyectos que agrupa, así como el wrapper. La carpeta [02-installation] de los ejemplos es una construcción que agrupa dos proyectos, [FirstProgram] y [TwoHands]:
- [src/main/kotlin] contiene los archivos fuente del programa; [src/main/resources] contendría los archivos de datos o de configuración que se colocan junto a las clases compiladas; [src/test/kotlin] contendría las pruebas (capítulo 6);
- Dentro de [src/main/kotlin], la estructura de carpetas refleja la de los paquetes (capítulo 4): el archivo [Main.kt] del paquete [first] se encuentra en la carpeta [first]. Kotlin no exige esta correspondencia, a diferencia de Java, pero la recomienda, y siempre la seguiremos;
- El archivo [Hello.kt] no pertenece a ningún proyecto: está ahí para ser compilado con [kotlinc], y Gradle lo ignora.
Un proyecto independiente (no agrupado con otros) tiene la misma estructura, con sus propios archivos [settings.gradle.kts] y del wrapper: es el caso del proyecto del capítulo 3. Puede crear esta estructura de directorios manualmente, o dejar que el IDE la cree (IntelliJ: “File / New / Project”, seleccione “Kotlin” como lenguaje y “Gradle” como sistema de construcción, con el DSL de Kotlin).
Veremos los archivos de la raíz en la siguiente sección. El archivo [build.gradle.kts] del proyecto [FirstProgram] es el siguiente:
Comentarios:
- línea 1: un comentario. El archivo de construcción está escrito en Kotlin: los comentarios se escriben igual que en un programa;
- líneas 2–7: los plugins aplicados al proyecto. Estos proporcionan a Gradle las tareas que necesitamos:
- línea 4: el plugin de Kotlin para la JVM. Agrega tareas que compilan los archivos de [src/main/kotlin] y agrega automáticamente la biblioteca estándar de Kotlin a las dependencias del proyecto. La notación [kotlin("jvm")] es una abreviatura del identificador completo del plugin, [org.jetbrains.kotlin.jvm]. Aquí no se especifica su versión porque el proyecto forma parte de una construcción de múltiples proyectos en la que el proyecto raíz establece esta versión para todos ellos (véase la siguiente sección). En un proyecto independiente, se escribiría [kotlin("jvm") version "2.4.20"]: esta versión determina la versión del compilador de Kotlin utilizada;
- línea 6: el plugin [application], que agrega las tareas [run] (ejecutar el programa) e [installDist] (preparar una versión instalable);
- líneas 10–11: los identificadores de proyecto, grupo y versión, que identifican el proyecto por su nombre ([FirstProgram], el nombre de su carpeta). Son también los identificadores que otro proyecto podría usar para hacer referencia a este, de manera similar a cómo se hace referencia a una biblioteca de Maven Central (capítulo 6);
- líneas 14–15: el repositorio donde Gradle busca las bibliotecas del proyecto, en este caso Maven Central;
- líneas 18–20: las bibliotecas usadas por el proyecto. Este proyecto no usa ninguna, aparte de la biblioteca estándar de Kotlin que el plugin de Kotlin agrega automáticamente;
- línea 24: la toolchain del proyecto: el código se compila para Java 25 y [gradlew run] lo ejecuta con un JDK 25, aunque el propio Gradle se ejecute con un JDK distinto. Gradle busca este JDK entre los instalados en la máquina. Si no encuentra ninguno, falla con el mensaje de error [Cannot find a Java installation on your machine ... matching: {languageVersion=25 ...}], a menos que la construcción declare el plugin [foojay-resolver-convention], como hacen todos los proyectos del curso (véase la siguiente sección): Gradle descarga entonces por sí mismo un JDK 25. En IntelliJ IDEA, también puede instalar este JDK mediante “File / Project Structure / SDK / Add SDK / Download JDK”;
- línea 27: una advertencia del compilador se trata como un error y detiene la compilación. El compilador de Kotlin señala muchos problemas (variables sin usar, conversiones de tipo innecesarias, operadores [!!] superfluos, etc.): queremos programas que no produzcan ninguno de ellos;
- línea 29: el compilador conserva los nombres de los parámetros de las funciones en el bytecode. Algunas bibliotecas lo aprovechan, por ejemplo, Jackson para crear un objeto a partir de un documento JSON (capítulo 5) o Spring (capítulo 13);
- líneas 33–35: la clase cuya función [main] ejecuta [gradlew run]. El nombre es el de la clase generada por el compilador para el archivo [Main.kt] del paquete [first]: [first.MainKt];
- líneas 38–41: todas las tareas que ejecutan un programa Java ([JavaExec]), como [run], reciben dos opciones de la máquina virtual: la salida por pantalla del programa ([System.out], [System.err]) se codifica en UTF-8. Sin ellas, los caracteres acentuados escritos por el programa aparecerían corruptos en la consola de IntelliJ IDEA en Windows (véase la nota sobre los acentos más arriba). [tasks.withType<JavaExec>()] se refiere a todas las tareas de este tipo, y [configureEach { … }] configura cada una de ellas. Todos los proyectos del curso que ejecutan un programa contienen esta configuración.
Este proyecto no usa ninguna biblioteca. Un proyecto que usa una biblioteca la declara en la sección [dependencies] mediante sus coordenadas, como haremos a partir del capítulo 5:
El término [implementation] indica que la biblioteca es necesaria para compilar y ejecutar el programa. También encontrará [runtimeOnly] (necesaria solo para la ejecución, como un controlador de base de datos) y [testImplementation] (necesaria solo para las pruebas). Gradle descargará entonces [jackson-databind] y las bibliotecas de las que depende.
El archivo [Main.kt] contiene el programa:
- línea 1: el archivo pertenece al paquete [first]. Por lo tanto, el nombre completo de la clase generada para este archivo es [first.MainKt];
- líneas 4–6: la función [main], con la misma forma que en [Hello.kt]. Un archivo Kotlin puede contener cualquier cantidad de funciones y clases, públicas o no: el nombre del archivo no depende de su contenido.
2.6.2. Compilación y ejecución
El comando [gradlew build], ejecutado en la carpeta [02-installation], compila los proyectos de la construcción (y ejecutaría sus pruebas si las tuvieran): Gradle descarga el plugin de Kotlin, el compilador y la biblioteca estándar según sea necesario, luego compila los archivos de [src/main/kotlin] y coloca las clases resultantes en la carpeta [build/classes/kotlin/main] de cada proyecto, conservando la estructura de paquetes ([FirstProgram/build/classes/kotlin/main/first/MainKt.class]).
El comando [gradlew run] compila un proyecto y luego lo ejecuta. En una construcción con varios proyectos, el proyecto se especifica mediante su ruta, precedida de dos puntos: [:FirstProgram:run] es la tarea [run] del proyecto [FirstProgram]. Con la opción [-q], solo se muestra la salida del programa:
También puede ir a la carpeta del proyecto y escribir [..\gradlew -q run]: Gradle sube hasta el archivo [settings.gradle.kts] del directorio raíz y ejecuta la tarea [run] del proyecto de la carpeta actual. En cambio, escribir [gradlew run] en el directorio raíz ejecutaría la tarea [run] de todos los proyectos que la tengan.
Una vez compilado el proyecto, también puede ejecutar la clase directamente con el comando [java], indicando la ubicación de las clases (en la carpeta [FirstProgram]):
Esto funciona aquí porque este programa no usa realmente nada de la biblioteca estándar de Kotlin en tiempo de ejecución: el compilador reemplaza la llamada a [println] por una llamada directa a [System.out.println]. Sin embargo, un programa que use, por ejemplo, una lista ([listOf(1, 2, 3)]) falla de este modo con el error [java.lang.NoClassDefFoundError: kotlin/collections/CollectionsKt]: no se encuentra la clase [CollectionsKt] de la biblioteca estándar. Entonces debe agregar el archivo [kotlin-stdlib-2.4.20.jar] a la ruta de clases (está en el caché de Gradle; la carpeta [lib] del compilador [kotlinc] también lo contiene, con el nombre [kotlin-stdlib.jar]): [java -cp "build/classes/kotlin/main;path/kotlin-stdlib-2.4.20.jar" first.MainKt] en Windows (el separador es [:] en Linux y macOS). El comando [kotlinr -cp build/classes/kotlin/main first.MainKt] del compilador de línea de comandos lo hace por nosotros.
La forma más sencilla es hacer que Gradle construya el programa y todo lo que necesita mediante la tarea [installDist] del plugin [application]:
Crea la carpeta [FirstProgram/build/install/FirstProgram], que contiene una carpeta [lib] (el archivo del proyecto, la biblioteca estándar de Kotlin y, en su caso, las demás bibliotecas del proyecto) y una carpeta [bin] con dos scripts de lanzamiento, [FirstProgram] (Linux, macOS) y [FirstProgram.bat] (Windows), que invocan [java] con la ruta de clases correcta. De esta forma, un programa se entrega para que pueda copiarse a otra computadora que tenga un JDK:
La carpeta [build] puede eliminarse sin riesgo ([gradlew clean]): la próxima compilación la vuelve a crear. El comando [gradlew build] también produce el archivo del proyecto [build/libs/FirstProgram-1.0.jar], que contiene únicamente sus propias clases.
2.7. Un proyecto con varios módulos
2.7.1. La construcción multiproyecto
Una construcción Gradle puede agrupar varios proyectos, llamados subproyectos (o módulos). El archivo [settings.gradle.kts] del directorio raíz los enumera. El de la carpeta [02-installation] es el siguiente:
- líneas 3–6: un plugin para la construcción en sí (no para un proyecto), [foojay-resolver-convention]: cuando un proyecto solicita un JDK mediante [jvmToolchain(25)] que Gradle no encuentra en la máquina, Gradle lo descarga del servicio foojay.io y lo almacena en su caché. La primera ejecución tarda un poco más, pero el estudiante ya no necesita tener instalado el JDK correcto. El bloque [plugins] debe ser el primero del archivo. Todas las construcciones del curso declaran este plugin;
- línea 8: el nombre de la construcción (el proyecto raíz). Sin esta línea, sería el nombre de la carpeta;
- línea 11: los subproyectos, identificados por los nombres de sus carpetas. Un subproyecto puede estar anidado más profundamente: [include("TaxV5:tax-dao")] se refiere al proyecto de la carpeta [TaxV5/tax-dao] (capítulo 6).
El proyecto raíz también tiene un archivo llamado [build.gradle.kts]:
- líneas 3–4: se declara el plugin de Kotlin, junto con su versión, pero no se aplica al proyecto raíz ([apply false]), que no contiene código para compilar. Esta declaración hace que el plugin esté disponible para los subproyectos, que lo aplican mediante [kotlin("jvm")] sin repetir la versión: así, todos los subproyectos usan la misma versión de Kotlin, que puede cambiarse en un único lugar. Si cada subproyecto declarara por su cuenta la versión del plugin, Gradle lo cargaría varias veces, algo que el plugin de Kotlin desaconseja.
En la carpeta [02-installation], el comando [gradlew build] compila ambos proyectos; un IDE que abre esta carpeta ve ambos proyectos a la vez. En el capítulo 6 veremos que un subproyecto puede depender de otro ([implementation(project(":TaxV5:tax-dao"))]), y en los capítulos 10 a 13 veremos que una construcción puede incluso reutilizar proyectos de otra construcción ([includeBuild]).
2.7.2. Un proyecto con varias funciones main
Un proyecto puede contener varios archivos, cada uno con una función [main]: cada una es un posible punto de entrada, y la clase que se ejecutará se elige en tiempo de ejecución. El proyecto [TwoHands] contiene dos archivos del paquete [twohands]. El archivo [P1.kt]:
y el archivo [P2.kt], que es idéntico salvo por el nombre. Ambas funciones se llaman [main] y pertenecen al mismo paquete: no hay conflicto porque están en dos clases distintas, [twohands.P1Kt] y [twohands.P2Kt]. El comando [java] ejecuta la clase que se le indica (en la carpeta [TwoHands], una vez compilado el proyecto):
Para el comando [gradlew run], el archivo [build.gradle.kts] del proyecto especifica la clase que se ejecutará:
- línea 5: la clase que se ejecuta se especifica mediante la propiedad [main] de Gradle, que se proporciona en la línea de comandos mediante la opción [-Pmain=...]. La función [providers.gradleProperty("main")] lee esta propiedad; [orElse(...)] especifica el valor que se usará si no se ha proporcionado: en este caso, la clase [twohands.P2Kt].
El resto del archivo es igual al de [FirstProgram], con el agregado de una configuración para la tarea [run] ([standardInput = System.in]), que transmite la entrada del teclado al programa: sin ella, un programa iniciado con [gradlew run] no puede leer el teclado.
Resultados:
Esto permite seleccionar el programa que se ejecutará sin modificar el archivo [build.gradle.kts]. Con IntelliJ IDEA, el problema no se plantea: cada función [main] tiene su propio triángulo verde en el margen.
2.7.3. Un paquete por programa
Los proyectos de los capítulos siguientes usan todos este mecanismo, ya que cada uno contiene muchos programas pequeños. Para evitar que estos programas interfieran entre sí, este documento sigue una convención sencilla: cada programa tiene su propio paquete, que lleva su nombre en minúsculas y se almacena en una carpeta con el mismo nombre. Así, el programa [Basics04.kt] del capítulo 3 es el archivo [03-basics/src/main/kotlin/basics04/Basics04.kt], que comienza con la línea [package basics04]; su clase es [basics04.Basics04Kt], y se ejecuta de la siguiente manera:
Esta convención tiene dos razones:
- Todos los programas de un proyecto se compilan juntos. Si estuvieran en el mismo paquete, dos programas no podrían declarar una función o clase con el mismo nombre (una función [display], una clase [Person]…): el compilador informaría una declaración duplicada. Con un paquete por programa, cada uno tiene su propio espacio de nombres;
- un programa formado por varios archivos es simplemente un paquete que contiene varios archivos: en el capítulo 4, el paquete [persons] contiene la clase [Person] en [Person.kt] y el programa principal en [Main.kt], que se ejecuta mediante [-Pmain=persons.MainKt].
El texto de cada capítulo indica, antes de los resultados de un programa, el comando exacto que lo ejecuta. Volveremos sobre esta estructura en el capítulo 3.
2.8. Los ejemplos de este documento
Para ejecutar los ejemplos de este documento:
- descargue la carpeta [kotlin-oct-2026] (enlace al principio del documento). Contiene una carpeta por capítulo ([02-installation], [03-basics], [04-classes]…), y cada una de estas carpetas es una construcción Gradle, completa con su wrapper: un único proyecto, o varios subproyectos agrupados mediante su archivo [settings.gradle.kts];
- abra la carpeta de un capítulo en IntelliJ IDEA (“File / Open”); luego ejecute un programa haciendo clic en el triángulo verde junto a su función [main];
- o, en una terminal ubicada en la carpeta del capítulo, ejecute un programa con [gradlew -q run -Pmain=package.ClassKt] (con la ruta del subproyecto antes de [run] si hay varios subproyectos); el texto de cada capítulo indica el comando exacto.
El primer comando [gradlew] de un capítulo requiere acceso a Internet: Gradle descarga entonces su propia distribución, el plugin de Kotlin y las bibliotecas del proyecto, que luego almacena en su caché.
Los capítulos 10 y 11 usan una base de datos llamada MySQL; la instalación de MySQL con [Laragon] se describe en el apéndice.