From ea8adaf1ccca332cb26c390a1f58e431d067a339 Mon Sep 17 00:00:00 2001 From: Alexander Fougner Date: Sun, 5 Mar 2023 15:43:45 +0100 Subject: [PATCH] Update docs - add some project info for the main readme - migrate readmes to markdown for improved formatting - The main binary now requires the Rust toolchain, so make note of it in the build instructions. Signed-off-by: Alexander Fougner --- INSTALL | 75 --------------------------------------- INSTALL.md | 101 +++++++++++++++++++++++++++++++++++++++++++++++++++++ README | 12 ------- README.md | 27 ++++++++++++++ 4 files changed, 128 insertions(+), 87 deletions(-) delete mode 100644 INSTALL create mode 100644 INSTALL.md delete mode 100644 README create mode 100644 README.md diff --git a/INSTALL b/INSTALL deleted file mode 100644 index b4d60bf4..00000000 --- a/INSTALL +++ /dev/null @@ -1,75 +0,0 @@ --- Getting started -- - -Dependencies: - - * libaio - * libblkid - * libkeyutils - * liblz4 - * libsodium - * liburcu - * libuuid - * libzstd - * pkg-config - * zlib1g - * valgrind - -Debian (Bullseye or later) and Ubuntu (20.04 or later): you can install these with - apt install -y pkg-config libaio-dev libblkid-dev libkeyutils-dev \ - liblz4-dev libsodium-dev liburcu-dev libzstd-dev \ - uuid-dev zlib1g-dev valgrind libudev-dev git build-essential \ - python3 python3-docutils - -Fedora: install the "Development tools" group along with: - dnf install -y libaio-devel libsodium-devel \ - libblkid-devel libzstd-devel zlib-devel userspace-rcu-devel \ - lz4-devel libuuid-devel valgrind-devel keyutils-libs-devel \ - findutils - -Arch: install bcachefs-tools-git from the AUR. -Or to build from source, install build dependencies with - pacman -S base-devel libaio keyutils libsodium liburcu zstd valgrind - -Then, just make && make install - - --- Experimental features -- - -Experimental fuse support is currently disabled by default. Fuse support is at -an early stage and may corrupt your filesystem, so it should only be used for -testing. To enable, you'll also need to add: - -* libfuse3 >= 3.7 - -On Debian/Ubuntu (Bullseye/20.04 or later needed for libfuse >= 3.7): - apt install -y libfuse3-dev - -On Fedora (32 or later needed for lbifuse >= 3.7): - dnf install -y fuse3-devel - -Arch: - pacman -S fuse3 - -Then, make using the BCACHEFS_FUSE environment variable (make clean first if -previously built without fuse support): - -BCACHEFS_FUSE=1 make && make install - - --- Tests -- - -Some tests are available to validate the "bcachefs" binary. The tests depend -on python3 pytest. - -On debian: - apt install -u python3-pytest - -Then, you can run the tests via: - - make check - # or if pytest has a different name - make check PYTEST=pytest - -Optionally, you may wish to run tests in parallel using python3-pytest-xdist: - - cd tests; pytest-3 -n4 diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 00000000..ec5d67bb --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,101 @@ +Getting started +--------------- + +Build dependencies: + + * libaio + * libblkid + * libkeyutils + * liblz4 + * libsodium + * liburcu + * libuuid + * libzstd + * pkg-config + * valgrind + * zlib1g + +In addition a recent Rust toolchain is required (rustc, cargo), either by using +[rustup](https://rustup.rs/) or make sure to use a distribution where rustc (>=1.64) +is available. + +Debian (Bullseye or later) and Ubuntu (20.04 or later): you can install these with + +``` shell +apt install -y pkg-config libaio-dev libblkid-dev libkeyutils-dev \ + liblz4-dev libsodium-dev liburcu-dev libzstd-dev \ + uuid-dev zlib1g-dev valgrind libudev-dev git build-essential \ + python3 python3-docutils +``` + +Fedora: install the "Development tools" group along with: +```shell +dnf install -y libaio-devel libsodium-devel \ + libblkid-devel libzstd-devel zlib-devel userspace-rcu-devel \ + lz4-devel libuuid-devel valgrind-devel keyutils-libs-devel \ + findutils +``` + +Arch: install bcachefs-tools-git from the AUR. +Or to build from source, install build dependencies with +```shell +pacman -S base-devel libaio keyutils libsodium liburcu zstd valgrind +``` + +Then, just `make && make install` + + +Experimental features +--------------------- + +Experimental fuse support is currently disabled by default. Fuse support is at +an early stage and may corrupt your filesystem, so it should only be used for +testing. To enable, you'll also need to add: + +* libfuse3 >= 3.7 + +On Debian/Ubuntu (Bullseye/20.04 or later needed for libfuse >= 3.7): +```shell +apt install -y libfuse3-dev +``` + +On Fedora (32 or later needed for lbifuse >= 3.7): +```shell +dnf install -y fuse3-devel +``` + +Arch: +```shell +pacman -S fuse3 +``` + +Then, make using the `BCACHEFS_FUSE` environment variable (make clean first if +previously built without fuse support): + +```shell +BCACHEFS_FUSE=1 make && make install +``` + +Tests +----- +Some tests are available to validate the `bcachefs` binary. The tests depend +on python3 pytest. + +On debian: +```shell +apt install -u python3-pytest +``` + +Then, you can run the tests via: + +```shell +make check +# or if pytest has a different name +make check PYTEST=pytest +``` + +Optionally, you may wish to run tests in parallel using python3-pytest-xdist: + +```shell +cd tests; pytest-3 -n4 +``` \ No newline at end of file diff --git a/README b/README deleted file mode 100644 index 3d2641e4..00000000 --- a/README +++ /dev/null @@ -1,12 +0,0 @@ -Userspace tools for bcachefs - -This builds the bcachefs tool, which has a number of subcommands for formatting -and managing bcachefs filesystems: - -bcachefs format -bcachefs unlock -bcachefs assemble -bcachefs incremental -etc. - -Run bcachefs --help for full list of commands. diff --git a/README.md b/README.md new file mode 100644 index 00000000..30149ab4 --- /dev/null +++ b/README.md @@ -0,0 +1,27 @@ +bcachefs-tools +============== +Userspace tools and docs for bcachefs + +Bcachefs is an advanced new filesystem for Linux, with an emphasis on reliability and robustness +and the complete set of features one would expect from a modern filesystem. + +This repo primarily consists of the following: + +- bcachefs tool, the reason this repo exists. +- {mkfs,mount,fsck}.bcachefs utils, which is just wrappers calling the corresponding subcommands + in the main tool +- docs in the form of man-pages and a user manual + +Please refer to the main site for [getting started](https://bcachefs.org/#Getting_started) +An in-depth user manual is (also) found on the [official website](https://bcachefs.org/#Documentation) + +Build and install +----------------- + +Refer to [INSTALL.md](./INSTALL.md) + +Bug reports and contributions +----------------------------- + +- The official mailing list, linux-bcachefs@vger.kernel.org +- IRC: #bcache on OFTC (irc.oftc.net). Although, note that it can be easily missed.