Criando, configurando e publicando uma biblioteca Kotlin

Este artigo tem como objetivo apresentar um passo a passo de como criar, configurar e publicar uma biblioteca Kotlin.

Se você gostar mesmo de ver o código, pode acessar o repositório de amostra no GitHub.

Criação do projeto

Primeiro passo instale o CLI do Gradle, conforme a documentação disponível no link. Em seguida, execute o passo a passo de criação de projetos, conforme a documentação disponível no link.

No caso da nossa proposta utilizamos os seguintes comandos:

$ gradle init

Select type of project to generate:
 1: basic
 2: application
 3: library
 4: Gradle plugin
Enter selection (default: basic) [1..4] 3

Select implementation language:
 1: C++
 2: Groovy
 3: Java
 4: Kotlin
 5: Scala
 6: Swift
Enter selection (default: Java) [1..6] 4

Select build script DSL:
 1: Groovy
 2: Kotlin
Enter selection (default: Groovy) [1..2] 2

Project name (default: demo): Minha Lib
Source package (default: demo): br.com.meudominio.meuprojeto

BUILD SUCCESSFUL
2 actionable tasks: 2 executed

Onde vamos publicar nossa biblioteca?

No nosso exemplo utilizaremos um repositório Maven para disponibilizar tanto a biblioteca quanto os códigos fontes (Quem importa a biblioteca consegue ver o código dentro do seu projeto).

Existem vários serviços e projetos open source que permitem publicar bibliotecas em repositórios Maven, como por exemplo o Archiva, Nexus e o JFrog.

Nosso objetivo era disponibilizar uma biblioteca privada, sem a necessidade de ter uma máquina dedicada na nossa infra/cloud, logo, decidimos adotar o JFrog, visto que, o plano free atenderia todas nossas necessidades.

Configuração do Gradle

Quando você cria o projeto ele vem com algumas configurações padrões, entretanto, para nosso exemplo foram realizadas algumas alterações, principalmente no arquivo /lib/build.gradle.kts.

Além das configurações padrões, foram adicionadas as tasks do Detekt (Static code analysis tool) e do Dokka (Documentation engine for Kotlin), porém, não nos aprofundaremos nas mesmas.

Variáveis de ambiente

O intuito dessas variáveis é poder ocultar as chaves de acesso do JFrog, deixando as configurações apenas no CI/CD (No nosso caso vamos utilizar o plano free do Code Magic).

Para que isso seja possível, configure as variáveis no arquivo gradle.properties, conforme abaixo.

publishingUrl=
publishingGroupId=
publishingArtifactId=
publishingVersion=
artifactoryRepoKey=
artifactoryUserName=
artifactoryPassword=

Em seguida, declare as mesmas no arquivo /lib/build.gradle.kts.

//Environment variables initialized in gradle.properties file or by command line
val publishingGroupId: String by project //Exemple value: io.github.viniciusalvesmello
val publishingArtifactId: String by project //Exemple value: kotlinlibr@arysample
val publishingVersion: String by project //Exemple value: 1.0.0
val artifactoryUrl: String by project //Exemple value: https://viniciusalvesmello.jfrog.io/artifactory
val artifactoryRepoKey: String by project //Exemple value: kotlin-library
val artifactoryUserName: String by project //Exemple value: youremail@email.com
val artifactoryPassword: String by project //Exemple value: YourPassword#9911

Adicionando as Dependências e os Plugins

Para que seja possível compilar e publicar nossa biblioteca, precisamos adicionar as informações abaixo no arquivo /lib/build.gradle.kts. Nessas configurações temos dependências, plugins do Kotlin, Java Library, Maven, JFrog, Dokka e Detekt e Tests.

buildscript {
    dependencies {
        //The build information is sent to Artifactory in json format -> https://github.com/jfrog/build-info/
        classpath("org.jfrog.buildinfo:build-info-extractor-gradle:4.29.3")
    }
}

//Plugins
plugins {
    //Plugin to add support for Kotlin.
    id("org.jetbrains.kotlin.jvm") version "1.7.21"

    //Java-library plugin for API and implementation separation.
    `java-library`

    //Maven Publish Plugin provides the ability to publish build artifacts to an Apache Maven repository -> https://docs.gradle.org/current/userguide/publishing_maven.html
    `maven-publish`

    //The Gradle Artifactory Plugin allows you to deploy your build artifacts and build information to Artifactory -> https://www.jfrog.com/confluence/display/JFROG/Gradle+Artifactory+Plugin
    id("com.jfrog.artifactory") version "4.29.3"
}

//Repositories
repositories {
    mavenCentral()
}

//Dependencies
dependencies {
    //Align versions of all Kotlin components
    implementation(platform("org.jetbrains.kotlin:kotlin-bom"))

    //Kotlin JDK 8 standard library
    implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8")

    //Kotlin test library.
    testImplementation("org.jetbrains.kotlin:kotlin-test")

    //Kotlin JUnit
    testImplementation("org.jetbrains.kotlin:kotlin-test-junit")
}

Adicionando o código fonte na biblioteca

