From 9c37fa1bd6e2cdca3cbb7d2e216b37fb6bfc8619 Mon Sep 17 00:00:00 2001 From: Liviu Ionescu Date: Thu, 10 Oct 2024 01:33:33 +0300 Subject: [PATCH] website: updates --- website/docs/developer/index.mdx | 4 +- website/docs/getting-started/index.mdx | 59 ++++++++++++------- .../_common/_automatic-install-quick-test.mdx | 7 +++ .../_common/_manual-install-quick-test.mdx | 7 +++ website/docs/install/index.mdx | 41 ++++++------- website/docs/maintainer/index.mdx | 2 +- website/docusaurus.config.ts | 2 +- .../src/components/HomepageFeatures/index.tsx | 4 +- website/src/pages/index.tsx | 2 +- 9 files changed, 78 insertions(+), 50 deletions(-) diff --git a/website/docs/developer/index.mdx b/website/docs/developer/index.mdx index 431269b..d770fb4 100644 --- a/website/docs/developer/index.mdx +++ b/website/docs/developer/index.mdx @@ -56,7 +56,7 @@ for inexperienced users.
xPack build configurations -The xPack framework supports projects with **multiple build configurations**. +The xPack Framework supports projects with **multiple build configurations**. Build configurations are sets of **properties**, **actions** and **dependencies** that apply to a specific build. Build configurations can inherit from @@ -65,7 +65,7 @@ other build configurations. For simple projects, the typical use case is with two configurations, **Debug** and **Release**. -For building the xPack binary tools, there is one configuration +For building the binary xPack executables, there is one configuration for each platform: diff --git a/website/docs/getting-started/index.mdx b/website/docs/getting-started/index.mdx index ea8cb01..f094575 100644 --- a/website/docs/getting-started/index.mdx +++ b/website/docs/getting-started/index.mdx @@ -55,40 +55,57 @@ this project also includes the ## xPacks +**xPacks** (short for **xpm packages**) are general-purpose, +language-neutral software packages. +
-What the heck are xPacks? Please, not yet another package format! +What the heck are xPacks? Please, do not introduce another package format! + +While the initial appearance may seem complex, utilizing xPacks +(xpm packages) is, in fact, straightforward. +The design rationale is to automate frequent +operations that occur during software development, in this case the +installation of +dependencies, and to ensure reproducibility. + +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. + +The xPacks Framework **does NOT introduce a new package format**; instead, +it uses **the same format as npm packages**, which is a collection of +files/folders and a `package.json` file with the package metadata. -**xPacks** are general purpose multi-version software packages. +**xpm** can install packages from the +same repositories as **npm**, whether public or private. -There are two types of xPacks: +The packages (usually regular archives, but also git repositories), +are extracted into separate folders within the project. + +Based on the content, there are two types of packets: - **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 +The binary xPacks include references to 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. +These archives are also expanded along the package metadata. Since they +include executables, links/forwarders to +these executables are created in a `.bin` folder, +eliminating the need to add multiple folders to the `PATH`. -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. +Given that some binary xPacks, 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. -There is no magic behind **xpm**, it operates straightforwardly by -unpacking platform-specific archives into distinct directories and then creating links in the project to the corresponding executables. - -In short, xPacks are just a way to automate installing source libraries and -tools. +Simply put, xPacks can be used to further automate the installation of source +libraries and tools.
- ## Features All binaries are: @@ -130,7 +147,7 @@ procedure on **x64 Windows** ## Install The executables and other related files can be installed automatically with -**xpm** via the **binary xPacks** or manually by downloading the +**xpm** or manually by downloading the **platform specific archives**. The details of installing the **xPack Windows Build Tools** on various platforms are diff --git a/website/docs/install/_common/_automatic-install-quick-test.mdx b/website/docs/install/_common/_automatic-install-quick-test.mdx index 4192c02..bdea7d4 100644 --- a/website/docs/install/_common/_automatic-install-quick-test.mdx +++ b/website/docs/install/_common/_automatic-install-quick-test.mdx @@ -25,3 +25,10 @@ ${props.branding}${customField('upstreamVersion')} + +:::note + +The reported version is the upstream version, which is shorter than the xPack +version, as the latter requires more digits to identify the releases. + +::: diff --git a/website/docs/install/_common/_manual-install-quick-test.mdx b/website/docs/install/_common/_manual-install-quick-test.mdx index 0443285..a2f91f0 100644 --- a/website/docs/install/_common/_manual-install-quick-test.mdx +++ b/website/docs/install/_common/_manual-install-quick-test.mdx @@ -25,3 +25,10 @@ ${props.branding}${customField('upstreamVersion')} + +:::note + +The reported version is the upstream version, which is shorter than the xPack +version, as the latter requires more digits to identify the releases. + +::: diff --git a/website/docs/install/index.mdx b/website/docs/install/index.mdx index 217f307..92637c2 100644 --- a/website/docs/install/index.mdx +++ b/website/docs/install/index.mdx @@ -41,29 +41,26 @@ platform specific archives. ## Automated install The easiest (and recommended) way to install Windows Build Tools -is by using the **binary xPack**, available +is via **xpm** and the package available as @xpack-dev-tools/windows-build-tools from the [`npmjs.com`](https://www.npmjs.com) registry.
-xPacks 101 +xPacks refresher -While the initial appearance may seem complex, utilizing xPacks is, -in fact, straightforward. The design rationale is to automate frequent -operations that occur during software development, in this case the -installation of -dependencies, and to ensure reproducibility. +xPacks (short for xpm packages) 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. -xPacks are regular archives that are extracted into separate folders -within the project. If the xPacks contain -executables, links/forwarders to -these executables are created in a `.bin` folder, -eliminating the need to add multiple folders to the `PATH`. +Binary xPacks also 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. -Given that some binary xPacks, such as toolchains, can be quite large, -the archives 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. +For more details, please see the previous explanation in the +[Getting Started](/docs/getting-started/#xpacks) page.
@@ -135,12 +132,12 @@ If multiple binary packages are installed, in order to allow the executables to be accessed, one possible solution is to add all `/.content/bin` folders to the `PATH`. -To simplify things, **npm** employs a separate `node_modules/.bin` folder +To simplify things, **npm** employs a separate `/node_modules/.bin` folder where it places links/forwarders pointing to the actual executable files. Similarly, **xpm** adds links/forwarders into -a separate `xpacks/.bin` folder. +a separate `/xpacks/.bin` folder. With this setup, the project needs to prepend only this `.bin` folder to the `PATH`, and all the required tools are accesible @@ -212,7 +209,7 @@ already present. In addition to `name` & `version`, the minimal `package.json` must include a property named `xpacks`, even empty. This property is -mandatory to identify the package as an **xPack**. +mandatory to identify the package as an **xpm package**.
@@ -396,7 +393,7 @@ The binaries do not use any form of installer; instead they are distributed as portable {props.isWindows ? .zip : .tar.gz} archives; therefore they do not require to run any uninstaller; simply removing the -links and possibly the user global xPack store folder and +links and possibly the user global xPacks store folder and the user xPack cache folder is enough. To remove the created by @@ -413,7 +410,7 @@ and ask **xpm** to uninstall the package: `xpm uninstall @xpack-dev-tools/windows-build-tools --verbose `} -To completely remove the package from the user global xPack store: +To completely remove the package from the user global xPacks store: { `xpm uninstall --global @xpack-dev-tools/windows-build-tools --verbose @@ -438,7 +435,7 @@ For a thorough clean-up, please note that **xpm** uses only two folders: They can be removed at any time and space reclaimed; **xpm** will recreate them on new installs. -However, projects linking to the user global xPack store will fail with +However, projects linking to the user global xPacks store will fail with broken paths. diff --git a/website/docs/maintainer/index.mdx b/website/docs/maintainer/index.mdx index 53cec6c..5d53f7d 100644 --- a/website/docs/maintainer/index.mdx +++ b/website/docs/maintainer/index.mdx @@ -593,7 +593,7 @@ watching this project. ### Prepare a new blog post -- check and possibly update the `build-assets/templates/body-blog-release-*-liquid.md` +- check and possibly update the `website/blog/_templates/blog-post-release-part-[12]-liquid.md` - run the **generate-website-blog-post** xPack action; this will add a file in the `website/blog` folder: diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts index 9613520..c0ed42c 100644 --- a/website/docusaurus.config.ts +++ b/website/docusaurus.config.ts @@ -36,7 +36,7 @@ function getCustomFields() { const xpackVersion = jsonVersion.replace(/[.][0-9]*$/, ''); // Remove the pre-release. - const xpackSemver = xpackVersion.replace(/[-][0-9]*$/, ''); + const xpackSemver = xpackVersion.replace(/[-].*$/, ''); // Remove the first part, up to the dash. const xpackSubversion = xpackVersion.replace(/^.*[-]/, ''); diff --git a/website/src/components/HomepageFeatures/index.tsx b/website/src/components/HomepageFeatures/index.tsx index 0deac69..f9f13d8 100644 --- a/website/src/components/HomepageFeatures/index.tsx +++ b/website/src/components/HomepageFeatures/index.tsx @@ -38,7 +38,7 @@ const FeatureList: FeatureItem[] = [ Svg: require('@site/static/img/check-badge.svg').default, description: ( <> - The binary xPacks can be added to projects + The binary packages can be added to projects as development dependencies, and conveniently installed with xpm install. This feature also ensures reproducibility, which is particularly @@ -55,7 +55,7 @@ const FeatureList: FeatureItem[] = [ complements npm with several extra features specific to C/C++ projects. This allows the - binary xPacks to nicely integrate into the Node.js ecosystem, + binary packages to nicely integrate into the Node.js ecosystem, while still allowing the binary archives to be installed manually. ), diff --git a/website/src/pages/index.tsx b/website/src/pages/index.tsx index 37d3d40..cf377ac 100644 --- a/website/src/pages/index.tsx +++ b/website/src/pages/index.tsx @@ -43,7 +43,7 @@ export default function Home(): JSX.Element { return ( + description="A binary package with the Windows Build Tools executables">