Skip to content

Commit

Permalink
- minimal adjustments of README
Browse files Browse the repository at this point in the history
  • Loading branch information
@mikepenz
mikepenz committed Oct 31, 2021
1 parent 7c1d305 commit 320201f
Show file tree
Hide file tree
Showing 2 changed files with 21 additions and 178 deletions.
7 changes: 7 additions & 0 deletions MIGRATION.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,12 @@
### Upgrade Notes

#### v10.x.y
* v10 includes a major rewrite of the `Gradle Plugin`. The old `xml` string resource format definitions are no longer supported.
* All meta information is now written to a single json file
* Old `enchant` config files are no longer supported
* The UI module dropped a major amount of configurations to lower complexity.
* TODO

#### v7.0.1
* in case your project has custom licenses, check out the new feature to allow the license description be included as raw file. This helps to solve the potential STRING_TOO_LARGE issue.

Expand Down
192 changes: 14 additions & 178 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# AboutLibraries

.. allows you to easily create an **used open source libraries** fragment/activity within your app. All the library information is automatically collected from the POM information of your dependencies and included during compile time.
.. collects all dependency details including licenses at compile time, and offers simple APIs to visualize these in the app.
*No runtime overhead.* Strong caching. Any dependency is supported.

-------
Expand All @@ -19,15 +19,12 @@
### What's included 🚀
- **used open source libraries**
- name, description, creator, license, version, ...
- **about this app** section (optional)
- Kotlin Multiplatform support
- autodetect libraries (via the gradle dependencies)
- configuration and build caching support
- many included library details
- automatic created fragment/activity
- feature rich builder to simply create and start the fragment / activities
- large amount of configuration options
- usage standalone possible too
- much much more... try the sample for a quick overview.
- libraries include a significant amount of meta data
- generated data can be accessed directly and included in custom UI
- Compose support

