Tree [51af39] master /
History



File Date Author Commit
extras 2010-03-31 David Given David Given [de3fed] Correctly set the terminal type.
src 2010-03-31 David Given David Given [93daac] Added getresuid() and getresgid().
tools 2010-03-07 David Given David Given [0494b2] First version in git.
website 2010-04-01 David Given David Given [51af39] Added links to LINE and LOW.
LICENSE 2010-03-29 David Given David Given [f1676d] Built installer, wrote README, tidied the BusyB...
README 2010-03-31 David Given David Given [ab8253] Added source README. Added distribution system....
README.source 2010-03-31 David Given David Given [ab8253] Added source README. Added distribution system....
mkdist 2010-03-31 David Given David Given [ab8253] Added source README. Added distribution system....
pm 2010-03-16 David Given David Given [cab0f3] Updated Prime Mover to 0.1.5.
pmfile 2010-03-31 David Given David Given [ab8253] Added source README. Added distribution system....
sync-website 2010-03-31 David Given David Given [44de2c] Add website sync script.

Read Me

                                  LBW v0.1
                                  ========
                                  
                         Copyright (C) 2010 David Given
                                 2010-04-01
            
            
                                 
INTRODUCTION
============

LBW is a system call translator that allows you to run unmodified Linux
ix86 binaries on Windows.

It is not virtualisation; only one operating system is running, which is
the Windows one. It is the equivalent of WINE, but in reverse, translating
Linux system calls into Windows ones for execution. It is not emulation; the
Linux applications run directly on the processor, resulting in (theoretically)
full native performance.

Currently it is in a proof-of-concept stage and is no way suitable for doing
real work on --- it's full of bugs --- but currently it's good enough to run
a Debian chroot, install packages with apt and dpkg, compile and run programs
using gcc, ssh into remote terminals, and even run some basic X clients.
Both static and dynamic binaries are supported (using Linux's own user-space
dynamic binary loader).

Right now it's known to work on Windows XP (because that's where I do my
development). It is known not to work on Windows 7 --- I don't know why
(assistance appreciated). I have no access to other Windows versions. Please
let me know the results if you try it.

LBW is released under the MIT open source license; please see the file
LICENSE in the installation directory for the full text.


                                *** BEWARE ***

                                 LBW is EVIL.
                                                                 
                        Lots of things in LBW don't work!
                        
                        Lots of things will *never* work!
                         
                                IT WILL CRASH.
                                
                   Back up your data, keep your system secure,
                              and above all else:

                             YOU HAVE BEEN WARNED.



USAGE
=====

The distribution package will (if you let it) set up a simple little chroot
using BusyBox. You can run this from the Start menu. This can be used to
run static binaries. If you want to run dynamic libraries, see the section
below on running Debian. (Or you could install the libraries in the BusyBox
shell, but you'll have to do this yourself.)

/proc is not supported yet; some applications will fail due to its absence.

/home is symlinked to point at your Windows home directory;
"/home/My Documents" and "/home/Desktop" will work, for example.

Your Windows drives can be found in /dev/fs.

You *can* run Windows software directly from inside LBW --- make sure the
.exe is executable and just run it.

You can run as many LBW shell sessions as you like.

LBW can be run manually from the Windows command line. The syntax is:

    posix /c "C:\PathWhereYouInstalledLBW\lbw" \
        [<LBW options...>] <executable> [<Linux options...>]
  
There is a bug in Interix where the above won't work if the executable is in
a path containing spaces --- such as C:\Program Files. The 'posix /c' works
around this. And yes, the lbw executable is *supposed* to not have a .exe
file extension.

LBW can *also* be run manually from an Interix or LBW command line. In this
situation, do:

   /dev/fs/C/PathWhereYouInstalledLBW/lbw
        [<LBW options...>] <executable> [<Linux options...>]

It's perfectly safe to run LBW from inside LBW --- in fact, that's what
happens normally when you run programs.

LBW supports the following command line options:

    --help         Displays brief usage information.
    
    --fakeroot     Enables a simple fakeroot mode.
                       Note that this is not a real fakeroot; all it does is
                       force getuid() to return 0 and make chown() etc ignore
                       errors. It's just enough to keep Debian happy.
                       
    --chroot <dir> Set up a simple chroot.
                       This is not a real chroot; it's entirely not suitable
                       for security purposes, and some of the semantics
                       aren't right.
                        
    --warnings     Show emulation warnings.
                       Normally when LBW sees something it doesn't handle
                       properly it won't warn the user (as it gets really
                       annoying when you just want to get stuff done). This
                       option will cause LBW to spam you with all the info.



RUNNING DEBIAN
==============

If you want to run a full Debian chroot, you will need access to a real Debian
32-bit x86 machine to contruct a filesystem. (For legal reasons I cannot
distribute a Debian filesystem with LBW, and cdebootstrap doesn't work yet.)

On your Debian system, become root, and then do:

   cd /tmp
   deboostrap lenny debian
   tar cvjf debian.tar.bz2 debian
   
Transfer the debian.tar.bz2 file to the desktop of your Windows machine.

On the Windows machine, start the BusyBox shell and do:

   cd /
   tar xvjf "/home/Desktop/debian.tar.bz2"
   
Once it's decompressed, you can start the Debian chroot with:

   fakeroot chroot debian /bin/sh
   
You probably next want to teach Debian about the console by doing:

   tic "$LBWHOME/interix.termcap"
      
...and then:

   apt-get update
   apt-get install python
   python 

Bear in mind that the system is not fully initialised, and it will require
some tinkering to make work. Also, LBW simulates Linux *processes*, not a
Linux *machine*; whenever Debian tries to do system management, such as
adding users or trying to run init, it will fail. 

Plus, various things do *not* work, some things crash, some things fail in
really weird ways that confuse the package manager, etc. I have to wipe and
reinitialise my Debian chroot on a regular basis as things go wrong with it.
On the other hand, lots of stuff works, so if you're careful, you can get a
lot done.



MORE INFORMATION
================

Please see the website at:

    http://lbw.sourceforge.net
    
...for more information, including a discussion of the things that don't
work (which I'm not going into here, because there's just too many).



THE AUTHOR
==========

Prime Mover was written by me, David Given. You may contact me at
dg@cowlark.com, or visit my website at http://www.cowlark.com. There may or
may not be anything interesting there.



CHANGELOG
=========

2010-04-01: First version released to an unsuspecting world. Many thanks to
Jayson Smith for being the first guinea-pig to try this *ever*. He's a brave
man and a lucky one.