ish: Linux Shell for iOS

Introduction

iSH is an ambitious open-source project that provides a full-fledged Linux shell environment for iOS devices. It leverages usermode x86 emulation and syscall translation to enable the execution of Linux binaries directly on Apple's mobile operating system. This allows users to access a powerful command-line interface, run various Linux tools, and even set up a self-contained Alpine Linux filesystem on their iPhone or iPad. With over 18,000 stars on GitHub, iSH is a highly regarded tool for developers and power users seeking a robust Unix-like environment on their mobile devices.

Installation

There are several ways to get iSH running, from installing the official app to building it from source.

App Store / TestFlight

The easiest way to get iSH is through the official channels:

• App Store: Install directly from the App Store.
• TestFlight Beta: Join the beta program via TestFlight.

Building for iOS (Xcode)

To build iSH for iOS from source, follow these steps:

1. Clone the repository:

   git clone --recurse-submodules https://github.com/ish-app/ish
   cd ish
   

2. Install prerequisites:
   • Python 3 (with Meson: pip3 install meson)
   • Ninja
   • Clang and LLD (e.g., brew install llvm on macOS, sudo apt install clang lld on Linux)
   • sqlite3 (often pre-installed, otherwise sudo apt install libsqlite3-dev)
   • libarchive (e.g., brew install libarchive on macOS, sudo apt install libarchive-dev on Linux)
3. Open in Xcode: Open the project in Xcode.
4. Configure: Open iSH.xcconfig and change ROOT_BUNDLE_IDENTIFIER to a unique value. Update the development team ID in the project build settings.
5. Run: Click Run in Xcode. Scripts should handle the rest automatically.

Building Command-Line Tool for Testing

For a command-line testing tool on your desktop:

1. Set up environment:

   cd ish # (assuming you cloned the repo as above)
   meson build
   cd build
   ninja
   

Examples

Once you have iSH set up, you can start exploring its capabilities.

Running Alpine Linux

To set up and run a self-contained Alpine Linux filesystem:

1. Download Alpine minirootfs: Get the i386 tarball from the Alpine Linux website.
2. Prepare filesystem:

   ./tools/fakefsify <path/to/minirootfs.tar.gz> alpine
   

3. Run shell:

   ./ish -f alpine /bin/sh
   

Enabling Logging

iSH offers several logging channels for debugging. To enable them:

• In Xcode: Set the ISH_LOG setting in iSH.xcconfig to a space-separated list of channels (e.g., strace verbose).
• With Meson: Run meson configure -Dlog="strace verbose".

strace is particularly useful for logging system call parameters and return values.

Why Use iSH?

iSH stands out for several compelling reasons:

• Full Linux Environment on iOS: It provides a genuine Linux command-line experience, allowing users to run familiar tools and scripts directly on their iPhone or iPad, transforming their mobile device into a powerful portable workstation.
• Unique Emulation Approach: By using usermode x86 emulation and syscall translation, iSH offers a robust and surprisingly performant way to bridge the gap between iOS and Linux architectures.
• Custom Interpreter for Performance: The project features a custom-written interpreter that utilizes a threaded code technique, resulting in a significant speedup (approximately 3-5x) compared to simpler emulation methods.
• Developer-Friendly: For developers, iSH offers a convenient way to test Linux-based tools or scripts without needing a separate machine or virtual environment, making it ideal for on-the-go development and experimentation.
• Open Source Community: Being an open-source project, iSH benefits from community contributions and transparency, ensuring continuous improvement and a supportive environment.

Links

• GitHub Repository: https://github.com/ish-app/ish
• App Store Page: https://apps.apple.com/us/app/ish-shell/id1436902243
• TestFlight Beta: https://testflight.apple.com/join/97i7KM8O
• Discord Server: https://discord.gg/HFAXj44
• Wiki with Help and Tutorials: https://github.com/ish-app/ish/wiki