QuickStart: Instructions on how to quickly get DOSEMU up and running.
==========

Well, you are impatient? Ok, maybe you'll succeed with this SHORT description.
However, if you are reasonable just execute ViewDocs to read the docs.
                                            ========

--------------------------------------------------------------------------
1. Install and use the ready-to-use DOSEMU binary distribution
--------------------------------------------------------------------------

The easiest way to get DOSEMU working on your machine is to use
the ready-to-use DOSEMU binary distribution. This one comes in 2 packages:

  - ftp://ftp.dosemu.org/dosemu/dosemu-freedos-bin.tgz
    (A tarball containing a collection of suitable FreeDos binaries)

  - ftp://ftp.dosemu.org/dosemu/dosemu-<version>-bin.tgz
    (A tarball containing the recent DOSEMU binaries)

You have to unpack both tarballs (as normal user, NOT as root) into
the same directory in your HOME, such as:

  $ mkdir mydos
  $ cd mydos
  $ tar -zxf dosemu-freedos-bin.tgz
  $ tar -zxf dosemu-1.0.2.1-bin.tgz
  $ cd dosemu

Now execute DOSEMU

  $ ./xdosemu

For a more detailed description have a look at README.bindist.

--------------------------------------------------------------------------
2. Compile
--------------------------------------------------------------------------

- adjust compiletime-settings; see compiletime-settings.help for help.
- make

--------------------------------------------------------------------------
2a. Want to install systemwide? 
--------------------------------------------------------------------------

- download dosemu-freedos-<version>bin.tgz from dosemu.org or one of its mirrors
  and rename it to dosemu-freedos-bin.tgz
- su -		(become root)
- make install

--------------------------------------------------------------------------
2b. Want to update a systemwide installation? 
--------------------------------------------------------------------------

- su -		(become root)
- make install

You can now start DOSEMU using "dosemu" or "xdosemu". By default, when you
start it the first time it will ask you if you want to create a FreeDOS C: 
drive in the directory ~/dosemu/freedos. This is accomplished by creating 
symbolic links to files in the system-wide DOSEMU tree. You can replace 
those symbolic links by real files if you wish to do so. The boot 
directory location and other runtime configuration variables are stored 
in the file ~/.dosemurc. This file overrides the dosemu.conf file which 
is usually either in /etc or /etc/dosemu. By default, most error and debug 
messages are logged to the file ~/.dosemu/boot.log.

If you do not want to use the FreeDOS C: drive in $HOME/dosemu/freedos, 
then you will have to adjust dosemu.conf or ~/.dosemurc yourself and point
$_hdimage to the right boot directory or hdimage (which can be a symbolic
link).

--------------------------------------------------------------------------
3.  Want to use a non-standard configuration ?
--------------------------------------------------------------------------

Then you have to edit compiletime-settings (changing on/off) and run
./default-configure _prior_ to running make.

Or (if you have Tcl/Tk installed) alternatively, you can use the new menu
driven configuration tool:

- ./setup-dosemu

then choose "Compile configuration / compilation", when you have
finished toggling the configuration switches, click < Ok> and choose
the appropriate action ...
... well it should be self descriptive.


--------------------------------------------------------------------------
4.  Configure for a system wide suid-root (or sudo-using) installation
--------------------------------------------------------------------------

(Note: this is only necessary if you wish to use graphics on the console
 or need direct port access, hardware interrupts or raw network access.
 Moreover, suidroot binaries might be a means to compromise system security).

- Install system-wide, as explained above in section 2.
  Modify /etc/dosemu/dosemu.conf by using the info in the file ./doc/README.txt
  chapter 2

