diff options
author | Justus Winter <justus@sequoia-pgp.org> | 2018-10-18 16:40:56 +0200 |
---|---|---|
committer | Justus Winter <justus@sequoia-pgp.org> | 2018-12-07 11:44:25 +0100 |
commit | 22fe5f5fa08b7d98a05a9394320d7984083cd62f (patch) | |
tree | 766c91458bee19a064f7b0b0740a99eae97a5b20 /guide/src/chapter_00.md | |
parent | 614b24bf61e91525d7e22203405f097e065cbb3e (diff) |
guide: New crate.
- Our previous guide published on our web site quickly bitrotted
away. This guide, however, is tested as part of Sequoia's test
suite, making sure that it stays in sync.
Diffstat (limited to 'guide/src/chapter_00.md')
-rw-r--r-- | guide/src/chapter_00.md | 95 |
1 files changed, 95 insertions, 0 deletions
diff --git a/guide/src/chapter_00.md b/guide/src/chapter_00.md new file mode 100644 index 00000000..63eed991 --- /dev/null +++ b/guide/src/chapter_00.md @@ -0,0 +1,95 @@ +Describes how to create a simple Rust application using Sequoia. + +# Build dependencies + +First of all, you need Rust, and a few libraries that we depend upon. +On Debian-like systems, the required packages can be installed using +the following command. As of this writing, this works fine on Debian +10 (Buster). You can use Debian 9 (Stretch), but you need to pull +`rustc`, `cargo`, and `nettle-dev` from testing. + +```text +# apt install git rustc cargo clang make pkg-config nettle-dev libssl-dev capnproto libsqlite3-dev +``` + +# Creating a new project + +If are starting from scratch, you need to create a new crate: + +```text +$ cargo new --bin example + Created binary (application) `example` project +$ cd example +``` + +Now add Sequoia to the `[dependencies]` section in `Cargo.toml`: + +```toml +sequoia-openpgp = "0.2" +``` + +If you want to use the bleeding edge, you can instead refer to the +version in git: + +```toml +sequoia-openpgp = { git = "https://gitlab.com/sequoia-pgp/sequoia.git" } +``` + +To build and run your application, do: + +```sh +$ cargo run +``` + +On the first run, cargo will download and build Sequoia and all +dependencies. When finished, nothing really happens because we have +not populated `main` yet. Let's do that! Open `src/main.rs` with +your favorite editor, and enter: + +``` +#[macro_use] // For armored! +extern crate sequoia_openpgp as openpgp; +use std::io; + +fn main() { + let mut reader = armored!( + "-----BEGIN PGP ARMORED FILE----- + + SGVsbG8gd29ybGQhCg== + =XLsG + -----END PGP ARMORED FILE-----" + ); + + io::copy(&mut reader, &mut io::stdout()).unwrap(); +} +``` + +Running the application now prints a friendly message to stdout. + +A word on the `armored` macro. We will use this macro in this guide +to inline OpenPGP data into the source code. Sequoia includes filters +for ASCII armored data. You can use these filters to read armored +data from any `Read`er, or write armored data to any `Write`r. The +`armored` macro does the same for string literals. In order to use +this macro, you need to use `#[macro_use]` when importing the +`openpgp` crate. + +# Building the Sequoia tool + +Sequoia includes a simple frontend `sq` that can be used to experiment +with Sequoia and OpenPGP. The documentation for this tool is +[here](../../sq/index.html). It is also an example of +how to use various aspects of Sequoia. Clone Sequoia and build the +tool: + +```sh +$ git clone https://gitlab.com/sequoia-pgp/sequoia.git +... +$ cd sequoia +$ cargo build -p sequoia-tool +... +$ target/debug/sq +sq 0.1.0 +Sequoia is an implementation of OpenPGP. This is a command-line frontend. +... +``` |