Getting Started with xpm
To meet the specific needs of different audiences, this site features separate User's Guide, Contributor's Guide and Maintainer's Guide pages. This way, each group can easily find the information and resources most relevant to them.
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 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.
Documentation
The project documentation is currently available exclusively on the project's website.
Release schedule
There are no scheduled releases; the project adheres to a continuous release approach, with updates deployed as development progresses.
Releases
The list of releases is available in the Releases pages.
Change log
The release and change log is available in the repository
CHANGELOG.md file.
Support & feedback
The quick advice for getting support and providing feedback is to use the GitHub Discussions.
For additional information, please refer to 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.
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 otherwise stated, the original content is released 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 enjoyed using this project, please let us know! Here are some ways you can show your support:
