docs: add initial README.md

Sponsored-by: pep.foundation

1 files changed, 41 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9681380
--- /dev/null
+++ b/README.md
@@ -0,0 +1,41 @@
+# List dependencies that haven't been packaged
+
+Operating systems such as Debian package dependencies separately, and
+frown upon embedded copies of them. Without going into why they do
+that, it's something projects using Rust have to live with, if they
+want their software packaged for such systems.
+
+This repository contains tooling to make it easier to see what Rust
+dependencies (crates) are missing from a target operating system.
+There are three parts:
+
+* `debian-crate-packages` is a simple shell script that fetches the
+  package list for the Debian "unstable" version, and produces a list
+  of Rust crates and versions that have been packaged.
+* `rust-dependencies` is a shell script that reads the output of
+  `cargo tree` (possibly with options like `--all-features`) and
+  produces a list of crates and versions.
+* The Rust program in this crate reads the outputs of the two scripts
+  and produces a list of missing crates or versions.
+
+A crate may be entirely missing from the target system, or the target
+may have package of an older version.
+
+The list of missing crates can be used to make informed decisions
+about dependencies:
+
+* should Rust project drop the dependency, or ask the target system to
+  package it?
+* should the Rust project lower the version of the dependency or ask
+  the target system to update their package to a newer version?
+
+
+## Example
+
+```sh
+$ ./debian-crate-packages > crates-in-debian
+$ (cd /where/rust/program/is && cargo tree) | ./rust-dependencies > crates-wanted
+$ cargo run -q -- crates-in-debian crates-wanted
+missing-version aho-corasick 0.7.18
+missing-entirely ansi_term
+```