Merge pull request #8 from aSemy/update/readme

Update README with Kotlin Multiplatform info, add Contributing guide with lockfile instructions

CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing to UrlEncoder
+
+First and foremost, thank you for your interest in contributing! Here's a brief guide on how to contribute to the
+UrlEncoder project.
+
+## Getting Started
+
+1. Fork the repository.
+2. Clone your fork locally.
+3. Create a new branch for your feature or bugfix.
+
+## Updating Dependencies
+
+To support deterministic builds, and to help with dependency analysis tools like Snyk, UrlEncoder uses lockfiles
+to ensure consistent dependencies. Whenever a dependency is updated the lockfiles must be updated.
+
+### Gradle Lock Files
+
+Gradle's [dependency lockfiles](https://docs.gradle.org/current/userguide/dependency_locking.html)
+can be updated by running
+
+```bash
+./gradlew resolveAndLockAllDependencies --write-locks
+```
+
+### Kotlin/JS Lockfile
+
+The Kotlin/JS target 
+[also uses a lockfile](https://kotlinlang.org/docs/js-project-setup.html#version-locking-via-kotlin-js-store),
+which is managed by Yarn. 
+
+To update the Kotlin/JS lockfile, run
+
+```bash
+./gradlew kotlinNpmInstall
+```

README.md

@@ -10,7 +10,7 @@
 
 # URL Encoder for Kotlin
 
-A simple defensive library to encode/decode URL components.
+UrlEncoder is a simple defensive Kotlin Multiplatform library to encode/decode URL components.
 
 This library was adapted from the [RIFE2 Web Application Framework](https://rife2.com).  
 A pure Java version can also be found at [https://github.com/gbevin/urlencoder](https://github.com/gbevin/urlencoder).
@@ -51,19 +51,34 @@ UrlEncoder.decode("foo+bar", plusToSpace = true) // -> foo bar
 
 To use with [Gradle](https://gradle.org/), include the following dependency in your build file:
 
-```gradle
+```kotlin
 repositories {
     mavenCentral()
-    maven { url = uri("https://oss.sonatype.org/content/repositories/snapshots") } // only needed for SNAPSHOT
+    // only needed for SNAPSHOT
+    maven("https://oss.sonatype.org/content/repositories/snapshots") { 
+      name = "SonatypeSnapshots"
+      mavenContent { snapshotsOnly() }
+    }
 }
 
 dependencies {
-    implementation("net.thauvin.erik:urlencoder:1.3.0")
+    implementation("net.thauvin.erik:urlencoder-lib:1.3.0")
 }
 ```
 
-Instructions for using with Maven, Ivy, etc. can be found
-on [Maven Central](https://maven-badges.herokuapp.com/maven-central/net.thauvin.erik/urlencoder-jvm).
+Adding a dependency in [Maven](https://maven.apache.org/) requires specifying the JVM variant by adding a `-jvm` suffix
+to the artifact URL.
+
+```xml
+<dependency>
+    <groupId>net.thauvin.erik</groupId>
+    <artifactId>urlencoder-lib-jvm</artifactId>
+    <version>1.3.0</version>
+</dependency>
+```
+
+Instructions for using with Maven, Ivy, etc. can be found on 
+[Maven Central](https://search.maven.org/artifact/net.thauvin.erik/urlencoder).
 
 ## Standalone usage
 
@@ -127,7 +142,7 @@ foo+%2Bbar
 Trying to decode it with [Spring](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/util/UriUtils.html#decode(java.lang.String,java.lang.String)), for example:
 
 ```kotlin
-UriUtils.decode(u, StandardCharsets.UTF_8))
+UriUtils.decode(u, StandardCharsets.UTF_8)
 ```
 
 would return:

gradle.lockfile

@@ -5,5 +5,14 @@ org.freemarker:freemarker:2.3.30=koverJvmReporter
 org.jetbrains.intellij.deps:coverage-report:1.0.19=koverJvmReporter
 org.jetbrains.intellij.deps:intellij-coverage-agent:1.0.721=koverJvmAgent,koverJvmReporter
 org.jetbrains.intellij.deps:intellij-coverage-reporter:1.0.721=koverJvmReporter
+org.jetbrains.intellij.deps:trove4j:1.0.20200330=kotlinKlibCommonizerClasspath
+org.jetbrains.kotlin:kotlin-compiler-embeddable:1.9.0=kotlinKlibCommonizerClasspath
+org.jetbrains.kotlin:kotlin-daemon-embeddable:1.9.0=kotlinKlibCommonizerClasspath
+org.jetbrains.kotlin:kotlin-klib-commonizer-embeddable:1.9.0=kotlinKlibCommonizerClasspath
+org.jetbrains.kotlin:kotlin-reflect:1.6.10=kotlinKlibCommonizerClasspath
+org.jetbrains.kotlin:kotlin-script-runtime:1.9.0=kotlinKlibCommonizerClasspath
+org.jetbrains.kotlin:kotlin-stdlib-common:1.9.0=kotlinKlibCommonizerClasspath
+org.jetbrains.kotlin:kotlin-stdlib:1.9.0=kotlinKlibCommonizerClasspath
+org.jetbrains:annotations:13.0=kotlinKlibCommonizerClasspath
 org.jetbrains:annotations:16.0.2=koverJvmReporter
 empty=koverExternalArtifacts

gradle.properties

@@ -7,3 +7,5 @@ org.gradle.welcome=never
 # enableKgpDependencyResolution provides a smoother import experience in multiplatform projects
 # https://kotlinlang.org/docs/whatsnew1820.html#preview-of-gradle-composite-builds-support-in-kotlin-multiplatform
 kotlin.mpp.import.enableKgpDependencyResolution=true
+# hide warning "Some Kotlin/Native targets cannot be built on this mingw_x64 machine and are disabled"
+kotlin.native.ignoreDisabledTargets=true

gradlew

@@ -83,7 +83,8 @@ done
 # This is normally unused
 # shellcheck disable=SC2034
 APP_BASE_NAME=${0##*/}
-APP_HOME=$( cd "${APP_HOME:-./}" && pwd -P ) || exit
+# Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036)
+APP_HOME=$( cd "${APP_HOME:-./}" > /dev/null && pwd -P ) || exit
 
 # Use the maximum available, or set MAX_FD != -1 to use that value.
 MAX_FD=maximum

settings.gradle.kts

@@ -17,6 +17,60 @@ dependencyResolutionManagement {
       name = "Sonatype Snapshots"
       mavenContent { snapshotsOnly() }
     }
+
+    // Declare the Node.js & Yarn download repositories
+    exclusiveContent {
+      forRepository {
+        ivy("https://nodejs.org/dist/") {
+          name = "Node Distributions at $url"
+          patternLayout { artifact("v[revision]/[artifact](-v[revision]-[classifier]).[ext]") }
+          metadataSources { artifact() }
+          content { includeModule("org.nodejs", "node") }
+        }
+      }
+      filter { includeGroup("org.nodejs") }
+    }
+
+    exclusiveContent {
+      forRepository {
+        ivy("https://github.com/yarnpkg/yarn/releases/download") {
+          name = "Yarn Distributions at $url"
+          patternLayout { artifact("v[revision]/[artifact](-v[revision]).[ext]") }
+          metadataSources { artifact() }
+          content { includeModule("com.yarnpkg", "yarn") }
+        }
+      }
+      filter { includeGroup("com.yarnpkg") }
+    }
+
+    // workaround for https://youtrack.jetbrains.com/issue/KT-51379
+    exclusiveContent {
+      forRepository {
+        ivy("https://download.jetbrains.com/kotlin/native/builds") {
+          name = "Kotlin Native"
+          patternLayout {
+            // example download URLs:
+            // https://download.jetbrains.com/kotlin/native/builds/releases/1.7.20/linux-x86_64/kotlin-native-prebuilt-linux-x86_64-1.7.20.tar.gz
+            // https://download.jetbrains.com/kotlin/native/builds/releases/1.7.20/windows-x86_64/kotlin-native-prebuilt-windows-x86_64-1.7.20.zip
+            // https://download.jetbrains.com/kotlin/native/builds/releases/1.7.20/macos-x86_64/kotlin-native-prebuilt-macos-x86_64-1.7.20.tar.gz
+            listOf(
+              "macos-x86_64",
+              "macos-aarch64",
+              "osx-x86_64",
+              "osx-aarch64",
+              "linux-x86_64",
+              "windows-x86_64",
+            ).forEach { os ->
+              listOf("dev", "releases").forEach { stage ->
+                artifact("$stage/[revision]/$os/[artifact]-[revision].[ext]")
+              }
+            }
+          }
+          metadataSources { artifact() }
+        }
+      }
+      filter { includeModuleByRegex(".*", ".*kotlin-native-prebuilt.*") }
+    }
   }
 }
 

urlencoder-app/build.gradle.kts

@@ -19,6 +19,8 @@ import org.jetbrains.dokka.gradle.DokkaTask
 
 plugins {
     buildsrc.conventions.lang.`kotlin-multiplatform-jvm`
+    buildsrc.conventions.lang.`kotlin-multiplatform-js`
+    buildsrc.conventions.lang.`kotlin-multiplatform-native`
     buildsrc.conventions.publishing
     id("application")
     id("com.github.ben-manes.versions")

urlencoder-lib/build.gradle.kts

@@ -19,6 +19,8 @@ import org.jetbrains.dokka.gradle.DokkaTask
 
 plugins {
     buildsrc.conventions.lang.`kotlin-multiplatform-jvm`
+    buildsrc.conventions.lang.`kotlin-multiplatform-js`
+    buildsrc.conventions.lang.`kotlin-multiplatform-native`
     buildsrc.conventions.publishing
     id("com.github.ben-manes.versions")
 }