**structured w/o scope**

The base format is `Map>`.

**flatten**

The base format is `List`. The format of `ArtifactDefinition` is almost same but only *key* is different.

```
- key: ":"
...
...
```

#### license-catalog.yml

This file contains licenses that artifacts have references. This plugin infers licenses using their name and provide primary keys automatically.

```yaml
- key: "" # Required
name: "" # Required
url: "" # Optional. null or removing this field means this license has no url.
```

#### .artifactignore

This file is to find artifact that should be ignored from the management. Each lines must consist of regular expressions or glob patterns that matches with `:`. If you'd like to use `glob` pattern, you need to configure this plugin through the extension. ref: [Extension](#extension)

**Regular expression samples**

```
com\.example:sample-artifact
io\.github\.jmatsu\.internal:.*
io\.github\.jmatsu\..*
```

**Glob pattern samples**

*: is a path separator instead of /*

```
com.example:sample-artifact
io.github.jmatsu.internal:*
io.github.jmatsu.**
```

### Manage files

This section explains how you will manage the files that this plugin uses.

#### The basic management cycle

The basic management cycle is the below.

1. Run `./gradlew validateLicenseList`
2. Run `mergeLicenseList` to reflect the current artifacts if failed.
3. Run `./gradlew inspectLicenseList`
4. Modify `artifact-definition.yml` based on the inspection report above.
- You may want to modify `.artifactignore` to exclude several artifacts.
- If so, please go to Step2 after updating `.artifactignore` to reflect the ignore configurations.
5. And also, modify `license-catalog.yml` as well.
6. Go back to Step1 until no issue is found.

#### Generate a license viewer or its resource

Generate the file for your license viewer by running `./gradlew visualizeLicenseList` and embed it into your application.

This plugin supports `html` and `json` as the resource format.

## Tasks

This plugin follows the naming strategy of Android Gradle Plugin does as much as possible. i.e. `LicenseList` is it.

### Initialize

`initLicenseList`

This is the entrypoint of this plugin. It generates the base definition file and the license catalog file that you will manage.

**Do you want to overwrite it?**

If you would like to re-initialize the definition files, then please pass `-Poverwrite=true` when running this task.

### Inspect

*Available since 0.4*

`inspectLicenseList`

Inspect the current management files and report lacked attributes.

NOTE: This doesn't mean your definition file *satisfy* license usages. It's your responsibility, not of this plugin.

### Validate

`validateLicenseList`

This checks if the current definition files and the current project dependencies differ.

NOTE: This doesn't mean your definition file *satisfy* license usages. It's your responsibility, not of this plugin.

### Merge/Update

`mergeLicenseList`

Merge the current project dependencies into the current definition files with respecting the current definition files.

The strategy is *defensive*. This task will preserve your changes in the definition files.

### Visualize

`visualizeLicenseList`

It will create a HTML file or JSON file based on the plugin configuration if validation and inspection succeed.

NOTE: `-PskipInspect=true` can skip *inspect* action and `-PskipValidate=true` can skip *validate* action.

Tips: [example](./example) renders its licenses based on the both of json and html.

## Extension

```kotlin
licenseList {
// Control availability of this plugin('s tasks). true by default.
isEnabled =

// Make initLicenseList an alias of `initFreeReleaseLicenseList`
defaultTarget = ""

// The filter pattern used for ignore feature. regex is default.
ignoreFormat = ""

variants {
// you can declare the configuration for each variants
create("freeRelease") {
// A directory that contains artifact-definition.yml, license-catalog.yml and .artifactignore
baseDir = file("license-list")

// options for the management file
assembly {
// management file format
// optional: yaml by default
format = ""

// the style of the managed content
// optional: structured by default
style = ""

// whether or not artifacts are grouped by scopes like `implementation`
// optional: true by default
groupByScopes = true

// Rarely used. See Tips/Custom configurations
// optional
additionalScopes += setOf("customImplConfiguration")

// Rarely used. See Tips/WearApp
// optional
targetConfigurations += setOf("wearApp")
}

// options for the report file
visualization {
format = "" // html by default

// the embedded template will be used by default
htmlTemplateDir = file("")

// To support free maker's breaking changes. rarely used.
freeMakerVersion = ""

// `/assets` is the default location
outputDir = file("")
}
}
}
}
```

## Tips

### For license-tools-plugin users

ref: [cookpad/license-tools-plugin](https://github.com/cookpad/license-tools-plugin/blob/master/LICENSE.md)

Those who are from license-tools-plugin can migrate their yml file to the format that this plugin supports.

**Configure this plugin for the migration**

```kotlin
plugins {
id("com.cookpad.android.licensetools") // A migration task is available only when the plugin is applied
id("io.github.jmatsu.license-list")
}

licenseTools {
licensesYaml = ... // this property is supported
ignoreGroups = [...] // this property is also supported
}

licenseList {
defaultVariant = ""
}
```

**Run the migration task**

Please note that the following task is available only when `license-tools-plugin` is applied

```bash
./gradlew migrateLicenseToolsDefinition
```

**Copy generated files and remove license-tools-plugin**

Generated files are available in `/path/to/app-module/build/license-list`. They are `.artifactignore`, `artifact-definition.yml`, and `license-catalog.yml`.
Please move them to the directory where you would like to use for the management. The default configuration will check `/path/to/app-module` directory.

- Only v1.7.0 is tested. Please feel free to open issues if you have any problems.
- `licenseTools.ignoreProjects` is not supported. Because I couldn't imagine the usecase that we really want to ignore *projects*. The group/artifact ignore feature is enough.

*Points*

- Each line of `.artifactignore` are the same to `skip` in license-tools-plugin
- `skip` in `artifact-definition.yml` is the same to `forceGenerate`

## Manage local files

This plugin can manage local files as well. `local-files` is the reserved *group* in `artifact-definition.yml`.

```yaml
local-files: # equivalent to group
- key: ""
...
...
...
```

### Exclude specific groups/artifacts

You can exclude specific groups and/or artifacts through `.artifactignore` file. `.artifactignore` file is a list of Regexp that matches with `:`.

Let's say you want to exclude `com.example` group and `io.github.jmatsu:example` artifact. Your ignore file should be like the following.

```
com.example:.*
io.github.jmatsu:example
```

Please note that this plugin will automatically add `^` and `$` to each lines, so you must not add it in this ignore file.

For the more details, see [example/app/license-list/.artifactignore](example/app/license-list/.artifactignore).

#### Additional configurations like WearApp

For example `wearApp` is an independent from `implementation` etc. This plugin allows you to add such independent configurations to discovery targets. (No action is required if the variant's configurations extend the custom configurations.)

```kotlin
assembly {
targetConfigurations += "wearApp"
}
```

### Custom variant aware configurations

If you have created `functionalImplementation` and `FunctionalImplementation` for each variants, `additionalScopes` will be your help.

```kotlin
assembly {
// Elements in additionalScopes will be used to build dynamic configurations with using targetConfigurations
// e.g. `functional` will be used to build `functionalImplementation`, `functionalTestImplementation` and so on
additionalScopes += "functional"
}
```

### Html Customization

This plugin uses FreeMaker to generate HTML files and can accept an user-defined template like the following.

```kotlin
visualization {
// the name of the template file must be *license.html.ftl
htmlTemplateDir = file("customTemplateDir")
}
```

Please check the original `ftl` file for variables that you can use.

### Render Json

You can generate resources in json format.

```kotlin
licenseList {
variants {
freeRelease {
visualization {
format = "json"
}
}
}
}
```

The schema of the json resources are defined in `schema` module, which is published to jcenter.

```kotlin
repositories {
jcenter()
}

dependencies {
implementation("io.github.jmatsu:license-list-schema:")
}
```

They are just *interfaces* in pure Kotlin. So you can chose any serialization method, custom attribute transformation, and so on in the both of Java and Kotlin.

## Limitations

- Only for Android application projects.
- I think Java project support should also be supported but not yet planned.
- Sharing configuration between variants
- Modification detection

## Migration

### 0.7 breaking changes

The generated license URLs have been changed to show the contents correctly. Please run `mergeLicenseList` and `visualizeLicenseList` tasks to update your license catalog file and visualized file.

### 0.4 breaking changes

Breaking change1 :

`inspect` action was introduced in `0.4`. It reports missing or misconfigured attributes in your management files. `inspect` action does

- Recognize empty string and empty array as *invalid* values, and null as *valid* values.
- *null* was default values of `License#url` until `0.3`. Since `0.4`, *""* (empty string) is a default value because `inspection` should fail if no url is found in a pom file. Please modify *null* to *""* in your management file if the *null* is not unintended to make it an inspection target. It's okay to leave `null` as it is if it's intended of course.
- *empty array* was default values of `ArtifactDefinition#copyrightHolders`. It has not been changed in `0.4` but *empty array* becomes one of invalid values. This means `inspect` will fail anyway. Please use *null* or remove the copyrightHolders field from your management file if the artifact really has no copyright holders.

Breaking change2 :

- Now `visualize` action depends on `validate` and `inspect` actions.
- Please pass `-PskipInspect=true` and/or `-PskipValidate=true` unless necessary.

Deprecation:

- `artifactOutputDirectory` has been deprecated and renamed to `baseDir`

## License

Under MIT License.

```
Copyright 2020 Jumpei Matsuda (jmatsu)
```