/sys/doc/ Documentation archive

Starting off with Inferno

These notes tell how to install and start playing with the Inferno system. Topics covered include starting it up, making yourself an Inferno user, and the basics of command execution. For detailed information about any of the points here, you'll need the reference materials.

The basic idea

On both Windows and Unix machines, a program called emu (for emulator) supports the Inferno environment by creating a virtual machine for Inferno programs. It starts with one command-line text window: the control console for Inferno. Here, typed commands are Inferno commands, not those of the the underlying operating system. The file system available to its commands and other applications is the Inferno file system, which is a subtree of the the files presented by the Windows or Unix system on which Inferno is hosted.

The console is mainly used for basic administration and to start an Inferno window manager. The supplied system actually supports three different user interfaces to try: this command-line interface, a GUI interface with graphics based on Tk, and a demo version of an ITV (interactive television) set-top box.

Starting up on Windows (95 or NT)

Use your browser to download the InstallShield executable selection; its file name is inferno.exe. It is best to use Save As directed to an empty folder, or put it on the Desktop, so you can find it easily; otherwise, depending on your browser, it may land in a hard-to-see place.

Run inferno.exe. It will extract itself into 11 files. A DOS window will appear reporting the results; this window can be deleted once the extraction is done.

Run the file called setup.exe to install Inferno. The installation procedure is automatic except for a couple of dialog boxes.

setup.exe will make an entry for Lucent Inferno on your Programs menu. Except for such shortcuts, the whole distribution will go into the folder \users\inferno.

To run Inferno, select the emu subentry from the Lucent Inferno item on the Programs menu. This will make a command-line (text) window for the Inferno control console.

The actual path to the Inferno emulator on Windows (either kind) is \users\inferno\Nt\386\bin\emu.exe.

Starting up on Unix-like systems

Download the appropriate files: they will be called Inferno_Base.tar.Y and Inferno_X.tar, where X is one of Sol, SGI, or Plan9, and Y is .Z or .gz. Put it in the directory you want Inferno to go (say, /usr/inferno) and extract it. If you use tar remember to set the p flag to preserve permissions. To run Inferno, find the appropriate binary for the system you are on: one of


When you run it in a window, that window becomes the control console for the Inferno machine.

It would be useful to make a symbolic link or shell script referring to the appropriate instance of emu with desired options.

Playing with Inferno: Windows and Unix

When you run emu, you'll see some chatter and a prompt, like this:

	Inferno BETA.2 Build 11 main (pid=132) interp
	Initialize Dis: /dis/sh.dis
On Windows, this will be in a newly made DOS window; on a Unix system, it's more likely that you typed "emu" in an existing window. In either case, this window is now the control console for Inferno. If you type your standard program-interrupt character (typically ^C or DEL) here, you will kill off this instance of Inferno.

You can type commands to configure your environment and start the window system, and the standard output of programs--such as the output from print statements--will appear in this window.

In the console window, you start off located at the root of the Inferno file system: the directory known as /usr/inferno or \users\inferno to the outside world. Incidentally, if you put the distribution other than the standard place, you will need to use the -r option of emu to let it know where its root is.

Most of the console commands are Unix-like; for example cat, ls, mkdir, grep, cd are there. You can see the commands by typing

	ls /dis
The file separator in Inferno is the /, not the \.

For your first session, don't worry about configuration. Just enter the Inferno window system by typing

at the console. This will trigger the creation of a new window. With Microsoft Windows you'll see a new Inferno icon in the taskbar; click it to pull up the Inferno graphics window. Under Unix, using the X window system or a derivative, do whatever you've configured to set focus in X.

In either case, you'll see a logon screen appear in the Inferno display window, asking for your user name. Just type inferno and hit return.

The logon window will resolve to an aquamarine screen with a grey bar bearing an Inferno icon. This is the startup screen for the Inferno window manager.

When you click on the Inferno icon using the left mouse button, Windows style, a menu appears. The bottom half of the menu is defined by the system and has the basic system services; the upper half (except for the top line) is defined by the contents of your wmsetup file (see below). Click, for example, on the Applications button to see its submenu. Click on one of the entries of the submenu and the corresponding application will start. For example, the top Applications entry invokes a simple text editor. Clicking Shell in the main menu will start a command-line window, much like the console. This shell is rudimentary, but does understand redirection (with < and >), piping (with |), file-name expansion (with * etc), and quoting with '.

Configuring Inferno

Inferno user's directories are located in /usr in the Inferno file system. To set yourself up, do

	mkdir /usr/yourname
