How to make new xPack GNU Arm Embedded GCC releases
This page is designed for maintainers of the xPack GNU Arm Embedded GCC project and provides documentation on how to create new releases.
Prerequisites
The build scripts run on GNU/Linux and macOS. The Windows binaries are compiled on x64 GNU/Linux, using mingw-w64.
For details on installing the prerequisites, please read the Build Prerequisites page.
Get project sources
The project is hosted on GitHub:
To clone the stable branch (xpack
), run the following commands in a
terminal (on Windows use the Git Bash console):
rm -rf ~/Work/xpack-dev-tools/arm-none-eabi-gcc-xpack.git && \
git clone https://github.com/xpack-dev-tools/arm-none-eabi-gcc-xpack.git \
~/Work/xpack-dev-tools/arm-none-eabi-gcc-xpack.git
For development purposes, clone the xpack-development
branch:
rm -rf ~/Work/xpack-dev-tools/arm-none-eabi-gcc-xpack.git && \
mkdir -p ~/Work/xpack-dev-tools && \
git clone \
--branch xpack-development \
https://github.com/xpack-dev-tools/arm-none-eabi-gcc-xpack.git \
~/Work/xpack-dev-tools/arm-none-eabi-gcc-xpack.git
Or, if the repo was already cloned:
git -C ~/Work/xpack-dev-tools/arm-none-eabi-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:
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:
git -C ~/Work/xpack-dev-tools/xbb-helper-xpack.git pull
xpm link -C ~/Work/xpack-dev-tools/xbb-helper-xpack.git
Other repositories in use are:
- https://github.com/xpack-dev-tools/binutils-gdb - for the binutils & gdb sources
- git://sourceware.org/git/binutils-gdb.git - a fork of the upstream, with tags added to the commits used by the Arm Toolchain distribution; this allows direct archive downloads instead of git clone.
Release schedule
This distribution generally follows the official Arm GNU Toolchain release schedule (about 2 times per year).
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/arm-none-eabi-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/arm-none-eabi-gcc-xpack
Git repo:
- switch to the
xpack-development
branch - pull new changes
- if necessary, merge the
xpack
branch - if necessary, merge the
website
branch
This is really important, otherwise the next steps will build again the previous release!
The xpack
branch should be unchanged since the previous release
and will be updated when the new release is out.
Update helper & other dependencies
Check the latest versions at https://github.com/xpack-dev-tools/ and
update the dependencies in build-assets/package.json
.
Check the latest upstream release
The latest releases must have been announced in Arm GNU Toolchain Downloads. Compare the latest Arm release with the latest xPack release. If necessary, update the triplet, otherwise increase the fourth & fifth numbers, as below.
Update to the latest Arm release
- download the new Source code archive (like
arm-gnu-toolchain-src-snapshot-14.2.rel1.tar.xz
) from Arm GNU Toolchain Downloads - unpack the archive
- the GCC version is in
gcc/gcc/BASE-VER
- the binutils version is in
binutils-gdb/bfd/version.m4
- the GDB version is in
binutils-gdb--gdb/gdb/version.in
- the newlib version is in
newlib-cygwin/newlib/configure
, search forVERSION=
- download the latest macOS (x86_64) hosted cross toolchains archive (like
arm-gnu-toolchain-14.2.rel1-darwin-x86_64-arm-none-eabi.tar.xz
) - unpack the archive
- create a folder
build-assets/extras/14.2.rel1
- copy the file with the configurations
(
14.2.rel1-darwin-x86_64-arm-none-eabi-manifest.txt
) to the new folder in extras - download the manifest.txt with the individual source URLs
(
arm-gnu-toolchain-src-snapshot-14.2.rel1-manifest.txt
) - copy to the new folder in extras
Starting with 14.2.Rel1 there is a link to a README explaining the new build scripts.
Increase the version and update it in the top package.json
- determine the version (like
14.2.1-1.1.1
) - update the version in top
package.json
- use the new version, suffixed by
.pre
, like14.2.1-1.1.1.pre
.
Increase the version and update VERSION
Determine the version (like 14.2.1-1.1
)
and update the build-assets/scripts/VERSION
file; the format
is 14.2.1-1.1
.
The fourth & fifth numbers are the xPack release number of this version. A sixth number will be added to the version in package.json
when the package is published to the npm
server.
Update the websiteConfig
in website/package.json
(if necessary)
- update the release specific properties (if any)
Generate the top commons
Run the top generate-top-commons npm script to update the
build-assets/package.json
and the GitHub workflow files.
(cd ~/Work/xpack-dev-tools/arm-none-eabi-gcc-xpack.git; npm run generate-top-commons)
Commit the top changes
- stage GitHub workflows and
package.json
files (top and frombuild-assets
) - commit with the message re-generate top commons to bump deps
Update the website commons
Run the generate-website-commons npm script from website/package.json
.
Commit the website changes
- stage
website
and topREADME.md
- commit with the message website: re-generate commons
Start the local web server
Execute the npm script clean then start in the website sub-project, or run the following in a terminal:
(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 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 local binutils-gdb fork
With a Git client:
- checkout the branch mentioned in the release notes
(like
users/ARM/binutils-2_43-branch
) - push it to origin with the same name
- enable a filter on the current branch
- identify the commit ID from release notes or manifest.txt (search back in time)
- add a tag like
binutils-2.43-arm-none-eabi-14.2.rel1
- push the tag to origin
- check the tag at https://github.com/xpack-dev-tools/binutils-gdb/tags/
Similarly for GDB:
- checkout the branch mentioned in the release notes
(like
gdb-15-branch
) - push it to origin with the same name
- enable a filter on the current branch
- identify the commit ID from release notes or manifest.txt (search back in time)
- add a tag like
gdb-15-arm-none-eabi-14.2.rel1
- push the tag to origin
- check the tag at https://github.com/xpack-dev-tools/binutils-gdb/tags/
Update the local gcc fork (optional, normally the archive is used)
With a Git client:
- checkout the branch mentioned in the release notes
(like
ARM/arm-14
) - push it to origin with the same name
- enable a filter on the current branch
- identify the commit ID from release notes or manifest.txt (search back in time)
- create a branch like
arm-14-arm-none-eabi-14.2.rel1-xpack
- create a tag like
arm-14-arm-none-eabi-14.2.rel1
- push the tag to origin
- check the tag at https://github.com/xpack-dev-tools/gcc/tags/
- cherry pick the
system.h: do not define abort() on mingw
commit - push the *-xpack branch to origin
- save as Patches into the helper
patches
folder - rename as
gcc-14.2.1-cross.git.patch
Update the local newlib-cygwin fork (optional, normally the archive is used)
With a Git client:
- pull from the
master
branch (none mentioned in the release notes) - push it to origin with the same name
- enable a filter on the current branch
- identify the commit ID from release notes or manifest.txt (search back in time)
- create a tag like
newlib-4.4.0-arm-none-eabi-14.2.rel1
- push the tag to origin
- check the tag at https://github.com/xpack-dev-tools/newlib-cygwin/tags/
Update the gdb-*-cross.git.patch in helper
Copy/paste a previous one; adjust if necessary.
Update other dependencies versions
Check the release notes and updates the libgmp
, libisl
, libmpfr
, libmpc
, libiconv
versions.
Check configure options
Verify if the configure options used in
the 14.2.rel1-darwin-x86_64-arm-none-eabi-manifest.txt
file
are used in the build scripts.
Fix possible open issues
Check GitHub issues and pull requests:
- https://github.com/xpack-dev-tools/arm-none-eabi-gcc-xpack/issues
- https://github.com/xpack-dev-tools/arm-none-eabi-gcc-xpack/pulls
and fix them; assign them to a milestone (like 14.2.1-1.1
).
Update CHANGELOG.md
- open the
CHANGELOG.md
file - check if all previous fixed issues are in
- check the latest commits
xpm run git-log
; if necessary, copy/paste lines, group by dates and edit them using the below regular expressions - to turn the dates into headings, change from:
to:
([0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]) [*]
## $1
* - to remove the rest of the dates, change from:
to:
^[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9] [*]
*
- add a new entry like * v14.2.1-1.1 prepared
- commit with the message prepare v14.2.1-1.1
Push the changes to the xpack-development
branch
Be sure that the latest commit that updates VERSION
is pushed
to the xpack-development
branch!
This is really important, otherwise the next steps will build again the previous release!