From 6709a91894926e4de1240b2e258f1c1c8a009673 Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Wed, 1 Jul 2026 18:07:48 +0200 Subject: [PATCH 1/2] doc/manual: move language chapter out of build-helpers Packaging is a first class concern and should live as toplevel navigation entry --- doc/build-helpers.md | 1 - doc/manual.md.in | 4 ++++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/build-helpers.md b/doc/build-helpers.md index f11deafdc24d..8b38a79ceff4 100644 --- a/doc/build-helpers.md +++ b/doc/build-helpers.md @@ -25,6 +25,5 @@ build-helpers/dev-shell-tools.chapter.md build-helpers/special.md build-helpers/images.md hooks/index.md -languages-frameworks/index.md packages/index.md ``` diff --git a/doc/manual.md.in b/doc/manual.md.in index 8d75d0fe459e..dbfa6591dbc1 100644 --- a/doc/manual.md.in +++ b/doc/manual.md.in @@ -17,6 +17,10 @@ contributing.md interoperability.md ``` +```{=include=} chapters +languages-frameworks/index.md +``` + ```{=include=} appendix html:into-file=//release-notes.html release-notes/release-notes.md ``` From acfc12be479ffe69ca1a57e72cac21fac15a8bf0 Mon Sep 17 00:00:00 2001 From: Johannes Kirschbauer Date: Wed, 1 Jul 2026 18:08:07 +0200 Subject: [PATCH 2/2] doc/manual: init example packaging guide Used go as example, python and rust where not found suitable due to theory overhead and multiple competing builder choices --- doc/first-package.chapter.md | 84 +++++++++++++++++++++++++++++++ doc/languages-frameworks/index.md | 4 ++ doc/manual.md.in | 1 + doc/redirects.json | 9 ++++ 4 files changed, 98 insertions(+) create mode 100644 doc/first-package.chapter.md diff --git a/doc/first-package.chapter.md b/doc/first-package.chapter.md new file mode 100644 index 000000000000..19a8583fea79 --- /dev/null +++ b/doc/first-package.chapter.md @@ -0,0 +1,84 @@ +# Package your first application {#chap-first-package} + +Package an application with Nixpkgs by picking the build helper for its language and setting a few attributes. + +Each language ecosystem has its own build helper. +See [](#chap-language-support) for the full set. + +## Package a Go application {#first-package-go} + +`buildGoModule` builds Go programs that use Go modules. + +Write the package to `package.nix`: + +:::{.example #ex-first-package-go} + +# Package `pet` with `buildGoModule` + +```nix +# package.nix +{ + buildGoModule, + fetchFromGitHub, + lib, +}: +buildGoModule (finalAttrs: { + pname = "pet"; + version = "0.3.4"; + + src = fetchFromGitHub { + owner = "knqyf263"; + repo = "pet"; + tag = "v${finalAttrs.version}"; + hash = "sha256-Gjw1dRrgM8D3G7v6WIM2+50r4HmTXvx0Xxme2fH9TlQ="; + }; + + vendorHash = "sha256-6hCgv2/8UIRHw1kCe3nLkxF23zE/7t5RDwEjSzX3pBQ="; + + meta = { + description = "Simple command-line snippet manager, written in Go"; + homepage = "https://github.com/knqyf263/pet"; + license = lib.licenses.mit; + maintainers = with lib.maintainers; [ kalbasit ]; + }; +}) +``` + +::: + +`buildGoModule` needs `pname`, `version`, `src`, and `vendorHash`. + +Pin Nixpkgs and call the package from `default.nix`: + +```nix +# default.nix +let + nixpkgs = fetchTarball "https://github.com/NixOS/nixpkgs/archive/nixos-unstable.tar.gz"; + pkgs = import nixpkgs { }; +in +pkgs.callPackage ./package.nix { } +``` + +Build it: + +```shell +$ nix-build ./default.nix +# or equivalent +$ nix-build +``` + +Run it: + +```shell +$ ./result/bin/pet --help +pet - Simple command-line snippet manager. +``` + +`vendorHash` pins the fetched dependencies. +To find its value: + +1. Set `vendorHash` to an empty string `""`. +2. Run `nix-build`. +3. Copy the correct value from the error into `vendorHash`. + +See the [Go reference](#sec-language-go) for every attribute and advanced usage. diff --git a/doc/languages-frameworks/index.md b/doc/languages-frameworks/index.md index 6e2438ebcb6a..b49653db4461 100644 --- a/doc/languages-frameworks/index.md +++ b/doc/languages-frameworks/index.md @@ -2,6 +2,10 @@ The [standard build environment](#chap-stdenv) makes it easy to build typical Autotools-based packages with very little code. Any other kind of package can be accommodated by overriding the appropriate phases of `stdenv`. However, there are specialised functions in Nixpkgs to easily build packages for other programming languages, such as Perl or Haskell. These are described in this chapter. +::: {.tip} +New to packaging? Start with [](#chap-first-package), then return here for the ecosystem you need. +::: + Each supported language or software ecosystem has its own package set named `Packages`, which can be explored in various ways: - Search on [search.nixos.org](https://search.nixos.org/packages) diff --git a/doc/manual.md.in b/doc/manual.md.in index dbfa6591dbc1..4bb047ef621e 100644 --- a/doc/manual.md.in +++ b/doc/manual.md.in @@ -3,6 +3,7 @@ ```{=include=} chapters preface.chapter.md +first-package.chapter.md ``` ```{=include=} parts diff --git a/doc/redirects.json b/doc/redirects.json index cf6ab6a33842..1bbae80c166b 100644 --- a/doc/redirects.json +++ b/doc/redirects.json @@ -2,6 +2,9 @@ "chap-build-helpers-finalAttrs": [ "index.html#chap-build-helpers-finalAttrs" ], + "chap-first-package": [ + "index.html#chap-first-package" + ], "chap-release-notes": [ "release-notes.html#chap-release-notes" ], @@ -105,6 +108,9 @@ "ex-build-helpers-extendMkDerivation": [ "index.html#ex-build-helpers-extendMkDerivation" ], + "ex-first-package-go": [ + "index.html#ex-first-package-go" + ], "ex-modularServiceCompliance-nixos": [ "index.html#ex-modularServiceCompliance-nixos" ], @@ -131,6 +137,9 @@ "ex-writeShellApplication": [ "index.html#ex-writeShellApplication" ], + "first-package-go": [ + "index.html#first-package-go" + ], "friction-graphics": [ "index.html#friction-graphics" ],