diff --git a/website/docs/getting-started/index.mdx b/website/docs/getting-started/index.mdx index 5823b7a..4c96c3e 100644 --- a/website/docs/getting-started/index.mdx +++ b/website/docs/getting-started/index.mdx @@ -37,8 +37,8 @@ import ReleaseSchedule from './_release-schedule.mdx' ## Overview -**xPack GNU Arm Embedded GCC** is a standalone -cross-platform (Windows, macOS, GNU/Linux) binary +**xPack GNU Arm Embedded GCC** is a +standalone, cross-platform (Windows, macOS, GNU/Linux) binary distribution of GNU Arm Embedded GCC, aimed at reproducible builds. @@ -48,7 +48,7 @@ aimed at reproducible builds. To be **reproducible**, an operation must remain stable over time and across different environments. In other words, if builds are repeated after some time, possibly on a different machine or platform, the -resulting behavior must be functionally equivalent. +resulting behaviour must be functionally equivalent. @@ -65,7 +65,7 @@ this project also includes the -## What are xpm packages? (xPacks) +## What are xpm packages? (xPacks) {#xpm-packages} **xpm packages**, abbreviated as **xPacks**, are versatile, language-neutral software packages. They have been successfully @@ -74,16 +74,16 @@ utilised in C/C++ projects.
What the heck are xpm packages / xPacks? Please, do not introduce another package format! -While the initial appearance may seem complex, utilizing +Although the initial appearance may seem complex, utilising xpm packages is, in fact, straightforward. The design rationale is to automate frequent -operations that occur during software development, in this case the +operations that occur during software development, such as the installation of dependencies, and to ensure reproducibility. These packages are managed by **[xpm](https://xpack.github.io/xpm/)** (the xPack Project Manager), -a program that complements the **[npm](https://docs.npmjs.com/cli/)** CLI +a programme that complements the **[npm](https://docs.npmjs.com/cli/)** CLI (the popular JavaScript package manager), with new language-neutral features. The xPacks Framework **does NOT introduce a new package format**; instead, @@ -98,24 +98,29 @@ are extracted into separate folders within the project. Based on the content, there are two types of xpm packages: -- **source packages** (that install source files, usually libraries) and -- **binary packages** (that install executables/binary files, usually tools). +- packages with source libraries (**source** xpm packages) +- packages with executables, usually platform-specific binary +tools (**binary** xpm packages) -Binary packages include references to archives with the platform specific -binaries (such as `.tar.gz` for Unix or `.zip` for Windows). +**Source xpm packages** are regular npm packages that include **library +source files**, typically in **C/C++**, though there are no language +restrictions. -These archives are also expanded along the package metadata. Since they -include executables, links/forwarders to +**Binary xpm packages** are also regular npm packages, but with minimal +content, typically just the `package.json` file. Since these packages +provide executables for multiple platforms, some of which are quite +large, it is not practical to include all binaries within the npm +package itself. Instead, the `package.json` file contains references +(URLs) to platform-specific binary archives (e.g., `.tar.gz` for Unix or +`.zip` for Windows). + +These archives are also expanded along with the package metadata. +Links/forwarders to these executables are created in a `.bin` folder, eliminating the need to add multiple folders to the `PATH`. -Given that some binary packages, such as toolchains, can have very large -archives, the packages are extracted only once into a user global location to -conserve space. In projects, instead of duplicating the content of these -archives, symbolic links are created. - -Simply put, xpm packages can be used to further automate the -installation of source libraries and tools. +In summary, xpm packages can enhance and automate the installation +process for source libraries and tools.
@@ -123,9 +128,10 @@ installation of source libraries and tools. All binaries are: -- **self-contained** (include all required libraries) -- **file-system relocatable** (can be installed in any location) -- built on slightly older systems (to make them run on both old and new systems) +- **Self-contained** (include all required libraries). +- **File-system relocatable** (can be installed in any location). +- Built on slightly older systems (to ensure compatibility with both +old and new systems).
Compatibility with older systems @@ -154,17 +160,17 @@ location, including in user folders. The main advantages of using the **xPack GNU Arm Embedded GCC** are: -- a convenient, uniform and portable install/uninstall/upgrade +- A convenient, uniform and portable install/uninstall/upgrade procedure; the same procedure is used for all major - platforms (**x64 Windows**, **x64 macOS**, **arm64 macOS**, **x64 GNU/Linux**, **arm64 GNU/Linux**, **arm GNU/Linux**) -- multiple versions of the same package can be installed at the same time on - the same system -- no need to worry about dependent libraries, they are all included -- not affected by system updates that - might change the versions of the dependent libraries -- significantly lighter and easier to use than Docker images that provide - similar functionality and are GNU/Linux centric -- projects can be tied to specific tools versions; this provides a good + platforms (**x64 Windows**, **x64 macOS**, **arm64 macOS**, **x64 GNU/Linux**, **arm64 GNU/Linux**, **arm GNU/Linux**). +- Multiple versions of the same package can be installed at the same time on + the same system. +- No need to worry about dependent libraries, they are all included. +- Not affected by system updates that + might change the versions of the dependent libraries. +- Significantly lighter and easier to use than Docker images that provide + similar functionality and are GNU/Linux centric. +- Projects can be tied to specific tools versions; this provides a good reproducibility, especially useful in **CI/CD** environments. diff --git a/website/docs/install/index.mdx b/website/docs/install/index.mdx index 325c6f4..4a43ec3 100644 --- a/website/docs/install/index.mdx +++ b/website/docs/install/index.mdx @@ -63,22 +63,22 @@ as the [`npmjs.com`](https://www.npmjs.com) registry.
-xPacks refresher +xpm packages (xPacks) refresher -xPacks (short for xpm packages) are general-purpose, +**xpm packages**, abbreviated as **xPacks**, are general-purpose, language-neutral software packages. They use **the same format as npm packages**, which is a collection of files/folders and a `package.json` file with the package metadata. **xpm** can install source and binary packages. -Binary xPacks include references to regular archives with the platform +Binary packages include references to regular archives with the platform specific binaries (such as `.tar.gz` for Unix or `.zip` for Windows). These archives are unpacked and links/forwarders to the executables are created in a `.bin` folder. For more details, please see the previous explanation in the -[Getting Started](/docs/getting-started/#xpacks) page. +[Getting Started](/docs/getting-started/#xpm-packages) page.
@@ -426,7 +426,7 @@ install the packages globally will fail with _already installed_.
PATH setup -In order to access the GNU RISC-V Embedded GCC binaries installed in +In order to access the GNU Arm Embedded GCC binaries installed in the user global xPacks store, the project build configurations need a PATH adjustment: diff --git a/website/docs/user/index.mdx b/website/docs/user/index.mdx index 9cc647c..a6153fa 100644 --- a/website/docs/user/index.mdx +++ b/website/docs/user/index.mdx @@ -3,7 +3,7 @@ # DO NOT EDIT! # Automatically generated from xbb-helper/templates/docusaurus/common. -title: User Information +title: User's Guide description: User information, including the versioning scheme, usage of shared libraries, and RPATH configuration on GNU/Linux. keywords: - xpack diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts index b49eb67..28624d0 100644 --- a/website/docusaurus.config.ts +++ b/website/docusaurus.config.ts @@ -102,9 +102,12 @@ const config: Config = { organizationName: 'xpack-dev-tools', // Usually your GitHub org/user name. projectName: 'arm-none-eabi-gcc-xpack', // Usually your repo name. + onBrokenAnchors: 'throw', onBrokenLinks: 'throw', onBrokenMarkdownLinks: 'throw', + onDuplicateRoutes: 'throw', + // Useful for the sitemap.xml, to avoid redirects, since // GitHub redirects all to trailing slash. trailingSlash: true,