README.md
1<!-- SPDX-FileCopyrightText: 2017 Adriaan de Groot <groot@kde.org>
2 SPDX-FileCopyrightText: 2017-2020 Andrius Štikonas <andrius@stikonas.eu>
3 SPDX-License-Identifier: CC-BY-4.0
4-->
5
6# KPMcore
7
8> KPMcore, the KDE Partition Manager core, is a library for examining
9> and modifying partitions, disk devices, and filesystems on a
10> Linux system. It provides a unified programming interface over
11> top of (external) system-manipulation tools.
12
13KPMcore is a library for examining and manipulating all facets
14of storage devices on a system:
15* raw disk devices
16* partition tables on a device
17* filesystems within a partition
18
19There are multiple backends so that KPMcore can support different
20operating systems, although the only functional backend is the
21one for Linux systems:
22* sfdisk backend (Linux)
23* null backend
24
25## Using KPMcore
26
27Most of the usage information on KPMcore is included in the API
28documentation; this section contains only high-level usage information.
29
30### Finding KPMcore with CMake
31
32KPMcore supports CMake as (meta-)build system and installs suitable
33CMake support files. Typical use of of KPMcore in a `CMakeLists.txt`
34looks like this:
35
36```cmake
37 find_package( KPMcore 3.2 REQUIRED )
38 include_directories( ${KPMCORE_INCLUDE_DIR} )
39 target_link_libraries( target kpmcore )
40```
41
42There are no imported targets defined for KPMcore.
43
44### Initialization
45
46An application must initialize the library and load a suitable
47backend before using KPMcore functions. By convention, the
48environment variable `KPMCORE_BACKEND` names a backend,
49and typical initialization code will look like this (or use the
50class `KPMCoreInitializer` from `test/helpers.h`):
51
52```cpp
53 #include <backend/corebackendmanager.h>
54 #include <QDebug>
55
56 bool initKPMcore()
57 {
58 static bool inited = false;
59 if ( inited ) return true;
60
61 QByteArray env = qgetenv( "KPMCORE_BACKEND" );
62 auto backendName = env.isEmpty() ? CoreBackendManager::defaultBackendName() : env;
63 if ( !CoreBackendManager::self()->load( backendName ) )
64 {
65 qWarning() << "Failed to load backend plugin" << backendName;
66 return false;
67 }
68 inited = true;
69 return true;
70 }
71```
72
73This code uses the environment variable if set, and otherwise falls
74back to a default backend suitable for the current platform.
75
76Calling KPMcore functions before the library is initialized will
77result in undefined behavior.
78
79### Devices
80
81After the backend is initialized you can scan for available devices.
82If you only want devices from the loaded backend you can call
83
84```cpp
85 QList<Device*> devices = backend->scanDevices( excludeReadOnly );
86```
87
88where `bool` option `excludeReadOnly` specifies whether to exclude
89read only devices.
90
91#### KPMcore device scanner
92
93Alternatively, you can use KPMcore device scanner
94
95```cpp
96 #include <core/device.h>
97 #include <core/devicescanner.h>
98 #include <core/operationstack.h>
99
100 // First create operationStack with another QObject as parent, we will use nullptr here.
101 OperationStack *operationStack = new OperationStack(nullptr);
102 DeviceScanner *deviceScanner = new DeviceScanner(nullptr, *operationStack);
103 deviceScanner->scan(); // use start() for scanning in the background thread
104 QList<Device*> devices = operationStack->previewDevices();
105```
106
107Then `deviceScanner` scans for the devices in a background thread. After
108scanning is complete `DeviceScanner::finished()` signal will be emitted.
109Then the devices can accessed using `operationStack->previewDevices()`.
110