3.4. Compiling Bochs

3.4.1. Standard Compile

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 are known to work too. By now, you should have unpacked your source TAR file or checked out Bochs with GIT from GitHub. 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, and Cygwin (win32). There are separate instructions for compiling for Win32 with Microsoft VC++.

3.4.1.1. Configure

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. One useful configure option is --prefix=directory, which sets the directory in which Bochs will be installed. All the possible configure options are documented in a later section.

Among other things, the configure script tries to detect your platform and which compile options to use. 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. Now the sources are ready to compile.

3.4.1.1.1. Configure Shortcut Scripts

In the Bochs source directory, you will see a series of scripts called .conf.platform. These scripts run the configure script for you, with a set of options that are appropriate for that platform. It is not necessary to use the shortcut scripts; they are simply there to show you an example that the developers have used. Some of these scripts have been used to build official binary packages.

Tip: If a shortcut script is "almost right" for you, just edit it and then run it! If you run a shortcut script, you don't need to run configure manually.

Run a shortcut script using Bourne shell, like this:
  sh .conf.win32-vcpp
These .conf.platform scripts have been tested in recent Bochs versions:

Table 3-4. Shortcut scripts

NameBuild environment
.conf.linuxLinux (32/64 bit)
.conf.macosxMacOS X
.conf.win32-cygwinWindows with Cygwin or MinGW/MSYS
.conf.win32-vcppWindows with MSVC (32 bit)
.conf.win64-vcppWindows with MSVC (64 bit)
.conf.win64-cross-mingw32Cross compiling on Linux for Windows

3.4.1.2. Make

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.

3.4.1.3. Make Install

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. By default, the files are copied to some directories in /usr/local. The following tables show the directories and their contents.

Table 3-5. Installed files

binbinary executables (bochs, bximage)
lib/bochs/pluginsplugins (if present)
man/man1manpages for installed binaries
man/man5manpage for the config file (bochsrc)
share/bochsBIOS images, VGABIOS images, keymaps
share/doc/bochsHTML docs, license, readme, changes, bochsrc sample

3.4.1.4. Installing the DLX Linux demo

To download and install the DLX Linux demo distributed with Bochs binary release packages, use these two make commands:

  make unpack_dlx
  make install_dlx
The package will be downloaded from the Bochs website and installed at same location as the files of the Bochs base system.

3.4.2. Configure Options

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 configure script will detect your platform and choose the default GUI for your platform. If the default choice is not what you want, use the --with-* options to override the default. The options in the first table tell which GUI library is the default for each platform. Starting in version 2.0, you can use multiple --with-* options at once to compile with multiple display libraries, and then choose between them at runtime with the display_library option in the configuration file. Or, you can let the configure script detect which libraries are on your system and use them all, by configuring with --with-all-libs.

Note: The concept of platform detection and default GUIs was added in Bochs 1.4. In Bochs 1.3 and before, the X11 GUI was always the default.

Table 3-6. Defaults by Platform

PlatformDefault GUIExtra compile flags
win32, Cygwin or MinGW/MSYS--with-win32If using nmake method, compile using cl /nologo /MT /W3 /EHs-c- /DNDEBUG /DWIN32 /D_WINDOWS /D_CRT_SECURE_NO_WARNINGS. If using Visual C++ workspace, see the workspace file for compile settings. See Compiling on Win32 with Microsoft VC++ for instructions.
MacOS X or Darwin--with-carbon-fpascal-strings -fno-common -arch ppc -Wno-four-char-constants -Wno-unknown-pragmas -Dmacintosh
MacOS 9 or before--with-macosnone
AmigaOS--with-amigaosnone
any other platform--with-x11none

Table 3-7. Configure Options to Select the Display Library (optional)

