# INSTALL

## Environment variables

You can set the following environment variables to have additional control over Legacy behavior. None of them are required.

- DOOMWADDIR: This environment variable defines a path where wad files are located. This way you can easily share your wad files between different programs. It is searched before the current directory, and the wad directory list are searched.
- USER: This variable contains your username, is used as the default value for your player name in multiplayer games.
- HOME: This variable indicates your home directory. In the home directory Doom Legacy will create a legacy directory to store your config and savegame files. If this variable is not defined, a default legacy home directory will be checked for existing, or one created in the program directory. Failure to have a consistent HOME will lead to losing your config, and savegames will not be saved.
- UserProfile: This variable is checked on Windows systems as a substitute for HOME, if HOME is not defined.

## Install General Instructions

### Install Requires:

<nl>
- Doom Legacy executable.

  This may be obtained as a package download, or may be compiled from source. The binary download package may have a script or batch file to install the binary.

  The Doom Legacy source is in the source package. The source package Makefile has an install for the compiled executables, docs, and legacy.wad.

- The legacy.wad file.

  The legacy.wad is in the legacy common download package package, along with these docs. The legacy common may have a script or batch file to install it.

  The legacy.wad file contains fonts and graphics to run the Doom Legacy menu system.

  The search for the legacy.wad file goes through the program directory, the program wads directory, and the list of wad directories. There is also a LEGACYWADDIR option that can be specified at compile time, which provides an additional directory to look in for the legacy.wad file. This will be used for Mac Frameworks packaging.

  Do not hide the legacy.wad file in a subdirectory. Subdirectories will NOT be searched.

- SDL library.

  The SDL library is required for the SDL build of Doom Legacy. Linux users are expected to install the SDL library as a system resource.

  Doom Legacy uses SDL 1.2. The SDL 2 library is not compatible, and will not work.

  The SDL binaries have an SDL library included, for those users who do not have SDL already installed. If your system does not already have SDL libraries or have older SDL libraries, then these library files need to be installed with the Doom Legacy executable.

  For Windows users who do not install such libraries system wide, the SDL libraries will need to be installed with the executable.

  The install script may try to do this itself. If it fails to detect the situation correctly, manual installation of the SDL libraries may be required. They just need to be moved or copied to the Doom Legacy program directory.

  There are other compile options that do not use SDL, such as DOS_NATIVE, WIN_NATIVE, and LINUX_X11. The SDL libraries are not needed for such Doom ports. Other special libraries may be required to be installed. See the make_options file for compiling your port.

- Dynamic loading library, dlopen.

  The Linux binaries are able to use dlopen to dynamically load other libraries. This is a system standard library for Linux.

  Choosing to dynamically detect and load a library is an option that is available for some of the libraries, under Linux. Code is generated that uses dlopen to detect and load the library. This a more complicated way to use a library and involves extra overhead. The advantage is that a binary can be generated that will run, even when the user is missing some of those hardware devices, or their libraries.

  The user compiling a binary for themselves does not need such capability. They can simply choose to set hardware options as 1 or 0.

  The same capability is probably possible using Windows, or a Windows compatible dlopen could be installed to MSYS. We will need to find a Windows programmer willing to implement one or both of these in Doom Legacy.

- The libzip library is used to read zip archives. This allows loading zipped wads directly.

  It is selected as a compile-time option using the make_options file.

  When it normally optioned (1), the libzip library must be present, or else the system will refuse to run the Doom Legacy binary. This will work fine for the user compiling a binary just for themselves.

  When the dynamic loading (3) option is selected, then dlopen will be used to detect and load libzip. If libzip is not present then DoomLegacy will not be able to read zip archives.

- The zlib library is used to read some compressed extended nodes. These are only used by one extended node format, and as it is an option, is probably only present in a few very large wads.

  It is selected as a compile-time option using the make_options file.

  When it normally optioned (1), the zlib library must be present, or else the system will refuse to run the Doom Legacy binary. This will work fine for the user compiling a binary just for themselves. Zlib is used commonly enough that it may already be installed for another program.

  When the dynamic loading (3) option is selected, then dlopen will be used to detect and load zlib. When zlib is not present then DoomLegacy will still be able to run, but will not be able to uncompress the extended node map of some wads.

