Skip to content

Commit

Permalink
Merge pull request #36 from Kotlin/readme_update
Browse files Browse the repository at this point in the history 
README tidying
  • Loading branch information
@adam-enko
adam-enko authored Oct 17, 2024
2 parents 0bc4fbd + 174a199 commit 4e78e03
Show file tree
Hide file tree
Showing 2 changed files with 51 additions and 42 deletions.
91 changes: 50 additions & 41 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,25 +1,23 @@
[![official project](http://jb.gg/badges/official.svg)](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub)
[![official project](http://jb.gg/badges/official.svg)](https://github.com/JetBrains#jetbrains-on-github)

# Multiplatform library template

## What is it?

It is the barebones library project intended to quickly bootstrap a Kotlin Multiplatform library, that is deployable to Maven Central.
This repository contains a simple library project, intended to demonstrate a [Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform.html) library that is deployable to [Maven Central](https://central.sonatype.com/).

It has only one function: generate the [Fibonacci sequence](https://en.wikipedia.org/wiki/Fibonacci_sequence) starting from platform-provided numbers. Also, it has a test for each platform just to be sure that tests run.
The library has only one function: generate the [Fibonacci sequence](https://en.wikipedia.org/wiki/Fibonacci_sequence) starting from platform-provided numbers. Also, it has a test for each platform just to be sure that tests run.

Note that no other actions or tools usually required for the library development are set up, such as [tracking of backwards compatibility]
(https://kotlinlang.org/docs/jvm-api-guidelines-backward-compatibility.html#tools-designed-to-enforce-backward-compatibility), explicit API mode,
licensing, contribution guideline, code of conduct and others. You can find a guide for best practices for designing Kotlin libraries [here.](https://kotlinlang.org/docs/api-guidelines-introduction.html)
Note that no other actions or tools usually required for the library development are set up, such as [tracking of backwards compatibility](https://kotlinlang.org/docs/jvm-api-guidelines-backward-compatibility.html#tools-designed-to-enforce-backward-compatibility), explicit API mode, licensing, contribution guideline, code of conduct and others. You can find a guide for best practices for designing Kotlin libraries [here](https://kotlinlang.org/docs/api-guidelines-introduction.html).

## How to publish?

This guide describes the steps of publishing a library built with Kotlin Multiplatform to the [Maven Central repository](https://central.sonatype.com/). To publish your library, you’ll need to:

* Set up credentials, including an account on Maven Central and a PGP key to use for signing
* Configure the publishing plugin in your library’s project
* Provide your credentials to the publishing plugin so it can sign and upload your artifacts
* Run the publication task, either locally or using continuous integration
* Set up credentials, including an account on Maven Central and a PGP key to use for signing.
* Configure the publishing plugin in your library’s project.
* Provide your credentials to the publishing plugin so it can sign and upload your artifacts.
* Run the publication task, either locally or using continuous integration.

This guide assumes that you are:

Expand All @@ -31,11 +29,11 @@ This guide assumes that you are:

Most of the steps here are still applicable if you’re using a different setup, but there might be some differences you need to account for. An [important limitation](https://kotlinlang.org/docs/multiplatform-publish-lib.html#host-requirements) is that Apple targets must be built on a machine with macOS.

Throughout this guide, we’ll use the [https://github.com/kotlin-hands-on/fibonacci](https://github.com/kotlin-hands-on/fibonacci) repository as an example. You can refer to the code of this repository to see how the publishing setup works. Don’t forget to **replace all example values with your own** as you’re configuring your project.
Throughout this guide, we’ll use the [https://github.com/kotlin-hands-on/fibonacci](https://github.com/kotlin-hands-on/fibonacci) repository as an example. You can refer to the code of this repository to see how the publishing setup works. You **must replace all example values with your own** as you’re configuring your project.

### Prepare accounts and credentials

#### Register a namespace {#register-a-namespace}
#### Register a namespace

Artifacts published to Maven repositories are identified by their coordinates, for example `com.example:library:1.0.0`. These coordinates are made up of three parts, separated by colons: the `groupId`, `artifactId`, and `version`.

Expand All @@ -46,27 +44,27 @@ To get started with publishing to Maven Central, sign in (or create a new accoun
**For a GitHub repository**
Using your GitHub account to create a namespace is a good option if you don’t own a domain name to use for publication. To create a namespace based on your GitHub account:

1. Enter io.github.`<your username>` as your namespace. For example, `io.github.kotlin-hands-on`.
1. Enter `io.github.<your username>` as your namespace. For example, `io.github.kotlin-hands-on`.
2. Copy the Verification Key displayed.
3. On GitHub, create a new repository with your GitHub account with the verification key as the repository’s name. For example, `http://github.com/kotlin-hands-on/ex4mpl3c0d`.
4. Navigate back to Maven Central, and click on the Verify Namespace button. After a successful verification, you can delete the repository you’ve created.
4. Navigate back to Maven Central, and click on the Verify Namespace button. After verification succeeds you can delete the repository you’ve created.

**For a domain name**
To use a domain name that you own as your namespace:

1. Enter your domain as the namespace using reverse-DNS form. If your domain is `example.com`, enter `com.example`.
1. Enter your domain as the namespace using a reverse-DNS form. If your domain is `example.com`, enter `com.example`.
2. Copy the Verification Key displayed.
3. Create a new DNS TXT record with the verification key as its contents. See [Maven Central’s FAQ](https://central.sonatype.org/faq/how-to-set-txt-record/) for more information on how to do this with various domain registrars.
4. Navigate back to Maven Central, and click on the Verify Namespace button. After a successful verification, you can delete the TXT record you’ve created.
4. Navigate back to Maven Central, and click on the Verify Namespace button. After verification succeeds you can delete the TXT record you’ve created.

#### Generate a Key Pair

Artifacts published to Maven Central [must be signed with a PGP signature](https://central.sonatype.org/publish/requirements/gpg/), which allows users to validate the origin of artifacts.

To get started with signing, you’ll need to generate a key pair:

* The **private key** is used to sign your artifacts, and should never be shared with others
* The **public key** can be used by others to validate the signature of the artifacts, and should be published
* The **private key** is used to sign your artifacts, and should never be shared with others.
* The **public key** can be used by others to validate the signature of the artifacts, and should be published.

The `gpg` tool that can manage signatures for you is available from [their website](https://gnupg.org/download/index.html). You can also install it using package managers such as [Homebrew](https://brew.sh/):

Expand All @@ -88,7 +86,7 @@ Next, you’ll be prompted to set the expiration of the key. If you choose to cr

You will be asked for your real name, email, and a comment. You can leave the comment empty.

```bash
```text
Please select what kind of key you want:
(1) RSA and RSA
(2) DSA and Elgamal
Expand All @@ -98,6 +96,7 @@ Please select what kind of key you want:
(10) ECC (sign only)
(14) Existing key from card
Your selection? 9
Please select which elliptic curve you want:
(1) Curve 25519 *default*
(4) NIST P-384
Expand All @@ -113,7 +112,7 @@ Please specify how long the key should be valid.
Key is valid for? (0) 0
Key does not expire at all
`Is this correct? (y/N) y
Is this correct? (y/N) y
GnuPG needs to construct a user ID to identify your key.
```

Expand All @@ -127,7 +126,7 @@ gpg --list-keys

The output will look something like this:

```bash
```text
pub ed25519 2024-10-06 [SC]
F175482952A225BFC4A07A715EE6B5F76620B385CE
uid [ultimate] Your name <your email address>
Expand All @@ -146,27 +145,30 @@ Run the following command to upload your public key using `gpg`, **substituting
gpg --keyserver keyserver.ubuntu.com --send-keys F175482952A225BFC4A07A715EE6B5F76620B385CE
```

#### Export your private key {#export-your-private-key}
#### Export your private key

To let your Gradle project access your private key, you’ll need to export it to a file. Use the following command, **passing in your own keyid** as a parameter. You will be prompted to enter the passphrase you’ve used when creating the key.

```bash
gpg --armor --export-secret-keys F175482952A225BFC4A07A715EE6B5F76620B385CE > key.gpg
```

This will create a `key.gpg` file which contains your private key. Remember not to share this with anyone.
This will create a `key.gpg` file which contains your private key.

> [!CAUTION]
> Never share a private key with anyone.
If you check the contents of the file, you should see contents similar to this:

```bash
```text
-----BEGIN PGP PRIVATE KEY BLOCK-----
lQdGBGby2X4BEACvFj7cxScsaBpjty60ehgB6xRmt8ayt+zmgB8p+z8njF7m2XiN
...
bpD/h7ZI7FC0Db2uCU4CYdZoQVl0MNNC1Yr56Pa68qucadJhY0sFNiB63KrBUoiO
... SQ== =Qh2r
-----END PGP PRIVATE KEY BLOCK-----
```

#### Generate the user token {#generate-the-user-token}
#### Generate the user token

Your project will also need to authenticate with Maven Central to upload artifacts. On the Central Portal, navigate to the [Account](https://central.sonatype.com/account) page, and click on *Generate User Token*.

Expand All @@ -176,7 +178,7 @@ The output will look like the example below, containing a username and a passwor
<server>
<id>${server}</id>
<username>l3nfaPmz</username>
<password<gh9jT9XfnGtUngWTZwTu/8241keYdmQpipqLPRKeDLTh</password>
<password>gh9jT9XfnGtUngWTZwTu/8241keYdmQpipqLPRKeDLTh</password>
</server>
```

Expand All @@ -189,6 +191,8 @@ If you started developing your library from a template project, this is a good t
If you have an Android target in your project, you should follow the [steps to prepare your Android library release](https://developer.android.com/build/publish-library/prep-lib-release). This, at a minimum, requires you to [specify an appropriate namespace](https://developer.android.com/build/publish-library/prep-lib-release#choose-namespace) for your library, so that a unique R class will be generated when their resources are compiled. Notice that the namespace is different from the Maven namespace created in the [Register a namespace](#register-a-namespace) section above.

```kotlin
// build.gradle.kts

android {
namespace = "io.github.kotlinhandson.fibonacci"
}
Expand All @@ -201,6 +205,8 @@ This guide uses [vanniktech/gradle-maven-publish-plugin](https://github.com/vann
To add the plugin to your project, add the following line in the plugins block, in your library module’s `build.gradle.kts` file:

```kotlin
// build.gradle.kts

plugins {
id("com.vanniktech.maven.publish") version "0.29.0"
}
Expand All @@ -211,6 +217,8 @@ plugins {
In the same file, add the following configuration. Customize all these values appropriately for your library.

```kotlin
// build.gradle.kts

mavenPublishing {
publishToMavenCentral(SonatypeHost.CENTRAL_PORTAL)

Expand All @@ -226,8 +234,8 @@ mavenPublishing {
licenses {
license {
name = "The Apache License, Version 2.0"
url = "http://www.apache.org/licenses/LICENSE-2.0.txt"
distribution = "http://www.apache.org/licenses/LICENSE-2.0.txt"
url = "https://www.apache.org/licenses/LICENSE-2.0.txt"
distribution = "https://www.apache.org/licenses/LICENSE-2.0.txt"
}
}
developers {
Expand All @@ -239,7 +247,7 @@ mavenPublishing {
}
scm {
url = "https://github.com/kotlin-hands-on/fibonacci/"
connection "scm:git:git://github.com/kotlin-hands-on/fibonacci.git"`
connection = "scm:git:git://github.com/kotlin-hands-on/fibonacci.git"
developerConnection = "scm:git:ssh://[email protected]/kotlin-hands-on/fibonacci.git"
}
}
Expand All @@ -264,6 +272,8 @@ You can set up continuous integration which builds and publishes your library fo
To get started, add the following workflow to your repository, in the `.github/workflows/publish.yml` file.

```yaml
# .github/workflows/publish.yml

name: Publish
on:
release:
Expand Down Expand Up @@ -292,11 +302,12 @@ jobs:
After committing and pushing this change, this workflow will run automatically when you create a release (including a pre-release) in the GitHub repository hosting your project. It checks out the current version of your code, sets up a JDK, and then runs the `publishToMavenCentral` Gradle task.

\> Alternatively, you could configure the workflow to [trigger when a tag is pushed](https://stackoverflow.com/a/61892639) to your repository.
\> The script above disables Gradle [configuration cache](https://docs.gradle.org/current/userguide/configuration_cache.html) for the publication task by adding `--no-configuration-cache` to the Gradle command, as the publication plugin does not support it (see this [open issue](https://github.com/gradle/gradle/issues/22779)).
\> Reminder: When using `publishToMavenCentral`, you’ll still need to check and release your deployment manually on the website, as described in the previous section. You may use `publishAndReleaseToMavenCentral` instead for a fully automated release.
> [!NOTE]
> Alternatively, you could configure the workflow to [trigger when a tag is pushed](https://stackoverflow.com/a/61892639) to your repository.
>
> The script above disables Gradle [configuration cache](https://docs.gradle.org/current/userguide/configuration_cache.html) for the publication task by adding `--no-configuration-cache` to the Gradle command, as the publication plugin does not support it (see this [open issue](https://github.com/gradle/gradle/issues/22779)).
>
> Reminder: When using `publishToMavenCentral`, you’ll still need to check and release your deployment manually on the website, as described in the previous section. You may use `publishAndReleaseToMavenCentral` instead for a fully automated release.

This action will need your signing details and your Maven Central credentials. These will be configured as GitHub Actions secrets in the next section. The configuration of the workflow above takes these secrets and places them into environment variables, which will make them available to the Gradle build automatically.

Expand All @@ -311,8 +322,6 @@ Click on the `New repository secret` button, and add the following secrets:
- `SIGNING_PASSWORD` is the passphrase you’ve provided when generating your signing key.
- `GPG_KEY_CONTENTS` should contain the contents of your GPG private key file, which you’ve created earlier in the [Export your private key](#export-your-private-key) section.

#
![](/images/github_secrets.png)

Note again that the names used for these secrets must match those used by the workflow that accesses their values.
Expand Down Expand Up @@ -341,18 +350,18 @@ The checkboxes below allow you to mark a release as a pre-release (useful for al

Click the *Publish release* button to create the new release. This will immediately show up on your GitHub repository’s main page.

Click the Actions tab on the top of your GitHub repository. Here you’ll see the new workflow that was triggered by the GitHub release. Click it to see the outputs of the publication task.
Click the Actions tab on the top of your GitHub repository. Here you’ll see the new workflow was triggered by the GitHub release. Click it to see the outputs of the publication task.

After this task completes successfully, navigate to the [Deployments](https://central.sonatype.com/publishing/deployments) dashboard. You should see a new deployment here. This deployment will be in the *pending* and *validating* states for some time while Maven Central performs checks on it.

Once your deployment moves to a *validated* state, you should see that it contains all the artifacts you’ve uploaded. If everything looks correct, click the *Publish* button to release these artifacts.

![](/images/published_on_maven_central.png)

Note that it will take some time (about 15-30 minutes, usually) after the release for the artifacts to be available publicly on Maven Central.
Note that it will take some time (about 15–30 minutes, usually) after the release for the artifacts to be available publicly on Maven Central.
Also note that the library may be available for use before they are indexed on [the Maven Central website](https://central.sonatype.com/).

There’s also another task available which both uploads and releases the artifacts automatically once the the deployment is verified, without having to manually release them on the website:
There’s also another task available which both uploads and releases the artifacts automatically once the deployment is verified, without having to manually release them on the website:

```bash
./gradlew publishAndReleaseToMavenCentral
Expand All @@ -369,4 +378,4 @@ There’s also another task available which both uploads and releases the artifa

# Other resources
* [Publishing via the Central Portal](https://central.sonatype.org/publish-ea/publish-ea-guide/)
* [Gradle Maven Publish Plugin \- Publishing to Maven Central](https://vanniktech.github.io/gradle-maven-publish-plugin/central/)
* [Gradle Maven Publish Plugin \- Publishing to Maven Central](https://vanniktech.github.io/gradle-maven-publish-plugin/central/)
2 changes: 1 addition & 1 deletion build.gradle.kts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,4 @@ plugins {
alias(libs.plugins.androidLibrary) apply false
alias(libs.plugins.kotlinMultiplatform) apply false
alias(libs.plugins.vanniktech.mavenPublish) apply false
}
}

0 comments on commit 4e78e03

Please sign in to comment.