OptionComments
--with-x11Use X windows user interface. On many operating systems, Bochs will use X windows by default.
--with-win32Use the native Win32 GUI. This is the default on win32 platforms.
--with-carbonCompile for MacOS X with the Carbon GUI. See the .conf.macosx file for the correct MacOS X compile options. WARNING: This Bochs feature is not maintained yet and may fail.
--with-amigaosCompile for Amiga MorphOS. This code is written by Nicholai Benalal.
--with-rfb Enable support for the RFB protocol to talk to AT&T's VNC Viewer. Refer to Section 3.4.9 for details.
--with-vncsrv Enable support for an extended RFB(VNC) GUI using the LibVNCServer library. Refer to Section 3.4.10 for details.
--with-sdlEnable support for the SDL 1.2.x GUI interface; see Section 3.4.11.
--with-sdl2Enable support for the SDL 2.x GUI interface; see Section 3.4.12.
--with-termUse text-only GUI with curses library. Almost certainly won't work right with the debugger or the textconfig interface.
--with-macosUse 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. WARNING: This Bochs feature is not maintained yet and may fail.
--with-wx Enable support for wxWidgets configuration and display interface; see Section 3.4.13.
--with-noguiNo native GUI; just use blank stubs. This is if you don't care about having video output, but are just running tests.
--with-all-libs Automatically detect which libraries are installed on your system and enable them. This option is still experimental; it might enable libraries that are not usable and cause the compile to fail. If you have trouble, just list the --with-* options for the specific display libraries that you want.

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. The following 3 tables show the general options (.e.g debugger and plugins support), the CPU-related stuff (e.g. cpu level, SMP, x86_64 support) and the devices options (e.g. PCI, USB, Cirrus graphics).

Table 3-8. Configure Options (General)

OptionDefaultComments
--enable-pluginsno Plugins are shared libraries that can be loaded on demand. Example: the serial device is implemented as a plugin. In Unix, the serial plugin is called libbx_serial.so. When Bochs reads its configuration file, if the serial device is enabled it loads libbx_serial.so. See the Features section for supported platforms.
--enable-debuggerno 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; see Chapter 8 for more information.
--enable-debugger-guiyes if debugger is on Enable support for the GUI frontend of the Bochs debugger. This feature is supported on Windows hosts and on hosts with GTK2/GTK3 installed.
--enable-readlinedetected by configure Compile the debugger with the GNU readline library, which gives command line editing and history.
--enable-gdb-stubno Enable support for the remote GDB stub. See Using Bochs and the remote GDB stub. NOTE: This feature cannot be used if the Bochs debugger is also enabled. WARNING: This Bochs feature is not maintained yet and may fail.
--enable-docbookdetected Build the docbook documentation in doc/docbook. The configure script will enable this option automatically if you have a program called docbook2html installed.
--enable-instrumentation=directoryno 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.
--enable-xpmyes Enables the check for the XPM library. This option is only valid if the x display library is enabled (--with-x11).
--enable-show-ipsyes Enables logging of measured IPS, see the ips parameter of the cpu option.
--enable-loggingyes By default, Bochs generates logfile output that can be configured with bochsrc options and at runtime. Use --disable-logging to turn off this feature completely.
--enable-assert-checksyes if debugger is on BX_ASSERT event causes a panic on assertion failure if enabled (logging feature must be enabled, too).
--enable-cppno Use .cpp as C++ suffix. Renames all the .cc files to .cpp for use with compilers which want that, like older MS C++ compilers. Don't use this option unless you know you need it.
--enable-idle-hackno 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. It only works with X11 or term GUI.

Table 3-9. Configure Options (CPU & Memory)

