diff --git a/BUILD.md b/BUILD.md new file mode 100644 index 00000000..ed45cf83 --- /dev/null +++ b/BUILD.md @@ -0,0 +1,73 @@ +# Build `meli` + +For a quick start, build and install locally: + +```sh + PREFIX=~/.local make install +``` + +Available subcommands for `make` are listed with `make help`. +The Makefile *should* be POSIX portable and not require a specific `make` version. + +`meli` requires rust version 1.68.2 or later and rust's package manager, Cargo. +Information on how to get it on your system can be found here: + +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`. + +You can build and run `meli` with one command: `cargo run --release`. + +## Build features + +Some functionality is held behind "feature gates", or compile-time flags. The following list explains each feature's purpose: + +- `gpgme` enables GPG support via `libgpgme` (on by default) +- `dbus-notifications` enables showing notifications using `dbus` (on by default) +- `notmuch` provides support for using a notmuch database as a mail backend (on by default) +- `jmap` provides support for connecting to a jmap server and use it as a mail backend (on by default) +- `sqlite3` provides support for builting fast search indexes in local sqlite3 databases (on by default) +- `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]` (on by default). +- `regexp` provides experimental support for theming some e-mail fields based + on regular expressions. + It uses the `pcre2` library. + Since it's actual use in the code is very limited, it is not recommended to use this (off by default). +- `static` and `*-static` bundle C libraries in dependencies so that you don't need them installed in your system (on by default). + +## Build Debian package (*deb*) + +Building with Debian's packaged cargo might require the installation of these two packages: `librust-openssl-sys-dev librust-libdbus-sys-dev` + +A `*.deb` package can be built with `make deb-dist` + +## Using notmuch + +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. +If it is not detected, you can use the `library_file_path` setting on your notmuch account to specify the absolute path of the library. + +## Using GPG + +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. + +## Development + +Development builds can be built and/or run with + +``` +cargo build +cargo run +``` + +There is a debug/tracing log feature that can be enabled by using the flag `--feature debug-tracing` after uncommenting the features in `Cargo.toml`. +The logs are printed in stderr when the env var `MELI_DEBUG_STDERR` is defined, thus you can run `meli` with a redirection (i.e `2> log`). + +To trace network and protocol communications you can enable the following features: + +- `imap-trace` +- `jmap-trace` +- `nntp-trace` +- `smtp-trace` diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 41c7866e..155035f9 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,5 +1,23 @@ # Development +Code style follows the `rustfmt.toml` file. + +## Trace logs + +Enable trace logs to `stderr` with: + +```sh +export MELI_DEBUG_STDERR=yes +``` + +This means you will have to to redirect `stderr` to a file like `meli 2> trace.log`. + +Tracing is opt-in by build features: + +```sh +cargo build --features=debug-tracing,imap-trace,smtp-trace +``` + ## use `.git-blame-ignore-revs` file _optional_ Use this file to ignore formatting commits from `git-blame`. @@ -9,25 +27,41 @@ It needs to be set up per project because `git-blame` will fail if it's missing. git config blame.ignoreRevsFile .git-blame-ignore-revs ``` -## Testing +## Formatting with `rustfmt` -How to run specific tests: +```sh +make fmt +``` + +## Linting with `clippy` ```sh -cargo test -p {melib, meli} (-- --nocapture) (--test test_name) +make lint ``` -## Profiling +## Testing ```sh -perf record -g target/debug/bin -perf script | stackcollapse-perf | rust-unmangle | flamegraph > perf.svg +make test ``` -## Running fuzz targets +How to run specific tests: -Note: `cargo-fuzz` requires the nightly toolchain. +```sh +cargo test -p {melib, meli} (-- --nocapture) (--test test_name) +``` + +## Profiling ```sh -cargo +nightly fuzz run envelope_parse -- -dict=fuzz/envelope_tokens.dict +perf record -g target/debug/meli +perf script | stackcollapse-perf | rust-unmangle | flamegraph > perf.svg ``` + + + + + + + + diff --git a/README.md b/README.md index 6f68a4fe..09646df1 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,46 @@ -# 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) [![IRC channel](https://img.shields.io/badge/irc.oftc.net-%23meli-blue)](ircs://irc.oftc.net:6697/%23meli) +# meli ![Established, created in 2017](https://img.shields.io/badge/Est.-2017-blue) ![Minimum Supported Rust Version](https://img.shields.io/badge/MSRV-1.68.2-blue) [![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) [![IRC channel](https://img.shields.io/badge/irc.oftc.net-%23meli-blue)](ircs://irc.oftc.net:6697/%23meli) -**BSD/Linux terminal email client with support for multiple accounts and Maildir / mbox / notmuch / IMAP / JMAP / NNTP (Usenet).** +**BSD/Linux/macos terminal email client with support for multiple accounts and Maildir / mbox / notmuch / IMAP / JMAP / NNTP (Usenet).** -* [mailing lists](https://lists.meli.delivery/) | `#meli` on OFTC IRC -* Main repository: Report bugs and/or feature requests in [meli's issue tracker](https://git.meli.delivery/meli/meli/issues "meli gitea issue tracker") -* Official mirrors: - - - - +Try an [old online interactive web demo](https://meli-email.org/wasm2.html "online interactive web demo") powered by WebAssembly! + +* `#meli` on OFTC IRC | [mailing lists](https://lists.meli-email.org/) +* Repository: + - Main Report bugs and/or feature requests in [meli's issue tracker](https://git.meli-email.org/meli/meli/issues "meli gitea issue tracker") + - Official mirror + - Official mirror + +**Table of contents**: + +- [Install](#install) +- [Build](#build) +- [Quick start](#quick-start) +- [Supported E-mail backends](#supported-e-mail-backends) +- [E-mail submission backends](#e-mail-submission-backends) +- [Non-exhaustive list of features](#non-exhaustive-list-of-features) +- [HTML Rendering](#html-rendering) +- [Documentation](#documentation) ## Install -- Try an [old online interactive web demo](https://meli.delivery/wasm2.html "online interactive web demo") powered by WebAssembly -- Pre-built binaries for [pkgsrc](https://pkgsrc.se/mail/meli) and [openbsd ports](https://openports.pl/path/mail/meli). -- `cargo install meli` or `cargo install --git https://git.meli.delivery/meli/meli.git meli` -- [Download and install pre-built debian package, static linux binary](https://github.com/meli/meli/releases/ "github releases for meli"), or -- 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'"). +- [pkgsrc](https://pkgsrc.se/mail/meli) +- [openbsd ports](https://openports.pl/path/mail/meli) +- `cargo install meli` or `cargo install --git https://git.meli-email.org/meli/meli.git meli` +- [Pre-built debian package, static binaries](https://github.com/meli/meli/releases/ "github releases for meli") +- [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'") + +## Build + +Run `cargo build --release --bin meli` or `make`. + +For detailed building instructions, see [`BUILD.md`](./BUILD.md) ## Quick start
-```shell +```sh # Create configuration file in ${XDG_CONFIG_HOME}/meli/config.toml: $ meli create-config # Edit configuration in ${EDITOR} or ${VISUAL}: @@ -36,9 +55,12 @@ $ meli See a comprehensive tour of `meli` in the manual page [`meli(7)`](./meli/docs/meli.7). -See also the [Quickstart tutorial](https://meli.delivery/documentation.html#quick-start) online. +See also the [Quickstart tutorial](https://meli-email.org/documentation.html#quick-start) online. -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 `meli/docs/samples/` subdirectory. Manual pages are also [hosted online](https://meli.delivery/documentation.html "meli documentation"). `meli` by default looks for a configuration file in this location: `${XDG_CONFIG_HOME}/meli/config.toml` +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 `meli/docs/samples/` subdirectory. +Manual pages are also [hosted online](https://meli-email.org/documentation.html "meli documentation"). +`meli` by default looks for a configuration file in this location: `${XDG_CONFIG_HOME}/meli/config.toml`. You can run meli with arbitrary configuration files by setting the `${MELI_CONFIG}` environment variable to their locations, i.e.: @@ -100,92 +122,32 @@ Main view | Compact main view | Compose with embed terminal editor - GPG signing, encryption, signing + encryption - GPG signature verification +## HTML Rendering + +HTML rendering is achieved using [w3m](https://github.com/tats/w3m) by default. +You can use the `pager.html_filter` setting to override this (for more details you can consult [`meli.conf(5)`](./meli/docs/meli.conf.5)). + + ## Documentation See a comprehensive tour of `meli` in the manual page [`meli(7)`](./meli/docs/meli.7). -See also the [Quickstart tutorial](https://meli.delivery/documentation.html#quick-start) online. +See also the [Quickstart tutorial](https://meli-email.org/documentation.html#quick-start) online. 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 `meli/docs/samples/` subdirectory. -Manual pages are also [hosted online](https://meli.delivery/documentation.html "meli documentation"). +Manual pages are also [hosted online](https://meli-email.org/documentation.html "meli documentation"). `meli` by default looks for a configuration file in this location: `${XDG_CONFIG_HOME}/meli/config.toml` -You can run meli with arbitrary configuration files by setting the `${MELI_CONFIG}` environment variable to their locations, i.e.: +You can run meli with arbitrary configuration files by setting the `${MELI_CONFIG}` environment variable to their locations, or use the `[-c, --config]` argument: ```sh -MELI_CONFIG=./test_config cargo run +MELI_CONFIG=./test_config meli ``` -## Build -For a quick start, build and install locally: +or ```sh - PREFIX=~/.local make install +meli -c ./test_config ``` - -Available subcommands for `make` are listed with `make help`. -The Makefile *should* be POSIX portable and not require a specific `make` version. - -`meli` requires rust version 1.68.2 or later and rust's package manager, Cargo. -Information on how to get it on your system can be found here: - -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`. - -You can build and run `meli` with one command: `cargo run --release`. - -### Build features - -Some functionality is held behind "feature gates", or compile-time flags. The following list explains each feature's purpose: - -- `gpgme` enables GPG support via `libgpgme` (on by default) -- `dbus-notifications` enables showing notifications using `dbus` (on by default) -- `notmuch` provides support for using a notmuch database as a mail backend (on by default) -- `jmap` provides support for connecting to a jmap server and use it as a mail backend (on by default) -- `sqlite3` provides support for builting fast search indexes in local sqlite3 databases (on by default) -- `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]` (on by default). -- `regexp` provides experimental support for theming some e-mail fields based - on regular expressions. - It uses the `pcre2` library. - Since it's actual use in the code is very limited, it is not recommended to use this (off by default). -- `static` and `*-static` bundle C libraries in dependencies so that you don't need them installed in your system (on by default). - -### Build Debian package (*deb*) - -Building with Debian's packaged cargo might require the installation of these two packages: `librust-openssl-sys-dev librust-libdbus-sys-dev` - -A `*.deb` package can be built with `make deb-dist` - -### Using notmuch - -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. - -### Using GPG - -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. - -### HTML Rendering - -HTML rendering is achieved using [w3m](https://github.com/tats/w3m) by default. -You can use the `pager.html_filter` setting to override this (for more details you can consult [`meli.conf(5)`](./meli/docs/meli.conf.5)). - -# Development - -Development builds can be built and/or run with - -``` -cargo build -cargo run -``` - -There is a debug/tracing log feature that can be enabled by using the flag `--feature debug-tracing` after uncommenting the features in `Cargo.toml`. -The logs are printed in stderr when the env var `MELI_DEBUG_STDERR` is defined, thus you can run `meli` with a redirection (i.e `2> log`). - -Code style follows the `rustfmt.toml` file.