# Screenshots
![Image](https://raw.githubusercontent.com/mikepenz/AboutLibraries/develop/DEV/screenshots/screenshots.jpg)
Expand All @@ -36,14 +33,12 @@

## Latest releases 🛠

- (NEW) Kotlin | [v10.0.0-a01](https://github.com/mikepenz/AboutLibraries/tree/v10.0.0-a01)
- Kotlin && Gradle Plugin | [v8.9.4](https://github.com/mikepenz/AboutLibraries/tree/v8.9.4)
- Kotlin | [v7.1.0](https://github.com/mikepenz/AboutLibraries/tree/v7.1.0) - Deprecated
- Java && AndroidX | [v6.2.3](https://github.com/mikepenz/AboutLibraries/tree/v6.2.3) - Deprecated
- Java && AppCompat | [v6.1.1](https://github.com/mikepenz/AboutLibraries/tree/v6.1.1) - Deprecated

## Gradle Plugin

As a new feature of the AboutLibraries v8.x.y we offer a gradle plugin which will resolve the dependency during compilation, and only includes the libraries which are really specified as dependencies.
AboutLibraries v10 includes a completely redone plugin, with build and configuration cache support. It includes all dependencies as found based on the gradle configuration.

```gradle
// Root build.gradle
Expand Down Expand Up @@ -94,8 +89,6 @@ The activity uses a toolbar, which requires the appropriate theme. See [Style th
#### Fragment
```kotlin
val fragment = LibsBuilder()
.withFields(R.string::class.java.fields) // in some cases it may be needed to provide the R class, if it can not be automatically resolved
.withLibraryModification("aboutlibraries", Libs.LibraryFields.LIBRARY_NAME, "_AboutLibraries") // optionally apply modifications for library information
.supportFragment()
```

Expand All @@ -121,23 +114,6 @@ See the `Config` section for more information.

# Advanced Usage

## Jetpack navigation

Include the AboutLibraries destination in your graph

```xml
<include app:graph="@navigation/aboutlibs_navigation" />
```

After that you can define it as your target
```xml
<action
android:id="@+id/action_x_to_about_libs"
app:destination="@id/about_libraries" />
```

> To configure provide the `LibsBuilder` as the data argument
## Access generated library details

If you want to create your own integration you can access the generated library information programmatically through the core module.
Expand Down Expand Up @@ -198,33 +174,21 @@ It is possible to provide custom configurations / adjustments to the automatic d

```groovy
aboutLibraries {
configPath = "config" // the path to the directory relative to the root of the whole project containing configuration files
configPath = "config"
// provide libraries or licenses to be integrated in the generated data
// see the sample project for a demo usage
// libraries are merged using the `uniqueId`, and licenses using the `hash`
}
```

This directory may contain one or more of the following configurations:

```
custom_enchant_mapping.prop // allows providing custom mapping files to overwrite the information from the POM file
custom_license_mappings.prop // allows defining the licenseId which should be used for the library (if not resolvable via the POM file)
custom_license_year_mappings.prop // allows defining the license Year for this library (this information CANNOT be resolved from the POM file)
custom_name_mappings.prop // allows overwriting the name of a library if the POM specifies unexpected information
custom_author_mappings.prop // allows overwriting the authors of a library if the POM specifies unexpected information
custom_exclusion_list.prop // allows excluding libraries by their id at build time
```

See the corresponding files here for the format and content: https://github.com/mikepenz/AboutLibraries/tree/develop/aboutlibraries-definitions/src/main/res/raw
See the corresponding files here for the format and content: https://github.com/mikepenz/AboutLibraries/tree/develop/config

### Exclude libraries

> This is mainly meant for internal libraries, or projects. Full attribution to used projects is appreciated.
```groovy
aboutLibraries {
// allows to specify regex patterns to exclude some libraries
// preferred for internal libraries, ...
// The regex applies onto the uniqueId. E.g.: `com_mikepenz__materialdrawer`
// specify with the groovy regex syntax.
// allows to specify regex patterns to exclude some libraries preferred for internal libraries, ...
// The regex applies onto the uniqueId. E.g.: `com.mikepenz:materialdrawer` specify with the groovy regex syntax.
exclusionPatterns = [~"com_.*", ~/com_mylibrary_.*/]
}
```
Expand All @@ -245,104 +209,6 @@ aboutLibraries {
}
```

Alternatively all licenses can be included in the project.

> NOTE: Doing this will include extra string resources in your project.
```groovy
aboutLibraries {
includeAllLicenses = true
}
```

## Custom Licenses

It is possible to add additional licenses. In order to do so, you have to add the content of the license as an own text file in the app's raw folder e.g. `app/src/main/res/raw/myLicense.txt`
This file will contain the full raw license text which may be too long for the strings.xml file.

```html
<h3>GNU GENERAL PUBLIC LICENSE</h3>

<p>Version 2, June 1991</p>

<p>
Copyright &copy; 1989, 1991 Free Software Foundation, Inc.<br/>
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA<br/><br/>

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
```

Next, you need to add string identifiers that allow the plugin to recognize the license.

```xml
<!-- identifier used to reference this license -->
<string name="define_license_myLicense" translatable="false" />
<string name="license_myLicense_licenseName" translatable="false">Custom License</string>
<string name="license_myLicense_licenseWebsite" translatable="false">https://www.gnu.org/licenses/gpl-2.0.html</string>
<string name="license_myLicense_licenseShortDescription" translatable="false">
<![CDATA[
<p>&lt;one line to give the program\'s name and a brief idea of what it does.&gt;
Copyright &copy; &lt;year&gt; &lt;name of author&gt;</p>
<p>This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.</p>
<p>This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.</p>
<p>You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</p>
]]>
</string>
<!-- name of the license file under the raw folder -->
<string name="license_myLicense_licenseDescription" translatable="false">raw:myLicense</string>
```

Finally, you have to use the specified identifier `myLicense` when referencing this license in your mappings.

## Custom Libraries

In case the plugin fails to detect a library or you're using an embedded library, you can manually add an entry that will be picked up by the plugin. All you have to do is define custom string identifiers for the library.

```xml
<resources>
<!-- identifier used to reference this library -->
<string name="define_plu_myLibrary">year;owner</string>
<string name="library_myLibrary_author">Author</string>
<string name="library_myLibrary_authorWebsite">https://mikepenz.dev</string>
<string name="library_myLibrary_libraryName">My Library</string>
<string name="library_myLibrary_libraryDescription">Some text</string>
<string name="library_myLibrary_libraryVersion">10.1.1</string>
<string name="library_myLibrary_libraryWebsite">https://mikepenz.dev</string>
<!-- you can also reference custom licenses here e.g. myLicense -->
<string name="library_myLibrary_licenseIds">apache_2_0</string>
<string name="library_myLibrary_isOpenSource">true</string>
<string name="library_myLibrary_repositoryLink">https://mikepenz.dev</string>
<!-- Custom variables section -->
<string name="library_myLibrary_owner">Owner</string>
<string name="library_myLibrary_year">2020</string>
</resources>
```

## Usage WITHOUT gradle plugin (deprecated)

If you do not want to use the gradle plugin, you need to add the legacy definition files, which will then be included in the built apk, and resolved via reflection during runtime.

> NOTE: This is not recommended. Please migrate to use the gradle plugin
```gradle
implementation "com.mikepenz:aboutlibraries-definitions:${latestAboutLibsRelease}"
```

## ProGuard

ProGuard / R8 rules are bundled internally with the core module.

> Please check the configuration in regards to passing in the fields `.withFields(R.string::class.java.fields)`
# Disclaimer

This library uses all compile time dependencies (and their sub dependencies) as defined in your `build.gradle` file,
Expand All @@ -357,36 +223,6 @@ Additional dependencies can be provided via this plugins API to extend and provi
# Used by
(feel free to send me new projects)

* [TV Time](https://play.google.com/store/apps/details?id=com.tozelabs.tvshowtime)
* [Sprit Club](https://play.google.com/store/apps/details?id=at.idev.spritpreise)
* [ML Manager](https://play.google.com/store/apps/details?id=com.javiersantos.mlmanager)
* [TurnMe Panorama](https://play.google.com/store/apps/details?id=com.bezine.panosphere)
* [Navig'Tours](https://play.google.com/store/apps/details?id=com.codetroopers.transport.tours)
* [AS Sales Management](https://play.google.com/store/apps/details?id=com.armsoft.mtrade)
* [News](https://play.google.com/store/apps/details?id=com.moblino.countrynews)
* [Makota Money Manager](https://play.google.com/store/apps/details?id=be.jatra.makota)
* [Budget Manager](https://play.google.com/store/apps/details?id=com.jakubmateusiak.budgetmanager)
* [Calendula](https://play.google.com/store/apps/details?id=es.usc.citius.servando.calendula)
* [Drinking Games](https://play.google.com/store/apps/details?id=com.drinkinggames.android)
* [Recipedia](https://play.google.com/store/apps/details?id=com.md.recipedia)
* [Ordkamp FREE](https://play.google.com/store/apps/details?id=com.betapet.mobile.dk.free)
* [Ordkamp](https://play.google.com/store/apps/details?id=com.betapet.mobile.dk.full)
* [Ordspill GRATIS](https://play.google.com/store/apps/details?id=com.ap.ordspill.free)
* [Ordspill](https://play.google.com/store/apps/details?id=com.ap.ordspill.full)
* [Betapet FREE](https://play.google.com/store/apps/details?id=com.betapet.mobile.se.free)
* [Contact Lenses Time](https://play.google.com/store/apps/details?id=com.brando.lenti)
* [HTTP Shortcuts](https://github.com/Waboodoo/HTTP-Shortcuts)
* [KAU (library)](https://allanwang.github.io/KAU/about/)
* [OneMeme: Meme Maker](https://play.google.com/store/apps/details?id=com.mememaker.android&hl)
* [andOTP](https://play.google.com/store/apps/details?id=org.shadowice.flocke.andotp)
* [MyLife - Journal](https://play.google.com/store/apps/details?id=com.pi143.mylife)
* [LibreAV](https://github.com/projectmatris/antimalwareapp)
* [Honda RoadSync](https://play.google.com/store/apps/details?id=com.honda.ms.dm.sab)
* [SimpleSettings Library](https://github.com/marcauberer/simple-settings)
* [Orna Companion](https://play.google.com/store/apps/details?id=nl.bryanderidder.ornaguide)
* [School](https://github.com/daannnnn/School)
* [Secure File Manager](https://play.google.com/store/apps/details?id=com.securefilemanager.app)

# Developed By

- Mike Penz
Expand Down

0 comments on commit 320201f

Please sign in to comment.