Commit
Author: Manos Pitsidianakis [manos@pitsidianak.is]
Hash: 5afc078587b86104dc5b615c1840dade64768a5f
Timestamp: Sat, 20 Jan 2024 09:41:07 +0000 (11 months ago)

+165 -96 +/-3 browse
Update README.md, DEVELOPMENT.md and create BUILD.md 
Update README.md, DEVELOPMENT.md and create BUILD.md

README.md is quite lengthy so split extraneous info to other `.md`
files.

Signed-off-by: Manos Pitsidianakis <manos@pitsidianak.is>
1diff --git a/BUILD.md b/BUILD.md
2new file mode 100644
3index 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
81index 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
160index 6f68a4f..09646df 100644
161--- a/README.md
162+++ b/README.md
163 @@ -1,27 +1,46 @@
164- # 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)
165+ # 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)
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.