Add flake.nix with development environment & CI

This makes it easy to onboard new contributors, as flake.nix provides
the fully configured development environment, package definition, and
continuous integration:

- development environment: nix develop
- package build: nix build
- package install: nix profile install
- testing: nix flake check

Author: bryango

.github/workflows/nix-build.yml

@@ -0,0 +1,25 @@
+name: "Nix: build and check"
+on:
+  pull_request:
+  push:
+    paths-ignore:
+      - '**.md'
+jobs:
+  nix:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    env:
+      GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
+    steps:
+    - uses: actions/checkout@v4
+    - uses: cachix/install-nix-action@v25
+      with:
+        nix_path: nixpkgs=channel:nixpkgs-unstable
+        install_url: https://releases.nixos.org/nix/nix-2.18.1/install
+        extra_nix_config: |
+          experimental-features = nix-command flakes
+          access-tokens = github.com=${{ secrets.GITHUB_TOKEN }}
+    - uses: DeterminateSystems/magic-nix-cache-action@v2
+    - run: nix flake check --print-build-logs --show-trace

.gitignore

@@ -5,3 +5,6 @@
 /tests/00*00-latex-*.fmt
 /tests/*-plain-*.fmt
 /tests/xenia/paper.pdf
+
+.direnv
+.envrc

docs/src/howto/build-tectonic/index.md

@@ -14,6 +14,12 @@ binary will save you time and, possibly, headaches.
 
 [install]: ../installation/index.md
 
+If you use the [Nix] package manager, we provide a community maintained
+`flake.nix` with the package definition and a fully configured development
+environment. Please refer to the [Using Nix](#using-nix) section for more
+instructions.
+
+[Nix]: https://nixos.org/
 
 ## Basic Prerequisites
 
@@ -173,3 +179,23 @@ environment variables are set up properly. Read [The Cargo Book][cargo-book] for
 vastly more information about where you can go from there.
 
 [cargo-book]: https://doc.rust-lang.org/cargo/index.html
+
+## Using Nix
+
+If you have a working Nix installation [configured] with the experimental
+features `flakes` and `nix-command`, you can easily pull in the necessary
+dependencies with the following commands at the project root:
+
+- `nix develop` to enter a sub-shell with the development environments
+- `nix build` for a reproducible build of the tectonic package
+- `nix profile install` to install the package in your local nix profile
+
+The package definition is inherited from the community maintained repository
+[nixpkgs], with local overrides defined in `flake.nix` at the root of
+Tectonic's source repo. The nixpkgs definition also takes care of some
+packaging related issues, such as bundling with the correct version of `biber`
+to avoid [incompatibilities][biber-mismatch].
+
+[configured]: https://nixos.org/manual/nix/stable/command-ref/conf-file#conf-experimental-features
+[nixpkgs]: https://github.com/NixOS/nixpkgs
+[biber-mismatch]: https://github.com/tectonic-typesetting/tectonic/issues/893

flake.lock

@@ -0,0 +1,94 @@
+{
+  description = "Tectonic, a modernized TeX/LaTeX engine";
+
+  outputs = { self, nixpkgs }:
+    let
+      inherit (nixpkgs) lib;
+      supportedSystems = [
+        "aarch64-linux"
+        "aarch64-darwin"
+        "i686-linux"
+        "x86_64-darwin"
+        "x86_64-linux"
+      ];
+      foreachSystem = f: lib.genAttrs supportedSystems (system: f {
+        pkgs = nixpkgs.legacyPackages.${system};
+        /** final packages set (of a given system) provided in this flake */
+        final = self.packages.${system};
+      });
+      addCargoFeatures = x: lib.unique (x ++ [
+        /** currently nix flake does not work well with git submodules, so we
+            ensure that the nixpkgs provided harfbuzz is used instead. */
+        "external-harfbuzz"
+      ]);
+    in
+    {
+      packages = foreachSystem ({ pkgs, final }: {
+
+        /** package definition from nixpkgs, with local overrides */
+        tectonic-unwrapped = pkgs.tectonic-unwrapped.overrideAttrs (
+          { meta, cargoBuildFeatures, cargoCheckFeatures, ... }: {
+            name = "tectonic";
+            src = ./.;
+            cargoDeps = pkgs.rustPlatform.importCargoLock {
+              lockFile = ./Cargo.lock;
+            };
+            cargoBuildFeatures = addCargoFeatures cargoBuildFeatures;
+            cargoCheckFeatures = addCargoFeatures cargoCheckFeatures;
+
+            /*
+              For `flake.nix` contributors: put additional overrides here.
+              If the changes are also applicable to the `tectonic` package
+              in nixpkgs, consider first improving the definition there,
+              and then update the `flake.lock` here.
+            */
+
+            meta = {
+              # to correctly generate meta.position for back trace:
+              inherit (meta) description;
+
+              # maintainers for the local overrides:
+              maintainers = with lib.maintainers; [ bryango ];
+            };
+          }
+        );
+
+        /** a version of biber that works with the current tectonic bundle */
+        inherit (pkgs) biber-for-tectonic;
+
+        /** tectonic wrapped with the correct version of biber; this provides
+            a partial fix for issue #893. */
+        tectonic = pkgs.tectonic.override {
+          inherit (final)
+            tectonic-unwrapped
+            biber-for-tectonic;
+        };
+
+        /** the default package to build & install */
+        default = final.tectonic;
+      });
+
+      devShells = foreachSystem ({ pkgs, final }: {
+        default = final.tectonic-unwrapped.overrideAttrs (prev: {
+          # for developments, e.g. symbol lookup in std library
+          env.RUST_SRC_PATH = "${pkgs.rustPlatform.rustLibSrc}";
+        });
+      });
+
+      checks = foreachSystem ({ pkgs, final }:
+        let
+          tectonic-unwrapped =
+            final.tectonic-unwrapped.overrideAttrs (prevAttrs: {
+              preCheck = prevAttrs.preCheck or "" + ''
+                export RUST_BACKTRACE=1
+              '';
+            });
+        in
+        {
+          inherit tectonic-unwrapped;
+          tectonic = final.tectonic.override {
+            inherit tectonic-unwrapped;
+          };
+        });
+    };
+}