From fddba314dcd342849a56d6e2fab908bdb94694f3 Mon Sep 17 00:00:00 2001 From: Liviu Ionescu Date: Wed, 24 Jul 2024 16:44:27 +0300 Subject: [PATCH] website: rework common code --- website/blog/2024-07-12-web-site.md | 3 +- .../docs/developer-info/_common/_part1.mdx | 87 ---- .../docs/developer-info/_common/_part2.mdx | 312 ------------ website/docs/developer-info/_manual-tests.mdx | 58 +++ .../developer-info/_other-repositories.mdx | 9 + website/docs/developer-info/index.mdx | 463 +++++++++++++++--- .../docs/getting-started/_common/_part2.mdx | 9 - .../docs/getting-started/_common/_part3.mdx | 40 -- .../docs/getting-started/_compatibility.mdx | 7 + .../docs/getting-started/_documentation.mdx | 8 + .../getting-started/_release-schedule.mdx | 8 + website/docs/getting-started/index.md | 35 -- .../{_common/_part1.mdx => index.mdx} | 72 +++ .../install/_common/_automated-install.mdx | 5 +- .../install/_common/_automated-uninstall.mdx | 3 + website/docs/install/_common/_install.mdx | 27 - website/docs/install/_common/_manual-info.mdx | 3 + .../install/_common/_manual-install-linux.mdx | 3 + .../install/_common/_manual-install-macos.mdx | 3 + .../_common/_manual-install-windows.mdx | 3 + .../docs/install/_common/_manual-install.mdx | 3 + website/docs/install/_install-linux.mdx | 4 +- website/docs/install/_install-macos.mdx | 2 +- website/docs/install/_install-windows.mdx | 2 +- website/docs/install/_testing.mdx | 32 ++ website/docs/install/index.mdx | 56 +-- website/docs/releases/index.md | 4 + website/docs/support/_check-documentation.mdx | 3 + website/docs/support/_common/_part1.mdx | 11 - website/docs/support/_common/_part2.mdx | 48 -- website/docs/support/index.mdx | 77 ++- website/docs/test/index.mdx | 8 +- 32 files changed, 734 insertions(+), 674 deletions(-) delete mode 100644 website/docs/developer-info/_common/_part1.mdx delete mode 100644 website/docs/developer-info/_common/_part2.mdx create mode 100644 website/docs/developer-info/_manual-tests.mdx create mode 100644 website/docs/developer-info/_other-repositories.mdx delete mode 100644 website/docs/getting-started/_common/_part2.mdx delete mode 100644 website/docs/getting-started/_common/_part3.mdx create mode 100644 website/docs/getting-started/_compatibility.mdx create mode 100644 website/docs/getting-started/_documentation.mdx create mode 100644 website/docs/getting-started/_release-schedule.mdx delete mode 100644 website/docs/getting-started/index.md rename website/docs/getting-started/{_common/_part1.mdx => index.mdx} (51%) delete mode 100644 website/docs/install/_common/_install.mdx create mode 100644 website/docs/install/_testing.mdx create mode 100644 website/docs/support/_check-documentation.mdx delete mode 100644 website/docs/support/_common/_part1.mdx delete mode 100644 website/docs/support/_common/_part2.mdx diff --git a/website/blog/2024-07-12-web-site.md b/website/blog/2024-07-12-web-site.md index c1f4a76..2643db7 100644 --- a/website/blog/2024-07-12-web-site.md +++ b/website/blog/2024-07-12-web-site.md @@ -10,7 +10,8 @@ tags: --- -After some experimentation with modern site generators, the **xPack OpenOCD** +After some experimentation with modern site generators, +the **xPack OpenOCD** project has a new web site. diff --git a/website/docs/developer-info/_common/_part1.mdx b/website/docs/developer-info/_common/_part1.mdx deleted file mode 100644 index 6e8a983..0000000 --- a/website/docs/developer-info/_common/_part1.mdx +++ /dev/null @@ -1,87 +0,0 @@ -import CodeBlock from '@theme/CodeBlock'; - -import customField from '@site/src/libs/customField'; - -{/* ------------------------------------------------------------------------ */} - -This page is intended for those who want to build the xPack OpenOCD -binaries themselves. - -## The xPack Build Box - -The build scripts in this project use the **xPack Build Box** (**XBB**) -tools, which require the usual native development tools -(packed as a Docker image for GNU/Linux builds), complemented with -several binary xPacks, installed with `xpm` as development dependencies. - -For those interested in understanding how things work, a good starting point -would be to read the [XBB](https://xpack.github.io/xbb/) page. - -:::caution - -The XBB tools are intended for building standalone relocatable distributions, -thus are quite complex and perform several post-processing steps to -adjust RPATH and validate the resulting binaries. - -For the traditional `configure && make install` builds specific to Linux, -these scripts are probably too complicated and thus are not recommended -for inexperienced users. - -::: - -## Prerequisites - -The build scripts run on GNU/Linux and macOS. The Windows binaries are -generated on Intel GNU/Linux, using [mingw-w64](https://mingw-w64.org). - -For details on installing the prerequisites, please read the -[XBB prerequisites page](https://xpack.github.io/xbb/prerequisites/). - -## Get project sources - -The project is hosted on GitHub: - -- https://github.com/xpack-dev-tools/openocd-xpack.git - -To clone the stable branch (`xpack`), run the following commands in a -terminal (on Windows use the _Git Bash_ console): - -```sh -rm -rf ~/Work/xpack-dev-tools/openocd-xpack.git && \ -git clone https://github.com/xpack-dev-tools/openocd-xpack.git \ - ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -For development purposes, clone the `xpack-develop` branch: - -```sh -rm -rf ~/Work/xpack-dev-tools/openocd-xpack.git && \ -mkdir -p ~/Work/xpack-dev-tools && \ -git clone \ - --branch xpack-develop \ - https://github.com/xpack-dev-tools/openocd-xpack.git \ - ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -## Get helper sources (optional, for development purposes) - -The project has a dependency to a common **helper**, that is -normally installed as a read-only dependency; **for development -purposes**, to be able to make changes to the scripts located in the helper, -clone the `xpack-develop` branch and link it to the central -xPacks store: - -```sh -rm -rf ~/Work/xpack-dev-tools/xbb-helper-xpack.git && \ -mkdir -p ~/Work/xpack-dev-tools && \ -git clone \ - --branch xpack-develop \ - https://github.com/xpack-dev-tools/xbb-helper-xpack.git \ - ~/Work/xpack-dev-tools/xbb-helper-xpack.git && \ -xpm link -C ~/Work/xpack-dev-tools/xbb-helper-xpack.git -``` - -For more details the how a writeable helper can be used via -`xpm link`, please see the -[XBB](https://xpack.github.io/xbb/#writable-helper-scripts) documentation. - diff --git a/website/docs/developer-info/_common/_part2.mdx b/website/docs/developer-info/_common/_part2.mdx deleted file mode 100644 index d6474a3..0000000 --- a/website/docs/developer-info/_common/_part2.mdx +++ /dev/null @@ -1,312 +0,0 @@ -import customField from '@site/src/libs/customField'; - -{/* ------------------------------------------------------------------------ */} - -## How to build - -The builds require dedicated machines for each platform -(Intel GNU/Linux, Arm 32 GNU/Linux, Arm 64 GNU/Linux, -Intel macOS and Apple Silicon macOS). - -### Update the repo - -```sh -git -C ~/Work/xpack-dev-tools/openocd-xpack.git pull -``` - -and, if needed, the helper, when using a writeable helper: - -```sh -git -C ~/Work/xpack-dev-tools/xbb-helper-xpack.git pull -``` - -### xPack actions - -The following instructions make use of xPack actions, which are a -an extension of npm scripts, i.e. sequences of commands executed -via `xpm run ` in an -environment where the PATH is adjusted to include the current project -dependencies. - -To see the commands associated with each action, see the `xpack.actions` -definitions in the `package.json` file. - -The [xPack C/C++ Managed Build Tools](https://marketplace.visualstudio.com/items?itemName=ilg-vscode.xpack) -Visual Studio Code extension -provides convenient upport to invoke xPack actions from the VS Code. - -### Intel macOS - -To prepare the native build on an Intel Mac: - -```sh -xpm run install -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ -xpm install --config darwin-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -or, with the writeable helper: - -```sh -xpm run install -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ -xpm run link-deps -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ -xpm install --config darwin-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -To run the build: - -```sh -xpm run build --config darwin-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -or, for more verbosity: - -```sh -xpm run build-develop --config darwin-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -About 10 minutes later, the output of the build script is a compressed -archive and its SHA signature, created in the `deploy` folder: - -* xpack-openocd-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-darwin-x64.tar.gz -* xpack-openocd-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-darwin-x64.tar.gz.sha - -To rerun the build, invoke the deep-clean action and repeat from install: - -```sh -xpm run deep-clean --config darwin-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -#### Apple Silicon macOS - -To prepare the native build on an Apple Silicon Mac: - -```sh -xpm run install -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ -xpm install --config darwin-arm64 -C ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -or, with the writeable helper: - -```sh -xpm run install -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ -xpm run link-deps -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ -xpm install --config darwin-arm64 -C ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -To run the build: - -```sh -xpm run build --config darwin-arm64 -C ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -or, for more verbosity: - -```sh -xpm run build-develop --config darwin-arm64 -C ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -Several minutes later, the output of the build script is a compressed -archive and its SHA signature, created in the `deploy` folder: - -* xpack-openocd-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-darwin-arm64.tar.gz -* xpack-openocd-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-darwin-arm64.tar.gz.sha - -To rerun the build, invoke the deep-clean action and repeat from install: - -```sh -xpm run deep-clean --config darwin-arm64 -C ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -#### Intel GNU/Linux - -The docker builds run on a 64-bit Intel GNU/Linux. - -##### Build the Intel GNU/Linux binaries - -To prepare the build on Intel GNU/Linux: - -```sh -xpm run install -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ -xpm run docker-prepare --config linux-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -or, with the writeable helper: - -```sh -xpm run install -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ -xpm run link-deps -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ -xpm run docker-prepare --config linux-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ -xpm run docker-link-deps --config linux-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -To run the build: - -```sh -xpm run docker-build --config linux-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -or, for more verbosity: - -```sh -xpm run docker-build-develop --config linux-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -Several minutes later, the output of the build script is a compressed -archive and its SHA signature, created in the `deploy` folder: - -* xpack-openocd-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-linux-x64.tar.gz -* xpack-openocd-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-linux-x64.tar.gz.sha - -To rerun the build, invoke the deep-clean action and repeat from docker-prepare: - -```sh -xpm run deep-clean --config linux-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -##### Build the Intel Windows binaries - -To prepare the build on Intel GNU/Linux: - -```sh -xpm run install -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ -xpm run docker-prepare --config win32-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -or, with the writeable helper: - -```sh -xpm run install -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ -xpm run link-deps -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ -xpm run docker-prepare --config win32-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ -xpm run docker-link-deps --config win32-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -To run the build: - -```sh -xpm run docker-build --config win32-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -or, for more verbosity: - -```sh -xpm run docker-build-develop --config win32-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -About 5 minutes later, the output of the build script is a compressed -archive and its SHA signature, created in the `deploy` folder: - -* xpack-openocd-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-win32-x64.zip -* xpack-openocd-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-win32-x64.zip.sha - -To rerun the build, invoke the deep-clean action and repeat from docker-prepare: - -```sh -xpm run deep-clean --config win32-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -#### Arm GNU/Linux 64-bit - -To prepare the docker build on a 64-bit aarch64 GNU/Linux machine: - -```sh -xpm run install -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ -xpm run docker-prepare --config linux-arm64 -C ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -or, with the writeable helper: - -```sh -xpm run install -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ -xpm run link-deps -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ -xpm run docker-prepare --config linux-arm64 -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ -xpm run docker-link-deps --config linux-arm64 -C ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -To run the build: - -```sh -xpm run docker-build --config linux-arm64 -C ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -or, for more verbosity: - -```sh -xpm run docker-build-develop --config linux-arm64 -C ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -About 10 minutes later, the output of the build script is a compressed -archive and its SHA signature, created in the `deploy` folder: - -* xpack-openocd-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-linux-arm64.tar.gz -* xpack-openocd-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-linux-arm64.tar.gz.sha - -To rerun the build, invoke the deep-clean action and repeat from docker-prepare: - -```sh -xpm run deep-clean --config linux-arm64 -C ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -#### Arm GNU/Linux 32-bit - -To prepare the docker build on a 32-bit armhf GNU/Linux machine: - -```sh -xpm run install -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ -xpm run docker-prepare --config linux-arm -C ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -or, with the writeable helper: - -```sh -xpm run install -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ -xpm run link-deps -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ -xpm run docker-prepare --config linux-arm -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ -xpm run docker-link-deps --config linux-arm -C ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -To run the build: - -```sh -xpm run docker-build --config linux-arm -C ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -or, for more verbosity: - -```sh -xpm run docker-build-develop --config linux-arm -C ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -About 10 minutes later, the output of the build script is a compressed -archive and its SHA signature, created in the `deploy` folder: - -* xpack-openocd-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-linux-arm.tar.gz -* xpack-openocd-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-linux-arm.tar.gz.sha - -To rerun the build, invoke the deep-clean action and repeat from docker-prepare: - -```sh -xpm run deep-clean --config linux-arm -C ~/Work/xpack-dev-tools/openocd-xpack.git -``` - -### How to build a debug version - -In some cases it is necessary to run a debug session with the binaries. - -For these cases, the build script accepts the `--debug` options. - -There are also xPack actions that use this option (`build-develop-debug` -and `docker-build-develop-debug`). - -### Files cache - -The XBB build scripts use a local cache such that files are downloaded only -during the first run, later runs being able to use the cached files. - -However, occasionally some servers may not be available, and the builds -may fail. - -The workaround is to manually download the files from alternate -locations (like -https://github.com/xpack-dev-tools/files-cache/tree/master/libs), -place them in the XBB cache (`Work/cache`) and restart the build. diff --git a/website/docs/developer-info/_manual-tests.mdx b/website/docs/developer-info/_manual-tests.mdx new file mode 100644 index 0000000..5542ee1 --- /dev/null +++ b/website/docs/developer-info/_manual-tests.mdx @@ -0,0 +1,58 @@ + +import CodeBlock from '@theme/CodeBlock'; + +import customField from '@site/src/libs/customField'; + +{/* ------------------------------------------------------------------------ */} + +### Manual tests + +For the simplest functional case, plug a common board like the +STM32F4DISCOVERY into an USB port, start the program and check +if the CPU is identified. + +Note: If this is the first time openocd is executed, on GNU/Linux +it is necessary +to configure the rights, otherwise LIBUSB will issue the _libusb_open +failed: LIBUSB_ERROR_ACCESS_ error. + + { +`sudo cp ~/Downloads/xpack-openocd-${ customField('upstreamVersion') }-${ customField('xpackSubversion') }/contrib/60-openocd.rules /etc/udev/rules.d +sudo udevadm control --reload-rules` +} + +Then it is possible to start openocd: + + { +`$ .../bin/openocd -f "board/stm32f4discovery.cfg" +xPack Open On-Chip Debugger ${ customField('upstreamVersion') }-01004-g9ea7f3d64-dirty +Licensed under GNU GPL v2 +For bug reports, read + https://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 +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 V2J39S0 (API v2) VID:PID 0483:3748 +Info : Target voltage: 2.901598 +Info : [stm32f4x.cpu] Cortex-M4 r0p1 processor detected +Info : [stm32f4x.cpu] target has 6 breakpoints, 4 watchpoints +Info : starting gdb server for stm32f4x.cpu on 3333 +Info : Listening on port 3333 for gdb connections +[stm32f4x.cpu] halted due to breakpoint, current mode: Handler HardFault +xPSR: 0x61000003 pc: 0x080002d6 msp: 0x2001ff78 +^C +shutdown command invoked` +} + +Note: on recent macOS systems it might be necessary to allow individual +programs to run. + +For a more thorough test, run a debug session with +the Eclipse STM32F4DISCOVERY blinky test +available in the xpack-arm-none-eabi-openocd package, which uses +the `-f "board/stm32f4discovery.cfg"` configuration file +(import the `arm-f4b-fs` project and start the `arm-f4b-fs-debug-oocd` +launcher). diff --git a/website/docs/developer-info/_other-repositories.mdx b/website/docs/developer-info/_other-repositories.mdx new file mode 100644 index 0000000..f2407f2 --- /dev/null +++ b/website/docs/developer-info/_other-repositories.mdx @@ -0,0 +1,9 @@ + +{/* ------------------------------------------------------------------------ */} + +## Other repositories + +Other repositories in use are: + +- https://github.com/openocd-org/openocd.git - a read-only mirror of the + upstream OpenOCD (git://git.code.sf.net/p/openocd/code) diff --git a/website/docs/developer-info/index.mdx b/website/docs/developer-info/index.mdx index eb76b8e..321068a 100644 --- a/website/docs/developer-info/index.mdx +++ b/website/docs/developer-info/index.mdx @@ -1,4 +1,8 @@ --- + +# DO NOT EDIT! +# Automatically generated from xbb-helper/templates/docusaurus/common. + title: Information for xPack OpenOCD developers date: 2024-11-12 20:33:00 +0300 @@ -9,72 +13,403 @@ import CodeBlock from '@theme/CodeBlock'; import customField from '@site/src/libs/customField'; -import Part1 from './_common/_part1.mdx'; -import Part2 from './_common/_part2.mdx' +import OtherRepositories from './_other-repositories.mdx'; +import ManualTests from './_manual-tests.mdx' {/* ------------------------------------------------------------------------ */} [![license](https://img.shields.io/github/license/xpack-dev-tools/openocd-xpack)](https://github.com/xpack-dev-tools/openocd-xpack/blob/xpack/LICENSE) - - -## Other repositories - -Other repositories in use are: - -- https://github.com/openocd-org/openocd.git - a read-only mirror of the - upstream OpenOCD (git://git.code.sf.net/p/openocd/code) - - - -### Manual tests - -For the simplest functional case, plug a common board like the -STM32F4DISCOVERY into an USB port, start the program and check -if the CPU is identified. - -Note: If this is the first time openocd is executed, on GNU/Linux -it is necessary -to configure the rights, otherwise LIBUSB will issue the _libusb_open -failed: LIBUSB_ERROR_ACCESS_ error. - - { -`sudo cp ~/Downloads/xpack-openocd-${ customField('upstreamVersion') }-${ customField('xpackSubversion') }/contrib/60-openocd.rules /etc/udev/rules.d -sudo udevadm control --reload-rules` -} - -Then it is possible to start openocd: - - { -`$ .../bin/openocd -f "board/stm32f4discovery.cfg" -xPack Open On-Chip Debugger ${ customField('upstreamVersion') }-01004-g9ea7f3d64-dirty -Licensed under GNU GPL v2 -For bug reports, read - https://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 -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 V2J39S0 (API v2) VID:PID 0483:3748 -Info : Target voltage: 2.901598 -Info : [stm32f4x.cpu] Cortex-M4 r0p1 processor detected -Info : [stm32f4x.cpu] target has 6 breakpoints, 4 watchpoints -Info : starting gdb server for stm32f4x.cpu on 3333 -Info : Listening on port 3333 for gdb connections -[stm32f4x.cpu] halted due to breakpoint, current mode: Handler HardFault -xPSR: 0x61000003 pc: 0x080002d6 msp: 0x2001ff78 -^C -shutdown command invoked` -} - -Note: on recent macOS systems it might be necessary to allow individual -programs to run. - -For a more thorough test, run a debug session with -the Eclipse STM32F4DISCOVERY blinky test -available in the xpack-arm-none-eabi-openocd package, which uses -the `-f "board/stm32f4discovery.cfg"` configuration file -(import the `arm-f4b-fs` project and start the `arm-f4b-fs-debug-oocd` -launcher). +This page is intended for those who want to build the xPack OpenOCD +binaries themselves. + +## The xPack Build Box + +The build scripts in this project use the **xPack Build Box** (**XBB**) +tools, which require the usual native development tools +(packed as a Docker image for GNU/Linux builds), complemented with +several binary xPacks, installed with `xpm` as development dependencies. + +For those interested in understanding how things work, a good starting point +would be to read the [XBB](https://xpack.github.io/xbb/) page. + +:::caution + +The XBB tools are intended for building standalone relocatable distributions, +thus are quite complex and perform several post-processing steps to +adjust RPATH and validate the resulting binaries. + +For the traditional `configure && make install` builds specific to Linux, +these scripts are probably too complicated and thus are not recommended +for inexperienced users. + +::: + +## Prerequisites + +The build scripts run on GNU/Linux and macOS. The Windows binaries are +generated on Intel GNU/Linux, using [mingw-w64](https://mingw-w64.org). + +For details on installing the prerequisites, please read the +[XBB prerequisites page](https://xpack.github.io/xbb/prerequisites/). + +## Get project sources + +The project is hosted on GitHub: + +- https://github.com/xpack-dev-tools/openocd-xpack.git + +To clone the stable branch (`xpack`), run the following commands in a +terminal (on Windows use the _Git Bash_ console): + +```sh +rm -rf ~/Work/xpack-dev-tools/openocd-xpack.git && \ +git clone https://github.com/xpack-dev-tools/openocd-xpack.git \ + ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +For development purposes, clone the `xpack-develop` branch: + +```sh +rm -rf ~/Work/xpack-dev-tools/openocd-xpack.git && \ +mkdir -p ~/Work/xpack-dev-tools && \ +git clone \ + --branch xpack-develop \ + https://github.com/xpack-dev-tools/openocd-xpack.git \ + ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +## Get helper sources (optional, for development purposes) + +The project has a dependency to a common **helper**, that is +normally installed as a read-only dependency; **for development +purposes**, to be able to make changes to the scripts located in the helper, +clone the `xpack-develop` branch and link it to the central +xPacks store: + +```sh +rm -rf ~/Work/xpack-dev-tools/xbb-helper-xpack.git && \ +mkdir -p ~/Work/xpack-dev-tools && \ +git clone \ + --branch xpack-develop \ + https://github.com/xpack-dev-tools/xbb-helper-xpack.git \ + ~/Work/xpack-dev-tools/xbb-helper-xpack.git && \ +xpm link -C ~/Work/xpack-dev-tools/xbb-helper-xpack.git +``` + +For more details the how a writeable helper can be used via +`xpm link`, please see the +[XBB](https://xpack.github.io/xbb/#writable-helper-scripts) documentation. + + + +## How to build + +The builds require dedicated machines for each platform +(Intel GNU/Linux, Arm 32 GNU/Linux, Arm 64 GNU/Linux, +Intel macOS and Apple Silicon macOS). + +### Update the repo + +```sh +git -C ~/Work/xpack-dev-tools/openocd-xpack.git pull +``` + +and, if needed, the helper, when using a writeable helper: + +```sh +git -C ~/Work/xpack-dev-tools/xbb-helper-xpack.git pull +``` + +### xPack actions + +The following instructions make use of xPack actions, which are a +an extension of npm scripts, i.e. sequences of commands executed +via `xpm run ` in an +environment where the PATH is adjusted to include the current project +dependencies. + +To see the commands associated with each action, see the `xpack.actions` +definitions in the `package.json` file. + +The [xPack C/C++ Managed Build Tools](https://marketplace.visualstudio.com/items?itemName=ilg-vscode.xpack) +Visual Studio Code extension +provides convenient upport to invoke xPack actions from the VS Code. + +### Intel macOS + +To prepare the native build on an Intel Mac: + +```sh +xpm run install -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ +xpm install --config darwin-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +or, with the writeable helper: + +```sh +xpm run install -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ +xpm run link-deps -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ +xpm install --config darwin-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +To run the build: + +```sh +xpm run build --config darwin-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +or, for more verbosity: + +```sh +xpm run build-develop --config darwin-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +About 10 minutes later, the output of the build script is a compressed +archive and its SHA signature, created in the `deploy` folder: + +* xpack-openocd-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-darwin-x64.tar.gz +* xpack-openocd-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-darwin-x64.tar.gz.sha + +To rerun the build, invoke the deep-clean action and repeat from install: + +```sh +xpm run deep-clean --config darwin-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +#### Apple Silicon macOS + +To prepare the native build on an Apple Silicon Mac: + +```sh +xpm run install -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ +xpm install --config darwin-arm64 -C ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +or, with the writeable helper: + +```sh +xpm run install -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ +xpm run link-deps -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ +xpm install --config darwin-arm64 -C ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +To run the build: + +```sh +xpm run build --config darwin-arm64 -C ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +or, for more verbosity: + +```sh +xpm run build-develop --config darwin-arm64 -C ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +Several minutes later, the output of the build script is a compressed +archive and its SHA signature, created in the `deploy` folder: + +* xpack-openocd-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-darwin-arm64.tar.gz +* xpack-openocd-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-darwin-arm64.tar.gz.sha + +To rerun the build, invoke the deep-clean action and repeat from install: + +```sh +xpm run deep-clean --config darwin-arm64 -C ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +#### Intel GNU/Linux + +The docker builds run on a 64-bit Intel GNU/Linux. + +##### Build the Intel GNU/Linux binaries + +To prepare the build on Intel GNU/Linux: + +```sh +xpm run install -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ +xpm run docker-prepare --config linux-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +or, with the writeable helper: + +```sh +xpm run install -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ +xpm run link-deps -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ +xpm run docker-prepare --config linux-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ +xpm run docker-link-deps --config linux-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +To run the build: + +```sh +xpm run docker-build --config linux-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +or, for more verbosity: + +```sh +xpm run docker-build-develop --config linux-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +Several minutes later, the output of the build script is a compressed +archive and its SHA signature, created in the `deploy` folder: + +* xpack-openocd-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-linux-x64.tar.gz +* xpack-openocd-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-linux-x64.tar.gz.sha + +To rerun the build, invoke the deep-clean action and repeat from docker-prepare: + +```sh +xpm run deep-clean --config linux-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +##### Build the Intel Windows binaries + +To prepare the build on Intel GNU/Linux: + +```sh +xpm run install -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ +xpm run docker-prepare --config win32-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +or, with the writeable helper: + +```sh +xpm run install -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ +xpm run link-deps -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ +xpm run docker-prepare --config win32-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ +xpm run docker-link-deps --config win32-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +To run the build: + +```sh +xpm run docker-build --config win32-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +or, for more verbosity: + +```sh +xpm run docker-build-develop --config win32-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +About 5 minutes later, the output of the build script is a compressed +archive and its SHA signature, created in the `deploy` folder: + +* xpack-openocd-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-win32-x64.zip +* xpack-openocd-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-win32-x64.zip.sha + +To rerun the build, invoke the deep-clean action and repeat from docker-prepare: + +```sh +xpm run deep-clean --config win32-x64 -C ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +#### Arm GNU/Linux 64-bit + +To prepare the docker build on a 64-bit aarch64 GNU/Linux machine: + +```sh +xpm run install -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ +xpm run docker-prepare --config linux-arm64 -C ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +or, with the writeable helper: + +```sh +xpm run install -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ +xpm run link-deps -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ +xpm run docker-prepare --config linux-arm64 -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ +xpm run docker-link-deps --config linux-arm64 -C ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +To run the build: + +```sh +xpm run docker-build --config linux-arm64 -C ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +or, for more verbosity: + +```sh +xpm run docker-build-develop --config linux-arm64 -C ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +About 10 minutes later, the output of the build script is a compressed +archive and its SHA signature, created in the `deploy` folder: + +* xpack-openocd-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-linux-arm64.tar.gz +* xpack-openocd-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-linux-arm64.tar.gz.sha + +To rerun the build, invoke the deep-clean action and repeat from docker-prepare: + +```sh +xpm run deep-clean --config linux-arm64 -C ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +#### Arm GNU/Linux 32-bit + +To prepare the docker build on a 32-bit armhf GNU/Linux machine: + +```sh +xpm run install -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ +xpm run docker-prepare --config linux-arm -C ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +or, with the writeable helper: + +```sh +xpm run install -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ +xpm run link-deps -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ +xpm run docker-prepare --config linux-arm -C ~/Work/xpack-dev-tools/openocd-xpack.git && \ +xpm run docker-link-deps --config linux-arm -C ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +To run the build: + +```sh +xpm run docker-build --config linux-arm -C ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +or, for more verbosity: + +```sh +xpm run docker-build-develop --config linux-arm -C ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +About 10 minutes later, the output of the build script is a compressed +archive and its SHA signature, created in the `deploy` folder: + +* xpack-openocd-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-linux-arm.tar.gz +* xpack-openocd-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-linux-arm.tar.gz.sha + +To rerun the build, invoke the deep-clean action and repeat from docker-prepare: + +```sh +xpm run deep-clean --config linux-arm -C ~/Work/xpack-dev-tools/openocd-xpack.git +``` + +### How to build a debug version + +In some cases it is necessary to run a debug session with the binaries. + +For these cases, the build script accepts the `--debug` options. + +There are also xPack actions that use this option (`build-develop-debug` +and `docker-build-develop-debug`). + +### Files cache + +The XBB build scripts use a local cache such that files are downloaded only +during the first run, later runs being able to use the cached files. + +However, occasionally some servers may not be available, and the builds +may fail. + +The workaround is to manually download the files from alternate +locations (like +https://github.com/xpack-dev-tools/files-cache/tree/master/libs), +place them in the XBB cache (`Work/cache`) and restart the build. + + diff --git a/website/docs/getting-started/_common/_part2.mdx b/website/docs/getting-started/_common/_part2.mdx deleted file mode 100644 index 0923e75..0000000 --- a/website/docs/getting-started/_common/_part2.mdx +++ /dev/null @@ -1,9 +0,0 @@ -## Install - -The binaries can be installed automatically as **binary xPacks** or manually as -**portable archives**. - -The details of installing the **xPack OpenOCD** on various platforms are -presented in the separate -[Install Guide](/docs/install/) page. - diff --git a/website/docs/getting-started/_common/_part3.mdx b/website/docs/getting-started/_common/_part3.mdx deleted file mode 100644 index 07a42e1..0000000 --- a/website/docs/getting-started/_common/_part3.mdx +++ /dev/null @@ -1,40 +0,0 @@ -## Support - -The quick advice for getting support is to use the -[GitHub Discussions](https://github.com/xpack-dev-tools/openocd-xpack/discussions/). - -For additional information, please refer to the -[Help Center](/docs/support/) page. - -## Change log - -The release and change log is available in the repository -[`CHANGELOG.md`](https://github.com/xpack-dev-tools/openocd-xpack/blob/xpack/CHANGELOG.md) file. - -## Maintainer & Developer info - -For information on the workflow used to make releases, please see the -[Maintainer Info](/docs/maintainer-info/) page. - -For information on how to build the binaries, please see the -[Developer Info](/docs/developer-info/) page. - -However, the ultimate source for details are the build scripts themselves, -all available from the -[`openocd-xpack.git/scripts`](https://github.com/xpack-dev-tools/openocd-xpack/tree/xpack/scripts/) -folder. The scripts include common code from the [`@xpack-dev-tools/xbb-helper`](https://github.com/xpack-dev-tools/xbb-helper-xpack) package. - -## License - -Unless otherwise stated, the original content is released under the terms of the -[MIT License](https://opensource.org/licenses/mit/), -with all rights reserved to -[Liviu Ionescu](https://github.com/ilg-ul). - -The binary distributions include several open-source components; the -corresponding licenses are available in the installed -`distro-info/licenses` folder. - -## Releases - -The list of releases is available in the [Releases](/docs/releases/) pages. diff --git a/website/docs/getting-started/_compatibility.mdx b/website/docs/getting-started/_compatibility.mdx new file mode 100644 index 0000000..ee3825f --- /dev/null +++ b/website/docs/getting-started/_compatibility.mdx @@ -0,0 +1,7 @@ + +{/* ------------------------------------------------------------------------ */} + +## Compatibility + +The **xPack OpenOCD** is fully compatible with the original **OpenOCD** +source distribution. diff --git a/website/docs/getting-started/_documentation.mdx b/website/docs/getting-started/_documentation.mdx new file mode 100644 index 0000000..7f64349 --- /dev/null +++ b/website/docs/getting-started/_documentation.mdx @@ -0,0 +1,8 @@ + +{/* ------------------------------------------------------------------------ */} + +## Documentation + +The original OpenOCD documentation is available from the project web: + +- https://openocd.org/pages/documentation.html [![PDF](/img/pdf-24.png)](https://openocd.org/doc/pdf/openocd.pdf) diff --git a/website/docs/getting-started/_release-schedule.mdx b/website/docs/getting-started/_release-schedule.mdx new file mode 100644 index 0000000..159662f --- /dev/null +++ b/website/docs/getting-started/_release-schedule.mdx @@ -0,0 +1,8 @@ + +{/* ------------------------------------------------------------------------ */} + +## Release schedule + +This distribution generally follows the official +[OpenOCD](https://openocd.org), with +additional releases based on the current Git form time to time. diff --git a/website/docs/getting-started/index.md b/website/docs/getting-started/index.md deleted file mode 100644 index 41d7658..0000000 --- a/website/docs/getting-started/index.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Getting Started with xPack OpenOCD - -date: 2020-09-28 17:49:00 +0300 - ---- - -import Part1 from './_common/_part1.mdx'; -import Part2 from './_common/_part2.mdx' -import Part3 from './_common/_part3.mdx' - -{/* ------------------------------------------------------------------------ */} - - - -## Compatibility - -The **xPack OpenOCD** is fully compatible with the original **OpenOCD** -source distribution. - - - -## Documentation - -The original OpenOCD documentation is available from the project web: - -- https://openocd.org/pages/documentation.html [![PDF](/img/pdf-24.png)](https://openocd.org/doc/pdf/openocd.pdf) - -## Release schedule - -This distribution generally follows the official -[OpenOCD](https://openocd.org), with -additional releases based on the current Git form time to time. - - diff --git a/website/docs/getting-started/_common/_part1.mdx b/website/docs/getting-started/index.mdx similarity index 51% rename from website/docs/getting-started/_common/_part1.mdx rename to website/docs/getting-started/index.mdx index 6e2446e..e5e46d0 100644 --- a/website/docs/getting-started/_common/_part1.mdx +++ b/website/docs/getting-started/index.mdx @@ -1,3 +1,20 @@ +--- + +# DO NOT EDIT! +# Automatically generated from xbb-helper/templates/docusaurus/common. + +title: Getting Started with xPack OpenOCD + +date: 2020-09-28 17:49:00 +0300 + +--- + +import Compatibility from './_compatibility.mdx'; +import Documentation from './_documentation.mdx' +import ReleaseSchedule from './_release-schedule.mdx' + +{/* ------------------------------------------------------------------------ */} + [![GitHub package.json version](https://img.shields.io/github/package-json/v/xpack-dev-tools/openocd-xpack)](https://github.com/xpack-dev-tools/openocd-xpack/blob/xpack/package.json) [![GitHub release (latest by date)](https://img.shields.io/github/v/release/xpack-dev-tools/openocd-xpack)](https://github.com/xpack-dev-tools/openocd-xpack/releases/) [![npm (scoped)](https://img.shields.io/npm/v/@xpack-dev-tools/openocd.svg?color=blue)](https://www.npmjs.com/package/@xpack-dev-tools/openocd/) @@ -47,3 +64,58 @@ The main advantages of using the **xPack OpenOCD** are: - projects can be tied to specific tools versions; this provides a good reproducibility, especially useful in **CI/CD** environments. + + +## Install + +The binaries can be installed automatically as **binary xPacks** or manually as +**portable archives**. + +The details of installing the **xPack OpenOCD** on various platforms are +presented in the separate +[Install Guide](/docs/install/) page. + + + + + +## Support + +The quick advice for getting support is to use the +[GitHub Discussions](https://github.com/xpack-dev-tools/openocd-xpack/discussions/). + +For additional information, please refer to the +[Help Center](/docs/support/) page. + +## Change log + +The release and change log is available in the repository +[`CHANGELOG.md`](https://github.com/xpack-dev-tools/openocd-xpack/blob/xpack/CHANGELOG.md) file. + +## Maintainer & Developer info + +For information on the workflow used to make releases, please see the +[Maintainer Info](/docs/maintainer-info/) page. + +For information on how to build the binaries, please see the +[Developer Info](/docs/developer-info/) page. + +However, the ultimate source for details are the build scripts themselves, +all available from the +[`openocd-xpack.git/scripts`](https://github.com/xpack-dev-tools/openocd-xpack/tree/xpack/scripts/) +folder. The scripts include common code from the [`@xpack-dev-tools/xbb-helper`](https://github.com/xpack-dev-tools/xbb-helper-xpack) package. + +## License + +Unless otherwise stated, the original content is released under the terms of the +[MIT License](https://opensource.org/licenses/mit/), +with all rights reserved to +[Liviu Ionescu](https://github.com/ilg-ul). + +The binary distributions include several open-source components; the +corresponding licenses are available in the installed +`distro-info/licenses` folder. + +## Releases + +The list of releases is available in the [Releases](/docs/releases/) pages. diff --git a/website/docs/install/_common/_automated-install.mdx b/website/docs/install/_common/_automated-install.mdx index 33090c9..c006cbd 100644 --- a/website/docs/install/_common/_automated-install.mdx +++ b/website/docs/install/_common/_automated-install.mdx @@ -1,3 +1,6 @@ +{/* DO NOT EDIT! */} +{/* Automatically generated from xbb-helper/templates/docusaurus/common. */} + import CodeBlock from '@theme/CodeBlock'; import Admonition from '@theme/Admonition'; @@ -117,7 +120,7 @@ The main result is a set of : }
-PATH +PATH setup With all binary tools installed in `xpacks/.bin`, the project build configurations need a single PATH adjustment: diff --git a/website/docs/install/_common/_automated-uninstall.mdx b/website/docs/install/_common/_automated-uninstall.mdx index 8bc5df1..b0c2326 100644 --- a/website/docs/install/_common/_automated-uninstall.mdx +++ b/website/docs/install/_common/_automated-uninstall.mdx @@ -1,3 +1,6 @@ +{/* DO NOT EDIT! */} +{/* Automatically generated from xbb-helper/templates/docusaurus/common. */} + import CodeBlock from '@theme/CodeBlock'; import customField from '@site/src/libs/customField'; diff --git a/website/docs/install/_common/_install.mdx b/website/docs/install/_common/_install.mdx deleted file mode 100644 index 649a572..0000000 --- a/website/docs/install/_common/_install.mdx +++ /dev/null @@ -1,27 +0,0 @@ -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; - -import customField from '@site/src/libs/customField'; - -import InstallWindows from '../_install-windows.mdx'; -import InstallMacOS from '../_install-macos.mdx'; -import InstallLinux from '../_install-linux.mdx'; - -{/* ------------------------------------------------------------------------ */} - -The **xPack OpenOCD** can be installed automatically, using the `xpm` command -(the recommended method), or manually, by downloading and unpacking one of the -portable archives. - - - - - - - - - - - - diff --git a/website/docs/install/_common/_manual-info.mdx b/website/docs/install/_common/_manual-info.mdx index db372a9..fa85d0e 100644 --- a/website/docs/install/_common/_manual-info.mdx +++ b/website/docs/install/_common/_manual-info.mdx @@ -1,3 +1,6 @@ +{/* DO NOT EDIT! */} +{/* Automatically generated from xbb-helper/templates/docusaurus/common. */} + :::info For manual installs, the recommended diff --git a/website/docs/install/_common/_manual-install-linux.mdx b/website/docs/install/_common/_manual-install-linux.mdx index e547f20..b03b33d 100644 --- a/website/docs/install/_common/_manual-install-linux.mdx +++ b/website/docs/install/_common/_manual-install-linux.mdx @@ -1,3 +1,6 @@ +{/* DO NOT EDIT! */} +{/* Automatically generated from xbb-helper/templates/docusaurus/common. */} + import CodeBlock from '@theme/CodeBlock'; import customField from '@site/src/libs/customField'; diff --git a/website/docs/install/_common/_manual-install-macos.mdx b/website/docs/install/_common/_manual-install-macos.mdx index 1af8adc..14b6792 100644 --- a/website/docs/install/_common/_manual-install-macos.mdx +++ b/website/docs/install/_common/_manual-install-macos.mdx @@ -1,3 +1,6 @@ +{/* DO NOT EDIT! */} +{/* Automatically generated from xbb-helper/templates/docusaurus/common. */} + import CodeBlock from '@theme/CodeBlock'; import customField from '@site/src/libs/customField'; diff --git a/website/docs/install/_common/_manual-install-windows.mdx b/website/docs/install/_common/_manual-install-windows.mdx index 8b09fc7..3a05897 100644 --- a/website/docs/install/_common/_manual-install-windows.mdx +++ b/website/docs/install/_common/_manual-install-windows.mdx @@ -1,3 +1,6 @@ +{/* DO NOT EDIT! */} +{/* Automatically generated from xbb-helper/templates/docusaurus/common. */} + import CodeBlock from '@theme/CodeBlock'; import customField from '@site/src/libs/customField'; diff --git a/website/docs/install/_common/_manual-install.mdx b/website/docs/install/_common/_manual-install.mdx index 1766b12..b24aa3f 100644 --- a/website/docs/install/_common/_manual-install.mdx +++ b/website/docs/install/_common/_manual-install.mdx @@ -1,3 +1,6 @@ +{/* DO NOT EDIT! */} +{/* Automatically generated from xbb-helper/templates/docusaurus/common. */} + import customField from '@site/src/libs/customField'; {/* ------------------------------------------------------------------------ */} diff --git a/website/docs/install/_install-linux.mdx b/website/docs/install/_install-linux.mdx index 73ad0d9..f418c92 100644 --- a/website/docs/install/_install-linux.mdx +++ b/website/docs/install/_install-linux.mdx @@ -14,7 +14,7 @@ import ManualInstallLinux from './_common/_manual-install-linux.mdx'
-PATH +PATH setup In order to access the OpenOCD binaries installed in the central xPacks store, @@ -79,7 +79,7 @@ ${ customField('upstreamVersion') }`
-PATH +PATH setup With all binary tools installed in `xpacks/.bin`, the project build configurations need a single PATH adjustment: diff --git a/website/docs/install/_install-macos.mdx b/website/docs/install/_install-macos.mdx index 72c25e8..7f867d4 100644 --- a/website/docs/install/_install-macos.mdx +++ b/website/docs/install/_install-macos.mdx @@ -14,7 +14,7 @@ import ManualInstallInfo from './_common/_manual-info.mdx';
-PATH +PATH setup In order to access the OpenOCD binaries installed in the central xPacks store, diff --git a/website/docs/install/_install-windows.mdx b/website/docs/install/_install-windows.mdx index 9f69af7..afd7ba4 100644 --- a/website/docs/install/_install-windows.mdx +++ b/website/docs/install/_install-windows.mdx @@ -14,7 +14,7 @@ import ManualInstallInfo from './_common/_manual-info.mdx';
-PATH +PATH setup In order to access the OpenOCD binaries installed in the central xPacks store, diff --git a/website/docs/install/_testing.mdx b/website/docs/install/_testing.mdx new file mode 100644 index 0000000..5b1f02d --- /dev/null +++ b/website/docs/install/_testing.mdx @@ -0,0 +1,32 @@ + +import CodeBlock from '@theme/CodeBlock'; + +import customField from '@site/src/libs/customField'; + +{/* ------------------------------------------------------------------------ */} + +### 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/${ customField('upstreamVersion') }-${ customField('xpackSubversion') }.${ customField('npmSubversion') }/.content/bin/openocd -f board/stm32f4discovery.cfg +xPack OpenOCD x86_64 Open On-Chip Debugger ${ customField('upstreamVersion') }+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` +} + diff --git a/website/docs/install/index.mdx b/website/docs/install/index.mdx index 03a35c3..94e1636 100644 --- a/website/docs/install/index.mdx +++ b/website/docs/install/index.mdx @@ -1,4 +1,8 @@ --- + +# DO NOT EDIT! +# Automatically generated from xbb-helper/templates/docusaurus/common. + title: How to install the xPack OpenOCD binaries hide_table_of_contents: true @@ -7,38 +11,34 @@ date: 2020-09-27 11:09:00 +0300 --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; import customField from '@site/src/libs/customField'; -import Install from './_common/_install.mdx'; +import InstallWindows from './_install-windows.mdx'; +import InstallMacOS from './_install-macos.mdx'; +import InstallLinux from './_install-linux.mdx'; -{/* ------------------------------------------------------------------------ */} +import Testing from './_testing.mdx'; - - -### 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/${ customField('upstreamVersion') }-${ customField('xpackSubversion') }.${ customField('npmSubversion') }/.content/bin/openocd -f board/stm32f4discovery.cfg -xPack OpenOCD x86_64 Open On-Chip Debugger ${ customField('upstreamVersion') }+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` -} +{/* ------------------------------------------------------------------------ */} +The **xPack OpenOCD** can be installed automatically, using the `xpm` command +(the recommended method), or manually, by downloading and unpacking one of the +portable archives. + + + + + + + + + + + + + + diff --git a/website/docs/releases/index.md b/website/docs/releases/index.md index 5174afe..297e210 100644 --- a/website/docs/releases/index.md +++ b/website/docs/releases/index.md @@ -1,4 +1,8 @@ --- + +# DO NOT EDIT! +# Automatically generated from xbb-helper/templates/docusaurus/common. + title: The xPack OpenOCD releases hide_table_of_contents: true diff --git a/website/docs/support/_check-documentation.mdx b/website/docs/support/_check-documentation.mdx new file mode 100644 index 0000000..d20bf30 --- /dev/null +++ b/website/docs/support/_check-documentation.mdx @@ -0,0 +1,3 @@ +The original OpenOCD documentation is available from: + +- https://openocd.org/pages/documentation.html diff --git a/website/docs/support/_common/_part1.mdx b/website/docs/support/_common/_part1.mdx deleted file mode 100644 index 9ff81b5..0000000 --- a/website/docs/support/_common/_part1.mdx +++ /dev/null @@ -1,11 +0,0 @@ -## Quick links - -The quick answer is to use the -[GitHub Discussions](https://github.com/xpack-dev-tools/openocd-xpack/discussions/) pages. - -## Preliminary checks - -Before posting any questions, check if the subject was not -already addressed. - -- check the documentation. diff --git a/website/docs/support/_common/_part2.mdx b/website/docs/support/_common/_part2.mdx deleted file mode 100644 index f56bb5f..0000000 --- a/website/docs/support/_common/_part2.mdx +++ /dev/null @@ -1,48 +0,0 @@ -- check the [FAQ](/docs/faq/) -for similar problems -- check the [GitHub Discussions](https://github.com/xpack-dev-tools/openocd-xpack/discussions/) for -similar problems -- check the -[GitHub Issues](https://github.com/xpack-dev-tools/openocd-xpack/issues/) -tracker for similar problems. - -## Ask questions in GitHub Discussions - -If you still could not find a solution, if you have interesting use -cases, if you have custom configurations, and generally if you have -any experience that you want to share with others, use the -[GitHub Discussions](https://github.com/xpack-dev-tools/openocd-xpack/discussions/) pages, -and enter a **New discussion**; use the **Q&A** category for questions. - -## Register a new support ticket only if necessary - -If you are convinced that you identified a bug related to the binary -distribution, not OpenOCD itself (if you have doubts, use the GitHub Discussions), -or if you have a pertinent suggestion how to enhance the **xPack OpenOCD** -distribution, register a **New Issue** in the -[GitHub Issues](https://github.com/xpack-dev-tools/openocd-xpack/issues/) -tracker. - -:::tip - -**Do not** use the GitHub Issues tracker -for questions and support, **use the -[GitHub Discussions](https://github.com/xpack-dev-tools/openocd-xpack/discussions/)** pages. - -::: - -## Use of private e-mail - -:::caution Please, please, please! - -**Do not** use -private e-mail for support, **use the -[GitHub Discussions](https://github.com/xpack-dev-tools/openocd-xpack/discussions/)** pages. - -::: - -Sending private messages will be automatically replied with -a link to this page. -The reason for this rude behaviour is simply an attempt to use -the time more efficiently; since discussions are archived, other people -having similar problems might benefit from the answers. diff --git a/website/docs/support/index.mdx b/website/docs/support/index.mdx index d147aa3..5659db0 100644 --- a/website/docs/support/index.mdx +++ b/website/docs/support/index.mdx @@ -1,16 +1,81 @@ --- + +# DO NOT EDIT! +# Automatically generated from xbb-helper/templates/docusaurus/common. + title: How to get help for xPack OpenOCD date: 2020-09-28 17:54:00 +0300 --- -import Part1 from './_common/_part1.mdx'; -import Part2 from './_common/_part2.mdx' +import CheckDocumentation from './_check-documentation.mdx'; {/* ------------------------------------------------------------------------ */} - - The original documentation is available from: - - https://openocd.org/pages/documentation.html - +## Quick links + +The quick answer is to use the +[GitHub Discussions](https://github.com/xpack-dev-tools/openocd-xpack/discussions/) pages. + +## Check documentation + +As usual, before anything, it is a good idea to check the project +documentation. + + + +## Preliminary checks + +Before posting any questions, check if the subject was not +already addressed. + +- check the [FAQ](/docs/faq/) +for similar problems +- check the [GitHub Discussions](https://github.com/xpack-dev-tools/openocd-xpack/discussions/) for +similar problems +- check the +[GitHub Issues](https://github.com/xpack-dev-tools/openocd-xpack/issues/) +tracker for similar problems. + +## Ask questions in GitHub Discussions + +If you still could not find a solution, if you have interesting use +cases, if you have custom configurations, and generally if you have +any experience that you want to share with others, use the +[GitHub Discussions](https://github.com/xpack-dev-tools/openocd-xpack/discussions/) pages, +and enter a **New discussion**; use the **Q&A** category for questions. + +## Register a new support ticket only if necessary + +If you are convinced that you identified a bug related to the binary +distribution, not OpenOCD itself (if you have doubts, use the GitHub Discussions), +or if you have a pertinent suggestion how to enhance the **xPack OpenOCD** +distribution, register a **New Issue** in the +[GitHub Issues](https://github.com/xpack-dev-tools/openocd-xpack/issues/) +tracker. + +:::tip + +**Do not** use the GitHub Issues tracker +for questions and support, **use the +[GitHub Discussions](https://github.com/xpack-dev-tools/openocd-xpack/discussions/)** pages. + +::: + +## Use of private e-mail + +:::caution Please, please, please! + +**Do not** use +private e-mail for support, **use the +[GitHub Discussions](https://github.com/xpack-dev-tools/openocd-xpack/discussions/)** pages. + +::: + +Sending private messages will be automatically replied with +a link to this page. +The reason for this rude behaviour is simply an attempt to use +the time more efficiently; since discussions are archived, other people +having similar problems might benefit from the answers. + diff --git a/website/docs/test/index.mdx b/website/docs/test/index.mdx index 8b102b2..ad0b972 100644 --- a/website/docs/test/index.mdx +++ b/website/docs/test/index.mdx @@ -1,11 +1,17 @@ --- -title: A title + +# DO NOT EDIT! +# Automatically generated from xbb-helper/templates/docusaurus/common. + +title: A test page description: A short description something: "Some text" # https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#markdown-front-matter + --- + import CodeBlock from '@theme/CodeBlock'; export const world = 'World'