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.