Skip to main content

The dependencies definitions

Purpose​

Define the xpm source packages required at compile/link time.

Syntax​

{
    ...
    "dependencies": {
        "<package>": "semver" | {
            "specifier": "<package specifier>",
            "local": "link" | "copy",
            "platforms": "<name>,..."
        },
        ...
    }
    ...
}

Description​

The dependencies definition is similar to the npm definition but lists the xpm source packages required at compile/link time.

When a source package is installed locally into the local project's xpacks folder (without --global), all packages listed in its xpack.dependencies are also recursively installed into the same local xpacks folder.

In other words, the list of source dependencies is linearised, and all dependencies are installed at the same top level. This approach is necessary for compiled languages (like C/C++) to ensure all source libraries are compiled and available at link time.

info

This linearised list of source dependencies is the main difference compared to npm.

npm, designed for JavaScript/TypeScript, maintains the hierarchical structure of dependencies, which is not suitable for compiled languages.

There are two formats for defining the dependencies, the extended format specific to xpm, and the short format, used for compatibility with npm.

When installing source packages into an xpm project, they are also added to the dependencies list, in the extended format.

Properties​

In the short format, the dependency value is a string, with the same content as for npm dependencies.

In the extended format, the value is an object with the following properties:

specifier​

A string that identifies the package.

  • a SemVer expression: a package with a version that matches the expression will be downloaded from the npmjs.com repository
  • a full URI/URL: the package will be installed from the address
  • user/project: a simplified syntax for GitHub projects,

local​

A string that defines the install strategy:

  • link: create a link in the local project pointing to a read-only instance of the package
  • copy: create a full writable copy in the local project

platforms​

A string that indicates the platforms where the dependency can be installed.

  • all: install on all platforms
  • ...: comma separated list of platforms (linux-x64, linux-arm64, darwin-x64, darwin-arm64, win32-x64)
note

Currently the value is ignored by npm install.

Examples​

Extended format source dependency:

{
  "xpack": {
    "minimumXpmRequired": "0.19.4",
    "dependencies": {
      "@micro-os-plus/micro-test-plus": {
        "specifier": "^3.1.2",
        "local": "link",
        "platforms": "all"
      }
    }
  }
}

Traditional short form source dependency:

{
  "xpack": {
    "dependencies": {
      "@micro-os-plus/micro-test-plus": "^3.1.2"
    }
  }
}