Logo Computer scientist,
engineer, and educator
• Software  • The KBOX3 project

KBOX3 installation instructions

KBOX logo
Please note that there is at present no automated installation procedure for KBOX3, as there was for KBOX2. However, the command-line installation procedure for KBOX3 is slightly simplified compared to KBOX2.

Installing KBOX3 is, I hope, relatively straightforward. However, I am no longer providing a version of KBOX that is bundled with a terminal emulator — this is just too much work, and it didn't work with Android versions after 4.1 anyway (thanks, Google). To install KBOX3 does require a willingness to work with Linux commands; but I'm assuming that anybody who wants to run a complete Linux distribution on their Android handset is happy to do that.

Before you start

PLEASE READ THIS!

It should be possible to install KBOX3 with any Android terminal emulator app, on any device with Android version later than 5.0. Earlier versions might work, but there has been little testing. KBOX2 supports android versions 3.0-4.4.

To install at all, you must first identify a filesystem location to which the terminal emulator can write files, and which supports the setting of execute attributes on files. This immediately rules out the SD card, either internal or external, because these file areas are mounted with exec permission disabled (thanks Google). Android is so locked down that there are relatively few places you can install a complete Linux distribution (!). The best place to install KBOX3 is in the terminal emulator's own data area. This will vary from app to app, but will usually be /data/data/[package_name]. The package name is unlikely to be something you can guess — it's something the developer will have assigned. For Jack Palevich's terminal, the writeable data area is at the following place:

/data/data/jackpal.androidterm
At present the installer won't stop you installing in an unsuitable directory; you might get a bunch of error messages, but most likely it will install and then nothing will work. In short, whatever terminal emulator you use, ensure that you know where its writeable data area is, and use that for the installation. In the following instructions, I assume that you're using Jack Palevich's terminal emulator, and installing in the directory shown above.

Installing the base system

The base system provides Busybox (including the package manager), and the libraries that provide the virtual root filesystem. Installation is somewhat automated, but there are a number of manual steps. Full automation is almost very difficult, because Android Linux offers only a woefully small selection of utilities — there isn't even a working cp command, for example.

1. Download the base system installer (here) to your Android device. You can do this using the built-in browser, or download using a desktop computer and then copy to the device. It's important that you know what directory the downloaded file is in, as seen from the Android terminal emulator. If you download using the built-in browser, the download directory is probably
/sdcard/Download
However, if you've installed an external SD card, it might have been changed to
/storage/extSdCard/Download
I will assume that the file is in /sdcard/Download; adjust as appropriate if not. Ultimately, your goal is to get this file to some directory where you can assign execute permission to it — you can't do that on the SD card.

2. Start the terminal emulator. Install one first if you haven't already. Again, I'm assuming that you're using Jack Palevich's terminal emulator, but others should work. You might find that you need to adjust some settings in the terminal app, particularly the font size.

3. In the terminal emulator, change to the writable data area for the terminal app.

$ cd /data/data/jackpal.androidterm

4. Copy the base installer to the writeable data area. Many Android versions don't have a working cp command, so you'll need to use cat to do this:

$ cat /sdcard/Download/kbox3-install-base > kbox3-install-base

5. Set execute permission on the installer:

$ chmod 755 kbox3-install-base

6. Run the installer

$ ./kbox3-install-base
The installer will first explode a bunch of files into a temporary directory called kbox3-base-installer. Then it will prompt whether to run the installation script install.sh. You need to say 'yes' here, if it isn't obvious. The installation script kicks of a series of steps that create the kbox3 directory and build the KBOX3 filesystem in that directory.

Note that the full path to the KBOX3 shell is displayed if the installer completes successfully. You'll see something like:

The full path of the KBOX3 shell is /data/data/jackpal.androidterm/kbox3/bin/kbox_shell
The installer creates the directory kbox3 in whichever directory it is run from, and that is the directory that will become the virtual root filesystem from within the KBOX shell.

7. Test the KBOX shell, by running it using the path displayed in the previous step.

$ /data/data/jackpal.androidterm/kbox3/bin/kbox_shell
Prompt should change to 'kbox$'. Running
kbox$ pwd
should show the current directory as /home/kbox, and ls / should show a unix-like root filesystem.

Exit the shell by typing exit or pressing Ctrl+D

8. (Optional) delete the temporary installation directory kbox3-base-installer and the installer itself.

kbox$ cd /data/data/jackpal.androidterm
jackpal.androidterm$ rm -rf kbox3-base-installer/ kbox3-install-base
You might prefer to leave these files in place. You can run the kbox3-install-base program again at any point to re-install KBOX3 if you delete or modify something critical accidentally.

9. Configure the terminal emulator to run the KBOX shell by default. This is an optional step, but it greatly increases the convenience of using KBOX. The mechanism to make this change depends on the terminal emulator. With Jack Palevich's Android Terminal Emulator, choose Preferences from the main menu, then find the entry for Command Line. Replace /system/bin/sh with the full path to the KBOX shell, as displayed in step 6. Caution is required. If you make a mistake here, most likely the terminal emulator will not start up again, and you'll be faced with re-installing it, along with repeating all the steps described above.

Installing packages

KBOX3 packages are in .deb format, and have names of the form xxx_kbox3.deb. This format is used by other Linux distributions but, even if the KBOX installer can unpack them, you can be sure they won't work.

To install a package, first get it onto the Android device, perhaps by using the built-in Web browser. I'm assuming that downloads from the browser go to the directory /sdcard/Download. Then, from the KBOX shell:

$ dpkg -i /sdcard/Download/{package}.deb
If you get warnings about missing dependencies, but you're sure that you have installed any packages on which there are dependencies, over-ride the warnings by doing:
$ dpkg -F depends -i /sdcard/Download/{package}.deb
Copyright © 1994-2015 Kevin Boone. Updated Jul 31 2015