Scripting - Chapter 9: Standardization

From PlayOnLinux
Jump to: navigation, search

Standardization, what is this thing?

To improve script readability, maintainability, debugging, and translation, scripts are standardized. This means that things need to be added or modified so that scripts will look and behave in a similar fashion.

Let us go over the details...

Make your script available under Mac OS X using PlayOnMac

It may be useful to clarify (for those who would not know) that PlayOnLinux and PlayOnMac are really the same software, sharing the same code. Only the name changes depending on the operating system. So, making your script available to PlayOnMac users can be very easy. You just have to check that your script runs fine under Mac OS X. Even if you don't have any Mac OS X at hand, for small and simple software one can expect that, if it works correctly under GNU/Linux, there's a 99% probability that it will also work under Mac OS X.

To make your script available under Mac OS X, check the box "PlayOnMac compatible" of the new script submission form of the PlayOnLinux website. Read more here:

Standardization; let's begin

First, we shall be introduced to several items regarding standardization in scripts.

The $TITLE variable

You should assign the variable $TITLE with the name of the script, and use it every time the name of the script is required.


#!/usr/bin/env playonlinux-bash
[ "$PLAYONLINUX" = "" ] && exit 0
source "$PLAYONLINUX/lib/sources"
TITLE="Mozilla Firefox" # Should be present in all your scripts
POL_SetupWindow_presentation "$TITLE" "Mozilla" "" "YourNickname" "MozillaFirefox"
POL_Shortcut "firefox.exe" "$TITLE"

Obviously, adapt it to the name of your script (that usually matches the name of the software it installs). The variable $TITLE is notably required for the use of PlayOnLinux's debugging system.

Use the $TITLE variable for window titles

To avoid confusing the user with disparate window titles, it is recommended to use the variable $TITLE as window title.


POL_SetupWindow_message "Message" "$TITLE"
POL_SetupWindow_browse "Message" "$TITLE"
POL_SetupWindow_wait "Message" "$TITLE"

The $PREFIX variable


#!/usr/bin/env playonlinux-bash
[ "$PLAYONLINUX" = "" ] && exit 0
source "$PLAYONLINUX/lib/sources"
TITLE="Mozilla Firefox"
POL_SetupWindow_presentation "$TITLE" "Mozilla" "" "YourNickname" "$PREFIX"
POL_Wine_SelectPrefix "$PREFIX"
POL_System_TmpCreate "$PREFIX"

Some informations about the script

It is recommended to provide some information near the beginning of the script, right after the #!/bin/bash line. Headers like this are standard practice in any script or source code, and should be applied as such.


#!/usr/bin/env playonlinux-bash
# Date : (Year-month-day hour-min)
# Last revision : (Year-month-day hour-min)
# Wine version used :
# Distribution used to test : Distribution
# Author : Your nickname
# PlayOnLinux : version of POL used to make the script
# Script licence : GPL3 recommended (2018)
# Program licence : License of the main software installed by the script


#!/usr/bin/env playonlinux-bash
# Date : (2011-11-19 06-39)
# Last revision : (2011-11-19 06-39)
# Wine version used : 1.3.4
# Distribution used to test : Ubuntu 10.04 LTS
# Author : Your nickname
# PlayOnLinux : 4.3.4
# Script licence : GPL3
# Program licence : Retail

Enable debugging

PlayOnLinux has a script debugging mode that must be enabled through a command. It is mandatory to enable it, even if you have no use for it; if some user experiences a problem with your script, it will allow him to sent a bug report to the PlayOnLinux website.



This command should be put right after the command POL_SetupWindow_Init.

Some more information

Random information that does not fit into previous chapters.

It is forbidden to use sudo

Commands sudo, su, gksudo, kdesu and similar are forbidden for the sake of security. However, if you really need sudo (for example to display hidden files from hybrid PC/MAC DVDs, using mount command), you can use the following command:


POL_Call POL_Function_RootCommand "command using sudo; exit"

Winetricks forbidden in scripts

Winetricks, or a similar script, is forbidden in PlayOnLinux scripts. Instead, you can use the very similar command POL_Call.


POL_Call Script


POL_Call POL_Install_vcrun6

The list of all the available scripts can be seen on this page.

Advanced Standardization

Setting the software categorie

Using the following command allow the GNU/Linux (freedesktop compatibles) to sort the icons among the menus.


POL_Shortcut "Space Colony.exe" "$TITLE" "" "" "Game;StrategyGame;"

POL_Shortcut "Photoshop.exe" "$TITLE" "" "" "Graphics;"

For details and more categories, read : Desktop Menu Specification: categories (see also the page Additional Categories).

Usage: POL_Shortcut [binary] [shortcut name] [playonlinux website icon] [argument] [categories]

Adding a changelog (history of changes made to the script)

If the script receive many updates, this can help the next developpers to know what was changed and why. Add this between the informations (top) and the script code.


# [MrBean] (2019-05-15 22-40)
#   Added some bugs.
# [Dadu042] (2019-05-10 20-36)
#   Initial writting.

Choosing the Wine version

When making your script, using the latest Wine version often spare time and bugs. However the Wine version you will put in the script is important, because older POL/POM versions might not support it.

This is why we recommend to chose the latest version supported by the most common POL/POM version currently packaged with GNU/Linux distributions.
Example: currently (july 2019), Ubuntu 18.04 (Long term support branch) has POL v4.2.12, it support Wine 3.0.3 maximum.

Scripts translation

We're almost done with scripts standardization. The only item left is script translations. This will be the topic of the next chapter.

Previous: Chapter 8: My First Real Script

Next: Chapter 10: Script Translation