diff --git a/website/blog/2023-08-24-riscv-none-elf-gcc-v13-2-0-1-released.mdx b/website/blog/2023-08-24-riscv-none-elf-gcc-v13-2-0-1-released.mdx index b53ecab..6319e1b 100644 --- a/website/blog/2023-08-24-riscv-none-elf-gcc-v13-2-0-1-released.mdx +++ b/website/blog/2023-08-24-riscv-none-elf-gcc-v13-2-0-1-released.mdx @@ -247,7 +247,7 @@ of build environments based on slightly older distributions, that should be compatible with most recent systems. For the prerequisites and more details on the build procedure, please see the -[Maintainer Info](/docs/maintainer-info/) page. +[Maintainer Info](/docs/maintainer/) page. ## CI tests diff --git a/website/blog/2023-08-25-riscv-none-elf-gcc-v12-3-0-1-released.mdx b/website/blog/2023-08-25-riscv-none-elf-gcc-v12-3-0-1-released.mdx index bad3aa9..a0f7bc8 100644 --- a/website/blog/2023-08-25-riscv-none-elf-gcc-v12-3-0-1-released.mdx +++ b/website/blog/2023-08-25-riscv-none-elf-gcc-v12-3-0-1-released.mdx @@ -247,7 +247,7 @@ of build environments based on slightly older distributions, that should be compatible with most recent systems. For the prerequisites and more details on the build procedure, please see the -[Maintainer Info](/docs/maintainer-info/) page. +[Maintainer Info](/docs/maintainer/) page. ## CI tests diff --git a/website/blog/2023-09-22-riscv-none-elf-gcc-v12-3-0-2-released.mdx b/website/blog/2023-09-22-riscv-none-elf-gcc-v12-3-0-2-released.mdx index 789fca0..07fe541 100644 --- a/website/blog/2023-09-22-riscv-none-elf-gcc-v12-3-0-2-released.mdx +++ b/website/blog/2023-09-22-riscv-none-elf-gcc-v12-3-0-2-released.mdx @@ -246,7 +246,7 @@ of build environments based on slightly older distributions, that should be compatible with most recent systems. For the prerequisites and more details on the build procedure, please see the -[Maintainer Info](/docs/maintainer-info/) page. +[Maintainer Info](/docs/maintainer/) page. ## CI tests diff --git a/website/blog/2023-09-25-riscv-none-elf-gcc-v13-2-0-2-released.mdx b/website/blog/2023-09-25-riscv-none-elf-gcc-v13-2-0-2-released.mdx index 5a5dde4..5a88e3a 100644 --- a/website/blog/2023-09-25-riscv-none-elf-gcc-v13-2-0-2-released.mdx +++ b/website/blog/2023-09-25-riscv-none-elf-gcc-v13-2-0-2-released.mdx @@ -246,7 +246,7 @@ of build environments based on slightly older distributions, that should be compatible with most recent systems. For the prerequisites and more details on the build procedure, please see the -[Maintainer Info](/docs/maintainer-info/) page. +[Maintainer Info](/docs/maintainer/) page. ## CI tests diff --git a/website/blog/2024-07-24-riscv-none-elf-gcc-v14-1-0-1-released.mdx b/website/blog/2024-07-24-riscv-none-elf-gcc-v14-1-0-1-released.mdx index b2b35d7..9de4b18 100644 --- a/website/blog/2024-07-24-riscv-none-elf-gcc-v14-1-0-1-released.mdx +++ b/website/blog/2024-07-24-riscv-none-elf-gcc-v14-1-0-1-released.mdx @@ -244,7 +244,7 @@ of build environments based on slightly older distributions, that should be compatible with most recent systems. For the prerequisites and more details on the build procedure, please see the -[Maintainer Info](/docs/maintainer-info/) page. +[Maintainer Info](/docs/maintainer/) page. ## CI tests diff --git a/website/blog/2024-07-25-riscv-none-elf-gcc-v13-3-0-1-released.mdx b/website/blog/2024-07-25-riscv-none-elf-gcc-v13-3-0-1-released.mdx index 2d48fff..4fe34d9 100644 --- a/website/blog/2024-07-25-riscv-none-elf-gcc-v13-3-0-1-released.mdx +++ b/website/blog/2024-07-25-riscv-none-elf-gcc-v13-3-0-1-released.mdx @@ -244,7 +244,7 @@ of build environments based on slightly older distributions, that should be compatible with most recent systems. For the prerequisites and more details on the build procedure, please see the -[Maintainer Info](/docs/maintainer-info/) page. +[Maintainer Info](/docs/maintainer/) page. ## CI tests diff --git a/website/blog/2024-07-26-riscv-none-elf-gcc-v12-4-0-1-released.mdx b/website/blog/2024-07-26-riscv-none-elf-gcc-v12-4-0-1-released.mdx index a0d4f96..466d409 100644 --- a/website/blog/2024-07-26-riscv-none-elf-gcc-v12-4-0-1-released.mdx +++ b/website/blog/2024-07-26-riscv-none-elf-gcc-v12-4-0-1-released.mdx @@ -244,7 +244,7 @@ of build environments based on slightly older distributions, that should be compatible with most recent systems. For the prerequisites and more details on the build procedure, please see the -[Maintainer Info](/docs/maintainer-info/) page. +[Maintainer Info](/docs/maintainer/) page. ## CI tests diff --git a/website/blog/2024-07-27-riscv-none-elf-gcc-v11-5-0-1-released.mdx b/website/blog/2024-07-27-riscv-none-elf-gcc-v11-5-0-1-released.mdx index acc6f81..6b7c664 100644 --- a/website/blog/2024-07-27-riscv-none-elf-gcc-v11-5-0-1-released.mdx +++ b/website/blog/2024-07-27-riscv-none-elf-gcc-v11-5-0-1-released.mdx @@ -244,7 +244,7 @@ of build environments based on slightly older distributions, that should be compatible with most recent systems. For the prerequisites and more details on the build procedure, please see the -[Maintainer Info](/docs/maintainer-info/) page. +[Maintainer Info](/docs/maintainer/) page. ## CI tests diff --git a/website/blog/2024-08-07-riscv-none-elf-gcc-v14-2-0-1-released.md b/website/blog/2024-08-07-riscv-none-elf-gcc-v14-2-0-1-released.md index 3578cc8..9c7346e 100644 --- a/website/blog/2024-08-07-riscv-none-elf-gcc-v14-2-0-1-released.md +++ b/website/blog/2024-08-07-riscv-none-elf-gcc-v14-2-0-1-released.md @@ -170,7 +170,7 @@ of build environments based on slightly older distributions, that should be compatible with most recent systems. For the prerequisites and more details on the build procedure, please see the -[Maintainer Info](/docs/maintainer-info/) page. +[Maintainer Info](/docs/maintainer/) page. ## CI tests diff --git a/website/docs/developer/_common/_platform-docker-section.mdx b/website/docs/developer/_common/_platform-docker-section.mdx new file mode 100644 index 0000000..f5d5787 --- /dev/null +++ b/website/docs/developer/_common/_platform-docker-section.mdx @@ -0,0 +1,57 @@ +{/* DO NOT EDIT! */} +{/* Automatically generated from xbb-helper/templates/docusaurus/common. */} + +import CodeBlock from '@theme/CodeBlock'; + +import customField from '@site/src/libs/customField'; +import { durations } from '../_durations.mdx' + +{/* ------------------------------------------------------------------------ */} + +{/* Arguments: props.platform */} + +{ props.platform == "win32-x64" ? (

