love-release/modules.md

How to write love-release module ?

Introduction

What's the point anyway ? Well, you could do that if you wanted to support another platform, or maybe to set up your own build script if you want to use old or custom versions of LÖVE, or finally to add other directives at build time.

Read this example and take a look at the other modules. To create a new module, you have to create a file in the scripts directory, and then recompile love-release. If you wish to submit a new module, please also edit README.md and love-release.1

Variables

You have access to global variables. You can modify them freely, as a module is executed in a subshell.

• $PROJECT_DIR: absolute path to the directory where love-release was launched.

• $RELEASE_DIR: path the release directory. You should not assume the path will be absolute nor relative. To be sure, always do cd "$PROJECT_DIR" before using this variable.

• $LOVE_FILE: the name of the default LÖVE file. Always do cd "$RELEASE_DIR" before using this variable.

• $CACHE_DIR: absolute path to the cache directory of your module.

• $FILES: an array containing the list of files and directories to include in the zip. By default, it's FILE=( "." ).

• $EXCLUDE: an array containing the list of files and directories to exclude. By default, all the .file are excluded.

• $LOVE_VERSION: the LÖVE version your module should use. The three following variables are generated by the gen_version function.

  • $LOVE_VERSION_MAJOR,
  • $LOVE_VERSION_MINOR,
  • $LOVE_VERSION_REVISION.

• $TITLE: the game's title.

• $IDENTITY: the game's identity. You should generate it yourself if needed.

• $DESCRIPTION: the games's description.

• $GAME_VERSION: the game's version.

• $URL: the game's url.

• $AUTHOR: the game's author.

• $EMAIL: the author's email.

• $ICON: it can contain a directory path to a directory where icons are stored, or a direct path to the icon file. You should not assume the path will be absolute nor relative. To be sure, always do cd "$PROJECT_DIR" before using this variable.

Init

A module should always begin with the function init_module. It tests if the module should be executed or not, and reads the configuration file and the options. If the module should not be executed, then it will exit.

init_module takes three parameters:

• the pretty name of the module, for logging.
• the real name of the module. It must be the name of the script, and the name of the OS used in the configuration file.
• the option that will trigger your script.

For example, we could have init_module "Android" "android" "A".

Additional options

Declare the additional options your script will be using. Beware ! They are parsed by sed, so let them be simple strings at the beginning of the line.

Love-release uses GNU getopt. Short options are made of one character. Add them in the $OPTIONS variable. Long options can be added in the $LONG_OPTIONS variable, separated by a comma. Each option may be followed by one colon to indicate it has a required argument, and by two colons to indicate it has an optional argument.

OPTIONS="A"
LONG_OPTIONS="activity:,update"

Setup

Configuration

Configuration is loaded if a conf.lua file is present. You have nothing to do.

Additional options

If you have declared additional options, you have to read them. Reaching -- means that they are no more options to read.

while true; do
    case "$1" in
        --activity ) ACTIVITY="$2"; shift 2 ;;
        --update )   UPDATE=true; shift ;;
        -- )         break ;;
        * )          shift ;;
    esac
done

Dependencies

If your module has external dependencies, you should test if they are installed. You can use this snippet:

if ! command -v git > /dev/null 2>&1; then
    exit_module "deps" "git was not found."
fi

Script variables

If your module requires (by example) the $AUTHOR variable, you should test if it's empty. You can also test the validity of the variables.

LÖVE file

Modules scripts always start in $PROJECT_DIR. If you have moved, get back in !

Use create_love_file 9 to create the LÖVE file. It is created in $RELEASE_DIR. The function takes as parameter the level of compression to use.

Write your code

Read the title !

You can use the dump_var to print most of the script's variables for debugging purposes. You can also compare two LÖVE versions with the compare_version.

# Compare two LÖVE versions
## $1: First LÖVE version
## $2: comparison operator
##     "ge", "le", "gt" "lt"
##     ">=", "<=", ">", "<"
## $3: Second LÖVE version
## return: 0 - true, 1 - false
if compare_version "$LOVE_VERSION" '>=' '0.8.0'; then
    : # do something
fi

Exit the module

Exit the module with exit_module. You can also report an error with an identifier as first argument:

• execute: module could not be executed.
• binary: the LÖVE binaries could not be found or downloaded.
• options: errors in the options given to the script.
• version: the LÖVE version string is invalid.
• deps: unsatisfacted dependencies.
• undef|*: undefined error.