mirror of
https://github.com/TangentFoxy/love-release.git
synced 2025-07-28 19:12:19 +00:00
123 lines
5.1 KiB
Markdown
123 lines
5.1 KiB
Markdown
# 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 `$MOD_OPTIONS` variable. Long options can be added in the `$MOD_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
|
|
MOD_OPTIONS="A"
|
|
MOD_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.
|