yquake2
/
yquake2remaster
mirror of https://github.com/yquake2/yquake2remaster.git
0
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Some clarifications, typo and grammar fixes to the documentation. 

Make some things clearer and fix some small miss informations, overhaul
the timing guide. While at it fix typos and grammar mistakes.
This commit is contained in:
Yamagi Burmeister 2019-04-03 11:33:20 +02:00
parent 3b296c43a0
commit 4f20ac97d1
5 changed files with 95 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
doc/01_index.md
View File

@ -9,10 +9,10 @@ Some general hints:
* No matter what's the current keyboard layout or on which platform the * No matter what's the current keyboard layout or on which platform the
game is running, the console is always opened and closed by pressing game is running, the console is always opened and closed by pressing
**Left Shift + Escape**. **Left Shift + Escape**.
* Yamagi Quake II saves its configuration, savegames and screenshots * Yamagi Quake II saves its configuration, savegames and screenshots to
to *~/.yq2* (unixoid platforms) or *My Documents\YamagiQ2* (Windows). *~/.yq2/* (unixoid platforms) or *My Documents\YamagiQ2\* (Windows).
If Yamagi Quake II is started with the `-portable` switch all data If Yamagi Quake II is started with the `-portable` switch all data is
is saved in the same directory as the executables. saved in the same directory as the executables.
The documentation is split into several documents: The documentation is split into several documents:

27
doc/02_installation.md
View File

@ -1,8 +1,7 @@
# Installation # Installation
This guide shows how to install Yamagi Quake II from scratch. All This guide shows how to install Yamagi Quake II from scratch. All fully
fully supported platforms and both the full version and the demo supported platforms, both the full and the demo version are covered.
version are covered.
## The Full Version ## The Full Version
@ -16,7 +15,7 @@ Over the years Quake II was distributed in a myriad of ways:
* etc. * etc.
Yamagi Quake II is compatible with all of these versions. While some of Yamagi Quake II is compatible with all of these versions. While some of
these versions come with all patches applied it's highly recommended to these versions come with all patches applied, it's highly recommended to
follow this guide step by step and to reapply the patch by hand. Not all follow this guide step by step and to reapply the patch by hand. Not all
distributors patched the game correctly, leading to serve problems like distributors patched the game correctly, leading to serve problems like
missing assets or even crashes. missing assets or even crashes.
@ -130,7 +129,7 @@ just *music/*, next to *baseq2/*. **Not** inside *baseq2/*.
### Alternate Startup Configuration ### Alternate Startup Configuration
Yamagi Quake II ships with an alternative startup config that overrides Yamagi Quake II ships with an alternative startup config that overrides
some gloibal settings to saner defaults. To use is copy *stuff/yq2.cfg* some global settings to saner defaults. To use is copy *stuff/yq2.cfg*
into the *baseq2/* directory. into the *baseq2/* directory.
@ -208,8 +207,9 @@ system. The gamedata is searched at:
commandline argument. commandline argument.
- In *$HOME/.yq2* - In *$HOME/.yq2*
If you're a package maintainer, please look at our documentation at If you're a package maintainer, please look at our packaging guide at
the [Packaging Guide](05_packaging.md) the [Packaging Guide](05_packaging.md).
## Compiling from source ## Compiling from source
@ -220,7 +220,7 @@ To compile Yamagi Quake II from source the following dependencies
* A LibGL implementation with system headers. * A LibGL implementation with system headers.
* An OpenAL implementation, *openal-soft* is highly recommended. * An OpenAL implementation, *openal-soft* is highly recommended.
* SDL 2.0. * SDL 2.0.
* libcurl * libcurl.
While Yamagi Quake II ships with an CMakeFile.txt using the GNU Makefile While Yamagi Quake II ships with an CMakeFile.txt using the GNU Makefile
for release builds is recommended. The GNU Makefile offers more options for release builds is recommended. The GNU Makefile offers more options
@ -233,9 +233,10 @@ On Windows a MinGW environment is needed. A preconfigured environment
with all necessary dependencies and compatibles compilers can be found with all necessary dependencies and compatibles compilers can be found
at: https://deponie.yamagi.org/quake2/windows/build/ at: https://deponie.yamagi.org/quake2/windows/build/
The environment must be extracted into *C:\MSYS2\* (other directory will The environment must be extracted into *C:\MSYS2\*. Other directores
likely work but are unsupported). Either the 32 bit version can be will likely work, but are unsupported. So don't complain if you
started through *C:\MSYS2\msys32.exe* or the 64 bit version through experience problems. Either the 32 bit version can be started through
*C:\MSYS2\msys32.exe* or the 64 bit version through
*C:\MSYS2\msys64.exe*. *C:\MSYS2\msys64.exe*.
At this time Yamagi Quake II can't be compiled with Microsoft Visual At this time Yamagi Quake II can't be compiled with Microsoft Visual
@ -252,7 +253,7 @@ The build dependencies can be installed with:
* On MacOS the dependencies can be installed with Homebrew (from * On MacOS the dependencies can be installed with Homebrew (from
https://brew.sh): `brew install sdl2 openal-soft` https://brew.sh): `brew install sdl2 openal-soft`
Other distributions or platforms often have package names similar to the Other distributions or platforms often have package named similar to the
Debian or FreeBSD packages. Debian or FreeBSD packages.
@ -261,7 +262,7 @@ Debian or FreeBSD packages.
Download the latest release from https://www.yamagi.org/quake2 or clone Download the latest release from https://www.yamagi.org/quake2 or clone
the source from https://github.com/yquake2/yquake2.git, change into the the source from https://github.com/yquake2/yquake2.git, change into the
*yquake2/* source directory and type *make* (Linux, MacOS and Windows) *yquake2/* source directory and type *make* (Linux, MacOS and Windows)
or *gmake* (FreeBSD). After the build finished copy everything from the or *gmake* (FreeBSD). After the build finished, copy everything from the
*release/* directory to the Yamagi Quake II installation directory. *release/* directory to the Yamagi Quake II installation directory.
For the addons download or clone their source, change into the source For the addons download or clone their source, change into the source

95
doc/03_configuration.md
View File

@ -11,23 +11,23 @@ with the defaults and the options that can be set through the menu.
Yamagi Quake II ships with 3 renderers: Yamagi Quake II ships with 3 renderers:
* The **OpenGL 3.2** renderer: This renderer was developed for the needs * The **OpenGL 3.2** renderer: This renderer was developed for the needs
of modern hardware and is usually the best choice for OpenGL 3.2 of modern graphics hardware and is usually the best choice for OpenGL
capable graphics cards. It provides a very detailed look and feel, 3.2 capable graphics cards. It provides a very detailed look and feel,
matching the dark and dirty atmosphere on Stroggos. The texturing matching the dark and dirty atmosphere on Stroggos. The texturing
renderer of the OpenGL 3.2 renderer looks mostly the same on all GPU renderer looks mostly the same on all GPU drivers. Depending on the
drivers. The default lighting may be too bright or too dark, it can be display the default lighting may be too bright or too dark, it can be
adjusted through the menu or through the *vid_gamma* cvar. adjusted through the menu or through the *vid_gamma* cvar.
* The **OpenGL 1.4** renderer: This is a slightly enhanced version of * The **OpenGL 1.4** renderer: This is a slightly enhanced version of
the original OpenGL renderer shipped in 1997 with Quake II. It's the original OpenGL renderer shipped in 1997 with the retail release.
provided for older graphics cards, not able to run the OpenGL 3.2 It's provided for older graphics cards, not able to run the OpenGL 3.2
renderer. The OpenGL 1.4 renderer has some limitations. The look and renderer. The OpenGL 1.4 renderer has some limitations. The look and
feel is highly dependent on the GPU driver and the platforms OpenGL feel is highly dependent on the GPU driver and the platforms OpenGL
implementation, especially the texture rendering may vary to a wide implementation, especially the texture rendering may vary to a wide
margin. The global lighting may not be rendered correctly, especially margin. The global lighting may not be rendered correctly, especially
liquids may be too dark or too bright. liquids may be too dark or too bright.
* The **Software** renderer: Shipped for historical reasons only. * The **Software** renderer: Shipped for historical reasons only.
Setting the OpenGL 3.2 renderer to match the software renderers looks Setting the OpenGL 3.2 renderer to match the software renderers look
and feel is often the better choice since it's faster and provides and feel is often the better choice, since it's faster and provides
colored lighting. The software renderer may show some rendering errors colored lighting. The software renderer may show some rendering errors
on widescreen resolutions. on widescreen resolutions.
@ -37,15 +37,15 @@ Yamagi Quake II ships with 3 renderers:
Yamagi Quake II ships with 2 sound system: Yamagi Quake II ships with 2 sound system:
* The **OpenAL** sound system: This is the default and highly * The **OpenAL** sound system: This is the default and highly
recommended. It provides full surround sound support and even HRTF. recommended. It provides full surround sound support and even HRTF for
But also the plain stereo playback is much better then in the original headphones. But also the plain stereo playback is much better than in
sound system. The setup is done mostly through OpenAL, have a look at the original sound system. The setup is done mostly through OpenAL,
the documentation of your OpenAL library. have a look at the documentation of your OpenAL library.
* The **SDL** sound system: This is the classic sound system, providing * The **SDL** sound system: This is the classic sound system, providing
an experience like the original client. Set `s_openal` to `0` and an experience like the original client. Set `s_openal` to `0` and
execute an `snd_restart` to activate it. The classic sound system execute an `snd_restart` to activate it. The classic sound system may
may be problematic on modern systems like Windows 10 or Linux with be somewhat problematic on modern systems like Windows 10 or Linux
Pulseaudio. with Pulseaudio.
## Tuning for Precise Timings ## Tuning for Precise Timings
@ -62,9 +62,9 @@ network protocol and the whole look and feel depends on them. We can
just try work around them. just try work around them.
Additionally modern high resolution LCD displays are much more prone to Additionally modern high resolution LCD displays are much more prone to
tearing and missed frames then the low resolution CRT displays of the tearing and missed frames than the low resolution CRT displays of the
1990th. This is a big problem because precise timings and keeping the late 1990th. This is a big problem, because precise timings and keeping
frame rate constant are at least partly mutual exclusive. So players the frame rate constant are at least partly mutual exclusive. So players
have the choice: have the choice:
* Keep an accurate frame rate, rendering exactly as many frames as the * Keep an accurate frame rate, rendering exactly as many frames as the
@ -89,27 +89,28 @@ the GPU driver and the preferences of the player.
You'll never get precise timing and tearing- and / or micro stuttering You'll never get precise timing and tearing- and / or micro stuttering
free gameplay with busy waits switched off! free gameplay with busy waits switched off!
* `r_vsync` can be set to `0`. Enabling the vertical synchronization * `r_vsync` can be set to `0`. Enabling the vertical synchronization
allows the GPU driver to wait for the display, thus stealing time from allows the GPU driver to wait for the display, thus "stealing" time
Yamagi Quake II. This stolen time is missing to the internal time from Yamagi Quake II. This stolen time may add some variance to the
accounting, while Yamagi Quake II tries to determine how much time was internal timing. Disabling vertical synchronization will always cause
lost that's always an imprecise guess. Disabling vertical tearing!
synchronization will always cause tearing! * `cl_maxfps` must be set to a value lower than the renderer frame rate.
* `cl_maxfps` must be set to a value lower than `vid_maxfps`. The margin With `r_vsync` set to 1 that's the display refresh rate and otherwise
between the two values should be at least 3 frames per second, better the value of `vid_maxfps`. Yamagi Quake II enforces this restriction
5 frames per second. Yamagi Quake II internally enforces a margin of with an margin of 5%. For example, if `r_vsync` is set to 1 on an 60hz
5%. If `cl_maxfps` is set too high (above 90) the good old 125hz bug display 60 * 0.95 = 57 FPS. if `cl_maxfps` is set too high (above 90)
will trigger and the physics will be off. That may be desired. the famous 125hz bug will trigger and the physics will be off. That
may be desired.
* `vid_displayrefreshrate` must be set to the framerate of the display. * `vid_displayrefreshrate` must be set to the framerate of the display.
The default is `-1` which means autodetect. In most cases that's okay, The default is `-1` which means autodetect. In most cases that's okay,
but for precise timings it's a good idea to override the autodetected but for precise timings it's a good idea to override the autodetected
value and set the display refresh rate by hand. The displays EDID info value and set the display refresh rate by hand. The displays EDID info
or the GPU driver may be lying. Only full numbers can be given. If or the GPU driver may be lying. Only full numbers can be given, e.g.
round up there's a risk for imprecise timing. When round down the risk 59 or 60 for a 59.95hz display. If round up there's a small risk for
if micro stuttering increases. imprecise timing. If round down micro stuttering may occure.
* When running with vertical synchronisation enabled `vid_maxfps` can be * When running with vertical synchronisation enabled, `vid_maxfps` can
set to any value higher then the display refresh rate. If the vertical be set to any value higher than the display refresh rate. If the
synchronisation is disabled `vid_maxfps` should be set to the desired vertical synchronisation is disabled `vid_maxfps` should be set to the
target frame rate. desired target frame rate.
Putting it all together we come up with three so to say standard Putting it all together we come up with three so to say standard
configurations that can be used as a baseline for experiments: configurations that can be used as a baseline for experiments:
@ -135,15 +136,15 @@ configurations that can be used as a baseline for experiments:
And there's always the option to disable the asynchronous client all And there's always the option to disable the asynchronous client all
together by setting `cl_async` to `1`. In that case `cl_maxfps` and together by setting `cl_async` to `1`. In that case `cl_maxfps` and
`vid_maxfps` are tight together, like in the original Quake II release `vid_maxfps` are tied together, just like with the original client each
each renderframe is a clientframe. With that both precise timings and renderframe is also a clientframe. With that both precise timings and
tearing / micro stuttering free rendering can be archieved by setting tearing / micro stuttering free rendering can be archieved by setting
`cl_maxfps` to a value higher then the displays refresh rate and `cl_maxfps` to a value higher then the displays refresh rate and
activating the vertical syncrhonization by setting `r_vsync` to `1`. activating the vertical synrchonization by setting `r_vsync` to `1`.
But if `cl_maxfps` is set above about 90 frames per second the 125hz But if `cl_maxfps` is set too high (about 90) second the 125hz bug will
bug will trigger and the physics will be off. Additionally it will trigger and the physics will be off. Additionally it will flood servers
flood servers with packages, at least one package per frame. That may with packages, at least one package per frame. That may be considered
be considered abuse. abuse.
## Getting a classic look and feel ## Getting a classic look and feel
@ -216,15 +217,15 @@ support colored lighting.
General cvars: General cvars:
* `cl_lights` set to `0` disables the dynamic lights. * `cl_lights` set to `0` disables the dynamic lightning.
* `gl_texturemode` set to `GL_NEAREST_MIPMAP_LINEAR` disabled the * `gl_texturemode` set to `GL_NEAREST_MIPMAP_LINEAR` disables the
texture filtering, giving a nice pixel look. texture filtering, giving a classic pixel look.
The OpenGL 1.4 renderer: The OpenGL 1.4 renderer:
* `gl1_pointparameters`: When set to `0` the particles are rendered as * `gl1_pointparameters`: When set to `0` the particles are rendered as
squares. May be already the case if the GPU driver doesn't support blurry octagon. May be already the case if the GPU driver doesn't
point parameters. support point parameters.
The OpenGL 3.2 renderer: The OpenGL 3.2 renderer:

48
doc/04_cvarlist.md
View File

@ -17,7 +17,7 @@ have been renamed. The prefixes are:
* `vid_`: Video backend. * `vid_`: Video backend.
All cvars may be given at command line trough `+set cvar value` or typed All cvars may be given at command line trough `+set cvar value` or typed
into the console. The console can be opended with *shift-esc*. into the console. The console can be opended with *Left Shift + Esc*.
## Command line arguments ## Command line arguments
@ -41,7 +41,7 @@ it's `+set busywait 0` (setting the `busywait` cvar) and `-portable`
* **busywait**: By default this is set to `1`. causing Quake II to spin * **busywait**: By default this is set to `1`. causing Quake II to spin
in a very tight loop until it's time to process the next frame. This in a very tight loop until it's time to process the next frame. This
is a very accurate way to determine the internal timing but comes with is a very accurate way to determine the internal timing, but comes with
a relatively high CPU usage. If set to `0` Quake II lays itself to a relatively high CPU usage. If set to `0` Quake II lays itself to
sleep and tells the operating system to send a wakeup signal when it's sleep and tells the operating system to send a wakeup signal when it's
time for the next frame. The later is more CPU friendly but rather time for the next frame. The later is more CPU friendly but rather
@ -58,10 +58,13 @@ it's `+set busywait 0` (setting the `busywait` cvar) and `-portable`
* In case that the vsync is active, *vid_maxfps* must not be lower * In case that the vsync is active, *vid_maxfps* must not be lower
than the display refresh rate. than the display refresh rate.
Both contraints are enforced.
If *cl_async* is set to `0` *vid_maxfps* is the same as *cl_maxfps*, If *cl_async* is set to `0` *vid_maxfps* is the same as *cl_maxfps*,
use *cl_maxfps* to set the framerate. use *cl_maxfps* to set the framerate.
* **cl_showfps**: Shows the framecounter. * **cl_showfps**: Shows the framecounter. Set to `2` for more and to
`3` for even more informations.
* **in_grab**: Defines how the mouse is grabbed by Yamagi Quake IIs * **in_grab**: Defines how the mouse is grabbed by Yamagi Quake IIs
window. If set to `0` the mouse is never grabbed and if set to `1` window. If set to `0` the mouse is never grabbed and if set to `1`
@ -92,15 +95,15 @@ it's `+set busywait 0` (setting the `busywait` cvar) and `-portable`
* **s_openal**: Use OpenAL for sound playback. This is enabled by * **s_openal**: Use OpenAL for sound playback. This is enabled by
default. OpenAL gives a huge quality boost over the classic sound default. OpenAL gives a huge quality boost over the classic sound
system and supports surround speakers and HRTF. system and supports surround speakers and HRTF for headphones. OpenAL
is much more reliable than the classic sound system, especially on
modern systems like Windows 10 or Linux with PulseAudio.
* **s_underwater**: Dampen sounds if submerged. Enabled by default. * **s_underwater**: Dampen sounds if submerged. Enabled by default.
## Graphics (all renderers) ## Graphics (all renderers)
* Most old `r_*` cvars, but renamed to `gl_*`
* **vid_displayrefreshrate**: Sets the displays refresh rate. The * **vid_displayrefreshrate**: Sets the displays refresh rate. The
default `-1` let the game determine the refresh rate automatically. default `-1` let the game determine the refresh rate automatically.
Often the default setting is okay, but some graphics drivers report Often the default setting is okay, but some graphics drivers report
@ -130,10 +133,9 @@ it's `+set busywait 0` (setting the `busywait` cvar) and `-portable`
* **horplus**: If set to 1 (the default) the horplus algorithm is used * **horplus**: If set to 1 (the default) the horplus algorithm is used
to calculate an optimal horizontal and vertical field of view, to calculate an optimal horizontal and vertical field of view,
independent of the window or screen aspect ratio or resolution. If independent of the window or screen aspect ratio or resolution.
enabled *fov* is forced to `90`.
* **vid_gamma**: The value used for gamma correction. Higher value looks * **vid_gamma**: The value used for gamma correction. Higher values look
brighter. The OpenGL 1.4 and software renderers use "Hardware Gamma", brighter. The OpenGL 1.4 and software renderers use "Hardware Gamma",
setting the Gamma of the whole screen to this value in realtime setting the Gamma of the whole screen to this value in realtime
(except on MacOS where it's applied to textures on load and thus needs (except on MacOS where it's applied to textures on load and thus needs
@ -146,7 +148,8 @@ it's `+set busywait 0` (setting the `busywait` cvar) and `-portable`
crosshair. The value given is the scale factor, a factor of `1` means crosshair. The value given is the scale factor, a factor of `1` means
no scaling. Values greater `1` make the objects bigger, values lower 1 no scaling. Values greater `1` make the objects bigger, values lower 1
smaller. The special value `-1` (default) sets the optimal scaling smaller. The special value `-1` (default) sets the optimal scaling
factor for the current resolution. factor for the current resolution. All cvars are set through the
scaling slider in the video menu.
* **r_customheight** / **r_customwidth**: Specifies a custom resolution, * **r_customheight** / **r_customwidth**: Specifies a custom resolution,
the windows will be *r_customheight* pixels high and *r_customwidth* the windows will be *r_customheight* pixels high and *r_customwidth*
@ -160,8 +163,8 @@ it's `+set busywait 0` (setting the `busywait` cvar) and `-portable`
`cl_maxfps` is used as maximum framerate. See `cl_async` description `cl_maxfps` is used as maximum framerate. See `cl_async` description
above for more information. *Note* that vsync (`r_vsync`) also above for more information. *Note* that vsync (`r_vsync`) also
restricts the framerate to the monitor refresh rate, so if vsync is restricts the framerate to the monitor refresh rate, so if vsync is
enabled, the game won't render more than 60fps on most displays (or enabled, the game won't render more than frame than the display can
120 on a 120hz display etc). show.
* **r_vsync**: Enables the vsync: frames are synchronized with * **r_vsync**: Enables the vsync: frames are synchronized with
display refresh rate, should (but doesn't always) prevent tearing. display refresh rate, should (but doesn't always) prevent tearing.
@ -194,25 +197,24 @@ it's `+set busywait 0` (setting the `busywait` cvar) and `-portable`
* **gl_zfix**: Sometimes two or even more surfaces overlap and flicker. * **gl_zfix**: Sometimes two or even more surfaces overlap and flicker.
If this cvar is set to `1` the renderer inserts a small gap between If this cvar is set to `1` the renderer inserts a small gap between
the overlapping surfaces to mitigate the flickering. This may lead to the overlapping surfaces to mitigate the flickering. This may make
small render errors. things better or worse, depending on the map.
## Graphics (OpenGL 1.4 only) ## Graphics (OpenGL 1.4 only)
* **gl1_intensity**: Sets the color intensity used for 3D rendering. * **gl1_intensity**: Sets the color intensity. Must be a floating point
Must be a floating point value, at least `1.0` - default is `2.0`. value, at least `1.0` - default is `2.0`. Applied when textures are
Applied when textures are loaded, so it needs a `vid_restart`! loaded, so it needs a `vid_restart`.
* **gl1_overbrightbits**: Enables overbright bits, brightness scaling of * **gl1_overbrightbits**: Enables overbright bits, brightness scaling of
lightmaps and models. Higher values make shadows less dark. Possible lightmaps and models. Higher values make shadows less dark. Possible
values are `0` (no overbright bits), `1` (correct lighting for water), values are `0` (no overbright bits), `1` (more correct lighting for
`2` (scale by factor 2) and `3` (scale by factor 3). Applied in water), `2` (scale by factor 2) and `3` (scale by factor 3). Applied
realtime, does not need `vid_restart`. in realtime, does not need `vid_restart`.
* **gl1_stencilshadow**: If `gl_shadows` is set to `1`, this makes them * **gl1_stencilshadow**: If `gl_shadows` is set to `1`, this makes them
look a bit better (no flickering) by using the stencil buffer. (This look a bit better (no flickering) by using the stencil buffer.
is always done in OpenGL 3.2, so not configurable there)
## Graphics (OpenGL 3.2 only) ## Graphics (OpenGL 3.2 only)
@ -226,7 +228,7 @@ it's `+set busywait 0` (setting the `busywait` cvar) and `-portable`
Similar to OpenGL 1.4 `gl1_intensity`, but more flexible: can be any Similar to OpenGL 1.4 `gl1_intensity`, but more flexible: can be any
value between 0.0 (completely dark) and 256.0 (very bright). Good value between 0.0 (completely dark) and 256.0 (very bright). Good
values are between `1.0` and `2.0`, default is `1.5`. Applied in values are between `1.0` and `2.0`, default is `1.5`. Applied in
realtime via shader, so it does *not* need a `vid_restart`. realtime via shader, so it does not need a `vid_restart`.
* **gl3_intensity_2D**: The same for 2D rendering (HUD, menu, console, * **gl3_intensity_2D**: The same for 2D rendering (HUD, menu, console,
videos) videos)

2
doc/05_packaging.md
View File

@ -35,7 +35,7 @@ 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 all directories that are also searched for game data. This is for
better compatibility with mods that might ship their own game.so. better compatibility with mods that might ship their own game.so.
You can **just symlink the executables to a directory into the $PATH**, You can **just symlink the executables to a directory in the $PATH**,
like */usr/bin/*. There's one exception to this rule: OpenBSD does not 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. provide a way to get the executable path, so a wrapper script is needed.