3.3. Installing a Binary

This section is divided up by platform, since installing a binary package is different on different platforms.

3.3.1. Windows

The Bochs binaries for Windows are distributed in an EXE installer package. The Bochs installer can be started like any other Windows program and it brings up the installation wizard. Here you can select the destination folder and the installation options. The wizard installs the files and creates the registry keys, start menu and desktop links.

Previous releases of Bochs were distributed as ZIP packages, too. These packages contained the same set of files as the installer package from the same version.

If you are new to Bochs you should try out the DLX Linux demo distributed with Bochs. The installation wizard has created a link on the desktop if you decided to install the demo. If you doubleclick the icon two windows will appear: one is the Bochs Display window, and the other is text window that is used for the runtime configuration and for log messages if no logfile is specified.

You can find more information on the DLX Linux demo in the next section below the DLX Linux screenshot.

Table 3-3. Files in Bochs directory (Windows version)

FileDescription
bios.bin-1.13.0 SeaBIOS ROM image
BIOS-bochs-latest default ROM BIOS image for Bochs
BIOS-bochs-legacy ROM BIOS image without 32-bit init code
bochsdbg.exe the main Bochs executable with debugger enabled
bochs.exe the main Bochs executable
bochs.ico the Bochs icon (used for links in start menu and on the desktop)
bochsrc-sample.txt sample Bochs configuration file
bxhub.exe utility required for the 'socket' networking module
bximage.exe tool for manipulating disk images
CHANGES.txt what has changed between versions
COPYING.txt copy of the LGPL license
lgban.ico a set of Bochs icons in different sizes
LICENSE.txt Bochs license information
logo.ico another set of Bochs icons
niclist.exe tool to find out the network interface name
penguin.ico icons for the DLX Linux link
README.txt the read-me file from the source distribution.
sb16ctrl.exe tool to control sb16 in Bochs
sb16ctrl.txt examples of sb16ctrl commands
SeaBIOS-README.txt README for SeaBIOS ROM image
SeaVGABIOS-README.txt README for SeaVGABIOS ROM image
slirp.conf sample config file for the advanced 'slirp' network configuration
vnet.conf sample config file for the advanced 'vnet' network configuration
TODO.txt the TODO file from the source distribution.
unbochs.ico icon for the uninstaller link
uninstall.exe uninstall program for Bochs (created by the installation wizard)
vgabios-cirrus.bin-1.13.0 SeaVGABIOS ROM image (for Cirrus adapter)
VGABIOS-elpin-2.40 VGA BIOS image for Bochs
VGABIOS-elpin-LICENSE.txt license for VGA BIOS
VGABIOS-lgpl-latest LGPL'd VGA BIOS image for Bochs
VGABIOS-lgpl-latest-debug LGPL'd VGA BIOS image for Bochs with debug output to the logfile
VGABIOS-lgpl-latest-cirrus LGPL'd VGA BIOS image for Bochs with the Cirrus extension enabled
VGABIOS-lgpl-latest-cirrus-debug LGPL'd VGA BIOS image for Bochs with the Cirrus extension enabled and debug output to the logfile
VGABIOS-lgpl-latest-banshee LGPL'd VGA BIOS image for Bochs with the Voodoo Banshee extension enabled
VGABIOS-lgpl-README.txt readme for the LGPL'd VGA BIOS
dlxlinux\ directory containing DLX linux sample disk image and configuration files
dlxlinux\bochsrc.bxrc Bochs configuration file for DLX
dlxlinux/hd10meg.img disk image file (10 meg)
dlxlinux\readme.txt description of DLX linux
dlxlinux\run.bat Run this BAT file to try out DLX Linux inside Bochs!
dlxlinux\testform.txt Form for reporting success or failure
doc\index.htmla local copy of all Bochs documentation (online copy)
keymaps\*.map keymap tables (on Windows used for the paste feature only)

3.3.2. Linux RPM

RPM stands for "RedHat Package Manager." An RPM is a compressed file containing files to be installed on your system. Many Linux distributions, not just RedHat ones, can install files from an RPM. First, download the Bochs RPM for your architecture to your computer. For example, if you have an Intel-compatible computer, be sure to get the RPM that says "for Linux x86 distributions" or "i386". Once you have the package on your local disk, you should become the root user and install it as follows[1]:

Figure 3-2. Installing an RPM in Linux

  user$ su
  Password:
  root# ls -l bochs-2.5.x86_64.rpm
  -rw-r--r--    1 user     users     2628643 Nov 27 17:20 bochs-2.5.x86_64.rpm
  root# rpm -i bochs-2.5.x86_64.rpm
  root# exit
  user$ _

