tvl-depot/nix/buildGo
Vincent Ambo db74ffb4b1 fix(nix/buildGo): Remove absolute references to GOROOT from binaries
Setting the GOROOT_FINAL environment variables replaces the absolute
location of the Go standard library sources in the final build
artefacts with a fake location (in this case starting with
go/src/...).

This is despite the documentation for 'trimpath' (in 'go tool
compile') stating that it would affect all source paths: That's only
true for user code!

I figured this out by reading through the implementation of the other
'trimpath' (in 'gob build'):

https://go-review.googlesource.com/c/go/+/173345
2020-03-31 01:29:35 +01:00
..
example chore: Significantly restructure folder layout 2019-12-20 20:18:41 +00:00
external chore: Significantly restructure folder layout 2019-12-20 20:18:41 +00:00
.skip-subtree chore: Significantly restructure folder layout 2019-12-20 20:18:41 +00:00
default.nix fix(nix/buildGo): Remove absolute references to GOROOT from binaries 2020-03-31 01:29:35 +01:00
proto.nix chore: Significantly restructure folder layout 2019-12-20 20:18:41 +00:00
README.md docs(nix/buildLisp): Update the README with actual docs 2020-01-29 00:03:24 +00:00

buildGo.nix

This is an alternative Nix build system for Go. It supports building Go libraries and programs, and even automatically generating Protobuf & gRPC libraries.

Note: This will probably end up being folded into Nixery.

Background

Most language-specific Nix tooling outsources the build to existing language-specific build tooling, which essentially means that Nix ends up being a wrapper around all sorts of external build systems.

However, systems like Bazel take an alternative approach in which the compiler is invoked directly and the composition of programs and libraries stays within a single homogeneous build system.

Users don't need to learn per-language build systems and especially for companies with large monorepo-setups (like Google) this has huge productivity impact.

This project is an attempt to prove that Nix can be used in a similar style to build software directly, rather than shelling out to other build systems.

Example

Given a program layout like this:

.
├── lib          <-- some library component
│   ├── bar.go
│   └── foo.go
├── api.proto    <-- gRPC API definition
├── main.go      <-- program implementation
└── default.nix  <-- build instructions

The contents of default.nix could look like this:

{ buildGo }:

let
  api = buildGo.grpc {
    name  = "someapi";
    proto = ./api.proto;
  };

  lib = buildGo.package {
    name = "somelib";
    srcs = [
      ./lib/bar.go
      ./lib/foo.go
    ];
  };
in buildGo.program {
  name = "my-program";
  deps = [ api lib ];

  srcs = [
    ./main.go
  ];
}

(If you don't know how to read Nix, check out nix-1p)

Usage

buildGo exposes five different functions:

  • buildGo.program: Build a Go binary out of the specified source files.

    parameter type use required?
    name string Name of the program (and resulting executable) yes
    srcs list<path> List of paths to source files yes
    deps list<drv> List of dependencies (i.e. other Go libraries) no
    x_defs attrs<string, string> Attribute set of linker vars (i.e. -X-flags) no
  • buildGo.package: Build a Go library out of the specified source files.

    parameter type use required?
    name string Name of the library yes
    srcs list<path> List of paths to source files yes
    deps list<drv> List of dependencies (i.e. other Go libraries) no
    path string Go import path for the resulting library no
  • buildGo.external: Build an externally defined Go library or program.

    This function performs analysis on the supplied source code (which can use the standard Go tooling layout) and creates a tree of all the packages contained within.

    This exists for compatibility with external libraries that were not defined using buildGo.

    parameter type use required?
    path string Go import path for the resulting package yes
    src path Path to the source directory yes
    deps list<drv> List of dependencies (i.e. other Go packages) no

    For some examples of how buildGo.external is used, check out proto.nix.

  • buildGo.proto: Build a Go library out of the specified Protobuf definition.

    parameter type use required?
    name string Name for the resulting library yes
    proto path Path to the Protobuf definition file yes
    path string Import path for the resulting Go library no
    extraDeps list<drv> Additional Go dependencies to add to the library no
  • buildGo.grpc: Build a Go library out of the specified gRPC definition.

    The parameters are identical to buildGo.proto.

Current status

This project is work-in-progress. Crucially it is lacking the following features:

  • feature flag parity with Bazel's Go rules
  • documentation building
  • test execution

There are still some open questions around how to structure some of those features in Nix.