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>
|
