From cc5400bc8e474f5241fca7f97ce11c8322db4b9d Mon Sep 17 00:00:00 2001
From: oxalica <oxalicc@pm.me>
Date: Sat, 2 Jan 2021 02:38:48 +0800
Subject: [PATCH] Add README and license

---
 LICENSE   | 17 +++++++++++
 README.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 108 insertions(+)
 create mode 100644 LICENSE
 create mode 100644 README.md

diff --git a/LICENSE b/LICENSE
new file mode 100644
index 00000000000..f85e365de02
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,17 @@
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
new file mode 100644
index 00000000000..99dfd0e438f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,91 @@
+# rust-overlay
+
+*Pure and reproducible* overlay for binary distributed rust toolchains.
+A better replacement for github:mozilla/nixpkgs-mozilla
+
+Hashes of toolchain components are pre-fetched (and compressed) in `manifests` directory.
+So there's no need to have network access during nix evaluation (but nixpkgs-mozilla does).
+
+Since the evaluation is now *pure*, it also means this can work well with [Nix Flakes](https://nixos.wiki/wiki/Flakes).
+
+- [ ] Auto-updating is TODO.
+- Current oldest supported version is stable 1.29.0 and nightly 2018-09-13
+  (which is randomly chosen).
+
+## Use as classical nix overlay
+
+The installaction and usage are exactly the same as nixpkgs-mozilla.
+You can follow https://github.com/mozilla/nixpkgs-mozilla#rust-overlay and just replace the url to
+https://github.com/oxalica/rust-overlay
+
+You can put the code below into your `~/.config/nixpkgs/overlays.nix`.
+```nix
+[ (import (builtins.fetchTarball https://github.com/oxalica/rust-overlay/archive/master.tar.gz)) ]
+```
+
+Or install it into `nix-channel`:
+```shell
+$ nix-channel --add https://github.com/oxalica/rust-overlay/archive/master.tar.gz rust-overlay
+```
+And then feel free to use it anywhere like
+`import <nixpkgs> { overlays = [ (import <rust-overlay>) ] }` in your nix shell environment
+
+## Use with Nix Flakes
+
+This repository already has flake support. So you can simply use it as input.
+Here's an example of using it in nixos configuration.
+
+```nix
+{
+  description = "My configuration";
+
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
+    rust-overlay.url = "github:oxalica/rust-overlay";
+  };
+
+  outputs = { nixpkgs, rust-overlay, ... }: {
+    nixosConfigurations = {
+      hostname = nixpkgs.lib.nixosSystem {
+        system = "x86_64-linux";
+        modules = [
+          ./configuration.nix # Your system configuration.
+          ({ pkgs, ... }: {
+            nixpkgs.overlays = [ rust-overlay.overlay ];
+            environment.systemPackages = [ pkgs.latest.rustChannels.stable.rust ];
+          })
+        ];
+      };
+    };
+  };
+}
+```
+
+## Interface
+
+The overlay re-use many codes from nixpkgs/mozilla and the interface is **almost the same**.
+It provides `latest.rustChannels.{stable,nightly}.<toolchain-component>` and `rustChannelOf`.
+
+To use the latest stable or nightly rust toolchain, the easiest way is just to install
+`latest.rustChannels.{stable,nightly}.rust`, which combines `rustc`, `cargo`, `rustfmt` and
+all other default components.
+
+You can also pin to specific nightly toolchain using `rustChannelOf`:
+```nix
+(nixpkgs.rustChannelOf { date = "2020-01-01"; channel = "nightly"; }).rust
+```
+
+Customize an toolchain.
+```nix
+nixpkgs.latest.rustChannels.stable.rust.override {
+  extensions = [
+    "rust-src"
+  ];
+  targets = [
+    "x86_64-unknown-linux-musl"
+    "arm-unknown-linux-gnueabihf"
+  ];
+}
+```
+
+For more details, see `./rust-overlay.nix` or README of https://github.com/mozilla/nixpkgs-mozilla.