- Either:
	chmod u+s /path/to/dosemu.bin
  or (recommended for better protection):
	* leave dosemu.bin non-suid-root
	* install "sudo" if you haven't already done so
	* use "visudo" as root to add entries such as
		joeuser   hostname=(root) NOPASSWD: /usr/local/bin/dosemu.bin
	  to your /etc/sudoers file, where "joeuser" is the user who is
	  allowed to run privileged DOSEMU and "hostname" is the name of
	  your current host (use "ALL" for any host).
	* if you change NOPASSWD to PASSWD then joeuser needs to type
	  the user's password (not root's password) when invoking DOSEMU.
	* invoke dosemu using "dosemu -s" when privileged functionality,
	  such as console graphics, is needed.
  This way DOSEMU will only use its root privileges during the 
  initialization phase, and drops them before booting the DOS.

- Certain privileged settings such as I/O ports, hardware IRQ passing,
  and console graphics can only be enabled using the system-wide dosemu.conf 
  and not in ~/.dosemurc.

- If all you need from suid operation is console graphics, then a dosemu.users
  file is no longer necessary; restricting users via "sudo" is a better
  approach if you want to do that.
  However, some other more specialized settings, such as $_ports, 
  $_irqpassing and $_hardware_ram, cannot  be used by a normal user in a 
  default suid installation. For that you need to copy and adjust
  /etc/dosemu/dosemu.users.example to /etc/dosemu/dosemu.users, which 
  contains a list of users who are privileged to use these DOSEMU features.
  Example:

    joeuser c_all

  For a more detailed description on 'running as user' have a look
  at ./doc/README.txt 'Running dosemu as a normal user' (chapter 6).

--------------------------------------------------------------------------
5.  Something's not right!!!
--------------------------------------------------------------------------

- Read your dosemu.conf file carefully and make corrections.

- Try disabling certain features.  The video options and some of the
  rawkeyboard options sometimes cause problems.

- If the video support does not work, ensure that the video BIOS address
  in dosemu.conf (variable $_vbios_seg) is correct.

- Read all documentation files carefully, and try to get some help from
  others who have used DOSEMU.

- Read the dosemu-HOWTO for Q&A's.

- If no luck, please send us a debug report by typing 'dosemu -D+a -o debug'
  and send the file debug together with your config files and a
  description of your problem to the SF bug tracking system that you can
  reach from

    http://www.dosemu.org

  Don't forget to mention the versions of DOSEMU, GCC, LIBC, Binutils etc.
  For problems with the packaging of DOSEMU by Linux distributors,
  please bother them directly - we won't hunt after those bugs.

  For general discussion on dosemu use the mailing list
  linux-msdos@vger.kernel.org

- Please be patient with us.  We get flooded with bug reports and do our
  best to respond in a timely fashion.

--------------------------------------------------------------------------
6.  Available documentation -- mostly somewhat outdated :(
--------------------------------------------------------------------------

./README.bindist
	Describes the ready-to-use DOSEMU binary distribution, which
	frees you from all bothering about compilation, installation
	and configuration ... just _use_ it.
./README.distributors
	Not intended for 'Joe User' but for Linux distributors.
./doc/dosemu-HOWTO.txt
	This is the F.A.Q. for DOSEMU.  It is a little bit outdated,
	but still very helpful.  (Read this file first, however.)
./ChangeLog
	This is a log file of progress that have been done on
	DOSEMU since previous versions.
./doc/DANG.txt
	The Dosemu Alterer Novice's Guide, for interested hackers
	and programmers alike, if they want to look at the internals
	of DOSEMU and how it works.
./doc/DPR
	The Dosemu Project Registry, an outdated document keeping
	track of who's doing what kind of programming for DOSEMU.
./man/dosemu.bin.1
	This is the 'lowlevel' DOSEMU man page. It is now up to date with 1.0.2.
./man/dosemu.1
	This is the DOSEMU man page of the wrapper script.
./man/mkfatimage16.1
	This describes how to create (empty) hdimages of various sizes.
./doc/announce
	The announcement textfile for DOSEMU.
./doc/README.txt
	Readme file for various applications and general purpose settings.
./doc/README-tech.txt
	Readme file for various technical details and settings.
./doc/configuration.txt
	How to use the menu driven configuration tools


----------

Many thanks to all involved, including all those who submitted debug
output for our viewing pleasure, keep it coming.


       Bart Oldeman

Email: bart@dosemu.org
