doc/languages-frameworks/hare.section.md

   1 # Hare {#sec-language-hare}
   2
   3 ## Building Hare programs with `hareHook` {#ssec-language-hare}
   4
   5 The `hareHook` package sets up the environment for building Hare programs by
   6 doing the following:
   7
   8 1. Setting the `HARECACHE`, `HAREPATH` and `NIX_HAREFLAGS` environment variables;
   9 1. Propagating `harec`, `qbe` and two wrapper scripts  for the hare binary.
  10
  11 It is not a function as is the case for some other languages --- *e. g.*, Go or
  12 Rust ---, but a package to be added to `nativeBuildInputs`.
  13
  14 ## Attributes of `hareHook` {#hareHook-attributes}
  15
  16 The following attributes are accepted by `hareHook`:
  17
  18 1. `hareBuildType`: Either `release` (default) or `debug`. It controls if the
  19    `-R` flag is added to `NIX_HAREFLAGS`.
  20
  21 ## Example for `hareHook` {#ex-hareHook}
  22
  23 ```nix
  24 {
  25   hareHook,
  26   lib,
  27   stdenv,
  28 }: stdenv.mkDerivation {
  29   pname = "<name>";
  30   version = "<version>";
  31   src = "<src>";
  32
  33   nativeBuildInputs = [ hareHook ];
  34
  35   meta = {
  36     description = "<description>";
  37     inherit (hareHook) badPlatforms platforms;
  38   };
  39 }
  40 ```
  41
  42 ## Cross Compilation {#hareHook-cross-compilation}
  43
  44 `hareHook` should handle cross compilation out of the box. This is the main
  45 purpose of `NIX_HAREFLAGS`: In it, the `-a` flag is passed with the architecture
  46 of the `hostPlatform`.
  47
  48 However, manual intervention may be needed when a binary compiled by the build
  49 process must be run for the build to complete --- *e. g.*, when using Hare's
  50 `hare` module for code generation.
  51
  52 In those cases, `hareHook` provides the `hare-native` script, which is a wrapper
  53 around the hare binary for using the native (`buildPlatform`) toolchain.