- The Linux X11 version has a sound device selection mechanism that can select between several sound devices: OSS, ESD, ALSA, PulseAudio, and JACK.

  The device could have been compiled in normally, or with dynamic loading.

  If the normal option was used, the device library must be present or else the system will refuse to run the Doom Legacy binary.

  If the dynamic loading option was used, then dlopen will be used to detect and load the sound device library.

- The Linux X11 version has a music device selection mechanism that can select between several music devices: MIDI, TiMidity, FluidSynth, external MIDI, FM_Synth, and AWE32_Synth.

  The device could have been compiled in normally, or with dynamic loading.

  If the normal option was used, the device library must be present or else the system will refuse to run the Doom Legacy binary.

  If the dynamic loading option was used, then dlopen will be used to detect and load the music device library.

- A Doom IWAD.

  The Doom IWAD can be one of the Id Games Doom wads (which are still under copyright) such as Doom, DoomII, Plutonia, TNT, or Heretic. A free IWAD such as FreeDoom can also be used.

  These IWAD should be in one of the Doom Legacy wad search directories. Any or all of the directories can contain wad files. The IWAD can also be specified explicitly on the command line, or launcher, but that becomes cumbersome.

  An IWAD search started from the "-game" switch, will search 3 subdirectories deep, looking for a known IWAD name. See GAME_SEARCH_DEPTH in doomdef.h.

  An IWAD search started from the "-iwad" switch, will search 5 subdirectories deep. See IWAD_SEARCH_DEPTH in doomdef.h. The depth is limited to control disk rattling on mistyped names.

  </nl>

  ### Types of Install:

  #### System Share Install

  <nl>
- Install to a system executable directory.
- The docs and wads are installed to a system share directory.
- The file and directory ownership will be set to a privileged owner.
- Access is for use by all system users. </nl>

  #### Games Share Install

  <nl>
- Install the binary in the games directory.
- The wads and docs are installed to a system share directory.
- Access is for use by all system users.
- The file and directory ownership will be set to a privileged owner.
- To change the install directory the install script must be edited. </nl>

  #### Games Install

  <nl>
- Install entirely in the games directory, for use by all system users.
- The file and directory ownership will be set to a privileged owner.
- To change the install directory the install script must be edited. </nl>

  #### User Install

  <nl>
- Install for the use of the immediate user, owned by the immediate user.
- The install directory must be within the user directory space, and will be owned by the user.
- A directory may be specified. </nl>

  ## Linux

  #### System Share Install

  $ install_nix sys $ install_nix sys GROUP=1234 OWNER=9876 PREFIX=/opt
  <nl>
- Specify PREFIX= to install to "/usr" or "/opt", the default is "/usr/local".
- The default file and directory ownership will be "games:games".
- Specify GROUP= and OWNER= to change the ownership. </nl>

      PREFIX = "/usr/local"
      INSTALL_BIN_DIR = "$PREFIX/bin"
      INSTALL_SHARE_DIR = "$PREFIX/share/games/doomlegacy"
      INSTALL_WADS_DIR = "$PREFIX/share/games/doomlegacy/wads"

  #### Games Share Install

  $ install_nix sharegames $ install_nix sharegames GROUP=1234 OWNER=9876 PREFIX=/opt
  <nl>
- The default file and directory ownership will be "games:games". </nl>

      PREFIX = "/usr/local"
      INSTALL_BIN_DIR = "$PREFIX/games"
      INSTALL_SHARE_DIR = "$PREFIX/share/games/doomlegacy"
      INSTALL_WADS_DIR = "$PREFIX/share/games/doomlegacy/wads"

  #### Games Install

  $ install_nix games $ install_nix games GROUP=1234 OWNER=9876 PREFIX=/opt
  <nl>
- The default file and directory ownership will be "games:games".
- All files are installed to the games directory. </nl>

      PREFIX = "/usr/local"
      INSTALL_BIN_DIR = "$PREFIX/games/doomlegacy"
      INSTALL_WADS_DIR = "$PREFIX/games/doomlegacy/wads"

  #### User Install

  $ install_nix user $ install_nix user doomgames
  <nl>
- The user directory may be specified.
- Files are owned by the installer (user).
- All files are installed to the user directory.
- The user can still access wads in any other wad directory. </nl>

      INSTALL_BIN_DIR="$HOME/games/doomlegacy"

  #### Search directories in Linux

  To change, edit source file doomdef.h, and re-compile.
  Other directories can be added to doomdef.h, with up to 21 search directories.
  The tilde is converted to $HOME by Doom Legacy.
  Where PROGDIR is the program directory, and DEFDIR is the current directory.

  #### Search for legacy.wad:

  <nl>
