1Describes how to create a simple Rust application using Sequoia.
2
3# Build dependencies
4
5First of all, you need Rust, and a few libraries that we depend upon.
6On Debian-like systems, the required packages can be installed using
7the following command.  As of this writing, this works fine on Debian
810 (Buster).  You can use Debian 9 (Stretch), but you need to pull
9`rustc`, `cargo`, and `nettle-dev` from testing.
10
11```text
12# apt install git rustc cargo clang make pkg-config nettle-dev libssl-dev capnproto libsqlite3-dev
13```
14
15# Creating a new project
16
17If are starting from scratch, you need to create a new crate:
18
19```text
20$ cargo new --bin example
21     Created binary (application) `example` project
22$ cd example
23```
24
25Now add Sequoia to the `[dependencies]` section in `Cargo.toml`:
26
27```toml
28sequoia-openpgp = "*"
29```
30
31Note: Explicitly stating a major version for dependencies is usually
32better than just using the wildcard here (read how to [specify
33dependencies]).  Also, please check that the crate's version matches
34the version of this guide.
35
36[specify dependencies]: https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html
37
38If you want to use the bleeding edge, you can instead refer to the
39version in git:
40
41```toml
42sequoia-openpgp = { git = "https://gitlab.com/sequoia-pgp/sequoia.git" }
43```
44
45To build and run your application, do:
46
47```sh
48$ cargo run
49```
50
51On the first run, cargo will download and build Sequoia and all
52dependencies.  When finished, nothing really happens because we have
53not populated `main` yet.  Let's do that!  Open `src/main.rs` with
54your favorite editor, and enter:
55
56```
57extern crate sequoia_openpgp as openpgp;
58use std::io;
59
60fn main() {
61    let mut reader = openpgp::armor::Reader::from_bytes(
62       b"-----BEGIN PGP ARMORED FILE-----
63
64         SGVsbG8gd29ybGQhCg==
65         =XLsG
66         -----END PGP ARMORED FILE-----", None);
67
68    io::copy(&mut reader, &mut io::stdout()).unwrap();
69}
70```
71
72Running the application now prints a friendly message to stdout.
73
74A word on the `armored` macro.  We will use this macro in this guide
75to inline OpenPGP data into the source code.  Sequoia includes filters
76for ASCII armored data.  You can use these filters to read armored
77data from any `Read`er, or write armored data to any `Write`r.
78
79# Building the Sequoia tool
80
81Sequoia includes a simple frontend `sq` that can be used to experiment
82with Sequoia and OpenPGP.  The documentation for this tool is
83[here](../../sq/index.html).  It is also an example of
84how to use various aspects of Sequoia.  Clone Sequoia and build the
85tool:
86
87```sh
88$ git clone https://gitlab.com/sequoia-pgp/sequoia.git
89...
90$ cd sequoia
91$ cargo build -p sequoia-tool
92...
93$ target/debug/sq
94sq 0.1.0
95Sequoia is an implementation of OpenPGP.  This is a command-line frontend.
96...
97```
98