Einstein: a NewtonOS emulator, and the platform work behind it

What the project is, and where it runs

Einstein is an emulator for NewtonOS, the operating system of a handheld device from the end of the nineteen nineties, and the readme's first line is that simple. The project's own summary puts it differently: NewtonOS running on other operating systems.

That second phrasing is the interesting one, because it says what the project is actually for. A faithful emulator of a dead platform is a curiosity. A faithful emulator of a dead platform that runs on everything, including a phone, is a preservation project with practical uses, and the list of supported targets says what those are.

Officially it runs on macOS, on iOS and on Ubuntu Linux, with partial support for Android, for the Raspberry Pi and for Windows. And the continuous integration badges show four build configurations: macOS with one user interface toolkit, macOS with another, Ubuntu, and Windows with the second toolkit. Which tells you two things. That there are two front ends rather than one, and that the second one is the portable one, since it is the one built on Windows and on Linux as well as on the desktop system.

The presence of a build for iOS is the other thing worth noticing. A system from the era of the original handheld running on a phone is the case that makes an emulator worth more than a museum piece, and the project supports it officially.

The code is C and C++, and the repository carries a language grade badge from a static analysis service, which for a project of this size and this age is an unusual thing to publish. It is a measure of the code's health, and publishing it means the project is comfortable being judged on something other than whether it still works.

The licence is the copyleft one, which is the right choice for an emulator whose whole value is that people can run it, modify it and keep it running, and the release history shows a version named after its date, with several releases in the last fortnight.

The system image, and the decision not to ship it

The second paragraph of the readme is the one that explains what you need to actually run the thing.

A system image file for the original device is required, and the project cannot distribute it. If you own a device, you may be able to dump your own image from it, and there is a page in the wiki about how to do that.

The ethics of this are handled correctly, and it is worth saying so plainly, because emulation projects often get this wrong. A ROM file is copyrighted content, and a project that made it easy to obtain would be distributing copyrighted material. So the project does the opposite: it tells you where to find the image you already own, and it tells you how to extract it from hardware you already own, and it leaves the acquisition entirely to you.

That has a practical consequence for anybody evaluating the project, and it is the main one. The emulator is open and buildable, and the thing it emulates is not. A new user has to find a device or find the image before they can do anything, and the readme is upfront about that rather than burying it.

It also shapes the project's community. The people using Einstein are people who care about the original device, which is why the repository carries a user guide in the tree, a wiki with a page on the practical side of getting an image, and a directory of screenshots that includes images of the emulator running a Mac from 2015.

The screenshot is a nice detail. It is dated, and it is a Mac, which tells you two things about the project at a glance: the user interface on the native desktop toolkit was working years ago and was worth photographing, and the emulator's appeal is partly that it restores a workflow that no current machine has.

Two front ends, and what that costs

The four continuous integration configurations imply something about the shape of the code, and the screenshot confirms it.

One front end is built on the native toolkit of the desktop system, which in the screenshot's case is the window server of a Mac, drawn in the platform's own idiom. The other is built on a cross-platform toolkit, and it is the one built for Windows, for Linux and for the phone.

Carrying two front ends is a real cost, and the interesting question is why the project pays it. The answer is the same reason the project exists: an emulator that only runs on the platform it was written for is not much of a preservation effort, and the platform that the original device's users might still have is not the platform the emulator is built for. So the portable front end is the important one, and the native one exists because a native window on the desktop is a much better experience than a portable one, and because the people maintaining the project are on that platform.

And you can see the priority in the release notes and the change log: the project maintains a long history of both, and the change log is a file in the repository rather than a page on a site, which for a project that has been running for two decades is the right choice.

There is one more detail in that set of files that is worth a paragraph. There are three separate documents about changes: a change log, release notes, and a separate file that holds the text used for a release. That is three different purposes, and separating them is a sign of a project that has a release process rather than a person who pushes when they feel like it. The change log is for developers, the release notes are for users, and the release text is for the announcement, and the fact that they are separate files means the announcement can be written once and reused.

