Skip to main content

The actions definitions

Purpose​

Define a map of sequences of shell commands to be invoked by name.

Syntax​

{
    ...
    "actions": {
        ...
        "<action name>": "<command>" | [ "<command>",... ],
        ...
    }
    ...
}

The value of an actions entry can be either a string or an array of strings containing shell commands.

Description​

xpm actions are an extended version of npm scripts, that support multiple lines and substitutions.

actions can be defined at project level, or at build configuration level.

When actions are invoked for a specific build configuration, the actions defined in the build configuration take precedence over actions with the same name defined at the project level.

Portability warning

Special attention should be given to running shell commands on Windows. While invoking simple applications is generally portable, many Unix shell commands do not have direct equivalents on Windows.

The solution is to use portable applications, for example instead of rm use del-cli, and so on.

If full portability is not required, a workaround is to execute the xpm run commands in a Git Bash terminal.

Multi-line actions​

In order to accommodate more complex actions, it is possible to define sequences of commands as arrays of strings, with each line executed as a separate command.

If multiple commands are generated via loops, line terminators can be inserted with {{ os.EOL }}), for example:

{% for command in package.xpack.my_commands %}{{ command }}{{ os.EOL }}{% endfor %}

Example​

{
  "name": "@xpack-dev-tools/cmake",
  "version": "3.28.6-1.1",
  "xpack": {
    "properties": {
      "appLcName": "cmake",
    },
    "actions": {
      "install": [
        "npm install",
        "xpm install"
      ]
    },
    "buildConfigurations": {
      "common-docker": {
        "hidden": true,
        "properties": {
          "containerName": "{{properties.appLcName}}-{{package.version}}-{{configuration.name}}",
          "force32": ""
        },
        "actions": {
          "docker-remove": [
            "docker stop {{properties.containerName}}",
            "docker rm {{properties.containerName}}"
          ]
        }
      }
    }
  }
}