Gradle’ı Anlamak (Plugins) - Jendrik Johannes (ÇEVİRİ) PART 3

Serinin Diğer İçerikleri:

Diğer içerikleri görüntülemek için linke tıklayın.

Benim Notum: Gradle Plugin Türleri Nelerdir?

3 farklı plugin dağıtım türü var demiştik. Bununla beraber Gradle’da iki genel plugin türü vardır: binary plugins ve script plugins. ²

• “Binary plugins”, Plugin arayüzü uygulanarak (implementing the Plugin interface) programlı olarak veya Groovy veya Kotlin DSL’deki deklarasyonlar aracılığıyla yazılır. Bir “build script”‘de, proje hiyerarşisi içinde veya harici olarak bir plugin jar’da bulunabilirler.

• “Script plugins”, build’i ayrıca yapılandıran ve genellikle build’i manipüle etmek için deklaratif bir yaklaşım uygulayan ek “build scripts”‘lerdir. Genellikle bir build içinde kullanılırlar ancak harici hale getirilebilir ve uzaktan erişilebilirler.

Bir plugin genellikle bir script plugin olarak başlar (çünkü yazılması kolaydır). Daha sonra, kod daha değerli hale geldikçe, kolayca test edilebilecek ve birden fazla proje veya kuruluş arasında paylaşılabilecek bir binary plugin’e taşınır.

Benim Notum: settings.gradle

Görüldüğü üzere Gradle Plugin Portal burada tanımlanıyor.

1
2
3
4
5
6
7
pluginManagement{
    repositories {
        gradlePluginPortal() // Artifact Repository
        ...
    }
    ....
}

Başka bir Not: Bir “Settings” script’i, hem Groovy hem de Kotlin dillerinde özel bir kısayol olan “{ …​ }” ifadesini sıklıkla kullanan, Gradle API’sine yapılan bir dizi yöntem çağrısıdır. “{ }” bloğuna Kotlin’de lambda veya Groovy’de closure adı verilir.

Basitçe söylemek gerekirse, “plugins{ }” bloğu, bir Kotlin lambda nesnesinin veya Groovy closure nesnesinin argüman olarak iletildiği bir yöntem çağrısıdır. “plugins{ }” bloğu, bunun kısa şeklidir: ³

1
2
3
plugins(function() {
    id("plugin")
})

Bloklar Gradle API yöntemleriyle haritalanır. Fonksiyonun içindeki kod, Kotlin lambda’da “receiver”, Groovy closure’da da “delegate” olarak adlandırılan “this” nesnesine karşı yürütülür. Gradle doğru “this” nesnesini belirler ve karşılık gelen doğru yöntemi çağırır. Yöntem çağrısı id("plugin")‘nin this nesnesi “PluginDependegencySpec” türündedir.

Settings dosyası, DSL’lerin üzerine inşa edilmiş Gradle API çağrılarından oluşur. Gradle, script’i yukarıdan aşağıya satır satır yürütür.

Benim Notum:

1
2
3
4
5
kotlin { //this: KotlinJvmProjectExtension

}

• kotlin {} yapılandırma bloğu, Kotlin community plugin uygulandığında yüklenen çok yararlı bir uzantı (extension) işlevidir.

• Bir task, sınıfları derlemek veya javadoc oluşturmak gibi bir build için tek bir atomik çalışma parçasını temsil eder.

• useJUnitPlatform() : JUnit Platform tabanlı testleri keşfedip ve uygular. ⁴

Benim Notum: Plugin'leri kullanma

Bir eklentide kapsüllenmiş (encapsulated) yapı mantığını (build logic) kullanmak için Gradle’ın iki adım gerçekleştirmesi gerekir. Önce eklentiyi çözmesi (resolve the plugin), ardından eklentiyi hedefe, genellikle bir Projeye uygulaması (apply the plugin) gerekir.

Bir eklentiyi çözmek (yani, resolve the plugin), belirli bir eklentiyi içeren jar’ın doğru sürümünü bulmak ve onu script sınıf yoluna (script classpath) eklemek anlamına gelir. Bir eklenti çözüldüğünde, API’si bir build script’te kullanılabilir. Hatırlayacağınız üzere 2 tür plugin vardı. Bunlardan biri script plugin, diğeri ise binary plugin’di. Script plugin’ler, uygulanırken (apply) sağlanan belirli dosya yolu (specific file path) veya URL’den çözümlenmeleri (resolved) bakımından “kendi kendine çözümlenir (yani self-resolving‘dir)”. Bununla beraber Gradle dağıtımının bir parçası olarak sağlanan core binary plugin’ler otomatik olarak çözülür.

Bir eklenti uygulamak (applying a plugin), eklenti ile geliştirmek istediğiniz Projede eklentinin Plugin.apply(T) öğesini yürütmek anlamına gelir.

