From cfa58200cd9958eea5221bf5dfcf82778a0e0220 Mon Sep 17 00:00:00 2001
From: Coutinho de Souza <dev@onemoresuza.com>
Date: Sat, 25 May 2024 11:34:14 -0300
Subject: [PATCH] doc/hare: init

---
 doc/languages-frameworks/hare.section.md | 53 ++++++++++++++++++++++++
 doc/languages-frameworks/index.md        |  1 +
 2 files changed, 54 insertions(+)
 create mode 100644 doc/languages-frameworks/hare.section.md

diff --git a/doc/languages-frameworks/hare.section.md b/doc/languages-frameworks/hare.section.md
new file mode 100644
index 000000000000..0ae8abeba45c
--- /dev/null
+++ b/doc/languages-frameworks/hare.section.md
@@ -0,0 +1,53 @@
+# Hare {#sec-language-hare}
+
+## Building Hare programs with `hareHook` {#ssec-language-hare}
+
+The `hareHook` package sets up the environment for building Hare programs by
+doing the following:
+
+1. Setting the `HARECACHE`, `HAREPATH` and `NIX_HAREFLAGS` environment variables;
+1. Propagating `harec`, `qbe` and two wrapper scripts  for the hare binary.
+
+It is not a function as is the case for some other languages --- *e. g.*, Go or
+Rust ---, but a package to be added to `nativeBuildInputs`.
+
+## Attributes of `hareHook` {#hareHook-attributes}
+
+The following attributes are accepted by `hareHook`:
+
+1. `hareBuildType`: Either `release` (default) or `debug`. It controls if the
+   `-R` flag is added to `NIX_HAREFLAGS`.
+
+## Example for `hareHook` {#ex-hareHook}
+
+```nix
+{
+  hareHook,
+  lib,
+  stdenv,
+}: stdenv.mkDerivation {
+  pname = "<name>";
+  version = "<version>";
+  src = "<src>";
+
+  nativeBuildInputs = [ hareHook ];
+
+  meta = {
+    description = "<description>";
+    inherit (hareHook) badPlatforms platforms;
+  };
+}
+```
+
+## Cross Compilation {#hareHook-cross-compilation}
+
+`hareHook` should handle cross compilation out of the box. This is the main
+purpose of `NIX_HAREFLAGS`: In it, the `-a` flag is passed with the architecture
+of the `hostPlatform`.
+
+However, manual intervention may be needed when a binary compiled by the build
+process must be run for the build to complete --- *e. g.*, when using Hare's
+`hare` module for code generation.
+
+In those cases, `hareHook` provides the `hare-native` script, which is a wrapper
+around the hare binary for using the native (`buildPlatform`) toolchain.
diff --git a/doc/languages-frameworks/index.md b/doc/languages-frameworks/index.md
index 920e5e7bd431..e8fee9c45216 100644
--- a/doc/languages-frameworks/index.md
+++ b/doc/languages-frameworks/index.md
@@ -19,6 +19,7 @@ dotnet.section.md
 emscripten.section.md
 gnome.section.md
 go.section.md
+hare.section.md
 haskell.section.md
 hy.section.md
 idris.section.md