Skip to content

Commit 0ad7abf

Browse files
ilg-ulilg-ul
committed
website: rework getting-started
1 parent b2f6d00 commit 0ad7abf

File tree

12 files changed

+271
-192
lines changed

12 files changed

+271
-192
lines changed

‎website/docs/getting-started/_common/_benefits.mdx‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{/* DO NOT EDIT! */}
2+
{/* Automatically generated from docusaurus-template-liquid/templates/docusaurus. */}
3+
4+
{/* ------------------------------------------------------------------------ */}
5+
6+
## Benefits
7+
8+
The main advantages of using the **xPack MinGW-w64 GCC** are:
9+
10+
- A convenient, uniform and portable install/uninstall/upgrade
11+
procedure; the same procedure is used for all major
12+
platforms (**x64 Windows**, **x64 macOS**, **arm64 macOS**, **x64 GNU/Linux**, **arm64 GNU/Linux**, **arm GNU/Linux**).
13+
- Multiple versions of the same package can be installed at the same time on
14+
the same system.
15+
- No need to worry about dependent libraries, they are all included.
16+
- Not affected by system updates that
17+
might change the versions of the dependent libraries.
18+
- Significantly lighter and easier to use than Docker images that provide
19+
similar functionality and are GNU/Linux centric.
20+
- Projects can be tied to specific tools versions; this provides a good
21+
reproducibility, especially useful in **CI/CD** environments.

