Skip to main content

The xpm Frequently Asked Questions

error: Cannot read property 'path' of null (aggressive antivirus)

This problem is specific to Windows and is caused by aggressive antivirus programs.

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. Or switch to a better operating system.

... running scripts is disabled on this system (PowerShell)

Recent Windows versions use PowerShell, which has a more restrictive execution policy intended to prevent the execution of malicious scripts; unfortunately this also prevents the execution of node.js applications.

If you get a message in the console as the one below:

xpm : File C:\Users\...\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 init --template @xpack/hello-world-template@latest --property lan ...
+ ~~~
    + CategoryInfo          : SecurityError: (:) [], PSSecurityException
    + FullyQualifiedErrorId : UnauthorizedAccess
The terminal process "C:\WINDOWS\System32\WindowsPowerShell\v1.0\powershell.exe -Command xpm init --template @xpack/hello-world-template@latest --property language

then run the following command in a PowerShell terminal:

Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope CurrentUser

For more details please read the Microsoft about_Execution_Policies page.

zsh: command not found: xpm

The location where npm installs global modules got lost; most probably you recently switched to zsh and forgot to migrate the shell startup to .zprofile.

Copy the PATH setting from your previous shell startup file to .zprofile.

Why xpm manages configurations, instead of limiting itself to managing dependencies/packages, isn't it a package manager?

No, xpm is not a package manager, it is a project manager.

In the most generic use case, configurations can have specific dependencies, for example different configurations can use different architecture toolchains, or, in test cases, even different versions of the same toolchain.

Therefore, defining configurations in package.json is probably the best choice, otherwise both xpm and the build tools must handle multiple files with partly redundant content.

static async start () ... SyntaxError: Unexpected identifier

This problem occurs usually on GNU/Linux, and is caused by trying to use the outdated version of Node available in the distribution, which does not understand the async keyword.

Errors may look like:

$ 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)

The solution is to install the most recent LTS version of Node, as described in the prerequisite page.

Cannot find the Library folder (on macOS)

Yes, due to an unfortunate Apple decision, this folder is hidden for regular browsing in Finder.

To make it back visible, use:

/usr/bin/chflags nohidden ~/Library
xattr -d com.apple.FinderInfo ~/Library
Cannot find the .content folder (on macOS)

Yes, due to an unfortunate Apple decision, all folders starting with a dot are hidden for regular browsing in Finder.

Fortunately there is a workaround for this:

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.

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

In certain conditions, npm may fail when installing a new xpm over a very old 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/v18.18.2/lib/node_modules/xpm/lib/main.js
- /home/ilg/.nvm/versions/node/v18.18.2/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.

I am perfectly content with my development environment, so why should I consider using xPacks?

While current development environments are indeed excellent, and rolling distributions like Arch and Homebrew do an outstanding job of keeping systems up-to-date, it is not uncommon for the latest versions to disrupt older applications and various complex processes, such as build scripts, that rely on older versions.

The xpm dependency mechanism is designed to address this issue by providing a straightforward and consistent solution for installing different versions of the same package in separate folders and managing dependencies.

Nix also offers reproducible builds and a vast array of packages, so why consider xpm packages?

Nix is an excellent project that rigorously controls versions down to the individual library. However, it relies on file links, which are either unavailable or unreliable on Windows, making Nix currently available only on GNU/Linux and macOS. Additionally, mastering the Nix language requires considerable effort.

Why couldn't npm be used as-is, and why was it necessary to invent xpm?

Each package manager implements a specific strategy for managing dependencies. npm, yarn, and pnpm all employ strategies tailored to ECMAScript dependencies.

Unfortunately, these strategies do not work for other languages, such as C/C++. Additionally, it would be very challenging and require inelegant hacks to adapt development dependencies to binary archives (for tools like compilers).

Why bother managing versions when auto-configure can sort out the differences?

Traditionally, dealing with different versions and variations between systems involves adding a complex auto-configure mechanism. This mechanism detects which tools and components are present, identifies their versions, and uses this information to parametrise the process (such as a project build) to accommodate all these differences.

This approach began with GNU configure and has evolved to include even more complex solutions, like CMake or Meson scripts.

Instead of constantly figuring out how to utilise new versions and making the auto-configure scripts increasingly complex, why not allow the application to request the exact versions known to be compatible and let an automated tool handle the dependencies?

The xpm can do precisely this, bringing the exact versions needed into the project, thus rendering the auto-configure step superfluous.