mirror of
https://github.com/espressif/esp-idf.git
synced 2026-04-27 19:13:21 +00:00
docs(jtag): replace OpenOCD build instructions with GH workflow reference
This commit is contained in:
Erhan Kurubas
@@ -31,13 +31,10 @@ api-guides/ble/blufi.rst
|
||||
api-guides/ble/ble-feature-support-status.rst
|
||||
api-guides/file-system-considerations.rst
|
||||
api-guides/jtag-debugging/index.rst
|
||||
api-guides/jtag-debugging/building-openocd-macos.rst
|
||||
api-guides/jtag-debugging/debugging-examples.rst
|
||||
api-guides/jtag-debugging/building-openocd-windows.rst
|
||||
api-guides/jtag-debugging/configure-ft2232h-jtag.rst
|
||||
api-guides/jtag-debugging/configure-other-jtag.rst
|
||||
api-guides/jtag-debugging/using-debugger.rst
|
||||
api-guides/jtag-debugging/building-openocd-linux.rst
|
||||
api-guides/jtag-debugging/tips-and-quirks.rst
|
||||
api-guides/jtag-debugging/configure-builtin-jtag.rst
|
||||
api-guides/RF_calibration.rst
|
||||
|
||||
@@ -1,77 +0,0 @@
|
||||
***************************************
|
||||
Building OpenOCD from Sources for Linux
|
||||
***************************************
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
The following instructions are alternative to downloading binary OpenOCD from `Espressif GitHub <https://github.com/espressif/openocd-esp32/releases>`_. To quickly setup the binary OpenOCD, instead of compiling it yourself, backup and proceed to section :ref:`jtag-debugging-setup-openocd`.
|
||||
|
||||
|
||||
.. highlight:: bash
|
||||
|
||||
Download Sources of OpenOCD
|
||||
===========================
|
||||
|
||||
The sources for the {IDF_TARGET_NAME}-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands::
|
||||
|
||||
cd ~/esp
|
||||
git clone --recursive https://github.com/espressif/openocd-esp32.git
|
||||
|
||||
The clone of sources should be now saved in ``~/esp/openocd-esp32`` directory.
|
||||
|
||||
|
||||
Install Dependencies
|
||||
====================
|
||||
|
||||
Install packages that are required to compile OpenOCD.
|
||||
|
||||
.. note::
|
||||
|
||||
Install the following packages one by one, check if installation was successful and then proceed to the next package. Resolve reported problems before moving to the next step.
|
||||
|
||||
::
|
||||
|
||||
sudo apt-get install make
|
||||
sudo apt-get install libtool
|
||||
sudo apt-get install pkg-config
|
||||
sudo apt-get install autoconf
|
||||
sudo apt-get install automake
|
||||
sudo apt-get install texinfo
|
||||
sudo apt-get install libusb-1.0
|
||||
|
||||
.. note::
|
||||
|
||||
* Version of pkg-config should be 0.2.3 or above.
|
||||
* Version of autoconf should be 2.6.4 or above.
|
||||
* Version of automake should be 1.9 or above.
|
||||
* When using USB-Blaster, ASIX Presto, OpenJTAG and FT2232 as adapters, drivers libFTDI and FTD2XX need to be downloaded and installed.
|
||||
* When using CMSIS-DAP, HIDAPI is needed.
|
||||
|
||||
|
||||
Build OpenOCD
|
||||
=============
|
||||
|
||||
Proceed with configuring and building OpenOCD::
|
||||
|
||||
cd ~/esp/openocd-esp32
|
||||
./bootstrap
|
||||
./configure
|
||||
make
|
||||
|
||||
Optionally you can add ``sudo make install`` step at the end. Skip it, if you have an existing OpenOCD (from e.g., another development platform), as it may get overwritten.
|
||||
|
||||
.. note::
|
||||
|
||||
* Should an error occur, resolve it and try again until the command ``make`` works.
|
||||
* If there is a submodule problem from OpenOCD, please ``cd`` to the ``openocd-esp32`` directory and input ``git submodule update --init``.
|
||||
* If the ``./configure`` is successfully run, information of enabled JTAG will be printed under ``OpenOCD configuration summary``.
|
||||
* If the information of your device is not shown in the log, use ``./configure`` to enable it as described in ``../openocd-esp32/doc/INSTALL.txt``.
|
||||
* For details concerning compiling OpenOCD, please refer to ``openocd-esp32/README``.
|
||||
|
||||
Once ``make`` process is successfully completed, the executable of OpenOCD will be saved in ``~/openocd-esp32/bin`` directory.
|
||||
|
||||
|
||||
Next Steps
|
||||
==========
|
||||
|
||||
To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-target`.
|
||||
@@ -1,61 +0,0 @@
|
||||
***************************************
|
||||
Building OpenOCD from Sources for MacOS
|
||||
***************************************
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
The following instructions are alternative to downloading binary OpenOCD from `Espressif GitHub <https://github.com/espressif/openocd-esp32/releases>`_. To quickly setup the binary OpenOCD, instead of compiling it yourself, backup and proceed to section :ref:`jtag-debugging-setup-openocd`.
|
||||
|
||||
.. highlight:: bash
|
||||
|
||||
Download Sources of OpenOCD
|
||||
===========================
|
||||
|
||||
The sources for the {IDF_TARGET_NAME}-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands::
|
||||
|
||||
cd ~/esp
|
||||
git clone --recursive https://github.com/espressif/openocd-esp32.git
|
||||
|
||||
The clone of sources should be now saved in ``~/esp/openocd-esp32`` directory.
|
||||
|
||||
|
||||
Install Dependencies
|
||||
====================
|
||||
|
||||
Install packages that are required to compile OpenOCD using Homebrew::
|
||||
|
||||
brew install automake libtool libusb wget gcc@4.9 pkg-config
|
||||
|
||||
|
||||
Build OpenOCD
|
||||
=============
|
||||
|
||||
Proceed with configuring and building OpenOCD::
|
||||
|
||||
cd ~/esp/openocd-esp32
|
||||
./bootstrap
|
||||
./configure
|
||||
make
|
||||
|
||||
Optionally you can add ``sudo make install`` step at the end. Skip it, if you have an existing OpenOCD (from e.g., another development platform), as it may get overwritten.
|
||||
|
||||
.. note::
|
||||
|
||||
* Should an error occur, resolve it and try again until the command ``make`` works.
|
||||
* Error ``Unknown command 'raggedright'`` may indicate that the required version of ``texinfo`` was not installed on your computer or installed but was not linked to your PATH. To resolve this issue make sure ``texinfo`` is installed and PATH is adjusted prior to the ``./bootstrap`` by running::
|
||||
|
||||
brew install texinfo
|
||||
export PATH=/usr/local/opt/texinfo/bin:$PATH
|
||||
|
||||
* If there is a submodule problem from OpenOCD, please ``cd`` to the ``openocd-esp32`` directory and input ``git submodule update --init``.
|
||||
* If the ``./configure`` is successfully run, information of enabled JTAG will be printed under ``OpenOCD configuration summary``.
|
||||
* If the information of your device is not shown in the log, use ``./configure`` to enable it as described in ``../openocd-esp32/doc/INSTALL.txt``.
|
||||
* For details concerning compiling OpenOCD, please refer to ``openocd-esp32/README.OSX``.
|
||||
|
||||
Once ``make`` process is successfully completed, the executable of OpenOCD will be saved in ``~/esp/openocd-esp32/src/openocd`` directory.
|
||||
|
||||
|
||||
Next Steps
|
||||
==========
|
||||
|
||||
To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-target`.
|
||||
@@ -1,131 +0,0 @@
|
||||
*****************************************
|
||||
Building OpenOCD from Sources for Windows
|
||||
*****************************************
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
.. note::
|
||||
|
||||
This document outlines how to build a binary of OpenOCD from its source files instead of downloading the pre-built binary. For a quick setup, users can download a pre-built binary of OpenOCD from `Espressif GitHub <https://github.com/espressif/openocd-esp32/releases>`_ instead of compiling it themselves (see :ref:`jtag-debugging-setup-openocd` for more details).
|
||||
|
||||
.. note::
|
||||
|
||||
All code snippets in this document are assumed to be running in an MSYS2 shell with the MINGW32 subsystem.
|
||||
|
||||
|
||||
Install Dependencies
|
||||
====================
|
||||
|
||||
Install packages that are required to compile OpenOCD:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pacman -S --noconfirm --needed autoconf automake git make \
|
||||
mingw-w64-i686-gcc \
|
||||
mingw-w64-i686-toolchain \
|
||||
mingw-w64-i686-libtool \
|
||||
mingw-w64-i686-pkg-config \
|
||||
mingw-w64-cross-winpthreads-git \
|
||||
p7zip
|
||||
|
||||
|
||||
Download Sources of OpenOCD
|
||||
===========================
|
||||
|
||||
The sources for the {IDF_TARGET_NAME}-enabled variant of OpenOCD are available from Espressif's GitHub under https://github.com/espressif/openocd-esp32. These source files can be pulled via Git using the following commands:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd ~/esp
|
||||
git clone --recursive https://github.com/espressif/openocd-esp32.git
|
||||
|
||||
The clone of sources should be now saved in ``~/esp/openocd-esp32`` directory.
|
||||
|
||||
|
||||
Downloading libusb
|
||||
==================
|
||||
|
||||
The libusb library is also required when building OpenOCD. The following commands will download a particular release of libusb and uncompress it to the current directory.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
wget https://github.com/libusb/libusb/releases/download/v1.0.22/libusb-1.0.22.7z
|
||||
7z x -olibusb ./libusb-1.0.22.7z
|
||||
|
||||
We now need to export the following variables such that the libusb library gets linked into the OpenOCD build.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
export CPPFLAGS="$CPPFLAGS -I${PWD}/libusb/include/libusb-1.0"
|
||||
export LDFLAGS="$LDFLAGS -L${PWD}/libusb/MinGW32/.libs/dll"
|
||||
|
||||
|
||||
Build OpenOCD
|
||||
=============
|
||||
|
||||
The following commands will configure OpenOCD then build it.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd ~/esp/openocd-esp32
|
||||
export CPPFLAGS="$CPPFLAGS -D__USE_MINGW_ANSI_STDIO=1 -Wno-error"; export CFLAGS="$CFLAGS -Wno-error"
|
||||
./bootstrap
|
||||
./configure --disable-doxygen-pdf --enable-ftdi --enable-jlink --enable-ulink --build=i686-w64-mingw32 --host=i686-w64-mingw32
|
||||
make
|
||||
cp ../libusb/MinGW32/dll/libusb-1.0.dll ./src
|
||||
cp /opt/i686-w64-mingw32/bin/libwinpthread-1.dll ./src
|
||||
|
||||
|
||||
Once the build is completed, the OpenOCD binary will be placed in ``~/esp/openocd-esp32/src/``.
|
||||
|
||||
You can then optionally call ``make install``. This will copy the OpenOCD binary to a user specified location.
|
||||
|
||||
- This location can be specified when OpenOCD is configured, or by setting ``export DESTDIR="/custom/install/dir"`` before calling ``make install``.
|
||||
- If you have an existing OpenOCD (from e.g., another development platform), you may want to skip this call as your existing OpenOCD may get overwritten.
|
||||
|
||||
.. note::
|
||||
|
||||
* Should an error occur, resolve it and try again until the command ``make`` works.
|
||||
* If there is a submodule problem from OpenOCD, please ``cd`` to the ``openocd-esp32`` directory and input ``git submodule update --init``.
|
||||
* If the ``./configure`` is successfully run, information of enabled JTAG will be printed under ``OpenOCD configuration summary``.
|
||||
* If the information of your device is not shown in the log, use ``./configure`` to enable it as described in ``../openocd-esp32/doc/INSTALL.txt``.
|
||||
* For details concerning compiling OpenOCD, please refer to ``openocd-esp32/README.Windows``.
|
||||
* Don't forget to copy `libusb-1.0.dll` and `libwinpthread-1.dll` into `OOCD_INSTALLDIR/bin` from ``~/esp/openocd-esp32/src``.
|
||||
|
||||
Once ``make`` process is successfully completed, the executable of OpenOCD will be saved in ``~/esp/openocd-esp32/src`` directory.
|
||||
|
||||
|
||||
Full Listing
|
||||
============
|
||||
|
||||
For greater convenience, all of commands called throughout the OpenOCD build process have been listed in the code snippet below. Users can copy this code snippet into a shell script then execute it:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pacman -S --noconfirm --needed autoconf automake git make mingw-w64-i686-gcc mingw-w64-i686-toolchain mingw-w64-i686-libtool mingw-w64-i686-pkg-config mingw-w64-cross-winpthreads-git p7zip
|
||||
cd ~/esp
|
||||
git clone --recursive https://github.com/espressif/openocd-esp32.git
|
||||
|
||||
wget https://github.com/libusb/libusb/releases/download/v1.0.22/libusb-1.0.22.7z
|
||||
7z x -olibusb ./libusb-1.0.22.7z
|
||||
export CPPFLAGS="$CPPFLAGS -I${PWD}/libusb/include/libusb-1.0"; export LDFLAGS="$LDFLAGS -L${PWD}/libusb/MinGW32/.libs/dll"
|
||||
|
||||
export CPPFLAGS="$CPPFLAGS -D__USE_MINGW_ANSI_STDIO=1 -Wno-error"; export CFLAGS="$CFLAGS -Wno-error"
|
||||
cd ~/esp/openocd-esp32
|
||||
./bootstrap
|
||||
./configure --disable-doxygen-pdf --enable-ftdi --enable-jlink --enable-ulink --build=i686-w64-mingw32 --host=i686-w64-mingw32
|
||||
make
|
||||
cp ../libusb/MinGW32/dll/libusb-1.0.dll ./src
|
||||
cp /opt/i686-w64-mingw32/bin/libwinpthread-1.dll ./src
|
||||
|
||||
# # optional
|
||||
# export DESTDIR="$PWD"
|
||||
# make install
|
||||
# cp ./src/libusb-1.0.dll $DESTDIR/mingw32/bin
|
||||
# cp ./src/libwinpthread-1.dll $DESTDIR/mingw32/bin
|
||||
|
||||
|
||||
Next Steps
|
||||
==========
|
||||
|
||||
To carry on with debugging environment setup, proceed to section :ref:`jtag-debugging-configuring-target`.
|
||||
@@ -28,7 +28,7 @@ The document is structured as follows:
|
||||
:ref:`jtag-debugging-examples`
|
||||
If you are not familiar with GDB, check this section for debugging examples provided from :ref:`jtag-debugging-examples-eclipse` as well as from :ref:`jtag-debugging-examples-command-line`.
|
||||
:ref:`jtag-debugging-building-openocd`
|
||||
Procedure to build OpenOCD from sources for :doc:`Windows <building-openocd-windows>`, :doc:`Linux <building-openocd-linux>` and :doc:`macOS <building-openocd-macos>` operating systems.
|
||||
Reference to OpenOCD build workflow for building from sources.
|
||||
:ref:`jtag-debugging-tips-and-quirks`
|
||||
This section provides collection of tips and quirks related to JTAG debugging of {IDF_TARGET_NAME} with OpenOCD and GDB.
|
||||
|
||||
@@ -282,42 +282,9 @@ Before proceeding to examples, set up your {IDF_TARGET_NAME} target and load it
|
||||
Building OpenOCD from Sources
|
||||
-----------------------------
|
||||
|
||||
Please refer to separate documents listed below, that describe build process.
|
||||
The examples in this document use the pre-built OpenOCD binary distribution described in section :ref:`jtag-debugging-setup-openocd`.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Windows <building-openocd-windows>
|
||||
Linux <building-openocd-linux>
|
||||
macOS <building-openocd-macos>
|
||||
|
||||
The examples of invoking OpenOCD in this document assume using pre-built binary distribution described in section :ref:`jtag-debugging-setup-openocd`.
|
||||
|
||||
To use binaries build locally from sources, change the path to OpenOCD executable to ``src/openocd`` and set the ``OPENOCD_SCRIPTS`` environment variable so that OpenOCD can find the configuration files. For Linux and macOS:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd ~/esp/openocd-esp32
|
||||
export OPENOCD_SCRIPTS=$PWD/tcl
|
||||
|
||||
For Windows:
|
||||
|
||||
.. code-block:: batch
|
||||
|
||||
cd %USERPROFILE%\esp\openocd-esp32
|
||||
set "OPENOCD_SCRIPTS=%CD%\tcl"
|
||||
|
||||
Example of invoking OpenOCD build locally from sources, for Linux and macOS:
|
||||
|
||||
.. include:: {IDF_TARGET_PATH_NAME}.inc
|
||||
:start-after: run-openocd-src-linux
|
||||
:end-before: ---
|
||||
|
||||
and Windows:
|
||||
|
||||
.. include:: {IDF_TARGET_PATH_NAME}.inc
|
||||
:start-after: run-openocd-src-win
|
||||
:end-before: ---
|
||||
If you need to build OpenOCD from sources for custom requirements, please refer to the `OpenOCD build workflow <https://github.com/espressif/openocd-esp32/blob/master/.github/workflows/build_openocd.yml>`_ which demonstrates how OpenOCD is built for different platforms (Windows, Linux, macOS).
|
||||
|
||||
.. _jtag-debugging-tips-and-quirks:
|
||||
|
||||
|
||||
@@ -1,77 +0,0 @@
|
||||
******************************
|
||||
Linux 环境下从源码编译 OpenOCD
|
||||
******************************
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
除了从 `Espressif 官方 <https://github.com/espressif/openocd-esp32/releases>`_ 直接下载 OpenOCD 可执行文件，你还可以选择从源码编译得到 OpenOCD。如果想要快速设置 OpenOCD 而不是自行编译，请备份好当前文件，前往 :ref:`jtag-debugging-setup-openocd` 章节查阅。
|
||||
|
||||
|
||||
.. highlight:: bash
|
||||
|
||||
下载 OpenOCD 源码
|
||||
=================
|
||||
|
||||
支持 {IDF_TARGET_NAME} 的 OpenOCD 源代码可以从乐鑫官方的 GitHub 获得，网址为 https://github.com/espressif/openocd-esp32。请使用以下命令来下载源代码::
|
||||
|
||||
cd ~/esp
|
||||
git clone --recursive https://github.com/espressif/openocd-esp32.git
|
||||
|
||||
克隆后的源代码被保存在 ``~/esp/openocd-esp32`` 目录中。
|
||||
|
||||
|
||||
安装依赖的软件包
|
||||
================
|
||||
|
||||
安装编译 OpenOCD 所需的软件包。
|
||||
|
||||
.. note::
|
||||
|
||||
依次安装以下软件包，检查安装是否成功，然后继续下一个软件包的安装。在进行下一步操作之前，要先解决当前报告的问题。
|
||||
|
||||
::
|
||||
|
||||
sudo apt-get install make
|
||||
sudo apt-get install libtool
|
||||
sudo apt-get install pkg-config
|
||||
sudo apt-get install autoconf
|
||||
sudo apt-get install automake
|
||||
sudo apt-get install texinfo
|
||||
sudo apt-get install libusb-1.0
|
||||
|
||||
.. note::
|
||||
|
||||
* pkg-config 应为 0.2.3 或以上的版本。
|
||||
* autoconf 应为 2.6.4 或以上的版本。
|
||||
* automake 应为 1.9 或以上的版本。
|
||||
* 当使用 USB-Blaster，ASIX Presto，OpenJTAG 和 FT2232 作为适配器时，需要下载安装 libFTDI 和 FTD2XX 的驱动。
|
||||
* 当使用 CMSIS-DAP 时，需要安装 HIDAPI。
|
||||
|
||||
|
||||
构建 OpenOCD
|
||||
============
|
||||
|
||||
配置和构建 OpenOCD 的流程如下::
|
||||
|
||||
cd ~/esp/openocd-esp32
|
||||
./bootstrap
|
||||
./configure
|
||||
make
|
||||
|
||||
你可以选择最后再执行 ``sudo make install`` ，如果你已经安装过别的开发平台的 OpenOCD，请跳过这个步骤，因为它可能会覆盖掉原来的 OpenOCD。
|
||||
|
||||
.. note::
|
||||
|
||||
* 如果发生错误，请解决后再次尝试编译，直到 ``make`` 成功为止。
|
||||
* 如果 OpenOCD 存在子模块问题，请 ``cd`` 到 ``openocd-esp32`` 目录，并输入 ``git submodule update --init`` 命令。
|
||||
* 如果 ``./configure`` 成功运行，JTAG 被使能的信息会被打印在 ``OpenOCD configuration summary`` 下面。
|
||||
* 如果你的设备信息未显示在日志中，请根据 ``../openocd-esp32/doc/INSTALL.txt`` 文中的描述使用 ``./configure`` 启用它。
|
||||
* 有关编译 OpenOCD 的详细信息，请参阅 ``openocd-esp32/README``。
|
||||
|
||||
一旦 ``make`` 过程成功结束，OpenOCD 的可执行文件会被保存到 ``~/openocd-esp32/bin`` 目录中。
|
||||
|
||||
|
||||
下一步
|
||||
======
|
||||
|
||||
想要进一步配置调试环境，请前往 :ref:`jtag-debugging-configuring-target` 章节。
|
||||
@@ -1,61 +0,0 @@
|
||||
******************************
|
||||
MacOS 环境下从源码编译 OpenOCD
|
||||
******************************
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
除了从 `Espressif 官方 <https://github.com/espressif/openocd-esp32/releases>`_ 直接下载 OpenOCD 可执行文件，你还可以选择从源码编译得到 OpenOCD。如果想要快速设置 OpenOCD 而不是自行编译，请备份好当前文件，前往 :ref:`jtag-debugging-setup-openocd` 章节查阅。
|
||||
|
||||
.. highlight:: bash
|
||||
|
||||
下载 OpenOCD 源码
|
||||
=================
|
||||
|
||||
支持 {IDF_TARGET_NAME} 的 OpenOCD 源代码可以从乐鑫官方的 GitHub 获得，网址为 https://github.com/espressif/openocd-esp32。请使用以下命令来下载源代码::
|
||||
|
||||
cd ~/esp
|
||||
git clone --recursive https://github.com/espressif/openocd-esp32.git
|
||||
|
||||
克隆后的源代码被保存在 ``~/esp/openocd-esp32`` 目录中。
|
||||
|
||||
|
||||
安装依赖的软件包
|
||||
================
|
||||
|
||||
使用 Homebrew 安装编译 OpenOCD 所需的软件包::
|
||||
|
||||
brew install automake libtool libusb wget gcc@4.9 pkg-config
|
||||
|
||||
|
||||
构建 OpenOCD
|
||||
=============
|
||||
|
||||
配置和构建 OpenOCD 的流程如下::
|
||||
|
||||
cd ~/esp/openocd-esp32
|
||||
./bootstrap
|
||||
./configure
|
||||
make
|
||||
|
||||
你可以选择最后再执行 ``sudo make install`` ，如果你已经安装过别的开发平台的 OpenOCD，请跳过这个步骤，因为它可能会覆盖掉原来的 OpenOCD。
|
||||
|
||||
.. note::
|
||||
|
||||
* 如果发生错误，请解决后再次尝试编译，直到 ``make`` 成功为止。
|
||||
* 发生 ``Unknown command 'raggedright'`` 错误可能是因为安装的 ``texinfo`` 版本不对，或是由于没有将其添加到 PATH 路径。为了解决该问题，在运行 ``./bootstrap`` 前，请先运行如下命令确保安装合适版本的 ``texinfo`` 并将其添加到 PATH 路径::
|
||||
|
||||
brew install texinfo
|
||||
export PATH=/usr/local/opt/texinfo/bin:$PATH
|
||||
|
||||
* 如果 OpenOCD 存在子模块问题，请 ``cd`` 到 ``openocd-esp32`` 目录，并输入 ``git submodule update --init`` 命令。
|
||||
* 如果 ``./configure`` 成功运行，JTAG 被使能的信息会被打印在 ``OpenOCD configuration summary`` 下面。
|
||||
* 如果你的设备信息未显示在日志中，请根据 ``../openocd-esp32/doc/INSTALL.txt`` 文中的描述使用 ``./configure`` 启用它。
|
||||
* 有关编译 OpenOCD 的详细信息，请参阅 ``openocd-esp32/README.OSX``。
|
||||
|
||||
一旦 ``make`` 过程成功结束，OpenOCD 的可执行文件会被保存到 ``~/esp/openocd-esp32/src/openocd`` 目录中。
|
||||
|
||||
|
||||
下一步
|
||||
======
|
||||
|
||||
想要进一步配置调试环境，请前往 :ref:`jtag-debugging-configuring-target` 章节。
|
||||
@@ -1,131 +0,0 @@
|
||||
********************************
|
||||
Windows 环境下从源码编译 OpenOCD
|
||||
********************************
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
.. note::
|
||||
|
||||
本文介绍了如何从 OpenOCD 源文件构建二进制文件。如果你想要更快速地构建，也可以从 `乐鑫 GitHub <https://github.com/espressif/openocd-esp32/releases>`_ 直接下载 OpenOCD 的预构建二进制文件，而无需自己编译（详细信息，请参阅 :ref:`jtag-debugging-setup-openocd`）。
|
||||
|
||||
.. note::
|
||||
|
||||
本文涉及的命令行操作均在装有 MINGW32 子系统的 MSYS2 shell 环境中进行了验证。
|
||||
|
||||
|
||||
安装依赖的软件包
|
||||
================
|
||||
|
||||
安装编译 OpenOCD 所需的软件包：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pacman -S --noconfirm --needed autoconf automake git make \
|
||||
mingw-w64-i686-gcc \
|
||||
mingw-w64-i686-toolchain \
|
||||
mingw-w64-i686-libtool \
|
||||
mingw-w64-i686-pkg-config \
|
||||
mingw-w64-cross-winpthreads-git \
|
||||
p7zip
|
||||
|
||||
|
||||
下载 OpenOCD 源码
|
||||
=================
|
||||
|
||||
支持 {IDF_TARGET_NAME} 的 OpenOCD 源码可以从乐鑫官方 GitHub 获取，网址为 https://github.com/espressif/openocd-esp32。你可以在 Git 中使用以下命令来拉取源代码：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd ~/esp
|
||||
git clone --recursive https://github.com/espressif/openocd-esp32.git
|
||||
|
||||
克隆后的源代码保存在 ``~/esp/openocd-esp32`` 目录下。
|
||||
|
||||
|
||||
下载 libusb
|
||||
================
|
||||
|
||||
构建 OpenOCD 需使用 libusb 库。请执行以下命令来下载特定版本的 libusb，并将其解压至当前目录。
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
wget https://github.com/libusb/libusb/releases/download/v1.0.22/libusb-1.0.22.7z
|
||||
7z x -olibusb ./libusb-1.0.22.7z
|
||||
|
||||
现在需要导出以下变量，以便将 libusb 库与 OpenOCD 构建相关联。
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
export CPPFLAGS="$CPPFLAGS -I${PWD}/libusb/include/libusb-1.0"
|
||||
export LDFLAGS="$LDFLAGS -L${PWD}/libusb/MinGW32/.libs/dll"
|
||||
|
||||
|
||||
构建 OpenOCD
|
||||
============
|
||||
|
||||
配置和构建 OpenOCD，请参考以下命令：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd ~/esp/openocd-esp32
|
||||
export CPPFLAGS="$CPPFLAGS -D__USE_MINGW_ANSI_STDIO=1 -Wno-error"; export CFLAGS="$CFLAGS -Wno-error"
|
||||
./bootstrap
|
||||
./configure --disable-doxygen-pdf --enable-ftdi --enable-jlink --enable-ulink --build=i686-w64-mingw32 --host=i686-w64-mingw32
|
||||
make
|
||||
cp ../libusb/MinGW32/dll/libusb-1.0.dll ./src
|
||||
cp /opt/i686-w64-mingw32/bin/libwinpthread-1.dll ./src
|
||||
|
||||
|
||||
构建完成后，OpenOCD 的二进制文件将被保存于 ``~/esp/openocd-esp32/src/`` 目录下。
|
||||
|
||||
你也可以调用 ``make install``，将其复制到指定位置。
|
||||
|
||||
- 你可以在配置 OpenOCD 时指定这一位置，也可以在调用 ``make install`` 前设置 ``export DESTDIR="/custom/install/dir"``。
|
||||
- 如果你已经安装过其他开发平台的 OpenOCD，请跳过此步骤，否则原来的 OpenOCD 可能会被覆盖。
|
||||
|
||||
.. note::
|
||||
|
||||
* 如果发生错误，请解决后再次尝试编译，直到 ``make`` 成功为止。
|
||||
* 如果 OpenOCD 存在子模块问题，请 ``cd`` 到 ``openocd-esp32`` 目录，并输入 ``git submodule update --init`` 命令。
|
||||
* 如果 ``./configure`` 成功运行，JTAG 被使能的信息会被打印在 ``OpenOCD configuration summary`` 下面。
|
||||
* 如果你的设备信息未显示在日志中，请根据 ``../openocd-esp32/doc/INSTALL.txt`` 文中的描述使用 ``./configure`` 启用它。
|
||||
* 有关编译 OpenOCD 的详细信息，请参阅 ``openocd-esp32/README.Windows``。
|
||||
* 请记得将 `libusb-1.0.dll` 和 `libwinpthread-1.dll` 从 ``~/esp/openocd-esp32/src`` 复制到 `OOCD_INSTALLDIR/bin`。
|
||||
|
||||
一旦 ``make`` 过程完成，OpenOCD 的可执行文件会被保存到 ``~/esp/openocd-esp32/src/openocd`` 目录下。
|
||||
|
||||
|
||||
完整编译过程
|
||||
==============
|
||||
|
||||
OpenOCD 编译过程中所调用的所有命令都已包含在以下代码片段中，你可以将其复制到 shell 脚本中，以便快速执行:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
pacman -S --noconfirm --needed autoconf automake git make mingw-w64-i686-gcc mingw-w64-i686-toolchain mingw-w64-i686-libtool mingw-w64-i686-pkg-config mingw-w64-cross-winpthreads-git p7zip
|
||||
cd ~/esp
|
||||
git clone --recursive https://github.com/espressif/openocd-esp32.git
|
||||
|
||||
wget https://github.com/libusb/libusb/releases/download/v1.0.22/libusb-1.0.22.7z
|
||||
7z x -olibusb ./libusb-1.0.22.7z
|
||||
export CPPFLAGS="$CPPFLAGS -I${PWD}/libusb/include/libusb-1.0"; export LDFLAGS="$LDFLAGS -L${PWD}/libusb/MinGW32/.libs/dll"
|
||||
|
||||
export CPPFLAGS="$CPPFLAGS -D__USE_MINGW_ANSI_STDIO=1 -Wno-error"; export CFLAGS="$CFLAGS -Wno-error"
|
||||
cd ~/esp/openocd-esp32
|
||||
./bootstrap
|
||||
./configure --disable-doxygen-pdf --enable-ftdi --enable-jlink --enable-ulink --build=i686-w64-mingw32 --host=i686-w64-mingw32
|
||||
make
|
||||
cp ../libusb/MinGW32/dll/libusb-1.0.dll ./src
|
||||
cp /opt/i686-w64-mingw32/bin/libwinpthread-1.dll ./src
|
||||
|
||||
# # optional
|
||||
# export DESTDIR="$PWD"
|
||||
# make install
|
||||
# cp ./src/libusb-1.0.dll $DESTDIR/mingw32/bin
|
||||
# cp ./src/libwinpthread-1.dll $DESTDIR/mingw32/bin
|
||||
|
||||
|
||||
下一步
|
||||
======
|
||||
|
||||
想要进一步配置调试环境，请前往 :ref:`jtag-debugging-configuring-target` 章节。
|
||||
@@ -28,7 +28,7 @@ JTAG 调试
|
||||
:ref:`jtag-debugging-examples`
|
||||
如果你不熟悉 GDB，请查看此小节以获取 :ref:`Eclipse 集成开发环境 <jtag-debugging-examples-eclipse>` 以及 :ref:`命令行终端 <jtag-debugging-examples-command-line>` 提供的调试示例。
|
||||
:ref:`jtag-debugging-building-openocd`
|
||||
介绍如何在 :doc:`Windows <building-openocd-windows>`，:doc:`Linux <building-openocd-linux>` 和 :doc:`macOS <building-openocd-macos>` 操作系统上从源码构建 OpenOCD。
|
||||
参考 OpenOCD 构建工作流以从源码构建。
|
||||
:ref:`jtag-debugging-tips-and-quirks`
|
||||
介绍使用 OpenOCD 和 GDB 通过 JTAG 接口调试 {IDF_TARGET_NAME} 时的注意事项和补充内容。
|
||||
|
||||
@@ -282,42 +282,9 @@ OpenOCD 安装完成后就可以配置 {IDF_TARGET_NAME} 目标（即带 JTAG
|
||||
从源码构建 OpenOCD
|
||||
------------------
|
||||
|
||||
以下文档分别介绍了如何在各操作系统平台上从源码构建 OpenOCD。
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Windows <building-openocd-windows>
|
||||
Linux <building-openocd-linux>
|
||||
macOS <building-openocd-macos>
|
||||
|
||||
本文档在演示中所使用的 OpenOCD 是预编译好的二进制发行版，在 :ref:`jtag-debugging-setup-openocd` 章节中有所介绍。
|
||||
|
||||
如果要使用本地从源代码编译的 OpenOCD 程序，需要将相应可执行文件的路径修改为 ``src/openocd``，并设置 ``OPENOCD_SCRIPTS`` 环境变量，使得 OpenOCD 能够找到配置文件。Linux 和 macOS 用户可以执行:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd ~/esp/openocd-esp32
|
||||
export OPENOCD_SCRIPTS=$PWD/tcl
|
||||
|
||||
Windows 用户可以执行:
|
||||
|
||||
.. code-block:: batch
|
||||
|
||||
cd %USERPROFILE%\esp\openocd-esp32
|
||||
set "OPENOCD_SCRIPTS=%CD%\tcl"
|
||||
|
||||
针对 Linux 和 macOS 用户，运行本地编译的 OpenOCD 的示例:
|
||||
|
||||
.. include:: {IDF_TARGET_PATH_NAME}.inc
|
||||
:start-after: run-openocd-src-linux
|
||||
:end-before: ---
|
||||
|
||||
Windows 用户的示例如下:
|
||||
|
||||
.. include:: {IDF_TARGET_PATH_NAME}.inc
|
||||
:start-after: run-openocd-src-win
|
||||
:end-before: ---
|
||||
如需根据特定需求从源码构建 OpenOCD，请参考 `OpenOCD 构建工作流 <https://github.com/espressif/openocd-esp32/blob/master/.github/workflows/build_openocd.yml>`_，该工作流演示了如何在不同平台（Windows、Linux、macOS）上构建 OpenOCD。
|
||||
|
||||
.. _jtag-debugging-tips-and-quirks:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user