Docs: add a README, explain high-level usage
This commit is contained in:
parent
e67b6b6a2b
commit
41b835ba46
|
@ -0,0 +1,72 @@
|
|||
# KPMcore
|
||||
|
||||
> KPMcore, the KDE Partition Manager core, is a library for examining
|
||||
> and modifying partitions, disk devices, and filesystems on a
|
||||
> Linux system. It provides a unified programming interface over
|
||||
> top of (external) system-manipulation tools.
|
||||
|
||||
KPMcore is a library for examining and manipulating all facets
|
||||
of storage devices on a system:
|
||||
* raw disk devices
|
||||
* partition tables on a device
|
||||
* filesystems within a partition
|
||||
|
||||
There are multiple backends so that KPMcore can support different
|
||||
operating systems, although the only functional backend is the
|
||||
one for Linux systems:
|
||||
* libparted backend (Linux)
|
||||
* null backend
|
||||
|
||||
## Using KPMcore
|
||||
|
||||
Most of the usage information on KPMcore is included in the API
|
||||
documentation; this section contains only high-level usage information.
|
||||
|
||||
### Finding KPMcore with CMake
|
||||
|
||||
KPMcore supports CMake as (meta-)build system and installs suitable
|
||||
CMake support files. Typical use of of KPMcore in a `CMakeLists.txt`
|
||||
looks like this:
|
||||
|
||||
```
|
||||
find_package( KPMcore 3.2 REQUIRED )
|
||||
include_directories( ${KPMCORE_INCLUDE_DIR} )
|
||||
target_link_libraries( target kpmcore )
|
||||
```
|
||||
|
||||
There are no imported targets defined for KPMcore.
|
||||
|
||||
### Initialization
|
||||
|
||||
An application must initialize the library and load a suitable
|
||||
backend before using KPMcore functions. By convention, the
|
||||
environment variable `KPMCORE_BACKEND` names a backend,
|
||||
and typical initialization code will look like this (or use the
|
||||
class `KPMCoreInitializer` from `test/helpers.h`):
|
||||
|
||||
```
|
||||
#include <kpmcore/backend/corebackendmanager.h>
|
||||
#include <QDebug>
|
||||
|
||||
bool initKPMcore()
|
||||
{
|
||||
static bool inited = false;
|
||||
if ( inited ) return true;
|
||||
|
||||
QByteArray env = qgetenv( "KPMCORE_BACKEND" );
|
||||
auto backendName = env.isEmpty() ? CoreBackendManager::defaultBackendName() : env;
|
||||
if ( !CoreBackendManager::self()->load( backendName )
|
||||
{
|
||||
qWarning() << "Failed to load backend plugin" << backendName;
|
||||
return false;
|
||||
}
|
||||
inited = true;
|
||||
return true;
|
||||
}
|
||||
```
|
||||
|
||||
This code uses the environment variable if set, and otherwise falls
|
||||
back to a default backend suitable for the current platform.
|
||||
|
||||
Calling KPMcore functions before the library is initialized will
|
||||
result in undefined behavior.
|
Loading…
Reference in New Issue