@chapter{ Running from the command line }

It is possible to launch Doomsday directly from the command line. If all data
files can be found under the default directories, the engine should be able to
launch itself without further aid. If not, command line options must be used
to configure data file locations and other settings. To see which options are
used by default, you can preview the command line in the Doomsday Frontend
(e.g., by right-clicking the Play button).

For historical reasons, Doomsday has never considered the command line the
primary launch method. Consequently, it currently lacks convenient things like
a @opt{--help} option for aiding command line usage. For more information
about command line options, see the @link{Command Line Options Reference}
{http://dengine.net/dew/index.php?title=Command_line_options}.

$* TODO: Much of the following is outdated. Ringzero makes life simpler even
   with a pure command line setup. The parts that are still relevant should 
   be revised.

@section{ File paths on the command line }

There are a few things you should know about the handling of relative
paths. First of all, these are the directories that the engine is working
with:

@list{
@item Doomsday root/base directory (for example @file{ C:\Doomsday\ }).
	Everything relating to the Doomsday engine is under this directory.

@item Working/runtime directory (for example @file{ C:\Doomsday\Run\x\ }).
	This is the directory where the engine spends it time when a game
	is running.

@item Data directory (for example @file{ C:\Doomsday\Data\x\ }).
	WAD files and external resources are loaded from here.
}

The @opt{-basedir} option tells the engine where the base directory is in
relation to the runtime directory (or it's the the absolute path of the
base directory, e.g. @file{ C:\Doomsday\ }).

The principle is that @opt{-basedir} only affects built-in default paths and relative paths in DED files. @opt{-basedir} does not affect relative paths in command line options. If a relative path is given on the command line, it is first searched in relation to the runtime directory. For example, the option @opt{-file doom.wad} will make the engine read the file @file{doom.wad}, which is located in the runtime directory. In the default configuration this is @file{ C:\Doomsday\Run\jDoom\ }. If the file is not found in the runtime directory, the data directory is searched instead.

KickStart automatically uses a @opt{-basedir} of @file{..\..}, which means the root directory is the 'grandparent' of the runtime directory. The option @opt{-sbd} (@opt{-stdbasedir}) is the equivalent of @opt{-basedir ..\..}.

There is one exception, though. With the @opt{-file} (and @opt{-iwad}) options a relative path can begin with a greater-than character (>) or a closing brace character (@}). When the engine loads the WAD file in question, the > or @} character is replaced with the path specified by @opt{-basedir}. For example, @opt{-file >Data\Doom.wad} would make the engine load a WAD named @file{ C:\Doomsday\Data\Doom.wad } (assuming the default Doomsday root @file{ C:\Doomsday\ }). Note that if you're executing @file{Doomsday.exe} from the command line or from a DOS batch file, you must enclose the file names that contain a > character in quotes or otherwise DOS will think you're trying to redirect output. In response files it doesn't matter if there are quotes or not. (If you really are trying to redirect output, you should use the @opt{-out} option.)

The default launch method (used by KickStart 1.6) is a runtime directory oriented approach. KickStart will change the current working directory to the Game's runtime folder and execute @file{Doomsday.exe} from there, with the @opt{-basedir ..\..} option. This way the engine will use the appropriate runtime folder as the working directory, but will also know where the Doomsday root directory is by adding the base directory's @file{..\..} to default path names (like fonts and definitions files).

There is an alternative approach, which could be called an executable oriented approach. @file{Doomsday.exe} is executed in the @file{Bin} directory, with the options @opt{-userdir <runtime-path> -basedir <path-to-root>}. @file{<runtime-path>} can be a relative or an absolute path to the correct runtime directory. Again, @opt{-basedir} tells the engine where the root directory is, using an absolute path or in relation to @file{<runtime-path>}. @opt{-userdir} will make the engine run in the given directory, i.e. it specifies the runtime directory.

Note that @opt{-game} and @opt{-gl} work a bit differently because their arguments are directly passed on to the Win32 routine @cmd{LoadLibrary}. You should either omit the path entirely (e.g. @opt{-game jHeretic.dll}) or use a full path to the DLL (e.g. @opt{-game C:\Doomsday\Bin\jHeretic.dll}), no matter where you're executing @file{Doomsday.exe}.

The default place where you should put your IWADs is @file{ Data\<Game>\ }. jDoom, jHeretic and jHexen will by default look for IWADs in @file{ Data\<Game>\ }, @file{ Data\ }, the base directory and the runtime directory, in that order.

*$

@section{ Loading IWADs }

IWAD files must be specified with the @opt{-iwad} option. You can either
provide the path to the IWAD to use, or the path of the directory under which
IWADs are located. Doomsday will look through the specified location and
use all the recognized IWADs automatically. In other words, you can have the
IWADs for all games stored in a single directory; Doomsday will use the
appropriate one for each launched game.

$ TODO: Is it allowed to use more than one -iwad option?

There are alternative ways to specify IWADs: see @ref{environ}{Environment}.

@section{ The @opt{-file} option }

@a{fileopt} The @opt{-file} (or @opt{-f}) option is used to load WAD files and
other data files from the command line.

@note{Paths given to @opt{-file} are relative to the runtime directory; see
the default in @ref{files}{Files}.}

In addition to normal WAD files, the @opt{-file} option can be used
to load any type of data files, for instance PCX images. An example:

@samp{@opt{-file image.pcx}}

This would load the file @file{image.pcx} from the runtime directory (or the
data directory). When loading files in this manner, the engine will treat the
file as if it was a WAD file with a single data lump. The lump gets its name
from the base of the file name, which in the example's case would be
@file{IMAGE}. Anyone can then refer to the data lump using that name, just as
if it was included in a WAD file.

$* TODO: Document unloading.

Any file loaded with the @opt{-file} option can't be unloaded from
memory at runtime using the @cmd{unload} command. This is mainly a
precaution, since unloading the main WAD file of the game or any
data related to it would lead to fatal errors.
*$
