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

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

--------------------------------------------------------------------------
1. Compile
--------------------------------------------------------------------------

- make
- su
- make install

--------------------------------------------------------------------------
1.  Want to use not 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 chose "Compile configiration / compilation", when you have
finished toggling the configuration switches, klick < Ok> and chose
the appropriate action ...
... well it should be self descriptive.


--------------------------------------------------------------------------
2.  First tiny test
--------------------------------------------------------------------------

You may want to instantaneously start dosemu. We supply a ready to boot
hdimage with a tiny FreeDos installation (just the kernel). This may
be booted via

- become root
- ./first-test

FreeDos kernel will show up, and you can leave it via

- C:> exitemu
or
- C:> exit
      ... oh well, FreeDos also exits on top level command.com :-(

--------------------------------------------------------------------------
3.  Configure  ... the _real_ stuff
--------------------------------------------------------------------------

- Copy ./etc/dosemu.conf to /etc if you are installing for the first time.
  ( make install would have done this, if /etc/dosemu.conf dosen't exist )
  Modify /etc/dosemu.setup by using the info in the file ./doc/README.txt
  chapter 2

- Copy ./etc/dosemu.users.easy to /etc/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.users.secure to
  /etc/dosemu.users and have a look at an other example in
  ./doc/README.txt chapter 2.

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

--------------------------------------------------------------------------
4  Boot ( 'comfortable' method ;-)
--------------------------------------------------------------------------

The most comfortable method to get DOSEMU booting your DOS is to
prepare a socalled 'bootdir'. This is a Linux directory under
/var/lib/dosemu, which contains all you normally have in the native
DOS partition. You may use

  ./setup-bootdir

to generate a /var/lib/dosemu/bootdir.first. But this one only serves
as starting point, so you better do it manually (or enhance the
./setup-bootdir generated one) as described:

Just copy/symlink all your DOS system files (IO.SYS, MSDOS.SYS) into it,
create a CONFIG.SYS and AUTOEXEC.BAT and symlink the rest of your (mounted)
native DOS partition into it. Here the possible contents of a
/var/lib/dosemu/bootdir.first (/dos beeing your mounted DOS):

  config.sys
  autoexec.bat
  dosemu           # directory containing the DOSEMU supplied stuff
  command.com -> /dos/command.com
  io.sys -> /dos/io.sys
  msdos.sys -> /dos/msdos.sys
  dos -> /dos/dos

If you have a special DOS, that needs a private bootsector, copy this
one (using 'dd if=/dev/xxx of=boot.blk bs=512 count=1') into
/var/lib/dosemu/bootdir/boot.blk.
Then put a '$_hdimage = "bootdir.first"' in to your /etc/dosemu.conf
and you can boot from this directory:

- Run 'dos -O 2>/tmp/error.out', ... and dosemu should boot your DOS...
  ... If not make certain that the /etc/dosemu.conf and /etc/dosemu.users
  are setup correctly. You can examine '/tmp/error.out' for errors/remarks
  that were reported by DOSEMU.

- Exit dos by running "c:\dosmeu\exitemu".  If you have problems, hold down
  the <ctrl> and <alt> buttons simultaneously while pressing <pgdn>.
  (<ctrl><alt><pgdn> will automatically exit dosemu.)

The bootdir method, however, doesn't work if you use the DosC (FreeDos)
kernel, for this you have to use 'hdimages' and ./setup-hdimage. Have a look
at ./doc/README.txt, chapter 2 and ./doc/README-tech.txt, chapter 7.)


--------------------------------------------------------------------------
5. Some more hints after you've set up your bootdir (or hdimage)
--------------------------------------------------------------------------

- If hitting Alt-FunctionKey doesn't switch virtual consoles from DOSEMU,
  try using Ctrl-Alt-FunctionKey to switch from the virtual console running
  DOSEMU.

- You can start setting up /etc/dosemu.conf more throughly.

- You can set up DOSEMU to boot directly off your DOS hard disk partition.

- If you want to use disk compression such as STACKER or DOUBLESPACE with
  DOSEMU, you will have to configure /etc/dosemu.conf for partition access.

- From here you are on your own. Please read the documentation in
  ./doc/README.txt (chapter 2), the "DOSEMU-HOWTO" file, and the other files
  in the ./doc subdirectory.

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

- Check your /etc/dosemu.users file (maybe insufficient privileges set)

- Read your /etc/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 /etc/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 'dos -D+a -o debug'
  and prepare this mail via the tool we supply:

    ./submit-bug-report

  The tool will either send directly or save the mail to a file.
  For more on this please read the file ./doc/bugreports.txt

  For general discussion on dosemu use the mailing list
  linux-msdos@vger.rutgers.edu

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

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

./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 Alterning 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/dos.1
	This is the DOSEMU man page. It is now up to date with 0.98.
	This normally goes into the /usr/man/man1 directory.
./man/mkfatimage16.1
	This discribes 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/bugreports.txt
	How to report bug via gnats
./doc/configuration.txt
	How to use the menu driven configuration tools
./contrib/dosC/readme.dosemu
	Usage of FreeDos kernel within DOSEMU
./dexe/*
	Tools to make directly bootable DOS-apps and hdimages


----------

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
