Librarian

Librarian is generate notice that library used in gradle module

License	License MIT License
Categories	Categories Net CLI User Interface Gson Data JSON
GroupId	GroupId net.meilcli.librarian
ArtifactId	ArtifactId ui-serializer-gson
Last Version	Last Version 1.0.1
Release Date	Release Date May 16, 2021
Type	Type aar
Description	Description Librarian Librarian is generate notice that library used in gradle module
Project URL	Project URL https://github.com/MeilCli/Librarian
Source Code Management	Source Code Management https://github.com/MeilCli/Librarian

Download ui-serializer-gson

Filename	Size
ui-serializer-gson-1.0.1.pom
ui-serializer-gson-1.0.1-sources.jar	4 KB
ui-serializer-gson-1.0.1-javadoc.jar	40 KB
Browse

How to add to project

Apache Maven

<!-- https://jarcasting.com/artifacts/net.meilcli.librarian/ui-serializer-gson/ -->
<dependency>
    <groupId>net.meilcli.librarian</groupId>
    <artifactId>ui-serializer-gson</artifactId>
    <version>1.0.1</version>
    <type>aar</type>
</dependency>

Gradle Groovy

// https://jarcasting.com/artifacts/net.meilcli.librarian/ui-serializer-gson/
implementation 'net.meilcli.librarian:ui-serializer-gson:1.0.1'

Gradle Kotlin

// https://jarcasting.com/artifacts/net.meilcli.librarian/ui-serializer-gson/
implementation ("net.meilcli.librarian:ui-serializer-gson:1.0.1")

Apache Buildr

'net.meilcli.librarian:ui-serializer-gson:aar:1.0.1'

Apache Ivy

<dependency org="net.meilcli.librarian" name="ui-serializer-gson" rev="1.0.1">
  <artifact name="ui-serializer-gson" type="aar" />
</dependency>

Groovy Grape

@Grapes(
@Grab(group='net.meilcli.librarian', module='ui-serializer-gson', version='1.0.1')
)

Scala SBT

libraryDependencies += "net.meilcli.librarian" % "ui-serializer-gson" % "1.0.1"

Leiningen

[net.meilcli.librarian/ui-serializer-gson "1.0.1"]

Dependencies

compile (2)

Group / Artifact	Type	Version
net.meilcli.librarian : ui-core	jar	1.0.1
com.google.code.gson : gson	jar	2.8.6

runtime (2)

Group / Artifact	Type	Version
org.jetbrains.kotlin : kotlin-stdlib-jdk7	jar	1.3.72
androidx.appcompat » appcompat	jar	1.1.0

Project Modules

There are no modules declared in this project.

Librarian

日本語

Librarian is generate notice that library used in gradle module

Librarian focuses on:

Aggregate artifacts as Group by same library
Accurately aggregate the library
Automation as much as possible with prepared preset information
Aggregate configurations as Page, generate multiple notice files

Required

Gradle 5.5 or over
(if you develop Android app) Android Studio and Android Gradle Plugin 3.5 or over

Upgrade Gradle version

open project folder
move gradle/wrapper/gradle-wrapper.properties
upgrade gradle version
- for example: distributionUrl=https\://services.gradle.org/distributions/gradle-5.5.1-all.zip

Getting started

Install

Librarian is published on GitHub Packages and Bintray. So you choice maven repository.

using Bintray:

buildscript {
    repositories {
        maven { url "https://dl.bintray.com/meilcli/librarian" }
    }
}

using GitHub Packages:

buildscript {
    repositories {
        maven {
            url "https://maven.pkg.github.com/MeilCli/Librarian"
            credentials {
                username System.getenv("GITHUB_USER")
                password System.getenv("GITHUB_TOKEN") // token has permission of read:packages
            }
        }
    }
}

And set classpath:

buildscript {
    dependencies {
        classpath "net.meilcli.librarian:plugin-core:VERSION" // replace VERSION
        classpath "net.meilcli.librarian:plugin-preset:VERSION" // replace VERSION
    }
}

And apply plugin your project:

apply plugin: 'librarian'
apply plugin: 'librarian-preset'

Task

Configuration

