libbtrfsutil/README.md

   1 libbtrfsutil
   2 ============
   3
   4 libbtrfsutil is a library for managing Btrfs filesystems. It is licensed under
   5 the LGPL. libbtrfsutil provides interfaces for a subset of the operations
   6 offered by the `btrfs` command line utility. It also includes official Python
   7 bindings (Python 3 only).
   8
   9 Development
  10 -----------
  11
  12 The [development process for btrfs-progs](../README.md#development) applies.
  13
  14 libbtrfsutil only includes operations that are done through the filesystem and
  15 ioctl interface, not operations that modify the filesystem directly (e.g., mkfs
  16 or fsck). This is by design but also a legal necessity, as the filesystem
  17 implementation is GPL but libbtrfsutil is LGPL. That is also why the
  18 libbtrfsutil code is a reimplementation of the btrfs-progs code rather than a
  19 refactoring. Be wary of this when porting functionality.
  20
  21 libbtrfsutil is semantically versioned separately from btrfs-progs. It is the
  22 maintainers' responsibility to bump the version as needed (at most once per
  23 release of btrfs-progs).
  24
  25 A few guidelines:
  26
  27 * All interfaces must be documented in `btrfsutil.h` using the kernel-doc style
  28 * Error codes should be specific about what _exactly_ failed
  29 * Functions should have a path and an fd variant whenever possible
  30 * Spell out terms in function names, etc. rather than abbreviating whenever
  31   possible
  32 * Don't require the Btrfs UAPI headers for any interfaces (e.g., instead of
  33   directly exposing a type from `linux/btrfs_tree.h`, abstract it away in a
  34   type specific to `libbtrfsutil`)
  35 * Preserve API and ABI compatability at all times (i.e., we don't want to bump
  36   the library major version if we don't have to)
  37 * Include Python bindings for all interfaces
  38 * Write tests for all interfaces