Eklentileri tek bir adımda çözmek ve uygulamak için DSL eklentileri (plugins DSL) önerilir.

Benim Notum:

Önceden derlenmiş komut dosyası eklentisi (precompiled script plugin) adlarının iki önemli sınırlaması vardır:

• org.gradle ile başlayamazlar.
• Yerleşik bir plugin kimliğiyle aynı isme sahip olamazlar. Bu, precompiled script plugin’lerin sessizce göz ardı edilmemesini sağlar. ⁵

Benim Notum: Dile özgü kaynak dosyalarını ayırma (Separate language-specific source files)

Bağımsız projeler (standalone projects) olarak yazılan pluginlere ek olarak Gradle, Groovy veya Kotlin DSL’lerinde önceden derlenmiş komut dosyası eklentileri (precompiled script plugins) olarak yazılmış build logic sağlamanıza da olanak tanır. Bunları “src/main/groovy” dizinine *.gradle dosyaları veya “src/main/kotlin” dizinine *.gradle.kts dosyaları olarak yazıyorsunuz.

Gradle’ın dil eklentileri (language plugins), kaynak (source) kodunu keşfetmeye ve derlemeye yönelik kurallar oluşturur. Örneğin, Java eklentisini (java plugin) uygulayan bir proje, kodu otomatik olarak src/main/java dizininde derleyecektir. Diğer dil eklentileri de aynı modeli izler. Dizin yolunun son kısmı genellikle kaynak dosyaların beklenen dilini gösterir.

Aşağıdaki kaynak ağacı (source tree) Java ve Kotlin kaynak dosyalarını içerir. Java kaynak dosyaları src/main/java‘da yaşarken, Kotlin kaynak dosyaları src/main/kotlin‘de yaşar. ⁶

1
2
3
4
5
6
7
8
.
├── build.gradle.kts
└── src
    └── main
        ├── java
        │   └── HelloWorld.java
        └── kotlin
            └── Utils.kt

Benim Notum:

Benim Notum:

Bu durumla ilgili Jendrik’e, neden kotlin dizini altında, my-java-library.gradle.kts script’i içindeki kotlin plugin deklarasyonunu version numarası belirtmeden gerçekleştirdik, şeklinde bir soru yönelttim.

O da, gradle’ın bu durumu henüz iyi bir şekilde belgelendirmediğini ifade etti. Aslında yukarıdaki şekilde bu durumu izah etmeye çalıştığını da belirtti.

“convention” eklentilerinizde, tıpkı core Gradle eklentilerini kullandığınız gibi, “Gradle Plugin Portalı”ndaki “community” eklentileri gibi diğer kaynaklardan gelen harici eklentileri kullanabilirsiniz. (Core Gradle eklentileri, ‘java-library’ veya ‘application’ gibi Gradle ile birlikte verilen eklentilerdir. Sırf bu yüzden versiyon numarası belirtilmesine gerek yoktur.)

Ayrı bir “build logic“‘e sahip olduğunuzda (build/project), diğer Gradle projelerinde olduğu gibi Gradle’ın bağımlılık yönetimi (dependency management) mekanizmalarını kullanırsınız. Harici eklentiler (external plugins) veya daha iyisi eklentileri içeren jar’lar, daha sonra build logic projesinin build.gradle.kts dosyasında tanımladığınız projenin bağımlılıkları (dependencies) haline gelir. Bu örnekte, build.gradle.kts dosyası içinde elimizde:

1
2
3
dependencies {
    implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:1.5.21")
}

var.

