Getting Started with xpm
To cater to the diverse requirements of its audience, this site offers distinct pages: User's Guide, Contributor's Guide and Maintainer's Guide. Each guide is tailored to ensure users can efficiently access the information and resources most pertinent to their specific roles or needs.
First, let's clarify what xpm is NOT
- xpm is NOT a npm replacement (like yarn or pnpm)
- xpm is NOT just another package manager (like apt, rpm, etc)
- xpm is NOT introducing a new package format (it uses the npm format)
- xpm is NOT a build system (like CMake or meson)
So, what is xpm?
xpm, short for xPack Project Manager, is a Node.js CommonJS module and a CLI application designed to automate builds, conduct tests, and manage C/C++ dependencies.
It is also a package manager, offering features similar to those of npm, but extending them to C/C++ source libraries and binary tools. Additionally, it manages build configurations, actions, properties, substitutions and more. It runs on Windows, macOS and GNU/Linux.
Compatibility with legacy CommonJS is required until VS Code extensions will be updated to import ES6 modules.
The open source project is hosted on GitHub as xpack/xpm-js and is published on npmjs.com as xpm.
But why?
I am perfectly content with my development environment, so why should I consider using xpm packages (xPacks)?
While current development environments are indeed excellent, and rolling distributions like Arch and Homebrew do an outstanding job of keeping systems up-to-date, it is not uncommon for the latest versions to disrupt older applications and various complex processes, such as build scripts, that rely on older versions.
The xpm dependency mechanism is designed to address this issue by providing a straightforward and consistent solution for installing different versions of the same package in separate folders and managing dependencies.
Nix also offers reproducible builds and a vast array of packages, so why consider xpm packages?
Nix is an excellent project that rigorously controls versions down to the individual library. However, it relies on file links, which are either unavailable or unreliable on Windows, making Nix currently available only on GNU/Linux and macOS. Additionally, mastering the Nix language requires considerable effort.
Why couldn't npm be used as-is, and why was it necessary to invent xpm?
Each package manager implements a specific strategy for managing dependencies. npm, yarn, and pnpm all employ strategies tailored to ECMAScript dependencies.
Unfortunately, these strategies do not work for other languages, such as C/C++. Additionally, it would be very challenging and require inelegant hacks to adapt development dependencies to binary archives (for tools like compilers).
Why bother managing versions when auto-configure can sort out the differences?
Traditionally, dealing with different versions and variations between systems involves adding a complex auto-configure mechanism. This mechanism detects which tools and components are present, identifies their versions, and uses this information to parametrise the process (such as a project build) to accommodate all these differences.
This approach began with GNU configure and has evolved to include even more complex solutions, like CMake or Meson scripts.
Instead of constantly figuring out how to utilise new versions and making the auto-configure scripts increasingly complex, why not allow the application to request the exact versions known to be compatible and let an automated tool handle the dependencies?
The xpm can do precisely this, bringing the exact versions needed into the project, thus rendering the auto-configure step superfluous.
What are xpm packages? (xPacks)
xpm packages, abbreviated as xPacks, are versatile, language-neutral software packages. They have been successfully utilised in C/C++ projects.
What the heck are xpm packages (xPacks)? Please, do not introduce another package format!
Based on the content, there are two types of xpm packages:
- packages with source libraries (source xpm packages)
- packages with executables, usually platform-specific binary tools (binary xpm packages)
Source xpm packages are regular npm packages that include library source files, typically in C/C++, though there are no language restrictions.
Binary xpm packages are also regular npm packages, but with minimal
content, typically just the package.json file. Since these packages
provide executables for multiple platforms, some of which are quite
large, it is not practical to include all binaries within the npm
package itself. Instead, the package.json file contains references
(URLs) to platform-specific binary archives (e.g., .tar.gz for Unix or
.zip for Windows).
These archives are also expanded along with the package metadata.
Links/forwarders to
these executables are created in a .bin folder,
eliminating the need to add multiple folders to the PATH.
In summary, xpm packages can streamline and automate the installation process for source libraries and tools. Further details are available on the Concepts page.
By design, xpm packages support multiple versions, allowing packages to have various versions installed simultaneously. Each project or build configuration can maintain its own set of dependencies, ensuring that system upgrades do not affect existing projects.
Package Author's Guide
Using xpm with existing packages is relatively straightforward.
However, creating new packages or adding the xpm metadata to an
existing project is somewhat more complex and requires an understanding
of xpm concepts and metadata, which are documented in the
Package Author's Guide.
Features
By design, the xPack Framework aims to automate:
- Managing dependencies
- Managing build configurations
- The component configurations process
- The build process
xpm complements npm by streamlining cross-platform builds and tests with its distinctive features:
- Cross-Platform Support: Operates seamlessly on Windows, macOS, and GNU/Linux.
- Package Installation: Installs the same format of packages as npm, including those from Git repositories and the npm public repository (npmjs.com).
- Version Locking: Locks specific versions of source and binary packages as project dependencies, installing them on demand.
- Build Configurations: Manages multiple build configurations, such as debug/release builds or platform-specific tests.
- Configuration Dependencies: Locks specific versions of packages as build configuration dependencies.
- Command Actions: Defines multi-line command actions at the project or build configuration level.
- Property Management: Manages properties with complex substitutions, using the LiquidJS engine.
Benefits
- Being able to develop exactly the same project on Windows, macOS and GNU/Linux provides team members with the flexibility to use their preferred platform.
- Locking projects to specific versions of dependencies ensures reproducibility, providing stability over time and across different environments.
- Defining dependencies at the build configuration level allows for testing across different architectures, such as native, Arm, and RISC-V.
- Installing multiple versions of the same package simultaneously enables testing with various versions of the same toolchain.
- Running multi-line commands with parameters and substitutions offer a robust and portable scripting mechanism.
- Installing packages directly from Git/GitHub simplifies the maintenance of some packages during development.
Install
xpm is a npm package available from the npmjs.com public registry and can be installed via npm.
The easiest way to get the install command is from the website's homepage. Simply hover the mouse over the command, and a copy button will appear on the right side. Click it to copy the command.
For comprehensive installation instructions, please visit the Install Guide page.
Status
xpm is fully functional, but it is still under development;
therefore, according to
SemVer, the version is kept as 0.y.z.
Upon completion, releases will start from version 1.0.0, signifying the program's transition to production status.
As xpm is still under development, it is recommended to use it with caution.
Testing
The library undergoes continuous integration (CI) testing with every push using GitHub Actions. This ensures compatibility and stability across Ubuntu, macOS, and Windows operating systems.
The tests are conducted on both 32-bit and 64-bit bare-metal platforms, including Arm Cortex-M0, Cortex-M3, Cortex-M4F, Cortex-M7F, Cortex-A15, Cortex-A72, RISC-V RV32IMAC, and RV64IMAFDC. Additionally, native testing is performed using GCC and LLVM/clang compilers, ensuring thorough validation across various environments.
Release schedule
There are no scheduled releases; the project adheres to a continuous release approach, with updates deployed as development progresses.
Releases
A complete list of releases can be found on the Releases pages.
Change log
The release notes and change log can be accessed in the repository's
CHANGELOG.md
file.
Support & feedback
For prompt support and to provide feedback, it is recommended to utilise GitHub Discussions.
For more detailed information, please visit the Help Centre page.
Compatibility notices
According to SemVer rules:
Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API.
The breaking changes introduced in each major release are documented in reverse chronological order. This information provides a comprehensive overview of significant modifications and is readily available in the respective release notes.
v0.0.0
All v0.*.* were development versions, with features gradually added.
v0.14.0
The xpm dependencies were separated from npm dependencies and policy 0001 was introduced.
v0.19.0
The Node.js base was increased to 18.0; no incompatibilities.
v0.20.0
The list of executable applications in binary xPacks was renamed from
xpack.bin to xpacks.executables.
License
Unless explicitly mentioned otherwise, the original content is distributed under the terms of the MIT License, with all rights reserved by Liviu Ionescu.
Credits
Special thanks to MacStadium, for providing the Apple Silicon development infrastructure as part of their generous Free and Open Source Software program.
Thanks to Shields IO for the badges.
Enjoyed Using This Project? Let Us Know!
If you've found this project valuable, we'd love to hear from you! Here are some ways you can show your support:
- Donate: Every contribution, no matter the size, helps sustain the xPack . Your generosity keeps the development alive and thriving.
- Star the project on GitHub: Help others discover our work by giving it a star — it makes a difference!
- Follow Us on X/Twitter: Stay informed about our latest updates, releases, and news by following our account.
Your support is greatly appreciated and motivates us to continue improving!