lxrun -- Frequently Asked Questions

Version 3.3

(last modified: Jan 10, 2001)


=== Section 0: The Basics ===

Q0.0: What is "lxrun"?

A: It is a Linux x86 binary emulator for other x86 *IX machines. Currently, the following platforms are supported:
  • SCO OpenServer 5.0.x
  • SCO UnixWare 2.1.* and 7.*
  • Sun Solaris 2.6, 7, and 8 for x86

Q0.1: How can I get started using lxrun?

A: Find a distribution and install it. :-) Currently, there are several known distributions in the form of source code and/or precompiled for various platforms. Here's a quick list:
The Official Lxrun WWW Site
This is the best place to get the latest source. However, due to limitations in ftp server space, you can't get precompiled binaries from this site.
SCO UnixWare 7.1
As of version 7.1 of SCO UnixWare, lxrun comes installed with the system. Just run your Linux binaries as if they were native, and lxrun will be invoked automatically. The version if lxrun currently shipping in UnixWare 7.1 is a little old, but it can be easily updated by compiling the latest sources and replacing the binaries that came with UnixWare.
SCO Skunkware site
The SCO Skunkware site has source and precompiled lxrun binaries for UnixWare and OpenServer platforms.
Sun Microsystems lxrun site
This site is a great resource, particularly for Solaris x86 users.

Installation instructions should be included with whatever distribution you pick.

Q0.2: How does lxrun work?

A: Quite well, actually. :-)

Seriously, it works by remapping system calls on the fly. As it turns out, there's not much difference between Linux and iBCS2 binaries. The main difference is the way in which system calls are handled. In Linux, an "int $0x80" instruction is used, which jumps to the system-call-handling portion of the Linux kernel. On other systems, "int $0x80" usually causes a SIGSEGV signal. Lxrun intercepts these signals and calls the native equivalent of the system call that the Linux program attempted. The result is that the Linux binary can be run (with the help of lxrun) with a small (usually negligible) performance penalty. All this is accomplished without modifying the kernel or the Linux binary.

Q0.2.1: What does "negligible performance penalty" mean?

A: Well, lxrun is not really an emulator, in that it's not really doing any emulation work. You can think of it more as a layer that sits between the Linux binary and the rest of the system doing a few translations here and there where it's necessary. When are these translations necessary? When the Linux binary attempts a system call. The rest of the time, lxrun is dormant and does not affect the performance of your application at all.

System calls are used for I/O, displaying things on the screen, accessing the network, etc. System calls are not used during computation. This means that computation-intensive applications (such as compilers, image processors, etc.) will show the least difference in performance.

As for more I/O-driven applications, consider this: The time it takes to access data on a hard drive or to transfer data over typical networks is usually measured in milliseconds. Are you really going to notice a few extra microseconds of system call translation? No... The time it takes for lxrun to remap a system call is effectively "lost in the noise"; it most often represents a tiny fraction of the overall elapsed time during the system call.

Finally, we have found cases where a Linux app running under lxrun on a UNIX system will actually outperform the same app running (without emulation) under Linux. We think this is the result of the UNIX kernel being more efficient at some tasks than the Linux kernel.

So to summarize: The performance "penalty" will probably not be noticeable -- and likely not even measurable.

The one exception to this rule is X-Windows performance. Since Linux apps can not use shared memory to communicate with a UNIX X server, you may notice a slight slow-down in graphics-intensive apps.

Q0.3: How do I run [name of your favorite OS] binaries on Linux?

A: Well, that's not really our department. It might be worth your while to check out the WINE project or see if you can dig up an iBCS2 driver for Linux. But as far as we're concerned, you're on your own.

Q0.4: Can you port lxrun to [name of your favorite OS] for me?

A: No, sorry. We (the lxrun team) barely have the resources to maintain lxrun, let alone make major enhancements...

However, lxrun has survived for quite some time on contributions of code from users just like you. In fact, the original Solaris port was just such a contribution. Mess around with it. Maybe you can get it to work. If you do, send us a patch!

Q0.5: Is there a version of lxrun that works on [name of non-Intel processor]?

A: Not that I know of. I've received a number of E-Mails from people asking if such a thing exists and suggesting that such a thing might be possible, but I haven't seen any real work done in this area.

Q0.6: Can I compile lxrun for Windows NT using a POSIX compatability layer?

A: It depends on how closely your POSIX layer emulates System V UNIX. Lxrun depends on all sorts of UNIX-specific (and System V-specific) behavior. While porting lxrun to NT is not out of the question, I do not think it would be an easy task.

Q0.7: Who wrote lxrun?

A: It was originally written by Michael Davidson, an engineer at SCO.