The Windows builds run on GNU/Linux, using mingw-w64.

) : ''} + +To prepare the docker build: + + { +`xpm run install -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets && \\ +xpm run docker-prepare --config ${ props.platform } -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets` +} + +
+... or, with the writable helper ... + + { +`xpm run install -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets && \\ +xpm run link-deps -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets && \\ +xpm run docker-prepare --config ${ props.platform } -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets && \\ +xpm run docker-link-deps --config ${ props.platform } -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets` +} + +
+ +To run the docker build: + + { +`xpm run docker-build --config ${ props.platform } -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets` +} + +or, for more verbosity, run the similar development build: + + { +`xpm run docker-build-development --config ${ props.platform } -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets` +} + +{ durations[ props.platform ] }, the output of the build script is a compressed +archive and its SHA signature, created in +the buils-assets/build/{ props.platform }/deploy folder: + +* xpack-riscv-none-elf-gcc-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-{ props.platform }.tar.gz +* xpack-riscv-none-elf-gcc-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-{ props.platform }.tar.gz.sha + +To rerun the build, invoke the **deep-clean** action and repeat from install: + + { +`xpm run deep-clean --config ${ props.platform } -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets` +} diff --git a/website/docs/developer/_common/_platform-native-section.mdx b/website/docs/developer/_common/_platform-native-section.mdx new file mode 100644 index 0000000..d3174c2 --- /dev/null +++ b/website/docs/developer/_common/_platform-native-section.mdx @@ -0,0 +1,54 @@ +{/* DO NOT EDIT! */} +{/* Automatically generated from xbb-helper/templates/docusaurus/common. */} + +import CodeBlock from '@theme/CodeBlock'; + +import customField from '@site/src/libs/customField'; +import { durations } from '../_durations.mdx' + +{/* ------------------------------------------------------------------------ */} + +{/* Arguments: props.platform */} + +To prepare the native build: + + { +`xpm run install -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets && \\ +xpm install --config ${ props.platform } -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets` +} + +
+... or, with the writable helper ... + + { +`xpm run install -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets && \\ +xpm run link-deps -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets && \\ +xpm install --config ${ props.platform } -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets` +} + +
+ +To run the native build: + + { +`xpm run build --config ${ props.platform } -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets` +} + +or, for more verbosity, run the similar development build: + + { +`xpm run build-development --config ${ props.platform } -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets` +} + +{ durations[ props.platform ] }, the output of the build script is a compressed +archive and its SHA signature, created in +the buils-assets/build/{ props.platform }/deploy folder: + +* xpack-riscv-none-elf-gcc-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-{ props.platform }.tar.gz +* xpack-riscv-none-elf-gcc-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-{ props.platform }.tar.gz.sha + +To rerun the build, invoke the **deep-clean** action and repeat from install: + + { +`xpm run deep-clean --config ${ props.platform } -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets` +} diff --git a/website/docs/developer/_durations.mdx b/website/docs/developer/_durations.mdx new file mode 100644 index 0000000..3e8e125 --- /dev/null +++ b/website/docs/developer/_durations.mdx @@ -0,0 +1,11 @@ + +{/* ------------------------------------------------------------------------ */} + +export const durations = { + "darwin-x64": "About 6h38 later", + "darwin-arm64": "About 3h19 later", + "linux-x64": "About 4h17 later", + "win32-x64": "About 4h17 later", + "linux-arm64": "About 21h56 later", + "linux-arm": "About 20h32 later", +} diff --git a/website/docs/developer/_manual-tests.mdx b/website/docs/developer/_manual-tests.mdx new file mode 100644 index 0000000..728470e --- /dev/null +++ b/website/docs/developer/_manual-tests.mdx @@ -0,0 +1,3 @@ + +{/* ------------------------------------------------------------------------ */} + diff --git a/website/docs/developer/_other-repositories.mdx b/website/docs/developer/_other-repositories.mdx new file mode 100644 index 0000000..728470e --- /dev/null +++ b/website/docs/developer/_other-repositories.mdx @@ -0,0 +1,3 @@ + +{/* ------------------------------------------------------------------------ */} + diff --git a/website/docs/developer/index.mdx b/website/docs/developer/index.mdx new file mode 100644 index 0000000..c5367b9 --- /dev/null +++ b/website/docs/developer/index.mdx @@ -0,0 +1,325 @@ +--- + +# DO NOT EDIT! +# Automatically generated from xbb-helper/templates/docusaurus/common. + +title: How to build the xPack GNU RISC-V Embedded GCC + +date: 2024-11-12 20:33:00 +0300 + +--- + +import CodeBlock from '@theme/CodeBlock'; + +import customField from '@site/src/libs/customField'; + +import PlatformNativeSection from './_common/_platform-native-section.mdx' +import PlatformDockerSection from './_common/_platform-docker-section.mdx' +import OtherRepositories from './_other-repositories.mdx'; +import ManualTests from './_manual-tests.mdx' + +{/* ------------------------------------------------------------------------ */} + +[![license](https://img.shields.io/github/license/xpack-dev-tools/riscv-none-elf-gcc-xpack)](https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/blob/xpack/LICENSE) + +This page is intended for those who want to build the +**xPack GNU RISC-V Embedded GCC** +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 therefore are not recommended +for inexperienced users. + +::: + +
+ +
+xPack build configurations + +The xPack framework supports projects with **multiple build configurations**. + +Build configurations are sets of **properties**, **actions** and **dependencies** +that apply to a specific build. Build configurations can inherit from +other build configurations. + +For simple projects, the typical use case is with two configurations, +**Debug** and **Release**. + +For building the xPack binary tools, there is one configuration +for each platform: + +- `darwin-x64` +- `darwin-arm64` +- `linux-x64` +- `win32-x64` +- `linux-arm64` +- `linux-arm` + +:::note + +In case you wonder where these names come +from, they are exactly the Node.js `process.platform` and `process.arch` +for each platform. + +::: + +The build configurations are defined in the `package.json` file, in the +`xpack` section. + + +```json +{ + "...":"...", + "xpack": { + "buildConfigurations": { + "...": { + }, + "win32-x64": { + "inherit": [ + "common-dependencies", + "common-actions", + "common-docker" + ], + "devDependencies": { + "@xpack-dev-tools/gcc": "13.2.0-2.1", + "@xpack-dev-tools/mingw-w64-gcc": "13.2.0-1.1", + "@xpack-dev-tools/wine": "8.0.2-1.1" + }, + "properties": { + "dockerImage": "ilegeul/ubuntu:amd64-18.04-xbb-v5.2.2" + }, + "actions": { + "build": "{{ properties.commandBashBuild }} --windows", + "build-development": "{{ properties.commandBashBuild }} --windows --development", + "build-development-debug": "{{ properties.commandBashBuild }} --windows --development --debug", + "build-development-tests-only": "{{ properties.commandBashBuild }} --windows --development --tests-only" + } + } + } + } +} +``` + + +To ask **xpm** to perform a specific action on a given build configuration, +use the `--config ` option. + +For example: + +```sh +xpm install --config darwin-x64 +xpm run build --config darwin-x64 +``` + +
+ +
+xPack actions + +The xPack actions are extensions of npm scripts, i.e. named sequences +of commands that are invoked via `xpm run ` to perform specific +operations. +together in a sub-shell . + +The commands are invoked in a sub-shell with an adjusted PATH, +having the `xpacks/.bin` +folder prepended. This ensures the locally installed tools are +prefered to the system tools. + +Actions can be defined for the entire project or for a specific build +configuration. + +The actions are defined in the `package.json` file, in the +`xpack` section, at the top or inside build configurations. + +:::tip + +For those who, for various reasons, can not use **xpm**, it is +perfectly possible to manually adjust the PATH and to invoke the +sequence of commands in order, just that it is more tedious, +since multiple substitutions must be performed to compose the +commands. + +::: + +
+ +
+Visual Studio Code integration + +xPack actions and build configurations are supported in Visual Studio via the +[xPack C/C++ Managed Build Tools](https://marketplace.visualstudio.com/items?itemName=ilg-vscode.xpack) extension. + +With this extension installed, xPack actions can be very conveniently +invoked via a single mouse click, for example: + +![xPack actions](https://github.com/xpack/vscode-xpack-extension-ts/raw/master/assets/docs-images/xpack-actions.png) + +
+ +## Prerequisites + +The build scripts run on GNU/Linux and macOS. The Windows binaries are +compiled on x64 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/riscv-none-elf-gcc-xpack.git + +
+Branches + +Apart from the unused `master` branch, there are two active branches: + +- `xpack`, with the latest stable version (default) +- xpack-development, with the current development version + +All development is done in the xpack-development branch, and contributions via +Pull Requests should be directed to this branch. + +When new releases are published, the xpack-development branch is merged +into `xpack`. + +
+ +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/riscv-none-elf-gcc-xpack.git && \ +git clone https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack.git \ + ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git +``` + +
+For development purposes, clone the xpack-development branch. + +```sh +rm -rf ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git && \ +mkdir -p ~/Work/xpack-dev-tools && \ +git clone \ + --branch xpack-development \ + https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack.git \ + ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git +``` + +
+ +
+Get the writable 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 inside the helper, +clone the xpack-development branch and link it to +the user global xPacks store: + +```sh +rm -rf ~/Work/xpack-dev-tools/xbb-helper-xpack.git && \ +mkdir -p ~/Work/xpack-dev-tools && \ +git clone \ + --branch xpack-development \ + 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 writable 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 +(x64 GNU/Linux, armh64 GNU/Linux, arm GNU/Linux, +x64 macOS and arm64 macOS). + +### Update the repo + +```sh +git -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git pull +``` + +
+... and the helper (when using a writable helper) ... + +```sh +git -C ~/Work/xpack-dev-tools/xbb-helper-xpack.git pull +``` + +
+ +### Build the x64 macOS binaries + + + +### Build the arm64 macOS binaries + + + +### Build the x64 GNU/Linux binaries + + + +### Build the x64 Windows binaries + + + +### Build the arm64 GNU/Linux binaries + + + +### Build the arm GNU/Linux (32-bit) binaries + + + +### Compile with debug info + +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-development-debug` +and `docker-build-development-debug`). + +### Use a local 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/index.mdx b/website/docs/getting-started/index.mdx index 4def50d..842cd05 100644 --- a/website/docs/getting-started/index.mdx +++ b/website/docs/getting-started/index.mdx @@ -112,10 +112,10 @@ The release and change log is available in the repository ## Maintainer & Developer info For information on the workflow used to make releases, please see the -[Maintainer Info](/docs/maintainer-info/) page. +[Maintainer Info](/docs/maintainer/) page. For information on how to build the binaries, please see the -[Developer Info](/docs/developer-info/) page. +[Developer Info](/docs/developer/) page. However, the ultimate source for details are the build scripts themselves, all available from the diff --git a/website/docs/maintainer/_check-upstream-release.mdx b/website/docs/maintainer/_check-upstream-release.mdx new file mode 100644 index 0000000..8f86ee0 --- /dev/null +++ b/website/docs/maintainer/_check-upstream-release.mdx @@ -0,0 +1,11 @@ + +{/* ------------------------------------------------------------------------ */} + +### Check the latest upstream release + +The current release must be announced in the +[GCC Timeline](https://gcc.gnu.org/releases.html) page. +Compare the latest release with the current xPack +[release](https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases). +If necessary, update the triplet, otherwise increase the fourth number, +as below. diff --git a/website/docs/maintainer/_common/_platform-docker-build.mdx b/website/docs/maintainer/_common/_platform-docker-build.mdx new file mode 100644 index 0000000..2769a27 --- /dev/null +++ b/website/docs/maintainer/_common/_platform-docker-build.mdx @@ -0,0 +1,45 @@ +{/* DO NOT EDIT! */} +{/* Automatically generated from xbb-helper/templates/docusaurus/common. */} + +import CodeBlock from '@theme/CodeBlock'; + +import customField from '@site/src/libs/customField'; + +import { durations } from '../_durations.mdx' + +{/* ------------------------------------------------------------------------ */} + +To update the build scripts and build the development binaries: + + { +`rm -f ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/package-lock.json && \\ +git -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git pull && \\ +xpm run install -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets && \\ +git -C ~/Work/xpack-dev-tools/xbb-helper-xpack.git pull && \\ +xpm link -C ~/Work/xpack-dev-tools/xbb-helper-xpack.git && \\ +xpm run link-deps -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets && \\ +\\ +xpm run deep-clean --config ${ props.platform } -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets && \\ +xpm run docker-prepare --config ${ props.platform } -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets && \\ +xpm run docker-link-deps --config ${ props.platform } -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets && \\ +xpm run docker-build-development --config ${ props.platform } -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets` +} + +{ durations[ props.platform ] }, the output of the build script is a compressed +archive and its SHA signature, created in +the buils-assets/build/{ props.platform }/deploy folder: + +* xpack-riscv-none-elf-gcc-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-{ props.platform }.{ props.platform === 'win32-x64' ? 'zip' : 'tar.gz' } +* xpack-riscv-none-elf-gcc-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-{ props.platform }.{ props.platform === 'win32-x64' ? 'zip' : 'tar.gz' }.sha + +To update the build scripts and build the release binaries: + + { +`rm -f ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/package-lock.json && \\ +git -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git pull && \\ +xpm run install -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets && \\ +\\ +xpm run deep-clean --config ${ props.platform } -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets && \\ +xpm run docker-prepare --config ${ props.platform } -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets && \\ +xpm run docker-build-development --config ${ props.platform } -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets` +} diff --git a/website/docs/maintainer/_common/_platform-native-build.mdx b/website/docs/maintainer/_common/_platform-native-build.mdx new file mode 100644 index 0000000..d96090c --- /dev/null +++ b/website/docs/maintainer/_common/_platform-native-build.mdx @@ -0,0 +1,44 @@ +{/* DO NOT EDIT! */} +{/* Automatically generated from xbb-helper/templates/docusaurus/common. */} + +import CodeBlock from '@theme/CodeBlock'; + +import customField from '@site/src/libs/customField'; + +import { durations } from '../_durations.mdx' + +{/* ------------------------------------------------------------------------ */} + +To update the build scripts and build the development binaries: + + { +`rm -f ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/package-lock.json && \\ +git -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git pull && \\ +xpm run install -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets && \\ +git -C ~/Work/xpack-dev-tools/xbb-helper-xpack.git pull && \\ +xpm link -C ~/Work/xpack-dev-tools/xbb-helper-xpack.git && \\ +xpm run link-deps -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets && \\ +\\ +xpm run deep-clean --config ${ props.platform } -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets && \\ +xpm install --config ${ props.platform } -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets && \\ +xpm run build-development --config ${ props.platform } -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets` +} + +{ durations[ props.platform ] }, the output of the build script is a compressed +archive and its SHA signature, created in +the buils-assets/build/{ props.platform }/deploy folder: + +* xpack-riscv-none-elf-gcc-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-{ props.platform }.tar.gz +* xpack-riscv-none-elf-gcc-{ customField('upstreamVersion') }-{ customField('xpackSubversion') }-{ props.platform }.tar.gz.sha + +To update the build scripts and build the release binaries: + + { +`rm -f ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/package-lock.json && \\ +git -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git pull && \\ +xpm run install -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets && \\ +\\ +xpm run deep-clean --config ${ props.platform } -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets && \\ +xpm install --config ${ props.platform } -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets && \\ +xpm run build --config ${ props.platform } -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets` +} diff --git a/website/docs/maintainer/_durations.mdx b/website/docs/maintainer/_durations.mdx new file mode 100644 index 0000000..0bd542b --- /dev/null +++ b/website/docs/maintainer/_durations.mdx @@ -0,0 +1,14 @@ + +{/* ------------------------------------------------------------------------ */} + +{/* Values for 14.2.0. */} +{/* Below 5 minutes use "Several minutes later" */} +export const durations = { + "work": "about 128 minutes (2h08m) (with reduced multi-libs)", + "darwin-x64": "About 102 minutes (1h42m) later", + "darwin-arm64": "About 58 minutes later", + "linux-x64": "About 73 minutes later", + "win32-x64": "About 65 minutes later", + "linux-arm64": "About 459 minutes (7h39m) later, or 115 minutes (1h55m) on ampere", + "linux-arm": "About 433 minutes (7h13m) later", +} diff --git a/website/docs/maintainer/_functional-tests.mdx b/website/docs/maintainer/_functional-tests.mdx new file mode 100644 index 0000000..7ac8d13 --- /dev/null +++ b/website/docs/maintainer/_functional-tests.mdx @@ -0,0 +1,46 @@ + +{/* ------------------------------------------------------------------------ */} + + +- rename the version + folder, by replacing a dash with a space; this will test paths with spaces; + on Windows the current paths always use spaces, so renaming is not needed +- clone this repo locally; on Windows use the Git console + +```sh +rm -rf ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git && \ +mkdir -p ~/Work/xpack-dev-tools && \ +git clone \ + --branch xpack-develop \ + https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack.git \ + ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git +``` + +- check version: + +```sh +.../riscv-none-elf-gcc-14.1.0-1.1/bin/riscv-none-elf-gcc --version +riscv-none-elf-gcc (xPack GNU RISC-V Embedded GCC x86_64) 14.1.0 +``` + +- in a separate workspace, Import → General → Existing Projects into Workspace + the Eclipse projects available in the + `tests/eclipse` folder of the build repo; more details in the + [README.md](https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/blob/xpack/tests/eclipse/README.md) +- define the **Eclipse** → **Preferences...** → **MCU** → + **Workspace RISC-V Toolchain path** to use the `Downloads` + temporary location +- to test the compiler: for all projects + - remove all build folders, or **Clean all** + - build all configs, with the hammer, in `riscv-h1b-fs` + - build all configs, with the hammer, in `riscv-h1b-fs-lib`; this should + also run the builds in `riscv-static-lib` +- to test the debugger: for all OpenOCD debug configurations + - start the OpenOCD debug session, + - single step a few lines (Step Over) + - start continuous run (Resume) + - halt (Suspend) + - start (Resume) + - stop (Terminate) + - (don't miss the LTO cases, since in the past they had problems) +- to test the Python debugger, start it with `--version` diff --git a/website/docs/maintainer/_github-actions-durations.mdx b/website/docs/maintainer/_github-actions-durations.mdx new file mode 100644 index 0000000..c1d480a --- /dev/null +++ b/website/docs/maintainer/_github-actions-durations.mdx @@ -0,0 +1,11 @@ + +{/* ------------------------------------------------------------------------ */} + +The full builds take about 22 hours: + +- `darwin-x64`: 6h28m (nuc) +- `darwin-arm64`: 3h22m (m1) +- `linux-x64`: 3h40m (amd) +- `win32-x64`: 3h45m (amd) +- `linux-arm64`: 21h47m (rpi4) +- `linux-arm`: 20h38m (rpi4) diff --git a/website/docs/maintainer/_more-repos.mdx b/website/docs/maintainer/_more-repos.mdx new file mode 100644 index 0000000..2a39939 --- /dev/null +++ b/website/docs/maintainer/_more-repos.mdx @@ -0,0 +1,2 @@ + +{/* ------------------------------------------------------------------------ */} diff --git a/website/docs/maintainer/_patches.mdx b/website/docs/maintainer/_patches.mdx new file mode 100644 index 0000000..f472c66 --- /dev/null +++ b/website/docs/maintainer/_patches.mdx @@ -0,0 +1,6 @@ + +{/* ------------------------------------------------------------------------ */} + +### Patches + +For macOS builds, this project uses the same patches as `gcc-xpack`. diff --git a/website/docs/maintainer/_release-schedule.mdx b/website/docs/maintainer/_release-schedule.mdx new file mode 100644 index 0000000..6446836 --- /dev/null +++ b/website/docs/maintainer/_release-schedule.mdx @@ -0,0 +1,6 @@ + +{/* ------------------------------------------------------------------------ */} + +import GccReleaseSchedule from '../getting-started/_common/_gcc-release-schedule.mdx' + + diff --git a/website/docs/maintainer/_share-custom.mdx b/website/docs/maintainer/_share-custom.mdx new file mode 100644 index 0000000..8560fd5 --- /dev/null +++ b/website/docs/maintainer/_share-custom.mdx @@ -0,0 +1,25 @@ + +{/* ------------------------------------------------------------------------ */} + +import CodeBlock from '@theme/CodeBlock'; + +import customField from '@site/src/libs/customField'; + +## Announce to the RISC-V community + +Add a new topic in the **Announcements** category of the +[RISC-V forums](https://groups.google.com/a/groups.riscv.org/g/sw-dev). + +Copy/paste from [GitHub Releases](https://github.com/xpack-dev-tools/riscv-none-elf-gcc/). + + { +`Subject: xPack GNU RISC-V Embedded GCC v${ customField('upstreamVersion') }-${ customField('xpackSubversion') } released + +Version ${ customField('upstreamVersion') }-${ customField('xpackSubversion') } is a new release of the xPack GNU RISC-V Embedded GCC; it follows the GNU GCC release. + +- https://xpack-dev-tools.github.io/riscv-none-elf-gcc-xpack/blog/YYYY/MM/DD/riscv-none-elf-gcc-vNN-N-N-N-released/ + +Updates for the previous versions (13.3, 12.4 & 11.5) were also released.` +} + +Update the link to the actual blog post. diff --git a/website/docs/maintainer/_update-version-specific.mdx b/website/docs/maintainer/_update-version-specific.mdx new file mode 100644 index 0000000..d415871 --- /dev/null +++ b/website/docs/maintainer/_update-version-specific.mdx @@ -0,0 +1,8 @@ + +{/* ------------------------------------------------------------------------ */} + +### Update the version specific code + +- open the `build-assets/scripts/versioning.sh` file +- add a new `if` with the new version before the existing code +- update the versions, branch names and commit ids diff --git a/website/docs/maintainer/index.mdx b/website/docs/maintainer/index.mdx new file mode 100644 index 0000000..e50df1d --- /dev/null +++ b/website/docs/maintainer/index.mdx @@ -0,0 +1,797 @@ +--- + +# DO NOT EDIT! +# Automatically generated from xbb-helper/templates/docusaurus/common. + +title: How to make new xPack GNU RISC-V Embedded GCC releases + +date: 2024-07-12 20:11:00 +0300 + +--- + +import CodeBlock from '@theme/CodeBlock'; + +import customField from '@site/src/libs/customField'; + +import MoreRepos from './_more-repos.mdx'; +import ReleaseSchedule from './_release-schedule.mdx'; +import CheckUpstreamRelease from './_check-upstream-release.mdx' +import UpdateVersionSpecific from './_update-version-specific.mdx' +import GitHubActionsDurations from './_github-actions-durations.mdx' +import FunctionalTests from './_functional-tests.mdx' +import ShareCustom from './_share-custom.mdx' + +import { durations } from './_durations.mdx' +import Patches from './_patches.mdx' + +import PlatformNativeBuild from './_common/_platform-native-build.mdx' +import PlatformDockerBuild from './_common/_platform-docker-build.mdx' + +{/* ------------------------------------------------------------------------ */} + +[![license](https://img.shields.io/github/license/xpack-dev-tools/riscv-none-elf-gcc-xpack)](https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/blob/xpack/LICENSE) +[![GitHub issues](https://img.shields.io/github/issues/xpack-dev-tools/riscv-none-elf-gcc-xpack.svg)](https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/issues/) +[![GitHub pulls](https://img.shields.io/github/issues-pr/xpack-dev-tools/riscv-none-elf-gcc-xpack.svg)](https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/pulls) + +This page is intended for those who maintain +**xPack GNU RISC-V Embedded GCC** +and documents how to make new releases. + +## Prerequisites + +The build scripts run on GNU/Linux and macOS. The Windows binaries are +compiled on x64 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/riscv-none-elf-gcc-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/riscv-none-elf-gcc-xpack.git && \ +git clone https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack.git \ + ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git +``` + +For **development** purposes, clone the `xpack-development` branch: + +```sh +rm -rf ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git && \ +mkdir -p ~/Work/xpack-dev-tools && \ +git clone \ + --branch xpack-development \ + https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack.git \ + ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git +``` + +Or, if the repo was already cloned: + +```sh +git -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git pull +``` + +## Get the writable helper sources + +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 inside the helper, +clone the `xpack-development` branch and link it to +the user global xPacks store: + +```sh +rm -rf ~/Work/xpack-dev-tools/xbb-helper-xpack.git && \ +mkdir -p ~/Work/xpack-dev-tools && \ +git clone \ + --branch xpack-development \ + 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 +``` + +Or, if the repo was already cloned: + +```sh +git -C ~/Work/xpack-dev-tools/xbb-helper-xpack.git pull +xpm link -C ~/Work/xpack-dev-tools/xbb-helper-xpack.git +``` + + + + + +## Prepare the new releases + +Before starting the build, perform some checks and tweaks. + +### Download the build scripts + +The build scripts are available in the `build-assets/scripts` folder of the +[`xpack-dev-tools/riscv-none-elf-gcc-xpack`](https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack) +Git repo. + +To download them on a new machine, clone the `xpack-development` branch, +as seen above. + +### Check Git + +In the `xpack-dev-tools/riscv-none-elf-gcc-xpack` Git repo: + +- switch to the `xpack-development` branch +- pull new changes +- if needed, merge the `xpack` branch + +### Update helper & other dependencies + +Check the latest versions at https://github.com/xpack-dev-tools/ and +update the dependencies in `build-assets/package.json`. + + + +### Fix possible open issues + +Check GitHub issues and pull requests: + +- https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/issues/ + +and fix them; assign them to a milestone (like { customField('upstreamVersion') }-{ customField('xpackSubversion') }). + +### Increase the version and update VERSION + +Determine the version (like { customField('upstreamVersion') }) +and update the `build-assets/scripts/VERSION` file; the format +is { customField('upstreamVersion') }-{ customField('xpackSubversion') }. +The fourth number is the xPack release number +of this version. A fifth number will be added to the version in `package.json` +when the package is published to the `npm` server. + +### Update the version in top `package.json` to a pre-release + +Use the new version, suffixed by `.pre`, +like { customField('upstreamVersion') }-{ customField('xpackSubversion') }.{ customField('npmSubversion') }.pre. + +### Start the local web server + +Execute the npm script `clean` then `start` in the website sub-project, +or run the following in a terminal: + +```sh +(cd ~/Work/xpack-dev-tools/xbb-helper-xpack.git/website; npm run clean; npm run start) +``` + +Navigate to the **Maintainer Info** page, +the **Update the version specific code** section. + + + +### Update `CHANGELOG.md` + +- open the `CHANGELOG.md` file +- check if all previous fixed issues are in +- add a new entry like _**\* v{ customField('upstreamVersion') }-{ customField('xpackSubversion') } prepared**_ +- commit with a message like _**prepare v{ customField('upstreamVersion') }-{ customField('xpackSubversion') }**_ + +### Push the changes to Git + +Be sure that the latest commit that updates `VERSION` is pushed +to the `xpack-development` branch! + +:::caution + +This is really important, otherwise the next steps +will build again the previous release! + +::: + +## Run the development builds + +The builds currently run on 5 dedicated machines (x64 GNU/Linux, +arm64 GNU/Linux, arm GNU/Linux, x64 macOS and arm64 macOS). + +Before the real build, run test builds on all platforms. + +### Visual Studio Code + +All actions are defined as **xPack actions** and can be conveniently +triggered via the VS Code graphical interface, using the +[xPack extension](https://marketplace.visualstudio.com/items?itemName=ilg-vscode.xpack). + + + +### Restart the docker daemons + +If, for any reasons, the docker builds need to be canceled, it is very +likely that some processes will continue to run in the background. + +To completely terminate them, and ensure that docker runs +from a clean slate, restart the docker daemons on all GNU/Linux +machines: + +```sh +sudo systemctl restart docker +``` + +### Build the x64 macOS binaries + +For x64 macOS, first run the build on the development machine +(`wksi`, a recent macOS): + +```sh +export XBB_ENVIRONMENT_SKIP_CHECKS="y" +``` + +```sh +rm -f ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/package-lock.json +git -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git pull + +xpm run install -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets + +git -C ~/Work/xpack-dev-tools/xbb-helper-xpack.git pull +xpm link -C ~/Work/xpack-dev-tools/xbb-helper-xpack.git + +xpm run link-deps -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets + +xpm run deep-clean --config darwin-x64 -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets && \ +xpm install --config darwin-x64 -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets && \ +xpm run build-development --config darwin-x64 -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets +``` + +For a debug build: + +```sh +xpm run build-development-debug --config darwin-x64 -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets +``` + +The build takes { durations["work"] }. + +When functional, push the `xpack-development` branch to GitHub. + +Run the native build on the production machine +(`xbbmi`, an older macOS); +start a VS Code remote session, or connect with a terminal: + +```sh +caffeinate ssh xbbmi +``` + + + +### Build the arm64 macOS binaries + +Run the native build on the production machine +(`xbbma`, an older macOS); +start a VS Code remote session, or connect with a terminal: + +```sh +caffeinate ssh xbbma +``` + + + +### Build the x64 GNU/Linux binaries + +Run the docker build on the production machine (`xbbli`); +start a VS Code remote session, or connect with a terminal: + +```sh +caffeinate ssh xbbli +``` + + + +### Build the x64 Windows binaries + +Run the docker build on the production machine (`xbbli`); +start a VS Code remote session, or connect with a terminal: + +```sh +caffeinate ssh xbbli +``` + + + +### Build the arm64 GNU/Linux binaries + +Run the docker build on the production machine (`xbbla`); +start a VS Code remote session, or connect with a terminal: + +```sh +caffeinate ssh xbbla +``` + + + +### Build the arm GNU/Linux (32-bit) binaries + +Run the docker build on the production machine (`xbbla32`); +start a VS Code remote session, or connect with a terminal: + +```sh +caffeinate ssh xbbla32 +``` + + + +### Update the trees in the Install Guide page + +Copy the trees displayed at the end of the test builds and paste to +**Folder hierarchy** section in the web file: + +- `website/docs/install/_miscellaneous.mdx` + +Replace **{ customField('upstreamVersion') }** with +`${ customField('upstreamVersion') }` (there must be 6 occurences). + +:::tip + +macOS does not have a `tree` command; either compile it from +[sources](https://github.com/Old-Man-Programmer/tree), or install it +via HomeBrew, and make a link to `/usr/local/bin`. + +::: + +### Update the list of links in package.json + +Copy/paste the full list of links displayed at the end of the build, in +sequence, for each platform (GNU/Linux, macOS, Windows), and check the +differences compared to the repository. + +Commit if necessary. + +### 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-development-debug` +and `docker-build-development-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. + +## Run the production builds + +The automation is provided by GitHub Actions and three self-hosted runners. + + +### Start the self-hosted runners + +- on the development machine (`wksi`) open ssh sessions to the build +machines (`xbbmi`, `xbbma`, `xbbli`, `xbbla` and `xbbla32`): + +```sh +caffeinate ssh xbbmi +caffeinate ssh xbbma +caffeinate ssh xbbli +caffeinate ssh xbbla +caffeinate ssh xbbla32 +``` + +Create a `screen` session, to provide a persistent standard output for +the runners: + +```sh +screen -S ga +``` + +To quit it, use `# Ctrl-a Ctrl-d`. + +For `xbbli` & `xbbla`, which have more memory, start two runners: + +```sh +~/actions-runners/xpack-dev-tools/1/run.sh & +~/actions-runners/xpack-dev-tools/2/run.sh & +``` + +On all other machines start a single runner: + +```sh +~/actions-runners/xpack-dev-tools/run.sh & +``` + +To check the status of the runners locally: + +```sh +ps -a | grep 'Runner.Listener' +``` + +To kill them: + +```sh +killall Runner.Listener +``` + +### Check the status of the runners + +The status of all self-hosted runners is available at the [GitHub Runners](https://github.com/organizations/xpack-dev-tools/settings/actions/runners) page. + +### Publish the helper + +Publish a new release of the helper on **npmjs**. + +### Update the dependency to the new helper + +In `build-assets/package.json`, update the reference +to `"@xpack-dev-tools/xbb-helper":` +(possibly in all xPack projects). + +### Commit the changes to `build-assets/package.json` + +Use the message **build-assets/package.json: bump deps**. + +### Check for disk space + +Check if the build machines have enough free space and eventually +do some cleanups + +GNU/Linux: + +```sh +df -BG -H / +``` + +macOS: +``` +df -gH / +``` + +To free the space used by previous builds: + +```sh +rm -rf ~/Work/xpack-dev-tools/*/build-assets/build ~/Work/xpack-dev-tools/*/build +``` + +### Generate the GitHub workflows + +Run the **generate-workflows** xPack action to update the +GitHub workflow files. + +```sh +xpm run generate-workflows -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets +``` + +### Commit and push + +- commit with the message **Re-generate workflows** +- push the `xpack-dependency` branch to GitHub + +### Manually trigger the build GitHub Actions + +To trigger the GitHub Actions builds, use the xPack actions: + +- **trigger-workflow-build-darwin-x64** +- **trigger-workflow-build-darwin-arm64** +- **trigger-workflow-build-linux-x64** +- **trigger-workflow-build-win32-x64** +- **trigger-workflow-build-linux-arm64** +- **trigger-workflow-build-linux-arm** + +```sh +xpm run trigger-workflow-build-darwin-x64 -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets +xpm run trigger-workflow-build-darwin-arm64 -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets +xpm run trigger-workflow-build-linux-x64 -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets +xpm run trigger-workflow-build-win32-x64 -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets +xpm run trigger-workflow-build-darwin-x64 -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets +xpm run trigger-workflow-build-darwin-x64 -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets +``` + +The scripts behind these actions require the `GITHUB_API_DISPATCH_TOKEN` +variable to be present +in the environment, and the organization `PUBLISH_TOKEN` to be visible in the +Settings → Action → +[Secrets](https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/settings/secrets/actions) +page. + +These commands use the `xpack-development` branch of this repo. + +### Durations & resulting binaries + + + +The workflow result and logs are available from the +[GitHub Actions](https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/actions/) page. + +The resulting binaries are available for testing from +[pre-releases/test](https://github.com/xpack-dev-tools/pre-releases/releases/tag/test/). + +## Run the tests + +### Automated tests + +The automation is provided by GitHub Actions. + +To trigger the GitHub Actions tests, run the xPack actions: + +use the xPack actions: + +- **trigger-workflow-test-prime** +- **trigger-workflow-test-docker-linux-x64** +- **trigger-workflow-test-docker-linux-arm** + +```sh +xpm run trigger-workflow-test-prime -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets +xpm run trigger-workflow-test-docker-linux-x64 -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets +xpm run trigger-workflow-test-docker-linux-arm -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets +``` + +The scripts behind these accesible require the `GITHUB_API_DISPATCH_TOKEN` variable to be present +in the environment. + +These actions use the `xpack-development` branch of this repo and the +[pre-releases/test](https://github.com/xpack-dev-tools/pre-releases/releases/tag/test/) +binaries. + +The tests results are available from the +[GitHub Actions](https://github.com/xpack-dev-tools/openocd-xpack/actions/) page. + +Since GitHub Actions provides a limited range of versions for the macOS +runner, the multi-version macOS tests run on Travis. + +To trigger the Travis test, run the **trigger-travis-macos** xPack action: + +```sh +xpm run trigger-travis-macos -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets +``` + +This script requires the `TRAVIS_COM_TOKEN` variable to be present +in the environment. + +The test results are available from +[Travis CI](https://app.travis-ci.com/github/xpack-dev-tools/riscv-none-elf-gcc-xpack/builds/). + +### Manual tests + +To download the pre-released archive for the specific platform +and run the tests, use: + +```sh +git -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git pull +xpm run install -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets +xpm run test-pre-release -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets +``` + +For even more tests, on each platform (MacOS, GNU/Linux, Windows), +download the archive from +[pre-releases/test](https://github.com/xpack-dev-tools/pre-releases/releases/tag/test/) +and check the binaries. + +On macOS, remove the `com.apple.quarantine` flag: + +```sh +xattr -cr ${HOME}/Downloads/xpack-* +``` + + + +## Publish the release + +### Create a new GitHub pre-release draft + +- in `CHANGELOG.md`, add the release date and a message + like _**\* v{ customField('upstreamVersion') }-{ customField('xpackSubversion') } released**_ +- commit with _**CHANGELOG update**_ +- check and possibly update the `build-assets/templates/body-github-release-liquid.mdx` +- push the `xpack-development` branch to GitHub +- run the **trigger-workflow-publish-release** xPack action: + +```sh +xpm run trigger-workflow-publish-release -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets +``` + +The workflow result and logs are available from the +[GitHub Actions](https://github.com/xpack-dev-tools/openocd-xpack/actions/) page. + +The result is a +[draft pre-release](https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases/) +tagged like **v{ customField('upstreamVersion') }-{ customField('xpackSubversion') }** (mind the dash in the middle!) and +named like **xPack GNU RISC-V Embedded GCC v{ customField('upstreamVersion') }-{ customField('xpackSubversion') }** (mind the dash), +with all binaries attached. + +- edit the draft and attach it to the `xpack-development` branch (important!) +- save the draft (do **not** publish yet!) + +### Prepare a new blog post + +- check and possibly update the `build-assets/templates/body-blog-release-*-liquid.md` +- run the **generate-website-blog-post** xPack action; +this will add a file in the `website/blog` folder: + +```sh +xpm run generate-website-blog-post -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets +``` + +- edit the front matter properties +- select the correct summary +- commit with _**blog post release { customField('upstreamVersion') }-{ customField('xpackSubversion') } published**_ + +### Create the GitHub pre-release + +- go to the [GitHub Releases](https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases/) page +- perform the final edits and check if everything is fine +- **keep the pre-release button enabled** +- do not enable Discussions yet +- click the **Publish release** button + +Note: at this moment the system should send a notification to all clients +watching this project. + +### Update the web install page + +- check and possibly update the output of the `--version` runs in + - `website/docs/install/_automatic-install-quick-test.mdx` + - `website/docs/install/_manual-install-quick-test.mdx` +- commit changes + +### Check the list of links in package.json + +- open the `package.json` file +- check if the links in the `bin` property cover the actual binaries +- if necessary, also check on Windows + +### Update the package.json list of binaries + +- select the `xpack-development` branch +- run the **update-package-binaries** xPack action: + +```sh +xpm run update-package-binaries -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets +``` + +- open the top `package.json` file +- check the `baseUrl:` it should match the file URLs (including the tag/version); + no terminating `/` is required +- from the release, check the SHA & file names +- compare the SHA sums with those shown by `cat *.sha` +- check the executable names +- commit all changes, use a message like + _**package.json: update urls for { customField('upstreamVersion') }-{ customField('xpackSubversion') }.{ customField('npmSubversion') } release**_ + +### Publish on the npmjs.com server + +- select the `xpack-development` branch +- check the latest commits `npm run git-log` +- update `CHANGELOG.md`, add a line like _**\* v{ customField('upstreamVersion') }-{ customField('xpackSubversion') } published on npmjs.com**_ +- commit with a message like _**CHANGELOG: publish npm v{ customField('upstreamVersion') }-{ customField('xpackSubversion') }.{ customField('npmSubversion') }**_ +- `npm pack` and check the content of the archive, which should list + only the `package.json`, the `README.md`, `LICENSE` and `CHANGELOG.md`; + possibly adjust `.npmignore` +- configure the version; the first 4 numbers are the same as the + GitHub release; the fifth number is the npm specific version: + + { +`npm version ${ customField('upstreamVersion') }-${ customField('xpackSubversion') }.${ customField('npmSubversion') } +`} + +- the commits and the tag should have been pushed by the `postversion` script; + if not, push them with `git push origin --tags` to GitHub +- publish and add the `next` tag: + +```sh +npm publish --tag next +``` + +- when publishing for the first time, use: + +```sh +npm publish --access public +``` + +After a few moments the version will be visible at +npmjs.com. + +### Test if the binaries can be installed with xpm + +Run the **trigger-workflow-test-xpm** xPack action: + +```sh +xpm run trigger-workflow-test-xpm -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets +``` + +This will install the package via `xpm install` on all supported platforms. + +The tests results are available from the +[GitHub Actions](https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/actions/) page. + +### Tag the npm package as `latest` + +When the release is considered stable, promote it as `latest`: + + { +`npm dist-tag ls @xpack-dev-tools/riscv-none-elf-gcc +npm dist-tag add @xpack-dev-tools/riscv-none-elf-gcc@${ customField('upstreamVersion') }-${ customField('xpackSubversion') }.${ customField('npmSubversion') } latest +npm dist-tag ls @xpack-dev-tools/riscv-none-elf-gcc` +} + +In case the previous version is not functional and needs to be unpublished: + + { +`npm unpublish @xpack-dev-tools/riscv-none-elf-gcc@${ customField('upstreamVersion') }-${ customField('xpackSubversion') }.${ customField('npmSubversion') }` +} + +### Update the repo & publish the website + +- merge `xpack-development` into `xpack` +- push the `xpack` branch to GitHub + +At this moment the website is also generated. + +- the result is in https://xpack-dev-tools.github.io/riscv-none-elf-gcc-xpack/blog/ +- remember the post URL, since it must be updated in the release page + +### Create the final GitHub release + +- go to the [GitHub Releases](https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases/) page +- check the download counter, it should match the number of tests +- add a link to the Web blog `[Continue reading »]()`; use an same blog URL +- remove the _tests only_ notice +- **disable** the **pre-release** button +- click the **Update Release** button + +### Check SourceForge mirror + +- https://sourceforge.net/projects/riscv-none-elf-gcc-xpack/files/ + +## Cleanups + +### Remove the pre-release binaries + +- go to https://github.com/xpack-dev-tools/pre-releases/releases/tag/test/ +- remove the test binaries + +### Clean the work area + +Run the **trigger-workflow-deep-clean** xPack action + +```sh +xpm run trigger-workflow-deep-clean -C ~/Work/xpack-dev-tools/riscv-none-elf-gcc-xpack.git/build-assets +``` + +This will remove the build folders on all self-hosted runners. + +The results are available from the +[GitHub Actions](https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/actions/) page. + +## Share on Twitter + +- in a separate browser windows, open [X/Twitter](https://twitter.com) +- using the **`@xpack_project`** account +- paste the release name like _**xPack GNU RISC-V Embedded GCC v{ customField('upstreamVersion') }-{ customField('xpackSubversion') } released**_ +- paste the link to the blog post + [release](https://xpack.github.io/riscv-none-elf-gcc/releases/) +- click the **Tweet** button + + + +## Analytics + +- GitHub [`xpack-dev-tools/riscv-none-elf-gcc-xpack`](https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/) repo + - latest xPack release +[![Github All Releases](https://img.shields.io/github/downloads/xpack-dev-tools/riscv-none-elf-gcc-xpack/latest/total.svg)](https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases/) + - all xPack releases [![Github All Releases](https://img.shields.io/github/downloads/xpack-dev-tools/riscv-none-elf-gcc-xpack/total.svg)](https://github.com/xpack-dev-tools/riscv-none-elf-gcc-xpack/releases/) + - [individual file counters](https://somsubhra.github.io/github-release-stats/?username=xpack-dev-tools&repository=riscv-none-elf-gcc-xpack) (grouped per release) +- npmjs.com [`@xpack-dev-tools/riscv-none-elf-gcc`](https://www.npmjs.com/package/@xpack-dev-tools/riscv-none-elf-gcc/) xPack + - latest release, per month +[![npm (scoped)](https://img.shields.io/npm/v/@xpack-dev-tools/riscv-none-elf-gcc.svg)](https://www.npmjs.com/package/@xpack-dev-tools/riscv-none-elf-gcc/) +[![npm](https://img.shields.io/npm/dm/@xpack-dev-tools/riscv-none-elf-gcc.svg)](https://www.npmjs.com/package/@xpack-dev-tools/riscv-none-elf-gcc/) + - all releases [![npm](https://img.shields.io/npm/dt/@xpack-dev-tools/riscv-none-elf-gcc.svg)](https://www.npmjs.com/package/@xpack-dev-tools/riscv-none-elf-gcc/) + +Credit to [Shields IO](https://shields.io) for the badges and to +[Somsubhra/github-release-stats](https://github.com/Somsubhra/github-release-stats) +for the individual file counters. diff --git a/website/docs/user/_common/_libraries-and-rpath.mdx b/website/docs/user/_common/_libraries-and-rpath.mdx new file mode 100644 index 0000000..36f65f2 --- /dev/null +++ b/website/docs/user/_common/_libraries-and-rpath.mdx @@ -0,0 +1,35 @@ +{/* DO NOT EDIT! */} +{/* Automatically generated from xbb-helper/templates/docusaurus/common. */} + +{/* ------------------------------------------------------------------------ */} + +## Shared libraries + +On all platforms the binary xPack packages are **standalone**, +and expect only the standard runtime to be present on the host. + +All dependencies that are built as shared libraries are copied locally +in the `libexec` folder (or in the same folder as the executable for Windows). + +### `DT_RPATH` and `LD_LIBRARY_PATH` + +On GNU/Linux the binaries are adjusted to use a relative path: + +```console +$ readelf -d library.so | grep rpath + 0x000000000000001d (RPATH) Library rpath: [$ORIGIN] +``` + +In the GNU `ld.so` search strategy, the `DT_RPATH` has +the highest priority, higher than `LD_LIBRARY_PATH`, so if this latter one +is set in the environment, it should not interfere with the xPack binaries. + +Please note that previous versions, up to mid-2020, used `DT_RUNPATH`, which +has a priority lower than `LD_LIBRARY_PATH`; setting `LD_LIBRARY_PATH` +in the environment overrode `DT_RUNPATH`, resulting in failures to load +the libraries. + +### `@rpath` and `@loader_path` + +Similarly, on macOS, the binaries are adjusted with `install_name_tool` +(part of CLT) to use a relative path. diff --git a/website/docs/user/_common/_versioning.mdx b/website/docs/user/_common/_versioning.mdx new file mode 100644 index 0000000..d226153 --- /dev/null +++ b/website/docs/user/_common/_versioning.mdx @@ -0,0 +1,33 @@ +{/* DO NOT EDIT! */} +{/* Automatically generated from xbb-helper/templates/docusaurus/common. */} + +import CodeBlock from '@theme/CodeBlock'; +import Admonition from '@theme/Admonition'; + +import customField from '@site/src/libs/customField'; + +import LinksVsForwarders from '@site/src/components/LinksVsForwarders' + +{/* ------------------------------------------------------------------------ */} + +## Versioning + +The version string used by the +upstream { props.upstreamName ? props.upstreamName : 'GNU RISC-V Embedded GCC' } project +is a three number string +like { customField('upstreamVersion') }; +to this string the xPack distribution adds a fourth number, +but since [SemVer](https://semver.org) allows only three numbers, +all additional ones can +be added only as pre-release strings, separated by a dash, +like { customField('upstreamVersion') }-{ customField('xpackSubversion') }. When +published as a npm package, the version gets +a fifth number, +like { customField('upstreamVersion') }-{ customField('xpackSubversion') }.{ customField('npmSubversion') }. + +Since adherence of third party packages to SemVer is not guaranteed, +it is recommended to avoid referring to the xPack GNU RISC-V Embedded GCC dependency via +a SemVer expressions +like ^{ customField('upstreamVersion') } or ~{ customField('upstreamVersion') }, and +prefer exact matches, +like { customField('upstreamVersion') }-{ customField('xpackSubversion') }.{ customField('npmSubversion') }. diff --git a/website/docs/user/_more.mdx b/website/docs/user/_more.mdx new file mode 100644 index 0000000..ffc30be --- /dev/null +++ b/website/docs/user/_more.mdx @@ -0,0 +1,273 @@ + +{/* ------------------------------------------------------------------------ */} + +## riscv-none-elf-gcc + +After installing the toolchain, the result is a large set of programs +prefixed by `riscv-none-elf-`. For those used to other RISC-V +toolchains, there is no `riscv64-` or `riscv32-` prefix since +the word size is +actually not needed, the RISC-V toolchain produces both 32/64-bit binaries, +based on `-march` and `-mabi`. + +### `-march` and `-mabi` + +The RISC-V CPU is not defined as a single architecture, but as a family of +architectures, with optional extensions, identified by letters. + +RISC-V ISA strings begin with either RV32I, RV32E, RV64I, or RV128I, +the numerical value +indicating the register size in bits for the base integer ISA. + +- RV32I: A load-store ISA with 32 general-purpose integer registers of 32-bit +- RV32E: An embedded flavour of RV32I with only 16 integer registers of 32-bit +- RV64I: A 64-bit flavour of RV32I where the general-purpose integer registers + are 64-bit wide. + +In addition to these base ISAs, a large number of extensions have been +specified. The most used extensions that have both been specified +and are supported by the toolchain are: + +- M: Integer Multiplication and Division +- A: Atomics +- F: Single-Precision Floating-Point +- D: Double-Precision Floating-Point +- C: 16-bit Compressed Instructions +- Zicsr: Control and Status Register (CSR) +- Zifencei: Instruction-Fetch Fence +- G: General, a shortcut to IMAFD, Zicsr, Zifencei + +RISC-V ISA strings are defined by appending the supported extensions to the +base ISA in the order listed above. For example, the RISC-V ISA with +32-bit integer registers and the instructions to for multiplication would +be denoted as "RV32IM". Users can control the set of instructions that GCC +uses when generating assembly code by passing the lower-case ISA string to +the `-march` GCC option: for example `-march=rv32imac`. + +There are some other extensions. For more details, please see +[The RISC-V ISA Specification, Volume I: Unprivileged Spec](https://riscv.org/specifications/). + +In addition to controlling the instructions used by GCC during code +generation, users can select from various ABIs (which define +the calling convention and layout of objects in memory). +It is recommended for objects and +libraries to follow the same ABI, and not rely on the toolchain +logic for matching multilibs. + +RISC-V defines two integer ABIs and three floating-point ABIs, which +together are treated as a single ABI string. The integer ABIs follow the +standard ABI naming scheme: + +- `ilp32`: "int", "long", and pointers are all 32-bit long. "long long" is + a 64-bit type, "char" is 8-bit, and "short" is 16-bit. +- `lp64`: "long" and pointers are 64-bit long, while "int" is a 32-bit type. + The other types remain the same as ilp32. + +Compilers also implement a `ilp32e` ABI for small embedded devices, but its +standardisation status is not clear at this moment. + +while the floating-point ABIs are a RISC-V specific addition: + +- "" (the empty string): No floating-point arguments are passed in registers. +- `f`: 32-bit and smaller floating-point arguments are passed in registers. + This ABI requires the F extension, as without F there are no + floating-point registers. +- `d`: 64-bit and smaller floating-point arguments are passed in registers. + This ABI requires the D extension. + +ABI strings, possibly extended with `f` or `d`, are passed via +the `-mabi` argument to GCC. For example: + +- `-march=rv32imafdc -mabi=ilp32d`: Hardware floating-point instructions can + be generated and floating-point arguments are passed in registers. This + is like the `-mfloat-abi=hard` option to Arm's GCC. +- `-march=rv32imac -mabi=ilp32`: No floating-point instructions can be + generated and no floating-point arguments are passed in registers. This + is like the `-mfloat-abi=soft` argument to Arm's GCC. +- `-march=rv32imafdc -mabi=ilp32`: Hardware floating-point instructions can + be generated, but no floating-point arguments will be passed in + registers. This is like the `-mfloat-abi=softfp` argument to Arm's GCC, + and is usually used when interfacing with soft-float binaries on a + hard-float system. +- `-march=rv32imac -mabi=ilp32d`: Illegal, as the ABI requires floating-point + arguments are passed in registers but the ISA defines no floating-point + registers to pass them in. + +### `_zicsr` and `_zifencei` + +Starting with 12.x, the GCC compiler +implemented the new RISC-V ISA, which introduces an incompatibility with +early compilers, +therefore it is possible that builds will throw error messages +like _unrecognized opcode `csrr`_. + +The reason is that csr read/write (`csrr*`/`csrw*`) +instructions and `fence.i` instruction were separated from the `I` +extension, becoming two standalone extensions: `Zicsr` and `Zifencei`. + +The solution is to add `_zicsr` and/or `_zifencei` to the +`-march` option, e.g. `-march=rv32imac` becomes +`-march=rv32imac_zicsr_zifencei`. + +### newlib-nano + +Support for **newlib-nano** is available using the +`--specs=nano.specs` option. + +:::tip + +For better results, this option must be +added to both the compile and link steps. + +::: + +### nosys.specs + +If no syscalls are needed, `--specs=nosys.specs` can be used at link +time to provide empty implementations of the POSIX system calls. + +### `-mcmodel=medany` + +The libraries are compiled with `-O2 -mcmodel=medany`. The nano version is +compiled with `-Os -mcmodel=medany`. + +:::caution + +It is mandatory for the applications to +be compiled with +`-mcmodel=medany`, otherwise the link will fail. + +::: + +### Multiple libraries + +Due to the large number of architectures and ABIs defined for RISC-V, not all +possible combinations are actually available. + +Please check the release for the actual list. + +## Text User Interface (TUI) + +Support for TUI was added to GDB. The `ncurses` library was added to +the distribution. + +:::note + +TUI is not available on Windows + +::: + +## Python + +Support for Python scripting was added to GDB. This distribution provides +a separate binary, `riscv-none-elf-gdb-py3` with +support for **Python**. + +The Python 3 run-time is included, so GDB does not need any version of +Python to be installed, and is insensitive to the presence of other +versions. + +## Integration with Eclipse + +**The GNU RISC-V Embedded GCC** is fully integrated into +[Eclipse Embedded CDT](https://eclipse-embed-cdt.github.io). + +Eclipse provides full support for configure the RISC-V projects, +both in the build and the debug phase. + +## Automated testing + +In addition to integrating into regular development environments, +like Eclipse, GNU RISC-V Embedded GCC can be used for building +unit tests, in CI/CD environments. + +### CMake example + +The easiest way to build automated tests is with CMake in xPack applications. + +For CMake cross-build projects, it is necessary to pass a +`-D CMAKE_TOOLCHAIN_FILE` +with the path to the toolchain definition. + +A possible such file is +[riscv-none-elf-gcc.cmake](https://github.com/micro-os-plus/build-helper-xpack/blob/xpack/cmake/toolchains/riscv-none-elf-gcc.cmake), part of the +[µOS++](https://micro-os-plus.github.io) +build [helper](https://github.com/micro-os-plus/build-helper-xpack/). + +:::tip Windows + +Since on Windows the xPack OpenOCD uses `.cmd` forwarders, it is necessary +to explicitly define the extension, later used when invoking `openocd`: + +```cmake +if("${CMAKE_HOST_SYSTEM_NAME}" STREQUAL "Windows") + set(extension ".cmd") +endif() +``` + +::: + +To run the test, the semihosted application can be directly +executed by QEMU, which provides a good RISC-V emulation. + +An example of a unit test running on QEMU is: + +```cmake +if (ENABLE_UNIT_TEST) + + add_executable(unit-test) + set_target_properties(unit-test PROPERTIES OUTPUT_NAME "unit-test") + + // ... definitions to build the application with semihosting support ... + + add_test( + NAME "unit-test" + + COMMAND qemu-system-riscv32${extension} + --machine virt + --cpu rv32 + --kernel unit-test.elf + --nographic + -smp 1 + -bios none + -d unimp,guest_errors + --semihosting-config enable=on,target=native,arg=unit-test + ) + +endif () +``` + +In an xPack application, the tests can be invoked by running an xPack action, +like this: + +```sh +xpm run test +``` + +This asssumes that in `package.json` there is an action named `test` +and that all required tools were previously installed: + +```json +{ + "...": "...", + + "xpack": { + "actions": { + "...": "...", + "test": "ctest -V" + }, + "devDependencies": { + "@xpack-dev-tools/cmake": "3.26.5-1.1", + "@xpack-dev-tools/ninja-build": "1.11.1-3.1", + "@xpack-dev-tools/qemu-riscv": "8.2.2-1.1", + "@xpack-dev-tools/riscv-none-elf-gcc": "12.3.1-1.2.1" + } + } +} +``` + +The xPack action runs the defined command (`ctest -V` in this case) +in an environment where `xpacks/.bin` is prepended to the PATH, so +the tools installed locally by **xpm** are available and prefered to +possibly other similar tools installed in the system, thus +achieving a good reproducibility. diff --git a/website/docs/user/_versioning.mdx b/website/docs/user/_versioning.mdx new file mode 100644 index 0000000..d6c02f8 --- /dev/null +++ b/website/docs/user/_versioning.mdx @@ -0,0 +1,6 @@ + +import Versioning from './_common/_versioning.mdx'; + +{/* ------------------------------------------------------------------------ */} + + diff --git a/website/docs/user/index.mdx b/website/docs/user/index.mdx new file mode 100644 index 0000000..f94656a --- /dev/null +++ b/website/docs/user/index.mdx @@ -0,0 +1,27 @@ +--- + +# DO NOT EDIT! +# Automatically generated from xbb-helper/templates/docusaurus/common. + +title: How to use the xPack GNU RISC-V Embedded GCC + +date: 2024-07-11 18:56:00 +0300 + +--- + +import customField from '@site/src/libs/customField'; + +import Versioning from './_versioning.mdx'; +import LibrariesAndRpath from './_common/_libraries-and-rpath.mdx'; +import More from './_more.mdx'; + +{/* ------------------------------------------------------------------------ */} + +This page is intended for those who plan +to use the **xPack GNU RISC-V Embedded GCC** binaries in their workflows. + + + + + + diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts index e420e45..6f5a4fd 100644 --- a/website/docusaurus.config.ts +++ b/website/docusaurus.config.ts @@ -134,6 +134,57 @@ const config: Config = { disableInDev: false, }, ], + [ + // https://docusaurus.io/docs/next/api/plugins/@docusaurus/plugin-client-redirects#redirects + '@docusaurus/plugin-client-redirects', + { + // fromExtensions: ['html', 'htm'], // /myPage.html -> /myPage + // toExtensions: ['exe', 'zip'], // /myAsset -> /myAsset.zip (if latter exists) + redirects: [ + // // /docs/oldDoc -> /docs/newDoc + // { + // to: '/docs/newDoc', + // from: '/docs/oldDoc', + // }, + // // Redirect from multiple old paths to the new path + // { + // to: '/docs/newDoc2', + // from: ['/docs/oldDocFrom2019', '/docs/legacyDocFrom2016'], + // }, + ], + createRedirects(existingPath) { + // logger.info(existingPath); + // if (existingPath.includes('/evenimente')) { + // // logger.info(`to ${existingPath} from ${existingPath.replace('/evenimente', '/events')}`); + // // Redirect from /events/X to /evenimente/X + // return [ + // existingPath.replace('/evenimente', '/events') + // ]; + // } else if (existingPath.includes('/amintiri')) { + // // logger.info(`to ${existingPath} from ${existingPath.replace('/amintiri', '/blog')}`); + // // Redirect from /blog/Z to /amintiri/X + // return [ + // existingPath.replace('/amintiri', '/blog') + // ]; + // } + // return undefined; // Return a falsy value: no redirect created + // }, + if (existingPath.includes('/user-info')) { + return [ + existingPath.replace('/user-info', '/user') + ]; + } else if (existingPath.includes('/developer-info')) { + return [ + existingPath.replace('/developer-info', '/developer') + ]; + } else if (existingPath.includes('/maintainer-info')) { + return [ + existingPath.replace('/maintainer-info', '/maintainer') + ]; + } + } + } + ], './src/plugins/SelectReleasesPlugin', ], @@ -171,7 +222,7 @@ const config: Config = { }, { label: 'User Information', - to: '/docs/user-info' + to: '/docs/user' }, { label: 'Help Centre', diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current.json b/website/i18n/en/docusaurus-plugin-content-docs/current.json index fee70c2..0d6d103 100644 --- a/website/i18n/en/docusaurus-plugin-content-docs/current.json +++ b/website/i18n/en/docusaurus-plugin-content-docs/current.json @@ -13,7 +13,7 @@ }, "sidebar.docsSidebar.doc.User Info": { "message": "User Info", - "description": "The label for the doc item User Info in sidebar docsSidebar, linking to the doc user-info" + "description": "The label for the doc item User Info in sidebar docsSidebar, linking to the doc user" }, "sidebar.docsSidebar.doc.FAQ": { "message": "FAQ", diff --git a/website/package-lock.json b/website/package-lock.json index 4d266eb..9ef3890 100644 --- a/website/package-lock.json +++ b/website/package-lock.json @@ -9,6 +9,7 @@ "version": "0.0.0", "dependencies": { "@docusaurus/core": "3.4.0", + "@docusaurus/plugin-client-redirects": "3.4.0", "@docusaurus/plugin-ideal-image": "3.4.0", "@docusaurus/preset-classic": "3.4.0", "@mdx-js/react": "^3.0.0", @@ -2464,6 +2465,30 @@ "react-dom": "*" } }, + "node_modules/@docusaurus/plugin-client-redirects": { + "version": "3.4.0", + "resolved": "https://registry.npmjs.org/@docusaurus/plugin-client-redirects/-/plugin-client-redirects-3.4.0.tgz", + "integrity": "sha512-Pr8kyh/+OsmYCvdZhc60jy/FnrY6flD2TEAhl4rJxeVFxnvvRgEhoaIVX8q9MuJmaQoh6frPk94pjs7/6YgBDQ==", + "license": "MIT", + "dependencies": { + "@docusaurus/core": "3.4.0", + "@docusaurus/logger": "3.4.0", + "@docusaurus/utils": "3.4.0", + "@docusaurus/utils-common": "3.4.0", + "@docusaurus/utils-validation": "3.4.0", + "eta": "^2.2.0", + "fs-extra": "^11.1.1", + "lodash": "^4.17.21", + "tslib": "^2.6.0" + }, + "engines": { + "node": ">=18.0" + }, + "peerDependencies": { + "react": "^18.0.0", + "react-dom": "^18.0.0" + } + }, "node_modules/@docusaurus/plugin-content-blog": { "version": "3.4.0", "resolved": "https://registry.npmjs.org/@docusaurus/plugin-content-blog/-/plugin-content-blog-3.4.0.tgz", diff --git a/website/package.json b/website/package.json index 287b048..0c84d41 100644 --- a/website/package.json +++ b/website/package.json @@ -18,6 +18,7 @@ "dependencies": { "@docusaurus/core": "3.4.0", "@docusaurus/preset-classic": "3.4.0", + "@docusaurus/plugin-client-redirects": "3.4.0", "@docusaurus/plugin-ideal-image": "3.4.0", "@mdx-js/react": "^3.0.0", "clsx": "^2.0.0", diff --git a/website/sidebars.ts b/website/sidebars.ts index 31a245c..2db51f2 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -31,7 +31,7 @@ const sidebars: SidebarsConfig = { }, { type: 'doc', - id: 'user-info/index', + id: 'user/index', label: 'User Information' }, { @@ -46,12 +46,12 @@ const sidebars: SidebarsConfig = { }, { type: 'doc', - id: 'developer-info/index', + id: 'developer/index', label: 'Developer Information' }, { type: 'doc', - id: 'maintainer-info/index', + id: 'maintainer/index', label: 'Maintainer Information' }, {