From 1893b70a55ae264259e162089b89531d04110776 Mon Sep 17 00:00:00 2001 From: Liviu Ionescu Date: Wed, 9 Oct 2024 00:22:02 +0300 Subject: [PATCH] website: updates --- website/docs/faq/_common/_flatpack-snap.mdx | 18 +++++++ website/docs/faq/_common/_nixos.mdx | 21 ++++++++ website/docs/getting-started/index.mdx | 50 +++++++++++++++++-- website/docs/install/index.mdx | 2 +- .../src/components/HomepageFeatures/index.tsx | 11 ++-- 5 files changed, 92 insertions(+), 10 deletions(-) create mode 100644 website/docs/faq/_common/_flatpack-snap.mdx create mode 100644 website/docs/faq/_common/_nixos.mdx diff --git a/website/docs/faq/_common/_flatpack-snap.mdx b/website/docs/faq/_common/_flatpack-snap.mdx new file mode 100644 index 0000000..705ede4 --- /dev/null +++ b/website/docs/faq/_common/_flatpack-snap.mdx @@ -0,0 +1,18 @@ +{/* DO NOT EDIT! */} +{/* Automatically generated from xbb-helper/templates/docusaurus/common. */} + +import Link from '@docusaurus/Link'; + +{/* ------------------------------------------------------------------------ */} + +
+Flatpack & Snap also promise universal packages, why not use them? + +The short answer is… _“because they run only on GNU/Linux”_. + +Both [Flatpack](https://flatpak.org) and [Snap](https://snapcraft.io) +hold promise as the future of application distribution. While they may +eventually achieve this, they are currently specific to GNU/Linux, with +very little chance of expanding to other platforms. + +
diff --git a/website/docs/faq/_common/_nixos.mdx b/website/docs/faq/_common/_nixos.mdx new file mode 100644 index 0000000..f35f026 --- /dev/null +++ b/website/docs/faq/_common/_nixos.mdx @@ -0,0 +1,21 @@ +{/* DO NOT EDIT! */} +{/* Automatically generated from xbb-helper/templates/docusaurus/common. */} + +import Link from '@docusaurus/Link'; + +{/* ------------------------------------------------------------------------ */} + +
+Nix also provides reproducible builds, why not use it? + +The short answer is… _“because of Windows”_. + +[Nix](https://nixos.org/) is a remarkable project that carefully +controls versions down to individual libraries. However, it relies +on file links, which are either unavailable or unreliable on Windows. + +As a result, Nix is currently only available on GNU/Linux and, with +some limitations, on macOS. Additionally, mastering the Nix language +requires significant effort. + +
diff --git a/website/docs/getting-started/index.mdx b/website/docs/getting-started/index.mdx index d6fd249..ddf87f4 100644 --- a/website/docs/getting-started/index.mdx +++ b/website/docs/getting-started/index.mdx @@ -28,6 +28,16 @@ cross-platform (GNU/Linux, macOS) binary distribution of GNU sed, aimed at reproducible builds. +
+What are 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. + +
+ The open source **xPack GNU sed** project is hosted on GitHub as @@ -41,6 +51,39 @@ this project also includes the +## xPacks + +
+What the heck are xPacks? Please, not yet another package format! + +**xPacks** are general purpose multi-version software packages. + +There are two types of xPacks: + +- **source xPacks** (that install source files, usually libraries) and +- **binary xPacks** (that install executables/binary files, usually tools). + +The xPacks project **does NOT introduce a new package format**; instead, +it uses **the same format as npm**, which is a collection of files/folders +and a `package.json` file with the package metadata. Additionally, +installing binary xPacks also installs the archives with the platform specific +binaries (such as `.tar.gz` for Unix or `.zip` for Windows). + +Also, xPacks can be installed from the +same repositories as **npm** packages, whether public or private. + +xPacks 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 (the +popular JavaScript package manager), +with new language-neutral features. + +In short, xPacks are just a way to automate installing source libraries and +tools. + +
+ + ## Features All binaries are: @@ -70,7 +113,7 @@ procedure; the same procedure is used for all major platforms (**x64 GNU/Linux**, **arm64 GNU/Linux**, **arm GNU/Linux**, **x64 macOS**, **arm64 macOS**) - multiple versions of the same package can be installed at the same time on the same system -- no need to worry about dependent libraries, all are included +- no need to worry about dependent libraries, they are all included - 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 @@ -82,8 +125,9 @@ procedure; the same procedure is used for all major ## Install -The binaries can be installed automatically as **binary xPacks** or manually as -**portable archives**. +The executables and other related files can be installed automatically with +**xpm** via the **binary xPacks** or manually by downloading the +**platform specific archives**. The details of installing the **xPack GNU sed** on various platforms are presented in the diff --git a/website/docs/install/index.mdx b/website/docs/install/index.mdx index 4e16a32..7d92906 100644 --- a/website/docs/install/index.mdx +++ b/website/docs/install/index.mdx @@ -36,7 +36,7 @@ import Testing from './_testing.mdx'; The **xPack GNU sed** can be installed automatically, using the `xpm` command (the recommended method), or manually, by downloading and unpacking one of the -portable archives. +platform specific archives. ## Automated install diff --git a/website/src/components/HomepageFeatures/index.tsx b/website/src/components/HomepageFeatures/index.tsx index ebb2268..eceb069 100644 --- a/website/src/components/HomepageFeatures/index.tsx +++ b/website/src/components/HomepageFeatures/index.tsx @@ -15,6 +15,7 @@ import clsx from 'clsx'; import Heading from '@theme/Heading'; import styles from './styles.module.css'; +import Link from '@docusaurus/Link'; type FeatureItem = { title: string; @@ -28,10 +29,7 @@ const FeatureList: FeatureItem[] = [ Svg: require('@site/static/img/mosaic.svg').default, description: ( <> - By design, multiple versions of the same tools can be - installed at the same time on the same - system. The supported platforms are: GNU/Linux, macOS. - The tools include all required libraries and can be installed in any folder. + The xPack Framework aims to automate the installation of multiple versions of development tools that are otherwise not easily available in common software distributions, across multiple platforms (Windows, macOS, GNU/Linux). ), }, @@ -40,7 +38,7 @@ const FeatureList: FeatureItem[] = [ Svg: require('@site/static/img/check-badge.svg').default, description: ( <> - The xPack binaries can be added to projects + The binary xPacks can be added to projects as development dependencies, and conveniently installed with xpm install. This feature also ensures reproducibility, which is particularly @@ -53,7 +51,8 @@ const FeatureList: FeatureItem[] = [ Svg: require('@site/static/img/globe.svg').default, description: ( <> - The xpm tool complements npm with + The xpm CLI tool + complements npm with several extra features specific to C/C++ projects. This allows the binary xPacks to nicely integrate into the Node.js ecosystem,