Skip to content
Linux shell for iOS
C Objective-C Assembly C++ Shell Meson Other
Branch: master
Clone or download

Latest commit

tbodt Update hterm
Put the character under the cursor into the cursor node

Also make Xcode always run mkdist, because it doesn't support depfiles
and it's very quick anyway.

Fixed #532
Latest commit 69d1f1c May 23, 2020

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Add github sponsors to the FUNDING.yml Apr 25, 2020
app Update hterm May 23, 2020
emu Add fst st(i) to the decoder May 23, 2020
fastlane Release build 67 to testflight May 4, 2020
fs Hack around Darwin sometimes returning POLLPRI on pipes May 23, 2020
iSH.xcodeproj Update hterm May 23, 2020
jit Fix stack alignment when doing cross-page accesses May 23, 2020
kernel Hack around Darwin sometimes returning POLLPRI on pipes May 23, 2020
platform Return the correct answer for total system memory on Darwin Oct 14, 2019
subprojects Remove gdbm Nov 30, 2018
tests Enable FPU tests in qemu test program May 18, 2020
tools Fix permissions on / Jan 19, 2020
util Handle timeout values that are valid on Linux but valid on Mac May 9, 2020
vdso Remove fill directive from linker script Sep 30, 2019
.editorconfig apply 4 space to everything, utf-8 May 14, 2019
.gitignore add end to end testing script, two example tests, and travis Jun 7, 2019
.gitmodules Fix submodule path Sep 7, 2019
.travis.yml Update Travis to Ubuntu 18.04 Apr 6, 2020
CHANGELOG.md Update changelog Feb 12, 2019
ISSUE_TEMPLATE.md Update ISSUE_TEMPLATE.md Mar 31, 2019
LICENSE Use GPL, not LGPL Oct 11, 2018
LICENSE.IOS Add license terms to allow App Store distribution Nov 10, 2018
README.md Missed a spot Apr 7, 2020
README_ZH.md Polished Chinese translation to README_ZH.md Apr 27, 2020
debug.h Don't warn about variables only used in log statements Feb 10, 2020
iSH.xcconfig Get app group IDs from entitlements Mar 1, 2020
ish-gdb.gdb Ignore SIGPIPE in gdb Sep 30, 2018
main.c Make iosfs unsafe into a mount option Apr 13, 2020
meson.build Get rid of xfail on float80_test May 18, 2020
meson_options.txt Remove redundant default, add interp option. Oct 20, 2019
misc.h Don't warn about variables only used in log statements Feb 10, 2020
xX_main_Xx.h Reset the terminal when exiting normally May 16, 2020
xcode-meson.sh Deal with breaking change in Meson 0.54.0 Apr 11, 2020

README.md

iSH

Build Status goto counter fuck counter

A project to get a Linux shell running on iOS, using usermode x86 emulation and syscall translation.

For the current status of the project, check the issues tab, and the commit logs.

Hacking

This project has a git submodule, make sure to clone with --recurse-submodules or run git submodule update --init after cloning.

You'll need these things to build the project:

  • Python 3
  • Ninja
  • Meson (pip install meson)
  • Clang and LLD (on mac, brew install llvm, on linux, sudo apt install clang lld or sudo pacman -S clang lld or whatever)
  • sqlite3 (this is so common it may already be installed on linux and is definitely already installed on mac. if not, do something like sudo apt install libsqlite3-dev)

Build for iOS

Open the project in Xcode, open iSH.xcconfig, and change ROOT_BUNDLE_IDENTIFIER to something unique. Then click Run. There are scripts that should do everything else automatically. If you run into any problems, open an issue and I'll try to help.

Build command line tool for testing

To set up your environment, cd to the project and run meson build to create a build directory in build. Then cd to the build directory and run ninja.

To set up a self-contained Alpine linux filesystem, download the Alpine minirootfs tarball for i386 from the Alpine website and run the tools/fakefsify.py script. Specify the minirootfs tarball as the first argument and the name of the output directory as the second argument. Then you can run things inside the Alpine filesystem with ./ish -f alpine /bin/login -f root, assuming the output directory is called alpine.

You can replace ish with tools/ptraceomatic to run the program in a real process and single step and compare the registers at each step. I use it for debugging. Requires 64-bit Linux 4.11 or later.

Logging

iSH has several logging channels which can be enabled at build time. By default, all of them are disabled. To enable them:

  • In Xcode: Set the ISH_LOG setting in iSH.xcconfig to a space-separated list of log channels.
  • With Meson (command line tool for testing): Run meson configure -Dlog="<space-separated list of log channels>.

Available channels:

  • strace: The most useful channel, logs the parameters and return value of almost every system call.
  • instr: Logs every instruction executed by the emulator. This slows things down a lot.
  • verbose: Debug logs that don't fit into another category.
  • Grep for DEFAULT_CHANNEL to see if more log channels have been added since this list was updated.

A note on the JIT

Possibly the most interesting thing I wrote as part of iSH is the JIT. It's not actually a JIT since it doesn't target machine code. Instead it generates an array of pointers to functions called gadgets, and each gadget ends with a tailcall to the next function; like the threaded code technique used by some Forth interpreters. The result is a speedup of roughly 3-5x compared to pure emulation.

Unfortunately, I made the decision to write nearly all of the gadgets in assembly language. This was probably a good decision with regards to performance (though I'll never know for sure), but a horrible decision with regards to readability, maintainability, and my sanity. The amount of bullshit I've had to put up with from the compiler/assembler/linker is insane. It's like there's a demon in there that makes sure my code is sufficiently deformed, and if not, makes up stupid reasons why it shouldn't compile. In order to stay sane while writing this code, I've had to ignore best practices in code structure and naming. You'll find macros and variables with such descriptive names as ss and s and a. Assembler macros nested beyond belief. And to top it off, there are almost no comments.

So a warning: Long-term exposure to this code may cause loss of sanity, nightmares about GAS macros and linker errors, or any number of other debilitating side effects. This code is known to the State of California to cause cancer, birth defects, and reproductive harm.

You can’t perform that action at this time.