Linux shell for iOS
Clone or download
tbodt Merge pull request #280 from DavidSouthgate/master
 Updated AppDelegate.m so that IPv6 addresses are used for DNS
Latest commit 18809db Jan 16, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
app Adjust whitespace Jan 16, 2019
emu Fix some FPU bugs Jan 12, 2019
fastlane Release build 44 to testflight Jan 6, 2019
fs Stop ignoring -Winitializer-overrides Jan 13, 2019
iSH.xcodeproj Release build 44 to testflight Jan 6, 2019
jit Small aarch64 improvement to fstsw Jan 16, 2019
kernel Stop ignoring -Winitializer-overrides Jan 13, 2019
platform Implement /proc/meminfo Jan 6, 2019
subprojects Remove gdbm Nov 30, 2018
tests Implement bt[csr] for x86_64 Jan 13, 2019
tools Undefined flags for bsr Jan 16, 2019
util Really fix UAF when destroying a timer Jan 8, 2019
vdso Check for homebrew clang, and check that it actually works Aug 14, 2018
.gitignore Update to GDBM 1.18 Sep 30, 2018
.lvimrc Replace exrc with lvimrc Nov 16, 2017
.travis.yml use apt for ninja on xenial Dec 10, 2018
CHANGELOG.md Update changelog Jan 6, 2019
ISSUE_TEMPLATE.md Update ISSUE_TEMPLATE.md Dec 1, 2018
LICENSE Use GPL, not LGPL Oct 11, 2018
LICENSE.IOS Add license terms to allow App Store distribution Nov 10, 2018
README.md Update README.md Dec 20, 2018
debug.h Add function to report error and crash Nov 30, 2018
ish-gdb.gdb Ignore SIGPIPE in gdb Sep 30, 2018
main.c Mount /proc automatically when running from the terminal Dec 27, 2018
meson.build Don't skip rounding for shifts of size 64 (fixes #258) Jan 8, 2019
meson_options.txt Merge branch 'jit' Aug 13, 2018
misc.h Mark unused function arguments Jan 6, 2019
xX_main_Xx.h Fix string.h being auto included pretty much everywhere Dec 24, 2018
xcode-meson.sh Handle meson config vars with spaces Nov 30, 2018

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.

You can join the Testflight beta now. There's also a Discord server.

Hacking

You'll need these things to build the project:

  • Python 3
  • Ninja
  • Yarn (only when building for iOS)
  • 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)

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, 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.

To compile the iOS app, just open the Xcode project and click run. There are scripts that should download and set up the alpine filesystem and create build directories for cross compilation and so on automatically.

Further setup guide

To enable local development there are a few more steps that needs to be done.

  • Go to the project settings in Xcode find the "iSH" target

  • Under "General" change the bundle identifier to a specific identifier for you

  • Under "Capabilities" change the name of the "App Group" and remove the old app group

  • Go to the "iSHFileProvider" target

  • Under "General" use the same bundle identifier you created before and add .FileProvider to it

  • Under "Capabilities" use the same name of the "App Group" as for the "iSH" target

  • Go to the file app/AppDelegate.m

  • Change the string in the function manager containerURLForSecurityApplicationGroupIdentifier: to your App Group name that you entered in the step before.

Congratulations! You should now have the app running!

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.