OptionDefaultComments
--enable-cpu-level={3,4,5,6}6 Select which CPU level to emulate. Choices are 3,4,5,6 which mean to target 386, 486, Pentium, or Pentium Pro and later emulation.
--enable-smpno Compile in support for 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. Refer to Section 9.9 for more details on SMP in Bochs.
--enable-fpuyesIf you want to compile Bochs to make use of the FPU emulator written by Stanislav Shwartsman, use this option.
--enable-3dnowno3DNow! instruction set support (incomplete)
--enable-x86-64no Add support for x86-64 instruction set, written by Peter Tattam and Stanislav Shwartsman.
--enable-vmxnoIntel Virtualization Extensions (VMX) support
--enable-svmnoAMD SVM (Secure Virtual Machine) extensions emulation support
--enable-avxnoAVX instructions support
--enable-x86-debuggernoX86 debugger support. If the software you run in Bochs needs to use the x86 hardware debugging facilities such as DR0..DR7, instruction and data breakpoints etc., then you should use this option. Otherwise don't use it, as it will slow down the emulation.
--enable-monitor-mwaitnoMONITOR/MWAIT instructions support (still experimental)
--enable-alignment-checkyes if cpu level >= 4support for alignment check in the CPU and #AC exception
--enable-configurable-msrsnosupport for user configurations of emulated MSR registers (see example in msrs.def)
--enable-long-phy-addressnosupport for guest physical address larger than 32 bit
--enable-a20-pinyessupport for the A20 pin
--enable-large-ramfileyessupport for guest memory larger than the host supports
--enable-repeat-speedupsnoenable support repeated I/O and memory copy speedups
--enable-fast-function-callsnoenable support for fast function calls (gcc on x86 only)
--enable-handlers-chainingnoenable support for handlers chaining optimization
--enable-all-optimizationsno Turn on the enables for all speed optimizations that the developers believe are safe to use: --enable-repeat-speedups, --enable-fast-function-calls, --enable-handlers-chaining.

Table 3-10. Configure Options (Devices)

OptionDefaultComments
--enable-cdromyes Enable use of a real CD-ROM/DVD drive. The CD-ROM emulation and the portable ISO image file support are always present. You can use this option to compile in support for accessing the media in your workstation's CD-ROM drive. The supported platforms are Linux, Solaris, FreeBSD, OpenBSD, MacOS X and Windows. For other platforms, a small amount of code specific to your platform must be written.
--enable-sb16no Enable Sound Blaster emulation. The available lowlevel sound interfaces are autodetected. See section Using Sound for supported platforms and more info. This option also enables the standard PC gameport which is a part of the SB16. If you don't want to use it, you might use --disable-gameport.
--enable-es1370no Enable ES1370 sound emulation. Just like the SB16 option, the available lowlevel sound interfaces are autodetected and the gameport is turned on.
--enable-gameportno Enables the standard PC gameport. This option is only necessary if you want to have a gameport, but no SB16 or ES1370 (see above). The connection to a real joystick is currently supported on Linux and win32 only.
--enable-ne2000noEnable NE2000 network card support. This requires a low-level component to be written for each OS (supported on FreeBSD, OpenBSD, Linux, and Windows 9x/NT/2K/XP). When enabled and configured, the NE2000 device model can talk to any computer on the network EXCEPT FOR the local host. Exception: Under most circumstances, Bochs can talk to the local host on Windows, and in the ethertap interface for Linux.
--enable-pnicnoEnable PCI pseudo NIC (network card) support.
--enable-e1000noEnable Intel(R) 82540EM Gigabit Ethernet adapter support.
--enable-clgd54xxnoEnable Cirrus Logic GD54xx (CL-GD5430 ISA or CL-GD5446 PCI) video card support. For more information see Section 9.19.
--enable-voodoonoEnable experimental 3dfx Voodoo Graphics emulation. The Voodoo1 is known to work, the Voodoo2 support is not yet complete, but almost usable. The Banshee / Voodoo3 support is under construction, but basically usable. For more information see Section 9.20.
--enable-iodebugyes if debugger is on 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 the developer documentation for details.
--enable-pciyesEnable limited i440FX / i430FX / i440BX PCI support. This is still incomplete, but usable.
--enable-pcidevno Enable PCI host device mapping support. This requires --enable-pci to be set as well as Linux 2.4, 2.6 or 3.x as host. WARNING: This Bochs feature is not maintained yet and may fail.
--enable-usbno Enable i440FX / i440BX PCI USB support (UHCI). The host controller with 2-port root hub and 9 USB device types are available.
--enable-usb-ohcino Enable USB OHCI support. The host controller with 2-port root hub is available (USB device types: same as UHCI).
--enable-usb-ehcino Enable USB EHCI support. The host controller with 6-port root hub is available (USB device types: same as UHCI).
--enable-usb-xhcino Enable USB xHCI support. The host controller with 4-port root hub is available (USB device types: same as UHCI).
--enable-raw-serialno Enable support for the serial port emulation to access to the host's serial port. This feature is partly implemented for Windows hosts only.

