Skip to main content

How to install xPack OpenOCD

GitHub package.json version GitHub release (latest by date) GitHub Release Date NPM Version GitHub Downloads (all assets, all releases) NPM Downloads NPM Downloads license

The xPack OpenOCD may be installed automatically, utilising the xpm command (the recommended method), or manually, by downloading and unpacking one of the platform-specific archives.

Automated installation​

The easiest (and recommended) method to install xPack OpenOCD is via xpm and the package available as @xpack-dev-tools/openocd from the npmjs.com registry.

xpm packages (xPacks) refresher

xpm packages, abbreviated as xPacks, are general-purpose, language-neutral software packages. They utilise the same format as npm packages, which comprises a collection of files/folders and a package.json file with the package metadata.

xpm can install source and binary packages. Binary packages include references to regular archives with the platform-specific binaries (such as .tar.gz for Unix or .zip for Windows). These archives are unpacked and links/forwarders to the executables are created within a .bin folder.

For more details, please refer to the previous explanation on the Getting Started page.

Prerequisites​

The only requirement for an automated installation is a recent xpm, which is a portable Node.js command line application that complements npm with several additional features specific to C/C++ projects.

To install xpm, follow the instructions on the xpm install page.

If already installed, it is always advisable to update it to the latest version with:

npm install --location=global xpm@latest
tip

Although not mandated by xpm, it is also advisable to upgrade npm to the latest version, and node to a reasonably recent version (currently npm requires a node >=18.17.0).

Local installations

One of the xPack design goals is to allow each project to select the exact versions of the tools it requires.

Similarly to npm being able to install specific versions of the JavaScript tools into each project, xpm was also designed to be able to install specific versions of the required binary tools locally into each project.

Therefore, similarly to the way npm installs the JavaScript packages into node_modules, xpm installs the binary tools into xpacks. Here there will be separate folders with the installed packages, for example xpacks/@xpack-dev-tools/openocd.

Each such folder includes the package.json file with the project metadata and a sub-folder .content with the extracted binary archive. The executables are usually within .content/bin.

tip

On some platforms, names beginning with . (dot) might be hidden for normal browsing, and viewing them requires separate options (such as ls -A) or, in file browsers, to enable settings such as Show Hidden Files.

The xpacks/.bin folder

If multiple binary packages are installed, in order to allow the executables to be accessed, one possible solution is to add all <package>/.content/bin folders to the PATH.

To simplify matters, npm employs a separate <project>/node_modules/.bin folder where it places links/forwarders pointing to the actual executable files.

Similarly, xpm adds links/forwarders into a separate <project>/xpacks/.bin folder.

With this setup, the project needs to prepend only this .bin folder to the PATH, and all the required tools are accessible and preferred over possible system tools.

Global installations and the user global xPacks store

Given that some binary tools (such as toolchains) may be very large (hundreds of megabytes or more), it is impractical to maintain multiple copies of these tools, one for each project.

Instead, xpm installs the binary packages only once into a user global store (a platform-dependent folder within the home folder), thereby conserving disk space when the same tools are utilised across multiple projects.

In order to allow the projects to access the binary tools installed within the user global store, instead of unpacking the archives in xpacks, xpm adds symbolic links pointing to the user global xPacks store.

The outcome is functionally equivalent to installing the tools into each project, but without the wasted disk space.

tip

It is possible to force a local installation into a project by passing --copy to xpm install.

If necessary, it is also possible to install packages only globally, without creating local links/forwarders (see below).

The user xPacks cache

To save download time, all archives are first stored within a cache, and all subsequent downloads are replaced with the cached content.

Therefore, all published archives should be read-only and it is not permitted to replace them at a later time.

Initialise the project​

Upon initial use, ensure that a package.json file is present within the project root folder.

This may be achieved by executing xpm init in the desired project folder (substitute my-project accordingly):

cd my-project
xpm init
Under the hood

The primary purpose of xpm init is to create a package.json file, if not already present.

In addition to name & version, the minimal package.json must include a property named xpacks, even if empty. This property is mandatory to identify the package as an xpm package.

Initialise the project​

Upon initial use, ensure that a package.json file is present in the project root folder.

This may be achieved by executing xpm init in the desired project folder (substitute my-project accordingly):

cd my-project
xpm init
Under the hood

The primary purpose of xpm init is to create a package.json file, if not already present.

In addition to name & version, the minimal package.json must include a property named xpacks, even if empty. This property is mandatory to identify the package as an xpm package.

Installation within the project​

The next step is to install the openocd package into the project.

The command to install the latest available version of openocd is:

