Skip to content

Commit

Permalink
Rewrite of the documentation for 2.0.0 release (#99)
Browse files Browse the repository at this point in the history 
* Rewrite of the documentation for 2.0.0 release

* Fix typos

* Update documentation for Twirl integration for version 2.0.0

* Add migration guide
  • Loading branch information
@britter @hseeberger
britter authored and hseeberger committed May 9, 2017
1 parent c8916b1 commit cb37f9f
Showing 1 changed file with 189 additions and 111 deletions.
300 changes: 189 additions & 111 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,137 +9,142 @@

sbt-header is an [sbt](http://www.scala-sbt.org) plugin for creating or updating file headers, e.g. copyright headers.

## Requirements

- Java 7 or higher
- sbt 0.13.13 or higher

## Configuration
## Getting started

In order to add the sbt-header plugin to your build, add the following line to `project/plugins.sbt`:

``` scala
addSbtPlugin("de.heikoseeberger" % "sbt-header" % "1.8.0")
addSbtPlugin("de.heikoseeberger" % "sbt-header" % "2.0.0")
```

If your build uses an auto plugin for common settings, make sure to add `HeaderPlugin` to `requires`:
Then in your `build.sbt` configure the following settings:

``` scala
import de.heikoseeberger.sbtheader.HeaderPlugin
```scala
organizationName := "Heiko Seeberger"
startYear := Some(2015)
licenses += ("Apache-2.0", new URL("https://www.apache.org/licenses/LICENSE-2.0.txt"))
```

object Build extends AutoPlugin {
override def requires = ... && HeaderPlugin
...
}
This configuration will add apply Apache License 2.0 headers to Scala and Java files. sbt-header provides two tasks: `headerCreate` and `headerCheck`, which are described in the following sub sections. For more information on how to customize sbt-header, please refer to the [Configuration](#configuration) section.

### Creating headers

In order to create or update file headers, execute the `headerCreate` task:

```
> headerCreate
[info] Headers created for 2 files:
[info] /Users/heiko/projects/sbt-header/sbt-header-test/test.scala
[info] /Users/heiko/projects/sbt-header/sbt-header-test/test2.scala
```

You have to define which source or resource files should be considered by sbt-header and if so, how the headers should look like. sbt-header uses a mapping from file extension to header pattern and text for that purpose, specified with the `headers` setting. Here's an example:
### Checking headers

``` scala
import de.heikoseeberger.sbtheader.HeaderPattern
In order to check whether all files have headers (for example for CI), execute the `headerCheck` task:

headers := Map(
"scala" -> (
HeaderPattern.cStyleBlockComment,
"""|/*
| * Copyright 2015 Heiko Seeberger
| *
| * Licensed under the Apache License, Version 2.0 (the "License");
| * you may not use this file except in compliance with the License.
| * You may obtain a copy of the License at
| *
| * http://www.apache.org/licenses/LICENSE-2.0
| *
| * Unless required by applicable law or agreed to in writing, software
| * distributed under the License is distributed on an "AS IS" BASIS,
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
| * See the License for the specific language governing permissions and
| * limitations under the License.
| */
|
|""".stripMargin
)
)
```
> headerCheck
[error] (compile:checkHeaders) There are files without headers!
[error] /Users/heiko/projects/sbt-header/sbt-header-test/test.scala
[error] /Users/heiko/projects/sbt-header/sbt-header-test/test2.scala
```

To exclude some files, use the [sbt's file filters](http://www.scala-sbt.org/0.13/docs/Howto-Customizing-Paths.html#Include%2Fexclude+files+in+the+source+directory):
`headerCheck` will not modify any files but will cause the build to file there are files without a license header.

``` scala
import de.heikoseeberger.sbtheader.HeaderPattern
### Requirements

headers := Map(
"scala" -> Apache2_0("2015", "Heiko Seeberger")
)
- Java 7 or higher
- sbt 0.13.13 or higher

excludeFilter.in(unmanagedSources.in(createHeaders)) := HiddenFileFilter || "*Excluded.scala"
```
## Configuration

The most common licenses have been pre-canned in [License](https://github.com/sbt/sbt-header/blob/master/src/main/scala/de/heikoseeberger/sbtheader/license/License.scala):
- [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
- [MIT License](https://opensource.org/licenses/MIT)
- BSD [2 Clause](https://opensource.org/licenses/BSD-2-Clause) and [3 Clause](https://opensource.org/licenses/BSD-3-Clause) License
- [GNU General Public License v3](http://www.gnu.org/licenses/gpl-3.0.en.html)
- [GNU Lesser General Public License v3](http://www.gnu.org/licenses/lgpl-3.0.en.html)
- [GNU Affero General Public License v3](https://www.gnu.org/licenses/agpl.html)
By default sbt-header tries to infer the license header you want to use from the `orgaizationName`, `startYear` and `licenses` settings. For this to work, sbt-header requires the `licenses` setting to contain exactly one entry. The first component of that entry has to be the [SPDX license identifier](http://spdx.org/licenses/) of one of the [supported licenses](#build-in-licenses).

They can be added as follows:
### Setting the license to use explicitly

``` scala
import de.heikoseeberger.sbtheader.license.Apache2_0
If you can not setup your build in a way that sbt-header can detect the license you want to use (see above), you can set the license to use explicitly:

headers := Map(
"scala" -> Apache2_0("2015", "Heiko Seeberger"),
"conf" -> Apache2_0("2015", "Heiko Seeberger", "#")
)
```scala
headerLicense := Some(HeaderLicense.MIT("2015", "Heiko Seeberger"))
```

The built-in licenses support three comment styles:
- C style block comments (default)
- C++ style line comments (commentStyle = "//")
- Hash line comments (commentStyle = "#")
This will also given precedence if a license has been auto detected from project settings.

The CommentStyleMapping object in [HeaderPlugin](https://github.com/sbt/sbt-header/blob/master/src/main/scala/de/heikoseeberger/sbtheader/HeaderPlugin.scala) provides default mappings for common file types, so that they don't have to be configured manually:
### Build in licenses

``` scala
import de.heikoseeberger.sbtheader.license.Apache2_0
import de.heikoseeberger.sbtheader.CommentStyleMapping._
The most common licenses have been pre-canned in [License](https://github.com/sbt/sbt-header/blob/master/src/main/scala/de/heikoseeberger/sbtheader/License.scala). They can either be detected using their SPDX identifier or by setting them explicitly.

headers := createFrom(Apache2_0, "2015", "Heiko Seeberger")
|License|SPDX identifier|
|-------|---------------|
|[Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)|`Apache-2.0`|
|[BSD 2 Clause](https://opensource.org/licenses/BSD-2-Clause)|`BSD-2-Clause`|
|[BSD 3 Clause](https://opensource.org/licenses/BSD-3-Clause)|`BSD-3-Clause`|
|[GNU General Public License v3](http://www.gnu.org/licenses/gpl-3.0.en.html)|`GPL-3.0`|
|[GNU Lesser General Public License v3](http://www.gnu.org/licenses/lgpl-3.0.en.html)|`LGPL-3.0`|
|[GNU Affero General Public License v3](https://www.gnu.org/licenses/agpl.html)|`AGPL-3.0`|
|[MIT License](https://opensource.org/licenses/MIT)|`MIT`|
|[Mozilla Public License, v. 2.0](http://mozilla.org/MPL/2.0/)|`MPL-2.0`|

### Using a custom license text

If you don't want to use one of the build in licenses, you can define a custom license test using the `Custom` case class:

```scala
headerLicense := Some(HeaderLicense.Custom(
"""|Copyright (c) Awesome Company 2015
|
|This is the custom License of Awesome Company
|""".stripMargin
))
```

Notice that for the header pattern you have to provide a `Regex` which extracts the header and the body for a given file, i.e. one with two capturing groups. `HeaderPattern` defines three widely used patterns:
- `cStyleBlockComment`, e.g. for Scala and Java
- `cppStyleLineComment`, e.g. for C++ and Protobuf
- `hashLineComment`, e.g. for Bash, Python and HOCON
Note that you don't need to add comment markers like `//` or `/*`. The comment style is configured on a per file type basis (see [next section](#build-in-comment-styles)).

By the way, first lines starting with shebang are not touched by sbt-header.
### Configuring comment styles

You can also declare your own quite easily using the `HeaderPattern.commentBetween` and `HeaderPattern.commentStartingWith` functions.
Comment styles are configured on a per file type basis. The default is to apply C Style block comments to Scala and Java files. No other comment styles are predefined. If you want to create comments for example for your XML files, you have to add the corresponding mapping manually (see below). The build-in comment styles are defined in [CommentStyle](https://github.com/sbt/sbt-header/blob/master/src/main/scala/de/heikoseeberger/sbtheader/CommentStyle.scala):

By default sbt-header takes `Compile` and `Test` configurations into account. If you need more, just add them:
|Name|Description|
|----|-----------|
|CStyleBlockComment|C style block comments (blocks starting with "/*" and ending with "*/")|
|CppStyleLineComment|C++ style line comments (lines prefixed with "//")|
|HashLineComment|Hash line comments (lines prefixed with "#")|
|TwirlStyleComment|Twirl style comment (blocks starting with "@*" and ending with "*@")|
|TwirlStyleBlockComment|Twirl style block comments (comment blocks with a frame made of "*")|

To override the configuration for Scala/Java files or add a configuration for some other file type, use the `headerMapping` setting:

``` scala
HeaderPlugin.settingsFor(It, MultiJvm)
headersMappings := headerMapping.value + (HeaderFileType.scala -> HeaderCommentStyle.CppStyleLineComment)
```

## Usage
### Excluding files

In order to create or update file headers, execute the `createHeaders` task:
To exclude some files, use the [sbt's file filters](http://www.scala-sbt.org/0.13/docs/Howto-Customizing-Paths.html#Include%2Fexclude+files+in+the+source+directory):

``` scala
excludeFilter.in(unmanagedSources.in(headerCreate)) := HiddenFileFilter || "*Excluded.scala"
```
> createHeaders
[info] Headers created for 2 files:
[info] /Users/heiko/projects/sbt-header/sbt-header-test/test.scala
[info] /Users/heiko/projects/sbt-header/sbt-header-test/test2.scala
```

In order to check whether all files have headers, execute the `checkHeaders` task:
### Using an auto plugin

If your build uses an auto plugin for common settings, make sure to add `HeaderPlugin` to `requires`:

``` scala
import de.heikoseeberger.sbtheader.HeaderPlugin

object Build extends AutoPlugin {
override def requires = ... && HeaderPlugin
...
}
```
> checkHeaders
[error] (compile:checkHeaders) There are files without headers!
[error] /Users/heiko/projects/sbt-header/sbt-header-test/test.scala
[error] /Users/heiko/projects/sbt-header/sbt-header-test/test2.scala

### Adding headers to files in other configurations

By default sbt-header takes `Compile` and `Test` configurations into account. If you need more, just add them:

``` scala
HeaderPlugin.settingsFor(It, MultiJvm)
```

### Automation
Expand All @@ -161,7 +166,41 @@ AutomateHeaderPlugin.automateFor(It, MultiJvm)
## Integration with other plugins

This plugin by default only handles `managedSources` and `managedResources` in `Compile` and `Test`. For this reason you
need to tell sbt-header when it should also add headers to additional files managed by other plugins.
need to tell sbt-header if it should also add headers to additional files managed by other plugins.

### sbt-twirl / play projects

To use sbt-header in a project using [sbt-twirl](https://github.com/playframework/twirl) (for example a Play web
project), the Twirl templates have to be added to the sources handled by sbt-header. Add the following to your build
definition:

```scala
import de.heikoseeberger.sbtheader.FileType
import play.twirl.sbt.Import.TwirlKeys

headersMappings := headerMapping.value + (FileType("html") -> HeaderCommentStyle.TwirlStyleBlockComment)

unmanagedSources.in(Compile, createHeaders) ++= sources.in(Compile, TwirlKeys.compileTemplates).value
```

sbt-header supports two comment styles for Twirl templates. `TwirlStyleBlockComment` will produce simple twirl block comments, while `TwirlStyleFramedBlockComment` will produce
framed twirl comments.

`TwirlStyleBlockComment` comment style:

```scala
@*
* This is a simple twirl block comment
*@
```

`TwirlStyleFramedBlockComment` comment style:

```scala
@**********************************
* This is a framed twirl comment *
**********************************@
```

### sbt-boilerplate

Expand All @@ -179,42 +218,81 @@ addBoilerplate(Compile, Test)
This adds `src/{conf}/boilerplate/**.scala` in the list of files handled by sbt-headers for `conf`, where `conf` is
either `Compile` or `Test`.

### sbt-twirl / play projects
## Migrating from 1.x

To use sbt-header in a project using [sbt-twirl](https://github.com/playframework/twirl) (for example a Play web
project), the Twirl templates have to be added to the sources handled by sbt-header. Add the following to your build
definition:
This section contains migration notes from version 1.x of sbt-header to version 2.x. The latest release of the 1.x line is 1.8.0. You can find the documentation of that release in the [corresponding git tag](https://github.com/sbt/sbt-header/tree/v1.8.0).

### Changed task names and settings keys

The names of all tasks and settings have been changed from 1.x to 2.x. Furthermore types of settings have changed. The following tables give an overview of the changes:

Changed task names:

|Old Name|New Name|
|--------|--------|
|`createHeaders`|`headerCreate`|
|`checkHeaders`|`headerCheck`|

Changed settings:

|Old Name : Old Type|New Name: New Type|
|--------|--------|
|`headers : Map[String, (Regex, String)]`|`headerMappings : Map[FileType, CommentStyle]`|
| - | `headerLicense : Option[License]`|
| `exclude : Seq[String]` | removed in favor of sbt include/excude filters|

### `createFrom` method

sbt-header 1.x featured some default header mappings as well as the `createFrom` method, which could be used to easily define header mappings:

```scala
import de.heikoseeberger.sbtheader.license.Apache2_0
import play.twirl.sbt.Import.TwirlKeys
headers := createFrom(Apache2_0, "2015", "Heiko Seeberger")
```

This method has been removed and the default mappings for Scala and Java files has been added as default mapping to the `headerMappings` setting.

### Custom licenses

In sbt-header 1.x when you needed to use a custom license this would typically look like this:

```scala
headers := Map(
"html" -> Apache2_0("2015", "Heiko Seeberger", "@*")
"scala" -> (
HeaderPattern.cStyleBlockComment,
"""|/*
| * Copyright 2015 Awesome Company
| */
|""".stripMargin
)
)

unmanagedSources.in(Compile, createHeaders) ++= sources.in(Compile, TwirlKeys.compileTemplates).value
```

sbt-header supports two comment styles for Twirl templates. `@*` will produce simple twirl comments, while `@**` produce
twirl block comments.

`@*` comment style:
In sbt-header 2.x, licenses are defined as instances of `de.hseeberger.sbtheader.License`. Further more, the license is only defined once and not per file type. So the above in 2.x is equivalent to:

```scala
@*
* This is a simple twirl comment
*@
headerLicense := Some(HeaderLicense.Custom(
"""|/*
| * Copyright 2015 Awesome Company
| */
|""".stripMargin
))
```

`@**` comment style:
This will apply C style block comments to Java and Scala files. If you have mappings for additional file types, please add these to the `headerMappings` setting.

### Dropped features

In sbt-header 1.x it was possible to define different licenses for different files types, e.g.:

```scala
@*********************************
* This is a twirl block comment *
********************************@
headers := Map(
"scala" -> Apache2_0("2015", "Heiko Seeberger"),
"java" -> MIT("2015", "Heiko Seeberger")
)
```

Since we believe most of the projects out there will only ever have one license, we dropped this feature without replacement. In sbt-header 2.x users have to define a single license for the whole project using the `headerLicense` setting (or let sbt-header infer it from the `licenses` project setting, see [above](#getting-started)) and a mapping from file type to comment style using the `headerMappings` setting.

## Contribution policy ##

Contributions via GitHub pull requests are gladly accepted from their original author. Along with any pull requests, please state that the contribution is your original work and that you license the work to the project under the project's open source license. Whether or not you state this explicitly, by submitting any copyrighted material via pull request, email, or other means you agree to license the material under the project's open source license and warrant that you have the legal authority to do so.
Expand Down

0 comments on commit cb37f9f

Please sign in to comment.