3.4.3. Transcript of Successful Compilation

This example shows the output of a compilation and installation on Linux.

  user$ ls -l bochs-2.5.tar.gz
  -rw-r--r-- 1 user   users 4117999 27. Nov 17:14 bochs-2.5.tar.gz
  user$ gunzip -c bochs-2.5.tar.gz | tar -xvf -
  bochs-2.5/
  bochs-2.5/.conf.sparc
  bochs-2.5/build/
  bochs-2.5/build/macosx/
  bochs-2.5/build/macosx/pbdevelopment.plist
  bochs-2.5/build/macosx/make-dmg.sh
    .
    .
    .
  bochs-2.5/memory/memory.cc
  bochs-2.5/memory/misc_mem.cc
  bochs-2.5/memory/Makefile.in
  user$ cd bochs-2.5
  user$ ./configure --enable-cpu-level=6
  checking build system type... x86_64-unknown-linux-gnu
  checking host system type... x86_64-unknown-linux-gnu
  checking target system type... x86_64-unknown-linux-gnu
  checking if you are configuring for another platform... no
  checking for standard CFLAGS on this platform...
  checking for gcc... gcc
    .
    .
    .
  config.status: creating build/win32/nsis/bochs.nsi
  config.status: creating host/linux/pcidev/Makefile
  config.status: creating config.h
  config.status: creating ltdlconf.h
  user$ make
  cd iodev && \
          make  libiodev.a
  make[1]: Entering directory `/home/volker/Archiv/test/bochs-2.5/iodev'
  g++ -c  -I.. -I./.. -I../instrument/stubs -I./../instrument/stubs -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES    devices.cc -o devices.o
  g++ -c  -I.. -I./.. -I../instrument/stubs -I./../instrument/stubs -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES    virt_timer.cc -o virt_timer.o
  g++ -c  -I.. -I./.. -I../instrument/stubs -I./../instrument/stubs -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES    slowdown_timer.cc -o slowdown_timer.o
  g++ -c  -I.. -I./.. -I../instrument/stubs -I./../instrument/stubs -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES    pic.cc -o pic.o
    .
    .
    .
  echo done
  done
  /bin/sh ./libtool --mode=link g++ -o bochs -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES      -DBX_SHARE_PATH='"/usr/local/share/bochs"'  -export-dynamic logio.o main.o config.o load32bitOShack.o pc_system.o osdep.o plugin.o crc.o   \
                  iodev/libiodev.a  cpu/libcpu.a cpu/cpudb/libcpudb.a \
                  memory/libmemory.a gui/libgui.a \
                  disasm/libdisasm.a   \
                  fpu/libfpu.a \
                  -lSM -lICE -lX11 -lXpm -lXrandr   \
                  \
                  \
                  \
                  \
                  -lm
  mkdir .libs
  g++ -o bochs -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES -DBX_SHARE_PATH=\"/usr/local/share/bochs\" logio.o main.o config.o load32bitOShack.o pc_system.o osdep.o plugin.o crc.o -Wl,--export-dynamic  iodev/libiodev.a cpu/libcpu.a cpu/cpudb/libcpudb.a memory/libmemory.a gui/libgui.a disasm/libdisasm.a fpu/libfpu.a -lSM -lICE -lX11 -lXpm -lXrandr -lm
  gcc -c -I. -I./. -Iinstrument/stubs -I./instrument/stubs -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES   ./misc/bximage.c -o misc/bximage.o
  /bin/sh ./libtool --mode=link g++ -o bximage -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES     misc/bximage.o
  g++ -o bximage -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES misc/bximage.o
  gcc -c -I. -I./. -Iinstrument/stubs -I./instrument/stubs -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES   ./misc/bxcommit.c -o misc/bxcommit.o
  /bin/sh ./libtool --mode=link g++ -o bxcommit -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES    misc/bxcommit.o
  g++ -o bxcommit -g -O2 -D_FILE_OFFSET_BITS=64 -D_LARGE_FILES misc/bxcommit.o
  user$ su
  root# make install
  cd iodev && \
          make  libiodev.a
  make[1]: Entering directory `/home/volker/Archiv/test/bochs-2.5/iodev'
    .
    .
    .
  for i in CHANGES COPYING README TODO; do if test -f $i; then install -m 644 $i /usr/local/share/doc/bochs; else install -m 644 ./$i /usr/local/share/doc/bochs; fi; done
  rm -f /usr/local/share/doc/bochs/README
  cat ./build/linux/README.linux-binary ./README > /usr/local/share/doc/bochs/README
  install -m 644 ./.bochsrc /usr/local/share/doc/bochs/bochsrc-sample.txt
  root# exit
  user$ _

