doc/manual: init example packaging guide (#537480)

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
 ```

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.

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 `<language or ecosystem>Packages`, which can be explored in various ways:
 
 - Search on [search.nixos.org](https://search.nixos.org/packages)

doc/manual.md.in

@@ -3,6 +3,7 @@
 
 ```{=include=} chapters
 preface.chapter.md
+first-package.chapter.md
 ```
 
 ```{=include=} parts
@@ -17,6 +18,10 @@ contributing.md
 interoperability.md
 ```
 
+```{=include=} chapters
+languages-frameworks/index.md
+```
+
 ```{=include=} appendix html:into-file=//release-notes.html
 release-notes/release-notes.md
 ```

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"
   ],