doc/languages-frameworks/dart.section.md

   1 # Dart {#sec-language-dart}
   2
   3 ## Dart applications {#ssec-dart-applications}
   4
   5 The function `buildDartApplication` builds Dart applications managed with pub.
   6
   7 It fetches its Dart dependencies automatically through `pub2nix`, and (through a series of hooks) builds and installs the executables specified in the pubspec file. The hooks can be used in other derivations, if needed. The phases can also be overridden to do something different from installing binaries.
   8
   9 If you are packaging a Flutter desktop application, use [`buildFlutterApplication`](#ssec-dart-flutter) instead.
  10
  11 `pubspecLock` is the parsed pubspec.lock file. pub2nix uses this to download required packages.
  12 This can be converted to JSON from YAML with something like `yq . pubspec.lock`, and then read by Nix.
  13
  14 Alternatively, `autoPubspecLock` can be used instead, and set to a path to a regular `pubspec.lock` file. This relies on import-from-derivation, and is not permitted in Nixpkgs, but can be useful at other times.
  15
  16 ::: {.warning}
  17 When using `autoPubspecLock` with a local source directory, make sure to use a
  18 concatenation operator (e.g. `autoPubspecLock = src + "/pubspec.lock";`), and
  19 not string interpolation.
  20
  21 String interpolation will copy your entire source directory to the Nix store and
  22 use its store path, meaning that unrelated changes to your source tree will
  23 cause the generated `pubspec.lock` derivation to rebuild!
  24 :::
  25
  26 If the package has Git package dependencies, the hashes must be provided in the `gitHashes` set. If a hash is missing, an error message prompting you to add it will be shown.
  27
  28 The `dart` commands run can be overridden through `pubGetScript` and `dartCompileCommand`, you can also add flags using `dartCompileFlags` or `dartJitFlags`.
  29
  30 Dart supports multiple [outputs types](https://dart.dev/tools/dart-compile#types-of-output), you can choose between them using `dartOutputType` (defaults to `exe`). If you want to override the binaries path or the source path they come from, you can use `dartEntryPoints`. Outputs that require a runtime will automatically be wrapped with the relevant runtime (`dartaotruntime` for `aot-snapshot`, `dart run` for `jit-snapshot` and `kernel`, `node` for `js`), this can be overridden through `dartRuntimeCommand`.
  31
  32 ```nix
  33 { lib, buildDartApplication, fetchFromGitHub }:
  34
  35 buildDartApplication rec {
  36   pname = "dart-sass";
  37   version = "1.62.1";
  38
  39   src = fetchFromGitHub {
  40     owner = "sass";
  41     repo = pname;
  42     rev = version;
  43     hash = "sha256-U6enz8yJcc4Wf8m54eYIAnVg/jsGi247Wy8lp1r1wg4=";
  44   };
  45
  46   pubspecLock = lib.importJSON ./pubspec.lock.json;
  47 }
  48 ```
  49
  50 ### Patching dependencies {#ssec-dart-applications-patching-dependencies}
  51
  52 Some Dart packages require patches or build environment changes. Package derivations can be customised with the `customSourceBuilders` argument.
  53
  54 A collection of such customisations can be found in Nixpkgs, in the `development/compilers/dart/package-source-builders` directory.
  55
  56 This allows fixes for packages to be shared between all applications that use them. It is strongly recommended to add to this collection instead of including fixes in your application derivation itself.
  57
  58 ### Running executables from dev_dependencies {#ssec-dart-applications-build-tools}
  59
  60 Many Dart applications require executables from the `dev_dependencies` section in `pubspec.yaml` to be run before building them.
  61
  62 This can be done in `preBuild`, in one of two ways:
  63
  64 1. Packaging the tool with `buildDartApplication`, adding it to Nixpkgs, and running it like any other application
  65 2. Running the tool from the package cache
  66
  67 Of these methods, the first is recommended when using a tool that does not need
  68 to be of a specific version.
  69
  70 For the second method, the `packageRun` function from the `dartConfigHook` can be used.
  71 This is an alternative to `dart run` that does not rely on Pub.
  72
  73 e.g., for `build_runner`:
  74
  75 ```bash
  76 packageRun build_runner build
  77 ```
  78
  79 Do _not_ use `dart run <package_name>`, as this will attempt to download dependencies with Pub.
  80
  81 ### Usage with nix-shell {#ssec-dart-applications-nix-shell}
  82
  83 #### Using dependencies from the Nix store {#ssec-dart-applications-nix-shell-deps}
  84
  85 As `buildDartApplication` provides dependencies instead of `pub get`, Dart needs to be explicitly told where to find them.
  86
  87 Run the following commands in the source directory to configure Dart appropriately.
  88 Do not use `pub` after doing so; it will download the dependencies itself and overwrite these changes.
  89
  90 ```bash
  91 cp --no-preserve=all "$pubspecLockFilePath" pubspec.lock
  92 mkdir -p .dart_tool && cp --no-preserve=all "$packageConfig" .dart_tool/package_config.json
  93 ```
  94
  95 ## Flutter applications {#ssec-dart-flutter}
  96
  97 The function `buildFlutterApplication` builds Flutter applications.
  98
  99 See the [Dart documentation](#ssec-dart-applications) for more details on required files and arguments.
 100
 101 `flutter` in Nixpkgs always points to `flutterPackages.stable`, which is the latest packaged version. To avoid unforeseen breakage during upgrade, packages in Nixpkgs should use a specific flutter version, such as `flutter319` and `flutter322`, instead of using `flutter` directly.
 102
 103 ```nix
 104 {  flutter322, fetchFromGitHub }:
 105
 106 flutter322.buildFlutterApplication {
 107   pname = "firmware-updater";
 108   version = "0-unstable-2023-04-30";
 109
 110   # To build for the Web, use the targetFlutterPlatform argument.
 111   # targetFlutterPlatform = "web";
 112
 113   src = fetchFromGitHub {
 114     owner = "canonical";
 115     repo = "firmware-updater";
 116     rev = "6e7dbdb64e344633ea62874b54ff3990bd3b8440";
 117     hash = "sha256-s5mwtr5MSPqLMN+k851+pFIFFPa0N1hqz97ys050tFA=";
 118     fetchSubmodules = true;
 119   };
 120
 121   pubspecLock = lib.importJSON ./pubspec.lock.json;
 122 }
 123 ```
 124
 125 ### Usage with nix-shell {#ssec-dart-flutter-nix-shell}
 126
 127 Flutter-specific `nix-shell` usage notes are included here. See the [Dart documentation](#ssec-dart-applications-nix-shell) for general `nix-shell` instructions.
 128
 129 #### Entering the shell {#ssec-dart-flutter-nix-shell-enter}
 130
 131 By default, dependencies for only the `targetFlutterPlatform` are available in the
 132 build environment. This is useful for keeping closures small, but be problematic
 133 during development. It's common, for example, to build Web apps for Linux during
 134 development to take advantage of native features such as stateful hot reload.
 135
 136 To enter a shell with all the usual target platforms available, use the `multiShell` attribute.
 137
 138 e.g. `nix-shell '<nixpkgs>' -A fluffychat-web.multiShell`.