3.4.4. Compiling on Win32 with Microsoft VC++

The standard compile uses the configure script, but the Windows platform cannot run the configure script natively. The current solution to this problem is that the Bochs configure script must 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 or MinGW/MSYS to run the configure script. [3].

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 the configure options. Then type these commands in the Bochs source directory:

  sh .conf.win32-vcpp
  make win32_snap
These 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 [4]. 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.sln in the folder "vs2013" 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 auxiliary programs bximage.exe, bxhub.exe and niclist.exe.

Using workspaces is easy and intuitive, but there is one caveat. The workspaces come directly out of a ZIP file in build/win32/vs2013ex-workspace.zip, and they are not controlled by the configure script. When you compile with certain configure options (e.g. --with-sdl) you need to link with additional libraries. For now you must add them to the VC++ workspace by hand. In version 2.0, we have improved the situation considerably by adding #if...#endif around every optional file and including nearly every Bochs source file in the workspace. This solves the problem of having to manually add source files to the workspace when you turn on configure options such as --enable-debugger. The problem of adding link libraries remains unresolved.

Tip: To compile with the Bochs debugger enabled, add --enable-debugger to the configure line in .conf.win32-vcpp before running it. No modifications to the workspace are necessary.

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 nmake method is currently used to build the release binaries.

The make install doesn't work with nmake yet. Currently it must be run inside of Cygwin or MinGW/MSYS and requires the environment variable INSTDIR to be set.

3.4.5. Compiling on Win32 with Cygwin or MinGW/MSYS

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. The configure script should automatically detect Cygwin and add "-mno-cygwin -DWIN32" to the compiler options. You should get a working Bochs if you just type:

  configure
  make
Optionally, you can use the configure shortcut script for Cygwin, .conf.win32-cygwin, instead of running configure directly. If this script is close to what you need, just edit the script and then run it. To use the configure shortcut script and compile in Cygwin, the commands are
  sh .conf.win32-cygwin
  make
To find out the options which are known to work in Cygwin, open the file .conf.win32-cygwin in any text editor/viewer and have a look at the end of that file.

When using gcc 4.7 or newer you need to add the switch -mno-ms-bitfields to the CFLAGS, to make sure that hdimage and network structures are packed as expected.

The command make install installs the Bochs files in the directory structure of your build environment. To install Bochs into any desired folder you need to use the install_win32 target. It requires the environment variable INSTDIR to be set.

