The properties definitions

Purpose

Define the values used as variables in the LiquidJS substitutions.

Syntax

{
    ...
    "properties": {
         ...
         "<property name>": "<property value>",
         ...
    }
}

The value of properties is a map of string definitions.

Description

The properties map is used to define string properties that can be used as substitution variable in other definitions.

properties can be defined on top of other properties, and the LiquidJS engine will be invoked repeatedly until all substitutions are performed.

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.

Reserved properties

The properties are generally under the user's full control.

However, xpm reserves certain names for variables with special usage.

buildFolderRelativePath

The value of this variable is used by xpm as the folder where the build configuration-specific dependencies will be installed.

The folder is relative to the location of the package.json file.

If not explicitly defined, an warning is issued, and the default value of build/<configurationName> is used.

tip

Ensure that the resulting paths are valid on Windows, meaning they should use backslash separators. To achieve this, compose the paths using path_join: (see the example below).

Examples

Project properties:

{
    "xpack": {
        "properties": {
            "buildFolderRelativePath": "{{'build' | path_join: configuration.name | to_filename | downcase}}",
        }
    }
}

info

Please note that the path_join: in the above definition is platform-specific, and generates paths with back-slashes separators on Windows.

Build configuration properties:

{
    "name": "@xpack-dev-tools/cmake",
    "version": "3.28.6-1.1",
    "xpack": {
        "properties": {
            "appLcName": "cmake",
        },
        "buildConfigurations": {
            "common-docker": {
                "hidden": true,
                "properties": {
                    "containerName": "{{properties.appLcName}}-{{package.version}}-{{configuration.name}}",
                    "force32": ""
                }
            }
        }
    }
}