Edit

Overview

xpm is a Node.js CLI application available as the npm package xpm from the npmjs.com public repository.

Prerequisites

  • a recent Node.js (>=12.x), since some dependencies require new features
  • a recent npm.

For details, please read (carefully!) the prerequisites page.

xpm install

On Windows, by default, global Node.js packages are installed in the user home folder, in %APPDATA%\npm (like C:\Users\ilg\AppData\Roaming\npm), and managing packages does not require administrative rights.

C:\>npm install --global xpm@latest
C:\Users\ilg\AppData\Roaming\npm\xpm -> C:\Users\ilg\AppData\Roaming\npm\node_modules\xpm\bin\xpm.js
+ xpm@0.5.0
added 260 packages from 147 contributors in 36.304s

The result is a pair of files in the %APPDATA%\npm folder:

C:\>dir "%APPDATA%"\npm\xpm*
 Volume in drive C has no label.
 Volume Serial Number is 28CE-1C06

 Directory of C:\Users\ilg\AppData\Roaming\npm

18/04/2018  10:40               319 xpm
18/04/2018  10:40               196 xpm.cmd
               2 File(s)            515 bytes
               0 Dir(s)  51,207,155,712 bytes free

If you followed the instructions in the prerequisites page, you should already have this path configured and the program should start normally:

C:\>xpm --version
0.5.0

Power Shell execution policy

By default, Power Shell restricts scripts, and xpm is not allowed to run:

PS C:\Users\ilg> xpm --version
xpm : File C:\Users\ilg\AppData\Roaming\npm\xpm.ps1 cannot be loaded because running scripts is disabled on this
system. For more information, see about_Execution_Policies at https:/go.microsoft.com/fwlink/?LinkID=135170.
At line:1 char:1
+ xpm --version
+ ~~~
    + CategoryInfo          : SecurityError: (:) [], PSSecurityException
    + FullyQualifiedErrorId : UnauthorizedAccess
PS C:\Users\ilg>

In order to run xpm it is necessary to change the execution policy:

PS C:\Users\ilg> Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser

