xpm install

Purpose

Install dependencies.

Synopsis

Invoked with arguments referring to packages:

xpm install [<options> ...] [<packs>...]

Invoked with no package arguments, and running in a package folder:

xpm install [<options> ...]

Aliases:

i
intstall

Description

This command installs a package, and all packages that it depends on.

As for npm, an xpm package is any of the following:

A folder containing a package.json file.
A gzipped tarball containing (1).
A URL that resolves to (2).
A <name>@<version> that is published on the registry with (3).
A <name>@<tag> that points to (4).
A <name> that has a latest tag satisfying (5).
A git url that, when cloned, results in (1).

Even if you never publish your package, you can still gain numerous benefits from using xpm to conveniently install dependencies and potentially automate path management for dependent tools.

Install dependencies

When invoked without arguments in a package folder, xpm install installs the dependencies listed in the dependencies and devDependencies fields in package.json.

The dependencies are installed in the local xpacks folder. For binary xpm packages, soft links to the executables are created in the xpacks/.bin folder (on Windows .cmd stubs are created).

Install packages

When invoked with arguments, they must refer to packages. The common use case is to use names of packages stored on the public npm repository. However, since xpm uses the same library to manage downloads as npm, all formats are accepted:

xpm install [<@scope>/]<name>
xpm install [<@scope>/]<name>@<tag>
xpm install [<@scope>/]<name>@<version>
xpm install [<@scope>/]<name>@<version range>
xpm install <github>:<organization>/<repo-name>[#commit-id]
xpm install <github>:<organization>/<repo-name>[#semver:X.Y.Z]
xpm install <gitlab>:<organization>/<repo-name>[#commit-id]
xpm install <gitlab>:<organization>/<repo-name>[#semver:X.Y.Z]
xpm install <git repo url>
xpm install <tarball file>
xpm install <tarball url>
xpm install <folder>

When referring to GitHub by semver, a tag named vX.Y.Z must be present.

For detail please see npm install.

Options

Help (`--help`)

% xpm install --help

xPack project manager - install package(s)
Usage: xpm install [options...] [--global] [--force] [--force-32bit]
                 [--config <config_name>] [--all-configs] [--dry-run]
                 [--save-prod] [--no-save] [--save-dev] [--save-optional]
                 [--save-bundle] [--save-exact] [--copy]
                 [[@<scope>/]<name>[@<version]|<github_name>/<repo>]...

Install options:
  -g|--global                Install the package globally in the home folder (optional)
  -f|--force                 Force install over existing package (optional)
  -32|--force-32bit          Force install 32-bit binaries (optional)
  -c|--config <config_name>  Install configuration specific dependencies (optional)
  -a|--all-configs           Install dependencies for all configurations (optional)
  -n|--dry-run               Pretend to install the package(s) (optional)
  -P|--save-prod             Save to dependencies; default unless -D or -O (optional)
  --no-save                  Prevent saving to dependencies (optional)
  -D|--save-dev              Save to devDependencies (optional)
  -O|--save-optional         Save to optionalDependencies (optional)
  -B|--save-bundle           Save to bundleDependencies (optional)
  -E|--save-exact            Save deps with exact version (optional)
  --copy                     Copy locally, do not link to central store (optional)

Common options:
  --loglevel <level>         Set log level (silent|warn|info|verbose|debug|trace)
  -s|--silent                Disable all messages (--loglevel silent)
  -q|--quiet                 Mostly quiet, warnings and errors (--loglevel warn)
  --informative              Informative (--loglevel info)
  -v|--verbose               Verbose (--loglevel verbose)
  -d|--debug                 Debug messages (--loglevel debug)
  -dd|--trace                Trace messages (--loglevel trace, -d -d)
  --no-update-notifier       Skip check for a more recent version
  -C <folder>                Set current folder

xpm -h|--help                Quick help
xpm --version                Show version
xpm -i|--interactive         Enter interactive mode

npm xpm@0.20.8 '/Users/ilg/.nvm/versions/node/v20.18.0/lib/node_modules/xpm'
Home page: <https://xpack.github.io/xpm-preview/>
Bug reports: <https://github.com/xpack/xpm-js/issues>

Global install (`-g|--global`)

Install package(s) in the user global xPacks store (located in the user home folder).

Force install (`-f|--force`)

Normally, if a package is already installed, xpm exits with an error message.

Use this option to force xpm to reinstall a package.

Configuration (`-c|--config`)

Install dependencies into an existing configuration build folder instead of the top project folder.

xpm install --config debug-clang-17 @xpack-dev-tools/clang@17.0.6-3.1
xpm install --config debug-clang-16 @xpack-dev-tools/clang@16.0.6-1.1

The xpacks folders are not stored in the project folder, but in the configuration build folder, configured via the buildFolderRelativePath property.

Similarly, the dependencies are stored in the configuration, for example:

{
    ...
    "xpack": {
        "buildConfigurations": {
            "debug": {...},
            "release": {...},
            "debug-clang-17": {
                "devDependencies": {
                    "@xpack-dev-tools/clang": {
                        "specifier": "17.0.6-3.1",
                        "local": "link",
                        "platforms": "all"
                    }
                }
            },
            "debug-clang-16": {
                "devDependencies": {
                    "@xpack-dev-tools/clang": {
                        "specifier": "16.0.6-1.1",
                        "local": "link",
                        "platforms": "all"
                    }
                }
            }
        }
    }
}

Dry-run (`-n|--dry-run`)

Do everything except to actually installing the packages(s).

Save to dependencies (`-P|--save-prod`)

Add the installed packages to the dependencies array and update the package.json;

Unless an explicit -D or -O, source xpm packages are stored in dependencies by default.

Prevent saving to dependencies (`--no-save`)

Prevent saving to dependencies and updating the package.json file.

Save to devDependencies (`-D|--save-dev`)

Add the installed packages to the devDependencies array and update the package.json.

Unless an explicit -P is specified, binary xpm packages are stored in devDependencies by default.

Save with exact version (`-E|--save-exact`)

By default, the stored reference to the installed package uses the ^ syntax, which is the npm/semver convention that means compatible. This means it will use the highest available version that does not change the major version number

Example without -E:

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

This option alters the behaviour by storing the version without the ^ symbol, meaning the exact version is required.

Example with -E:

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

Unless an explicit -D is used, binary xpm packages with longer version strings (that do not comply with semver) are stored without the ^ symbol by default. For example:

{
    "xpack": {
        ...
        "devDependencies": {
            "@xpack-dev-tools/clang": {
                "specifier": "17.0.6-3.1",
                "local": "link",
                "platforms": "all"
            }
        },
        ...
    }
}

Example

Install dependencies

% cd my-project
% xpm install --verbose
xPack project manager - install package(s)

Collecting dependencies for package @my-scope/my-project...
Identified @xpack-dev-tools/clang@18.1.8-2.1 as a dev dependency
Identified @xpack-dev-tools/cmake@3.28.6-1.1 as a dev dependency
Identified @xpack-dev-tools/ninja-build@1.11.1-3.1 as a dev dependency

Installing 3 dependencies...
Folder 'xpacks/@xpack-dev-tools/cmake' linked to global '@xpack-dev-tools/cmake/3.28.6-1.1'
Folder 'xpacks/@xpack-dev-tools/ninja-build' linked to global '@xpack-dev-tools/ninja-build/1.11.1-3.1'
Folder 'xpacks/@xpack-dev-tools/clang' linked to global '@xpack-dev-tools/clang/18.1.8-2.1'
File 'xpacks/.bin/ccmake' linked to '../@xpack-dev-tools/cmake/.content/bin/ccmake'
File 'xpacks/.bin/ninja' linked to '../@xpack-dev-tools/ninja-build/.content/bin/ninja'
File 'xpacks/.bin/analyze-build' linked to '../@xpack-dev-tools/clang/.content/bin/analyze-build'
File 'xpacks/.bin/cmake' linked to '../@xpack-dev-tools/cmake/.content/bin/cmake'
File 'xpacks/.bin/clang' linked to '../@xpack-dev-tools/clang/.content/bin/clang'
File 'xpacks/.bin/cpack' linked to '../@xpack-dev-tools/cmake/.content/bin/cpack'
File 'xpacks/.bin/clang++' linked to '../@xpack-dev-tools/clang/.content/bin/clang++'
File 'xpacks/.bin/ctest' linked to '../@xpack-dev-tools/cmake/.content/bin/ctest'
File 'xpacks/.bin/clang-check' linked to '../@xpack-dev-tools/clang/.content/bin/clang-check'
File 'xpacks/.bin/clang-cl' linked to '../@xpack-dev-tools/clang/.content/bin/clang-cl'
File 'xpacks/.bin/clang-cpp' linked to '../@xpack-dev-tools/clang/.content/bin/clang-cpp'
File 'xpacks/.bin/clang-doc' linked to '../@xpack-dev-tools/clang/.content/bin/clang-doc'
...
File 'xpacks/.bin/wasm-ld' linked to '../@xpack-dev-tools/clang/.content/bin/wasm-ld'

'xpm install' completed in 1.931 sec.

Install package

% xpm install @xpack-dev-tools/clang@latest --verbose
xPack project manager - install package(s)

Processing @xpack-dev-tools/clang@18.1.8-2.1...
Folder 'xpacks/@xpack-dev-tools/clang' linked to global '@xpack-dev-tools/clang/18.1.8-2.1'
File 'xpacks/.bin/analyze-build' linked to '../@xpack-dev-tools/clang/.content/bin/analyze-build'
File 'xpacks/.bin/clang' linked to '../@xpack-dev-tools/clang/.content/bin/clang'
File 'xpacks/.bin/clang++' linked to '../@xpack-dev-tools/clang/.content/bin/clang++'
...
File 'xpacks/.bin/wasm-ld' linked to '../@xpack-dev-tools/clang/.content/bin/wasm-ld'
Adding '@xpack-dev-tools/clang' to 'devDependencies'...

'xpm install' completed in 346 ms.

Purpose​

Synopsis​

Description​

Install dependencies​

Install packages​

Options​

Help (--help)​

Global install (-g|--global)​

Force install (-f|--force)​

Configuration (-c|--config)​

Dry-run (-n|--dry-run)​

Save to dependencies (-P|--save-prod)​

Prevent saving to dependencies (--no-save)​

Save to devDependencies (-D|--save-dev)​

Save with exact version (-E|--save-exact)​

Example​

Install dependencies​

Install package​

Purpose

Synopsis

Description

Install dependencies

Install packages

Options

Help (`--help`)

Global install (`-g|--global`)

Force install (`-f|--force`)

Configuration (`-c|--config`)

Dry-run (`-n|--dry-run`)

Save to dependencies (`-P|--save-prod`)

Prevent saving to dependencies (`--no-save`)

Save to devDependencies (`-D|--save-dev`)

Save with exact version (`-E|--save-exact`)

Example

Install dependencies

Install package