proto.nix

Nix utilities for generating language-specific bindings from Google Protocol Buffers .proto files.

The intended goal is to enable Bazel-like Google Protobuf workflows with Nix.

Quick example showing how to build a Haskell Cabal and Markdown documentation package from a .proto schema:

let
  example-hs-pb = proto-nix.haskellProto {
    src = ./.;
    protos = ["example.proto"];
    cabalPackageName = "addressbook-pb";
  }

  example-api-docs = proto-nix.docProto {
    src = ./.;
    protos = ["example.proto"];
  }

Overview

src

Directory containing the implementation of PB Nix utilities (functions and flake-parts modules).

See the build.nix for available build outputs.

# Open the Nix REPL to inspect the Flake outputs
$ nix repl
# Inspects the `lib` functions
nix-repl> :lf .
nix-repl> lib.x86_64-linux.
lib.x86_64-linux.haskellProto
lib.x86_64-linux.docProto

google-pb

Directory containing the protoc generated libraries for standard Google .proto schemas.

See the build.nix for available build outputs.

# Builds the Google's descriptor.proto Haskell library
$ nix build .#descriptor-hs-pb
# Inspects the result
$ find result/
result/
result/descriptor-pb.cabal
result/src
result/src/Proto
result/src/Proto/Google
result/src/Proto/Google/Protobuf
result/src/Proto/Google/Protobuf/Descriptor.hs
result/src/Proto/Google/Protobuf/Descriptor_Fields.hs

tests

Directory containing some tests and demonstration on how to use proto-nix.

# Builds the AddressBook canonical API Haskell library
$ nix build .#address-book-hs-pb
# Inspects the result
$ find result/
result/
result/addressbook-pb.cabal
result/addressbook.proto
result/src
result/src/Proto
result/src/Proto/Addressbook_Fields.hs
result/src/Proto/Addressbook.hs

docs

Directory containing proto.nix (also auto generated) documentation.

# Builds the proto-nix book
$ nix build .#proto-nix-book
# Opens the generated documentation with Chrome
$ chromium result/index.html

Getting started

Installing Nix

This repository relies heavily on the Nix Package Manager for both development and package distribution.

To install run the following command:

sh <(curl -L https://nixos.org/nix/install) --daemon

and follow the instructions.

$ nix --version
nix (Nix) 2.8.0

NOTE: The repository should work with Nix version greater or equal to 2.8.0.

Make sure to enable Nix Flakes and IFD by editing either ~/.config/nix/nix.conf or /etc/nix/nix.conf on your machine and add the following configuration entries:

experimental-features = nix-command flakes
allow-import-from-derivation = true

Optionally, to improve build speed, it is possible to set up a binary caches maintained by IOHK and Plutonomicon by setting additional configuration entries:

substituters = https://cache.nixos.org https://iohk.cachix.org https://cache.iog.io https://public-plutonomicon.cachix.org
trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ= iohk.cachix.org-1:DpRUyj7h7V830dp/i6Nti+NEO2/nhblbov/8MW7Rqoo= public-plutonomicon.cachix.org-1:3AKJMhCLn32gri1drGuaZmFrmnue+KkKrhhubQk/CWc=

Building and development

To facilitate seamlessly moving between directories and associated Nix development shells we use direnv and nix-direnv:

To install both using nixpkgs:

nix profile install nixpkgs#direnv
nix profile install nixpkgs#nix-direnv

Your shell and editors should pick up on the .envrc files in different directories and prepare the environment accordingly. Use direnv allow to enable the direnv environment and direnv reload to reload it when necessary.

Additionally, throughout the repository one can use:

$ pre-commit run --all
cabal-fmt............................................(no files to check)Skipped
fourmolu.................................................................Passed
hlint....................................................................Passed
markdownlint.............................................................Passed
nix-linter...............................................................Passed
nixpkgs-fmt..............................................................Passed
shellcheck...........................................(no files to check)Skipped
typos....................................................................Passed

to run all the code quality tooling specified in the Pre Commit hooks config file