Scripting - Chapter 9: Standardization
Contents
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.
Example:
#!/usr/bin/env playonlinux-bash [ "$PLAYONLINUX" = "" ] && exit 0 source "$PLAYONLINUX/lib/sources" TITLE="Mozilla Firefox" # Should be present in all your scripts POL_SetupWindow_Init ... POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "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.
Example:
POL_SetupWindow_message "Message" "$TITLE" POL_SetupWindow_browse "Message" "$TITLE" POL_SetupWindow_wait "Message" "$TITLE"
The $PREFIX variable
Example:
#!/usr/bin/env playonlinux-bash [ "$PLAYONLINUX" = "" ] && exit 0 source "$PLAYONLINUX/lib/sources" TITLE="Mozilla Firefox" PREFIX="MozillaFirefox" POL_SetupWindow_Init ... POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "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.
Syntax:
#!/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
Example:
#!/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.
Syntax:
POL_Debug_Init
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:
Syntax:
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.
Syntax:
POL_Call Script
Example:
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.
Example:
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).
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.
Example:
# CHANGELOG # [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 choose 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 packaged with GNU/Linux distributions. For 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
