KTX 1.9.11-b2 release. #317

.github/CONTRIBUTING.md

@@ -51,7 +51,7 @@ git checkout develop
 ### Gradle
 
 The project itself is managed by [Gradle](http://gradle.org/). Gradle wrapper is included, but you can use a local
-Gradle installation - scripts should be compatible with Gradle `5.+`. Gradle projects are handled out of the box by
+Gradle installation - scripts should be compatible with Gradle `6.+`. Gradle projects are handled out of the box by
 IntelliJ, so KTX should be relatively easy to import.
 
 Some useful Gradle tasks include:
@@ -72,7 +72,7 @@ separately usually fixes the issue.
 
 - Create folder matching module name in root of the repository. Modules should generally be named with a single word.
 When multiple words are necessary, use a single dash (`-`) as the word separator.
-- Add folder name to `settings.gradle` file. This will also serve as the project identifier that you use in
+- Add folder name to `settings.gradle.kts` file. This will also serve as the project identifier that you use in
 `build.gradle` scripts and to run individual Gradle tasks (e.g. `gradle actors:test`).
 - Create `src/main/kotlin` and `src/test/kotlin` directories in your module folder. They will be automatically marked
 as source thanks to Gradle. You should also create package structure matching `ktx/your/module` in each source folder.
@@ -83,8 +83,9 @@ projectName=ktx-your-module
 projectDesc=Description of your module as it will appear in Maven Central.
 ```
 
-- Add a `build.gradle` file. It should contain dependencies specific to your module. If there are none, you can leave it
-empty.
+- Add a `build.gradle.kts` file. It should contain dependencies specific to your module. If there are none, you can
+leave it empty. By adding `import ktx.*` at the top of this file, you will be able to access the versions of major
+dependencies of the modules as defined in the [`buildSrc`](../buildSrc) directory.
 - Add a `README.md` file describing your module. Refer to other `README.md` files for guidelines. `README.md` files
 should generally consist of the following sections:
   - _General description_ - in a single sentence, what problem does the module solve?
@@ -109,7 +110,7 @@ should generally consist of the following sections:
       - yourModule.kt
     > test/kotlin/ktx/your/module/
       - yourModuleTest.kt
-  - build.gradle
+  - build.gradle.kts
   - gradle.properties
   - README.md
 ```
@@ -120,21 +121,22 @@ The following sections are for the maintainers of the repository.
 
 ### Updating dependencies
 
-Dependencies versions are stored in the [gradle.properties](../gradle.properties) file. Snapshot releases should keep
-all of the dependencies (outside of testing scope) up-to-date. Major dependencies updating:
+Kotlin and plugin versions are stored in the [gradle.properties](../gradle.properties) file, while module dependencies
+versions are stored with the [`Versions.kt`](../buildSrc/src/main/kotlin/ktx/Versions.kt) file. Snapshot releases
+should keep all of the dependencies (outside of testing scope) up-to-date. Major dependencies include:
 
-- **LibGDX**: update `gdxVersion` in the properties file and LibGDX version in the tag on the top of the 
+- **LibGDX**: update `gdxVersion` in the versions file and LibGDX version in the tag on the top of the 
 [README.md](../README.md) file. Note that updating LibGDX also affects the KTX version and milestones, so make sure
 to update the [version.txt](../version.txt) and [milestones](https://github.com/libktx/ktx/milestones) as well.
-- **Kotlin**: update the `kotlinVersion` property and the Kotlin tag in the [README.md](../README.md).
-- **Kotlin Coroutines**: update `kotlinCoroutinesVersion` property and the tag in the
+- **Kotlin**: update the `kotlinVersion` in the properties file and the Kotlin tag in the [README.md](../README.md).
+- **Kotlin Coroutines**: update `kotlinCoroutinesVersion` in the versions file and the tag in the
 `ktx-async` [README.md](../async/README.md).
 - **Gradle**: run `gradle wrapper` in the root project folder. Make sure that the
 [Gradle wrapper properties file](../gradle/wrapper/gradle-wrapper.properties) points the `all` Gradle release under
 `distributionUrl` rather than just the binaries (`bin`).
-- **VisUI**: update `visUiVersion` in the properties file and VisUI version in the tag on the top of the 
+- **VisUI**: update `visUiVersion` in the versions file and VisUI version in the tag on the top of the 
 [vis/README.md](../vis/README.md) file.
-- **Ashley**: update `ashleyVersion` in the properties file and Ashely version in the tag on the top of the 
+- **Ashley**: update `ashleyVersion` in the versions file and Ashely version in the tag on the top of the 
 [ashley/README.md](../ashley/README.md) file.
 
 All of the major dependencies updates should be added to the [changelog](../CHANGELOG.md).
@@ -151,9 +153,9 @@ Apply `dev` label and milestone corresponding to the LibGDX version. An example
 - Create a pull request from the `develop` branch to the `master` branch. Review and merge the changes to the `master`
 branch.
 - Checkout the `master` branch. Fetch the latest changes.
-- Run `gradle build install uploadArchives closeAndPromoteRepository` to push artifacts to both _Maven Local_ and
-_Maven Central_. Note that the Maven plugin has its issues and you might need to run `gradle promoteRepository` after
-the previous task sequence (if it fails on the `closeAndPromoteRepository` task).
+- Run `gradle build publish closeAndReleaseRepository` to push artifacts to _Maven Central_. Note that the Maven plugin
+has its issues and might fail with an error, but usually the release will be successful. You can check if the staging
+repository was properly close, promoted and released at [Nexus Repository Manager](https://oss.sonatype.org/).
 - Run `gradle distZip` to prepare an archive with KTX sources, compiled binary and documentation.
 - Upload the archive to [releases](https://github.com/libktx/ktx/releases) section. The tag should be made from the
 `master` branch and its name should match the released version. Name of the release should match `KTX $libVersion`.
@@ -172,9 +174,8 @@ match the used LibGDX version followed by the `-SNAPSHOT` suffix.
 
 - Make sure that the [`version.txt`](../version.txt) ends with the `-SNAPSHOT` suffix and matches the LibGDX version
 that the library was compiled against.
-- Run `gradle build install uploadSnapshot` to push artifacts to both _Maven Local_ and _Sonatype_ snapshots repository.
-This task will do nothing if the current [version](../version.txt) is not a snapshot to avoid accidentally pushing
-a stable release.
+- Run `gradle build uploadSnapshot` to push artifacts to _Sonatype_ snapshots repository. This task will do nothing
+if the current [version](../version.txt) is not a snapshot to avoid accidentally pushing a stable release.
 
 Note that snapshots are automatically uploaded to Maven Central (Sonatype) snapshots repository after pushing
 to the `develop` branch.

.github/CONTRIBUTORS.md

@@ -67,7 +67,17 @@ Project contributors listed chronologically.
   * Author of the [Cyberpunk](https://github.com/ImXico/Cyberpunk) framework, which is another set of Kotlin LibGDX extensions.
   * Utilities for profiling, text rendering, camera updating and taking screenshots were integrated into KTX with **@ImXico** permission.
 * [@heyheyIvan](https://github.com/heyheyIvan)
-  * Contributed utilities to [graphics module](../graphics).
+  * Contributed utilities to the [graphics module](../graphics).
+* [@Divelix](https://github.com/Divelix)
+  * Contributed utilities to the [Scene2D module](../scene2d).
+* [@Rinat-Suleimanov](https://github.com/Rinat-Suleimanov)
+  * Contributed utilities to the [collections module](../collections).
+* [@Megamiun](https://github.com/Megamiun)
+  * Migrated Groovy Gradle configuration files to Kotlin.
+  * Updated the project from Gradle 5 to Gradle 6.
+  * Updated the sources documentation generator to Dokka 1.4.
+* [@deveth0](https://github.com/deveth0)
+  * Contributed utilities to the [graphics module](../graphics).
 
 ### Metrics
 

.github/workflows/build.yml

@@ -23,7 +23,7 @@ jobs:
     - name: Execution permission for Gradle wrapper
       run: chmod +x gradlew
     - name: Build
-      run: ./gradlew assemble install -x dokka -x dokkaZip
+      run: ./gradlew assemble install -x dokkaHtml -x dokkaZip
     - name: Tests
       run: ./gradlew check --continue
       env:

.github/workflows/publish-documentation.yml

@@ -14,16 +14,15 @@ jobs:
       - name: JDK setup
         uses: actions/setup-java@v1
         with:
-          java-version: 1.8
+          java-version: 1.11
       - name: Execution permission for Gradle wrapper
         run: chmod +x gradlew
       - name: Dokka
-        run: ./gradlew dokka
-      - name: Gather modules documentation
-        run: ./gradlew gatherDokkaDocumentation
+        run: ./gradlew dokkaHtmlCollector
       - name: Publish GitHub pages
         uses: JamesIves/github-pages-deploy-action@releases/v3
         with:
           ACCESS_TOKEN: ${{ secrets.accessToken }}
           BRANCH: gh-pages
-          FOLDER: build/dokka
+          FOLDER: build/dokka/htmlCollector
+          REPOSITORY_NAME: libktx/docs

CHANGELOG.md

@@ -1,5 +1,18 @@
 _See also: [the official LibGDX changelog](https://github.com/libgdx/libgdx/blob/master/CHANGES)._
 
+#### 1.9.11-SNAPSHOT
+
+- **[UPDATE]** Updated to Kotlin 1.4.10.
+- **[UPDATE]** Updated to Kotlin Coroutines 1.4.0.
+- **[UPDATE]** Updated to Gradle 6.7.
+- **[UPDATE]** Updated to Dokka 1.4.10-2.
+- **[MISC]** Groovy Gradle scripts and configuration files migrated to Kotlin.
+- **[MISC]** The generated sources documentation is vastly improved and moved to a new URL.
+- **[FEATURE]** (`ktx-collections`) Added `GdxIdentityMap` and `GdxArrayMap` aliases for LibGDX `IdentityMap` and `ArrayMap` collections.
+- **[FEATURE]** (`ktx-collections`) Added `set` operator extension method to `ArrayMap` to support square brackets assignment.
+- **[FEATURE]** (`ktx-graphics`) Added optional `Camera` and projection matrix parameters to `ShapeRenderer.use`.
+- **[FEATURE]** (`ktx-scene2d`) Added `image` builders for `NinePatch`, `TextureRegion`, `Texture` and `Drawable`.
+
 #### 1.9.11-b1
 
 - **[UPDATE]** Updated to LibGDX 1.9.11.

README.md

@@ -1,5 +1,5 @@
 [![GitHub Build](https://github.com/libktx/ktx/workflows/build/badge.svg)](https://github.com/libktx/ktx/actions?query=workflow%3Abuild)
-[![Kotlin](https://img.shields.io/badge/kotlin-1.3.72-orange.svg)](http://kotlinlang.org/)
+[![Kotlin](https://img.shields.io/badge/kotlin-1.4.10-orange.svg)](http://kotlinlang.org/)
 [![LibGDX](https://img.shields.io/badge/libgdx-1.9.11-red.svg)](https://libgdx.badlogicgames.com/)
 [![Maven Central](https://img.shields.io/maven-central/v/io.github.libktx/ktx-async.svg)](https://search.maven.org/#search%7Cga%7C1%7Cg%3A%22io.github.libktx%22)
 
@@ -75,7 +75,7 @@ in your `build.gradle` file:
 ```Groovy
 ext {
   // Update this version to match the latest KTX release:
-  ktxVersion = '1.9.11-b1'
+  ktxVersion = '1.9.11-b2'
 }
 
 dependencies {
@@ -129,7 +129,7 @@ repositories {
 
 ext {
   // Update this version to match the latest LibGDX release:
-  ktxVersion = '1.9.10-SNAPSHOT'
+  ktxVersion = '1.9.11-SNAPSHOT'
 }
 ```
 

actors/build.gradle.kts

@@ -0,0 +1,6 @@
+import ktx.*
+
+dependencies {
+  testImplementation("com.badlogicgames.gdx:gdx-backend-lwjgl:$gdxVersion")
+  testImplementation("com.badlogicgames.gdx:gdx-platform:$gdxVersion:natives-desktop")
+}

app/build.gradle.kts

@@ -0,0 +1,6 @@
+import ktx.*
+
+dependencies {
+  testImplementation("com.badlogicgames.gdx:gdx-backend-lwjgl:$gdxVersion")
+  testImplementation("com.badlogicgames.gdx:gdx-platform:$gdxVersion:natives-desktop")
+}

ashley/build.gradle.kts

@@ -0,0 +1,24 @@
+import ktx.*
+
+val junitPlatformVersion: String by project
+
+dependencies {
+  compileOnly("com.badlogicgames.ashley:ashley:$ashleyVersion")
+
+  testImplementation("org.jetbrains.spek:spek-api:$spekVersion")
+  testImplementation("org.assertj:assertj-core:$assertjVersion")
+
+  testRuntimeOnly("org.junit.platform:junit-platform-launcher:$junitPlatformVersion")
+  testRuntimeOnly("org.jetbrains.spek:spek-junit-platform-engine:$spekVersion")
+}
+
+tasks.withType<Test> {
+  testLogging {
+    showExceptions = true
+    events("FAILED", "SKIPPED")
+  }
+
+  useJUnitPlatform {
+    includeEngines("spek")
+  }
+}

assets-async/build.gradle.kts

@@ -0,0 +1,15 @@
+import ktx.*
+
+val async = project(":async")
+
+dependencies {
+  api(project(":assets"))
+  api(async)
+  compileOnly("org.jetbrains.kotlinx:kotlinx-coroutines-core:$kotlinCoroutinesVersion")
+
+  testImplementation(async.sourceSets.test.get().output)
+  testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-jdk8:$kotlinCoroutinesVersion")
+  testImplementation("com.badlogicgames.gdx:gdx-backend-headless:$gdxVersion")
+  testImplementation("com.badlogicgames.gdx:gdx-backend-lwjgl:$gdxVersion")
+  testImplementation("com.badlogicgames.gdx:gdx-platform:$gdxVersion:natives-desktop")
+}

async/README.md

@@ -1,4 +1,4 @@
-[![Kotlin](https://img.shields.io/badge/kotlin--coroutines-1.3.6-orange.svg)](http://kotlinlang.org/)
+[![Kotlin](https://img.shields.io/badge/kotlin--coroutines-1.4.0-orange.svg)](http://kotlinlang.org/)
 [![Maven Central](https://img.shields.io/maven-central/v/io.github.libktx/ktx-async.svg)](https://search.maven.org/artifact/io.github.libktx/ktx-async)
 
 # KTX: coroutines support and threading utilities

async/build.gradle.kts

@@ -0,0 +1,22 @@
+import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
+import ktx.*
+
+tasks.withType<KotlinCompile> {
+  kotlinOptions {
+    freeCompilerArgs += listOf(
+      "-Xuse-experimental=kotlinx.coroutines.ExperimentalCoroutinesApi",
+      "-Xuse-experimental=kotlinx.coroutines.InternalCoroutinesApi"
+    )
+  }
+}
+
+dependencies {
+  compileOnly("org.jetbrains.kotlinx:kotlinx-coroutines-core:$kotlinCoroutinesVersion")
+
+  testImplementation("com.badlogicgames.gdx:gdx-backend-headless:$gdxVersion")
+  testImplementation("com.badlogicgames.gdx:gdx-backend-lwjgl:$gdxVersion")
+  testImplementation("com.badlogicgames.gdx:gdx-platform:$gdxVersion:natives-desktop")
+  testImplementation("me.alexpanov:free-port-finder:1.0") // Version unlikely to change, not parametrized.
+  testImplementation("com.github.tomakehurst:wiremock:$wireMockVersion")
+  testImplementation("org.slf4j:slf4j-nop:$slf4jVersion")
+}

async/src/main/kotlin/ktx/async/dispatchers.kt

@@ -33,7 +33,7 @@ interface KtxDispatcher : CoroutineContext, Delay {
     schedule(delaySeconds = timeMillis.toSeconds()) { continuation.resume(Unit) }
   }
 
-  override fun invokeOnTimeout(timeMillis: Long, block: Runnable): DisposableHandle {
+  override fun invokeOnTimeout(timeMillis: Long, block: Runnable, context: CoroutineContext): DisposableHandle {
     val task = schedule(delaySeconds = timeMillis.toSeconds()) { execute(block) }
     return DisposableTimerTask(task)
   }

async/src/test/kotlin/ktx/async/dispatchersTest.kt

@@ -9,6 +9,7 @@ import java.util.concurrent.CompletableFuture
 import java.util.concurrent.atomic.AtomicBoolean
 import java.util.concurrent.atomic.AtomicInteger
 import java.util.concurrent.atomic.AtomicLong
+import kotlinx.coroutines.GlobalScope
 import kotlinx.coroutines.Runnable
 import kotlinx.coroutines.async
 import kotlinx.coroutines.launch
@@ -88,7 +89,7 @@ abstract class CoroutineDispatcherTest : AsyncTest() {
     // When:
     tested.invokeOnTimeout(50L, Runnable {
       executionTime.set(System.currentTimeMillis() - start)
-    })
+    }, GlobalScope.coroutineContext)
 
     // Then:
     delay(100L)
@@ -97,13 +98,13 @@ abstract class CoroutineDispatcherTest : AsyncTest() {
 
   @Test
   fun `should support timeout task cancellation`() {
-    // Note: normally you'd use withTimeout in coroutine scope to execute tasks with timout.
+    // Note: normally you'd use withTimeout in coroutine scope to execute tasks with timeout.
     // This tests the internal invokeOnTimeout API.
 
     // Given:
     val tested = tested
     val executed = AtomicBoolean()
-    val handle = tested.invokeOnTimeout(50L, Runnable { executed.set(true) })
+    val handle = tested.invokeOnTimeout(50L, Runnable { executed.set(true) }, GlobalScope.coroutineContext)
 
     // When:
     handle.dispose()

box2d/build.gradle.kts

@@ -0,0 +1,6 @@
+import ktx.*
+
+dependencies {
+  compileOnly("com.badlogicgames.gdx:gdx-box2d:$gdxVersion")
+  testImplementation("com.badlogicgames.gdx:gdx-box2d-platform:$gdxVersion:natives-desktop")
+}