Skip to content

Latest commit

 

History

History
117 lines (92 loc) · 5.12 KB

README.md

File metadata and controls

117 lines (92 loc) · 5.12 KB
Raw

Pekko SBT Paradox

This plugin is intended to extend the sbt-paradox plugin with some settings along with providing the Apache Pekko theme.

It is intended as a shared doc theme for the Apache Pekko umbrella of projects, and not as a public theme to use on "any" project.

Usage

JDK 1.8 (only)

The project intentionally supports JDK 1.8 by default since its built against sbt-paradox/sbt-paradox-theme 0.9.2 so you can just include it like this

addSbtPlugin("org.apache.pekko" % "sbt-paradox-pekko" % "<version>")

NOTE: If you happen to be using sbt-paradox plugins aside from

  • sbt-web
  • sbt-paradox-apidoc
  • sbt-paradox-project-info you need to use an excludesAll statement on addSbtPlugin to remove the resolved dependencies that rely on JDK 11+, i.e. if you need to use sbt-site-paradox you would do the following
addSbtPlugin(("com.github.sbt" % "sbt-site-paradox" % "1.5.0").excludeAll(
"com.lightbend.paradox", "sbt-paradox"))

JDK 11+

With JDK 11 or later you need to explicitly override the sbt-paradox/sbt-paradox-theme versions to use the 10.6.x (or newer) series, i.e.

addSbtPlugin("org.apache.pekko" % "sbt-paradox-pekko" % "<version>")
addSbtPlugin("com.lightbend.paradox" % "sbt-paradox" % "0.10.6")
addSbtPlugin("com.lightbend.paradox" % "sbt-paradox-theme" % "0.10.6")

Enable it instead of the upstream ParadoxPlugin:

import org.apache.pekko.PekkoParadoxPlugin

enablePlugins(PekkoParadoxPlugin)

For more settings refer to the Paradox documentation

Testing

When you have made changes to pekko-sbt-paradox, you can test it locally with:

sbt publishLocal sbtPlugin/scripted

This should show:

Pausing in /tmp/sbt_e457458e/simple
Press enter to continue.

Building from Source

Prerequisites

  • Make sure you have installed a Java Development Kit (JDK) version 8.
  • Make sure you have sbt installed and using this JDK.

Running the Build

  • Open a command window and change directory to your preferred base directory
  • Use git to clone the repo or download a source release from https://pekko.apache.org (and unzip or untar it, as appropriate)
  • Change directory to the directory where you installed the source (you should have a file called build.sbt in this directory)
  • sbt compile compiles the main source for project default version of Scala (2.13)
  • sbt test will compile the code and run the unit tests
  • sbt package will build the jars
    • the jars will built into target dirs of the various modules
    • for the the 'plugin' module, the jar will be built to plugin/target/scala-2.12/sbt-1.0/
  • sbt publishLocal will push the jars to your local Apache Ivy repository
  • sbt publishM2 will push the jars to your local Apache Maven repository
  • sbt sourceDistGenerate will generate source release to target/dist/
  • The version number that appears in filenames and docs is derived, by default. The derived version contains the most git commit id or the date/time (if the directory is not under git control).
    • You can set the version number explicitly when running sbt commands
      • eg sbt "set ThisBuild / version := \"1.0.0\"; sourceDistGenerate"
    • Or you can add a file called version.sbt to the same directory that has the build.sbt containing something like
      • ThisBuild / version := "1.0.0"

Community

There are several ways to interact with the Pekko community:

  • GitHub discussions: for questions and general discussion.
  • Pekko dev mailing list: for Pekko development discussions.
  • Pekko users mailing list: for Pekko user discussions.
  • GitHub issues: for bug reports and feature requests. Please search the existing issues before creating new ones. If you are unsure whether you have found a bug, consider asking in GitHub discussions or the mailing list first.