mirror of
https://github.com/kdave/btrfs-progs
synced 2024-12-27 00:22:22 +00:00
23c01b3c1b
The C libbtrfsutil library isn't very useful for scripting, so we also want bindings for Python. Writing unit tests in Python is also much easier than doing so in C. Only Python 3 is supported; if someone really wants Python 2 support, they can write their own bindings. This commit is just the scaffolding. Signed-off-by: Omar Sandoval <osandov@fb.com> Signed-off-by: David Sterba <dsterba@suse.com>
39 lines
1.7 KiB
Markdown
39 lines
1.7 KiB
Markdown
libbtrfsutil
|
|
============
|
|
|
|
libbtrfsutil is a library for managing Btrfs filesystems. It is licensed under
|
|
the LGPL. libbtrfsutil provides interfaces for a subset of the operations
|
|
offered by the `btrfs` command line utility. It also includes official Python
|
|
bindings (Python 3 only).
|
|
|
|
Development
|
|
-----------
|
|
|
|
The [development process for btrfs-progs](../README.md#development) applies.
|
|
|
|
libbtrfsutil only includes operations that are done through the filesystem and
|
|
ioctl interface, not operations that modify the filesystem directly (e.g., mkfs
|
|
or fsck). This is by design but also a legal necessity, as the filesystem
|
|
implementation is GPL but libbtrfsutil is LGPL. That is also why the
|
|
libbtrfsutil code is a reimplementation of the btrfs-progs code rather than a
|
|
refactoring. Be wary of this when porting functionality.
|
|
|
|
libbtrfsutil is semantically versioned separately from btrfs-progs. It is the
|
|
maintainers' responsibility to bump the version as needed (at most once per
|
|
release of btrfs-progs).
|
|
|
|
A few guidelines:
|
|
|
|
* All interfaces must be documented in `btrfsutil.h` using the kernel-doc style
|
|
* Error codes should be specific about what _exactly_ failed
|
|
* Functions should have a path and an fd variant whenever possible
|
|
* Spell out terms in function names, etc. rather than abbreviating whenever
|
|
possible
|
|
* Don't require the Btrfs UAPI headers for any interfaces (e.g., instead of
|
|
directly exposing a type from `linux/btrfs_tree.h`, abstract it away in a
|
|
type specific to `libbtrfsutil`)
|
|
* Preserve API and ABI compatability at all times (i.e., we don't want to bump
|
|
the library major version if we don't have to)
|
|
* Include Python bindings for all interfaces
|
|
* Write tests for all interfaces
|