xpm install @xpack-dev-tools/openocd@latest --verbose

To install a specific version, specify it explicitly:

xpm install @xpack-dev-tools/openocd@0.12.0-7.1 --verbose

The main result is a set of forwarders in the .bin folder:

dir xpacks\.bin
PATH setup

With all binary tools installed within xpacks/.bin, the project build configurations require only a single PATH adjustment:

export PATH=<...project-path...>/xpacks/.bin:$PATH
tip

This syntax is for the Git Bash console. When using COMMAND.EXE or Power Shell, adjust the syntax for the corresponding Windows specific shell.

Installation details

The above xpm install command will perform the following:

  • identify the platform-specific archive for the desired version of @xpack-dev-tools/openocd, download it into a cache and unpack it into a versioned folder within the user's global xPacks store (if not already present); check the output of the xpm install command for the actual folder used on your platform;

  • create a local symbolic link such as xpacks/@xpack-dev-tools/openocd pointing to the versioned folder in the user's global xPacks store

  • add links/forwarders into the local xpacks/.bin folder, referring to the binaries in xpacks/@xpack-dev-tools/openocd/.content/bin;

  • add @xpack-dev-tools/openocd to package.json as a development dependency; this associates a specific version of xPack OpenOCD with the current project (details below).

tip

The installation location may be configured using the XPACKS_STORE_FOLDER environment variable; for more details please refer to the xpm folders page.

Reproducibility and devDependencies

To ensure reproducibility, it is essential for each project to always utilise the exact desired versions of the required tools, regardless of the tools installed in the system.

To achieve this objective, xpm records all locally installed binary packages as development dependencies in the project package.json file.

The result appears as follows:

  "xpack": {
  "minimumXpmRequired": "0.20.7",
  "dependencies": {},
  "devDependencies": {
    "@xpack-dev-tools/openocd": {
      "specifier": "0.12.0-7.1",
      "local": "link",
      "platforms": "all"
    }
  },
  "properties": {},
  "actions": {},
  "buildConfigurations": {}
}

If the package.json is saved in the revision system, the above definition acts as a firm reference to the specific version of xPack OpenOCD.

After cloning the project into a different location, the command xpm install may be used to install all development dependencies.

This is particularly useful for CI/CD environments.

Installation globally​

For older development environments, it is also possible to install xPack OpenOCD only globally in the user's global xPacks store, without any local links/forwarders; it is the developer's responsibility to configure the path to the tools.

No other files are installed in any system folders or other locations.

xpm install @xpack-dev-tools/openocd@latest --global --verbose
note

Installing packages locally into a project always installs the packages in the user's global xPacks store; subsequent attempts to install the packages globally will fail with already installed.

PATH setup

In order to access the xPack OpenOCD binaries installed in the user's global xPacks store, the project build configurations need a PATH adjustment:

export PATH=$HOME/AppData/Roaming/xPacks/xpack-dev-tools/openocd/0.12.0-7.1/.content/bin:$PATH
tip

When not using the Git console, adjust the syntax for the corresponding shell.

Uninstall​

The xpm binaries do not utilise any form of system installer; instead they are distributed as portable (.zip or .tar.gz) archives; therefore they do not require the execution of any uninstaller; simply removing the links and possibly the user's global xPacks store folder and the user xPack cache folder is sufficient.

To remove the links created by xpm in the current project, navigate to the project folder:

cd my-project

and request xpm to uninstall the package:

xpm uninstall @xpack-dev-tools/openocd --verbose

To completely remove the package from the user's global xPacks store:

xpm uninstall --global @xpack-dev-tools/openocd --verbose
Clean-ups

For a comprehensive clean-up, please note that xpm utilises only two folders:

  • %APPDATA%\Roaming\xPacks
  • %APPDATA%\Local\Caches\xPacks

They can be removed at any time and space reclaimed; xpm will recreate them during new installations.

However, projects linking to the user's global xPacks store will fail with broken paths.

Quick test​

To verify if the xPack OpenOCD installed by xpm starts correctly, utilise something such as:

C:\> %USERPROFILE%\AppData\Roaming\xPacks\@xpack-dev-tools\openocd\0.12.0-7.1\.content\bin\openocd.exe --version
xPack Open On-Chip Debugger 0.12.0
note

The reported version is the upstream version, which is shorter than the xPack version, as the latter requires additional digits to identify the releases.

Manual installation​

For all platforms, the xPack OpenOCD binaries are released as portable archives that may be installed in any location.

The archives may be downloaded from the GitHub Releases pages.

Download & unpack​

