Building OpenOCD under Windows using MSYS2

Introduction

In the past, building OpenOCD on Windows was a complicated process due to its numerous dependencies and lack of availability on the Windows platform. Fortunately, with MSYS2, building OpenOCD has become a simple task. For those who require the latest stable version of OpenOCD on MSYS2, it is available as a binary and can be installed with a single command.

However, there may be cases where you need to build the development version of OpenOCD or apply some patches from the OpenOCD Gerrit repository. Using MSYS2 and PKGBUILD from the upstream repository, accomplishing these operations is now easy. In this article, we’ll guide you through the steps required to build OpenOCD on Windows using MSYS2.

Note that when I first wrote this article, my main objective was to provide a simple recipe for building OpenOCD on Windows and creating a standalone version suitable for ChibiStudio. However, the article’s purpose has since expanded to address a broader audience. Whether you’re looking to install OpenOCD in MSYS2 from binary, compile and install OpenOCD in MSYS2 from the development repository, or export OpenOCD as a standalone application, this article has got you covered.

About MSYS2

What is MSYS2

MSYS2, short for Minimal SYStem 2, is a lightweight application built on Cygwin and MinGW-w64, designed to run on Windows. With MSYS2, you can use autotools, revision control systems, and build native Windows applications using MINGW-w64 toolchains. Installing packages is simplified since the creators have ported Arch Linux’s Pacman. This brings powerful features like dependency resolution and simple complete system upgrades. When launched, MSYS2 appears as a basic terminal.

MSYS2 consists of three subsystems, and each has its corresponding package repository. They are msys2, mingw32, and mingw64.

• The mingw subsystems are the project’s primary focus and provide native Windows programs. These programs are built to work well with other Windows programs, regardless of the other subsystems.
• The msys2 subsystem provides an emulated, mostly POSIX-compliant environment for building software, package management, and shell scripting. These programs exist in a virtual, single-root file system, with the root being the MSYS2 installation directory. While the programs are designed to work well with native Windows programs, there may be some limitations.

Setup of MSYS2

You can download MSYS2 as an executable from SourceForge. The installation process is straightforward, and it creates a folder, usually under C:, named msys64 (or msys32 for 32-bit systems). Once you have completed the installation, you can launch the shell through one of the three .exe files available in the installation folder, each of which is associated with one of the three MSYSTEM subsystems.

The general suggestion is to use mingw32 instead of mingw64 to have a program compatible with the old 32-bit systems. You can verify your current MSYSTEM by running the following command:

echo $MSYSTEM

To avoid any issues related to low permission levels, it is advisable to launch MSYS2 as Administrator. Additionally, note that the classical copy-and-paste hotkeys may not work as expected. Instead, you can right-click on the terminal to paste or use CTRL+Ins and Shift+Ins instead of CTRL+C and CTRL+V.

Getting OpenOCD

There are two ways to obtain OpenOCD with MSYS2:

1. We can install the pre-built version of OpenOCD that comes with MSYS2 and then extract it.
2. We can build OpenOCD by installing the necessary tools and downloading the latest version from the git repository.

Both options are valuable. The first is simpler and provides us with the latest stable version of OpenOCD built by the developers. However, there may be instances where we require the latest development version, which may support new microcontrollers or include bug fixes that are essential for us.

Install the pre-build version of OpenOCD

MSYS2 comes with a pre-built version of OpenOCD, which can be installed to run it directly from the command line. While this may not be useful if your ultimate goal is to build OpenOCD from the repository, it’s worth mentioning if you want to use OpenOCD from the MSYS2 command line.

Once installed, creating a standalone version of OpenOCD by extracting it and its dependencies from the C:\msys64\mingw32 (or C:\msys64\mingw64 for the 64-bit version) folder is simple and suitable for most scenarios. To install the 32-bit version, you can use the following command:

pacman -S mingw-w64-i686-openocd-git

To install the 64-bit version, you can use the following command:

pacman -S mingw-w64-x86_64-openocd-git

Once the setup is complete, you can use OpenOCD in MSYS2 as a native command. For instance, to launch OpenOCD for an STM32 Nucleo-64 F401, you can use the following command:

