File: android-deltas-sync/_etc/termux-widget-shims/_TERMUX-WIDGET-HOWTO.txt
Termux and Termux:Widget How-To INTRO ===== This guide describes how to install Termux and Termux:Widget, for running the Android Deltas Sync package on your phone. You can run the scripts in other apps, but Termux is recommended. All of the following steps are run on your phone. In commands below, "$" stands for the Termux shell prompt, which may vary; don't type this character itself, just the command to its right. Also, when copying commands, be sure to copy/paste the complete command; dropping just one letter on the front or end will fail. The following also generally assumes you've already fetched and unzipped both the Android Deltas Sync package and Mergeall; see "Quick Start" in ../../_README.html for more details. This is a complete and self-contained guide, but the process is naturally prone to change; check the following for more info and future revisions: Termux => https://wiki.termux.com/wiki/Main_Page widget => https://wiki.termux.com/wiki/Termux:Widget UPDATE: as of version 1.2, three of the setup steps below are now automated by included scripts noted along the way. In short, to avoid copy-paste of numerous commands, run the _INSTALL-ALL.sh master script in Termux like this to satisfy steps 3 through 5: $ cd /sdcard/Download/android-deltas-sync/_etc/termux-widget-shims $ bash _INSTALL-ALL.sh For more control, you can instead run the subscripts which this master script launches as covered ahead. No pre-run edits are required to use any of these setup scripts. HOW-TO ====== To setup Termux and its widget on your phone, run the following steps in sequence. This is a one-time task that will generally take 10-15 minutes, after which a single tap on a home-screen widget runs a script on your phone. 0) CLEANUP? =========== First, be sure to uninstall any Google Play versions of Termux apps already installed on your phone. Termux's F-Droid apps don't work with its Google Play apps, and vice versa. 1) APPS INSTALL =============== Install the "Termux" and "Termux:Widget" apps from F-Droid from "https://f-droid.org/" (their Google Play versions are deprecated): A) Search for these apps on F-Droid by name. B) Download these apps' APK files - scroll down to the "Download APK" on their pages and tap it to fetch. C) Open these apps' APK files on your phone in a file explorer to install; find them in your Download folder and tap to open. You may need to grant your file explorer permission in Settings to install apps not from the Google Play store. Being able to install non-store apps this way is sideloading, one of Android's main advantages over iOS. You may wish to also install Termux:Styling, an extension for tweaking appearance in Termux itself. 2) TERMUX CONFIG ================ Open and configure the Termux app itself: A) Tap the Termux app on your phone's apps screen. B) Type or paste the following at Termux's command line, to get Python; remember to omit the "$": $ pkg install python C) Also run the following at Termux's command line and approve access in the popup, if you'll store content in shared storage's /sdcard (which is slightly recommended over app-specific storage; see "Android Storage" in ../../_README.html for details): $ termux-setup-storage See also "MORE TERMUX TIPS" ahead for additional usage pointers. 3) WIDGET CONFIG ================ MANUAL: Configure the Termux widget, by running the following six commands one at a time in Termux itself (copy and paste from here for ease): A) Shortcuts folder: $ mkdir -p /data/data/com.termux/files/home/.shortcuts $ chmod 700 -R /data/data/com.termux/files/home/.shortcuts B) Icons folder (optional) $ mkdir -p /data/data/com.termux/files/home/.shortcuts/icons $ chmod -R a-x,u=rwX,go-rwx /data/data/com.termux/files/home/.shortcuts/icons C) Tasks folder (optional: not used or required by Android Deltas Sync) $ mkdir -p /data/data/com.termux/files/home/.shortcuts/tasks $ chmod 700 -R /data/data/com.termux/files/home/.shortcuts/tasks AUTOMATIC: A new Bash script added in 1.2 automatically runs all the commands above; no script edits are required, but see its docs for more info: _etc/termux-widget-shims/_config-widget.sh 4) WIDGET SHIMS CONFIG ====================== MANUAL: Widget-shim scripts run the main package's scripts on widget taps. After fetching and unzipping the scripts package (see _README.html), copy its shim scripts to the Termux shortcuts folder, with the following commands in Termux itself; change the "A" path in the first if you've downloaded the scripts package to somewhere else: $ A=/sdcard/Download/android-deltas-sync $ cp $A/_etc/termux-widget-shims/initial-copy.py ~/.shortcuts $ cp $A/_etc/termux-widget-shims/sync-changes.py ~/.shortcuts $ cp $A/_etc/termux-widget-shims/verify-phone.py ~/.shortcuts $ cp $A/_etc/termux-widget-shims/export-phone.py ~/.shortcuts Note: you must edit each shim's "runee" setting if you didn't unzip this package to /sdcard/Download; change to use your path. AUTOMATIC: A new Bash script added in 1.2 automatically runs all the commands above; no script edits are required, but see its docs for more info: _etc/termux-widget-shims/_install-shims.sh 5) WIDGET ICONS CONFIG ====================== MANUAL: This is an optional but suggested step. Customize icons for the individual-script Termux shortcut widget, by copying images into the icons folder. To use Mergeall's own icon: $ I=$A/_etc/termux-widget-shims/icons/Mergeall1024.png $ cp $I ~/.shortcuts/icons/initial-copy.py.png $ cp $I ~/.shortcuts/icons/sync-changes.py.png $ cp $I ~/.shortcuts/icons/verify-phone.py.png $ cp $I ~/.shortcuts/icons/export-phone.py.png Alternatively, replace the "I" image path above with that of any PNG image you care to try. You can use the same or different images for each shim script (and any other shortcuts you've installed), as well as any of the other image options shipped in ./icons/alternate. For example, to use the shipped alternative images: $ I=$A/_etc/termux-widget-shims/icons/alternates $ cp $I/mergeall128.png ~/.shortcuts/icons/initial-copy.py.png $ cp $I/Mergeall1024.png ~/.shortcuts/icons/sync-changes.py.png $ cp $I/noandroid11.png ~/.shortcuts/icons/verify-phone.py.png $ cp $I/androidfold.png ~/.shortcuts/icons/export-phone.py.png Examples of the icons live: ../screenshots/termux-widget-shim-icons1.jpg ../screenshots/termux-widget-shim-icons2.jpg AUTOMATIC: Two new Bash scripts added in 1.2 automatically run the command sets above; no script edits are required, but see their docs for more info, and run either the first for the same icon or the second for a mix: _etc/termux-widget-shims/icons/_install-icons-same.sh _etc/termux-widget-shims/icons/_install-icons-alts.sh SUMMARY: STEPS 3, 4, 5 ====================== Taken together, the last three steps' automatic procedure in 1.2 is just this; use your install folder in the first command if different: $ cd /sdcard/Download/android-deltas-sync/_etc/termux-widget-shims $ bash _config-widget.sh $ bash _install-shims.sh $ bash icons/_install-icons-alts.sh Better still, the prior three commands are run by this master script: $ cd /sdcard/Download/android-deltas-sync/_etc/termux-widget-shims $ bash _INSTALL-ALL.sh That two-command sequence configures widget shortcut folders, and installs both widget shims and widget icons in a single step. It satisfies steps 3, 4, and 5 above for the Android Deltas Sync package. 6) HOME SCREEN ============== As a last setup step, add the widgets to your phone's home screen: A) Go to the home screen, longpress on an empty area, select Widgets near the bottom, and navigate to Termux:Widget B) Select the Widget style you prefer, longpress or tap Add, and move to a home-screen window (make a new one if desired): - The menu widget ("Termux widget") lists all scripts in ~/.shortcuts, by name. - The individual-script widget ("Termux shortcut" black oval) asks you to select a script in ~/.shortcuts to launch; this widget will display the icon image(s) you copied in the prior step, if any. 7) RUN SCRIPTS ============== Finally, launch scripts from your home screen with a single tap on either widget menu entries or individual-script widgets. Depending on your device, you may need to perform two steps on the first run (only): A) On some phones, the first run asks you to give Termux permission to run in the background and use power; this is necessary for it to acquire and release its wakelock so scripts keep running after the screen blanks. Reply to the popup to allow. B) On some Androids, a brief first-run message asks you to give Termux permission to run on top of other content; go to Settings, Apps, Termux, Advanced (on some phones), and scroll down to set the "Appear on Top" toggle to on. Or... you can open Termux and type full command lines with paths to launch scripts each time, but it's likely to grow tedious quickly, especially on a phone. Copy-and-paste and script files can help, but the widget is far easier once you get past these setup steps. MORE TERMUX TIPS ================ - You may need to run "termux-change-repo" to install Python and other tools. See https://github.com/termux/termux-packages/issues/6726. - Longpress anywhere and tap "More..." to open a menu with help, styles, transcripts, etc., and use spread/pinch gestures to adjust text size. - Swipe in from the top-left edge in Termux to access a menu; longpress its "Keyboard" to turn the extra-keys rows off and on. - Hacker's Keyboard is essential for Termux command-line usage; get the app at the Play store and install (this makes Termux extra keys moot). - Up/Down arrows scroll through command history, tab expands filenames as normal in Bash shells, and left/right keys move in command lines. - The usual longpress can copy and paste text in Termux; Ctrl+C/V also copy/paste in Hacker's Keyboard, though longpress-copy text may differ. - Your ~/.bash_profile can be used to preset abbreviations and aliases, because it's always loaded on Termux startup; see Bash docs. - Run "pkg install vim" to get the vi text editor, and ditto for nano; most standard Unix tools are either preinstalled or installed this way. - Python packages can be installed with "pip install <package>" as usual; see thumbspage's user guide for tips on installing the Pillow library. - The Termux /sdcard/Android/data/com.termux app-specific folder is fast and widely accessible, but also auto-deleted on Termux uninstall. - See "phantom" in the top-level _README.html for info on Android 12's process killer; this may require additional steps to avoid script culls.