Merge branch 'doc/openocd_build2win_update' into 'master'

Updated building-openocd-windows.rst instruction

See merge request idf/esp-idf!5049

docs/en/api-guides/jtag-debugging/building-openocd-windows.rst

@@ -5,9 +5,27 @@ Building OpenOCD from Sources for Windows
 
 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 :doc:`setup-openocd-windows`.
 
-
 .. highlight:: bash
 
+.. note::
+
+    Following instructions are assumed to be runned in MSYS2 environment with MINGW32 subsystem!
+
+
+Install Dependencies
+====================
+
+Install packages that are required to compile OpenOCD::
+
+    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
 ===========================
 
@@ -16,30 +34,20 @@ The sources for the ESP32-enabled variant of OpenOCD are available from Espressi
     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
+Downloading libusb
-====================
+==================
 
-Install packages that are required to compile OpenOCD:
+Build and export variables for a following OpenOCD compilation::
 
-.. note::
+    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"
 
-    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.
-
-::
-
-    pacman -S libtool
-    pacman -S autoconf
-    pacman -S automake
-    pacman -S texinfo
-    pacman -S mingw-w64-i686-libusb-compat-git
-    pacman -S pkg-config
-
-.. note::
-
-    Installation of ``pkg-config`` is breaking operation of esp-idf toolchain. After building of OpenOCD it should be uninstalled. It be covered at the end of this instruction. To build OpenOCD again, you will need to run ``pacman -S pkg-config`` once more. This issue does not concern other packages installed in this step (before ``pkg-config``).
 
 
 Build OpenOCD
@@ -48,11 +56,15 @@ Build OpenOCD
 Proceed with configuring and building OpenOCD::
 
     cd ~/esp/openocd-esp32
+    export CPPFLAGS="$CPPFLAGS -D__USE_MINGW_ANSI_STDIO=1 -Wno-error"; export CFLAGS="$CFLAGS -Wno-error"
     ./bootstrap
-    ./configure
+    ./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
+    
 
-Optionally you can add ``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.
+Optionally you can add ``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. Also you could use ``export DESTDIR="/custom/install/dir"; make install``.
 
 .. note::
 
@@ -61,12 +73,38 @@ Optionally you can add ``make install`` step at the end. Skip it, if you have an
     * 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/openocd`` directory.
+Once ``make`` process is successfully completed, the executable of OpenOCD will be saved in ``~/esp/openocd-esp32/src`` directory.
 
-Remove ``pkg-config``, as discussed during installation of dependencies::
 
-    pacman -Rs pkg-config
+Full Listing
+============
+
+A complete described previously process is provided below for the faster execution, e.g. as a shell script::
+
+    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