{"id":13902383,"url":"https://github.com/usefulness/easylauncher-gradle-plugin","last_synced_at":"2025-04-05T11:11:15.732Z","repository":{"id":37755352,"uuid":"283004535","full_name":"usefulness/easylauncher-gradle-plugin","owner":"usefulness","description":"Add a different ribbon to each of your Android app variants using this gradle plugin. Of course, configure it as you will","archived":false,"fork":false,"pushed_at":"2024-04-18T00:54:45.000Z","size":9437,"stargazers_count":379,"open_issues_count":6,"forks_count":17,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-04-18T06:57:31.981Z","etag":null,"topics":["android","debug","flavor","icon","launcher","overlay","ribbon"],"latest_commit_sha":null,"homepage":"https://medium.com/@cycki/ribbonize-your-android-application-laucher-icon-again-c52e08d58172?source=friends_link\u0026sk=4747a61844ce085a648d2116780ec4d3","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/usefulness.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2020-07-27T20:08:33.000Z","updated_at":"2024-04-20T08:30:40.915Z","dependencies_parsed_at":"2023-10-23T22:26:24.377Z","dependency_job_id":"6d3539fc-c8bd-4677-9255-f26a7a000e15","html_url":"https://github.com/usefulness/easylauncher-gradle-plugin","commit_stats":null,"previous_names":[],"tags_count":39,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usefulness%2Feasylauncher-gradle-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usefulness%2Feasylauncher-gradle-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usefulness%2Feasylauncher-gradle-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/usefulness%2Feasylauncher-gradle-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/usefulness","download_url":"https://codeload.github.com/usefulness/easylauncher-gradle-plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247325693,"owners_count":20920714,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","debug","flavor","icon","launcher","overlay","ribbon"],"created_at":"2024-08-06T22:01:07.670Z","updated_at":"2025-04-05T11:11:15.710Z","avatar_url":"https://github.com/usefulness.png","language":"Kotlin","funding_links":[],"categories":["Kotlin"],"sub_categories":[],"readme":"# Easylauncher Gradle Plugin for Android\n\n[![build](https://github.com/usefulness/easylauncher-gradle-plugin/actions/workflows/default.yml/badge.svg)](https://github.com/usefulness/easylauncher-gradle-plugin/actions/workflows/default.yml)\n\u0026nbsp;[![ktlint](https://img.shields.io/badge/code%20style-%E2%9D%A4-FF4081.svg)](https://ktlint.github.io/)\n\n[![version](https://img.shields.io/maven-metadata/v/https/plugins.gradle.org/m2/com/project/starter/easylauncher/maven-metadata.xml?label=gradle)](https://plugins.gradle.org/search?term=com.starter)\n\nModify the launcher icon of each of your app-variants using simple Gradle rules. Add ribbons of any color, overlay your own images, customize it according to your needs!\n\n| Circle | RoundedRectangle | Teardrop |\n| --- | --- | --- |\n| ![](icons/launcher_circle.png) | ![](icons/launcher_rectangle.png) | ![](icons/launcher_teardrop.png) |\n\nThis library heavily relies on the original [Akaita's easylauncher](https://github.com/akaita/easylauncher-gradle-plugin) plugin, but introduces supports for modern build tools and **Vector icons**\n\n## Usage\n\n### Basic usage\n\n```groovy\n// in app/build.gradle\nplugins {\n    id \"com.starter.easylauncher\" version \"${{version}}\"\n}\n```\nsee [Gradle Plugin Portal] for the details\n\n\u003cdetails\u003e\n  \u003csummary\u003eWhat should I do if I get `Could not resolve all artifacts` error?\u003c/summary\u003e\n    \n  In some configurations a dependency resolution error might be thrown with a message: \n  \u003e Could not find com.android.tools.build:gradle:x.x.x`.\n  \n  As a solution apply the plugin to the root project using:\n  \n```groovy\n// in root project's build.gradle \nbuildscript {\n    repositories.google()\n}\nplugins {\n    id \"com.starter.easylauncher\" version \"${{version}}\" apply false\n}\n  ```\nthen apply the plugin in your application module:\n```groovy\n// in app/build.gradle \nplugins {\n    id \"com.starter.easylauncher\"\n}\n```\n\nAlternatively, if using Version Catalog:\n```toml\n[plugins]\nstarter-easylauncher = { id = \"com.starter.easylauncher\", version.ref = \"easylauncher\" }\n```\n\nSee [related issue](https://github.com/usefulness/easylauncher-gradle-plugin/issues/80) for more information.\n  \n\u003c/details\u003e  \n\n### Advanced usage\n\nBy default, the plugin applies green ribbon for all debuggable build variants. \nYou can customize the filters applied to each type, flavor and variant of your app.  \n\nImagine these are the type and flavors of your app:\n\n```groovy\n// in app/build.gradle\nandroid {\n    buildTypes {\n        named(\"debug\") {\n            //Debuggable, will get a default ribbon in the launcher icon\n        }\n        named(\"release\") {\n            //Non-debuggable, will not get any default ribbon\n        }\n        register(\"beta\") {\n            //Debuggable, will get a default ribbon in the launcher icon\n            debuggable true\n        }\n        register('canary') {\n            //Non-debuggable, will not get any default ribbon\n            debuggable false\n        }\n    }\n    productFlavors {\n        register(\"local\") {}\n        register(\"qa\") {}\n        register(\"staging\") {}\n        register(\"production\") {}\n    }\n}\n```\n\n\nYou could customize the plugin's behaviour like this: \n\n\n```groovy\neasylauncher {\n    defaultFlavorNaming = true // Use flavor name for default ribbon, instead of the type name\n    showWarnings = true // Defines if the plugins should show warnings at configuration time\n    \n    productFlavors {\n        register(\"local\") {}\n        register(\"qa\") {\n            // Add one more filter to all `qa` variants\n            filters redRibbonFilter()\n        }\n        register(\"staging\") {}\n        register(\"production\") {}\n    }\n    \n    buildTypes {\n        register(\"beta\") {\n            // Add two more filters to all `beta` variants\n            filters = [\n                    customRibbon(ribbonColor: \"#0000FF\"),\n                    overlayFilter(file(\"example-custom/launcherOverlay/beta.png\"))\n            ]\n        }\n        register(\"canary\") {\n            // Remove ALL filters to `canary` variants\n            enable = false\n        }\n        register(\"release\") {}\n    }\n    \n    variants {\n        register(\"productionDebug\") {\n            // OVERRIDE all previous filters defined for `productionDebug` variant\n            filters = orangeRibbonFilter(\"custom\")\n        }\n    }\n}\n```\n\n#### Providing Icon Names\nBy default, the plugin **automatically** discovers launcher icon and applies provided filters.  \nCustom icon names, useful i.e. when defining multiple activity aliases, can be provided using `iconNames` property as follows:\n\n```groovy\neasylauncher {\n    iconNames = [\"@mipmap/custom_launcher_icon\"] // optional, disables automatic launcher icon discovery and will use provided icons only\n\n    buildTypes {\n        register(\"beta\") {\n            // icon names can also be provided per each configuration (buildType, productFlavor or variant)\n            iconNames = [\"@mipmap/beta_launcher\"]  \n        }\n    }\n}\n```  \n\n## Available filters\n\n## Overlay filter\n\n| Command | Result |\n| --- | --- |\n| `overlayFilter(file(\"example-custom/launcherOverlay/beta.png\"))` | ![](icons/overlay.png) |\n\n## Ribbon filters\n\n| Filter | Command | Result |\n| --- | --- | --- |\n| Gray ribbon | `grayRibbonFilter()` | ![](icons/ribbon_grey.png) |\n| Green ribbon | `greenRibbonFilter()` | ![](icons/ribbon_green.png) |\n| Yellow ribbon | `yellowRibbonFilter()` | ![](icons/ribbon_yellow.png) |\n| Orange ribbon | `orangeRibbonFilter()` | ![](icons/ribbon_orange.png) |\n| Red ribbon | `redRibbonFilter()` | ![](icons/ribbon_red.png) |\n| Blue ribbon | `blueRibbonFilter()` | ![](icons/ribbon_blue.png) |\n\n## Advanced Ribbon filter\n\n| Description | Command | Result |\n| --- | --- | --- |\n| Custom background color  | `customRibbon(ribbonColor: \"#6600CC\")` | ![](icons/ribbon_custom_background.png) |\n| Custom label | `customRibbon(label: \"label\", ribbonColor: \"#DCDCDC\")` | ![](icons/ribbon_custom_label.png) |\n| Custom text color | `customRibbon(label: \"label\", ribbonColor: \"#DCDCDC\", labelColor: \"#000000\")` | ![](icons/ribbon_custom_textcolor.png) |\n| Custom gravity - Top | `customRibbon(label: \"custom\", position: \"top\")` | ![](icons/ribbon_custom_top.png) |\n| Custom gravity - Bottom | `customRibbon(position: \"bottom\")` | ![](icons/ribbon_custom_bottom.png) |\n| Custom gravity - TopLeft | `customRibbon(position: \"topLeft\")` | ![](icons/ribbon_custom_topleft.png) |\n| Custom gravity - TopRight | `customRibbon(position: \"topRight\")` | ![](icons/ribbon_custom_topright.png) |\n| Custom text size (relative to the icon size) | `customRibbon(position: \"bottom\", textSizeRatio: 0.2)` | ![](icons/ribbon_custom_textsizeratio.png) |\n| Custom font (locally installed) | `customRibbon(position: \"top\", font: \"ComicSansMs\")` | ![](icons/ribbon_custom_font.png) |\n| Custom font (using font pack) | `customRibbon(position: \"top\", font: file(\"fonts/CustomFont.ttf\"))` | ![](icons/ribbon_custom_font.png) |\n\n\u003cdetails\u003e\n  \u003csummary\u003eTroubleshooting on \"Problem reading font data.\"\u003c/summary\u003e\n\nWhen using docker or a _minimalistic_ environment one might encounter above error message when loading Fonts.  \nThe solution is to make sure font support was installed i.e. by calling:\n```\napk add --no-cache freetype fontconfig ttf-dejavu\n```\n\nSee [related issue](https://github.com/usefulness/easylauncher-gradle-plugin/issues/201) for more information.\n\n\u003c/details\u003e  \n\n## Chrome-like filters\n\n| Filter | Command | Result |\n| --- | --- | --- |\n| Default | `chromeLike()` | ![](icons/chromelike_default.png) |\n| Custom appearance | `chromeLike(label: \"Custom\", ribbonColor: \"#FF00FF\", labelColor: \"#FFFFFF\")` | ![](icons/chromelike_custom.png) |\n| Custom font (locally installed) | `chromeLike(label: \"Custom\", font: \"ComicSansMS-Bold\")` | ![](icons/chromelike_font.png) |\n| Custom gravity - Top (with additional padding)| `chromeLike(label: \"Top\", gravity: \"Top\", labelPadding: 10)` | ![](icons/chromelike_top.png) |\n| Custom overlay/label alignment| `chromeLike(label: \"Tall\", overlayHeight: 0.6, textSizeRatio: 0.3)` | ![](icons/chromelike_tall.png) |\n\n## Available options\n\n - `defaultFlavorNaming`: use _flavor_ name in default ribbons, instead of using _buildType_\n - `enable`: enable/disable **all** filters for a flavor/type/variant\n - `productFlavors`: define filters for flavors (will be **added** to filters defined for types)\n - `buildTypes`: define filters for types (will be **added** to filter defined for flavors)\n - `variants`: define filters for variants (will **override** any other filters)\n - `iconNames`: provides a list of icons which will have the filters applied\n\n## Requirements\nMinimal requirements for the plugin are: \n- Gradle: **8.2.1**\n- Android Gradle Plugin: **8.2.2**\n- Java Version: **11**\n- minSdkVersion: **26** _(theoretically there should be no lower boundary - it just hasn't been tested)_\n\n## Project Structure\n\n```\neasylauncher/   - source code of Gradle plugin\nsample/         - root directory of supported Android applications which serve as test projects\n```\n\n## Credits\nCredits to [Akaita's easylauncher plugin](https://github.com/akaita/easylauncher-gradle-plugin) which this project heavily relies on\n\n\n[Gradle Plugin Portal]: https://plugins.gradle.org/plugin/com.starter.easylauncher\n\n---\n\n\u003cimg src=\"https://www.yourkit.com/images/yklogo.png\" alt=\"YourKit logo\" /\u003e\n\nYourKit supports open source projects with innovative and intelligent tools\nfor monitoring and profiling Java and .NET applications.\nYourKit is the creator of \u003ca href=\"https://www.yourkit.com/java/profiler/\"\u003eYourKit Java Profiler\u003c/a\u003e,\n\u003ca href=\"https://www.yourkit.com/.net/profiler/\"\u003eYourKit .NET Profiler\u003c/a\u003e,\nand \u003ca href=\"https://www.yourkit.com/youmonitor/\"\u003eYourKit YouMonitor\u003c/a\u003e.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusefulness%2Feasylauncher-gradle-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fusefulness%2Feasylauncher-gradle-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusefulness%2Feasylauncher-gradle-plugin/lists"}