user.dbk

bochs

  Filesystem    1024-blocks   Used  Available Capacity Mounted on
  /dev/hda1        10060      2736      6005     29%   /
  dlx:/# _
</screen>

<para>
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.
</para>


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

<table><title>Files in RPM package</title>
<tgroup cols=2 align=left colsep=1 rowsep=1>
<thead> <row> <entry>File</entry> <entry>Description</entry> </row>
</thead>
<tbody>

<row><entry>/usr/share/doc/bochs/README</entry> <entry> the read-me file from the source distribution. </entry> </row>
<row><entry>/usr/share/doc/bochs/CHANGES</entry> <entry> what has changed between versions </entry> </row>
<row><entry>/usr/share/doc/bochs/COPYING</entry> <entry> copy of the LGPL license </entry> </row>
<row><entry>/usr/bin/bochs </entry> <entry> the main Bochs executable </entry> </row>
<row><entry>/usr/bin/bximage </entry> <entry> tool for making new disk images </entry> </row>
<row><entry>/usr/share/doc/bochs/bochsrc-sample.txt</entry> <entry> sample Bochs configuration file </entry> </row>
<row><entry>/usr/share/man/man1/* </entry> <entry> man pages for bochs, bochs-dlx and bximage </entry> </row>
<row><entry>/usr/share/man/man5/* </entry> <entry> man page for bochsrc </entry> </row>
<row><entry>/usr/share/doc/bochs/index.html</entry> <entry> a local copy of all Bochs documentation ( <ulink url="http://bochs.sourceforge.net/doc/docbook/index.html">Online copy</ulink> )</entry> </row>
<row><entry>/usr/share/bochs/BIOS-* </entry> <entry> ROM BIOS images for Bochs.  Normally you would only use BIOS-bochs-latest unless you are simulating multiple processors.  </entry> </row>
<row><entry>/usr/share/bochs/VGABIOS-elpin-* </entry> <entry> VGA BIOS image for Bochs </entry> </row>
<row><entry>/usr/share/bochs/VGABIOS-elpin-LICENSE </entry> <entry> license for VGA BIOS </entry> </row>
<row><entry>/usr/share/bochs/VGABIOS-lgpl-latest </entry> <entry> LGPL'd VGA BIOS image for Bochs </entry> </row>
<row><entry>/usr/share/bochs/VGABIOS-lgpl-README </entry> <entry> readme for the LGPL'd VGA BIOS </entry> </row>
<row><entry>/usr/bin/bochs-dlx </entry> <entry> run this script to try out DLX Linux inside Bochs!</entry> </row>
<row><entry>/usr/share/bochs/dlxlinux/ </entry> <entry> directory containing DLX linux sample disk image and configuration files</entry> </row>
<row><entry>/usr/share/bochs/dlxlinux/README</entry> <entry> description of DLX linux</entry> </row>
</tbody>
</tgroup>
</table>


</section> <!-- end of Installing a Binary:Linux section -->

</section> <!-- end of Installing a Binary -->

<section id="compiling"><title>Compiling Bochs</title>

  <section><title>Standard Compile</title>
<para>
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 from CVS.  If not, you can return to <link
linkend="downloading">Downloading Bochs</link> for details.  The top level
directory of the source code will be referred to as &bochsdir;.  (&bochsdir;
contains the files <filename>bochs.h</filename> and
<filename>main.cc</filename> and subdirectories <filename>cpu</filename> and
<filename>bios</filename>.) 
</para>

<para>
The standard compile process has three basic steps:
<command>configure</command>, <command>make</command>, and <command>make
install</command>.  Each step is described in a separate section below.  The
standard compile process is used on all Unix machines, MacOS X, BeOS, and 
Cygwin (win32).  There are separate instructions for <link
linkend="compiling-win32">compiling for Win32 with Microsoft VC++</link>.
</para>

<section id="configure"><title>Configure</title>

<para>
There is a script called <command>configure</command> which tests your
machine, C/C++ compiler and libraries to discover what settings should work on
your system.  If you run <command>configure</command> with no arguments after
it, defaults will be used for all settings.  To change the settings, you can
run <command>configure</command> with options that override the 
defaults.  You can get a list of valid configure options by typing
<command>configure --help</command>.  One useful configure option is
--prefix=<replaceable>directory</replaceable>, which sets the directory in
which Bochs will be installed.  All the possible configure options are
documented in a <link linkend="config-opts">later section</link>.  


</para>

<para>
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: <varname>CC</varname>,
<varname>CXX</varname>, <varname>CFLAGS</varname>,
<varname>CXXFLAGS</varname>.  Here is an example that sets the environment
variables, using bash/ksh<footnote>
<para>
The syntax for bash and ksh is given.  In csh and variants, use the syntax
<command>setenv <replaceable>VARIABLE</replaceable>
<replaceable>value</replaceable></command> to change environment variables.
Do not use an equal sign for csh!
</para>
</footnote>
syntax:
<screen>
  export CC=egcs
  export CXX="$CC"
  export CFLAGS="-Wall -O2 -m486 -fomit-frame-pointer -pipe"
  export CXXFLAGS="$CFLAGS"
</screen>
</para>

<para>
Once the configure script knows what options are selected,
it creates a Makefile in every source code directory, and creates 
<filename>$BOCHS/config.h</filename> with all the option values written
as preprocessor #defines.  Now the sources are ready to compile.
</para>

<section><title>Configure Shortcut Scripts</title>
<para>
In the Bochs source directory, you will see a series of scripts called
<filename>.conf.<replaceable>platform</replaceable></filename>.
These scripts run the <command>configure</command> 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.

<tip>
<para>
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.  
</para>
</tip>

Run a shortcut script using Bourne shell, like this:
<screen>
  sh .conf.win32-vcpp
</screen>

These <filename>.conf.<replaceable>platform</replaceable></filename> have 
been tested in recent Bochs versions:
<screen>
  .conf.linux
  .conf.sparc
  .conf.macos
  .conf.macosx
  .conf.win32-vcpp
  .conf.win32-cygwin
  .conf.AIX.4.3.1
  .conf.beos
</screen>
</para>

</section> <!-- end of Configure Shortcut Scripts -->

</section> <!-- end of Compiling:Unix:Configure -->


<section><title>Make</title>
<para>
The <command>make</command> 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
<command>make</command> to build the source code.  
</para> 

<para>
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
<filename>main.o</filename> depends on <filename>main.cc</filename>.  Knowing 
this, it will only compile <filename>main.cc</filename> if it is newer than
<filename>main.o</filename>.
</para>

<para>
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 <command>make all-clean</command>
and then <command>make</command> again.  All-clean means to clean up
the compiled files in every subdirectory, while <command>make clean</command>
means to clean up just the current directory<footnote>

<para>
This is different from the terminology of some other projects, and it may cause
confusion.  Sometimes "clean" implies that all subdirectories are affected.
</para>
</footnote>.  However, it's important to note that <command>make
all-clean</command> leaves the configuration intact.  You do not have
to run <command>configure</command> again.
</para>

<para>
If you're really in the mood for cleaning, <command>make dist-clean</command>
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.
</para>

</section>

<section><title>Make Install</title>
<para>
Once the program has been built, the next step is typically to run
<command>make install</command> to copy the executables, documentation, and
other required files into a public place so that all users can use it.
<footnote><para>
&FIXME; We should mention what gets installed, and where.
    /usr/local/bin/bochs (and bximage)
    /usr/local/share/bochs/*
    /usr/local/share/man/man1/bochs*.1 (and bximage.1)
    make install_dlx option
</para></footnote>
</para>
</section>

</section>  <!-- end of Compiling:Unix section -->

<section id="config-opts"><title>Configure Options</title>
<para>
This section describes the configure options for Bochs.  Perhaps the most
important option is <option>--help</option>, 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 <option>--with-*</option> 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
<option>--with-*</option> options at once to compile with multiple
display libraries, and then choose between them at runtime with the
display_library command 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.
</para>
<note>
<para>
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.
</para>
</note>


<table><title>Defaults by Platform</title>
<tgroup cols=3 align=left colsep=1 rowsep=1>
<thead>
  <row>
    <entry>Platform</entry>
    <entry>Default GUI</entry>
    <entry>Extra compile flags</entry>
  </row>
</thead>
<tbody>
  <row>
    <entry>win32 or Cygwin</entry>
    <entry>--with-win32</entry>
    <entry>If using nmake method, compile using cl /nologo /G6 /MT /W3 /GX /DNDEBUG /DWIN32 /D_WINDOWS /O2.  If using Visual C++ workspace, see the workspace file for compile settings.  See <link linkend="compiling-win32">Compiling on Win32 with Microsoft VC++</link> for instructions.
    </entry>
  </row>
  <row>
    <entry>MacOS X or Darwin</entry>
    <entry>--with-carbon</entry>
    <entry>-fpascal-strings -fno-common -arch ppc -Wno-four-char-constants -Wno-unknown-pragmas -Dmacintosh
    </entry>
  </row>
  <row>
    <entry>MacOS 9 or before</entry>
    <entry>--with-macos</entry>
    <entry>none
    </entry>
  </row>
  <row>
    <entry>BeOS</entry>
    <entry>--with-beos</entry>
    <entry>none
    </entry>
  </row>
  <row>
    <entry>AmigaOS</entry>
    <entry>--with-amigaos</entry>
    <entry>none
    </entry>
  </row>
  <row>
    <entry>any other platform</entry>
    <entry>--with-x11</entry>
    <entry>none
    </entry>
  </row>
</tbody>
</tgroup>
</table>

<table><title>Configure Options to Select the Display Library (optional)</title>
<tgroup cols=3>
  <thead>
    <row>
      <entry>Option</entry>
      <entry>Comments</entry>
   </row>
  </thead>
  <tbody>
    <row>
      <entry>--with-x11</entry>
      <entry>Use X windows user interface.  On many operating systems,
      Bochs will use X windows by default.
       </entry>
    </row>
    <row>
      <entry>--with-win32-vcpp</entry>
      <entry>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 
          <xref link