‎website/docs/getting-started/_common/_change-log.mdx‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{/* DO NOT EDIT! */}
2+
{/* Automatically generated from docusaurus-template-liquid/templates/docusaurus. */}
3+
4+
{/* ------------------------------------------------------------------------ */}
5+
6+
## Change log
7+
8+
The release and change log is available in the repository
9+
[`CHANGELOG.md`](https://github.com/xpack-dev-tools/mingw-w64-gcc-xpack/blob/xpack/CHANGELOG.md) file.

‎website/docs/getting-started/_common/_content.mdx‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
{/* DO NOT EDIT! */}
2+
{/* Automatically generated from docusaurus-template-liquid/templates/docusaurus. */}
3+
4+
import DetailsReproducibleBuilds from './_details-reproducible-builds.mdx';
5+
import WhatAreXpmPackages from './_what-are-xpm-packages.mdx';
6+
import Features from './_features.mdx';
7+
import Benefits from './_benefits.mdx';
8+
import InstallPreamble from './_install-preamble.mdx';
9+
10+
import Overview from '../_project/_overview.mdx';
11+
import OtherBenefits from '../_project/_other-benefits.mdx';
12+
import UpgradeNotice from '../_project/_upgrade-notice.mdx';
13+
import Compatibility from '../_project/_compatibility.mdx';
14+
15+
{/* ------------------------------------------------------------------------ */}
16+
17+
18+
## Overview
19+
20+
**xPack MinGW-w64 GCC** is a
21+
standalone, cross-platform (Windows, macOS, GNU/Linux) binary
22+
distribution of MinGW-w64 GCC,
23+
aimed at reproducible builds.
24+
25+
<DetailsReproducibleBuilds />
26+
27+
<Overview/>
28+
29+
The open source **xPack MinGW-w64 GCC** project is hosted on GitHub as
30+
[`xpack-dev-tools/mingw-w64-gcc-xpack`](https://github.com/xpack-dev-tools/mingw-w64-gcc-xpack/);
31+
it provides the platform specific binaries as
32+
[release assets](https://github.com/xpack-dev-tools/mingw-w64-gcc-xpack/releases).
33+
34+
In addition to the binary archives and the package metadata,
35+
this project also includes the
36+
[build scripts](https://github.com/xpack-dev-tools/mingw-w64-gcc-xpack/tree/xpack/build-assets/scripts).
37+
38+
<UpgradeNotice/>
39+
40+
<WhatAreXpmPackages />
41+
42+
<Features />
43+
44+
<Benefits />
45+
46+
<OtherBenefits/>
47+
48+
<Compatibility/>
49+
50+
## Install
51+
52+
<InstallPreamble />
53+
54+
The details for installing the **xPack MinGW-w64 GCC** on different platforms are
55+
provided in the
56+
[Install Guide](/docs/install/) on each project's website.

‎website/docs/getting-started/_common/_details-reproducible-builds.mdx‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{/* DO NOT EDIT! */}
2+
{/* Automatically generated from docusaurus-template-liquid/templates/docusaurus. */}
3+
4+
{/* ------------------------------------------------------------------------ */}
5+
6+
<details>
7+
<summary>What are reproducible builds?</summary>
8+
9+
To be **reproducible**, an operation must remain stable over time and
10+
across different environments. In other words, if builds are repeated
11+
after some time, possibly on a different machine or platform, the
12+
resulting behaviour must be functionally equivalent.
13+
14+
</details>

‎website/docs/getting-started/_common/_features.mdx‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
{/* DO NOT EDIT! */}
2+
{/* Automatically generated from docusaurus-template-liquid/templates/docusaurus. */}
3+
4+
{/* ------------------------------------------------------------------------ */}
5+
6+
## Features
7+
8+
All binaries are:
9+
10+
- **Self-contained** (include all required libraries).
11+
- **File-system relocatable** (can be installed in any location).
12+
- Built on slightly older systems (to ensure compatibility with both
13+
old and new systems).
14+
15+
<details>
16+
<summary>Compatibility with older systems</summary>
17+
18+
Given that most operating systems maintain significant compatibility
19+
with older versions, building an application on an older system ensures
20+
that the same binary can run on newer versions. Conversely, building an
21+
application on a newer system may utilize library features that are
22+
not available in older versions, making backward compatibility less
23+
feasible.
24+
25+
</details>
26+
27+
Similarly to [flatpacks](https://flatpak.org) or [snap](https://snapcraft.io),
28+
but significantly simpler, xpm packages include all dependent shared libraries
29+
within the distributed archives, making the binaries independent of
30+
any similar libraries installed on the system. This ensures they
31+
can run on any system without needing specific libraries to be
32+
installed.
33+
34+
Also the builds are configured so that the binaries do not depend on
35+
being installed in specific folders, and can be installed in any
36+
location, including in user folders.

‎website/docs/getting-started/_common/_install-preamble.mdx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{/* DO NOT EDIT! */}
2+
{/* Automatically generated from docusaurus-template-liquid/templates/docusaurus. */}
3+
4+
{/* ------------------------------------------------------------------------ */}
5+
6+
The executables and other related files can be installed automatically with
7+
**xpm** or manually by downloading the
8+
**platform specific archives**.

‎website/docs/getting-started/_common/_releases.mdx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{/* DO NOT EDIT! */}
2+
{/* Automatically generated from docusaurus-template-liquid/templates/docusaurus. */}
3+
4+
{/* ------------------------------------------------------------------------ */}
5+
6+
## Releases
7+
8+
The list of releases is available in the [Releases](/docs/releases/) pages.

‎website/docs/getting-started/_common/_support-and-feedback.mdx‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{/* DO NOT EDIT! */}
2+
{/* Automatically generated from docusaurus-template-liquid/templates/docusaurus. */}
3+
4+
{/* ------------------------------------------------------------------------ */}
5+
6+
## Support & feedback
7+
8+
The quick advice for getting support and providing feedback is to use the
9+
[GitHub Discussions](https://github.com/xpack-dev-tools/mingw-w64-gcc-xpack/discussions).
10+
11+
For additional information, please refer to the
12+
[Help Centre](/docs/support/) page.

‎website/docs/getting-started/_common/_user-developer-maintainer.mdx‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
{/* DO NOT EDIT! */}
2+
{/* Automatically generated from docusaurus-template-liquid/templates/docusaurus. */}
3+
4+
{/* ------------------------------------------------------------------------ */}
5+
6+
:::info Separate User/Contributor/Maintainer pages
7+
8+
To meet the specific needs of different
9+
audiences, this site features separate
10+
**[User's Guide](/docs/user/)**,
11+
**[Contributor's Guide](/docs/developer/)** and
12+
**[Maintainer's Guide](/docs/maintainer/)**
13+
pages. This way, each group can easily find the information and resources
14+
most relevant to them.
15+
16+
:::

‎website/docs/getting-started/_common/_what-are-xpm-packages.mdx‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
{/* DO NOT EDIT! */}
2+
{/* Automatically generated from docusaurus-template-liquid/templates/docusaurus. */}
3+
4+
{/* ------------------------------------------------------------------------ */}
5+
6+
## What are xpm packages? (xPacks) {#xpm-packages}
7+
8+
**xpm packages**, abbreviated as **xPacks**, are versatile,
9+
language-neutral software packages. They have been successfully
10+
utilised in C/C++ projects.
11+
12+
<details>
13+
<summary>What the heck are xpm packages (xPacks)? Please, do not introduce another package format!</summary>
14+
15+
Although the initial appearance may seem complex, utilising
16+
xpm packages is, in fact, straightforward.
17+
The design rationale is to automate frequent
18+
operations that occur during software development, such as the
19+
installation of
20+
dependencies, and to ensure reproducibility.
21+
22+
These packages are managed by **[xpm](https://xpack.github.io/xpm/)**
23+
(the xPack Project Manager),
24+
a programme that complements the **[npm](https://docs.npmjs.com/cli/)** CLI
25+
(the popular JavaScript package manager), with new language-neutral features.
26+
27+
The xPacks Framework **does NOT introduce a new package format**; instead,
28+
it uses **the same format as npm packages**, which is a collection of
29+
files/folders and a `package.json` file with the package metadata.
30+
31+
**xpm** can install packages from the
32+
same repositories as **npm**, whether public or private.
33+
34+
The packages (usually regular archives, but also git repositories),
35+
are extracted into separate folders within the project.
36+
37+
Based on the content, there are two types of xpm packages:
38+
39+
- packages with source libraries (**source** xpm packages)
40+
- packages with executables, usually platform-specific binary
41+
tools (**binary** xpm packages)
42+
43+
**Source xpm packages** are regular npm packages that include **library
44+
source files**, typically in **C/C++**, though there are no language
45+
restrictions.
46+
47+
**Binary xpm packages** are also regular npm packages, but with minimal
48+
content, typically just the `package.json` file. Since these packages
49+
provide executables for multiple platforms, some of which are quite
50+
large, it is not practical to include all binaries within the npm
51+
package itself. Instead, the `package.json` file contains references
52+
(URLs) to platform-specific binary archives (e.g., `.tar.gz` for Unix or
53+
`.zip` for Windows).
54+
55+
These archives are also expanded along with the package metadata.
56+
Links/forwarders to
57+
these executables are created in a `.bin` folder,
58+
eliminating the need to add multiple folders to the `PATH`.
59+
60+
In summary, xpm packages can enhance and automate the installation
61+
process for source libraries and tools.
62+
63+
In summary, xpm packages can streamline and automate the installation
64+
process for source libraries and tools. Further details are available on the
65+
[xpm Concepts](https://xpack.github.io/xpm/docs/guide/concepts/) page.
66+
67+
</details>

0 commit comments

Comments
 (0)