README: document do.systemless, update and sync with XDA thread

1 files changed, 37 insertions, 15 deletions

diff --git a/README.md b/README.md
index d287694..7d90b31 100644
--- a/README.md
+++ b/README.md
@@ -5,20 +5,22 @@ AnyKernel3 - Flashable Zip Template for Kernel Releases with Ramdisk Modificatio
 
 "AnyKernel is a template for an update.zip that can apply any kernel to any ROM, regardless of ramdisk." - Koush
 
-AnyKernel3 pushes the format even further by allowing kernel developers to modify the underlying ramdisk for kernel feature support easily using a number of included command methods along with properties and variables.
+AnyKernel2 pushed the format further by allowing kernel developers to modify the underlying ramdisk for kernel feature support easily using a number of included command methods along with properties and variables to customize the installation experience to their kernel. AnyKernel3 adds the power of topjohnwu's magiskboot for wider format support by default, and to automatically detect and retain Magisk root by patching the new Image.*-dtb as Magisk would.
 
-_A script based on Galaxy Nexus (tuna) is included for reference._
+_A script based on Galaxy Nexus (tuna) is included for reference. Everything to edit is self-contained in __anykernel.sh__._
 
 ## // Properties / Variables ##
 ```
 kernel.string=KernelName by YourName @ xda-developers
 do.devicecheck=1
 do.modules=1
+do.systemless=1
 do.cleanup=1
 do.cleanuponabort=0
 device.name1=maguro
 device.name2=toro
 device.name3=toroplus
+device.name4=tuna
 supported.versions=6.0 - 7.1.2
 supported.patchlevels=2019-07 -
 
@@ -27,13 +29,15 @@ is_slot_device=0;
 ramdisk_compression=auto;
 ```
 
-__do.devicecheck=1__ specified requires at least device.name1 to be present. This should match ro.product.device or ro.build.product for your device. There is support for as many device.name# properties as needed. You may remove any empty ones that aren't being used.
+__do.devicecheck=1__ specified requires at least device.name1 to be present. This should match ro.product.device, ro.build.product, ro.product.vendor.device or ro.vendor.product.device from the build.prop files for your device. There is support for as many device.name# properties as needed. You may remove any empty ones that aren't being used.
 
-__do.modules=1__ will push the contents of the module directory to the same location relative to root (/) and apply 644 permissions.
+__do.modules=1__ will push the .ko contents of the modules directory to the same location relative to root (/) and apply correct permissions. On A/B devices this can only be done to the active slot.
 
-__do.cleanup=0__ will keep the zip from removing it's working directory in /tmp/anykernel (by default) - this can be useful if trying to debug in adb shell whether the patches worked correctly.
+__do.systemless=1__ (with __do.modules=1__) will instead push the full contents of the modules directory to create a simple "ak3-helper" Magisk module, allowing developers to effectively replace system files, including .ko files. If the current kernel is changed then the kernel helper module automatically removes itself to prevent conflicts.
 
-__do.cleanuponabort=0__ will keep the zip from removing it's working directory in /tmp/anykernel (by default) in case of installation abort.
+__do.cleanup=0__ will keep the zip from removing its working directory in /tmp/anykernel (by default) - this can be useful if trying to debug in adb shell whether the patches worked correctly.
+
+__do.cleanuponabort=0__ will keep the zip from removing its working directory in /tmp/anykernel (by default) in case of installation abort.
 
 __supported.versions=__ will match against ro.build.version.release from the current ROM's build.prop. It can be set to a list or range. As a list of one or more entries, e.g. `7.1.2` or `8.1.0, 9` it will look for exact matches, as a range, e.g. `7.1.2 - 9` it will check to make sure the current version falls within those limits. Whitespace optional, and supplied version values should be in the same number format they are in the build.prop value for that Android version.
 
@@ -49,8 +53,6 @@ __supported.patchlevels=__ will match against ro.build.version.security_patch fr
 
 `slot_select=active|inactive` may be added to allow specifying the target slot. If omitted the default remains `active`.
 
-_Note: Currently pushing modules is to the active slot only._
-
 ## // Command Methods ##
 ```
 ui_print "<text>" [...]
@@ -103,7 +105,7 @@ __"block|mount|fstype|options|flags"__ requires you specify which part (listed i
 
 _dump_boot_ and _write_boot_ are the default method of unpacking/repacking, but for more granular control, or omitting ramdisk changes entirely ("OG AK" mode), these can be separated into _split_boot; unpack_ramdisk_ and _repack_ramdisk; flash_boot_ respectively. _flash_dtbo_ can be used to flash a dtbo image. It is automatically included in _write_boot_ but can be called separately if using "OG AK" mode or creating a dtbo only zip.
 
-Multi-partition zips can be created by removing the ramdisk and patch folders from the zip and including instead "-files" folders named for the partition (without slot suffix), e.g. boot-files + recovery-files, or kernel-files + ramdisk-files (on some Treble devices). These then contain zImage, and ramdisk, patch, etc. subfolders for each partition. To setup for the next partition, simply set `block=` (without slot suffix) and `ramdisk_compression=` for the new target partition and use the _reset_ak_ command.
+Multi-partition zips can be created by removing the ramdisk and patch folders from the zip and including instead "-files" folders named for the partition (without slot suffix), e.g. boot-files + recovery-files, or kernel-files + ramdisk-files (on some Treble devices). These then contain Image.gz, and ramdisk, patch, etc. subfolders for each partition. To setup for the next partition, simply set `block=` (without slot suffix) and `ramdisk_compression=` for the new target partition and use the _reset_ak_ command.
 
 Similarly, multi-slot zips can be created with the normal zip layout for the active (current) slot, then resetting for the inactive slot by setting `block=` (without slot suffix) again, `slot_select=inactive` and `ramdisk_compression=` for the target slot and using the _reset_ak keep_ command, which will retain the patch and any added ramdisk files for the next slot.
 
@@ -134,13 +136,13 @@ Optionally moving ARM builds to tools/arm and putting x86 builds in tools/x86 wi
 
 ## // Instructions ##
 
-1. Place final kernel build product, e.g. Image.gz-dtb or zImage to name a couple, in the zip root (separate dt, dtb or recovery_dtbo, and/or dtbo should also go here for devices that require custom ones, each will fallback to the original if not included)
+1. Place final kernel build product, e.g. Image.gz-dtb or zImage to name a couple, in the zip root (any separate dt, dtb or recovery_dtbo, and/or dtbo should also go here for devices that require custom ones, each will fallback to the original if not included)
 
-2. Place any required ramdisk files in /ramdisk and modules in /modules (with the full path like /modules/system/lib/modules)
+2. Place any required ramdisk files in /ramdisk and module files in /modules (with the full path like /modules/system/lib/modules)
 
 3. Place any required patch files (generally partial files which go with AK3 file editing commands) in /patch
 
-4. Modify the anykernel.sh to add your kernel's name, boot partition location, permissions for added ramdisk files, and use methods for any required ramdisk modifications (optionally, also place banner and/or version files in the root to have these displayed during flash)
+4. Modify the anykernel.sh to add your kernel's name, boot partition location, permissions for any added ramdisk files, and use methods for any required ramdisk modifications (optionally, also place banner and/or version files in the root to have these displayed during flash)
 
 5. `zip -r9 UPDATE-AnyKernel3.zip * -x .git README.md *placeholder`
 
@@ -150,12 +152,32 @@ If supporting a recovery that forces zip signature verification (like Cyanogen R
 
 http://forum.xda-developers.com/android/software-hacking/dev-complete-shell-script-flashable-zip-t2934449
 
-Not required, but any tweaks you can't hardcode into the source (best practice) should be added with an additional init.tweaks.rc or bootscript.sh to minimize the necessary ramdisk changes.
+Not required, but any tweaks you can't hardcode into the source (best practice) should be added with an additional init.tweaks.rc or bootscript.sh to minimize the necessary ramdisk changes. On newer devices Magisk allows these within /overlay.d - see examples.
 
 It is also extremely important to note that for the broadest AK3 compatibility it is always better to modify a ramdisk file rather than replace it.
 
 ___If running into trouble when flashing an AK3 zip, the suffix -debugging may be added to the zip's filename to enable creation of a debug .tgz of /tmp for later examination while booted or on desktop.___
 
-For further support and usage examples please see the AnyKernel3 XDA thread: https://forum.xda-developers.com/showthread.php?t=2670512
+## // Staying Up-To-Date ##
+
+Now that you've got a ready zip for your device, you might be wondering how to keep it up-to-date with the latest AnyKernel commits. AnyKernel2 and AnyKernel3 have been painstakingly developed to allow you to just drop in the latest update-binary and tools directory and have everything "just work" for beginners not overly git or script savvy, but the best practice way is as follows:
+
+1. Fork my AnyKernel3 repo on GitHub
+
+2. `git clone https://github.com/<yourname>/AnyKernel3`
+
+3. `git remote add upstream https://github.com/osm0sis/AnyKernel3`
+
+4. `git checkout -b <devicename>`
+
+5. Set it up like your <devicename> zip (i.e. remove any folders you don't use like ramdisk or patch, delete README.md, and add your anykernel.sh and optionally your Image.*-dtb if you want it up there) then commit all those changes
+
+6. `git push --set-upstream origin <devicename>`
+
+7. `git checkout master` then repeat steps 4-6 for any other devices you support
+
+Then you should be able to `git pull upstream master` from your master branch and either merge or cherry-pick the new AK3 commits into your device branches as needed.
+
+___For further support and usage examples please see the AnyKernel3 XDA thread:___ _https://forum.xda-developers.com/showthread.php?t=2670512_
 
-Have fun!
+__Have fun!__