1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178
|
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
<!ENTITY % local.common.attrib "xmlns:xi CDATA #FIXED 'http://www.w3.org/2003/XInclude'">
]>
<book id="index">
<bookinfo>
<title>libblockdev Reference Manual for libblockdev @VERSION@.</title>
<releaseinfo>
<para>
The latest version of this documentation can be found on-line at
<ulink role="online-location"
url="http://storaged.org/libblockdev/">http://storaged.org/libblockdev/</ulink>.
</para>
<para>
The latest version of the code can be found at
<ulink role="online-location"
url="https://github.com/storaged-project/libblockdev">https://github.com/storaged-project/libblockdev</ulink>
</para>
<para>
Documentation for Python bindings is available <ulink type="http" url="BlockDev-3.0/index.html">here</ulink>
</para>
</releaseinfo>
</bookinfo>
<chapter>
<title>libblockdev Reference Manual</title>
<xi:include href="xml/blockdev.xml"/>
<xi:include href="xml/btrfs.xml"/>
<xi:include href="xml/crypto.xml"/>
<xi:include href="xml/dm.xml"/>
<xi:include href="xml/fs.xml"/>
<xi:include href="xml/loop.xml"/>
<xi:include href="xml/lvm.xml"/>
<xi:include href="xml/mdraid.xml"/>
<xi:include href="xml/mpath.xml"/>
<xi:include href="xml/nvdimm.xml"/>
<xi:include href="xml/nvme.xml"/>
<xi:include href="xml/plugins.xml"/>
<xi:include href="xml/part.xml"/>
<xi:include href="xml/smart.xml"/>
<xi:include href="xml/swap.xml"/>
<xi:include href="xml/s390.xml"/>
<xi:include href="xml/utils.xml"/>
</chapter>
<chapter>
<title>GI Overrides</title>
<para>
The libblockdev library supports <emphasis>GObject introspection</emphasis> and thus
can be used from a variety of languages. To make such use even easier and to make
the code using libblockdev from different languages than C feel more natural the
library also provides so-called <emphasis>overrides</emphasis> — pieces of
code that usually wrap the original libblockdev functions with language-native
objects (usually functions) that provide language-specific features like default
values for parameters etc.
</para>
<para>
The overrides are not documented here (yet), but it should be easy to directly check
the sources for anybody who understands their language of choice. The overrides are
located in the <filename class="directory">src/LANG_NAME</filename> directory in the
source tree. The only language that libblockdev provides overrides for right now is
Python (under the <filename class="directory">src/python</filename> directory).
</para>
</chapter>
<chapter>
<title>Testing libblockdev</title>
<para>
libblockdev's test suite is written using the standard unittest.TestCase framework
in Python. Tests are separated in modules, usually one per libblockdev plugin - e.g.
BTRFS, LVM, Crypto. There are one or more base classes in each module used to
setup the environment and perform some testing. More specific test scenarios
inherit from these base classes.
</para>
<para>
Before running the tests you have to prepare your system so that libblockdev
can be built from source.
</para>
<para>
Install all build requirements. On Fedora this can be done with
<screen><userinput>
cat dist/libblockdev.spec.in | grep BuildRequires: | cut -f2 -d: | cut -f2 -d' ' | xargs dnf -y install
</userinput></screen>
Configure the build scripts
<screen><userinput>./autogen.sh
./configure</userinput></screen>
</para>
<para>
To execute the Pylint code analysis tool run:
<screen><userinput>make check</userinput></screen>
The check target is a dependency of all test targets and you don't have to
execute it explicitly when testing.
</para>
<para>
To execute the test suite from inside the source directory run one of these
commands:
<screen><userinput>make test</userinput></screen>
executes all safe tests or
<screen><userinput>make fast-test</userinput></screen>
executes all fast tests or
<screen><userinput>make test-all</userinput></screen>
executes all tests, including ones which may result in kernel panic or
take more time to complete or
<screen><userinput>make test-plugin-NAME</userinput></screen>
executes only tests for given plugin and similarly
<screen><userinput>make fast-test-plugin-NAME</userinput></screen>
executes only fast tests for given plugin.
</para>
<para>
It is also possible to run only subset of available tests or only one test
using the `run_tests.py` script:
<screen><userinput># python3 tests/run_tests.py fs_test.GenericResize</userinput></screen>
executes all tests from the <emphasis>GenericResize</emphasis> test class
from filesystem plugin test cases and
<screen><userinput># python3 tests/run_tests.py fs_test.GenericResize.test_ext2_generic_resize</userinput></screen>
executes only <emphasis>test_ext2_generic_resize</emphasis> from this class.
This script also allows skipping slow tests or running potentially dangerous
tests. Use:
<screen><userinput>$ python3 tests/run_tests.py --help</userinput></screen>
to see all available options.
</para>
<para>
It is also possible to generate test coverage reports using the Python coverage
tool:
<screen><userinput>make coverage</userinput></screen>
is equivalent to `make test'.
<screen><userinput>make coverage-all</userinput></screen>
is equivalent to `make test-all'.
</para>
</chapter>
<xi:include href="3.0-api-changes.xml"><xi:fallback /></xi:include>
<index id="api-index-full">
<title>API Index</title>
<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
</index>
<index id="deprecated-api-index" role="deprecated">
<title>Index of deprecated API</title>
<xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
</index>
<xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
</book>
|