docs: Add README file that describes project usage & background
This commit is contained in:
parent
9280cf9715
commit
28e587b348
1 changed files with 139 additions and 0 deletions
139
README.md
Normal file
139
README.md
Normal file
|
@ -0,0 +1,139 @@
|
||||||
|
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:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
{ 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 (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 |
|
||||||
|
| `path` | `string` | Go import path for the resulting library | no |
|
||||||
|
|
||||||
|
* `buildGo.external`: Build a Go library or program using standard `go` tooling.
|
||||||
|
|
||||||
|
This exists for compatibility with complex external dependencies. In theory it
|
||||||
|
is possible to write `buildGo.package` specifications for each subpackage of
|
||||||
|
an external dependency, but it is often cumbersome to do so.
|
||||||
|
|
||||||
|
| parameter | type | use | required? |
|
||||||
|
|-----------|----------------|------------------------------------------------|-----------|
|
||||||
|
| `path` | `string` | Go import path for the resulting library | yes |
|
||||||
|
| `src` | `path` | Path to the source **directory** | yes |
|
||||||
|
| `deps` | `list<drv>` | List of dependencies (i.e. other Go libraries) | no |
|
||||||
|
| `srcOnly` | `bool` | Only copy sources, do not perform a build. | no |
|
||||||
|
| `targets` | `list<string>` | Sub-packages to build (defaults to all) | no |
|
||||||
|
|
||||||
|
For some examples of how `buildGo.external` is used, check out
|
||||||
|
[`proto.nix`](./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.
|
||||||
|
|
||||||
|
[Nix]: https://nixos.org/nix/
|
||||||
|
[Go]: https://golang.org/
|
||||||
|
[Nixery]: https://github.com/google/nixery
|
||||||
|
[Bazel]: https://bazel.build/
|
||||||
|
[like Google]: https://ai.google/research/pubs/pub45424
|
||||||
|
[nix-1p]: https://github.com/tazjin/nix-1p
|
Loading…
Reference in a new issue