diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 122 |
1 files changed, 81 insertions, 41 deletions
@@ -1,65 +1,105 @@ [](https://travis-ci.org/drivergroup/sbt-settings) [](https://index.scala-lang.org/drivergroup/sbt-settings) -# _sbt_ plugin for common _sbt_ settings -Provides common Driver Scala projects configuration for sbt, Scala compiler, testing, linting, formatting, release process, packaging, publication. Allows to use only necessary parts. Sets artifact `organization` to `xyz.driver`. +# Common sbt settings + +Provides common settings for Scala projects, as they are typically +configured at Driver. + +sbt-settings is a suite of [sbt +autoplugins](https://www.scala-sbt.org/1.0/docs/Plugins.html) that +provide common settings for the scala compiler, testing, linting, +formatting, release process, packaging and publication. ## Getting started -### project/plugins.sbt +Adding the following snippet to `project/plugins.sbt` will make the +plugins available: + +```scala +addSbtPlugin("xyz.driver" % "sbt-settings" % "<latest_tag>") +``` + +The next section exlains what plugins are available and which ones are +activated out-of-the-box. + +## Plugins + +### Summary + +| Name | Enabled | +|--------------------------|----------------------------------------| +| Linting | automatic | +| Versioning | automatic | +| IntegrationTestPackaging | automatic, if ServicePlugin is enabled | +| Library | manual | +| Service | manual | + +### Linting + +*[source](src/main/scala/xyz.driver.sbt/Linting.scala)* + +- Includes configuration for scalafmt and scalastyle, modifies the + `test` task to check for formatting and styling. +- Sets strict compiler flags and treats warnings as errors (with the + exception of deprecations). + +This plugin can get in the way of developer productivity. If that is +the case, it can simply be disabled. + +### Versioning + +*[source](src/main/scala/xyz.driver.sbt/Versioning.scala)* - addSbtPlugin("xyz.driver" % "sbt-settings" % "<latest_tag>") +Sets the project organization and reads version information from +git. It also enables overriding the version by setting a `VERSION` +environment variable (which may be useful to do from CI). -### build.sbt +### Integration Test Packaging -There are two different ways to use the `sbt-settings` configuration: +*[source](src/main/scala/xyz.driver.sbt/IntegrationTestPackaging.scala)* - * As a "Service" — deployed application distributed as a Docker container. Includes Driver Inc.'s artifactory settings, Docker packaging with truststore configuration, build info generation. Versioned using `version.sbt` file for major and minor versions. Usage example, as follows +Augments the packaging configuration of ServicePlugin, to include +integration tests in deployed applications images. - ``` - lazy val root = (project in file(".")) - .driverService ("Name-Of-Your-Service") - .integrationTestingConfiguration // Enable integration tests - .packagingConfiguration // To package to zip file as java server app - .settings(lintingSettings) // Scala code linting settings - .settings(formatSettings) // Standard Scala code formatting - .settings(releaseSettings(ServiceReleaseProcess)) // Release process configuration - ``` +### Library Plugin - * As a "Library" — commonly used code, distributed as jar using artifactory. Versioned using git tag-based versioning. Includes Driver Inc.'s artifactory settings, publication to artifactory, `sbt release` settings, +*[source](src/main/scala/xyz.driver.sbt/Library.scala)* - ``` - lazy val root = (project in file(".")) - .driverLibrary("Name-Of-Your-Library") - .settings(lintingSettings ++ formatSettings) - ``` +Common settings for libraries. It only sets the default publish +target to Driver's artifactory. -Do `sbt reload` after adding a plugin and changing project configuration. +### Service Plugin -## Reference +*[source](src/main/scala/xyz.driver.sbt/Service.scala)* -Artifact organization is set to `xyz.driver`. +Packages an application as a docker image and provides a way to +include internal TLS certificates. -### Scala compiler settings -Scala version — 2.12, flags configured: +It also includes some utility commands such as `start` and `stop` +(based on [sbt-revolver](https://github.com/spray/sbt-revolver), to +enable rapid local development cycles of applications. - - Common settings: `-unchecked -feature -encoding utf8`, - - _Advanced Scala features_: `-language:higherKinds -language:implicitConversions -language:postfixOps -language:reflectiveCalls`, - - _Compiler linting_: `-Xlint -deprecation -Ywarn-numeric-widen -Ywarn-dead-code -Ywarn-unused -Ywarn-unused-import -Xfatal-warnings -Xlint:-missing-interpolator`. +## Canonical Use Case +sbt-settings provides many plugins, which may be used in various +ways. Typically however, a project is either a Library or a Service, +and as such, it will enable one of those plugins explicitly. The other +plugins will provide general settings for common conventions and are +always enabled. -### Used sbt plugins +The following provides a typical example for configuring a project as +a service called "myservice": - - [sbt-scalafmt](https://olafurpg.github.io/scalafmt/) - code formatter for Scala, - - [scalastyle-sbt-plugin](https://github.com/scalastyle) - examines your Scala code and indicates potential problems with it, - - [sbt-revolver](https://github.com/spray/sbt-revolver) - for dangerously fast development turnaround in Scala, - - [sbt-buildinfo](https://github.com/sbt/sbt-buildinfo) - generates Scala source from your build definitions, - - [sbt-git](https://github.com/sbt/sbt-git) - to get access to git data (commit hash, branch) in sbt, - - [sbt-native-packager](https://github.com/sbt/sbt-native-packager) - build application packages in native formats, - - [sbt-assembly](https://github.com/sbt/sbt-assembly) - deploy fat JARs. Restart processes (sbt-native-packager is used instead,) - - [sbt-release](https://github.com/sbt/sbt-release) - customizable release process, - - [sbt-docker](https://github.com/marcuslonnberg/sbt-docker) - create Docker images directly from sbt. +```scala +lazy val myservice = project + .in(file(".")) + .enablePlugin(ServicePlugin) + .disablePlugins(IntegrationTestPackaging) // we don't need integration tests + .disablePlugins(LintPlugin) // I don't need style check during development! + .settings( /* custom settings */) +``` -## Developing +## Developing this Plugin This project is set up to auto-deploy on push. If an annotated tag in the form `v<digit>.*` is pushed, a new version of this project will be built and published to Maven Central. |