librarian {
    dataFolderName = "Library" // String, default value is Library
    depth = "firstLevel" // String, firstLevel or allLevel, default value is firstLevel
    failOnGeneratePageWhenFoundPlaceholder = true // Boolean, default value is true
    failOnOverrideUnMatchedLicense = true // Boolean, default value is true
    failOnTooManyResolvingConfigurationLimit = 1000 // Int, default value is 1000
    useBintray = false // Boolean, default value is false
    ignoreArtifacts = [] // Array of String

    pages {
        "plugin-core-usings-plugin" { // page name, must be unique
            title = "Librarian plugin-core's using libraries" // String?, default value is same the name
            description = null // String?, default value is null
            markdown = true // Boolean, default value is null
            markdownFileName = "README.md" // String, default value is README.md
            json = true // Boolean, default value is null
            jsonFileName = "notices.json" // String, default value is notices.json
            jsonAdditionalOutputPath = null // File, default is null
            configurations {
                exact {
                    value = [""] // Array of String
                }
                contain {
                    value = [""]
                }
                exact { value = [""] } // exact and contain can be multiple
            }
            additionalNotices {
                "AdditionalNotice" { // Notice name
                    artifacts = ["text:com"] // Array of String, default is empty
                    author = "Tester" // String, default is empty, must set value
                    url = "https://google.com" // String, default is empty, must set value
                    description = "" // String?, default value is null
                    licenses {
                        "MIT" { // License name, must set value
                            url = "https://google.com" // String, default is empty, must set value
                        }
                    }
                }
            }
        }
    }

    groups {
        "Kotlin" { // group name, must be unique
            artifacts = [
                    "org.jetbrains.kotlin:kotlin-gradle-plugin",
                    "org.jetbrains.kotlin:kotlin-serialization",
                    "org.jetbrains.kotlin:kotlin-stdlib-jdk7"
            ] // Array of String, default is empty list
            author = null // String?, default value is null
            url = null // String?, default value is null
            description = null // String?, default value is null
            licenseName = null // String?, default value is null
            licenseUrl = null // String?, default value is null
        }
    }
}

path	summary
librarian.dataFolderName	output root folder name
librarian.depth	search dependency depth, firstLevel find your directly dependency
librarian.failOnGeneratePageWhenFoundPlaceholder	fail on `librarianGeneratePages` when found placeholder
librarian.failOnOverrideUnMatchedLicense	fail on override un matched license by group
librarian.failOnTooManyResolvingConfigurationLimit	fail limit that resolving configurations too many, multi module project will be increase exponentially
librarian.useBintray	if true, actually use Bintray api at `librarianGenerateBintrayGroups` task, this feature is alpha
librarian.ignoreArtifacts	ignore notice of maven artifact, ignore by prefix match

Generate Notice Page

install Librarian
configure your project, put pages
- librarianShowConfigurations task helps when configure your project
set false to librarian.failOnGeneratePageWhenFoundPlaceholder
execute librarianGeneratePresetPipeline task
if console output error or incomplete result, configure your project that put groups
set true to librarian.failOnGeneratePageWhenFoundPlaceholder
execute librarianGeneratePresetPipeline task

Android Viewer

Librarian is prepared Android Viewer library

ui-core: core of UI, including some interface, NoticesView and NoticeView
ui-activity: wrap of core, for easily usage of Activity
ui-fragment: wrap of core, for easily usage of Fragment
ui-serializer-**: serializer implementation of some Json Serializer Library

Getting started of ui-activity

install UI Library:

dependencies {
    implementation "net.meilcli.librarian:ui-activity:VERSION" // replace VERSION
    implementation "net.meilcli.librarian:ui-serializer-kotlin:VERSION" // replace VERSION and serializer
}

configure Librarian:

apply plugin: 'librarian'
apply plugin: 'librarian-preset'

librarian {
    pages {
        "sample-from-maven" {
            title = "Using Libraries"
            description = "sample-from-maven is using this libraries."
            configurations {
                contain {
                    value = [
                        "implementationDependenciesMetadata",
                        "releaseImplementationDependenciesMetadata"
                    ]
                }
            }
            jsonAdditionalOutputPath = file("src/main/assets/notices.json")
        }
    }
}

<application>
    <!-- Replace your NoActionBar style -->
    <activity
        android:name="net.meilcli.librarian.activities.NoticesActivity"
        android:theme="@style/AppTheme.NoActionBar" />
    <activity
        android:name="net.meilcli.librarian.activities.NoticeActivity"
        android:theme="@style/AppTheme.NoActionBar" />
</application>

button.setOnClickListener {
    startActivity(NoticesActivity.createIntent(this, NoticesReader(), "notices.json"))
}

Serializers

KotlinX Serialization: ui-serializer-kotlin
Moshi: ui-serializer-moshi
Gson: ui-serializer-gson

Samples

Using ui-core: sample/sample-ui-core
Using ui-activity: sample/sample-ui-activity
Using ui-fragment: sample/sample-ui-fragment
Using Dynamic Feature Module: sample/sample-dynamic-app
Custom style: sample/sample-ui-custom

Other

Create Viewer

See Create Own Viewer

Tips

About the mechanism of page configuration

Librarian can select configurations that including dependencies to notify on every page

in normal case, project has some configurations such as:

implementationDependenciesMetadata
testImplementationDependenciesMetadata
classpath
etc..

the dependencies block configuration adds dependencies to these configurations. you can see configurations that has dependencies by librarianShowConfigurations task

add configuration names that want to notify at page to pages.configurations block. in normal case, you can use contain block

in nested module case, you can set exact configuration name order, and librarianShowFilteredDependencyGraph task show configuration name order

example table:

configurations	contain("releaseRuntimeClasspath", "apiDependenciesMetadata")	exact("releaseRuntimeClasspath", "apiDependenciesMetadata")
releaseRuntimeClasspath => releaseApiDependenciesMetadata	❌	❌
releaseRuntimeClasspath => releaseRuntimeClasspath	⭕	❌
releaseRuntimeClasspath => apiDependenciesMetadata	⭕	⭕

