Home

renpy_desktop_generator.sh v2.2.3 Help:
A script to generate a desktop file for a given Ren'Py game according to the
freedesktop.org specification 1.1. The user may choose whether they want to
install the generated desktop file or place it in the current directory.

Syntax:
  This documentation uses the following syntax convention:
    [STRING]  Everything inside brackets is optional and can be left out for
              the pattern to match. This also applies to substrings.
    STRING... Everything in the command line argument STRING can be repeated an
              arbitrary amount of times - including not at all. Must be a
              separate command line argument for every repetition.
    STRING 1 | ... | STRING N
              At this position one of STRING 1 to STRING N is possible and
              expected.

Usage:
 renpy_desktop_generator.sh [OPTION...] [FILE...]

Operation:
 Finding the game directory:
  The script needs to know where the game directory is. To find it, the script
  will search the following places with the given priorities:
  1. With the highest priority the path to a game start script (usually called
     NAME.sh) will be used if given
  2. If that is not given, use the directory given as an argument (which may be
     the game directory intself or one of its subdirectories) to search for the
     game directory
  3. Then assume that the given icon file may be located in the game directory
     and use that
  4. If the GUI is activated (see ‘--gui’), use a game directory selection
     dialogue to let the user choose the correct directory
  5. In case that all the methods above fail, use the current working
     directory of the script to search for the game directory.
  (The paths used in method 1 to 3 use paths provided by the script by the user
   in arbitrary order. The type of the path will be determined automatically.
   To set the type explicitly the options listed in the ‘Start script, Icon and
   search directory settings’ section can be used. The order of evaluation
   mentioned above stays the same.)

  After the game directory is found, the script will search for the icon and
  the game script if they were not given explicitly by arguments.

 Installation defaults:
  The script tries to install the desktop file and the icon to the standardised
  directories and create any needed directories. The icon will be converted to
  PNG and saved as NAME.

  By default, the desktop file will not execute the game start script directly
  but will contain a script that tries to find the newest of all found possible
  game start scripts. For more details, see option ‘--current-version-search’.

 Potential errors and how to handle them:
 * If any of the given paths contain ‘unusual characters’ like new lines, a
   launcher may not behave as expected. In this case it may be best to create
   hard links to the files that do not contain these characters in their path.

 * For the current version search to work, the directory that contains the game
   script must also contain a Python script of the same name (NAME.py).

 * There may also be problems for the script if files end with one or more
   new line characters because these get stripped by most shells. If problems
   occur, the same methods as above may be used when possible.
   If the game name contains new lines and launchers misbehave, the option
   ‘--display-name’ can be used to force a better name.

 * This script expects ‘/tmp’ to be writeable. If it is not, the script can be
   executed as super user. This will change the default installation behaviour
   to install the game for all users. See ‘--[no-]install-all-users’.

 Recommendations:
  The only optional dependencies that should be installed regardless are the
  ImageMagick suite or FFmpeg/FFprobe to convert, extract install icons and
  `icns2png` to do the same with the Apple Icon Image files.
  Otherwise, the whole icon handling part of the script will not execute and
  the direct path to the icon will be used. The specification only supports the
  formats PNG, XPM and optionally SVG. If the icon has another format,
  launchers may not display them. Also, because the path will be absolute,
  reinstalling the game may lead to the icon not being found, even if the
  desktop file itself was installed.

 Some more specific behaviour is documented in the appropriate options.

