Ruby Everywhere: Ruby on Kindle Paperwhite

This involves jailbreaking your Kindle.

Let’s take a break from regular Ruby Everyday articles. In this episode, I’ll get Ruby 2.1 to run on my Kindle Paperwhite.

Jailbreak

First, go to Kindle Touch Hacking on MobileRead Wiki and jailbreak your Kindle. It’s pretty easy and straightforward, but do it at your own risk. Please make backups.

Install these things:

• usbnet. This allows you to SSH/Telnet into your Kindle.
• KUAL: Kindle Unified Application Launcher. This launcher lets you run other applications on your Kindle, including the terminal emulator Kterm. You probably need to install mkk (MobileRead Kindlet Kit) as well.
• Kterm: A Terminal Emulator for Kindle Paperwhite. You can also download useful tools there, such as tmux and vim.

Now, you should have a Terminal on your Kindle!

Install Ruby

Download a precompiled Ruby binaries for Kindle from my repository, and follow the instructions.

You should then be able to invoke Ruby from your Terminal by using the full path (/mnt/us/opt/ruby-2.1.2/bin)

For example, to fire up irb:

# /mnt/us/opt/ruby-2.1.2/bin/irb

Link Ruby to /usr/bin

It is too tedious to have to spell out the full path name every time… We’ll link Ruby to /usr/bin so that it can be run instantly.

To make change to the root filesystem (outside of /mnt/us), we must switch to writable rootfs first, then we can create the symbolic links.

# mntroot rw
system: I mntroot:def:Making root filesystem writeable
# ln -s /mnt/us/opt/ruby-2.1.2/bin/irb /usr/bin/
# ln -s /mnt/us/opt/ruby-2.1.2/bin/ruby /usr/bin/
# mntroot ro
system: I mntroot:def:Making root filesystem read-only

Add irb to the Menu Bar

We will add another menu item in KUAL for quick access to irb.

Go to `/mnt/us/extensions/kterm` and edit `menu.json`. Add another item to the menu, name it `irb`, and change its action to `bin/kterm_irb.sh`.

Inside the `bin` folder, make a copy of `kterm.sh`, rename that copy `kterm_irb.sh`, and open it for editing. On the line that invokes kterm, make it look like this:

${EXTENSION}/bin/kterm ${PARAM} -e irb

Now, when you go back to KUAL, you should see the irb menu item. Tap it, and you can write some Ruby code right away.

Source Codes

The source codes (Dockerfile) for building the toolchain and building Ruby are in the following repositories:

• dtinth/docker-kindle-k5-toolchain
• dtinth/kindle-k5-ruby

About This Collection

Ruby Everyday is a collection of stories about using small Ruby codes to solve everyday problems and make life easier.

I am looking for writers/editors for this collection. Please leave a note here, or contact @dtinth if you are interested in writing for this collection!

Suggestions are welcome! Please leave a note if you have any comments about code or my English writing.

Read on for some more rambling about the cross-compilation process.

The Cross Compilation

To get Ruby to run on Kindle, I had to do a “cross-compilation.”

Different versions of the tools on the build machine and on the Kindle caused many problems; they are not compatible with each other.

Sometimes the program would compile just fine, but when I run it on my Kindle, it just hangs silently.

crosstool-ng

Then, I found crosstool-ng, a tool that automates the process of building a cross-compilation toolchain with a specific kernel, compiler and library versions.

After a lot of fiddling and searching, I found the right configuration that works with on Kindle Paperwhite.

There was a lot of trial-and-error. It took me many hours until I got this right, partly due to the lengthy toolchain compilation step. If this was some kind of drama, it’d have been like this:

Hours were spent to equip her with every aspect he was looking for: the right CPU architecture, kernel version, endianness, and even glibc version.

She came to him once more to find herself being struck by his answer… Just two words, so simple, yet bitter.

“Segmentation fault”

Dockerized

To ease further development, I did all this inside a Docker container, so that we have a more controllable environment to work on. Other people who want to compile stuff to run on Kindle can also pull my toolchain image.

• dtinth/kindle-k5-toolchain (Docker Hub) contains Ubuntu with the toolchain for building programs on Kindle Touch and Paperwhite.
• dtinth/kindle-k5-ruby (GitHub) contains the instructions and Dockerfile for building Ruby using the above toolchain. Precompiled binaries are also available in the Releases section.

“Finally it’s compiling!” I waited expectantly as the toolchain announces, “Finishing installation (may take a few seconds)…”

And finally, it said something.

Something I did not expect at all.

“write /mnt/sda1/var/lib/docker/aufs/diff/…: no space left on device”

Help Wanted

Toolchain: The current toolchain is based on crosstool-ng. I just realized that Amazon also provides Makefiles for building the GCC cross-toolchain. I don’t know if it is a better idea to use that instead, but the current one works for me.

zlib: Right now the gem command fails because we did not compile Ruby against zlib.

Any contribution is welcome. :D