contain: whether configuration names is contained in value
exact: whether configuration names is equaled to value

Add android dynamic feature module dependency notices

in the case of android dynamic feature module, dependency graph is different from normal case

dynamic feature module configuration names is the starting point about releaseReverseMetadataValues(different every build flavor)

see sample: sample/sample-dynamic-app

Cannot auto generate because Librarian dose not infer some information

Sometimes, Librarian dose not infer Library information when not enough pom file

You can compensate information by using Library groups. Library groups is prepared originally for aggregation artifacts, but can use as to override information your hand

example:

librarian {
    groups {
        "Kotlin" { // group name, must be unique
            artifacts = [
                    "org.jetbrains.kotlin:kotlin-gradle-plugin",
                    "org.jetbrains.kotlin:kotlin-serialization",
                    "org.jetbrains.kotlin:kotlin-stdlib-jdk7"
            ] // Array of String, default is empty list
            author = null // String?, default value is null
            url = null // String?, default value is null
            description = null // String?, default value is null
            licenseName = null // String?, default value is null
            licenseUrl = null // String?, default value is null
        }
    }
}

Or, can request preset here

Add image resource license notice

Sometimes, developers must notify image resource licence or else. Librarian can add notice apart from maven artifact

example of Material design icons:

librarian {
    pages {
        "example" { // page name
            additionalNotices {
                "Material design icons" { // Notice name
                    artifacts = []
                    author = "Google Inc."
                    url = "https://github.com/google/material-design-icons"
                    description = "Material Design icons by Google" // optional
                    licenses {
                        "Apache License 2.0" {
                            url = "https://github.com/google/material-design-icons/blob/master/LICENSE"
                        }
                    }
                }
            }
        }
    }
}

Cannot resolve pom file

Sometimes, Librarian cannot resolve pom file. In most cases it's because Maven Repository URL is not set to module's build.gradle.

Librarian task aggregate root build.gradle's buildscript. in time, if it is only set to root build.gradle's buildscript, problems will occur.

GitHub Actions

if you use GitHub Actions, recommend use GitHub Packages when CI Build

switch maven repository by environment variables:

buildscript {
    repositories {
        def githubUser = System.getenv("GITHUB_USER")
        def githubToken = System.getenv("GITHUB_TOKEN")
        if (githubUser != null && githubToken != null) {
            maven {
                url "https://maven.pkg.github.com/MeilCli/Librarian"
                credentials {
                    username githubUser
                    password githubToken
                }
            }
        } else {
            maven { url "https://dl.bintray.com/meilcli/librarian" }
        }
    }
}

set environment your workflow

jobs:
  build:
    env:
      GITHUB_USER: "github-bot"
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Auto Generate Notice Page and Create Pull Request

using peter-evans/create-pull-request example:

name: CI

on:
  push:
    branches:
      - '*'
    tags-ignore:
      - '*'

jobs:
  librarian:
    runs-on: ubuntu-latest
    env:
      GITHUB_USER: "github-bot"
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-java@v1
        with:
          java-version: 1.8
      - name: Grant permission
        run: chmod +x gradlew
      - run: ./gradlew librarianGeneratePresetPipeline
      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v2
        with:
          commit-message: "update library notices"
          title: "update library notices"

Contributing

see Contributing.md. if you think to report issue, select Issue Template

License

Librarian is MIT License

Using Libraries

Each notices is located in the Library folder

artifact name	including binary libraries	using when developing
`plugin-core`	plugin-core-usings-plugin	plugin-core-usings-development
`plugin-preset`	plugin-preset-usings-plugin	plugin-preset-usings-development
`ui-core`	ui-core-usings-library	ui-core-usings-development
`ui-activity`	ui-activity-usings-library	ui-activity-usings-development
`ui-fragment`	ui-fragment-usings-library	ui-fragment-usings-development
`ui-serializer-kotlin`	ui-serializer-kotlin-usings-library	ui-serializer-kotlin-usings-development
`ui-serializer-moshi`	ui-serializer-moshi-usings-library	ui-serializer-moshi-usings-development
`ui-serializer-gson`	ui-serializer-gson-usings-library	ui-serializer-gson-usings-development

Versions

Version
1.0.1 May 16, 2021

Librarian

License

Categories

GroupId

ArtifactId

Last Version

Release Date

Type

Description

Project URL

Source Code Management

Download ui-serializer-gson

How to add to project

Dependencies

compile (2)

runtime (2)

Project Modules

Librarian

Table of Contents

Required

Upgrade Gradle version

Getting started

Install

Task

Configuration

Generate Notice Page

Android Viewer

Getting started of ui-activity

Serializers

Samples

Other

Create Viewer

Tips

About the mechanism of page configuration

Add android dynamic feature module dependency notices

Cannot auto generate because Librarian dose not infer some information

Add image resource license notice

Cannot resolve pom file

GitHub Actions

Auto Generate Notice Page and Create Pull Request

Contributing

License

Using Libraries

Versions