Makalenin başında gösterdiğimiz “kısa notasyon (short notation) yani id("org.jetbrains.kotlin.jvm") version "1.5.21", “harici eklentileri (external plugins)” doğrudan projenizin “build.gradle.kts” dosyasında bir “build Logic” projesi olmadan kullanmak için kullanılabilir. Ama buradaki gibi ayrı bir build logic mantığı kullandığımızda, “java-plugins/src/main/kotlin/*.gradle.kts” dosyalarının içinde id("org.jetbrains.kotlin.jvm") şeklinde, sürüm numarası olmadan kullanılması gerekir. Sürüm yerine java-plugins/build.gradle.kts dosyasında, eklentiyi içeren jar’a bağımlılık (dependency) tanımlarsınız. Bu durumda az önce belirttiğimiz kod bloğu bu sorunu çözecektir. Yani;

1
2
3
dependencies {
    implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:1.5.21")
}

Dikkat ederseniz, bu eklenti (kotlin-gradle-plugin) Gradle çekirdeğinde (core) doğrudan bulunmadığından, Gradle’a eklentiyi içeren jar’ı build time’da kullanılabilir hale getirmesini söylemek için “my-build-logic/java-plugins” projenizin “build” dosyasına bir bağımlılık (dependency) eklemeniz gerekir.

Benim Notum: Plugin Dağıtım Türleri Hakkında

Jendrik, plugin dağıtım türlerinin sınıflandırılması ile ilgili şunlara da değinmektedir.

Kategorik olarak plugin dağıtım türlerini 3 bölüme ayırmak yeni başlayanlar için bilinmesi yeterlidir. Ama bunu detaylandırmak da mümkündür. Daha derine inersek, sınıflandırmak için kullanabileceğiniz birkaç boyut vardır. ⁷

1. İlk olarak, bir eklentiyi nasıl uyguladığınızın teknik boyutu var. Burada zaten birkaç seçeneğiniz var:
   1. (a) Eklentiyi, Plugin<Project> implement eden bir sınıf olarak uygulayın ve sonrasında onu build dosyasına kaydedin - burada tüm JVM dillerini seçebilirsiniz - yani, Java, Kotlin, Groovy, Scala’da uygulayabilirsiniz.
   2. (b) Eklentiyi, daha az gürültülü olan ve size daha fazla kolaylık sağlayan “önceden derlenmiş komut dosyası eklentileri (pre-compiled script plugins)” olarak uygulayın (kısacası bu içerikte anlatılan convention eklentiler gibi). Yani Eklentiyi .gradle veya .gradle.kts script olarak yazarsınız - bu daha sonra Kod’a “derlenir”, böylece çalışma zamanında Gradle, (a) ve (b) seçenekleri arasında hiçbir fark görmez.
2. İkincisi, plugini nereye koyduğunuzun ve build’inizde nereden “tükettiğinizin (consume)” boyutu vardır. Bunu söyleyeceğimiz birçok kategoriye ayırabilirsiniz. Ancak sonuçta en büyük fark versiyonlamadır. İçerikteki 3 kategoriye geri dönülen yer de burasıdır:
   1. Gradle çekirdeğinden (gradle core) eklenti tüketin (consume) (sürüm gerekmez, ancak eklenti binary’dir ve değiştirilemez).
   2. Eklentiyi bir repodan (repository) (portaldan veya private bir repodan veya MavenCentral gibi başka bir genel repodan) tüketin (consume), burada eklentinin sürümünü (version) belirlemeniz gerekir ve plugin’i tüketirken, ilgili sürümü, tüketen build’in herhangi bir yerinde tanımlamanız gerekir.
   3. Eklentiyi başka bir yerel(local) build’den tüketin (bu içerikteki my-build-logic). Burada bir sürüme (version) ihtiyacınız yok çünkü Gradle her zaman en son durumu (state’i) kullanır. Ancak burada, build üzerinde çalışırken eklentiyi istediğiniz gibi değiştirebilirsiniz.
3. Üçüncüsü, “Konvansiyon Eklentisi (Convention Plugin)” (yani, yalnızca bir takım şeyleri yapılandıran eklenti) ile “Build Logic Ekleyen Eklenti” (yani Kotlin, Android veya Spring Boot Eklentileri vb. gibi bir eklenti.) arasında kavramsal bir ayrım vardır. Ama burada da ayrım akışkandır. Şunu söyleyebilirsiniz: Yeni Task’lar (Transform’lar veyahut Action’lar) uygulamadığınız sürece bu bir convention’dır. Ya da şöyle diyebilirsiniz: “Yerel (local)” tuttuğum bir şey olduğu sürece bu bir convention’dır, çünkü zaten var olan şeylerin etrafında “küçük şeyler” inşa ediyorum. Bu yüzden, tüm bunları 3 kategoriye indirgeme düşüncem; Bir projeye başladığınızda çoğunlukla standart yapıyı takip etmeniz ve alışılagelmiş eklentileri kullanmanız yönündeydi, yani;
   1. core plugin’leri kullanın
   2. Portaldaki topluluk eklentilerini (community plugins) kullanın ve bunların sürümlerinin (versions) olduğunun farkında olmanız gerekir.
   3. build yapılandırmanızı düzenlemek için kendi küçük eklentilerinizi yazın - ve bunun için “önceden derlenmiş komut dosyası eklentileri (yani pre-compiled script plugins)” kullanımı en iyi/en kolay olanlardır.

Gradle’ın bir parçası oldukları için ‘çekirdek eklentiler (core plugins)’ yazamazsınız. Diğer tüm eklentiler kavramsal olarak aynıdır. Yani, bir “Topluluk eklentisi (community plugin)”, yayınlanan (published) ve bir sürümü (version) olan bir eklentidir. Bu tanımla, bu örnekte yazdığımız tipteki eklentiler (yani convention/local/custom olanlar), şayet onları yayınlarsanız (yani bir platformda publish ederseniz) “topluluk eklentileri (community plugins)” haline gelir (belki de onlara “yayınlanmış eklentiler (‘published plugins)” demek daha iyi bir seçim olurdu).