Options:
 All options support long names and some also short names. Short options can be
 concatenated (e.g. ‘-iv’). If an option has an argument, it can be provided as
 an additional argument `-[-]KEY VALUE` or as one argument in `-[-]KEY=VALUE`
 format for both short and long options.
 Options and their arguments are mostly case-sensitive. Additionally, all
 options can also be set via variables at the start of the script or using the
 environment.
 The opposite effect of some options can be archived by inverting the case of a
 short option character or toggling the ‘no-’ prefix for long options.

 Installation settings:
  Determines whether and how the desktop file should be installed. If settings
  are interactive and not set, the script will ask what to do interactively.
  -i, --install
        Install the generated desktop file to the INSTALLATION_DIR
        (see --installation-dir) and install the found icon to ICON_DIR
        (see --icon-dir). {interactive default}
  -I, --no-install
        Place the generated desktop file in the current directory and place the
        icon(s) in the game or current version search directory.
  -u, --uninstall
        Uninstall a previously installed desktop file and icon file(s). This
        has priority over an installation and quits the script afterwards.
  -U, --no-uninstall
        Do not uninstall. {interactive default}
  -e, --remove-empty-dirs
        If empty directories are created while the icon file(s) are
        uninstalled, remove them too. {interactive default}
  -E, --no-remove-empty-dirs
        Do not remove empty directories.
  -a, --install-all-users
        Install the desktop file and icon file(s) system wide, instead of only
        for the current user. This affects the automatic determination of
        INSTALLATION_DIR and ICON_DIR if they are empty.
        This does not move the game directory so it and the version search
        directory should still be readable by all users.
        {default if executed as super user}
  -A, --no-install-all-users
        Only install the desktop file and icon file(s) for the current user.
        This affects the automatic determination of INSTALLATION_DIR and
        ICON_DIR if they are empty. {default if NOT executed as super user}

 Start script, Icon and search directory settings:
  Set the parameters that are otherwise determined by context if given as a
  non-option explicitly. These take priority over the non-explicit versions.
  The evaluation order still applies.
  -s FILE, --script=FILE
        Set the game start script. It is usually called NAME.sh and must be a
        valid POSIX shell script and contained in a Ren'Py game directory.
  -d DIR, --starting-dir=DIR
        Set the directory from which to start the search for the Ren'Py game
        directory.
  -c FILE, --icon=FILE
        The file to use for the icon. The script will try to check whether
        ImageMagick/FFmpeg can process the file if they are installed. To
        process the Apple Icon Image format, `icns2png` must be installed. If
        an Apple Icon Image format file should be found automatically, it must
        have the correct file extension `.icns`.

 Generation settings:
  -v, --current-version-search
        The generated desktop file will try to search for the newest installed
        version of the game (from the SEARCH_DIR). This may be a good option if
        the user installs a new version by unpacking the archive without
        ensuring that the path to the game start script stays the same.
        This may still not be fool proof in the case the name of the game
        (start script) changes, the change times of scripts do not reflect
        their versions or the user has two files NAME.sh and NAME.py in the
        same directory in the search space that do not belong to the game. It
        may also be relatively slow to find the script depending on how big the
        search space is.
        In these cases the user should re-run this script, use a direct path
        (see below) or update the ctime of the appropriate files using
        `touch`. [interactive default]
  -V, --no-current-version-search
        Use the direct path to the game start script in the desktop file.
  -S SEARCH_DIR, --current-version-search-dir=SEARCH_DIR
        Set the directory from which to search for the current version of the
        game. It is relative to the Ren'Py game directory so that arguments
        like three directories above the game directory (‘../../..’) are
        possible. If the value is empty, the directory defaults to the direct
        parent of the game directory (‘..’), so if all versions are unpacked to
        the same directory they should be found.
  -N STRING, --display-name=STRING
        Set a separate name for the desktop file (`Name` field in it) instead
        of trying to extract the configured name from the game files or using
        NAME if no name was found. This may be interesting if the game name
        contains unusual characters, is not descriptive or no name was found.
 -k WORD [WORD...], --[add-]keywords=[WORD[;WORD...]]
        Add given keywords to the `Keywords` field in the desktop file.
        This can be useful to add more search terms by which the game can be
        found in a launcher. By default, keywords will include the terms
        ‘entertainment’, ‘games’, ‘vn’, ‘renpy’ and NAME (unaffected by the
        configured name or ‘--display-name’). This option can be used multiple
        times, adding to already set keywords. Unusual characters like form
        feeds might irritate launchers.
        There are two syntaxes for passing keywords:
        Joint list (when using the `-[-]OPTION=ARGS` syntax):
          All keywords and the option name are written as one command line
          argument. Different keywords are separated by ‘;’s unless they are
          escaped with ‘\’. If a literal ‘\’ is meant, it must also be
          escaped with a ‘\’.
          E.g.: `-k='-one;-2;\;0\;;one;two;thr\;e;4;fi\\/e'`
        Separate arguments (when using the `-[-]OPTION [ARG...]` syntax):
          Each given argument represents a keyword. The first argument must be
          present and can start with a ‘-’. Subsequent arguments are parsed
          until an argument starts with ‘-’ (which will then be interpreted as
          the next option).
          To supply multiple keywords starting with ‘-’ this option can be
          specified multiple times. To end option parsing altogether ‘--’ can
          be used.
          No characters have to be escaped.
          E.g.: `-k -one -k -2 ';0;' one two 'thr;e' 4 'fi\/e' --next-option`
 -K WORD [WORD...], --set-keywords=[WORD[;WORD...]]
        Same as ‘--[add-]keywords’ but set the keywords to the given list
        instead of adding them. This can be useful to avoid the default
        keywords. An empty list will clear the keyword list. The NAME keyword
        will be added regardless unless ‘--no-name-keyword’ is given.
        Further keywords can be added with ‘--[add-]keywords’.
 -m, --name-keyword
        Use NAME as an additional keyword. {default}
 -M, --no-name-keyword
        Do not use NAME as a keyword.
 -p PREFIX, --vendor-prefix=PREFIX
        Set the vendor prefix. This is useful to prevent name conflicts and is
        used for the desktop file and installed icons. PREFIX defaults to
        ‘renpydeskgen’ if unset. An empty value can be used to disable the
        vendor prefix.

 Storage settings:
  Set where and which files are created. If the set location is not accessible
  by the user, this script will ask for the appropriate credentials.
  In that case the script may also be executed as super user.
  -O ICON_DIR, --icon-dir=ICON_DIR
        The directory that should be used to store the icon(s) when installing.
        This should be one of the standardised XDG icon directories, e.g.
        ‘$XDG_DATA_HOME/icons’ to be findable by launchers. If this value is
        empty, an appropriate directory will be chosen automatically.
  -o INSTALLATION_DIR, --installation-dir=INSTALLATION_DIR
        The directory that should be used to store the desktop file when
        installing. This should be one of the standardised XDG icon
        directories, e.g. ‘$XDG_DATA_HOME/applications’ to be findable by
        launchers. If this value is empty, an appropriate directory will be
        chosen automatically.
  -f, --create-default-icon-size
        The specification strongly recommends to at least install an icon of
        size 48×48. Create this icon if it is not already present and install
        it. What is actually done with the icon once it is created is affected
        by the setting of ‘--icon-size-not-existing-handling’. {default}
        (Mnemonic: <f>ourty-eight)
  -F, --no-create-default-icon-size
        Do not create a 48×48 icon. (Mnemonic: <F>ourty-eight)
  -P PROGRAM, --icon-handling-program PROGRAM
        Set the preferred program for handling the icons, i.e. converting,
        extracting and installing icons.
        PROGRAM can be one of the values ‘magick’ or ‘ffmpeg’. This defaults
        to ‘magick’ or ‘ffmpeg’ if they are installed and the value is empty.
  -t FILE, --theme-attribute-file=FILE
        The theme configuration file to work with and potentially update. If
        the user does not have the permissions to edit the file, they must
        provide the appropriate credentials.
        If this is not set, the first file in the order dictated by the
        specification will be used to search for the ‘hicolor’ configuration.
        In the case that no file is found or the file is invalid
        ‘--icon-size-not-existing-handling’ will default to ‘only-create’.
  -H METHOD, --icon-size-not-existing-handling=METHOD
        Set how to act if it is detected that an icon may not be recognised
        because it has dimensions that are not registered in the ‘hicolor’
        theme. METHOD can be one of the following values:
        C, closest-convert
            Find the closest matching size and convert the icon to that size if
            necessary.
        M, closest-move
            Find the closest matching size and pretend that the icon has that
            size without converting it. This may not be compatible with some
            launchers, so they may not display the icon correctly.
        S[[MIN,]MAX], create-new-scaled[=[MIN,]MAX]
            Register the icon as a new scaled file size with a size range of
            MIN to MAX and update the theme attribute file.
            MIN and MAX default to 1 and 1024 respectively if not given.
            The values MIN and MAX determine the sizes the icons in this
            directory are allowed to be scaled to.
            If the configuration is located in a system directory, additional
            authorisation may be required. If the change is not recognised by
            the launcher the user may try setting the theme configuration file
            manually with ‘--theme-attribute-file’ or try another METHOD.
        T[THRESHOLD], create-new-threshold[=THRESHOLD]
            Register the icon as a new threshold file size with a given
            THRESHOLD and update the theme attribute file.
            THRESHOLD defaults to 2 if not given.
            The value THRESHOLD determines the sizes icons in this directory
            are allowed to over or under the directory size.
            This method has the same requirements as ‘create-new-scaled’.
        F, create-new-fixed
            Register the icon a new file size with exact dimension and update
            the theme attribute file.
            This method has the same requirements as ‘create-new-scaled’.
        O, only-create
            Only create the appropriate directories without registering them in
            the theme. This is a lot faster because the theme attribute file
            does not have to be parsed but may result in the icon not being
            found.
            This is the fallback behaviour if the other METHODs fail.
        {default: ‘closest-convert’}
  -r METHOD, --icon-resize-method=METHOD
        Sets the method which is used by ‘--create-default-icon-size’ and
        ‘--icon-size-not-existing-handling=closest-convert’ to resize the
        icon(s).
        Either ImageMagick or FFmpeg will be used for the conversion. (See
        ‘--icon-handling-program’) Depending on the program used the results
        may be slightly different.
        METHOD can be one of the following values:
        l[anczos] | resize
            Resize the icon using Lanczos interpolation.
        a[verage] | scale | area | box
            Resize the icon by averaging or replacing the pixels when shrinking
            or enlarging the image respectively.
        n[earest-neighbo[u]r] | sample | nn | point
            Resize the icon by skipping over or finding the nearest neighbour
            of pixels when shrinking or enlarging the image respectively.
        c[ustom]:FUNCTION
            Set a custom resize filter/flag. FUNCTION is not checked by the
            script so misbehaviour by ImageMagick and FFmpeg may be possible.
            Possible values can be found here:
            * https://imagemagick.org/script/command-line-options.php#filter
            * https://ffmpeg.org/ffmpeg-scaler.html#sws_005fflags
        {default: ‘resize’}

 Icon settings:
  -C, --no-icon
        Do not use an icon. This option overwrites the ‘--icon’ option
        regardless of whether it was set implicitly or explicitly.
  --broad-icon-search
        Use the glob pattern ‘*icon*.*’ when searching for icons. This is very
        general and may match undesired results like ‘silicon-form.png’.
  --no-broad-icon-search
        Do not use ‘*icon*.*’ when searching. {default}
  -w, --download-fallback-icon
        Download a default icon if no icon was found in the game directory.
        The programs `wget` or `curl` must be installed to download the
        icon.
  -W, --no-download-fallback-icon
        Do not download a default icon, instead opting for using no icon at
        all. {default}
  --fallback-icon-url=URL
        The URL of the default icon to download from. It defaults to the
        foreground of the Android icon from RAPT.
        This does imply ‘--download-fallback-icon’.

 Interaction settings:
  Sets what happens with INSTALL, UNINSTALL, REMOVE DIRECTORIES and CURRENT
  VERSION SEARCH choices and how the user interacts with the script.
  --interactive
        Force interactiveness by clearing the values.
  --no[n]-interactive
        Force non-interactiveness by setting the defaults for all values. The
        switches ‘--[no-]install’, ‘--[no-]uninstall’,
        ‘--[no-]remove-empty-dirs’ and ‘--[no-]current-version-search’ can be
        used for a more fine-grain configuration.
  -y, --yes
        Assume ‘yes’ for all interactive prompts.
  -n, --no
        Assume ‘no’ for all interactive prompts.
  -g, --gui
        Explicitly enable a rudimentary GUI using `zenity`. If not explicitly
        enabled, the script will try to turn this setting on if it detects that
        it is not run from a terminal.
        In the case that a GUI is not available (because `zenity` is not
        installed or the GUI is disabled explicitly before execution by setting
        the defaults at the start of this script), the script will set some
        reasonable defaults for the interactive prompts to make running it
        still possible. This may still fail if the user has to authenticate to
        access some files.
  -G, --no-gui
        Explicitly disable the rudimentary GUI.

 Miscellaneous:
  -h, --help
        Print this help to `$PAGER` or to the GUI and exit.
  -Z, --version
        Print version information and exit.
  -l LEVEL, --log-level=LEVEL
        Possible values for LEVEL:
            q[uiet] | 0, e[rror] | 1, w[arning] | 2, i[nfo] | 3, d[ebug] | 4
        If the log level is ‘debug’, all file system changing operations will
        be verbose and code executed with `sudo` will be printed before
        execution. {default: ‘info’}
  -L LEVEL, --gui-log-level=LEVEL
        Set for which log LEVELs to create extra GUI dialogues. The GUI LEVEL
        has the same possible values than the console LEVEL and must not be
        bigger than it. {default: ‘warning’}
  -x, --log-system
        Also write logs to the system logs. This is the default when the script
        is NOT run from a terminal.
  -X, --no-log-system
        Do not write logs to the system logs. This is the default when the
        script is run from a terminal.
  --    Do not treat following arguments as options.