Skip to content

doc: fix typos and grammar issues in README.md #3239

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
igaw merged 1 commit into from
Apr 7, 2026
+38 −36
Merged

doc: fix typos and grammar issues in README.md #3239

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 38 additions & 36 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,18 +23,21 @@ libnvme:
nvme-cli uses meson as its build system. There is more than one way to configure and
build the project in order to mitigate meson dependency on the build environment.

If you build on a relative modern system, either use meson directly or the
If you build on a relatively modern system, either use meson directly or the
Makefile wrapper.

Older distros might ship a too old version of meson, in this case it's possible
Older distros might ship a too old version of meson. In this case, it's possible
to build the project using [samurai](https://github.com/michaelforney/samurai)
and [muon](https://github.com/annacrombie/muon). Both build tools have only a
minimal dependency on the build environment. Too easy this step there is a build
minimal dependency on the build environment. To ease this step, there is a build
script which helps to setup a build environment.

### nvme-cli dependencies (3.x and later):

Starting with nvme-cli 3.x, the libnvme library is fully integrated into the nvme-cli source tree. There is no longer any dependency on an external libnvme repository or package. All required libnvme and libnvme-mi code is included and built as part of nvme-cli.
Starting with nvme-cli 3.x, the libnvme library is fully integrated into the
nvme-cli source tree. There is no longer any dependency on an external libnvme
repository or package. All required libnvme and libnvme-mi code is included and
built as part of nvme-cli.

| Library | Dependency | Notes |
|---------|------------|-------|
Expand All @@ -46,8 +49,6 @@ Starting with nvme-cli 3.x, the libnvme library is fully integrated into the nvm

#### Configuring

#### Configuring

No special configuration is required for libnvme, as it is now part of the
nvme-cli source tree. Simply run:

Expand Down Expand Up @@ -78,16 +79,16 @@ default configuration (meson, gcc and defaults)

It's possible to change the compiler to clang

`scripts/builds.sh -c clang`
`scripts/build.sh -c clang`

or enabling all the fallbacks
or enable all the fallbacks

`scripts/build.sh fallback`

### Minimal static build with muon

`scripts/build.sh -m muon` will download and build `samurai` and `muon` instead
using `meson` to build the project. This reduces the dependency on the build
of using `meson` to build the project. This reduces the dependency on the build
environment to:
- gcc
- make
Expand All @@ -109,11 +110,11 @@ RPM build support via Makefile that uses meson

$ make rpm

Static binary(no dependency) build support via Makefile that uses meson
Static binary (no dependency) build support via Makefile that uses meson

$ make static

If not sure how to use, find the top-level documentation with:
If you are not sure how to use it, find the top-level documentation with:

$ man nvme

Expand Down Expand Up @@ -142,17 +143,18 @@ To build without any vendor plugins:

## Distro Support

Many popular distributions (Alpine, Arch, Debian, Fedora, FreeBSD, Gentoo,
Ubuntu, Nix(OS), openSUSE, ...) and the usual package name is nvme-cli.
It is available on many popular distributions (Alpine, Arch, Debian, Fedora,
FreeBSD, Gentoo, Ubuntu, Nix(OS), openSUSE, ...) and the usual package name is
nvme-cli.

#### OpenEmbedded/Yocto

An [nvme-cli recipe](https://layers.openembedded.org/layerindex/recipe/88631/)
is available as part of the `meta-openembeded` layer collection.
is available as part of the `meta-openembedded` layer collection.

#### Buildroot

`nvme-cli` is available as [buildroot](https://buildroot.org) package. The
`nvme-cli` is available as a [buildroot](https://buildroot.org) package. The
package is named `nvme`.

## Developers
Expand All @@ -168,11 +170,12 @@ events are created by Linux kernel's 'ftrace' component.

The first thing to do is define a new command entry in the command
list. This is declared in nvme-builtin.h. Simply append a new "ENTRY" into
the list. The ENTRY normally takes three arguments: the "name" of the
the list. The ENTRY normally takes three arguments: the "name" of the
subcommand (this is what the user will type at the command line to invoke
your command), a short help description of what your command does, and the
name of the function callback that you're going to write. Additionally,
You can declare an alias name of subcommand with fourth argument, if needed.
you can declare an alias name of the subcommand with a fourth argument, if
needed.

After the ENTRY is defined, you need to implement the callback. It takes
four arguments: argc, argv, the command structure associated with the
Expand All @@ -188,11 +191,11 @@ after the sub-command. So if the command line is "nvme foo --option=bar",
the argc is 1 and argv starts at "--option".

You can then define argument parsing for your sub-command's specific
options then do some command specific action in your callback.
options then do some command-specific action in your callback.

### Add a new plugin

The nvme-cli provides macros to make define a new plug-in simpler. You
The nvme-cli provides macros to make defining a new plug-in simpler. You
can certainly do all this by hand if you want, but it should be easier
to get going using the macros. To start, first create a header file
to define your plugin. This is where you will give your plugin a name,
Expand Down Expand Up @@ -226,7 +229,7 @@ PLUGIN(NAME("foo", "Foo plugin"),

In order to have the compiler generate the plugin through the xmacro
expansion, you need to include this header in your source file, with
pre-defining macro directive to create the commands.
a pre-defining macro directive to create the commands.

To get started from the above example, we just need to define "CREATE_CMD"
and include the header:
Expand Down Expand Up @@ -333,33 +336,32 @@ drifts silently.
## Dependency

libnvme depends on the /sys/class/nvme-subsystem interface which was
introduced in the Linux kernel release v4.15. Hence nvme-cli 2.x is
only working on kernels >= v4.15. For older kernels nvme-cli 1.x is
recommended to be used.
introduced in the Linux kernel release v4.15. Hence nvme-cli 2.x only works on
kernels >= v4.15. For older kernels nvme-cli 1.x is recommended to be used.

## How to contribute

There are two ways to send code changes to the project. The first one
is by sending the changes to linux-nvme@lists.infradead.org. The
second one is by posting a pull request on github. In both cases
second one is by posting a pull request on Github. In both cases
please follow the Linux contributions guidelines as documented in

https://docs.kernel.org/process/submitting-patches.html#

That means the changes should be a clean series (no merges should be
present in a github PR for example) and every commit should build.
present in a Github PR for example) and every commit should build.

See also https://opensource.com/article/19/7/create-pull-request-github

### How to cleanup your series before creating PR
### How to clean up your series before creating a PR

This example here assumes, the changes are in a branch called
This example here assumes the changes are in a branch called
fix-something, which branched away from master in the past. In the
meantime the upstream project has changed, hence the fix-something
branch is not based on the current HEAD. Before posting the PR, the
branch should be rebased on the current HEAD and retest everything.

For example rebasing can be done by following steps
For example, rebasing can be done by the following steps

```shell
# Update master branch
Expand All @@ -380,7 +382,7 @@ $ git rebase master
[fixup all merge conflicts]
[retest]

# Push your changes to github and trigger a PR
# Push your changes to Github and trigger a PR
$ git push -u origin fix-something
```

Expand All @@ -391,7 +393,7 @@ the file `/etc/nvme/discovery.conf` using the old style, or in the file
`/etc/nvme/config.json` using the new style.

On the other hand, volatile configurations, such as those obtained from
third-party tools like `nvme-stats` or `blktests'` can be stored in the
third-party tools like `nvme-stats` or `blktests`, can be stored in the
`/run/nvme` directory. When using the `nvme-cli` tool, all these configurations
are combined into a single configuration that is used as input.

Expand All @@ -403,7 +405,7 @@ file in `/run/nvme` to inform `nvme-cli` that it should not perform any actions
triggered from the udev context. This behavior can be controlled using the
`--context` argument.

For example a `blktests` volatile configuration could look like:
For example, a `blktests` volatile configuration could look like:

```json
[
Expand All @@ -427,16 +429,16 @@ For example a `blktests` volatile configuration could look like:
]
```

Note when updating the volatile configuration during runtime, it should done in
a an atomic way. For example create a temporary file without the `.json` file
extension in `/run/nvme` and write the contents to this file. When finished use
Note when updating the volatile configuration during runtime, it should be done
in an atomic way. For example, create a temporary file without the `.json` file
extension in `/run/nvme` and write the contents to this file. When finished, use
`rename` to add the `'.json'` file name extension. This ensures nvme-cli only
sees the complete file.

## Testing

For testing purposes a x86_64 static build from the current HEAD and is
available here:
For testing purposes, an x86_64 static build from the current HEAD is available
here:

https://monom.org/linux-nvme/upload/nvme-cli-latest-x86_64

Expand Down
Loading