231 lines
5.8 KiB
Diff
231 lines
5.8 KiB
Diff
From 730f8388467426bfd061151205d93391c942b86a Mon Sep 17 00:00:00 2001
|
||
From: "Richard W.M. Jones" <rjones@redhat.com>
|
||
Date: Sun, 15 Jul 2018 17:26:59 +0100
|
||
Subject: [PATCH 11/12] Rework README file.
|
||
|
||
---
|
||
README | 119 +++++++++++++++++++++++++++++++--------------------------
|
||
1 file changed, 65 insertions(+), 54 deletions(-)
|
||
|
||
diff --git a/README b/README
|
||
index 685b41f..5114b31 100644
|
||
--- a/README
|
||
+++ b/README
|
||
@@ -1,7 +1,7 @@
|
||
-NBD is a protocol for accessing Block Devices (hard disks and
|
||
-disk-like things) over a Network.
|
||
+NBD — Network Block Device — is a protocol for accessing Block Devices
|
||
+(hard disks and disk-like things) over a Network.
|
||
|
||
-'nbdkit' is a toolkit for creating NBD servers.
|
||
+nbdkit is a toolkit for creating NBD servers.
|
||
|
||
The key features are:
|
||
|
||
@@ -13,24 +13,39 @@ The key features are:
|
||
libraries or included in proprietary code.
|
||
|
||
* Well-documented, simple plugin API with a stable ABI guarantee.
|
||
- Lets you export "unconventional" block devices easily.
|
||
+ Lets you export “unconventional” block devices easily.
|
||
|
||
* You can write plugins in C, Lua, Perl, Python, OCaml, Ruby or Tcl.
|
||
|
||
-For documentation, see the docs/ directory.
|
||
+ * Filters can be stacked in front of plugins to transform the output.
|
||
|
||
-For plugins and examples, see the plugins/ directory.
|
||
+For documentation, see the ‘docs/’ directory.
|
||
|
||
-License
|
||
--------
|
||
+For plugins, examples and filters, see the ‘plugins/’ and ‘filters/’
|
||
+directories.
|
||
+
|
||
+LICENSE
|
||
+=======
|
||
|
||
This software is copyright (C) Red Hat Inc. and licensed under a BSD
|
||
-license. See LICENSE for details.
|
||
+license. See ‘LICENSE’ for details.
|
||
|
||
-Building from source
|
||
---------------------
|
||
+BUILDING FROM SOURCE
|
||
+====================
|
||
|
||
-By default nbdkit needs nothing except Linux and reasonably recent gcc.
|
||
+Requirements
|
||
+------------
|
||
+
|
||
+To build the basic server and some plugins nbdkit needs nothing except
|
||
+Linux and reasonably recent gcc.
|
||
+
|
||
+Although it is possible to build without it, it’s recommended to
|
||
+enable TLS support for which you will need:
|
||
+
|
||
+ - gnutls >= 3.3.0
|
||
+
|
||
+Optional dependencies
|
||
+---------------------
|
||
|
||
To build the man pages, you will optionally need to install:
|
||
|
||
@@ -38,13 +53,6 @@ To build the man pages, you will optionally need to install:
|
||
|
||
- Pod::Man and Pod::Simple (perl library)
|
||
|
||
-There are some *optional* libraries you may want to install for
|
||
-plugins or extra features.
|
||
-
|
||
-For TLS support:
|
||
-
|
||
- - gnutls >= 3.3.0
|
||
-
|
||
For the gzip plugin:
|
||
|
||
- zlib
|
||
@@ -79,19 +87,22 @@ For the VDDK plugin:
|
||
|
||
For the Perl, example4 and tar plugins:
|
||
|
||
+ - perl interpreter
|
||
+
|
||
- perl development libraries
|
||
|
||
- perl module ExtUtils::Embed
|
||
|
||
For the Python plugin:
|
||
|
||
- - python development libraries
|
||
+ - python interpreter
|
||
(either version 2 or 3 may be used)
|
||
|
||
+ - python development libraries
|
||
+
|
||
For the OCaml plugin:
|
||
|
||
- - OCaml >= 4.02.2 which has support for shared libraries, see:
|
||
- http://caml.inria.fr/mantis/view.php?id=6693
|
||
+ - OCaml >= 4.02.2
|
||
|
||
For the Tcl plugin:
|
||
|
||
@@ -109,81 +120,81 @@ To run the test suite:
|
||
|
||
- bash
|
||
|
||
-To test for memory leaks ('make check-valgrind'):
|
||
+To test for memory leaks (‘make check-valgrind’):
|
||
|
||
- valgrind program and development headers
|
||
|
||
For non-essential enhancements to the test suite:
|
||
|
||
+ - qemu-io (usually shipped with qemu)
|
||
+
|
||
- socat
|
||
|
||
- ss (from iproute package)
|
||
|
||
-After installing any dependencies:
|
||
+Building
|
||
+--------
|
||
|
||
- To build from tarball: To build from git:
|
||
- ---------------------- ------------------
|
||
- autoreconf -i
|
||
- ./configure ./configure
|
||
- make make
|
||
- make check make check
|
||
+ To build from tarball: To build from git:
|
||
+ ---------------------- ------------------
|
||
+ autoreconf -i
|
||
+ ./configure ./configure
|
||
+ make make
|
||
+ make check make check
|
||
|
||
To run nbdkit from the source directory, use the top level ./nbdkit
|
||
script. It will run nbdkit and plugins from the locally compiled
|
||
directory:
|
||
|
||
- $ ./nbdkit example1 -f -v
|
||
- ./src/nbdkit ./plugins/example1/.libs/nbdkit-example1-plugin.so -f -v
|
||
- [etc]
|
||
+ $ ./nbdkit example1 -f -v
|
||
+ ./src/nbdkit ./plugins/example1/.libs/nbdkit-example1-plugin.so -f -v
|
||
+ [etc]
|
||
|
||
Optionally run this command as root to install everything:
|
||
|
||
- make install
|
||
+ make install
|
||
|
||
Python
|
||
------
|
||
|
||
By default nbdkit uses the Python version of the Python interpreter
|
||
-called "python" on the current $PATH. To use another version of
|
||
+called “python” on the current $PATH. To use another version of
|
||
Python you may need to set the PYTHON variable when configuring. For
|
||
example:
|
||
|
||
- ./configure PYTHON=/usr/bin/python3
|
||
+ ./configure PYTHON=/usr/bin/python3
|
||
|
||
-Tests
|
||
------
|
||
+Running the tests
|
||
+-----------------
|
||
|
||
You will need to install libguestfs to run most of the test suite:
|
||
|
||
- make check
|
||
+ make check
|
||
|
||
The test suite is fairly comprehensive. It runs the newly built
|
||
nbdkit + plugins as a captive process, and tests them using
|
||
libguestfs. If there is a failure, look at the corresponding
|
||
-tests/*.log file for debug information.
|
||
+‘tests/*.log’ file for debug information.
|
||
|
||
-Developers
|
||
-----------
|
||
+DOWNLOAD TARBALLS
|
||
+=================
|
||
+
|
||
+Tarballs are available from:
|
||
+http://libguestfs.org/download/nbdkit
|
||
+
|
||
+DEVELOPERS
|
||
+==========
|
||
|
||
Install the valgrind program and development headers.
|
||
|
||
Use:
|
||
|
||
- ./configure --enable-gcc-warnings --enable-valgrind
|
||
+ ./configure --enable-gcc-warnings --enable-valgrind
|
||
|
||
When testing use:
|
||
|
||
- make check
|
||
- make check-valgrind
|
||
-
|
||
-Packager information
|
||
---------------------
|
||
-
|
||
-Tarballs are available from:
|
||
-http://libguestfs.org/download/nbdkit
|
||
-
|
||
-Developer information
|
||
----------------------
|
||
+ make check
|
||
+ make check-valgrind
|
||
|
||
For development ideas, see the TODO file.
|
||
|
||
--
|
||
2.17.1
|
||
|