- "PROGDIR"
- LEGACYWADDIR
- "PROGDIR/wads"
- wad search directory list </nl>

  #### Search order, IWAD:

  <nl>
- DOOMWADDIR
- "DEFDIR"
- "PROGDIR/wads"
- "~/games/doomlegacy/wads"
- "~/games/doomwads"
- "~/games/doom"
- "/usr/local/share/games/doomlegacy/wads"
- "/usr/local/share/games/doomwads"
- "/usr/local/share/games/doom"
- "/usr/local/games/doomlegacy/wads"
- "/usr/local/games/doomwads"
- "/usr/share/games/doom"
- "/usr/share/games/doomlegacy/wads"
- "/usr/share/games/doomwads"
- "/usr/games/doomlegacy/wads"
- "/usr/games/doomwads"
- "~/games/doomlegacy"
- "/usr/local/share/games/doomlegacy"
- "/usr/local/games/doomlegacy"
- "/usr/share/games/doomlegacy"
- "/usr/games/doomlegacy"
- "PROGDIR" </nl>

  ### Linux Install Notes

  The installation location is flexible, and can be moved. The installation directory can be one that all players can use, such as /usr/local/games/doomlegacy.

  To manually install, unpack the tar file contents in the installation directory. The installation directory needs to include the doomlegacy binary, and legacy.wad. The tar file will also install the Doom Legacy docs there. The installation directory can also contain an autoexec.cfg file, that can execute Doom Legacy commands upon every Doom Legacy startup.

  The IWAD files should go in a separate directory that can be shared between all Doom source ports (such as /usr/local/share/games/doomwads). The list of directories will be searched for the IWAD file. This list is specified for each operating system in the doomdef.h file. Most of the directories searched are system directories, and some user directories. Wads that are specific to Doom Legacy can be put in one of the directories that is unique to Doom Legacy.

  The DOOMWADDIR environment variable can be set to point to another directory, in a login script or a game starting script. This environment variable was used by some other ports to specify the Doom wads directory. The DOOMWADDIR directory will be searched before the list. The current directory, and a wads directory of the program directory are also searched before the list.

  Specify the verbose flag on the command line, "-v", to see the search list, and other directories. It is shown on the console, and to stderr.

  You can also make soft links in the above mentioned IWAD directory to point to the actual IWAD files. The valid IWAD file names for each games selection can be found in docs/technical/wad_selection.txt.

  $ ln -s wads/idgames/doom1.wad doom1.wad $ ln -s wads/idgames/doom2.wad doom2.wad $ ln -s wads/idgames/doomu.wad doomu.wad $ ln -s wads/idgames/plutonia.wad plutonia.wad $ ln -s wads/idgames/tnt.wad tnt.wad $ ln -s wads/freedoom-iwad-0.7/doom2.wad freedoom.wad $ ln -s wads/freedoom-iwad-0.9/freedoom2.wad freedoom2.wad

  Doom Legacy will use the HOME environment variable, which is usually set by your Linux login, to find your home directory. There it will make a hidden directory named .doomlegacy for storing your configuration files and saved games. If HOME is not set, Doom Legacy will try to find an alternate home directory. First it will try to find a user created "legacyhome" in the current directory. If that fails it will try to create "legacyhome" in the program directory.

  This behavior can be overridden by using the -home and -config switches:

  $ doomlegacy -home ~/doomstuff -game plutonia $ doomlegacy -home ~/doom -config ~/doom/plutconfig.cfg -game plutonia

  PWAD and DeHackEd files can be included using the -file switch. Examples:

  $ doomlegacy -game tnt $ doomlegacy -game plutonia -file pwad/pl2/PL2.WAD $ doomlegacy -iwad freedoom.wad -file new_map13.wad $ doomlegacy -file pwad/Twilight/TWILIGHT.DEH pwad/Twilight/TWILIGHT.WAD

  Script files can also be used to start Doom Legacy:

  #!/bin/sh cd /usr/local/games/legacy/ USER="Shotgun-wizard" DOOMWADDIR=wads doomlegacy -iwad doom2.wad -file DM8.WAD

  ## FreeBSD, Solaris

  ### FreeBSD Install Notes

  FreeBSD, Solaris, and the other similar operating systems use the LINUX install and operating instructions.

  If there is some unique code for these operating systems. Should some unique problem be discovered please notify the Doom Legacy team by way of the SourceForge DoomLegacy project bug and request system. These notes will then be updated appropriately. If a solution is also submitted the problem may even get fixed.

  ## Windows

  There may be several install batch files present, because of the various flavors of DOS and WINDOWS. Choose one that fits your system the best. Help specifics for that batch file are obtained by running it with no parameters.

  The instructions here most closely follow the install for Win98. Other flavors of Windows may have more options.

  #### System Share Install

  $ install_win sys
  <nl>
