Editar Página
Para construir un proyecto Kotlin con Gradle, debes aplicar el plugin Kotlin Gradle a tu proyecto y configurar las dependencias.
- Plugin y versiones
- Objetivo de múltiples plataformas
- Objeción de la JVM
- Fuentes de Kotlin y Java
- Objetivos de JavaScript
- Fuentes de Kotlin y Java
- Objetivo Android
- Configuración de dependencias
- Tipos de dependencia
- Dependencia de la biblioteca estándar
- Establecer dependencias de bibliotecas de prueba
- Establecer una dependencia de una biblioteca kotlinx
- Establezca las dependencias en el nivel superior
- Procesamiento de anotaciones
- Compilación incremental
- Soporte de caché de compilación de Gradle
- Soporte de caché de configuración de Gradle
- Opciones del compilador
- Atributos comunes para JVM, JS, y JS DCE
- Atributos comunes para JVM y JS
- Atributos específicos para JVM
- Atributos específicos para JS
- Generar documentación
- OSGi
- Usando Gradle Kotlin DSL
Plugin y versiones
Aplica el plugin Kotlin Gradle utilizando el DSL de plugins de Gradle.
El plugin Kotlin Gradle 1.4.30 funciona con Gradle 5.4 y posteriores. El plugin kotlin-multiplatformrequiere Gradle 6.0 o posterior.
plugins { id 'org.jetbrains.kotlin.<...>' version '1.4.30'}plugins { kotlin("<...>") version "1.4.30"}El marcador de posición <...> debe ser sustituido por uno de los nombres de plugin que se pueden encontrar en otras secciones.
Objetivo de múltiples plataformas
Los proyectos destinados a múltiples plataformas, llamados proyectos multiplataforma, requieren el plugin kotlin-multiplatform. Más información sobre el plugin.
El plugin
kotlin-multiplatformfunciona con Gradle 6.0 o posterior.
plugins { id 'org.jetbrains.kotlin.multiplatform' version '1.4.30'}plugins { kotlin("multiplatform") version "1.4.30"}Objeción de la JVM
Para la orientación de la JVM, aplique el plugin Kotlin JVM.
plugins { id "org.jetbrains.kotlin.jvm" version "1.4.30"}plugins { kotlin("jvm") version "1.4.30"}El version debe ser literal en este bloque, y no se puede aplicar desde otro script de compilación.
Alternativamente, puedes usar el enfoque más antiguo de apply plugin:
apply plugin: 'kotlin'No se recomienda aplicar plugins de Kotlin con apply en Gradle Kotlin DSL – ver por qué.
Fuentes de Kotlin y Java
Las fuentes de Kotlin pueden almacenarse con las de Java en la misma carpeta, o colocarse en carpetas diferentes. La convención por defecto es utilizar carpetas diferentes:
project - src - main (root) - kotlin - javaLa propiedad sourceSets correspondiente debe ser actualizada si no se utiliza la convención por defecto:
sourceSets { main.kotlin.srcDirs += 'src/main/myKotlin' main.java.srcDirs += 'src/main/myJava'}sourceSets.main { java.srcDirs("src/main/myJava", "src/main/myKotlin")}Objetivos de JavaScript
Cuando se trate de objetivos sólo de JavaScript, utilice el plugin kotlin-js. Más información
plugins { id 'org.jetbrains.kotlin.js' version '1.4.30'}plugins { kotlin("js") version "1.4.30"}Fuentes de Kotlin y Java
Este plugin sólo funciona para archivos de Kotlin por lo que se recomienda guardar los archivos de Kotlin y Java por separado (en caso de que el proyecto contenga archivos de Java). Si no los guardas por separado , especifica la carpeta de fuentes en el bloque sourceSets:
kotlin { sourceSets { main.kotlin.srcDirs += 'src/main/myKotlin' }}kotlin { sourceSets.apply { kotlin.srcDir("src/main/myKotlin") }}Objetivo Android
Se recomienda utilizar Android Studio para crear aplicaciones Android. Aprende a utilizar el plugin Gradle de Android.
Configuración de dependencias
Para añadir una dependencia de una biblioteca, establece la dependencia del tipo requerido (por ejemplo, implementation) en el bloque dependencies del DSL de los conjuntos de fuentes.
kotlin { sourceSets { commonMain { dependencies { implementation 'com.example:my-library:1.0' } } }}kotlin { sourceSets { val commonMain by getting { dependencies { implementation("com.example:my-library:1.0") } } }}Alternativamente, puede establecer dependencias en el nivel superior.
Tipos de dependencia
Elige el tipo de dependencia en función de tus necesidades.
| Tipo | Descripción | Cuándo utilizar |
|---|---|---|
api |
Se utiliza tanto durante la compilación como en tiempo de ejecución y se exporta a los consumidores de la biblioteca. | Si algún tipo de una dependencia se utiliza en la API pública del módulo actual, utiliza una dependencia api. |
implementation |
Se utiliza durante la compilación y en tiempo de ejecución para el módulo actual, pero no se expone para la compilación de otros módulos que dependen del que tiene la dependencia `implementation`. |
Utilizar para las dependencias necesarias para la lógica interna de un módulo. Si un módulo es una aplicación de punto final que no se publica, utilice |
compileOnly |
Se utiliza para la compilación del módulo actual y no está disponible en tiempo de ejecución ni durante la compilación de otros módulos. | Se utiliza para las API que tienen una implementación de terceros disponible en tiempo de ejecución. |
runtimeOnly |
Disponible en tiempo de ejecución pero no es visible durante la compilación de ningún módulo. |
Dependencia de la biblioteca estándar
Se añade automáticamente una dependencia de una biblioteca estándar (stdlib) en cada conjunto de fuentes. La versión de la biblioteca estándar es la misma que la del plugin Kotlin Gradle.
Para los conjuntos de fuentes específicos de la plataforma, se utiliza la variante específica de la plataforma correspondiente de la biblioteca, mientras que una biblioteca estándar común se añade al resto. El plugin Kotlin Gradle seleccionará la biblioteca estándar JVM apropiada dependiendo de la opción de compilador kotlinOptions.jvmTarget de tu script de construcción Gradle.
Si declaras una dependencia de biblioteca estándar explícitamente (por ejemplo, si necesitas una versión diferente), el plugin Kotlin Gradle no la anulará ni añadirá una segunda biblioteca estándar.
Si no necesitas una biblioteca estándar en absoluto, puedes añadir la bandera opt-out al gradle.properties:
kotlin.stdlib.default.dependency=falseEstablecer dependencias de bibliotecas de prueba
La API kotlin.test está disponible para probar diferentes proyectos Kotlin.
Añadir las dependencias correspondientes en las bibliotecas de prueba:
- Para
commonTest, añadir las dependenciaskotlin-test-commonykotlin-test-annotations-common. - Para los objetivos JVM, utilice
kotlin-test-junitokotlin-test-testngpara la implementación correspondiente del asertor y el mapeo de anotaciones. - Para los objetivos Kotlin/JS, añada
kotlin-test-jscomo dependencia de prueba.
Los objetivos Kotlin/Nativo no requieren dependencias de prueba adicionales, y las implementaciones de la API kotlin.test están incorporadas.
Se puede utilizar la abreviatura de una dependencia de un módulo Kotlin, por ejemplo, kotlin(«test») para «org.jetbrains.kotlin:kotlin-test».
Establecer una dependencia de una biblioteca kotlinx
Si utilizas una biblioteca kotlinx y necesitas una dependencia específica de la plataforma, puedes utilizar variantes de bibliotecas específicas de la plataforma con sufijos como -jvm o -js, por ejemplo, kotlinx-coroutines-core-jvm. También puede utilizar el nombre del artefacto base de la biblioteca en su lugar – kotlinx-coroutines-core.
kotlin { sourceSets { jvmMain { dependencies { implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.4.2' } } }}Si utiliza una biblioteca multiplataforma y necesita depender del código compartido, establezca la dependencia sólo una vez en el conjunto de fuentes compartido. Utilice el nombre del artefacto base de la biblioteca, como kotlinx-coroutines-core o ktor-client-core.
kotlin { sourceSets { commonMain { dependencies { implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.4.2' } } }}Establezca las dependencias en el nivel superior
Alternativamente, puede especificar las dependencias en el nivel superior con los nombres de configuración siguiendo el patrón <sourceSetName><DependencyType>. Esto es útil para algunas dependencias integradas en Gradle, como gradleApi(), localGroovy() o gradleTestKit(), que no están disponibles en el DSL de dependencias de conjuntos de fuentes.
dependencies { commonMainImplementation 'com.example:my-library:1.0'}dependencies { "commonMainImplementation"("com.example:my-library:1.0")}Procesamiento de anotaciones
Kotlin soporta el procesamiento de anotaciones a través de la herramienta de procesamiento de anotaciones de Kotlin kapt.
Compilación incremental
El plugin Gradle de Kotlin soporta la compilación incremental. La compilación incremental realiza un seguimiento de los cambios de los archivos de origen entre las compilaciones, por lo que sólo se compilarían los archivos afectados por estos cambios.
La compilación incremental es compatible con los proyectos Kotlin/JVM y Kotlin/JS y está activada por defecto desde Kotlin 1.1.1.
Hay varias formas de desactivar la configuración:
- Añade la siguiente línea al archivo
gradle.propertiesolocal.properties:-
kotlin.incremental=falsepara Kotlin/JVM -
kotlin.incremental.js=falsepara proyectos Kotlin/JS
-
-
Como parámetro de línea de comandos, utilice
-Pkotlin.incremental=falseo-Pkotlin.incremental.js=false.Nótese que en este caso el parámetro debe añadirse a cada compilación posterior, y cualquier compilación con la compilación incremental desactivada invalida las cachés incrementales.
Nótese que la primera compilación no es incremental en ningún caso.
Soporte de caché de compilación de Gradle
El plugin de Kotlin soporta la caché de compilación de Gradle que almacena las salidas de compilación para su reutilización en futuras compilaciones.
Para deshabilitar el almacenamiento en caché para todas las tareas de Kotlin, establezca la bandera de la propiedad del sistema kotlin.caching.enabled a false (ejecute la compilación con el argumento -Dkotlin.caching.enabled=false).
Si utiliza kapt, tenga en cuenta que las tareas de procesamiento de anotaciones de kapt no se almacenan en caché por defecto. Sin embargo, puedes habilitar el almacenamiento en caché para ellas manualmente.
Soporte de caché de configuración de Gradle
La caché de configuración está disponible en Gradle 6.5 y posteriores como una característica experimental.Puedes consultar la página de versiones de Gradle para ver si ha sido promovida a estable.
El plugin de Kotlin es compatible con la caché de configuración de Gradle, que acelera el proceso de construcción mediante la reutilización de los resultados de la fase de configuración.
Consulta la documentación de Gradle para saber cómo habilitar la caché de configuración. Una vez que se habilita la función de caché de configuración, el plugin Gradle de Kotlin comenzará a utilizarla.
Opciones del compilador
Para especificar opciones de compilación adicionales, utilice la propiedad kotlinOptions de una tarea de compilación de Kotlin.
Cuando se dirige a la JVM, las tareas se llaman compileKotlin para el código de producción y compileTestKotlin para el código de prueba. Las tareas para los conjuntos de fuentes personalizados se llaman de acuerdo con el patrón compile<Name>Kotlin.
Los nombres de las tareas en los proyectos de Android contienen los nombres de las variantes de compilación y siguen el patrón compile<BuildVariant>Kotlin, por ejemplo, compileDebugKotlin, compileReleaseUnitTestKotlin.
Cuando se dirige a JavaScript, las tareas se llaman compileKotlinJs y compileTestKotlinJs respectivamente, y compile<Name>KotlinJs para los conjuntos de fuentes personalizados.
Para configurar una sola tarea, utilice su nombre. Ejemplos:
compileKotlin { kotlinOptions.suppressWarnings = true}//orcompileKotlin { kotlinOptions { suppressWarnings = true }}Tenga en cuenta que con Gradle Kotlin DSL, debe obtener la tarea desde el tasks del proyecto primero.
Utilice los tipos Kotlin2JsCompile y KotlinCompileCommon para los objetivos JS y Common, respectivamente.
También es posible configurar todas las tareas de compilación de Kotlin en el proyecto:
tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach { kotlinOptions { /*...*/ }}tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile>().configureEach { kotlinOptions { /*...*/ }}La lista completa de opciones para las tareas de Gradle es la siguiente:
Atributos comunes para JVM, JS, y JS DCE
| Nombre | Descripción | Valores posibles | Valor por defecto |
|---|---|---|---|
allWarningsAsErrors |
Informar de un error si hay alguna advertencias | false | |
suppressWarnings |
No generar advertencias | ||
verbose |
Activar la salida de registro verboso | false | |
freeCompilerArgs |
Una lista de argumentos adicionales del compilador |
Atributos comunes para JVM y JS
Atributos específicos para JVM
| Nombre | Descripción | Valores posibles | Valor por defecto |
|---|---|---|---|
javaParameters |
Generar metadatos para Java 1.8 en los parámetros de los métodos | false | |
jdkHome |
Incluir un JDK personalizado desde la ubicación especificada en el classpath en lugar del JAVA_HOME | ||
jvmTarget |
Versión objetivo del bytecode de la JVM generada | «1.6», «1.8», «9», «10», «11», «12», «13», «14», «15» | «1.6» |
noJdk |
No incluir automáticamente el runtime de Java en el classpath | ||
noReflect |
No incluir automáticamente Kotlin reflection en el classpath | true | |
noStdlib |
No incluir automáticamente la stdlib de Kotlin/JVM y la reflexión de Kotlin en el classpath | true | |
useIR |
Utilizar el backend IR | false |
Atributos específicos para JS
| Nombre | Descripción | Valores posibles | Valor por defecto |
|---|---|---|---|
friendModulesDisabled |
Desactivar la exportación de la declaración interna | false | |
main |
Define si la función maindebe ser llamada al ejecutarse |
«call», «noCall» | «call» |
metaInfo |
Generar los archivos .meta.js y archivos .kjsm con metadatos. Se utiliza para crear una biblioteca | true | |
moduleKind |
El tipo de módulo JS generado por el compilador | «umd», «commonjs», «amd», «plain» | «umd» |
noStdlib |
No incluir automáticamente el stdlib de Kotlin/JS por defecto en las dependencias de compilación | ||
outputFile |
Destino *.js para el resultado de la compilación | «<buildDir>/js/packages/<project.name>/kotlin/<project.name>.js» | |
sourceMap |
Generar mapa de fuentes | true | |
sourceMapEmbedSources |
Incorporar archivos fuente en el mapa de fuentes | «nunca», «siempre», «inlining» | |
sourceMapPrefix |
Añadir el prefijo especificado a las rutas en el mapa de fuentes | ||
target |
Generar archivos JS para la versión ECMA específica | «v5» | «v5» |
typedArrays |
Traducir arrays primitivos a arrays tipados en JS | true |
Generar documentación
Para generar documentación para proyectos Kotlin, utilice Dokka;por favor, consulte el README de Dokka para obtener instrucciones de configuración. Dokka soporta proyectos de lenguaje mixto y puede generar la salida en múltiples formatos, incluyendo JavaDoc estándar.
OSGi
Para el soporte de OSGi vea la página de Kotlin OSGi.
Usando Gradle Kotlin DSL
Cuando use Gradle Kotlin DSL, aplique los plugins de Kotlin usando el bloque plugins { ... }. Si los aplicas con apply { plugin(...) } en su lugar, puedes encontrar referencias no resueltas a las extensiones generadas por Gradle Kotlin DSL. Para resolverlo, puedes comentar los usos erróneos, ejecutar la tarea de Gradle kotlinDslAccessorsSnapshot, luego descomentar los usos de nuevo y volver a ejecutar la construcción o reimportar el proyecto en el IDE.