3.4.6. Compiling on MacOS 9 with CodeWarrior

It is possible that this 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.

If you are interested and have the required MacOS development tools, please let us know by contacting the bochs-developers mailing list. Someone requests a MacOS port almost once a month, but none of the developers know how to help them.

3.4.7. Compiling on MacOS X

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 will need the compiler and libraries from the development tools CD. Bochs should configure and compile with the Carbon GUI if you simply type:

  configure
  make
Optionally, you can use the configure shortcut script for MacOS X, .conf.macosx, instead of running configure directly. If this script is close to what you need, just edit the script and then run it. To use the configure shortcut script and compile, the commands are
  sh .conf.macosx
  make
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.

On MacOS X the default GUI is the Carbon interface, but you can also try other Bochs GUIs. Use --with-x11 for X windows, --with-rfb for VNC/RFB, --with-sdl for SDL or --with-sdl2 for SDL2.

3.4.8. Compiling on Amiga/MorphOS

Nicholai Benalal created this port to MorphOS running on Amiga. It should compile with:

  configure
  make
If the platform is not detected properly, you might need to use --enable-amigaos as a configure option. Optionally, you can use the configure shortcut script, .conf.amigaos.

3.4.9. Compiling with the RFB interface

The RFB code was written by Don Becker , who has a Bochs-RFB web page on his site, http://www.psyon.org/bochs-rfb/.

This interface allows you to view the Bochs display with AT&T's VNC Viewer. The protocol used between a VNC server and a VNC viewer is called RFB. Because the RFB code in Bochs is written with portable network socket and POSIX thread code, it can be compiled on many platforms and has been tested in Linux and Win32. No additional libraries are required. To try it, type:

  configure --with-rfb
  make
RFB currently uses this setup:

With the display library option "timeout" the default value of 30 seconds can be changed. With a value of 0 it is possible to start the simulation without a client connected.

3.4.10. Compiling with the VNCSRV interface

The LibVNCServer is a cross-platform library that allows to implement VNC server functionality easily. On platforms supported by LibVNCServer Bochs can be compiled with support for it this way:

  configure --with-vncsrv
  make

Unlike the RFB GUI this new implementation is not limited to 8 bpp and it is possible to connect a Bochs session with a web browser.

3.4.11. Compiling with the SDL interface

Dave Poirier has written an SDL interface for Bochs. Simple DirectMedia Layer, or SDL, is a cross-platform multimedia library distributed from libsdl.org. SDL is available for many platforms including Win32, Linux, BSD, IRIX, MacOS, MacOS X, and AmigaOS.

To compile Bochs with SDL, you must first install the SDL library from libsdl.org. You can either get the source code and compile it yourself, or install the development libraries for your platform (already compiled). Then, go into the Bochs directory and type:

  configure --with-sdl
  make

If you are on FreeBSD and have SDL installed using the ports collection, Bochs won't be able to find the library automatically, as the SDL config script is called sdl11-config in that case (even for version 1.2). The easiest way to make Bochs find it, is to create a symlink to that script called sdl-config inside a directory which is in the path. For example:

  ln -s /usr/local/bin/sdl11-config ~/bin/sdl-config

To compile in Microsoft VS2013Ex, you have to configure on a different system (see Compiling on Win32 with Microsoft VC++). Before running the configure script, you have to add --with-sdl to the shortcut script. If you have already configured, you can set BX_WITH_SDL to 1 in config.h.

Then you have to set up the project for SDL this way:

- add source file sdl.cc to the module gui
- add path to the SDL include files to the modules bochs and gui
- add lbraries SDL.lib and SDLmain.lib to the module bochs
- change the runtime library for all modules to Multithreaded-DLL (/MD)
Compiling with MSVC nmake is not supported yet.

3.4.12. Compiling with the SDL version 2 interface

