Author: Kevin Lawton

# Compiling and Installing Bochs

- Getting current source code
- Compiling source code
- Setting up environment before running
- Bochsrc file options
- Bochs command line options
- Installing an OS (DOS/Win'95/Minix/Linux) within Bochs
- ChangeLog
- Optional command line debugger
- Optional cosimulation debugger
- Instrumentation
- mtools: utilities to access DOS disks in Unix

- LGPL License
- 3rd Party Software Licensing and Temporary Files
- Bochs source code developers email mailing list
- Summary of current Bochs supported features
- X11 Keyboard Hacks

## Getting current source code

Source code for Bochs, is available via anonymous FTP at ftp://bochs.com/pub/. Release names are of the format bochs-YYMMDD.tar.gz. Log in as anonymous and use your email as the password.

## Compiling source code

All releases are gzip'd tar files. That means the whole Bochs source code directory has been consolidated into one file using the Unix command 'tar', then compressed to save space with GNU 'gzip'. To extract the source code, you'll need both 'tar' and 'gzip/gunzip'. All files are contained within one subdirectory named 'bochs-YYMMDDv'.

        cd /path/parent-directory
        gzip -dc bochs-YYMMDDv.tar.gz | tar -xvf -
        cd bochs-YYMMDDv

Before compiling, you'll need to run the configure script, which will configure source code to run on your system, and with your chosen options. There are many options to 'configure', and you probably don't need any of them. If you run BeOS, specify '--with-beos' to configure. To see a complete list:

        unix-> ./configure --help

For more complete documentation of options available to configure, click on this link.

You will also need to set environment variables to tell configure what compiler and options to use. Check out this link. It's the same as the one above.

Now run configure, be it manually or by way of a script file.

        unix-> ./configure
           -or-
        unix-> ./.conf.x86

If the configure script bombs, check 'config.log'. Specifically, look for errors returned by the compiler. You may have options incompatible with your compiler. See the link on setting the environment variables above.

Assuming at this point all went well with the configure command, edit the file 'config.h', which was generated by ./configure. Look for the USER CONFIGURABLE OPTIONS section. Each parameter available for editing is documented. Generally the defaults are fine for typical users. Please read about each parameter and edit carefully. NOTE: This file is generated, and will be deleted if you run 'make dist-clean'.

You may now compile the source.

        unix-> make

## Setting up environment before running

In text mode, Bochs requires your X server to have access to the VGA font. If you don't already have it, you must install it from one of the font files in bochs-yymmdd/font.

There are two options; you may install the VGA font in a global place, or in a local directory. You may need to install it locally if you don't have root access.

Option 1: installing VGA font in global font directory

       # NOTE1: Make sure your DISPLAY variable points to local machine.
       # NOTE2: These steps require root privileges.
       # NOTE3: Your X11 fonts path will vary on different systems. For example:
       #        Solaris 2.x /usr/openwin/lib/X11/fonts
       #        Linux       /usr/lib/X11/fonts/
       root-> cp font/vga.pcf font-path-here/misc
       root-> compress font-path-here/misc/vga.pcf
       root-> mkfontdir font-path-here/misc
       root-> xset fp rehash

Option 2: installing VGA font in local font directory

       # NOTE1: Make sure your DISPLAY variable points to local machine.
       # NOTE2: The "xset" command needs to be run for each X session.
       user-> mkfontdir bochs-YYMMDD/font
       user-> xset fp+ [full-path]/bochs-YYMMDD/font

Hard Drive Image File: Bochs emulates a hard drive by using a large Unix file, which you must create. The size of the hard drive is dependent upon the number of cylinders, heads, and sectors-per-track that you would like to emulate. Here are some examples of possible drive geometries:

Size | Cylinders | Heads | Sectors/Track | Sectors Total
--- | --- | --- | --- | ---
10MB | 306 | 4 | 17 | 20808
20MB | 615 | 4 | 17 | 41820
30MB | 615 | 6 | 17 | 62730
46MB | 940 | 6 | 17 | 95880
62MB | 940 | 8 | 17 | 127840
112MB | 900 | 15 | 17 | 229500
126MB | 256 | 16 | 63 | 258048
483MB | 1024 | 15 | 63 | 967680
504MB | 1024 | 16 | 63 | 1032192

Pick the size of the hard drive you want to emulate, and create a blank file according to the parameters in the table. If you have the 'dd' command, you can use it to create the file. Keeping in mind that there are 512 bytes in a sector, just use the number of "Sectors Total" from the table as the 'count=' option to dd, and tell dd to use a block size ('bs=') the same as a disk sector size (512). For example, for a 112MB drive, there are 229500 (900*15*17) sectors.

        unix-> dd if=/dev/zero of=112M bs=512 count=229500

Floppy Disk Image File: Bochs emulates a floppy drive/disk using either a Unix file, or a real floppy drive Unix device. To use either, you will need an entry in your '.bochsrc' file pointing to the regular or device file. Use the 'floppya:' and 'floppyb:' directives. If you are starting out, you will need to make a copy of an existing bootable floppy. Otherwise, you may create a blank image file, if you intend on formatting it using the OS you boot within Bochs.

Size | Cylinders | Heads | Sectors/Track | Sectors Total
--- | --- | --- | --- | ---
0.720MB | 80 | 2 | 9 | 1440
1.2MB | 80 | 2 | 15 | 2400
1.44MB | 80 | 2 | 18 | 2880
1.680MB | 80 | 2 | 21 | 3360

To create a blank floppy image file, you can use the same concept as above for creating blank hard disk image files. For example, to create a blank 1.44MB floppy image file:

        unix-> dd if=/dev/zero of=1.44M bs=512 count=2880

To create a copy of an existing floppy disk, granted you have a floppy disk drive on your workstation, you can use one of the following commands, where '/dev/fd0' would be the path to your floppy drive device name.

NOTE: If your system uses a form of volume management to automount your floppy drive, you may have to tell it you popped in a new floppy, and use an alternative device name to access it.

        # Linux, direct use of floppy drive using 'dd'
        unix-> dd if=/dev/fd0 ibs=512 of=1.44M

            --or--

        # Linux, direct use of floppy drive using 'cp'
        unix-> cp /dev/fd0 1.44M

            --or--

        # With Volume Management handling floppy drive
        Solaris 2.x-> volcheck
        Solaris 2.x-> dd if=/vol/dev/aliases/floppy0 ibs=512 of=1.44M

## Bochsrc file options

There are many options which you can change, to alter the behaviour of bochs, enable features, etc. You can set values for these options in a file called ".bochsrc". There should be a reference file with this name, that comes with the source code distribution. As, it's easier to maintain documenting possible commands in the file itself, look in the reference file for more info.

Search Order:

- bochs first tries to find this file in your current directory
- bochs then tries to find this file in your home directory
- bochs then gives up and doesn't use one.

Note: These options are overridden by any command line options you provide

## Bochs command line options

You may now pass all options available in the ".bochsrc" file, to bochs on the command line. Syntax for command line options is now identical to directives in ".bocshrc". Old command line options, such as -bootC are no longer valid. Bochs expects that each option is passed as a single argument, so if you need to use spaces, surround the option in quotes. For example:

      bochs boot:c
      bochs "boot: c"  "diskc: file=../10M.vga, cyl=306, heads=4, spt=17"
      bochs romimage:/tmp/someimage

Note: Look in the reference ".bochsrc" for syntax

## Installing an OS (DOS/Win'95/Minix/Linux) within Bochs

The goal of Bochs is to emulate the components of a basic PC (CPU, BIOS, disk drive, floppy, keyboard, VGA, and other chipsets) well enough to allow for multiple Operating Systems to run within the emulator. So far, Bochs has been successful in running several OS's at one time or the other. Follow the link of your choice to learn how to install the OS of your interest.

- DOS
- Windows 3.1
- Windows '95
- Minix
- Linux
- Deprecated Win95 install instructions
- WinNT 4.0

## X11 Keyboard Hacks

      NOTE: your backspace key may not work properly.  You may have to
            source the file 'misc/xmods' in the main distribution directory.
            I need to look at this problem a little more.
            Using Ctrl-h always seems to work for me.