The Windows versions of xPack OpenOCD are packed as .zip files. Download the latest version named like:

  • xpack-openocd-0.12.0-7-win32-x64.zip
note

In case you wonder where the suffix originates from, it is exactly the Node.js process.platform and process.arch. The win32 part is confusing, but we have to live with it.

To manually install the xPack OpenOCD, unpack the archive and move it to a location of your choice.

The recommended location is the %USERPROFILE%\AppData\Roaming\xPacks\openocd folder, for example C:\Users\ilg\AppData\Roaming\xPacks\openocd\xpack-openocd-0.12.0-7.

note

According to Microsoft, AppData\Roaming is the recommended location for installing user-specific packages.

info

For manual installations, the recommended installation location is slightly different from the folders created by xpm install, which utilise the @xpack-dev-tools scope to group different tools, and .content to store the unpacked archive.

Quick test​

To verify if the xPack OpenOCD installed manually starts correctly, utilise something such as:

C:\> %USERPROFILE%\AppData\Roaming\xPacks\openocd\xpack-openocd-0.12.0-7\bin\openocd.exe --version
xPack Open On-Chip Debugger 0.12.0
note

The reported version is the upstream version, which is shorter than the xPack version, as the latter requires additional digits to identify the releases.

Folder hierarchy​

After installation, the package creates a hierarchy of folders such as the following (only the first two depth levels are shown):

C:> tree /f %USERPROFILE%\AppData\Roaming\xPacks\@xpack-dev-tools\openocd\0.12.0-7.1.1\.content
Folder PATH listing
Volume serial number is B02D-925C
├── README.md
├── bin
│   ├── libftdi1.dll
│   ├── libusb-1.0.dll
│   └── openocd.exe
├── distro-info
│   └── licenses
└── openocd
  ├── OpenULINK
  ├── angie
  ├── contrib
  └── scripts

8 directories, 4 files

Drivers​

As usual on Windows, mastering drivers is a challenge and OpenOCD is no exceptions, so don't be surprised to encounter many incompatible drivers for various JTAG probes.

Zadig

The OpenOCD distribution includes some libusb drivers, and recommends to run the zadig.exe tool to activate them.

For example ARM-USB-OCD from Olimex, after installing the vendor drivers, asks to install Zadig and convert the vendor drivers to WinUSB drivers.

caution

Although converting the vendor drivers to WinUSB drivers will make OpenOCD happy, please be aware that other tools using the original drivers will no longer work while Zadig is active, and to make them work you need to uninstall the Zadig driver for the device and reinstall the vendor driver (see Zadig FAQ). Our recommendation is to use Zadig only as a last resort solution, and, when possible, prefer the manufacturer drivers.

ST-LINK

One example of compatible drivers are the ST-LINK USB drivers, from ST, available as part number STSW-LINK009. Download the latest stsw-link009.zip archive, extract its content into a separate folder, and run the dpinst_amd64.exe (or dpinst_x86.exe) with administrative privileges.

As for most Windows drivers, to complete the installation, a restart usually helps.

Connect the ST-LINK or the DISCOVERY board and check in Control Panel → System → Device Manager if the JTAG is operational.

ST-LINK Windows device

For other probes follow the manufacturer instructions.

note

All Windows tests were performed on Windows 11. If, for any reasons, you still need to use older versions, especially the venerable Windows XP, some differences may be observed in the USB subsystem; to stay on the safe side, try to always use original manufacturer drivers.

Testing​

To test if OpenOCD is able to connect to a specific board, it is generally necessary to select the interface and the processor. As a shortcut, for some well known boards, there are ready made configuration files to set both the interface and the processor. For example to test a connection via ST/LINK to the STM32F4DISCOVERY board, you can use something like this:

$ .../xPacks/@xpack-dev-tools/openocd/0.12.0-7.1/.content/bin/openocd -f board/stm32f4discovery.cfg
xPack OpenOCD x86_64 Open On-Chip Debugger 0.12.0+dev
Licensed under GNU GPL v2
For bug reports, read
http://openocd.org/doc/doxygen/bugs.html
Info : The selected transport took over low-level target control. The results might differ compared to plain JTAG/SWD
adapter speed: 2000 kHz
adapter_nsrst_delay: 100
none separate
srst_only separate srst_nogate srst_open_drain connect_deassert_srst
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections
Info : clock speed 2000 kHz
Info : STLINK V2J14S0 (API v2) VID:PID 0483:3748
Info : Target voltage: 2.881412
Info : stm32f4x.cpu: hardware has 6 breakpoints, 4 watchpoints
Info : Listening on port 3333 for gdb connections
^C