libnvme


Namelibnvme JSON
Version 1.8 PyPI version JSON
download
home_pagehttps://github.com/linux-nvme/libnvme
Summarypython bindings for libnvme
upload_time2024-02-14 09:42:06
maintainer
docs_urlNone
authorHannes Reinecke
requires_python
licenseLGPL-2.1-or-later
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # libnvme

![MesonBuild](https://github.com/linux-nvme/libnvme/actions/workflows/build.yml/badge.svg)
![PyBuild](https://github.com/linux-nvme/libnvme/actions/workflows/release-python.yml/badge.svg)
[![PyPI](https://img.shields.io/pypi/v/libnvme)](https://pypi.org/project/libnvme/)
[![PyPI - Wheel](https://img.shields.io/pypi/wheel/libnvme)](https://pypi.org/project/libnvme/)
![GitHub](https://img.shields.io/github/license/linux-nvme/libnvme)
[![codecov](https://codecov.io/gh/linux-nvme/libnvme/branch/master/graph/badge.svg)](https://codecov.io/gh/linux-nvme/libnvme)
[![Read the Docs](https://img.shields.io/readthedocs/libnvme)](https://libnvme.readthedocs.io/en/latest/)

This is the libnvme development C library. libnvme provides type
definitions for NVMe specification structures, enumerations, and bit
fields, helper functions to construct, dispatch, and decode commands
and payloads, and utilities to connect, scan, and manage nvme devices
on a Linux system.

The public specification is the authority to resolve any protocol
discrepancies with this library. For more info on NVM Express, please
see:

  https://nvmexpress.org

Subscribe to linux-nvme@lists.infradead.org for linux-nvme related
discussions and development for both kernel and userspace. The list is
archived here:

  https://lists.infradead.org/mailman/listinfo/linux-nvme

# License

Except where otherwise stated, all software contained within this repo
is currently licensed LGPL-2.1-or-later, see COPYING for more
information.

Keith Busch 2020-02-06

------

# Dependency

libnvme depends on minimum Linux kernel version v4.15, which
introduced the /sys/class/nvme-subsystem.

# Build from source
## Prerequisite

A minimal build depends on a set of build tools

  - gcc
  - ninja
  - meson

Not all feature will be present with such configuration, e.g.
the fabrics part of the library wont support authentication or
TLS over the nvme-tcp transport.

To enable the optional features install following libraries

`/etc/nvme/config.json`` support:
  - json-c (recommend)

Authentication and TLS over nvme-tcp:
  - openssl
  - keyutils

End point discovery for MI
  - libdbus

Python bindings
  - Python 3 interpreter
  - Python 3 development libraries

## Minimal on embedded builds

The reference implemention of the Meson specification is in Python 3. Installing
or porting this dependency is not really feasible for embedded project. Though
there are two project which implement the Ninja and the Meson API in pure C99

  - samurai: https://github.com/michaelforney/samurai.git
  - muon: https://git.sr.ht/~lattis/muon

The CI build helper script `scripts/build.sh` is able to setup and build this
project in a minimal setup using samurai and muon and thus only depending on:
- gcc
- make
- git

`scripts/build.sh -m muon`

## To compile libnvme

To `configure` the project:

```
meson setup .build
```

Which will default to build a shared library. To configure for static libraries call

```
meson setup --default-library=static .build
```

One nice feature of meson is that it doesn't mix build artifacts
(e.g. `*.o`, `*.so`, etc.) with source code. In the above example,
"`.build`" is the name of the directory where the build configuration
as well as all the build artifacts will be saved. This directory can
be named anything as long as it's not an existing source directory. To
completely "clean" all the build artifacts, one need only delete the
`.build` directory.

To compile:

```
meson compile -C .build
```

## To install libnvme

To install `libnvme`:

```
meson install -C .build
```

## To run unit tests

To run unit tests:

```
meson test -C .build
```

## To purge everything

To completely clean all build artifacts, including the build configuration.

```
rm -rf .build
```

## Supported build options

A few build options can be specified on the command line when invoking meson.

| Option      | Values [default]          | Description                                                  |
| ----------- | ------------------------- | ------------------------------------------------------------ |
| version-tag | none                      | Overwrite the git version string in the binary               |
| htmldir     | none                      | Installation directory for the HTML documentation            |
| rstdir      | none                      | Installation directory for the RST documentation             |
| docs        | [false], html, man, rst, all | Install documentation                                     |
| docs-build  | [false], true             | Enable build documentation                                   |
| python | [auto], enabled, disabled | Whether to build the Python bindings. When set to `auto`, the default, meson will check for the presence of the  tools and libraries (e.g. `swig`) required to build the Python bindings. If found, meson will configure the project to build the Python bindings. If a tool or library is missing, then the Python bindings won't be built. Setting this to `enabled`, forces the Python bindings to be built. When set to `disabled`, meson will configure the project to not build the Python bindings.<br />Example: `meson setup .build -Dpython=disabled` |
| openssl     | [auto], enabled, disabled | Enables OpenSSL dependent features (e.g. TLS over TCP), adds build dependency on OpenSSL |
| libdbus     | auto, enabled, [disabled] | Enables D-Bus dependent features (libnvme-mi: End point discovery), adds build dependency on libdbus |
| json-c      | [auto], enabled, disabled | (recommended) Enables JSON-C dependend features (e.g. config.json parsing), adds build depdency on json-c |
| keyutils    | [auto], enabled, disabled | Enables keyutils dependent features (e.g. authentication), adds build dependency on keyutils |

See the full configuration options with

```bash
meson configure .build
```

### Changing the build options from the command-line (i.e. w/o modifying any files)

To configure a build for debugging purposes (i.e. optimization turned
off and debug symbols enabled):

```bash
meson setup .build --buildtype=debug
```

To enable address sanitizer (advanced debugging of memory issues):

```bash
meson setup .build -Db_sanitize=address
```

This option adds `-fsanitize=address` to the gcc options. The tests can then be run normally (`meson test -C .build`).

Note that when using the sanitize feature, the library `libasan.so` must be available and must be the very first library loaded when running an executable. If experiencing linking issues, you can ensure that `libasan.so` gets loaded first with the `LD_PRELOAD` environment variable as follows:

```
meson setup .build -Db_sanitize=address && LD_PRELOAD=/lib64/libasan.so.6 ninja -C .build test
```

It's also possible to enable the undefined behavior sanitizer with `-Db_sanitize=undefined`. To enable both, use `-Db_sanitize=address,undefined`.

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/linux-nvme/libnvme",
    "name": "libnvme",
    "maintainer": "",
    "docs_url": null,
    "requires_python": "",
    "maintainer_email": "",
    "keywords": "",
    "author": "Hannes Reinecke",
    "author_email": "hare@suse.de",
    "download_url": "https://files.pythonhosted.org/packages/ed/3a/b034b3d5e62c6154f8159429ce94207e38b2ccbadd562bb995b67ebd9b88/libnvme-1.8.tar.gz",
    "platform": null,
    "description": "# libnvme\n\n![MesonBuild](https://github.com/linux-nvme/libnvme/actions/workflows/build.yml/badge.svg)\n![PyBuild](https://github.com/linux-nvme/libnvme/actions/workflows/release-python.yml/badge.svg)\n[![PyPI](https://img.shields.io/pypi/v/libnvme)](https://pypi.org/project/libnvme/)\n[![PyPI - Wheel](https://img.shields.io/pypi/wheel/libnvme)](https://pypi.org/project/libnvme/)\n![GitHub](https://img.shields.io/github/license/linux-nvme/libnvme)\n[![codecov](https://codecov.io/gh/linux-nvme/libnvme/branch/master/graph/badge.svg)](https://codecov.io/gh/linux-nvme/libnvme)\n[![Read the Docs](https://img.shields.io/readthedocs/libnvme)](https://libnvme.readthedocs.io/en/latest/)\n\nThis is the libnvme development C library. libnvme provides type\ndefinitions for NVMe specification structures, enumerations, and bit\nfields, helper functions to construct, dispatch, and decode commands\nand payloads, and utilities to connect, scan, and manage nvme devices\non a Linux system.\n\nThe public specification is the authority to resolve any protocol\ndiscrepancies with this library. For more info on NVM Express, please\nsee:\n\n  https://nvmexpress.org\n\nSubscribe to linux-nvme@lists.infradead.org for linux-nvme related\ndiscussions and development for both kernel and userspace. The list is\narchived here:\n\n  https://lists.infradead.org/mailman/listinfo/linux-nvme\n\n# License\n\nExcept where otherwise stated, all software contained within this repo\nis currently licensed LGPL-2.1-or-later, see COPYING for more\ninformation.\n\nKeith Busch 2020-02-06\n\n------\n\n# Dependency\n\nlibnvme depends on minimum Linux kernel version v4.15, which\nintroduced the /sys/class/nvme-subsystem.\n\n# Build from source\n## Prerequisite\n\nA minimal build depends on a set of build tools\n\n  - gcc\n  - ninja\n  - meson\n\nNot all feature will be present with such configuration, e.g.\nthe fabrics part of the library wont support authentication or\nTLS over the nvme-tcp transport.\n\nTo enable the optional features install following libraries\n\n`/etc/nvme/config.json`` support:\n  - json-c (recommend)\n\nAuthentication and TLS over nvme-tcp:\n  - openssl\n  - keyutils\n\nEnd point discovery for MI\n  - libdbus\n\nPython bindings\n  - Python 3 interpreter\n  - Python 3 development libraries\n\n## Minimal on embedded builds\n\nThe reference implemention of the Meson specification is in Python 3. Installing\nor porting this dependency is not really feasible for embedded project. Though\nthere are two project which implement the Ninja and the Meson API in pure C99\n\n  - samurai: https://github.com/michaelforney/samurai.git\n  - muon: https://git.sr.ht/~lattis/muon\n\nThe CI build helper script `scripts/build.sh` is able to setup and build this\nproject in a minimal setup using samurai and muon and thus only depending on:\n- gcc\n- make\n- git\n\n`scripts/build.sh -m muon`\n\n## To compile libnvme\n\nTo `configure` the project:\n\n```\nmeson setup .build\n```\n\nWhich will default to build a shared library. To configure for static libraries call\n\n```\nmeson setup --default-library=static .build\n```\n\nOne nice feature of meson is that it doesn't mix build artifacts\n(e.g. `*.o`, `*.so`, etc.) with source code. In the above example,\n\"`.build`\" is the name of the directory where the build configuration\nas well as all the build artifacts will be saved. This directory can\nbe named anything as long as it's not an existing source directory. To\ncompletely \"clean\" all the build artifacts, one need only delete the\n`.build` directory.\n\nTo compile:\n\n```\nmeson compile -C .build\n```\n\n## To install libnvme\n\nTo install `libnvme`:\n\n```\nmeson install -C .build\n```\n\n## To run unit tests\n\nTo run unit tests:\n\n```\nmeson test -C .build\n```\n\n## To purge everything\n\nTo completely clean all build artifacts, including the build configuration.\n\n```\nrm -rf .build\n```\n\n## Supported build options\n\nA few build options can be specified on the command line when invoking meson.\n\n| Option      | Values [default]          | Description                                                  |\n| ----------- | ------------------------- | ------------------------------------------------------------ |\n| version-tag | none                      | Overwrite the git version string in the binary               |\n| htmldir     | none                      | Installation directory for the HTML documentation            |\n| rstdir      | none                      | Installation directory for the RST documentation             |\n| docs        | [false], html, man, rst, all | Install documentation                                     |\n| docs-build  | [false], true             | Enable build documentation                                   |\n| python | [auto], enabled, disabled | Whether to build the Python bindings. When set to `auto`, the default, meson will check for the presence of the  tools and libraries (e.g. `swig`) required to build the Python bindings. If found, meson will configure the project to build the Python bindings. If a tool or library is missing, then the Python bindings won't be built. Setting this to `enabled`, forces the Python bindings to be built. When set to `disabled`, meson will configure the project to not build the Python bindings.<br />Example: `meson setup .build -Dpython=disabled` |\n| openssl     | [auto], enabled, disabled | Enables OpenSSL dependent features (e.g. TLS over TCP), adds build dependency on OpenSSL |\n| libdbus     | auto, enabled, [disabled] | Enables D-Bus dependent features (libnvme-mi: End point discovery), adds build dependency on libdbus |\n| json-c      | [auto], enabled, disabled | (recommended) Enables JSON-C dependend features (e.g. config.json parsing), adds build depdency on json-c |\n| keyutils    | [auto], enabled, disabled | Enables keyutils dependent features (e.g. authentication), adds build dependency on keyutils |\n\nSee the full configuration options with\n\n```bash\nmeson configure .build\n```\n\n### Changing the build options from the command-line (i.e. w/o modifying any files)\n\nTo configure a build for debugging purposes (i.e. optimization turned\noff and debug symbols enabled):\n\n```bash\nmeson setup .build --buildtype=debug\n```\n\nTo enable address sanitizer (advanced debugging of memory issues):\n\n```bash\nmeson setup .build -Db_sanitize=address\n```\n\nThis option adds `-fsanitize=address` to the gcc options. The tests can then be run normally (`meson test -C .build`).\n\nNote that when using the sanitize feature, the library `libasan.so` must be available and must be the very first library loaded when running an executable. If experiencing linking issues, you can ensure that `libasan.so` gets loaded first with the `LD_PRELOAD` environment variable as follows:\n\n```\nmeson setup .build -Db_sanitize=address && LD_PRELOAD=/lib64/libasan.so.6 ninja -C .build test\n```\n\nIt's also possible to enable the undefined behavior sanitizer with `-Db_sanitize=undefined`. To enable both, use `-Db_sanitize=address,undefined`.\n",
    "bugtrack_url": null,
    "license": "LGPL-2.1-or-later",
    "summary": "python bindings for libnvme",
    "version": "1.8",
    "project_urls": {
        "Homepage": "https://github.com/linux-nvme/libnvme"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "ed3ab034b3d5e62c6154f8159429ce94207e38b2ccbadd562bb995b67ebd9b88",
                "md5": "6a9c8798d7adb7f499a47e1710cef6a5",
                "sha256": "394c66f7599155b71479a4168a6ed46740f91cdebfc3ce94db5bd4852bd8b330"
            },
            "downloads": -1,
            "filename": "libnvme-1.8.tar.gz",
            "has_sig": false,
            "md5_digest": "6a9c8798d7adb7f499a47e1710cef6a5",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 646954,
            "upload_time": "2024-02-14T09:42:06",
            "upload_time_iso_8601": "2024-02-14T09:42:06.804097Z",
            "url": "https://files.pythonhosted.org/packages/ed/3a/b034b3d5e62c6154f8159429ce94207e38b2ccbadd562bb995b67ebd9b88/libnvme-1.8.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-02-14 09:42:06",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "linux-nvme",
    "github_project": "libnvme",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "libnvme"
}
        
Elapsed time: 0.19251s