Browse Source

Convert README to Markdown

tags/alpha-0.5.0
Manos Pitsidianakis 4 months ago
parent
commit
548c9f4ac3
WARNING! Although there is a key with this ID in the database it does not verify this commit! This commit is SUSPICIOUS. GPG Key ID: 73627C2F690DF710
2 changed files with 133 additions and 113 deletions
  1. +0
    -113
      README
  2. +133
    -0
      README.md

+ 0
- 113
README View File

@@ -1,113 +0,0 @@
__
__/ \__
/ \__/ \__ .
\__/ \__/ \ , _ , _ ___ β”‚ '
/ \__ \__/ β”‚' `β”‚ `β”’ .' ` β”‚ β”‚
\__/ \__/ \ β”‚ β”‚ β”‚ |────' β”‚ β”‚
\__/ \__/ β”‚ / `.___, /\__ /
\__/
,-.
\_/
terminal mail user agent {|||)<
/ \
`-'
DOCUMENTATION
=============

After installing meli, see meli(1) and meli.conf(5) for documentation.

BUILDING
========

meli requires rust 1.39 and rust's package manager, Cargo. Information on how
to get it on your system can be found here:

https://doc.rust-lang.org/cargo/getting-started/installation.html

With Cargo available, the project can be built with

# make

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

See meli(1) and meli.conf(5) for documentation.

You can build and run meli with one command:

# cargo run --release

While the project is in early development, meli will only be developed for the
linux kernel and respected linux distributions. Support for more UNIX-like OSes
is on the roadmap.

BUILDING IN DEBIAN
==================

Building with Debian's packaged cargo might require the installation of these
two packages: librust-openssl-sys-dev and librust-libdbus-sys-dev

BUILDING WITH NOTMUCH
=====================

To use the optional notmuch backend feature, you must have libnotmuch installed in your system. In Debian-like systems, install the "libnotmuch" package.

To build with notmuch support, prepend the environment variable "MELI_FEATURES='notmuch'" to your make invocation:

# MELI_FEATURES="notmuch" make

or if building directly with cargo, use the flag '--features="notmuch"'.

BUILDING WITH JMAP
=====================

To build with JMAP support, prepend the environment variable "MELI_FEATURES='jmap'" to your make invocation:

# MELI_FEATURES="jmap" make

or if building directly with cargo, use the flag '--features="jmap"'.

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, thus you can run meli with a redirection (i.e `2> log`)

Code style follows the default rustfmt profile.

CONFIG
======

meli by default looks for a configuration file in this location:
# $XDG_CONFIG_HOME/meli/config

You can run meli with arbitrary configuration files by setting the MELI_CONFIG
environment variable to their locations, ie:

# MELI_CONFIG=./test_config cargo run

TESTING
=======

How to run specific tests:

# cargo test -p {melib, ui, meli} (-- --nocapture) (--test test_name)

PROFILING
=========

# perf record -g target/debug/bin
# perf script | stackcollapse-perf | rust-unmangle | flamegraph > perf.svg

+ 133
- 0
README.md View File

@@ -0,0 +1,133 @@
# meli
For a quick start, build and install locally:

```sh
PREFIX=~/.local make install
```

Available subcommands:
- meli (builds meli with optimizations in `$CARGO_TARGET_DIR`)
- install (installs binary in `$BINDIR` and documentation to `$MANDIR`)
- uninstall
Secondary subcommands:
- clean (cleans build artifacts)
- check-deps (checks dependencies)
- install-bin (installs binary to `$BINDIR`)
- install-doc (installs manpages to `$MANDIR`)
- help (prints this information)
- dist (creates release tarball named `meli-VERSION.tar.gz` in this directory)
- deb-dist (builds debian package in the parent directory)
- distclean (cleans distribution build artifacts)

The Makefile *should* be portable and not require a specific `make` version.

# Documentation

After installing meli, see `meli(1)` and `meli.conf(5)` for documentation.

# Building

meli requires rust 1.39 and rust's package manager, Cargo. Information on how
to get it on your system can be found here: <https://doc.rust-lang.org/cargo/getting-started/installation.html>

With Cargo available, the project can be built with

```sh
make meli
```

The resulting binary will then be found under `target/release/meli`

Run:

```sh
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`:

```sh
make PREFIX=$HOME/.local install
```

See `meli(1)` and `meli.conf(5)` for documentation.

You can build and run meli with one command:

```sh
cargo run --release
```

While the project is in early development, meli will only be developed for the
linux kernel and respected linux distributions. Support for more UNIX-like OSes
is on the roadmap.

# Building in Debian

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`

# Building with notmuch

To use the optional notmuch backend feature, you must have `libnotmuch` installed in your system. In Debian-like systems, install the `libnotmuch5 libnotmuch-dev` packages.

To build with notmuch support, prepend the environment variable `MELI_FEATURES='notmuch'` to your make invocation:

```sh
MELI_FEATURES="notmuch" make
```

or if building directly with cargo, use the flag `--features="notmuch"'.

# Building with JMAP

To build with JMAP support, prepend the environment variable `MELI_FEATURES='jmap'` to your make invocation:

```sh
MELI_FEATURES="jmap" make
```

or if building directly with cargo, use the flag `--features="jmap"'.

# 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, thus you can run meli with a redirection (i.e `2> log`)

Code style follows the default rustfmt profile.

# Configuration

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, ie:

```sh
MELI_CONFIG=./test_config cargo run
```

# Testing

How to run specific tests:

```sh
cargo test -p {melib, meli} (-- --nocapture) (--test test_name)
```

# Profiling

```sh
perf record -g target/debug/bin
perf script | stackcollapse-perf | rust-unmangle | flamegraph > perf.svg
```

Loading…
Cancel
Save