The SDL library version 2 is now also supported by Bochs. For some basic information about SDL, see Section 3.4.11. The configure option to enable SDL2 support is --with-sdl2 and the configuration script is called sdl2-config. Note that the Bochs GUIs for SDL version 1.2.x and 2.x are mutually exclusive. The legacy SDL GUI support will be removed someday. When using the GUI library autodetection (--with-all-libs) the configure script probes for SDL version 2 first.

3.4.13. Compiling with the wxWidgets interface

wxWidgets is a cross-platform C++ user interface library which you can download for free at wxwidgets.org. The wxWidgets port of Bochs provides both a graphical configuration interface for editing bochsrc options (see config_interface option) and a display (see display_library option). It was written by Bryce Denney, Don Becker, Dave Poirier, and Volker Ruppert.

  configure --with-wx
  make

If you want Bochs to use a wxWidgets installation not in your path (but installed somewhere else), you need to set the WX_CONFIG environment variable to the proper wx-config script, before running configure (example for csh):

  setenv WX_CONFIG '/home/compile/wx/bin/wx-config'

3.4.14. Building an RPM on Linux

RPM stands for "RedHat Package Manager." An RPM is a compressed file containing files to be installed on your system. Bochs has a special shell script called make-rpm that helps to build an RPM of Bochs. Start with a clean source directory. Edit .conf.linux first if you want to adjust the configure options. Then, type:

  ./build/redhat/make-rpm | tee /tmp/build.txt
When this command completes, you should have a source RPM and a binary RPM of Bochs in the current directory. The tee part of the command (optional) saves a transcript of the build process into /tmp/build.txt, which is very useful if anything goes wrong. Instructions for installing an RPM are here.

Note: In the past, you had to build rpms as root, but as of version 2.0 you can build them as a normal user.

3.4.15. Compile Problems

3.4.15.1. The configure script failed

The configure script can fail for various reasons. If the error message on the shell doesn't give enough information, it is recommended to review the output file config.log to find out what exactly happened. The following issues can be fixed by modifying the configure options used:

  • deprecated option (option from previous Bochs version not needed / supported anymore)

  • mutually exclusive option (e.g. --enable-debugger and --enable-gdb-stub)

  • dependent option (e.g. USB support requires PCI support)

  • incomplete option (e.g. --enable-cpu-level requires an argument)

  • development package for library not installed (e.g. for --with-wx)

If the configure issue cannot be fixed by option changes and / or installing development packages / tools it should be reported in the bochs-developers mailing list or the SF bug tracker for the Bochs project.

3.4.15.2. Make / compilation failure

The make utility itself can only fail if the specified target is not supported by the environment or simply doesn't exist. In most cases the programs called from make are causing the failure (e.g. compiler / linker).

In some cases it might be useful to rebuild Bochs completely by calling make dist-clean and running the configure script once again. These steps are recommended if the development sources from GitHub are used and one of the build system files (e.g. Makefile or config.h.in) has been changed.

Sometimes it is possible to isolate the failing piece of code by disabling one or more configure options. For example, if the compilation fails somewhere in the cpu/avx* files, it might help to configure without --enable-avx. The same could be done with other Bochs facilities controlled by configure options.

3.4.15.3. Runtime issues with self-compiled Bochs

After a successful compilation the self-compiled Bochs can fail if at least one library is not installed properly. This can happen if the library consists of a development and a runtime package and the second one is missing. Another problem can appear on build environments like Cygwin and MinGW/MSYS. Applications built there are usually designed to be run inside of the environment. When starting them from the Windows shell, it may cause errors like "missing cygwin1.dll" or similar. In that case, the missing DLL must be copied from e.g. the Cygwin folder to the location of the compiled EXE file.

Notes

[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]

Because Bochs depends so much on the configure script, if you are doing much win32 Bochs development, you should consider downloading Cygwin or MinGW/MSYS so that you can run the configure step natively.

[4]

If the source directory is /home/joe/bochs-win32, the resulting .zip file is in /home/joe/bochs-win32-msvc-src.zip.