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