DOSEMU installation instructions (from source)
==============================================

-> REQUIREMENTS for DOSEMU:
    - egcs >= 2.91.66 (1.1.2) / gcc >= 2.95.2
    - glibc >= 2.1.3
    - Linux >= 2.0.30, 2.x.y >= 2.1.27 (>= 2.4.20 recommended)
      2.6 kernels <= 2.6.5 can be problematic
    - bison (not just yacc) and flex

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

- (optional) adjust compiletime-settings; see compiletime-settings.help
  for help.

- make
or
- create a seperate directory and run
    $SRCDIR/configure (or $SRCDIR/default-configure; see below)
    make
  in that directory.

--------------------------------------------------------------------------
2a. Install 
--------------------------------------------------------------------------

- 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. Update
--------------------------------------------------------------------------

- 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 can adjust dosemu.conf or ~/.dosemurc yourself and point 
$_hdimage to the right boot directory or hdimage (which can be a symbolic
link). Alternatively you can create symbolic links in ~/.dosemu/drives
such as
	~/.dosemu/drives/c ---> /dosc (ln -s /dosc ~/.dosemu/drives/c)
and so on where /dosc is your mounted DOS partition or
	~/.dosemu/drives/c ---> ~/msdos
where you put a working DOS installation in ~/msdos (io.sys, msdos.sys,
command.com and so on, or equivalents). This symbolic link is also
created the first time you run [x]dosemu or if you run [x]dosemu -install.


--------------------------------------------------------------------------
3.  Want to use a different configuration ?
--------------------------------------------------------------------------

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

If you want a DOSEMU executable with development settings (debug info,
experimental features, and so on) then it is easier to use the file 
compiletime-settings.devel -- you can use it by running
	./default-configure -d
(*not* ./configure -d) prior to running make.

Optimizations: 
BIG NOTE: do _not_ use -O3 in CFLAGS, because it forces _inline_ at
places where we don't want it !

---- NOTE: the setup tool is temporarily disabled! ----
Or (if you have Tcl/Tk installed) alternatively, you can use the 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).


More notes about system-wide installation
=========================================

This section provides a little background and explanations, aimed
at Linux distributors, people who set up large installations
and anyone else who is interested.

As of DOSEMU-1.0.2 DOSEMU is not longer installed suid-root by default.
Running DOSEMU suid-root is not (and never was) recommended on net-connected
machines, hence, whoever really wants to do it should fiddle with the problems
himself.

By default, every user has its own copy/instance of DOS 'somewhere' 
(default is $HOME/dosemu/freedos), which consists of symbolic links 
to shared DOS files or is completely private. This way each user has 
full write access to the C: drive, which is what is normally expected 
in a DOSish environment.

The systemwide install, "make install" keeps the DOSEMU binaries, 
the docs and the templates to generate the user's private
DOSEMU instance on demand. Whenever a the script [x]dosemu (of such a
systemwide install) is called by a user who has no private instance yet,
the script does the install (essentially, it unpacks tarballs which
consist of symbolic links and a few small files) before it launches DOS. 

This systemwide installation can be created as follows:

  - in addition to the DOSEMU source distribution you first have
    to download at least the file dosemu-freedos-bin.tgz from dosemu.org
    (this contains a bootable collection of suitable FreeDos binaries).

  - adjust the paths in compiletime-settings and compile the DOSEMU 
    source as follows: 

    $ cd /where/you/unpacked/the/dosemu/source/dosemu-<version>
    $ make
    $ su -
    # make install
    
where you can also pack the result into a RPM or what ever package format 
you like.

If you upgrade an existing DOSEMU or dosemu-freedos tarball then this
this change will have an immediate effect on all users,
because the user's private instances will have symlinks to the
commonly used DOS binaries.

			--Bart Oldeman, 2003/09/30