- The executable, legacy.wad, and docs are installed in the Program Files directory.
- The wads directory is outside that file structure. </nl>

      INSTALL_DIR =  "\Program Files\doomlegacy"
      INSTALL_WADS = "\doomwads"

  #### Games Share Install

  Games Share install is not available for Windows. Use Games install.

  #### Games Install

  $ install_win games $ INSTALL_WIN games d:
  <nl>
- A hard drive letter or other prefix may be specified as the second parameter.
- The executable, legacy.wad, and docs are installed in the Program Files directory.
- There is a wads subdirectory, mostly for legacy specific wads. <lib>Other, generic wads directories, will also be searched. </nl>

      INSTALL_DIR = \games\doomlegacy
      INSTALL_WADS = %INSTALL_DIR%\wads

  #### User Install

  $ install_win user $ INSTALL_WIN user my_doom_directory
  <nl>
- The user directory may be specified.
- The default user install directory is "games/doomlegacy" in the user directory. </nl>

      INSTALL_BIN_DIR="$HOME/games/doomlegacy"

  #### Search directories in Windows

  To change, edit source file doomdef.h, and re-compile.
  Other directories can be added to doomdef.h, with up to 21 search directories.
  The tilde is converted to $HOME by Doom Legacy.
  Where PROGDIR is the program directory, and DEFDIR is the current directory.

  #### Search for legacy.wad:

  <nl>
- "PROGDIR"
- LEGACYWADDIR
- "PROGDIR\wads"
- wad search directory list </nl>

  #### Search order, IWAD:

  <nl>