openocd -f "board/st_nucleo_f4.cfg"

Building OpenOCD from the repository

To compile packages, we need to update MSYS2 and install and configure some tools. Even if you’ve done this before, it’s still a good idea to update your system at least once.

Update MSYS2

The following command updates MSYS2. While it usually works on the first try, major changes may cause it to fail. It’s recommended to run the command, restart the system, and rerun the command until it reports that there are no packages left to update. The command to update MSYS2 is:

pacman -Syuu

Install and configuring the needed tools

We now have to install the base development package with this command

pacman -S base-devel

The MinGW toolchain. If we want to install the 32-bit version the command is:

pacman -S mingw-w64-i686-toolchain

If we want to install the 64-bit version the command is:

pacman -S mingw-w64-x86_64-toolchain

Then we need git

pacman -S git

Note that at first use git requires configuring our identity. To do this we must use these commands (obviously using your identity and your email):

git config --global user.name "John Doe"
git config --global user.email "johndoe@example.com"

As suggested by Kristof (see comments below), the following commands enlarge the memory allocated to git, preventing crashes when cloning large repositories:

git config --global pack.windowMemory "100m"
git config --global pack.packSizeLimit "100m"
git config --global pack.threads "1"

Cloning the upstream packages repository

As mentioned earlier, each MSYSTEM has its own package repository. To obtain the packages needed for OpenOCD and its dependencies, we must clone the MINGW-packages repository.

For this article, I will be using my home folder (~) as the workspace. The home folder is located at C:/msys64/home/[winusername]. Therefore, I will clone the repository to this location using the git clone command.

cd ~
git clone https://github.com/Alexpux/MINGW-packages.git

If the git clone command executes successfully, a new folder named MINGW-packages will be created in our home folder. This folder contains numerous sub-folders, each containing a PKGBUILD file. PKGBUILD is a set of instructions that are required to build a tool while resolving its dependencies.

Building OpenOCD

Now we are able to build OpenOCD from its repository. If we want to build the 32-bit version we have to issue

export MINGW_ARCH=mingw32
cd ~/MINGW-packages/mingw-w64-openocd 
makepkg-mingw -sLf

Otherwise

export MINGW_ARCH=mingw64
cd ~/MINGW-packages/mingw-w64-openocd 
makepkg-mingw -sLf

The procedure will require some time, depending on your computer. Once the process is complete, navigate to the mingw-w64-openocd-git folder. Here, you will find:

• A folder named pkg, which contains the built package
• A folder named src, which contains the source code
• A tar file containing the built package and the source code, which is ready to be installed

Installing the freshly built OpenOCD (optional)

If you want to install OpenOCD in your MSYS2 system to run it from the command line, you can use the following command to install OpenOCD from the tar file you just created.

pacman -U mingw-w64-*-openocd-*-any.pkg.tar.xz

Similar to installing from binary, this enables you to use OpenOCD in MSYS2 as a native command. The key difference is that you are now using the latest development version of OpenOCD.

Exporting OpenOCD as stand-alone

If you want to use OpenOCD as a standalone tool, you must also build its dependencies and copy them to a separate folder along with the OpenOCD binary. If you have already installed OpenOCD, the dependencies are available in the C:\msys64\mingw32 (or C:\msys64\mingw64 for the 64-bit version) folder.

Building the dependencies

The following commands, run one by one, build each of the dependencies of OpenOCD. Execute them once at a time being sure that no error is given

cd ~/MINGW-packages/mingw-w64-confuse
makepkg-mingw -sLf

cd ~/MINGW-packages/mingw-w64-capstone
makepkg-mingw -sLf

cd ~/MINGW-packages/mingw-w64-hidapi 
makepkg-mingw -sLf

cd ~/MINGW-packages/mingw-w64-libftdi
makepkg-mingw -sLf

cd ~/MINGW-packages/mingw-w64-libjaylink-git
makepkg-mingw -sLf

cd ~/mingw-packages/mingw-w64-winpthreads-git
makepkg-mingw -sLf

cd ~/MINGW-packages/mingw-w64-libusb
makepkg-mingw -sLf

