Skip to content

ekala-project/ekapkgs / .agents/skills/go

Package a Go module for ekapkgs. Use when writing or editing a buildGoModule derivation — covers vendorHash, ldflags, subPackages, tags, env.CGO_ENABLED, proxyVendor, shell completions, and pinning a Go version.

FileKindSize
SKILL.mdskill md5.1 KB
---
name: go
description: Package a Go module for ekapkgs. Use when writing or editing a buildGoModule derivation — covers vendorHash, ldflags, subPackages, tags, env.CGO_ENABLED, proxyVendor, shell completions, and pinning a Go version.
---

# Go Packages

## Minimal Example

```nix
{
  lib,
  buildGoModule,
  fetchFromGitHub,
}:

buildGoModule (finalAttrs: {
  pname = "example";
  version = "1.0.0";

  src = fetchFromGitHub {
    owner = "example";
    repo = "example";
    tag = "v${finalAttrs.version}";
    hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
  };

  vendorHash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";

  meta = {
    description = "Example Go tool";
    license = lib.licenses.mit;
    mainProgram = "example";
  };
})
```

## Essential Requirements

**Always use `buildGoModule`** (aliased from `go.buildModule`). It handles vendor fetching, build phases, and automatic `passthru.tests.build`.

## Pinning a Go Version

When upstream requires a specific Go release, use the versioned builder:

```nix
{ go, ... }:

go.v1_26.buildModule (finalAttrs: {
  # ...
})
```

Available as `go.v1_XX.buildModule` for each Go version in corepkgs. Only pin when necessary (e.g., upstream uses APIs removed in a newer Go).

## Common Patterns

### Vendor Hash

- `vendorHash` — SRI hash of vendored Go modules. Set to `lib.fakeHash` to get the correct value from the build error.
- `vendorHash = null` — when the source tree already contains a `vendor/` directory.

### Proxy Vendor

Use `proxyVendor = true` when the vendor hash differs between Linux and Darwin (common with C dependencies in vendored modules):

```nix
proxyVendor = true;  # hash mismatch between Linux and Darwin
vendorHash = "sha256-...";
```

### ldflags

Linker flags, commonly used for stripping debug info and injecting version strings:

```nix
ldflags = [
  "-s" "-w"
  "-X main.Version=v${finalAttrs.version}"
];
```

Multiple `-X` flags for complex version info:

```nix
ldflags = [
  "-s" "-w"
  "-X github.com/org/repo/pkg.Version=v${finalAttrs.version}"
  "-X github.com/org/repo/pkg.Commit=unknown"
];
```

Dynamic ldflags via `preBuild`:

```nix
ldflags = [ "-s" "-w" "-X main.Version=v${finalAttrs.version}" ];

preBuild = ''
  ldflags+=" -X main.Date=$(cat SOURCE_DATE_EPOCH)"
'';
```

The framework automatically appends `-buildid=` to ldflags.

### CGO

CGO is controlled via `env.CGO_ENABLED`. It defaults to the Go toolchain's value.

```nix
# Disable CGO (pure Go, no C dependencies)
env.CGO_ENABLED = 0;

# Enable CGO (links C libraries)
env.CGO_ENABLED = 1;
```

Platform-conditional CGO:

```nix
env.CGO_ENABLED = if stdenv.hostPlatform.isDarwin then 1 else 0;
```

### subPackages

Limit which packages get built (defaults to scanning all):

```nix
subPackages = [ "cmd/mytool" ];
```

Common patterns:

```nix
subPackages = [ "." ];                    # Root package only
subPackages = [ "cmd/foo" "cmd/bar" ];    # Multiple binaries
subPackages = [ "cmd/*" ];                # Glob
```

### tags

Build tags for conditional compilation:

```nix
tags = [ "release" ];
```

Platform-conditional tags:

```nix
tags = lib.optionals (fuse3 != null) [ "fuse3" ]
  ++ lib.optionals enableCmount [ "cmount" ];
```

### checkFlags

Flags for `go test`. Use `-skip` to disable specific tests:

```nix
checkFlags = [ "-skip" "TestNetwork" ];
```

### env

Additional environment variables via the `env` attrset (exported under structured attrs):

```nix
env = {
  CGO_ENABLED = 0;
  GOFLAGS = [ "-trimpath" ];
};
```

## Auto-Generated Tests

`buildGoModule` automatically provides `passthru.tests.build` — a variant that re-runs with `doCheck = true`. User-supplied `passthru.tests` entries merge alongside it.

## Version Check

```nix
nativeInstallCheckInputs = [ versionCheckHook ];
versionCheckProgramArg = "--version";
doInstallCheck = true;
```

## Shell Completions

```nix
nativeBuildInputs = [ installShellFiles ];

postInstall = lib.optionalString (stdenv.buildPlatform.canExecute stdenv.hostPlatform) ''
  installShellCompletion --cmd example \
    --bash <($out/bin/example completion bash) \
    --fish <($out/bin/example completion fish) \
    --zsh  <($out/bin/example completion zsh)
'';
```

The `canExecute` guard is needed for cross-compilation — the built binary may not be runnable on the build platform.

## Complete Example

```nix
{
  lib,
  stdenv,
  buildGoModule,
  fetchFromGitHub,
  installShellFiles,
  versionCheckHook,
}:

buildGoModule (finalAttrs: {
  pname = "age";
  version = "1.3.1";

  src = fetchFromGitHub {
    owner = "FiloSottile";
    repo = "age";
    tag = "v${finalAttrs.version}";
    hash = "sha256-...";
  };

  vendorHash = "sha256-...";

  ldflags = [
    "-s" "-w"
    "-X main.Version=v${finalAttrs.version}"
  ];

  nativeBuildInputs = [ installShellFiles ];

  preInstall = ''
    installManPage doc/*.1
  '';

  nativeInstallCheckInputs = [ versionCheckHook ];
  versionCheckProgramArg = "--version";
  doInstallCheck = true;

  checkFlags = [ "-skip" "TestScript/plugin" ];

  meta = {
    description = "Modern encryption tool with small explicit keys";
    homepage = "https://age-encryption.org/";
    license = lib.licenses.bsd3;
    mainProgram = "age";
  };
})
```
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall