Skip to content

Commit

Permalink
build: maven central release (#24)
Browse files Browse the repository at this point in the history
  • Loading branch information
@bluestreak01
bluestreak01 authored Mar 9, 2023
1 parent 69d1cfa commit c6c743f
Show file tree
Hide file tree
Showing 9 changed files with 365 additions and 106 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/build.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,5 +42,5 @@ jobs:
run: mvn test

- name: Running the example
run: java -cp "./rust-maven-example/target/rust-maven-example-1.0.0-SNAPSHOT.jar${{ matrix.path-sep }}./jar-jni/target/jar-jni-1.0.0-SNAPSHOT.jar" io.questdb.example.rust.Main
run: java -cp "./rust-maven-example/target/*${{ matrix.path-sep }}./jar-jni/target/*" io.questdb.example.rust.Main

54 changes: 54 additions & 0 deletions DEV_NOTES.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# Developer's Notes

## Building

To build the project and run the example:

```shell
git clone https://github.com/questdb/rust-maven-plugin.git
cd rust-maven-plugin
mvn clean package
java -cp "./rust-maven-example/target/*:./jar-jni/target/*" io.questdb.example.rust.Main
```

_(Substituting `:` for `;` if developing on Windows)_

## Testing Against Another Project

To test your changes against another project you need to install
the `jar-jni` and `rust-maven-plugin` artifacts locally in your Maven cache:

```shell
cd jar-jni
mnv clean install
cd ../rust-maven-plugin
mvn clean install
```

## Cutting a new release

### Maven Upload

To cut a new release and upload to Maven Central, run:

```
mvn -B release:prepare release:perform
```

Here the `-B` flag will bump up the release version automatically.
The bump is a patch release, e.g. `1.0.1` to `1.0.2`.

For full docs, see https://maven.apache.org/maven-release/maven-release-plugin/examples/prepare-release.html.

### Updating `README.md`.

The documentation in `README.md` mentions the version explicitly.

To update it and discourage the use of old versions, run the
`update_doc_version.py` script.

```
python3 update_doc_version.py
```

This will make changes without checking them in.
78 changes: 41 additions & 37 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,8 +35,8 @@ $ mvn clean package
For your convenience, we've also made `jar-jni` available:
An optional Java library to load JNI dynamic libraries from JARs.

Both the plugin and the library support a directory naming convention structure to support compiling
for a multitude of platforms.
Both the plugin and the library support a common directory naming convention
to organize and find compiled artifacts for a multitude of platforms.

# Complete Example
See the [`rust-maven-example`](rust-maven-example/) directory for a working
Expand All @@ -58,7 +58,7 @@ Edit your `pom.xml` to add the plugin:
<build>
<plugins>
<plugin>
<groupId>io.questdb</groupId>
<groupId>org.questdb</groupId>
<artifactId>rust-maven-plugin</artifactId>
<version>1.0.0-SNAPSHOT</version>
<executions>
Expand Down Expand Up @@ -142,6 +142,9 @@ Accepted values are:
The plugin can be configured to build in release mode by setting
`<release>true</release>` in the `<configuration>` block.

Building `--release` will cut down binary size considerably and should be taken
into consideration when shipping binaries in `.jar` files.

## Specifying Crate Features

The equivalent of `cargo build --features feat1,feat2,feat3` is
Expand All @@ -157,6 +160,30 @@ The equivalent of `cargo build --features feat1,feat2,feat3` is
You can also specify `--all-features` via `<all-features>true</all-features>` and `--no-default-features`
via `<no-default-features>true</no-default-features>`.

Note that you can drive features with maven profiles by introducing variables.

```xml
<!-- in the plugin configuration -->
<features>
<feature>$rustFeature1</feature>
<feature>$rustFeature2</feature>
</features>
```

```xml
<!-- in the profiles section -->
<profile>
<id>feat-ssl</id>
<properties>
<rustFeature1>ssl</rustFeature1>
<rustFeature1>use-rustls</rustFeature1>
</properties>
</profile>
```

Then building with `mvn package -P feat-ssl` will call
`cargo build --features ssl,use-rustls`.

## Additional cargo arguments

Additional arguments to can go in the `<extra-args>` configuration section.
Expand Down Expand Up @@ -190,8 +217,8 @@ directory, via `cargo build --target-dir ...`.
# De-duplicating build directories when invoking `cargo build` without Maven

If you (or your IDE) end up invoking `cargo build` on your Rust crate without
the plugin, you'll notice this creates a duplicate `target` dir that will not
be cleaned at the next `mvn clean`.
the plugin, you'll notice this creates a duplicate `target` dir, inside the
crate's directory, that will not be cleaned at the next `mvn clean`.

To avoid this duplicate `target` directory problem, consider adding
`.cargo/config.toml` files configured to match the `--target-dir` argument
Expand All @@ -202,9 +229,10 @@ from the `str-reverse` crate in the example.

# Bundling binaries in the `.jar` file

The `<copyTo>` configuration allows copying the binaries anywhere. The example
however choses to copy them to `${project.build.directory}/classes/...`.
Anything placed there gets bundled in the JAR file.
The `<copyTo>` configuration (as shown in the example) allows copying the
binaries any path. The example however choses to copy them to
`${project.build.directory}/classes/...`. Anything placed there gets bundled
into the JAR file.
The `classes` directory sits within the `target` directory and outside of the
source tree.

Expand Down Expand Up @@ -238,13 +266,13 @@ code when you need to.
<build>
<plugins>
<plugin>
<groupId>io.questdb</groupId>
<groupId>org.questdb</groupId>
<artifactId>rust-maven-plugin</artifactId>
<version>1.0.0-SNAPSHOT</version>
...
```

You can then enable the profile in Maven via `mvn clean package -Prust ...`.
You can then enable the profile in Maven via `mvn clean package -P rust ...`.

## Supporting Multiple Platforms

Expand Down Expand Up @@ -273,7 +301,7 @@ The `jar-jni` library is configured as so:
...
<dependencies>
<dependency>
<groupId>io.questdb</groupId>
<groupId>org.questdb</groupId>
<artifactId>jar-jni</artifactId>
<version>1.0.0-SNAPSHOT</version>
</dependency>
Expand Down Expand Up @@ -319,29 +347,5 @@ JarJniLoader.loadLib(

If you want to talk to us, we're on [Slack](https://slack.questdb.io/).

## Building

To build the project and run the example:

```shell
git clone https://github.com/questdb/rust-maven-plugin.git
cd rust-maven-plugin
mvn clean package
java -cp "./rust-maven-example/target/rust-maven-example-1.0.0-SNAPSHOT.jar:./jar-jni/target/jar-jni-1.0.0-SNAPSHOT.jar" io.questdb.example.rust.Main
```

## Testing Against Another Project

For test your changes against another project you need to install the `jar-jni` and `rust-maven-plugin` artifacts locally in your Maven cache:

```shell
cd jar-jni
mnv clean install
cd ../rust-maven-plugin
mvn clean install
```

## Thanks to

* OktaDev for covering custom Maven plugins on YouTube https://www.youtube.com/watch?v=wHX4j0z-sUU - It's a great introduction to Maven plugins.
* The CMake maven plugin project https://github.com/cmake-maven-project/cmake-maven-project for inspiration.
Also read the [Developer's Notes](DEV_NOTES.md) with instructions on building
and running from source.
108 changes: 89 additions & 19 deletions jar-jni/pom.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,11 +22,10 @@
~
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->

<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>io.questdb</groupId>
<groupId>org.questdb</groupId>
<artifactId>jar-jni</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>jar</packaging>
Expand All @@ -52,19 +51,9 @@
<scm>
<url>https://github.com/questdb/rust-maven-plugin</url>
<connection>scm:git:https://github.com/questdb/rust-maven-plugin.git</connection>
<developerConnection>scm:git:git@github.com:questdb/rust-maven-plugin.git</developerConnection>
<developerConnection>scm:git:https://github.com/questdb/rust-maven-plugin.git</developerConnection>
<tag>HEAD</tag>
</scm>
<distributionManagement>
<snapshotRepository>
<id>central</id>
<url>https://oss.sonatype.org/content/repositories/snapshots</url>
</snapshotRepository>
<repository>
<id>central</id>
<url>https://oss.sonatype.org/service/local/staging/deploy/maven2</url>
</repository>
</distributionManagement>

<properties>
<maven.compiler.source>1.8</maven.compiler.source>
Expand All @@ -76,6 +65,74 @@
</properties>

<profiles>
<profile>
<id>maven-central-release</id>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.5.0</version>
<executions>
<execution>
<id>attach-javadocs</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-source-plugin</artifactId>
<version>3.0.1</version>
<executions>
<execution>
<id>attach-sources</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-gpg-plugin</artifactId>
<version>1.6</version>
<executions>
<execution>
<id>sign-artifacts</id>
<phase>verify</phase>
<goals>
<goal>sign</goal>
</goals>
</execution>
</executions>
<configuration>
<executable>gpg</executable>
</configuration>
</plugin>
<plugin>
<groupId>org.sonatype.plugins</groupId>
<artifactId>nexus-staging-maven-plugin</artifactId>
<version>1.6.3</version>
<executions>
<execution>
<id>default-deploy</id>
<phase>deploy</phase>
<goals>
<goal>deploy</goal>
</goals>
</execution>
</executions>
<configuration>
<serverId>central</serverId>
<nexusUrl>https://oss.sonatype.org</nexusUrl>
</configuration>
</plugin>
</plugins>
</build>
</profile>
<profile>
<id>java-module</id>
<activation>
Expand Down Expand Up @@ -106,10 +163,11 @@
<target>
<mkdir dir="${java9.build.outputDirectory}"/>
<javac srcdir="${java9.sourceDirectory}"
destdir="${java9.build.outputDirectory}"
classpath="${project.build.outputDirectory}"
includeantruntime="false"
source="9" />
destdir="${java9.build.outputDirectory}"
classpath="${project.build.outputDirectory}"
includeantruntime="false"
source="9"
target="9"/>
</target>
</configuration>
</execution>
Expand All @@ -127,7 +185,8 @@
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory>${project.build.outputDirectory}/META-INF/versions/9</outputDirectory>
<outputDirectory>${project.build.outputDirectory}/META-INF/versions/9
</outputDirectory>
<resources>
<resource>
<directory>${java9.build.outputDirectory}</directory>
Expand All @@ -153,4 +212,15 @@
</build>
</profile>
</profiles>

<distributionManagement>
<snapshotRepository>
<id>central</id>
<url>https://oss.sonatype.org/content/repositories/snapshots</url>
</snapshotRepository>
<repository>
<id>central</id>
<url>https://oss.sonatype.org/service/local/staging/deploy/maven2</url>
</repository>
</distributionManagement>
</project>
Loading

0 comments on commit c6c743f

Please sign in to comment.