cd ~/MINGW-packages/mingw-w64-libusb-compat-git
makepkg-mingw -sLf

Composing our package

Now that we have all the necessary components, we can create the standalone folder. The following commands will copy these pieces into a single folder and rearrange them to obtain a structure similar to that released by the OpenOCD team through the Freddie Chopin website.

This will create the standalone folder named openocd in the home directory C:\msys64\home\[winusername].

if [ "$MINGW_ARCH" == "mingw32" ]; then
 MINGW_PACKAGE_PREFIX="mingw-w64-i686"
 MINGW_FOLD="mingw32"
else
 MINGW_PACKAGE_PREFIX="mingw-w64-x86_64"
 MINGW_FOLD="mingw64"
fi
cp -avr ~/mingw-packages/mingw-w64-confuse/pkg/${MINGW_PACKAGE_PREFIX}-confuse/${MINGW_FOLD}/ ~/
cp -avr ~/mingw-packages/mingw-w64-capstone/pkg/${MINGW_PACKAGE_PREFIX}-capstone/${MINGW_FOLD}/ ~/
cp -avr ~/mingw-packages/mingw-w64-hidapi/pkg/${MINGW_PACKAGE_PREFIX}-hidapi/${MINGW_FOLD}/ ~/
cp -avr ~/mingw-packages/mingw-w64-libftdi/pkg/${MINGW_PACKAGE_PREFIX}-libftdi/${MINGW_FOLD}/ ~/
cp -avr ~/mingw-packages/mingw-w64-libjaylink-git/pkg/${MINGW_PACKAGE_PREFIX}-libjaylink-git/${MINGW_FOLD}/ ~/
cp -avr ~/mingw-packages/mingw-w64-winpthreads-git/pkg/${MINGW_PACKAGE_PREFIX}-libwinpthread-git/${MINGW_FOLD}/ ~/
cp -avr ~/mingw-packages/mingw-w64-libusb/pkg/${MINGW_PACKAGE_PREFIX}-libusb/${MINGW_FOLD}/ ~/
cp -avr ~/mingw-packages/mingw-w64-libusb-compat-git/pkg/${MINGW_PACKAGE_PREFIX}-libusb-compat-git/${MINGW_FOLD}/ ~/
cp -avr ~/mingw-packages/mingw-w64-openocd/pkg/${MINGW_PACKAGE_PREFIX}-openocd/${MINGW_FOLD}/ ~/
mv ~/${MINGW_FOLD} ~/openocd
mv ~/openocd/share/openocd/scripts ~/openocd/scripts
cp -avr /${MINGW_FOLD}/bin/libgcc_s_dw2-1.dll ~/openocd/bin
cp -avr /${MINGW_FOLD}/bin/libjaylink-0.dll ~/openocd/bin
rm -rf ~/openocd/share

Additional notes about patching

If you want to patch the repository, a good approach would be to duplicate the /mingw-packages/mingw-w64-openocd-git folder and edit its PKGBUILD by adding some git commands.

For example, some time ago I had to add two patches to support STM32F746G Discovery and this is how I edited the PKGBUILD:

pkgver() {
  mv "${srcdir}/code" "${srcdir}/${_realname}"
  cd "${srcdir}/${_realname}"
  printf "r%s.%s" "$(git rev-list --count HEAD)" "$(git rev-parse --short HEAD)"
  printf "%s.%s.%s" "$(git fetch http://openocd.zylin.com/openocd refs/changes/54/2754/2)" "$(git fetch http://openocd.zylin.com/openocd refs/changes/55/2755/4)" "$(git checkout FETCH_HEAD)"
}

What I did was to add a printf() in the function pkgver() containing additional git commands. Maybe not the cleanest solution but it worked at the time.

Conclusions

This article serves as a useful reference for building OpenOCD using MSYS2. While it was written with the purpose of building OpenOCD for ChibiStudio, the steps provided here are applicable for any project that requires building OpenOCD on Windows using MSYS2.

It is worth noting that while these steps have been tested and verified, there may be cases where they do not work as expected. In such instances, I encourage you to reach out and leave a comment below. Your feedback will be valuable in updating and improving this documentation.