# HG changeset patch # User Da Risk # Date 1746479413 14400 # Node ID f1e51fe391c2440f84ada7806812dfcc9582560e # Parent 33ee5f3d646651e8e18418554635d3932d39b9a1 docs: add documentation for different license sources and UI diff -r 33ee5f3d6466 -r f1e51fe391c2 README.md --- a/README.md Mon May 05 17:09:13 2025 -0400 +++ b/README.md Mon May 05 17:10:13 2025 -0400 @@ -1,42 +1,24 @@ AboutOss ========== -AboutOss is an utility library to retrieve and display opensource licenses in Android applications. - -Usage -===== - -The library works with the [OSS Licenses Gradle Plugin](https://github.com/google/play-services-plugins/tree/master/oss-licenses-plugin). -You can integrate it in your application with few simple steps. +AboutOss is a Kotlin Multiplatform utility library to retrieve and display opensource licenses in your applications. -### Apply the OSS Licenses Gradle Plugin - -In your app-level `build.gradle`, apply the plugin by adding the following line under the existing `apply plugin: 'com.android.application'` at the top of the file: +License sources +--------------- -```kotlin title="build.gradle.kts" -apply plugin: 'com.google.android.gms.oss-licenses-plugin' -``` - -### Add the ui library to your application +The library can work with license information files generated by: -```kotlin title="build.gradle.kts" -repositories { - maven { - url = uri("https://jitpack.io") - } -} +- [OSS Licenses Gradle Plugin](https://github.com/google/play-services-plugins/tree/main/oss-licenses-plugin) +- [licensee](https://github.com/cashapp/licensee) +- [LicensePlist](https://github.com/mono0926/LicensePlist) -dependencies { - implementation("com.geekorum.aboutoss:ui-material:0.0.1") -} -``` +User interface +-------------- -### Launch the license activity +The user interface to display license information is written in [Compose Multiplatform](https://github.com/JetBrains/compose-multiplatform). +There is out of the box composables for Material and Material3 and you can easily write your own UI. -```kotlin -val intent = Intent(this, OpenSourceLicensesActivity::class.java) -startActivity(intent) -``` +Check the sample [here](https://github.com/fbarthelery/AboutOss/tree/main/sample) Build instructions ================== diff -r 33ee5f3d6466 -r f1e51fe391c2 buildSrc/src/main/kotlin/Dokka.kt --- a/buildSrc/src/main/kotlin/Dokka.kt Mon May 05 17:09:13 2025 -0400 +++ b/buildSrc/src/main/kotlin/Dokka.kt Mon May 05 17:10:13 2025 -0400 @@ -39,6 +39,18 @@ localDirectory = rootDir remoteUrl = uri("https://github.com/fbarthelery/AboutOss/tree/main/") } + + externalDocumentationLinks.register("okio") { + url = uri("https://square.github.io/okio/3.x/okio/okio/") + } + externalDocumentationLinks.register("kotlinx-coroutines") { + url = uri("https://kotlinlang.org/api/kotlinx.coroutines/") + } + + perPackageOption { + matchingRegex = ".*\\.generated\\.resources" + suppress = true + } } } diff -r 33ee5f3d6466 -r f1e51fe391c2 docs/license-sources.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/license-sources.md Mon May 05 17:10:13 2025 -0400 @@ -0,0 +1,62 @@ +License sources +=============== + +Setup +===== + +Add the dependency to your project + +```kotlin title="build.gradle.kts" +dependencies { + implementation("com.geekorum.aboutoss:core:") +} +``` + +OSS Licenses Gradle Plugin +-------------------------- + +The [OSS Licenses Gradle Plugin](https://github.com/google/play-services-plugins/tree/main/oss-licenses-plugin) stores license information in Android resources. + +Create a [GmsLicenseInfoRepository](api/core/com.geekorum.aboutoss.core.gms/-gms-license-info-repository/index.html) to retrieves it. + +The `GmsLicenseInfoRepository` is only available on Android platform. + +```kotlin + val licenseInfoRepository = GmsLicenseInfoRepository( + appContext = application + ) +``` + + +Licensee +-------- + +[licensee](https://github.com/cashapp/licensee) report file can be used as a source of license information. + +Create a [LicenseeLicenseInfoRepository](api/core/com.geekorum.aboutoss.core.licensee/-licensee-license-info-repository/index.html) to read the report file. + + +```kotlin title="on iOS and Desktop" +val licenseInfoRepository = LicenseeLicenseInfoRepository() +``` + +```kotlin title="on Android" +val licenseInfoRepository = LicenseeLicenseInfoRepository( + assetManager = application.assets +) +``` + +LicensePlist +------------ + +On iOS, [LicensePlist](https://github.com/mono0926/LicensePlist) can be use to automatically generates a Plist of all your dependencies. + +Use [LicensePlistLicenseInfoRepository](api/core/com.geekorum.aboutoss.core.licenseplist/-license-plist-license-info-repository/index.html) +to parse license information stored in your resources bundle. + +The `LicensePlistLicenseInfoRepository` is only available on iOS platform. + +```kotlin +val licenseInfoRepository = LicensePlistLicenseInfoRepository() +``` + diff -r 33ee5f3d6466 -r f1e51fe391c2 docs/ui-material.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/ui-material.md Mon May 05 17:10:13 2025 -0400 @@ -0,0 +1,57 @@ +Ui-Material +=========== + +Setup +===== + +Add the dependency to your project + +```kotlin title="build.gradle.kts" +dependencies { + implementation("com.geekorum.aboutoss:ui-material:") +} +``` + +Usage +===== + +The [OpenSourceDependenciesNavHost](api/ui/material2/com.geekorum.aboutoss.ui.material/-open-source-dependencies-nav-host.html) +composable allows to display the licenses. +It takes an [OpenSourceLicensesViewModel](api/ui/common/com.geekorum.aboutoss.ui.common/-open-source-licenses-view-model/index.html) +that you can create with the [LicenseInfoRepository](license-sources.md) of your choice. + +```kotlin +val licenseInfoRepository = LicenseeLicenseInfoRepository() +val viewModel = viewModel(factory = OpenSourceLicensesViewModel.Factory(licenseInfoRepository)) +OpenSourceDependenciesNavHost( + openSourceLicensesViewModel = viewModel, + navigateUp = { + // close screen + } +) +``` + +Android +======= + +The [OpenSourceLicensesActivity](api/ui/material2/com.geekorum.aboutoss.ui.material/-open-source-licenses-activity/index.html) is configured to work with the [OSS Licenses Gradle Plugin](https://github.com/google/play-services-plugins/tree/main/oss-licenses-plugin) +You can launch the activity like this: + +```kotlin +val intent = Intent(this, OpenSourceLicensesActivity::class.java) +startActivity(intent) +``` + + +Desktop +======= + +On Desktop the [OpenSourceLicensesWindow](api/ui/material2/com.geekorum.aboutoss.ui.material/-open-source-licenses-window.html) is configured to work with [licensee](https://github.com/cashapp/licensee). +You can use it like this: + +```kotlin +OpenSourceLicensesWindow(onCloseRequest = { + // close window +}) +``` + diff -r 33ee5f3d6466 -r f1e51fe391c2 docs/ui-material3.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/ui-material3.md Mon May 05 17:10:13 2025 -0400 @@ -0,0 +1,72 @@ +Ui-Material3 +============ + +Setup +===== + +Add the dependency to your project + +```kotlin title="build.gradle.kts" +dependencies { + implementation("com.geekorum.aboutoss:ui-material3:") +} +``` + +Usage +===== + +The [OpenSourceDependenciesNavHost](api/ui/material3/com.geekorum.aboutoss.ui.material3/-open-source-dependencies-nav-host.html) +composable allows to display the licenses. +It takes an [OpenSourceLicensesViewModel](api/ui/common/com.geekorum.aboutoss.ui.common/-open-source-licenses-view-model/index.html) +that you can create with the [LicenseInfoRepository](license-sources.md) of your choice. + +```kotlin +val licenseInfoRepository = LicenseeLicenseInfoRepository() +val viewModel = viewModel(factory = OpenSourceLicensesViewModel.Factory(licenseInfoRepository)) +OpenSourceDependenciesNavHost( + openSourceLicensesViewModel = viewModel, + navigateUp = { + // close screen + } +) +``` + +The [AdaptiveOpenSourceDependenciesScreen](api/ui/material3/com.geekorum.aboutoss.ui.material3/-adaptive-open-source-dependencies-screen.html) +composable display the licenses in an adaptive screen. The User interface will adapt based on the available space. + +```kotlin +val licenseInfoRepository = LicenseeLicenseInfoRepository() +val viewModel = viewModel(factory = OpenSourceLicensesViewModel.Factory(licenseInfoRepository)) +AdaptiveOpenSourceDependenciesScreen( + openSourceLicensesViewModel = viewModel, + navigateUp = { + // close screen + } +) +``` + + +Android +======= + +The [OpenSourceLicensesActivity](api/ui/material3/com.geekorum.aboutoss.ui.material3/-open-source-licenses-activity/index.html) is configured to work with the [OSS Licenses Gradle Plugin](https://github.com/google/play-services-plugins/tree/main/oss-licenses-plugin) +You can launch the activity like this: + +```kotlin +val intent = Intent(this, OpenSourceLicensesActivity::class.java) +startActivity(intent) +``` + + +Desktop +======= + +On Desktop the [OpenSourceLicensesWindow](api/ui/material3/com.geekorum.aboutoss.ui.material3/-open-source-licenses-window.html) is configured to work with [licensee](https://github.com/cashapp/licensee). +You can use it like this: + +```kotlin +OpenSourceLicensesWindow(onCloseRequest = { + // close window +}) +``` + diff -r 33ee5f3d6466 -r f1e51fe391c2 mkdocs.yml --- a/mkdocs.yml Mon May 05 17:09:13 2025 -0400 +++ b/mkdocs.yml Mon May 05 17:10:13 2025 -0400 @@ -38,5 +38,9 @@ nav: - Home: index.md + - License sources: license-sources.md + - User interface: + - Material: ui-material.md + - Material3: ui-material3.md - API: api/index.html - "Discussions ⏏": https://github.com/fbarthelery/AboutOss/discussions \ No newline at end of file