The same care shows in the formatting and the automation: a formatting configuration for the code, an editor configuration, a pre-commit configuration, and a static analysis configuration. Four files that all say the same thing, which is that the code is expected to be written to a standard without anybody having to ask.

The repository, and the twenty years of ports in it

The top level of the repository is the most interesting document in the project, because the directory names are a map of everything the emulator has had to be made to fit.

There is an emulator directory, which is the core, and a directory for the emulated system's own kernel, and one for the monitor, which is the low-level screen and keyboard layer of the original system. There is a directory named for the emulated device itself, which is where the emulated hardware and its firmware live, and a toolkit directory, and a drivers directory.

Then there are the platform directories, and they are the story. There is a directory for a Mac toolkit, one for the embedded Linux distribution that ran on a particular line of handhelds, one for its successor, and one for a different embedded distribution from a different vendor. There is a directory for the phone, one for an application directory, and a directory for the vendored audio library that the host uses to make sound.

And then there is the foreign function interface. There is a directory for it, and then one for each platform it was ported to: a version for ARM Linux, one for the Cygwin environment, one for Linux generally, two for two generations of a different vendor's handheld platform, one for macOS, and one for Windows. Eight copies.

That is the single most telling thing in the repository, and it deserves an explanation, because the answer explains the whole project. The emulated system is not written in a language the host can compile. Its ROM is a binary for a processor that no longer exists, so the emulator has to execute it, and the way it does that is to let the emulated code call into the host through the foreign function interface of the original platform. And the original platforms each had their own convention for that interface, so each one needs its own port, and the ports have to be maintained separately as the compiler and the operating systems move.

Which means that the eight directories are not redundancy. They are the price of the fidelity, and they are the reason the project can run on a phone today: somebody kept the interface port for the phone's platform current while keeping the one for the old handheld working.

The other directories follow the same logic. The packages directory is where the per-platform build definitions live, the resources directory holds the data the emulator needs, and the build, data and test directories with their leading underscores are the output of the build system rather than source. The documentation directory holds the user guide, and the readme points at it as the thing to read first.

Building it, and the small files that say how it is run

The build is driven by CMake, with a directory of build modules beside it, and there is a separate document for building it and another for contributing.

The interesting thing about the repository is how much of it is documentation about process rather than code. There is an issue template, which means the project wants structured bug reports rather than free-form ones. There is a build document, separate from the readme, which is where the per-platform build instructions live, because the readme cannot hold a set of instructions for a dozen targets and still be readable.

There is a change log, release notes and a release text, as we have seen. There is an editor configuration and a formatting configuration, so that a contributor's first patch is formatted the way the project expects. And there is a pre-commit configuration, which means the checks run before the commit rather than in the pipeline afterwards.

And there is a file instructing coding assistants, which is the most recent thing in a repository whose oldest directories are for platforms that stopped shipping in the middle of two thousand. That contrast is the project's whole character: a twenty-year-old emulation effort, carried forward by a small number of people, with the platform work done once per operating system and the incremental work done every time a compiler changes.

The result is a project that a newcomer can read, because the documentation is in the tree, and that a newcomer can also build, because the build system is a standard one with per-platform packages. What they cannot easily do is run it, and that is a deliberate and correct boundary: the emulation of a copyrighted system is the user's own business, and the project has decided that its obligation ends at the edge of it.

Editorial conclusion

Einstein fits somebody with a Newton device who wants the operating system running on a modern machine, and it fits a developer who wants to read a long-lived emulation project that has been ported to a dozen platforms. It does not fit somebody looking for the games, since it needs a system image that the project cannot ship. Verify first that you can obtain a system image legally, since the project deliberately distributes none and the readme points at a page on dumping one from your own device, that the build for your platform is one of the ones with a badge, since the two user interfaces and the platform ports are not equally finished, and that the documentation you need is in the repository rather than on a site that changes, since the readme points at a user guide file in the tree.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. pguyot/Einstein on GitHub
4. README
5. Releases