Skip to content

Commit bd026f5

Browse files
ilg-ulilg-ul
committed
website: rework getting-started
1 parent 20e7e27 commit bd026f5

12 files changed

+230
-177
lines changed

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

+21
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 Binary Development Tools** 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/_details-reproducible-builds.mdx

+14
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

+36
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

+8
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/_user-developer-maintainer.mdx

+16
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

+67
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>

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

+56
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 '../_common/_details-reproducible-builds.mdx';
5+
import WhatAreXpmPackages from '../_common/_what-are-xpm-packages.mdx';
6+
import Features from '../_common/_features.mdx';
7+
import Benefits from '../_common/_benefits.mdx';
8+
import InstallPreamble from '../_common/_install-preamble.mdx';
9+
10+
import License from '../_common/_license.mdx';
11+
import Credits from '../_common/_credits.mdx';
12+
import EnjoyedUsing from '../_common/_enjoyed-using.mdx';
13+
14+
import Overview from './_overview.mdx';
15+
import OtherBenefits from './_other-benefits.mdx';
16+
import UpgradeNotice from './_upgrade-notice.mdx';
17+
import Compatibility from './_compatibility.mdx';
18+
19+
{/* ------------------------------------------------------------------------ */}
20+
21+
22+
## Overview
23+
24+
**xPack Binary Development Tools** is a collection of standalone cross-platform binary tools, aimed at reproducible builds.
25+
26+
<DetailsReproducibleBuilds />
27+
28+
<Overview/>
29+
30+
<WhatAreXpmPackages />
31+
32+
<Features />
33+
34+
<Benefits />
35+
36+
<OtherBenefits/>
37+
38+
<Compatibility/>
39+
40+
## Install
41+
42+
<InstallPreamble />
43+
44+
The details for installing the various **xPack Binary Development Tools**
45+
on different platforms are provided in the
46+
**Install Guide** on each project's website.
47+
48+
<License />
49+
50+
The binary distributions include several open-source components;
51+
the corresponding licenses are available in each archive in the
52+
`distro-info/licenses` folder.
53+
54+
<Credits />
55+
56+
<EnjoyedUsing />

‎website/docs/getting-started/_project/_documentation.mdx

-9
This file was deleted.

‎website/docs/getting-started/_project/_more-credits.mdx

-2
This file was deleted.

‎website/docs/getting-started/_project/_status.mdx

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
2+
{/* ------------------------------------------------------------------------ */}
3+
4+
## Status
5+
6+
The **xPack Binary Development Tools** project is fully functional,
7+
stable, and suitable for use in production environments.

0 commit comments

Comments
 (0)