Execution Policy Change
The execution policy helps protect you from scripts that you do not trust. Changing the execution policy might expose
you to the security risks described in the about_Execution_Policies help topic at
https:/go.microsoft.com/fwlink/?LinkID=135170. Do you want to change the execution policy?
[Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help (default is "N"): A
PS C:\Users\ilg> xpm --version
0.8.1
PS C:\Users\ilg>

Aggressive antivirus programs & xpm

On Windows, binary xPacks are .zip archives containing .exe files; some aggressive antivirus programs may quarantine those files, or even modify the content of the archives, affecting the checksum and thus preventing the packages to be installed.

Errors may look like:

Downloading https://github.com/gnu-mcu-eclipse/qemu/releases/download/v2.8.0-4-20190211/gnu-mcu-eclipse-qemu-2.8.0-4-20190211-0633-win64.zip...
{ Error: sha256-p3CgzXJt4zi5g0kxQXlOpss3Xu5Yy+Zv8HXWXkUdg6g= integrity checksum failed when using sha256: wanted sha256-p3CgzXJt4zi5g0kxQXlOpss3Xu5Yy+Zv8HXWXkUdg6g= but got sha512-k1s9UW6Zb20llIuopUwbf3D38OP1F+Nkgf3wGWwsXPwoQfhuiR89+VF3Rrf7YF20fN3tG4/3jZSC3apiHbQ6NA== sha256-ABnfxLMtY8E5KqJkrtIlPB4ML7CSFvjizCabv7i7SbU=. (9 bytes)
...
Extracting 'gnu-mcu-eclipse-qemu-2.8.0-4-20190211-0633-win64.zip'...
error: Cannot read property 'path' of null

The solution is to configure the antivirus program to be less aggressive, at least for files in the AppData\Roaming\xPacks and AppData\Local\Caches\xPacks folders.

If this is not possible, temporarily disable the antivirus program.

On macOS, by default, global Node.js packages are installed in /usr/local, and managing them requires administrative rights, but if you followed the instructions in the prerequisites page, you should already have configured npm to use a location in the home folder.

With the environment properly set, the command to install xpm is:

npm install --global xpm@latest

To test if xpm starts:

$ which xpm
/Users/ilg/Library/npm/bin/xpm
$ xpm --version
0.10.2

On GNU/Linux, by default, global Node.js packages are installed in /usr/local, and managing them requires administrative rights, but if you followed the instructions in the prerequisites page, you should already have configured npm to use a location in the home folder.

With the environment properly set, the command to install xpm is:

npm install --global xpm@latest

To test if xpm starts:

$ which xpm
/home/ilg/opt/npm/bin/xpm
$ xpm --version
0.10.2

Using an out of date Node.js

Ignoring the recommendation to use the LTS version of Node.js and insisting on using the one provided by the distribution usually results in errors like this:

$ xpm -v
/home/ilg/opt/npm/lib/node_modules/xpm/node_modules/@ilg/cli-start-options/lib/cli-application.js:150
  static async start () {
               ^^^^^
SyntaxError: Unexpected identifier
    at exports.runInThisContext (vm.js:53:16)
    at Module._compile (module.js:374:25)
    at Object.Module._extensions..js (module.js:417:10)
    at Module.load (module.js:344:32)
    at Function.Module._load (module.js:301:12)
    at Module.require (module.js:354:17)
    at require (internal/module.js:12:17)
    at Object.<anonymous> (/home/ilg/opt/npm/lib/node_modules/xpm/node_modules/@ilg/cli-start-options/index.js:55:24)
    at Module._compile (module.js:410:26)
    at Object.Module._extensions..js (module.js:417:10)

This problem is caused by the old Node.js, unable to understand the async keyword.

Follow the instructions in the prerequisites page and update your node & npm programs.

Uninstall

To remove xpm, the command is:

npm uninstall --global xpm

Miscellaneous

The official page explaining how to install npm in a custom folder is Resolving EACCES permissions errors when installing packages globally.

npx

If, for any reason, you decide not to install xpm, you can still benefit from it by using the npx command, as a trampoline to start xpm:

$ npx xpm --version
0.10.2

However, for regular usage, this method is not efficient, since npx will need to prepare the Node.js module for each run, and this takes some time.

npm folders

For more details on the folders used by npm, see npm-folders.

xpm folders

To avoid security issues and the need to increase the user privilege level, xpm does not use any system folders, and all activity happens in the user home.

There are two main folders:

  • a cache folder, where all downloaded files are stored
  • a global xPacks store folder, where the xPacks are expanded

For more details see xpm folders.

macOS specifics

The default location used to install the global packages is in ~/Library, a folder that, due to an unfortunate Apple decision, is hidden for regular browsing in Finder.

To make it back visible, use:

/usr/bin/chflags nohidden ~/Library
xattr -d com.apple.FinderInfo ~/Library

A more general solution is to make all hidden files:

defaults write com.apple.Finder AppleShowAllFiles true
killall Finder

Another annoying behaviour of the file browser is to hide names starting with . (dot), which is a real pity since the binary packages are extracted in a folder named .content.

Fortunately there is a workaround for this too:

cmd+shift+'.'

This keyboard shortcut works like a toggle, using it once makes files starting with dot visible, using it again reverts to hiding them.

Proxy

If you are behind a firewall, you need to configure a proxy.

xpm uses the same modules to fetch the package (pacote), so setting a proxy for npm should also work for xpm.

In addition, xpm uses (node-fetch, https-proxy-agent, proxy-from-env) to download the binary archive. These packages require setting the http_proxy & https_proxy variables in the environment. See proxy-from-env for details.

zsh: command not found: xpm

If you recently switched to zsh, or updated macOS to 11.x, which does this automatically, you need to copy the PATH setting from your previous shell startup file to .zprofile, otherwise the location where npm installs global modules is not in the path.

Cannot find module '@ilg/cli-start-options'

In certain conditions, npm may fail when installing a new xpm over an existing one, and xpm becomes unusable, complaining about missing modules.

% xpm --version
internal/modules/cjs/loader.js:888
  throw err;
  ^

Error: Cannot find module '@ilg/cli-start-options'
Require stack:
- /home/ilg/.nvm/versions/node/v14.17.0/lib/node_modules/xpm/lib/main.js
- /home/ilg/.nvm/versions/node/v14.17.0/lib/node_modules/xpm/bin/xpm.js
    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:885:15)

If this happens, a new install usually fixes the problem, if not, the safe way is to first uninstall xpm and then re-install.

User info

To get an initial glimpse on the program, ask for help:

% xpm --help

The xPack project manager command line tool
Usage: xpm <command> [<subcommand>...] [<options> ...] [<args>...]

where <command> is one of:
  init, install, link, list, run, uninstall

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 <command> -h|--help  Quick help on command
xpm --version            Show version
xpm -i|--interactive     Enter interactive mode

npm xpm@0.10.2 '/Users/ilg/.nvm/versions/node/v14.16.0/lib/node_modules/xpm'
Home page: <https://xpack.github.io/xpm/>
Bug reports: <https://github.com/xpack/xpm-js/issues/>
%