Rewrite example.sh to modules.md

Makefile

@@ -35,7 +35,7 @@ install:
 	install -m 0755 '$(BUILD_DIR)/love-release' '$(BINARY_DIR)'
 	install -m 0755 -d '$(INSTALL_DIR)' '$(INSTALL_DIR)/scripts' '$(COMPLETION_DIR)'
 	install -m 0755 scripts/* '$(INSTALL_DIR)/scripts'
-	install -m 0644 -t '$(INSTALL_DIR)' README.md conf.lua example.sh
+	install -m 0644 -t '$(INSTALL_DIR)' README.md conf.lua modules.md
 	install -m 0644 '$(BUILD_DIR)/completion.sh' '$(COMPLETION_DIR)/love-release'
 	install -m 0644 '$(BUILD_DIR)/love-release.1.gz' '$(MANPAGE_DIR)'
 

README.md

@@ -163,7 +163,7 @@ with eventual underscores (i.e. [a-zA-Z0-9\_]), otherwise you'll get errors.
 The script is modular.
 Each different platform is handled by a subscript stored in `scripts`.
 If you’d like to add the support of another platform,
-or write your own build script, see `scripts/example.sh`.
+or write your own build script, see `modules.md`.
 
 #### ICONS
 The script doesn’t yet handle the process of creating icons,

example.sh

@@ -1,106 +0,0 @@
-# Example
-
-# This example script should show you how to write a module for love-release.
-
-# 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'd want to use old or custom versions of love,
-# 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 this directory,
-# and to edit the main love-release script.
-# If you wish to submit a new module, please also edit README.md and love-release.1
-# You could add configuration options in config.ini too,
-# but the name of the section must be the same as the name of the script.
-
-
-# Love-release script
-
-## 1. Register your module
-# To register your platforms scripts, you have to choose a command name that will trigger your script.
-# It must be followed by:
-# - a semicolon ";" if it doesn't require an argument
-# - a dot "." if it has an optional argument
-# - a colon ":" if it requires an argument
-# If you need options that might conflict by their names with already defined options, please prefix them.
-# If you want automatic completion to be available, add them to completion.sh
-SCRIPT_ARGS="q; wer: ty. uiop $SCRIPT_ARGS"
-
-# If some options require a file or a directory as argument,
-# and this file should be excluded by zip, add the option.
-EXCLUDE_OPTIONS=("wer")
-EXCLUDE_CONFIG=("INI__q__wer")
-
-## 2. Add a short summary of your module
-SHORT_HELP=" -q    Create an Example application"
-
-## 3. Source your script at the end of the file in the getoptex loop
-while getoptex "$SCRIPT_ARGS" "$@"
-do
-    if [ "$OPTOPT" = "q" ]; then
-        source "$PLATFORMS_DIR"/example.sh
-    fi
-done
-
-
-# Module script
-
-## 0. Theses variables are available:
-## $MAIN_CACHE_DIR  - if you need to cache something independant from love version
-## $CACHE_DIR       - if you need to cache something dependant from love version
-## $PROJECT_FILES   - if empty, means *
-## $EXCLUDE_FILES   - add files to be excluded by zip.
-## $PROJECT_NAME
-## $PROJECT_DIR
-## $RELEASE_DIR
-## $LOVE_FILE       - points to the love file
-
-## 1. Init the module
-### $1: Module name
-init_module "Example"
-
-## 2. Read the configuration
-# Syntax is ${INI__section__variable}
-if [ "$CONFIG" = true ]; then
-    if [ -n "${INI__q__wer}" ]; then
-        WER=${INI__q__wer}
-    fi
-    if [ -n "${INI__q__ty}" ]; then
-        TY=${INI_q_ty}
-    fi
-    if [ -n "${INI__q__uiop}" ]; then
-        UIOP=true
-    fi
-fi
-
-## 3. Parse the options
-# $OPTOPT holds the option and $OPTARG holds the eventual argument passed to it.
-while getoptex "$SCRIPT_ARGS" "$@"
-do
-    if [ "$OPTOPT" = "wer" ]; then
-        WER=$OPTARG
-    elif [ "$OPTOPT" = "ty" ]; then
-        TY=$OPTARG
-    elif [ "$OPTOPT" = "uiop" ]; then
-        UIOP=true
-    fi
-done
-
-## 4. Create the love file
-### $1: Compression level 0-9
-create_love_file 9
-
-
-## 5. Write your code
-
-
-## 6. Unset every variable passed by configuration or command-line
-unset WER TY UIOP
-
-## 7. Exit the module
-### $1: exit code. 0 - success, other - failure
-### $2: error message
-exit_module
-

love-release.1

@@ -201,7 +201,7 @@ One can replace the Love files there.
 The script is modular.
 Each different platform is handled by a subscript stored in \fIscripts\fR.
 If you'd like to add the support of another platform,
-or write your own build script, see \fIscripts/example.sh\fR.
+or write your own build script, see \fImodules.md\fR.
 .SH ICONS
 The script doesn’t yet handle the process of creating icons,
 but if provided it can use them.

modules.md

@@ -0,0 +1,122 @@
+# 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.
+```bash
+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.
+```bash
+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:
+```bash
+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`.
+```bash
+# 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.