From 346e77a1881122b47f6c01ef0b9ef879fb26c563 Mon Sep 17 00:00:00 2001 From: FriendlyNeighborhoodShane Date: Wed, 8 Sep 2021 04:05:45 +0530 Subject: [PATCH] *.md: reflow text to 80 cols --- INSTALL.md | 195 +++++++++++++++++++++++++++++++------------- README.md | 97 ++++++++++++++++------ conf/conf-readme.md | 98 +++++++++++++++++----- conf/custom-conf.md | 123 +++++++++++++++++++++------- res/res-readme.md | 3 +- src/src-readme.md | 6 +- 6 files changed, 388 insertions(+), 134 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index eaa193c..8e9579d 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -7,40 +7,70 @@ ### Instructions for installation ##### Chapter 1: ROM -You can skip this if you have the ROM set up already, but it's highly recommended to start with a clean install. +You can skip this if you have the ROM set up already, but it's highly +recommended to start with a clean install. - Wipe or format data from your custom recovery. - Flash your clean ROM and any other system mods you may want. ##### Chapter 2: microG -You can install MinMicroG as a Magisk module or directly to the system. If you install as a module, it will not touch system at all, and you can easily remove it when something goes wrong. On the other hand, it will be tied to the Magisk installation and can be removed with it. - - If you want MinMicroG to be installed as a Magisk module, flash Magisk and boot your phone once to allow Magisk to setup properly. +You can install MinMicroG as a Magisk module or directly to the system. If you +install as a module, it will not touch system at all, and you can easily remove +it when something goes wrong. On the other hand, it will be tied to the Magisk +installation and can be removed with it. + - If you want MinMicroG to be installed as a Magisk module, flash Magisk and + boot your phone once to allow Magisk to setup properly. - Flash MinMicroG, preferably from recovery. - - Open microG Settings > Self-Check. If "System grants signature spoofing permission" isn't ticked, click on it and grant the permission. - - In microG settings, Go to "Google device registration", "Google Cloud Messaging" and enable both of them. - - If you wish to connect to your Google account, go to Settings > Accounts > Add Accounts > Google and login to your account. + - Open microG Settings > Self-Check. If "System grants signature spoofing + permission" isn't ticked, click on it and grant the permission. + - In microG settings, Go to "Google device registration", "Google Cloud + Messaging" and enable both of them. + - If you wish to connect to your Google account, go to Settings > Accounts > + Add Accounts > Google and login to your account. - Reboot. ##### Chapter 3: UnifiedNLP - - In microG settings, go to Location modules, and enable every backend you want in "Network-based geolocation modules" and "Address lookup modules". - - Open gear icons on the backends that have it and grant all neccessary permissions and configuration. + - In microG settings, go to Location modules, and enable every backend you + want in "Network-based geolocation modules" and "Address lookup modules". + - Open gear icons on the backends that have it and grant all neccessary + permissions and configuration. - Reboot. -Most of your self-check should be checked by now. If the last one or two are not, just enable high accuracy location, open the map tab on Satstat (from FDroid) and wait until a blue circle appears. They should be okay now. +Most of your self-check should be checked by now. If the last one or two are +not, just enable high accuracy location, open the map tab on Satstat (from +FDroid) and wait until a blue circle appears. They should be okay now. ### Prerequisites ##### [microG] Signature spoofing -Sigspoofing is a feature that is required by several core features of MicroG, namely those that require pretending to be the real Google Play Services. - -All apps basically call Play Services like, "Yo, package `com.google.android.gms` with signature `x`, I need this done". So for microg to receive that message, microg needs to have the same signature. - -But since we don't have google's keys to sign the microg apk with the same signature as gapps, we add an extra feature in Android that makes microg look like it has the play services signature. The app asks, "Hey Android, is this really play services?" Android responds , "Yeah, sure". - -Of course, this is only a simplified explanation. To be more technically accurate, it patches Android's signature checking mechanism at the core. Because of that, apps can misuse the permission and compromise your device by allowing APKs from different (possibly malicious) creators to be installed over the current one. - -ROMs with a source sigspoof patch are much less dangerous in this regard because they have sigspoofing as a part of the Android runtime permissions GUI, as opposed to dexpatched ROMs, which grant it universally without any user consent. Regardless, you should carefully watch who you grant sigspoof to, and how you update that app. I am not aware of any app that legitimately requires sigspoof other than microG, fakestore, and patched Playstore. - -Because the permission has the possibility to be misused, several ROM maintainers (including LOS) have rejected putting sigspoof in the official code. But most of them have rejected it just because they are averse to trying to leave Google. Some ROMs that do include sigspoof in official builds are: +Sigspoofing is a feature that is required by several core features of MicroG, +namely those that require pretending to be the real Google Play Services. + +All apps basically call Play Services like, "Yo, package +`com.google.android.gms` with signature `x`, I need this done". So for microg +to receive that message, microg needs to have the same signature. + +But since we don't have google's keys to sign the microg apk with the same +signature as gapps, we add an extra feature in Android that makes microg look +like it has the play services signature. The app asks, "Hey Android, is this +really play services?" Android responds , "Yeah, sure". + +Of course, this is only a simplified explanation. To be more technically +accurate, it patches Android's signature checking mechanism at the core. +Because of that, apps can misuse the permission and compromise your device by +allowing APKs from different (possibly malicious) creators to be installed over +the current one. + +ROMs with a source sigspoof patch are much less dangerous in this regard +because they have sigspoofing as a part of the Android runtime permissions GUI, +as opposed to dexpatched ROMs, which grant it universally without any user +consent. Regardless, you should carefully watch who you grant sigspoof to, and +how you update that app. I am not aware of any app that legitimately requires +sigspoof other than microG, fakestore, and patched Playstore. + +Because the permission has the possibility to be misused, several ROM +maintainers (including LOS) have rejected putting sigspoof in the official +code. But most of them have rejected it just because they are averse to trying +to leave Google. Some ROMs that do include sigspoof in official builds are: * LOS for µG * AEX * AospExtended @@ -54,7 +84,9 @@ There are several other ways to have your ROM support sigspoof too: - Patching it at the source level - Easiest if you self-build or know a friendly neighborhood maintainer - Patches in microG repo - - OmniROM's commits to integrate it into Android's permissions GUI [here](https://gerrit.omnirom.org/c/android_packages_apps_PackageInstaller/+/36730) and [here](https://gerrit.omnirom.org/c/android_frameworks_base/+/36729) + - OmniROM's commits to integrate it into Android's permissions GUI + [here](https://gerrit.omnirom.org/c/android_packages_apps_PackageInstaller/+/36730) + and [here](https://gerrit.omnirom.org/c/android_frameworks_base/+/36729) - Patching it with Haystack patcher or Needle patcher - Requires PC - Using the NanoDroid-patcher standalone zip for on-device patching @@ -62,24 +94,39 @@ There are several other ways to have your ROM support sigspoof too: - Using an Xposed module called FakeGapps - Using the SmaliPatcher application on PC (shrouded in mystery) - Proprietary, windows only - - [Here](https://forum.xda-developers.com/showpost.php?p=78958124) OP of XDA thread admits they do not know of the source code, probably do not even have access to it - - [Here](https://forum.xda-developers.com/showpost.php?p=80287799), [Here](https://forum.xda-developers.com/showpost.php?p=80287989), [Here](https://forum.xda-developers.com/showpost.php?p=80292041), It connects to arbitrary Russian IPs and OP says it's probably nothing + - [Here](https://forum.xda-developers.com/showpost.php?p=78958124) OP of XDA + thread admits they do not know of the source code, probably do not even have + access to it + - [Here](https://forum.xda-developers.com/showpost.php?p=80287799), + [Here](https://forum.xda-developers.com/showpost.php?p=80287989), + [Here](https://forum.xda-developers.com/showpost.php?p=80292041), + It connects to arbitrary Russian IPs and OP says it's probably nothing ##### [microG and UNLP] Network Location Provider support Another major thing MicroG and UNLP do is providing network location to apps. -What is network location? It's a quick and rough estimate of your location, several hundred metres wide, made using cellular towers and wifi networks around you, before you get a precise GPS lock. Basically it's the wider circle that appears on your maps app quickly before a smaller accurate one appears. +What is network location? It's a quick and rough estimate of your location, +several hundred metres wide, made using cellular towers and wifi networks +around you, before you get a precise GPS lock. Basically it's the wider circle +that appears on your maps app quickly before a smaller accurate one appears. -It technically should not be needed for the functioning of most apps, but poorly coded ones that depend on Google Play Services often crash without it. +It technically should not be needed for the functioning of most apps, but +poorly coded ones that depend on Google Play Services often crash without it. -Most ROMs should support it, but some OnePlus's and Xaiomi's have other providers (like `com.qualcomm.location`) that do not allow other providers to bind with system. +Most ROMs should support it, but some OnePlus's and Xaiomi's have other +providers (like `com.qualcomm.location`) that do not allow other providers to +bind with system. If UNLP doesn't bind on your N+ ROM: - - Ask maintainer to apply this [patch](https://github.com/microg/android_packages_apps_UnifiedNlp/blob/master/patches/android_frameworks_base-N.patch) - - Make sure your the ROM looks for `com.google.android.gms` as a location provider + - Ask maintainer to apply this + [patch](https://github.com/microg/android_packages_apps_UnifiedNlp/blob/master/patches/android_frameworks_base-N.patch) + - Make sure your the ROM looks for `com.google.android.gms` as a location + provider ##### No preinstalled GApps, obviously -MinMicroG does a little debloating that may even make it work on GApps-infected ROMs, but I've never tested and give no guarantees. (Well I don't give guarantees for clean ROMs either, but that'a a different thing) +MinMicroG does a little debloating that may even make it work on GApps-infected +ROMs, but I've never tested and give no guarantees. (Well I don't give +guarantees for clean ROMs either, but that'a a different thing) Get a clean AOSP-based ROM. @@ -97,43 +144,61 @@ Or if you're a masochist, there are several ways to clean those kinds of ROMs: ### Troubleshooting ##### Not registered as system location provider -If multiple reboots do not solve this, some other provider might be overriding it, like `com.qualcomm.location`. Debloat them. If that doesn't solve it, your ROM may require source-level patches, detailed in the prerequisites section. +If multiple reboots do not solve this, some other provider might be overriding +it, like `com.qualcomm.location`. Debloat them. If that doesn't solve it, your +ROM may require source-level patches, detailed in the prerequisites section. ##### Misc network location problems -I should take these two paragraphs to clarify that Network location is NOT GPS. microG has nothing to do with your GPS. Network Location is that hugely approximated wide-circle that appears before you get a GPS Lock. +I should take these two paragraphs to clarify that Network location is NOT GPS. +microG has nothing to do with your GPS. Network Location is that hugely +approximated wide-circle that appears before you get a GPS Lock. -If you cannot get a location even on device only location mode, it's not microG. It's your app, your ROM, your device, or your cursed house. Change any of these. +If you cannot get a location even on device only location mode, it's not +microG. It's your app, your ROM, your device, or your cursed house. Change any +of these. -To test network location, enable high accuracy location, and then use satstat (from FDroid), open maps tab and wait for the blue circle to appear. +To test network location, enable high accuracy location, and then use satstat +(from FDroid), open maps tab and wait for the blue circle to appear. If it doesn't, there's a problem with UNLP. ##### Permission troubles with microG and gang -Run this command from any terminal app (like Termux) after `su`, or from a computer after `adb shell`, and then reboot: +Run this command from any terminal app (like Termux) after `su`, or from a +computer after `adb shell`, and then reboot: ``` npem; ``` -Some new permissions are protected by Android now, and cannot simply be granted. You can try several things that may or may not work, depending on your ROM: - - Extracting the MicroG APK from the zip (`system/priv-app/MicroGGMSCore/MicroGGMSCore.apk`) and installing it as an user app update +Some new permissions are protected by Android now, and cannot simply be +granted. You can try several things that may or may not work, depending on your +ROM: + - Extracting the MicroG APK from the zip + (`system/priv-app/MicroGGMSCore/MicroGGMSCore.apk`) and installing it as an + user app update - Installing MinMicroG as system instead of as a Magisk module - Clean flashing, if all else fails ##### GCM/FCM push messaging -Go to microG settings > Google Cloud Messaging and check if the app is connected. +Go to microG settings > Google Cloud Messaging and check if the app is +connected. if no: - Try wiping data for the app - - Before restoring a backup, first restore the app only (without data) and start it to register the app. After that you can restore the data. + - Before restoring a backup, first restore the app only (without data) and + start it to register the app. After that you can restore the data. If yes: - - Ensure you don't have an adblocker blocking the domain, whitelist it in adaway and similar: `mtalk.google.com` + - Ensure you don't have an adblocker blocking the domain, whitelist it in + adaway and similar: `mtalk.google.com` -If you can't get any app to register for Google Cloud Messaging, try dialing this: +If you can't get any app to register for Google Cloud Messaging, try dialing +this: `*#*#2432546#*#*` or `*#*#CHECKIN#*#*` -If you restored app data from old backups, there might be some configuration files left over preventing the app from registering for push with microG. Run this from a root terminal: +If you restored app data from old backups, there might be some configuration +files left over preventing the app from registering for push with microG. Run +this from a root terminal: ``` rm -rf /data/data/*/shared_prefs/com.google.android.gms.*.xml @@ -148,7 +213,8 @@ Go to System > Apps > Play Store If even that doesn't work: - Settings > System > Accounts > Remove Google Account - System > Accounts > Disable Account Data Synchronization - - After all is set in microG self-test after doing the above steps, open Play Store and re-add your account. + - After all is set in microG self-test after doing the above steps, open Play + Store and re-add your account. - You may have to close (recent apps > swipe it away) the Play Store once Et voila, it (hopefully) works properly again. @@ -156,18 +222,25 @@ Et voila, it (hopefully) works properly again. ### Alternatives and Suggestions ##### Contact sync -The standard package includes sync adapters that work automatically after logging in and turning on device registration. +The standard package includes sync adapters that work automatically after +logging in and turning on device registration. -But giving all your contacts to Google is not on the "top 100 ideas of all time" list. You should probably look into selfhosting. +But giving all your contacts to Google is not on the "top 100 ideas of all +time" list. You should probably look into selfhosting. You can retieve your contacts directly from your Google account in a vcf file: - Go to [Google Contacts](https://contacts.google.com) and login - Use sidebar > Export > select 'Export as VCard' > Export -You should also be able to sync contacts with Google without proprietary apps or microG using the open-source CardDAV client DAVx5 (available on F-Droid or Play) - - Go to Google Dashboard's [app passwords](https://myaccount.google.com/apppasswords) page, and create an app password if you don't have one already +You should also be able to sync contacts with Google without proprietary apps +or microG using the open-source CardDAV client DAVx5 (available on F-Droid or +Play) + - Go to Google Dashboard's + [app passwords](https://myaccount.google.com/apppasswords) page, and create + an app password if you don't have one already - When logging in with DAVx5, Use "Login with URL and user name" - - Base URL: `https://www.google.com/calendar/dav/[your_gmail_id]@gmail.com/events` + - Base URL: + `https://www.google.com/calendar/dav/[your_gmail_id]@gmail.com/events` - User name: `[your_gmail_id]@gmail.com` - Password: `[your_app_password]` @@ -176,20 +249,32 @@ You should also be able to sync contacts with Google without proprietary apps or - AsteroidOS and similar projects ##### Making miscelleneous Google Apps work -If they don't log into an account, try force stop and wipe data. Or perhaps logging out of all Google accounts, and logging in from inside the app's prompt. +If they don't log into an account, try force stop and wipe data. Or perhaps +logging out of all Google accounts, and logging in from inside the app's prompt. -If nothing else works, backing up the app from a working GApps setup and then restoring it should. Stuff like MagicGapps or WeebGApps should be helpful. +If nothing else works, backing up the app from a working GApps setup and then +restoring it should. Stuff like MagicGapps or WeebGApps should be helpful. ##### Paid apps, license verification and IAPs -You can directly buy apps from the Play Store if you have it installed with microG. But if you don't, a much cleaner way is to buy it from the [Google Play](https://play.google.com) website through a browser. +You can directly buy apps from the Play Store if you have it installed with +microG. But if you don't, a much cleaner way is to buy it from the +[Google Play](https://play.google.com) website through a browser. -If you've bought an app, you can download it without Play Store by using Aurora Store by logging in with your own account. +If you've bought an app, you can download it without Play Store by using Aurora +Store by logging in with your own account. -License verification, unfortunately, is something tied to Play Store and probably always will be. If you don't want to install it, all you can do is pester the devs to remove it or atleast offer alternative means of verification. - - The Titanium Backup devs are a bunch of nice people. If you email them, they'll give you offline verification codes. +License verification, unfortunately, is something tied to Play Store and +probably always will be. If you don't want to install it, all you can do is +pester the devs to remove it or atleast offer alternative means of verification. + - The Titanium Backup devs are a bunch of nice people. If you email them, + they'll give you offline verification codes. -In App Purchases are even more tied to Play Store. Not even vanilla Play Store will do, it has to be patched for sigspoofing to be able to use IAPs. Setialpha regularly grabs the latest release and patches it, and the product can be found in the NanoDroid F-Droid repository. +In App Purchases are even more tied to Play Store. Not even vanilla Play Store +will do, it has to be patched for sigspoofing to be able to use IAPs. Setialpha +regularly grabs the latest release and patches it, and the product can be found +in the NanoDroid F-Droid repository. ##### Making swipe work on AOSP keyboard -If you do not wish to switch to the superior AnySoft keyboard and the swipe libs don't work with AOSP kb on your ROM, try this: +If you do not wish to switch to the superior AnySoft keyboard and the swipe +libs don't work with AOSP kb on your ROM, try this: https://forum.xda-developers.com/android/apps-games/enhancedime-aosp-latinime-enhancements-t3366639 diff --git a/README.md b/README.md index 00c1984..032f21f 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,12 @@ * [microG user group](https://t.me/microg) on Telegram ### What is this? -This is a simple MicroG installer. It can install MicroG and other stuff into your system partition or as a Magisk module. It supports virtually all mobile architectures (arm/64, x86/64, mips/64) and fully supports KitKat and above. It can also (mostly) support much older versions, but sync adapters and some location providers won't work. It can even uninstall itself from your device, just rename it and flash it again. +This is a simple MicroG installer. It can install MicroG and other stuff into +your system partition or as a Magisk module. It supports virtually all mobile +architectures (arm/64, x86/64, mips/64) and fully supports KitKat and above. It +can also (mostly) support much older versions, but sync adapters and some +location providers won't work. It can even uninstall itself from your device, +just rename it and flash it again. The things included in the `Standard` Edition zip are: - MicroG (GMSCore, GSFProxy, Maps APIv1) (from MicroG FDroid repo) @@ -61,23 +66,46 @@ The things included in the `AuroraServices` Edition zip are: - An addon.d file to backup/restore everything on a rom flash ### Notes -Dirty flashing not recommended. you'll mess up all your permissions and may even cause conflicts in app data, leading to crashes. -The maker does not support or endorse dirty flashing. It will harm you and your loved ones. Don't come complaining to me. +Dirty flashing not recommended. you'll mess up all your permissions and may +even cause conflicts in app data, leading to crashes. +The maker does not support or endorse dirty flashing. It will harm you and your +loved ones. Don't come complaining to me. How to control the zip by changing its name: -NOTE: Control by name is not possible in Magisk Manager, since it copies the zip to a cache directory and renames it install.zip. This is unavoidable behaviour. - - - Add `system` to its filename to force it to install/uninstall from system. Otherwise, it looks for Magisk, and if not found, installs to system. Obviously, if you flash it through Magisk Manager, you want to install it to Magisk. If not, you have to flash it through recovery. - - Remember that choosing Magisk mode (which is the default if Magisk is installed already) will remove the MinMicroG package if you uninstall Magisk. - - - Add `uninstall` to its filename to uninstall it from your device, whether in Magisk mode or system mode. If you use Magisk Manager, your preffered method of uninstallation is from there. - -Just rename it and flash it again for the intended effect. For example, `MinMicroG-variant-version-signed.zip` to `system-MinMicroG-variant-version-signed.zip` (and the same for uninstall). - -NOTE: If you have made a system install but have Magisk installed as well, you will have to use both `system` and `uninstall` keywords in the name for an uninstall flash. - -The zip debloats three specific Google apps from your phone (GmsCore, GoogleServicesFramework, Phonesky and their MicroG counterparts) and 4 NLP providers when the pack contents conflicts with them. In Magisk mode, they won't be removed from system, and if you uninstall the pack, they'll come back. If you install in system, the debloated stuff will be stored in `internal-storage/MinMicroG/Backup`. -WARNING: This zip does not and never will debloat anything else because that is the minimum coming in MicroG's way. I have had my own share of PTSD with debloating. I believe (through instinct) that it should work even on flashes over GApped ROMs, but don't take my word for it. Debloat before you flash. +NOTE: Control by name is not possible in Magisk Manager, since it copies the +zip to a cache directory and renames it install.zip. This is unavoidable +behaviour. + + - Add `system` to its filename to force it to install/uninstall from system. + Otherwise, it looks for Magisk, and if not found, installs to system. + Obviously, if you flash it through Magisk Manager, you want to install it to + Magisk. If not, you have to flash it through recovery. + - Remember that choosing Magisk mode (which is the default if Magisk is + installed already) will remove the MinMicroG package if you uninstall + Magisk. + + - Add `uninstall` to its filename to uninstall it from your device, whether in + Magisk mode or system mode. If you use Magisk Manager, your preffered method + of uninstallation is from there. + +Just rename it and flash it again for the intended effect. For example, +`MinMicroG-variant-version-signed.zip` to +`system-MinMicroG-variant-version-signed.zip` (and the same for uninstall). + +NOTE: If you have made a system install but have Magisk installed as well, you +will have to use both `system` and `uninstall` keywords in the name for an +uninstall flash. + +The zip debloats three specific Google apps from your phone (GmsCore, +GoogleServicesFramework, Phonesky and their MicroG counterparts) and 4 NLP +providers when the pack contents conflicts with them. In Magisk mode, they +won't be removed from system, and if you uninstall the pack, they'll come back. +If you install in system, the debloated stuff will be stored in +`internal-storage/MinMicroG/Backup`. +WARNING: This zip does not and never will debloat anything else because that is +the minimum coming in MicroG's way. I have had my own share of PTSD with +debloating. I believe (through instinct) that it should work even on flashes +over GApped ROMs, but don't take my word for it. Debloat before you flash. For support with flashing: If you flashed through recovery, provide its logs. @@ -103,24 +131,39 @@ To build all the packs and place them in the `releases` directory. That's it! If it tells you that some dependency is missing, install it. -You can pass `update.sh` several extended regexes as arguments to only download specific files. -You can pass `build.sh` some specific pack's conf names instead of all to build only the specific packs. +You can pass `update.sh` several extended regexes as arguments to only download +specific files. +You can pass `build.sh` some specific pack's conf names instead of all to build +only the specific packs. -If you have `apksigner` and `openssl` installed, the update script will dump the signing certificates of all downloaded APKs and repo jars to `resdl/util/certs`. It will compare all future downloads with those certs, and in case of any signature errors or mismatches, will warn you. +If you have `apksigner` and `openssl` installed, the update script will dump +the signing certificates of all downloaded APKs and repo jars to +`resdl/util/certs`. It will compare all future downloads with those certs, and +in case of any signature errors or mismatches, will warn you. -If you have `aapt` installed, the update script will download the permission docs from the Android website, check the priv-apps for any new privileged permissions and tell you to add them to the whitelist in `res/system/etc/permissions/[package].xml` files. +If you have `aapt` installed, the update script will download the permission +docs from the Android website, check the priv-apps for any new privileged +permissions and tell you to add them to the whitelist in +`res/system/etc/permissions/[package].xml` files. To build your own custom pack, refer to `conf/custom-conf.md`. -Any changes made to the code should ideally be tested with `test.sh`, which runs the `shellcheck` linter program on every script. +Any changes made to the code should ideally be tested with `test.sh`, which +runs the `shellcheck` linter program on every script. -Use `bump.sh` to automatically bump the `ver`, `verc` and `date` values across all defconf files. +Use `bump.sh` to automatically bump the `ver`, `verc` and `date` values across +all defconf files. ### Credits - - Thanks to @osm0sis for the base magisk/recovery code and inspiration and guidance on the majority of the stuff in here. - - Thanks to @Setialpha, the creator of NanoDroid, and ale5000 for the lib installation code, permissions code, and patched play. - - Thanks to FDroid and the MicroG project for actively resisting monopoly and control so we can actually use our devices without fear. + - Thanks to @osm0sis for the base magisk/recovery code and inspiration and + guidance on the majority of the stuff in here. + - Thanks to @Setialpha, the creator of NanoDroid, and ale5000 for the lib + installation code, permissions code, and patched play. + - Thanks to FDroid and the MicroG project for actively resisting monopoly and + control so we can actually use our devices without fear. - Thanks to Whyorean for his amazing works in the form of the Aurora Apps. - - Thanks to my friends over at NoGoolag for their help and patience over however long it took me to learn to do shit without "rm -rf /"-ing devices. + - Thanks to my friends over at NoGoolag for their help and patience over + however long it took me to learn to do shit without "rm -rf /"-ing devices. -And most of all, thank you Google & gang for being so shitty to people and thus giving us a mission. +And most of all, thank you Google & gang for being so shitty to people and thus +giving us a mission. diff --git a/conf/conf-readme.md b/conf/conf-readme.md index 7c8df5f..553719d 100644 --- a/conf/conf-readme.md +++ b/conf/conf-readme.md @@ -2,28 +2,70 @@ All the config files for packs. -Every pack is built and installed according to a config file. A config file is supposed to be a simple shell script setting some variables and functions. It's not supposed to execute any command, which is important, as it is executed by both the building process on the building device and the flashing process on the flashing device. +Every pack is built and installed according to a config file. A config file is +supposed to be a simple shell script setting some variables and functions. It's +not supposed to execute any command, which is important, as it is executed by +both the building process on the building device and the flashing process on +the flashing device. -All the config files are named as `defconf-[name].txt` where `[name]` is the argument you'll pass to `build.sh` to build a pack using that config file. -The `resdl-download.txt` file is a special config that is read by `update.sh` to download all the relevant dynamic assets. -The rest of the files here are code snippets you might find useful to put in install actions. +All the config files are named as `defconf-[name].txt` where `[name]` is the +argument you'll pass to `build.sh` to build a pack using that config file. +The `resdl-download.txt` file is a special config that is read by `update.sh` +to download all the relevant dynamic assets. +The rest of the files here are code snippets you might find useful to put in +install actions. For making your own pack and config file, check `conf/custom-conf.md`. ## Variables in defconf files - - `variant`: The name that will be in the filename of the released zip as well as will be shown on installation. It does not have to be related to the name of the defconf file (for example the `defconf-unlp.txt` file has variant "Backend" and creates the `MinMicroG-Backend-*-*.zip` package). Any string without whitespace will do. - - `ver`: The version number of the package, which is shown in the release filename and during installation. It can be anything except whitespace, but for convenience is integers along with decimals. - - `verc`: The version code for the package. It's only really used in Magisk installations's `mod.prop`, where Magisk compares it to decide if a version of the module is newer than the installed version. It strictly has to be an integer. - - `date`: The date of releasing the specific pack version, shown on installation. - - `minsdk`: The minimum Android SDK version the pack supports fully. It'll still install below that, but will show a warning to the user. - - `modprop`: The variable containing the entirety of Magisk's `mod.prop`, which will appear in your installed modules. Nothing really important here except `verc`, which is described above, and `id`, which has to be the same as `modname` variable from `update-binary`. - - `stuff`, `stuff_arch`, `stuff_sdk`, `stuff_arch_sdk`: Stuff variables are really space/tab-separated lists of all the objects (Relative to the root of the zip during flashing, or relative to either `res` or `resdl` directories in the build process) that are installed to be installed to device. It is going to be put through a for loop, so no whitespace is to be used in a single entry. Luckily, android system files aren't supposed to have spaces in their names/paths. For files in `stuff`, the file with that path is grabbed directly from `res` or `resdl` (in ascending priority), while for the other arrays, the files are grabbed from `$(dirname [path])/-*-/$(basename [path])`. - - `stuff_util`: Same whitespace-separated list as above, but for things that should be grabbed from `res` or `resdl` during building, but not placed during installation. Could be used for extra tools used in the hook funcs. - - `stuff_other`, `stuff_old`: Just lists of stuff from other packs and stuff that used to be in any of the packs that I made for organisation. They have no purpose other than to be merged in `stuff_uninstall`. - - `stuff_uninstall`: Everything in this list is removed from system during a system installation and uninstallation. Should include everything in the pack, along with anything that used to be in it and anything that might be from alternative conflicting packs. - - `stuff_debloat`: Anything not from these packs that might conflict with it. For example GApps, other location providers, etc. They are removed (and backed up) during a system install and pseudo-debloated during a Magisk install. - - `stuff_perm`: Subdirectories of `/system` on which permission are to be applied in case of a system installation. This variable exists because perming the whole system takes too long. + - `variant`: The name that will be in the filename of the released zip as well + as will be shown on installation. It does not have to be related to the name + of the defconf file (for example the `defconf-unlp.txt` file has variant + "Backend" and creates the `MinMicroG-Backend-*-*.zip` package). Any string + without whitespace will do. + - `ver`: The version number of the package, which is shown in the release + filename and during installation. It can be anything except whitespace, but + for convenience is integers along with decimals. + - `verc`: The version code for the package. It's only really used in Magisk + installations's `mod.prop`, where Magisk compares it to decide if a version + of the module is newer than the installed version. It strictly has to be an + integer. + - `date`: The date of releasing the specific pack version, shown on + installation. + - `minsdk`: The minimum Android SDK version the pack supports fully. It'll + still install below that, but will show a warning to the user. + - `modprop`: The variable containing the entirety of Magisk's `mod.prop`, + which will appear in your installed modules. Nothing really important here + except `verc`, which is described above, and `id`, which has to be the same + as `modname` variable from `update-binary`. + - `stuff`, `stuff_arch`, `stuff_sdk`, `stuff_arch_sdk`: Stuff variables are + really space/tab-separated lists of all the objects (Relative to the root of + the zip during flashing, or relative to either `res` or `resdl` directories + in the build process) that are installed to be installed to device. It is + going to be put through a for loop, so no whitespace is to be used in a + single entry. Luckily, android system files aren't supposed to have spaces + in their names/paths. For files in `stuff`, the file with that path is + grabbed directly from `res` or `resdl` (in ascending priority), while for + the other arrays, the files are grabbed from + `$(dirname [path])/-*-/$(basename [path])`. + - `stuff_util`: Same whitespace-separated list as above, but for things that + should be grabbed from `res` or `resdl` during building, but not placed + during installation. Could be used for extra tools used in the hook funcs. + - `stuff_other`, `stuff_old`: Just lists of stuff from other packs and stuff + that used to be in any of the packs that I made for organisation. They have + no purpose other than to be merged in `stuff_uninstall`. + - `stuff_uninstall`: Everything in this list is removed from system during a + system installation and uninstallation. Should include everything in the + pack, along with anything that used to be in it and anything that might be + from alternative conflicting packs. + - `stuff_debloat`: Anything not from these packs that might conflict with it. + For example GApps, other location providers, etc. They are removed (and + backed up) during a system install and pseudo-debloated during a Magisk + install. + - `stuff_perm`: Subdirectories of `/system` on which permission are to be + applied in case of a system installation. This variable exists because + perming the whole system takes too long. ## Functions in defconf files @@ -34,12 +76,30 @@ For making your own pack and config file, check `conf/custom-conf.md`. - `pre_uninstall_actions()` - `post_uninstall_actions()` -Pretty self explanatory. Leave them blank with a `return 0` if there's no use for them, not having them at all will cause errors. +Pretty self explanatory. Leave them blank with a `return 0` if there's no use +for them, not having them at all will cause errors. ## Variables in `resdl-conf.txt` - - `stuff_repos`: List of FDroid format app repositories that are to be downloaded and their contents used by `update.sh`. First column has their names, which are to be unique and are the key to access them in `stuff_download`. Second column is the URL, to which appending "/index-v1.jar" should result in an object downloadable by `curl`. - - `stuff_download`: List of actual objects that are put into `resdl` by `update.sh`. First column is the filepath inside `resdl` that it should be put in. Second column is the source that it comes from, which is one of `local`, `direct`, `github`, `gitlab`, or `repo`. Other columns depend upon the source and any extra columns are ignored. For `local`, third column is a path resolved against the repo directory from which the file is `cp`'d to the destination. For `direct`, the third column is a URL that must be downloadable using `curl`. For `github` and `gitlab`, the third column is `[repo owner]/[repo name]` from which the newest file is grabbed from the releases page, optionally filtering only for the regex-enabled suffix in the fourth column if provided. For repo, it's the `[repo key]/[package name]` of which the latest APK is grabbed, optionally filtering for the arch and minimum SDK if provided in the third column in the format `ARCH:SDK` (one of these variables can be ommitted but not the colon). + - `stuff_repos`: List of FDroid format app repositories that are to be + downloaded and their contents used by `update.sh`. First column has their + names, which are to be unique and are the key to access them in + `stuff_download`. Second column is the URL, to which appending "/index-v1.jar" + should result in an object downloadable by `curl`. + - `stuff_download`: List of actual objects that are put into `resdl` by + `update.sh`. First column is the filepath inside `resdl` that it should be + put in. Second column is the source that it comes from, which is one of + `local`, `direct`, `github`, `gitlab`, or `repo`. Other columns depend upon + the source and any extra columns are ignored. For `local`, third column is + a path resolved against the repo directory from which the file is `cp`'d to + the destination. For `direct`, the third column is a URL that must be + downloadable using `curl`. For `github` and `gitlab`, the third column is + `[repo owner]/[repo name]` from which the newest file is grabbed from the + releases page, optionally filtering only for the regex-enabled suffix in the + fourth column if provided. For repo, it's the `[repo key]/[package name]` of + which the latest APK is grabbed, optionally filtering for the arch and minimum + SDK if provided in the third column in the format `ARCH:SDK` (one of these + variables can be ommitted but not the colon). ## Functions in resdl-conf file diff --git a/conf/custom-conf.md b/conf/custom-conf.md index 800c33a..12280e7 100644 --- a/conf/custom-conf.md +++ b/conf/custom-conf.md @@ -1,61 +1,122 @@ # Custom pack guide -The MinMicrog update, build, and install scripts were written with one primary goal in mind: To be completely abstracted from any files being processed using it (of course, along with being fast and widely supported), which is its primary advantage in use cases over any other similar Android flashable mods (besides helping me in staying lazy). What is being installed doesn't matter to the installer; All it needs are a few variables in a text file telling it what files to do stuff to and it'll do its job (as smartly as I could think of). What all this means, my dear fellow, is that you can whip up a quick conf file to make MinMicroG build any kind of flashable zip within minutes. - -To prove this, we're gonna write a new config and resdl-download file for an entirely new and relatively simple pack: the AuroraServices package containing just AuroraServices along with a perm file. - -If you've read through this document (or perhaps want to play Russian roulette with `rm` and your device), there is a blank config file in `defconf-dummy.txt` that you can fill in. +The MinMicrog update, build, and install scripts were written with one primary +goal in mind: To be completely abstracted from any files being processed using +it (of course, along with being fast and widely supported), which is its +primary advantage in use cases over any other similar Android flashable mods +(besides helping me in staying lazy). What is being installed doesn't matter to +the installer; All it needs are a few variables in a text file telling it what +files to do stuff to and it'll do its job (as smartly as I could think of). +What all this means, my dear fellow, is that you can whip up a quick conf file +to make MinMicroG build any kind of flashable zip within minutes. + +To prove this, we're gonna write a new config and resdl-download file for an +entirely new and relatively simple pack: the AuroraServices package containing +just AuroraServices along with a perm file. + +If you've read through this document (or perhaps want to play Russian roulette +with `rm` and your device), there is a blank config file in `defconf-dummy.txt` +that you can fill in. ### `update.sh` and `resdl-download.txt` -First, before making a pack, we gotta get the Aurora APK files from somewhere. We could've just downloaded and put them in the `res` directory, but they'd need to be updated and I'm lazy, so no. - -What `update.sh` does for me is get everything I would need for a pack itself from a list of predefined sources and puts them in their proper places in the `resdl` directory so the build script picks them up. Now, `update.sh` knows what to get by executing and getting the variables from `conf/resdl-download.txt` (open it and see), so we're gonna add a few lines to it to get the Aurora APKs downloaded automatically when we run the script. - -We could get them from FDroid, but their releases are usually out of date and I trust Whyorean so we're gonna grab them from his GitLab page. Fortunately, he has precompiled binaries on his releases page. - -Now, we don't need any new FDroid repo for this, so we leave the `stuff_repos` list untouched. But we're gonna change `stuff_download`. - -For AuroraServices, we'll be keeping the file at path `/system/priv-app/AuroraServices/AuroraServices.apk` (inside `resdl`). The URL for the project is `https://gitlab.com/AuroraOSS/AuroraServices` at the official gitlab server, so our source type is `gitlab` and source path is `AuroraOSS/AuroraServices`. So we add the line: +First, before making a pack, we gotta get the Aurora APK files from somewhere. +We could've just downloaded and put them in the `res` directory, but they'd +need to be updated and I'm lazy, so no. + +What `update.sh` does for me is get everything I would need for a pack itself +from a list of predefined sources and puts them in their proper places in the +`resdl` directory so the build script picks them up. Now, `update.sh` knows +what to get by executing and getting the variables from +`conf/resdl-download.txt` (open it and see), so we're gonna add a few lines to +it to get the Aurora APKs downloaded automatically when we run the script. + +We could get them from FDroid, but their releases are usually out of date and I +trust Whyorean so we're gonna grab them from his GitLab page. Fortunately, he +has precompiled binaries on his releases page. + +Now, we don't need any new FDroid repo for this, so we leave the `stuff_repos` +list untouched. But we're gonna change `stuff_download`. + +For AuroraServices, we'll be keeping the file at path +`/system/priv-app/AuroraServices/AuroraServices.apk` (inside `resdl`). The URL +for the project is `https://gitlab.com/AuroraOSS/AuroraServices` at the +official gitlab server, so our source type is `gitlab` and source path is +`AuroraOSS/AuroraServices`. So we add the line: ``` /system/priv-app/AuroraServices/AuroraServices.apk gitlab AuroraOSS/AuroraServices ``` To `stuff_download`. -But ding-ding! When you run the script, you may or may not notice that you may or may not get a valid APK file as the result. Why is that? open AuroraServices's GitLab releases page for yourself and see. The problem is that Whyorean provides a Flashable zip with each release too! How considerate. But that's a problem for the script, because as you may or may not have seen, our poor `update.sh` can get confused between different files in a release, and we can't exactly blame it; It has no way to know what we wanted and what we got are different, it's simply grabbing the latest file from a release's attachments. - -Fortunately, I am wise. I foresaw this situation, and so I added a way to filter through the release files from a GitLab page. All we have to do is add a `.apk` in the fourth column, so that `update.sh` will first filter all the release attachments into only those having .apk at the end, and then grab the latest of them. So what we have to change that entry into is: +But ding-ding! When you run the script, you may or may not notice that you may +or may not get a valid APK file as the result. Why is that? open +AuroraServices's GitLab releases page for yourself and see. The problem is that +Whyorean provides a Flashable zip with each release too! How considerate. But +that's a problem for the script, because as you may or may not have seen, our +poor `update.sh` can get confused between different files in a release, and we +can't exactly blame it; It has no way to know what we wanted and what we got +are different, it's simply grabbing the latest file from a release's +attachments. + +Fortunately, I am wise. I foresaw this situation, and so I added a way to +filter through the release files from a GitLab page. All we have to do is add a +`.apk` in the fourth column, so that `update.sh` will first filter all the +release attachments into only those having .apk at the end, and then grab the +latest of them. So what we have to change that entry into is: ``` /system/priv-app/AuroraServices/AuroraServices.apk gitlab AuroraOSS/AuroraServices .apk ``` -Note that while here I am using a simple suffix for this filtering since there are no other APKs to be confused by, you can also use a more complicated extended regex like `AuroraServices-v[.1-9]*.apk` to protect against future additional APKs in the releases. -Also note that exact same behaviour applies to the fourth column for the `github` source type. -Additionally note that the fourth column for the `repo` source type has a different function but similar purpose; It is the architecture and minimum SDK level to filter all the available APKs by. - -Now, when we run `update.sh`, as long as the internet is still up, we will get a correct AuroraServices.apk where we wanted. +Note that while here I am using a simple suffix for this filtering since there +are no other APKs to be confused by, you can also use a more complicated +extended regex like `AuroraServices-v[.1-9]*.apk` to protect against future +additional APKs in the releases. +Also note that exact same behaviour applies to the fourth column for the +`github` source type. +Additionally note that the fourth column for the `repo` source type has a +different function but similar purpose; It is the architecture and minimum SDK +level to filter all the available APKs by. + +Now, when we run `update.sh`, as long as the internet is still up, we will get +a correct AuroraServices.apk where we wanted. ### `build.sh` and `defconf-aurora.txt` -For a new pack, we make a new defconf file. Note that the name in the defconf file is only used to execute the build command, the name of the zip in releases will be using the `variant` variable in the defconf. Open the `defconf-aurora.txt` file and see what the final result is. +For a new pack, we make a new defconf file. Note that the name in the defconf +file is only used to execute the build command, the name of the zip in releases +will be using the `variant` variable in the defconf. Open the +`defconf-aurora.txt` file and see what the final result is. -NOTE: I only reccomend doing this if you're familiar with shell scripts. DO NOT execute anything directly in the file; it is executed at both build time and flash time, so I hope it's obvious that's a bad idea. +NOTE: I only reccomend doing this if you're familiar with shell scripts. DO NOT +execute anything directly in the file; it is executed at both build time and +flash time, so I hope it's obvious that's a bad idea. - First, we set the `variant` variable to "AuroraServices". - - Then, we set `ver`, `verc`, and `date` to the correct values, considering that `verc` has to be an integer. + - Then, we set `ver`, `verc`, and `date` to the correct values, considering + that `verc` has to be an integer. - Since Services only supports lollipop and above, we set `minsdk` to `21`. - - Then we fill up the empty values in `modprop`, seeing as `id` has to be the `modname` defined in `update-binary`, and the Magisk module template is at `1900`. + - Then we fill up the empty values in `modprop`, seeing as `id` has to be the + `modname` defined in `update-binary`, and the Magisk module template is at + `1900`. - - Since we have only two files (I wrote up the perm file) to be installed and they both are the same for various architectures and SDKs, we just add them to `stuff`. -(To understand how the others like `stuff_arch` and `stuff_sdk` work, I'd recommend running `update.sh` and looking at the keyboard swipe and contact sync files.) + - Since we have only two files (I wrote up the perm file) to be installed and + they both are the same for various architectures and SDKs, we just add them + to `stuff`. + (To understand how the others like `stuff_arch` and `stuff_sdk` work, I'd + recommend running `update.sh` and looking at the keyboard swipe and contact + sync files.) - - They don't have anything they conflict with, so nothing to add to `stuff_debloat`. + - They don't have anything they conflict with, so nothing to add to + `stuff_debloat`. - - We need to add permissions to the two files, so we add their respective directories to `stuff_perm`. + - We need to add permissions to the two files, so we add their respective + directories to `stuff_perm`. - - We don't have anything special to do with this package, so nothing in the build or install functions. But we don't remove the functions completely, that would cause an error. + - We don't have anything special to do with this package, so nothing in the + build or install functions. But we don't remove the functions completely, + that would cause an error. There, we have the config file for our brand new AuroraServices pack! diff --git a/res/res-readme.md b/res/res-readme.md index 8fc98fa..fc491e3 100644 --- a/res/res-readme.md +++ b/res/res-readme.md @@ -1,3 +1,4 @@ -Put all static or manually updated binary assets in the `system` or `util` folder here. +Put all static or manually updated binary assets in the `system` or `util` +folder here. Automagically updated assets go in `resdl` instead. diff --git a/src/src-readme.md b/src/src-readme.md index bddfef6..8a780b2 100644 --- a/src/src-readme.md +++ b/src/src-readme.md @@ -1,3 +1,7 @@ The main scripts for MinMicroG installer. -The recovery or Magisk Manager execute `update-binary`, which unzips and executes defconf from the zip's root directory, and... does stuff. I hope to have better docs about it someday, but for now, I've made sure you won't have to deal with it even if you want to make a new pack. I've also tried to keep it simple and readable, even if I failed miserably in several places. +The recovery or Magisk Manager execute `update-binary`, which unzips and +executes defconf from the zip's root directory, and... does stuff. I hope to +have better docs about it someday, but for now, I've made sure you won't have +to deal with it even if you want to make a new pack. I've also tried to keep it +simple and readable, even if I failed miserably in several places.