Bochs is written in C++, so you need a C++ compiler on your system. Most platforms have been tested with GNU gcc/g++, but other compilers also work. By now, you should have unpacked your source TAR file or checked out Bochs from CVS. If not, you can return to Downloading Bochs for details. The top level directory of the source code will be referred to as $BOCHS. ($BOCHS contains the files bochs.h and main.cc and subdirectories cpu and bios.)
The standard compile process has three basic steps: configure, make, and make install. Each step is described in a separate section below. The standard compile process is used on all Unix machines, MacOS X, BeOS, and Win32 with Cygwin. There are separate instructions for compiling for Win32 with Microsoft VC++.
There is a script called configure which tests your machine, C/C++ compiler and libraries to discover what settings should work on your system. If you run configure with no arguments after it, defaults will be used for all settings. To change the settings, you can run configure with options that override the defaults. You can get a list of valid configure options by typing configure --help. All configure options are documented in a later section. One useful configure option is --prefix=directory, which sets the directory in which Bochs will be installed.
Among other things, the configure script tries to guess your compiler and a set of compile options that work. If you want to control this, set these environment variables before running configure: CC, CXX, CFLAGS, CXXFLAGS. Here is an example that sets the environment variables, using bash/ksh[1] syntax:
export CC=egcs export CXX="$CC" export CFLAGS="-Wall -O2 -m486 -fomit-frame-pointer -pipe" export CXXFLAGS="$CFLAGS"
Once the configure script knows what options are selected, it creates a Makefile in every source code directory, and creates $BOCHS/config.h with all the option values written as preprocessor #defines. The sources are ready to compile.
In the Bochs source directory, there is a series of scripts called .conf.platform. These scripts run configure script for you, with a set of options that appropriate for that platform. On some platforms, configure cannot guess all the right options, so it is necessary to use the shortcut scripts instead of a plain configure command. If a .conf.platform file exists for your platform, you should probably use it.
Tip: If a shortcut script is "almost right" for you, just edit it and then run it! If you use a shortcut script, you don't need to run configure manually.
sh .conf.win32-vcppThese .conf.platform have been tested in recent Bochs versions:
.conf.linux .conf.sparc .conf.macosx .conf.win32-vcpp .conf.win32-cygwin .conf.AIX.4.3.1 .conf.beos-x86-R4
The make command compiles Bochs. Make is a program used by many software projects that reads the Makefile in each source directory and follows the instructions that it finds there. A Makefile tells which files depend on which other files, what commands to use to compile and link the code, and more. After you have finished the configure step, just type make to build the source code.
The reason that make is so popular is that it is smart about when to compile and when not to compile. If you run make once, it compiles every file. But when you run it again, it checks to see if any source files have been modified; if not, there's nothing to do! For example, the Makefile says that main.o depends on main.cc. Knowing this, it will only compile main.cc if it is newer than main.o.
Of course, make can only do the right thing if the Makefile lists all the dependencies correctly, so human error can sometimes lead make astray. If make refuses to build something that you think it should, or you are getting strange compile errors, try doing make all-clean and then make again. All-clean means to clean up the compiled files in every subdirectory, while make clean means to clean up just the current directory[2]. However, it's important to note that make all-clean leaves the configuration intact. You do not have to run configure again.
If you're really in the mood for cleaning, make dist-clean erases all the configuration information too. In theory, after a dist-clean your directory should look much like when you first untarred it or checked it out. There's usually some extra stuff lying around, but the Makefile tries at least to erase any files that it created.
Once the program has been built, the next step is typically to run make install to copy the executables, documentation, and other required files into a public place so that all users can use it. [3]
user$ ls -l bochs-1.2.1.tar.gz -rw-rw-r-- 1 user user 887993 Sep 15 23:24 bochs-1.2.1.tar.gz user$ gunzip -c bochs-1.2.1.tar.gz | tar -xvf - bochs-1.2.1/ bochs-1.2.1/bios/ bochs-1.2.1/bios/BIOS-bochs-2-processors bochs-1.2.1/bios/Makefile.in . . . bochs-1.2.1/patches/NOTES bochs-1.2.1/patches/patch.4meg-pages bochs-1.2.1/patches/patch.goswin-changes user$ cd bochs-1.2.1 user$ ./configure --enable-cdrom creating cache ./config.cache checking for gcc... gcc checking whether the C compiler (gcc ) works... yes checking whether the C compiler (gcc ) is a cross-compiler... no checking whether we are using GNU C... yes checking whether gcc accepts -g... yes . . . creating misc/Makefile creating dynamic/Makefile creating fpu/Makefile creating config.h user$ make cd iodev && \ make CC="gcc" CXX="c++" CFLAGS="-g -O2 " CXXFLAGS="-g -O2 " LDFLAGS="" LIBS="" X_LIBS="-L/usr/X11R6/lib" X_PRE_LIBS="-lSM -lICE" prefix="/usr/local" exec_prefix="/usr/local" bindir="/usr/local/bin" infodir="" libiodev.a make[1]: Entering directory `/tmp/bochs-1.2.1/iodev' c++ -c -g -O2 -I.. -I../instrument/stubs devices.cc -o devices.o c++ -c -g -O2 -I.. -I../instrument/stubs pic.cc -o pic.o c++ -c -g -O2 -I.. -I../instrument/stubs pit.cc -o pit.o c++ -c -g -O2 -I.. -I../instrument/stubs unmapped.cc -o unmapped.o c++ -c -g -O2 -I.. -I../instrument/stubs cmos.cc -o cmos.o . . . echo done done c++ -o bochs -g -O2 main.o load32bitOShack.o state_file.o pc_system.o osdep.o \ iodev/libiodev.a \ cpu/libcpu.a memory/libmemory.a gui/libgui.a \ fpu/libfpu.a \ -L/usr/X11R6/lib -lSM -lICE -lX11 gcc -c -g -O2 -I. -Iinstrument/stubs misc/bximage.c -o misc/bximage.o c++ -o bximage -g -O2 misc/bximage.o user$ su root# make install cd iodev && \ make CC="gcc" CXX="c++" CFLAGS="-g -O2 " CXXFLAGS="-g -O2 " LDFLAGS="" LIBS="" X_LIBS="-L/usr/X11R6/lib" X_PRE_LIBS="-lSM -lICE" prefix="/usr/local" exec_prefix="/usr/local" bindir="/usr/local/bin" infodir="" libiodev.a make[1]: Entering directory `/tmp/bochs-1.2.1/iodev' . . . /usr/local/bochs/1.2.1/install-x11-fonts Looking for fonts to install... font/ Looking for X11 Font Path... /usr/lib/X11/fonts Installing vga.pcf... ok (it was already there) Running mkfontdir... Done installing Bochs fonts for X11. root# exit user$ _
The standard compile uses the configure script, but the Windows platform cannot run the configure script natively. The currently solution to this problem is that the Bochs configure script can be run on a different platform that does support shell scripts, with options that cause it to configure for a Win32 platform instead of the native one. Many people have access to a UNIX machine that could run the configure script, or you can use Cygwin to run the configure script [4].
Download the Bochs sources on a machine that can run shell scripts. Edit the configure shortcut script .conf.win32-vcpp if you want to adjust configure options. Then type these commands in the Bochs source directory:
sh .conf.win32-vcpp make win32_snapThese commands will run the configure step, produce VC++ makefiles and workspace files, and pack it all into a .zip file in the directory above the source directory [5]. The .zip file is all ready to transfer to the target Windows machine to be unzipped and compiled. Or, if you run the sh/make steps in Cygwin, you are already on the target machine so you don't need the .zip file.
When you have the Win32 sources transferred to a Windows machine with VC++, find the workspace file called bochs.dsw and load it in VC++. Choose Project:Set Active Project and be sure that "bochs" is selected. Then choose Build:Build bochs.exe. This will build all the required libraries (iodev, cpu, etc.) and the auxilliary programs bximage.exe and niclist.exe. The workspace compile method is new in version 1.3, so it has not had very long to be tested and tuned. Using workspaces is easy and intuitive, but there is one caveat. The workspaces are not currently integrated with configure. Some configure options such as --enable-debugger need to add additional source files to the Makefile to be compiled, but they do not alter the workspace file. If you add configure options and start having compile problems, try the nmake method (below) instead. These problems should be fixed in future versions.
Tip: To compile with the debugger enabled, add "--enable-debugger" to the configure line in .conf.win32-vcpp before running it. Then when you have loaded the workspace file, you must add the debug and disasm libraries to the project dependency list. Choose Project:Dependencies and make sure that debug and disasm are checked.
An alternative way to compile is to run nmake.exe in an MS-DOS window. Instead of using the workspace files, nmake uses the Bochs makefiles that are generated by configure. The workspace file is new in version 1.3; before that, nmake was the only way to compile Bochs in VC++. If you are having trouble with the workspace, try the nmake compile instead.
The make install for Win32 is presently broken. In the future, a make install that runs in Cygwin may be provided.
Cygwin is a free Unix-like environment for Windows written by Steve Chamberlain and now maintained by RedHat, Inc. You can download it from www.cygwin.com. Because Cygwin supports the configure script and uses GNU gcc/g++, you can use the standard compile process. A few compiler options are needed, so it is best to use the configure shortcut script called .conf.win32-cygwin. Edit the shortcut script if you want to modify the configure options. Then, to compile in Cygwin, just type:
sh .conf.win32-cygwin makeThese options are known to work in cygwin, so they are enabled in the configure shortcut file:
--enable-cdrom --enable-sb16=win
Possibly hasn't been tried since 1999. In theory, you run sh .conf.macos on a unix box to build the makefiles and headers, copy the whole thing over to a Mac, and then use CodeWarrior to compile. Since it hasn't been tested in so long, it is quite likely that some work is needed to bring the Mac port up to date.
The port to MacOS X with Carbon API by Emmanuel Mailliard is quite new, and the configure and makefile support was added by Bryce Denney. You need to install the compiler and libraries from the development tools CD. It should configure and compile ok if you use the .conf.macosx configure shortcut script. MacOS X has a special format for an application bundle, which looks like a directory that contains the required resource files and binaries. The Makefile currently creates this application bundle "by hand" using mkdir and copy, which is surely the wrong way to do it. Bryce doesn't know the official way to create an application from a Makefile, so this hack will remain until a real Mac developer helps to clean it up.
sh .conf.macosx make
Note: If you have X windows installed, you should also be able to build Bochs with X windows GUI. To try it, just run configure instead of the .conf.macosx shortcut script.
Kevin Lawton ported Bochs to BeOS. Bernd Korz has taken over the port, and is working on raw cdrom and raw floppy support. It should compile if you configure with --with-beos or use the .conf.beos-x86-R4 script.
Nicholai Benalal created this port to MorphOS running on Amiga. It should compile with
./configure --with-amigaos; makeBryce also made an (untested) .conf.amigaos script that enables FPU and CDROM.
Linux is based on Unix, so it uses the standard compile. Several Linux distributions use the Redhat Package Manager (RPM) to make it easier to install and uninstall software. If you want to build an RPM of Bochs, here are the commands. Edit .conf.linux first if you want to adjust the configure options.
su root Password: type root password sh .conf.linux make rpmWhen this command completes, you will have a source RPM and a binary RPM of Bochs, probably under /usr/src/redhat/RPMS. The output of the make rpm will tell you the exact location of these new files. Instructions for installing an RPM are here.
This section describes the configure options for Bochs. Perhaps the most important option is --help, since it gives you a list of all the other options. The options in the first table choose which GUI library to use. The default is --with-x11 so if you don't include --with-* it will try to compile for X windows.
Table 3-3. Configure Options to select the GUI
Option | Default | Comments |
---|---|---|
--with-x11 | yes | Use X windows user interface. This is the default, so you never actually need to type it. |
--with-win32-vcpp | no | Use Win32 GUI/Visual C++ environment. This is for running configure on a platform which supports running configure, so that you may then transfer the configured code over to an MS Win32/Visual C++ environment. See the Section called Compiling on Win32 with Microsoft VC++ for details. |
--with-win32 | no | Use Win32 GUI, but compile with a Win32/gcc environment such as cygwin. For cygwin, see .conf.win32-cygwin for the correct compile options. |
--with-carbon | no | Compile for MacOS X with the Carbon GUI. See the .conf.macosx file for the correct MacOS X compile options. |
--with-amigaos | no | Compile for Amiga MorphOS. This code is written by Nicholai Benalal. |
--with-rfb | no | Use RFB protocol to talk to AT&T's VNC Viewer. The RFB code was written by Don Becker <x-odus@iname.com>, who has a Bochs-RFB web page on his site, http://www.psyon.org/bochs-rfb. RFB mode has been tested in Linux and Win32. |
--with-beos | no | Use BeOS GUI. The configure script will run natively on BeOS; use this option when doing so. |
--with-term | no | Use text-only gui with curses library. Almost certainly won't work right with the debugger or the control panel. |
--with-macos | no | Use Macintosh/CodeWarrior environment. This is for running configure on a platform which supports running configure, so that you may then transfer the configured code over to the real compile environment. (Hasn't been tested in a long time.) |
--with-nogui | no | No native GUI; just use blank stubs. This is if you don't care about having video output, but are just running tests. |
The remaining options can generally be used with any GUI. For each option such as --enable-cdrom, you can also write --disable-cdrom to explicitly turn it off.
Table 3-4. Frequently Used Configure Options
Option | Default | Comments |
---|---|---|
--enable-cpu-level={3,4,5,6} | 5 | Select which CPU level to emulate. Choices are 3,4,5,6 which mean to target 386, 486, Pentium, or Pentium Pro emulation. Pentium Pro support is quite incomplete, so level 5 is the best choice for now. |
--enable-cdrom | no | Enable use of a real CDROM. The cdrom emulation is always present, and emulates a drive without media by default. You can use this option to compile in support for accessing the media in your workstation's cdrom drive. The supported platforms are Linux, Solaris, OpenBSD, and Windows. For other platforms, a small amount of code specific to your platform must be written. The module iodev/cdrom.cc is the place to add more support. For the most part, you need to figure out the right set of ioctl() calls. |
--enable-sb16={dummy, win, linux} | no | Enable Sound Blaster emulation. SB16 output is only supported for
Windows or Linux. The dummy option means to support
an SB16, but don't use an output device. So for example, you might use
--enable-sb16=linux. Check out ![]() |
--enable-control-panel | yes | Enables text-mode configuration menus when you first start Bochs. The menus let you read in a bochsrc file, edit some options, and safe the new bochsrc before starting the simulation. Also enables a runtime menu (controlled by a Config button on the Bochs display) which lets you change certain settings during simulation. The control panel was added by Bryce Denney. |
--enable-new-pit | yes | Enables Greg Alexander's PIT model, written during Summer 2001. This model was written from scratch to be much more complete than the old Bochs PIT model, which was missing many registers and features. If you disable this option, the old PIT model will be used instead. |
--enable-slowdown | no | Enables Greg Alexander's experimental "slowdown timer" which tries to keep the Bochs simulation time in sync with real time. When Bochs is executing many instructions, the slowdown timer will have no effect. When Bochs is idle, or just waiting around for an interrupt, the slowdown timer kicks in to prevent Bochs time from speeding ahead. This should solve problems like, "Why does my screen saver turn on after 30 seconds?" |
--enable-idle-hack | no | Enables Roland Mainz's experimental idle code, which is intended to keep Bochs from always using 100% of CPU time. When Bochs is waiting around for an interrupt, the idle code uses a select() loop and some X11 tricks to wait until user input arrives. This is designed to keep Bochs responsive while still yielding to other processes when Bochs is idle. |
--enable-ne2000 | no | Enable NE2000 network card support. This requires a low-level component to be written for each OS. The NE2000 option is only supported on FreeBSD, OpenBSD, Linux, and Windows NT/2K[a]. When enabled and configured, the NE2000 device model can talk to any computer on the network EXCEPT FOR the local host. |
--enable-vga | yes | Use VGA emulation. VGA is the only supported option and since it's the default, you don't need to include this option. |
--enable-fpu | yes | If you want to compile bochs to make use of the FPU emulator written by Bill Metzenthen (the one used by the Linux kernel), use this option. |
--enable-split-hd | yes | When enabled, this allows a series of partial hard disk image files to be treated as if it was one large file. The .bochsrc specifies the first partial HD image (example win95-1) and then bochs searches for the other partial images in as a sequence (win95-2, win95-3, etc.) and opens them all. Then, it treats the series as if there was a single large file created by "cat win95-1 win95-2 win95-3". This trick works for both diskc and diskd. All files must be a multiple of 512 bytes. |
--enable-debugger | no | Compile in support for Bochs internal command-line debugger. This has
nothing to do with x86 hardware debug support. It is a more powerful
and non-intrusive native debugger. Enabling this will of course slow
down the emulation. You only need this option if you know you need it.
After you have run ./configure, you may want to edit 'config.h' to
customize the debugger further. Look at the section entitled 'OPTIONAL
DEBUGGER SECTION'. ![]() |
--enable-disasm | no | Compile in support for built-in disassembler. Bochs has a built-in disassembler, which is useful if you either run the built-in debugger (--enable-debugger), or want disassembly of the current instruction when there is a panic in bochs. You don't need this option. |
--enable-cpp | no | Use .cpp as C++ suffix. Renames all the .cc files to .cpp for use with compilers which want that, like MS C++ compilers. Don't use this option unless you know you need it. |
Notes: a. Windows support was very recently added by Don Becker, and will not work on Windows 95/98. |
Table 3-5. Less Used Configure Options
Option | Default | Comments |
---|---|---|
--enable-iodebug | no | Dave Poirier has written an experimental interface to the debugger
using I/O ports, so that software running in the guest OS can access
features of the debugger. You only want this option if you are
developing guest OS code for use in Bochs. In other words, most people
don't. Also, it should only be used with --enable-debugger. See section
![]() |
--enable-x86-debugger | no | X86 debugger support. If the software you run in bochs needs to use the x86 hardware debugging facilities such as DR0..DR8, instruction and data breakpoints etc., then you should use this option. Otherwise don't use it, as it will slow down the emulation. |
--enable-pci | no | Enable limited i440FX PCI support. This is not complete. Don't use this option. |
--enable-port-e9-hack | no | Writes to port e9 go to console. Unless you know you want this option, you don't. |
--enable-processors={1,2,3,...,15} | 1 | By changing to more than 1 processor, you enable SMP simulation. This
allows you to boot Linux and maybe other OSes in SMP mode, and bochs will
simulate all the different CPUs and communication between them. Do not
expect this option to speed up your simulation! On the contrary, it has
to spend extra time simulating the different CPUs (even if they're mostly
idle) and the communication between them. Use it to try out an SMP OS if
you don't have an SMP machine, or to debug SMP OS drivers. Click
here ![]() |
--enable-apic | no | In an SMP machine, there is an APIC (Advanced Programmable Interrupt Controller) built into each processor and a separate I/O APIC. The APICs are used for inter-processor communication, so they must be enabled for SMP to work. The default is "no" when there is one processor and "yes" when there is more than one processor. Normally, the default is correct and you would never need to type this option. |
--enable-loader | no | Support calling external loader from debugger. This is an unsupported option. Don't use it. |
--enable-instrumentation=directory | no | Compile in support for instrumentation. This allows you to collect instrumentation data from bochs as it executes code. You have to create your own instrumentation library and define the instrumentation macros (hooks in bochs) to either call your library functions or not, depending upon whether you want to collect each piece of data. [Kevin wrote: I broke some of the hooks when I recoded the fetch/decode loop.] |
--enable-simid={0, 1} | 0 | CPU simulator ID. You likely don't need this option. If you are using bochs to cosimulate, that is to run multiple simulators in parallel so that you can compare results and check for divergence, each simulator needs an ID. When you only have one CPU simulator (as usual) the default of 0 is fine. [Kevin wrote: I use this option occasionally to run 2 versions of bochs against each other and check for divergence, to find bugs etc. This option gets broken more than not due to architectural changes, and I usually end of fixing it each time I use it.] |
--enable-num-sim={1, 2} | 1 | Number of CPU simulators. The default of 1 is likely what you want, so don't use this option. It is for assigning an ID to the simulator, for cosimulation described above. |
--enable-time0=n | no | Start CMOS clock at at time0 of n instead of using time(). You likely don't want this option. When debugging, it is very helpful to have deterministic execution, and the clock is something that can skew determinism. If you supply this option, pass it a value returned by the time(NULL) call, relating to the time you want bochs to start the CMOS clock from. For instance, '--enable-time0=917385580'. If you use this option but don't provide a value, configure uses a default value. Note that the time0 option in .bochsrc will override this value. Without this option, the CMOS clock uses a time0 based on the value of time(NULL), which is probably what you want. |
--enable-hga-dumps=Nmicroseconds | no | Copy memory to HGA video buffer every N useconds. A deprecated option, don't use. |
what if configure fails? - tar up config.* and send to bochs-testing@tlw.com - report the problem with a source forge bug report. what if make fails? - try make dist-clean, and run configure and make again - use configure options to disable options. For example, if errors in fpu/fpu_system.h, you could try --disable-fpu. - search for the error on the Bochs website (bug reports, patches) - if familiar with C++, many minor problems can be corrected - move to more stable code. if it's CVS, see if a release version will compile. Report problem to bochs-developers. - report the problem with a source forge bug report.
[1] | The syntax for bash and ksh is given. In csh and variants, use the syntax setenv VARIABLE value to change environment variables. Do not use an equal sign for csh! |
[2] | This is different from the terminology of some other projects, and it may cause confusion. Sometimes "clean" implies that all subdirectories are affected. |
[3] |
|
[4] | Because Bochs depends so much on the configure script, if you are doing much win32 Bochs development, you should consider downloading cygwin so that you can run the configure step natively. |
[5] | If the source directory is /home/joe/bochs-win32, the resulting .zip file is in /home/joe/bochs-win32.zip. |