diff --git a/doc/02_installation.md b/doc/02_installation.md index 30b4a22b..83a36ecc 100644 --- a/doc/02_installation.md +++ b/doc/02_installation.md @@ -127,6 +127,13 @@ needs to be copied into the game data directory. The target directory is just *music/*, next to *baseq2/*. **Not** inside *baseq2/*. +### Alternate Startup Configuration + +Yamagi Quake II ships with an alternative startup config that overrides +some gloibal settings to saner defaults. To use is copy *stuff/yq2.cfg* +into the *baseq2/* directory. + + ## The Demo Version A free demo version of Quake II is available and supported by Yamagi @@ -202,7 +209,7 @@ system. The gamedata is searched at: - In *$HOME/.yq2* If you're a package maintainer, please look at our documentation at -https://github.com/yquake2/yquake2/blob/master/doc/packaging.md +https://github.com/yquake2/yquake2/blob/master/doc/05_packaging.md ## Compiling from source diff --git a/doc/05_packaging.md b/doc/05_packaging.md index 093bf127..7de3594a 100644 --- a/doc/05_packaging.md +++ b/doc/05_packaging.md @@ -1,66 +1,66 @@ # Notes for Package Maintainers -Our 7.00 release caused some trouble for package maintainers -(see https://github.com/yquake2/yquake2/issues/214), so we decided to finally -properly document how we think it should be done and what assumptions -Yamagi Quake II makes regarding binary locations etc. +This guide shows how Yamagi Quake II should be packaged and what +assumptions the games makes regarding binary and game data locations. -## Where you should put the executables +This guide uses the notation for unixoid platforms. Executables have no +file extensions and libraries are given with the *.so* extension. MacOS +and Windows behave exactly the same way, but with the platform specific +file extensions. -Yamagi Quake II expects all binaries (executables and libs) to be in the same directory -(or, in the case of game.so/.dll/dylib, in the mod-specific subdirectory). -So the binary directory should look somehow like this *(on Unix-like systems; -on Windows and OSX it's very similar but with different extensions: .dll or -.dylib instead of .so, and the executables have .exe file extension on Windows of course)*: +## The Executables + +Yamagi Quake II expects all binaries (executables and libraries) to be +in the same directory or, in the case of *game.so*, in the mod-specific +subdirectory. + +So the binary directory should look somehow like this: * /path/to/yamagi-quake2/ - - quake2 - - q2ded - - ref_gl1.so - - ref_gl3.so - - baseq2/ + * quake2 + * q2ded + * ref_gl1.so + * ref_gl3.so + * baseq2/ * game.so - - xatrix/ + * xatrix/ * game.so - - ... *(the same for other addons/mods)* + * ... (the same for other addons) -Yamagi Quake2 will get the directory the `quake2` executable is in from the system -and then look in that directory (and nowhere else!) for `ref_*.so`. -It will look for `game.so` there first, but if it's not found in the binary directory, -it will look for it in all directories that are also searched for game -data (SYSTEMDIR, basedir, $HOME/.yq2/). This is for better compatibility with mods that -might ship their own game.so. +Yamagi Quake2 will get the directory the `quake2` executable is in from +the system and then look in that directory (and nowhere else!) for the +`ref_*.so` renderer libraries. It will look for `game.so` there first, +but if it's not found in the binary directory, it will look for it in +all directories that are also searched for game data. This is for +better compatibility with mods that might ship their own game.so. -You can **just symlink the executables to a directory in your $PATH**, like /usr/bin/. -(*Except on OpenBSD, which does not provide a way to get the executable directory, - there you'll need a shellscript that first does a `cd /path/to/yamagi-quake2/` and - then executes `./quake2`*) +You can **just symlink the executables to a directory into the $PATH**, +like */usr/bin/*. There's one exception to this rule: OpenBSD does not +provide a way to get the executable path, so a wrapper script is needed. + +We want all binaries to be in the same directory to ensure that people +don't accidentally update only parts of their Yamagi Quake II +installation, so they'd end up with a new quake2 executable and old +renderer libraries (`ref_*.so`) and report weird bugs. -We want all binaries to be in the same directory to ensure that people don't accidentally -update only parts of their Yamagi Quake II installtion, so they'd end up with a new -quake2 executable and old render libraries (`ref_*.so`) and report weird bugs. ## The SYSTEMWIDE and SYSTEMDIR options -The Makefile allows you to enable the `SYSTEMWIDE` feature (`WITH_SYSTEMWIDE=yes`) and -lets you specify the directory that will be used (`SYSTEMDIR`, `WITH_SYSTEMDIR=/your/custom/path/`). -If you don't set SYSTEMDIR, it defaults to `/usr/share/games/quake2`, which is what debian uses. +The Makefile allows to enable the *SYSTEMWIDE* feature to force Yamagi +Quake II to search the game data in an system specific directory. That +directory can be given in the Makefile. If no directory is given the +game defaults to */usr/share/games/quake2/* which should be correct for +most Linux distributions. -The `SYSTEMDIR` was meant to contain just the game data, *not* the binaries, and allows -several Quake2 source ports to share the same game data. -Unfortunately, we didn't document this assumption, so some packages used it for both binaries -and data, just binaries or - which causes most trouble - only for the game libs, but not the -executables. The latter case doesn't work anymore since we (re)introduced the render libs, -as they need to be located next to the executable, and if the executable is in /usr/bin/ you -don't want to put libs next to it. +The `SYSTEMDIR` is meant to contain only the game data and *not* the +binaries. It allows several Quake2 source ports to share the same game +data. -Anyway: If you use `SYSTEMWIDE`/`SYSTEMDIR`, please use it for game data. -You *can* also put the binaries in there, but in that case please put all of them -(including executables) in there, as explained above. ## Alternative startup config -Yamagi Quake II has support for an alternative startup config. -It may be a good idea to install it, since it sets some global options to sane defaults. -Copy yq2.cfg to the baseq2/ subdirectory in the gamedata (`SYSTEMDIR`) directory. +Yamagi Quake II has support for an alternative startup config. That +config overrides some global values with sane defaults. It may be a good +idea to install it. Copy yq2.cfg to the baseq2/ subdirectory in the +gamedata directory.