about summary refs log tree commit diff
path: root/overrides/buildGo/README.md
diff options
context:
space:
mode:
authorVincent Ambo <tazjin@google.com>2019-12-20T20·18+0000
committerVincent Ambo <tazjin@google.com>2019-12-20T20·18+0000
commit03bfe08e1dd9faf48b06cb146bfa446575cde88a (patch)
tree55317968922a9b2a01516f1b79527874df037517 /overrides/buildGo/README.md
parente52eed3cd4f73779c2e7c350537fb346835ba9f3 (diff)
chore: Significantly restructure folder layout r/237
This moves the various projects from "type-based" folders (such as
"services" or "tools") into more appropriate semantic folders (such as
"nix", "ops" or "web").

Deprecated projects (nixcon-demo & gotest) which only existed for
testing/demonstration purposes have been removed.

(Note: *all* builds are broken with this commit)
Diffstat (limited to 'overrides/buildGo/README.md')
-rw-r--r--overrides/buildGo/README.md140
1 files changed, 0 insertions, 140 deletions
diff --git a/overrides/buildGo/README.md b/overrides/buildGo/README.md
deleted file mode 100644
index e84ede663bf8..000000000000
--- a/overrides/buildGo/README.md
+++ /dev/null
@@ -1,140 +0,0 @@
-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 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`](./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