Librarian

English

Librarianはgradle moduleで使用しているライブラリーの通知を作ります

Librarianは以下の点に焦点を当てています:

同一ライブラリーのアーティファクトをグループとして集計
正確にライブラリーを集計する
予め用意されたプリセット情報による可能な限りの自動化
コンフィグレーションをページとして集計し、複数の通知ファイルの作成

必須

Gradle 5.5またはそれ以上
(Android開発の場合) version3.5以上のAndroid StudioとAndroid Gradle Plugin

Gradleのバージョンアップ

プロジェクトのフォルダーを開く
gradle/wrapper/gradle-wrapper.propertiesに移動
Gradleのバージョンを挙げます
- たとえばこのように書き換えます:distributionUrl=https\://services.gradle.org/distributions/gradle-5.5.1-all.zip

はじめに

インストール

LibrarianはGitHub PackagesとBintrayに公開しているのでどちらのMaven Repositoryを参照するか選んでください

Bintrayの場合:

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

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
            }
        }
    }
}

そしてclasspathを追加してください:

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

そしてprojectにpluginを適用します:

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

タスク

librarian plugin
librarian preset plugin
- librarianGeneratePresetGroups
- librarianGeneratePresetPipeline

構成

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, must set value
                    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	出力するrootフォルダーの名前
librarian.depth	依存を検索する深さ、firstLevelはあなたが直接依存したものを探します
librarian.failOnGeneratePageWhenFoundPlaceholder	`librarianGeneratePages`でプレースホルダーが見つかったときに失敗します
librarian.failOnOverrideUnMatchedLicense	groupのライセンス情報と一致しないオーバーライドを使用としたときに失敗します
librarian.failOnTooManyResolvingConfigurationLimit	configurationの解決が多すぎる場合に失敗させる制限値、マルチモジュールプロジェクトは解決数が指数関数的に増えていきます
librarian.useBintray	`librarianGenerateBintrayGroups`タスクのときにBintray APIを使ってライブラリー情報を探します、この機能はアルファ版です
librarian.ignoreArtifacts	通知で無視するartifact、前方一致です

通知ページの生成

Librarianをインストール
プロジェクトで構成を書きます、pagesブロックを付けてください
- librarianShowConfigurationsタスクを使いながら構成を書くといいでしょう
librarian.failOnGeneratePageWhenFoundPlaceholderにfalseを設定します
librarianGeneratePresetPipelineタスクを実行
もしエラーが出たり完了しなかったらgroupsブロックを記述してlibrarianGenerateGroupsタスクを実行します
librarian.failOnGeneratePageWhenFoundPlaceholderにtrueを設定します
librarianGeneratePresetPipelineタスクを実行

Androidビューワー

LibrarianはAndroidで通知を表示するためのネイティブビューワーを用意しています

ui-core: UIのコア実装であり、NoticesViewとNoticeViewが含まれてます
ui-activity: Activityとして表示するためのui-coreのラップ実装です
ui-fragment: Fragmentとして表示するためのui-coreのラップ実装です
ui-serializer-**: 様々なJson Serializer Libraryのための実装です

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")
        }
    }
}

register activity:

<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>

register listener:

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

Jsonシリアライザー

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

サンプル

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

その他

Create Own Android Serializer
Customize Android Viewer

Viewerの作成

See Create Own Viewer

Tips

page configurationのメカニズムについて

Librarianはそれぞれのページにおいて依存を通知するconfigurationsを選ぶことができます

通常ではプロジェクトはこのようなconfigurationsを持っています:

implementationDependenciesMetadata
testImplementationDependenciesMetadata
classpath
etc..

dependenciesブロックの構成でこららのconfigurationsに依存が追加されます。追加された依存はlibrarianShowConfigurationsタスクで確認することができます

通知したいconfiguration名をpages.configurationsブロックに追加します。通常ではcontainブロックを使えばいいです

モジュールをネストした場合、configuration名の正確な順序を設定することができ、librarianShowFilteredDependencyGraphタスクではそれらの順序まで表示します

example table:

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

contain: containで設定した値にconfigurationsが収まっているか
exact: exactで設定した値と同じか

Android dynamic feature moduleの依存を通知に追加する

Android dynamic feature moduleを使っている場合は通常とは違う依存グラフになります

dynamic feature moduleのconfiguration名はreleaseReverseMetadataValues(これはBuild Flavorによって異なる)といったものから始まります

see sample: sample/sample-dynamic-app

Librarianが情報を推測できなくて通知を自動生成できない

ときどきLibrarianはPomファイルから情報を十分に得ることができません

そういったときはLibrary groupsを使って情報を補足することができます。Library groupはもともとはartifactsを集約するための機能ですが、情報をオーバーライドするためにも使用することができるのです

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
        }
    }
}

もしくはここからプリセットをリクエストすることができます

イメージリソースライセンス通知を追加する

たまに開発者は使用しているイメージリソースなどの通知をしなければなりません。Librarianはmaven artifactとは別に通知を追加することができます

example of Material design icons:

librarian {
    pages {
        "example" { // page name
            additionalNotices {
                "Material design icons" { // Notice name
                    artifacts = ["com.google.material:icons"] // set any value
                    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"
                        }
                    }
                }
            }
        }
    }
}

pomファイルを解決できない

たまにLibrarianがpomファイルを解決できない時があります。ほとんどの場合でそれはMaven Repository URLがモジュールのbuild.gradleに設定されていないことが原因です

Librarianのタスクではroot直下のbuild.gradleのbuildscriptも集計します。このとき、root直下のbuild.gradleのbuildscriptのみに設定されていると問題が起きます

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README-ja.md

README-ja.md

Librarian

目次

必須

Gradleのバージョンアップ

はじめに

インストール

タスク

構成

通知ページの生成

Androidビューワー

ui-activityの導入

Jsonシリアライザー

サンプル

その他

Viewerの作成

Tips

page configurationのメカニズムについて

Android dynamic feature moduleの依存を通知に追加する

Librarianが情報を推測できなくて通知を自動生成できない

イメージリソースライセンス通知を追加する

pomファイルを解決できない

GitHub Actions

Auto Generate Notice Page and Create Pull Request

Contributing

License

Using Libraries

Files

README-ja.md

Latest commit

History

README-ja.md

File metadata and controls

Librarian

目次

必須

Gradleのバージョンアップ

はじめに

インストール

タスク

構成

通知ページの生成

Androidビューワー

ui-activityの導入

Jsonシリアライザー

サンプル

その他

Viewerの作成

Tips

page configurationのメカニズムについて

Android dynamic feature moduleの依存を通知に追加する

Librarianが情報を推測できなくて通知を自動生成できない

イメージリソースライセンス通知を追加する

pomファイルを解決できない

GitHub Actions

Auto Generate Notice Page and Create Pull Request

Contributing

License

Using Libraries