Intro to Lantern

Ryan Torvik - December 12, 2024 - 6 minute read

Lantern

Lantern is a version of Emerson that allows anyone—from hobbyists to professional developers—to explore ARMv4 VirtIO Linux emulation. If any program is compiled for ARMv4, you can run it on Lantern. In this post, I will guide you through how to get Lantern working on your machine and its applications. Check out the video below or continue reading for a quick guide and demo.

Pre-Requirements

Before you can start, you need a license to install the Emerson Docker image. Click the Download button in the top right and fill out the form. An email with a license key and the source code will be sent to your email.

Getting Started

Once you have the Lantern source code and license key, we can start installing the Docker image that the Emerson emulator lives on. Download the source code sent to you.

Unzip lantern.tar with the command below and navigate inside of the lantern file.

tar xvf lantern.tar

Run this script to install the Docker image. It should prompt you for your license. Paste it from the email that was sent to you and hit enter.

./install

Next you are going to run the server to interact with Emerson.

./server start

Lastly, connect to the port that the server is being hosted on http://localhost:10314. You are now running Lantern!

Navigating Lantern

You should now be on Emerson’s project page.

Make a new Lantern session by clicking Lantern under Projects. You should now see the device YAML file which is used for configuration purposes. Click the Create button to make a new session.

Your are now in Emerson’s main GUI interface where you can interact with the ARMv4 VirtIO Linux machine. To start, click the Snapshot icon and click the pre-saved “booted” snapshot to load the linux kernel.

Your Counter value should have increased because of this. Next click the Play button and your machine is now actively running.

Note: if you accidentally erased the “booted” snapshot, run ./server stop and then ./server start again to reset the image.

Lantern File Structure

• .share- Any files you put in the .share directory will be available to the emulated machine in the /host directory.
• /arm-examples- Holds three different pre-compiled examples we have given you to play around with. There is also an Earthy file to compile and auto place all executables inside of the .share directory for reference.

Using the Serial I/O tty1 Console

Theres a lot of different tools and interfaces inside of Emerson but for now, we are going to focus on interacting with Linux to run some code. Stay tuned for more feature walkthroughs!

Inside of the Serial I/O Device Box, select the tty1 console to connect to the VirtIO console. The tty0 console is used to see the boot process of the machine and won’t be used for now.

Interact with the tty1 console as you would with a normal linux console. Type ls into the console to show the files in the current root directory.

Lets test running the hello-world program in /arm-examples. This is already compiled for you and placed in the .share folder so the host machine can access it. For details on how this was built, check out the GitHub README for the commands. You can also use the commands found in the GitHub as a guide if you want to compile your own examples; just replace the file names.

In the tty1 console type ls host to show all of the built files you can execute.

Type host/hello to run the hello-world program. The console should output “hello-world”.

There is also hello-world-fails and terminal-snake executables we can run by typing host/hello-fails and host/snake.

Running Scripts Through the tty1 Console

Lantern allows you to streamline testing by running scripts directly from your host machine. This eliminates the need to execute files manually in the emulated environment. We will be using the ./client script to achieve this.

This will run a file in the emulator, capture the output, and exit with the exit code of the supplied file. You can hook this into a testing framework as well.

./client test <file_to_run>

To look at an example, if we ran ./client test ./.share/hello-fails we can see that the test failed to pass in our terminal. If you have the tty1 terminal up while you run the unit test, you can see the actual commands being run real time inside of the emulator.

Wrapping Up

Lantern is a powerful and easy-to-use playground for emulating and testing ARMv4 applications. Whether you’re running pre-built examples, writing custom scripts, or automating tests with the ./client tool, Lantern simplifies the emulation process.

For even more flexibility, try using GDB within the tty1 console for debugging. Ready to explore more? Read our other blog posts and visit our GitHub page to access the source code and stay up to date with new features.

Happy experimenting with Lantern!