All RPM installations are done as the root user because they require permission to update system files and directories. If you do not have root access you need to compile Bochs in your home directory.

RPM installation can fail for a few reasons. It will fail if you already have a Bochs package installed. In this case, try upgrading the old package to the new package with rpm --upgrade NAME.i386.rpm. Another potential problem is missing RPM dependencies. If you are getting errors about missing files or RPMs, then first you should try to install the RPMs that provide the missing pieces. If that cannot be done, download the source RPM and build a new binary RPM that is appropriate for your platform. The command is rpmbuild --rebuild NAME.src.rpm. As a last resort, you can run rpm with the --nodeps option to ignore dependencies and install it anyway, but if it is missing important pieces, it may not run properly.

The Bochs RPM installs five new commands and associated manual pages: bochs, bochs-dlx and bximage. First, let's try out the DLX Linux demo by typing bochs-dlx.

  user$ bochs-dlx
  ---------------------------------------------------------------
	      DLX Linux Demo, for Bochs x86 Emulator
  ---------------------------------------------------------------
  Checking for bochs binary...ok
  Checking for DLX linux directory...ok
  Checking for /bin/gzip...ok
  Checking for /usr/users/bryce/.bochsdlx directory...
  ---------------------------------------------------------------
  To run the DLX Linux demo, I need to create a directory called
  /usr/users/bryce/.bochsdlx, and copy some configuration files
  and a 10 megabyte disk image into the directory.
  ---------------------------------------------------------------
  Is that okay? [y/n]
  y
  Copying /usr/share/bochs/dlxlinux/bochsrc.txt -> /usr/users/bryce/.bochsdlx/.
  Copying /usr/share/bochs/dlxlinux/README -> /usr/users/bryce/.bochsdlx/.
  Copying /usr/share/bochs/dlxlinux/testform.txt -> /usr/users/bryce/.bochsdlx/.
  Uncompressing /usr/share/bochs/dlxlinux/hd10meg.img.gz -> /usr/users/bryce/.bochsdlx/hd10meg.img
  Entering /usr/users/bryce/.bochsdlx
  Running bochs
  ========================================================================
			Bochs x86 Emulator 2.4.6.svn
		Build from SVN snapshot, after release 2.4.6
                     Compiled on Oct 20 2011 at 19:40:05
  ========================================================================
Then you get a new X11 window containing the VGA display of the simulated machine. First you see the VGA BIOS screen, then Linux uncompresses and boots, and you get a login prompt. Type "root" and ENTER to log in to DLX linux.

Figure 3-3. Screenshot of Bochs running DLX Linux

Booting is complete when you see "dlx login:" and a cursor. At this login prompt, type "root". On UNIX systems, root is the system admin user. There is no password for root on this sample disk image, so it lets you log in without typing any password. Now you should see a UNIX prompt, and you can begin to type UNIX commands.

  Welcome to DLX V1.0 (C) 1995-96 Erich Boehm
                      (C) 1995    Hannes Boehm

  dlx login: root
  Linux 1.3.89.
  dlx:~# pwd
  /root
  dlx:~# cd /
  dlx:~# ls
  bin/       etc/       lost+found/       root/       usr/
  boot/      fd/        mnt/              sbin/       var/
  dev/       lib/       proc/             tmp/        zip/
  dlx:/# df
  Filesystem    1024-blocks   Used  Available Capacity Mounted on
  /dev/hda1        10060      2736      6005     29%   /
  dlx:/# _

When you get tired of playing with DLX Linux, just type "reboot" in the Bochs window to shut down the DLX Linux operating system, and when it starts to reboot again press the "Power" button at the top of the Bochs display to end the application.

Here is a list of the files that are installed by the RPM, and a brief description of each one.

Table 3-4. Files in RPM package

