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-bin.tgz from dosemu.org or one of its mirrors
- 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 installation
--------------------------------------------------------------------------

(Note: You normally don't need it for a non-suid-root DOSEMU).

(BIG FAT WARNING: you have to be _very_ skilled to do it right !!)

- 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

- Copy /etc/dosemu/dosemu.users.easy to /etc/dosemu/dosemu.users which 
  contains a list of users who are privileged to use dosemu.  The user "all" 
  will allow anyone to run dosemu. example:

    root c_all
    all c_all

  Note that the above example is _insecure_, because it allows all to any
  user. If you want security, then copy /etc/dosemu/dosemu.users.secure to
  /etc/dosemu/dosemu.users and have a look at an other example in
  ./doc/README.txt chapter 2.

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

- For users without enough privileges to change $_hdimage, the dosemu boot 
  directory or hard disk image and several other variables can only be set
  in the system-wide dosemu.conf and not in ~/.dosemurc.

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

- For suid-root installations:
  Check your dosemu.users file (maybe insufficient privileges set)

- Read your dosemu.config 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.


       Hans Lermen

SnailMail:
       Am Muehlenweg 38
       D53424 REMAGEN-Unkelbach
       Germany

Email: lermen@fgan.de