In 1997, Michael released the lxrun source code to Steven Ginzburg who is continuing its development as an open source project under the Mozilla public license. Contributors to lxrun have included hobbyists and engineers from all over the world. In addition, the Santa Cruz Operation (SCO) and Sun Microsystems have both contributed engineering time and other resources to the project.

=== Section 1: Building and Using lxrun ===

Q1.0: What does lxrun need in order to work?

A: To run most Linux programs, lxrun requires the help of the Linux dynamic loader (ld-linux.so.*) and whatever Linux shared libraries are required by the program.

Effectively, you need to set up a "Linux environment" that looks enough like a real Linux system to fool the program you are trying to run. For more information, see the section below on Linux environments.

Q1.1: What sorts of Linux binaries work well with lxrun?

A: Most programs that do not rely on Linux-specific quirks or deal directly with hardware should work under lxrun. Users of lxrun have reported success with raplayer (RealAudio client), xquake, some versions of the StarOffice suite, gcc (the GNU C compiler), and a myriad of smaller apps and utilities. While running most apps is usually straightforward, installing them and getting everything set up correctly can be tricky. See the official lxrun WWW site (http://www.ugcs.caltech.edu/~steven/lxrun) for hints on getting some of the more troublesome apps working.

Q1.2: What does the PATHMAP file do?

A: When you run lxrun, it creates an environment for the Linux app that "looks" like a real Linux system. The PATHMAP file configures that environment by telling lxrun which parts should come from your real, native filesystem and which parts should come from other places, such as your $LINUX_ROOT directory.

Each line in the PATHMAP file is a separate entry. Each entry consists of two parts: a path in the Linux environment and what that path maps to in your native filesystem. For example:

	/dev/mouse		/dev/tty1a

This tells lxrun that a Linux app attempting to access /dev/mouse should actually use /dev/tty1a instead. Individual files or whole directories can be remapped in this way. A plus (+) sign in the "map to" field represents $LINUX_ROOT. For example:

	/lib			+

This entry tells lxrun that anything the Linux app tries to access under /lib actually refers to $LINUX_ROOT/lib. This sort of mapping is useful for keeping your native and Linux libraries separate.

Q1.3.1: What is the difference between a "style 1" and a "style 2" PATHMAP file?

A: They are based on different models of Linux environment.

In the early days of lxrun, a Linux environment was often just a big lib directory containing lots of different Linux libraries acquired from different sources at different times as they were needed. A "style 1" PATHMAP file is based on this model; all lib directories are remapped to a few central places.

More commonly nowadays, people are using Linux environments that look like (or are) real Linux systems. These environments typically come from one of three possible sources:

Since these environments are laid out like real Linux systems, the PATHMAP file tends to be a direct mapping of certain important directories.

See the section below on Linux environments for more information.

Q1.4: How do I get shell scripts to work with lxrun?

A: Lxrun knows about shell scripts, and will attempt to do the right thing when it encounters one. However, there are some ways you can help lxrun do its job.

Consider the following shell script:


./linuxapp arg1 arg2

For lxrun to correctly execute "linuxapp", one of two things must happen: either your operating system must allow direct execution of Linux binaries (see Q1.5 below) or lxrun must be helping the script interpreter (/bin/sh in this case) to run, which probably won't be the case since /bin/sh is a native binary. However, you can use the PATHMAP file to map /bin/sh to a Linux shell, in which case the above script will work correctly.

To do this, install a Linux sh-like shell (e.g., "bash") in $LINUX_ROOT/bin and add the following line to your PATHMAP file:

	/bin/sh			+/bin/bash

This tells lxrun to use "bash" instead of "sh" to execute the shell script. Since lxrun will be helping the shell script run, "linuxapp" will be executed properly.

Q1.5: What do the files "ld-linux.so.?" and "liblxrun.so.1" do?

A: On some operating systems, lxrun is able to masquerade as the Linux dynamic linker allowing you to run most Linux ELF binaries as if they were native programs -- i.e., without typing "lxrun" first. This feature only works on UnixWare right now. UnixWare users can copy ld-linux.so.2 into /lib to make this feature work. On other platforms, the above files are useless and should be ignored.

Note that there is a big difference between the Linux dynamic loader (ld-linux.so.2) and lxrun masquerading as the Linux dynamic loader (also called ld-linux.so.2). For lxrun to work, you need a real Linux loader installed properly in your $LINUX_ROOT directory.

Q1.6: How do I build lxrun with gcc?

A: The Makefile included with lxrun is intended to be used with the native cc on the target platform. The file contains some alternate lines appropriate for gcc that you can use in place of the native-cc specific lines.

Edit the Makefile. Look for comments containing the word "gcc". Uncomment the commented-out gcc-specific lines and comment out the native equivalent.

Q1.7: The distribution is messed up! Lxrun won't build! The Makefile is broken!

A: Make sure you typed "make". Not "make all"...not "make lxrun"... Just "make". The Makefile will automatically detect the system on which you're running and reinvoke itself.

If your default shell is a C-shell derivative, you may need to add the line "SHELL=/bin/sh" to the top of the Makefile.

The reason the lxrun Makefile is so funky is because both SCO and Sun want it to be compatible with their internal build systems. Consequently, there's a lot of stuff in the Makefile that simply isn't applicable to someone building from the WWW distribution.

Q1.8: How come ld-linux.so.* wasn't built?

A: This file is only useful on UnixWare. If you're not building on UnixWare, the Makefile will omit it.

=== Section 2: Linux Environments ===

Q2.0: What is a "Linux Environment"?

A: The goal of an emulator is to fool the foreign application into thinking it's running on the sort of system for which it was written. Lxrun does a good job of simulating the Linux kernel, but that's only half the story. Most Linux binaries also require libraries, system databases, configuration files, etc. This collection of files is the Linux environment. If a program is behaving strangely or crashing under lxrun, it may be because the Linux environment you are presenting to your application is deficient in some way, e.g., missing an important data file.

Q2.1: How does lxrun form its Linux environment?

A: In your Linux environment, you probably want a combination of Linux files and files from your native system. For example, a Linux text editor requires Linux libraries, but you probably want it to operate on documents from your home directory on your native system.

Because of this, lxrun forms its Linux environment from a combination of native files and Linux files. You store the Linux files in a special directory and set the $LINUX_ROOT environment variable to point to it. The PATHMAP file in that directory tells lxrun where to find particular files -- whether to take them from the native filesystem or from the miniature Linux filesystem in the $LINUX_ROOT directory.

For example, the PATHMAP file usually maps /lib to $LINUX_ROOT/lib. This means that when your app attempts to access files in /lib (probably libraries) lxrun should look in $LINUX_ROOT/lib for those files. That way the app will find the Linux libraries instead of your native libraries which are stored in /lib.

Q2.2: When I set up a Linux environment, from which Linux distribution(s) should I take the files?

A: There are lots of Linux distributions in the world today. Though all of them use (slightly different versions of) the same kernel, the filesystems vary widely from distro to distro. For that reason, the most reliable way to run a program designed for a particular distro is to install your Linux environment files from that distro. That way, you will present a Linux environment to your application that closely resembles the environment in which it was meant to run.

Q2.3: What is the easiest way to set up a Linux environment?

A: Getting all the files you need in all the right places can be a real pain. Luckily, there are three fairly simple ways to do the job:

Q2.4: Where can I get an ext2fs driver for my UNIX system?

A: Currently, the only such driver known to the lxrun team is for Solaris only. It can be obtained from sunfreeware.com.

There is also a modified version on this site that allows you to mount Linux partitions that are within DOS extended partitions.

If you have problems with the driver, make sure you are using the latest version. Recent improvements include Solaris 8 support and support for more advanced versions of the ext2fs filesystem.

=== Section 3: Adding System Calls to lxrun ===

Q3.0: How robust is lxrun?

A: Somewhat robust. Obviously, the more system calls lxrun is able to emulate, the more complete its capabilities. In recent releases of lxrun, there are still quite a few unimplemented system calls, but they are calls that are not used very often. So lxrun can successfully run _many_ Linux binaries.

Q3.1: What if I find a Linux binary that lxrun doesn't support?

A: Follow these steps:

  1. Go to http://www.ugcs.caltech.edu/~steven/lxrun and make sure you have the most recent version of lxrun. If not, download the latest one and try it. We are updating lxrun with new system calls all the time.

  2. Try running lxrun in "trace" mode. If you type "lxrun" with no arguments and you see a "-t" option in the usage message, then your lxrun binary supports tracing. (If you don't see it, you'll have to recompile lxrun with tracing enabled in the Makefile.) When you enable tracing, you get a truss-like log of system calls that your program has attempted.
  3. Search the log for unexpected error messages or messages about unimplemented system calls. Try to narrow down exactly which system call failed. Often, the failure will be due to a system call that has not yet been implemented in lxrun.

  4. Implement the system call mapping. This is usually pretty easy to do. The vast majority of lxrun's code does mappings of this sort, so you can pick out almost any source file to see how it is done. Chances are, the system call you need to remap is already in one of the lxrun source files, but its code looks something like this:

    	int lx_flock()		{ return enosys("flock"); }	

    This means that you're the first person who has gotten around to mapping that particular system call.

  5. After making your modification, recompile lxrun and see if it works. You may have to remap more than one system call to get your binary working!

  6. E-Mail your changes to steven at ugcs dot caltech dot edu. This way, we can put your changes into the next release of lxrun.

  7. If steps 1-5 seem are beyond your programming ability, contact steven at ugcs dot caltech dot edu and maybe he or someone else will have time to give you a hand with it. Make sure to say exactly what program you're having trouble with and where you got it.

Q3.2: What are some known limitations in lxrun?

  • Installation can be a pain in the neck. :-)

  • X11 binaries must be run over TCP, which can cause performance to be poor.

  • No thread support (yet)

