
1. Directly executable DOS applications using dosemu
====================================================


Well, you may have wondered what these *.dexe file extension stands for.
Looking at the title above you now know it ;-)

In fact its a tiny hdimage which is bootable and just contains _one_
DOS application. Because this has isolated access to the hdimage only,
it may have less security issues then a complete DOS environement under
Linux and, more worth, you need not to fiddle with installation, because
the implementor already has done this for you.

On the other hand, you may create your own *.dexe files using the script
'mkdexe'. For this to run you need however atleast mtools-3.6, because
this versions has options, that older versions don't have.



In detail you need the following to make a *.dexe:

  - have mtools-3.6 available.
         ^^^^^^^^^^
  - have dosemu already compiled _and_ did _not_ 'make pristine'.

  - have a *.zip file containing the all files which belong to the
    DOS application (may be whole directories)

  - Have the following info handy before starting 'mkdexe':

       o  The partition size needed for the hdimage
       o  The DOS version that you want to put onto the hdimage.
          If your DOS app can run under the FreeDos kernel, you don't
          need that, else 'mkdexe' needs to know from what bootable
          existing partition to get the system from.
       o  The contents of the config.sys and autoexec.bat.

  - then (under root) do

       # cd ./dexe
       # mkdexe myapp.zip -x myapp.exe -o confirm

  - If all went ok, you then have a /var/lib/dosemu/myapp.dexe and this
    one can be executed via

       # dos -L myapp.dex [ dosemu-options ]
    or
       # dosexec myapp.dex [ dosemu-options ]

Here is what ./mkdexe will print as help, when called without argument:

   USAGE:
     mkdexe [{ application | hdimage}]
                        [-b dospart] [{-s|-S} size] [-x appname]
                        [-c confsys] [-a autoexe] [-C comcom ] [-d dosemuconf]
                        [-i IOname] [-m MSname]
                        [-o <option> [-o ...]]

     application  the whole DOS application packet into a *.zip file
     hdimage      the name of the target hdimage, ih -o noapp is give
                  (see below)
     dospart      If not given, FreeDos will be used as system
                  If given it must be either a bootable DOS partion (/dev/...)
                  or a already made bootable dosemu hdimage
     -s size      The _additional_ free space (in Kbytes) on the hdimage
     -S size      The total size (in Kbytes) of the hdimage -s,-S are mutual
                  exclusive.
     appname      The DOS filename of the application, that should be executed
     confsys      Template for config.sys
     autoexe      Template for autoexec.bat
     comcom       file name of the shell, usually command.com
     dosemuconf   Template for the dosemu.conf to use
     IOname       The name of DOS file, that usually is called IO.SYS,
                  (default for FreeDos: IPL.SYS) this one is always put as
                  first file onto the hdimage
     MSname       The name of DOS file, that usually is called MSDOS.SYS, 
                  (default for FreeDos: MSDOS.SYS) this one is always put as
                  second file onto the hdimage
     -o <option>  Following option flags are recognized:
                    confirm   offer config.sys, autoexec.bat and dconfig
                              to edit via $EDITOR
                    nocomcom  Omit command.com, because its not used anyway
                              when using  shell=c:\appname.exe
                    noapp     Make a simple bootable hdimage for standard
                              DOSEMU usage (replacement for hdimage.dist)


If you want to change the builtin configuration file, you may use
./src/tools/periph/dexeconfig to extract/re-insert the configuration.

  # dexeconfig -x configfile dexefile

extracts the configuration out of 'dexefile' and puts it into 'configfile'

  # dexeconfig -i configfile dexefile

does the reverse.

