![[Home page]](../PythonPowered.gif "Home page"){kind=small}
| Books | Code | Blog | Python | Author | Train | Find | ©M.Lutz |
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.