You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

132 lines
5.9 KiB

  1. # meli [![GitHub license](https://img.shields.io/github/license/meli/meli)](https://github.com/meli/meli/blob/master/COPYING) [![Crates.io](https://img.shields.io/crates/v/meli)](https://crates.io/crates/meli)
  2. **BSD/Linux terminal email client with support for multiple accounts and Maildir / mbox / notmuch / IMAP / JMAP.**
  3. Community links:
  4. [mailing lists](https://lists.meli.delivery/) | `#meli` on OFTC IRC | Report bugs and/or feature requests in [meli's issue tracker](https://git.meli.delivery/meli/meli/issues "meli gitea issue tracker")
  5. | | | |
  6. :---:|:---:|:---:
  7. ![Main view screenshot](./docs/screenshots/main.webp "mail meli view screenshot") | ![Compact main view screenshot](./docs/screenshots/compact.webp "compact main view screenshot") | ![Compose with embed terminal editor screenshot](./docs/screenshots/compose.webp "composing view screenshot")
  8. Main view | Compact main view | Compose with embed terminal editor
  9. Main repository:
  10. * https://git.meli.delivery/meli/meli
  11. Official mirrors:
  12. * https://github.com/meli/meli
  13. ## Install
  14. - Try an [online interactive web demo](https://meli.delivery/wasm2.html "online interactive web demo") powered by WebAssembly
  15. - [`cargo install meli`](https://crates.io/crates/meli "crates.io meli package")
  16. - [Download and install pre-built debian package, static linux binary](https://github.com/meli/meli/releases/ "github releases for meli"), or
  17. - Install with [Nix](https://search.nixos.org/packages?show=meli&query=meli&from=0&size=30&sort=relevance&channel=unstable#disabled "nixos package search results for 'meli'")
  18. ## Documentation
  19. See a comprehensive tour of `meli` in the manual page [`meli(7)`](./docs/meli.7).
  20. See also the [Quickstart tutorial](https://meli.delivery/documentation.html#quick-start) online.
  21. After installing `meli`, see `meli(1)`, `meli.conf(5)`, `meli(7)` and `meli-themes(5)` for documentation. Sample configuration and theme files can be found in the `docs/samples/` subdirectory. Manual pages are also [hosted online](https://meli.delivery/documentation.html "meli documentation").
  22. `meli` by default looks for a configuration file in this location: `$XDG_CONFIG_HOME/meli/config.toml`
  23. You can run meli with arbitrary configuration files by setting the `$MELI_CONFIG`
  24. environment variable to their locations, i.e.:
  25. ```sh
  26. MELI_CONFIG=./test_config cargo run
  27. ```
  28. ## Build
  29. For a quick start, build and install locally:
  30. ```sh
  31. PREFIX=~/.local make install
  32. ```
  33. Available subcommands for `make` are listed with `make help`. The Makefile *should* be POSIX portable and not require a specific `make` version.
  34. `meli` requires rust 1.39 and rust's package manager, Cargo. Information on how
  35. to get it on your system can be found here: <https://doc.rust-lang.org/cargo/getting-started/installation.html>
  36. With Cargo available, the project can be built with `make` and the resulting binary will then be found under `target/release/meli`. Run `make install` to install the binary and man pages. This requires root, so I suggest you override the default paths and install it in your `$HOME`: `make PREFIX=$HOME/.local install`.
  37. You can build and run `meli` with one command: `cargo run --release`.
  38. ### Build features
  39. Some functionality is held behind "feature gates", or compile-time flags. The following list explains each feature's purpose:
  40. - `gpgme` enables GPG support via `libgpgme` (on by default)
  41. - `dbus-notifications` enables showing notifications using `dbus` (on by default)
  42. - `notmuch` provides support for using a notmuch database as a mail backend (on by default)
  43. - `jmap` provides support for connecting to a jmap server and use it as a mail backend (off by default)
  44. - `sqlite3` provides support for builting fast search indexes in local sqlite3 databases (on by default)
  45. - `cli-docs` includes the manpage documentation compiled by either `mandoc` or `man` binary to plain text in `meli`'s command line. Embedded documentation can be viewed with the subcommand `meli man [PAGE]`
  46. - `svgscreenshot` provides support for taking screenshots of the current view of `meli` and saving it as SVG files. Its only purpose is taking screenshots for the official `meli` webpage. (off by default)
  47. - `debug-tracing` enables various trace debug logs from various places around the `meli` code base. The trace log is printed in `stderr`. (off by default)
  48. ### Build Debian package (*deb*)
  49. Building with Debian's packaged cargo might require the installation of these
  50. two packages: `librust-openssl-sys-dev librust-libdbus-sys-dev`
  51. A `*.deb` package can be built with `make deb-dist`
  52. ### Using notmuch
  53. To use the optional notmuch backend feature, you must have `libnotmuch5` installed in your system. In Debian-like systems, install the `libnotmuch5` packages. `meli` detects the library's presence on runtime.
  54. ### Using GPG
  55. To use the optional gpg feature, you must have `libgpgme` installed in your system. In Debian-like systems, install the `libgpgme11` package. `meli` detects the library's presence on runtime.
  56. ### Building with JMAP
  57. To build with JMAP support, prepend the environment variable `MELI_FEATURES='jmap'` to your make invocation:
  58. ```sh
  59. MELI_FEATURES="jmap" make
  60. ```
  61. or if building directly with cargo, use the flag `--features="jmap"'.
  62. # Development
  63. Development builds can be built and/or run with
  64. ```
  65. cargo build
  66. cargo run
  67. ```
  68. There is a debug/tracing log feature that can be enabled by using the flag
  69. `--feature debug-tracing` after uncommenting the features in `Cargo.toml`. The logs
  70. are printed in stderr, thus you can run `meli` with a redirection (i.e `2> log`)
  71. Code style follows the default rustfmt profile.
  72. ## Testing
  73. How to run specific tests:
  74. ```sh
  75. cargo test -p {melib, meli} (-- --nocapture) (--test test_name)
  76. ```
  77. ## Profiling
  78. ```sh
  79. perf record -g target/debug/bin
  80. perf script | stackcollapse-perf | rust-unmangle | flamegraph > perf.svg
  81. ```
  82. ## Running fuzz targets
  83. Note: `cargo-fuzz` requires the nightly toolchain.
  84. ```sh
  85. cargo +nightly fuzz run envelope_parse -- -dict=fuzz/envelope_tokens.dict
  86. ```