GNU MCU Eclipse

A family of Eclipse CDT extensions and tools for GNU ARM & RISC-V development

How to build the OpenOCD binaries?

The latest version of the build script is a single run, multi-platform build, generating the Windows 32, Windows 64, GNU/Linux 32, GNU/Linux 64 and macOS distribution packages at once.

The script was developed on macOS, but it also runs on any recent GNU/Linux distribution (just that in this case it cannot generate the macOS package).


The prerequisites are common to all binary builds. Please follow the instructions in the separate Prerequisites for building binaries page and return when ready.

Download the build scripts repo

The build script is available from GitHub and can be viewed online.

To download it, clone the gnu-mcu-eclipse/openocd-build Git repo.

$ git clone --recurse-submodules \

Check the script

The script creates a temporary build Work/openocd folder in the user home. Although not recommended, if for any reasons you need to change this, you can redefine WORK_FOLDER variable before invoking the script.

Preload the Docker images

Docker does not require to explicitly download new images, but does this automatically at first use.

However, since the images used for this build are relatively large, it is recommended to load them explicitly before starting the build:

$ bash ~/Downloads/openocd-build.git/scripts/ preload-images

The result should look similar to:

$ docker images
REPOSITORY                  TAG                   IMAGE ID            CREATED             SIZE
ilegeul/centos32            6-xbb-v1              f695dd6cb46e        7 days ago          2.92GB
ilegeul/centos              6-xbb-v1              294dd5ee82f3        7 days ago          3.09GB
hello-world                 latest                1815c82652c0        6 months ago        1.84kB


When preparing official release, observe the following steps.

Update git repos

The GNU MCU Eclipse OpenOCD is following closely the OpenOCD master and the official RISC-V OpenOCD.

Prepare release

Update gnu-mcu-eclipse/info files:

  • CHANGES.txt (add release, scan the log)
  • (update references to commits)

In the script:

  • update the commit id OPENOCD_GIT_COMMIT to the desired one
  • commit and push (without push, the inner clone uses an older version)

Build all distribution files

Before starting a multi-platform build, check if Docker is started.

$ bash ~/Downloads/openocd-build.git/scripts/ --all

On macOS, to prevent entering sleep, use:

$ caffeinate bash ~/Downloads/openocd-build.git/scripts/ --all

About half an hour later, the output of the build script is a set of 5 files in the output folder:

$ ls -l deploy
total 31088
drwxr-xr-x  1 ilg  staff    16384 Jan  4 18:41 centos32
drwxr-xr-x  1 ilg  staff    16384 Jan  4 18:26 centos64
-rw-r--r--  1 ilg  staff        1 Jan  4 18:50 empty.sha
-rw-r--r--  1 ilg  staff  2495436 Jan  4 18:41 gnu-mcu-eclipse-openocd-0.10.0-6-20180104-1616-centos32.tgz
-rw-r--r--  1 ilg  staff      126 Jan  4 18:41 gnu-mcu-eclipse-openocd-0.10.0-6-20180104-1616-centos32.tgz.sha
-rw-r--r--  1 ilg  staff  2558621 Jan  4 18:26 gnu-mcu-eclipse-openocd-0.10.0-6-20180104-1616-centos64.tgz
-rw-r--r--  1 ilg  staff      126 Jan  4 18:26 gnu-mcu-eclipse-openocd-0.10.0-6-20180104-1616-centos64.tgz.sha
-rw-r--r--  1 ilg  staff  2669737 Jan  4 18:22 gnu-mcu-eclipse-openocd-0.10.0-6-20180104-1616-osx.tgz
-rw-r--r--  1 ilg  staff      121 Jan  4 18:22 gnu-mcu-eclipse-openocd-0.10.0-6-20180104-1616-osx.tgz.sha
-rw-r--r--  1 ilg  staff  3271104 Jan  4 18:50
-rw-r--r--  1 ilg  staff      123 Jan  4 18:50
-rw-r--r--  1 ilg  staff  3377719 Jan  4 18:37
-rw-r--r--  1 ilg  staff      123 Jan  4 18:37
drwxr-xr-x  1 ilg  staff    16384 Jan  4 18:21 osx
drwxr-xr-x  1 ilg  staff    16384 Jan  4 18:50 win32
drwxr-xr-x  1 ilg  staff    16384 Jan  4 18:37 win64

Subsequent runs

Separate platform specific builds

Instead of --all, you can use any combination of:

--win32 --win64 --linux32 --linux64 --osx


To remove most build files, use:

$ bash ~/Downloads/openocd-build.git/scripts/ clean

To also remove the repository and the output files, use:

$ bash ~/Downloads/openocd-build.git/scripts/ cleanall

Native builds

In addition to the CentOS binaries, if necessary, the script can be used to build binaries for any Linux distribution.

For such cases, simply start the script without any platform option:

$ bash ~/Downloads/openocd-build.git/scripts/

It is the responsibility of the user to meet all the prerequisites.

Install hierarchy

The procedure to install GNU MCU Eclipse OpenOCD is relatively straight forward and requires to unpack the archive.

After install, this package should create structure like this (only the first two depth levels are shown):

$ tree -L 2 ${HOME}/opt/gnu-mcu-eclipse/openocd/0.10.0-5-20171110-1117
├── bin
│   └── openocd
├── doc
│   ├── openocd.html
│   └── openocd.pdf
├── info
│   ├── BUILD.txt
│   ├── INFO.txt
│   └──
├── license
│   ├── hidapi
│   └── openocd
└── scripts
    ├── bitsbytes.tcl
    ├── board
    ├── chip
    ├── cpld
    ├── cpu
    ├── interface
    ├── mem_helper.tcl
    ├── memory.tcl
    ├── mmr_helpers.tcl
    ├── target
    ├── test
    └── tools

16 directories, 9 files

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


The binaries are distributed as portable archives, that do not need to run a setup and do not require an uninstall.


A simple test is performed by the script at the end, by launching the executable to check if all shared/dynamic libraries are correctly used.

For a true test you need to first install the package and then run the program form the final location. For example on macOS the output should look like:

$ ${HOME}/opt/gnu-mcu-eclipse/openocd/0.10.0-3-20170826-0939-dev/bin/openocd --version
GNU MCU Eclipse 64-bits Open On-Chip Debugger 0.10.0+dev-00138-g96c70022 (2017-08-26-12:40)
Licensed under GNU GPL v2
For bug reports, read


To run debug sessions on macOS, it is necessary to build images that include the debugging info:

$ bash ~/Downloads/openocd-build.git/scripts/ --without-pdf --no-strip --debug

With Xcode, create a new Cross-platform, External Build System project. Select a folder below xcode.

In the External Build Tool Configuration, use the build/osx/openocd folder.

Add the openocd.git folder to the sources.

More build details

The script is quite complex, and an attempt to explain its functionality would require some effort. For the final authoritative details, please refer to the comments available in the script.