There is a problem, however, when you want allow a user to execute a DEXE
and the DOS application needs to write to a file within the dexe
(which is in fact a whole DOS FS). For this would have to give write
permissions to the user (what is not what you want).
DEXEs have a workaround for this: You may set read-only permissions
for the DEXE file itself in the Linux-FS, but set a flag in the DEXE itself,
so that DOSEMU will open this file read/write anyway.
This means: The user cannot delete or replace the DEXE, but the imbedded
DOS-application can (totally isolated) write to DOS files within the
DEXE (complicated, isn't it?). To set such a permission, you (again) need
'dexeconfig':

  # dexeconfig -p W dexefile

Here is what 'dexeconfig' will print as help, when called without argument:

   USAGE:
      dexeconfig [-M] [-p {w|W}] -i configfile dexefile
      dexeconfig -x configfile dexefile
      dexeconfig -v  dexefile
      dexeconfig -p {w|W}  dexefile

   where is
      -i      insert a config file
      -x      extract a config file
      -p w    clear write permission
      -p W    set write permission
      -v      view status information


It would be great, if we could collect an archive of working, free
distributatble *.dexe files, and I'm herein asking for contribution.
However, BIG NOTE, if you want to contribute a *.dexe file to the public,
please do NOT use any other DOS than FreeDos else you would violate
existing copyrights. This also (unfortunately) is true for OpenDos
which can only be distributed after Caldera did allow you to do so :-(

If you _have_ assembled a *.dexe and you wnat to contribute it, please
send me a mail and upload the stuff to

   tsx-11.mit.edu:/pub/linux/ALPHA/dosemu/Development/Incoming

I'll then put it into
 
   tsx-11.mit.edu:/pub/linux/ALPHA/dosemu/dexe/*
   ftp.suse.com:/pub/dosemu/dexe/*

There currently only is one in that archive: fallout.dexe
Its a nice Tetris like games that I found on an old CDrom and which runs in
300x200 on console and X (not Slang-terminal). When you put it into
you /var/lib/dosemu/* directory, you may start it via:

   dosexec fallout.dexe -X


Hope we get more of *.dexe in the future ....


2. Using binfmt_misc to spawn DEXEs direktly
============================================

There is a nifty kernel patch flying around from Richard Guenther
<zxmpm11@student.uni-tuebingen.de>. This can be get via

  http://www.anatom.uni-tuebingen.de/~richi/linux/binfmt_misc.html

We hope this patch makes it into the kernel, because then we could
execute a DEXE just by typing its name at the Bash prompt. To register
DEXE format using binfmt_misc you do (in your /etc/rc.-whatever)

  cd /proc/sys/fs/binfmt_misc
  echo :DEXE:M::\\x0eDEXE::/usr/bin/dosexec: >register

thats all.


3. Making a bootable hdimage for general purpose
================================================

You may also use './mkdexe' do generate a _normal_ bootable hdimage,
it then has the advantage, that you no longer need to fiddle with a DOS boot
disk. I succeded to make a bootable hdimage with FreeDos, MSDOS-6.2 and
also WINDOWS'95 (yes, that can be booted with the DOSEMU-own MBR ;-)
I did not test other DOSes, but I guess, they also will work, as long as you
pass the correct system file names to 'mkdexe' (-i, -m options)

Example:
Given you have a bootable DOS-partition in /dev/hda1, then this ...

  # cd ./dexe
  # ./mkdexe myhdimage -b /dev/hda1 -o noapp

... will generate a direct bootable 'myhdimage' from your existing DOS
installation. You need not to make a boot floppy, nor need you to fiddle
with fdisk /MBR and sys.com any more. Using -o confirm you may also
edit the configuration files before they are put onto the hdimage.

Further more, there is a script on top of mkdexe: setup-hdimage, which
helps more to firsttime install DOSEMU's hdimage. It prompts for
needed things and should work on most machines.

  # cd /where/I/have/dosemu
  # ./setup-hdimage



4. Accessing hdimage files using mtools
=======================================

In the ./dexe directory there is also a script, that allows you to
directly access the hdimage's files, even without changing your
/etc/mtools.conf. The usage of this script is:

   USAGE:
     do_mtools device mcommand [ arg1 [...] ]

   where is:
     device    = DOS-partition such as '/dev/hda1'
                 or a DOSEMU hdimage
     mcommand  = any valid mtools comand
     argX      = any valid mtools argument.
                 NOTE: for the DOS drive use 'W:'

   example:
     do_mtools /var/lib/dosemu/hdimage mcopy W:/autoexec.bat -


Hans, May 16, 1997
<lermen@fgan.de>