Q3.3: How hard can it be to implement the "clone" system call and make threads work?

A: Harder than you think.

Implementing the clone system call is only half the battle. Lxrun itself must be made thread-safe so that it won't crash if the application attempts to use two system calls at the same time from two different threads of execution. One of the goals of the 0.9.5-series development is to make lxrun thread-safe in anticipation of implementing the clone system call.

Once lxrun itself is thread-safe, the actual implementation of the clone system call will not be entirely straightforward. For one thing, lxrun must continue to run on four different UNIX variants spanning three major realeases of System V. The system with the oldest roots (OpenServer, based on System V release 3) doesn't even have native thread support! Implementing thread support in a system-independent way will be difficult, if possible at all.

There is one additional complication: There are plans for future versions of the Linux kernel and GNU libraries to make changes in the thread model. These changes involve mechanisms that are impossible for lxrun to emulate because they are too similar to the native System V (iBCS2) system call model. Once these changes take place, the only way lxrun will be able to support threads is with a shim library.

=== Section 4: Troubleshooting ===

Q4.0: What does "linuxemul: fatal error: program load failed: No such file or directory" mean?

A: It probably means you have your LINUX_ROOT environment variable set up incorrectly or there is something wrong with your PATHMAP file.

Q4.1: What does "progname: can't load library 'some_library_name.so'" mean?

