Termux and Termux:Widget How-To INTRO This guide describes how to install Termux and Termux:Widget, for running the Android Deltas Scripts 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 the full 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 deltas-scripts 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 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 single taps run scripts: 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 3) WIDGET CONFIG 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) Tasks folder (optional, and not needed for deltas scripts) $ mkdir -p /data/data/com.termux/files/home/.shortcuts/tasks $ chmod 700 -R /data/data/com.termux/files/home/.shortcuts/tasks C) 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 4) SHIMS CONFIG 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-scripts $ 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 5) ICONS CONFIG (optional) 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 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: $ I=$A/_etc/termux-widget-shims/icons/alternates $ cp $I/androidfold.png ~/.shortcuts/icons/initial-copy.py.png Examples of the icons live: ../screenshots/termux-widget-shim-icons1.jpg ../screenshots/termux-widget-shim-icons2.jpg 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, and move to one of your homescreen windows (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 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. Cut-and-paste and script files can help, but the widget is far easier once you get past these setup steps. MORE TERMUX TIPS - 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.