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.

146 lines
4.5 KiB

  1. # meli
  2. For a quick start, build and install locally:
  3. ```sh
  4. PREFIX=~/.local make install
  5. ```
  6. Available subcommands:
  7. - meli (builds meli with optimizations in `$CARGO_TARGET_DIR`)
  8. - install (installs binary in `$BINDIR` and documentation to `$MANDIR`)
  9. - uninstall
  10. Secondary subcommands:
  11. - clean (cleans build artifacts)
  12. - check-deps (checks dependencies)
  13. - install-bin (installs binary to `$BINDIR`)
  14. - install-doc (installs manpages to `$MANDIR`)
  15. - help (prints this information)
  16. - dist (creates release tarball named `meli-VERSION.tar.gz` in this directory)
  17. - deb-dist (builds debian package in the parent directory)
  18. - distclean (cleans distribution build artifacts)
  19. - build-rustdoc (builds rustdoc documentation for all packages in `$CARGO_TARGET_DIR`)
  20. The Makefile *should* be portable and not require a specific `make` version.
  21. # Documentation
  22. After installing meli, see `meli(1)` and `meli.conf(5)` for documentation. Sample configuration and theme files can be found in the `samples/` subdirectory.
  23. # Building
  24. meli requires rust 1.39 and rust's package manager, Cargo. Information on how
  25. to get it on your system can be found here: <https://doc.rust-lang.org/cargo/getting-started/installation.html>
  26. With Cargo available, the project can be built with
  27. ```sh
  28. make
  29. ```
  30. The resulting binary will then be found under `target/release/meli`
  31. Run:
  32. ```sh
  33. make install
  34. ```
  35. to install the binary and man pages. This requires root, so I suggest you override the default paths and install it in your `$HOME`:
  36. ```sh
  37. make PREFIX=$HOME/.local install
  38. ```
  39. See `meli(1)` and `meli.conf(5)` for documentation.
  40. You can build and run meli with one command:
  41. ```sh
  42. cargo run --release
  43. ```
  44. While the project is in early development, meli will only be developed for the
  45. linux kernel and respected linux distributions. Support for more UNIX-like OSes
  46. is on the roadmap.
  47. ## Features
  48. Some functionality is held behind "feature gates", or compile-time flags. The following list explains each feature's purpose:
  49. - `dbus-notifications` enables showing notifications using `dbus`.
  50. - `notmuch` provides support for using a notmuch database as a mail backend
  51. - `jmap` provides support for connecting to a jmap server and use it as a mail backend
  52. - `sqlite3` provides support for builting fast search indexes in local sqlite3 databases
  53. - `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]`
  54. - `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.
  55. - `debug-tracing` enables various trace debug logs from various places around the meli code base. The trace log is printed in `stderr`.
  56. ## Building in Debian
  57. Building with Debian's packaged cargo might require the installation of these
  58. two packages: `librust-openssl-sys-dev librust-libdbus-sys-dev`
  59. A `*.deb` package can be built with `make deb-dist`
  60. # Using notmuch
  61. 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.
  62. # Building with JMAP
  63. To build with JMAP support, prepend the environment variable `MELI_FEATURES='jmap'` to your make invocation:
  64. ```sh
  65. MELI_FEATURES="jmap" make
  66. ```
  67. or if building directly with cargo, use the flag `--features="jmap"'.
  68. # Development
  69. Development builds can be built and/or run with
  70. ```
  71. cargo build
  72. cargo run
  73. ```
  74. There is a debug/tracing log feature that can be enabled by using the flag
  75. `--feature debug-tracing` after uncommenting the features in `Cargo.toml`. The logs
  76. are printed in stderr, thus you can run meli with a redirection (i.e `2> log`)
  77. Code style follows the default rustfmt profile.
  78. # Configuration
  79. meli by default looks for a configuration file in this location: `$XDG_CONFIG_HOME/meli/config.toml`
  80. You can run meli with arbitrary configuration files by setting the `$MELI_CONFIG`
  81. environment variable to their locations, ie:
  82. ```sh
  83. MELI_CONFIG=./test_config cargo run
  84. ```
  85. # Testing
  86. How to run specific tests:
  87. ```sh
  88. cargo test -p {melib, meli} (-- --nocapture) (--test test_name)
  89. ```
  90. # Profiling
  91. ```sh
  92. perf record -g target/debug/bin
  93. perf script | stackcollapse-perf | rust-unmangle | flamegraph > perf.svg
  94. ```
  95. # Running fuzz targets
  96. Note: `cargo-fuzz` requires the nightly toolchain.
  97. ```sh
  98. cargo +nightly fuzz run envelope_parse -- -dict=fuzz/envelope_tokens.dict
  99. ```