A: It means you're missing a shared library that is needed to run a particular binary. You can either try to find a compiled version of the library from a Linux ftp site (such as ftp://sunsite.unc.edu/pub/Linux/libs/) or if you have access to a running Linux system, you can copy the library directly. You should put the library in $LINUX_ROOT/lib on your system (/usr/local/linux/lib by default).

Q4.2: Why are my Linux binaries unable to find their data files?

A: To keep your native files separate from Linux files that may have the same filename, lxrun prepends the contents of the $LINUX_ROOT variable to many common pathnames. The PATHMAP file that came with your distribution controls which paths get mapped where. Check to make sure your file isn't getting mapped somewhere unexpected by lxrun.

Q4.3: What does the following error message mean?
myprog: can't resolve symbol 'XXX'

A: This (and other strange messages) often mean that the Linux dynamic loader found a native library and is using it instead of the corresponding Linux binary. (You can find out exactly which library is causing the problem by examining the log file produced by an lxrun system call trace. See Q2.1 above for more information.)

This glitch will only show up if you have a native library installed that has the same name as a needed Linux binary. If you have XFree86 installed on your native system, the /usr/X11R6/lib libraries are common culprits.

The best solution is to make sure no native libraries are available anywhere under the directory pointed to by $LINUX_ROOT.

Q4.4: My Linux application is crashing, behaving strangely, or just plain not working. Can you give me some general advice for tracking down the problem?

A: I'd be glad to.

First, check your libraries. Where did you get the Linux libraries you're using? Are they fairly up-to-date? The most reliable way to pick libraries is to take them from a Linux system that you know can run the application in question. Avoid mixing libraries from different Linux distributions or different libc versions. Note that the libraries included with UnixWare 7.1 or found on Skunkware may not work for you depending on what app you're trying to run.

If that fails, use the "-t" option to tell lxrun to produce a system call trace while running your application. (You should probably start with the "-t sys" option because it will give you the most complete, yet concise output.) Here are some things to look for in the trace dump:

  1. Failed system calls -- These are often, but not always, an indication of a problem. For example, it's a problem if the application tries to open a file, can't find it, and then core dumps. It's probably okay if the application tries to open a file, can't find it, checks another directory, finds it there, and continues. Both cases will appear as a failed "open" call in the system call trace.
  2. Unimplemented system calls -- If your application tries to do something that lxrun doesn't know how to handle, this will most likely cause problems.

Q4.5: What should I do if I find a problem with lxrun, and even after reading this FAQ, I can't solve it?

A: Please report any difficulty you have with lxrun by e-mailing steven at ugcs dot caltech dot edu. Feel free to include suggestions, comments, code modifications, extensions, ...

The lxrun FAQ is maintained by Steve Ginzburg (steven at ugcs dot caltech dot edu)

A special thanks to:

Visit the lxrun web site at: http://www.ugcs.caltech.edu/~steven/lxrun for the latest news...