Skip to content

Commit

Permalink
website: install updates
Browse files Browse the repository at this point in the history
  • Loading branch information
ilg-ul committed Jul 31, 2024
1 parent 7d8ca0e commit c08e932
Show file tree
Hide file tree
Showing 2 changed files with 83 additions and 44 deletions.
125 changes: 82 additions & 43 deletions website/docs/install/_common/_automated-install.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -21,18 +21,21 @@ the [`npmjs.com`](https://www.npmjs.com) registry.
<summary>xPacks 101</summary>

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, <LinksVsForwarders isWindows={ props.isWindows }/> 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.

</details>

Expand Down Expand Up @@ -66,40 +69,75 @@ a **node** >=18.17.0).
:::

<details>
<summary>Local vs. global installs</summary>
<summary>Local installs</summary>

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
<code>xpacks/@xpack-dev-tools/riscv-none-elf-gcc</code>.

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**.

:::

</details>

<details>
<summary>The `xpacks/.bin` folder</summary>

If multiple binary packages are installed, in order to allow
the executables to be accessed, one possible solution is to add
all `<package>/.content/bin` folders to the `PATH`.

To simplify things, **npm** employs a separate `node_modules/.bin` folder
where it places <LinksVsForwarders isWindows={ props.isWindows }/>
pointing to the actual executable files.

Similarly, **xpm** adds <LinksVsForwarders isWindows={ props.isWindows }/> 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`.
</details>

<details>
<summary>The central xPacks store</summary>
<summary>Global installs and the central xPacks store</summary>

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 <LinksVsForwarders isWindows={ props.isWindows }/>
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

Expand All @@ -108,9 +146,9 @@ by passing `--copy` to `xpm install`.

:::

If needed, it is also possible to install packages only globally,
without creating local <LinksVsForwarders isWindows={ props.isWindows }/>
(see below).
If needed, it is also possible to install packages only globally, without
creating local <LinksVsForwarders isWindows={ props.isWindows }/> (see below).

</details>

### Initialise the project
Expand All @@ -135,7 +173,9 @@ The next step is to install the
`xpm install @xpack-dev-tools/riscv-none-elf-gcc@latest --verbose`
} </CodeBlock>

The main result is a set of <LinksVsForwarders isWindows={ props.isWindows }/> in the `.bin` folder:
The main result is a set
of <LinksVsForwarders isWindows={ props.isWindows }/> in
the `.bin` folder:

<CodeBlock language="console"> {
`${ props.isWindows === 'True' ? 'dir xpacks\\.bin' : 'ls -l xpacks/.bin' }`
Expand All @@ -145,7 +185,7 @@ The main result is a set of <LinksVsForwarders isWindows={ props.isWindows }/> i
<summary>PATH setup</summary>

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
Expand All @@ -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 <LinksVsForwarders isWindows={ props.isWindows }/>
into the local `xpacks/.bin` folder, referring to the binaries in the central store;
* create a local symbolic link
like <code>xpacks/@xpack-dev-tools/riscv-none-elf-gcc</code> pointing to the
versioned folder in the central xPacks store
* add <LinksVsForwarders isWindows={ props.isWindows }/> into
the local `xpacks/.bin` folder, referring to the binaries in
<code>xpacks/@xpack-dev-tools/riscv-none-elf-gcc/.content/bin</code>;
* add <code>@xpack-dev-tools/riscv-none-elf-gcc</code> to
`package.json` as a
development dependency; this associates a specific version of GNU RISC-V Embedded GCC with
Expand All @@ -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**.

:::
</details>

<details>
<summary>devDependencies</summary>
<summary>Reproducibility and `devDependencies`</summary>

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:
Expand All @@ -223,14 +262,14 @@ The result looks like this:
} </CodeBlock>

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.

</details>

### Install globally
Expand Down
2 changes: 1 addition & 1 deletion website/docs/install/_common/_manual-info.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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."

Expand Down

0 comments on commit c08e932

Please sign in to comment.