Skip to main content

LiquidJS substitutions

To increase reusability, it is possible to use substitutions in in all xpm metadata definitions. The syntax is more elaborate than the simple variable substitution, and is using the LiquidJS template engine syntax, which accepts the full LiquidJS syntax.

The LiquidJS definitions are:

  • variables, like {{ configuration.name }}
  • filters, like {{ configuration.name | downcase }}
  • tags, like {% if os.platform != 'win32' %}xpm run execute --config synthetic-posix-cmake-debug{% endif %}

For more details, please see the documentation for the xpack/xpm-liquid-ts module, where the substitutions are implemented.

Predefined variables​

The LiquidJS syntax to include variables uses double curly braces:

{{variable}}

Example:

Simple variable substitution
"install": "xpm install --config {{configuration.name}}"

The main source for variables are the properties maps.

tip

When substitutions occur within a build configuration, the properties defined in the build configuration take precedence over properties with the same name defined at the project level.

The available variables are:

  • package.* - the entire package.json parsed
  • properties.* - user defined string properties
  • configuration.name - the name of the current configuration
  • configuration.* - the entire current configuration parsed
  • env.* - the Node.js process environment
  • os.* - the Node.js os definitions
    • os.EOL
    • os.arch (like 'arm', 'arm64', 'ia32', 'x64')
    • os.constants
    • os.cpus
    • os.endianness
    • os.homedir
    • os.hostname
    • os.platform (like 'darwin', 'linux', 'win32')
    • os.release
    • os.tmpdir
    • os.type
    • os.version (available since Node 12)
  • path.* definitions
    • path.delimiter (; for Windows, : for POSIX)
    • path.sep (\ on Windows, / on POSIX)
    • path.win32.delimiter (;)
    • path.win32.sep (\)
    • path.posix.delimiter (:)
    • path.posix.sep (/)

Custom filters​

Filters act like pipes processing strings. The syntax is similar to the shell pipe syntax:

{{variable|filter}}

Example:

Multi-filter substitution
"buildFolderRelativePath": "{{'build' | path_join: configuration.name | to_filename | downcase}}"

In addition to the standard LiquidJS filters, the following xpm specific filters are also available:

  • path_basename
  • path_dirname
  • path_normalize
  • path_join
  • path_relative
  • path_posix_basename
  • path_posix_dirname
  • path_posix_normalize
  • path_posix_join
  • path_posix_relative
  • path_win32_basename
  • path_win32_dirname
  • path_win32_normalize
  • path_win32_join
  • path_win32_relative
  • util_format
  • to_filename
  • to_posix_filename
  • to_win32_filename

Multi-line definitions​

If multiple lines 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 %}