Skip to content

Developer Guide

Jump to bottom
Swagata Prateek edited this page Dec 6, 2022 · 2 revisions

Developer Guide

This part of the wiki talks about daily developer guidelines to work on MapLibre-Java.

Setting up the workspace

Open MapLibre-Java as it is on IntelliJ Idea. If you want to use Visual Studio Code or any other editor, use an appropriate Gradle Plugin to get you started.

How to build

The following utility libraries are hosted here:

  1. services-geojson
  2. services-turf

This repository has one root gradle projects. All the libraries are configured to be gradle sub-projects.

To see all the sub-projects, run the following:

./gradlew projects

To see all the sub-projects from gradle

To build both of the libraries, run:

./gradlew clean build

To build a specific library such as services-geojson, run

./gradlew :services-geojson:build

How to test

To run unit test of the libraries, run:

./gradlew test

To build a specific library such as services-geojson, run

./gradlew :services-geojson:test

Local publishing to Maven

To test out Maven publishing without actually publishing to maven, we can use a local publish.

Creating PGP key pair

To get started with that, the first thing we will need is a PGP key-pair. MapLibre-Java uses Gradle as build-system. Gradle's Signing Plugin requires artifact signature before publishing to anywhere.

To get started, install gpg in your machine. If you are on OSX, use brew

brew install gpg

If you are on Linux, use any of the following:

# for apt users (Ubuntu, Debian, Mint, and Kali)
sudo apt-get install gnupg 
# for yum users (CentOS, Fedora, or RHEL)
sudo yum install gnupg

After installation, give it a quick version check

You will see something like the following

$ gpg --version
gpg (GnuPG) 2.3.8
libgcrypt 1.10.1
Copyright (C) 2021 Free Software Foundation, Inc.
License GNU GPL-3.0-or-later <https://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Home: /Users/pswagata/.gnupg
Supported algorithms:
Pubkey: RSA, ELG, DSA, ECDH, ECDSA, EDDSA
Cipher: IDEA, 3DES, CAST5, BLOWFISH, AES, AES192, AES256, TWOFISH,
        CAMELLIA128, CAMELLIA192, CAMELLIA256
AEAD: EAX, OCB
Hash: SHA1, RIPEMD160, SHA256, SHA384, SHA512, SHA224
Compression: Uncompressed, ZIP, ZLIB, BZIP2

Now, we move to create a key pair locally

gpg --gen-key

This will create a public and private key pair. Go through the whole process and ensure you provide a strong passphrase. It will ask for your name and email too.

After creation of the key-pair, run the following command to list the available key-pairs. You will see something like the following:

$ gpg --list-secret-keys --keyid-format short

/Users/pswagata/.gnupg/pubring.kbx
----------------------------------
sec   ed25519/69938690 2022-12-05 [SC] [expires: 2024-12-04]
      E0DB98C067844BB435153D88F56EFE4569938690
uid         [ultimate] Swagata Prateek <[email protected]>
ssb   cv25519/1E89EA3B 2022-12-05 [E] [expires: 2024-12-04]

According to Gradle documentation, to configure the Signatory Credentials, we will require the following:

Public Key ID

The last 8 symbols of the keyId. If we look above, we listed all our available keys with gpg --list-secret-keys --keyid-format short command. In this example, the key id is 69938690 taken from ed25519/69938690 part of the text.

Passphrase

Nothing special to write here. This is the passphrase you provided when you created the key pair.

Secret Key Ring File

This is the absolute path to the secret key ring file containing your private key. Since gpg 2.1, we need to export the keys with the follwoing command

gpg --keyring /Users/pswagata/.gnupg/pubring.kbx --export-secret-keys -o ~/.gnupg/secring.gpg

This will translate the .kbx file to a .gpg file that Gradle signing plugin understands.

Using PGP key pair in local build

There are many ways to go about it. To know all the ways available, please check Gradle Signatory Credentials documentation.

We recommend creating a local.properties file in the root of the maplibre-java project. In the local.properties file, write the following content

signing.keyId=<KeyID>
signing.password=<Your Pass>
signing.secretKeyRingFile=<Secret KeyRing File>

Running local publishing

You are all set to run a local publish. To summarize a local publish does the following:

  1. Builds your artifact
  2. Creates a Maven pom file based on the project
  3. Publishes a Gradle Module
  4. Publishes the publish ready artifact to local Maven.

Run the following:

./gradlew :<project-name>:publishToMavenLocal --info

For example, for services-geojson gradle sub-project, the command will be

./gradlew :services-geojson:publishToMavenLocal --info

Now, to see the path of your local maven repo, run the following:

mvn help:effective-settings

It is usually under ~/.m2/repository/ path. You can visit it to check generated maven artifacts.

Clone this wiki locally