mirrors/Bochs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Updated most of the user doc after transition to GIT / GitHub.

Browse Source
This commit is contained in:
Volker Ruppert 2024-03-25 17:53:04 +01:00
parent e9c66051bd
commit 9daf6e9f50
1 changed files with 118 additions and 205 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

323
bochs/doc/docbook/user/user.dbk
View File

@ -895,13 +895,11 @@ code that displays the Bochs VGA screen and handles keyboard and mouse events.
<para>
The change log is stored in the Bochs source code in a file called
CHANGES. Click <ulink url="http://svn.code.sf.net/p/bochs/code/trunk/bochs/CHANGES">here</ulink>
CHANGES. Click <ulink url="https://github.com/bochs-emu/Bochs/blob/master/bochs/CHANGES">here</ulink>
to see the latest version of the CHANGES file.
</para>
<para>
The link above is provided by Source Forge and might change one day. If it
stops working, you can download the current source code with SVN and read
the CHANGES file there.
You can also download the current source code from GitHub and read the CHANGES file there.
</para>
</chapter>
@ -919,8 +917,8 @@ You can download Bochs from our web site at &bochs-sf-net;. First, you
need to choose what version to get: a recent release or a development
version. If you trying to get things working for the first time, a release
version is recommended since it has been tested the most. The development
versions (sometimes called SVN snapshots) may have some newer bug fixes and
new features, but have not been tested as much as the releases.
versions may have some newer bug fixes and new features, but have not been
tested as much as the releases.
</para>
<para>
@ -939,8 +937,8 @@ linkend="install-binary">Installing a Binary</link> for more information.
If you are going to compile Bochs yourself, you need the gzipped tarball
containing the source code, called
<filename>bochs-<replaceable>version</replaceable>.tar.gz</filename>. For
Windows and Mac, the prebuilt Makefiles are separate, so also get
the Makefiles for your platform. To unpack a compressed TAR file<footnote>
Windows a ZIP package with sources and prebuilt Makefiles is available.
To unpack a compressed TAR file<footnote>
<para>
A TAR file is a single file that contains many files packed inside. Bochs
TAR files are compressed with a program called gzip, and another program
@ -963,74 +961,60 @@ Bochs are in the section, <link linkend="compiling">Compiling Bochs</link>.
</para>
<para>
Alternatively, you can also obtain the sources for any Bochs version using SVN.
See the <link linkend="get-src-svn">SVN instructions</link> for details.
Alternatively, you can also obtain the sources for any Bochs version using GIT.
See the <link linkend="get-src-git">GIT instructions</link> for details.
</para>
</section> <!-- End of Installation:Downloading Bochs section -->
<section id="get-src-svn"><title>Tracking the source code with SVN</title>
<section id="get-src-git"><title>Tracking the source code with GIT</title>
<para>
&FIXME; These sections need updates because of the transition to GitHub
GIT is a free and open source version control system designed to handle small
to very large project efficiently. Git is used to tracking changes in the source
code, enabling multiple developers to work together on non-linear development.
The Bochs source code and documentation is available using GIT<footnote>
<para>
You can download GIT software and documentation from
<ulink url="https://git-scm.com/">git-scm.com</ulink>.
</para>
<para>
SVN (Subversion) is a tool used by many software developers to manage changes
within their source code tree. SVN provides the means to store not only the
current version of a piece of source code, but a record of all changes (and who
made those changes) that have occurred to that source code. Use of SVN is
particularly common on projects with multiple developers, since SVN ensures
changes made by one developer are not accidentally removed when another
developer posts their changes to the source tree. The Bochs source code and
documentation is available using SVN<footnote>
<para>
You can download SVN software and documentation from
<ulink url="http://subversion.apache.org">subversion.apache.org</ulink>.
</para>
</footnote>.
</footnote> on <ulink url="https://github.com/bochs-emu/Bochs/">GitHub</ulink>.
</para>
<section><title>Checking out Bochs</title>
<para>
When you have SVN installed, the first step is to do a checkout. The initial
checkout command is long and ugly, but usually you only have to do it
once. The example below shows the SVN checkout process of the Bochs trunk in Unix.
On the Windows platform, you can download a SVN client from
<ulink url="http://subversion.apache.org/packages.html#windows">subversion.apache.org</ulink>,
or use SVN within Cygwin<footnote>
When you have a GIT client installed, the first step is to do a checkout.
The initial checkout command is long and ugly, but usually you only have to do it
once. The example below shows the GIT checkout process of the Bochs master branch in Unix.
On the Windows platform, you can download a GIT client from
<ulink url="https://git-scm.com/download/win">git-scm.com</ulink>,
or use GIT within Cygwin<footnote>
<para>
Cygwin is an open source Unix-like environment for Windows platforms,
available at <ulink url="http://www.cygwin.com">www.cygwin.com</ulink>.
available at <ulink url="https://www.cygwin.com">www.cygwin.com</ulink>.
</para>
</footnote>.
<figure><title>Checking out Bochs in SVN</title>
<figure><title>Checking out Bochs in GIT</title>
<screen>
user$ <command>svn co http://svn.code.sf.net/p/bochs/code/trunk/bochs bochs</command>
A bochs/ltdl.c
A bochs/Makefile.in
A bochs/bochs.h
.
. <lineannotation>(This might take a few minutes, depending on your network connection.)</lineannotation>
.
A bochs/install.sh
U bochs
Checkout, Revision 10754.
user$ <command>cd bochs</command>
user$ <command>git clone https://github.com/bochs-emu/Bochs.git</command>
Cloning into 'Bochs'...
remote: Enumerating objects: 107946, done.
remote: Counting objects: 100% (2708/2708), done.
remote: Compressing objects: 100% (869/869), done.
remote: Total 107946 (delta 2095), reused 2118 (delta 1817), pack-reused 105238
Receiving objects: 100% (107946/107946), 39.53 MiB | 2.86 MiB/s, done.
Resolving deltas: 100% (85554/85554), done.
<lineannotation>(This might take a few minutes, depending on your network connection.)</lineannotation>
user$ <command>cd Bochs/bochs</command>
user$ <command>ls</command>
aclocal.m4 cpu logio.cc pc_system.cc
bios cpudb.h ltdl.c pc_system.h
bochs.h crc.cc ltdlconf.h.in plugin.cc
build disasm ltdl.h plugin.h
bx_debug doc ltmain.sh README
bxversion.h.in docs-html main.cc README-plugins
bxversion.rc.in extplugin.h Makefile.in README.rfb
CHANGES fpu memory README-wxWindows
config.cc gdbstub.cc misc TESTFORM.txt
config.guess gui msrs.def TODO
config.h.in host osdep.cc win32_enh_dbg.rc
config.sub install-sh osdep.h win32res.rc
configure instrument param_names.h wxbochs.rc
configure.in iodev PARAM_TREE.txt
COPYING load32bitOShack.cc patches
CHANGES aclocal.m4 bxversion.rc.in crc.cc iodev osdep.h win32res.rc
COPYING bios config.cc doc logio.cc param_names.h win32usbres.rc
LICENSE bochs.h config.guess docs-html logio.h patches wxbochs.rc
Makefile.in build config.h.in extplugin.h ltmain.sh pc_system.cc
PARAM_TREE.txt bx_debug config.sub gdbstub.cc main.cc pc_system.h
README bxdisasm.cc configure gui memory plugin.cc
README-wxWidgets bxthread.cc configure.ac host misc plugin.h
TESTFORM.txt bxthread.h cpu install-sh msrs.def qemu-queue.h
TODO bxversion.h.in cpudb.h instrument osdep.cc win32_enh_dbg.rc
user$ _
</screen>
</figure>
@ -1044,114 +1028,47 @@ available at <ulink url="http://www.cygwin.com">www.cygwin.com</ulink>.
<tip>
<para>
If you have write access to the Bochs SVN tree, see the Developers Guide
<footnote>
<para>
See the <ulink url="../development/resources.html">Developers Guide</ulink>
and/or look at
<ulink url="http://sourceforge.net/apps/trac/sourceforge/wiki/Subversion#Access">SourceForge's Subversion documentation</ulink>,
If you have write access to the Bochs GIT tree, see the
<ulink url="../development/resources.html">Developers Guide</ulink>
for instructions.
</para>
</footnote> for details.
</para>
</tip>
<para>
The SVN checkout process (above) gives you a directory called <filename>bochs</filename>
The GIT checkout process (above) gives you a directory called <filename>Bochs</filename>
that contains the very latest source code. I will refer to this directory
as &bochsdir;. In this directory there's also a subdirectory called ".svn"
which tells the SVN software where the code was checked out, what version
as &bochsdir;. In this directory there's also a subdirectory called ".git"
which tells the GIT software where the code was checked out, what version
you have, and where to go for future updates.
</para>
</section>
<section><title>Getting the Latest Version</title>
<para>
Most developers use SVN to always give them the latest source code. The minute
Most developers use GIT to always give them the latest source code. The minute
that any developer checks in a change, they are available to everyone else
through SVN. You just have to type <command>svn update</command> in the
&bochsdir; directory, and SVN will retrieve any files and directories that have
through GIT. You just have to type <command>git pull</command> in the
&bochsdir; directory, and GIT will retrieve any files and directories that have
been changed since you did a checkout. If you update regularly, each update
takes a short time because it downloads only the files that changed.
See also <link linkend="svn-release-version">Getting a release version</link>.
See also <link linkend="git-release-version">Getting a release version</link>.
</para>
<para>
The <command>svn update</command> command tells you if any new files have
The <command>git pull</command> command tells you if any new files have
been downloaded from the server, and it also tells you if you have modified any
of the SVN-controlled files. As it checks through the source directories, it
will list files that have changed, with a single letter before the name that
tells the status of that file. The most common status letters are listed
below.
<table frame="all">
<title>Status letters in a SVN update</title>
<tgroup cols="3">
<thead>
<row>
<entry>Letter</entry>
<entry>Meaning</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>?</entry>
<entry>unknown</entry>
<entry>
This file is in your Bochs directory, but SVN does not know anything
about it. For example, when you compile Bochs, any files created
during the build process appear as ?.
</entry>
</row>
<row>
<entry>U</entry>
<entry>update</entry>
<entry>
SVN downloaded a new version of this file because it changed on the
server, usually because someone else did a checkin.
</entry>
</row>
<row>
<entry>A</entry>
<entry>added</entry>
<entry>
SVN downloaded a newly added file from the server.
</entry>
</row>
<row>
<entry>D</entry>
<entry>deleted</entry>
<entry>
This file has been deleted on the server and SVN removed it from your
local copy.
</entry>
</row>
<row>
<entry>C</entry>
<entry>conflict</entry>
<entry>
You have changed this file on your disk, but this change conflicts with
a change that was checked in. Conflicts occur when two people change
the same line of code in different ways. You need to edit the
conflicting file(s) and clean it up by hand. Or, sometimes it's
easiest to discard your own edits and download a fresh copy, by
deleting the conflicting file and running svn update again.
</entry>
</row>
</tbody>
</tgroup>
</table>
of the GIT-controlled files. As it checks through the source directories, it
will list files that have changed.
</para>
</section>
<section id="svn-release-version"><title>Getting a Release Version</title>
<section id="git-release-version"><title>Getting a Release Version</title>
<para>
You can also use the SVN checkout command to get the Bochs source code for
You can also use the GIT checkout command to get the Bochs source code for
any release since March 2000. The command is
<screen>
user$ <command>svn co http://svn.code.sf.net/p/bochs/code/tags/<replaceable>tagname</replaceable>/bochs bochs</command>
user$ <command>git clone</command> --branch <replaceable>tagname</replaceable> https://github.com/bochs-emu/Bochs.git
</screen>
The <replaceable>tagname</replaceable> tells which release you want, and it can be one of the following:
@ -1161,210 +1078,215 @@ The <replaceable>tagname</replaceable> tells which release you want, and it can
<thead>
<row>
<entry>Bochs version</entry>
<entry>Release tag for SVN</entry>
<entry>SVN revision</entry>
<entry>Release tag for GIT</entry>
<entry>Release date</entry>
</row>
</thead>
<tbody>
<row>
<entry>2.8</entry>
<entry>REL_2_8_FINAL</entry>
<entry>March 10, 2024</entry>
</row>
<row>
<entry>2.7</entry>
<entry>REL_2_7_FINAL</entry>
<entry>14332</entry>
<entry>August 1, 2021</entry>
</row>
<row>
<entry>2.6.11 (bugfix)</entry>
<entry>REL_2_6_11_FINAL</entry>
<entry>13774</entry>
<entry>January 5, 2020</entry>
</row>
<row>
<entry>2.6.10 (intermediate)</entry>
<entry>REL_2_6_10_FINAL</entry>
<entry>13629</entry>
<entry>December 1, 2019</entry>
</row>
<row>
<entry>2.6.9 (intermediate)</entry>
<entry>REL_2_6_9_FINAL</entry>
<entry>13181</entry>
<entry>April 9, 2017</entry>
</row>
<row>
<entry>2.6.8 (intermediate)</entry>
<entry>REL_2_6_8_FINAL</entry>
<entry>12740</entry>
<entry>May 3, 2015</entry>
</row>
<row>
<entry>2.6.7 (intermediate)</entry>
<entry>REL_2_6_7_FINAL</entry>
<entry>12531</entry>
<entry>November 2, 2014</entry>
</row>
<row>
<entry>2.6.6 (bugfix)</entry>
<entry>REL_2_6_6_FINAL</entry>
<entry>12375</entry>
<entry>June 15, 2014</entry>
</row>
<row>
<entry>2.6.5 (intermediate)</entry>
<entry>REL_2_6_5_FINAL</entry>
<entry>12349</entry>
<entry>June 1, 2014</entry>
</row>
<row>
<entry>2.6.2 (bugfix)</entry>
<entry>REL_2_6_2_FINAL</entry>
<entry>11694</entry>
<entry>May 26, 2013</entry>
</row>
<row>
<entry>2.6.1 (intermediate)</entry>
<entry>REL_2_6_1_FINAL</entry>
<entry>11667</entry>
<entry>April 7, 2013</entry>
</row>
<row>
<entry>2.6</entry>
<entry>REL_2_6_FINAL</entry>
<entry>11395</entry>
<entry>September 2, 2012</entry>
</row>
<row>
<entry>2.5.1 (bugfix)</entry>
<entry>REL_2_5_1_FINAL</entry>
<entry>10946</entry>
<entry>January 6, 2012</entry>
</row>
<row>
<entry>2.5</entry>
<entry>REL_2_5_FINAL</entry>
<entry>10801</entry>
<entry>November 27, 2011</entry>
</row>
<row>
<entry>2.4.6</entry>
<entry>REL_2_4_6_FINAL</entry>
<entry>10202</entry>
<entry>February 22, 2011</entry>
</row>
<row>
<entry>2.4.5</entry>
<entry>REL_2_4_5_FINAL</entry>
<entry>9914</entry>
<entry>April 25, 2010</entry>
</row>
<row>
<entry>2.4.2</entry>
<entry>REL_2_4_2_FINAL</entry>
<entry>9568</entry>
<entry>November 12, 2009</entry>
</row>
<row>
<entry>2.4.1</entry>
<entry>REL_2_4_1_FINAL</entry>
<entry>9368</entry>
<entry>June 7, 2009</entry>
</row>
<row>
<entry>2.4</entry>
<entry>REL_2_4_FINAL</entry>
<entry>9289</entry>
<entry>May 3, 2009</entry>
</row>
<row>
<entry>2.3.7</entry>
<entry>REL_2_3_7_FINAL</entry>
<entry>8537</entry>
<entry>June 3, 2008</entry>
</row>
<row>
<entry>2.3.6</entry>
<entry>REL_2_3_6_FINAL</entry>
<entry>8111</entry>
<entry>December 24, 2007</entry>
</row>
<row>
<entry>2.3.5</entry>
<entry>REL_2_3_5_FINAL</entry>
<entry>7840</entry>
<entry>September 16, 2007</entry>
</row>
<row>
<entry>2.3</entry>
<entry>REL_2_3_FINAL</entry>
<entry>7538</entry>
<entry>August 27, 2006</entry>
</row>
<row>
<entry>2.2.6 (intermediate2)</entry>
<entry>REL_2_2_6_FINAL</entry>
<entry>7060</entry>
<entry>January 29, 2005</entry>
</row>
<row>
<entry>2.2.5 (intermediate1)</entry>
<entry>REL_2_2_5_FINAL</entry>
<entry>6942</entry>
<entry>December 30, 2005</entry>
</row>
<row>
<entry>2.2.1 (bugfix1)</entry>
<entry>REL_2_2_1_FINAL</entry>
<entry>6624</entry>
<entry>July 8, 2005</entry>
</row>
<row>
<entry>2.2</entry>
<entry>REL_2_2_FINAL</entry>
<entry>6476</entry>
<entry>May 28, 2005</entry>
</row>
<row>
<entry>2.1.1 (bugfix1)</entry>
<entry>REL_2_1_1_FINAL</entry>
<entry>5560</entry>
<entry>February 8, 2004</entry>
</row>
<row>
<entry>2.1</entry>
<entry>REL_2_1_FINAL</entry>
<entry>5441</entry>
<entry>January 9, 2004</entry>
</row>
<row>
<entry>2.0.2 (bugfix2)</entry>
<entry>REL_2_0_2_FINAL</entry>
<entry>4592</entry>
<entry>January 21, 2003</entry>
</row>
<row>
<entry>2.0.1 (bugfix1)</entry>
<entry>REL_2_0_1_FINAL</entry>
<entry>4491</entry>
<entry>January 4, 2003</entry>
</row>
<row>
<entry>2.0</entry>
<entry>REL_2_0_FINAL</entry>
<entry>4409</entry>
<entry>December 21, 2002</entry>
</row>
<row>
<entry>1.4.1 (bugfix1)</entry>
<entry>REL_1_4_1_FINAL</entry>
<entry>2513</entry>
<entry>June 22, 2002</entry>
</row>
<row>
<entry>1.4</entry>
<entry>REL_1_4_FINAL</entry>
<entry>2235</entry>
<entry>March 27, 2002</entry>
</row>
<row>
<entry>1.3</entry>
<entry>REL_1_3_FINAL</entry>
<entry>1705</entry>
<entry>December 10, 2001</entry>
</row>
<row>
<entry>1.2.1 (bugfix1)</entry>
<entry>REL_1_2_1_FINAL</entry>
<entry>912</entry>
<entry>June 12, 2001</entry>
</row>
<row>
<entry>1.2</entry>
<entry>REL_1_2_FINAL</entry>
<entry>797</entry>
<entry>June 3, 2001</entry>
</row>
<row>
<entry>1.1.2 (bugfix3)</entry>
<entry>REL_1_1_2_BASE</entry>
<entry>510</entry>
<entry>May 16, 2001</entry>
</row>
<row>
<entry>1.1.1 (bugfix2)</entry>
<entry>REL_1_1_1_BASE</entry>
<entry>57</entry>
<entry>April 9, 2001</entry>
</row>
<row>
<entry>1.1 (bugfix1)</entry>
<entry>REL_1_1_BASE</entry>
<entry>51</entry>
<entry>April 6, 2001</entry>
</row>
<row>
<entry>1.0 (bochs-2000_0325a)</entry>
<entry>REL-bochs-2000-03-25</entry>
<entry>7</entry>
<entry>March 25, 2000</entry>
</row>
</tbody>
</tgroup>
@ -1374,25 +1296,15 @@ The <replaceable>tagname</replaceable> tells which release you want, and it can
</section>
<section><title>More about SVN</title>
<section><title>More about GIT</title>
<para>
Entire books have been written on SVN, so there's no sense in duplicating
it all here in the Bochs documentation. Some sources of additional
information is listed below.
&FIXME;
</para>
<itemizedlist>
<listitem><para>The <ulink url="http://subversion.apache.org">subversion.apache.org
site</ulink> has tons of SVN FAQs and documentation.</para></listitem>
<listitem><para>
A German <ulink url="http://pvs.uni-muenster.de/pvs/lehre/WS06/projekt/svn-faq.html">SVN FAQ</ulink>
is available at University of Muenster.
</para></listitem>
</itemizedlist>
</section>
</section> <!-- End of Installation:Getting the source code with SVN -->
</section> <!-- End of Installation:Getting the source code with GIT -->
<section id="install-binary"><title>Installing a Binary</title>
@ -1746,7 +1658,7 @@ descriptions or tool-tips).
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 SVN. If not, you can return to <link
out Bochs with GIT from GitHub. 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
@ -3070,7 +2982,7 @@ called from <command>make</command> are causing the failure (e.g. compiler / lin
In some cases it might be useful to rebuild Bochs completely by calling
<command>make dist-clean</command> and running the <command>configure</command>
script once again. These steps are recommended if the development sources from
SVN are used and one of the build system files (e.g. <filename>Makefile</filename>
GitHub are used and one of the build system files (e.g. <filename>Makefile</filename>
or <filename>config.h.in</filename>) has been changed.
</para>
<para>
@ -7154,7 +7066,7 @@ When reporting errors while building Bochs to the &devlist; or the SF bug
tracker for the Bochs project, this information is required to fix the issue:
<itemizedlist>
<listitem><para>host platorm / build environment</para></listitem>
<listitem><para>Bochs release version or SVN revision</para></listitem>
<listitem><para>Bochs release version or GIT SHA revision code</para></listitem>
<listitem><para>configure options used</para></listitem>
<listitem><para>full error message</para></listitem>
<listitem><para>config.log output if configure failure</para></listitem>
@ -7173,7 +7085,7 @@ or submit the patch in SF patch tracker for Bochs.
If Bochs does not work properly (e.g. panic, segfault, malfunction of emulated device)
we need some information to find out what's going on:
<itemizedlist>
<listitem><para>Bochs version used (version number if binary release / SVN revision
<listitem><para>Bochs version used (version number if binary release / GIT revision
if self-compiled)</para></listitem>
<listitem><para>host platorm / build environment (if self-compiled)</para></listitem>
<listitem><para>bochsrc options used</para></listitem>
@ -7187,7 +7099,7 @@ we need some information to find out what's going on:
Patches for Bochs should be provided in the "unified diff" format. In addition
to the patch file and a detailed description this information is required:
<itemizedlist>
<listitem><para>patch applies to Bochs release version / SVN revision</para></listitem>
<listitem><para>patch applies to Bochs release version / GIT revision</para></listitem>
<listitem><para>test case (if required)</para></listitem>
</itemizedlist>
</para>
@ -7272,8 +7184,9 @@ will get 2 copies of every announcement.
<section id="bochs-cvs"><title>bochs-cvs mailing list</title>
<para>
This is the svn commit mailinglist (a unified diff email will be sent
whenever someone does a checkin in the bochs SVN repository).
This is the SVN commit mailinglist (an email had been sent whenever someone did
a checkin in the Bochs SVN repository). After transitioning to GitHub there is
no activity anymore. The mail archive is still present.
</para>
<para>