source: postlfs/filesystems/btrfs-progs.xml@ d0a57b06

trunk
Last change on this file since d0a57b06 was 8674204, checked in by Douglas R. Reno <renodr@…>, 2 months ago

btrfs-progs: Add a dependency on sphinx_rtd_theme.

Without this, the build will fail if sphinx is installed:

[SPHINX] man

Extension error:
Could not import extension sphinx_rtd_theme (exception: No module named 'sphinx_rtd_theme')
  • Property mode set to 100644
File size: 12.4 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
4 <!ENTITY % general-entities SYSTEM "../../general.ent">
5 %general-entities;
6
7 <!ENTITY btrfs-progs-download-http "&kernel-dl;/linux/kernel/people/kdave/btrfs-progs/btrfs-progs-v&btrfs-progs-version;.tar.xz">
8 <!ENTITY btrfs-progs-download-ftp " ">
9 <!ENTITY btrfs-progs-md5sum "3898c68efdc0fe4e3a6a1bd90b3b4fa4">
10 <!ENTITY btrfs-progs-size "2.4 MB">
11 <!ENTITY btrfs-progs-buildsize "62 MB (transient files created during tests need up to 10 GB)">
12 <!ENTITY btrfs-progs-time "0.3 SBU (with parallelism=4; add 4.6 SBU for tests, up to 14 SBU on slow disks)">
13 <!-- tests run with reiserfs disabled in kernel -->
14]>
15
16<sect1 id="btrfs-progs" xreflabel="btrfs-progs-&btrfs-progs-version;">
17 <?dbhtml filename="btrfs-progs.html"?>
18
19
20 <title>btrfs-progs-&btrfs-progs-version;</title>
21
22 <indexterm zone="btrfs-progs">
23 <primary sortas="a-btrfs-progs">btrfs-progs</primary>
24 </indexterm>
25
26 <sect2 role="package">
27 <title>Introduction to btrfs-progs</title>
28
29 <para>
30 The <application>btrfs-progs</application> package contains
31 administration and debugging tools for the B-tree file system (btrfs).
32 </para>
33
34 &lfs121_checked;
35
36 <bridgehead renderas="sect3">Package Information</bridgehead>
37 <itemizedlist spacing="compact">
38 <listitem>
39 <para>
40 Download (HTTP): <ulink url="&btrfs-progs-download-http;"/>
41 </para>
42 </listitem>
43 <listitem>
44 <para>
45 Download (FTP): <ulink url="&btrfs-progs-download-ftp;"/>
46 </para>
47 </listitem>
48 <listitem>
49 <para>
50 Download MD5 sum: &btrfs-progs-md5sum;
51 </para>
52 </listitem>
53 <listitem>
54 <para>
55 Download size: &btrfs-progs-size;
56 </para>
57 </listitem>
58 <listitem>
59 <para>
60 Estimated disk space required: &btrfs-progs-buildsize;
61 </para>
62 </listitem>
63 <listitem>
64 <para>
65 Estimated build time: &btrfs-progs-time;
66 </para>
67 </listitem>
68 </itemizedlist>
69<!--
70<bridgehead renderas="sect3">Additional Downloads</bridgehead>
71 <itemizedlist spacing="compact">
72 <listitem>
73 <para>
74 Required patch if building with linux kernel headers version
75 before 5.12:
76 <ulink url="&patch-root;/btrfs-progs-&btrfs-progs-version;-headers_fix-1.patch"/>
77 </para>
78 </listitem>
79 </itemizedlist>
80-->
81 <bridgehead renderas="sect3">Btrfs-progs Dependencies</bridgehead>
82
83 <bridgehead renderas="sect4">Required</bridgehead>
84 <para role="required">
85 <xref linkend="lzo"/>
86 </para>
87 <!-- In v6.2.1 (and maybe previous), sphinx is required for the doc
88 <bridgehead renderas="sect4">Recommended</bridgehead>
89 <para role="recommended">
90 <xref linkend="asciidoc"/> (or <xref role="nodep" linkend="asciidoctor"/>)
91 and <xref linkend="xmlto"/> (both required to generate man pages)
92 </para>
93 -->
94 <bridgehead renderas="sect4">Optional</bridgehead>
95 <para role="optional">
96 <xref linkend="lvm2"/> (<command>dmsetup</command> is used in tests),
97 <xref linkend="sphinx"/> and <xref linkend="sphinx_rtd_theme"/>
98 (required to build documentation), and
99 <ulink
100 url='https://mirrors.edge.kernel.org/pub/linux/kernel/people/jeffm/reiserfsprogs/'>
101 reiserfsprogs</ulink> (for tests).
102
103 </para>
104
105
106 </sect2>
107
108 <sect2 role="kernel" id="btrfs-progs-kernel">
109 <title>Kernel Configuration</title>
110
111 <para>
112 Enable the following option in the kernel configuration
113 and recompile the kernel:
114 </para>
115
116 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
117 href="btrfs-progs-kernel.xml"/>
118
119 <para>
120 In addition to the above and to the options required for
121 <xref linkend="lvm2"/>, the following
122 options must be enabled for running tests:
123 </para>
124
125 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
126 href="btrfs-progs-test-kernel.xml"/>
127
128 <indexterm zone="btrfs-progs btrfs-progs-kernel">
129 <primary sortas="d-btrfs-progs">BTRFS Programs</primary>
130 </indexterm>
131
132 </sect2>
133
134 <sect2 role="installation">
135 <title>Installation of btrfs-progs</title>
136
137 <para>
138 Install <application>btrfs-progs</application> by running the following
139 commands:
140 </para>
141
142<screen><userinput>./configure --prefix=/usr \
143 --disable-static \
144 --disable-documentation &amp;&amp;
145make</userinput></screen>
146
147 <note>
148 <para>
149 Some tests require grep built with perl regular expressions. To
150 obtain this, rebuild grep with the LFS Chapter 8 instructions after
151 installing <xref linkend="pcre2"/>.
152 </para>
153 </note>
154<!-- Keeping this for now, but it seems that calling "make test" is
155 simpler and does the same thing -->
156 <para>
157 Before running tests, build a support program:
158 </para>
159
160<screen remap="test"><userinput>make fssum</userinput></screen>
161
162 <para>
163 To test the results, issue (as the &root; user):
164 </para>
165
166<screen role="root" remap="test"><userinput>pushd tests
167 ./fsck-tests.sh
168 ./mkfs-tests.sh
169 ./cli-tests.sh
170 ./convert-tests.sh
171 ./misc-tests.sh
172 ./fuzz-tests.sh
173popd</userinput></screen>
174
175<!-- Template for failed test removal:
176 <para>
177 To test the results, first disable one test that fails and prevents
178 the other ones to run:
179 </para>
180
181<screen remap="test"><userinput>mv tests/fsck-tests/012-leaf-corruption/test.sh{,.broken}</userinput></screen>
182Substitute your test failure with the one above.
183 <para>
184 To test the results, run (as the
185 <systemitem class="username">root</systemitem> user):
186 </para>
187
188<screen role="root" remap="test"><userinput>make -j1 -k test</userinput></screen>
189-->
190 <note>
191 <para>
192 If the above mentioned kernel options are not enabled, some tests
193 fail, and prevent all the remaining tests from running because the test
194 disk image is not cleanly unmounted.
195 </para>
196 </note>
197<!-- Now passes in version 6.3.1.
198 <para>
199 The mkfs test 025-zoned-parallel is known to fail.
200 </para>
201-->
202 <para>
203 Install the package as the &root; user:
204 </para>
205
206<screen role="root"><userinput>make install</userinput></screen>
207
208 <para>
209 If you have passed <parameter>--disable-documentation</parameter> to
210 <command>configure</command> and you need the manual pages, install them
211 by running, as the &root; user:
212 </para>
213
214<screen role="root"><userinput>for i in 5 8; do
215 install Documentation/*.$i /usr/share/man/man$i
216done</userinput></screen>
217
218 </sect2>
219
220 <sect2 role="commands">
221 <title>Command Explanations</title>
222
223 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
224 href="../../xincludes/static-libraries.xml"/>
225
226 <para>
227 <parameter>--disable-documentation</parameter>: This switch
228 disables rebuilding the manual pages, because it requires
229 <xref linkend="sphinx"/>.
230 </para>
231<!--
232 <para>
233 <command>sed 's/,orphan_file//" ...</command>: In this version of
234 <application>btrfs-progs</application>, the
235 <command>btrfs-convert</command> program produces a btrfs filesystem
236 containing errors if converting from an ext4 filesystem created
237 with the <quote>orphan_file</quote> feature. This command creates
238 a custom configuration file that prevents creating a filesystem
239 with this feature.
240 </para>
241-->
242 <!--
243 <para>
244 <command>ln -s ... /usr/lib/libbtrfs.so</command>: Creates a
245 symbolic link in the directory where it is expected.
246 </para>
247
248 <para>
249 <command>rm /lib/libbtrfs.{a,so}</command>: Removes unneeded
250 library entries.
251 </para>
252-->
253 </sect2>
254<!--
255 <sect2 role="using" id="using-btrfs-convert">
256 <title>Using the btrfs-convert Program</title>
257
258 <para>
259 This version of <application>btrfs-progs</application> does not convert
260 correctly ext4 filesystems to btrfs if the ext4
261 <option>orphan_file</option> feature is turned on. If you happen to
262 convert such a filesystem, you need to first run:
263 </para>
264
265<screen role="nodump"><userinput>tune2fs -O ^orphan_file <replaceable>/dev/sdxx</replaceable></userinput></screen>
266
267 <para>
268 where <filename>/dev/sdxx</filename> is the partition of the filesystem
269 you want to convert.
270 </para>
271 </sect2>
272-->
273
274 <sect2 role="content">
275 <title>Contents</title>
276
277 <segmentedlist>
278 <segtitle>Installed Programs</segtitle>
279 <segtitle>Installed Libraries</segtitle>
280 <segtitle>Installed Directories</segtitle>
281
282 <seglistitem>
283 <seg>
284 btrfs,
285 btrfs-convert,
286 btrfs-find-root,
287 btrfs-image,
288 btrfs-map-logical,
289 btrfs-select-super,
290 btrfsck (link to btrfs),
291 btrfstune,
292 fsck.btrfs, and
293 mkfs.btrfs
294 </seg>
295
296 <seg>
297 libbtrfs.so and
298 libbtrfsutil.so
299 </seg>
300
301 <seg>/usr/include/btrfs</seg>
302 </seglistitem>
303 </segmentedlist>
304
305 <variablelist>
306 <bridgehead renderas="sect3">Short Descriptions</bridgehead>
307 <?dbfo list-presentation="list"?>
308 <?dbhtml list-presentation="table"?>
309
310 <varlistentry id="btrfs-prog">
311 <term><command>btrfs</command></term>
312 <listitem>
313 <para>
314 is the main interface into btrfs filesystem operations
315 </para>
316 <indexterm zone="btrfs-progs btrfs-prog">
317 <primary sortas="b-btrfs">btrfs</primary>
318 </indexterm>
319 </listitem>
320 </varlistentry>
321
322 <varlistentry id="btrfs-convert">
323 <term><command>btrfs-convert</command></term>
324 <listitem>
325 <para>
326 converts from an ext2/3/4 or reiserfs filesystem to btrfs <!--(see
327 <xref linkend="using-btrfs-convert"/> above)-->
328 </para>
329 <indexterm zone="btrfs-progs btrfs-convert">
330 <primary sortas="b-btrfs-convert">btrfs-convert</primary>
331 </indexterm>
332 </listitem>
333 </varlistentry>
334
335 <varlistentry id="btrfs-find-root">
336 <term><command>btrfs-find-root</command></term>
337 <listitem>
338 <para>
339 is a filter to find btrfs root
340 </para>
341 <indexterm zone="btrfs-progs btrfs-find-root">
342 <primary sortas="b-btrfs-find-root">btrfs-find-root</primary>
343 </indexterm>
344 </listitem>
345 </varlistentry>
346
347 <varlistentry id="btrfs-map-logical">
348 <term><command>btrfs-map-logical</command></term>
349 <listitem>
350 <para>
351 maps btrfs logical extent to physical extent
352 </para>
353 <indexterm zone="btrfs-progs btrfs-map-logical">
354 <primary sortas="b-btrfs-map-logical">btrfs-map-logical</primary>
355 </indexterm>
356 </listitem>
357 </varlistentry>
358
359 <varlistentry id="btrfs-select-super">
360 <term><command>btrfs-select-super</command></term>
361 <listitem>
362 <para>
363 overwrites the primary superblock with a backup copy
364 </para>
365 <indexterm zone="btrfs-progs btrfs-select-super">
366 <primary sortas="b-btrfs-select-super">btrfs-select-super</primary>
367 </indexterm>
368 </listitem>
369 </varlistentry>
370
371 <varlistentry id="btrfstune">
372 <term><command>btrfstune</command></term>
373 <listitem>
374 <para>
375 tunes various filesystem parameters
376 </para>
377 <indexterm zone="btrfs-progs btrfstune">
378 <primary sortas="b-btrfstune">btrfstune</primary>
379 </indexterm>
380 </listitem>
381 </varlistentry>
382
383 <varlistentry id="fsck.btrfs">
384 <term><command>fsck.btrfs</command></term>
385 <listitem>
386 <para>
387 does nothing, but is present for consistency with fstab
388 </para>
389 <indexterm zone="btrfs-progs fsck.btrfs">
390 <primary sortas="b-fsck.btrfs">fsck.btrfs</primary>
391 </indexterm>
392 </listitem>
393 </varlistentry>
394
395 <varlistentry id="mkfs.btrfs">
396 <term><command>mkfs.btrfs</command></term>
397 <listitem>
398 <para>
399 creates a btrfs file system
400 </para>
401 <indexterm zone="btrfs-progs mkfs.btrfs">
402 <primary sortas="b-mkfs.btrfs">mkfs.btrfs</primary>
403 </indexterm>
404 </listitem>
405 </varlistentry>
406
407 </variablelist>
408
409 </sect2>
410
411</sect1>
Note: See TracBrowser for help on using the repository browser.