From 4d3bb30b8bd6871ffeb575aab1d9e4593ba9e1d0 Mon Sep 17 00:00:00 2001
From: Patryk Wychowaniec <pwychowaniec@pm.me>
Date: Sun, 11 Jun 2023 19:47:46 +0200
Subject: [PATCH] Improve README

Closes https://github.com/nix-community/naersk/issues/283.
---
 README.md     | 32 ++++++++++++++++++++++++++++++++
 README.tpl.md | 32 ++++++++++++++++++++++++++++++++
 2 files changed, 64 insertions(+)

diff --git a/README.md b/README.md
index 7a4bc54..12bbcf2 100644
--- a/README.md
+++ b/README.md
@@ -4,11 +4,43 @@
 
 Build Rust projects with ease!
 
+* [Introduction](#introduction)
 * [Setup](#setup)
 * [Usage](#usage)
 * [Examples](#examples)
 * [Tips & Tricks](#tips--tricks)
 
+## Introduction
+
+Naersk is a [Nix](https://nixos.org/explore.html) library for building Rust
+projects - basically, you write:
+
+```
+naersk.buildPackage {
+  src = ./.; # Wherever your Cargo.lock and the rest of your source code are
+}
+```
+
+... and that turns your code into a Nix derivation which you can, for instance,
+include in your system:
+
+```
+environment.systemPackages = [
+  (naersk.buildPackage {
+    src = ./my-cool-app;
+  })
+];
+
+# (see below for more complete examples)
+```
+
+Under the hood, `buildPackage` parses `Cargo.lock`, downloads all dependencies,
+and compiles your application, fully utilizing Nix's sandboxing and caching
+abilities; so, with a pinch of salt, Naersk is `cargo build`, but inside Nix!
+
+If you're using Hydra, you can rely on Naersk as well because it doesn't use
+IFD - all the parsing happens directly inside Nix code.
+
 ## Setup
 
 ### Using Flakes
diff --git a/README.tpl.md b/README.tpl.md
index aa50249..d132e1b 100644
--- a/README.tpl.md
+++ b/README.tpl.md
@@ -4,11 +4,43 @@
 
 Build Rust projects with ease!
 
+* [Introduction](#introduction)
 * [Setup](#setup)
 * [Usage](#usage)
 * [Examples](#examples)
 * [Tips & Tricks](#tips--tricks)
 
+## Introduction
+
+Naersk is a [Nix](https://nixos.org/explore.html) library for building Rust
+projects - basically, you write:
+
+```
+naersk.buildPackage {
+  src = ./.; # Wherever your Cargo.lock and the rest of your source code are
+}
+```
+
+... and that turns your code into a Nix derivation which you can, for instance,
+include in your system:
+
+```
+environment.systemPackages = [
+  (naersk.buildPackage {
+    src = ./my-cool-app;
+  })
+];
+
+# (see below for more complete examples)
+```
+
+Under the hood, `buildPackage` parses `Cargo.lock`, downloads all dependencies,
+and compiles your application, fully utilizing Nix's sandboxing and caching
+abilities; so, with a pinch of salt, Naersk is `cargo build`, but inside Nix!
+
+If you're using Hydra, you can rely on Naersk as well because it doesn't use
+IFD - all the parsing happens directly inside Nix code.
+
 ## Setup
 
 ### Using Flakes