126 lines
2.8 KiB
Markdown
126 lines
2.8 KiB
Markdown
# sbt-gs-calver
|
|
|
|
CalVer plugin for Garrity Software projects. Typically used for library
|
|
development.
|
|
|
|
- [Usage](#usage)
|
|
- [Adding the Plugin](#adding-the-plugin)
|
|
- [Updating the Build File](#updating-the-build-file)
|
|
- [Publishing a Release](#publishing-a-release)
|
|
- [Supported Setting Keys](#supported-setting-keys)
|
|
- [`calVer`](#calVer)
|
|
- [Supported Command Line Properties](#supported-command-line-properties)
|
|
- [The `release` Property](#the-release-property)
|
|
- [Supported Tasks](#supported-tasks)
|
|
- [`calVerInfo`](#calverinfo)
|
|
- [Complete Example](#complete-example)
|
|
|
|
## Usage
|
|
|
|
This is an auto plugin that provides setting keys for version values.
|
|
|
|
1. Add the plugin to your build.
|
|
2. Update your build file to leverage the calculated CalVer values.
|
|
3. Build releases using the `-Drelease` parameter.
|
|
|
|
### Adding the Plugin
|
|
|
|
**File: project/plugins.sbt**
|
|
```scala
|
|
resolvers += "Garrity Software Releases" at "https://maven.garrity.co/gs"
|
|
|
|
addSbtPlugin("gs" % "sbt-gs-calver" % "0.1.0")
|
|
```
|
|
|
|
### Updating the Build File
|
|
|
|
On any project within the build:
|
|
|
|
```
|
|
.settings(version := calVerSelected.value)
|
|
```
|
|
|
|
### Publishing a Release
|
|
|
|
```
|
|
sbt -Drelease=true publish
|
|
```
|
|
|
|
## Supported Setting Keys
|
|
|
|
These are available in `build.sbt` once the plugin is added.
|
|
|
|
### `calVerSelected`
|
|
|
|
This setting should be used as the project version. Assign the value of this
|
|
setting to the `version` setting:
|
|
|
|
```scala
|
|
lazy val `example` = project
|
|
.in(file("."))
|
|
.settings(version := calVerSelected.value)
|
|
```
|
|
|
|
### `calVerMajor`
|
|
|
|
This setting should be used to calculate library names that are version-aware.
|
|
This practice helps protect against binary compatibility issues stemming from
|
|
different library versions existing as transitive dependencies.
|
|
|
|
```scala
|
|
lazy val `example` = project
|
|
.in(file("."))
|
|
.settings(version := calVerSelected.value)
|
|
```
|
|
|
|
## Supported Command Line Properties
|
|
|
|
Properties are provided via `-D` parameters: `-D<name>=<value>`.
|
|
|
|
### The `release` Property
|
|
|
|
Value is either `true` or `false`. If this property is not set, `false` is
|
|
assumed. Releases are opt-in.
|
|
|
|
## Supported Tasks
|
|
|
|
### `calVerInfo`
|
|
|
|
Invoking `sbt calVerInfo` will emit diagnostic version information at the `info`
|
|
log level via the SBT logger.
|
|
|
|
```
|
|
sbt calVerInfo
|
|
...
|
|
[info] [CalVer] Version: 2024.1.18-eba621c
|
|
...
|
|
```
|
|
|
|
## Complete Example
|
|
|
|
### `plugins.sbt`
|
|
|
|
```scala
|
|
resolvers += "Garrity Software Releases" at "https://maven.garrity.co/gs"
|
|
|
|
addSbtPlugin("gs" % "sbt-gs-calver" % "0.1.0")
|
|
```
|
|
|
|
### `build.sbt`
|
|
|
|
```scala
|
|
val scala3: String = "3.3.1"
|
|
|
|
ThisBuild / organizationName := "garrity software"
|
|
ThisBuild / organization := "gs"
|
|
ThisBuild / scalaVersion := scala3
|
|
|
|
lazy val sharedSettings = Seq(
|
|
scalaVersion := scala3,
|
|
version := calVerSelected.value
|
|
)
|
|
|
|
lazy val `gs-example` = project
|
|
.in(file("."))
|
|
.settings(sharedSettings)
|
|
```
|