Para que seja possível visualizar os códigos fontes nas aplicações que consomem a biblioteca precisamos adicionar os códigos fontes na task artifacts no arquivo/lib/build.gradle.kts. Aqui adicionamos tanto o código fonte da biblioteca como dos testes unitários.

//Gradle tasks setup
tasks {
    //Create Jar file with project source code
    val sourcesJar by creating(Jar::class) {
        group = "build"
        archiveClassifier.set("sources")
        from(sourceSets["main"].allSource)
    }

    //Create Jar file with tests project source code
    val testsJar by creating(Jar::class) {
        dependsOn(JavaPlugin.TEST_CLASSES_TASK_NAME)
        group = "build"
        archiveClassifier.set("tests")
        from(sourceSets["test"].output)
    }

    //Add Jar files in artifactory
    artifacts {
        add("archives", sourcesJar)
        add("archives", testsJar)
    }
}

Configurar a publicação da biblioteca para o repositório Maven

Nesse ponto, configuramos a publicação no arquivo /lib/build.gradle.kts, sendo esta responsável por criar o pacote que será enviado para o repositório Maven.

//Publication setup
publishing {
    publications {
        create<MavenPublication>("maven") {
            groupId = publishingGroupId
            artifactId = publishingArtifactId
            version = publishingVersion

            from(components["java"])
            setArtifacts(configurations.archives.get().allArtifacts)
        }
    }
}

Algumas informações do pacote virão das variáveis de ambiente, mas você pode seguir as sugestões abaixo, para preencher as mesmas:

• groupId: Nome do pacote (Ex.: io.github.viniciusalvesmello);
• artifactId: Nome da biblioteca (Ex.: kotlinlibrarysample);
• version: Versão da biblioteca (Ex.: 1.0.0).

Um ponto interessante da versão da biblioteca, é que você pode automatizar seu CI/CD e toda vez que for criada uma nova tag no git a pipeline de publicação é iniciada automaticamente. No geral, as ferramentas de CI/CD disponibilizam uma variável de ambiente que te possibilita recuperar o valor da última tag criada, facilitando assim o preenchimento da variável de ambiente publishingVersion.

No código fonte do projeto de amostra temos dois arquivos responsáveis pela automatização do processo de deploy da biblioteca. Apesar de não ser o foco desse artigo, você pode visualizar os mesmos no repositório do GitHub, sendo eles:

• Configuração do Fastlane disponível no arquivo /fastlane/Fastfile;
• Configuração do CodeMagic, que fica no arquivo codemagic.yaml.

Configurar o JFrog Artifactory

Aqui realizamos as configurações no arquivo /lib/build.gradle.kts, para que seja possível publicar a biblioteca no JFrog Artifactory.

//Artifactory setup
artifactory {
    setContextUrl(publishingUrl)

    publish(delegateClosureOf<org.jfrog.gradle.plugin.artifactory.dsl.PublisherConfig> {
        repository(delegateClosureOf<groovy.lang.GroovyObject> {
            setProperty("repoKey", artifactoryRepoKey)
            setProperty("username", artifactoryUserName)
            setProperty("password", artifactoryPassword)
        })

        defaults(delegateClosureOf<groovy.lang.GroovyObject> {
            invokeMethod("publications", publishing.publications.names.toTypedArray())
        })
    })
}

Nas configurações acima utilizamos algumas variáveis de ambiente, sendo elas:

• publishingUrl: URL do seu projeto na plataforma (Ex: https://viniciusalvesmello.jfrog.io/artifactory);
• artifactoryRepoKey: Nome da chave do repositório Maven (Ex: kotlin-library);
• artifactoryUserName: Nome do usuário responsável pelo deploy;
• artifactoryPassword: Senha do usuário responsável pelo deploy;

Código fonte da biblioteca

O código fonte da biblioteca de amostra é bem simples e contém algumas extension functions em Kotlin.

Código Fonte mais os testes unitários

Execução dos testes unitários

Como publicar a biblioteca manualmente

O comando abaixo permite publicar a biblioteca usando o terminal, sendo este, composto pelo clean que limpa o build atual e o artifactoryPublish executa um novo build e faz o deploy para o repository Maven. As demais partes do comando iniciadas com-P definem as variáveis de ambiente necessárias para o deploy.

$ ./gradlew clean artifactoryPublish -PpublishingGroupId=io.github.viniciusalvesmello -PpublishingArtifactId=kotlinlibrarysample -PpublishingVersion=1.0.0 -PartifactoryUrl=https://viniciusalvesmello.jfrog.io/artifactory -PartifactoryRepoKey=kotlin-library -PartifactoryUserName=youremail@email.com -PartifactoryPassword=YourPassword#9911

Extras

Pensando em facilitar a jornada de quem for realizar um trabalho similar, criei dois posts simples com um passo a passo de como configurar o JFrog e o CodeMagic, conforme links abaixo:

• Configurando um repositório Maven no JFrog
• Criando uma conta e configurando um projeto no CodeMagic

Agradecimentos

Gostaria de deixar aqui um agradecimento especial para o João Couto, que me apoiou no processo de aprendizado com a criação de bibliotecas, com dicas gerais, indicação de artigos, entre outros.