From 83e3020a2c3490a91aedd19c1f920d6481b4c7cb Mon Sep 17 00:00:00 2001 From: Leonid Pliushch Date: Fri, 2 Oct 2020 21:29:55 +0300 Subject: [PATCH] termux-tools: add manual page for Termux app An offline compilation of important information from the Termux Wiki. --- packages/termux-tools/build.sh | 6 +- packages/termux-tools/motd | 3 +- packages/termux-tools/termux.1.md | 744 ++++++++++++++++++++++++++++++ 3 files changed, 751 insertions(+), 2 deletions(-) create mode 100644 packages/termux-tools/termux.1.md diff --git a/packages/termux-tools/build.sh b/packages/termux-tools/build.sh index 437816d91..83a99d7ba 100644 --- a/packages/termux-tools/build.sh +++ b/packages/termux-tools/build.sh @@ -1,7 +1,7 @@ TERMUX_PKG_HOMEPAGE=https://termux.com/ TERMUX_PKG_DESCRIPTION="Basic system tools for Termux" TERMUX_PKG_LICENSE="GPL-3.0" -TERMUX_PKG_VERSION=0.94 +TERMUX_PKG_VERSION=0.95 TERMUX_PKG_SKIP_SRC_EXTRACT=true TERMUX_PKG_PLATFORM_INDEPENDENT=true TERMUX_PKG_ESSENTIAL=true @@ -43,4 +43,8 @@ termux_step_make_install() { install -Dm600 $TERMUX_PKG_BUILDER_DIR/motd $TERMUX_PREFIX/etc/motd ln -sfr $TERMUX_PREFIX/bin/termux-open $TERMUX_PREFIX/bin/xdg-open + + mkdir -p $TERMUX_PREFIX/share/man/man1 + pandoc --standalone --to man --output $TERMUX_PREFIX/share/man/man1/termux.1 \ + $TERMUX_PKG_BUILDER_DIR/termux.1.md } diff --git a/packages/termux-tools/motd b/packages/termux-tools/motd index adb0df671..de07bb1cf 100644 --- a/packages/termux-tools/motd +++ b/packages/termux-tools/motd @@ -1,7 +1,6 @@ Welcome to Termux! -Wiki: https://wiki.termux.com Community forum: https://termux.com/community Gitter chat: https://gitter.im/termux/termux IRC channel: #termux on freenode @@ -20,3 +19,5 @@ Subscribing to additional repositories: Report issues at https://termux.com/issues +Run 'man termux' or visit https://wiki.termux.com +to learn more about Termux. diff --git a/packages/termux-tools/termux.1.md b/packages/termux-tools/termux.1.md new file mode 100644 index 000000000..73ab918b0 --- /dev/null +++ b/packages/termux-tools/termux.1.md @@ -0,0 +1,744 @@ +% TERMUX(1) As of application version 0.101 | Termux User Documentation +% By @xeffyr (Leonid Pliushch ) and Termux Wiki contributors. +% October 2, 2020 + +NAME +==== + +**Termux** - a terminal emulator application for Android OS. + +DESCRIPTION +=========== + +Termux is an Android terminal emulator and Linux environment application that +works directly with no rooting or setup required. A minimal base system is +installed automatically, additional packages are available using the package +manager. + +Here is a just a brief list of things you can do with Termux: + + - Data processing with Python. + - Programming in a development environment. + - Downloading and managing files and pages using time-established tools. + - Learning the basics of the Linux command line environment. + - Running an SSH client. + - Synchronizing and backing up your files. + +Of course, usage is not limited to the topics listed above. + +Note that it is expected that you have at least basic knowledge about +command line and shell scripting. + +USER INTERFACE +============== + +At launch Termux shows a terminal interface, whose text size can be adjusted +by pinch zooming or double tapping and pulling the content towards or from you. + +Besides the terminal there are three additional interface elements available: +a context menu, navigation drawer and notification. + +The context menu can be shown by long pressing anywhere on the terminal. It +provides menu entries for: + + - Selecting and pasting text. + - Sharing text from the terminal to other apps (e.g. email or SMS) + - Resetting the terminal if it gets stuck. + - Hangup (exiting the current terminal session). + - Styling the terminal by selecting a font and a color scheme. + - Showing this help page. + +The navigation drawer is revealed by swiping inwards from the left part of the +screen. It has three elements: + + - A list of sessions. Clicking on a session shows it in the terminal while + long pressing allows you to specify a session title. + - A button to toggle visibility of the touch keyboard. + - A button to create new terminal sessions. Long press it for creating a named + session or a fail-safe one. + +The notification, available when a terminal session is running, is available by +pulling down the notification menu. Pressing the notification leads to the most +current terminal session. It may also be expanded by pinch-zooming or performing +a single-finger glide to expose these actions: + + - Exiting all running terminal sessions. + - Use a wake lock to avoid entering sleep mode. + - Use a high performance wifi lock to maximize wifi performance. + +With a wake lock held the notification and Termux background processes will be +available even if no terminal session is running, which allows server and other +background processes to run more reliably. + +Using wake-lock +--------------- + +If you are executing a long operation in Termux and want to turn off device +screen, you need to enable Wake Lock. You can do that through the notification, +by clicking on button "Acquire wakelock" or by executing this command: + + termux-wake-lock + +Wake locks are needed to prevent device from going into sleep mode. If you will +not do that, your tasks will run very slowly or even be paused. Acquired Wake +Lock implies a higher battery usage during standby. + +Please note that Wake Lock does not affect network performance when screen is +off and you may observe a packet loss. + +To release Wake Lock, you need to either run command + + termux-wake-unlock + +or click button "Release wakelock" in notification. + +TOUCH KEYBOARD +============== + +Use of keys like ALT, CTRL, ESC is necessary for working with a command line +programs. As Android touch keyboards usually do not include such keys, Termux +uses the Volume-Down button to emulate the CTRL key. For example, holding the +Volume-Down and "L" on touch keyboard will send the same input as pressing +key combination CTRL+L on a hardware keyboard. + +The result of using CTRL (Volume-Down) in combination with a key depends on +which program is being used. See below for the list of common shortcuts usable +in most shells. + +`CTRL+A` +: Move cursor to the beginning of line + +`CTRL+C` +: Abort current process by sending SIGINT + +`CTRL+D` +: Logout of a terminal session by sending EOF + +`CTRL+E` +: Move cursor to the end of line + +`CTRL+K` +: Delete from cursor to the end of line + +`CTRL+U` +: Delete from cursor to the beginning of line + +`CTRL+L` +: Clear the terminal + +`CTRL+Z` +: Suspend current process by sending SIGTSTP + +`CTRL+W` +: Clear prompt before word + +The Volume-Up key also serves as a special key to produce certain input. +But please note that Volume-Up is not equivalent of the ALT key. + +`Volume-Up+E` +: Escape key + +`Volume-Up+T` +: Tab key + +`Volume-Up+1` +: F1, Volume-Up+2 will produce F2, etc + +`Volume-Up+0` +: F10 key + +`Volume-Up+B` +: ALT+B, back a word when using Readline + +`Volume-Up+F` +: ALT+F, forward a word when using Realine + +`Volume-Up+X` +: ALT+X + +`Volume-Up+W` +: Up arrow key + +`Volume-Up+A` +: Left arrow key + +`Volume-Up+S` +: Down arrow key + +`Volume-Up+D` +: Right arrow key + +`Volume-Up+L` +: **|**, the pipe character + +`Volume-Up+H` +: **~**, the tilde character + +`Volume-Up+U` +: **\_**, the underscore character + +`Volume-Up+P` +: Page Up key + +`Volume-Up+N` +: Page Down key + +`Volume-Up+.` +: CTRL+\\, send SIGQUIT + +`Volume-Up+V` +: Show the volume control + +`Volume-Up+Q` +: Toggle extra keys row + +`Volume-Up+K` +: Another variant to toggle extra keys row + +Termux supports the special key row which allows you to specify desired +keys like CTRL or ESC or their combinations. See section **EXTRA KEYS ROW**. + +HARDWARE KEYBOARD +============== + +The following shortcuts are available when using Termux with a hardware +(e.g. Bluetooth) keyboard: + +`CTRL+ALT+C` +: Create new session + +`CTRL+ALT+R` +: Rename current session + +`CTRL+ALT+` +: Switch to next session + +`CTRL+ALT+` +: Switch to previous session + +`CTRL+ALT+` +: Open drawer + +`CTRL+ALT+` +: Close drawer + +`CTRL+ALT+M` +: Show menu + +`CTRL+ALT+U` +: Select URL + +`CTRL+ALT+V` +: Paste clipboard content + +`CTRL+ALT+ (+/-)` +: Adjust font size + +`CTRL+ALT+ (1-9)` +: Go to numbered session + +These shortcuts do not work with touch keyboard or extra keys row. + +CONFIGURATION +============= + +All Termux configuration is done through text file located at + + ~/.termux/termux.properties + +It uses a simple key=value property syntax. See below for all supported +properties. + +Note that updated configuration takes effect only when you have executed + + termux-reload-settings + +or have restarted the application. + +`back-key` +: Controls the behavior of key "back". + + Accepts a one of these values: + + - **back** - The default. A standard behavior of Android OS, will + hide touch keyboard if shown, if not - move to home screen without + closing application. + + - **escape** - When set, touching the key will send escape character. + +`bell-character` +: Controls the behavior of bell characters. + + Accepts a one of these values: + + - **vibrate** - vibrate the device. + - **beep** - short sound beep. + - **ignore** - ignore bell characters. + + If property is not being set, the default behavior is equivalent + to "bell-character=vibrate". + +`enforce-char-based-input` +: Set this to "true" if you have issues with touch keyboard. For example text + is not being sent to terminal until you tap space. Or keyboard shows the + wrong layout, for example numeric. + + Recommended for people using Samsung devices with stock touch keyboard. + +`shortcut.create-session` +: Sets a key combination for creating new session. + + For example, use of + + shortcut.create-session = ctrl + t + + will allow to open a new terminal session by pressing CTRL + t. + +`shortcut.next-session` +: Sets a key combination for switching to the next session. + Value format is same as for "shortcut.create-session" property. + +`shortcut.previous-session` +: Sets a key combination for switching to the previous session. + Value format is same as for "shortcut.create-session" property. + +`shortcut.rename-session` +: Sets a key combination for opening a dialog for renaming the + current session. + Value format is same as for "shortcut.create-session" property. + +`use-black-ui` +: If set to "true", application will use primarily black color for + the most of user interface elements. + + Setting this to "false" will have opposite effect. + + If the property is not set, then application will choose colors + accordingly to the current system theme. + +EXTRA KEYS ROW +============== + +Termux also has an extra keys row(s) which allows you to extend your +current keyboard. To enable the extra keys row you have to long tap +on the keyboard button in the left drawer menu or Volume-Down+K key +combination. + +Layout of the extra keys rows is configurable through the standard +Termux configuration file located in + + ~/.termux/termux.properties + +See section **CONFIGURATION** to learn more about Termux properties. + +Sample configuration of 2 extra keys rows: + + extra-keys = [ \ + ['ESC','/','-','HOME','UP','END','PGUP'], \ + ['TAB','CTRL','ALT','LEFT','DOWN','RIGHT','PGDN'] \ + ] + +Configuration may be done as one line or be spread between multiple lines +by using backslashes like in example above. + +Value format is 2-dimensional JSON array. + +It is possible to configure a popups buttons which can be triggered by swiping +up on the respective keys. + +Here is a syntax for the popup key object: + + {key: KEY, popup: POPUP_KEY} + +Alternate, more advanced syntax for defining the popup: + + {key: KEY, popup: {macro: 'KEY COMBINATION', display: 'Key combo'}} + +An example of complex Termux extra keys configuration with using popups: + + extra-keys = [[ \ + {key: ESC, popup: {macro: "CTRL f d", display: "tmux exit"}}, \ + {key: CTRL, popup: {macro: "CTRL f BKSP", display: "tmux ←"}}, \ + {key: ALT, popup: {macro: "CTRL f TAB", display: "tmux →"}}, \ + {key: TAB, popup: {macro: "ALT a", display: A-a}}, \ + {key: LEFT, popup: HOME}, \ + {key: DOWN, popup: PGDN}, \ + {key: UP, popup: PGUP}, \ + {key: RIGHT, popup: END}, \ + {macro: "ALT j", display: A-j, popup: {macro: "ALT g", display: A-g}}, \ + {key: KEYBOARD, popup: {macro: "CTRL d", display: exit}} \ + ]] + +SUPPORTED KEYS +-------------- + +Each key "entry" can be either a string such as '|', '/', '=' or one of the +values listed below. + + - CTRL ("special key") + - ALT ("special key") + - FN ("special key") + - SPACE + - ESC + - TAB + - HOME + - END + - PGUP + - PGDN + - INS + - DEL + - BKSP + - UP + - LEFT + - RIGHT + - DOWN + - ENTER + - BACKSLASH + - QUOTE + - APOSTROPHE + - F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12 + - KEYBOARD (hide the keyboard) + - DRAWER (open app drawer) + +Each of the three "special keys" listed above should only be listed at most +ONCE in the extra-keys definition i.e. do NOT have more than one CTRL key. +Having more than one instance of any "special key" will result in a bug +whereby those keys do not function correctly. + +A note about backslash: this character has special meaning and you should +not use it directly to define a key. Use 'BACKSLASH' instead, otherwise +properly escape it - `'\\\\'`. + +TEXT INPUT VIEW +--------------- + +Termux does not support the advanced features of touch keyboards like +autocorrection, prediction and swipe typing. To solve this, it provides a +text input view. Text entered in it will get pasted to the terminal. Because +it is a native Android text input view, all touch keyboard features will work. +To access the text input view you have to swipe the extra keys row to the left. + +DIFFERENCES FROM LINUX DISTRIBUTIONS +==================================== + +Termux does not guarantee full compatibility with GNU/Linux environment and +you may observe inconvenient behavior of some utilities, especially from +those which were not officially ported to Android OS (Termux). See below to +learn about the major differences. + +`No compliance with Filesystem Hierarchy Standard` +: Termux does not follow Filesystem Hierarchy Standard because Android does + not make root file system world-writable and Termux is not a virtual + machine. + + All files are stored within the application private directory on internal + storage to ensure that application has full control over its files and + also special features like symlinks or file access modes (**chmod(1)**). + + The data is being stored in 2 main locations: + + `/data/data/com.termux/files/home` + : A home directory where user can place his files. + + `/data/data/com.termux/files/usr` + : The prefix - a place where all packages are being extracted during + installation. Has a directory structure similar to the root file + system of traditional Linux distributions. + + You may have problems with running some utilities accessing standard + directories like /var or /tmp. + + Termux has some workarounds for that. For example, it preloads a shared + library "libtermux-exec.so" which intercepts "execve()" and maps /bin to + directory located in the prefix. + + With utility "termux-chroot" that comes as part of package "proot" you + should be able to emulate a FHS-compliant root file system. + +`No GNU libc` +: Termux does not use GNU libc. Instead it uses a Bionic libc and dynamic + linker provided by Android OS. + + Programs linked with GNU libc will not work in Termux. Bionic libc has + different ABI and dynamic linker path. You likely will observe weird + messages "No such file or directory" when attempting to run executable + file but know that file is present. That happens because dynamic linker + cannot be started because does not exist on expected location. + + Programs which were statically-linked with GNU libc may misbehave too. + You may get a "Bad system call" errors. Also networking software will + likely show DNS resolution errors because Android does not provide + `/etc/resolv.conf` and by default even in statically-linked programs + GNU libc still uses libresolv as shared library which is not present. + + Consider to rebuild your software in Termux environment by using clang. + +`Only one user` +: Termux environment is sinle-user only. There any kind of privilege + separation and you cannot change the given user id or name. + + Be extremely careful when executing third-party scripts as they are + able to tamper files in Termux prefix. + +PACKAGE MANAGEMENT +================== + +Termux uses **apt(8)** as package manager, just like Debian. However we +highly recommend to use our wrapper **pkg** which simplifies certain +tasks and also automatically picks the mirror to help reduce traffic usage +on the origin repositories. See its usage below. + +Installing package: + + pkg install + +Uninstall package: + + pkg uninstall + +Reinstall package: + + pkg reinstall + +List the all available packages: + + pkg list-all + +List the installed packages: + + pkg list-installed + +Search packages: + + pkg search + +Upgrade packages: + + pkg upgrade + +Termux implements a rolling-release updates scheme to reduce amount of work +needed to maintain packages since developer team is small. You need to check +for updates on a regular basis, especially before installing a new package. +Otherwise at some day your environment will be broken. + +If you prefer to use **apt(8)** over **pkg**, please ensure that for +installing updates you use these commands: + + apt update + apt full-upgrade + +Also always run "apt update" before installing package. The wrapper **pkg** +does that for you automatically. + +RECOVERY +======== + +If Termux session cannot be launched due to misconfiguration in dotfiles, +you still should be able to start a failsafe session. How-to: + + 1. Long click on Termux launcher icon. + 2. Select shortcut "failsafe". + +Once you are in a failsafe session, navigate to Termux home directory and +rename or delete the dotfiles causing the issue. Finally, restart the +application. + +If problem is not with the dotfiles, for example you have messed up Termux +prefix and do not know what to do, our recommendation is *complete reinstallation* +by executing + + rm -rf /data/data/com.termux/files/usr + +This will erase all packages but will not touch your home directory. + +ACCESSING THE STORAGE +===================== + +By default Termux does not provide access to storage volumes where you +typically store your files like pictures or documents. In order to get +access to shared storage, execute the next command: + + termux-setup-storage + +This will prompt you for Storage Access Permission. Once it granted, Termux +will setup symlinks to various standard directories under "~/storage". + +`~/storage/shared` +: The root directory of shared storage. + +`~/storage/downloads` +: Standard directory where downloaded files are stored. + +`~/storage/dcim` +: Standard directory where captured photos and video are stored. + +`~/storage/pictures` +: Standard directory for photo gallery. + +`~/storage/music` +: Standard directory where music albums are stored. + +`~/storage/movies` +: Standard directory where videos are stored. + +`~/storage/external-1` +: The private directory of Termux on external SD-card. + +Note that if you decide to wipe Termux data or uninstall application, +all files stored in private application directories will be deleted. + +Note about external storage +--------------------------- + +Android does not allow to have a direct write access to external storage +like SD-cards and USB drives unless you are not doing so in private +directories like + + /storage/0123-ABCD/Android/data/com.termux/files + +If you want to write files to storage root or directory other than private +one of Termux, you need superuser permissions. + +Android applications like file managers can do that because they use a +special API called Storage Access Framework. But command line utilities +cannot use this one. + +Transferring files to Termux +---------------------------- + +To put files into Termux, you have 2 variants. + +The first one would be copying or moving files from shared storage into +Termux directory by using **cp(1)** or **mv(1)**. You may also setup +a some file server and access it through localhost. + +The second variant would be usage of file manager application which supports +Storage Access Framework and is able to attach volumes. Just select "Termux" +volume from menu and you should be able to access home directory. + +Sharing data to other applications +----------------------------------- + +You may give a temporary read access to certain files stored within +Termux. Use command + + termux-open + +to do this. You may specify a MIME type by using option "--content-type" when +sharing the file to ensure that it will be opened by correct application. + +Similarly to sharing files, you may share URL. You will need to use +command "**termux-open-url**". + +Android 11+ +----------- + +Since Android 11 Termux may not be able to provide the access to shared and +external storage. This is not a bug. Just new restrictions which enforce +storage access over Android API which cannot be used by shell. + +From that point you are locked to Termux private directories like $HOME or +such on storage volume: + + /storage/self/primary/Android/data/com.termux/files + +You still should be able to exchange files with Termux home directory by +accessing Termux virtual volume through File managers supporting Storage +Access Framework. + +ENVIRONMENT +=========== + +Termux exposes some variables set by Android OS as well as its own. Here +is a brief list of default environment variables, their description and +values. + +`HOME` +: Path to Termux home. + + Termux home directory is a place for user files. It is located at + + /data/data/com.termux/files/home + + Do not modify the value of this environment variable since Termux + doesn't support customizing location of the home directory. + +`PREFIX` +: Termux installation prefix. + + A base directory for Termux installation. It is located at + + /data/data/com.termux/files/usr + + Do not modify the value of this environment variable. Termux packages + are not relocatable. Some of them may also look this variable to find + their files. + +`PATH` +: Utility lookup paths for shells. + + Used by shells to find command line utilities. By default, it contains + this value: + + /data/data/com.termux/files/usr/bin + + You may append or prepend your own paths if needed, for example: + + export PATH=$PATH:$HOME/bin + + But make sure that Termux-specific bin directory location is not missing. + +`LANG` +: Locale. + + Mimic support of UTF-8 en_US locale, so programs will properly handle + Unicode characters. + + Default value is "en_US.UTF-8". + + As Termux does not support locales, changing this variable is not + recommended and may have unexpected effects. + +FILES +===== + +A list of files which have special meaning for the Termux application. + +`~/bin/termux-url-opener` +: A script for processing an intent when a third-party application shares + an URL with Termux. + +`~/bin/termux-file-editor` +: A script for processing an intent when a third-party application shares + a file with Termux. + +`~/storage` +: A directory containing symlinks to shared or external storages and to + certain standard directories. + + Do not store files directly under this directory. Put them to locations + accessible through symlinks instead. + +`~/.termux/termux.properties` +: Application configuration file. + +`~/.termux/colors.properties` +: A configuration file containing a color scheme for styling the terminal. + Usually is generated by Termux:Styling add-on. + +`~/.termux/font.ttf` +: A file containing TTF font data for styling the terminal. + Usually is generated by Termux:Styling add-on. + +BUGS +==== + +Report application issues to https://github.com/termux/termux-app/issues. + +Package-related issues should be reported to https://github.com/termux/termux-packages/issues. + +SEE ALSO +======== + +Complete and up-to-date infomation about Termux usage is available on Termux +Wiki here: https://wiki.termux.com/wiki/Main_Page.