in an Inferno shell window. Make sure this directory is owned and operated by you. It's a good idea to check this from outside Inferno, in order to verify that the user-ID mapping is correct-- Inferno mirrors the ownership and permissions of files from your underlying operating system.

After you've made the directory, copy the files wmsetup and namespace into your own directory:

	cp /usr/inferno/wmsetup /usr/yourname
	cp /usr/inferno/namespace /usr/yourname
Once you've done this, you can log on to Inferno (at the wm/logon screen) using yourname. The wmsetup file controls the contents of the main and submenus of the Inferno button, in a fairly obvious way: first the main menu item, then the submenu, then the file that contains the application itself. The current contents are approximately:

	# This file defines the format of the
	# start button in wm
	System:Task Manager:/dis/wm/task.dis
	System:Limbo Debugger:/dis/wm/deb.dis
	System:Module Manager:/dis/wm/rt.dis
	Applications:Text Editor:/dis/wm/edit.dis
	Applications:HTML Browser:/dis/wm/guido.dis
	Media Players:Coffee:/dis/wm/coffee.dis
	Media Players:Viewer:/dis/wm/view.dis
	Media Players:Mpeg Player:/dis/wm/mpeg.dis
	Media Players:AVI Player:/dis/wm/avi.dis
	Media Players:QuickTime Player:/dis/wm/qt.dis

The setup document that comes in the downloaded Documentation Set contains further information about configuring the system, in particular the networking facilities.

Interactive TV

Although the programs are not very useful without the right hardware, and want spiffing up by good graphics interface designers, it's worth investigating the other Inferno environment. At the Inferno console, type

You will get a menu intended to be browsed by a TV remote control. Use these keyboard characters to move around:

	i	up in menu
	m	down in menu
	j	left in menu
	k	right in menu
	space	pop up from current selection
	CR	activate selected item
	x	pull up main menu, leaving app running
Several of these applications are mere stubs, and all the actual content is faked. In the lab the mail is our own mail, the newswire is the real AP, and you get video for at least some of the movies and news clips. However, the demo gives at least the flavor of the possibilities. At the very least, looking at the Asian 'newspapers' demonstrates the integration of Unicode (even if the content consists of the Japanese translation of the Unix troff manual), and glancing at the movie synopses shows that a Markov algorithm is as competent as anyone at summarizing movies.

Where things are

The binary versions of programs are stored somewhere under the directory /dis, and the suffix of their names is .dis. Commands intended for command-line typing (e.g. to the Inferno console) are directly under /dis; those for the window manager are under /dis/wm; those for ITV are under /dis/mux.

Correspondingly, the Limbo source for the applications lives under /appl/cmd for text-only command things, /appl/wm for windowing programs, and /appl/mux for ITV. The standard suffix for Limbo programs is .b. We have included the Limbo source for most of the applications.

Compiling Limbo programs

You're encouraged to write your own applications; starting out by modifying existing ones is a good way of starting out. The tools that run directly under your native operating system, including the Limbo compiler, are found in the same directory as emu:


HTML renditions of the manual pages are part of the main distribution package; they are in /usr/man/html/[1-9]. They can be read by any convenient browser.

The documentation package is separate, and the papers in it are in both Postscript and PDF format. If you don't have a browser for PDF, you can get a free version of the Adobe Acrobat reader from Adobe.

A few more facts about emu

Emu is a C program that runs above a regular operating system. It's composed of lots of processes running in a single shared address space, so don't be surprised if you run (in Unix) ps and see dozens of processes running.

There is no way to call arbitrary C code from emu, only Limbo programs. There is an escape hatch, the cmd driver (see the man page cmd (3)), to enable running C programs in the external environment, but its interface is strictly controlled. In particular, the list of commands that may be called this way is restricted. One example of a program run this way is webget, a C program that implements the back end of the web browsers, off-loading URL lookup, graphics file conversion, and so on.

Emu has several options. The -c1 option causes all Limbo programs to be compiled on-the-fly into native code when loaded; by default, Limbo is interpreted. (Finer-grained control of compilation is forthcoming; watch this space.) The -g option tells emu what size window to make; the default is -g640x480. The -r option selects a root for the Inferno system other than the standard one.

When a Limbo program misbehaves, the error may manifest itself as a fault reported by the interpreter. This, for example, is what occurs if a Limbo program tries to indirect through a nil pointer. Therefore, emu catches faults and suspends the offending program, which may then be examined by the Limbo debugger. The -s flag to emu turns off this behavior, to enable debugging of the emulator itself.

To exit emu, type a Delete or Ctrl-C, whatever your interrupt character is, in the console window.