FileDescription
/usr/bin/bochs the main Bochs executable
/usr/bin/bochs-dlx run this script to try out DLX Linux inside Bochs!
/usr/bin/bxhub utility required for the 'socket' networking module
/usr/bin/bximage tool for manipulating disk images
/usr/lib/bochs/plugins/* plugins (devices, guis, etc.) for Bochs (plugin version only)
/usr/share/doc/bochs/bochsrc-sample.txt sample Bochs configuration file
/usr/share/man/man1/* man pages for bochs, bochs-dlx and bximage
/usr/share/man/man5/* man page for bochsrc
/usr/share/doc/bochs/CHANGES what has changed between versions
/usr/share/doc/bochs/COPYING copy of the LGPL license
/usr/share/doc/bochs/LICENSE Bochs license information
/usr/share/doc/bochs/README the read-me file from the source distribution.
/usr/share/doc/bochs/TODO the TODO file from the source distribution.
/usr/share/doc/bochs/index.html a local copy of all Bochs documentation ( Online copy )
/usr/share/doc/bochs/slirp.conf sample config file for the advanced 'slirp' network configuration
/usr/share/doc/bochs/vnet.conf sample config file for the advanced 'vnet' network configuration
/usr/share/bochs/BIOS-bochs-latest default ROM BIOS image for Bochs
/usr/share/bochs/BIOS-bochs-legacy ROM BIOS image without 32-bit init code
/usr/share/bochs/SeaBIOS-README README for SeaBIOS ROM image
/usr/share/bochs/SeaVGABIOS-README README for SeaVGABIOS ROM image
/usr/share/bochs/VGABIOS-elpin-2.40 VGA BIOS image for Bochs
/usr/share/bochs/VGABIOS-elpin-LICENSE license for VGA BIOS
/usr/share/bochs/VGABIOS-lgpl-latest LGPL'd VGA BIOS image for Bochs
/usr/share/bochs/VGABIOS-lgpl-latest-debug LGPL'd VGA BIOS image for Bochs with debug output to the logfile
/usr/share/bochs/VGABIOS-lgpl-latest-cirrus LGPL'd VGA BIOS image for Bochs with the Cirrus extension enabled
/usr/share/bochs/VGABIOS-lgpl-latest-cirrus-debug LGPL'd VGA BIOS image for Bochs with the Cirrus extension enabled and debug output to the logfile
/usr/share/bochs/VGABIOS-lgpl-latest-banshee LGPL'd VGA BIOS image for Bochs with the Voodoo Banshee extension enabled
/usr/share/bochs/VGABIOS-lgpl-README readme for the LGPL'd VGA BIOS
/usr/share/bochs/bios.bin-1.13.0 SeaBIOS ROM image
/usr/share/bochs/dlxlinux/ directory containing DLX linux sample disk image and configuration files
/usr/share/bochs/dlxlinux/readme.txt description of DLX linux
/usr/share/bochs/keymaps/*.map keymap tables for X11, SDL and SDL2
/usr/share/bochs/vgabios-cirrus.bin-1.13.0 SeaVGABIOS ROM image (for Cirrus adapter)

3.3.3. MacOS X DMG

This was contributed by Aard Vark in January 2003

The MacOS X binary distribution is a mountable disk image (.dmg file). Once you've downloaded the binary distribution file, just double click on it to automatically unpack the archive and mount the volume on the desktop. An icon will appear exactly as if you'd inserted a CD-ROM or removable storage device, and a finder window containing the volume should automatically open. It is likely to have an odd name such as _dmg_top, but don't worry about that.

Copy the Bochs-2.0 (or whatever version) folder from the disk image onto your hard disk. Either Home or Applications would be sensible places to put it. Because the disk image is mounted read only, you can't run the included dlxlinux guest OS until you've copied it to the hard disk.

Once you've installed the binaries, it's probably a good idea to drag the _dmg_top volume to trash to unmount it, so you don't get confused and try to run Bochs from there. Then open the Bochs folder from wherever you installed it.

The MacOS X version of Bochs requires a terminal window to run. If you just double click on the Bochs icon, you'll get an error message telling you to double click on "bochs.scpt" to start Bochs in a new terminal window. You'll need to configure Bochs before you will get very far with the bochs.scpt in the top folder, so to try out Bochs open the dlxlinux folder and double click on the bochs.scpt icon inside.

This will open a new terminal window which will contain the Bochs startup messages, and a configuration menu. The default option is [5], which starts the simulation, so press enter to do so. You will then get a new window containing the VGA display of the simulated machine. The new window will probably appear behind the current terminal window, so either click on the Bochs icon in the dock or the simulation window to bring it to the front. If you're quick enough you'll then see the VGA BIOS screen, then Linux uncompresses and boots, and you get a login prompt. Type "root" and ENTER to log in to DLX Linux.

Once you've finished playing with DLX Linux, just type "reboot" in the Bochs window to shut down the DLX Linux operating system, and when it starts to reboot again press the "Power" button in the "MacBochs Hardware Controls" window (it's the circle containing a vertical bar at the far right - have a look at the Linux screenshots, since the Mac version doesn't seem to have descriptions or tool-tips).

Notes

[1]

Many distributions have their own RPM installer program, often graphical, and they should work ok. It is helpful to be able to see the text output from RPM, so if you use a fancy RPM installer, be sure to find the text output and check that it looks correct.