Toolbox#
Supporting the development of xNVMe is a toolbox with a collection of
scripts in Python, Bash and a Makefile to instrument it. See section
Makefile helper for a description of it.
For common linter/format tooling then the pre-commit framework is used and described in section Pre-commit / Git-hooks.
Makefile helper#
As described in Getting Started, xNVMe uses the Meson
build-system, however, during development usage of the
Toolbox is invoked via make based on the
Makefile in the root of the xNVMe repository.
The Makefile contains a bunch of helper-targets. Invoking make help
provides a brief description of what is available:
Usage:
make help ; Brief target description
make help-verbose ; Verbose target descriptions
make [target] ; Invoke the given 'target'
Example:
make common && sudo make install
Targets:
_require_builddir ; This helper is not intended to be invoked via the command-line-interface.
build ; Build xNVMe with Meson
cijoe-install ; Install CIJOE and dependencies via pipx (used by CI and guest-env)
clean ; Remove Meson builddir
clean-subprojects ; Remove Meson builddir as well as running 'make clean' in all subprojects
clobber ; Invoke 'make clean' and: remove subproject builds, git-clean and git-checkout .
common ; Invokes: make info git-setup clean config build tags
config ; Configure Meson
config-debug ; Configure Meson to compile xNVMe with '--buildtype=debug'
config-slim ; Configure Meson to compile xNVMe without any third-party libraries
deb-dev ; Build a binary DEB of the checkout's build, for a test box
deb-dist ; Build the Debian packages from the source archive without subprojects, with
default ; Invoke: 'make help'
devenv-docgen ; Generate the documentation in the running guest, from the source it has;
devenv-down ; Stop the guest and remove the host container; DEVENV_HOME is kept
devenv-host ; Start the xnvme-devenv host container, unless running, without a guest
devenv-provision ; Build this tree's source archive and provision it into the running guest
devenv-run ; Run CMD in the host container, starting it unless running; no guest is
devenv-shell ; Open a shell in the host container
devenv-ssh ; SSH into the guest as root, on the port the host container publishes it on
devenv-sync ; Update the provisioned guest's source with this tree and rebuild only what
devenv-test ; Run tests in the running guest: those TESTS selects, or the guest's test task
devenv-up ; Start the xnvme-devenv host container, unless running, the guest in it, and
docgen-deps ; Install xNVMe's documentation tooling where cijoe runs; doxygen, graphviz and
docgen-guest ; Start and provision a QEMU guest, then generate the documentation in it
docker ; Drop into a privileged docker instance with the repository bind-mounted at /tmp/xnvme
docs ; Build docs using the new tooling (ctags, doxygen, apigen, toolchain, sphinx)
format ; Run code format (style, code-conventions and language-integrity) on staged changes
format-all ; Run code format (style, code-conventions and language-integrity) on staged and committed changes
gen-artifacts ; Generate artifacts in "/tmp/artifacts" for local guest provisioning
gen-libconf ; Helper-target generating third-party/subproject/os/library-configuration string
gen-man-pages ; Helper-target to produce man pages for tools (tools, examples, tests)
gen-src-archive ; Produce a source-archive (.tar.gz) without the source of SPDK, carrying only
gen-src-archive-with-subprojects ; Produce a source-archive (.tar.gz) with subproject-source
git-setup ; Do git config for: 'core.hooksPath' and 'blame.ignoreRevsFile'
guest-bench ; Prepare the provisioned guest for benchmarking, then run a benchmark in it
guest-docgen ; Generate the documentation in the provisioned guest, the transport
guest-env ; Setup guest environment: install CIJOE, check QEMU, select guest
guest-provision ; Sync source, build, and install xNVMe inside the guest (reads from cijoe/current.guest)
guest-select ; Interactive menu to select the active QEMU guest (or pipe: echo debian-trixie | make guest-select)
guest-start ; Kill, initialize, and start the QEMU guest (reads from cijoe/current.guest)
guest-stop ; Stop (kill) the QEMU guest (reads from cijoe/current.guest)
guest-test ; Run the CIJOE test task for the selected guest (reads from cijoe/current.guest)
help ; Print the description of every target
help-verbose ; Print the verbose description of every target
info ; Print information relevant to xNVMe
install ; Install xNVMe with Meson
install-deb ; Install the binary DEB package created with: make deb-dev
install-rpm ; Install the binary RPM package created with: make rpm-dev
rpm-dev ; Build a binary RPM of the checkout, installing to /usr/local, for a test box
rpm-dist ; Build RPMs the way a distribution would, from the source archive without
tags ; Helper-target to produce tags and compile-commands
tags-xnvme-public ; Make tags for public APIs
test ; Test xNVMe with Meson
uninstall ; Uninstall xNVMe with Meson
uninstall-deb ; Uninstall xNVMe with apt-get
uninstall-rpm ; Uninstall xNVMe with yum
verify-guest ; Chain: guest-start + guest-provision + guest-test (reads from cijoe/current.guest)
verify-ramdisk ; Build, install, prepare fio, and run the CIJOE ramdisk test suite
Local Testing#
To reproduce the CI test suite locally, in xnvme-devenv’s host container, see Developing in a guest.
Pre-commit / Git-hooks#
xNVMe utilizes the pre-commit framework for wrapping various code-format and linters tools. You can enable it to run via git-hooks or invoke it manually via the Makefile helper e.g.:
# format all files
make format-all
# format only files with staged changes
make format