Getting Started#

Here you will be taken through the process of Building and installing xNVMe, which includes retrieving the xNVMe source, installing a C compiler / toolchain, libraries, and then building and installing xNVMe itself. With xNVMe in place on your system, an Example Program is provided for you to Compile, link, and run!.

Building and installing#

Below are examples of building and installing xNVMe on different operating systems. Additional examples and detailed information can be found in the Toolchain section, covering numerous Linux distributions, as well as FreeBSD, macOS, and Windows versions.

# Clone the xNVMe repos
git clone https://github.com/xnvme/xnvme.git
cd xnvme

# Install toolchain and libraries on Linux (Debian Bookworm)
sudo ./toolbox/pkgs/debian-bookworm.sh

# configure xNVMe and build meson subprojects(SPDK)
meson setup builddir

# build xNVMe
meson compile -C builddir

# install xNVMe
sudo meson install -C builddir

# uninstall xNVMe
# cd builddir && meson --internal uninstall

# Clone the xNVMe repos
git clone https://github.com/xnvme/xnvme.git
cd xnvme

# Install toolchain and libraries on FreeBSD (13)
sudo ./xnvme/toolbox/pkgs/freebsd-13.sh

# configure xNVMe and build meson subprojects(SPDK)
meson setup builddir

# build xNVMe
meson compile -C builddir

# install xNVMe
sudo meson install -C builddir

# uninstall xNVMe
# cd builddir && meson --internal uninstall

# Clone the xNVMe repos
git clone https://github.com/xnvme/xnvme.git
cd xnvme

# Install toolchain and libraries on macOS (14)
sudo ./xnvme/toolbox/pkgs/macos-14.sh

# configure xNVMe
meson setup builddir

# build xNVMe
meson compile -C builddir

# install xNVMe
sudo meson install -C builddir

# uninstall xNVMe
# cd builddir && meson --internal uninstall

# Clone the xNVMe repos
git clone https://github.com/xnvme/xnvme.git
cd xnvme

# Install toolchain and libraries on Windows (2022)
Set-ExecutionPolicy Bypass -Scope Process -Force
.\toolbox\pkgs\windows-2022.ps1

# Setup helper-function to invoke commands inside msys2 environment from Powershell
function run { param([string]$cmd=$(throw "You must specify a command.")); & msys2_shell -no-start -here -use-full-path -defterm -mingw64 -c "$cmd" }

# configure xNVMe (adjust this to correct path)
run "meson setup builddir --prefix=/usr"

# build xNVMe
run "meson compile -C builddir"

# install xNVMe
run "meson install -C builddir"

# uninstall xNVMe
# cd builddir && run "meson --internal uninstall"

Note

Run this in an elevated Powershell session!

Building system software can be challenging. If you encounter errors when following the steps above, and if meson is new to you, a couple of pointers are provided to help you out. You can also look at the Troubleshooting section for known issues.

Build-errors: Details on the build errors can be seen by inspecting the log file at builddir/meson-logs/meson-log.txt.
Rebuilding: In case rebuilding fails, e.g., due to errors during meson setup or missing toolchain/dependencies, remove the builddir folder. If errors persist, try also removing the SPDK subproject at subprojects/spdk.
Customizing-the-build: If you want to customize the build, e.g., install into a different location, this is handled by meson built-in options. In addition, you can inspect meson_options.txt which contains options specific to xNVMe.

Example Program#

This example code illustrates how to use the xNVMe library (libxnvme) in C to perform the following tasks with an NVMe device: open the device, probe and retrieve device information, print device information, and finally close the device.

#include <errno.h>
#include <libxnvme.h>

int
main(int argc, char **argv)
{
	struct xnvme_opts opts = xnvme_opts_default();
	struct xnvme_dev *dev;

	if (argc < 2) {
		xnvme_cli_perr("Usage: %s <identifer>", EINVAL);
		return 1;
	}

	dev = xnvme_dev_open(argv[1], &opts);
	if (!dev) {
		xnvme_cli_perr("xnvme_dev_open()", errno);
		return 1;
	}

	if (xnvme_dev_derive_geo(dev)) {
		printf("Failed deriving geometry, check your permissions.");
	}
	xnvme_dev_pr(dev, XNVME_PR_DEF);
	xnvme_dev_close(dev);

	return 0;
}

Additional examples of using the xNVMe C API can be found in the xNVMe repository. This includes explicit example code, the source for the command-line tools, and tests. For examples of efficient and high-performance integration, refer to the fio xNVMe I/O engine and the SPDK xNVMe bdev module.

Furthermore, while the example given above is written in C, bindings for the xNVMe C API are also available for other languages. These include Python ( Pypi ) bindings and Rust ( crates.io ) bindings.

Compile, link, and run!#

xNVMe provides a pkg-config file (xnvme.pc), it is populated to fit the version of xNVMe installed on the system. Use it to ensure you get the correct flags. For example, like so:

# Build, link and make the example executable
gcc ../getting_started/hello.c  $(pkg-config --libs xnvme) -o hello
chmod +x hello

# Run it
./hello /dev/nvme2n1