- DOOMWADDIR
- "DEFDIR"
- "PROGDIR\wads"
- "~\games\doom"
- "~\games\doomwads"
- "~\games\doomlegacy\wads"
- "\doomwads"
- "\games\doomwads"
- "\games\doom"
- "\Program Files\doomlegacy\wads"
- "PROGDIR" </nl>

  ### Windows Install Notes

  The search directories for Windows are not as extensive as other ports. If the legacy.wad and IWAD are installed within these directories it should be possible to execute Doom Legacy without having to switch to the executable first.

  If there is difficulty, it may be required to move files to a known location, or edit the doomdef.h file to customize a search directory. Support files, like wads, legacy.wad, autoexec.cfg, and config.cfg, need to be found by Doom Legacy and it is not reliable to look in the current directory for these. Users commonly would lose their config file because they had not set HOME, did not know where their config went, or Doom Legacy could not find a HOME to store config and savegames.

  Put your wad files in directory "\doomwads", or "\games\doomwads", or in the current directory. Doom Legacy will search all doomwaddir for the wad file. The environment variable DOOMWADDIR can be set in a batch file to specify a different wad directory. Other doom ports commonly used that environment variable to point to the doom wad directory.

  A "legacy" or "doomlegacy" directory will be created in your home directory for savegames and saved config files. This depends upon determining the HOME directory at run-time. This is commonly done with a UserProfile or HOME environment variable set at user login to the operating system.

  For Windows, Doom Legacy first looks for the HOME directory in the "HOME" environment variable, and then in the "UserProfile" environment variable.

  If HOME (or UserProfile), is not set by system login then it should be set by the user. Set the environment variable "HOME" in a batch file, or use the -home switch when starting Doom Legacy. If HOME is not set, Doom Legacy will try to find an alternate home directory. First it will try to find a user created "legacyhome" in the current directory. If that fails it will try to create "legacyhome" in the program directory.

  Overriding by using the -home and -config switches, examples:

  > doomlegacy -home c:\games\doomsave -game plutonia > doomlegacy -home c:\games\doomsave -config c:\games\plutconfig.cfg -game plutonia

  Use the verbose switch -v, and Doom Legacy will print to stderr the directory names that it used. On Win98 this becomes a file named stderr.txt. The use of directory names with spaces may fail.

  It is difficult to start a program under windows and set command line switches. Most of the settings that the launcher supported can now be set from menus and the console. However the -game, -file, and -config must be set from command line switches.

  Doomlegacy will invoke a Launcher window when it is started without switches. It will also invoke the Launcher window when the game selection results or iwad selection are invalid. The Launcher window provides input of the game switches, iwad, config, home, and doomwad directories.

  Another way to start Doom Legacy is to create shortcuts. These can be executed using a mouse. Specify in the shortcut the command line, and change the starting directory to where the doomlegacy program resides.

  Example shortcut for Doom Legacy with plutonia2 wad: Shortcut: dl_plut2 command: doomlegacy -game plutonia -file c:\games\pl2\PL2.WAD current directory: c:\games\legacydir

  Creating a batch file with the necessary commands is also an easy way to record a combination of switches. Run the batch file to start doomlegacy with the particular game and PWAD. In the following batch file examples, legacydir, homedir, configdir, and waddir stand for directories that you specify.

  DOOM2.BAT cd c:\legacydir\ doomlegacy -game doom2 DM8.BAT cd c:\legacydir\ doomlegacy -iwad waddir\doom2.wad -home c:\homedir\ -config c:\homedir\config8.cfg DM2MOD.BAT SET HOME=c:\games\home SET DOOMWADDIR=c:\games\wads cd c:\games\legacydir doomlegacy -game doom2 -file levl9.wad mod2.deh mod8.bex

  ## DOS

  The DOS install is not as capable as other ports. Because a binary download will not be available, it will have to be compiled from Doom Legacy Source.

  This will require a compiler.
  Development used MinGW, but Watcom, and Clang have been tested. The code does test for MS compilers, but their usage with a DOS compile is unknown. Only DOS_NATIVE compile is available.

  #### System Share Install

  System Share install is not available for DOS.

  #### Games Share Install

  Games Share install is not available for DOS. Use Games install.

  #### Games Install

  $ INSTAL games $ INSTAL games d:
  <nl>
- A hard drive letter or other prefix may be specified as the second parameter. It is used as a prefix on the games install dir.
- All executable, legacy.wad, and docs are installed to the games directory.
- There is a wads subdirectory, mostly for legacy specific wads.
- Other, generic wads directories, will also be searched. </nl>

      INSTALL_DIR = \games\legacy
      INSTALL_WADS = %INSTALL_DIR%\wads

  #### User Install

  $ INSTAL user $ INSTAL user my_doom_directory
  <nl>
- The user directory may be specified.
- The default user install directory is "games/legacy" in the user directory. </nl>

      INSTALL_DIR = \games\legacy
      INSTALL_WADS = %INSTALL_DIR%\wads

  #### Search directories in DOS

  To change, edit source file doomdef.h, and re-compile.
  Other directories can be added to doomdef.h, with up to 21 search directories.
  The tilde is converted to $HOME by Doom Legacy.
  Where PROGDIR is the program directory, and DEFDIR is the current directory.

  #### Search for legacy.wad:

  <nl>
- "PROGDIR"
- LEGACYWADDIR
- "PROGDIR\wads"
- wad search directory list </nl>

  #### Search order, IWAD:

  <nl>
- DOOMWADDIR
- "DEFDIR"
- "PROGDIR\wads"
- "~\games\doom"
- "~\games\doomwads"
- "~\games\doomlegacy\wads"
- "\doomwads"
- "\games\doomwads"
- "\games\doom"
- "PROGDIR" </nl>

  ### DOS Install Notes

  Put IWAD files in some of the directories in the search list.

  See the Windows install notes, as the situation is very much the same.

  A "legacy" directory will be created in your specified home directory for savegames and saved config files.

  Set the environment variable "HOME" in a batch file, or use the -home switch when starting Doom Legacy. If HOME is not set, Doom Legacy will try to find an alternate home directory. First it will try to find a user created "DL_HOME" in the current directory. If that fails it will try to create "DL_HOME" in the program directory.
  This behavior can be overridden by using the -home and -config switches.