diff --git a/website/docs/install/_common/_automated-install.mdx b/website/docs/install/_common/_automated-install.mdx index 73cd8e4..5a6d5b9 100644 --- a/website/docs/install/_common/_automated-install.mdx +++ b/website/docs/install/_common/_automated-install.mdx @@ -21,18 +21,21 @@ the [`npmjs.com`](https://www.npmjs.com) registry. xPacks 101 While the initial appearance may seem complex, utilizing xPacks is, -in fact, straightforward. The design rationale is to automate common -steps in software development, in this case the installation of dependencies. +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 standard archives that are extracted into separate folders -within the project. If the xPacks contain executables, symbolic -links to these executables are created in a `.bin` folder, +within the project. If the xPacks contain +executables, to +these executables are created in a `.bin` folder, eliminating the need to add multiple folders to the `PATH`. Given that some binary xPacks, such as toolchains, can be quite large, the archives are extracted only once into a central/global location to -conserve space. In projects, instead of duplicating these files, symbolic -links are created. +conserve space. In projects, instead of duplicating the content of these +archives, symbolic links are created. @@ -66,40 +69,75 @@ a **node** >=18.17.0). :::
-Local vs. global installs +Local installs -To ensure reproducibility, it is essential for each project to be able to -use specific versions of the required tools. +One of the xPack design goals is to allow each project to +choose the exact versions of the tools it requires. Similarly to **npm** being able to install specific versions of the JavaScript tools into each project, **xpm** was also designed to be able to install specific versions of the -required binary tools into each project. +required binary tools locally into each project. + +Therefore, similarly to the way **npm** installs the JavaScript packages into +`node_modules`, **xpm** installs the binary tools into +`xpacks`. Here there will be separate folders with the installed +packages, for example +xpacks/@xpack-dev-tools/riscv-none-elf-gcc. + +Each such folder includes the `package.json` file with the +project metadata and a sub-folder `.content` with the extracted +binary archive. The executables are usually in `.content/bin`. + +:::tip + +On some platforms, names starting with `.` (dot) might be hidden for +normal browsing, and seeing them requires +separate options (like `ls -A`) or, in file browsers, to enable +settings like **Show Hidden Files**. + +::: + +
+ +
+The `xpacks/.bin` folder + +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 +where it places +pointing to the actual executable files. + +Similarly, **xpm** adds into +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 +and prefered to possible system tools. -Therefore, similarly to the way **npm** installs the JavaScript tools in -`node_modules/.bin`, **xpm** installs the binary tools in -`xpacks/.bin`.
-The central xPacks store +Global installs and the central xPacks store Given that some binary tools (such as toolchains) can be very large (hundreds of megabytes or more), it is impractical to keep multiple copies of these tools, one for each project. Instead, **xpm** installs the binary packages only once -into a central store, a platform-dependent folder -within the home folder, thereby conserving disk space when the same tools are -used across multiple projects. +into a central store (a platform-dependent folder +within the home folder), thereby conserving disk space when the same +tools are used across multiple projects. In order to allow the projects to access the binary tools installed in the -central folder, -**xpm** adds -into the projects, pointing to the **central xPacks store**. +central folder, instead of unpacking the archives in `xpacks`, +**xpm** adds symbolic links pointing to the **central xPacks store**. -The outcome is functionally equivalent to installing the tools in each project, -but without the wasted disk space. +The outcome is functionally equivalent to installing the tools into +each project, but without the wasted disk space. :::tip @@ -108,9 +146,9 @@ by passing `--copy` to `xpm install`. ::: -If needed, it is also possible to install packages only globally, -without creating local -(see below). +If needed, it is also possible to install packages only globally, without +creating local (see below). +
### Initialise the project @@ -135,7 +173,9 @@ The next step is to install the `xpm install @xpack-dev-tools/riscv-none-elf-gcc@latest --verbose` } -The main result is a set of in the `.bin` folder: +The main result is a set +of in +the `.bin` folder: { `${ props.isWindows === 'True' ? 'dir xpacks\\.bin' : 'ls -l xpacks/.bin' }` @@ -145,7 +185,7 @@ The main result is a set of i PATH setup With all binary tools installed in `xpacks/.bin`, the project build -configurations need a single PATH adjustment: +configurations need only a single PATH adjustment: ```sh export PATH=<...project-path...>/xpacks/.bin:$PATH @@ -171,8 +211,12 @@ The above `xpm install` command will do the following: in the **central xPacks store** (if not already there); check the output of the `xpm` command for the actual folder used on your platform; -* add - into the local `xpacks/.bin` folder, referring to the binaries in the central store; +* create a local symbolic link + like xpacks/@xpack-dev-tools/riscv-none-elf-gcc pointing to the + versioned folder in the central xPacks store +* add into + the local `xpacks/.bin` folder, referring to the binaries in + xpacks/@xpack-dev-tools/riscv-none-elf-gcc/.content/bin; * add @xpack-dev-tools/riscv-none-elf-gcc to `package.json` as a development dependency; this associates a specific version of GNU RISC-V Embedded GCC with @@ -186,21 +230,16 @@ The install location can be configured using the ::: -:::tip - -**xpm** unpacks the archive content into a folder -named `.content`. On some platforms -this might be hidden for normal browsing, and seeing it requires -separate options (like `ls -A`) or, in file browsers, to enable -settings like **Show Hidden Files**. - -:::
-devDependencies +Reproducibility and `devDependencies` + +To ensure reproducibility, it is essential for each project to always +use the exact desired versions of the required tools, regardless of the +tools installed in the system. -As mentioned before, **xpm** adds all locally installed binary packages +To achieve this goal, **xpm** records all locally installed binary packages as development dependencies in the project `package.json` file. The result looks like this: @@ -223,14 +262,14 @@ The result looks like this: } If the `package.json` is saved in the revision system, the above -definition adds -a hard reference to the specific version of +definition acts as a hard reference to the specific version of **xPack GNU RISC-V Embedded GCC**. -After cloning the project to a different location, the command `xpm install` +After cloning the project into a different location, the command `xpm install` can be used to install all development dependencies. This is particularly useful for CI/CD environments. +
### Install globally diff --git a/website/docs/install/_common/_manual-info.mdx b/website/docs/install/_common/_manual-info.mdx index fa85d0e..386f522 100644 --- a/website/docs/install/_common/_manual-info.mdx +++ b/website/docs/install/_common/_manual-info.mdx @@ -4,7 +4,7 @@ :::info For manual installs, the recommended -install location is slightly different from the xpm install folders, +install location is slightly different then the folders created by `xpm install`, which use the `@xpack-dev-tools` scope to group different tools, and `.content` to store the unpacked archive."