Scripting - Chapter 9: Standardization

From PlayOnLinux
Revision as of 15:03, 22 May 2019 by Dadu042 (talk | contribs) (Setting the software categorie)
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.

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;"

For details and more categories, read : Desktop Menu Specification: categories.

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