+165 -96 +/-3 browse
| 1 | diff --git a/BUILD.md b/BUILD.md |
| 2 | new file mode 100644 |
| 3 | index 0000000..ed45cf8 |
| 4 | --- /dev/null |
| 5 | +++ b/BUILD.md |
| 6 | @@ -0,0 +1,73 @@ |
| 7 | + # Build `meli` |
| 8 | + |
| 9 | + For a quick start, build and install locally: |
| 10 | + |
| 11 | + ```sh |
| 12 | + PREFIX=~/.local make install |
| 13 | + ``` |
| 14 | + |
| 15 | + Available subcommands for `make` are listed with `make help`. |
| 16 | + The Makefile *should* be POSIX portable and not require a specific `make` version. |
| 17 | + |
| 18 | + `meli` requires rust version 1.68.2 or later and rust's package manager, Cargo. |
| 19 | + Information on how to get it on your system can be found here: <https://doc.rust-lang.org/cargo/getting-started/installation.html> |
| 20 | + |
| 21 | + With Cargo available, the project can be built with `make` and the resulting binary will then be found under `target/release/meli`. |
| 22 | + Run `make install` to install the binary and man pages. |
| 23 | + This requires root, so I suggest you override the default paths and install it in your `$HOME`: `make PREFIX=${HOME}/.local install`. |
| 24 | + |
| 25 | + You can build and run `meli` with one command: `cargo run --release`. |
| 26 | + |
| 27 | + ## Build features |
| 28 | + |
| 29 | + Some functionality is held behind "feature gates", or compile-time flags. The following list explains each feature's purpose: |
| 30 | + |
| 31 | + - `gpgme` enables GPG support via `libgpgme` (on by default) |
| 32 | + - `dbus-notifications` enables showing notifications using `dbus` (on by default) |
| 33 | + - `notmuch` provides support for using a notmuch database as a mail backend (on by default) |
| 34 | + - `jmap` provides support for connecting to a jmap server and use it as a mail backend (on by default) |
| 35 | + - `sqlite3` provides support for builting fast search indexes in local sqlite3 databases (on by default) |
| 36 | + - `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). |
| 37 | + - `regexp` provides experimental support for theming some e-mail fields based |
| 38 | + on regular expressions. |
| 39 | + It uses the `pcre2` library. |
| 40 | + Since it's actual use in the code is very limited, it is not recommended to use this (off by default). |
| 41 | + - `static` and `*-static` bundle C libraries in dependencies so that you don't need them installed in your system (on by default). |
| 42 | + |
| 43 | + ## Build Debian package (*deb*) |
| 44 | + |
| 45 | + Building with Debian's packaged cargo might require the installation of these two packages: `librust-openssl-sys-dev librust-libdbus-sys-dev` |
| 46 | + |
| 47 | + A `*.deb` package can be built with `make deb-dist` |
| 48 | + |
| 49 | + ## Using notmuch |
| 50 | + |
| 51 | + To use the optional notmuch backend feature, you must have `libnotmuch5` installed in your system. |
| 52 | + In Debian-like systems, install the `libnotmuch5` packages. |
| 53 | + `meli` detects the library's presence on runtime. |
| 54 | + 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. |
| 55 | + |
| 56 | + ## Using GPG |
| 57 | + |
| 58 | + To use the optional gpg feature, you must have `libgpgme` installed in your system. |
| 59 | + In Debian-like systems, install the `libgpgme11` package. |
| 60 | + `meli` detects the library's presence on runtime. |
| 61 | + |
| 62 | + ## Development |
| 63 | + |
| 64 | + Development builds can be built and/or run with |
| 65 | + |
| 66 | + ``` |
| 67 | + cargo build |
| 68 | + cargo run |
| 69 | + ``` |
| 70 | + |
| 71 | + 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`. |
| 72 | + 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`). |
| 73 | + |
| 74 | + To trace network and protocol communications you can enable the following features: |
| 75 | + |
| 76 | + - `imap-trace` |
| 77 | + - `jmap-trace` |
| 78 | + - `nntp-trace` |
| 79 | + - `smtp-trace` |
| 80 | diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md |
| 81 | index 41c7866..155035f 100644 |
| 82 | --- a/DEVELOPMENT.md |
| 83 | +++ b/DEVELOPMENT.md |
| 84 | @@ -1,5 +1,23 @@ |
| 85 | # Development |
| 86 | |
| 87 | + Code style follows the `rustfmt.toml` file. |
| 88 | + |
| 89 | + ## Trace logs |
| 90 | + |
| 91 | + Enable trace logs to `stderr` with: |
| 92 | + |
| 93 | + ```sh |
| 94 | + export MELI_DEBUG_STDERR=yes |
| 95 | + ``` |
| 96 | + |
| 97 | + This means you will have to to redirect `stderr` to a file like `meli 2> trace.log`. |
| 98 | + |
| 99 | + Tracing is opt-in by build features: |
| 100 | + |
| 101 | + ```sh |
| 102 | + cargo build --features=debug-tracing,imap-trace,smtp-trace |
| 103 | + ``` |
| 104 | + |
| 105 | ## use `.git-blame-ignore-revs` file _optional_ |
| 106 | |
| 107 | Use this file to ignore formatting commits from `git-blame`. |
| 108 | @@ -9,25 +27,41 @@ It needs to be set up per project because `git-blame` will fail if it's missing. |
| 109 | git config blame.ignoreRevsFile .git-blame-ignore-revs |
| 110 | ``` |
| 111 | |
| 112 | - ## Testing |
| 113 | + ## Formatting with `rustfmt` |
| 114 | |
| 115 | - How to run specific tests: |
| 116 | + ```sh |
| 117 | + make fmt |
| 118 | + ``` |
| 119 | + |
| 120 | + ## Linting with `clippy` |
| 121 | |
| 122 | ```sh |
| 123 | - cargo test -p {melib, meli} (-- --nocapture) (--test test_name) |
| 124 | + make lint |
| 125 | ``` |
| 126 | |
| 127 | - ## Profiling |
| 128 | + ## Testing |
| 129 | |
| 130 | ```sh |
| 131 | - perf record -g target/debug/bin |
| 132 | - perf script | stackcollapse-perf | rust-unmangle | flamegraph > perf.svg |
| 133 | + make test |
| 134 | ``` |
| 135 | |
| 136 | - ## Running fuzz targets |
| 137 | + How to run specific tests: |
| 138 | |
| 139 | - Note: `cargo-fuzz` requires the nightly toolchain. |
| 140 | + ```sh |
| 141 | + cargo test -p {melib, meli} (-- --nocapture) (--test test_name) |
| 142 | + ``` |
| 143 | + |
| 144 | + ## Profiling |
| 145 | |
| 146 | ```sh |
| 147 | - cargo +nightly fuzz run envelope_parse -- -dict=fuzz/envelope_tokens.dict |
| 148 | + perf record -g target/debug/meli |
| 149 | + perf script | stackcollapse-perf | rust-unmangle | flamegraph > perf.svg |
| 150 | ``` |
| 151 | + <!-- --> |
| 152 | + <!-- ## Running fuzz targets --> |
| 153 | + <!-- --> |
| 154 | + <!-- Note: `cargo-fuzz` requires the nightly toolchain. --> |
| 155 | + <!-- --> |
| 156 | + <!-- ```sh --> |
| 157 | + <!-- cargo +nightly fuzz run envelope_parse -- -dict=fuzz/envelope_tokens.dict --> |
| 158 | + <!-- ``` --> |
| 159 | diff --git a/README.md b/README.md |
| 160 | index 6f68a4f..09646df 100644 |
| 161 | --- a/README.md |
| 162 | +++ b/README.md |
| 163 | @@ -1,27 +1,46 @@ |
| 164 | - # meli [](https://github.com/meli/meli/blob/master/COPYING) [](https://crates.io/crates/meli) [](ircs://irc.oftc.net:6697/%23meli) |
| 165 | + # meli   [](https://github.com/meli/meli/blob/master/COPYING) [](https://crates.io/crates/meli) [](ircs://irc.oftc.net:6697/%23meli) |
| 166 | |
| 167 | - **BSD/Linux terminal email client with support for multiple accounts and Maildir / mbox / notmuch / IMAP / JMAP / NNTP (Usenet).** |
| 168 | + **BSD/Linux/macos terminal email client with support for multiple accounts and Maildir / mbox / notmuch / IMAP / JMAP / NNTP (Usenet).** |
| 169 | |
| 170 | - * [mailing lists](https://lists.meli.delivery/) | `#meli` on OFTC IRC |
| 171 | - * Main repository: <https://git.meli.delivery/meli/meli> Report bugs and/or feature requests in [meli's issue tracker](https://git.meli.delivery/meli/meli/issues "meli gitea issue tracker") |
| 172 | - * Official mirrors: |
| 173 | - - <https://codeberg.org/epilys/meli> |
| 174 | - - <https://github.com/meli/meli> |
| 175 | + Try an [old online interactive web demo](https://meli-email.org/wasm2.html "online interactive web demo") powered by WebAssembly! |
| 176 | + |
| 177 | + * `#meli` on OFTC IRC | [mailing lists](https://lists.meli-email.org/) |
| 178 | + * Repository: |
| 179 | + - Main <https://git.meli-email.org/meli/meli> Report bugs and/or feature requests in [meli's issue tracker](https://git.meli-email.org/meli/meli/issues "meli gitea issue tracker") |
| 180 | + - Official mirror <https://codeberg.org/epilys/meli> |
| 181 | + - Official mirror <https://github.com/meli/meli> |
| 182 | + |
| 183 | + **Table of contents**: |
| 184 | + |
| 185 | + - [Install](#install) |
| 186 | + - [Build](#build) |
| 187 | + - [Quick start](#quick-start) |
| 188 | + - [Supported E-mail backends](#supported-e-mail-backends) |
| 189 | + - [E-mail submission backends](#e-mail-submission-backends) |
| 190 | + - [Non-exhaustive list of features](#non-exhaustive-list-of-features) |
| 191 | + - [HTML Rendering](#html-rendering) |
| 192 | + - [Documentation](#documentation) |
| 193 | |
| 194 | ## Install |
| 195 | |
| 196 | - - Try an [old online interactive web demo](https://meli.delivery/wasm2.html "online interactive web demo") powered by WebAssembly |
| 197 | - - Pre-built binaries for [pkgsrc](https://pkgsrc.se/mail/meli) and [openbsd ports](https://openports.pl/path/mail/meli). |
| 198 | - - `cargo install meli` or `cargo install --git https://git.meli.delivery/meli/meli.git meli` |
| 199 | - - [Download and install pre-built debian package, static linux binary](https://github.com/meli/meli/releases/ "github releases for meli"), or |
| 200 | - - 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'"). |
| 201 | + - [pkgsrc](https://pkgsrc.se/mail/meli) |
| 202 | + - [openbsd ports](https://openports.pl/path/mail/meli) |
| 203 | + - `cargo install meli` or `cargo install --git https://git.meli-email.org/meli/meli.git meli` |
| 204 | + - [Pre-built debian package, static binaries](https://github.com/meli/meli/releases/ "github releases for meli") |
| 205 | + - [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'") |
| 206 | + |
| 207 | + ## Build |
| 208 | + |
| 209 | + Run `cargo build --release --bin meli` or `make`. |
| 210 | + |
| 211 | + For detailed building instructions, see [`BUILD.md`](./BUILD.md) |
| 212 | |
| 213 | ## Quick start |
| 214 | |
| 215 | <table> |
| 216 | <tr><td> |
| 217 | |
| 218 | - ```shell |
| 219 | + ```sh |
| 220 | # Create configuration file in ${XDG_CONFIG_HOME}/meli/config.toml: |
| 221 | $ meli create-config |
| 222 | # Edit configuration in ${EDITOR} or ${VISUAL}: |
| 223 | @@ -36,9 +55,12 @@ $ meli |
| 224 | |
| 225 | See a comprehensive tour of `meli` in the manual page [`meli(7)`](./meli/docs/meli.7). |
| 226 | |
| 227 | - See also the [Quickstart tutorial](https://meli.delivery/documentation.html#quick-start) online. |
| 228 | + See also the [Quickstart tutorial](https://meli-email.org/documentation.html#quick-start) online. |
| 229 | |
| 230 | - 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` |
| 231 | + After installing `meli`, see `meli(1)`, `meli.conf(5)`, `meli(7)` and `meli-themes(5)` for documentation. |
| 232 | + Sample configuration and theme files can be found in the `meli/docs/samples/` subdirectory. |
| 233 | + Manual pages are also [hosted online](https://meli-email.org/documentation.html "meli documentation"). |
| 234 | + `meli` by default looks for a configuration file in this location: `${XDG_CONFIG_HOME}/meli/config.toml`. |
| 235 | |
| 236 | You can run meli with arbitrary configuration files by setting the `${MELI_CONFIG}` environment variable to their locations, i.e.: |
| 237 | |
| 238 | @@ -100,92 +122,32 @@ Main view | Compact main view | Compose with embed terminal editor |
| 239 | - GPG signing, encryption, signing + encryption |
| 240 | - GPG signature verification |
| 241 | |
| 242 | + ## HTML Rendering |
| 243 | + |
| 244 | + HTML rendering is achieved using [w3m](https://github.com/tats/w3m) by default. |
| 245 | + 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)). |
| 246 | + |
| 247 | + |
| 248 | ## Documentation |
| 249 | |
| 250 | See a comprehensive tour of `meli` in the manual page [`meli(7)`](./meli/docs/meli.7). |
| 251 | |
| 252 | - See also the [Quickstart tutorial](https://meli.delivery/documentation.html#quick-start) online. |
| 253 | + See also the [Quickstart tutorial](https://meli-email.org/documentation.html#quick-start) online. |
| 254 | |
| 255 | After installing `meli`, see `meli(1)`, `meli.conf(5)`, `meli(7)` and `meli-themes(5)` for documentation. |
| 256 | Sample configuration and theme files can be found in the `meli/docs/samples/` subdirectory. |
| 257 | - Manual pages are also [hosted online](https://meli.delivery/documentation.html "meli documentation"). |
| 258 | + Manual pages are also [hosted online](https://meli-email.org/documentation.html "meli documentation"). |
| 259 | |
| 260 | `meli` by default looks for a configuration file in this location: `${XDG_CONFIG_HOME}/meli/config.toml` |
| 261 | |
| 262 | - You can run meli with arbitrary configuration files by setting the `${MELI_CONFIG}` environment variable to their locations, i.e.: |
| 263 | + You can run meli with arbitrary configuration files by setting the `${MELI_CONFIG}` environment variable to their locations, or use the `[-c, --config]` argument: |
| 264 | |
| 265 | ```sh |
| 266 | - MELI_CONFIG=./test_config cargo run |
| 267 | + MELI_CONFIG=./test_config meli |
| 268 | ``` |
| 269 | |
| 270 | - ## Build |
| 271 | - For a quick start, build and install locally: |
| 272 | + or |
| 273 | |
| 274 | ```sh |
| 275 | - PREFIX=~/.local make install |
| 276 | + meli -c ./test_config |
| 277 | ``` |
| 278 | - |
| 279 | - Available subcommands for `make` are listed with `make help`. |
| 280 | - The Makefile *should* be POSIX portable and not require a specific `make` version. |
| 281 | - |
| 282 | - `meli` requires rust version 1.68.2 or later and rust's package manager, Cargo. |
| 283 | - Information on how to get it on your system can be found here: <https://doc.rust-lang.org/cargo/getting-started/installation.html> |
| 284 | - |
| 285 | - With Cargo available, the project can be built with `make` and the resulting binary will then be found under `target/release/meli`. |
| 286 | - Run `make install` to install the binary and man pages. |
| 287 | - This requires root, so I suggest you override the default paths and install it in your `$HOME`: `make PREFIX=${HOME}/.local install`. |
| 288 | - |
| 289 | - You can build and run `meli` with one command: `cargo run --release`. |
| 290 | - |
| 291 | - ### Build features |
| 292 | - |
| 293 | - Some functionality is held behind "feature gates", or compile-time flags. The following list explains each feature's purpose: |
| 294 | - |
| 295 | - - `gpgme` enables GPG support via `libgpgme` (on by default) |
| 296 | - - `dbus-notifications` enables showing notifications using `dbus` (on by default) |
| 297 | - - `notmuch` provides support for using a notmuch database as a mail backend (on by default) |
| 298 | - - `jmap` provides support for connecting to a jmap server and use it as a mail backend (on by default) |
| 299 | - - `sqlite3` provides support for builting fast search indexes in local sqlite3 databases (on by default) |
| 300 | - - `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). |
| 301 | - - `regexp` provides experimental support for theming some e-mail fields based |
| 302 | - on regular expressions. |
| 303 | - It uses the `pcre2` library. |
| 304 | - Since it's actual use in the code is very limited, it is not recommended to use this (off by default). |
| 305 | - - `static` and `*-static` bundle C libraries in dependencies so that you don't need them installed in your system (on by default). |
| 306 | - |
| 307 | - ### Build Debian package (*deb*) |
| 308 | - |
| 309 | - Building with Debian's packaged cargo might require the installation of these two packages: `librust-openssl-sys-dev librust-libdbus-sys-dev` |
| 310 | - |
| 311 | - A `*.deb` package can be built with `make deb-dist` |
| 312 | - |
| 313 | - ### Using notmuch |
| 314 | - |
| 315 | - To use the optional notmuch backend feature, you must have `libnotmuch5` installed in your system. |
| 316 | - In Debian-like systems, install the `libnotmuch5` packages. |
| 317 | - `meli` detects the library's presence on runtime. |
| 318 | - |
| 319 | - ### Using GPG |
| 320 | - |
| 321 | - To use the optional gpg feature, you must have `libgpgme` installed in your system. |
| 322 | - In Debian-like systems, install the `libgpgme11` package. |
| 323 | - `meli` detects the library's presence on runtime. |
| 324 | - |
| 325 | - ### HTML Rendering |
| 326 | - |
| 327 | - HTML rendering is achieved using [w3m](https://github.com/tats/w3m) by default. |
| 328 | - 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)). |
| 329 | - |
| 330 | - # Development |
| 331 | - |
| 332 | - Development builds can be built and/or run with |
| 333 | - |
| 334 | - ``` |
| 335 | - cargo build |
| 336 | - cargo run |
| 337 | - ``` |
| 338 | - |
| 339 | - 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`. |
| 340 | - 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`). |
| 341 | - |
| 342 | - Code style follows the `rustfmt.toml` file. |